@types/three 0.171.0 → 0.172.0

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;

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

@@ -1,13 +1,31 @@
 import NodeAttribute from "../../nodes/core/NodeAttribute.js";
+/**
+ * Class for representing programmable stages which are vertex,
+ * fragment or compute shaders. Unlike fixed-function states (like blending),
+ * they represent the programmable part of a pipeline.
+ *
+ * @private
+ */
 declare class ProgrammableStage {
     id: number;
     code: string;
     stage: "compute" | "vertex" | "fragment";
+    name: string;
     attributes: NodeAttribute[] | null;
     usedTimes: number;
+    /**
+     * Constructs a new programmable stage.
+     *
+     * @param {String} code - The shader code.
+     * @param {('vertex'|'fragment'|'compute')} stage - The type of stage.
+     * @param {String} name - The name of the shader.
+     * @param {Array<Object>?} [transforms=null] - The transforms (only relevant for compute stages with WebGL 2 which uses Transform Feedback).
+     * @param {Array<Object>?} [attributes=null] - The attributes (only relevant for compute stages with WebGL 2 which uses Transform Feedback).
+     */
     constructor(
         code: string,
-        type: "compute" | "vertex" | "fragment",
+        stage: "compute" | "vertex" | "fragment",
+        name: string,
         transforms?: null,
         attributes?: NodeAttribute[] | null,
     );

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

@@ -1,9 +1,20 @@
 import { Camera } from "../../cameras/Camera.js";
-import { Object3D } from "../../core/Object3D.js";
+import BundleGroup from "./BundleGroup.js";
+/**
+ * This module is used to represent render bundles inside the renderer
+ * for further processing.
+ *
+ * @private
+ */
 declare class RenderBundle {
-    scene: Object3D;
+    bundleGroup: BundleGroup;
     camera: Camera;
-    constructor(scene: Object3D, camera: Camera);
-    clone(): RenderBundle & this;
+    /**
+     * Constructs a new bundle group.
+     *
+     * @param {BundleGroup} bundleGroup - The bundle group.
+     * @param {Camera} camera - The camera the bundle group is rendered with.
+     */
+    constructor(bundleGroup: BundleGroup, camera: Camera);
 }
 export default RenderBundle;

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

@@ -2,10 +2,28 @@ import { Camera } from "../../cameras/Camera.js";
 import BundleGroup from "./BundleGroup.js";
 import ChainMap from "./ChainMap.js";
 import RenderBundle from "./RenderBundle.js";
+/**
+ * This renderer module manages render bundles.
+ *
+ * @private
+ */
 declare class RenderBundles {
-    lists: ChainMap<readonly [BundleGroup, Camera], RenderBundle>;
+    bundles: ChainMap<readonly [BundleGroup, Camera], RenderBundle>;
+    /**
+     * Constructs a new render bundle management component.
+     */
     constructor();
-    get(scene: BundleGroup, camera: Camera): RenderBundle;
+    /**
+     * Returns a render bundle for the given bundle group and camera.
+     *
+     * @param {BundleGroup} bundleGroup - The bundle group.
+     * @param {Camera} camera - The camera the bundle group is rendered with.
+     * @return {RenderBundle} The render bundle.
+     */
+    get(bundleGroup: BundleGroup, camera: Camera): RenderBundle;
+    /**
+     * Frees all internal resources.
+     */
     dispose(): void;
 }
 export default RenderBundles;

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

@@ -3,6 +3,14 @@ import { Vector4 } from "../../math/Vector4.js";
 import { DepthTexture } from "../../textures/DepthTexture.js";
 import { Texture } from "../../textures/Texture.js";
 import ClippingContext from "./ClippingContext.js";
+/**
+ * Any render or compute command is executed in a specific context that defines
+ * the state of the renderer and its backend. Typical examples for such context
+ * data are the current clear values or data from the active framebuffer. This
+ * module is used to represent these contexts as objects.
+ *
+ * @private
+ */
 declare class RenderContext {
     id: number;
     color: boolean;
@@ -36,8 +44,22 @@ declare class RenderContext {
     renderTarget?: RenderTarget | undefined;
     activeMipmapLevel?: number | undefined;
     occlusionQueryCount?: number | undefined;
+    /**
+     * Constructs a new render context.
+     */
     constructor();
+    /**
+     * Returns the cache key of this render context.
+     *
+     * @return {Number} The cache key.
+     */
     getCacheKey(): number;
 }
+/**
+ * Computes a cache key for the given render context.
+ *
+ * @param {RenderContext} renderContext - The render context.
+ * @return {Number} The cache key.
+ */
 export declare function getCacheKey(renderContext: RenderContext): number;
 export default RenderContext;

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

@@ -3,15 +3,54 @@ import { Object3D } from "../../core/Object3D.js";
 import { RenderTarget } from "../../core/RenderTarget.js";
 import ChainMap from "./ChainMap.js";
 import RenderContext from "./RenderContext.js";
+/**
+ * This module manages the render contexts of the renderer.
+ *
+ * @private
+ */
 declare class RenderContexts {
     chainMaps: {
-        [attachmentState: string]: ChainMap<readonly [Object3D, Camera], RenderContext> | undefined;
+        [attachmentState: string]:
+            | ChainMap<
+                | readonly [Object3D, Camera]
+                | readonly [Object3D, Camera, {
+                    id: "default";
+                }],
+                RenderContext
+            >
+            | undefined;
     };
+    /**
+     * Constructs a new render context management component.
+     */
     constructor();
-    get(scene: Object3D, camera: Camera, renderTarget?: RenderTarget | null): RenderContext;
+    /**
+     * Returns a render context for the given scene, camera and render target.
+     *
+     * @param {Scene?} [scene=null] - The scene. The parameter can become `null` e.g. when the renderer clears a render target.
+     * @param {Camera?} [camera=null] - The camera that is used to render the scene. The parameter can become `null` e.g. when the renderer clears a render target.
+     * @param {RenderTarget?} [renderTarget=null] - The active render target.
+     * @return {RenderContext} The render context.
+     */
+    get(scene?: Object3D | null, camera?: Camera | null, renderTarget?: RenderTarget | null): RenderContext;
+    /**
+     * Returns a chain map for the given attachment state.
+     *
+     * @param {String} attachmentState - The attachment state.
+     * @return {ChainMap} The chain map.
+     */
     getChainMap(
         attachmentState: string,
-    ): ChainMap<readonly [Object3D<import("../../core/Object3D.js").Object3DEventMap>, Camera], RenderContext>;
+    ): ChainMap<
+        | readonly [Object3D<import("../../core/Object3D.js").Object3DEventMap>, Camera]
+        | readonly [Object3D<import("../../core/Object3D.js").Object3DEventMap>, Camera, {
+            id: "default";
+        }],
+        RenderContext
+    >;
+    /**
+     * Frees internal resources.
+     */
     dispose(): void;
 }
 export default RenderContexts;

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

@@ -23,6 +23,17 @@ export interface RenderItem {
     group: GeometryGroup | null;
     clippingContext: ClippingContext | null;
 }
+/**
+ * When the renderer analyzes the scene at the beginning of a render call,
+ * it stores 3D object for further processing in render lists. Depending on the
+ * properties of a 3D objects (like their transformation or material state), the
+ * objects are maintained in ordered lists for the actual rendering.
+ *
+ * Render lists are unique per scene and camera combination.
+ *
+ * @private
+ * @augments Pipeline
+ */
 declare class RenderList {
     renderItems: RenderItem[];
     renderItemsIndex: number;
@@ -35,8 +46,38 @@ declare class RenderList {
     scene: Object3D;
     camera: Camera;
     occlusionQueryCount: number;
+    /**
+     * Constructs a render list.
+     *
+     * @param {Lighting} lighting - The lighting management component.
+     * @param {Scene} scene - The scene.
+     * @param {Camera} camera - The camera the scene is rendered with.
+     */
     constructor(lighting: Lighting, scene: Object3D, camera: Camera);
+    /**
+     * This method is called right at the beginning of a render call
+     * before the scene is analyzed. It prepares the internal data
+     * structures for the upcoming render lists generation.
+     *
+     * @return {RenderList} A reference to this render list.
+     */
     begin(): this;
+    /**
+     * Returns a render item for the giving render item state. The state is defined
+     * by a series of object-related parameters.
+     *
+     * The method avoids object creation by holding render items and reusing them in
+     * subsequent render calls (just with different property values).
+     *
+     * @param {Object3D} object - The 3D object.
+     * @param {BufferGeometry} geometry - The 3D object's geometry.
+     * @param {Material} material - The 3D object's material.
+     * @param {Number} groupOrder - The current group order.
+     * @param {Number} z - Th 3D object's depth value (z value in clip space).
+     * @param {Number?} group - {Object?} group - Only relevant for objects using multiple materials. This represents a group entry from the respective `BufferGeometry`.
+     * @param {ClippingContext} clippingContext - The current clipping context.
+     * @return {Object} The render item.
+     */
     getNextRenderItem(
         object: Object3D,
         geometry: BufferGeometry,
@@ -46,6 +87,18 @@ declare class RenderList {
         group: GeometryGroup | null,
         clippingContext: ClippingContext | null,
     ): RenderItem;
+    /**
+     * Pushes the given object as a render item to the internal render lists.
+     * The selected lists depend on the object properties.
+     *
+     * @param {Object3D} object - The 3D object.
+     * @param {BufferGeometry} geometry - The 3D object's geometry.
+     * @param {Material} material - The 3D object's material.
+     * @param {Number} groupOrder - The current group order.
+     * @param {Number} z - Th 3D object's depth value (z value in clip space).
+     * @param {Number?} group - {Object?} group - Only relevant for objects using multiple materials. This represents a group entry from the respective `BufferGeometry`.
+     * @param {ClippingContext} clippingContext - The current clipping context.
+     */
     push(
         object: Object3D,
         geometry: BufferGeometry,
@@ -55,6 +108,18 @@ declare class RenderList {
         group: GeometryGroup | null,
         clippingContext: ClippingContext | null,
     ): void;
+    /**
+     * Inserts the given object as a render item at the start of the internal render lists.
+     * The selected lists depend on the object properties.
+     *
+     * @param {Object3D} object - The 3D object.
+     * @param {BufferGeometry} geometry - The 3D object's geometry.
+     * @param {Material} material - The 3D object's material.
+     * @param {Number} groupOrder - The current group order.
+     * @param {Number} z - Th 3D object's depth value (z value in clip space).
+     * @param {Number?} group - {Object?} group - Only relevant for objects using multiple materials. This represents a group entry from the respective `BufferGeometry`.
+     * @param {ClippingContext} clippingContext - The current clipping context.
+     */
     unshift(
         object: Object3D,
         geometry: BufferGeometry,
@@ -64,12 +129,32 @@ declare class RenderList {
         group: GeometryGroup | null,
         clippingContext: ClippingContext | null,
     ): void;
+    /**
+     * Pushes render bundle group data into the render list.
+     *
+     * @param {Object} group - Bundle group data.
+     */
     pushBundle(group: Bundle): void;
+    /**
+     * Pushes a light into the render list.
+     *
+     * @param {Light} light - The light.
+     */
     pushLight(light: Light): void;
+    /**
+     * Sorts the internal render lists.
+     *
+     * @param {Function} customOpaqueSort - A custom sort function for opaque objects.
+     * @param {Function} customTransparentSort -  A custom sort function for transparent objects.
+     */
     sort(
         customOpaqueSort: ((a: RenderItem, b: RenderItem) => number) | null,
         customTransparentSort: ((a: RenderItem, b: RenderItem) => number) | null,
     ): void;
+    /**
+     * This method performs finalizing tasks right after the render lists
+     * have been generated.
+     */
     finish(): void;
 }
 export default RenderList;

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

@@ -3,11 +3,32 @@ import { Object3D } from "../../core/Object3D.js";
 import ChainMap from "./ChainMap.js";
 import Lighting from "./Lighting.js";
 import RenderList from "./RenderList.js";
+/**
+ * This renderer module manages the render lists which are unique
+ * per scene and camera combination.
+ *
+ * @private
+ */
 declare class RenderLists {
     lighting: Lighting;
     lists: ChainMap<readonly [Object3D, Camera], RenderList>;
+    /**
+     * Constructs a render lists management component.
+     *
+     * @param {Lighting} lighting - The lighting management component.
+     */
     constructor(lighting: Lighting);
+    /**
+     * Returns a render list for the given scene and camera.
+     *
+     * @param {Scene} scene - The scene.
+     * @param {Camera} camera - The camera.
+     * @return {RenderList} The render list.
+     */
     get(scene: Object3D, camera: Camera): RenderList;
+    /**
+     * Frees all internal resources.
+     */
     dispose(): void;
 }
 export default RenderLists;