@types/three 0.181.0 → 0.183.0

three/src/audio/AudioListener.d.ts

@@ -1,96 +1,75 @@
 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 constructor 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}
+ * The class represents a virtual listener of the all positional and non-positional audio effects
+ * in the scene. A three.js application usually creates a single listener. It is a mandatory
+ * constructor parameter for audios entities like {@link Audio} and {@link 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.
  */
 export class AudioListener extends Object3D {
     /**
-     * Create a new AudioListener.
+     * The native audio context.
      */
-    constructor();
-
+    readonly context: AudioContext;
     /**
-     * A Read-only _string_ to check if `this` object type.
-     * @remarks Sub-classes will update this value.
-     * @defaultValue `AudioListener`
+     * The gain node used for volume control.
      */
-    readonly type: string | "AudioListener";
-
+    readonly gain: GainNode;
     /**
-     * The {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioContext | AudioContext} of the {@link {@link AudioListener} | listener} given in the constructor.
+     * An optional filter.
+     *
+     * Defined via {@link AudioListener#setFilter}.
+     *
+     * @default null
      */
-    context: AudioContext;
-
+    readonly filter: AudioNode | null;
     /**
-     * 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()}.
+     * Time delta values required for `linearRampToValueAtTime()` usage.
+     *
+     * @default 0
      */
-    gain: GainNode;
-
-    /**
-     * @defaultValue `null`
-     */
-    filter: AudioNode;
-
+    readonly timeDelta: number;
     /**
-     * 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}.
+     * Returns the listener's input node.
+     *
+     * This method is used by other audio nodes to connect to this listener.
+     *
+     * @return {GainNode} The input node.
      */
     getInput(): GainNode;
     /**
-     * Set the {@link AudioListener.filter | filter} property to `null`.
+     * Removes the current filter from this listener.
+     *
+     * @return {AudioListener} A reference to this listener.
      */
     removeFilter(): this;
-
     /**
-     * Returns the value of the {@link AudioListener.filter | filter} property.
+     * Returns the current set filter.
+     *
+     * @return {?AudioNode} The filter.
      */
-    getFilter(): AudioNode;
+    getFilter(): AudioNode | null;
     /**
-     * Set the {@link AudioListener.filter | filter} property to `value`.
-     * @param value
+     * Sets the given filter to this listener.
+     *
+     * @param {AudioNode} value - The filter to set.
+     * @return {AudioListener} A reference to this listener.
      */
     setFilter(value: AudioNode): this;
-
     /**
-     * Return the volume.
+     * Returns the applications master volume.
+     *
+     * @return {number} The master volume.
      */
     getMasterVolume(): number;
-
     /**
-     * Set the volume.
-     * @param value
+     * Sets the applications master volume. This volume setting affects
+     * all audio nodes in the scene.
+     *
+     * @param {number} value - The master volume to set.
+     * @return {AudioListener} A reference to this listener.
      */
     setMasterVolume(value: number): this;
 }

three/src/audio/PositionalAudio.d.ts

@@ -1,101 +1,108 @@
 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
+ * Represents a positional audio object.
+ *
+ * ```js
  * // 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
+ * camera.add( listener );
+ *
+ * // create the PositionalAudio object (passing in the listener)
+ * const sound = new THREE.PositionalAudio( listener );
+ *
+ * // load a sound and set it as the PositionalAudio object's buffer
  * const audioLoader = new THREE.AudioLoader();
- * audioLoader.load('sounds/song.ogg', function (buffer) {
- *     sound.setBuffer(buffer);
- *     sound.setRefDistance(20);
- *     sound.play();
+ * 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);
+ * 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}
+ * mesh.add( sound );
  */
 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}.
+     * The panner node represents the location, direction, and behavior of an audio
+     * source in 3D space.
      */
-    getOutput(): PannerNode;
-
+    readonly panner: PannerNode;
+    disconnect(): this;
     /**
-     * Returns the value of {@link https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/refDistance | panner.refDistance}.
+     * Returns the current reference distance.
+     *
+     * @return {number} The reference distance.
      */
     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`
+     * Defines the reference distance for reducing volume as the audio source moves
+     * further from the listener – i.e. the distance at which the volume reduction
+     * starts taking effect.
+     *
+     * @param {number} value - The reference distance to set.
+     * @return {PositionalAudio} A reference to this instance.
      */
     setRefDistance(value: number): this;
-
     /**
-     * Returns the value of {@link https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/rolloffFactor | panner.rolloffFactor}.
+     * Returns the current rolloff factor.
+     *
+     * @return {number} The rolloff factor.
      */
     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`
+     * Defines how quickly the volume is reduced as the source moves away from the listener.
+     *
+     * @param {number} value - The rolloff factor.
+     * @return {PositionalAudio} A reference to this instance.
      */
     setRolloffFactor(value: number): this;
-
     /**
-     * Returns the value of {@link https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/distanceModel | panner.distanceModel}.
+     * Returns the current distance model.
+     *
+     * @return {('linear'|'inverse'|'exponential')} The distance model.
      */
-    getDistanceModel(): string;
+    getDistanceModel(): "linear" | "inverse" | "exponential";
     /**
-     * Sets the value of {@link https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/distanceModel | panner.distanceModel}.
-     * @param value
+     * Defines which algorithm to use to reduce the volume of the audio source
+     * as it moves away from the listener.
+     *
+     * Read [the spec](https://www.w3.org/TR/webaudio-1.1/#enumdef-distancemodeltype)
+     * for more details.
+     *
+     * @param {('linear'|'inverse'|'exponential')} value - The distance model to set.
+     * @return {PositionalAudio} A reference to this instance.
      */
-    setDistanceModel(value: string): this;
-
+    setDistanceModel(value: "linear" | "inverse" | "exponential"): this;
     /**
-     * Returns the value of {@link https://developer.mozilla.org/en-US/docs/Web/API/PannerNode/maxDistance | panner.maxDistance}.
+     * Returns the current max distance.
+     *
+     * @return {number} The max distance.
      */
     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`
+     * Defines the maximum distance between the audio source and the listener,
+     * after which the volume is not reduced any further.
+     *
+     * This value is used only by the `linear` distance model.
+     *
+     * @param {number} value - The max distance.
+     * @return {PositionalAudio} A reference to this instance.
      */
     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`
+     * Sets the directional cone in which the audio can be listened.
+     *
+     * @param {number} coneInnerAngle - An angle, in degrees, of a cone inside of which there will be no volume reduction.
+     * @param {number} coneOuterAngle - An angle, in degrees, of a cone outside of which the volume will be reduced by a constant value, defined by the `coneOuterGain` parameter.
+     * @param {number} coneOuterGain - The amount of volume reduction outside the cone defined by the `coneOuterAngle`. When set to `0`, no sound can be heard.
+     * @return {PositionalAudio} A reference to this instance.
      */
     setDirectionalCone(coneInnerAngle: number, coneOuterAngle: number, coneOuterGain: number): this;
 }

three/src/cameras/ArrayCamera.d.ts

@@ -1,38 +1,35 @@
 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}
+ * This type of camera can be used in order to efficiently render a scene with a
+ * predefined set of cameras. This is an important performance aspect for
+ * rendering VR scenes.
+ *
+ * An instance of `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.
  */
 export class ArrayCamera extends PerspectiveCamera {
     /**
-     * Read-only flag to check if a given object is of type {@link ArrayCamera}.
-     * @remarks This is a _constant_ value
-     * @defaultValue `true`
+     * Constructs a new array camera.
+     *
+     * @param {Array<PerspectiveCamera>} [array=[]] - An array of perspective sub cameras.
      */
-    readonly isArrayCamera: true;
-
+    constructor(array?: PerspectiveCamera[]);
     /**
-     * Whether this camera is used with multiview rendering or not.
+     * This flag can be used for type testing.
+     *
+     * @default true
      */
-    isMultiViewCamera: boolean;
-
+    readonly isArrayCamera: boolean;
     /**
-     * An array of cameras.
-     * @defaultValue `[]`
+     * Whether this camera is used with multiview rendering or not.
+     *
+     * @default false
      */
-    cameras: PerspectiveCamera[];
-
-    index: number;
-
+    readonly isMultiViewCamera: boolean;
     /**
-     * An array of cameras.
+     * An array of perspective sub cameras.
      */
-    constructor(cameras?: PerspectiveCamera[]);
+    cameras: PerspectiveCamera[];
 }

three/src/cameras/Camera.d.ts

@@ -1,81 +1,42 @@
 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}
+ * Abstract base class for cameras. This class should always be inherited
+ * when you build a new camera.
  */
 export class Camera extends Object3D {
     /**
-     * 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 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()`
+     * This flag can be used for type testing.
+     *
+     * @default true
      */
-    override layers: Layers;
-
+    readonly isCamera: boolean;
     /**
-     * This is the inverse of matrixWorld.
-     * @remarks MatrixWorld contains the Matrix which has the world transform of the {@link Camera} .
-     * @defaultValue {@link Matrix4 | `new THREE.Matrix4()`}
+     * The inverse of the camera's world matrix.
      */
     matrixWorldInverse: Matrix4;
-
     /**
-     * This is the matrix which contains the projection.
-     * @defaultValue {@link Matrix4 | `new THREE.Matrix4()`}
+     * The camera's projection matrix.
      */
     projectionMatrix: Matrix4;
-
     /**
-     * This is the inverse of projectionMatrix.
-     * @defaultValue {@link Matrix4 | `new THREE.Matrix4()`}
+     * The inverse of the camera's projection matrix.
      */
     projectionMatrixInverse: Matrix4;
-
-    coordinateSystem: CoordinateSystem;
-
-    viewport?: Vector4;
-
     /**
-     * @remarks
-     * Note that this class is not intended to be called directly; you probably want a
-     * {@link PerspectiveCamera | PerspectiveCamera} or
-     * {@link OrthographicCamera | OrthographicCamera} instead.
+     * The coordinate system in which the camera is used.
      */
-    constructor();
-
+    coordinateSystem: CoordinateSystem;
+    viewport?: Vector4;
     /**
      * The flag that indicates whether the camera uses a reversed depth buffer.
      *
      * @default false
      */
     get reversedDepth(): boolean;
-
-    /**
-     * Returns a {@link 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;
+    copy(source: Camera, recursive?: boolean): this;
+    clone(): this;
 }

three/src/cameras/CubeCamera.d.ts

@@ -1,6 +1,7 @@
 import { CoordinateSystem } from "../constants.js";
 import { Object3D } from "../core/Object3D.js";
 import { RenderTarget } from "../core/RenderTarget.js";
+import CubeRenderTarget from "../renderers/common/CubeRenderTarget.js";
 import { WebGLCubeRenderTarget } from "../renderers/WebGLCubeRenderTarget.js";
 import { Camera } from "./Camera.js";
 
@@ -21,12 +22,13 @@ export interface CubeCameraRenderer {
 }
 
 /**
- * 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
+ * A special type of camera that is positioned in 3D space to render its surroundings into a
+ * cube render target. The render target can then be used as an environment map for rendering
+ * realtime reflections in your scene.
+ *
+ * ```js
  * // Create cube render target
- * const cubeRenderTarget = new THREE.WebGLCubeRenderTarget( 128, { generateMipmaps: true, minFilter: THREE.LinearMipmapLinearFilter } );
+ * const cubeRenderTarget = new THREE.WebGLCubeRenderTarget( 256, { generateMipmaps: true, minFilter: THREE.LinearMipmapLinearFilter } );
  *
  * // Create cube camera
  * const cubeCamera = new THREE.CubeCamera( 1, 100000, cubeRenderTarget );
@@ -46,40 +48,42 @@ export interface CubeCameraRenderer {
  * 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.
+     * Constructs a new cube camera.
+     *
+     * @param {number} near - The camera's near plane.
+     * @param {number} far - The camera's far plane.
+     * @param {WebGLCubeRenderTarget} renderTarget - The cube render target.
      */
-    constructor(near: number, far: number, renderTarget: WebGLCubeRenderTarget);
-
+    constructor(near: number, far: number, renderTarget: WebGLCubeRenderTarget | CubeRenderTarget);
     /**
-     * @override
-     * @defaultValue `CubeCamera`
+     * A reference to the cube render target.
      */
-    override readonly type: string | "CubeCamera";
-
+    renderTarget: WebGLCubeRenderTarget;
     /**
-     * The destination cube render target.
+     * The current active coordinate system.
+     *
+     * @default null
+     */
+    coordinateSystem: CoordinateSystem | null;
+    /**
+     * The current active mipmap level
+     *
+     * @default 0
      */
-    renderTarget: WebGLCubeRenderTarget;
-
-    coordinateSystem: CoordinateSystem;
-
     activeMipmapLevel: number;
-
+    /**
+     * Must be called when the coordinate system of the cube camera is changed.
+     */
     updateCoordinateSystem(): void;
-
     /**
-     * Call this to update the {@link CubeCamera.renderTarget | renderTarget}.
-     * @param renderer The current WebGL renderer
-     * @param scene The current scene
+     * Calling this method will render the given scene with the given renderer
+     * into the cube render target of the camera.
+     *
+     * @param {(Renderer|WebGLRenderer)} renderer - The renderer.
+     * @param {Scene} scene - The scene to render.
      */
     update(renderer: CubeCameraRenderer, scene: Object3D): void;
 }