Skip to content

Commit 8df2d8d

Browse files
vanceingallsclaude
andauthored
feat(core): capture motion blur pose, discovery and compositor (#5875)
Add the three pure modules capture motion blur is built from: pose (an element's box as an affine in composition space, and the poses between two times), discover (find the elements that move fast enough for a smear to show) and composite (redraw each mover along its path into one frame). Nothing calls them yet; the runtime that wires them up lands in the next change. The pose reads the individual translate, rotate and scale properties in CSS order, adds the offsetParent border back and subtracts ancestor scroll, so it matches getBoundingClientRect for a box centered with translate: -50% -50%. Folded review fixes: R3 (pose half; the scan's 3D skip for individual transforms lands with the mover scan). Co-authored-by: Claude Sonnet 5.5 <[email protected]>
1 parent 0874518 commit 8df2d8d

6 files changed

Lines changed: 995 additions & 0 deletions

File tree

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,80 @@
1+
import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
2+
import { createCompositor, type MoverFrame } from "./composite";
3+
import { IDENTITY, translate } from "./pose";
4+
5+
function fakeContext() {
6+
return {
7+
drawImage: vi.fn(),
8+
clearRect: vi.fn(),
9+
setTransform: vi.fn(),
10+
globalAlpha: 1,
11+
globalCompositeOperation: "source-over",
12+
};
13+
}
14+
let offscreen: Array<ReturnType<typeof fakeContext>> = [];
15+
16+
beforeEach(() => {
17+
offscreen = [];
18+
vi.stubGlobal(
19+
"OffscreenCanvas",
20+
class {
21+
constructor(
22+
public width: number,
23+
public height: number,
24+
) {}
25+
getContext() {
26+
const ctx = fakeContext();
27+
offscreen.push(ctx);
28+
return ctx;
29+
}
30+
},
31+
);
32+
});
33+
afterEach(() => vi.unstubAllGlobals());
34+
35+
const capture = {} as CanvasImageSource;
36+
const background = {} as CanvasImageSource;
37+
const slide = (from: number, to: number, n = 16) =>
38+
Array.from({ length: n }, (_, k) => translate(IDENTITY, from + ((to - from) * (k + 0.5)) / n, 0));
39+
const mover = (w: number, h: number, taps: ReturnType<typeof slide>): MoverFrame => ({
40+
w,
41+
h,
42+
now: translate(IDENTITY, 50, 0),
43+
taps,
44+
});
45+
46+
describe("createCompositor", () => {
47+
it("keeps no crop for a mover that does not travel a pixel, and draws only the background", () => {
48+
const c = createCompositor(100, 100);
49+
const movers = [mover(10, 10, slide(0, 0.5))];
50+
const kept = c.crop(capture, movers);
51+
expect(kept).toEqual([false]);
52+
const out = fakeContext();
53+
expect(c.draw(background, out as never, movers, kept)).toEqual({ blurred: 0, taps: 0 });
54+
expect(out.drawImage).toHaveBeenCalledTimes(1);
55+
expect(out.drawImage.mock.calls[0]?.[0]).toBe(background);
56+
});
57+
58+
it("crops a moving mover once and lays one tap per draw over the background", () => {
59+
const c = createCompositor(1000, 100);
60+
const movers = [mover(10, 10, slide(0, 100))];
61+
const kept = c.crop(capture, movers);
62+
expect(kept).toEqual([true]);
63+
const crop = offscreen.at(-1);
64+
expect(crop?.drawImage).toHaveBeenCalledWith(capture, 0, 0);
65+
const out = fakeContext();
66+
const stats = c.draw(background, out as never, movers, kept);
67+
const accum = offscreen[0];
68+
expect(stats.blurred).toBe(1);
69+
expect(accum?.drawImage).toHaveBeenCalledTimes(stats.taps);
70+
expect(accum?.globalAlpha).toBeCloseTo(1 / stats.taps, 9);
71+
// Background first, then the trail over it.
72+
expect(out.drawImage.mock.calls[0]).toEqual([background, 0, 0]);
73+
expect(out.drawImage).toHaveBeenCalledTimes(2);
74+
});
75+
76+
it("leaves a mover sharp when its box is too big to copy every frame", () => {
77+
const c = createCompositor(100, 100);
78+
expect(c.crop(capture, [mover(1000, 1000, slide(0, 100))])).toEqual([false]);
79+
});
80+
});
Lines changed: 135 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,135 @@
1+
/**
2+
* The per-frame draw: a background, then each mover's own pixels redrawn along its path.
3+
*
4+
* Each mover is cropped from a capture of the scene and drawn at every tap pose into a float
5+
* buffer, additive at weight 1/n: the shutter integral. Its coverage fades at the path ends, so
6+
* the trail needs a background without the mover (a second capture, movers hidden); falling back
7+
* to the sharp frame leaves thin lines looking unblurred.
8+
*
9+
* Image-space approximation: a mover's box contents move with it; ink outside it is not redrawn.
10+
*/
11+
12+
import { type Affine, invert, sweep, thinTaps } from "./pose";
13+
14+
export interface MoverFrame {
15+
w: number;
16+
h: number;
17+
/** The pose the capture shows (frame time). */
18+
now: Affine;
19+
/** Poses across the shutter. */
20+
taps: Affine[];
21+
}
22+
23+
interface CompositeStats {
24+
blurred: number;
25+
taps: number;
26+
}
27+
28+
type Context2D = CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D;
29+
interface Layer {
30+
canvas: OffscreenCanvas;
31+
ctx: OffscreenCanvasRenderingContext2D;
32+
}
33+
34+
// Float16 keeps n additive 1/n-weighted taps exact; 8-bit loses up to ~n/2 levels per channel.
35+
function makeLayer(w: number, h: number): Layer {
36+
const canvas = new OffscreenCanvas(w, h);
37+
let ctx: OffscreenCanvasRenderingContext2D | null = null;
38+
try {
39+
ctx = canvas.getContext("2d", { colorType: "float16" } as CanvasRenderingContext2DSettings);
40+
} catch {
41+
ctx = null;
42+
}
43+
ctx = ctx ?? canvas.getContext("2d");
44+
if (!ctx) throw new Error("capture motion blur: no 2D context for the accumulation buffer");
45+
return { canvas, ctx };
46+
}
47+
48+
/** Whether a mover travels far enough within this shutter to draw a trail at all. */
49+
function moves(mover: MoverFrame, frameW: number, frameH: number): boolean {
50+
const { travel, rect } = sweep(mover.taps, mover.w, mover.h, frameW, frameH);
51+
return rect !== null && travel >= 1;
52+
}
53+
54+
export function createCompositor(width: number, height: number) {
55+
const accum = makeLayer(width, height);
56+
const crops: Layer[] = [];
57+
// A mover box this many times the frame is too big to copy every frame; it is left sharp.
58+
const maxCropArea = width * height * 4;
59+
60+
const cropLayer = (i: number, w: number, h: number): Layer => {
61+
let layer = crops[i];
62+
if (!layer || layer.canvas.width < w || layer.canvas.height < h) {
63+
layer = makeLayer(
64+
Math.max(w, layer?.canvas.width ?? 1),
65+
Math.max(h, layer?.canvas.height ?? 1),
66+
);
67+
crops[i] = layer;
68+
}
69+
return layer;
70+
};
71+
72+
/** Copy each mover's frame-time pixels out of `src`; false marks a mover to leave sharp. */
73+
function crop(src: CanvasImageSource, movers: MoverFrame[]): boolean[] {
74+
return movers.map((mover, i) => {
75+
const { w, h } = mover;
76+
const back = invert(mover.now);
77+
if (!back || w * h > maxCropArea || !moves(mover, width, height)) return false;
78+
const c = cropLayer(i, w, h).ctx;
79+
c.setTransform(1, 0, 0, 1, 0, 0);
80+
c.globalCompositeOperation = "source-over";
81+
c.globalAlpha = 1;
82+
c.clearRect(0, 0, w, h);
83+
c.setTransform(back.a, back.b, back.c, back.d, back.e, back.f);
84+
c.drawImage(src, 0, 0);
85+
return true;
86+
});
87+
}
88+
89+
function trail(out: Context2D, mover: MoverFrame, layer: Layer): number {
90+
const { w, h } = mover;
91+
const { travel, rect } = sweep(mover.taps, w, h, width, height);
92+
if (!rect) return 0;
93+
const taps = thinTaps(mover.taps, travel);
94+
const a = accum.ctx;
95+
a.setTransform(1, 0, 0, 1, 0, 0);
96+
a.globalCompositeOperation = "source-over";
97+
a.globalAlpha = 1;
98+
a.clearRect(rect.x, rect.y, rect.w, rect.h);
99+
a.globalCompositeOperation = "lighter";
100+
a.globalAlpha = 1 / taps.length;
101+
for (const m of taps) {
102+
a.setTransform(m.a, m.b, m.c, m.d, m.e, m.f);
103+
a.drawImage(layer.canvas, 0, 0, w, h, 0, 0, w, h);
104+
}
105+
out.drawImage(accum.canvas, rect.x, rect.y, rect.w, rect.h, rect.x, rect.y, rect.w, rect.h);
106+
return taps.length;
107+
}
108+
109+
/** `background` into `out`, then the trail of every mover `crop` kept. */
110+
function draw(
111+
background: CanvasImageSource,
112+
out: Context2D,
113+
movers: MoverFrame[],
114+
kept: boolean[],
115+
): CompositeStats {
116+
out.setTransform(1, 0, 0, 1, 0, 0);
117+
out.globalAlpha = 1;
118+
out.globalCompositeOperation = "copy";
119+
out.drawImage(background, 0, 0);
120+
out.globalCompositeOperation = "source-over";
121+
const stats: CompositeStats = { blurred: 0, taps: 0 };
122+
movers.forEach((mover, i) => {
123+
const layer = crops[i];
124+
if (!kept[i] || !layer) return;
125+
const n = trail(out, mover, layer);
126+
if (n > 0) {
127+
stats.blurred++;
128+
stats.taps += n;
129+
}
130+
});
131+
return stats;
132+
}
133+
134+
return { crop, draw };
135+
}
Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
import { afterEach, describe, expect, it, vi } from "vitest";
2+
import { discoverMovers } from "./discover";
3+
4+
// jsdom lays nothing out: each element's rect follows the x its fake timeline writes.
5+
function element(parent: Element, id: string): HTMLElement {
6+
const el = document.createElement("div");
7+
el.id = id;
8+
parent.append(el);
9+
el.getBoundingClientRect = () => {
10+
const x = parseFloat(el.style.transform.replace("translateX(", "")) || 0;
11+
return { left: x, top: 0, right: x + 10, bottom: 10, width: 10, height: 10 } as DOMRect;
12+
};
13+
return el;
14+
}
15+
16+
function setup() {
17+
const scene = document.createElement("div");
18+
const fast = element(scene, "fast");
19+
const fastChild = element(fast, "fast-child");
20+
const slow = element(scene, "slow");
21+
const still = element(scene, "still");
22+
const off = element(scene, "off");
23+
off.setAttribute("data-motion-blur", "off");
24+
// 1 s at 30 fps: `fast` and `off` cross 300 px (10 px/frame), `slow` 15 px (0.5 px/frame).
25+
const seek = (t: number): void => {
26+
fast.style.transform = `translateX(${300 * t}px)`;
27+
fastChild.style.transform = `translateX(${200 * t}px)`;
28+
slow.style.transform = `translateX(${15 * t}px)`;
29+
off.style.transform = `translateX(${300 * t}px)`;
30+
};
31+
seek(0);
32+
return { scene, fast, fastChild, slow, still, off, seek };
33+
}
34+
35+
describe("discoverMovers", () => {
36+
afterEach(() => vi.restoreAllMocks());
37+
38+
it("keeps fast, outermost movers that are not opted out", () => {
39+
const { scene, fast, seek } = setup();
40+
const { movers } = discoverMovers({ scene, durationSeconds: 1, fps: 30, seek });
41+
expect(movers).toEqual([fast]);
42+
});
43+
44+
it("marks every changing element dynamic, slow and opted-out ones included", () => {
45+
const { scene, fast, fastChild, slow, still, off, seek } = setup();
46+
const { dynamic } = discoverMovers({ scene, durationSeconds: 1, fps: 30, seek });
47+
expect(
48+
dynamic.has(fast) && dynamic.has(fastChild) && dynamic.has(slow) && dynamic.has(off),
49+
).toBe(true);
50+
expect(dynamic.has(still)).toBe(false);
51+
});
52+
53+
it("ignores a CSS animation of offset-distance, which the pose has no term for", () => {
54+
const scene = document.createElement("div");
55+
const box = document.createElement("div");
56+
scene.append(box);
57+
let x = 0; // moves with no inline style change: only getAnimations can nominate it
58+
box.getBoundingClientRect = () =>
59+
({ left: x, right: x + 10, top: 0, bottom: 10, width: 10 }) as DOMRect;
60+
const scan = (prop: string) => {
61+
const effect = { target: box, getKeyframes: () => [{ [prop]: "0" }] };
62+
Object.defineProperty(document, "getAnimations", {
63+
value: () => [{ effect }],
64+
configurable: true,
65+
});
66+
const seek = (t: number): void => void (x = 300 * t);
67+
return discoverMovers({ scene, durationSeconds: 1, fps: 30, seek }).movers;
68+
};
69+
expect(scan("offsetDistance")).toEqual([]);
70+
expect(scan("translate")).toEqual([box]);
71+
Reflect.deleteProperty(document, "getAnimations");
72+
});
73+
74+
it("drops a mover in a 3D context, or on an offset-path the pose cannot follow", () => {
75+
const { scene, fast, seek } = setup();
76+
const real = window.getComputedStyle;
77+
let own: object = {};
78+
vi.spyOn(window, "getComputedStyle").mockImplementation((el: Element) =>
79+
el === fast
80+
? ({ transform: "none", transformStyle: "flat", perspective: "none", ...own } as never)
81+
: real(el),
82+
);
83+
for (own of [
84+
{ transform: "matrix3d(1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1)" },
85+
{ offsetPath: "path('M 0 0')" },
86+
])
87+
expect(discoverMovers({ scene, durationSeconds: 1, fps: 30, seek }).movers).toEqual([]);
88+
});
89+
});

0 commit comments

Comments
 (0)