feat: Change 'kernel' to 'use gpu' (#1798)

Author: iwoplaza

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

@@ -8,7 +8,7 @@ This feature is under heavy development and is yet to reach stability.
 :::
 
 **TGSL (TypeGPU Shading Language)** is a subset of JavaScript used to define functions that run on the GPU via TypeGPU.
-It works by transpiling JavaScript into a compact AST format, called [tinyest](https://www.npmjs.com/package/tinyest), 
+It works by transpiling JavaScript into a compact AST format, called [tinyest](https://www.npmjs.com/package/tinyest),
 which is then used to generate equivalent WGSL.
 
 You can check the current state of supported JavaScript syntax in the [tinyest-for-wgsl repository](https://github.com/software-mansion/TypeGPU/blob/release/packages/tinyest-for-wgsl/src/parsers.ts).
@@ -91,19 +91,19 @@ When using TGSL, you don't need to explicitly declare function externals with th
 The [TypeGPU Build Plugin](/TypeGPU/tooling/unplugin-typegpu/) automatically extracts all external definitions from the function's AST.
 :::
 
-Sometimes, we are unable to recognize functions that are supposed to be TGSL. For that case, we have a *"kernel"* directive.
+Sometimes, we are unable to recognize functions that are supposed to be TGSL. For that case, we have a *"use gpu"* directive.
 
 ```ts
 const patternFn = tgpu.fn([d.vec2f], d.f32);
 
 const patternCheckers = patternFn((uv) => {
-  'kernel';
+  'use gpu';
   const suv = floor(mul(20, uv));
   return suv.x + suv.y - 2 * floor((suv.x + suv.y) * 0.5);
 });
 
 const patternSolid = patternFn(() => {
-  'kernel';
+  'use gpu';
   return 1;
 });
 ```
@@ -112,7 +112,7 @@ const patternSolid = patternFn(() => {
 
 TGSL-implemented functions can be invoked on the CPU,
 as along as they do not use any GPU-exclusive functionalities,
-like buffers or textures (regardless of whether they are marked as *"kernel"* or not).
+like buffers or textures (regardless of whether they are marked with *"use gpu"* or not).
 
 Keep in mind that you cannot execute entry-point functions in JavaScript.
 
@@ -149,10 +149,10 @@ const bgColor = root.createUniform(d.vec4f, d.vec4f(0.114, 0.447, 0.941, 1));
 const fragmentTgsl = tgpu['~unstable'].fragmentFn({ out: d.vec4f })(() => {
   return bgColor.$;
 //               ^?
-}); 
+});
 
-const fragmentWgsl = tgpu['~unstable'].fragmentFn({ out: d.vec4f })`{ 
-  return bgColor; 
+const fragmentWgsl = tgpu['~unstable'].fragmentFn({ out: d.vec4f })`{
+  return bgColor;
 }
 `.$uses({ bgColor });
 ```
@@ -176,12 +176,12 @@ const fn = tgpu.fn([d.ptrFn(d.vec3f)], d.vec3f)((ptr) => {
   ptr.x += 1;
 //^?
   return ptr;
-}); 
+});
 ```
 
 * **When to use TGSL instead of WGSL** --
 Writing the code using TGSL has a few significant advantages.
-It allows defining utils only once and using them both as a kernel and host functions,
+It allows defining utils only once and using them both as GPU and CPU functions,
 as well as enables complete syntax highlighting and autocomplete in TypeGPU function definitions, leading to a better developer UX.
 However, it sometimes might be better to choose WGSL for certain functions.
 Since JavaScript doesn't support operator overloading, functions including complex matrix operations can be more readable in WGSL.

apps/typegpu-docs/src/content/docs/fundamentals/timestamp-queries.mdx

@@ -7,15 +7,15 @@ description: How to use timestamp queries to measure the performance of your pip
 This feature is under heavy development and is yet to reach stability.
 :::
 
-To measure kernel execution time, you can use **timestamp queries**, which instruct compute or render passes to write timestamps at the start and end of execution. By reading back these timestamps, you can calculate the pipeline’s execution duration in nanoseconds.
+To measure shader execution time, you can use **timestamp queries**, which instruct compute or render passes to write timestamps at the start and end of execution. By reading back these timestamps, you can calculate the pipeline’s execution duration in nanoseconds.
 
 :::tip
 To use performance callbacks and timestamp queries, you must enable the `timestamp-query` feature on your GPU device. See [Enabling Features](/TypeGPU/fundamentals/enabling-features) for details.
 :::
 
 TypeGPU offers two ways to employ timestamp queries:
 
-1. **High-level API** via the pipeline’s `.withPerformanceCallback()` method  
+1. **High-level API** via the pipeline’s `.withPerformanceCallback()` method
 2. **Low-level API** using a `TgpuQuerySet`, which you can attach to a TypeGPU pipeline or a raw WebGPU command encoder
 
 ## Performance callbacks

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

@@ -17,7 +17,7 @@ const root = await tgpu.init();
 const data = root.createMutable(d.arrayOf(d.u32, 8), [0, 1, 2, 3, 4, 5, 6, 7]);
 
 const doubleUp = prepareDispatch(root, (x) => {
-  'kernel';
+  'use gpu';
   data.$[x] *= 2;
 });
 
@@ -30,7 +30,7 @@ console.log(await data.read()); // [0, 8, 16, 24, 16, 20, 24, 28]
 ```
 
 :::note
-Remember to mark the callback with `'kernel'` directive to let TypeGPU know that this function is TGSL.
+Remember to mark the callback with the `'use gpu'` directive to let TypeGPU know that this function is TGSL.
 :::
 
 The callback can have up to three arguments (dimensions).
@@ -52,7 +52,7 @@ const waterLevelMutable = root.createMutable(
 );
 
 prepareDispatch(root, (x, y) => {
-  'kernel';
+  'use gpu';
   randf.seed2(d.vec2f(x, y).div(1024));
   waterLevelMutable.$[x][y] = 10 + randf.sample();
 }).dispatch(1024, 512);
@@ -85,7 +85,7 @@ const bindGroup2 = root.createBindGroup(layout, {
 });
 
 const test = prepareDispatch(root, (x) => {
-  'kernel';
+  'use gpu';
   layout.$.buffer[x] *= 2;
 });
 
@@ -130,12 +130,12 @@ const root = await tgpu.init();
 // ---cut---
 const callCountMutable = root.createMutable(d.u32, 0);
 const compute = prepareDispatch(root, () => {
-  'kernel';
+  'use gpu';
   callCountMutable.$ += 1;
   console.log('Call number', callCountMutable.$);
 });
 
-compute.dispatch(); 
+compute.dispatch();
 compute.dispatch();
 
 // Eventually...

apps/typegpu-docs/src/content/docs/tooling/unplugin-typegpu.mdx

@@ -27,20 +27,20 @@ The package includes the following functionalities:
   ```
 
   However, if the implementation function, or the shell, is referenced via a variable, the plugin will not recognize it as TGSL,
-  thus to make it work, the function needs to be marked with a `"kernel"` directive.
+  thus to make it work, the function needs to be marked with a `'use gpu'` directive.
 
   ```ts
   const addFn = tgpu.fn([d.u32, d.u32], d.u32);
 
   const add = addFn((a, b) => {
-    'kernel';
+    'use gpu';
     return a + b;
   });
   ```
 
   ```ts
   const addImpl = (a, b) => {
-    'kernel';
+    'use gpu';
     return a + b;
   };
 
@@ -128,7 +128,7 @@ interface Options {
   autoNamingEnabled?: boolean;
 
   /**
-   * Skipping files that don't contain "typegpu", "tgpu" or "kernel".
+   * Skipping files that don't contain 'typegpu', 'tgpu' or 'use gpu'.
    * In case this early pruning hinders transformation, you
    * can disable it.
    *

apps/typegpu-docs/src/examples/algorithms/matrix-next/index.ts

@@ -19,7 +19,7 @@ const state = {
     second: [] as number[],
     result: [] as number[],
   },
-  kernelTime: 0,
+  gpuTime: 0,
 };
 
 const root = await tgpu.init({
@@ -57,7 +57,7 @@ function createBindGroup() {
 
 function createPipelines() {
   const performanceCallback = (start: bigint, end: bigint) => {
-    state.kernelTime = Number(end - start) / 1_000_000;
+    state.gpuTime = Number(end - start) / 1_000_000;
   };
 
   const optimized = root['~unstable']
@@ -195,11 +195,11 @@ async function compute() {
       cpu: 'CPU',
     }[state.strategy];
 
-    const showKernel = state.strategy !== 'cpu' && hasTimestampQuery;
+    const showGpu = state.strategy !== 'cpu' && hasTimestampQuery;
     updateTimingDisplay(
       strategyName,
       totalTime,
-      showKernel ? state.kernelTime : undefined,
+      showGpu ? state.gpuTime : undefined,
     );
 
     printMatrixToHtml(
@@ -227,15 +227,15 @@ generateMatrices();
 function updateTimingDisplay(
   strategy: string,
   totalTime: number,
-  kernelTime?: number,
+  gpuTime?: number,
 ) {
   if (!timingDisplay) return;
 
-  timingDisplay.innerHTML = kernelTime !== undefined
+  timingDisplay.innerHTML = gpuTime !== undefined
     ? `<div>${strategy} computation:</div>
        <div style="font-size: 0.9em; margin-top: 0.25rem;">
-         Total: ${totalTime.toFixed(2)}ms | Kernel: ${
-      kernelTime >= 0.01 ? kernelTime.toFixed(2) : '<0.01'
+         Total: ${totalTime.toFixed(2)}ms | GPU: ${
+      gpuTime >= 0.01 ? gpuTime.toFixed(2) : '<0.01'
     }ms
        </div>`
     : `${strategy} computation: ${totalTime.toFixed(2)}ms`;

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

@@ -99,7 +99,7 @@ const buffer0mutable = fishDataBuffers[0].as('mutable');
 const buffer1mutable = fishDataBuffers[1].as('mutable');
 const seedUniform = root.createUniform(d.f32);
 const randomizeFishPositionsOnGPU = prepareDispatch(root, (x) => {
-  'kernel';
+  'use gpu';
   randf.seed2(d.vec2f(d.f32(x), seedUniform.$));
   const data = ModelData({
     position: d.vec3f(

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

@@ -3,7 +3,7 @@ import { add, cos, dot, normalize, sin } from 'typegpu/std';
 import type { Line3 } from './schemas.ts';
 
 export const projectPointOnLine = (point: d.v3f, line: Line3): d.v3f => {
-  'kernel';
+  'use gpu';
   const pointVector = point.sub(line.origin);
   const projection = dot(pointVector, line.dir);
   return line.origin.add(line.dir.mul(projection));
@@ -20,7 +20,7 @@ export const applySinWave = (
   vertex: PosAndNormal,
   time: number,
 ) => {
-  'kernel';
+  'use gpu';
   const a = -60.1;
   const b = 0.8;
   const c = 6.1;

apps/typegpu-docs/src/examples/rendering/caustics/index.ts

@@ -21,15 +21,15 @@ const mainVertex = tgpu['~unstable'].vertexFn({
  * location.
  */
 const tilePattern = (uv: d.v2f): number => {
-  'kernel';
+  'use gpu';
   const tiledUv = std.fract(uv);
   const proximity = std.abs(std.sub(std.mul(tiledUv, 2), 1));
   const maxProximity = std.max(proximity.x, proximity.y);
   return std.saturate(std.pow(1 - maxProximity, 0.6) * 5);
 };
 
 const caustics = (uv: d.v2f, time: number, profile: d.v3f): d.v3f => {
-  'kernel';
+  'use gpu';
   const distortion = perlin3d.sample(d.vec3f(std.mul(uv, 0.5), time * 0.2));
   // Distorting UV coordinates
   const uv2 = std.add(uv, distortion);
@@ -42,7 +42,7 @@ const caustics = (uv: d.v2f, time: number, profile: d.v3f): d.v3f => {
  * in the XY plane (around the imaginary Z axis)
  */
 const rotateXY = (angle: number): d.m2x2f => {
-  'kernel';
+  'use gpu';
   return d.mat2x2f(
     /* right */ d.vec2f(std.cos(angle), std.sin(angle)),
     /* up    */ d.vec2f(-std.sin(angle), std.cos(angle)),

apps/typegpu-docs/src/examples/rendering/cubemap-reflection/helpers.ts

@@ -2,27 +2,27 @@ import * as d from 'typegpu/data';
 import * as std from 'typegpu/std';
 
 export const unpackVec2u = (packed: d.v2u): d.v4f => {
-  'kernel';
+  'use gpu';
   const xy = std.unpack2x16float(packed.x);
   const zw = std.unpack2x16float(packed.y);
   return d.vec4f(xy, zw);
 };
 
 export const packVec2u = (toPack: d.v4f): d.v2u => {
-  'kernel';
+  'use gpu';
   const xy = std.pack2x16float(toPack.xy);
   const zw = std.pack2x16float(toPack.zw);
   return d.vec2u(xy, zw);
 };
 
 export const getAverageNormal = (v1: d.v4f, v2: d.v4f, v3: d.v4f): d.v4f => {
-  'kernel';
+  'use gpu';
   const edge1 = std.sub(v2.xyz, v1.xyz);
   const edge2 = std.sub(v3.xyz, v1.xyz);
   return std.normalize(d.vec4f(std.cross(edge1, edge2), 0));
 };
 
 export const calculateMidpoint = (v1: d.v4f, v2: d.v4f): d.v4f => {
-  'kernel';
+  'use gpu';
   return d.vec4f(std.mul(0.5, std.add(v1.xyz, v2.xyz)), 1);
 };

apps/typegpu-docs/src/examples/rendering/disco/utils.ts

@@ -2,7 +2,7 @@ import * as d from 'typegpu/data';
 import * as std from 'typegpu/std';
 
 export const palette = (t: number): d.v3f => {
-  'kernel';
+  'use gpu';
   const a = d.vec3f(0.50, 0.59, 0.85);
   const b = d.vec3f(0.18, 0.42, 0.40);
   const c = d.vec3f(0.18, 0.48, 0.41);