Resolve

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:

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:

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);
}

Tip

If you wish to resolve just a single TGSL function and its dependencies, you can call resolve with that function in the externals and with no template.

const multiply = tgpu.fn([d.u32], d.u32)((n) => 2 * n);

const resolved = tgpu.resolve({ externals: { multiply } });

console.log(resolved);
// fn multiply_0(n: u32) ->  u32{
//   return (2 * n);
// }

You can also resolve TypeGPU schemas or even entire pipelines the same way.

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 via the layout.bound property.

  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 .$name call, an object is named based on its associated key in externals. This approach makes all 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.

Note

If you are using the TypeGPU Build Plugin, then most TypeGPU resources will be auto-named for you.

// before unplugin-typegpu
const myStruct = d.struct({ pos: d.vec3f });

// after unplugin-typegpu
const myStruct = d.struct({ pos: d.vec3f }).$name("myStruct");

This does not work for all resources. For example, a resource created in a function return statement will not be auto-named.

resolveWithContext

Sometimes, it may not be clear which bind group layouts were used in a given resolution. This may occur especially when using:

• Buffer usages/shorthands, which use a hidden, automatically created “catchall” bind group,
• TypeGPU functions implemented in TGSL, which generate their externals automatically.

For these cases, you can use tgpu.resolveWithContext, which has the same input API as tgpu.resolve, but in addition to the resolved code, it also returns information about the layouts used. tgpu.resolveWithContext returns an object with 3 props:

• code - the resolved code,
• usedBindGroupLayouts - a list of used tgpu.bindGroupLayout,
• catchall - a two-element array containing the bind group constructed for buffer usages and buffer shorthands, preceded by its index.

An example, where the “catchall” bind group is created:

const countMutable = root.createMutable(d.u32);

const { code, usedBindGroupLayouts, catchall } = tgpu.resolveWithContext({
  template: `
    fn exampleFn() {
      countMutable += 1;
    }
  `,
  externals: { countMutable },
});

console.log(code); // same as tgpu.resolve(...)
console.log(usedBindGroupLayouts); // an array containing the catchall bind group layout
console.log(catchall?.[0]); // 0 - the group index of the catchall bind group
console.log(catchall?.[1]); // the catchall bind group

An example, where a bind group layout is automatically included via a TGSL function:

const myLayout = tgpu.bindGroupLayout({ count: { uniform: d.u32 } });

const exampleFn = tgpu.fn([])(() => {
  myLayout.$.count += 1;
});

const { code, usedBindGroupLayouts, catchall } = tgpu.resolveWithContext({
  externals: { exampleFn },
});

console.log(code); // same as tgpu.resolve(...)
console.log(usedBindGroupLayouts); // [myLayout]
console.log(catchall); // undefined