Extract multi-draw-indirect into new methods.

mrshannon · mrshannon · commit b80d5d9ca640 · 2021-07-25T21:18:02.000-06:00
diff --git a/spec/index.bs b/spec/index.bs
@@ -1254,6 +1254,12 @@ The default is used if a value is not explicitly specified in {{GPUDeviceDescrip
     <tr class=row-continuation><td colspan=4>
         The maximum value for the arguments of {{GPUComputePassEncoder/dispatch(x, y, z)}}.
 
+    <tr><td><dfn>maxMultiDrawIndirectCount</dfn>
+        <td>{{GPUSize32}} <td>Higher <td>1
+    <tr class=row-continuation><td colspan=4>
+        The maximum value for the `maxDrawCount` argument in
+        {{GPURenderEncoderBase/multiDrawIndirect()}} and {{GPURenderEncoderBase/multiDrawIndexedIndirect()}}.
+
 </table>
 
 Issue: Do we need to have a max per-pixel render target size?
@@ -1290,6 +1296,7 @@ interface GPUSupportedLimits {
     readonly attribute unsigned long maxComputeWorkgroupInvocations;
     readonly attribute GPUExtent3D maxComputeWorkgroupSize;
     readonly attribute unsigned long maxComputePerDimensionDispatchSize;
+    readonly attribute unsigned long maxIndirectDrawCount;
 };
 </script>
 
@@ -6689,12 +6696,15 @@ interface mixin GPURenderEncoderBase {
                      optional GPUSignedOffset32 baseVertex = 0,
                      optional GPUSize32 firstInstance = 0);
 
-    undefined drawIndirect(GPUBuffer indirectBuffer, GPUSize64 indirectOffset,
-                     optional GPUSize32 maxDrawCount = 1,
+    undefined drawIndirect(GPUBuffer indirectBuffer, GPUSize64 indirectOffset);
+    undefined drawIndexedIndirect(GPUBuffer indirectBuffer, GPUSize64 indirectOffset);
+
+    undefined multiDrawIndirect(GPUBuffer indirectBuffer, GPUSize64 indirectOffset,
+                     GPUSize32 maxDrawCount,
                      optional GPUBuffer drawCountBuffer = null,
                      optional GPUSize64 drawCountOffset = 0);
-    undefined drawIndexedIndirect(GPUBuffer indirectBuffer, GPUSize64 indirectOffset,
-                     optional GPUSize32 maxDrawCount = 1,
+    undefined multiDrawIndexedIndirect(GPUBuffer indirectBuffer, GPUSize64 indirectOffset,
+                     GPUSize32 maxDrawCount,
                      optional GPUBuffer drawCountBuffer = null,
                      optional GPUSize64 drawCountOffset = 0);
 };
@@ -7216,12 +7226,12 @@ enum GPUStoreOp {
             </div>
         </div>
 
-    : <dfn>drawIndirect(indirectBuffer, indirectOffset, maxDrawCount, drawCountBuffer, drawCountOffset)</dfn>
+    : <dfn>drawIndirect(indirectBuffer, indirectOffset)</dfn>
     ::
         Draws primitives using parameters read from a {{GPUBuffer}}.
         See [[#rendering-operations]] for the detailed specification.
 
-        The <dfn dfn for=>indirect draw parameters</dfn> encoded in the |indirectBuffer| must be a tightly
+        The <dfn dfn for=>indirect draw parameters</dfn> encoded in the buffer must be a tightly
         packed block of **four 32-bit unsigned integer values (16 bytes total)**, given in the same
         order as the arguments for {{GPURenderEncoderBase/draw()}}. For example:
 
@@ -7238,23 +7248,13 @@ enum GPUStoreOp {
         non-zero `firstInstance` value will result in the {{GPURenderEncoderBase/drawIndirect()}} call being
         treated as a no-op.
 
-        If and only if the {{GPUFeatureName/"multi-draw-indirect"}} [=feature=] is enabled, [=indirect draw parameters=]
-        may be repeated with 16 byte stride, allowing multiple draws per call to {{GPURenderEncoderBase/drawIndirect()}}.
-        The actual number of draws is the minimum of |maxDrawCount| and the [=indirect draw count=] (if given).
-
-        The <dfn dfn for=>indirect draw count</dfn> encoded in the |drawCountBuffer| must be a **32-bit unsigned
-        integer** giving the number of draws to issue from the |indirectBuffer|.
-
         <div algorithm="GPURenderEncoderBase.drawIndirect">
             **Called on:** {{GPURenderEncoderBase}} this.
 
             **Arguments:**
             <pre class=argumentdef for="GPURenderEncoderBase/drawIndirect(indirectBuffer, indirectOffset)">
                 |indirectBuffer|: Buffer containing the [=indirect draw parameters=].
                 |indirectOffset|: Offset in bytes into |indirectBuffer| where the drawing data begins.
-                |maxDrawCount|: Maxumum number of draws or exact number of draws if |drawCountBuffer| is `null`.
-                |drawCountBuffer|: Buffer containing the [=indirect draw count=].
-                |drawCountOffset|: Offset in bytes into |drawCountBuffer| where the [=indirect draw count=] is located.
             </pre>
 
             **Returns:** {{undefined}}
@@ -7269,24 +7269,17 @@ enum GPUStoreOp {
                         - |indirectOffset| + sizeof([=indirect draw parameters=]) &le;
                             |indirectBuffer|.{{GPUBuffer/[[size]]}}.
                         - |indirectOffset| is a multiple of 4.
-                        - |maxDrawCount| = 1, unless the {{GPUFeatureName/"multi-draw-indirect"}} [=feature=] is enabled.
-                        - |drawCountBuffer| is `null`, unless the {{GPUFeatureName/"multi-draw-indirect"}} [=feature=] is enabled.
-                        - |drawCountBuffer| is [$valid to use with$] |this|.
-                        - |drawCountBuffer|.{{GPUBuffer/[[usage]]}} contains {{GPUBufferUsage/INDIRECT}}.
-                        - |drawCountOffset| + sizeof([=indirect draw count=]) &le;
-                            |drawCountBuffer|.{{GPUBuffer/[[size]]}}.
-                        - |drawCountOffset| is a multiple of 4.
                     </div>
-                1. Add |indirectBuffer| and |drawCountBuffer| (if given) to the [=usage scope=] as [=internal usage/input=].
+                1. Add |indirectBuffer| to the [=usage scope=] as [=internal usage/input=].
             </div>
         </div>
 
-    : <dfn>drawIndexedIndirect(indirectBuffer, indirectOffset, maxDrawCount, drawCountBuffer, drawCountOffset)</dfn>
+    : <dfn>drawIndexedIndirect(indirectBuffer, indirectOffset)</dfn>
     ::
         Draws indexed primitives using parameters read from a {{GPUBuffer}}.
         See [[#rendering-operations]] for the detailed specification.
 
-        The <dfn dfn for=>indirect drawIndexed parameters</dfn> encoded in the |indirectBuffer| must be a
+        The <dfn dfn for=>indirect drawIndexed parameters</dfn> encoded in the buffer must be a
         tightly packed block of **five 32-bit unsigned integer values (20 bytes total)**, given in
         the same order as the arguments for {{GPURenderEncoderBase/drawIndexed()}}. For example:
 
@@ -7304,23 +7297,13 @@ enum GPUStoreOp {
         non-zero `firstInstance` value will result in the {{GPURenderEncoderBase/drawIndirect()}} call being
         treated as a no-op.
 
-        If and only if the {{GPUFeatureName/"multi-draw-indirect"}} [=feature=] is enabled, [=indirect draw parameters=]
-        may be repeated with 16 byte stride, allowing multiple draws per call to {{GPURenderEncoderBase/drawIndirect()}}.
-        The actual number of draws is the minimum of |maxDrawCount| and the [=indirect draw count=] (if given).
-
-        The <dfn dfn for=>indirect drawIndexed count</dfn> encoded in the |drawCountBuffer| must be a **32-bit unsigned
-        integer** giving the number of draws to issue from the |indirectBuffer|.
-
         <div algorithm="GPURenderEncoderBase.drawIndexedIndirect">
             **Called on:** {{GPURenderEncoderBase}} this.
 
             **Arguments:**
             <pre class=argumentdef for="GPURenderEncoderBase/drawIndexedIndirect(indirectBuffer, indirectOffset)">
                 |indirectBuffer|: Buffer containing the [=indirect drawIndexed parameters=].
                 |indirectOffset|: Offset in bytes into |indirectBuffer| where the drawing data begins.
-                |maxDrawCount|: Maxumum number of draws or exact number of draws if |drawCountBuffer| is `null`.
-                |drawCountBuffer|: Buffer containing the [=indirect drawIndexed count=].
-                |drawCountOffset|: Offset in bytes into |drawCountBuffer| where the [=indirect drawIndexed count=] is located.
             </pre>
 
             **Returns:** {{undefined}}
@@ -7335,22 +7318,139 @@ enum GPUStoreOp {
                         - |indirectOffset| + sizeof([=indirect drawIndexed parameters=]) &le;
                             |indirectBuffer|.{{GPUBuffer/[[size]]}}.
                         - |indirectOffset| is a multiple of 4.
-                        - |maxDrawCount| = 1, unless the {{GPUFeatureName/"multi-draw-indirect"}} [=feature=] is enabled.
+                    </div>
+                1. Add |indirectBuffer| to the [=usage scope=] as [=internal usage/input=].
+            </div>
+        </div>
+
+    : <dfn>multiDrawIndirect(indirectBuffer, indirectOffset, maxDrawCount, drawCountBuffer, drawCountOffset)</dfn>
+    ::
+        Draws primitives using an array of parameters read from a {{GPUBuffer}}.
+        See [[#rendering-operations]] for the detailed specification.
+
+        This method is defined if and only if the {{GPUFeatureName/"multi-draw-indirect"}} [=feature=] is enabled.
+
+        The <dfn dfn for=>indirect multiDraw parameters</dfn> encoded in the |indirectBuffer| must be zero or more
+        tightly packed blocks of **four 32-bit unsigned integer values (16 bytes total)**, given in the same
+        order as the arguments for {{GPURenderEncoderBase/draw()}}. For example:
+
+        <pre highlight="js">
+            let drawIndirectParameters = new Uint32Array(8);
+            // first draw
+            drawIndirectParameters[0] = vertexCount0;
+            drawIndirectParameters[1] = instanceCount0;
+            drawIndirectParameters[2] = firstVertex0;
+            drawIndirectParameters[3] = firstInstance0;
+            // second draw
+            drawIndirectParameters[4] = vertexCount1;
+            drawIndirectParameters[5] = instanceCount1;
+            drawIndirectParameters[6] = firstVertex1;
+            drawIndirectParameters[7] = firstInstance1;
+        </pre>
+
+        The <dfn dfn for=>indirect multiDraw count</dfn> encoded in the |drawCountBuffer| must be a **32-bit unsigned
+        integer** giving the number of draws to issue from the |indirectBuffer|.
+
+        <div algorithm="GPURenderEncoderBase.multiDrawIndirect">
+            **Called on:** {{GPURenderEncoderBase}} this.
+
+            **Arguments:**
+            <pre class=argumentdef for="GPURenderEncoderBase/multiDrawIndirect(indirectBuffer, indirectOffset, maxDrawCount, drawCountBuffer, drawCountOffset)">
+                |indirectBuffer|: Buffer containing the [=indirect multiDraw parameters=].
+                |indirectOffset|: Offset in bytes into |indirectBuffer| where the drawing data begins.
+                |maxDrawCount|: Maxumum number of draws or exact number of draws if |drawCountBuffer| is `null`.
+                |drawCountBuffer|: Buffer containing the [=indirect multiDraw count=].
+                |drawCountOffset|: Offset in bytes into |drawCountBuffer| where the [=indirect multiDraw count=] is located.
+            </pre>
+
+            **Returns:** {{undefined}}
+
+            Issue the following steps on the [=Device timeline=] of |this|.{{GPUObjectBase/[[device]]}}:
+            <div class=device-timeline>
+                1. If any of the following conditions are unsatisfied, make |this| [=invalid=] and stop.
+                    <div class=validusage>
+                        - It is [$valid to draw$] with |this|.
+                        - |indirectBuffer| is [$valid to use with$] |this|.
+                        - |indirectBuffer|.{{GPUBuffer/[[usage]]}} contains {{GPUBufferUsage/INDIRECT}}.
+                        - |indirectOffset| + sizeof([=indirect multiDraw parameters=]) &le;
+                            |indirectBuffer|.{{GPUBuffer/[[size]]}}.
+                        - |indirectOffset| is a multiple of 4.
+                        - |maxDrawCount| &le; limits.{{supported limits/maxMultiDrawIndirectCount}}.
                         - |drawCountBuffer| is `null`, unless the {{GPUFeatureName/"multi-draw-indirect"}} [=feature=] is enabled.
                         - |drawCountBuffer| is [$valid to use with$] |this|.
                         - |drawCountBuffer|.{{GPUBuffer/[[usage]]}} contains {{GPUBufferUsage/INDIRECT}}.
-                        - |drawCountOffset| + sizeof([=indirect drawIndexed count=]) &le;
+                        - |drawCountOffset| + sizeof([=indirect multiDraw count=]) &le;
                             |drawCountBuffer|.{{GPUBuffer/[[size]]}}.
                         - |drawCountOffset| is a multiple of 4.
                     </div>
                 1. Add |indirectBuffer| and |drawCountBuffer| (if given) to the [=usage scope=] as [=internal usage/input=].
             </div>
         </div>
-</dl>
 
-Note: The ability to set a `firstInstance` for indirect draw calls is initially disabled to expand
-the hardware that supports WebGPU. It is likely to be added as a feature in the future along with
-other new indirect drawing features.
+    : <dfn>multiDrawIndexedIndirect(indirectBuffer, indirectOffset, maxDrawCount, drawCountBuffer, drawCountOffset)</dfn>
+    ::
+        Draws indexed primitives using an array of parameters read from a {{GPUBuffer}}.
+        See [[#rendering-operations]] for the detailed specification.
+
+        The <dfn dfn for=>indirect multiDrawIndexed parameters</dfn> encoded in the |indirectBuffer| must be zero or more
+        tightly packed blocks of **five 32-bit unsigned integer values (20 bytes total)**, given in
+        the same order as the arguments for {{GPURenderEncoderBase/drawIndexed()}}. For example:
+
+        <pre highlight="js">
+            let drawIndexedIndirectParameters = new Uint32Array(10);
+            // first draw
+            drawIndexedIndirectParameters[0] = indexCount0;
+            drawIndexedIndirectParameters[1] = instanceCount0;
+            drawIndexedIndirectParameters[2] = firstIndex0;
+            drawIndexedIndirectParameters[3] = baseVertex0;
+            drawIndexedIndirectParameters[4] = firstInstance0;
+            // second draw
+            drawIndexedIndirectParameters[5] = indexCount1;
+            drawIndexedIndirectParameters[6] = instanceCount1;
+            drawIndexedIndirectParameters[7] = firstIndex1;
+            drawIndexedIndirectParameters[8] = baseVertex1;
+            drawIndexedIndirectParameters[9] = firstInstance1;
+        </pre>
+
+        The <dfn dfn for=>indirect multiDrawIndexed count</dfn> encoded in the |drawCountBuffer| must be a **32-bit unsigned
+        integer** giving the number of draws to issue from the |indirectBuffer|.
+
+        <div algorithm="GPURenderEncoderBase.multiDrawIndexedIndirect">
+            **Called on:** {{GPURenderEncoderBase}} this.
+
+            **Arguments:**
+            <pre class=argumentdef for="GPURenderEncoderBase/multiDrawIndexedIndirect(indirectBuffer, indirectOffset, maxDrawCount, drawCountBuffer, drawCountOffset)">
+                |indirectBuffer|: Buffer containing the [=indirect multiDrawIndexed parameters=].
+                |indirectOffset|: Offset in bytes into |indirectBuffer| where the drawing data begins.
+                |maxDrawCount|: Maxumum number of draws or exact number of draws if |drawCountBuffer| is `null`.
+                |drawCountBuffer|: Buffer containing the [=indirect multiDrawIndexed count=].
+                |drawCountOffset|: Offset in bytes into |drawCountBuffer| where the [=indirect multiDrawIndexed count=] is located.
+            </pre>
+
+            **Returns:** {{undefined}}
+
+            Issue the following steps on the [=Device timeline=] of |this|.{{GPUObjectBase/[[device]]}}:
+            <div class=device-timeline>
+                1. If any of the following conditions are unsatisfied, make |this| [=invalid=] and stop.
+                    <div class=validusage>
+                        - It is [$valid to draw indexed$] with |this|.
+                        - |indirectBuffer| is [$valid to use with$] |this|.
+                        - |indirectBuffer|.{{GPUBuffer/[[usage]]}} contains {{GPUBufferUsage/INDIRECT}}.
+                        - |indirectOffset| + sizeof([=indirect multiDrawIndexed parameters=]) &le;
+                            |indirectBuffer|.{{GPUBuffer/[[size]]}}.
+                        - |indirectOffset| is a multiple of 4.
+                        - |maxDrawCount| &le; limits.{{supported limits/maxMultiDrawIndirectCount}}.
+                        - |drawCountBuffer| is `null`, unless the {{GPUFeatureName/"multi-draw-indirect"}} [=feature=] is enabled.
+                        - |drawCountBuffer| is [$valid to use with$] |this|.
+                        - |drawCountBuffer|.{{GPUBuffer/[[usage]]}} contains {{GPUBufferUsage/INDIRECT}}.
+                        - |drawCountOffset| + sizeof([=indirect multiDrawIndexed count=]) &le;
+                            |drawCountBuffer|.{{GPUBuffer/[[size]]}}.
+                        - |drawCountOffset| is a multiple of 4.
+                    </div>
+                1. Add |indirectBuffer| and |drawCountBuffer| (if given) to the [=usage scope=] as [=internal usage/input=].
+            </div>
+        </div>
+</dl>
 
 <div algorithm>
     To determine if it's <dfn abstract-op>valid to draw</dfn> with {{GPURenderEncoderBase}} |encoder|
@@ -9292,26 +9392,20 @@ The following enums are supported if and only if the {{GPUFeatureName/"depth32fl
 
 ## <dfn dfn-type=enum-value dfn-for=GPUFeatureName>multi-draw-indirect</dfn> ## {#multi-draw-indirect}
 
-Allows {{GPURenderEncoderBase/drawIndirect()}} and {{GPURenderEncoderBase/drawIndexedIndirect()}} to
-operate on arrays of [=indirect draw parameters=] and [=indirect drawIndexed parameters=] respectively
-and allows `firstInstance` to be greater than 0.
+Allows the use of the {{GPURenderEncoderBase/multiDrawIndirect()}} and
+{{GPURenderEncoderBase/multiDrawIndexedIndirect()}} methods and removes the zero value restriction on
+`firstInstance` in [=indirect draw parameters=] and [=indirect drawIndexed parameters=].
 
-**Feature Function Arguments**
+**Feature Methods**
 
-The following optional function arguments are supported if and only if the
-{{GPUFeatureName/"multi-draw-indirect"}} [=feature=] is enabled.
+The following methods are supported if and only if the {{GPUFeatureName/"multi-draw-indirect"}}
+[=feature=] is enabled.
 
 <dl>
-    : {{GPURenderEncoderBase/drawIndirect()}}
-    ::
-        * <l>{{GPURenderEncoderBase/drawIndirect(indirectBuffer, indirectOffset)/maxDrawCount}}</l>
-        * <l>{{GPURenderEncoderBase/drawIndirect(indirectBuffer, indirectOffset)/drawCountBuffer}}</l>
-        * <l>{{GPURenderEncoderBase/drawIndirect(indirectBuffer, indirectOffset)/drawCountOffset}}</l>
-    : {{GPURenderEncoderBase/drawIndexedIndirect()}}
+    : {{GPURenderEncoderBase}}
     ::
-        * <l>{{GPURenderEncoderBase/drawIndexedIndirect(indirectBuffer, indirectOffset)/maxDrawCount}}</l>
-        * <l>{{GPURenderEncoderBase/drawIndexedIndirect(indirectBuffer, indirectOffset)/drawCountBuffer}}</l>
-        * <l>{{GPURenderEncoderBase/drawIndexedIndirect(indirectBuffer, indirectOffset)/drawCountOffset}}</l>
+        * {{GPURenderEncoderBase/multiDrawIndirect()}}
+        * {{GPURenderEncoderBase/multiDrawIndexedIndirect()}}
 </dl>
 
 
