@needle-tools/three 0.169.20 → 0.183.2-canary.0

package/src/nodes/accessors/StorageBufferNode.js

@@ -1,9 +1,41 @@
 import BufferNode from './BufferNode.js';
 import { bufferAttribute } from './BufferAttributeNode.js';
-import { nodeObject, varying } from '../tsl/TSLBase.js';
+import { varying } from '../tsl/TSLBase.js';
 import { storageElement } from '../utils/StorageArrayElementNode.js';
-import { GPUBufferBindingType } from '../../renderers/webgpu/utils/WebGPUConstants.js';
-
+import { NodeAccess } from '../core/constants.js';
+import { getTypeFromLength } from '../core/NodeUtils.js';
+
+/**
+ * This node is used in context of compute shaders and allows to define a
+ * storage buffer for data. A typical workflow is to create instances of
+ * this node with the convenience functions `attributeArray()` or `instancedArray()`,
+ * setup up a compute shader that writes into the buffers and then convert
+ * the storage buffers to attribute nodes for rendering.
+ *
+ * ```js
+ * const positionBuffer = instancedArray( particleCount, 'vec3' ); // the storage buffer node
+ *
+ * const computeInit = Fn( () => { // the compute shader
+ *
+ * 	const position = positionBuffer.element( instanceIndex );
+ *
+ * 	// compute position data
+ *
+ * 	position.x = 1;
+ * 	position.y = 1;
+ * 	position.z = 1;
+ *
+ * } )().compute( particleCount );
+ *
+ * const particleMaterial = new THREE.SpriteNodeMaterial();
+ * particleMaterial.positionNode = positionBuffer.toAttribute();
+ *
+ * renderer.computeAsync( computeInit );
+ *
+ * ```
+ *
+ * @augments BufferNode
+ */
 class StorageBufferNode extends BufferNode {
 
 	static get type() {
@@ -12,26 +44,113 @@ class StorageBufferNode extends BufferNode {
 
 	}
 
-	constructor( value, bufferType, bufferCount = 0 ) {
+	/**
+	 * Constructs a new storage buffer node.
+	 *
+	 * @param {StorageBufferAttribute|StorageInstancedBufferAttribute|BufferAttribute} value - The buffer data.
+	 * @param {?(string|Struct)} [bufferType=null] - The buffer type (e.g. `'vec3'`).
+	 * @param {number} [bufferCount=0] - The buffer count.
+	 */
+	constructor( value, bufferType = null, bufferCount = 0 ) {
+
+		let nodeType, structTypeNode = null;
+
+		if ( bufferType && bufferType.isStruct ) {
+
+			nodeType = 'struct';
+			structTypeNode = bufferType.layout;
+
+			if ( value.isStorageBufferAttribute || value.isStorageInstancedBufferAttribute ) {
+
+				bufferCount = value.count;
+
+			}
+
+		} else if ( bufferType === null && ( value.isStorageBufferAttribute || value.isStorageInstancedBufferAttribute ) ) {
+
+			nodeType = getTypeFromLength( value.itemSize );
+			bufferCount = value.count;
+
+		} else {
+
+			nodeType = bufferType;
+
+		}
 
-		super( value, bufferType, bufferCount );
+		super( value, nodeType, bufferCount );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isStorageBufferNode = true;
 
-		this.access = GPUBufferBindingType.Storage;
-		this.isAtomic = false;
 
-		this.bufferObject = false;
-		this.bufferCount = bufferCount;
+		/**
+		 * The buffer struct type.
+		 *
+		 * @type {?StructTypeNode}
+		 * @default null
+		 */
+		this.structTypeNode = structTypeNode;
+
+		/**
+		 * The access type of the texture node.
+		 *
+		 * @type {string}
+		 * @default 'readWrite'
+		 */
+		this.access = NodeAccess.READ_WRITE;
+
+		/**
+		 * Whether the node is atomic or not.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
+		this.isAtomic = false;
 
+		/**
+		 * Whether the node represents a PBO or not.
+		 * Only relevant for WebGL.
+		 *
+		 * @type {boolean}
+		 * @default false
+		 */
+		this.isPBO = false;
+
+		/**
+		 * A reference to the internal buffer attribute node.
+		 *
+		 * @private
+		 * @type {?BufferAttributeNode}
+		 * @default null
+		 */
 		this._attribute = null;
+
+		/**
+		 * A reference to the internal varying node.
+		 *
+		 * @private
+		 * @type {?VaryingNode}
+		 * @default null
+		 */
 		this._varying = null;
 
+		/**
+		 * `StorageBufferNode` sets this property to `true` by default.
+		 *
+		 * @type {boolean}
+		 * @default true
+		 */
 		this.global = true;
 
 		if ( value.isStorageBufferAttribute !== true && value.isStorageInstancedBufferAttribute !== true ) {
 
-			// TOOD: Improve it, possibly adding a new property to the BufferAttribute to identify it as a storage buffer read-only attribute in Renderer
+			// TODO: Improve it, possibly adding a new property to the BufferAttribute to identify it as a storage buffer read-only attribute in Renderer
 
 			if ( value.isInstancedBufferAttribute ) value.isStorageInstancedBufferAttribute = true;
 			else value.isStorageBufferAttribute = true;
@@ -40,6 +159,13 @@ class StorageBufferNode extends BufferNode {
 
 	}
 
+	/**
+	 * This method is overwritten since the buffer data might be shared
+	 * and thus the hash should be shared as well.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {string} The hash.
+	 */
 	getHash( builder ) {
 
 		if ( this.bufferCount === 0 ) {
@@ -64,26 +190,61 @@ class StorageBufferNode extends BufferNode {
 
 	}
 
+	/**
+	 * Overwrites the default implementation to return a fixed value `'indirectStorageBuffer'` or `'storageBuffer'`.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {string} The input type.
+	 */
 	getInputType( /*builder*/ ) {
 
-		return 'storageBuffer';
+		return this.value.isIndirectStorageBufferAttribute ? 'indirectStorageBuffer' : 'storageBuffer';
 
 	}
 
+	/**
+	 * Enables element access with the given index node.
+	 *
+	 * @param {IndexNode} indexNode - The index node.
+	 * @return {StorageArrayElementNode} A node representing the element access.
+	 */
 	element( indexNode ) {
 
 		return storageElement( this, indexNode );
 
 	}
 
-	setBufferObject( value ) {
+	/**
+	 * Defines whether this node is a PBO or not. Only relevant for WebGL.
+	 *
+	 * @param {boolean} value - The value so set.
+	 * @return {StorageBufferNode} A reference to this node.
+	 */
+	setPBO( value ) {
 
-		this.bufferObject = value;
+		this.isPBO = value;
 
 		return this;
 
 	}
 
+	/**
+	 * Returns the `isPBO` value.
+	 *
+	 * @return {boolean} Whether the node represents a PBO or not.
+	 */
+	getPBO() {
+
+		return this.isPBO;
+
+	}
+
+	/**
+	 * Defines the node access.
+	 *
+	 * @param {string} value - The node access.
+	 * @return {StorageBufferNode} A reference to this node.
+	 */
 	setAccess( value ) {
 
 		this.access = value;
@@ -92,12 +253,23 @@ class StorageBufferNode extends BufferNode {
 
 	}
 
+	/**
+	 * Convenience method for configuring a read-only node access.
+	 *
+	 * @return {StorageBufferNode} A reference to this node.
+	 */
 	toReadOnly() {
 
-		return this.setAccess( GPUBufferBindingType.ReadOnlyStorage );
+		return this.setAccess( NodeAccess.READ_ONLY );
 
 	}
 
+	/**
+	 * Defines whether the node is atomic or not.
+	 *
+	 * @param {boolean} value - The atomic flag.
+	 * @return {StorageBufferNode} A reference to this node.
+	 */
 	setAtomic( value ) {
 
 		this.isAtomic = value;
@@ -106,33 +278,105 @@ class StorageBufferNode extends BufferNode {
 
 	}
 
+	/**
+	 * Convenience method for making this node atomic.
+	 *
+	 * @return {StorageBufferNode} A reference to this node.
+	 */
 	toAtomic() {
 
 		return this.setAtomic( true );
 
 	}
 
-	generate( builder ) {
+	/**
+	 * Returns attribute data for this storage buffer node.
+	 *
+	 * @return {{attribute: BufferAttributeNode, varying: VaryingNode}} The attribute data.
+	 */
+	getAttributeData() {
 
-		if ( builder.isAvailable( 'storageBuffer' ) ) {
+		if ( this._attribute === null ) {
 
-			return super.generate( builder );
+			this._attribute = bufferAttribute( this.value );
+			this._varying = varying( this._attribute );
 
 		}
 
-		const nodeType = this.getNodeType( builder );
+		return {
+			attribute: this._attribute,
+			varying: this._varying
+		};
 
-		if ( this._attribute === null ) {
+	}
 
-			this._attribute = bufferAttribute( this.value );
-			this._varying = varying( this._attribute );
+	/**
+	 * This method is overwritten since the node type from the availability of storage buffers
+	 * and the attribute data.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {string} The node type.
+	 */
+	getNodeType( builder ) {
+
+		if ( this.structTypeNode !== null ) {
+
+			return this.structTypeNode.getNodeType( builder );
+
+		}
+
+		if ( builder.isAvailable( 'storageBuffer' ) || builder.isAvailable( 'indirectStorageBuffer' ) ) {
+
+			return super.getNodeType( builder );
+
+		}
+
+		const { attribute } = this.getAttributeData();
+
+		return attribute.getNodeType( builder );
+
+	}
+
+	/**
+	 * Returns the type of a member of the struct.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @param {string} name - The name of the member.
+	 * @return {string} The type of the member.
+	 */
+	getMemberType( builder, name ) {
+
+		if ( this.structTypeNode !== null ) {
+
+			return this.structTypeNode.getMemberType( builder, name );
+
+		}
+
+		return 'void';
+
+	}
+
+	/**
+	 * Generates the code snippet of the storage buffer node.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {string} The generated code snippet.
+	 */
+	generate( builder ) {
+
+		if ( this.structTypeNode !== null ) this.structTypeNode.build( builder );
+
+		if ( builder.isAvailable( 'storageBuffer' ) || builder.isAvailable( 'indirectStorageBuffer' ) ) {
+
+			return super.generate( builder );
 
 		}
 
+		const { attribute, varying } = this.getAttributeData();
 
-		const output = this._varying.build( builder, nodeType );
+		const output = varying.build( builder );
 
-		builder.registerTransform( output, this._attribute );
+		builder.registerTransform( output, attribute );
 
 		return output;
 
@@ -142,6 +386,14 @@ class StorageBufferNode extends BufferNode {
 
 export default StorageBufferNode;
 
-// Read-Write Storage
-export const storage = ( value, type, count ) => nodeObject( new StorageBufferNode( value, type, count ) );
-export const storageObject = ( value, type, count ) => nodeObject( new StorageBufferNode( value, type, count ).setBufferObject( true ) );
+/**
+ * TSL function for creating a storage buffer node.
+ *
+ * @tsl
+ * @function
+ * @param {StorageBufferAttribute|StorageInstancedBufferAttribute|BufferAttribute} value - The buffer data.
+ * @param {?(string|Struct)} [type=null] - The buffer type (e.g. `'vec3'`).
+ * @param {number} [count=0] - The buffer count.
+ * @returns {StorageBufferNode}
+ */
+export const storage = ( value, type = null, count = 0 ) => new StorageBufferNode( value, type, count );

package/src/nodes/accessors/StorageTextureNode.js

@@ -1,7 +1,38 @@
 import TextureNode from './TextureNode.js';
 import { nodeProxy } from '../tsl/TSLBase.js';
-import { GPUStorageTextureAccess } from '../../renderers/webgpu/utils/WebGPUConstants.js';
-
+import { NodeAccess } from '../core/constants.js';
+
+/**
+ * This special version of a texture node can be used to
+ * write data into a storage texture with a compute shader.
+ *
+ * ```js
+ * const storageTexture = new THREE.StorageTexture( width, height );
+ *
+ * const computeTexture = Fn( ( { storageTexture } ) => {
+ *
+ * 	const posX = instanceIndex.mod( width );
+ * 	const posY = instanceIndex.div( width );
+ * 	const indexUV = uvec2( posX, posY );
+ *
+ * 	// generate RGB values
+ *
+ * 	const r = 1;
+ * 	const g = 1;
+ * 	const b = 1;
+ *
+ * 	textureStore( storageTexture, indexUV, vec4( r, g, b, 1 ) ).toWriteOnly();
+ *
+ * } );
+ *
+ * const computeNode = computeTexture( { storageTexture } ).compute( width * height );
+ * renderer.computeAsync( computeNode );
+ * ```
+ *
+ * This node can only be used with a WebGPU backend.
+ *
+ * @augments TextureNode
+ */
 class StorageTextureNode extends TextureNode {
 
 	static get type() {
@@ -10,18 +41,58 @@ class StorageTextureNode extends TextureNode {
 
 	}
 
+	/**
+	 * Constructs a new storage texture node.
+	 *
+	 * @param {StorageTexture} value - The storage texture.
+	 * @param {Node<vec2|vec3>} uvNode - The uv node.
+	 * @param {?Node} [storeNode=null] - The value node that should be stored in the texture.
+	 */
 	constructor( value, uvNode, storeNode = null ) {
 
 		super( value, uvNode );
 
+		/**
+		 * The value node that should be stored in the texture.
+		 *
+		 * @type {?Node}
+		 * @default null
+		 */
 		this.storeNode = storeNode;
 
+		/**
+		 * The mip level to write to for storage textures.
+		 *
+		 * @type {number}
+		 * @default 0
+		 */
+		this.mipLevel = 0;
+
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isStorageTextureNode = true;
 
-		this.access = GPUStorageTextureAccess.WriteOnly;
+		/**
+		 * The access type of the texture node.
+		 *
+		 * @type {string}
+		 * @default 'writeOnly'
+		 */
+		this.access = NodeAccess.WRITE_ONLY;
 
 	}
 
+	/**
+	 * Overwrites the default implementation to return a fixed value `'storageTexture'`.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {string} The input type.
+	 */
 	getInputType( /*builder*/ ) {
 
 		return 'storageTexture';
@@ -35,8 +106,16 @@ class StorageTextureNode extends TextureNode {
 		const properties = builder.getNodeProperties( this );
 		properties.storeNode = this.storeNode;
 
+		return properties;
+
 	}
 
+	/**
+	 * Defines the node access.
+	 *
+	 * @param {string} value - The node access.
+	 * @return {StorageTextureNode} A reference to this node.
+	 */
 	setAccess( value ) {
 
 		this.access = value;
@@ -44,6 +123,27 @@ class StorageTextureNode extends TextureNode {
 
 	}
 
+	/**
+	 * Sets the mip level to write to.
+	 *
+	 * @param {number} level - The mip level.
+	 * @return {StorageTextureNode} A reference to this node.
+	 */
+	setMipLevel( level ) {
+
+		this.mipLevel = level;
+		return this;
+
+	}
+
+	/**
+	 * Generates the code snippet of the storage node. If no `storeNode`
+	 * is defined, the texture node is generated as normal texture.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @param {string} output - The current output.
+	 * @return {string} The generated code snippet.
+	 */
 	generate( builder, output ) {
 
 		let snippet;
@@ -62,45 +162,138 @@ class StorageTextureNode extends TextureNode {
 
 	}
 
+	/**
+	 * Generates the snippet for the storage texture.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @param {string} textureProperty - The texture property.
+	 * @param {string} uvSnippet - The uv snippet.
+	 * @param {?string} levelSnippet - The level snippet.
+	 * @param {?string} biasSnippet - The bias snippet.
+	 * @param {?string} depthSnippet - The depth snippet.
+	 * @param {?string} compareSnippet - The compare snippet.
+	 * @param {?Array<string>} gradSnippet - The grad snippet.
+	 * @param {?string} offsetSnippet - The offset snippet.
+	 * @return {string} The generated code snippet.
+	 */
+	generateSnippet( builder, textureProperty, uvSnippet, levelSnippet, biasSnippet, depthSnippet, compareSnippet, gradSnippet, offsetSnippet ) {
+
+		const texture = this.value;
+
+		return builder.generateStorageTextureLoad( texture, textureProperty, uvSnippet, levelSnippet, depthSnippet, offsetSnippet );
+
+	}
+
+	/**
+	 * Convenience method for configuring a read/write node access.
+	 *
+	 * @return {StorageTextureNode} A reference to this node.
+	 */
+	toReadWrite() {
+
+		return this.setAccess( NodeAccess.READ_WRITE );
+
+	}
+
+	/**
+	 * Convenience method for configuring a read-only node access.
+	 *
+	 * @return {StorageTextureNode} A reference to this node.
+	 */
 	toReadOnly() {
 
-		return this.setAccess( GPUStorageTextureAccess.ReadOnly );
+		return this.setAccess( NodeAccess.READ_ONLY );
 
 	}
 
+	/**
+	 * Convenience method for configuring a write-only node access.
+	 *
+	 * @return {StorageTextureNode} A reference to this node.
+	 */
 	toWriteOnly() {
 
-		return this.setAccess( GPUStorageTextureAccess.WriteOnly );
+		return this.setAccess( NodeAccess.WRITE_ONLY );
 
 	}
 
+	/**
+	 * Generates the code snippet of the storage texture node.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 */
 	generateStore( builder ) {
 
 		const properties = builder.getNodeProperties( this );
 
-		const { uvNode, storeNode } = properties;
+		const { uvNode, storeNode, depthNode } = properties;
 
 		const textureProperty = super.generate( builder, 'property' );
-		const uvSnippet = uvNode.build( builder, 'uvec2' );
+		const uvSnippet = uvNode.build( builder, this.value.is3DTexture === true ? 'uvec3' : 'uvec2' );
 		const storeSnippet = storeNode.build( builder, 'vec4' );
+		const depthSnippet = depthNode ? depthNode.build( builder, 'int' ) : null;
 
-		const snippet = builder.generateTextureStore( builder, textureProperty, uvSnippet, storeSnippet );
+		const snippet = builder.generateTextureStore( builder, textureProperty, uvSnippet, depthSnippet, storeSnippet );
 
 		builder.addLineFlowCode( snippet, this );
 
 	}
 
+	clone() {
+
+		const newNode = super.clone();
+		newNode.storeNode = this.storeNode;
+		newNode.mipLevel = this.mipLevel;
+		newNode.access = this.access;
+		return newNode;
+
+	}
+
 }
 
 export default StorageTextureNode;
 
-export const storageTexture = /*@__PURE__*/ nodeProxy( StorageTextureNode );
-
+/**
+ * TSL function for creating a storage texture node.
+ *
+ * @tsl
+ * @function
+ * @param {StorageTexture} value - The storage texture.
+ * @param {?Node<vec2|vec3>} uvNode - The uv node.
+ * @param {?Node} [storeNode=null] - The value node that should be stored in the texture.
+ * @returns {StorageTextureNode}
+ */
+export const storageTexture = /*@__PURE__*/ nodeProxy( StorageTextureNode ).setParameterLength( 1, 3 );
+
+
+/**
+ * TODO: Explain difference to `storageTexture()`.
+ *
+ * @tsl
+ * @function
+ * @param {StorageTexture} value - The storage texture.
+ * @param {Node<vec2|vec3>} uvNode - The uv node.
+ * @param {?Node} [storeNode=null] - The value node that should be stored in the texture.
+ * @returns {StorageTextureNode}
+ */
 export const textureStore = ( value, uvNode, storeNode ) => {
 
-	const node = storageTexture( value, uvNode, storeNode );
+	let node;
+
+	if ( value.isStorageTextureNode === true ) {
+
+		// Derive new storage texture node from existing one
+		node = value.clone();
+		node.uvNode = uvNode;
+		node.storeNode = storeNode;
+
+	} else {
+
+		node = storageTexture( value, uvNode, storeNode );
+
+	}
 
-	if ( storeNode !== null ) node.append();
+	if ( storeNode !== null ) node.toStack();
 
 	return node;