@vyr/three 0.0.10 → 0.0.11

package/build/controls/CameraControls.d.ts

@@ -0,0 +1,647 @@
+import { Graphics } from '@vyr/engine';
+import { EventDispatcher, Vector3, Vector2, Spherical, Box3, Sphere, Quaternion, PerspectiveCamera, OrthographicCamera, Object3D, Mesh, Vector4 } from 'three';
+interface Pointer {
+    pointerId: number;
+    clientX: number;
+    clientY: number;
+    deltaX: number;
+    deltaY: number;
+    mouseButton: number | null;
+}
+declare class CameraControls extends EventDispatcher<any> {
+    static get ACTION(): Readonly<{
+        NONE: 0;
+        ROTATE: 1;
+        TRUCK: 2;
+        OFFSET: 4;
+        DOLLY: 8;
+        ZOOM: 16;
+        TOUCH_ROTATE: 32;
+        TOUCH_TRUCK: 64;
+        TOUCH_OFFSET: 128;
+        TOUCH_DOLLY: 256;
+        TOUCH_ZOOM: 512;
+        TOUCH_DOLLY_TRUCK: 1024;
+        TOUCH_DOLLY_OFFSET: 2048;
+        TOUCH_DOLLY_ROTATE: 4096;
+        TOUCH_ZOOM_TRUCK: 8192;
+        TOUCH_ZOOM_OFFSET: 16384;
+        TOUCH_ZOOM_ROTATE: 32768;
+    }>;
+    private _listeners;
+    minPolarAngle: number;
+    maxPolarAngle: number;
+    minAzimuthAngle: number;
+    maxAzimuthAngle: number;
+    minDistance: number;
+    maxDistance: number;
+    infinityDolly: boolean;
+    minZoom: number;
+    maxZoom: number;
+    smoothTime: number;
+    draggingSmoothTime: number;
+    maxSpeed: number;
+    azimuthRotateSpeed: number;
+    polarRotateSpeed: number;
+    dollySpeed: number;
+    dollyDragInverted: boolean;
+    truckSpeed: number;
+    dollyToCursor: boolean;
+    dragToOffset: boolean;
+    verticalDragToForward: boolean;
+    boundaryFriction: number;
+    restThreshold: number;
+    colliderMeshes: never[];
+    cancel: () => void;
+    _enabled: boolean;
+    _state: number;
+    _viewport: Vector4 | null;
+    _changedDolly: number;
+    _changedZoom: number;
+    _hasRested: boolean;
+    _boundaryEnclosesCamera: boolean;
+    _needsUpdate: boolean;
+    _updatedLastTime: boolean;
+    _elementRect: DOMRect;
+    _isDragging: boolean;
+    _dragNeedsUpdate: boolean;
+    _activePointers: Pointer[];
+    _lockedPointer: Pointer | null;
+    _interactiveArea: DOMRect;
+    _isUserControllingRotate: boolean;
+    _isUserControllingDolly: boolean;
+    _isUserControllingTruck: boolean;
+    _isUserControllingOffset: boolean;
+    _isUserControllingZoom: boolean;
+    _lastDollyDirection: number;
+    _thetaVelocity: {
+        value: number;
+    };
+    _phiVelocity: {
+        value: number;
+    };
+    _radiusVelocity: {
+        value: number;
+    };
+    _targetVelocity: Vector3;
+    _focalOffsetVelocity: Vector3;
+    _zoomVelocity: {
+        value: number;
+    };
+    _truckInternal: (deltaX: number, deltaY: number, dragToOffset: boolean) => void;
+    _rotateInternal: (deltaX: number, deltaY: number) => void;
+    _dollyInternal: (delta: number, x: number, y: number) => void;
+    _zoomInternal: (delta: number, x: number, y: number) => void;
+    _nearPlaneCorners: Vector3[];
+    _target: Vector3;
+    _focalOffset: Vector3;
+    _domElement: HTMLElement;
+    dragStartPosition: Vector2;
+    lastDragPosition: Vector2;
+    dollyStart: Vector2;
+    _camera: PerspectiveCamera | OrthographicCamera;
+    _yAxisUpSpace: Quaternion;
+    _yAxisUpSpaceInverse: Quaternion;
+    _targetEnd: Vector3;
+    _focalOffsetEnd: Vector3;
+    _spherical: Spherical;
+    _sphericalEnd: Spherical;
+    _lastDistance: number;
+    _zoom: number;
+    _zoomEnd: number;
+    _lastZoom: number;
+    _boundary: Box3;
+    _cameraUp0: Vector3;
+    _target0: Vector3;
+    _position0: Vector3;
+    _zoom0: number;
+    _focalOffset0: Vector3;
+    _dollyControlCoord: Vector2;
+    mouseButtons: {
+        left: number;
+        middle: number;
+        right: number;
+        wheel: number;
+    };
+    touches: {
+        one: number;
+        two: number;
+        three: number;
+    };
+    events: number[];
+    lockPointer: () => void;
+    unlockPointer: () => void;
+    constructor(graphics: Graphics);
+    /**
+     * The camera to be controlled
+     * @category Properties
+     */
+    get camera(): PerspectiveCamera | OrthographicCamera;
+    set camera(camera: PerspectiveCamera | OrthographicCamera);
+    /**
+     * Whether or not the controls are enabled.
+     * `false` to disable user dragging/touch-move, but all methods works.
+     * @category Properties
+     */
+    get enabled(): boolean;
+    set enabled(enabled: boolean);
+    /**
+     * Returns `true` if the controls are active updating.
+     * readonly value.
+     * @category Properties
+     */
+    get active(): boolean;
+    /**
+     * Getter for the current `ACTION`.
+     * readonly value.
+     * @category Properties
+     */
+    get currentAction(): number;
+    /**
+     * get/set Current distance.
+     * @category Properties
+     */
+    get distance(): number;
+    set distance(distance: number);
+    /**
+     * get/set the azimuth angle (horizontal) in radians.
+     * Every 360 degrees turn is added to `.azimuthAngle` value, which is accumulative.
+     * @category Properties
+     */
+    get azimuthAngle(): number;
+    set azimuthAngle(azimuthAngle: number);
+    /**
+     * get/set the polar angle (vertical) in radians.
+     * @category Properties
+     */
+    get polarAngle(): number;
+    set polarAngle(polarAngle: number);
+    /**
+     * Whether camera position should be enclosed in the boundary or not.
+     * @category Properties
+     */
+    get boundaryEnclosesCamera(): boolean;
+    set boundaryEnclosesCamera(boundaryEnclosesCamera: boolean);
+    /**
+     * Set drag-start, touches and wheel enable area in the domElement.
+     * each values are between `0` and `1` inclusive, where `0` is left/top and `1` is right/bottom of the screen.
+     * e.g. `{ x: 0, y: 0, width: 1, height: 1 }` for entire area.
+     * @category Properties
+     */
+    set interactiveArea(interactiveArea: DOMRect);
+    /**
+     * Adds the specified event listener.
+     * Applicable event types (which is `K`) are:
+     * | Event name          | Timing |
+     * | ------------------- | ------ |
+     * | `'controlstart'`    | When the user starts to control the camera via mouse / touches. ¹ |
+     * | `'control'`         | When the user controls the camera (dragging). |
+     * | `'controlend'`      | When the user ends to control the camera. ¹ |
+     * | `'transitionstart'` | When any kind of transition starts, either user control or using a method with `enableTransition = true` |
+     * | `'update'`          | When the camera position is updated. |
+     * | `'wake'`            | When the camera starts moving. |
+     * | `'rest'`            | When the camera movement is below `.restThreshold` ². |
+     * | `'sleep'`           | When the camera end moving. |
+     *
+     * 1. `mouseButtons.wheel` (Mouse wheel control) does not emit `'controlstart'` and `'controlend'`. `mouseButtons.wheel` uses scroll-event internally, and scroll-event happens intermittently. That means "start" and "end" cannot be detected.
+     * 2. Due to damping, `sleep` will usually fire a few seconds after the camera _appears_ to have stopped moving. If you want to do something (e.g. enable UI, perform another transition) at the point when the camera has stopped, you probably want the `rest` event. This can be fine tuned using the `.restThreshold` parameter. See the [Rest and Sleep Example](https://yomotsu.github.io/camera-controls/examples/rest-and-sleep.html).
+     *
+     * e.g.
+     * ```
+     * cameraControl.addEventListener( 'controlstart', myCallbackFunction );
+     * ```
+     * @param type event name
+     * @param listener handler function
+     * @category Methods
+     */
+    addEventListener(type: string, listener: (...args: any[]) => any): void;
+    /**
+     * Removes the specified event listener
+     * e.g.
+     * ```
+     * cameraControl.addEventListener( 'controlstart', myCallbackFunction );
+     * ```
+     * @param type event name
+     * @param listener handler function
+     * @category Methods
+     */
+    removeEventListener(type: string, listener: (...args: any[]) => any): void;
+    removeAllEventListeners(type?: string): void;
+    /**
+     * Rotate azimuthal angle(horizontal) and polar angle(vertical).
+     * Every value is added to the current value.
+     * @param azimuthAngle Azimuth rotate angle. In radian.
+     * @param polarAngle Polar rotate angle. In radian.
+     * @param enableTransition Whether to move smoothly or immediately
+     * @category Methods
+     */
+    rotate(azimuthAngle: number, polarAngle: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * Rotate azimuthal angle(horizontal) to the given angle and keep the same polar angle(vertical) target.
+     *
+     * e.g.
+     * ```
+     * cameraControls.rotateAzimuthTo( 30 * MathUtils.DEG2RAD, true );
+     * ```
+     * @param azimuthAngle Azimuth rotate angle. In radian.
+     * @param enableTransition Whether to move smoothly or immediately
+     * @category Methods
+     */
+    rotateAzimuthTo(azimuthAngle: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * Rotate polar angle(vertical) to the given angle and keep the same azimuthal angle(horizontal) target.
+     *
+     * e.g.
+     * ```
+     * cameraControls.rotatePolarTo( 30 * MathUtils.DEG2RAD, true );
+     * ```
+     * @param polarAngle Polar rotate angle. In radian.
+     * @param enableTransition Whether to move smoothly or immediately
+     * @category Methods
+     */
+    rotatePolarTo(polarAngle: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * Rotate azimuthal angle(horizontal) and polar angle(vertical) to the given angle.
+     * Camera view will rotate over the orbit pivot absolutely:
+     *
+     * azimuthAngle
+     * ```
+     *       0º
+     *         \
+     * 90º -----+----- -90º
+     *           \
+     *           180º
+     * ```
+     * | direction | angle                  |
+     * | --------- | ---------------------- |
+     * | front     | 0º                     |
+     * | left      | 90º (`Math.PI / 2`)    |
+     * | right     | -90º (`- Math.PI / 2`) |
+     * | back      | 180º (`Math.PI`)       |
+     *
+     * polarAngle
+     * ```
+     *     180º
+     *      |
+     *      90º
+     *      |
+     *      0º
+     * ```
+     * | direction            | angle                  |
+     * | -------------------- | ---------------------- |
+     * | top/sky              | 180º (`Math.PI`)       |
+     * | horizontal from view | 90º (`Math.PI / 2`)    |
+     * | bottom/floor         | 0º                     |
+     *
+     * @param azimuthAngle Azimuth rotate angle to. In radian.
+     * @param polarAngle Polar rotate angle to. In radian.
+     * @param enableTransition  Whether to move smoothly or immediately
+     * @category Methods
+     */
+    rotateTo(azimuthAngle: number, polarAngle: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * Dolly in/out camera position.
+     * @param distance Distance of dollyIn. Negative number for dollyOut.
+     * @param enableTransition Whether to move smoothly or immediately.
+     * @category Methods
+     */
+    dolly(distance: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * Dolly in/out camera position to given distance.
+     * @param distance Distance of dolly.
+     * @param enableTransition Whether to move smoothly or immediately.
+     * @category Methods
+     */
+    dollyTo(distance: number, enableTransition?: boolean): Promise<void>;
+    _dollyToNoClamp(distance: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * Dolly in, but does not change the distance between the target and the camera, and moves the target position instead.
+     * Specify a negative value for dolly out.
+     * @param distance Distance of dolly.
+     * @param enableTransition Whether to move smoothly or immediately.
+     * @category Methods
+     */
+    dollyInFixed(distance: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * Zoom in/out camera. The value is added to camera zoom.
+     * Limits set with `.minZoom` and `.maxZoom`
+     * @param zoomStep zoom scale
+     * @param enableTransition Whether to move smoothly or immediately
+     * @category Methods
+     */
+    zoom(zoomStep: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * Zoom in/out camera to given scale. The value overwrites camera zoom.
+     * Limits set with .minZoom and .maxZoom
+     * @param zoom
+     * @param enableTransition
+     * @category Methods
+     */
+    zoomTo(zoom: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * @deprecated `pan()` has been renamed to `truck()`
+     * @category Methods
+     */
+    pan(x: number, y: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * Truck and pedestal camera using current azimuthal angle
+     * @param x Horizontal translate amount
+     * @param y Vertical translate amount
+     * @param enableTransition Whether to move smoothly or immediately
+     * @category Methods
+     */
+    truck(x: number, y: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * Move forward / backward.
+     * @param distance Amount to move forward / backward. Negative value to move backward
+     * @param enableTransition Whether to move smoothly or immediately
+     * @category Methods
+     */
+    forward(distance: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * Move up / down.
+     * @param height Amount to move up / down. Negative value to move down
+     * @param enableTransition Whether to move smoothly or immediately
+     * @category Methods
+     */
+    elevate(height: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * Move target position to given point.
+     * @param x x coord to move center position
+     * @param y y coord to move center position
+     * @param z z coord to move center position
+     * @param enableTransition Whether to move smoothly or immediately
+     * @category Methods
+     */
+    moveTo(x: number, y: number, z: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * Look in the given point direction.
+     * @param x point x.
+     * @param y point y.
+     * @param z point z.
+     * @param enableTransition Whether to move smoothly or immediately.
+     * @returns Transition end promise
+     * @category Methods
+     */
+    lookInDirectionOf(x: number, y: number, z: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * Fit the viewport to the box or the bounding box of the object, using the nearest axis. paddings are in unit.
+     * set `cover: true` to fill enter screen.
+     * e.g.
+     * ```
+     * cameraControls.fitToBox( myMesh );
+     * ```
+     * @param box3OrObject Axis aligned bounding box to fit the view.
+     * @param enableTransition Whether to move smoothly or immediately.
+     * @param options | `<object>` { cover: boolean, paddingTop: number, paddingLeft: number, paddingBottom: number, paddingRight: number }
+     * @returns Transition end promise
+     * @category Methods
+     */
+    fitToBox(box3OrObject: Box3 | Object3D, enableTransition: boolean, { cover, paddingLeft, paddingRight, paddingBottom, paddingTop }?: {
+        cover?: boolean | undefined;
+        paddingLeft?: number | undefined;
+        paddingRight?: number | undefined;
+        paddingBottom?: number | undefined;
+        paddingTop?: number | undefined;
+    }): Promise<void[]>;
+    /**
+     * Fit the viewport to the sphere or the bounding sphere of the object.
+     * @param sphereOrMesh
+     * @param enableTransition
+     * @category Methods
+     */
+    fitToSphere(sphereOrMesh: Sphere | Mesh, enableTransition: boolean): Promise<void[]>;
+    /**
+     * Look at the `target` from the `position`.
+     * @param positionX
+     * @param positionY
+     * @param positionZ
+     * @param targetX
+     * @param targetY
+     * @param targetZ
+     * @param enableTransition
+     * @category Methods
+     */
+    setLookAt(positionX: number, positionY: number, positionZ: number, targetX: number, targetY: number, targetZ: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * Similar to setLookAt, but it interpolates between two states.
+     * @param positionAX
+     * @param positionAY
+     * @param positionAZ
+     * @param targetAX
+     * @param targetAY
+     * @param targetAZ
+     * @param positionBX
+     * @param positionBY
+     * @param positionBZ
+     * @param targetBX
+     * @param targetBY
+     * @param targetBZ
+     * @param t
+     * @param enableTransition
+     * @category Methods
+     */
+    lerpLookAt(positionAX: number, positionAY: number, positionAZ: number, targetAX: number, targetAY: number, targetAZ: number, positionBX: number, positionBY: number, positionBZ: number, targetBX: number, targetBY: number, targetBZ: number, t: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * Set angle and distance by given position.
+     * An alias of `setLookAt()`, without target change. Thus keep gazing at the current target
+     * @param positionX
+     * @param positionY
+     * @param positionZ
+     * @param enableTransition
+     * @category Methods
+     */
+    setPosition(positionX: number, positionY: number, positionZ: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * Set the target position where gaze at.
+     * An alias of `setLookAt()`, without position change. Thus keep the same position.
+     * @param targetX
+     * @param targetY
+     * @param targetZ
+     * @param enableTransition
+     * @category Methods
+     */
+    setTarget(targetX: number, targetY: number, targetZ: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * Set focal offset using the screen parallel coordinates. z doesn't affect in Orthographic as with Dolly.
+     * @param x
+     * @param y
+     * @param z
+     * @param enableTransition
+     * @category Methods
+     */
+    setFocalOffset(x: number, y: number, z: number, enableTransition?: boolean): Promise<void>;
+    /**
+     * Set orbit point without moving the camera.
+     * SHOULD NOT RUN DURING ANIMATIONS. `setOrbitPoint()` will immediately fix the positions.
+     * @param targetX
+     * @param targetY
+     * @param targetZ
+     * @category Methods
+     */
+    setOrbitPoint(targetX: number, targetY: number, targetZ: number): void;
+    /**
+     * Set the boundary box that encloses the target of the camera. box3 is in Box3
+     * @param box3
+     * @category Methods
+     */
+    setBoundary(box3: Box3): void;
+    /**
+     * Set (or unset) the current viewport.
+     * Set this when you want to use renderer viewport and .dollyToCursor feature at the same time.
+     * @param viewportOrX
+     * @param y
+     * @param width
+     * @param height
+     * @category Methods
+     */
+    setViewport(viewportOrX: number | Vector4, y: number, width: number, height: number): void;
+    /**
+     * Calculate the distance to fit the box.
+     * @param width box width
+     * @param height box height
+     * @param depth box depth
+     * @returns distance
+     * @category Methods
+     */
+    getDistanceToFitBox(width: number, height: number, depth: number, cover?: boolean): number;
+    /**
+     * Calculate the distance to fit the sphere.
+     * @param radius sphere radius
+     * @returns distance
+     * @category Methods
+     */
+    getDistanceToFitSphere(radius: number): number;
+    /**
+     * Returns the orbit center position, where the camera looking at.
+     * @param out The receiving Vector3 instance to copy the result
+     * @param receiveEndValue Whether receive the transition end coords or current. default is `true`
+     * @category Methods
+     */
+    getTarget(out: Vector3, receiveEndValue?: boolean): Vector3;
+    /**
+     * Returns the camera position.
+     * @param out The receiving Vector3 instance to copy the result
+     * @param receiveEndValue Whether receive the transition end coords or current. default is `true`
+     * @category Methods
+     */
+    getPosition(out: Vector3, receiveEndValue?: boolean): Vector3;
+    /**
+     * Returns the spherical coordinates of the orbit.
+     * @param out The receiving Spherical instance to copy the result
+     * @param receiveEndValue Whether receive the transition end coords or current. default is `true`
+     * @category Methods
+     */
+    getSpherical(out: Spherical, receiveEndValue?: boolean): Spherical;
+    /**
+     * Returns the focal offset, which is how much the camera appears to be translated in screen parallel coordinates.
+     * @param out The receiving Vector3 instance to copy the result
+     * @param receiveEndValue Whether receive the transition end coords or current. default is `true`
+     * @category Methods
+     */
+    getFocalOffset(out: Vector3, receiveEndValue?: boolean): Vector3;
+    /**
+     * Normalize camera azimuth angle rotation between 0 and 360 degrees.
+     * @category Methods
+     */
+    normalizeRotations(): void;
+    listen(camera: PerspectiveCamera | OrthographicCamera): void;
+    /**
+     * Reset all rotation and position to defaults.
+     * @param enableTransition
+     * @category Methods
+     */
+    reset(enableTransition?: boolean): Promise<void[]>;
+    /**
+     * Set current camera position as the default position.
+     * @category Methods
+     */
+    saveState(): void;
+    /**
+     * Sync camera-up direction.
+     * When camera-up vector is changed, `.updateCameraUp()` must be called.
+     * @category Methods
+     */
+    updateCameraUp(): void;
+    /**
+     * Apply current camera-up direction to the camera.
+     * The orbit system will be re-initialized with the current position.
+     * @category Methods
+     */
+    applyCameraUp(): void;
+    /**
+     * Update camera position and directions.
+     * This should be called in your tick loop every time, and returns true if re-rendering is needed.
+     * @param delta
+     * @returns updated
+     * @category Methods
+     */
+    update(delta: number): boolean;
+    /**
+     * Get all state in JSON string
+     * @category Methods
+     */
+    toJSON(): string;
+    /**
+     * Reproduce the control state with JSON. enableTransition is where anim or not in a boolean.
+     * @param json
+     * @param enableTransition
+     * @category Methods
+     */
+    fromJSON(json: string, enableTransition?: boolean): void;
+    /**
+     * Attach all internal event handlers to enable drag control.
+     * @category Methods
+     */
+    connect(domElement: HTMLElement): void;
+    /**
+     * Detach all internal event handlers to disable drag control.
+     */
+    disconnect(): void;
+    /**
+     * Dispose the cameraControls instance itself, remove all eventListeners.
+     * @category Methods
+     */
+    dispose(): void;
+    _getTargetDirection(out: Vector3): Vector3;
+    _getCameraDirection(out: Vector3): Vector3;
+    _findPointerById(pointerId: number): Pointer | undefined;
+    _findPointerByMouseButton(mouseButton: number): Pointer | undefined;
+    _disposePointer(pointer: Pointer): void;
+    _encloseToBoundary(position: Vector3, offset: Vector3, friction: number): Vector3;
+    _updateNearPlaneCorners(): void;
+    _collisionTest(): number;
+    /**
+     * Get its client rect and package into given `DOMRect` .
+     */
+    _getClientRect(target: DOMRect): DOMRect | undefined;
+    _createOnRestPromise(resolveImmediately: boolean): Promise<void>;
+    _addAllEventListeners(_domElement: HTMLElement): void;
+    _removeAllEventListeners(): void;
+    /**
+     * backward compatible
+     * @deprecated use smoothTime (in seconds) instead
+     * @category Properties
+     */
+    get dampingFactor(): number;
+    /**
+     * backward compatible
+     * @deprecated use smoothTime (in seconds) instead
+     * @category Properties
+     */
+    set dampingFactor(_: number);
+    /**
+     * backward compatible
+     * @deprecated use draggingSmoothTime (in seconds) instead
+     * @category Properties
+     */
+    get draggingDampingFactor(): number;
+    /**
+     * backward compatible
+     * @deprecated use draggingSmoothTime (in seconds) instead
+     * @category Properties
+     */
+    set draggingDampingFactor(_: number);
+    static createBoundingSphere(object3d: Object3D, out?: Sphere): Sphere;
+}
+export { CameraControls };