@types/three 0.171.0 → 0.172.0

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

@@ -7,6 +7,12 @@ import DataMap from "./DataMap.js";
 interface Data {
     version?: number | undefined;
 }
+/**
+ * This renderer module manages geometry attributes.
+ *
+ * @private
+ * @augments DataMap
+ */
 declare class Attributes extends DataMap<{
     attribute: {
         key: BufferAttribute | InterleavedBufferAttribute;
@@ -14,9 +20,34 @@ declare class Attributes extends DataMap<{
     };
 }> {
     backend: Backend;
+    /**
+     * Constructs a new attribute management component.
+     *
+     * @param {Backend} backend - The renderer's backend.
+     */
     constructor(backend: Backend);
+    /**
+     * Deletes the data for the given attribute.
+     *
+     * @param {BufferAttribute} attribute - The attribute.
+     * @return {Object} The deleted attribute data.
+     */
     delete(attribute: BufferAttribute | InterleavedBufferAttribute): Data;
+    /**
+     * Updates the given attribute. This method creates attribute buffers
+     * for new attributes and updates data for existing ones.
+     *
+     * @param {BufferAttribute} attribute - The attribute to update.
+     * @param {Number} type - The attribute type.
+     */
     update(attribute: BufferAttribute | InterleavedBufferAttribute, type: AttributeType): void;
+    /**
+     * Utility method for handling interleaved buffer attributes correctly.
+     * To process them, their `InterleavedBuffer` is returned.
+     *
+     * @param {BufferAttribute} attribute - The attribute.
+     * @return {BufferAttribute|InterleavedBuffer}
+     */
     _getBufferAttribute(attribute: BufferAttribute | InterleavedBufferAttribute): BufferAttribute | InterleavedBuffer;
 }
 export default Attributes;

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

@@ -1,6 +1,17 @@
 import { CoordinateSystem } from "../../constants.js";
 import Renderer from "./Renderer.js";
 
+declare module "../../core/Object3D.js" {
+    interface Object3D {
+        // See https://github.com/mrdoob/three.js/pull/28683
+        count?: number | undefined;
+        // See https://github.com/mrdoob/three.js/pull/26335
+        occlusionTest?: boolean | undefined;
+        // https://github.com/mrdoob/three.js/pull/29386
+        static?: boolean | undefined;
+    }
+}
+
 export interface BackendParameters {
     canvas?: HTMLCanvasElement | undefined;
 }

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

@@ -9,6 +9,12 @@ interface SceneData {
     backgroundMesh?: Mesh;
     backgroundCacheKey: string;
 }
+/**
+ * This renderer module manages the background.
+ *
+ * @private
+ * @augments DataMap
+ */
 declare class Background extends DataMap<{
     scene: {
         key: Scene;
@@ -17,7 +23,23 @@ declare class Background extends DataMap<{
 }> {
     renderer: Renderer;
     nodes: Nodes;
+    /**
+     * Constructs a new background management component.
+     *
+     * @param {Renderer} renderer - The renderer.
+     * @param {Nodes} nodes - Renderer component for managing nodes related logic.
+     */
     constructor(renderer: Renderer, nodes: Nodes);
+    /**
+     * Updates the background for the given scene. Depending on how `Scene.background`
+     * or `Scene.backgroundNode` are configured, this method might configure a simple clear
+     * or add a mesh to the render list for rendering the background as a textured plane
+     * or skybox.
+     *
+     * @param {Scene} scene - The scene.
+     * @param {RenderList} renderList - The current render list.
+     * @param {RenderContext} renderContext - The current render context.
+     */
     update(scene: Scene, renderList: RenderList, renderContext: RenderContext): void;
 }
 export default Background;

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

@@ -1,11 +1,26 @@
 import Binding from "./Binding.js";
 import NodeUniformsGroup from "./nodes/NodeUniformsGroup.js";
+/**
+ * A bind group represents a collection of bindings and thus a collection
+ * or resources. Bind groups are assigned to pipelines to provide them
+ * with the required resources (like uniform buffers or textures).
+ *
+ * @private
+ */
 declare class BindGroup {
     name: string;
     bindings: NodeUniformsGroup[] | Binding[];
     index: number;
     bindingsReference: NodeUniformsGroup[] | BindGroup;
     id: number;
+    /**
+     * Constructs a new bind group.
+     *
+     * @param {String} name - The bind group's name.
+     * @param {Array<Binding>} bindings - An array of bindings.
+     * @param {Number} index - The group index.
+     * @param {Array<Binding>} bindingsReference - An array of reference bindings.
+     */
     constructor(
         name?: string,
         bindings?: NodeUniformsGroup[],

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

@@ -1,8 +1,32 @@
+/**
+ * A binding represents the connection between a resource (like a texture, sampler
+ * or uniform buffer) and the resource definition in a shader stage.
+ *
+ * This module is an abstract base class for all concrete bindings types.
+ *
+ * @abstract
+ * @private
+ */
 declare class Binding {
     name: string;
     visibility: number;
+    /**
+     * Constructs a new binding.
+     *
+     * @param {String} [name=''] - The binding's name.
+     */
     constructor(name?: string);
+    /**
+     * Makes sure binding's resource is visible for the given shader stage.
+     *
+     * @param {Number} visibility - The shader stage.
+     */
     setVisibility(visibility: number): void;
+    /**
+     * Clones the binding.
+     *
+     * @return {Binding} The cloned binding.
+     */
     clone(): Binding & this;
 }
 export default Binding;

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

@@ -11,7 +11,23 @@ import Textures from "./Textures.js";
 interface BindGroupData {
     bindGroup?: BindGroup | undefined;
 }
+/**
+ * This renderer module manages the bindings of the renderer.
+ *
+ * @private
+ * @augments DataMap
+ */
 declare class Bindings extends DataMap<{
+    /**
+     * Constructs a new bindings management component.
+     *
+     * @param {Backend} backend - The renderer's backend.
+     * @param {Nodes} nodes - Renderer component for managing nodes related logic.
+     * @param {Textures} textures - Renderer component for managing textures.
+     * @param {Attributes} attributes - Renderer component for managing attributes.
+     * @param {Pipelines} pipelines - Renderer component for managing pipelines.
+     * @param {Info} info - Renderer component for managing metrics and monitoring data.
+     */
     bindGroup: {
         key: BindGroup;
         value: BindGroupData;
@@ -31,12 +47,50 @@ declare class Bindings extends DataMap<{
         pipelines: Pipelines,
         info: Info,
     );
+    /**
+     * Returns the bind groups for the given render object.
+     *
+     * @param {RenderObject} renderObject - The render object.
+     * @return {Array<BindGroup>} The bind groups.
+     */
     getForRender(renderObject: RenderObject): BindGroup[];
+    /**
+     * Returns the bind groups for the given compute node.
+     *
+     * @param {Node} computeNode - The compute node.
+     * @return {Array<BindGroup>} The bind groups.
+     */
     getForCompute(computeNode: ComputeNode): BindGroup[];
+    /**
+     * Updates the bindings for the given compute node.
+     *
+     * @param {Node} computeNode - The compute node.
+     */
     updateForCompute(computeNode: ComputeNode): void;
+    /**
+     * Updates the bindings for the given render object.
+     *
+     * @param {RenderObject} renderObject - The render object.
+     */
     updateForRender(renderObject: RenderObject): void;
+    /**
+     * Updates the given array of bindings.
+     *
+     * @param {Array<BindGroup>} bindings - The bind groups.
+     */
     _updateBindings(bindings: BindGroup[]): void;
+    /**
+     * Initializes the given bind group.
+     *
+     * @param {BindGroup} bindGroup - The bind group to initialize.
+     */
     _init(bindGroup: BindGroup): void;
+    /**
+     * Updates the given bind group.
+     *
+     * @param {BindGroup} bindGroup - The bind group to update.
+     * @param {Array<BindGroup>} bindings - The bind groups.
+     */
     _update(bindGroup: BindGroup, bindings: BindGroup[]): void;
 }
 export default Bindings;

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

@@ -1,11 +1,42 @@
 import Binding from "./Binding.js";
+/**
+ * Represents a buffer binding type.
+ *
+ * @private
+ * @abstract
+ * @augments Binding
+ */
 declare class Buffer extends Binding {
     readonly isBuffer: true;
     bytesPerElement: number;
     _buffer: Float32Array | null;
+    /**
+     * Constructs a new buffer.
+     *
+     * @param {String} name - The buffer's name.
+     * @param {TypedArray} [buffer=null] - The buffer.
+     */
     constructor(name?: string, buffer?: Float32Array | null);
+    /**
+     * The buffer's byte length.
+     *
+     * @type {Number}
+     * @readonly
+     */
     get byteLength(): number;
+    /**
+     * A reference to the internal buffer.
+     *
+     * @type {Float32Array}
+     * @readonly
+     */
     get buffer(): Float32Array | null;
+    /**
+     * Updates the binding.
+     *
+     * @return {Boolean} Whether the buffer has been updated and must be
+     * uploaded to the GPU.
+     */
     update(): boolean;
 }
 export default Buffer;

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

@@ -1,4 +1,30 @@
+/** @module BufferUtils **/
+/**
+ * This function is usually called with the length in bytes of an array buffer.
+ * It returns an padded value whic ensure chunk size alignment according to STD140 layout.
+ *
+ * @function
+ * @param {Number} floatLength - The buffer length.
+ * @return {Number} The padded length.
+ */
 declare function getFloatLength(floatLength: number): number;
+/**
+ * Given the count of vectors and their vector length, this function computes
+ * a total length in bytes with buffer alignment according to STD140 layout.
+ *
+ * @function
+ * @param {Number} count - The number of vectors.
+ * @param {Number} [vectorLength=4] - The vector length.
+ * @return {Number} The padded length.
+ */
 declare function getVectorLength(count: number, vectorLength?: number): number;
+/**
+ * This function is called with a vector length and ensure the computed length
+ * matches a predefined stride (in this case `4`).
+ *
+ * @function
+ * @param {Number} vectorLength - The vector length.
+ * @return {Number} The padded length.
+ */
 declare function getStrideLength(vectorLength: number): number;
 export { getFloatLength, getStrideLength, getVectorLength };

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

@@ -1,10 +1,32 @@
 import { Group } from "../../objects/Group.js";
+/**
+ * A specialized group which eanbles applications access to the
+ * Render Bundle API of WebGPU. The group with all its descendant nodes
+ * are considered as one render bundle and processed as such by
+ * the renderer.
+ *
+ * This module is only fully supported by `WebGPURenderer` with a WebGPU backend.
+ * With a WebGL backend, the group can technically be rendered but without
+ * any performance improvements.
+ *
+ * @augments Group
+ */
 declare class BundleGroup extends Group {
     readonly isBundleGroup: true;
     readonly type: string;
     static: boolean;
     version: number;
+    /**
+     * Constructs a new bundle group.
+     */
     constructor();
+    /**
+     * Set this property to `true` when the bundle group has changed.
+     *
+     * @type {Boolean}
+     * @default false
+     * @param {Boolean} value
+     */
     set needsUpdate(value: boolean);
 }
 export default BundleGroup;

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

@@ -1,9 +1,39 @@
 type RecursiveWeakMap<K extends readonly object[], V> = WeakMap<K[number], V | RecursiveWeakMap<K, V>>;
+/**
+ * Data structure for the renderer. It allows defining values
+ * with chained, hierarchical keys. Keys are meant to be
+ * objects since the module internally works with Weak Maps
+ * for perforamnce reasons.
+ *
+ * @private
+ */
 export default class ChainMap<K extends readonly object[], V> {
     weakMap: RecursiveWeakMap<K, V>;
+    /**
+     * Constructs a new chained map.
+     */
     constructor();
+    /**
+     * Returns the value for the given array of keys.
+     *
+     * @param {Array<Object>} keys - List of keys.
+     * @return {Any} The value. Returns `undefined` if no value was found.
+     */
     get(keys: K): V | undefined;
-    set(keys: K, value: V): V;
+    /**
+     * Sets the value for the given keys.
+     *
+     * @param {Array<Object>} keys - List of keys.
+     * @param {Any} value - The value to set.
+     * @return {ChainMap} A reference to this chain map.
+     */
+    set(keys: K, value: V): this;
+    /**
+     * Deletes a value for the given keys.
+     *
+     * @param {Array<Object>} keys - The keys.
+     * @return {Boolean} Returns `true` if the value has been removed successfully and `false` if the value has not be found.
+     */
     delete(keys: K): boolean;
 }
 export {};

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

@@ -5,6 +5,14 @@ import { Plane } from "../../math/Plane.js";
 import { Vector4 } from "../../math/Vector4.js";
 import { ClippingGroup } from "../../objects/ClippingGroup.js";
 import { Scene } from "../../scenes/Scene.js";
+/**
+ * Represents the state that is used to perform clipping via clipping planes.
+ * There is a default clipping context for each render context. When the
+ * scene holds instances of `ClippingGroup`, there will be a context for each
+ * group.
+ *
+ * @private
+ */
 declare class ClippingContext {
     version: number;
     clipIntersection: boolean | null;
@@ -16,11 +24,48 @@ declare class ClippingContext {
     shadowPass: boolean;
     viewMatrix?: Matrix4;
     parentVersion: number | null;
+    /**
+     * Constructs a new clipping context.
+     *
+     * @param {ClippingContext?} [parentContext=null] - A reference to the parent clipping context.
+     */
     constructor(parentContext?: ClippingContext | null);
+    /**
+     * Projects the given source clipping planes and writes the result into the
+     * destination array.
+     *
+     * @param {Array<Plane>} source - The source clipping planes.
+     * @param {Array<Vector4>} destination - The destination.
+     * @param {Number} offset - The offset.
+     */
     projectPlanes(source: readonly Plane[], destination: readonly Vector4[], offset: number): void;
+    /**
+     * Updates the root clipping context of a scene.
+     *
+     * @param {Scene} scene - The scene.
+     * @param {Camera} camera - The camera that is used to render the scene.
+     */
     updateGlobal(scene: Scene, camera: Camera): void;
+    /**
+     * Updates the clipping context.
+     *
+     * @param {ClippingContext} parentContext - The parent context.
+     * @param {ClippingGroup} clippingGroup - The clipping group this context belongs to.
+     */
     update(parentContext: ClippingContext, clippingGroup: ClippingGroup): void;
+    /**
+     * Returns a clipping context for the given clipping group.
+     *
+     * @param {ClippingGroup} clippingGroup - The clipping group.
+     * @return {ClippingContext} The clipping context.
+     */
     getGroupContext(clippingGroup: ClippingGroup): ClippingContext;
+    /**
+     * The count of union clipping planes.
+     *
+     * @type {Number}
+     * @readonly
+     */
     get unionClippingCount(): number;
 }
 export default ClippingContext;

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

@@ -1,10 +1,46 @@
 import { Color, ColorRepresentation } from "../../math/Color.js";
+/**
+ * A four-component version of {@link Color} which is internally
+ * used by the renderer to represents clear color with alpha as
+ * one object.
+ *
+ * @private
+ * @augments Color
+ */
 declare class Color4 extends Color {
     a: number;
+    /**
+     * Constructs a new four-component color.
+     *
+     * @param {Number|String} r - The red value.
+     * @param {Number} g - The green value.
+     * @param {Number} b - The blue value.
+     * @param {Number} [a=1] - The alpha value.
+     */
     constructor(color?: ColorRepresentation);
     constructor(r: number, g: number, b: number, a?: number);
+    /**
+     * Overwrites the default to honor alpha.
+     *
+     * @param {Number|String} r - The red value.
+     * @param {Number} g - The green value.
+     * @param {Number} b - The blue value.
+     * @param {Number} [a=1] - The alpha value.
+     * @return {Color4} A reference to this object.
+     */
     set(...args: [color: ColorRepresentation] | [r: number, g: number, b: number, a?: number]): this;
+    /**
+     * Overwrites the default to honor alpha.
+     *
+     * @param {Color4} color - The color to copy.
+     * @return {Color4} A reference to this object.
+     */
     copy(color: Color): this;
+    /**
+     * Overwrites the default to honor alpha.
+     *
+     * @return {Color4} The cloned color.
+     */
     clone(): this;
 }
 export default Color4;

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

@@ -1,8 +1,20 @@
 import Pipeline from "./Pipeline.js";
 import ProgrammableStage from "./ProgrammableStage.js";
+/**
+ * Class for representing compute pipelines.
+ *
+ * @private
+ * @augments Pipeline
+ */
 declare class ComputePipeline extends Pipeline {
     computeProgram: ProgrammableStage;
     readonly isComputePipeline: true;
+    /**
+     * Constructs a new render pipeline.
+     *
+     * @param {String} cacheKey - The pipeline's cache key.
+     * @param {ProgrammableStage} computeProgram - The pipeline's compute shader.
+     */
     constructor(cacheKey: string, computeProgram: ProgrammableStage);
 }
 export default ComputePipeline;

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

@@ -2,9 +2,22 @@ import { RenderTargetOptions } from "../../core/RenderTarget.js";
 import { WebGLCubeRenderTarget } from "../../renderers/WebGLCubeRenderTarget.js";
 import { Texture } from "../../textures/Texture.js";
 import { WebGLRenderer } from "../WebGLRenderer.js";
+/**
+ * This class represents a cube render target. It is a special version
+ * of `WebGLCubeRenderTarget` which is compatible with `WebGPURenderer`.
+ *
+ * @augments WebGLCubeRenderTarget
+ */
 declare class CubeRenderTarget extends WebGLCubeRenderTarget {
     readonly isCubeRenderTarget: true;
     constructor(size?: number, options?: RenderTargetOptions);
+    /**
+     * Converts the given equirectangular texture to a cube map.
+     *
+     * @param {Renderer} renderer - The renderer.
+     * @param {Texture} texture - The equirectangular texture.
+     * @return {CubeRenderTarget} A reference to this cube render target.
+     */
     fromEquirectangularTexture(renderer: WebGLRenderer, texture: Texture): this;
 }
 export default CubeRenderTarget;

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

@@ -1,3 +1,9 @@
+/**
+ * Data structure for the renderer. It is intended to manage
+ * data of objects in dictionaries.
+ *
+ * @private
+ */
 declare class DataMap<
     M extends {
         [key: string]: {
@@ -7,14 +13,38 @@ declare class DataMap<
     },
 > {
     data: WeakMap<M[keyof M]["key"], M[keyof M]["value"]>;
+    /**
+     * Constructs a new data map.
+     */
     constructor();
+    /**
+     * Returns the dictionary for the given object.
+     *
+     * @param {Object} object - The object.
+     * @return {Object} The dictionary.
+     */
     get<K extends M[keyof M]["key"]>(object: K): Extract<M[keyof M], {
         key: K;
     }>["value"];
+    /**
+     * Deletes the dictionary for the given object.
+     *
+     * @param {Object} object - The object.
+     * @return {Object?} The deleted dictionary.
+     */
     delete<K extends M[keyof M]["key"]>(object: K): Extract<M[keyof M], {
         key: K;
     }>["value"];
+    /**
+     * Returns `true` if the given object has a dictionary defined.
+     *
+     * @param {Object} object - The object to test.
+     * @return {Boolean} Whether a dictionary is defined or not.
+     */
     has(object: M[keyof M]["key"]): boolean;
+    /**
+     * Frees internal resources.
+     */
     dispose(): void;
 }
 export default DataMap;

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

@@ -10,6 +10,12 @@ import RenderObject from "./RenderObject.js";
 interface GeometryData {
     initialized?: boolean | undefined;
 }
+/**
+ * This renderer module manages geometries.
+ *
+ * @private
+ * @augments DataMap
+ */
 declare class Geometries extends DataMap<{
     geometry: {
         key: BufferGeometry;
@@ -20,13 +26,59 @@ declare class Geometries extends DataMap<{
     info: Info;
     wireframes: WeakMap<BufferGeometry, BufferAttribute>;
     attributeCall: WeakMap<BufferAttribute | InterleavedBufferAttribute | InterleavedBuffer, number>;
+    /**
+     * Constructs a new geometry management component.
+     *
+     * @param {Attributes} attributes - Renderer component for managing attributes.
+     * @param {Info} info - Renderer component for managing metrics and monitoring data.
+     */
     constructor(attributes: Attributes, info: Info);
+    /**
+     * Returns `true` if the given render object has an initialized geometry.
+     *
+     * @param {RenderObject} renderObject - The render object.
+     * @return {Boolean} Whether if the given render object has an initialized geometry or not.
+     */
     has(renderObject: RenderObject | BufferGeometry): boolean;
+    /**
+     * Prepares the geometry of the given render object for rendering.
+     *
+     * @param {RenderObject} renderObject - The render object.
+     */
     updateForRender(renderObject: RenderObject): void;
+    /**
+     * Initializes the geometry of the given render object.
+     *
+     * @param {RenderObject} renderObject - The render object.
+     */
     initGeometry(renderObject: RenderObject): void;
+    /**
+     * Updates the geometry attributes of the given render object.
+     *
+     * @param {RenderObject} renderObject - The render object.
+     */
     updateAttributes(renderObject: RenderObject): void;
+    /**
+     * Updates the given attribute.
+     *
+     * @param {BufferAttribute} attribute - The attribute to update.
+     * @param {Number} type - The attribute type.
+     */
     updateAttribute(attribute: BufferAttribute | InterleavedBufferAttribute, type: AttributeType): void;
+    /**
+     * Returns the indirect buffer attribute of the given render object.
+     *
+     * @param {RenderObject} renderObject - The render object.
+     * @return {BufferAttribute?} The indirect attribute. `null` if no indirect drawing is used.
+     */
     getIndirect(renderObject: RenderObject): import("./IndirectStorageBufferAttribute.js").default | null;
+    /**
+     * Returns the index of the given render object's geometry. This is implemented
+     * in a method to return a wireframe index if necessary.
+     *
+     * @param {RenderObject} renderObject - The render object.
+     * @return {BufferAttribute?} The index. Returns `null` for non-indexed geometries.
+     */
     getIndex(renderObject: RenderObject): BufferAttribute | null;
 }
 export default Geometries;