Pipelines

Recommended reading

It is assumed that you are familiar with the following concepts:

• WebGPU Fundamentals
• TypeGPU Functions

TypeGPU introduces a custom API to easily define and execute render and compute pipelines. It abstracts away the standard WebGPU procedures to offer a convenient, type-safe way to run shaders on the GPU.

Creating pipelines

A pipeline can be defined with one of the following methods on the root object:

• createRenderPipeline
• createComputePipeline
• createGuardedComputePipeline

const renderPipeline = root.createRenderPipeline({
  vertex: mainVertex,
  fragment: mainFragment,
  targets: { format: presentationFormat },
});

const computePipeline1 = root.createComputePipeline({
  compute: mainCompute,
});

const computePipeline2 = root.createGuardedComputePipeline((x, y, z) => {
  'use gpu';
  // ...
});

createRenderPipeline

The createRenderPipeline method creates a render pipeline by accepting an options object that specifies the vertex function, fragment function, targets, and optional additional settings.

• vertex: The TgpuVertexFn or 'use gpu' callback to use as the vertex shader.
• fragment: The TgpuFragmentFn or 'use gpu' callback to use as the fragment shader.
• targets: A record defining the formats and behaviors of the color targets, similar to WebGPU’s GPUColorTargetState, but as a record with named targets.
• depthStencil (optional): Depth-stencil state, same as WebGPU’s GPUDepthStencilState.
• multisample (optional): Multisample state, same as WebGPU’s GPUMultisampleState.
• primitive (optional): Primitive state, same as WebGPU’s GPUPrimitiveState.

The vertex function’s input parameters (non-builtin) are matched to vertex attributes specified in the pipeline’s vertex layout when executing. Vertex attributes are validated at the type level for compatibility.

const vertexLayout = tgpu.vertexLayout(d.arrayOf(d.vec2f));

const renderPipeline = root.createRenderPipeline({
  attribs: { pos: vertexLayout.attrib },
  vertex: mainVertex,
  fragment: mainFragment,
  targets: { format: presentationFormat },
  // Additional options can be specified here
  depthStencil: {
    format: 'depth24plus',
    depthWriteEnabled: true,
    depthCompare: 'less',
  },
  multisample: {
    count: 4,
  },
  primitive: { topology: 'triangle-list' },
});

Type-level validation

Using the pipelines should ensure the compatibility of the vertex output and fragment input on the type level. These parameters are identified by their names, not by their numeric location index. In general, when using vertex and fragment functions with TypeGPU pipelines, it is not necessary to set locations on the IO struct properties. The library automatically matches up the corresponding members (by their names) and assigns common locations to them. When a custom location is provided by the user (via the d.location attribute function) it is respected by the automatic assignment procedure, as long as there is no conflict between vertex and fragment location values.

import { tgpu, d } from 'typegpu';

const vertex = tgpu.vertexFn({
  out: { pos: d.builtin.position },
})`(...)`;
const fragment = tgpu.fragmentFn({
  in: { uv: d.vec2f },
  out: d.vec4f,
})`(...)`;

const root = await tgpu.init();

root.createRenderPipeline({
  vertex,
  fragment,
Error ts(2769)  ― No overload matches this call.
  Overload 3 of 3, '(descriptor: DescriptorBase & ({ attribs?: {} | undefined; vertex: TgpuVertexFn<{}, {}> | ((input: AutoVertexIn<InferGPURecord<AttribRecordToDefaultDataTypes<{}>>>) => AutoVertexOut<...>); fragment: ((input: AutoFragmentIn<...>) => v4f | (AnyAutoCustoms & Partial<...>)) | TgpuFragmentFn<...>; targets?: TgpuColorTargetState; } | { ...; })): TgpuRenderPipeline<...> | TgpuRenderPipeline<...>', gave the following error.
    Type 'TgpuFragmentFn<{ uv: Vec2f; }, Vec4f>' is not assignable to type '((input: AutoFragmentIn<InferGPURecord<{}>>) => v4f | (AnyAutoCustoms & Partial<InferGPURecord<{ readonly $fragDepth: BuiltinFragDepth; readonly $sampleMask: BuiltinSampleMask; }>>)) | TgpuFragmentFn<...> | TgpuFragmentFn<...> | ((input: AutoFragmentIn<...>) => undefined) | undefined'.
      Type 'TgpuFragmentFn<{ uv: Vec2f; }, Vec4f>' is not assignable to type 'TgpuFragmentFn<{} & Record<string, AnyFragmentInputBuiltin>, Vec4f>'.
        Property 'uv' is missing in type '{} & Record<string, AnyFragmentInputBuiltin>' but required in type '{ uv: Vec2f; }'.
  targets: { format: 'bgra8unorm' },
});

createComputePipeline

The createComputePipeline method creates a compute pipeline by accepting an options object with the compute function.

• compute: The TgpuComputeFn to use as the compute shader.

const computePipeline = root.createComputePipeline({
  compute: mainCompute,
});

Caution

The underlying WebGPU resources for TypeGPU pipelines are created lazily, just before the first execution or as part of a root.unwrap, not immediately after the createRenderPipeline or createComputePipeline invocation.

createGuardedComputePipeline

The createGuardedComputePipeline method streamlines running simple computations on the GPU. Instead of dispatching workgroups, the guarded pipeline allows calling an exact number of GPU threads. Think of it as a parallelized for loop. Under the hood, it creates a compute pipeline that calls the provided callback only if the current thread ID is within the requested range.

const data = root.createMutable(d.arrayOf(d.u32, 8), [0, 1, 2, 3, 4, 5, 6, 7]);

const doubleUpPipeline = root.createGuardedComputePipeline((x) => {
  'use gpu';
  data.$[x] *= 2;
});

doubleUpPipeline.dispatchThreads(8);
doubleUpPipeline.dispatchThreads(8);
doubleUpPipeline.dispatchThreads(5);

// the command encoder will queue the read after `doubleUpPipeline`
console.log(await data.read()); // [0, 8, 16, 24, 32, 20, 24, 28]

Tip

When using guarded compute pipelines, it is impossible to change workgroup sizes, or use builtins. The default workgroup sizes are:

• [1, 1, 1] for 0D dispatches,
• [256, 1, 1] for 1D dispatches,
• [16, 16, 1] for 2D dispatches,
• [8, 8, 4] for 3D dispatches.

The callback can have up to three arguments (dimensions). createGuardedComputePipeline can simplify writing a pipeline helping reduce serialization overhead when initializing buffers with data. Buffer initialization commonly uses random number generators. For that, you can use the @typegpu/noise library.

import { randf } from '@typegpu/noise';

const root = await tgpu.init();

// buffer of 1024x512 floats
const waterLevelMutable = root.createMutable(
  d.arrayOf(d.arrayOf(d.f32, 512), 1024),
);

root.createGuardedComputePipeline((x, y) => {
  'use gpu';
  randf.seed2(d.vec2f(x, y).div(1024));
  waterLevelMutable.$[x][y] = 10 + randf.sample();
}).dispatchThreads(1024, 512);
// callback will be called for x in range 0..1023 and y in range 0..511

// (optional) read values in JS
console.log(await waterLevelMutable.read());

Note

TgpuGuardedComputePipeline provides getters for the underlying pipeline and the size buffer. Those might be useful for tgpu.resolve, since you cannot resolve a guarded pipeline directly.

const innerPipeline = doubleUpPipeline.with(bindGroup1).pipeline;
tgpu.resolve([innerPipeline]);

Initialization

Pipeline initialization involves resolving the pipeline code, creating the shader module, and creating the underlying WebGPU pipeline. This happens automatically the first time the pipeline is executed via .draw, .dispatchWorkgroups, or a similar method. The initSync method lets you start the initialization early. To wait until initialization actually finishes on the device (fully avoiding a stall on first execution), use initAsync instead.

Note

For small and medium sized shaders, pipeline pre-initialization does not provide a noticeable performance improvement. Use initSync/initAsync only in larger applications, or in cases where your shaders are particularly large or numerous.

// Automatically calls `pipeline.initSync();`,
// then enqueues a dispatch.
pipeline.dispatchWorkgroups(1);

// If not already initialized, runs JS initialization,
// and issues pipeline initialization steps on the device.
pipeline.initSync();

// Enqueues a dispatch.
// Stall partially avoided because the pipeline is already resolved.
pipeline.dispatchWorkgroups(1);

// If not already initialized, runs JS initialization,
// and issues pipeline initialization steps on the device.
const initPromise = pipeline.initAsync();

// Awaits until the initialization finishes.
await initPromise;

// Enqueues a dispatch.
// Stall avoided, the pipeline is already resolved and initialized on the device.
pipeline.dispatchWorkgroups(1);

Execution

renderPipeline
  .withColorAttachment({ view: context })
  .draw(3);

computePipeline.dispatchWorkgroups(16);

guardedComputePipeline.dispatchThreads(4);

Attachments

Render pipelines require specifying a color attachment for each target. The attachments are specified in the same way as in the WebGPU API (but accept both TypeGPU resources and regular WebGPU ones). However, similar to the targets argument, multiple targets need to be passed in as a record, with each target identified by name.

Similarly, when using withDepthStencil it is necessary to pass in a depth stencil attachment, via the withDepthStencilAttachment method.

renderPipeline
  .withColorAttachment({
    color: {
      view: msaaTextureView,
      resolveTarget: context,
      loadOp: 'clear',
      storeOp: 'store',
    },
    shadow: {
      view: shadowTextureView,
      clearValue: [1, 1, 1, 1],
      loadOp: 'clear',
      storeOp: 'store',
    },
  })
  .withDepthStencilAttachment({
    view: depthTextureView,
    depthClearValue: 1,
    depthLoadOp: 'clear',
    depthStoreOp: 'store',
  })
  .draw(vertexCount);

Resource bindings

Before executing pipelines, it is necessary to bind all of the utilized resources, like bind groups, vertex buffers and slots. It is done using the with method. It accepts either a bind group (render and compute pipelines) or a vertex layout and a vertex buffer (render pipelines only).

// vertex layout
const vertexLayout = tgpu.vertexLayout(
  d.disarrayOf(d.float16),
  'vertex',
);
const vertexBuffer = root
  .createBuffer(d.disarrayOf(d.float16, 8), [0, 0, 1, 0, 0, 1, 1, 1])
  .$usage('vertex');

// bind group layout
const bindGroupLayout = tgpu.bindGroupLayout({
  size: { uniform: d.vec2u },
});

const sizeBuffer = root
  .createBuffer(d.vec2u, d.vec2u(64, 64))
  .$usage('uniform');

const bindGroup = root.createBindGroup(bindGroupLayout, {
  size: sizeBuffer,
});

// binding and execution
renderPipeline
  .with(vertexLayout, vertexBuffer)
  .with(bindGroup)
  .draw(8);

computePipeline
  .with(bindGroup)
  .dispatchWorkgroups(1);

Pipelines also expose a pipe method, which applies a function to the pipeline and returns its result. It lets a package hand out a reusable configuration step that binds everything it owns, instead of documenting a list of with calls.

const mesh = {
  vertices: root.createBuffer(vertexLayout.schemaForCount(3)).$usage('vertex'),
  indices: root.createBuffer(d.arrayOf(d.u32, 3)).$usage('index'),
  inject: () => <P extends TgpuRenderPipeline>(pipeline: P) =>
    pipeline.with(vertexLayout, mesh.vertices).withIndexBuffer(mesh.indices),
};

renderPipeline
  .pipe(mesh.inject())
  .drawIndexed(3);

Timing performance

Pipelines also expose the withPerformanceCallback and withTimestampWrites methods for timing the execution time on the GPU. For more info about them, refer to the Timing Your Pipelines guide.

draw, dispatchWorkgroups

After creating the render pipeline and setting all of the attachments, it can be put to use by calling the draw method. It accepts the number of vertices and optionally the instance count, first vertex index and first instance index. After calling the method, the shader is set for execution immediately.

Compute pipelines are executed using the dispatchWorkgroups method, which accepts the number of workgroups in each dimension.

Drawing with drawIndexed

The drawIndexed is analogous to draw, but takes advantage of index buffer to explicitly map vertex data onto primitives. When using an index buffer, you don’t need to list every vertex for every primitive explicitly. Instead, you provide a list of unique vertices in a vertex buffer. Then, the index buffer defines how these vertices are connected to form primitives.

const indexBuffer = root
  .createBuffer(d.arrayOf(d.u16, 6), [0, 2, 1, 0, 3, 2])
  .$usage('index');

const pipeline = root
  .createRenderPipeline({
    attribs: { color: vertexLayout.attrib },
    vertex,
    fragment: mainFragment,
    targets: { format: presentationFormat },
  })
  .withIndexBuffer(indexBuffer);

  pipeline
    .with(vertexLayout, colorBuffer)
    .drawIndexed(6);

Indirect dispatches and draws

Indirect methods read their execution parameters from a buffer, which allows a previous GPU operation to determine the amount of later work. Mark a typed buffer with .$usage('indirect') and use one of:

Method	Consecutive values read from the buffer
dispatchWorkgroupsIndirect	x: u32, y: u32, z: u32
drawIndirect	vertexCount: u32, instanceCount: u32, firstVertex: u32, firstInstance: u32
drawIndexedIndirect	indexCount: u32, instanceCount: u32, firstIndex: u32, baseVertex: i32, firstInstance: u32

const DispatchArgs = d.struct({
  x: d.u32,
  y: d.u32,
  z: d.u32,
});

const dispatchArgs = root
  .createBuffer(DispatchArgs, { x: 16, y: 8, z: 1 })
  .$usage('indirect');

computePipeline.dispatchWorkgroupsIndirect(dispatchArgs);

For an argument block nested inside a larger schema, pass the offset returned by d.memoryLayoutOf:

const FrameCommands = d.struct({
  frameIndex: d.u32,
  dispatch: DispatchArgs,
});

const commands = root.createBuffer(FrameCommands).$usage('indirect');
const dispatchOffset = d.memoryLayoutOf(FrameCommands, (value) => value.dispatch);

computePipeline.dispatchWorkgroupsIndirect(commands, dispatchOffset);

Raw GPUBuffer objects are also accepted. Offsets must be aligned to four bytes, and the required values must fit in a contiguous region of the buffer. drawIndexedIndirect additionally requires an index buffer bound with .withIndexBuffer(...).

WebGPU encoder interoperability

Render and compute pipelines can record commands into encoders that your application manages. Pass an existing encoder to .with(...) before drawing or dispatching:

const encoder = root.device.createCommandEncoder();

computePipeline
  .with(encoder)
  .dispatchWorkgroups(16);

renderPipeline
  .with(encoder)
  .withColorAttachment({ view: context })
  .draw(3);

root.device.queue.submit([encoder.finish()]);

With a GPUCommandEncoder, TypeGPU creates and ends the needed pass but leaves finishing and submitting the command buffer to you.

You can instead record directly into an existing pass:

const computePass = encoder.beginComputePass();
computePipeline.with(computePass).dispatchWorkgroups(16);
computePass.end();

const renderPass = encoder.beginRenderPass(renderPassDescriptor);
renderPipeline.with(renderPass).draw(3);
renderPass.end();

When passed a GPUComputePassEncoder or GPURenderPassEncoder, TypeGPU applies its pipeline and bind-group state to that pass without ending it. Render pipelines also accept a GPURenderBundleEncoder, allowing .draw(...), .drawIndexed(...), and their indirect variants to be recorded in a render bundle. The caller remains responsible for ending the pass or finishing the bundle.

Command encoders and passes

Experimental

createCommandEncoder and typed passes are unstable features. The API may be subject to change in the near future.

When a pipeline is executed directly via draw or dispatchWorkgroups, it records its own pass and submits it to the GPU queue immediately. For scenarios that require more control, such as executing multiple pipelines in a single render pass or batching multiple passes into a single submission, TypeGPU provides a typed equivalent of the WebGPU command encoder. It can be created with the createCommandEncoder method on the root object and mirrors GPUCommandEncoder, while accepting TypeGPU resources directly.

const encoder = root['~unstable'].createCommandEncoder();

const pass = encoder.beginRenderPass({
  colorAttachments: [{
    view: msaaTexture,
    resolveTarget: context,
  }],
  depthStencilAttachment: {
    view: depthTexture,
  },
});

scenePipeline.with(pass).draw(mesh.vertexCount);
lightPipeline.with(pass).draw(6, lightCount);
skyPipeline.with(pass).draw(3);

pass.end();
encoder.submit();

The beginRenderPass method accepts a descriptor similar to WebGPU’s GPURenderPassDescriptor, with a few conveniences:

• Attachment views can be TypeGPU textures, texture views and canvas contexts, as well as raw GPUTextureViews.
• loadOp, storeOp and depthClearValue default to 'clear', 'store' and 1 respectively. A single color attachment does not need to be wrapped in an array.
• occlusionQuerySet and timestampWrites accept TypeGPU query sets as well as raw GPUQuerySets.

There are two equivalent ways to execute pipelines in a pass. Passing the pass to pipeline.with(pass) keeps the pipeline-centric API, together with all of its with* methods. Alternatively, the pass itself mirrors the GPURenderPassEncoder API, while accepting TypeGPU resources.

pass.setPipeline(renderPipeline);
pass.setBindGroup(bindGroup);
pass.setVertexBuffer(vertexLayout, vertexBuffer);
pass.draw(3);

In both cases, the pipeline, bind groups, vertex and index buffers, and the stencil reference are applied lazily when a draw call is recorded, and only if they changed since the previous one. Both styles operate on the same pass state, resolved per draw with a fixed precedence: state set on the pass (pass.set*) wins over state held by the pipeline (pipeline.with*), which wins over the WebGPU defaults. Pass state persists until overwritten, regardless of which pipeline is drawn in between, while pipeline-held state applies only to draws of that pipeline.

Note

pipeline.with(pass).draw(...) sets the pass’s current pipeline, so a subsequent pass.draw(...) executes that pipeline, not one set earlier via pass.setPipeline(...).

Note that pipeline.with(pass) allocates a new pipeline wrapper on every call. When drawing the same pipeline repeatedly into one pass, bind it once (const bound = pipeline.with(pass)) and draw with bound in the loop, so that unchanged state is not re-applied on every draw. For values that change between draws, prefer pass-level state (pass.setBindGroup, pass.setImmediates) over the allocating with* methods.

Compute passes work the same way:

const encoder = root['~unstable'].createCommandEncoder();
const pass = encoder.beginComputePass();
computePipeline.with(pass).dispatchWorkgroups(16);
pass.end();
encoder.submit();

Calling encoder.submit() finishes the recording and submits it to the device queue. Shader console.log output and performance callbacks are processed as part of that submission.

Guarded compute pipelines (createGuardedComputePipeline) cannot record into passes or encoders, every dispatchThreads call submits on its own.

Whenever something is not covered by the typed API, the underlying WebGPU resources remain accessible:

• root.unwrap(encoder) and root.unwrap(pass) return the raw GPUCommandEncoder, GPURenderPassEncoder or GPUComputePassEncoder, which can be used e.g. for texture copies. Commands recorded this way are invisible to TypeGPU, so after unwrapping a pass, every draw applies its full state again.
• encoder.finish() returns the raw GPUCommandBuffer without submitting it, allowing manual batching via device.queue.submit([...]). TypeGPU never sees such a submission, so shader logs and performance callbacks are not processed for it.

Raw GPUCommandEncoders and pass encoders can also be passed to pipeline.with(...) directly, with the same limitations, since TypeGPU cannot know when they are submitted, nor what state has been set on them.

It is also possible to access the underlying WebGPU resources for the TypeGPU pipelines, by calling root.unwrap(pipeline). That way, they can be used with a regular WebGPU API, though this also requires unwrapping all the necessary resources.

const pipeline = root.createRenderPipeline({
  vertex: mainVertex,
  fragment: mainFragment,
  targets: { format: 'rg8unorm' },
});

const rawPipeline = root.unwrap(pipeline);
const rawPipeline: GPURenderPipeline

Immediates

Experimental

immediateVar is an unstable feature, built on top of a WebGPU proposal that is not yet universally available (Chrome 149+). The API may be subject to change in the near future.

Immediates are small pieces of data set directly on a pass, on a per-draw (or per-dispatch) basis, without the overhead of a buffer. They are WebGPU’s take on push constants. An immediate variable is defined with tgpu['~unstable'].immediateVar and used in shaders through its .$ property, like other TypeGPU resources.

const tint = tgpu['~unstable'].immediateVar(d.vec4f, d.vec4f(1)); // schema + optional default

const mainFragment = tgpu.fragmentFn({ out: d.vec4f })(() => tint.$);

The value is provided at execution time, either on the pipeline (pipeline.with(immediate, value)) or on the pass (pass.setImmediates), and can be changed between draws. A value set with pass.setImmediates takes precedence over the pipeline’s value, which takes precedence over the variable’s default. Pass overrides persist across draws and pipeline switches until another setImmediates call replaces them. Drawing with no value available throws a MissingImmediatesError.

Values are captured (serialized) the moment they are provided, which makes subsequent draws that reuse them essentially free. Mutating a vector after passing it has no effect until it is set again.

For per-draw changing data, an ArrayBuffer or typed array can be passed instead of a structured value. The bytes are copied verbatim with no serialization (the caller guarantees they match the schema’s memory layout), making a thousand different transforms across a thousand draws nearly as cheap as the raw WebGPU calls.

// on the pipeline
pipeline
  .with(tint, d.vec4f(1, 0, 0, 1))
  .withColorAttachment({ view: context })
  .draw(3);

// on the pass
const encoder = root['~unstable'].createCommandEncoder();
const pass = encoder.beginRenderPass({ colorAttachments: [{ view: context }] });
pass.setImmediates(tint, d.vec4f(1, 0, 0, 1));
pipeline.with(pass).draw(3);
pass.end();
encoder.submit();

Immediates come with a few WebGPU-imposed restrictions:

• Only one immediate variable can be used in a single shader. To pass multiple values, use a struct schema.
• The schema cannot contain arrays, atomics or booleans (use d.u32 or d.i32 instead).
• The size of the schema must be a multiple of 4 bytes (pad with d.size if needed, e.g. d.struct({ x: d.size(4, d.f16) })) and is limited by the device’s maxImmediateSize limit (64 bytes by default where supported). A higher limit can be requested at initialization via tgpu.init({ device: { requiredLimits: { maxImmediateSize: 128 } } }).

Feature detection and fallback

Immediates require the immediate_address_space WGSL language extension, which is not yet supported everywhere. Support can be checked via root.enabledWgslLanguageFeatures, and since immediate variables can fulfill accessors (alongside buffer usages and functions), an accessor can seamlessly fall back to a uniform buffer on unsupported hardware.

const viewProj = tgpu.accessor(d.mat4x4f);

const viewProjSource = root.enabledWgslLanguageFeatures.has('immediate_address_space')
  ? tgpu['~unstable'].immediateVar(d.mat4x4f)
  : root.createUniform(d.mat4x4f);

const pipeline = root
  .with(viewProj, viewProjSource)
  .createRenderPipeline({ vertex: mainVertex, fragment: mainFragment });

// per frame:
if (isImmediateVar(viewProjSource)) {
  pass.setImmediates(viewProjSource, viewProjMatrix);
} else {
  viewProjSource.write(viewProjMatrix);
}

On the fallback path, buffer.write(...) queues a buffer update rather than recording a command between draws. To use different values for draws within one pass, give each distinct value its own uniform buffer and bind group.