@types/three 0.150.2 → 0.151.0

three/src/lights/SpotLightShadow.d.ts

@@ -1,12 +1,72 @@
 import { PerspectiveCamera } from './../cameras/PerspectiveCamera';
 import { LightShadow } from './LightShadow';
 
-export class SpotLightShadow extends LightShadow {
-    camera: PerspectiveCamera;
+/**
+ * This is used internally by {@link SpotLight | SpotLights} for calculating shadows.
+ * @example
+ * ```typescript
+ * //Create a WebGLRenderer and turn on shadows in the renderer
+ * const renderer = new THREE.WebGLRenderer();
+ * renderer.shadowMap.enabled = true;
+ * renderer.shadowMap.type = THREE.PCFSoftShadowMap; // default THREE.PCFShadowMap
+ * //Create a SpotLight and turn on shadows for the light
+ * const light = new THREE.SpotLight(0xffffff);
+ * light.castShadow = true; // default false
+ * scene.add(light);
+ * //Set up shadow properties for the light
+ * light.shadow.mapSize.width = 512; // default
+ * light.shadow.mapSize.height = 512; // default
+ * light.shadow.camera.near = 0.5; // default
+ * light.shadow.camera.far = 500; // default
+ * light.shadow.focus = 1; // default
+ * //Create a sphere that cast shadows (but does not receive them)
+ * const sphereGeometry = new THREE.SphereGeometry(5, 32, 32);
+ * const sphereMaterial = new THREE.MeshStandardMaterial({
+ *     color: 0xff0000
+ * });
+ * const sphere = new THREE.Mesh(sphereGeometry, sphereMaterial);
+ * sphere.castShadow = true; //default is false
+ * sphere.receiveShadow = false; //default
+ * scene.add(sphere);
+ * //Create a plane that receives shadows (but does not cast them)
+ * const planeGeometry = new THREE.PlaneGeometry(20, 20, 32, 32);
+ * const planeMaterial = new THREE.MeshStandardMaterial({
+ *     color: 0x00ff00
+ * })
+ * const plane = new THREE.Mesh(planeGeometry, planeMaterial);
+ * plane.receiveShadow = true;
+ * scene.add(plane);
+ * //Create a helper for the shadow camera (optional)
+ * const helper = new THREE.CameraHelper(light.shadow.camera);
+ * scene.add(helper);
+ * ```
+ * @see {@link https://threejs.org/docs/index.html#api/en/lights/shadows/SpotLightShadow | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/lights/SpotLightShadow.js | Source}
+ */
+export class SpotLightShadow extends LightShadow<PerspectiveCamera> {
+    /**
+     * Read-only flag to check if a given object is of type {@link SpotLightShadow}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
     readonly isSpotLightShadow: true;
 
     /**
-     * @default 1
+     * The light's view of the world.
+     * @remarks This is used to generate a depth map of the scene; objects behind other objects from the light's perspective will be in shadow.
+     * @remarks
+     * The {@link THREE.PerspectiveCamera.fov | fov} will track the {@link THREE.SpotLight.angle | angle} property
+     * of the owning {@link SpotLight | SpotLight} via the {@link SpotLightShadow.update | update} method.
+     * Similarly, the {@link THREE.PerspectiveCamera.aspect | aspect} property will track the aspect of the {@link LightShadow.mapSize | mapSize}.
+     * If the {@link SpotLight.distance | distance} property of the light is set, the {@link THREE.PerspectiveCamera.far | far} clipping plane will track that, otherwise it defaults to `500`.
+     * @defaultValue is a {@link THREE.PerspectiveCamera | PerspectiveCamera} with {@link THREE.PerspectiveCamera.near | near} clipping plane at `0.5`.
+     */
+    camera: PerspectiveCamera;
+
+    /**
+     * Used to focus the shadow camera.
+     * @remarks The camera's field of view is set as a percentage of the spotlight's field-of-view. Range is `[0, 1]`. 0`.
+     * @defaultValue `1`
      */
     focus: number;
 }

three/src/materials/LineBasicMaterial.d.ts

@@ -1,5 +1,6 @@
-import { Color, ColorRepresentation } from './../math/Color';
+import { Color, ColorRepresentation } from '../math/Color';
 import { MaterialParameters, Material } from './Material';
+import { Texture } from '../textures/Texture';
 
 export interface LineBasicMaterialParameters extends MaterialParameters {
     color?: ColorRepresentation | undefined;
@@ -43,5 +44,10 @@ export class LineBasicMaterial extends Material {
      */
     linejoin: string;
 
+    /**
+     * Sets the color of the lines using data from a {@link Texture}.
+     */
+    map: Texture | null;
+
     setValues(parameters: LineBasicMaterialParameters): void;
 }

three/src/materials/MeshDistanceMaterial.d.ts

@@ -46,21 +46,6 @@ export class MeshDistanceMaterial extends Material {
      */
     displacementBias: number;
 
-    /**
-     * @default 1000
-     */
-    farDistance: number;
-
-    /**
-     * @default 1
-     */
-    nearDistance: number;
-
-    /**
-     * @default new THREE.Vector3()
-     */
-    referencePosition: Vector3;
-
     /**
      * @default false
      */

three/src/math/Color.d.ts

@@ -1,7 +1,9 @@
 import { ColorSpace } from '../constants';
+import { Matrix3 } from './Matrix3';
+import { Vector3 } from './Vector3';
 
-import { BufferAttribute } from './../core/BufferAttribute';
-import { InterleavedBufferAttribute } from './../core/InterleavedBufferAttribute';
+import { BufferAttribute } from '../core/BufferAttribute';
+import { InterleavedBufferAttribute } from '../core/InterleavedBufferAttribute';
 
 export { SRGBToLinear } from './ColorManagement';
 
@@ -203,6 +205,13 @@ export class Color {
     b: number;
 
     set(color: ColorRepresentation): Color;
+
+    /**
+     * Sets this color's {@link r}, {@link g} and {@link b} components from the x, y, and z components of the specified
+     * {@link Vector3 | vector}.
+     */
+    setFromVector3(vector: Vector3): this;
+
     setScalar(scalar: number): Color;
     setHex(hex: number, colorSpace?: ColorSpace): Color;
 
@@ -295,6 +304,12 @@ export class Color {
     add(color: Color): this;
     addColors(color1: Color, color2: Color): this;
     addScalar(s: number): this;
+
+    /**
+     * Applies the transform {@link Matrix3 | m} to this color's RGB components.
+     */
+    applyMatrix3(m: Matrix3): this;
+
     sub(color: Color): this;
     multiply(color: Color): this;
     multiplyScalar(s: number): this;
@@ -326,6 +341,12 @@ export class Color {
      */
     toArray(xyz: ArrayLike<number>, offset?: number): ArrayLike<number>;
 
+    /**
+     * This method defines the serialization result of Color.
+     * @return The color as a hexadecimal value.
+     */
+    toJSON(): number;
+
     fromBufferAttribute(attribute: BufferAttribute | InterleavedBufferAttribute, index: number): this;
 
     [Symbol.iterator](): Generator<number, void>;

three/src/math/Quaternion.d.ts

@@ -138,6 +138,12 @@ export class Quaternion {
      */
     toArray(array: ArrayLike<number>, offset?: number): ArrayLike<number>;
 
+    /**
+     * This method defines the serialization result of Quaternion.
+     * @return The numerical elements of this quaternion in an array of format [x, y, z, w].
+     */
+    toJSON(): [number, number, number, number];
+
     /**
      * Sets x, y, z, w properties of this quaternion from the attribute.
      * @param attribute the source attribute.

three/src/math/Triangle.d.ts

@@ -1,5 +1,6 @@
 import { Vector2 } from './Vector2';
 import { Vector3 } from './Vector3';
+import { Vector4 } from './Vector4';
 import { Plane } from './Plane';
 import { Box3 } from './Box3';
 
@@ -39,7 +40,13 @@ export class Triangle {
     getNormal(target: Vector3): Vector3;
     getPlane(target: Plane): Plane;
     getBarycoord(point: Vector3, target: Vector3): Vector3;
+    /**
+     * @deprecated Triangle.getUV() has been renamed to Triangle.getInterpolation().
+     */
     getUV(point: Vector3, uv1: Vector2, uv2: Vector2, uv3: Vector2, target: Vector2): Vector2;
+    getInterpolation(point: Vector3, v1: Vector2, v2: Vector2, v3: Vector2, target: Vector2): Vector2;
+    getInterpolation(point: Vector3, v1: Vector3, v2: Vector3, v3: Vector3, target: Vector3): Vector3;
+    getInterpolation(point: Vector3, v1: Vector4, v2: Vector4, v3: Vector4, target: Vector4): Vector4;
     containsPoint(point: Vector3): boolean;
     intersectsBox(box: Box3): boolean;
     isFrontFacing(direction: Vector3): boolean;
@@ -49,6 +56,9 @@ export class Triangle {
     static getNormal(a: Vector3, b: Vector3, c: Vector3, target: Vector3): Vector3;
     static getBarycoord(point: Vector3, a: Vector3, b: Vector3, c: Vector3, target: Vector3): Vector3;
     static containsPoint(point: Vector3, a: Vector3, b: Vector3, c: Vector3): boolean;
+    /**
+     * @deprecated THREE.Triangle.getUV() has been renamed to THREE.Triangle.getInterpolation().
+     */
     static getUV(
         point: Vector3,
         p1: Vector3,
@@ -59,5 +69,35 @@ export class Triangle {
         uv3: Vector2,
         target: Vector2,
     ): Vector2;
+    static getInterpolation(
+        point: Vector3,
+        p1: Vector3,
+        p2: Vector3,
+        p3: Vector3,
+        v1: Vector2,
+        v2: Vector2,
+        v3: Vector2,
+        target: Vector2,
+    ): Vector2;
+    static getInterpolation(
+        point: Vector3,
+        p1: Vector3,
+        p2: Vector3,
+        p3: Vector3,
+        v1: Vector3,
+        v2: Vector3,
+        v3: Vector3,
+        target: Vector3,
+    ): Vector3;
+    static getInterpolation(
+        point: Vector3,
+        p1: Vector3,
+        p2: Vector3,
+        p3: Vector3,
+        v1: Vector4,
+        v2: Vector4,
+        v3: Vector4,
+        target: Vector4,
+    ): Vector4;
     static isFrontFacing(a: Vector3, b: Vector3, c: Vector3, direction: Vector3): boolean;
 }

three/src/math/Vector2.d.ts

@@ -354,6 +354,11 @@ export class Vector2 implements Vector {
      */
     angle(): number;
 
+    /**
+     * Returns the angle between this vector and vector {@link Vector2 | v} in radians.
+     */
+    angleTo(v: Vector2): number;
+
     /**
      * Computes distance of this vector to v.
      */

three/src/math/Vector3.d.ts

@@ -2,12 +2,13 @@ import { Euler } from './Euler';
 import { Matrix3 } from './Matrix3';
 import { Matrix4 } from './Matrix4';
 import { Quaternion } from './Quaternion';
-import { Camera } from './../cameras/Camera';
+import { Camera } from '../cameras/Camera';
 import { Spherical } from './Spherical';
 import { Cylindrical } from './Cylindrical';
-import { BufferAttribute } from './../core/BufferAttribute';
-import { InterleavedBufferAttribute } from './../core/InterleavedBufferAttribute';
+import { BufferAttribute } from '../core/BufferAttribute';
+import { InterleavedBufferAttribute } from '../core/InterleavedBufferAttribute';
 import { Vector } from './Vector2';
+import { Color } from './Color';
 
 export type Vector3Tuple = [number, number, number];
 
@@ -68,6 +69,12 @@ export class Vector3 implements Vector {
 
     setComponent(index: number, value: number): this;
 
+    /**
+     * Sets this vector's {@link x}, {@link y} and {@link z} components from the r, g, and b components of the specified
+     * {@link Color | color}.
+     */
+    setFromColor(color: Color): this;
+
     getComponent(index: number): number;
 
     /**

three/src/objects/InstancedMesh.d.ts

@@ -39,23 +39,19 @@ export class InstancedMesh<
      */
     readonly isInstancedMesh: true;
 
-    /////////////////////////////////////////////////
-    // FUTURE - r151
-    /////////////////////////////////////////////////
-    // /**
-    //  * This bounding box encloses all instances of the {@link InstancedMesh},, which can be calculated with {@link computeBoundingBox | .computeBoundingBox()}.
-    //  * @remarks Bounding boxes aren't computed by default. They need to be explicitly computed, otherwise they are `null`.
-    //  * @defaultValue `null`
-    //  */
-    // boundingBox: Box3 | null;
+    /**
+     * This bounding box encloses all instances of the {@link InstancedMesh},, which can be calculated with {@link computeBoundingBox | .computeBoundingBox()}.
+     * @remarks Bounding boxes aren't computed by default. They need to be explicitly computed, otherwise they are `null`.
+     * @defaultValue `null`
+     */
+    boundingBox: Box3 | null;
 
-    // /**
-    //  * This bounding sphere encloses all instances of the {@link InstancedMesh}, which can be calculated with {@link computeBoundingSphere | .computeBoundingSphere()}.
-    //  * @remarks bounding spheres aren't computed by default. They need to be explicitly computed, otherwise they are `null`.
-    //  * @defaultValue `null`
-    //  */
-    // boundingSphere: Sphere | null;
-    /////////////////////////////////////////////////
+    /**
+     * This bounding sphere encloses all instances of the {@link InstancedMesh}, which can be calculated with {@link computeBoundingSphere | .computeBoundingSphere()}.
+     * @remarks bounding spheres aren't computed by default. They need to be explicitly computed, otherwise they are `null`.
+     * @defaultValue `null`
+     */
+    boundingSphere: Sphere | null;
 
     /**
      * The number of instances.
@@ -80,21 +76,17 @@ export class InstancedMesh<
      */
     instanceMatrix: InstancedBufferAttribute;
 
-    /////////////////////////////////////////////////
-    // FUTURE - r151
-    /////////////////////////////////////////////////
-    // /**
-    //  * Computes bounding box of the all instances, updating {@link boundingBox | .boundingBox} attribute.
-    //  * @remarks Bounding boxes aren't computed by default. They need to be explicitly computed, otherwise they are `null`.
-    //  */
-    // computeBoundingBox(): void;
+    /**
+     * Computes bounding box of the all instances, updating {@link boundingBox | .boundingBox} attribute.
+     * @remarks Bounding boxes aren't computed by default. They need to be explicitly computed, otherwise they are `null`.
+     */
+    computeBoundingBox(): void;
 
-    // /**
-    //  * Computes bounding sphere of the all instances, updating {@link boundingSphere | .boundingSphere} attribute.
-    //  * @remarks bounding spheres aren't computed by default. They need to be explicitly computed, otherwise they are `null`.
-    //  */
-    // computeBoundingSphere(): void;
-    /////////////////////////////////////////////////
+    /**
+     * Computes bounding sphere of the all instances, updating {@link boundingSphere | .boundingSphere} attribute.
+     * @remarks bounding spheres aren't computed by default. They need to be explicitly computed, otherwise they are `null`.
+     */
+    computeBoundingSphere(): void;
 
     /**
      * Get the color of the defined instance.

three/src/objects/LineSegments.d.ts

@@ -30,6 +30,8 @@ export class LineSegments<
     readonly isLineSegments: true;
 
     /**
+     * A Read-only _string_ to check if `this` object type.
+     * @remarks Sub-classes will update this value.
      * @override
      * @defaultValue `LineSegments`
      */

three/src/objects/Skeleton.d.ts

@@ -32,7 +32,7 @@ export class Skeleton {
      * @param bones The array of {@link THREE.Bone | bones}. Default `[]`.
      * @param boneInverses An array of {@link THREE.Matrix4 | Matrix4s}. Default `[]`.
      */
-    constructor(bones: Bone[], boneInverses?: Matrix4[]);
+    constructor(bones?: Bone[], boneInverses?: Matrix4[]);
 
     /**
      * {@link http://en.wikipedia.org/wiki/Universally_unique_identifier | UUID} of this object instance.
@@ -112,4 +112,8 @@ export class Skeleton {
      * Call this method whenever this instance is no longer used in your app.
      */
     dispose(): void;
+
+    toJSON(): unknown;
+
+    fromJSON(json: unknown, bones: Record<string, Bone>): void;
 }

three/src/objects/SkinnedMesh.d.ts

@@ -1,9 +1,11 @@
 import { Material } from './../materials/Material';
+import { Box3 } from '../math/Box3';
 import { Matrix4 } from './../math/Matrix4';
 import { Vector3 } from './../math/Vector3';
 import { Skeleton } from './Skeleton';
 import { Mesh } from './Mesh';
 import { BufferGeometry } from '../core/BufferGeometry';
+import { Sphere } from '../math/Sphere';
 
 /**
  * A mesh that has a {@link THREE.Skeleton | Skeleton} with {@link Bone | bones} that can then be used to animate the vertices of the geometry.
@@ -86,6 +88,18 @@ export class SkinnedMesh<
      */
     bindMatrixInverse: Matrix4;
 
+    /**
+     * The bounding box of the SkinnedMesh. Can be calculated with {@link computeBoundingBox | .computeBoundingBox()}.
+     * @default `null`
+     */
+    boundingBox: Box3;
+
+    /**
+     * The bounding box of the SkinnedMesh. Can be calculated with {@link computeBoundingSphere | .computeBoundingSphere()}.
+     * @default `null`
+     */
+    boundingSphere: Sphere;
+
     /**
      * {@link THREE.Skeleton | Skeleton} representing the bone hierarchy of the skinned mesh.
      */
@@ -100,6 +114,23 @@ export class SkinnedMesh<
      */
     bind(skeleton: Skeleton, bindMatrix?: Matrix4): void;
 
+    /**
+     * Computes the bounding box, updating {@link boundingBox | .boundingBox} attribute.
+     * @remarks
+     * Bounding boxes aren't computed by default. They need to be explicitly computed, otherwise they are `null`. If an
+     * instance of SkinnedMesh is animated, this method should be called per frame to compute a correct bounding box.
+     */
+    computeBoundingBox(): void;
+
+    /**
+     * Computes the bounding sphere, updating {@link boundingSphere | .boundingSphere} attribute.
+     * @remarks
+     * Bounding spheres aren't computed by default. They need to be explicitly computed, otherwise they are `null`. If
+     * an instance of SkinnedMesh is animated, this method should be called per frame to compute a correct bounding
+     * sphere.
+     */
+    computeBoundingSphere(): void;
+
     /**
      * This method sets the skinned mesh in the rest pose (resets the pose).
      */
@@ -110,35 +141,16 @@ export class SkinnedMesh<
      */
     normalizeSkinWeights(): void;
 
-    /////////////////////////////////////////////////
-    // FUTURE - r151
-    /////////////////////////////////////////////////
-    // /**
-    //  * Applies the bone transform associated with the given index to the given position vector
-    //  * @remarks Returns the updated vector.
-    //  * @param index Expects a `Integer`
-    //  * @param vector
-    //  */
-    // applyBoneTransform(index: number, vector: Vector3): Vector3;
-
-    // /**
-    //  * @deprecated {@link THREE.SkinnedMesh}: {@link boneTransform | .boneTransform()} was renamed to {@link applyBoneTransform | .applyBoneTransform()} in **r151**.
-    //  */
-    // boneTransform(index: number, target: Vector3): Vector3;
-    /////////////////////////////////////////////////
-
     /**
-     * Applies the bone transform associated with the given index to the given position vector.
-     * Calculates the position of the vertex at the given index relative to the current bone transformations.
-     * Target vector must be initialized with the vertex coordinates prior to the transformation:
-     * ```typescript
-     * const target = new THREE.Vector3();
-     * target.fromBufferAttribute( mesh.geometry.attributes.position, index );
-     * mesh.boneTransform( index, target );
-     * ```
+     * Applies the bone transform associated with the given index to the given position vector
      * @remarks Returns the updated vector.
      * @param index Expects a `Integer`
      * @param vector
      */
+    applyBoneTransform(index: number, vector: Vector3): Vector3;
+
+    /**
+     * @deprecated {@link THREE.SkinnedMesh}: {@link boneTransform | .boneTransform()} was renamed to {@link applyBoneTransform | .applyBoneTransform()} in **r151**.
+     */
     boneTransform(index: number, target: Vector3): Vector3;
 }

three/src/renderers/WebGLRenderer.d.ts

@@ -22,6 +22,7 @@ import { Data3DTexture } from '../textures/Data3DTexture';
 import { Vector3 } from '../math/Vector3';
 import { Box3 } from '../math/Box3';
 import { DataArrayTexture } from '../textures/DataArrayTexture';
+import { WebGLProgram } from './webgl/WebGLProgram';
 
 export interface Renderer {
     domElement: HTMLCanvasElement;
@@ -99,6 +100,21 @@ export interface WebGLDebug {
      * Enables error checking and reporting when shader programs are being compiled.
      */
     checkShaderErrors: boolean;
+
+    /**
+     * A callback function that can be used for custom error reporting. The callback receives the WebGL context, an
+     * instance of WebGLProgram as well two instances of WebGLShader representing the vertex and fragment shader.
+     * Assigning a custom function disables the default error reporting.
+     * @default `null`
+     */
+    onShaderError:
+        | ((
+              gl: WebGLRenderingContext,
+              program: WebGLProgram,
+              glVertexShader: WebGLShader,
+              glFragmentShader: WebGLShader,
+          ) => void)
+        | null;
 }
 
 /**