Damage & partial redraw

A static chart that only re-highlights one point should not re-rasterize the whole canvas. insomni’s damage-tracked partial redraw repaints only the rects that changed, leaving everything else untouched in a persistent backbuffer. This is on by default (config.partialRedraw, config.persistent).

Partial redraw Hover and click a grid where only the touched cells repaint via render(layers, { regions }).

The persistent-backbuffer + scissor model

WebGPU does not guarantee that the swap-chain texture retains its contents between frames. So insomni (when config.persistent) renders into a renderer-owned single-sample color texture — the backbuffer — that does retain its pixels across frames. That retention is what makes a scissored loadOp: "load" partial frame correct: untouched pixels survive in the backbuffer.

Each frame, after the render pass ends, the whole backbuffer is copied onto the swap-chain texture so the browser presents the complete image:

import { blitBackbuffer } from "insomni/internal";

// Recorded after pass.end(), before queue.submit(). Always full-canvas.
blitBackbuffer(encoder, ctx.backbuffer, swapChainTexture, ctx.width, ctx.height);

The blit is always full-canvas, never per-rect. A partial copy is unsound: the swap chain exposes no buffer-age signal and the physical buffer rotated in may be any of the swap chain’s N buffers, so a partial copy would leave pixels outside the damaged rect cleared on whichever buffer is presented — ghosting/flicker. The partial-redraw win lives on the render side (untouched geometry isn’t re-rasterized), not on the blit side; the blit is a cheap fixed-cost copy.

Choosing what to repaint

render(layers, opts) decides full vs partial by this precedence (see Renderer):

fullFrame: true > explicit regions > damage: "auto" > default full.

// 1. Caller-supplied regions (CSS px, Bounds2D = { minX, minY, maxX, maxY }).
renderer.render(layers, { regions: [changedRect] });

// 2. Let core derive the damage by diffing instance AABBs frame-over-frame.
renderer.render(layers, { damage: "auto" });

// 3. Force a whole-canvas repaint.
renderer.render(layers, { fullFrame: true });

A persistent frame with an unchanged composite view and a non-empty regions list (or damage: "auto") takes the partial path; otherwise a full repaint runs. The “view” is a fingerprint over camera, size, dpr, background, z-order, visibility, emphasis, and the caller’s viewKey (group transforms / data domain). Any change to it forces a full frame automatically.

`damage: "auto"`

With damage: "auto", core retains a per-layer snapshot of the previous frame (pack version, instance count, a copy of the per-instance world AABBs) and diffs it against the current pack, projecting the small old ∪ new rects of whatever moved. Notable promotions to full:

The first auto frame (or any layer missing a snapshot) → "auto-damage-seed".
Union damage exceeding 60% of the canvas → "auto-damage-area".
A layer whose glyph version changed → "auto-damage-glyphs" (glyph packs carry no per-glyph AABBs to diff).

Projecting changed instances to repaint regions

When you know which instances changed (a hover halo, a bring-to-front, an emphasis dim/undim), project their AABBs into a CSS-px region and pass it as regions.

The renderer convenience entry:

// Project layer instances at `indices` to one padded CSS-px Bounds2D, or null.
const region = renderer.regionsFromLayerAabbs(layer, [hoveredIndex]);
if (region) renderer.render(layers, { regions: [region] });

The pure helpers behind it (for callers that already hold a layer-space view-projection):

Export	Description
`projectAabbToBounds(minX, minY, maxX, maxY, viewProjection, cssW, cssH, pad?)`	Project one world AABB through a layer-space→NDC matrix into a padded CSS-px `Bounds2D`. All four corners are transformed, so the result is correct under camera rotation.
`unionRegionFromAabbs(aabbs, indices, viewProjection, cssW, cssH, pad?)`	Union the projected regions of `aabbs[i4..i4+3]` for each index into one padded `Bounds2D`, or `null` if none contribute. Degenerate zero AABBs (the cull sentinel) are skipped.
`DEFAULT_REGION_PAD`	`2` — CSS-px padding added on every side, covering SDF anti-alias + a thin halo.

For several far-apart clusters, call unionRegionFromAabbs once per cluster to get disjoint regions; a single call always returns one enclosing rect.

The frame spine

The frame loop is driven by a FrameSpine: it wires a dirty-region channel to a scheduler, coalescing many mark() calls before a flush into one callback (via rect union) and suppressing empty flushes.

import { FrameSpine, createTestSpine, type DirtyRegion } from "insomni/internal";

const spine = new FrameSpine({
  onFlush: (regions: DirtyRegion) => renderFrame(regions),
  // scheduler defaults to a RAF scheduler in production
});
spine.mark([{ rect: { x: 0, y: 0, w: 10, h: 10 }, kind: "paint" }]);

Export	Description
`FrameSpine`	`mark(regions)` accumulates + schedules one flush; `dispose()` removes the subscriber + cancels pending flush.
`FrameSpineOptions`	`{ scheduler?, onFlush }`.
`DirtyRegion`	An array of `{ rect: { x, y, w, h }, kind }` entries.
`createTestSpine(onFlush)`	Returns `{ spine, pump }` backed by a manual scheduler for deterministic tests; call `pump()` to drain synchronously.

The GPU scene root

GpuSceneRoot is a full scene-graph wrapper that owns a FrameSpine, a recursive damage cull, and a PointerRouter, mapping each damage rect 1:1 to a GPU scissor region. Nodes extend GpuSceneNode and emit geometry in drawSelf.

import { GpuSceneRoot, GpuSceneNode, rectToBounds, type PaintCtx } from "insomni/internal";

class DotNode extends GpuSceneNode {
  drawSelf(ctx: PaintCtx): void {
    // push shapes into ctx.layer; read ctx.projectOpts for screen-pixel math
  }
}

const root = new GpuSceneRoot(renderer, layer, {
  projectOpts: () => ({ camera, group: null, dpr, viewportWidth, viewportHeight }),
  groups: () => activeGroups, // folded into viewKey; a group move forces full
});
node.invalidatePaint(); // schedules a coalesced partial frame

The recursive cull prunes any subtree whose AABB misses every damage rect — a leaf deep in a large container repaints only the nodes whose bounds actually touch a damage rect, so cost scales with damaged area, not scene size.

Export	Description
`GpuSceneRoot`	Scene root: `beginFrame`/`endFrame`, `requestPaint()`, `requestPaintRegion(rect)`, `dispatchPointer(e)`, `dispose()`.
`GpuSceneRootOptions`	`{ scheduler?, fullFrame?, onFrameTiming?, projectOpts, groups?, dataKey? }`.
`GpuSceneNode`	Abstract node: `drawSelf(ctx)`, `invalidatePaint/Layout/Data(rect?)`, `projectBounds(ctx, space?)`.
`PaintCtx`	`{ layer, projectOpts }` threaded down the paint walk (no per-node re-walk).
`rectToBounds(r)`	Convert a spatial `Rect` (`{x,y,w,h}`, CSS px) to the renderer’s `Bounds2D`.

Bakes: caching static and z-banded content

A layer whose geometry doesn’t change every frame can be baked to an offscreen texture and composited instead of re-rasterized. cacheLayer(layer) on the renderer does this; the cache policy is driven by a layer’s cache CacheHint ("auto" | "always" | "never") and the config.layerCacheBudgetBytes budget.

The bake is z-aware: it lands under all live geometry when its z-band sits below the first live layer, over when it sits above the last, and is demoted back to a live draw for any frame in which it is sandwiched between two live layers.

Building a bake

A bake runs at config.msaaBakes× MSAA and resolves into a canvas-sized single-sample texture. Crucially, it draws the layer’s MSDF glyphs inside the same bake pass, so a cached layer’s text is part of the snapshot (no live-text desync during pan/zoom).

Export	Description
`createBakeTexture(device, format, width, height)`	Allocate the single-sample resolve target (also `TEXTURE_BINDING` so it can be sampled back). Caller destroys it.
`createBakePipelines(device, format, shader, sampleCount)`	MSAA shape (opaque + transparent) pipelines + an MSDF glyph pipeline + shared camera/instance layouts. `sampleCount` = `config.msaaBakes` (1 \| 4).
`runBakePass(device, config, input, pipelines, opts)`	Single-submit RTT bake: shapes (opaque reverse, transparent forward) then glyphs, into one pass. Creates and destroys all scratch per call.
`bakeViewProjection(space, ctx, camera, dpr, cacheSize?)`	Bake-time view-projection. `world` freezes the camera at bake time; `ui` / `device` bake in their own coordinate space.
`packCamera(vp, out, viewportDevW?, viewportDevH?, dpr?)`	Write a `Mat3` view-projection (+ viewport/dpr tail) into the 10-float camera uniform.
`BakeInput`	`{ shapes: UberPack, glyphs?, atlas? }`.
`BakeOptions`	`{ target, width, height, viewProjection, clearColor, glyphSampler?, clip? }`.
`BakeAtlas`	`{ texture: { view }, pxRange, atlasSize }` — a `GlyphAtlas` satisfies it.
`BakeSizeSource`	`{ width, height }` (device px).
`BakePipelineSet`	The pipelines returned by `createBakePipelines`.

Compositing a bake

The bake texture is drawn back with the composite pipeline — a textured quad that samples the (premultiplied) bake and blends it premultiplied src-over.

import { createCompositePipeline, packFullScreenComposite } from "insomni/internal";

const composite = createCompositePipeline(device, format);
const uniform = new Float32Array(8); // COMPOSITE_UNIFORM_FLOATS
packFullScreenComposite(uniform); // dest = whole NDC viewport, full UV

Export	Description
`createCompositePipeline(device, format)`	Returns `{ pipeline, pipelineInPass, layout }`. `pipeline` is the post-main composite (no depth, bakes that stack above live geometry); `pipelineInPass` runs inside the main pass with inert depth (bakes that land under live geometry).
`packFullScreenComposite(out)`	Fill the uniform for a full-screen bake: dest = whole NDC viewport, UVs flipped so the texture reads upright.
`COMPOSITE_UNIFORM_FLOATS` / `COMPOSITE_UNIFORM_BYTES`	`8` / `32` — the composite uniform size (dest NDC rect + source UV rect).
`CompositePipelineSet`	The set returned by `createCompositePipeline`.

Configuration

Knob	Default	Effect
`partialRedraw`	`true`	Honor `regions` / `damage: "auto"` in `render()`. Read live each frame.
`persistent`	`true`	Render into the persistent backbuffer (required for partial redraw to be sound).
`msaaBakes`	`4`	MSAA sample count for bakes (`1` or `4`).
`layerCacheBudgetBytes`	`128 MiB`	Resident memory cap for auto-managed bakes. `0` (or negative) = unlimited. `"always"` / manual `cacheLayer()` bakes are pinned.