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

package/src/nodes/lighting/BasicEnvironmentNode.js

@@ -1,6 +1,14 @@
 import LightingNode from './LightingNode.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() {
@@ -9,10 +17,21 @@ class BasicEnvironmentNode extends LightingNode {
 
 	}
 
+	/**
+	 * 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;
 
 	}

package/src/nodes/lighting/BasicLightMapNode.js

@@ -1,6 +1,13 @@
 import LightingNode from './LightingNode.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() {
@@ -9,10 +16,20 @@ class BasicLightMapNode extends LightingNode {
 
 	}
 
+	/**
+	 * 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;
 
 	}

package/src/nodes/lighting/DirectionalLightNode.js

@@ -1,6 +1,11 @@
 import AnalyticLightNode from './AnalyticLightNode.js';
 import { lightTargetDirection } from '../accessors/Lights.js';
 
+/**
+ * Module for representing directional lights as nodes.
+ *
+ * @augments AnalyticLightNode
+ */
 class DirectionalLightNode extends AnalyticLightNode {
 
 	static get type() {
@@ -9,27 +14,23 @@ class DirectionalLightNode extends AnalyticLightNode {
 
 	}
 
+	/**
+	 * Constructs a new directional light node.
+	 *
+	 * @param {?DirectionalLight} [light=null] - The directional light source.
+	 */
 	constructor( light = null ) {
 
 		super( light );
 
 	}
 
-	setup( builder ) {
-
-		super.setup( builder );
-
-		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 };
 
 	}
 

package/src/nodes/lighting/EnvironmentNode.js

@@ -1,16 +1,23 @@
 import LightingNode from './LightingNode.js';
-import { cache } from '../core/CacheNode.js';
+import { isolate } from '../core/IsolateNode.js';
 import { roughness, clearcoatRoughness } from '../core/PropertyNode.js';
 import { cameraViewMatrix } from '../accessors/Camera.js';
-import { transformedClearcoatNormalView, transformedNormalView, transformedNormalWorld } from '../accessors/Normal.js';
+import { normalView, clearcoatNormalView, normalWorld } from '../accessors/Normal.js';
 import { positionViewDirection } from '../accessors/Position.js';
-import { float } from '../tsl/TSLBase.js';
-import { reference } from '../accessors/ReferenceNode.js';
-import { transformedBentNormalView } from '../accessors/AccessorsUtils.js';
+import { float, pow4 } from '../tsl/TSLBase.js';
+import { bentNormalView } from '../accessors/AccessorsUtils.js';
 import { pmremTexture } from '../pmrem/PMREMNode.js';
+import { materialEnvIntensity } from '../accessors/MaterialProperties.js';
 
-const _envNodeCache = new WeakMap();
+const _rendererCache = new WeakMap();
 
+/**
+ * Represents a physical model for Image-based lighting (IBL). The environment
+ * is defined via environment maps in the equirectangular, cube map or cubeUV (PMREM) format.
+ * `EnvironmentNode` is intended for PBR materials like {@link MeshStandardNodeMaterial}.
+ *
+ * @augments LightingNode
+ */
 class EnvironmentNode extends LightingNode {
 
 	static get type() {
@@ -19,10 +26,21 @@ class EnvironmentNode extends LightingNode {
 
 	}
 
+	/**
+	 * Constructs a new 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;
 
 	}
@@ -37,13 +55,15 @@ class EnvironmentNode extends LightingNode {
 
 			const value = ( envNode.isTextureNode ) ? envNode.value : material[ envNode.property ];
 
-			let cacheEnvNode = _envNodeCache.get( value );
+			const cache = this._getPMREMNodeCache( builder.renderer );
+
+			let cacheEnvNode = cache.get( value );
 
 			if ( cacheEnvNode === undefined ) {
 
 				cacheEnvNode = pmremTexture( value );
 
-				_envNodeCache.set( value, cacheEnvNode );
+				cache.set( value, cacheEnvNode );
 
 			}
 
@@ -53,17 +73,14 @@ class EnvironmentNode extends LightingNode {
 
 		//
 
-		const envMap = material.envMap;
-		const intensity = envMap ? reference( 'envMapIntensity', 'float', builder.material ) : reference( 'environmentIntensity', 'float', builder.scene ); // @TODO: Add materialEnvIntensity in MaterialNode
-
 		const useAnisotropy = material.useAnisotropy === true || material.anisotropy > 0;
-		const radianceNormalView = useAnisotropy ? transformedBentNormalView : transformedNormalView;
+		const radianceNormalView = useAnisotropy ? bentNormalView : normalView;
 
-		const radiance = envNode.context( createRadianceContext( roughness, radianceNormalView ) ).mul( intensity );
-		const irradiance = envNode.context( createIrradianceContext( transformedNormalWorld ) ).mul( Math.PI ).mul( intensity );
+		const radiance = envNode.context( createRadianceContext( roughness, radianceNormalView ) ).mul( materialEnvIntensity );
+		const irradiance = envNode.context( createIrradianceContext( normalWorld ) ).mul( Math.PI ).mul( materialEnvIntensity );
 
-		const isolateRadiance = cache( radiance );
-		const isolateIrradiance = cache( irradiance );
+		const isolateRadiance = isolate( radiance );
+		const isolateIrradiance = isolate( irradiance );
 
 		//
 
@@ -77,8 +94,8 @@ class EnvironmentNode extends LightingNode {
 
 		if ( clearcoatRadiance ) {
 
-			const clearcoatRadianceContext = envNode.context( createRadianceContext( clearcoatRoughness, transformedClearcoatNormalView ) ).mul( intensity );
-			const isolateClearcoatRadiance = cache( clearcoatRadianceContext );
+			const clearcoatRadianceContext = envNode.context( createRadianceContext( clearcoatRoughness, clearcoatNormalView ) ).mul( materialEnvIntensity );
+			const isolateClearcoatRadiance = isolate( clearcoatRadianceContext );
 
 			clearcoatRadiance.addAssign( isolateClearcoatRadiance );
 
@@ -86,6 +103,29 @@ class EnvironmentNode extends LightingNode {
 
 	}
 
+	/**
+	 * Returns the PMREM node cache of the current renderer.
+	 *
+	 * @private
+	 * @param {Renderer} renderer - The current renderer.
+	 * @return {WeakMap} The node cache.
+	 */
+	_getPMREMNodeCache( renderer ) {
+
+		let pmremCache = _rendererCache.get( renderer );
+
+		if ( pmremCache === undefined ) {
+
+			pmremCache = new WeakMap();
+
+			_rendererCache.set( renderer, pmremCache );
+
+		}
+
+		return pmremCache;
+
+	}
+
 }
 
 export default EnvironmentNode;
@@ -102,7 +142,7 @@ const createRadianceContext = ( roughnessNode, normalViewNode ) => {
 				reflectVec = positionViewDirection.negate().reflect( normalViewNode );
 
 				// Mixing the reflection with the normal is more accurate and keeps rough objects from gathering light from behind their tangent plane.
-				reflectVec = roughnessNode.mul( roughnessNode ).mix( reflectVec, normalViewNode ).normalize();
+				reflectVec = pow4( roughnessNode ).mix( reflectVec, normalViewNode ).normalize();
 
 				reflectVec = reflectVec.transformDirection( cameraViewMatrix );
 

package/src/nodes/lighting/HemisphereLightNode.js

@@ -1,12 +1,17 @@
 import AnalyticLightNode from './AnalyticLightNode.js';
 import { uniform } from '../core/UniformNode.js';
 import { mix } from '../math/MathNode.js';
-import { normalView } from '../accessors/Normal.js';
+import { normalWorld } from '../accessors/Normal.js';
 import { lightPosition } from '../accessors/Lights.js';
 import { renderGroup } from '../core/UniformGroupNode.js';
 
 import { Color } from '../../math/Color.js';
 
+/**
+ * Module for representing hemisphere lights as nodes.
+ *
+ * @augments AnalyticLightNode
+ */
 class HemisphereLightNode extends AnalyticLightNode {
 
 	static get type() {
@@ -15,17 +20,43 @@ class HemisphereLightNode extends AnalyticLightNode {
 
 	}
 
+	/**
+	 * Constructs a new hemisphere light node.
+	 *
+	 * @param {?HemisphereLight} [light=null] - The hemisphere light source.
+	 */
 	constructor( light = null ) {
 
 		super( light );
 
+		/**
+		 * Uniform node representing the light's position.
+		 *
+		 * @type {UniformNode<vec3>}
+		 */
 		this.lightPositionNode = lightPosition( light );
+
+		/**
+		 * A node representing the light's direction.
+		 *
+		 * @type {Node<vec3>}
+		 */
 		this.lightDirectionNode = this.lightPositionNode.normalize();
 
+		/**
+		 * Uniform node representing the light's ground color.
+		 *
+		 * @type {UniformNode<vec3>}
+		 */
 		this.groundColorNode = uniform( new Color() ).setGroup( renderGroup );
 
 	}
 
+	/**
+	 * Overwritten to updated hemisphere light specific uniforms.
+	 *
+	 * @param {NodeFrame} frame - A reference to the current node frame.
+	 */
 	update( frame ) {
 
 		const { light } = this;
@@ -42,7 +73,7 @@ class HemisphereLightNode extends AnalyticLightNode {
 
 		const { colorNode, groundColorNode, lightDirectionNode } = this;
 
-		const dotNL = normalView.dot( lightDirectionNode );
+		const dotNL = normalWorld.dot( lightDirectionNode );
 		const hemiDiffuseWeight = dotNL.mul( 0.5 ).add( 0.5 );
 
 		const irradiance = mix( groundColorNode, colorNode, hemiDiffuseWeight );

package/src/nodes/lighting/IESSpotLightNode.js

@@ -2,6 +2,11 @@ import SpotLightNode from './SpotLightNode.js';
 import { texture } from '../accessors/TextureNode.js';
 import { vec2 } from '../tsl/TSLBase.js';
 
+/**
+ * An IES version of the default spot light node.
+ *
+ * @augments SpotLightNode
+ */
 class IESSpotLightNode extends SpotLightNode {
 
 	static get type() {
@@ -10,7 +15,14 @@ class IESSpotLightNode extends SpotLightNode {
 
 	}
 
-	getSpotAttenuation( angleCosine ) {
+	/**
+	 * Overwrites the default implementation to compute an IES conform spot attenuation.
+	 *
+	 * @param {NodeBuilder} builder - The node builder.
+	 * @param {Node<float>} angleCosine - The angle to compute the spot attenuation for.
+	 * @return {Node<float>} The spot attenuation.
+	 */
+	getSpotAttenuation( builder, angleCosine ) {
 
 		const iesMap = this.light.iesMap;
 

package/src/nodes/lighting/IrradianceNode.js

@@ -1,5 +1,12 @@
 import LightingNode from './LightingNode.js';
 
+/**
+ * A generic class that can be used by nodes which contribute
+ * irradiance to the scene. E.g. a light map node can be used
+ * as input for this module. Used in {@link NodeMaterial}.
+ *
+ * @augments LightingNode
+ */
 class IrradianceNode extends LightingNode {
 
 	static get type() {
@@ -8,10 +15,20 @@ class IrradianceNode extends LightingNode {
 
 	}
 
+	/**
+	 * Constructs a new irradiance node.
+	 *
+	 * @param {Node<vec3>} node - A node contributing irradiance.
+	 */
 	constructor( node ) {
 
 		super();
 
+		/**
+		 * A node contributing irradiance.
+		 *
+		 * @type {Node<vec3>}
+		 */
 		this.node = node;
 
 	}

package/src/nodes/lighting/LightProbeNode.js

@@ -4,6 +4,11 @@ import { uniformArray } from '../accessors/UniformArrayNode.js';
 import { Vector3 } from '../../math/Vector3.js';
 import getShIrradianceAt from '../functions/material/getShIrradianceAt.js';
 
+/**
+ * Module for representing light probes as nodes.
+ *
+ * @augments AnalyticLightNode
+ */
 class LightProbeNode extends AnalyticLightNode {
 
 	static get type() {
@@ -12,6 +17,11 @@ class LightProbeNode extends AnalyticLightNode {
 
 	}
 
+	/**
+	 * Constructs a new light probe node.
+	 *
+	 * @param {?LightProbe} [light=null] - The light probe.
+	 */
 	constructor( light = null ) {
 
 		super( light );
@@ -20,10 +30,20 @@ class LightProbeNode extends AnalyticLightNode {
 
 		for ( let i = 0; i < 9; i ++ ) array.push( new Vector3() );
 
+		/**
+		 * Light probe represented as a uniform of spherical harmonics.
+		 *
+		 * @type {UniformArrayNode}
+		 */
 		this.lightProbe = uniformArray( array );
 
 	}
 
+	/**
+	 * Overwritten to updated light probe specific uniforms.
+	 *
+	 * @param {NodeFrame} frame - A reference to the current node frame.
+	 */
 	update( frame ) {
 
 		const { light } = this;

package/src/nodes/lighting/LightUtils.js

@@ -1,8 +1,16 @@
 import { Fn } from '../tsl/TSLBase.js';
 
-export const getDistanceAttenuation = /*@__PURE__*/ Fn( ( inputs ) => {
-
-	const { lightDistance, cutoffDistance, decayExponent } = inputs;
+/**
+ * Represents a `discard` shader operation in TSL.
+ *
+ * @method
+ * @param {Object} inputs - The input parameter object.
+ * @param {Node<float>} inputs.lightDistance - The distance of the light's position to the current fragment position.
+ * @param {Node<float>} inputs.cutoffDistance - The light's cutoff distance.
+ * @param {Node<float>} inputs.decayExponent - The light's decay exponent.
+ * @return {Node<float>} The distance falloff.
+ */
+export const getDistanceAttenuation = /*@__PURE__*/ Fn( ( { lightDistance, cutoffDistance, decayExponent } ) => {
 
 	// based upon Frostbite 3 Moving to Physically-based Rendering
 	// page 32, equation 26: E[window1]

package/src/nodes/lighting/LightingContextNode.js

@@ -1,6 +1,13 @@
 import ContextNode from '../core/ContextNode.js';
 import { nodeProxy, float, vec3 } from '../tsl/TSLBase.js';
 
+/**
+ * `LightingContextNode` represents an extension of the {@link ContextNode} module
+ * by adding lighting specific context data. It represents the runtime context of
+ * {@link LightsNode}.
+ *
+ * @augments ContextNode
+ */
 class LightingContextNode extends ContextNode {
 
 	static get type() {
@@ -9,18 +16,59 @@ class LightingContextNode extends ContextNode {
 
 	}
 
-	constructor( node, lightingModel = null, backdropNode = null, backdropAlphaNode = null ) {
-
-		super( node );
-
+	/**
+	 * Constructs a new lighting context node.
+	 *
+	 * @param {LightsNode} lightsNode - The lights node.
+	 * @param {?LightingModel} [lightingModel=null] - The current lighting model.
+	 * @param {?Node<vec3>} [backdropNode=null] - A backdrop node.
+	 * @param {?Node<float>} [backdropAlphaNode=null] - A backdrop alpha node.
+	 */
+	constructor( lightsNode, lightingModel = null, backdropNode = null, backdropAlphaNode = null ) {
+
+		super( lightsNode );
+
+		/**
+		 * The current lighting model.
+		 *
+		 * @type {?LightingModel}
+		 * @default null
+		 */
 		this.lightingModel = lightingModel;
+
+		/**
+		 * A backdrop node.
+		 *
+		 * @type {?Node<vec3>}
+		 * @default null
+		 */
 		this.backdropNode = backdropNode;
+
+		/**
+		 * A backdrop alpha node.
+		 *
+		 * @type {?Node<float>}
+		 * @default null
+		 */
 		this.backdropAlphaNode = backdropAlphaNode;
 
 		this._value = null;
 
 	}
 
+	/**
+	 * Returns a lighting context object.
+	 *
+	 * @return {{
+	 * radiance: Node<vec3>,
+	 * irradiance: Node<vec3>,
+	 * iblIrradiance: Node<vec3>,
+	 * ambientOcclusion: Node<float>,
+	 * reflectedLight: {directDiffuse: Node<vec3>, directSpecular: Node<vec3>, indirectDiffuse: Node<vec3>, indirectSpecular: Node<vec3>},
+	 * backdrop: Node<vec3>,
+	 * backdropAlpha: Node<float>
+	 * }} The lighting context object.
+	 */
 	getContext() {
 
 		const { backdropNode, backdropAlphaNode } = this;

package/src/nodes/lighting/LightingNode.js

@@ -1,5 +1,10 @@
 import Node from '../core/Node.js';
 
+/**
+ * Base class for lighting nodes.
+ *
+ * @augments Node
+ */
 class LightingNode extends Node {
 
 	static get type() {
@@ -8,20 +13,24 @@ class LightingNode extends Node {
 
 	}
 
+	/**
+	 * Constructs a new lighting node.
+	 */
 	constructor() {
 
 		super( 'vec3' );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isLightingNode = true;
 
 	}
 
-	generate( /*builder*/ ) {
-
-		console.warn( 'Abstract function.' );
-
-	}
-
 }
 
 export default LightingNode;