Add and document many synchronous error statuses #377
Conversation
Fixes webgpu-native#255 Fixes (again?) webgpu-native#291 Issue webgpu-native#225 Fixes webgpu-native#64
|
|
||
| Generally these will return some kind of failure status (like \ref WGPUStatus_Error), or `NULL`. | ||
|
|
||
| ### Struct-Chaining Error {#StructChainingError} |
There was a problem hiding this comment.
Why can't these piggy-back on device errors when possible? There's a lot of call that take extensible structs and that return void.
There was a problem hiding this comment.
Basically they are validation errors.
| @@ -840,6 +840,8 @@ enums: | |||
| doc: The system ran out of memory. | |||
| - name: device_lost | |||
| doc: The @ref WGPUDevice configured on the @ref WGPUSurface was lost. | |||
| - name: error | |||
| doc: The surface is not configured, or there was a @ref StructChainingError. | |||
There was a problem hiding this comment.
Maybe just point at the Surface.md article for a description of what might return an error?
| @@ -3184,8 +3190,8 @@ objects: | |||
| TODO | |||
| returns: | |||
| doc: | | |||
| TODO | |||
| type: bool | |||
| Returns @ref WGPUStatus_Error (and leaves `limits` unchanged) if there was a @ref StructChainingError. | |||
There was a problem hiding this comment.
What about if the device/adapter itself is an error? IMHO the error cases should be defined in the algorithm steps of the articles, and not call out a particular kind of error.
| @@ -3291,34 +3299,43 @@ objects: | |||
| TODO | |||
| returns: | |||
| doc: | | |||
| TODO | |||
| Returns a mutable pointer to beginning of the mapped range. | |||
| It may be written, but reading is undefined behavior unless the buffer was also mapped with @ref WGPUMapMode_Read. | |||
There was a problem hiding this comment.
Reading should be a valid for mapped write buffers, because any mapped range should get flushed to the GPU and not be modified if the implementation didn't end up writing to it. That's what happens in JS.
| @@ -4081,7 +4096,8 @@ objects: | |||
| callback: callback.queue_work_done | |||
| - name: write_buffer | |||
| doc: | | |||
| TODO | |||
| Produces a @ref DeviceError if `size` is not a multiple of 4 | |||
There was a problem hiding this comment.
This error is already handled in the JS spec.
Sorry this is a lot of things in one PR, but I kept changing all of the docs to be consistent with each other, so this was easier.
(Can split if there are some parts that need more time to discuss.)
Fixes #255
Fixes (again?) #291
Issue #225
Fixes #64