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.

feat(renderer): a prepared cell knows which shader variants it will need, before it has entities

esengine730ae73d43d7
diff --git a/bench/residency/heavy.mjs b/bench/residency/heavy.mjs
index d338d7036..690c8e47c 100755
--- a/bench/residency/heavy.mjs
+++ b/bench/residency/heavy.mjs
@@ -222,6 +222,13 @@ function main() {
// bookkeeping shows in the first, first visibility in the second.
['blind', [{ do: 'step', frames: 30 }, { do: 'tap', key: 'Digit3', frames: 10 },
profile('published', 'Digit1'), profile('revealed', 'Digit4')]],
+ // Does a PREPARED cell know what a published one needs? Both derivations
+ // run on the same cell and their key SETS are compared — a count that
+ // matched by luck would not be an equivalence.
+ ['equivalence', [{ do: 'step', frames: 30 }, { do: 'tap', key: 'Digit3', frames: 10 },
+ profile('published', 'Digit1'),
+ { do: 'prewarm', as: 'document', cell: CELL_NAME, from: 'document' },
+ { do: 'prewarm', as: 'entities', cell: CELL_NAME }]],
// The same walk, with the programs readied while the camera is still
// away. If first visibility then costs what a warm frame costs, the
// hitch was the compile and readying it early is where it belongs.
@@ -229,6 +236,13 @@ function main() {
profile('published', 'Digit1'),
{ do: 'prewarm', as: 'ready', cell: CELL_NAME },
profile('revealed', 'Digit4')]],
+ // The real shape: readied while the cell is only PREPARED, from its own
+ // document, before a single entity of it exists. Then demanded, which on
+ // this path publishes and becomes visible in the same frame.
+ ['readied', [{ do: 'step', frames: 30 },
+ { do: 'arrive', as: 'primed', key: 'Digit2' },
+ { do: 'prewarm', as: 'ready', cell: CELL_NAME, from: 'document' },
+ profile('arrival', 'Digit1')]],
];
for (const [arm, steps] of arms) {
@@ -236,12 +250,26 @@ function main() {
for (const [as, { frames, delivery }] of runs) {
report(`${arm}${runs.size > 1 ? `/${as}` : ''}`, frames, delivery);
}
- const ready = prewarmed.get(arm);
- if (ready) {
- console.log(`\n readying ${arm}'s programs early took ${ready.ms.toFixed(2)} ms`
+ for (const [as, ready] of prewarmed.get(arm) ?? []) {
+ console.log(`\n readying ${arm}/${as} took ${ready.ms.toFixed(2)} ms`
+ ` — ${ready.compiles} compile(s) of ${ready.uniqueKeys} unique key(s)`
- + ` over ${ready.asks} ask(s) for ${ready.entities} entit(ies);`
- + ` ${ready.materialCompiles} material compile(s) of ${ready.materialAsks} ask(s)`);
+ + ` over ${ready.asks} ask(s) for ${ready.entities} renderable(s);`
+ + ` ${ready.materialCompiles} material compile(s) of ${ready.materialAsks} ask(s)`
+ + ` keys ${keySet(ready)}`);
+ }
+ const both = prewarmed.get(arm);
+ if (both?.has('document') && both.has('entities')) {
+ const doc = both.get('document');
+ const live = both.get('entities');
+ const same = doc.keysLo === live.keysLo && doc.keysHi === live.keysHi;
+ failedTotal += same ? 0 : 1;
+ console.log(`\n ${same ? '✓' : '✗'} what a PREPARED cell knows it will need equals`
+ + ` what its published entities ask for`
+ + ` — ${keySet(doc)} from the document, ${keySet(live)} from the world`);
+ const materials = doc.materialAsks === live.materialAsks;
+ failedTotal += materials ? 0 : 1;
+ console.log(` ${materials ? '✓' : '✗'} and the material-owned path is enumerated the`
+ + ` same both ways — ${doc.materialAsks} against ${live.materialAsks} ask(s)`);
}
}
console.log('');
@@ -269,7 +297,10 @@ function drive(out, name, steps) {
for (const line of (run.stdout || '').split('\n')) {
const ready = /^prewarm ([^:]+): (.*)$/.exec(line);
if (ready) {
- try { prewarmed.set(name, JSON.parse(ready[2])); } catch { /* partial */ }
+ try {
+ if (!prewarmed.has(name)) prewarmed.set(name, new Map());
+ prewarmed.get(name).set(ready[1], JSON.parse(ready[2]));
+ } catch { /* partial */ }
continue;
}
const match = /^(profile|delivery) ([^:]+): /.exec(line);
@@ -293,6 +324,16 @@ function drive(out, name, steps) {
return runs;
}
+/**
+ * What may be left unnamed before an instrument is not closed.
+ *
+ * PER FRAME for the frame accounting, because the residual IS the per-frame cost
+ * outside every system accumulated over the window — a fixed budget would pass a
+ * short window and fail a long one for the same engine.
+ */
+const RESIDUAL_MS = 0.6;
+const RESIDUAL_MS_PER_FRAME = 0.15;
+
function report(arm, frames, delivery) {
console.log(`\n${'='.repeat(78)}\nheavy cell, ${arm.toUpperCase()} — `
@@ -372,13 +413,16 @@ function report(arm, frames, delivery) {
console.log(' What demand pays whatever prefetch did, and it is NOT all of what demand pays:');
printTree(half(false), ' ');
const published = sum(half(false));
- const witness = arm === 'hit'
+ // Decided by the STREAMER's verdict, not the arm's name: a hit publishes
+ // inside the frame that asked, so wall time there spans the whole frame.
+ // Keying it on the arm made a third hitting arm read the wrong clock.
+ const witness = v.outcome === 'hit'
? { ms: sceneExcess, what: "the frame profiler's `scene` domain" }
: { ms: v.publishMs, what: 'publish → resident wall time' };
console.log(` ${'= accounted'.padEnd(22)}${published.toFixed(2).padStart(7)} ms`);
console.log(` ${'against'.padEnd(22)}${witness.ms.toFixed(2).padStart(7)} ms`
+ ` from ${witness.what} (${pct(published, witness.ms)})`);
- if (arm === 'hit') {
+ if (v.outcome === 'hit') {
console.log(` ${'(publish → resident'.padEnd(22)}${v.publishMs.toFixed(2).padStart(7)} ms`
+ ` wall, which on a hit spans the whole frame — not the transaction.)`);
}
@@ -402,9 +446,10 @@ function report(arm, frames, delivery) {
+ `parent, ${deepest.name} — reported, not a criterion: sub-phases partition their `
+ `parent by construction.)`);
}
- check(prepared >= v.prepareMs * 0.95,
+ check(v.prepareMs - prepared <= RESIDUAL_MS,
'and so is the preparation prefetch hides',
- `${pct(prepared, v.prepareMs)} of ${v.prepareMs.toFixed(2)} ms accounted`);
+ `${(v.prepareMs - prepared).toFixed(2)} ms unnamed of ${v.prepareMs.toFixed(2)} ms `
+ + `(${pct(prepared, v.prepareMs)})`);
}
console.log(`\n realization — ECS-visible → actually drawn. Steady state ${baseline.toFixed(2)} ms/frame, `
@@ -455,12 +500,17 @@ function report(arm, frames, delivery) {
realization(window, frames[arrivalAt]);
console.log('');
- check(window.length > 0 && systemExcess >= wallExcess * 0.95,
- 'and what the arrival ADDS to those frames is explained by the systems that ran',
- `${pct(systemExcess, wallExcess)} of ${wallExcess.toFixed(2)} ms of excess over `
- + `${window.length} frames (raw: ${pct(accounted, wall)} of ${wall.toFixed(2)} ms, `
- + `which carries ${((baseline - baselineSystems) * window.length).toFixed(2)} ms of `
- + `per-frame overhead outside every system)`);
+ // The RESIDUAL, not the ratio: at an excess of 2.7 ms the same 0.2 ms of
+ // per-frame overhead reads as 93%, so a ratio would measure how cheap the
+ // arrival was. A truncated breakdown still fails this, leaving 3.6 ms.
+ const residual = wallExcess - systemExcess;
+ if (arrived) {
+ check(residual <= RESIDUAL_MS_PER_FRAME * window.length,
+ 'and what the arrival ADDS to those frames is explained by the systems that ran',
+ `${residual.toFixed(2)} ms unnamed of ${wallExcess.toFixed(2)} ms of excess over `
+ + `${window.length} frames, against ${(RESIDUAL_MS_PER_FRAME * window.length).toFixed(2)}`
+ + ` ms of known per-frame overhead (${pct(systemExcess, wallExcess)})`);
+ }
const first = Object.values(delivery ?? {})[0];
const publicationCost = first
@@ -482,11 +532,13 @@ function report(arm, frames, delivery) {
const HEADROOM = 1000 / 60 / 2;
const spike = firstVisibleFrameCost - baseline;
const fits = spike <= HEADROOM;
- console.log(` ${fits ? '✓' : '✗'} BUDGET — a heavy arrival leaves the game its half of the frame`
- + ` — ${spike.toFixed(2)} ms of arrival work against ${HEADROOM.toFixed(2)} ms of headroom`);
- if (!fits) failed++;
+ console.log('');
+ // Through `check`: this verdict was incrementing a tally the exit code does
+ // not read, so a run that printed the violation still exited 0.
+ check(fits, 'BUDGET — a heavy arrival leaves the game its half of the frame',
+ `${spike.toFixed(2)} ms of arrival work against ${HEADROOM.toFixed(2)} ms of headroom`);
- void failed;
+ void failed; // every verdict goes through `check`
const spikes = frames.map((f, i) => ({ i, f }))
.filter(({ f }) => f.ms > baseline + 4)
.sort((a, b) => b.f.ms - a.f.ms).slice(0, 6);
@@ -659,6 +711,16 @@ function realization(window, arrival) {
}
}
+/** The variant keys a prewarm derived, as a set a reader can compare by eye. */
+function keySet(r) {
+ const keys = [];
+ for (let i = 0; i < 32; i++) {
+ if (r.keysLo & (1 << i)) keys.push(i);
+ if (r.keysHi & (1 << i)) keys.push(i + 32);
+ }
+ return `{${keys.join(', ')}}`;
+}
+
/** What one frame cost, by the domain that owns each system. */
function byDomain(frame) {
return new Map(Object.entries(frame.domains ?? {}));
diff --git a/pipeline/src/runtime/gameHost.ts b/pipeline/src/runtime/gameHost.ts
index ee5eb3b3d..05cfc7d63 100644
--- a/pipeline/src/runtime/gameHost.ts
+++ b/pipeline/src/runtime/gameHost.ts
@@ -141,6 +141,17 @@ async function boot(): Promise<void> {
if (headless) {
let statsOn = false;
+ /** Seven words out: five counts and the key SET, which is what an equality
+ * claim between two derivations needs. */
+ const readPrewarm = (heap: Uint32Array, ptr: number): Record<string, number> => {
+ const o = heap.subarray(ptr >> 2, (ptr >> 2) + 7);
+ return {
+ asks: o[0], compiles: o[1], uniqueKeys: o[2],
+ materialAsks: o[3], materialCompiles: o[4],
+ keysLo: o[5], keysHi: o[6],
+ };
+ };
+
/**
* Ready the shader programs a resident cell's meshes will be asked for,
* drawing none of them. Attached only where the engine answers it.
@@ -160,7 +171,7 @@ async function boot(): Promise<void> {
outPtr: number): void;
};
const entityPtr = m._malloc(entities.length * 4);
- const outPtr = m._malloc(5 * 4);
+ const outPtr = m._malloc(7 * 4);
try {
m.HEAPU32.set(entities, entityPtr >> 2);
// Around the call ALONE: reading the counts back is this probe's cost,
@@ -169,18 +180,58 @@ async function boot(): Promise<void> {
m.engine_prewarmMeshVariants(app.world.getCppRegistry(), entityPtr, entities.length,
outPtr);
const ms = performance.now() - began;
- const out = m.HEAPU32.subarray(outPtr >> 2, (outPtr >> 2) + 5);
- return {
- ms, entities: entities.length,
- asks: out[0], compiles: out[1], uniqueKeys: out[2],
- materialAsks: out[3], materialCompiles: out[4],
- };
+ return { ms, entities: entities.length, ...readPrewarm(m.HEAPU32, outPtr) };
} finally {
m._free(entityPtr);
m._free(outPtr);
}
};
+ /**
+ * The same readiness from the cell's DOCUMENT and the assets its preparation
+ * decoded — no entity is consulted. Whether those facts SUFFICE is a claim
+ * about the two derivations being equal, not about this call succeeding.
+ */
+ const prewarmMeshVariantsFromDocument = async (cell: string): Promise<Record<string, number>> => {
+ const found = worlds.flatMap((w) => w.cells).find((c) => c.name === cell);
+ if (!found) throw new Error(`[estella] no cooked cell "${cell}"`);
+ const doc = (await (await fetch(`./${found.path}`)).json()) as SceneData;
+ const assets = app.getResource(Assets);
+ // The same channel preparation loads through, so the handles are the ones
+ // it already acquired rather than a second decode.
+ const resolved = await assets.preloadSceneAssets(doc);
+ assets.resolveSceneAssetPaths(doc, resolved);
+ const rows: number[] = [];
+ for (const entity of doc.entities) {
+ const parts = (entity as { components?: Array<{ type: string; data: Record<string, unknown> }> }).components;
+ const renderer = parts?.find((c) => c.type === 'MeshRenderer');
+ if (!renderer) continue;
+ const skin = parts?.find((c) => c.type === 'MeshSkin');
+ const joints = (skin?.data.joints as unknown[] | undefined)?.length ?? 0;
+ rows.push(Number(renderer.data.mesh) || 0, renderer.data.lit ? 1 : 0,
+ Number(renderer.data.normalMap) || 0, joints,
+ Number(renderer.data.material) || 0);
+ }
+ const m = module as unknown as {
+ _malloc(n: number): number;
+ _free(p: number): void;
+ HEAPU32: Uint32Array;
+ engine_prewarmMeshVariantsFromDocument(rowsPtr: number, count: number, outPtr: number): void;
+ };
+ const rowsPtr = m._malloc(rows.length * 4);
+ const outPtr = m._malloc(7 * 4);
+ try {
+ m.HEAPU32.set(rows, rowsPtr >> 2);
+ const began = performance.now();
+ m.engine_prewarmMeshVariantsFromDocument(rowsPtr, rows.length / 5, outPtr);
+ const ms = performance.now() - began;
+ return { ms, entities: rows.length / 5, ...readPrewarm(m.HEAPU32, outPtr) };
+ } finally {
+ m._free(rowsPtr);
+ m._free(outPtr);
+ }
+ };
+
const cooked: Record<string, unknown> = {
capture(): { width: number; height: number; rgba: Uint8Array } {
const w = canvas.width, h = canvas.height;
@@ -581,6 +632,7 @@ async function boot(): Promise<void> {
if (typeof (module as unknown as Record<string, unknown>).engine_prewarmMeshVariants
=== 'function') {
cooked.prewarmMeshVariants = prewarmMeshVariants;
+ cooked.prewarmMeshVariantsFromDocument = prewarmMeshVariantsFromDocument;
}
(window as unknown as { __estellaCooked?: unknown }).__estellaCooked = cooked;
}
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index 83ff6df8b..edee200ca 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -739,17 +739,32 @@ std::string engine_getCpuScopes() {
}
#ifdef ES_ENABLE_TEST_PROBES
-void engine_prewarmMeshVariants(ecs::Registry& registry, u32 entitiesPtr, u32 count, u32 outPtr) {
- auto* out = reinterpret_cast<u32*>(static_cast<uintptr_t>(outPtr));
- for (u32 i = 0; i < 5; ++i) out[i] = 0;
- if (!g_initialized || !g_renderFrame) return;
- const auto* entities = reinterpret_cast<const Entity*>(static_cast<uintptr_t>(entitiesPtr));
- const RenderPrewarmResult r = g_renderFrame->prewarmPrograms(registry, entities, count);
+/** Seven words: five counts and the 64-bit key set, which is what an equality
+ * claim between two derivations needs. */
+static void writePrewarm(u32* out, const RenderPrewarmResult& r) {
out[0] = r.asks;
out[1] = r.compiles;
out[2] = r.uniqueKeys;
out[3] = r.materialAsks;
out[4] = r.materialCompiles;
+ out[5] = static_cast<u32>(r.keys & 0xFFFFFFFFull);
+ out[6] = static_cast<u32>(r.keys >> 32);
+}
+
+void engine_prewarmMeshVariants(ecs::Registry& registry, u32 entitiesPtr, u32 count, u32 outPtr) {
+ auto* out = reinterpret_cast<u32*>(static_cast<uintptr_t>(outPtr));
+ for (u32 i = 0; i < 7; ++i) out[i] = 0;
+ if (!g_initialized || !g_renderFrame) return;
+ const auto* entities = reinterpret_cast<const Entity*>(static_cast<uintptr_t>(entitiesPtr));
+ writePrewarm(out, g_renderFrame->prewarmPrograms(registry, entities, count));
+}
+
+void engine_prewarmMeshVariantsFromDocument(u32 rowsPtr, u32 count, u32 outPtr) {
+ auto* out = reinterpret_cast<u32*>(static_cast<uintptr_t>(outPtr));
+ for (u32 i = 0; i < 7; ++i) out[i] = 0;
+ if (!g_initialized || !g_renderFrame) return;
+ const auto* rows = reinterpret_cast<const MeshDocumentRecord*>(static_cast<uintptr_t>(rowsPtr));
+ writePrewarm(out, g_renderFrame->prewarmDocument(rows, count));
}
#endif
diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hpp
index a9411f536..5c89be248 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -147,6 +147,10 @@ std::string engine_getCpuScopes();
* to @p outPtr; JSON here would put an allocation inside the measurement.
*/
void engine_prewarmMeshVariants(ecs::Registry& registry, u32 entitiesPtr, u32 count, u32 outPtr);
+
+/** @brief The same, from a prepared cell's own description — five words per
+ * renderable at @p rowsPtr, and no entity of it need exist. */
+void engine_prewarmMeshVariantsFromDocument(u32 rowsPtr, u32 count, u32 outPtr);
#endif
std::string engine_getCounters();
std::string engine_getGpuScopes();
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 8670a3d5f..f0a11056c 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -720,6 +720,8 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("engine_getCpuScopes", &esengine::engine_getCpuScopes);
#ifdef ES_ENABLE_TEST_PROBES
emscripten::function("engine_prewarmMeshVariants", &esengine::engine_prewarmMeshVariants);
+ emscripten::function("engine_prewarmMeshVariantsFromDocument",
+ &esengine::engine_prewarmMeshVariantsFromDocument);
#endif
emscripten::function("engine_getCounters", &esengine::engine_getCounters);
emscripten::function("engine_getGpuScopes", &esengine::engine_getGpuScopes);
diff --git a/src/esengine/renderer/RenderTypePlugin.hpp b/src/esengine/renderer/RenderTypePlugin.hpp
index 7c9c0dc32..5e1217e18 100644
--- a/src/esengine/renderer/RenderTypePlugin.hpp
+++ b/src/esengine/renderer/RenderTypePlugin.hpp
@@ -105,6 +105,32 @@ inline CameraView computeCameraView(const glm::mat4& viewProjection) {
return view;
}
+/**
+ * @brief What a renderable's program key is made of, with no say in where the
+ * facts came from — a live entity's components, or a PREPARED cell's
+ * document. One combination, so the two can be shown to agree.
+ */
+/**
+ * @brief One renderable as a PREPARED cell knows it: document fields plus the
+ * handles its preparation decoded. Five words, so the boundary that
+ * carries it needs no encoding.
+ */
+struct MeshDocumentRecord {
+ u32 meshHandle = 0;
+ u32 lit = 0;
+ u32 normalMapHandle = 0;
+ u32 jointCount = 0;
+ u32 materialId = 0;
+};
+
+struct MeshProgramFacts {
+ bool hasNormals = false;
+ bool lit = false;
+ u32 normalTextureId = 0;
+ bool skinned = false;
+ u32 materialId = 0;
+};
+
/** @brief What readying a set of renderables' programs found. Counts, not JSON:
* this crosses no boundary and pays for no encoding. */
struct RenderPrewarmResult {
@@ -114,6 +140,8 @@ struct RenderPrewarmResult {
u32 uniqueKeys = 0;
u32 materialAsks = 0;
u32 materialCompiles = 0;
+ /** Which keys, not how many: an equality claim needs the set. 64 variants. */
+ u64 keys = 0;
RenderPrewarmResult& operator+=(const RenderPrewarmResult& other) {
asks += other.asks;
@@ -121,6 +149,7 @@ struct RenderPrewarmResult {
uniqueKeys += other.uniqueKeys;
materialAsks += other.materialAsks;
materialCompiles += other.materialCompiles;
+ keys |= other.keys;
return *this;
}
};
@@ -327,6 +356,20 @@ public:
return {};
}
+ /**
+ * @brief The same readiness, asked of a PREPARED cell's own description.
+ *
+ * @details The second fact source. What it derives must equal what `prewarm`
+ * derives from the live entities, which is a claim a criterion holds
+ * rather than a comment.
+ */
+ virtual RenderPrewarmResult prewarmDocument(RenderFrameContext& ctx,
+ const MeshDocumentRecord* rows, u32 count,
+ bool shadowPasses) {
+ (void)ctx; (void)rows; (void)count; (void)shadowPasses;
+ return {};
+ }
+
/**
* @brief What this plugin's collect is called in a frame profile.
*
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 6d2a7a006..665607fb3 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -1590,6 +1590,14 @@ RenderPrewarmResult RenderFrame::prewarmPrograms(ecs::Registry& registry,
return out;
}
+RenderPrewarmResult RenderFrame::prewarmDocument(const MeshDocumentRecord* rows, u32 count) {
+ auto ctx = makeContext();
+ const bool shadowPasses = !shadow_casters_.empty();
+ RenderPrewarmResult out;
+ for (auto& plugin : plugins_) out += plugin->prewarmDocument(ctx, rows, count, shadowPasses);
+ return out;
+}
+
void RenderFrame::collectAll(ecs::Registry& registry) {
ES_PROFILE_SCOPE("render.collect");
// Split because "collect is expensive" names no mechanism: planning shadows,
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index 2c747fa58..33eb1a06a 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -414,6 +414,10 @@ public:
* WASM adapter that lets a driver call it from outside.
*/
RenderPrewarmResult prewarmPrograms(ecs::Registry& registry, const Entity* entities, u32 count);
+
+ /** @brief The same readiness, from a prepared cell's own description — no
+ * entity of it need exist. */
+ RenderPrewarmResult prewarmDocument(const MeshDocumentRecord* rows, u32 count);
void collectAll(ecs::Registry& registry);
/**
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index a7949be7b..4a33bfa50 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -46,27 +46,53 @@ u32 mulColor(u32 a, u32 b) {
*/
/**
* @brief How many joints this entity would be posed by; 0 when it draws unskinned.
+ * Separated from posing: the key needs the ANSWER, not the matrices, and a
+ * re-derived one would disagree with the predicate that draws.
+ */
+/**
+ * @brief Whether a mesh posed by @p joints joints draws skinned.
*
- * @details Separated from posing because the variant key needs the ANSWER and not
- * the matrices: a caller that re-derived "is this skinned" would be a
- * second predicate free to disagree with the one that draws.
+ * @details Takes the joint count from wherever the caller found it: a live
+ * `MeshSkin`, or a prepared document with no entities yet.
*/
-u32 skinJointCount(ecs::Registry& registry, Entity entity, const Mesh& mesh, bool& warnedBones) {
- if (!mesh.isSkinned()) return 0;
- const auto* skin = registry.tryGet<ecs::MeshSkin>(entity);
- if (!skin || skin->joints.size() != mesh.inverseBind.size()) return 0;
+u32 skinnedBy(const Mesh& mesh, usize joints, bool& warnedBones) {
+ if (!mesh.isSkinned() || joints != mesh.inverseBind.size()) return 0;
// Posing the first MESH_MAX_BONES leaves the rest indexing a matrix this
// draw never uploads — the wrong-matrix read the count check above already
// rejects, so it takes the same answer. For files no importer here wrote.
- if (skin->joints.size() > MESH_MAX_BONES) {
+ if (joints > MESH_MAX_BONES) {
if (!warnedBones) {
warnedBones = true;
ES_LOG_WARN("MeshSkin: {} joints exceeds the {} one draw can be posed by; drawing the"
- " bind pose", skin->joints.size(), MESH_MAX_BONES);
+ " bind pose", joints, MESH_MAX_BONES);
}
return 0;
}
- return static_cast<u32>(skin->joints.size());
+ return static_cast<u32>(joints);
+}
+
+u32 skinJointCount(ecs::Registry& registry, Entity entity, const Mesh& mesh, bool& warnedBones) {
+ const auto* skin = registry.tryGet<ecs::MeshSkin>(entity);
+ return skin ? skinnedBy(mesh, skin->joints.size(), warnedBones) : 0;
+}
+
+/** @brief The facts a PREPARED cell answers with: its document's fields, and the
+ * assets its preparation already decoded. No entity is consulted. */
+MeshProgramFacts meshFactsFromDocument(RenderFrameContext& ctx, const MeshDocumentRecord& row,
+ bool& warnedBones) {
+ MeshProgramFacts facts;
+ const Mesh* resident = row.meshHandle != 0
+ ? ctx.resources.getMesh(resource::MeshHandle(row.meshHandle)) : nullptr;
+ facts.hasNormals = resident && resident->hasNormals;
+ facts.lit = row.lit != 0;
+ facts.materialId = row.materialId;
+ if (row.normalMapHandle != 0 && facts.lit && facts.hasNormals) {
+ if (Texture* tex = ctx.resources.getTexture(resource::TextureHandle(row.normalMapHandle))) {
+ facts.normalTextureId = tex->getId();
+ }
+ }
+ facts.skinned = resident && skinnedBy(*resident, row.jointCount, warnedBones) > 0;
+ return facts;
}
u32 skinPose(ecs::Registry& registry, Entity entity, const Mesh& mesh,
@@ -189,21 +215,37 @@ struct MeshDrawKeys {
u32 normalTextureId = 0;
};
-MeshDrawKeys meshDrawFor(RenderFrameContext& ctx, ecs::Registry& registry, Entity entity,
- const ecs::MeshRenderer& mesh, const Mesh* resident, bool shadowDepth,
- bool& warnedBones) {
- MeshDrawKeys out;
+u32 meshVariantFrom(const MeshProgramFacts& facts, bool envMapped, bool shadowDepth) {
+ return meshVariant(facts.hasNormals, facts.lit && !shadowDepth,
+ facts.normalTextureId != 0 && !shadowDepth, facts.skinned, shadowDepth,
+ envMapped);
+}
+
+/** @brief The facts a LIVE entity answers with: its components and its mesh. */
+MeshProgramFacts meshFactsFromEntity(RenderFrameContext& ctx, ecs::Registry& registry,
+ Entity entity, const ecs::MeshRenderer& mesh,
+ const Mesh* resident, bool& warnedBones) {
+ MeshProgramFacts facts;
+ facts.hasNormals = resident && resident->hasNormals;
+ facts.lit = mesh.lit;
+ facts.materialId = mesh.material;
// Only meaningful with normals to perturb AND a draw that takes light.
if (mesh.normalMap.isValid() && mesh.lit && resident && resident->hasNormals) {
if (Texture* tex = ctx.resources.getTexture(mesh.normalMap)) {
- out.normalTextureId = tex->getId();
+ facts.normalTextureId = tex->getId();
}
}
- const bool skinned = resident && skinJointCount(registry, entity, *resident, warnedBones) > 0;
- out.variant = meshVariant(resident && resident->hasNormals, mesh.lit && !shadowDepth,
- out.normalTextureId != 0 && !shadowDepth, skinned, shadowDepth,
- ctx.environment_texture_id != 0);
- return out;
+ facts.skinned = resident && skinJointCount(registry, entity, *resident, warnedBones) > 0;
+ return facts;
+}
+
+MeshDrawKeys meshDrawFor(RenderFrameContext& ctx, ecs::Registry& registry, Entity entity,
+ const ecs::MeshRenderer& mesh, const Mesh* resident, bool shadowDepth,
+ bool& warnedBones) {
+ const MeshProgramFacts facts =
+ meshFactsFromEntity(ctx, registry, entity, mesh, resident, warnedBones);
+ return { meshVariantFrom(facts, ctx.environment_texture_id != 0, shadowDepth),
+ facts.normalTextureId };
}
} // namespace
@@ -287,38 +329,31 @@ u32 MeshPlugin::meshProgram(RenderFrameContext& ctx, u32 variant) {
return mesh_programs_[variant];
}
-RenderPrewarmResult MeshPlugin::prewarm(RenderFrameContext& ctx, ecs::Registry& registry,
- const Entity* entities, u32 count, bool shadowPasses) {
+RenderPrewarmResult MeshPlugin::prewarmFacts(RenderFrameContext& ctx,
+ const MeshProgramFacts* facts, u32 count,
+ bool shadowPasses, bool residentGeometry) {
RenderPrewarmResult out;
- u64 seen = 0;
const u32 materialsBefore = ctx.materials ? ctx.materials->builtVariantCount() : 0;
+ const bool envMapped = ctx.environment_texture_id != 0;
for (u32 i = 0; i < count; ++i) {
- const Entity entity = entities[i];
- const auto* mesh = registry.tryGet<ecs::MeshRenderer>(entity);
- if (!mesh || !mesh->enabled) continue;
- if (mesh->indices.empty() && !mesh->mesh.isValid()) continue;
- const Mesh* resident = mesh->mesh.isValid() ? ctx.resources.getMesh(mesh->mesh) : nullptr;
// Both purposes when the scene draws depth too: the same renderable is
// asked for twice with different keys, and readying only the camera's
// leaves the first shadow map to pay for the other.
for (u32 pass = 0; pass < 2; ++pass) {
const bool shadowDepth = pass == 1;
- if (shadowDepth && (!shadowPasses || !resident)) continue;
- const u32 variant =
- meshDrawFor(ctx, registry, entity, *mesh, resident, shadowDepth,
- warned_bones_).variant;
+ if (shadowDepth && (!shadowPasses || !residentGeometry)) continue;
+ const u32 variant = meshVariantFrom(facts[i], envMapped, shadowDepth);
++out.asks;
- if ((seen & (1ull << variant)) == 0) { seen |= 1ull << variant; ++out.uniqueKeys; }
+ if ((out.keys & (1ull << variant)) == 0) { out.keys |= 1ull << variant; ++out.uniqueKeys; }
if (!mesh_compiled_[variant]) ++out.compiles;
meshProgram(ctx, variant);
}
// The second lazily-compiled path. A fixture without materials would let
// readiness look complete while a material-shaded world still hitched.
- if (mesh->material != 0 && ctx.materials && resident) {
+ if (facts[i].materialId != 0 && ctx.materials) {
++out.materialAsks;
- ctx.materials->meshProgram(mesh->material, ctx.resources, resident->hasNormals,
- skinJointCount(registry, entity, *resident, warned_bones_) > 0,
- ctx.environment_texture_id != 0);
+ ctx.materials->meshProgram(facts[i].materialId, ctx.resources, facts[i].hasNormals,
+ facts[i].skinned, envMapped);
}
}
if (ctx.materials) {
@@ -328,6 +363,41 @@ RenderPrewarmResult MeshPlugin::prewarm(RenderFrameContext& ctx, ecs::Registry&
return out;
}
+RenderPrewarmResult MeshPlugin::prewarmDocument(RenderFrameContext& ctx,
+ const MeshDocumentRecord* rows, u32 count,
+ bool shadowPasses) {
+ std::vector<MeshProgramFacts> facts;
+ facts.reserve(count);
+ bool anyResident = false;
+ for (u32 i = 0; i < count; ++i) {
+ if (rows[i].meshHandle == 0) continue;
+ anyResident = anyResident
+ || ctx.resources.getMesh(resource::MeshHandle(rows[i].meshHandle)) != nullptr;
+ facts.push_back(meshFactsFromDocument(ctx, rows[i], warned_bones_));
+ }
+ return prewarmFacts(ctx, facts.data(), static_cast<u32>(facts.size()), shadowPasses,
+ anyResident);
+}
+
+RenderPrewarmResult MeshPlugin::prewarm(RenderFrameContext& ctx, ecs::Registry& registry,
+ const Entity* entities, u32 count, bool shadowPasses) {
+ std::vector<MeshProgramFacts> facts;
+ facts.reserve(count);
+ bool anyResident = false;
+ for (u32 i = 0; i < count; ++i) {
+ const Entity entity = entities[i];
+ const auto* mesh = registry.tryGet<ecs::MeshRenderer>(entity);
+ if (!mesh || !mesh->enabled) continue;
+ if (mesh->indices.empty() && !mesh->mesh.isValid()) continue;
+ const Mesh* resident = mesh->mesh.isValid() ? ctx.resources.getMesh(mesh->mesh) : nullptr;
+ anyResident = anyResident || resident != nullptr;
+ facts.push_back(
+ meshFactsFromEntity(ctx, registry, entity, *mesh, resident, warned_bones_));
+ }
+ return prewarmFacts(ctx, facts.data(), static_cast<u32>(facts.size()), shadowPasses,
+ anyResident);
+}
+
void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
auto& registry = collect_ctx.registry;
auto& frustum = collect_ctx.frustum;
diff --git a/src/esengine/renderer/plugins/MeshPlugin.hpp b/src/esengine/renderer/plugins/MeshPlugin.hpp
index 142fcf7a1..ae5fd1d05 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.hpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.hpp
@@ -27,6 +27,12 @@ public:
void collect(RenderCollectContext& ctx) override;
RenderPrewarmResult prewarm(RenderFrameContext& ctx, ecs::Registry& registry,
const Entity* entities, u32 count, bool shadowPasses) override;
+ /** @brief Ready programs from facts already gathered — the door a PREPARED
+ * cell comes through, before any entity of it exists. */
+ RenderPrewarmResult prewarmFacts(RenderFrameContext& ctx, const MeshProgramFacts* facts,
+ u32 count, bool shadowPasses, bool residentGeometry);
+ RenderPrewarmResult prewarmDocument(RenderFrameContext& ctx, const MeshDocumentRecord* rows,
+ u32 count, bool shadowPasses) override;
const char* collectScope() const override { return "render.collect.mesh"; }
private:
diff --git a/tools/launchers/residency-run.mjs b/tools/launchers/residency-run.mjs
index 8d01d2625..f413d5541 100644
--- a/tools/launchers/residency-run.mjs
+++ b/tools/launchers/residency-run.mjs
@@ -243,10 +243,13 @@ async function main() {
// Absent capability is a FAILED run, never a quiet pass: a probe that was
// not built reads as "nothing needed compiling", which is the answer the
// experiment is trying to earn.
- const has = await exec('typeof window.__estellaCooked.prewarmMeshVariants === "function"');
+ const has = await exec('typeof window.__estellaCooked.prewarmMeshVariants === "function"'
+ + ' && typeof window.__estellaCooked.prewarmMeshVariantsFromDocument === "function"');
if (!has) { stop(); server.close(); return fail('this build has no prewarm probe', 2); }
- const r = await exec(`window.__estellaCooked.prewarmMeshVariants(${JSON.stringify(step.cell)})`);
- console.log(`prewarm ${step.as}: ${JSON.stringify(r)}`);
+ const call = step.from === 'document'
+ ? `window.__estellaCooked.prewarmMeshVariantsFromDocument(${JSON.stringify(step.cell)})`
+ : `window.__estellaCooked.prewarmMeshVariants(${JSON.stringify(step.cell)})`;
+ console.log(`prewarm ${step.as}: ${JSON.stringify(await exec(call))}`);
continue;
}
if (step.do === 'frames') {