@gnsx/three 0.185.15 → 0.186.0

package/examples/jsm/lights/SunLight.js

@@ -0,0 +1,95 @@
+import { Light, Object3D } from '@gnsx/three';
+import { SunLightShadow } from './SunLightShadow.js';
+
+/**
+ * A sun-like light that gets emitted in a specific direction, with rays that
+ * are all parallel, and casts cascaded shadow maps via {@link SunLightShadow},
+ * suited for lighting large scenes.
+ *
+ * Unlike {@link DirectionalLight}, the light has no target: like
+ * {@link HemisphereLight}, its direction is defined by its position. The
+ * light shines from its position towards the origin and points straight
+ * down by default.
+ *
+ * ```js
+ * const sun = new SunLight( 0xfff2e3, 3 );
+ * sun.position.set( 1, 1, 1 );
+ * sun.castShadow = true;
+ * scene.add( sun );
+ * ```
+ *
+ * When used with `WebGPURenderer`, the light must be registered with the
+ * renderer's node library first:
+ * ```js
+ * renderer.library.addLight( SunLightNode, SunLight );
+ * ```
+ *
+ * @augments Light
+ * @three_import import { SunLight } from 'three/addons/lights/SunLight.js';
+ */
+class SunLight extends Light {
+
+	/**
+	 * Constructs a new sun light.
+	 *
+	 * @param {(number|Color|string)} [color=0xffffff] - The light's color.
+	 * @param {number} [intensity=1] - The light's strength/intensity.
+	 */
+	constructor( color, intensity ) {
+
+		super( color, intensity );
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isSunLight = true;
+
+		this.type = 'SunLight';
+
+		this.position.copy( Object3D.DEFAULT_UP );
+		this.updateMatrix();
+
+		/**
+		 * This property holds the light's shadow configuration.
+		 *
+		 * @type {SunLightShadow}
+		 */
+		this.shadow = new SunLightShadow();
+
+	}
+
+	dispose() {
+
+		super.dispose();
+
+		this.shadow.dispose();
+
+	}
+
+	copy( source ) {
+
+		super.copy( source );
+
+		this.shadow = source.shadow.clone();
+
+		return this;
+
+	}
+
+	toJSON( meta ) {
+
+		const data = super.toJSON( meta );
+
+		data.object.shadow = this.shadow.toJSON();
+
+		return data;
+
+	}
+
+}
+
+export { SunLight };

package/examples/jsm/lights/SunLightNode.js

@@ -0,0 +1,56 @@
+import { AnalyticLightNode } from '@gnsx/three/webgpu';
+import { cameraViewMatrix, lightPosition } from '@gnsx/three/tsl';
+import { sunShadow } from './SunShadowNode.js';
+
+/**
+ * Module for representing sun lights as nodes. Register it with the
+ * renderer's node library to use {@link SunLight} with `WebGPURenderer`:
+ * ```js
+ * renderer.library.addLight( SunLightNode, SunLight );
+ * ```
+ *
+ * @augments AnalyticLightNode
+ * @three_import import { SunLightNode } from 'three/addons/lights/SunLightNode.js';
+ */
+class SunLightNode extends AnalyticLightNode {
+
+	static get type() {
+
+		return 'SunLightNode';
+
+	}
+
+	/**
+	 * Constructs a new sun light node.
+	 *
+	 * @param {?SunLight} [light=null] - The sun light source.
+	 */
+	constructor( light = null ) {
+
+		super( light );
+
+	}
+
+	/**
+	 * Overwritten to setup the cascaded shadows of sun lights.
+	 *
+	 * @return {SunShadowNode} The created shadow node.
+	 */
+	setupShadowNode() {
+
+		return sunShadow( this.light );
+
+	}
+
+	setupDirect() {
+
+		const lightColor = this.colorNode;
+		const lightDirection = cameraViewMatrix.transformDirection( lightPosition( this.light ) );
+
+		return { lightDirection, lightColor };
+
+	}
+
+}
+
+export { SunLightNode };

package/examples/jsm/lights/SunLightShadow.js

@@ -0,0 +1,319 @@
+import {
+	Frustum,
+	LightShadow,
+	Matrix4,
+	OrthographicCamera,
+	Vector3,
+	Vector4,
+	WebGPUCoordinateSystem
+} from '@gnsx/three';
+
+const _lightOrientationMatrix = /*@__PURE__*/ new Matrix4();
+const _viewToLightMatrix = /*@__PURE__*/ new Matrix4();
+const _lightDirection = /*@__PURE__*/ new Vector3();
+const _up = /*@__PURE__*/ new Vector3();
+const _center = /*@__PURE__*/ new Vector3();
+
+const _nearCorners = [
+	/*@__PURE__*/ new Vector3(),
+	/*@__PURE__*/ new Vector3(),
+	/*@__PURE__*/ new Vector3(),
+	/*@__PURE__*/ new Vector3()
+];
+
+const _farCorners = [
+	/*@__PURE__*/ new Vector3(),
+	/*@__PURE__*/ new Vector3(),
+	/*@__PURE__*/ new Vector3(),
+	/*@__PURE__*/ new Vector3()
+];
+
+const _cascadeCorners = [
+	/*@__PURE__*/ new Vector3(),
+	/*@__PURE__*/ new Vector3(),
+	/*@__PURE__*/ new Vector3(),
+	/*@__PURE__*/ new Vector3(),
+	/*@__PURE__*/ new Vector3(),
+	/*@__PURE__*/ new Vector3(),
+	/*@__PURE__*/ new Vector3(),
+	/*@__PURE__*/ new Vector3()
+];
+
+// must match the cascade count in the sun shadow shader chunks
+
+const _cascadeCount = 2;
+
+// fraction of each cascade's depth range that blends into the next cascade
+
+const _cascadeFade = 0.1;
+
+/**
+ * Represents the shadow configuration of {@link SunLight}, using two
+ * cascaded shadow maps (CSM).
+ *
+ * The shadow camera projection is fitted automatically to slices of the view
+ * frustum, up to a distance of `camera.far` (or the view camera's far plane,
+ * whichever is smaller), and adjacent cascades blend into each other over a
+ * small depth range. `camera.left/right/top/bottom` are ignored.
+ *
+ * The default `mapSize` is `1024x1024` per cascade.
+ *
+ * @augments LightShadow
+ * @three_import import { SunLightShadow } from 'three/addons/lights/SunLightShadow.js';
+ */
+class SunLightShadow extends LightShadow {
+
+	/**
+	 * Constructs a new sun light shadow.
+	 */
+	constructor() {
+
+		super( new OrthographicCamera( - 5, 5, 5, - 5, 0.5, 500 ) );
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isSunLightShadow = true;
+
+		this.mapSize.set( 1024, 1024 );
+
+		this._cameras = [];
+		this._matrices = [];
+		this._frustums = [];
+		this._cascadeSplits = new Array( _cascadeCount + 1 ).fill( 0 );
+
+		// per cascade ( begin, end, fade start ) view depths, consumed by the renderer
+
+		this._cascadeData = [];
+
+		this._viewportCount = _cascadeCount;
+		this._frameExtents.set( 2, 1 );
+
+		for ( let i = 0; i < _cascadeCount; i ++ ) {
+
+			this._cameras.push( new OrthographicCamera() );
+			this._matrices.push( new Matrix4() );
+			this._frustums.push( new Frustum() );
+			this._cascadeData.push( new Vector4() );
+
+		}
+
+		while ( this._viewports.length < _cascadeCount ) this._viewports.push( new Vector4() );
+
+	}
+
+	/**
+	 * Returns the shadow camera of the given cascade.
+	 *
+	 * @param {number} [cascadeIndex=0] - The cascade index.
+	 * @return {OrthographicCamera} The shadow camera.
+	 */
+	getCamera( cascadeIndex = 0 ) {
+
+		return this._cameras[ cascadeIndex ];
+
+	}
+
+	/**
+	 * Returns the shadow matrix of the given cascade.
+	 *
+	 * @param {number} [cascadeIndex=0] - The cascade index.
+	 * @return {Matrix4} The shadow matrix.
+	 */
+	getMatrix( cascadeIndex = 0 ) {
+
+		return this._matrices[ cascadeIndex ];
+
+	}
+
+	/**
+	 * Returns the shadow camera frustum of the given cascade. Used internally by
+	 * the renderer to cull objects.
+	 *
+	 * @param {number} [cascadeIndex=0] - The cascade index.
+	 * @return {Frustum} The shadow camera frustum.
+	 */
+	getFrustum( cascadeIndex = 0 ) {
+
+		return this._frustums[ cascadeIndex ];
+
+	}
+
+	/**
+	 * Update the matrices for the cascade cameras and shadows, used internally
+	 * by the renderer.
+	 *
+	 * @param {Light} light - The light for which the shadow is being rendered.
+	 * @param {Camera} viewCamera - The camera the scene is rendered with.
+	 */
+	updateMatrices( light, viewCamera ) {
+
+		if ( viewCamera === undefined ) return;
+
+		// inset the cascade viewports so shadow filtering cannot read across atlas tiles
+
+		const insetX = Math.min( 0.25, ( Math.ceil( this.radius ) + 1 ) / this.mapSize.x );
+		const insetY = Math.min( 0.25, ( Math.ceil( this.radius ) + 1 ) / this.mapSize.y );
+
+		for ( let i = 0; i < _cascadeCount; i ++ ) {
+
+			this._viewports[ i ].set( i + insetX, insetY, 1 - 2 * insetX, 1 - 2 * insetY );
+
+		}
+
+		const resolutionX = this.mapSize.x * ( 1 - 2 * insetX );
+		const resolutionY = this.mapSize.y * ( 1 - 2 * insetY );
+		const resolution = Math.min( resolutionX, resolutionY );
+
+		const camera = this.camera;
+		const cameraNear = viewCamera.near;
+		const cameraFar = Math.max( cameraNear + 1e-6, Math.min( camera.far, viewCamera.far ) );
+
+		// practical split scheme: the average of uniform and logarithmic splits
+
+		const splits = this._cascadeSplits;
+		splits[ 0 ] = cameraNear;
+
+		for ( let i = 1; i < _cascadeCount; i ++ ) {
+
+			const amount = i / _cascadeCount;
+			const uniform = cameraNear + ( cameraFar - cameraNear ) * amount;
+			const logarithmic = cameraNear > 0 ? cameraNear * Math.pow( cameraFar / cameraNear, amount ) : uniform;
+			splits[ i ] = ( uniform + logarithmic ) * 0.5;
+
+		}
+
+		splits[ _cascadeCount ] = cameraFar;
+
+		_lightDirection.setFromMatrixPosition( light.matrixWorld ).negate().normalize();
+
+		_up.set( 0, 1, 0 );
+		if ( Math.abs( _up.dot( _lightDirection ) ) > 0.99 ) _up.set( 0, 0, 1 );
+
+		_lightOrientationMatrix.lookAt( _center.set( 0, 0, 0 ), _lightDirection, _up );
+		_viewToLightMatrix.copy( _lightOrientationMatrix ).transpose().multiply( viewCamera.matrixWorld );
+
+		// view frustum corners in light space; the rotation preserves distances,
+		// so the cascades can be fitted and snapped directly in this space
+
+		const zNear = viewCamera.reversedDepth ? 1 : ( viewCamera.coordinateSystem === WebGPUCoordinateSystem ? 0 : - 1 );
+		const inverseProjectionMatrix = viewCamera.projectionMatrixInverse;
+
+		let globalMaxZ = - Infinity;
+
+		for ( let i = 0; i < 4; i ++ ) {
+
+			const x = i === 0 || i === 1 ? 1 : - 1;
+			const y = i === 0 || i === 3 ? 1 : - 1;
+
+			const nearCorner = _nearCorners[ i ].set( x, y, zNear ).applyMatrix4( inverseProjectionMatrix );
+			const farCorner = _farCorners[ i ];
+
+			if ( viewCamera.isPerspectiveCamera === true ) {
+
+				farCorner.copy( nearCorner ).multiplyScalar( cameraFar / cameraNear );
+
+			} else {
+
+				farCorner.set( nearCorner.x, nearCorner.y, - cameraFar );
+
+			}
+
+			nearCorner.applyMatrix4( _viewToLightMatrix );
+			farCorner.applyMatrix4( _viewToLightMatrix );
+
+			globalMaxZ = Math.max( globalMaxZ, nearCorner.z, farCorner.z );
+
+		}
+
+		// raise the ceiling one shadow range towards the light so casters outside
+		// the view frustum still cast into it
+
+		globalMaxZ += cameraFar;
+
+		const shadowNear = camera.near;
+
+		for ( let i = 0; i < _cascadeCount; i ++ ) {
+
+			// each cascade covers the fade band of the previous one so both can be sampled while blending
+
+			const cascadeNear = i === 0 ? splits[ 0 ] : this._cascadeData[ i - 1 ].z;
+			const cascadeFar = splits[ i + 1 ];
+			const fadeStart = cascadeFar - _cascadeFade * ( cascadeFar - splits[ i ] );
+
+			this._cascadeData[ i ].set( i === 0 ? - 1e10 : cascadeNear, cascadeFar, fadeStart, 0 );
+
+			// bounding sphere of the cascade slice for a rotation-stable projection
+
+			const nearAlpha = ( cascadeNear - cameraNear ) / ( cameraFar - cameraNear );
+			const farAlpha = ( cascadeFar - cameraNear ) / ( cameraFar - cameraNear );
+
+			_center.set( 0, 0, 0 );
+
+			for ( let j = 0; j < 4; j ++ ) {
+
+				_cascadeCorners[ j * 2 ].lerpVectors( _nearCorners[ j ], _farCorners[ j ], nearAlpha );
+				_cascadeCorners[ j * 2 + 1 ].lerpVectors( _nearCorners[ j ], _farCorners[ j ], farAlpha );
+				_center.add( _cascadeCorners[ j * 2 ] ).add( _cascadeCorners[ j * 2 + 1 ] );
+
+			}
+
+			_center.multiplyScalar( 1 / 8 );
+
+			let radiusSq = 0;
+			let minZ = Infinity;
+
+			for ( let j = 0; j < 8; j ++ ) {
+
+				radiusSq = Math.max( radiusSq, _cascadeCorners[ j ].distanceToSquared( _center ) );
+				minZ = Math.min( minZ, _cascadeCorners[ j ].z );
+
+			}
+
+			let radius = Math.sqrt( radiusSq );
+
+			// snap to the texel grid to avoid shimmering when the view camera moves
+
+			if ( resolution > 1 ) {
+
+				// pad by half a texel so snapping cannot clip a frustum corner
+				radius /= 1 - 1 / resolution;
+				const texelSizeX = 2 * radius / resolutionX;
+				const texelSizeY = 2 * radius / resolutionY;
+				_center.x = Math.round( _center.x / texelSizeX ) * texelSizeX;
+				_center.y = Math.round( _center.y / texelSizeY ) * texelSizeY;
+
+			}
+
+			// place the near plane at the caster ceiling
+
+			_center.z = globalMaxZ + shadowNear;
+			_center.applyMatrix4( _lightOrientationMatrix );
+
+			const cascadeCamera = this._cameras[ i ];
+			cascadeCamera.position.copy( _center );
+			cascadeCamera.quaternion.setFromRotationMatrix( _lightOrientationMatrix );
+			cascadeCamera.left = - radius;
+			cascadeCamera.right = radius;
+			cascadeCamera.top = radius;
+			cascadeCamera.bottom = - radius;
+			cascadeCamera.near = shadowNear;
+			cascadeCamera.far = globalMaxZ - minZ + 2 * shadowNear;
+			cascadeCamera.coordinateSystem = camera.coordinateSystem;
+			cascadeCamera._reversedDepth = camera.reversedDepth;
+			cascadeCamera.updateProjectionMatrix();
+			cascadeCamera.updateMatrixWorld();
+
+			this._updateMatrix( cascadeCamera, this._matrices[ i ], this._frustums[ i ], this._viewports[ i ] );
+
+		}
+
+	}
+
+}
+
+export { SunLightShadow };