@types/three 0.171.0 → 0.172.0

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

@@ -17,6 +17,24 @@ import Nodes from "./nodes/Nodes.js";
 import RenderContext from "./RenderContext.js";
 import Renderer from "./Renderer.js";
 import RenderPipeline from "./RenderPipeline.js";
+/**
+ * A render object is the renderer's representation of single entity that gets drawn
+ * with a draw command. There is no unique mapping of render objects to 3D objects in the
+ * scene since render objects also depend from the used material, the current render context
+ * and the current scene's lighting.
+ *
+ * In general, the basic process of the renderer is:
+ *
+ * - Analyze the 3D objects in the scene and generate render lists containing render items.
+ * - Process the render lists by calling one or more render commands for each render item.
+ * - For each render command, request a render object and perform the draw.
+ *
+ * The module provides an interface to get data required for the draw command like the actual
+ * draw parameters or vertex buffers. It also holds a series of caching related methods since
+ * creating render objects should only be done when necessary.
+ *
+ * @private
+ */
 export default class RenderObject {
     _nodes: Nodes;
     _geometries: Geometries;
@@ -54,6 +72,20 @@ export default class RenderObject {
     onDispose: (() => void) | null;
     readonly isRenderObject: true;
     onMaterialDispose: () => void;
+    /**
+     * Constructs a new render object.
+     *
+     * @param {Nodes} nodes - Renderer component for managing nodes related logic.
+     * @param {Geometries} geometries - Renderer component for managing geometries.
+     * @param {Renderer} renderer - The renderer.
+     * @param {Object3D} object - The 3D object.
+     * @param {Material} material - The 3D object's material.
+     * @param {Scene} scene - The scene the 3D object belongs to.
+     * @param {Camera} camera - The camera the object should be rendered with.
+     * @param {LightsNode} lightsNode - The lights node.
+     * @param {RenderContext} renderContext - The render context.
+     * @param {ClippingContext} clippingContext - The clipping context.
+     */
     constructor(
         nodes: Nodes,
         geometries: Geometries,
@@ -66,34 +98,153 @@ export default class RenderObject {
         renderContext: RenderContext,
         clippingContext: ClippingContext | null,
     );
-    updateClipping(parent: ClippingContext): void;
+    /**
+     * Updates the clipping context.
+     *
+     * @param {ClippingContext} context - The clipping context to set.
+     */
+    updateClipping(context: ClippingContext): void;
+    /**
+     * Whether the clipping requires an update or not.
+     *
+     * @type {Boolean}
+     * @readonly
+     */
     get clippingNeedsUpdate(): boolean;
+    /**
+     * The number of clipping planes defined in context of hardware clipping.
+     *
+     * @type {Number}
+     * @readonly
+     */
     get hardwareClippingPlanes(): number;
+    /**
+     * Returns the node builder state of this render object.
+     *
+     * @return {NodeBuilderState} The node buider state.
+     */
     getNodeBuilderState(): NodeBuilderState;
+    /**
+     * Returns the node material observer of this render object.
+     *
+     * @return {NodeMaterialObserver} The node material observer.
+     */
     getMonitor(): NodeMaterialObserver;
+    /**
+     * Returns an array of bind groups of this render object.
+     *
+     * @return {Array<BindGroup>} The bindings.
+     */
     getBindings(): BindGroup[];
+    /**
+     * Returns the index of the render object's geometry.
+     *
+     * @return {BufferAttribute?} The index. Returns `null` for non-indexed geometries.
+     */
     getIndex(): BufferAttribute | null;
+    /**
+     * Returns the indirect buffer attribute.
+     *
+     * @return {BufferAttribute?} The indirect attribute. `null` if no indirect drawing is used.
+     */
     getIndirect(): import("./IndirectStorageBufferAttribute.js").default | null;
+    /**
+     * Returns an array that acts as a key for identifying the render object in a chain map.
+     *
+     * @return {Array<Object>} An array with object references.
+     */
     getChainArray(): readonly [
         Object3D<import("../../core/Object3D.js").Object3DEventMap>,
         Material,
         RenderContext,
         LightsNode,
     ];
+    /**
+     * This method is used when the geometry of a 3D object has been exchanged and the
+     * respective render object now requires an update.
+     *
+     * @param {BufferGeometry} geometry - The geometry to set.
+     */
     setGeometry(geometry: BufferGeometry): void;
+    /**
+     * Returns the buffer attributes of the render object. The returned array holds
+     * attribute definitions on geometry and node level.
+     *
+     * @return {Array<BufferAttribute>} An array with buffer attributes.
+     */
     getAttributes(): (BufferAttribute | InterleavedBufferAttribute)[];
+    /**
+     * Returns the vertex buffers of the render object.
+     *
+     * @return {Array<BufferAttribute|InterleavedBuffer>} An array with buffer attribute or interleaved buffers.
+     */
     getVertexBuffers(): (BufferAttribute | InterleavedBuffer)[] | null;
+    /**
+     * Returns the draw parameters for the render object.
+     *
+     * @return {{vertexCount: Number, firstVertex: Number, instanceCount: Number, firstInstance: Number}} The draw parameters.
+     */
     getDrawParameters(): {
         vertexCount: number;
         firstVertex: number;
         instanceCount: number;
         firstInstance: number;
     } | null;
+    /**
+     * Returns the render object's geometry cache key.
+     *
+     * The geometry cache key is part of the material cache key.
+     *
+     * @return {String} The geometry cache key.
+     */
     getGeometryCacheKey(): string;
+    /**
+     * Returns the render object's material cache key.
+     *
+     * The material cache key is part of the render object cache key.
+     *
+     * @return {String} The material cache key.
+     */
     getMaterialCacheKey(): number;
+    /**
+     * Whether the geometry requires an update or not.
+     *
+     * @type {Boolean}
+     * @readonly
+     */
     get needsGeometryUpdate(): boolean;
+    /**
+     * Whether the render object requires an update or not.
+     *
+     * Note: There are two distinct places where render objects are checked for an update.
+     *
+     * 1. In `RenderObjects.get()` which is executed when the render object is request. This
+     * method checks the `needsUpdate` flag and recreates the render object if necessary.
+     * 2. In `Renderer._renderObjectDirect()` right after getting the render object via
+     * `RenderObjects.get()`. The render object's NodeMaterialObserver is then used to detect
+     * a need for a refresh due to material, geometry or object related value changes.
+     *
+     * TODO: Investigate if it's possible to merge boths steps so there is only a single place
+     * that performs the 'needsUpdate' check.
+     *
+     * @type {Boolean}
+     * @readonly
+     */
     get needsUpdate(): boolean;
+    /**
+     * Returns the dynamic cache key which represents a key that is computed per draw command.
+     *
+     * @return {String} The cache key.
+     */
     getDynamicCacheKey(): string;
+    /**
+     * Returns the render object's cache key.
+     *
+     * @return {String} The cache key.
+     */
     getCacheKey(): string;
+    /**
+     * Frees internal resources.
+     */
     dispose(): void;
 }

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

@@ -13,6 +13,11 @@ import Pipelines from "./Pipelines.js";
 import RenderContext from "./RenderContext.js";
 import Renderer from "./Renderer.js";
 import RenderObject from "./RenderObject.js";
+/**
+ * This module manages the render objects of the renderer.
+ *
+ * @private
+ */
 declare class RenderObjects {
     renderer: Renderer;
     nodes: Nodes;
@@ -23,6 +28,16 @@ declare class RenderObjects {
     chainMaps: {
         [passId: string]: ChainMap<readonly [Object3D, Material, RenderContext, LightsNode], RenderObject>;
     };
+    /**
+     * Constructs a new render object management component.
+     *
+     * @param {Renderer} renderer - The renderer.
+     * @param {Nodes} nodes - Renderer component for managing nodes related logic.
+     * @param {Geometries} geometries - Renderer component for managing geometries.
+     * @param {Pipelines} pipelines - Renderer component for managing pipelines.
+     * @param {Bindings} bindings - Renderer component for managing bindings.
+     * @param {Info} info - Renderer component for managing metrics and monitoring data.
+     */
     constructor(
         renderer: Renderer,
         nodes: Nodes,
@@ -31,6 +46,19 @@ declare class RenderObjects {
         bindings: Bindings,
         info: Info,
     );
+    /**
+     * Returns a render object for the given object and state data.
+     *
+     * @param {Object3D} object - The 3D object.
+     * @param {Material} material - The 3D object's material.
+     * @param {Scene} scene - The scene the 3D object belongs to.
+     * @param {Camera} camera - The camera the 3D object should be rendered with.
+     * @param {LightsNode} lightsNode - The lights node.
+     * @param {RenderContext} renderContext - The render context.
+     * @param {ClippingContext} clippingContext - The clipping context.
+     * @param {String?} passId - An optional ID for identifying the pass.
+     * @return {RenderObject} The render object.
+     */
     get(
         object: Object3D,
         material: Material,
@@ -41,13 +69,38 @@ declare class RenderObjects {
         clippingContext: ClippingContext | null,
         passId?: string | undefined,
     ): RenderObject;
+    /**
+     * Returns a chain map for the given pass ID.
+     *
+     * @param {String} [passId='default'] - The pass ID.
+     * @return {ChainMap} The chain map.
+     */
     getChainMap(
         passId?: string,
     ): ChainMap<
         readonly [Object3D<import("../../core/Object3D.js").Object3DEventMap>, Material, RenderContext, LightsNode],
         RenderObject
     >;
+    /**
+     * Frees internal resources.
+     */
     dispose(): void;
+    /**
+     * Factory method for creating render objects with the given list of parameters.
+     *
+     * @param {Nodes} nodes - Renderer component for managing nodes related logic.
+     * @param {Geometries} geometries - Renderer component for managing geometries.
+     * @param {Renderer} renderer - The renderer.
+     * @param {Object3D} object - The 3D object.
+     * @param {Material} material - The object's material.
+     * @param {Scene} scene - The scene the 3D object belongs to.
+     * @param {Camera} camera - The camera the object should be rendered with.
+     * @param {LightsNode} lightsNode - The lights node.
+     * @param {RenderContext} renderContext - The render context.
+     * @param {ClippingContext} clippingContext - The clipping context.
+     * @param {String?} passId - An optional ID for identifying the pass.
+     * @return {RenderObject} The render object.
+     */
     createRenderObject(
         nodes: Nodes,
         geometries: Geometries,

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

@@ -1,8 +1,21 @@
 import Pipeline from "./Pipeline.js";
 import ProgrammableStage from "./ProgrammableStage.js";
+/**
+ * Class for representing render pipelines.
+ *
+ * @private
+ * @augments Pipeline
+ */
 declare class RenderPipeline extends Pipeline {
     vertexProgram: ProgrammableStage;
     fragmentProgram: ProgrammableStage;
+    /**
+     * Constructs a new render pipeline.
+     *
+     * @param {String} cacheKey - The pipeline's cache key.
+     * @param {ProgrammableStage} vertexProgram - The pipeline's vertex shader.
+     * @param {ProgrammableStage} fragmentProgram - The pipeline's fragment shader.
+     */
     constructor(cacheKey: string, vertexProgram: ProgrammableStage, fragmentProgram: ProgrammableStage);
 }
 export default RenderPipeline;