Skip to content

Commit 860a541

Browse files
kainino0xkainino0x
authored
Add missing defaulting docs to binding layout types (#451)
* Add missing defaulting docs to binding layout types * make all defaulting docs explicit about what value defaults * add defaulting doc for alphaMode too
1 parent b787f0f commit 860a541

File tree

3 files changed

+123
-52
lines changed

3 files changed

+123
-52
lines changed

‎doc/articles/SentinelValues.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@ can be called equivalently as `b.getMappedRange()`, `b.getMappedRange(0)`,
1616

1717
To represent `undefined` in C, `webgpu.h` uses `NULL` where possible (anything
1818
behind a pointer, including objects), `*_UNDEFINED` sentinel numeric values
19-
(generally `UINT32_MAX`, etc.) and `*_Undefined` enum values (generally `0`).
19+
(usually `UINT32_MAX` or similar) and `*_Undefined` enum values (usually `0`).
2020

2121
The place that uses the type will define what to do with an undefined value.
2222
It may be:

‎webgpu.h

Lines changed: 62 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1639,19 +1639,22 @@ typedef struct WGPUBindGroupEntry {
16391639
*/
16401640
typedef struct WGPUBlendComponent {
16411641
/**
1642-
* [Defaults](@ref SentinelValues) to @ref WGPUBlendOperation_Add.
1642+
* If set to @ref WGPUBlendOperation_Undefined,
1643+
* [defaults](@ref SentinelValues) to @ref WGPUBlendOperation_Add.
16431644
*
16441645
* The `INIT` macro sets this to @ref WGPUBlendOperation_Undefined.
16451646
*/
16461647
WGPUBlendOperation operation;
16471648
/**
1648-
* [Defaults](@ref SentinelValues) to @ref WGPUBlendFactor_One.
1649+
* If set to @ref WGPUBlendFactor_Undefined,
1650+
* [defaults](@ref SentinelValues) to @ref WGPUBlendFactor_One.
16491651
*
16501652
* The `INIT` macro sets this to @ref WGPUBlendFactor_Undefined.
16511653
*/
16521654
WGPUBlendFactor srcFactor;
16531655
/**
1654-
* [Defaults](@ref SentinelValues) to @ref WGPUBlendFactor_Zero.
1656+
* If set to @ref WGPUBlendFactor_Undefined,
1657+
* [defaults](@ref SentinelValues) to @ref WGPUBlendFactor_Zero.
16551658
*
16561659
* The `INIT` macro sets this to @ref WGPUBlendFactor_Undefined.
16571660
*/
@@ -1673,6 +1676,9 @@ typedef struct WGPUBlendComponent {
16731676
typedef struct WGPUBufferBindingLayout {
16741677
WGPUChainedStruct const * nextInChain;
16751678
/**
1679+
* If set to @ref WGPUBufferBindingType_Undefined,
1680+
* [defaults](@ref SentinelValues) to @ref WGPUBufferBindingType_Uniform.
1681+
*
16761682
* The `INIT` macro sets this to @ref WGPUBufferBindingType_BindingNotUsed.
16771683
*/
16781684
WGPUBufferBindingType type;
@@ -2263,7 +2269,8 @@ typedef struct WGPUPipelineLayoutDescriptor {
22632269
typedef struct WGPUPrimitiveState {
22642270
WGPUChainedStruct const * nextInChain;
22652271
/**
2266-
* [Defaults](@ref SentinelValues) to @ref WGPUPrimitiveTopology_TriangleList.
2272+
* If set to @ref WGPUPrimitiveTopology_Undefined,
2273+
* [defaults](@ref SentinelValues) to @ref WGPUPrimitiveTopology_TriangleList.
22672274
*
22682275
* The `INIT` macro sets this to @ref WGPUPrimitiveTopology_Undefined.
22692276
*/
@@ -2273,13 +2280,15 @@ typedef struct WGPUPrimitiveState {
22732280
*/
22742281
WGPUIndexFormat stripIndexFormat;
22752282
/**
2276-
* [Defaults](@ref SentinelValues) to @ref WGPUFrontFace_CCW.
2283+
* If set to @ref WGPUFrontFace_Undefined,
2284+
* [defaults](@ref SentinelValues) to @ref WGPUFrontFace_CCW.
22772285
*
22782286
* The `INIT` macro sets this to @ref WGPUFrontFace_Undefined.
22792287
*/
22802288
WGPUFrontFace frontFace;
22812289
/**
2282-
* [Defaults](@ref SentinelValues) to @ref WGPUCullMode_None.
2290+
* If set to @ref WGPUCullMode_Undefined,
2291+
* [defaults](@ref SentinelValues) to @ref WGPUCullMode_None.
22832292
*
22842293
* The `INIT` macro sets this to @ref WGPUCullMode_Undefined.
22852294
*/
@@ -2515,7 +2524,8 @@ typedef struct WGPURequestAdapterOptions {
25152524
/**
25162525
* "Feature level" for the adapter request. If an adapter is returned, it must support the features and limits in the requested feature level.
25172526
*
2518-
* [Defaults](@ref SentinelValues) to @ref WGPUFeatureLevel_Core.
2527+
* If set to @ref WGPUFeatureLevel_Undefined,
2528+
* [defaults](@ref SentinelValues) to @ref WGPUFeatureLevel_Core.
25192529
* Additionally, implementations may ignore @ref WGPUFeatureLevel_Compatibility
25202530
* and provide @ref WGPUFeatureLevel_Core instead.
25212531
*
@@ -2567,6 +2577,9 @@ typedef struct WGPURequestAdapterOptions {
25672577
typedef struct WGPUSamplerBindingLayout {
25682578
WGPUChainedStruct const * nextInChain;
25692579
/**
2580+
* If set to @ref WGPUSamplerBindingType_Undefined,
2581+
* [defaults](@ref SentinelValues) to @ref WGPUSamplerBindingType_Filtering.
2582+
*
25702583
* The `INIT` macro sets this to @ref WGPUSamplerBindingType_BindingNotUsed.
25712584
*/
25722585
WGPUSamplerBindingType type;
@@ -2592,37 +2605,43 @@ typedef struct WGPUSamplerDescriptor {
25922605
*/
25932606
WGPUStringView label;
25942607
/**
2595-
* [Defaults](@ref SentinelValues) to @ref WGPUAddressMode_ClampToEdge.
2608+
* If set to @ref WGPUAddressMode_Undefined,
2609+
* [defaults](@ref SentinelValues) to @ref WGPUAddressMode_ClampToEdge.
25962610
*
25972611
* The `INIT` macro sets this to @ref WGPUAddressMode_Undefined.
25982612
*/
25992613
WGPUAddressMode addressModeU;
26002614
/**
2601-
* [Defaults](@ref SentinelValues) to @ref WGPUAddressMode_ClampToEdge.
2615+
* If set to @ref WGPUAddressMode_Undefined,
2616+
* [defaults](@ref SentinelValues) to @ref WGPUAddressMode_ClampToEdge.
26022617
*
26032618
* The `INIT` macro sets this to @ref WGPUAddressMode_Undefined.
26042619
*/
26052620
WGPUAddressMode addressModeV;
26062621
/**
2607-
* [Defaults](@ref SentinelValues) to @ref WGPUAddressMode_ClampToEdge.
2622+
* If set to @ref WGPUAddressMode_Undefined,
2623+
* [defaults](@ref SentinelValues) to @ref WGPUAddressMode_ClampToEdge.
26082624
*
26092625
* The `INIT` macro sets this to @ref WGPUAddressMode_Undefined.
26102626
*/
26112627
WGPUAddressMode addressModeW;
26122628
/**
2613-
* [Defaults](@ref SentinelValues) to @ref WGPUFilterMode_Nearest.
2629+
* If set to @ref WGPUFilterMode_Undefined,
2630+
* [defaults](@ref SentinelValues) to @ref WGPUFilterMode_Nearest.
26142631
*
26152632
* The `INIT` macro sets this to @ref WGPUFilterMode_Undefined.
26162633
*/
26172634
WGPUFilterMode magFilter;
26182635
/**
2619-
* [Defaults](@ref SentinelValues) to @ref WGPUFilterMode_Nearest.
2636+
* If set to @ref WGPUFilterMode_Undefined,
2637+
* [defaults](@ref SentinelValues) to @ref WGPUFilterMode_Nearest.
26202638
*
26212639
* The `INIT` macro sets this to @ref WGPUFilterMode_Undefined.
26222640
*/
26232641
WGPUFilterMode minFilter;
26242642
/**
2625-
* [Defaults](@ref SentinelValues) to @ref WGPUMipmapFilterMode_Nearest.
2643+
* If set to @ref WGPUFilterMode_Undefined,
2644+
* [defaults](@ref SentinelValues) to @ref WGPUMipmapFilterMode_Nearest.
26262645
*
26272646
* The `INIT` macro sets this to @ref WGPUMipmapFilterMode_Undefined.
26282647
*/
@@ -2740,25 +2759,29 @@ typedef struct WGPUShaderSourceWGSL {
27402759
*/
27412760
typedef struct WGPUStencilFaceState {
27422761
/**
2743-
* [Defaults](@ref SentinelValues) to @ref WGPUCompareFunction_Always.
2762+
* If set to @ref WGPUCompareFunction_Undefined,
2763+
* [defaults](@ref SentinelValues) to @ref WGPUCompareFunction_Always.
27442764
*
27452765
* The `INIT` macro sets this to @ref WGPUCompareFunction_Undefined.
27462766
*/
27472767
WGPUCompareFunction compare;
27482768
/**
2749-
* [Defaults](@ref SentinelValues) to @ref WGPUStencilOperation_Keep.
2769+
* If set to @ref WGPUStencilOperation_Undefined,
2770+
* [defaults](@ref SentinelValues) to @ref WGPUStencilOperation_Keep.
27502771
*
27512772
* The `INIT` macro sets this to @ref WGPUStencilOperation_Undefined.
27522773
*/
27532774
WGPUStencilOperation failOp;
27542775
/**
2755-
* [Defaults](@ref SentinelValues) to @ref WGPUStencilOperation_Keep.
2776+
* If set to @ref WGPUStencilOperation_Undefined,
2777+
* [defaults](@ref SentinelValues) to @ref WGPUStencilOperation_Keep.
27562778
*
27572779
* The `INIT` macro sets this to @ref WGPUStencilOperation_Undefined.
27582780
*/
27592781
WGPUStencilOperation depthFailOp;
27602782
/**
2761-
* [Defaults](@ref SentinelValues) to @ref WGPUStencilOperation_Keep.
2783+
* If set to @ref WGPUStencilOperation_Undefined,
2784+
* [defaults](@ref SentinelValues) to @ref WGPUStencilOperation_Keep.
27622785
*
27632786
* The `INIT` macro sets this to @ref WGPUStencilOperation_Undefined.
27642787
*/
@@ -2781,6 +2804,9 @@ typedef struct WGPUStencilFaceState {
27812804
typedef struct WGPUStorageTextureBindingLayout {
27822805
WGPUChainedStruct const * nextInChain;
27832806
/**
2807+
* If set to @ref WGPUStorageTextureAccess_Undefined,
2808+
* [defaults](@ref SentinelValues) to @ref WGPUStorageTextureAccess_WriteOnly.
2809+
*
27842810
* The `INIT` macro sets this to @ref WGPUStorageTextureAccess_BindingNotUsed.
27852811
*/
27862812
WGPUStorageTextureAccess access;
@@ -2789,7 +2815,8 @@ typedef struct WGPUStorageTextureBindingLayout {
27892815
*/
27902816
WGPUTextureFormat format;
27912817
/**
2792-
* [Defaults](@ref SentinelValues) to @ref WGPUTextureViewDimension_2D.
2818+
* If set to @ref WGPUTextureViewDimension_Undefined,
2819+
* [defaults](@ref SentinelValues) to @ref WGPUTextureViewDimension_2D.
27932820
*
27942821
* The `INIT` macro sets this to @ref WGPUTextureViewDimension_Undefined.
27952822
*/
@@ -2963,13 +2990,18 @@ typedef struct WGPUSurfaceConfiguration {
29632990
/**
29642991
* How the surface's frames will be composited on the screen.
29652992
*
2993+
* If set to @ref WGPUCompositeAlphaMode_Auto,
2994+
* [defaults] to @ref WGPUCompositeAlphaMode_Inherit in native (allowing the mode
2995+
* to be configured externally), and to @ref WGPUCompositeAlphaMode_Opaque in Wasm.
2996+
*
29662997
* The `INIT` macro sets this to @ref WGPUCompositeAlphaMode_Auto.
29672998
*/
29682999
WGPUCompositeAlphaMode alphaMode;
29693000
/**
29703001
* When and in which order the surface's frames will be shown on the screen.
29713002
*
2972-
* [Defaults](@ref SentinelValues) to @ref WGPUPresentMode_Fifo.
3003+
* If set to @ref WGPUPresentMode_Undefined,
3004+
* [defaults](@ref SentinelValues) to @ref WGPUPresentMode_Fifo.
29733005
*
29743006
* The `INIT` macro sets this to @ref WGPUPresentMode_Undefined.
29753007
*/
@@ -3269,11 +3301,15 @@ typedef struct WGPUTexelCopyBufferLayout {
32693301
typedef struct WGPUTextureBindingLayout {
32703302
WGPUChainedStruct const * nextInChain;
32713303
/**
3304+
* If set to @ref WGPUTextureSampleType_Undefined,
3305+
* [defaults](@ref SentinelValues) to @ref WGPUTextureSampleType_Float.
3306+
*
32723307
* The `INIT` macro sets this to @ref WGPUTextureSampleType_BindingNotUsed.
32733308
*/
32743309
WGPUTextureSampleType sampleType;
32753310
/**
3276-
* [Defaults](@ref SentinelValues) to @ref WGPUTextureViewDimension_2D.
3311+
* If set to @ref WGPUTextureViewDimension_Undefined,
3312+
* [defaults](@ref SentinelValues) to @ref WGPUTextureViewDimension_2D.
32773313
*
32783314
* The `INIT` macro sets this to @ref WGPUTextureViewDimension_Undefined.
32793315
*/
@@ -3330,7 +3366,8 @@ typedef struct WGPUTextureViewDescriptor {
33303366
*/
33313367
uint32_t arrayLayerCount;
33323368
/**
3333-
* [Defaults](@ref SentinelValues) to @ref WGPUTextureAspect_All.
3369+
* If set to @ref WGPUTextureAspect_Undefined,
3370+
* [defaults](@ref SentinelValues) to @ref WGPUTextureAspect_All.
33343371
*
33353372
* The `INIT` macro sets this to @ref WGPUTextureAspect_Undefined.
33363373
*/
@@ -3824,7 +3861,8 @@ typedef struct WGPUTexelCopyTextureInfo {
38243861
*/
38253862
WGPUOrigin3D origin;
38263863
/**
3827-
* [Defaults](@ref SentinelValues) to @ref WGPUTextureAspect_All.
3864+
* If set to @ref WGPUTextureAspect_Undefined,
3865+
* [defaults](@ref SentinelValues) to @ref WGPUTextureAspect_All.
38283866
*
38293867
* The `INIT` macro sets this to @ref WGPUTextureAspect_Undefined.
38303868
*/
@@ -3857,7 +3895,8 @@ typedef struct WGPUTextureDescriptor {
38573895
*/
38583896
WGPUTextureUsage usage;
38593897
/**
3860-
* [Defaults](@ref SentinelValues) to @ref WGPUTextureDimension_2D.
3898+
* If set to @ref WGPUTextureDimension_Undefined,
3899+
* [defaults](@ref SentinelValues) to @ref WGPUTextureDimension_2D.
38613900
*
38623901
* The `INIT` macro sets this to @ref WGPUTextureDimension_Undefined.
38633902
*/

0 commit comments

Comments
 (0)