Slots

Slots are a powerful dependency injection mechanism in TypeGPU that allows you to write shader logic without having to tightly couple to specific resources. Similarly to bind group layouts, you can think of slots as of typed “holes” in TypeGPU shaders, that can be filled in later on from the outside. The main differences between slots and bound resources include the following:

• Slots are filled in before the shader module compile time, instead of just before the shader execution starts.
• Slots can contain not only buffers, but also basically any JavaScript value, even TypeGPU functions.

Main use cases for slots include:

• Generics — instead of rewriting a function for each generic parameter, it suffices to fill a slot with a different value.
• Passing callbacks — high-level libraries based on TypeGPU can leave slots for user-defined functions to call.

Basic usage

A slot is created using the tgpu.slot() function and can optionally take a default value:

const filterColorSlot = tgpu.slot<d.v3f>(); // Slot for a 3D vector.
const mySlot = tgpu.slot<number>(42); // Slot with a default value.

interface Config {
  fogEnabled: boolean;
  tint: d.v3f;
}

const configSlot = tgpu.slot<Config>();

You can access a slot’s value using .$:

const value = mySlot.$;

Caution

Slot values can only be accessed inside TypeGPU functions. Attempting to access them outside will throw an error.

Slots are resolved during the TypeGPU resolution phase. The slot object itself does not hold any value. Instead, you can bind it in one of two ways.

Binding after defining a function

The first way to bind a value to a slot is to call the with method on a wrapped TypeGPU function:

const filterColorSlot = tgpu.slot<d.v3f>();

const filter = (color: d.v3f): d.v3f => {
  'use gpu';
  const filterColor = filterColorSlot.$;
  return color.mul(filterColor);
};

// Bind the filter function with a red color.
const filterWithRed = tgpu.fn(filter)
  .with(filterColorSlot, d.vec3f(1, 0, 0));

// Bind the filter function with a green color.
const filterWithGreen = tgpu.fn(filter)
  .with(filterColorSlot, d.vec3f(0, 1, 0));

In the example above, after resolution we are left with two different WGSL functions:

fn filter_0(color: vec3f) ->  vec3f{
  var filterColor = vec3f(1, 0, 0);
  return (color * filterColor);
}

fn filter_1(color: vec3f) ->  vec3f{
  var filterColor = vec3f(0, 1, 0);
  return (color * filterColor);
}

Binding during pipeline creation

The other way to fill in a slot is to call the with method during the creation of a TgpuComputePipeline or TgpuRenderPipeline:

const resultBuffer = root.createMutable(d.i32, 0);
const multiplierSlot = tgpu.slot<number>();

const computeMultiply = tgpu.computeFn({ workgroupSize: [1] })(() => {
  resultBuffer.$ = resultBuffer.$ * multiplierSlot.$;
});

const pipeline = root
  .with(multiplierSlot, 3)
  .createComputePipeline({ compute: computeMultiply });

The pipeline above resolves to the following WGSL:

@group(0) @binding(0) var<storage, read_write> resultBuffer_1: i32;

@compute @workgroup_size(1) fn computeMultiply_0(){
  resultBuffer_1 = (resultBuffer_1 * 3);
}

Note

Static code analysis does not verify whether all slots have been filled. If you forget to assign a value to a slot, a runtime error will be thrown instead.

Inversion of control

Slots allow libraries to expose customization points to their users. They enable internal behavior to be modified without sacrificing type safety or performance.

physics.ts

const defaultGravity = tgpu.fn([d.vec2f], d.vec2f)((pos) => {
  return d.vec2f(0, -9.8);
});

export const gravitySlot = tgpu.slot(defaultGravity);
const gravitySlot: TgpuSlot<TgpuFn<(pos: d.Vec2f) => d.Vec2f>>

export const stepPhysics = tgpu.fn([])(() => {
  for (const obj of objects.$) {
    // Calling whatever implementation was provided.
    const gravity = gravitySlot.$(obj.position);

    obj.velocity = add(obj.velocity, mul(gravity, deltaTime.$));
  }
});

main.ts

import { stepPhysics, gravitySlot } from './physics.ts';

const gravityTowardsCenter = tgpu.fn([vec2f], vec2f)((pos) => {
  return mul(normalize(pos), -1);
});

const stepPhysicsCustomized = stepPhysics
  .with(gravitySlot, gravityTowardsCenter);

const main = tgpu.computeFn()(() => {
  stepPhysicsCustomized(); // <- Will use altered gravity.
});

Lazy values

tgpu.lazy(compute) defers a JavaScript computation until shader resolution. Its result is memoized for the current resolution namespace and slot bindings, so shared dependencies are computed only once. Access the resolved value with .$, just like a slot:

const componentCount = tgpu.slot(4);

const ResultArray = tgpu.lazy(() =>
  d.arrayOf(d.f32, componentCount.$)
);

const createResult = tgpu.fn([])(() => {
  const result = ResultArray.$();
});

const createShortResult = createResult.with(componentCount, 2);

A lazy computation can read slots, accessors, and other lazy values. Use .with(slotOrAccessor, value) on the lazy object when it should carry a binding into its computation and into resources returned from it.

const configuredResult = ResultArray.with(componentCount, 8);

Caution

Create lazy objects while defining your program, not from inside another lazy computation or while shader resolution is already in progress. Their .$ value is only available during resolution.

Composable configuration

Every configurable TypeGPU object supports .pipe(transform). It lets libraries package a set of slot or accessor bindings as a reusable configuration transform:

import type { Configurable } from 'typegpu';

const lightingEnabled = tgpu.slot(false);
const lightCount = tgpu.slot(0);

const injectLighting = (cfg: Configurable) =>
  cfg
    .with(lightingEnabled, true)
    .with(lightCount, 4);

const configuredRoot = root.pipe(injectLighting);

The transform receives the current configurable object and must return a configurable object. Transforms can be chained and can themselves call .with(...) or another .pipe(...), making them useful for library-level feature injection.

Slots in raw WGSL

It is possible to use slots even in TypeGPU functions that are implemented in WGSL:

const colorSlot = tgpu.slot(d.vec3f(1, 0, 0));

const getColor = tgpu.fn([], d.vec3f)`() {
  return colorSlot;
}`.$uses({ colorSlot });

The code above resolves to the following WGSL:

fn getColor() -> vec3f {
  return vec3f(1, 0, 0);
}