refactor!: subvert-rename dispatch* to dispatchWorkGroups*

CHANGELOG.md

@@ -82,6 +82,7 @@ Bottom level categories:
 - Zero-size `Queue::write_buffer` now returns an error if the offset is invalid or the buffer lacks `COPY_DST`. By @39ali in [#9374](https://github.com/gfx-rs/wgpu/pull/9374).
 - `Buffer::get_mapped_range` and variants now return `Result<_, MapRangeError>>` instead of panicking, in line with WebGPU spec. By @atlv24 in [#9281](https://github.com/gfx-rs/wgpu/pull/9281).
 - Passthrough shaders now require a list of entry points when being created. by @inner-daemons in [#9064](https://github.com/gfx-rs/wgpu/pull/9064).
+- BREAKING: The `dispatch` and `dispatch_indirect` methods on pass and bundle encoders have been renamed to `dispatch_workgroups` and `dispatch_workgroups_indirect`, respectively, to match the WebGPU spec. By @ErichDonGubler in [#9362](https://github.com/gfx-rs/wgpu/pull/9362).
 
 #### Validation
 

player/src/lib.rs

@@ -1056,8 +1056,8 @@ impl Player {
                 size_bytes,
                 values_offset,
             },
-            C::Dispatch(groups) => C::Dispatch(groups),
-            C::DispatchIndirect { buffer, offset } => C::DispatchIndirect {
+            C::DispatchWorkgroups(groups) => C::DispatchWorkgroups(groups),
+            C::DispatchWorkgroupsIndirect { buffer, offset } => C::DispatchWorkgroupsIndirect {
                 buffer: self.resolve_buffer_id(buffer),
                 offset,
             },

player/tests/player/data/pipeline-statistics-query.ron

@@ -62,7 +62,7 @@
                             query_set: PointerId(0x10),
                             query_index: 0,
                         ),
-                        Dispatch((2, 3, 7,)),
+                        DispatchWorkgroups((2, 3, 7,)),
                         EndPipelineStatisticsQuery,
                     ],
                     dynamic_offsets: [],

player/tests/player/data/zero-init-buffer.ron

@@ -149,7 +149,7 @@
                             num_dynamic_offsets: 0,
                             bind_group: Some(PointerId(0x10)),
                         ),
-                        Dispatch((4, 1, 1)),
+                        DispatchWorkgroups((4, 1, 1)),
                     ],
                     dynamic_offsets: [],
                     string_data: [],

player/tests/player/data/zero-init-texture-binding.ron

@@ -152,7 +152,7 @@
                             num_dynamic_offsets: 0,
                             bind_group: Some(PointerId(0x10)),
                         ),
-                        Dispatch((4, 1, 1)),
+                        DispatchWorkgroups((4, 1, 1)),
                     ],
                     dynamic_offsets: [],
                     string_data: [],

wgpu-core/src/command/compute.rs

@@ -742,13 +742,14 @@ pub(super) fn encode_compute_pass(
                 )
                 .map_pass_err(scope)?;
             }
-            ArcComputeCommand::Dispatch(groups) => {
+            ArcComputeCommand::DispatchWorkgroups(groups) => {
                 let scope = PassErrorScope::Dispatch { indirect: false };
-                dispatch(&mut state, groups).map_pass_err(scope)?;
+                dispatch_workgroups(&mut state, groups).map_pass_err(scope)?;
             }
-            ArcComputeCommand::DispatchIndirect { buffer, offset } => {
+            ArcComputeCommand::DispatchWorkgroupsIndirect { buffer, offset } => {
                 let scope = PassErrorScope::Dispatch { indirect: true };
-                dispatch_indirect(&mut state, device, buffer, offset).map_pass_err(scope)?;
+                dispatch_workgroups_indirect(&mut state, device, buffer, offset)
+                    .map_pass_err(scope)?;
             }
             ArcComputeCommand::PushDebugGroup { color: _, len } => {
                 pass::push_debug_group(&mut state.pass, &base.string_data, len);
@@ -907,7 +908,7 @@ fn set_pipeline(
     )
 }
 
-fn dispatch(state: &mut State, groups: [u32; 3]) -> Result<(), ComputePassErrorInner> {
+fn dispatch_workgroups(state: &mut State, groups: [u32; 3]) -> Result<(), ComputePassErrorInner> {
     api_log!("ComputePass::dispatch {groups:?}");
 
     state.is_ready()?;
@@ -931,12 +932,12 @@ fn dispatch(state: &mut State, groups: [u32; 3]) -> Result<(), ComputePassErrorI
     }
 
     unsafe {
-        state.pass.base.raw_encoder.dispatch(groups);
+        state.pass.base.raw_encoder.dispatch_workgroups(groups);
     }
     Ok(())
 }
 
-fn dispatch_indirect(
+fn dispatch_workgroups_indirect(
     state: &mut State,
     device: &Arc<Device>,
     buffer: Arc<Buffer>,
@@ -1054,7 +1055,7 @@ fn dispatch_indirect(
         }
 
         unsafe {
-            state.pass.base.raw_encoder.dispatch([1, 1, 1]);
+            state.pass.base.raw_encoder.dispatch_workgroups([1, 1, 1]);
         }
 
         // reset state
@@ -1112,7 +1113,7 @@ fn dispatch_indirect(
                 .pass
                 .base
                 .raw_encoder
-                .dispatch_indirect(params.dst_buffer, 0);
+                .dispatch_workgroups_indirect(params.dst_buffer, 0);
         }
     } else {
         state.flush_bindings(Some(&buffer), true)?;
@@ -1123,7 +1124,7 @@ fn dispatch_indirect(
                 .pass
                 .base
                 .raw_encoder
-                .dispatch_indirect(buf_raw, offset);
+                .dispatch_workgroups_indirect(buf_raw, offset);
         }
     }
 
@@ -1268,7 +1269,9 @@ impl Global {
 
         pass_base!(pass, scope)
             .commands
-            .push(ArcComputeCommand::Dispatch([groups_x, groups_y, groups_z]));
+            .push(ArcComputeCommand::DispatchWorkgroups([
+                groups_x, groups_y, groups_z,
+            ]));
 
         Ok(())
     }
@@ -1286,7 +1289,7 @@ impl Global {
         let buffer = pass_try!(base, scope, hub.buffers.get(buffer_id).get());
 
         base.commands
-            .push(ArcComputeCommand::DispatchIndirect { buffer, offset });
+            .push(ArcComputeCommand::DispatchWorkgroupsIndirect { buffer, offset });
 
         Ok(())
     }

wgpu-core/src/command/compute_command.rs

@@ -36,9 +36,9 @@ pub enum ComputeCommand<R: ReferenceType> {
         values_offset: u32,
     },
 
-    Dispatch([u32; 3]),
+    DispatchWorkgroups([u32; 3]),
 
-    DispatchIndirect {
+    DispatchWorkgroupsIndirect {
         buffer: R::Buffer,
         offset: wgt::BufferAddress,
     },

wgpu-core/src/device/trace/record.rs

@@ -469,8 +469,8 @@ impl IntoTrace for ArcComputeCommand {
                 size_bytes,
                 values_offset,
             },
-            C::Dispatch(groups) => C::Dispatch(groups),
-            C::DispatchIndirect { buffer, offset } => C::DispatchIndirect {
+            C::DispatchWorkgroups(groups) => C::DispatchWorkgroups(groups),
+            C::DispatchWorkgroupsIndirect { buffer, offset } => C::DispatchWorkgroupsIndirect {
                 buffer: buffer.into_trace(),
                 offset,
             },

wgpu-core/src/indirect_validation/draw.rs

@@ -447,7 +447,7 @@ impl Draw {
             }
 
             unsafe {
-                encoder.dispatch([(batch.entries.len() as u32).div_ceil(64), 1, 1]);
+                encoder.dispatch_workgroups([(batch.entries.len() as u32).div_ceil(64), 1, 1]);
             }
         }
 

wgpu-core/src/timestamp_normalization/mod.rs

@@ -353,7 +353,7 @@ impl TimestampNormalizer {
                 0,
                 &[buffer_offset_timestamps, total_timestamps],
             );
-            encoder.dispatch([needed_workgroups, 1, 1]);
+            encoder.dispatch_workgroups([needed_workgroups, 1, 1]);
             encoder.end_compute_pass();
         }
     }

wgpu-hal/examples/ray-traced-triangle/main.rs

@@ -981,7 +981,7 @@ impl<A: hal::Api> Example<A> {
             ctx.encoder.set_compute_pipeline(&self.pipeline);
             ctx.encoder
                 .set_bind_group(&self.pipeline_layout, 0, &self.bind_group, &[]);
-            ctx.encoder.dispatch([512 / 8, 512 / 8, 1]);
+            ctx.encoder.dispatch_workgroups([512 / 8, 512 / 8, 1]);
         }
 
         ctx.frames_recorded += 1;

wgpu-hal/src/dx12/command.rs

@@ -1589,12 +1589,16 @@ impl crate::CommandEncoder for super::CommandEncoder {
         unsafe { list.SetPipelineState(&pipeline.raw) }
     }
 
-    unsafe fn dispatch(&mut self, count @ [x, y, z]: [u32; 3]) {
+    unsafe fn dispatch_workgroups(&mut self, count @ [x, y, z]: [u32; 3]) {
         self.prepare_dispatch(count);
         unsafe { self.list.as_ref().unwrap().Dispatch(x, y, z) }
     }
 
-    unsafe fn dispatch_indirect(&mut self, buffer: &super::Buffer, offset: wgt::BufferAddress) {
+    unsafe fn dispatch_workgroups_indirect(
+        &mut self,
+        buffer: &super::Buffer,
+        offset: wgt::BufferAddress,
+    ) {
         if self
             .pass
             .layout

wgpu-hal/src/dynamic/command.rs

@@ -183,8 +183,12 @@ pub trait DynCommandEncoder: DynResource + core::fmt::Debug {
 
     unsafe fn set_compute_pipeline(&mut self, pipeline: &dyn DynComputePipeline);
 
-    unsafe fn dispatch(&mut self, count: [u32; 3]);
-    unsafe fn dispatch_indirect(&mut self, buffer: &dyn DynBuffer, offset: wgt::BufferAddress);
+    unsafe fn dispatch_workgroups(&mut self, count: [u32; 3]);
+    unsafe fn dispatch_workgroups_indirect(
+        &mut self,
+        buffer: &dyn DynBuffer,
+        offset: wgt::BufferAddress,
+    );
 
     unsafe fn build_acceleration_structures<'a>(
         &mut self,
@@ -606,13 +610,17 @@ impl<C: CommandEncoder + DynResource> DynCommandEncoder for C {
         unsafe { C::set_compute_pipeline(self, pipeline) };
     }
 
-    unsafe fn dispatch(&mut self, count: [u32; 3]) {
-        unsafe { C::dispatch(self, count) };
+    unsafe fn dispatch_workgroups(&mut self, count: [u32; 3]) {
+        unsafe { C::dispatch_workgroups(self, count) };
     }
 
-    unsafe fn dispatch_indirect(&mut self, buffer: &dyn DynBuffer, offset: wgt::BufferAddress) {
+    unsafe fn dispatch_workgroups_indirect(
+        &mut self,
+        buffer: &dyn DynBuffer,
+        offset: wgt::BufferAddress,
+    ) {
         let buffer = buffer.expect_downcast_ref();
-        unsafe { C::dispatch_indirect(self, buffer, offset) };
+        unsafe { C::dispatch_workgroups_indirect(self, buffer, offset) };
     }
 
     unsafe fn set_render_pipeline(&mut self, pipeline: &dyn DynRenderPipeline) {

wgpu-hal/src/gles/command.rs

@@ -1245,14 +1245,18 @@ impl crate::CommandEncoder for super::CommandEncoder {
         self.set_pipeline_inner(&pipeline.inner);
     }
 
-    unsafe fn dispatch(&mut self, count: [u32; 3]) {
+    unsafe fn dispatch_workgroups(&mut self, count: [u32; 3]) {
         // Empty dispatches are invalid in OpenGL, but valid in WebGPU.
         if count.contains(&0) {
             return;
         }
         self.cmd_buffer.commands.push(C::Dispatch(count));
     }
-    unsafe fn dispatch_indirect(&mut self, buffer: &super::Buffer, offset: wgt::BufferAddress) {
+    unsafe fn dispatch_workgroups_indirect(
+        &mut self,
+        buffer: &super::Buffer,
+        offset: wgt::BufferAddress,
+    ) {
         self.cmd_buffer.commands.push(C::DispatchIndirect {
             indirect_buf: buffer.raw.unwrap(),
             indirect_offset: offset,

wgpu-hal/src/lib.rs

@@ -1689,8 +1689,8 @@ pub trait CommandEncoder: WasmNotSendSync + fmt::Debug {
 
     unsafe fn set_compute_pipeline(&mut self, pipeline: &<Self::A as Api>::ComputePipeline);
 
-    unsafe fn dispatch(&mut self, count: [u32; 3]);
-    unsafe fn dispatch_indirect(
+    unsafe fn dispatch_workgroups(&mut self, count: [u32; 3]);
+    unsafe fn dispatch_workgroups_indirect(
         &mut self,
         buffer: &<Self::A as Api>::Buffer,
         offset: wgt::BufferAddress,

wgpu-hal/src/metal/command.rs

@@ -1770,7 +1770,7 @@ impl crate::CommandEncoder for super::CommandEncoder {
         }
     }
 
-    unsafe fn dispatch(&mut self, count: [u32; 3]) {
+    unsafe fn dispatch_workgroups(&mut self, count: [u32; 3]) {
         if count[0] > 0 && count[1] > 0 && count[2] > 0 {
             let encoder = self.state.compute.as_ref().unwrap();
             let raw_count = MTLSize {
@@ -1785,7 +1785,11 @@ impl crate::CommandEncoder for super::CommandEncoder {
         }
     }
 
-    unsafe fn dispatch_indirect(&mut self, buffer: &super::Buffer, offset: wgt::BufferAddress) {
+    unsafe fn dispatch_workgroups_indirect(
+        &mut self,
+        buffer: &super::Buffer,
+        offset: wgt::BufferAddress,
+    ) {
         let encoder = self.state.compute.as_ref().unwrap();
         unsafe {
             encoder

wgpu-hal/src/noop/command.rs

@@ -267,8 +267,9 @@ impl crate::CommandEncoder for CommandBuffer {
 
     unsafe fn set_compute_pipeline(&mut self, pipeline: &Resource) {}
 
-    unsafe fn dispatch(&mut self, count: [u32; 3]) {}
-    unsafe fn dispatch_indirect(&mut self, buffer: &Buffer, offset: wgt::BufferAddress) {}
+    unsafe fn dispatch_workgroups(&mut self, count: [u32; 3]) {}
+    unsafe fn dispatch_workgroups_indirect(&mut self, buffer: &Buffer, offset: wgt::BufferAddress) {
+    }
 
     unsafe fn build_acceleration_structures<'a, T>(
         &mut self,

wgpu-hal/src/vulkan/command.rs

@@ -1340,14 +1340,18 @@ impl crate::CommandEncoder for super::CommandEncoder {
         };
     }
 
-    unsafe fn dispatch(&mut self, count: [u32; 3]) {
+    unsafe fn dispatch_workgroups(&mut self, count: [u32; 3]) {
         unsafe {
             self.device
                 .raw
                 .cmd_dispatch(self.active, count[0], count[1], count[2])
         };
     }
-    unsafe fn dispatch_indirect(&mut self, buffer: &super::Buffer, offset: wgt::BufferAddress) {
+    unsafe fn dispatch_workgroups_indirect(
+        &mut self,
+        buffer: &super::Buffer,
+        offset: wgt::BufferAddress,
+    ) {
         unsafe {
             self.device
                 .raw

wgpu-types/src/limits.rs

@@ -231,7 +231,7 @@ pub struct Limits {
     /// The maximum value of the `workgroup_size` Z dimension for a compute stage `ShaderModule` entry-point.
     /// Defaults to 64. Higher is "better".
     pub max_compute_workgroup_size_z: u32,
-    /// The maximum value for each dimension of a `ComputePass::dispatch(x, y, z)` operation.
+    /// The maximum value for each dimension of a `ComputePass::dispatch_workgroups(x, y, z)` operation.
     /// Defaults to 65535. Higher is "better".
     pub max_compute_workgroups_per_dimension: u32,
 

wgpu-types/src/render.rs

@@ -977,7 +977,7 @@ impl DrawIndexedIndirectArgs {
     }
 }
 
-/// Argument buffer layout for `dispatch_indirect` commands.
+/// Argument buffer layout for `dispatch_workgroups_indirect` commands.
 #[repr(C)]
 #[derive(Copy, Clone, Debug, Default, Pod, Zeroable)]
 pub struct DispatchIndirectArgs {

wgpu/src/api/compute_pass.rs

@@ -49,7 +49,7 @@ impl ComputePass<'_> {
     }
 
     /// Sets the active bind group for a given bind group index. The bind group layout
-    /// in the active pipeline when the `dispatch()` function is called must match the layout of this bind group.
+    /// in the active pipeline when the `dispatch_workgroups()` function is called must match the layout of this bind group.
     ///
     /// If the bind group have dynamic offsets, provide them in the binding order.
     /// These offsets have to be aligned to [`Limits::min_uniform_buffer_offset_alignment`]