@plastic-software/three 0.167.3 → 0.174.0

package/src/nodes/accessors/UV.js

@@ -0,0 +1,11 @@
+import { attribute } from '../core/AttributeNode.js';
+
+/**
+ * TSL function for creating an uv attribute node with the given index.
+ *
+ * @tsl
+ * @function
+ * @param {number} [index=0] - The uv index.
+ * @return {AttributeNode<vec2>} The uv attribute node.
+ */
+export const uv = ( index = 0 ) => attribute( 'uv' + ( index > 0 ? index : '' ), 'vec2' );

package/src/nodes/accessors/UniformArrayNode.js

@@ -1,23 +1,40 @@
-import { addNodeClass } from '../core/Node.js';
-import { nodeObject } from '../shadernode/ShaderNode.js';
+import { nodeObject } from '../tsl/TSLBase.js';
 import { NodeUpdateType } from '../core/constants.js';
 import { getValueType } from '../core/NodeUtils.js';
 import ArrayElementNode from '../utils/ArrayElementNode.js';
 import BufferNode from './BufferNode.js';
 
+/**
+ * Represents the element access on uniform array nodes.
+ *
+ * @augments ArrayElementNode
+ */
 class UniformArrayElementNode extends ArrayElementNode {
 
-	constructor( arrayBuffer, indexNode ) {
+	static get type() {
 
-		super( arrayBuffer, indexNode );
-
-		this.isArrayBufferElementNode = true;
+		return 'UniformArrayElementNode';
 
 	}
 
-	getNodeType( builder ) {
-
-		return this.node.getElementType( builder );
+	/**
+	 * Constructs a new buffer node.
+	 *
+	 * @param {UniformArrayNode} uniformArrayNode - The uniform array node to access.
+	 * @param {IndexNode} indexNode - The index data that define the position of the accessed element in the array.
+	 */
+	constructor( uniformArrayNode, indexNode ) {
+
+		super( uniformArrayNode, indexNode );
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
+		this.isArrayBufferElementNode = true;
 
 	}
 
@@ -25,51 +42,163 @@ class UniformArrayElementNode extends ArrayElementNode {
 
 		const snippet = super.generate( builder );
 		const type = this.getNodeType();
+		const paddedType = this.node.getPaddedType();
 
-		return builder.format( snippet, 'vec4', type );
+		return builder.format( snippet, paddedType, type );
 
 	}
 
 }
 
+/**
+ * Similar to {@link BufferNode} this module represents array-like data as
+ * uniform buffers. Unlike {@link BufferNode}, it can handle more common
+ * data types in the array (e.g `three.js` primitives) and automatically
+ * manage buffer padding. It should be the first choice when working with
+ * uniforms buffers.
+ * ```js
+ * const tintColors = uniformArray( [
+ * 	new Color( 1, 0, 0 ),
+ * 	new Color( 0, 1, 0 ),
+ * 	new Color( 0, 0, 1 )
+ * ], 'color' );
+ *
+ * const redColor = tintColors.element( 0 );
+ *
+ * @augments BufferNode
+ */
 class UniformArrayNode extends BufferNode {
 
+	static get type() {
+
+		return 'UniformArrayNode';
+
+	}
+
+	/**
+	 * Constructs a new uniform array node.
+	 *
+	 * @param {Array<any>} value - Array holding the buffer data.
+	 * @param {?string} [elementType=null] - The data type of a buffer element.
+	 */
 	constructor( value, elementType = null ) {
 
-		super( null, 'vec4' );
+		super( null );
 
+		/**
+		 * Array holding the buffer data. Unlike {@link BufferNode}, the array can
+		 * hold number primitives as well as three.js objects like vectors, matrices
+		 * or colors.
+		 *
+		 * @type {Array<any>}
+		 */
 		this.array = value;
-		this.elementType = elementType;
-
-		this._elementType = null;
-		this._elementLength = 0;
 
+		/**
+		 * The data type of an array element.
+		 *
+		 * @type {string}
+		 */
+		this.elementType = elementType === null ? getValueType( value[ 0 ] ) : elementType;
+
+		/**
+		 * The padded type. Uniform buffers must conform to a certain buffer layout
+		 * so a separate type is computed to ensure correct buffer size.
+		 *
+		 * @type {string}
+		 */
+		this.paddedType = this.getPaddedType();
+
+		/**
+		 * Overwritten since uniform array nodes are updated per render.
+		 *
+		 * @type {string}
+		 * @default 'render'
+		 */
 		this.updateType = NodeUpdateType.RENDER;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isArrayBufferNode = true;
 
 	}
 
+	/**
+	 * This method is overwritten since the node type is inferred from the
+	 * {@link UniformArrayNode#paddedType}.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {string} The node type.
+	 */
+	getNodeType( /*builder*/ ) {
+
+		return this.paddedType;
+
+	}
+
+	/**
+	 * The data type of the array elements.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {string} The element type.
+	 */
 	getElementType() {
 
-		return this.elementType || this._elementType;
+		return this.elementType;
 
 	}
 
-	getElementLength() {
+	/**
+	 * Returns the padded type based on the element type.
+	 *
+	 * @return {string} The padded type.
+	 */
+	getPaddedType() {
+
+		const elementType = this.elementType;
 
-		return this._elementLength;
+		let paddedType = 'vec4';
+
+		if ( elementType === 'mat2' ) {
+
+			paddedType = 'mat2';
+
+		} else if ( /mat/.test( elementType ) === true ) {
+
+			paddedType = 'mat4';
+
+		} else if ( elementType.charAt( 0 ) === 'i' ) {
+
+			paddedType = 'ivec4';
+
+		} else if ( elementType.charAt( 0 ) === 'u' ) {
+
+			paddedType = 'uvec4';
+
+		}
+
+		return paddedType;
 
 	}
 
+	/**
+	 * The update makes sure to correctly transfer the data from the (complex) objects
+	 * in the array to the internal, correctly padded value buffer.
+	 *
+	 * @param {NodeFrame} frame - A reference to the current node frame.
+	 */
 	update( /*frame*/ ) {
 
 		const { array, value } = this;
 
-		const elementLength = this.getElementLength();
-		const elementType = this.getElementType();
+		const elementType = this.elementType;
 
-		if ( elementLength === 1 ) {
+		if ( elementType === 'float' || elementType === 'int' || elementType === 'uint' ) {
 
 			for ( let i = 0; i < array.length; i ++ ) {
 
@@ -93,6 +222,58 @@ class UniformArrayNode extends BufferNode {
 
 			}
 
+		} else if ( elementType === 'mat2' ) {
+
+			for ( let i = 0; i < array.length; i ++ ) {
+
+				const index = i * 4;
+				const matrix = array[ i ];
+
+				value[ index ] = matrix.elements[ 0 ];
+				value[ index + 1 ] = matrix.elements[ 1 ];
+				value[ index + 2 ] = matrix.elements[ 2 ];
+				value[ index + 3 ] = matrix.elements[ 3 ];
+
+			}
+
+		} else if ( elementType === 'mat3' ) {
+
+			for ( let i = 0; i < array.length; i ++ ) {
+
+				const index = i * 16;
+				const matrix = array[ i ];
+
+				value[ index ] = matrix.elements[ 0 ];
+				value[ index + 1 ] = matrix.elements[ 1 ];
+				value[ index + 2 ] = matrix.elements[ 2 ];
+
+				value[ index + 4 ] = matrix.elements[ 3 ];
+				value[ index + 5 ] = matrix.elements[ 4 ];
+				value[ index + 6 ] = matrix.elements[ 5 ];
+
+				value[ index + 8 ] = matrix.elements[ 6 ];
+				value[ index + 9 ] = matrix.elements[ 7 ];
+				value[ index + 10 ] = matrix.elements[ 8 ];
+
+				value[ index + 15 ] = 1;
+
+			}
+
+		} else if ( elementType === 'mat4' ) {
+
+			for ( let i = 0; i < array.length; i ++ ) {
+
+				const index = i * 16;
+				const matrix = array[ i ];
+
+				for ( let i = 0; i < matrix.elements.length; i ++ ) {
+
+					value[ index + i ] = matrix.elements[ i ];
+
+				}
+
+			}
+
 		} else {
 
 			for ( let i = 0; i < array.length; i ++ ) {
@@ -111,26 +292,40 @@ class UniformArrayNode extends BufferNode {
 
 	}
 
+	/**
+	 * Implement the value buffer creation based on the array data.
+	 *
+	 * @param {NodeBuilder} builder - A reference to the current node builder.
+	 * @return {null}
+	 */
 	setup( builder ) {
 
 		const length = this.array.length;
-
-		this._elementType = this.elementType === null ? getValueType( this.array[ 0 ] ) : this.elementType;
-		this._elementLength = builder.getTypeLength( this._elementType );
+		const elementType = this.elementType;
 
 		let arrayType = Float32Array;
 
-		if ( this._elementType.charAt( 0 ) === 'i' ) arrayType = Int32Array;
-		else if ( this._elementType.charAt( 0 ) === 'u' ) arrayType = Uint32Array;
+		const paddedType = this.paddedType;
+		const paddedElementLength = builder.getTypeLength( paddedType );
 
-		this.value = new arrayType( length * 4 );
+		if ( elementType.charAt( 0 ) === 'i' ) arrayType = Int32Array;
+		if ( elementType.charAt( 0 ) === 'u' ) arrayType = Uint32Array;
+
+		this.value = new arrayType( length * paddedElementLength );
 		this.bufferCount = length;
-		this.bufferType = builder.changeComponentType( 'vec4', builder.getComponentType( this._elementType ) );
+		this.bufferType = paddedType;
 
 		return super.setup( builder );
 
 	}
 
+	/**
+	 * Overwrites the default `element()` method to provide element access
+	 * based on {@link UniformArrayNode}.
+	 *
+	 * @param {IndexNode} indexNode - The index node.
+	 * @return {UniformArrayElementNode}
+	 */
 	element( indexNode ) {
 
 		return nodeObject( new UniformArrayElementNode( this, nodeObject( indexNode ) ) );
@@ -141,12 +336,26 @@ class UniformArrayNode extends BufferNode {
 
 export default UniformArrayNode;
 
+/**
+ * TSL function for creating an uniform array node.
+ *
+ * @tsl
+ * @function
+ * @param {Array<any>} values - Array-like data.
+ * @param {?string} nodeType - The data type of the array elements.
+ * @returns {UniformArrayNode}
+ */
 export const uniformArray = ( values, nodeType ) => nodeObject( new UniformArrayNode( values, nodeType ) );
 
-addNodeClass( 'UniformArrayNode', UniformArrayNode );
-
-//
-
+/**
+ * @tsl
+ * @function
+ * @deprecated since r168. Use {@link uniformArray} instead.
+ *
+ * @param {Array<any>} values - Array-like data.
+ * @param {string} nodeType - The data type of the array elements.
+ * @returns {UniformArrayNode}
+ */
 export const uniforms = ( values, nodeType ) => { // @deprecated, r168
 
 	console.warn( 'TSL.UniformArrayNode: uniforms() has been renamed to uniformArray().' );

package/src/nodes/accessors/UserDataNode.js

@@ -1,22 +1,62 @@
 import ReferenceNode from './ReferenceNode.js';
-import { addNodeClass } from '../core/Node.js';
-import { nodeObject } from '../shadernode/ShaderNode.js';
+import { nodeObject } from '../tsl/TSLBase.js';
 
+/**
+ * A special type of reference node that allows to link values in
+ * `userData` fields to node objects.
+ * ```js
+ * sprite.userData.rotation = 1; // stores individual rotation per sprite
+ *
+ * const material = new THREE.SpriteNodeMaterial();
+ * material.rotationNode = userData( 'rotation', 'float' );
+ * ```
+ * Since `UserDataNode` is extended from {@link ReferenceNode}, the node value
+ * will automatically be updated when the `rotation` user data field changes.
+ *
+ * @augments ReferenceNode
+ */
 class UserDataNode extends ReferenceNode {
 
+	static get type() {
+
+		return 'UserDataNode';
+
+	}
+
+	/**
+	 * Constructs a new user data node.
+	 *
+	 * @param {string} property - The property name that should be referenced by the node.
+	 * @param {string} inputType - The node data type of the reference.
+	 * @param {?Object} [userData=null] - A reference to the `userData` object. If not provided, the `userData` property of the 3D object that uses the node material is evaluated.
+	 */
 	constructor( property, inputType, userData = null ) {
 
 		super( property, inputType, userData );
 
+		/**
+		 * A reference to the `userData` object. If not provided, the `userData`
+		 * property of the 3D object that uses the node material is evaluated.
+		 *
+		 * @type {?Object}
+		 * @default null
+		 */
 		this.userData = userData;
 
 	}
 
-	update( frame ) {
+	/**
+	 * Overwritten to make sure {@link ReferenceNode#reference} points to the correct
+	 * `userData` field.
+	 *
+	 * @param {(NodeFrame|NodeBuilder)} state - The current state to evaluate.
+	 * @return {Object} A reference to the `userData` field.
+	 */
+	updateReference( state ) {
 
-		this.reference = this.userData !== null ? this.userData : frame.object.userData;
+		this.reference = this.userData !== null ? this.userData : state.object.userData;
 
-		super.update( frame );
+		return this.reference;
 
 	}
 
@@ -24,6 +64,14 @@ class UserDataNode extends ReferenceNode {
 
 export default UserDataNode;
 
+/**
+ * TSL function for creating a user data node.
+ *
+ * @tsl
+ * @function
+ * @param {string} name - The property name that should be referenced by the node.
+ * @param {string} inputType - The node data type of the reference.
+ * @param {?Object} userData - A reference to the `userData` object. If not provided, the `userData` property of the 3D object that uses the node material is evaluated.
+ * @returns {UserDataNode}
+ */
 export const userData = ( name, inputType, userData ) => nodeObject( new UserDataNode( name, inputType, userData ) );
-
-addNodeClass( 'UserDataNode', UserDataNode );

package/src/nodes/accessors/VelocityNode.js

@@ -0,0 +1,223 @@
+import TempNode from '../core/TempNode.js';
+import { modelViewMatrix } from './ModelNode.js';
+import { positionLocal, positionPrevious } from './Position.js';
+import { nodeImmutable } from '../tsl/TSLBase.js';
+import { NodeUpdateType } from '../core/constants.js';
+import { Matrix4 } from '../../math/Matrix4.js';
+import { uniform } from '../core/UniformNode.js';
+import { sub } from '../math/OperatorNode.js';
+import { cameraProjectionMatrix } from './Camera.js';
+import { renderGroup } from '../core/UniformGroupNode.js';
+
+const _objectData = new WeakMap();
+
+/**
+ * A node for representing motion or velocity vectors. Foundation
+ * for advanced post processing effects like motion blur or TRAA.
+ *
+ * The node keeps track of the model, view and projection matrices
+ * of the previous frame and uses them to compute offsets in NDC space.
+ * These offsets represent the final velocity.
+ *
+ * @augments TempNode
+ */
+class VelocityNode extends TempNode {
+
+	static get type() {
+
+		return 'VelocityNode';
+
+	}
+
+	/**
+	 * Constructs a new vertex color node.
+	 */
+	constructor() {
+
+		super( 'vec2' );
+
+		/**
+		 * The current projection matrix.
+		 *
+		 * @type {?Matrix4}
+		 * @default null
+		 */
+		this.projectionMatrix = null;
+
+		/**
+		 * Overwritten since velocity nodes are updated per object.
+		 *
+		 * @type {string}
+		 * @default 'object'
+		 */
+		this.updateType = NodeUpdateType.OBJECT;
+
+		/**
+		 * Overwritten since velocity nodes save data after the update.
+		 *
+		 * @type {string}
+		 * @default 'object'
+		 */
+		this.updateAfterType = NodeUpdateType.OBJECT;
+
+		/**
+		 * Uniform node representing the previous model matrix in world space.
+		 *
+		 * @type {UniformNode<mat4>}
+		 * @default null
+		 */
+		this.previousModelWorldMatrix = uniform( new Matrix4() );
+
+		/**
+		 * Uniform node representing the previous projection matrix.
+		 *
+		 * @type {UniformNode<mat4>}
+		 * @default null
+		 */
+		this.previousProjectionMatrix = uniform( new Matrix4() ).setGroup( renderGroup );
+
+		/**
+		 * Uniform node representing the previous view matrix.
+		 *
+		 * @type {UniformNode<mat4>}
+		 * @default null
+		 */
+		this.previousCameraViewMatrix = uniform( new Matrix4() );
+
+	}
+
+	/**
+	 * Sets the given projection matrix.
+	 *
+	 * @param {Matrix4} projectionMatrix - The projection matrix to set.
+	 */
+	setProjectionMatrix( projectionMatrix ) {
+
+		this.projectionMatrix = projectionMatrix;
+
+	}
+
+	/**
+	 * Updates velocity specific uniforms.
+	 *
+	 * @param {NodeFrame} frame - A reference to the current node frame.
+	 */
+	update( { frameId, camera, object } ) {
+
+		const previousModelMatrix = getPreviousMatrix( object );
+
+		this.previousModelWorldMatrix.value.copy( previousModelMatrix );
+
+		//
+
+		const cameraData = getData( camera );
+
+		if ( cameraData.frameId !== frameId ) {
+
+			cameraData.frameId = frameId;
+
+			if ( cameraData.previousProjectionMatrix === undefined ) {
+
+				cameraData.previousProjectionMatrix = new Matrix4();
+				cameraData.previousCameraViewMatrix = new Matrix4();
+
+				cameraData.currentProjectionMatrix = new Matrix4();
+				cameraData.currentCameraViewMatrix = new Matrix4();
+
+				cameraData.previousProjectionMatrix.copy( this.projectionMatrix || camera.projectionMatrix );
+				cameraData.previousCameraViewMatrix.copy( camera.matrixWorldInverse );
+
+			} else {
+
+				cameraData.previousProjectionMatrix.copy( cameraData.currentProjectionMatrix );
+				cameraData.previousCameraViewMatrix.copy( cameraData.currentCameraViewMatrix );
+
+			}
+
+			cameraData.currentProjectionMatrix.copy( this.projectionMatrix || camera.projectionMatrix );
+			cameraData.currentCameraViewMatrix.copy( camera.matrixWorldInverse );
+
+			this.previousProjectionMatrix.value.copy( cameraData.previousProjectionMatrix );
+			this.previousCameraViewMatrix.value.copy( cameraData.previousCameraViewMatrix );
+
+		}
+
+	}
+
+	/**
+	 * Overwritten to updated velocity specific uniforms.
+	 *
+	 * @param {NodeFrame} frame - A reference to the current node frame.
+	 */
+	updateAfter( { object } ) {
+
+		getPreviousMatrix( object ).copy( object.matrixWorld );
+
+	}
+
+	/**
+	 * Implements the velocity computation based on the previous and current vertex data.
+	 *
+	 * @param {NodeBuilder} builder - A reference to the current node builder.
+	 * @return {Node<vec2>} The motion vector.
+	 */
+	setup( /*builder*/ ) {
+
+		const projectionMatrix = ( this.projectionMatrix === null ) ? cameraProjectionMatrix : uniform( this.projectionMatrix );
+
+		const previousModelViewMatrix = this.previousCameraViewMatrix.mul( this.previousModelWorldMatrix );
+
+		const clipPositionCurrent = projectionMatrix.mul( modelViewMatrix ).mul( positionLocal );
+		const clipPositionPrevious = this.previousProjectionMatrix.mul( previousModelViewMatrix ).mul( positionPrevious );
+
+		const ndcPositionCurrent = clipPositionCurrent.xy.div( clipPositionCurrent.w );
+		const ndcPositionPrevious = clipPositionPrevious.xy.div( clipPositionPrevious.w );
+
+		const velocity = sub( ndcPositionCurrent, ndcPositionPrevious );
+
+		return velocity;
+
+	}
+
+}
+
+function getData( object ) {
+
+	let objectData = _objectData.get( object );
+
+	if ( objectData === undefined ) {
+
+		objectData = {};
+		_objectData.set( object, objectData );
+
+	}
+
+	return objectData;
+
+}
+
+function getPreviousMatrix( object, index = 0 ) {
+
+	const objectData = getData( object );
+
+	let matrix = objectData[ index ];
+
+	if ( matrix === undefined ) {
+
+		objectData[ index ] = matrix = new Matrix4();
+
+	}
+
+	return matrix;
+
+}
+
+export default VelocityNode;
+
+/**
+ * TSL object that represents the velocity of a render pass.
+ *
+ * @tsl
+ * @type {VelocityNode}
+ */
+export const velocity = /*@__PURE__*/ nodeImmutable( VelocityNode );