Render targets

kit.targets

module

Creates render targets that follow a size.

targets.create(root, source, specs, { resolution? }?) → Targets

targets.scaled(source, scale) → SizeSource

rootborrows

the root

sourcetakes

the size it follows, such as a surface

specstakes

a format and options per target, by name

resolution?takes

the fraction of each side drawn, which changes without allocating

Targetsreturns

a set of targets you fit every frame and destroy

sourcetakes

the size it scales, such as a surface

scaletakes

a factor, or a function that returns it

SizeSourcereturns

a size that targets and cameras can follow

types

SpecSizeSourceSurfaceFixedSizeDepthTextureTargets

Optionscreate · 1 field

resolution?

number | (() => number)= 1

Sets the fraction of each side to draw, capped at 1 and read at each fit().

records

fit() before the passes that use the targets; it returns true after a rebuild.

owns

a texture per target

Replaced as a set when the size changes.

allocates

on resize

The whole set, new textures and their views; a new resolution allocates nothing.

lifecycle

✓destroy()✓[Symbol.dispose]

used by

AfterimageBenthosBlockfallCenserClassroomCloisterDomino runEmber mirrorFalling sandFireworksFish tankForestHex isleJelliesJelly worldKineticLatticeNight marketOceanPlatformerQuiver treesRaymarchRobot armSkeletonsSlime mouldSolar systemSPH SculptSpiderStampedeStar mapSurvey model

pixel ratio11.523

resolution

1

Drag the canvas corner or change pixel ratio or resolution. A memo lookup each frame replaces the bind group after rebuilding, while a group created once retains the destroyed texture.

A renderer may need multisampled colour, depth, HDR colour and bloom textures that follow the canvas size. A WebGPU texture can’t be resized, so a new size means new textures, views and bind groups. targets.create makes a set of textures that share a size, and fit() replaces the whole set when the size changes.

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

const screen = targets.create(root, surface, {
  scene: { format: 'rgba16float', samples: 4 }, // transient
  depth: { format: 'depth24plus', samples: 4 }, // transient
  hdr: { format: 'rgba16float', sampled: true },
  bloom: { format: 'rgba16float', scale: 1 / 2, mips: 5, sampled: true },
  blur: { format: 'rgba16float', scale: 1 / 4, sampled: true },
});

// Runs again only when `hdr` is a new texture
const hdrGroup = memo((hdr: typeof screen.textures.hdr) => root.createBindGroup(layout, { hdr }));

frames.create(root, (frame) => {
  screen.fit(); // new textures if the canvas changed size

  const scene = frame.encoder.beginRenderPass({
    colorAttachments: {
      view: screen.views.scene,
      resolveTarget: screen.views.hdr,
      storeOp: 'discard',
    },
    depthStencilAttachment: { view: screen.views.depth, depthStoreOp: 'discard' },
  });
  // draw the scene
  scene.end();

  const final = frame.encoder.beginRenderPass({ colorAttachments: { view: surface.view(frame) } });
  final.setPipeline(tone);
  final.setBindGroup(hdrGroup(screen.textures.hdr));
  final.draw(3);
  final.end();
});

Specs

Each key names a target in textures, views, levels and layers.

Field	Default	Meaning
format		Texture format.
scale	1	Fraction of the set’s size; each side is rounded up and at least 1.
samples	1	MSAA sample count. A multisampled target can’t be mipped or stored.
mips	1	Mip levels, at most as many as the size has. levels.name[i] views level i.
sampled	false	Also bindable as a sampled texture.
storage	false	Also bindable as a storage texture, in a format TypeGPU binds as one, such as rgba16float.
transient	true when multisampled and not sampled	Cleared and discarded in each pass: memoryless where the browser has GPUTextureUsage.TRANSIENT_ATTACHMENT, a plain attachment elsewhere.
layers	none	Layers of a 2D array texture, one sample and one mip each. layers.name[k] views layer k. Passes draw a pass into each.

• A 16 × 9 target has five mip levels, so levels.bloom can be shorter than the mips asked for. Loop over levels.
• create throws before making any texture for a transient target that is sampled, stored or mipped, for a multisampled target with mips or storage, and for a target with layers that is multisampled or mipped or has more layers than the device’s maxTextureArrayLayers. It checks the mips you asked for, not the clamped count. The types already refuse storage on a format with no storage binding, such as depth24plus.
• A target only sometimes needed, like a depth-of-field buffer, goes in a set of its own, created when the feature turns on. There is no enabled flag.
• targets.Depth types the depth that TAA, depth of field and ambient occlusion read: single-sampled and sampled, in depth16unorm, depth24plus or depth32float.
• Take a pipeline’s format from screen.textures.name.props.format, and its sampleCount from the same props. Literals break only at the first draw after the spec changes.

Transient targets

A transient target is cleared, discarded and never read after its pass, such as MSAA colour or depth. Where memoryless attachments are available on tile-based GPUs, it uses tile memory during the pass without video-memory storage. Elsewhere, discarding the target still avoids storing its samples. Transience is a texture usage and needs no device feature request. screen.memoryless reports support.

• Multisampled targets are transient by default unless sampled or stored. Other targets require transient: true. screen.transient.scene reports whether scene is transient.
• A pass into a transient target clears it and uses storeOp: 'discard', so only what it resolves outlives the pass.
• begin throws when a pass would keep one, as a second pass that draws over the first does. Give that target transient: false:

const screen = targets.create(root, surface, {
  scene: { format: 'rgba16float', samples: 4, transient: false }, // kept for the glows' pass
  depth: { format: 'depth24plus', samples: 4, transient: false },
  hdr: { format: 'rgba16float', sampled: true },
});

Resizing

fit() compares the source’s size with the set’s. When it changed, it destroys every texture, creates new ones and returns true.

• Call it before recording passes that use the targets. A pass recorded with a destroyed texture fails at submit.
• Sizes round up to whole pixels, at least 1 and at most the device’s maxTextureDimension2D.
• create fits once, so the textures exist before the first frame.
• The source can be any SizeSource, such as a canvas surface, plain object or fixed-height getter. fit() reads it each time. A plain object of fixed size makes a texture of your own to draw into.
• destroy(), or [Symbol.dispose] with using, destroys the textures. fit(), textures, views and levels then throw The target set was destroyed.

Following new textures

kit.memo

cpu

Caches the last two results of fn, comparing arguments by identity.

memo(fn)

kind

cpu

used by

AfterimageCenserClassroomFireworksLatticeOceanPlatformer

A cached bind group still refers to the texture it was created with after that texture is destroyed. memo(fn) reruns fn when an argument’s identity changes. Call it each frame with the current texture to create a group only when the texture changes. It also works with textures replaced by other modules.

• Up to four arguments, so a call allocates nothing.
• It keeps its last two results, so arguments that alternate between two textures run fn only twice per rebuild.
• It destroys nothing; keep it for bind groups and the like.
• levels.name is a new array per rebuild, so it works as an argument, as bloom keys its per-level groups and passes on chain.levels.glow.

New objects every call

memo compares by identity. An array or object literal made in the call is new every time, so fn runs every frame and nothing warns you. Pass the textures themselves.

A temporal effect, such as a cloud history, writes one target of a pair while it reads the other, and swaps each frame. One memo holds both groups:

const screen = targets.create(root, surface, {
  a: { format: 'rgba16float', sampled: true },
  b: { format: 'rgba16float', sampled: true },
});

const historyOf = memo((history: typeof screen.textures.a) =>
  root.createBindGroup(History, { history }),
);

frames.create(root, (frame) => {
  screen.fit();

  // Even frames write a and read b, odd frames the other way
  const even = frame.index % 2 === 0;
  const pass = frame.encoder.beginRenderPass({
    colorAttachments: { view: even ? screen.views.a : screen.views.b },
  });
  pass.setPipeline(resolve);
  pass.setBindGroup(historyOf(even ? screen.textures.b : screen.textures.a));
  pass.draw(3);
  pass.end();
});

After a rebuild both sides are new and zeroed, so the effect starts over from an empty history.

Resolution scale

The resolution option sets the fraction of each side to draw, read on every fit(). Textures keep their full source size, so changing resolution during play allocates nothing. Passes use a viewport to draw within each target’s region. Bloom and finish read only that region:

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

const screen = targets.create(
  root,
  surface,
  {
    hdr: { format: 'rgba16float', sampled: true },
    depth: { format: 'depth24plus' },
  },
  { resolution: () => settings.resolution },
);

const source = () => screen.textures.hdr;
const region = screen.regions.hdr;
const glow = bloom.create(root, { source, region });
const final = finish.create(root, { format: surface.format, source, region, glow });

frames.create(root, (frame) => {
  screen.fit(); // takes the resolution into the regions

  const scene = frame.encoder.beginRenderPass({
    colorAttachments: { view: screen.views.hdr },
    depthStencilAttachment: { view: screen.views.depth },
  });
  scene.setViewport(0, 0, region.width, region.height, 0, 1);
  // draw the scene
  scene.end();

  glow.record(frame);
  final.record(frame, surface.view(frame));
});

• regions.name describes the drawn region from the target’s top-left corner. Its dimensions are the target size multiplied by resolution, rounded up. The objects stay the same for the life of the set, and fit() updates them.
• A clear clears the whole texture; the viewport limits only the drawing.
• A shader of your own that samples a target reads uv * region / size, kept half a texel inside the region, as bloom and finish do.
• The resolution is at most 1.
• dynamicResolution picks the resolution that keeps the frame under a GPU budget.

For a resolution that stays put, targets.scaled(source, scale) is a smaller SizeSource that sets and cameras can share. Its textures take less memory, and a new scale makes new ones at the next fit(). Both of these scale the whole set; a spec’s scale is fixed per target.

Views

views.name (mip 0) and levels.name (one per mip) are attachment views of one mip level each, made once per rebuild. Use these for attachments. TypeGPU’s default texture view covers every mip level, which an attachment can’t accept. textures.name is the TypeGPU texture, for bind groups and other views.

layers.name holds an attachment view of each layer, and of the one 2D texture for a target without layers. views.name is layer 0. To sample every layer, view the whole array:

import { d } from 'typegpu';
import { 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 all = maps.textures.depth.createView(d.textureDepth2dArray());

Limits

• Nothing waits for the size to settle, so a drag-resize rebuilds the set in every frame the size changes. A rotation is one rebuild.
• Two sets that follow the same source fit and rebuild separately.
• A spec, such as samples, is fixed when the set is made; fit() replaces textures and keeps the specs. Another sample count is another set, and a new description of passes with new pipelines.
• A set created when a feature turns on allocates its textures in that frame, mid-game.
• On React Native, transient targets are plain attachments, and memoryless reports it. Budget memory for their multisampled colour and depth.
• Set storeOp: 'discard' yourself when opening a pass into a transient target outside begin. Memoryless targets reject other store operations. Reading a discarded plain attachment in a later pass or copy produces no validation error.
• Only single-mip attachment views are made. A sampled view of a range of mips is yours to make and keep, with memo if it follows the set.
• With resolution, the textures take the full size’s memory at any resolution.
• WebGPU has no view of a rectangle, so whatever samples a target crops in the shader. A shader of your own that samples with a full-texture uv reads past the region, where the texture holds an older frame or the clear colour.