@types/three 0.171.0 → 0.172.0

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,19 @@
+/**
+ * {@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;
+    /**
+     * Constructs a new node variable.
+     *
+     * @param {String} name - The name of the variable.
+     * @param {String} type - The type of the variable.
+     */
     constructor(name: string, type: string | 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/StructTypeNode.d.ts

@@ -1,9 +1,27 @@
 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 struct data that are going to be generated
+ * by the builder. A dictionary of struct types is maintained in {@link NodeBuilder#structs}
+ * for this purpose.
+ */
 declare class StructTypeNode extends Node {
     static get type(): string;
+    name: string;
     types: string[];
     readonly isStructTypeNode: true;
-    constructor(types: string[]);
+    /**
+     * Constructs a new struct type node.
+     *
+     * @param {String} name - The name of the struct.
+     * @param {Array<String>} types - An array of types.
+     */
+    constructor(name: string, types: string[]);
+    /**
+     * Returns the member types.
+     *
+     * @return {Array<String>} The types.
+     */
     getMemberTypes(): 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/VaryingNode.d.ts

@@ -14,8 +14,11 @@ 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 {
         varying: typeof varying;
+        vertexStage: typeof vertexStage;
     }
 }

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

@@ -1,13 +1,41 @@
+/** @module NodeConstants **/
+/**
+ * Possible shader stages.
+ *
+ * @property {string} VERTEX The vertex shader stage.
+ * @property {string} FRAGMENT The fragment shader stage.
+ */
 export declare const NodeShaderStage: {
     readonly VERTEX: "vertex";
     readonly FRAGMENT: "fragment";
 };
+/**
+ * Update types of a node.
+ *
+ * @property {string} NONE The update method is not executed.
+ * @property {string} FRAME The update method is executed per frame.
+ * @property {string} RENDER The update method is executed per render. A frame might be produced by multiple render calls so this value allows more detailed updates than FRAME.
+ * @property {string} OBJECT The update method is executed per {@link Object3D} that uses the node for rendering.
+ */
 export declare const NodeUpdateType: {
     readonly NONE: "none";
     readonly FRAME: "frame";
     readonly RENDER: "render";
     readonly OBJECT: "object";
 };
+/**
+ * Data types of a node.
+ *
+ * @property {string} BOOLEAN Boolean type.
+ * @property {string} INTEGER Integer type.
+ * @property {string} FLOAT Float type.
+ * @property {string} VECTOR2 Two-dimensional vector type.
+ * @property {string} VECTOR3 Three-dimensional vector type.
+ * @property {string} VECTOR4 Four-dimensional vector type.
+ * @property {string} MATRIX2 2x2 matrix type.
+ * @property {string} MATRIX3 3x3 matrix type.
+ * @property {string} MATRIX4 4x4 matrix type.
+ */
 export declare const NodeType: {
     readonly BOOLEAN: "bool";
     readonly INTEGER: "int";
@@ -19,6 +47,13 @@ export declare const NodeType: {
     readonly MATRIX3: "mat3";
     readonly MATRIX4: "mat4";
 };
+/**
+ * Access types of a node. These are relevant for compute and storage usage.
+ *
+ * @property {string} READ_ONLY Read-only access
+ * @property {string} WRITE_ONLY Write-only access.
+ * @property {string} READ_WRITE Read and write access.
+ */
 export declare const NodeAccess: {
     readonly READ_ONLY: "readOnly";
     readonly WRITE_ONLY: "writeOnly";

three/src/nodes/display/PassNode.d.ts

@@ -68,4 +68,4 @@ export default PassNode;
 
 export const pass: (scene: Scene, camera: Camera, options?: RenderTargetOptions) => ShaderNodeObject<PassNode>;
 export const passTexture: (pass: PassNode, texture: Texture) => ShaderNodeObject<PassTextureNode>;
-export const depthPass: (scene: Scene, camera: Camera) => ShaderNodeObject<PassNode>;
+export const depthPass: (scene: Scene, camera: Camera, options?: RenderTargetOptions) => ShaderNodeObject<PassNode>;

three/src/nodes/fog/Fog.d.ts

@@ -0,0 +1,26 @@
+import Node from "../core/Node.js";
+import { NodeRepresentation, ShaderNodeObject } from "../tsl/TSLCore.js";
+
+export const rangeFogFactor: (near: NodeRepresentation, far: NodeRepresentation) => ShaderNodeObject<Node>;
+
+export const densityFogFactor: (density: NodeRepresentation) => ShaderNodeObject<Node>;
+
+export const fog: (color: NodeRepresentation, factor: NodeRepresentation) => ShaderNodeObject<Node>;
+
+/**
+ * @deprecated
+ */
+export function rangeFog(
+    color: NodeRepresentation,
+    near: NodeRepresentation,
+    far: NodeRepresentation,
+): ShaderNodeObject<Node>;
+
+/**
+ * @deprecated
+ */
+export function densityFog(
+    color: NodeRepresentation,
+    near: NodeRepresentation,
+    far: NodeRepresentation,
+): ShaderNodeObject<Node>;

three/src/nodes/gpgpu/ComputeNode.d.ts

@@ -8,18 +8,23 @@ export default class ComputeNode extends Node {
     count: number;
     workgroupSize: number[];
     dispatchCount: number;
+    name: string;
 
     onInitFunction: ((args: { renderer: Renderer }) => void) | null;
 
     constructor(computeNode: Node, count: number, workgroupSize?: number[]);
 
+    label(name: string): void;
+
+    updateDispatchCount(): void;
+
     onInit(callback: ((args: { renderer: Renderer }) => void) | null): void;
 }
 
 export const compute: (
     node: NodeRepresentation,
     count: number,
-    workgroupSize: number[],
+    workgroupSize?: number[],
 ) => ShaderNodeObject<ComputeNode>;
 
 declare module "../tsl/TSLCore.js" {

three/src/nodes/gpgpu/WorkgroupInfoNode.d.ts

@@ -7,6 +7,8 @@ declare class WorkgroupInfoNode extends Node {
 
     readonly isWorkgroupInfoNode: true;
 
+    elementType: string;
+
     scope: string;
 
     constructor(scope: string, bufferType: string, bufferCount?: number);

three/src/nodes/lighting/ShadowBaseNode.d.ts

@@ -0,0 +1,15 @@
+import { Light } from "../../lights/Light.js";
+import Node from "../core/Node.js";
+import { ShaderNodeObject } from "../tsl/TSLCore.js";
+
+declare class ShadowBaseNode extends Node {
+    light: Light;
+
+    readonly isShadowBasedNode: true;
+
+    constructor(light: Light);
+}
+
+export const shadowPositionWorld: ShaderNodeObject<Node>;
+
+export default ShadowBaseNode;

three/src/nodes/lighting/ShadowNode.d.ts

@@ -2,6 +2,7 @@ import { Light } from "../../lights/Light.js";
 import { LightShadow } from "../../lights/LightShadow.js";
 import Node from "../core/Node.js";
 import { NodeRepresentation, ShaderNodeObject } from "../tsl/TSLCore.js";
+import ShadowBaseNode from "./ShadowBaseNode.js";
 
 export const BasicShadowFilter: (
     depthTexture: NodeRepresentation,
@@ -25,7 +26,7 @@ export const VSMShadowFilter: (
     shadowCoord: NodeRepresentation,
 ) => ShaderNodeObject<Node>;
 
-declare class ShadowNode extends Node {
+declare class ShadowNode extends ShadowBaseNode {
     constructor(light: Light, shadow: LightShadow | null);
 }
 

three/src/nodes/math/MathNode.d.ts

@@ -37,7 +37,6 @@ export type MathNodeMethod1 =
     | typeof MathNode.TRANSPOSE;
 
 export type MathNodeMethod2 =
-    | typeof MathNode.ATAN2
     | typeof MathNode.MIN
     | typeof MathNode.MAX
     | typeof MathNode.MOD
@@ -99,7 +98,6 @@ export default class MathNode extends TempNode {
 
     // 2 inputs
 
-    static ATAN2: "atan2";
     static MIN: "min";
     static MAX: "max";
     static MOD: "mod";
@@ -157,7 +155,7 @@ export const cos: Unary;
 export const tan: Unary;
 export const asin: Unary;
 export const acos: Unary;
-export const atan: Unary;
+export const atan: (a: NodeRepresentation, b?: NodeRepresentation) => ShaderNodeObject<MathNode>;
 export const abs: Unary;
 export const sign: Unary;
 export const length: Unary;
@@ -174,7 +172,6 @@ export const transpose: Unary;
 
 type Binary = (a: NodeRepresentation, b: NodeRepresentation) => ShaderNodeObject<MathNode>;
 
-export const atan2: Binary;
 export const min: Binary;
 export const max: Binary;
 export const mod: Binary;
@@ -210,6 +207,18 @@ export const rand: (uv: NodeRepresentation) => ShaderNodeObject<OperatorNode>;
 export const mixElement: Ternary;
 export const smoothstepElement: Ternary;
 
+/**
+ * @deprecated
+ */
+export const atan2: Binary;
+
+// GLSL alias function
+
+export const faceforward: typeof faceForward;
+export const inversesqrt: typeof inverseSqrt;
+
+// Method chaining
+
 declare module "../tsl/TSLCore.js" {
     interface NodeElements {
         all: typeof all;

three/src/nodes/tsl/TSLCore.d.ts

@@ -35,15 +35,29 @@ export interface NodeElements {
 
 export function addMethodChaining(name: string, nodeElement: unknown): void;
 
-export type SwizzleCharacter = "x" | "y" | "z" | "w" | "r" | "g" | "b" | "a" | "s" | "t" | "p" | "q";
-
-export type SwizzleOption = Exclude<
-    | `${SwizzleCharacter}`
-    | `${SwizzleCharacter}${SwizzleCharacter}`
-    | `${SwizzleCharacter}${SwizzleCharacter}${SwizzleCharacter}`
-    | `${SwizzleCharacter}${SwizzleCharacter}${SwizzleCharacter}${SwizzleCharacter}`,
-    "abs" | "sqrt"
->;
+type XYZWCharacter = "x" | "y" | "z" | "w";
+type RGBACharacter = "r" | "g" | "b" | "a";
+type STPQCharacter = "s" | "t" | "p" | "q";
+
+type XYZWSwizzle =
+    | `${XYZWCharacter}`
+    | `${XYZWCharacter}${XYZWCharacter}`
+    | `${XYZWCharacter}${XYZWCharacter}${XYZWCharacter}`
+    | `${XYZWCharacter}${XYZWCharacter}${XYZWCharacter}${XYZWCharacter}`;
+
+type RGBASwizzle =
+    | `${RGBACharacter}`
+    | `${RGBACharacter}${RGBACharacter}`
+    | `${RGBACharacter}${RGBACharacter}${RGBACharacter}`
+    | `${RGBACharacter}${RGBACharacter}${RGBACharacter}${RGBACharacter}`;
+
+type STPQSwizzle =
+    | `${STPQCharacter}`
+    | `${STPQCharacter}${STPQCharacter}`
+    | `${STPQCharacter}${STPQCharacter}${STPQCharacter}`
+    | `${STPQCharacter}${STPQCharacter}${STPQCharacter}${STPQCharacter}`;
+
+export type SwizzleOption = XYZWSwizzle | RGBASwizzle | STPQSwizzle;
 
 export type Swizzable<T extends Node = Node> =
     & T
@@ -172,6 +186,11 @@ type ConstructedNode<T> = T extends new(...args: any[]) => infer R ? (R extends
 
 export type NodeOrType = Node | string;
 
+declare class ShaderCallNodeInternal extends Node {
+}
+
+declare class ShaderNodeInternal extends Node {}
+
 export const defined: (v: unknown) => unknown;
 
 export const getConstNodeType: (value: NodeOrType) => string | null;
@@ -209,13 +228,26 @@ export function nodeImmutable<T>(
     ...params: ProxiedTuple<GetConstructors<T>>
 ): ShaderNodeObject<ConstructedNode<T>>;
 
-export function Fn<R extends Node = ShaderNodeObject<Node>>(jsFunc: () => R): () => R;
-export function Fn<T extends any[], R extends Node = ShaderNodeObject<Node>>(
-    jsFunc: (args: T) => R,
-): (...args: ProxiedTuple<T>) => R;
-export function Fn<T extends { [key: string]: unknown }, R extends Node = ShaderNodeObject<Node>>(
-    jsFunc: (args: T) => R,
-): (args: ProxiedObject<T>) => R;
+interface Layout {
+    name: string;
+    type: string;
+    inputs: { name: string; type: string }[];
+}
+
+interface ShaderNodeFn<Args extends readonly unknown[]> {
+    (...args: Args): ShaderNodeObject<ShaderCallNodeInternal>;
+    shaderNode: ShaderNodeObject<ShaderNodeInternal>;
+    setLayout: (layout: Layout) => this;
+    once: () => this;
+}
+
+export function Fn(jsFunc: () => void): ShaderNodeFn<[]>;
+export function Fn<T extends readonly unknown[]>(
+    jsFunc: (args: T) => void,
+): ShaderNodeFn<ProxiedTuple<T>>;
+export function Fn<T extends { readonly [key: string]: unknown }>(
+    jsFunc: (args: T) => void,
+): ShaderNodeFn<[ProxiedObject<T>]>;
 
 /**
  * @deprecated tslFn() has been renamed to Fn()

three/src/nodes/utils/EquirectUVNode.d.ts

@@ -1,8 +1,8 @@
 import { Node, TempNode } from "../Nodes.js";
-import { ShaderNodeObject } from "../tsl/TSLCore.js";
+import { NodeRepresentation, ShaderNodeObject } from "../tsl/TSLCore.js";
 
 export default class EquirectUVNode extends TempNode {
     constructor(dirNode?: ShaderNodeObject<Node>);
 }
 
-export const equirectUV: ShaderNodeObject<EquirectUVNode>;
+export const equirectUV: (dirNode?: NodeRepresentation) => ShaderNodeObject<EquirectUVNode>;

three/src/nodes/utils/LoopNode.d.ts

@@ -1,6 +1,18 @@
 import Node from "../core/Node.js";
 import NodeBuilder from "../core/NodeBuilder.js";
-import { NodeRepresentation, ShaderNodeObject } from "../tsl/TSLCore.js";
+import { ShaderNodeObject } from "../tsl/TSLCore.js";
+
+interface LoopNodeObjectParameter {
+    // TODO Expand to other types and update loop function types appropriately
+    type?: "int" | "uint";
+    // TODO The variable name should affect the type of the loop function
+    // name?: string;
+    start: number | Node;
+    end: number | Node;
+    condition: string;
+}
+
+type LoopNodeParameter = Node | number | LoopNodeObjectParameter;
 
 declare class LoopNode extends Node {
     params: unknown[];
@@ -12,7 +24,16 @@ declare class LoopNode extends Node {
 
 export default LoopNode;
 
-export const Loop: (...params: unknown[]) => ShaderNodeObject<Node>;
+interface Loop {
+    (i: LoopNodeParameter, func: (inputs: { readonly i: number }) => void): ShaderNodeObject<Node>;
+    (
+        i: LoopNodeParameter,
+        j: LoopNodeParameter,
+        func: (inputs: { readonly i: number; readonly j: number }) => void,
+    ): ShaderNodeObject<Node>;
+}
+
+export const Loop: Loop;
 export const Continue: () => ShaderNodeObject<Node>;
 export const Break: () => ShaderNodeObject<Node>;
 

three/src/objects/ClippingGroup.d.ts

@@ -2,7 +2,7 @@ import { Plane } from "../math/Plane.js";
 import { Group } from "./Group.js";
 
 /**
- * A special version of the Group object that defines clipping planes for decendant objects. ClippingGroups can be
+ * A special version of the Group object that defines clipping planes for descendant objects. ClippingGroups can be
  * nested, with clipping planes accumulating by type: intersection or union.
  */
 declare class ClippingGroup extends Group {

three/src/renderers/WebGLRenderer.d.ts

@@ -26,13 +26,6 @@ import { WebGLState } from "./webgl/WebGLState.js";
 import { WebGLRenderTarget } from "./WebGLRenderTarget.js";
 import { WebXRManager } from "./webxr/WebXRManager.js";
 
-export interface Renderer {
-    domElement: HTMLCanvasElement;
-
-    render(scene: Object3D, camera: Camera): void;
-    setSize(width: number, height: number, updateStyle?: boolean): void;
-}
-
 export interface WebGLRendererParameters extends WebGLCapabilitiesParameters {
     /**
      * A Canvas where the renderer draws its output.
@@ -115,7 +108,7 @@ export interface WebGLDebug {
  *
  * see {@link https://github.com/mrdoob/three.js/blob/master/src/renderers/WebGLRenderer.js|src/renderers/WebGLRenderer.js}
  */
-export class WebGLRenderer implements Renderer {
+export class WebGLRenderer {
     /**
      * parameters is an optional object with properties defining the renderer's behavior.
      * The constructor also accepts no parameters at all.
@@ -198,6 +191,13 @@ export class WebGLRenderer implements Renderer {
      */
     toneMappingExposure: number;
 
+    /**
+     * The normalized resolution scale for the transmission render target, measured in percentage of viewport
+     * dimensions. Lowering this value can result in significant improvements to {@link MeshPhysicalMaterial}
+     * transmission performance. Default is `1`.
+     */
+    transmissionResolutionScale: number;
+
     info: WebGLInfo;
 
     shadowMap: WebGLShadowMap;

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

@@ -4,17 +4,47 @@ interface AnimationContext {
     requestAnimationFrame(callback: FrameRequestCallback, frame?: XRFrame): number;
     cancelAnimationFrame(handle: number): void;
 }
+/**
+ * This module manages the internal animation loop of the renderer.
+ *
+ * @private
+ */
 declare class Animation {
     nodes: Nodes;
     info: Info;
     _context: AnimationContext;
     _animationLoop: ((time: DOMHighResTimeStamp, frame?: XRFrame) => void) | null;
     _requestId: number | null;
+    /**
+     * Constructs a new animation loop management component.
+     *
+     * @param {Nodes} nodes - Renderer component for managing nodes related logic.
+     * @param {Info} info - Renderer component for managing metrics and monitoring data.
+     */
     constructor(nodes: Nodes, info: Info);
+    /**
+     * Starts the internal animation loop.
+     */
     start(): void;
+    /**
+     * Stops the internal animation loop.
+     */
     stop(): void;
+    /**
+     * Defines the user-level animation loop.
+     *
+     * @param {Function} callback - The animation loop.
+     */
     setAnimationLoop(callback: ((time: DOMHighResTimeStamp, frame?: XRFrame) => void) | null): void;
+    /**
+     * Defines the context in which `requestAnimationFrame()` is executed.
+     *
+     * @param {Window|XRSession} context - The context to set.
+     */
     setContext(context: AnimationContext): void;
+    /**
+     * Frees all internal resources and stops the animation loop.
+     */
     dispose(): void;
 }
 export default Animation;