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.

fix: preserve and tightly cull native mesh placements

yhh7ba49c3903f5
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 360a3a139..873a5a951 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -33,7 +33,7 @@ env:
test_shader_device test_draw_params test_per_draw_blocks test_texture_fb test_buffer_device
test_frame_pacer test_audio_watchdog test_packaged_config test_mapped_file test_sdf_generator
test_compressed_format test_batch_builder test_skeletal_batch_color test_boundary_span test_webgpu_device
- test_clip_depth test_planar_reflection test_sort_key test_retained_text test_sprite_mask_range test_sprite_draw_mode test_shadow_atlas test_particle_shapes test_lod_selection test_billboard_facing test_impostor_frames test_view_shading test_mesh_edges test_hdr_format test_probe_store test_occlusion_view test_reflection_store test_tiled_lights test_light_layers test_shadow_channels
+ test_clip_depth test_planar_reflection test_sort_key test_retained_text test_sprite_mask_range test_sprite_draw_mode test_shadow_atlas test_particle_shapes test_lod_selection test_placement_bounds test_billboard_facing test_impostor_frames test_view_shading test_mesh_edges test_hdr_format test_probe_store test_occlusion_view test_reflection_store test_tiled_lights test_light_layers test_shadow_channels
test_text_edit test_render_graph test_device_loss test_physics_interpolation
test_bitmap_font test_texture_cache test_material_shader_lifetime test_mesh_recovery test_aot_host test_aot_conformance
test_touch_stream
@@ -103,6 +103,15 @@ jobs:
node tools/tests/planar-reflection.e2e.mjs --webgl-only --prepass
- name: Check paused and scaled render clocks with genuine headless Chromium
run: node tools/tests/render-clock.e2e.mjs --webgl-only
+ - name: Check native placement bounds with genuine headless Chromium
+ run: node tools/tests/placement-bounds.e2e.mjs --webgl-only
+ - name: Upload native placement observations
+ if: always()
+ uses: actions/upload-artifact@v7
+ with:
+ name: placement-bounds-runtime
+ path: output/placement-bounds/
+ retention-days: 3
- name: Upload render clock runtime observations
if: always()
uses: actions/upload-artifact@v7
diff --git a/docs/astro/src/content/docs/performance/static-batching.mdx b/docs/astro/src/content/docs/performance/static-batching.mdx
index 0585bf3d0..f605f3b4b 100644
--- a/docs/astro/src/content/docs/performance/static-batching.mdx
+++ b/docs/astro/src/content/docs/performance/static-batching.mdx
@@ -107,6 +107,11 @@ them are the root's children:
The root reports what it drew: **Batched parts**, **Instanced parts**, **Draws** and **Draws
before**, and **Moving parts**.
+Native instance groups, also used by foliage, bound every placement using both
+mesh LODs and the material's declared `vertexbounds`. Those bounds include
+placement rotation, scale and shear. A material that moves vertices must declare
+its full local displacement so a visible surface is not culled at a view edge.
+
Measured in the editor's Play on WebGL2, a model of 2,004 parts (1,600 planks, 400 posts and four
props) under one root:
diff --git a/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx b/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx
index 6fca03d64..7a37adff3 100644
--- a/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx
+++ b/docs/astro/src/content/docs/zh-cn/performance/static-batching.mdx
@@ -97,6 +97,9 @@ world.insert(ship, CompositeBatch, {});
根节点上会显示合并结果:**Batched parts**、**Instanced parts**、**Draws**、**Draws before** 和 **Moving parts**。
+植被和组合模型共用的原生实例组,会把两个网格 LOD 和材质声明的 `vertexbounds` 一起计入每个实例的范围,
+并覆盖实例的旋转、缩放与剪切。会移动顶点的材质必须声明完整的局部变形范围,避免仍在画面中的表面在视野边缘被剔除。
+
在编辑器 Play、WebGL2 下实测,一个根节点下 2,004 个部件(1,600 块甲板、400 根柱子、4 个道具):
| | 不加 | `CompositeBatch` |
diff --git a/fixtures/scenes/placement-bounds.esscene b/fixtures/scenes/placement-bounds.esscene
new file mode 100644
index 000000000..5c61102a0
--- /dev/null
+++ b/fixtures/scenes/placement-bounds.esscene
@@ -0,0 +1,234 @@
+{
+ "version": 4,
+ "name": "Placement Bounds",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 400
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 200,
+ "nearPlane": 1,
+ "farPlane": 2000,
+ "isActive": true,
+ "clearFlags": 3
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Individual",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": -300,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "material": "/scenes/placement-bounds/bend.esmaterial",
+ "opaque": true,
+ "lit": false,
+ "castShadows": false
+ }
+ }
+ ]
+ },
+ {
+ "id": 2,
+ "name": "Placements",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {}
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "builtin:cube",
+ "material": "/scenes/placement-bounds/bend.esmaterial",
+ "opaque": true,
+ "lit": false,
+ "castShadows": false,
+ "enabled": false
+ }
+ },
+ {
+ "type": "MeshInstances",
+ "data": {}
+ }
+ ]
+ },
+ {
+ "id": 3,
+ "name": "Coarse reference",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 350,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "/scenes/placement-bounds/coarse.esmesh",
+ "material": "/scenes/placement-bounds/plain.esmaterial",
+ "opaque": true,
+ "lit": false,
+ "castShadows": false,
+ "cullBackfaces": false,
+ "enabled": false
+ }
+ }
+ ]
+ },
+ {
+ "id": 4,
+ "name": "Coarse placements",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "/scenes/placement-bounds/fine.esmesh",
+ "material": "/scenes/placement-bounds/plain.esmaterial",
+ "opaque": true,
+ "lit": false,
+ "castShadows": false,
+ "cullBackfaces": false,
+ "enabled": false
+ }
+ },
+ {
+ "type": "MeshInstances",
+ "data": {
+ "lod1Mesh": "/scenes/placement-bounds/coarse.esmesh",
+ "lodDistance": 1
+ }
+ }
+ ]
+ },
+ {
+ "id": 5,
+ "name": "Rotated reference",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 350,
+ "z": 0
+ },
+ "rotation": {
+ "x": 0,
+ "y": 0,
+ "z": 0.7071067811865476,
+ "w": 0.7071067811865476
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "/scenes/placement-bounds/coarse.esmesh",
+ "material": "/scenes/placement-bounds/plain.esmaterial",
+ "opaque": true,
+ "lit": false,
+ "castShadows": false,
+ "cullBackfaces": false,
+ "enabled": false
+ }
+ }
+ ]
+ },
+ {
+ "id": 6,
+ "name": "Rotated placements",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ }
+ }
+ },
+ {
+ "type": "MeshRenderer",
+ "data": {
+ "mesh": "/scenes/placement-bounds/coarse.esmesh",
+ "material": "/scenes/placement-bounds/plain.esmaterial",
+ "opaque": true,
+ "lit": false,
+ "castShadows": false,
+ "cullBackfaces": false,
+ "enabled": false
+ }
+ },
+ {
+ "type": "MeshInstances",
+ "data": {}
+ }
+ ]
+ }
+ ]
+}
diff --git a/fixtures/scenes/placement-bounds/bend.esmaterial b/fixtures/scenes/placement-bounds/bend.esmaterial
new file mode 100644
index 000000000..e96a3d514
--- /dev/null
+++ b/fixtures/scenes/placement-bounds/bend.esmaterial
@@ -0,0 +1,9 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "bend.esshader",
+ "properties": {},
+ "blendMode": 0,
+ "depthTest": true,
+ "depthWrite": true
+}
diff --git a/fixtures/scenes/placement-bounds/bend.esshader b/fixtures/scenes/placement-bounds/bend.esshader
new file mode 100644
index 000000000..1705526c6
--- /dev/null
+++ b/fixtures/scenes/placement-bounds/bend.esshader
@@ -0,0 +1,30 @@
+#pragma shader "PlacementBounds"
+#pragma version 300 es
+#pragma domain Unlit
+#pragma vertexbounds 300
+
+#pragma vertexoffset
+void esMaterialVertex(inout vec3 local, inout vec3 localNormal, in vec2 uv) {
+ local.x += 300.0;
+}
+#pragma end
+
+#pragma vertexoffset wgsl
+fn esMaterialVertex(local: ptr<function, vec3f>, localNormal: ptr<function, vec3f>, uv: vec2f) {
+ (*local).x += 300.0;
+}
+#pragma end
+
+#pragma fragment
+precision highp float;
+out vec4 fragColor;
+void main() {
+ fragColor = vec4(0.0, 1.0, 0.0, 1.0);
+}
+#pragma end
+
+#pragma fragment wgsl
+@fragment fn fs_main(v: VSOut) -> @location(0) vec4f {
+ return vec4f(0.0, 1.0, 0.0, 1.0);
+}
+#pragma end
diff --git a/fixtures/scenes/placement-bounds/coarse.esmesh b/fixtures/scenes/placement-bounds/coarse.esmesh
new file mode 100644
index 000000000..416e0fa0d
Binary files /dev/null and b/fixtures/scenes/placement-bounds/coarse.esmesh differ
diff --git a/fixtures/scenes/placement-bounds/fine.esmesh b/fixtures/scenes/placement-bounds/fine.esmesh
new file mode 100644
index 000000000..4cf135b9b
Binary files /dev/null and b/fixtures/scenes/placement-bounds/fine.esmesh differ
diff --git a/fixtures/scenes/placement-bounds/plain.esmaterial b/fixtures/scenes/placement-bounds/plain.esmaterial
new file mode 100644
index 000000000..5eace99ea
--- /dev/null
+++ b/fixtures/scenes/placement-bounds/plain.esmaterial
@@ -0,0 +1,9 @@
+{
+ "version": "1.0",
+ "type": "material",
+ "shader": "plain.esshader",
+ "properties": {},
+ "blendMode": 0,
+ "depthTest": true,
+ "depthWrite": true
+}
diff --git a/fixtures/scenes/placement-bounds/plain.esshader b/fixtures/scenes/placement-bounds/plain.esshader
new file mode 100644
index 000000000..5274f4a5b
--- /dev/null
+++ b/fixtures/scenes/placement-bounds/plain.esshader
@@ -0,0 +1,17 @@
+#pragma shader "PlacementBoundsPlain"
+#pragma version 300 es
+#pragma domain Unlit
+
+#pragma fragment
+precision highp float;
+out vec4 fragColor;
+void main() {
+ fragColor = vec4(0.0, 1.0, 0.0, 1.0);
+}
+#pragma end
+
+#pragma fragment wgsl
+@fragment fn fs_main(v: VSOut) -> @location(0) vec4f {
+ return vec4f(0.0, 1.0, 0.0, 1.0);
+}
+#pragma end
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index a444682f9..767bd09ad 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -19,6 +19,7 @@
#include "../renderer/frame/RenderStage.hpp"
#include "../renderer/draw/ImmediateDraw.hpp"
#include "../renderer/draw/CustomGeometry.hpp"
+#include "../renderer/draw/PlacementBounds.hpp"
#include "../renderer/draw/TextVertexFormat.hpp"
#include "../resource/ResourceManager.hpp"
#include "../ecs/GroupOpacityLookup.hpp"
@@ -391,11 +392,7 @@ void meshInstances_set(ecs::Registry& registry, u32 entity, uintptr_t dataPtr, u
const glm::vec3 at(r[3], r[7], r[11]);
mn = glm::min(mn, at);
mx = glm::max(mx, at);
- // The longest column of the linear part: how far the instance stretches its mesh.
- const f32 c0 = r[0] * r[0] + r[4] * r[4] + r[8] * r[8];
- const f32 c1 = r[1] * r[1] + r[5] * r[5] + r[9] * r[9];
- const f32 c2 = r[2] * r[2] + r[6] * r[6] + r[10] * r[10];
- scale = std::max(scale, std::max(c0, std::max(c1, c2)));
+ scale = std::max(scale, placement_bounds::stretchSquared(r));
}
set->originMin = mn;
set->originMax = mx;
diff --git a/src/esengine/renderer/draw/PlacementBounds.hpp b/src/esengine/renderer/draw/PlacementBounds.hpp
new file mode 100644
index 000000000..12c52854b
--- /dev/null
+++ b/src/esengine/renderer/draw/PlacementBounds.hpp
@@ -0,0 +1,45 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file PlacementBounds.hpp
+ * @brief Conservative mesh reach and affine stretch for native placements.
+ */
+#pragma once
+
+#include "../../core/Types.hpp"
+#include <glm/glm.hpp>
+#include <algorithm>
+#include <cmath>
+
+namespace esengine::placement_bounds {
+
+/** Radius about the placement origin, including the material's local displacement. */
+inline f32 radius(const glm::vec3& lo, const glm::vec3& hi, f32 displacement) {
+ return glm::length(glm::max(glm::abs(lo), glm::abs(hi)) + glm::vec3(std::max(displacement, 0.0f)));
+}
+
+/** Squared stretch bound for the linear part of a row-major 3x4 placement. */
+inline f32 stretchSquared(const f32* rows) {
+ const glm::vec3 a(rows[0], rows[4], rows[8]);
+ const glm::vec3 b(rows[1], rows[5], rows[9]);
+ const glm::vec3 c(rows[2], rows[6], rows[10]);
+ const f32 ab = std::abs(glm::dot(a, b));
+ const f32 ac = std::abs(glm::dot(a, c));
+ const f32 bc = std::abs(glm::dot(b, c));
+ // The maximum absolute row sum of A^T A bounds its largest eigenvalue.
+ // Orthogonal TRS columns retain the exact longest scale; shears remain conservative.
+ return std::max({glm::dot(a, a) + ab + ac, glm::dot(b, b) + ab + bc, glm::dot(c, c) + ac + bc});
+}
+
+/** Transforms a local box through the complete placement and parent linear transforms. */
+inline void transformedBox(const glm::mat3& parent, const f32* rows, const glm::vec3& origin,
+ const glm::vec3& localCentre, const glm::vec3& localHalf,
+ glm::vec3& centre, glm::vec3& half) {
+ const glm::vec3 a = parent * glm::vec3(rows[0], rows[4], rows[8]);
+ const glm::vec3 b = parent * glm::vec3(rows[1], rows[5], rows[9]);
+ const glm::vec3 c = parent * glm::vec3(rows[2], rows[6], rows[10]);
+ centre = origin + a * localCentre.x + b * localCentre.y + c * localCentre.z;
+ half = glm::abs(a) * localHalf.x + glm::abs(b) * localHalf.y + glm::abs(c) * localHalf.z;
+}
+
+} // namespace esengine::placement_bounds
diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cpp
index 5837c83fd..0c86df618 100644
--- a/src/esengine/renderer/plugins/MeshPlugin.cpp
+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp
@@ -15,6 +15,7 @@
#include "../../ecs/components/Billboard.hpp"
#include "../draw/BillboardFacing.hpp"
#include "../draw/ImpostorFrames.hpp"
+#include "../draw/PlacementBounds.hpp"
#include "../draw/BatchBuilder.hpp"
#include "../../ecs/components/Impostor.hpp"
#include "../../resource/Mesh.hpp"
@@ -612,32 +613,32 @@ void emitImpostorCard(RenderCollectContext& collect, const RenderFrame::Impostor
template <typename Emit>
void emitPlacements(const RenderFrameContext& ctx, RenderCollectContext& collect, const ecs::MeshInstances& set,
const ecs::MeshRenderer& mesh, const glm::vec3& position, const glm::quat& rotation,
- const glm::vec3& scale, const Mesh& fine, const Mesh* coarse, u32& records, Emit&& emit) {
+ const glm::vec3& scale, const Mesh& fine, const Mesh* coarse,
+ const glm::vec3& localCentre, const glm::vec3& localHalf, u32& records, Emit&& emit) {
static thread_local std::vector<u32> nearList, farList;
nearList.clear();
farList.clear();
const glm::mat4 entityModel = glm::translate(glm::mat4(1.0f), position) * glm::mat4_cast(rotation) * glm::scale(glm::mat4(1.0f), scale);
- const f32 entityScale = std::max(std::abs(scale.x), std::max(std::abs(scale.y), std::abs(scale.z)));
- const f32 reach = glm::length(glm::max(glm::abs(fine.localMin), glm::abs(fine.localMax)));
+ const glm::mat3 entityLinear(entityModel);
const bool eyeKnown = ctx.has_view_eye;
const u32 count = static_cast<u32>(set.transforms.size() / 16);
u32 tooFar = 0, outside = 0;
for (u32 i = 0; i < count; ++i) {
const f32* r = set.transforms.data() + static_cast<usize>(i) * 16;
const glm::vec3 at = glm::vec3(entityModel * glm::vec4(r[3], r[7], r[11], 1.0f));
- const f32 c0 = r[0] * r[0] + r[4] * r[4] + r[8] * r[8];
- const f32 c1 = r[1] * r[1] + r[5] * r[5] + r[9] * r[9];
- const f32 c2 = r[2] * r[2] + r[6] * r[6] + r[10] * r[10];
- const f32 radius = reach * std::sqrt(std::max(c0, std::max(c1, c2))) * entityScale;
+ glm::vec3 centre, half;
+ placement_bounds::transformedBox(entityLinear, r, at, localCentre, localHalf, centre, half);
+ const f32 radius = glm::length(half);
f32 distance = 0.0f;
if (eyeKnown) {
distance = glm::distance(at, ctx.view_eye);
- if (set.drawDistance > 0.0f && distance - radius > set.drawDistance) { ++tooFar; continue; }
- if (distance + radius < set.minDistance) continue;
- if (ctx.purpose == RenderPurpose::ShadowDepth && set.shadowDistance > 0.0f && distance - radius > set.shadowDistance) continue;
+ const f32 centreDistance = glm::distance(centre, ctx.view_eye);
+ if (set.drawDistance > 0.0f && centreDistance - radius > set.drawDistance) { ++tooFar; continue; }
+ if (centreDistance + radius < set.minDistance) continue;
+ if (ctx.purpose == RenderPurpose::ShadowDepth && set.shadowDistance > 0.0f && centreDistance - radius > set.shadowDistance) continue;
}
- if (!collect.visible(at, glm::vec3(radius), false)) { ++outside; continue; }
- if (ctx.purpose == RenderPurpose::ShadowDepth && !collect.castsIntoView(at, radius)) { ++outside; continue; }
+ if (!collect.visible(centre, half, false)) { ++outside; continue; }
+ if (ctx.purpose == RenderPurpose::ShadowDepth && !collect.castsIntoView(centre, radius)) { ++outside; continue; }
(coarse && eyeKnown && set.lodDistance > 0.0f && distance > set.lodDistance ? farList : nearList).push_back(i);
}
ES_PROFILE_COUNTER("render.placements.seen", count);
@@ -813,16 +814,6 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
}
}
}
- // A set of placements is bounded by where they stand, grown by how far the mesh reaches from its origin at the greatest scale.
- const glm::vec3 reach = (placements ? glm::max(glm::abs(resident->localMin), glm::abs(resident->localMax)) * placements->maxScale
- : glm::vec3(0.0f));
- const glm::vec3 localMin = placements ? placements->originMin - reach
- : group ? levels.localMin
- : resident ? resident->localMin : glm::vec3(mesh.localMin, 0.0f);
- const glm::vec3 localMax = placements ? placements->originMax + reach
- : group ? levels.localMax
- : resident ? resident->localMax : glm::vec3(mesh.localMax, 0.0f);
-
// BEFORE the cull, because whether this draw depth-tests decides if an
// occluder may refuse it, and the material is where that is finally said.
// Reused by the draw key below: two lookups is how the two come to differ.
@@ -833,8 +824,32 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
const f32 bend = material ? ctx.materials->vertexBounds(mesh.material) : 0.0f;
const bool depthTested = mesh.opaque || (material && material->depthTest);
+ const Mesh* placementCoarse = placements && placements->lod1Mesh.isValid()
+ ? ctx.resources.getMesh(placements->lod1Mesh) : nullptr;
+ if (placementCoarse && (!placementCoarse->isDrawable() || placementCoarse->hasNormals != resident->hasNormals
+ || placementCoarse->hasTangents != resident->hasTangents
+ || placementCoarse->hasLightmapUV != resident->hasLightmapUV)) placementCoarse = nullptr;
+ f32 placementRadius = 0.0f;
+ glm::vec3 placementCentre(0.0f), placementHalf(0.0f);
+ if (placements) {
+ const glm::vec3 lo = placementCoarse ? glm::min(resident->localMin, placementCoarse->localMin) : resident->localMin;
+ const glm::vec3 hi = placementCoarse ? glm::max(resident->localMax, placementCoarse->localMax) : resident->localMax;
+ placementRadius = placement_bounds::radius(lo, hi, bend);
+ placementCentre = (lo + hi) * 0.5f;
+ placementHalf = (hi - lo) * 0.5f + glm::vec3(bend);
+ }
+ // Placements can rotate or shear independently. One origin-centred sphere includes both LODs and local deformation.
+ const glm::vec3 reach(placements ? placementRadius * placements->maxScale : 0.0f);
+ const glm::vec3 localMin = placements ? placements->originMin - reach
+ : group ? levels.localMin
+ : resident ? resident->localMin : glm::vec3(mesh.localMin, 0.0f);
+ const glm::vec3 localMax = placements ? placements->originMax + reach
+ : group ? levels.localMax
+ : resident ? resident->localMax : glm::vec3(mesh.localMax, 0.0f);
+ const glm::vec3 padding(placements ? 0.0f : bend);
+
glm::vec3 aabbCenter(0.0f), halfExtents(0.0f);
- orientedWorldAabb(position, rotation, scale, localMin - glm::vec3(bend), localMax + glm::vec3(bend),
+ orientedWorldAabb(position, rotation, scale, localMin - padding, localMax + padding,
aabbCenter, halfExtents);
// The collect's own predicate, not a frustum test of this plugin's: it
// answers "outside the view" AND "behind something solid", and a mesh is
@@ -1211,12 +1226,8 @@ void MeshPlugin::collect(RenderCollectContext& collect_ctx) {
};
if (placements) {
// The record written for the entity above is not drawn: the instances are, each with a record of its own.
- const Mesh* coarse = placements->lod1Mesh.isValid() ? ctx.resources.getMesh(placements->lod1Mesh) : nullptr;
- if (coarse && (!coarse->isDrawable() || coarse->hasNormals != resident->hasNormals
- || coarse->hasTangents != resident->hasTangents || coarse->hasLightmapUV != resident->hasLightmapUV)) {
- coarse = nullptr;
- }
- emitPlacements(ctx, collect_ctx, *placements, mesh, position, rotation, scale, *resident, coarse, instanceRecords, emit);
+ emitPlacements(ctx, collect_ctx, *placements, mesh, position, rotation, scale, *resident, placementCoarse,
+ placementCentre, placementHalf, instanceRecords, emit);
continue;
}
key.vertexBuffer = resident->vertexBuffer;
diff --git a/tests/CMakeLists.txt b/tests/CMakeLists.txt
index aa75e3a3e..5e3643ce7 100644
--- a/tests/CMakeLists.txt
+++ b/tests/CMakeLists.txt
@@ -414,6 +414,13 @@ target_include_directories(test_lod_selection PRIVATE
)
add_test(NAME test_lod_selection COMMAND test_lod_selection)
+add_executable(test_placement_bounds renderer/test_placement_bounds.cpp)
+target_include_directories(test_placement_bounds PRIVATE
+ ${CMAKE_SOURCE_DIR}/src
+ ${CMAKE_SOURCE_DIR}/third_party/glm
+)
+add_test(NAME test_placement_bounds COMMAND test_placement_bounds)
+
# How a Billboard is turned to a view: the view plane, upright about world up, an orthographic view. Header-only.
add_executable(test_billboard_facing renderer/test_billboard_facing.cpp)
target_include_directories(test_billboard_facing PRIVATE
diff --git a/tests/renderer/test_placement_bounds.cpp b/tests/renderer/test_placement_bounds.cpp
new file mode 100644
index 000000000..07ffb808b
--- /dev/null
+++ b/tests/renderer/test_placement_bounds.cpp
@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file test_placement_bounds.cpp
+ * @brief Check placement bounds against transformed geometry, including affine shear.
+ */
+#include "esengine/renderer/draw/PlacementBounds.hpp"
+#include <glm/gtc/matrix_transform.hpp>
+#include <cstdio>
+#include <array>
+
+using namespace esengine;
+
+int main() {
+ int failures = 0;
+ const auto check = [&](bool ok, const char* message) {
+ std::printf("%s: %s\n", ok ? "ok" : "FAIL", message);
+ if (!ok) ++failures;
+ };
+ const auto rowsOf = [](const glm::mat4& matrix) {
+ std::array<f32, 12> rows{};
+ for (int r = 0; r < 3; ++r) for (int c = 0; c < 4; ++c) rows[r * 4 + c] = matrix[c][r];
+ return rows;
+ };
+ const auto trs = rowsOf(glm::scale(glm::rotate(glm::mat4(1), 0.73f, glm::normalize(glm::vec3(1, 2, 3))), glm::vec3(2, -3, 0.5f)));
+ check(std::abs(placement_bounds::stretchSquared(trs.data()) - 9.0f) < 1e-5f, "rotated signed TRS keeps its exact largest scale");
+ const f32 shear[12] = {1, 1, 1, 500, 0, 0.1f, 0, -500, 0, 0, 0.1f, 100};
+ const glm::vec3 diagonal = glm::normalize(glm::vec3(1));
+ const glm::vec3 sheared(diagonal.x + diagonal.y + diagonal.z, diagonal.y * 0.1f, diagonal.z * 0.1f);
+ check(glm::dot(sheared, sheared) > 1.01f, "longest column alone underestimates an affine shear");
+ check(placement_bounds::stretchSquared(shear) >= glm::dot(sheared, sheared), "shared stretch bound contains the sheared diagonal");
+ const f32 zero[12]{};
+ check(placement_bounds::stretchSquared(zero) == 0.0f, "collapsed placements have zero stretch");
+
+ const glm::vec3 lo(-300, -10, 0), hi(300, 10, 0);
+ const f32 radius = placement_bounds::radius(lo, hi, 40);
+ bool contained = true;
+ for (int mask = 0; mask < 8; ++mask) {
+ glm::vec3 corner;
+ for (int axis = 0; axis < 3; ++axis) corner[axis] = (mask & (1 << axis)) ? hi[axis] + 40 : lo[axis] - 40;
+ contained &= glm::length(corner) <= radius + 1e-4f;
+ }
+ check(contained, "origin radius contains every displaced corner of an elongated mesh");
+ check(placement_bounds::radius(lo, hi, -1) == placement_bounds::radius(lo, hi, 0), "negative displacement cannot shrink authored bounds");
+
+ u32 seed = 42;
+ const auto random = [&]() { seed = seed * 1664525u + 1013904223u; return static_cast<f32>(seed >> 8) / 16777216.0f * 8.0f - 4.0f; };
+ bool allContained = true;
+ for (int i = 0; i < 10000; ++i) {
+ f32 rows[12];
+ for (f32& value : rows) value = random();
+ const glm::vec3 v(random(), random(), random());
+ const glm::vec3 transformed(rows[0] * v.x + rows[1] * v.y + rows[2] * v.z,
+ rows[4] * v.x + rows[5] * v.y + rows[6] * v.z,
+ rows[8] * v.x + rows[9] * v.y + rows[10] * v.z);
+ allContained &= glm::dot(transformed, transformed) <= placement_bounds::stretchSquared(rows) * glm::dot(v, v) + 1e-3f;
+ }
+ check(allContained, "10000 arbitrary affine placements contain independently transformed points");
+ const glm::mat3 parent(glm::rotate(glm::scale(glm::mat4(1), glm::vec3(2, 3, 0.5f)), 0.8f, glm::vec3(0, 0, 1)));
+ const glm::vec3 origin(500, -700, 30), localCentre(120, -30, 8), localHalf(10, 40, 2);
+ glm::vec3 centre, half;
+ placement_bounds::transformedBox(parent, shear, origin, localCentre, localHalf, centre, half);
+ bool boxContains = true;
+ for (int mask = 0; mask < 8; ++mask) {
+ glm::vec3 corner = localCentre;
+ for (int axis = 0; axis < 3; ++axis) corner[axis] += ((mask & (1 << axis)) ? 1 : -1) * localHalf[axis];
+ const glm::vec3 placed(corner.x + corner.y + corner.z, corner.y * 0.1f, corner.z * 0.1f);
+ const glm::vec3 actual = origin + parent * placed;
+ boxContains &= glm::all(glm::lessThanEqual(glm::abs(actual - centre), half + glm::vec3(1e-3f)));
+ }
+ check(boxContains, "tight box contains offset geometry under parent scale, rotation and placement shear");
+ return failures ? 1 : 0;
+}
diff --git a/tools/render-host/host.ts b/tools/render-host/host.ts
index 317ca5031..5aaa21fc2 100644
--- a/tools/render-host/host.ts
+++ b/tools/render-host/host.ts
@@ -455,6 +455,26 @@ const api = {
/** Waits for submitted shader variants without advancing the simulation clock. */
waitForShaders: () => shadersCompiled(module),
+ /** Uploads the native row-major placement records used by foliage and composite batches. */
+ setMeshPlacements(id: number, values: number[]): void {
+ if (!module?.meshInstances_set || values.length % 16 !== 0 || values.some(v => !Number.isFinite(v))) {
+ throw new Error('setMeshPlacements: expected finite sixteen-float native records');
+ }
+ const entity = requireEntity(id);
+ const instances = getComponent('MeshInstances');
+ if (!instances) throw new Error('setMeshPlacements: MeshInstances is unavailable');
+ if (!app!.world.has(entity, instances)) app!.world.insert(entity, instances, {});
+ const data = new Float32Array(values);
+ const ptr = module._malloc(Math.max(4, data.byteLength));
+ if (!ptr) throw new Error('setMeshPlacements: allocation failed');
+ try {
+ new Float32Array(module.HEAPU8.buffer, ptr, data.length).set(data);
+ module.meshInstances_set(app!.world.getCppRegistry()!, entity, ptr, values.length / 16);
+ } finally {
+ module._free(ptr);
+ }
+ },
+
/**
* The frame as the ENGINE holds it, whichever backend drew it. captureViewport
* reads the page instead, which on WebGPU is a compositor copy — blank in a
diff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjs
index f0e372b54..a384b3155 100644
--- a/tools/render-host/run.mjs
+++ b/tools/render-host/run.mjs
@@ -293,6 +293,11 @@ app.whenReady().then(async () => {
);
// Opt-in play mode (ESTELLA_VERIFY_PLAY=1): runs the SDK plugin updates — particle
// emission/simulation, animation — so time-driven content actually renders.
+ if (process.env.ESTELLA_VERIFY_PLACEMENTS) {
+ for (const { entity, transforms } of JSON.parse(process.env.ESTELLA_VERIFY_PLACEMENTS)) {
+ await exec(`window.__estellaHeadless.api.setMeshPlacements(${Number(entity)}, ${JSON.stringify(transforms)})`);
+ }
+ }
if (process.env.ESTELLA_VERIFY_PLAY === '1') {
await exec('window.__estellaHeadless.api.setRunMode(true)');
}
diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjs
index 7171dda70..a00532233 100644
--- a/tools/renderScenes.mjs
+++ b/tools/renderScenes.mjs
@@ -56,6 +56,27 @@ export function sceneWatchdogMs(backend, host) {
* verbatim — an empty one is the default sprite scene.
*/
export const SCENES = [
+ ...[
+ { id: 'placements-bent', entity: 2, projection: 1, records: [1, 0, 0, -300, 0, 1, 0, 0, 0, 0, 1, 0, 1, 1, 1, 1], x: 0.5, y: 0.5, coarse: 0 },
+ { id: 'placements-bent-scaled', entity: 2, projection: 1, records: [3, 0, 0, -900, 0, 3, 0, 0, 0, 0, 3, 0, 1, 1, 1, 1], x: 0.5, y: 0.5, coarse: 0 },
+ { id: 'placements-coarse-bounds', entity: 4, projection: 0, records: [1, 0, 0, 350, 0, 1, 0, 0, 0, 0, 1, 0, 1, 1, 1, 1], x: 0.9, y: 0.5, coarse: 1 },
+ { id: 'placements-rotated-bounds', entity: 6, projection: 1, records: [0, -1, 0, 0, 1, 0, 0, 350, 0, 0, 1, 0, 1, 1, 1, 1], x: 0.5, y: 0.1, coarse: 0 },
+ { id: 'placements-tight-bounds', entity: 6, projection: 1, records: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 1, 1, 1, 1, 1, 0, 0, 0, 0, 1, 0, 350, 0, 0, 1, 0, 1, 1, 1, 1], x: 0.5, y: 0.5, coarse: 0, outside: 1 },
+ ].map(test => ({
+ id: test.id, tier: 'pr', webgpu: true,
+ env: {
+ ESTELLA_VERIFY_SCENE: '/scenes/placement-bounds.esscene',
+ ESTELLA_VERIFY_W: '256', ESTELLA_VERIFY_H: '256', ESTELLA_VERIFY_STEPS: '3',
+ ESTELLA_VERIFY_PLACEMENTS: JSON.stringify([{ entity: test.entity, transforms: test.records }]),
+ ESTELLA_VERIFY_SET_FIELD: JSON.stringify([
+ { entity: 0, component: 'Camera', key: 'projectionType', value: test.projection },
+ { entity: 1, component: 'MeshRenderer', key: 'enabled', value: false },
+ { entity: test.entity, component: 'MeshRenderer', key: 'enabled', value: true },
+ ]),
+ ESTELLA_VERIFY_EXPECT: JSON.stringify([{ x: test.x, y: test.y, rgb: [0, 255, 0], tol: 2 }]),
+ ESTELLA_VERIFY_COUNTERS: JSON.stringify({ 'render.placements.seen': test.records.length / 16, 'render.placements.outside': test.outside ?? 0, 'render.placements.coarse': test.coarse }),
+ },
+ })),
{
id: 'render-clock', tier: 'pr',
// WebGPU captures the next frame; GL reads the already completed frame.
diff --git a/tools/tests/placement-bounds.e2e.mjs b/tools/tests/placement-bounds.e2e.mjs
new file mode 100644
index 000000000..ba8a35b3e
--- /dev/null
+++ b/tools/tests/placement-bounds.e2e.mjs
@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file placement-bounds.e2e.mjs
+ * @brief Compare native instance culling with individual deformed meshes.
+ */
+import { chromium } from 'playwright';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import assert from 'node:assert/strict';
+import { serveHost } from '../lib/staticServer.mjs';
+import { requireCurrentEngine } from '../lib/engineBuild.mjs';
+
+const { PNG } = createRequire(new URL('../../pipeline/package.json', import.meta.url))('pngjs');
+const repo = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+const out = path.join(repo, 'output/placement-bounds');
+const host = path.join(repo, 'build/render-host');
+requireCurrentEngine(repo, path.join(host, 'wasm'));
+await mkdir(out, { recursive: true });
+const server = await serveHost(host);
+const browser = await chromium.launch({
+ channel: 'chromium', headless: true,
+ args: ['--enable-unsafe-webgpu', '--ignore-gpu-blocklist', '--enable-unsafe-swiftshader', '--mute-audio'],
+});
+const report = { status: 'failed', checks: [] };
+try {
+ const backends = process.argv.includes('--webgl-only') ? ['webgl2'] : ['webgl2', 'webgpu'];
+ for (const backend of backends) {
+ const page = await browser.newPage({ viewport: { width: 256, height: 256 } });
+ const errors = [];
+ page.on('pageerror', error => errors.push(String(error)));
+ page.on('console', message => { if (message.type() === 'error') errors.push(message.text()); });
+ await page.route('**/favicon.ico', route => route.fulfill({ status: 204 }));
+ await page.goto(`http://127.0.0.1:${server.address().port}/?w=256&h=256&backend=${backend}`);
+ await page.evaluate(async () => { await window.__estellaHeadless.ready; });
+ const loaded = await page.evaluate(() => window.__estellaHeadless.api.loadScene('/scenes/placement-bounds.esscene'));
+ assert.deepEqual(loaded.missing, []);
+ await page.evaluate(() => window.__estellaHeadless.api.setCpuProfiling(true));
+ const capture = async label => {
+ const raw = await page.evaluate(async () => {
+ const { api } = window.__estellaHeadless;
+ await api.step(2);
+ if (!await api.waitForShaders()) throw new Error('Shader compilation did not complete');
+ await api.step(1);
+ const image = await api.captureViewportPixels();
+ return { width: image.width, height: image.height, rgba: Array.from(image.rgba), counters: api.getCounters() };
+ });
+ const image = new PNG({ width: raw.width, height: raw.height });
+ const bytes = Buffer.from(raw.rgba), stride = raw.width * 4;
+ for (let y = 0; y < raw.height; y++) {
+ bytes.copy(image.data, y * stride, (raw.height - 1 - y) * stride, (raw.height - y) * stride);
+ }
+ await writeFile(path.join(out, `${backend}-${label}.png`), PNG.sync.write(image));
+ let green = 0;
+ for (let i = 0; i < image.data.length; i += 4) {
+ if (image.data[i + 1] > 200 && image.data[i] < 20 && image.data[i + 2] < 20) green++;
+ }
+ return { image, green, counters: raw.counters };
+ };
+ for (const scale of [1, 3]) {
+ await page.evaluate(async scale => {
+ const { api } = window.__estellaHeadless;
+ await api.setField(1, 'Transform', 'position', '', { x: -300 * scale, y: 0, z: 0 });
+ await api.setField(1, 'Transform', 'scale', '', { x: scale, y: scale, z: scale });
+ await api.setField(1, 'MeshRenderer', 'enabled', '', true);
+ await api.setField(2, 'MeshRenderer', 'enabled', '', false);
+ api.setMeshPlacements(2, [scale, 0, 0, -300 * scale, 0, scale, 0, 0, 0, 0, scale, 0, 1, 1, 1, 1]);
+ }, scale);
+ const individual = await capture(`scale-${scale}-individual`);
+ assert.ok(individual.green > 1000, 'The individual deformed mesh must be visible');
+ await page.evaluate(async () => {
+ const { api } = window.__estellaHeadless;
+ await api.setField(1, 'MeshRenderer', 'enabled', '', false);
+ await api.setField(2, 'MeshRenderer', 'enabled', '', true);
+ });
+ const placements = await capture(`scale-${scale}-instances`);
+ let changed = 0;
+ for (let i = 0; i < individual.image.data.length; i += 4) {
+ if ([0, 1, 2].some(c => individual.image.data[i + c] !== placements.image.data[i + c])) changed++;
+ }
+ report.checks.push({ backend, scale, individualGreen: individual.green, instancesGreen: placements.green,
+ changed, counters: placements.counters });
+ }
+ for (const test of [
+ { name: 'coarse-bounds', reference: 3, placed: 4, record: [1, 0, 0, 350, 0, 1, 0, 0, 0, 0, 1, 0, 1, 1, 1, 1] },
+ { name: 'rotated-bounds', reference: 5, placed: 6, record: [0, -1, 0, 0, 1, 0, 0, 350, 0, 0, 1, 0, 1, 1, 1, 1] },
+ { name: 'tight-bounds', reference: 5, placed: 6, outside: 1,
+ record: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 1, 1, 1, 1,
+ 1, 0, 0, 0, 0, 1, 0, 350, 0, 0, 1, 0, 1, 1, 1, 1] },
+ ]) {
+ await page.evaluate(async test => {
+ const { api } = window.__estellaHeadless;
+ await api.setField(0, 'Camera', 'projectionType', '', test.name === 'coarse-bounds' ? 0 : 1);
+ if (test.name === 'tight-bounds') {
+ await api.setField(5, 'Transform', 'position', '', { x: 0, y: 0, z: 0 });
+ await api.setField(5, 'Transform', 'rotation', '', { x: 0, y: 0, z: 0, w: 1 });
+ }
+ for (let id = 1; id <= 6; id++) await api.setField(id, 'MeshRenderer', 'enabled', '', id === test.reference);
+ api.setMeshPlacements(test.placed, test.record);
+ }, test);
+ const individual = await capture(`${test.name}-individual`);
+ assert.ok(individual.green > 20, 'The reference surface must intersect the view');
+ await page.evaluate(async test => {
+ const { api } = window.__estellaHeadless;
+ await api.setField(test.reference, 'MeshRenderer', 'enabled', '', false);
+ await api.setField(test.placed, 'MeshRenderer', 'enabled', '', true);
+ }, test);
+ const placements = await capture(`${test.name}-instances`);
+ let changed = 0;
+ for (let i = 0; i < individual.image.data.length; i += 4) {
+ if ([0, 1, 2].some(c => Math.abs(individual.image.data[i + c] - placements.image.data[i + c]) > 2)) changed++;
+ }
+ report.checks.push({ backend, name: test.name, individualGreen: individual.green,
+ instancesGreen: placements.green, changed, counters: placements.counters,
+ correctCull: placements.counters['render.placements.outside'] === (test.outside ?? 0) });
+ }
+ assert.deepEqual(errors, []);
+ await page.close();
+ }
+ assert.ok(report.checks.every(row => row.changed === 0 && row.correctCull !== false),
+ 'Instancing must preserve visible geometry and reject placements outside the view');
+ report.status = 'checks-passed';
+ console.log(JSON.stringify(report));
+} catch (error) {
+ report.error = String(error);
+ throw error;
+} finally {
+ await writeFile(path.join(out, 'report.json'), JSON.stringify(report, null, 2));
+ await browser.close();
+ await new Promise(resolve => server.close(resolve));
+}