@plastic-software/three 0.167.4 → 0.174.0

package/src/nodes/accessors/MaterialReferenceNode.js

@@ -1,31 +1,64 @@
 import ReferenceNode from './ReferenceNode.js';
-//import { renderGroup } from '../core/UniformGroupNode.js';
-//import { NodeUpdateType } from '../core/constants.js';
-import { addNodeClass } from '../core/Node.js';
-import { nodeObject } from '../shadernode/ShaderNode.js';
-
+import { nodeObject } from '../tsl/TSLBase.js';
+
+/**
+ * This node is a special type of reference node which is intended
+ * for linking material properties with node values.
+ * ```js
+ * const opacityNode = materialReference( 'opacity', 'float', material );
+ * ```
+ * When changing `material.opacity`, the node value of `opacityNode` will
+ * automatically be updated.
+ *
+ * @augments ReferenceNode
+ */
 class MaterialReferenceNode extends ReferenceNode {
 
+	static get type() {
+
+		return 'MaterialReferenceNode';
+
+	}
+
+	/**
+	 * Constructs a new material reference node.
+	 *
+	 * @param {string} property - The name of the property the node refers to.
+	 * @param {string} inputType - The uniform type that should be used to represent the property value.
+	 * @param {?Material} [material=null] - The material the property belongs to. When no material is set,
+	 * the node refers to the material of the current rendered object.
+	 */
 	constructor( property, inputType, material = null ) {
 
 		super( property, inputType, material );
 
+		/**
+		 * The material the property belongs to. When no material is set,
+		 * the node refers to the material of the current rendered object.
+		 *
+		 * @type {?Material}
+		 * @default null
+		 */
 		this.material = material;
 
-		//this.updateType = NodeUpdateType.RENDER;
-
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isMaterialReferenceNode = true;
 
 	}
 
-	/*setNodeType( node ) {
-
-		super.setNodeType( node );
-
-		this.node.groupNode = renderGroup;
-
-	}*/
-
+	/**
+	 * Updates the reference based on the given state. The state is only evaluated
+	 * {@link MaterialReferenceNode#material} is not set.
+	 *
+	 * @param {(NodeFrame|NodeBuilder)} state - The current state.
+	 * @return {Object} The updated reference.
+	 */
 	updateReference( state ) {
 
 		this.reference = this.material !== null ? this.material : state.material;
@@ -38,6 +71,15 @@ class MaterialReferenceNode extends ReferenceNode {
 
 export default MaterialReferenceNode;
 
-export const materialReference = ( name, type, material ) => nodeObject( new MaterialReferenceNode( name, type, material ) );
-
-addNodeClass( 'MaterialReferenceNode', MaterialReferenceNode );
+/**
+ * TSL function for creating a material reference node.
+ *
+ * @tsl
+ * @function
+ * @param {string} name - The name of the property the node refers to.
+ * @param {string} type - The uniform type that should be used to represent the property value.
+ * @param {?Material} [material=null] - The material the property belongs to.
+ * When no material is set, the node refers to the material of the current rendered object.
+ * @returns {MaterialReferenceNode}
+ */
+export const materialReference = ( name, type, material = null ) => nodeObject( new MaterialReferenceNode( name, type, material ) );

package/src/nodes/accessors/ModelNode.js

@@ -1,18 +1,44 @@
 import Object3DNode from './Object3DNode.js';
-import { addNodeClass } from '../core/Node.js';
-import { nodeImmutable } from '../shadernode/ShaderNode.js';
+import { Fn, nodeImmutable } from '../tsl/TSLBase.js';
 import { uniform } from '../core/UniformNode.js';
 
 import { Matrix4 } from '../../math/Matrix4.js';
+import { cameraViewMatrix } from './Camera.js';
+import { Matrix3 } from '../../math/Matrix3.js';
 
+/**
+ * This type of node is a specialized version of `Object3DNode`
+ * with larger set of model related metrics. Unlike `Object3DNode`,
+ * `ModelNode` extracts the reference to the 3D object from the
+ * current node frame state.
+ *
+ * @augments Object3DNode
+ */
 class ModelNode extends Object3DNode {
 
-	constructor( scope = ModelNode.VIEW_MATRIX ) {
+	static get type() {
+
+		return 'ModelNode';
+
+	}
+
+	/**
+	 * Constructs a new object model node.
+	 *
+	 * @param {('position'|'viewPosition'|'direction'|'scale'|'worldMatrix')} scope - The node represents a different type of transformation depending on the scope.
+	 */
+	constructor( scope ) {
 
 		super( scope );
 
 	}
 
+	/**
+	 * Extracts the model reference from the frame state and then
+	 * updates the uniform value depending on the scope.
+	 *
+	 * @param {NodeFrame} frame - The current node frame.
+	 */
 	update( frame ) {
 
 		this.object3d = frame.object;
@@ -25,13 +51,134 @@ class ModelNode extends Object3DNode {
 
 export default ModelNode;
 
-export const modelDirection = nodeImmutable( ModelNode, ModelNode.DIRECTION );
-export const modelViewMatrix = nodeImmutable( ModelNode, ModelNode.VIEW_MATRIX ).label( 'modelViewMatrix' ).temp( 'ModelViewMatrix' );
-export const modelNormalMatrix = nodeImmutable( ModelNode, ModelNode.NORMAL_MATRIX );
-export const modelWorldMatrix = nodeImmutable( ModelNode, ModelNode.WORLD_MATRIX );
-export const modelPosition = nodeImmutable( ModelNode, ModelNode.POSITION );
-export const modelScale = nodeImmutable( ModelNode, ModelNode.SCALE );
-export const modelViewPosition = nodeImmutable( ModelNode, ModelNode.VIEW_POSITION );
-export const modelWorldMatrixInverse = uniform( new Matrix4() ).onObjectUpdate( ( { object }, self ) => self.value.copy( object.matrixWorld ).invert() );
+/**
+ * TSL object that represents the object's direction in world space.
+ *
+ * @tsl
+ * @type {ModelNode<vec3>}
+ */
+export const modelDirection = /*@__PURE__*/ nodeImmutable( ModelNode, ModelNode.DIRECTION );
+
+/**
+ * TSL object that represents the object's world matrix.
+ *
+ * @tsl
+ * @type {ModelNode<mat4>}
+ */
+export const modelWorldMatrix = /*@__PURE__*/ nodeImmutable( ModelNode, ModelNode.WORLD_MATRIX );
+
+/**
+ * TSL object that represents the object's position in world space.
+ *
+ * @tsl
+ * @type {ModelNode<vec3>}
+ */
+export const modelPosition = /*@__PURE__*/ nodeImmutable( ModelNode, ModelNode.POSITION );
+
+/**
+ * TSL object that represents the object's scale in world space.
+ *
+ * @tsl
+ * @type {ModelNode<vec3>}
+ */
+export const modelScale = /*@__PURE__*/ nodeImmutable( ModelNode, ModelNode.SCALE );
+
+/**
+ * TSL object that represents the object's position in view/camera space.
+ *
+ * @tsl
+ * @type {ModelNode<vec3>}
+ */
+export const modelViewPosition = /*@__PURE__*/ nodeImmutable( ModelNode, ModelNode.VIEW_POSITION );
+
+/**
+ * TSL object that represents the object's radius.
+ *
+ * @tsl
+ * @type {ModelNode<float>}
+ */
+export const modelRadius = /*@__PURE__*/ nodeImmutable( ModelNode, ModelNode.RADIUS );
+
+/**
+ * TSL object that represents the object's normal matrix.
+ *
+ * @tsl
+ * @type {UniformNode<mat3>}
+ */
+export const modelNormalMatrix = /*@__PURE__*/ uniform( new Matrix3() ).onObjectUpdate( ( { object }, self ) => self.value.getNormalMatrix( object.matrixWorld ) );
+
+/**
+ * TSL object that represents the object's inverse world matrix.
+ *
+ * @tsl
+ * @type {UniformNode<mat4>}
+ */
+export const modelWorldMatrixInverse = /*@__PURE__*/ uniform( new Matrix4() ).onObjectUpdate( ( { object }, self ) => self.value.copy( object.matrixWorld ).invert() );
+
+/**
+ * TSL object that represents the object's model view matrix.
+ *
+ * @tsl
+ * @type {Node<mat4>}
+ */
+export const modelViewMatrix = /*@__PURE__*/ ( Fn( ( builder ) => {
+
+	return builder.renderer.nodes.modelViewMatrix || mediumpModelViewMatrix;
+
+} ).once() )().toVar( 'modelViewMatrix' );
+
+// GPU Precision
+
+/**
+ * TSL object that represents the object's model view in `mediump` precision.
+ *
+ * @tsl
+ * @type {Node<mat4>}
+ */
+export const mediumpModelViewMatrix = /*@__PURE__*/ cameraViewMatrix.mul( modelWorldMatrix );
+
+// CPU Precision
+
+/**
+ * TSL object that represents the object's model view in `highp` precision
+ * which is achieved by computing the matrix in JS and not in the shader.
+ *
+ * @tsl
+ * @type {Node<mat4>}
+ */
+export const highpModelViewMatrix = /*@__PURE__*/ ( Fn( ( builder ) => {
+
+	builder.context.isHighPrecisionModelViewMatrix = true;
+
+	return uniform( 'mat4' ).onObjectUpdate( ( { object, camera } ) => {
+
+		return object.modelViewMatrix.multiplyMatrices( camera.matrixWorldInverse, object.matrixWorld );
+
+	} );
+
+} ).once() )().toVar( 'highpModelViewMatrix' );
+
+/**
+ * TSL object that represents the object's model normal view in `highp` precision
+ * which is achieved by computing the matrix in JS and not in the shader.
+ *
+ * @tsl
+ * @type {Node<mat3>}
+ */
+export const highpModelNormalViewMatrix = /*@__PURE__*/ ( Fn( ( builder ) => {
+
+	const isHighPrecisionModelViewMatrix = builder.context.isHighPrecisionModelViewMatrix;
+
+	return uniform( 'mat3' ).onObjectUpdate( ( { object, camera } ) => {
+
+		if ( isHighPrecisionModelViewMatrix !== true ) {
+
+			object.modelViewMatrix.multiplyMatrices( camera.matrixWorldInverse, object.matrixWorld );
+
+		}
+
+		return object.normalMatrix.getNormalMatrix( object.modelViewMatrix );
+
+	} );
 
-addNodeClass( 'ModelNode', ModelNode );
+} ).once() )().toVar( 'highpModelNormalViewMatrix' );

package/src/nodes/accessors/ModelViewProjectionNode.js

@@ -1,39 +1,13 @@
-import { addNodeClass } from '../core/Node.js';
-import TempNode from '../core/TempNode.js';
-import { cameraProjectionMatrix } from './CameraNode.js';
-import { modelViewMatrix } from './ModelNode.js';
-import { positionLocal } from './PositionNode.js';
-import { nodeProxy } from '../shadernode/ShaderNode.js';
-import { varying } from '../core/VaryingNode.js';
+import { Fn } from '../tsl/TSLCore.js';
 
-class ModelViewProjectionNode extends TempNode {
+/**
+ * TSL object that represents the position in clip space after the model-view-projection transform of the current rendered object.
+ *
+ * @tsl
+ * @type {VaryingNode<vec4>}
+ */
+export const modelViewProjection = /*@__PURE__*/ ( Fn( ( builder ) => {
 
-	constructor( positionNode = null ) {
+	return builder.context.setupModelViewProjection();
 
-		super( 'vec4' );
-
-		this.positionNode = positionNode;
-
-	}
-
-	setup( builder ) {
-
-		if ( builder.shaderStage === 'fragment' ) {
-
-			return varying( builder.context.mvp );
-
-		}
-
-		const position = this.positionNode || positionLocal;
-
-		return cameraProjectionMatrix.mul( modelViewMatrix ).mul( position );
-
-	}
-
-}
-
-export default ModelViewProjectionNode;
-
-export const modelViewProjection = nodeProxy( ModelViewProjectionNode );
-
-addNodeClass( 'ModelViewProjectionNode', ModelViewProjectionNode );
+}, 'vec4' ).once() )().toVarying( 'v_modelViewProjection' );

package/src/nodes/accessors/MorphNode.js

@@ -1,13 +1,12 @@
-import Node, { addNodeClass } from '../core/Node.js';
+import Node from '../core/Node.js';
 import { NodeUpdateType } from '../core/constants.js';
-import { float, nodeProxy, Fn } from '../shadernode/ShaderNode.js';
+import { float, nodeProxy, Fn, ivec2, int } from '../tsl/TSLBase.js';
 import { uniform } from '../core/UniformNode.js';
 import { reference } from './ReferenceNode.js';
-import { positionLocal } from './PositionNode.js';
-import { normalLocal } from './NormalNode.js';
+import { positionLocal } from './Position.js';
+import { normalLocal } from './Normal.js';
 import { textureLoad } from './TextureNode.js';
 import { instanceIndex, vertexIndex } from '../core/IndexNode.js';
-import { ivec2, int } from '../shadernode/ShaderNode.js';
 import { Loop } from '../utils/LoopNode.js';
 
 import { DataArrayTexture } from '../../textures/DataArrayTexture.js';
@@ -15,10 +14,10 @@ import { Vector2 } from '../../math/Vector2.js';
 import { Vector4 } from '../../math/Vector4.js';
 import { FloatType } from '../../constants.js';
 
-const _morphTextures = new WeakMap();
+const _morphTextures = /*@__PURE__*/ new WeakMap();
 const _morphVec4 = /*@__PURE__*/ new Vector4();
 
-const getMorph = Fn( ( { bufferMap, influence, stride, width, depth, offset } ) => {
+const getMorph = /*@__PURE__*/ Fn( ( { bufferMap, influence, stride, width, depth, offset } ) => {
 
 	const texelIndex = int( vertexIndex ).mul( stride ).add( offset );
 
@@ -157,26 +156,63 @@ function getEntry( geometry ) {
 
 }
 
-
+/**
+ * This node implements the vertex transformation shader logic which is required
+ * for morph target animation.
+ *
+ * @augments Node
+ */
 class MorphNode extends Node {
 
+	static get type() {
+
+		return 'MorphNode';
+
+	}
+
+	/**
+	 * Constructs a new morph node.
+	 *
+	 * @param {Mesh} mesh - The mesh holding the morph targets.
+	 */
 	constructor( mesh ) {
 
 		super( 'void' );
 
+		/**
+		 * The mesh holding the morph targets.
+		 *
+		 * @type {Mesh}
+		 */
 		this.mesh = mesh;
+
+		/**
+		 * A uniform node which represents the morph base influence value.
+		 *
+		 * @type {UniformNode<float>}
+		 */
 		this.morphBaseInfluence = uniform( 1 );
 
+		/**
+		 * The update type overwritten since morph nodes are updated per object.
+		 *
+		 * @type {string}
+		 */
 		this.updateType = NodeUpdateType.OBJECT;
 
 	}
 
+	/**
+	 * Setups the morph node by assigning the transformed vertex data to predefined node variables.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 */
 	setup( builder ) {
 
 		const { geometry } = builder;
 
 		const hasMorphPosition = geometry.morphAttributes.position !== undefined;
-		const hasMorphNormals = geometry.morphAttributes.normal !== undefined;
+		const hasMorphNormals = geometry.hasAttribute( 'normal' ) && geometry.morphAttributes.normal !== undefined;
 
 		const morphAttribute = geometry.morphAttributes.position || geometry.morphAttributes.normal || geometry.morphAttributes.color;
 		const morphTargetsCount = ( morphAttribute !== undefined ) ? morphAttribute.length : 0;
@@ -234,7 +270,12 @@ class MorphNode extends Node {
 
 	}
 
-	update() {
+	/**
+	 * Updates the state of the morphed mesh by updating the base influence.
+	 *
+	 * @param {NodeFrame} frame - The current node frame.
+	 */
+	update( /*frame*/ ) {
 
 		const morphBaseInfluence = this.morphBaseInfluence;
 
@@ -254,6 +295,12 @@ class MorphNode extends Node {
 
 export default MorphNode;
 
-export const morphReference = nodeProxy( MorphNode );
-
-addNodeClass( 'MorphNode', MorphNode );
+/**
+ * TSL function for creating a morph node.
+ *
+ * @tsl
+ * @function
+ * @param {Mesh} mesh - The mesh holding the morph targets.
+ * @returns {MorphNode}
+ */
+export const morphReference = /*@__PURE__*/ nodeProxy( MorphNode );

package/src/nodes/accessors/Normal.js

@@ -0,0 +1,156 @@
+import { attribute } from '../core/AttributeNode.js';
+import { cameraViewMatrix } from './Camera.js';
+import { modelNormalMatrix, modelWorldMatrix } from './ModelNode.js';
+import { mat3, vec3, Fn, varying } from '../tsl/TSLBase.js';
+import { positionView } from './Position.js';
+import { faceDirection } from '../display/FrontFacingNode.js';
+
+/**
+ * TSL object that represents the normal attribute of the current rendered object.
+ *
+ * @tsl
+ * @type {Node<vec3>}
+ */
+export const normalGeometry = /*@__PURE__*/ attribute( 'normal', 'vec3' );
+
+/**
+ * TSL object that represents the vertex normal in local space of the current rendered object.
+ *
+ * @tsl
+ * @type {Node<vec3>}
+ */
+export const normalLocal = /*@__PURE__*/ ( Fn( ( builder ) => {
+
+	if ( builder.geometry.hasAttribute( 'normal' ) === false ) {
+
+		console.warn( 'TSL.NormalNode: Vertex attribute "normal" not found on geometry.' );
+
+		return vec3( 0, 1, 0 );
+
+	}
+
+	return normalGeometry;
+
+}, 'vec3' ).once() )().toVar( 'normalLocal' );
+
+/**
+ * TSL object that represents the flat vertex normal in view space of the current rendered object.
+ *
+ * @tsl
+ * @type {Node<vec3>}
+ */
+export const normalFlat = /*@__PURE__*/ positionView.dFdx().cross( positionView.dFdy() ).normalize().toVar( 'normalFlat' );
+
+/**
+ * TSL object that represents the vertex normal in view space of the current rendered object.
+ *
+ * @tsl
+ * @type {Node<vec3>}
+ */
+export const normalView = /*@__PURE__*/ ( Fn( ( builder ) => {
+
+	let node;
+
+	if ( builder.material.flatShading === true ) {
+
+		node = normalFlat;
+
+	} else {
+
+		node = varying( transformNormalToView( normalLocal ), 'v_normalView' ).normalize();
+
+	}
+
+	return node;
+
+}, 'vec3' ).once() )().toVar( 'normalView' );
+
+/**
+ * TSL object that represents the vertex normal in world space of the current rendered object.
+ *
+ * @tsl
+ * @type {Node<vec3>}
+ */
+export const normalWorld = /*@__PURE__*/ varying( normalView.transformDirection( cameraViewMatrix ), 'v_normalWorld' ).normalize().toVar( 'normalWorld' );
+
+/**
+ * TSL object that represents the transformed vertex normal in view space of the current rendered object.
+ *
+ * @tsl
+ * @type {Node<vec3>}
+ */
+export const transformedNormalView = /*@__PURE__*/ ( Fn( ( builder ) => {
+
+	// Use getUV context to avoid side effects from nodes overwriting getUV in the context (e.g. EnvironmentNode)
+
+	return builder.context.setupNormal().context( { getUV: null } );
+
+}, 'vec3' ).once() )().mul( faceDirection ).toVar( 'transformedNormalView' );
+
+/**
+ * TSL object that represents the transformed vertex normal in world space of the current rendered object.
+ *
+ * @tsl
+ * @type {Node<vec3>}
+ */
+export const transformedNormalWorld = /*@__PURE__*/ transformedNormalView.transformDirection( cameraViewMatrix ).toVar( 'transformedNormalWorld' );
+
+/**
+ * TSL object that represents the transformed clearcoat vertex normal in view space of the current rendered object.
+ *
+ * @tsl
+ * @type {Node<vec3>}
+ */
+export const transformedClearcoatNormalView = /*@__PURE__*/ ( Fn( ( builder ) => {
+
+	// Use getUV context to avoid side effects from nodes overwriting getUV in the context (e.g. EnvironmentNode)
+
+	return builder.context.setupClearcoatNormal().context( { getUV: null } );
+
+}, 'vec3' ).once() )().mul( faceDirection ).toVar( 'transformedClearcoatNormalView' );
+
+/**
+ * Transforms the normal with the given matrix.
+ *
+ * @tsl
+ * @function
+ * @param {Node<vec3>} normal - The normal.
+ * @param {Node<mat3>} [matrix=modelWorldMatrix] - The matrix.
+ * @return {Node<vec3>} The transformed normal.
+ */
+export const transformNormal = /*@__PURE__*/ Fn( ( [ normal, matrix = modelWorldMatrix ] ) => {
+
+	const m = mat3( matrix );
+
+	const transformedNormal = normal.div( vec3( m[ 0 ].dot( m[ 0 ] ), m[ 1 ].dot( m[ 1 ] ), m[ 2 ].dot( m[ 2 ] ) ) );
+
+	return m.mul( transformedNormal ).xyz;
+
+} );
+
+/**
+ * Transforms the given normal from local to view space.
+ *
+ * @tsl
+ * @function
+ * @param {Node<vec3>} normal - The normal.
+ * @param {NodeBuilder} builder - The current node builder.
+ * @return {Node<vec3>} The transformed normal.
+ */
+export const transformNormalToView = /*@__PURE__*/ Fn( ( [ normal ], builder ) => {
+
+	const modelNormalViewMatrix = builder.renderer.nodes.modelNormalViewMatrix;
+
+	if ( modelNormalViewMatrix !== null ) {
+
+		return modelNormalViewMatrix.transformDirection( normal );
+
+	}
+
+	//
+
+	const transformedNormal = modelNormalMatrix.mul( normal );
+
+	return cameraViewMatrix.transformDirection( transformedNormal );
+
+} );