@types/three 0.184.1 → 0.185.0

three/src/materials/nodes/NodeMaterial.d.ts

@@ -4,6 +4,7 @@ import LightingModel from "../../nodes/core/LightingModel.js";
 import MRTNode from "../../nodes/core/MRTNode.js";
 import Node from "../../nodes/core/Node.js";
 import NodeBuilder from "../../nodes/core/NodeBuilder.js";
+import LightingNode from "../../nodes/lighting/LightingNode.js";
 import LightsNode from "../../nodes/lighting/LightsNode.js";
 import { MapColorPropertiesToColorRepresentations, Material, MaterialParameters } from "../Material.js";
 import NodeMaterialObserver from "./manager/NodeMaterialObserver.js";
@@ -21,14 +22,6 @@ export interface NodeMaterialNodeProperties {
      * @default false
      */
     lights: boolean;
-    /**
-     * Whether this material uses hardware clipping or not.
-     * This property is managed by the engine and should not be
-     * modified by apps.
-     *
-     * @default false
-     */
-    hardwareClipping: boolean;
     /**
      * Node materials which set their `lights` property to `true`
      * are affected by all lights of the scene. Sometimes selective
@@ -416,9 +409,16 @@ declare class NodeMaterial extends Material {
      * Setups the lights node based on the scene, environment and material.
      *
      * @param {NodeBuilder} builder - The current node builder.
-     * @return {LightsNode} The lights node.
+     * @return {LightingNode<Array>} The lights node.
+     */
+    setupMaterialLightings(builder: NodeBuilder): LightingNode[];
+    /**
+     * Setups the ambient occlusion node from the material.
+     *
+     * @param {NodeBuilder} builder - The current node builder.
+     * @return {Node} The ambient occlusion node.
      */
-    setupLights(builder: NodeBuilder): LightsNode;
+    setupAmbientOcclusion(builder: NodeBuilder): Node;
     /**
      * This method should be implemented by most derived materials
      * since it defines the material's lighting model.
@@ -454,6 +454,26 @@ declare class NodeMaterial extends Material {
     /**
      * Setups the output node.
      *
+     * This method can be implemented by derived materials to extend the functionality
+     * of the material's output or replace it altogether.
+     *
+     * ```js
+     * class ColoredShadowMaterial extends MeshPhongNodeMaterial {
+     *   constructor( parameters ) {
+     *     super( parameters );
+     *     this._shadeColor = uniform( new Color( parameters.shadeColor ?? 0xff0000 ) );
+     *   }
+     *
+     *   setupOutput( builder, outputNode ) {
+     * 	   // Modify the native output of the MeshPhongNodeMaterial fragment shader
+     *     const brightness = min( outputNode.r, 1.0 );
+     *     const mixedColor = mix( this._shadeColor, diffuseColor.rgb, brightness );
+     * 	   // Return new output back into NodeMaterial flow
+     *     return super.setupOutput( builder, vec4( mixedColor, outputNode.a ) );
+     *   }
+     * }
+     * ```
+     *
      * @param {NodeBuilder} builder - The current node builder.
      * @param {Node<vec4>} outputNode - The existing output node.
      * @return {Node<vec4>} The output node.
@@ -468,12 +488,12 @@ declare class NodeMaterial extends Material {
      */
     setDefaultValues(material: Material): void;
     /**
-     * Copies the properties of the given node material to this instance.
+     * Copies the common properties of the given material to this instance.
      *
-     * @param {NodeMaterial} source - The material to copy.
+     * @param {Material} source - The material to copy.
      * @return {NodeMaterial} A reference to this node material.
      */
-    copy(source: NodeMaterial): this;
+    copy(source: Material): this;
 }
 
 // eslint-disable-next-line @typescript-eslint/no-empty-interface

three/src/materials/nodes/manager/NodeMaterialObserver.d.ts

@@ -1,12 +1,5 @@
-import { BufferAttribute } from "../../../core/BufferAttribute.js";
-import { BufferGeometry } from "../../../core/BufferGeometry.js";
-import { Light } from "../../../lights/Light.js";
 import NodeBuilder from "../../../nodes/core/NodeBuilder.js";
-import NodeFrame from "../../../nodes/core/NodeFrame.js";
-import LightsNode from "../../../nodes/lighting/LightsNode.js";
 import Renderer from "../../../renderers/common/Renderer.js";
-import RenderObject from "../../../renderers/common/RenderObject.js";
-import { Material } from "../../Material.js";
 
 /**
  * This class is used by {@link WebGPURenderer} as management component.
@@ -20,13 +13,6 @@ declare class NodeMaterialObserver {
      * @param {NodeBuilder} builder - The node builder.
      */
     constructor(builder: NodeBuilder);
-    /**
-     * A node material can be used by more than one render object so the
-     * monitor must maintain a list of render objects.
-     *
-     * @type {WeakMap<RenderObject,Object>}
-     */
-    renderObjects: WeakMap<RenderObject, unknown>;
     /**
      * Whether the material uses node objects or not.
      *
@@ -52,13 +38,6 @@ declare class NodeMaterialObserver {
      * @default 0
      */
     renderId: number;
-    /**
-     * Returns `true` if the given render object is verified for the first time of this observer.
-     *
-     * @param {RenderObject} renderObject - The render object.
-     * @return {boolean} Whether the given render object is verified for the first time of this observer.
-     */
-    firstInitialization(renderObject: RenderObject): boolean;
     /**
      * Returns `true` if the current rendering produces motion vectors.
      *
@@ -66,21 +45,6 @@ declare class NodeMaterialObserver {
      * @return {boolean} Whether the current rendering produces motion vectors or not.
      */
     needsVelocity(renderer: Renderer): boolean;
-    /**
-     * Returns monitoring data for the given render object.
-     *
-     * @param {RenderObject} renderObject - The render object.
-     * @return {Object} The monitoring data.
-     */
-    getRenderObjectData(renderObject: RenderObject): unknown;
-    /**
-     * Returns an attribute data structure holding the attributes versions for
-     * monitoring.
-     *
-     * @param {Object} attributes - The geometry attributes.
-     * @return {Object} An object for monitoring the versions of attributes.
-     */
-    getAttributesData(attributes: Record<string, BufferAttribute>): unknown;
     /**
      * Returns `true` if the node builder's material uses
      * node properties.
@@ -89,54 +53,6 @@ declare class NodeMaterialObserver {
      * @return {boolean} Whether the node builder's material uses node properties or not.
      */
     containsNode(builder: NodeBuilder): boolean;
-    /**
-     * Returns a geometry data structure holding the geometry property values for
-     * monitoring.
-     *
-     * @param {BufferGeometry} geometry - The geometry.
-     * @return {Object} An object for monitoring geometry properties.
-     */
-    getGeometryData(geometry: BufferGeometry): unknown;
-    /**
-     * Returns a material data structure holding the material property values for
-     * monitoring.
-     *
-     * @param {Material} material - The material.
-     * @return {Object} An object for monitoring material properties.
-     */
-    getMaterialData(material: Material): unknown;
-    /**
-     * Returns `true` if the given render object has not changed its state.
-     *
-     * @param {RenderObject} renderObject - The render object.
-     * @param {Array<Light>} lightsData - The current material lights.
-     * @param {number} renderId - The current render ID.
-     * @return {boolean} Whether the given render object has changed its state or not.
-     */
-    equals(renderObject: RenderObject, lightsData: Light[], renderId: number): boolean;
-    /**
-     * Returns the lights data for the given material lights.
-     *
-     * @param {Array<Light>} materialLights - The material lights.
-     * @return {Array<Object>} The lights data for the given material lights.
-     */
-    getLightsData(materialLights: Light[]): unknown[];
-    /**
-     * Returns the lights for the given lights node and render ID.
-     *
-     * @param {LightsNode} lightsNode - The lights node.
-     * @param {number} renderId - The render ID.
-     * @return {Array<Object>} The lights for the given lights node and render ID.
-     */
-    getLights(lightsNode: LightsNode, renderId: number): unknown[];
-    /**
-     * Checks if the given render object requires a refresh.
-     *
-     * @param {RenderObject} renderObject - The render object.
-     * @param {NodeFrame} nodeFrame - The current node frame.
-     * @return {boolean} Whether the given render object requires a refresh or not.
-     */
-    needsRefresh(renderObject: RenderObject, nodeFrame: NodeFrame): boolean;
 }
 
 export default NodeMaterialObserver;

three/src/math/Box2.d.ts

@@ -1,4 +1,4 @@
-import { Vector2 } from "./Vector2.js";
+import { Vector2, Vector2Like } from "./Vector2.js";
 
 // Math //////////////////////////////////////////////////////////////////////////////////
 
@@ -16,7 +16,7 @@ export class Box2 {
     max: Vector2;
 
     set(min: Vector2, max: Vector2): Box2;
-    setFromPoints(points: Vector2[]): Box2;
+    setFromPoints(points: Vector2Like[]): Box2;
     setFromCenterAndSize(center: Vector2, size: Vector2): Box2;
     clone(): this;
     copy(box: Box2): this;
@@ -24,7 +24,7 @@ export class Box2 {
     isEmpty(): boolean;
     getCenter(target: Vector2): Vector2;
     getSize(target: Vector2): Vector2;
-    expandByPoint(point: Vector2): Box2;
+    expandByPoint(point: Vector2Like): Box2;
     expandByVector(vector: Vector2): Box2;
     expandByScalar(scalar: number): Box2;
     containsPoint(point: Vector2): boolean;

three/src/math/Box3.d.ts

@@ -4,67 +4,303 @@ import { Matrix4 } from "./Matrix4.js";
 import { Plane } from "./Plane.js";
 import { Sphere } from "./Sphere.js";
 import { Triangle } from "./Triangle.js";
-import { Vector3 } from "./Vector3.js";
+import { Vector3, type Vector3Like } from "./Vector3.js";
 
+/**
+ * Represents an axis-aligned bounding box (AABB) in 3D space.
+ */
 export class Box3 {
+    /**
+     * Constructs a new bounding box.
+     *
+     * @param {Vector3} [min=(Infinity,Infinity,Infinity)] - A vector representing the lower boundary of the box.
+     * @param {Vector3} [max=(-Infinity,-Infinity,-Infinity)] - A vector representing the upper boundary of the box.
+     */
     constructor(min?: Vector3, max?: Vector3);
-
     /**
-     * @default new THREE.Vector3( + Infinity, + Infinity, + Infinity )
+     * This flag can be used for type testing.
+     *
+     * @type {boolean}
+     * @readonly
+     * @default true
+     */
+    readonly isBox3: boolean;
+    /**
+     * The lower boundary of the box.
+     *
+     * @type {Vector3}
      */
     min: Vector3;
-
     /**
-     * @default new THREE.Vector3( - Infinity, - Infinity, - Infinity )
+     * The upper boundary of the box.
+     *
+     * @type {Vector3}
      */
     max: Vector3;
-    readonly isBox3: true;
-
+    /**
+     * Sets the lower and upper boundaries of this box.
+     * Please note that this method only copies the values from the given objects.
+     *
+     * @param {Vector3} min - The lower boundary of the box.
+     * @param {Vector3} max - The upper boundary of the box.
+     * @return {Box3} A reference to this bounding box.
+     */
     set(min: Vector3, max: Vector3): this;
+    /**
+     * Sets the upper and lower bounds of this box so it encloses the position data
+     * in the given array.
+     *
+     * @param {Array<number>} array - An array holding 3D position data.
+     * @return {Box3} A reference to this bounding box.
+     */
     setFromArray(array: ArrayLike<number>): this;
-    setFromBufferAttribute(bufferAttribute: BufferAttribute): this;
-    setFromPoints(points: Vector3[]): this;
+    /**
+     * Sets the upper and lower bounds of this box so it encloses the position data
+     * in the given buffer attribute.
+     *
+     * @param {BufferAttribute} attribute - A buffer attribute holding 3D position data.
+     * @return {Box3} A reference to this bounding box.
+     */
+    setFromBufferAttribute(attribute: BufferAttribute): this;
+    /**
+     * Sets the upper and lower bounds of this box so it encloses the position data
+     * in the given array.
+     *
+     * @param {Array<Vector3>} points - An array holding 3D position data as instances of {@link Vector3}.
+     * @return {Box3} A reference to this bounding box.
+     */
+    setFromPoints(points: Array<Vector3Like>): this;
+    /**
+     * Centers this box on the given center vector and sets this box's width, height and
+     * depth to the given size values.
+     *
+     * @param {Vector3} center - The center of the box.
+     * @param {Vector3} size - The x, y and z dimensions of the box.
+     * @return {Box3} A reference to this bounding box.
+     */
     setFromCenterAndSize(center: Vector3, size: Vector3): this;
+    /**
+     * Computes the world-axis-aligned bounding box for the given 3D object
+     * (including its children), accounting for the object's, and children's,
+     * world transforms. The function may result in a larger box than strictly necessary.
+     *
+     * Note: To compute the correct bounding box, make sure the given 3D object
+     * has an up-to-date world matrix that reflects the current transformation of its
+     * ancestor nodes. Call `object.updateWorldMatrix( true, false )` beforehand if
+     * you're unsure.
+     *
+     * @param {Object3D} object - The 3D object to compute the bounding box for.
+     * @param {boolean} [precise=false] - If set to `true`, the method computes the smallest
+     * world-axis-aligned bounding box at the expense of more computation.
+     * @return {Box3} A reference to this bounding box.
+     */
     setFromObject(object: Object3D, precise?: boolean): this;
+    /**
+     * Returns a new box with copied values from this instance.
+     *
+     * @return {Box3} A clone of this instance.
+     */
     clone(): this;
+    /**
+     * Copies the values of the given box to this instance.
+     *
+     * @param {Box3} box - The box to copy.
+     * @return {Box3} A reference to this bounding box.
+     */
     copy(box: Box3): this;
+    /**
+     * Makes this box empty which means in encloses a zero space in 3D.
+     *
+     * @return {Box3} A reference to this bounding box.
+     */
     makeEmpty(): this;
+    /**
+     * Returns true if this box includes zero points within its bounds.
+     * Note that a box with equal lower and upper bounds still includes one
+     * point, the one both bounds share.
+     *
+     * @return {boolean} Whether this box is empty or not.
+     */
     isEmpty(): boolean;
+    /**
+     * Returns the center point of this box.
+     *
+     * @param {Vector3} target - The target vector that is used to store the method's result.
+     * @return {Vector3} The center point.
+     */
     getCenter(target: Vector3): Vector3;
+    /**
+     * Returns the dimensions of this box.
+     *
+     * @param {Vector3} target - The target vector that is used to store the method's result.
+     * @return {Vector3} The size.
+     */
     getSize(target: Vector3): Vector3;
-    expandByPoint(point: Vector3): this;
+    /**
+     * Expands the boundaries of this box to include the given point.
+     *
+     * @param {Vector3} point - The point that should be included by the bounding box.
+     * @return {Box3} A reference to this bounding box.
+     */
+    expandByPoint(point: Vector3Like): this;
+    /**
+     * Expands this box equilaterally by the given vector. The width of this
+     * box will be expanded by the x component of the vector in both
+     * directions. The height of this box will be expanded by the y component of
+     * the vector in both directions. The depth of this box will be
+     * expanded by the z component of the vector in both directions.
+     *
+     * @param {Vector3} vector - The vector that should expand the bounding box.
+     * @return {Box3} A reference to this bounding box.
+     */
     expandByVector(vector: Vector3): this;
+    /**
+     * Expands each dimension of the box by the given scalar. If negative, the
+     * dimensions of the box will be contracted.
+     *
+     * @param {number} scalar - The scalar value that should expand the bounding box.
+     * @return {Box3} A reference to this bounding box.
+     */
     expandByScalar(scalar: number): this;
+    /**
+     * Expands the boundaries of this box to include the given 3D object and
+     * its children, accounting for the object's, and children's, world
+     * transforms. The function may result in a larger box than strictly
+     * necessary (unless the precise parameter is set to true).
+     *
+     * @param {Object3D} object - The 3D object that should expand the bounding box.
+     * @param {boolean} precise - If set to `true`, the method expands the bounding box
+     * as little as necessary at the expense of more computation.
+     * @return {Box3} A reference to this bounding box.
+     */
     expandByObject(object: Object3D, precise?: boolean): this;
+    /**
+     * Returns `true` if the given point lies within or on the boundaries of this box.
+     *
+     * @param {Vector3} point - The point to test.
+     * @return {boolean} Whether the bounding box contains the given point or not.
+     */
     containsPoint(point: Vector3): boolean;
+    /**
+     * Returns `true` if this bounding box includes the entirety of the given bounding box.
+     * If this box and the given one are identical, this function also returns `true`.
+     *
+     * @param {Box3} box - The bounding box to test.
+     * @return {boolean} Whether the bounding box contains the given bounding box or not.
+     */
     containsBox(box: Box3): boolean;
+    /**
+     * Returns a point as a proportion of this box's width, height and depth.
+     *
+     * @param {Vector3} point - A point in 3D space.
+     * @param {Vector3} target - The target vector that is used to store the method's result.
+     * @return {Vector3} A point as a proportion of this box's width, height and depth.
+     */
     getParameter(point: Vector3, target: Vector3): Vector3;
+    /**
+     * Returns `true` if the given bounding box intersects with this bounding box.
+     *
+     * @param {Box3} box - The bounding box to test.
+     * @return {boolean} Whether the given bounding box intersects with this bounding box.
+     */
     intersectsBox(box: Box3): boolean;
+    /**
+     * Returns `true` if the given bounding sphere intersects with this bounding box.
+     *
+     * @param {Sphere} sphere - The bounding sphere to test.
+     * @return {boolean} Whether the given bounding sphere intersects with this bounding box.
+     */
     intersectsSphere(sphere: Sphere): boolean;
+    /**
+     * Returns `true` if the given plane intersects with this bounding box.
+     *
+     * @param {Plane} plane - The plane to test.
+     * @return {boolean} Whether the given plane intersects with this bounding box.
+     */
     intersectsPlane(plane: Plane): boolean;
+    /**
+     * Returns `true` if the given triangle intersects with this bounding box.
+     *
+     * @param {Triangle} triangle - The triangle to test.
+     * @return {boolean} Whether the given triangle intersects with this bounding box.
+     */
     intersectsTriangle(triangle: Triangle): boolean;
+    /**
+     * Clamps the given point within the bounds of this box.
+     *
+     * @param {Vector3} point - The point to clamp.
+     * @param {Vector3} target - The target vector that is used to store the method's result.
+     * @return {Vector3} The clamped point.
+     */
     clampPoint(point: Vector3, target: Vector3): Vector3;
+    /**
+     * Returns the euclidean distance from any edge of this box to the specified point. If
+     * the given point lies inside of this box, the distance will be `0`.
+     *
+     * @param {Vector3} point - The point to compute the distance to.
+     * @return {number} The euclidean distance.
+     */
     distanceToPoint(point: Vector3): number;
+    /**
+     * Returns a bounding sphere that encloses this bounding box.
+     *
+     * @param {Sphere} target - The target sphere that is used to store the method's result.
+     * @return {Sphere} The bounding sphere that encloses this bounding box.
+     */
     getBoundingSphere(target: Sphere): Sphere;
+    /**
+     * Computes the intersection of this bounding box and the given one, setting the upper
+     * bound of this box to the lesser of the two boxes' upper bounds and the
+     * lower bound of this box to the greater of the two boxes' lower bounds. If
+     * there's no overlap, makes this box empty.
+     *
+     * @param {Box3} box - The bounding box to intersect with.
+     * @return {Box3} A reference to this bounding box.
+     */
     intersect(box: Box3): this;
+    /**
+     * Computes the union of this box and another and the given one, setting the upper
+     * bound of this box to the greater of the two boxes' upper bounds and the
+     * lower bound of this box to the lesser of the two boxes' lower bounds.
+     *
+     * @param {Box3} box - The bounding box that will be unioned with this instance.
+     * @return {Box3} A reference to this bounding box.
+     */
     union(box: Box3): this;
+    /**
+     * Transforms this bounding box by the given 4x4 transformation matrix.
+     *
+     * @param {Matrix4} matrix - The transformation matrix.
+     * @return {Box3} A reference to this bounding box.
+     */
     applyMatrix4(matrix: Matrix4): this;
-    translate(offset: Vector3): this;
-    equals(box: Box3): boolean;
     /**
-     * @deprecated Use {@link Box3#isEmpty .isEmpty()} instead.
+     * Adds the given offset to both the upper and lower bounds of this bounding box,
+     * effectively moving it in 3D space.
+     *
+     * @param {Vector3} offset - The offset that should be used to translate the bounding box.
+     * @return {Box3} A reference to this bounding box.
      */
-    empty(): any;
+    translate(offset: Vector3): this;
     /**
-     * @deprecated Use {@link Box3#intersectsBox .intersectsBox()} instead.
+     * Returns `true` if this bounding box is equal with the given one.
+     *
+     * @param {Box3} box - The box to test for equality.
+     * @return {boolean} Whether this bounding box is equal with the given one.
      */
-    isIntersectionBox(b: any): any;
+    equals(box: Box3): boolean;
     /**
-     * @deprecated Use {@link Box3#intersectsSphere .intersectsSphere()} instead.
+     * Returns a serialized structure of the bounding box.
+     *
+     * @return {Object} Serialized structure with fields representing the object state.
      */
-    isIntersectionSphere(s: any): any;
-
     toJSON(): Box3JSON;
+    /**
+     * Returns a serialized structure of the bounding box.
+     *
+     * @param {Object} json - The serialized json to set the box from.
+     * @return {Box3} A reference to this bounding box.
+     */
     fromJSON(json: Box3JSON): this;
 }
 

three/src/math/Color.d.ts

@@ -230,8 +230,8 @@ export class Color {
      */
     setFromVector3(vector: Vector3): this;
 
-    setScalar(scalar: number): Color;
-    setHex(hex: number, colorSpace?: string): Color;
+    setScalar(scalar: number): this;
+    setHex(hex: number, colorSpace?: string): this;
 
     /**
      * Sets this color from RGB values.
@@ -239,7 +239,7 @@ export class Color {
      * @param g Green channel value between 0 and 1.
      * @param b Blue channel value between 0 and 1.
      */
-    setRGB(r: number, g: number, b: number, colorSpace?: string): Color;
+    setRGB(r: number, g: number, b: number, colorSpace?: string): this;
 
     /**
      * Sets this color from HSL values.
@@ -249,20 +249,20 @@ export class Color {
      * @param s Saturation value channel between 0 and 1.
      * @param l Value channel value between 0 and 1.
      */
-    setHSL(h: number, s: number, l: number, colorSpace?: string): Color;
+    setHSL(h: number, s: number, l: number, colorSpace?: string): this;
 
     /**
      * Sets this color from a CSS context style string.
      * @param contextStyle Color in CSS context style format.
      */
-    setStyle(style: string, colorSpace?: string): Color;
+    setStyle(style: string, colorSpace?: string): this;
 
     /**
      * Sets this color from a color name.
      * Faster than {@link Color#setStyle .setStyle()} method if you don't need the other CSS-style formats.
      * @param style Color name in X11 format.
      */
-    setColorName(style: string, colorSpace?: string): Color;
+    setColorName(style: string, colorSpace?: string): this;
 
     /**
      * Clones this color.
@@ -279,23 +279,23 @@ export class Color {
      * Copies given color making conversion from `SRGBColorSpace` to `LinearSRGBColorSpace`.
      * @param color Color to copy.
      */
-    copySRGBToLinear(color: Color): Color;
+    copySRGBToLinear(color: Color): this;
 
     /**
      * Copies given color making conversion from `LinearSRGBColorSpace` to `SRGBColorSpace`.
      * @param color Color to copy.
      */
-    copyLinearToSRGB(color: Color): Color;
+    copyLinearToSRGB(color: Color): this;
 
     /**
      * Converts this color from `SRGBColorSpace` to `LinearSRGBColorSpace`.
      */
-    convertSRGBToLinear(): Color;
+    convertSRGBToLinear(): this;
 
     /**
      * Converts this color from `LinearSRGBColorSpace` to `SRGBColorSpace`.
      */
-    convertLinearToSRGB(): Color;
+    convertLinearToSRGB(): this;
 
     /**
      * Returns the hexadecimal value of this color.