Merge branch 'release'

Author: iwoplaza

apps/typegpu-docs/public/assets/phong/teapot.obj

@@ -332,3 +332,82 @@ const indexBuffer = root
 
 ```
 
+## Binding buffers
+
+To use a buffer in a shader, it needs to be bound using a bind group.
+There are two approaches provided by TypeGPU.
+
+### Manual binding
+
+The default option is to create bind group layouts and bind your buffers via bind groups.
+Read more in the chapter dedicated to [bind groups](/TypeGPU/fundamentals/bind-groups).
+
+```ts twoslash
+import tgpu from 'typegpu';
+import * as d from 'typegpu/data';
+
+const root = await tgpu.init();
+// ---cut---
+const pointsBuffer = root
+  .createBuffer(d.arrayOf(d.vec2i, 100))
+  .$usage('storage');
+
+const bindGroupLayout = tgpu.bindGroupLayout({
+  points: { storage: d.arrayOf(d.vec2i, 100), access: 'mutable' },
+});
+
+const bindGroup = root
+  .createBindGroup(bindGroupLayout, { points: pointsBuffer });
+
+const mainCompute = tgpu['~unstable'].computeFn({
+  in: { gid: d.builtin.globalInvocationId },
+  workgroupSize: [1],
+})((input) => {
+  // Access and modify the bound buffer via the layout
+  bindGroupLayout.$.points[input.gid[0]] = d.vec2i(1, 2);
+});
+
+const pipeline = root['~unstable']
+  .withCompute(mainCompute)
+  .createPipeline();
+
+pipeline
+  .with(bindGroupLayout, bindGroup)
+  .dispatchWorkgroups(100);
+```
+
+### Using fixed resources
+
+For scenarios where buffers remain consistent across multiple compute or render operations,
+TypeGPU offers fixed resources that appear bindless from a code perspective.
+Fixed buffers are created using dedicated root methods.
+
+| WGSL type                  | TypeGPU constructor     |
+|----------------------------|-------------------------|
+| `var<uniform>`             | `root.createUniform()`  |
+| `var<storage, read>`       | `root.createReadonly()` |
+| `var<storage, read_write>` | `root.createMutable()`  |
+
+```ts twoslash
+import tgpu from 'typegpu';
+import * as d from 'typegpu/data';
+
+const root = await tgpu.init();
+// ---cut---
+const pointsBuffer = root.createMutable(d.arrayOf(d.vec2i, 100));
+
+const mainCompute = tgpu['~unstable'].computeFn({
+  in: { gid: d.builtin.globalInvocationId },
+  workgroupSize: [1],
+})((input) => {
+  // Access and modify the fixed buffer directly
+  pointsBuffer.$[input.gid[0]] = d.vec2i();
+});
+
+const pipeline = root['~unstable'].withCompute(mainCompute).createPipeline();
+pipeline.dispatchWorkgroups(100);
+```
+
+TypeGPU automatically generates a "catch-all" bind group and populates it with the fixed resources.
+
+You can also use [`resolveWithContext`](/TypeGPU/fundamentals/resolve/#resolvewithcontext) to access the automatically generated bind group and layout containing your fixed resources.

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

@@ -104,7 +104,6 @@ export const controls = {
       }[value];
       if (patternIndex !== undefined) {
         currentPipeline = pipelines[patternIndex];
-        render();
       }
     },
   },

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

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

apps/typegpu-docs/src/examples/rendering/phong-reflection/index.html

@@ -0,0 +1,210 @@
+import tgpu from 'typegpu';
+import * as d from 'typegpu/data';
+import * as std from 'typegpu/std';
+import * as p from './params.ts';
+import {
+  ExampleControls,
+  ModelVertexInput,
+  modelVertexLayout,
+  ModelVertexOutput,
+} from './schemas.ts';
+import { loadModel } from './load-model.ts';
+import { Camera, setupOrbitCamera } from './setup-orbit-camera.ts';
+
+// setup
+const canvas = document.querySelector('canvas') as HTMLCanvasElement;
+const context = canvas.getContext('webgpu') as GPUCanvasContext;
+const presentationFormat = navigator.gpu.getPreferredCanvasFormat();
+const root = await tgpu.init();
+
+context.configure({
+  device: root.device,
+  format: presentationFormat,
+  alphaMode: 'premultiplied',
+});
+
+// model (https://j5boom.itch.io/utah-teapot-obj)
+const model = await loadModel(root, '/TypeGPU/assets/phong/teapot.obj');
+
+// camera
+const cameraUniform = root.createUniform(Camera);
+
+const { cleanupCamera } = setupOrbitCamera(
+  canvas,
+  {
+    initPos: d.vec4f(-10, 4, -8, 1),
+    target: d.vec4f(0, 1, 0, 1),
+    minZoom: 8,
+    maxZoom: 40,
+  },
+  (updates) => cameraUniform.writePartial(updates),
+);
+
+// shaders
+const exampleControlsUniform = root.createUniform(
+  ExampleControls,
+  p.initialControls,
+);
+
+export const vertexShader = tgpu['~unstable'].vertexFn({
+  in: { ...ModelVertexInput.propTypes, instanceIndex: d.builtin.instanceIndex },
+  out: ModelVertexOutput,
+})((input) => {
+  const worldPosition = d.vec4f(input.modelPosition, 1);
+  const camera = cameraUniform.$;
+
+  const canvasPosition = camera.projection.mul(camera.view).mul(worldPosition);
+
+  return {
+    worldPosition: input.modelPosition,
+    worldNormal: input.modelNormal,
+    canvasPosition: canvasPosition,
+  };
+});
+
+// see https://gist.github.com/chicio/d983fff6ff304bd55bebd6ff05a2f9dd
+export const fragmentShader = tgpu['~unstable'].fragmentFn({
+  in: ModelVertexOutput,
+  out: d.vec4f,
+})((input) => {
+  const lightColor = std.normalize(exampleControlsUniform.$.lightColor);
+  const lightDirection = std.normalize(exampleControlsUniform.$.lightDirection);
+  // fixed color, can be replaced with texture sample
+  const ambientColor = exampleControlsUniform.$.ambientColor;
+  const ambientStrength = exampleControlsUniform.$.ambientStrength;
+  const specularStrength = exampleControlsUniform.$.specularExponent;
+
+  // ambient component
+  const ambient = ambientColor.mul(ambientStrength);
+
+  // diffuse component
+  const cosTheta = std.dot(input.worldNormal, lightDirection);
+  const diffuse = lightColor.mul(std.max(0, cosTheta));
+
+  // specular component
+  const reflectionDirection = std.reflect(
+    lightDirection.mul(-1),
+    input.worldNormal,
+  );
+  const viewDirection = std.normalize(
+    cameraUniform.$.position.xyz.sub(input.worldPosition),
+  );
+  const specular = lightColor.mul(
+    std.pow(
+      std.max(0, std.dot(reflectionDirection, viewDirection)),
+      specularStrength,
+    ),
+  );
+
+  // add the components up
+  const color = ambient.add(diffuse).add(specular);
+  return d.vec4f(color, 1);
+});
+
+// pipelines
+const renderPipeline = root['~unstable']
+  .withVertex(vertexShader, modelVertexLayout.attrib)
+  .withFragment(fragmentShader, { format: presentationFormat })
+  .withDepthStencil({
+    format: 'depth24plus',
+    depthWriteEnabled: true,
+    depthCompare: 'less',
+  })
+  .withPrimitive({ topology: 'triangle-list' })
+  .createPipeline();
+
+let depthTexture = root.device.createTexture({
+  size: [canvas.width, canvas.height, 1],
+  format: 'depth24plus',
+  usage: GPUTextureUsage.RENDER_ATTACHMENT,
+});
+
+// frame
+let frameId: number;
+function frame() {
+  renderPipeline
+    .withColorAttachment({
+      view: context.getCurrentTexture().createView(),
+      clearValue: [
+        p.backgroundColor.x,
+        p.backgroundColor.y,
+        p.backgroundColor.z,
+        1,
+      ],
+      loadOp: 'clear',
+      storeOp: 'store',
+    })
+    .withDepthStencilAttachment({
+      view: depthTexture.createView(),
+      depthClearValue: 1,
+      depthLoadOp: 'clear',
+      depthStoreOp: 'store',
+    })
+    .with(modelVertexLayout, model.vertexBuffer)
+    .draw(model.polygonCount);
+
+  frameId = requestAnimationFrame(frame);
+}
+frameId = requestAnimationFrame(frame);
+
+// #region Example controls and cleanup
+export const controls = {
+  'light color': {
+    initial: [...p.initialControls.lightColor],
+    onColorChange(value: readonly [number, number, number]) {
+      exampleControlsUniform.writePartial({ lightColor: d.vec3f(...value) });
+    },
+  },
+  'light direction': {
+    min: [-10, -10, -10],
+    max: [10, 10, 10],
+    initial: [...p.initialControls.lightDirection],
+    step: [0.01, 0.01, 0.01],
+    onVectorSliderChange(v: [number, number, number]) {
+      exampleControlsUniform.writePartial({ lightDirection: d.vec3f(...v) });
+    },
+  },
+  'ambient color': {
+    initial: [...p.initialControls.ambientColor],
+    onColorChange(value: readonly [number, number, number]) {
+      exampleControlsUniform.writePartial({ ambientColor: d.vec3f(...value) });
+    },
+  },
+  'ambient strength': {
+    min: 0,
+    max: 1,
+    initial: p.initialControls.ambientStrength,
+    step: 0.01,
+    onSliderChange(v: number) {
+      exampleControlsUniform.writePartial({ ambientStrength: v });
+    },
+  },
+  'specular exponent': {
+    min: 0.5,
+    max: 16,
+    initial: p.initialControls.specularExponent,
+    step: 0.1,
+    onSliderChange(v: number) {
+      exampleControlsUniform.writePartial({ specularExponent: v });
+    },
+  },
+};
+
+const resizeObserver = new ResizeObserver(() => {
+  depthTexture.destroy();
+  depthTexture = root.device.createTexture({
+    size: [canvas.width, canvas.height, 1],
+    format: 'depth24plus',
+    usage: GPUTextureUsage.RENDER_ATTACHMENT,
+  });
+});
+resizeObserver.observe(canvas);
+
+export function onCleanup() {
+  cancelAnimationFrame(frameId);
+  cleanupCamera();
+  resizeObserver.unobserve(canvas);
+  root.destroy();
+}
+
+// #endregion

apps/typegpu-docs/src/examples/rendering/phong-reflection/index.ts

@@ -0,0 +1,42 @@
+import { load } from '@loaders.gl/core';
+import { OBJLoader } from '@loaders.gl/obj';
+import type { TgpuRoot } from 'typegpu';
+import * as d from 'typegpu/data';
+import { modelVertexLayout } from './schemas.ts';
+
+export async function loadModel(
+  root: TgpuRoot,
+  modelPath: string,
+) {
+  const modelMesh = await load(modelPath, OBJLoader);
+  const polygonCount = modelMesh.attributes.POSITION.value.length / 3;
+
+  const vertexBuffer = root
+    .createBuffer(modelVertexLayout.schemaForCount(polygonCount))
+    .$usage('vertex')
+    .$name(`model vertices of ${modelPath}`);
+
+  const modelVertices = [];
+  for (let i = 0; i < polygonCount; i++) {
+    modelVertices.push({
+      modelPosition: d.vec3f(
+        modelMesh.attributes.POSITION.value[3 * i],
+        modelMesh.attributes.POSITION.value[3 * i + 1],
+        modelMesh.attributes.POSITION.value[3 * i + 2],
+      ),
+      modelNormal: d.vec3f(
+        modelMesh.attributes.NORMAL.value[3 * i],
+        modelMesh.attributes.NORMAL.value[3 * i + 1],
+        modelMesh.attributes.NORMAL.value[3 * i + 2],
+      ),
+    });
+  }
+  modelVertices.reverse();
+
+  vertexBuffer.write(modelVertices);
+
+  return {
+    vertexBuffer,
+    polygonCount,
+  };
+}

apps/typegpu-docs/src/examples/rendering/phong-reflection/load-model.ts

@@ -0,0 +1,5 @@
+{
+  "title": "Phong Reflection Model",
+  "category": "rendering",
+  "tags": ["experimental", "3d"]
+}

apps/typegpu-docs/src/examples/rendering/phong-reflection/meta.json

@@ -0,0 +1,12 @@
+import * as d from 'typegpu/data';
+import { ExampleControls } from './schemas.ts';
+
+export const backgroundColor = d.vec3f(28, 28, 28).div(255);
+
+export const initialControls = ExampleControls({
+  lightColor: d.vec3f(1, 0.7, 0),
+  lightDirection: d.vec3f(0, 7, -7),
+  ambientColor: d.vec3f(0.6, 0.6, 0.6),
+  ambientStrength: 0.5,
+  specularExponent: 8,
+});

apps/typegpu-docs/src/examples/rendering/phong-reflection/params.ts

@@ -0,0 +1,27 @@
+import tgpu from 'typegpu';
+import * as d from 'typegpu/data';
+
+// schemas
+
+export const ModelVertexInput = d.struct({
+  modelPosition: d.vec3f,
+  modelNormal: d.vec3f,
+});
+
+export const ModelVertexOutput = {
+  worldPosition: d.vec3f,
+  worldNormal: d.vec3f,
+  canvasPosition: d.builtin.position,
+} as const;
+
+export const ExampleControls = d.struct({
+  lightColor: d.vec3f,
+  lightDirection: d.vec3f,
+  ambientColor: d.vec3f,
+  ambientStrength: d.f32,
+  specularExponent: d.f32,
+});
+
+// layouts
+
+export const modelVertexLayout = tgpu.vertexLayout(d.arrayOf(ModelVertexInput));