Instances

count

96

Change the count to add boxes and spheres without increasing the two draws. Positions update every frame, while live lists update only after the count changes.

Drawing each object separately spends CPU time on JavaScript calls, especially on phones. Store a transform and material per object in a set of instances: a table whose rows are meshes from a mesh pool. Its renderer lights and draws the live rows with one draw per mesh. Adding instances increases data without increasing draws.

import { instances, lighting, materials } from '@typegpu/kit';

const root = await tgpu.init();
const light = lighting.create(root, { settings: { sunDirection: [0.4, 1, 0.3] } });
const scene = passes
  .create(root, screen, { hdr: passes.color, depth: passes.depth })
  .pipe(view.inject())
  .beneath(light.inject());
const things = instances.create(root, pool, { capacity: 256 });
const drawn = scene.add(things.renderer());

things.add(box, { position: [0, 0.5, 0], ...materials.glossy(d.vec3f(0.62, 0.24, 0.16), 0.4) });
const moon = things.add(ball, { scale: 0.5, ...materials.glow(d.vec3f(1, 0.85, 0.6), 2) });

const orbit = things.fields.position;

const loop = frames.create(root, (frame) => {
  orbit.set(moon, 2 * Math.cos(frame.time), 1.5, 2 * Math.sin(frame.time));
  things.flush();

  scene.record(frame, drawn);
});
frames.animate(loop);

things.renderer() returns a drawing, lit by the lighting its pass description gives through beneath. scene.add builds pipelines for its pass description and returns the draw commands. Each mesh uses a direct draw. Meshes with matching side, mask and texture settings share a pipeline. This needs no optional device feature. A finished look for model scenes draws one set of glTF models with shadows, ambient occlusion, TAA and bloom.

Rows

things.add(mesh, values) returns an id. Every value is optional:

Field	Default
position	the origin	world space
rotation	none	a unit quaternion, [x, y, z, w]
scale	1	one factor, or one per axis
color	the mesh’s	linear
roughness, metallic	the mesh’s
emission	the mesh’s	linear
opacity	the mesh’s alpha	under a blend or clear renderer

import { quat } from 'wgpu-matrix';

const crate = things.add(box, { position: [3, 0.5, 0], color: [0.4, 0.3, 0.2] });

things.write(crate, { rotation: quat.fromAxisAngle([0, 1, 0], Math.PI / 4) });
things.write(crate, { emission: [2, 0.4, 0] });
things.remove(crate);

• A row starts with its mesh’s material. Shapes default to white chalk. Models use the file’s factors, multiplied by textures. Supplied values and the set’s defaults replace factors. To tint relative to the file, start with mesh.material.
• Spread a materials preset into the values, for example { position, ...materials.glossy(color, 0.3), opacity: 0.2 }.
• write changes only supplied fields. undefined leaves a field unchanged. write and remove take effect at the next flush. Removal invalidates the id, and has(id) checks whether it is live.
• In shaders, instances.rotate(q, v) rotates v by a unit quaternion. instances.facing(direction) turns +z toward direction with +y up. facing also runs on the CPU.

A table of meshes

The set is a table of its kind, and everything a table offers works on it. Field handles write without allocating, live() spreads into a picker, neighbour grid or live lists, and idAt names the instance at a slot the GPU found:

const crates = instances.create(root, pool, { capacity: 1024, defaults: { roughness: 0.8 } });
const crate = crates.add(box);

const spin = crates.fields.rotation; // keep the handle outside the loop
spin.set(crate, 0, Math.SQRT1_2, 0, Math.SQRT1_2);

const hits = picker.create(root, view, {
  ...crates.live(), // the capacity and the live test
  size,
  position: instances.Instance.position.pipe(crates.inject()),
});

// Once a pick is read back
const slot = hits.result.take();
if (typeof slot === 'number') crates.write(crates.idAt(slot), { emission: [1, 0.6, 0] });

• A set without a kind stores instances.Instance rows, whose getters its shaders read.
• buffers, slotOf(id) and clear() also work as on a table. count counts instances, while capacity and span count rows.
• things.add(model) adds one row per mesh under one id. write, field handles and remove act on every row of the model. idAt gives the model’s id for any of its slots, and count counts it once. A field handle’s get reads the model’s first mesh.
• Use things.add({ meshes }) to group any pool meshes, including a character and held items.
• Pass a function of each mesh to give a model’s meshes values of their own, such as a coat colour per part: things.add(horse, (mesh, i) => ({ color: coats[i] })).
• defaults sets values for fields add omits, including a kind’s own fields.

Every frame

1. Call things.flush() to upload changed rows. When instances are added or removed, it also uploads per-mesh live lists. A set with history is typed HistoryInstances, whose flush takes the frame’s encoder.
2. Run any kernels that move the set.
3. Call renderer.cull(pass) in a compute pass for a culling renderer.
4. For a shadow, call light.shadow.record(frame, [cast]). Create cast = light.shadow.add(renderer) while loading.
5. Call drawn.draw(pass) in the scene pass or use scene.record(frame, drawn). Direct rendering uses one drawIndexed per mesh with instances. Culling uses one drawIndexedIndirect per mesh the set has used. Meshes sharing a pipeline and textures draw consecutively with the pipeline and groups set once.

Await scene.initAsync() and light.shadow.initAsync() while loading to compile renderer pipelines. Otherwise each pipeline compiles on its first draw. The GPU debug panel names pipelines by kind, with qualifiers such as cast, cover for a prepass, two-sided or masked.

Motion

Outputs such as antialiasing over time’s motion run the renderer’s vertex code a second time with last frame’s rows. Create the set with history: true to keep them, as a table does. Each instance then moves in the motion output, whether write or a kernel moved it:

const school = instances.create(root, pool, { kind: Fish, capacity: 1024, history: true });

frames.create(root, (frame) => {
  school.flush(frame.encoder); // keeps last frame's rows, then uploads
  // ... kernels that move the school, then the passes
});

Without history, the motion output sees only the camera move.

Renderers

things.renderer(options) draws the set. Add it to multiple pass descriptions to build pipelines for each. Multiple renderers can draw the same set. drawn.destroy() removes a drawing from its description and frees its resources.

Option	Default
light	none	A lighting in place of the one the description gives through beneath; a renderer whose shade reads none needs neither
blend	'opaque'	'translucent' covers what is drawn by each instance’s opacity and writes no depth; 'clear' is glass
transmit	none	Under 'clear', the share of each colour behind that shows through: a tint
textured	true	false ignores mesh textures and masks, drawing textured meshes with their factors alone
specularAntialiasing	true	false keeps sharp highlights on flat-shaded faces
cull	false	true draws into each description only what its camera may see
from	0	Draws only the instances at least this far from eye; a number or a 'use gpu' function of the row’s slot
to	every distance	Draws only the instances nearer than this to eye, as from
fade	0	Metres around from and to across which it hands its samples over
eye	none	The camera from and to measure from; a renderer with either needs it
shade	shading.shade	Computes outgoing light from the material. Supply unlit, toon or debug shading. A blend: 'clear' renderer always uses shadeClear
prepass	false	true draws an opaque renderer’s depth first, with coverage and masks alone, then shades where the depth is equal

Culling

With cull: true, each pass draws only instances its camera may see. The scene uses view, and the shadow uses the sun. Record renderer.cull(pass) after things.flush() and movement kernels, before shadow and scene passes:

const renderer = things.renderer({ cull: true });
const drawn = scene.add(renderer);
const cast = light.shadow.add(renderer); // each keeps a list of its own

// After things.flush() each frame
const culling = frame.encoder.beginComputePass();
renderer.cull(culling);
culling.end();

light.shadow.record(frame, [cast]);
scene.record(frame, drawn);

Culling reads draw counts written by GPU kernels and uses indirect draws. Request indirect-first-instance with tgpu.init({ device: { optionalFeatures: ['indirect-first-instance'] } }) to share pipelines across meshes without a group per mesh. Without the feature, each indirect draw binds a group that holds its mesh, and its pipeline reads the mesh from there. Where a pipeline has no bind group to spare, each mesh gets a pipeline with its mesh compiled in.

• Test each row with the sphere around its mesh box, scaled and transformed by the row. Model meshes and held items each use their own boxes.
• Visible rows retain set order across frames so blended objects do not flicker.
• cull dispatches two kernels over live rows per active pass description. It skips shadow work while shadows are off. Multiple renderers can share a compute pass.
• In a description with layers, each layer keeps a list of its own, seen through its view. The two kernels dispatch once, over every layer at once, so the work grows with rows times layers and the dispatch count stays the same. Each layer’s pass draws its own list.
• If deform moves vertices beyond the mesh box, supply a bounds sphere.
• Use cameras.sees(cameras.current.$, center, radius) for the same visibility test in your shaders, such as a live lists alive callback.

By distance

fade0 m2 m5 m

Pause

Change the fade around 7 m from the bright eye marker. One renderer draws nearby spheres and another draws distant boxes, splitting pixels across the fade and culling from the view above.

Use less detail for distant objects. A culling renderer with from and to draws instances at least from and less than to metres from eye. Split a set between renderers, or use separate sets for near meshes and distant impostors:

const near = { to: 40, fade: 8, eye: view };
const far = { from: 40, fade: 8, eye: view };

const renderers = [
  trees.renderer({ cull: true, ...near }),
  cards.renderer({ cull: true, ...far }).pipe(atlas.inject()),
];
const drawn = renderers.map((renderer) => scene.add(renderer));
const casts = renderers.map((renderer) => light.shadow.add(renderer));

• Measure distance from eye to each row’s position. The same distance applies in every pass description, including shadows.
• from and to can be shader callbacks taking the row slot, with their dependencies filled. Read uniforms to change thresholds without recompiling. Keep from below to for every row.
• Across fade metres around a threshold, the renderer draws a share of each instance that falls with its distance. Give the adjoining renderer the same fade to draw the rest. With multisampling an instance keeps whole samples, the same ones in every pixel, so the two blend evenly across it in steps of one sample. Without it they split pixels in a 4 × 4 pattern, which shows as a screen door where the two look different. Shadows switch without fading.
• Fading discards pixels or samples, which prevents early rejection of hidden pixels and increases shading work.

Transparency

With blend: 'translucent', instances draw translucent from premultiplied colour and their opacity. In a description with translucency targets they need no order; elsewhere they blend over in draw order. They write no depth and cast no shadows. The renderer accepts only pass descriptions with colour. Put blended objects in a separate set and draw them after opaque objects:

const solid = instances.create(root, pool, { capacity: 512 });
const ghosts = instances.create(root, pool, { capacity: 4 });
const blocks = solid.renderer();

// Drawn in this order, the ghosts over the blocks
const drawn = [scene.add(blocks), scene.add(ghosts.renderer({ blend: 'translucent' }))];
const casters = [light.shadow.add(blocks)];

Glass

blend: 'clear' draws as 'translucent' does, with shading.shadeClear. Highlights and sky reflections stay bright at any opacity. Opacity scales diffuse light and emission. On metals, it fades only fog.

Use transmit to tint the background through glass. { blend: 'clear', transmit: [0.88, 0.92, 0.94] } transmits those fractions of each channel at any opacity. Opacity controls the milky appearance. The tint belongs to the renderer and is set as the pass blend constant at each draw, so a transmit renderer blends over in draw order.

Other outputs

The renderer supplies an instances.Corner at each vertex and an instances.Lit at each pixel. Outputs use these values, including motion for antialiasing over time. See Passes for target outputs.

Kinds

A kind adds row fields and replaces shader functions with your own 'use gpu' functions. The fish tank’s fish keep velocity, beat their tails and have pale bellies:

const Fish = instances.define('Fish', {
  host: { belly: d.vec3f, phase: d.f32 },
  device: { velocity: d.vec3f },
  transform: 'device',

  // uv.x runs from the nose to the tail
  deform: (vertex, fish) => {
    'use gpu';
    const t = vertex.uv.x;
    const beat = std.sin(time.$ * 10 + fish.phase - t * 5) * 0.14 * t * t;
    return vertex.position + d.vec3f(beat, 0, 0);
  },

  material: (point, fish) => {
    'use gpu';
    const up = std.cos(point.uv.y * TAU);
    return materials.glossy(std.mix(fish.belly, fish.color, std.smoothstep(-0.4, 0.5, up)), 0.35);
  },
});

const school = instances.create(root, pool, { kind: Fish, capacity: 4096 });
school.add(body, {
  position: [0, 2, 0],
  color: [0.1, 0.45, 0.95],
  belly: [0.95, 0.25, 0.22],
  phase: 1.3,
  velocity: [1, 0, 0],
});

• Call instances.define at module scope without a root. Pass the result to create as kind.
• The name brands set ids, such as instances.Id<'Fish'>, and names the WGSL.
• Supply custom fields alongside built-in fields in add and write. Reusing a built-in name such as color or a reserved table name such as host, device, row, alive, span or slotOf is a type error. define also throws.

All functions are optional. instance gives the whole row. Functions can read uniforms and buffers, such as time.$ above:

Function	Takes and returns	What it replaces
place	(instance) => instances.Placement	Where the instance is, from data of your own, in every pass, in culling and for from and to. The row’s own transform goes unread.
visible	(instance) => bool	Whether it draws, in every renderer and pass. A culling renderer leaves it out of its lists; one that doesn’t cull collapses its triangles.
pose	(instance) => u32, a pose’s id	The mesh as bound: vertices and normals follow the pose’s joints, in every pass, before deform. Poses come from the poses piped into the renderer.
deform	(vertex: instances.Vertex, instance) => vec3f	Where the vertex is, in object space, in every pass. The normal stays the mesh’s, or the pose’s.
bounds	(instance, base: instances.Sphere) => instances.Sphere	The sphere a culling renderer tests, in world space; base is the one around the mesh’s box.
carry	(vertexIndex: u32, instance) => vec4f	Sends interpolated per-vertex data to material and surface as carried. See Carried from each vertex.
material	(point: shading.Point, instance, base: shading.Material, carried) => shading.Material	What the point is made of; base is the row’s material times the mesh’s textures. Call materials presets here.
surface	(point: shading.Point, instance, base: shading.Material, carried) => instances.Shaded	Replaces the mesh surface with a shading point and material, as impostors do.
coverage	(point: shading.Point, instance, base: shading.Material, carried) => f32	How much of the pixel the instance covers, from 0 to 1, in every pass, shadows included: holes such as lace, or the leaves on a card.

• With deform, the shadow pass reads 20 bytes per vertex rather than 12, or 28 rather than 20 with a pose. Set deformShadow: false for deformations too small to see in shadows, such as tail motion.
• A culling renderer of a kind with a deform needs bounds.
• Supply either material or surface. A custom surface shades at mesh depth and writes its supplied point depth to shadows.
• coverage runs before material or surface. With multisampling, it selects the share of samples covered; without, pixels below half coverage are omitted. Blended renderers scale opacity by it. A kind without coverage keeps early depth testing, so each mesh draws once and hidden pixels go unshaded.
• A heavy material or surface that overlaps itself, such as a forest of impostor cards, can take prepass: true on its renderer: the depth goes first, running only coverage and the mesh masks, then the colour shades each visible pixel once. It costs a second pass over the vertices and needs a description with depth.
• Each kind compiles a colour pipeline per pass description and a depth pipeline for shadows. Put per-instance differences in row fields to avoid extra pipelines.

Moved by your kernels

With transform: 'device', the transform joins the kind’s device fields. A kernel created from root.pipe(school.inject()) reads through the kind’s getters and writes Fish.device.$[i]. Dispatch it over school.span after school.flush(), skipping free slots:

const swim = tgpu.computeFn({
  workgroupSize: [64],
  in: { gid: d.builtin.globalInvocationId },
})(({ gid }) => {
  'use gpu';
  const i = gid.x;
  if (!Fish.alive(i)) return;

  const fish = Fish.device.$[i]!;
  fish.position = Fish.position(i) + Fish.velocity(i) * step;
  fish.rotation = instances.facing(Fish.velocity(i));
});

const swimming = root.pipe(school.inject()).createComputePipeline({ compute: swim });
pass.setPipeline(swimming);
pass.dispatchWorkgroups(Math.ceil(school.span / 64));

add uploads the whole initial row. Kernels then own device fields. Writing those fields from the CPU overwrites kernel values at the next flush.

For motion that follows each fish, create the set with history.

Placed from your own data

If a simulation has its own position buffer, read it in place instead of copying positions to rows every frame. Fill the dependency through the renderer’s pipe:

const bodies = tgpu.accessor(d.arrayOf(d.vec4f, 256)); // xyz is world position; w is heading

const Horse = instances.define('Horse', {
  host: { body: d.u32, fallen: d.u32 },
  place: (horse) => {
    'use gpu';
    const body = bodies.$[horse.body]!;
    return instances.Placement({
      rotation: d.vec4f(0, std.sin(body.w / 2), 0, std.cos(body.w / 2)),
      position: body.xyz,
      scale: d.vec3f(1),
    });
  },
  visible: (horse) => {
    'use gpu';
    return horse.fallen === 0;
  },
});

const horses = instances.create(root, pool, { kind: Horse, capacity: 256 });
const renderer = horses.renderer().pipe((cfg) => cfg.with(bodies, herd.as('readonly')));

add and write still accept row position, rotation and scale, but place ignores them. place runs for each vertex in every pass; when it does heavy work, a kernel that writes rows once a frame costs less.

Fills

Fill dependencies read by kind functions through the renderer’s pipe. For example, the fish tank reads a noise cache. See shader dependencies:

const noise = perlin3d.staticCache({ root, size: d.vec3u(16, 16, 32) });

const renderer = sand.renderer().pipe(noise.inject());
// No surface lies below the sand, so omit its shadow caster
const drawn = scene.add(renderer);

A custom fill takes a configuration, for example .pipe((cfg) => cfg.with(clock, time)).

Textures in a kind

base includes mesh textures. Modify only the fields you need. The hex isle adds light where its house atlas has window panes:

const House = instances.define('House', {
  host: { glow: d.f32 },

  material: (point, house, base) => {
    'use gpu';
    // Window panes occupy column 6, row 1 of the 8 by 4 atlas
    const pane = std.all(std.eq(std.floor(point.uv * d.vec2f(8, 4)), d.vec2f(6, 1)));
    const lit = std.select(d.f32(0), house.glow * night.$, pane);

    const glowing = shading.Material(base);
    glowing.emission = base.emission + WARM * lit;
    return glowing;
  },
});

materials.textured(material, point) textures a material made another way, such as a preset, in a fragment shader.

Carried from each vertex

Use carry to read per-vertex data, such as a mesh-pool extra attribute. material and surface receive the interpolated value as their last argument. This example uses vertex colours:

const pool = meshPool.create(root, { capacity: 16, extra: { color: d.vec4f } });

const Painted = instances.define('Painted', {
  carry: (vertexIndex) => {
    'use gpu';
    return pool.extra.color(vertexIndex);
  },
  material: (_point, _instance, base, carried) => {
    'use gpu';
    const painted = shading.Material(base);
    painted.color = base.color * carried.rgb;
    return painted;
  },
});

• vertexIndex uses pool indices, as meshPool.vertexAt does. Without carry, carried is zero and vertices pass four fewer floats.
• pool.extra belongs to one pool. Define kinds that read it after creating that pool, and use them only with its meshes.

Members

Member
things.count	Live instances. A model counts once.
things.span, things.capacity	Rows: the slot range kernels must visit, and the most rows the set holds.
fields, live(), idAt, slotOf, buffers, clear()	As on a table, with a model’s rows under one id.
Fish.device	The device fields, a storage buffer per set that school.inject() fills, for your kernels to write. A write overwrites them from the CPU.
Fish.position(i), Fish.alive(i)	A getter per field, and whether slot i is live, in shaders created from inject().

Memory

What
a row	80 bytes plus custom kind fields, or 48 bytes in each part with transform: 'device'. The live list adds 4 bytes per row.
a set	4 bytes per mesh of pool capacity for its list. Drawing through a render bundle adds 20 bytes per mesh for draw arguments.
culling	Per pass description and per layer, 8 bytes per row of set capacity and 28 bytes per mesh of pool capacity.
history	Twice the row bytes again, for last frame’s rows and the frame’s uploads.

destroy() on a set frees its buffers once nothing draws with them. After it, has is false and remove does nothing.

Errors

Message	Thrown by
The kind 'Fish' must supply either material or surface, not both.	define
'color' is a built-in instance field. Choose another name., or 'span' is reserved by table.define.	define
The set is full (1024 rows; a model takes a row per mesh).	add
Row id … is stale because its row was removed.	write or remove after remove
The mesh belongs to another pool.	add
The table 'Fish' keeps history, so flush takes the frame's encoder: flush(frame.encoder).	flush without an encoder, on a set with history
Slot 3 holds no row.	idAt, for a free slot
The model has no meshes.	add
The kind 'Fish' uses pose and requires a mesh with joints.	add, for a mesh that isn’t skinned
The kind 'Fish' uses deform. Supply bounds before enabling culling.	renderer, with cull: true
A renderer with from or to requires cull: true.	renderer
A renderer with from or to requires eye.	renderer
Renderer distances require from >= 0, to > from and fade >= 0. …, a RangeError	renderer, for a negative from or fade, or a to not beyond from
A renderer with transmit requires blend: 'clear'.	renderer
Each transmit channel must be from 0 to 1. Received [1, 1.5, 1]., a RangeError	renderer
A renderer with blend: 'translucent' leaves depth alone; …, or 'clear'	light.shadow.add, or add on any description of depth alone
A renderer with prepass: true draws into passes with depth.	add on a description without depth
This renderer was created without `cull: true`.	cull
The instances were destroyed.	add, write, flush, inject, renderer, and building, culling or drawing a renderer, after destroy

Limits

• Two sets of one kind with the same renderer options compile a pipeline pair each.
• Renderers compile a pipeline for each combination of doubleSided, masked and textured present in the pool, including unused meshes. initAsync compiles combinations present at that time. Adding a mesh with another combination, such as an impostor card, causes compilation on its first draw.
• A renderer draws an alpha: 'blend' material as opaque; blending is the renderer’s blend option.
• Render bundles cannot set a blend constant. For a transmit renderer in a bundle, set it on the enclosing pass with pass.setBlendConstant([...transmit, 1]).
• A bundle draws the meshes that had instances when it was recorded. Record it again after a mesh’s first instance, and once a model’s ready resolves.
• Back-face lighting uses the interpolated normal relative to the eye. A front face can therefore receive back lighting near an edge where that normal turns away.
• A kind with a surface ignores masks: it says what it covers itself.
• deform can’t bend the normal or move the uv.
• facing applies no y rotation for straight-up or straight-down directions. Rotate models that do not face +z when reading them with rotation.