mirror of
https://github.com/heygen-com/hyperframes.git
synced 2026-11-18 07:50:13 +00:00
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:
co-authored by
Claude Opus 5.5
parent
318724f5f4
commit
18fc75dcd7
@@ -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);
|
||||
}
|
||||
|
||||
/**
|
||||
|
||||
@@ -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 {
|
||||
|
||||
@@ -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;
|
||||
|
||||
Reference in New Issue
Block a user