diff --git a/doc/articles/SentinelValues.md b/doc/articles/SentinelValues.md index 321839ac..4bfddbb0 100644 --- a/doc/articles/SentinelValues.md +++ b/doc/articles/SentinelValues.md @@ -1,6 +1,6 @@ # Sentinel Values {#SentinelValues} -## Undefined +## Undefined and Null Since WebGPU is defined first as a JavaScript API, it uses the JavaScript value `undefined` in many places to indicate the lack of a value. @@ -14,7 +14,8 @@ It may also be used in functions/methods. For example, `GPUBuffer`'s can be called equivalently as `b.getMappedRange()`, `b.getMappedRange(0)`, `b.getMappedRange(undefined)`, or `b.getMappedRange(undefined, undefined)`. -To represent `undefined` in C, `webgpu.h` uses `*_UNDEFINED` sentinel numeric values +To represent `undefined` in C, `webgpu.h` uses `NULL` where possible (anything +behind a pointer, including objects), `*_UNDEFINED` sentinel numeric values (generally `UINT32_MAX`, etc.) and `*_Undefined` enum values (generally `0`). The place that uses the type will define what to do with an undefined value. @@ -26,13 +27,19 @@ It may be: (usually this is either a special value or it has more complex defaulting, for example depending on other values). -## Other sentinel values - -Undefined values are also be used in C-specific ways in place of WebIDL's -more flexible typing: - -- \ref WGPUVertexStepMode_VertexBufferNotUsed -- \ref WGPUBufferBindingType_BindingNotUsed -- \ref WGPUSamplerBindingType_BindingNotUsed -- \ref WGPUTextureSampleType_BindingNotUsed -- \ref WGPUStorageTextureAccess_BindingNotUsed +## C-Specific Sentinel Values + +Undefined and null values are also used in C-specific ways in place of +WebIDL's more flexible typing: + +- \ref WGPUStringView has a special null value +- \ref WGPUFuture has a special null value +- Special cases to indicate the parent struct is null, avoiding extra layers of + pointers just for nullability: + - \ref WGPUVertexBufferLayout::stepMode = \ref WGPUVertexStepMode_VertexBufferNotUsed + - \ref WGPUBufferBindingLayout::type = \ref WGPUBufferBindingType_BindingNotUsed + - \ref WGPUSamplerBindingLayout::type = \ref WGPUSamplerBindingType_BindingNotUsed + - \ref WGPUTextureBindingLayout::sampleType = \ref WGPUTextureSampleType_BindingNotUsed + - \ref WGPUStorageTextureBindingLayout::access = \ref WGPUStorageTextureAccess_BindingNotUsed + - \ref WGPURenderPassColorAttachment::view = `NULL` + - \ref WGPUColorTargetState::format = \ref WGPUTextureFormat_Undefined diff --git a/webgpu.h b/webgpu.h index a08c9a42..7e3d7ea5 100644 --- a/webgpu.h +++ b/webgpu.h @@ -3668,6 +3668,9 @@ typedef struct WGPUInstanceDescriptor { typedef struct WGPURenderPassColorAttachment { WGPUChainedStruct const * nextInChain; /** + * If `NULL`, indicates a hole in the parent + * @ref WGPURenderPassDescriptor::colorAttachments array. + * * The `INIT` macro sets this to `NULL`. */ WGPU_NULLABLE WGPUTextureView view; diff --git a/webgpu.yml b/webgpu.yml index a75fa595..88d88073 100644 --- a/webgpu.yml +++ b/webgpu.yml @@ -2374,7 +2374,8 @@ structs: members: - name: view doc: | - TODO + If `NULL`, indicates a hole in the parent + @ref WGPURenderPassDescriptor::colorAttachments array. type: object.texture_view optional: true - name: depth_slice