From 2381d22c98f0fb8f3ce5ec764236b2919788e11d Mon Sep 17 00:00:00 2001 From: Michael Herzog Date: Thu, 23 Apr 2026 13:50:24 +0200 Subject: [PATCH] Docs: Improve `displacementMap` JSDoc. (#33453) --- src/materials/MeshLambertMaterial.js | 4 +++- src/materials/MeshMatcapMaterial.js | 4 +++- src/materials/MeshNormalMaterial.js | 4 +++- src/materials/MeshPhongMaterial.js | 4 +++- src/materials/MeshStandardMaterial.js | 4 +++- src/materials/MeshToonMaterial.js | 4 +++- 6 files changed, 18 insertions(+), 6 deletions(-) diff --git a/src/materials/MeshLambertMaterial.js b/src/materials/MeshLambertMaterial.js index f44e8f1ee84b99..9635b0f5e2fac5 100644 --- a/src/materials/MeshLambertMaterial.js +++ b/src/materials/MeshLambertMaterial.js @@ -181,7 +181,9 @@ class MeshLambertMaterial extends Material { * 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. * * @type {?Texture} * @default null diff --git a/src/materials/MeshMatcapMaterial.js b/src/materials/MeshMatcapMaterial.js index f580ff81bf21bf..0677bbd75f2b2b 100644 --- a/src/materials/MeshMatcapMaterial.js +++ b/src/materials/MeshMatcapMaterial.js @@ -123,7 +123,9 @@ class MeshMatcapMaterial extends Material { * 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. * * @type {?Texture} * @default null diff --git a/src/materials/MeshNormalMaterial.js b/src/materials/MeshNormalMaterial.js index e4a4e2fe188fec..39ca898278b24d 100644 --- a/src/materials/MeshNormalMaterial.js +++ b/src/materials/MeshNormalMaterial.js @@ -88,7 +88,9 @@ class MeshNormalMaterial extends Material { * 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. * * @type {?Texture} * @default null diff --git a/src/materials/MeshPhongMaterial.js b/src/materials/MeshPhongMaterial.js index 8a26209e2d0499..fc4b0f1dcb6ba3 100644 --- a/src/materials/MeshPhongMaterial.js +++ b/src/materials/MeshPhongMaterial.js @@ -196,7 +196,9 @@ class MeshPhongMaterial extends Material { * 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. * * @type {?Texture} * @default null diff --git a/src/materials/MeshStandardMaterial.js b/src/materials/MeshStandardMaterial.js index 4c4ac44ff8b818..2bf8485a66f088 100644 --- a/src/materials/MeshStandardMaterial.js +++ b/src/materials/MeshStandardMaterial.js @@ -221,7 +221,9 @@ class MeshStandardMaterial extends Material { * 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. * * @type {?Texture} * @default null diff --git a/src/materials/MeshToonMaterial.js b/src/materials/MeshToonMaterial.js index 72ec94dc3010a3..ac6570e0508e05 100644 --- a/src/materials/MeshToonMaterial.js +++ b/src/materials/MeshToonMaterial.js @@ -181,7 +181,9 @@ class MeshToonMaterial extends Material { * 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. * * @type {?Texture} * @default null