@plastic-software/three 0.167.4 → 0.174.0

package/src/renderers/common/nodes/NodeLibrary.js

@@ -0,0 +1,194 @@
+/**
+ * The purpose of a node library is to assign node implementations
+ * to existing library features. In `WebGPURenderer` lights, materials
+ * which are not based on `NodeMaterial` as well as tone mapping techniques
+ * are implemented with node-based modules.
+ *
+ * @private
+ */
+class NodeLibrary {
+
+	/**
+	 * Constructs a new node library.
+	 */
+	constructor() {
+
+		/**
+		 * A weak map that maps lights to light nodes.
+		 *
+		 * @type {WeakMap<Light.constructor,AnalyticLightNode.constructor>}
+		 */
+		this.lightNodes = new WeakMap();
+
+		/**
+		 * A map that maps materials to node materials.
+		 *
+		 * @type {Map<string,NodeMaterial.constructor>}
+		 */
+		this.materialNodes = new Map();
+
+		/**
+		 * A map that maps tone mapping techniques (constants)
+		 * to tone mapping node functions.
+		 *
+		 * @type {Map<number,Function>}
+		 */
+		this.toneMappingNodes = new Map();
+
+	}
+
+	/**
+	 * Returns a matching node material instance for the given material object.
+	 *
+	 * This method also assigns/copies the properties of the given material object
+	 * to the node material. This is done to make sure the current material
+	 * configuration carries over to the node version.
+	 *
+	 * @param {Material} material - A material.
+	 * @return {NodeMaterial} The corresponding node material.
+	 */
+	fromMaterial( material ) {
+
+		if ( material.isNodeMaterial ) return material;
+
+		let nodeMaterial = null;
+
+		const nodeMaterialClass = this.getMaterialNodeClass( material.type );
+
+		if ( nodeMaterialClass !== null ) {
+
+			nodeMaterial = new nodeMaterialClass();
+
+			for ( const key in material ) {
+
+				nodeMaterial[ key ] = material[ key ];
+
+			}
+
+		}
+
+		return nodeMaterial;
+
+	}
+
+	/**
+	 * Adds a tone mapping node function for a tone mapping technique (constant).
+	 *
+	 * @param {Function} toneMappingNode - The tone mapping node function.
+	 * @param {number} toneMapping - The tone mapping.
+	 */
+	addToneMapping( toneMappingNode, toneMapping ) {
+
+		this.addType( toneMappingNode, toneMapping, this.toneMappingNodes );
+
+	}
+
+	/**
+	 * Returns a tone mapping node function for a tone mapping technique (constant).
+	 *
+	 * @param {number} toneMapping - The tone mapping.
+	 * @return {?Function} The tone mapping node function. Returns `null` if no node function is found.
+	 */
+	getToneMappingFunction( toneMapping ) {
+
+		return this.toneMappingNodes.get( toneMapping ) || null;
+
+	}
+
+	/**
+	 * Returns a node material class definition for a material type.
+	 *
+	 * @param {string} materialType - The material type.
+	 * @return {?NodeMaterial.constructor} The node material class definition. Returns `null` if no node material is found.
+	 */
+	getMaterialNodeClass( materialType ) {
+
+		return this.materialNodes.get( materialType ) || null;
+
+	}
+
+	/**
+	 * Adds a node material class definition for a given material type.
+	 *
+	 * @param {NodeMaterial.constructor} materialNodeClass - The node material class definition.
+	 * @param {string} materialClassType - The material type.
+	 */
+	addMaterial( materialNodeClass, materialClassType ) {
+
+		this.addType( materialNodeClass, materialClassType, this.materialNodes );
+
+	}
+
+	/**
+	 * Returns a light node class definition for a light class definition.
+	 *
+	 * @param {Light.constructor} light - The light class definition.
+	 * @return {?AnalyticLightNode.constructor} The light node class definition. Returns `null` if no light node is found.
+	 */
+	getLightNodeClass( light ) {
+
+		return this.lightNodes.get( light ) || null;
+
+	}
+
+	/**
+	 * Adds a light node class definition for a given light class definition.
+	 *
+	 * @param {AnalyticLightNode.constructor} lightNodeClass - The light node class definition.
+	 * @param {Light.constructor} lightClass - The light class definition.
+	 */
+	addLight( lightNodeClass, lightClass ) {
+
+		this.addClass( lightNodeClass, lightClass, this.lightNodes );
+
+	}
+
+	/**
+	 * Adds a node class definition for the given type to the provided type library.
+	 *
+	 * @param {any} nodeClass - The node class definition.
+	 * @param {number|string} type - The object type.
+	 * @param {Map} library - The type library.
+	 */
+	addType( nodeClass, type, library ) {
+
+		if ( library.has( type ) ) {
+
+			console.warn( `Redefinition of node ${ type }` );
+			return;
+
+		}
+
+		if ( typeof nodeClass !== 'function' ) throw new Error( `Node class ${ nodeClass.name } is not a class.` );
+		if ( typeof type === 'function' || typeof type === 'object' ) throw new Error( `Base class ${ type } is not a class.` );
+
+		library.set( type, nodeClass );
+
+	}
+
+	/**
+	 * Adds a node class definition for the given class definition to the provided type library.
+	 *
+	 * @param {any} nodeClass - The node class definition.
+	 * @param {any} baseClass - The class definition.
+	 * @param {WeakMap} library - The type library.
+	 */
+	addClass( nodeClass, baseClass, library ) {
+
+		if ( library.has( baseClass ) ) {
+
+			console.warn( `Redefinition of node ${ baseClass.name }` );
+			return;
+
+		}
+
+		if ( typeof nodeClass !== 'function' ) throw new Error( `Node class ${ nodeClass.name } is not a class.` );
+		if ( typeof baseClass !== 'function' ) throw new Error( `Base class ${ baseClass.name } is not a class.` );
+
+		library.set( baseClass, nodeClass );
+
+	}
+
+}
+
+export default NodeLibrary;

package/src/renderers/common/nodes/NodeSampledTexture.js

@@ -1,24 +1,68 @@
 import { SampledTexture } from '../SampledTexture.js';
 
+/**
+ * A special form of sampled texture binding type.
+ * It's texture value is managed by a node object.
+ *
+ * @private
+ * @augments SampledTexture
+ */
 class NodeSampledTexture extends SampledTexture {
 
+	/**
+	 * Constructs a new node-based sampled texture.
+	 *
+	 * @param {string} name - The textures's name.
+	 * @param {TextureNode} textureNode - The texture node.
+	 * @param {UniformGroupNode} groupNode - The uniform group node.
+	 * @param {?string} [access=null] - The access type.
+	 */
 	constructor( name, textureNode, groupNode, access = null ) {
 
 		super( name, textureNode ? textureNode.value : null );
 
+		/**
+		 * The texture node.
+		 *
+		 * @type {TextureNode}
+		 */
 		this.textureNode = textureNode;
+
+		/**
+		 * The uniform group node.
+		 *
+		 * @type {UniformGroupNode}
+		 */
 		this.groupNode = groupNode;
 
+		/**
+		 * The access type.
+		 *
+		 * @type {?string}
+		 * @default null
+		 */
 		this.access = access;
 
 	}
 
-	get needsBindingsUpdate() {
+	/**
+	 * Overwrites the default to additionally check if the node value has changed.
+	 *
+	 * @param {number} generation - The generation.
+	 * @return {boolean} Whether an update is required or not.
+	 */
+	needsBindingsUpdate( generation ) {
 
-		return this.textureNode.value !== this.texture || super.needsBindingsUpdate;
+		return this.textureNode.value !== this.texture || super.needsBindingsUpdate( generation );
 
 	}
 
+	/**
+	 * Updates the binding.
+	 *
+	 * @return {boolean} Whether the texture has been updated and must be
+	 * uploaded to the GPU.
+	 */
 	update() {
 
 		const { textureNode } = this;
@@ -37,24 +81,68 @@ class NodeSampledTexture extends SampledTexture {
 
 }
 
+/**
+ * A special form of sampled cube texture binding type.
+ * It's texture value is managed by a node object.
+ *
+ * @private
+ * @augments NodeSampledTexture
+ */
 class NodeSampledCubeTexture extends NodeSampledTexture {
 
-	constructor( name, textureNode, groupNode, access ) {
+	/**
+	 * Constructs a new node-based sampled cube texture.
+	 *
+	 * @param {string} name - The textures's name.
+	 * @param {TextureNode} textureNode - The texture node.
+	 * @param {UniformGroupNode} groupNode - The uniform group node.
+	 * @param {?string} [access=null] - The access type.
+	 */
+	constructor( name, textureNode, groupNode, access = null ) {
 
 		super( name, textureNode, groupNode, access );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSampledCubeTexture = true;
 
 	}
 
 }
 
+/**
+ * A special form of sampled 3D texture binding type.
+ * It's texture value is managed by a node object.
+ *
+ * @private
+ * @augments NodeSampledTexture
+ */
 class NodeSampledTexture3D extends NodeSampledTexture {
 
-	constructor( name, textureNode, groupNode, access ) {
+	/**
+	 * Constructs a new node-based sampled 3D texture.
+	 *
+	 * @param {string} name - The textures's name.
+	 * @param {TextureNode} textureNode - The texture node.
+	 * @param {UniformGroupNode} groupNode - The uniform group node.
+	 * @param {?string} [access=null] - The access type.
+	 */
+	constructor( name, textureNode, groupNode, access = null ) {
 
 		super( name, textureNode, groupNode, access );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSampledTexture3D = true;
 
 	}

package/src/renderers/common/nodes/NodeSampler.js

@@ -1,16 +1,44 @@
 import Sampler from '../Sampler.js';
 
+/**
+ * A special form of sampler binding type.
+ * It's texture value is managed by a node object.
+ *
+ * @private
+ * @augments Sampler
+ */
 class NodeSampler extends Sampler {
 
+	/**
+	 * Constructs a new node-based sampler.
+	 *
+	 * @param {string} name - The samplers's name.
+	 * @param {TextureNode} textureNode - The texture node.
+	 * @param {UniformGroupNode} groupNode - The uniform group node.
+	 */
 	constructor( name, textureNode, groupNode ) {
 
 		super( name, textureNode ? textureNode.value : null );
 
+		/**
+		 * The texture node.
+		 *
+		 * @type {TextureNode}
+		 */
 		this.textureNode = textureNode;
+
+		/**
+		 * The uniform group node.
+		 *
+		 * @type {UniformGroupNode}
+		 */
 		this.groupNode = groupNode;
 
 	}
 
+	/**
+	 * Updates the texture value of this sampler.
+	 */
 	update() {
 
 		this.texture = this.textureNode.value;

package/src/renderers/common/nodes/NodeStorageBuffer.js

@@ -1,21 +1,55 @@
 import StorageBuffer from '../StorageBuffer.js';
-import { GPUBufferBindingType } from '../../webgpu/utils/WebGPUConstants.js';
+import { NodeAccess } from '../../../nodes/core/constants.js';
 
 let _id = 0;
 
+/**
+ * A special form of storage buffer binding type.
+ * It's buffer value is managed by a node object.
+ *
+ * @private
+ * @augments StorageBuffer
+ */
 class NodeStorageBuffer extends StorageBuffer {
 
+	/**
+	 * Constructs a new node-based storage buffer.
+	 *
+	 * @param {StorageBufferNode} nodeUniform - The storage buffer node.
+	 * @param {UniformGroupNode} groupNode - The uniform group node.
+	 */
 	constructor( nodeUniform, groupNode ) {
 
 		super( 'StorageBuffer_' + _id ++, nodeUniform ? nodeUniform.value : null );
 
+		/**
+		 * The node uniform.
+		 *
+		 * @type {StorageBufferNode}
+		 */
 		this.nodeUniform = nodeUniform;
-		this.access = nodeUniform ? nodeUniform.access : GPUBufferBindingType.Storage;
-		this.groupNode = groupNode;
 
+		/**
+		 * The access type.
+		 *
+		 * @type {string}
+		 */
+		this.access = nodeUniform ? nodeUniform.access : NodeAccess.READ_WRITE;
+
+		/**
+		 * The uniform group node.
+		 *
+		 * @type {UniformGroupNode}
+		 */
+		this.groupNode = groupNode;
 
 	}
 
+	/**
+	 * The storage buffer.
+	 *
+	 * @type {BufferAttribute}
+	 */
 	get buffer() {
 
 		return this.nodeUniform.value;