Merge branch 'main' into feat/layout-value

Author: iwoplaza

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

@@ -19,14 +19,13 @@ These functions can reference outside resources, like other user-defined or help
 ## Creating a function
 
 Functions are constructed by first defining their shells, which specify their inputs and outputs.
-Then the actual WGSL implementation is passed in through the `does` method.
+Then the actual WGSL implementation is passed in as an argument to a shell invocation.
 
 The following code defines a function that accepts one argument and returns one value.
 
 ```ts
 const getGradientColor = tgpu['~unstable']
-  .fn([d.f32], d.vec4f)
-  .does(`(ratio: f32) -> vec4f {
+  .fn({ ratio: d.f32 }, d.vec4f)(`{
     let color = mix(vec4f(0.769, 0.392, 1.0, 1), d.vec4f(0.114, 0.447, 0.941, 1), ratio);
     return color;
   }`)
@@ -42,14 +41,14 @@ Externals can be any value or TypeGPU resource that can be resolved to WGSL (fun
 
 ```ts
 const getBlue = tgpu['~unstable']
-  .fn([], d.f32)
-  .does('() -> f32 { return 0.941; }');
+  .fn({}, d.vec4f)(`{ 
+    return vec4f(0.114, 0.447, 0.941, 1); 
+  }`);
 
 const purple = d.vec4f(0.769, 0.392, 1.0, 1);
 
 const getGradientColor = tgpu['~unstable']
-  .fn([d.f32], d.vec4f)
-  .does(`(ratio: f32) -> vec4f {
+  .fn({ ratio: d.f32 }, d.vec4f)(`{
     let color = mix(purple, getBlue(), ratio);
     return color;
   }`)
@@ -60,7 +59,9 @@ const getGradientColor = tgpu['~unstable']
 The `getGradientColor` function, when resolved to WGSL, includes the definitions of all used external resources:
 
 ```wgsl
-fn getBlue_1() -> f32 { return 0.941; }
+fn getBlue_1() -> vec4f { 
+  return vec4f(0.114, 0.447, 0.941, 1); 
+}
 
 fn getGradientColor_0(ratio: f32) -> vec4f {
   let color = mix(vec4f(0.769, 0.392, 1, 1), getBlue_1(), ratio);
@@ -82,8 +83,7 @@ const mainVertex = tgpu['~unstable']
   .vertexFn({
     in: { vertexIndex: d.builtin.vertexIndex },
     out: { outPos: d.builtin.position, uv: d.vec2f },
-  })
-  .does(/* wgsl */ `(input: VertexInput) -> VertexOutput {
+  })(/* wgsl */ `{
     var pos = array<vec2f, 3>(
       vec2(0.0, 0.5),
       vec2(-0.5, -0.5),
@@ -96,19 +96,19 @@ const mainVertex = tgpu['~unstable']
       vec2(1.0, 0.0),
     );
 
-    return VertexOutput(vec4f(pos[input.vertexIndex], 0.0, 1.0), uv[input.vertexIndex]);
+    return Out(vec4f(pos[in.vertexIndex], 0.0, 1.0), uv[in.vertexIndex]);
   }`);
 
 const mainFragment = tgpu['~unstable']
-  .fragmentFn({ in: { uv: d.vec2f }, out: d.vec4f })
-  .does(/* wgsl */ `(input: FragmentInput) -> @location(0) vec4f {
-    return getGradientColor((input.uv[0] + input.uv[1]) / 2);
+  .fragmentFn({ in: { uv: d.vec2f }, out: d.vec4f })(/* wgsl */ `{
+    return getGradientColor((in.uv[0] + in.uv[1]) / 2);
   }`)
   .$uses({ getGradientColor });
 ```
 
-When entry function inputs or outputs are specified as objects containing builtins and inter-stage variables, the WGSL implementations need to access these arguments as passed in via structs (see *VertexInput*, *VertexOutput*, *FragmentInput*). 
-TypeGPU schemas for these structs are created automatically by the library and their definitions are included when resolving the functions. The names referenced in the implementations do not matter.
+When entry function inputs or outputs are specified as objects containing builtins and inter-stage variables, the WGSL implementations need to access these arguments as passed in via structs. 
+TypeGPU schemas for these structs are created automatically by the library and their definitions are included when resolving the functions. 
+Input values are accessible through the `in` keyword, while the automatically created structs for input and output shall be referenced in implementation as `In` and `Out` respectively.
 
 ## Usage in pipelines
 

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

@@ -9,7 +9,7 @@ You can think of slots as holes in the shader that can be filled in from the out
 ```ts
 const filterColorSlot = tgpu.slot<vec3f>(); // => TgpuSlot<vec3f>
 
-const filter = tgpu.fn([vec3f]).does((color) => {
+const filter = tgpu.fn([vec3f])((color) => {
   const filterColor = filterColorSlot.$; // => vec3f
 
   return mul(color, filterColor);
@@ -29,7 +29,7 @@ const filterWithGreen = filter
 ```ts
 const safeLoopSlot = tgpu.slot(false);
 
-const processObjects = tgpu.fn([f32], f32).does(() => {
+const processObjects = tgpu.fn([f32], f32)(() => {
   let len = objects.length;
 
   if (safeLoopSlot.$) { // <- evaluated at compile time
@@ -49,12 +49,12 @@ const processObjects = tgpu.fn([f32], f32).does(() => {
 ```ts
 // physics.ts
 
-const defaultGravity = tgpu.fn([vec2f], vec2f).does(() => vec2f(0, 9.8));
+const defaultGravity = tgpu.fn([vec2f], vec2f)(() => vec2f(0, 9.8));
 
 export const getGravitySlot = tgpu.slot(defaultGravity);
 //           ^ TgpuSlot<TgpuFn<[Vec2f], Vec2f>>
 
-export const stepPhysics = tgpu.fn([]).does(() => {
+export const stepPhysics = tgpu.fn([])(() => {
   for (const obj of objects.$) {
     // Calling whatever implementation was provided.
     const gravity = getGravitySlot.$(obj.position);
@@ -70,15 +70,13 @@ export const stepPhysics = tgpu.fn([]).does(() => {
 import { stepPhysics, getGravitySlot } from './physics';
 
 const getGravityTowardsCenter = tgpu
-  .fn([vec2f], vec2f)
-  .does((position) => mul(normalize(position), -1));
+  .fn([vec2f], vec2f)((position) => mul(normalize(position), -1));
 
 const stepPhysicsAltered = stepPhysics
   .with(getGravitySlot, getGravityTowardsCenter);
 
 const main = tgpu
-  .computeFn()
-  .does(() => {
+  .computeFn()(() => {
     stepPhysicsAltered(); // <- Will use altered gravity.
   });
 ```

apps/typegpu-docs/src/content/docs/reference/naming-convention.mdx

@@ -25,8 +25,7 @@ We give tgpu functions *camelCase* names, without any special suffix or prefix.
 
 ```ts
 const createBoid = tgpu
-  .fn([], Boid)
-  .does(() => ({
+  .fn([], Boid)(() => ({
     pos: vec2f(),
     vel: vec2f(0, 1),
   }));

apps/typegpu-docs/src/content/docs/tutorials/triangle-to-boids/index.mdx

@@ -92,8 +92,7 @@ const VertexOutput = d.ioStruct({
 });
 
 const vertexMain = tgpu
-  .vertexFn([tgpu.builtin.vertexIndex], VertexOutput)
-  .does((idx) => {
+  .vertexFn([tgpu.builtin.vertexIndex], VertexOutput)((idx) => {
     const vertices = [
       vec2f(0, 0.5),
       vec2f(-0.5, -0.5),
@@ -108,8 +107,7 @@ const vertexMain = tgpu
   });
 
 const fragmentMain = tgpu
-  .fragmentFn([], vec4f)
-  .does(() => {
+  .fragmentFn([], vec4f)(() => {
     // let's go with a simple purple for now
     return vec4f(0.7686, 0.3922, 1.0, 1.0);
   });
@@ -122,8 +120,7 @@ what arguments it accepts, and what it should return:
 
 ```ts
 const vertexMain = tgpu
-  .vertexFn([tgpu.builtin.vertexIndex], VertexOutput)
-  .does(/* accept parameter of type (p0: number) => { position: vec4f } */);
+  .vertexFn([tgpu.builtin.vertexIndex], VertexOutput)(/* accept parameter of type (p0: number) => { position: vec4f } */);
 ```
 
 
@@ -1503,3 +1500,4 @@ import step9webgpu from 'code/step9-webgpu.ts?raw';
 
 Congratulations! You've successfully implemented the boids flocking algorithm in WebGPU using TypeGPU.
 Along the way, you learned about creating and using a TypeGPU runtime, writing shader code, managing buffers, creating pipelines, and using slots. For more information, refer to the TypeGPU documentation. Thank you for following along and happy coding!
+

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

@@ -9,8 +9,7 @@ export const computeShader = tgpu['~unstable']
   .computeFn({
     in: { gid: d.builtin.globalInvocationId },
     workgroupSize: [p.workGroupSize],
-  })
-  .does((input) => {
+  })((input) => {
     const fishIndex = input.gid.x;
     const fishData = layout.$.currentFishData[fishIndex];
     let separation = d.vec3f();
@@ -72,11 +71,11 @@ export const computeShader = tgpu['~unstable']
     }
 
     if (layout.$.mouseRay.activated === 1) {
-      const distanceVector = distanceVectorFromLine(
-        layout.$.mouseRay.pointX,
-        layout.$.mouseRay.pointY,
-        fishData.position,
-      );
+      const distanceVector = distanceVectorFromLine({
+        lineStart: layout.$.mouseRay.pointX,
+        lineEnd: layout.$.mouseRay.pointY,
+        point: fishData.position,
+      });
       const limit = p.fishMouseRayRepulsionDistance;
       const str =
         std.pow(2, std.clamp(limit - std.length(distanceVector), 0, limit)) - 1;

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

@@ -14,8 +14,7 @@ export const vertexShader = tgpu['~unstable']
   .vertexFn({
     in: { ...ModelVertexInput, instanceIndex: d.builtin.instanceIndex },
     out: ModelVertexOutput,
-  })
-  .does((input) => {
+  })((input) => {
     // rotate the model so that it aligns with model's direction of movement
     // https://simple.wikipedia.org/wiki/Pitch,_yaw,_and_roll
     const currentModelData = layout.$.modelData[input.instanceIndex];
@@ -88,8 +87,10 @@ export const vertexShader = tgpu['~unstable']
   .$name('vertexShader');
 
 const sampleTexture = tgpu['~unstable']
-  .fn([d.vec2f], d.vec4f)
-  .does(/* wgsl */ `(uv: vec2f) -> vec4f {
+  .fn(
+    { uv: d.vec2f },
+    d.vec4f,
+  )(/* wgsl */ `{
     return textureSample(layout.$.modelTexture, layout.$.sampler, uv);
   }`)
   .$uses({ layout })
@@ -99,13 +100,12 @@ export const fragmentShader = tgpu['~unstable']
   .fragmentFn({
     in: ModelVertexOutput,
     out: d.vec4f,
-  })
-  .does((input) => {
+  })((input) => {
     // shade the fragment in Phong reflection model
     // https://en.wikipedia.org/wiki/Phong_reflection_model
     // then apply sea fog and sea desaturation
 
-    const textureColorWithAlpha = sampleTexture(input.textureUV); // base color
+    const textureColorWithAlpha = sampleTexture({ uv: input.textureUV }); // base color
     const textureColor = textureColorWithAlpha.xyz;
 
     const ambient = std.mul(0.5, std.mul(textureColor, p.lightColor));

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

@@ -3,13 +3,18 @@ import * as d from 'typegpu/data';
 import * as std from 'typegpu/std';
 
 export const distanceVectorFromLine = tgpu['~unstable']
-  .fn([d.vec3f, d.vec3f, d.vec3f], d.vec3f)
-  .does((lineStart, lineEnd, point) => {
-    const lineDirection = std.normalize(std.sub(lineEnd, lineStart));
-    const pointVector = std.sub(point, lineStart);
+  .fn(
+    { lineStart: d.vec3f, lineEnd: d.vec3f, point: d.vec3f },
+    d.vec3f,
+  )((args) => {
+    const lineDirection = std.normalize(std.sub(args.lineEnd, args.lineStart));
+    const pointVector = std.sub(args.point, args.lineStart);
     const projection = std.dot(pointVector, lineDirection);
-    const closestPoint = std.add(lineStart, std.mul(projection, lineDirection));
-    return std.sub(point, closestPoint);
+    const closestPoint = std.add(
+      args.lineStart,
+      std.mul(projection, lineDirection),
+    );
+    return std.sub(args.point, closestPoint);
   })
   .$name('distance vector from line');
 
@@ -18,34 +23,34 @@ const ApplySinWaveReturnSchema = d.struct({
   normal: d.vec3f,
 });
 
-export const applySinWave = tgpu['~unstable']
-  .fn([d.u32, d.u32, d.vec3f, d.vec3f], ApplySinWaveReturnSchema)
-  .does((index, time, position, normal) => {
-    const a = 60.1;
-    const b = 0.8;
-    const c = 10.1;
-    // z += sin(index + (time / a + x) / b) / c
+export const applySinWave = tgpu['~unstable'].fn(
+  [d.u32, d.u32, d.vec3f, d.vec3f],
+  ApplySinWaveReturnSchema,
+)((index, time, position, normal) => {
+  const a = 60.1;
+  const b = 0.8;
+  const c = 10.1;
+  // z += sin(index + (time / a + x) / b) / c
 
-    const positionModification = d.vec3f(
-      0,
-      0,
-      std.sin(d.f32(index) + (d.f32(time) / a + position.x) / b) / c,
-    );
+  const positionModification = d.vec3f(
+    0,
+    0,
+    std.sin(d.f32(index) + (d.f32(time) / a + position.x) / b) / c,
+  );
 
-    const coeff =
-      std.cos(d.f32(index) + (d.f32(time) / a + position.x) / b) / c;
-    const newOX = std.normalize(d.vec3f(1, 0, coeff));
-    const newOZ = d.vec3f(-newOX.z, 0, newOX.x);
-    const newNormalXZ = std.add(
-      std.mul(normal.x, newOX),
-      std.mul(normal.z, newOZ),
-    );
+  const coeff = std.cos(d.f32(index) + (d.f32(time) / a + position.x) / b) / c;
+  const newOX = std.normalize(d.vec3f(1, 0, coeff));
+  const newOZ = d.vec3f(-newOX.z, 0, newOX.x);
+  const newNormalXZ = std.add(
+    std.mul(normal.x, newOX),
+    std.mul(normal.z, newOZ),
+  );
 
-    const wavedNormal = d.vec3f(newNormalXZ.x, normal.y, newNormalXZ.z);
-    const wavedPosition = std.add(position, positionModification);
+  const wavedNormal = d.vec3f(newNormalXZ.x, normal.y, newNormalXZ.z);
+  const wavedPosition = std.add(position, positionModification);
 
-    return ApplySinWaveReturnSchema({
-      position: wavedPosition,
-      normal: wavedNormal,
-    });
+  return ApplySinWaveReturnSchema({
+    position: wavedPosition,
+    normal: wavedNormal,
   });
+});