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

package/src/nodes/lighting/LightsNode.js

@@ -1,5 +1,7 @@
 import Node from '../core/Node.js';
-import { nodeObject, nodeProxy, vec3 } from '../tsl/TSLBase.js';
+import { nodeObject, property, vec3 } from '../tsl/TSLBase.js';
+import { hashArray } from '../core/NodeUtils.js';
+import { warn } from '../../utils.js';
 
 const sortLights = ( lights ) => {
 
@@ -24,7 +26,15 @@ const getLightNodeById = ( id, lightNodes ) => {
 };
 
 const _lightsNodeRef = /*@__PURE__*/ new WeakMap();
-
+const _hashData = [];
+
+/**
+ * This node represents the scene's lighting and manages the lighting model's life cycle
+ * for the current build 3D object. It is responsible for computing the total outgoing
+ * light in a given lighting context.
+ *
+ * @augments Node
+ */
 class LightsNode extends Node {
 
 	static get type() {
@@ -33,24 +43,113 @@ class LightsNode extends Node {
 
 	}
 
-	constructor( lights = [] ) {
+	/**
+	 * Constructs a new lights node.
+	 */
+	constructor() {
 
 		super( 'vec3' );
 
-		this.totalDiffuseNode = vec3().toVar( 'totalDiffuse' );
-		this.totalSpecularNode = vec3().toVar( 'totalSpecular' );
-
-		this.outgoingLightNode = vec3().toVar( 'outgoingLight' );
-
-		this._lights = lights;
-
+		/**
+		 * A node representing the total diffuse light.
+		 *
+		 * @type {Node<vec3>}
+		 */
+		this.totalDiffuseNode = property( 'vec3', 'totalDiffuse' );
+
+		/**
+		 * A node representing the total specular light.
+		 *
+		 * @type {Node<vec3>}
+		 */
+		this.totalSpecularNode = property( 'vec3', 'totalSpecular' );
+
+		/**
+		 * A node representing the outgoing light.
+		 *
+		 * @type {Node<vec3>}
+		 */
+		this.outgoingLightNode = property( 'vec3', 'outgoingLight' );
+
+		/**
+		 * An array representing the lights in the scene.
+		 *
+		 * @private
+		 * @type {Array<Light>}
+		 */
+		this._lights = [];
+
+		/**
+		 * For each light in the scene, this node will create a
+		 * corresponding light node.
+		 *
+		 * @private
+		 * @type {?Array<LightingNode>}
+		 * @default null
+		 */
 		this._lightNodes = null;
+
+		/**
+		 * A hash for identifying the current light nodes setup.
+		 *
+		 * @private
+		 * @type {?string}
+		 * @default null
+		 */
 		this._lightNodesHash = null;
 
+		/**
+		 * `LightsNode` sets this property to `true` by default.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.global = true;
 
 	}
 
+	/**
+	 * Overwrites the default {@link Node#customCacheKey} implementation by including
+	 * light data into the cache key.
+	 *
+	 * @return {number} The custom cache key.
+	 */
+	customCacheKey() {
+
+		const lights = this._lights;
+
+		for ( let i = 0; i < lights.length; i ++ ) {
+
+			const light = lights[ i ];
+
+			_hashData.push( light.id );
+			_hashData.push( light.castShadow ? 1 : 0 );
+
+			if ( light.isSpotLight === true ) {
+
+				const hashMap = ( light.map !== null ) ? light.map.id : - 1;
+				const hashColorNode = ( light.colorNode ) ? light.colorNode.getCacheKey() : - 1;
+
+				_hashData.push( hashMap, hashColorNode );
+
+			}
+
+		}
+
+		const cacheKey = hashArray( _hashData );
+
+		_hashData.length = 0;
+
+		return cacheKey;
+
+	}
+
+	/**
+	 * Computes a hash value for identifying the current light nodes setup.
+	 *
+	 * @param {NodeBuilder} builder - A reference to the current node builder.
+	 * @return {string} The computed hash.
+	 */
 	getHash( builder ) {
 
 		if ( this._lightNodesHash === null ) {
@@ -75,7 +174,7 @@ class LightsNode extends Node {
 
 	analyze( builder ) {
 
-		const properties = builder.getDataFromNode( this );
+		const properties = builder.getNodeProperties( this );
 
 		for ( const node of properties.nodes ) {
 
@@ -83,8 +182,16 @@ class LightsNode extends Node {
 
 		}
 
+		properties.outputNode.build( builder );
+
 	}
 
+	/**
+	 * Creates lighting nodes for each scene light. This makes it possible to further
+	 * process lights in the node system.
+	 *
+	 * @param {NodeBuilder} builder - A reference to the current node builder.
+	 */
 	setupLightsNode( builder ) {
 
 		const lightNodes = [];
@@ -92,7 +199,7 @@ class LightsNode extends Node {
 		const previousLightNodes = this._lightNodes;
 
 		const lights = sortLights( this._lights );
-		const nodeLibrary = builder.renderer.nodes.library;
+		const nodeLibrary = builder.renderer.library;
 
 		for ( const light of lights ) {
 
@@ -106,17 +213,19 @@ class LightsNode extends Node {
 
 				if ( previousLightNodes !== null ) {
 
-					lightNode = getLightNodeById( light.id, previousLightNodes ); // resuse existing light node
+					lightNode = getLightNodeById( light.id, previousLightNodes ); // reuse existing light node
 
 				}
 
 				if ( lightNode === null ) {
 
+					// find the corresponding node type for a given light
+
 					const lightNodeClass = nodeLibrary.getLightNodeClass( light.constructor );
 
 					if ( lightNodeClass === null ) {
 
-						console.warn( `LightsNode.setupNodeLights: Light node not found for ${ light.constructor.name }` );
+						warn( `LightsNode.setupNodeLights: Light node not found for ${ light.constructor.name }` );
 						continue;
 
 					}
@@ -146,18 +255,88 @@ class LightsNode extends Node {
 
 	}
 
-	setup( builder ) {
+	/**
+	 * Sets up a direct light in the lighting model.
+	 *
+	 * @param {Object} builder - The builder object containing the context and stack.
+	 * @param {Object} lightNode - The light node.
+	 * @param {Object} lightData - The light object containing color and direction properties.
+	 */
+	setupDirectLight( builder, lightNode, lightData ) {
+
+		const { lightingModel, reflectedLight } = builder.context;
+
+		lightingModel.direct( {
+			...lightData,
+			lightNode,
+			reflectedLight
+		}, builder );
+
+	}
+
+	setupDirectRectAreaLight( builder, lightNode, lightData ) {
+
+		const { lightingModel, reflectedLight } = builder.context;
+
+		lightingModel.directRectArea( {
+			...lightData,
+			lightNode,
+			reflectedLight
+		}, builder );
+
+	}
+
+	/**
+	 * Setups the internal lights by building all respective
+	 * light nodes.
+	 *
+	 * @param {NodeBuilder} builder - A reference to the current node builder.
+	 * @param {Array<LightingNode>} lightNodes - An array of lighting nodes.
+	 */
+	setupLights( builder, lightNodes ) {
+
+		for ( const lightNode of lightNodes ) {
+
+			lightNode.build( builder );
+
+		}
+
+	}
+
+	getLightNodes( builder ) {
 
 		if ( this._lightNodes === null ) this.setupLightsNode( builder );
 
+		return this._lightNodes;
+
+	}
+
+	/**
+	 * The implementation makes sure that for each light in the scene
+	 * there is a corresponding light node. By building the light nodes
+	 * and evaluating the lighting model the outgoing light is computed.
+	 *
+	 * @param {NodeBuilder} builder - A reference to the current node builder.
+	 * @return {Node<vec3>} A node representing the outgoing light.
+	 */
+	setup( builder ) {
+
+		const currentLightsNode = builder.lightsNode;
+
+		builder.lightsNode = this;
+
+		//
+
+		let outgoingLightNode = this.outgoingLightNode;
+
 		const context = builder.context;
 		const lightingModel = context.lightingModel;
 
-		let outgoingLightNode = this.outgoingLightNode;
+		const properties = builder.getNodeProperties( this );
 
 		if ( lightingModel ) {
 
-			const { _lightNodes, totalDiffuseNode, totalSpecularNode } = this;
+			const { totalDiffuseNode, totalSpecularNode } = this;
 
 			context.outgoingLight = outgoingLightNode;
 
@@ -165,24 +344,11 @@ class LightsNode extends Node {
 
 			//
 
-			const properties = builder.getDataFromNode( this );
 			properties.nodes = stack.nodes;
 
 			//
 
-			lightingModel.start( context, stack, builder );
-
-			// lights
-
-			for ( const lightNode of _lightNodes ) {
-
-				lightNode.build( builder );
-
-			}
-
-			//
-
-			lightingModel.indirect( context, stack, builder );
+			lightingModel.start( builder );
 
 			//
 
@@ -203,8 +369,6 @@ class LightsNode extends Node {
 
 				}
 
-				context.material.transparent = true;
-
 			}
 
 			totalDiffuseNode.assign( totalDiffuse );
@@ -214,18 +378,32 @@ class LightsNode extends Node {
 
 			//
 
-			lightingModel.finish( context, stack, builder );
+			lightingModel.finish( builder );
 
 			//
 
 			outgoingLightNode = outgoingLightNode.bypass( builder.removeStack() );
 
+		} else {
+
+			properties.nodes = [];
+
 		}
 
+		//
+
+		builder.lightsNode = currentLightsNode;
+
 		return outgoingLightNode;
 
 	}
 
+	/**
+	 * Configures this node with an array of lights.
+	 *
+	 * @param {Array<Light>} lights - An array of lights.
+	 * @return {LightsNode} A reference to this node.
+	 */
 	setLights( lights ) {
 
 		this._lights = lights;
@@ -237,14 +415,39 @@ class LightsNode extends Node {
 
 	}
 
+	/**
+	 * Returns an array of the scene's lights.
+	 *
+	 * @return {Array<Light>} The scene's lights.
+	 */
 	getLights() {
 
 		return this._lights;
 
 	}
 
+	/**
+	 * Whether the scene has lights or not.
+	 *
+	 * @type {boolean}
+	 */
+	get hasLights() {
+
+		return this._lights.length > 0;
+
+	}
+
 }
 
 export default LightsNode;
 
-export const lights = /*@__PURE__*/ nodeProxy( LightsNode );
+/**
+ * TSL function for creating an instance of `LightsNode` and configuring
+ * it with the given array of lights.
+ *
+ * @tsl
+ * @function
+ * @param {Array<Light>} lights - An array of lights.
+ * @return {LightsNode} The created lights node.
+ */
+export const lights = ( lights = [] ) => new LightsNode().setLights( lights );

package/src/nodes/lighting/PointLightNode.js

@@ -1,10 +1,31 @@
 import AnalyticLightNode from './AnalyticLightNode.js';
 import { getDistanceAttenuation } from './LightUtils.js';
 import { uniform } from '../core/UniformNode.js';
-import { lightViewPosition } from '../accessors/Lights.js';
-import { positionView } from '../accessors/Position.js';
-import { renderGroup } from '../TSL.js';
+import { renderGroup } from '../core/UniformGroupNode.js';
+import { pointShadow } from './PointShadowNode.js';
 
+export const directPointLight = ( { color, lightVector, cutoffDistance, decayExponent } ) => {
+
+	const lightDirection = lightVector.normalize();
+	const lightDistance = lightVector.length();
+
+	const attenuation = getDistanceAttenuation( {
+		lightDistance,
+		cutoffDistance,
+		decayExponent
+	} );
+
+	const lightColor = color.mul( attenuation );
+
+	return { lightDirection, lightColor };
+
+};
+
+/**
+ * Module for representing point lights as nodes.
+ *
+ * @augments AnalyticLightNode
+ */
 class PointLightNode extends AnalyticLightNode {
 
 	static get type() {
@@ -13,15 +34,36 @@ class PointLightNode extends AnalyticLightNode {
 
 	}
 
+	/**
+	 * Constructs a new point light node.
+	 *
+	 * @param {?PointLight} [light=null] - The point light source.
+	 */
 	constructor( light = null ) {
 
 		super( light );
 
+		/**
+		 * Uniform node representing the cutoff distance.
+		 *
+		 * @type {UniformNode<float>}
+		 */
 		this.cutoffDistanceNode = uniform( 0 ).setGroup( renderGroup );
-		this.decayExponentNode = uniform( 0 ).setGroup( renderGroup );
+
+		/**
+		 * Uniform node representing the decay exponent.
+		 *
+		 * @type {UniformNode<float>}
+		 */
+		this.decayExponentNode = uniform( 2 ).setGroup( renderGroup );
 
 	}
 
+	/**
+	 * Overwritten to updated point light specific uniforms.
+	 *
+	 * @param {NodeFrame} frame - A reference to the current node frame.
+	 */
 	update( frame ) {
 
 		const { light } = this;
@@ -33,33 +75,26 @@ class PointLightNode extends AnalyticLightNode {
 
 	}
 
-	setup( builder ) {
-
-		const { colorNode, cutoffDistanceNode, decayExponentNode, light } = this;
+	/**
+	 * Overwritten to setup point light specific shadow.
+	 *
+	 * @return {PointShadowNode}
+	 */
+	setupShadowNode() {
 
-		const lightingModel = builder.context.lightingModel;
+		return pointShadow( this.light );
 
-		const lVector = lightViewPosition( light ).sub( positionView ); // @TODO: Add it into LightNode
+	}
 
-		const lightDirection = lVector.normalize();
-		const lightDistance = lVector.length();
+	setupDirect( builder ) {
 
-		const lightAttenuation = getDistanceAttenuation( {
-			lightDistance,
-			cutoffDistance: cutoffDistanceNode,
-			decayExponent: decayExponentNode
+		return directPointLight( {
+			color: this.colorNode,
+			lightVector: this.getLightVector( builder ),
+			cutoffDistance: this.cutoffDistanceNode,
+			decayExponent: this.decayExponentNode
 		} );
 
-		const lightColor = colorNode.mul( lightAttenuation );
-
-		const reflectedLight = builder.context.reflectedLight;
-
-		lightingModel.direct( {
-			lightDirection,
-			lightColor,
-			reflectedLight
-		}, builder.stack, builder );
-
 	}
 
 }