@plastic-software/three 0.167.3 → 0.174.0

package/src/nodes/functions/VolumetricLightingModel.js

@@ -0,0 +1,183 @@
+import LightingModel from '../core/LightingModel.js';
+import { property } from '../core/PropertyNode.js';
+import { float, If, uniform, vec3, vec4 } from '../tsl/TSLBase.js';
+import { positionWorld } from '../accessors/Position.js';
+import { cameraFar, cameraNear, cameraPosition, cameraViewMatrix } from '../accessors/Camera.js';
+import { Loop } from '../utils/LoopNode.js';
+import { linearDepth, viewZToPerspectiveDepth } from '../display/ViewportDepthNode.js';
+import { modelRadius } from '../accessors/ModelNode.js';
+import { LTC_Evaluate_Volume } from './BSDF/LTC.js';
+
+const scatteringDensity = property( 'vec3' );
+const linearDepthRay = property( 'vec3' );
+const outgoingRayLight = property( 'vec3' );
+
+/**
+ * VolumetricLightingModel class extends the LightingModel to implement volumetric lighting effects.
+ * This model calculates the scattering and transmittance of light through a volumetric medium.
+ * It dynamically adjusts the direction of the ray based on the camera and object positions.
+ * The model supports custom scattering and depth nodes to enhance the lighting effects.
+ *
+ * @augments LightingModel
+ */
+class VolumetricLightingModel extends LightingModel {
+
+	constructor() {
+
+		super();
+
+	}
+
+	start( builder ) {
+
+		const { material, context } = builder;
+
+		const startPos = property( 'vec3' );
+		const endPos = property( 'vec3' );
+
+		// This approach dynamically changes the direction of the ray,
+		// prioritizing the ray from the camera to the object if it is inside the mesh, and from the object to the camera if it is far away.
+
+		If( cameraPosition.sub( positionWorld ).length().greaterThan( modelRadius.mul( 2 ) ), () => {
+
+			startPos.assign( cameraPosition );
+			endPos.assign( positionWorld );
+
+		} ).Else( () => {
+
+			startPos.assign( positionWorld );
+			endPos.assign( cameraPosition );
+
+		} );
+
+		//
+
+		const viewVector = endPos.sub( startPos );
+
+		const steps = uniform( 'int' ).onRenderUpdate( ( { material } ) => material.steps );
+		const stepSize = viewVector.length().div( steps ).toVar();
+
+		const rayDir = viewVector.normalize().toVar(); // TODO: toVar() should be automatic here ( in loop )
+
+		const distTravelled = float( 0.0 ).toVar();
+		const transmittance = vec3( 1 ).toVar();
+
+		if ( material.offsetNode ) {
+
+			// reduce banding
+
+			distTravelled.addAssign( material.offsetNode.mul( stepSize ) );
+
+		}
+
+		Loop( steps, () => {
+
+			const positionRay = startPos.add( rayDir.mul( distTravelled ) );
+			const positionViewRay = cameraViewMatrix.mul( vec4( positionRay, 1 ) ).xyz;
+
+			if ( material.depthNode !== null ) {
+
+				linearDepthRay.assign( linearDepth( viewZToPerspectiveDepth( positionViewRay.z, cameraNear, cameraFar ) ) );
+
+				context.sceneDepthNode = linearDepth( material.depthNode ).toVar();
+
+			}
+
+			context.positionWorld = positionRay;
+			context.shadowPositionWorld = positionRay;
+			context.positionView = positionViewRay;
+
+			scatteringDensity.assign( 0 );
+
+			let scatteringNode;
+
+			if ( material.scatteringNode ) {
+
+				scatteringNode = material.scatteringNode( {
+					positionRay
+				} );
+
+			}
+
+			super.start( builder );
+
+			if ( scatteringNode ) {
+
+				scatteringDensity.mulAssign( scatteringNode );
+
+			}
+
+			// beer's law
+
+			const falloff = scatteringDensity.mul( .01 ).negate().mul( stepSize ).exp();
+			transmittance.mulAssign( falloff );
+
+			// move along the ray
+
+			distTravelled.addAssign( stepSize );
+
+		} );
+
+		outgoingRayLight.addAssign( transmittance.saturate().oneMinus() );
+
+	}
+
+	scatteringLight( lightColor, builder ) {
+
+		const sceneDepthNode = builder.context.sceneDepthNode;
+
+		if ( sceneDepthNode ) {
+
+			If( sceneDepthNode.greaterThanEqual( linearDepthRay ), () => {
+
+				scatteringDensity.addAssign( lightColor );
+
+			} );
+
+		} else {
+
+			scatteringDensity.addAssign( lightColor );
+
+		}
+
+	}
+
+	direct( { lightNode, lightColor }, builder ) {
+
+		// Ignore lights with infinite distance
+
+		if ( lightNode.light.distance === undefined ) return;
+
+		// TODO: We need a viewportOpaque*() ( output, depth ) to fit with modern rendering approaches
+
+		const directLight = lightColor.xyz.toVar();
+		directLight.mulAssign( lightNode.shadowNode ); // it no should be necessary if used in the same render pass
+
+		this.scatteringLight( directLight, builder );
+
+	}
+
+	directRectArea( { lightColor, lightPosition, halfWidth, halfHeight }, builder ) {
+
+		const p0 = lightPosition.add( halfWidth ).sub( halfHeight ); // counterclockwise; light shines in local neg z direction
+		const p1 = lightPosition.sub( halfWidth ).sub( halfHeight );
+		const p2 = lightPosition.sub( halfWidth ).add( halfHeight );
+		const p3 = lightPosition.add( halfWidth ).add( halfHeight );
+
+		const P = builder.context.positionView;
+
+		const directLight = lightColor.xyz.mul( LTC_Evaluate_Volume( { P, p0, p1, p2, p3 } ) ).pow( 1.5 );
+
+		this.scatteringLight( directLight, builder );
+
+	}
+
+	finish( builder ) {
+
+		builder.context.outgoingLight.assign( outgoingRayLight );
+
+	}
+
+}
+
+export default VolumetricLightingModel;

package/src/nodes/functions/material/getAlphaHashThreshold.js

@@ -0,0 +1,68 @@
+import { abs, add, ceil, clamp, dFdx, dFdy, exp2, float, floor, Fn, fract, length, log2, max, min, mul, sin, sub, vec2, vec3 } from '../../tsl/TSLBase.js';
+
+// See: https://casual-effects.com/research/Wyman2017Hashed/index.html
+
+const ALPHA_HASH_SCALE = 0.05; // Derived from trials only, and may be changed.
+
+const hash2D = /*@__PURE__*/ Fn( ( [ value ] ) => {
+
+	return fract( mul( 1.0e4, sin( mul( 17.0, value.x ).add( mul( 0.1, value.y ) ) ) ).mul( add( 0.1, abs( sin( mul( 13.0, value.y ).add( value.x ) ) ) ) ) );
+
+} );
+
+const hash3D = /*@__PURE__*/ Fn( ( [ value ] ) => {
+
+	return hash2D( vec2( hash2D( value.xy ), value.z ) );
+
+} );
+
+const getAlphaHashThreshold = /*@__PURE__*/ Fn( ( [ position ] ) => {
+
+	// Find the discretized derivatives of our coordinates
+	const maxDeriv = max(
+		length( dFdx( position.xyz ) ),
+		length( dFdy( position.xyz ) )
+	);
+
+	const pixScale = float( 1 ).div( float( ALPHA_HASH_SCALE ).mul( maxDeriv ) ).toVar( 'pixScale' );
+
+	// Find two nearest log-discretized noise scales
+	const pixScales = vec2(
+		exp2( floor( log2( pixScale ) ) ),
+		exp2( ceil( log2( pixScale ) ) )
+	);
+
+	// Compute alpha thresholds at our two noise scales
+	const alpha = vec2(
+		hash3D( floor( pixScales.x.mul( position.xyz ) ) ),
+		hash3D( floor( pixScales.y.mul( position.xyz ) ) ),
+	);
+
+	// Factor to interpolate lerp with
+	const lerpFactor = fract( log2( pixScale ) );
+
+	// Interpolate alpha threshold from noise at two scales
+	const x = add( mul( lerpFactor.oneMinus(), alpha.x ), mul( lerpFactor, alpha.y ) );
+
+	// Pass into CDF to compute uniformly distrib threshold
+	const a = min( lerpFactor, lerpFactor.oneMinus() );
+	const cases = vec3(
+		x.mul( x ).div( mul( 2.0, a ).mul( sub( 1.0, a ) ) ),
+		x.sub( mul( 0.5, a ) ).div( sub( 1.0, a ) ),
+		sub( 1.0, sub( 1.0, x ).mul( sub( 1.0, x ) ).div( mul( 2.0, a ).mul( sub( 1.0, a ) ) ) ) );
+
+	// Find our final, uniformly distributed alpha threshold (ατ)
+	const threshold = x.lessThan( a.oneMinus() ).select( x.lessThan( a ).select( cases.x, cases.y ), cases.z );
+
+	// Avoids ατ == 0. Could also do ατ =1-ατ
+	return clamp( threshold, 1.0e-6, 1.0 );
+
+} ).setLayout( {
+	name: 'getAlphaHashThreshold',
+	type: 'float',
+	inputs: [
+		{ name: 'position', type: 'vec3' }
+	]
+} );
+
+export default getAlphaHashThreshold;

package/src/nodes/functions/material/getGeometryRoughness.js

@@ -1,9 +1,15 @@
-import { normalGeometry } from '../../accessors/NormalNode.js';
-import { Fn } from '../../shadernode/ShaderNode.js';
+import { normalView } from '../../accessors/Normal.js';
+import { float, Fn } from '../../tsl/TSLBase.js';
 
-const getGeometryRoughness = Fn( () => {
+const getGeometryRoughness = /*@__PURE__*/ Fn( ( builder ) => {
 
-	const dxy = normalGeometry.dFdx().abs().max( normalGeometry.dFdy().abs() );
+	if ( builder.geometry.hasAttribute( 'normal' ) === false ) {
+
+		return float( 0 );
+
+	}
+
+	const dxy = normalView.dFdx().abs().max( normalView.dFdy().abs() );
 	const geometryRoughness = dxy.x.max( dxy.y ).max( dxy.z );
 
 	return geometryRoughness;

package/src/nodes/functions/material/getParallaxCorrectNormal.js

@@ -0,0 +1,37 @@
+import { positionWorld } from '../../accessors/Position.js';
+import { float, Fn, min, normalize, sub, vec3 } from '../../tsl/TSLBase.js';
+
+/**
+ * This computes a parallax corrected normal which is used for box-projected cube mapping (BPCEM).
+ *
+ * Reference: {@link https://devlog-martinsh.blogspot.com/2011/09/box-projected-cube-environment-mapping.html}
+ *
+ * ```js
+ * const uvNode = getParallaxCorrectNormal( reflectVector, vec3( 200, 100, 100 ), vec3( 0, - 50, 0 ) );
+ * material.envNode = pmremTexture( renderTarget.texture, uvNode );
+ * ```
+ *
+ * @tsl
+ * @function
+ * @param {Node<vec3>} normal - The normal to correct.
+ * @param {Node<vec3>} cubeSize - The cube size should reflect the size of the environment (BPCEM is usually applied in closed environments like rooms).
+ * @param {Node<vec3>} cubePos - The cube position.
+ * @return {Node<vec3>} The parallax corrected normal.
+ */
+const getParallaxCorrectNormal = /*@__PURE__*/ Fn( ( [ normal, cubeSize, cubePos ] ) => {
+
+	const nDir = normalize( normal ).toVar( 'nDir' );
+	const rbmax = sub( float( 0.5 ).mul( cubeSize.sub( cubePos ) ), positionWorld ).div( nDir ).toVar( 'rbmax' );
+	const rbmin = sub( float( - 0.5 ).mul( cubeSize.sub( cubePos ) ), positionWorld ).div( nDir ).toVar( 'rbmin' );
+	const rbminmax = vec3().toVar( 'rbminmax' );
+	rbminmax.x = nDir.x.greaterThan( float( 0 ) ).select( rbmax.x, rbmin.x );
+	rbminmax.y = nDir.y.greaterThan( float( 0 ) ).select( rbmax.y, rbmin.y );
+	rbminmax.z = nDir.z.greaterThan( float( 0 ) ).select( rbmax.z, rbmin.z );
+
+	const correction = min( min( rbminmax.x, rbminmax.y ), rbminmax.z ).toVar( 'correction' );
+	const boxIntersection = positionWorld.add( nDir.mul( correction ) ).toVar( 'boxIntersection' );
+	return boxIntersection.sub( cubePos );
+
+} );
+
+export default getParallaxCorrectNormal;

package/src/nodes/functions/material/getRoughness.js

@@ -1,7 +1,7 @@
 import getGeometryRoughness from './getGeometryRoughness.js';
-import { Fn } from '../../shadernode/ShaderNode.js';
+import { Fn } from '../../tsl/TSLBase.js';
 
-const getRoughness = Fn( ( inputs ) => {
+const getRoughness = /*@__PURE__*/ Fn( ( inputs ) => {
 
 	const { roughness } = inputs;
 

package/src/nodes/functions/material/getShIrradianceAt.js

@@ -0,0 +1,28 @@
+import { Fn, mul } from '../../tsl/TSLBase.js';
+
+const getShIrradianceAt = /*@__PURE__*/ Fn( ( [ normal, shCoefficients ] ) => {
+
+	// normal is assumed to have unit length
+
+	const x = normal.x, y = normal.y, z = normal.z;
+
+	// band 0
+	let result = shCoefficients.element( 0 ).mul( 0.886227 );
+
+	// band 1
+	result = result.add( shCoefficients.element( 1 ).mul( 2.0 * 0.511664 ).mul( y ) );
+	result = result.add( shCoefficients.element( 2 ).mul( 2.0 * 0.511664 ).mul( z ) );
+	result = result.add( shCoefficients.element( 3 ).mul( 2.0 * 0.511664 ).mul( x ) );
+
+	// band 2
+	result = result.add( shCoefficients.element( 4 ).mul( 2.0 * 0.429043 ).mul( x ).mul( y ) );
+	result = result.add( shCoefficients.element( 5 ).mul( 2.0 * 0.429043 ).mul( y ).mul( z ) );
+	result = result.add( shCoefficients.element( 6 ).mul( z.mul( z ).mul( 0.743125 ).sub( 0.247708 ) ) );
+	result = result.add( shCoefficients.element( 7 ).mul( 2.0 * 0.429043 ).mul( x ).mul( z ) );
+	result = result.add( shCoefficients.element( 8 ).mul( 0.429043 ).mul( mul( x, x ).sub( mul( y, y ) ) ) );
+
+	return result;
+
+} );
+
+export default getShIrradianceAt;

package/src/nodes/geometry/RangeNode.js

@@ -1,9 +1,9 @@
-import Node, { addNodeClass } from '../core/Node.js';
+import Node from '../core/Node.js';
 import { getValueType } from '../core/NodeUtils.js';
 import { buffer } from '../accessors/BufferNode.js';
 import { instancedBufferAttribute } from '../accessors/BufferAttributeNode.js';
 import { instanceIndex } from '../core/IndexNode.js';
-import { nodeProxy, float } from '../shadernode/ShaderNode.js';
+import { nodeProxy, float } from '../tsl/TSLBase.js';
 
 import { Vector4 } from '../../math/Vector4.js';
 import { MathUtils } from '../../math/MathUtils.js';
@@ -12,17 +12,59 @@ import { InstancedBufferAttribute } from '../../core/InstancedBufferAttribute.js
 let min = null;
 let max = null;
 
+/**
+ * `RangeNode` generates random instanced attribute data in a defined range.
+ * An exemplary use case for this utility node is to generate random per-instance
+ * colors:
+ * ```js
+ * const material = new MeshBasicNodeMaterial();
+ * material.colorNode = range( new Color( 0x000000 ), new Color( 0xFFFFFF ) );
+ * const mesh = new InstancedMesh( geometry, material, count );
+ * ```
+ * @augments Node
+ */
 class RangeNode extends Node {
 
+	static get type() {
+
+		return 'RangeNode';
+
+	}
+
+	/**
+	 * Constructs a new range node.
+	 *
+	 * @param {Node<any>} [minNode=float()] - A node defining the lower bound of the range.
+	 * @param {Node<any>} [maxNode=float()] - A node defining the upper bound of the range.
+	 */
 	constructor( minNode = float(), maxNode = float() ) {
 
 		super();
 
+		/**
+		 *  A node defining the lower bound of the range.
+		 *
+		 * @type {Node<any>}
+		 * @default float()
+		 */
 		this.minNode = minNode;
+
+		/**
+		 *  A node defining the upper bound of the range.
+		 *
+		 * @type {Node<any>}
+		 * @default float()
+		 */
 		this.maxNode = maxNode;
 
 	}
 
+	/**
+	 * Returns the vector length which is computed based on the range definition.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {number} The vector length.
+	 */
 	getVectorLength( builder ) {
 
 		const minLength = builder.getTypeLength( getValueType( this.minNode.value ) );
@@ -32,6 +74,12 @@ class RangeNode extends Node {
 
 	}
 
+	/**
+	 * This method is overwritten since the node type is inferred from range definition.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {string} The node type.
+	 */
 	getNodeType( builder ) {
 
 		return builder.object.count > 1 ? builder.getTypeFromLength( this.getVectorLength( builder ) ) : 'float';
@@ -59,11 +107,11 @@ class RangeNode extends Node {
 			max.setScalar( 0 );
 
 			if ( minLength === 1 ) min.setScalar( minValue );
-			else if ( minValue.isColor ) min.set( minValue.r, minValue.g, minValue.b );
+			else if ( minValue.isColor ) min.set( minValue.r, minValue.g, minValue.b, 1 );
 			else min.set( minValue.x, minValue.y, minValue.z || 0, minValue.w || 0 );
 
 			if ( maxLength === 1 ) max.setScalar( maxValue );
-			else if ( maxValue.isColor ) max.set( maxValue.r, maxValue.g, maxValue.b );
+			else if ( maxValue.isColor ) max.set( maxValue.r, maxValue.g, maxValue.b, 1 );
 			else max.set( maxValue.x, maxValue.y, maxValue.z || 0, maxValue.w || 0 );
 
 			const stride = 4;
@@ -112,6 +160,13 @@ class RangeNode extends Node {
 
 export default RangeNode;
 
-export const range = nodeProxy( RangeNode );
-
-addNodeClass( 'RangeNode', RangeNode );
+/**
+ * TSL function for creating a range node.
+ *
+ * @tsl
+ * @function
+ * @param {Node<any>} [minNode=float()] - A node defining the lower bound of the range.
+ * @param {Node<any>} [maxNode=float()] - A node defining the upper bound of the range.
+ * @returns {RangeNode}
+ */
+export const range = /*@__PURE__*/ nodeProxy( RangeNode );