@types/three 0.170.0 → 0.172.0

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

@@ -1,24 +1,71 @@
 import { Camera } from "../../cameras/Camera.js";
-import { Material } from "../../materials/Material.js";
 import { Matrix3 } from "../../math/Matrix3.js";
 import { Matrix4 } from "../../math/Matrix4.js";
 import { Plane } from "../../math/Plane.js";
 import { Vector4 } from "../../math/Vector4.js";
-import Renderer from "./Renderer.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;
-    globalClippingCount: number;
-    localClippingCount: number;
-    localClippingEnabled: boolean | undefined;
-    localClipIntersection: boolean;
-    planes: Vector4[];
-    parentVersion: number;
+    clipIntersection: boolean | null;
+    cacheKey: string;
+    intersectionPlanes?: Plane[];
+    unionPlanes?: Plane[];
     viewNormalMatrix: Matrix3;
-    cacheKey: number;
-    viewMatrix?: Matrix4 | undefined;
-    constructor();
-    projectPlanes(source: readonly Plane[], offset: number): void;
-    updateGlobal(renderer: Renderer, camera: Camera): void;
-    update(parent: ClippingContext, material: Material): void;
+    clippingGroupContexts: WeakMap<ClippingGroup, 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;

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

@@ -1,4 +1,9 @@
 import { Object3D } from "../../core/Object3D.js";
+/**
+ * This renderer module provides a series of statistical information
+ * about the GPU memory and the rendering process. Useful for debugging
+ * and monitoring.
+ */
 declare class Info {
     autoReset: boolean;
     frame: number;
@@ -25,10 +30,32 @@ declare class Info {
         geometries: number;
         textures: number;
     };
+    /**
+     * Constructs a new info component.
+     */
     constructor();
+    /**
+     * This method should be executed per draw call and updates the corresponding metrics.
+     *
+     * @param {Object3D} object - The 3D object that is going to be rendered.
+     * @param {Number} count - The vertex or index count.
+     * @param {Number} instanceCount - The instance count.
+     */
     update(object: Object3D, count: number, instanceCount: number): void;
+    /**
+     * Used by async render methods to updated timestamp metrics.
+     *
+     * @param {('render'|'compute')} type - The type of render call.
+     * @param {Number} time - The duration of the compute/render call in milliseconds.
+     */
     updateTimestamp(type: "render" | "compute", time: number): void;
+    /**
+     * Resets frame related metrics.
+     */
     reset(): void;
+    /**
+     * Performs a complete reset of the object.
+     */
     dispose(): void;
 }
 export default Info;

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

@@ -1,6 +1,17 @@
+/**
+ * Abstract class for representing pipelines.
+ *
+ * @private
+ * @abstract
+ */
 declare class Pipeline {
     cacheKey: string;
     usedTimes: number;
+    /**
+     * Constructs a new pipeline.
+     *
+     * @param {String} cacheKey - The pipeline's cache key.
+     */
     constructor(cacheKey: string);
 }
 export default Pipeline;

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

@@ -16,6 +16,12 @@ interface ComputeNodeData {
 interface RenderObjectData {
     pipeline: RenderPipeline;
 }
+/**
+ * This renderer module manages the pipelines of the renderer.
+ *
+ * @private
+ * @augments DataMap
+ */
 declare class Pipelines extends DataMap<{
     computeNode: {
         key: ComputeNode;
@@ -35,18 +41,73 @@ declare class Pipelines extends DataMap<{
         fragment: Map<string, ProgrammableStage>;
         compute: Map<string, ProgrammableStage>;
     };
+    /**
+     * Constructs a new pipeline management component.
+     *
+     * @param {Backend} backend - The renderer's backend.
+     * @param {Nodes} nodes - Renderer component for managing nodes related logic.
+     */
     constructor(backend: Backend, nodes: Nodes);
+    /**
+     * Returns a compute pipeline for the given compute node.
+     *
+     * @param {Node} computeNode - The compute node.
+     * @param {Array<BindGroup>} bindings - The bindings.
+     * @return {ComputePipeline} The compute pipeline.
+     */
     getForCompute(computeNode: ComputeNode, bindings: Binding[]): ComputePipeline;
+    /**
+     * Returns a render pipeline for the given render object.
+     *
+     * @param {RenderObject} renderObject - The render object.
+     * @param {Array<Promise>?} [promises=null] - An array of compilation promises which is only relevant in context of `Renderer.compileAsync()`.
+     * @return {RenderPipeline} The render pipeline.
+     */
     getForRender(renderObject: RenderObject, promises?: Promise<void>[] | null): RenderPipeline;
+    /**
+     * Deletes the pipeline for the given render object.
+     *
+     * @param {RenderObject} object - The render object.
+     * @return {Object?} The deleted dictionary.
+     */
     delete(object: ComputeNode | RenderObject): never;
+    /**
+     * Frees internal resources.
+     */
     dispose(): void;
+    /**
+     * Updates the pipeline for the given render object.
+     *
+     * @param {RenderObject} renderObject - The render object.
+     */
     updateForRender(renderObject: RenderObject): void;
+    /**
+     * Returns a compute pipeline for the given parameters.
+     *
+     * @private
+     * @param {Node} computeNode - The compute node.
+     * @param {ProgrammableStage} stageCompute - The programmable stage representing the compute shader.
+     * @param {String} cacheKey - The cache key.
+     * @param {Array<BindGroup>} bindings - The bindings.
+     * @return {ComputePipeline} The compute pipeline.
+     */
     _getComputePipeline(
         computeNode: ComputeNode,
         stageCompute: ProgrammableStage,
         cacheKey: string,
         bindings: Binding[],
     ): ComputePipeline;
+    /**
+     * Returns a render pipeline for the given parameters.
+     *
+     * @private
+     * @param {RenderObject} renderObject - The render object.
+     * @param {ProgrammableStage} stageVertex - The programmable stage representing the vertex shader.
+     * @param {ProgrammableStage} stageFragment - The programmable stage representing the fragment shader.
+     * @param {String} cacheKey - The cache key.
+     * @param {Array} promises - An array of compilation promises which is only relevant in context of `Renderer.compileAsync()`.
+     * @return {ComputePipeline} The compute pipeline.
+     */
     _getRenderPipeline(
         renderObject: RenderObject,
         stageVertex: ProgrammableStage,
@@ -54,15 +115,58 @@ declare class Pipelines extends DataMap<{
         cacheKey: string,
         promises: Promise<void>[] | null,
     ): RenderPipeline;
+    /**
+     * Computes a cache key representing a compute pipeline.
+     *
+     * @private
+     * @param {Node} computeNode - The compute node.
+     * @param {ProgrammableStage} stageCompute - The programmable stage representing the compute shader.
+     * @return {String} The cache key.
+     */
     _getComputeCacheKey(computeNode: ComputeNode, stageCompute: ProgrammableStage): string;
+    /**
+     * Computes a cache key representing a render pipeline.
+     *
+     * @private
+     * @param {RenderObject} renderObject - The render object.
+     * @param {ProgrammableStage} stageVertex - The programmable stage representing the vertex shader.
+     * @param {ProgrammableStage} stageFragment - The programmable stage representing the fragment shader.
+     * @return {String} The cache key.
+     */
     _getRenderCacheKey(
         renderObject: RenderObject,
         stageVertex: ProgrammableStage,
         stageFragment: ProgrammableStage,
     ): string;
+    /**
+     * Releases the given pipeline.
+     *
+     * @private
+     * @param {Pipeline} pipeline - The pipeline to release.
+     */
     _releasePipeline(pipeline: Pipeline): void;
+    /**
+     * Releases the shader program.
+     *
+     * @private
+     * @param {Object} program - The shdaer program to release.
+     */
     _releaseProgram(program: ProgrammableStage): void;
+    /**
+     * Returns `true` if the compute pipeline for the given compute node requires an update.
+     *
+     * @private
+     * @param {Node} computeNode - The compute node.
+     * @return {Boolean} Whether the compute pipeline for the given compute node requires an update or not.
+     */
     _needsComputeUpdate(computeNode: ComputeNode): boolean;
+    /**
+     * Returns `true` if the render pipeline for the given render object requires an update.
+     *
+     * @private
+     * @param {RenderObject} renderObject - The render object.
+     * @return {Boolean} Whether the render object for the given render object requires an update or not.
+     */
     _needsRenderUpdate(renderObject: RenderObject): true | void;
 }
 export default Pipelines;