@needle-tools/three 0.169.20 → 0.183.2-canary.0

package/examples/jsm/objects/Sky.js

@@ -8,21 +8,32 @@ 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](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
+ * @three_import import { Sky } from 'three/addons/objects/Sky.js';
+ */
 class Sky extends Mesh {
 
+	/**
+	 * Constructs a new skydome.
+	 */
 	constructor() {
 
 		const shader = Sky.SkyShader;
@@ -38,6 +49,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;
 
 	}
@@ -54,7 +72,13 @@ Sky.SkyShader = {
 		'mieCoefficient': { value: 0.005 },
 		'mieDirectionalG': { value: 0.8 },
 		'sunPosition': { value: new Vector3() },
-		'up': { value: new Vector3( 0, 1, 0 ) }
+		'up': { value: new Vector3( 0, 1, 0 ) },
+		'cloudScale': { value: 0.0002 },
+		'cloudSpeed': { value: 0.0001 },
+		'cloudCoverage': { value: 0.4 },
+		'cloudDensity': { value: 0.4 },
+		'cloudElevation': { value: 0.5 },
+		'time': { value: 0.0 }
 	},
 
 	vertexShader: /* glsl */`
@@ -77,7 +101,7 @@ Sky.SkyShader = {
 
 		// wavelength of used primaries, according to preetham
 		const vec3 lambda = vec3( 680E-9, 550E-9, 450E-9 );
-		// this pre-calcuation replaces older TotalRayleigh(vec3 lambda) function:
+		// this pre-calculation replaces older TotalRayleigh(vec3 lambda) function:
 		// (8.0 * pow(pi, 3.0) * pow(pow(n, 2.0) - 1.0, 2.0) * (6.0 + 3.0 * pn)) / (3.0 * N * pow(lambda, vec3(4.0)) * (6.0 - 7.0 * pn))
 		const vec3 totalRayleigh = vec3( 5.804542996261093E-6, 1.3562911419845635E-5, 3.0265902468824876E-5 );
 
@@ -120,7 +144,7 @@ Sky.SkyShader = {
 
 			float rayleighCoefficient = rayleigh - ( 1.0 * ( 1.0 - vSunfade ) );
 
-			// extinction (absorbtion + out scattering)
+			// extinction (absorption + out scattering)
 			// rayleigh coefficients
 			vBetaR = totalRayleigh * rayleighCoefficient;
 
@@ -132,13 +156,45 @@ Sky.SkyShader = {
 	fragmentShader: /* glsl */`
 		varying vec3 vWorldPosition;
 		varying vec3 vSunDirection;
-		varying float vSunfade;
 		varying vec3 vBetaR;
 		varying vec3 vBetaM;
 		varying float vSunE;
 
 		uniform float mieDirectionalG;
 		uniform vec3 up;
+		uniform float cloudScale;
+		uniform float cloudSpeed;
+		uniform float cloudCoverage;
+		uniform float cloudDensity;
+		uniform float cloudElevation;
+		uniform float time;
+
+		// Cloud noise functions
+		float hash( vec2 p ) {
+			return fract( sin( dot( p, vec2( 127.1, 311.7 ) ) ) * 43758.5453123 );
+		}
+
+		float noise( vec2 p ) {
+			vec2 i = floor( p );
+			vec2 f = fract( p );
+			f = f * f * ( 3.0 - 2.0 * f );
+			float a = hash( i );
+			float b = hash( i + vec2( 1.0, 0.0 ) );
+			float c = hash( i + vec2( 0.0, 1.0 ) );
+			float d = hash( i + vec2( 1.0, 1.0 ) );
+			return mix( mix( a, b, f.x ), mix( c, d, f.x ), f.y );
+		}
+
+		float fbm( vec2 p ) {
+			float value = 0.0;
+			float amplitude = 0.5;
+			for ( int i = 0; i < 5; i ++ ) {
+				value += amplitude * noise( p );
+				p *= 2.0;
+				amplitude *= 0.5;
+			}
+			return value;
+		}
 
 		// constants for atmospheric scattering
 		const float pi = 3.141592653589793238462643383279502884197169;
@@ -205,9 +261,43 @@ Sky.SkyShader = {
 
 			vec3 texColor = ( Lin + L0 ) * 0.04 + vec3( 0.0, 0.0003, 0.00075 );
 
-			vec3 retColor = pow( texColor, vec3( 1.0 / ( 1.2 + ( 1.2 * vSunfade ) ) ) );
+			// Clouds
+			if ( direction.y > 0.0 && cloudCoverage > 0.0 ) {
+
+				// Project to cloud plane (higher elevation = clouds appear lower/closer)
+				float elevation = mix( 1.0, 0.1, cloudElevation );
+				vec2 cloudUV = direction.xz / ( direction.y * elevation );
+				cloudUV *= cloudScale;
+				cloudUV += time * cloudSpeed;
+
+				// Multi-octave noise for fluffy clouds
+				float cloudNoise = fbm( cloudUV * 1000.0 );
+				cloudNoise += 0.5 * fbm( cloudUV * 2000.0 + 3.7 );
+				cloudNoise = cloudNoise * 0.5 + 0.5;
+
+				// Apply coverage threshold
+				float cloudMask = smoothstep( 1.0 - cloudCoverage, 1.0 - cloudCoverage + 0.3, cloudNoise );
+
+				// Fade clouds near horizon (adjusted by elevation)
+				float horizonFade = smoothstep( 0.0, 0.1 + 0.2 * cloudElevation, direction.y );
+				cloudMask *= horizonFade;
+
+				// Cloud lighting based on sun position
+				float sunInfluence = dot( direction, vSunDirection ) * 0.5 + 0.5;
+				float daylight = max( 0.0, vSunDirection.y * 2.0 );
+
+				// Base cloud color affected by atmosphere
+				vec3 atmosphereColor = Lin * 0.04;
+				vec3 cloudColor = mix( vec3( 0.3 ), vec3( 1.0 ), daylight );
+				cloudColor = mix( cloudColor, atmosphereColor + vec3( 1.0 ), sunInfluence * 0.5 );
+				cloudColor *= vSunE * 0.00002;
+
+				// Blend clouds with sky
+				texColor = mix( texColor, cloudColor, cloudMask * cloudDensity );
+
+			}
 
-			gl_FragColor = vec4( retColor, 1.0 );
+			gl_FragColor = vec4( texColor, 1.0 );
 
 			#include <tonemapping_fragment>
 			#include <colorspace_fragment>

package/examples/jsm/objects/SkyMesh.js

@@ -2,40 +2,146 @@ import {
 	BackSide,
 	BoxGeometry,
 	Mesh,
-	Vector3
-} from 'three';
-import { Fn, NodeMaterial, 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';
+	Vector3,
+	NodeMaterial
+} from 'three/webgpu';
+
+import { Fn, float, vec2, vec3, acos, add, mul, clamp, cos, dot, exp, max, mix, modelViewProjection, normalize, positionWorld, pow, smoothstep, sub, varyingProperty, vec4, uniform, cameraPosition, fract, floor, sin, time, Loop, If } 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](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 WebGPURenderer}.
+ * When using {@link WebGLRenderer}, use {@link Sky}.
  *
- * 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
+ * @three_import import { SkyMesh } from 'three/addons/objects/SkyMesh.js';
+ */
 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.isSky = true;
+		/**
+		 * The cloud scale uniform.
+		 *
+		 * @type {UniformNode<float>}
+		 */
+		this.cloudScale = uniform( 0.0002 );
+
+		/**
+		 * The cloud speed uniform.
+		 *
+		 * @type {UniformNode<float>}
+		 */
+		this.cloudSpeed = uniform( 0.0001 );
+
+		/**
+		 * The cloud coverage uniform.
+		 *
+		 * @type {UniformNode<float>}
+		 */
+		this.cloudCoverage = uniform( 0.4 );
+
+		/**
+		 * The cloud density uniform.
+		 *
+		 * @type {UniformNode<float>}
+		 */
+		this.cloudDensity = uniform( 0.4 );
+
+		/**
+		 * The cloud elevation uniform.
+		 *
+		 * @type {UniformNode<float>}
+		 */
+		this.cloudElevation = uniform( 0.5 );
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 * @deprecated Use isSkyMesh instead.
+		 */
+		this.isSky = true; // @deprecated, r182
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isSkyMesh = true;
+
+		// Varyings
+
+		const vSunDirection = varyingProperty( 'vec3' );
+		const vSunE = varyingProperty( 'float' );
+		const vBetaR = varyingProperty( 'vec3' );
+		const vBetaM = varyingProperty( 'vec3' );
 
 		const vertexNode = /*@__PURE__*/ Fn( () => {
 
@@ -45,7 +151,7 @@ class SkyMesh extends Mesh {
 
 			// wavelength of used primaries, according to preetham
 			// const lambda = vec3( 680E-9, 550E-9, 450E-9 );
-			// this pre-calcuation replaces older TotalRayleigh(vec3 lambda) function:
+			// this pre-calculation replaces older TotalRayleigh(vec3 lambda) function:
 			// (8.0 * pow(pi, 3.0) * pow(pow(n, 2.0) - 1.0, 2.0) * (6.0 + 3.0 * pn)) / (3.0 * N * pow(lambda, vec3(4.0)) * (6.0 - 7.0 * pn))
 			const totalRayleigh = vec3( 5.804542996261093E-6, 1.3562911419845635E-5, 3.0265902468824876E-5 );
 
@@ -64,52 +170,45 @@ class SkyMesh extends Mesh {
 
 			// varying sun position
 
-			const vSunDirection = normalize( this.sunPosition );
-			varyingProperty( 'vec3', 'vSunDirection' ).assign( vSunDirection );
+			const sunDirection = normalize( this.sunPosition );
+			vSunDirection.assign( sunDirection );
 
 			// varying sun intensity
 
-			const angle = dot( vSunDirection, this.upUniform );
+			const angle = dot( sunDirection, this.upUniform );
 			const zenithAngleCos = clamp( angle, - 1, 1 );
 			const sunIntensity = EE.mul( max( 0.0, float( 1.0 ).sub( pow( e, cutoffAngle.sub( acos( zenithAngleCos ) ).div( steepness ).negate() ) ) ) );
-			varyingProperty( 'float', 'vSunE' ).assign( sunIntensity );
+			vSunE.assign( sunIntensity );
 
-			// varying sun fade
+			// sun fade
 
-			const vSunfade = float( 1.0 ).sub( clamp( float( 1.0 ).sub( exp( this.sunPosition.y.div( 450000.0 ) ) ), 0, 1 ) );
-			varyingProperty( 'float', 'vSunfade' ).assign( vSunfade );
+			const sunfade = float( 1.0 ).sub( clamp( float( 1.0 ).sub( exp( this.sunPosition.y.div( 450000.0 ) ) ), 0, 1 ) );
 
 			// varying vBetaR
 
-			const rayleighCoefficient = this.rayleigh.sub( float( 1.0 ).mul( float( 1.0 ).sub( vSunfade ) ) );
+			const rayleighCoefficient = this.rayleigh.sub( float( 1.0 ).mul( float( 1.0 ).sub( sunfade ) ) );
 
-			// extinction (absorbtion + out scattering)
+			// extinction (absorption + out scattering)
 			// rayleigh coefficients
-			varyingProperty( 'vec3', 'vBetaR' ).assign( totalRayleigh.mul( rayleighCoefficient ) );
+			vBetaR.assign( totalRayleigh.mul( rayleighCoefficient ) );
 
 			// varying vBetaM
 
 			const c = float( 0.2 ).mul( this.turbidity ).mul( 10E-18 );
 			const totalMie = float( 0.434 ).mul( c ).mul( MieConst );
 
-			varyingProperty( 'vec3', 'vBetaM' ).assign( totalMie.mul( this.mieCoefficient ) );
+			vBetaM.assign( totalMie.mul( this.mieCoefficient ) );
 
 			// position
 
-			const position = modelViewProjection();
+			const position = modelViewProjection;
 			position.z.assign( position.w ); // set z to camera.far
 
 			return position;
 
 		} )();
 
-		const fragmentNode = /*@__PURE__*/ Fn( () => {
-
-			const vSunDirection = varying( vec3(), 'vSunDirection' );
-			const vSunE = varying( float(), 'vSunE' );
-			const vSunfade = varying( float(), 'vSunfade' );
-			const vBetaR = varying( vec3(), 'vBetaR' );
-			const vBetaM = varying( vec3(), 'vBetaM' );
+		const colorNode = /*@__PURE__*/ Fn( () => {
 
 			// constants for atmospheric scattering
 			const pi = float( 3.141592653589793238462643383279502884197169 );
@@ -166,11 +265,85 @@ class SkyMesh extends Mesh {
 			const sundisk = smoothstep( sunAngularDiameterCos, sunAngularDiameterCos.add( 0.00002 ), cosTheta );
 			L0.addAssign( vSunE.mul( 19000.0 ).mul( Fex ).mul( sundisk ) );
 
-			const texColor = add( Lin, L0 ).mul( 0.04 ).add( vec3( 0.0, 0.0003, 0.00075 ) );
+			const texColor = add( Lin, L0 ).mul( 0.04 ).add( vec3( 0.0, 0.0003, 0.00075 ) ).toVar();
+
+			// Cloud noise functions
+			const hash = Fn( ( [ p ] ) => {
+
+				return fract( sin( dot( p, vec2( 127.1, 311.7 ) ) ).mul( 43758.5453123 ) );
+
+			} );
+
+			const noise = Fn( ( [ p_immutable ] ) => {
+
+				const p = vec2( p_immutable ).toVar();
+				const i = floor( p );
+				const f = fract( p );
+				const ff = f.mul( f ).mul( sub( 3.0, f.mul( 2.0 ) ) );
+
+				const a = hash( i );
+				const b = hash( add( i, vec2( 1.0, 0.0 ) ) );
+				const c = hash( add( i, vec2( 0.0, 1.0 ) ) );
+				const d = hash( add( i, vec2( 1.0, 1.0 ) ) );
+
+				return mix( mix( a, b, ff.x ), mix( c, d, ff.x ), ff.y );
+
+			} );
+
+			const fbm = Fn( ( [ p_immutable ] ) => {
+
+				const p = vec2( p_immutable ).toVar();
+				const value = float( 0.0 ).toVar();
+				const amplitude = float( 0.5 ).toVar();
+
+				Loop( 5, () => {
+
+					value.addAssign( amplitude.mul( noise( p ) ) );
+					p.mulAssign( 2.0 );
+					amplitude.mulAssign( 0.5 );
+
+				} );
+
+				return value;
+
+			} );
+
+			// Clouds
+			If( direction.y.greaterThan( 0.0 ).and( this.cloudCoverage.greaterThan( 0.0 ) ), () => {
+
+				// Project to cloud plane (higher elevation = clouds appear lower/closer)
+				const elevation = mix( 1.0, 0.1, this.cloudElevation );
+				const cloudUV = direction.xz.div( direction.y.mul( elevation ) ).toVar();
+				cloudUV.mulAssign( this.cloudScale );
+				cloudUV.addAssign( time.mul( this.cloudSpeed ) );
+
+				// Multi-octave noise for fluffy clouds
+				const cloudNoise = fbm( cloudUV.mul( 1000.0 ) ).add( fbm( cloudUV.mul( 2000.0 ).add( 3.7 ) ).mul( 0.5 ) ).toVar();
+				cloudNoise.assign( cloudNoise.mul( 0.5 ).add( 0.5 ) );
+
+				// Apply coverage threshold
+				const cloudMask = smoothstep( sub( 1.0, this.cloudCoverage ), sub( 1.0, this.cloudCoverage ).add( 0.3 ), cloudNoise ).toVar();
+
+				// Fade clouds near horizon (adjusted by elevation)
+				const horizonFade = smoothstep( 0.0, add( 0.1, mul( 0.2, this.cloudElevation ) ), direction.y );
+				cloudMask.mulAssign( horizonFade );
+
+				// Cloud lighting based on sun position
+				const sunInfluence = dot( direction, vSunDirection ).mul( 0.5 ).add( 0.5 );
+				const daylight = max( 0.0, vSunDirection.y.mul( 2.0 ) );
+
+				// Base cloud color affected by atmosphere
+				const atmosphereColor = Lin.mul( 0.04 );
+				const cloudColor = mix( vec3( 0.3 ), vec3( 1.0 ), daylight ).toVar();
+				cloudColor.assign( mix( cloudColor, atmosphereColor.add( vec3( 1.0 ) ), sunInfluence.mul( 0.5 ) ) );
+				cloudColor.mulAssign( vSunE.mul( 0.00002 ) );
+
+				// Blend clouds with sky
+				texColor.assign( mix( texColor, cloudColor, cloudMask.mul( this.cloudDensity ) ) );
 
-			const retColor = pow( texColor, vec3( float( 1.0 ).div( float( 1.2 ).add( vSunfade.mul( 1.2 ) ) ) ) );
+			} );
 
-			return vec4( retColor, 1.0 );
+			return vec4( texColor, 1.0 );
 
 		} )();
 
@@ -178,7 +351,7 @@ class SkyMesh extends Mesh {
 		material.depthWrite = false;
 
 		material.vertexNode = vertexNode;
-		material.fragmentNode = fragmentNode;
+		material.colorNode = colorNode;
 
 	}
 

package/examples/jsm/objects/Water.js

@@ -1,6 +1,7 @@
 import {
 	Color,
 	FrontSide,
+	HalfFloatType,
 	Matrix4,
 	Mesh,
 	PerspectiveCamera,
@@ -14,18 +15,39 @@ 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](https://github.com/Slayvin)
+ * - [An implementation of water shader based on the flat mirror](https://home.adelphi.edu/~stemkoski/)
+ * - [Water shader explanations in WebGL](http://29a.ch/slides/2012/webglwater/ )
+ *
+ * @augments Mesh
+ * @three_import import { Water } from 'three/addons/objects/Water.js';
  */
-
 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;
@@ -63,7 +85,7 @@ class Water extends Mesh {
 
 		const mirrorCamera = new PerspectiveCamera();
 
-		const renderTarget = new WebGLRenderTarget( textureWidth, textureHeight );
+		const renderTarget = new WebGLRenderTarget( textureWidth, textureHeight, { type: HalfFloatType } );
 
 		const mirrorShader = {
 
@@ -175,10 +197,10 @@ class Water extends Mesh {
 					vec3 reflectionSample = vec3( texture2D( mirrorSampler, mirrorCoord.xy / mirrorCoord.w + distortion ) );
 
 					float theta = max( dot( eyeDirection, surfaceNormal ), 0.0 );
-					float rf0 = 0.3;
+					float rf0 = 0.02;
 					float reflectance = rf0 + ( 1.0 - rf0 ) * pow( ( 1.0 - theta ), 5.0 );
 					vec3 scatter = max( 0.0, dot( surfaceNormal, eyeDirection ) ) * waterColor;
-					vec3 albedo = mix( ( sunColor * diffuseLight * 0.3 + scatter ) * getShadowMask(), ( vec3( 0.1 ) + reflectionSample * 0.9 + reflectionSample * specularLight ), reflectance);
+					vec3 albedo = mix( ( sunColor * diffuseLight * 0.3 + scatter ) * getShadowMask(), reflectionSample + specularLight, reflectance );
 					vec3 outgoingLight = albedo;
 					gl_FragColor = vec4( outgoingLight, alpha );
 
@@ -330,4 +352,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 };