chore: Rename 'dispatch' to 'dispatchThreads' (#1828)

Author: iwoplaza

apps/typegpu-docs/src/content/docs/fundamentals/utils.mdx

@@ -6,7 +6,7 @@ description: A list of various utilities provided by TypeGPU.
 ## *prepareDispatch*
 
 The `prepareDispatch` function streamlines running simple computations on the GPU.
-Under the hood, it wraps the callback in a `TgpuFn`, creates a compute pipeline, and returns an object with dispatch method that executes the pipeline.
+Under the hood, it wraps the callback in a `TgpuFn`, creates a compute pipeline, and returns an object with a `dispatchThreads` method that executes the pipeline.
 Since the pipeline is reused, there’s no additional overhead for subsequent calls.
 
 ```ts twoslash
@@ -21,9 +21,9 @@ const doubleUp = root['~unstable'].prepareDispatch((x) => {
   data.$[x] *= 2;
 });
 
-doubleUp.dispatch(8);
-doubleUp.dispatch(8);
-doubleUp.dispatch(4);
+doubleUp.dispatchThreads(8);
+doubleUp.dispatchThreads(8);
+doubleUp.dispatchThreads(4);
 
 // the command encoder will queue the read after `doubleUp`
 console.log(await data.read()); // [0, 8, 16, 24, 16, 20, 24, 28]
@@ -55,7 +55,7 @@ root['~unstable'].prepareDispatch((x, y) => {
   'use gpu';
   randf.seed2(d.vec2f(x, y).div(1024));
   waterLevelMutable.$[x][y] = 10 + randf.sample();
-}).dispatch(1024, 512);
+}).dispatchThreads(1024, 512);
 // callback will be called for x in range 0..1023 and y in range 0..511
 
 // (optional) read values in JS
@@ -89,8 +89,8 @@ const test = root['~unstable'].prepareDispatch((x) => {
   layout.$.buffer[x] *= 2;
 });
 
-test.with(bindGroup1).dispatch(3);
-test.with(bindGroup2).dispatch(4);
+test.with(bindGroup1).dispatchThreads(3);
+test.with(bindGroup2).dispatchThreads(4);
 
 console.log(await buffer1.read()); // [2, 4, 6];
 console.log(await buffer2.read()); // [4, 8, 16, 32];
@@ -135,8 +135,8 @@ const compute = root['~unstable'].prepareDispatch(() => {
   console.log('Call number', callCountMutable.$);
 });
 
-compute.dispatch();
-compute.dispatch();
+compute.dispatchThreads();
+compute.dispatchThreads();
 
 // Eventually...
 // "[GPU] Call number 1"

apps/typegpu-docs/src/examples/rendering/3d-fish/index.ts

@@ -124,7 +124,7 @@ const randomizeFishPositionsOnGPU = root['~unstable'].prepareDispatch((x) => {
 
 const randomizeFishPositions = () => {
   seedUniform.write((performance.now() % 10000) / 10000);
-  randomizeFishPositionsOnGPU.dispatch(p.fishAmount);
+  randomizeFishPositionsOnGPU.dispatchThreads(p.fishAmount);
   enqueuePresetChanges();
 };
 
@@ -256,7 +256,7 @@ function frame(timestamp: DOMHighResTimeStamp) {
 
   simulateAction
     .with(computeBindGroups[odd ? 1 : 0])
-    .dispatch(p.fishAmount);
+    .dispatchThreads(p.fishAmount);
 
   renderPipeline
     .withColorAttachment({

apps/typegpu-docs/src/examples/simple/increment/index.ts

@@ -13,7 +13,7 @@ const gpuIncrement = root['~unstable'].prepareDispatch(() => {
 
 async function increment() {
   // Dispatch and read the result
-  gpuIncrement.dispatch();
+  gpuIncrement.dispatchThreads();
   return await counter.read();
 }
 

apps/typegpu-docs/src/examples/simulation/boids-next/index.ts

@@ -270,7 +270,7 @@ function frame() {
 
   simulateAction
     .with(computeBindGroups[even ? 0 : 1])
-    .dispatch(triangleAmount);
+    .dispatchThreads(triangleAmount);
 
   renderPipeline
     .withColorAttachment({

apps/typegpu-docs/src/examples/simulation/fluid-double-buffering/index.ts

@@ -496,17 +496,17 @@ function makePipelines(
 
   return {
     init() {
-      initWorldAction.dispatch(gridSize, gridSize);
+      initWorldAction.dispatchThreads(gridSize, gridSize);
     },
 
     applyMovedObstacles(bufferData: d.Infer<BoxObstacle>[]) {
       obstacles.write(bufferData);
-      moveObstaclesAction.dispatch();
+      moveObstaclesAction.dispatchThreads();
       prevObstacles.write(bufferData);
     },
 
     compute() {
-      simulateAction.dispatch(gridSize, gridSize);
+      simulateAction.dispatchThreads(gridSize, gridSize);
     },
 
     render() {

apps/typegpu-docs/src/examples/simulation/slime-mold-3d/index.ts

@@ -113,7 +113,7 @@ root['~unstable'].prepareDispatch((x) => {
   const center = resolution.div(2);
   const dir = std.normalize(center.sub(pos));
   agentsData.$[x] = Agent({ position: pos, direction: dir });
-}).dispatch(NUM_AGENTS);
+}).dispatchThreads(NUM_AGENTS);
 
 const params = root.createUniform(Params, {
   deltaTime: 0,

apps/typegpu-docs/src/examples/tests/dispatch/index.ts

@@ -16,7 +16,7 @@ async function test0d(): Promise<boolean> {
   root['~unstable'].prepareDispatch(() => {
     'use gpu';
     mutable.$ = 126;
-  }).dispatch();
+  }).dispatchThreads();
   const filled = await mutable.read();
   return isEqual(filled, 126);
 }
@@ -27,7 +27,7 @@ async function test1d(): Promise<boolean> {
   root['~unstable'].prepareDispatch((x) => {
     'use gpu';
     mutable.$[x] = x;
-  }).dispatch(...size);
+  }).dispatchThreads(...size);
   const filled = await mutable.read();
   return isEqual(filled, [0, 1, 2, 3, 4, 5, 6]);
 }
@@ -40,7 +40,7 @@ async function test2d(): Promise<boolean> {
   root['~unstable'].prepareDispatch((x, y) => {
     'use gpu';
     mutable.$[x][y] = d.vec2u(x, y);
-  }).dispatch(...size);
+  }).dispatchThreads(...size);
   const filled = await mutable.read();
   return isEqual(filled, [
     [d.vec2u(0, 0), d.vec2u(0, 1), d.vec2u(0, 2)],
@@ -59,7 +59,7 @@ async function test3d(): Promise<boolean> {
   root['~unstable'].prepareDispatch((x, y, z) => {
     'use gpu';
     mutable.$[x][y][z] = d.vec3u(x, y, z);
-  }).dispatch(...size);
+  }).dispatchThreads(...size);
   const filled = await mutable.read();
   return isEqual(filled, [
     [[d.vec3u(0, 0, 0), d.vec3u(0, 0, 1)]],
@@ -72,7 +72,7 @@ async function testWorkgroupSize(): Promise<boolean> {
   root['~unstable'].prepareDispatch((x, y, z) => {
     'use gpu';
     std.atomicAdd(mutable.$, 1);
-  }).dispatch(4, 3, 2);
+  }).dispatchThreads(4, 3, 2);
   const filled = await mutable.read();
   return isEqual(filled, 4 * 3 * 2);
 }
@@ -85,9 +85,9 @@ async function testMultipleDispatches(): Promise<boolean> {
     'use gpu';
     mutable.$[x] *= 2;
   });
-  test.dispatch(6);
-  test.dispatch(2);
-  test.dispatch(4);
+  test.dispatchThreads(6);
+  test.dispatchThreads(2);
+  test.dispatchThreads(4);
   const filled = await mutable.read();
   return isEqual(filled, [0 * 8, 1 * 8, 2 * 4, 3 * 4, 4 * 2, 5 * 2, 6 * 1]);
 }
@@ -114,8 +114,8 @@ async function testDifferentBindGroups(): Promise<boolean> {
     }
   });
 
-  test.with(bindGroup1).dispatch();
-  test.with(bindGroup2).dispatch();
+  test.with(bindGroup1).dispatchThreads();
+  test.with(bindGroup2).dispatchThreads();
 
   const filled1 = await buffer1.read();
   const filled2 = await buffer2.read();
@@ -131,8 +131,8 @@ async function testSlots(): Promise<boolean> {
     result.$ += valueSlot.$;
   };
 
-  root['~unstable'].prepareDispatch(main).dispatch(); // add 1
-  root['~unstable'].with(valueSlot, 3).prepareDispatch(main).dispatch(); // add 3
+  root['~unstable'].prepareDispatch(main).dispatchThreads(); // add 1
+  root['~unstable'].with(valueSlot, 3).prepareDispatch(main).dispatchThreads(); // add 3
 
   return await result.read() === 4;
 }

apps/typegpu-docs/src/examples/tests/log-test/index.ts

@@ -53,29 +53,29 @@ export const controls = {
       root['~unstable'].prepareDispatch(() => {
         'use gpu';
         console.log(d.u32(321));
-      }).dispatch(),
+      }).dispatchThreads(),
   },
   'Multiple arguments': {
     onButtonClick: () =>
       root['~unstable'].prepareDispatch(() => {
         'use gpu';
         console.log(1, d.vec3u(2, 3, 4), 5, 6);
-      }).dispatch(),
+      }).dispatchThreads(),
   },
   'String literals': {
     onButtonClick: () =>
       root['~unstable'].prepareDispatch(() => {
         'use gpu';
         console.log(2, 'plus', 3, 'equals', 5);
-      }).dispatch(),
+      }).dispatchThreads(),
   },
   'Two logs': {
     onButtonClick: () =>
       root['~unstable'].prepareDispatch(() => {
         'use gpu';
         console.log('First log.');
         console.log('Second log.');
-      }).dispatch(),
+      }).dispatchThreads(),
   },
   'Different types': {
     onButtonClick: () =>
@@ -119,7 +119,7 @@ export const controls = {
         } else {
           console.log("The 'shader-f16' flag is not enabled.");
         }
-      }).dispatch(),
+      }).dispatchThreads(),
   },
   'Compound types': {
     onButtonClick: () => {
@@ -144,15 +144,15 @@ export const controls = {
 
         const complexArray = ComplexArray([[3, 4], [5, 6], [7, 8]]);
         console.log(complexArray);
-      }).dispatch();
+      }).dispatchThreads();
     },
   },
   'Two threads': {
     onButtonClick: () =>
       root['~unstable'].prepareDispatch((x) => {
         'use gpu';
         console.log('Log from thread', x);
-      }).dispatch(2),
+      }).dispatchThreads(2),
   },
   '100 dispatches': {
     onButtonClick: async () => {
@@ -163,7 +163,7 @@ export const controls = {
       });
       for (let i = 0; i < 100; i++) {
         indexUniform.write(i);
-        test.dispatch();
+        test.dispatchThreads();
       }
     },
   },
@@ -177,9 +177,9 @@ export const controls = {
         }
       });
       logCountUniform.write(3);
-      test.dispatch();
+      test.dispatchThreads();
       logCountUniform.write(1);
-      test.dispatch();
+      test.dispatchThreads();
     },
   },
   'Render pipeline': {
@@ -235,7 +235,7 @@ export const controls = {
         console.log('Log 1 from thread', x);
         console.log('Log 2 from thread', x);
         console.log('Log 3 from thread', x);
-      }).dispatch(16),
+      }).dispatchThreads(16),
   },
 };
 

packages/typegpu/src/core/root/init.ts

@@ -177,7 +177,7 @@ export class PreparedDispatchImpl<TArgs extends number[]>
    * Unlike `TgpuComputePipeline.dispatchWorkgroups()`,
    * this method takes in the number of threads to run in each dimension.
    */
-  dispatch(...threads: TArgs): void {
+  dispatchThreads(...threads: TArgs): void {
     const sanitizedSize = toVec3(threads);
     const workgroupCount = ceil(
       vec3f(sanitizedSize).div(vec3f(this.#workgroupSize)),

packages/typegpu/src/core/root/rootTypes.ts

@@ -90,7 +90,7 @@ export interface PreparedDispatch<TArgs extends number[]> {
    * Unlike `TgpuComputePipeline.dispatchWorkgroups()`,
    * this method takes in the number of threads to run in each dimension.
    */
-  dispatch(...args: TArgs): void;
+  dispatchThreads(...args: TArgs): void;
 }
 
 export interface WithCompute {
@@ -220,7 +220,7 @@ export interface WithBinding {
    *   console.log('Hello, GPU!');
    * });
    *
-   * action.dispatch();
+   * action.dispatchThreads();
    * ```
    *
    * @example
@@ -232,7 +232,7 @@ export interface WithBinding {
    *   console.log('I am the', x, 'thread');
    * });
    *
-   * action.dispatch(12); // executing 12 threads
+   * action.dispatchThreads(12); // executing 12 threads
    * ```
    */
   prepareDispatch<TArgs extends number[]>(