From cb30157ebbbcfedd3606b9d566d565f4412de45e Mon Sep 17 00:00:00 2001 From: Vance Ingalls Date: Tue, 28 Jul 2026 00:00:21 -0700 Subject: [PATCH] feat(engine): open drawElement fast capture to Windows hardware GPU MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Widen the default-on drawElement clamp from darwin-only to darwin|win32 (still requiring a non-software-GPU browser). The darwin restriction was a validation envelope, not an architectural limit — the CanvasDrawElement Chrome flag ships on every platform, and every safety layer that made the macOS default-on release (v0.7.38) survivable is platform-neutral: compile-time gates, the SwiftShader init gate, per-render worker-encode self-verification with screenshot fallback, and the blank guard. Worst case on an unvalidated D3D11 backend is the same as on Metal: verify catches a bad frame and the render re-runs on the screenshot baseline. Why now: 30-day telemetry shows ~206k non-CI hardware-GPU Windows renders (~78% of the win32 fleet, 18k installs) held on the slow screenshot path by the clamp — the second-largest perf population after macOS, carrying ~1,550 capture-hours/month in the DE-eligible >=700-frame band alone at a measured ~2x speedup opportunity. Instrumentation for the new cohort: drawElement session init now records the raw WebGL UNMASKED_RENDERER_WEBGL string (detectSwiftShader generalized to detectGpuBackend — same single evaluate, the string was previously read and discarded) and threads it session -> CapturePerfSummary -> RenderPerfSummary -> render_complete as `gpu_renderer`. drawElement damage proved compositor-backend-specific throughout the macOS rollout, so D3D11-cohort failures must cluster by ANGLE backend + GPU vendor (NVIDIA/AMD/Intel), not just `os`. The two DE clamp branches are extracted into a pure, unit-tested `resolveDefaultDrawElement` (platform + GPU mode + worker-encode + explicit opt-in), which also drops resolveConfig's cyclomatic complexity. The win32 streaming-encode compound tests collapse onto one shared helper. Linux stays excluded: that fleet is headless/Docker SwiftShader, where DE has no speedup and known rendering defects. Kill switches unchanged: PRODUCER_EXPERIMENTAL_FAST_CAPTURE=false, --experimental-fast-capture=false. Co-Authored-By: Claude Opus 5 (1M context) --- packages/cli/src/commands/render.ts | 2 +- packages/cli/src/telemetry/events.ts | 3 + packages/engine/src/config.test.ts | 152 +++++++++++------- packages/engine/src/config.ts | 94 +++++++---- .../src/services/drawElementService.test.ts | 43 +++-- .../engine/src/services/drawElementService.ts | 41 +++-- packages/engine/src/services/frameCapture.ts | 14 +- packages/engine/src/types.ts | 8 + .../src/services/render/perfSummary.ts | 4 + .../src/services/renderOrchestrator.ts | 2 + 10 files changed, 252 insertions(+), 111 deletions(-) diff --git a/packages/cli/src/commands/render.ts b/packages/cli/src/commands/render.ts index 9b3d067e4..c70899cb4 100644 --- a/packages/cli/src/commands/render.ts +++ b/packages/cli/src/commands/render.ts @@ -1102,7 +1102,6 @@ let deParallelRouterTrialFiredThisProcess = false; * resetting outside a test process where many independent test cases share * one imported module instance. */ -// fallow-ignore-next-line unused-export export function __resetDeParallelRouterTrialStateForTests(): void { deParallelRouterTrialManagedByUs = false; deParallelRouterTrialFiredThisProcess = false; @@ -1429,6 +1428,7 @@ function trackRenderMetrics( deParallelRouter: perf?.drawElement?.parallelRouter, dePreRouterWorkers: perf?.drawElement?.preRouterWorkers, deGateReason: perf?.drawElement?.gateReason, + gpuRenderer: perf?.drawElement?.gpuRenderer, deWorkerEncode: perf?.drawElement?.workerEncode, deVerifyArmed: perf?.drawElement?.verifyArmed, deVerifyChecked: perf?.drawElement?.verifyChecked, diff --git a/packages/cli/src/telemetry/events.ts b/packages/cli/src/telemetry/events.ts index 8c67b88a4..05a0bb50f 100644 --- a/packages/cli/src/telemetry/events.ts +++ b/packages/cli/src/telemetry/events.ts @@ -183,6 +183,8 @@ export function trackRenderComplete( deParallelRouter?: string; dePreRouterWorkers?: number; deGateReason?: string; + /** Raw WebGL renderer string from DE session init (ANGLE backend + GPU vendor). */ + gpuRenderer?: string; deWorkerEncode?: boolean; deVerifyArmed?: number; deVerifyChecked?: number; @@ -280,6 +282,7 @@ export function trackRenderComplete( de_parallel_router: props.deParallelRouter, de_pre_router_workers: props.dePreRouterWorkers, de_gate_reason: props.deGateReason, + gpu_renderer: props.gpuRenderer, de_worker_encode: props.deWorkerEncode, de_verify_armed: props.deVerifyArmed, de_verify_checked: props.deVerifyChecked, diff --git a/packages/engine/src/config.test.ts b/packages/engine/src/config.test.ts index e917e3031..ce683547e 100644 --- a/packages/engine/src/config.test.ts +++ b/packages/engine/src/config.test.ts @@ -3,6 +3,7 @@ import { join } from "node:path"; import { tmpdir } from "node:os"; import { resolveConfig, + resolveDefaultDrawElement, DEFAULT_CONFIG, scaleProtocolTimeoutForComposition, shouldClampToScreenshotForConcreteGpu, @@ -232,6 +233,40 @@ describe("resolveConfig", () => { }); }); + describe("resolveDefaultDrawElement (pure host clamp)", () => { + const base = { + useDrawElement: true, + explicitOptIn: false, + browserGpuMode: "hardware" as const, + workerEncode: true, + }; + it("engages on darwin and win32, not linux", () => { + expect(resolveDefaultDrawElement({ ...base, platform: "darwin" })).toBe(true); + expect(resolveDefaultDrawElement({ ...base, platform: "win32" })).toBe(true); + expect(resolveDefaultDrawElement({ ...base, platform: "linux" })).toBe(false); + }); + it("software GPU clamps off even on supported platforms", () => { + expect( + resolveDefaultDrawElement({ ...base, platform: "win32", browserGpuMode: "software" }), + ).toBe(false); + }); + it("explicit opt-in overrides platform and GPU clamps", () => { + expect( + resolveDefaultDrawElement({ + ...base, + explicitOptIn: true, + platform: "linux", + browserGpuMode: "software", + }), + ).toBe(true); + }); + it("no worker-encode (no verify net) clamps the default off", () => { + expect(resolveDefaultDrawElement({ ...base, platform: "darwin", workerEncode: false })).toBe( + false, + ); + }); + }); + describe("useDrawElement (PRODUCER_EXPERIMENTAL_FAST_CAPTURE)", () => { it("default is clamped off on software-GPU hosts (page-side compositing preserved)", () => { setEnv("PRODUCER_BROWSER_GPU_MODE", "software"); @@ -242,21 +277,20 @@ describe("resolveConfig", () => { expect(config.enablePageSideCompositing).toBe(true); }); - it("default engages on macOS with a hardware-GPU browser", () => { - setEnv("PRODUCER_BROWSER_GPU_MODE", "hardware"); - unsetEnv("PRODUCER_EXPERIMENTAL_FAST_CAPTURE"); - unsetEnv("HF_DE_WORKER_ENCODE"); - const config = resolveConfig(); - expect(config.useDrawElement).toBe(process.platform === "darwin"); - }); - - it("default engages on macOS with auto GPU mode (the stock CLI path)", () => { - setEnv("PRODUCER_BROWSER_GPU_MODE", "auto"); - unsetEnv("PRODUCER_EXPERIMENTAL_FAST_CAPTURE"); - unsetEnv("HF_DE_WORKER_ENCODE"); - const config = resolveConfig(); - expect(config.useDrawElement).toBe(process.platform === "darwin"); - }); + // win32 opened 2026-07-27 (was darwin-only): ~206k non-CI hardware-GPU + // Windows renders / 30d sat on the screenshot path behind the old clamp. + // "auto" is the stock CLI path; both must pass the platform clamp. + for (const gpuMode of ["hardware", "auto"] as const) { + it(`default engages on macOS/Windows with ${gpuMode} GPU mode`, () => { + setEnv("PRODUCER_BROWSER_GPU_MODE", gpuMode); + unsetEnv("PRODUCER_EXPERIMENTAL_FAST_CAPTURE"); + unsetEnv("HF_DE_WORKER_ENCODE"); + const config = resolveConfig(); + expect(config.useDrawElement).toBe( + process.platform === "darwin" || process.platform === "win32", + ); + }); + } it("default requires worker-encode (the verified drain)", () => { setEnv("PRODUCER_BROWSER_GPU_MODE", "hardware"); @@ -624,40 +658,58 @@ describe("resolveConfig", () => { Object.defineProperty(process, "platform", { value: originalPlatform, configurable: true }); }); - it("auto-disables on win32 + software-GPU + workers=1 + no user opt-in", () => { - setPlatform("win32"); - setEnv("PRODUCER_BROWSER_GPU_MODE", "software"); - setEnv("PRODUCER_MAX_WORKERS", "1"); + /** + * Shared setup/assert for the win32 software-GPU compound: fixed common + * env (low-memory on, no explicit streaming opt-in), variable platform / + * gpu / workers, then assert whether the auto-disable fired. + */ + function expectCompoundOutcome(opts: { + platform: NodeJS.Platform; + gpuMode?: string; + workers?: string; + autoDisabled: boolean; + }): void { + setPlatform(opts.platform); + if (opts.gpuMode === undefined) unsetEnv("PRODUCER_BROWSER_GPU_MODE"); + else setEnv("PRODUCER_BROWSER_GPU_MODE", opts.gpuMode); + if (opts.workers === undefined) unsetEnv("PRODUCER_MAX_WORKERS"); + else setEnv("PRODUCER_MAX_WORKERS", opts.workers); setEnv("PRODUCER_LOW_MEMORY_MODE", "true"); unsetEnv("PRODUCER_ENABLE_STREAMING_ENCODE"); - const config = resolveConfig(); - expect(config.enableStreamingEncode).toBe(false); - expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBe(true); + expect(config.enableStreamingEncode).toBe(!opts.autoDisabled); + if (opts.autoDisabled) { + expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBe(true); + } else { + expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBeUndefined(); + } + } + + it("auto-disables on win32 + software-GPU + workers=1 + no user opt-in", () => { + expectCompoundOutcome({ + platform: "win32", + gpuMode: "software", + workers: "1", + autoDisabled: true, + }); }); it("leaves streaming-encode on when platform is linux", () => { - setPlatform("linux"); - setEnv("PRODUCER_BROWSER_GPU_MODE", "software"); - setEnv("PRODUCER_MAX_WORKERS", "1"); - setEnv("PRODUCER_LOW_MEMORY_MODE", "true"); - unsetEnv("PRODUCER_ENABLE_STREAMING_ENCODE"); - - const config = resolveConfig(); - expect(config.enableStreamingEncode).toBe(true); - expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBeUndefined(); + expectCompoundOutcome({ + platform: "linux", + gpuMode: "software", + workers: "1", + autoDisabled: false, + }); }); it("leaves streaming-encode on when workers > 1", () => { - setPlatform("win32"); - setEnv("PRODUCER_BROWSER_GPU_MODE", "software"); - setEnv("PRODUCER_MAX_WORKERS", "4"); - setEnv("PRODUCER_LOW_MEMORY_MODE", "true"); - unsetEnv("PRODUCER_ENABLE_STREAMING_ENCODE"); - - const config = resolveConfig(); - expect(config.enableStreamingEncode).toBe(true); - expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBeUndefined(); + expectCompoundOutcome({ + platform: "win32", + gpuMode: "software", + workers: "4", + autoDisabled: false, + }); }); it("respects explicit env opt-in (PRODUCER_ENABLE_STREAMING_ENCODE=true) on the compound", () => { @@ -703,16 +755,8 @@ describe("resolveConfig", () => { // --low-memory-mode implies screenshot capture. Compound applies even // if browserGpuMode is not literal "software" (defense-in-depth: matches // the OR semantics in `softwareGpuForced`). - setPlatform("win32"); - unsetEnv("PRODUCER_BROWSER_GPU_MODE"); unsetEnv("PRODUCER_DISABLE_GPU"); - setEnv("PRODUCER_MAX_WORKERS", "1"); - setEnv("PRODUCER_LOW_MEMORY_MODE", "true"); - unsetEnv("PRODUCER_ENABLE_STREAMING_ENCODE"); - - const config = resolveConfig(); - expect(config.enableStreamingEncode).toBe(false); - expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBe(true); + expectCompoundOutcome({ platform: "win32", workers: "1", autoDisabled: true }); }); it("does not trigger when concurrency is 'auto' (workers not explicitly pinned)", () => { @@ -720,15 +764,7 @@ describe("resolveConfig", () => { // helper's numeric workers check treats NaN as "unknown, don't trigger". // Downstream workers may still resolve to 1 via lowMemoryMode, but the // config-time clamp is deliberately conservative. - setPlatform("win32"); - setEnv("PRODUCER_BROWSER_GPU_MODE", "software"); - unsetEnv("PRODUCER_MAX_WORKERS"); - setEnv("PRODUCER_LOW_MEMORY_MODE", "true"); - unsetEnv("PRODUCER_ENABLE_STREAMING_ENCODE"); - - const config = resolveConfig(); - expect(config.enableStreamingEncode).toBe(true); - expect(config.streamingEncodeAutoDisabledOnWin32Compound).toBeUndefined(); + expectCompoundOutcome({ platform: "win32", gpuMode: "software", autoDisabled: false }); }); }); diff --git a/packages/engine/src/config.ts b/packages/engine/src/config.ts index b350f9e67..fb06796fe 100644 --- a/packages/engine/src/config.ts +++ b/packages/engine/src/config.ts @@ -66,8 +66,8 @@ export interface EngineConfig { /** * Use drawElementImage for frame capture (requires the CanvasDrawElement * Chrome flag, added globally in buildChromeArgs). Default ON, clamped in - * `resolveConfig` to hosts where it can actually engage (macOS + hardware-GPU - * browser); compile/init gates and the runtime self-verification net route + * `resolveConfig` to hosts where it can actually engage (macOS or Windows + + * hardware-GPU browser); compile/init gates and the runtime self-verification net route * incompatible or damaged renders back to screenshot capture. * Kill switch: `PRODUCER_EXPERIMENTAL_FAST_CAPTURE=false` (or the CLI * `--experimental-fast-capture=false`). @@ -708,6 +708,39 @@ function memoryAdaptiveCacheBytesMb(): number { * Env vars provide backward compatibility during migration; explicit config * takes precedence over everything. */ +/** + * Platforms where default-on drawElement may engage: macOS (Metal-ANGLE, + * the original validated envelope) and Windows (D3D11-ANGLE, opened + * 2026-07-27 — see the clamp comment above resolveDefaultDrawElement's call + * site). Linux is excluded: that fleet is headless/Docker SwiftShader. + * Internal — the exported `resolveDefaultDrawElement` is the tested surface. + */ +function isDrawElementPlatform(platform: NodeJS.Platform): boolean { + return platform === "darwin" || platform === "win32"; +} + +/** + * Default-on drawElement host clamp. An explicit opt-in always wins (attempt + * DE, let the init-time gates route away — debugging relies on it). Otherwise + * DE stays on only where it can actually engage — a supported platform with a + * non-software-GPU browser — AND with worker-encode enabled: the runtime + * self-verification net lives in the worker-encode drain (the serial path has + * only the blank guard), so a default-on session without it would ship + * unverified drawElement frames. Pure; exported for tests. + */ +export function resolveDefaultDrawElement(args: { + useDrawElement: boolean; + explicitOptIn: boolean; + platform: NodeJS.Platform; + browserGpuMode: EngineConfig["browserGpuMode"]; + workerEncode: boolean; +}): boolean { + if (!args.useDrawElement) return false; + if (args.explicitOptIn) return true; + if (!isDrawElementPlatform(args.platform) || args.browserGpuMode === "software") return false; + return args.workerEncode; +} + export function resolveConfig(overrides?: Partial): EngineConfig { const env = (key: string): string | undefined => process.env[key]; const envNum = (key: string, fallback: number): number => { @@ -857,38 +890,45 @@ export function resolveConfig(overrides?: Partial): EngineConfig { }; // Default-on drawElement is clamped to hosts where it can actually engage - // (macOS with a non-software-GPU browser; SwiftShader drops transparent - // sub-layers — crbug 521434899). "auto" passes the clamp: the stock CLI - // resolves GPU mode to auto, which probes to hardware on real Macs — and if - // it resolves to software after all, the SwiftShader init-time gate still - // routes the session to the screenshot baseline. Without the clamp, the - // default would needlessly disable page-side shader compositing (below) on - // Linux/Docker hosts where DE never runs. An EXPLICIT opt-in (env or caller override) - // skips the clamp and keeps the old semantics — attempt DE, let the - // init-time gates route away — which debugging relies on. + // (macOS or Windows with a non-software-GPU browser; SwiftShader drops + // transparent sub-layers — crbug 521434899). "auto" passes the clamp: the + // stock CLI resolves GPU mode to auto, which probes to hardware on real + // Macs/PCs — and if it resolves to software after all, the SwiftShader + // init-time gate still routes the session to the screenshot baseline. + // Without the clamp, the default would needlessly disable page-side shader + // compositing (below) on Linux/Docker hosts where DE never runs. An + // EXPLICIT opt-in (env or caller override) skips the clamp and keeps the + // old semantics — attempt DE, let the init-time gates route away — which + // debugging relies on. + // + // win32 opened 2026-07-27: telemetry showed ~206k non-CI hardware-GPU + // Windows renders / 30d (~78% of the win32 fleet) held on the slow + // screenshot path by the darwin-only clamp — the second-largest perf + // population after macOS. The mechanism is platform-neutral (the Chrome + // flag ships everywhere); darwin-only was a validation envelope, not an + // architectural limit. Opening it rides the same per-render safety + // contract macOS shipped with in v0.7.38: compile/init gates + + // worker-encode self-verify + screenshot fallback catch damage per + // render, and `gpu_renderer` telemetry (captured at DE session init) + // segments the D3D11/ANGLE cohort by GPU vendor so backend-specific + // damage clusters are attributable. Kill switches unchanged + // (PRODUCER_EXPERIMENTAL_FAST_CAPTURE=false; per-render --workers). + // Linux stays excluded: the fleet there is headless/Docker SwiftShader. const explicitDrawElementOptIn = env("PRODUCER_EXPERIMENTAL_FAST_CAPTURE") === "true" || overrides?.useDrawElement === true; - if ( - merged.useDrawElement && - !explicitDrawElementOptIn && - !(process.platform === "darwin" && merged.browserGpuMode !== "software") - ) { - merged.useDrawElement = false; - } - // The runtime self-verification net lives in the worker-encode drain — the - // serial drawElement path has only the blank guard. Default-on drawElement - // therefore requires worker-encode; disabling HF_DE_WORKER_ENCODE without an - // explicit drawElement opt-in falls back to the screenshot baseline rather - // than shipping unverified drawElement frames. - if (merged.useDrawElement && !explicitDrawElementOptIn && !merged.enableDrawElementWorkerEncode) { - merged.useDrawElement = false; - } + merged.useDrawElement = resolveDefaultDrawElement({ + useDrawElement: merged.useDrawElement, + explicitOptIn: explicitDrawElementOptIn, + platform: process.platform, + browserGpuMode: merged.browserGpuMode, + workerEncode: merged.enableDrawElementWorkerEncode, + }); // Software GPU implies screenshot capture. // // Two existing platform gates already do most of the work: `browserManager` // only launches BeginFrame on Linux + chrome-headless-shell + !forceScreenshot, - // and the DE clamp above turns off `useDrawElement` on non-(darwin + + // and the DE clamp above turns off `useDrawElement` on non-((darwin|win32) + // non-software) hosts. Setting `forceScreenshot` here layers defense-in-depth // on top: // diff --git a/packages/engine/src/services/drawElementService.test.ts b/packages/engine/src/services/drawElementService.test.ts index d877c97a0..a21f9602e 100644 --- a/packages/engine/src/services/drawElementService.test.ts +++ b/packages/engine/src/services/drawElementService.test.ts @@ -1,34 +1,49 @@ import { describe, expect, it, vi } from "vitest"; import type { Page } from "puppeteer-core"; -import { detectSwiftShader, resolveDrawElementCaptureMode } from "./drawElementService.js"; +import { + detectGpuBackend, + detectSwiftShader, + resolveDrawElementCaptureMode, +} from "./drawElementService.js"; -// ── detectSwiftShader ────────────────────────────────────────────────────────── +// ── detectGpuBackend / detectSwiftShader ─────────────────────────────────────── -describe("detectSwiftShader", () => { +describe("detectGpuBackend", () => { function makePage(evaluateResult: unknown): Page { return { evaluate: vi.fn().mockResolvedValue(evaluateResult), } as unknown as Page; } - it("returns true when renderer includes 'swiftshader'", async () => { - const page = makePage(true); + it("carries the raw renderer string alongside the SwiftShader verdict", async () => { + const page = makePage({ + isSwiftShader: false, + renderer: "ANGLE (NVIDIA, D3D11 vs_5_0 ps_5_0, D3D11)", + }); + expect(await detectGpuBackend(page)).toEqual({ + isSwiftShader: false, + 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); }); - it("returns false for a standard GPU renderer string", async () => { - const page = makePage(false); - expect(await detectSwiftShader(page)).toBe(false); - }); - - it("returns false when WebGL is unavailable", async () => { - const page = makePage(false); + it("detectSwiftShader wrapper returns false for a hardware renderer", async () => { + const page = makePage({ isSwiftShader: false, renderer: "ANGLE (Apple, ANGLE Metal)" }); expect(await detectSwiftShader(page)).toBe(false); }); it("passes a function to page.evaluate", async () => { - const page = makePage(false); - await detectSwiftShader(page); + const page = makePage({ isSwiftShader: false, renderer: null }); + await detectGpuBackend(page); expect(page.evaluate).toHaveBeenCalledWith(expect.any(Function)); }); }); diff --git a/packages/engine/src/services/drawElementService.ts b/packages/engine/src/services/drawElementService.ts index 99b126424..a5d08eb08 100644 --- a/packages/engine/src/services/drawElementService.ts +++ b/packages/engine/src/services/drawElementService.ts @@ -105,27 +105,50 @@ export function instrumentAcceleratedCanvases(): void { }; } +export interface GpuBackendInfo { + /** SwiftShader (software rasterizer) — e.g. Docker headless-shell. */ + isSwiftShader: boolean; + /** + * Raw UNMASKED_RENDERER_WEBGL string (e.g. "ANGLE (Apple, ANGLE Metal + * Renderer: Apple M4 Pro, ...)", "ANGLE (NVIDIA, D3D11 ...)"), or null when + * WebGL / the debug extension is unavailable. Carried to render telemetry: + * drawElement failure modes proved compositor-backend-specific during the + * macOS rollout, so the win32/D3D11 cohort needs damage clusters + * attributable to a GPU vendor + ANGLE backend, not just `os`. + */ + renderer: string | null; +} + /** - * Detect whether the page is running on SwiftShader (software rasterizer). + * Detect the page's WebGL backend: SwiftShader vs a real GPU, plus the raw + * renderer string for telemetry. * - * Returns true inside Docker headless-shell with --use-angle=swiftshader. - * Returns false on macOS / Linux with a real GPU. - * Call once after window.__hf is ready; cache result on session. + * `isSwiftShader` is true inside Docker headless-shell with + * --use-angle=swiftshader. Call once after window.__hf is ready; cache the + * result on the session. */ -export async function detectSwiftShader(page: Page): Promise { - return page.evaluate(() => { +export async function detectGpuBackend(page: Page): Promise { + return page.evaluate((): GpuBackendInfo => { const canvas = document.createElement("canvas"); const gl = canvas.getContext("webgl") || (canvas.getContext("experimental-webgl") as WebGLRenderingContext | null); - if (!gl) return false; + if (!gl) return { isSwiftShader: false, renderer: null }; const ext = gl.getExtension("WEBGL_debug_renderer_info"); - if (!ext) return false; + if (!ext) return { isSwiftShader: false, renderer: null }; const renderer = gl.getParameter(ext.UNMASKED_RENDERER_WEBGL) as string; - return renderer.toLowerCase().includes("swiftshader"); + return { isSwiftShader: renderer.toLowerCase().includes("swiftshader"), renderer }; }); } +/** + * Back-compat wrapper over {@link detectGpuBackend} for callers that only + * need the SwiftShader boolean. + */ +export async function detectSwiftShader(page: Page): Promise { + return (await detectGpuBackend(page)).isSwiftShader; +} + /** * Inject a `` around the composition root. * diff --git a/packages/engine/src/services/frameCapture.ts b/packages/engine/src/services/frameCapture.ts index af977c3a6..88e044cb4 100644 --- a/packages/engine/src/services/frameCapture.ts +++ b/packages/engine/src/services/frameCapture.ts @@ -34,7 +34,7 @@ import { shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js"; import { - detectSwiftShader, + detectGpuBackend, injectDrawElementCanvas, captureDrawElementFrame, resolveDrawElementCaptureMode, @@ -146,6 +146,13 @@ export interface CaptureSession { config?: Partial; /** True if running on SwiftShader (detected at init). Undefined before init. */ isSwiftShader?: boolean; + /** + * Raw WebGL UNMASKED_RENDERER_WEBGL string, captured alongside the + * SwiftShader probe at DE session init (e.g. "ANGLE (NVIDIA, D3D11 ...)"). + * Surfaces in CapturePerfSummary → render telemetry so backend-specific + * drawElement damage (Metal vs D3D11 vs GL) clusters attributably. + */ + gpuRenderer?: string; /** drawElementImage canvas was injected and is ready for capture. */ drawElementReady?: boolean; /** @@ -704,7 +711,9 @@ async function initDrawElementOrTransparentBackground( ); } if (useDrawElement) { - session.isSwiftShader = await detectSwiftShader(page); + const gpuBackend = await detectGpuBackend(page); + session.isSwiftShader = gpuBackend.isSwiftShader; + session.gpuRenderer = gpuBackend.renderer ?? undefined; const transparent = session.options.format === "png"; async function routeToFallback(): Promise { session.captureMode = session.launchCaptureMode; @@ -3784,6 +3793,7 @@ export function getCapturePerfSummary(session: CaptureSession): CapturePerfSumma beginFrameNoDamage: session.beginFrameNoDamageCount, beginFrameHasDamage: session.beginFrameHasDamageCount, captureMode: session.captureMode, + gpuRenderer: session.gpuRenderer, deGateReason: session.deGateReason, deFallbackTrigger: session.deFallbackTrigger, deWorkerEncode: session.workerEncodeEnabled ?? false, diff --git a/packages/engine/src/types.ts b/packages/engine/src/types.ts index cc467c328..9253e00df 100644 --- a/packages/engine/src/types.ts +++ b/packages/engine/src/types.ts @@ -276,6 +276,14 @@ export interface CapturePerfSummary { // ── drawElement fast-capture outcome (default-on release visibility) ── /** Final capture mode this session used: "drawelement" | "screenshot" | "beginframe". */ captureMode: string; + /** + * Raw WebGL UNMASKED_RENDERER_WEBGL string from DE session init (ANGLE + * backend + GPU vendor, e.g. "ANGLE (Apple, ANGLE Metal Renderer: ...)"). + * Undefined when drawElement was never attempted. Lets telemetry cluster + * backend-specific damage now that DE engages on both Metal (darwin) and + * D3D11 (win32). + */ + gpuRenderer?: string; /** * Low-cardinality init-time gate that routed a drawElement-eligible session * to the baseline: `swiftshader` | `css_effect:` | `at_risk_timeline` | diff --git a/packages/producer/src/services/render/perfSummary.ts b/packages/producer/src/services/render/perfSummary.ts index 2e288edc4..fe72e1e1c 100644 --- a/packages/producer/src/services/render/perfSummary.ts +++ b/packages/producer/src/services/render/perfSummary.ts @@ -111,6 +111,9 @@ function aggregateDrawElement( const gateReasons = [ ...new Set(perfs.map((p) => p.deGateReason).filter((r): r is string => !!r)), ].sort(); + const gpuRenderers = [ + ...new Set(perfs.map((p) => p.gpuRenderer).filter((r): r is string => !!r)), + ].sort(); const drain = de.drainStats; return { mode: modes.join("|") || "unknown", @@ -121,6 +124,7 @@ function aggregateDrawElement( parallelRouter: de.parallelRouter ?? "none", preRouterWorkers: de.preRouterWorkers, gateReason: gateReasons.length > 0 ? gateReasons.join("|") : undefined, + gpuRenderer: gpuRenderers.length > 0 ? gpuRenderers.join("|") : undefined, workerEncode: perfs.some((p) => p.deWorkerEncode), verifyArmed: perfs.reduce((sum, p) => sum + (p.deVerifyArmed ?? 0), 0), verifyChecked: drain?.verifyChecked ?? 0, diff --git a/packages/producer/src/services/renderOrchestrator.ts b/packages/producer/src/services/renderOrchestrator.ts index 504137f12..5417ef3fd 100644 --- a/packages/producer/src/services/renderOrchestrator.ts +++ b/packages/producer/src/services/renderOrchestrator.ts @@ -498,6 +498,8 @@ export interface RenderPerfSummary { preRouterWorkers?: number; /** Engine init-time gate: swiftshader | css_effect:* | at_risk_timeline | 3d_init_failed | supersampling | render_mode_hint. */ gateReason?: string; + /** Raw WebGL renderer string from DE session init (ANGLE backend + GPU vendor); |-joined across parallel sessions. */ + gpuRenderer?: string; /** Worker-encode drain (the verified path) was active. */ workerEncode: boolean; /** Self-verification ground-truth samples armed at init. */