Remove WGPUVertexStepMode_VertexBufferNotUsed, make 1:1 mapping with JS (#439)

Issue: 432

Author: kainino0x

doc/articles/SentinelValues.md

@@ -36,7 +36,7 @@ WebIDL's more flexible typing:
 - \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 WGPUVertexBufferLayout::stepMode = \ref WGPUVertexStepMode_Undefined with \ref WGPUVertexBufferLayout::attributeCount
     - \ref WGPUBufferBindingLayout::type = \ref WGPUBufferBindingType_BindingNotUsed
     - \ref WGPUSamplerBindingLayout::type = \ref WGPUSamplerBindingType_BindingNotUsed
     - \ref WGPUTextureBindingLayout::sampleType = \ref WGPUTextureSampleType_BindingNotUsed

webgpu.h

@@ -1080,17 +1080,11 @@ typedef enum WGPUVertexFormat {
 typedef enum WGPUVertexStepMode {
     /**
      * `0x00000000`.
-     * This @ref WGPUVertexBufferLayout is a "hole" in the @ref WGPUVertexState `buffers` array.
-     * (See also @ref SentinelValues.)
-     */
-    WGPUVertexStepMode_VertexBufferNotUsed = 0x00000000,
-    /**
-     * `0x00000001`.
      * Indicates no value is passed for this argument. See @ref SentinelValues.
      */
-    WGPUVertexStepMode_Undefined = 0x00000001,
-    WGPUVertexStepMode_Vertex = 0x00000002,
-    WGPUVertexStepMode_Instance = 0x00000003,
+    WGPUVertexStepMode_Undefined = 0x00000000,
+    WGPUVertexStepMode_Vertex = 0x00000001,
+    WGPUVertexStepMode_Instance = 0x00000002,
     WGPUVertexStepMode_Force32 = 0x7FFFFFFF
 } WGPUVertexStepMode WGPU_ENUM_ATTRIBUTE;
 
@@ -3866,16 +3860,25 @@ typedef struct WGPUTextureDescriptor {
 })
 
 /**
+ * If `attributes` is empty *and* `stepMode` is @ref WGPUVertexStepMode_Undefined,
+ * indicates a "hole" in the parent @ref WGPUVertexState `buffers` array,
+ * with behavior equivalent to `null` in the JS API.
+ *
+ * If `attributes` is empty but `stepMode` is *not* @ref WGPUVertexStepMode_Undefined,
+ * indicates a vertex buffer with no attributes, with behavior equivalent to
+ * `{ attributes: [] }` in the JS API. (TODO: If the JS API changes not to
+ * distinguish these cases, then this distinction doesn't matter and we can
+ * remove this documentation.)
+ *
+ * If `stepMode` is @ref WGPUVertexStepMode_Undefined but `attributes` is *not* empty,
+ * `stepMode` [defaults](@ref SentinelValues) to @ref WGPUVertexStepMode_Vertex.
+ *
  * Default values can be set using @ref WGPU_VERTEX_BUFFER_LAYOUT_INIT as initializer.
  */
 typedef struct WGPUVertexBufferLayout {
     WGPUChainedStruct const * nextInChain;
     /**
-     * The step mode for the vertex buffer. If @ref WGPUVertexStepMode_VertexBufferNotUsed,
-     * indicates a "hole" in the parent @ref WGPUVertexState `buffers` array:
-     * the pipeline does not use a vertex buffer at this `location`.
-     *
-     * The `INIT` macro sets this to @ref WGPUVertexStepMode_VertexBufferNotUsed.
+     * The `INIT` macro sets this to @ref WGPUVertexStepMode_Undefined.
      */
     WGPUVertexStepMode stepMode;
     /**
@@ -3894,7 +3897,7 @@ typedef struct WGPUVertexBufferLayout {
  */
 #define WGPU_VERTEX_BUFFER_LAYOUT_INIT _wgpu_MAKE_INIT_STRUCT(WGPUVertexBufferLayout, { \
     /*.nextInChain=*/NULL _wgpu_COMMA \
-    /*.stepMode=*/WGPUVertexStepMode_VertexBufferNotUsed _wgpu_COMMA \
+    /*.stepMode=*/WGPUVertexStepMode_Undefined _wgpu_COMMA \
     /*.arrayStride=*/0 _wgpu_COMMA \
     /*.attributeCount=*/0 _wgpu_COMMA \
     /*.attributes=*/NULL _wgpu_COMMA \

webgpu.yml

@@ -1330,10 +1330,6 @@ enums:
     doc: |
       TODO
     entries:
-      - name: vertex_buffer_not_used
-        doc: |
-          This @ref WGPUVertexBufferLayout is a "hole" in the @ref WGPUVertexState `buffers` array.
-          (See also @ref SentinelValues.)
       - name: undefined
         doc: Indicates no value is passed for this argument. See @ref SentinelValues.
       - name: vertex
@@ -3086,16 +3082,25 @@ structs:
         type: uint32
   - name: vertex_buffer_layout
     doc: |
-      TODO
+      If `attributes` is empty *and* `stepMode` is @ref WGPUVertexStepMode_Undefined,
+      indicates a "hole" in the parent @ref WGPUVertexState `buffers` array,
+      with behavior equivalent to `null` in the JS API.
+
+      If `attributes` is empty but `stepMode` is *not* @ref WGPUVertexStepMode_Undefined,
+      indicates a vertex buffer with no attributes, with behavior equivalent to
+      `{ attributes: [] }` in the JS API. (TODO: If the JS API changes not to
+      distinguish these cases, then this distinction doesn't matter and we can
+      remove this documentation.)
+
+      If `stepMode` is @ref WGPUVertexStepMode_Undefined but `attributes` is *not* empty,
+      `stepMode` [defaults](@ref SentinelValues) to @ref WGPUVertexStepMode_Vertex.
     type: base_in
     members:
       - name: step_mode
         doc: |
-          The step mode for the vertex buffer. If @ref WGPUVertexStepMode_VertexBufferNotUsed,
-          indicates a "hole" in the parent @ref WGPUVertexState `buffers` array:
-          the pipeline does not use a vertex buffer at this `location`.
+          TODO
         type: enum.vertex_step_mode
-        default: vertex_buffer_not_used
+        default: undefined
       - name: array_stride
         doc: |
           TODO