TSL: Add `Stack()` and `.toStack()` (#30956)

* add `Stack()`

* rev

* rev

examples/jsm/tsl/lighting/TiledLightsNode.js

@@ -234,8 +234,8 @@ class TiledLightsNode extends LightsNode {
 		const lightingModel = builder.context.reflectedLight;
 
 		// force declaration order, before of the loop
-		lightingModel.directDiffuse.append();
-		lightingModel.directSpecular.append();
+		lightingModel.directDiffuse.toStack();
+		lightingModel.directSpecular.toStack();
 
 		super.setupLights( builder, lightNodes );
 
@@ -262,7 +262,7 @@ class TiledLightsNode extends LightsNode {
 
 			} );
 
-		} )().append();
+		}, 'void' )();
 
 	}
 

src/materials/nodes/NodeMaterial.js

@@ -632,7 +632,7 @@ class NodeMaterial extends Material {
 
 		if ( depthNode !== null ) {
 
-			depth.assign( depthNode ).append();
+			depth.assign( depthNode ).toStack();
 
 		}
 
@@ -693,13 +693,13 @@ class NodeMaterial extends Material {
 
 		if ( geometry.morphAttributes.position || geometry.morphAttributes.normal || geometry.morphAttributes.color ) {
 
-			morphReference( object ).append();
+			morphReference( object ).toStack();
 
 		}
 
 		if ( object.isSkinnedMesh === true ) {
 
-			skinning( object ).append();
+			skinning( object ).toStack();
 
 		}
 
@@ -715,13 +715,13 @@ class NodeMaterial extends Material {
 
 		if ( object.isBatchedMesh ) {
 
-			batch( object ).append();
+			batch( object ).toStack();
 
 		}
 
 		if ( ( object.isInstancedMesh && object.instanceMatrix && object.instanceMatrix.isInstancedBufferAttribute === true ) ) {
 
-			instancedMesh( object ).append();
+			instancedMesh( object ).toStack();
 
 		}
 

src/nodes/accessors/StorageTextureNode.js

@@ -224,7 +224,7 @@ export const textureStore = ( value, uvNode, storeNode ) => {
 
 	const node = storageTexture( value, uvNode, storeNode );
 
-	if ( storeNode !== null ) node.append();
+	if ( storeNode !== null ) node.toStack();
 
 	return node;
 

src/nodes/core/VarNode.js

@@ -167,7 +167,7 @@ const createVar = /*@__PURE__*/ nodeProxy( VarNode );
  * @param {?string} name - The name of the variable in the shader.
  * @returns {VarNode}
  */
-export const Var = ( node, name = null ) => createVar( node, name ).append();
+export const Var = ( node, name = null ) => createVar( node, name ).toStack();
 
 /**
  * TSL function for creating a const node.
@@ -178,7 +178,7 @@ export const Var = ( node, name = null ) => createVar( node, name ).append();
  * @param {?string} name - The name of the constant in the shader.
  * @returns {VarNode}
  */
-export const Const = ( node, name = null ) => createVar( node, name, true ).append();
+export const Const = ( node, name = null ) => createVar( node, name, true ).toStack();
 
 // Method chaining
 

src/nodes/gpgpu/AtomicFunctionNode.js

@@ -150,10 +150,7 @@ const atomicNode = nodeProxy( AtomicFunctionNode );
  */
 export const atomicFunc = ( method, pointerNode, valueNode ) => {
 
-	const node = atomicNode( method, pointerNode, valueNode );
-	node.append();
-
-	return node;
+	return atomicNode( method, pointerNode, valueNode ).toStack();
 
 };
 

src/nodes/gpgpu/BarrierNode.js

@@ -63,7 +63,7 @@ const barrier = nodeProxy( BarrierNode );
  * @function
  * @returns {BarrierNode}
  */
-export const workgroupBarrier = () => barrier( 'workgroup' ).append();
+export const workgroupBarrier = () => barrier( 'workgroup' ).toStack();
 
 /**
  * TSL function for creating a storage barrier. All invocations must
@@ -74,7 +74,7 @@ export const workgroupBarrier = () => barrier( 'workgroup' ).append();
  * @function
  * @returns {BarrierNode}
  */
-export const storageBarrier = () => barrier( 'storage' ).append();
+export const storageBarrier = () => barrier( 'storage' ).toStack();
 
 /**
  * TSL function for creating a texture barrier. All invocations must
@@ -85,5 +85,5 @@ export const storageBarrier = () => barrier( 'storage' ).append();
  * @function
  * @returns {BarrierNode}
  */
-export const textureBarrier = () => barrier( 'texture' ).append();
+export const textureBarrier = () => barrier( 'texture' ).toStack();
 

src/nodes/tsl/TSLCore.js

@@ -304,6 +304,8 @@ class ShaderCallNodeInternal extends Node {
 		this.shaderNode = shaderNode;
 		this.inputNodes = inputNodes;
 
+		this.isShaderCallNodeInternal = true;
+
 	}
 
 	getNodeType( builder ) {
@@ -608,7 +610,11 @@ export const Fn = ( jsFunc, layout = null ) => {
 
 		}
 
-		return shaderNode.call( inputs );
+		const fnCall = shaderNode.call( inputs );
+
+		if ( nodeType === 'void' ) fnCall.toStack();
+
+		return fnCall;
 
 	};
 
@@ -663,21 +669,6 @@ export const Fn = ( jsFunc, layout = null ) => {
 
 };
 
-/**
- * @tsl
- * @function
- * @deprecated since r168. Use {@link Fn} instead.
- *
- * @param {...any} params
- * @returns {Function}
- */
-export const tslFn = ( ...params ) => { // @deprecated, r168
-
-	console.warn( 'THREE.TSL: tslFn() has been renamed to Fn().' );
-	return Fn( ...params );
-
-};
-
 //
 
 addMethodChaining( 'toGlobal', ( node ) => {
@@ -704,10 +695,44 @@ export const setCurrentStack = ( stack ) => {
 
 export const getCurrentStack = () => currentStack;
 
+/**
+ * Represent a conditional node using if/else statements.
+ *
+ * ```js
+ * If( condition, function )
+ * 	.ElseIf( condition, function )
+ * 	.Else( function )
+ * ```
+ * @tsl
+ * @function
+ * @param {...any} params - The parameters for the conditional node.
+ * @returns {StackNode} The conditional node.
+ */
 export const If = ( ...params ) => currentStack.If( ...params );
+
+/**
+ * Represent a conditional node using switch/case statements.
+ *
+ * ```js
+ * Switch( value )
+ * 	.Case( 1, function )
+ * 	.Case( 2, 3, 4, function )
+ * 	.Default( function )
+ * ```
+ * @tsl
+ * @function
+ * @param {...any} params - The parameters for the conditional node.
+ * @returns {StackNode} The conditional node.
+ */
 export const Switch = ( ...params ) => currentStack.Switch( ...params );
 
-export function append( node ) {
+/**
+ * Add the given node to the current stack.
+ *
+ * @param {Node} node - The node to add.
+ * @returns {Node} The node that was added to the stack.
+ */
+export function Stack( node ) {
 
 	if ( currentStack ) currentStack.add( node );
 
@@ -715,7 +740,7 @@ export function append( node ) {
 
 }
 
-addMethodChaining( 'append', append );
+addMethodChaining( 'toStack', Stack );
 
 // types
 
@@ -777,3 +802,42 @@ export const split = ( node, channels ) => nodeObject( new SplitNode( nodeObject
 
 addMethodChaining( 'element', element );
 addMethodChaining( 'convert', convert );
+
+// deprecated
+
+/**
+ * @tsl
+ * @function
+ * @deprecated since r176. Use {@link Stack} instead.
+ *
+ * @param {Node} node - The node to add.
+ * @returns {Function}
+ */
+export const append = ( node ) => { // @deprecated, r176
+
+	console.warn( 'THREE.TSL: append() has been renamed to Stack().' );
+	return Stack( node );
+
+};
+
+addMethodChaining( 'append', ( node ) => { // @deprecated, r176
+
+	console.warn( 'THREE.TSL: .append() has been renamed to .toStack().' );
+	return Stack( node );
+
+} );
+
+/**
+ * @tsl
+ * @function
+ * @deprecated since r168. Use {@link Fn} instead.
+ *
+ * @param {...any} params
+ * @returns {Function}
+ */
+export const tslFn = ( ...params ) => { // @deprecated, r168
+
+	console.warn( 'THREE.TSL: tslFn() has been renamed to Fn().' );
+	return Fn( ...params );
+
+};

src/nodes/utils/Discard.js

@@ -10,7 +10,7 @@ import { addMethodChaining } from '../tsl/TSLCore.js';
  * @param {?ConditionalNode} conditional - An optional conditional node. It allows to decide whether the discard should be executed or not.
  * @return {Node} The `discard` expression.
  */
-export const Discard = ( conditional ) => ( conditional ? select( conditional, expression( 'discard' ) ) : expression( 'discard' ) ).append();
+export const Discard = ( conditional ) => ( conditional ? select( conditional, expression( 'discard' ) ) : expression( 'discard' ) ).toStack();
 
 /**
  * Represents a `return` shader operation in TSL.
@@ -19,6 +19,6 @@ export const Discard = ( conditional ) => ( conditional ? select( conditional, e
  * @function
  * @return {ExpressionNode} The `return` expression.
  */
-export const Return = () => expression( 'return' ).append();
+export const Return = () => expression( 'return' ).toStack();
 
 addMethodChaining( 'discard', Discard );

src/nodes/utils/LoopNode.js

@@ -332,7 +332,7 @@ export default LoopNode;
  * @param {...any} params - A list of parameters.
  * @returns {LoopNode}
  */
-export const Loop = ( ...params ) => nodeObject( new LoopNode( nodeArray( params, 'int' ) ) ).append();
+export const Loop = ( ...params ) => nodeObject( new LoopNode( nodeArray( params, 'int' ) ) ).toStack();
 
 /**
  * TSL function for creating a `Continue()` expression.
@@ -341,7 +341,7 @@ export const Loop = ( ...params ) => nodeObject( new LoopNode( nodeArray( params
  * @function
  * @returns {ExpressionNode}
  */
-export const Continue = () => expression( 'continue' ).append();
+export const Continue = () => expression( 'continue' ).toStack();
 
 /**
  * TSL function for creating a `Break()` expression.
@@ -350,7 +350,7 @@ export const Continue = () => expression( 'continue' ).append();
  * @function
  * @returns {ExpressionNode}
  */
-export const Break = () => expression( 'break' ).append();
+export const Break = () => expression( 'break' ).toStack();
 
 // Deprecated