TSL: Use GlobalID in Compute Water, Update IndexNode Comments (#31941)

* init branch, add comments and warnings to various index node related code

* adjust comments

* remove comments

* fix error

* remove invocationGlobalIndex references

* remove comment

* remove extra IndexNode parameter, unify documentation between IndexNode and WGSLNodeBuilder

* unify IndexNode/WGSLNodeBuilder docs

examples/webgpu_compute_water.html

@@ -27,7 +27,7 @@
 		<script type="module">
 
 			import * as THREE from 'three/webgpu';
-			import { instanceIndex, struct, If, uint, int, floor, float, length, clamp, vec2, cos, vec3, vertexIndex, Fn, uniform, instancedArray, min, max, positionLocal, transformNormalToView } from 'three/tsl';
+			import { instanceIndex, struct, If, uint, int, floor, float, length, clamp, vec2, cos, vec3, vertexIndex, Fn, uniform, instancedArray, min, max, positionLocal, transformNormalToView, globalId } from 'three/tsl';
 
 			import { SimplexNoise } from 'three/addons/math/SimplexNoise.js';
 			import { GLTFLoader } from 'three/addons/loaders/GLTFLoader.js';
@@ -228,9 +228,10 @@
 
 					const newHeight = neighborHeight.mul( viscosity );
 
-					// Get 2-D compute coordinate from one-dimensional instanceIndex.
-					const x = float( instanceIndex.mod( WIDTH ) ).mul( 1 / WIDTH );
-					const y = float( instanceIndex.div( WIDTH ) ).mul( 1 / WIDTH );
+					// Get x and y position of the coordinate in the water plane
+
+					const x = float( globalId.x ).mul( 1 / WIDTH );
+					const y = float( globalId.y ).mul( 1 / WIDTH );
 
 					// Mouse influence
 					const centerVec = vec2( 0.5 );
@@ -244,7 +245,7 @@
 					prevHeightStorage.element( instanceIndex ).assign( height );
 					heightStorage.element( instanceIndex ).assign( newHeight );
 
-				} )().compute( WIDTH * WIDTH );
+				} )().compute( WIDTH * WIDTH, [ 16, 16 ] );
 
 				// Water Geometry corresponds with buffered compute grid.
 				const waterGeometry = new THREE.PlaneGeometry( BOUNDS, BOUNDS, WIDTH - 1, WIDTH - 1 );
@@ -330,7 +331,7 @@
 					const linearDamping = float( 0.92 );
 					const bounceDamping = float( - 0.4 );
 
-					// Get 2-D compute coordinate from one-dimensional instanceIndex. The calculation will
+					// Get 2-D compute coordinate from one-dimensional instanceIndex.
 					const instancePosition = duckInstanceDataStorage.element( instanceIndex ).get( 'position' ).toVar();
 					const velocity = duckInstanceDataStorage.element( instanceIndex ).get( 'velocity' ).toVar();
 
@@ -584,7 +585,7 @@
 
 				if ( frame >= 7 - effectController.speed ) {
 
-					renderer.computeAsync( computeHeight );
+					renderer.computeAsync( computeHeight, [ 8, 8, 1 ] );
 
 					if ( effectController.ducksEnabled ) {
 

src/nodes/core/IndexNode.js

@@ -10,7 +10,7 @@ import { nodeImmutable, varying } from '../tsl/TSLBase.js';
  * - `drawIndex`: The index of a draw call.
  * - `invocationLocalIndex`: The index of a compute invocation within the scope of a workgroup load.
  * - `invocationSubgroupIndex`: The index of a compute invocation within the scope of a subgroup.
- * - `subgroupIndex`: The index of the subgroup the current compute invocation belongs to.
+ * - `subgroupIndex`: The index of a compute invocation's subgroup within its workgroup.
  *
  * @augments Node
  */
@@ -25,7 +25,7 @@ class IndexNode extends Node {
 	/**
 	 * Constructs a new index node.
 	 *
-	 * @param {('vertex'|'instance'|'subgroup'|'invocationLocal'|'invocationSubgroup'|'draw')} scope - The scope of the index node.
+	 * @param {('vertex'|'instance'|'subgroup'|'invocationLocal'|'invocationGlobal'|'invocationSubgroup'|'draw')} scope - The scope of the index node.
 	 */
 	constructor( scope ) {
 

src/nodes/core/NodeBuilder.js

@@ -979,7 +979,8 @@ class NodeBuilder {
 	}
 
 	/**
-	 * Returns the instanceIndex input variable as a native shader string.
+	 * Contextually returns either the vertex stage instance index builtin
+	 * or the linearized index of an compute invocation within a grid of workgroups.
 	 *
 	 * @abstract
 	 * @return {string} The instanceIndex shader string.

src/renderers/webgl-fallback/nodes/GLSLNodeBuilder.js

@@ -963,7 +963,8 @@ ${ flowData.code }
 	}
 
 	/**
-	 * Returns the instance index builtin.
+	 * Contextually returns either the vertex stage instance index builtin
+	 * or the linearized index of an compute invocation within a grid of workgroups.
 	 *
 	 * @return {string} The instance index.
 	 */
@@ -974,7 +975,7 @@ ${ flowData.code }
 	}
 
 	/**
-	 * Returns the invocation local index builtin.
+	 * Returns a builtin representing the index of an invocation within its workgroup.
 	 *
 	 * @return {string} The invocation local index.
 	 */
@@ -988,6 +989,33 @@ ${ flowData.code }
 
 	}
 
+	/**
+	 * Returns a builtin representing the size of a subgroup within the current shader.
+	 */
+	getSubgroupSize() {
+
+		error( 'GLSLNodeBuilder: WebGLBackend does not support the subgroupSize node' );
+
+	}
+
+	/**
+	 * Returns a builtin representing the index of an invocation within its subgroup.
+	 */
+	getInvocationSubgroupIndex() {
+
+		error( 'GLSLNodeBuilder: WebGLBackend does not support the invocationSubgroupIndex node' );
+
+	}
+
+	/**
+	 * Returns a builtin representing the index of the current invocation's subgroup within its workgroup.
+	 */
+	getSubgroupIndex() {
+
+		error( 'GLSLNodeBuilder: WebGLBackend does not support the subgroupIndex node' );
+
+	}
+
 	/**
 	 * Returns the draw index builtin.
 	 *

src/renderers/webgpu/nodes/WGSLNodeBuilder.js

@@ -1115,7 +1115,8 @@ ${ flowData.code }
 	}
 
 	/**
-	 * Returns the instance index builtin.
+	 * Contextually returns either the vertex stage instance index builtin
+	 * or the linearized index of an compute invocation within a grid of workgroups.
 	 *
 	 * @return {string} The instance index.
 	 */
@@ -1131,8 +1132,9 @@ ${ flowData.code }
 
 	}
 
+
 	/**
-	 * Returns the invocation local index builtin.
+	 * Returns a builtin representing the index of a compute invocation within the scope of a workgroup load.
 	 *
 	 * @return {string} The invocation local index.
 	 */
@@ -1143,7 +1145,7 @@ ${ flowData.code }
 	}
 
 	/**
-	 * Returns the subgroup size builtin.
+	 * Returns a builtin representing the size of a subgroup within the current shader.
 	 *
 	 * @return {string} The subgroup size.
 	 */
@@ -1156,7 +1158,7 @@ ${ flowData.code }
 	}
 
 	/**
-	 * Returns the invocation subgroup index builtin.
+	 * Returns a builtin representing the index of a compute invocation within the scope of a subgroup.
 	 *
 	 * @return {string} The invocation subgroup index.
 	 */
@@ -1169,7 +1171,7 @@ ${ flowData.code }
 	}
 
 	/**
-	 * Returns the subgroup index builtin.
+	 * Returns a builtin representing the index of a compute invocation's subgroup within its workgroup.
 	 *
 	 * @return {string} The subgroup index.
 	 */