@types/three 0.176.0 → 0.178.0

three/src/materials/PointsMaterial.d.ts

@@ -1,56 +1,103 @@
-import { Color, ColorRepresentation } from "../math/Color.js";
+import { Color } from "../math/Color.js";
 import { Texture } from "../textures/Texture.js";
-import { Material, MaterialParameters } from "./Material.js";
-
-export interface PointsMaterialParameters extends MaterialParameters {
-    color?: ColorRepresentation | undefined;
-    map?: Texture | null | undefined;
-    alphaMap?: Texture | null | undefined;
-    size?: number | undefined;
-    sizeAttenuation?: boolean | undefined;
-    fog?: boolean | undefined;
-}
-
-export class PointsMaterial extends Material {
-    constructor(parameters?: PointsMaterialParameters);
-
-    /**
-     * Read-only flag to check if a given object is of type {@link PointsMaterial}.
-     * @remarks This is a _constant_ value
-     * @defaultValue `true`
-     */
-    readonly isPointsMaterial: true;
+import { MapColorPropertiesToColorRepresentations, Material, MaterialProperties } from "./Material.js";
 
+export interface PointsMaterialProperties extends MaterialProperties {
     /**
-     * @default new THREE.Color( 0xffffff )
+     * Color of the material.
+     *
+     * @default (1,1,1)
      */
     color: Color;
-
     /**
+     * The color map. May optionally include an alpha channel, typically combined
+     * with {@link Material#transparent} or {@link Material#alphaTest}. The texture map
+     * color is modulated by the diffuse `color`.
+     *
      * @default null
      */
     map: Texture | null;
-
     /**
+     * The alpha map is a grayscale texture that controls the opacity across the
+     * surface (black: fully transparent; white: fully opaque).
+     *
+     * Only the color of the texture is used, ignoring the alpha channel if one
+     * exists. For RGB and RGBA textures, the renderer will use the green channel
+     * when sampling this texture due to the extra bit of precision provided for
+     * green in DXT-compressed and uncompressed RGB 565 formats. Luminance-only and
+     * luminance/alpha textures will also still work as expected.
+     *
      * @default null
      */
     alphaMap: Texture | null;
-
     /**
+     * Defines the size of the points in pixels.
+     *
+     * Might be capped if the value exceeds hardware dependent parameters like [gl.ALIASED_POINT_SIZE_RANGE]{@link https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/getParamete}.
+     *
      * @default 1
      */
     size: number;
-
     /**
+     * Specifies whether size of individual points is attenuated by the camera depth (perspective camera only).
+     *
      * @default true
      */
     sizeAttenuation: boolean;
-
     /**
-     * Whether the material is affected by fog. Default is true.
-     * @default fog
+     * Whether the material is affected by fog or not.
+     *
+     * @default true
      */
     fog: boolean;
+}
 
-    setValues(parameters: PointsMaterialParameters): void;
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface PointsMaterialParameters
+    extends Partial<MapColorPropertiesToColorRepresentations<PointsMaterialProperties>>
+{}
+
+/**
+ * A material for rendering point primitives.
+ *
+ * Materials define the appearance of renderable 3D objects.
+ *
+ * ```js
+ * const vertices = [];
+ *
+ * for ( let i = 0; i < 10000; i ++ ) {
+ * 	const x = THREE.MathUtils.randFloatSpread( 2000 );
+ * 	const y = THREE.MathUtils.randFloatSpread( 2000 );
+ * 	const z = THREE.MathUtils.randFloatSpread( 2000 );
+ *
+ * 	vertices.push( x, y, z );
+ * }
+ *
+ * const geometry = new THREE.BufferGeometry();
+ * geometry.setAttribute( 'position', new THREE.Float32BufferAttribute( vertices, 3 ) );
+ * const material = new THREE.PointsMaterial( { color: 0x888888 } );
+ * const points = new THREE.Points( geometry, material );
+ * scene.add( points );
+ * ```
+ */
+export class PointsMaterial extends Material {
+    /**
+     * Constructs a new points material.
+     *
+     * @param {Object} [parameters] - An object with one or more properties
+     * defining the material's appearance. Any property of the material
+     * (including any property from inherited materials) can be passed
+     * in here. Color values can be passed any type of value accepted
+     * by {@link Color#set}.
+     */
+    constructor(parameters?: PointsMaterialParameters);
+    /**
+     * This flag can be used for type testing.
+     *
+     * @default true
+     */
+    readonly isPointsMaterial: boolean;
 }
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface PointsMaterial extends PointsMaterialProperties {}

three/src/materials/RawShaderMaterial.d.ts

@@ -1,12 +1,17 @@
-import { ShaderMaterial, ShaderMaterialParameters } from "./ShaderMaterial.js";
+import { ShaderMaterial } from "./ShaderMaterial.js";
 
+/**
+ * This class works just like {@link ShaderMaterial}, except that definitions
+ * of built-in uniforms and attributes are not automatically prepended to the
+ * GLSL shader code.
+ *
+ * `RawShaderMaterial` can only be used with {@link WebGLRenderer}.
+ */
 export class RawShaderMaterial extends ShaderMaterial {
-    constructor(parameters?: ShaderMaterialParameters);
-
     /**
-     * Read-only flag to check if a given object is of type {@link RawShaderMaterial}.
-     * @remarks This is a _constant_ value
-     * @defaultValue `true`
+     * This flag can be used for type testing.
+     *
+     * @default true
      */
-    readonly isRawShaderMaterial: true;
+    readonly isRawShaderMaterial: boolean;
 }

three/src/materials/ShaderMaterial.d.ts

@@ -1,162 +1,250 @@
 import { GLSLVersion } from "../constants.js";
 import { JSONMeta } from "../core/Object3D.js";
 import { UniformsGroup } from "../core/UniformsGroup.js";
-import { Matrix3, Matrix3Tuple } from "../math/Matrix3.js";
-import { Matrix4, Matrix4Tuple } from "../math/Matrix4.js";
+import { Matrix3Tuple } from "../math/Matrix3.js";
+import { Matrix4Tuple } from "../math/Matrix4.js";
 import { Vector2Tuple } from "../math/Vector2.js";
 import { Vector3Tuple } from "../math/Vector3.js";
 import { Vector4Tuple } from "../math/Vector4.js";
 import { IUniform } from "../renderers/shaders/UniformsLib.js";
-import { Material, MaterialJSON, MaterialParameters } from "./Material.js";
-
-export interface ShaderMaterialParameters extends MaterialParameters {
-    uniforms?: { [uniform: string]: IUniform } | undefined;
-    uniformsGroups?: UniformsGroup[] | undefined;
-    vertexShader?: string | undefined;
-    fragmentShader?: string | undefined;
-    linewidth?: number | undefined;
-    wireframe?: boolean | undefined;
-    wireframeLinewidth?: number | undefined;
-    lights?: boolean | undefined;
-    clipping?: boolean | undefined;
-    fog?: boolean | undefined;
-    extensions?:
-        | {
-            clipCullDistance?: boolean | undefined;
-            multiDraw?: boolean | undefined;
-        }
-        | undefined;
-    glslVersion?: GLSLVersion | undefined;
-}
-
-export type ShaderMaterialUniformJSON = {
-    type: "t";
-    value: string;
-} | {
-    type: "c";
-    value: number;
-} | {
-    type: "v2";
-    value: Vector2Tuple;
-} | {
-    type: "v3";
-    value: Vector3Tuple;
-} | {
-    type: "v4";
-    value: Vector4Tuple;
-} | {
-    type: "m3";
-    value: Matrix3Tuple;
-} | {
-    type: "m4";
-    value: Matrix4Tuple;
-} | {
-    value: unknown;
-};
-
-export interface ShaderMaterialJSON extends MaterialJSON {
-    glslVersion: number | null;
-    uniforms: Record<string, ShaderMaterialUniformJSON>;
-
-    defines?: Record<string, unknown>;
-
-    vertexShader: string;
-    fragmentShader: string;
-
-    lights: boolean;
-    clipping: boolean;
-
-    extensions?: Record<string, boolean>;
-}
-
-export class ShaderMaterial extends Material {
-    constructor(parameters?: ShaderMaterialParameters);
-
-    /**
-     * Read-only flag to check if a given object is of type {@link ShaderMaterial}.
-     * @remarks This is a _constant_ value
-     * @defaultValue `true`
-     */
-    readonly isShaderMaterial: true;
+import { MapColorPropertiesToColorRepresentations, Material, MaterialJSON, MaterialProperties } from "./Material.js";
 
+export interface ShaderMaterialProperties extends MaterialProperties {
     /**
-     * @default {}
+     * Defines custom constants using `#define` directives within the GLSL code
+     * for both the vertex shader and the fragment shader; each key/value pair
+     * yields another directive.
+     * ```js
+     * defines: {
+     * 	FOO: 15,
+     * 	BAR: true
+     * }
+     * ```
+     * Yields the lines:
+     * ```
+     * #define FOO 15
+     * #define BAR true
+     * ```
      */
     defines: { [key: string]: any };
-
     /**
-     * @default {}
+     * An object of the form:
+     * ```js
+     * {
+     * 	"uniform1": { value: 1.0 },
+     * 	"uniform2": { value: 2 }
+     * }
+     * ```
+     * specifying the uniforms to be passed to the shader code; keys are uniform
+     * names, values are definitions of the form
+     * ```
+     * {
+     * 	value: 1.0
+     * }
+     * ```
+     * where `value` is the value of the uniform. Names must match the name of
+     * the uniform, as defined in the GLSL code. Note that uniforms are refreshed
+     * on every frame, so updating the value of the uniform will immediately
+     * update the value available to the GLSL code.
      */
     uniforms: { [uniform: string]: IUniform };
-
-    uniformsGroups: UniformsGroup[];
-
+    /**
+     * An array holding uniforms groups for configuring UBOs.
+     */
+    uniformsGroups: Array<UniformsGroup>;
+    /**
+     * Vertex shader GLSL code. This is the actual code for the shader.
+     */
     vertexShader: string;
-
+    /**
+     * Fragment shader GLSL code. This is the actual code for the shader.
+     */
     fragmentShader: string;
-
     /**
+     * Controls line thickness or lines.
+     *
+     * WebGL and WebGPU ignore this setting and always render line primitives with a
+     * width of one pixel.
+     *
      * @default 1
      */
     linewidth: number;
-
     /**
+     * Renders the geometry as a wireframe.
+     *
      * @default false
      */
     wireframe: boolean;
-
     /**
+     * Controls the thickness of the wireframe.
+     *
+     * WebGL and WebGPU ignore this property and always render
+     * 1 pixel wide lines.
+     *
      * @default 1
      */
     wireframeLinewidth: number;
-
     /**
+     * Define whether the material color is affected by global fog settings; `true`
+     * to pass fog uniforms to the shader.
+     *
      * @default false
      */
     fog: boolean;
-
     /**
+     * Defines whether this material uses lighting; `true` to pass uniform data
+     * related to lighting to this shader.
+     *
      * @default false
      */
     lights: boolean;
-
     /**
+     * Defines whether this material supports clipping; `true` to let the renderer
+     * pass the clippingPlanes uniform.
+     *
      * @default false
      */
     clipping: boolean;
-
     /**
-     * @default {
-     *   clipCullDistance: false,
-     *   multiDraw: false
-     * }
+     * This object allows to enable certain WebGL 2 extensions.
+     *
+     * - clipCullDistance: set to `true` to use vertex shader clipping
+     * - multiDraw: set to `true` to use vertex shader multi_draw / enable gl_DrawID
      */
     extensions: {
         clipCullDistance: boolean;
         multiDraw: boolean;
     };
-
     /**
-     * @default { 'color': [ 1, 1, 1 ], 'uv': [ 0, 0 ], 'uv1': [ 0, 0 ] }
+     * When the rendered geometry doesn't include these attributes but the
+     * material does, these default values will be passed to the shaders. This
+     * avoids errors when buffer data is missing.
+     *
+     * - color: [ 1, 1, 1 ]
+     * - uv: [ 0, 0 ]
+     * - uv1: [ 0, 0 ]
      */
-    defaultAttributeValues: any;
-
+    defaultAttributeValues: {
+        color: [number, number, number];
+        uv: [number, number];
+        uv1: [number, number];
+    };
     /**
+     * If set, this calls [gl.bindAttribLocation]{@link https://developer.mozilla.org/en-US/docs/Web/API/WebGLRenderingContext/bindAttribLocation}
+     * to bind a generic vertex index to an attribute variable.
+     *
      * @default undefined
      */
     index0AttributeName: string | undefined;
-
     /**
+     * Can be used to force a uniform update while changing uniforms in
+     * {@link Object3D#onBeforeRender}.
+     *
      * @default false
      */
     uniformsNeedUpdate: boolean;
-
     /**
+     * Defines the GLSL version of custom shader code.
+     *
      * @default null
      */
     glslVersion: GLSLVersion | null;
+}
 
-    setValues(parameters: ShaderMaterialParameters): void;
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface ShaderMaterialParameters
+    extends Partial<MapColorPropertiesToColorRepresentations<ShaderMaterialProperties>>
+{}
 
+export type ShaderMaterialUniformJSON = {
+    type: "t";
+    value: string;
+} | {
+    type: "c";
+    value: number;
+} | {
+    type: "v2";
+    value: Vector2Tuple;
+} | {
+    type: "v3";
+    value: Vector3Tuple;
+} | {
+    type: "v4";
+    value: Vector4Tuple;
+} | {
+    type: "m3";
+    value: Matrix3Tuple;
+} | {
+    type: "m4";
+    value: Matrix4Tuple;
+} | {
+    value: unknown;
+};
+
+export interface ShaderMaterialJSON extends MaterialJSON {
+    glslVersion: number | null;
+    uniforms: Record<string, ShaderMaterialUniformJSON>;
+
+    defines?: Record<string, unknown>;
+
+    vertexShader: string;
+    fragmentShader: string;
+
+    lights: boolean;
+    clipping: boolean;
+
+    extensions?: Record<string, boolean>;
+}
+
+/**
+ * A material rendered with custom shaders. A shader is a small program written in GLSL.
+ * that runs on the GPU. You may want to use a custom shader if you need to implement an
+ * effect not included with any of the built-in materials.
+ *
+ * There are the following notes to bear in mind when using a `ShaderMaterial`:
+ *
+ * - `ShaderMaterial` can only be used with {@link WebGLRenderer}.
+ * - Built in attributes and uniforms are passed to the shaders along with your code. If
+ * you don't want that, use {@link RawShaderMaterial} instead.
+ * - You can use the directive `#pragma unroll_loop_start` and `#pragma unroll_loop_end`
+ * in order to unroll a `for` loop in GLSL by the shader preprocessor. The directive has
+ * to be placed right above the loop. The loop formatting has to correspond to a defined standard.
+ *   - The loop has to be [normalized]{@link https://en.wikipedia.org/wiki/Normalized_loop}.
+ *   - The loop variable has to be *i*.
+ *   - The value `UNROLLED_LOOP_INDEX` will be replaced with the explicitly
+ * value of *i* for the given iteration and can be used in preprocessor
+ * statements.
+ *
+ * ```js
+ * const material = new THREE.ShaderMaterial( {
+ * 	uniforms: {
+ * 		time: { value: 1.0 },
+ * 		resolution: { value: new THREE.Vector2() }
+ * 	},
+ * 	vertexShader: document.getElementById( 'vertexShader' ).textContent,
+ * 	fragmentShader: document.getElementById( 'fragmentShader' ).textContent
+ * } );
+ * ```
+ */
+export class ShaderMaterial extends Material {
+    /**
+     * Constructs a new shader material.
+     *
+     * @param {Object} [parameters] - An object with one or more properties
+     * defining the material's appearance. Any property of the material
+     * (including any property from inherited materials) can be passed
+     * in here. Color values can be passed any type of value accepted
+     * by {@link Color#set}.
+     */
+    constructor(parameters?: ShaderMaterialParameters);
+    /**
+     * This flag can be used for type testing.
+     *
+     * @default true
+     */
+    readonly isShaderMaterial: boolean;
     toJSON(meta?: JSONMeta): ShaderMaterialJSON;
 }
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface ShaderMaterial extends ShaderMaterialProperties {}

three/src/materials/ShadowMaterial.d.ts

@@ -1,34 +1,60 @@
-import { Color, ColorRepresentation } from "../math/Color.js";
-import { Material, MaterialParameters } from "./Material.js";
-
-export interface ShadowMaterialParameters extends MaterialParameters {
-    color?: ColorRepresentation | undefined;
-    fog?: boolean | undefined;
-}
-
-export class ShadowMaterial extends Material {
-    constructor(parameters?: ShadowMaterialParameters);
+import { Color } from "../math/Color.js";
+import { MapColorPropertiesToColorRepresentations, Material, MaterialProperties } from "./Material.js";
 
+export interface ShadowMaterialProperties extends MaterialProperties {
     /**
-     * Read-only flag to check if a given object is of type {@link ShadowMaterial}.
-     * @remarks This is a _constant_ value
-     * @defaultValue `true`
-     */
-    readonly isShadowMaterial: true;
-
-    /**
-     * @default new THREE.Color( 0x000000 )
+     * Color of the material.
+     *
+     * @default (0,0,0)
      */
     color: Color;
-
     /**
+     * Whether the material is affected by fog or not.
+     *
      * @default true
      */
-    transparent: boolean;
+    fog: boolean;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface ShadowMaterialParameters
+    extends Partial<MapColorPropertiesToColorRepresentations<ShadowMaterialProperties>>
+{}
 
+/**
+ * This material can receive shadows, but otherwise is completely transparent.
+ *
+ * ```js
+ * const geometry = new THREE.PlaneGeometry( 2000, 2000 );
+ * geometry.rotateX( - Math.PI / 2 );
+ *
+ * const material = new THREE.ShadowMaterial();
+ * material.opacity = 0.2;
+ *
+ * const plane = new THREE.Mesh( geometry, material );
+ * plane.position.y = -200;
+ * plane.receiveShadow = true;
+ * scene.add( plane );
+ * ```
+ */
+export class ShadowMaterial extends Material {
     /**
-     * Whether the material is affected by fog. Default is true.
-     * @default fog
+     * Constructs a new shadow material.
+     *
+     * @param {Object} [parameters] - An object with one or more properties
+     * defining the material's appearance. Any property of the material
+     * (including any property from inherited materials) can be passed
+     * in here. Color values can be passed any type of value accepted
+     * by {@link Color#set}.
      */
-    fog: boolean;
+    constructor(parameters?: ShadowMaterialParameters);
+    /**
+     * This flag can be used for type testing.
+     *
+     * @default true
+     */
+    readonly isShadowMaterial: boolean;
 }
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface ShadowMaterial extends ShadowMaterialProperties {}