@ifc-lite/renderer 6.0.1 → 6.3.0

package/dist/index.js

@@ -11,7 +11,7 @@ export { appearanceSourceTriangle, expandAppearanceCorners, equivalentAppearance
 export { sameCompanionParts } from './appearance-companions.js';
 export { invertAppearancePartition, validateAppearancePartition } from './appearance-preview.js';
 import { createReferenceImageManager } from './reference-image-host.js';
-import { measureDrawingBuffer, resizeRendererViewport } from './renderer-viewport.js';
+import { MAX_DRAWING_BUFFER_PIXEL_RATIO, measureDrawingBuffer, resizeRendererViewport } from './renderer-viewport.js';
 export { pickFitPolicy } from './camera-fit-policy.js';
 // `Scene` is NOT exported: an exported class republishes every method `SceneContents` above just froze.
 export { Picker } from './picker.js';
@@ -59,11 +59,6 @@ export { isEntityVisible } from './entity-visibility.js';
 // through its own glTF pipeline rather than this one (#2591).
 export { DEFAULT_GHOST_ALPHA, OPAQUE_ALPHA_CUTOFF } from './overlay-routing.js';
 export { VisibilityEpochTracker } from './visibility-epoch.js';
-// Frame/pass GPU timing (issue #2670 perf-verdict gate). Opt-in and NOT wired
-// into `Renderer` by default — a caller constructs `GpuFrameTimingRecorder`
-// itself and attaches its `timestampWrites` to the passes it wants measured;
-// see `frame-timing-gpu.ts`'s module doc for the usage pattern, and
-// `decideTimingMode` for choosing GPU queries vs. the CPU fallback vs. off.
 export { decideTimingMode, passDurationsMs, frameTotalMs, aggregateFrameTimings } from './frame-timing.js';
 export { computeDurationStats, nsToMs, isNegativeDelta } from './frame-timing-stats.js';
 export { GpuFrameTimingRecorder, hasTimestampQueryFeature } from './frame-timing-gpu.js';
@@ -74,6 +69,7 @@ export { PointPicker, decodePickSample } from './point-picker.js';
 export { PointCloudRenderer } from './pointcloud/point-cloud-renderer.js';
 export { PointRenderPipeline } from './pointcloud/point-pipeline.js';
 import { modelPlacementBounds, sceneMeshBounds } from './model-placement-bounds.js';
+import { configureRendererGpuTiming, readRendererGpuTiming, releaseRendererGpuTiming, beginRendererGpuTiming, renderPassTimestampWrites, submitRendererGpuTiming } from './renderer-frame-timing.js';
 import { WebGPUDevice } from './device.js';
 import { RenderPipeline } from './pipeline.js';
 import { Camera } from './camera.js';
@@ -117,8 +113,9 @@ import { XRayAlpha, XRayEpochTracker } from './xray-alpha.js';
 import { PartialBatchRequests } from './partial-batch-requests.js';
 import { uploadIndividualMesh } from './individual-mesh-upload.js';
 import { PointCloudRenderer } from './pointcloud/point-cloud-renderer.js';
-import { appendPointCloudChunk as appendPointCloudChunkImpl, beginPointCloudStream as beginPointCloudStreamImpl, endPointCloudStream as endPointCloudStreamImpl, removePointCloudAsset as removePointCloudAssetImpl, } from './pointcloud/point-cloud-stream-lifecycle.js';
+import { appendPointCloudChunk as appendPointCloudChunkImpl, beginPointCloudStream as beginPointCloudStreamImpl, endPointCloudStream as endPointCloudStreamImpl, removePointCloudAsset as removePointCloudAssetImpl, removePointCloudChunk as removePointCloudChunkImpl, } from './pointcloud/point-cloud-stream-lifecycle.js';
 import { DeviationComputer } from './deviation/deviation-computer.js';
+export { computeDeviationStatistics, computeDeviationStatisticsAsync, countWithinToleranceAsync, deviationHistogramAsync, summarizeDeviationAssetsAsync } from './deviation/deviation-statistics.js';
 import { runGuardedGpuUpload, isDeviceLossThrow } from './gpu-upload-guard.js';
 import { recoverRendererDevice, rendererDeviceLostError } from './device-recovery.js';
 /**
@@ -172,6 +169,7 @@ export class Renderer {
     hoverMeshes = new HoverMeshCache();
     /** Device px per CSS px in the drawing buffer; CSS-px sizes scale by it (#5383). */
     pixelRatio = 1;
+    maxPixelRatio = MAX_DRAWING_BUFFER_PIXEL_RATIO;
     interactionEffects = new InteractionEffectsGovernor();
     // Procedural sky background — created lazily on the first frame that
     // enables it (most sessions never do).
@@ -510,7 +508,7 @@ export class Renderer {
         // are clamped to the GPU's max 2D texture dimension so the initial
         // pipeline allocations can't overflow on tall/wide layouts.
         const maxDim = this.device.getMaxTextureDimension();
-        const measured = measureDrawingBuffer(this.canvas, maxDim);
+        const measured = measureDrawingBuffer(this.canvas, maxDim, this.maxPixelRatio);
         this.pixelRatio = measured?.pixelRatio ?? 1;
         const width = Math.max(1, Math.min(measured?.width ?? this.canvas.width, maxDim));
         const height = Math.max(1, Math.min(measured?.height ?? this.canvas.height, maxDim));
@@ -718,14 +716,14 @@ export class Renderer {
         this.deviceLossSequence++;
         this.deviceLost = true;
         cancelRendererColorFrame(this);
+        releaseRendererGpuTiming(this);
         this.recovery.lostReferenceImages = this.referenceImages.hasImages();
         this.referenceImages.destroy();
         this.deviceLostGeneration = this.initGeneration;
         this.deviceLostInfo = info;
         console.warn('[Renderer] GPU device lost — halting rendering until re-init:', info.message);
-        // Readiness describes the GPU objects, and every one of them just died:
-        // `isReady()` reports it from here on, and anyone parked in
-        // `whenReady()` is failed rather than left to be resolved by the init
+        // Readiness describes dead GPU objects: `isReady()` reports the loss
+        // and `whenReady()` waiters fail rather than awaiting the init
         // this loss may have landed in the middle of. Done BEFORE the listeners
         // run, so a listener that recovers by calling `init()` synchronously
         // finds the waiters already settled and re-arms the wait for the next
@@ -894,8 +892,13 @@ export class Renderer {
     beginPointCloudStream(meta) {
         return beginPointCloudStreamImpl(this, meta);
     }
-    appendPointCloudChunk(handle, chunk) {
-        appendPointCloudChunkImpl(this, handle, chunk);
+    /** `key` makes the chunk removable on its own via `removePointCloudChunk` (one COPC node, #6869). */
+    appendPointCloudChunk(handle, chunk, key) {
+        appendPointCloudChunkImpl(this, handle, chunk, key);
+    }
+    /** Free the chunks appended under `key`; returns the points removed (0 for a stale handle). */
+    removePointCloudChunk(handle, key) {
+        return removePointCloudChunkImpl(this, handle, key);
     }
     endPointCloudStream(handle) {
         endPointCloudStreamImpl(this, handle);
@@ -904,14 +907,13 @@ export class Renderer {
         removePointCloudAssetImpl(this, handle);
     }
     /**
-     * Reassign a streamed point-cloud's expressId after upload. Use
-     * this when the federation registry assigns a new model offset and
-     * the renderer needs to emit the post-offset globalId in picking
-     * outputs. The change takes effect on the next render — no GPU
-     * buffer rewrite needed.
+     * Bind a streamed point cloud to its federation identity after upload:
+     * the post-offset globalId picking and deviation readback report, and,
+     * when given, the model index they attribute the asset to (#6887). Takes
+     * effect on the next render — no GPU buffer rewrite needed.
      */
-    relabelPointCloudAsset(handle, newExpressId) {
-        this.pointCloudRenderer?.relabelAsset(handle, newExpressId);
+    relabelPointCloudAsset(handle, newExpressId, modelIndex) {
+        this.pointCloudRenderer?.relabelAsset(handle, newExpressId, modelIndex);
         this.requestRender();
     }
     /** Bounds across flat draw batches. */
@@ -964,6 +966,10 @@ export class Renderer {
     getPointCloudTransform(handle) {
         return this.pointCloudRenderer?.getAssetTransform(handle);
     }
+    /** Exact float64 placement copy for CPU math; the f32 transform rounds map-grid origins (#6894). */
+    getPointCloudPlacement(handle) {
+        return this.pointCloudRenderer?.getAssetPlacement(handle);
+    }
     /**
      * Set/clear a streamed cloud's column-major model matrix (16 floats) for
      * IfcMapConversion alignment (#1804). Applied on the next frame's uniform
@@ -981,22 +987,17 @@ export class Renderer {
      * `deviation/deviation-computer.ts` for the full contract.
      */
     async computeDeviations(opts = {}) {
-        return this.deviationComputer.compute(opts, {
-            device: this.device,
-            scene: this.scene,
-            pointCloudRenderer: this.pointCloudRenderer,
-            requestRender: () => this.requestRender(),
-        });
+        return this.deviationComputer.compute(opts, this.deviationContext());
     }
     /** Read per-scan-asset signed-distance statistics after a completed run. */
     async readDeviationAssetStats() {
-        return this.deviationComputer.readAssetStats({
-            device: this.device,
-            scene: this.scene,
-            pointCloudRenderer: this.pointCloudRenderer,
-            requestRender: () => this.requestRender(),
-        });
+        return this.deviationComputer.readAssetStats(this.deviationContext());
+    }
+    /** Read every computed point's signed distance (4 B/point) for summary statistics (#6872). */
+    async readDeviationDistances() {
+        return this.deviationComputer.readDistances(this.deviationContext());
     }
+    deviationContext = () => ({ device: this.device, scene: this.scene, pointCloudRenderer: this.pointCloudRenderer, requestRender: () => this.requestRender() });
     /**
      * Toggle Eye-Dome Lighting and tune its strength.
      *
@@ -1271,9 +1272,6 @@ export class Renderer {
             }
         });
     }
-    /**
-     * Render frame
-     */
     /** Get diagnostic info for mobile debugging */
     getDiagnostics() {
         const pos = this.camera.getPosition();
@@ -1294,15 +1292,15 @@ 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',
         };
     }
+    setGpuFrameTiming(enabled) { configureRendererGpuTiming(this, enabled); }
+    getGpuFrameTiming() { return readRendererGpuTiming(this); }
     /**
      * 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;
-    }
+    getFrameStats() { return this._lastFrameStats; }
     /**
      * Vendor/architecture identity of the GPU adapter, snapshotted during
      * `init()` (issue #2624 device-loss telemetry), or null when the runtime
@@ -1327,8 +1325,10 @@ export class Renderer {
             this.scene.setQuantizedBatches(true);
         return ok;
     }
+    /** Draw a frame through the shared submission path, preserving the void API. */
+    render(options = {}) { this.renderWithResult(options); }
     /**
-     * Draw one frame.
+     * Draw one frame; true only when it submits without a contained synchronous failure (#6709).
      *
      * Never throws, so callers never need to guard this call to keep their
      * animation loop alive.
@@ -1347,26 +1347,22 @@ export class Renderer {
      *    carries on. Once enough such frames have degraded without recovering,
      *    `onPersistentRenderDegradation` fires once.
      *
-     * SCOPE: `renderFrame()` has two try/catch regions — this outer one (canvas
-     * resize, context setup, evicted-batch restore) and an inner one opened
-     * after the swap-chain texture is acquired, covering encoder work through
-     * `submit`. Until #2417 only the outer one discriminated, so a device that
-     * died after `getCurrentTexture()` succeeded degraded quietly forever with
-     * no latch and no toast. Both now run the same policy; the encode catch
-     * additionally balances the frame's validation error scope before doing so.
-     */
-    render(options = {}) {
+     * Frame setup and encoding through `submit` share `containFrameThrow`
+     * (#2417); the encode catch also balances the validation error scope.
+     * Submission is synchronous, distinct from GPU completion/validation.
+     */
+    renderWithResult(options = {}) {
         this._renderCallCount++;
         // A lost device leaves every pipeline/buffer dead; rendering would only
         // emit a stream of validation errors. Stay quiet until re-init.
         if (this.deviceLost) {
             this._renderSkipCount++;
             cancelRendererColorFrame(this);
-            return;
+            return false;
         }
         try {
             this.frameContainedThrow = false;
-            this.renderFrame(options);
+            const submitted = this.renderFrame(options);
             // Only a frame that actually got through resets the run. A frame
             // the ENCODE catch contained returns here normally (that catch is
             // inside renderFrame), so "did not throw" is not the same question
@@ -1374,6 +1370,7 @@ export class Renderer {
             if (!this.frameContainedThrow)
                 this.consecutiveDegradedFrames = 0;
             retryRendererColorFrame(this, () => this.requestRender());
+            return submitted;
         }
         catch (error) {
             // Safari (26.5) reports device loss SYNCHRONOUSLY: a call against a
@@ -1390,24 +1387,25 @@ export class Renderer {
             this._renderSkipCount++;
             this.containFrameThrow(error, 'frame');
             cancelRendererColorFrame(this);
+            return false;
         }
     }
     /**
-     * The frame body. Throws on a synchronously-dead GPU device; `render()`
-     * owns the containment. Private for that reason — call `render()`.
+     * The frame body. Throws on a synchronously-dead GPU device;
+     * `renderWithResult()` owns containment for both public render methods.
      */
     renderFrame(options) {
         if (!this.device.isInitialized() || !this.pipeline) {
             this._renderSkipCount++;
-            return;
+            return false;
         }
         // Drawing buffer = the element's device-pixel size (capped ratio, clamped
         // to the GPU's max texture dimension); see computeDrawingBufferSize (#5383).
-        const measured = measureDrawingBuffer(this.canvas, this.device.getMaxTextureDimension());
+        const measured = measureDrawingBuffer(this.canvas, this.device.getMaxTextureDimension(), this.maxPixelRatio, options.maxPixelRatio);
         // Skip rendering while the canvas is collapsed or too small.
         if (!measured || measured.height < 10) {
             this._renderSkipCount++;
-            return;
+            return false;
         }
         const { width, height } = measured;
         this.pixelRatio = measured.pixelRatio;
@@ -1425,12 +1423,12 @@ export class Renderer {
         // Skip rendering if canvas is invalid
         if (this.canvas.width === 0 || this.canvas.height === 0) {
             this._renderSkipCount++;
-            return;
+            return false;
         }
         // Ensure context is valid before rendering (handles HMR, focus changes, etc.)
         if (!this.device.ensureContext()) {
             this._renderSkipCount++;
-            return; // Skip this frame, context will be ready next frame
+            return false; // Skip this frame, context will be ready next frame
         }
         const device = this.device.getDevice();
         const viewProj = this.camera.getViewProjMatrix().m;
@@ -1619,7 +1617,7 @@ export class Renderer {
                 errorScopePushed = false;
                 this.drainErrorScope(device);
             }
-            return; // Skip this frame, context will be reconfigured next frame
+            return false; // Skip this frame, context will be reconfigured next frame
         }
         let colorCapture = null;
         let colorReadback = null;
@@ -1762,6 +1760,7 @@ export class Renderer {
             }
             // Now record draw commands
             const encoder = device.createCommandEncoder();
+            beginRendererGpuTiming(this, device, encoder);
             // Sun shadow-map pass (#2670, Phase 2). Off unless the caller opts
             // in; when off the hot path pays only this check and (once) an
             // enabled=0 reset on toggle-off. Runs BEFORE the colour pass (its
@@ -1927,6 +1926,7 @@ export class Renderer {
                 storeOp: (needsObjectIdPass ? 'store' : 'discard'),
             });
             const pass = encoder.beginRenderPass({
+                timestampWrites: renderPassTimestampWrites(encoder, 'main'),
                 colorAttachments,
                 depthStencilAttachment: {
                     view: this.pipeline.getDepthTextureView(),
@@ -2306,6 +2306,10 @@ export class Renderer {
                 // probe (enableQuantizedBatches) verified they exist, so the
                 // base fallback here is type-safety, never taken.
                 const pipeFor = (batch, kind) => {
+                    const ghost = kind === 'transparent' && xray.isGhostBatch(batch)
+                        ? this.pipeline.getGhostPipeline(!!batch.quantized, () => this.requestRender()) : null;
+                    if (ghost)
+                        return ghost;
                     const base = kind === 'opaque' ? this.pipeline.getPipeline() : this.pipeline.getTransparentPipeline();
                     if (!batch.quantized)
                         return base;
@@ -2800,6 +2804,7 @@ export class Renderer {
                 height: this.canvas.height,
                 // Depth-only: depth24plus-stencil8 cannot be sampled as texture_depth_* with aspect 'all'.
                 depthView: this.pipeline.getDepthOnlyTextureView(),
+                maskDepthView: this.pipeline.getDepthTextureView(),
                 objectIdView,
                 projection: this.camera.getProjMatrix(),
                 enhancement: visualEnhancement,
@@ -2810,7 +2815,7 @@ export class Renderer {
                 selectionOutline,
             });
             colorReadback = colorCapture && encodeRendererColorFrameCapture(device, encoder, colorCapture);
-            device.queue.submit([encoder.finish()]);
+            submitRendererGpuTiming(this, device, encoder);
             if (colorReadback && colorCapture) {
                 settleRendererColorFrameCapture(this, colorCapture, colorReadback);
                 colorCapture = null;
@@ -2837,8 +2842,10 @@ export class Renderer {
                 errorScopePushed = false;
                 this.drainErrorScope(device);
             }
+            return true;
         }
         catch (error) {
+            releaseRendererGpuTiming(this);
             discardRendererColorFrameReadback(colorReadback);
             // Balance the validation scope if we threw before popping it above —
             // an unpopped scope would capture every later frame's errors silently.
@@ -2875,6 +2882,7 @@ export class Renderer {
             // the discriminator keys on the TYPE and not on "a frame threw".
             this.containFrameThrow(error, 'encode');
             cancelRendererColorFrame(this);
+            return false;
         }
     }
     /**
@@ -3007,6 +3015,8 @@ export class Renderer {
     resize(width, height) {
         resizeRendererViewport(this.canvas, this.camera, width, height);
     }
+    /** Cap the drawing buffer's device-pixel ratio, trading sharpness for fill on HiDPI screens; see computeDrawingBufferSize. */
+    setMaxPixelRatio(ratio) { this.maxPixelRatio = ratio; this.requestRender(); }
     /** Stage one new owner; borrowed mesh buffers must remain immutable until disposal. */
     prepareAuthoredOwner(parts) {
         if (this.deviceLost || !this.device.isInitialized() || !this.pipeline)
@@ -3286,6 +3296,7 @@ export class Renderer {
             // Re-arm the section-bounds diagnostic log for the next model.
             this._loggedSectionBounds = false;
         }
+        releaseRendererGpuTiming(this);
         // Render pipelines (textures + uniform buffers)
         this.pipeline?.destroy();
         this.pipeline = null;