@types/three 0.165.0 → 0.167.0

three/src/extras/DataUtils.d.ts

@@ -4,7 +4,7 @@
  * @see {@link https://threejs.org/docs/index.html#api/en/extras/DataUtils | Official Documentation}
  * @see {@link https://github.com/mrdoob/three.js/blob/master/src/extras/DataUtils.js | Source}
  */
-export function toHalfFloat(val: number): number;
+declare function toHalfFloat(val: number): number;
 
 /**
  * Returns a single precision floating point value from the given half precision floating point value.
@@ -12,4 +12,11 @@ export function toHalfFloat(val: number): number;
  * @see {@link https://threejs.org/docs/index.html#api/en/extras/DataUtils | Official Documentation}
  * @see {@link https://github.com/mrdoob/three.js/blob/master/src/extras/DataUtils.js | Source}
  */
-export function fromHalfFloat(val: number): number;
+declare function fromHalfFloat(val: number): number;
+
+declare const DataUtils: {
+    toHalfFloat: typeof toHalfFloat;
+    fromHalfFloat: typeof fromHalfFloat;
+};
+
+export { DataUtils, fromHalfFloat, toHalfFloat };

three/src/extras/ImageUtils.d.ts

@@ -1,17 +1,14 @@
-import { Mapping } from "../constants.js";
-import { Texture } from "../textures/Texture.js";
-
 /**
  * A class containing utility functions for images.
  * @see {@link https://threejs.org/docs/index.html#api/en/extras/ImageUtils | Official Documentation}
  * @see {@link https://github.com/mrdoob/three.js/blob/master/src/extras/ImageUtils.js | Source}
  */
-export namespace ImageUtils {
+declare class ImageUtils {
     /**
      * Returns a data URI containing a representation of the given image.
      * @param image The image object.
      */
-    function getDataURL(
+    static getDataURL(
         image: HTMLImageElement | HTMLCanvasElement | CanvasImageSource | ImageBitmap | ImageData,
     ): string;
 
@@ -19,15 +16,17 @@ export namespace ImageUtils {
      * Converts the given sRGB image data to linear color space.
      * @param image
      */
-    function sRGBToLinear(image: HTMLImageElement | HTMLCanvasElement | ImageBitmap): HTMLCanvasElement;
+    static sRGBToLinear(image: HTMLImageElement | HTMLCanvasElement | ImageBitmap): HTMLCanvasElement;
 
     /**
      * Converts the given sRGB image data to linear color space.
      * @param image
      */
-    function sRGBToLinear(image: ImageData): {
+    static sRGBToLinear(image: ImageData): {
         data: ImageData["data"];
         width: ImageData["width"];
         height: ImageData["height"];
     };
 }
+
+export { ImageUtils };

three/src/extras/ShapeUtils.d.ts

@@ -1,7 +1,4 @@
-export interface Vec2 {
-    x: number;
-    y: number;
-}
+import { Vector2Like } from "../math/Vector2.js";
 
 /**
  * A class containing utility functions for shapes.
@@ -9,20 +6,20 @@ export interface Vec2 {
  * @see {@link https://threejs.org/docs/index.html#api/en/extras/ShapeUtils | Official Documentation}
  * @see {@link https://github.com/mrdoob/three.js/blob/master/src/extras/ShapeUtils.js | Source}
  */
-export namespace ShapeUtils {
+export class ShapeUtils {
     /**
      * Calculate area of a ( 2D ) contour polygon.
      */
-    function area(contour: Vec2[]): number;
+    static area(contour: readonly Vector2Like[]): number;
 
     /**
      * Note that this is a linear function so it is necessary to calculate separately for x, y components of a polygon.
      * @remarks Used internally by {@link THREE.Path | Path}, {@link THREE.ExtrudeGeometry | ExtrudeGeometry} and {@link THREE.ShapeGeometry | ShapeGeometry}.
      */
-    function isClockWise(pts: Vec2[]): boolean;
+    static isClockWise(pts: readonly Vector2Like[]): boolean;
 
     /**
      * Used internally by {@link THREE.ExtrudeGeometry | ExtrudeGeometry} and {@link THREE.ShapeGeometry | ShapeGeometry} to calculate faces in shapes with holes.
      */
-    function triangulateShape(contour: Vec2[], holes: Vec2[][]): number[][];
+    static triangulateShape(contour: Vector2Like[], holes: Vector2Like[][]): number[][];
 }

three/src/extras/TextureUtils.d.ts

@@ -0,0 +1,42 @@
+import { CompressedPixelFormat, PixelFormat, TextureDataType } from "../constants.js";
+import { Texture } from "../textures/Texture.js";
+
+/**
+ * Scales the texture as large as possible within its surface without cropping or stretching the texture. The method
+ * preserves the original aspect ratio of the texture. Akin to CSS `object-fit: contain`.
+ */
+declare function contain(texture: Texture, aspect: number): Texture;
+
+/**
+ * Scales the texture to the smallest possible size to fill the surface, leaving no empty space. The method preserves
+ * the original aspect ratio of the texture. Akin to CSS `object-fit: cover`.
+ */
+declare function cover(texture: Texture, aspect: number): Texture;
+
+/**
+ * Configures the texture to the default transformation. Akin to CSS `object-fit: fill`.
+ */
+declare function fill(texture: Texture): Texture;
+
+/**
+ * Given the width, height, format, and type of a texture. Determines how many bytes must be used to represent the
+ * texture.
+ */
+declare function getByteLength(
+    width: number,
+    height: number,
+    format: PixelFormat | CompressedPixelFormat,
+    type: TextureDataType,
+): number;
+
+/**
+ * A class containing utility functions for textures.
+ */
+declare const TextureUtils: {
+    contain: typeof contain;
+    cover: typeof cover;
+    fill: typeof fill;
+    getByteLength: typeof getByteLength;
+};
+
+export { contain, cover, fill, getByteLength, TextureUtils };

three/src/extras/core/Curve.d.ts

@@ -1,6 +1,12 @@
 import { Vector2 } from "../../math/Vector2.js";
 import { Vector3 } from "../../math/Vector3.js";
 
+export interface CurveJSON {
+    metadata: { version: number; type: string; generator: string };
+    arcLengthDivisions: number;
+    type: string;
+}
+
 /**
  * An abstract base class for creating a {@link Curve} object that contains methods for interpolation
  * @remarks
@@ -146,11 +152,11 @@ export abstract class Curve<TVector extends Vector2 | Vector3> {
     /**
      * Returns a JSON object representation of this instance.
      */
-    toJSON(): {};
+    toJSON(): CurveJSON;
 
     /**
      * Copies the data from the given JSON object to this instance.
      * @param json
      */
-    fromJSON(json: {}): this;
+    fromJSON(json: CurveJSON): this;
 }

three/src/extras/core/CurvePath.d.ts

@@ -1,6 +1,11 @@
 import { Vector2 } from "../../math/Vector2.js";
 import { Vector3 } from "../../math/Vector3.js";
-import { Curve } from "./Curve.js";
+import { Curve, CurveJSON } from "./Curve.js";
+
+export interface CurvePathJSON extends CurveJSON {
+    autoClose: boolean;
+    curves: CurveJSON[];
+}
 
 /**
  * Curved Path - a curve path is simply a array of connected curves, but retains the api of a curve.
@@ -66,4 +71,7 @@ export class CurvePath<TVector extends Vector2 | Vector3> extends Curve<TVector>
      * @param divisions Number of pieces to divide the curve into. Expects a `Integer`. Default `40`
      */
     override getSpacedPoints(divisions?: number): TVector[];
+
+    toJSON(): CurvePathJSON;
+    fromJSON(json: CurvePathJSON): this;
 }

three/src/extras/core/Path.d.ts

@@ -1,5 +1,9 @@
-import { Vector2 } from "../../math/Vector2.js";
-import { CurvePath } from "./CurvePath.js";
+import { Vector2, Vector2Tuple } from "../../math/Vector2.js";
+import { CurvePath, CurvePathJSON } from "./CurvePath.js";
+
+export interface PathJSON extends CurvePathJSON {
+    currentPoint: Vector2Tuple;
+}
 
 /**
  * A 2D {@link Path} representation.
@@ -156,4 +160,7 @@ export class Path extends CurvePath<Vector2> {
      * @param points An array of {@link Vector2 | Vector2's}
      */
     splineThru(pts: Vector2[]): this;
+
+    toJSON(): PathJSON;
+    fromJSON(json: PathJSON): this;
 }

three/src/extras/core/Shape.d.ts

@@ -1,5 +1,10 @@
 import { Vector2 } from "../../math/Vector2.js";
-import { Path } from "./Path.js";
+import { Path, PathJSON } from "./Path.js";
+
+export interface ShapeJSON extends PathJSON {
+    uuid: string;
+    holes: PathJSON[];
+}
 
 /**
  * Defines an arbitrary 2d {@link Shape} plane using paths with optional holes
@@ -75,4 +80,7 @@ export class Shape extends Path {
      * @param divisions The fineness of the result. Expects a `Integer`
      */
     getPointsHoles(divisions: number): Vector2[][];
+
+    toJSON(): ShapeJSON;
+    fromJSON(json: ShapeJSON): this;
 }

three/src/lights/Light.d.ts

@@ -1,6 +1,21 @@
-import { Object3D } from "../core/Object3D.js";
+import { JSONMeta, Object3D, Object3DJSON } from "../core/Object3D.js";
 import { Color, ColorRepresentation } from "../math/Color.js";
-import { LightShadow } from "./LightShadow.js";
+import { LightShadow, LightShadowJSON } from "./LightShadow.js";
+
+export interface LightJSON extends Object3DJSON {
+    color: number;
+    intensity: number;
+
+    groundColor?: number;
+
+    distance?: number;
+    angle?: number;
+    decay?: number;
+    penumbra?: number;
+
+    shadow?: LightShadowJSON;
+    target?: string;
+}
 
 /**
  * Abstract base class for lights.
@@ -62,4 +77,6 @@ export abstract class Light<TShadowSupport extends LightShadow | undefined = Lig
      * Call this method whenever this instance is no longer used in your app.
      */
     dispose(): void;
+
+    toJSON(meta?: JSONMeta): LightJSON;
 }

three/src/lights/LightShadow.d.ts

@@ -1,11 +1,22 @@
 import { Camera } from "../cameras/Camera.js";
+import { Object3DJSONObject } from "../core/Object3D.js";
 import { Frustum } from "../math/Frustum.js";
 import { Matrix4 } from "../math/Matrix4.js";
-import { Vector2 } from "../math/Vector2.js";
+import { Vector2, Vector2Tuple } from "../math/Vector2.js";
 import { Vector4 } from "../math/Vector4.js";
 import { WebGLRenderTarget } from "../renderers/WebGLRenderTarget.js";
 import { Light } from "./Light.js";
 
+export interface LightShadowJSON {
+    intensity?: number;
+    bias?: number;
+    normalBias?: number;
+    radius?: number;
+    mapSize?: Vector2Tuple;
+
+    camera: Omit<Object3DJSONObject, "matrix">;
+}
+
 /**
  * Serves as a base class for the other shadow classes.
  * @see {@link https://threejs.org/docs/index.html#api/en/lights/shadows/LightShadow | Official Documentation}
@@ -24,6 +35,11 @@ export class LightShadow<TCamera extends Camera = Camera> {
      */
     camera: TCamera;
 
+    /**
+     * The intensity of the shadow. The default is `1`. Valid values are in the range `[0, 1]`.
+     */
+    intensity: number;
+
     /**
      * Shadow map bias, how much to add or subtract from the normalized depth when deciding whether a surface is in shadow.
      * @remark The Very tiny adjustments here (in the order of 0.0001) may help reduce artifacts in shadows.
@@ -122,7 +138,7 @@ export class LightShadow<TCamera extends Camera = Camera> {
     /**
      * Serialize this LightShadow.
      */
-    toJSON(): {};
+    toJSON(): LightShadowJSON;
 
     /**
      * Gets the shadow cameras frustum

three/src/lights/webgpu/IESSpotLight.d.ts

@@ -0,0 +1,6 @@
+import { Texture } from "../../textures/Texture.js";
+import { SpotLight } from "../SpotLight.js";
+
+export default class IESSpotLight extends SpotLight {
+    iesMap: Texture | null;
+}

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.
  */
@@ -394,17 +556,6 @@ export class Material extends EventDispatcher<{ dispose: {} }> {
      */
     set alphaTest(value: number);
 
-    onBuild(object: Object3D, parameters: WebGLProgramParametersWithUniforms, renderer: WebGLRenderer): void;
-
-    onBeforeRender(
-        renderer: WebGLRenderer,
-        scene: Scene,
-        camera: Camera,
-        geometry: BufferGeometry,
-        object: Object3D,
-        group: Group,
-    ): void;
-
     /**
      * An optional callback that is executed immediately before the shader program is compiled.
      * This function is called with the associated WebGL program parameters and renderer.
@@ -429,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.
@@ -443,7 +594,10 @@ export class Material extends EventDispatcher<{ dispose: {} }> {
     copy(material: Material): this;
 
     /**
-     * This disposes the material. Textures of a material don't get disposed. These needs to be disposed by {@link Texture}.
+     * Frees the GPU-related resources allocated by this instance. Call this method whenever this instance is no longer
+     * used in your app.
+     *
+     * Material textures must be disposed of by the dispose() method of {@link Texture}.
      */
     dispose(): void;
 
@@ -453,4 +607,21 @@ export class Material extends EventDispatcher<{ dispose: {} }> {
      * @default false
      */
     set needsUpdate(value: boolean);
+
+    /**
+     * @deprecated onBuild() has been removed.
+     */
+    onBuild(object: Object3D, parameters: WebGLProgramParametersWithUniforms, renderer: WebGLRenderer): void;
+
+    /**
+     * @deprecated onBeforeRender() has been removed.
+     */
+    onBeforeRender(
+        renderer: WebGLRenderer,
+        scene: Scene,
+        camera: Camera,
+        geometry: BufferGeometry,
+        object: Object3D,
+        group: Group,
+    ): void;
 }

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;