@ifc-lite/renderer 1.35.2 → 1.37.0

package/dist/index.js

@@ -32,6 +32,12 @@ export * from './types.js';
 export { resolveEnvironment, deriveSkyGradient, packEnvironmentUniforms, ENVIRONMENT_UNIFORM_SIZE, } from './environment.js';
 // Extracted manager classes
 export { PickingManager } from './picking-manager.js';
+export { resolveContributionThresholdPx, projectedAabbRadiusPx } from './contribution-cull.js';
+export { chunkCellKey, bucketBaseKeyFor, DEFAULT_CHUNK_CELL_SIZE } from './chunk-grid.js';
+export { selectEvictions, MIN_EVICTION_AGE_FRAMES } from './residency.js';
+export { simplifyIndicesByClustering, lodCellSizeForBounds, LOD_MIN_TRIANGLES, LOD_CELL_FRACTION } from './lod-simplify.js';
+export { quantizeInterleaved, octEncode, octDecode, QUANT_STEP, MAX_QUANT_EXTENT, QUANT_BYTES_PER_VERTEX } from './quantize.js';
+export { sumResidentGpuBytes } from './render-stats.js';
 export { RaycastEngine } from './raycast-engine.js';
 export { PointPicker, decodePickSample } from './point-picker.js';
 // Point cloud rendering (Phase 0: IFCx inline; Phase 1+: streaming LAS/LAZ)
@@ -53,6 +59,7 @@ import { PickingManager } from './picking-manager.js';
 import { RaycastEngine } from './raycast-engine.js';
 import { PostProcessor } from './post-processor.js';
 import { InteractionEffectsGovernor } from './interaction-effects-governor.js';
+import { resolveContributionThresholdPx, projectedAabbRadiusPx, projectedInstancedRadiusPx } from './contribution-cull.js';
 import { EdlPass } from './edl-pass.js';
 import { SkyPass } from './sky-pass.js';
 import { skyShaderSource } from './shaders/sky.wgsl.js';
@@ -144,6 +151,8 @@ export class Renderer {
     // Diagnostic counters for mobile debugging
     _renderCallCount = 0;
     _renderSkipCount = 0;
+    /** Snapshot of the last completed render() — see getFrameStats(). */
+    _lastFrameStats = null;
     _renderErrorCount = 0;
     _lastRenderError = '';
     // Dirty flag: set by requestRender(), consumed by the animation loop.
@@ -155,7 +164,9 @@ export class Renderer {
     // Pooled per-frame buffers to avoid GC pressure from per-batch Float32Array allocations
     // A single 224-byte uniform buffer (56 floats) is reused for all batches/meshes within a frame
     // (48 floats viewProj…flags + 8 floats clipBoxMin/clipBoxMax)
-    uniformScratch = new Float32Array(56);
+    // 60 floats = the WGSL Uniforms struct incl. quantParams (see
+    // pipeline.getUniformBufferSize).
+    uniformScratch = new Float32Array(60);
     uniformScratchU32 = new Uint32Array(this.uniformScratch.buffer, 176, 4);
     // What the last render() actually clipped, so the GPU picker can mirror it and
     // section/crop-clipped geometry stays unpickable, not just invisible. Updated
@@ -739,13 +750,24 @@ export class Renderer {
         const fr = Math.fround;
         const sox = so ? fr(so[0]) : null, soy = so ? fr(so[1]) : 0, soz = so ? fr(so[2]) : 0;
         const dx = so ? (ox - so[0]) : ox, dy = so ? (oy - so[1]) : oy, dz = so ? (oz - so[2]) : oz;
+        // Quantized batches (issue #1682 phase 6) render lattice-snapped
+        // positions: the shader's quantMin + q*step is exactly the lattice
+        // node nearest the batch's stored f32 rel coordinate. Reproduce it by
+        // snapping the SAME rel coordinate here (round(s*1024)/1024 in f64
+        // yields the identical exact-f32 lattice value — see quantize.ts), so
+        // the highlight/picker mesh stays BIT-coincident with its quantized
+        // source surface, exactly as the two-step fold above achieves for the
+        // f32 path. Meshes whose batch fell back to f32 must not snap.
+        const snap = this.scene.isMeshQuantized(meshData)
+            ? (v) => Math.round(v * 1024) / 1024
+            : (v) => v;
         const p = meshData.positions;
         for (let i = 0; i < vertexCount; i++) {
             const base = i * 7;
             const posBase = i * 3;
-            interleaved[base] = so ? fr(sox + fr(p[posBase] + dx)) : (p[posBase] + dx);
-            interleaved[base + 1] = so ? fr(soy + fr(p[posBase + 1] + dy)) : (p[posBase + 1] + dy);
-            interleaved[base + 2] = so ? fr(soz + fr(p[posBase + 2] + dz)) : (p[posBase + 2] + dz);
+            interleaved[base] = so ? fr(sox + snap(fr(p[posBase] + dx))) : snap(p[posBase] + dx);
+            interleaved[base + 1] = so ? fr(soy + snap(fr(p[posBase + 1] + dy))) : snap(p[posBase + 1] + dy);
+            interleaved[base + 2] = so ? fr(soz + snap(fr(p[posBase + 2] + dz))) : snap(p[posBase + 2] + dz);
             const hasNormals = meshData.normals.length > 0;
             interleaved[base + 3] = hasNormals ? meshData.normals[posBase] : 0;
             interleaved[base + 4] = hasNormals ? meshData.normals[posBase + 1] : 0;
@@ -834,6 +856,29 @@ export class Renderer {
             bounds: b ? `${b.min.x.toFixed(0)}..${b.max.x.toFixed(0)} ${b.min.y.toFixed(0)}..${b.max.y.toFixed(0)} ${b.min.z.toFixed(0)}..${b.max.z.toFixed(0)}` : 'none',
         };
     }
+    /**
+     * Statistics of the last COMPLETED render() call (draw calls issued,
+     * batches drawn / frustum-culled / contribution-culled), or null before
+     * the first frame. Pair with `getScene().getResidentGpuBytes()` for the
+     * load-complete telemetry snapshot (issue #1682 observability).
+     */
+    getFrameStats() {
+        return this._lastFrameStats;
+    }
+    /**
+     * Probe the quantized pipeline variants and, when all exist, enable
+     * 12-byte quantized batch vertices (issue #1682 phase 6). Returns
+     * whether quantization is active — on failure (e.g. a fragile backend
+     * rejecting pipeline creation) batches stay on the f32 path.
+     */
+    async enableQuantizedBatches() {
+        if (!this.pipeline)
+            return false;
+        const ok = await this.pipeline.ensureQuantizedPipelines();
+        if (ok)
+            this.scene.setQuantizedBatches(true);
+        return ok;
+    }
     render(options = {}) {
         this._renderCallCount++;
         if (!this.device.isInitialized() || !this.pipeline) {
@@ -880,6 +925,24 @@ export class Renderer {
         }
         const device = this.device.getDevice();
         const viewProj = this.camera.getViewProjMatrix().m;
+        // Frame stats (issue #1682): geometry draw calls + per-frame cull
+        // outcomes, snapshotted into _lastFrameStats before queue.submit.
+        let frameDrawCalls = 0;
+        let frameBatchesDrawn = 0;
+        let frameBatchesFrustumCulled = 0;
+        let frameBatchesContributionCulled = 0;
+        let frameBatchesNotResident = 0;
+        let frameBatchesAtLod1 = 0;
+        let frameInstancedDrawn = 0;
+        let frameInstancedFrustumCulled = 0;
+        let frameInstancedContributionCulled = 0;
+        // Residency ages are measured in RENDERED frames (idle never ages out).
+        this.scene.beginResidencyFrame();
+        // Capture renders restore evicted batches SYNCHRONOUSLY so isolation
+        // snapshots are complete in this very frame (see RenderOptions doc).
+        if (options.restoreEvictedForCapture && this.pipeline) {
+            this.scene.restoreAllEvicted(device, this.pipeline);
+        }
         const visualEnhancement = this.resolveVisualEnhancement(options.visualEnhancement);
         // Post effects during interaction (orbit/pan/zoom) are governed
         // adaptively: they stay on while the interactive frame cadence holds
@@ -1446,6 +1509,35 @@ export class Renderer {
                 // Frustum culling for batched meshes - skip entire batches outside the camera view
                 // This is the primary performance optimization for large models (200K+ meshes)
                 const frustum = FrustumUtils.fromViewProjMatrix(viewProj);
+                // Contribution culling (issue #1682): skip batches whose world
+                // AABB projects below a pixel threshold. Disabled unless the
+                // caller opts in via options.contributionCull; the threshold is
+                // raised while interacting (quality matters least mid-gesture).
+                const contribThresholdPx = resolveContributionThresholdPx(options.contributionCull, interacting);
+                // LOD1 selection (issue #1682 phase 5): batches projecting below
+                // this draw their simplified index range. Shares the projection
+                // camera with contribution culling. Precedence is intentional:
+                // a batch below the CULL threshold is skipped entirely, so a
+                // lod threshold at or below the cull threshold never fires.
+                const lodScreenPx = options.lod && options.lod.screenPx > 0 ? options.lod.screenPx : 0;
+                const lodBatches = new Set();
+                let cullCam = null;
+                if (contribThresholdPx > 0 || lodScreenPx > 0) {
+                    const eye = this.camera.getPosition();
+                    const tgt = this.camera.getTarget();
+                    const dx = tgt.x - eye.x, dy = tgt.y - eye.y, dz = tgt.z - eye.z;
+                    const len = Math.sqrt(dx * dx + dy * dy + dz * dz);
+                    cullCam = {
+                        eye,
+                        // Degenerate (eye == target) stays zero-length — the
+                        // projection helper fails open (never culls) on it.
+                        viewDir: len > 0 ? { x: dx / len, y: dy / len, z: dz / len } : { x: 0, y: 0, z: 0 },
+                        mode: this.camera.getProjectionMode(),
+                        fovYRadians: this.camera.getFOV(),
+                        orthoHalfHeight: this.camera.getOrthoSize(),
+                        viewportHeightPx: this.canvas.height,
+                    };
+                }
                 // Pre-compute visibility for each batch (only when filtering is active)
                 // A batch is visible if ANY of its elements are visible
                 // A batch is fully visible if ALL of its elements are visible
@@ -1524,8 +1616,25 @@ export class Renderer {
                     if (batch.bounds) {
                         const batchAABB = { min: batch.bounds.min, max: batch.bounds.max };
                         if (!FrustumUtils.isAABBVisible(frustum, batchAABB)) {
+                            frameBatchesFrustumCulled++;
                             continue; // Entire batch is off-screen
                         }
+                        if (cullCam) {
+                            const px = projectedAabbRadiusPx(batch.bounds.min, batch.bounds.max, cullCam);
+                            // Contribution cull: the whole batch projects below the
+                            // pixel threshold — drawing it could change at most a
+                            // (sub-)pixel. Selected entities still highlight: the
+                            // selection pass draws per-mesh, independent of batches.
+                            if (contribThresholdPx > 0 && px < contribThresholdPx) {
+                                frameBatchesContributionCulled++;
+                                continue;
+                            }
+                            // LOD1: small-but-visible batches draw the simplified
+                            // index range over the same vertices.
+                            if (lodScreenPx > 0 && px < lodScreenPx && batch.lod1IndexBuffer) {
+                                lodBatches.add(batch.id);
+                            }
+                        }
                     }
                     const alpha = alphaForBatch(batch, batch.color[3]);
                     const nativelyTransparent = alpha < 0.99;
@@ -1546,10 +1655,28 @@ export class Renderer {
                             if (visibleIds.size > 0) {
                                 pushVisibleAsPartial(batch, visibleIds, nativelyTransparent);
                             }
+                            // A COLD parent has no CPU meshData, so the partial
+                            // sub-batch above comes back empty — queue the
+                            // residency restore or the visible subset would
+                            // stay missing under hide/isolate forever.
+                            if (batch.gpuResident === false) {
+                                this.scene.requestBatchResidency(batch);
+                            }
                             continue; // Don't add batch to render list
                         }
                     }
-                    // Fully visible (or no filtering). Transparent batches with mixed
+                    // Fully visible (or no filtering) — this batch draws from its OWN
+                    // GPU buffers. An evicted batch (residency budget, #1682 phase 3a)
+                    // is skipped for a frame while its rebuild is queued; the partial
+                    // path above is unaffected (sub-batches own separate buffers built
+                    // from CPU meshData).
+                    if (batch.gpuResident === false) {
+                        this.scene.requestBatchResidency(batch);
+                        frameBatchesNotResident++;
+                        continue;
+                    }
+                    this.scene.recordBatchDrawn(batch);
+                    // Transparent batches with mixed
                     // override membership must be split so non-overridden batchmates
                     // stay transparent — see splitVisibleIdsByPromotion / issue #677.
                     if (nativelyTransparent) {
@@ -1643,12 +1770,44 @@ export class Renderer {
                     tpl[28] = o ? o[0] : 0;
                     tpl[29] = o ? o[1] : 0;
                     tpl[30] = o ? o[2] : 0;
+                    // Quantized dequantization params (issue #1682 phase 6);
+                    // zeroed for f32 batches (their pipelines ignore them).
+                    const qz = batch.quantized;
+                    tpl[56] = qz ? qz.min[0] : 0;
+                    tpl[57] = qz ? qz.min[1] : 0;
+                    tpl[58] = qz ? qz.min[2] : 0;
+                    tpl[59] = qz ? qz.step : 0;
                     device.queue.writeBuffer(batch.uniformBuffer, 0, tpl);
-                    // Single draw call for entire batch!
+                    // Single draw call for entire batch! LOD1-selected batches
+                    // bind their simplified index range over the same vertices.
+                    const useLod1 = batch.lod1IndexBuffer && batch.lod1IndexCount && lodBatches.has(batch.id);
                     pass.setBindGroup(0, batch.bindGroup);
                     pass.setVertexBuffer(0, batch.vertexBuffer);
-                    pass.setIndexBuffer(batch.indexBuffer, 'uint32');
-                    pass.drawIndexed(batch.indexCount);
+                    if (useLod1) {
+                        pass.setIndexBuffer(batch.lod1IndexBuffer, 'uint32');
+                        pass.drawIndexed(batch.lod1IndexCount);
+                        frameBatchesAtLod1++;
+                    }
+                    else {
+                        pass.setIndexBuffer(batch.indexBuffer, 'uint32');
+                        pass.drawIndexed(batch.indexCount);
+                    }
+                    frameDrawCalls++;
+                    frameBatchesDrawn++;
+                };
+                // Quantized batches (issue #1682 phase 6) draw through the
+                // quantized pipeline variants; scene only quantizes after the
+                // probe (enableQuantizedBatches) verified they exist, so the
+                // base fallback here is type-safety, never taken.
+                const pipeFor = (batch, kind) => {
+                    const base = kind === 'opaque'
+                        ? this.pipeline.getPipeline()
+                        : kind === 'transparent'
+                            ? this.pipeline.getTransparentPipeline()
+                            : this.pipeline.getOverlayPipeline();
+                    if (!batch.quantized)
+                        return base;
+                    return this.pipeline.getQuantizedPipelineVariant(kind) ?? base;
                 };
                 // Render opaque batches with the opaque (double-sided) pipeline.
                 // Material-layer slices render double-sided like all other IFC
@@ -1661,8 +1820,10 @@ export class Renderer {
                 // Double-siding draws every face of the watertight skin ⇒ solid.
                 pass.setPipeline(this.pipeline.getPipeline());
                 for (const batch of opaqueBatches) {
+                    pass.setPipeline(pipeFor(batch, 'opaque'));
                     renderBatch(batch);
                 }
+                pass.setPipeline(this.pipeline.getPipeline());
                 // GPU-instancing pass — repeated geometry collated by the producer
                 // into one template + a per-occurrence instance buffer (mat4 +
                 // entityId + rgba), drawn with the instanced pipeline as
@@ -1672,7 +1833,40 @@ export class Renderer {
                 // IFC Z-up→WebGL Y-up swap, so the uniform's model is unused here;
                 // we reuse the frame's viewProj + section + flags from `tpl`.
                 const instancedTemplates = this.scene.getInstancedTemplates();
+                // Cull templates ONCE per frame; the transparent instanced
+                // sub-pass below reuses this list. Frustum: the union of the
+                // occurrences' world AABBs off-screen ⇒ every occurrence is.
+                // Contribution: the LARGEST occurrence projected at the union
+                // box's nearest view depth is an upper bound for any single
+                // occurrence — bolts-scattered-everywhere templates cull as
+                // soon as no bolt can exceed the pixel threshold, even though
+                // the union box itself is model-sized. Templates with a
+                // selected occurrence are exempt so the highlight can't vanish.
+                // CATIA-class models put ~97% of draw calls in this pass, so
+                // this is where interactive frame cost lives (issue #1682).
+                let visibleInstanced = instancedTemplates;
                 if (instancedTemplates.length > 0) {
+                    const kept = [];
+                    for (const it of instancedTemplates) {
+                        if (it.bounds) {
+                            if (!FrustumUtils.isAABBVisible(frustum, it.bounds)) {
+                                frameInstancedFrustumCulled++;
+                                continue;
+                            }
+                            if (contribThresholdPx > 0 &&
+                                cullCam &&
+                                it.selectedCount === 0 &&
+                                projectedInstancedRadiusPx(it.bounds.min, it.bounds.max, it.maxOccRadius, cullCam) <
+                                    contribThresholdPx) {
+                                frameInstancedContributionCulled++;
+                                continue;
+                            }
+                        }
+                        kept.push(it);
+                    }
+                    visibleInstanced = kept;
+                }
+                if (visibleInstanced.length > 0) {
                     // Opaque instanced pass. flags.x bit 2 marks "instanced pass" so the
                     // shader routes per-instance opacity: opaque (or selected) occurrences
                     // draw here; translucent ones (lens/x-ray/compare overrides) are
@@ -1681,11 +1875,13 @@ export class Renderer {
                     pass.setPipeline(this.pipeline.getInstancedPipeline());
                     pass.setBindGroup(0, this.pipeline.getBindGroup());
                     pass.setBindGroup(1, this.pipeline.getEnvironmentBindGroup());
-                    for (const it of instancedTemplates) {
+                    for (const it of visibleInstanced) {
                         pass.setVertexBuffer(0, it.vertexBuffer);
                         pass.setVertexBuffer(1, it.instanceBuffer);
                         pass.setIndexBuffer(it.indexBuffer, 'uint32');
                         pass.drawIndexed(it.indexCount, it.instanceCount);
+                        frameDrawCalls++;
+                        frameInstancedDrawn++;
                     }
                     pass.setPipeline(this.pipeline.getPipeline());
                     // The TRANSPARENT instanced sub-pass is drawn later, alongside the
@@ -1738,6 +1934,7 @@ export class Renderer {
                         pass.setVertexBuffer(0, tm.vertexBuffer);
                         pass.setIndexBuffer(tm.indexBuffer, 'uint32');
                         pass.drawIndexed(tm.indexCount);
+                        frameDrawCalls++;
                     }
                     // Restore the opaque pipeline for the passes that follow.
                     pass.setPipeline(this.pipeline.getPipeline());
@@ -1760,7 +1957,7 @@ export class Renderer {
                             // lens/Pset colour override, so the overlay paint pass finds depth.
                             const isTransparent = shouldRouteBatchTransparent(alphaForBatch(subBatch, color[3]), subBatch.expressIds, colorOverrides);
                             if (isTransparent) {
-                                pass.setPipeline(this.pipeline.getTransparentPipeline());
+                                pass.setPipeline(pipeFor(subBatch, 'transparent'));
                             }
                             else {
                                 // Opaque (incl. material-layer slices): double-sided.
@@ -1768,7 +1965,7 @@ export class Renderer {
                                 // open watertight-skin bands with unreliable winding,
                                 // so culling punched holes (wall read hollow). See the
                                 // full-batch path above.
-                                pass.setPipeline(this.pipeline.getPipeline());
+                                pass.setPipeline(pipeFor(subBatch, 'opaque'));
                                 opaqueSubBatches.push(subBatch);
                             }
                             // Render the sub-batch as a single draw call
@@ -1794,6 +1991,7 @@ export class Renderer {
                     // bit 1 = overlay; bit 5 (32) = emphasize (pop) — see shader.
                     tplFlags[0] = options.emphasizeOverrides ? (2 | 32) : 2;
                     for (const batch of overrideBatches) {
+                        pass.setPipeline(pipeFor(batch, 'overlay'));
                         renderBatch(batch);
                     }
                     tplFlags[0] = 0; // restore for any downstream use of the template
@@ -1858,20 +2056,20 @@ export class Renderer {
                 // a complete depth buffer. Only runs when an override actually made some
                 // occurrence translucent (otherwise zero cost). flags.x bit 3 flips the
                 // shader's opacity routing so only translucent occurrences draw here.
-                const instancedTransparent = this.scene.getInstancedTemplates();
                 const instancedTransparentPipeline = this.pipeline.getInstancedTransparentPipeline();
-                if (instancedTransparent.length > 0 &&
+                if (visibleInstanced.length > 0 &&
                     this.scene.hasTransparentInstances() &&
                     instancedTransparentPipeline !== null) {
                     this.pipeline.writeRawUniforms(tpl, 0x4 | 0x8);
                     pass.setPipeline(instancedTransparentPipeline);
                     pass.setBindGroup(0, this.pipeline.getBindGroup());
                     pass.setBindGroup(1, this.pipeline.getEnvironmentBindGroup());
-                    for (const it of instancedTransparent) {
+                    for (const it of visibleInstanced) {
                         pass.setVertexBuffer(0, it.vertexBuffer);
                         pass.setVertexBuffer(1, it.instanceBuffer);
                         pass.setIndexBuffer(it.indexBuffer, 'uint32');
                         pass.drawIndexed(it.indexCount, it.instanceCount);
+                        frameDrawCalls++;
                     }
                     pass.setPipeline(this.pipeline.getPipeline());
                 }
@@ -1879,6 +2077,7 @@ export class Renderer {
                 if (transparentBatches.length > 0) {
                     pass.setPipeline(this.pipeline.getTransparentPipeline());
                     for (const batch of transparentBatches) {
+                        pass.setPipeline(pipeFor(batch, 'transparent'));
                         renderBatch(batch);
                     }
                 }
@@ -1923,6 +2122,7 @@ export class Renderer {
                         pass.setVertexBuffer(0, mesh.vertexBuffer);
                         pass.setIndexBuffer(mesh.indexBuffer, 'uint32');
                         pass.drawIndexed(mesh.indexCount, 1, 0, 0, 0);
+                        frameDrawCalls++;
                     }
                 }
                 // Ensure selected meshes have uniform buffers and bind groups
@@ -1983,6 +2183,7 @@ export class Renderer {
                     pass.setVertexBuffer(0, mesh.vertexBuffer);
                     pass.setIndexBuffer(mesh.indexBuffer, 'uint32');
                     pass.drawIndexed(mesh.indexCount, 1, 0, 0, 0);
+                    frameDrawCalls++;
                 }
             }
             else {
@@ -1998,6 +2199,7 @@ export class Renderer {
                     pass.setVertexBuffer(0, mesh.vertexBuffer);
                     pass.setIndexBuffer(mesh.indexBuffer, 'uint32');
                     pass.drawIndexed(mesh.indexCount, 1, 0, 0, 0);
+                    frameDrawCalls++;
                 }
                 // Render transparent meshes with transparent pipeline (alpha blending)
                 if (transparentMeshes.length > 0) {
@@ -2012,6 +2214,7 @@ export class Renderer {
                         pass.setVertexBuffer(0, mesh.vertexBuffer);
                         pass.setIndexBuffer(mesh.indexBuffer, 'uint32');
                         pass.drawIndexed(mesh.indexCount, 1, 0, 0, 0);
+                        frameDrawCalls++;
                     }
                 }
             }
@@ -2184,6 +2387,22 @@ export class Renderer {
                 });
             }
             device.queue.submit([encoder.finish()]);
+            this._lastFrameStats = {
+                drawCalls: frameDrawCalls,
+                batchesDrawn: frameBatchesDrawn,
+                batchesFrustumCulled: frameBatchesFrustumCulled,
+                batchesContributionCulled: frameBatchesContributionCulled,
+                batchesNotResident: frameBatchesNotResident,
+                batchesAtLod1: frameBatchesAtLod1,
+                instancedDrawn: frameInstancedDrawn,
+                instancedFrustumCulled: frameInstancedFrustumCulled,
+                instancedContributionCulled: frameInstancedContributionCulled,
+                timestamp: performance.now(),
+            };
+            // GPU residency budget (issue #1682 phase 3a): evict least-recently
+            // drawn bucket batches after submit — destruction of just-submitted
+            // buffers is deferred past in-flight work by WebGPU.
+            this.scene.enforceGpuBudget();
             // Pop validation error scope and capture the exact error
             if (captureGpuError) {
                 device.popErrorScope().then((error) => {