@types/three 0.171.0 → 0.173.0

three/src/renderers/common/{PostProcessingUtils.d.ts → RendererUtils.d.ts}

@@ -6,6 +6,7 @@ import { RenderTarget } from "../../core/RenderTarget.js";
 import { Material } from "../../materials/Material.js";
 import { Color } from "../../math/Color.js";
 import MRTNode from "../../nodes/core/MRTNode.js";
+import Node from "../../nodes/core/Node.js";
 import LightsNode from "../../nodes/lighting/LightsNode.js";
 import { Scene } from "../../scenes/Scene.js";
 import { CubeTexture } from "../../textures/CubeTexture.js";
@@ -43,24 +44,35 @@ export interface RendererState {
 
 export function saveRendererState(renderer: Renderer, state?: RendererState): RendererState;
 
-export function resetRendererState(renderer: Renderer, state?: RendererState): RendererState;
+export function resetRendererState(renderer: Renderer, state: RendererState): RendererState;
 
 export function restoreRendererState(renderer: Renderer, state: RendererState): void;
 
-// renderer and scene state
+// scene state
 
-export interface RendererAndSceneState extends RendererState {
+export interface SceneState {
     background: Color | Texture | CubeTexture | null;
     backgroundNode: Node | null | undefined;
     overrideMaterial: Material | null;
 }
 
+export function saveSceneState(scene: Scene, state?: SceneState): SceneState;
+
+export function resetSceneState(scene: Scene, state: SceneState): SceneState;
+
+export function restoreSceneState(scene: Scene, state: SceneState): SceneState;
+
+// renderer and scene state
+
+export interface RendererAndSceneState extends RendererState, SceneState {
+}
+
 export function saveRendererAndSceneState(
     renderer: RendererState,
     scene: Scene,
     state?: RendererAndSceneState,
 ): RendererAndSceneState;
 
-export function resetRendererAndSceneState(renderer: Renderer, state?: RendererAndSceneState): RendererAndSceneState;
+export function resetRendererAndSceneState(renderer: Renderer, state: RendererAndSceneState): RendererAndSceneState;
 
 export function restoreRendererAndSceneState(renderer: Renderer, state: RendererAndSceneState): void;

three/src/renderers/common/StorageBufferAttribute.d.ts

@@ -3,5 +3,5 @@ import { BufferAttribute, TypedArray } from "../../core/BufferAttribute.js";
 export default class StorageBufferAttribute extends BufferAttribute {
     readonly isStorageBufferAttribute: true;
 
-    constructor(array: TypedArray, itemSize: number);
+    constructor(array: TypedArray | number, itemSize: number);
 }

three/src/renderers/common/Textures.d.ts

@@ -43,6 +43,12 @@ interface TextureOptions {
     needsMipmaps?: boolean;
     levels?: number;
 }
+/**
+ * This module manages the textures of the renderer.
+ *
+ * @private
+ * @augments DataMap
+ */
 declare class Textures extends DataMap<{
     renderTarget: {
         key: RenderTarget;
@@ -56,13 +62,73 @@ declare class Textures extends DataMap<{
     renderer: Renderer;
     backend: Backend;
     info: Info;
+    /**
+     * Constructs a new texture management component.
+     *
+     * @param {Renderer} renderer - The renderer.
+     * @param {Backend} backend - The renderer's backend.
+     * @param {Info} info - Renderer component for managing metrics and monitoring data.
+     */
     constructor(renderer: Renderer, backend: Backend, info: Info);
+    /**
+     * Updates the given render target. Based on the given render target configuration,
+     * it updates the texture states representing the attachments of the framebuffer.
+     *
+     * @param {RenderTarget} renderTarget - The render target to update.
+     * @param {Number} [activeMipmapLevel=0] - The active mipmap level.
+     */
     updateRenderTarget(renderTarget: RenderTarget, activeMipmapLevel?: number): void;
+    /**
+     * Updates the given texture. Depending on the texture state, this method
+     * triggers the upload of texture data to the GPU memory. If the texture data are
+     * not yet ready for the upload, it uses default texture data for as a placeholder.
+     *
+     * @param {Texture} texture - The texture to update.
+     * @param {Object} [options={}] - The options.
+     */
     updateTexture(texture: Texture, options?: TextureOptions): void;
+    /**
+     * Computes the size of the given texture and writes the result
+     * into the target vector. This vector is also returned by the
+     * method.
+     *
+     * If no texture data are available for the compute yet, the method
+     * returns default size values.
+     *
+     * @param {Texture} texture - The texture to compute the size for.
+     * @param {Vector3} target - The target vector.
+     * @return {Vector3} The target vector.
+     */
     getSize(texture: Texture, target?: SizeVector3Unitialized): SizeVector3;
+    /**
+     * Computes the number of mipmap levels for the given texture.
+     *
+     * @param {Texture} texture - The texture.
+     * @param {Number} width - The texture's width.
+     * @param {Number} height - The texture's height.
+     * @return {Number} The number of mipmap levels.
+     */
     getMipLevels(texture: Texture, width: number, height: number): number;
+    /**
+     * Returns `true` if the given texture requires mipmaps.
+     *
+     * @param {Texture} texture - The texture.
+     * @return {Boolean} Whether mipmaps are required or not.
+     */
     needsMipmaps(texture: Texture): boolean;
+    /**
+     * Returns `true` if the given texture is an environment map.
+     *
+     * @param {Texture} texture - The texture.
+     * @return {Boolean} Whether the given texture is an environment map or not.
+     */
     isEnvironmentTexture(texture: Texture): boolean;
+    /**
+     * Frees internal resource when the given texture isn't
+     * required anymore.
+     *
+     * @param {Texture} texture - The texture to destroy.
+     */
     _destroyTexture(texture: Texture): void;
 }
 export default Textures;

three/src/renderers/common/TimestampQueryPool.d.ts

@@ -0,0 +1,31 @@
+import RenderContext from "./RenderContext.js";
+declare abstract class TimestampQueryPool {
+    trackTimestamp: boolean;
+    maxQueries: number;
+    currentQueryIndex: number;
+    queryOffsets: Map<number, number>;
+    isDisposed: boolean;
+    lastValue: number;
+    pendingResolve: boolean;
+    constructor(maxQueries?: number);
+    /**
+     * Allocate queries for a specific renderContext.
+     *
+     * @abstract
+     */
+    abstract allocateQueriesForContext(renderContext: RenderContext): number | null;
+    /**
+     * Resolve all timestamps and return data (or process them).
+     *
+     * @abstract
+     * @returns {Promise<Number>|Number} The resolved timestamp value.
+     */
+    abstract resolveQueriesAsync(): Promise<number>;
+    /**
+     * Dispose of the query pool.
+     *
+     * @abstract
+     */
+    abstract dispose(): void;
+}
+export default TimestampQueryPool;

three/src/renderers/common/Uniform.d.ts

@@ -1,45 +1,177 @@
 import { Color } from "../../math/Color.js";
+import { Matrix2 } from "../../math/Matrix2.js";
 import { Matrix3 } from "../../math/Matrix3.js";
 import { Matrix4 } from "../../math/Matrix4.js";
 import { Vector2 } from "../../math/Vector2.js";
 import { Vector3 } from "../../math/Vector3.js";
 import { Vector4 } from "../../math/Vector4.js";
+/**
+ * Abstract base class for uniforms.
+ *
+ * @abstract
+ * @private
+ */
 declare class Uniform<TValue> {
     name: string;
     value: TValue;
     boundary: number;
     itemSize: number;
     offset: number;
+    /**
+     * Constructs a new uniform.
+     *
+     * @param {String} name - The uniform's name.
+     * @param {Any} value - The uniform's value.
+     */
     constructor(name: string, value: TValue);
+    /**
+     * Sets the uniform's value.
+     *
+     * @param {Any} value - The value to set.
+     */
     setValue(value: TValue): void;
+    /**
+     * Returns the uniform's value.
+     *
+     * @return {Any} The value.
+     */
     getValue(): TValue;
 }
+/**
+ * Represents a Number uniform.
+ *
+ * @private
+ * @augments Uniform
+ */
 declare class NumberUniform extends Uniform<number> {
     readonly isNumberUniform: true;
+    /**
+     * Constructs a new Number uniform.
+     *
+     * @param {String} name - The uniform's name.
+     * @param {Number} value - The uniform's value.
+     */
     constructor(name: string, value?: number);
 }
+/**
+ * Represents a Vector2 uniform.
+ *
+ * @private
+ * @augments Uniform
+ */
 declare class Vector2Uniform extends Uniform<Vector2> {
     readonly isVector2Uniform: true;
+    /**
+     * Constructs a new Number uniform.
+     *
+     * @param {String} name - The uniform's name.
+     * @param {Vector2} value - The uniform's value.
+     */
     constructor(name: string, value?: Vector2);
 }
+/**
+ * Represents a Vector3 uniform.
+ *
+ * @private
+ * @augments Uniform
+ */
 declare class Vector3Uniform extends Uniform<Vector3> {
     readonly isVector3Uniform: true;
+    /**
+     * Constructs a new Number uniform.
+     *
+     * @param {String} name - The uniform's name.
+     * @param {Vector3} value - The uniform's value.
+     */
     constructor(name: string, value?: Vector3);
 }
+/**
+ * Represents a Vector4 uniform.
+ *
+ * @private
+ * @augments Uniform
+ */
 declare class Vector4Uniform extends Uniform<Vector4> {
     readonly isVector4Uniform: true;
+    /**
+     * Constructs a new Number uniform.
+     *
+     * @param {String} name - The uniform's name.
+     * @param {Vector4} value - The uniform's value.
+     */
     constructor(name: string, value?: Vector4);
 }
+/**
+ * Represents a Color uniform.
+ *
+ * @private
+ * @augments Uniform
+ */
 declare class ColorUniform extends Uniform<Color> {
     readonly isColorUniform: true;
+    /**
+     * Constructs a new Number uniform.
+     *
+     * @param {String} name - The uniform's name.
+     * @param {Color} value - The uniform's value.
+     */
     constructor(name: string, value?: Color);
 }
+/**
+ * Represents a Matrix2 uniform.
+ *
+ * @private
+ * @augments Uniform
+ */
+declare class Matrix2Uniform extends Uniform<Matrix2> {
+    readonly isMatrix2Uniform: true;
+    /**
+     * Constructs a new Number uniform.
+     *
+     * @param {String} name - The uniform's name.
+     * @param {Matrix2} value - The uniform's value.
+     */
+    constructor(name: string, value?: Matrix2);
+}
+/**
+ * Represents a Matrix3 uniform.
+ *
+ * @private
+ * @augments Uniform
+ */
 declare class Matrix3Uniform extends Uniform<Matrix3> {
     readonly isMatrix3Uniform: true;
+    /**
+     * Constructs a new Number uniform.
+     *
+     * @param {String} name - The uniform's name.
+     * @param {Matrix3} value - The uniform's value.
+     */
     constructor(name: string, value?: Matrix3);
 }
+/**
+ * Represents a Matrix4 uniform.
+ *
+ * @private
+ * @augments Uniform
+ */
 declare class Matrix4Uniform extends Uniform<Matrix4> {
     readonly isMatrix4Uniform: true;
+    /**
+     * Constructs a new Number uniform.
+     *
+     * @param {String} name - The uniform's name.
+     * @param {Matrix4} value - The uniform's value.
+     */
     constructor(name: string, value?: Matrix4);
 }
-export { ColorUniform, Matrix3Uniform, Matrix4Uniform, NumberUniform, Vector2Uniform, Vector3Uniform, Vector4Uniform };
+export {
+    ColorUniform,
+    Matrix2Uniform,
+    Matrix3Uniform,
+    Matrix4Uniform,
+    NumberUniform,
+    Vector2Uniform,
+    Vector3Uniform,
+    Vector4Uniform,
+};

three/src/renderers/common/UniformBuffer.d.ts

@@ -1,6 +1,18 @@
 import Buffer from "./Buffer.js";
+/**
+ * Represents a uniform buffer binding type.
+ *
+ * @private
+ * @augments Buffer
+ */
 declare class UniformBuffer extends Buffer {
     readonly isUniformBuffer: true;
+    /**
+     * Constructs a new uniform buffer.
+     *
+     * @param {String} name - The buffer's name.
+     * @param {TypedArray} [buffer=null] - The buffer.
+     */
     constructor(name?: string, buffer?: null);
 }
 export default UniformBuffer;

three/src/renderers/common/UniformsGroup.d.ts

@@ -9,25 +9,128 @@ import {
     Vector4NodeUniform,
 } from "./nodes/NodeUniform.js";
 import UniformBuffer from "./UniformBuffer.js";
+/**
+ * This class represents a uniform buffer binding but with
+ * an API that allows to maintain individual uniform objects.
+ *
+ * @private
+ * @augments UniformBuffer
+ */
 declare class UniformsGroup extends UniformBuffer {
     readonly isUniformsGroup: true;
     _values: number[] | null;
     uniforms: NodeUniformGPU[];
+    /**
+     * Constructs a new uniforms group.
+     *
+     * @param {String} name - The group's name.
+     */
     constructor(name?: string);
+    /**
+     * Adds a uniform to this group.
+     *
+     * @param {Uniform} uniform - The uniform to add.
+     * @return {UniformsGroup} A reference to this group.
+     */
     addUniform(uniform: NodeUniformGPU): this;
+    /**
+     * Removes a uniform from this group.
+     *
+     * @param {Uniform} uniform - The uniform to remove.
+     * @return {UniformsGroup} A reference to this group.
+     */
     removeUniform(uniform: NodeUniformGPU): this;
+    /**
+     * An array with the raw uniform values.
+     *
+     * @type {Array<Number>}
+     */
     get values(): number[];
+    /**
+     * A Float32 array buffer with the uniform values.
+     *
+     * @type {Float32Array}
+     */
     get buffer(): Float32Array;
+    /**
+     * The byte length of the buffer with correct buffer alignment.
+     *
+     * @type {Number}
+     */
     get byteLength(): number;
+    /**
+     * Updates this group by updating each uniform object of
+     * the internal uniform list. The uniform objects check if their
+     * values has actually changed so this method only returns
+     * `true` if there is a real value change.
+     *
+     * @return {Boolean} Whether the uniforms have been updated and
+     * must be uploaded to the GPU.
+     */
     update(): boolean;
+    /**
+     * Updates a given uniform by calling an update method matching
+     * the uniforms type.
+     *
+     * @param {Uniform} uniform - The uniform to update.
+     * @return {Boolean} Whether the uniform has been updated or not.
+     */
     updateByType(uniform: NodeUniformGPU): boolean | undefined;
+    /**
+     * Updates a given Number uniform.
+     *
+     * @param {NumberUniform} uniform - The Number uniform.
+     * @return {Boolean} Whether the uniform has been updated or not.
+     */
     updateNumber(uniform: NumberNodeUniform): boolean;
+    /**
+     * Updates a given Vector2 uniform.
+     *
+     * @param {Vector2Uniform} uniform - The Vector2 uniform.
+     * @return {Boolean} Whether the uniform has been updated or not.
+     */
     updateVector2(uniform: Vector2NodeUniform): boolean;
+    /**
+     * Updates a given Vector3 uniform.
+     *
+     * @param {Vector3Uniform} uniform - The Vector3 uniform.
+     * @return {Boolean} Whether the uniform has been updated or not.
+     */
     updateVector3(uniform: Vector3NodeUniform): boolean;
+    /**
+     * Updates a given Vector4 uniform.
+     *
+     * @param {Vector4Uniform} uniform - The Vector4 uniform.
+     * @return {Boolean} Whether the uniform has been updated or not.
+     */
     updateVector4(uniform: Vector4NodeUniform): boolean;
+    /**
+     * Updates a given Color uniform.
+     *
+     * @param {ColorUniform} uniform - The Color uniform.
+     * @return {Boolean} Whether the uniform has been updated or not.
+     */
     updateColor(uniform: ColorNodeUniform): boolean;
+    /**
+     * Updates a given Matrix3 uniform.
+     *
+     * @param {Matrix3Uniform} uniform - The Matrix3 uniform.
+     * @return {Boolean} Whether the uniform has been updated or not.
+     */
     updateMatrix3(uniform: Matrix3NodeUniform): boolean;
+    /**
+     * Updates a given Matrix4 uniform.
+     *
+     * @param {Matrix4Uniform} uniform - The Matrix4 uniform.
+     * @return {Boolean} Whether the uniform has been updated or not.
+     */
     updateMatrix4(uniform: Matrix4NodeUniform): boolean;
+    /**
+     * Returns a typed array that matches the given data type.
+     *
+     * @param {String} type - The data type.
+     * @return {TypedArray} The typed array.
+     */
     _getBufferForType(type: string | null): Int32Array | Uint32Array | Float32Array;
 }
 export default UniformsGroup;

three/src/renderers/common/XRManager.d.ts

@@ -0,0 +1,196 @@
+import { ArrayCamera } from "../../cameras/ArrayCamera.js";
+import { PerspectiveCamera } from "../../cameras/PerspectiveCamera.js";
+import { EventDispatcher } from "../../core/EventDispatcher.js";
+import { RenderTarget } from "../../core/RenderTarget.js";
+import { Vector2 } from "../../math/Vector2.js";
+import { WebXRController } from "../webxr/WebXRController.js";
+import { AnimationContext } from "./Animation.js";
+import Renderer from "./Renderer.js";
+import { XRRenderTarget } from "./XRRenderTarget.js";
+export interface XRManagerEventMap {
+    sessionstart: {};
+    sessionend: {};
+    planesdetected: {
+        data: XRFrame;
+    };
+}
+/**
+ * The XR manager is built on top of the WebXR Device API to
+ * manage XR sessions with `WebGPURenderer`.
+ *
+ * XR is currently only supported with a WebGL 2 backend.
+ *
+ * @augments EventDispatcher
+ */
+declare class XRManager extends EventDispatcher<XRManagerEventMap> {
+    enabled: boolean;
+    isPresenting: boolean;
+    cameraAutoUpdate: boolean;
+    _renderer: Renderer;
+    _cameraL: PerspectiveCamera;
+    _cameraR: PerspectiveCamera;
+    _cameras: PerspectiveCamera[];
+    _cameraXR: ArrayCamera;
+    _currentDepthNear: number | null;
+    _currentDepthFar: number | null;
+    _controllers: WebXRController[];
+    _controllerInputSources: (XRInputSource | null)[];
+    _currentRenderTarget: RenderTarget | null;
+    _xrRenderTarget: XRRenderTarget | null;
+    _currentAnimationContext: AnimationContext | null;
+    _currentAnimationLoop: ((time: DOMHighResTimeStamp, frame?: XRFrame) => void) | null;
+    _currentPixelRatio: number | null;
+    _currentSize: Vector2;
+    _onSessionEvent: (event: XRInputSourceEvent) => void;
+    _onSessionEnd: () => void;
+    _onInputSourcesChange: (event: XRInputSourcesChangeEvent) => void;
+    _onAnimationFrame: (time: DOMHighResTimeStamp, frame?: XRFrame) => void;
+    _referenceSpace: XRReferenceSpace | null;
+    _referenceSpaceType: XRReferenceSpaceType;
+    _customReferenceSpace: XRReferenceSpace | null;
+    _framebufferScaleFactor: number;
+    _foveation: number;
+    _session: XRSession | null;
+    _glBaseLayer: XRWebGLLayer | null;
+    _glBinding: XRWebGLBinding | null;
+    _glProjLayer: XRProjectionLayer | null;
+    _xrFrame: XRFrame | null;
+    _useLayers: boolean;
+    /**
+     * Constructs a new XR manager.
+     *
+     * @param {Renderer} renderer - The renderer.
+     */
+    constructor(renderer: Renderer);
+    /**
+     * Returns an instance of `THREE.Group` that represents the transformation
+     * of a XR controller in target ray space. The requested controller is defined
+     * by the given index.
+     *
+     * @param {Number} index - The index of the XR controller.
+     * @return {Group} A group that represents the controller's transformation.
+     */
+    getController(index: number): import("../webxr/WebXRController.js").XRTargetRaySpace;
+    /**
+     * Returns an instance of `THREE.Group` that represents the transformation
+     * of a XR controller in grip space. The requested controller is defined
+     * by the given index.
+     *
+     * @param {Number} index - The index of the XR controller.
+     * @return {Group} A group that represents the controller's transformation.
+     */
+    getControllerGrip(index: number): import("../webxr/WebXRController.js").XRGripSpace;
+    /**
+     * Returns an instance of `THREE.Group` that represents the transformation
+     * of a XR controller in hand space. The requested controller is defined
+     * by the given index.
+     *
+     * @param {Number} index - The index of the XR controller.
+     * @return {Group} A group that represents the controller's transformation.
+     */
+    getHand(index: number): import("../webxr/WebXRController.js").XRHandSpace;
+    /**
+     * Returns the foveation value.
+     *
+     * @return {Number|undefined} The foveation value. Returns `undefined` if no base or projection layer is defined.
+     */
+    getFoveation(): number | undefined;
+    /**
+     * Sets the foveation value.
+     *
+     * @param {Number} foveation - A number in the range `[0,1]` where `0` means no foveation (full resolution)
+     * and `1` means maximum foveation (the edges render at lower resolution).
+     */
+    setFoveation(foveation: number): void;
+    /**
+     * Returns the framebuffer scale factor.
+     *
+     * @return {Number} The framebuffer scale factor.
+     */
+    getFramebufferScaleFactor(): number;
+    /**
+     * Sets the framebuffer scale factor.
+     *
+     * This method can not be used during a XR session.
+     *
+     * @param {Number} factor - The framebuffer scale factor.
+     */
+    setFramebufferScaleFactor(factor: number): void;
+    /**
+     * Returns the reference space type.
+     *
+     * @return {String} The reference space type.
+     */
+    getReferenceSpaceType(): XRReferenceSpaceType;
+    /**
+     * Sets the reference space type.
+     *
+     * This method can not be used during a XR session.
+     *
+     * @param {String} type - The reference space type.
+     */
+    setReferenceSpaceType(type: XRReferenceSpaceType): void;
+    /**
+     * Returns the XR reference space.
+     *
+     * @return {XRReferenceSpace} The XR reference space.
+     */
+    getReferenceSpace(): XRReferenceSpace | null;
+    /**
+     * Sets a custom XR reference space.
+     *
+     * @param {XRReferenceSpace} space - The XR reference space.
+     */
+    setReferenceSpace(space: XRReferenceSpace): void;
+    /**
+     * Returns the XR camera.
+     *
+     * @return {ArrayCamera} The XR camera.
+     */
+    getCamera(): ArrayCamera;
+    /**
+     * Returns the environment blend mode from the current XR session.
+     *
+     * @return {('opaque'|'additive'|'alpha-blend')?} The environment blend mode. Returns `null` when used outside of a XR session.
+     */
+    getEnvironmentBlendMode(): XREnvironmentBlendMode | undefined;
+    /**
+     * Returns the current XR frame.
+     *
+     * @return {XRFrame?} The XR frame. Returns `null` when used outside a XR session.
+     */
+    getFrame(): XRFrame | null;
+    /**
+     * Returns the current XR session.
+     *
+     * @return {XRSession?} The XR session. Returns `null` when used outside a XR session.
+     */
+    getSession(): XRSession | null;
+    /**
+     * After a XR session has been requested usually with one of the `*Button` modules, it
+     * is injected into the renderer with this method. This method triggers the start of
+     * the actual XR rendering.
+     *
+     * @async
+     * @param {XRSession} session - The XR session to set.
+     * @return {Promise} A Promise that resolves when the session has been set.
+     */
+    setSession(session: XRSession): Promise<void>;
+    /**
+     * This method is called by the renderer per frame and updates the XR camera
+     * and it sub cameras based on the given camera. The given camera is the "user"
+     * camera created on application level and used for non-XR rendering.
+     *
+     * @param {PerspectiveCamera} camera - The camera.
+     */
+    updateCamera(camera: PerspectiveCamera): void;
+    /**
+     * Returns a WebXR controller for the given controller index.
+     *
+     * @private
+     * @param {Number} index - The controller index.
+     * @return {WebXRController} The XR controller.
+     */
+    _getController(index: number): WebXRController;
+}
+export default XRManager;