@types/three 0.184.0 → 0.185.0

three/src/extras/core/ShapePath.d.ts

@@ -4,95 +4,91 @@ import { Path } from "./Path.js";
 import { Shape } from "./Shape.js";
 
 /**
- * This class is used to convert a series of shapes to an array of {@link THREE.Path | Path's},
- * for example an SVG shape to a path.
- * @see {@link https://threejs.org/docs/index.html#api/en/extras/core/ShapePath | Official Documentation}
- * @see {@link https://github.com/mrdoob/three.js/blob/master/src/extras/core/ShapePath.js | Source}
+ * This class is used to convert a series of paths to an array of
+ * shapes. It is specifically used in context of fonts and SVG.
  */
 export class ShapePath {
+    type: string;
     /**
-     * Creates a new {@link ShapePath}
-     * @remarks
-     * Unlike a {@link THREE.Path | Path}, no points are passed in as the {@link ShapePath} is designed to be generated after creation.
+     * The color of the shape.
+     *
+     * @type {Color}
      */
-    constructor();
-
-    /**
-     * A Read-only _string_ to check if `this` object type.
-     * @remarks Sub-classes will update this value.
-     * @defaultValue `ShapePath`
-     */
-    readonly type: "ShapePath";
-
+    color: Color;
     /**
-     * Array of {@link THREE.Path | Path's}s.
-     * @defaultValue `[]`
+     * The paths that have been generated for this shape.
+     *
+     * @type {Array<Path>}
+     * @default null
      */
-    subPaths: Path[];
-
+    subPaths: Array<Path>;
     /**
-     * The current {@link THREE.Path | Path} that is being generated.
-     * @defaultValue `null`
+     * The current path that is being generated.
+     *
+     * @type {?Path}
+     * @default null
      */
-    readonly currentPath: Path | null;
-
+    currentPath: Path | null;
     /**
-     * {@link THREE.Color | Color} of the shape, by default set to white _(0xffffff)_.
-     * @defaultValue `new THREE.Color()`
+     * An object that can be used to store custom data about the shape path.
+     * Mainly used by SVGLoader to store style information.
+     *
+     * @type {Object}
      */
-    color: Color;
-
+    userData: Record<string, unknown>;
     /**
-     * Starts a new {@link THREE.Path | Path} and calls {@link THREE.Path.moveTo | Path.moveTo}( x, y ) on that {@link THREE.Path | Path}
-     * @remarks
-     * Also points {@link ShapePath.currentPath | currentPath} to that {@link THREE.Path | Path}.
-     * @param x Expects a `Float`
-     * @param y Expects a `Float`
+     * Creates a new path and moves it current point to the given one.
+     *
+     * @param {number} x - The x coordinate.
+     * @param {number} y - The y coordinate.
+     * @return {ShapePath} A reference to this shape path.
      */
     moveTo(x: number, y: number): this;
-
     /**
-     * This creates a line from the {@link ShapePath.currentPath | currentPath}'s offset to X and Y and updates the offset to X and Y.
-     * @param x Expects a `Float`
-     * @param y Expects a `Float`
+     * Adds an instance of {@link LineCurve} to the path by connecting
+     * the current point with the given one.
+     *
+     * @param {number} x - The x coordinate of the end point.
+     * @param {number} y - The y coordinate of the end point.
+     * @return {ShapePath} A reference to this shape path.
      */
     lineTo(x: number, y: number): this;
-
     /**
-     * This creates a quadratic curve from the {@link ShapePath.currentPath | currentPath}'s
-     * offset to _x_ and _y_ with _cpX_ and _cpY_ as control point and updates the {@link ShapePath.currentPath | currentPath}'s offset to _x_ and _y_.
-     * @param cpX Expects a `Float`
-     * @param cpY Expects a `Float`
-     * @param x Expects a `Float`
-     * @param y Expects a `Float`
+     * Adds an instance of {@link QuadraticBezierCurve} to the path by connecting
+     * the current point with the given one.
+     *
+     * @param {number} aCPx - The x coordinate of the control point.
+     * @param {number} aCPy - The y coordinate of the control point.
+     * @param {number} aX - The x coordinate of the end point.
+     * @param {number} aY - The y coordinate of the end point.
+     * @return {ShapePath} A reference to this shape path.
      */
     quadraticCurveTo(aCPx: number, aCPy: number, aX: number, aY: number): this;
-
     /**
-     * This creates a bezier curve from the {@link ShapePath.currentPath | currentPath}'s
-     * offset to _x_ and _y_ with _cp1X_, _cp1Y_ and _cp2X_, _cp2Y_ as control points and
-     * updates the {@link ShapePath.currentPath | currentPath}'s offset to _x_ and _y_.
-     * @param cp1X Expects a `Float`
-     * @param cp1Y Expects a `Float`
-     * @param cp2X Expects a `Float`
-     * @param cp2Y Expects a `Float`
-     * @param x Expects a `Float`
-     * @param y Expects a `Float`
+     * Adds an instance of {@link CubicBezierCurve} to the path by connecting
+     * the current point with the given one.
+     *
+     * @param {number} aCP1x - The x coordinate of the first control point.
+     * @param {number} aCP1y - The y coordinate of the first control point.
+     * @param {number} aCP2x - The x coordinate of the second control point.
+     * @param {number} aCP2y - The y coordinate of the second control point.
+     * @param {number} aX - The x coordinate of the end point.
+     * @param {number} aY - The y coordinate of the end point.
+     * @return {ShapePath} A reference to this shape path.
      */
     bezierCurveTo(aCP1x: number, aCP1y: number, aCP2x: number, aCP2y: number, aX: number, aY: number): this;
-
     /**
-     * Connects a new {@link THREE.SplineCurve | SplineCurve} onto the {@link ShapePath.currentPath | currentPath}.
-     * @param points An array of {@link THREE.Vector2 | Vector2}s
+     * Adds an instance of {@link SplineCurve} to the path by connecting
+     * the current point with the given list of points.
+     *
+     * @param {Array<Vector2>} pts - An array of points in 2D space.
+     * @return {ShapePath} A reference to this shape path.
      */
-    splineThru(pts: Vector2[]): this;
-
+    splineThru(pts: Array<Vector2>): this;
     /**
-     * Converts the {@link ShapePath.subPaths | subPaths} array into an array of Shapes
-     * @remarks
-     * By default solid shapes are defined clockwise (CW) and holes are defined counterclockwise (CCW)
-     * If isCCW is set to true, then those are flipped.
-     * @param isCCW Changes how solids and holes are generated
+     * Converts the paths into an array of shapes.
+     *
+     * @return {Array<Shape>} An array of shapes.
      */
-    toShapes(isCCW: boolean): Shape[];
+    toShapes(): Array<Shape>;
 }

three/src/loaders/DataTextureLoader.d.ts

@@ -1,14 +1,48 @@
-import { DataTexture } from "../textures/DataTexture.js";
+import {
+    ColorSpace,
+    MagnificationTextureFilter,
+    MinificationTextureFilter,
+    PixelFormat,
+    TextureDataType,
+    Wrapping,
+} from "../constants.js";
+import { TypedArray } from "../core/BufferAttribute.js";
+import { CompressedTextureMipmap } from "../textures/CompressedTexture.js";
+import { CubeTexture } from "../textures/CubeTexture.js";
+import { DataTexture, DataTextureImageData } from "../textures/DataTexture.js";
 import { Loader } from "./Loader.js";
 import { LoadingManager } from "./LoadingManager.js";
 
-export class DataTextureLoader extends Loader<DataTexture> {
+export interface DataTextureLoaderTexData {
+    image?: DataTextureImageData | undefined;
+    width?: number | undefined;
+    height?: number | undefined;
+    data?: TypedArray | undefined;
+    format?: PixelFormat | undefined;
+    type?: TextureDataType | undefined;
+    flipY?: boolean | undefined;
+    wrapS?: Wrapping | undefined;
+    wrapT?: Wrapping | undefined;
+    anisotropy?: number | undefined;
+    generateMipmaps?: boolean | undefined;
+    colorSpace?: ColorSpace | undefined;
+    magFilter?: MagnificationTextureFilter | undefined;
+    minFilter?: MinificationTextureFilter | undefined;
+    mipmaps?: CompressedTextureMipmap[] | CubeTexture[] | HTMLCanvasElement[] | undefined;
+    mipmapCount?: number | undefined;
+}
+
+export abstract class DataTextureLoader extends Loader<DataTexture> {
     constructor(manager?: LoadingManager);
 
     load(
         url: string,
-        onLoad?: (data: DataTexture, texData: object) => void,
+        onLoad?: (data: DataTexture, texData: DataTextureLoaderTexData) => void,
         onProgress?: (event: ProgressEvent) => void,
         onError?: (err: unknown) => void,
     ): DataTexture;
+
+    abstract parse(buffer: ArrayBuffer): DataTextureLoaderTexData;
+
+    createDataTexture(buffer: ArrayBuffer): DataTexture;
 }

three/src/loaders/MaterialLoader.d.ts

@@ -18,4 +18,12 @@ export class MaterialLoader extends Loader<Material> {
     createMaterialFromType(type: string): Material;
 
     static createMaterialFromType(type: string): Material;
+
+    /**
+     * Registers the given material at the internal material library.
+     *
+     * @param type The material type.
+     * @param materialClass The material class.
+     */
+    static registerMaterial(type: string, materialClass: new() => Material): void;
 }

three/src/materials/LineBasicMaterial.d.ts

@@ -13,6 +13,11 @@ export interface LineBasicMaterialProperties extends MaterialProperties {
      * Sets the color of the lines using data from a texture. The texture map
      * color is modulated by the diffuse `color`.
      *
+     * `map` represents color data, and the texture must be assigned a
+     * {@link Texture#colorSpace}. Most `map` textures set
+     * `texture.colorSpace = SRGBColorSpace`.
+     *
+     * @type {?Texture}
      * @default null
      */
     map: Texture | null;

three/src/materials/Material.d.ts

@@ -23,7 +23,7 @@ import { WebGLProgramParametersWithUniforms } from "../renderers/webgl/WebGLProg
 import { WebGLRenderer } from "../renderers/WebGLRenderer.js";
 import { Scene } from "../scenes/Scene.js";
 import { SourceJSON } from "../textures/Source.js";
-import { TextureJSON } from "../textures/Texture.js";
+import { Texture, TextureJSON } from "../textures/Texture.js";
 
 export interface MaterialProperties {
     /**
@@ -612,6 +612,14 @@ export class Material<TEventMap extends MaterialEventMap = MaterialEventMap> ext
      * @see {@link ObjectLoader#parse}
      */
     toJSON(meta?: JSONMeta): MaterialJSON;
+    /**
+     * Deserializes the material from the given JSON.
+     *
+     * @param {Object} json - The JSON holding the serialized material.
+     * @param {Object<string,Texture>} textures - A dictionary holding textures referenced by the material.
+     * @return {Material} A reference to this material.
+     */
+    fromJSON(json: MaterialJSON, textures: Record<string, Texture>): this;
     /**
      * Returns a new material with copied values from this instance.
      *

three/src/materials/MeshBasicMaterial.d.ts

@@ -16,12 +16,23 @@ export interface MeshBasicMaterialProperties extends MaterialProperties {
      * with {@link Material#transparent} or {@link Material#alphaTest}. The texture map
      * color is modulated by the diffuse `color`.
      *
+     * `map` represents color data, and the texture must be assigned a
+     * {@link Texture#colorSpace}. Most `map` textures set
+     * `texture.colorSpace = SRGBColorSpace`.
+     *
+     * @type {?Texture}
      * @default null
      */
     map: Texture | null;
     /**
      * The light map. Requires a second set of UVs.
      *
+     * `lightMap` represents pre-baked illuminance data, and the texture must be assigned
+     * a {@link Texture#colorSpace}. Most `lightMap` textures set
+     * `texture.colorSpace = LinearSRGBColorSpace` and use float-type formats
+     * such as `.exr` or `.hdr`.
+     *
+     * @type {?Texture}
      * @default null
      */
     lightMap: Texture | null;
@@ -35,6 +46,10 @@ export interface MeshBasicMaterialProperties extends MaterialProperties {
      * The red channel of this texture is used as the ambient occlusion map.
      * Requires a second set of UVs.
      *
+     * `aoMap` represents non-color data. Any texture assigned must have
+     * `texture.colorSpace = NoColorSpace` (default).
+     *
+     * @type {?Texture}
      * @default null
      */
     aoMap: Texture | null;
@@ -49,6 +64,11 @@ export interface MeshBasicMaterialProperties extends MaterialProperties {
     /**
      * Specular map used by the material.
      *
+     * `specularMap` represents color data, and the texture must be assigned a
+     * {@link Texture#colorSpace}. Most `specularMap` textures set
+     * `texture.colorSpace = SRGBColorSpace`.
+     *
+     * @type {?Texture}
      * @default null
      */
     specularMap: Texture | null;
@@ -62,12 +82,22 @@ export interface MeshBasicMaterialProperties extends MaterialProperties {
      * green in DXT-compressed and uncompressed RGB 565 formats. Luminance-only and
      * luminance/alpha textures will also still work as expected.
      *
+     * `alphaMap` represents non-color data. Any texture assigned must have
+     * `texture.colorSpace = NoColorSpace` (default).
+     *
+     * @type {?Texture}
      * @default null
      */
     alphaMap: Texture | null;
     /**
      * The environment map.
      *
+     * `envMap` represents luminance data, and the texture must be assigned
+     * a {@link Texture#colorSpace}. Most `envMap` textures set
+     * `texture.colorSpace = LinearSRGBColorSpace` and use float-type formats
+     * such as `.exr` or `.hdr`.
+     *
+     * @type {?Texture}
      * @default null
      */
     envMap: Texture | null;

three/src/materials/MeshDepthMaterial.d.ts

@@ -13,6 +13,11 @@ export interface MeshDepthMaterialProperties extends MaterialProperties {
      * The color map. May optionally include an alpha channel, typically combined
      * with {@link Material#transparent} or {@link Material#alphaTest}.
      *
+     * `map` represents color data, and the texture must be assigned a
+     * {@link Texture#colorSpace}. Most `map` textures set
+     * `texture.colorSpace = SRGBColorSpace`.
+     *
+     * @type {?Texture}
      * @default null
      */
     map: Texture | null;
@@ -26,6 +31,10 @@ export interface MeshDepthMaterialProperties extends MaterialProperties {
      * green in DXT-compressed and uncompressed RGB 565 formats. Luminance-only and
      * luminance/alpha textures will also still work as expected.
      *
+     * `alphaMap` represents non-color data. Any texture assigned must have
+     * `texture.colorSpace = NoColorSpace` (default).
+     *
+     * @type {?Texture}
      * @default null
      */
     alphaMap: Texture | null;
@@ -37,6 +46,10 @@ export interface MeshDepthMaterialProperties extends MaterialProperties {
      * of each pixel (white being the highest) is mapped against, and
      * repositions, the vertices of the mesh.
      *
+     * `displacementMap` represents non-color data. Any texture assigned must have
+     * `texture.colorSpace = NoColorSpace` (default).
+     *
+     * @type {?Texture}
      * @default null
      */
     displacementMap: Texture | null;

three/src/materials/MeshDistanceMaterial.d.ts

@@ -6,6 +6,11 @@ export interface MeshDistanceMaterialProperties extends MaterialProperties {
      * The color map. May optionally include an alpha channel, typically combined
      * with {@link Material#transparent} or {@link Material#alphaTest}.
      *
+     * `map` represents color data, and the texture must be assigned a
+     * {@link Texture#colorSpace}. Most `map` textures set
+     * `texture.colorSpace = SRGBColorSpace`.
+     *
+     * @type {?Texture}
      * @default null
      */
     map: Texture | null;
@@ -19,6 +24,10 @@ export interface MeshDistanceMaterialProperties extends MaterialProperties {
      * green in DXT-compressed and uncompressed RGB 565 formats. Luminance-only and
      * luminance/alpha textures will also still work as expected.
      *
+     * `alphaMap` represents non-color data. Any texture assigned must have
+     * `texture.colorSpace = NoColorSpace` (default).
+     *
+     * @type {?Texture}
      * @default null
      */
     alphaMap: Texture | null;
@@ -30,6 +39,10 @@ export interface MeshDistanceMaterialProperties extends MaterialProperties {
      * of each pixel (white being the highest) is mapped against, and
      * repositions, the vertices of the mesh.
      *
+     * `displacementMap` represents non-color data. Any texture assigned must have
+     * `texture.colorSpace = NoColorSpace` (default).
+     *
+     * @type {?Texture}
      * @default null
      */
     displacementMap: Texture | null;

three/src/materials/MeshLambertMaterial.d.ts

@@ -17,12 +17,23 @@ export interface MeshLambertMaterialProperties extends MaterialProperties {
      * with {@link Material#transparent} or {@link Material#alphaTest}. The texture map
      * color is modulated by the diffuse `color`.
      *
+     * `map` represents color data, and the texture must be assigned a
+     * {@link Texture#colorSpace}. Most `map` textures set
+     * `texture.colorSpace = SRGBColorSpace`.
+     *
+     * @type {?Texture}
      * @default null
      */
     map: Texture | null;
     /**
      * The light map. Requires a second set of UVs.
      *
+     * `lightMap` represents pre-baked illuminance data, and the texture must be assigned
+     * a {@link Texture#colorSpace}. Most `lightMap` textures set
+     * `texture.colorSpace = LinearSRGBColorSpace` and use float-type formats
+     * such as `.exr` or `.hdr`.
+     *
+     * @type {?Texture}
      * @default null
      */
     lightMap: Texture | null;
@@ -36,6 +47,10 @@ export interface MeshLambertMaterialProperties extends MaterialProperties {
      * The red channel of this texture is used as the ambient occlusion map.
      * Requires a second set of UVs.
      *
+     * `aoMap` represents non-color data. Any texture assigned must have
+     * `texture.colorSpace = NoColorSpace` (default).
+     *
+     * @type {?Texture}
      * @default null
      */
     aoMap: Texture | null;
@@ -65,6 +80,11 @@ export interface MeshLambertMaterialProperties extends MaterialProperties {
      * emissive color and the emissive intensity. If you have an emissive map,
      * be sure to set the emissive color to something other than black.
      *
+     * `emissiveMap` represents color data, and the texture must be assigned a
+     * {@link Texture#colorSpace}. Most `emissiveMap` textures set
+     * `texture.colorSpace = SRGBColorSpace`.
+     *
+     * @type {?Texture}
      * @default null
      */
     emissiveMap: Texture | null;
@@ -74,6 +94,10 @@ export interface MeshLambertMaterialProperties extends MaterialProperties {
      * the geometry of the object, only the lighting. If a normal map is defined
      * this will be ignored.
      *
+     * `bumpMap` represents non-color data. Any texture assigned must have
+     * `texture.colorSpace = NoColorSpace` (default).
+     *
+     * @type {?Texture}
      * @default null
      */
     bumpMap: Texture | null;
@@ -91,6 +115,10 @@ export interface MeshLambertMaterialProperties extends MaterialProperties {
      * convention, the `y` component of `normalScale` should be negated to compensate
      * for the different handedness.
      *
+     * `normalMap` represents non-color data. Any texture assigned must have
+     * `texture.colorSpace = NoColorSpace` (default).
+     *
+     * @type {?Texture}
      * @default null
      */
     normalMap: Texture | null;
@@ -112,8 +140,14 @@ export interface MeshLambertMaterialProperties extends MaterialProperties {
      * 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.
+     * repositions, the vertices of the mesh. For best results, pair a
+     * displacement map with a matching normal map, since the renderer can
+     * not recompute surface normals from the displaced vertices.
+     *
+     * `displacementMap` represents non-color data. Any texture assigned must have
+     * `texture.colorSpace = NoColorSpace` (default).
      *
+     * @type {?Texture}
      * @default null
      */
     displacementMap: Texture | null;
@@ -136,6 +170,11 @@ export interface MeshLambertMaterialProperties extends MaterialProperties {
     /**
      * Specular map used by the material.
      *
+     * `specularMap` represents color data, and the texture must be assigned a
+     * {@link Texture#colorSpace}. Most `specularMap` textures set
+     * `texture.colorSpace = SRGBColorSpace`.
+     *
+     * @type {?Texture}
      * @default null
      */
     specularMap: Texture | null;
@@ -149,12 +188,22 @@ export interface MeshLambertMaterialProperties extends MaterialProperties {
      * green in DXT-compressed and uncompressed RGB 565 formats. Luminance-only and
      * luminance/alpha textures will also still work as expected.
      *
+     * `alphaMap` represents non-color data. Any texture assigned must have
+     * `texture.colorSpace = NoColorSpace` (default).
+     *
+     * @type {?Texture}
      * @default null
      */
     alphaMap: Texture | null;
     /**
      * The environment map.
      *
+     * `envMap` represents luminance data, and the texture must be assigned
+     * a {@link Texture#colorSpace}. Most `envMap` textures set
+     * `texture.colorSpace = LinearSRGBColorSpace` and use float-type formats
+     * such as `.exr` or `.hdr`.
+     *
+     * @type {?Texture}
      * @default null
      */
     envMap: Texture | null;

three/src/materials/MeshMatcapMaterial.d.ts

@@ -14,6 +14,13 @@ export interface MeshMatcapMaterialProperties extends MaterialProperties {
     /**
      * The matcap map.
      *
+     * `matcap` represents luminance data, and the texture must be assigned
+     * a {@link Texture#colorSpace}. HDR `matcap` textures (e.g. `.exr`)
+     * typically set `texture.colorSpace = LinearSRGBColorSpace`, while LDR
+     * `matcap` textures (e.g. `.png`, `.jpg`, `.webp`) typically set
+     * `texture.colorSpace = SRGBColorSpace`.
+     *
+     * @type {?Texture}
      * @default null
      */
     matcap: Texture | null;
@@ -22,6 +29,11 @@ export interface MeshMatcapMaterialProperties extends MaterialProperties {
      * with {@link Material#transparent} or {@link Material#alphaTest}. The texture map
      * color is modulated by the diffuse `color`.
      *
+     * `map` represents color data, and the texture must be assigned a
+     * {@link Texture#colorSpace}. Most `map` textures set
+     * `texture.colorSpace = SRGBColorSpace`.
+     *
+     * @type {?Texture}
      * @default null
      */
     map: Texture | null;
@@ -31,6 +43,10 @@ export interface MeshMatcapMaterialProperties extends MaterialProperties {
      * the geometry of the object, only the lighting. If a normal map is defined
      * this will be ignored.
      *
+     * `bumpMap` represents non-color data. Any texture assigned must have
+     * `texture.colorSpace = NoColorSpace` (default).
+     *
+     * @type {?Texture}
      * @default null
      */
     bumpMap: Texture | null;
@@ -48,6 +64,10 @@ export interface MeshMatcapMaterialProperties extends MaterialProperties {
      * convention, the `y` component of `normalScale` should be negated to compensate
      * for the different handedness.
      *
+     * `normalMap` represents non-color data. Any texture assigned must have
+     * `texture.colorSpace = NoColorSpace` (default).
+     *
+     * @type {?Texture}
      * @default null
      */
     normalMap: Texture | null;
@@ -69,8 +89,14 @@ export interface MeshMatcapMaterialProperties extends MaterialProperties {
      * 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.
+     * repositions, the vertices of the mesh. For best results, pair a
+     * displacement map with a matching normal map, since the renderer can
+     * not recompute surface normals from the displaced vertices.
+     *
+     * `displacementMap` represents non-color data. Any texture assigned must have
+     * `texture.colorSpace = NoColorSpace` (default).
      *
+     * @type {?Texture}
      * @default null
      */
     displacementMap: Texture | null;
@@ -100,6 +126,10 @@ export interface MeshMatcapMaterialProperties extends MaterialProperties {
      * green in DXT-compressed and uncompressed RGB 565 formats. Luminance-only and
      * luminance/alpha textures will also still work as expected.
      *
+     * `alphaMap` represents non-color data. Any texture assigned must have
+     * `texture.colorSpace = NoColorSpace` (default).
+     *
+     * @type {?Texture}
      * @default null
      */
     alphaMap: Texture | null;

three/src/materials/MeshNormalMaterial.d.ts

@@ -10,6 +10,10 @@ export interface MeshNormalMaterialProperties extends MaterialProperties {
      * the geometry of the object, only the lighting. If a normal map is defined
      * this will be ignored.
      *
+     * `bumpMap` represents non-color data. Any texture assigned must have
+     * `texture.colorSpace = NoColorSpace` (default).
+     *
+     * @type {?Texture}
      * @default null
      */
     bumpMap: Texture | null;
@@ -27,6 +31,10 @@ export interface MeshNormalMaterialProperties extends MaterialProperties {
      * convention, the `y` component of `normalScale` should be negated to compensate
      * for the different handedness.
      *
+     * `normalMap` represents non-color data. Any texture assigned must have
+     * `texture.colorSpace = NoColorSpace` (default).
+     *
+     * @type {?Texture}
      * @default null
      */
     normalMap: Texture | null;
@@ -48,7 +56,9 @@ export interface MeshNormalMaterialProperties extends MaterialProperties {
      * 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.
+     * repositions, the vertices of the mesh. For best results, pair a
+     * displacement map with a matching normal map, since the renderer can
+     * not recompute surface normals from the displaced vertices.
      *
      * @default null
      */