Nodes - Document AtomicFunctionNode and BarrierNode (#30153)

* init branch

* complete first draft

* remove TODO

* Update AtomicFunctionNode.js

* Update BarrierNode.js

---------

Co-authored-by: Michael Herzog <michael.herzog@human-interactive.org>

src/nodes/gpgpu/AtomicFunctionNode.js

@@ -4,7 +4,11 @@ import { nodeProxy } from '../tsl/TSLCore.js';
 /** @module AtomicFunctionNode **/
 
 /**
- * TODO
+ * `AtomicFunctionNode` represents any function that can operate on atomic variable types
+ * within a shader. In an atomic function, any modifiation to an atomic variable will
+ * occur as an indivisble step with a defined order relative to other modifications.
+ * Accordingly, even if multiple atomic functions are modifying an atomic variable at once
+ * atomic operations will not interfer with each other.
  *
  * @augments TempNode
  */
@@ -19,38 +23,38 @@ class AtomicFunctionNode extends TempNode {
 	/**
 	 * Constructs a new atomic function node.
 	 *
-	 * @param {String} method - TODO.
-	 * @param {Node} pointerNode - TODO.
-	 * @param {Node} valueNode - TODO.
-	 * @param {Node?} [storeNode=null] - TODO.
+	 * @param {String} method - The signature of the atomic function to construct.
+	 * @param {Node} pointerNode - An atomic variable or element of an atomic buffer.
+	 * @param {Node} valueNode - The value that mutates the atomic variable.
+	 * @param {Node?} [storeNode=null] - A variable storing the return value of an atomic operation, typically the value of the atomic variable before the operation.
 	 */
 	constructor( method, pointerNode, valueNode, storeNode = null ) {
 
 		super( 'uint' );
 
 		/**
-		 * TODO
+		 * The signature of the atomic function to construct.
 		 *
 		 * @type {String}
 		 */
 		this.method = method;
 
 		/**
-		 * TODO
+		 * An atomic variable or element of an atomic buffer.
 		 *
 		 * @type {Node}
 		 */
 		this.pointerNode = pointerNode;
 
 		/**
-		 * TODO
+		 * A value that modifies the atomic variable.
 		 *
 		 * @type {Node}
 		 */
 		this.valueNode = valueNode;
 
 		/**
-		 * TODO
+		 * A variable storing the return value of an atomic operation, typically the value of the atomic variable before the operation.
 		 *
 		 * @type {Node?}
 		 * @default null
@@ -133,22 +137,22 @@ export default AtomicFunctionNode;
  * TSL function for creating an atomic function node.
  *
  * @function
- * @param {String} method - TODO.
- * @param {Node} pointerNode - TODO.
- * @param {Node} valueNode - TODO.
- * @param {Node?} [storeNode=null] - TODO.
+ * @param {String} method - The signature of the atomic function to construct.
+ * @param {Node} pointerNode - An atomic variable or element of an atomic buffer.
+ * @param {Node} valueNode - The value that mutates the atomic variable.
+ * @param {Node?} [storeNode=null] - A variable storing the return value of an atomic operation, typically the value of the atomic variable before the operation.
  * @returns {AtomicFunctionNode}
  */
 const atomicNode = nodeProxy( AtomicFunctionNode );
 
 /**
- * TODO
+ * TSL function for appending an atomic function call into the programmatic flow of a compute shader.
  *
  * @function
- * @param {String} method - TODO.
- * @param {Node} pointerNode - TODO.
- * @param {Node} valueNode - TODO.
- * @param {Node?} [storeNode=null] - TODO.
+ * @param {String} method - The signature of the atomic function to construct.
+ * @param {Node} pointerNode - An atomic variable or element of an atomic buffer.
+ * @param {Node} valueNode - The value that mutates the atomic variable.
+ * @param {Node?} [storeNode=null] - A variable storing the return value of an atomic operation, typically the value of the atomic variable before the operation.
  * @returns {AtomicFunctionNode}
  */
 export const atomicFunc = ( method, pointerNode, valueNode, storeNode = null ) => {
@@ -161,89 +165,89 @@ export const atomicFunc = ( method, pointerNode, valueNode, storeNode = null ) =
 };
 
 /**
- * TODO
+ * Stores a value in the atomic variable.
  *
  * @function
- * @param {Node} pointerNode - TODO.
- * @param {Node} valueNode - TODO.
- * @param {Node?} [storeNode=null] - TODO.
+ * @param {Node} pointerNode - An atomic variable or element of an atomic buffer.
+ * @param {Node} valueNode - The value that mutates the atomic variable.
+ * @param {Node?} [storeNode=null] - A variable storing the return value of an atomic operation, typically the value of the atomic variable before the operation.
  * @returns {AtomicFunctionNode}
  */
 export const atomicStore = ( pointerNode, valueNode, storeNode = null ) => atomicFunc( AtomicFunctionNode.ATOMIC_STORE, pointerNode, valueNode, storeNode );
 
 /**
- * TODO
+ * Increments the value stored in the atomic variable.
  *
  * @function
- * @param {Node} pointerNode - TODO.
- * @param {Node} valueNode - TODO.
- * @param {Node?} [storeNode=null] - TODO.
+ * @param {Node} pointerNode - An atomic variable or element of an atomic buffer.
+ * @param {Node} valueNode - The value that mutates the atomic variable.
+ * @param {Node?} [storeNode=null] - A variable storing the return value of an atomic operation, typically the value of the atomic variable before the operation.
  * @returns {AtomicFunctionNode}
  */
 export const atomicAdd = ( pointerNode, valueNode, storeNode = null ) => atomicFunc( AtomicFunctionNode.ATOMIC_ADD, pointerNode, valueNode, storeNode );
 
 /**
- * TODO
+ * Decrements the value stored in the atomic variable.
  *
  * @function
- * @param {Node} pointerNode - TODO.
- * @param {Node} valueNode - TODO.
- * @param {Node?} [storeNode=null] - TODO.
+ * @param {Node} pointerNode - An atomic variable or element of an atomic buffer.
+ * @param {Node} valueNode - The value that mutates the atomic variable.
+ * @param {Node?} [storeNode=null] - A variable storing the return value of an atomic operation, typically the value of the atomic variable before the operation.
  * @returns {AtomicFunctionNode}
  */
 export const atomicSub = ( pointerNode, valueNode, storeNode = null ) => atomicFunc( AtomicFunctionNode.ATOMIC_SUB, pointerNode, valueNode, storeNode );
 
 /**
- * TODO
+ * Stores in an atomic variable the maximum between its current value and a parameter.
  *
  * @function
- * @param {Node} pointerNode - TODO.
- * @param {Node} valueNode - TODO.
- * @param {Node?} [storeNode=null] - TODO.
+ * @param {Node} pointerNode - An atomic variable or element of an atomic buffer.
+ * @param {Node} valueNode - The value that mutates the atomic variable.
+ * @param {Node?} [storeNode=null] - A variable storing the return value of an atomic operation, typically the value of the atomic variable before the operation.
  * @returns {AtomicFunctionNode}
  */
 export const atomicMax = ( pointerNode, valueNode, storeNode = null ) => atomicFunc( AtomicFunctionNode.ATOMIC_MAX, pointerNode, valueNode, storeNode );
 
 /**
- * TODO
+ * Stores in an atomic variable the minimum between its current value and a parameter.
  *
  * @function
- * @param {Node} pointerNode - TODO.
- * @param {Node} valueNode - TODO.
- * @param {Node?} [storeNode=null] - TODO.
+ * @param {Node} pointerNode - An atomic variable or element of an atomic buffer.
+ * @param {Node} valueNode - The value that mutates the atomic variable.
+ * @param {Node?} [storeNode=null] - A variable storing the return value of an atomic operation, typically the value of the atomic variable before the operation.
  * @returns {AtomicFunctionNode}
  */
 export const atomicMin = ( pointerNode, valueNode, storeNode = null ) => atomicFunc( AtomicFunctionNode.ATOMIC_MIN, pointerNode, valueNode, storeNode );
 
 /**
- * TODO
+ * Stores in an atomic variable the bitwise AND of its value with a parameter.
  *
  * @function
- * @param {Node} pointerNode - TODO.
- * @param {Node} valueNode - TODO.
- * @param {Node?} [storeNode=null] - TODO.
+ * @param {Node} pointerNode - An atomic variable or element of an atomic buffer.
+ * @param {Node} valueNode - The value that mutates the atomic variable.
+ * @param {Node?} [storeNode=null] - A variable storing the return value of an atomic operation, typically the value of the atomic variable before the operation.
  * @returns {AtomicFunctionNode}
  */
 export const atomicAnd = ( pointerNode, valueNode, storeNode = null ) => atomicFunc( AtomicFunctionNode.ATOMIC_AND, pointerNode, valueNode, storeNode );
 
 /**
- * TODO
+ * Stores in an atomic variable the bitwise OR of its value with a parameter.
  *
  * @function
- * @param {Node} pointerNode - TODO.
- * @param {Node} valueNode - TODO.
- * @param {Node?} [storeNode=null] - TODO.
+ * @param {Node} pointerNode - An atomic variable or element of an atomic buffer.
+ * @param {Node} valueNode - The value that mutates the atomic variable.
+ * @param {Node?} [storeNode=null] - A variable storing the return value of an atomic operation, typically the value of the atomic variable before the operation.
  * @returns {AtomicFunctionNode}
  */
 export const atomicOr = ( pointerNode, valueNode, storeNode = null ) => atomicFunc( AtomicFunctionNode.ATOMIC_OR, pointerNode, valueNode, storeNode );
 
 /**
- * TODO
+ * Stores in an atomic variable the bitwise XOR of its value with a parameter.
  *
  * @function
- * @param {Node} pointerNode - TODO.
- * @param {Node} valueNode - TODO.
- * @param {Node?} [storeNode=null] - TODO.
+ * @param {Node} pointerNode - An atomic variable or element of an atomic buffer.
+ * @param {Node} valueNode - The value that mutates the atomic variable.
+ * @param {Node?} [storeNode=null] - A variable storing the return value of an atomic operation, typically the value of the atomic variable before the operation.
  * @returns {AtomicFunctionNode}
  */
 export const atomicXor = ( pointerNode, valueNode, storeNode = null ) => atomicFunc( AtomicFunctionNode.ATOMIC_XOR, pointerNode, valueNode, storeNode );

src/nodes/gpgpu/BarrierNode.js

@@ -4,7 +4,7 @@ import { nodeProxy } from '../tsl/TSLCore.js';
 /** @module BarrierNode **/
 
 /**
- * TODO
+ * Represents a GPU control barrier that synchronizes compute operations within a given scope.
  *
  * @augments Node
  */
@@ -54,7 +54,9 @@ export default BarrierNode;
 const barrier = nodeProxy( BarrierNode );
 
 /**
- * TSL function for creating a workgroup barrier.
+ * TSL function for creating a workgroup barrier. All compute shader
+ * invocations must wait for each invocation within a workgroup to
+ * complete before the barrier can be surpassed.
  *
  * @function
  * @returns {BarrierNode}
@@ -62,7 +64,9 @@ const barrier = nodeProxy( BarrierNode );
 export const workgroupBarrier = () => barrier( 'workgroup' ).append();
 
 /**
- * TSL function for creating a storage barrier.
+ * TSL function for creating a storage barrier. All invocations must
+ * wait for each access to variables within the 'storage' address space
+ * to complete before the barrier can be passed.
  *
  * @function
  * @returns {BarrierNode}
@@ -70,7 +74,9 @@ export const workgroupBarrier = () => barrier( 'workgroup' ).append();
 export const storageBarrier = () => barrier( 'storage' ).append();
 
 /**
- * TSL function for creating a texture barrier.
+ * TSL function for creating a texture barrier. All invocations must
+ * wait for each access to variables within the 'texture' address space
+ * to complete before the barrier can be passed.
  *
  * @function
  * @returns {BarrierNode}