@needle-tools/three 0.169.12 → 0.169.13

package/types/src/animation/AnimationUtils.d.ts

@@ -0,0 +1,60 @@
+import { AnimationClip } from "./AnimationClip.js";
+
+declare function convertArray(array: any, type: any, forceClone: boolean): any;
+
+declare function isTypedArray(object: any): boolean;
+
+declare function getKeyframeOrder(times: number[]): number[];
+
+declare function sortedArray(values: any[], stride: number, order: number[]): any[];
+
+declare function flattenJSON(jsonKeys: string[], times: any[], values: any[], valuePropertyName: string): void;
+
+/**
+ * @param sourceClip
+ * @param name
+ * @param startFrame
+ * @param endFrame
+ * @param [fps=30]
+ */
+declare function subclip(
+    sourceClip: AnimationClip,
+    name: string,
+    startFrame: number,
+    endFrame: number,
+    fps?: number,
+): AnimationClip;
+
+/**
+ * @param targetClip
+ * @param [referenceFrame=0]
+ * @param [referenceClip=targetClip]
+ * @param [fps=30]
+ */
+declare function makeClipAdditive(
+    targetClip: AnimationClip,
+    referenceFrame?: number,
+    referenceClip?: AnimationClip,
+    fps?: number,
+): AnimationClip;
+
+declare const AnimationUtils: {
+    convertArray: typeof convertArray;
+    isTypedArray: typeof isTypedArray;
+    getKeyframeOrder: typeof getKeyframeOrder;
+    sortedArray: typeof sortedArray;
+    flattenJSON: typeof flattenJSON;
+    subclip: typeof subclip;
+    makeClipAdditive: typeof makeClipAdditive;
+};
+
+export {
+    AnimationUtils,
+    convertArray,
+    flattenJSON,
+    getKeyframeOrder,
+    isTypedArray,
+    makeClipAdditive,
+    sortedArray,
+    subclip,
+};

package/types/src/animation/KeyframeTrack.d.ts

@@ -0,0 +1,55 @@
+import { InterpolationModes } from "../constants.js";
+import { Interpolant } from "../math/Interpolant.js";
+import { CubicInterpolant } from "../math/interpolants/CubicInterpolant.js";
+import { DiscreteInterpolant } from "../math/interpolants/DiscreteInterpolant.js";
+import { LinearInterpolant } from "../math/interpolants/LinearInterpolant.js";
+
+export interface KeyframeTrackJSON {
+    name: string;
+    times: number[];
+    values: number[];
+    interpolation?: InterpolationModes;
+    type: string;
+}
+
+export class KeyframeTrack {
+    /**
+     * @param name
+     * @param times
+     * @param values
+     * @param [interpolation=THREE.InterpolateLinear]
+     */
+    constructor(name: string, times: ArrayLike<number>, values: ArrayLike<any>, interpolation?: InterpolationModes);
+
+    name: string;
+    times: Float32Array;
+    values: Float32Array;
+
+    ValueTypeName: string;
+    TimeBufferType: Float32Array;
+    ValueBufferType: Float32Array;
+
+    /**
+     * @default THREE.InterpolateLinear
+     */
+    DefaultInterpolation: InterpolationModes;
+
+    InterpolantFactoryMethodDiscrete(result: any): DiscreteInterpolant;
+    InterpolantFactoryMethodLinear(result: any): LinearInterpolant;
+    InterpolantFactoryMethodSmooth(result: any): CubicInterpolant;
+
+    setInterpolation(interpolation: InterpolationModes): KeyframeTrack;
+    getInterpolation(): InterpolationModes;
+    createInterpolant(): Interpolant;
+
+    getValueSize(): number;
+
+    shift(timeOffset: number): KeyframeTrack;
+    scale(timeScale: number): KeyframeTrack;
+    trim(startTime: number, endTime: number): KeyframeTrack;
+    validate(): boolean;
+    optimize(): KeyframeTrack;
+    clone(): this;
+
+    static toJSON(track: KeyframeTrack): KeyframeTrackJSON;
+}

package/types/src/animation/PropertyBinding.d.ts

@@ -0,0 +1,43 @@
+export interface ParseTrackNameResults {
+    nodeName: string;
+    objectName: string;
+    objectIndex: string;
+    propertyName: string;
+    propertyIndex: string;
+}
+
+declare class Composite {
+    constructor(targetGroup: any, path: any, parsedPath?: any);
+
+    getValue(array: any, offset: number): any;
+    setValue(array: any, offset: number): void;
+    bind(): void;
+    unbind(): void;
+}
+
+declare class PropertyBinding {
+    constructor(rootNode: any, path: string, parsedPath?: any);
+
+    path: string;
+    parsedPath: any;
+    node: any;
+    rootNode: any;
+
+    getValue(targetArray: any, offset: number): any;
+    setValue(sourceArray: any, offset: number): void;
+    bind(): void;
+    unbind(): void;
+
+    BindingType: { [bindingType: string]: number };
+    Versioning: { [versioning: string]: number };
+
+    GetterByBindingType: Array<() => void>;
+    SetterByBindingTypeAndVersioning: Array<Array<() => void>>;
+
+    static create(root: any, path: any, parsedPath?: any): PropertyBinding | Composite;
+    static sanitizeNodeName(name: string): string;
+    static parseTrackName(trackName: string): ParseTrackNameResults;
+    static findNode(root: any, nodeName: string): any;
+}
+
+export { PropertyBinding };

package/types/src/animation/PropertyMixer.d.ts

@@ -0,0 +1,17 @@
+export class PropertyMixer {
+    constructor(binding: any, typeName: string, valueSize: number);
+
+    binding: any;
+    valueSize: number;
+    buffer: any;
+    cumulativeWeight: number;
+    cumulativeWeightAdditive: number;
+    useCount: number;
+    referenceCount: number;
+
+    accumulate(accuIndex: number, weight: number): void;
+    accumulateAdditive(weight: number): void;
+    apply(accuIndex: number): void;
+    saveOriginalState(): void;
+    restoreOriginalState(): void;
+}

package/types/src/animation/tracks/BooleanKeyframeTrack.d.ts

@@ -0,0 +1,10 @@
+import { KeyframeTrack } from "../KeyframeTrack.js";
+
+export class BooleanKeyframeTrack extends KeyframeTrack {
+    constructor(name: string, times: ArrayLike<number>, values: ArrayLike<any>);
+
+    /**
+     * @default 'bool'
+     */
+    ValueTypeName: string;
+}

package/types/src/animation/tracks/ColorKeyframeTrack.d.ts

@@ -0,0 +1,11 @@
+import { InterpolationModes } from "../../constants.js";
+import { KeyframeTrack } from "../KeyframeTrack.js";
+
+export class ColorKeyframeTrack extends KeyframeTrack {
+    constructor(name: string, times: ArrayLike<number>, values: ArrayLike<number>, interpolation?: InterpolationModes);
+
+    /**
+     * @default 'color'
+     */
+    ValueTypeName: string;
+}

package/types/src/animation/tracks/NumberKeyframeTrack.d.ts

@@ -0,0 +1,11 @@
+import { InterpolationModes } from "../../constants.js";
+import { KeyframeTrack } from "../KeyframeTrack.js";
+
+export class NumberKeyframeTrack extends KeyframeTrack {
+    constructor(name: string, times: ArrayLike<number>, values: ArrayLike<number>, interpolation?: InterpolationModes);
+
+    /**
+     * @default 'number'
+     */
+    ValueTypeName: string;
+}

package/types/src/animation/tracks/QuaternionKeyframeTrack.d.ts

@@ -0,0 +1,11 @@
+import { InterpolationModes } from "../../constants.js";
+import { KeyframeTrack } from "../KeyframeTrack.js";
+
+export class QuaternionKeyframeTrack extends KeyframeTrack {
+    constructor(name: string, times: ArrayLike<number>, values: ArrayLike<number>, interpolation?: InterpolationModes);
+
+    /**
+     * @default 'quaternion'
+     */
+    ValueTypeName: string;
+}

package/types/src/animation/tracks/StringKeyframeTrack.d.ts

@@ -0,0 +1,10 @@
+import { KeyframeTrack } from "../KeyframeTrack.js";
+
+export class StringKeyframeTrack extends KeyframeTrack {
+    constructor(name: string, times: ArrayLike<number>, values: ArrayLike<any>);
+
+    /**
+     * @default 'string'
+     */
+    ValueTypeName: string;
+}

package/types/src/animation/tracks/VectorKeyframeTrack.d.ts

@@ -0,0 +1,11 @@
+import { InterpolationModes } from "../../constants.js";
+import { KeyframeTrack } from "../KeyframeTrack.js";
+
+export class VectorKeyframeTrack extends KeyframeTrack {
+    constructor(name: string, times: ArrayLike<number>, values: ArrayLike<number>, interpolation?: InterpolationModes);
+
+    /**
+     * @default 'vector'
+     */
+    ValueTypeName: string;
+}

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

@@ -0,0 +1,273 @@
+import { Object3D } from "../core/Object3D.js";
+import { AudioContext } from "./AudioContext.js";
+import { AudioListener } from "./AudioListener.js";
+
+// 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);
+
+    /**
+     * 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;
+
+    /**
+     * Whether to start playback automatically.
+     * @defaultValue `false`
+     */
+    autoplay: boolean;
+
+    buffer: AudioBuffer | null;
+
+    /**
+     * Modify pitch, measured in cents. +/- 100 is a semitone. +/- 1200 is an octave.
+     * @defaultValue `0`
+     */
+    detune: number;
+
+    /**
+     * @default false
+     */
+    loop: boolean;
+
+    /**
+     * @default 0
+     */
+    loopStart: number;
+
+    /**
+     * @default 0
+     */
+    loopEnd: number;
+
+    /**
+     * 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;
+
+    /**
+     * 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;
+
+    /**
+     * Speed of playback.
+     * @defaultValue `1`
+     */
+    playbackRate: number;
+
+    /**
+     * Whether the {@link Audio} is currently playing.
+     * @defaultValue `false`
+     */
+    isPlaying: boolean;
+
+    /**
+     * Whether playback can be controlled using the {@link Audio.play | play}(), {@link Audio.pause | pause}() etc. methods.
+     * @defaultValue `true`
+     */
+    hasPlaybackControl: boolean;
+
+    /**
+     * Type of the {@link Audio} source.
+     * @defaultValue 'empty'.
+     */
+    sourceType: string;
+
+    /**
+     * 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: AudioScheduledSourceNode | 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: AudioScheduledSourceNode): 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;
+
+    /**
+     * If {@link Audio.hasPlaybackControl | hasPlaybackControl} is true, pauses playback.
+     */
+    pause(): this;
+
+    /**
+     * If {@link Audio.hasPlaybackControl | hasPlaybackControl} is enabled, stops playback.
+     * @param delay (optional) - The delay, in seconds, at which the audio should start playing.
+     */
+    stop(delay?: number): 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;
+
+    /**
+     * Returns the detuning of oscillation in cents.
+     */
+    getDetune(): number;
+    /**
+     * 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;
+
+    /**
+     * 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;
+    /**
+     * Set the volume.
+     * @param value Expects a `Float`
+     */
+    setVolume(value: number): this;
+}

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

@@ -0,0 +1,58 @@
+import { Audio } from "./Audio.js";
+
+/**
+ * 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 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;
+
+    /**
+     * Get the average of the frequencies returned by the {@link AudioAnalyser.getFrequencyData | getFrequencyData} method.
+     */
+    getAverageFrequency(): number;
+}

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

@@ -0,0 +1,19 @@
+/**
+ * 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;
+}