How the kit works

TypeGPU Kit is a set of modules for TypeGPU. Your program keeps the GPU device, the loop and every command. Each module takes over one piece you would otherwise write by hand, such as textures that follow the canvas size, a glow or a pool of particles.

This page writes one frame in plain TypeGPU, then moves it onto the kit one piece at a time. Each step introduces one of the six rules every module follows, yours included.

A frame in plain TypeGPU

The frame draws rings that ripple out from the middle of the canvas. A small program on the GPU, a kernel, moves the ripple forward each frame, and a fragment function colours every pixel from it.

PauseGlow

The frame this page builds. Turn on Glow to add the bloom from A module borrows.

TypeGPU starts from a root, which holds the GPU device and creates everything else. The program asks it for two pieces of GPU memory and two pipelines, each a GPU function compiled together with the fixed state it needs:

import { common, d, std, tgpu } from 'typegpu';

const root = await tgpu.init();
const context = root.configureContext({ canvas: document.querySelector('canvas')! });

const tint = root.createUniform(d.vec4f, d.vec4f(0.2, 0.6, 1, 1)); // written by the CPU
const phase = root.createMutable(d.f32); // written by the kernel

const advance = tgpu.computeFn({ workgroupSize: [1] })(() => {
  'use gpu';
  phase.$ += 0.05;
});
const rings = tgpu.fragmentFn({ in: { uv: d.vec2f }, out: d.vec4f })(({ uv }) => {
  'use gpu';
  const wave = std.sin(std.length(uv - d.vec2f(0.5)) * 40 - phase.$) * 0.5 + 0.5;
  return tint.$ * wave;
});

const advancing = root.createComputePipeline({ compute: advance });
const drawing = root.createRenderPipeline({
  vertex: common.fullScreenTriangle,
  fragment: rings, // draws in the canvas's format
});

• 'use gpu' marks a function TypeGPU compiles for the GPU. Inside one, +, -, * and / work on vectors such as d.vec2f.
• A uniform holds a few values that are the same for every pixel. The CPU writes it. A mutable buffer is memory that kernels write. A shader reads either through .$.
• configureContext connects the canvas to the root’s device. Its format and a pipeline’s both default to the browser’s preferred format.
• common.fullScreenTriangle is TypeGPU’s vertex function for one triangle that covers the canvas, and hands each pixel its uv, from 0 to 1 across the canvas.
• Compiling a pipeline takes time, so a program creates its pipelines once, before the first frame.

The GPU doesn’t run commands as they are called. An encoder records them. Work goes into passes: a compute pass runs kernels, and a render pass draws into textures. A submit sends what the encoder recorded to the GPU, which runs it in order:

function frame() {
  const encoder = root.createCommandEncoder();

  const compute = encoder.beginComputePass();
  compute.setPipeline(advancing);
  compute.dispatchWorkgroups(1); // runs the kernel once
  compute.end();

  const pass = encoder.beginRenderPass({
    colorAttachments: { view: context.getCurrentTexture().createView() },
  });
  pass.setPipeline(drawing);
  pass.draw(3); // the triangle's three corners
  pass.end();

  encoder.submit(); // one command buffer for the whole frame
  requestAnimationFrame(frame);
}
requestAnimationFrame(frame);

A larger program also needs a loop with time, textures that follow the canvas size, effects such as a glow, and thousands of objects. The kit’s modules provide those.

You own the frame

The kit’s frames runs the loop part of frame(). It creates the encoder, calls your function with it, and submits once your function returns. web.surface configures the canvas and follows its size. The passes stay yours:

import { frames } from '@typegpu/kit';
import * as web from '@typegpu/kit/web';

const surface = web.surface(root, canvas);

const loop = frames.create(root, (frame) => {
  const compute = frame.encoder.beginComputePass();
  compute.setPipeline(advancing);
  compute.dispatchWorkgroups(1);
  compute.end();

  const pass = frame.encoder.beginRenderPass({ colorAttachments: { view: surface.view(frame) } });
  pass.setPipeline(drawing);
  pass.draw(3);
  pass.end();
}); // submits frame.encoder after this returns

frames.animate(loop); // runs the loop at every animation frame

frame holds the encoder, the time in seconds and dt, the seconds since the last frame.

The first rule: your program owns the device, the loop, the encoder, the passes and the submit. No module submits during a frame. Each records into a pass or an encoder you hand it, so the GPU runs the frame in the order of your calls.

A module borrows

A glow makes the bright rings bleed light. It needs the frame drawn into a texture with more range than the canvas, a high dynamic range (HDR) texture, which a blur then reads. Three modules cover it:

• targets holds a set of textures that follow the canvas size. fit() replaces them when the size changes.
• bloom blurs the bright parts of a texture into a glow texture.
• finish, the final pass, brings HDR colour into the canvas’s range and adds the glow.

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

const screen = targets.create(root, surface, { hdr: { format: 'rgba16float', sampled: true } });
const hdr = () => screen.textures.hdr;
const glow = bloom.create(root, { source: hdr });
const final = finish.create(root, { format: surface.format, source: hdr, glow });

const drawing = root.createRenderPipeline({
  vertex: common.fullScreenTriangle,
  fragment: rings,
  targets: { format: 'rgba16float' }, // into the HDR texture now
});

frames.create(root, (frame) => {
  screen.fit();
  const pass = frame.encoder.beginRenderPass({ colorAttachments: { view: screen.views.hdr } });
  pass.setPipeline(drawing);
  pass.draw(3);
  pass.end();

  glow.record(frame); // opens its own passes
  final.record(frame, surface.view(frame));
});

Each module came from a factory, create(root, options). A factory allocates what the module needs and returns a handle:

• Resources, as TypeGPU objects you read and write. glow.settings is a uniform, so glow.settings.patch({ threshold: 0.8 }) changes the threshold. glow.output is the glow texture, which your own passes can sample.
• Recording methods, such as glow.record(frame), which record into what you pass them.
• 'use gpu' functions your shaders can call, on modules that have them, such as particles’ emit.
• destroy(), which frees what the module made and nothing it borrowed. glow.destroy() frees the glow’s textures, and the screen’s stay.

The second rule: a module borrows. It takes the root and the resources you hand it, keeps no global state, and destroys only what it made, so two glows share nothing. A recording method takes the smallest piece of the frame it needs: a compute or render pass, or the frame or its encoder when it opens passes of its own. A method that eases over time reads dt from the frame.

The figure shows a larger frame: a flow field, particles, a readback and a glow, each recording into the one encoder. Turn a module off to see what it recorded.

Flow fieldParticlesReadbackBloom and finish

Turn a module off to remove its calls or passes. Point at a resource to follow it from the writing pass to its readers.

Next to plain WebGPU, TypeGPU and a renderer such as three.js, the kit keeps TypeGPU’s shaders and schemas and leaves you the passes and the submit:

	WebGPU	TypeGPU	TypeGPU Kit	Three.js
Shaders	WGSL strings	TypeScript marked 'use gpu'	TypeGPU shader functions	built-in materials, TSL for your own
Memory layout	byte offsets, by hand	schemas such as d.struct	TypeGPU schemas and tables	attributes and uniforms it uploads
Objects			rows in buffers	a scene graph of Object3D
Passes and order	yours	yours	yours; modules record into them	the renderer’s
The submit	yours	yours, or one per call without an encoder	yours, once a frame	the renderer’s
Reusable pieces		functions, slots and accessors	modules that borrow your root	classes and add-ons

Nothing is hidden

Creating GPU objects during a frame costs time and memory the frame can’t spare, and a pipeline compiled during a frame stalls it. So the modules allocate when you create them, compile in initAsync, and only record during frames:

await Promise.all([
  advancing.initAsync(),
  drawing.initAsync(),
  glow.initAsync(),
  final.initAsync(),
]);

After that a steady frame creates no GPU objects at all. The figure runs a scene on a recording root, which counts what the device creates without a GPU. Run a frame twice and the counts stay put.

initAsync()framesteps

2

Reset

WGSL in log.shaders

Press frame again to see that a steady frame allocates nothing, with changed counters highlighted. Reset and run a frame before initAsync() to see compilation on first use. steps sets how many fixed steps a frame records.

The third rule: nothing is hidden. Each module’s page opens with a card generated from its source, which states its costs. A test runs every module and checks the card against what it does:

• allocates names anything a module creates after setup, such as the bind group a video feed makes for each camera frame it copies.
• owns lists what destroy() frees.
• binds counts the storage buffers and uniforms its shaders add. WebGPU guarantees 8 storage buffers per shader stage, so the counts tell you what fits in one pipeline.
• records says where its work goes and in which order.
• injects names the accessors it fills, which the next section explains.
• submits setup marks the few calls that submit on their own, such as meshPool.add without an encoder, so you make them while loading.

recordingRoot() runs your own scene the same way in a test.

Modules connect through TypeGPU

The ripple can become a module too. Then the colouring shader no longer captures phase itself: it reads the ripple through an accessor, a placeholder that a pipeline fills with a real resource when it is created. The module fills its accessor in inject():

export function createRipple(root: TgpuRoot) {
  const phase = root.createMutable(d.f32);
  const ripple = tgpu.accessor(d.f32); // a placeholder for some ripple's phase

  const advance = tgpu.computeFn({ workgroupSize: [1] })(() => {
    'use gpu';
    phase.$ += 0.05;
  });
  const advancing = root.createComputePipeline({ compute: advance });

  return {
    heightAt: (uv: d.v2f) => {
      'use gpu';
      return std.sin(std.length(uv - d.vec2f(0.5)) * 40 - ripple.$) * 0.5 + 0.5;
    },
    step: (pass: TgpuComputePass) => {
      pass.setPipeline(advancing);
      pass.dispatchWorkgroups(1);
    },
    inject: (): Inject => (cfg) => cfg.with(ripple, phase), // fills it with this ripple's
  };
}

A shader that calls heightAt reads the accessor, so the pipeline that runs it is created from root.pipe(ripple.inject()):

const rings = tgpu.fragmentFn({ in: { uv: d.vec2f }, out: d.vec4f })(({ uv }) => {
  'use gpu';
  return d.vec4f(0.2, 0.6, 1, 1) * ripple.heightAt(uv);
});
const drawing = root.pipe(ripple.inject()).createRenderPipeline({
  vertex: common.fullScreenTriangle,
  fragment: rings,
  targets: { format: 'rgba16float' },
});

The fourth rule: modules connect through TypeGPU’s own accessors, slots and pipe, never through a registry. The kit’s modules connect this way everywhere:

• Every renderer reads the camera through one accessor, cameras.current. A scene picks its camera with .pipe(view.inject()).
• Any kernel piped with sparks.inject() can start particles in sparks with sparks.emit.

Connecting modules covers the kinds of accessor, callbacks and resources that are replaced.

Objects are rows in buffers

A pipeline is compiled from its code, and a value captured into the code is part of it. Ten ripples with their centres captured into the shader would compile ten pipelines. With the centres in a buffer, one pipeline draws all ten, and an eleventh needs one more row and no new pipeline:

// One pipeline per ripple: each centre is part of a shader's code
const ringsAround = centres.map((centre) => (uv: d.v2f) => {
  'use gpu';
  return std.sin(std.length(uv - centre) * 40);
});

// One pipeline for every ripple: the centres are data
const centreOf = root.createReadonly(d.arrayOf(d.vec2f, 16), centres);
const ringsOf = (i: number, uv: d.v2f) => {
  'use gpu';
  return std.sin(std.length(uv - centreOf.$[i]!) * 40);
};

The fifth rule: per-object values live in buffers, and state that evolves stays on the GPU. The kit gives those buffers structure:

• A table is a buffer of rows with named fields. The CPU writes some fields, kernels write the others, and the table uploads only what changed.
• Instances draw every mesh’s objects from a table’s rows, and particles live in a pool of rows.

Data on the GPU covers rows, fixed steps, settings and reading results back.

Scenes are described once

A real scene draws more than colour. TAA needs to know where each pixel was last frame, picking needs an id at every pixel, and the depth decides what is in front. Every renderer would have to write all of these.

Instead, passes.create describes once what each target holds. A renderer hands over a drawing: what each corner carries to its pixels, what a pixel looks like, and how to draw. Here is the ripple as a drawing:

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

const Seen = d.struct({ color: d.vec4f }); // what a pixel looks like

const scene = passes.create(root, screen, { hdr: passes.color }).pipe(ripple.inject());
const water = scene.add({
  ...passes.fullScreen, // one triangle over the screen, carrying uv
  surfaceOf: (corner: d.Infer<typeof passes.fullScreen.Vertex>) => {
    'use gpu';
    return Seen({ color: d.vec4f(0.2, 0.6, 1, 1) * ripple.heightAt(corner.uv) });
  },
  color: passes.shaded, // writes the surface's colour as it is
  draw: (pass) => pass.draw(3),
});

frames.create(root, (frame) => scene.record(frame, [water]));

scene.add builds the pipeline that writes every target the description lists. Add a motion target to the description and the same drawing writes motion too.

The sixth rule: scenes are described once, and every renderer, the kit’s included, hands over a drawing. Scenes and passes covers outputs, shadows and other views.

What the kit leaves to you

The kit has no scene graph, ECS, physics, required asset format or engine loop. Parent-child transforms, game state and input stay in your code. A host, such as web.host or React Native’s useScene, runs a scene for you, and the scene still records its own frame.

Modules return TypeGPU resources, and most fit in one source file. You can edit a module or write your own and record both into the same encoder. The kit also runs on a device it shares with three.js or vgpu: Beside other renderers passes buffers, textures and images between them.

Modules covers the module contract in detail.