super-three 0.171.0 → 0.173.0

package/src/nodes/pmrem/PMREMNode.js

@@ -8,10 +8,19 @@ import { nodeProxy, vec3 } from '../tsl/TSLBase.js';
 import { WebGLCoordinateSystem } from '../../constants.js';
 import { Texture } from '../../textures/Texture.js';
 
+/** @module PMREMNode **/
+
 let _generator = null;
 
 const _cache = new WeakMap();
 
+/**
+ * Generates the cubeUV size based on the given image height.
+ *
+ * @private
+ * @param {Number} imageHeight - The image height.
+ * @return {{texelWidth: Number,texelHeight: Number, maxMip: Number}} The result object.
+ */
 function _generateCubeUVSize( imageHeight ) {
 
 	const maxMip = Math.log2( imageHeight ) - 2;
@@ -24,6 +33,13 @@ function _generateCubeUVSize( imageHeight ) {
 
 }
 
+/**
+ * Generates a PMREM from the given texture .
+ *
+ * @private
+ * @param {Texture} texture - The texture to create the PMREM for.
+ * @return {Texture} The PMREM.
+ */
 function _getPMREMFromTexture( texture ) {
 
 	let cacheTexture = _cache.get( texture );
@@ -71,6 +87,17 @@ function _getPMREMFromTexture( texture ) {
 
 }
 
+/**
+ * This node represents a PMREM which is a special type of preprocessed
+ * environment map intended for PBR materials.
+ *
+ * ```js
+ * const material = new MeshStandardNodeMaterial();
+ * material.envNode = pmremTexture( envMap );
+ * ```
+ *
+ * @augments TempNode
+ */
 class PMREMNode extends TempNode {
 
 	static get type() {
@@ -79,27 +106,98 @@ class PMREMNode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new function overloading node.
+	 *
+	 * @param {Texture} value - The input texture.
+	 * @param {Node<vec2>} [uvNode=null] - The uv node.
+	 * @param {Node<float>} [levelNode=null] - The level node.
+	 */
 	constructor( value, uvNode = null, levelNode = null ) {
 
 		super( 'vec3' );
 
+		/**
+		 * Reference to the input texture.
+		 *
+		 * @private
+		 * @type {Texture}
+		 */
 		this._value = value;
+
+		/**
+		 * Reference to the generated PMREM.
+		 *
+		 * @private
+		 * @type {Texture | null}
+		 * @default null
+		 */
 		this._pmrem = null;
 
+		/**
+		 *  The uv node.
+		 *
+		 * @type {Node<vec2>}
+		 */
 		this.uvNode = uvNode;
+
+		/**
+		 *  The level node.
+		 *
+		 * @type {Node<float>}
+		 */
 		this.levelNode = levelNode;
 
+		/**
+		 * Reference to a PMREM generator.
+		 *
+		 * @private
+		 * @type {PMREMGenerator}
+		 * @default null
+		 */
 		this._generator = null;
 
 		const defaultTexture = new Texture();
 		defaultTexture.isRenderTargetTexture = true;
 
+		/**
+		 * The texture node holding the generated PMREM.
+		 *
+		 * @private
+		 * @type {TextureNode}
+		 */
 		this._texture = texture( defaultTexture );
 
+		/**
+		 * A uniform representing the PMREM's width.
+		 *
+		 * @private
+		 * @type {UniformNode<float>}
+		 */
 		this._width = uniform( 0 );
+
+		/**
+		 * A uniform representing the PMREM's height.
+		 *
+		 * @private
+		 * @type {UniformNode<float>}
+		 */
 		this._height = uniform( 0 );
+
+		/**
+		 * A uniform representing the PMREM's max Mip.
+		 *
+		 * @private
+		 * @type {UniformNode<float>}
+		 */
 		this._maxMip = uniform( 0 );
 
+		/**
+		 * The `updateBeforeType` is set to `NodeUpdateType.RENDER`.
+		 *
+		 * @type {String}
+		 * @default 'render'
+		 */
 		this.updateBeforeType = NodeUpdateType.RENDER;
 
 	}
@@ -111,12 +209,22 @@ class PMREMNode extends TempNode {
 
 	}
 
+	/**
+	 * The node's texture value.
+	 *
+	 * @type {Texture}
+	 */
 	get value() {
 
 		return this._value;
 
 	}
 
+	/**
+	 * Uses the given PMREM texture to update internal values.
+	 *
+	 * @param {Texture} texture - The PMREM texture.
+	 */
 	updateFromTexture( texture ) {
 
 		const cubeUVSize = _generateCubeUVSize( texture.image.height );
@@ -191,6 +299,8 @@ class PMREMNode extends TempNode {
 
 		}
 
+		uvNode = vec3( uvNode.x, uvNode.y.negate(), uvNode.z );
+
 		//
 
 		let levelNode = this.levelNode;
@@ -211,6 +321,13 @@ class PMREMNode extends TempNode {
 
 export default PMREMNode;
 
+/**
+ * Returns `true` if the given cube map image has been fully loaded.
+ *
+ * @private
+ * @param {Array<(Image|Object)>} image - The cube map image.
+ * @return {Boolean} Whether the given cube map is ready or not.
+ */
 function isCubeMapReady( image ) {
 
 	if ( image === null || image === undefined ) return false;
@@ -229,6 +346,13 @@ function isCubeMapReady( image ) {
 
 }
 
+/**
+ * Returns `true` if the given equirectangular image has been fully loaded.
+ *
+ * @private
+ * @param {(Image|Object)} image - The equirectangular image.
+ * @return {Boolean} Whether the given cube map is ready or not.
+ */
 function isEquirectangularMapReady( image ) {
 
 	if ( image === null || image === undefined ) return false;
@@ -237,4 +361,13 @@ function isEquirectangularMapReady( image ) {
 
 }
 
+/**
+ * TSL function for creating a PMREM node.
+ *
+ * @function
+ * @param {Texture} value - The input texture.
+ * @param {Node<vec2>} [uvNode=null] - The uv node.
+ * @param {Node<float>} [levelNode=null] - The level node.
+ * @returns {PMREMNode}
+ */
 export const pmremTexture = /*@__PURE__*/ nodeProxy( PMREMNode );

package/src/nodes/pmrem/PMREMUtils.js

@@ -237,7 +237,7 @@ const bilinearCubeUV = /*@__PURE__*/ Fn( ( [ envMap, direction_immutable, mipInt
 	uv.x.mulAssign( CUBEUV_TEXEL_WIDTH );
 	uv.y.mulAssign( CUBEUV_TEXEL_HEIGHT );
 
-	return envMap.uv( uv ).grad( vec2(), vec2() ); // disable anisotropic filtering
+	return envMap.sample( uv ).grad( vec2(), vec2() ); // disable anisotropic filtering
 
 } );
 
@@ -267,7 +267,7 @@ export const blur = /*@__PURE__*/ Fn( ( { n, latitudinal, poleAxis, outputDirect
 	axis.assign( normalize( axis ) );
 
 	const gl_FragColor = vec3().toVar();
-	gl_FragColor.addAssign( weights.element( int( 0 ) ).mul( getSample( { theta: 0.0, axis, outputDirection, mipInt, envMap, CUBEUV_TEXEL_WIDTH, CUBEUV_TEXEL_HEIGHT, CUBEUV_MAX_MIP } ) ) );
+	gl_FragColor.addAssign( weights.element( 0 ).mul( getSample( { theta: 0.0, axis, outputDirection, mipInt, envMap, CUBEUV_TEXEL_WIDTH, CUBEUV_TEXEL_HEIGHT, CUBEUV_MAX_MIP } ) ) );
 
 	Loop( { start: int( 1 ), end: n }, ( { i } ) => {
 

package/src/nodes/procedural/Checker.js

@@ -1,6 +1,15 @@
 import { uv } from '../accessors/UV.js';
 import { Fn } from '../tsl/TSLBase.js';
 
+/** @module Procedural **/
+
+/**
+ * Creates a 2x2 checkerboard pattern that can be used as procedural texture data.
+ *
+ * @method
+ * @param {Node<vec2>} coord - The uv coordinates.
+ * @return {Node<float>} The result data.
+ */
 export const checker = /*@__PURE__*/ Fn( ( [ coord = uv() ] ) => {
 
 	const uv = coord.mul( 2.0 );

package/src/nodes/shapes/Shapes.js

@@ -0,0 +1,33 @@
+import { Fn, float } from '../tsl/TSLBase.js';
+import { lengthSq, smoothstep } from '../math/MathNode.js';
+import { uv } from '../accessors/UV.js';
+
+/** @module Shapes **/
+
+/**
+ * Generates a circle based on the uv coordinates.
+ *
+ * @method
+ * @param {Node<vec2>} coord - The uv to generate the circle.
+ * @return {Node<float>} The circle shape.
+ */
+export const shapeCircle = Fn( ( [ coord = uv() ], { renderer, material } ) => {
+
+	const alpha = float( 1 ).toVar();
+	const len2 = lengthSq( coord.mul( 2 ).sub( 1 ) );
+
+	if ( material.alphaToCoverage && renderer.samples > 1 ) {
+
+		const dlen = float( len2.fwidth() ).toVar();
+
+		alpha.assign( smoothstep( dlen.oneMinus(), dlen.add( 1 ), len2 ).oneMinus() );
+
+	} else {
+
+		len2.greaterThan( 1.0 ).discard();
+
+	}
+
+	return alpha;
+
+} );

package/src/nodes/tsl/TSLBase.js

@@ -2,8 +2,9 @@
 // TSL Base Syntax
 
 export * from './TSLCore.js'; // float(), vec2(), vec3(), vec4(), mat3(), mat4(), Fn(), If(), element(), nodeObject(), nodeProxy(), ...
+export * from '../core/ArrayNode.js'; // array(), .toArray()
 export * from '../core/UniformNode.js'; // uniform()
-export * from '../core/PropertyNode.js'; // property()  <-> TODO: Seperate Material Properties in other file
+export * from '../core/PropertyNode.js'; // property()  <-> TODO: Separate Material Properties in other file
 export * from '../core/AssignNode.js'; // .assign()
 export * from '../code/FunctionCallNode.js'; // .call()
 export * from '../math/OperatorNode.js'; // .add(), .sub(), ...
@@ -11,7 +12,7 @@ export * from '../math/MathNode.js'; // abs(), floor(), ...
 export * from '../math/ConditionalNode.js'; // select(), ...
 export * from '../core/ContextNode.js'; // .context()
 export * from '../core/VarNode.js'; // .var() -> TODO: Maybe rename .toVar() -> .var()
-export * from '../core/VaryingNode.js'; // varying() -> TODO: Add vertexStage()
+export * from '../core/VaryingNode.js'; // varying(), vertexStage()
 export * from '../display/ColorSpaceNode.js'; // .toColorSpace()
 export * from '../display/ToneMappingNode.js'; // .toToneMapping()
 export * from '../accessors/BufferAttributeNode.js'; // .toAttribute()

package/src/nodes/tsl/TSLCore.js

@@ -6,9 +6,10 @@ import SplitNode from '../utils/SplitNode.js';
 import SetNode from '../utils/SetNode.js';
 import FlipNode from '../utils/FlipNode.js';
 import ConstNode from '../core/ConstNode.js';
+import MemberNode from '../utils/MemberNode.js';
 import { getValueFromType, getValueType } from '../core/NodeUtils.js';
 
-//
+/** @module TSLCore **/
 
 let currentStack = null;
 
@@ -112,6 +113,12 @@ const shaderNodeHandler = {
 
 				return nodeObject( new ArrayElementNode( nodeObj, new ConstNode( Number( prop ), 'uint' ) ) );
 
+			} else if ( /^get$/.test( prop ) === true ) {
+
+				// accessing properties
+
+				return ( value ) => nodeObject( new MemberNode( nodeObj, value ) );
+
 			}
 
 		}
@@ -261,6 +268,12 @@ class ShaderCallNodeInternal extends Node {
 
 	}
 
+	getMemberType( builder, name ) {
+
+		return this.getOutputNode( builder ).getMemberType( builder, name );
+
+	}
+
 	call( builder ) {
 
 		const { shaderNode, inputNodes } = this;
@@ -305,7 +318,7 @@ class ShaderCallNodeInternal extends Node {
 		} else {
 
 			const jsFunc = shaderNode.jsFunc;
-			const outputNode = inputNodes !== null ? jsFunc( inputNodes, builder ) : jsFunc( builder );
+			const outputNode = inputNodes !== null || jsFunc.length > 1 ? jsFunc( inputNodes || [], builder ) : jsFunc( builder );
 
 			result = nodeObject( outputNode );
 
@@ -553,6 +566,13 @@ export const Fn = ( jsFunc, nodeType ) => {
 
 };
 
+/**
+ * @function
+ * @deprecated since r168. Use {@link Fn} instead.
+ *
+ * @param  {...any} params
+ * @returns {Function}
+ */
 export const tslFn = ( ...params ) => { // @deprecated, r168
 
 	console.warn( 'TSL.ShaderNode: tslFn() has been renamed to Fn().' );

package/src/nodes/utils/ArrayElementNode.js

@@ -1,24 +1,60 @@
 import Node from '../core/Node.js';
 
-class ArrayElementNode extends Node {
+/**
+ * Base class for representing element access on an array-like
+ * node data structures.
+ *
+ * @augments Node
+ */
+class ArrayElementNode extends Node { // @TODO: If extending from TempNode it breaks webgpu_compute
 
 	static get type() {
 
 		return 'ArrayElementNode';
 
-	} // @TODO: If extending from TempNode it breaks webgpu_compute
+	}
 
+	/**
+	 * Constructs an array element node.
+	 *
+	 * @param {Node} node - The array-like node.
+	 * @param {Node} indexNode - The index node that defines the element access.
+	 */
 	constructor( node, indexNode ) {
 
 		super();
 
+		/**
+		 * The array-like node.
+		 *
+		 * @type {Node}
+		 */
 		this.node = node;
+
+		/**
+		 * The index node that defines the element access.
+		 *
+		 * @type {Node}
+		 */
 		this.indexNode = indexNode;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {Boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isArrayElementNode = true;
 
 	}
 
+	/**
+	 * This method is overwritten since the node type is inferred from the array-like node.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {String} The node type.
+	 */
 	getNodeType( builder ) {
 
 		return this.node.getElementType( builder );
@@ -30,7 +66,7 @@ class ArrayElementNode extends Node {
 		const nodeSnippet = this.node.build( builder );
 		const indexSnippet = this.indexNode.build( builder, 'uint' );
 
-		return `${nodeSnippet}[ ${indexSnippet} ]`;
+		return `${ nodeSnippet }[ ${ indexSnippet } ]`;
 
 	}
 

package/src/nodes/utils/ConvertNode.js

@@ -1,5 +1,12 @@
 import Node from '../core/Node.js';
 
+/**
+ * This module is part of the TSL core and usually not used in app level code.
+ * It represents a convert operation during the shader generation process
+ * meaning it converts the data type of a node to a target data type.
+ *
+ * @augments Node
+ */
 class ConvertNode extends Node {
 
 	static get type() {
@@ -8,15 +15,39 @@ class ConvertNode extends Node {
 
 	}
 
+	/**
+	 * Constructs a new convert node.
+	 *
+	 * @param {Node} node - The node which type should be converted.
+	 * @param {String} convertTo - The target node type. Multiple types can be defined by separating them with a `|` sign.
+	 */
 	constructor( node, convertTo ) {
 
 		super();
 
+		/**
+		 * The node which type should be converted.
+		 *
+		 * @type {Node}
+		 */
 		this.node = node;
+
+		/**
+		 * The target node type. Multiple types can be defined by separating them with a `|` sign.
+		 *
+		 * @type {String}
+		 */
 		this.convertTo = convertTo;
 
 	}
 
+	/**
+	 * This method is overwritten since the implementation tries to infer the best
+	 * matching type from the {@link ConvertNode#convertTo} property.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {String} The node type.
+	 */
 	getNodeType( builder ) {
 
 		const requestType = this.node.getNodeType( builder );

package/src/nodes/utils/CubeMapNode.js

@@ -6,8 +6,16 @@ import { cubeTexture } from '../accessors/CubeTextureNode.js';
 import CubeRenderTarget from '../../renderers/common/CubeRenderTarget.js';
 import { CubeReflectionMapping, CubeRefractionMapping, EquirectangularReflectionMapping, EquirectangularRefractionMapping } from '../../constants.js';
 
+/** @module CubeMapNode **/
+
 const _cache = new WeakMap();
 
+/**
+ * This node can be used to automatically convert environment maps in the
+ * equirectangular format into the cube map format.
+ *
+ * @augments TempNode
+ */
 class CubeMapNode extends TempNode {
 
 	static get type() {
@@ -16,20 +24,59 @@ class CubeMapNode extends TempNode {
 
 	}
 
+	/**
+	 * Constructs a new cube map node.
+	 *
+	 * @param {Node} envNode - The node representing the environment map.
+	 */
 	constructor( envNode ) {
 
 		super( 'vec3' );
 
+		/**
+		 * The node representing the environment map.
+		 *
+		 * @type {Node}
+		 */
 		this.envNode = envNode;
 
+		/**
+		 * A reference to the internal cube texture.
+		 *
+		 * @private
+		 * @type {CubeTexture}
+		 * @default null
+		 */
 		this._cubeTexture = null;
+
+		/**
+		 * A reference to the internal cube texture node.
+		 *
+		 * @private
+		 * @type {CubeTextureNode}
+		 */
 		this._cubeTextureNode = cubeTexture();
 
 		const defaultTexture = new CubeTexture();
 		defaultTexture.isRenderTargetTexture = true;
 
+		/**
+		 * A default cube texture that acts as a placeholder.
+		 * It is used when the conversion from equirectangular to cube
+		 * map has not finished yet for a given texture.
+		 *
+		 * @private
+		 * @type {CubeTexture}
+		 */
 		this._defaultTexture = defaultTexture;
 
+		/**
+		 * The `updateBeforeType` is set to `NodeUpdateType.RENDER` since the node updates
+		 * the texture once per render in its {@link CubeMapNode#updateBefore} method.
+		 *
+		 * @type {String}
+		 * @default 'render'
+		 */
 		this.updateBeforeType = NodeUpdateType.RENDER;
 
 	}
@@ -117,6 +164,14 @@ class CubeMapNode extends TempNode {
 
 export default CubeMapNode;
 
+/**
+ * Returns true if the given equirectangular image has been fully loaded
+ * and is ready for further processing.
+ *
+ * @private
+ * @param {Image} image - The equirectangular image to check.
+ * @return {Boolean} Whether the image is ready or not.
+ */
 function isEquirectangularMapReady( image ) {
 
 	if ( image === null || image === undefined ) return false;
@@ -125,6 +180,14 @@ function isEquirectangularMapReady( image ) {
 
 }
 
+/**
+ * This function is executed when `dispose()` is called on the equirectangular
+ * texture. In this case, the generated cube map with its render target
+ * is deleted as well.
+ *
+ * @private
+ * @param {Object} event - The event object.
+ */
 function onTextureDispose( event ) {
 
 	const texture = event.target;
@@ -143,6 +206,14 @@ function onTextureDispose( event ) {
 
 }
 
+/**
+ * This function makes sure the generated cube map uses the correct
+ * texture mapping that corresponds to the equirectangular original.
+ *
+ * @private
+ * @param {Texture} texture - The cube texture.
+ * @param {Number} mapping - The original texture mapping.
+ */
 function mapTextureMapping( texture, mapping ) {
 
 	if ( mapping === EquirectangularReflectionMapping ) {
@@ -157,4 +228,11 @@ function mapTextureMapping( texture, mapping ) {
 
 }
 
+/**
+ * TSL function for creating a cube map node.
+ *
+ * @function
+ * @param {Node} envNode - The node representing the environment map.
+ * @returns {CubeMapNode}
+ */
 export const cubeMapNode = /*@__PURE__*/ nodeProxy( CubeMapNode );

package/src/nodes/utils/Discard.js

@@ -2,7 +2,23 @@ import { select } from '../math/ConditionalNode.js';
 import { expression } from '../code/ExpressionNode.js';
 import { addMethodChaining } from '../tsl/TSLCore.js';
 
+/** @module Discard **/
+
+/**
+ * Represents a `discard` shader operation in TSL.
+ *
+ * @method
+ * @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();
+
+/**
+ * Represents a `return` shader operation in TSL.
+ *
+ * @method
+ * @return {ExpressionNode} The `return` expression.
+ */
 export const Return = () => expression( 'return' ).append();
 
 addMethodChaining( 'discard', Discard );