@plastic-software/three 0.167.4 → 0.174.0

package/src/nodes/accessors/ReflectVector.js

@@ -0,0 +1,36 @@
+import { cameraViewMatrix } from './Camera.js';
+import { transformedNormalView } from './Normal.js';
+import { positionViewDirection } from './Position.js';
+import { materialRefractionRatio } from './MaterialProperties.js';
+
+/**
+ * The reflect vector in view space.
+ *
+ * @tsl
+ * @type {Node<vec3>}
+ */
+export const reflectView = /*@__PURE__*/ positionViewDirection.negate().reflect( transformedNormalView );
+
+/**
+ * The refract vector in view space.
+ *
+ * @tsl
+ * @type {Node<vec3>}
+ */
+export const refractView = /*@__PURE__*/ positionViewDirection.negate().refract( transformedNormalView, materialRefractionRatio );
+
+/**
+ * Used for sampling cube maps when using cube reflection mapping.
+ *
+ * @tsl
+ * @type {Node<vec3>}
+ */
+export const reflectVector = /*@__PURE__*/ reflectView.transformDirection( cameraViewMatrix ).toVar( 'reflectVector' );
+
+/**
+ * Used for sampling cube maps when using cube refraction mapping.
+ *
+ * @tsl
+ * @type {Node<vec3>}
+ */
+export const refractVector = /*@__PURE__*/ refractView.transformDirection( cameraViewMatrix ).toVar( 'reflectVector' );

package/src/nodes/accessors/RendererReferenceNode.js

@@ -1,17 +1,58 @@
-import ReferenceNode from './ReferenceNode.js';
-import { addNodeClass } from '../core/Node.js';
-import { nodeObject } from '../shadernode/ShaderNode.js';
+import ReferenceBaseNode from './ReferenceBaseNode.js';
+import { nodeObject } from '../tsl/TSLCore.js';
+import { renderGroup } from '../core/UniformGroupNode.js';
 
-class RendererReferenceNode extends ReferenceNode {
+/**
+ * This node is a special type of reference node which is intended
+ * for linking renderer properties with node values.
+ * ```js
+ * const exposureNode = rendererReference( 'toneMappingExposure', 'float', renderer );
+ * ```
+ * When changing `renderer.toneMappingExposure`, the node value of `exposureNode` will
+ * automatically be updated.
+ *
+ * @augments ReferenceBaseNode
+ */
+class RendererReferenceNode extends ReferenceBaseNode {
 
+	static get type() {
+
+		return 'RendererReferenceNode';
+
+	}
+
+	/**
+	 * Constructs a new renderer 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 {?Renderer} [renderer=null] - The renderer the property belongs to. When no renderer is set,
+	 * the node refers to the renderer of the current state.
+	 */
 	constructor( property, inputType, renderer = null ) {
 
 		super( property, inputType, renderer );
 
+		/**
+		 * The renderer the property belongs to. When no renderer is set,
+		 * the node refers to the renderer of the current state.
+		 *
+		 * @type {?Renderer}
+		 * @default null
+		 */
 		this.renderer = renderer;
 
+		this.setGroup( renderGroup );
+
 	}
 
+	/**
+	 * Updates the reference based on the given state. The state is only evaluated
+	 * {@link RendererReferenceNode#renderer} is not set.
+	 *
+	 * @param {(NodeFrame|NodeBuilder)} state - The current state.
+	 * @return {Object} The updated reference.
+	 */
 	updateReference( state ) {
 
 		this.reference = this.renderer !== null ? this.renderer : state.renderer;
@@ -24,6 +65,15 @@ class RendererReferenceNode extends ReferenceNode {
 
 export default RendererReferenceNode;
 
-export const rendererReference = ( name, type, renderer ) => nodeObject( new RendererReferenceNode( name, type, renderer ) );
-
-addNodeClass( 'RendererReferenceNode', RendererReferenceNode );
+/**
+ * TSL function for creating a renderer 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 {?Renderer} [renderer=null] - The renderer the property belongs to. When no renderer is set,
+ * the node refers to the renderer of the current state.
+ * @returns {RendererReferenceNode}
+ */
+export const rendererReference = ( name, type, renderer = null ) => nodeObject( new RendererReferenceNode( name, type, renderer ) );

package/src/nodes/accessors/SceneNode.js

@@ -1,19 +1,66 @@
+import { UVMapping } from '../../constants.js';
+import { Euler } from '../../math/Euler.js';
+import { Matrix4 } from '../../math/Matrix4.js';
 import Node from '../core/Node.js';
-import { addNodeClass } from '../core/Node.js';
-import { nodeImmutable } from '../shadernode/ShaderNode.js';
+import { renderGroup } from '../core/UniformGroupNode.js';
+import { nodeImmutable, uniform } from '../tsl/TSLBase.js';
 import { reference } from './ReferenceNode.js';
 
+const _e1 = /*@__PURE__*/ new Euler();
+const _m1 = /*@__PURE__*/ new Matrix4();
+
+/**
+ * This module allows access to a collection of scene properties. The following predefined TSL objects
+ * are available for easier use:
+ *
+ * - `backgroundBlurriness`: A node that represents the scene's background blurriness.
+ * - `backgroundIntensity`: A node that represents the scene's background intensity.
+ * - `backgroundRotation`: A node that represents the scene's background rotation.
+ *
+ * @augments Node
+ */
 class SceneNode extends Node {
 
+	static get type() {
+
+		return 'SceneNode';
+
+	}
+
+	/**
+	 * Constructs a new scene node.
+	 *
+	 * @param {('backgroundBlurriness'|'backgroundIntensity'|'backgroundRotation')} scope - The scope defines the type of scene property that is accessed.
+	 * @param {?Scene} [scene=null] - A reference to the scene.
+	 */
 	constructor( scope = SceneNode.BACKGROUND_BLURRINESS, scene = null ) {
 
 		super();
 
+		/**
+		 * The scope defines the type of scene property that is accessed.
+		 *
+		 * @type {('backgroundBlurriness'|'backgroundIntensity'|'backgroundRotation')}
+		 */
 		this.scope = scope;
+
+		/**
+		 * A reference to the scene that is going to be accessed.
+		 *
+		 * @type {?Scene}
+		 * @default null
+		 */
 		this.scene = scene;
 
 	}
 
+	/**
+	 * Depending on the scope, the method returns a different type of node that represents
+	 * the respective scene property.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {Node} The output node.
+	 */
 	setup( builder ) {
 
 		const scope = this.scope;
@@ -29,6 +76,31 @@ class SceneNode extends Node {
 
 			output = reference( 'backgroundIntensity', 'float', scene );
 
+		} else if ( scope === SceneNode.BACKGROUND_ROTATION ) {
+
+			output = uniform( 'mat4' ).label( 'backgroundRotation' ).setGroup( renderGroup ).onRenderUpdate( () => {
+
+				const background = scene.background;
+
+				if ( background !== null && background.isTexture && background.mapping !== UVMapping ) {
+
+					_e1.copy( scene.backgroundRotation );
+
+					// accommodate left-handed frame
+					_e1.x *= - 1; _e1.y *= - 1; _e1.z *= - 1;
+
+					_m1.makeRotationFromEuler( _e1 );
+
+				} else {
+
+					_m1.identity();
+
+				}
+
+				return _m1;
+
+			} );
+
 		} else {
 
 			console.error( 'THREE.SceneNode: Unknown scope:', scope );
@@ -43,10 +115,30 @@ class SceneNode extends Node {
 
 SceneNode.BACKGROUND_BLURRINESS = 'backgroundBlurriness';
 SceneNode.BACKGROUND_INTENSITY = 'backgroundIntensity';
+SceneNode.BACKGROUND_ROTATION = 'backgroundRotation';
 
 export default SceneNode;
 
-export const backgroundBlurriness = nodeImmutable( SceneNode, SceneNode.BACKGROUND_BLURRINESS );
-export const backgroundIntensity = nodeImmutable( SceneNode, SceneNode.BACKGROUND_INTENSITY );
-
-addNodeClass( 'SceneNode', SceneNode );
+/**
+ * TSL object that represents the scene's background blurriness.
+ *
+ * @tsl
+ * @type {SceneNode}
+ */
+export const backgroundBlurriness = /*@__PURE__*/ nodeImmutable( SceneNode, SceneNode.BACKGROUND_BLURRINESS );
+
+/**
+ * TSL object that represents the scene's background intensity.
+ *
+ * @tsl
+ * @type {SceneNode}
+ */
+export const backgroundIntensity = /*@__PURE__*/ nodeImmutable( SceneNode, SceneNode.BACKGROUND_INTENSITY );
+
+/**
+ * TSL object that represents the scene's background rotation.
+ *
+ * @tsl
+ * @type {SceneNode}
+ */
+export const backgroundRotation = /*@__PURE__*/ nodeImmutable( SceneNode, SceneNode.BACKGROUND_ROTATION );

package/src/nodes/accessors/SkinningNode.js

@@ -1,29 +1,78 @@
-import Node, { addNodeClass } from '../core/Node.js';
+import Node from '../core/Node.js';
 import { NodeUpdateType } from '../core/constants.js';
-import { nodeObject } from '../shadernode/ShaderNode.js';
+import { nodeObject } from '../tsl/TSLBase.js';
 import { attribute } from '../core/AttributeNode.js';
 import { reference, referenceBuffer } from './ReferenceNode.js';
 import { add } from '../math/OperatorNode.js';
-import { normalLocal } from './NormalNode.js';
-import { positionLocal } from './PositionNode.js';
-import { tangentLocal } from './TangentNode.js';
+import { normalLocal } from './Normal.js';
+import { positionLocal, positionPrevious } from './Position.js';
+import { tangentLocal } from './Tangent.js';
 import { uniform } from '../core/UniformNode.js';
 import { buffer } from './BufferNode.js';
+import { getDataFromObject } from '../core/NodeUtils.js';
 
+const _frameId = new WeakMap();
+
+/**
+ * This node implements the vertex transformation shader logic which is required
+ * for skinning/skeletal animation.
+ *
+ * @augments Node
+ */
 class SkinningNode extends Node {
 
+	static get type() {
+
+		return 'SkinningNode';
+
+	}
+
+	/**
+	 * Constructs a new skinning node.
+	 *
+	 * @param {SkinnedMesh} skinnedMesh - The skinned mesh.
+	 * @param {boolean} [useReference=false] - Whether to use reference nodes for internal skinned mesh related data or not.
+	 */
 	constructor( skinnedMesh, useReference = false ) {
 
 		super( 'void' );
 
+		/**
+		 * The skinned mesh.
+		 *
+		 * @type {SkinnedMesh}
+		 */
 		this.skinnedMesh = skinnedMesh;
+
+		/**
+		 * Whether to use reference nodes for internal skinned mesh related data or not.
+		 * TODO: Explain the purpose of the property.
+		 *
+		 * @type {boolean}
+		 */
 		this.useReference = useReference;
 
+		/**
+		 * The update type overwritten since skinning nodes are updated per object.
+		 *
+		 * @type {string}
+		 */
 		this.updateType = NodeUpdateType.OBJECT;
 
 		//
 
+		/**
+		 * The skin index attribute.
+		 *
+		 * @type {AttributeNode}
+		 */
 		this.skinIndexNode = attribute( 'skinIndex', 'uvec4' );
+
+		/**
+		 * The skin weight attribute.
+		 *
+		 * @type {AttributeNode}
+		 */
 		this.skinWeightNode = attribute( 'skinWeight', 'vec4' );
 
 		let bindMatrixNode, bindMatrixInverseNode, boneMatricesNode;
@@ -42,24 +91,57 @@ class SkinningNode extends Node {
 
 		}
 
+		/**
+		 * The bind matrix node.
+		 *
+		 * @type {Node<mat4>}
+		 */
 		this.bindMatrixNode = bindMatrixNode;
+
+		/**
+		 * The bind matrix inverse node.
+		 *
+		 * @type {Node<mat4>}
+		 */
 		this.bindMatrixInverseNode = bindMatrixInverseNode;
+
+		/**
+		 * The bind matrices as a uniform buffer node.
+		 *
+		 * @type {Node}
+		 */
 		this.boneMatricesNode = boneMatricesNode;
 
+		/**
+		 * The previous bind matrices as a uniform buffer node.
+		 * Required for computing motion vectors.
+		 *
+		 * @type {?Node}
+		 * @default null
+		 */
+		this.previousBoneMatricesNode = null;
+
 	}
 
-	setup( builder ) {
+	/**
+	 * Transforms the given vertex position via skinning.
+	 *
+	 * @param {Node} [boneMatrices=this.boneMatricesNode] - The bone matrices
+	 * @param {Node<vec3>} [position=positionLocal] - The vertex position in local space.
+	 * @return {Node<vec3>} The transformed vertex position.
+	 */
+	getSkinnedPosition( boneMatrices = this.boneMatricesNode, position = positionLocal ) {
 
-		const { skinIndexNode, skinWeightNode, bindMatrixNode, bindMatrixInverseNode, boneMatricesNode } = this;
+		const { skinIndexNode, skinWeightNode, bindMatrixNode, bindMatrixInverseNode } = this;
 
-		const boneMatX = boneMatricesNode.element( skinIndexNode.x );
-		const boneMatY = boneMatricesNode.element( skinIndexNode.y );
-		const boneMatZ = boneMatricesNode.element( skinIndexNode.z );
-		const boneMatW = boneMatricesNode.element( skinIndexNode.w );
+		const boneMatX = boneMatrices.element( skinIndexNode.x );
+		const boneMatY = boneMatrices.element( skinIndexNode.y );
+		const boneMatZ = boneMatrices.element( skinIndexNode.z );
+		const boneMatW = boneMatrices.element( skinIndexNode.w );
 
 		// POSITION
 
-		const skinVertex = bindMatrixNode.mul( positionLocal );
+		const skinVertex = bindMatrixNode.mul( position );
 
 		const skinned = add(
 			boneMatX.mul( skinWeightNode.x ).mul( skinVertex ),
@@ -68,7 +150,25 @@ class SkinningNode extends Node {
 			boneMatW.mul( skinWeightNode.w ).mul( skinVertex )
 		);
 
-		const skinPosition = bindMatrixInverseNode.mul( skinned ).xyz;
+		return bindMatrixInverseNode.mul( skinned ).xyz;
+
+	}
+
+	/**
+	 * Transforms the given vertex normal via skinning.
+	 *
+	 * @param {Node} [boneMatrices=this.boneMatricesNode] - The bone matrices
+	 * @param {Node<vec3>} [normal=normalLocal] - The vertex normal in local space.
+	 * @return {Node<vec3>} The transformed vertex normal.
+	 */
+	getSkinnedNormal( boneMatrices = this.boneMatricesNode, normal = normalLocal ) {
+
+		const { skinIndexNode, skinWeightNode, bindMatrixNode, bindMatrixInverseNode } = this;
+
+		const boneMatX = boneMatrices.element( skinIndexNode.x );
+		const boneMatY = boneMatrices.element( skinIndexNode.y );
+		const boneMatZ = boneMatrices.element( skinIndexNode.z );
+		const boneMatW = boneMatrices.element( skinIndexNode.w );
 
 		// NORMAL
 
@@ -81,21 +181,87 @@ class SkinningNode extends Node {
 
 		skinMatrix = bindMatrixInverseNode.mul( skinMatrix ).mul( bindMatrixNode );
 
-		const skinNormal = skinMatrix.transformDirection( normalLocal ).xyz;
+		return skinMatrix.transformDirection( normal ).xyz;
+
+	}
+
+	/**
+	 * Transforms the given vertex normal via skinning.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {Node<vec3>} The skinned position from the previous frame.
+	 */
+	getPreviousSkinnedPosition( builder ) {
+
+		const skinnedMesh = builder.object;
+
+		if ( this.previousBoneMatricesNode === null ) {
+
+			skinnedMesh.skeleton.previousBoneMatrices = new Float32Array( skinnedMesh.skeleton.boneMatrices );
+
+			this.previousBoneMatricesNode = referenceBuffer( 'skeleton.previousBoneMatrices', 'mat4', skinnedMesh.skeleton.bones.length );
+
+		}
+
+		return this.getSkinnedPosition( this.previousBoneMatricesNode, positionPrevious );
+
+	}
+
+	/**
+	 * Returns `true` if bone matrices from the previous frame are required.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {boolean} Whether bone matrices from the previous frame are required or not.
+	 */
+	needsPreviousBoneMatrices( builder ) {
+
+		const mrt = builder.renderer.getMRT();
+
+		return ( mrt && mrt.has( 'velocity' ) ) || getDataFromObject( builder.object ).useVelocity === true;
+
+	}
+
+	/**
+	 * Setups the skinning node by assigning the transformed vertex data to predefined node variables.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 */
+	setup( builder ) {
+
+		if ( this.needsPreviousBoneMatrices( builder ) ) {
+
+			positionPrevious.assign( this.getPreviousSkinnedPosition( builder ) );
+
+		}
+
+		const skinPosition = this.getSkinnedPosition();
 
-		// ASSIGNS
 
 		positionLocal.assign( skinPosition );
-		normalLocal.assign( skinNormal );
 
-		if ( builder.hasGeometryAttribute( 'tangent' ) ) {
+		if ( builder.hasGeometryAttribute( 'normal' ) ) {
+
+			const skinNormal = this.getSkinnedNormal();
+
+			normalLocal.assign( skinNormal );
+
+			if ( builder.hasGeometryAttribute( 'tangent' ) ) {
 
-			tangentLocal.assign( skinNormal );
+				tangentLocal.assign( skinNormal );
+
+			}
 
 		}
 
 	}
 
+	/**
+	 * Generates the code snippet of the skinning node.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @param {string} output - The current output.
+	 * @return {string} The generated code snippet.
+	 */
 	generate( builder, output ) {
 
 		if ( output !== 'void' ) {
@@ -106,11 +272,23 @@ class SkinningNode extends Node {
 
 	}
 
+	/**
+	 * Updates the state of the skinned mesh by updating the skeleton once per frame.
+	 *
+	 * @param {NodeFrame} frame - The current node frame.
+	 */
 	update( frame ) {
 
 		const object = this.useReference ? frame.object : this.skinnedMesh;
+		const skeleton = object.skeleton;
+
+		if ( _frameId.get( skeleton ) === frame.frameId ) return;
+
+		_frameId.set( skeleton, frame.frameId );
 
-		object.skeleton.update();
+		if ( this.previousBoneMatricesNode !== null ) skeleton.previousBoneMatrices.set( skeleton.boneMatrices );
+
+		skeleton.update();
 
 	}
 
@@ -118,7 +296,22 @@ class SkinningNode extends Node {
 
 export default SkinningNode;
 
+/**
+ * TSL function for creating a skinning node.
+ *
+ * @tsl
+ * @function
+ * @param {SkinnedMesh} skinnedMesh - The skinned mesh.
+ * @returns {SkinningNode}
+ */
 export const skinning = ( skinnedMesh ) => nodeObject( new SkinningNode( skinnedMesh ) );
-export const skinningReference = ( skinnedMesh ) => nodeObject( new SkinningNode( skinnedMesh, true ) );
 
-addNodeClass( 'SkinningNode', SkinningNode );
+/**
+ * TSL function for creating a skinning node with reference usage.
+ *
+ * @tsl
+ * @function
+ * @param {SkinnedMesh} skinnedMesh - The skinned mesh.
+ * @returns {SkinningNode}
+ */
+export const skinningReference = ( skinnedMesh ) => nodeObject( new SkinningNode( skinnedMesh, true ) );