@plastic-software/three 0.167.3 → 0.174.0

package/src/nodes/utils/SplitNode.js

@@ -1,21 +1,67 @@
-import Node, { addNodeClass } from '../core/Node.js';
+import Node from '../core/Node.js';
 import { vectorComponents } from '../core/constants.js';
 
-const stringVectorComponents = vectorComponents.join( '' );
-
+const _stringVectorComponents = vectorComponents.join( '' );
+
+/**
+ * This module is part of the TSL core and usually not used in app level code.
+ * `SplitNode` represents a property access operation which means it is
+ * used to implement any `.xyzw`, `.rgba` and `stpq` usage on node objects.
+ * For example:
+ * ```js
+ * const redValue = color.r;
+ * ```
+ *
+ * @augments Node
+ */
 class SplitNode extends Node {
 
+	static get type() {
+
+		return 'SplitNode';
+
+	}
+
+	/**
+	 * Constructs a new split node.
+	 *
+	 * @param {Node} node - The node that should be accessed.
+	 * @param {string} [components='x'] - The components that should be accessed.
+	 */
 	constructor( node, components = 'x' ) {
 
 		super();
 
+		/**
+		 * The node that should be accessed.
+		 *
+		 * @type {Node}
+		 */
 		this.node = node;
+
+		/**
+		 * The components that should be accessed.
+		 *
+		 * @type {string}
+		 */
 		this.components = components;
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isSplitNode = true;
 
 	}
 
+	/**
+	 * Returns the vector length which is computed based on the requested components.
+	 *
+	 * @return {number} The vector length.
+	 */
 	getVectorLength() {
 
 		let vectorLength = this.components.length;
@@ -30,12 +76,24 @@ class SplitNode extends Node {
 
 	}
 
+	/**
+	 * Returns the component type of the node's type.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {string} The component type.
+	 */
 	getComponentType( builder ) {
 
 		return builder.getComponentType( this.node.getNodeType( builder ) );
 
 	}
 
+	/**
+	 * This method is overwritten since the node type is inferred from requested components.
+	 *
+	 * @param {NodeBuilder} builder - The current node builder.
+	 * @return {string} The node type.
+	 */
 	getNodeType( builder ) {
 
 		return builder.getTypeFromLength( this.components.length, this.getComponentType( builder ) );
@@ -65,7 +123,7 @@ class SplitNode extends Node {
 
 			const nodeSnippet = node.build( builder, type );
 
-			if ( this.components.length === nodeTypeLength && this.components === stringVectorComponents.slice( 0, this.components.length ) ) {
+			if ( this.components.length === nodeTypeLength && this.components === _stringVectorComponents.slice( 0, this.components.length ) ) {
 
 				// unnecessary swizzle
 
@@ -108,5 +166,3 @@ class SplitNode extends Node {
 }
 
 export default SplitNode;
-
-addNodeClass( 'SplitNode', SplitNode );

package/src/nodes/utils/SpriteSheetUVNode.js

@@ -1,15 +1,56 @@
-import Node, { addNodeClass } from '../core/Node.js';
-import { uv } from '../accessors/UVNode.js';
-import { nodeProxy, float, vec2 } from '../shadernode/ShaderNode.js';
-
+import Node from '../core/Node.js';
+import { uv } from '../accessors/UV.js';
+import { nodeProxy, float, vec2 } from '../tsl/TSLBase.js';
+
+/**
+ * Can be used to compute texture coordinates for animated sprite sheets.
+ *
+ * ```js
+ * const uvNode = spritesheetUV( vec2( 6, 6 ), uv(), time.mul( animationSpeed ) );
+ *
+ * material.colorNode = texture( spriteSheet, uvNode );
+ * ```
+ *
+ * @augments Node
+ */
 class SpriteSheetUVNode extends Node {
 
+	static get type() {
+
+		return 'SpriteSheetUVNode';
+
+	}
+
+	/**
+	 * Constructs a new sprite sheet uv node.
+	 *
+	 * @param {Node<vec2>} countNode - The node that defines the number of sprites in the x and y direction (e.g 6x6).
+	 * @param {Node<vec2>} [uvNode=uv()] - The uv node.
+	 * @param {Node<float>} [frameNode=float()] - The node that defines the current frame/sprite.
+	 */
 	constructor( countNode, uvNode = uv(), frameNode = float( 0 ) ) {
 
 		super( 'vec2' );
 
+		/**
+		 * The node that defines the number of sprites in the x and y direction (e.g 6x6).
+		 *
+		 * @type {Node<vec2>}
+		 */
 		this.countNode = countNode;
+
+		/**
+		 * The uv node.
+		 *
+		 * @type {Node<vec2>}
+		 */
 		this.uvNode = uvNode;
+
+		/**
+		 * The node that defines the current frame/sprite.
+		 *
+		 * @type {Node<float>}
+		 */
 		this.frameNode = frameNode;
 
 	}
@@ -36,6 +77,14 @@ class SpriteSheetUVNode extends Node {
 
 export default SpriteSheetUVNode;
 
-export const spritesheetUV = nodeProxy( SpriteSheetUVNode );
-
-addNodeClass( 'SpriteSheetUVNode', SpriteSheetUVNode );
+/**
+ * TSL function for creating a sprite sheet uv node.
+ *
+ * @tsl
+ * @function
+ * @param {Node<vec2>} countNode - The node that defines the number of sprites in the x and y direction (e.g 6x6).
+ * @param {Node<vec2>} [uvNode=uv()] - The uv node.
+ * @param {Node<float>} [frameNode=float()] - The node that defines the current frame/sprite.
+ * @returns {SpriteSheetUVNode}
+ */
+export const spritesheetUV = /*@__PURE__*/ nodeProxy( SpriteSheetUVNode );

package/src/nodes/utils/SpriteUtils.js

@@ -1,9 +1,25 @@
 import { modelWorldMatrix } from '../accessors/ModelNode.js';
-import { cameraViewMatrix, cameraProjectionMatrix } from '../accessors/CameraNode.js';
-import { positionLocal } from '../accessors/PositionNode.js';
-import { Fn, defined } from '../shadernode/ShaderNode.js';
-
-export const billboarding = Fn( ( { position = null, horizontal = true, vertical = false } ) => {
+import { cameraViewMatrix, cameraProjectionMatrix } from '../accessors/Camera.js';
+import { positionLocal } from '../accessors/Position.js';
+import { Fn, defined } from '../tsl/TSLBase.js';
+
+/**
+ * This can be used to achieve a billboarding behavior for flat meshes. That means they are
+ * oriented always towards the camera.
+ *
+ * ```js
+ * material.vertexNode = billboarding();
+ * ```
+ *
+ * @tsl
+ * @function
+ * @param {Object} config - The configuration object.
+ * @param {?Node<vec3>} [config.position=null] - Can be used to define the vertex positions in world space.
+ * @param {boolean} [config.horizontal=true] - Whether to follow the camera rotation horizontally or not.
+ * @param {boolean} [config.vertical=false] - Whether to follow the camera rotation vertically or not.
+ * @return {Node<vec3>} The updated vertex position in clip space.
+ */
+export const billboarding = /*@__PURE__*/ Fn( ( { position = null, horizontal = true, vertical = false } ) => {
 
 	let worldMatrix;
 

package/src/nodes/utils/StorageArrayElementNode.js

@@ -1,17 +1,52 @@
-import { addNodeClass } from '../core/Node.js';
-import { nodeProxy, addNodeElement } from '../shadernode/ShaderNode.js';
+import { nodeProxy } from '../tsl/TSLBase.js';
 import ArrayElementNode from './ArrayElementNode.js';
 
+/**
+ * This class enables element access on instances of {@link StorageBufferNode}.
+ * In most cases, it is indirectly used when accessing elements with the
+ * {@link StorageBufferNode#element} method.
+ *
+ * ```js
+ * const position = positionStorage.element( instanceIndex );
+ * ```
+ *
+ * @augments ArrayElementNode
+ */
 class StorageArrayElementNode extends ArrayElementNode {
 
+	static get type() {
+
+		return 'StorageArrayElementNode';
+
+	}
+
+	/**
+	 * Constructs storage buffer element node.
+	 *
+	 * @param {StorageBufferNode} storageBufferNode - The storage buffer node.
+	 * @param {Node} indexNode - The index node that defines the element access.
+	 */
 	constructor( storageBufferNode, indexNode ) {
 
 		super( storageBufferNode, indexNode );
 
+		/**
+		 * This flag can be used for type testing.
+		 *
+		 * @type {boolean}
+		 * @readonly
+		 * @default true
+		 */
 		this.isStorageArrayElementNode = true;
 
 	}
 
+	/**
+	 * The storage buffer node.
+	 *
+	 * @param {Node} value
+	 * @type {StorageBufferNode}
+	 */
 	set storageBufferNode( value ) {
 
 		this.node = value;
@@ -24,11 +59,25 @@ class StorageArrayElementNode extends ArrayElementNode {
 
 	}
 
+	getMemberType( builder, name ) {
+
+		const structTypeNode = this.storageBufferNode.structTypeNode;
+
+		if ( structTypeNode ) {
+
+			return structTypeNode.getMemberType( builder, name );
+
+		}
+
+		return 'void';
+
+	}
+
 	setup( builder ) {
 
 		if ( builder.isAvailable( 'storageBuffer' ) === false ) {
 
-			if ( ! this.node.instanceIndex && this.node.bufferObject === true ) {
+			if ( this.node.isPBO === true ) {
 
 				builder.setupPBO( this.node );
 
@@ -50,15 +99,13 @@ class StorageArrayElementNode extends ArrayElementNode {
 
 		if ( builder.isAvailable( 'storageBuffer' ) === false ) {
 
-			const { node } = this;
-
-			if ( ! node.instanceIndex && this.node.bufferObject === true && isAssignContext !== true ) {
+			if ( this.node.isPBO === true && isAssignContext !== true && ( this.node.value.isInstancedBufferAttribute || builder.shaderStage !== 'compute' ) ) {
 
 				snippet = builder.generatePBO( this );
 
 			} else {
 
-				snippet = node.build( builder );
+				snippet = this.node.build( builder );
 
 			}
 
@@ -84,8 +131,13 @@ class StorageArrayElementNode extends ArrayElementNode {
 
 export default StorageArrayElementNode;
 
-export const storageElement = nodeProxy( StorageArrayElementNode );
-
-addNodeElement( 'storageElement', storageElement );
-
-addNodeClass( 'StorageArrayElementNode', StorageArrayElementNode );
+/**
+ * TSL function for creating a storage element node.
+ *
+ * @tsl
+ * @function
+ * @param {StorageBufferNode} storageBufferNode - The storage buffer node.
+ * @param {Node} indexNode - The index node that defines the element access.
+ * @returns {StorageArrayElementNode}
+ */
+export const storageElement = /*@__PURE__*/ nodeProxy( StorageArrayElementNode );

package/src/nodes/utils/Timer.js

@@ -0,0 +1,73 @@
+import { renderGroup } from '../core/UniformGroupNode.js';
+import { uniform } from '../core/UniformNode.js';
+
+/**
+ * Represents the elapsed time in seconds.
+ *
+ * @tsl
+ * @type {UniformNode<float>}
+ */
+export const time = /*@__PURE__*/ uniform( 0 ).setGroup( renderGroup ).onRenderUpdate( ( frame ) => frame.time );
+
+/**
+ * Represents the delta time in seconds.
+ *
+ * @tsl
+ * @type {UniformNode<float>}
+ */
+export const deltaTime = /*@__PURE__*/ uniform( 0 ).setGroup( renderGroup ).onRenderUpdate( ( frame ) => frame.deltaTime );
+
+/**
+ * Represents the current frame ID.
+ *
+ * @tsl
+ * @type {UniformNode<uint>}
+ */
+export const frameId = /*@__PURE__*/ uniform( 0, 'uint' ).setGroup( renderGroup ).onRenderUpdate( ( frame ) => frame.frameId );
+
+// Deprecated
+
+/**
+ * @tsl
+ * @function
+ * @deprecated since r170. Use {@link time} instead.
+ *
+ * @param {number} [timeScale=1] - The time scale.
+ * @returns {UniformNode<float>}
+ */
+export const timerLocal = ( timeScale = 1 ) => { // @deprecated, r170
+
+	console.warn( 'TSL: timerLocal() is deprecated. Use "time" instead.' );
+	return time.mul( timeScale );
+
+};
+
+/**
+ * @tsl
+ * @function
+ * @deprecated since r170. Use {@link time} instead.
+ *
+ * @param {number} [timeScale=1] - The time scale.
+ * @returns {UniformNode<float>}
+ */
+export const timerGlobal = ( timeScale = 1 ) => { // @deprecated, r170
+
+	console.warn( 'TSL: timerGlobal() is deprecated. Use "time" instead.' );
+	return time.mul( timeScale );
+
+};
+
+/**
+ * @tsl
+ * @function
+ * @deprecated since r170. Use {@link deltaTime} instead.
+ *
+ * @param {number} [timeScale=1] - The time scale.
+ * @returns {UniformNode<float>}
+ */
+export const timerDelta = ( timeScale = 1 ) => { // @deprecated, r170
+
+	console.warn( 'TSL: timerDelta() is deprecated. Use "deltaTime" instead.' );
+	return deltaTime.mul( timeScale );
+
+};

package/src/nodes/utils/TriplanarTexturesNode.js

@@ -1,23 +1,86 @@
-import Node, { addNodeClass } from '../core/Node.js';
+import Node from '../core/Node.js';
 import { add } from '../math/OperatorNode.js';
-import { normalLocal } from '../accessors/NormalNode.js';
-import { positionLocal } from '../accessors/PositionNode.js';
+import { normalLocal } from '../accessors/Normal.js';
+import { positionLocal } from '../accessors/Position.js';
 import { texture } from '../accessors/TextureNode.js';
-import { addNodeElement, nodeProxy, float, vec3 } from '../shadernode/ShaderNode.js';
-
+import { nodeProxy, float, vec3 } from '../tsl/TSLBase.js';
+
+/**
+ * Can be used for triplanar texture mapping.
+ *
+ * ```js
+ * material.colorNode = triplanarTexture( texture( diffuseMap ) );
+ * ```
+ *
+ * @augments Node
+ */
 class TriplanarTexturesNode extends Node {
 
+	static get type() {
+
+		return 'TriplanarTexturesNode';
+
+	}
+
+	/**
+	 * Constructs a new triplanar textures node.
+	 *
+	 * @param {Node} textureXNode - First texture node.
+	 * @param {?Node} [textureYNode=null] - Second texture node. When not set, the shader will sample from `textureXNode` instead.
+	 * @param {?Node} [textureZNode=null] - Third texture node. When not set, the shader will sample from `textureXNode` instead.
+	 * @param {?Node<float>} [scaleNode=float(1)] - The scale node.
+	 * @param {?Node<vec3>} [positionNode=positionLocal] - Vertex positions in local space.
+	 * @param {?Node<vec3>} [normalNode=normalLocal] - Normals in local space.
+	 */
 	constructor( textureXNode, textureYNode = null, textureZNode = null, scaleNode = float( 1 ), positionNode = positionLocal, normalNode = normalLocal ) {
 
 		super( 'vec4' );
 
+		/**
+		 * First texture node.
+		 *
+		 * @type {Node}
+		 */
 		this.textureXNode = textureXNode;
+
+		/**
+		 * Second texture node. When not set, the shader will sample from `textureXNode` instead.
+		 *
+		 * @type {Node}
+		 * @default null
+		 */
 		this.textureYNode = textureYNode;
+
+		/**
+		 * Third texture node. When not set, the shader will sample from `textureXNode` instead.
+		 *
+		 * @type {Node}
+		 * @default null
+		 */
 		this.textureZNode = textureZNode;
 
+		/**
+		 * The scale node.
+		 *
+		 * @type {Node<float>}
+		 * @default float(1)
+		 */
 		this.scaleNode = scaleNode;
 
+		/**
+		 * Vertex positions in local space.
+		 *
+		 * @type {Node<vec3>}
+		 * @default positionLocal
+		 */
 		this.positionNode = positionNode;
+
+		/**
+		 * Normals in local space.
+		 *
+		 * @type {Node<vec3>}
+		 * @default normalLocal
+		 */
 		this.normalNode = normalNode;
 
 	}
@@ -54,9 +117,32 @@ class TriplanarTexturesNode extends Node {
 
 export default TriplanarTexturesNode;
 
-export const triplanarTextures = nodeProxy( TriplanarTexturesNode );
+/**
+ * TSL function for creating a triplanar textures node.
+ *
+ * @tsl
+ * @function
+ * @param {Node} textureXNode - First texture node.
+ * @param {?Node} [textureYNode=null] - Second texture node. When not set, the shader will sample from `textureXNode` instead.
+ * @param {?Node} [textureZNode=null] - Third texture node. When not set, the shader will sample from `textureXNode` instead.
+ * @param {?Node<float>} [scaleNode=float(1)] - The scale node.
+ * @param {?Node<vec3>} [positionNode=positionLocal] - Vertex positions in local space.
+ * @param {?Node<vec3>} [normalNode=normalLocal] - Normals in local space.
+ * @returns {TriplanarTexturesNode}
+ */
+export const triplanarTextures = /*@__PURE__*/ nodeProxy( TriplanarTexturesNode );
+
+/**
+ * TSL function for creating a triplanar textures node.
+ *
+ * @tsl
+ * @function
+ * @param {Node} textureXNode - First texture node.
+ * @param {?Node} [textureYNode=null] - Second texture node. When not set, the shader will sample from `textureXNode` instead.
+ * @param {?Node} [textureZNode=null] - Third texture node. When not set, the shader will sample from `textureXNode` instead.
+ * @param {?Node<float>} [scaleNode=float(1)] - The scale node.
+ * @param {?Node<vec3>} [positionNode=positionLocal] - Vertex positions in local space.
+ * @param {?Node<vec3>} [normalNode=normalLocal] - Normals in local space.
+ * @returns {TriplanarTexturesNode}
+ */
 export const triplanarTexture = ( ...params ) => triplanarTextures( ...params );
-
-addNodeElement( 'triplanarTexture', triplanarTexture );
-
-addNodeClass( 'TriplanarTexturesNode', TriplanarTexturesNode );

package/src/nodes/utils/UVUtils.js

@@ -1,12 +1,33 @@
-import { addNodeElement, Fn, vec2 } from '../shadernode/ShaderNode.js';
-
-export const rotateUV = Fn( ( [ uv, rotation, center = vec2( 0.5 ) ] ) => {
-
-	return uv.sub( center ).rotate( rotation ).add( center );
+import { Fn, vec2 } from '../tsl/TSLBase.js';
+import { rotate } from './RotateNode.js';
+
+/**
+ * Rotates the given uv coordinates around a center point
+ *
+ * @tsl
+ * @function
+ * @param {Node<vec2>} uv - The uv coordinates.
+ * @param {Node<float>} rotation - The rotation defined in radians.
+ * @param {Node<vec2>} center - The center of rotation
+ * @return {Node<vec2>} The rotated uv coordinates.
+ */
+export const rotateUV = /*@__PURE__*/ Fn( ( [ uv, rotation, center = vec2( 0.5 ) ] ) => {
+
+	return rotate( uv.sub( center ), rotation ).add( center );
 
 } );
 
-export const spherizeUV = Fn( ( [ uv, strength, center = vec2( 0.5 ) ] ) => {
+/**
+ * Applies a spherical warping effect to the given uv coordinates.
+ *
+ * @tsl
+ * @function
+ * @param {Node<vec2>} uv - The uv coordinates.
+ * @param {Node<float>} strength - The strength of the effect.
+ * @param {Node<vec2>} center - The center point
+ * @return {Node<vec2>} The updated uv coordinates.
+ */
+export const spherizeUV = /*@__PURE__*/ Fn( ( [ uv, strength, center = vec2( 0.5 ) ] ) => {
 
 	const delta = uv.sub( center );
 	const delta2 = delta.dot( delta );
@@ -16,6 +37,3 @@ export const spherizeUV = Fn( ( [ uv, strength, center = vec2( 0.5 ) ] ) => {
 	return uv.add( delta.mul( deltaOffset ) );
 
 } );
-
-addNodeElement( 'rotateUV', rotateUV );
-addNodeElement( 'spherizeUV', spherizeUV );

package/src/nodes/utils/ViewportUtils.js

@@ -1,13 +1,25 @@
-import { Fn } from '../shadernode/ShaderNode.js';
-import { viewportTopLeft } from '../display/ViewportNode.js';
+import { Fn } from '../tsl/TSLBase.js';
+import { screenUV } from '../display/ScreenNode.js';
 import { viewportDepthTexture } from '../display/ViewportDepthTextureNode.js';
 import { linearDepth } from '../display/ViewportDepthNode.js';
 
-export const viewportSafeUV = Fn( ( [ uv = null ] ) => {
+/**
+ * A special version of a screen uv function that involves a depth comparison
+ * when computing the final uvs. The function mitigates visual errors when
+ * using viewport texture nodes for refraction purposes. Without this function
+ * objects in front of a refractive surface might appear on the refractive surface
+ * which is incorrect.
+ *
+ * @tsl
+ * @function
+ * @param {?Node<vec2>} uv - Optional uv coordinates. By default `screenUV` is used.
+ * @return {Node<vec2>} The update uv coordinates.
+ */
+export const viewportSafeUV = /*@__PURE__*/ Fn( ( [ uv = null ] ) => {
 
 	const depth = linearDepth();
 	const depthDiff = linearDepth( viewportDepthTexture( uv ) ).sub( depth );
-	const finalUV = depthDiff.lessThan( 0 ).select( viewportTopLeft, uv );
+	const finalUV = depthDiff.lessThan( 0 ).select( screenUV, uv );
 
 	return finalUV;