Merge pull request #603 from software-mansion/0.3

0.3

Author: mhawryluk

apps/typegpu-docs/astro.config.mjs

@@ -109,7 +109,6 @@ export default defineConfig({
             {
               label: 'Roots',
               slug: 'fundamentals/roots',
-              badge: { text: '0.2' },
             },
             {
               label: 'Buffers',
@@ -122,7 +121,11 @@ export default defineConfig({
             {
               label: 'Bind Groups',
               slug: 'fundamentals/bind-groups',
-              badge: { text: '0.2' },
+            },
+            {
+              label: 'Resolve',
+              slug: 'fundamentals/resolve',
+              badge: { text: '0.3' },
             },
             DEV && {
               label: 'Slots',
@@ -145,15 +148,14 @@ export default defineConfig({
         {
           label: 'Integration',
           items: stripFalsy([
-            DEV && {
+            {
               label: 'WebGPU Interoperability',
               slug: 'integration/webgpu-interoperability',
               badge: { text: 'new' },
             },
             {
               label: 'Working with wgpu-matrix',
               slug: 'integration/working-with-wgpu-matrix',
-              badge: { text: 'new' },
             },
           ]),
         },
@@ -163,7 +165,6 @@ export default defineConfig({
             {
               label: 'Generator CLI',
               slug: 'tooling/tgpu-gen',
-              badge: { text: 'new' },
             },
           ]),
         },

apps/typegpu-docs/src/components/roadmap/MilestoneLinkerBadge.astro

@@ -26,7 +26,7 @@ const fooBuffer = ...;
 const barTexture = ...;
 
 // Create a bind group that can fulfill the required layout.
-const fooBindGroup = fooLayout.populate({
+const fooBindGroup = root.createBindGroup(fooLayout, {
   foo: fooBuffer,
   bar: barTexture,
 });
@@ -124,6 +124,10 @@ Matching WGSL statement:
 Apart from being able to specify any data type, we can signal that the shader is generalized to work on
 arbitrarily sized data by passing a function.
 
+:::note
+Runtime-sized arrays are only usable with **storage** buffers.
+:::
+
 ```ts
 // main.ts
 const Filter = (n: number) =>
@@ -195,7 +199,7 @@ You can see the list of supported storage texture formats [here](https://www.w3.
 ## Bind Groups
 
 Before execution of a pipeline, any bind group that matches a given layout can be put in its place and used by the shader.
-To create a bind group, you can call the `populate` method on the bind group layout and associate each named key with
+To create a bind group, you can call the `createBindGroup` method on the [root object](/TypeGPU/fundamentals/roots) and associate each named key with
 a proper resource.
 
 ```ts
@@ -205,13 +209,13 @@ const fooLayout = tgpu.bindGroupLayout({
   // ...
 });
 
-const fooBindGroup0 = fooLayout.populate({
+const fooBindGroup0 = root.createBindGroup(fooLayout, {
   key1: ...,
   key0: ...,
   // ...
 });
 
-const fooBindGroup1 = fooLayout.populate({
+const fooBindGroup1 = root.createBindGroup(fooLayout, {
   key0: ...,
   key1: ...,
   // ...

apps/typegpu-docs/src/content/docs/fundamentals/bind-groups.mdx

@@ -189,6 +189,14 @@ If you pass an unmapped buffer, the data will be written to the buffer using `GP
 If you passed your own buffer to the `root.createBuffer` function, you need to ensure it has the `GPUBufferUsage.COPY_DST` usage flag if you want to write to it using the `write` method.
 :::
 
+There's also an option to copy value from another typed buffer using the `.copyFrom(buffer)` method, 
+as long as both buffers have a matching data schema.
+
+```ts
+const backupParticleBuffer = root.createBuffer(Particle);
+backupParticleBuffer.copyFrom(particleBuffer);
+```
+
 ## Reading from a buffer
 
 To read data from a buffer, you can use the `.read()` method.

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

@@ -0,0 +1,127 @@
+---
+title: Resolve
+description: Resolve API can be used to extend shader code with WGSL definitions of TypeGPU-defined objects.
+---
+
+Defining shader schemas and objects in JS/TS has lots of benefits, but having to keep them in sync with the corresponding WGSL code is hard to maintain.
+The `tgpu.resolve` API takes in a WGSL template, all TypeGPU schemas that you want to use in the shader, and generates a ready-to-use WGSL bundle.
+
+:::note
+`tgpu.resolve` is essentially a dedicated TypeGPU linker.
+:::
+
+Here's an example:
+```ts
+import tgpu from 'typegpu';
+import * as d from 'typegpu/data';
+
+const LightSource = d
+  .struct({
+    ambientColor: d.vec3f,
+    intensity: d.f32,
+  })
+  .$name('Source');
+// ^ giving the struct an explicit name (optional)
+
+const layout = tgpu
+  .bindGroupLayout({
+    lightSource: { uniform: LightSource },
+    sampling: { sampler: 'filtering' },
+    bgTexture: { externalTexture: {} },
+  })
+  .$idx(0);
+// ^ forces code-gen to assign `0` as the group index (optional)
+
+const rawShader = /* wgsl */ `
+  @fragment
+  fn main(@location(0) uv: vec2f) -> @location(0) vec4f {
+    var bgColor = textureSampleBaseClampToEdge(bgTexture, sampling, uv).rgb;
+
+    var newSource: LightSource;
+    newSource.ambientColor = (bgColor + lightSource.ambientColor) * factor;
+    newSource.intensity = 0.6;
+
+    return vec4f(newSource.ambientColor, newSource.intensity);
+  }
+`;
+
+const resolved = tgpu.resolve({
+  template: rawShader,
+  externals: {
+    // mapping names in the template to corresponding resources/values
+    LightSource,
+    factor: d.vec3f(0.4, 0.6, 1.0),
+    ...layout.bound,
+  },
+});
+```
+
+Resolved WGSL shader code is as follows:
+
+```wgsl
+struct Source_0 {
+  ambientColor: vec3f,
+  intensity: f32,
+}
+
+@group(0) @binding(0) var<uniform> lightSource_1: Source_0;
+@group(0) @binding(1) var sampling_2: sampler;
+@group(0) @binding(2) var bgTexture_3: texture_external;
+
+@fragment
+fn main(@location(0) uv: vec2f) -> @location(0) vec4f {
+  var bgColor = textureSampleBaseClampToEdge(bgTexture_3, sampling_2, uv).rgb;
+
+  var newSource: Source_0; // identifiers for references are generated based on the chosen naming scheme
+  newSource.ambientColor = (bgColor + lightSource_1.ambientColor) * vec3f(0.4, 0.6, 1);
+  newSource.intensity = 0.6;
+
+  return vec4f(newSource.ambientColor, newSource.intensity);
+}
+```
+
+## Template
+
+This optional property of the `tgpu.resolve` function argument is a string containing WGSL code, that is meant to be extended with additional definitions. 
+It can contain references to objects passed in the `externals` record.
+
+## Externals
+
+This is a record with TypeGPU objects that are to be included in the final resolved shader code. 
+The values in the mapping are the objects themselves, while the keys are the names by which they are referenced in the template code.
+Each object is resolved to its WGSL declaration, which is included in the final shader code.
+Moreover each reference to the object in the template is replaced with the name used in its newly generated declaration.
+
+If an object is being referenced only by another TypeGPU object in *externals*, it doesn't have to be included in the record.
+Any passed-in object's dependencies are automatically resolved and included in the final result.
+
+:::note
+To resolve bindings you can access each entry of a [bindGroupLayout](/TypeGPU/fundamentals/bind-groups) via the `layout.bound` property.
+
+```ts
+  externals: {
+    lightSource: layout.bound.lightSource,
+    sampling: layout.bound.sampling,
+    bgTexture: layout.bound.bgTexture,
+  }
+
+  // As long as the names in the shader match the
+  // layout keys, it can be shortened to:
+  externals: {
+    ...layout.bound,
+  }
+```
+:::
+
+## Naming scheme
+
+When externals are being resolved, they are given new names based on the specified naming scheme (`names` parameter).
+
+The default naming scheme is `"random"`. It uses labels assigned to the objects via `.$name("foo")` method or, if they aren't present, the keys in the *externals* record. 
+In this mode labels are later transformed to match the allowed identifier pattern, as well as include some unique suffix to ensure that no identifiers conflict with each other. 
+
+Another allowed value of the parameter is `"strict"` which names resolved objects in the WGSL code exactly as they are labeled by the user in JS,
+unless there is a name conflict, in which case a suffix is added.
+If there is no explicit *.$name* call, an object is named based on its associated key in *externals*. 
+This approach makes all of the generated identifiers predictable, but demands that all labels are valid identifiers 
+and requires explicit naming (via `.$name`) of all objects that aren't immediate values in the *externals* record.

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

@@ -52,14 +52,17 @@ untyped value of a typed resource, use the `root.unwrap` function.
 
 | Function | Description |
 | --- | --- |
-| `root.unwrap(resource: TgpuBuffer<AnyTgpuData>)` | Returns a `GPUBuffer`. |
+| `root.unwrap(resource: TgpuBuffer<AnyData>)` | Returns a `GPUBuffer`. |
 | `root.unwrap(resource: TgpuBindGroupLayout)` | Returns a `GPUBindGroupLayout`. |
 | `root.unwrap(resource: TgpuBindGroup)` | Returns a `GPUBindGroup`. |
+{/* | `root.unwrap(resource: TgpuTexture)` | Returns a `GPUTexture`. | */}
+{/* | `root.unwrap(resource: TgpuReadonlyTexture \| TgpuWriteonlyTexture \| TgpuMutableTexture \| TgpuSampledTexture)` | Returns a `GPUTextureView`. | */}
 
 
 ## Destroying resources
 
 Calling `root.destroy()` will destroy all resources created with it.
+It will also destroy the underlying WebGPU device, if it wasn't originally passed in via the `initFromDevice` function.
 
 ```ts
 root.destroy(); // <- frees up all the resources

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

@@ -1,6 +1,5 @@
 ---
 title: WebGPU Interoperability
-draft: true
 ---
 
 TypeGPU is built in a way that allows you to pick and choose the primitives you need, incrementally adopt them into your project and have a working app at each step
@@ -46,13 +45,6 @@ const rawNumbersBuffer = root.unwrap(numbersBuffer); // => GPUBuffer
 // they are essentially the same resource.
 ```
 
-```ts
-const fooTexture = root.createTexture({ ... }).$usage('sampled');
-//    ^? TgpuTexture<...> & Sampled
-
-const rawFooTexture = root.unwrap(fooTexture); // => GPUTexture
-```
-
 ```ts
 const bindGroup = root.createBindGroup(layout, { ... });
 //    ^? TgpuBindGroup<...>
@@ -291,13 +283,13 @@ const layout = tgpu.bindGroupLayout({
 -});
 +}).$idx(0); // <- forces code-gen to assign `0` as the group index.
 
-const rawShader = /* wgsl*/ `
+const rawShader = /* wgsl */ `
 -  @group(0) @binding(0) var<uniform> ambientColor: vec3f;
 -  @group(0) @binding(1) var<uniform> intensity: f32;
 -
   @fragment
   fn main() -> @location(0) vec4f {
-    return vec4f(ambientColor * intensity), 1.);
+    return vec4f(ambientColor * intensity, 1.);
   }
 `;
 
@@ -322,5 +314,5 @@ Benefits gained:
 - **Reduced fragility** - binding indices are now being handled end-to-end by TypeGPU, leaving human-readable keys
   as the way to connect the shader with JavaScript.
 - **Single source of truth** - typed bind group layouts not only describe JS behavior, but also WGSL behavior. This
-  allows `tgpu.resolve` to generate the appropriate WGSL code. Definitions of structs used as part of the layout will
+  allows [`tgpu.resolve`](/TypeGPU/fundamentals/resolve) to generate the appropriate WGSL code. Definitions of structs used as part of the layout will
   also be included in the returned shader code.

apps/typegpu-docs/src/content/docs/integration/webgpu-interoperability.mdx

@@ -328,13 +328,13 @@ buffer1 = root
   .createBuffer(arrayOf(u32, length))
   .$usage("storage", "vertex");
 
-const bindGroup0 = bindGroupLayoutCompute.populate({
+const bindGroup0 = root.createBindGroup(bindGroupLayoutCompute, {
   size: sizeBuffer,
   current: buffer0,
   next: buffer1,
 });
 
-const bindGroup1 = bindGroupLayoutCompute.populate({
+const bindGroup1 = root.createBindGroup(bindGroupLayoutCompute, {
   size: sizeBuffer,
   current: buffer1,
   next: buffer0,