Update three.js (#1478)

* Update three.js

* Add src

* Update patch and delete src

* Update declarations

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

@@ -1,7 +1,9 @@
 import Binding from "./Binding.js";
 import NodeUniformsGroup from "./nodes/NodeUniformsGroup.js";
 /**
- * Represents a bind group.
+ * 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
  */

types/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;

types/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,

types/three/src/renderers/common/nodes/Nodes.d.ts

@@ -46,7 +46,20 @@ declare module "../../../scenes/Scene.js" {
         fogNode?: ShaderNodeObject<Node> | null | undefined;
     }
 }
+/**
+ * This renderer module manages node-related objects and is the
+ * primary interface between the renderer and the node system.
+ *
+ * @private
+ * @augments DataMap
+ */
 declare class Nodes extends DataMap<{
+    /**
+     * Constructs a new nodes management component.
+     *
+     * @param {Renderer} renderer - The renderer.
+     * @param {Backend} backend - The renderer's backend.
+     */
     nodeUniformsGroup: {
         key: NodeUniformsGroup;
         value: NodeUniformsGroupData;
@@ -79,27 +92,128 @@ declare class Nodes extends DataMap<{
         [type: string]: WeakMap<object, ShaderNodeObject<Node> | undefined>;
     };
     constructor(renderer: Renderer, backend: Backend);
+    /**
+     * Returns `true` if the given node uniforms group must be updated or not.
+     *
+     * @param {NodeUniformsGroup} nodeUniformsGroup - The node uniforms group.
+     * @return {Boolean} Whether the node uniforms group requires an update or not.
+     */
     updateGroup(nodeUniformsGroup: NodeUniformsGroup): boolean;
+    /**
+     * Returns the cache key for the given render object.
+     *
+     * @param {RenderObject} renderObject - The render object.
+     * @return {Number} The cache key.
+     */
     getForRenderCacheKey(renderObject: RenderObject): string;
+    /**
+     * Returns a node builder state for the given render object.
+     *
+     * @param {RenderObject} renderObject - The render object.
+     * @return {NodeBuilderState} The node builder state.
+     */
     getForRender(renderObject: RenderObject): NodeBuilderState;
+    /**
+     * Deletes the given object from the internal data map
+     *
+     * @param {Any} object - The object to delete.
+     * @return {Object?} The deleted dictionary.
+     */
     delete(
         object: NodeUniformsGroup | RenderObject | ComputeNode | Scene,
     ): SceneData | RenderObjectData | NodeUniformsGroupData | ComputeNodeData;
+    /**
+     * Returns a node builder state for the given compute node.
+     *
+     * @param {Node} computeNode - The compute node.
+     * @return {NodeBuilderState} The node builder state.
+     */
     getForCompute(computeNode: ComputeNode): NodeBuilderState;
+    /**
+     * Creates a node builder state for the given node builder.
+     *
+     * @private
+     * @param {NodeBuilder} nodeBuilder - The node builder.
+     * @return {NodeBuilderState} The node builder state.
+     */
     _createNodeBuilderState(nodeBuilder: NodeBuilder): NodeBuilderState;
+    /**
+     * Returns an environment node for the current configured
+     * scene environment.
+     *
+     * @param {Scene} scene - The scene.
+     * @return {Node} A node representing the current scene environment.
+     */
     getEnvironmentNode(scene: Scene): ShaderNodeObject<Node> | null;
+    /**
+     * Returns a background node for the current configured
+     * scene background.
+     *
+     * @param {Scene} scene - The scene.
+     * @return {Node} A node representing the current scene background.
+     */
     getBackgroundNode(scene: Scene): ShaderNodeObject<Node> | null;
+    /**
+     * Returns a fog node for the current configured scene fog.
+     *
+     * @param {Scene} scene - The scene.
+     * @return {Node} A node representing the current scene fog.
+     */
     getFogNode(scene: Scene): ShaderNodeObject<Node> | null;
+    /**
+     * Returns a cache key for the given scene and lights node.
+     * This key is used by `RenderObject` as a part of the dynamic
+     * cache key (a key that must be checked every time the render
+     * objects is drawn).
+     *
+     * @param {Scene} scene - The scene.
+     * @param {LightsNode} lightsNode - The lights node.
+     * @return {Number} The cache key.
+     */
     getCacheKey(scene: Scene, lightsNode: LightsNode): string;
+    /**
+     * A boolean that indicates whether tone mapping should be enabled
+     * or not.
+     *
+     * @type {Boolean}
+     */
     get isToneMappingState(): boolean;
+    /**
+     * If a scene background is configured, this method makes sure to
+     * represent the background with a corresponding node-based implementation.
+     *
+     * @param {Scene} scene - The scene.
+     */
     updateBackground(scene: Scene): void;
+    /**
+     * This method is part of the caching of nodes which are used to represents the
+     * scene's background, fog or environment.
+     *
+     * @param {String} type - The type of object to cache.
+     * @param {Object} object - The object.
+     * @param {Function} callback - A callback that produces a node representation for the given object.
+     * @param {Boolean} [forceUpdate=false] - Whether an update should be enforced or not.
+     * @return {Node} The node representation.
+     */
     getCacheNode(
         type: string,
         object: object,
         callback: () => ShaderNodeObject<Node> | undefined,
         forceUpdate?: boolean,
     ): ShaderNodeObject<Node> | undefined;
+    /**
+     * If a scene fog is configured, this method makes sure to
+     * represent the fog with a corresponding node-based implementation.
+     *
+     * @param {Scene} scene - The scene.
+     */
     updateFog(scene: Scene): void;
+    /**
+     * If a scene environment is configured, this method makes sure to
+     * represent the environment with a corresponding node-based implementation.
+     *
+     * @param {Scene} scene - The scene.
+     */
     updateEnvironment(scene: Scene): void;
     getNodeFrame(
         renderer?: Renderer,
@@ -109,14 +223,66 @@ declare class Nodes extends DataMap<{
         material?: Material | null,
     ): NodeFrame;
     getNodeFrameForRender(renderObject: RenderObject): NodeFrame;
+    /**
+     * Returns the current output cache key.
+     *
+     * @return {String} The output cache key.
+     */
     getOutputCacheKey(): string;
+    /**
+     * Checks if the output configuration (tone mapping and color space) for
+     * the given target has changed.
+     *
+     * @param {Texture} outputTarget - The output target.
+     * @return {Boolean} Whether the output configuration has changed or not.
+     */
     hasOutputChange(outputTarget: Texture): boolean;
-    getOutputNode(outputTexture: Texture): ShaderNodeObject<Node>;
+    /**
+     * Returns a node that represents the output configuration (tone mapping and
+     * color space) for the current target.
+     *
+     * @param {Texture} outputTarget - The output target.
+     * @return {Node} The output node.
+     */
+    getOutputNode(outputTarget: Texture): ShaderNodeObject<Node>;
+    /**
+     * Triggers the call of `updateBefore()` methods
+     * for all nodes of the given render object.
+     *
+     * @param {RenderObject} renderObject - The render object.
+     */
     updateBefore(renderObject: RenderObject): void;
+    /**
+     * Triggers the call of `updateAfter()` methods
+     * for all nodes of the given render object.
+     *
+     * @param {RenderObject} renderObject - The render object.
+     */
     updateAfter(renderObject: RenderObject): void;
+    /**
+     * Triggers the call of `update()` methods
+     * for all nodes of the given compute node.
+     *
+     * @param {Node} computeNode - The compute node.
+     */
     updateForCompute(computeNode: ComputeNode): void;
+    /**
+     * Triggers the call of `update()` methods
+     * for all nodes of the given compute node.
+     *
+     * @param {RenderObject} renderObject - The render object.
+     */
     updateForRender(renderObject: RenderObject): void;
+    /**
+     * Returns `true` if the given render object requires a refresh.
+     *
+     * @param {RenderObject} renderObject - The render object.
+     * @return {Boolean} Whether the given render object requires a refresh or not.
+     */
     needsRefresh(renderObject: RenderObject): boolean;
+    /**
+     * Frees the intenral resources.
+     */
     dispose(): void;
 }
 export default Nodes;