@types/three 0.150.0 → 0.150.1

three/src/textures/DataArrayTexture.d.ts

@@ -1,33 +1,107 @@
 import { Texture } from './Texture';
-import { TextureFilter } from '../constants';
+import { MagnificationTextureFilter, MinificationTextureFilter } from '../constants';
+import { Texture3DImageData } from './types';
 
+/**
+ * Creates an array of textures directly from raw data, width and height and depth
+ * @remarks Compatible only with {@link WebGL2RenderingContext | WebGL 2 Rendering Context}.
+ * @example
+ * ```typescript
+ * This creates a[name] where each texture has a different color.
+ * // create a buffer with color data
+ * const width = 512;
+ * const height = 512;
+ * const depth = 100;
+ * const size = width * height;
+ * const data = new Uint8Array(4 * size * depth);
+ * for (let i = 0; i & lt; depth; i++) {
+ *     const color = new THREE.Color(Math.random(), Math.random(), Math.random());
+ *     const r = Math.floor(color.r * 255);
+ *     const g = Math.floor(color.g * 255);
+ *     const b = Math.floor(color.b * 255);
+ *     for (let j = 0; j & lt; size; j++) {
+ *         const stride = (i * size + j) * 4;
+ *         data[stride] = r;
+ *         data[stride + 1] = g;
+ *         data[stride + 2] = b;
+ *         data[stride + 3] = 255;
+ *     }
+ * }
+ * // used the buffer to create a [name]
+ * const texture = new THREE.DataArrayTexture(data, width, height, depth);
+ * texture.needsUpdate = true;
+ * ```
+ * @see Example: {@link https://threejs.org/examples/#webgl2_materials_texture2darray | WebGL2 / materials / texture2darray}
+ * @see Example: {@link https://threejs.org/examples/#webgl2_rendertarget_texture2darray | WebGL2 / rendertarget / texture2darray}
+ * @see {@link https://threejs.org/docs/index.html#api/en/textures/DataArrayTexture | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/textures/DataArrayTexture.js | Source}
+ */
 export class DataArrayTexture extends Texture {
+    /**
+     * This creates a new {@link THREE.DataArrayTexture | DataArrayTexture} object.
+     * @remarks The interpretation of the data depends on {@link format} and {@link type}.
+     * @remarks If the {@link type} is {@link THREE.UnsignedByteType}, a {@link Uint8Array} will be useful for addressing the texel data
+     * @remarks If the {@link format} is {@link THREE.RGBAFormat}, data needs four values for one texel; Red, Green, Blue and Alpha (typically the opacity).
+     * @remarks For the packed {@link type | types}, {@link THREE.UnsignedShort4444Type} and {@link THREE.UnsignedShort5551Type}
+     * all color components of one texel can be addressed as bitfields within an integer element of a {@link Uint16Array}.
+     * @remarks In order to use the {@link type | types} {@link THREE.FloatType} and {@link THREE.HalfFloatType},
+     * the WebGL implementation must support the respective extensions _OES_texture_float_ and _OES_texture_half_float_
+     * @remarks In order to use {@link THREE.LinearFilter} for component-wise, bilinear interpolation of the texels based on these types,
+     * the WebGL extensions _OES_texture_float_linear_ or _OES_texture_half_float_linear_ must also be present.
+     * @param data {@link https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView | ArrayBufferView} of the texture. Default `null`.
+     * @param width Width of the texture. Default `1`.
+     * @param height Height of the texture. Default `1`.
+     * @param depth Depth of the texture. Default `1`.
+     */
     constructor(data?: BufferSource, width?: number, height?: number, depth?: number);
 
     /**
-     * @default THREE.NearestFilter
+     * Read-only flag to check if a given object is of type {@link DataArrayTexture}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isDataArrayTexture: true;
+
+    /**
+     * Overridden with a record type holding data, width and height and depth.
+     * @override
      */
-    magFilter: TextureFilter;
+    get image(): Texture3DImageData;
+    set image(data: Texture3DImageData);
 
     /**
-     * @default THREE.NearestFilter
+     * @override
+     * @defaultValue {@link THREE.NearestFilter}
      */
-    minFilter: TextureFilter;
+    magFilter: MagnificationTextureFilter;
 
     /**
-     * @default THREE.ClampToEdgeWrapping
+     * @override
+     * @defaultValue {@link THREE.NearestFilter}
+     */
+    minFilter: MinificationTextureFilter;
+
+    /**
+     * @override
+     * @defaultValue  {@link THREE.ClampToEdgeWrapping}
      */
     wrapR: boolean;
 
     /**
-     * @default false
+     * @override
+     * @defaultValue `false`
      */
     flipY: boolean;
 
     /**
-     * @default false
+     * @override
+     * @defaultValue `false`
      */
     generateMipmaps: boolean;
 
-    readonly isDataArrayTexture: true;
+    /**
+     * @override
+     * @defaultValue `1`
+     */
+    unpackAlignment: number;
 }

three/src/textures/DataTexture.d.ts

@@ -1,20 +1,56 @@
 import { Texture } from './Texture';
-import { Mapping, Wrapping, TextureFilter, PixelFormat, TextureDataType, TextureEncoding } from '../constants';
+import {
+    Mapping,
+    Wrapping,
+    PixelFormat,
+    TextureDataType,
+    TextureEncoding,
+    MagnificationTextureFilter,
+    MinificationTextureFilter,
+} from '../constants';
+import { TextureImageData } from './types';
 
+/**
+ * Creates a texture directly from raw data, width and height.
+ * @example
+ * ```typescript
+ * // create a buffer with color data
+ * const width = 512;
+ * const height = 512;
+ * const size = width * height;
+ * const data = new Uint8Array(4 * size);
+ * const color = new THREE.Color(0xffffff);
+ * const r = Math.floor(color.r * 255);
+ * const g = Math.floor(color.g * 255);
+ * const b = Math.floor(color.b * 255);
+ * for (let i = 0; i & lt; size; i++) {
+ *     const stride = i * 4;
+ *     data[stride] = r;
+ *     data[stride + 1] = g;
+ *     data[stride + 2] = b;
+ *     data[stride + 3] = 255;
+ * }
+ * // used the buffer to create a [name]
+ * const texture = new THREE.DataTexture(data, width, height);
+ * texture.needsUpdate = true;
+ * ```
+ * @see {@link https://threejs.org/docs/index.html#api/en/textures/DataTexture | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/textures/DataTexture.js | Source}
+ */
 export class DataTexture extends Texture {
     /**
-     * @param data
-     * @param width
-     * @param height
-     * @param [format=THREE.RGBAFormat]
-     * @param [type=THREE.UnsignedByteType]
-     * @param [mapping=THREE.Texture.DEFAULT_MAPPING]
-     * @param [wrapS=THREE.ClampToEdgeWrapping]
-     * @param [wrapT=THREE.ClampToEdgeWrapping]
-     * @param [magFilter=THREE.NearestFilter]
-     * @param [minFilter=THREE.NearestFilter]
-     * @param [anisotropy=1]
-     * @param [encoding=THREE.LinearEncoding]
+     * @param data {@link https://developer.mozilla.org/en-US/docs/Web/API/ArrayBufferView | ArrayBufferView} of the texture. Default `null`.
+     * @param width Width of the texture. Default `1`.
+     * @param height Height of the texture. Default `1`.
+     * @param format See {@link Texture.format | .format}. Default {@link THREE.RGBAFormat}
+     * @param type See {@link Texture.type | .type}. Default {@link THREE.UnsignedByteType}
+     * @param mapping See {@link Texture.mapping | .mapping}. Default {@link THREE.Texture.DEFAULT_MAPPING}
+     * @param wrapS See {@link Texture.wrapS | .wrapS}. Default {@link THREE.ClampToEdgeWrapping}
+     * @param wrapT See {@link Texture.wrapT | .wrapT}. Default {@link THREE.ClampToEdgeWrapping}
+     * @param magFilter See {@link Texture.magFilter | .magFilter}. Default {@link THREE.NearestFilter}
+     * @param minFilter  See {@link Texture.minFilter | .minFilter}. Default {@link THREE.NearestFilter}
+     * @param anisotropy See {@link Texture.anisotropy | .anisotropy}. Default {@link THREE.Texture.DEFAULT_ANISOTROPY}
+     * @param encoding See {@link Texture.encoding | .encoding}. Default {@link THREE.LinearEncoding}
      */
     constructor(
         data?: BufferSource | null,
@@ -25,34 +61,53 @@ export class DataTexture extends Texture {
         mapping?: Mapping,
         wrapS?: Wrapping,
         wrapT?: Wrapping,
-        magFilter?: TextureFilter,
-        minFilter?: TextureFilter,
+        magFilter?: MagnificationTextureFilter,
+        minFilter?: MinificationTextureFilter,
         anisotropy?: number,
         encoding?: TextureEncoding,
     );
 
-    get image(): ImageData;
-    set image(value: ImageData);
+    /**
+     * Read-only flag to check if a given object is of type {@link DataTexture}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isDataTexture: true;
 
     /**
-     * @default false
+     * Overridden with a record type holding data, width and height and depth.
+     * @override
      */
-    flipY: boolean;
+    get image(): TextureImageData;
+    set image(value: TextureImageData);
 
     /**
-     * @default false
+     * @override
+     * @defaultValue {@link THREE.NearestFilter}
      */
-    generateMipmaps: boolean;
+    magFilter: MagnificationTextureFilter;
 
     /**
-     * @default 1
+     * @override
+     * @defaultValue {@link THREE.NearestFilter}
      */
-    unpackAlignment: number;
+    minFilter: MinificationTextureFilter;
 
     /**
-     * @default THREE.DepthFormat
+     * @override
+     * @defaultValue `false`
      */
-    format: PixelFormat;
+    flipY: boolean;
 
-    readonly isDataTexture: true;
+    /**
+     * @override
+     * @defaultValue `false`
+     */
+    generateMipmaps: boolean;
+
+    /**
+     * @override
+     * @defaultValue `1`
+     */
+    unpackAlignment: number;
 }

three/src/textures/DepthTexture.d.ts

@@ -1,17 +1,35 @@
 import { Texture } from './Texture';
-import { Mapping, Wrapping, TextureFilter, TextureDataType } from '../constants';
+import {
+    Mapping,
+    Wrapping,
+    TextureDataType,
+    DeepTexturePixelFormat,
+    MagnificationTextureFilter,
+    MinificationTextureFilter,
+} from '../constants';
 
+/**
+ * This class can be used to automatically save the depth information of a rendering into a texture
+ * @remarks
+ * When using a **WebGL1** rendering context, {@link DepthTexture} requires support for the
+ * {@link https://www.khronos.org/registry/webgl/extensions/WEBGL_depth_texture/ | WEBGL_depth_texture} extension.
+ * @see Example: {@link https://threejs.org/examples/#webgl_depth_texture | depth / texture}
+ * @see {@link https://threejs.org/docs/index.html#api/en/textures/DepthTexture | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/textures/DepthTexture.js | Source}
+ */
 export class DepthTexture extends Texture {
     /**
-     * @param width
-     * @param height
-     * @param type
-     * @param [mapping=THREE.Texture.DEFAULT_MAPPING]
-     * @param [wrapS=THREE.ClampToEdgeWrapping]
-     * @param [wrapT=THREE.ClampToEdgeWrapping]
-     * @param [magFilter=THREE.NearestFilter]
-     * @param [minFilter=THREE.NearestFilter]
-     * @param [anisotropy=1]
+     * Create a new instance of {@link DepthTexture}
+     * @param width Width of the texture.
+     * @param height Height of the texture.
+     * @param type See {@link Texture.type | .type}. Default {@link THREE.UnsignedByteType} or {@link THREE.UnsignedInt248Type}
+     * @param mapping See {@link Texture.mapping | .mapping}. Default {@link THREE.Texture.DEFAULT_MAPPING}
+     * @param wrapS See {@link Texture.wrapS | .wrapS}. Default {@link THREE.ClampToEdgeWrapping}
+     * @param wrapT See {@link Texture.wrapT | .wrapT}. Default {@link THREE.ClampToEdgeWrapping}
+     * @param magFilter See {@link Texture.magFilter | .magFilter}. Default {@link THREE.NearestFilter}
+     * @param minFilter  See {@link Texture.minFilter | .minFilter}. Default {@link THREE.NearestFilter}
+     * @param anisotropy See {@link Texture.anisotropy | .anisotropy}. Default {@link THREE.Texture.DEFAULT_ANISOTROPY}
+     * @param format See {@link DepthTexture.format | .format}. Default {@link THREE.DepthFormat}
      */
     constructor(
         width: number,
@@ -20,23 +38,61 @@ export class DepthTexture extends Texture {
         mapping?: Mapping,
         wrapS?: Wrapping,
         wrapT?: Wrapping,
-        magFilter?: TextureFilter,
-        minFilter?: TextureFilter,
+        magFilter?: MagnificationTextureFilter,
+        minFilter?: MinificationTextureFilter,
         anisotropy?: number,
+        format?: DeepTexturePixelFormat,
     );
 
+    /**
+     * Read-only flag to check if a given object is of type {@link DepthTexture}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isDepthTexture: true;
+
+    /**
+     * Overridden with a record type holding width and height.
+     * @override
+     */
     get image(): { width: number; height: number };
     set image(value: { width: number; height: number });
 
     /**
-     * @default false
+     * @override
+     * @defaultValue `false`
      */
     flipY: boolean;
 
     /**
-     * @default false
+     * @override
+     * @defaultValue {@link THREE.NearestFilter}
+     */
+    magFilter: MagnificationTextureFilter;
+
+    /**
+     * @override
+     * @defaultValue {@link THREE.NearestFilter}
+     */
+    minFilter: MinificationTextureFilter;
+
+    /**
+     * @override Depth textures do not use mipmaps.
+     * @defaultValue `false`
      */
     generateMipmaps: boolean;
 
-    readonly isDepthTexture: true;
+    /**
+     * @override
+     * @see {@link Texture.format | Texture.format}
+     * @defaultValue {@link THREE.DepthFormat}.
+     */
+    format: DeepTexturePixelFormat;
+
+    /**
+     * @override
+     * @defaultValue {@link THREE.UnsignedByteType} when {@link format | .format} === {@link THREE.DepthFormat}
+     * @defaultValue {@link THREE.UnsignedInt248Type} when {@link format | .format} === {@link THREE.DepthStencilFormat}
+     */
+    type: TextureDataType;
 }

three/src/textures/FramebufferTexture.d.ts

@@ -1,8 +1,63 @@
 import { Texture } from './Texture';
-import { PixelFormat } from '../constants';
+import { MagnificationTextureFilter, MinificationTextureFilter, PixelFormat } from '../constants';
 
+/**
+ * This class can only be used in combination with {@link THREE.WebGLRenderer.copyFramebufferToTexture | WebGLRenderer.copyFramebufferToTexture()}.
+ * @example
+ * ```typescript
+ * const pixelRatio = window.devicePixelRatio;
+ * const textureSize = 128 * pixelRatio;
+ *
+ * // instantiate a framebuffer texture
+ * const frameTexture = new FramebufferTexture( textureSize, textureSize, RGBAFormat );
+ *
+ * // calculate start position for copying part of the frame data
+ * const vector = new Vector2();
+ * vector.x = ( window.innerWidth * pixelRatio / 2 ) - ( textureSize / 2 );
+ * vector.y = ( window.innerHeight * pixelRatio / 2 ) - ( textureSize / 2 );
+ *
+ * // render the scene
+ * renderer.clear();
+ * renderer.render( scene, camera );
+ *
+ * // copy part of the rendered frame into the framebuffer texture
+ * renderer.copyFramebufferToTexture( vector, frameTexture );
+ * ```
+ * @see Example: {@link https://threejs.org/examples/#webgl_framebuffer_texture | webgl_framebuffer_texture}
+ * @see {@link https://threejs.org/docs/index.html#api/en/textures/FramebufferTexture | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/textures/FramebufferTexture.js | Source}
+ */
 export class FramebufferTexture extends Texture {
+    /**
+     * Create a new instance of {@link FramebufferTexture}
+     * @param width The width of the texture.
+     * @param height The height of the texture.
+     * @param format See {@link Texture.format | .format}. Default {@link THREE.RGBAFormat}.
+     */
+    constructor(width: number, height: number, format: PixelFormat);
+
+    /**
+     * Read-only flag to check if a given object is of type {@link FramebufferTexture}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
     readonly isFramebufferTexture: true;
 
-    constructor(width: number, height: number, format: PixelFormat);
+    /**
+     * @override
+     * @defaultValue {@link THREE.NearestFilter}
+     */
+    magFilter: MagnificationTextureFilter;
+
+    /**
+     * @override
+     * @defaultValue {@link THREE.NearestFilter}
+     */
+    minFilter: MinificationTextureFilter;
+
+    /**
+     * @override
+     * @defaultValue `false`
+     */
+    generateMipmaps: boolean;
 }

three/src/textures/Source.d.ts

@@ -1,39 +1,49 @@
 /**
- * Represents the data source of a texture.
+ * Represents the data {@link Source} of a texture.
+ * @see {@link https://threejs.org/docs/index.html#api/en/textures/Source | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/textures/Source.js | Source}
  */
 export class Source {
     /**
-     * @param [data] The data definition of a texture. default is **null**.
+     * Create a new instance of {@link Source}
+     * @param data The data definition of a texture. Default `null`
      */
     constructor(data: any);
 
     /**
-     * The actual data of a texture. The type of this property depends on the texture that uses this instance.
+     * Flag to check if a given object is of type {@link Source}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isSource: true;
+
+    /**
+     * The actual data of a texture.
+     * @remarks The type of this property depends on the texture that uses this instance.
      */
     data: any;
 
     /**
-     * Set this to **true** to trigger a data upload to the GPU next time the source is used.
+     * Set this to `true` to trigger a data upload to the GPU next time the {@link Source} is used.
      */
     set needsUpdate(value: boolean);
 
     /**
-     * [UUID](http://en.wikipedia.org/wiki/Universally_unique_identifier) of this object instance.
-     * This gets automatically assigned, so this shouldn't be edited.
+     * {@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;
 
     /**
-     * This starts at **0** and counts how many times [property:Boolean needsUpdate] is set to **true**.
+     * This starts at `0` and counts how many times {@link needsUpdate | .needsUpdate} is set to `true`.
+     * @remarks Expects a `Integer`
+     * @defaultValue `0`
      */
     version: number;
 
     /**
-     * Convert the data source to three.js [JSON Object/Scene format](https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4).
-     *
-     * @param [meta] optional object containing metadata.
+     * Convert the data {@link Source} to three.js {@link https://github.com/mrdoob/three.js/wiki/JSON-Object-Scene-format-4 | JSON Object/Scene format}.
+     * @param meta Optional object containing metadata.
      */
-    toJSON(meta: any): any;
-
-    readonly isTexture: true;
+    toJSON(meta?: string | {}): {};
 }