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(spine): whether this camera would draw it, asked of the renderer

esengine2a614bddcc7d
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 0c7d81b5b..5bc83c751 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -348,6 +348,7 @@ renderer_captureNextFrame: () => void
renderer_createTarget: (width: number, height: number, flags: number) => number
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
renderer_flush: () => void
renderer_getCapturedCameraCount: () => number
renderer_getCapturedEntities: () => number
diff --git a/sdk/src/spine/SpineRuntime.ts b/sdk/src/spine/SpineRuntime.ts
index 216f7fd8c..89edf96cb 100644
--- a/sdk/src/spine/SpineRuntime.ts
+++ b/sdk/src/spine/SpineRuntime.ts
@@ -29,6 +29,7 @@ import { submitEntityMeshes, type SkeletalMaterialOf } from '../skeletal/submitM
import type { SpineClipBudget } from './spineMetrics';
import { mayDeferWorldPose } from './spineBounds';
import type { SpineCullingEnvelope } from './spineBounds';
+import { withScratch } from '../wasm/wasmScratch';
interface EntityInfo {
skelHandle: number;
@@ -323,6 +324,37 @@ export class SpineRuntime {
return result;
}
+ /**
+ * Whether the camera in hand would draw this entity, or null where the
+ * question cannot be asked — no certified extent, or a core without the
+ * entry point. Null is not "invisible": an unknown extent makes visibility
+ * unknown, and the only answer a caller may act on is `false`.
+ */
+ private cameraWouldDraw_(
+ core: NonNullable<EngineApi>, registry: CppRegistry, entity: Entity, info: EntityInfo,
+ ): boolean | null {
+ const ask = (core as { renderer_entityVisibleToCamera?: unknown })
+ .renderer_entityVisibleToCamera as
+ | ((r: CppRegistry, e: number, layer: number,
+ minX: number, minY: number, maxX: number, maxY: number, out: number) => void)
+ | undefined;
+ if (!ask) return null;
+ const residency = this.skeletons_.get(info.era);
+ if (!residency || residency.culling.kind !== 'certified') return null;
+
+ const { bounds } = residency.culling;
+ const scale = info.skeletonScale;
+ const heap = core.HEAPU32;
+ if (!heap || !core._malloc || !core._free) return null;
+ return withScratch({ _malloc: core._malloc, _free: core._free }, (alloc) => {
+ const ptr = alloc(4);
+ ask(registry, entity as unknown as number, info.layer,
+ bounds.minX * scale, bounds.minY * scale,
+ bounds.maxX * scale, bounds.maxY * scale, ptr);
+ return heap[ptr >> 2] !== 0;
+ });
+ }
+
/**
* Whether this entity's world pose may be left owed when nothing wants it —
* both proofs, settled when its residency was made. The scheduler that will
@@ -415,6 +447,12 @@ export class SpineRuntime {
const started = m ? performance.now() : 0;
for (const [entity, info] of this.entities_) {
if (this.disabledEntities_.has(entity)) continue;
+ // What this camera would do with it, asked of the renderer rather
+ // than worked out here. Nothing acts on the answer yet: this pass
+ // still resolves, extracts and submits exactly what it did before.
+ if (m && this.cameraWouldDraw_(core, registry, entity, info) === false) {
+ m.pose.renderCulled++;
+ }
// The renderer is a consumer of the world pose like any other, and
// asks for it the same way. Today it is already resolved.
this.ensurePose(entity);
diff --git a/sdk/src/spine/spineMetrics.ts b/sdk/src/spine/spineMetrics.ts
index 75a03d2da..e20197710 100644
--- a/sdk/src/spine/spineMetrics.ts
+++ b/sdk/src/spine/spineMetrics.ts
@@ -91,6 +91,8 @@ export interface SpinePoseCounts {
worldMaterializations: number;
worldDeferred: number;
meshExtractions: number;
+ /** Extractions the camera in hand would not have drawn. Counted, not acted on. */
+ renderCulled: number;
}
export interface SpineFrameMetrics {
@@ -113,7 +115,7 @@ export function newSpineFrameMetrics(): SpineFrameMetrics {
return {
frame: 0, entities: 0, residencies: 0, meshBatches: 0, vertices: 0, indices: 0,
abi: { pose: 0, world: 0, batchCount: 0, vertexCount: 0, indexCount: 0, batchData: 0, malloc: 0, free: 0, submit: 0 },
- pose: { logicalUpdates: 0, worldMaterializations: 0, worldDeferred: 0, meshExtractions: 0 },
+ pose: { logicalUpdates: 0, worldMaterializations: 0, worldDeferred: 0, meshExtractions: 0, renderCulled: 0 },
bytes: { wasmRead: 0, coreWrite: 0, scratchAllocated: 0 },
time: { pose: 0, readback: 0, total: 0 },
};
@@ -127,7 +129,7 @@ export function beginSpineFrame(m: SpineFrameMetrics): void {
m.abi.batchData = 0; m.abi.malloc = 0; m.abi.free = 0; m.abi.submit = 0;
m.bytes.wasmRead = 0; m.bytes.coreWrite = 0; m.bytes.scratchAllocated = 0;
m.pose.logicalUpdates = 0; m.pose.worldMaterializations = 0;
- m.pose.worldDeferred = 0; m.pose.meshExtractions = 0;
+ m.pose.worldDeferred = 0; m.pose.meshExtractions = 0; m.pose.renderCulled = 0;
m.time.pose = 0; m.time.readback = 0; m.time.total = 0;
}
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index a72dc083a..960f08f4b 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -287,6 +287,15 @@ export interface ESEngineModule {
* Geometry posed by a skeletal runtime (Spine, DragonBones): x,y,u,v,r,g,b,a per
* vertex, drawn as `entity`'s, with `materialId` resolved as a Sprite's is.
*/
+ /**
+ * Whether the camera being rendered right now would draw this entity's
+ * geometry at the local extent it promises to stay inside. The frame's own
+ * frustum and culling mask — a fact, not a permission.
+ */
+ renderer_entityVisibleToCamera?(
+ registry: CppRegistry, entity: number, layer: number,
+ minX: number, minY: number, maxX: number, maxY: number, outVisiblePtr: number): void;
+
renderer_submitSkeletalBatchByEntity?(
registry: CppRegistry,
verticesPtr: number, vertexCount: number,
diff --git a/sdk/tests/spine-camera-visibility.test.ts b/sdk/tests/spine-camera-visibility.test.ts
new file mode 100644
index 000000000..f47bc422e
--- /dev/null
+++ b/sdk/tests/spine-camera-visibility.test.ts
@@ -0,0 +1,169 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file spine-camera-visibility.test.ts
+ * @brief Whether this camera would draw it — asked of the renderer, acted on
+ * by nobody yet.
+ *
+ * @details The engine culls per CAMERA, not per frame: `collectAll` runs once
+ * for each, with that camera's frustum and its culling mask, and the
+ * draw list is cleared between them. There is no camera bitmask to
+ * propagate — `cullBit` on a draw is which LAYER it belongs to.
+ *
+ * So visibility is a per-camera question and the union over cameras
+ * falls out of the revision model rather than being computed: the first
+ * camera that wants an entity resolves its pose, and the rest find the
+ * debt paid. Nothing here needs a bitmask, and nothing invents one.
+ *
+ * This cut only asks. Behaviour is identical — the same entities are
+ * resolved, extracted and submitted as before — which is what keeps the
+ * scheduling decision in the cut that will make it.
+ */
+import { describe, it, expect } from 'vitest';
+import { SpineRuntime } from '../src/spine/SpineRuntime';
+import { fakeSpineModule, fakeSpineEra } from './helpers/fakeSpineModule';
+import { certifyBounds } from '../src/spine/spineBounds';
+import type { Entity } from '../src/types';
+
+const PROMISE = certifyBounds({ minX: -100, minY: -100, maxX: 100, maxY: 100 });
+
+/** A core that answers the visibility question however the test wants. */
+function core(answer: ((entity: number, layer: number) => boolean) | null): {
+ core: never; asked: Array<{ entity: number; layer: number; rect: number[] }>;
+} {
+ const asked: Array<{ entity: number; layer: number; rect: number[] }> = [];
+ const heap = new Uint32Array(64);
+ const api: Record<string, unknown> = {
+ renderer_submitSkeletalBatchByEntity: () => {},
+ _malloc: () => 4,
+ _free: () => {},
+ HEAPU8: new Uint8Array(heap.buffer),
+ HEAPU32: heap,
+ };
+ if (answer) {
+ api.renderer_entityVisibleToCamera = (
+ _r: unknown, entity: number, layer: number,
+ minX: number, minY: number, maxX: number, maxY: number, out: number,
+ ): void => {
+ asked.push({ entity, layer, rect: [minX, minY, maxX, maxY] });
+ heap[out >> 2] = answer(entity, layer) ? 1 : 0;
+ };
+ }
+ return { core: api as never, asked };
+}
+
+function runtimeWith(culling = PROMISE): { runtime: SpineRuntime; fake: ReturnType<typeof fakeSpineModule> } {
+ const fake = fakeSpineModule();
+ const runtime = new SpineRuntime('3.8', fake.module);
+ runtime.loadEntity(1 as Entity, fakeSpineEra('era#1', new Uint8Array([1]), culling));
+ runtime.setAnimation(1 as Entity, 'walk', true);
+ runtime.observe(true);
+ return { runtime, fake };
+}
+
+describe('what this camera would draw, asked of the renderer', () => {
+ it('a certified entity is asked about, in its own extent', () => {
+ const { runtime } = runtimeWith();
+ const { core: engine, asked } = core(() => true);
+ runtime.updateAll(1 / 60);
+ runtime.extractAndSubmitMeshes(engine, {} as never);
+
+ expect(asked).toHaveLength(1);
+ expect(asked[0].rect, 'the promise was not the extent that was asked about')
+ .toEqual([-100, -100, 100, 100]);
+ expect(runtime.metrics()!.pose.renderCulled).toBe(0);
+ runtime.dispose();
+ });
+
+ it('an entity this camera cannot see is counted, not skipped', () => {
+ // The whole point of this cut landing before the next one: the fact is
+ // available and changes nothing.
+ const { runtime } = runtimeWith();
+ const { core: engine } = core(() => false);
+ runtime.updateAll(1 / 60);
+ runtime.extractAndSubmitMeshes(engine, {} as never);
+
+ const m = runtime.metrics()!;
+ expect(m.pose.renderCulled, 'the camera fact was not recorded').toBe(1);
+ expect(m.pose.worldMaterializations, 'a world pose was skipped already').toBe(1);
+ expect(m.pose.meshExtractions, 'an extraction was skipped already').toBe(1);
+ runtime.dispose();
+ });
+
+ it('an uncertified entity is not asked about at all', () => {
+ // Its extent is unknown, so its visibility is unknown; there is nothing
+ // to ask with, and "unknown" may never be read as "invisible".
+ const { runtime } = runtimeWith({ kind: 'unknown' });
+ const { core: engine, asked } = core(() => false);
+ runtime.updateAll(1 / 60);
+ runtime.extractAndSubmitMeshes(engine, {} as never);
+
+ expect(asked, 'an uncertified extent was used to ask about visibility').toHaveLength(0);
+ expect(runtime.metrics()!.pose.renderCulled).toBe(0);
+ runtime.dispose();
+ });
+
+ it('an observed extent is not asked about either', () => {
+ // The rule from the certification cut, reaching the render path: an
+ // observation is not a promise, so it is not an extent to cull against.
+ const { runtime } = runtimeWith({
+ kind: 'observed', source: 'animation-scan', sampleStep: 1 / 30, era: 'era#1',
+ bounds: { minX: -100, minY: -100, maxX: 100, maxY: 100 },
+ coverage: { animations: 1, skins: 1, samples: 30 },
+ });
+ const { core: engine, asked } = core(() => false);
+ runtime.updateAll(1 / 60);
+ runtime.extractAndSubmitMeshes(engine, {} as never);
+
+ expect(asked, 'a scan was used as the extent to cull against').toHaveLength(0);
+ runtime.dispose();
+ });
+
+ it('a core that cannot answer is not treated as a no', () => {
+ const { runtime } = runtimeWith();
+ const { core: engine } = core(null);
+ runtime.updateAll(1 / 60);
+ runtime.extractAndSubmitMeshes(engine, {} as never);
+ expect(runtime.metrics()!.pose.renderCulled).toBe(0);
+ runtime.dispose();
+ });
+
+ it('the entity scale is carried into the extent it is asked about', () => {
+ const { runtime } = runtimeWith();
+ runtime.setEntityProps(1 as Entity, { skeletonScale: 3 });
+ const { core: engine, asked } = core(() => true);
+ runtime.updateAll(1 / 60);
+ runtime.extractAndSubmitMeshes(engine, {} as never);
+ expect(asked[0].rect, 'a scaled skeleton was culled against its unscaled extent')
+ .toEqual([-300, -300, 300, 300]);
+ runtime.dispose();
+ });
+
+ it('the layer is the one the entity draws on', () => {
+ const { runtime } = runtimeWith();
+ runtime.setEntityProps(1 as Entity, { layer: 7 });
+ const { core: engine, asked } = core(() => true);
+ runtime.updateAll(1 / 60);
+ runtime.extractAndSubmitMeshes(engine, {} as never);
+ expect(asked[0].layer, "the camera was asked about the wrong layer").toBe(7);
+ runtime.dispose();
+ });
+
+ it('two cameras are two passes, and the second finds the pose paid', () => {
+ // The union, without a bitmask: each camera runs its own submit, and the
+ // revision model means only the first one that wants it pays.
+ const { runtime } = runtimeWith();
+ const invisible = core(() => false);
+ const visible = core(() => true);
+ runtime.updateAll(1 / 60);
+ const before = runtime.metrics()!.pose.worldMaterializations;
+
+ runtime.extractAndSubmitMeshes(invisible.core, {} as never);
+ runtime.extractAndSubmitMeshes(visible.core, {} as never);
+
+ const m = runtime.metrics()!;
+ expect(m.pose.worldMaterializations, 'a second camera re-resolved the pose').toBe(before);
+ expect(m.pose.renderCulled, 'only one of the two cameras declined it').toBe(1);
+ runtime.dispose();
+ });
+});
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index 364bfa1ac..a0f497b04 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -2,6 +2,8 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
#include "RendererBindings.hpp"
+
+#include <limits>
#include "../resource/ShaderParser.hpp"
#include "ActiveContext.hpp"
#include "BoundarySpan.hpp"
@@ -114,6 +116,42 @@ void renderer_submitSkeletalBatchByEntity(
textureId, blendMode, &model[0][0], ent, layer, depth, materialId);
}
+/**
+ * Whether the camera being rendered right now would draw this entity, given the
+ * local extent it promises to stay inside. All four corners are transformed,
+ * because under rotation the result's corners are not the input's. The frustum
+ * and mask are the frame's own — a fact, not a permission.
+ */
+void renderer_entityVisibleToCamera(
+ ecs::Registry& registry, u32 entity, i32 layer,
+ f32 minX, f32 minY, f32 maxX, f32 maxY, uintptr_t outVisiblePtr
+) {
+ auto* out = reinterpret_cast<i32*>(outVisiblePtr);
+ if (!out) return;
+ *out = 1;
+ if (!g_initialized || !g_renderFrame) return;
+ const Entity ent = Entity::fromRaw(entity);
+ if (!registry.has<ecs::Transform>(ent)) return;
+
+ auto& t = registry.get<ecs::Transform>(ent);
+ t.ensureDecomposed();
+ const glm::mat4 model = glm::translate(glm::mat4(1.0f), t.worldPosition)
+ * glm::mat4_cast(t.worldRotation)
+ * glm::scale(glm::mat4(1.0f), t.worldScale);
+
+ const glm::vec2 corners[4] = {
+ { minX, minY }, { maxX, minY }, { maxX, maxY }, { minX, maxY },
+ };
+ glm::vec3 lo{std::numeric_limits<f32>::max()};
+ glm::vec3 hi{-std::numeric_limits<f32>::max()};
+ for (const glm::vec2& corner : corners) {
+ const glm::vec4 world = model * glm::vec4(corner.x, corner.y, 0.0f, 1.0f);
+ lo = glm::min(lo, glm::vec3(world));
+ hi = glm::max(hi, glm::vec3(world));
+ }
+ *out = g_renderFrame->visibleToCamera(layer, (lo + hi) * 0.5f, (hi - lo) * 0.5f) ? 1 : 0;
+}
+
// TS lays out glyph quads against the dynamic SDF atlas and
// submits them here (ungated — text is core, unlike spine).
void renderer_submitTextBatch(
diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hpp
index e360d2033..1b5a79507 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -34,6 +34,12 @@ void renderer_end();
#endif
/// Geometry posed by a skeletal runtime (Spine, DragonBones): x,y,u,v,r,g,b,a per
/// vertex, drawn as @p entity's, with its material resolved as a Sprite's is.
+// Whether the camera being rendered right now would draw this entity's geometry
+// at the local extent it promises to stay inside. A fact, not a permission.
+void renderer_entityVisibleToCamera(
+ ecs::Registry& registry, u32 entity, i32 layer,
+ f32 minX, f32 minY, f32 maxX, f32 maxY, uintptr_t outVisiblePtr);
+
void renderer_submitSkeletalBatchByEntity(
ecs::Registry& registry,
uintptr_t verticesPtr, i32 vertexCount,
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 7c51e146e..1aff85abc 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -518,6 +518,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
// Every skeletal runtime is a side module; this is the one door their posed
// geometry comes through, so it belongs to neither of their build flags.
emscripten::function("renderer_submitSkeletalBatchByEntity", &esengine::renderer_submitSkeletalBatchByEntity);
+ emscripten::function("renderer_entityVisibleToCamera", &esengine::renderer_entityVisibleToCamera);
emscripten::function("renderer_submitTextBatch", &esengine::renderer_submitTextBatch);
emscripten::function("meshRenderer_setGeometry", &esengine::meshRenderer_setGeometry);
emscripten::function("mesh_createFromChannels", &esengine::mesh_createFromChannels);
diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cpp
index 7fbda5d02..100ccf899 100644
--- a/src/esengine/renderer/frame/RenderFrame.cpp
+++ b/src/esengine/renderer/frame/RenderFrame.cpp
@@ -1359,6 +1359,12 @@ void RenderFrame::collectSky(RenderCollectContext& ctx) {
BATCH_QUAD_INDICES, 6, key);
}
+bool RenderFrame::visibleToCamera(i32 layer, const glm::vec3& center,
+ const glm::vec3& halfExtents) const {
+ if (!draw_list_.layerVisible(DrawList::layerBit(layer))) return false;
+ return frustum_.intersectsAABB(center, halfExtents);
+}
+
void RenderFrame::collectAll(ecs::Registry& registry) {
ES_PROFILE_SCOPE("render.collect");
buildClipState();
diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hpp
index 4269182ac..996e9fd17 100644
--- a/src/esengine/renderer/frame/RenderFrame.hpp
+++ b/src/esengine/renderer/frame/RenderFrame.hpp
@@ -252,6 +252,16 @@ public:
void addPlugin(std::unique_ptr<RenderTypePlugin> plugin);
void collectAll(ecs::Registry& registry);
+ /**
+ * @brief Whether the camera being rendered right now would draw something of
+ * @p layer at these world bounds.
+ *
+ * @details The frame's OWN frustum and culling mask, both set by `begin`
+ * for the camera in hand — asked rather than reimplemented, so
+ * geometry from outside `collect` is culled by the same fact.
+ */
+ bool visibleToCamera(i32 layer, const glm::vec3& center, const glm::vec3& halfExtents) const;
+
/**
* Compiled program id for a batch-shader feature variant, compiled+cached on
* first use. `{}` is the default batch program; `{"SDF"}`