Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

tools(render): find the call a GPU process died in, and compile one shader pair alone

yhhc33030b5d2c1
diff --git a/tools/render-host/build.mjs b/tools/render-host/build.mjs
index d58a099fb..ea66aa270 100644
--- a/tools/render-host/build.mjs
+++ b/tools/render-host/build.mjs
@@ -57,5 +57,6 @@ await build({
});
await cp(path.join(HERE, 'index.html'), path.join(OUT, 'index.html'));
+await cp(path.join(HERE, 'gltrace.js'), path.join(OUT, 'gltrace.js'));
await cp(WASM_SRC, path.join(OUT, 'wasm'), { recursive: true });
console.log(`render-host: built into ${path.relative(ROOT, OUT)}`);
diff --git a/tools/render-host/gltrace.js b/tools/render-host/gltrace.js
new file mode 100644
index 000000000..1b2c2cc94
--- /dev/null
+++ b/tools/render-host/gltrace.js
@@ -0,0 +1,46 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file gltrace.js — what the page asked WebGL for, in order, for a GPU process that dies mid-frame.
+ *
+ * Loaded before the engine and inert unless the page is opened with `gltrace=1` (run.mjs does that for
+ * ESTELLA_VERIFY_GL_TRACE). Every shader compiled, program linked (with its sources, once), program used and
+ * draw made is printed as a `GLTRACE ` console line, which the runner appends to a file as it arrives: when the
+ * GPU process dies inside a driver or a shader compiler, the last line is the call it died in.
+ */
+(() => {
+ if (!new URLSearchParams(location.search).has('gltrace')) return;
+ const P = WebGL2RenderingContext.prototype;
+ const ids = new WeakMap();
+ let next = 1;
+ const id = (o) => {
+ if (!o) return 0;
+ if (!ids.has(o)) ids.set(o, next++);
+ return ids.get(o);
+ };
+ const sources = new WeakMap();
+ const printed = new WeakSet();
+ const log = (s) => console.log('GLTRACE ' + s);
+ const wrap = (name, before) => {
+ const orig = P[name];
+ P[name] = function (...args) {
+ before.apply(this, args);
+ return orig.apply(this, args);
+ };
+ };
+ wrap('shaderSource', function (shader, text) { sources.set(shader, text); });
+ wrap('compileShader', function (shader) { log('compile shader#' + id(shader)); });
+ wrap('attachShader', function (program, shader) { log('attach program#' + id(program) + ' shader#' + id(shader)); });
+ wrap('linkProgram', function (program) {
+ log('link program#' + id(program));
+ for (const shader of this.getAttachedShaders(program) || []) {
+ if (printed.has(shader)) continue;
+ printed.add(shader);
+ log('source shader#' + id(shader) + ' ' + JSON.stringify(sources.get(shader) || ''));
+ }
+ });
+ wrap('useProgram', function (program) { log('use program#' + id(program)); });
+ for (const d of ['drawElements', 'drawArrays', 'drawElementsInstanced', 'drawArraysInstanced']) {
+ wrap(d, function (...a) { log(d + ' ' + a.slice(0, 3).join(',')); });
+ }
+})();
diff --git a/tools/render-host/index.html b/tools/render-host/index.html
index 50d8d3847..4e7606cbf 100644
--- a/tools/render-host/index.html
+++ b/tools/render-host/index.html
@@ -16,6 +16,8 @@
</style>
</head>
<body>
+ <!-- Inert unless the page is opened with gltrace=1 (ESTELLA_VERIFY_GL_TRACE). -->
+ <script src="./gltrace.js"></script>
<script type="module" src="./host.js"></script>
</body>
</html>
diff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjs
index a384b3155..f83abd1c6 100644
--- a/tools/render-host/run.mjs
+++ b/tools/render-host/run.mjs
@@ -57,6 +57,7 @@ import { app, BrowserWindow } from 'electron';
for (const stream of [process.stdout, process.stderr]) stream.on('error', () => app.exit(0));
import os from 'node:os';
import { writeFile } from 'node:fs/promises';
+import { appendFileSync, writeFileSync } from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { onRendererConsole } from '../lib/rendererConsole.mjs';
@@ -258,7 +259,7 @@ app.whenReady().then(async () => {
let server;
try {
server = await serveHost(DIST);
- const url = `http://127.0.0.1:${server.address().port}/${PAGE}?w=${W}&h=${H}&backend=${BACKEND}${COLORSPACE ? `&colorSpace=${COLORSPACE}` : ''}${OUTPUT_TRANSFORM ? `&outputTransform=${OUTPUT_TRANSFORM}` : ''}${MSAA ? `&msaa=${MSAA}` : ''}${PREPASS ? '&prepass=1' : ''}${TEXTURES ? `&textures=${TEXTURES}` : ''}${DEPTH_LAYERS ? `&depthLayers=${DEPTH_LAYERS}` : ''}${RENDER_RESOLUTION ? `&renderResolution=${RENDER_RESOLUTION}` : ''}${SEED ? `&seed=${SEED}` : ''}${process.env.ESTELLA_VERIFY_NO_COMPUTE === '1' ? '&noCompute=1' : ''}`;
+ const url = `http://127.0.0.1:${server.address().port}/${PAGE}?w=${W}&h=${H}&backend=${BACKEND}${COLORSPACE ? `&colorSpace=${COLORSPACE}` : ''}${OUTPUT_TRANSFORM ? `&outputTransform=${OUTPUT_TRANSFORM}` : ''}${MSAA ? `&msaa=${MSAA}` : ''}${PREPASS ? '&prepass=1' : ''}${TEXTURES ? `&textures=${TEXTURES}` : ''}${DEPTH_LAYERS ? `&depthLayers=${DEPTH_LAYERS}` : ''}${RENDER_RESOLUTION ? `&renderResolution=${RENDER_RESOLUTION}` : ''}${SEED ? `&seed=${SEED}` : ''}${process.env.ESTELLA_VERIFY_NO_COMPUTE === '1' ? '&noCompute=1' : ''}${process.env.ESTELLA_VERIFY_GL_TRACE ? '&gltrace=1' : ''}`;
// useContentSize: the capture rectangle must be the page area, not the
// outer frame (the same trap the parity runner documents).
@@ -266,7 +267,13 @@ app.whenReady().then(async () => {
show: false, width: W, height: H, useContentSize: true,
webPreferences: { offscreen: false },
});
+ // ESTELLA_VERIFY_GL_TRACE=<file>: every shader compiled, program linked, program used and draw made, in order, written to the
+ // file as the page makes them — with each program's sources — so a GPU process that dies mid-frame leaves the call it died on as
+ // the last line. Lines arrive through the console because the page may not live to be asked.
+ const GL_TRACE = process.env.ESTELLA_VERIFY_GL_TRACE || '';
+ if (GL_TRACE) writeFileSync(GL_TRACE, '');
onRendererConsole(win.webContents, (msg) => {
+ if (GL_TRACE && msg.startsWith('GLTRACE ')) { appendFileSync(GL_TRACE, msg.slice(8) + '\n'); return; }
// `webgpu` spelled out: "webgl" does not match it, so the second backend's
// boot — including which adapter served it — was the one thing never shown.
if (/error|fail|unwind|exception|webgl|webgpu|adapter|recovery|placeholder/i.test(msg)) console.log('[renderer]', msg.slice(0, 240));
diff --git a/tools/shader-compile-probe.mjs b/tools/shader-compile-probe.mjs
new file mode 100644
index 000000000..425755823
--- /dev/null
+++ b/tools/shader-compile-probe.mjs
@@ -0,0 +1,49 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file shader-compile-probe.mjs — does this GLSL pair compile and link on THIS machine's real WebGL2 (ANGLE)?
+ *
+ * npx electron tools/shader-compile-probe.mjs <vertex.glsl> <fragment.glsl>
+ *
+ * Prints one JSON line: { ok, vertexLog, fragmentLog, linkLog, contextLost, gpuCrashed }. A shader that kills the
+ * GPU process (on Windows, a D3D compiler that recurses past its stack on what ANGLE translated) reports
+ * gpuCrashed instead of hanging the caller. A hidden window, like the render host's: nothing is shown.
+ * The pair is compiled alone, so a crash names the shader and not the frame that happened to ask for it.
+ */
+import { app, BrowserWindow } from 'electron';
+import { readFileSync } from 'node:fs';
+
+const [vertexPath, fragmentPath] = process.argv.slice(-2);
+const vertex = readFileSync(vertexPath, 'utf8');
+const fragment = readFileSync(fragmentPath, 'utf8');
+
+let gpuCrashed = false;
+app.on('child-process-gone', (_e, details) => { if (details.type === 'GPU') gpuCrashed = true; });
+
+app.whenReady().then(async () => {
+ const win = new BrowserWindow({ show: false, width: 64, height: 64 });
+ await win.loadURL('data:text/html,<canvas id=c width=8 height=8></canvas>');
+ const code = `(async () => {
+ const gl = document.getElementById('c').getContext('webgl2');
+ if (!gl) return { ok: false, error: 'no webgl2' };
+ const make = (type, src) => { const s = gl.createShader(type); gl.shaderSource(s, src); gl.compileShader(s); return s; };
+ const vs = make(gl.VERTEX_SHADER, ${JSON.stringify(vertex)});
+ const fs = make(gl.FRAGMENT_SHADER, ${JSON.stringify(fragment)});
+ const p = gl.createProgram();
+ gl.attachShader(p, vs); gl.attachShader(p, fs); gl.linkProgram(p);
+ const ok = !!gl.getProgramParameter(p, gl.LINK_STATUS);
+ return { ok, vertexLog: gl.getShaderInfoLog(vs), fragmentLog: gl.getShaderInfoLog(fs), linkLog: gl.getProgramInfoLog(p),
+ contextLost: gl.isContextLost() };
+ })()`;
+ let result;
+ try {
+ result = await Promise.race([
+ win.webContents.executeJavaScript(code, true),
+ new Promise((resolve) => setTimeout(() => resolve({ ok: false, error: 'timeout' }), 60000)),
+ ]);
+ } catch (e) {
+ result = { ok: false, error: String(e) };
+ }
+ console.log(JSON.stringify({ ...result, gpuCrashed }));
+ app.exit(0);
+});