@types/three 0.148.1 → 0.150.0

three/src/core/BufferGeometry.d.ts

@@ -1,4 +1,6 @@
 import { BufferAttribute } from './BufferAttribute';
+import { InterleavedBufferAttribute } from './InterleavedBufferAttribute';
+import { GLBufferAttribute } from './GLBufferAttribute';
 import { Box3 } from './../math/Box3';
 import { Sphere } from './../math/Sphere';
 import { Matrix4 } from './../math/Matrix4';
@@ -6,190 +8,359 @@ import { Quaternion } from './../math/Quaternion';
 import { Vector2 } from './../math/Vector2';
 import { Vector3 } from './../math/Vector3';
 import { EventDispatcher } from './EventDispatcher';
-import { InterleavedBufferAttribute } from './InterleavedBufferAttribute';
 import { BuiltinShaderAttributeName } from '../constants';
+import * as BufferGeometryUtils from '../../examples/jsm/utils/BufferGeometryUtils';
 
 /**
- * This is a superefficent class for geometries because it saves all data in buffers.
- * It reduces memory costs and cpu cycles. But it is not as easy to work with because of all the necessary buffer calculations.
- * It is mainly interesting when working with static objects.
+ * A representation of mesh, line, or point geometry
+ * Includes vertex positions, face indices, normals, colors, UVs, and custom attributes within buffers, reducing the cost of passing all this data to the GPU.
+ * @remarks
+ * To read and edit data in BufferGeometry attributes, see {@link THREE.BufferAttribute | BufferAttribute} documentation.
+ * @example
+ * ```typescript
+ * const geometry = new THREE.BufferGeometry();
+ * // create a simple square shape. We duplicate the top left and bottom right
+ * // vertices because each vertex needs to appear once per triangle.
+ * const vertices = new Float32Array([
+ *         -1.0, -1.0, 1.0,
+ *          1.0, -1.0, 1.0,
+ *          1.0,  1.0, 1.0,
  *
- * see {@link https://github.com/mrdoob/three.js/blob/master/src/core/BufferGeometry.js|src/core/BufferGeometry.js}
+ *          1.0,  1.0, 1.0,
+ *         -1.0,  1.0, 1.0,
+ *         -1.0, -1.0, 1.0]);
+ * // itemSize = 3 because there are 3 values (components) per vertex
+ * geometry.setAttribute('position', new THREE.BufferAttribute(vertices, 3));
+ * const material = new THREE.MeshBasicMaterial({ color: 0xff0000 });
+ * const mesh = new THREE.Mesh(geometry, material);
+ * ```
+ * @see Example: {@link https://threejs.org/examples/#webgl_buffergeometry | Mesh with non-indexed faces}
+ * @see Example: {@link https://threejs.org/examples/#webgl_buffergeometry_indexed | Mesh with indexed faces}
+ * @see Example: {@link https://threejs.org/examples/#webgl_buffergeometry_lines | Lines}
+ * @see Example: {@link https://threejs.org/examples/#webgl_buffergeometry_lines_indexed | Indexed Lines}
+ * @see Example: {@link https://threejs.org/examples/#webgl_buffergeometry_custom_attributes_particles | Particles}
+ * @see Example: {@link https://threejs.org/examples/#webgl_buffergeometry_rawshader | Raw Shaders}
+ * @see {@link https://threejs.org/docs/index.html#api/en/core/BufferGeometry | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/core/BufferGeometry.js | Source}
  */
 export class BufferGeometry extends EventDispatcher {
     /**
-     * This creates a new BufferGeometry. It also sets several properties to an default value.
+     * This creates a new {@link THREE.BufferGeometry | BufferGeometry} object.
      */
     constructor();
 
     /**
-     * Unique number of this buffergeometry instance
+     * Unique number for this {@link THREE.BufferGeometry | BufferGeometry} instance.
+     * @remarks Expects a `Integer`
      */
     id: number;
+
+    /**
+     * {@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;
 
     /**
-     * @default ''
+     * Optional name for this {@link THREE.BufferGeometry | BufferGeometry} instance.
+     * @defaultValue `''`
      */
     name: string;
 
     /**
-     * @default 'BufferGeometry'
+     * @defaultValue `BufferGeometry`
      */
-    type: string;
+    type: string; // TODO Replace for "BufferGeometry" // TODO add readonly
 
     /**
-     * @default null
+     * Allows for vertices to be re-used across multiple triangles; this is called using "indexed triangles".
+     * Each triangle is associated with the indices of three vertices. This attribute therefore stores the index of each vertex for each triangular face.
+     * If this attribute is not set, the {@link THREE.WebGLRenderer | renderer}  assumes that each three contiguous positions represent a single triangle.
+     * @defaultValue `null`
      */
     index: BufferAttribute | null;
 
     /**
-     * @default {}
+     * This hashmap has as id the name of the attribute to be set and as value the {@link THREE.BufferAttribute | buffer} to set it to. Rather than accessing this property directly,
+     * use {@link setAttribute | .setAttribute} and {@link getAttribute | .getAttribute} to access attributes of this geometry.
+     * @defaultValue `{}`
      */
     attributes: {
-        [name: string]: BufferAttribute | InterleavedBufferAttribute;
+        [name: string]: BufferAttribute | InterleavedBufferAttribute | GLBufferAttribute; // TODO Replace for 'Record<>'
     };
 
     /**
-     * @default {}
+     * Hashmap of {@link THREE.BufferAttribute | BufferAttributes} holding details of the geometry's morph targets.
+     * @remarks
+     * Once the geometry has been rendered, the morph attribute data cannot be changed.
+     * You will have to call {@link dispose | .dispose}(), and create a new instance of {@link THREE.BufferGeometry | BufferGeometry}.
+     * @defaultValue `{}`
      */
     morphAttributes: {
-        [name: string]: Array<BufferAttribute | InterleavedBufferAttribute>;
+        [name: string]: Array<BufferAttribute | InterleavedBufferAttribute>; // TODO Replace for 'Record<>'
     };
 
     /**
-     * @default false
+     * Used to control the morph target behavior; when set to true, the morph target data is treated as relative offsets, rather than as absolute positions/normals.
+     * @defaultValue `false`
      */
     morphTargetsRelative: boolean;
 
     /**
-     * @default []
+     * Split the geometry into groups, each of which will be rendered in a separate WebGL draw call. This allows an array of materials to be used with the geometry.
+     * @remarks Every vertex and index must belong to exactly one group — groups must not share vertices or indices, and must not leave vertices or indices unused.
+     * @remarks Use {@link addGroup | .addGroup} to add groups, rather than modifying this array directly.
+     * @defaultValue `[]`
      */
-    groups: Array<{ start: number; count: number; materialIndex?: number | undefined }>;
+    groups: Array<{
+        /**
+         * Specifies the first element in this draw call – the first vertex for non-indexed geometry, otherwise the first triangle index.
+         * @remarks Expects a `Integer`
+         */
+        start: number;
+        /**
+         * Specifies how many vertices (or indices) are included.
+         * @remarks Expects a `Integer`
+         */
+        count: number;
+        /**
+         * Specifies the material array index to use.
+         * @remarks Expects a `Integer`
+         */
+        materialIndex?: number | undefined;
+    }>;
 
     /**
-     * @default null
+     * Bounding box for the bufferGeometry, 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;
 
     /**
-     * @default null
+     * Bounding sphere for the {@link THREE.BufferGeometry | BufferGeometry}, 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;
 
     /**
-     * @default { start: 0, count: Infinity }
+     * Determines the part of the geometry to render. This should not be set directly, instead use {@link setDrawRange | .setDrawRange(...)}.
+     * @remarks For non-indexed {@link THREE.BufferGeometry | BufferGeometry}, count is the number of vertices to render.
+     * @remarks For indexed {@link THREE.BufferGeometry | BufferGeometry}, count is the number of indices to render.
+     * @defaultValue `{ start: 0, count: Infinity }`
      */
     drawRange: { start: number; count: number };
 
     /**
-     * @default {}
+     * An object that can be used to store custom data about the BufferGeometry. It should not hold references to functions as these will not be cloned.
+     * @defaultValue `{}`
      */
     userData: { [key: string]: any };
+
+    /**
+     * Read-only flag to check if a given object is of type {@link BufferGeometry}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
     readonly isBufferGeometry: true;
 
+    /**
+     * Return the {@link index | .index} buffer.
+     */
     getIndex(): BufferAttribute | null;
-    setIndex(index: BufferAttribute | number[] | null): BufferGeometry;
 
+    /**
+     * Set the {@link THREE.BufferGeometry.index | .index} buffer.
+     * @param index
+     */
+    setIndex(index: BufferAttribute | number[] | null): this;
+
+    /**
+     * Sets an {@link attributes | attribute} to this geometry with the specified name.
+     * @remarks
+     * Use this rather than the attributes property, because an internal hashmap of {@link attributes | .attributes} is maintained to speed up iterating over attributes.
+     * @param name
+     * @param attribute
+     */
     setAttribute(
         name: BuiltinShaderAttributeName | (string & {}),
-        attribute: BufferAttribute | InterleavedBufferAttribute,
-    ): BufferGeometry;
-    getAttribute(name: BuiltinShaderAttributeName | (string & {})): BufferAttribute | InterleavedBufferAttribute;
+        attribute: BufferAttribute | InterleavedBufferAttribute | GLBufferAttribute,
+    ): this;
+
+    /**
+     * Returns the {@link attributes | attribute} with the specified name.
+     * @param name
+     */
+    getAttribute(
+        name: BuiltinShaderAttributeName | (string & {}),
+    ): BufferAttribute | InterleavedBufferAttribute | GLBufferAttribute;
+
+    /**
+     * Deletes the  {@link attributes | attribute} with the specified name.
+     * @param name
+     */
     deleteAttribute(name: BuiltinShaderAttributeName | (string & {})): BufferGeometry;
+
+    /**
+     * Returns true if the {@link attributes | attribute} with the specified name exists.
+     * @param name
+     */
     hasAttribute(name: BuiltinShaderAttributeName | (string & {})): boolean;
 
+    /**
+     * Adds a group to this geometry
+     * @see the {@link BufferGeometry.groups | groups} property for details.
+     * @param start
+     * @param count
+     * @param materialIndex
+     */
     addGroup(start: number, count: number, materialIndex?: number): void;
+
+    /**
+     * Clears all groups.
+     */
     clearGroups(): void;
 
+    /**
+     * Set the {@link drawRange | .drawRange} property
+     * @remarks For non-indexed BufferGeometry, count is the number of vertices to render
+     * @remarks For indexed BufferGeometry, count is the number of indices to render.
+     * @param start
+     * @param count is the number of vertices or indices to render. Expects a `Integer`
+     */
     setDrawRange(start: number, count: number): void;
 
     /**
-     * Bakes matrix transform directly into vertex coordinates.
+     * Applies the matrix transform to the geometry.
+     * @param matrix
      */
-    applyMatrix4(matrix: Matrix4): BufferGeometry;
-    applyQuaternion(q: Quaternion): BufferGeometry;
+    applyMatrix4(matrix: Matrix4): this;
 
-    rotateX(angle: number): BufferGeometry;
-    rotateY(angle: number): BufferGeometry;
-    rotateZ(angle: number): BufferGeometry;
-    translate(x: number, y: number, z: number): BufferGeometry;
-    scale(x: number, y: number, z: number): BufferGeometry;
-    lookAt(v: Vector3): void;
+    /**
+     * Applies the rotation represented by the quaternion to the geometry.
+     * @param quaternion
+     */
+    applyQuaternion(quaternion: Quaternion): this;
 
-    center(): BufferGeometry;
+    /**
+     * Rotate the geometry about the X axis. This is typically done as a one time operation, and not during a loop.
+     * @remarks Use {@link THREE.Object3D.rotation | Object3D.rotation} for typical real-time mesh rotation.
+     * @param angle radians. Expects a `Float`
+     */
+    rotateX(angle: number): this;
 
-    setFromPoints(points: Vector3[] | Vector2[]): BufferGeometry;
+    /**
+     * Rotate the geometry about the Y axis.
+     * @remarks This is typically done as a one time operation, and not during a loop.
+     * @remarks Use {@link THREE.Object3D.rotation | Object3D.rotation} for typical real-time mesh rotation.
+     * @param angle radians. Expects a `Float`
+     */
+    rotateY(angle: number): this;
 
     /**
-     * Computes bounding box of the geometry, updating Geometry.boundingBox attribute.
-     * Bounding boxes aren't computed by default. They need to be explicitly computed, otherwise they are null.
+     * Rotate the geometry about the Z axis.
+     * @remarks This is typically done as a one time operation, and not during a loop.
+     * @remarks Use {@link THREE.Object3D.rotation | Object3D.rotation} for typical real-time mesh rotation.
+     * @param angle radians. Expects a `Float`
      */
-    computeBoundingBox(): void;
+    rotateZ(angle: number): this;
 
     /**
-     * Computes bounding sphere of the geometry, updating Geometry.boundingSphere attribute.
-     * Bounding spheres aren't' computed by default. They need to be explicitly computed, otherwise they are null.
+     * Translate the geometry.
+     * @remarks This is typically done as a one time operation, and not during a loop.
+     * @remarks Use {@link THREE.Object3D.position | Object3D.position} for typical real-time mesh rotation.
+     * @param x Expects a `Float`
+     * @param y Expects a `Float`
+     * @param z Expects a `Float`
      */
-    computeBoundingSphere(): void;
+    translate(x: number, y: number, z: number): this;
 
     /**
-     * Computes and adds tangent attribute to this geometry.
+     * Scale the geometry data.
+     * @remarks This is typically done as a one time operation, and not during a loop.
+     * @remarks Use {@link THREE.Object3D.scale | Object3D.scale} for typical real-time mesh scaling.
+     * @param x Expects a `Float`
+     * @param y Expects a `Float`
+     * @param z Expects a `Float`
      */
-    computeTangents(): void;
+    scale(x: number, y: number, z: number): this;
 
     /**
-     * Computes vertex normals by averaging face normals.
+     * Rotates the geometry to face a point in space.
+     * @remarks This is typically done as a one time operation, and not during a loop.
+     * @remarks Use {@link THREE.Object3D.lookAt | Object3D.lookAt} for typical real-time mesh usage.
+     * @param vector A world vector to look at.
      */
-    computeVertexNormals(): void;
+    lookAt(vector: Vector3): this;
 
-    normalizeNormals(): void;
+    /**
+     * Center the geometry based on the bounding box.
+     */
+    center(): this;
 
-    toNonIndexed(): BufferGeometry;
+    /**
+     * Sets the attributes for this BufferGeometry from an array of points.
+     * @param points
+     */
+    setFromPoints(points: Vector3[] | Vector2[]): this;
 
-    toJSON(): any;
-    clone(): BufferGeometry;
-    copy(source: BufferGeometry): this;
+    /**
+     * Computes bounding box of the geometry, 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;
 
     /**
-     * Disposes the object from memory.
-     * You need to call this when you want the bufferGeometry removed while the application is running.
+     * Computes bounding sphere of the geometry, updating {@link boundingSphere | .boundingSphere} attribute.
+     * @remarks bounding spheres aren't computed by default. They need to be explicitly computed, otherwise they are `null`.
      */
-    dispose(): void;
+    computeBoundingSphere(): void;
+
+    /**
+     * Calculates and adds a tangent attribute to this geometry.
+     * The computation is only supported for indexed geometries and if position, normal, and uv attributes are defined
+     * @remarks
+     * When using a tangent space normal map, prefer the MikkTSpace algorithm provided by
+     * {@link BufferGeometryUtils.computeMikkTSpaceTangents} instead.
+     */
+    computeTangents(): void;
 
     /**
-     * @deprecated Use {@link BufferGeometry#groups .groups} instead.
+     * Computes vertex normals by averaging face normals.
      */
-    drawcalls: any;
+    computeVertexNormals(): void;
 
     /**
-     * @deprecated Use {@link BufferGeometry#groups .groups} instead.
+     * Every normal vector in a geometry will have a magnitude of 1
+     * @remarks This will correct lighting on the geometry surfaces.
      */
-    offsets: any;
+    normalizeNormals(): void;
 
     /**
-     * @deprecated Use {@link BufferGeometry#setIndex .setIndex()} instead.
+     * Return a non-index version of an indexed BufferGeometry.
      */
-    addIndex(index: any): void;
+    toNonIndexed(): BufferGeometry;
 
     /**
-     * @deprecated Use {@link BufferGeometry#addGroup .addGroup()} instead.
+     * Convert the buffer geometry to three.js {@link https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4 | JSON Object/Scene format}.
      */
-    addDrawCall(start: any, count: any, indexOffset?: any): void;
+    toJSON(): {};
 
     /**
-     * @deprecated Use {@link BufferGeometry#clearGroups .clearGroups()} instead.
+     * Creates a clone of this BufferGeometry
      */
-    clearDrawCalls(): void;
+    clone(): BufferGeometry;
 
     /**
-     * @deprecated Use {@link BufferGeometry#setAttribute .setAttribute()} instead.
+     * Copies another BufferGeometry to this BufferGeometry.
+     * @param source
      */
-    addAttribute(name: string, attribute: BufferAttribute | InterleavedBufferAttribute): BufferGeometry;
-    addAttribute(name: any, array: any, itemSize: any): any;
+    copy(source: BufferGeometry): this;
 
     /**
-     * @deprecated Use {@link BufferGeometry#deleteAttribute .deleteAttribute()} instead.
+     * Frees the GPU-related resources allocated by this instance.
+     * @remarks Call this method whenever this instance is no longer used in your app.
      */
-    removeAttribute(name: string): BufferGeometry;
+    dispose(): void;
 }

three/src/core/Clock.d.ts

@@ -1,64 +1,72 @@
 /**
- * Object for keeping track of time.
- *
- * see {@link https://github.com/mrdoob/three.js/blob/master/src/core/Clock.js|src/core/Clock.js}
+ * Object for keeping track of time
+ * @remarks
+ * This uses {@link https://developer.mozilla.org/en-US/docs/Web/API/Performance/now | performance.now} if it is available,
+ * otherwise it reverts to the less accurate {@link https://developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/Date/now | Date.now}.
+ * @see {@link https://threejs.org/docs/index.html#api/en/core/Clock | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/core/Clock.js | Source}
  */
 export class Clock {
     /**
-     * @param [autoStart=true] Automatically start the clock.
+     * Create a new instance of {@link THREE.Clock | Clock}
+     * @param autoStart - Whether to automatically start the clock when {@link getDelta | .getDelta()} is called for the first time. Default `true`
      */
     constructor(autoStart?: boolean);
 
     /**
-     * If set, starts the clock automatically when the first update is called.
-     * @default true
+     * If set, starts the clock automatically when {@link getDelta | .getDelta()} is called for the first time.
+     * @defaultValue `true`
      */
     autoStart: boolean;
 
     /**
-     * When the clock is running, It holds the starttime of the clock.
-     * This counted from the number of milliseconds elapsed since 1 January 1970 00:00:00 UTC.
-     * @default 0
+     * Holds the time at which the clock's {@link start | .start()} method was last called.
+     * @defaultValue `0`
      */
     startTime: number;
 
     /**
-     * When the clock is running, It holds the previous time from a update.
-     * This counted from the number of milliseconds elapsed since 1 January 1970 00:00:00 UTC.
-     * @default 0
+     * Holds the time at which the clock's {@link start | .start()}, {@link getElapsedTime | .getElapsedTime()} or {@link getDelta | .getDelta()} methods were last called.
+     * @defaultValue `0`
      */
     oldTime: number;
 
     /**
-     * When the clock is running, It holds the time elapsed between the start of the clock to the previous update.
-     * This parameter is in seconds of three decimal places.
-     * @default 0
+     * Keeps track of the total time that the clock has been running.
+     * @defaultValue `0`
      */
     elapsedTime: number;
 
     /**
-     * This property keeps track whether the clock is running or not.
-     * @default false
+     * Whether the clock is running or not.
+     * @defaultValue `false`
      */
     running: boolean;
 
     /**
      * Starts clock.
+     * @remarks
+     * Also sets the {@link startTime | .startTime} and {@link oldTime | .oldTime} to the current time,
+     * sets {@link elapsedTime | .elapsedTime} to `0` and {@link running | .running} to `true`.
      */
     start(): void;
 
     /**
-     * Stops clock.
+     * Stops clock and sets {@link oldTime | oldTime} to the current time.
      */
     stop(): void;
 
     /**
-     * Get the seconds passed since the clock started.
+     * Get the seconds passed since the clock started and sets {@link oldTime | .oldTime} to the current time.
+     * @remarks
+     * If {@link autoStart | .autoStart} is `true` and the clock is not running, also starts the clock.
      */
     getElapsedTime(): number;
 
     /**
-     * Get the seconds passed since the last call to this method.
+     * Get the seconds passed since the time {@link oldTime | .oldTime} was set and sets {@link oldTime | .oldTime} to the current time.
+     * @remarks
+     * If {@link autoStart | .autoStart} is `true` and the clock is not running, also starts the clock.
      */
     getDelta(): number;
 }

three/src/core/EventDispatcher.d.ts

@@ -13,12 +13,28 @@ export type EventListener<E, T, U> = (event: E & { type: T } & { target: U }) =>
 
 /**
  * JavaScript events for custom objects
- *
- * @source src/core/EventDispatcher.js
+ * @example
+ * ```typescript
+ * // Adding events to a custom object
+ * class Car extends EventDispatcher {
+ *   start() {
+ *     this.dispatchEvent( { type: 'start', message: 'vroom vroom!' } );
+ *   }
+ * };
+ * // Using events with the custom object
+ * const car = new Car();
+ * car.addEventListener( 'start', ( event ) => {
+ *   alert( event.message );
+ * } );
+ * car.start();
+ * ```
+ * @see {@link https://github.com/mrdoob/eventdispatcher.js | mrdoob EventDispatcher on GitHub}
+ * @see {@link https://threejs.org/docs/index.html#api/en/core/EventDispatcher | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/core/EventDispatcher.js | Source}
  */
 export class EventDispatcher<E extends BaseEvent = Event> {
     /**
-     * Creates eventDispatcher object. It needs to be call with '.call' to add the functionality to an object.
+     * Creates {@link THREE.EventDispatcher | EventDispatcher} object.
      */
     constructor();
 
@@ -45,7 +61,7 @@ export class EventDispatcher<E extends BaseEvent = Event> {
 
     /**
      * Fire an event type.
-     * @param type The type of event that gets fired.
+     * @param event The event that gets fired.
      */
     dispatchEvent(event: E): void;
 }