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.mdindex 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.mdindex 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 ownershipdiff --git a/src/gl-program.js b/src/gl-program.jsindex 1b0904a4..3473e516 100644Binary files a/src/gl-program.js and b/src/gl-program.js differdiff --git a/src/hero-lab/hero-loop.js b/src/hero-lab/hero-loop.jsindex 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.jsindex 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.jsindex 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.jsindex 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.jsnew file mode 100644index 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: [] }));+});