@types/three 0.171.0 → 0.172.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/Uniform.d.ts

@@ -4,42 +4,148 @@ 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 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 };

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/nodes/NodeBuilderState.d.ts

@@ -2,6 +2,15 @@ import NodeMaterialObserver from "../../../materials/nodes/manager/NodeMaterialO
 import Node from "../../../nodes/core/Node.js";
 import NodeAttribute from "../../../nodes/core/NodeAttribute.js";
 import BindGroup from "../BindGroup.js";
+/**
+ * This module represents the state of a node builder after it was
+ * used to build the nodes for a render object. The state holds the
+ * results of the build for further processing in the renderer.
+ *
+ * Render objects with identical cache keys share the same node builder state.
+ *
+ * @private
+ */
 declare class NodeBuilderState {
     vertexShader: string | null;
     fragmentShader: string | null;
@@ -14,6 +23,20 @@ declare class NodeBuilderState {
     updateAfterNodes: Node[];
     monitor: NodeMaterialObserver;
     usedTimes: number;
+    /**
+     * Constructs a new node builder state.
+     *
+     * @param {String?} vertexShader - The native vertex shader code.
+     * @param {String?} fragmentShader - The native fragment shader code.
+     * @param {String?} computeShader - The native compute shader code.
+     * @param {Array<NodeAttribute>} nodeAttributes - An array of node attributes.
+     * @param {Array<BindGroup>} bindings - An array of bind groups.
+     * @param {Array<Node>} updateNodes - An array of nodes that implement their `update()` method.
+     * @param {Array<Node>} updateBeforeNodes - An array of nodes that implement their `updateBefore()` method.
+     * @param {Array<Node>} updateAfterNodes - An array of nodes that implement their `updateAfter()` method.
+     * @param {NodeMaterialObserver} monitor - A node material observer.
+     * @param {Array<Object>} transforms - An array with transform attribute objects. Only relevant when using compute shaders with WebGL 2.
+     */
     constructor(
         vertexShader: string | null,
         fragmentShader: string | null,
@@ -26,6 +49,13 @@ declare class NodeBuilderState {
         monitor: NodeMaterialObserver,
         transforms?: never[],
     );
+    /**
+     * This method is used to create a array of bind groups based
+     * on the existing bind groups of this state. Shared groups are
+     * not cloned.
+     *
+     * @return {Array<BindGroup>} A array of bind groups.
+     */
     createBindings(): BindGroup[];
 }
 export default NodeBuilderState;

three/src/renderers/common/nodes/NodeLibrary.d.ts

@@ -5,6 +5,14 @@ import NodeMaterial from "../../../materials/nodes/NodeMaterial.js";
 import Node from "../../../nodes/core/Node.js";
 import AnalyticLightNode from "../../../nodes/lighting/AnalyticLightNode.js";
 import { NodeRepresentation, ShaderNodeObject } from "../../../nodes/tsl/TSLCore.js";
+/**
+ * The purpose of a node library is to assign node implementations
+ * to existing library features. In `WebGPURenderer` lights, materials
+ * which are not based on `NodeMaterial` as well as tone mapping techniques
+ * are implemented with node-based modules.
+ *
+ * @private
+ */
 declare class NodeLibrary {
     lightNodes: WeakMap<{
         new(): Light;
@@ -18,26 +26,89 @@ declare class NodeLibrary {
         ToneMapping,
         (color: NodeRepresentation, exposure: NodeRepresentation) => ShaderNodeObject<Node>
     >;
+    /**
+     * Constructs a new node library.
+     */
     constructor();
+    /**
+     * Returns a matching node material instance for the given material object.
+     *
+     * This method also assigns/copies the properties of the given material object
+     * to the node material. This is done to make sure the current material
+     * configuration carries over to the node version.
+     *
+     * @param {Material} material - A material.
+     * @return {NodeMaterial} The corresponding node material.
+     */
     fromMaterial(material: Material): Material | NodeMaterial | null;
+    /**
+     * Adds a tone mapping node function for a tone mapping technique (constant).
+     *
+     * @param {Function} toneMappingNode - The tone mapping node function.
+     * @param {Number} toneMapping - The tone mapping.
+     */
     addToneMapping(
         toneMappingNode: (color: NodeRepresentation, exposure: NodeRepresentation) => ShaderNodeObject<Node>,
         toneMapping: ToneMapping,
     ): void;
+    /**
+     * Returns a tone mapping node function for a tone mapping technique (constant).
+     *
+     * @param {Number} toneMapping - The tone mapping.
+     * @return {Function?} The tone mapping node function. Returns `null` if no node function is found.
+     */
     getToneMappingFunction(
         toneMapping: ToneMapping,
     ): ((color: NodeRepresentation, exposure: NodeRepresentation) => ShaderNodeObject<Node>) | null;
+    /**
+     * Returns a node material class definition for a material type.
+     *
+     * @param {Sring} materialType - The material type.
+     * @return {NodeMaterial.constructor?} The node material class definition. Returns `null` if no node material is found.
+     */
     getMaterialNodeClass(materialType: string): (new() => NodeMaterial) | null;
+    /**
+     * Adds a node material class definition for a given material type.
+     *
+     * @param {NodeMaterial.constructor} materialNodeClass - The node material class definition.
+     * @param {Sring} materialClassType - The material type.
+     */
     addMaterial(materialNodeClass: {
         new(): NodeMaterial;
     }, materialClassType: string): void;
+    /**
+     * Returns a light node class definition for a light class definition.
+     *
+     * @param {Light.constructor} light - The light class definition.
+     * @return {AnalyticLightNode.constructor?} The light node class definition. Returns `null` if no light node is found.
+     */
     getLightNodeClass(light: Light): (new(light: Light) => AnalyticLightNode<Light>) | null;
+    /**
+     * Adds a light node class definition for a given light class definition.
+     *
+     * @param {AnalyticLightNode.constructor} lightNodeClass - The light node class definition.
+     * @param {Light.constructor} lightClass - The light class definition.
+     */
     addLight<TLight extends Light>(lightNodeClass: {
         new(light: TLight): AnalyticLightNode<TLight>;
     }, lightClass: {
         new(): TLight;
     }): void;
+    /**
+     * Adds a node class definition for the given type to the provided type library.
+     *
+     * @param {Any} nodeClass - The node class definition.
+     * @param {String} type - The object type.
+     * @param {Map} library - The type library.
+     */
     addType<TNodeClass, TType>(nodeClass: TNodeClass, type: TType, library: Map<TType, TNodeClass>): void;
+    /**
+     * Adds a node class definition for the given class definition to the provided type library.
+     *
+     * @param {Any} nodeClass - The node class definition.
+     * @param {Any} baseClass - The class definition.
+     * @param {WeakMap} library - The type library.
+     */
     addClass<TNodeClass, TBaseClass extends object>(
         nodeClass: TNodeClass,
         baseClass: TBaseClass,