@needle-tools/three 0.169.12 → 0.169.13

package/types/src/audio/AudioListener.d.ts

@@ -0,0 +1,96 @@
+import { Object3D } from "../core/Object3D.js";
+import { AudioContext } from "./AudioContext.js";
+
+/**
+ * The {@link AudioListener} represents a virtual {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioListener | listener} of the all positional and non-positional audio effects in the scene.
+ * A three.js application usually creates a single instance of {@link AudioListener}  * @remarks
+ * It is a mandatory construtor parameter for audios entities like {@link Audio | Audio} and {@link PositionalAudio | PositionalAudio}.
+ * In most cases, the listener object is a child of the camera
+ * So the 3D transformation of the camera represents the 3D transformation of the listener.
+ * @example
+ * ```typescript
+ * // create an {@link AudioListener} and add it to the camera
+ * const listener = new THREE.AudioListener();
+ * camera.add(listener);
+ * // create a global audio source
+ * const sound = new THREE.Audio(listener);
+ * // load a sound and set it as the Audio object's buffer
+ * const audioLoader = new THREE.AudioLoader();
+ * audioLoader.load('sounds/ambient.ogg', function (buffer) {
+ *     sound.setBuffer(buffer);
+ *     sound.setLoop(true);
+ *     sound.setVolume(0.5);
+ *     sound.play();
+ * });
+ * ```
+ * @see Example: {@link https://threejs.org/examples/#webaudio_sandbox | webaudio / sandbox }
+ * @see Example: {@link https://threejs.org/examples/#webaudio_timing | webaudio / timing }
+ * @see Example: {@link https://threejs.org/examples/#webaudio_visualizer | webaudio / visualizer }
+ * @see {@link https://threejs.org/docs/index.html#api/en/audio/AudioListener | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/audio/AudioListener.js | Source}
+ */
+export class AudioListener extends Object3D {
+    /**
+     * Create a new AudioListener.
+     */
+    constructor();
+
+    /**
+     * A Read-only _string_ to check if `this` object type.
+     * @remarks Sub-classes will update this value.
+     * @defaultValue `AudioListener`
+     */
+    readonly type: string | "AudioListener";
+
+    /**
+     * The {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioContext | AudioContext} of the {@link {@link AudioListener} | listener} given in the constructor.
+     */
+    context: AudioContext;
+
+    /**
+     * A {@link https://developer.mozilla.org/en-US/docs/Web/API/GainNode | GainNode} created using
+     * {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/createGain | AudioContext.createGain()}.
+     */
+    gain: GainNode;
+
+    /**
+     * @defaultValue `null`
+     */
+    filter: AudioNode;
+
+    /**
+     * Time delta value for audio entities. Use in context of {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioParam/linearRampToValueAtTime | AudioParam.linearRampToValueAtTimeDefault()}.
+     * @defaultValue `0`
+     */
+    timeDelta: number;
+
+    /**
+     * Return the {@link AudioListener.gain | gainNode}.
+     */
+    getInput(): GainNode;
+    /**
+     * Set the {@link AudioListener.filter | filter} property to `null`.
+     */
+    removeFilter(): this;
+
+    /**
+     * Returns the value of the {@link AudioListener.filter | filter} property.
+     */
+    getFilter(): AudioNode;
+    /**
+     * Set the {@link AudioListener.filter | filter} property to `value`.
+     * @param value
+     */
+    setFilter(value: AudioNode): this;
+
+    /**
+     * Return the volume.
+     */
+    getMasterVolume(): number;
+
+    /**
+     * Set the volume.
+     * @param value
+     */
+    setMasterVolume(value: number): this;
+}

package/types/src/audio/PositionalAudio.d.ts

@@ -0,0 +1,101 @@
+import { Audio } from "./Audio.js";
+import { AudioListener } from "./AudioListener.js";
+
+/**
+ * Create a positional audio object.
+ * This uses the {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API | Web Audio API}.
+ * @example
+ * ```typescript
+ * // create an AudioListener and add it to the camera
+ * const listener = new THREE.AudioListener();
+ * camera.add(listener);
+ * // create the {@link PositionalAudio} object (passing in the listener)
+ * const sound = new THREE.PositionalAudio(listener);
+ * // load a sound and set it as the {@link PositionalAudio} object's buffer
+ * const audioLoader = new THREE.AudioLoader();
+ * audioLoader.load('sounds/song.ogg', function (buffer) {
+ *     sound.setBuffer(buffer);
+ *     sound.setRefDistance(20);
+ *     sound.play();
+ * });
+ * // create an object for the sound to play from
+ * const sphere = new THREE.SphereGeometry(20, 32, 16);
+ * const material = new THREE.MeshPhongMaterial({
+ *     color: 0xff2200
+ * });
+ * const mesh = new THREE.Mesh(sphere, material);
+ * scene.add(mesh);
+ * // finally add the sound to the mesh
+ * mesh.add(sound);
+ * ```
+ * @see Example: {@link https://threejs.org/examples/#webaudio_orientation | webaudio / orientation }
+ * @see Example: {@link https://threejs.org/examples/#webaudio_sandbox | webaudio / sandbox }
+ * @see Example: {@link https://threejs.org/examples/#webaudio_timing | webaudio / timing }
+ * @see {@link https://threejs.org/docs/index.html#api/en/audio/PositionalAudio | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/audio/PositionalAudio.js | Source}
+ */
+export class PositionalAudio extends Audio<PannerNode> {
+    /**
+     * Create a new instance of {@link PositionalAudio}
+     * @param listener (required) {@link AudioListener | AudioListener} instance.
+     */
+    constructor(listener: AudioListener);
+
+    /**
+     * The PositionalAudio's {@link https://developer.mozilla.org/en-US/docs/Web/API/PannerNode | PannerNode}.
+     */
+    panner: PannerNode;
+
+    /**
+     * Returns the {@link PositionalAudio.panner | panner}.
+     */
+    getOutput(): PannerNode;
+
+    /**
+     * Returns the value of {@link https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/refDistance | panner.refDistance}.
+     */
+    getRefDistance(): number;
+    /**
+     * Sets the value of {@link https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/refDistance | panner.refDistance}.
+     * @param value Expects a `Float`
+     */
+    setRefDistance(value: number): this;
+
+    /**
+     * Returns the value of {@link https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/rolloffFactor | panner.rolloffFactor}.
+     */
+    getRolloffFactor(): number;
+    /**
+     * Sets the value of {@link https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/rolloffFactor | panner.rolloffFactor}.
+     * @param value Expects a `Float`
+     */
+    setRolloffFactor(value: number): this;
+
+    /**
+     * Returns the value of {@link https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/distanceModel | panner.distanceModel}.
+     */
+    getDistanceModel(): string;
+    /**
+     * Sets the value of {@link https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/distanceModel | panner.distanceModel}.
+     * @param value
+     */
+    setDistanceModel(value: string): this;
+
+    /**
+     * Returns the value of {@link https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/maxDistance | panner.maxDistance}.
+     */
+    getMaxDistance(): number;
+    /**
+     * Sets the value of {@link https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/maxDistance | panner.maxDistance}.
+     * @param value Expects a `Float`
+     */
+    setMaxDistance(value: number): this;
+
+    /**
+     * This method can be used in order to transform an omnidirectional sound into a {@link https://developer.mozilla.org/en-US/docs/Web/API/PannerNode | directional sound}.
+     * @param coneInnerAngle Expects a `Float`
+     * @param coneOuterAngle Expects a `Float`
+     * @param coneOuterGain Expects a `Float`
+     */
+    setDirectionalCone(coneInnerAngle: number, coneOuterAngle: number, coneOuterGain: number): this;
+}

package/types/src/cameras/ArrayCamera.d.ts

@@ -0,0 +1,32 @@
+import { PerspectiveCamera } from "./PerspectiveCamera.js";
+
+/**
+ * {@link ArrayCamera} can be used in order to efficiently render a scene with a predefined set of cameras
+ * @remarks
+ * This is an important performance aspect for rendering VR scenes.
+ * An instance of {@link ArrayCamera} always has an array of sub cameras
+ * It's mandatory to define for each sub camera the `viewport` property which determines the part of the viewport that is rendered with this camera.
+ * @see Example: {@link https://threejs.org/examples/#webgl_camera_array | camera / array }
+ * @see {@link https://threejs.org/docs/index.html#api/en/cameras/ArrayCamera | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/cameras/ArrayCamera.js | Source}
+ */
+export class ArrayCamera extends PerspectiveCamera {
+    /**
+     * An array of cameras.
+     * @param array. Default `[]`.
+     */
+    constructor(cameras?: PerspectiveCamera[]);
+
+    /**
+     * Read-only flag to check if a given object is of type {@link ArrayCamera}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isArrayCamera: true;
+
+    /**
+     * An array of cameras.
+     * @defaultValue `[]`
+     */
+    cameras: PerspectiveCamera[];
+}

package/types/src/cameras/Camera.d.ts

@@ -0,0 +1,74 @@
+import { CoordinateSystem } from "../constants.js";
+import { Layers } from "../core/Layers.js";
+import { Object3D } from "../core/Object3D.js";
+import { Matrix4 } from "../math/Matrix4.js";
+import { Vector3 } from "../math/Vector3.js";
+import { Vector4 } from "../math/Vector4.js";
+
+/**
+ * Abstract base class for cameras
+ * @remarks
+ * This class should always be inherited when you build a new camera.
+ * @see {@link https://threejs.org/docs/index.html#api/en/cameras/Camera | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/cameras/Camera.js | Source}
+ */
+export class Camera extends Object3D {
+    /**
+     * @remarks
+     * Note that this class is not intended to be called directly; you probably want a
+     * {@link THREE.PerspectiveCamera | PerspectiveCamera} or
+     * {@link THREE.OrthographicCamera | OrthographicCamera} instead.
+     */
+    constructor();
+
+    /**
+     * Read-only flag to check if a given object is of type {@link Camera}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isCamera: true;
+
+    /**
+     * @override
+     * @defaultValue `Camera`
+     */
+    override readonly type: string | "Camera";
+
+    /**
+     * @override
+     * The {@link THREE.Layers | layers} that the {@link Camera} is a member of.
+     * @remarks Objects must share at least one layer with the {@link Camera} to be n when the camera's viewpoint is rendered.
+     * @defaultValue `new THREE.Layers()`
+     */
+    override layers: Layers;
+
+    /**
+     * This is the inverse of matrixWorld.
+     * @remarks MatrixWorld contains the Matrix which has the world transform of the {@link Camera} .
+     * @defaultValue {@link THREE.Matrix4 | `new THREE.Matrix4()`}
+     */
+    matrixWorldInverse: Matrix4;
+
+    /**
+     * This is the matrix which contains the projection.
+     * @defaultValue {@link THREE.Matrix4 | `new THREE.Matrix4()`}
+     */
+    projectionMatrix: Matrix4;
+
+    /**
+     * This is the inverse of projectionMatrix.
+     * @defaultValue {@link THREE.Matrix4 | `new THREE.Matrix4()`}
+     */
+    projectionMatrixInverse: Matrix4;
+
+    coordinateSystem: CoordinateSystem;
+
+    viewport?: Vector4;
+
+    /**
+     * Returns a {@link THREE.Vector3 | Vector3} representing the world space direction in which the {@link Camera} is looking.
+     * @remarks Note: A {@link Camera} looks down its local, negative z-axis.
+     * @param target The result will be copied into this Vector3.
+     */
+    getWorldDirection(target: Vector3): Vector3;
+}

package/types/src/cameras/CubeCamera.d.ts

@@ -0,0 +1,68 @@
+import { CoordinateSystem } from "../constants.js";
+import { Object3D } from "../core/Object3D.js";
+import { WebGLCubeRenderTarget } from "../renderers/WebGLCubeRenderTarget.js";
+import { WebGLRenderer } from "../renderers/WebGLRenderer.js";
+
+/**
+ * Creates **6** {@link THREE.PerspectiveCamera | cameras} that render to a {@link THREE.WebGLCubeRenderTarget | WebGLCubeRenderTarget}.
+ * @remarks The cameras are added to the {@link children} array.
+ * @example
+ * ```typescript
+ * // Create cube render target
+ * const cubeRenderTarget = new THREE.WebGLCubeRenderTarget( 128, { generateMipmaps: true, minFilter: THREE.LinearMipmapLinearFilter } );
+ *
+ * // Create cube camera
+ * const cubeCamera = new THREE.CubeCamera( 1, 100000, cubeRenderTarget );
+ * scene.add( cubeCamera );
+ *
+ * // Create car
+ * const chromeMaterial = new THREE.MeshLambertMaterial( { color: 0xffffff, envMap: cubeRenderTarget.texture } );
+ * const car = new THREE.Mesh( carGeometry, chromeMaterial );
+ * scene.add( car );
+ *
+ * // Update the render target cube
+ * car.visible = false;
+ * cubeCamera.position.copy( car.position );
+ * cubeCamera.update( renderer, scene );
+ *
+ * // Render the scene
+ * car.visible = true;
+ * renderer.render( scene, camera );
+ * ```
+ * @see Example: {@link https://threejs.org/examples/#webgl_materials_cubemap_dynamic | materials / cubemap / dynamic }
+ * @see {@link https://threejs.org/docs/index.html#api/en/cameras/CubeCamera | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/cameras/CubeCamera.js | Source}
+ */
+export class CubeCamera extends Object3D {
+    /**
+     * Constructs a {@link CubeCamera} that contains 6 {@link PerspectiveCamera | PerspectiveCameras} that render to a {@link THREE.WebGLCubeRenderTarget | WebGLCubeRenderTarget}.
+     * @param near The near clipping distance.
+     * @param far The far clipping distance.
+     * @param renderTarget The destination cube render target.
+     */
+    constructor(near: number, far: number, renderTarget: WebGLCubeRenderTarget);
+
+    /**
+     * @override
+     * @defaultValue `CubeCamera`
+     */
+    override readonly type: string | "CubeCamera";
+
+    /**
+     * The destination cube render target.
+     */
+    renderTarget: WebGLCubeRenderTarget;
+
+    coordinateSystem: CoordinateSystem;
+
+    activeMipmapLevel: number;
+
+    updateCoordinateSystem(): void;
+
+    /**
+     * Call this to update the {@link CubeCamera.renderTarget | renderTarget}.
+     * @param renderer The current WebGL renderer
+     * @param scene The current scene
+     */
+    update(renderer: WebGLRenderer, scene: Object3D): void;
+}

package/types/src/cameras/OrthographicCamera.d.ts

@@ -0,0 +1,174 @@
+import { JSONMeta, Object3DJSON, Object3DJSONObject } from "../core/Object3D.js";
+import { Camera } from "./Camera.js";
+
+export interface OrthographicCameraJSONObject extends Object3DJSONObject {
+    zoom: number;
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    near: number;
+    far: number;
+
+    view?: {
+        enabled: boolean;
+        fullWidth: number;
+        fullHeight: number;
+        offsetX: number;
+        offsetY: number;
+        width: number;
+        height: number;
+    };
+}
+
+export interface OrthographicCameraJSON extends Object3DJSON {
+    object: OrthographicCameraJSONObject;
+}
+
+/**
+ * Camera that uses {@link https://en.wikipedia.org/wiki/Orthographic_projection | orthographic projection}.
+ * In this projection mode, an object's size in the rendered image stays constant regardless of its distance from the camera.
+ * This can be useful for rendering 2D scenes and UI elements, amongst other things.
+ * @example
+ * ```typescript
+ * const camera = new THREE.OrthographicCamera(width / -2, width / 2, height / 2, height / -2, 1, 1000);
+ * scene.add(camera);
+ * ```
+ * @see Example: {@link https://threejs.org/examples/#webgl_camera | camera }
+ * @see Example: {@link https://threejs.org/examples/#webgl_interactive_cubes_ortho | interactive / cubes / ortho }
+ * @see Example: {@link https://threejs.org/examples/#webgl_materials_cubemap_dynamic | materials / cubemap / dynamic }
+ * @see Example: {@link https://threejs.org/examples/#webgl_postprocessing_advanced | postprocessing / advanced }
+ * @see Example: {@link https://threejs.org/examples/#webgl_postprocessing_dof2 | postprocessing / dof2 }
+ * @see Example: {@link https://threejs.org/examples/#webgl_postprocessing_godrays | postprocessing / godrays }
+ * @see Example: {@link https://threejs.org/examples/#webgl_rtt | rtt }
+ * @see Example: {@link https://threejs.org/examples/#webgl_shaders_tonemapping | shaders / tonemapping }
+ * @see Example: {@link https://threejs.org/examples/#webgl_shadowmap | shadowmap }
+ * @see {@link https://threejs.org/docs/index.html#api/en/cameras/OrthographicCamera | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/cameras/OrthographicCamera.js | Source}
+ */
+export class OrthographicCamera extends Camera {
+    /**
+     * Creates a new {@link OrthographicCamera}.
+     * @remarks Together these define the camera's {@link https://en.wikipedia.org/wiki/Viewing_frustum | viewing frustum}.
+     * @param left Camera frustum left plane. Default `-1`.
+     * @param right Camera frustum right plane. Default `1`.
+     * @param top Camera frustum top plane. Default `1`.
+     * @param bottom Camera frustum bottom plane. Default `-1`.
+     * @param near Camera frustum near plane. Default `0.1`.
+     * @param far Camera frustum far plane. Default `2000`.
+     */
+    constructor(left?: number, right?: number, top?: number, bottom?: number, near?: number, far?: number);
+
+    /**
+     * Read-only flag to check if a given object is of type {@link OrthographicCamera}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isOrthographicCamera: true;
+
+    /**
+     * @override
+     * @defaultValue `OrthographicCamera`
+     */
+    override readonly type: string | "OrthographicCamera";
+
+    /**
+     * Gets or sets the zoom factor of the camera.
+     * @defaultValue `1`
+     */
+    zoom: number;
+
+    /**
+     * Set by {@link setViewOffset | .setViewOffset()}.
+     * @defaultValue `null`
+     */
+    view: null | {
+        enabled: boolean;
+        fullWidth: number;
+        fullHeight: number;
+        offsetX: number;
+        offsetY: number;
+        width: number;
+        height: number;
+    };
+
+    /**
+     * Camera frustum left plane.
+     * @remarks Expects a `Float`
+     * @defaultValue `-1`
+     */
+    left: number;
+
+    /**
+     * Camera frustum right plane.
+     * @remarks Expects a `Float`
+     * @defaultValue `1`
+     */
+    right: number;
+
+    /**
+     * Camera frustum top plane.
+     * @remarks Expects a `Float`
+     * @defaultValue `1`
+     */
+    top: number;
+
+    /**
+     * Camera frustum bottom plane.
+     * @remarks Expects a `Float`.
+     * @defaultValue `-1`
+     */
+    bottom: number;
+
+    /**
+     * Camera frustum near plane.`.
+     * @remarks The valid range is between `0` and the current value of the {@link far | .far} plane.
+     * @remarks Note that, unlike for the {@link THREE.PerspectiveCamera | PerspectiveCamera}, `0` is a valid value for an {@link THREE.OrthographicCamera | OrthographicCamera's} near plane.
+     * @remarks Expects a `Float`
+     * @defaultValue `0.1`
+     */
+    near: number;
+
+    /**
+     * Camera frustum far plane.
+     * @remarks Must be greater than the current value of {@link near | .near} plane.
+     * @remarks Expects a `Float`
+     * @defaultValue `2000`
+     */
+    far: number;
+
+    /**
+     * Updates the camera projection matrix
+     * @remarks Must be called after any change of parameters.
+     */
+    updateProjectionMatrix(): void;
+
+    /**
+     * Sets an offset in a larger {@link https://en.wikipedia.org/wiki/Viewing_frustum | viewing frustum}
+     * @remarks
+     * This is useful for multi-window or multi-monitor/multi-machine setups
+     * For an example on how to use it see {@link PerspectiveCamera.setViewOffset | PerspectiveCamera}.
+     * @see {@link THREE.PerspectiveCamera.setViewOffset | PerspectiveCamera}.
+     * @param fullWidth Full width of multiview setup Expects a `Float`.
+     * @param fullHeight Full height of multiview setup Expects a `Float`.
+     * @param x Horizontal offset of subcamera Expects a `Float`.
+     * @param y Vertical offset of subcamera Expects a `Float`.
+     * @param width Width of subcamera Expects a `Float`.
+     * @param height Height of subcamera Expects a `Float`.
+     */
+    setViewOffset(
+        fullWidth: number,
+        fullHeight: number,
+        offsetX: number,
+        offsetY: number,
+        width: number,
+        height: number,
+    ): void;
+
+    /**
+     * Removes any offset set by the {@link setViewOffset | .setViewOffset} method.
+     */
+    clearViewOffset(): void;
+
+    toJSON(meta?: JSONMeta): OrthographicCameraJSON;
+}