docs: Generator slot

apps/typegpu-docs/src/content/docs/ecosystem/typegpu-noise.mdx

@@ -10,7 +10,7 @@ It also features a [Perlin noise](#perlin-noise) implementation, which is useful
 effects, terrains, and other procedural elements.
 
 :::note
-Threads do not share the generator's `State`. As a result, unless you change the seed or provide thread-dependent variables, each thread will produce the same sequence of sampled values.
+Threads do not share the generator's `State`. As a result, unless you change the seed in each thread, each thread will produce the same sequence of sampled values.
 :::
 
 ## Use with either TypeGPU or WebGPU
@@ -267,3 +267,58 @@ pipeline
 // a different domain size
 bindGroup = initBindGroup(d.vec3u(5, 5, 1));
 ```
+
+## Generator slot
+The package provides convenient way to change PRNG as needed.
+You can easily implement your own PRNG and plug it into the pipeline.
+
+```ts twoslash
+import tgpu from 'typegpu';
+import * as d from 'typegpu/data';
+import { randf } from '@typegpu/noise';
+import * as std from 'typegpu/std';
+
+const root = await tgpu.init();
+
+const b = root.createMutable(d.f32);
+const f = tgpu['~unstable'].computeFn({ workgroupSize: [1] })(() => {
+  b.$ = randf.sample();
+});
+// ---cut---
+import {
+  randomGeneratorSlot,
+  type StatefulGenerator,
+} from '@typegpu/noise';
+
+export const LCG: StatefulGenerator = (() => {
+  const seed = tgpu.privateVar(d.u32);
+
+  const u32To01Float = tgpu.fn([d.u32], d.f32)`(val){
+    let exponent: u32 = 0x3f800000;
+    let mantissa: u32 = 0x007fffff & val;
+    var ufloat: u32 = (exponent | mantissa);
+    return bitcast<f32>(ufloat) - 1f;
+  }`;
+
+  return {
+    seed: (value: number) => {
+      'kernel';
+      seed.$ = d.u32(value * std.pow(32, 3));
+    },
+    seed2: (value: d.v2f) => {
+      'kernel';
+      seed.$ = d.u32(value.x * std.pow(32, 3) + value.y * std.pow(32, 2));
+    },
+    sample: () => {
+      'kernel';
+      seed.$ = seed.$ * 1664525 + 1013904223; // % 2 ^ 32
+      return u32To01Float(seed.$);
+    },
+  };
+})();
+
+const pipeline = root['~unstable']
+  .with(randomGeneratorSlot, LCG)
+  .withCompute(f)
+  .createPipeline();
+```

apps/typegpu-docs/src/examples/tests/uniformity/constants.ts

@@ -0,0 +1,6 @@
+import { PRNG } from './prngs.ts';
+
+export const gridSizes = [10, 25, 50, 100, 200, 500, 700, 1000];
+export const initialGridSize = gridSizes[3];
+export const initialPRNG = PRNG.BPETER;
+export const prngs: PRNG[] = Object.values(PRNG);

apps/typegpu-docs/src/examples/tests/uniformity/fragment.ts

@@ -0,0 +1,21 @@
+import tgpu from 'typegpu';
+import type { TgpuUniform } from 'typegpu';
+import * as d from 'typegpu/data';
+import * as std from 'typegpu/std';
+import { randf } from '@typegpu/noise';
+
+export const bindFullScreenGridFSWithUniforms = (
+  gridSizeUniform: TgpuUniform<d.F32>,
+  canvasRatioUniform: TgpuUniform<d.F32>,
+) =>
+  tgpu['~unstable'].fragmentFn({
+    in: { uv: d.vec2f },
+    out: d.vec4f,
+  })((input) => {
+    const uv = input.uv.add(1).div(2).mul(d.vec2f(canvasRatioUniform.$, 1));
+    const gridedUV = std.floor(uv.mul(gridSizeUniform.$));
+
+    randf.seed2(gridedUV);
+
+    return d.vec4f(d.vec3f(randf.sample()), 1.0);
+  });

apps/typegpu-docs/src/examples/tests/uniformity/helpers.ts

@@ -0,0 +1,37 @@
+import type { TgpuRenderPipeline, TgpuRoot, TgpuUniform } from 'typegpu';
+import { randomGeneratorSlot } from '@typegpu/noise';
+import type * as d from 'typegpu/data';
+
+import { fullScreenTriangleVertexShader } from './vertex.ts';
+import { bindFullScreenGridFSWithUniforms } from './fragment.ts';
+import { getPRNG, type PRNG } from './prngs.ts';
+
+export const preparePipeline = (
+  root: TgpuRoot,
+  presentationFormat: GPUTextureFormat,
+  prng: PRNG,
+  gridSizeUniform: TgpuUniform<d.F32>,
+  canvasRatioUniform: TgpuUniform<d.F32>,
+): TgpuRenderPipeline =>
+  root['~unstable']
+    .with(randomGeneratorSlot, getPRNG(prng))
+    .withVertex(fullScreenTriangleVertexShader, {})
+    .withFragment(
+      bindFullScreenGridFSWithUniforms(gridSizeUniform, canvasRatioUniform),
+      {
+        format: presentationFormat,
+      },
+    )
+    .createPipeline();
+
+export const executePipeline = (
+  pipeline: TgpuRenderPipeline,
+  context: GPUCanvasContext,
+) =>
+  pipeline
+    .withColorAttachment({
+      view: context.getCurrentTexture().createView(),
+      loadOp: 'clear',
+      storeOp: 'store',
+    })
+    .draw(3);

apps/typegpu-docs/src/examples/tests/uniformity/index.html

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

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

@@ -0,0 +1,94 @@
+import tgpu, { type TgpuRenderPipeline } from 'typegpu';
+import * as d from 'typegpu/data';
+
+import * as c from './constants.ts';
+import type { PRNG } from './prngs.ts';
+import { executePipeline, preparePipeline } from './helpers.ts';
+
+const root = await tgpu.init();
+
+const canvas = document.querySelector('canvas') as HTMLCanvasElement;
+const context = canvas.getContext('webgpu') as GPUCanvasContext;
+const presentationFormat = navigator.gpu.getPreferredCanvasFormat();
+context.configure({
+  device: root.device,
+  format: presentationFormat,
+  alphaMode: 'premultiplied',
+});
+
+const gridSizeUniform = root.createUniform(d.f32, c.initialGridSize);
+const canvasRatioUniform = root.createUniform(
+  d.f32,
+  canvas.width / canvas.height,
+);
+const pipelineCache = new Map<PRNG, TgpuRenderPipeline>();
+let prng: PRNG = c.initialPRNG;
+
+const redraw = (value: PRNG) => {
+  let pipeline = undefined;
+  if (!pipelineCache.has(value)) {
+    pipeline = preparePipeline(
+      root,
+      presentationFormat,
+      value,
+      gridSizeUniform,
+      canvasRatioUniform,
+    );
+    pipelineCache.set(value, pipeline);
+  } else {
+    pipeline = pipelineCache.get(value);
+  }
+  executePipeline(pipeline as TgpuRenderPipeline, context);
+};
+
+// #region Example controls & Cleanup
+export const controls = {
+  'PRNG': {
+    initial: c.initialPRNG,
+    options: c.prngs,
+    onSelectChange: (value: PRNG) => {
+      prng = value;
+      redraw(value);
+    },
+  },
+  'Grid Size': {
+    initial: c.initialGridSize,
+    options: c.gridSizes,
+    onSelectChange: (value: number) => {
+      gridSizeUniform.write(value);
+      redraw(prng);
+    },
+  },
+  'Test Resolution': import.meta.env.DEV && {
+    onButtonClick: () => {
+      c.prngs
+        .map((prng) =>
+          tgpu.resolve({
+            externals: {
+              f: preparePipeline(
+                root,
+                presentationFormat,
+                prng,
+                gridSizeUniform,
+                canvasRatioUniform,
+              ),
+            },
+          })
+        )
+        .map((r) => root.device.createShaderModule({ code: r }));
+    },
+  },
+};
+
+const resizeObserver = new ResizeObserver(() => {
+  canvasRatioUniform.write(canvas.width / canvas.height);
+  redraw(prng);
+});
+resizeObserver.observe(canvas);
+
+export function onCleanup() {
+  resizeObserver.disconnect();
+  root.destroy();
+}
+
+// #endregion

apps/typegpu-docs/src/examples/tests/uniformity/lcg.ts

@@ -0,0 +1,31 @@
+import tgpu from 'typegpu';
+import * as d from 'typegpu/data';
+import * as std from 'typegpu/std';
+import type { StatefulGenerator } from '@typegpu/noise';
+
+export const LCG: StatefulGenerator = (() => {
+  const seed = tgpu.privateVar(d.u32);
+
+  const u32To01Float = tgpu.fn([d.u32], d.f32)`(val){
+    let exponent: u32 = 0x3f800000;
+    let mantissa: u32 = 0x007fffff & val;
+    var ufloat: u32 = (exponent | mantissa);
+    return bitcast<f32>(ufloat) - 1f;
+  }`;
+
+  return {
+    seed: (value: number) => {
+      'kernel';
+      seed.$ = d.u32(value * std.pow(32, 3));
+    },
+    seed2: (value: d.v2f) => {
+      'kernel';
+      seed.$ = d.u32(value.x * std.pow(32, 3) + value.y * std.pow(32, 2));
+    },
+    sample: () => {
+      'kernel';
+      seed.$ = seed.$ * 1664525 + 1013904223; // % 2 ^ 32
+      return u32To01Float(seed.$);
+    },
+  };
+})();

apps/typegpu-docs/src/examples/tests/uniformity/meta.json

@@ -0,0 +1,6 @@
+{
+  "title": "Uniformity",
+  "category": "tests",
+  "tags": ["experimental"],
+  "dev": true
+}

apps/typegpu-docs/src/examples/tests/uniformity/prngs.ts

@@ -0,0 +1,17 @@
+import { BPETER, type StatefulGenerator } from '@typegpu/noise';
+
+import { LCG } from './lcg.ts';
+
+export const PRNG = {
+  BPETER: 'bpeter (default)',
+  LCG: 'lcg',
+} as const;
+
+export type PRNG = typeof PRNG[keyof typeof PRNG];
+
+const PRNG_MAP = {
+  [PRNG.BPETER]: BPETER,
+  [PRNG.LCG]: LCG,
+};
+
+export const getPRNG = (prng: PRNG): StatefulGenerator => PRNG_MAP[prng];

apps/typegpu-docs/src/examples/tests/uniformity/vertex.ts

@@ -0,0 +1,14 @@
+import tgpu from 'typegpu';
+import * as d from 'typegpu/data';
+
+export const fullScreenTriangleVertexShader = tgpu['~unstable'].vertexFn({
+  in: { vertexIndex: d.builtin.vertexIndex },
+  out: { pos: d.builtin.position, uv: d.vec2f },
+})((input) => {
+  const pos = [d.vec2f(-1, -1), d.vec2f(3, -1), d.vec2f(-1, 3)];
+
+  return {
+    pos: d.vec4f(pos[input.vertexIndex], 0.0, 1.0),
+    uv: pos[input.vertexIndex],
+  };
+});

packages/typegpu-noise/src/generator.ts

@@ -3,11 +3,11 @@ import * as d from 'typegpu/data';
 import { add, cos, dot, fract } from 'typegpu/std';
 
 export interface StatefulGenerator {
-  seed: TgpuFn<(seed: d.F32) => d.Void>;
-  seed2: TgpuFn<(seed: d.Vec2f) => d.Void>;
-  seed3: TgpuFn<(seed: d.Vec3f) => d.Void>;
-  seed4: TgpuFn<(seed: d.Vec4f) => d.Void>;
-  sample: TgpuFn<() => d.F32>;
+  seed: TgpuFn<(seed: d.F32) => d.Void> | ((seed: number) => void);
+  seed2?: TgpuFn<(seed: d.Vec2f) => d.Void> | ((seed: d.v2f) => void);
+  seed3?: TgpuFn<(seed: d.Vec3f) => d.Void> | ((seed: d.v3f) => void);
+  seed4?: TgpuFn<(seed: d.Vec4f) => d.Void> | ((seed: d.v4f) => void);
+  sample: TgpuFn<() => d.F32> | (() => number);
 }
 
 export const randomGeneratorShell: TgpuFnShell<[], d.F32> = tgpu.fn([], d.f32);