History

latticeThin beams turning over a sky, embers rising through them, smoothed over frames with TAA.

PauseOpen the full example

The lattice stores its turn angle in history.create(root, d.f32, { usage: 'uniform' }). TAA’s motion output runs the vertex code again with previously to read last frame’s angle. Switch to a plain uniform to make both runs read the current angle. The motion view then shows only camera motion. TAA samples last frame’s colour at the wrong positions, and the beams dim as they turn. Raise the speed to see the effect.

Motion vectors and reprojection need last frame’s camera and object positions. Maintaining separate shader functions for current and previous state risks differences between them.

history.previously(fn) compiles fn a second time. In that copy, accessors filled with history.temporal(current, previous) read previous. history.create stores last frame’s buffer state for that fill. The kit’s cameras store their own previous views, and a table or a set of instances created with history: true keeps its own rows. Passes use previously to compute last frame’s vertex for outputs such as motion.

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

const offsets = tgpu.accessor(d.arrayOf(d.vec3f, 64));
const placed = history.create(root, d.arrayOf(d.vec3f, 64));

const offsetOf = (i: number) => {
  'use gpu';
  return offsets.$[i]!;
};
const offsetBefore = history.previously(offsetOf); // last frame's

const moved = root.createMutable(d.arrayOf(d.f32, 64));
const measure = tgpu.computeFn({
  workgroupSize: [64],
  in: { gid: d.builtin.globalInvocationId },
})(({ gid }) => {
  'use gpu';
  if (gid.x >= 64) return;
  moved.$[gid.x] = std.distance(offsetOf(gid.x), offsetBefore(gid.x));
});
const measuring = root.with(offsets, placed.reading).createComputePipeline({ compute: measure });

placed.write(next); // lands at the next advance
frames.animate(
  frames.create(root, (frame) => {
    placed.advance(frame);
    const pass = frame.encoder.beginComputePass();
    pass.setPipeline(measuring);
    pass.dispatchWorkgroups(1);
    pass.end();
  }),
);

Last frame’s code

• history.epoch is a slot, 'current' or 'previous', and previously resolves its function with 'previous'. Call what it returns from any 'use gpu' function, in any stage.
• history.temporal(current, previous) fills an accessor with any values it accepts. You can use two uniforms, two buffers, or a current constant and a previous uniform.
• Code that never calls a previously function binds current only.

A buffer’s history

history.create(root, schema, options) owns three buffers, for current state, previous state and the next write.

• reading fills a state accessor. The default storage usage binds read-only in render pipelines and read-write in compute pipelines. It can fill a mutable accessor for kernels that update the state. usage: 'uniform' suits small state written by the CPU.
• write(value) holds a value for the next advance. A queue write lands before everything the frame submits, so a write straight into current would be copied aside as last frame’s too.
• advance(frame) copies current to previous, then the held write into current. Call it once a frame, before what reads or moves the state. A write that no advance follows never shows. A frame that does not submit, such as one that throws, leaves the write for the next.
• current and previous are the buffers, for readback and copies.
• destroy(), or [Symbol.dispose], destroys the three buffers.

Pause

writeeach frameon click

write(t)

Choose write on click, then write a frame index t. Both versions copy current to previous, but direct writes arrive before the copy and erase motion; history preserves it for the written frame.

In a drawing

Store state that moves a drawing, such as the lattice’s turn angle, in a history. Read it through a vertex-code accessor filled with reading by the drawing. Outputs that compute last frame’s vertex then include the object’s motion:

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

// How far the triangle has turned, now and last frame
const turn = tgpu.accessor(d.f32);
const turned = history.create(root, d.f32, { usage: 'uniform' });

const at = (vertexIndex: number, _instanceIndex: number) => {
  'use gpu';
  const angle = turn.$ + d.f32(vertexIndex) * 2.1;
  const world = d.vec3f(std.cos(angle), std.sin(angle), 0);
  return Corner({ position: cameras.current.$.viewProjection * d.vec4f(world, 1) });
};
const spinner = scene.add({
  Vertex: Corner,
  at,
  surfaceOf,
  color: passes.shaded,
  inject: () => (cfg) => cfg.with(turn, turned.reading),
  draw: (pass) => pass.draw(3),
});

// Each frame, before the pass that draws it
turned.write(frame.time);
turned.advance(frame);

Filled with a plain uniform, last frame’s code reads this frame’s turn, and the motion output sees only the camera move.

Limits

• History stores only one previous frame.
• advance copies the whole state every frame, and again in a frame with a write.
• A write that jumps the state, such as a teleport, reads as motion for a frame.