@types/three 0.149.0 → 0.150.0

three/src/core/GLBufferAttribute.d.ts

@@ -1,27 +1,121 @@
 /**
- * see {@link https://github.com/mrdoob/three.js/blob/master/src/core/GLBufferAttribute.js|src/core/GLBufferAttribute.js}
+ * This buffer attribute class does not construct a VBO.
+ * Instead, it uses whatever VBO is passed in constructor and can later be altered via the {@link buffer | .buffer} property.
+ * @remarks
+ * It is required to pass additional params alongside the VBO
+ * Those are: the GL context, the GL data type, the number of components per vertex, the number of bytes per component, and the number of vertices.
+ * @remarks
+ * The most common use case for this class is when some kind of GPGPU calculation interferes or even produces the VBOs in question.
+ * @see Example: {@link https://threejs.org/examples/#webgl_buffergeometry_glbufferattribute | WebGL / buffergeometry / glbufferattribute}
+ * @see {@link https://threejs.org/docs/index.html#api/en/core/GLBufferAttribute | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/core/GLBufferAttribute.js | Source}
  */
-
 export class GLBufferAttribute {
-    constructor(buffer: WebGLBuffer, type: number, itemSize: number, elementSize: 1 | 2 | 4, count: number);
+    /**
+     * This creates a new GLBufferAttribute object.
+     * @param buffer Must be a {@link https://developer.mozilla.org/en-US/docs/Web/API/WebGLBuffer | WebGLBuffer}. See {@link GLBufferAttribute.buffer | .buffer}
+     * @param type One of {@link https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/Constants#Data_types | WebGL Data Types}. See {@link GLBufferAttribute.type | .type}
+     * @param itemSize How many values make up each item (vertex). See {@link GLBufferAttribute.itemSize | .itemSize}
+     * @param elementSize `1`, `2` or `4`. The corresponding size (in bytes) for the given {@link type} param. See {@link GLBufferAttribute.elementSize | .elementSize}
+     * @param count The expected number of vertices in VBO. See {@link GLBufferAttribute.count | .count}
+     */
+    constructor(buffer: WebGLBuffer, type: GLenum, itemSize: number, elementSize: 1 | 2 | 4, count: number);
+
+    /**
+     * Read-only flag to check if a given object is of type {@link GLBufferAttribute}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isGLBufferAttribute: true;
 
     /**
-     * @default ''
+     * Optional name for this attribute instance.
+     * @defaultValue `""`
      */
     name: string;
+
+    /**
+     * The current {@link https://developer.mozilla.org/en-US/docs/Web/API/WebGLBuffer | WebGLBuffer} instance.
+     */
     buffer: WebGLBuffer;
-    type: number;
+
+    /**
+     * A {@link https://developer.mozilla.org/en-US/docs/Web/API/WebGL_API/Constants#Data_types | WebGL Data Type} describing the underlying VBO contents.
+     *
+     * #### WebGL Data Type (`GLenum`)
+     * - gl.BYTE: 0x1400
+     * - gl.UNSIGNED_BYTE: 0x1401
+     * - gl.SHORT: 0x1402
+     * - gl.UNSIGNED_SHORT: 0x1403
+     * - gl.INT: 0x1404
+     * - gl.UNSIGNED_INT: 0x1405
+     * - gl.FLOAT: 0x1406
+     * @remarks Set this property together with {@link elementSize | .elementSize}. The recommended way is using the {@link setType | .setType()} method.
+     * @remarks Expects a `DataType` `GLenum` _possible values:_ `0x1400` `0x1401` `0x1402` `0x1403` `0x1404` `0x1405` `0x1406`
+     */
+    type: GLenum;
+
+    /**
+     * How many values make up each item (vertex).
+     * @remarks The number of values of the array that should be associated with a particular vertex.
+     * For instance, if this attribute is storing a 3-component vector (such as a position, normal, or color), then itemSize should be 3.
+     * @remarks Expects a `Integer`
+     */
     itemSize: number;
+
+    /**
+     * Stores the corresponding size in bytes for the current {@link type | .type} property value.
+     *
+     * The corresponding size (_in bytes_) for the given "type" param.
+     * #### WebGL Data Type (`GLenum`)
+     * - gl.BYTE: 1
+     * - gl.UNSIGNED_BYTE: 1
+     * - gl.SHORT: 2
+     * - gl.UNSIGNED_SHORT: 2
+     * - gl.INT: 4
+     * - gl.UNSIGNED_INT: 4
+     * - gl.FLOAT: 4
+     * @remarks Set this property together with {@link type | .type}. The recommended way is using the {@link setType | .setType} method.
+     * @see `constructor`` for a list of known type sizes.
+     * @remarks Expects a `1`, `2` or `4`
+     */
     elementSize: 1 | 2 | 4;
+
+    /**
+     * The expected number of vertices in VBO.
+     * @remarks Expects a `Integer`
+     */
     count: number;
-    version: number;
 
-    readonly isGLBufferAttribute: true;
+    /**
+     * A version number, incremented every time the needsUpdate property is set to true.
+     * @remarks Expects a `Integer`
+     */
+    version: number;
 
+    /**
+     * Setting this to true increments {@link version | .version}.
+     * @remarks _set-only property_.
+     */
     set needsUpdate(value: boolean);
 
+    /**
+     * Sets the {@link buffer | .buffer} property.
+     */
     setBuffer(buffer: WebGLBuffer): this;
-    setType(type: number, elementSize: 1 | 2 | 4): this;
+
+    /**
+     * Sets the both {@link GLBufferAttribute.type | type} and {@link GLBufferAttribute.elementSize | elementSize} properties.
+     */
+    setType(type: GLenum, elementSize: 1 | 2 | 4): this;
+
+    /**
+     * Sets the {@link GLBufferAttribute.itemSize | itemSize} property.
+     */
     setItemSize(itemSize: number): this;
+
+    /**
+     * Sets the {@link GLBufferAttribute.count | count} property.
+     */
     setCount(count: number): this;
 }

three/src/core/InstancedBufferAttribute.d.ts

@@ -2,36 +2,25 @@ import { BufferGeometry } from './BufferGeometry';
 import { BufferAttribute } from './BufferAttribute';
 
 /**
- * see {@link https://github.com/mrdoob/three.js/blob/master/examples/jsm/utils/BufferGeometryUtils.js|examples/jsm/utils/BufferGeometryUtils.js}
+ * An instanced version of {@link THREE.InstancedBufferAttributeBufferAttribute | BufferAttribute}.
+ * @see {@link https://threejs.org/docs/index.html#api/en/core/InstancedBufferAttribute | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/core/InstancedBufferAttribute.js | Source}
  */
-export namespace BufferGeometryUtils {
-    function mergeBufferGeometries(geometries: BufferGeometry[]): BufferGeometry;
-    function computeTangents(geometry: BufferGeometry): null;
-    function mergeBufferAttributes(attributes: BufferAttribute[]): BufferAttribute;
-}
-
-/**
- * @deprecated
- */
-export namespace GeometryUtils {
-    /**
-     * @deprecated Use {@link Geometry#merge geometry.merge( geometry2, matrix, materialIndexOffset )} instead.
-     */
-    function merge(geometry1: any, geometry2: any, materialIndexOffset?: any): any;
+export class InstancedBufferAttribute extends BufferAttribute {
     /**
-     * @deprecated Use {@link Geometry#center geometry.center()} instead.
+     * Create a new instance of {@link THREE.InstancedBufferAttribute | InstancedBufferAttribute}
+     * @param array
+     * @param itemSize
+     * @param normalized
+     * @param meshPerAttribute
      */
-    function center(geometry: any): any;
-}
-
-/**
- * see {@link https://github.com/mrdoob/three.js/blob/master/src/core/InstancedBufferAttribute.js|src/core/InstancedBufferAttribute.js}
- */
-export class InstancedBufferAttribute extends BufferAttribute {
     constructor(array: ArrayLike<number>, itemSize: number, normalized?: boolean, meshPerAttribute?: number);
 
     /**
-     * @default 1
+     * Defines how often a value of this buffer attribute should be repeated.
+     * A value of one means that each value of the instanced attribute is used for a single instance.
+     * A value of two means that each value is used for two consecutive instances (and so on).
+     * @defaultValue `1`
      */
     meshPerAttribute: number;
 }

three/src/core/InstancedBufferGeometry.d.ts

@@ -1,20 +1,38 @@
 import { BufferGeometry } from './BufferGeometry';
 
 /**
- * see {@link https://github.com/mrdoob/three.js/blob/master/src/core/InstancedBufferGeometry.js|src/core/InstancedBufferGeometry.js}
+ * An instanced version of {@link THREE.BufferGeometry | BufferGeometry}.
+ * @see {@link https://threejs.org/docs/index.html#api/en/core/InstancedBufferGeometry | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/core/InstancedBufferGeometry.js | Source}
  */
 export class InstancedBufferGeometry extends BufferGeometry {
+    /**
+     * Create a new instance of {@link InstancedBufferGeometry}
+     */
     constructor();
 
     /**
-     * @default 'InstancedBufferGeometry
+     * @defaultValue `InstancedBufferGeometry`
      */
     type: string;
 
-    isInstancedBufferGeometry: boolean;
+    /**
+     * Read-only flag to check if a given object is of type {@link InstancedBufferGeometry}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isInstancedBufferGeometry: true;
 
     /**
-     * @default Infinity
+     *
+     * @defaultValue `Infinity`
      */
     instanceCount: number;
+
+    /**
+     * Copies the given {@link InstancedBufferGeometry} to this instance.
+     * @param source
+     * @override
+     */
+    copy(source: InstancedBufferGeometry): this;
 }

three/src/core/InstancedInterleavedBuffer.d.ts

@@ -1,13 +1,21 @@
 import { InterleavedBuffer } from './InterleavedBuffer';
 
 /**
- * see {@link https://github.com/mrdoob/three.js/blob/master/src/core/InstancedInterleavedBuffer.js|src/core/InstancedInterleavedBuffer.js}
+ * An instanced version of {@link THREE.InterleavedBuffer | InterleavedBuffer}.
+ * @see {@link https://threejs.org/docs/index.html#api/en/core/InstancedInterleavedBuffer | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/core/InstancedInterleavedBuffer.js | Source}
  */
 export class InstancedInterleavedBuffer extends InterleavedBuffer {
+    /**
+     * Create a new instance of {@link InstancedInterleavedBuffer}
+     * @param array
+     * @param itemSize
+     * @param meshPerAttribute
+     */
     constructor(array: ArrayLike<number>, stride: number, meshPerAttribute?: number);
 
     /**
-     * @default 1
+     * @defaultValue `1`
      */
     meshPerAttribute: number;
 }

three/src/core/InterleavedBuffer.d.ts

@@ -2,44 +2,128 @@ import { InterleavedBufferAttribute } from './InterleavedBufferAttribute';
 import { Usage } from '../constants';
 
 /**
- * see {@link https://github.com/mrdoob/three.js/blob/master/src/core/InterleavedBuffer.js|src/core/InterleavedBuffer.js}
+ * **"Interleaved"** means that multiple attributes, possibly of different types, (e.g., _position, normal, uv, color_) are packed into a single array buffer.
+ * An introduction into interleaved arrays can be found here: {@link https://blog.tojicode.com/2011/05/interleaved-array-basics.html | Interleaved array basics}
+ * @see Example: {@link https://threejs.org/examples/#webgl_buffergeometry_points_interleaved | webgl / buffergeometry / points / interleaved}
+ * @see {@link https://threejs.org/docs/index.html#api/en/core/InterleavedBuffer | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/core/InterleavedBuffer.js | Source}
  */
 export class InterleavedBuffer {
+    /**
+     * Create a new instance of {@link InterleavedBuffer}
+     * @param array A {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray | TypedArray} with a shared buffer. Stores the geometry data.
+     * @param stride The number of typed-array elements per vertex. Expects a `Integer`
+     */
     constructor(array: ArrayLike<number>, stride: number);
 
+    /**
+     * A {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray | TypedArray} with a shared buffer. Stores the geometry data.
+     */
     array: ArrayLike<number>;
+
+    /**
+     * The number of {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray | TypedArray} elements per vertex.
+     * @remarks Expects a `Integer`
+     */
     stride: number;
 
     /**
-     * @default THREE.StaticDrawUsage
+     * Defines the intended usage pattern of the data store for optimization purposes.
+     * Corresponds to the {@link BufferAttribute.usage | usage} parameter of
+     * {@link https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/bufferData | WebGLRenderingContext.bufferData}.
+     * @remarks
+     * After the initial use of a buffer, its usage cannot be changed. Instead, instantiate a new one and set the desired usage before the next render.
+     * @see {@link https://threejs.org/docs/index.html#api/en/constants/BufferAttributeUsage | Buffer Attribute Usage Constants} for all possible values.
+     * @see {@link BufferAttribute.setUsage | setUsage}
+     * @defaultValue {@link THREE.StaticDrawUsage | THREE.StaticDrawUsage}.
      */
     usage: Usage;
 
     /**
-     * @default { offset: number; count: number }
+     * Object containing offset and count.
+     * @defaultValue `{ offset: number = 0; count: number = -1 }`
      */
-    updateRange: { offset: number; count: number };
+    updateRange: {
+        /** @defaultValue `0` */
+        offset: number;
+        /** @defaultValue `-1` */
+        count: number;
+    };
 
     /**
-     * @default 0
+     * A version number, incremented every time the {@link BufferAttribute.needsUpdate | needsUpdate} property is set to true.
+     * @remarks Expects a `Integer`
+     * @defaultValue `0`
      */
     version: number;
 
-    length: number;
-
     /**
-     * @default 0
+     * Gives the total number of elements in the array.
+     * @remarks Expects a `Integer`
+     * @defaultValue 0
      */
     count: number;
-    needsUpdate: boolean;
+
+    /**
+     * Flag to indicate that this attribute has changed and should be re-sent to the GPU.
+     * Set this to true when you modify the value of the array.
+     * @remarks Setting this to true also increments the {@link BufferAttribute.version | version}.
+     * @remarks _set-only property_.
+     */
+    set needsUpdate(value: boolean);
+
+    /**
+     * {@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;
 
-    setUsage(usage: Usage): InterleavedBuffer;
-    clone(data: object): InterleavedBuffer;
+    /**
+     * Calls {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypedArray/set | TypedArray.set}( {@link value}, {@link offset} )
+     * on the {@link BufferAttribute.array | array}.
+     * @param value The source `TypedArray`.
+     * @param offset index of the {@link BufferAttribute.array | array} at which to start copying. Expects a `Integer`. Default `0`.
+     * @throws `RangeError` When {@link offset} is negative or is too large.
+     */
+    set(value: ArrayLike<number>, offset: number): this;
+
+    /**
+     * Set {@link BufferAttribute.usage | usage}
+     * @remarks
+     * After the initial use of a buffer, its usage cannot be changed. Instead, instantiate a new one and set the desired usage before the next render.
+     * @see {@link https://threejs.org/docs/index.html#api/en/constants/BufferAttributeUsage | Buffer Attribute Usage Constants} for all possible values.
+     * @see {@link BufferAttribute.usage | usage}
+     * @param value Corresponds to the {@link BufferAttribute.usage | usage} parameter of
+     * {@link https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/bufferData | WebGLRenderingContext.bufferData}.
+     */
+    setUsage(value: Usage): this;
+
+    /**
+     * Copies another {@link InterleavedBuffer} to this {@link InterleavedBuffer} instance.
+     * @param source
+     */
     copy(source: InterleavedBuffer): this;
-    copyAt(index1: number, attribute: InterleavedBufferAttribute, index2: number): InterleavedBuffer;
-    set(value: ArrayLike<number>, index: number): InterleavedBuffer;
-    toJSON(data: object): {
+
+    /**
+     * Copies data from {@link attribute}[{@link index2}] to {@link InterleavedBuffer.array | array}[{@link index1}].
+     * @param index1 Expects a `Integer`
+     * @param attribute
+     * @param index2 Expects a `Integer`
+     */
+    copyAt(index1: number, attribute: InterleavedBufferAttribute, index2: number): this;
+
+    /**
+     * Creates a clone of this {@link InterleavedBuffer}.
+     * @param data This object holds shared array buffers required for properly cloning geometries with interleaved attributes.
+     */
+    clone(data: {}): InterleavedBuffer;
+
+    /**
+     * Serializes this {@link InterleavedBuffer}.
+     * Converting to {@link https://github.com/mrdoob/three.js/wiki/JSON-Geometry-format-4 | JSON Geometry format v4},
+     * @param data This object holds shared array buffers required for properly serializing geometries with interleaved attributes.
+     */
+    toJSON(data: {}): {
         uuid: string;
         buffer: string;
         type: string;

three/src/core/InterleavedBufferAttribute.d.ts

@@ -2,51 +2,190 @@ import { BufferAttribute } from './BufferAttribute';
 import { InterleavedBuffer } from './InterleavedBuffer';
 import { Matrix4 } from './../math/Matrix4';
 import { Matrix } from './../math/Matrix3';
+
 /**
- * see {@link https://github.com/mrdoob/three.js/blob/master/src/core/InterleavedBufferAttribute.js|src/core/InterleavedBufferAttribute.js}
+ * @see {@link https://threejs.org/docs/index.html#api/en/core/InterleavedBufferAttribute | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/core/InterleavedBufferAttribute.js | Source}
  */
 export class InterleavedBufferAttribute {
+    /**
+     * Create a new instance of {@link THREE.InterleavedBufferAttribute | InterleavedBufferAttribute}.
+     * @param interleavedBuffer
+     * @param itemSize
+     * @param offset
+     * @param normalized Default `false`.
+     */
     constructor(interleavedBuffer: InterleavedBuffer, itemSize: number, offset: number, normalized?: boolean);
 
     /**
-     * @default ''
+     * Optional name for this attribute instance.
+     * @defaultValue `''`
      */
     name: string;
+
+    /**
+     * The {@link InterleavedBuffer | InterleavedBuffer} instance passed in the constructor.
+     */
     data: InterleavedBuffer;
+
+    /**
+     * How many values make up each item.
+     * @remarks Expects a `Integer`
+     */
     itemSize: number;
+
+    /**
+     * The offset in the underlying array buffer where an item starts.
+     * @remarks Expects a `Integer`
+     */
     offset: number;
 
     /**
-     * @default false
+     * @defaultValue `false`
      */
     normalized: boolean;
 
+    /**
+     * The value of {@link data | .data}.{@link InterleavedBuffer.count | count}.
+     * If the buffer is storing a 3-component item (such as a _position, normal, or color_), then this will count the number of such items stored.
+     * @remarks _get-only property_.
+     * @remarks Expects a `Integer`
+     */
     get count(): number;
+
+    /**
+     * The value of {@link InterleavedBufferAttribute.data | data}.{@link InterleavedBuffer.array | array}.
+     * @remarks _get-only property_.
+     */
     get array(): ArrayLike<number>;
+
+    /**
+     * Flag to indicate that the {@link data | .data} ({@link InterleavedBuffer}) attribute has changed and should be re-sent to the GPU.
+     * @remarks Setting this to have the same result of setting true also increments the {@link InterleavedBuffer.needsUpdate | InterleavedBuffer.needsUpdate} of {@link data | .data}.
+     * @remarks Setting this to true also increments the {@link InterleavedBuffer.version | InterleavedBuffer.version}.
+     * @remarks _set-only property_.
+     */
     set needsUpdate(value: boolean);
 
+    /**
+     * Read-only flag to check if a given object is of type {@link InterleavedBufferAttribute}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
     readonly isInterleavedBufferAttribute: true;
 
+    /**
+     * Applies matrix {@link Matrix4 | m} to every Vector3 element of this InterleavedBufferAttribute.
+     * @param m
+     */
     applyMatrix4(m: Matrix4): this;
-    clone(data?: object): BufferAttribute;
+
+    /**
+     * Applies normal matrix {@link Matrix3 | m} to every Vector3 element of this InterleavedBufferAttribute.
+     * @param m
+     */
+    applyNormalMatrix(matrix: Matrix): this;
+
+    /**
+     * Applies matrix {@link Matrix4 | m} to every Vector3 element of this InterleavedBufferAttribute, interpreting the elements as a direction vectors.
+     * @param m
+     */
+    transformDirection(matrix: Matrix): this;
+
+    /**
+     * Returns the x component of the item at the given index.
+     * @param index Expects a `Integer`
+     */
     getX(index: number): number;
+
+    /**
+     * Sets the x component of the item at the given index.
+     * @param index Expects a `Integer`
+     * @param x Expects a `Float`
+     */
     setX(index: number, x: number): this;
+
+    /**
+     * Returns the y component of the item at the given index.
+     * @param index Expects a `Integer`
+     */
     getY(index: number): number;
+
+    /**
+     * Sets the y component of the item at the given index.
+     * @param index Expects a `Integer`
+     * @param y Expects a `Float`
+     */
     setY(index: number, y: number): this;
+
+    /**
+     * Returns the z component of the item at the given index.
+     * @param index Expects a `Integer`
+     */
     getZ(index: number): number;
+
+    /**
+     * Sets the z component of the item at the given index.
+     * @param index Expects a `Integer`
+     * @param z Expects a `Float`
+     */
     setZ(index: number, z: number): this;
+
+    /**
+     * Returns the w component of the item at the given index.
+     * @param index Expects a `Integer`
+     */
     getW(index: number): number;
+
+    /**
+     * Sets the w component of the item at the given index.
+     * @param index Expects a `Integer`
+     * @param w Expects a `Float`
+     */
     setW(index: number, z: number): this;
+
+    /**
+     * Sets the x and y components of the item at the given index.
+     * @param index Expects a `Integer`
+     * @param x Expects a `Float`
+     * @param y Expects a `Float`
+     */
     setXY(index: number, x: number, y: number): this;
+    /**
+     * Sets the x, y and z components of the item at the given index.
+     * @param index Expects a `Integer`
+     * @param x Expects a `Float`
+     * @param y Expects a `Float`
+     * @param z Expects a `Float`
+     */
     setXYZ(index: number, x: number, y: number, z: number): this;
+
+    /**
+     * Sets the x, y, z and w components of the item at the given index.
+     * @param index Expects a `Integer`
+     * @param x Expects a `Float`
+     * @param y Expects a `Float`
+     * @param z Expects a `Float`
+     * @param w Expects a `Float`
+     */
     setXYZW(index: number, x: number, y: number, z: number, w: number): this;
-    toJSON(data?: object): {
+
+    /**
+     * Creates a clone of this {@link InterleavedBufferAttribute}.
+     * @param data This object holds shared array buffers required for properly cloning geometries with interleaved attributes.
+     */
+    clone(data?: {}): BufferAttribute;
+
+    /**
+     * Serializes this {@link InterleavedBufferAttribute}.
+     * Converting to {@link https://github.com/mrdoob/three.js/wiki/JSON-Geometry-format-4 | JSON Geometry format v4},
+     * @param data This object holds shared array buffers required for properly serializing geometries with interleaved attributes.
+     */
+    toJSON(data?: {}): {
         isInterleavedBufferAttribute: true;
         itemSize: number;
         data: string;
         offset: number;
         normalized: boolean;
     };
-    applyNormalMatrix(matrix: Matrix): this;
-    transformDirection(matrix: Matrix): this;
 }

three/src/core/Layers.d.ts

@@ -1,17 +1,72 @@
+/**
+ * A {@link THREE.Layers | Layers} object assigns an {@link THREE.Object3D | Object3D} to 1 or more of 32 layers numbered `0` to `31` - internally the
+ * layers are stored as a {@link https://en.wikipedia.org/wiki/Mask_(computing) | bit mask}, and
+ * by default all Object3Ds are a member of layer `0`.
+ * @remarks
+ * This can be used to control visibility - an object must share a layer with a {@link Camera | camera} to be visible when that camera's view is rendered.
+ * @remarks
+ * All classes that inherit from {@link THREE.Object3D | Object3D} have an {@link THREE.Object3D.layers | Object3D.layers} property which is an instance of this class.
+ * @see Example: {@link https://threejs.org/examples/#webgl_layers | WebGL / layers}
+ * @see Example: {@link https://threejs.org/examples/#webxr_vr_layers | Webxr / vr / layers}
+ * @see {@link https://threejs.org/docs/index.html#api/en/core/Layers | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/core/Layers.js | Source}
+ */
 export class Layers {
+    /**
+     * Create a new Layers object, with membership initially set to layer 0.
+     */
     constructor();
 
     /**
-     * @default 1 | 0
+     * A bit mask storing which of the 32 layers this layers object is currently a member of.
+     * @defaultValue `1 | 0`
+     * @remarks Expects a `Integer`
      */
     mask: number;
 
-    set(channel: number): void;
-    enable(channel: number): void;
+    /**
+     * Set membership to `layer`, and remove membership all other layers.
+     * @param layer An integer from 0 to 31.
+     */
+    set(layer: number): void;
+
+    /**
+     * Add membership of this `layer`.
+     * @param layer An integer from 0 to 31.
+     */
+    enable(layer: number): void;
+
+    /**
+     * Add membership to all layers.
+     */
     enableAll(): void;
-    toggle(channel: number): void;
-    disable(channel: number): void;
+
+    /**
+     * Toggle membership of `layer`.
+     * @param layer An integer from 0 to 31.
+     */
+    toggle(layer: number): void;
+
+    /**
+     * Remove membership of this `layer`.
+     * @param layer An integer from 0 to 31.
+     */
+    disable(layer: number): void;
+
+    /**
+     * Remove membership from all layers.
+     */
     disableAll(): void;
+
+    /**
+     * Returns true if this and the passed `layers` object have at least one layer in common.
+     * @param layers A Layers object
+     */
     test(layers: Layers): boolean;
-    isEnabled(channel: number): boolean;
+
+    /**
+     * Returns true if the given layer is enabled.
+     * @param layer An integer from 0 to 31.
+     */
+    isEnabled(layer: number): boolean;
 }