@types/three 0.166.0 → 0.167.1

three/src/loaders/Cache.d.ts

@@ -1,16 +1,21 @@
-export namespace Cache {
+declare const Cache: {
     /**
      * @default false
      */
-    let enabled: boolean;
+    enabled: boolean;
 
     /**
      * @default {}
      */
-    let files: any;
+    files: any;
 
-    function add(key: string, file: any): void;
-    function get(key: string): any;
-    function remove(key: string): void;
-    function clear(): void;
-}
+    add(key: string, file: any): void;
+
+    get(key: string): any;
+
+    remove(key: string): void;
+
+    clear(): void;
+};
+
+export { Cache };

three/src/materials/Material.d.ts

@@ -4,7 +4,9 @@ import {
     BlendingDstFactor,
     BlendingEquation,
     BlendingSrcFactor,
+    Combine,
     DepthModes,
+    NormalMapTypes,
     PixelFormat,
     Side,
     StencilFunc,
@@ -12,13 +14,14 @@ import {
 } from "../constants.js";
 import { BufferGeometry } from "../core/BufferGeometry.js";
 import { EventDispatcher } from "../core/EventDispatcher.js";
-import { Object3D } from "../core/Object3D.js";
+import { JSONMeta, Object3D } from "../core/Object3D.js";
 import { Color, ColorRepresentation } from "../math/Color.js";
 import { Plane } from "../math/Plane.js";
 import { Group } from "../objects/Group.js";
 import { WebGLProgramParametersWithUniforms } from "../renderers/webgl/WebGLPrograms.js";
 import { WebGLRenderer } from "../renderers/WebGLRenderer.js";
 import { Scene } from "../scenes/Scene.js";
+import { EulerTuple, SourceJSON, TextureJSON, Vector2Tuple } from "../Three.js";
 
 export interface MaterialParameters {
     alphaHash?: boolean | undefined;
@@ -68,6 +71,165 @@ export interface MaterialParameters {
     userData?: Record<string, any> | undefined;
 }
 
+export interface MaterialJSON {
+    metadata: { version: number; type: string; generator: string };
+
+    uuid: string;
+    type: string;
+
+    name?: string;
+
+    color?: number;
+    roughness?: number;
+    metalness?: number;
+
+    sheen?: number;
+    sheenColor?: number;
+    sheenRoughness?: number;
+    emissive?: number;
+    emissiveIntensity?: number;
+
+    specular?: number;
+    specularIntensity?: number;
+    specularColor?: number;
+    shininess?: number;
+    clearcoat?: number;
+    clearcoatRoughness?: number;
+    clearcoatMap?: string;
+    clearcoatRoughnessMap?: string;
+    clearcoatNormalMap?: string;
+    clearcoatNormalScale?: Vector2Tuple;
+
+    dispersion?: number;
+
+    iridescence?: number;
+    iridescenceIOR?: number;
+    iridescenceThicknessRange?: number;
+    iridescenceMap?: string;
+    iridescenceThicknessMap?: string;
+
+    anisotropy?: number;
+    anisotropyRotation?: number;
+    anisotropyMap?: string;
+
+    map?: string;
+    matcap?: string;
+    alphaMap?: string;
+
+    lightMap?: string;
+    lightMapIntensity?: number;
+
+    aoMap?: string;
+    aoMapIntensity?: number;
+
+    bumpMap?: string;
+    bumpScale?: number;
+
+    normalMap?: string;
+    normalMapType?: NormalMapTypes;
+    normalScale?: Vector2Tuple;
+
+    displacementMap?: string;
+    displacementScale?: number;
+    displacementBias?: number;
+
+    roughnessMap?: string;
+    metalnessMap?: string;
+
+    emissiveMap?: string;
+    specularMap?: string;
+    specularIntensityMap?: string;
+    specularColorMap?: string;
+
+    envMap?: string;
+    combine?: Combine;
+
+    envMapRotation?: EulerTuple;
+    envMapIntensity?: number;
+    reflectivity?: number;
+    refractionRatio?: number;
+
+    gradientMap?: string;
+
+    transmission?: number;
+    transmissionMap?: string;
+    thickness?: number;
+    thicknessMap?: string;
+    attenuationDistance?: number;
+    attenuationColor?: number;
+
+    size?: number;
+    shadowSide?: number;
+    sizeAttenuation?: boolean;
+
+    blending?: Blending;
+    side?: Side;
+    vertexColors?: boolean;
+
+    opacity?: number;
+    transparent?: boolean;
+
+    blendSrc?: BlendingSrcFactor;
+    blendDst?: BlendingDstFactor;
+    blendEquation?: BlendingEquation;
+    blendSrcAlpha?: number | null;
+    blendDstAlpha?: number | null;
+    blendEquationAlpha?: number | null;
+    blendColor?: number;
+    blendAlpha?: number;
+
+    depthFunc?: DepthModes;
+    depthTest?: boolean;
+    depthWrite?: boolean;
+    colorWrite?: boolean;
+
+    stencilWriteMask?: number;
+    stencilFunc?: StencilFunc;
+    stencilRef?: number;
+    stencilFuncMask?: number;
+    stencilFail?: StencilOp;
+    stencilZFail?: StencilOp;
+    stencilZPass?: StencilOp;
+    stencilWrite?: boolean;
+
+    rotation?: number;
+
+    polygonOffset?: boolean;
+    polygonOffsetFactor?: number;
+    polygonOffsetUnits?: number;
+
+    linewidth?: number;
+    dashSize?: number;
+    gapSize?: number;
+    scale?: number;
+
+    dithering?: boolean;
+
+    alphaTest?: number;
+    alphaHash?: boolean;
+    alphaToCoverage?: boolean;
+    premultipliedAlpha?: boolean;
+    forceSinglePass?: boolean;
+
+    wireframe?: boolean;
+    wireframeLinewidth?: number;
+    wireframeLinecap?: string;
+    wireframeLinejoin?: string;
+
+    flatShading?: boolean;
+
+    visible?: boolean;
+
+    toneMapped?: boolean;
+
+    fog?: boolean;
+
+    userData?: Record<string, unknown>;
+
+    textures?: Array<Omit<TextureJSON, "metadata">>;
+    images?: SourceJSON[];
+}
+
 /**
  * Materials describe the appearance of objects. They are defined in a (mostly) renderer-independent way, so you don't have to rewrite materials if you decide to use a different renderer.
  */
@@ -418,7 +580,7 @@ export class Material extends EventDispatcher<{ dispose: {} }> {
      * Convert the material to three.js JSON format.
      * @param meta Object containing metadata such as textures or images for the material.
      */
-    toJSON(meta?: any): any;
+    toJSON(meta?: JSONMeta): MaterialJSON;
 
     /**
      * Return a new material with the same parameters as this material.

three/src/materials/ShaderMaterial.d.ts

@@ -1,7 +1,13 @@
 import { GLSLVersion } from "../constants.js";
+import { JSONMeta } from "../core/Object3D.js";
 import { UniformsGroup } from "../core/UniformsGroup.js";
+import { Matrix3, Matrix3Tuple } from "../math/Matrix3.js";
+import { Matrix4, Matrix4Tuple } from "../math/Matrix4.js";
+import { Vector2Tuple } from "../math/Vector2.js";
+import { Vector3Tuple } from "../math/Vector3.js";
+import { Vector4Tuple } from "../math/Vector4.js";
 import { IUniform } from "../renderers/shaders/UniformsLib.js";
-import { Material, MaterialParameters } from "./Material.js";
+import { Material, MaterialJSON, MaterialParameters } from "./Material.js";
 
 export interface ShaderMaterialParameters extends MaterialParameters {
     uniforms?: { [uniform: string]: IUniform } | undefined;
@@ -23,6 +29,46 @@ export interface ShaderMaterialParameters extends MaterialParameters {
     glslVersion?: GLSLVersion | undefined;
 }
 
+export type ShaderMaterialUniformJSON = {
+    type: "t";
+    value: string;
+} | {
+    type: "c";
+    value: number;
+} | {
+    type: "v2";
+    value: Vector2Tuple;
+} | {
+    type: "v3";
+    value: Vector3Tuple;
+} | {
+    type: "v4";
+    value: Vector4Tuple;
+} | {
+    type: "m3";
+    value: Matrix3Tuple;
+} | {
+    type: "m4";
+    value: Matrix4Tuple;
+} | {
+    value: unknown;
+};
+
+export interface ShaderMaterialJSON extends MaterialJSON {
+    glslVersion: number | null;
+    uniforms: Record<string, ShaderMaterialUniformJSON>;
+
+    defines?: Record<string, unknown>;
+
+    vertexShader: string;
+    ragmentShader: string;
+
+    lights: boolean;
+    clipping: boolean;
+
+    extensions?: Record<string, boolean>;
+}
+
 export class ShaderMaterial extends Material {
     constructor(parameters?: ShaderMaterialParameters);
 
@@ -116,5 +162,6 @@ export class ShaderMaterial extends Material {
     glslVersion: GLSLVersion | null;
 
     setValues(parameters: ShaderMaterialParameters): void;
-    toJSON(meta: any): any;
+
+    toJSON(meta?: JSONMeta): ShaderMaterialJSON;
 }

three/src/math/ColorManagement.d.ts

@@ -8,6 +8,7 @@ import {
     SRGBColorSpace,
 } from "../constants.js";
 import { Color } from "./Color.js";
+import { Vector3 } from "./Vector3.js";
 
 export type WorkingColorSpace = typeof LinearSRGBColorSpace | typeof LinearDisplayP3ColorSpace;
 export type DefinedColorSpace =
@@ -37,6 +38,8 @@ export interface ColorManagement {
     getPrimaries: (colorSpace: DefinedColorSpace) => ColorSpacePrimaries;
 
     getTransfer: (colorSpace: ColorSpace) => ColorSpaceTransfer;
+
+    getLuminanceCoefficients: (target: Vector3, colorSpace?: ColorSpace) => Vector3;
 }
 
 export const ColorManagement: ColorManagement;

three/src/math/Euler.d.ts

@@ -4,6 +4,8 @@ import { Vector3 } from "./Vector3.js";
 
 export type EulerOrder = "XYZ" | "YXZ" | "ZXY" | "ZYX" | "YZX" | "XZY";
 
+export type EulerTuple = [x: number, y: number, z: number, order?: EulerOrder];
+
 export class Euler {
     constructor(x?: number, y?: number, z?: number, order?: EulerOrder);
 
@@ -38,8 +40,8 @@ export class Euler {
     setFromVector3(v: Vector3, order?: EulerOrder): Euler;
     reorder(newOrder: EulerOrder): Euler;
     equals(euler: Euler): boolean;
-    fromArray(xyzo: [number, number, number, EulerOrder?, ...any[]]): Euler;
-    toArray(array?: Array<number | string | undefined>, offset?: number): Array<number | string | undefined>;
+    fromArray(array: EulerTuple): Euler;
+    toArray(array?: Partial<EulerTuple>, offset?: number): EulerTuple;
     _onChange(callback: () => void): this;
 
     static DEFAULT_ORDER: "XYZ";

three/src/math/Matrix2.d.ts

@@ -0,0 +1,53 @@
+export type Matrix2Tuple = [
+    n11: number,
+    n12: number,
+    n21: number,
+    n22: number,
+];
+
+/**
+ * A class representing a 2x2 {@link https://en.wikipedia.org/wiki/Matrix_(mathematics) matrix}.
+ *
+ * @example
+ * const m = new Matrix2();
+ */
+export class Matrix2 {
+    readonly isMatrix2: true;
+
+    /**
+     * A {@link https://en.wikipedia.org/wiki/Row-_and_column-major_order column-major} list of matrix values.
+     */
+    elements: Matrix2Tuple;
+
+    /**
+     * Creates a 2x2 {@link https://en.wikipedia.org/wiki/Identity_matrix identity matrix}.
+     */
+    constructor();
+
+    /**
+     * Creates a 2x2 matrix with the given arguments in row-major order.
+     */
+    constructor(n11: number, n12: number, n21: number, n22: number);
+
+    /**
+     * Resets this matrix to the 2x2 identity matrix:
+     */
+    identity(): this;
+
+    /**
+     * Sets the elements of this matrix based on an array in
+     * {@link https://en.wikipedia.org/wiki/Row-_and_column-major_order#Column-major_order column-major} format.
+     *
+     * @param array the array to read the elements from
+     * @param offset (optional) index of first element in the array. Default is `0`.
+     */
+    fromArray(array: ArrayLike<number>, offset?: number): this;
+
+    /**
+     * Sets the 2x2 matrix values to the given
+     * {@link https://en.wikipedia.org/wiki/Row-_and_column-major_order row-major} sequence of values:
+     * [n11, n12,
+     *  n21, n22]
+     */
+    set(n11: number, n12: number, n21: number, n22: number): this;
+}

three/src/math/Matrix3.d.ts

@@ -4,55 +4,26 @@ import { Matrix4 } from "./Matrix4.js";
 import { Vector2 } from "./Vector2.js";
 import { Vector3 } from "./Vector3.js";
 
-export type Matrix3Tuple = [number, number, number, number, number, number, number, number, number];
+export type Matrix3Tuple = [
+    n11: number,
+    n12: number,
+    n13: number,
+    n21: number,
+    n22: number,
+    n23: number,
+    n31: number,
+    n32: number,
+    n33: number,
+];
+
+export class Matrix3 {
+    readonly isMatrix3: true;
 
-/**
- * ( interface Matrix<T> )
- */
-export interface Matrix {
     /**
      * Array with matrix values.
+     * @default [1, 0, 0, 0, 1, 0, 0, 0, 1]
      */
-    elements: number[];
-
-    /**
-     * identity():T;
-     */
-    identity(): Matrix;
-
-    /**
-     * copy(m:T):T;
-     */
-    copy(m: this): this;
-
-    /**
-     * multiplyScalar(s:number):T;
-     */
-    multiplyScalar(s: number): Matrix;
-
-    determinant(): number;
-
-    /**
-     * transpose():T;
-     */
-    transpose(): Matrix;
-
-    /**
-     * invert():T;
-     */
-    invert(): Matrix;
-
-    /**
-     * clone():T;
-     */
-    clone(): Matrix;
-}
-
-/**
- * ( class Matrix3 implements Matrix<Matrix3> )
- */
-export class Matrix3 implements Matrix {
-    readonly isMatrix3: true;
+    elements: Matrix3Tuple;
 
     /**
      * Creates an identity matrix.
@@ -73,12 +44,6 @@ export class Matrix3 implements Matrix {
         n33: number,
     );
 
-    /**
-     * Array with matrix values.
-     * @default [1, 0, 0, 0, 1, 0, 0, 0, 1]
-     */
-    elements: number[];
-
     set(
         n11: number,
         n12: number,
@@ -90,34 +55,68 @@ export class Matrix3 implements Matrix {
         n32: number,
         n33: number,
     ): Matrix3;
-    identity(): Matrix3;
-    clone(): this;
+
+    identity(): this;
+
     copy(m: Matrix3): this;
-    extractBasis(xAxis: Vector3, yAxis: Vector3, zAxis: Vector3): Matrix3;
+
+    extractBasis(xAxis: Vector3, yAxis: Vector3, zAxis: Vector3): this;
+
     setFromMatrix4(m: Matrix4): Matrix3;
-    multiplyScalar(s: number): Matrix3;
+
+    /**
+     * Multiplies this matrix by m.
+     */
+    multiply(m: Matrix3): this;
+
+    premultiply(m: Matrix3): this;
+
+    /**
+     * Sets this matrix to a x b.
+     */
+    multiplyMatrices(a: Matrix3, b: Matrix3): this;
+
+    multiplyScalar(s: number): this;
+
     determinant(): number;
 
     /**
      * Inverts this matrix in place.
      */
-    invert(): Matrix3;
+    invert(): this;
 
     /**
      * Transposes this matrix in place.
      */
-    transpose(): Matrix3;
-    getNormalMatrix(matrix4: Matrix4): Matrix3;
+    transpose(): this;
+
+    getNormalMatrix(matrix4: Matrix4): this;
 
     /**
      * Transposes this matrix into the supplied array r, and returns itself.
      */
-    transposeIntoArray(r: number[]): Matrix3;
+    transposeIntoArray(r: number[]): this;
+
+    setUvTransform(tx: number, ty: number, sx: number, sy: number, rotation: number, cx: number, cy: number): this;
+
+    scale(sx: number, sy: number): this;
 
-    setUvTransform(tx: number, ty: number, sx: number, sy: number, rotation: number, cx: number, cy: number): Matrix3;
+    rotate(theta: number): this;
 
-    scale(sx: number, sy: number): Matrix3;
+    translate(tx: number, ty: number): this;
 
+    /**
+     * Sets this matrix as a 2D translation transform:
+     *
+     * ```
+     * 1, 0, x,
+     * 0, 1, y,
+     * 0, 0, 1
+     * ```
+     *
+     * @param v the amount to translate.
+     */
+    makeTranslation(v: Vector2): this;
     /**
      * Sets this matrix as a 2D translation transform:
      *
@@ -130,7 +129,6 @@ export class Matrix3 implements Matrix {
      * @param x the amount to translate in the X axis.
      * @param y the amount to translate in the Y axis.
      */
-    makeTranslation(v: Vector2): this;
     makeTranslation(x: number, y: number): this;
 
     /**
@@ -145,7 +143,6 @@ export class Matrix3 implements Matrix {
      * @param theta Rotation angle in radians. Positive values rotate counterclockwise.
      */
     makeRotation(theta: number): this;
-    makeRotation(theta: number): Matrix3;
 
     /**
      * Sets this matrix as a 2D scale transform:
@@ -160,11 +157,6 @@ export class Matrix3 implements Matrix {
      * @param y the amount to scale in the Y axis.
      */
     makeScale(x: number, y: number): this;
-    makeScale(x: number, y: number): Matrix3;
-
-    rotate(theta: number): Matrix3;
-
-    translate(tx: number, ty: number): Matrix3;
 
     equals(matrix: Matrix3): boolean;
 
@@ -173,55 +165,20 @@ export class Matrix3 implements Matrix {
      * @param array the source array or array-like.
      * @param offset (optional) offset into the array-like. Default is 0.
      */
-    fromArray(array: number[] | ArrayLike<number>, offset?: number): Matrix3;
-
-    /**
-     * Returns an array with the values of this matrix, or copies them into the provided array.
-     * @param array (optional) array to store the matrix to. If this is not provided, a new array will be created.
-     * @param offset (optional) optional offset into the array.
-     * @return The created or provided array.
-     */
-    toArray(array?: number[], offset?: number): number[];
-    toArray(array?: Matrix3Tuple, offset?: 0): Matrix3Tuple;
+    fromArray(array: ArrayLike<number>, offset?: number): this;
 
     /**
-     * Copies he values of this matrix into the provided array-like.
-     * @param array array-like to store the matrix to.
-     * @param offset (optional) optional offset into the array-like.
-     * @return The provided array-like.
+     * Writes the elements of this matrix to an array in
+     * {@link https://en.wikipedia.org/wiki/Row-_and_column-major_order#Column-major_order column-major} format.
      */
-    toArray(array?: ArrayLike<number>, offset?: number): ArrayLike<number>;
-
+    toArray(): Matrix3Tuple;
     /**
-     * Multiplies this matrix by m.
+     * Writes the elements of this matrix to an array in
+     * {@link https://en.wikipedia.org/wiki/Row-_and_column-major_order#Column-major_order column-major} format.
+     * @param array array to store the resulting vector in. If not given a new array will be created.
+     * @param offset (optional) offset in the array at which to put the result.
      */
-    multiply(m: Matrix3): Matrix3;
-
-    premultiply(m: Matrix3): Matrix3;
+    toArray<TArray extends ArrayLike<number>>(array: TArray, offset?: number): TArray;
 
-    /**
-     * Sets this matrix to a x b.
-     */
-    multiplyMatrices(a: Matrix3, b: Matrix3): Matrix3;
-
-    /**
-     * @deprecated Use {@link Vector3.applyMatrix3 vector.applyMatrix3( matrix )} instead.
-     */
-    multiplyVector3(vector: Vector3): any;
-
-    /**
-     * @deprecated This method has been removed completely.
-     */
-    multiplyVector3Array(a: any): any;
-
-    /**
-     * @deprecated Use {@link Matrix3#invert .invert()} instead.
-     */
-    getInverse(matrix: Matrix4, throwOnDegenerate?: boolean): Matrix3;
-    getInverse(matrix: Matrix): Matrix;
-
-    /**
-     * @deprecated Use {@link Matrix3#toArray .toArray()} instead.
-     */
-    flattenToArrayOffset(array: number[], offset: number): number[];
+    clone(): this;
 }