Docs: More JSDoc. (#30675)

examples/jsm/objects/GroundedSkybox.js

@@ -1,14 +1,32 @@
 import { Mesh, MeshBasicMaterial, SphereGeometry, Vector3 } from 'three';
 
 /**
- * A ground-projected skybox. The height is how far the camera that took the photo was above the ground -
- * a larger value will magnify the downward part of the image. By default the object is centered at the camera,
- * so it is often helpful to set skybox.position.y = height to put the ground at the origin. Set the radius
- * large enough to ensure your user's camera stays inside.
+ * A ground-projected skybox.
+ *
+ * By default the object is centered at the camera, so it is often helpful to set
+ * `skybox.position.y = height` to put the ground at the origin.
+ *
+ * ```js
+ * const height = 15, radius = 100;
+ *
+ * const skybox = new GroundedSkybox( envMap, height, radius );
+ * skybox.position.y = height;
+ * scene.add( skybox );
+ * ```
+ *
+ * @augments Mesh
  */
-
 class GroundedSkybox extends Mesh {
 
+	/**
+	 * Constructs a new ground-projected skybox.
+	 *
+	 * @param {Texture} map - The environment map to use.
+	 * @param {number} height - The height is how far the camera that took the photo was above the ground.
+	 * A larger value will magnify the downward part of the image.
+	 * @param {number} radius - The radius of the skybox. Must be large enough to ensure the scene's camera stays inside.
+	 * @param {number} [resolution=128] - The geometrix resolution of the skybox.
+	 */
 	constructor( map, height, radius, resolution = 128 ) {
 
 		if ( height <= 0 || radius <= 0 || resolution <= 0 ) {

examples/jsm/objects/Lensflare.js

@@ -15,16 +15,59 @@ import {
 	Vector4
 } from 'three';
 
+/**
+ * Creates a simulated lens flare that tracks a light.
+ *
+ * Note that this class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, use {@link LensflareMesh}.
+ *
+ * ```js
+ * const light = new THREE.PointLight( 0xffffff, 1.5, 2000 );
+ *
+ * const lensflare = new Lensflare();
+ * lensflare.addElement( new LensflareElement( textureFlare0, 512, 0 ) );
+ * lensflare.addElement( new LensflareElement( textureFlare1, 512, 0 ) );
+ * lensflare.addElement( new LensflareElement( textureFlare2, 60, 0.6 ) );
+ *
+ * light.add( lensflare );
+ * ```
+ *
+ * @augments Mesh
+ */
 class Lensflare extends Mesh {
 
+	/**
+	 * Constructs a new lensflare.
+	 */
 	constructor() {
 
 		super( Lensflare.Geometry, new MeshBasicMaterial( { opacity: 0, transparent: true } ) );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLensflare = true;
 
 		this.type = 'Lensflare';
+
+		/**
+		 * Overwritten to disable view-frustum culling by default.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.frustumCulled = false;
+
+		/**
+		 * Overwritten to make sure lensflares a rendered last.
+		 *
+		 * @type {number}
+		 * @default Infinity
+		 */
 		this.renderOrder = Infinity;
 
 		//
@@ -149,6 +192,11 @@ class Lensflare extends Mesh {
 
 		const mesh2 = new Mesh( geometry, material2 );
 
+		/**
+		 * Adds the given lensflare element to this instance.
+		 *
+		 * @param {LensflareElement} element - The element to add.
+		 */
 		this.addElement = function ( element ) {
 
 			elements.push( element );
@@ -263,6 +311,10 @@ class Lensflare extends Mesh {
 
 		};
 
+		/**
+		 * Frees the GPU-related resources allocated by this instance. Call this
+		 * method whenever this instance is no longer used in your app.
+		 */
 		this.dispose = function () {
 
 			material1a.dispose();
@@ -284,15 +336,52 @@ class Lensflare extends Mesh {
 
 }
 
-//
-
+/**
+ * Represents a single flare that can be added to a {@link Lensflare} container.
+ */
 class LensflareElement {
 
+	/**
+	 * Constructs a new lensflare element.
+	 *
+	 * @param {Texture} texture - The flare's texture.
+	 * @param {number} [size=1] - The size in pixels.
+	 * @param {number} [distance=0] - The normalized distance (`[0,1]`) from the light source.
+	 * A value of `0` means the flare is located at light source.
+	 * @param {Color} [color] - The flare's color
+	 */
 	constructor( texture, size = 1, distance = 0, color = new Color( 0xffffff ) ) {
 
+		/**
+		 * The flare's texture.
+		 *
+		 * @type {Texture}
+		 */
 		this.texture = texture;
+
+		/**
+		 * The size in pixels.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.size = size;
+
+		/**
+		 * The normalized distance (`[0,1]`) from the light source.
+		 * A value of `0` means the flare is located at light source.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
 		this.distance = distance;
+
+		/**
+		 * The flare's color
+		 *
+		 * @type {Color}
+		 * @default (1,1,1)
+		 */
 		this.color = color;
 
 	}

examples/jsm/objects/LensflareMesh.js

@@ -18,16 +18,59 @@ import {
 
 import { texture, textureLoad, uv, ivec2, vec2, vec4, positionGeometry, reference, varyingProperty, materialReference, Fn } from 'three/tsl';
 
+/**
+ * Creates a simulated lens flare that tracks a light.
+ *
+ * Note that this class can only be used with {@link WebGPURenderer}.
+ * When using {@link WebGLRenderer}, use {@link Lensflare}.
+ *
+ * ```js
+ * const light = new THREE.PointLight( 0xffffff, 1.5, 2000 );
+ *
+ * const lensflare = new LensflareMesh();
+ * lensflare.addElement( new LensflareElement( textureFlare0, 512, 0 ) );
+ * lensflare.addElement( new LensflareElement( textureFlare1, 512, 0 ) );
+ * lensflare.addElement( new LensflareElement( textureFlare2, 60, 0.6 ) );
+ *
+ * light.add( lensflare );
+ * ```
+ *
+ * @augments Mesh
+ */
 class LensflareMesh extends Mesh {
 
+	/**
+	 * Constructs a new lensflare mesh.
+	 */
 	constructor() {
 
 		super( LensflareMesh.Geometry, new MeshBasicNodeMaterial( { opacity: 0, transparent: true } ) );
 
-		this.isLensflare = true;
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isLensflareMesh = true;
 
 		this.type = 'LensflareMesh';
+
+		/**
+		 * Overwritten to disable view-frustum culling by default.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.frustumCulled = false;
+
+		/**
+		 * Overwritten to make sure lensflares a rendered last.
+		 *
+		 * @type {number}
+		 * @default Infinity
+		 */
 		this.renderOrder = Infinity;
 
 		//
@@ -146,7 +189,11 @@ class LensflareMesh extends Mesh {
 
 		} )();
 
-
+		/**
+		 * Adds the given lensflare element to this instance.
+		 *
+		 * @param {LensflareElement} element - The element to add.
+		 */
 		this.addElement = function ( element ) {
 
 			elements.push( element );
@@ -264,6 +311,10 @@ class LensflareMesh extends Mesh {
 
 		};
 
+		/**
+		 * Frees the GPU-related resources allocated by this instance. Call this
+		 * method whenever this instance is no longer used in your app.
+		 */
 		this.dispose = function () {
 
 			material1a.dispose();

examples/jsm/objects/MarchingCubes.js

@@ -9,17 +9,34 @@ import {
 } from 'three';
 
 /**
- * Port of http://webglsamples.org/blob/blob.html
+ * A marching cubes implementation.
+ *
+ * Port of: {@link http://webglsamples.org/blob/blob.html}
  */
-
 class MarchingCubes extends Mesh {
 
+	/**
+	 * Constructs a new marching cubes instance.
+	 *
+	 * @param {number} resolution - The effect's resolution.
+	 * @param {Material} material - The cube's material.
+	 * @param {boolean} [enableUvs=false] - Whether texture coordinates should be animated or not.
+	 * @param {boolean} [enableColors=false] - Whether colors should be animated or not.
+	 * @param {boolean} [maxPolyCount=10000] - The maximum size of the geometry buffers.
+	 */
 	constructor( resolution, material, enableUvs = false, enableColors = false, maxPolyCount = 10000 ) {
 
 		const geometry = new BufferGeometry();
 
 		super( geometry, material );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isMarchingCubes = true;
 
 		const scope = this;
@@ -30,7 +47,20 @@ class MarchingCubes extends Mesh {
 		const nlist = new Float32Array( 12 * 3 );
 		const clist = new Float32Array( 12 * 3 );
 
+		/**
+		 * Whether texture coordinates should be animated or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.enableUvs = enableUvs;
+
+		/**
+		 * Whether colors should be animated or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.enableColors = enableColors;
 
 		// functions have to be object properties
@@ -495,9 +525,17 @@ class MarchingCubes extends Mesh {
 		// Metaballs
 		/////////////////////////////////////
 
-		// Adds a reciprocal ball (nice and blobby) that, to be fast, fades to zero after
-		// a fixed distance, determined by strength and subtract.
-
+		/**
+		 * Adds a reciprocal ball (nice and blobby) that, to be fast, fades to zero after
+		 * a fixed distance, determined by strength and subtract.
+		 *
+		 * @param {number} ballx - The x-coordinate of the ball.
+		 * @param {number} bally - The y-coordinate of the ball.
+		 * @param {number} ballz - The z-coordinate of the ball.
+		 * @param {number} strength - The strength factor.
+		 * @param {number} subtract - The subtract factor.
+		 * @param {Color} colors - The color.
+		 */
 		this.addBall = function ( ballx, bally, ballz, strength, subtract, colors ) {
 
 			const sign = Math.sign( strength );
@@ -598,6 +636,12 @@ class MarchingCubes extends Mesh {
 
 		};
 
+		/**
+		 * Adds a plane along the x-axis.
+		 *
+		 * @param {number} strength - The strength factor.
+		 * @param {number} subtract - The subtract factor.
+		 */
 		this.addPlaneX = function ( strength, subtract ) {
 
 			// cache attribute lookups
@@ -643,6 +687,12 @@ class MarchingCubes extends Mesh {
 
 		};
 
+		/**
+		 * Adds a plane along the y-axis.
+		 *
+		 * @param {number} strength - The strength factor.
+		 * @param {number} subtract - The subtract factor.
+		 */
 		this.addPlaneY = function ( strength, subtract ) {
 
 			// cache attribute lookups
@@ -687,6 +737,12 @@ class MarchingCubes extends Mesh {
 
 		};
 
+		/**
+		 * Adds a plane along the z-axis.
+		 *
+		 * @param {number} strength - The strength factor.
+		 * @param {number} subtract - The subtract factor.
+		 */
 		this.addPlaneZ = function ( strength, subtract ) {
 
 			// cache attribute lookups
@@ -735,6 +791,14 @@ class MarchingCubes extends Mesh {
 		// Updates
 		/////////////////////////////////////
 
+		/**
+		 * Sets the cell value for the given coordinates.
+		 *
+		 * @param {number} x - The x value.
+		 * @param {number} y - The y value.
+		 * @param {number} z - The z value.
+		 * @param {number} value - The value to set.
+		 */
 		this.setCell = function ( x, y, z, value ) {
 
 			const index = this.size2 * z + this.size * y + x;
@@ -742,6 +806,14 @@ class MarchingCubes extends Mesh {
 
 		};
 
+		/**
+		 * Returns the cell value for the given coordinates.
+		 *
+		 * @param {number} x - The x value.
+		 * @param {number} y - The y value.
+		 * @param {number} z - The z value.
+		 * @return {number} The value.
+		 */
 		this.getCell = function ( x, y, z ) {
 
 			const index = this.size2 * z + this.size * y + x;
@@ -749,6 +821,11 @@ class MarchingCubes extends Mesh {
 
 		};
 
+		/**
+		 * Applies a blur with the given intensity.
+		 *
+		 * @param {number} [intensity=1] - The intensity of the blur.
+		 */
 		this.blur = function ( intensity = 1 ) {
 
 			const field = this.field;
@@ -802,6 +879,9 @@ class MarchingCubes extends Mesh {
 
 		};
 
+		/**
+		 * Resets the effect.
+		 */
 		this.reset = function () {
 
 			// wipe the normal cache
@@ -818,6 +898,9 @@ class MarchingCubes extends Mesh {
 
 		};
 
+		/**
+		 * Updates the effect.
+		 */
 		this.update = function () {
 
 			this.count = 0;

examples/jsm/objects/Reflector.js

@@ -12,16 +12,65 @@ import {
 	HalfFloatType
 } from 'three';
 
+/**
+ * Can be used to create a flat, reflective surface like a mirror.
+ *
+ * Note that this class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, use {@link ReflectorNode}.
+ *
+ * ```js
+ * const geometry = new THREE.PlaneGeometry( 100, 100 );
+ *
+ * const reflector = new Reflector( geometry, {
+ * 	clipBias: 0.003,
+ * 	textureWidth: window.innerWidth * window.devicePixelRatio,
+ * 	textureHeight: window.innerHeight * window.devicePixelRatio,
+ * 	color: 0xc1cbcb
+ * } );
+ *
+ * scene.add( reflector );
+ * ```
+ *
+ * @augments Mesh
+ */
 class Reflector extends Mesh {
 
+	/**
+	 * Constructs a new reflector.
+	 *
+	 * @param {BufferGeometry} geometry - The reflector's geometry.
+	 * @param {Reflector~Options} [options] - The configuration options.
+	 */
 	constructor( geometry, options = {} ) {
 
 		super( geometry );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isReflector = true;
 
 		this.type = 'Reflector';
+
+		/**
+		 * Whether to force an update, no matter if the reflector
+		 * is in view or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.forceUpdate = false;
+
+		/**
+		 * The reflector's virtual camera. This is used to render
+		 * the scene from the mirror's point of view.
+		 *
+		 * @type {PerspectiveCamera}
+		 */
 		this.camera = new PerspectiveCamera();
 
 		const scope = this;
@@ -178,12 +227,21 @@ class Reflector extends Mesh {
 
 		};
 
+		/**
+		 * Returns the reflector's internal render target.
+		 *
+		 * @return {WebGLRenderTarget} The internal render target
+		 */
 		this.getRenderTarget = function () {
 
 			return renderTarget;
 
 		};
 
+		/**
+		 * Frees the GPU-related resources allocated by this instance. Call this
+		 * method whenever this instance is no longer used in your app.
+		 */
 		this.dispose = function () {
 
 			renderTarget.dispose();
@@ -264,4 +322,16 @@ Reflector.ReflectorShader = {
 		}`
 };
 
+/**
+ * Constructor options of `Reflector`.
+ *
+ * @typedef {Object} Reflector~Options
+ * @property {number|Color|string} [color=0x7F7F7F] - The reflector's color.
+ * @property {number} [textureWidth=512] - The texture width. A higher value results in more clear reflections but is also more expensive.
+ * @property {number} [textureHeight=512] - The texture height. A higher value results in more clear reflections but is also more expensive.
+ * @property {number} [clipBias=0] - The clip bias.
+ * @property {Object} [shader] - Can be used to pass in a custom shader that defines how the reflective view is projected onto the reflector's geometry.
+ * @property {number} [multisample=4] - How many samples to use for MSAA. `0` disables MSAA.
+ **/
+
 export { Reflector };

examples/jsm/objects/ReflectorForSSRPass.js

@@ -15,8 +15,19 @@ import {
 	HalfFloatType
 } from 'three';
 
+/**
+ * A special version of {@link Reflector} for usage with {@link SSRPass}.
+ *
+ * @augments Mesh
+ */
 class ReflectorForSSRPass extends Mesh {
 
+	/**
+	 * Constructs a new reflector.
+	 *
+	 * @param {BufferGeometry} geometry - The reflector's geometry.
+	 * @param {ReflectorForSSRPass~Options} [options] - The configuration options.
+	 */
 	constructor( geometry, options = {} ) {
 
 		super( geometry );
@@ -240,12 +251,28 @@ class ReflectorForSSRPass extends Mesh {
 
 		};
 
+		/**
+		 * Returns the reflector's internal render target.
+		 *
+		 * @return {WebGLRenderTarget} The internal render target
+		 */
 		this.getRenderTarget = function () {
 
 			return renderTarget;
 
 		};
 
+		/**
+		 * Frees the GPU-related resources allocated by this instance. Call this
+		 * method whenever this instance is no longer used in your app.
+		 */
+		this.dispose = function () {
+
+			renderTarget.dispose();
+			scope.material.dispose();
+
+		};
+
 	}
 
 }
@@ -349,4 +376,16 @@ ReflectorForSSRPass.ReflectorShader = {
 	`,
 };
 
+/**
+ * Constructor options of `ReflectorForSSRPass`.
+ *
+ * @typedef {Object} ReflectorForSSRPass~Options
+ * @property {number|Color|string} [color=0x7F7F7F] - The reflector's color.
+ * @property {number} [textureWidth=512] - The texture width. A higher value results in more clear reflections but is also more expensive.
+ * @property {number} [textureHeight=512] - The texture height. A higher value results in more clear reflections but is also more expensive.
+ * @property {number} [clipBias=0] - The clip bias.
+ * @property {Object} [shader] - Can be used to pass in a custom shader that defines how the reflective view is projected onto the reflector's geometry.
+ * @property {boolean} [useDepthTexture=true] - Whether to store depth values in a texture or not.
+ **/
+
 export { ReflectorForSSRPass };

examples/jsm/objects/Refractor.js

@@ -13,15 +13,55 @@ import {
 	HalfFloatType
 } from 'three';
 
+/**
+ * Can be used to create a flat, refractive surface like for special
+ * windows or water effects.
+ *
+ * Note that this class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, use {@link viewportSharedTexture}.
+ *
+ * ```js
+ * const geometry = new THREE.PlaneGeometry( 100, 100 );
+ *
+ * const refractor = new Refractor( refractorGeometry, {
+ * 	color: 0xcbcbcb,
+ * 	textureWidth: 1024,
+ * 	textureHeight: 1024
+ * } );
+ *
+ * scene.add( refractor );
+ * ```
+ *
+ * @augments Mesh
+ */
 class Refractor extends Mesh {
 
+	/**
+	 * Constructs a new refractor.
+	 *
+	 * @param {BufferGeometry} geometry - The refractor's geometry.
+	 * @param {Refractor~Options} [options] - The configuration options.
+	 */
 	constructor( geometry, options = {} ) {
 
 		super( geometry );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isRefractor = true;
 
 		this.type = 'Refractor';
+
+		/**
+		 * The reflector's virtual camera.
+		 *
+		 * @type {PerspectiveCamera}
+		 */
 		this.camera = new PerspectiveCamera();
 
 		const scope = this;
@@ -243,12 +283,21 @@ class Refractor extends Mesh {
 
 		};
 
+		/**
+		 * Returns the reflector's internal render target.
+		 *
+		 * @return {WebGLRenderTarget} The internal render target
+		 */
 		this.getRenderTarget = function () {
 
 			return renderTarget;
 
 		};
 
+		/**
+		 * Frees the GPU-related resources allocated by this instance. Call this
+		 * method whenever this instance is no longer used in your app.
+		 */
 		this.dispose = function () {
 
 			renderTarget.dispose();
@@ -324,4 +373,16 @@ Refractor.RefractorShader = {
 
 };
 
+/**
+ * Constructor options of `Refractor`.
+ *
+ * @typedef {Object} Refractor~Options
+ * @property {number|Color|string} [color=0x7F7F7F] - The refractor's color.
+ * @property {number} [textureWidth=512] - The texture width. A higher value results in more clear refractions but is also more expensive.
+ * @property {number} [textureHeight=512] - The texture height. A higher value results in more clear refractions but is also more expensive.
+ * @property {number} [clipBias=0] - The clip bias.
+ * @property {Object} [shader] - Can be used to pass in a custom shader that defines how the refractive view is projected onto the reflector's geometry.
+ * @property {number} [multisample=4] - How many samples to use for MSAA. `0` disables MSAA.
+ **/
+
 export { Refractor };

examples/jsm/objects/ShadowMesh.js

@@ -6,14 +6,31 @@ import {
 	IncrementStencilOp
 } from 'three';
 
-/**
- * A shadow Mesh that follows a shadow-casting Mesh in the scene, but is confined to a single plane.
- */
-
 const _shadowMatrix = new Matrix4();
 
+/**
+ * A Shadow Mesh that follows a shadow-casting mesh in the scene,
+ * but is confined to a single plane. This technique can be used as
+ * a very performant alternative to classic shadow mapping. However,
+ * it has serious limitations like:
+ *
+ * - Shadows can only be casted on flat planes.
+ * - No soft shadows support.
+ *
+ * ```js
+ * const cubeShadow = new ShadowMesh( cube );
+ * scene.add( cubeShadow );
+ * ```
+ *
+ * @augments Mesh
+ */
 class ShadowMesh extends Mesh {
 
+	/**
+	 * Constructs a new shadw mesh.
+	 *
+	 * @param {Mesh} mesh - The shadow-casting reference mesh.
+	 */
 	constructor( mesh ) {
 
 		const shadowMaterial = new MeshBasicMaterial( {
@@ -31,15 +48,47 @@ class ShadowMesh extends Mesh {
 
 		super( mesh.geometry, shadowMaterial );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isShadowMesh = true;
 
+		/**
+		 * Represent the world matrix of the reference mesh.
+		 *
+		 * @type {Matrix4}
+		 */
 		this.meshMatrix = mesh.matrixWorld;
 
+		/**
+		 * Overwritten to disable view-frustum culling by default.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.frustumCulled = false;
+
+		/**
+		 * Overwritten to disable automatic matrix update. The local
+		 * matrix is computed manually in {@link ShadowMesh#update}.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.matrixAutoUpdate = false;
 
 	}
 
+	/**
+	 * Updates the shadow mesh so it follows its shadow-casting reference mesh.
+	 *
+	 * @param {Plane} plane - The plane onto the shadow mesh is projected.
+	 * @param {Vector4} lightPosition4D - The light position.
+	 */
 	update( plane, lightPosition4D ) {
 
 		// based on https://www.opengl.org/archives/resources/features/StencilTalk/tsld021.htm

examples/jsm/objects/Sky.js

@@ -8,21 +8,31 @@ import {
 } from 'three';
 
 /**
- * Based on "A Practical Analytic Model for Daylight"
- * aka The Preetham Model, the de facto standard analytic skydome model
- * https://www.researchgate.net/publication/220720443_A_Practical_Analytic_Model_for_Daylight
+ * Represents a skydome for scene backgrounds. Based on [A Practical Analytic Model for Daylight]{@link https://www.researchgate.net/publication/220720443_A_Practical_Analytic_Model_for_Daylight}
+ * aka The Preetham Model, the de facto standard for analytical skydomes.
  *
- * First implemented by Simon Wallner
- * http://simonwallner.at/project/atmospheric-scattering/
+ * Note that this class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, use {@link SkyMesh}.
  *
- * Improved by Martin Upitis
- * http://blenderartists.org/forum/showthread.php?245954-preethams-sky-impementation-HDR
+ * More references:
  *
- * Three.js integration by zz85 http://twitter.com/blurspline
+ * - {@link http://simonwallner.at/project/atmospheric-scattering/}
+ * - {@link http://blenderartists.org/forum/showthread.php?245954-preethams-sky-impementation-HDR}
+ *
+ *
+ * ```js
+ * const sky = new Sky();
+ * sky.scale.setScalar( 10000 );
+ * scene.add( sky );
+ * ```
+ *
+ * @augments Mesh
 */
-
 class Sky extends Mesh {
 
+	/**
+	 * Constructs a new skydome.
+	 */
 	constructor() {
 
 		const shader = Sky.SkyShader;
@@ -38,6 +48,13 @@ class Sky extends Mesh {
 
 		super( new BoxGeometry( 1, 1, 1 ), material );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSky = true;
 
 	}

examples/jsm/objects/SkyMesh.js

@@ -9,34 +9,85 @@ import {
 import { Fn, float, vec3, acos, add, mul, clamp, cos, dot, exp, max, mix, modelViewProjection, normalize, positionWorld, pow, smoothstep, sub, varying, varyingProperty, vec4, uniform, cameraPosition } from 'three/tsl';
 
 /**
- * Based on "A Practical Analytic Model for Daylight"
- * aka The Preetham Model, the de facto standard analytic skydome model
- * https://www.researchgate.net/publication/220720443_A_Practical_Analytic_Model_for_Daylight
+ * Represents a skydome for scene backgrounds. Based on [A Practical Analytic Model for Daylight]{@link https://www.researchgate.net/publication/220720443_A_Practical_Analytic_Model_for_Daylight}
+ * aka The Preetham Model, the de facto standard for analytical skydomes.
  *
- * First implemented by Simon Wallner
- * http://simonwallner.at/project/atmospheric-scattering/
+ * Note that this class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, use {@link SkyMesh}.
  *
- * Improved by Martin Upitis
- * http://blenderartists.org/forum/showthread.php?245954-preethams-sky-impementation-HDR
+ * More references:
  *
- * Three.js integration by zz85 http://twitter.com/blurspline
+ * - {@link http://simonwallner.at/project/atmospheric-scattering/}
+ * - {@link http://blenderartists.org/forum/showthread.php?245954-preethams-sky-impementation-HDR}
+ *
+ * ```js
+ * const sky = new SkyMesh();
+ * sky.scale.setScalar( 10000 );
+ * scene.add( sky );
+ * ```
+ *
+ * @augments Mesh
 */
-
 class SkyMesh extends Mesh {
 
+	/**
+	 * Constructs a new skydome.
+	 */
 	constructor() {
 
 		const material = new NodeMaterial();
 
 		super( new BoxGeometry( 1, 1, 1 ), material );
 
+		/**
+		 * The turbidity uniform.
+		 *
+		 * @type {UniformNode<float>}
+		 */
 		this.turbidity = uniform( 2 );
+
+		/**
+		 * The rayleigh uniform.
+		 *
+		 * @type {UniformNode<float>}
+		 */
 		this.rayleigh = uniform( 1 );
+
+		/**
+		 * The mieCoefficient uniform.
+		 *
+		 * @type {UniformNode<float>}
+		 */
 		this.mieCoefficient = uniform( 0.005 );
+
+		/**
+		 * The mieDirectionalG uniform.
+		 *
+		 * @type {UniformNode<float>}
+		 */
 		this.mieDirectionalG = uniform( 0.8 );
+
+		/**
+		 * The sun position uniform.
+		 *
+		 * @type {UniformNode<vec3>}
+		 */
 		this.sunPosition = uniform( new Vector3() );
+
+		/**
+		 * The up position.
+		 *
+		 * @type {UniformNode<vec3>}
+		 */
 		this.upUniform = uniform( new Vector3( 0, 1, 0 ) );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSky = true;
 
 		const vertexNode = /*@__PURE__*/ Fn( () => {

examples/jsm/objects/Water.js

@@ -14,18 +14,38 @@ import {
 } from 'three';
 
 /**
- * Work based on :
- * https://github.com/Slayvin: Flat mirror for three.js
- * https://home.adelphi.edu/~stemkoski/ : An implementation of water shader based on the flat mirror
- * http://29a.ch/ && http://29a.ch/slides/2012/webglwater/ : Water shader explanations in WebGL
+ * A basic flat, reflective water effect.
+ *
+ * Note that this class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, use {@link WaterMesh}.
+ *
+ * References:
+ *
+ * - [Flat mirror for three.js]{@link https://github.com/Slayvin}
+ * - [An implementation of water shader based on the flat mirror]{@link https://home.adelphi.edu/~stemkoski/}
+ * - [Water shader explanations in WebGL]{@link http://29a.ch/slides/2012/webglwater/ }
+ *
+ * @augments Mesh
  */
-
 class Water extends Mesh {
 
+	/**
+	 * Constructs a new water instance.
+	 *
+	 * @param {BufferGeometry} geometry - The water's geometry.
+	 * @param {Water~Options} [options] - The configuration options.
+	 */
 	constructor( geometry, options = {} ) {
 
 		super( geometry );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isWater = true;
 
 		const scope = this;
@@ -330,4 +350,23 @@ class Water extends Mesh {
 
 }
 
+/**
+ * Constructor options of `Water`.
+ *
+ * @typedef {Object} Water~Options
+ * @property {number} [textureWidth=512] - The texture width. A higher value results in more clear reflections but is also more expensive.
+ * @property {number} [textureHeight=512] - The texture height. A higher value results in more clear reflections but is also more expensive.
+ * @property {number} [clipBias=0] - The clip bias.
+ * @property {number} [alpha=1] - The alpha value.
+ * @property {number} [time=0] - The time value.
+ * @property {?Texture} [waterNormals=null] - The water's normal map.
+ * @property {Vector3} [sunDirection=(0.70707,0.70707,0.0)] - The sun direction.
+ * @property {number|Color|string} [sunColor=0xffffff] - The sun color.
+ * @property {number|Color|string} [waterColor=0x7F7F7F] - The water color.
+ * @property {Vector3} [eye] - The eye vector.
+ * @property {number} [distortionScale=20] - The distortion scale.
+ * @property {(FrontSide|BackSide|DoubleSide)} [side=FrontSide] - The water material's `side` property.
+ * @property {boolean} [fog=false] - Whether the water should be affected by fog or not.
+ **/
+
 export { Water };

examples/jsm/objects/Water2.js

@@ -14,19 +14,40 @@ import {
 import { Reflector } from '../objects/Reflector.js';
 import { Refractor } from '../objects/Refractor.js';
 
+/** @module Water2 */
+
 /**
+ * An advanced water effect that supports reflections, refractions and flow maps.
+ *
+ * Note that this class can only be used with {@link WebGLRenderer}.
+ * When using {@link WebGPURenderer}, use {@link module:Water2Mesh}.
+ *
  * References:
- *	https://alex.vlachos.com/graphics/Vlachos-SIGGRAPH10-WaterFlow.pdf
- *	http://graphicsrunner.blogspot.de/2010/08/water-using-flow-maps.html
  *
+ * - {@link https://alex.vlachos.com/graphics/Vlachos-SIGGRAPH10-WaterFlow.pdf}
+ * - {@link http://graphicsrunner.blogspot.de/2010/08/water-using-flow-maps.html}
+ *
+ * @augments Mesh
  */
-
 class Water extends Mesh {
 
+	/**
+	 * Constructs a new water instance.
+	 *
+	 * @param {BufferGeometry} geometry - The water's geometry.
+	 * @param {module:Water2~Options} [options] - The configuration options.
+	 */
 	constructor( geometry, options = {} ) {
 
 		super( geometry );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isWater = true;
 
 		this.type = 'Water';
@@ -358,4 +379,22 @@ Water.WaterShader = {
 
 };
 
+/**
+ * Constructor options of `Water`.
+ *
+ * @typedef {Object} module:Water2~Options
+ * @property {number|Color|string} [color=0xFFFFFF] - The water color.
+ * @property {number} [textureWidth=512] - The texture width. A higher value results in better quality but is also more expensive.
+ * @property {number} [textureHeight=512] - The texture height. A higher value results in better quality but is also more expensive.
+ * @property {number} [clipBias=0] - The clip bias.
+ * @property {Vector2} [flowDirection=(1,0)] - The water's flow direction.
+ * @property {number} [flowSpeed=0.03] - The water's flow speed.
+ * @property {number} [reflectivity=0.02] - The water's reflectivity.
+ * @property {number} [scale=1] - The water's scale.
+ * @property {Object} [shader] - A custom water shader.
+ * @property {?Texture} [flowMap=null] - The flow map. If no flow map is assigned, the water flow is defined by `flowDirection`.
+ * @property {?Texture} [normalMap0] - The first water normal map.
+ * @property {?Texture} [normalMap1] -  The second water normal map.
+ **/
+
 export { Water };

examples/jsm/objects/Water2Mesh.js

@@ -10,21 +10,42 @@ import {
 
 import { Fn, vec2, viewportSafeUV, viewportSharedTexture, reflector, pow, float, abs, texture, uniform, vec4, cameraPosition, positionWorld, uv, mix, vec3, normalize, max, dot, screenUV } from 'three/tsl';
 
+/** @module Water2Mesh */
+
 /**
+ * An advanced water effect that supports reflections, refractions and flow maps.
+ *
+ * Note that this class can only be used with {@link WebGPURenderer}.
+ * When using {@link WebGLRenderer}, use {@link module:Water2}.
+ *
  * References:
- *	https://alex.vlachos.com/graphics/Vlachos-SIGGRAPH10-WaterFlow.pdf
- *	http://graphicsrunner.blogspot.de/2010/08/water-using-flow-maps.html
  *
+ * - {@link https://alex.vlachos.com/graphics/Vlachos-SIGGRAPH10-WaterFlow.pdf}
+ * - {@link http://graphicsrunner.blogspot.de/2010/08/water-using-flow-maps.html}
+ *
+ * @augments Mesh
  */
-
 class WaterMesh extends Mesh {
 
+	/**
+	 * Constructs a new water mesh.
+	 *
+	 * @param {BufferGeometry} geometry - The water's geometry.
+	 * @param {module:Water2~Options} [options] - The configuration options.
+	 */
 	constructor( geometry, options = {} ) {
 
 		const material = new NodeMaterial();
 
 		super( geometry, material );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isWater = true;
 
 		material.fragmentNode = new WaterNode( options, this );
@@ -159,4 +180,18 @@ class WaterNode extends TempNode {
 
 }
 
+/**
+ * Constructor options of `WaterMesh`.
+ *
+ * @typedef {Object} module:Water2Mesh~Options
+ * @property {number|Color|string} [color=0xFFFFFF] - The water color.
+ * @property {Vector2} [flowDirection=(1,0)] - The water's flow direction.
+ * @property {number} [flowSpeed=0.03] - The water's flow speed.
+ * @property {number} [reflectivity=0.02] - The water's reflectivity.
+ * @property {number} [scale=1] - The water's scale.
+ * @property {?Texture} [flowMap=null] - The flow map. If no flow map is assigned, the water flow is defined by `flowDirection`.
+ * @property {Texture} normalMap0 - The first water normal map.
+ * @property {Texture} normalMap1 - The second water normal map.
+ **/
+
 export { WaterMesh };

examples/jsm/objects/WaterMesh.js

@@ -8,32 +8,105 @@ import {
 import { Fn, add, cameraPosition, div, normalize, positionWorld, sub, time, texture, vec2, vec3, max, dot, reflect, pow, length, float, uniform, reflector, mul, mix, diffuseColor } from 'three/tsl';
 
 /**
- * Work based on :
- * https://github.com/Slayvin: Flat mirror for three.js
- * https://home.adelphi.edu/~stemkoski/ : An implementation of water shader based on the flat mirror
- * http://29a.ch/ && http://29a.ch/slides/2012/webglwater/ : Water shader explanations in WebGL
+ * A basic flat, reflective water effect.
+ *
+ * Note that this class can only be used with {@link WebGPURenderer}.
+ * When using {@link WebGLRenderer}, use {@link Water}.
+ *
+ * References:
+ *
+ * - [Flat mirror for three.js]{@link https://github.com/Slayvin}
+ * - [An implementation of water shader based on the flat mirror]{@link https://home.adelphi.edu/~stemkoski/}
+ * - [Water shader explanations in WebGL]{@link http://29a.ch/slides/2012/webglwater/ }
+ *
+ * @augments Mesh
  */
-
 class WaterMesh extends Mesh {
 
+	/**
+	 * Constructs a new water mesh.
+	 *
+	 * @param {BufferGeometry} geometry - The water mesh's geometry.
+	 * @param {WaterMesh~Options} [options] - The configuration options.
+	 */
 	constructor( geometry, options ) {
 
 		const material = new MeshLambertNodeMaterial();
 
 		super( geometry, material );
 
-		this.isWater = true;
-
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isWaterMesh = true;
+
+		/**
+		 * The effect's resolution scale.
+		 *
+		 * @type {number}
+		 * @default 0.5
+		 */
 		this.resolution = options.resolution !== undefined ? options.resolution : 0.5;
 
 		// Uniforms
 
+		/**
+		 * The water's normal map.
+		 *
+		 * @type {TextureNode}
+		 */
 		this.waterNormals = texture( options.waterNormals );
+
+		/**
+		 * The alpha value.
+		 *
+		 * @type {UniformNode<float>}
+		 * @default 1
+		 */
 		this.alpha = uniform( options.alpha !== undefined ? options.alpha : 1.0 );
+
+		/**
+		 * The size value.
+		 *
+		 * @type {UniformNode<float>}
+		 * @default 1
+		 */
 		this.size = uniform( options.size !== undefined ? options.size : 1.0 );
+
+		/**
+		 * The sun color.
+		 *
+		 * @type {UniformNode<color>}
+		 * @default 0xffffff
+		 */
 		this.sunColor = uniform( new Color( options.sunColor !== undefined ? options.sunColor : 0xffffff ) );
+
+		/**
+		 * The sun direction.
+		 *
+		 * @type {UniformNode<vec3>}
+		 * @default (0.70707,0.70707,0.0)
+		 */
 		this.sunDirection = uniform( options.sunDirection !== undefined ? options.sunDirection : new Vector3( 0.70707, 0.70707, 0.0 ) );
+
+		/**
+		 * The water color.
+		 *
+		 * @type {UniformNode<color>}
+		 * @default 0x7f7f7f
+		 */
 		this.waterColor = uniform( new Color( options.waterColor !== undefined ? options.waterColor : 0x7f7f7f ) );
+
+		/**
+		 * The distortion scale.
+		 *
+		 * @type {UniformNode<float>}
+		 * @default 20
+		 */
 		this.distortionScale = uniform( options.distortionScale !== undefined ? options.distortionScale : 20.0 );
 
 		// TSL
@@ -105,4 +178,18 @@ class WaterMesh extends Mesh {
 
 }
 
+/**
+ * Constructor options of `WaterMesh`.
+ *
+ * @typedef {Object} WaterMesh~Options
+ * @property {number} [resolution=0.5] - The resolution scale.
+ * @property {?Texture} [waterNormals=null] - The water's normal map.
+ * @property {number} [alpha=1] - The alpha value.
+ * @property {number} [size=1] - The size value.
+ * @property {number|Color|string} [sunColor=0xffffff] - The sun color.
+ * @property {Vector3} [sunDirection=(0.70707,0.70707,0.0)] - The sun direction.
+ * @property {number|Color|string} [waterColor=0x7F7F7F] - The water color.
+ * @property {number} [distortionScale=20] - The distortion scale.
+ **/
+
 export { WaterMesh };

utils/docs/jsdoc.config.json

@@ -29,6 +29,7 @@
             "examples/jsm/materials",
             "examples/jsm/math",
             "examples/jsm/modifiers",
+            "examples/jsm/objects",
             "examples/jsm/renderers",
             "examples/jsm/textures",
             "examples/jsm/tsl",
@@ -40,7 +41,9 @@
             "examples/jsm/helpers/TextureHelperGPU.js",
             "examples/jsm/lines/webgpu",
             "examples/jsm/materials/LDrawConditionalLineNodeMaterial.js",
-            "examples/jsm/modifiers/CurveModifierGPU.js"
+            "examples/jsm/modifiers/CurveModifierGPU.js",
+            "examples/jsm/objects/Water2.js",
+            "examples/jsm/objects/Water2Mesh.js"
         ]
     }
 }