@types/three 0.177.0 → 0.178.1

three/src/materials/MeshBasicMaterial.d.ts

@@ -1,134 +1,173 @@
 import { Combine } from "../constants.js";
-import { Color, ColorRepresentation } from "../math/Color.js";
+import { Color } from "../math/Color.js";
 import { Euler } from "../math/Euler.js";
 import { Texture } from "../textures/Texture.js";
-import { Material, MaterialParameters } from "./Material.js";
-
-/**
- * parameters is an object with one or more properties defining the material's appearance.
- */
-export interface MeshBasicMaterialParameters extends MaterialParameters {
-    color?: ColorRepresentation | undefined;
-    opacity?: number | undefined;
-    map?: Texture | null | undefined;
-    lightMap?: Texture | null;
-    lightMapIntensity?: number | undefined;
-    aoMap?: Texture | null | undefined;
-    aoMapIntensity?: number | undefined;
-    specularMap?: Texture | null | undefined;
-    alphaMap?: Texture | null | undefined;
-    fog?: boolean | undefined;
-    envMap?: Texture | null | undefined;
-    envMapRotation?: Euler | undefined;
-    combine?: Combine | undefined;
-    reflectivity?: number | undefined;
-    refractionRatio?: number | undefined;
-    wireframe?: boolean | undefined;
-    wireframeLinewidth?: number | undefined;
-    wireframeLinecap?: string | undefined;
-    wireframeLinejoin?: string | undefined;
-}
-
-export class MeshBasicMaterial extends Material {
-    constructor(parameters?: MeshBasicMaterialParameters);
-
-    /**
-     * Read-only flag to check if a given object is of type {@link MeshBasicMaterial}.
-     * @remarks This is a _constant_ value
-     * @defaultValue `true`
-     */
-    readonly isMeshBasicMaterial: true;
+import { MapColorPropertiesToColorRepresentations, Material, MaterialProperties } from "./Material.js";
 
+export interface MeshBasicMaterialProperties 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 light map. Requires a second set of UVs.
+     *
      * @default null
      */
     lightMap: Texture | null;
-
     /**
+     * Intensity of the baked light.
+     *
      * @default 1
      */
     lightMapIntensity: number;
-
     /**
+     * The red channel of this texture is used as the ambient occlusion map.
+     * Requires a second set of UVs.
+     *
      * @default null
      */
     aoMap: Texture | null;
-
     /**
+     * Intensity of the ambient occlusion effect. Range is `[0,1]`, where `0`
+     * disables ambient occlusion. Where intensity is `1` and the AO map's
+     * red channel is also `1`, ambient light is fully occluded on a surface.
+     *
      * @default 1
      */
     aoMapIntensity: number;
-
     /**
+     * Specular map used by the material.
+     *
      * @default null
      */
     specularMap: 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;
-
     /**
+     * The environment map.
+     *
      * @default null
      */
     envMap: Texture | null;
-
     /**
-     * The rotation of the environment map in radians. Default is `(0,0,0)`.
+     * The rotation of the environment map in radians.
+     *
+     * @default (0,0,0)
      */
     envMapRotation: Euler;
-
     /**
-     * @default THREE.MultiplyOperation
+     * How to combine the result of the surface's color with the environment map, if any.
+     *
+     * When set to `MixOperation`, the {@link MeshBasicMaterial#reflectivity} is used to
+     * blend between the two colors.
+     *
+     * @default MultiplyOperation
      */
     combine: Combine;
-
     /**
+     * How much the environment map affects the surface.
+     * The valid range is between `0` (no reflections) and `1` (full reflections).
+     *
      * @default 1
      */
     reflectivity: number;
-
     /**
+     * The index of refraction (IOR) of air (approximately 1) divided by the
+     * index of refraction of the material. It is used with environment mapping
+     * modes {@link CubeRefractionMapping} and {@link EquirectangularRefractionMapping}.
+     * The refraction ratio should not exceed `1`.
+     *
      * @default 0.98
      */
     refractionRatio: number;
-
     /**
+     * Renders the geometry as a wireframe.
+     *
      * @default false
      */
     wireframe: boolean;
-
     /**
+     * Controls the thickness of the wireframe.
+     *
+     * Can only be used with {@link SVGRenderer}.
+     *
      * @default 1
      */
     wireframeLinewidth: number;
-
     /**
+     * Defines appearance of wireframe ends.
+     *
+     * Can only be used with {@link SVGRenderer}.
+     *
      * @default 'round'
      */
-    wireframeLinecap: string;
-
+    wireframeLinecap: "round" | "bevel" | "miter";
     /**
+     * Defines appearance of wireframe joints.
+     *
+     * Can only be used with {@link SVGRenderer}.
+     *
      * @default 'round'
      */
-    wireframeLinejoin: string;
-
+    wireframeLinejoin: "round" | "bevel" | "miter";
     /**
-     * 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;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface MeshBasicMaterialParameters
+    extends Partial<MapColorPropertiesToColorRepresentations<MeshBasicMaterialProperties>>
+{}
 
-    setValues(parameters: MeshBasicMaterialParameters): void;
+/**
+ * A material for drawing geometries in a simple shaded (flat or wireframe) way.
+ *
+ * This material is not affected by lights.
+ */
+export class MeshBasicMaterial extends Material {
+    /**
+     * Constructs a new mesh basic 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?: MeshBasicMaterialParameters);
+    /**
+     * This flag can be used for type testing.
+     *
+     * @default true
+     */
+    readonly isMeshBasicMaterial: boolean;
 }
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface MeshBasicMaterial extends MeshBasicMaterialProperties {}

three/src/materials/MeshDepthMaterial.d.ts

@@ -1,66 +1,105 @@
 import { DepthPackingStrategies } from "../constants.js";
 import { Texture } from "../textures/Texture.js";
-import { Material, MaterialParameters } from "./Material.js";
+import { MapColorPropertiesToColorRepresentations, Material, MaterialProperties } from "./Material.js";
 
-export interface MeshDepthMaterialParameters extends MaterialParameters {
-    map?: Texture | null | undefined;
-    alphaMap?: Texture | null | undefined;
-    depthPacking?: DepthPackingStrategies | undefined;
-    displacementMap?: Texture | null | undefined;
-    displacementScale?: number | undefined;
-    displacementBias?: number | undefined;
-    wireframe?: boolean | undefined;
-    wireframeLinewidth?: number | undefined;
-}
-
-export class MeshDepthMaterial extends Material {
-    constructor(parameters?: MeshDepthMaterialParameters);
+export interface MeshDepthMaterialProperties extends MaterialProperties {
     /**
-     * Read-only flag to check if a given object is of type {@link MeshDepthMaterial}.
-     * @remarks This is a _constant_ value
-     * @defaultValue `true`
+     * Type for depth packing.
+     *
+     * @default BasicDepthPacking
      */
-    readonly isMeshDepthMaterial: true;
-
+    depthPacking: DepthPackingStrategies;
     /**
+     * The color map. May optionally include an alpha channel, typically combined
+     * with {@link Material#transparent} or {@link Material#alphaTest}.
+     *
      * @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;
-
-    /**
-     * @default THREE.BasicDepthPacking
-     */
-    depthPacking: DepthPackingStrategies;
-
     /**
+     * The displacement map affects the position of the mesh's vertices. Unlike
+     * other maps which only affect the light and shade of the material the
+     * displaced vertices can cast shadows, block other objects, and otherwise
+     * act as real geometry. The displacement texture is an image where the value
+     * of each pixel (white being the highest) is mapped against, and
+     * repositions, the vertices of the mesh.
+     *
      * @default null
      */
     displacementMap: Texture | null;
-
     /**
-     * @default 1
+     * How much the displacement map affects the mesh (where black is no
+     * displacement, and white is maximum displacement). Without a displacement
+     * map set, this value is not applied.
+     *
+     * @default 0
      */
     displacementScale: number;
-
     /**
+     * The offset of the displacement map's values on the mesh's vertices.
+     * The bias is added to the scaled sample of the displacement map.
+     * Without a displacement map set, this value is not applied.
+     *
      * @default 0
      */
     displacementBias: 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;
+}
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface MeshDepthMaterialParameters
+    extends Partial<MapColorPropertiesToColorRepresentations<MeshDepthMaterialProperties>>
+{}
 
-    setValues(parameters: MeshDepthMaterialParameters): void;
+/**
+ * A material for drawing geometry by depth. Depth is based off of the camera
+ * near and far plane. White is nearest, black is farthest.
+ */
+export class MeshDepthMaterial extends Material {
+    /**
+     * Constructs a new mesh depth 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?: MeshDepthMaterialParameters);
+    /**
+     * This flag can be used for type testing.
+     *
+     * @default true
+     */
+    readonly isMeshDepthMaterial: boolean;
 }
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface MeshDepthMaterial extends MeshDepthMaterialProperties {}

three/src/materials/MeshDistanceMaterial.d.ts

@@ -1,52 +1,88 @@
-import { Vector3 } from "../math/Vector3.js";
 import { Texture } from "../textures/Texture.js";
-import { Material, MaterialParameters } from "./Material.js";
-
-export interface MeshDistanceMaterialParameters extends MaterialParameters {
-    map?: Texture | null | undefined;
-    alphaMap?: Texture | null | undefined;
-    displacementMap?: Texture | null | undefined;
-    displacementScale?: number | undefined;
-    displacementBias?: number | undefined;
-    farDistance?: number | undefined;
-    nearDistance?: number | undefined;
-    referencePosition?: Vector3 | undefined;
-}
-
-export class MeshDistanceMaterial extends Material {
-    constructor(parameters?: MeshDistanceMaterialParameters);
-
-    /**
-     * Read-only flag to check if a given object is of type {@link MeshDistanceMaterial}.
-     * @remarks This is a _constant_ value
-     * @defaultValue `true`
-     */
-    readonly isMeshDistanceMaterial: true;
+import { MapColorPropertiesToColorRepresentations, Material, MaterialProperties } from "./Material.js";
 
+export interface MeshDistanceMaterialProperties extends MaterialProperties {
     /**
+     * The color map. May optionally include an alpha channel, typically combined
+     * with {@link Material#transparent} or {@link Material#alphaTest}.
+     *
      * @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;
-
     /**
+     * The displacement map affects the position of the mesh's vertices. Unlike
+     * other maps which only affect the light and shade of the material the
+     * displaced vertices can cast shadows, block other objects, and otherwise
+     * act as real geometry. The displacement texture is an image where the value
+     * of each pixel (white being the highest) is mapped against, and
+     * repositions, the vertices of the mesh.
+     *
      * @default null
      */
     displacementMap: Texture | null;
-
     /**
-     * @default 1
+     * How much the displacement map affects the mesh (where black is no
+     * displacement, and white is maximum displacement). Without a displacement
+     * map set, this value is not applied.
+     *
+     * @default 0
      */
     displacementScale: number;
-
     /**
+     * The offset of the displacement map's values on the mesh's vertices.
+     * The bias is added to the scaled sample of the displacement map.
+     * Without a displacement map set, this value is not applied.
+     *
      * @default 0
      */
     displacementBias: number;
+}
 
-    setValues(parameters: MeshDistanceMaterialParameters): void;
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface MeshDistanceMaterialParameters
+    extends Partial<MapColorPropertiesToColorRepresentations<MeshDistanceMaterialProperties>>
+{}
+
+/**
+ * A material used internally for implementing shadow mapping with
+ * point lights.
+ *
+ * Can also be used to customize the shadow casting of an object by assigning
+ * an instance of `MeshDistanceMaterial` to {@link Object3D#customDistanceMaterial}.
+ * The following examples demonstrates this approach in order to ensure
+ * transparent parts of objects do no cast shadows.
+ */
+export class MeshDistanceMaterial extends Material {
+    /**
+     * Constructs a new mesh distance 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?: MeshDistanceMaterialParameters);
+    /**
+     * This flag can be used for type testing.
+     *
+     * @default true
+     */
+    readonly isMeshDistanceMaterial: boolean;
 }
+
+// eslint-disable-next-line @typescript-eslint/no-empty-interface
+export interface MeshDistanceMaterial extends MeshDistanceMaterialProperties {}