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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
fix: preserve and tightly cull native mesh placements
yhh7ba49c3903f5
diff --git a/.github/workflows/build.yml b/.github/workflows/build.ymlindex 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_devicetest_frame_pacer test_audio_watchdog test_packaged_config test_mapped_file test_sdf_generatortest_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_channelstest_text_edit test_render_graph test_device_loss test_physics_interpolationtest_bitmap_font test_texture_cache test_material_shader_lifetime test_mesh_recovery test_aot_host test_aot_conformancetest_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 Chromiumrun: 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 observationsif: always()uses: actions/upload-artifact@v7diff --git a/docs/astro/src/content/docs/performance/static-batching.mdx b/docs/astro/src/content/docs/performance/static-batching.mdxindex 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 **Drawsbefore**, 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 fourprops) 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.mdxindex 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.esscenenew file mode 100644index 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.esmaterialnew file mode 100644index 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.esshadernew file mode 100644index 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 enddiff --git a/fixtures/scenes/placement-bounds/coarse.esmesh b/fixtures/scenes/placement-bounds/coarse.esmeshnew file mode 100644index 000000000..416e0fa0dBinary files /dev/null and b/fixtures/scenes/placement-bounds/coarse.esmesh differdiff --git a/fixtures/scenes/placement-bounds/fine.esmesh b/fixtures/scenes/placement-bounds/fine.esmeshnew file mode 100644index 000000000..4cf135b9bBinary files /dev/null and b/fixtures/scenes/placement-bounds/fine.esmesh differdiff --git a/fixtures/scenes/placement-bounds/plain.esmaterial b/fixtures/scenes/placement-bounds/plain.esmaterialnew file mode 100644index 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.esshadernew file mode 100644index 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 enddiff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex 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, uconst 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.hppnew file mode 100644index 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_boundsdiff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cppindex 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::Impostortemplate <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.txtindex 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 PRIVATEdiff --git a/tests/renderer/test_placement_bounds.cpp b/tests/renderer/test_placement_bounds.cppnew file mode 100644index 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.tsindex 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 adiff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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));+}