Skip to content

Commit 18fc75d

Browse files
vanceingallsclaude
andauthored
fix(engine): drawElement falls back on gpu-less linux and beginframe launches instead of hanging self-verify (heygen-com#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 <[email protected]> * 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 <[email protected]> --------- Co-authored-by: Claude Opus 5.5 <[email protected]>
1 parent 318724f commit 18fc75d

8 files changed

Lines changed: 376 additions & 59 deletions

File tree

‎packages/engine/src/services/browserManager.ts‎

Lines changed: 11 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -65,17 +65,19 @@ interface WebGlProbeInfo {
6565
renderer: string;
6666
}
6767

68+
export const SOFTWARE_WEBGL_RENDERER_TOKENS: readonly string[] = [
69+
"swiftshader",
70+
"llvmpipe",
71+
"lavapipe",
72+
"softpipe",
73+
"mesa offscreen",
74+
"microsoft basic render driver",
75+
"software rasterizer",
76+
];
77+
6878
function isSoftwareWebGlRenderer(rendererInfo: string): boolean {
6979
const renderer = rendererInfo.trim().toLowerCase();
70-
return (
71-
renderer.includes("swiftshader") ||
72-
renderer.includes("llvmpipe") ||
73-
renderer.includes("lavapipe") ||
74-
renderer.includes("softpipe") ||
75-
renderer.includes("mesa offscreen") ||
76-
renderer.includes("microsoft basic render driver") ||
77-
renderer.includes("software rasterizer")
78-
);
80+
return SOFTWARE_WEBGL_RENDERER_TOKENS.some((token) => renderer.includes(token));
7981
}
8082

8183
async function getPuppeteer(): Promise<PuppeteerNode> {

‎packages/engine/src/services/drawElementService.test.ts‎

Lines changed: 125 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,13 @@
1-
import { describe, expect, it, vi } from "vitest";
1+
import { afterEach, describe, expect, it, vi } from "vitest";
22
import type { Page } from "puppeteer-core";
33
import {
44
classifyGpuRenderer,
55
detectGpuBackend,
66
detectSwiftShader,
7+
drawElementGate,
78
resolveDrawElementCaptureMode,
89
} from "./drawElementService.js";
10+
import { SOFTWARE_WEBGL_RENDERER_TOKENS } from "./browserManager.js";
911

1012
// ── detectGpuBackend / detectSwiftShader ───────────────────────────────────────
1113

@@ -19,19 +21,16 @@ describe("detectGpuBackend", () => {
1921
it("carries the raw renderer string alongside the SwiftShader verdict", async () => {
2022
const page = makePage({
2123
isSwiftShader: false,
24+
webglAvailable: true,
2225
renderer: "ANGLE (NVIDIA, D3D11 vs_5_0 ps_5_0, D3D11)",
2326
});
2427
expect(await detectGpuBackend(page)).toEqual({
2528
isSwiftShader: false,
29+
webglAvailable: true,
2630
renderer: "ANGLE (NVIDIA, D3D11 vs_5_0 ps_5_0, D3D11)",
2731
});
2832
});
2933

30-
it("reports null renderer when WebGL is unavailable", async () => {
31-
const page = makePage({ isSwiftShader: false, renderer: null });
32-
expect(await detectGpuBackend(page)).toEqual({ isSwiftShader: false, renderer: null });
33-
});
34-
3534
it("detectSwiftShader wrapper returns true when renderer is SwiftShader", async () => {
3635
const page = makePage({ isSwiftShader: true, renderer: "Google SwiftShader" });
3736
expect(await detectSwiftShader(page)).toBe(true);
@@ -43,9 +42,88 @@ describe("detectGpuBackend", () => {
4342
});
4443

4544
it("passes a function to page.evaluate", async () => {
46-
const page = makePage({ isSwiftShader: false, renderer: null });
45+
const page = makePage({ isSwiftShader: false, webglAvailable: false, renderer: null });
4746
await detectGpuBackend(page);
48-
expect(page.evaluate).toHaveBeenCalledWith(expect.any(Function));
47+
expect(page.evaluate).toHaveBeenCalledWith(
48+
expect.any(Function),
49+
SOFTWARE_WEBGL_RENDERER_TOKENS,
50+
);
51+
});
52+
});
53+
54+
// ── detectGpuBackend: the in-page probe itself ────────────────────────────────
55+
// The mocks above hand back a canned verdict, so none of them exercise the probe that
56+
// produces it. These run the real in-page function against a stand-in `document`.
57+
58+
describe("detectGpuBackend in-page probe", () => {
59+
afterEach(() => vi.unstubAllGlobals());
60+
61+
/** A page whose evaluate runs the probe against a fake canvas. */
62+
function pageWithCanvas(getContext: (type: string) => unknown): Page {
63+
vi.stubGlobal("document", { createElement: () => ({ getContext }) });
64+
return {
65+
evaluate: async (fn: (...args: unknown[]) => unknown, ...args: unknown[]) => fn(...args),
66+
} as unknown as Page;
67+
}
68+
69+
/** The gate for a screenshot launch, where only the backend can close it. */
70+
const gateFor = (backend: Awaited<ReturnType<typeof detectGpuBackend>>) =>
71+
drawElementGate({ backend, launchCaptureMode: "screenshot", forceDE: false });
72+
73+
const glWithRenderer = (renderer: string) => ({
74+
getExtension: () => ({ UNMASKED_RENDERER_WEBGL: 0x9246 }),
75+
getParameter: () => renderer,
76+
});
77+
78+
it("reads a host with no WebGL context as unavailable, not as a real GPU", async () => {
79+
const backend = await detectGpuBackend(pageWithCanvas(() => null));
80+
expect(backend).toEqual({ isSwiftShader: false, webglAvailable: false, renderer: null });
81+
expect(gateFor(backend)).toBe("webgl_unavailable");
82+
});
83+
84+
it("reads a getContext that throws as unavailable too", async () => {
85+
const backend = await detectGpuBackend(
86+
pageWithCanvas(() => {
87+
throw new Error("GPU process crashed");
88+
}),
89+
);
90+
expect(backend.webglAvailable).toBe(false);
91+
expect(gateFor(backend)).toBe("webgl_unavailable");
92+
});
93+
94+
it("leaves a real GPU unchanged: WebGL available, not software, gate open", async () => {
95+
const renderer = "ANGLE (Apple, ANGLE Metal Renderer: Apple M4 Pro, Unspecified Version)";
96+
const backend = await detectGpuBackend(pageWithCanvas(() => glWithRenderer(renderer)));
97+
expect(backend).toEqual({ isSwiftShader: false, webglAvailable: true, renderer });
98+
expect(gateFor(backend)).toBeNull();
99+
});
100+
101+
it("leaves real SwiftShader unchanged: software, gated as swiftshader", async () => {
102+
const renderer =
103+
"ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (Subzero)), SwiftShader driver)";
104+
const backend = await detectGpuBackend(pageWithCanvas(() => glWithRenderer(renderer)));
105+
expect(backend).toEqual({ isSwiftShader: true, webglAvailable: true, renderer });
106+
expect(gateFor(backend)).toBe("swiftshader");
107+
});
108+
109+
it.each([
110+
["llvmpipe", "ANGLE (Mesa, llvmpipe (LLVM 15.0.7, 256 bits), OpenGL 4.5)"],
111+
[
112+
"Microsoft Basic Render Driver",
113+
"ANGLE (Microsoft, Microsoft Basic Render Driver Direct3D11 vs_5_0 ps_5_0)",
114+
],
115+
])("reads %s as software GL, gated like SwiftShader", async (_name, renderer) => {
116+
const backend = await detectGpuBackend(pageWithCanvas(() => glWithRenderer(renderer)));
117+
expect(backend).toEqual({ isSwiftShader: true, webglAvailable: true, renderer });
118+
expect(gateFor(backend)).toBe("swiftshader");
119+
});
120+
121+
it("keeps a context whose renderer string is hidden as available (a real GL context)", async () => {
122+
const backend = await detectGpuBackend(
123+
pageWithCanvas(() => ({ getExtension: () => null, getParameter: () => "" })),
124+
);
125+
expect(backend).toEqual({ isSwiftShader: false, webglAvailable: true, renderer: null });
126+
expect(gateFor(backend)).toBeNull();
49127
});
50128
});
51129

@@ -85,6 +163,45 @@ describe("classifyGpuRenderer", () => {
85163
});
86164
});
87165

166+
// ── drawElementGate ────────────────────────────────────────────────────────────
167+
168+
describe("drawElementGate", () => {
169+
const gpu = { isSwiftShader: false, webglAvailable: true };
170+
171+
it("gates an opaque drawElement session launched for BeginFrame, even with a GPU backend", () => {
172+
expect(drawElementGate({ backend: gpu, launchCaptureMode: "beginframe", forceDE: false })).toBe(
173+
"beginframe_no_self_verify",
174+
);
175+
});
176+
177+
it("lets a screenshot launch with a GPU backend engage", () => {
178+
expect(
179+
drawElementGate({ backend: gpu, launchCaptureMode: "screenshot", forceDE: false }),
180+
).toBeNull();
181+
});
182+
183+
it("names the backend before the launch mode, so a GPU-less BeginFrame host reads as webgl_unavailable", () => {
184+
const none = { isSwiftShader: false, webglAvailable: false };
185+
expect(
186+
drawElementGate({ backend: none, launchCaptureMode: "beginframe", forceDE: false }),
187+
).toBe("webgl_unavailable");
188+
const soft = { isSwiftShader: true, webglAvailable: true };
189+
expect(
190+
drawElementGate({ backend: soft, launchCaptureMode: "beginframe", forceDE: false }),
191+
).toBe("swiftshader");
192+
});
193+
194+
it("lets HF_FORCE_DRAWELEMENT past the launch gate only, for R&D", () => {
195+
expect(
196+
drawElementGate({ backend: gpu, launchCaptureMode: "beginframe", forceDE: true }),
197+
).toBeNull();
198+
const soft = { isSwiftShader: true, webglAvailable: true };
199+
expect(drawElementGate({ backend: soft, launchCaptureMode: "beginframe", forceDE: true })).toBe(
200+
"swiftshader",
201+
);
202+
});
203+
});
204+
88205
// ── resolveDrawElementCaptureMode ──────────────────────────────────────────────
89206

90207
describe("resolveDrawElementCaptureMode", () => {

‎packages/engine/src/services/drawElementService.ts‎

Lines changed: 54 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -15,6 +15,8 @@
1515
*/
1616

1717
import type { Page } from "puppeteer-core";
18+
import { SOFTWARE_WEBGL_RENDERER_TOKENS } from "./browserManager.js";
19+
import type { CaptureMode } from "./browserLeasePool.js";
1820

1921
/**
2022
* 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";
5658
* destination additionally drops promoted sub-layers (Chromium bug
5759
* 521434899). The speedup is real only on a hardware GPU (macOS 1.6×), so
5860
* SwiftShader always routes to the platform baseline.
59-
*
60-
* The former <video> gate (a proxy for the word-by-word caption opacity pattern)
61-
* was removed once Chrome 151 fixed crbug 521861819: video + nested-fade comps now
62-
* render correctly on the drawElement path (verified PSNR=inf vs baseline). 151 is
63-
* the pinned floor. See docs/fast-capture-limitations.md Lim 2.
61+
* - No WebGL at all (a GPU-less host asked for hardware GL) is software at best: `webgl_unavailable`.
62+
* - A BeginFrame launch (Linux headless-shell): the self-verify truth page has no BeginFrame
63+
* driver, so drawElement is gated as `beginframe_no_self_verify`.
6464
*/
6565
export function resolveDrawElementCaptureMode(
66-
isSwiftShader: boolean,
66+
softwareBackend: boolean,
6767
transparent: boolean,
6868
): "drawelement" | "screenshot" {
69-
// `transparent` is retained for call-site clarity; SwiftShader blocks
69+
// `transparent` is retained for call-site clarity; a software backend blocks
7070
// unconditionally now (no GPU egress to skip — parity at best), which
7171
// subsumes the former transparent-only SwiftShader case.
7272
void transparent;
73-
if (isSwiftShader) return "screenshot";
73+
if (softwareBackend) return "screenshot";
7474
return "drawelement";
7575
}
7676

77+
export type DrawElementGateReason =
78+
| "swiftshader"
79+
| "webgl_unavailable"
80+
| "beginframe_no_self_verify";
81+
82+
/**
83+
* The init-time gate that routes drawElement to the baseline capture, or null when it may engage.
84+
* `swiftshader` covers any software GL; `webgl_unavailable` is a host with no WebGL at all.
85+
* `beginframe_no_self_verify` is a BeginFrame launch, which cannot take the self-verify ground truth.
86+
* `forceDE` (HF_FORCE_DRAWELEMENT) bypasses only the launch gate. Pure; exported for tests.
87+
*/
88+
export function drawElementGate(args: {
89+
backend: Pick<GpuBackendInfo, "isSwiftShader" | "webglAvailable">;
90+
launchCaptureMode: CaptureMode;
91+
forceDE: boolean;
92+
}): DrawElementGateReason | null {
93+
const { backend, launchCaptureMode, forceDE } = args;
94+
if (backend.isSwiftShader) return "swiftshader";
95+
if (!backend.webglAvailable) return "webgl_unavailable";
96+
if (launchCaptureMode === "beginframe" && !forceDE) return "beginframe_no_self_verify";
97+
return null;
98+
}
99+
77100
/**
78101
* Instrument `HTMLCanvasElement.getContext` before any page script runs.
79102
*
@@ -147,8 +170,10 @@ export function forcePreservedDrawingBuffer(): void {
147170
}
148171

149172
export interface GpuBackendInfo {
150-
/** SwiftShader (software rasterizer) — e.g. Docker headless-shell. */
173+
/** Software GL (SwiftShader, llvmpipe, ...) — e.g. Docker headless-shell. Named for the common case. */
151174
isSwiftShader: boolean;
175+
/** False when no WebGL context could be created (null or threw): not a real GPU. */
176+
webglAvailable: boolean;
152177
/**
153178
* Raw UNMASKED_RENDERER_WEBGL string (e.g. "ANGLE (Apple, ANGLE Metal
154179
* Renderer: Apple M4 Pro, ...)", "ANGLE (NVIDIA, GeForce RTX 3080 Direct3D11
@@ -207,22 +232,32 @@ export function classifyGpuRenderer(renderer: string | null | undefined): string
207232
* Detect the page's WebGL backend: SwiftShader vs a real GPU, plus the raw
208233
* renderer string for telemetry.
209234
*
210-
* `isSwiftShader` is true inside Docker headless-shell with
211-
* --use-angle=swiftshader. Call once after window.__hf is ready; cache the
235+
* `isSwiftShader` is true for any software GL, e.g. Docker headless-shell with
236+
* --use-angle=swiftshader; `webglAvailable` is false with no WebGL at all. Call once after window.__hf is ready; cache the
212237
* result on the session.
213238
*/
214239
export async function detectGpuBackend(page: Page): Promise<GpuBackendInfo> {
215-
return page.evaluate((): GpuBackendInfo => {
240+
return page.evaluate((softwareTokens: readonly string[]): GpuBackendInfo => {
216241
const canvas = document.createElement("canvas");
217-
const gl =
218-
canvas.getContext("webgl") ||
219-
(canvas.getContext("experimental-webgl") as WebGLRenderingContext | null);
220-
if (!gl) return { isSwiftShader: false, renderer: null };
242+
let gl: WebGLRenderingContext | null = null;
243+
try {
244+
gl =
245+
canvas.getContext("webgl") ||
246+
(canvas.getContext("experimental-webgl") as WebGLRenderingContext | null);
247+
} catch {
248+
gl = null;
249+
}
250+
if (!gl) return { isSwiftShader: false, webglAvailable: false, renderer: null };
221251
const ext = gl.getExtension("WEBGL_debug_renderer_info");
222-
if (!ext) return { isSwiftShader: false, renderer: null };
252+
if (!ext) return { isSwiftShader: false, webglAvailable: true, renderer: null };
223253
const renderer = gl.getParameter(ext.UNMASKED_RENDERER_WEBGL) as string;
224-
return { isSwiftShader: renderer.toLowerCase().includes("swiftshader"), renderer };
225-
});
254+
const lower = renderer.toLowerCase();
255+
return {
256+
isSwiftShader: softwareTokens.some((token) => lower.includes(token)),
257+
webglAvailable: true,
258+
renderer,
259+
};
260+
}, SOFTWARE_WEBGL_RENDERER_TOKENS);
226261
}
227262

228263
/**

‎packages/engine/src/services/frameCapture.ts‎

Lines changed: 23 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -85,9 +85,10 @@ import {
8585
import {
8686
classifyGpuRenderer,
8787
detectGpuBackend,
88+
drawElementGate,
89+
type DrawElementGateReason,
8890
injectDrawElementCanvas,
8991
captureDrawElementFrame,
90-
resolveDrawElementCaptureMode,
9192
forcePreservedDrawingBuffer,
9293
instrumentAcceleratedCanvases,
9394
initDrawElementWorkerEncode,
@@ -974,6 +975,18 @@ async function waitForCloseWithTimeout(promise: Promise<unknown>): Promise<boole
974975
return !timedOut;
975976
}
976977

978+
const DE_GATE_MESSAGES: Record<DrawElementGateReason, string> = {
979+
swiftshader:
980+
"SwiftShader (software rasterizer, no GPU egress to skip, drawElement is " +
981+
"parity-or-slower; see fast-capture-limitations.md)",
982+
webgl_unavailable:
983+
"WebGL is unavailable (no GPU behind this browser, so it rasterizes in software and " +
984+
"drawElement has no GPU egress to skip)",
985+
beginframe_no_self_verify:
986+
"this browser was launched for BeginFrame capture, whose self-verify truth page has no " +
987+
"BeginFrame driver, so drawElement frames could not be checked",
988+
};
989+
977990
/**
978991
* Post-readiness capture-surface init, shared by the screenshot and BeginFrame
979992
* init paths (called after the page is fully ready). When `useDrawElement` is
@@ -1128,18 +1141,21 @@ async function initDrawElementOrTransparentBackground(
11281141
// Both reproduced on Chrome <=150 (video+caption-fade ~12 dB; stacked fade
11291142
// 24.5 dB) and both render correctly on 151 (verified: video+nested-fade repro
11301143
// PSNR=inf; efb59c5b 24.5→47.4 dB, 0 damaged frames). 151 is the pinned floor.
1131-
const mode = resolveDrawElementCaptureMode(session.isSwiftShader, transparent);
1132-
if (mode === "screenshot") {
1133-
session.deGateReason = "swiftshader";
1134-
session.deFallbackTrigger = "swiftshader";
1144+
const gateReason = drawElementGate({
1145+
backend: gpuBackend,
1146+
launchCaptureMode: session.launchCaptureMode,
1147+
forceDE,
1148+
});
1149+
if (gateReason !== null) {
1150+
session.deGateReason = gateReason;
1151+
session.deFallbackTrigger = gateReason;
11351152
// Fall back to the browser's LAUNCH mode, not unconditionally to
11361153
// "screenshot": on a BeginFrame-launched browser (Linux fast capture)
11371154
// Page.captureScreenshot hangs for the full protocol timeout, while
11381155
// beginFrameCapture is the platform's normal baseline path.
11391156
console.error(
11401157
`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
1141-
"SwiftShader (software rasterizer, no GPU egress to skip, drawElement is " +
1142-
"parity-or-slower; see fast-capture-limitations.md)",
1158+
DE_GATE_MESSAGES[gateReason],
11431159
);
11441160
await routeToFallback();
11451161
} else {

‎packages/engine/src/types.ts‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -414,9 +414,9 @@ export interface CapturePerfSummary {
414414
chromeMemorySamples?: number;
415415
/**
416416
* Low-cardinality init-time gate that routed a drawElement-eligible session
417-
* to the baseline: `swiftshader` | `css_effect:<fx>` | `at_risk_timeline` |
418-
* `3d_init_failed` | `supersampling` | `render_mode_hint`. Undefined when
419-
* drawElement ran or was never attempted.
417+
* to the baseline: `swiftshader` | `webgl_unavailable` | `beginframe_no_self_verify` |
418+
* `css_effect:<fx>` | `at_risk_timeline` | `3d_init_failed` | `supersampling` |
419+
* `render_mode_hint`. Undefined when drawElement ran or was never attempted.
420420
*/
421421
deGateReason?: string;
422422
motionBlur?: PageMotionBlurSummary;

0 commit comments

Comments
 (0)