fix(engine): a frame's pixels no longer depend on the frames drawn before it (#7181)

This commit is contained in:
Märten Tropp
2026-11-12 17:52:38 +00:00
committed by GitHub
parent d1a366b42f
commit b4fc4736d7
4 changed files with 143 additions and 2 deletions
+5
View File
@@ -61,6 +61,11 @@ write your own, it must follow the
order, nothing resolves after the frame is committed, and the lifecycle stays
`init` → `seekFrame` (many times) → `destroy`.
With screenshot capture, Chrome redraws each changed raster tile whole, so a frame's
pixels don't depend on what the page drew before it. The worker count, chunk boundaries
and seek order don't change them. [Motion blur](/guides/motion-blur#cost-and-limits) is
the exception.
## Rule out your machine as a variable
Fonts and Chrome versions differ between computers, so a local render can shift
@@ -272,6 +272,22 @@ describe("buildChromeArgs browser GPU mode", () => {
).not.toContain("--disable-gpu-compositing");
});
// HF#7111: partial raster makes a frame's pixels depend on the frames drawn before it.
it.each(["software", "hardware"] as const)(
"disables partial raster for %s screenshot capture",
(browserGpuMode) => {
expect(buildChromeArgs({ ...base, captureMode: "screenshot" }, { browserGpuMode })).toContain(
"--disable-partial-raster",
);
},
);
it("leaves partial raster alone under BeginFrame control", () => {
expect(buildChromeArgs({ ...base, captureMode: "beginframe" })).not.toContain(
"--disable-partial-raster",
);
});
it("uses Metal-backed ANGLE for hardware browser GPU mode on macOS", () => {
const args = buildChromeArgs({ ...base, platform: "darwin" }, { browserGpuMode: "hardware" });
expect(args).toContain("--enable-unsafe-webgpu");
@@ -1856,5 +1872,9 @@ describe.runIf(process.platform === "linux")("BeginFrame launch on a slow first
expect(result.captureMode).toBe("screenshot");
expect(launch).toHaveBeenCalledTimes(3);
// HF#7111: this browser captures by screenshot, though its args were built for BeginFrame.
const fallbackArgs = launch.mock.lastCall?.[0]?.args;
expect(fallbackArgs).toContain("--disable-partial-raster");
expect(fallbackArgs).not.toContain("--enable-begin-frame-control");
});
});
@@ -341,10 +341,12 @@ const BEGINFRAME_ONLY_FLAGS = new Set([
"--enable-surface-synchronization",
]);
function stripBeginFrameFlags(args: string[]): string[] {
function stripBeginFrameFlags(args: readonly string[]): string[] {
return args.filter((a) => !BEGINFRAME_ONLY_FLAGS.has(a));
}
const WHOLE_TILE_RASTER_FLAG = "--disable-partial-raster";
/**
* Probe the complete HeadlessExperimental.beginFrame runtime contract.
*
@@ -979,7 +981,7 @@ async function launchBrowser(
`${result.detail}; falling back to screenshot mode.`,
);
captureMode = "screenshot";
browser = await launch(stripBeginFrameFlags([...fingerprint.args]));
browser = await launch([...stripBeginFrameFlags(fingerprint.args), WHOLE_TILE_RASTER_FLAG]);
}
}
@@ -1234,6 +1236,8 @@ export function buildChromeArgs(options: BuildChromeArgsOptions, config?: GpuCon
"--disable-image-animation-resync",
"--enable-surface-synchronization",
);
} else {
chromeArgs.push(WHOLE_TILE_RASTER_FLAG);
}
if (gpuDisabled) {
@@ -0,0 +1,112 @@
import { spawnSync } from "node:child_process";
import puppeteer, { type Browser, type Page } from "puppeteer-core";
import { afterAll, beforeAll, describe, expect, it } from "vitest";
import { decodePng } from "../utils/alphaBlit.js";
import { buildChromeArgs, resolveHeadlessShellPath } from "./browserManager.js";
import { closeTestChrome } from "./__fixtures__/loopback.js";
import { pageScreenshotCapture } from "./screenshotService.js";
const chromePath = resolveHeadlessShellPath();
const hasBrowser = chromePath !== undefined && spawnSync(chromePath, ["--version"]).status === 0;
const WIDTH = 640;
const HEIGHT = 360;
const FRAMES = 60;
const FPS = 30;
const CAPTURE = { width: WIDTH, height: HEIGHT, fps: { num: FPS, den: 1 }, format: "png" } as const;
// Why screenshot browsers launch with --disable-partial-raster. Partial raster redraws only the
// invalidated part of a tile over its previous contents, and antialiased edges inside that region
// come out slightly different from a whole raster. A frame's pixels then depend on which frames the
// page drew first, so 1 and 3 workers disagree from the second worker's first frame onward, as do
// repeated and backward seeks. A whole tile redraw is a function of the content alone.
//
// HF#7111's scene: rotated boxes beside text whose opacity changes every frame.
const SCENE = `<!doctype html><html><head><meta charset="utf-8"><style>
html,body{margin:0;width:${WIDTH}px;height:${HEIGHT}px;overflow:hidden}
.card{position:absolute;background:#f7f5ef;overflow:hidden}
.card p{position:absolute;inset:0;margin:0;font:700 16px/22px Arial;color:#222;word-break:break-all;text-align:center}
.card span{opacity:0}
</style></head><body>
<div style="position:relative;width:${WIDTH}px;height:${HEIGHT}px;background:#303030;overflow:hidden">
<div class="card" style="left:110px;top:230px;width:200px;height:90px;transform:rotate(4deg)"><p>${"<span>j</span>".repeat(60)}</p></div>
<div class="card" style="left:360px;top:60px;width:200px;height:180px;transform:rotate(-3deg)"><div style="position:absolute;left:8px;top:8px;right:8px;bottom:30px;background:#6e6e6e"></div><p style="top:auto;height:22px;bottom:4px">AAAA</p></div>
</div></body></html>`;
async function captureAt(page: Page, frame: number): Promise<Buffer> {
await page.evaluate((time: number) => {
document.querySelectorAll("span").forEach((span, i) => {
const progress = (time - 0.2 - i * 0.02) / 0.05;
span.style.opacity = String(Math.min(1, Math.max(0, progress)));
});
}, frame / FPS);
const png = await pageScreenshotCapture(page, CAPTURE);
return Buffer.from(decodePng(png).data);
}
/** The frames that differ from the same frame drawn on a page with no history. */
async function framesDifferingFromFresh(
browser: Browser,
shots: ReadonlyMap<number, Buffer>,
): Promise<number[]> {
const differing: number[] = [];
for (const [frame, pixels] of shots) {
const page = await browser.newPage();
await page.setViewport({ width: WIDTH, height: HEIGHT });
await page.setContent(SCENE);
const fresh = await captureAt(page, frame);
await page.close();
if (!fresh.equals(pixels)) differing.push(frame);
}
return differing;
}
// The GPU modes a test machine can launch: Metal exists on every macOS runner, and SwiftShader
// exists everywhere.
const gpuModes =
process.platform === "darwin" ? (["hardware", "software"] as const) : (["software"] as const);
describe.skipIf(!hasBrowser).each(gpuModes)(
"frame independence on %s screenshot capture",
(mode) => {
let browser: Browser | undefined;
beforeAll(async () => {
browser = await puppeteer.launch({
executablePath: chromePath,
headless: true,
args: buildChromeArgs(
{ width: WIDTH, height: HEIGHT, captureMode: "screenshot" },
{ browserGpuMode: mode },
),
});
});
afterAll(async () => {
await closeTestChrome(browser);
});
async function drawnInOrder(order: readonly number[]): Promise<Map<number, Buffer>> {
if (!browser) throw new Error("browser not launched");
const page = await browser.newPage();
await page.setViewport({ width: WIDTH, height: HEIGHT });
await page.setContent(SCENE);
const shots = new Map<number, Buffer>();
for (const frame of order) shots.set(frame, await captureAt(page, frame));
await page.close();
return shots;
}
it("draws each frame of a forward run the same as on a page with no history", async () => {
const order = Array.from({ length: FRAMES }, (_, frame) => frame);
const shots = await drawnInOrder(order);
expect(await framesDifferingFromFresh(browser as Browser, shots)).toEqual([]);
}, 120_000);
it("draws a frame reached backward the same as on a page with no history", async () => {
const order = Array.from({ length: FRAMES }, (_, i) => FRAMES - 1 - i);
const shots = await drawnInOrder(order);
expect(await framesDifferingFromFresh(browser as Browser, shots)).toEqual([]);
}, 120_000);
},
);