feat(core): motion blur preview draws fewer filter copies at lower preview quality (#7547)

* feat(core): motion blur preview draws fewer filter copies at lower preview quality

The filter tier's preview draws 16 copies at preview quality 1/2 and 8 at 1/4 and
below; renders keep 32. Preview facts now list those levels in lighterAt once the
filter tier has movers, so a host that steps quality down on choppy playback can do
so for a film whose only load is blur.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

* refactor(core): name the blur preview copies instead of commenting them

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
Vance Ingalls
2026-11-11 23:01:58 +00:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 6bd9bb8a44
commit 6cc734fd24
5 changed files with 63 additions and 14 deletions
+1 -1
View File
@@ -91,7 +91,7 @@ In the page, `window.__hfMotionBlur.report()` returns `state`, `tier`, `reason`,
- **Distributed renders.** Blur applies in every chunk, drawn with the filter tier on `auto`. Measured on two real 1080p films with plan, `renderChunk` and assemble at 240 frames per chunk, in a software-GPU Chrome 153 on a machine other work was loading (load average 12 to 25), one run per arm: summed chunk CPU seconds went from 155 to 246 (1.6 times) on `k3-promo` and from 338 to 545 (1.6 times) on `spacex-launch`; summed chunk wall time rose 1.2 and 1.4 times. A film with `data-motion-blur="on"` also plans screenshot capture instead of BeginFrame capture, and the measured cost includes that switch.
- **Editing.** The filter tier never wraps anything. With capture the root is wrapped only while playing or rendering; paused, it is plain DOM, so click-to-select works.
- **Capture only.** Blurred preview can run at half the frame rate on heavy compositions, and a `<video>` drawn through the capture looks about 2–3% darker in the browser editor preview than in normal playback. Renders are not affected.
- **Preview and render.** `auto` draws the same way in both. A page that asks for capture previews with the filter tier in a browser without HTML in Canvas, so a spin or zoom looks softer there than in the render.
- **Preview and render.** `auto` draws the same way in both at full preview quality. When a host lowers preview quality (Studio's `set-preview-quality` message), the filter tier's preview draws 16 copies at 1/2 and 8 at 1/4 and below; renders always draw 32. Against a sub-frame reference, 16 copies stayed within measurement noise of 32. 8 copies differ visibly on turning content. A page that asks for capture previews with the filter tier in a browser without HTML in Canvas, so a spin or zoom looks softer there than in the render.
- **Worker count.** Output is not bit-identical between worker counts (around 60 dB PSNR), about the size of the difference chunking already causes.
- **Not handled.** Pose errors under CSS `zoom`, `position: fixed` and `foreignObject`; a very short Web Animations API animation that falls between scan samples; a large see-through mover (a full-frame translucent sweep), which is left sharp while its fast children still blur. With capture, a mover is drawn above the static content, so a static element that should cover a mover does not.
- **Limits of the filter tier** (the default), as measured on one-pattern test compositions:
@@ -17,6 +17,13 @@ import type { CaptureMotionBlurHost, Config, Report, Tier } from "./tier";
const NS = "http://www.w3.org/2000/svg";
/** Copies per mover; the softening along the motion closes the steps between them. */
const COPIES = 32;
export const FILTER_LIGHTER_LEVELS = [0.5, 0.25] as const;
const previewCopiesAt = (level: number): number => (level >= 1 ? COPIES : level >= 0.5 ? 16 : 8);
let previewCopies = COPIES;
export function setFilterPreviewQuality(level: number): void {
if (level > 0) previewCopies = previewCopiesAt(level);
}
const PREVIEW_READS = 4;
const RENDER_READS = 8;
const FILTER_ID = "hf-mb";
@@ -42,15 +49,14 @@ function node<K extends keyof SVGElementTagNameMap>(
return el;
}
/** 32 offset copies, averaged in pairs so 8-bit filter buffers do not band, then softened. */
function buildLayer(defs: SVGDefsElement, index: number, el: HTMLElement): Layer {
const id = `${FILTER_ID}-${index}`;
/** Offset copies (a power of two), averaged in pairs so 8-bit filter buffers do not band, then softened. */
function buildLayer(defs: Element, id: string, el: HTMLElement, copies: number): Layer {
const filter = node(defs, "filter", {
id,
"color-interpolation-filters": "sRGB",
filterUnits: "userSpaceOnUse",
});
const offsets = Array.from({ length: COPIES }, (_, k) =>
const offsets = Array.from({ length: copies }, (_, k) =>
node(filter, "feOffset", { in: "SourceGraphic", result: `s${k}` }),
);
let level = offsets.map((_, k) => `s${k}`);
@@ -177,9 +183,10 @@ export function createFilterTier(
for (const el of [...styled]) drop(el);
}
function layerOf(el: HTMLElement): Layer {
let layer = layers.get(el);
if (layer) return layer;
function layerOf(el: HTMLElement, copies: number): Layer {
const kept = layers.get(el);
if (kept?.offsets.length === copies) return kept;
kept?.filter.remove();
if (!defs) {
defs = document.createElementNS(NS, "svg");
defs.setAttribute("width", "0");
@@ -190,13 +197,14 @@ export function createFilterTier(
node(defs, "defs", {});
document.documentElement.append(defs);
}
layer = buildLayer(defs.querySelector("defs") ?? defs, layers.size, el);
const id = kept?.filter.id ?? `${FILTER_ID}-${layers.size}`;
const layer = buildLayer(defs.querySelector("defs") ?? defs, id, el, copies);
layers.set(el, layer);
return layer;
}
function show(el: HTMLElement, plan: FilterPlan): void {
const layer = layerOf(el);
const layer = layerOf(el, plan.offsets.length);
aim(layer, plan);
const base = strip(el) || layer.css;
el.style.filter = base ? `${base} ${layer.url}` : layer.url;
@@ -217,7 +225,7 @@ export function createFilterTier(
t,
reads: engineMode ? RENDER_READS : PREVIEW_READS,
...shutterTimes(config.shutterDeg, config.phaseDeg, host.fps),
taps: COPIES,
taps: engineMode ? COPIES : previewCopies,
frameW: width,
scene: root,
frameH: height,
@@ -6,10 +6,12 @@ import {
type CaptureMotionBlurHost,
captureMotionBlurBusy,
initCaptureMotionBlur,
motionBlurLighterLevels,
paintCaptureMotionBlur,
releaseCaptureMotionBlurFrame,
resetCaptureMotionBlurForTests,
setFilterFallbackForTests,
setMotionBlurPreviewQuality,
trackAcceleratedCanvases,
} from ".";
@@ -1976,6 +1978,22 @@ describe("filter fallback", () => {
expect(document.querySelectorAll("feGaussianBlur")).toHaveLength(1);
});
it("draws fewer copies in preview below Full, and the full 32 in a render", () => {
const { el, h } = movingHost(CAPTURE);
initCaptureMotionBlur(h);
expect(motionBlurLighterLevels()).toEqual([]);
setMotionBlurPreviewQuality(0.5);
void paintCaptureMotionBlur(0.5, PLAY);
expect(document.querySelectorAll("feOffset")).toHaveLength(16);
expect(motionBlurLighterLevels()).toEqual([0.5, 0.25]);
setMotionBlurPreviewQuality(0.125);
void paintCaptureMotionBlur(0.6, PLAY);
expect(document.querySelectorAll("feOffset")).toHaveLength(8);
expect(el.style.filter).toMatch(/url\("?#hf-mb-0"?\)/);
void paintCaptureMotionBlur(0.5, { engineMode: true });
expect(document.querySelectorAll("feOffset")).toHaveLength(32);
});
it("stays off when the renderer turned blur off", () => {
win.__HF_PAGE_MOTION_BLUR_OFF__ = "hdr-render";
const { el, h } = movingHost();
@@ -38,7 +38,7 @@ import { swallow } from "../diagnostics";
import { createCompositor, type MoverFrame } from "./composite";
import { readMotionBlurSettings } from "../../motionBlurSettings";
import { scanMovers, whileCallbacksMuted } from "./discover";
import { createFilterTier } from "./filterTier";
import { createFilterTier, FILTER_LIGHTER_LEVELS, setFilterPreviewQuality } from "./filterTier";
import { compositionFingerprint, coverageSampler } from "./fingerprint";
import { readMoverFrames, shutterTimes } from "./frames";
import { createPoseReader } from "./pose";
@@ -783,6 +783,15 @@ export function paintCaptureMotionBlur(
return done;
}
export function setMotionBlurPreviewQuality(level: number): void {
setFilterPreviewQuality(level);
}
export function motionBlurLighterLevels(): readonly number[] {
if (!instance || !onFallback || suspended) return [];
return instance.report().movers > 0 ? FILTER_LIGHTER_LEVELS : [];
}
/** True while a blurred frame is between its two captures: the page must hold still. */
export function captureMotionBlurBusy(): boolean {
return instance?.busy() ?? false;
@@ -827,6 +836,7 @@ export function resetCaptureMotionBlurForTests(): void {
suspended = false;
priorResolver = null;
ourResolver = null;
setFilterPreviewQuality(1);
}
/** Test-only: judge the capture tier alone, without the filter fallback taking over. */
+15 -2
View File
@@ -117,6 +117,7 @@ import {
MEDIA_PRESEEK_SECONDS,
type RuntimeMediaClip,
} from "./media";
import { PREVIEW_QUALITY_LEVELS, type PreviewQuality } from "../previewProxyBox";
import {
handleErrorForProxy,
handleMetadataForProxy,
@@ -188,8 +189,10 @@ import { watchSceneWebglContexts } from "./webglContextRecovery";
import {
captureMotionBlurBusy,
initCaptureMotionBlur,
motionBlurLighterLevels,
paintCaptureMotionBlur,
releaseCaptureMotionBlurFrame,
setMotionBlurPreviewQuality,
} from "./captureMotionBlur";
import { TransportClock } from "./clock";
import { WebAudioTransport } from "./webAudioTransport";
@@ -324,6 +327,13 @@ function resolveExportRenderFps(): ExportRenderFpsResolution {
};
}
/** Levels below Full that make the preview lighter: a heavy video's copy, or blur's fewer copies. */
function lighterLevels(): PreviewQuality[] {
const videos = levelsWithLighterCopies();
const blur = motionBlurLighterLevels();
return PREVIEW_QUALITY_LEVELS.filter((level) => videos.includes(level) || blur.includes(level));
}
function compositionFps(): number | null {
const declared = parseFps(findRootCompositionElement()?.getAttribute("data-fps") ?? "");
return declared.ok ? declared.value.num / declared.value.den : null;
@@ -6687,11 +6697,14 @@ export function initSandboxRuntimeModular(): void {
mountedElementCount: document.body.querySelectorAll("*").length,
durationSeconds: clock.getDuration(),
videos: describeVideoSources(),
lighterAt: levelsWithLighterCopies(),
lighterAt: lighterLevels(),
copiesReady: copiesReady(),
},
}),
onSetPreviewQuality: setPreviewQuality,
onSetPreviewQuality: (level) => {
setPreviewQuality(level);
setMotionBlurPreviewQuality(level);
},
onSetCopiesAhead: (on) => setCopiesAhead(on, () => clock.isPlaying()),
onRetryPreviewCopies: retryPreviewCopies,
onSetIdleHeartbeat: (slow) => {