diff --git a/doc/articles/SentinelValues.md b/doc/articles/SentinelValues.md index 96d80885..da509fbf 100644 --- a/doc/articles/SentinelValues.md +++ b/doc/articles/SentinelValues.md @@ -16,7 +16,7 @@ can be called equivalently as `b.getMappedRange()`, `b.getMappedRange(0)`, 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`). +(usually `UINT32_MAX` or similar) and `*_Undefined` enum values (usually `0`). The place that uses the type will define what to do with an undefined value. It may be: diff --git a/webgpu.h b/webgpu.h index f465b748..2e17a34b 100644 --- a/webgpu.h +++ b/webgpu.h @@ -1639,19 +1639,22 @@ typedef struct WGPUBindGroupEntry { */ typedef struct WGPUBlendComponent { /** - * [Defaults](@ref SentinelValues) to @ref WGPUBlendOperation_Add. + * If set to @ref WGPUBlendOperation_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUBlendOperation_Add. * * The `INIT` macro sets this to @ref WGPUBlendOperation_Undefined. */ WGPUBlendOperation operation; /** - * [Defaults](@ref SentinelValues) to @ref WGPUBlendFactor_One. + * If set to @ref WGPUBlendFactor_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUBlendFactor_One. * * The `INIT` macro sets this to @ref WGPUBlendFactor_Undefined. */ WGPUBlendFactor srcFactor; /** - * [Defaults](@ref SentinelValues) to @ref WGPUBlendFactor_Zero. + * If set to @ref WGPUBlendFactor_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUBlendFactor_Zero. * * The `INIT` macro sets this to @ref WGPUBlendFactor_Undefined. */ @@ -1673,6 +1676,9 @@ typedef struct WGPUBlendComponent { typedef struct WGPUBufferBindingLayout { WGPUChainedStruct const * nextInChain; /** + * If set to @ref WGPUBufferBindingType_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUBufferBindingType_Uniform. + * * The `INIT` macro sets this to @ref WGPUBufferBindingType_BindingNotUsed. */ WGPUBufferBindingType type; @@ -2263,7 +2269,8 @@ typedef struct WGPUPipelineLayoutDescriptor { typedef struct WGPUPrimitiveState { WGPUChainedStruct const * nextInChain; /** - * [Defaults](@ref SentinelValues) to @ref WGPUPrimitiveTopology_TriangleList. + * If set to @ref WGPUPrimitiveTopology_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUPrimitiveTopology_TriangleList. * * The `INIT` macro sets this to @ref WGPUPrimitiveTopology_Undefined. */ @@ -2273,13 +2280,15 @@ typedef struct WGPUPrimitiveState { */ WGPUIndexFormat stripIndexFormat; /** - * [Defaults](@ref SentinelValues) to @ref WGPUFrontFace_CCW. + * If set to @ref WGPUFrontFace_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUFrontFace_CCW. * * The `INIT` macro sets this to @ref WGPUFrontFace_Undefined. */ WGPUFrontFace frontFace; /** - * [Defaults](@ref SentinelValues) to @ref WGPUCullMode_None. + * If set to @ref WGPUCullMode_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUCullMode_None. * * The `INIT` macro sets this to @ref WGPUCullMode_Undefined. */ @@ -2515,7 +2524,8 @@ typedef struct WGPURequestAdapterOptions { /** * "Feature level" for the adapter request. If an adapter is returned, it must support the features and limits in the requested feature level. * - * [Defaults](@ref SentinelValues) to @ref WGPUFeatureLevel_Core. + * If set to @ref WGPUFeatureLevel_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUFeatureLevel_Core. * Additionally, implementations may ignore @ref WGPUFeatureLevel_Compatibility * and provide @ref WGPUFeatureLevel_Core instead. * @@ -2567,6 +2577,9 @@ typedef struct WGPURequestAdapterOptions { typedef struct WGPUSamplerBindingLayout { WGPUChainedStruct const * nextInChain; /** + * If set to @ref WGPUSamplerBindingType_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUSamplerBindingType_Filtering. + * * The `INIT` macro sets this to @ref WGPUSamplerBindingType_BindingNotUsed. */ WGPUSamplerBindingType type; @@ -2592,37 +2605,43 @@ typedef struct WGPUSamplerDescriptor { */ WGPUStringView label; /** - * [Defaults](@ref SentinelValues) to @ref WGPUAddressMode_ClampToEdge. + * If set to @ref WGPUAddressMode_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUAddressMode_ClampToEdge. * * The `INIT` macro sets this to @ref WGPUAddressMode_Undefined. */ WGPUAddressMode addressModeU; /** - * [Defaults](@ref SentinelValues) to @ref WGPUAddressMode_ClampToEdge. + * If set to @ref WGPUAddressMode_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUAddressMode_ClampToEdge. * * The `INIT` macro sets this to @ref WGPUAddressMode_Undefined. */ WGPUAddressMode addressModeV; /** - * [Defaults](@ref SentinelValues) to @ref WGPUAddressMode_ClampToEdge. + * If set to @ref WGPUAddressMode_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUAddressMode_ClampToEdge. * * The `INIT` macro sets this to @ref WGPUAddressMode_Undefined. */ WGPUAddressMode addressModeW; /** - * [Defaults](@ref SentinelValues) to @ref WGPUFilterMode_Nearest. + * If set to @ref WGPUFilterMode_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUFilterMode_Nearest. * * The `INIT` macro sets this to @ref WGPUFilterMode_Undefined. */ WGPUFilterMode magFilter; /** - * [Defaults](@ref SentinelValues) to @ref WGPUFilterMode_Nearest. + * If set to @ref WGPUFilterMode_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUFilterMode_Nearest. * * The `INIT` macro sets this to @ref WGPUFilterMode_Undefined. */ WGPUFilterMode minFilter; /** - * [Defaults](@ref SentinelValues) to @ref WGPUMipmapFilterMode_Nearest. + * If set to @ref WGPUFilterMode_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUMipmapFilterMode_Nearest. * * The `INIT` macro sets this to @ref WGPUMipmapFilterMode_Undefined. */ @@ -2740,25 +2759,29 @@ typedef struct WGPUShaderSourceWGSL { */ typedef struct WGPUStencilFaceState { /** - * [Defaults](@ref SentinelValues) to @ref WGPUCompareFunction_Always. + * If set to @ref WGPUCompareFunction_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUCompareFunction_Always. * * The `INIT` macro sets this to @ref WGPUCompareFunction_Undefined. */ WGPUCompareFunction compare; /** - * [Defaults](@ref SentinelValues) to @ref WGPUStencilOperation_Keep. + * If set to @ref WGPUStencilOperation_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUStencilOperation_Keep. * * The `INIT` macro sets this to @ref WGPUStencilOperation_Undefined. */ WGPUStencilOperation failOp; /** - * [Defaults](@ref SentinelValues) to @ref WGPUStencilOperation_Keep. + * If set to @ref WGPUStencilOperation_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUStencilOperation_Keep. * * The `INIT` macro sets this to @ref WGPUStencilOperation_Undefined. */ WGPUStencilOperation depthFailOp; /** - * [Defaults](@ref SentinelValues) to @ref WGPUStencilOperation_Keep. + * If set to @ref WGPUStencilOperation_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUStencilOperation_Keep. * * The `INIT` macro sets this to @ref WGPUStencilOperation_Undefined. */ @@ -2781,6 +2804,9 @@ typedef struct WGPUStencilFaceState { typedef struct WGPUStorageTextureBindingLayout { WGPUChainedStruct const * nextInChain; /** + * If set to @ref WGPUStorageTextureAccess_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUStorageTextureAccess_WriteOnly. + * * The `INIT` macro sets this to @ref WGPUStorageTextureAccess_BindingNotUsed. */ WGPUStorageTextureAccess access; @@ -2789,7 +2815,8 @@ typedef struct WGPUStorageTextureBindingLayout { */ WGPUTextureFormat format; /** - * [Defaults](@ref SentinelValues) to @ref WGPUTextureViewDimension_2D. + * If set to @ref WGPUTextureViewDimension_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUTextureViewDimension_2D. * * The `INIT` macro sets this to @ref WGPUTextureViewDimension_Undefined. */ @@ -2963,13 +2990,18 @@ typedef struct WGPUSurfaceConfiguration { /** * How the surface's frames will be composited on the screen. * + * If set to @ref WGPUCompositeAlphaMode_Auto, + * [defaults] to @ref WGPUCompositeAlphaMode_Inherit in native (allowing the mode + * to be configured externally), and to @ref WGPUCompositeAlphaMode_Opaque in Wasm. + * * The `INIT` macro sets this to @ref WGPUCompositeAlphaMode_Auto. */ WGPUCompositeAlphaMode alphaMode; /** * When and in which order the surface's frames will be shown on the screen. * - * [Defaults](@ref SentinelValues) to @ref WGPUPresentMode_Fifo. + * If set to @ref WGPUPresentMode_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUPresentMode_Fifo. * * The `INIT` macro sets this to @ref WGPUPresentMode_Undefined. */ @@ -3269,11 +3301,15 @@ typedef struct WGPUTexelCopyBufferLayout { typedef struct WGPUTextureBindingLayout { WGPUChainedStruct const * nextInChain; /** + * If set to @ref WGPUTextureSampleType_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUTextureSampleType_Float. + * * The `INIT` macro sets this to @ref WGPUTextureSampleType_BindingNotUsed. */ WGPUTextureSampleType sampleType; /** - * [Defaults](@ref SentinelValues) to @ref WGPUTextureViewDimension_2D. + * If set to @ref WGPUTextureViewDimension_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUTextureViewDimension_2D. * * The `INIT` macro sets this to @ref WGPUTextureViewDimension_Undefined. */ @@ -3330,7 +3366,8 @@ typedef struct WGPUTextureViewDescriptor { */ uint32_t arrayLayerCount; /** - * [Defaults](@ref SentinelValues) to @ref WGPUTextureAspect_All. + * If set to @ref WGPUTextureAspect_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUTextureAspect_All. * * The `INIT` macro sets this to @ref WGPUTextureAspect_Undefined. */ @@ -3824,7 +3861,8 @@ typedef struct WGPUTexelCopyTextureInfo { */ WGPUOrigin3D origin; /** - * [Defaults](@ref SentinelValues) to @ref WGPUTextureAspect_All. + * If set to @ref WGPUTextureAspect_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUTextureAspect_All. * * The `INIT` macro sets this to @ref WGPUTextureAspect_Undefined. */ @@ -3857,7 +3895,8 @@ typedef struct WGPUTextureDescriptor { */ WGPUTextureUsage usage; /** - * [Defaults](@ref SentinelValues) to @ref WGPUTextureDimension_2D. + * If set to @ref WGPUTextureDimension_Undefined, + * [defaults](@ref SentinelValues) to @ref WGPUTextureDimension_2D. * * The `INIT` macro sets this to @ref WGPUTextureDimension_Undefined. */ diff --git a/webgpu.yml b/webgpu.yml index a29fd757..26835714 100644 --- a/webgpu.yml +++ b/webgpu.yml @@ -1633,17 +1633,20 @@ structs: members: - name: operation doc: | - [Defaults](@ref SentinelValues) to @ref WGPUBlendOperation_Add. + If set to @ref WGPUBlendOperation_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUBlendOperation_Add. type: enum.blend_operation default: undefined - name: src_factor doc: | - [Defaults](@ref SentinelValues) to @ref WGPUBlendFactor_One. + If set to @ref WGPUBlendFactor_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUBlendFactor_One. type: enum.blend_factor default: undefined - name: dst_factor doc: | - [Defaults](@ref SentinelValues) to @ref WGPUBlendFactor_Zero. + If set to @ref WGPUBlendFactor_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUBlendFactor_Zero. type: enum.blend_factor default: undefined - name: blend_state @@ -1666,7 +1669,8 @@ structs: members: - name: type doc: | - TODO + If set to @ref WGPUBufferBindingType_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUBufferBindingType_Uniform. type: enum.buffer_binding_type default: binding_not_used - name: has_dynamic_offset @@ -2268,7 +2272,8 @@ structs: members: - name: topology doc: | - [Defaults](@ref SentinelValues) to @ref WGPUPrimitiveTopology_TriangleList. + If set to @ref WGPUPrimitiveTopology_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUPrimitiveTopology_TriangleList. type: enum.primitive_topology default: undefined - name: strip_index_format @@ -2277,12 +2282,14 @@ structs: type: enum.index_format - name: front_face doc: | - [Defaults](@ref SentinelValues) to @ref WGPUFrontFace_CCW. + If set to @ref WGPUFrontFace_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUFrontFace_CCW. type: enum.front_face default: undefined - name: cull_mode doc: | - [Defaults](@ref SentinelValues) to @ref WGPUCullMode_None. + If set to @ref WGPUCullMode_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUCullMode_None. type: enum.cull_mode default: undefined - name: unclipped_depth @@ -2530,7 +2537,8 @@ structs: doc: | "Feature level" for the adapter request. If an adapter is returned, it must support the features and limits in the requested feature level. - [Defaults](@ref SentinelValues) to @ref WGPUFeatureLevel_Core. + If set to @ref WGPUFeatureLevel_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUFeatureLevel_Core. Additionally, implementations may ignore @ref WGPUFeatureLevel_Compatibility and provide @ref WGPUFeatureLevel_Core instead. type: enum.feature_level @@ -2565,7 +2573,8 @@ structs: members: - name: type doc: | - TODO + If set to @ref WGPUSamplerBindingType_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUSamplerBindingType_Filtering. type: enum.sampler_binding_type default: binding_not_used - name: sampler_descriptor @@ -2579,32 +2588,38 @@ structs: type: string_with_default_empty - name: address_mode_u doc: | - [Defaults](@ref SentinelValues) to @ref WGPUAddressMode_ClampToEdge. + If set to @ref WGPUAddressMode_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUAddressMode_ClampToEdge. type: enum.address_mode default: undefined - name: address_mode_v doc: | - [Defaults](@ref SentinelValues) to @ref WGPUAddressMode_ClampToEdge. + If set to @ref WGPUAddressMode_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUAddressMode_ClampToEdge. type: enum.address_mode default: undefined - name: address_mode_w doc: | - [Defaults](@ref SentinelValues) to @ref WGPUAddressMode_ClampToEdge. + If set to @ref WGPUAddressMode_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUAddressMode_ClampToEdge. type: enum.address_mode default: undefined - name: mag_filter doc: | - [Defaults](@ref SentinelValues) to @ref WGPUFilterMode_Nearest. + If set to @ref WGPUFilterMode_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUFilterMode_Nearest. type: enum.filter_mode default: undefined - name: min_filter doc: | - [Defaults](@ref SentinelValues) to @ref WGPUFilterMode_Nearest. + If set to @ref WGPUFilterMode_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUFilterMode_Nearest. type: enum.filter_mode default: undefined - name: mipmap_filter doc: | - [Defaults](@ref SentinelValues) to @ref WGPUMipmapFilterMode_Nearest. + If set to @ref WGPUFilterMode_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUMipmapFilterMode_Nearest. type: enum.mipmap_filter_mode default: undefined - name: lod_min_clamp @@ -2671,22 +2686,26 @@ structs: members: - name: compare doc: | - [Defaults](@ref SentinelValues) to @ref WGPUCompareFunction_Always. + If set to @ref WGPUCompareFunction_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUCompareFunction_Always. type: enum.compare_function default: undefined - name: fail_op doc: | - [Defaults](@ref SentinelValues) to @ref WGPUStencilOperation_Keep. + If set to @ref WGPUStencilOperation_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUStencilOperation_Keep. type: enum.stencil_operation default: undefined - name: depth_fail_op doc: | - [Defaults](@ref SentinelValues) to @ref WGPUStencilOperation_Keep. + If set to @ref WGPUStencilOperation_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUStencilOperation_Keep. type: enum.stencil_operation default: undefined - name: pass_op doc: | - [Defaults](@ref SentinelValues) to @ref WGPUStencilOperation_Keep. + If set to @ref WGPUStencilOperation_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUStencilOperation_Keep. type: enum.stencil_operation default: undefined - name: storage_texture_binding_layout @@ -2696,7 +2715,8 @@ structs: members: - name: access doc: | - TODO + If set to @ref WGPUStorageTextureAccess_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUStorageTextureAccess_WriteOnly. type: enum.storage_texture_access default: binding_not_used - name: format @@ -2706,7 +2726,8 @@ structs: default: undefined - name: view_dimension doc: | - [Defaults](@ref SentinelValues) to @ref WGPUTextureViewDimension_2D. + If set to @ref WGPUTextureViewDimension_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUTextureViewDimension_2D. type: enum.texture_view_dimension default: undefined - name: supported_features @@ -2785,14 +2806,20 @@ structs: type: array pointer: immutable - name: alpha_mode - doc: How the surface's frames will be composited on the screen. + doc: | + How the surface's frames will be composited on the screen. + + If set to @ref WGPUCompositeAlphaMode_Auto, + [defaults] to @ref WGPUCompositeAlphaMode_Inherit in native (allowing the mode + to be configured externally), and to @ref WGPUCompositeAlphaMode_Opaque in Wasm. type: enum.composite_alpha_mode default: auto - name: present_mode doc: | When and in which order the surface's frames will be shown on the screen. - [Defaults](@ref SentinelValues) to @ref WGPUPresentMode_Fifo. + If set to @ref WGPUPresentMode_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUPresentMode_Fifo. type: enum.present_mode default: undefined - name: surface_descriptor @@ -2948,7 +2975,8 @@ structs: type: struct.origin_3D - name: aspect doc: | - [Defaults](@ref SentinelValues) to @ref WGPUTextureAspect_All. + If set to @ref WGPUTextureAspect_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUTextureAspect_All. type: enum.texture_aspect default: undefined - name: texture_binding_layout @@ -2958,12 +2986,14 @@ structs: members: - name: sample_type doc: | - TODO + If set to @ref WGPUTextureSampleType_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUTextureSampleType_Float. type: enum.texture_sample_type default: binding_not_used - name: view_dimension doc: | - [Defaults](@ref SentinelValues) to @ref WGPUTextureViewDimension_2D. + If set to @ref WGPUTextureViewDimension_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUTextureViewDimension_2D. type: enum.texture_view_dimension default: undefined - name: multisampled @@ -2987,7 +3017,8 @@ structs: default: none - name: dimension doc: | - [Defaults](@ref SentinelValues) to @ref WGPUTextureDimension_2D. + If set to @ref WGPUTextureDimension_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUTextureDimension_2D. type: enum.texture_dimension default: undefined - name: size @@ -3055,7 +3086,8 @@ structs: default: constant.array_layer_count_undefined - name: aspect doc: | - [Defaults](@ref SentinelValues) to @ref WGPUTextureAspect_All. + If set to @ref WGPUTextureAspect_Undefined, + [defaults](@ref SentinelValues) to @ref WGPUTextureAspect_All. type: enum.texture_aspect default: undefined - name: usage