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

package/examples/jsm/csm/CSM.js

@@ -11,8 +11,9 @@ import { CSMFrustum } from './CSMFrustum.js';
 import { CSMShader } from './CSMShader.js';
 
 const _cameraToLightMatrix = new Matrix4();
-const _lightSpaceFrustum = new CSMFrustum();
+const _lightSpaceFrustum = new CSMFrustum( { webGL: true } );
 const _center = new Vector3();
+const _origin = new Vector3();
 const _bbox = new Box3();
 const _uniformArray = [];
 const _logArray = [];
@@ -20,38 +21,181 @@ const _lightOrientationMatrix = new Matrix4();
 const _lightOrientationMatrixInverse = new Matrix4();
 const _up = new Vector3( 0, 1, 0 );
 
+/**
+ * An implementation of Cascade Shadow Maps (CSM).
+ *
+ * This module can only be used with {@link WebGLRenderer}. When using {@link WebGPURenderer},
+ * use {@link CSMShadowNode} instead.
+ *
+ * @three_import import { CSM } from 'three/addons/csm/CSM.js';
+ */
 export class CSM {
 
+	/**
+	 * Constructs a new CSM instance.
+	 *
+	 * @param {CSM~Data} data - The CSM data.
+	 */
 	constructor( data ) {
 
+		/**
+		 * The scene's camera.
+		 *
+		 * @type {Camera}
+		 */
 		this.camera = data.camera;
+
+		/**
+		 * The parent object, usually the scene.
+		 *
+		 * @type {Object3D}
+		 */
 		this.parent = data.parent;
+
+		/**
+		 * The number of cascades.
+		 *
+		 * @type {number}
+		 * @default 3
+		 */
 		this.cascades = data.cascades || 3;
+
+		/**
+		 * The maximum far value.
+		 *
+		 * @type {number}
+		 * @default 100000
+		 */
 		this.maxFar = data.maxFar || 100000;
+
+		/**
+		 * The frustum split mode.
+		 *
+		 * @type {('practical'|'uniform'|'logarithmic'|'custom')}
+		 * @default 'practical'
+		 */
 		this.mode = data.mode || 'practical';
+
+		/**
+		 * The shadow map size.
+		 *
+		 * @type {number}
+		 * @default 2048
+		 */
 		this.shadowMapSize = data.shadowMapSize || 2048;
+
+		/**
+		 * The shadow bias.
+		 *
+		 * @type {number}
+		 * @default 0.000001
+		 */
 		this.shadowBias = data.shadowBias || 0.000001;
+
+		/**
+		 * The light direction.
+		 *
+		 * @type {Vector3}
+		 */
 		this.lightDirection = data.lightDirection || new Vector3( 1, - 1, 1 ).normalize();
+
+		/**
+		 * The light intensity.
+		 *
+		 * @type {number}
+		 * @default 3
+		 */
 		this.lightIntensity = data.lightIntensity || 3;
+
+		/**
+		 * The light near value.
+		 *
+		 * @type {number}
+		 * @default 1
+		 */
 		this.lightNear = data.lightNear || 1;
+
+		/**
+		 * The light far value.
+		 *
+		 * @type {number}
+		 * @default 2000
+		 */
 		this.lightFar = data.lightFar || 2000;
+
+		/**
+		 * The light margin.
+		 *
+		 * @type {number}
+		 * @default 200
+		 */
 		this.lightMargin = data.lightMargin || 200;
+
+		/**
+		 * Custom split callback when using `mode='custom'`.
+		 *
+		 * @type {Function}
+		 */
 		this.customSplitsCallback = data.customSplitsCallback;
+
+		/**
+		 * Whether to fade between cascades or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.fade = false;
-		this.mainFrustum = new CSMFrustum();
+
+		/**
+		 * The main frustum.
+		 *
+		 * @type {CSMFrustum}
+		 */
+		this.mainFrustum = new CSMFrustum( { webGL: true } );
+
+		/**
+		 * An array of frustums representing the cascades.
+		 *
+		 * @type {Array<CSMFrustum>}
+		 */
 		this.frustums = [];
+
+		/**
+		 * An array of numbers in the range `[0,1]` the defines how the
+		 * mainCSM frustum should be split up.
+		 *
+		 * @type {Array<number>}
+		 */
 		this.breaks = [];
 
+		/**
+		 * An array of directional lights which cast the shadows for
+		 * the different cascades. There is one directional light for each
+		 * cascade.
+		 *
+		 * @type {Array<DirectionalLight>}
+		 */
 		this.lights = [];
+
+		/**
+		 * A Map holding enhanced material shaders.
+		 *
+		 * @type {Map<Material,Object>}
+		 */
 		this.shaders = new Map();
 
-		this.createLights();
+		this._createLights();
 		this.updateFrustums();
-		this.injectInclude();
+		this._injectInclude();
 
 	}
 
-	createLights() {
+	/**
+	 * Creates the directional lights of this CSM instance.
+	 *
+	 * @private
+	 */
+	_createLights() {
 
 		for ( let i = 0; i < this.cascades; i ++ ) {
 
@@ -72,7 +216,12 @@ export class CSM {
 
 	}
 
-	initCascades() {
+	/**
+	 * Inits the cascades according to the scene's camera and breaks configuration.
+	 *
+	 * @private
+	 */
+	_initCascades() {
 
 		const camera = this.camera;
 		camera.updateProjectionMatrix();
@@ -81,7 +230,12 @@ export class CSM {
 
 	}
 
-	updateShadowBounds() {
+	/**
+	 * Updates the shadow bounds of this CSM instance.
+	 *
+	 * @private
+	 */
+	_updateShadowBounds() {
 
 		const frustums = this.frustums;
 		for ( let i = 0; i < frustums.length; i ++ ) {
@@ -130,7 +284,13 @@ export class CSM {
 
 	}
 
-	getBreaks() {
+	/**
+	 * Computes the breaks of this CSM instance based on the scene's camera, number of cascades
+	 * and the selected split mode.
+	 *
+	 * @private
+	 */
+	_getBreaks() {
 
 		const camera = this.camera;
 		const far = Math.min( camera.far, this.maxFar );
@@ -197,6 +357,10 @@ export class CSM {
 
 	}
 
+	/**
+	 * Updates the CSM. This method must be called in your animation loop before
+	 * calling `renderer.render()`.
+	 */
 	update() {
 
 		const camera = this.camera;
@@ -204,7 +368,7 @@ export class CSM {
 
 		// for each frustum we need to find its min-max box aligned with the light orientation
 		// the position in _lightOrientationMatrix does not matter, as we transform there and back
-		_lightOrientationMatrix.lookAt( new Vector3(), this.lightDirection, _up );
+		_lightOrientationMatrix.lookAt( _origin, this.lightDirection, _up );
 		_lightOrientationMatrixInverse.copy( _lightOrientationMatrix ).invert();
 
 		for ( let i = 0; i < frustums.length; i ++ ) {
@@ -243,13 +407,23 @@ export class CSM {
 
 	}
 
-	injectInclude() {
+	/**
+	 * Injects the CSM shader enhancements into the built-in materials.
+	 *
+	 * @private
+	 */
+	_injectInclude() {
 
 		ShaderChunk.lights_fragment_begin = CSMShader.lights_fragment_begin;
 		ShaderChunk.lights_pars_begin = CSMShader.lights_pars_begin;
 
 	}
 
+	/**
+	 * Applications must call this method for all materials that should be affected by CSM.
+	 *
+	 * @param {Material} material - The material to setup for CSM support.
+	 */
 	setupMaterial( material ) {
 
 		material.defines = material.defines || {};
@@ -269,7 +443,7 @@ export class CSM {
 		material.onBeforeCompile = function ( shader ) {
 
 			const far = Math.min( scope.camera.far, scope.maxFar );
-			scope.getExtendedBreaks( breaksVec2 );
+			scope._getExtendedBreaks( breaksVec2 );
 
 			shader.uniforms.CSM_cascades = { value: breaksVec2 };
 			shader.uniforms.cameraNear = { value: scope.camera.near };
@@ -283,7 +457,12 @@ export class CSM {
 
 	}
 
-	updateUniforms() {
+	/**
+	 * Updates the CSM uniforms.
+	 *
+	 * @private
+	 */
+	_updateUniforms() {
 
 		const far = Math.min( this.camera.far, this.maxFar );
 		const shaders = this.shaders;
@@ -293,7 +472,7 @@ export class CSM {
 			if ( shader !== null ) {
 
 				const uniforms = shader.uniforms;
-				this.getExtendedBreaks( uniforms.CSM_cascades.value );
+				this._getExtendedBreaks( uniforms.CSM_cascades.value );
 				uniforms.cameraNear.value = this.camera.near;
 				uniforms.shadowFar.value = far;
 
@@ -315,7 +494,13 @@ export class CSM {
 
 	}
 
-	getExtendedBreaks( target ) {
+	/**
+	 * Computes the extended breaks for the CSM uniforms.
+	 *
+	 * @private
+	 * @param {Array<Vector2>} target - The target array that holds the extended breaks.
+	 */
+	_getExtendedBreaks( target ) {
 
 		while ( target.length < this.breaks.length ) {
 
@@ -336,15 +521,21 @@ export class CSM {
 
 	}
 
+	/**
+	 * Applications must call this method every time they change camera or CSM settings.
+	 */
 	updateFrustums() {
 
-		this.getBreaks();
-		this.initCascades();
-		this.updateShadowBounds();
-		this.updateUniforms();
+		this._getBreaks();
+		this._initCascades();
+		this._updateShadowBounds();
+		this._updateUniforms();
 
 	}
 
+	/**
+	 * Applications must call this method when they remove the CSM usage from their scene.
+	 */
 	remove() {
 
 		for ( let i = 0; i < this.lights.length; i ++ ) {
@@ -356,6 +547,10 @@ export class CSM {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
 		const shaders = this.shaders;
@@ -382,3 +577,22 @@ export class CSM {
 	}
 
 }
+
+/**
+ * Constructor data of `CSM`.
+ *
+ * @typedef {Object} CSM~Data
+ * @property {Camera} camera - The scene's camera.
+ * @property {Object3D} parent - The parent object, usually the scene.
+ * @property {number} [cascades=3] - The number of cascades.
+ * @property {number} [maxFar=100000] - The maximum far value.
+ * @property {('practical'|'uniform'|'logarithmic'|'custom')} [mode='practical'] - The frustum split mode.
+ * @property {Function} [customSplitsCallback] - Custom split callback when using `mode='custom'`.
+ * @property {number} [shadowMapSize=2048] - The shadow map size.
+ * @property {number} [shadowBias=0.000001] - The shadow bias.
+ * @property {Vector3} [lightDirection] - The light direction.
+ * @property {number} [lightIntensity=3] - The light intensity.
+ * @property {number} [lightNear=1] - The light near value.
+ * @property {number} [lightNear=2000] - The light far value.
+ * @property {number} [lightMargin=200] - The light margin.
+ **/

package/examples/jsm/csm/CSMFrustum.js

@@ -2,12 +2,37 @@ import { Vector3, Matrix4 } from 'three';
 
 const inverseProjectionMatrix = new Matrix4();
 
+/**
+ * Represents the frustum of a CSM instance.
+ *
+ * @three_import import { CSMFrustum } from 'three/addons/csm/CSMFrustum.js';
+ */
 class CSMFrustum {
 
+	/**
+	 * Constructs a new CSM frustum.
+	 *
+	 * @param {CSMFrustum~Data} [data] - The CSM data.
+	 */
 	constructor( data ) {
 
 		data = data || {};
 
+		/**
+		 * The zNear value. This value depends on whether the CSM
+		 * is used with WebGL or WebGPU. Both API use different
+		 * conventions for their projection matrices.
+		 *
+		 * @type {number}
+		 */
+		this.zNear = data.webGL === true ? - 1 : 0;
+
+		/**
+		 * An object representing the vertices of the near and
+		 * far plane in view space.
+		 *
+		 * @type {Object}
+		 */
 		this.vertices = {
 			near: [
 				new Vector3(),
@@ -31,8 +56,16 @@ class CSMFrustum {
 
 	}
 
+	/**
+	 * Setups this CSM frustum from the given projection matrix and max far value.
+	 *
+	 * @param {Matrix4} projectionMatrix - The projection matrix, usually of the scene's camera.
+	 * @param {number} maxFar - The maximum far value.
+	 * @returns {Object} An object representing the vertices of the near and far plane in view space.
+	 */
 	setFromProjectionMatrix( projectionMatrix, maxFar ) {
 
+		const zNear = this.zNear;
 		const isOrthographic = projectionMatrix.elements[ 2 * 4 + 3 ] === 0;
 
 		inverseProjectionMatrix.copy( projectionMatrix ).invert();
@@ -42,10 +75,10 @@ class CSMFrustum {
 		// 2 --- 1
 		// clip space spans from [-1, 1]
 
-		this.vertices.near[ 0 ].set( 1, 1, - 1 );
-		this.vertices.near[ 1 ].set( 1, - 1, - 1 );
-		this.vertices.near[ 2 ].set( - 1, - 1, - 1 );
-		this.vertices.near[ 3 ].set( - 1, 1, - 1 );
+		this.vertices.near[ 0 ].set( 1, 1, zNear );
+		this.vertices.near[ 1 ].set( 1, - 1, zNear );
+		this.vertices.near[ 2 ].set( - 1, - 1, zNear );
+		this.vertices.near[ 3 ].set( - 1, 1, zNear );
 		this.vertices.near.forEach( function ( v ) {
 
 			v.applyMatrix4( inverseProjectionMatrix );
@@ -77,6 +110,14 @@ class CSMFrustum {
 
 	}
 
+	/**
+	 * Splits the CSM frustum by the given array. The new CSM frustum are pushed into the given
+	 * target array.
+	 *
+	 * @param {Array<number>} breaks - An array of numbers in the range `[0,1]` the defines how the
+	 * CSM frustum should be split up.
+	 * @param {Array<CSMFrustum>} target - The target array that holds the new CSM frustums.
+	 */
 	split( breaks, target ) {
 
 		while ( breaks.length > target.length ) {
@@ -131,6 +172,13 @@ class CSMFrustum {
 
 	}
 
+	/**
+	 * Transforms the given target CSM frustum into the different coordinate system defined by the
+	 * given camera matrix.
+	 *
+	 * @param {Matrix4} cameraMatrix - The matrix that defines the new coordinate system.
+	 * @param {CSMFrustum} target - The CSM to convert.
+	 */
 	toSpace( cameraMatrix, target ) {
 
 		for ( let i = 0; i < 4; i ++ ) {
@@ -149,4 +197,13 @@ class CSMFrustum {
 
 }
 
+/**
+ * Constructor data of `CSMFrustum`.
+ *
+ * @typedef {Object} CSMFrustum~Data
+ * @property {boolean} [webGL] - Whether this CSM frustum is used with WebGL or WebGPU.
+ * @property {Matrix4} [projectionMatrix] - A projection matrix usually of the scene's camera.
+ * @property {number} [maxFar] - The maximum far value.
+ **/
+
 export { CSMFrustum };

package/examples/jsm/csm/CSMHelper.js

@@ -12,14 +12,52 @@ import {
 	DoubleSide
 } from 'three';
 
+/**
+ * A helper for visualizing the cascades of a CSM instance.
+ *
+ * @augments Group
+ * @three_import import { CSMHelper } from 'three/addons/csm/CSMHelper.js';
+ */
 class CSMHelper extends Group {
 
+	/**
+	 * Constructs a new CSM helper.
+	 *
+	 * @param {CSM|CSMShadowNode} csm - The CSM instance to visualize.
+	 */
 	constructor( csm ) {
 
 		super();
+
+		/**
+		 * The CSM instance to visualize.
+		 *
+		 * @type {CSM|CSMShadowNode}
+		 */
 		this.csm = csm;
+
+		/**
+		 * Whether to display the CSM frustum or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.displayFrustum = true;
+
+		/**
+		 * Whether to display the cascade planes or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.displayPlanes = true;
+
+		/**
+		 * Whether to display the shadow bounds or not.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.displayShadowBounds = true;
 
 		const indices = new Uint16Array( [ 0, 1, 1, 2, 2, 3, 3, 0, 4, 5, 5, 6, 6, 7, 7, 4, 0, 4, 1, 5, 2, 6, 3, 7 ] );
@@ -37,6 +75,9 @@ class CSMHelper extends Group {
 
 	}
 
+	/**
+	 * This method must be called if one of the `display*` properties is changed at runtime.
+	 */
 	updateVisibility() {
 
 		const displayFrustum = this.displayFrustum;
@@ -63,6 +104,9 @@ class CSMHelper extends Group {
 
 	}
 
+	/**
+	 * Updates the helper. This method should be called in the app's animation loop.
+	 */
 	update() {
 
 		const csm = this.csm;
@@ -78,6 +122,8 @@ class CSMHelper extends Group {
 		const cascadePlanes = this.cascadePlanes;
 		const shadowLines = this.shadowLines;
 
+		if ( camera === null ) return;
+
 		this.position.copy( camera.position );
 		this.quaternion.copy( camera.quaternion );
 		this.scale.copy( camera.scale );
@@ -158,6 +204,10 @@ class CSMHelper extends Group {
 
 	}
 
+	/**
+	 * Frees the GPU-related resources allocated by this instance. Call this
+	 * method whenever this instance is no longer used in your app.
+	 */
 	dispose() {
 
 		const frustumLines = this.frustumLines;

package/examples/jsm/csm/CSMShader.js

@@ -1,5 +1,16 @@
 import { ShaderChunk } from 'three';
 
+/**
+ * @module CSMShader
+ * @three_import import { CSMShader } from 'three/addons/csm/CSMShader.js';
+ */
+
+/**
+ * The object that holds the GLSL enhancements to enable CSM. This
+ * code is injected into the built-in material shaders by {@link CSM}.
+ *
+ * @type {Object}
+ */
 const CSMShader = {
 	lights_fragment_begin: /* glsl */`
 vec3 geometryPosition = - vViewPosition;
@@ -46,7 +57,8 @@ IncidentLight directLight;
 
 		#if defined( USE_SHADOWMAP ) && ( UNROLLED_LOOP_INDEX < NUM_POINT_LIGHT_SHADOWS )
 		pointLightShadow = pointLightShadows[ i ];
-		directLight.color *= ( directLight.visible && receiveShadow ) ? getPointShadow( pointShadowMap[ i ], pointLightShadow.shadowMapSize, pointLightShadow.shadowBias, pointLightShadow.shadowRadius, vPointShadowCoord[ i ], pointLightShadow.shadowCameraNear, pointLightShadow.shadowCameraFar ) : 1.0;
+		directLight.color *= ( directLight.visible && receiveShadow ) ? getPointShadow( pointShadowMap[ i ], pointLightShadow.shadowMapSize, pointLightShadow.shadowIntensity, pointLightShadow.shadowBias, pointLightShadow.shadowRadius, vPointShadowCoord[ i ], pointLightShadow.shadowCameraNear, pointLightShadow.shadowCameraFar ) : 1.0;
+
 		#endif
 
 		RE_Direct( directLight, geometryPosition, geometryNormal, geometryViewDir, geometryClearcoatNormal, material, reflectedLight );