super-three 0.172.0 → 0.173.1

package/src/nodes/core/StructTypeNode.js

@@ -1,10 +1,40 @@
+
 import Node from './Node.js';
+import { getLengthFromType } from './NodeUtils.js';
+
+/** @module StructTypeNode **/
 
 /**
- * {@link NodeBuilder} is going to create instances of this class during the build process
- * of nodes. They represent the final shader struct data that are going to be generated
- * by the builder. A dictionary of struct types is maintained in {@link NodeBuilder#structs}
- * for this purpose.
+ * Generates a layout for struct members.
+ * This function takes an object representing struct members and returns an array of member layouts.
+ * Each member layout includes the member's name, type, and whether it is atomic.
+ *
+ * @param {Object.<string, string|Object>} members - An object where keys are member names and values are either types (as strings) or objects with type and atomic properties.
+ * @returns {Array.<{name: string, type: string, atomic: boolean}>} An array of member layouts.
+ */
+function getMembersLayout( members ) {
+
+	return Object.entries( members ).map( ( [ name, value ] ) => {
+
+		if ( typeof value === 'string' ) {
+
+			return { name, type: value, atomic: false };
+
+		}
+
+		return { name, type: value.type, atomic: value.atomic || false };
+
+	} );
+
+}
+
+/**
+ * Represents a struct type node in the node-based system.
+ * This class is used to define and manage the layout and types of struct members.
+ * It extends the base Node class and provides methods to get the length of the struct,
+ * retrieve member types, and generate the struct type for a builder.
+ *
+ * @augments Node
  */
 class StructTypeNode extends Node {
 
@@ -15,29 +45,29 @@ class StructTypeNode extends Node {
 	}
 
 	/**
-	 * Constructs a new struct type node.
+	 * Creates an instance of StructTypeNode.
 	 *
-	 * @param {String} name - The name of the struct.
-	 * @param {Array<String>} types - An array of types.
+	 * @param {Object} membersLayout - The layout of the members for the struct.
+	 * @param {string} [name=null] - The optional name of the struct.
 	 */
-	constructor( name, types ) {
+	constructor( membersLayout, name = null ) {
 
-		super();
+		super( 'struct' );
 
 		/**
-		 * The name of the struct.
+		 * The layout of the members for the struct
 		 *
-		 * @type {String}
+		 * @type {Array.<{name: string, type: string, atomic: boolean}>}
 		 */
-		this.name = name;
-
+		this.membersLayout = getMembersLayout( membersLayout );
 
 		/**
-		 * An array of types.
+		 * The name of the struct.
 		 *
-		 * @type {Array<String>}
+		 * @type {String}
+		 * @default null
 		 */
-		this.types = types;
+		this.name = name;
 
 		/**
 		 * This flag can be used for type testing.
@@ -46,18 +76,49 @@ class StructTypeNode extends Node {
 		 * @readonly
 		 * @default true
 		 */
-		this.isStructTypeNode = true;
+		this.isStructLayoutNode = true;
 
 	}
 
 	/**
-	 * Returns the member types.
+	 * Returns the length of the struct.
+	 * The length is calculated by summing the lengths of the struct's members.
 	 *
-	 * @return {Array<String>} The types.
+	 * @returns {Number} The length of the struct.
 	 */
-	getMemberTypes() {
+	getLength() {
+
+		let length = 0;
+
+		for ( const member of this.membersLayout ) {
+
+			length += getLengthFromType( member.type );
+
+		}
+
+		return length;
+
+	}
+
+	getMemberType( builder, name ) {
+
+		const member = this.membersLayout.find( m => m.name === name );
+
+		return member ? member.type : 'void';
+
+	}
+
+	getNodeType( builder ) {
+
+		const structType = builder.getStructTypeFromNode( this, this.membersLayout, this.name );
+
+		return structType.name;
+
+	}
+
+	generate( builder ) {
 
-		return this.types;
+		return this.getNodeType( builder );
 
 	}
 

package/src/nodes/core/TempNode.js

@@ -68,7 +68,7 @@ class TempNode extends Node {
 				const nodeVar = builder.getVarFromNode( this, null, type );
 				const propertyName = builder.getPropertyName( nodeVar );
 
-				builder.addLineFlowCode( `${propertyName} = ${snippet}`, this );
+				builder.addLineFlowCode( `${ propertyName } = ${ snippet }`, this );
 
 				nodeData.snippet = snippet;
 				nodeData.propertyName = propertyName;

package/src/nodes/core/VarNode.js

@@ -26,8 +26,9 @@ class VarNode extends Node {
 	 *
 	 * @param {Node} node - The node for which a variable should be created.
 	 * @param {String?} name - The name of the variable in the shader.
+	 * @param {Boolean?} readOnly - The read-only flag.
 	 */
-	constructor( node, name = null ) {
+	constructor( node, name = null, readOnly = false ) {
 
 		super();
 
@@ -64,6 +65,15 @@ class VarNode extends Node {
 		 */
 		this.isVarNode = true;
 
+		/**
+		 *
+		 * The read-only flag.
+		 *
+		 * @type {Boolean}
+		 * @default false
+		 */
+		this.readOnly = readOnly;
+
 	}
 
 	getHash( builder ) {
@@ -72,6 +82,18 @@ class VarNode extends Node {
 
 	}
 
+	getMemberType( builder, name ) {
+
+		return this.node.getMemberType( builder, name );
+
+	}
+
+	getElementType( builder ) {
+
+		return this.node.getElementType( builder );
+
+	}
+
 	getNodeType( builder ) {
 
 		return this.node.getNodeType( builder );
@@ -80,15 +102,50 @@ class VarNode extends Node {
 
 	generate( builder ) {
 
-		const { node, name } = this;
+		const { node, name, readOnly } = this;
+		const { renderer } = builder;
+
+		const isWebGPUBackend = renderer.backend.isWebGPUBackend === true;
+
+		let isDeterministic = false;
+		let shouldTreatAsReadOnly = false;
+
+		if ( readOnly ) {
+
+			isDeterministic = builder.isDeterministic( node );
+
+			shouldTreatAsReadOnly = isWebGPUBackend ? readOnly : isDeterministic;
 
-		const nodeVar = builder.getVarFromNode( this, name, builder.getVectorType( this.getNodeType( builder ) ) );
+		}
+
+		const vectorType = builder.getVectorType( this.getNodeType( builder ) );
+		const snippet = node.build( builder, vectorType );
+
+		const nodeVar = builder.getVarFromNode( this, name, vectorType, undefined, shouldTreatAsReadOnly );
 
 		const propertyName = builder.getPropertyName( nodeVar );
 
-		const snippet = node.build( builder, nodeVar.type );
+		let declarationPrefix = propertyName;
+
+		if ( shouldTreatAsReadOnly ) {
+
+			if ( isWebGPUBackend ) {
+
+				declarationPrefix = isDeterministic
+					? `const ${ propertyName }`
+					: `let ${ propertyName }`;
+
+			} else {
 
-		builder.addLineFlowCode( `${propertyName} = ${snippet}`, this );
+				const count = builder.getArrayCount( node );
+
+				declarationPrefix = `const ${ builder.getVar( nodeVar.type, propertyName, count ) }`;
+
+			}
+
+		}
+
+		builder.addLineFlowCode( `${ declarationPrefix } = ${ snippet }`, this );
 
 		return propertyName;
 
@@ -108,13 +165,43 @@ export default VarNode;
  */
 const createVar = /*@__PURE__*/ nodeProxy( VarNode );
 
-addMethodChaining( 'toVar', ( ...params ) => createVar( ...params ).append() );
+/**
+ * TSL function for creating a var node.
+ *
+ * @function
+ * @param {Node} node - The node for which a variable should be created.
+ * @param {String?} name - The name of the variable in the shader.
+ * @returns {VarNode}
+ */
+export const Var = ( node, name = null ) => createVar( node, name ).append();
+
+/**
+ * TSL function for creating a const node.
+ *
+ * @function
+ * @param {Node} node - The node for which a constant should be created.
+ * @param {String?} name - The name of the constant in the shader.
+ * @returns {VarNode}
+ */
+export const Const = ( node, name = null ) => createVar( node, name, true ).append();
+
+// Method chaining
+
+addMethodChaining( 'toVar', Var );
+addMethodChaining( 'toConst', Const );
 
 // Deprecated
 
+/**
+ * @function
+ * @deprecated since r170. Use `Var( node )` or `node.toVar()` instead.
+ *
+ * @param {Any} node
+ * @returns {VarNode}
+ */
 export const temp = ( node ) => { // @deprecated, r170
 
-	console.warn( 'TSL: "temp" is deprecated. Use ".toVar()" instead.' );
+	console.warn( 'TSL: "temp( node )" is deprecated. Use "Var( node )" or "node.toVar()" instead.' );
 
 	return createVar( node );
 

package/src/nodes/core/VaryingNode.js

@@ -9,7 +9,7 @@ import { addMethodChaining, nodeProxy } from '../tsl/TSLCore.js';
  * existing nodes like the following:
  *
  * ```js
- * const positionLocal = positionGeometry.varying( 'vPositionLocal' );
+ * const positionLocal = positionGeometry.toVarying( 'vPositionLocal' );
  * ```
  *
  * @augments Node
@@ -185,5 +185,21 @@ export const varying = /*@__PURE__*/ nodeProxy( VaryingNode );
  */
 export const vertexStage = ( node ) => varying( node );
 
-addMethodChaining( 'varying', varying );
-addMethodChaining( 'vertexStage', vertexStage );
+addMethodChaining( 'toVarying', varying );
+addMethodChaining( 'toVertexStage', vertexStage );
+
+// Deprecated
+
+addMethodChaining( 'varying', ( ...params ) => { // @deprecated, r173
+
+	console.warn( 'TSL.VaryingNode: .varying() has been renamed to .toVarying().' );
+	return varying( ...params );
+
+} );
+
+addMethodChaining( 'vertexStage', ( ...params ) => { // @deprecated, r173
+
+	console.warn( 'TSL.VaryingNode: .vertexStage() has been renamed to .toVertexStage().' );
+	return varying( ...params );
+
+} );

package/src/nodes/display/BlendModes.js

@@ -1,6 +1,20 @@
 import { Fn, vec4 } from '../tsl/TSLBase.js';
 import { mix, min, step } from '../math/MathNode.js';
 
+/** @module BlendModes **/
+
+/**
+ * Represents a "Color Burn" blend mode.
+ *
+ * It's designed to darken the base layer's colors based on the color of the blend layer.
+ * It significantly increases the contrast of the base layer, making the colors more vibrant and saturated.
+ * The darker the color in the blend layer, the stronger the darkening and contrast effect on the base layer.
+ *
+ * @method
+ * @param {Node<vec3>} base - The base color.
+ * @param {Node<vec3>} blend - The blend color. A white (#ffffff) blend color does not alter the base color.
+ * @return {Node<vec3>} The result.
+ */
 export const blendBurn = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
 
 	return min( 1.0, base.oneMinus().div( blend ) ).oneMinus();
@@ -14,6 +28,18 @@ export const blendBurn = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
 	]
 } );
 
+/**
+ * Represents a "Color Dodge" blend mode.
+ *
+ * It's designed to lighten the base layer's colors based on the color of the blend layer.
+ * It significantly increases the brightness of the base layer, making the colors lighter and more vibrant.
+ * The brighter the color in the blend layer, the stronger the lightening and contrast effect on the base layer.
+ *
+ * @method
+ * @param {Node<vec3>} base - The base color.
+ * @param {Node<vec3>} blend - The blend color. A black (#000000) blend color does not alter the base color.
+ * @return {Node<vec3>} The result.
+ */
 export const blendDodge = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
 
 	return min( base.div( blend.oneMinus() ), 1.0 );
@@ -27,6 +53,18 @@ export const blendDodge = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
 	]
 } );
 
+/**
+ * Represents a "Screen" blend mode.
+ *
+ * Similar to `blendDodge()`, this mode also lightens the base layer's colors based on the color of the blend layer.
+ * The "Screen" blend mode is better for general brightening whereas the "Dodge" results in more subtle and nuanced
+ * effects.
+ *
+ * @method
+ * @param {Node<vec3>} base - The base color.
+ * @param {Node<vec3>} blend - The blend color. A black (#000000) blend color does not alter the base color.
+ * @return {Node<vec3>} The result.
+ */
 export const blendScreen = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
 
 	return base.oneMinus().mul( blend.oneMinus() ).oneMinus();
@@ -40,6 +78,18 @@ export const blendScreen = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
 	]
 } );
 
+/**
+ * Represents a "Overlay" blend mode.
+ *
+ * It's designed to increase the contrast of the base layer based on the color of the blend layer.
+ * It amplifies the existing colors and contrast in the base layer, making lighter areas lighter and darker areas darker.
+ * The color of the blend layer significantly influences the resulting contrast and color shift in the base layer.
+ *
+ * @method
+ * @param {Node<vec3>} base - The base color.
+ * @param {Node<vec3>} blend - The blend color
+ * @return {Node<vec3>} The result.
+ */
 export const blendOverlay = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
 
 	return mix( base.mul( 2.0 ).mul( blend ), base.oneMinus().mul( 2.0 ).mul( blend.oneMinus() ).oneMinus(), step( 0.5, base ) );
@@ -53,6 +103,15 @@ export const blendOverlay = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
 	]
 } );
 
+/**
+ * This function blends two color based on their alpha values by replicating the behavior of `THREE.NormalBlending`.
+ * It assumes both input colors have non-preumiltiplied alpha.
+ *
+ * @method
+ * @param {Node<vec4>} base - The base color.
+ * @param {Node<vec4>} blend - The blend color
+ * @return {Node<vec4>} The result.
+ */
 export const blendColor = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
 
 	const outAlpha = blend.a.add( base.a.mul( blend.a.oneMinus() ) );
@@ -68,8 +127,15 @@ export const blendColor = /*@__PURE__*/ Fn( ( [ base, blend ] ) => {
 	]
 } );
 
-// deprecated
+// Deprecated
 
+/**
+ * @function
+ * @deprecated since r171. Use {@link blendBurn} instead.
+ *
+ * @param  {...any} params
+ * @returns {Function}
+ */
 export const burn = ( ...params ) => { // @deprecated, r171
 
 	console.warn( 'THREE.TSL: "burn" has been renamed. Use "blendBurn" instead.' );
@@ -77,6 +143,13 @@ export const burn = ( ...params ) => { // @deprecated, r171
 
 };
 
+/**
+ * @function
+ * @deprecated since r171. Use {@link blendDodge} instead.
+ *
+ * @param  {...any} params
+ * @returns {Function}
+ */
 export const dodge = ( ...params ) => { // @deprecated, r171
 
 	console.warn( 'THREE.TSL: "dodge" has been renamed. Use "blendDodge" instead.' );
@@ -84,6 +157,13 @@ export const dodge = ( ...params ) => { // @deprecated, r171
 
 };
 
+/**
+ * @method
+ * @deprecated since r171. Use {@link blendScreen} instead.
+ *
+ * @param  {...any} params
+ * @returns {Function}
+ */
 export const screen = ( ...params ) => { // @deprecated, r171
 
 	console.warn( 'THREE.TSL: "screen" has been renamed. Use "blendScreen" instead.' );
@@ -91,6 +171,13 @@ export const screen = ( ...params ) => { // @deprecated, r171
 
 };
 
+/**
+ * @method
+ * @deprecated since r171. Use {@link blendOverlay} instead.
+ *
+ * @param  {...any} params
+ * @returns {Function}
+ */
 export const overlay = ( ...params ) => { // @deprecated, r171
 
 	console.warn( 'THREE.TSL: "overlay" has been renamed. Use "blendOverlay" instead.' );

package/src/nodes/display/BumpMapNode.js

@@ -66,8 +66,8 @@ class BumpMapNode extends TempNode {
 	/**
 	 * Constructs a new bump map node.
 	 *
-	 * @param {Node} textureNode - Represents the bump map data.
-	 * @param {Node?} [scaleNode=null] - Controls the intensity of the bump effect.
+	 * @param {Node<float>} textureNode - Represents the bump map data.
+	 * @param {Node<float>?} [scaleNode=null] - Controls the intensity of the bump effect.
 	 */
 	constructor( textureNode, scaleNode = null ) {
 
@@ -76,14 +76,14 @@ class BumpMapNode extends TempNode {
 		/**
 		 * Represents the bump map data.
 		 *
-		 * @type {Node}
+		 * @type {Node<float>}
 		 */
 		this.textureNode = textureNode;
 
 		/**
 		 * Controls the intensity of the bump effect.
 		 *
-		 * @type {Node?}
+		 * @type {Node<float>?}
 		 * @default null
 		 */
 		this.scaleNode = scaleNode;
@@ -111,8 +111,8 @@ export default BumpMapNode;
  * TSL function for creating a bump map node.
  *
  * @function
- * @param {Node} textureNode - Represents the bump map data.
- * @param {Node?} [scaleNode=null] - Controls the intensity of the bump effect.
+ * @param {Node<float>} textureNode - Represents the bump map data.
+ * @param {Node<float>?} [scaleNode=null] - Controls the intensity of the bump effect.
  * @returns {BumpMapNode}
  */
 export const bumpMap = /*@__PURE__*/ nodeProxy( BumpMapNode );

package/src/nodes/display/NormalMapNode.js

@@ -59,8 +59,8 @@ class NormalMapNode extends TempNode {
 	/**
 	 * Constructs a new normal map node.
 	 *
-	 * @param {Node} node - Represents the normal map data.
-	 * @param {Node?} [scaleNode=null] - Controls the intensity of the effect.
+	 * @param {Node<vec3>} node - Represents the normal map data.
+	 * @param {Node<vec2>?} [scaleNode=null] - Controls the intensity of the effect.
 	 */
 	constructor( node, scaleNode = null ) {
 
@@ -69,14 +69,14 @@ class NormalMapNode extends TempNode {
 		/**
 		 * Represents the normal map data.
 		 *
-		 * @type {Node}
+		 * @type {Node<vec3>}
 		 */
 		this.node = node;
 
 		/**
 		 * Controls the intensity of the effect.
 		 *
-		 * @type {Node?}
+		 * @type {Node<vec2>?}
 		 * @default null
 		 */
 		this.scaleNode = scaleNode;
@@ -142,8 +142,8 @@ export default NormalMapNode;
  * TSL function for creating a normal map node.
  *
  * @function
- * @param {Node} node - Represents the normal map data.
- * @param {Node?} [scaleNode=null] - Controls the intensity of the effect.
+ * @param {Node<vec3>} node - Represents the normal map data.
+ * @param {Node<vec2>?} [scaleNode=null] - Controls the intensity of the effect.
  * @returns {NormalMapNode}
  */
 export const normalMap = /*@__PURE__*/ nodeProxy( NormalMapNode );

package/src/nodes/display/PassNode.js

@@ -546,13 +546,15 @@ class PassNode extends TempNode {
 
 		this.renderTarget.samples = this.options.samples === undefined ? renderer.samples : this.options.samples;
 
-		// Disable MSAA for WebGL backend for now
+		// TODO: Disable MSAA for WebGL backend for now
 		if ( renderer.backend.isWebGLBackend === true ) {
 
 			this.renderTarget.samples = 0;
 
 		}
 
+		this.renderTarget.texture.type = renderer.getColorBufferType();
+
 		return this.scope === PassNode.COLOR ? this.getTextureNode() : this.getLinearDepthNode();
 
 	}

package/src/nodes/display/ScreenNode.js

@@ -243,6 +243,9 @@ export const viewportUV = /*@__PURE__*/ viewportCoordinate.div( viewportSize );
 
 // Deprecated
 
+/**
+ * @deprecated since r169. Use {@link screenSize} instead.
+ */
 export const viewportResolution = /*@__PURE__*/ ( Fn( () => { // @deprecated, r169
 
 	console.warn( 'TSL.ViewportNode: "viewportResolution" is deprecated. Use "screenSize" instead.' );
@@ -251,6 +254,9 @@ export const viewportResolution = /*@__PURE__*/ ( Fn( () => { // @deprecated, r1
 
 }, 'vec2' ).once() )();
 
+/**
+ * @deprecated since r168. Use {@link screenUV} instead.
+ */
 export const viewportTopLeft = /*@__PURE__*/ ( Fn( () => { // @deprecated, r168
 
 	console.warn( 'TSL.ViewportNode: "viewportTopLeft" is deprecated. Use "screenUV" instead.' );
@@ -259,6 +265,9 @@ export const viewportTopLeft = /*@__PURE__*/ ( Fn( () => { // @deprecated, r168
 
 }, 'vec2' ).once() )();
 
+/**
+ * @deprecated since r168. Use `screenUV.flipY()` instead.
+ */
 export const viewportBottomLeft = /*@__PURE__*/ ( Fn( () => { // @deprecated, r168
 
 	console.warn( 'TSL.ViewportNode: "viewportBottomLeft" is deprecated. Use "screenUV.flipY()" instead.' );

package/src/nodes/fog/Fog.js

@@ -78,6 +78,15 @@ export const fog = Fn( ( [ color, factor ] ) => {
 
 // Deprecated
 
+/**
+ * @function
+ * @deprecated since r171. Use `fog( color, rangeFogFactor( near, far ) )` instead.
+ *
+ * @param {Node} color
+ * @param {Node} near
+ * @param {Node} far
+ * @returns {Function}
+ */
 export function rangeFog( color, near, far ) { // @deprecated, r171
 
 	console.warn( 'THREE.TSL: "rangeFog( color, near, far )" is deprecated. Use "fog( color, rangeFogFactor( near, far ) )" instead.' );
@@ -85,6 +94,14 @@ export function rangeFog( color, near, far ) { // @deprecated, r171
 
 }
 
+/**
+ * @function
+ * @deprecated since r171. Use `fog( color, densityFogFactor( density ) )` instead.
+ *
+ * @param {Node} color
+ * @param {Node} density
+ * @returns {Function}
+ */
 export function densityFog( color, density ) { // @deprecated, r171
 
 	console.warn( 'THREE.TSL: "densityFog( color, density )" is deprecated. Use "fog( color, densityFogFactor( density ) )" instead.' );

package/src/nodes/gpgpu/AtomicFunctionNode.js

@@ -5,10 +5,10 @@ import { nodeProxy } from '../tsl/TSLCore.js';
 
 /**
  * `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.
+ * within a shader. In an atomic function, any modification to an atomic variable will
+ * occur as an indivisible 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.
+ * atomic operations will not interfere with each other.
  *
  * This node can only be used with a WebGPU backend.
  *
@@ -103,7 +103,13 @@ class AtomicFunctionNode extends TempNode {
 		const params = [];
 
 		params.push( `&${ a.build( builder, inputType ) }` );
-		params.push( b.build( builder, inputType ) );
+
+		if ( b !== null ) {
+
+			params.push( b.build( builder, inputType ) );
+
+
+		}
 
 		const methodSnippet = `${ builder.getMethod( method, type ) }( ${params.join( ', ' )} )`;
 
@@ -166,6 +172,16 @@ export const atomicFunc = ( method, pointerNode, valueNode, storeNode = null ) =
 
 };
 
+/**
+ * Loads the value stored in the atomic variable.
+ *
+ * @function
+ * @param {Node} pointerNode - An atomic variable or element of an atomic buffer.
+ * @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 atomicLoad = ( pointerNode, storeNode = null ) => atomicFunc( AtomicFunctionNode.ATOMIC_LOAD, pointerNode, null, storeNode );
+
 /**
  * Stores a value in the atomic variable.
  *