Passes

latticeThin beams turning over a sky, embers rising through them, smoothed over frames with TAA.

PauseOpen the full example

The sky, beams and embers share one description for colour, TAA motion and depth. The description runs taa.motion for each drawing. Grey means still, colour means motion and black means no motion output. Drag horizontally to turn the camera. Put the embers in scene.without('motion') to keep the motion beneath them. Only the beams appear in depth, because the sky and embers test depth without writing it.

TAA needs motion vectors and a pick of your own needs ids at each pixel. Every renderer must write these alongside colour. Implementing each output separately in every renderer duplicates shader code. Renderers without the required data, such as particles without ids, also need a rule for that target.

passes.create defines what each target holds. A renderer supplies a drawing with a vertex function, a surface containing per-pixel data such as colour or id, and a draw call. scene.add(drawing) builds a pipeline that computes every output from that surface. scene.record(frame, drawn) draws it into the targets.

import { d } from 'typegpu';
import { passes } from '@typegpu/kit';

const screen = targets.create(root, surface, {
  hdr: { format: 'rgba16float', sampled: true },
  motion: { format: 'rg16float', sampled: true },
  depth: { format: 'depth24plus', sampled: true },
});
const scene = passes
  .create(root, screen, { hdr: passes.color, motion, depth: passes.depth })
  .pipe(view.inject());

// What each vertex carries to its pixels, and what the renderer knows at a pixel
const Corner = d.struct({ position: d.vec4f, world: d.vec3f });
const Seen = d.struct({ color: d.vec4f });

const at = (vertexIndex: number, instanceIndex: number) => {
  'use gpu';
  const corners = [d.vec3f(-1, 0, 0), d.vec3f(1, 0, 0), d.vec3f(0, 2, 0)];
  const world = corners[vertexIndex]! + d.vec3f(d.f32(instanceIndex) * 3, 0, 0);
  return Corner({ position: cameras.current.$.viewProjection * d.vec4f(world, 1), world });
};
const surfaceOf = (corner: d.Infer<typeof Corner>) => {
  'use gpu';
  return Seen({ color: d.vec4f(corner.world * 0.25 + 0.5, 1) });
};

// Four triangles, drawn into every target the scene describes
const triangles = scene.add({
  Vertex: Corner,
  at,
  surfaceOf,
  color: passes.shaded,
  draw: (pass) => pass.draw(3, 4),
});
await scene.initAsync();

frames.animate(frames.create(root, (frame) => scene.record(frame, triangles)));

passes.create(root, surface) draws each renderer’s colour into the canvas without extra targets or outputs.

Drawing into your own texture

passes.create takes a target set or a surface, { format, view(frame), width, height } with an optional pixelRatio. The surface form is for textures created outside the kit, such as a canvas. A texture you create to draw into and sample elsewhere, such as a label, a decal or a mirror, is a target set. targets.create takes any { width, height } and sizes a fixed set once, when it is created:

import { passes, targets } from '@typegpu/kit';

const size = { width: 512, height: 256, pixelRatio: 1 };
const page = targets.create(root, size, { ink: { format: 'rgba8unorm', sampled: true } });
const tags = text.create(root, font, { capacity: 1, length: 3, place: text.screen });
const paint = passes.create(root, page, { ink: passes.color });
const drawn = paint.add(tags.drawing);
tags.labels.patch({ 0: { position: [330, 128, 0.5], color: [1, 1, 1, 1] } });

// When the value changes, draw it into the page before the passes that sample it
tags.write(0, '42', { em: 180, align: 'right' });
paint.record(frame, drawn);

// Sample it from another shader, such as a floor's
const ink = page.textures.ink.createView();

The jelly slider draws its value this way and samples it from the floor under the jelly.

Drawings

A drawing of one pipeline is a plain object, a passes.Drawing<Vertex, Surface>:

Field	Default
Vertex	required	A struct whose position is in clip space. Its other fields reach surfaceOf interpolated, where position is the pixel’s.
at(vertexIndex, instanceIndex)	required	Makes one Vertex.
draw(pass)	required	Records its draw into the pass, which holds the pipeline the description built, bound to indices when it gives them.
surfaceOf(vertex)	needed for colour	Its surface, which every output’s write reads.
color	needed for colour	Its own output into passes.color, such as passes.shaded.
indices	none	An index buffer its draw reads, bound to each pipeline built for it. drawIndexed throws without.
label	none	Names its pipelines. The kit’s drawings have one; scene.add({ ...sparks.drawing, label: 'sparks' }) renames it.
blend	none	The blend of the color target.
translucent	false	Draws it as a translucent layer, in any order.
writeMask	every channel	The write mask of the color target. 0 writes no colour target and no output, for a pass of depth alone.
depth	{ depthWriteEnabled: true, depthCompare: 'less' }	WebGPU’s depth-stencil state without its format. A blended drawing that tests the depth without writing it gives depthWriteEnabled: false.
depthOf(surface)	none	A depth of its own for each pixel, such as the point an impostor shows, with the description’s bias added. Left out without a depth target.
cutout(vertex)	none	True where the pixel is cut out of the shape, discarded before surfaceOf. Into depth alone it runs without surfaceOf unless depthOf does.
invariant	false	Computes position alike in every pipeline built from this vertex, so a later pass can test the depth an earlier one wrote for equal.
flat	none	Fields of the vertex that reach the pixels flat, the same across a primitive. Integers always do.
linear	none	Fields of the vertex interpolated in screen space without perspective, such as a distance across a shape extruded on screen.
primitive	WebGPU’s	The pipeline’s primitive state, such as { cullMode: 'back' }.
alphaToCoverage	false	Covers the share of samples the color output’s alpha gives, when multisampled.
sampleMask(vertex, surface)	every sample	The samples each pixel writes when multisampled, bit i for sample i, such as the share one drawing hands to another. Takes no alphaToCoverage, so fold coverage into the mask.
inject()	none	Fills what its shaders read, before what is piped into the description, which wins.
initAsync()	none	Compiles what it needs besides the pipeline, such as its kernels.

passes.fullScreen is the Vertex and at of one triangle that covers the screen at depth 0, drawn with draw(3).

• Each description a drawing is added to builds a pipeline of its own, for its targets, jitter, samples and fills. A renderer gives its drawing, scene.add(particles.drawing), and holds no pipeline.
• Every target in a description has the same sample count. passes.create reads it once to build pipelines. To change MSAA, create another target set and description, then add each drawing again. Destroy the old description to free its compound drawings’ per-view work.
• A drawing whose surface can’t feed an output fails to type-check at add, naming the output, until without leaves it out.
• add returns a passes.Drawn. drawn.draw(pass) records into a pass from begin. drawn.destroy() removes it from the description’s compilation list and makes its draw throw.
• scene.destroy() destroys every drawing added to it and to the descriptions pipe, without and instead made from it. The targets stay yours.

What color takes

color requires an output. Passing a function such as color: (s) => s.color fails to type-check at add. passes.shaded writes the surface’s color field as it is. Any other colour is an output of your own whose write reads the surface:

// The surface's colour, premultiplied for `pipelines.blend.over`
const premultiplied = passes.output(d.vec4f, {
  write: (surface: { readonly color: d.v4f }) => {
    'use gpu';
    return d.vec4f(surface.color.xyz * surface.color.w, surface.color.w);
  },
});

const veil = scene.add({ ...drawing, color: premultiplied, blend: pipelines.blend.over });

Compound drawings

A renderer with several pipelines or per-view resources supplies a passes.Compound object with build(into). Per-view resources can include a list of objects visible to a camera. Each description calls build once, so the shadow and scene get separate pipelines. build creates them with into.pipeline(drawing) and returns a passes.Built with draw, initAsync and an optional destroy for per-view cleanup. Instances renderers use this form.

These drawings share a vertex function. Their two pipelines draw a fill, then an outline:

const outlined: passes.Compound<Seen, d.Infer<typeof Corner>> = {
  build(into) {
    const filling = into.pipeline(fill);
    const rimming = into.pipeline(rim);
    return {
      draw(pass) {
        pass.setPipeline(filling);
        pass.draw(4, count);
        pass.setPipeline(rimming);
        pass.draw(4, count);
      },
      async initAsync() {
        await Promise.all([filling.initAsync(), rimming.initAsync()]);
      },
    };
  },
};

const drawn = scene.add(outlined);

For a createRenderPipeline of your own, into.stages(drawing) gives a drawing’s stages, targets and depth state to spread into it.

In a description with layers, into.layers is how many there are, for per-layer work such as a visible list for each. The built draw(pass, layer) receives the layer of the pass it draws into, to pick that layer’s work.

Outputs

passes.output(schema, spec) defines the value each renderer writes per pixel to one target:

• write(surface, carried) runs per pixel and returns a value of schema. Its first parameter types the required surface data. (surface: { id: number }) requires an id, so only surfaces with that field can write it.
• vary(vertex, before) runs per vertex and returns a varyings struct. The rasteriser interpolates it for write’s carried parameter. With previous: true, before holds last frame’s vertex. The renderer’s vertex code compiles again with history.previously to read last frame’s camera and other temporal fills.
• clear is what the target holds where nothing drew, zero by default. The color target clears to the description’s clear option instead.
• Integers go between the stages flat.

// Where the surface at each pixel was last frame, in UV
const Clips = d.struct({ now: d.vec4f, before: d.vec4f });
const motion = passes.output(d.vec2f, {
  varyings: Clips,
  previous: true,
  vary: (now: { position: d.v4f }, before: { position: d.v4f }) => {
    'use gpu';
    return Clips({ now: now.position, before: before.position });
  },
  write: (_surface: unknown, clips) => {
    'use gpu';
    return uvOf(clips.before) - uvOf(clips.now);
  },
});

const id = passes.output(d.u32, {
  clear: 0xffffffff, // nothing here
  write: (surface: { id: number }) => {
    'use gpu';
    return surface.id;
  },
});

passes.color marks the target for each renderer’s colour. passes.depth marks the depth target. A description allows at most one of each and leaves unlisted targets untouched.

What each target gets

scene.without('id') omits the id output and its varyings for drawings that can’t supply it. scene.instead({ motion: skyMotion }) writes an output of the drawing’s own into that target. Both draw into the pass scene.begin starts:

const embers = scene.without('id').add(sparks.drawing);
const sky = scene.without('id').instead({ motion: skyMotion }).add(skyDrawing);

Target	What the drawing writes there
passes.color	Its own color, through its blend and writeMask.
passes.depth	Its depth, or depthOf’s, as its depth state says: tested and written by default.
An output	The output’s write, from its surface and the output’s varyings. Outputs don’t blend: a blended drawing replaces the value wherever it draws, its transparent corners too.
An output instead replaces	The replacement’s write.
An output without leaves out, opaque	The output’s clear, as if nothing drew there.
An output without leaves out, with a blend	Nothing: what is under it stays.

The kit’s drawings:

Drawing	Vertex	Surface	Blend	Depth
An instances renderer	instances.Corner	instances.Lit	none, or as its blend says	written; tested only when translucent
particles.drawing	particles.Corner	particles.Seen	add, or as its blend says	tested only
A lines set’s drawing	lines.Corner	lines.Seen	over, or as its blend says	tested only; written with opaque
trails.drawing	lines.Corner	lines.Seen	add, or as its blend says	tested only
A text set’s drawing	text.Corner	text.Seen	over, or as its blend says	tested only

Draw what tests the depth without writing it after the opaque drawings. Impostors draw through an instances renderer.

Translucent drawings

jelliesTranslucent jellies in any draw order; tap one and it flashes.

PauseOpen the full example

Every bell, oral arm and tentacle is a translucent drawing. Turn off oit to draw them into a description without the two targets: they blend over in draw order, and the moon jelly behind the sea nettle covers it.

Blending translucent drawings over each other looks right only when they draw from far to near. That needs sorting every frame, and still fails where two surfaces cross. A drawing with translucent: true needs no order. Give the description two more targets, one marked passes.accumulation and one marked passes.revealage. Each translucent pixel adds its colour into the first, weighted so that nearer layers count most, and multiplies the share of what lies behind it that still shows into the second. scene.composite(frame) then lays the average over the colour target in a pass of its own:

import { passes, targets } from '@typegpu/kit';

const screen = targets.create(root, surface, {
  hdr: { format: 'rgba16float', sampled: true },
  accum: { format: 'rgba16float', sampled: true },
  reveal: { format: 'r16float', sampled: true },
  depth: { format: 'depth24plus' },
});
const scene = passes
  .create(root, screen, {
    hdr: passes.color,
    accum: passes.accumulation,
    reveal: passes.revealage,
    depth: passes.depth,
  })
  .pipe(view.inject());

// The opaque ground first, then the translucent bells
const drawn = [scene.add(ground), scene.add({ ...bells, translucent: true })];

frames.create(root, (frame) => {
  scene.record(frame, drawn);
  scene.composite(frame);
});

• A translucent drawing’s color output is premultiplied, d.vec4f(rgb * alpha, alpha). Colour with an alpha of 0 adds light, as a glow does.
• It tests the depth that opaque drawings wrote before it and writes none. Draw it after them, in any order among the translucent ones.
• Opaque drawings leave the two targets alone. Outputs such as motion take a translucent drawing’s value as they take a blended one’s.
• In a description without the two targets, the same drawing blends over the colour target in draw order. The jellies keep a second description to turn the targets off.
• composite reads both targets as textures, so each needs sampled: true. It draws over the colour target, or over its resolve destination when it resolves, and throws in a description without the targets.
• An instances renderer with blend: 'translucent' or 'clear' draws translucent.

Fills

pipe(fill) adds a fill to every pipeline built from the returned description. It applies after the drawing’s fill and takes precedence. passes.create(…).pipe(view.inject()) uses view as its camera. A shadow map uses a description of depth alone, viewed from the sun.

beneath(fill) adds a fill that applies before the drawing’s fill, as a default the drawing can override. scene.beneath(light.inject()) lights every drawing that doesn’t fill the lighting’s hooks itself. Fills given to beneath and to pipe each apply in call order.

inject() returns the description’s fills, those given to beneath and then the piped ones. A compound drawing that builds pipelines from its own configuration, such as an instances renderer, starts from inject() and applies its own fills over it, so beneath lights it too.

Pixels and points

A line two points wide or a label pinned beside a star needs the size of what the pass draws into, which differs between the canvas, a low-resolution target and a shadow map. Every description fills passes.pixels in each pipeline and kernel it builds. It holds the drawn region’s size in pixels and its pixelRatio, the pixels a point takes:

import { cameras, passes } from '@typegpu/kit';

/** Where a world point lands on the target, moved `offset` points right and up. */
const besideInPoints = (world: d.v3f, offset: d.v2f) => {
  'use gpu';
  const view = passes.pixels.$;
  const clip = cameras.current.$.viewProjection * d.vec4f(world, 1);
  return d.vec4f(clip.xy + ((offset * 2 * view.pixelRatio) / view.size) * clip.w, clip.zw);
};

• Over a surface, size is the surface’s and pixelRatio its pixelRatio. Over targets, size is the drawn region and pixelRatio the source’s, scaled by the region, so a point keeps its size at a lower resolution or through targets.scaled. A source without a ratio, such as a shadow map’s fixed size, has a pixelRatio of 1.
• begin and record write it when the region has changed. A pipeline from pipeline() drawn into a pass you begin yourself, or a kernel built from inject() in a frame where the description doesn’t begin, reads the region of the last begin.
• Each description holds its own uniform, even beside another over the same targets. A pipeline that reads it binds 1 uniform.
• Descriptions also fill two slots: passes.sampleCount with the samples per pixel, and passes.depthOnly with whether they draw into depth alone. A drawing reads them to cut its own edges where there is one sample, or to leave out what only shows in colour, such as an antialiased edge in a shadow map.

Buffers and textures of your own

A drawing’s shaders read buffers, textures and samplers through accessors, which its inject() fills. The description builds each pipeline from that fill, so a draw binds no group of yours:

const tints = tgpu.accessor(d.arrayOf(d.vec4f, 4));
const picture = tgpu.accessor(d.texture2d(d.f32));
const smooth = tgpu.accessor(d.sampler());

const tintBuffer = root.createReadonly(d.arrayOf(d.vec4f, 4));
const image = root.createTexture({ size: [512, 512], format: 'rgba8unorm' }).$usage('sampled');
const view = image.createView(d.texture2d(d.f32));
const sampler = root.createSampler({ magFilter: 'linear', minFilter: 'linear' });

const backdrop = scene.add({
  ...passes.fullScreen,
  surfaceOf: (corner: d.Infer<typeof passes.fullScreen.Vertex>) => {
    'use gpu';
    const band = std.min(d.u32(corner.uv.y * 4), 3);
    return Seen({ color: std.textureSample(picture.$, smooth.$, corner.uv) * tints.$[band]! });
  },
  color: passes.shaded,
  inject: () => (cfg) =>
    cfg
      .with(tints, tintBuffer)
      .with(picture, () => view.$)
      .with(smooth, () => sampler.$),
  draw: (pass) => pass.draw(3),
});

• Shaders can read tintBuffer.$ and view.$ without accessors. The resources become fixed bindings in each pipeline’s automatic group.
• A kernel of your own reads them the same way, created from root.pipe(fill), with scene.inject() piped in too when it reads the camera.
• WebGPU forbids read-write storage in a vertex stage. Fill an accessor that a kernel writes and a vertex stage reads with byStage(buffer), read-write in compute and read-only elsewhere.
• cfg.with takes a slot or accessor and its value. Passing a bind group as cfg.with(group) fails with TS2554.

A resource you swap without new pipelines, such as a texture that follows the canvas, goes in a bindings.layout part. Share the part with bindings.share before passes.create, and give the description the shared layout as shared. Every pass it begins then sets the shared group:

import { bindings } from '@typegpu/kit';

const backdropBindings = bindings.layout({
  picture: { texture: d.texture2d(d.f32) },
  smooth: { sampler: 'filtering' },
});
const part = backdropBindings.bind({ picture: image, smooth: sampler });
const shared = bindings.share(root, { backdrop: part }); // before the pipelines that read it
const scene = passes.create(root, screen, { hdr: passes.color }, { shared });

const backdrop = scene.add({
  ...passes.fullScreen,
  surfaceOf: (corner: d.Infer<typeof passes.fullScreen.Vertex>) => {
    'use gpu';
    const color = std.textureSample(
      backdropBindings.$.picture,
      backdropBindings.$.smooth,
      corner.uv,
    );
    return Seen({ color });
  },
  color: passes.shaded,
  draw: (pass) => pass.draw(3),
});

frames.create(root, (frame) => scene.record(frame, backdrop));

part.replace({ picture: bigger }); // between frames, keeping the pipeline

• shared also fills every shared part in the pipelines the description builds, so a drawing needs no inject for them.
• The share must exist before passes.create, and before any other pipeline that reads its parts. A pipeline built before then holds the part as fixed bindings, and bindings.share throws.
• A pass you open yourself, outside begin, sets the group with pass.setBindGroup(shared.layout, shared.group()).

Every frame

begin(frame) starts a pass into every target named by the description. record(frame, drawn) starts a pass with the same options, draws one handle or a list in order, and ends the pass. Create the list at setup. Use begin to choose drawings per frame or set a bind group of your own before drawing.

const timing = profiler.create(root);
const sceneTime = timing.timer('scene');
const opaque = [ground, herd];

frames.create(root, (frame) => {
  scene.record(frame, opaque, { timestampWrites: sceneTime.writes() });
  glows.record(frame, sparks, { clear: false }); // over what the scene drew
  timing.capture(frame);
});

• Output targets clear to their output’s clear. The colour target uses the description’s clear, which the pass reads at each begin. Depth uses depth.clear, which defaults to 1. Stencil uses stencilClear.
• clear: false keeps what every target holds, for a later pass such as glows after one that reads the depth. clear: ['hdr'] clears the targets it names and keeps the rest, such as the depth an earlier pass drew.
• A transient target can’t retain its contents between passes. begin throws if asked to keep it. Set transient: false in its spec to retain contents. Multisampled targets are transient by default.
• Each pass stores what it drew, storeOp: 'store', except into a transient target, 'discard', which keeps only what it resolves.
• timestampWrites times the pass with a profiler.
• A description of targets that resolves into no surface also begins from an encoder in place of the frame.
• A set below its full resolution gets the viewport of its region.
• The jitter option moves each vertex where the rasteriser sees it and nowhere else. Outputs read where the vertex is, so motion holds no jitter. Temporal antialiasing sets it.
• record and composite skip a disabled description; begin does not.
• initAsync() compiles every pipeline built into the description, and what each drawing added needs, including drawings added while it compiles.

Layers

A shadow map in cascades, one per distance, draws the same casters into several layers of one texture, each through its own view. Give targets.create a target with layers, and the description draws a pass into each. cameras.layered holds a view per layer:

import { mat4 } from 'wgpu-matrix';
import { cameras, passes, targets } from '@typegpu/kit';

const size = { width: 1024, height: 1024, pixelRatio: 1 };
const maps = targets.create(root, size, {
  depth: { format: 'depth16unorm', layers: 3, sampled: true },
});
const views = cameras.layered(root, 3);
const casters = passes
  .create(root, maps, { depth: passes.depth }, { bias: { constant: 2, slope: 2 } })
  .pipe(views.inject());
const drawn = casters.add(herd);

frames.create(root, (frame) => {
  // A wider view for each layer
  for (let k = 0; k < 3; k++) {
    const reach = 8 * 4 ** k;
    const view = mat4.lookAt([20, 40, 20], [0, 0, 0], [0, 1, 0]);
    views.write(k, view, mat4.ortho(-reach, reach, -reach, reach, 0, 200));
  }
  casters.record(frame, drawn); // a pass into each layer
});

• The description builds each pipeline once, for all layers. Each pass sets a uniform holding its layer, which shaders read as passes.layer.$. cameras.layered reads it to give cameras.current.$ the layer’s view. Data of your own per layer can be indexed by it too.
• record draws a pass into each layer, in order, with the same options. record(frame, drawn, { layer }) draws into one. begin(frame, { layer }) begins one and throws without a layer when there are several.
• With timestampWrites, the first layer’s pass writes the start and the last layer’s pass writes the end.
• The description draws as many layers as its targets have, and casters.layers reports the count. Every target it draws into needs the same layers, or passes.create throws naming each target and its count. Translucency targets and resolves aren’t drawn into layers.
• A render bundle can’t draw into a description of 2 or more layers, and draw throws for one. Record the drawing into the passes that record or begin opens.
• Drawings of one pipeline, particles, trails and text draw the same way into each layer, through the layer’s view. An instances renderer with cull: true keeps a visible list per layer and culls every layer in one pair of dispatches. Impostors and poses draw through an instances renderer.
• A kernel built from a layered description’s inject() runs outside its passes, so it fills passes.layer itself, as the instances culling does from each invocation’s y.
• The layer takes 1 uniform and one of WebGPU’s 4 bind groups in each pipeline that reads passes.layer. With cameras.layered, a caster binds 2 uniforms: the views and the layer.

Limits

• A drawing’s surface reads its vertex’s fields and the pixel’s position, not WebGPU’s other fragment inputs, such as frontFacing.
• Each output’s varyings go between the stages as <target>_<field>, and a vertex field of that name throws. They count towards WebGPU’s 16 inter-stage variables, with the vertex’s own fields.
• An output with previous: true runs the renderer’s at twice per vertex, and binds last frame’s uniforms beside this frame’s.
• Translucent layers that overlap in depth average their colours by weight, so a layer close behind another shows through more than it would in order. The weight suits distances from the eye of about 0.1 to 500.
• A translucent drawing’s motion is that of the layer drawn last where it shows, so TAA can smear what lies behind it. Leave it out of motion with without('motion') to keep the motion beneath it.
• Particles, trails and text drawings set a blend and draw over in order. A drawing of your own made from one, without its blend and with translucent: true, draws in any order when its colour is premultiplied.