@xeokit/xeokit-sdk 2.1.0 → 2.2.0

package/dist/xeokit-sdk.cjs.js

@@ -39371,36 +39371,42 @@ class DistanceMeasurementsPlugin extends Plugin {
 }
 
 /**
- * {@link Viewer} plugin that improves interactivity by temporarily switching to fast and simple rendering while the
- * {@link Camera} is moving or the {@link Canvas} is resizing.
+ * {@link Viewer} plugin that makes interaction smoother with large models, by temporarily switching
+ * the Viewer to faster, lower-quality rendering modes whenever we interact.
  *
  * [<img src="https://xeokit.io/img/docs/FastNavPlugin/FastNavPlugin.gif">](https://xeokit.github.io/xeokit-sdk/examples/#performance_FastNavPlugin)
  *
- * FastNavPlugin works by disabling specified rendering features, and optionally down-scaling the canvas, whenever we
- * move the Camera or resize the Canvas. Then, once the Camera or Canvas has been at rest after a certain time, FastNavPlugin
- * restores those rendering features and original canvas scale again.
+ * FastNavPlugin works by hiding specified Viewer rendering features, and optionally scaling the Viewer's canvas
+ * resolution, whenever we interact with the Viewer. Then, once we've finished interacting, FastNavPlugin restores those
+ * rendering features and the original canvas scale, after a configured delay.
  *
- * The effect we experience is a low-quality view while moving, then a high-quality view
- * after we stop, following an optional delay.
+ * Depending on how we configure FastNavPlugin, we essentially switch to a smooth-rendering low-quality view while
+ * interacting, then return to the normal higher-quality view after we stop, following an optional delay.
  *
- * Down-scaling the canvas resolution gives particularly good results. For example, scaling by ````0.5````
- * means that we're rendering a quarter of the pixels while moving, which makes the Viewer noticeably smoother
- * with big models.
+ * Down-scaling the canvas resolution gives particularly good results. For example, scaling by ````0.5```` means that
+ * we're rendering a quarter of the pixels while interacting, which can make the Viewer noticeably smoother with big models.
+ *
+ * The screen capture above shows FastNavPlugin in action. In this example, whenever we move the Camera or resize the Canvas,
+ * FastNavPlugin switches off enhanced edges and ambient shadows (SAO), and down-scales the canvas, making it slightly
+ * blurry. When ````0.5```` seconds passes with no interaction, the plugin shows edges and SAO again, and restores the
+ * original canvas scale.
  *
  * # Usage
  *
  * In the example below, we'll create a {@link Viewer}, add a {@link FastNavPlugin}, then use an {@link XKTLoaderPlugin} to load a model.
  *
- * Whenever our Camera moves, the FastNavPlugin will:
+ * Whenever we interact with the Viewer, our FastNavPlugin will:
  *
- * * disable edges,
- * * disable ambient shadows,
- * * disable physically-based materials (switching to non-PBR),
+ * * hide edges,
+ * * hide ambient shadows (SAO),
+ * * hide physically-based materials (switching to non-PBR),
  * * hide transparent objects, and
- * * down-scale the canvas by 0.5, causing 75% less pixels to render.
+ * * scale the canvas resolution by 0.5, causing the GPU to render 75% less pixels.
+ *
  * <br><br>
- * We'll also configure a 0.5 second delay before we transition back to high-quality each time we stop moving, so that we're
- * not continually flipping between low and high quality as we interact.
+ * We'll also configure a 0.5 second delay before we transition back to high-quality each time we stop ineracting, so that we're
+ * not continually flipping between low and high quality as we interact. Since we're only rendering ambient shadows when not interacting, we'll also treat ourselves
+ * to expensive, high-quality SAO settings, that we wouldn't normally configure for an interactive SAO effect.
  *
  * * [[Run this example](https://xeokit.github.io/xeokit-sdk/examples/#performance_FastNavPlugin)]
  *
@@ -39420,17 +39426,23 @@ class DistanceMeasurementsPlugin extends Plugin {
  * viewer.scene.camera.look = [42.45, 49.62, -43.59];
  * viewer.scene.camera.up = [0.05, 0.95, 0.15];
  *
+ * // Higher-quality SAO settings
+ *
+ * viewer.scene.sao.enabled = true;
+ * viewer.scene.sao.numSamples = 60;
+ * viewer.scene.sao.kernelRadius = 170;
+ *
  * // Install a FastNavPlugin
  *
  * new FastNavPlugin(viewer, {
- *      dynamicEdges: false,                // Don't show edges while moving (default is false)
- *      dynamicSAO: false,                  // Don't show ambient shadows while moving (default is false)
- *      dynamicPBR: false,                  // Non-physically-based rendering while moving (default is false)
- *      dynamicTransparent: false,          // Hide transparent objects while moving (default is false)
- *      dynamicCanvasResolution: true,      // Reduce canvas resolution while moving (default is false)
- *      dynamicCanvasResolutionScale: 0.5,  // Factor by which we reduce canvas resolution when moving (default is 0.6)
- *      delayBeforeStatic: true,            // When we stop, delay before returning to quality static render (default is true)
- *      delayBeforeStaticDuration: 0.5      // The delay duration, in seconds (default is 0.5)
+ *      hideEdges: true,                // Don't show edges while we interact (default is true)
+ *      hideSAO: true,                  // Don't show ambient shadows while we interact (default is true)
+ *      hidePBR: true,                  // No physically-based rendering while we interact (default is true)
+ *      hideTransparentObjects: true,   // Hide transparent objects while we interact (default is false)
+ *      scaleCanvasResolution: true,    // Scale canvas resolution while we interact (default is false)
+ *      scaleCanvasResolutionFactor: 0.5,  // Factor by which we scale canvas resolution when we interact (default is 0.6)
+ *      delayBeforeRestore: true,       // When we stop interacting, delay before restoring normal render (default is true)
+ *      delayBeforeRestoreSeconds: 0.5  // The delay duration, in seconds (default is 0.5)
  * });
  *
  * // Load a BIM model from XKT
@@ -39454,40 +39466,40 @@ class FastNavPlugin extends Plugin {
      * @param {Viewer} viewer The Viewer.
      * @param {Object} cfg FastNavPlugin configuration.
      * @param {String} [cfg.id="FastNav"] Optional ID for this plugin, so that we can find it within {@link Viewer#plugins}.
-     * @param {Boolean} [cfg.dynamicPBR=false] Whether to enable physically-based rendering (PBR) while the camera is moving.
-     * @param {Boolean} [cfg.dynamicSAO=false] Whether to enable scalable ambient occlusion (SAO) while the camera is moving.
-     * @param {Boolean} [cfg.dynamicEdges=false] Whether to enable enhanced edges while the camera is moving.
-     * @param {Boolean} [cfg.dynamicTransparent=true] Whether to show transparent objects when the camera is moving.
-     * @param {Number} [cfg.dynamicCanvasResolution=false] Whether to down-scale the canvas resolution while the camera is moving.
-     * @param {Number} [cfg.dynamicCanvasResolutionScale=0.6] The factor by which we downscale the canvas resolution while the camera is moving.
-     * @param {Boolean} [cfg.delayBeforeStatic=true] Once the camera stops moving, whether to have a delay before transitioning back to normal rendering.
-     * @param {Number} [cfg.delayBeforeStaticDuration=0.5] Delay in seconds before transitioning back to normal rendering when camera stops moving. Only works when ````delayBeforeStatic```` is ````true````.
+     * @param {Boolean} [cfg.hidePBR=true] Whether to temporarily hide physically-based rendering (PBR) whenever we interact with the Viewer.
+     * @param {Boolean} [cfg.hideSAO=true] Whether to temporarily hide scalable ambient occlusion (SAO) whenever we interact with the Viewer.
+     * @param {Boolean} [cfg.hideEdges=true] Whether to temporarily hide edges whenever we interact with the Viewer.
+     * @param {Boolean} [cfg.hideTransparentObjects=false] Whether to temporarily hide transparent objects whenever we interact with the Viewer.
+     * @param {Number} [cfg.scaleCanvasResolution=false] Whether to temporarily down-scale the canvas resolution whenever we interact with the Viewer.
+     * @param {Number} [cfg.scaleCanvasResolutionFactor=0.6] The factor by which we downscale the canvas resolution whenever we interact with the Viewer.
+     * @param {Boolean} [cfg.delayBeforeRestore=true] Whether to temporarily have a delay before restoring normal rendering after we stop interacting with the Viewer.
+     * @param {Number} [cfg.delayBeforeRestoreSeconds=0.5] Delay in seconds before restoring normal rendering after we stop interacting with the Viewer.
      */
     constructor(viewer, cfg = {}) {
 
         super("FastNav", viewer);
 
-        this._dynamicPBR = !!cfg.dynamicPBR;
-        this._dynamicSAO = !!cfg.dynamicSAO;
-        this._dynamicEdges = !!cfg.dynamicEdges;
-        this._dynamicTransparent = (cfg.dynamicTransparent !== false);
-        this._dynamicCanvasResolution = !!cfg.dynamicCanvasResolution;
-        this._dynamicCanvasResolutionScale = cfg.dynamicCanvasResolutionScale || 0.6;
-        this._delayBeforeStatic = (cfg.delayBeforeStatic !== false);
-        this._delayBeforeStaticDuration = cfg.delayBeforeStaticDuration || 0.5;
+        this._hidePBR = cfg.hidePBR !== false;
+        this._hideSAO = cfg.hideSAO !== false;
+        this._hideEdges = cfg.hideEdges !== false;
+        this._hideTransparentObjects = !!cfg.hideTransparentObjects;
+        this._scaleCanvasResolution = !!cfg.scaleCanvasResolution;
+        this._scaleCanvasResolutionFactor = cfg.scaleCanvasResolutionFactor || 0.6;
+        this._delayBeforeRestore = (cfg.delayBeforeRestore !== false);
+        this._delayBeforeRestoreSeconds = cfg.delayBeforeRestoreSeconds || 0.5;
 
-        let timer = this._delayBeforeStaticDuration * 1000;
+        let timer = this._delayBeforeRestoreSeconds * 1000;
         let fastMode = false;
 
         const switchToLowQuality = () => {
-            timer = (this._delayBeforeStaticDuration * 1000);
+            timer = (this._delayBeforeRestoreSeconds * 1000);
             if (!fastMode) {
-                viewer.scene._renderer.setPBREnabled(this._dynamicPBR);
-                viewer.scene._renderer.setSAOEnabled(this._dynamicSAO);
-                viewer.scene._renderer.setTransparentEnabled(this._dynamicTransparent);
-                viewer.scene._renderer.setEdgesEnabled(this._dynamicEdges);
-                if (this._dynamicCanvasResolution) {
-                    viewer.scene.canvas.resolutionScale = this._dynamicCanvasResolutionScale;
+                viewer.scene._renderer.setPBREnabled(!this._hidePBR);
+                viewer.scene._renderer.setSAOEnabled(!this._hideSAO);
+                viewer.scene._renderer.setTransparentEnabled(!this._hideTransparentObjects);
+                viewer.scene._renderer.setEdgesEnabled(!this._hideEdges);
+                if (this._scaleCanvasResolution) {
+                    viewer.scene.canvas.resolutionScale = this._scaleCanvasResolutionFactor;
                 } else {
                     viewer.scene.canvas.resolutionScale = 1;
                 }
@@ -39512,7 +39524,7 @@ class FastNavPlugin extends Plugin {
                 return;
             }
             timer -= tickEvent.deltaTime;
-            if ((!this._delayBeforeStatic) || timer <= 0) {
+            if ((!this._delayBeforeRestore) || timer <= 0) {
                 switchToHighQuality();
             }
         });
@@ -39536,199 +39548,201 @@ class FastNavPlugin extends Plugin {
     }
 
     /**
-     * Gets whether to enable physically-based rendering (PBR) while the camera is moving.
+     * Gets whether to temporarily hide physically-based rendering (PBR) whenever we interact with the Viewer.
      *
-     * Default is ````false````.
+     * Default is ````true````.
      *
-     * @return {Boolean} Whether PBR will be enabled while the camera is moving.
+     * @return {Boolean} ````true```` if hiding PBR.
      */
-    get dynamicPBR() {
-        return this._dynamicPBR;
+    get hidePBR() {
+        return this._hidePBR;
     }
 
     /**
-     * Sets whether to enable physically-based rendering (PBR) while the camera is moving.
+     * Sets whether to temporarily hide physically-based rendering (PBR) whenever we interact with the Viewer.
      *
-     * Default is ````false````.
+     * Default is ````true````.
      *
-     * @param {Boolean} dynamicPBR Whether PBR will be enabled while the camera is moving.
+     * @param {Boolean} hidePBR ````true```` to hide PBR.
      */
-    set dynamicPBR(dynamicPBR) {
-        this._dynamicPBR = dynamicPBR;
+    set hidePBR(hidePBR) {
+        this._hidePBR = hidePBR;
     }
 
     /**
-     * Gets whether to enable Scalable Ambient Obscurrance (SAO) while the camera is moving.
+     * Gets whether to temporarily hide scalable ambient shadows (SAO) whenever we interact with the Viewer.
      *
-     * Default is ````false````.
+     * Default is ````true````.
      *
-     * @return {Boolean} Whether SAO will be enabled.
+     * @return {Boolean} ````true```` if hiding SAO.
      */
-    get dynamicSAO() {
-        return this._dynamicSAO;
+    get hideSAO() {
+        return this._hideSAO;
     }
 
     /**
-     * Sets whether to enable Scalable Ambient Obscurrance (SAO) while the camera is moving.
+     * Sets whether to temporarily hide scalable ambient shadows (SAO) whenever we interact with the Viewer.
      *
-     * Default is ````false````.
+     * Default is ````true````.
      *
-     * @param {Boolean} dynamicSAO Whether SAO will be enabled while the camera is moving.
+     * @param {Boolean} hideSAO ````true```` to hide SAO.
      */
-    set dynamicSAO(dynamicSAO) {
-        this._dynamicSAO = dynamicSAO;
+    set hideSAO(hideSAO) {
+        this._hideSAO = hideSAO;
     }
 
     /**
-     * Gets whether to enable enhanced edges while the camera is moving.
+     * Gets whether to temporarily hide edges whenever we interact with the Viewer.
      *
-     * Default is ````false````.
+     * Default is ````true````.
      *
-     * @return {Boolean} Whether edges will be enabled while the camera is moving.
+     * @return {Boolean}  ````true```` if hiding edges.
      */
-    get dynamicEdges() {
-        return this._dynamicEdges;
+    get hideEdges() {
+        return this._hideEdges;
     }
 
     /**
-     * Sets whether to enable enhanced edges while the camera is moving.
+     * Sets whether to temporarily hide edges whenever we interact with the Viewer.
      *
-     * Default is ````false````.
+     * Default is ````true````.
      *
-     * @param {Boolean} dynamicEdges Whether edge enhancement will be enabled while the camera is moving.
+     * @param {Boolean} hideEdges ````true```` to hide edges.
      */
-    set dynamicEdges(dynamicEdges) {
-        this._dynamicEdges = dynamicEdges;
+    set hideEdges(hideEdges) {
+        this._hideEdges = hideEdges;
     }
 
     /**
-     * Gets whether to show transparent objects while the camera is moving.
+     * Gets whether to temporarily hide transparent objects whenever we interact with the Viewer.
      *
-     * Default is ````true````.
+     * Does not hide X-rayed, selected, highlighted objects.
+     *
+     * Default is ````false````.
      *
-     * @return {Boolean} Whether to show transparent objects while the camera is moving.
+     * @return {Boolean} ````true```` if hiding transparent objects.
      */
-    get dynamicTransparent() {
-        return this._dynamicTransparent
+    get hideTransparentObjects() {
+        return this._hideTransparentObjects
     }
 
     /**
-     * Sets whether to show transparent objects while the camera is moving.
+     * Sets whether to temporarily hide transparent objects whenever we interact with the Viewer.
      *
-     * Default is ````true````.
+     * Does not hide X-rayed, selected, highlighted objects.
      *
-     * @param {Boolean} dynamicTransparent Whether to show transparent objects while the camera is moving.
+     * Default is ````false````.
+     *
+     * @param {Boolean} hideTransparentObjects ````true```` to hide transparent objects.
      */
-    set dynamicTransparent(dynamicTransparent) {
-        this._dynamicTransparent = (dynamicTransparent !== false);
+    set hideTransparentObjects(hideTransparentObjects) {
+        this._hideTransparentObjects = (hideTransparentObjects !== false);
     }
 
     /**
-     * Gets whether to down-scale the canvas resolution while the camera is moving.
+     * Gets whether to temporarily scale the canvas resolution whenever we interact with the Viewer.
      *
-     * Default is ````true````.
+     * Default is ````false````.
      *
-     * The down-scaling factor is configured via {@link FastNavPlugin#dynamicCanvasResolutionScale}.
+     * The scaling factor is configured via {@link FastNavPlugin#scaleCanvasResolutionFactor}.
      *
-     * @return {Boolean} Whether to down-scale the canvas resolution while the camera is moving.
+     * @return {Boolean} ````true```` if scaling the canvas resolution.
      */
-    get dynamicCanvasResolution() {
-        return this._dynamicCanvasResolution;
+    get scaleCanvasResolution() {
+        return this._scaleCanvasResolution;
     }
 
     /**
-     * Sets whether to down-scale the canvas resolution while the camera is moving.
+     * Sets whether to temporarily scale the canvas resolution whenever we interact with the Viewer.
      *
-     * Default is ````true````.
+     * Default is ````false````.
      *
-     * The down-scaling factor is configured via {@link FastNavPlugin#dynamicCanvasResolutionScale}.
+     * The scaling factor is configured via {@link FastNavPlugin#scaleCanvasResolutionFactor}.
      *
-     * @param {Boolean} dynamicCanvasResolution Whether to down-scale the canvas resolution while the camera is moving.
+     * @param {Boolean} scaleCanvasResolution ````true```` to scale the canvas resolution.
      */
-    set dynamicCanvasResolution(dynamicCanvasResolution) {
-        this._dynamicCanvasResolution = dynamicCanvasResolution;
+    set scaleCanvasResolution(scaleCanvasResolution) {
+        this._scaleCanvasResolution = scaleCanvasResolution;
     }
 
     /**
-     * Gets the factor by which we downscale the canvas resolution while the camera is moving.
-     *
-     * This allows us to render a low-resolution image to the canvas while we're moving the camera.
-     *
-     * Accepted range is ````[0.0 .. 1.0]````.
+     * Gets the factor by which we temporarily scale the canvas resolution when we interact with the viewer.
      *
      * Default is ````0.6````.
      *
-     * @return {Number} Factor by which we downscale the canvas resolution while the camera is moving.
+     * Enable canvas resolution scaling by setting {@link FastNavPlugin#scaleCanvasResolution} ````true````.
+     *
+     * @return {Number} Factor by which we scale the canvas resolution.
      */
-    get dynamicCanvasResolutionScale() {
-        return this._dynamicCanvasResolutionScale;
+    get scaleCanvasResolutionFactor() {
+        return this._scaleCanvasResolutionFactor;
     }
 
     /**
-     * Sets the factor by which we downscale the canvas resolution while the camera is moving.
-     *
-     * This allows us to render a low-resolution image to the canvas while we're moving the camera.
+     * Sets the factor by which we temporarily scale the canvas resolution when we interact with the viewer.
      *
      * Accepted range is ````[0.0 .. 1.0]````.
      *
      * Default is ````0.6````.
      *
-     * @param {Number} dynamicCanvasResolutionScale Factor by which we downscale the canvas resolution while the camera is moving.
+     * Enable canvas resolution scaling by setting {@link FastNavPlugin#scaleCanvasResolution} ````true````.
+     *
+     * @param {Number} scaleCanvasResolutionFactor Factor by which we scale the canvas resolution.
      */
-    set dynamicCanvasResolutionScale(dynamicCanvasResolutionScale) {
-        this._dynamicCanvasResolutionScale = dynamicCanvasResolutionScale || 0.6;
+    set scaleCanvasResolutionFactor(scaleCanvasResolutionFactor) {
+        this._scaleCanvasResolutionFactor = scaleCanvasResolutionFactor || 0.6;
     }
 
     /**
-     * Gets whether to have a delay before transitioning back to normal static rendering after the camera stops moving.
+     * Gets whether to have a delay before restoring normal rendering after we stop interacting with the Viewer.
      *
-     * The delay duration is configured via {@link FastNavPlugin#delayBeforeStaticDuration}.
+     * The delay duration is configured via {@link FastNavPlugin#delayBeforeRestoreSeconds}.
      *
      * Default is ````true````.
      *
      * @return {Boolean} Whether to have a delay.
      */
-    get delayBeforeStatic() {
-        return this._delayBeforeStatic;
+    get delayBeforeRestore() {
+        return this._delayBeforeRestore;
     }
 
     /**
-     * Sets whether to have a delay before transitioning back to normal static rendering after the camera stops moving.
+     * Sets whether to have a delay before restoring normal rendering after we stop interacting with the Viewer.
      *
-     * The delay duration is configured via {@link FastNavPlugin#delayBeforeStaticDuration}.
+     * The delay duration is configured via {@link FastNavPlugin#delayBeforeRestoreSeconds}.
      *
      * Default is ````true````.
      *
-     * @param {Boolean} delayBeforeStatic Whether to have a delay.
+     * @param {Boolean} delayBeforeRestore Whether to have a delay.
      */
-    set delayBeforeStatic(delayBeforeStatic) {
-        this._delayBeforeStatic = delayBeforeStatic;
+    set delayBeforeRestore(delayBeforeRestore) {
+        this._delayBeforeRestore = delayBeforeRestore;
     }
 
     /**
-     * Gets the delay in seconds before transitioning back to normal static rendering when camera stops moving.
+     * Gets the delay before restoring normal rendering after we stop interacting with the Viewer.
      *
-     * The delay is enabled when {@link FastNavPlugin#delayBeforeStatic} is ````true````.
+     * The delay is enabled when {@link FastNavPlugin#delayBeforeRestore} is ````true````.
      *
      * Default is ````0.5```` seconds.
      *
-     * @return {Number} Timeout duration in seconds.
+     * @return {Number} Delay in seconds.
      */
-    get delayBeforeStaticDuration() {
-        return this._delayBeforeStaticDuration;
+    get delayBeforeRestoreSeconds() {
+        return this._delayBeforeRestoreSeconds;
     }
 
     /**
-     * Sets the delay in seconds before transitioning back to normal static rendering when camera stops moving.
+     * Sets the delay before restoring normal rendering after we stop interacting with the Viewer.
      *
-     * The delay is enabled when {@link FastNavPlugin#delayBeforeStatic} is ````true````.
+     * The delay is enabled when {@link FastNavPlugin#delayBeforeRestore} is ````true````.
      *
      * Default is ````0.5```` seconds.
      *
-     * @param {Number} delayBeforeStaticDuration Timeout duration in seconds.
+     * @param {Number} delayBeforeRestoreSeconds Delay in seconds.
      */
-    set delayBeforeStaticDuration(delayBeforeStaticDuration) {
-        this._delayBeforeStaticDuration = delayBeforeStaticDuration !== null && delayBeforeStaticDuration !== undefined ? delayBeforeStaticDuration : 0.5;
+    set delayBeforeRestoreSeconds(delayBeforeRestoreSeconds) {
+        this._delayBeforeRestoreSeconds = delayBeforeRestoreSeconds !== null && delayBeforeRestoreSeconds !== undefined ? delayBeforeRestoreSeconds : 0.5;
     }
 
     /**