@types/three 0.167.2 → 0.169.0

three/examples/jsm/controls/TransformControls.d.ts

@@ -1,12 +1,29 @@
-import { Camera, Mesh, MOUSE, Object3D, Object3DEventMap, Quaternion, Raycaster, Vector3 } from "three";
+import { Camera, Controls, Mesh, Object3D, Quaternion, Raycaster, Vector3 } from "three";
 
 type TransformControlsMode = "translate" | "rotate" | "scale";
 
-export interface TransformControlsEventMap extends Object3DEventMap {
+export interface TransformControlsEventMap {
+    /**
+     * Fires if any type of change (object or property change) is performed. Property changes are separate events you
+     * can add event listeners to. The event type is "propertyname-changed".
+     */
     change: {};
+
+    /**
+     * Fires if a pointer (mouse/touch) becomes active.
+     */
     mouseDown: { mode: TransformControlsMode };
+
+    /**
+     * Fires if a pointer (mouse/touch) is no longer active.
+     */
     mouseUp: { mode: TransformControlsMode };
+
+    /**
+     * Fires if the controlled 3D object is changed.
+     */
     objectChange: {};
+
     "camera-changed": { value: unknown };
     "object-changed": { value: unknown };
     "enabled-changed": { value: unknown };
@@ -34,55 +51,164 @@ export interface TransformControlsEventMap extends Object3DEventMap {
     "eye-changed": { value: unknown };
 }
 
-export class TransformControls extends Object3D<TransformControlsEventMap> {
-    constructor(object: Camera, domElement?: HTMLElement);
-
-    domElement: HTMLElement;
-
-    // API
-
+/**
+ * This class can be used to transform objects in 3D space by adapting a similar interaction model of DCC tools like
+ * Blender. Unlike other controls, it is not intended to transform the scene's camera.
+ *
+ * TransformControls expects that its attached 3D object is part of the scene graph.
+ */
+declare class TransformControls extends Controls<TransformControlsEventMap> {
+    /**
+     * The camera of the rendered scene.
+     */
     camera: Camera;
-    object: Object3D | undefined;
-    enabled: boolean;
+
+    /**
+     * The current transformation axis.
+     */
     axis: "X" | "Y" | "Z" | "E" | "XY" | "YZ" | "XZ" | "XYZ" | "XYZE" | null;
+
+    /**
+     * The current transformation mode. Possible values are "translate", "rotate" and "scale". Default is `translate`.
+     */
     mode: TransformControlsMode;
+
+    /**
+     * By default, 3D objects are continuously translated. If you set this property to a numeric value (world units),
+     * you can define in which steps the 3D object should be translated. Default is `null`.
+     */
     translationSnap: number | null;
+
+    /**
+     * By default, 3D objects are continuously rotated. If you set this property to a numeric value (radians), you can
+     * define in which steps the 3D object should be rotated. Default is `null`.
+     */
     rotationSnap: number | null;
+
+    /**
+     * Defines in which coordinate space transformations should be performed. Possible values are "world" and "local".
+     * Default is `world`.
+     */
     space: "world" | "local";
+
+    /**
+     * The size of the helper UI (axes/planes). Default is *1*.
+     */
     size: number;
+
+    /**
+     * Whether or not dragging is currently performed. Read-only property.
+     */
     dragging: boolean;
+
+    /**
+     * Whether or not the x-axis helper should be visible. Default is `true`.
+     */
     showX: boolean;
+
+    /**
+     * Whether or not the y-axis helper should be visible. Default is `true`.
+     */
     showY: boolean;
+
+    /**
+     * Whether or not the z-axis helper should be visible. Default is `true`.
+     */
     showZ: boolean;
 
-    readonly isTransformControls: true;
-    mouseButtons: {
-        LEFT?: MOUSE | null | undefined;
-        MIDDLE?: MOUSE | null | undefined;
-        RIGHT?: MOUSE | null | undefined;
-    };
+    /**
+     * Creates a new instance of TransformControls.
+     * @param camera The camera of the rendered scene.
+     * @param domElement The HTML element used for event listeners. (optional)
+     */
+    constructor(camera: Camera, domElement?: HTMLElement);
+
+    /**
+     * Returns the visual representation of the controls. Add the helper to your scene to visually transform the
+     * attached 3D object.
+     */
+    getHelper(): TransformControlsRoot;
 
     pointerHover(pointer: PointerEvent | null): void;
     pointerDown(pointer: PointerEvent | null): void;
     pointerMove(pointer: PointerEvent | null): void;
     pointerUp(pointer: PointerEvent | null): void;
 
+    /**
+     * Sets the 3D object that should be transformed and ensures the controls UI is visible.
+     * @param object The 3D object that should be transformed.
+     */
     attach(object: Object3D): this;
+
+    /**
+     * Removes the current 3D object from the controls and makes the helper UI invisible.
+     */
     detach(): this;
-    getMode(): TransformControlsMode;
+
+    /**
+     * Resets the object's position, rotation and scale to when the current transform began.
+     */
+    reset(): void;
+
+    /**
+     * Returns the {@link Raycaster} object that is used for user interaction. This object is shared between all
+     * instances of TransformControls. If you set the [.layers]{@link Object3D.layers} property of the
+     * TransformControls, you will also want to set the [.layers]{@link Raycaster.layers} property on the
+     * {@link Raycaster} with a matching value, or else the TransformControls won't work as expected.
+     */
     getRaycaster(): Raycaster;
+
+    /**
+     * Returns the transformation mode.
+     */
+    getMode(): TransformControlsMode;
+
+    /**
+     * Sets the transformation mode.
+     * @param mode The transformation mode.
+     */
     setMode(mode: TransformControlsMode): void;
+
+    /**
+     * Sets the translation snap.
+     * @param translationSnap The translation snap.
+     */
     setTranslationSnap(translationSnap: number | null): void;
+
+    /**
+     * Sets the rotation snap.
+     * @param rotationSnap The rotation snap.
+     */
     setRotationSnap(rotationSnap: number | null): void;
+
+    /**
+     * Sets the scale snap.
+     * @param scaleSnap The scale snap.
+     */
     setScaleSnap(scaleSnap: number | null): void;
+
+    /**
+     * Sets the size of the helper UI.
+     * @param size The size of the helper UI.
+     */
     setSize(size: number): void;
+
+    /**
+     * Sets the coordinate space in which transformations are applied.
+     * @param space The coordinate space in which transformations are applied.
+     */
     setSpace(space: "world" | "local"): void;
-    reset(): void;
-    dispose(): void;
 }
 
-export class TransformControlsGizmo extends Object3D {
-    type: "TransformControlsGizmo";
+declare class TransformControlsRoot extends Object3D {
+    readonly isTransformControlsRoot: true;
+
+    controls: TransformControls;
+
+    constructor(controls: TransformControls);
+}
+
+declare class TransformControlsGizmo extends Object3D {
     isTransformControlsGizmo: true;
 
     gizmo: {
@@ -104,9 +230,8 @@ export class TransformControlsGizmo extends Object3D {
     constructor();
 }
 
-export class TransformControlsPlane extends Mesh {
-    type: "TransformControlsPlane";
-    isTransformControlsPlane: true;
+declare class TransformControlsPlane extends Mesh {
+    readonly isTransformControlsPlane: true;
 
     constructor();
 
@@ -120,3 +245,5 @@ export class TransformControlsPlane extends Mesh {
     worldPosition: Vector3;
     worldQuaternion: Quaternion;
 }
+
+export { TransformControls, TransformControlsGizmo, TransformControlsPlane };

three/examples/jsm/effects/AnaglyphEffect.d.ts

@@ -1,11 +1,17 @@
 import { Camera, Matrix3, Scene, WebGLRenderer } from "three";
 
-export class AnaglyphEffect {
-    constructor(renderer: WebGLRenderer, width?: number, height?: number);
+declare class AnaglyphEffect {
     colorMatrixLeft: Matrix3;
+
     colorMatrixRight: Matrix3;
 
-    dispose(): void;
-    render(scene: Scene, camera: Camera): void;
-    setSize(width: number, height: number): void;
+    setSize: (width: number, height: number) => void;
+
+    render: (scene: Scene, camera: Camera) => void;
+
+    dispose: () => void;
+
+    constructor(renderer: WebGLRenderer, width?: number, height?: number);
 }
+
+export { AnaglyphEffect };

three/examples/jsm/effects/ParallaxBarrierEffect.d.ts

@@ -1,8 +1,11 @@
 import { Camera, Scene, WebGLRenderer } from "three";
 
-export class ParallaxBarrierEffect {
-    constructor(renderer: WebGLRenderer);
+declare class ParallaxBarrierEffect {
+    setSize: (width: number, height: number) => void;
+    render: (scene: Scene, camera: Camera) => void;
+    dispose: () => void;
 
-    render(scene: Scene, camera: Camera): void;
-    setSize(width: number, height: number): void;
+    constructor(renderer: WebGLRenderer);
 }
+
+export { ParallaxBarrierEffect };

three/examples/jsm/environments/RoomEnvironment.d.ts

@@ -1,6 +1,6 @@
-import { Scene, WebGLRenderer } from "three";
+import { Scene } from "three";
 
 export class RoomEnvironment extends Scene {
-    constructor(renderer?: WebGLRenderer);
+    constructor();
     dispose(): void;
 }

three/examples/jsm/exporters/EXRExporter.d.ts

@@ -6,6 +6,7 @@
  */
 
 import { DataTexture, TextureDataType, WebGLRenderer, WebGLRenderTarget } from "three";
+import { WebGPURenderer } from "three/webgpu";
 
 export const NO_COMPRESSION: 0;
 export const ZIPS_COMPRESSION: 2;
@@ -17,6 +18,10 @@ export interface EXRExporterParseOptions {
 }
 
 export class EXRExporter {
-    parse(renderer: WebGLRenderer, renderTarget: WebGLRenderTarget, options?: EXRExporterParseOptions): Uint8Array;
-    parse(dataTexture: DataTexture, options?: EXRExporterParseOptions): Uint8Array;
+    parse(
+        renderer: WebGLRenderer | WebGPURenderer,
+        renderTarget: WebGLRenderTarget,
+        options?: EXRExporterParseOptions,
+    ): Promise<Uint8Array>;
+    parse(dataTexture: DataTexture, options?: EXRExporterParseOptions): Promise<Uint8Array>;
 }

three/examples/jsm/exporters/KTX2Exporter.d.ts

@@ -1,5 +1,7 @@
 import { Data3DTexture, DataTexture, WebGLRenderer, WebGLRenderTarget } from "three";
+import { WebGPURenderer } from "three/webgpu";
 
 export class KTX2Exporter {
-    parse(arg1: Data3DTexture | DataTexture | WebGLRenderer, arg2?: WebGLRenderTarget): Uint8Array;
+    parse(renderer: WebGLRenderer | WebGPURenderer, rtt?: WebGLRenderTarget): Promise<Uint8Array>;
+    parse(texture: Data3DTexture | DataTexture): Promise<Uint8Array>;
 }

three/examples/jsm/helpers/LightProbeHelper.d.ts

@@ -1,10 +1,12 @@
 import { LightProbe, Mesh } from "three";
 
-export class LightProbeHelper extends Mesh {
-    constructor(lightProbe: LightProbe, size: number);
-
+declare class LightProbeHelper extends Mesh {
     lightProbe: LightProbe;
     size: number;
 
+    constructor(lightProbe: LightProbe, size?: number);
+
     dispose(): void;
 }
+
+export { LightProbeHelper };

three/examples/jsm/helpers/LightProbeHelperGPU.d.ts

@@ -0,0 +1,12 @@
+import { LightProbe, Mesh } from "three";
+
+declare class LightProbeHelper extends Mesh {
+    lightProbe: LightProbe;
+    size: number;
+
+    constructor(lightProbe: LightProbe, size?: number);
+
+    dispose(): void;
+}
+
+export { LightProbeHelper };

three/examples/jsm/lights/LightProbeGenerator.d.ts

@@ -1,6 +1,10 @@
 import { CubeTexture, LightProbe, WebGLCubeRenderTarget, WebGLRenderer } from "three";
+import { WebGPURenderer } from "three/webgpu";
 
 export namespace LightProbeGenerator {
     function fromCubeTexture(cubeTexture: CubeTexture): LightProbe;
-    function fromCubeRenderTarget(renderer: WebGLRenderer, cubeRenderTarget: WebGLCubeRenderTarget): LightProbe;
+    function fromCubeRenderTarget(
+        renderer: WebGLRenderer | WebGPURenderer,
+        cubeRenderTarget: WebGLCubeRenderTarget,
+    ): Promise<LightProbe>;
 }

three/examples/jsm/lines/Line2.d.ts

@@ -2,10 +2,24 @@ import { LineGeometry } from "./LineGeometry.js";
 import { LineMaterial } from "./LineMaterial.js";
 import { LineSegments2 } from "./LineSegments2.js";
 
+/**
+ * A polyline drawn between vertices.
+ *
+ * This adds functionality beyond {@link Line}, like arbitrary line width and changing width to be in world units. It
+ * extends {@link LineSegments2}, simplifying constructing segments from a chain of points.
+ */
 export class Line2 extends LineSegments2 {
     geometry: LineGeometry;
     material: LineMaterial;
 
-    constructor(geometry?: LineGeometry, material?: LineMaterial);
+    /**
+     * Read-only flag to check if a given object is of type Line2.
+     */
     readonly isLine2: true;
+
+    /**
+     * @param geometry (optional) Pair(s) of vertices representing each line segment
+     * @param material (optional) Material for the line. Default is a {@link LineMaterial} with random color.
+     */
+    constructor(geometry?: LineGeometry, material?: LineMaterial);
 }

three/examples/jsm/lines/LineGeometry.d.ts

@@ -2,9 +2,26 @@ import { Line } from "three";
 
 import { LineSegmentsGeometry } from "./LineSegmentsGeometry.js";
 
+/**
+ * A chain of vertices, forming a polyline.
+ *
+ * This is used in {@link Line2} to describe the shape.
+ */
 export class LineGeometry extends LineSegmentsGeometry {
-    constructor();
+    /**
+     * Read-only flag to check if a given object is of type LineGeometry.
+     */
     readonly isLineGeometry: true;
 
+    /**
+     * Creates a new geometry.
+     * Call [setPositions]{@link LineGeometry.setPositions} to add segments.
+     */
+    constructor();
+
+    /**
+     * Copy the vertex positions of a {@link Line} object into this geometry.
+     * Assumes the source geometry is not using indices.
+     */
     fromLine(line: Line): this;
 }

three/examples/jsm/lines/LineMaterial.d.ts

@@ -12,18 +12,71 @@ export interface LineMaterialParameters extends ShaderMaterialParameters {
     worldUnits?: boolean | undefined;
 }
 
+/**
+ * A material for drawing wireframe-style geometries.
+ * Unlike {@link LineBasicMaterial}, it supports arbitrary line widths and allows using world units instead of screen
+ * space units. This material is used with {@link LineSegments2} and {@link Line2}.
+ *
+ * Lines are always rendered with round caps and round joints.
+ */
 export class LineMaterial extends ShaderMaterial {
-    constructor(parameters?: LineMaterialParameters);
-    color: Color;
-    dashed: boolean;
-    dashScale: number;
-    dashSize: number;
-    dashOffset: number;
-    gapSize: number;
-    opacity: number;
     readonly isLineMaterial: true;
-    linewidth: number;
-    resolution: Vector2;
-    alphaToCoverage: boolean;
-    worldUnits: boolean;
+
+    /**
+     * @param parameters (optional) an object with one or more properties defining the material's appearance. Any
+     * property of the material (including any property inherited from {@link ShaderMaterial}) can be passed in here.
+     *
+     * The exception is the property color, which can be passed in as a number or hexadecimal string and is `0xffffff`
+     * (white) by default. Color.set( color ) is called internally.
+     */
+    constructor(parameters?: LineMaterialParameters);
+
+    /**
+     * {@link Color} of the material, by default set to white (0xffffff).
+     */
+    get color(): Color;
+    set color(value: Color);
+
+    /**
+     * Whether the material's sizes (width, dash gaps) are in world units. Default is `false` (screen space units.)
+     */
+    get worldUnits(): boolean;
+    set worldUnits(value: boolean);
+
+    /**
+     * Whether the line is dashed, or solid. Default is `false`.
+     */
+    get dashed(): boolean;
+    set dashed(value: boolean);
+
+    /**
+     * The scale of the dashes and gaps. Default is `1`.
+     */
+    get dashScale(): number;
+    set dashScale(value: number);
+
+    /**
+     * The size of the dash. Default is `1`.
+     */
+    get dashSize(): number;
+    set dashSize(value: number);
+
+    /**
+     * Where in the dash cycle the dash starts. Default is `0`.
+     */
+    get dashOffset(): number;
+    set dashOffset(value: number);
+
+    /**
+     * The size of the gap. Default is `1`.
+     */
+    get gapSize(): number;
+    set gapSize(value: number);
+
+    /**
+     * The size of the viewport, in screen pixels. This must be kept updated to make screen-space rendering accurate.
+     * The {@link LineSegments2.onBeforeRender} callback performs the update for visible objects. Default is `[1, 1]`.
+     */
+    get resolution(): Vector2;
+    set resolution(value: Vector2);
 }

three/examples/jsm/lines/LineSegments2.d.ts

@@ -1,14 +1,37 @@
-import { Mesh } from "three";
+import { Mesh, WebGLRenderer } from "three";
 
 import { LineMaterial } from "./LineMaterial.js";
 import { LineSegmentsGeometry } from "./LineSegmentsGeometry.js";
 
+/**
+ * A series of lines drawn between pairs of vertices.
+ *
+ * This adds functionality beyond {@link LineSegments}, like arbitrary line width and changing width to be in world
+ * units. The {@link Line2} extends this object, forming a polyline instead of individual segments.
+ */
 export class LineSegments2 extends Mesh {
     geometry: LineSegmentsGeometry;
     material: LineMaterial;
 
-    constructor(geometry?: LineSegmentsGeometry, material?: LineMaterial);
+    /**
+     * Read-only flag to check if a given object is of type LineSegments2.
+     */
     readonly isLineSegments2: true;
 
+    /**
+     * @param geometry (optional) Pair(s) of vertices representing each line segment.
+     * @param material (optional) Material for the line. Default is a {@link LineMaterial} with random color.
+     */
+    constructor(geometry?: LineSegmentsGeometry, material?: LineMaterial);
+
     computeLineDistances(): this;
+
+    /**
+     * Called by the framework to update the material's resolution property, needed for screen-scaled widths.
+     *
+     * If your object is not visible to a camera (e.g. by [layers]{@link Object3D.layers} or
+     * [visible]{@link Object3D.visible}), you must call this manually whenever the viewport changes.
+     * @param renderer
+     */
+    onBeforeRender(renderer: WebGLRenderer): void;
 }

three/examples/jsm/lines/LineSegmentsGeometry.d.ts

@@ -1,16 +1,53 @@
-import { EdgesGeometry, InstancedBufferGeometry, LineSegments, Matrix4, Mesh, WireframeGeometry } from "three";
+import { EdgesGeometry, InstancedBufferGeometry, LineSegments, Mesh, WireframeGeometry } from "three";
 
+/**
+ * A series of vertex pairs, forming line segments.
+ *
+ * This is used in {@link LineSegments2} to describe the shape.
+ */
 export class LineSegmentsGeometry extends InstancedBufferGeometry {
-    constructor();
+    /**
+     * Read-only flag to check if a given object is of type LineSegmentsGeometry.
+     */
     readonly isLineSegmentsGeometry: true;
 
-    applyMatrix4(matrix: Matrix4): this;
-    computeBoundingBox(): void;
-    computeBoundingSphere(): void;
+    /**
+     * Creates a new geometry. Call [setPositions]{@link LineSegmentsGeometry.setPositions} to add segments.
+     */
+    constructor();
+
+    /**
+     * Replace the vertex positions with a new set. The array can be an `Array` or `Float32Array`. The length must be a
+     * multiple of six.
+     * @param array
+     */
+    setPositions(array: number[] | Float32Array): this;
+
+    /**
+     * Replace the per-vertex colors. Every sixtuple describes a segment: `[r1, g1, b1, r2, g2, b2]`. The array can be
+     * an `Array` or `Float32Array`.
+     * @param array
+     */
+    setColors(array: number[] | Float32Array): this;
+
+    /**
+     * Copy the vertex positions of a wireframe geometry into this geometry.
+     */
+    fromWireframeGeometry(geometry: WireframeGeometry): this;
+
+    /**
+     * Copy the vertex positions of an edge geometry into this geometry.
+     */
     fromEdgesGeometry(geometry: EdgesGeometry): this;
-    fromLineSegments(lineSegments: LineSegments): this;
+
+    /**
+     * Copy the vertex positions of a mesh object into this geometry.
+     */
     fromMesh(mesh: Mesh): this;
-    fromWireframeGeometry(geometry: WireframeGeometry): this;
-    setColors(array: number[] | Float32Array): this;
-    setPositions(array: number[] | Float32Array): this;
+
+    /**
+     * Copy the vertex positions of a {@link LineSegments} object into this geometry. Assumes the source geometry is not
+     * using indices.
+     */
+    fromLineSegments(lineSegments: LineSegments): this;
 }

three/examples/jsm/loaders/DRACOLoader.d.ts

@@ -14,6 +14,12 @@ export class DRACOLoader extends Loader<BufferGeometry> {
         onError?: (err: unknown) => void,
     ): void;
 
+    parse(
+        buffer: ArrayBuffer,
+        onLoad?: (geometry: BufferGeometry) => void,
+        onError?: (err: unknown) => void,
+    ): void;
+
     preload(): DRACOLoader;
     dispose(): DRACOLoader;
 }

three/examples/jsm/loaders/KTX2Loader.d.ts

@@ -43,6 +43,10 @@ export class KTX2Loader extends Loader<CompressedTexture> {
      */
     detectSupport(renderer: WebGLRenderer | WebGPURenderer): this;
 
+    init(): Promise<void>;
+
+    parse(buffer: ArrayBuffer, onLoad?: (texture: CompressedTexture) => void, onError?: (err: unknown) => void): void;
+
     /**
      * Disposes the loader object, de-allocating any Web Workers created.
      */

three/examples/jsm/modifiers/CurveModifier.d.ts

@@ -7,7 +7,7 @@ export interface SplineUniform {
     spineOffset: IUniform;
     flow: IUniform;
 }
-export function initSplineTexture(size?: number): DataTexture;
+export function initSplineTexture(numberOfCurves?: number): DataTexture;
 
 export function updateSplineTexture(texture: DataTexture, splineCurve: Curve<Vector3>, offset?: number): void;
 
@@ -16,22 +16,26 @@ export function getUniforms(splineTexture: DataTexture): SplineUniform;
 export function modifyShader(material: Material, uniforms: SplineUniform, numberOfCurves?: number): void;
 
 export class Flow {
-    constructor(mesh: Mesh, numberOfCurves?: number);
     curveArray: number[];
     curveLengthArray: number[];
+
     object3D: Mesh;
     splineTexure: DataTexture;
     uniforms: SplineUniform;
+
+    constructor(mesh: Mesh, numberOfCurves?: number);
     updateCurve(index: number, curve: Curve<Vector3>): void;
     moveAlongCurve(amount: number): void;
 }
 
 export class InstancedFlow extends Flow {
-    constructor(count: number, curveCount: number, geometry: BufferGeometry, material: Material);
     object3D: InstancedMesh;
+
     offsets: number[];
     whichCurve: number[];
 
+    constructor(count: number, curveCount: number, geometry: BufferGeometry, material: Material);
+
     moveIndividualAlongCurve(index: number, offset: number): void;
     setCurve(index: number, curveNo: number): void;
 }