Readback

Pauseread()

hz603010none

map takes

2

framesslots

3

Press read() to wait for the next capture of a buffer containing the frame index. Set 60 Hz, a slow map and one staging slot to see captures skipped while the buffer maps.

The GPU executes commands after the CPU records them. A result such as the object under a cursor therefore reaches the CPU in a later frame. TypeGPU’s buffer.read() creates a staging buffer, submit and promise per call. A readback reuses a ring of staging buffers, records copies in your frame’s encoder and maps them after submit.

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

const hits = root.createBuffer(d.arrayOf(d.u32, 4)).$usage('storage');
const probe = readback.create(root, hits, { hz: 30 });

frames.create(root, (frame) => {
  // ... the pass that writes `hits`
  probe.capture(frame); // after it
  scheduler.run(frame);

  const polled = probe.take(); // polled: each new value once, or undefined
  if (polled) onHits(polled[0]!);
});

function* react() {
  const counts = yield* coroutines.until(probe.next()); // or waited on: the next capture
  onHits(counts[0]!);
}

Placing the capture

capture(frame) copies the whole buffer at that point in the command order. Place it after the pass that fills a counter, or before the passes when a picker must read the frame already on screen.

• It records only while a next() waits, after a request(), or when hz is due.
• While every staging buffer is mapping, it is skipped and tried again next frame.
• Record the pass that fills the buffer every frame and let hz pick the frames that copy; a pass that counts costs microseconds. Gating that pass with a clock of your own makes two cadences that disagree, so a copy can land in a frame the pass skipped.
• A frame captures once; a second call does nothing.
• A frame that is never submitted hands its reads to the next capture.

Reading

• latest holds the newest value. latestFrame identifies the frame that copied it. Reads return the buffer’s value transformed by decode, if supplied. If decode throws, reads waiting on that copy fail with its error.
• take() returns latest once per completed copy, then undefined until another copy completes. Two callers split those values. If both need every value, have each read latest and track latestFrame.
• next() returns a promise for the next capture’s value. Promises asked for until then share one copy. It stays pending until a capture completes. In a coroutine, wait for it with yield* coroutines.until(probe.next()).
• request() makes the next capture copy with no read waiting, for a buffer written on demand rather than every frame. A picker’s pick requests its own copy. A capture skipped while every staging buffer maps leaves the request open.
• destroy(), or using, destroys the staging buffers and rejects waiting and later promises. capture then records nothing, and take and latest give undefined.
• For counters that only increase, compare each read with the last value to handle late or repeated reads. Events does that for named counters.

Reading bytes

Reads decode the whole schema into JavaScript values, one object per struct, so a large array of structs allocates thousands of objects per read. Pass bytes: true to skip decoding. decode then receives the copied bytes, which follow the schema’s WGSL layout with its padding. They are valid only during the call, so read them into arrays of your own. Without decode, reads return a copy as an ArrayBuffer.

const Cell = d.struct({ level: d.f32, source: d.u32 }); // 8 bytes a cell
const cells = root.createBuffer(d.arrayOf(Cell, 12288)).$usage('storage');

const levels = new Float32Array(12288);
const field = readback.create(root, cells, {
  bytes: true,
  decode: (bytes) => {
    const words = new Float32Array(bytes);
    for (let i = 0; i < levels.length; i++) levels[i] = words[i * 2]!;
    return levels;
  },
});

Rate

hz schedules captures at that rate and updates latest without a waiting read. It uses a cadence, so the first capture is immediate.

Staleness

• Call reset() after clearing a buffer or reloading a scene to discard earlier copies. It sets latest to undefined and latestFrame to -1, and moves waiting reads to the next capture.
• To restart counters, clear the buffer in the frame, before the passes that count, and reset(). Otherwise a copy made before the clear can land after it, and counters that take differences run backwards.
• A late map never replaces a newer latest.
• A promise that already resolved keeps its value, even if its coroutine resumes after a reset. Compare a held result with latest.
• A table’s changes reach the GPU at the first submit after its flush. Compare latestFrame with that frame’s index when a value must be newer than a change.

Device loss rejects every map. Promises waiting on a copy reject with the map’s error, later captures also fail, and latest keeps its last value. Create the modules again on another root to recover.

Limits

• A capture placed before the pass that fills the buffer reads the previous frame’s value, and nothing catches that.
• A capture copies the whole buffer without a range option.
• A readback reads a fixed buffer. A varying list read once, on demand, needs code of its own.