@types/three 0.150.0 → 0.150.2

three/src/textures/CanvasTexture.d.ts

@@ -1,30 +1,52 @@
 import { OffscreenCanvas, Texture } from './Texture';
-import { Mapping, Wrapping, TextureFilter, PixelFormat, TextureDataType } from '../constants';
+import {
+    Mapping,
+    Wrapping,
+    PixelFormat,
+    TextureDataType,
+    MagnificationTextureFilter,
+    MinificationTextureFilter,
+} from '../constants';
 
+/**
+ * Creates a texture from a {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/canvas | canvas element}.
+ * @remarks
+ * This is almost the same as the base {@link Texture | Texture} class,
+ * except that it sets {@link Texture.needsUpdate | needsUpdate} to `true` immediately.
+ * @see {@link THREE.Texture | Texture}
+ * @see {@link https://threejs.org/docs/index.html#api/en/textures/CanvasTexture | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/textures/CanvasTexture.js | Source}
+ */
 export class CanvasTexture extends Texture {
     /**
-     * @param canvas
-     * @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.LinearFilter]
-     * @param [minFilter=THREE.LinearMipmapLinearFilter]
-     * @param [anisotropy=1]
-     * @param [encoding=THREE.LinearEncoding]
+     * This creates a new {@link THREE.CanvasTexture | CanvasTexture} object.
+     * @param canvas The HTML canvas element from which to load the texture.
+     * @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.LinearFilter}
+     * @param minFilter  See {@link Texture.minFilter | .minFilter}. Default {@link THREE.LinearMipmapLinearFilter}
+     * @param format See {@link Texture.format | .format}. Default {@link THREE.RGBAFormat}
+     * @param type See {@link Texture.type | .type}. Default {@link THREE.UnsignedByteType}
+     * @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(
         canvas: TexImageSource | OffscreenCanvas,
         mapping?: Mapping,
         wrapS?: Wrapping,
         wrapT?: Wrapping,
-        magFilter?: TextureFilter,
-        minFilter?: TextureFilter,
+        magFilter?: MagnificationTextureFilter,
+        minFilter?: MinificationTextureFilter,
         format?: PixelFormat,
         type?: TextureDataType,
         anisotropy?: number,
     );
 
+    /**
+     * Read-only flag to check if a given object is of type {@link CanvasTexture}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
     readonly isCanvasTexture: true;
 }

three/src/textures/CompressedArrayTexture.d.ts

@@ -1,17 +1,51 @@
 import { CompressedPixelFormat, TextureDataType, Wrapping } from '../constants';
 import { CompressedTexture } from './CompressedTexture.js';
 
+/**
+ * Creates an texture 2D array based on data in compressed form, for example from a
+ * {@link https://en.wikipedia.org/wiki/DirectDraw_Surface | DDS} file.
+ * @remarks For use with the {@link THREE.CompressedTextureLoader | CompressedTextureLoader}.
+ * @see {@link https://threejs.org/docs/index.html#api/en/textures/CompressedArrayTexture | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/textures/CompressedArrayTexture.js | Source}
+ */
 export class CompressedArrayTexture extends CompressedTexture {
-    isCompressedArrayTexture: true;
-
-    wrapR: Wrapping;
-
+    /**
+     * Create a new instance of {@link CompressedArrayTexture}
+     * @param mipmaps The mipmaps array should contain objects with data, width and height.
+     * The mipmaps should be of the correct {@link format} and {@link type}. See {@link THREE.mipmaps}.
+     * @param width The width of the biggest mipmap.
+     * @param height The height of the biggest mipmap.
+     * @param depth The number of layers of the 2D array texture
+     * @param format The format used in the mipmaps. See {@link THREE.CompressedPixelFormat}.
+     * @param type See {@link Texture.type | .type}. Default {@link THREE.UnsignedByteType}
+     */
     constructor(
         mipmaps: ImageData[],
         width: number,
         height: number,
         depth: number,
-        format?: CompressedPixelFormat,
+        format: CompressedPixelFormat,
         type?: TextureDataType,
     );
+
+    /**
+     * Read-only flag to check if a given object is of type {@link CompressedArrayTexture}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isCompressedArrayTexture: true;
+
+    /**
+     * Overridden with a object containing width and height.
+     * @override
+     */
+    get image(): { width: number; height: number; depth: number };
+    set image(value: { width: number; height: number; depth: number });
+
+    /**
+     * This defines how the texture is wrapped in the depth direction.
+     * @see {@link https://threejs.org/docs/index.html#api/en/constants/Textures | Texture Constants}
+     * @defaultValue {@link THREE.ClampToEdgeWrapping}
+     */
+    wrapR: Wrapping;
 }

three/src/textures/CompressedTexture.d.ts

@@ -2,56 +2,85 @@ import { Texture } from './Texture';
 import {
     Mapping,
     Wrapping,
-    TextureFilter,
     CompressedPixelFormat,
     TextureDataType,
     TextureEncoding,
+    MagnificationTextureFilter,
+    MinificationTextureFilter,
 } from '../constants';
 
+/**
+ * Creates a texture based on data in compressed form, for example from a {@link https://en.wikipedia.org/wiki/DirectDraw_Surface | DDS} file.
+ * @remarks For use with the {@link THREE.CompressedTextureLoader | CompressedTextureLoader}.
+ * @see {@link https://threejs.org/docs/index.html#api/en/textures/CompressedTexture | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/textures/CompressedTexture.js | Source}
+ */
 export class CompressedTexture extends Texture {
     /**
-     * @param mipmaps
-     * @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.LinearFilter]
-     * @param [minFilter=THREE.LinearMipmapLinearFilter]
-     * @param [anisotropy=1]
-     * @param [encoding=THREE.LinearEncoding]
+     * This creates a new {@link THREE.CompressedTexture | CompressedTexture} object.
+     * @param mipmaps The mipmaps array should contain objects with data, width and height.
+     * The mipmaps should be of the correct {@link format} and {@link type}. See {@link THREE.mipmaps}.
+     * @param width The width of the biggest mipmap.
+     * @param height The height of the biggest mipmap.
+     * @param format The format used in the mipmaps. See {@link THREE.CompressedPixelFormat}.
+     * @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.LinearFilter}
+     * @param minFilter  See {@link Texture.minFilter | .minFilter}. Default {@link THREE.LinearMipmapLinearFilter}
+     * @param anisotropy See {@link Texture.anisotropy | .anisotropy}. Default {@link THREE.Texture.DEFAULT_ANISOTROPY}
      */
     constructor(
         mipmaps: ImageData[],
         width: number,
         height: number,
-        format?: CompressedPixelFormat,
+        format: CompressedPixelFormat,
         type?: TextureDataType,
         mapping?: Mapping,
         wrapS?: Wrapping,
         wrapT?: Wrapping,
-        magFilter?: TextureFilter,
-        minFilter?: TextureFilter,
+        magFilter?: MagnificationTextureFilter,
+        minFilter?: MinificationTextureFilter,
         anisotropy?: number,
         encoding?: TextureEncoding,
     );
 
+    /**
+     * Read-only flag to check if a given object is of type {@link CompressedTexture}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isCompressedTexture: true;
+
+    /**
+     * Overridden with a object containing width and height.
+     * @override
+     */
     get image(): { width: number; height: number };
     set image(value: { width: number; height: number });
 
+    /**
+     *  The mipmaps array should contain objects with data, width and height. The mipmaps should be of the correct {@link format} and {@link type}.
+     */
     mipmaps: ImageData[];
 
     /**
-     * @default false
+     * @override
+     * @see {@link https://threejs.org/docs/index.html#api/en/constants/Textures | Texture Constants}
+     * @see {@link THREE.CompressedPixelFormat}
+     */
+    format: CompressedPixelFormat;
+
+    /**
+     * @override No flipping for cube textures. (also flipping doesn't work for compressed textures)
+     * @defaultValue `false`
      */
     flipY: boolean;
 
     /**
-     * @default false
+     * @override Can't generate mipmaps for compressed textures. mips must be embedded in DDS files
+     * @defaultValue `false`
      */
     generateMipmaps: boolean;
-
-    readonly isCompressedTexture: true;
 }

three/src/textures/CubeTexture.d.ts

@@ -1,38 +1,91 @@
 import { Texture } from './Texture';
-import { Mapping, Wrapping, TextureFilter, PixelFormat, TextureDataType, TextureEncoding } from '../constants';
+import {
+    Mapping,
+    Wrapping,
+    PixelFormat,
+    TextureDataType,
+    TextureEncoding,
+    MagnificationTextureFilter,
+    MinificationTextureFilter,
+    CubeTextureMapping,
+} from '../constants';
 
+/**
+ * Creates a cube texture made up of six images.
+ * @remarks
+ * {@link CubeTexture} is almost equivalent in functionality and usage to {@link Texture}.
+ * The only differences are that the images are an array of _6_ images as opposed to a single image,
+ * and the mapping options are {@link THREE.CubeReflectionMapping} (default) or {@link THREE.CubeRefractionMapping}
+ * @example
+ * ```typescript
+ * const loader = new THREE.CubeTextureLoader();
+ * loader.setPath('textures/cube/pisa/');
+ * const textureCube = loader.load(['px.png', 'nx.png', 'py.png', 'ny.png', 'pz.png', 'nz.png']);
+ * const material = new THREE.MeshBasicMaterial({
+ *     color: 0xffffff,
+ *     envMap: textureCube
+ * });
+ * ```
+ * @see {@link https://threejs.org/docs/index.html#api/en/textures/CubeTexture | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/textures/CubeTexture.js | Source}
+ */
 export class CubeTexture extends Texture {
     /**
-     * @param [images=[]]
-     * @param [mapping=THREE.CubeReflectionMapping]
-     * @param [wrapS=THREE.ClampToEdgeWrapping]
-     * @param [wrapT=THREE.ClampToEdgeWrapping]
-     * @param [magFilter=THREE.LinearFilter]
-     * @param [minFilter=THREE.LinearMipmapLinearFilter]
-     * @param [format=THREE.RGBAFormat]
-     * @param [type=THREE.UnsignedByteType]
-     * @param [anisotropy=1]
-     * @param [encoding=THREE.LinearEncoding]
+     * This creates a new {@link THREE.CubeTexture | CubeTexture} object.
+     * @param images
+     * @param mapping See {@link CubeTexture.mapping | .mapping}. Default {@link THREE.CubeReflectionMapping}
+     * @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.LinearFilter}
+     * @param minFilter  See {@link Texture.minFilter | .minFilter}. Default {@link THREE.LinearMipmapLinearFilter}
+     * @param format See {@link Texture.format | .format}. Default {@link THREE.RGBAFormat}
+     * @param type See {@link Texture.type | .type}. Default {@link THREE.UnsignedByteType}
+     * @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(
         images?: any[], // HTMLImageElement or HTMLCanvasElement
-        mapping?: Mapping,
+        mapping?: CubeTextureMapping,
         wrapS?: Wrapping,
         wrapT?: Wrapping,
-        magFilter?: TextureFilter,
-        minFilter?: TextureFilter,
+        magFilter?: MagnificationTextureFilter,
+        minFilter?: MinificationTextureFilter,
         format?: PixelFormat,
         type?: TextureDataType,
         anisotropy?: number,
         encoding?: TextureEncoding,
     );
 
-    images: any; // returns and sets the value of Texture.image in the codde ?
+    /**
+     * Read-only flag to check if a given object is of type {@link CubeTexture}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
+     */
+    readonly isCubeTexture: true;
 
     /**
-     * @default false
+     * An image object, typically created using the {@link THREE.CubeTextureLoader.load | CubeTextureLoader.load()} method.
+     * @see {@link Texture.image}
      */
-    flipY: boolean;
+    get image(): any;
+    set image(data: any);
 
-    readonly isCubeTexture: true;
+    /**
+     * An image object, typically created using the {@link THREE.CubeTextureLoader.load | CubeTextureLoader.load()} method.
+     * @see {@link Texture.image}
+     */
+    get images(): any;
+    set images(data: any);
+
+    /**
+     * @inheritDoc
+     * @defaultValue {@link THREE.CubeReflectionMapping}
+     */
+    mapping: CubeTextureMapping;
+
+    /**
+     * @inheritDoc
+     * @defaultValue `false`
+     */
+    flipY: boolean;
 }

three/src/textures/Data3DTexture.d.ts

@@ -1,33 +1,97 @@
 import { Texture } from './Texture';
-import { TextureFilter, Wrapping } from '../constants';
+import { MagnificationTextureFilter, MinificationTextureFilter, Wrapping } from '../constants';
+import { Texture3DImageData } from './types';
 
+/**
+ * Creates a three-dimensional texture from raw data, with parameters to divide it into width, height, and depth
+ * @remarks Compatible only with {@link WebGL2RenderingContext | WebGL 2 Rendering Context}.
+ * @example
+ * ```typescript
+ * This creates a[name] with repeating data, 0 to 255
+ * // create a buffer with some data
+ * const sizeX = 64;
+ * const sizeY = 64;
+ * const sizeZ = 64;
+ * const data = new Uint8Array(sizeX * sizeY * sizeZ);
+ * let i = 0;
+ * for (let z = 0; z & lt; sizeZ; z++) {
+ *     for (let y = 0; y & lt; sizeY; y++) {
+ *         for (let x = 0; x & lt; sizeX; x++) {
+ *             data[i] = i % 256;
+ *             i++;
+ *         }
+ *     }
+ * }
+ * // use the buffer to create the texture
+ * const texture = new THREE.Data3DTexture(data, sizeX, sizeY, sizeZ);
+ * texture.needsUpdate = true;
+ * ```
+ * @see Example: {@link https://threejs.org/examples/#webgl2_materials_texture3d | WebGL2 / materials / texture3d}
+ * @see Example: {@link https://threejs.org/examples/#webgl2_materials_texture3d_partialupdate | WebGL2 / materials / texture3d / partialupdate}
+ * @see Example: {@link https://threejs.org/examples/#webgl2_volume_cloud | WebGL2 / volume / cloud}
+ * @see Example: {@link https://threejs.org/examples/#webgl2_volume_perlin | WebGL2 / volume / perlin}
+ * @see {@link https://threejs.org/docs/index.html#api/en/textures/Data3DTexture | Official Documentation}
+ * @see {@link https://github.com/mrdoob/three.js/blob/master/src/textures/Data3DTexture.js | Source}
+ */
 export class Data3DTexture extends Texture {
-    constructor(data: BufferSource, width: number, height: number, depth: number);
+    /**
+     * Create a new instance of {@link Data3DTexture}
+     * @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 | null, width?: number, height?: number, depth?: number);
 
     /**
-     * @default THREE.NearestFilter
+     * Read-only flag to check if a given object is of type {@link Data3DTexture}.
+     * @remarks This is a _constant_ value
+     * @defaultValue `true`
      */
-    magFilter: TextureFilter;
+    readonly isData3DTexture: true;
 
     /**
-     * @default THREE.NearestFilter
+     * Overridden with a record type holding data, width and height and depth.
+     * @override
      */
-    minFilter: TextureFilter;
+    get image(): Texture3DImageData;
+    set image(data: Texture3DImageData);
 
     /**
-     * @default THREE.ClampToEdgeWrapping
+     * @override
+     * @defaultValue {@link THREE.NearestFilter}
+     */
+    magFilter: MagnificationTextureFilter;
+
+    /**
+     * @override
+     * @defaultValue {@link THREE.NearestFilter}
+     */
+    minFilter: MinificationTextureFilter;
+
+    /**
+     * @override
+     * @defaultValue {@link THREE.ClampToEdgeWrapping}
      */
     wrapR: Wrapping;
 
     /**
-     * @default false
+     * @override
+     * @defaultValue `false`
      */
     flipY: boolean;
 
     /**
-     * @default false
+     * @override
+     * @defaultValue `false`
      */
     generateMipmaps: boolean;
 
-    readonly isData3DTexture: true;
+    /**
+     * @override
+     * @defaultValue `1`
+     */
+    unpackAlignment: number;
 }
+
+export {};

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;
 }