@plastic-software/three 0.167.4 → 0.174.0

package/src/nodes/lighting/EnvironmentNode.js

@@ -1,24 +1,46 @@
 import LightingNode from './LightingNode.js';
 import { cache } from '../core/CacheNode.js';
-import { context } from '../core/ContextNode.js';
 import { roughness, clearcoatRoughness } from '../core/PropertyNode.js';
-import { cameraViewMatrix } from '../accessors/CameraNode.js';
-import { transformedClearcoatNormalView, transformedNormalView, transformedNormalWorld } from '../accessors/NormalNode.js';
-import { positionViewDirection } from '../accessors/PositionNode.js';
-import { addNodeClass } from '../core/Node.js';
-import { float } from '../shadernode/ShaderNode.js';
-import { reference } from '../accessors/ReferenceNode.js';
+import { cameraViewMatrix } from '../accessors/Camera.js';
+import { transformedClearcoatNormalView, transformedNormalView, transformedNormalWorld } from '../accessors/Normal.js';
+import { positionViewDirection } from '../accessors/Position.js';
+import { float } from '../tsl/TSLBase.js';
 import { transformedBentNormalView } from '../accessors/AccessorsUtils.js';
 import { pmremTexture } from '../pmrem/PMREMNode.js';
+import { materialEnvIntensity } from '../accessors/MaterialProperties.js';
 
 const _envNodeCache = 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() {
+
+		return 'EnvironmentNode';
+
+	}
+
+	/**
+	 * 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;
 
 	}
@@ -49,14 +71,11 @@ 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 radiance = context( envNode, createRadianceContext( roughness, radianceNormalView ) ).mul( intensity );
-		const irradiance = context( envNode, createIrradianceContext( transformedNormalWorld ) ).mul( Math.PI ).mul( intensity );
+		const radiance = envNode.context( createRadianceContext( roughness, radianceNormalView ) ).mul( materialEnvIntensity );
+		const irradiance = envNode.context( createIrradianceContext( transformedNormalWorld ) ).mul( Math.PI ).mul( materialEnvIntensity );
 
 		const isolateRadiance = cache( radiance );
 		const isolateIrradiance = cache( irradiance );
@@ -73,7 +92,7 @@ class EnvironmentNode extends LightingNode {
 
 		if ( clearcoatRadiance ) {
 
-			const clearcoatRadianceContext = context( envNode, createRadianceContext( clearcoatRoughness, transformedClearcoatNormalView ) ).mul( intensity );
+			const clearcoatRadianceContext = envNode.context( createRadianceContext( clearcoatRoughness, transformedClearcoatNormalView ) ).mul( materialEnvIntensity );
 			const isolateClearcoatRadiance = cache( clearcoatRadianceContext );
 
 			clearcoatRadiance.addAssign( isolateClearcoatRadiance );
@@ -84,6 +103,8 @@ class EnvironmentNode extends LightingNode {
 
 }
 
+export default EnvironmentNode;
+
 const createRadianceContext = ( roughnessNode, normalViewNode ) => {
 
 	let reflectVec = null;
@@ -130,7 +151,3 @@ const createIrradianceContext = ( normalWorldNode ) => {
 	};
 
 };
-
-export default EnvironmentNode;
-
-addNodeClass( 'EnvironmentNode', EnvironmentNode );

package/src/nodes/lighting/HemisphereLightNode.js

@@ -1,27 +1,62 @@
 import AnalyticLightNode from './AnalyticLightNode.js';
-import { addLightNode } from './LightsNode.js';
 import { uniform } from '../core/UniformNode.js';
 import { mix } from '../math/MathNode.js';
-import { normalView } from '../accessors/NormalNode.js';
-import { objectPosition } from '../accessors/Object3DNode.js';
-import { addNodeClass } from '../core/Node.js';
+import { normalView } from '../accessors/Normal.js';
+import { lightPosition } from '../accessors/Lights.js';
+import { renderGroup } from '../core/UniformGroupNode.js';
 
 import { Color } from '../../math/Color.js';
-import { HemisphereLight } from '../../lights/HemisphereLight.js';
 
+/**
+ * Module for representing hemisphere lights as nodes.
+ *
+ * @augments AnalyticLightNode
+ */
 class HemisphereLightNode extends AnalyticLightNode {
 
+	static get type() {
+
+		return 'HemisphereLightNode';
+
+	}
+
+	/**
+	 * Constructs a new hemisphere light node.
+	 *
+	 * @param {?HemisphereLight} [light=null] - The hemisphere light source.
+	 */
 	constructor( light = null ) {
 
 		super( light );
 
-		this.lightPositionNode = objectPosition( 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();
 
-		this.groundColorNode = uniform( new Color() );
+		/**
+		 * 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;
@@ -50,7 +85,3 @@ class HemisphereLightNode extends AnalyticLightNode {
 }
 
 export default HemisphereLightNode;
-
-addNodeClass( 'HemisphereLightNode', HemisphereLightNode );
-
-addLightNode( HemisphereLight, HemisphereLightNode );

package/src/nodes/lighting/IESSpotLightNode.js

@@ -1,13 +1,26 @@
 import SpotLightNode from './SpotLightNode.js';
-import { addLightNode } from './LightsNode.js';
 import { texture } from '../accessors/TextureNode.js';
-import { vec2 } from '../shadernode/ShaderNode.js';
-import { addNodeClass } from '../core/Node.js';
-
-import IESSpotLight from '../../lights/webgpu/IESSpotLight.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() {
+
+		return 'IESSpotLightNode';
+
+	}
+
+	/**
+	 * Overwrites the default implementation to compute an IES conform spot attenuation.
+	 *
+	 * @param {Node<float>} angleCosine - The angle to compute the spot attenuation for.
+	 * @return {Node<float>} The spot attenuation.
+	 */
 	getSpotAttenuation( angleCosine ) {
 
 		const iesMap = this.light.iesMap;
@@ -33,7 +46,3 @@ class IESSpotLightNode extends SpotLightNode {
 }
 
 export default IESSpotLightNode;
-
-addNodeClass( 'IESSpotLightNode', IESSpotLightNode );
-
-addLightNode( IESSpotLight, IESSpotLightNode );

package/src/nodes/lighting/IrradianceNode.js

@@ -1,12 +1,34 @@
 import LightingNode from './LightingNode.js';
-import { addNodeClass } from '../core/Node.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() {
+
+		return 'IrradianceNode';
+
+	}
+
+	/**
+	 * 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;
 
 	}
@@ -20,5 +42,3 @@ class IrradianceNode extends LightingNode {
 }
 
 export default IrradianceNode;
-
-addNodeClass( 'IrradianceNode', IrradianceNode );

package/src/nodes/lighting/LightProbeNode.js

@@ -1,15 +1,27 @@
 import AnalyticLightNode from './AnalyticLightNode.js';
-import { addLightNode } from './LightsNode.js';
-import { normalWorld } from '../accessors/NormalNode.js';
-import { addNodeClass } from '../core/Node.js';
-import { LightProbe } from '../../lights/LightProbe.js';
+import { normalWorld } from '../accessors/Normal.js';
 import { uniformArray } from '../accessors/UniformArrayNode.js';
-import { Fn } from '../shadernode/ShaderNode.js';
-import { mul } from '../math/OperatorNode.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() {
+
+		return 'LightProbeNode';
+
+	}
+
+	/**
+	 * Constructs a new light probe node.
+	 *
+	 * @param {?LightProbe} [light=null] - The light probe.
+	 */
 	constructor( light = null ) {
 
 		super( light );
@@ -18,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;
@@ -40,7 +62,7 @@ class LightProbeNode extends AnalyticLightNode {
 
 	setup( builder ) {
 
-		const irradiance = shGetIrradianceAt( normalWorld, this.lightProbe );
+		const irradiance = getShIrradianceAt( normalWorld, this.lightProbe );
 
 		builder.context.irradiance.addAssign( irradiance );
 
@@ -48,33 +70,4 @@ class LightProbeNode extends AnalyticLightNode {
 
 }
 
-const shGetIrradianceAt = Fn( ( [ normal, shCoefficients ] ) => {
-
-	// normal is assumed to have unit length
-
-	const x = normal.x, y = normal.y, z = normal.z;
-
-	// band 0
-	const result = shCoefficients.element( 0 ).mul( 0.886227 );
-
-	// band 1
-	result.addAssign( shCoefficients.element( 1 ).mul( 2.0 * 0.511664 ).mul( y ) );
-	result.addAssign( shCoefficients.element( 2 ).mul( 2.0 * 0.511664 ).mul( z ) );
-	result.addAssign( shCoefficients.element( 3 ).mul( 2.0 * 0.511664 ).mul( x ) );
-
-	// band 2
-	result.addAssign( shCoefficients.element( 4 ).mul( 2.0 * 0.429043 ).mul( x ).mul( y ) );
-	result.addAssign( shCoefficients.element( 5 ).mul( 2.0 * 0.429043 ).mul( y ).mul( z ) );
-	result.addAssign( shCoefficients.element( 6 ).mul( z.mul( z ).mul( 0.743125 ).sub( 0.247708 ) ) );
-	result.addAssign( shCoefficients.element( 7 ).mul( 2.0 * 0.429043 ).mul( x ).mul( z ) );
-	result.addAssign( shCoefficients.element( 8 ).mul( 0.429043 ).mul( mul( x, x ).sub( mul( y, y ) ) ) );
-
-	return result;
-
-} );
-
 export default LightProbeNode;
-
-addNodeClass( 'LightProbeNode', LightProbeNode );
-
-addLightNode( LightProbe, LightProbeNode );

package/src/nodes/lighting/LightUtils.js

@@ -1,8 +1,16 @@
-import { Fn } from '../shadernode/ShaderNode.js';
+import { Fn } from '../tsl/TSLBase.js';
 
-export const getDistanceAttenuation = 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,29 +1,82 @@
 import ContextNode from '../core/ContextNode.js';
-import { addNodeClass } from '../core/Node.js';
-import { addNodeElement, nodeProxy, float, vec3 } from '../shadernode/ShaderNode.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 {
 
-	constructor( node, lightingModel = null, backdropNode = null, backdropAlphaNode = null ) {
+	static get type() {
+
+		return 'LightingContextNode';
 
-		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._context = null;
+		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;
 
-		const directDiffuse = vec3().temp( 'directDiffuse' ),
-			directSpecular = vec3().temp( 'directSpecular' ),
-			indirectDiffuse = vec3().temp( 'indirectDiffuse' ),
-			indirectSpecular = vec3().temp( 'indirectSpecular' );
+		const directDiffuse = vec3().toVar( 'directDiffuse' ),
+			directSpecular = vec3().toVar( 'directSpecular' ),
+			indirectDiffuse = vec3().toVar( 'indirectDiffuse' ),
+			indirectSpecular = vec3().toVar( 'indirectSpecular' );
 
 		const reflectedLight = {
 			directDiffuse,
@@ -33,10 +86,10 @@ class LightingContextNode extends ContextNode {
 		};
 
 		const context = {
-			radiance: vec3().temp( 'radiance' ),
-			irradiance: vec3().temp( 'irradiance' ),
-			iblIrradiance: vec3().temp( 'iblIrradiance' ),
-			ambientOcclusion: float( 1 ).temp( 'ambientOcclusion' ),
+			radiance: vec3().toVar( 'radiance' ),
+			irradiance: vec3().toVar( 'irradiance' ),
+			iblIrradiance: vec3().toVar( 'iblIrradiance' ),
+			ambientOcclusion: float( 1 ).toVar( 'ambientOcclusion' ),
 			reflectedLight,
 			backdrop: backdropNode,
 			backdropAlpha: backdropAlphaNode
@@ -48,8 +101,8 @@ class LightingContextNode extends ContextNode {
 
 	setup( builder ) {
 
-		this.context = this._context || ( this._context = this.getContext() );
-		this.context.lightingModel = this.lightingModel || builder.context.lightingModel;
+		this.value = this._value || ( this._value = this.getContext() );
+		this.value.lightingModel = this.lightingModel || builder.context.lightingModel;
 
 		return super.setup( builder );
 
@@ -59,8 +112,4 @@ class LightingContextNode extends ContextNode {
 
 export default LightingContextNode;
 
-export const lightingContext = nodeProxy( LightingContextNode );
-
-addNodeElement( 'lightingContext', lightingContext );
-
-addNodeClass( 'LightingContextNode', LightingContextNode );
+export const lightingContext = /*@__PURE__*/ nodeProxy( LightingContextNode );

package/src/nodes/lighting/LightingNode.js

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