From 76bb89e12bcd20582b9a592b690b6762ff652db0 Mon Sep 17 00:00:00 2001 From: eust-w Date: Thu, 25 Jun 2026 04:46:31 +0800 Subject: [PATCH] Instance fixed repeated scene meshes --- docs/product-readiness.md | 42 +++-- scripts/product-readiness-gate.mjs | 13 +- src/main.ts | 14 +- src/preview/UniversalPreviewer.ts | 275 +++++++++++++++++++++++++---- src/types.ts | 4 + 5 files changed, 299 insertions(+), 49 deletions(-) diff --git a/docs/product-readiness.md b/docs/product-readiness.md index bb2c1dd..d3d618f 100644 --- a/docs/product-readiness.md +++ b/docs/product-readiness.md @@ -349,6 +349,11 @@ Scene evidence: - Pre-frozen mesh clone cache: retained mesh sources are frozen once after load. Repeated clone construction reuses that frozen state and skips the per-clone 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, pick proxy, editable group, and backend sync path. + This reduces WebGL draw work for shelf/product inventory without turning the + objects into frontend-only decorations. - Cached hover/drag bounds: hover focus, hover outline, and drag highlight use the existing pick proxy bounds through a `Box3Helper` when present, so hovering or dragging a large shelf/product group does not call @@ -390,25 +395,27 @@ Scene evidence: Bundle evidence: - JavaScript chunks: `4` -- App entry chunk: `191.83 kB raw / 49.90 kB gzip` -- Largest JavaScript gzip chunk: `140.95 KiB / 170.00 KiB` -- Total JavaScript gzip: `213.54 KiB / 230.00 KiB` +- App entry chunk: `196.36 kB raw / 50.93 kB gzip` +- Largest JavaScript gzip chunk: `140.96 KiB / 170.00 KiB` +- Total JavaScript gzip: `214.56 KiB / 230.00 KiB` - Large-scene performance mode: `large-scene`, target `45 fps`, 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`, `28` empty frames - skipped, `1839` static visual nodes frozen, `627` mesh clones using pre-frozen - source state, `627` repeated spin scans skipped, `7` primitive geometry shapes - cached, `51` mesh source assets retained, `576/51` mesh cache hit/miss in - the primary large scene, `636` cached object bounds, `627` fast pick-proxy - bounds from `51` cached source bounds, real hover proof `hoverProxy 1` with - cached bounds and `fallback 0`, with `0` camera-fit traversals, `1/636` - scene root batch insertion, `329` + skipped, `703` static visual nodes frozen, `59` remaining mesh clones using + pre-frozen source state, `627` repeated spin scans skipped, `568` repeated + fixed mesh objects rendered as `16` instanced batches with `16` instanced + draw units and `568` matrix uploads, `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-proxy bounds from + `51` cached source bounds, real hover proof `hoverProxy 1` with cached bounds + and `fallback 0`, with `0` camera-fit traversals, `1/652` + scene root batch insertion, `349` partial render frames suppressed during the primary load, `26` browser event-loop yields during scene construction, active state payload `34/602` with `3` reduced frames and `4` incremental body-map merges, - UI physics-profile cache `30/3` hit/miss, UI builder-profile cache `33/1` + UI physics-profile cache `33/3` hit/miss, UI builder-profile cache `36/1` hit/miss, `636` lightweight pick proxies used for non-recursive raycasts, and a stable paused backend state cache reported `manual roots 636 updates 67` with `state apply 0/skip 67`. @@ -437,14 +444,19 @@ Bundle evidence: `fast=627` and `source=51`, proving repeated mesh pick bounds are served from cached source bounds. - Pre-frozen mesh clone gate: `browser-large-scene-performance-mode` now checks - `prefrozen=627` and `spinSkip=627`, proving repeated mesh clones avoid - re-traversing static visual subtrees and non-spinning clone trees. + `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`, and that instanced draw units are fewer + than instanced objects, proving repeated fixed inventory renders through + shared GPU batches instead of one cloned render tree per item. - Hover proxy 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 proxy bounds instead of traversing the visual root. - Scene-load batching gate: `browser-large-scene-performance-mode` now checks - `scene batches 1/636` and `yields 26`, proving the large scene is attached as + `scene batches 1/652` and `yields 26`, proving the large scene is attached as a single batch while object construction still yields to the browser event loop during load. - Resource lifecycle on a real Scene Builder compose switch: released `1` @@ -480,7 +492,7 @@ Control evidence: `acceptanceLatency=0 ms / 11-0-0`, `binding=635/636; 4/568`, `builderPhysics=已添加物体 4: 后端动态 4 / 仅视觉 0`, - `renderPerformance=large-scene; target 45 fps; actual 0.7 fps; dpr 1.00; buffer preserved false; readback renders 1; shadows off; skipped 28; hover 32ms; frozen 1839 prefrozen 627 spinSkip 627; manual roots 636 updates 67; primitive geometries 7; mesh cache 51 sources 576/51 hit/miss retained 51g/17m; bounds cache 636 fast 627 source 51 hoverProxy 1 cached 1/fallback 0 camera traversals 0; scene batches 1/636 suppressed 329 yields 26; state payload 34/602 reduced 3 incremental 4; ui cache physics 30/3 builder 33/1; pick proxies 636; state apply 0/skip 67; unchanged frames 1; 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 28; hover 32ms; frozen 703 prefrozen 59 spinSkip 627; instanced 568/16/16 matrices 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 source 51 hoverProxy 1 cached 1/fallback 0 camera traversals 0; scene batches 1/652 suppressed 349 yields 26; state payload 34/602 reduced 3 incremental 4; ui cache physics 33/3 builder 36/1; pick proxies 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: diff --git a/scripts/product-readiness-gate.mjs b/scripts/product-readiness-gate.mjs index 5e4b3ab..4d18a1e 100644 --- a/scripts/product-readiness-gate.mjs +++ b/scripts/product-readiness-gate.mjs @@ -646,6 +646,10 @@ async function readBrowserStats(page) { frozenStaticObjectCount: numberData("frozenStaticObjectCount"), preFrozenMeshCloneCount: numberData("preFrozenMeshCloneCount"), spinningScanSkippedCount: numberData("spinningScanSkippedCount"), + instancedMeshObjectCount: numberData("instancedMeshObjectCount"), + instancedMeshBatchCount: numberData("instancedMeshBatchCount"), + instancedMeshDrawCount: numberData("instancedMeshDrawCount"), + instancedMeshMatrixUpdateCount: numberData("instancedMeshMatrixUpdateCount"), manualMatrixRootCount: numberData("manualMatrixRootCount"), manualMatrixUpdateCount: numberData("manualMatrixUpdateCount"), primitiveGeometryCount: numberData("primitiveGeometryCount"), @@ -1633,8 +1637,13 @@ async function verifyBrowser() { && renderPerformance.hoverPickIntervalMs === 32 && (renderPerformance.renderSkipCount ?? 0) > 0 && (renderPerformance.frozenStaticObjectCount ?? 0) >= 500 - && (renderPerformance.preFrozenMeshCloneCount ?? 0) >= thresholds.minMeshes + && (renderPerformance.preFrozenMeshCloneCount ?? 0) + (renderPerformance.instancedMeshObjectCount ?? 0) >= thresholds.minMeshes && (renderPerformance.spinningScanSkippedCount ?? 0) >= thresholds.minMeshes + && (renderPerformance.instancedMeshObjectCount ?? 0) >= 500 + && (renderPerformance.instancedMeshBatchCount ?? 0) > 0 + && (renderPerformance.instancedMeshDrawCount ?? Number.POSITIVE_INFINITY) > 0 + && (renderPerformance.instancedMeshDrawCount ?? Number.POSITIVE_INFINITY) < (renderPerformance.instancedMeshObjectCount ?? 0) + && (renderPerformance.instancedMeshMatrixUpdateCount ?? 0) >= (renderPerformance.instancedMeshObjectCount ?? 0) && (renderPerformance.manualMatrixRootCount ?? 0) >= objectCount && (renderPerformance.primitiveGeometryCount ?? 0) > 0 && (renderPerformance.meshCacheSourceCount ?? 0) > 0 @@ -1657,7 +1666,7 @@ async function verifyBrowser() { && (renderPerformance.pickProxyCount ?? 0) >= objectCount && (renderPerformance.skippedBodyStateCount ?? 0) > 0 && desktopStats.diagnostics.renderPerformance.includes("large-scene"), - `mode=${renderPerformance.largeSceneMode} fps=${renderPerformance.targetRenderFps ?? "-"} 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 ?? "-"} 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 ?? "-"} source=${renderPerformance.meshSourceBoundsCount ?? "-"} hoverProxy=${renderPerformance.hoverProxyBoundsHitCount ?? "-"} cached=${renderPerformance.hoverCachedBoundsHitCount ?? "-"}/fallback=${renderPerformance.hoverRootBoundsFallbackCount ?? "-"} cameraTraversals=${renderPerformance.cameraFitTraversalCount ?? "-"} sceneBatches=${renderPerformance.sceneRootBatchCount ?? "-"}/${renderPerformance.batchedSceneRootCount ?? "-"} suppressed=${renderPerformance.sceneLoadSuppressedRenderCount ?? "-"} yields=${renderPerformance.sceneBuildYieldCount ?? "-"} statePayload=${renderPerformance.statePayloadBodyCount ?? "-"}/${renderPerformance.mergedBodyStateCount ?? "-"} reduced=${renderPerformance.reducedStateFrameCount ?? "-"} incremental=${renderPerformance.incrementalBodyMergeCount ?? "-"} uiCache=physics ${renderPerformance.objectPhysicsProfileCacheHitCount ?? "-"}/${renderPerformance.objectPhysicsProfileCacheMissCount ?? "-"} builder ${renderPerformance.builderPhysicsProfileCacheHitCount ?? "-"}/${renderPerformance.builderPhysicsProfileCacheMissCount ?? "-"} pickProxies=${renderPerformance.pickProxyCount ?? "-"} 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 ?? "-"} 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 ?? "-"} 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 ?? "-"} source=${renderPerformance.meshSourceBoundsCount ?? "-"} hoverProxy=${renderPerformance.hoverProxyBoundsHitCount ?? "-"} cached=${renderPerformance.hoverCachedBoundsHitCount ?? "-"}/fallback=${renderPerformance.hoverRootBoundsFallbackCount ?? "-"} cameraTraversals=${renderPerformance.cameraFitTraversalCount ?? "-"} sceneBatches=${renderPerformance.sceneRootBatchCount ?? "-"}/${renderPerformance.batchedSceneRootCount ?? "-"} suppressed=${renderPerformance.sceneLoadSuppressedRenderCount ?? "-"} yields=${renderPerformance.sceneBuildYieldCount ?? "-"} statePayload=${renderPerformance.statePayloadBodyCount ?? "-"}/${renderPerformance.mergedBodyStateCount ?? "-"} reduced=${renderPerformance.reducedStateFrameCount ?? "-"} incremental=${renderPerformance.incrementalBodyMergeCount ?? "-"} uiCache=physics ${renderPerformance.objectPhysicsProfileCacheHitCount ?? "-"}/${renderPerformance.objectPhysicsProfileCacheMissCount ?? "-"} builder ${renderPerformance.builderPhysicsProfileCacheHitCount ?? "-"}/${renderPerformance.builderPhysicsProfileCacheMissCount ?? "-"} pickProxies=${renderPerformance.pickProxyCount ?? "-"} 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 043de80..2af29e9 100644 --- a/src/main.ts +++ b/src/main.ts @@ -173,6 +173,10 @@ interface RuntimeDiagnostics { frozenStaticObjectCount: number; preFrozenMeshCloneCount: number; spinningScanSkippedCount: number; + instancedMeshObjectCount: number; + instancedMeshBatchCount: number; + instancedMeshDrawCount: number; + instancedMeshMatrixUpdateCount: number; manualMatrixRootCount: number; manualMatrixUpdateCount: number; primitiveGeometryCount: number; @@ -2501,6 +2505,10 @@ function currentRuntimeDiagnostics( frozenStaticObjectCount: stats.frozenStaticObjectCount, preFrozenMeshCloneCount: stats.preFrozenMeshCloneCount, spinningScanSkippedCount: stats.spinningScanSkippedCount, + instancedMeshObjectCount: stats.instancedMeshObjectCount, + instancedMeshBatchCount: stats.instancedMeshBatchCount, + instancedMeshDrawCount: stats.instancedMeshDrawCount, + instancedMeshMatrixUpdateCount: stats.instancedMeshMatrixUpdateCount, manualMatrixRootCount: stats.manualMatrixRootCount, manualMatrixUpdateCount: stats.manualMatrixUpdateCount, primitiveGeometryCount: stats.primitiveGeometryCount, @@ -2593,7 +2601,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; 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}; 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} 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}; ui cache physics ${stats.objectPhysicsProfileCacheHitCount}/${stats.objectPhysicsProfileCacheMissCount} builder ${stats.builderPhysicsProfileCacheHitCount}/${stats.builderPhysicsProfileCacheMissCount}; pick proxies ${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; 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}; 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} 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}; ui cache physics ${stats.objectPhysicsProfileCacheHitCount}/${stats.objectPhysicsProfileCacheMissCount} builder ${stats.builderPhysicsProfileCacheHitCount}/${stats.builderPhysicsProfileCacheMissCount}; pick proxies ${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(diagnostics = currentRuntimeDiagnostics()): void { @@ -2620,6 +2628,10 @@ function renderDiagnosticsPanel(diagnostics = currentRuntimeDiagnostics()): void data.frozenStaticObjectCount = String(diagnostics.stats.frozenStaticObjectCount); data.preFrozenMeshCloneCount = String(diagnostics.stats.preFrozenMeshCloneCount); data.spinningScanSkippedCount = String(diagnostics.stats.spinningScanSkippedCount); + data.instancedMeshObjectCount = String(diagnostics.stats.instancedMeshObjectCount); + data.instancedMeshBatchCount = String(diagnostics.stats.instancedMeshBatchCount); + data.instancedMeshDrawCount = String(diagnostics.stats.instancedMeshDrawCount); + data.instancedMeshMatrixUpdateCount = String(diagnostics.stats.instancedMeshMatrixUpdateCount); 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 da20e3d..ce38cfb 100644 --- a/src/preview/UniversalPreviewer.ts +++ b/src/preview/UniversalPreviewer.ts @@ -30,6 +30,26 @@ interface BoundObject { root: THREE.Object3D; } +interface InstancedSubmesh { + mesh: THREE.InstancedMesh; + sourceMatrix: THREE.Matrix4; +} + +interface InstancedVisualBatch { + key: string; + root: THREE.Group; + capacity: number; + used: number; + submeshes: InstancedSubmesh[]; +} + +interface InstancedVisualBinding { + batch: InstancedVisualBatch; + index: number; + root: THREE.Object3D; + local: THREE.Object3D; +} + export interface DragTargetPose { id: string; source: [number, number, number]; @@ -105,6 +125,9 @@ export class UniversalPreviewer { private readonly cachedMeshSources = new Set(); private readonly retainedMeshGeometries = new Set(); private readonly retainedMeshMaterials = new Set(); + private readonly instancedMeshBatchCapacities = new Map(); + private readonly instancedMeshBatches = new Map>(); + private readonly instancedVisualBindings = new Map(); private readonly bodyBindings = new Map(); private readonly objectsById = new Map(); private readonly pickProxyById = new Map(); @@ -120,6 +143,7 @@ export class UniversalPreviewer { private readonly scratchSize = new THREE.Vector3(); private readonly scratchPreviousFocusPosition = new THREE.Vector3(); private readonly scratchPreviousFocusQuaternion = new THREE.Quaternion(); + private readonly scratchMatrix = new THREE.Matrix4(); private readonly editableObjectIds = new Set(); private readonly clock = new THREE.Clock(); private readonly raycaster = new THREE.Raycaster(); @@ -152,6 +176,10 @@ export class UniversalPreviewer { private frozenStaticObjectCount = 0; private preFrozenMeshCloneCount = 0; private spinningScanSkippedCount = 0; + private instancedMeshObjectCount = 0; + private instancedMeshBatchCount = 0; + private instancedMeshDrawCount = 0; + private instancedMeshMatrixUpdateCount = 0; private manualMatrixRootCount = 0; private manualMatrixUpdateCount = 0; private releasedGeometryCount = 0; @@ -268,6 +296,7 @@ export class UniversalPreviewer { this.clearScene(); try { this.buildMaterials(manifest.materials ?? []); + this.prepareInstancedMeshBatchCapacities(manifest.objects); this.addDefaultHelpers(); this.addLights(manifest); this.applyCamera(manifest); @@ -331,7 +360,11 @@ export class UniversalPreviewer { } this.cacheBodyState(bodyName, bodyState); for (const item of bound) { - changed = this.applyBodyState(item.root, bodyName, bodyState) || changed; + const itemChanged = this.applyBodyState(item.root, bodyName, bodyState); + if (itemChanged) { + this.updateInstancedVisualMatrix(item.manifest.id); + } + changed = itemChanged || changed; appliedBodyStateCount += 1; } } @@ -435,6 +468,10 @@ export class UniversalPreviewer { frozenStaticObjectCount: this.frozenStaticObjectCount, preFrozenMeshCloneCount: this.preFrozenMeshCloneCount, spinningScanSkippedCount: this.spinningScanSkippedCount, + instancedMeshObjectCount: this.instancedMeshObjectCount, + instancedMeshBatchCount: this.instancedMeshBatchCount, + instancedMeshDrawCount: this.instancedMeshDrawCount, + instancedMeshMatrixUpdateCount: this.instancedMeshMatrixUpdateCount, manualMatrixRootCount: this.manualMatrixRootCount, manualMatrixUpdateCount: this.manualMatrixUpdateCount, primitiveGeometryCount: this.primitiveGeometryCache.size, @@ -988,6 +1025,9 @@ export class UniversalPreviewer { this.bodySourceOffsets.clear(); this.bodyVisualOffsets.clear(); this.bodyStateCache.clear(); + this.instancedMeshBatches.clear(); + this.instancedMeshBatchCapacities.clear(); + this.instancedVisualBindings.clear(); this.robotObjectIds.clear(); this.robotBodyNames.clear(); this.cancelDrag(); @@ -1008,6 +1048,10 @@ export class UniversalPreviewer { this.frozenStaticObjectCount = 0; this.preFrozenMeshCloneCount = 0; this.spinningScanSkippedCount = 0; + this.instancedMeshObjectCount = 0; + this.instancedMeshBatchCount = 0; + this.instancedMeshDrawCount = 0; + this.instancedMeshMatrixUpdateCount = 0; this.manualMatrixRootCount = 0; this.manualMatrixUpdateCount = 0; this.sceneObjectBounds.makeEmpty(); @@ -1094,6 +1138,9 @@ export class UniversalPreviewer { this.cachedMeshSources.clear(); this.retainedMeshGeometries.clear(); this.retainedMeshMaterials.clear(); + this.instancedMeshBatches.clear(); + this.instancedMeshBatchCapacities.clear(); + this.instancedVisualBindings.clear(); } private disposeMaterial(material: THREE.Material, disposedTextures: Set): void { @@ -1273,6 +1320,7 @@ export class UniversalPreviewer { } bound.root.position.copy(start).add(delta); this.updateManualObjectMatrix(bound.root); + this.updateInstancedVisualMatrix(targetId); } this.updateDraggedBodyOffsets(deltaSource); this.refreshDragHighlight(); @@ -1321,6 +1369,7 @@ export class UniversalPreviewer { } bound.root.position.copy(start).add(delta); this.updateManualObjectMatrix(bound.root); + this.updateInstancedVisualMatrix(targetId); } this.updateDraggedBodyOffsets(deltaSource); this.refreshDragHighlight(); @@ -1754,20 +1803,166 @@ export class UniversalPreviewer { this.controls.update(); } + private prepareInstancedMeshBatchCapacities(objects: PreviewObject[]): void { + this.instancedMeshBatchCapacities.clear(); + for (const object of objects) { + if (!this.isInstancedMeshCandidate(object)) { + continue; + } + const key = this.meshCacheKey(object.geometry, object.material); + this.instancedMeshBatchCapacities.set(key, (this.instancedMeshBatchCapacities.get(key) ?? 0) + 1); + } + for (const [key, count] of [...this.instancedMeshBatchCapacities]) { + if (count < 2) { + this.instancedMeshBatchCapacities.delete(key); + } + } + } + + private isInstancedMeshCandidate(object: PreviewObject): object is PreviewObject & { geometry: MeshGeometry } { + return this.largeSceneMode + && object.visible !== false + && object.geometry.kind === "mesh" + && object.physics === "fixed" + && Boolean(object.body); + } + + private async createInstancedVisual( + object: PreviewObject, + root: THREE.Object3D, + token: number, + sceneRoots: THREE.Object3D[], + ): Promise<{ local: THREE.Object3D } | undefined> { + if (!this.isInstancedMeshCandidate(object)) { + return undefined; + } + const key = this.meshCacheKey(object.geometry, object.material); + if (!this.instancedMeshBatchCapacities.has(key)) { + return undefined; + } + try { + const batch = await this.getInstancedMeshBatch(object.geometry, object.material, key, sceneRoots); + if (token !== this.loadToken) { + return undefined; + } + const sourceBounds = this.meshSourceBounds.get(key); + if (!sourceBounds || sourceBounds.isEmpty() || batch.submeshes.length === 0 || batch.used >= batch.capacity) { + return undefined; + } + const local = new THREE.Group(); + local.name = `${object.id}_local_pose`; + local.userData.sourceLocalBounds = sourceBounds; + local.userData.hasSpinningObjects = false; + this.converter.applyPose(local, object.pose); + local.updateMatrix(); + local.matrixAutoUpdate = false; + const index = batch.used; + batch.used += 1; + this.instancedVisualBindings.set(object.id, { + batch, + index, + root, + local, + }); + this.instancedMeshObjectCount += 1; + this.loadedMeshCount += 1; + return { local }; + } catch { + return undefined; + } + } + + private async getInstancedMeshBatch( + geometry: MeshGeometry, + materialId: string | undefined, + key: string, + sceneRoots: THREE.Object3D[], + ): Promise { + const pending = this.instancedMeshBatches.get(key); + if (pending) { + return pending; + } + const capacity = this.instancedMeshBatchCapacities.get(key) ?? 0; + const created = this.getMeshSource(geometry, materialId) + .then(({ source }) => this.createInstancedMeshBatch(key, source, capacity)); + this.instancedMeshBatches.set(key, created); + const batch = await created; + sceneRoots.push(batch.root); + return batch; + } + + private createInstancedMeshBatch(key: string, source: THREE.Object3D, capacity: number): InstancedVisualBatch { + const root = new THREE.Group(); + root.name = `instanced_${key.replace(/[^a-z0-9_-]+/gi, "_").slice(0, 72)}`; + root.matrixAutoUpdate = false; + source.updateWorldMatrix(true, true); + const submeshes: InstancedSubmesh[] = []; + source.traverse((child) => { + const sourceMesh = child as THREE.Mesh; + if (!sourceMesh.isMesh || !sourceMesh.geometry || !sourceMesh.material) { + return; + } + const instanced = new THREE.InstancedMesh(sourceMesh.geometry, sourceMesh.material, capacity); + instanced.name = `${root.name}_${submeshes.length}`; + instanced.castShadow = false; + instanced.receiveShadow = false; + instanced.frustumCulled = false; + instanced.matrixAutoUpdate = false; + instanced.instanceMatrix.setUsage(THREE.DynamicDrawUsage); + root.add(instanced); + submeshes.push({ + mesh: instanced, + sourceMatrix: sourceMesh.matrixWorld.clone(), + }); + }); + this.instancedMeshBatchCount += 1; + this.instancedMeshDrawCount += submeshes.length; + return { + key, + root, + capacity, + used: 0, + submeshes, + }; + } + + private updateInstancedVisualMatrix(id: string): void { + const binding = this.instancedVisualBindings.get(id); + if (!binding) { + return; + } + binding.root.updateWorldMatrix(true, false); + binding.local.updateWorldMatrix(true, false); + for (const submesh of binding.batch.submeshes) { + this.scratchMatrix.multiplyMatrices(binding.local.matrixWorld, submesh.sourceMatrix); + submesh.mesh.setMatrixAt(binding.index, this.scratchMatrix); + submesh.mesh.instanceMatrix.needsUpdate = true; + } + this.instancedMeshMatrixUpdateCount += 1; + } + private async addObject(object: PreviewObject, token: number, sceneRoots: THREE.Object3D[]): Promise { const root = new THREE.Group(); root.name = object.name ?? object.id; root.visible = object.visible !== false; root.userData.manifestId = object.id; - const visual = await this.createVisual(object.geometry, object.material, token); + const instancedVisual = await this.createInstancedVisual(object, root, token, sceneRoots); if (token !== this.loadToken) { return; } - visual.castShadow = !this.largeSceneMode && (object.castShadow ?? true); - visual.receiveShadow = !this.largeSceneMode && (object.receiveShadow ?? true); + const visual = instancedVisual?.local ?? await this.createVisual(object.geometry, object.material, token); + if (token !== this.loadToken) { + return; + } + if (!instancedVisual) { + visual.castShadow = !this.largeSceneMode && (object.castShadow ?? true); + visual.receiveShadow = !this.largeSceneMode && (object.receiveShadow ?? true); + } visual.name = `${object.id}_visual`; - if (object.body) { + if (instancedVisual) { + root.add(instancedVisual.local); + } else if (object.body) { const local = new THREE.Group(); local.name = `${object.id}_local_pose`; this.converter.applyPose(local, object.pose); @@ -1792,6 +1987,9 @@ export class UniversalPreviewer { sceneRoots.push(root); this.pickRoots.push(pickProxy ?? root); this.registerSpinningObjects(root, visual); + if (instancedVisual) { + this.updateInstancedVisualMatrix(object.id); + } this.objectsById.set(object.id, { manifest: object, root }); if (object.editableGroup) { const group = this.editableGroups.get(object.editableGroup) ?? []; @@ -2141,32 +2339,7 @@ export class UniversalPreviewer { private async loadMesh(geometry: MeshGeometry, materialId: string | undefined, token: number): Promise { try { - const format = geometry.format ?? inferMeshFormat(geometry.url); - const cacheKey = `${format ?? "unknown"}:${geometry.url}:${geometry.materialOverride ?? materialId ?? "default"}`; - let pending = this.meshCache.get(cacheKey); - if (!pending) { - this.meshCacheMissCount += 1; - const material = this.getMaterial(geometry.materialOverride ?? materialId); - pending = this.loadMeshSource(geometry, format, material) - .then((source) => { - this.prepareLoadedMesh(source); - const bounds = new THREE.Box3().setFromObject(source); - if (!bounds.isEmpty()) { - this.meshSourceBounds.set(cacheKey, bounds.clone()); - } - this.cachedMeshSources.add(source); - this.retainMeshSourceResources(source); - return source; - }) - .catch((error) => { - this.meshCache.delete(cacheKey); - throw error; - }); - this.meshCache.set(cacheKey, pending); - } else { - this.meshCacheHitCount += 1; - } - const source = await pending; + const { source, cacheKey } = await this.getMeshSource(geometry, materialId); const loaded = source.clone(true); const sourceBounds = this.meshSourceBounds.get(cacheKey); if (sourceBounds) { @@ -2190,6 +2363,46 @@ export class UniversalPreviewer { } } + private async getMeshSource( + geometry: MeshGeometry, + materialId: string | undefined, + ): Promise<{ source: THREE.Object3D; cacheKey: string }> { + const format = geometry.format ?? inferMeshFormat(geometry.url); + const cacheKey = this.meshCacheKey(geometry, materialId, format); + let pending = this.meshCache.get(cacheKey); + if (!pending) { + this.meshCacheMissCount += 1; + const material = this.getMaterial(geometry.materialOverride ?? materialId); + pending = this.loadMeshSource(geometry, format, material) + .then((source) => { + this.prepareLoadedMesh(source); + const bounds = new THREE.Box3().setFromObject(source); + if (!bounds.isEmpty()) { + this.meshSourceBounds.set(cacheKey, bounds.clone()); + } + this.cachedMeshSources.add(source); + this.retainMeshSourceResources(source); + return source; + }) + .catch((error) => { + this.meshCache.delete(cacheKey); + throw error; + }); + this.meshCache.set(cacheKey, pending); + } else { + this.meshCacheHitCount += 1; + } + return { source: await pending, cacheKey }; + } + + private meshCacheKey( + geometry: MeshGeometry, + materialId: string | undefined, + format: MeshGeometry["format"] | undefined = geometry.format ?? inferMeshFormat(geometry.url), + ): string { + return `${format ?? "unknown"}:${geometry.url}:${geometry.materialOverride ?? materialId ?? "default"}`; + } + private async loadMeshSource( geometry: MeshGeometry, format: MeshGeometry["format"] | undefined, diff --git a/src/types.ts b/src/types.ts index 7fd844d..466b5da 100644 --- a/src/types.ts +++ b/src/types.ts @@ -207,6 +207,10 @@ export interface RendererStats { frozenStaticObjectCount: number; preFrozenMeshCloneCount: number; spinningScanSkippedCount: number; + instancedMeshObjectCount: number; + instancedMeshBatchCount: number; + instancedMeshDrawCount: number; + instancedMeshMatrixUpdateCount: number; manualMatrixRootCount: number; manualMatrixUpdateCount: number; primitiveGeometryCount: number;