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): an offscreen preview is addressed by its handle, never entered

esengineed75d46766fe
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 3b87a3cdb..04d86eee0 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 113,
"beta": 91,
- "experimental": 1670,
+ "experimental": 1672,
"deprecated": 3
},
- "total": 1874,
+ "total": 1876,
"subsystems": [
{
"id": "ecs",
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 654163209..49ef20b12 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 84 beta · 1507 experimental · 3 deprecated
+Symbols: 113 public · 84 beta · 1509 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -7258,6 +7258,33 @@ runtime: string
skeletonField: string
```
+## SkeletalPreview — class @experimental
+```
+dispose: () => void
+height: number
+live: boolean
+render: (viewProjection: Float32Array) => Promise<ImageData | null>
+submit: (batch: SkeletalPreviewBatch) => boolean
+width: number
+static create: (module: unknown, w: number, h: number) => SkeletalPreview | null
+static new (core: SkeletalPreviewCore, id: number, width: number, height: number): SkeletalPreview
+static prototype: SkeletalPreview
+```
+
+## SkeletalPreviewBatch — interface @experimental
+```
+blendMode: number
+depth: number | undefined
+indexCount: number
+indices: Uint8Array<ArrayBufferLike>
+layer: number | undefined
+materialId: number | undefined
+textureId: number
+transform: Float32Array<ArrayBufferLike>
+vertexCount: number
+vertices: Uint8Array<ArrayBufferLike>
+```
+
## SliceBorder — interface @experimental
```
bottom: number
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 7196e63f0..48e6e87c3 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.native
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 89 beta · 1526 experimental · 3 deprecated
+Symbols: 113 public · 89 beta · 1528 experimental · 3 deprecated
## ABI_LAYOUT_HASH — const @experimental
```
@@ -7451,6 +7451,33 @@ runtime: string
skeletonField: string
```
+## SkeletalPreview — class @experimental
+```
+dispose: () => void
+height: number
+live: boolean
+render: (viewProjection: Float32Array) => Promise<ImageData | null>
+submit: (batch: SkeletalPreviewBatch) => boolean
+width: number
+static create: (module: unknown, w: number, h: number) => SkeletalPreview | null
+static new (core: SkeletalPreviewCore, id: number, width: number, height: number): SkeletalPreview
+static prototype: SkeletalPreview
+```
+
+## SkeletalPreviewBatch — interface @experimental
+```
+blendMode: number
+depth: number | undefined
+indexCount: number
+indices: Uint8Array<ArrayBufferLike>
+layer: number | undefined
+materialId: number | undefined
+textureId: number
+transform: Float32Array<ArrayBufferLike>
+vertexCount: number
+vertices: Uint8Array<ArrayBufferLike>
+```
+
## SliceBorder — interface @experimental
```
bottom: number
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 79b4f7ede..37c85f0d1 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/index.node
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 86 beta · 1506 experimental · 3 deprecated
+Symbols: 113 public · 86 beta · 1508 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -7253,6 +7253,33 @@ runtime: string
skeletonField: string
```
+## SkeletalPreview — class @experimental
+```
+dispose: () => void
+height: number
+live: boolean
+render: (viewProjection: Float32Array) => Promise<ImageData | null>
+submit: (batch: SkeletalPreviewBatch) => boolean
+width: number
+static create: (module: unknown, w: number, h: number) => SkeletalPreview | null
+static new (core: SkeletalPreviewCore, id: number, width: number, height: number): SkeletalPreview
+static prototype: SkeletalPreview
+```
+
+## SkeletalPreviewBatch — interface @experimental
+```
+blendMode: number
+depth: number | undefined
+indexCount: number
+indices: Uint8Array<ArrayBufferLike>
+layer: number | undefined
+materialId: number | undefined
+textureId: number
+transform: Float32Array<ArrayBufferLike>
+vertexCount: number
+vertices: Uint8Array<ArrayBufferLike>
+```
+
## SliceBorder — interface @experimental
```
bottom: number
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index c8c1a47ff..fb88f8568 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/minigame
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 84 beta · 1528 experimental · 3 deprecated
+Symbols: 113 public · 84 beta · 1530 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -7499,6 +7499,33 @@ runtime: string
skeletonField: string
```
+## SkeletalPreview — class @experimental
+```
+dispose: () => void
+height: number
+live: boolean
+render: (viewProjection: Float32Array) => Promise<ImageData | null>
+submit: (batch: SkeletalPreviewBatch) => boolean
+width: number
+static create: (module: unknown, w: number, h: number) => SkeletalPreview | null
+static new (core: SkeletalPreviewCore, id: number, width: number, height: number): SkeletalPreview
+static prototype: SkeletalPreview
+```
+
+## SkeletalPreviewBatch — interface @experimental
+```
+blendMode: number
+depth: number | undefined
+indexCount: number
+indices: Uint8Array<ArrayBufferLike>
+layer: number | undefined
+materialId: number | undefined
+textureId: number
+transform: Float32Array<ArrayBufferLike>
+vertexCount: number
+vertices: Uint8Array<ArrayBufferLike>
+```
+
## SliceBorder — interface @experimental
```
bottom: number
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 5bc83c751..37618985f 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -345,7 +345,9 @@ renderer_begin: (matrixPtr: number, targetHandle: number, clearFlags: number, r:
renderer_beginFrame: (elapsedSec: number) => void
renderer_captureFrame: ((w: number, h: number) => number) | undefined
renderer_captureNextFrame: () => void
+renderer_createSkeletalPreview: (w: number, h: number) => number
renderer_createTarget: (width: number, height: number, flags: number) => number
+renderer_destroySkeletalPreview: (preview: number) => void
renderer_diagnose: () => void
renderer_end: () => void
renderer_entityVisibleToCamera: ((registry: CppRegistry, entity: number, layer: number, minX: number, minY: number, maxX: number, maxY: number, outVisiblePtr: number) => void) | undefined
@@ -365,6 +367,10 @@ renderer_getPreviewPtr: () => number
renderer_getPreviewSize: () => number
renderer_getPreviewWidth: () => number
renderer_getSkeletal: (() => number) | undefined
+renderer_getSkeletalPreviewHeight: (preview: number) => number
+renderer_getSkeletalPreviewPtr: (preview: number) => number
+renderer_getSkeletalPreviewSize: (preview: number) => number
+renderer_getSkeletalPreviewWidth: (preview: number) => number
renderer_getSnapshotHeight: () => number
renderer_getSnapshotPtr: () => number
renderer_getSnapshotSize: () => number
@@ -379,10 +385,12 @@ renderer_hasCapturedData: () => boolean
renderer_init: (width: number, height: number) => void
renderer_pollFrameCapture: ((handle: number) => number) | undefined
renderer_pollPreviewReadback: () => number
+renderer_pollSkeletalPreview: (preview: number) => number
renderer_pollSnapshotReadback: () => number
renderer_releaseTarget: (handle: number) => void
renderer_renderMaterialPreview: (materialId: number, w: number, h: number) => void
renderer_renderMeshPreview: (meshId: number, w: number, h: number) => void
+renderer_renderSkeletalPreview: (preview: number, viewProjectionPtr: number) => number
renderer_replayToDrawCall: (drawCallIndex: number) => void
renderer_resize: (width: number, height: number) => void
renderer_setClearColor: (r: number, g: number, b: number, a: number) => void
@@ -396,6 +404,7 @@ renderer_setViewport: (x: number, y: number, w: number, h: number) => void
renderer_setYSortLayers: ((mask: number) => void) | undefined
renderer_submitAll: (registry: CppRegistry, vpX: number, vpY: number, vpW: number, vpH: number) => void
renderer_submitSkeletalBatchByEntity: ((registry: CppRegistry, verticesPtr: number, vertexCount: number, indicesPtr: number, indexCount: number, textureId: number, blendMode: number, entity: number, skelScale: number, flipX: boolean, flipY: boolean, layer: number, depth: number, materialId: number) => void) | undefined
+renderer_submitSkeletalPreviewBatch: (preview: number, verticesPtr: number, vertexCount: number, indicesPtr: number, indexCount: number, textureId: number, blendMode: number, transformPtr: number, layer: number, depth: number, materialId: number) => number
renderer_submitTextBatch: ((verticesPtr: number, vertexCount: number, indicesPtr: number, indexCount: number, textureId: number, transformPtr: number, entity: number, layer: number, depth: number, sdf: number, cullBit: number) => void) | undefined
renderer_takeFrameCapture: ((handle: number, dest: number, destSize: number) => boolean) | undefined
renderer_updateTransforms: (registry: CppRegistry) => void
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 4b096156f..9ada6b076 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/wechat
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 113 public · 84 beta · 1518 experimental · 3 deprecated
+Symbols: 113 public · 84 beta · 1520 experimental · 3 deprecated
## ANCHOR_AXES — const @experimental
```
@@ -7260,6 +7260,33 @@ runtime: string
skeletonField: string
```
+## SkeletalPreview — class @experimental
+```
+dispose: () => void
+height: number
+live: boolean
+render: (viewProjection: Float32Array) => Promise<ImageData | null>
+submit: (batch: SkeletalPreviewBatch) => boolean
+width: number
+static create: (module: unknown, w: number, h: number) => SkeletalPreview | null
+static new (core: SkeletalPreviewCore, id: number, width: number, height: number): SkeletalPreview
+static prototype: SkeletalPreview
+```
+
+## SkeletalPreviewBatch — interface @experimental
+```
+blendMode: number
+depth: number | undefined
+indexCount: number
+indices: Uint8Array<ArrayBufferLike>
+layer: number | undefined
+materialId: number | undefined
+textureId: number
+transform: Float32Array<ArrayBufferLike>
+vertexCount: number
+vertices: Uint8Array<ArrayBufferLike>
+```
+
## SliceBorder — interface @experimental
```
bottom: number
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index 53249ba27..612946f67 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -93,6 +93,8 @@ export {
} from './render/material';
export { renderMeshPreview } from './render/assetPreview';
+export { SkeletalPreview } from './render/skeletalPreview';
+export type { SkeletalPreviewBatch } from './render/skeletalPreview';
export {
BUILTIN_SHADER_TEMPLATES,
diff --git a/sdk/src/render/skeletalPreview.ts b/sdk/src/render/skeletalPreview.ts
new file mode 100644
index 000000000..bdf9d6016
--- /dev/null
+++ b/sdk/src/render/skeletalPreview.ts
@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Offscreen preview of posed skeletal geometry, owned by its handle.
+ *
+ * Unlike a material ball, what is drawn here is not in any scene: the
+ * caller poses a skeleton itself and hands over the batches, which the
+ * engine copies and replays through the one skeletal path a frame's own
+ * geometry takes.
+ *
+ * Everything names the handle. There is no current preview, no mode and
+ * no begin/end pair to get wrong, so two previews in flight cannot reach
+ * each other whatever order their calls arrive in — and a render CONSUMES
+ * what was handed over, so a frame that fails cannot draw last frame's
+ * pose again underneath the next one.
+ */
+import type { ESEngineModule } from '../wasm';
+import { awaitReadback, READBACK_READY } from './readback';
+import { withScratch } from '../wasm/wasmScratch';
+
+export type SkeletalPreviewCore = Pick<ESEngineModule,
+ 'renderer_createSkeletalPreview' | 'renderer_submitSkeletalPreviewBatch'
+ | 'renderer_renderSkeletalPreview' | 'renderer_pollSkeletalPreview'
+ | 'renderer_getSkeletalPreviewPtr' | 'renderer_getSkeletalPreviewSize'
+ | 'renderer_getSkeletalPreviewWidth' | 'renderer_getSkeletalPreviewHeight'
+ | 'renderer_destroySkeletalPreview' | '_malloc' | '_free' | 'HEAPU8'>;
+
+/** The connected core, when it answers the skeletal-preview surface. */
+export function skeletalPreviewCore(m: unknown): SkeletalPreviewCore | null {
+ const p = m as SkeletalPreviewCore | null;
+ return typeof p?.renderer_createSkeletalPreview === 'function' ? p : null;
+}
+
+/** One batch of posed geometry, in the format every skeletal runtime emits. */
+export interface SkeletalPreviewBatch {
+ /** x,y,u,v,r,g,b,a per vertex. */
+ vertices: Uint8Array;
+ indices: Uint8Array;
+ vertexCount: number;
+ indexCount: number;
+ textureId: number;
+ blendMode: number;
+ /** Column-major 4×4, as the renderer takes a model matrix. */
+ transform: Float32Array;
+ materialId?: number;
+ layer?: number;
+ depth?: number;
+}
+
+/**
+ * An offscreen preview of one posed skeleton.
+ *
+ * Its lifetime is the caller's: whoever needs the preview to be alive holds
+ * this, and `dispose` ends it. A disposed handle answers nothing rather than
+ * quietly addressing whatever was made next.
+ */
+export class SkeletalPreview {
+ private id: number;
+
+ private constructor(private readonly core: SkeletalPreviewCore, id: number,
+ readonly width: number, readonly height: number) {
+ this.id = id;
+ }
+
+ /** A preview of `w`×`h`, or null where this core has no such surface. */
+ static create(module: unknown, w: number, h: number): SkeletalPreview | null {
+ const core = skeletalPreviewCore(module);
+ if (!core || w <= 0 || h <= 0) return null;
+ const id = core.renderer_createSkeletalPreview(w, h);
+ return id ? new SkeletalPreview(core, id, w, h) : null;
+ }
+
+ get live(): boolean {
+ return this.id !== 0;
+ }
+
+ /** Hand over one batch. The engine copies it, so these buffers are the
+ * caller's again the moment this returns. */
+ submit(batch: SkeletalPreviewBatch): boolean {
+ if (!this.id) return false;
+ const core = this.core;
+ return withScratch({ _malloc: core._malloc, _free: core._free }, (alloc) => {
+ const vp = alloc(batch.vertices.byteLength);
+ const ip = alloc(batch.indices.byteLength);
+ const tp = alloc(16 * 4);
+ core.HEAPU8.set(batch.vertices, vp);
+ core.HEAPU8.set(batch.indices, ip);
+ core.HEAPU8.set(new Uint8Array(batch.transform.buffer, batch.transform.byteOffset, 16 * 4), tp);
+ return core.renderer_submitSkeletalPreviewBatch(
+ this.id, vp, batch.vertexCount, ip, batch.indexCount,
+ batch.textureId, batch.blendMode, tp,
+ batch.layer ?? 0, batch.depth ?? 0, batch.materialId ?? 0) !== 0;
+ });
+ }
+
+ /**
+ * Draw what has been handed over and resolve with the pixels, upright.
+ *
+ * Null when this preview already has a readback in flight — one at a time,
+ * which is what keeps a landed image and the camera it was drawn with from
+ * drifting apart. The caller re-renders when the pending one lands.
+ */
+ async render(viewProjection: Float32Array): Promise<ImageData | null> {
+ if (!this.id) return null;
+ const core = this.core;
+ const started = withScratch({ _malloc: core._malloc, _free: core._free }, (alloc) => {
+ const vp = alloc(16 * 4);
+ core.HEAPU8.set(new Uint8Array(viewProjection.buffer, viewProjection.byteOffset, 16 * 4), vp);
+ return core.renderer_renderSkeletalPreview(this.id, vp) !== 0;
+ });
+ if (!started) return null;
+ if (await awaitReadback(() => core.renderer_pollSkeletalPreview(this.id)) !== READBACK_READY) {
+ return null;
+ }
+ const size = core.renderer_getSkeletalPreviewSize(this.id);
+ const w = core.renderer_getSkeletalPreviewWidth(this.id);
+ const h = core.renderer_getSkeletalPreviewHeight(this.id);
+ if (size === 0 || w === 0 || h === 0) return null;
+ const pixels = new Uint8ClampedArray(core.HEAPU8.buffer, core.renderer_getSkeletalPreviewPtr(this.id), size);
+ // Readback rows are bottom-up; flip so the preview is upright.
+ const flipped = new Uint8ClampedArray(size);
+ const rowBytes = w * 4;
+ for (let y = 0; y < h; y++) {
+ flipped.set(pixels.subarray(y * rowBytes, (y + 1) * rowBytes), (h - 1 - y) * rowBytes);
+ }
+ return new ImageData(flipped, w, h);
+ }
+
+ /** End it. Idempotent, and the id stops answering rather than addressing
+ * whatever is made next. */
+ dispose(): void {
+ if (!this.id) return;
+ this.core.renderer_destroySkeletalPreview(this.id);
+ this.id = 0;
+ }
+}
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 960f08f4b..24fd8b206 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -542,6 +542,20 @@ export interface ESEngineModule {
renderer_getSnapshotWidth(): number;
renderer_getSnapshotHeight(): number;
renderer_renderMaterialPreview(materialId: number, w: number, h: number): void;
+ /** A skeletal preview, owned by its handle: every call names one, so two of
+ * them cannot reach each other and there is no "current" preview. */
+ renderer_createSkeletalPreview(w: number, h: number): number;
+ renderer_submitSkeletalPreviewBatch(
+ preview: number, verticesPtr: number, vertexCount: number,
+ indicesPtr: number, indexCount: number, textureId: number, blendMode: number,
+ transformPtr: number, layer: number, depth: number, materialId: number): number;
+ renderer_renderSkeletalPreview(preview: number, viewProjectionPtr: number): number;
+ renderer_pollSkeletalPreview(preview: number): number;
+ renderer_getSkeletalPreviewPtr(preview: number): number;
+ renderer_getSkeletalPreviewSize(preview: number): number;
+ renderer_getSkeletalPreviewWidth(preview: number): number;
+ renderer_getSkeletalPreviewHeight(preview: number): number;
+ renderer_destroySkeletalPreview(preview: number): void;
renderer_renderMeshPreview(meshId: number, w: number, h: number): void;
/** Same 0/1/2 readback contract as renderer_pollSnapshotReadback. */
renderer_pollPreviewReadback(): number;
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index a0f497b04..8f21a7cf8 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -38,6 +38,7 @@
#include <glm/glm.hpp>
#include <glm/gtc/matrix_transform.hpp>
#include <glm/gtc/type_ptr.hpp>
+#include <cstring>
#include <utility>
namespace esengine {
@@ -974,6 +975,67 @@ bool renderer_takeFrameCapture(u32 handle, uintptr_t dest, u32 destSize) {
return true;
}
+u32 renderer_createSkeletalPreview(i32 w, i32 h) {
+ if (!g_renderFrame || w <= 0 || h <= 0) return 0;
+ return static_cast<u32>(g_renderFrame->createSkeletalPreview(
+ static_cast<u32>(w), static_cast<u32>(h)));
+}
+
+i32 renderer_submitSkeletalPreviewBatch(
+ u32 preview,
+ uintptr_t verticesPtr, i32 vertexCount,
+ uintptr_t indicesPtr, i32 indexCount,
+ u32 textureId, i32 blendMode, uintptr_t transformPtr,
+ i32 layer, f32 depth, u32 materialId
+) {
+ if (!g_renderFrame || vertexCount < 0 || indexCount < 0) return 0;
+ // Skeletal vertex format is x,y,u,v,r,g,b,a (8 floats per vertex).
+ auto* vertices = boundarySpan<f32>(verticesPtr, static_cast<u64>(vertexCount) * 8,
+ "renderer_submitSkeletalPreviewBatch.vertices");
+ auto* indices = boundarySpan<u16>(indicesPtr, static_cast<u64>(indexCount),
+ "renderer_submitSkeletalPreviewBatch.indices");
+ auto* transform = boundarySpan<f32>(transformPtr, 16,
+ "renderer_submitSkeletalPreviewBatch.transform");
+ if (!vertices || !indices || !transform) return 0;
+ return g_renderFrame->submitSkeletalPreviewBatch(
+ preview, vertices, vertexCount, indices, indexCount,
+ textureId, blendMode, transform, layer, depth, materialId) ? 1 : 0;
+}
+
+i32 renderer_renderSkeletalPreview(u32 preview, uintptr_t viewProjectionPtr) {
+ if (!g_renderFrame) return 0;
+ auto* vp = boundarySpan<f32>(viewProjectionPtr, 16, "renderer_renderSkeletalPreview.vp");
+ if (!vp) return 0;
+ glm::mat4 viewProjection{1.0f};
+ std::memcpy(&viewProjection[0][0], vp, sizeof(f32) * 16);
+ return g_renderFrame->renderSkeletalPreview(preview, viewProjection) ? 1 : 0;
+}
+
+i32 renderer_pollSkeletalPreview(u32 preview) {
+ return g_renderFrame ? g_renderFrame->pollSkeletalPreview(preview) : 2;
+}
+
+uintptr_t renderer_getSkeletalPreviewPtr(u32 preview) {
+ return g_renderFrame
+ ? reinterpret_cast<uintptr_t>(g_renderFrame->skeletalPreviewPixels(preview)) : 0;
+}
+
+u32 renderer_getSkeletalPreviewSize(u32 preview) {
+ return g_renderFrame ? g_renderFrame->skeletalPreviewSize(preview) : 0;
+}
+
+u32 renderer_getSkeletalPreviewWidth(u32 preview) {
+ return g_renderFrame ? g_renderFrame->skeletalPreviewWidth(preview) : 0;
+}
+
+u32 renderer_getSkeletalPreviewHeight(u32 preview) {
+ return g_renderFrame ? g_renderFrame->skeletalPreviewHeight(preview) : 0;
+}
+
+void renderer_destroySkeletalPreview(u32 preview) {
+ if (g_renderFrame) g_renderFrame->destroySkeletalPreview(preview);
+}
+
void renderer_renderMaterialPreview(u32 materialId, i32 w, i32 h) {
if (!g_renderFrame || w <= 0 || h <= 0) return;
diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hpp
index 1b5a79507..fc22ce5e0 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -162,6 +162,23 @@ u32 renderer_getSnapshotSize();
u32 renderer_getSnapshotWidth();
u32 renderer_getSnapshotHeight();
+// A skeletal preview is owned by whoever created it: every call names the
+// handle, so two of them cannot reach each other and there is no "current" one.
+u32 renderer_createSkeletalPreview(i32 w, i32 h);
+i32 renderer_submitSkeletalPreviewBatch(
+ u32 preview,
+ uintptr_t verticesPtr, i32 vertexCount,
+ uintptr_t indicesPtr, i32 indexCount,
+ u32 textureId, i32 blendMode, uintptr_t transformPtr,
+ i32 layer, f32 depth, u32 materialId);
+i32 renderer_renderSkeletalPreview(u32 preview, uintptr_t viewProjectionPtr);
+i32 renderer_pollSkeletalPreview(u32 preview);
+uintptr_t renderer_getSkeletalPreviewPtr(u32 preview);
+u32 renderer_getSkeletalPreviewSize(u32 preview);
+u32 renderer_getSkeletalPreviewWidth(u32 preview);
+u32 renderer_getSkeletalPreviewHeight(u32 preview);
+void renderer_destroySkeletalPreview(u32 preview);
+
void renderer_renderMaterialPreview(u32 materialId, i32 w, i32 h);
void renderer_renderMeshPreview(u32 meshId, i32 w, i32 h);
i32 renderer_pollPreviewReadback();
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 1aff85abc..166385352 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -705,6 +705,17 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("renderer_getSnapshotWidth", &esengine::renderer_getSnapshotWidth);
emscripten::function("renderer_getSnapshotHeight", &esengine::renderer_getSnapshotHeight);
emscripten::function("renderer_renderMaterialPreview", &esengine::renderer_renderMaterialPreview);
+ // Skeletal previews. Every one names its handle — there is no current preview
+ // and no begin/end pair, so two of them cannot reach each other.
+ emscripten::function("renderer_createSkeletalPreview", &esengine::renderer_createSkeletalPreview);
+ emscripten::function("renderer_submitSkeletalPreviewBatch", &esengine::renderer_submitSkeletalPreviewBatch);
+ emscripten::function("renderer_renderSkeletalPreview", &esengine::renderer_renderSkeletalPreview);
+ emscripten::function("renderer_pollSkeletalPreview", &esengine::renderer_pollSkeletalPreview);
+ emscripten::function("renderer_getSkeletalPreviewPtr", &esengine::renderer_getSkeletalPreviewPtr);
+ emscripten::function("renderer_getSkeletalPreviewSize", &esengine::renderer_getSkeletalPreviewSize);
+ emscripten::function("renderer_getSkeletalPreviewWidth", &esengine::renderer_getSkeletalPreviewWidth);
+ emscripten::function("renderer_getSkeletalPreviewHeight", &esengine::renderer_getSkeletalPreviewHeight);
+ emscripten::function("renderer_destroySkeletalPreview", &esengine::renderer_destroySkeletalPreview);
emscripten::function("renderer_renderMeshPreview", &esengine::renderer_renderMeshPreview);
emscripten::function("renderer_pollPreviewReadback", &esengine::renderer_pollPreviewReadback);
emscripten::function("renderer_getPreviewPtr", &esengine::renderer_getPreviewPtr);
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 100ccf899..65740479a 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -18,7 +18,9 @@
#include <algorithm>
#include <cmath>
+#include <cstring>
#include <limits>
+#include <utility>
#include <vector>
namespace esengine {
@@ -603,16 +605,22 @@ void RenderFrame::replayToDrawCall(i32 stopAtDrawCall) {
}
void RenderFrame::renderToTarget(ecs::Registry& registry, const glm::mat4& viewProjection, u32 w, u32 h) {
+ renderSurface(registry, viewProjection, preview_, w, h, {});
+}
+
+void RenderFrame::renderSurface(ecs::Registry& registry, const glm::mat4& viewProjection,
+ PreviewSurface& surface, u32 w, u32 h,
+ std::span<const PendingSkeletalBatch> extraSkeletalBatches) {
if (w == 0 || h == 0) return;
if (!device_.isDeviceUsable()) return;
- if (preview_rt_ == 0) {
- preview_rt_ = target_manager_.create(w, h, /*depth=*/false, /*linearFilter=*/false);
- } else if (auto* existing = target_manager_.get(preview_rt_);
+ if (surface.target == 0) {
+ surface.target = target_manager_.create(w, h, /*depth=*/false, /*linearFilter=*/false);
+ } else if (auto* existing = target_manager_.get(surface.target);
existing && (existing->getWidth() != w || existing->getHeight() != h)) {
existing->resize(w, h);
}
- auto* rt = target_manager_.get(preview_rt_);
+ auto* rt = target_manager_.get(surface.target);
if (!rt) return;
RenderPassDesc previewPass{rt->getFramebuffer(), /*clearColor=*/true};
@@ -633,6 +641,16 @@ void RenderFrame::renderToTarget(ecs::Registry& registry, const glm::mat4& viewP
collectAll(registry);
+ // AFTER the collect, because the clear above would have eaten them. Geometry
+ // a caller posed itself and handed over, replayed through the one skeletal
+ // path a scene's batches take.
+ for (const auto& batch : extraSkeletalBatches) {
+ submitSkeletalBatch(batch.vertices.data(), static_cast<i32>(batch.vertices.size() / 8),
+ batch.indices.data(), static_cast<i32>(batch.indices.size()),
+ batch.textureId, batch.blendMode, &batch.transform[0][0],
+ batch.entity, batch.layer, batch.depth, batch.materialId);
+ }
+
draw_list_.finalize(pool_);
pool_.upload();
context_.updateCameraConstants(viewProjection);
@@ -645,19 +663,124 @@ void RenderFrame::renderToTarget(ecs::Registry& registry, const glm::mat4& viewP
device_.invalidatePipelineCache();
// Async readback seam (same shape as the replay snapshot above).
- if (preview_readback_ != ReadbackHandle::Invalid) device_.discardReadback(preview_readback_);
- preview_w_ = w;
- preview_h_ = h;
- preview_pixels_.clear();
- preview_readback_ = device_.requestReadback(rt->getFramebuffer(), w, h);
+ if (surface.readback != ReadbackHandle::Invalid) device_.discardReadback(surface.readback);
+ surface.width = w;
+ surface.height = h;
+ surface.pixels.clear();
+ surface.readback = device_.requestReadback(rt->getFramebuffer(), w, h);
}
i32 RenderFrame::pollSnapshotReadback() {
return pollReadback(snapshot_readback_, snapshot_pixels_, snapshot_w_, snapshot_h_);
}
+RenderFrame::SkeletalPreview* RenderFrame::skeletalPreview(SkeletalPreviewId id) {
+ auto it = skeletal_previews_.find(id);
+ return it == skeletal_previews_.end() ? nullptr : it->second.get();
+}
+
+const RenderFrame::SkeletalPreview* RenderFrame::skeletalPreview(SkeletalPreviewId id) const {
+ auto it = skeletal_previews_.find(id);
+ return it == skeletal_previews_.end() ? nullptr : it->second.get();
+}
+
+RenderFrame::SkeletalPreviewId RenderFrame::createSkeletalPreview(u32 w, u32 h) {
+ if (w == 0 || h == 0) return 0;
+ auto preview = std::make_unique<SkeletalPreview>();
+ // Its own one-entity scene. The transform is identity and stays that way:
+ // where a preview stands is the preview camera's business, and a batch
+ // arrives with its own model matrix.
+ preview->entity = preview->registry.create();
+ preview->registry.emplace<ecs::Transform>(preview->entity);
+ preview->surface.width = w;
+ preview->surface.height = h;
+ const SkeletalPreviewId id = next_skeletal_preview_++;
+ skeletal_previews_.emplace(id, std::move(preview));
+ return id;
+}
+
+bool RenderFrame::submitSkeletalPreviewBatch(
+ SkeletalPreviewId id,
+ const f32* vertices, i32 vertexCount,
+ const u16* indices, i32 indexCount,
+ u32 textureId, i32 blendMode, const f32* transform16,
+ i32 layer, f32 depth, u32 materialId
+) {
+ auto* preview = skeletalPreview(id);
+ if (!preview || !vertices || !indices || vertexCount < 0 || indexCount < 0) return false;
+ PendingSkeletalBatch batch;
+ // COPIED, not referenced: this sits until the next render call, and the
+ // caller's scratch is gone the moment it returns.
+ batch.vertices.assign(vertices, vertices + static_cast<usize>(vertexCount) * 8);
+ batch.indices.assign(indices, indices + static_cast<usize>(indexCount));
+ batch.textureId = textureId;
+ batch.blendMode = blendMode;
+ if (transform16) std::memcpy(&batch.transform[0][0], transform16, sizeof(f32) * 16);
+ batch.entity = preview->entity;
+ batch.layer = layer;
+ batch.depth = depth;
+ batch.materialId = materialId;
+ preview->pending.push_back(std::move(batch));
+ return true;
+}
+
+bool RenderFrame::renderSkeletalPreview(SkeletalPreviewId id, const glm::mat4& viewProjection) {
+ auto* preview = skeletalPreview(id);
+ if (!preview) return false;
+ // One in flight per preview. A second render would land two images for one
+ // camera and leave a caller no way to say which its overlay belongs to.
+ if (preview->surface.readback != ReadbackHandle::Invalid) return false;
+ // Taken before the draw: a render that throws or bails must not leave last
+ // frame's geometry to be drawn again on top of the next one.
+ const auto batches = std::exchange(preview->pending, {});
+ renderSurface(preview->registry, viewProjection, preview->surface,
+ preview->surface.width, preview->surface.height, batches);
+ return true;
+}
+
+i32 RenderFrame::pollSkeletalPreview(SkeletalPreviewId id) {
+ auto* preview = skeletalPreview(id);
+ if (!preview) return 2;
+ return pollReadback(preview->surface.readback, preview->surface.pixels,
+ preview->surface.width, preview->surface.height);
+}
+
+const u8* RenderFrame::skeletalPreviewPixels(SkeletalPreviewId id) const {
+ const auto* preview = skeletalPreview(id);
+ return preview ? preview->surface.pixels.data() : nullptr;
+}
+
+u32 RenderFrame::skeletalPreviewSize(SkeletalPreviewId id) const {
+ const auto* preview = skeletalPreview(id);
+ return preview ? static_cast<u32>(preview->surface.pixels.size()) : 0;
+}
+
+u32 RenderFrame::skeletalPreviewWidth(SkeletalPreviewId id) const {
+ const auto* preview = skeletalPreview(id);
+ return preview ? preview->surface.width : 0;
+}
+
+u32 RenderFrame::skeletalPreviewHeight(SkeletalPreviewId id) const {
+ const auto* preview = skeletalPreview(id);
+ return preview ? preview->surface.height : 0;
+}
+
+void RenderFrame::destroySkeletalPreview(SkeletalPreviewId id) {
+ auto it = skeletal_previews_.find(id);
+ if (it == skeletal_previews_.end()) return;
+ // Logical ownership ends now; the device's outstanding work is handed back
+ // the same way every other readback is, so nothing lands in freed pixels.
+ auto& surface = it->second->surface;
+ if (surface.readback != ReadbackHandle::Invalid) {
+ device_.discardReadback(surface.readback);
+ surface.readback = ReadbackHandle::Invalid;
+ }
+ if (surface.target != 0) target_manager_.release(surface.target);
+ skeletal_previews_.erase(it);
+}
+
i32 RenderFrame::pollPreviewReadback() {
- return pollReadback(preview_readback_, preview_pixels_, preview_w_, preview_h_);
+ return pollReadback(preview_.readback, preview_.pixels, preview_.width, preview_.height);
}
i32 RenderFrame::pollReadback(ReadbackHandle& handle, std::vector<u8>& pixels, u32 w, u32 h) {
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index 996e9fd17..1edbe390b 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -23,6 +23,8 @@
#include "../../resource/ResourceManager.hpp"
#include <glm/glm.hpp>
+#include <span>
+#include <unordered_map>
#include <vector>
#include <string>
#include <memory>
@@ -171,6 +173,41 @@ public:
Entity entity, i32 layer, f32 depth, bool sdf, u32 cullBit = 0
);
+ /**
+ * @brief One offscreen render's resources, correct only together.
+ *
+ * @details Loose, they were one slot: two previews in flight overwrote each
+ * other's target, readback and pixels. As an object, a caller with
+ * its own preview owns its own surface.
+ */
+ struct PreviewSurface {
+ RenderTargetManager::Handle target = 0;
+ ReadbackHandle readback = ReadbackHandle::Invalid;
+ std::vector<u8> pixels;
+ u32 width = 0;
+ u32 height = 0;
+ };
+
+ /**
+ * @brief Skeletal geometry a caller holds until it renders, owning its bytes.
+ *
+ * @details A scene's batches go straight into the frame being built. A
+ * preview's cross the ABI, wait for a render call, and are replayed
+ * — so they cannot be spans into the caller's scratch. Owning the
+ * bytes is what lets `submit` return and the caller reuse its buffer.
+ */
+ struct PendingSkeletalBatch {
+ std::vector<f32> vertices;
+ std::vector<u16> indices;
+ u32 textureId = 0;
+ i32 blendMode = 0;
+ glm::mat4 transform{1.0f};
+ Entity entity{};
+ i32 layer = 0;
+ f32 depth = 0.0f;
+ u32 materialId = 0;
+ };
+
/**
* @brief Batch vertices posed by a skeletal runtime, drawn as one entity's geometry.
* @details Serves every such runtime — Spine and DragonBones both arrive here — and
@@ -241,14 +278,58 @@ public:
* viewport exactly. Clobbers the transient draw list/pool, which the next real frame rebuilds.
*/
void renderToTarget(ecs::Registry& registry, const glm::mat4& viewProjection, u32 w, u32 h);
- const u8* getPreviewPixels() const { return preview_pixels_.data(); }
- u32 getPreviewSize() const { return static_cast<u32>(preview_pixels_.size()); }
- u32 getPreviewWidth() const { return preview_w_; }
- u32 getPreviewHeight() const { return preview_h_; }
+ const u8* getPreviewPixels() const { return preview_.pixels.data(); }
+ u32 getPreviewSize() const { return static_cast<u32>(preview_.pixels.size()); }
+ u32 getPreviewWidth() const { return preview_.width; }
+ u32 getPreviewHeight() const { return preview_.height; }
/** Lands the preview's async readback; same 0/1/2 contract as pollSnapshotReadback(). */
i32 pollPreviewReadback();
+ // — Skeletal previews —————————————————————————————————————————————————————
+ // Every call names its handle: no current preview, no mode, no begin/end
+ // pair, so two in flight cannot reach each other whatever the call order.
+
+ /** A skeletal preview's id. Carries a generation, so a destroyed one cannot
+ * come back pointing at whatever took its slot. */
+ using SkeletalPreviewId = u64;
+
+ /** A preview of @p w×@p h, or 0 when one cannot be made. */
+ SkeletalPreviewId createSkeletalPreview(u32 w, u32 h);
+
+ /** Hand one batch to @p id, which COPIES it: the caller may reuse its
+ * buffers the moment this returns. False for an id that is not live — a
+ * stale handle is a mistake worth hearing about, not a no-op. */
+ bool submitSkeletalPreviewBatch(
+ SkeletalPreviewId id,
+ const f32* vertices, i32 vertexCount,
+ const u16* indices, i32 indexCount,
+ u32 textureId, i32 blendMode, const f32* transform16,
+ i32 layer, f32 depth, u32 materialId);
+
+ /**
+ * Draw everything handed to @p id, and start its readback. CONSUMES the
+ * batches, so a render that fails cannot draw last frame's pose again.
+ *
+ * Refused while this preview's readback is in flight — one at a time keeps a
+ * landed image and the camera it was drawn with together.
+ */
+ bool renderSkeletalPreview(SkeletalPreviewId id, const glm::mat4& viewProjection);
+
+ /** Lands @p id's readback: 0 pending, 1 pixels available, 2 nothing to read. */
+ i32 pollSkeletalPreview(SkeletalPreviewId id);
+ const u8* skeletalPreviewPixels(SkeletalPreviewId id) const;
+ u32 skeletalPreviewSize(SkeletalPreviewId id) const;
+ u32 skeletalPreviewWidth(SkeletalPreviewId id) const;
+ u32 skeletalPreviewHeight(SkeletalPreviewId id) const;
+
+ /**
+ * End @p id. Ownership ends here and the id stops answering; the target and
+ * any readback still in the device's hands are released the way every other
+ * one is, so nothing lands in freed memory.
+ */
+ void destroySkeletalPreview(SkeletalPreviewId id);
+
void addPlugin(std::unique_ptr<RenderTypePlugin> plugin);
void collectAll(ecs::Registry& registry);
@@ -291,6 +372,17 @@ private:
// resets @p handle. Returns the 0/1/2 contract of the public poll methods.
i32 pollReadback(ReadbackHandle& handle, std::vector<u8>& pixels, u32 w, u32 h);
+ /**
+ * The collect+execute body every preview shares, with an explicit target.
+ *
+ * @p extraSkeletalBatches replay AFTER `collectAll` — before it the draw
+ * list is cleared and they are dropped. A span, not a callback: a hook here
+ * would become where every future pass is inserted.
+ */
+ void renderSurface(ecs::Registry& registry, const glm::mat4& viewProjection,
+ PreviewSurface& surface, u32 w, u32 h,
+ std::span<const PendingSkeletalBatch> extraSkeletalBatches);
+
Stats stats_;
/**
* ONE per frame, spanning the graph. GL's TIME_ELAPSED has a single global
@@ -304,11 +396,21 @@ private:
ReadbackHandle snapshot_readback_ = ReadbackHandle::Invalid;
u32 snapshot_w_ = 0;
u32 snapshot_h_ = 0;
- std::vector<u8> preview_pixels_;
- RenderTargetManager::Handle preview_rt_ = 0;
- ReadbackHandle preview_readback_ = ReadbackHandle::Invalid;
- u32 preview_w_ = 0;
- u32 preview_h_ = 0;
+ PreviewSurface preview_;
+
+ /** One editor preview: its own scene, its own surface, its own pending work. */
+ struct SkeletalPreview {
+ ecs::Registry registry;
+ Entity entity{};
+ std::vector<PendingSkeletalBatch> pending;
+ PreviewSurface surface;
+ };
+ std::unordered_map<SkeletalPreviewId, Unique<SkeletalPreview>> skeletal_previews_;
+ /** Never reused, so a destroyed id can only ever be a destroyed id. */
+ SkeletalPreviewId next_skeletal_preview_ = 1;
+
+ SkeletalPreview* skeletalPreview(SkeletalPreviewId id);
+ const SkeletalPreview* skeletalPreview(SkeletalPreviewId id) const;
bool in_frame_ = false;
bool flushed_ = false;
/// Depth state for the capture's attachment — see applySceneDepthNeed.
diff --git a/tools/check-preview-ownership.mjs b/tools/check-preview-ownership.mjs
new file mode 100644
index 000000000..9dcc70f9c
--- /dev/null
+++ b/tools/check-preview-ownership.mjs
@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file check-preview-ownership.mjs — an offscreen preview is addressed, never
+ * entered.
+ *
+ * The shape refused here is a renderer that is "in preview mode": a begin, some
+ * submits whose destination depends on the calls around them, and an end. It is
+ * the same family as the ambient state the shadow pass and the certificate
+ * transport were each moved out of, and it fails the same way — by working until
+ * two callers exist.
+ *
+ * What replaced it: every call names a handle, the batches a preview holds own
+ * their bytes, and the one shared render body takes its destination as an
+ * argument. Each of those is a decision somebody could undo without noticing.
+ *
+ * node tools/check-preview-ownership.mjs
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const FRAME_H = 'src/esengine/renderer/frame/RenderFrame.hpp';
+const FRAME_C = 'src/esengine/renderer/frame/RenderFrame.cpp';
+const BINDINGS_H = 'src/esengine/bindings/RendererBindings.hpp';
+
+const missing = [FRAME_H, FRAME_C, BINDINGS_H].filter((f) => !existsSync(path.join(ROOT, f)));
+if (missing.length) {
+ console.error(`check-preview-ownership is stale: ${missing.join(', ')} does not exist.`);
+ process.exit(1);
+}
+
+const read = (rel) => readFileSync(path.join(ROOT, rel), 'utf8');
+const strip = (text) => text
+ .replace(/\/\*[\s\S]*?\*\//g, '')
+ .replace(/\/\/[^\n]*/g, '');
+
+const RULES = [
+ {
+ rule: 'No renderer state says which preview is the current one. A begin/end pair makes what a submit reaches depend on the calls around it, which is correct until two callers exist.',
+ holds: () => {
+ const bad = [];
+ for (const file of [FRAME_H, FRAME_C, BINDINGS_H]) {
+ const text = strip(read(file));
+ for (const m of text.matchAll(/\b(current|active|in)_?[Pp]review\w*\b/g)) {
+ bad.push(`${file} declares ${m[0]}`);
+ }
+ if (/\b(begin|end)SkeletalPreview\b/.test(text)) {
+ bad.push(`${file} has a begin/end preview pair`);
+ }
+ }
+ return bad.length ? bad.join('; ') : null;
+ },
+ },
+ {
+ rule: 'Every skeletal-preview entry takes the preview it is about as its first argument. An entry without one can only mean "the current preview".',
+ holds: () => {
+ const text = strip(read(BINDINGS_H));
+ const bad = [];
+ for (const m of text.matchAll(/\b(\w*SkeletalPreview\w*)\s*\(([^)]*)\)/g)) {
+ const [, name, args] = m;
+ if (name.includes('create')) continue; // creates one rather than naming one
+ if (!/^\s*u32 preview\b/.test(args)) bad.push(name);
+ }
+ return bad.length === 0 ? null
+ : `${bad.join(', ')} does not name the preview it acts on`;
+ },
+ },
+ {
+ rule: 'The shared render body takes a SPAN of batches, never a callback. A hook there becomes the place every future pass is inserted, and this is a preview rather than a second orchestration door.',
+ holds: () => {
+ const decl = strip(read(FRAME_H)).match(/void renderSurface\(([\s\S]*?)\);/);
+ if (!decl) return 'renderSurface is gone — the shared render body was inlined again';
+ return /std::function|auto&&\s*\w+|template/.test(decl[1])
+ ? 'renderSurface takes a callback' : null;
+ },
+ },
+ {
+ rule: 'A preview\'s batches own their bytes. They cross the ABI and wait for a render call, so a span into the caller\'s scratch would be a lifetime protocol nobody wrote down.',
+ holds: () => {
+ const body = strip(read(FRAME_H)).match(/struct PendingSkeletalBatch \{([\s\S]*?)\};/);
+ if (!body) return 'PendingSkeletalBatch is gone';
+ if (/\bconst\s+\w+\s*\*|std::span|_ptr\b/.test(body[1])) {
+ return 'PendingSkeletalBatch refers to memory it does not own';
+ }
+ return /std::vector<f32>[\s\S]*std::vector<u16>/.test(body[1]) ? null
+ : 'PendingSkeletalBatch no longer owns its vertices and indices';
+ },
+ },
+ {
+ rule: 'Handed-over batches are replayed AFTER the collect. Before it, the draw list is cleared and they are silently dropped — which is the whole reason a preview holds them rather than submitting through.',
+ holds: () => {
+ const body = strip(read(FRAME_C)).match(/void RenderFrame::renderSurface\([\s\S]*?\n\}/);
+ if (!body) return 'renderSurface is gone';
+ const collect = body[0].indexOf('collectAll(registry)');
+ // The LOOP, not the parameter — which is named in the signature above.
+ const replay = body[0].search(/for\s*\([^)]*:\s*extraSkeletalBatches\s*\)/);
+ const finalize = body[0].indexOf('draw_list_.finalize');
+ if (collect < 0 || replay < 0 || finalize < 0) return 'renderSurface no longer collects, replays and finalizes';
+ return collect < replay && replay < finalize ? null
+ : 'the replay is not between the collect and the finalize';
+ },
+ },
+ {
+ rule: 'A render consumes what it was handed. Left behind, the batches would draw again under the next frame — which is a clear/submit/render protocol wearing different clothes.',
+ holds: () => {
+ const body = strip(read(FRAME_C)).match(/bool RenderFrame::renderSkeletalPreview\([\s\S]*?\n\}/);
+ if (!body) return null; // ownership moved; the ABI's own rule covers it
+ return /std::exchange\(\s*\w+->pending/.test(body[0]) ? null
+ : 'renderSkeletalPreview does not take its pending batches';
+ },
+ },
+];
+
+const findings = [];
+for (const { rule, holds } of RULES) {
+ const broken = holds();
+ if (broken) findings.push(`${broken}\n the boundary: ${rule}`);
+}
+
+if (findings.length === 0) {
+ console.log(`check-preview-ownership: ${RULES.length} frozen boundaries — a preview is addressed by its handle, never entered.`);
+ process.exit(0);
+}
+for (const f of findings) console.error(`✗ ${f}`);
+console.error('\nChanging one of these is allowed — with a counterexample. Edit this file and say why.');
+process.exit(1);
diff --git a/tools/gates.mjs b/tools/gates.mjs
index dddd5e685..fd80aa8fb 100644
--- a/tools/gates.mjs
+++ b/tools/gates.mjs
@@ -134,6 +134,9 @@ export const GATES = [
{ id: 'tilemap-realm', run: 'node tools/check-tilemap-realm.mjs' },
// The five spine lifetime invariants, each with the judgment that proves it:
// what they replaced were teardown protocols, and a protocol comes back quietly.
+ // An offscreen preview is addressed by its handle, never entered: no current
+ // preview, no begin/end pair, and batches that own their bytes.
+ { id: 'preview-ownership', run: 'node tools/check-preview-ownership.mjs' },
{ id: 'spine-lifetimes', run: 'node tools/check-spine-lifetimes.mjs' },
// The profiler's spine section renders the realm's report and computes none
// of it: one side measures a frame, or two of them disagree about it.