Progressively mount large scene roots

This commit is contained in:
eust-w 2026-06-25 06:32:24 +08:00
parent d2bb640957
commit 1506fb455d
3 changed files with 68 additions and 38 deletions

View File

@ -374,9 +374,11 @@ Scene evidence:
- Scratch bounds transforms: pick-target bounds construction reuses `Box3`,
`Matrix4`, and corner `Vector3` scratch objects for cached mesh bounds instead
of allocating transformed bounds for every repeated shelf/product object.
- Scene-load render gating: large scene roots are batched into one Three.js
insertion after object preparation, and the render loop skips partial scene
frames while the batch is still loading.
- Progressive scene-load batching: large scene roots are mounted into the
Three.js scene in bounded batches during object preparation, while instanced
mesh batches still wait until their matrices and bounds are finalized. The
render loop only paints loading frames when a new batch is ready, so scene
import provides visible progress without returning to per-object scene churn.
- Scene-build yielding: large scene object construction periodically yields to
the browser event loop during load; the release gate checks
`sceneBuildYieldCount` so this cannot silently regress back to one long main
@ -419,13 +421,13 @@ Scene evidence:
Bundle evidence:
- JavaScript chunks: `4`
- App entry chunk: `200.56 kB raw / 51.84 kB gzip`
- App entry chunk: `200.90 kB raw / 51.95 kB gzip`
- Largest JavaScript gzip chunk: `140.96 KiB / 170.00 KiB`
- Total JavaScript gzip: `215.45 KiB / 230.00 KiB`
- Total JavaScript gzip: `215.56 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
gate, `preserveDrawingBuffer=false`, `1` explicit readback render, shadows
`off`, hover picking throttled to `32ms`, `36` empty frames
`off`, hover picking throttled to `32ms`, `39` empty frames
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
@ -434,21 +436,21 @@ Bundle evidence:
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
bounds from `51` cached source bounds, real hover proof `hoverProxy 1` with
cached bounds and `fallback 0`, with `0` camera-fit traversals, `1/84`
scene root batch insertion under the computed `84` root cap, `347`
partial render frames
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, `259` no-op loading 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 `31/3` hit/miss, UI builder-profile cache `34/1`
hit/miss, UI text write gating `108/464` write/skip, text selector cache
`526/46` hit/miss, scratch bounds transforms `1263`, diagnostics panel
throttling `20/7` render/skip, `88/636`
hit/miss, UI text write gating `114/504` write/skip, text selector cache
`572/46` hit/miss, scratch bounds transforms `1263`, diagnostics panel
throttling `21/6` 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
67` with `state apply 0/skip 67`.
- Mesh cache lifecycle evidence: the Scene Builder compose switch reported
cumulative `1203/51` mesh cache hit/miss with `51` retained geometries and
cumulative `99/51` mesh cache hit/miss with `51` retained geometries and
`17` retained materials, avoiding repeated parser/network work for duplicate
shelf and product assets.
- Active-state gate: `browser-large-scene-performance-mode` now checks
@ -494,10 +496,10 @@ Bundle evidence:
`fallback=0`, proving hover highlight uses the pruned cached bounds list
instead of traversing the visual root. The current proof hits the shelf
fixture at `point=0.35,0.50` with `固定物理体: geom_64`.
- Scene-load batching gate: `browser-large-scene-performance-mode` now checks
`scene batches 1/84`, `maxSceneRoots=84`, and `yields 26`, proving fixed
instanced object roots stay detached from the Three scene while object
construction still yields to the browser event loop during load.
- Progressive scene-load batching gate: `browser-large-scene-performance-mode`
now checks `scene batches 4/84`, `maxSceneRoots=84`, `maxBatches=5`, and
`yields 26`, proving large scene import mounts bounded visible batches while
repeated fixed inventory still renders through finalized instanced batches.
- Resource lifecycle on a real Scene Builder compose switch: released `1`
geometry, `10` materials, and `2` textures from non-retained scene graph
resources while preserving cached mesh sources.
@ -518,8 +520,8 @@ Control evidence:
- Dynamic composed object drop: `0.48012m`.
- Static shelf anchor stability: `max drift 0.00000m` after a 2500 ms resume
window.
- Resume backend state: `58ms paused=false`
- Resume visible UI state: `60ms`
- Resume backend state: `61ms paused=false`
- Resume visible UI state: `62ms`
- Pause backend state: `50ms paused=true`
- Pause visible UI state: `39ms`
- Desktop acceptance wait: `1243ms` total, product telemetry `0ms`
@ -527,11 +529,11 @@ Control evidence:
- Runtime diagnostics panel:
`state=http://127.0.0.1:18090/state`,
`control=http://127.0.0.1:18090/control`,
`latency=响应 38 ms / 确认 38 ms / 可见 39 ms`,
`latency=响应 39 ms / 确认 39 ms / 可见 39 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 36; hover 32ms; frozen 703 prefrozen 59 spinSkip 627; instanced 568/16/16 matrices 568 cull 16 static 16; 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 1/84 suppressed 347 yields 26; state payload 34/602 reduced 3 incremental 4; ui cache physics 31/3 builder 34/1 text 112/494 selector 560/46 diagnostics 21/6; pick targets 88/636; state apply 0/skip 67; unchanged frames 1; released 0g/0m/0t`.
`renderPerformance=large-scene; target 45 fps; actual 0.8 fps; dpr 1.00; buffer preserved false; readback renders 1; shadows off; skipped 39; hover 32ms; frozen 703 prefrozen 59 spinSkip 627; instanced 568/16/16 matrices 568 cull 16 static 16; 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 259 yields 26; state payload 34/602 reduced 3 incremental 4; ui cache physics 31/3 builder 34/1 text 112/494 selector 560/46 diagnostics 21/6; 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:

View File

@ -1655,6 +1655,7 @@ async function verifyBrowser() {
- (renderPerformance.instancedMeshObjectCount ?? 0)
+ (renderPerformance.instancedMeshBatchCount ?? 0),
);
const maxProgressiveSceneRootBatches = Math.max(2, Math.ceil(maxInstancedSceneRoots / 24) + 1);
const maxHoverPickTargets = Math.max(100, Math.ceil(objectCount * 0.18));
check(
"browser-large-scene-performance-mode",
@ -1693,7 +1694,8 @@ async function verifyBrowser() {
&& (renderPerformance.statePayloadBodyCount ?? Number.POSITIVE_INFINITY) < (renderPerformance.mergedBodyStateCount ?? 0)
&& (renderPerformance.mergedBodyStateCount ?? 0) >= thresholds.minBodyBindings
&& (renderPerformance.batchedSceneRootCount ?? Number.POSITIVE_INFINITY) <= maxInstancedSceneRoots
&& (renderPerformance.sceneRootBatchCount ?? 0) === 1
&& (renderPerformance.sceneRootBatchCount ?? 0) > 1
&& (renderPerformance.sceneRootBatchCount ?? Number.POSITIVE_INFINITY) <= maxProgressiveSceneRootBatches
&& (renderPerformance.objectPhysicsProfileCacheHitCount ?? 0) > 0
&& (renderPerformance.builderPhysicsProfileCacheHitCount ?? 0) > 0
&& (renderPerformance.textWriteSkipCount ?? 0) > 0
@ -1707,7 +1709,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 ?? "-"} 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 ?? "-"} 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} 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 ?? "-"} text ${renderPerformance.textWriteCount ?? "-"}/${renderPerformance.textWriteSkipCount ?? "-"} selector ${renderPerformance.textSelectorCacheHitCount ?? "-"}/${renderPerformance.textSelectorCacheMissCount ?? "-"} diagnostics ${renderPerformance.diagnosticsPanelRenderCount ?? "-"}/${renderPerformance.diagnosticsPanelSkipCount ?? "-"} 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 ?? "-"} 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 ?? "-"} 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 ?? "-"} 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 ?? "-"} 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",

View File

@ -18,6 +18,9 @@ import type {
} from "../types";
import { CoordinateConverter } from "../utils/coordinates";
const LARGE_SCENE_ROOT_BATCH_SIZE = 24;
const LARGE_SCENE_LOADING_RENDER_INTERVAL_MS = 1000 / 20;
type InteractionMode = "idle" | "inspect" | "hover" | "dragging";
type PointerLikeEvent = PointerEvent | MouseEvent;
@ -56,6 +59,11 @@ interface PickBoundsTarget {
worldBounds: THREE.Box3;
}
interface SceneBuildRoots {
visible: THREE.Object3D[];
instanced: THREE.Object3D[];
}
export interface DragTargetPose {
id: string;
source: [number, number, number];
@ -629,18 +637,21 @@ export class UniversalPreviewer {
private animate = (): void => {
this.animationHandle = requestAnimationFrame(this.animate);
if (this.sceneLoadInProgress) {
const now = performance.now();
if (this.sceneLoadInProgress && !this.renderDirty) {
this.sceneLoadSuppressedRenderCount += 1;
return;
}
if (performance.now() < this.renderSuspendedUntil) {
if (now < this.renderSuspendedUntil) {
return;
}
const now = performance.now();
const controlsChanged = this.controls.update();
const focusChanged = this.updateFocusMarker();
const spinChanged = this.updateSpinningObjects(this.clock.getElapsedTime());
const enoughTimeElapsed = this.targetRenderIntervalMs <= 0 || now - this.lastRenderAt >= this.targetRenderIntervalMs;
const renderIntervalMs = this.sceneLoadInProgress
? Math.max(this.targetRenderIntervalMs, LARGE_SCENE_LOADING_RENDER_INTERVAL_MS)
: this.targetRenderIntervalMs;
const enoughTimeElapsed = renderIntervalMs <= 0 || now - this.lastRenderAt >= renderIntervalMs;
if (!enoughTimeElapsed || (!this.renderDirty && !controlsChanged && !focusChanged && !spinChanged)) {
this.renderSkipCount += 1;
return;
@ -1845,7 +1856,7 @@ export class UniversalPreviewer {
object: PreviewObject,
root: THREE.Object3D,
token: number,
sceneRoots: THREE.Object3D[],
sceneRoots: SceneBuildRoots,
): Promise<{ local: THREE.Object3D } | undefined> {
if (!this.isInstancedMeshCandidate(object)) {
return undefined;
@ -1890,7 +1901,7 @@ export class UniversalPreviewer {
geometry: MeshGeometry,
materialId: string | undefined,
key: string,
sceneRoots: THREE.Object3D[],
sceneRoots: SceneBuildRoots,
): Promise<InstancedVisualBatch> {
const pending = this.instancedMeshBatches.get(key);
if (pending) {
@ -1901,7 +1912,7 @@ export class UniversalPreviewer {
.then(({ source }) => this.createInstancedMeshBatch(key, source, capacity));
this.instancedMeshBatches.set(key, created);
const batch = await created;
sceneRoots.push(batch.root);
sceneRoots.instanced.push(batch.root);
return batch;
}
@ -1972,7 +1983,7 @@ export class UniversalPreviewer {
}
}
private async addObject(object: PreviewObject, token: number, sceneRoots: THREE.Object3D[]): Promise<void> {
private async addObject(object: PreviewObject, token: number, sceneRoots: SceneBuildRoots): Promise<void> {
const root = new THREE.Group();
root.name = object.name ?? object.id;
root.visible = object.visible !== false;
@ -2015,7 +2026,7 @@ export class UniversalPreviewer {
}
this.freezeObjectRootMatrix(root);
if (!instancedVisual) {
sceneRoots.push(root);
sceneRoots.visible.push(root);
}
this.registerSpinningObjects(root, visual);
if (instancedVisual) {
@ -2055,7 +2066,10 @@ export class UniversalPreviewer {
private async addObjects(objects: PreviewObject[], token: number): Promise<void> {
let nextIndex = 0;
let builtSinceYield = 0;
const sceneRoots: THREE.Object3D[] = [];
const sceneRoots: SceneBuildRoots = {
visible: [],
instanced: [],
};
const workerCount = Math.min(24, Math.max(1, objects.length));
const workers = Array.from({ length: workerCount }, async () => {
while (token === this.loadToken) {
@ -2067,6 +2081,7 @@ export class UniversalPreviewer {
}
await this.addObject(object, token, sceneRoots);
builtSinceYield += 1;
this.flushSceneRootBatch(sceneRoots.visible);
if (this.largeSceneMode && builtSinceYield >= 24) {
builtSinceYield = 0;
await this.yieldDuringSceneBuild(token);
@ -2077,18 +2092,29 @@ export class UniversalPreviewer {
if (token !== this.loadToken) {
return;
}
this.flushSceneRootBatch(sceneRoots.visible, true);
await this.finalizeInstancedMeshBatches();
if (token !== this.loadToken) {
return;
}
if (sceneRoots.length > 0) {
this.root.add(...sceneRoots);
this.batchedSceneRootCount += sceneRoots.length;
this.sceneRootBatchCount += 1;
}
this.flushSceneRootBatch(sceneRoots.instanced, true);
this.refreshEditablePickTargets();
}
private flushSceneRootBatch(sceneRoots: THREE.Object3D[], force = false): void {
if (sceneRoots.length === 0) {
return;
}
if (!force && sceneRoots.length < LARGE_SCENE_ROOT_BATCH_SIZE) {
return;
}
const batch = sceneRoots.splice(0, sceneRoots.length);
this.root.add(...batch);
this.batchedSceneRootCount += batch.length;
this.sceneRootBatchCount += 1;
this.markRenderDirty();
}
private async yieldDuringSceneBuild(token: number): Promise<void> {
this.sceneBuildYieldCount += 1;
await new Promise<void>((resolve) => window.setTimeout(resolve, 0));