@types/three 0.170.0 → 0.172.0

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/math/OperatorNode.d.ts

@@ -10,6 +10,7 @@ export type OperatorNodeOp =
     | ">>"
     | "<<"
     | "=="
+    | "!="
     | "&&"
     | "||"
     | "^^"
@@ -42,6 +43,7 @@ export const mul: Operator;
 export const div: Operator;
 export const modInt: Operator;
 export const equal: Operator;
+export const notEqual: Operator;
 export const lessThan: Operator;
 export const greaterThan: Operator;
 export const lessThanEqual: Operator;
@@ -65,6 +67,7 @@ declare module "../tsl/TSLCore.js" {
         div: typeof div;
         modInt: typeof modInt;
         equal: typeof equal;
+        notEqual: typeof notEqual;
         lessThan: typeof lessThan;
         greaterThan: typeof greaterThan;
         lessThanEqual: typeof lessThanEqual;

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

@@ -19,3 +19,8 @@ export * from "../math/OperatorNode.js";
 export * from "../utils/Discard.js";
 export * from "../utils/RemapNode.js";
 export * from "./TSLCore.js";
+
+/**
+ * @deprecated
+ */
+export function addNodeElement(name: string): void;

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,13 @@ 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;
 
 export class ShaderNode<T = {}, R extends Node = Node> {
@@ -207,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()
@@ -271,3 +305,4 @@ export const arrayBuffer: (value: ArrayBuffer) => ShaderNodeObject<ConstNode<Arr
 
 export const element: (node: NodeRepresentation, indexNode: NodeRepresentation) => ShaderNodeObject<Node>;
 export const convert: (node: NodeRepresentation, types: string) => ShaderNodeObject<Node>;
+export const split: (node: NodeRepresentation, channels?: string) => ShaderNodeObject<Node>;

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/nodes/utils/SplitNode.d.ts

@@ -1,7 +1,6 @@
 import Node from "../core/Node.js";
 import { SwizzleOption } from "../tsl/TSLCore.js";
 
-/** swizzle node */
 export default class SplitNode extends Node {
     node: Node;
     components: string;
@@ -11,5 +10,6 @@ export default class SplitNode extends Node {
      * @param components swizzle like string, default = "x"
      */
     constructor(node: Node, components?: SwizzleOption);
+
     getVectorLength(): number;
 }

three/src/objects/BatchedMesh.d.ts

@@ -19,10 +19,10 @@ export interface BatchedMeshGeometryRange {
 }
 
 /**
- * A special version of {@link Mesh} with multi draw batch rendering support. Use {@link BatchedMesh} if you have to
- * render a large number of objects with the same material but with different world transformations. The  usage of
- * {@link BatchedMesh} will help you to reduce the number of draw calls and thus improve the overall rendering
- * performance in your application.
+ * A special version of {@link Mesh} with multi draw batch rendering support. Use BatchedMesh if you have to render a
+ * large number of objects with the same material but with different geometries or world transformations. The usage of
+ * BatchedMesh will help you to reduce the number of draw calls and thus improve the overall rendering performance in
+ * your application.
  *
  * If the {@link https://developer.mozilla.org/en-US/docs/Web/API/WEBGL_multi_draw WEBGL_multi_draw extension} is not
  * supported then a less performant fallback is used.

three/src/objects/ClippingGroup.d.ts

@@ -0,0 +1,41 @@
+import { Plane } from "../math/Plane.js";
+import { Group } from "./Group.js";
+
+/**
+ * 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 {
+    /**
+     * Read-only flag to check if a given object is of type ClippingGroup.
+     */
+    readonly isClippingGroup: true;
+
+    /**
+     * User-defined clipping planes specified as THREE.Plane objects in world space. These planes apply to the objects
+     * that are children of this ClippingGroup. Points in space whose signed distance to the plane is negative are
+     * clipped (not rendered). See the webgpu_clipping example. Default is `[]`.
+     */
+    clippingPlanes: Plane[];
+
+    /**
+     * Determines if the clipping planes defined by this object are applied. Default is `true`.
+     */
+    enabled: boolean;
+
+    /**
+     * Changes the behavior of clipping planes so that only their intersection is clipped, rather than their union.
+     * Default is `false`.
+     */
+    clipIntersection: boolean;
+
+    /**
+     * Defines whether to clip shadows according to the clipping planes specified by this ClippingGroup. Default is
+     * `false`.
+     */
+    clipShadows: boolean;
+
+    constructor();
+}
+
+export { ClippingGroup };

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;
@@ -444,6 +444,7 @@ export class WebGLRenderer implements Renderer {
      * @param dstTexture Specifies the destination texture.
      * @param srcRegion Specifies the bounds
      * @param dstPosition Specifies the pixel offset into the dstTexture where the copy will occur.
+     * @param srcLevel Specifies the source mipmap level of the texture.
      * @param dstLevel Specifies the destination mipmap level of the texture.
      */
     copyTextureToTexture(
@@ -451,6 +452,7 @@ export class WebGLRenderer implements Renderer {
         dstTexture: Texture,
         srcRegion?: Box2 | Box3 | null,
         dstPosition?: Vector2 | Vector3 | null,
+        srcLevel?: number,
         dstLevel?: number,
     ): void;
 

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

@@ -1,13 +1,50 @@
 import Info from "./Info.js";
 import Nodes from "./nodes/Nodes.js";
+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;
-    animationLoop: ((time: DOMHighResTimeStamp, frame?: XRFrame) => void) | null;
-    requestId: number | null;
+    _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);
-    _init(): void;
-    dispose(): void;
+    /**
+     * 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;

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

@@ -7,6 +7,12 @@ import DataMap from "./DataMap.js";
 interface Data {
     version?: number | undefined;
 }
+/**
+ * This renderer module manages geometry attributes.
+ *
+ * @private
+ * @augments DataMap
+ */
 declare class Attributes extends DataMap<{
     attribute: {
         key: BufferAttribute | InterleavedBufferAttribute;
@@ -14,9 +20,34 @@ declare class Attributes extends DataMap<{
     };
 }> {
     backend: Backend;
+    /**
+     * Constructs a new attribute management component.
+     *
+     * @param {Backend} backend - The renderer's backend.
+     */
     constructor(backend: Backend);
+    /**
+     * Deletes the data for the given attribute.
+     *
+     * @param {BufferAttribute} attribute - The attribute.
+     * @return {Object} The deleted attribute data.
+     */
     delete(attribute: BufferAttribute | InterleavedBufferAttribute): Data;
+    /**
+     * Updates the given attribute. This method creates attribute buffers
+     * for new attributes and updates data for existing ones.
+     *
+     * @param {BufferAttribute} attribute - The attribute to update.
+     * @param {Number} type - The attribute type.
+     */
     update(attribute: BufferAttribute | InterleavedBufferAttribute, type: AttributeType): void;
+    /**
+     * Utility method for handling interleaved buffer attributes correctly.
+     * To process them, their `InterleavedBuffer` is returned.
+     *
+     * @param {BufferAttribute} attribute - The attribute.
+     * @return {BufferAttribute|InterleavedBuffer}
+     */
     _getBufferAttribute(attribute: BufferAttribute | InterleavedBufferAttribute): BufferAttribute | InterleavedBuffer;
 }
 export default Attributes;

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

@@ -1,6 +1,17 @@
 import { CoordinateSystem } from "../../constants.js";
 import Renderer from "./Renderer.js";
 
+declare module "../../core/Object3D.js" {
+    interface Object3D {
+        // See https://github.com/mrdoob/three.js/pull/28683
+        count?: number | undefined;
+        // See https://github.com/mrdoob/three.js/pull/26335
+        occlusionTest?: boolean | undefined;
+        // https://github.com/mrdoob/three.js/pull/29386
+        static?: boolean | undefined;
+    }
+}
+
 export interface BackendParameters {
     canvas?: HTMLCanvasElement | undefined;
 }

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

@@ -9,6 +9,12 @@ interface SceneData {
     backgroundMesh?: Mesh;
     backgroundCacheKey: string;
 }
+/**
+ * This renderer module manages the background.
+ *
+ * @private
+ * @augments DataMap
+ */
 declare class Background extends DataMap<{
     scene: {
         key: Scene;
@@ -17,7 +23,23 @@ declare class Background extends DataMap<{
 }> {
     renderer: Renderer;
     nodes: Nodes;
+    /**
+     * Constructs a new background management component.
+     *
+     * @param {Renderer} renderer - The renderer.
+     * @param {Nodes} nodes - Renderer component for managing nodes related logic.
+     */
     constructor(renderer: Renderer, nodes: Nodes);
+    /**
+     * Updates the background for the given scene. Depending on how `Scene.background`
+     * or `Scene.backgroundNode` are configured, this method might configure a simple clear
+     * or add a mesh to the render list for rendering the background as a textured plane
+     * or skybox.
+     *
+     * @param {Scene} scene - The scene.
+     * @param {RenderList} renderList - The current render list.
+     * @param {RenderContext} renderContext - The current render context.
+     */
     update(scene: Scene, renderList: RenderList, renderContext: RenderContext): void;
 }
 export default Background;

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

@@ -1,11 +1,26 @@
 import Binding from "./Binding.js";
 import NodeUniformsGroup from "./nodes/NodeUniformsGroup.js";
+/**
+ * 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
+ */
 declare class BindGroup {
     name: string;
     bindings: NodeUniformsGroup[] | Binding[];
     index: number;
     bindingsReference: NodeUniformsGroup[] | BindGroup;
     id: number;
+    /**
+     * Constructs a new bind group.
+     *
+     * @param {String} name - The bind group's name.
+     * @param {Array<Binding>} bindings - An array of bindings.
+     * @param {Number} index - The group index.
+     * @param {Array<Binding>} bindingsReference - An array of reference bindings.
+     */
     constructor(
         name?: string,
         bindings?: NodeUniformsGroup[],

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

@@ -1,8 +1,32 @@
+/**
+ * A binding represents the connection between a resource (like a texture, sampler
+ * or uniform buffer) and the resource definition in a shader stage.
+ *
+ * This module is an abstract base class for all concrete bindings types.
+ *
+ * @abstract
+ * @private
+ */
 declare class Binding {
     name: string;
     visibility: number;
+    /**
+     * Constructs a new binding.
+     *
+     * @param {String} [name=''] - The binding's name.
+     */
     constructor(name?: string);
+    /**
+     * Makes sure binding's resource is visible for the given shader stage.
+     *
+     * @param {Number} visibility - The shader stage.
+     */
     setVisibility(visibility: number): void;
+    /**
+     * Clones the binding.
+     *
+     * @return {Binding} The cloned binding.
+     */
     clone(): Binding & this;
 }
 export default Binding;

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

@@ -11,7 +11,23 @@ import Textures from "./Textures.js";
 interface BindGroupData {
     bindGroup?: BindGroup | undefined;
 }
+/**
+ * This renderer module manages the bindings of the renderer.
+ *
+ * @private
+ * @augments DataMap
+ */
 declare class Bindings extends DataMap<{
+    /**
+     * Constructs a new bindings management component.
+     *
+     * @param {Backend} backend - The renderer's backend.
+     * @param {Nodes} nodes - Renderer component for managing nodes related logic.
+     * @param {Textures} textures - Renderer component for managing textures.
+     * @param {Attributes} attributes - Renderer component for managing attributes.
+     * @param {Pipelines} pipelines - Renderer component for managing pipelines.
+     * @param {Info} info - Renderer component for managing metrics and monitoring data.
+     */
     bindGroup: {
         key: BindGroup;
         value: BindGroupData;
@@ -31,12 +47,50 @@ declare class Bindings extends DataMap<{
         pipelines: Pipelines,
         info: Info,
     );
+    /**
+     * Returns the bind groups for the given render object.
+     *
+     * @param {RenderObject} renderObject - The render object.
+     * @return {Array<BindGroup>} The bind groups.
+     */
     getForRender(renderObject: RenderObject): BindGroup[];
+    /**
+     * Returns the bind groups for the given compute node.
+     *
+     * @param {Node} computeNode - The compute node.
+     * @return {Array<BindGroup>} The bind groups.
+     */
     getForCompute(computeNode: ComputeNode): BindGroup[];
+    /**
+     * Updates the bindings for the given compute node.
+     *
+     * @param {Node} computeNode - The compute node.
+     */
     updateForCompute(computeNode: ComputeNode): void;
+    /**
+     * Updates the bindings for the given render object.
+     *
+     * @param {RenderObject} renderObject - The render object.
+     */
     updateForRender(renderObject: RenderObject): void;
+    /**
+     * Updates the given array of bindings.
+     *
+     * @param {Array<BindGroup>} bindings - The bind groups.
+     */
     _updateBindings(bindings: BindGroup[]): void;
+    /**
+     * Initializes the given bind group.
+     *
+     * @param {BindGroup} bindGroup - The bind group to initialize.
+     */
     _init(bindGroup: BindGroup): void;
+    /**
+     * Updates the given bind group.
+     *
+     * @param {BindGroup} bindGroup - The bind group to update.
+     * @param {Array<BindGroup>} bindings - The bind groups.
+     */
     _update(bindGroup: BindGroup, bindings: BindGroup[]): void;
 }
 export default Bindings;