Merge branch 'main' into feat/tgpu-three

Author: iwoplaza

apps/typegpu-docs/src/components/translator/lib/rolldown.ts

@@ -2,7 +2,7 @@ import type { InputOptions, OutputOptions } from '@rolldown/browser';
 import { join } from 'pathe';
 
 export interface BundleResult {
-  output: Record<string, string | Uint8Array>;
+  output: Record<string, string | Uint8Array<ArrayBuffer>>;
   warnings?: string[] | undefined;
 }
 
@@ -88,7 +88,7 @@ export async function bundle(
     result.output.map((chunk) =>
       chunk.type === 'chunk'
         ? [chunk.fileName, chunk.code]
-        : [chunk.fileName, chunk.source]
+        : [chunk.fileName, chunk.source.slice()]
     ),
   );
 

apps/typegpu-docs/src/content/docs/fundamentals/functions/index.mdx

@@ -323,7 +323,7 @@ function manhattanDistance(a: d.v3f, b: d.v3f) {
   const dy = std.abs(a.y - b.y);
   const dz = std.abs(a.z - b.z);
 
-  return std.max(dx, std.max(dy, dz));
+  return std.max(dx, dy, dz);
 }
 ```
 

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

@@ -128,6 +128,76 @@ tgpu.resolve([innerPipeline]);
 ```
 :::
 
+## *tgpu.comptime*
+
+`tgpu['~unstable'].comptime(func)` creates a version of `func` that instead of being transpiled to WGSL, will be called during the WGSL code generation.
+This can be used to precompute and inject a value into the final shader code.
+
+```ts twoslash
+import tgpu from 'typegpu';
+import * as d from 'typegpu/data';
+
+const hsvToRgb = tgpu.fn([d.f32, d.f32, d.f32], d.vec3f)``;
+
+// ---cut---
+const injectRand01 = tgpu['~unstable']
+  .comptime(() => Math.random());
+
+const getColor = tgpu.fn([d.vec3f])((diffuse) => {
+  'use gpu';
+  const albedo = hsvToRgb(injectRand01(), 1, 0.5);
+  return albedo.mul(diffuse);
+});
+```
+
+Note how the function passed into `comptime` doesn't have to be marked with
+`'use gpu'` and can use `Math`. That's because the function doesn't execute on the GPU, it gets
+executed before the shader code gets sent to the GPU.
+
+## *tgpu.rawCodeSnippet*
+
+When working on top of some existing shader code, sometimes you may know for certain that some variable will be already defined and should be accessible in the code. 
+In such scenario you can use `tgpu['~unstable'].rawCodeSnippet` -- an advanced API that creates a typed shader expression which can be injected into the final shader bundle upon use.
+
+```ts twoslash
+import tgpu from 'typegpu';
+import * as d from 'typegpu/data';
+
+// ---cut---
+// `EXISTING_GLOBAL` is an identifier that we know will be in the
+// final shader bundle, but we cannot
+// refer to it in any other way.
+const existingGlobal = tgpu['~unstable']
+  .rawCodeSnippet('EXISTING_GLOBAL', d.f32, 'constant');
+
+const foo = tgpu.fn([], d.f32)(() => {
+  'use gpu';
+  return existingGlobal.$ * 22;
+});
+
+const wgsl = tgpu.resolve([foo]);
+// fn foo() -> f32 {
+//   return (EXISTING_GLOBAL * 22f);
+// }
+```
+
+:::note
+There currently is no way to create a `rawCodeSnippet` that refers to an existing function.
+:::
+
+### Which origin to choose?
+
+The optional third parameter `origin` lets TypeGPU transpiler know how to optimize the code snippet, as well as allows for some transpilation-time validity checks.
+
+Usually `'runtime'` (the default) is a safe bet, but if you're sure that the expression or
+computation is constant (either a reference to a constant, a numeric literal,
+or an operation on constants), then pass `'constant'` as it might lead to better
+optimizations.
+
+If what the expression is a direct reference to an existing value (e.g. a uniform, a
+storage binding, ...), then choose from `'uniform'`, `'mutable'`, `'readonly'`, `'workgroup'`,
+`'private'` or `'handle'` depending on the address space of the referred value.
+
 ## *console.log*
 
 Yes, you read that correctly, TypeGPU implements logging to the console on the GPU!

apps/typegpu-docs/src/content/docs/reference/shader-generation.mdx

@@ -200,6 +200,7 @@ There are essentially three types of origins:
   include accessing the position of an existing `Boid` instance or modifying the position of an existing `Boid` instance. These include `'uniform'`, `'mutable'`, `'readonly'`, `'workgroup'`, `'private'`, `'function'`, `'handle'`, `'constant-ref'` and `'this-function'`.
     - `'uniform'`, `'mutable'`, `'readonly'`, `'workgroup'`, `'private'`, `'function'`, `'handle'` all reflect address spaces that values can belong to, and
       we use them to determine what kind of pointer type they are.
-    - `'constant-ref'` is a reference to a value stored in a `tgpu.const`. They're different from `constant`s, as we know that even if they're referential (non-primitive), the developer cannot mutate them.
+    - `'constant-tgpu-const-ref'` is a reference to a value stored in a `tgpu.const`. They're different from `constant`s, as we know that even if they're referential (non-primitive), the developer cannot mutate them.
+    - `'runtime-tgpu-const-ref'` is a reference to a value stored in a `tgpu.const` but accessed in a way that isn’t constant at shader‑creation time (for example, indexed using a runtime value).
     - `'this-function'` lets us track whether values originates from the function we're currently generating, or the function that called us.
 - **Argument Origins**: This group is dedicated to exactly one origin: 'argument'. It represents values that are passed as arguments to functions.

apps/typegpu-docs/src/examples/algorithms/jump-flood/index.html

@@ -0,0 +1 @@
+<canvas data-fit-to-container></canvas>