Skip to content

armgit / 67.js

Public Imported from GitHub
0

3D engine that AI agents drive

Draw the hidden first frame without blocking on programs the driver is still building (Part of #ISSUE)

Nguyen Xuan Anec8397fbc8f4
diff --git a/changes/ISSUE-hero-jank.md b/changes/ISSUE-hero-jank.md
index 88695a51..42efa845 100644
--- a/changes/ISSUE-hero-jank.md
+++ b/changes/ISSUE-hero-jank.md
@@ -1 +1 @@
-- A renderer built with `deferProgramLink: true` links its shaders without freezing the page: await `renderer.programsReady()`; `shaderFeatureRepresentatives(parts)` picks the few parts that compile the program a whole scene needs, and `groupParts` builds each material key once (#ISSUE)
+- A renderer built with `deferProgramLink: true` links its shaders without freezing the page: await `renderer.programsReady()`; `shaderFeatureRepresentatives(parts)` picks the few parts that compile the program a whole scene needs, and `groupParts` builds each material key once; `await renderer.prepareFrame(frame)` then draws the first frame while the canvas is hidden without blocking on the post, liquid, occlusion and reversed-depth programs a first draw links (#ISSUE)
diff --git a/docs/gltf.md b/docs/gltf.md
index 1f7a6b43..a270050a 100644
--- a/docs/gltf.md
+++ b/docs/gltf.md
@@ -113,6 +113,7 @@ renderer.replaceParts(asset.parts);
```
`programsReady()` polls `KHR_parallel_shader_compile` and then finishes construction; a renderer made with `deferProgramLink` must not render before it resolves.
+`await renderer.prepareFrame(frame)` is the matching last step before a hidden renderer is shown: it draws `frame` once without freezing the page for the programs a first draw links (the post pass of a fog or sky frame, liquids, ambient occlusion, the reversed-depth copy). A draw that meets a program the driver is still building stops, the page waits in short timers, and the draw runs again until one completes; it resolves `true`. After `timeoutMilliseconds` (6000 by default) it draws the frame in one block and resolves `false`, so a slow driver costs a stall, never a hang. Start the next scene's `prepareFrame` while the current scene plays and begin the fade when it resolves.
Starting on `shaderFeatureRepresentatives` matters: a scene whose first parts lack a feature recompiles the program inside `replaceParts`, which blocks again.
## Animation and ownership
diff --git a/src/gl-program.js b/src/gl-program.js
index 1b0904a4..3473e516 100644
Binary files a/src/gl-program.js and b/src/gl-program.js differ
diff --git a/src/hero-lab/hero-loop.js b/src/hero-lab/hero-loop.js
index 70135391..e6707be1 100644
--- a/src/hero-lab/hero-loop.js
+++ b/src/hero-lab/hero-loop.js
@@ -93,13 +93,17 @@ function prepare(index, { immediately = false } = {}) {
await entry.permission;
if (entry.skipped) return;
const started = performance.now();
- entry.world = await buildFrom(download);
+ const world = await buildFrom(download);
await new Promise(resolve => setTimeout(resolve, 0));
- if (!entry.skipped) {
- const warmStarted = performance.now();
- entry.world.warm(flights[index].at(0));
- note('warmed', { scene: SCENES[index].id, ms: Math.round(performance.now() - warmStarted) });
+ // The world joins the loop only after its first draw has linked every program and allocated every target, so the fade never waits on the driver.
+ const warmStarted = performance.now();
+ const complete = entry.skipped ? true : await world.warm(flights[index].at(0));
+ note('warmed', { scene: SCENES[index].id, ms: Math.round(performance.now() - warmStarted), complete });
+ if (entry.skipped) {
+ world.dispose();
+ return;
}
+ entry.world = world;
note('built', { scene: SCENES[index].id, ms: Math.round(performance.now() - started) });
loopState.peakWorlds = Math.max(loopState.peakWorlds, loopState.worldsAlive());
})
diff --git a/src/hero-lab/loop/world.js b/src/hero-lab/loop/world.js
index 5c17c985..d3fbfdce 100644
--- a/src/hero-lab/loop/world.js
+++ b/src/hero-lab/loop/world.js
@@ -167,9 +167,10 @@ export async function buildWorld(download, canvas, overrides = {}) {
const drawn = effects ? effects.apply(renderer, seconds, frame) : frame;
renderer.render({ ...drawn, eye: camera.eye, target: camera.target, fov: camera.fov, time: seconds });
},
- // One draw while the canvas is still hidden: shaders compile and textures upload now, not on the first frame of a fade.
+ // The first draw while the canvas is still hidden: programs link on the driver's threads and targets allocate now, not on the first frame of a fade.
+ // Resolves false when the driver took longer than the timeout and the draw ran in one block.
warm(camera) {
- renderer.render({ ...frame, eye: camera.eye, target: camera.target, fov: camera.fov, time: 0 });
+ return renderer.prepareFrame({ ...frame, eye: camera.eye, target: camera.target, fov: camera.fov, time: 0 });
},
resize: () => renderer.resize(),
dispose() {
diff --git a/src/liquid-renderer.js b/src/liquid-renderer.js
index a4d81879..01a8c88a 100644
--- a/src/liquid-renderer.js
+++ b/src/liquid-renderer.js
@@ -1,4 +1,4 @@
-import { startProgram, finishProgram } from './gl-program.js';
+import { compileProgram } from './gl-program.js';
import { resolveLiquidOptics } from './liquid-optics.js';
// The renderer's liquid and foam pass, kept apart from renderer.js so a scene without liquid or foam does not carry it.
@@ -17,7 +17,7 @@ const LIQUID_UNIFORMS = [
function ensureLiquidProgram(renderer, environmentSpecularUnit, vertexSource, fragmentSource) {
if (renderer.liquidProgram) return;
const context = renderer.context;
- renderer.liquidProgram = finishProgram(context, startProgram(context, vertexSource, renderer.withViewTransform(fragmentSource, 'liquid')));
+ renderer.liquidProgram = compileProgram(context, vertexSource, renderer.withViewTransform(fragmentSource, 'liquid'));
renderer.liquidUniforms = Object.fromEntries(LIQUID_UNIFORMS.map(name => [name, context.getUniformLocation(renderer.liquidProgram, name)]));
context.useProgram(renderer.liquidProgram);
context.uniform1i(renderer.liquidUniforms.skinInfluences, 6);
diff --git a/src/renderer.js b/src/renderer.js
index cf23ac2a..6c0756d6 100644
--- a/src/renderer.js
+++ b/src/renderer.js
@@ -2,7 +2,7 @@ import { materialTags } from './shader-registry.js';
import { mat4, mat3 } from 'gl-matrix';
import { SPLAT_UNITS, requireSplatSupport, layerTextureSupport, LIGHT_SHADING_FEATURE, SHADING_MODES, LIGHT_SHADING_MAXIMUM_SAMPLES, createVertexShader, vertexShader, liquidFragmentSource, createFragmentShader, liquidPassDrawer, depthFragmentShader, withDepthCode, benchmarkVertexShader, benchmarkFragmentShader, viewTransformShader, createDepthVertexShader } from './shaders.js';
import { postFragment, createPostFragment, POST_STEPS, POST_STEPS_WITH_OPTIONAL_CODE, skyFragment, bloomFragment } from './post.js';
-import { fullscreenVertex, startProgram, finishProgram, compileProgram } from './gl-program.js';
+import { fullscreenVertex, startProgram, finishProgram, compileProgram, ProgramNotReady, isLinkComplete, setPreparing } from './gl-program.js';
import { ambientOcclusionFragment } from './ambient-occlusion.js';
import { planRenderSize, estimateTextureBytes, estimateFrameBytes, memoryBudgetError } from './budget.js';
import { applyProjection } from './camera.js';
@@ -807,6 +807,37 @@ export class Renderer67 {
this.finishConstruction();
}
+ /**
+ * Draws `frame` once the way a real frame is drawn, but without freezing the page for programs the driver has not finished
+ * building (the post pass of a fog or sky frame, liquids, ambient occlusion, a reversed-depth copy). Each draw that meets one
+ * stops there; the driver's thread keeps building while this waits in short timers, then the draw runs again. The last
+ * draw is complete and leaves every program, target and texture that frame uses ready, so the next frame costs no more than
+ * any other. Call it while the canvas is hidden or another world is on screen. Past `timeoutMilliseconds` it draws the
+ * frame at once and resolves true when it never had to, false otherwise.
+ */
+ async prepareFrame(frame, { timeoutMilliseconds = 6000 } = {}) {
+ await this.programsReady();
+ const context = this.context;
+ const deadline = performance.now() + timeoutMilliseconds;
+ setPreparing(context, true);
+ try {
+ for (;;) {
+ try {
+ this.render(frame);
+ return true;
+ } catch (error) {
+ if (!(error instanceof ProgramNotReady)) throw error;
+ while (!isLinkComplete(context, error.program) && performance.now() < deadline) await new Promise(resolve => setTimeout(resolve, 8));
+ if (performance.now() >= deadline) break;
+ }
+ }
+ } finally {
+ setPreparing(context, false);
+ }
+ this.render(frame);
+ return false;
+ }
+
selectViewTransform(viewTransform, lookSource) {
if ((viewTransform !== 'aces' || lookSource) && !viewTransformShader.apply) throw new Error("viewTransform and look need their shader code: add import '@codepawlhq/67js/addons/view-transform-shader' (a recipe: await loadAgentSceneModules(recipe)).");
this.viewTransform = viewTransform;
diff --git a/tests/gl-program-prepare.test.js b/tests/gl-program-prepare.test.js
new file mode 100644
index 00000000..1caf5a66
--- /dev/null
+++ b/tests/gl-program-prepare.test.js
@@ -0,0 +1,66 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { compileProgram, finishProgram, isLinkComplete, ProgramNotReady, setPreparing } from '../src/gl-program.js';
+
+// A context whose programs report completion after a number of polls, as a driver building on its own threads does.
+function fakeContext({ pollsUntilComplete }) {
+ const polls = new Map();
+ let created = 0;
+ return {
+ created: () => created,
+ LINK_STATUS: 0x8b82,
+ COMPILE_STATUS: 0x8b81,
+ VERTEX_SHADER: 1,
+ FRAGMENT_SHADER: 2,
+ getExtension: () => ({ COMPLETION_STATUS_KHR: 0x91b1 }),
+ createProgram: () => ({ id: created++ }),
+ createShader: () => ({}),
+ shaderSource() {},
+ compileShader() {},
+ attachShader() {},
+ linkProgram() {},
+ getProgramParameter(program, parameter) {
+ if (parameter !== 0x91b1) return true;
+ polls.set(program, (polls.get(program) ?? 0) + 1);
+ return polls.get(program) > pollsUntilComplete;
+ },
+ getShaderParameter: () => true,
+ getShaderInfoLog: () => '',
+ getProgramInfoLog: () => '',
+ deleteShader() {},
+ deleteProgram() {},
+ isContextLost: () => false,
+ };
+}
+
+test('outside preparation a program is finished at once, even before the driver reports completion', () => {
+ const context = fakeContext({ pollsUntilComplete: 5 });
+ assert.doesNotThrow(() => compileProgram(context, 'vertex', 'fragment'));
+});
+
+test('while preparing, an unfinished program throws ProgramNotReady and is found again, not restarted', () => {
+ const context = fakeContext({ pollsUntilComplete: 2 });
+ setPreparing(context, true);
+ let program = null;
+ let attempts = 0;
+ while (!program) {
+ attempts++;
+ try {
+ program = compileProgram(context, 'vertex', 'fragment');
+ } catch (error) {
+ assert.ok(error instanceof ProgramNotReady);
+ assert.equal(isLinkComplete(context, error.program), false);
+ }
+ }
+ setPreparing(context, false);
+ assert.equal(context.created(), 1, 'the retry reused the started program');
+ assert.ok(attempts > 1);
+});
+
+test('a finished program is not blocked while preparing, and preparation ends cleanly', () => {
+ const context = fakeContext({ pollsUntilComplete: 0 });
+ setPreparing(context, true);
+ assert.doesNotThrow(() => finishProgram(context, { program: { id: 9 }, shaders: [] }));
+ setPreparing(context, false);
+ assert.doesNotThrow(() => finishProgram(context, { program: { id: 10 }, shaders: [] }));
+});