fix(engine): drawElement falls back on gpu-less linux and beginframe launches instead of hanging self-verify (#7324)

* fix(engine): a gpu-less linux host falls back from drawElement instead of hanging self-verify

On a GPU-less Linux headless shell asked for browserGpuMode "hardware", Chrome has
GPU args and no GPU, so getContext("webgl") returns null. detectGpuBackend read that
as { isSwiftShader: false }, the SwiftShader gate let drawElement engage on a
BeginFrame-launched browser, and self-verify on its truth page then stalled until
the render failed after about 300 s, with no fallback.

drawElementGate now decides the init-time fallback, each with a named deGateReason:

- swiftshader: any software GL (SwiftShader, llvmpipe, lavapipe, softpipe, Microsoft
  Basic Render Driver), from one shared token list. Detection on real GPUs is unchanged.
- webgl_unavailable: no WebGL context could be created (null, or getContext throws).
- beginframe_no_self_verify: the browser was launched for BeginFrame. Its self-verify
  truth page has no BeginFrame driver, so drawElement frames could not be checked, and
  a Linux host with a GPU would stall the same way. HF_FORCE_DRAWELEMENT bypasses only
  this gate.

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

* test(producer): windowed frames runs drawElement through self-verify and a recycle

Adds a drawElement case to the windowed-frames integration test: drawElement capture,
self-verify through the on-demand hook, and a browser recycle. It covers that hook
only on a macOS or Windows host with a GPU. Linux always gates drawElement away
(headless-shell launches for BeginFrame, which has no self-verify), and so does any
host with no GPU; there the case asserts the named gate fallback (swiftshader,
webgl_unavailable or beginframe_no_self_verify) and prints that drawElement did not
run. HF_TEST_REQUIRE_DRAWELEMENT=1 turns that fallback into a failure, for the hosts
that are meant to run it.

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-06 08:59:04 -08:00
committed by GitHub
co-authored by Claude Opus 5.5
parent 318724f5f4
commit 18fc75dcd7
8 changed files with 376 additions and 59 deletions
+11 -9
View File
@@ -65,17 +65,19 @@ interface WebGlProbeInfo {
renderer: string;
}
export const SOFTWARE_WEBGL_RENDERER_TOKENS: readonly string[] = [
"swiftshader",
"llvmpipe",
"lavapipe",
"softpipe",
"mesa offscreen",
"microsoft basic render driver",
"software rasterizer",
];
function isSoftwareWebGlRenderer(rendererInfo: string): boolean {
const renderer = rendererInfo.trim().toLowerCase();
return (
renderer.includes("swiftshader") ||
renderer.includes("llvmpipe") ||
renderer.includes("lavapipe") ||
renderer.includes("softpipe") ||
renderer.includes("mesa offscreen") ||
renderer.includes("microsoft basic render driver") ||
renderer.includes("software rasterizer")
);
return SOFTWARE_WEBGL_RENDERER_TOKENS.some((token) => renderer.includes(token));
}
async function getPuppeteer(): Promise<PuppeteerNode> {
@@ -1,11 +1,13 @@
import { describe, expect, it, vi } from "vitest";
import { afterEach, describe, expect, it, vi } from "vitest";
import type { Page } from "puppeteer-core";
import {
classifyGpuRenderer,
detectGpuBackend,
detectSwiftShader,
drawElementGate,
resolveDrawElementCaptureMode,
} from "./drawElementService.js";
import { SOFTWARE_WEBGL_RENDERER_TOKENS } from "./browserManager.js";
// ── detectGpuBackend / detectSwiftShader ───────────────────────────────────────
@@ -19,19 +21,16 @@ describe("detectGpuBackend", () => {
it("carries the raw renderer string alongside the SwiftShader verdict", async () => {
const page = makePage({
isSwiftShader: false,
webglAvailable: true,
renderer: "ANGLE (NVIDIA, D3D11 vs_5_0 ps_5_0, D3D11)",
});
expect(await detectGpuBackend(page)).toEqual({
isSwiftShader: false,
webglAvailable: true,
renderer: "ANGLE (NVIDIA, D3D11 vs_5_0 ps_5_0, D3D11)",
});
});
it("reports null renderer when WebGL is unavailable", async () => {
const page = makePage({ isSwiftShader: false, renderer: null });
expect(await detectGpuBackend(page)).toEqual({ isSwiftShader: false, renderer: null });
});
it("detectSwiftShader wrapper returns true when renderer is SwiftShader", async () => {
const page = makePage({ isSwiftShader: true, renderer: "Google SwiftShader" });
expect(await detectSwiftShader(page)).toBe(true);
@@ -43,9 +42,88 @@ describe("detectGpuBackend", () => {
});
it("passes a function to page.evaluate", async () => {
const page = makePage({ isSwiftShader: false, renderer: null });
const page = makePage({ isSwiftShader: false, webglAvailable: false, renderer: null });
await detectGpuBackend(page);
expect(page.evaluate).toHaveBeenCalledWith(expect.any(Function));
expect(page.evaluate).toHaveBeenCalledWith(
expect.any(Function),
SOFTWARE_WEBGL_RENDERER_TOKENS,
);
});
});
// ── detectGpuBackend: the in-page probe itself ────────────────────────────────
// The mocks above hand back a canned verdict, so none of them exercise the probe that
// produces it. These run the real in-page function against a stand-in `document`.
describe("detectGpuBackend in-page probe", () => {
afterEach(() => vi.unstubAllGlobals());
/** A page whose evaluate runs the probe against a fake canvas. */
function pageWithCanvas(getContext: (type: string) => unknown): Page {
vi.stubGlobal("document", { createElement: () => ({ getContext }) });
return {
evaluate: async (fn: (...args: unknown[]) => unknown, ...args: unknown[]) => fn(...args),
} as unknown as Page;
}
/** The gate for a screenshot launch, where only the backend can close it. */
const gateFor = (backend: Awaited<ReturnType<typeof detectGpuBackend>>) =>
drawElementGate({ backend, launchCaptureMode: "screenshot", forceDE: false });
const glWithRenderer = (renderer: string) => ({
getExtension: () => ({ UNMASKED_RENDERER_WEBGL: 0x9246 }),
getParameter: () => renderer,
});
it("reads a host with no WebGL context as unavailable, not as a real GPU", async () => {
const backend = await detectGpuBackend(pageWithCanvas(() => null));
expect(backend).toEqual({ isSwiftShader: false, webglAvailable: false, renderer: null });
expect(gateFor(backend)).toBe("webgl_unavailable");
});
it("reads a getContext that throws as unavailable too", async () => {
const backend = await detectGpuBackend(
pageWithCanvas(() => {
throw new Error("GPU process crashed");
}),
);
expect(backend.webglAvailable).toBe(false);
expect(gateFor(backend)).toBe("webgl_unavailable");
});
it("leaves a real GPU unchanged: WebGL available, not software, gate open", async () => {
const renderer = "ANGLE (Apple, ANGLE Metal Renderer: Apple M4 Pro, Unspecified Version)";
const backend = await detectGpuBackend(pageWithCanvas(() => glWithRenderer(renderer)));
expect(backend).toEqual({ isSwiftShader: false, webglAvailable: true, renderer });
expect(gateFor(backend)).toBeNull();
});
it("leaves real SwiftShader unchanged: software, gated as swiftshader", async () => {
const renderer =
"ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (Subzero)), SwiftShader driver)";
const backend = await detectGpuBackend(pageWithCanvas(() => glWithRenderer(renderer)));
expect(backend).toEqual({ isSwiftShader: true, webglAvailable: true, renderer });
expect(gateFor(backend)).toBe("swiftshader");
});
it.each([
["llvmpipe", "ANGLE (Mesa, llvmpipe (LLVM 15.0.7, 256 bits), OpenGL 4.5)"],
[
"Microsoft Basic Render Driver",
"ANGLE (Microsoft, Microsoft Basic Render Driver Direct3D11 vs_5_0 ps_5_0)",
],
])("reads %s as software GL, gated like SwiftShader", async (_name, renderer) => {
const backend = await detectGpuBackend(pageWithCanvas(() => glWithRenderer(renderer)));
expect(backend).toEqual({ isSwiftShader: true, webglAvailable: true, renderer });
expect(gateFor(backend)).toBe("swiftshader");
});
it("keeps a context whose renderer string is hidden as available (a real GL context)", async () => {
const backend = await detectGpuBackend(
pageWithCanvas(() => ({ getExtension: () => null, getParameter: () => "" })),
);
expect(backend).toEqual({ isSwiftShader: false, webglAvailable: true, renderer: null });
expect(gateFor(backend)).toBeNull();
});
});
@@ -85,6 +163,45 @@ describe("classifyGpuRenderer", () => {
});
});
// ── drawElementGate ────────────────────────────────────────────────────────────
describe("drawElementGate", () => {
const gpu = { isSwiftShader: false, webglAvailable: true };
it("gates an opaque drawElement session launched for BeginFrame, even with a GPU backend", () => {
expect(drawElementGate({ backend: gpu, launchCaptureMode: "beginframe", forceDE: false })).toBe(
"beginframe_no_self_verify",
);
});
it("lets a screenshot launch with a GPU backend engage", () => {
expect(
drawElementGate({ backend: gpu, launchCaptureMode: "screenshot", forceDE: false }),
).toBeNull();
});
it("names the backend before the launch mode, so a GPU-less BeginFrame host reads as webgl_unavailable", () => {
const none = { isSwiftShader: false, webglAvailable: false };
expect(
drawElementGate({ backend: none, launchCaptureMode: "beginframe", forceDE: false }),
).toBe("webgl_unavailable");
const soft = { isSwiftShader: true, webglAvailable: true };
expect(
drawElementGate({ backend: soft, launchCaptureMode: "beginframe", forceDE: false }),
).toBe("swiftshader");
});
it("lets HF_FORCE_DRAWELEMENT past the launch gate only, for R&D", () => {
expect(
drawElementGate({ backend: gpu, launchCaptureMode: "beginframe", forceDE: true }),
).toBeNull();
const soft = { isSwiftShader: true, webglAvailable: true };
expect(drawElementGate({ backend: soft, launchCaptureMode: "beginframe", forceDE: true })).toBe(
"swiftshader",
);
});
});
// ── resolveDrawElementCaptureMode ──────────────────────────────────────────────
describe("resolveDrawElementCaptureMode", () => {
@@ -15,6 +15,8 @@
*/
import type { Page } from "puppeteer-core";
import { SOFTWARE_WEBGL_RENDERER_TOKENS } from "./browserManager.js";
import type { CaptureMode } from "./browserLeasePool.js";
/**
* Discriminant prefix embedded in every "capture canvas isn't set up yet"
@@ -56,24 +58,45 @@ export const DE_CANVAS_NOT_INITIALIZED_CODE = "HF_DE_CANVAS_NOT_INITIALIZED";
* destination additionally drops promoted sub-layers (Chromium bug
* 521434899). The speedup is real only on a hardware GPU (macOS 1.6×), so
* SwiftShader always routes to the platform baseline.
*
* The former <video> gate (a proxy for the word-by-word caption opacity pattern)
* was removed once Chrome 151 fixed crbug 521861819: video + nested-fade comps now
* render correctly on the drawElement path (verified PSNR=inf vs baseline). 151 is
* the pinned floor. See docs/fast-capture-limitations.md Lim 2.
* - No WebGL at all (a GPU-less host asked for hardware GL) is software at best: `webgl_unavailable`.
* - A BeginFrame launch (Linux headless-shell): the self-verify truth page has no BeginFrame
* driver, so drawElement is gated as `beginframe_no_self_verify`.
*/
export function resolveDrawElementCaptureMode(
isSwiftShader: boolean,
softwareBackend: boolean,
transparent: boolean,
): "drawelement" | "screenshot" {
// `transparent` is retained for call-site clarity; SwiftShader blocks
// `transparent` is retained for call-site clarity; a software backend blocks
// unconditionally now (no GPU egress to skip — parity at best), which
// subsumes the former transparent-only SwiftShader case.
void transparent;
if (isSwiftShader) return "screenshot";
if (softwareBackend) return "screenshot";
return "drawelement";
}
export type DrawElementGateReason =
| "swiftshader"
| "webgl_unavailable"
| "beginframe_no_self_verify";
/**
* The init-time gate that routes drawElement to the baseline capture, or null when it may engage.
* `swiftshader` covers any software GL; `webgl_unavailable` is a host with no WebGL at all.
* `beginframe_no_self_verify` is a BeginFrame launch, which cannot take the self-verify ground truth.
* `forceDE` (HF_FORCE_DRAWELEMENT) bypasses only the launch gate. Pure; exported for tests.
*/
export function drawElementGate(args: {
backend: Pick<GpuBackendInfo, "isSwiftShader" | "webglAvailable">;
launchCaptureMode: CaptureMode;
forceDE: boolean;
}): DrawElementGateReason | null {
const { backend, launchCaptureMode, forceDE } = args;
if (backend.isSwiftShader) return "swiftshader";
if (!backend.webglAvailable) return "webgl_unavailable";
if (launchCaptureMode === "beginframe" && !forceDE) return "beginframe_no_self_verify";
return null;
}
/**
* Instrument `HTMLCanvasElement.getContext` before any page script runs.
*
@@ -147,8 +170,10 @@ export function forcePreservedDrawingBuffer(): void {
}
export interface GpuBackendInfo {
/** SwiftShader (software rasterizer) — e.g. Docker headless-shell. */
/** Software GL (SwiftShader, llvmpipe, ...) — e.g. Docker headless-shell. Named for the common case. */
isSwiftShader: boolean;
/** False when no WebGL context could be created (null or threw): not a real GPU. */
webglAvailable: boolean;
/**
* Raw UNMASKED_RENDERER_WEBGL string (e.g. "ANGLE (Apple, ANGLE Metal
* Renderer: Apple M4 Pro, ...)", "ANGLE (NVIDIA, GeForce RTX 3080 Direct3D11
@@ -207,22 +232,32 @@ export function classifyGpuRenderer(renderer: string | null | undefined): string
* Detect the page's WebGL backend: SwiftShader vs a real GPU, plus the raw
* renderer string for telemetry.
*
* `isSwiftShader` is true inside Docker headless-shell with
* --use-angle=swiftshader. Call once after window.__hf is ready; cache the
* `isSwiftShader` is true for any software GL, e.g. Docker headless-shell with
* --use-angle=swiftshader; `webglAvailable` is false with no WebGL at all. Call once after window.__hf is ready; cache the
* result on the session.
*/
export async function detectGpuBackend(page: Page): Promise<GpuBackendInfo> {
return page.evaluate((): GpuBackendInfo => {
return page.evaluate((softwareTokens: readonly string[]): GpuBackendInfo => {
const canvas = document.createElement("canvas");
const gl =
canvas.getContext("webgl") ||
(canvas.getContext("experimental-webgl") as WebGLRenderingContext | null);
if (!gl) return { isSwiftShader: false, renderer: null };
let gl: WebGLRenderingContext | null = null;
try {
gl =
canvas.getContext("webgl") ||
(canvas.getContext("experimental-webgl") as WebGLRenderingContext | null);
} catch {
gl = null;
}
if (!gl) return { isSwiftShader: false, webglAvailable: false, renderer: null };
const ext = gl.getExtension("WEBGL_debug_renderer_info");
if (!ext) return { isSwiftShader: false, renderer: null };
if (!ext) return { isSwiftShader: false, webglAvailable: true, renderer: null };
const renderer = gl.getParameter(ext.UNMASKED_RENDERER_WEBGL) as string;
return { isSwiftShader: renderer.toLowerCase().includes("swiftshader"), renderer };
});
const lower = renderer.toLowerCase();
return {
isSwiftShader: softwareTokens.some((token) => lower.includes(token)),
webglAvailable: true,
renderer,
};
}, SOFTWARE_WEBGL_RENDERER_TOKENS);
}
/**
+23 -7
View File
@@ -85,9 +85,10 @@ import {
import {
classifyGpuRenderer,
detectGpuBackend,
drawElementGate,
type DrawElementGateReason,
injectDrawElementCanvas,
captureDrawElementFrame,
resolveDrawElementCaptureMode,
forcePreservedDrawingBuffer,
instrumentAcceleratedCanvases,
initDrawElementWorkerEncode,
@@ -974,6 +975,18 @@ async function waitForCloseWithTimeout(promise: Promise<unknown>): Promise<boole
return !timedOut;
}
const DE_GATE_MESSAGES: Record<DrawElementGateReason, string> = {
swiftshader:
"SwiftShader (software rasterizer, no GPU egress to skip, drawElement is " +
"parity-or-slower; see fast-capture-limitations.md)",
webgl_unavailable:
"WebGL is unavailable (no GPU behind this browser, so it rasterizes in software and " +
"drawElement has no GPU egress to skip)",
beginframe_no_self_verify:
"this browser was launched for BeginFrame capture, whose self-verify truth page has no " +
"BeginFrame driver, so drawElement frames could not be checked",
};
/**
* Post-readiness capture-surface init, shared by the screenshot and BeginFrame
* init paths (called after the page is fully ready). When `useDrawElement` is
@@ -1128,18 +1141,21 @@ async function initDrawElementOrTransparentBackground(
// Both reproduced on Chrome <=150 (video+caption-fade ~12 dB; stacked fade
// 24.5 dB) and both render correctly on 151 (verified: video+nested-fade repro
// PSNR=inf; efb59c5b 24.5→47.4 dB, 0 damaged frames). 151 is the pinned floor.
const mode = resolveDrawElementCaptureMode(session.isSwiftShader, transparent);
if (mode === "screenshot") {
session.deGateReason = "swiftshader";
session.deFallbackTrigger = "swiftshader";
const gateReason = drawElementGate({
backend: gpuBackend,
launchCaptureMode: session.launchCaptureMode,
forceDE,
});
if (gateReason !== null) {
session.deGateReason = gateReason;
session.deFallbackTrigger = gateReason;
// Fall back to the browser's LAUNCH mode, not unconditionally to
// "screenshot": on a BeginFrame-launched browser (Linux fast capture)
// Page.captureScreenshot hangs for the full protocol timeout, while
// beginFrameCapture is the platform's normal baseline path.
console.error(
`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
"SwiftShader (software rasterizer, no GPU egress to skip, drawElement is " +
"parity-or-slower; see fast-capture-limitations.md)",
DE_GATE_MESSAGES[gateReason],
);
await routeToFallback();
} else {
+3 -3
View File
@@ -414,9 +414,9 @@ export interface CapturePerfSummary {
chromeMemorySamples?: number;
/**
* Low-cardinality init-time gate that routed a drawElement-eligible session
* to the baseline: `swiftshader` | `css_effect:<fx>` | `at_risk_timeline` |
* `3d_init_failed` | `supersampling` | `render_mode_hint`. Undefined when
* drawElement ran or was never attempted.
* to the baseline: `swiftshader` | `webgl_unavailable` | `beginframe_no_self_verify` |
* `css_effect:<fx>` | `at_risk_timeline` | `3d_init_failed` | `supersampling` |
* `render_mode_hint`. Undefined when drawElement ran or was never attempted.
*/
deGateReason?: string;
motionBlur?: PageMotionBlurSummary;
@@ -304,7 +304,7 @@ const ALLOWED_STRING_DATA_KEYS = new Set([
"stagePhase",
// Full-fidelity fast-capture fallback trigger — the specific reason
// drawElement gated off ("filter:blur", "filter:drop-shadow",
// "backdrop-filter", "clip-path", "at_risk_timeline", "swiftshader", …).
// "backdrop-filter", "clip-path", "at_risk_timeline", "swiftshader", "webgl_unavailable", …).
// Populated on the `capture_fallback_profile` checkpoint emitted by
// `fallbackCaptureProfile.ts` when the operator opts into
// `HF_PROFILE_FALLBACK_CAPTURE=true` so downstream metric consumers can
@@ -1,9 +1,15 @@
// Windowed source-video frames (HF_VIDEO_FRAME_WINDOW), rendered for real: each case renders twice
// on the segmented route, once reading a segment's frames at a time and once extracting whole
// videos, and the two outputs must match frame for frame. Needs Chrome + ffmpeg: integration lane.
// Known gap: this test pins `browserGpuMode: "software"`, so every render here takes the screenshot
// path. Windowed drawElement output parity was measured by hand on real footage and has no automated
// guard.
// Every case but one pins `browserGpuMode: "software"`, which takes the screenshot path. The
// drawElement case asks for `browserGpuMode: "hardware"` and `useDrawElement`, the only way to get
// past the engine's software-rasterizer gate without HF_FORCE_DRAWELEMENT (which skips self-verify),
// so it guards drawElement capture, self-verify through the on-demand hook, and a browser recycle.
// The drawElement branch runs only on a macOS or Windows host with a GPU. Linux always gates it away,
// with or without a GPU, because headless-shell launches for BeginFrame, which has no self-verify;
// there, and on any host with no GPU, the case asserts the named fallback and says in its output that
// drawElement did not run. HF_TEST_REQUIRE_DRAWELEMENT=1 turns that fallback into a failure, for the
// hosts that are meant to run it.
//
// HF_TEST_RETRY_BROWSER_STALL=1 renders once more after Chrome dies, for an overloaded local host.
// Never set it in CI: a windowed render that needs the retry alone fails the case.
@@ -66,6 +72,19 @@ interface Case {
calibrates?: boolean;
/** Caps the worker count the orchestrator picks, to keep the Chromes it opens few. */
maxWorkers?: number;
/** Captures with drawElement and its self-verify, which software rasterization would route away from. */
drawElement?: boolean;
/** Recycles a worker's browser after this many segments. */
recycleEverySegments?: number;
/** Keeps the windowed render's work dir to read `segment-frames` once it closes, and polls it meanwhile. */
inspectsFolder?: boolean;
}
interface DrawElementFacts {
mode: string | undefined;
verifyArmed: number | undefined;
selfVerifyFallback: boolean | undefined;
gateReason: string | undefined;
}
interface Run {
@@ -79,10 +98,15 @@ interface Run {
peakBytes: number | undefined;
extractedFrames: number | undefined;
calibration: string;
drawElement: DrawElementFacts;
/** Cadence-driven browser restarts the segmented capture reported. */
browserRecycles: number | undefined;
/** Windowed renders only: what a poll of `segment-frames` saw while the render ran. */
sampled: { peakBytes: number; largestFileBytes: number };
/** `keepWorkDir` renders only: the entries left in `segment-frames` once the render closed. */
leftInSegmentFrames: string[] | undefined;
/** `keepWorkDir` renders only: the `on-demand_*` folders a poll saw while they held a frame. */
onDemandWithFrames: number;
}
let root: string;
@@ -193,15 +217,23 @@ function firstDifference(left: string[], right: string[]): number {
const ENV_KEYS = [
"HF_SEGMENTED_CAPTURE",
"HF_SEGMENT_FRAMES",
"HF_SEGMENT_BROWSER_RECYCLE",
"HF_VIDEO_FRAME_WINDOW",
"KEEP_TEMP",
] as const;
/** Sets the render's env and returns the call that puts the caller's back. */
function setRenderEnv(windowed: boolean, keepWorkDir: boolean | undefined): () => void {
function setRenderEnv(
windowed: boolean,
keepWorkDir: boolean | undefined,
recycleEverySegments: number | undefined,
): () => void {
const saved = Object.fromEntries(ENV_KEYS.map((key) => [key, process.env[key]]));
process.env.HF_SEGMENTED_CAPTURE = "true";
process.env.HF_SEGMENT_FRAMES = String(SEGMENT_FRAMES);
if (recycleEverySegments !== undefined) {
process.env.HF_SEGMENT_BROWSER_RECYCLE = String(recycleEverySegments);
}
if (windowed) process.env.HF_VIDEO_FRAME_WINDOW = "true";
else delete process.env.HF_VIDEO_FRAME_WINDOW;
if (keepWorkDir) process.env.KEEP_TEMP = "1";
@@ -240,6 +272,29 @@ function watchWorkDirs(output: string, jobId: string) {
return { own };
}
/**
* Counts the `on-demand_*` folders seen holding a frame, by name. An extraction of one frame lasts
* about as long as an ffmpeg spawn, so this polls much faster than {@link sampleSegmentFrames}.
*/
function watchOnDemandFolders(own: () => string[]) {
const withFrames = new Set<string>();
const poll = setInterval(() => {
for (const workDir of own()) {
const folder = join(workDir, "segment-frames");
let names: string[];
try {
names = readdirSync(folder).filter((name) => name.startsWith("on-demand_"));
} catch {
continue;
}
for (const name of names) {
if (directoryBytes(join(folder, name), () => {}) > 0) withFrames.add(name);
}
}
}, 5);
return { withFrames, stop: () => clearInterval(poll) };
}
/** Polls `segment-frames` in the render's work dir for the most it holds at once. */
function sampleSegmentFrames(own: () => string[]) {
const sampled = { peakBytes: 0, largestFileBytes: 0 };
@@ -260,6 +315,7 @@ function describeRun(
job: RenderJob,
output: string,
trace: Array<Record<string, unknown>>,
seen: { browserRecycles: number | undefined },
): Omit<Run, "sampled" | "leftInSegmentFrames"> {
const perf = job.perfSummary;
const capture = perf?.observability?.capture;
@@ -281,6 +337,13 @@ function describeRun(
peakBytes: capture?.videoFrameWindowPeakBytes,
extractedFrames: perf?.observability?.extraction?.totalFramesExtracted,
calibration: String(calibration?.message ?? "not reached"),
drawElement: {
mode: perf?.drawElement?.mode,
verifyArmed: perf?.drawElement?.verifyArmed,
selfVerifyFallback: perf?.drawElement?.selfVerifyFallback,
gateReason: perf?.drawElement?.gateReason,
},
browserRecycles: seen.browserRecycles,
};
}
@@ -309,7 +372,11 @@ async function render(
}
}
function createJob(testCase: Case, trace: Array<Record<string, unknown>>): RenderJob {
function createJob(
testCase: Case,
trace: Array<Record<string, unknown>>,
seen: { browserRecycles: number | undefined },
): RenderJob {
return createRenderJob({
fps: testCase.fps,
quality: "draft",
@@ -320,13 +387,19 @@ function createJob(testCase: Case, trace: Array<Record<string, unknown>>): Rende
logger: {
info(message: string, meta?: Record<string, unknown>) {
if (message === "[Render:trace]" && meta) trace.push(meta);
if (message.startsWith("[Render] Segmented capture complete") && meta) {
seen.browserRecycles = Number(meta.browserRecycles);
}
},
warn() {},
error() {},
debug() {},
},
producerConfig: resolveConfig({
browserGpuMode: "software",
// "hardware" is what keeps drawElement from being routed to screenshot capture as software
// rasterization; the engine still runs every gate and the self-verify on the render.
browserGpuMode: testCase.drawElement ? "hardware" : "software",
useDrawElement: testCase.drawElement ? true : undefined,
concurrency: testCase.maxWorkers ?? "auto",
}),
});
@@ -345,11 +418,13 @@ async function renderOnce(testCase: Case, windowed: boolean, options: RenderOpti
const label = `${testCase.name.replace(/\W+/g, "-")}-${windowed ? "windowed" : "full"}`;
writeFileSync(join(root, "index.html"), composition(testCase));
const trace: Array<Record<string, unknown>> = [];
const job = createJob(testCase, trace);
const restoreEnv = setRenderEnv(windowed, options.keepWorkDir);
const seen = { browserRecycles: undefined as number | undefined };
const job = createJob(testCase, trace, seen);
const restoreEnv = setRenderEnv(windowed, options.keepWorkDir, testCase.recycleEverySegments);
const output = join(root, `${label}.mp4`);
const { own } = watchWorkDirs(output, job.id);
const sampler = options.sampleFolder ? sampleSegmentFrames(own) : NO_SAMPLER;
const onDemand = options.sampleFolder ? watchOnDemandFolders(own) : null;
const kept: string[] = [];
try {
await executeRenderJob(job, root, output).catch((error: unknown) => {
@@ -357,12 +432,14 @@ async function renderOnce(testCase: Case, windowed: boolean, options: RenderOpti
});
if (options.keepWorkDir) kept.push(...own());
return {
...describeRun(job, output, trace),
...describeRun(job, output, trace, seen),
sampled: sampler.sampled,
leftInSegmentFrames: leftInSegmentFrames(kept),
onDemandWithFrames: onDemand?.withFrames.size ?? 0,
};
} finally {
sampler.stop();
onDemand?.stop();
restoreEnv();
for (const workDir of kept) rmSync(workDir, { recursive: true, force: true });
}
@@ -376,9 +453,10 @@ function renderPair(testCase: Case): Promise<{ windowed: Run; full: Run }> {
if (!pair) {
pair = (async () => {
const full = await render(testCase, false);
const inspects = testCase.name === PEAK_CASE || testCase.inspectsFolder === true;
const windowed = await render(testCase, true, {
keepWorkDir: testCase.name === PEAK_CASE,
sampleFolder: testCase.name === PEAK_CASE,
keepWorkDir: inspects,
sampleFolder: inspects,
});
if (windowed.retried && !full.retried) {
throw new Error(`${testCase.name}: only the windowed render needed a retry`);
@@ -397,6 +475,9 @@ function renderPair(testCase: Case): Promise<{ windowed: Run; full: Run }> {
}
const PEAK_CASE = "2 workers";
const DRAW_ELEMENT_CASE = "drawElement capture with a browser recycle";
/** The engine's `deGateReason`s for a host that cannot run drawElement: software or no WebGL, or a BeginFrame launch. */
const HOST_GATES = new Set(["swiftshader", "webgl_unavailable", "beginframe_no_self_verify"]);
// Four segments for two workers, so the window has something to hold back.
const PEAK_SECONDS = 8;
const CFR = "assets/cfr.mp4";
@@ -475,6 +556,16 @@ function cases(): Case[] {
seconds: PEAK_SECONDS,
clips: [{ id: "clip", src: "assets/long.mp4", start: 0, duration: PEAK_SECONDS }],
},
{
...base,
name: DRAW_ELEMENT_CASE,
drawElement: true,
recycleEverySegments: 1,
inspectsFolder: true,
// Two segments, so the one recycle falls between them.
seconds: 4,
clips: [{ id: "clip", src: CFR, start: 0, duration: 4 }],
},
{
...base,
name: "motion blur, which declines the window",
@@ -546,6 +637,62 @@ describe.skipIf(!HAS_FFMPEG)("windowed source-video frames — real render", ()
}, 600_000);
}
it("captures with drawElement where the host can run it, and names its gate where it cannot", async () => {
const testCase = cases().find((candidate) => candidate.name === DRAW_ELEMENT_CASE)!;
const { windowed, full } = await renderPair(testCase);
// `gateReason` is a `|`-joined set across the render's sessions.
const gates = [windowed, full].map((run) => run.drawElement.gateReason ?? "");
const gated = gates.every(
(gate) => gate !== "" && gate.split("|").every((r) => HOST_GATES.has(r)),
);
if (gated) {
if (process.env.HF_TEST_REQUIRE_DRAWELEMENT === "1") {
throw new Error(
`HF_TEST_REQUIRE_DRAWELEMENT=1 but drawElement was gated away (${gates.join(", ")}): ` +
"this host cannot run it (no GPU, or a BeginFrame launch)",
);
}
for (const run of [windowed, full]) {
const { drawElement } = run;
// Falling back is the contract here: the render completed, on the baseline capture, with no
// self-verify armed and none to fail.
expect(drawElement.mode).not.toContain("drawelement");
expect(drawElement.verifyArmed ?? 0).toBe(0);
expect(drawElement.selfVerifyFallback ?? false).toBe(false);
}
expect(windowed.videoFrameWindow).toBe("on");
expect(windowed.leftInSegmentFrames).toEqual([]);
console.warn(
`[windowedFrames] ${DRAW_ELEMENT_CASE}: drawElement did NOT run on this host (gate ${gates.join(", ")}): ` +
"no GPU, or a BeginFrame launch. Only the fallback was asserted; drawElement capture, self-verify " +
"and the on-demand hook are unexercised here. Run on a macOS or Windows host with a GPU to cover them.",
);
return;
}
for (const run of [windowed, full]) {
const { drawElement } = run;
// A fall back to screenshot capture, or past the capability or software gates, reads here.
expect(`${drawElement.mode} gate=${drawElement.gateReason}`).toBe(
"drawelement gate=undefined",
);
// Armed samples read off a video comp mean the ground truth had real frames, not black boxes.
expect(drawElement.verifyArmed ?? 0).toBeGreaterThan(0);
expect(drawElement.selfVerifyFallback).toBe(false);
}
expect(windowed.videoFrameWindow).toBe("on");
expect(windowed.browserRecycles ?? 0).toBeGreaterThanOrEqual(1);
// The ground truth went through the on-demand hook: a hook that injected nothing leaves no folder to see.
expect(windowed.onDemandWithFrames).toBeGreaterThan(0);
// The folder exists once the render closes and holds neither an `on-demand_*` leftover nor anything else.
expect(windowed.leftInSegmentFrames).toEqual([]);
console.log(
`[windowedFrames] ${DRAW_ELEMENT_CASE}: ${JSON.stringify(windowed.drawElement)}; ` +
`recycles=${windowed.browserRecycles}; onDemandWithFrames=${windowed.onDemandWithFrames}; left=${JSON.stringify(windowed.leftInSegmentFrames)}`,
);
}, 600_000);
it("never holds more than workers x segment frames of source frames", async () => {
const testCase = cases().find((candidate) => candidate.name === PEAK_CASE)!;
const { windowed } = await renderPair(testCase);
@@ -674,7 +674,7 @@ export interface RenderPerfSummary {
parallelRouter?: string;
/** Worker count the auto-resolution chose BEFORE the router pinned it to 3 — the single-worker-inversion counterfactual. Only set when the router fired. */
preRouterWorkers?: number;
/** Engine init-time gate: swiftshader | css_effect:* | at_risk_timeline | 3d_init_failed | supersampling | render_mode_hint. */
/** Engine init-time gate: swiftshader | webgl_unavailable | beginframe_no_self_verify | css_effect:* | at_risk_timeline | 3d_init_failed | supersampling | render_mode_hint. */
gateReason?: string;
/** Low-cardinality GPU bucket from DE session init (`<backend>/<vendor>`, e.g. `d3d11/nvidia`); |-joined across parallel sessions (bounded: one bucket per distinct backend on the host). */
gpuRenderer?: string;