@plastic-software/three 0.167.4 → 0.174.0

package/src/nodes/core/NodeUtils.js

@@ -1,32 +1,116 @@
 import { Color } from '../../math/Color.js';
+import { Matrix2 } from '../../math/Matrix2.js';
 import { Matrix3 } from '../../math/Matrix3.js';
 import { Matrix4 } from '../../math/Matrix4.js';
 import { Vector2 } from '../../math/Vector2.js';
 import { Vector3 } from '../../math/Vector3.js';
 import { Vector4 } from '../../math/Vector4.js';
 
+// cyrb53 (c) 2018 bryc (github.com/bryc). License: Public domain. Attribution appreciated.
+// A fast and simple 64-bit (or 53-bit) string hash function with decent collision resistance.
+// Largely inspired by MurmurHash2/3, but with a focus on speed/simplicity.
+// See https://stackoverflow.com/questions/7616461/generate-a-hash-from-string-in-javascript/52171480#52171480
+// https://github.com/bryc/code/blob/master/jshash/experimental/cyrb53.js
+function cyrb53( value, seed = 0 ) {
+
+	let h1 = 0xdeadbeef ^ seed, h2 = 0x41c6ce57 ^ seed;
+
+	if ( value instanceof Array ) {
+
+		for ( let i = 0, val; i < value.length; i ++ ) {
+
+			val = value[ i ];
+			h1 = Math.imul( h1 ^ val, 2654435761 );
+			h2 = Math.imul( h2 ^ val, 1597334677 );
+
+		}
+
+	} else {
+
+		for ( let i = 0, ch; i < value.length; i ++ ) {
+
+			ch = value.charCodeAt( i );
+			h1 = Math.imul( h1 ^ ch, 2654435761 );
+			h2 = Math.imul( h2 ^ ch, 1597334677 );
+
+		}
+
+	}
+
+	h1 = Math.imul( h1 ^ ( h1 >>> 16 ), 2246822507 );
+	h1 ^= Math.imul( h2 ^ ( h2 >>> 13 ), 3266489909 );
+	h2 = Math.imul( h2 ^ ( h2 >>> 16 ), 2246822507 );
+	h2 ^= Math.imul( h1 ^ ( h1 >>> 13 ), 3266489909 );
+
+	return 4294967296 * ( 2097151 & h2 ) + ( h1 >>> 0 );
+
+}
+
+/**
+ * Computes a hash for the given string.
+ *
+ * @method
+ * @param {string} str - The string to be hashed.
+ * @return {number} The hash.
+ */
+export const hashString = ( str ) => cyrb53( str );
+
+/**
+ * Computes a hash for the given array.
+ *
+ * @method
+ * @param {Array<number>} array - The array to be hashed.
+ * @return {number} The hash.
+ */
+export const hashArray = ( array ) => cyrb53( array );
+
+/**
+ * Computes a hash for the given list of parameters.
+ *
+ * @method
+ * @param {...number} params - A list of parameters.
+ * @return {number} The hash.
+ */
+export const hash = ( ...params ) => cyrb53( params );
+
+/**
+ * Computes a cache key for the given node.
+ *
+ * @method
+ * @param {Object|Node} object - The object to be hashed.
+ * @param {boolean} [force=false] - Whether to force a cache key computation or not.
+ * @return {number} The hash.
+ */
 export function getCacheKey( object, force = false ) {
 
-	let cacheKey = '{';
+	const values = [];
 
 	if ( object.isNode === true ) {
 
-		cacheKey += object.id;
+		values.push( object.id );
+		object = object.getSelf();
 
 	}
 
 	for ( const { property, childNode } of getNodeChildren( object ) ) {
 
-		cacheKey += ',' + property.slice( 0, - 4 ) + ':' + childNode.getCacheKey( force );
+		values.push( cyrb53( property.slice( 0, - 4 ) ), childNode.getCacheKey( force ) );
 
 	}
 
-	cacheKey += '}';
-
-	return cacheKey;
+	return cyrb53( values );
 
 }
 
+/**
+ * This generator function can be used to iterate over the node children
+ * of the given object.
+ *
+ * @generator
+ * @param {Object} node - The object to be hashed.
+ * @param {boolean} [toJSON=false] - Whether to return JSON or not.
+ * @yields {Object} A result node holding the property, index (if available) and the child node.
+ */
 export function* getNodeChildren( node, toJSON = false ) {
 
 	for ( const property in node ) {
@@ -74,6 +158,91 @@ export function* getNodeChildren( node, toJSON = false ) {
 
 }
 
+const typeFromLength = /*@__PURE__*/ new Map( [
+	[ 1, 'float' ],
+	[ 2, 'vec2' ],
+	[ 3, 'vec3' ],
+	[ 4, 'vec4' ],
+	[ 9, 'mat3' ],
+	[ 16, 'mat4' ]
+] );
+
+const dataFromObject = /*@__PURE__*/ new WeakMap();
+
+/**
+ * Returns the data type for the given the length.
+ *
+ * @method
+ * @param {number} length - The length.
+ * @return {string} The data type.
+ */
+export function getTypeFromLength( length ) {
+
+	return typeFromLength.get( length );
+
+}
+
+/**
+ * Returns the typed array for the given data type.
+ *
+ * @method
+ * @param {string} type - The data type.
+ * @return {TypedArray} The typed array.
+ */
+export function getTypedArrayFromType( type ) {
+
+	// Handle component type for vectors and matrices
+	if ( /[iu]?vec\d/.test( type ) ) {
+
+		// Handle int vectors
+		if ( type.startsWith( 'ivec' ) ) return Int32Array;
+		// Handle uint vectors
+		if ( type.startsWith( 'uvec' ) ) return Uint32Array;
+		// Default to float vectors
+		return Float32Array;
+
+	}
+
+	// Handle matrices (always float)
+	if ( /mat\d/.test( type ) ) return Float32Array;
+
+	// Basic types
+	if ( /float/.test( type ) ) return Float32Array;
+	if ( /uint/.test( type ) ) return Uint32Array;
+	if ( /int/.test( type ) ) return Int32Array;
+
+	throw new Error( `THREE.NodeUtils: Unsupported type: ${type}` );
+
+}
+
+/**
+ * Returns the length for the given data type.
+ *
+ * @method
+ * @param {string} type - The data type.
+ * @return {number} The length.
+ */
+export function getLengthFromType( type ) {
+
+	if ( /float|int|uint/.test( type ) ) return 1;
+	if ( /vec2/.test( type ) ) return 2;
+	if ( /vec3/.test( type ) ) return 3;
+	if ( /vec4/.test( type ) ) return 4;
+	if ( /mat2/.test( type ) ) return 4;
+	if ( /mat3/.test( type ) ) return 9;
+	if ( /mat4/.test( type ) ) return 16;
+
+	console.error( 'THREE.TSL: Unsupported type:', type );
+
+}
+
+/**
+ * Returns the data type for the given value.
+ *
+ * @method
+ * @param {any} value - The value.
+ * @return {?string} The data type.
+ */
 export function getValueType( value ) {
 
 	if ( value === undefined || value === null ) return null;
@@ -112,6 +281,10 @@ export function getValueType( value ) {
 
 		return 'vec4';
 
+	} else if ( value.isMatrix2 === true ) {
+
+		return 'mat2';
+
 	} else if ( value.isMatrix3 === true ) {
 
 		return 'mat3';
@@ -134,6 +307,14 @@ export function getValueType( value ) {
 
 }
 
+/**
+ * Returns the value/object for the given data type and parameters.
+ *
+ * @method
+ * @param {string} type - The given type.
+ * @param {...any} params - A parameter list.
+ * @return {any} The value/object.
+ */
 export function getValueFromType( type, ...params ) {
 
 	const last4 = type ? type.slice( - 4 ) : undefined;
@@ -162,6 +343,10 @@ export function getValueFromType( type, ...params ) {
 
 		return new Vector4( ...params );
 
+	} else if ( last4 === 'mat2' ) {
+
+		return new Matrix2( ...params );
+
 	} else if ( last4 === 'mat3' ) {
 
 		return new Matrix3( ...params );
@@ -192,6 +377,34 @@ export function getValueFromType( type, ...params ) {
 
 }
 
+/**
+ * Gets the object data that can be shared between different rendering steps.
+ *
+ * @param {Object} object - The object to get the data for.
+ * @return {Object} The object data.
+ */
+export function getDataFromObject( object ) {
+
+	let data = dataFromObject.get( object );
+
+	if ( data === undefined ) {
+
+		data = {};
+		dataFromObject.set( object, data );
+
+	}
+
+	return data;
+
+}
+
+/**
+ * Converts the given array buffer to a Base64 string.
+ *
+ * @method
+ * @param {ArrayBuffer} arrayBuffer - The array buffer.
+ * @return {string} The Base64 string.
+ */
 export function arrayBufferToBase64( arrayBuffer ) {
 
 	let chars = '';
@@ -208,6 +421,13 @@ export function arrayBufferToBase64( arrayBuffer ) {
 
 }
 
+/**
+ * Converts the given Base64 string to an array buffer.
+ *
+ * @method
+ * @param {string} base64 - The Base64 string.
+ * @return {ArrayBuffer} The array buffer.
+ */
 export function base64ToArrayBuffer( base64 ) {
 
 	return Uint8Array.from( atob( base64 ), c => c.charCodeAt( 0 ) ).buffer;

package/src/nodes/core/NodeVar.js

@@ -1,12 +1,58 @@
+/**
+ * {@link NodeBuilder} is going to create instances of this class during the build process
+ * of nodes. They represent the final shader variables that are going to be generated
+ * by the builder. A dictionary of node variables is maintained in {@link NodeBuilder#vars} for
+ * this purpose.
+ */
 class NodeVar {
 
-	constructor( name, type ) {
+	/**
+	 * Constructs a new node variable.
+	 *
+	 * @param {string} name - The name of the variable.
+	 * @param {string} type - The type of the variable.
+	 * @param {boolean} [readOnly=false] - The read-only flag.
+	 * @param {?number} [count=null] - The size.
+	 */
+	constructor( name, type, readOnly = false, count = null ) {
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isNodeVar = true;
 
+		/**
+		 * The name of the variable.
+		 *
+		 * @type {string}
+		 */
 		this.name = name;
+
+		/**
+		 * The type of the variable.
+		 *
+		 * @type {string}
+		 */
 		this.type = type;
 
+		/**
+		 *  The read-only flag.
+		 *
+		 * @type {boolean}
+		 */
+		this.readOnly = readOnly;
+
+		/**
+		 * The size.
+		 *
+		 * @type {?number}
+		 */
+		this.count = count;
+
 	}
 
 }

package/src/nodes/core/NodeVarying.js

@@ -1,13 +1,41 @@
 import NodeVar from './NodeVar.js';
 
+/**
+ * {@link NodeBuilder} is going to create instances of this class during the build process
+ * of nodes. They represent the final shader varyings that are going to be generated
+ * by the builder. An array of node varyings is maintained in {@link NodeBuilder#varyings} for
+ * this purpose.
+ *
+ * @augments NodeVar
+ */
 class NodeVarying extends NodeVar {
 
+	/**
+	 * Constructs a new node varying.
+	 *
+	 * @param {string} name - The name of the varying.
+	 * @param {string} type - The type of the varying.
+	 */
 	constructor( name, type ) {
 
 		super( name, type );
 
+		/**
+		 * Whether this varying requires interpolation or not. This property can be used
+		 * to check if the varying can be optimized for a variable.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
 		this.needsInterpolation = false;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isNodeVarying = true;
 
 	}

package/src/nodes/core/OutputStructNode.js

@@ -1,37 +1,75 @@
-import Node, { addNodeClass } from './Node.js';
-import StructTypeNode from './StructTypeNode.js';
-import { nodeProxy } from '../shadernode/ShaderNode.js';
-
+import Node from './Node.js';
+import { nodeProxy } from '../tsl/TSLBase.js';
+
+/**
+ * This node can be used to define multiple outputs in a shader programs.
+ *
+ * @augments Node
+ */
 class OutputStructNode extends Node {
 
+	static get type() {
+
+		return 'OutputStructNode';
+
+	}
+
+	/**
+	 * Constructs a new output struct node. The constructor can be invoked with an
+	 * arbitrary number of nodes representing the members.
+	 *
+	 * @param {...Node} members - A parameter list of nodes.
+	 */
 	constructor( ...members ) {
 
 		super();
 
+		/**
+		 * An array of nodes which defines the output.
+		 *
+		 * @type {Array<Node>}
+		 */
 		this.members = members;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isOutputStructNode = true;
 
 	}
 
-	setup( builder ) {
+	getNodeType( builder ) {
 
-		super.setup( builder );
+		const properties = builder.getNodeProperties( this );
 
-		const members = this.members;
-		const types = [];
+		if ( properties.membersLayout === undefined ) {
 
-		for ( let i = 0; i < members.length; i ++ ) {
+			const members = this.members;
+			const membersLayout = [];
+
+			for ( let i = 0; i < members.length; i ++ ) {
+
+				const name = 'm' + i;
+				const type = members[ i ].getNodeType( builder );
 
-			types.push( members[ i ].getNodeType( builder ) );
+				membersLayout.push( { name, type, index: i } );
+
+			}
+
+			properties.membersLayout = membersLayout;
+			properties.structType = builder.getOutputStructTypeFromNode( this, properties.membersLayout );
 
 		}
 
-		this.nodeType = builder.getStructTypeFromNode( new StructTypeNode( types ) ).name;
+		return properties.structType.name;
 
 	}
 
-	generate( builder, output ) {
+	generate( builder ) {
 
 		const propertyName = builder.getOutputStructName();
 		const members = this.members;
@@ -40,9 +78,9 @@ class OutputStructNode extends Node {
 
 		for ( let i = 0; i < members.length; i ++ ) {
 
-			const snippet = members[ i ].build( builder, output );
+			const snippet = members[ i ].build( builder );
 
-			builder.addLineFlowCode( `${ structPrefix }m${ i } = ${ snippet }` );
+			builder.addLineFlowCode( `${ structPrefix }m${ i } = ${ snippet }`, this );
 
 		}
 
@@ -54,6 +92,12 @@ class OutputStructNode extends Node {
 
 export default OutputStructNode;
 
-export const outputStruct = nodeProxy( OutputStructNode );
-
-addNodeClass( 'OutputStructNode', OutputStructNode );
+/**
+ * TSL function for creating an output struct node.
+ *
+ * @tsl
+ * @function
+ * @param {...Node} members - A parameter list of nodes.
+ * @returns {OutputStructNode}
+ */
+export const outputStruct = /*@__PURE__*/ nodeProxy( OutputStructNode );

package/src/nodes/core/ParameterNode.js

@@ -1,13 +1,36 @@
-import { addNodeClass } from './Node.js';
-import { nodeObject } from '../shadernode/ShaderNode.js';
+import { nodeObject } from '../tsl/TSLBase.js';
 import PropertyNode from './PropertyNode.js';
 
+/**
+ * Special version of {@link PropertyNode} which is used for parameters.
+ *
+ * @augments PropertyNode
+ */
 class ParameterNode extends PropertyNode {
 
+	static get type() {
+
+		return 'ParameterNode';
+
+	}
+
+	/**
+	 * Constructs a new parameter node.
+	 *
+	 * @param {string} nodeType - The type of the node.
+	 * @param {?string} [name=null] - The name of the parameter in the shader.
+	 */
 	constructor( nodeType, name = null ) {
 
 		super( nodeType, name );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isParameterNode = true;
 
 	}
@@ -28,6 +51,13 @@ class ParameterNode extends PropertyNode {
 
 export default ParameterNode;
 
+/**
+ * TSL function for creating a parameter node.
+ *
+ * @tsl
+ * @function
+ * @param {string} type - The type of the node.
+ * @param {?string} name - The name of the parameter in the shader.
+ * @returns {ParameterNode}
+ */
 export const parameter = ( type, name ) => nodeObject( new ParameterNode( type, name ) );
-
-addNodeClass( 'ParameterNode', ParameterNode );