Frames

Next frameNext frame with a burstNext frame that throws

Make the frame throw to see writes arrive while recorded commands and callbacks are dropped. Calls appear on the left and GPU execution on the right, with queue writes before the command buffer.

Modules record into an encoder they are handed. The loop makes one each frame, runs your recorder with it and submits once, so a GPU capture shows the whole frame.

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

const loop = frames.create(root, ({ encoder, time, dt, index }) => {
  // record passes into `encoder`; don't submit it
});

frames.animate(loop); // calls loop.run(seconds) at every animation frame

• time is seconds since the first submitted frame. dt is seconds since the previous frame and is 0 on the first. index counts frames submitted before this one. loop.seconds holds the time of the last submitted frame, so a frame that throws leaves it unchanged.
• interval estimates the display’s frame interval. It follows the shortest recent frames, so a frame that misses the display barely moves it. Budget per-frame work with it, as dynamic resolution does.
• The loop schedules nothing. run(seconds) records one frame and submits it; a time that isn’t finite, or goes back, throws a RangeError.
• frames.animate(loop) calls run at every animation frame. A test or a benchmark calls run itself.
• The recorder is synchronous. Returning a promise throws a TypeError, and so does calling run from inside it.
• If the recorder throws or calls destroy(), the frame submits no further commands and the clock doesn’t advance. Queue writes and commands already sent with frame.submit() still run. After destroy(), run returns false.

Running the loop

frames.animate(loop, options) runs the loop at every animation frame, on the web and React Native.

• Each frame advances time by at most maxDt, which defaults to 0.1 s. This caps the time added after a stall or a hidden tab resumes.
• With a surface, animation and time stop while it is paused. The first frame after resume() has a dt of 0. On React Native, pause it from AppState. On the web, pause it for a canvas scrolled out of view or a pause menu; browsers already stop a hidden tab’s frames.
• destroy() on what it returns requests no more frames; inside a frame, such as at game over, it makes that frame the last. The loop stays yours.
• An error ends animation and reaches onError once. Without onError, the animation frame callback throws it.
• frame.time is the loop’s own time, so it drifts from performance.now() after the first pause or stall. Read performance.now() for wall time.

A canvas that draws only while on screen pauses its surface from an IntersectionObserver:

frames.animate(loop, { surface });

new IntersectionObserver(([entry]) =>
  entry?.isIntersecting ? surface.resume() : surface.pause(),
).observe(canvas);

After the submit

A readback records its copy in the frame but can only map it once the copy is submitted. A module that has to wait for the submit registers a callback while it records:

function createProbe(root: TgpuRoot /* , ... */) {
  const map = () => {
    // staging.mapAsync(GPUMapMode.READ).then(...)
  };

  return {
    record(frame: Frame) {
      // copy into the staging buffer on frame.encoder
      frame.afterSubmit(map);
    },
  };
}

• Callbacks run right after the frame’s last submit, in registration order, and only for frames that finish.
• Every callback runs even if one throws. The frame still counts. run throws the callback error afterwards, or an AggregateError if several failed.
• afterSubmit throws unless its own frame is recording. Each run makes a new Frame, so a module that acts once a frame tells frames apart by it.
• Create the callback once, as above, so recording allocates nothing.

Submitting early

frame.submit() submits the commands recorded so far. The next access to frame.encoder creates another encoder, and the loop submits the remaining commands when your recorder returns. Try the per-step values first. Each early submit adds a queue.submit and splits the frame in a GPU capture.

function frame(frame: Frame) {
  for (const phase of phases) {
    params.write({ phase });
    const pass = frame.encoder.beginComputePass();
    pass.setPipeline(step);
    pass.dispatchWorkgroups(64);
    pass.end();
    frame.submit(); // queued ahead of the next write
  }

  // the draws go into a fresh frame.encoder, which the loop submits
}

• End every pass first. A submit with a pass open is a WebGPU validation error that voids everything recorded since the last submit; a recording root throws there instead.
• Only the recorder you pass to frames.create calls it; a module never submits. A module reads frame.encoder at each call and never keeps it, since a kept encoder may have been submitted.
• A recording method that takes a frame or an encoder reads the encoder with frames.encoderOf(target) at each call.
• A frame ending with submit() sends no empty command buffer. It creates another encoder only if frame.encoder is read again.

Submit once per frame unless an early submit is required. Use one when:

• A step reads a value you can’t supply another way, such as a library kernel that reads its own createUniform.
• A library call submits its own work during a frame. Examples include a pipeline drawn without an encoder and a mesh pool’s add without an encoder. That work runs before your frame’s pending commands. Submit first to preserve order, or pass the encoder where supported.
• A command may be invalid. WebGPU invalidates its whole command buffer, while commands submitted before it still run.
• The GPU could start sooner. Submitting the simulation before recording draws lets the GPU work while the CPU records the rest.

Stepping by hand

A benchmark or GPU capture needs the same steps on every run, regardless of display rate. Leave out frames.animate and web.host, make the loop yourself, and call run once per step:

const STEP = 1 / 60;
const STEPS = 600;
const loop = frames.create(root, (frame) => scene.frame(frame));

const start = performance.now();
for (let i = 0; i < STEPS; i++) {
  loop.run(i * STEP); // one step, one submit
}
await root.device.queue.onSubmittedWorkDone();
const msPerStep = (performance.now() - start) / STEPS;

• run takes the time, not the step, so i * STEP gives every frame a dt of one step.
• Each run submits, so a uniform written in one step lands after the step before it was submitted. No count on the GPU is needed here.
• onSubmittedWorkDone() resolves once the GPU has finished everything submitted. Wait for it before stopping a timer or reading results.
• A fixed step of the same length runs exactly one step per frame. A canvas surface of a fixed size draws the same pixels on every screen, and offscreenSurface from @typegpu/kit/testing gives the scene a surface without a canvas.