@plastic-software/three 0.167.4 → 0.174.0

package/src/nodes/lighting/AnalyticLightNode.js

@@ -1,152 +1,113 @@
 import LightingNode from './LightingNode.js';
 import { NodeUpdateType } from '../core/constants.js';
 import { uniform } from '../core/UniformNode.js';
-import { addNodeClass } from '../core/Node.js';
-import { float, vec2, vec3, vec4 } from '../shadernode/ShaderNode.js';
-import { reference } from '../accessors/ReferenceNode.js';
-import { texture } from '../accessors/TextureNode.js';
-import { positionWorld } from '../accessors/PositionNode.js';
-import { normalWorld } from '../accessors/NormalNode.js';
-import { mix, fract } from '../math/MathNode.js';
-import { add } from '../math/OperatorNode.js';
 import { Color } from '../../math/Color.js';
-import { DepthTexture } from '../../textures/DepthTexture.js';
-import { Fn } from '../shadernode/ShaderNode.js';
-import { LessCompare, WebGPUCoordinateSystem } from '../../constants.js';
-
-const BasicShadowMap = Fn( ( { depthTexture, shadowCoord } ) => {
-
-	return texture( depthTexture, shadowCoord.xy ).compare( shadowCoord.z );
-
-} );
-
-const PCFShadowMap = Fn( ( { depthTexture, shadowCoord, shadow } ) => {
-
-	const depthCompare = ( uv, compare ) => texture( depthTexture, uv ).compare( compare );
-
-	const mapSize = reference( 'mapSize', 'vec2', shadow );
-	const radius = reference( 'radius', 'float', shadow );
-
-	const texelSize = vec2( 1 ).div( mapSize );
-	const dx0 = texelSize.x.negate().mul( radius );
-	const dy0 = texelSize.y.negate().mul( radius );
-	const dx1 = texelSize.x.mul( radius );
-	const dy1 = texelSize.y.mul( radius );
-	const dx2 = dx0.div( 2 );
-	const dy2 = dy0.div( 2 );
-	const dx3 = dx1.div( 2 );
-	const dy3 = dy1.div( 2 );
-
-	return add(
-		depthCompare( shadowCoord.xy.add( vec2( dx0, dy0 ) ), shadowCoord.z ),
-		depthCompare( shadowCoord.xy.add( vec2( 0, dy0 ) ), shadowCoord.z ),
-		depthCompare( shadowCoord.xy.add( vec2( dx1, dy0 ) ), shadowCoord.z ),
-		depthCompare( shadowCoord.xy.add( vec2( dx2, dy2 ) ), shadowCoord.z ),
-		depthCompare( shadowCoord.xy.add( vec2( 0, dy2 ) ), shadowCoord.z ),
-		depthCompare( shadowCoord.xy.add( vec2( dx3, dy2 ) ), shadowCoord.z ),
-		depthCompare( shadowCoord.xy.add( vec2( dx0, 0 ) ), shadowCoord.z ),
-		depthCompare( shadowCoord.xy.add( vec2( dx2, 0 ) ), shadowCoord.z ),
-		depthCompare( shadowCoord.xy, shadowCoord.z ),
-		depthCompare( shadowCoord.xy.add( vec2( dx3, 0 ) ), shadowCoord.z ),
-		depthCompare( shadowCoord.xy.add( vec2( dx1, 0 ) ), shadowCoord.z ),
-		depthCompare( shadowCoord.xy.add( vec2( dx2, dy3 ) ), shadowCoord.z ),
-		depthCompare( shadowCoord.xy.add( vec2( 0, dy3 ) ), shadowCoord.z ),
-		depthCompare( shadowCoord.xy.add( vec2( dx3, dy3 ) ), shadowCoord.z ),
-		depthCompare( shadowCoord.xy.add( vec2( dx0, dy1 ) ), shadowCoord.z ),
-		depthCompare( shadowCoord.xy.add( vec2( 0, dy1 ) ), shadowCoord.z ),
-		depthCompare( shadowCoord.xy.add( vec2( dx1, dy1 ) ), shadowCoord.z )
-	).mul( 1 / 17 );
-
-} );
-
-const PCFSoftShadowMap = Fn( ( { depthTexture, shadowCoord, shadow } ) => {
-
-	const depthCompare = ( uv, compare ) => texture( depthTexture, uv ).compare( compare );
-
-	const mapSize = reference( 'mapSize', 'vec2', shadow );
-
-	const texelSize = vec2( 1 ).div( mapSize );
-	const dx = texelSize.x;
-	const dy = texelSize.y;
-
-	const uv = shadowCoord.xy;
-	const f = fract( uv.mul( mapSize ).add( 0.5 ) );
-	uv.subAssign( f.mul( texelSize ) );
-
-	return add(
-		depthCompare( uv, shadowCoord.z ),
-		depthCompare( uv.add( vec2( dx, 0 ) ), shadowCoord.z ),
-		depthCompare( uv.add( vec2( 0, dy ) ), shadowCoord.z ),
-		depthCompare( uv.add( texelSize ), shadowCoord.z ),
-		mix(
-			depthCompare( uv.add( vec2( dx.negate(), 0 ) ), shadowCoord.z ),
-			depthCompare( uv.add( vec2( dx.mul( 2 ), 0 ) ), shadowCoord.z ),
-			f.x
-		),
-		mix(
-			depthCompare( uv.add( vec2( dx.negate(), dy ) ), shadowCoord.z ),
-			depthCompare( uv.add( vec2( dx.mul( 2 ), dy ) ), shadowCoord.z ),
-			f.x
-		),
-		mix(
-			depthCompare( uv.add( vec2( 0, dy.negate() ) ), shadowCoord.z ),
-			depthCompare( uv.add( vec2( 0, dy.mul( 2 ) ) ), shadowCoord.z ),
-			f.y
-		),
-		mix(
-			depthCompare( uv.add( vec2( dx, dy.negate() ) ), shadowCoord.z ),
-			depthCompare( uv.add( vec2( dx, dy.mul( 2 ) ) ), shadowCoord.z ),
-			f.y
-		),
-		mix(
-			mix(
-				depthCompare( uv.add( vec2( dx.negate(), dy.negate() ) ), shadowCoord.z ),
-				depthCompare( uv.add( vec2( dx.mul( 2 ), dy.negate() ) ), shadowCoord.z ),
-				f.x
-			),
-			mix(
-				depthCompare( uv.add( vec2( dx.negate(), dy.mul( 2 ) ) ), shadowCoord.z ),
-				depthCompare( uv.add( vec2( dx.mul( 2 ), dy.mul( 2 ) ) ), shadowCoord.z ),
-				f.x
-			),
-			f.y
-		)
-	).mul( 1 / 9 );
-
-} );
-
-const shadowFilterLib = [ BasicShadowMap, PCFShadowMap, PCFSoftShadowMap ];
-
-//
-
-let overrideMaterial = null;
-
+import { renderGroup } from '../core/UniformGroupNode.js';
+import { hash } from '../core/NodeUtils.js';
+import { shadow } from './ShadowNode.js';
+import { nodeObject } from '../tsl/TSLCore.js';
+import { lightViewPosition } from '../accessors/Lights.js';
+import { positionView } from '../accessors/Position.js';
+
+/**
+ * Base class for analytic light nodes.
+ *
+ * @augments LightingNode
+ */
 class AnalyticLightNode extends LightingNode {
 
+	static get type() {
+
+		return 'AnalyticLightNode';
+
+	}
+
+	/**
+	 * Constructs a new analytic light node.
+	 *
+	 * @param {?Light} [light=null] - The light source.
+	 */
 	constructor( light = null ) {
 
 		super();
 
-		this.updateType = NodeUpdateType.FRAME;
-
+		/**
+		 * The light source.
+		 *
+		 * @type {?Light}
+		 * @default null
+		 */
 		this.light = light;
 
+		/**
+		 * The light's color value.
+		 *
+		 * @type {Color}
+		 */
 		this.color = new Color();
-		this.colorNode = uniform( this.color );
 
+		/**
+		 * The light's color node. Points to `colorNode` of the light source, if set. Otherwise
+		 * it creates a uniform node based on {@link AnalyticLightNode#color}.
+		 *
+		 * @type {Node}
+		 */
+		this.colorNode = ( light && light.colorNode ) || uniform( this.color ).setGroup( renderGroup );
+
+		/**
+		 * This property is used to retain a reference to the original value of {@link AnalyticLightNode#colorNode}.
+		 * The final color node is represented by a different node when using shadows.
+		 *
+		 * @type {?Node}
+		 * @default null
+		 */
 		this.baseColorNode = null;
 
-		this.shadowMap = null;
+		/**
+		 * Represents the light's shadow.
+		 *
+		 * @type {?ShadowNode}
+   		 * @default null
+		 */
 		this.shadowNode = null;
+
+		/**
+		 * Represents the light's shadow color.
+		 *
+		 * @type {?Node}
+   		 * @default null
+		 */
 		this.shadowColorNode = null;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isAnalyticLightNode = true;
 
+		/**
+		 * Overwritten since analytic light nodes are updated
+		 * once per frame.
+		 *
+		 * @type {string}
+		 * @default 'frame'
+		 */
+		this.updateType = NodeUpdateType.FRAME;
+
 	}
 
-	getCacheKey() {
+	/**
+	 * Overwrites the default {@link Node#customCacheKey} implementation by including the
+	 * `light.id` and `light.castShadow` into the cache key.
+	 *
+	 * @return {number} The custom cache key.
+	 */
+	customCacheKey() {
 
-		return super.getCacheKey() + '-' + ( this.light.id + '-' + ( this.light.castShadow ? '1' : '0' ) );
+		return hash( this.light.id, this.light.castShadow ? 1 : 0 );
 
 	}
 
@@ -156,79 +117,68 @@ class AnalyticLightNode extends LightingNode {
 
 	}
 
-	setupShadow( builder ) {
-
-		const { object, renderer } = builder;
+	getLightVector( builder ) {
 
-		let shadowColorNode = this.shadowColorNode;
-
-		if ( shadowColorNode === null ) {
+		return lightViewPosition( this.light ).sub( builder.context.positionView || positionView );
 
-			if ( overrideMaterial === null ) {
-
-				overrideMaterial = builder.createNodeMaterial();
-				overrideMaterial.fragmentNode = vec4( 0, 0, 0, 1 );
-				overrideMaterial.isShadowNodeMaterial = true; // Use to avoid other overrideMaterial override material.fragmentNode unintentionally when using material.shadowNode
-
-			}
-
-			const depthTexture = new DepthTexture();
-			depthTexture.compareFunction = LessCompare;
+	}
 
-			const shadow = this.light.shadow;
-			const shadowMap = builder.createRenderTarget( shadow.mapSize.width, shadow.mapSize.height );
-			shadowMap.depthTexture = depthTexture;
+	/**
+	 * Sets up the direct lighting for the analytic light node.
+	 *
+	 * @abstract
+	 * @param {NodeBuilder} builder - The builder object used for setting up the light.
+	 */
+	setupDirect( /*builder*/ ) { }
 
-			shadow.camera.updateProjectionMatrix();
+	setupDirectRectArea( /*builder*/ ) { }
 
-			//
+	/**
+	 * Setups the shadow node for this light. The method exists so concrete light classes
+	 * can setup different types of shadow nodes.
+	 *
+	 * @return {ShadowNode} The created shadow node.
+	 */
+	setupShadowNode() {
 
-			const shadowIntensity = reference( 'intensity', 'float', shadow );
-			const bias = reference( 'bias', 'float', shadow );
-			const normalBias = reference( 'normalBias', 'float', shadow );
+		return shadow( this.light );
 
-			const position = object.material.shadowPositionNode || positionWorld;
+	}
 
-			let shadowCoord = uniform( shadow.matrix ).mul( position.add( normalWorld.mul( normalBias ) ) );
-			shadowCoord = shadowCoord.xyz.div( shadowCoord.w );
+	/**
+	 * Setups the shadow for this light. This method is only executed if the light
+	 * cast shadows and the current build object receives shadows. It incorporates
+	 * shadows into the lighting computation.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 */
+	setupShadow( builder ) {
 
-			let coordZ = shadowCoord.z.add( bias );
+		const { renderer } = builder;
 
-			if ( renderer.coordinateSystem === WebGPUCoordinateSystem ) {
+		if ( renderer.shadowMap.enabled === false ) return;
 
-				coordZ = coordZ.mul( 2 ).sub( 1 ); // WebGPU: Convertion [ 0, 1 ] to [ - 1, 1 ]
+		let shadowColorNode = this.shadowColorNode;
 
-			}
+		if ( shadowColorNode === null ) {
 
-			shadowCoord = vec3(
-				shadowCoord.x,
-				shadowCoord.y.oneMinus(), // follow webgpu standards
-				coordZ
-			);
+			const customShadowNode = this.light.shadow.shadowNode;
 
-			const frustumTest = shadowCoord.x.greaterThanEqual( 0 )
-				.and( shadowCoord.x.lessThanEqual( 1 ) )
-				.and( shadowCoord.y.greaterThanEqual( 0 ) )
-				.and( shadowCoord.y.lessThanEqual( 1 ) )
-				.and( shadowCoord.z.lessThanEqual( 1 ) );
+			let shadowNode;
 
-			//
+			if ( customShadowNode !== undefined ) {
 
-			const filterFn = shadow.filterNode || shadowFilterLib[ renderer.shadowMap.type ] || null;
+				shadowNode = nodeObject( customShadowNode );
 
-			if ( filterFn === null ) {
+			} else {
 
-				throw new Error( 'THREE.WebGPURenderer: Shadow map type not supported yet.' );
+				shadowNode = this.setupShadowNode( builder );
 
 			}
 
-			const shadowColor = texture( shadowMap.texture, shadowCoord );
-			const shadowNode = frustumTest.select( filterFn( { depthTexture, shadowCoord, shadow } ), float( 1 ) );
-
-			this.shadowMap = shadowMap;
-
 			this.shadowNode = shadowNode;
-			this.shadowColorNode = shadowColorNode = this.colorNode.mul( mix( 1, shadowNode.rgb.mix( shadowColor, 1 ), shadowIntensity.mul( shadowColor.a ) ) );
+
+			this.shadowColorNode = shadowColorNode = this.colorNode.mul( shadowNode );
 
 			this.baseColorNode = this.colorNode;
 
@@ -238,10 +188,15 @@ class AnalyticLightNode extends LightingNode {
 
 		this.colorNode = shadowColorNode;
 
-		this.updateBeforeType = NodeUpdateType.RENDER;
-
 	}
 
+	/**
+	 * Unlike most other nodes, lighting nodes do not return a output node in {@link Node#setup}.
+	 * The main purpose of lighting nodes is to configure the current {@link LightingModel} and/or
+	 * invocate the respective interface methods.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 */
 	setup( builder ) {
 
 		this.colorNode = this.baseColorNode || this.colorNode;
@@ -256,69 +211,36 @@ class AnalyticLightNode extends LightingNode {
 
 		} else if ( this.shadowNode !== null ) {
 
-			this.disposeShadow();
+			this.shadowNode.dispose();
+			this.shadowNode = null;
+			this.shadowColorNode = null;
 
 		}
 
-	}
-
-	updateShadow( frame ) {
-
-		const { shadowMap, light } = this;
-		const { renderer, scene, camera } = frame;
-
-		const currentOverrideMaterial = scene.overrideMaterial;
-
-		scene.overrideMaterial = overrideMaterial;
-
-		shadowMap.setSize( light.shadow.mapSize.width, light.shadow.mapSize.height );
-
-		light.shadow.updateMatrices( light );
-		light.shadow.camera.layers.mask = camera.layers.mask;
-
-		const currentRenderTarget = renderer.getRenderTarget();
-		const currentRenderObjectFunction = renderer.getRenderObjectFunction();
-
-		renderer.setRenderObjectFunction( ( object, ...params ) => {
-
-			if ( object.castShadow === true ) {
-
-				renderer.renderObject( object, ...params );
-
-			}
-
-		} );
+		const directLightData = this.setupDirect( builder );
+		const directRectAreaLightData = this.setupDirectRectArea( builder );
 
-		renderer.setRenderTarget( shadowMap );
-		renderer.render( scene, light.shadow.camera );
+		if ( directLightData ) {
 
-		renderer.setRenderTarget( currentRenderTarget );
-		renderer.setRenderObjectFunction( currentRenderObjectFunction );
+			builder.lightsNode.setupDirectLight( builder, this, directLightData );
 
-		scene.overrideMaterial = currentOverrideMaterial;
-
-	}
-
-	disposeShadow() {
-
-		this.shadowMap.dispose();
-		this.shadowMap = null;
-
-		this.shadowNode = null;
-		this.shadowColorNode = null;
-
-		this.baseColorNode = null;
+		}
 
-		this.updateBeforeType = NodeUpdateType.NONE;
+		if ( directRectAreaLightData ) {
 
-	}
+			builder.lightsNode.setupDirectRectAreaLight( builder, this, directRectAreaLightData );
 
-	updateBefore( frame ) {
-
-		this.updateShadow( frame );
+		}
 
 	}
 
+	/**
+	 * The update method is used to update light uniforms per frame.
+	 * Potentially overwritten in concrete light nodes to update light
+	 * specific uniforms.
+	 *
+	 * @param {NodeFrame} frame - A reference to the current node frame.
+	 */
 	update( /*frame*/ ) {
 
 		const { light } = this;
@@ -330,5 +252,3 @@ class AnalyticLightNode extends LightingNode {
 }
 
 export default AnalyticLightNode;
-
-addNodeClass( 'AnalyticLightNode', AnalyticLightNode );

package/src/nodes/lighting/BasicEnvironmentNode.js

@@ -1,13 +1,37 @@
 import LightingNode from './LightingNode.js';
-import { addNodeClass } from '../core/Node.js';
 import { cubeMapNode } from '../utils/CubeMapNode.js';
 
+/**
+ * Represents a basic model for Image-based lighting (IBL). The environment
+ * is defined via environment maps in the equirectangular or cube map format.
+ * `BasicEnvironmentNode` is intended for non-PBR materials like {@link MeshBasicNodeMaterial}
+ * or {@link MeshPhongNodeMaterial}.
+ *
+ * @augments LightingNode
+ */
 class BasicEnvironmentNode extends LightingNode {
 
+	static get type() {
+
+		return 'BasicEnvironmentNode';
+
+	}
+
+	/**
+	 * Constructs a new basic environment node.
+	 *
+	 * @param {Node} [envNode=null] - A node representing the environment.
+	 */
 	constructor( envNode = null ) {
 
 		super();
 
+		/**
+		 * A node representing the environment.
+		 *
+		 * @type {Node}
+		 * @default null
+		 */
 		this.envNode = envNode;
 
 	}
@@ -23,5 +47,3 @@ class BasicEnvironmentNode extends LightingNode {
 }
 
 export default BasicEnvironmentNode;
-
-addNodeClass( 'BasicEnvironmentNode', BasicEnvironmentNode );

package/src/nodes/lighting/BasicLightMapNode.js

@@ -1,13 +1,35 @@
 import LightingNode from './LightingNode.js';
-import { addNodeClass } from '../core/Node.js';
-import { float } from '../shadernode/ShaderNode.js';
-
+import { float } from '../tsl/TSLBase.js';
+
+/**
+ * A specific version of {@link IrradianceNode} that is only relevant
+ * for {@link MeshBasicNodeMaterial}. Since the material is unlit, it
+ * requires a special scaling factor for the light map.
+ *
+ * @augments LightingNode
+ */
 class BasicLightMapNode extends LightingNode {
 
+	static get type() {
+
+		return 'BasicLightMapNode';
+
+	}
+
+	/**
+	 * Constructs a new basic light map node.
+	 *
+	 * @param {?Node<vec3>} [lightMapNode=null] - The light map node.
+	 */
 	constructor( lightMapNode = null ) {
 
 		super();
 
+		/**
+		 * The light map node.
+		 *
+		 * @type {?Node<vec3>}
+		 */
 		this.lightMapNode = lightMapNode;
 
 	}
@@ -25,5 +47,3 @@ class BasicLightMapNode extends LightingNode {
 }
 
 export default BasicLightMapNode;
-
-addNodeClass( 'BasicLightMapNode', BasicLightMapNode );

package/src/nodes/lighting/DirectionalLightNode.js

@@ -1,40 +1,39 @@
 import AnalyticLightNode from './AnalyticLightNode.js';
-import { lightTargetDirection } from './LightNode.js';
-import { addLightNode } from './LightsNode.js';
-import { addNodeClass } from '../core/Node.js';
-
-import { DirectionalLight } from '../../lights/DirectionalLight.js';
+import { lightTargetDirection } from '../accessors/Lights.js';
 
+/**
+ * Module for representing directional lights as nodes.
+ *
+ * @augments AnalyticLightNode
+ */
 class DirectionalLightNode extends AnalyticLightNode {
 
-	constructor( light = null ) {
+	static get type() {
 
-		super( light );
+		return 'DirectionalLightNode';
 
 	}
 
-	setup( builder ) {
+	/**
+	 * Constructs a new directional light node.
+	 *
+	 * @param {?DirectionalLight} [light=null] - The directional light source.
+	 */
+	constructor( light = null ) {
 
-		super.setup( builder );
+		super( light );
 
-		const lightingModel = builder.context.lightingModel;
+	}
+
+	setupDirect() {
 
 		const lightColor = this.colorNode;
 		const lightDirection = lightTargetDirection( this.light );
-		const reflectedLight = builder.context.reflectedLight;
 
-		lightingModel.direct( {
-			lightDirection,
-			lightColor,
-			reflectedLight
-		}, builder.stack, builder );
+		return { lightDirection, lightColor };
 
 	}
 
 }
 
 export default DirectionalLightNode;
-
-addNodeClass( 'DirectionalLightNode', DirectionalLightNode );
-
-addLightNode( DirectionalLight, DirectionalLightNode );