diff --git a/src/nodes/accessors/Camera.js b/src/nodes/accessors/Camera.js index 3a8dcd0e8bc265..ae67f4385bab21 100644 --- a/src/nodes/accessors/Camera.js +++ b/src/nodes/accessors/Camera.js @@ -2,11 +2,60 @@ import { uniform } from '../core/UniformNode.js'; import { renderGroup } from '../core/UniformGroupNode.js'; import { Vector3 } from '../../math/Vector3.js'; +/** @module Camera **/ + +/** + * TSL object that represents the `near` value of the camera used for the current render. + * + * @type {UniformNode} + */ export const cameraNear = /*@__PURE__*/ uniform( 'float' ).label( 'cameraNear' ).setGroup( renderGroup ).onRenderUpdate( ( { camera } ) => camera.near ); + +/** + * TSL object that represents the `far` value of the camera used for the current render. + * + * @type {UniformNode} + */ export const cameraFar = /*@__PURE__*/ uniform( 'float' ).label( 'cameraFar' ).setGroup( renderGroup ).onRenderUpdate( ( { camera } ) => camera.far ); + +/** + * TSL object that represents the projection matrix of the camera used for the current render. + * + * @type {UniformNode} + */ export const cameraProjectionMatrix = /*@__PURE__*/ uniform( 'mat4' ).label( 'cameraProjectionMatrix' ).setGroup( renderGroup ).onRenderUpdate( ( { camera } ) => camera.projectionMatrix ); + +/** + * TSL object that represents the inverse projection matrix of the camera used for the current render. + * + * @type {UniformNode} + */ export const cameraProjectionMatrixInverse = /*@__PURE__*/ uniform( 'mat4' ).label( 'cameraProjectionMatrixInverse' ).setGroup( renderGroup ).onRenderUpdate( ( { camera } ) => camera.projectionMatrixInverse ); + +/** + * TSL object that represents the view matrix of the camera used for the current render. + * + * @type {UniformNode} + */ export const cameraViewMatrix = /*@__PURE__*/ uniform( 'mat4' ).label( 'cameraViewMatrix' ).setGroup( renderGroup ).onRenderUpdate( ( { camera } ) => camera.matrixWorldInverse ); + +/** + * TSL object that represents the world matrix of the camera used for the current render. + * + * @type {UniformNode} + */ export const cameraWorldMatrix = /*@__PURE__*/ uniform( 'mat4' ).label( 'cameraWorldMatrix' ).setGroup( renderGroup ).onRenderUpdate( ( { camera } ) => camera.matrixWorld ); + +/** + * TSL object that represents the normal matrix of the camera used for the current render. + * + * @type {UniformNode} + */ export const cameraNormalMatrix = /*@__PURE__*/ uniform( 'mat3' ).label( 'cameraNormalMatrix' ).setGroup( renderGroup ).onRenderUpdate( ( { camera } ) => camera.normalMatrix ); + +/** + * TSL object that represents the positon in world space of the camera used for the current render. + * + * @type {UniformNode} + */ export const cameraPosition = /*@__PURE__*/ uniform( new Vector3() ).label( 'cameraPosition' ).setGroup( renderGroup ).onRenderUpdate( ( { camera }, self ) => self.value.setFromMatrixPosition( camera.matrixWorld ) ); diff --git a/src/nodes/accessors/PointUVNode.js b/src/nodes/accessors/PointUVNode.js index 6cefa0baa0f39d..2557564e0d4969 100644 --- a/src/nodes/accessors/PointUVNode.js +++ b/src/nodes/accessors/PointUVNode.js @@ -1,6 +1,17 @@ import Node from '../core/Node.js'; import { nodeImmutable } from '../tsl/TSLBase.js'; +/** @module PointUVNode **/ + +/** + * A node for representing the uv coordinates of points. + * + * Can only be used with a WebGL backend. In WebGPU, point + * primitives always have the size of one pixel and can thus + * can't be used as sprite-like objects that display textures. + * + * @augments Node + */ class PointUVNode extends Node { static get type() { @@ -9,10 +20,20 @@ class PointUVNode extends Node { } + /** + * Constructs a new point uv node. + */ constructor() { super( 'vec2' ); + /** + * This flag can be used for type testing. + * + * @type {Boolean} + * @readonly + * @default true + */ this.isPointUVNode = true; } @@ -27,4 +48,9 @@ class PointUVNode extends Node { export default PointUVNode; +/** + * TSL object that represents the uv coordinates of points. + * + * @type {PointUVNode} + */ export const pointUV = /*@__PURE__*/ nodeImmutable( PointUVNode ); diff --git a/src/nodes/accessors/Position.js b/src/nodes/accessors/Position.js index 3e63c04d512051..6d7408dd994acf 100644 --- a/src/nodes/accessors/Position.js +++ b/src/nodes/accessors/Position.js @@ -1,10 +1,54 @@ import { attribute } from '../core/AttributeNode.js'; import { modelWorldMatrix, modelViewMatrix } from './ModelNode.js'; +/** @module Position **/ + +/** + * TSL object that represents the position attribute of the current rendered object. + * + * @type {AttributeNode} + */ export const positionGeometry = /*@__PURE__*/ attribute( 'position', 'vec3' ); + +/** + * TSL object that represents the vertex position in local space of the current rendered object. + * + * @type {AttributeNode} + */ export const positionLocal = /*@__PURE__*/ positionGeometry.varying( 'positionLocal' ); + +/** + * TSL object that represents the previous vertex position in local space of the current rendered object. + * Used in context of {@link VelocityNode} for rendering motion vectors. + * + * @type {AttributeNode} + */ export const positionPrevious = /*@__PURE__*/ positionGeometry.varying( 'positionPrevious' ); + +/** + * TSL object that represents the vertex position in world space of the current rendered object. + * + * @type {VaryingNode} + */ export const positionWorld = /*@__PURE__*/ modelWorldMatrix.mul( positionLocal ).xyz.varying( 'v_positionWorld' ); + +/** + * TSL object that represents the position world direction of the current rendered object. + * + * @type {Node} + */ export const positionWorldDirection = /*@__PURE__*/ positionLocal.transformDirection( modelWorldMatrix ).varying( 'v_positionWorldDirection' ).normalize().toVar( 'positionWorldDirection' ); + +/** + * TSL object that represents the vertex position in view space of the current rendered object. + * + * @type {VaryingNode} + */ export const positionView = /*@__PURE__*/ modelViewMatrix.mul( positionLocal ).xyz.varying( 'v_positionView' ); + +/** + * TSL object that represents the position view direction of the current rendered object. + * + * @type {VaryingNode} + */ export const positionViewDirection = /*@__PURE__*/ positionView.negate().varying( 'v_positionViewDirection' ).normalize().toVar( 'positionViewDirection' ); diff --git a/src/nodes/accessors/ReferenceNode.js b/src/nodes/accessors/ReferenceNode.js index d8edcf8b562031..e511c5d381e9f4 100644 --- a/src/nodes/accessors/ReferenceNode.js +++ b/src/nodes/accessors/ReferenceNode.js @@ -8,6 +8,15 @@ import { nodeObject } from '../tsl/TSLBase.js'; import { uniformArray } from './UniformArrayNode.js'; import ArrayElementNode from '../utils/ArrayElementNode.js'; +/** @module ReferenceNode **/ + +/** + * This class is only relevant if the referenced property is array-like. + * In this case, `ReferenceElementNode` allows to refer to a specific + * element inside the data structure via an index. + * + * @augments ArrayElementNode + */ class ReferenceElementNode extends ArrayElementNode { static get type() { @@ -16,16 +25,43 @@ class ReferenceElementNode extends ArrayElementNode { } + /** + * Constructs a new reference element node. + * + * @param {Node} referenceNode - The reference node. + * @param {Node} indexNode - The index node that defines the element access. + */ constructor( referenceNode, indexNode ) { super( referenceNode, indexNode ); + /** + * Similar to {@link ReferenceNode#reference}, an additional + * property references to the current node. + * + * @type {Node} + * @default null + */ this.referenceNode = referenceNode; + /** + * This flag can be used for type testing. + * + * @type {Boolean} + * @readonly + * @default true + */ this.isReferenceElementNode = true; } + /** + * This method is overwritten since the node type is inferred from + * the uniform type of the reference node. + * + * @param {NodeBuilder} builder - The current node builder. + * @return {String} The node type. + */ getNodeType() { return this.referenceNode.uniformType; @@ -44,7 +80,14 @@ class ReferenceElementNode extends ArrayElementNode { } -// TODO: Extends this from ReferenceBaseNode +/** + * This type of node establishes a reference to a property of another object. + * In this way, the value of the node is automatically linked to the value of + * referenced object. Reference nodes internally represents the linked value + * as a uniform. + * + * @augments Node + */ class ReferenceNode extends Node { static get type() { @@ -53,31 +96,118 @@ class ReferenceNode extends Node { } + /** + * Constructs a new reference node. + * + * @param {String} property - The name of the property the node refers to. + * @param {String} uniformType - The uniform type that should be used to represent the property value. + * @param {Object?} [object=null] - The object the property belongs to. + * @param {Number?} [count=null] - When the linked property is an array-like, this parameter defines its length. + */ constructor( property, uniformType, object = null, count = null ) { super(); + /** + * The name of the property the node refers to. + * + * @type {String} + */ this.property = property; + + /** + * The uniform type that should be used to represent the property value. + * + * @type {String} + */ this.uniformType = uniformType; + + /** + * The object the property belongs to. + * + * @type {Object?} + * @default null + */ this.object = object; + + /** + * When the linked property is an array, this parameter defines its length. + * + * @type {Number?} + * @default null + */ this.count = count; + /** + * The property name might have dots so nested properties can be referred. + * The hierarchy of the names is stored inside this array. + * + * @type {Array} + */ this.properties = property.split( '.' ); + + /** + * Points to the current referred object. This property exists next to {@link ReferenceNode#object} + * since the final reference might be updated from calling code. + * + * @type {Object?} + * @default null + */ this.reference = object; + + /** + * The uniform node that holds the value of the reference node. + * + * @type {UniformNode} + * @default null + */ this.node = null; + + /** + * The uniform group of the internal uniform. + * + * @type {UniformGroupNode} + * @default null + */ this.group = null; + + /** + * An optinal label of the internal uniform node. + * + * @type {String?} + * @default null + */ this.name = null; + /** + * Overwritten since velocity nodes are updated per object. + * + * @type {String} + * @default 'object' + */ this.updateType = NodeUpdateType.OBJECT; } + /** + * When the referred property is array-like, this method can be used + * to access elements via an index node. + * + * @param {IndexNode} indexNode - indexNode. + * @return {ReferenceElementNode} A reference to an element. + */ element( indexNode ) { return nodeObject( new ReferenceElementNode( this, nodeObject( indexNode ) ) ); } + /** + * Sets the uniform group for this reference node. + * + * @param {UniformGroupNode} group - The uniform group to set. + * @return {ReferenceNode} A reference to this node. + */ setGroup( group ) { this.group = group; @@ -86,6 +216,12 @@ class ReferenceNode extends Node { } + /** + * Sets the label for the internal uniform. + * + * @param {String} name - The label to set. + * @return {ReferenceNode} A reference to this node. + */ label( name ) { this.name = name; @@ -94,6 +230,12 @@ class ReferenceNode extends Node { } + /** + * Sets the node type which automatically defines the internal + * uniform type. + * + * @param {String} uniformType - The type to set. + */ setNodeType( uniformType ) { let node = null; @@ -132,6 +274,13 @@ class ReferenceNode extends Node { } + /** + * This method is overwritten since the node type is inferred from + * the type of the reference node. + * + * @param {NodeBuilder} builder - The current node builder. + * @return {String} The node type. + */ getNodeType( builder ) { if ( this.node === null ) { @@ -145,6 +294,12 @@ class ReferenceNode extends Node { } + /** + * Returns the property value from the given referred object. + * + * @param {Object} [object=this.reference] - The object to retrieve the property value from. + * @return {Any} The value. + */ getValueFromReference( object = this.reference ) { const { properties } = this; @@ -161,6 +316,13 @@ class ReferenceNode extends Node { } + /** + * Allows to update the reference based on the given state. The state is only + * evaluated {@link ReferenceNode#object} is not set. + * + * @param {(NodeFrame|NodeBuilder)} state - The current state. + * @return {Object} The updated reference. + */ updateReference( state ) { this.reference = this.object !== null ? this.object : state.object; @@ -169,7 +331,13 @@ class ReferenceNode extends Node { } - setup() { + /** + * The output of the reference node is the internal uniform node. + * + * @param {NodeBuilder} builder - The current node builder. + * @return {UniformNode} The output node. + */ + setup( /* builder */ ) { this.updateValue(); @@ -177,12 +345,21 @@ class ReferenceNode extends Node { } + /** + * Overwritten to to update the internal uniform value. + * + * @param {NodeFrame} frame - A reference to the current node frame. + */ update( /*frame*/ ) { this.updateValue(); } + /** + * Retrieves the value from the referred object property and uses it + * to updated the internal uniform. + */ updateValue() { if ( this.node === null ) this.setNodeType( this.uniformType ); @@ -205,5 +382,25 @@ class ReferenceNode extends Node { export default ReferenceNode; +/** + * TSL function for creating a reference node with the given paramters. + * + * @function + * @param {String} name - The name of the property the node refers to. + * @param {String} type - The uniform type that should be used to represent the property value. + * @param {Object} object - The object the property belongs to. + * @returns {ReferenceNode} + */ export const reference = ( name, type, object ) => nodeObject( new ReferenceNode( name, type, object ) ); + +/** + * TSL function for creating a reference node with the given paramters. + * + * @function + * @param {String} name - The name of the property the node refers to. + * @param {String} type - The uniform type that should be used to represent the property value. + * @param {Number} count - The number of value inside the array-like object. + * @param {Object} object - An array-like object the property belongs to. + * @returns {ReferenceNode} + */ export const referenceBuffer = ( name, type, count, object ) => nodeObject( new ReferenceNode( name, type, object, count ) ); diff --git a/src/nodes/accessors/SceneNode.js b/src/nodes/accessors/SceneNode.js index 27ad4863765df7..90b4d76bb3db4c 100644 --- a/src/nodes/accessors/SceneNode.js +++ b/src/nodes/accessors/SceneNode.js @@ -9,6 +9,18 @@ import { reference } from './ReferenceNode.js'; const _e1 = /*@__PURE__*/ new Euler(); const _m1 = /*@__PURE__*/ new Matrix4(); +/** @module SceneNode **/ + +/** + * This module allows access to a collection of scene properties. The following predefined TSL objects + * are available for easier use: + * + * - `backgroundBlurriness`: A node that represents the scene's background blurriness. + * - `backgroundIntensity`: A node that represents the scene's background intensity. + * - `backgroundRotation`: A node that represents the scene's background rotation. + * + * @augments Node + */ class SceneNode extends Node { static get type() { @@ -17,15 +29,40 @@ class SceneNode extends Node { } + /** + * Constructs a new scene node. + * + * @param {('backgroundBlurriness'|'backgroundIntensity'|'backgroundRotation')} scope - The scope defines the type of scene property that is accessed. + * @param {Scene?} [scene=null] - A reference to the scene. + */ constructor( scope = SceneNode.BACKGROUND_BLURRINESS, scene = null ) { super(); + /** + * The scope defines the type of scene property that is accessed. + * + * @type {('backgroundBlurriness'|'backgroundIntensity'|'backgroundRotation')} + */ this.scope = scope; + + /** + * A reference to the scene that is going to be accessed. + * + * @type {Scene?} + * @default null + */ this.scene = scene; } + /** + * Depending on the scope, the method returns a different type of node that represents + * the respective scene property. + * + * @param {NodeBuilder} builder - The current node builder. + * @return {Node} The output node. + */ setup( builder ) { const scope = this.scope; @@ -84,6 +121,23 @@ SceneNode.BACKGROUND_ROTATION = 'backgroundRotation'; export default SceneNode; +/** + * TSL object that represents the scene's background blurriness. + * + * @type {SceneNode} + */ export const backgroundBlurriness = /*@__PURE__*/ nodeImmutable( SceneNode, SceneNode.BACKGROUND_BLURRINESS ); + +/** + * TSL object that represents the scene's background intensity. + * + * @type {SceneNode} + */ export const backgroundIntensity = /*@__PURE__*/ nodeImmutable( SceneNode, SceneNode.BACKGROUND_INTENSITY ); + +/** + * TSL object that represents the scene's background rotation. + * + * @type {SceneNode} + */ export const backgroundRotation = /*@__PURE__*/ nodeImmutable( SceneNode, SceneNode.BACKGROUND_ROTATION ); diff --git a/src/nodes/accessors/TextureSizeNode.js b/src/nodes/accessors/TextureSizeNode.js index cd7692f712140b..9d05a47e7439c8 100644 --- a/src/nodes/accessors/TextureSizeNode.js +++ b/src/nodes/accessors/TextureSizeNode.js @@ -1,6 +1,15 @@ import Node from '../core/Node.js'; import { nodeProxy } from '../tsl/TSLBase.js'; +/** @module TextureSizeNode **/ + +/** + * A node that represents the dimensions of a texture. The texture size is + * retrieved in the shader via built-in shader functions like `textureDimensions()` + * or `textureSize()`. + * + * @augments Node + */ class TextureSizeNode extends Node { static get type() { @@ -9,13 +18,38 @@ class TextureSizeNode extends Node { } + /** + * Constructs a new texture size node. + * + * @param {TextureNode} textureNode - A texture node which size should be retrieved. + * @param {Node?} [levelNode=null] - A level node which defines the requested mip. + */ constructor( textureNode, levelNode = null ) { super( 'uvec2' ); + /** + * This flag can be used for type testing. + * + * @type {Boolean} + * @readonly + * @default true + */ this.isTextureSizeNode = true; + /** + * A texture node which size should be retrieved. + * + * @type {TextureNode} + */ this.textureNode = textureNode; + + /** + * A level node which defines the requested mip. + * + * @type {Node} + * @default null + */ this.levelNode = levelNode; } @@ -33,4 +67,12 @@ class TextureSizeNode extends Node { export default TextureSizeNode; +/** + * TSL function for creating a texture size node with the given paramters. + * + * @function + * @param {TextureNode} textureNode - A texture node which size should be retrieved. + * @param {Node?} [levelNode=null] - A level node which defines the requested mip. + * @returns {TextureSizeNode} + */ export const textureSize = /*@__PURE__*/ nodeProxy( TextureSizeNode ); diff --git a/src/nodes/accessors/UV.js b/src/nodes/accessors/UV.js index 4789a74bc36d67..6c94158bfdc8c0 100644 --- a/src/nodes/accessors/UV.js +++ b/src/nodes/accessors/UV.js @@ -1,3 +1,12 @@ import { attribute } from '../core/AttributeNode.js'; +/** @module UV **/ + +/** + * TSL function for creating an uv attribute node with the given index. + * + * @function + * @param {Number} index - The uv index. + * @return {AttributeNode} The uv attribute node. + */ export const uv = ( index ) => attribute( 'uv' + ( index > 0 ? index : '' ), 'vec2' ); diff --git a/src/nodes/accessors/UserDataNode.js b/src/nodes/accessors/UserDataNode.js index ff4a52f06c2289..01665518bcef30 100644 --- a/src/nodes/accessors/UserDataNode.js +++ b/src/nodes/accessors/UserDataNode.js @@ -1,6 +1,22 @@ import ReferenceNode from './ReferenceNode.js'; import { nodeObject } from '../tsl/TSLBase.js'; +/** @module UserDataNode **/ + +/** + * A special type of reference node that allows to link values in + * `userData` fields to node objects. + * ```js + * sprite.userData.rotation = 1; // stores individual rotation per sprite + * + * const material = new THREE.SpriteNodeMaterial(); + * material.rotationNode = userData( 'rotation', 'float' ); + * ``` + * Since `UserDataNode` is extended from {@link ReferenceNode}, the node value + * will automatically be updated when the `rotation` user data field changes. + * + * @augments ReferenceNode + */ class UserDataNode extends ReferenceNode { static get type() { @@ -9,14 +25,35 @@ class UserDataNode extends ReferenceNode { } + /** + * Constructs a new user data node. + * + * @param {String} property - The property name that should be referenced by the node. + * @param {String} inputType - The node data type of the reference. + * @param {Object?} [userData=null] - A reference to the `userData` object. If not provided, the `userData` property of the 3D object that uses the node material is evaluated. + */ constructor( property, inputType, userData = null ) { super( property, inputType, userData ); + /** + * A reference to the `userData` object. If not provided, the `userData` + * property of the 3D object that uses the node material is evaluated. + * + * @type {Object?} + * @default null + */ this.userData = userData; } + /** + * Overwritten to make sure {@link ReferenceNode#reference} points to the correct + * `userData` field. + * + * @param {(NodeFrame|NodeBuilder)} state - The current state to evaluate. + * @return {Object} A reference to the `userData` field. + */ updateReference( state ) { this.reference = this.userData !== null ? this.userData : state.object.userData; @@ -29,4 +66,13 @@ class UserDataNode extends ReferenceNode { export default UserDataNode; +/** + * TSL function for creating a user data node with the given paramters. + * + * @function + * @param {String} name - The property name that should be referenced by the node. + * @param {String} inputType - The node data type of the reference. + * @param {Object?} userData - A reference to the `userData` object. If not provided, the `userData` property of the 3D object that uses the node material is evaluated. + * @returns {UserDataNode} + */ export const userData = ( name, inputType, userData ) => nodeObject( new UserDataNode( name, inputType, userData ) ); diff --git a/src/nodes/accessors/VelocityNode.js b/src/nodes/accessors/VelocityNode.js index 62b412f0216186..bf9252f24fe441 100644 --- a/src/nodes/accessors/VelocityNode.js +++ b/src/nodes/accessors/VelocityNode.js @@ -11,6 +11,18 @@ import { renderGroup } from '../core/UniformGroupNode.js'; const _objectData = new WeakMap(); +/** @module VelocityNode **/ + +/** + * A node for representing motion or velocity vectors. Foundation + * for advanced post processing effects like motion blur or TRAA. + * + * The node keeps track of the model, view and projection matrices + * of the previous frame and uses them to compute offsets in NDC space. + * These offsets represent the final velocity. + * + * @augments TempNode + */ class VelocityNode extends TempNode { static get type() { @@ -19,27 +31,81 @@ class VelocityNode extends TempNode { } + /** + * Constructs a new vertex color node. + * + * @param {Number} [index=0] - The attribute index. + */ constructor() { super( 'vec2' ); + /** + * The current projection matrix. + * + * @type {Matrix4?} + * @default null + */ this.projectionMatrix = null; + /** + * Overwritten since velocity nodes are updated per object. + * + * @type {String} + * @default 'object' + */ this.updateType = NodeUpdateType.OBJECT; + + /** + * Overwritten since velocity nodes save data after the update. + * + * @type {String} + * @default 'object' + */ this.updateAfterType = NodeUpdateType.OBJECT; + /** + * Uniform node representing the previous model matrix in world space. + * + * @type {UniformNode} + * @default null + */ this.previousModelWorldMatrix = uniform( new Matrix4() ); + + /** + * Uniform node representing the previous projection matrix. + * + * @type {UniformNode} + * @default null + */ this.previousProjectionMatrix = uniform( new Matrix4() ).setGroup( renderGroup ); + + /** + * Uniform node representing the previous view matrix. + * + * @type {UniformNode} + * @default null + */ this.previousCameraViewMatrix = uniform( new Matrix4() ); } + /** + * Sets the given projection matrix. + * + * @param {Matrix4} projectionMatrix - The projection matrix to set. + */ setProjectionMatrix( projectionMatrix ) { this.projectionMatrix = projectionMatrix; } + /** + * Updates velocity specific uniforms. + * + * @param {NodeFrame} frame - A reference to the current node frame. + */ update( { frameId, camera, object } ) { const previousModelMatrix = getPreviousMatrix( object ); @@ -82,12 +148,23 @@ class VelocityNode extends TempNode { } + /** + * Overwritten to updated velocity specific uniforms. + * + * @param {NodeFrame} frame - A reference to the current node frame. + */ updateAfter( { object } ) { getPreviousMatrix( object ).copy( object.matrixWorld ); } + /** + * Implements the velocity computation based on the previous and current vertex data. + * + * @param {NodeBuilder} builder - A reference to the current node builder. + * @return {Node} The motion vector. + */ setup( /*builder*/ ) { const projectionMatrix = ( this.projectionMatrix === null ) ? cameraProjectionMatrix : uniform( this.projectionMatrix ); @@ -141,4 +218,9 @@ function getPreviousMatrix( object, index = 0 ) { export default VelocityNode; +/** + * TSL object that represents the velocity of a render pass. + * + * @type {VelocityNode} + */ export const velocity = /*@__PURE__*/ nodeImmutable( VelocityNode ); diff --git a/src/nodes/accessors/VertexColorNode.js b/src/nodes/accessors/VertexColorNode.js index 89abfb0350a923..4049a24653ed2b 100644 --- a/src/nodes/accessors/VertexColorNode.js +++ b/src/nodes/accessors/VertexColorNode.js @@ -1,8 +1,14 @@ import AttributeNode from '../core/AttributeNode.js'; import { nodeObject } from '../tsl/TSLBase.js'; - import { Vector4 } from '../../math/Vector4.js'; +/** @module VertexColorNode **/ + +/** + * An attribute node for representing vertex colors. + * + * @augments AttributeNode + */ class VertexColorNode extends AttributeNode { static get type() { @@ -11,16 +17,40 @@ class VertexColorNode extends AttributeNode { } + /** + * Constructs a new vertex color node. + * + * @param {Number} [index=0] - The attribute index. + */ constructor( index = 0 ) { super( null, 'vec4' ); + /** + * This flag can be used for type testing. + * + * @type {Boolean} + * @readonly + * @default true + */ this.isVertexColorNode = true; + /** + * The attribute index to enable more than one sets of vertex colors. + * + * @type {Number} + * @default 0 + */ this.index = index; } + /** + * Overwrites the default implementation by honoring the attribute index. + * + * @param {NodeBuilder} builder - The current node builder. + * @return {String} The attribute name. + */ getAttributeName( /*builder*/ ) { const index = this.index; @@ -71,4 +101,11 @@ class VertexColorNode extends AttributeNode { export default VertexColorNode; -export const vertexColor = ( ...params ) => nodeObject( new VertexColorNode( ...params ) ); +/** + * TSL function for creating a reference node with the given paramters. + * + * @function + * @param {Number} index - The attribute index. + * @returns {VertexColorNode} + */ +export const vertexColor = ( index ) => nodeObject( new VertexColorNode( index ) ); diff --git a/src/nodes/code/CodeNode.js b/src/nodes/code/CodeNode.js index 86180be2f26ec8..b3ea6d49884efd 100644 --- a/src/nodes/code/CodeNode.js +++ b/src/nodes/code/CodeNode.js @@ -1,6 +1,8 @@ import Node from '../core/Node.js'; import { nodeProxy } from '../tsl/TSLBase.js'; +/** @module CodeNode **/ + /** * This class represents native code sections. It is the base * class for modules like {@link FunctionNode} which allows to implement @@ -138,8 +140,43 @@ class CodeNode extends Node { export default CodeNode; +/** + * TSL function for creating a code node with the given paramters. + * + * @function + * @param {String} [code=''] - The native code. + * @param {Array} [includes=[]] - An array of includes. + * @param {('js'|'wgsl'|'glsl')} [language=''] - The used language. + * @returns {CodeNode} + */ export const code = /*@__PURE__*/ nodeProxy( CodeNode ); +/** + * TSL function for creating a JS code node with the given paramters. + * + * @function + * @param {String} src - The native code. + * @param {Array} includes - An array of includes. + * @returns {CodeNode} + */ export const js = ( src, includes ) => code( src, includes, 'js' ); + +/** + * TSL function for creating a WGSL code node with the given paramters. + * + * @function + * @param {String} src - The native code. + * @param {Array} includes - An array of includes. + * @returns {CodeNode} + */ export const wgsl = ( src, includes ) => code( src, includes, 'wgsl' ); + +/** + * TSL function for creating a GLSL code node with the given paramters. + * + * @function + * @param {String} src - The native code. + * @param {Array} includes - An array of includes. + * @returns {CodeNode} + */ export const glsl = ( src, includes ) => code( src, includes, 'glsl' ); diff --git a/src/nodes/code/ExpressionNode.js b/src/nodes/code/ExpressionNode.js index 2dcc305715511d..b2c9e2c434a458 100644 --- a/src/nodes/code/ExpressionNode.js +++ b/src/nodes/code/ExpressionNode.js @@ -1,6 +1,8 @@ import Node from '../core/Node.js'; import { nodeProxy } from '../tsl/TSLCore.js'; +/** @module ExpressionNode **/ + /** * This class can be used to implement basic expressions in shader code. * Basic examples for that are `return`, `continue` or `discard` statements. @@ -56,4 +58,12 @@ class ExpressionNode extends Node { export default ExpressionNode; +/** + * TSL function for creating an expression node with the given paramters. + * + * @function + * @param {String} [snippet=''] - The native code snippet. + * @param {String} [nodeType='void'] - The node type. + * @returns {ExpressionNode} + */ export const expression = /*@__PURE__*/ nodeProxy( ExpressionNode ); diff --git a/src/nodes/core/AssignNode.js b/src/nodes/core/AssignNode.js index 35a7dac5551134..e339742be2ba37 100644 --- a/src/nodes/core/AssignNode.js +++ b/src/nodes/core/AssignNode.js @@ -2,6 +2,8 @@ import TempNode from '../core/TempNode.js'; import { addMethodChaining, nodeProxy } from '../tsl/TSLCore.js'; import { vectorComponents } from '../core/constants.js'; +/** @module AssignNode **/ + /** * These node represents an assign operation. Meaning a node is assigned * to another node. @@ -162,6 +164,14 @@ class AssignNode extends TempNode { export default AssignNode; +/** + * TSL function for creating an assign node with the given parameters. + * + * @function + * @param {Node} targetNode - The target node. + * @param {Node} sourceNode - The source type. + * @returns {AssignNode} + */ export const assign = /*@__PURE__*/ nodeProxy( AssignNode ); addMethodChaining( 'assign', assign ); diff --git a/src/nodes/core/AttributeNode.js b/src/nodes/core/AttributeNode.js index b614fc55425763..453a2ec6ac1993 100644 --- a/src/nodes/core/AttributeNode.js +++ b/src/nodes/core/AttributeNode.js @@ -1,6 +1,8 @@ import Node from './Node.js'; import { nodeObject, varying } from '../tsl/TSLBase.js'; +/** @module AttributeNode **/ + /** * Base class for representing shader attributes as nodes. * @@ -155,4 +157,12 @@ class AttributeNode extends Node { export default AttributeNode; +/** + * TSL function for creating an attribute node with the given parameters. + * + * @function + * @param {String} name - The name of the attribute. + * @param {String?} nodeType - The node type. + * @returns {AttributeNode} + */ export const attribute = ( name, nodeType ) => nodeObject( new AttributeNode( name, nodeType ) ); diff --git a/src/nodes/core/BypassNode.js b/src/nodes/core/BypassNode.js index 7dabb9e70a9469..6edb2f9b8aaae4 100644 --- a/src/nodes/core/BypassNode.js +++ b/src/nodes/core/BypassNode.js @@ -1,6 +1,8 @@ import Node from './Node.js'; import { addMethodChaining, nodeProxy } from '../tsl/TSLCore.js'; +/** @module BypassNode **/ + /** * The class generates the code of a given node but returns another node in the output. * This can be used to call a method or node that does not return a value, i.e. @@ -79,6 +81,14 @@ class BypassNode extends Node { export default BypassNode; +/** + * TSL function for creating a bypass node with the given parameters. + * + * @function + * @param {Node} outputNode - The output node. + * @param {Node} callNode - The call node. + * @returns {BypassNode} + */ export const bypass = /*@__PURE__*/ nodeProxy( BypassNode ); addMethodChaining( 'bypass', bypass ); diff --git a/src/nodes/core/CacheNode.js b/src/nodes/core/CacheNode.js index 290e1cdc26cbd1..7e8025322360ae 100644 --- a/src/nodes/core/CacheNode.js +++ b/src/nodes/core/CacheNode.js @@ -1,6 +1,8 @@ import Node from './Node.js'; import { addMethodChaining, nodeObject } from '../tsl/TSLCore.js'; +/** @module CacheNode **/ + /** * This node can be used as a cache management component for another node. * Caching is in general used by default in {@link NodeBuilder} but this node @@ -77,6 +79,14 @@ class CacheNode extends Node { export default CacheNode; -export const cache = ( node, ...params ) => nodeObject( new CacheNode( nodeObject( node ), ...params ) ); +/** + * TSL function for creating a cache node with the given parameters. + * + * @function + * @param {Node} node - The node that should be cached. + * @param {Boolean} parent - Whether this node refers to a shared parent cache or not. + * @returns {CacheNode} + */ +export const cache = ( node, parent ) => nodeObject( new CacheNode( nodeObject( node ), parent ) ); addMethodChaining( 'cache', cache ); diff --git a/src/nodes/core/ContextNode.js b/src/nodes/core/ContextNode.js index 813fd9d80c6127..7db8b400ac85af 100644 --- a/src/nodes/core/ContextNode.js +++ b/src/nodes/core/ContextNode.js @@ -1,6 +1,8 @@ import Node from './Node.js'; import { addMethodChaining, nodeProxy } from '../tsl/TSLCore.js'; +/** @module ContextNode **/ + /** * This node can be used as a context management component for another node. * {@link NodeBuilder} performs its node building process in a specific context and @@ -116,7 +118,24 @@ class ContextNode extends Node { export default ContextNode; +/** + * TSL function for creating a context node with the given parameters. + * + * @function + * @param {Node} node - The node whose context should be modified. + * @param {Object} [value={}] - The modified context data. + * @returns {ContextNode} + */ export const context = /*@__PURE__*/ nodeProxy( ContextNode ); + +/** + * TSL function for defining a label context value for a given node. + * + * @function + * @param {Node} node - The node whose context should be modified. + * @param {String} name - The name/label to set. + * @returns {ContextNode} + */ export const label = ( node, name ) => context( node, { label: name } ); addMethodChaining( 'context', context ); diff --git a/src/nodes/core/IndexNode.js b/src/nodes/core/IndexNode.js index a00f441479df5f..d271c47cbd6764 100644 --- a/src/nodes/core/IndexNode.js +++ b/src/nodes/core/IndexNode.js @@ -1,6 +1,8 @@ import Node from './Node.js'; import { nodeImmutable, varying } from '../tsl/TSLBase.js'; +/** @module IndexNode **/ + /** * This class represents shader indices of different types. The following predefined node * objects cover frequent use cases: @@ -115,9 +117,44 @@ IndexNode.DRAW = 'draw'; export default IndexNode; +/** + * TSL object that represents the index of a vertex within a mesh. + * + * @type {IndexNode} + */ export const vertexIndex = /*@__PURE__*/ nodeImmutable( IndexNode, IndexNode.VERTEX ); + +/** + * TSL object that represents the index of either a mesh instance or an invocation of a compute shader. + * + * @type {IndexNode} + */ export const instanceIndex = /*@__PURE__*/ nodeImmutable( IndexNode, IndexNode.INSTANCE ); + +/** + * TSL object that represents the index of the subgroup the current compute invocation belongs to. + * + * @type {IndexNode} + */ export const subgroupIndex = /*@__PURE__*/ nodeImmutable( IndexNode, IndexNode.SUBGROUP ); + +/** + * TSL object that represents the index of a compute invocation within the scope of a subgroup. + * + * @type {IndexNode} + */ export const invocationSubgroupIndex = /*@__PURE__*/ nodeImmutable( IndexNode, IndexNode.INVOCATION_SUBGROUP ); + +/** + * TSL object that represents the index of a compute invocation within the scope of a workgroup load. + * + * @type {IndexNode} + */ export const invocationLocalIndex = /*@__PURE__*/ nodeImmutable( IndexNode, IndexNode.INVOCATION_LOCAL ); + +/** + * TSL object that represents the index of a draw call. + * + * @type {IndexNode} + */ export const drawIndex = /*@__PURE__*/ nodeImmutable( IndexNode, IndexNode.DRAW ); diff --git a/src/nodes/core/MRTNode.js b/src/nodes/core/MRTNode.js index 93401f3f1ec402..ef60b5a7464c68 100644 --- a/src/nodes/core/MRTNode.js +++ b/src/nodes/core/MRTNode.js @@ -1,6 +1,8 @@ import OutputStructNode from './OutputStructNode.js'; import { nodeProxy, vec4 } from '../tsl/TSLBase.js'; +/** @module MRTNode **/ + /** * Returns the MRT texture index for the given name. * @@ -139,4 +141,11 @@ class MRTNode extends OutputStructNode { export default MRTNode; +/** + * TSL function for creating a MRT node with the given parameters. + * + * @function + * @param {Object} outputNodes - The MRT outputs. + * @returns {MRTNode} + */ export const mrt = /*@__PURE__*/ nodeProxy( MRTNode ); diff --git a/src/nodes/core/OutputStructNode.js b/src/nodes/core/OutputStructNode.js index 804f77c97725e7..95f4a8f7b02a52 100644 --- a/src/nodes/core/OutputStructNode.js +++ b/src/nodes/core/OutputStructNode.js @@ -1,6 +1,8 @@ import Node from './Node.js'; import { nodeProxy } from '../tsl/TSLBase.js'; +/** @module OutputStructNode **/ + /** * This node can be used to define multiple outputs in a shader programs. * @@ -82,4 +84,11 @@ class OutputStructNode extends Node { export default OutputStructNode; +/** + * TSL function for creating an output struct node with the given parameters. + * + * @function + * @param {...Node} members - A parameter list of nodes. + * @returns {OutputStructNode} + */ export const outputStruct = /*@__PURE__*/ nodeProxy( OutputStructNode ); diff --git a/src/nodes/core/ParameterNode.js b/src/nodes/core/ParameterNode.js index 9f265b91a8adc5..338a0e3bba208c 100644 --- a/src/nodes/core/ParameterNode.js +++ b/src/nodes/core/ParameterNode.js @@ -1,6 +1,8 @@ import { nodeObject } from '../tsl/TSLBase.js'; import PropertyNode from './PropertyNode.js'; +/** @module ParameterNode **/ + /** * Special version of {@link PropertyNode} which is used for parameters. * @@ -52,9 +54,11 @@ class ParameterNode extends PropertyNode { export default ParameterNode; /** + * TSL function for creating a parameter node with the given paramters. * - * @param {string} type - * @param {string?} [name=null] - * @returns {ShaderNodeObject} + * @function + * @param {String} type - The type of the node. + * @param {String?} name - The name of the parameter in the shader. + * @returns {ParameterNode} */ export const parameter = ( type, name ) => nodeObject( new ParameterNode( type, name ) ); diff --git a/src/nodes/core/StackNode.js b/src/nodes/core/StackNode.js index a3603d9dfdfb69..59ce71fa00e027 100644 --- a/src/nodes/core/StackNode.js +++ b/src/nodes/core/StackNode.js @@ -2,6 +2,8 @@ import Node from './Node.js'; import { select } from '../math/ConditionalNode.js'; import { ShaderNode, nodeProxy, getCurrentStack, setCurrentStack } from '../tsl/TSLBase.js'; +/** @module StackNode **/ + /** * Stack is a helper for Nodes that need to produce stack-based code instead of continuous flow. * They are usually needed in cases like `If`, `Else`. @@ -175,4 +177,11 @@ class StackNode extends Node { export default StackNode; +/** + * TSL function for creating a stack node with the given parameters. + * + * @function + * @param {StackNode?} [parent=null] - The parent stack node. + * @returns {StackNode} + */ export const stack = /*@__PURE__*/ nodeProxy( StackNode ); diff --git a/src/nodes/core/UniformGroupNode.js b/src/nodes/core/UniformGroupNode.js index 580c7db4465d81..f0526300b2888e 100644 --- a/src/nodes/core/UniformGroupNode.js +++ b/src/nodes/core/UniformGroupNode.js @@ -1,5 +1,7 @@ import Node from './Node.js'; +/** @module UniformGroupNode **/ + /** * This node can be used to group single instances of {@link UniformNode} * and manage them as a uniform buffer. @@ -91,9 +93,42 @@ class UniformGroupNode extends Node { export default UniformGroupNode; +/** + * TSL function for creating a uniform group node with the given name. + * + * @function + * @param {String} name - The name of the uniform group node. + * @returns {UniformGroupNode} + */ export const uniformGroup = ( name ) => new UniformGroupNode( name ); + +/** + * TSL function for creating a shared uniform group node with the given name and order. + * + * @function + * @param {String} name - The name of the uniform group node. + * @param {Number} [order=0] - Influences the internal sorting. + * @returns {UniformGroupNode} + */ export const sharedUniformGroup = ( name, order = 0 ) => new UniformGroupNode( name, true, order ); +/** + * TSL object that represents a shared uniform group node which is updated once per frame. + * + * @type {UniformGroupNode} + */ export const frameGroup = /*@__PURE__*/ sharedUniformGroup( 'frame' ); + +/** + * TSL object that represents a shared uniform group node which is updated once per render. + * + * @type {UniformGroupNode} + */ export const renderGroup = /*@__PURE__*/ sharedUniformGroup( 'render' ); + +/** + * TSL object that represents a uniform group node which is updated once per object. + * + * @type {UniformGroupNode} + */ export const objectGroup = /*@__PURE__*/ uniformGroup( 'object' ); diff --git a/src/nodes/core/UniformNode.js b/src/nodes/core/UniformNode.js index 05e349d494a8d6..03491f170f0848 100644 --- a/src/nodes/core/UniformNode.js +++ b/src/nodes/core/UniformNode.js @@ -2,6 +2,8 @@ import InputNode from './InputNode.js'; import { objectGroup } from './UniformGroupNode.js'; import { nodeObject, getConstNodeType } from '../tsl/TSLCore.js'; +/** @module UniformNode **/ + /** * Class for representing a uniform. * @@ -156,6 +158,14 @@ class UniformNode extends InputNode { export default UniformNode; +/** + * TSL function for creating a uniform node with the given paramters. + * + * @function + * @param {Any} arg1 - The value of this node. Usually a JS primitive or three.js object (vector, matrix, color, texture). + * @param {String?} arg2 - The node type. If no explicit type is defined, the node tries to derive the type from its value. + * @returns {UniformNode} + */ export const uniform = ( arg1, arg2 ) => { const nodeType = getConstNodeType( arg2 || arg1 ); diff --git a/src/nodes/core/VarNode.js b/src/nodes/core/VarNode.js index b7ded3ad24def5..9441703b27c343 100644 --- a/src/nodes/core/VarNode.js +++ b/src/nodes/core/VarNode.js @@ -1,6 +1,8 @@ import Node from './Node.js'; import { addMethodChaining, nodeProxy } from '../tsl/TSLCore.js'; +/** @module VarNode **/ + /** * Class for representing shader variables as nodes. Variables are created from * existing nodes like the following: @@ -96,6 +98,14 @@ class VarNode extends Node { export default VarNode; +/** + * TSL function for creating a var node with the given paramters. + * + * @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} + */ const createVar = /*@__PURE__*/ nodeProxy( VarNode ); addMethodChaining( 'toVar', ( ...params ) => createVar( ...params ).append() ); diff --git a/src/nodes/core/VaryingNode.js b/src/nodes/core/VaryingNode.js index 448c844a790772..8662f46258784d 100644 --- a/src/nodes/core/VaryingNode.js +++ b/src/nodes/core/VaryingNode.js @@ -2,6 +2,8 @@ import Node from './Node.js'; import { NodeShaderStage } from './constants.js'; import { addMethodChaining, nodeProxy } from '../tsl/TSLCore.js'; +/** @module VaryingNode **/ + /** * Class for representing shader varyings as nodes. Varyings are create from * existing nodes like the following: @@ -151,6 +153,14 @@ class VaryingNode extends Node { export default VaryingNode; +/** + * TSL function for creating a varying node with the given paramters. + * + * @function + * @param {Node} node - The node for which a varying should be created. + * @param {String?} name - The name of the varying in the shader. + * @returns {VaryingNode} + */ export const varying = /*@__PURE__*/ nodeProxy( VaryingNode ); addMethodChaining( 'varying', varying ); diff --git a/src/nodes/core/constants.js b/src/nodes/core/constants.js index 5c3706d6dfbda0..d4cba7169e7614 100644 --- a/src/nodes/core/constants.js +++ b/src/nodes/core/constants.js @@ -1,3 +1,5 @@ +/** @module NodeConstants **/ + /** * Possible shader stages. * diff --git a/src/nodes/display/ColorSpaceNode.js b/src/nodes/display/ColorSpaceNode.js index 40bd3f34a94cbe..e087593c652a4b 100644 --- a/src/nodes/display/ColorSpaceNode.js +++ b/src/nodes/display/ColorSpaceNode.js @@ -6,6 +6,8 @@ import { ColorManagement } from '../../math/ColorManagement.js'; import { sRGBTransferEOTF, sRGBTransferOETF } from './ColorSpaceFunctions.js'; import { Matrix3 } from '../../math/Matrix3.js'; +/** @module ColorSpaceNode **/ + const WORKING_COLOR_SPACE = 'WorkingColorSpace'; const OUTPUT_COLOR_SPACE = 'OutputColorSpace'; @@ -126,12 +128,53 @@ class ColorSpaceNode extends TempNode { export default ColorSpaceNode; +/** + * TSL function for converting a given color node to the current output color space. + * + * @function + * @param {Node} node - Represents the node to convert. + * @returns {ColorSpaceNode} + */ export const toOutputColorSpace = ( node ) => nodeObject( new ColorSpaceNode( nodeObject( node ), WORKING_COLOR_SPACE, OUTPUT_COLOR_SPACE ) ); + +/** + * TSL function for converting a given color node to the current working color space. + * + * @function + * @param {Node} node - Represents the node to convert. + * @returns {ColorSpaceNode} + */ export const toWorkingColorSpace = ( node ) => nodeObject( new ColorSpaceNode( nodeObject( node ), OUTPUT_COLOR_SPACE, WORKING_COLOR_SPACE ) ); +/** + * TSL function for converting a given color node from the current working color space to the given color space. + * + * @function + * @param {Node} node - Represents the node to convert. + * @param {String} colorSpace - The target color space. + * @returns {ColorSpaceNode} + */ export const workingToColorSpace = ( node, colorSpace ) => nodeObject( new ColorSpaceNode( nodeObject( node ), WORKING_COLOR_SPACE, colorSpace ) ); + +/** + * TSL function for converting a given color node from the given color space to the current working color space. + * + * @function + * @param {Node} node - Represents the node to convert. + * @param {String} colorSpace - The source color space. + * @returns {ColorSpaceNode} + */ export const colorSpaceToWorking = ( node, colorSpace ) => nodeObject( new ColorSpaceNode( nodeObject( node ), colorSpace, WORKING_COLOR_SPACE ) ); +/** + * TSL function for converting a given color node from one color space to another one. + * + * @function + * @param {Node} node - Represents the node to convert. + * @param {String} sourceColorSpace - The source color space. + * @param {String} targetColorSpace - The target color space. + * @returns {ColorSpaceNode} + */ export const convertColorSpace = ( node, sourceColorSpace, targetColorSpace ) => nodeObject( new ColorSpaceNode( nodeObject( node ), sourceColorSpace, targetColorSpace ) ); addMethodChaining( 'toOutputColorSpace', toOutputColorSpace ); diff --git a/src/nodes/display/FrontFacingNode.js b/src/nodes/display/FrontFacingNode.js index 0330d59f414a68..884b976743d9d6 100644 --- a/src/nodes/display/FrontFacingNode.js +++ b/src/nodes/display/FrontFacingNode.js @@ -3,6 +3,8 @@ import { nodeImmutable, float } from '../tsl/TSLBase.js'; import { BackSide, WebGLCoordinateSystem } from '../../constants.js'; +/** @module FrontFacingNode **/ + /** * This node can be used to evaluate whether a primitive is front or back facing. * @@ -56,5 +58,17 @@ class FrontFacingNode extends Node { export default FrontFacingNode; +/** + * TSL object that represents whether a primitive is front or back facing + * + * @type {FrontFacingNode} + */ export const frontFacing = /*@__PURE__*/ nodeImmutable( FrontFacingNode ); + +/** + * TSL object that represents the front facing status as a number instead of a bool. + * `1` means front facing, `-1` means back facing. + * + * @type {Node} + */ export const faceDirection = /*@__PURE__*/ float( frontFacing ).mul( 2.0 ).sub( 1.0 ); diff --git a/src/nodes/display/NormalMapNode.js b/src/nodes/display/NormalMapNode.js index 8e4348b1d82470..97e17e2d42d2ac 100644 --- a/src/nodes/display/NormalMapNode.js +++ b/src/nodes/display/NormalMapNode.js @@ -10,6 +10,8 @@ import { Fn, nodeProxy, vec3 } from '../tsl/TSLBase.js'; import { TangentSpaceNormalMap, ObjectSpaceNormalMap } from '../../constants.js'; +/** @module NormalMapNode **/ + // Normal Mapping Without Precomputed Tangents // http://www.thetenthplanet.de/archives/1180 @@ -136,4 +138,12 @@ class NormalMapNode extends TempNode { export default NormalMapNode; +/** + * TSL function for creating a normal map node with the given paramters. + * + * @function + * @param {Node} node - Represents the normal map data. + * @param {Node?} [scaleNode=null] - Controls the intensity of the effect. + * @returns {NormalMapNode} + */ export const normalMap = /*@__PURE__*/ nodeProxy( NormalMapNode ); diff --git a/src/nodes/display/PassNode.js b/src/nodes/display/PassNode.js index 5ae3af0a001059..5e7b2857d90883 100644 --- a/src/nodes/display/PassNode.js +++ b/src/nodes/display/PassNode.js @@ -10,13 +10,14 @@ import { Vector2 } from '../../math/Vector2.js'; import { DepthTexture } from '../../textures/DepthTexture.js'; import { RenderTarget } from '../../core/RenderTarget.js'; +/** @module PassNode **/ + const _size = /*@__PURE__*/ new Vector2(); /** * Represents the texture of a pass node. * * @augments TextureNode - * @private */ class PassTextureNode extends TextureNode { @@ -68,7 +69,6 @@ class PassTextureNode extends TextureNode { * internal texture. Relevant for the `getPreviousTexture()` related API. * * @augments PassTextureNode - * @private */ class PassMultipleTextureNode extends PassTextureNode { @@ -638,6 +638,33 @@ PassNode.DEPTH = 'depth'; export default PassNode; +/** + * TSL function for creating a pass node with the given paramters. + * + * @function + * @param {Scene} scene - A reference to the scene. + * @param {Camera} camera - A reference to the camera. + * @param {Object} options - Options for the internal render target. + * @returns {PassNode} + */ export const pass = ( scene, camera, options ) => nodeObject( new PassNode( PassNode.COLOR, scene, camera, options ) ); + +/** + * TSL function for creating a pass texture node with the given paramters. + * + * @function + * @param {PassNode} pass - The pass node. + * @param {Texture} texture - The output texture. + * @returns {PassTextureNode} + */ export const passTexture = ( pass, texture ) => nodeObject( new PassTextureNode( pass, texture ) ); + +/** + * TSL function for creating a depth pass node with the given paramters. + * + * @function + * @param {Scene} scene - A reference to the scene. + * @param {Camera} camera - A reference to the camera. + * @returns {PassNode} + */ export const depthPass = ( scene, camera ) => nodeObject( new PassNode( PassNode.DEPTH, scene, camera ) ); diff --git a/src/nodes/display/PosterizeNode.js b/src/nodes/display/PosterizeNode.js index ef6d95d64e727f..930f07a928b4e6 100644 --- a/src/nodes/display/PosterizeNode.js +++ b/src/nodes/display/PosterizeNode.js @@ -1,6 +1,8 @@ import TempNode from '../core/TempNode.js'; import { nodeProxy } from '../tsl/TSLBase.js'; +/** @module PosterizeNode **/ + /** * Represents a posterize effect which reduces the number of colors * in an image, resulting in a more blocky and stylized appearance. @@ -53,4 +55,12 @@ class PosterizeNode extends TempNode { export default PosterizeNode; +/** + * TSL function for creating a posterize node with the given paramters. + * + * @function + * @param {Node} sourceNode - The input color. + * @param {Node} stepsNode - Controls the intensity of the posterization effect. A lower number results in a more blocky appearance. + * @returns {PosterizeNode} + */ export const posterize = /*@__PURE__*/ nodeProxy( PosterizeNode ); diff --git a/src/nodes/display/RenderOutputNode.js b/src/nodes/display/RenderOutputNode.js index ecbcfe85c019f0..bd22935409f1ec 100644 --- a/src/nodes/display/RenderOutputNode.js +++ b/src/nodes/display/RenderOutputNode.js @@ -4,6 +4,8 @@ import { addMethodChaining, nodeObject } from '../tsl/TSLCore.js'; import { NoColorSpace, NoToneMapping } from '../../constants.js'; import { ColorManagement } from '../../math/ColorManagement.js'; +/** @module RenderOutputNode **/ + /** * Normally, tone mapping and color conversion happens automatically * before outputting pixel too the default (screen) framebuffer. In certain @@ -109,6 +111,15 @@ class RenderOutputNode extends TempNode { export default RenderOutputNode; +/** + * TSL function for creating a posterize node with the given paramters. + * + * @function + * @param {Node} color - The color node to process. + * @param {String?} [toneMapping=null] - The tone mapping type. + * @param {String?} [outputColorSpace=null] - The output color space. + * @returns {RenderOutputNode} + */ export const renderOutput = ( color, toneMapping = null, outputColorSpace = null ) => nodeObject( new RenderOutputNode( nodeObject( color ), toneMapping, outputColorSpace ) ); addMethodChaining( 'renderOutput', renderOutput ); diff --git a/src/nodes/geometry/RangeNode.js b/src/nodes/geometry/RangeNode.js index a7f8c2995774f3..61b7e18720f95a 100644 --- a/src/nodes/geometry/RangeNode.js +++ b/src/nodes/geometry/RangeNode.js @@ -9,6 +9,8 @@ import { Vector4 } from '../../math/Vector4.js'; import { MathUtils } from '../../math/MathUtils.js'; import { InstancedBufferAttribute } from '../../core/InstancedBufferAttribute.js'; +/** @module RangeNode **/ + let min = null; let max = null; @@ -160,4 +162,12 @@ class RangeNode extends Node { export default RangeNode; +/** + * TSL function for creating a range node with the given paramters. + * + * @function + * @param {Node} [minNode=float()] - A node defining the lower bound of the range. + * @param {Node} [maxNode=float()] - A node defining the upper bound of the range. + * @returns {RangeNode} + */ export const range = /*@__PURE__*/ nodeProxy( RangeNode ); diff --git a/src/nodes/lighting/LightsNode.js b/src/nodes/lighting/LightsNode.js index 7e601de752809f..55299ad1ff35a8 100644 --- a/src/nodes/lighting/LightsNode.js +++ b/src/nodes/lighting/LightsNode.js @@ -382,10 +382,10 @@ class LightsNode extends Node { export default LightsNode; /** - * Factory method for creating an instance of `LightsNode` and configuring + * TSL function for creating an instance of `LightsNode` and configuring * it with the given array of lights. * - * @method + * @function * @param {Array} lights - An array of lights. * @return {LightsNode} The created lights node. */ diff --git a/src/nodes/lighting/PointShadowNode.js b/src/nodes/lighting/PointShadowNode.js index f2d236ee09e207..f15b55489686d2 100644 --- a/src/nodes/lighting/PointShadowNode.js +++ b/src/nodes/lighting/PointShadowNode.js @@ -11,6 +11,8 @@ import { Vector4 } from '../../math/Vector4.js'; import { Color } from '../../math/Color.js'; import { BasicShadowMap } from '../../constants.js'; +/** @module PointShadowNode **/ + const _clearColor = /*@__PURE__*/ new Color(); // cubeToUV() maps a 3D direction vector suitable for cube texture mapping to a 2D @@ -157,8 +159,12 @@ const _viewport = /*@__PURE__*/ new Vector4(); const _viewportSize = /*@__PURE__*/ new Vector2(); const _shadowMapSize = /*@__PURE__*/ new Vector2(); -// +/** + * Represents the shadow implementation for point light nodes. + * + * @augments ShadowNode + */ class PointShadowNode extends ShadowNode { static get type() { @@ -167,30 +173,68 @@ class PointShadowNode extends ShadowNode { } + /** + * Constructs a new point shadow node. + * + * @param {PointLight} light - The shadow casting point light. + * @param {PointLightShadow?} [shadow=null] - An optional point light shadow. + */ constructor( light, shadow = null ) { super( light, shadow ); } + /** + * Overwrites the default implementation to return point light shadow specific + * filtering functions. + * + * @param {Number} type - The shadow type. + * @return {Function} The filtering function. + */ getShadowFilterFn( type ) { return type === BasicShadowMap ? BasicPointShadowFilter : PointShadowFilter; } + /** + * Overwrites the default implementation so the unaltered shadow position is used. + * + * @param {NodeBuilder} builder - A reference to the current node builder. + * @param {Node} shadowPosition - A node representing the shadow position. + * @return {Node} The shadow coordinates. + */ setupShadowCoord( builder, shadowPosition ) { return shadowPosition; } + /** + * Overwrites the default implementation to only use point light specific + * shadow filter functions. + * + * @param {NodeBuilder} builder - A reference to the current node builder. + * @param {Object} inputs - A configuration object that defines the shadow filtering. + * @param {Function} inputs.filterFn - This function defines the filtering type of the shadow map e.g. PCF. + * @param {DepthTexture} inputs.depthTexture - A reference to the shadow map's texture data. + * @param {Node} inputs.shadowCoord - Shadow coordinates which are used to sample from the shadow map. + * @param {LightShadow} inputs.shadow - The light shadow. + * @return {Node} The result node of the shadow filtering. + */ setupShadowFilter( builder, { filterFn, shadowTexture, depthTexture, shadowCoord, shadow } ) { return pointShadowFilter( { filterFn, shadowTexture, depthTexture, shadowCoord, shadow } ); } + /** + * Overwrites the default implementation with point light specific + * rendering code. + * + * @param {NodeFrme} frame - A reference to the current node frame. + */ renderShadow( frame ) { const { shadow, shadowMap, light } = this; @@ -251,4 +295,12 @@ class PointShadowNode extends ShadowNode { export default PointShadowNode; +/** + * TSL function for creating an instance of `PointShadowNode`. + * + * @function + * @param {PointLight} light - The shadow casting point light. + * @param {PointLightShadow?} [shadow=null] - An optional point light shadow. + * @return {PointShadowNode} The created point shadow node. + */ export const pointShadow = ( light, shadow ) => nodeObject( new PointShadowNode( light, shadow ) ); diff --git a/src/nodes/lighting/ShadowBaseNode.js b/src/nodes/lighting/ShadowBaseNode.js index ccb5c64776f551..b8e7dc0a191ac0 100644 --- a/src/nodes/lighting/ShadowBaseNode.js +++ b/src/nodes/lighting/ShadowBaseNode.js @@ -84,7 +84,7 @@ class ShadowBaseNode extends Node { } /** - * Represents the vertex position in world space during the shadow pass. + * TSL object that represents the vertex position in world space during the shadow pass. * * @type {Node} */ diff --git a/src/nodes/lighting/ShadowNode.js b/src/nodes/lighting/ShadowNode.js index b3b0e034028f3a..09f4f88ffb38c6 100644 --- a/src/nodes/lighting/ShadowNode.js +++ b/src/nodes/lighting/ShadowNode.js @@ -17,6 +17,8 @@ import { viewZToLogarithmicDepth } from '../display/ViewportDepthNode.js'; import { objectPosition } from '../accessors/Object3DNode.js'; import { lightShadowMatrix } from '../accessors/Lights.js'; +/** @module ShadowNode **/ + const shadowMaterialLib = /*@__PURE__*/ new WeakMap(); const linearDistance = /*@__PURE__*/ Fn( ( [ position, cameraNear, cameraFar ] ) => { @@ -63,8 +65,6 @@ const getShadowMaterial = ( light ) => { }; -/** @module ShadowNode **/ - /** * A shadow filtering function performing basic filtering. This is in fact an unfiltered version of the shadow map * with a binary `[0,1]` result. @@ -784,9 +784,9 @@ class ShadowNode extends ShadowBaseNode { export default ShadowNode; /** - * Factory method for creating an instance of `ShadowNode`. + * TSL function for creating an instance of `ShadowNode`. * - * @method + * @function * @param {Light} light - The shadow casting light. * @param {LightShadow} shadow - The light shadow. * @return {ShadowNode} The created shadow node. diff --git a/src/nodes/pmrem/PMREMNode.js b/src/nodes/pmrem/PMREMNode.js index a72dbaec579b1a..a11b6805a9e910 100644 --- a/src/nodes/pmrem/PMREMNode.js +++ b/src/nodes/pmrem/PMREMNode.js @@ -8,6 +8,8 @@ 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(); @@ -359,4 +361,13 @@ function isEquirectangularMapReady( image ) { } +/** + * TSL function for creating a PMREM node with the given paramters. + * + * @function + * @param {Texture} value - The input texture. + * @param {Node} [uvNode=null] - The uv node. + * @param {Node} [levelNode=null] - The level node. + * @returns {PMREMNode} + */ export const pmremTexture = /*@__PURE__*/ nodeProxy( PMREMNode );