@needle-tools/engine 4.11.0 → 4.11.1

package/src/engine-components/web/ViewBox.ts

@@ -1,4 +1,4 @@
-import { Camera, Matrix4, PerspectiveCamera, Quaternion, Scene, Vector2, Vector3 } from "three";
+import { Camera, Matrix4, PerspectiveCamera, Vector3 } from "three";
 
 import { isDevEnvironment } from "../../engine/debug/debug.js";
 import { Gizmos } from "../../engine/engine_gizmos.js";
@@ -13,6 +13,8 @@ import { Behaviour } from "../Component.js";
 const debugParam = getParam("debugviewbox");
 const disabledGizmoColor = new RGBAColor(.5, .5, .5, .5);
 
+export type ViewBoxMode = "continuous" | "once";
+
 /**
  * This component can be used to automatically fit a certain box area into the camera view - no matter your screen size or aspect ratio.  
  * This is useful for example to frame a character or object in the center of the screen and ensure it is always fully visible. You can also animate or scale the viewbox to create zoom or framing effects.
@@ -36,6 +38,9 @@ const disabledGizmoColor = new RGBAColor(.5, .5, .5, .5);
 @registerType
 export class ViewBox extends Behaviour {
 
+    /**
+     * All active ViewBox instances. The last one in the array is the currently active one.
+     */
     static readonly instances: ViewBox[] = [];
 
     /**
@@ -45,21 +50,39 @@ export class ViewBox extends Behaviour {
     @serializable()
     referenceFieldOfView: number = -1;
 
+    /**
+     * The mode determines if the viewbox should be applied once or continuously while it is the active viewbox.  
+     * Options:
+     * - "once": The viewbox will be applied once when it becomes the active viewbox. This is useful if you want to fit the view once and then allow the user to zoom or pan freely.
+     * - "continuous": The viewbox will be applied continuously while it is the active viewbox. This is useful if you animate or scale the viewbox over time.
+    */
+    @serializable()
+    get mode() { return this._mode; }
+    set mode(v: ViewBoxMode) {
+        if (v === this._mode) return;
+        this._mode = v;
+        if (v === "once") this._applyCount = 0;
+        if (debugParam || this.debug) console.debug("[ViewBox] Set mode:", v);
+    }
+    private _mode: ViewBoxMode = "continuous";
+
     /**
      * Enable debug logs and rendering for this component instance
      */
     @serializable()
     debug: boolean = false;
 
+    /** @internal */
     onEnable(): void {
         if (debugParam || this.debug || isDevEnvironment()) console.debug("[ViewBox] Using camera fov:", this.referenceFieldOfView);
         // register instance
         ViewBox.instances.push(this);
-
+        this._applyCount = 0;
         this.removeUpdateCallback();
         this.context.pre_render_callbacks.push(this.internalUpdate);
     }
 
+    /** @internal */
     onDisable(): void {
         if (debugParam || this.debug) console.debug("[ViewBox] Disabled");
         // unregister instance
@@ -77,6 +100,7 @@ export class ViewBox extends Behaviour {
 
     private static readonly _tempProjectionMatrix: Matrix4 = new Matrix4();
     private static readonly _tempProjectionMatrixInverse: Matrix4 = new Matrix4();
+    private _applyCount = 0;
 
     private internalUpdate = () => {
         if (this.context.isInXR) return;
@@ -108,6 +132,11 @@ export class ViewBox extends Behaviour {
             return;
         }
 
+        if (this._applyCount >= 1 && this.mode === "once") {
+            return;
+        }
+        this._applyCount++;
+
         const domWidth = this.context.domWidth;
         const domHeight = this.context.domHeight;
 
@@ -129,7 +158,7 @@ export class ViewBox extends Behaviour {
         ViewBox._tempProjectionMatrix.copy(camera.projectionMatrix);
         ViewBox._tempProjectionMatrixInverse.copy(camera.projectionMatrixInverse);
         const view = camera.view;
-        const zoom = camera.zoom;
+        const cameraZoom = camera.zoom;
         const aspect = camera.aspect;
         const fov = camera.fov;
         // Set values to default so we can calculate the box size correctly
@@ -194,6 +223,7 @@ export class ViewBox extends Behaviour {
             width / diffWidth,
             height / diffHeight
         );
+        const zoom = scale / (height * .5);
         // console.log({ scale, width, height, boxWidth: boxWidth * camera.aspect, boxHeight, diffWidth, diffHeight, aspect: camera.aspect, distance })
         // this.context.focusRectSettings.zoom = 1.39;
         // if (!this.context.focusRect) this.context.setCameraFocusRect(this.context.domElement);
@@ -202,13 +232,13 @@ export class ViewBox extends Behaviour {
         vec.project(camera);
         this.context.focusRectSettings.offsetX = vec.x;
         this.context.focusRectSettings.offsetY = vec.y;
-        this.context.focusRectSettings.zoom = scale / (height * .5);
+        this.context.focusRectSettings.zoom = zoom;
         // if we don't have a focus rect yet, set it to the dom element
         if (!this.context.focusRect) this.context.setCameraFocusRect(this.context.domElement);
 
         // Reset values
         camera.view = view;
-        camera.zoom = zoom;
+        camera.zoom = cameraZoom;
         camera.aspect = aspect;
         camera.fov = fov;
         camera.projectionMatrix.copy(ViewBox._tempProjectionMatrix);