@types/three 0.150.0 → 0.150.1

three/README.md

@@ -8,7 +8,7 @@ This package contains type definitions for three (https://threejs.org/).
 Files were exported from https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/three.
 
 ### Additional Details
- * Last updated: Mon, 27 Mar 2023 18:33:59 GMT
+ * Last updated: Sun, 02 Apr 2023 10:33:00 GMT
  * Dependencies: [@types/fflate](https://npmjs.com/package/@types/fflate), [@types/lil-gui](https://npmjs.com/package/@types/lil-gui), [@types/stats.js](https://npmjs.com/package/@types/stats.js), [@types/webxr](https://npmjs.com/package/@types/webxr)
  * Global values: `THREE`
 

three/examples/jsm/controls/OrbitControls.d.ts

@@ -1,4 +1,4 @@
-import { Camera, MOUSE, MouseButton, TOUCH, TouchCount, Vector3 } from '../../../src/Three';
+import { Camera, MOUSE, TOUCH, Vector3 } from '../../../src/Three';
 
 /**
  * Orbit controls allow the camera to orbit around a target.
@@ -193,13 +193,13 @@ export class OrbitControls {
      * This object contains references to the mouse actions used
      * by the controls.
      */
-    mouseButtons: Partial<{ LEFT: MouseButton; MIDDLE: MouseButton; RIGHT: MouseButton }>;
+    mouseButtons: Partial<{ LEFT: MOUSE; MIDDLE: MOUSE; RIGHT: MOUSE }>;
 
     /**
      * This object contains references to the touch actions used by
      * the controls.
      */
-    touches: Partial<{ ONE: TouchCount; TWO: TouchCount }>;
+    touches: Partial<{ ONE: TOUCH; TWO: TOUCH }>;
 
     /**
      * Used internally by the .saveState and .reset methods.

three/examples/jsm/controls/TrackballControls.d.ts

@@ -1,4 +1,4 @@
-import { Camera, EventDispatcher, MOUSE, MouseButton, Vector3 } from '../../../src/Three';
+import { Camera, EventDispatcher, MOUSE, Vector3 } from '../../../src/Three';
 
 export class TrackballControls extends EventDispatcher {
     constructor(object: Camera, domElement?: HTMLElement);
@@ -21,7 +21,7 @@ export class TrackballControls extends EventDispatcher {
     minDistance: number;
     maxDistance: number;
     keys: string[];
-    mouseButtons: { LEFT: MouseButton; MIDDLE: MouseButton; RIGHT: MouseButton };
+    mouseButtons: { LEFT: MOUSE; MIDDLE: MOUSE; RIGHT: MOUSE };
 
     target: Vector3;
     position0: Vector3;

three/examples/jsm/controls/TransformControls.d.ts

@@ -1,4 +1,4 @@
-import { Object3D, Camera, MOUSE, Raycaster, Mesh, Vector3, Quaternion, MouseButton } from '../../../src/Three';
+import { Object3D, Camera, MOUSE, Raycaster, Mesh, Vector3, Quaternion } from '../../../src/Three';
 
 export class TransformControls extends Object3D {
     constructor(object: Camera, domElement?: HTMLElement);
@@ -21,11 +21,7 @@ export class TransformControls extends Object3D {
     showY: boolean;
     showZ: boolean;
     readonly isTransformControls: true;
-    mouseButtons: {
-        LEFT: MouseButton;
-        MIDDLE: MouseButton;
-        RIGHT: MouseButton;
-    };
+    mouseButtons: { LEFT: MOUSE; MIDDLE: MOUSE; RIGHT: MOUSE };
 
     attach(object: Object3D): this;
     detach(): this;

three/examples/jsm/geometries/TextGeometry.d.ts

@@ -1,37 +1,114 @@
-import { ExtrudeGeometry } from '../../../src/Three';
+import { ExtrudeGeometry, ExtrudeGeometryOptions, Shape } from '../../../src/Three';
 
 import { Font } from '../loaders/FontLoader';
 
-export interface TextGeometryParameters {
+export interface TextGeometryParameters extends ExtrudeGeometryOptions {
     font: Font;
+
+    /**
+     * Size of the text
+     * Expects a `Float`.
+     * @defaultValue `100`
+     */
     size?: number | undefined;
+
+    /**
+     * Thickness to extrude text.
+     * Expects a `Float`.
+     * @defaultValue `50`
+     */
     height?: number | undefined;
+
+    /**
+     * @override
+     * @defaultValue `12`
+     */
     curveSegments?: number | undefined;
+
+    /**
+     * @defaultValue `false`
+     */
     bevelEnabled?: boolean | undefined;
+
+    /**
+     * How deep into text bevel goes.
+     * Expects a `Float`.
+     * @override
+     * @defaultValue `10`
+     */
     bevelThickness?: number | undefined;
+
+    /**
+     * How far from text outline is bevel.
+     * Expects a `Float`.
+     * @override
+     * @defaultValue `8`
+     */
     bevelSize?: number | undefined;
+
+    /**
+     * How far from text outline bevel starts.
+     * Expects a `Float`.
+     * @override
+     * @defaultValue `0`
+     */
     bevelOffset?: number | undefined;
+
+    /**
+     * @override
+     * @defaultValue `3`
+     */
     bevelSegments?: number | undefined;
 }
 
+/**
+ * A class for generating text as a single geometry
+ * @remarks
+ * It is constructed by providing a string of text, and a set of parameters consisting of a loaded font and settings for the geometry's parent {@link THREE.ExtrudeGeometry | ExtrudeGeometry}
+ * See the {@link THREE.FontLoader | FontLoader} page for additional details.
+ * @example
+ * ```typescript
+ * const loader = new FontLoader();
+ * loader.load('fonts/helvetiker_regular.typeface.json', function (font) {
+ *     const geometry = new TextGeometry('Hello three.js!', {
+ *         font: font,
+ *         size: 80,
+ *         height: 5,
+ *         curveSegments: 12,
+ *         bevelEnabled: true,
+ *         bevelThickness: 10,
+ *         bevelSize: 8,
+ *         bevelOffset: 0,
+ *         bevelSegments: 5
+ *     });
+ * });
+ * ```
+ * @see Example: {@link https://threejs.org/examples/#webgl_geometry_text | geometry / text }
+ * @see {@link https://threejs.org/docs/index.html#api/en/C:/rafaelsc/Source/threejs/three.js/docs/examples/en/geometries/TextGeometry | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/examples/jsm/geometries/TextGeometry.js | Source}
+ */
 export class TextGeometry extends ExtrudeGeometry {
     /**
-     * @default 'TextGeometry'
+     * Create a new instance of {@link TextGeometry}
+     * @param text The text that needs to be shown.
+     * @param parameters Object that can contain the following parameters. @see {@link TextGeometryParameters} for defaults.
      */
-    type: string;
+    constructor(text: string, parameters?: TextGeometryParameters);
 
-    constructor(text: string, parameters: TextGeometryParameters);
+    /**
+     * A Read-only _string_ to check if `this` object type.
+     * @remarks Sub-classes will update this value.
+     * @defaultValue `TextGeometry`
+     */
+    override readonly type: string | 'TextGeometry';
 
-    parameters: {
-        font: Font;
-        size: number;
-        height: number;
-        curveSegments: number;
-        bevelEnabled: boolean;
-        bevelThickness: number;
-        bevelSize: number;
-        bevelOffset: number;
-        bevelSegments: number;
+    /**
+     * An object with a property for each of the constructor parameters.
+     * @remarks Any modification after instantiation does not change the geometry.
+     */
+    readonly parameters: {
+        readonly shapes: Shape | Shape[];
+        readonly options: TextGeometryParameters;
     };
 }
 

three/examples/jsm/loaders/EXRLoader.d.ts

@@ -1,11 +1,12 @@
-import { LoadingManager, DataTextureLoader, TextureDataType, PixelFormat } from '../../../src/Three';
+import { DataTextureLoader, LoadingManager, PixelFormat, TextureDataType, TextureEncoding } from '../../../src/Three';
 
 export interface EXR {
     header: object;
     width: number;
     height: number;
-    data: Float32Array;
+    data: Float32Array | Uint16Array;
     format: PixelFormat;
+    encoding: TextureEncoding;
     type: TextureDataType;
 }
 

three/examples/jsm/misc/GPUComputationRenderer.d.ts

@@ -9,6 +9,8 @@ import {
     TextureFilter,
     TextureDataType,
     IUniform,
+    MagnificationTextureFilter,
+    MinificationTextureFilter,
 } from '../../../src/Three';
 
 export interface Variable {
@@ -43,8 +45,8 @@ export class GPUComputationRenderer {
         sizeYTexture: number,
         wrapS: Wrapping,
         wrapT: number,
-        minFilter: TextureFilter,
-        magFilter: TextureFilter,
+        minFilter: MinificationTextureFilter,
+        magFilter: MagnificationTextureFilter,
     ): WebGLRenderTarget;
     createTexture(): DataTexture;
     renderTexture(input: Texture, output: Texture): void;

three/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@types/three",
-    "version": "0.150.0",
+    "version": "0.150.1",
     "description": "TypeScript definitions for three",
     "homepage": "https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/three",
     "license": "MIT",
@@ -30,7 +30,7 @@
         "fflate": "~0.6.9",
         "lil-gui": "~0.17.0"
     },
-    "typesPublisherContentHash": "05e4984f22e82431c725369b78c3643e5b4e94508994b1904e74a77e269b9617",
+    "typesPublisherContentHash": "c7ff42de666a86340964d8f399b86ddfa5b1abfa546b40ede1e3385f993d5903",
     "typeScriptVersion": "4.4",
     "exports": {
         ".": {

three/src/audio/Audio.d.ts

@@ -4,22 +4,71 @@ import { AudioContext } from './AudioContext';
 
 // Extras / Audio /////////////////////////////////////////////////////////////////////
 
+/**
+ * Create a non-positional ( global ) {@link Audio} object.
+ * This uses the {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API | Web {@link Audio} API}.
+ * @example
+ * ```typescript
+ * // create an AudioListener and add it to the camera
+ * const listener = new THREE.AudioListener();
+ * camera.add(listener);
+ * // create a global {@link Audio} source
+ * const sound = new THREE.Audio(listener);
+ * // load a sound and set it as the {@link 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_visualizer | webaudio / visualizer }
+ * @see {@link https://threejs.org/docs/index.html#api/en/audio/Audio | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/audio/Audio.js | Source}
+ */
 export class Audio<NodeType extends AudioNode = GainNode> extends Object3D {
+    /**
+     * Create a new instance of {@link Audio}
+     * @param listener (required) {@link AudioListener | AudioListener} instance.
+     */
     constructor(listener: AudioListener);
-    type: 'Audio';
 
+    /**
+     * A Read-only _string_ to check if `this` object type.
+     * @remarks Sub-classes will update this value.
+     * @defaultValue `Audio`
+     */
+    readonly type: string | 'Audio';
+
+    /**
+     * A reference to the listener object of this audio.
+     */
     listener: AudioListener;
+
+    /**
+     * The {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioContext | AudioContext} of the {@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;
 
     /**
-     * @default false
+     * Whether to start playback automatically.
+     * @defaultValue `false`
      */
     autoplay: boolean;
-    buffer: null | AudioBuffer;
+
+    buffer: AudioBuffer | null;
 
     /**
-     * @default 0
+     * Modify pitch, measured in cents. +/- 100 is a semitone. +/- 1200 is an octave.
+     * @defaultValue `0`
      */
     detune: number;
 
@@ -39,68 +88,183 @@ export class Audio<NodeType extends AudioNode = GainNode> extends Object3D {
     loopEnd: number;
 
     /**
-     * @default 0
+     * An offset to the time within the {@link Audio} buffer that playback should begin.
+     * Same as the {@link Audio.offset | offset} parameter of {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode/start | AudioBufferSourceNode.start()}.
+     * @defaultValue `0`
      */
     offset: number;
 
     /**
-     * @default undefined
+     * Overrides the duration of the audio. Same as the {@link Audio.duration | duration} parameter of
+     * {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode/start | AudioBufferSourceNode.start()}.
+     * @defaultValue `undefined` _to play the whole buffer_.
      */
     duration: number | undefined;
 
     /**
-     * @default 1
+     * Speed of playback.
+     * @defaultValue `1`
      */
     playbackRate: number;
 
     /**
-     * @default false
+     * Whether the {@link Audio} is currently playing.
+     * @defaultValue `false`
      */
     isPlaying: boolean;
 
     /**
-     * @default true
+     * Whether playback can be controlled using the {@link Audio.play | play}(), {@link Audio.pause | pause}() etc. methods.
+     * @defaultValue `true`
      */
     hasPlaybackControl: boolean;
 
     /**
-     * @default 'empty'
+     * Type of the {@link Audio} source.
+     * @defaultValue 'empty'.
      */
     sourceType: string;
-    source: null | AudioBufferSourceNode;
 
     /**
-     * @default []
+     * An {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode | AudioBufferSourceNode} created using
+     * {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioContext/createBufferSource | AudioContext.createBufferSource()}.
+     */
+    source: AudioBufferSourceNode | null;
+
+    /**
+     * Represents an array of {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioNode | AudioNodes}.
+     * Can be used to apply a variety of low-order filters to create more complex sound effects.
+     * In most cases, the array contains instances of {@link https://developer.mozilla.org/en-US/docs/Web/API/BiquadFilterNode | BiquadFilterNodes}.
+     * Filters are set via {@link THREE.Audio.setFilter | Audio.setFilter} or {@link THREE.Audio.setFilters | Audio.setFilters}.
+     * @defaultValue `[]`
      */
     filters: AudioNode[];
 
+    /**
+     * Return the {@link Audio.gain | gainNode}.
+     */
     getOutput(): NodeType;
+
+    /**
+     * Setup the {@link Audio.source | source} to the audioBuffer, and sets {@link Audio.sourceType | sourceType} to 'audioNode'.
+     * @remarks Also sets {@link Audio.hasPlaybackControl | hasPlaybackControl} to false.
+     */
     setNodeSource(audioNode: AudioBufferSourceNode): this;
+
+    /**
+     * Applies the given object of type {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLMediaElement | HTMLMediaElement} as the source of this audio.
+     * @remarks Also sets {@link Audio.hasPlaybackControl | hasPlaybackControl} to false.
+     */
     setMediaElementSource(mediaElement: HTMLMediaElement): this;
+
+    /**
+     * Applies the given object of type {@link https://developer.mozilla.org/en-US/docs/Web/API/MediaStream | MediaStream} as the source of this audio.
+     * @remarks Also sets {@link Audio.hasPlaybackControl | hasPlaybackControl} to false.
+     */
     setMediaStreamSource(mediaStream: MediaStream): this;
+
+    /**
+     * Setup the {@link Audio.source | source} to the audioBuffer, and sets {@link Audio.sourceType | sourceType} to 'buffer'.
+     * @remarks If {@link Audio.autoplay | autoplay}, also starts playback.
+     */
     setBuffer(audioBuffer: AudioBuffer): this;
+
+    /**
+     * If {@link Audio.hasPlaybackControl | hasPlaybackControl} is true, starts playback.
+     */
     play(delay?: number): this;
-    onEnded(): void;
+    /**
+     * If {@link Audio.hasPlaybackControl | hasPlaybackControl} is true, pauses playback.
+     */
     pause(): this;
+    /**
+     * If {@link Audio.hasPlaybackControl | hasPlaybackControl} is enabled, stops playback.
+     */
     stop(): this;
+
+    /**
+     * Called automatically when playback finished.
+     */
+    onEnded(): void;
+
+    /**
+     * Connect to the {@link THREE.Audio.source | Audio.source}
+     * @remarks This is used internally on initialisation and when setting / removing filters.
+     */
     connect(): this;
+    /**
+     * Disconnect from the {@link THREE.Audio.source | Audio.source}
+     * @remarks This is used internally when setting / removing filters.
+     */
     disconnect(): this;
-    setDetune(value: number): this;
+
+    /**
+     * Returns the detuning of oscillation in cents.
+     */
     getDetune(): number;
-    getFilters(): AudioNode[];
-    setFilters(value: AudioNode[]): this;
+    /**
+     * Defines the detuning of oscillation in cents.
+     * @param value Expects a `Float`
+     */
+    setDetune(value: number): this;
+
+    /**
+     * Returns the first element of the {@link Audio.filters | filters} array.
+     */
     getFilter(): AudioNode;
+    /**
+     * Applies a single filter node to the audio.
+     */
     setFilter(filter: AudioNode): this;
-    setPlaybackRate(value: number): this;
+
+    /**
+     * Returns the {@link Audio.filters | filters} array.
+     */
+    getFilters(): AudioNode[];
+    /**
+     * Applies an array of filter nodes to the audio.
+     * @param value Arrays of filters.
+     */
+    setFilters(value: AudioNode[]): this;
+
+    /**
+     * Return the value of {@link Audio.playbackRate | playbackRate}.
+     */
     getPlaybackRate(): number;
+    /**
+     * If {@link Audio.hasPlaybackControl | hasPlaybackControl} is enabled, set the {@link Audio.playbackRate | playbackRate} to `value`.
+     * @param value Expects a `Float`
+     */
+    setPlaybackRate(value: number): this;
+
+    /**
+     * Return the value of {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode/loop | source.loop} (whether playback should loop).
+     */
     getLoop(): boolean;
+    /**
+     * Set {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode/loop | source.loop} to `value` (whether playback should loop).
+     * @param value
+     */
     setLoop(value: boolean): this;
+
+    /**
+     * Set {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode/loopStart | source.loopStart} to `value`.
+     * @param value Expects a `Float`
+     */
     setLoopStart(value: number): this;
+    /**
+     * Set {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioBufferSourceNode/loopEnd | source.loopEnd} to `value`.
+     * @param value Expects a `Float`
+     */
     setLoopEnd(value: number): this;
+
+    /**
+     * Return the current volume.
+     */
     getVolume(): number;
-    setVolume(value: number): this;
     /**
-     * @deprecated Use {@link AudioLoader} instead.
+     * Set the volume.
+     * @param value Expects a `Float`
      */
-    load(file: string): Audio;
+    setVolume(value: number): this;
 }

three/src/audio/AudioAnalyser.d.ts

@@ -1,20 +1,58 @@
 import { Audio } from './Audio';
 
+/**
+ * Create a {@link AudioAnalyser} object, which uses an {@link https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode | AnalyserNode} to analyse audio data.
+ * 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 an 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();
+ * });
+ * // create an AudioAnalyser, passing in the sound and desired fftSize
+ * const analyser = new THREE.AudioAnalyser(sound, 32);
+ * // get the average frequency of the sound
+ * const data = analyser.getAverageFrequency();
+ * ```
+ * @see Example: {@link https://threejs.org/examples/#webaudio_sandbox | webaudio / sandbox }
+ * @see Example: {@link https://threejs.org/examples/#webaudio_visualizer | webaudio / visualizer }
+ * @see {@link https://threejs.org/docs/index.html#api/en/audio/AudioAnalyser | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/audio/AudioAnalyser.js | Source}
+ */
 export class AudioAnalyser {
     /**
+     * Create a new {@link {@link AudioAnalyser} | AudioAnalyser}.
      * @param audio
-     * @param [fftSize=2048]
+     * @param fftSize See {@link https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/fftSize | AnalyserNode.fftSize }. Expects a `unsigned integer`. Default `2048`.
      */
     constructor(audio: Audio<AudioNode>, fftSize?: number);
 
+    /**
+     * An {@link https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode | AnalyserNode} used to analyze audio.
+     */
     analyser: AnalyserNode;
+
+    /**
+     * A Uint8Array with size determined by {@link https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/frequencyBinCount | analyser.frequencyBinCount} used to hold analysis data.
+     */
     data: Uint8Array;
 
+    /**
+     * Uses the Web Audio's {@link https://developer.mozilla.org/en-US/docs/Web/API/AnalyserNode/getByteFrequencyData | getByteFrequencyData} method
+     */
     getFrequencyData(): Uint8Array;
-    getAverageFrequency(): number;
 
     /**
-     * @deprecated Use {@link AudioAnalyser#getFrequencyData .getFrequencyData()} instead.
+     * Get the average of the frequencies returned by the {@link AudioAnalyser.getFrequencyData | getFrequencyData} method.
      */
-    getData(file: any): any;
+    getAverageFrequency(): number;
 }

three/src/audio/AudioContext.d.ts

@@ -1,8 +1,19 @@
 /**
- * see {@link https://github.com/mrdoob/three.js/blob/master/src/audio/AudioContext.js|src/audio/AudioContext.js}
+ * This contains methods for setting up an {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioContext | AudioContext}.
+ * Used internally by the {@link AudioListener | AudioListener} and {@link AudioLoader | AudioLoader} classes.
+ * This uses the {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API | Web Audio API}.
+ * @see {@link https://threejs.org/docs/index.html#api/en/audio/AudioContext | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/audio/AudioContext.js | Source}
  */
 export namespace AudioContext {
+    /**
+     * Return the value of the variable `context` in the outer scope, if defined, otherwise set it to a new {@link https://developer.mozilla.org/en-US/docs/Web/API/AudioContext | AudioContext}.
+     */
     function getContext(): AudioContext;
 
+    /**
+     * Set the variable `context` in the outer scope to `value`.
+     * @param value
+     */
     function setContext(context: AudioContext): void;
 }