@types/three 0.149.0 → 0.150.1

three/src/objects/Points.d.ts

@@ -5,33 +5,64 @@ import { BufferGeometry } from '../core/BufferGeometry';
 import { Intersection } from '../core/Raycaster';
 
 /**
- * A class for displaying points. The points are rendered by the WebGLRenderer using gl.POINTS.
+ * A class for displaying {@link Points}
+ * @remarks
+ * The {@link Points} are rendered by the {@link THREE.WebGLRenderer | WebGLRenderer} using {@link https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/drawElements | gl.POINTS}.
+ * @see {@link https://threejs.org/docs/index.html#api/en/objects/Points | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/objects/Points.js | Source}
  */
 export class Points<
     TGeometry extends BufferGeometry = BufferGeometry,
     TMaterial extends Material | Material[] = Material | Material[],
 > extends Object3D {
     /**
-     * @param geometry An instance of BufferGeometry.
-     * @param material An instance of Material (optional).
+     * Create a new instance of {@link Points}
+     * @param geometry An instance of {@link THREE.BufferGeometry | BufferGeometry}. Default {@link THREE.BufferGeometry | `new THREE.BufferGeometry()`}.
+     * @param material A single or an array of {@link THREE.Material | Material}. Default {@link THREE.PointsMaterial | `new THREE.PointsMaterial()`}.
      */
     constructor(geometry?: TGeometry, material?: TMaterial);
 
-    type: 'Points';
+    /**
+     * Read-only flag to check if a given object is of type {@link Points}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isPoints: true;
+
+    /**
+     * @override
+     * @defaultValue `Points`
+     */
+    override readonly type: string | 'Points';
+
+    /**
+     * An array of weights typically from `0-1` that specify how much of the morph is applied.
+     * @defaultValue `undefined`, _but reset to a blank array by {@link updateMorphTargets | .updateMorphTargets()}._
+     */
     morphTargetInfluences?: number[] | undefined;
+
+    /**
+     * A dictionary of morphTargets based on the `morphTarget.name` property.
+     * @defaultValue `undefined`, _but rebuilt by {@link updateMorphTargets | .updateMorphTargets()}._
+     *
+     */
     morphTargetDictionary?: { [key: string]: number } | undefined;
-    readonly isPoints: true;
 
     /**
-     * An instance of BufferGeometry, where each vertex designates the position of a particle in the system.
+     * An instance of {@link THREE.BufferGeometry | BufferGeometry} (or derived classes), defining the object's structure.
+     * @remarks each vertex designates the position of a particle in the system.
      */
     geometry: TGeometry;
 
     /**
-     * An instance of Material, defining the object's appearance. Default is a PointsMaterial with randomised colour.
+     * An instance of {@link THREE.Material | Material}, defining the object's appearance.
+     * @defaultValue {@link THREE.PointsMaterial | `new THREE.PointsMaterial()`}, _with randomised colour_.
      */
     material: TMaterial;
 
-    raycast(raycaster: Raycaster, intersects: Intersection[]): void;
+    /**
+     * Updates the morphTargets to have no influence on the object
+     * @remarks Resets the {@link morphTargetInfluences} and {@link morphTargetDictionary} properties.
+     */
     updateMorphTargets(): void;
 }

three/src/objects/Skeleton.d.ts

@@ -2,28 +2,114 @@ import { Bone } from './Bone';
 import { Matrix4 } from './../math/Matrix4';
 import { DataTexture } from './../textures/DataTexture';
 
+/**
+ * Use an array of {@link Bone | bones} to create a {@link Skeleton} that can be used by a {@link THREE.SkinnedMesh | SkinnedMesh}.
+ * @example
+ * ```typescript
+ * // Create a simple "arm"
+ * const bones = [];
+ * const shoulder = new THREE.Bone();
+ * const elbow = new THREE.Bone();
+ * const hand = new THREE.Bone();
+ * shoulder.add(elbow);
+ * elbow.add(hand);
+ * bones.push(shoulder);
+ * bones.push(elbow);
+ * bones.push(hand);
+ * shoulder.position.y = -5;
+ * elbow.position.y = 0;
+ * hand.position.y = 5;
+ * const armSkeleton = new THREE.Skeleton(bones);
+ * See the[page: SkinnedMesh] page
+ * for an example of usage with standard[page: BufferGeometry].
+ * ```
+ * @see {@link https://threejs.org/docs/index.html#api/en/objects/Skeleton | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/objects/Skeleton.js | Source}
+ */
 export class Skeleton {
+    /**
+     * Creates a new 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[]);
 
+    /**
+     * {@link http://en.wikipedia.org/wiki/Universally_unique_identifier | UUID} of this object instance.
+     * @remarks This gets automatically assigned and shouldn't be edited.
+     */
     uuid: string;
+
+    /**
+     * The array of {@link THREE.Bone | Bones}.
+     * @remarks Note this is a copy of the original array, not a reference, so you can modify the original array without effecting this one.
+     */
     bones: Bone[];
+
+    /**
+     * An array of {@link Matrix4 | Matrix4s} that represent the inverse of the {@link THREE.Matrix4 | matrixWorld} of the individual bones.
+     */
     boneInverses: Matrix4[];
+
+    /**
+     * The array buffer holding the bone data when using a vertex texture.
+     */
     boneMatrices: Float32Array;
+
+    /**
+     * The {@link THREE.DataTexture | DataTexture} holding the bone data when using a vertex texture.
+     */
     boneTexture: null | DataTexture;
+
+    /**
+     * The size of the {@link boneTexture | .boneTexture}.
+     * @remarks Expects a `Integer`
+     */
     boneTextureSize: number;
+
     frame: number;
 
     init(): void;
+
+    /**
+     * Generates the {@link boneInverses} array if not provided in the constructor.
+     */
     calculateInverses(): void;
+
+    /**
+     * Computes an instance of {@link THREE.DataTexture | DataTexture} in order to pass the bone data more efficiently to the shader
+     * @remarks
+     * The texture is assigned to {@link boneTexture}.
+     */
     computeBoneTexture(): this;
+
+    /**
+     * Returns the skeleton to the base pose.
+     */
     pose(): void;
+
+    /**
+     * Updates the {@link boneMatrices} and {@link boneTexture} after changing the bones
+     * @remarks
+     * This is called automatically by the {@link THREE.WebGLRenderer | WebGLRenderer} if the {@link Skeleton} is used with a {@link THREE.SkinnedMesh | SkinnedMesh}.
+     */
     update(): void;
+
+    /**
+     * Returns a clone of this {@link Skeleton} object.
+     */
     clone(): Skeleton;
+
+    /**
+     * Searches through the skeleton's bone array and returns the first with a matching name.
+     * @param name String to match to the Bone's {@link THREE.Bone.name | .name} property.
+     */
     getBoneByName(name: string): undefined | Bone;
-    dispose(): void;
 
     /**
-     * @deprecated This property has been removed completely.
+     * Frees the GPU-related resources allocated by this instance
+     * @remarks
+     * Call this method whenever this instance is no longer used in your app.
      */
-    useVertexTexture: boolean;
+    dispose(): void;
 }

three/src/objects/SkinnedMesh.d.ts

@@ -5,21 +5,140 @@ import { Skeleton } from './Skeleton';
 import { Mesh } from './Mesh';
 import { BufferGeometry } from '../core/BufferGeometry';
 
+/**
+ * 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.
+ * @remarks
+ * {@link SkinnedMesh} can only be used with WebGL 2 or
+ * With WebGL 1 `OES_texture_float` and vertex textures support is required.
+ * @example
+ * ```typescript
+ * const geometry = new THREE.CylinderGeometry(5, 5, 5, 5, 15, 5, 30);
+ * // create the skin indices and skin weights manually
+ * // (typically a loader would read this data from a 3D model for you)
+ * const position = geometry.attributes.position;
+ * const vertex = new THREE.Vector3();
+ * const skinIndices = [];
+ * const skinWeights = [];
+ * for (let i = 0; i & lt; position.count; i++) {
+ *     vertex.fromBufferAttribute(position, i);
+ *     // compute skinIndex and skinWeight based on some configuration data
+ *     const y = (vertex.y + sizing.halfHeight);
+ *     const skinIndex = Math.floor(y / sizing.segmentHeight);
+ *     const skinWeight = (y % sizing.segmentHeight) / sizing.segmentHeight;
+ *     skinIndices.push(skinIndex, skinIndex + 1, 0, 0);
+ *     skinWeights.push(1 - skinWeight, skinWeight, 0, 0);
+ * }
+ * geometry.setAttribute('skinIndex', new THREE.Uint16BufferAttribute(skinIndices, 4));
+ * geometry.setAttribute('skinWeight', new THREE.Float32BufferAttribute(skinWeights, 4));
+ * // create skinned mesh and skeleton
+ * const mesh = new THREE.SkinnedMesh(geometry, material);
+ * const skeleton = new THREE.Skeleton(bones);
+ * // see example from THREE.Skeleton
+ * const rootBone = skeleton.bones[0];
+ * mesh.add(rootBone);
+ * // bind the skeleton to the mesh
+ * mesh.bind(skeleton);
+ * // move the bones and manipulate the model
+ * skeleton.bones[0].rotation.x = -0.1;
+ * skeleton.bones[1].rotation.x = 0.2;
+ * ```
+ * @see {@link https://threejs.org/docs/index.html#api/en/objects/SkinnedMesh | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/objects/SkinnedMesh.js | Source}
+ */
 export class SkinnedMesh<
     TGeometry extends BufferGeometry = BufferGeometry,
     TMaterial extends Material | Material[] = Material | Material[],
 > extends Mesh<TGeometry, TMaterial> {
+    /**
+     * Create a new instance of {@link SkinnedMesh}
+     * @param geometry An instance of {@link THREE.BufferGeometry | BufferGeometry}. Default {@link THREE.BufferGeometry | `new THREE.BufferGeometry()`}.
+     * @param material A single or an array of {@link THREE.Material | Material}. Default {@link THREE.MeshBasicMaterial | `new THREE.MeshBasicMaterial()`}.
+     */
     constructor(geometry?: TGeometry, material?: TMaterial, useVertexTexture?: boolean);
 
-    bindMode: string;
+    /**
+     * Read-only flag to check if a given object is of type {@link SkinnedMesh}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isSkinnedMesh: true;
+
+    /**
+     * @override
+     * @defaultValue `SkinnedMesh`
+     */
+    override readonly type: string | 'SkinnedMesh';
+
+    /**
+     * Either `attached` or `detached`.
+     *  - `attached` uses the {@link THREE.SkinnedMesh.matrixWorld | SkinnedMesh.matrixWorld} property for the base transform matrix of the bones.
+     *  - `detached` uses the {@link THREE.SkinnedMesh.bindMatrix | SkinnedMesh.bindMatrix}.
+     * @defaultValue `attached`.
+     */
+    bindMode: 'attached' | 'detached';
+
+    /**
+     * The base matrix that is used for the bound bone transforms.
+     */
     bindMatrix: Matrix4;
+    /**
+     * The base matrix that is used for resetting the bound bone transforms.
+     */
     bindMatrixInverse: Matrix4;
+
+    /**
+     * {@link THREE.Skeleton | Skeleton} representing the bone hierarchy of the skinned mesh.
+     */
     skeleton: Skeleton;
-    readonly isSkinnedMesh: true;
 
+    /**
+     * Bind a skeleton to the skinned mesh
+     * @remarks
+     * The bindMatrix gets saved to .bindMatrix property and the .bindMatrixInverse gets calculated.
+     * @param skeleton {@link THREE.Skeleton | Skeleton} created from a {@link Bone | Bones} tree.
+     * @param bindMatrix {@link THREE.Matrix4 | Matrix4} that represents the base transform of the skeleton.
+     */
     bind(skeleton: Skeleton, bindMatrix?: Matrix4): void;
+
+    /**
+     * This method sets the skinned mesh in the rest pose (resets the pose).
+     */
     pose(): void;
+
+    /**
+     * Normalizes the skin weights.
+     */
     normalizeSkinWeights(): void;
-    updateMatrixWorld(force?: boolean): 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 );
+     * ```
+     * @remarks Returns the updated vector.
+     * @param index Expects a `Integer`
+     * @param vector
+     */
     boneTransform(index: number, target: Vector3): Vector3;
 }

three/src/objects/Sprite.d.ts

@@ -5,16 +5,63 @@ import { Intersection } from '../core/Raycaster';
 import { SpriteMaterial } from '../materials/Materials';
 import { BufferGeometry } from '../core/BufferGeometry';
 
+/**
+ * A {@link Sprite} is a plane that always faces towards the camera, generally with a partially transparent texture applied.
+ * @remarks Sprites do not cast shadows, setting `castShadow = true` will have no effect.
+ * @example
+ * ```typescript
+ * const map = new THREE.TextureLoader().load('sprite.png');
+ * const material = new THREE.SpriteMaterial({
+ *     map: map
+ * });
+ * const {@link Sprite} = new THREE.Sprite(material);
+ * scene.add(sprite);
+ * ```
+ * @see {@link https://threejs.org/docs/index.html#api/en/objects/Sprite | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/objects/Sprite.js | Source}
+ */
 export class Sprite extends Object3D {
+    /**
+     * Creates a new Sprite.
+     * @param material An instance of {@link THREE.SpriteMaterial | SpriteMaterial}. Default {@link THREE.SpriteMaterial | `new SpriteMaterial()`}, _with white color_.
+     */
     constructor(material?: SpriteMaterial);
 
-    type: 'Sprite';
+    /**
+     * Read-only flag to check if a given object is of type {@link Sprite}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
     readonly isSprite: true;
 
+    /**
+     * @override
+     * @defaultValue `Sprite`
+     */
+    override readonly type: string | 'Sprite';
+
+    /**
+     * Whether the object gets rendered into shadow map.
+     * No effect in {@link Sprite}.
+     * @ignore
+     * @hidden
+     * @defaultValue `false`
+     */
+    override castShadow: false;
+
     geometry: BufferGeometry;
+
+    /**
+     * An instance of {@link THREE.SpriteMaterial | SpriteMaterial}, defining the object's appearance.
+     * @defaultValue {@link THREE.SpriteMaterial | `new SpriteMaterial()`}, _with white color_.
+     */
     material: SpriteMaterial;
-    center: Vector2;
 
-    raycast(raycaster: Raycaster, intersects: Intersection[]): void;
-    copy(source: this): this;
+    /**
+     * The sprite's anchor point, and the point around which the {@link Sprite} rotates.
+     * A value of (0.5, 0.5) corresponds to the midpoint of the sprite.
+     * A value of (0, 0) corresponds to the lower left corner of the sprite.
+     * @defaultValue {@link THREE.Vector2 | `new Vector2(0.5, 0.5)`}.
+     */
+    center: Vector2;
 }

three/src/renderers/WebGLRenderTarget.d.ts

@@ -2,13 +2,19 @@ import { Vector4 } from './../math/Vector4';
 import { Texture } from './../textures/Texture';
 import { DepthTexture } from './../textures/DepthTexture';
 import { EventDispatcher } from './../core/EventDispatcher';
-import { Wrapping, TextureFilter, TextureDataType, TextureEncoding } from '../constants';
+import {
+    Wrapping,
+    TextureDataType,
+    TextureEncoding,
+    MinificationTextureFilter,
+    MagnificationTextureFilter,
+} from '../constants';
 
 export interface WebGLRenderTargetOptions {
     wrapS?: Wrapping | undefined;
     wrapT?: Wrapping | undefined;
-    magFilter?: TextureFilter | undefined;
-    minFilter?: TextureFilter | undefined;
+    magFilter?: MagnificationTextureFilter | undefined;
+    minFilter?: MinificationTextureFilter | undefined;
     format?: number | undefined; // RGBAFormat;
     type?: TextureDataType | undefined; // UnsignedByteType;
     anisotropy?: number | undefined; // 1;

three/src/renderers/WebGLRenderer.d.ts

@@ -178,9 +178,9 @@ export class WebGLRenderer implements Renderer {
     outputEncoding: TextureEncoding;
 
     /**
-     * @default false
+     * @default true
      */
-    physicallyCorrectLights: boolean;
+    useLegacyLights: boolean;
 
     /**
      * @default THREE.NoToneMapping

three/src/scenes/Fog.d.ts

@@ -2,42 +2,94 @@ import { ColorRepresentation } from '../utils';
 import { Color } from './../math/Color';
 
 export interface FogBase {
+    /**
+     * Optional name of the `Fog` object
+     * @remarks _(doesn't need to be unique)_.
+     * @defaultValue `""`
+     */
     name: string;
+
+    /**
+     * Fog color.
+     * @remarks If set to black, far away objects will be rendered black.
+     */
     color: Color;
+
+    /**
+     * Returns a new Fog instance with the same parameters as this one.
+     */
     clone(): FogBase;
+
+    /**
+     * Return Fog data in JSON format.
+     */
     toJSON(): any;
 }
 
 /**
  * This class contains the parameters that define linear fog, i.e., that grows linearly denser with the distance.
+ *  @example
+ * ```typescript
+ * const scene = new THREE.Scene();
+ * scene.fog = new THREE.Fog(0xcccccc, 10, 15);
+ * ```
+ * @see {@link https://threejs.org/docs/index.html#api/en/scenes/Fog | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/scenes/Fog.js | Source}
  */
 export class Fog implements FogBase {
+    /**
+     * The color parameter is passed to the {@link THREE.Color | Color} constructor to set the color property
+     * @remarks
+     * Color can be a hexadecimal integer or a CSS-style string.
+     * @param color
+     * @param near Expects a `Float`
+     * @param far Expects a `Float`
+     */
     constructor(color: ColorRepresentation, near?: number, far?: number);
 
     /**
-     * @default ''
+     * Read-only flag to check if a given object is of type {@link Fog}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isFog: true;
+
+    /**
+     * Optional name of the object
+     * @remarks _(doesn't need to be unique)_.
+     * @defaultValue `""`
      */
     name: string;
 
     /**
      * Fog color.
+     * @remarks If set to black, far away objects will be rendered black.
      */
     color: Color;
 
     /**
-     * The minimum distance to start applying fog. Objects that are less than 'near' units from the active camera won't be affected by fog.
-     * @default 1
+     * The minimum distance to start applying fog.
+     * @remarks Objects that are less than **near** units from the active camera won't be affected by fog.
+     * @defaultValue `1`
+     * @remarks Expects a `Float`
      */
     near: number;
 
     /**
-     * The maximum distance at which fog stops being calculated and applied. Objects that are more than 'far' units away from the active camera won't be affected by fog.
-     * @default 1000
+     * The maximum distance at which fog stops being calculated and applied.
+     * @remarks Objects that are more than **far** units away from the active camera won't be affected by fog.
+     * @defaultValue `1000`
+     * @remarks Expects a `Float`
      */
     far: number;
 
-    readonly isFog: true;
-
+    /**
+     * Returns a new {@link Fog} instance with the same parameters as this one.
+     */
     clone(): Fog;
+
+    /**
+     * Return {@link Fog} data in JSON format.
+     */
     toJSON(): any;
 }

three/src/scenes/FogExp2.d.ts

@@ -1,26 +1,61 @@
+import { ColorRepresentation } from '../utils';
 import { Color } from './../math/Color';
 import { FogBase } from './Fog';
+
 /**
- * This class contains the parameters that define linear fog, i.e., that grows exponentially denser with the distance.
+ * This class contains the parameters that define exponential squared fog, which gives a clear view near the camera and a faster than exponentially densening fog farther from the camera.
+ * @example
+ * ```typescript
+ * const scene = new THREE.Scene();
+ * scene.fog = new THREE.FogExp2(0xcccccc, 0.002);
+ * ```
+ * @see Example: {@link https://threejs.org/examples/#webgl_geometry_terrain | webgl geometry terrain}
+ * @see {@link https://threejs.org/docs/index.html#api/en/scenes/FogExp2 | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/scenes/FogExp2.js | Source}
  */
 export class FogExp2 implements FogBase {
-    constructor(hex: number | string, density?: number);
+    /**
+     * The color parameter is passed to the {@link THREE.Color | Color} constructor to set the color property
+     * @remarks Color can be a hexadecimal integer or a CSS-style string.
+     * @param color
+     * @param density Expects a `Float`
+     */
+    constructor(color: ColorRepresentation, density?: number);
+
+    /**
+     * Read-only flag to check if a given object is of type {@link FogExp2}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isFogExp2: true;
 
     /**
-     * @default ''
+     * Optional name of the object
+     * @remarks _(doesn't need to be unique)_.
+     * @defaultValue `""`
      */
     name: string;
 
+    /**
+     * Fog color.
+     * @remarks If set to black, far away objects will be rendered black.
+     */
     color: Color;
 
     /**
      * Defines how fast the fog will grow dense.
-     * @default 0.00025
+     * @defaultValue `0.00025`
+     * @remarks Expects a `Float`
      */
     density: number;
 
-    readonly isFogExp2: true;
-
+    /**
+     * Returns a new {@link FogExp2} instance with the same parameters as this one.
+     */
     clone(): FogExp2;
+
+    /**
+     * Return {@link FogExp2} data in JSON format.
+     */
     toJSON(): any;
 }