@types/three 0.171.0 → 0.173.0

three/src/nodes/core/Node.d.ts

@@ -57,6 +57,11 @@ interface NodeJSONOutputData {
     images?: unknown[];
     nodes?: NodeJSONOutputData[];
 }
+/**
+ * Base class for all nodes.
+ *
+ * @augments EventDispatcher
+ */
 declare class Node extends EventDispatcher<{
     dispose: {};
 }> {
@@ -73,39 +78,279 @@ declare class Node extends EventDispatcher<{
     readonly isNode: true;
     readonly id: number;
     self?: this;
+    /**
+     * Constructs a new node.
+     *
+     * @param {String?} nodeType - The node type.
+     */
     constructor(nodeType?: string | null);
+    /**
+     * Set this property to `true` when the node should be regenerated.
+     *
+     * @type {Boolean}
+     * @default false
+     * @param {boolean} value
+     */
     set needsUpdate(value: boolean);
+    /**
+     * The type of the class. The value is usually the constructor name.
+     *
+     * @type {String}
+     * @readonly
+     */
     get type(): string | undefined;
+    /**
+     * Convenient method for defining {@link Node#update}.
+     *
+     * @param {Function} callback - The update method.
+     * @param {String} updateType - The update type.
+     * @return {Node} A reference to this node.
+     */
     onUpdate(callback: (this: this, frame: NodeFrame) => unknown, updateType: NodeUpdateType): this;
+    /**
+     * Convenient method for defining {@link Node#update}. Similar to {@link Node#onUpdate}, but
+     * this method automatically sets the update type to `FRAME`.
+     *
+     * @param {Function} callback - The update method.
+     * @return {Node} A reference to this node.
+     */
     onFrameUpdate(callback: (this: this, frame: NodeFrame) => void): this;
+    /**
+     * Convenient method for defining {@link Node#update}. Similar to {@link Node#onUpdate}, but
+     * this method automatically sets the update type to `RENDER`.
+     *
+     * @param {Function} callback - The update method.
+     * @return {Node} A reference to this node.
+     */
     onRenderUpdate(callback: (this: this, frame: NodeFrame) => void): this;
+    /**
+     * Convenient method for defining {@link Node#update}. Similar to {@link Node#onUpdate}, but
+     * this method automatically sets the update type to `OBJECT`.
+     *
+     * @param {Function} callback - The update method.
+     * @return {Node} A reference to this node.
+     */
     onObjectUpdate(callback: (this: this, frame: NodeFrame) => void): this;
+    /**
+     * Convenient method for defining {@link Node#updateReference}.
+     *
+     * @param {Function} callback - The update method.
+     * @return {Node} A reference to this node.
+     */
     onReference(callback: (this: this, frame: NodeBuilder | NodeFrame) => unknown): this;
+    /**
+     * The `this` reference might point to a Proxy so this method can be used
+     * to get the reference to the actual node instance.
+     *
+     * @return {Node} A reference to the node.
+     */
     getSelf(): this;
+    /**
+     * Nodes might refer to other objects like materials. This method allows to dynamically update the reference
+     * to such objects based on a given state (e.g. the current node frame or builder).
+     *
+     * @param {Any} state - This method can be invocated in different contexts so `state` can refer to any object type.
+     * @return {Any} The updated reference.
+     */
     updateReference(state: NodeBuilder | NodeFrame): unknown;
+    /**
+     * By default this method returns the value of the {@link Node#global} flag. This method
+     * can be overwritten in derived classes if an analytical way is required to determine the
+     * global status.
+     *
+     * @param {NodeBuilder} builder - The current node builder.
+     * @return {Boolean} Whether this node is global or not.
+     */
     isGlobal(builder: NodeBuilder): boolean;
+    /**
+     * Generator function that can be used to iterate over the child nodes.
+     *
+     * @generator
+     * @yields {Node} A child node.
+     */
     getChildren(): Generator<Node, void, unknown>;
+    /**
+     * Calling this method dispatches the `dispose` event. This event can be used
+     * to register event listeners for clean up tasks.
+     */
     dispose(): void;
+    /**
+     * Callback for {@link Node#traverse}.
+     *
+     * @callback traverseCallback
+     * @param {Node} node - The current node.
+     */
+    /**
+     * Can be used to traverse through the node's hierarchy.
+     *
+     * @param {traverseCallback} callback - A callback that is executed per node.
+     */
     traverse(callback: (node: Node) => void): void;
+    /**
+     * Returns the cache key for this node.
+     *
+     * @param {Boolean} [force=false] - When set to `true`, a recomputation of the cache key is forced.
+     * @return {Number} The cache key of the node.
+     */
     getCacheKey(force?: boolean): number;
+    /**
+     * Generate a custom cache key for this node.
+     *
+     * @return {Number} The cache key of the node.
+     */
+    customCacheKey(): number;
+    /**
+     * Returns the references to this node which is by default `this`.
+     *
+     * @return {Node} A reference to this node.
+     */
     getScope(): this;
+    /**
+     * Returns the hash of the node which is used to identify the node. By default it's
+     * the {@link Node#uuid} however derived node classes might have to overwrite this method
+     * depending on their implementation.
+     *
+     * @param {NodeBuilder} builder - The current node builder.
+     * @return {String} The hash.
+     */
     getHash(builder: NodeBuilder): string;
+    /**
+     * Returns the update type of {@link Node#update}.
+     *
+     * @return {NodeUpdateType} The update type.
+     */
     getUpdateType(): NodeUpdateType;
+    /**
+     * Returns the update type of {@link Node#updateBefore}.
+     *
+     * @return {NodeUpdateType} The update type.
+     */
     getUpdateBeforeType(): NodeUpdateType;
+    /**
+     * Returns the update type of {@link Node#updateAfter}.
+     *
+     * @return {NodeUpdateType} The update type.
+     */
     getUpdateAfterType(): NodeUpdateType;
+    /**
+     * Certain types are composed of multiple elements. For example a `vec3`
+     * is composed of three `float` values. This method returns the type of
+     * these elements.
+     *
+     * @param {NodeBuilder} builder - The current node builder.
+     * @return {String} The type of the node.
+     */
     getElementType(builder: NodeBuilder): "bool" | "int" | "float" | "vec2" | "vec3" | "vec4" | "uint" | null;
+    /**
+     * Returns the node member type for the given name.
+     *
+     * @param {NodeBuilder} builder - The current node builder.
+     * @param {String} name - The name of the member.
+     * @return {String} The type of the node.
+     */
+    getMemberType(builder: NodeBuilder, name: string): string;
+    /**
+     * Returns the node's type.
+     *
+     * @param {NodeBuilder} builder - The current node builder.
+     * @return {String} The type of the node.
+     */
     getNodeType(builder: NodeBuilder): string | null;
+    /**
+     * This method is used during the build process of a node and ensures
+     * equal nodes are not built multiple times but just once. For example if
+     * `attribute( 'uv' )` is used multiple times by the user, the build
+     * process makes sure to process just the first node.
+     *
+     * @param {NodeBuilder} builder - The current node builder.
+     * @return {Node} The shared node if possible. Otherwise `this` is returned.
+     */
     getShared(builder: NodeBuilder): Node;
+    /**
+     * Represents the setup stage which is the first step of the build process, see {@link Node#build} method.
+     * This method is often overwritten in derived modules to prepare the node which is used as the output/result.
+     * The output node must be returned in the `return` statement.
+     *
+     * @param {NodeBuilder} builder - The current node builder.
+     * @return {Node?} The output node.
+     */
     setup(builder: NodeBuilder): unknown;
+    /**
+     * Represents the analyze stage which is the second step of the build process, see {@link Node#build} method.
+     * This stage analyzes the node hierarchy and ensures descendent nodes are built.
+     *
+     * @param {NodeBuilder} builder - The current node builder.
+     */
     analyze(builder: NodeBuilder): void;
+    /**
+     * Represents the generate stage which is the third step of the build process, see {@link Node#build} method.
+     * This state builds the output node and returns the resulting shader string.
+     *
+     * @param {NodeBuilder} builder - The current node builder.
+     * @param {String?} output - Can be used to define the output type.
+     * @return {String?} The generated shader string.
+     */
     generate(builder: NodeBuilder, output?: string | null): string | null | undefined;
+    /**
+     * The method can be implemented to update the node's internal state before it is used to render an object.
+     * The {@link Node#updateBeforeType} property defines how often the update is executed.
+     *
+     * @abstract
+     * @param {NodeFrame} frame - A reference to the current node frame.
+     * @return {Boolean?} An optional bool that indicates whether the implementation actually performed an update or not (e.g. due to caching).
+     */
     updateBefore(frame: NodeFrame): void;
+    /**
+     * The method can be implemented to update the node's internal state after it was used to render an object.
+     * The {@link Node#updateAfterType} property defines how often the update is executed.
+     *
+     * @abstract
+     * @param {NodeFrame} frame - A reference to the current node frame.
+     * @return {Boolean?} An optional bool that indicates whether the implementation actually performed an update or not (e.g. due to caching).
+     */
     updateAfter(frame: NodeFrame): void;
+    /**
+     * The method can be implemented to update the node's internal state when it is used to render an object.
+     * The {@link Node#updateType} property defines how often the update is executed.
+     *
+     * @abstract
+     * @param {NodeFrame} frame - A reference to the current node frame.
+     * @return {Boolean?} An optional bool that indicates whether the implementation actually performed an update or not (e.g. due to caching).
+     */
     update(frame: NodeFrame): void;
+    /**
+     * This method performs the build of a node. The behavior of this method as well as its return value depend
+     * on the current build stage (setup, analyze or generate).
+     *
+     * @param {NodeBuilder} builder - The current node builder.
+     * @param {String?} output - Can be used to define the output type.
+     * @return {String?} When this method is executed in the setup or analyze stage, `null` is returned. In the generate stage, the generated shader string.
+     */
     build(builder: NodeBuilder, output?: string | null): string | null;
+    /**
+     * Returns the child nodes as a JSON object.
+     *
+     * @return {Array<Object>} An iterable list of serialized child objects as JSON.
+     */
     getSerializeChildren(): Generator<import("./NodeUtils.js").NodeChild, void, unknown>;
+    /**
+     * Serializes the node to JSON.
+     *
+     * @param {Object} json - The output JSON object.
+     */
     serialize(json: NodeJSONIntermediateOutputData): void;
+    /**
+     * Deserializes the node from the given JSON.
+     *
+     * @param {Object} json - The JSON object.
+     */
     deserialize(json: NodeJSONInputData): void;
+    /**
+     * Serializes the node into the three.js JSON Object/Scene format.
+     *
+     * @param {Object?} meta - An optional JSON object that already holds serialized data from other scene objects.
+     * @return {Object} The serialized node.
+     */
     toJSON(meta?: NodeJSONMeta | string): NodeJSONOutputData;
 }
 export default Node;

three/src/nodes/core/NodeAttribute.d.ts

@@ -1,9 +1,22 @@
 import Node from "./Node.js";
+/**
+ * {@link NodeBuilder} is going to create instances of this class during the build process
+ * of nodes. They represent the final shader attributes that are going to be generated
+ * by the builder. Arrays of node attributes is maintained in {@link NodeBuilder#attributes}
+ * and {@link NodeBuilder#bufferAttributes} for this purpose.
+ */
 declare class NodeAttribute {
     readonly isNodeAttribute: true;
     name: string;
     type: string | null;
     node: Node | null;
+    /**
+     * Constructs a new node attribute.
+     *
+     * @param {String} name - The name of the attribute.
+     * @param {String} type - The type of the attribute.
+     * @param {Node?} node - An optional reference to the node.
+     */
     constructor(name: string, type: string | null, node?: Node | null);
 }
 export default NodeAttribute;

three/src/nodes/core/NodeBuilder.d.ts

@@ -3,7 +3,6 @@ import { Object3D } from "../../core/Object3D.js";
 import { Material } from "../../materials/Material.js";
 import Renderer from "../../renderers/common/Renderer.js";
 import { Texture } from "../../textures/Texture.js";
-import FogNode from "../fog/FogNode.js";
 import LightsNode from "../lighting/LightsNode.js";
 import { NodeShaderStage } from "./constants.js";
 import Node from "./Node.js";
@@ -41,7 +40,7 @@ export default abstract class NodeBuilder {
     hashNodes: { [hash: string]: Node };
 
     lightsNode: LightsNode;
-    fogNode: FogNode;
+    fogNode: Node;
 
     vertexShader: string;
     fragmentShader: string;

three/src/nodes/core/NodeCache.d.ts

@@ -7,6 +7,7 @@ import NodeCode from "./NodeCode.js";
 import NodeUniform from "./NodeUniform.js";
 import NodeVar from "./NodeVar.js";
 import NodeVarying from "./NodeVarying.js";
+import StructType from "./StructType.js";
 export interface ShaderStageNodeData {
     properties?:
         | (
@@ -20,7 +21,7 @@ export interface ShaderStageNodeData {
         )
         | undefined;
     bufferAttribute?: NodeAttribute | undefined;
-    structType?: Node | undefined;
+    structType?: StructType | undefined;
     uniform?: NodeUniform<unknown> | undefined;
     variable?: NodeVar | undefined;
     varying?: NodeVarying | undefined;
@@ -39,13 +40,34 @@ interface NodeData {
 interface BufferAttributeData {
     node: BufferAttributeNode;
 }
+/**
+ * This utility class is used in {@link NodeBuilder} as an internal
+ * cache data structure for node data.
+ */
 declare class NodeCache {
     id: number;
     nodesData: WeakMap<Node | TypedArray | InterleavedBuffer | BufferAttribute, NodeData | BufferAttributeData>;
     parent: NodeCache | null;
+    /**
+     * Constructs a new node cache.
+     *
+     * @param {NodeCache?} parent - A reference to a parent cache.
+     */
     constructor(parent?: NodeCache | null);
+    /**
+     * Returns the data for the given node.
+     *
+     * @param {Node} node - The node.
+     * @return {Object?} The data for the node.
+     */
     getData(node: Node): NodeData | undefined;
     getData(node: TypedArray | InterleavedBuffer | BufferAttribute): BufferAttributeData | undefined;
+    /**
+     * Sets the data for a given node.
+     *
+     * @param {Node} node - The node.
+     * @param {Object} data - The data that should be cached.
+     */
     setData(node: Node, data: NodeData): void;
     setData(node: TypedArray | InterleavedBuffer | BufferAttribute, data: BufferAttributeData): void;
 }

three/src/nodes/core/NodeParser.d.ts

@@ -1,5 +1,16 @@
 import NodeFunction from "./NodeFunction.js";
+/**
+ * Base class for node parsers. A derived parser must be implemented
+ * for each supported native shader language.
+ */
 declare abstract class NodeParser {
+    /**
+     * The method parses the given native code an returns a node function.
+     *
+     * @abstract
+     * @param {String} source - The native shader code.
+     * @return {NodeFunction} A node function.
+     */
     abstract parseFunction(source: string): NodeFunction;
 }
 export default NodeParser;

three/src/nodes/core/NodeUniform.d.ts

@@ -1,14 +1,42 @@
 import UniformNode from "./UniformNode.js";
+/**
+ * {@link NodeBuilder} is going to create instances of this class during the build process
+ * of nodes. They represent the final shader uniforms that are going to be generated
+ * by the builder. A dictionary of node uniforms is maintained in {@link NodeBuilder#uniforms}
+ * for this purpose.
+ */
 declare class NodeUniform<TValue> {
     readonly isNodeUniform: true;
     name: string;
     type: string | null;
     node: UniformNode<TValue>;
     needsUpdate: boolean | undefined;
+    /**
+     * Constructs a new node uniform.
+     *
+     * @param {String} name - The name of the uniform.
+     * @param {String} type - The type of the uniform.
+     * @param {UniformNode} node - An reference to the node.
+     */
     constructor(name: string, type: string | null, node: UniformNode<TValue>);
+    /**
+     * The value of the uniform node.
+     *
+     * @type {Any}
+     */
     get value(): TValue;
     set value(val: TValue);
+    /**
+     * The id of the uniform node.
+     *
+     * @type {Number}
+     */
     get id(): number;
+    /**
+     * The uniform node's group.
+     *
+     * @type {UniformGroupNode}
+     */
     get groupNode(): import("./UniformGroupNode.js").default;
 }
 export default NodeUniform;

three/src/nodes/core/NodeVar.d.ts

@@ -1,7 +1,23 @@
+/**
+ * {@link NodeBuilder} is going to create instances of this class during the build process
+ * of nodes. They represent the final shader variables that are going to be generated
+ * by the builder. A dictionary of node variables is maintained in {@link NodeBuilder#vars} for
+ * this purpose.
+ */
 declare class NodeVar {
     readonly isNodeVar: true;
     name: string;
-    type: string | null;
-    constructor(name: string, type: string | null);
+    type: string;
+    readOnly: boolean;
+    count: number | null;
+    /**
+     * Constructs a new node variable.
+     *
+     * @param {String} name - The name of the variable.
+     * @param {String} type - The type of the variable.
+     * @param {Boolean} [readOnly=false] - The read-only flag.
+     * @param {Number?} [count=null] - The size.
+     */
+    constructor(name: string, type: string, readOnly?: boolean, count?: number | null);
 }
 export default NodeVar;

three/src/nodes/core/NodeVarying.d.ts

@@ -1,7 +1,21 @@
 import NodeVar from "./NodeVar.js";
+/**
+ * {@link NodeBuilder} is going to create instances of this class during the build process
+ * of nodes. They represent the final shader varyings that are going to be generated
+ * by the builder. An array of node varyings is maintained in {@link NodeBuilder#varyings} for
+ * this purpose.
+ *
+ * @augments NodeVar
+ */
 declare class NodeVarying extends NodeVar {
     needsInterpolation: boolean;
     readonly isNodeVarying: true;
+    /**
+     * Constructs a new node varying.
+     *
+     * @param {String} name - The name of the varying.
+     * @param {String} type - The type of the varying.
+     */
     constructor(name: string, type: string | null);
 }
 export default NodeVarying;

three/src/nodes/core/StructNode.d.ts

@@ -0,0 +1,21 @@
+import { ShaderNodeObject } from "../tsl/TSLCore.js";
+import Node from "./Node.js";
+import StructTypeNode, { MembersLayout } from "./StructTypeNode.js";
+
+declare class StructNode extends Node {
+    values: Node[];
+
+    constructor(structLayoutNode: StructTypeNode, values: Node[]);
+}
+
+export default StructNode;
+
+export interface Struct {
+    (): ShaderNodeObject<StructNode>;
+    (values: Node[]): ShaderNodeObject<StructNode>;
+    (...values: Node[]): ShaderNodeObject<StructNode>;
+    layout: StructTypeNode;
+    isStruct: true;
+}
+
+export const struct: (membersLayout: MembersLayout, name?: string | null) => Struct;

three/src/nodes/core/StructType.d.ts

@@ -0,0 +1,8 @@
+import { MemberLayout } from "./StructTypeNode.js";
+declare class StructType {
+    name: string;
+    members: MemberLayout[];
+    output: boolean;
+    constructor(name: string, members: MemberLayout[]);
+}
+export default StructType;

three/src/nodes/core/StructTypeNode.d.ts

@@ -1,9 +1,46 @@
 import Node from "./Node.js";
+import NodeBuilder from "./NodeBuilder.js";
+/** @module StructTypeNode **/
+export interface MembersLayout {
+    [name: string]: string | {
+        type: string;
+        atomic?: boolean;
+    };
+}
+export interface MemberLayout {
+    name: string;
+    type: string;
+    atomic: boolean;
+}
+/**
+ * Represents a struct type node in the node-based system.
+ * This class is used to define and manage the layout and types of struct members.
+ * It extends the base Node class and provides methods to get the length of the struct,
+ * retrieve member types, and generate the struct type for a builder.
+ *
+ * @augments Node
+ */
 declare class StructTypeNode extends Node {
     static get type(): string;
-    types: string[];
-    readonly isStructTypeNode: true;
-    constructor(types: string[]);
-    getMemberTypes(): string[];
+    membersLayout: MemberLayout[];
+    name: string | null;
+    readonly isStructLayoutNode: true;
+    /**
+     * Creates an instance of StructTypeNode.
+     *
+     * @param {Object} membersLayout - The layout of the members for the struct.
+     * @param {string} [name=null] - The optional name of the struct.
+     */
+    constructor(membersLayout: MembersLayout, name?: string | null);
+    /**
+     * Returns the length of the struct.
+     * The length is calculated by summing the lengths of the struct's members.
+     *
+     * @returns {Number} The length of the struct.
+     */
+    getLength(): number;
+    getMemberType(builder: NodeBuilder, name: string): string;
+    getNodeType(builder: NodeBuilder): string;
+    generate(builder: NodeBuilder): string;
 }
 export default StructTypeNode;

three/src/nodes/core/UniformNode.d.ts

@@ -4,20 +4,64 @@ import Node from "./Node.js";
 import NodeBuilder from "./NodeBuilder.js";
 import NodeFrame from "./NodeFrame.js";
 import UniformGroupNode from "./UniformGroupNode.js";
+/** @module UniformNode **/
+/**
+ * Class for representing a uniform.
+ *
+ * @augments InputNode
+ */
 declare class UniformNode<TValue> extends InputNode<TValue> {
     static get type(): string;
     readonly isUniformNode: true;
     name: string;
     groupNode: UniformGroupNode;
+    /**
+     * Constructs a new uniform node.
+     *
+     * @param {Any} value - The value of this node. Usually a JS primitive or three.js object (vector, matrix, color, texture).
+     * @param {String?} nodeType - The node type. If no explicit type is defined, the node tries to derive the type from its value.
+     */
     constructor(value: TValue, nodeType?: string | null);
+    /**
+     * Sets the {@link UniformNode#name} property.
+     *
+     * @param {String} name - The name of the uniform.
+     * @return {UniformNode} A reference to this node.
+     */
     label(name: string): this;
+    /**
+     * Sets the {@link UniformNode#groupNode} property.
+     *
+     * @param {UniformGroupNode} group - The uniform group.
+     * @return {UniformNode} A reference to this node.
+     */
     setGroup(group: UniformGroupNode): this;
+    /**
+     * Returns the {@link UniformNode#groupNode}.
+     *
+     * @return {UniformGroupNode} The uniform group.
+     */
     getGroup(): UniformGroupNode;
+    /**
+     * By default, this method returns the result of {@link Node#getHash} but derived
+     * classes might overwrite this method with a different implementation.
+     *
+     * @param {NodeBuilder} builder - The current node builder.
+     * @return {String} The uniform hash.
+     */
     getUniformHash(builder: NodeBuilder): string;
     onUpdate(callback: (frame: NodeFrame, self: this) => TValue | undefined, updateType: NodeUpdateType): this;
     generate(builder: NodeBuilder, output: string | null): string;
 }
 export default UniformNode;
+/**
+ * TSL function for creating a uniform node.
+ *
+ * @function
+ * @param {Any} arg1 - The value of this node. Usually a JS primitive or three.js object (vector, matrix, color, texture).
+ * @param {String?} arg2 - The node type. If no explicit type is defined, the node tries to derive the type from its value.
+ * @returns {UniformNode}
+ */
 export declare const uniform: <TValue>(
     arg1: InputNode<TValue> | TValue,
     arg2?: Node | string,

three/src/nodes/core/VarNode.d.ts

@@ -7,12 +7,19 @@ export default class VarNode extends Node {
 
     readonly isVarNode: true;
 
-    constructor(node: Node, name?: string | null);
+    readOnly: boolean;
+
+    constructor(node: Node, name?: string | null, readOnly?: boolean);
 }
 
+export const Var: (node: Node, name?: string | null) => ShaderNodeObject<VarNode>;
+
+export const Const: (node: Node, name?: string | null) => ShaderNodeObject<VarNode>;
+
 declare module "../tsl/TSLCore.js" {
     interface NodeElements {
         toVar: (node: NodeRepresentation, name?: string | null) => ShaderNodeObject<VarNode>;
+        toConst: (node: NodeRepresentation, name?: string | null) => ShaderNodeObject<VarNode>;
     }
 }
 

three/src/nodes/core/VaryingNode.d.ts

@@ -14,8 +14,20 @@ export default class VaryingNode extends Node {
 
 export const varying: (node: NodeRepresentation, name?: string) => ShaderNodeObject<VaryingNode>;
 
+export const vertexStage: (node: NodeRepresentation) => ShaderNodeObject<VaryingNode>;
+
 declare module "../tsl/TSLCore.js" {
     interface NodeElements {
+        toVarying: typeof varying;
+        toVertexStage: typeof vertexStage;
+
+        /**
+         * @deprecated .varying() has been renamed to .toVarying().
+         */
         varying: typeof varying;
+        /**
+         * @deprecated .vertexStage() has been renamed to .toVertexStage().
+         */
+        vertexStage: typeof vertexStage;
     }
 }