From bdb03ba5d7029a509709d658c5c281ea7a09bb18 Mon Sep 17 00:00:00 2001 From: eust-w Date: Thu, 25 Jun 2026 13:20:45 +0800 Subject: [PATCH] Virtualize fixed instanced scene roots --- docs/product-readiness.md | 101 ++++++++++++++++------------- scripts/product-readiness-gate.mjs | 10 ++- src/main.ts | 5 +- src/preview/UniversalPreviewer.ts | 98 +++++++++++++++++++++++++--- src/types.ts | 1 + 5 files changed, 157 insertions(+), 58 deletions(-) diff --git a/docs/product-readiness.md b/docs/product-readiness.md index a4b3c89..2e859b2 100644 --- a/docs/product-readiness.md +++ b/docs/product-readiness.md @@ -425,15 +425,17 @@ Scene evidence: static-subtree traversal and spin scan when the source has no animated nodes. - Fixed repeated mesh instancing: in large scenes, repeated fixed mesh assets render through shared `InstancedMesh` batches while each manifest object keeps - its own root, body binding, cached bounds, editable group, and backend sync path. - This reduces WebGL draw work for shelf/product inventory without turning the - objects into frontend-only decorations. -- Instanced local-pose elision: repeated fixed mesh assets no longer allocate a - persistent local-pose `Object3D` for every shelf/product item. Each item keeps - a cached local transform matrix plus source bounds, and the instanced matrix is - computed from `root.matrixWorld * localMatrix * sourceMatrix`. This keeps - backend bindings intact while removing hundreds of Three.js nodes from the - visible/data scene graph. + its body binding, cached bounds, editable group, and backend sync path. Fixed + instances now use a virtual identity root instead of one detached Three.js root + per shelf/product item. This reduces initialization matrix/object work without + turning the objects into frontend-only decorations. +- Instanced local-pose/root elision: repeated fixed mesh assets no longer + allocate a persistent local-pose `Object3D` or per-item root for every + shelf/product item. Each item keeps a cached local transform matrix plus source + bounds, and the instanced matrix is computed directly from + `localMatrix * sourceMatrix` for fixed virtual-root instances. This keeps + backend bindings intact while removing hundreds of Three.js nodes and inverse + bounds transforms from the large-scene build path. - Finalized instanced batch culling: after all instance matrices are written, each `InstancedMesh` computes a batch bounding box/sphere, switches its instance buffer to static usage, and re-enables frustum culling. The release @@ -520,8 +522,9 @@ Scene evidence: `preserveDrawingBuffer=false`, avoiding the persistent framebuffer retention cost. Pixel sampling and exported PNG screenshots call an explicit readback render, and positive pixel evidence is cached until the next scene reload. -- Manual root matrices: every manifest object root disables automatic matrix - recomputation after construction. Runtime state, drag, and robot-offset +- Manual and virtual root matrices: dynamic/stateful manifest objects keep manual + roots with automatic matrix updates disabled, while repeated fixed instanced + inventory uses virtual identity roots. Runtime state, drag, and robot-offset changes explicitly update only the roots that actually move. - Safe physical template pose: `/compose` applies the builder `robotPose` to the included G1 MJCF before loading MotrixSim, and the default physical @@ -532,13 +535,13 @@ Scene evidence: Bundle evidence: - JavaScript chunks: `4` -- App entry chunk: `213.59 kB raw / 54.90 kB gzip` +- App entry chunk: `215.57 kB raw / 55.26 kB gzip` - Largest JavaScript gzip chunk: `140.96 KiB / 170.00 KiB` -- Total JavaScript gzip: `218.44 KiB / 230.00 KiB` +- Total JavaScript gzip: `218.79 KiB / 230.00 KiB` - Large-scene performance mode: `large-scene`, target `45 fps`, - actual idle render rate `0.8 fps`, DPR cap observed at `1.00` in release + actual idle render rate `0.7 fps`, DPR cap observed at `1.00` in release gate, `preserveDrawingBuffer=false`, `1` explicit readback render, shadows - `off`, hover picking throttled to `32ms`, `1138` empty frames + `off`, hover picking throttled to `32ms`, `1096` empty frames skipped, `135` static visual nodes frozen, `568` instanced local-pose nodes elided, `59` remaining mesh clones using pre-frozen source state, `627` repeated spin scans skipped, `568` repeated @@ -546,21 +549,23 @@ Bundle evidence: draw units, `568` matrix uploads, and all `16` draw units finalized with frustum culling plus static instance matrices, `7` primitive geometry shapes cached, `51` mesh source assets retained, `24/51` mesh cache hit/miss in the - primary large scene, `636` cached object bounds, `627` fast pick-target + primary large scene, `568` virtual fixed instance roots, `68` manual roots, + `636` cached object bounds, `627` fast pick-target bounds from `51` cached source bounds, real hover proof `hoverProxy 2` with cached bounds and `fallback 0`, with `0` camera-fit traversals, `4/84` progressive scene root batches under the computed `84` root cap and `5` - batch cap, `327` no-op loading frames + batch cap, `826` no-op loading frames suppressed during the primary load, `26` browser event-loop yields during scene construction, active state payload `34/602` with `1` reduced frame and - `2` incremental body-map merges, semantic poll forwarding `6/2/4` + `2` incremental body-map merges, semantic poll forwarding `2/2/5` parsed/forwarded/duplicate-skip, - UI physics-profile cache `24/3` hit/miss, UI builder-profile cache `27/1` - hit/miss, UI text write gating `101/418` write/skip, text selector cache - `473/46` hit/miss, scratch bounds transforms `1263`, diagnostics panel - throttling `19/3` render/skip, `88/636` + state-hash polling `7/5/0` hash/hash-skip/semantic-skip with `5` real + `304 Not Modified` responses, UI physics-profile cache `25/3` hit/miss, UI + builder-profile cache `28/1` hit/miss, UI text write gating `105/445` + write/skip, text selector cache `504/46` hit/miss, scratch bounds transforms + `695`, diagnostics panel throttling `20/3` render/skip, `88/636` hover targets over cached bounds used for bounds-only ray tests, - and a stable paused backend state cache reported `manual roots 636 updates + and a stable paused backend state cache reported `manual roots 68 updates 67` with `state apply 0/skip 67`. - Mesh cache lifecycle evidence: the Scene Builder compose switch reported cumulative `99/51` mesh cache hit/miss with `51` retained geometries and @@ -616,20 +621,21 @@ Bundle evidence: - Camera-fit traversal gate: `browser-large-scene-performance-mode` now checks `bounds cache 636` and `camera traversals 0`. - Pick-proxy bounds gate: `browser-large-scene-performance-mode` now checks - `fast=627`, `scratch=1263`, and `source=51`, proving repeated mesh pick bounds - are served from cached source bounds and transformed through the reduced- - allocation scratch path. + `fast=627`, `scratch=695`, and `source=51`, proving repeated mesh pick bounds + are served from cached source bounds, with fixed instanced objects taking the + virtual-root one-transform path instead of the older root inverse path. - Pre-frozen mesh clone gate: `browser-large-scene-performance-mode` now checks `prefrozen + instanced >= repeated mesh threshold` and `spinSkip=627`, proving repeated mesh assets avoid re-traversing static visual subtrees and non-spinning clone trees. - Instanced mesh gate: `browser-large-scene-performance-mode` now checks `instanced=568/16/16`, `matrices=568`, `cull=16`, `static=16`, - `elidedLocal=568`, and that instanced draw units are fewer than instanced - objects, proving repeated fixed inventory renders through shared GPU batches - with safe frustum culling instead of one cloned render tree per item. The same - gate also requires `frozen + elidedLocal >= 500`, so removing local-pose nodes - cannot be mistaken for losing static-scene optimization coverage. + `elidedLocal=568`, `virtualRoots=568`, and that instanced draw units are fewer + than instanced objects, proving repeated fixed inventory renders through shared + GPU batches with virtual per-item roots and safe frustum culling instead of one + cloned render tree per item. The same gate also requires + `frozen + elidedLocal >= 500`, so removing local-pose nodes cannot be mistaken + for losing static-scene optimization coverage. - Hover bounds gate: `browser-hover-proxy-bounds` moves the mouse over the real canvas and now checks both `hoverProxy` and cached hover bounds increase while `fallback=0`, proving hover highlight uses the pruned cached bounds list @@ -652,29 +658,29 @@ Control evidence: - Active state endpoint: full `/state` returned `602` bodies; active `/state?bodies=active` returned `34` bodies in `62ms`, filtered `568` fixed bodies, and retained `4/4` composed dynamic bodies. -- Scene Builder UI compose: representative run `3756ms` end to end with real +- Scene Builder UI compose: representative run `3544ms` end to end with real backend diagnostics. -- Share-link restore: representative full browser restore `13118ms`. -- Config import restore: representative full browser restore `14236ms`. +- Share-link restore: representative full browser restore `20138ms`. +- Config import restore: representative full browser restore `18889ms`. - Composed object body edit: `47ms`. - Fixed inventory edit rejection: `59ms`. - Dynamic composed object drop: `0.48012m`. - Static shelf anchor stability: `max drift 0.00000m` after a 2500 ms resume window. -- Resume backend state: `44ms paused=false` -- Resume visible UI state: `35ms` -- Pause backend state: `54ms paused=true` -- Pause visible UI state: `43ms` +- Resume backend state: `55ms paused=false` +- Resume visible UI state: `46ms` +- Pause backend state: `258ms paused=true` +- Pause visible UI state: `44ms` - Desktop acceptance wait: `1243ms` total, product telemetry `0ms` - Mobile acceptance wait: `277ms` total, product telemetry `0ms` - Runtime diagnostics panel: `state=http://127.0.0.1:18090/state`, `control=http://127.0.0.1:18090/control`, - `latency=响应 43 ms / 确认 43 ms / 可见 43 ms`, + `latency=响应 44 ms / 确认 44 ms / 可见 44 ms`, `acceptanceLatency=0 ms / 11-0-0`, `binding=635/636; 4/568`, `builderPhysics=已添加物体 4: 后端动态 4 / 仅视觉 0`, - `renderPerformance=large-scene; target 45 fps; actual 0.9 fps; dpr 1.00; buffer preserved false; readback renders 1; shadows off; skipped 255; hover 32ms; frozen 135 prefrozen 59 spinSkip 627; instanced 568/16/16 matrices 568 cull 16 static 16 elidedLocal 568; manual roots 636 updates 67; primitive geometries 7; mesh cache 51 sources 24/51 hit/miss retained 51g/17m; bounds cache 636 fast 627 scratch 1263 source 51 hoverProxy 1 cached 1/fallback 0 camera traversals 0; scene batches 4/84 suppressed 273 yields 26; state payload 34/602 reduced 2 incremental 3; ui cache physics 30/3 builder 33/1 text 107/521 selector 582/46 diagnostics 22/5; pick targets 88/636; state apply 0/skip 67; unchanged frames 2; released 0g/0m/0t`. + `renderPerformance=large-scene; target 45 fps; actual 0.7 fps; dpr 1.00; buffer preserved false; readback renders 1; shadows off; skipped 1096; hover 32ms; frozen 135 prefrozen 59 spinSkip 627; instanced 568/16/16 matrices 568 cull 16 static 16 elidedLocal 568 virtualRoots 568; manual roots 68 updates 67; primitive geometries 7; mesh cache 51 sources 24/51 hit/miss retained 51g/17m; bounds cache 636 fast 627 scratch 695 source 51 hoverProxy 2 cached 2/fallback 0 camera traversals 0; scene batches 4/84 suppressed 826 yields 26; state payload 34/602 reduced 1 incremental 2; ui cache physics 25/3 builder 28/1 text 103/435 selector 492/46 diagnostics 20/3; pick targets 88/636; state apply 0/skip 67; unchanged frames 1; released 0g/0m/0t`. - Evidence screenshot artifacts: `builder page; share page; import page; visual-only boundary canvas; desktop canvas; debug PNG; mobile canvas` - Evidence export artifacts: @@ -771,13 +777,16 @@ Current performance boundaries: first load, Scene Builder compose, share restore, and config import restore still include browser asset creation and scene graph setup time. - The real backend control path is not the observed bottleneck in the current - gate: pause/resume visible UI confirmation is `56-60ms`, and the backend - physics step sample during pause verification reports `0.51ms` mean and - `0.81ms` p95 step time. + gate: resume visible UI confirmation is `46ms`, pause visible UI confirmation + is `44ms`, and the backend physics step sample during pause verification + reports `0.51ms` mean and `0.81ms` p95 step time. - The remaining high-impact optimization area is asset-level rendering and - static-scene packaging: more aggressive shelf/product instancing, material - reduction, LODs, and eventually moving repeated fixed inventory into a - backend static-state channel. + static-scene packaging: the current virtual-root instancing path reduces + per-item scene construction (`virtualRoots=568`, `manualRoots=68`), but + share/config restore still spends `18-20s` in full browser page load, compose + restore, asset setup, and screenshots. The next tier is material reduction, + LODs, static asset manifests, and eventually moving repeated fixed inventory + into a backend static-state channel. ## Handoff Criteria diff --git a/scripts/product-readiness-gate.mjs b/scripts/product-readiness-gate.mjs index 0468926..4ac85fe 100644 --- a/scripts/product-readiness-gate.mjs +++ b/scripts/product-readiness-gate.mjs @@ -693,6 +693,7 @@ async function readBrowserStats(page) { instancedMeshFrustumCulledCount: numberData("instancedMeshFrustumCulledCount"), instancedMeshStaticMatrixCount: numberData("instancedMeshStaticMatrixCount"), instancedLocalObjectElisionCount: numberData("instancedLocalObjectElisionCount"), + virtualInstancedRootCount: numberData("virtualInstancedRootCount"), manualMatrixRootCount: numberData("manualMatrixRootCount"), manualMatrixUpdateCount: numberData("manualMatrixUpdateCount"), primitiveGeometryCount: numberData("primitiveGeometryCount"), @@ -1847,14 +1848,17 @@ async function verifyBrowser() { && (renderPerformance.instancedMeshFrustumCulledCount ?? 0) === (renderPerformance.instancedMeshDrawCount ?? -1) && (renderPerformance.instancedMeshStaticMatrixCount ?? 0) === (renderPerformance.instancedMeshDrawCount ?? -1) && (renderPerformance.instancedLocalObjectElisionCount ?? 0) >= (renderPerformance.instancedMeshObjectCount ?? 0) - && (renderPerformance.manualMatrixRootCount ?? 0) >= objectCount + && (renderPerformance.virtualInstancedRootCount ?? 0) >= (renderPerformance.instancedMeshObjectCount ?? 0) + && (renderPerformance.manualMatrixRootCount ?? 0) + (renderPerformance.virtualInstancedRootCount ?? 0) >= objectCount + && (renderPerformance.manualMatrixRootCount ?? Number.POSITIVE_INFINITY) < objectCount && (renderPerformance.primitiveGeometryCount ?? 0) > 0 && (renderPerformance.meshCacheSourceCount ?? 0) > 0 && (renderPerformance.meshCacheHitCount ?? 0) > 0 && (renderPerformance.retainedMeshGeometryCount ?? 0) > 0 && (renderPerformance.sceneObjectBoundsCount ?? 0) >= objectCount && (renderPerformance.fastPickProxyBoundsCount ?? 0) >= thresholds.minMeshes - && (renderPerformance.pickBoundsScratchTransformCount ?? 0) >= (renderPerformance.fastPickProxyBoundsCount ?? 0) * 2 + && (renderPerformance.pickBoundsScratchTransformCount ?? 0) >= (renderPerformance.fastPickProxyBoundsCount ?? 0) + && (renderPerformance.pickBoundsScratchTransformCount ?? Number.POSITIVE_INFINITY) < (renderPerformance.fastPickProxyBoundsCount ?? 0) * 2 && (renderPerformance.meshSourceBoundsCount ?? 0) > 0 && (renderPerformance.hoverCachedBoundsHitCount ?? 0) > 0 && (renderPerformance.cameraFitTraversalCount ?? Number.POSITIVE_INFINITY) === 0 @@ -1892,7 +1896,7 @@ async function verifyBrowser() { && (renderPerformance.hoverPickTargetCount ?? Number.POSITIVE_INFINITY) <= maxHoverPickTargets && (renderPerformance.skippedBodyStateCount ?? 0) > 0 && desktopStats.diagnostics.renderPerformance.includes("large-scene"), - `mode=${renderPerformance.largeSceneMode} fps=${renderPerformance.targetRenderFps ?? "-"} statsRefresh=${renderPerformance.statsRefreshIntervalMs ?? "-"}ms ${renderPerformance.statsRefreshRenderCount ?? "-"}/${renderPerformance.statsRefreshSkipCount ?? "-"} dpr=${renderPerformance.renderPixelRatio ?? "-"} buffer=${renderPerformance.preserveDrawingBufferEnabled} readback=${renderPerformance.readbackRenderCount ?? "-"} shadows=${renderPerformance.shadowsEnabled} hover=${renderPerformance.hoverPickIntervalMs ?? "-"} skipped=${renderPerformance.renderSkipCount ?? "-"} frozen=${renderPerformance.frozenStaticObjectCount ?? "-"} prefrozen=${renderPerformance.preFrozenMeshCloneCount ?? "-"} spinSkip=${renderPerformance.spinningScanSkippedCount ?? "-"} instanced=${renderPerformance.instancedMeshObjectCount ?? "-"}/${renderPerformance.instancedMeshBatchCount ?? "-"}/${renderPerformance.instancedMeshDrawCount ?? "-"} matrices=${renderPerformance.instancedMeshMatrixUpdateCount ?? "-"} cull=${renderPerformance.instancedMeshFrustumCulledCount ?? "-"} static=${renderPerformance.instancedMeshStaticMatrixCount ?? "-"} elidedLocal=${renderPerformance.instancedLocalObjectElisionCount ?? "-"} manualRoots=${renderPerformance.manualMatrixRootCount ?? "-"} manualUpdates=${renderPerformance.manualMatrixUpdateCount ?? "-"} primitiveGeometries=${renderPerformance.primitiveGeometryCount ?? "-"} meshCache=${renderPerformance.meshCacheSourceCount ?? "-"} hit=${renderPerformance.meshCacheHitCount ?? "-"} miss=${renderPerformance.meshCacheMissCount ?? "-"} retained=${renderPerformance.retainedMeshGeometryCount ?? "-"}g/${renderPerformance.retainedMeshMaterialCount ?? "-"}m bounds=${renderPerformance.sceneObjectBoundsCount ?? "-"} fast=${renderPerformance.fastPickProxyBoundsCount ?? "-"} scratch=${renderPerformance.pickBoundsScratchTransformCount ?? "-"} source=${renderPerformance.meshSourceBoundsCount ?? "-"} hoverProxy=${renderPerformance.hoverProxyBoundsHitCount ?? "-"} cached=${renderPerformance.hoverCachedBoundsHitCount ?? "-"}/fallback=${renderPerformance.hoverRootBoundsFallbackCount ?? "-"} cameraTraversals=${renderPerformance.cameraFitTraversalCount ?? "-"} sceneBatches=${renderPerformance.sceneRootBatchCount ?? "-"}/${renderPerformance.batchedSceneRootCount ?? "-"} maxSceneRoots=${maxInstancedSceneRoots} maxBatches=${maxProgressiveSceneRootBatches} suppressed=${renderPerformance.sceneLoadSuppressedRenderCount ?? "-"} yields=${renderPerformance.sceneBuildYieldCount ?? "-"} statePayload=${renderPerformance.statePayloadBodyCount ?? "-"}/${renderPerformance.mergedBodyStateCount ?? "-"} reduced=${renderPerformance.reducedStateFrameCount ?? "-"} incremental=${renderPerformance.incrementalBodyMergeCount ?? "-"} poll=${renderPerformance.stateBasePollIntervalMs ?? "-"}/${renderPerformance.statePausedPollIntervalMs ?? "-"}/${renderPerformance.stateLastScheduledPollIntervalMs ?? "-"}ms ${renderPerformance.statePollRequestCount ?? "-"}/${renderPerformance.stateActivePollRequestCount ?? "-"}/${renderPerformance.statePausedPollRequestCount ?? "-"} semantic=${renderPerformance.stateParsedPollFrameCount ?? "-"}/${renderPerformance.stateForwardedPollFrameCount ?? "-"}/${renderPerformance.stateSkippedDuplicatePollFrameCount ?? "-"} hash=${renderPerformance.stateHashedPollFrameCount ?? "-"}/${renderPerformance.stateSkippedDuplicateHashPollFrameCount ?? "-"}/${renderPerformance.stateSkippedDuplicateSemanticPollFrameCount ?? "-"} notModified=${renderPerformance.stateNotModifiedPollFrameCount ?? "-"} uiCache=physics ${renderPerformance.objectPhysicsProfileCacheHitCount ?? "-"}/${renderPerformance.objectPhysicsProfileCacheMissCount ?? "-"} builder ${renderPerformance.builderPhysicsProfileCacheHitCount ?? "-"}/${renderPerformance.builderPhysicsProfileCacheMissCount ?? "-"} text ${renderPerformance.textWriteCount ?? "-"}/${renderPerformance.textWriteSkipCount ?? "-"} selector ${renderPerformance.textSelectorCacheHitCount ?? "-"}/${renderPerformance.textSelectorCacheMissCount ?? "-"} diagnostics ${renderPerformance.diagnosticsPanelRenderCount ?? "-"}/${renderPerformance.diagnosticsPanelSkipCount ?? "-"} builderPanels=${renderPerformance.builderPanelRenderCount ?? "-"}/${renderPerformance.builderPanelDeferredRenderCount ?? "-"}/${renderPerformance.builderPanelCoalescedRenderCount ?? "-"} pickTargets=${renderPerformance.hoverPickTargetCount ?? "-"}/${renderPerformance.pickProxyCount ?? "-"} hoverBudget=${maxHoverPickTargets} stateApply=${renderPerformance.appliedBodyStateCount ?? "-"}/skip=${renderPerformance.skippedBodyStateCount ?? "-"} unchanged=${renderPerformance.unchangedFrameCount ?? "-"} released=${renderPerformance.releasedGeometryCount ?? "-"}g/${renderPerformance.releasedMaterialCount ?? "-"}m/${renderPerformance.releasedTextureCount ?? "-"}t; ${desktopStats.diagnostics.renderPerformance}`, + `mode=${renderPerformance.largeSceneMode} fps=${renderPerformance.targetRenderFps ?? "-"} statsRefresh=${renderPerformance.statsRefreshIntervalMs ?? "-"}ms ${renderPerformance.statsRefreshRenderCount ?? "-"}/${renderPerformance.statsRefreshSkipCount ?? "-"} dpr=${renderPerformance.renderPixelRatio ?? "-"} buffer=${renderPerformance.preserveDrawingBufferEnabled} readback=${renderPerformance.readbackRenderCount ?? "-"} shadows=${renderPerformance.shadowsEnabled} hover=${renderPerformance.hoverPickIntervalMs ?? "-"} skipped=${renderPerformance.renderSkipCount ?? "-"} frozen=${renderPerformance.frozenStaticObjectCount ?? "-"} prefrozen=${renderPerformance.preFrozenMeshCloneCount ?? "-"} spinSkip=${renderPerformance.spinningScanSkippedCount ?? "-"} instanced=${renderPerformance.instancedMeshObjectCount ?? "-"}/${renderPerformance.instancedMeshBatchCount ?? "-"}/${renderPerformance.instancedMeshDrawCount ?? "-"} matrices=${renderPerformance.instancedMeshMatrixUpdateCount ?? "-"} cull=${renderPerformance.instancedMeshFrustumCulledCount ?? "-"} static=${renderPerformance.instancedMeshStaticMatrixCount ?? "-"} elidedLocal=${renderPerformance.instancedLocalObjectElisionCount ?? "-"} virtualRoots=${renderPerformance.virtualInstancedRootCount ?? "-"} manualRoots=${renderPerformance.manualMatrixRootCount ?? "-"} manualUpdates=${renderPerformance.manualMatrixUpdateCount ?? "-"} primitiveGeometries=${renderPerformance.primitiveGeometryCount ?? "-"} meshCache=${renderPerformance.meshCacheSourceCount ?? "-"} hit=${renderPerformance.meshCacheHitCount ?? "-"} miss=${renderPerformance.meshCacheMissCount ?? "-"} retained=${renderPerformance.retainedMeshGeometryCount ?? "-"}g/${renderPerformance.retainedMeshMaterialCount ?? "-"}m bounds=${renderPerformance.sceneObjectBoundsCount ?? "-"} fast=${renderPerformance.fastPickProxyBoundsCount ?? "-"} scratch=${renderPerformance.pickBoundsScratchTransformCount ?? "-"} source=${renderPerformance.meshSourceBoundsCount ?? "-"} hoverProxy=${renderPerformance.hoverProxyBoundsHitCount ?? "-"} cached=${renderPerformance.hoverCachedBoundsHitCount ?? "-"}/fallback=${renderPerformance.hoverRootBoundsFallbackCount ?? "-"} cameraTraversals=${renderPerformance.cameraFitTraversalCount ?? "-"} sceneBatches=${renderPerformance.sceneRootBatchCount ?? "-"}/${renderPerformance.batchedSceneRootCount ?? "-"} maxSceneRoots=${maxInstancedSceneRoots} maxBatches=${maxProgressiveSceneRootBatches} suppressed=${renderPerformance.sceneLoadSuppressedRenderCount ?? "-"} yields=${renderPerformance.sceneBuildYieldCount ?? "-"} statePayload=${renderPerformance.statePayloadBodyCount ?? "-"}/${renderPerformance.mergedBodyStateCount ?? "-"} reduced=${renderPerformance.reducedStateFrameCount ?? "-"} incremental=${renderPerformance.incrementalBodyMergeCount ?? "-"} poll=${renderPerformance.stateBasePollIntervalMs ?? "-"}/${renderPerformance.statePausedPollIntervalMs ?? "-"}/${renderPerformance.stateLastScheduledPollIntervalMs ?? "-"}ms ${renderPerformance.statePollRequestCount ?? "-"}/${renderPerformance.stateActivePollRequestCount ?? "-"}/${renderPerformance.statePausedPollRequestCount ?? "-"} semantic=${renderPerformance.stateParsedPollFrameCount ?? "-"}/${renderPerformance.stateForwardedPollFrameCount ?? "-"}/${renderPerformance.stateSkippedDuplicatePollFrameCount ?? "-"} hash=${renderPerformance.stateHashedPollFrameCount ?? "-"}/${renderPerformance.stateSkippedDuplicateHashPollFrameCount ?? "-"}/${renderPerformance.stateSkippedDuplicateSemanticPollFrameCount ?? "-"} notModified=${renderPerformance.stateNotModifiedPollFrameCount ?? "-"} uiCache=physics ${renderPerformance.objectPhysicsProfileCacheHitCount ?? "-"}/${renderPerformance.objectPhysicsProfileCacheMissCount ?? "-"} builder ${renderPerformance.builderPhysicsProfileCacheHitCount ?? "-"}/${renderPerformance.builderPhysicsProfileCacheMissCount ?? "-"} text ${renderPerformance.textWriteCount ?? "-"}/${renderPerformance.textWriteSkipCount ?? "-"} selector ${renderPerformance.textSelectorCacheHitCount ?? "-"}/${renderPerformance.textSelectorCacheMissCount ?? "-"} diagnostics ${renderPerformance.diagnosticsPanelRenderCount ?? "-"}/${renderPerformance.diagnosticsPanelSkipCount ?? "-"} builderPanels=${renderPerformance.builderPanelRenderCount ?? "-"}/${renderPerformance.builderPanelDeferredRenderCount ?? "-"}/${renderPerformance.builderPanelCoalescedRenderCount ?? "-"} pickTargets=${renderPerformance.hoverPickTargetCount ?? "-"}/${renderPerformance.pickProxyCount ?? "-"} hoverBudget=${maxHoverPickTargets} stateApply=${renderPerformance.appliedBodyStateCount ?? "-"}/skip=${renderPerformance.skippedBodyStateCount ?? "-"} unchanged=${renderPerformance.unchangedFrameCount ?? "-"} released=${renderPerformance.releasedGeometryCount ?? "-"}g/${renderPerformance.releasedMaterialCount ?? "-"}m/${renderPerformance.releasedTextureCount ?? "-"}t; ${desktopStats.diagnostics.renderPerformance}`, ); check( "browser-debug-capture-png", diff --git a/src/main.ts b/src/main.ts index d9f8622..e776a94 100644 --- a/src/main.ts +++ b/src/main.ts @@ -189,6 +189,7 @@ interface RuntimeDiagnostics { instancedMeshFrustumCulledCount: number; instancedMeshStaticMatrixCount: number; instancedLocalObjectElisionCount: number; + virtualInstancedRootCount: number; manualMatrixRootCount: number; manualMatrixUpdateCount: number; primitiveGeometryCount: number; @@ -2683,6 +2684,7 @@ function currentRuntimeDiagnostics( instancedMeshFrustumCulledCount: stats.instancedMeshFrustumCulledCount, instancedMeshStaticMatrixCount: stats.instancedMeshStaticMatrixCount, instancedLocalObjectElisionCount: stats.instancedLocalObjectElisionCount, + virtualInstancedRootCount: stats.virtualInstancedRootCount, manualMatrixRootCount: stats.manualMatrixRootCount, manualMatrixUpdateCount: stats.manualMatrixUpdateCount, primitiveGeometryCount: stats.primitiveGeometryCount, @@ -2805,7 +2807,7 @@ function currentDiagnosticsReport(): string { function renderPerformanceLabel(stats: RuntimeDiagnostics["stats"]): string { const mode = stats.largeSceneMode ? "large-scene" : "standard"; const shadows = stats.shadowsEnabled ? "shadows on" : "shadows off"; - return `${mode}; target ${stats.targetRenderFps} fps; actual ${stats.actualRenderFps.toFixed(1)} fps; stats refresh ${stats.statsRefreshIntervalMs}ms ${stats.statsRefreshRenderCount}/${stats.statsRefreshSkipCount}; dpr ${stats.renderPixelRatio.toFixed(2)}; buffer preserved ${stats.preserveDrawingBufferEnabled}; readback renders ${stats.readbackRenderCount}; ${shadows}; skipped ${stats.renderSkipCount}; hover ${stats.hoverPickIntervalMs}ms; frozen ${stats.frozenStaticObjectCount} prefrozen ${stats.preFrozenMeshCloneCount} spinSkip ${stats.spinningScanSkippedCount}; instanced ${stats.instancedMeshObjectCount}/${stats.instancedMeshBatchCount}/${stats.instancedMeshDrawCount} matrices ${stats.instancedMeshMatrixUpdateCount} cull ${stats.instancedMeshFrustumCulledCount} static ${stats.instancedMeshStaticMatrixCount} elidedLocal ${stats.instancedLocalObjectElisionCount}; manual roots ${stats.manualMatrixRootCount} updates ${stats.manualMatrixUpdateCount}; primitive geometries ${stats.primitiveGeometryCount}; mesh cache ${stats.meshCacheSourceCount} sources ${stats.meshCacheHitCount}/${stats.meshCacheMissCount} hit/miss retained ${stats.retainedMeshGeometryCount}g/${stats.retainedMeshMaterialCount}m; bounds cache ${stats.sceneObjectBoundsCount} fast ${stats.fastPickProxyBoundsCount} scratch ${stats.pickBoundsScratchTransformCount} source ${stats.meshSourceBoundsCount} hoverProxy ${stats.hoverProxyBoundsHitCount} cached ${stats.hoverCachedBoundsHitCount}/fallback ${stats.hoverRootBoundsFallbackCount} camera traversals ${stats.cameraFitTraversalCount}; scene batches ${stats.sceneRootBatchCount}/${stats.batchedSceneRootCount} suppressed ${stats.sceneLoadSuppressedRenderCount} yields ${stats.sceneBuildYieldCount}; state payload ${stats.statePayloadBodyCount}/${stats.mergedBodyStateCount} reduced ${stats.reducedStateFrameCount} incremental ${stats.incrementalBodyMergeCount} poll ${stats.stateBasePollIntervalMs}/${stats.statePausedPollIntervalMs}/${stats.stateLastScheduledPollIntervalMs}ms ${stats.statePollRequestCount}/${stats.stateActivePollRequestCount}/${stats.statePausedPollRequestCount} semantic ${stats.stateParsedPollFrameCount}/${stats.stateForwardedPollFrameCount}/${stats.stateSkippedDuplicatePollFrameCount} hash ${stats.stateHashedPollFrameCount}/${stats.stateSkippedDuplicateHashPollFrameCount}/${stats.stateSkippedDuplicateSemanticPollFrameCount} notModified ${stats.stateNotModifiedPollFrameCount}; ui cache physics ${stats.objectPhysicsProfileCacheHitCount}/${stats.objectPhysicsProfileCacheMissCount} builder ${stats.builderPhysicsProfileCacheHitCount}/${stats.builderPhysicsProfileCacheMissCount} text ${stats.textWriteCount}/${stats.textWriteSkipCount} selector ${stats.textSelectorCacheHitCount}/${stats.textSelectorCacheMissCount} diagnostics ${stats.diagnosticsPanelRenderCount}/${stats.diagnosticsPanelSkipCount} builderPanels ${stats.builderPanelRenderCount}/${stats.builderPanelDeferredRenderCount}/${stats.builderPanelCoalescedRenderCount}; drag ${stats.dragMoveEventCount}/${stats.dragAppliedMoveCount}/${stats.dragCoalescedMoveCount}; pick targets ${stats.hoverPickTargetCount}/${stats.pickProxyCount}; state apply ${stats.appliedBodyStateCount}/skip ${stats.skippedBodyStateCount}; unchanged frames ${stats.unchangedFrameCount}; released ${stats.releasedGeometryCount}g/${stats.releasedMaterialCount}m/${stats.releasedTextureCount}t`; + return `${mode}; target ${stats.targetRenderFps} fps; actual ${stats.actualRenderFps.toFixed(1)} fps; stats refresh ${stats.statsRefreshIntervalMs}ms ${stats.statsRefreshRenderCount}/${stats.statsRefreshSkipCount}; dpr ${stats.renderPixelRatio.toFixed(2)}; buffer preserved ${stats.preserveDrawingBufferEnabled}; readback renders ${stats.readbackRenderCount}; ${shadows}; skipped ${stats.renderSkipCount}; hover ${stats.hoverPickIntervalMs}ms; frozen ${stats.frozenStaticObjectCount} prefrozen ${stats.preFrozenMeshCloneCount} spinSkip ${stats.spinningScanSkippedCount}; instanced ${stats.instancedMeshObjectCount}/${stats.instancedMeshBatchCount}/${stats.instancedMeshDrawCount} matrices ${stats.instancedMeshMatrixUpdateCount} cull ${stats.instancedMeshFrustumCulledCount} static ${stats.instancedMeshStaticMatrixCount} elidedLocal ${stats.instancedLocalObjectElisionCount} virtualRoots ${stats.virtualInstancedRootCount}; manual roots ${stats.manualMatrixRootCount} updates ${stats.manualMatrixUpdateCount}; primitive geometries ${stats.primitiveGeometryCount}; mesh cache ${stats.meshCacheSourceCount} sources ${stats.meshCacheHitCount}/${stats.meshCacheMissCount} hit/miss retained ${stats.retainedMeshGeometryCount}g/${stats.retainedMeshMaterialCount}m; bounds cache ${stats.sceneObjectBoundsCount} fast ${stats.fastPickProxyBoundsCount} scratch ${stats.pickBoundsScratchTransformCount} source ${stats.meshSourceBoundsCount} hoverProxy ${stats.hoverProxyBoundsHitCount} cached ${stats.hoverCachedBoundsHitCount}/fallback ${stats.hoverRootBoundsFallbackCount} camera traversals ${stats.cameraFitTraversalCount}; scene batches ${stats.sceneRootBatchCount}/${stats.batchedSceneRootCount} suppressed ${stats.sceneLoadSuppressedRenderCount} yields ${stats.sceneBuildYieldCount}; state payload ${stats.statePayloadBodyCount}/${stats.mergedBodyStateCount} reduced ${stats.reducedStateFrameCount} incremental ${stats.incrementalBodyMergeCount} poll ${stats.stateBasePollIntervalMs}/${stats.statePausedPollIntervalMs}/${stats.stateLastScheduledPollIntervalMs}ms ${stats.statePollRequestCount}/${stats.stateActivePollRequestCount}/${stats.statePausedPollRequestCount} semantic ${stats.stateParsedPollFrameCount}/${stats.stateForwardedPollFrameCount}/${stats.stateSkippedDuplicatePollFrameCount} hash ${stats.stateHashedPollFrameCount}/${stats.stateSkippedDuplicateHashPollFrameCount}/${stats.stateSkippedDuplicateSemanticPollFrameCount} notModified ${stats.stateNotModifiedPollFrameCount}; ui cache physics ${stats.objectPhysicsProfileCacheHitCount}/${stats.objectPhysicsProfileCacheMissCount} builder ${stats.builderPhysicsProfileCacheHitCount}/${stats.builderPhysicsProfileCacheMissCount} text ${stats.textWriteCount}/${stats.textWriteSkipCount} selector ${stats.textSelectorCacheHitCount}/${stats.textSelectorCacheMissCount} diagnostics ${stats.diagnosticsPanelRenderCount}/${stats.diagnosticsPanelSkipCount} builderPanels ${stats.builderPanelRenderCount}/${stats.builderPanelDeferredRenderCount}/${stats.builderPanelCoalescedRenderCount}; drag ${stats.dragMoveEventCount}/${stats.dragAppliedMoveCount}/${stats.dragCoalescedMoveCount}; pick targets ${stats.hoverPickTargetCount}/${stats.pickProxyCount}; state apply ${stats.appliedBodyStateCount}/skip ${stats.skippedBodyStateCount}; unchanged frames ${stats.unchangedFrameCount}; released ${stats.releasedGeometryCount}g/${stats.releasedMaterialCount}m/${stats.releasedTextureCount}t`; } function renderDiagnosticsPanel( @@ -2862,6 +2864,7 @@ function renderDiagnosticsPanel( data.instancedMeshFrustumCulledCount = String(diagnostics.stats.instancedMeshFrustumCulledCount); data.instancedMeshStaticMatrixCount = String(diagnostics.stats.instancedMeshStaticMatrixCount); data.instancedLocalObjectElisionCount = String(diagnostics.stats.instancedLocalObjectElisionCount); + data.virtualInstancedRootCount = String(diagnostics.stats.virtualInstancedRootCount); data.manualMatrixRootCount = String(diagnostics.stats.manualMatrixRootCount); data.manualMatrixUpdateCount = String(diagnostics.stats.manualMatrixUpdateCount); data.primitiveGeometryCount = String(diagnostics.stats.primitiveGeometryCount); diff --git a/src/preview/UniversalPreviewer.ts b/src/preview/UniversalPreviewer.ts index c21ef16..ea97896 100644 --- a/src/preview/UniversalPreviewer.ts +++ b/src/preview/UniversalPreviewer.ts @@ -166,6 +166,7 @@ export class UniversalPreviewer { private readonly spinningObjects: THREE.Object3D[] = []; private readonly hoverOutlineBounds = new THREE.Box3(); private readonly hoverOutline = new THREE.Box3Helper(this.hoverOutlineBounds, "#38bdf8"); + private readonly virtualInstancedRoot = new THREE.Object3D(); private readonly scratchBounds = new THREE.Box3(); private readonly scratchPickWorldBounds = new THREE.Box3(); private readonly scratchPickLocalBounds = new THREE.Box3(); @@ -234,6 +235,7 @@ export class UniversalPreviewer { private instancedMeshFrustumCulledCount = 0; private instancedMeshStaticMatrixCount = 0; private instancedLocalObjectElisionCount = 0; + private virtualInstancedRootCount = 0; private manualMatrixRootCount = 0; private manualMatrixUpdateCount = 0; private releasedGeometryCount = 0; @@ -316,6 +318,9 @@ export class UniversalPreviewer { this.scene.environment = this.environmentTarget.texture; environmentGenerator.dispose(); this.scene.add(this.root); + this.virtualInstancedRoot.name = "virtual_instanced_root"; + this.virtualInstancedRoot.matrixAutoUpdate = false; + this.virtualInstancedRoot.updateMatrixWorld(true); this.focusMarker.visible = false; this.focusMarker.renderOrder = 50; this.scene.add(this.focusMarker); @@ -557,6 +562,7 @@ export class UniversalPreviewer { instancedMeshFrustumCulledCount: this.instancedMeshFrustumCulledCount, instancedMeshStaticMatrixCount: this.instancedMeshStaticMatrixCount, instancedLocalObjectElisionCount: this.instancedLocalObjectElisionCount, + virtualInstancedRootCount: this.virtualInstancedRootCount, manualMatrixRootCount: this.manualMatrixRootCount, manualMatrixUpdateCount: this.manualMatrixUpdateCount, primitiveGeometryCount: this.primitiveGeometryCache.size, @@ -1159,6 +1165,7 @@ export class UniversalPreviewer { this.instancedMeshFrustumCulledCount = 0; this.instancedMeshStaticMatrixCount = 0; this.instancedLocalObjectElisionCount = 0; + this.virtualInstancedRootCount = 0; this.manualMatrixRootCount = 0; this.manualMatrixUpdateCount = 0; this.sceneObjectBounds.makeEmpty(); @@ -2128,9 +2135,13 @@ export class UniversalPreviewer { } binding.root.updateWorldMatrix(true, false); this.scratchLocalWorldMatrix.multiplyMatrices(binding.root.matrixWorld, binding.localMatrix); - for (const submesh of binding.batch.submeshes) { - this.scratchMatrix.multiplyMatrices(this.scratchLocalWorldMatrix, submesh.sourceMatrix); - submesh.mesh.setMatrixAt(binding.index, this.scratchMatrix); + this.writeInstancedVisualMatrix(binding.batch, binding.index, this.scratchLocalWorldMatrix); + } + + private writeInstancedVisualMatrix(batch: InstancedVisualBatch, index: number, matrix: THREE.Matrix4): void { + for (const submesh of batch.submeshes) { + this.scratchMatrix.multiplyMatrices(matrix, submesh.sourceMatrix); + submesh.mesh.setMatrixAt(index, this.scratchMatrix); submesh.mesh.instanceMatrix.needsUpdate = true; } this.instancedMeshMatrixUpdateCount += 1; @@ -2154,6 +2165,10 @@ export class UniversalPreviewer { } private async addObject(object: PreviewObject, token: number, sceneRoots: SceneBuildRoots): Promise { + if (await this.addVirtualInstancedObject(object, token, sceneRoots)) { + return; + } + const root = new THREE.Group(); root.name = object.name ?? object.id; root.visible = object.visible !== false; @@ -2210,6 +2225,64 @@ export class UniversalPreviewer { this.updateInstancedVisualMatrix(object.id); } this.objectsById.set(object.id, { manifest: object, root }); + this.registerObjectMetadata(object, root); + } + + private async addVirtualInstancedObject(object: PreviewObject, token: number, sceneRoots: SceneBuildRoots): Promise { + if (!this.isInstancedMeshCandidate(object)) { + return false; + } + const key = this.meshCacheKey(object.geometry, object.material); + if (!this.instancedMeshBatchCapacities.has(key)) { + return false; + } + let batch: InstancedVisualBatch; + try { + batch = await this.getInstancedMeshBatch(object.geometry, object.material, key, sceneRoots); + } catch { + return false; + } + if (token !== this.loadToken) { + return true; + } + const sourceBounds = this.meshSourceBounds.get(key); + if (!sourceBounds || sourceBounds.isEmpty() || batch.submeshes.length === 0 || batch.used >= batch.capacity) { + return false; + } + + const localMatrix = this.createPoseMatrix(object.pose); + const index = batch.used; + batch.used += 1; + this.instancedVisualBindings.set(object.id, { + batch, + index, + root: this.virtualInstancedRoot, + localMatrix, + }); + this.writeInstancedVisualMatrix(batch, index, localMatrix); + this.instancedMeshObjectCount += 1; + this.instancedLocalObjectElisionCount += 1; + this.virtualInstancedRootCount += 1; + this.loadedMeshCount += 1; + this.spinningScanSkippedCount += 1; + + const pickTarget = this.createPickTargetFromWorldMatrix(sourceBounds, localMatrix, object.id); + if (pickTarget) { + this.fastPickProxyBoundsCount += 1; + this.sceneObjectBounds.union(pickTarget.worldBounds); + this.sceneObjectBoundsCount += 1; + this.pickBoundsById.set(object.id, pickTarget); + if (this.shouldIncludeHoverPickTarget(object, true)) { + this.pickTargets.push(pickTarget); + } + } + + this.objectsById.set(object.id, { manifest: object, root: this.virtualInstancedRoot }); + this.registerObjectMetadata(object, this.virtualInstancedRoot); + return true; + } + + private registerObjectMetadata(object: PreviewObject, root: THREE.Object3D): void { if (object.editableGroup) { const group = this.editableGroups.get(object.editableGroup) ?? []; if (!group.includes(object.id)) { @@ -2228,16 +2301,13 @@ export class UniversalPreviewer { if (!this.bodySourceOffsets.has(object.body)) { this.bodySourceOffsets.set(object.body, [...sourcePose] as [number, number, number]); } - } else { - this.objectBodyIds.set(object.id, []); - } - - if (object.body) { const items = this.bodyBindings.get(object.body) ?? []; items.push({ manifest: object, root }); this.bodyBindings.set(object.body, items); this.bodyBoundObjectCount += 1; + return; } + this.objectBodyIds.set(object.id, []); } private async addObjects(objects: PreviewObject[], token: number): Promise { @@ -2448,6 +2518,18 @@ export class UniversalPreviewer { return this.createPickTargetFromBounds(localBounds, worldBounds, manifestId); } + private createPickTargetFromWorldMatrix( + sourceBounds: THREE.Box3, + worldMatrix: THREE.Matrix4, + manifestId: string, + ): PickBoundsTarget | undefined { + const worldBounds = this.transformBoundsInto(sourceBounds, worldMatrix, this.scratchPickWorldBounds); + if (worldBounds.isEmpty()) { + return undefined; + } + return this.createPickTargetFromBounds(worldBounds, worldBounds, manifestId); + } + private createPickTargetFromBounds( localBounds: THREE.Box3, worldBounds: THREE.Box3, diff --git a/src/types.ts b/src/types.ts index 7462386..4effce6 100644 --- a/src/types.ts +++ b/src/types.ts @@ -218,6 +218,7 @@ export interface RendererStats { instancedMeshFrustumCulledCount: number; instancedMeshStaticMatrixCount: number; instancedLocalObjectElisionCount: number; + virtualInstancedRootCount: number; manualMatrixRootCount: number; manualMatrixUpdateCount: number; primitiveGeometryCount: number;