three
Version:
JavaScript 3D library
3,475 lines • 78.4 kB
JavaScript
import NodeUniform from './NodeUniform.js';
import NodeAttribute from './NodeAttribute.js';
import NodeVarying from './NodeVarying.js';
import NodeVar from './NodeVar.js';
import NodeCode from './NodeCode.js';
import NodeCache from './NodeCache.js';
import ParameterNode from './ParameterNode.js';
import StructType from './StructType.js';
import FunctionNode from '../code/FunctionNode.js';
import NodeMaterial from '../../materials/nodes/NodeMaterial.js';
import { getDataFromObject, getTypeFromLength, getTextureType, hashString } from './NodeUtils.js';
import { NodeUpdateType, defaultBuildStages, shaderStages } from './constants.js';
import {
NumberNodeUniform, Vector2NodeUniform, Vector3NodeUniform, Vector4NodeUniform,
ColorNodeUniform, Matrix2NodeUniform, Matrix3NodeUniform, Matrix4NodeUniform
} from '../../renderers/common/nodes/NodeUniform.js';
import { stack } from './StackNode.js';
import { getCurrentStack, setCurrentStack } from '../tsl/TSLBase.js';
import CubeRenderTarget from '../../renderers/common/CubeRenderTarget.js';
import BindGroup from '../../renderers/common/BindGroup.js';
import { REVISION, IntType, UnsignedIntType, LinearFilter, LinearMipmapNearestFilter, NearestMipmapLinearFilter, LinearMipmapLinearFilter, NormalBlending } from '../../constants.js';
import { RenderTarget } from '../../core/RenderTarget.js';
import { Color } from '../../math/Color.js';
import { Vector2 } from '../../math/Vector2.js';
import { Vector3 } from '../../math/Vector3.js';
import { Vector4 } from '../../math/Vector4.js';
import { Float16BufferAttribute } from '../../core/BufferAttribute.js';
import { warn, error, yieldToMain } from '../../utils.js';
let _id = 0;
const _bindingGroupsCache = new WeakMap();
const _functionNodeCache = new WeakMap();
const sharedNodeData = new WeakMap();
const typeFromArray = new Map( [
[ Int8Array, 'int' ],
[ Int16Array, 'int' ],
[ Int32Array, 'int' ],
[ Uint8Array, 'uint' ],
[ Uint16Array, 'uint' ],
[ Uint32Array, 'uint' ],
[ Float32Array, 'float' ]
] );
const _toFloat = ( value ) => {
if ( /e/g.test( value ) ) {
return String( value ).replace( /\+/g, '' );
} else {
value = Number( value );
return value + ( value % 1 ? '' : '.0' );
}
};
const _checkWriteUsage = ( data ) => {
if ( data.writeUsageCount > 0 ) return true;
if ( data.subBuildsCache !== undefined ) {
for ( const subBuild in data.subBuildsCache ) {
if ( _checkWriteUsage( data.subBuildsCache[ subBuild ] ) ) {
return true;
}
}
}
return false;
};
/**
* Base class for builders which generate a shader program based
* on a 3D object and its node material definition.
*/
class NodeBuilder {
/**
* Constructs a new node builder.
*
* @param {Object3D} object - The 3D object.
* @param {Renderer} renderer - The current renderer.
* @param {NodeParser} parser - A reference to a node parser.
*/
constructor( object, renderer, parser ) {
/**
* The 3D object.
*
* @type {Object3D}
*/
this.object = object;
/**
* The material of the 3D object.
*
* @type {?Material}
*/
this.material = ( object && object.material ) || null;
/**
* The geometry of the 3D object.
*
* @type {?BufferGeometry}
*/
this.geometry = ( object && object.geometry ) || null;
/**
* The compute node, if building for compute.
*
* @type {?ComputeNode}
* @default null
*/
this.compute = null;
/**
* The current renderer.
*
* @type {Renderer}
*/
this.renderer = renderer;
/**
* A reference to a node parser.
*
* @type {NodeParser}
*/
this.parser = parser;
/**
* The scene the 3D object belongs to.
*
* @type {?Scene}
* @default null
*/
this.scene = null;
/**
* The camera the 3D object is rendered with.
*
* @type {?Camera}
* @default null
*/
this.camera = null;
/**
* A list of all nodes the builder is processing
* for this 3D object.
*
* @type {Set<Node>}
*/
this.nodes = new Set();
/**
* A list of all nodes the builder is processing in sequential order.
*
* This is used to determine the update order of nodes, which is important for
* {@link NodeUpdateType#UPDATE_BEFORE} and {@link NodeUpdateType#UPDATE_AFTER}.
*
* @type {Set<Node>}
*/
this.sequentialNodes = new Set();
/**
* A list of all nodes which {@link Node#update} method should be executed.
*
* @type {Array<Node>}
*/
this.updateNodes = [];
/**
* A list of all nodes which {@link Node#updateBefore} method should be executed.
*
* @type {Array<Node>}
*/
this.updateBeforeNodes = [];
/**
* A list of all nodes which {@link Node#updateAfter} method should be executed.
*
* @type {Array<Node>}
*/
this.updateAfterNodes = [];
/**
* A dictionary that assigns each node to a unique hash.
*
* @type {Object<number,Node>}
*/
this.hashNodes = {};
/**
* A reference to a node material observer.
*
* @type {?NodeMaterialObserver}
* @default null
*/
this.observer = null;
/**
* A reference to the current lights node.
*
* @type {?LightsNode}
* @default null
*/
this.lightsNode = null;
/**
* A reference to the current environment node.
*
* @type {?Node}
* @default null
*/
this.environmentNode = null;
/**
* A reference to the current fog node.
*
* @type {?Node}
* @default null
*/
this.fogNode = null;
/**
* The current clipping context.
*
* @type {?ClippingContext}
*/
this.clippingContext = null;
/**
* Whether the built material uses hardware clipping or not.
*
* @type {boolean}
* @default false
*/
this.hardwareClipping = false;
/**
* The generated vertex shader.
*
* @type {?string}
*/
this.vertexShader = null;
/**
* The generated fragment shader.
*
* @type {?string}
*/
this.fragmentShader = null;
/**
* The generated compute shader.
*
* @type {?string}
*/
this.computeShader = null;
/**
* Nodes used in the primary flow of code generation.
*
* @type {Object<string,Array<Node>>}
*/
this.flowNodes = { vertex: [], fragment: [], compute: [] };
/**
* Nodes code from `.flowNodes`.
*
* @type {Object<string,string>}
*/
this.flowCode = { vertex: '', fragment: '', compute: '' };
/**
* This dictionary holds the node uniforms of the builder.
* The uniforms are maintained in an array for each shader stage.
*
* @type {Object}
*/
this.uniforms = { vertex: [], fragment: [], compute: [], index: 0 };
/**
* This dictionary holds the output structs of the builder.
* The structs are maintained in an array for each shader stage.
*
* @type {Object}
*/
this.structs = { vertex: [], fragment: [], compute: [], index: 0 };
/**
* This dictionary holds the types of the builder.
*
* @type {Object}
*/
this.types = { vertex: [], fragment: [], compute: [], index: 0 };
/**
* This dictionary holds the bindings for each shader stage.
*
* @type {Object}
*/
this.bindings = { vertex: {}, fragment: {}, compute: {} };
/**
* This dictionary maintains the binding indices per bind group.
*
* @type {Object}
*/
this.bindingsIndexes = {};
/**
* Reference to the array of bind groups.
*
* @type {?Array<BindGroup>}
*/
this.bindGroups = null;
/**
* This array holds the node attributes of this builder
* created via {@link AttributeNode}.
*
* @type {Array<NodeAttribute>}
*/
this.attributes = [];
/**
* This array holds the node attributes of this builder
* created via {@link BufferAttributeNode}.
*
* @type {Array<NodeAttribute>}
*/
this.bufferAttributes = [];
/**
* This array holds the node varyings of this builder.
*
* @type {Array<NodeVarying>}
*/
this.varyings = [];
/**
* This dictionary holds the (native) node codes of this builder.
* The codes are maintained in an array for each shader stage.
*
* @type {Object<string,Array<NodeCode>>}
*/
this.codes = {};
/**
* This dictionary holds the node variables of this builder.
* The variables are maintained in an array for each shader stage.
* This dictionary is also used to count the number of variables
* according to their type (const, vars).
*
* @type {Object<string,Array<NodeVar>|number>}
*/
this.vars = {};
/**
* This dictionary holds the declarations for each shader stage.
*
* @type {Object}
*/
this.declarations = {};
/**
* Current code flow.
* All code generated in this stack will be stored in `.flow`.
*
* @type {{code: string}}
*/
this.flow = { code: '' };
/**
* A chain of nodes.
* Used to check recursive calls in node-graph.
*
* @type {Array<Node>}
*/
this.chaining = [];
/**
* The current stack.
* This reflects the current process in the code block hierarchy,
* it is useful to know if the current process is inside a conditional for example.
*
* @type {StackNode}
*/
this.stack = stack();
/**
* List of stack nodes.
* The current stack hierarchy is stored in an array.
*
* @type {Array<StackNode>}
*/
this.stacks = [];
/**
* A tab value. Used for shader string generation.
*
* @type {string}
* @default '\t'
*/
this.tab = '\t';
/**
* Reference to the current function node.
*
* @type {?FunctionNode}
* @default null
*/
this.currentFunctionNode = null;
/**
* The builder's context.
*
* @type {Object}
*/
this.context = {
material: this.material
};
/**
* The builder's cache.
*
* @type {NodeCache}
*/
this.cache = new NodeCache();
/**
* Since the {@link NodeBuilder#cache} might be temporarily
* overwritten by other caches, this member retains the reference
* to the builder's own cache.
*
* @type {NodeCache}
* @default this.cache
*/
this.globalCache = this.cache;
this.flowsData = new WeakMap();
/**
* The current shader stage.
*
* @type {?('vertex'|'fragment'|'compute'|'any')}
*/
this.shaderStage = null;
/**
* The current build stage.
*
* @type {?('setup'|'analyze'|'generate')}
*/
this.buildStage = null;
/**
* The sub-build layers.
*
* @type {Array<SubBuildNode>}
* @default []
*/
this.subBuildLayers = [];
/**
* The active stack nodes.
*
* @type {Array<StackNode>}
*/
this.activeStacks = [];
/**
* The current sub-build TSL function(Fn).
*
* @type {?string}
* @default null
*/
this.subBuildFn = null;
/**
* The current TSL function(Fn) call node.
*
* @type {?Node}
* @default null
*/
this.fnCall = null;
Object.defineProperty( this, 'id', { value: _id ++ } );
}
/**
* Whether the material is using flat shading or not.
*
* @returns {boolean} Whether the material is using flat shading or not.
*/
isFlatShading() {
return this.material.flatShading === true || this.geometry.hasAttribute( 'normal' ) === false;
}
/**
* Whether the material is opaque or not.
*
* @return {boolean} Whether the material is opaque or not.
*/
isOpaque() {
const material = this.material;
return material.transparent === false && material.blending === NormalBlending && material.alphaToCoverage === false;
}
/**
* Factory method for creating an instance of {@link RenderTarget} with the given
* dimensions and options.
*
* @param {number} width - The width of the render target.
* @param {number} height - The height of the render target.
* @param {Object} options - The options of the render target.
* @return {RenderTarget} The render target.
*/
createRenderTarget( width, height, options ) {
return new RenderTarget( width, height, options );
}
/**
* Factory method for creating an instance of {@link CubeRenderTarget} with the given
* dimensions and options.
*
* @param {number} size - The size of the cube render target.
* @param {Object} options - The options of the cube render target.
* @return {CubeRenderTarget} The cube render target.
*/
createCubeRenderTarget( size, options ) {
return new CubeRenderTarget( size, options );
}
/**
* Whether the given node is included in the internal array of nodes or not.
*
* @param {Node} node - The node to test.
* @return {boolean} Whether the given node is included in the internal array of nodes or not.
*/
includes( node ) {
return this.nodes.has( node );
}
/**
* Returns the type of the color output based on the renderer's render target.
*
* @param {number} [index=0] - The index of the render target texture.
* @return {string} The type.
*/
getOutputType( index = 0 ) {
const renderTarget = this.renderer.getRenderTarget();
if ( renderTarget !== null ) {
return getTextureType( renderTarget.textures[ index ] );
}
return 'vec4';
}
/**
* Returns the output struct name which is required by
* {@link OutputStructNode}.
*
* @abstract
* @return {string} The name of the output struct.
*/
getOutputStructName() {}
/**
* Returns a bind group for the given group name and binding.
*
* @private
* @param {string} groupName - The group name.
* @param {Array<NodeUniformsGroup>} bindings - List of bindings.
* @return {BindGroup} The bind group
*/
_getBindGroup( groupName, bindings ) {
const groupNode = bindings[ 0 ].groupNode;
let sharedGroup = groupNode.shared;
if ( sharedGroup ) {
for ( let i = 1; i < bindings.length; i ++ ) {
if ( groupNode !== bindings[ i ].groupNode ) {
sharedGroup = false;
}
}
}
//
let bindGroup;
if ( sharedGroup ) {
let cacheKeyString = '';
for ( const binding of bindings ) {
if ( binding.isNodeUniformsGroup ) {
binding.uniforms.sort( ( a, b ) => a.nodeUniform.node.id - b.nodeUniform.node.id );
for ( const uniform of binding.uniforms ) {
cacheKeyString += uniform.nodeUniform.node.id;
}
} else {
cacheKeyString += binding.nodeUniform.id;
}
}
// TODO: Remove this hack ._currentRenderContext
const currentContext = this.renderer._currentRenderContext || this.renderer; // use renderer as fallback until we have a compute context
let bindingGroupsCache = _bindingGroupsCache.get( currentContext );
if ( bindingGroupsCache === undefined ) {
bindingGroupsCache = new Map();
_bindingGroupsCache.set( currentContext, bindingGroupsCache );
}
//
const cacheKey = hashString( cacheKeyString );
bindGroup = bindingGroupsCache.get( cacheKey );
if ( bindGroup === undefined ) {
bindGroup = new BindGroup( groupName, bindings );
bindingGroupsCache.set( cacheKey, bindGroup );
}
} else {
bindGroup = new BindGroup( groupName, bindings );
}
return bindGroup;
}
/**
* Returns an array of node uniform groups for the given group name and shader stage.
*
* @param {string} groupName - The group name.
* @param {('vertex'|'fragment'|'compute'|'any')} shaderStage - The shader stage.
* @return {Array<NodeUniformsGroup>} The array of node uniform groups.
*/
getBindGroupArray( groupName, shaderStage ) {
const bindings = this.bindings[ shaderStage ];
let bindGroup = bindings[ groupName ];
if ( bindGroup === undefined ) {
if ( this.bindingsIndexes[ groupName ] === undefined ) {
this.bindingsIndexes[ groupName ] = { binding: 0, group: Object.keys( this.bindingsIndexes ).length };
}
bindings[ groupName ] = bindGroup = [];
}
return bindGroup;
}
/**
* Returns a list bindings of all shader stages separated by groups.
*
* @return {Array<BindGroup>} The list of bindings.
*/
getBindings() {
let bindingsGroups = this.bindGroups;
if ( bindingsGroups === null ) {
const groups = {};
const bindings = this.bindings;
for ( const shaderStage of shaderStages ) {
for ( const groupName in bindings[ shaderStage ] ) {
const uniforms = bindings[ shaderStage ][ groupName ];
const groupUniforms = groups[ groupName ] || ( groups[ groupName ] = [] );
for ( const uniform of uniforms ) {
if ( groupUniforms.includes( uniform ) === false ) {
groupUniforms.push( uniform );
}
}
}
}
bindingsGroups = [];
for ( const groupName in groups ) {
const group = groups[ groupName ];
const bindingsGroup = this._getBindGroup( groupName, group );
bindingsGroups.push( bindingsGroup );
}
this.bindGroups = bindingsGroups;
}
return bindingsGroups;
}
/**
* Sorts the bind groups and updates {@link NodeBuilder#bindingsIndexes}.
*/
sortBindingGroups() {
const bindingsGroups = this.getBindings();
bindingsGroups.sort( ( a, b ) => ( a.bindings[ 0 ].groupNode.order - b.bindings[ 0 ].groupNode.order ) );
for ( let i = 0; i < bindingsGroups.length; i ++ ) {
const bindingGroup = bindingsGroups[ i ];
this.bindingsIndexes[ bindingGroup.name ].group = i;
}
}
/**
* The builder maintains each node in a hash-based dictionary.
* This method sets the given node (value) with the given hash (key) into this dictionary.
*
* @param {Node} node - The node to add.
* @param {number} hash - The hash of the node.
*/
setHashNode( node, hash ) {
this.hashNodes[ hash ] = node;
}
/**
* Adds a node to this builder.
*
* @param {Node} node - The node to add.
*/
addNode( node ) {
if ( this.nodes.has( node ) === false ) {
this.nodes.add( node );
this.setHashNode( node, node.getHash( this ) );
}
}
/**
* It is used to add Nodes that will be used as FRAME and RENDER events,
* and need to follow a certain sequence in the calls to work correctly.
* This function should be called after 'setup()' in the 'build()' process to ensure that the child nodes are processed first.
*
* @param {Node} node - The node to add.
*/
addSequentialNode( node ) {
const updateBeforeType = node.updateBeforeType;
const updateAfterType = node.updateAfterType;
if ( updateBeforeType !== NodeUpdateType.NONE || updateAfterType !== NodeUpdateType.NONE ) {
this.sequentialNodes.add( node );
}
}
/**
* Checks the update types of nodes
*/
buildUpdateNodes() {
for ( const node of this.nodes ) {
const updateType = node.updateType;
if ( updateType !== NodeUpdateType.NONE ) {
this.updateNodes.push( node );
}
}
for ( const node of this.sequentialNodes ) {
const updateBeforeType = node.updateBeforeType;
const updateAfterType = node.updateAfterType;
if ( updateBeforeType !== NodeUpdateType.NONE ) {
this.updateBeforeNodes.push( node );
}
if ( updateAfterType !== NodeUpdateType.NONE ) {
this.updateAfterNodes.push( node );
}
}
}
/**
* A reference the current node which is the
* last node in the chain of nodes.
*
* @type {Node}
*/
get currentNode() {
return this.chaining[ this.chaining.length - 1 ];
}
/**
* A reference to the render pipeline.
*
* @type {RenderPipeline}
*/
get renderPipeline() {
return this.context.renderPipeline;
}
/**
* Whether the given texture is filtered or not.
*
* @param {Texture} texture - The texture to check.
* @return {boolean} Whether the given texture is filtered or not.
*/
isFilteredTexture( texture ) {
return ( texture.magFilter === LinearFilter || texture.magFilter === LinearMipmapNearestFilter || texture.magFilter === NearestMipmapLinearFilter || texture.magFilter === LinearMipmapLinearFilter ||
texture.minFilter === LinearFilter || texture.minFilter === LinearMipmapNearestFilter || texture.minFilter === NearestMipmapLinearFilter || texture.minFilter === LinearMipmapLinearFilter );
}
/**
* Returns the maximum number of bytes available for uniform buffers.
*
* @return {number} The maximum number of bytes available for uniform buffers.
*/
getUniformBufferLimit() {
return this.renderer.backend.capabilities.getUniformBufferLimit();
}
/**
* Adds the given node to the internal node chain.
* This is used to check recursive calls in node-graph.
*
* @param {Node} node - The node to add.
*/
addChain( node ) {
/*
if ( this.chaining.indexOf( node ) !== - 1 ) {
warn( 'Recursive node: ', node );
}
*/
this.chaining.push( node );
}
/**
* Removes the given node from the internal node chain.
*
* @param {Node} node - The node to remove.
*/
removeChain( node ) {
const lastChain = this.chaining.pop();
if ( lastChain !== node ) {
throw new Error( 'THREE.NodeBuilder: Invalid node chaining!' );
}
}
/**
* Returns the native shader method name for a given generic name. E.g.
* the method name `textureDimensions` matches the WGSL name but must be
* resolved to `textureSize` in GLSL.
*
* @abstract
* @param {string} method - The method name to resolve.
* @return {string} The resolved method name.
*/
getMethod( method ) {
return method;
}
/**
* Returns the native snippet for a ternary operation. E.g. GLSL would output
* a ternary op as `cond ? x : y` whereas WGSL would output it as `select(y, x, cond)`
*
* @abstract
* @param {string} condSnippet - The condition determining which expression gets resolved.
* @param {string} ifSnippet - The expression to resolve to if the condition is true.
* @param {string} elseSnippet - The expression to resolve to if the condition is false.
* @return {string} The resolved method name.
*/
getTernary( /* condSnippet, ifSnippet, elseSnippet*/ ) {
return null;
}
/**
* Returns a node for the given hash, see {@link NodeBuilder#setHashNode}.
*
* @param {number} hash - The hash of the node.
* @return {Node} The found node.
*/
getNodeFromHash( hash ) {
return this.hashNodes[ hash ];
}
/**
* Adds the Node to a target flow so that it can generate code in the 'generate' process.
*
* @param {('vertex'|'fragment'|'compute')} shaderStage - The shader stage.
* @param {Node} node - The node to add.
* @return {Node} The node.
*/
addFlow( shaderStage, node ) {
this.flowNodes[ shaderStage ].push( node );
return node;
}
/**
* Sets builder's context.
*
* @param {Object} context - The context to set.
*/
setContext( context ) {
this.context = context;
}
/**
* Returns the builder's current context.
*
* @return {Object} The builder's current context.
*/
getContext() {
return this.context;
}
/**
* Adds context data to the builder's current context.
*
* @param {Object} context - The context to add.
* @return {Object} The previous context.
*/
addContext( context ) {
const previousContext = this.getContext();
this.setContext( { ...this.context, ...context } );
return previousContext;
}
/**
* Gets a context used in shader construction that can be shared across different materials.
* This is necessary since the renderer cache can reuse shaders generated in one material and use them in another.
*
* @return {Object} The builder's current context without material.
*/
getSharedContext() {
const context = { ...this.context };
delete context.material;
delete context.getUV;
delete context.getOutput;
delete context.getTextureLevel;
delete context.getAO;
delete context.getGI;
delete context.getShadow;
return context;
}
/**
* Sets builder's cache.
*
* @param {NodeCache} cache - The cache to set.
*/
setCache( cache ) {
this.cache = cache;
}
/**
* Returns the builder's current cache.
*
* @return {NodeCache} The builder's current cache.
*/
getCache() {
return this.cache;
}
/**
* Returns a cache for the given node.
*
* @param {Node} node - The node.
* @param {boolean} [parent=true] - Whether this node refers to a shared parent cache or not.
* @return {NodeCache} The cache.
*/
getCacheFromNode( node, parent = true ) {
const data = this.getDataFromNode( node );
if ( data.cache === undefined ) data.cache = new NodeCache( parent ? this.getCache() : null );
return data.cache;
}
/**
* Whether the requested feature is available or not.
*
* @abstract
* @param {string} name - The requested feature.
* @return {boolean} Whether the requested feature is supported or not.
*/
isAvailable( /*name*/ ) {
return false;
}
/**
* Returns the vertexIndex input variable as a native shader string.
*
* @abstract
* @return {string} The instanceIndex shader string.
*/
getVertexIndex() {
warn( 'Abstract function.' );
}
/**
* Contextually returns either the vertex stage instance index builtin
* or the linearized index of an compute invocation within a grid of workgroups.
*
* @abstract
* @return {string} The instanceIndex shader string.
*/
getInstanceIndex() {
warn( 'Abstract function.' );
}
/**
* Returns the drawIndex input variable as a native shader string.
* Only relevant for WebGL and its `WEBGL_multi_draw` extension.
*
* @abstract
* @return {?string} The drawIndex shader string.
*/
getDrawIndex() {
warn( 'Abstract function.' );
}
/**
* Returns the frontFacing input variable as a native shader string.
*
* @abstract
* @return {string} The frontFacing shader string.
*/
getFrontFacing() {
warn( 'Abstract function.' );
}
/**
* Returns the fragCoord input variable as a native shader string.
*
* @abstract
* @return {string} The fragCoord shader string.
*/
getFragCoord() {
warn( 'Abstract function.' );
}
/**
* Whether to flip texture data along its vertical axis or not. WebGL needs
* this method evaluate to `true`, WebGPU to `false`.
*
* @abstract
* @return {boolean} Whether to flip texture data along its vertical axis or not.
*/
isFlipY() {
return false;
}
/**
* Returns whether the builder is currently in an assignment context.
*
* @return {boolean} Whether the builder is in an assignment context.
*/
isContextAssign() {
return this.context.assign === true;
}
/**
* Calling this method increases the usage count for the given node by one.
*
* @param {Node} node - The node to increase the usage count for.
* @return {number} The updated usage count.
*/
increaseUsage( node ) {
const nodeData = this.getDataFromNode( node );
nodeData.usageCount = nodeData.usageCount === undefined ? 1 : nodeData.usageCount + 1;
if ( this.isContextAssign() ) {
nodeData.writeUsageCount = nodeData.writeUsageCount === undefined ? 1 : nodeData.writeUsageCount + 1;
} else {
nodeData.readUsageCount = nodeData.readUsageCount === undefined ? 1 : nodeData.readUsageCount + 1;
}
return nodeData.usageCount;
}
/**
* Returns whether the given node has been written to in any shader stage.
*
* @param {Node} node - The node to check.
* @return {boolean} Whether the node has been written to.
*/
hasWriteUsage( node ) {
const refNode = node.getShared( this );
const cache = refNode.isGlobal( this ) ? this.globalCache : this.cache;
const nodeData = cache.getData( refNode );
if ( nodeData !== undefined ) {
for ( const shaderStage in nodeData ) {
if ( _checkWriteUsage( nodeData[ shaderStage ] ) ) {
return true;
}
}
}
return false;
}
/**
* Generates a texture sample shader string for the given texture data.
*
* @abstract
* @param {Texture} texture - The texture.
* @param {string} textureProperty - The texture property name.
* @param {string} uvSnippet - Snippet defining the texture coordinates.
* @return {string} The generated shader string.
*/
generateTexture( /* texture, textureProperty, uvSnippet */ ) {
warn( 'Abstract function.' );
}
/**
* Generates a texture LOD shader string for the given texture data.
*
* @abstract
* @param {Texture} texture - The texture.
* @param {string} textureProperty - The texture property name.
* @param {string} uvSnippet - Snippet defining the texture coordinates.
* @param {?string} depthSnippet - Snippet defining the 0-based texture array index to sample.
* @param {string} levelSnippet - Snippet defining the mip level.
* @return {string} The generated shader string.
*/
generateTextureLod( /* texture, textureProperty, uvSnippet, depthSnippet, levelSnippet */ ) {
warn( 'Abstract function.' );
}
/**
* Generates a texture size shader string for the given texture data.
*
* @abstract
* @param {Texture} texture - The texture.
* @param {string} textureProperty - The texture property name.
* @param {string} levelSnippet - Snippet defining the mip level.
* @return {string} The generated shader string.
*/
generateTextureSize( /* texture, textureProperty, levelSnippet */ ) {
warn( 'Abstract function.' );
}
/**
* Generates the array declaration string.
*
* @param {string} type - The type.
* @param {?number} [count] - The count.
* @return {string} The generated value as a shader string.
*/
generateArrayDeclaration( type, count ) {
return this.getType( type ) + '[ ' + count + ' ]';
}
/**
* Generates the array shader string for the given type and value.
*
* @param {string} type - The type.
* @param {?number} [count] - The count.
* @param {?Array<Node>} [values=null] - The default values.
* @return {string} The generated value as a shader string.
*/
generateArray( type, count, values = null ) {
let snippet = this.generateArrayDeclaration( type, count ) + '( ';
for ( let i = 0; i < count; i ++ ) {
const value = values ? values[ i ] : null;
if ( value !== null ) {
snippet += value.build( this, type );
} else {
snippet += this.generateConst( type );
}
if ( i < count - 1 ) snippet += ', ';
}
snippet += ' )';
return snippet;
}
/**
* Generates the struct shader string.
*
* @param {string} type - The type.
* @param {Array<Object>} [membersLayout] - The count.
* @param {?Array<Node>} [values=null] - The default values.
* @return {string} The generated value as a shader string.
*/
generateStruct( type, membersLayout, values = null ) {
const snippets = [];
for ( const member of membersLayout ) {
const { name, type } = member;
if ( values && values[ name ] && values[ name ].isNode ) {
snippets.push( values[ name ].build( this, type ) );
} else {
snippets.push( this.generateConst( type ) );
}
}
return type + '( ' + snippets.join( ', ' ) + ' )';
}
/**
* Generates the shader string for the given type and value.
*
* @param {string} type - The type.
* @param {?any} [value=null] - The value.
* @return {string} The generated value as a shader string.
*/
generateConst( type, value = null ) {
if ( value === null ) {
if ( type === 'float' || type === 'int' || type === 'uint' ) value = 0;
else if ( type === 'bool' ) value = false;
else if ( type === 'color' ) value = new Color();
else if ( type === 'vec2' || type === 'uvec2' || type === 'ivec2' ) value = new Vector2();
else if ( type === 'vec3' || type === 'uvec3' || type === 'ivec3' ) value = new Vector3();
else if ( type === 'vec4' || type === 'uvec4' || type === 'ivec4' ) value = new Vector4();
}
if ( type === 'float' ) return _toFloat( value );
if ( type === 'int' ) return `${ Math.round( value ) }`;
if ( type === 'uint' ) return value >= 0 ? `${ Math.round( value ) }u` : '0u';
if ( type === 'bool' ) return value ? 'true' : 'false';
if ( type === 'color' ) return `${ this.getType( 'vec3' ) }( ${ _toFloat( value.r ) }, ${ _toFloat( value.g ) }, ${ _toFloat( value.b ) } )`;
const typeLength = this.getTypeLength( type );
const componentType = this.getComponentType( type );
const generateConst = value => this.generateConst( componentType, value );
if ( typeLength === 2 ) {
return `${ this.getType( type ) }( ${ generateConst( value.x ) }, ${ generateConst( value.y ) } )`;
} else if ( typeLength === 3 ) {
return `${ this.getType( type ) }( ${ generateConst( value.x ) }, ${ generateConst( value.y ) }, ${ generateConst( value.z ) } )`;
} else if ( typeLength === 4 && type !== 'mat2' ) {
return `${ this.getType( type ) }( ${ generateConst( value.x ) }, ${ generateConst( value.y ) }, ${ generateConst( value.z ) }, ${ generateConst( value.w ) } )`;
} else if ( typeLength >= 4 && value && ( value.isMatrix2 || value.isMatrix3 || value.isMatrix4 ) ) {
return `${ this.getType( type ) }( ${ value.elements.map( generateConst ).join( ', ' ) } )`;
} else if ( typeLength > 4 ) {
return `${ this.getType( type ) }()`;
}
throw new Error( `THREE.NodeBuilder: Type '${type}' not found in generate constant attempt.` );
}
/**
* It might be necessary to convert certain data types to different ones
* so this method can be used to hide the conversion.
*
* @param {string} type - The type.
* @return {string} The updated type.
*/
getType( type ) {
if ( type === 'color' ) return 'vec3';
return type;
}
/**
* Whether the given attribute name is defined in the geometry or not.
*
* @param {string} name - The attribute name.
* @return {boolean} Whether the given attribute name is defined in the geometry.
*/
hasGeometryAttribute( name ) {
return this.geometry && this.geometry.getAttribute( name ) !== undefined;
}
/**
* Returns a node attribute for the given name and type.
*
* @param {string} name - The attribute's name.
* @param {string} type - The attribute's type.
* @return {NodeAttribute} The node attribute.
*/
getAttribute( name, type ) {
const attributes = this.attributes;
// find attribute
for ( const attribute of attributes ) {
if ( attribute.name === name ) {
return attribute;
}
}
// create a new if no exist
const attribute = new NodeAttribute( name, type );
this.registerDeclaration( attribute );
attributes.push( attribute );
return attribute;
}
/**
* Returns for the given node and shader stage the property name for the shader.
*
* @param {Node} node - The node.
* @param {('vertex'|'fragment'|'compute'|'any')} shaderStage - The shader stage.
* @return {string} The property name.
*/
getPropertyName( node/*, shaderStage*/ ) {
return node.name;
}
/**
* Returns whether the given name is a reserved keyword of the backend's
* shading language. Backends override this method to provide their
* language-specific keywords.
*
* @param {string} name - The name to test.
* @return {boolean} Whether the name is a reserved keyword or not.
*/
isReservedKeyword( /* name */ ) {
return false;
}
/**
* Whether the given type is a vector type or not.
*
* @param {string} type - The type to check.
* @return {boolean} Whether the given type is a vector type or not.
*/
isVector( type ) {
return /vec\d/.test( type );
}
/**
* Whether the given type is a matrix type or not.
*
* @param {string} type - The type to check.
* @return {boolean} Whether the given type is a matrix type or not.
*/
isMatrix( type ) {
return /mat\d/.test( type );
}
/**
* Whether the given type is a reference type or not.
*
* @param {string} type - The type to check.
* @return {boolean} Whether the given type is a reference type or not.
*/
isReference( type ) {
return type === 'void' || type === 'property' || type === 'sampler' || type === 'samplerComparison' || type === 'texture' || type === 'cubeTexture' || type === 'storageTexture' || type === 'depthTexture' || type === 'texture3D';
}
/**
* Checks if the given texture requires a manual conversion to the working color space.
*
* @abstract
* @param {Texture} texture - The texture to check.
* @return {boolean} Whether the given texture requires a conversion to working color space or not.
*/
needsToWorkingColorSpace( /*texture*/ ) {
return false;
}
/**
* Returns the component type of a given texture.
*
* @param {Texture} texture - The texture.
* @return {string} The component type.
*/
getComponentTypeFromTexture( texture ) {
const type = texture.type;
if ( texture.isDepthTexture === true ) return 'float';
if ( type === IntType ) return 'int';
if ( type === UnsignedIntType ) return 'uint';
return 'float';
}
/**
* Returns the element type for a given type.
*
* @param {string} type - The type.
* @return {string} The element type.
*/
getElementType( type ) {
if ( type === 'mat2' ) return 'vec2';
if ( type === 'mat3' ) return 'vec3';
if ( type === 'mat4' ) return 'vec4';
return this.getComponentType( type );
}
/**
* Returns the component type for a given type.
*
* @param {string} type - The type.
* @return {string} The component type.
*/
getComponentType( type ) {
type = this.getVectorType( type );
if ( type === 'float' || type === 'bool' || type === 'int' || type === 'uint' ) return type;
const componentType = /(b|i|u|)(vec|mat)([2-4])/.exec( type );
if ( componentType === null ) return null;
if ( componentType[ 1 ] === 'b' ) return 'bool';
if ( componentType[ 1 ] === 'i' ) return 'int';
if ( componentType[ 1 ] === 'u' ) return 'uint';
return 'float';
}
/**
* Returns the vector type for a given type.
*
* @param {string} type - The type.
* @return {string} The vector type.
*/
getVectorType( type ) {
if ( type === 'color' ) return 'vec3';
if ( type === 'texture' || type === 'cubeTexture' || type === 'storageTexture' || type === 'texture3D' ) return 'vec4';
return type;
}
/**
* Returns the data type for the given the length and component type.
*
* @param {number} length - The length.
* @param {string} [componentType='float'] - The component type.
* @return {string} The type.
*/
getTypeFromLength( length, componentType = 'float' ) {
if ( length === 1 ) return componentType;
let baseType = getTypeFromLength( length );
const prefix = componentType === 'float' ? '' : componentType[ 0 ];
// fix edge case for mat2x2 being same size as vec4
if ( /mat2/.test( componentType ) === true ) {
baseType = baseType.replace( 'vec', 'mat' );
}
return prefix + baseType;
}
/**
* Returns the type for a given typed array.
*
* @param {TypedArray} array - The typed array.
* @return {string} The type.
*/
getTypeFromArray( array ) {
return typeFromArray.get( array.constructor );
}
/**
* Returns the type is an integer type.
*
* @param {string} type - The type.
* @return {boolean} Whether the type is an integer type or not.
*/
isInteger( type ) {
return /int|uint|(i|u)vec/.test( type );
}
/**
* Returns the type for a given buffer attribute.
*
* @param {BufferAttribute} attribute - The buffer attribute.
* @return {string} The type.
*/
getTypeFromAttribute( attribute ) {
let dataAttribute = attribute;
if ( attribute.isInterleavedBufferAttribute ) dataAttribute = attribute.data;
const array = dataAttribute.array;
const itemSize = attribute.itemSize;
const normalized = attribute.normalized;
let arrayType;
if ( ! ( attribute instanceof Float16BufferAttribute ) && normalized !== true ) {
arrayType = this.getTypeFromArray( array );
}
return this.getTypeFromLength( itemSize, arrayType );
}
/**
* Returns the length for the given data type.
*
* @param {string} type - The data type.
* @return {number} The length.
*/
getTypeLength( type ) {
const vecType = this.getVectorType( type );
const vecNum = /vec([2-4])/.exec( vecType );
if ( vecNum !== null ) return Number( vecNum[ 1 ] );
if ( vecType === 'float' || vecType === 'bool' || vecType === 'int' || vecType === 'uint' ) return 1;
if ( /mat2/.test( type ) === true ) return 4;
if ( /mat3/.test( type ) === true ) return 9;
if ( /mat4/.test( type ) === true ) return 16;
return 0;
}
/**
* Returns the vector type for a given matrix type.
*
* @param {string} type - The matrix type.
* @return {string} The vector type.
*/
getVectorFromMatrix( type ) {
return type.replace( 'mat', 'vec' );
}
/**
* For a given type this method changes the component type to the
* given value. E.g. `vec4` should be changed to the new component type
* `uint` which results in `uvec4`.
*
* @param {string} type - The type.
* @param {string} newComponentType - The new component type.
* @return {string} The new type.
*/
changeComponentType( type, newComponentType ) {
return this.getTypeFromLength( this.getTypeLength( type ), newComponentType );
}
/**
* Returns the integer type pendant for the given type.
*
* @param {string} type - The type.
* @return {string} The integer type.
*/
getIntegerType( type ) {
const componentType = this.getComponentType( type );
if ( componentType === 'int' || componentType === 'uint' ) return type;
return this.changeComponentType( type, 'int' );
}
/**
* Adds an active stack to the internal stack.
*
* @param {StackNode} stack - The stack node to add.
*/
setActiveStack( stack ) {
this.activeStacks.push( stack );
}
/**
* Removes the active stack from the internal stack.
*
* @param {StackNode} stack - The stack node to remove.
*/
removeActiveStack( stack ) {
if ( this.activeStacks[ this.activeStacks.length - 1 ] === stack ) {
this.activeStacks.pop();
} else {
throw new Error( 'THREE.NodeBuilder: Invalid active stack removal.' );
}
}
/**
* Returns the active stack.
*
* @return {StackNode} The active stack.
*/
getActiveStack() {
return this.activeStacks[ this.activeStacks.length - 1 ];
}
/**
* Returns the base stack.
*
* @return {StackNode} The base stack.
*/
getBaseStack() {
return this.activeStacks[ 0 ];
}
/**
* Adds a stack node to the internal stack.
*
* @return {StackNode} The added stack node.
*/
addStack() {
this.stack = stack( this.stack );
const previousStack = getCurrentStack();
this.stacks.push( previousStack );
setCurrentStack( this.stack );
return this.stack;
}
/**
* Removes the last stack node from the internal stack.
*
* @return {StackNode} The removed stack node.
*/
removeStack() {
const lastStack = this.stack;
for ( const node of lastStack.nodes ) {
const nodeData = this.getDataFromNode( node );
nodeData.stack = lastStack;
}
this.stack = lastStack.parent;
setCurrentStack( this.stacks.pop() );
return lastStack;
}
/**
* The builder maintains (cached) data for each node during the building process. This method
* can be used to get these data for a specific shader stage and cache.
*
* @param {Node} node - The node to get the data for.
* @param {('vertex'|'fragment'|'compute'|'any')} [shaderStage=this.shaderStage] - The shader stage.
* @param {?NodeCache} cache - An optional cache.
* @return {Object} The node data.
*/
getDataFromNode( node, shaderStage = this.shaderStage, cache = null ) {
cache = cache === null ? ( node.isGlobal( this ) ? this.globalCache : this.cache ) : cache;
let nodeData = cache.getData( node );
if ( nodeData === undefined ) {
nodeData = {};
cache.setData( node, nodeData );
}
if ( nodeData[ shaderStage ] === undefined ) nodeData[ shaderStage ] = {};
//
let data = nodeData[ shaderStage ];
if ( this.subBuildLayers.length === 0 ) return data;
const subBuilds = nodeData.any ? nodeData.any.subBuilds : null;
const subBuild = this.getClosestSubBuild( subBuilds );
if ( subBuild ) {
if ( data.subBuildsCache === undefined ) data.subBuildsCache = {};
data = data.subBuildsCache[ subBuild ] || ( data.subBuildsCache[ subBuild ] = {} );
data.subBuilds = subBuilds;
}
return data;
}
/**
* Returns the properties for the given node and shader stage.
*
* Properties are typically used within a build stage to reference a node's
* child node or nodes manually assigned to the properties in a separate build stage.
* A typical usage pattern for defining nodes manually would be assigning dependency nodes
* to the current node's properties in the setup stage and building those properties in the generate stage.
*
* @param {Node} node - The node to get the properties for.
* @param {('vertex'|'fragment'|'compute'|'any')} [shaderStage='any'] - The shader stage.
* @return {Object} The node properties.
*/
getNodeProperties( node, shaderStage = 'any' ) {
const nodeData = this.getDataFromNode( node, shaderStage );
return nodeData.properties || ( nodeData.properties = { outputNode: null } );
}
/**
* Returns an instance of {@link NodeAttribute} for the given buffer attribute node.
*
* @param {BufferAttributeNode} node - The buffer attribute node.
* @param {string} type - The node type.
* @param {?string} [name=null] - The name of the buffer attribute.
* @return {NodeAttribute} The node attribute.
*/
getBufferAttributeFromNode( node, type, name = null ) {
const nodeData = this.getDataFromNode( node, 'vertex' );
let bufferAttribute = nodeData.bufferAttribute;
if ( bufferAttribute === undefined ) {
const index = this.uniforms.index ++;
if ( name === null ) {
name = 'nodeAttribute' + index;
}
bufferAttribute = new NodeAttribute( name, type, node );
this.bufferAttributes.push( bufferAttribute );
nodeData.bufferAttribute = bufferAttribute;
}
return bufferAttribute;
}
/**
* Returns an instance of {@link StructType} for the given struct name and shader stage
* or null if not found.
*
* @param {string} name - The name of the struct.
* @param {('vertex'|'fragment'|'compute'|'any')} [shaderStage=this.shaderStage] - The shader stage.
* @return {?StructType} The struct type or null if not found.
*/
getStructTypeNode( name, shaderStage = this.shaderStage ) {
return this.types[ shaderStage ][ name ] || null;
}
/**
* Returns an instance of {@link StructType} for the given output struct node.
*
* @param {OutputStructNode} node - The output struct node.
* @param {Array<Object>} membersLayout - The output struct types.
* @param {?string} [name=null] - The name of the struct.
* @param {('vertex'|'fragment'|'compute'|'any')} [shaderStage=this.shaderStage] - The shader stage.
* @return {StructType} The struct type attribute.
*/
getStructTypeFromNode( node, membersLayout, name = null, shaderStage = this.shaderStage ) {
const nodeData = this.getDataFromNode( node, shaderStage, this.globalCache );
let structType = nodeData.structType;
if ( structType === undefined ) {
const index = this.structs.index ++;
if ( name === null ) name = 'StructType' + index;
structType = new StructType( name, membersLayout );
this.structs[ shaderStage ].push( structType );
this.types[ shaderStage ][ name ] = node;
nodeData.structType = structType;
}
return structType;
}
/**
* Returns an instance of {@link StructType} for the given output struct node.
*
* @param {OutputStructNode} node - The output struct node.
* @param {Array<Object>} membersLayout - The output struct types.
* @return {StructType} The struct type attribute.
*/
getOutputStructTypeFromNode( node, membersLayout ) {
const structType = this.getStructTypeFromNode( node, membersLayout, 'OutputType', 'fragment' );
structType.output = true;
return structType;
}
/**
* Returns an instance of {@link NodeUniform} for the given uniform node.
*
* @param {UniformNode} node - The uniform node.
* @param {string} type - The uniform type.
* @param {('vertex'|'fragment'|'compute'|'any')} [shaderStage=this.shaderStage] - The shader stage.
* @param {?string} name - The name of the uniform.
* @return {NodeUniform} The node uniform.
*/
getUniformFromNode( node, type, shaderStage = this.shaderStage, name = null ) {
const nodeData = this.getDataFromNode( node, shaderStage, this.globalCache );
let nodeUniform = nodeData.uniform;
if ( nodeUniform === undefined ) {
const index = this.uniforms.index ++;
nodeUniform = new NodeUniform( name || ( 'nodeUniform' + index ), type, node );
this.uniforms[ shaderStage ].push( nodeUniform );
this.registerDeclaration( nodeUniform );
nodeData.uniform = nodeUniform;
}
return nodeUniform;
}
/**
* Returns an instance of {@link NodeVar} for the given variable node.
*
* @param {VarNode} node - The variable node.
* @param {?string} name - The variable's name.
* @param {string} [type=node.getNodeType( this )] - The variable's type.
* @param {('vertex'|'fragment'|'compute'|'any')} [shaderStage=this.shaderStage] - The shader stage.
* @param {boolean} [readOnly=false] - Whether the variable is read-only or not.
*
* @return {NodeVar} The node variable.
*/
getVarFromNode( node, name = null, type = node.getNodeType( this ), shaderStage = this.shaderStage, readOnly = false ) {
const nodeData = this.getDataFromNode( node, shaderStage );
const subBuildVariable = this.getSubBuildProperty( 'variable', nodeData.subBuilds );
let nodeVar = nodeData[ subBuildVariable ];
if ( nodeVar === undefined ) {
const idNS = readOnly ? '_const' : '_var';
const vars = this.vars[ shaderStage ] || ( this.vars[ shaderStage ] = [] );
const id = this.vars[ idNS ] || ( this.vars[ idNS ] = 0 );
if ( name === null ) {
name = ( readOnly ? 'nodeConst' : 'nodeVar' ) + id;
this.vars[ idNS ] ++;
}
//
if ( subBuildVariable !== 'variable' ) {
name = this.getSubBuildProperty( name, nodeData.subBuilds );
}
//
const count = node.getArrayCount( this );
nodeVar = new NodeVar( name, type, readOnly, count );
if ( ! readOnly ) {
vars.push( nodeVar );
}
this.registerDeclaration( nodeVar );
nodeData[ subBuildVariable ] = nodeVar;
}
return nodeVar;
}
/**
* Returns whether a Node or its flow is deterministic, useful for use in `const`.
*
* @param {Node} node - The varying node.
* @return {boolean} Returns true if deterministic.
*/
isDeterministic( node ) {
if ( node.isMathNode ) {
return this.isDeterministic( node.aNode ) &&
( node.bNode ? this.isDeterministic( node.bNode ) : true ) &&
( node.cNode ? this.isDeterministic( node.cNode ) : true );
} else if ( node.isOperatorNode ) {
return this.isDeterministic( node.aNode ) &&
( node.bNode ? this.isDeterministic( node.bNode ) : true );
} else if ( node.isArrayNode ) {
if ( node.values !== null ) {
for ( const n of node.values ) {
if ( ! this.isDeterministic( n ) ) {
return false;
}
}
}
return true;
} else if ( node.isConstNode ) {
return true;
}
return false;
}
/**
* Returns an instance of {@link NodeVarying} for the given varying node.
*
* @param {(VaryingNode|PropertyNode)} node - The varying node.
* @param {?string} name - The varying's name.
* @param {string} [type=node.getNodeType( this )] - The varying's type.
* @param {?string} interpolationType - The interpolation type of the varying.
* @param {?string} interpolationSampling - The interpolation sampling type of the varying.
* @return {NodeVar} The node varying.
*/
getVaryingFromNode( node, name = null, type = node.getNodeType( this ), interpolationType = null, interpolationSampling = null ) {
const nodeData = this.getDataFromNode( node, 'any' );
const subBuildVarying = this.getSubBuildProperty( 'varying', nodeData.subBuilds );
let nodeVarying = nodeData[ subBuildVarying ];
if ( nodeVarying === undefined ) {
const varyings = this.varyings;
const index = varyings.length;
if ( name === null ) name = 'nodeVarying' + index;
//
if ( subBuildVarying !== 'varying' ) {
name = this.getSubBuildProperty( name, nodeData.subBuilds );
}
//
nodeVarying = new NodeVarying( name, type, interpolationType, interpolationSampling );
varyings.push( nodeVarying );
this.registerDeclaration( nodeVarying );
nodeData[ subBuildVarying ] = nodeVarying;
}
return nodeVarying;
}
/**
* Registers a node declaration in the current shader stage.
*
* @param {Object} node - The node to be registered.
*/
registerDeclaration( node ) {
const shaderStage = this.shaderStage;
const declarations = this.declarations[ shaderStage ] || ( this.declarations[ shaderStage ] = {} );
const checkKeywords = this.renderer.debug.diagnostics.keywords;
const baseName = node.name;
let name = baseName;
let property = this.getPropertyName( node );
let index = 1;
// Automatically renames the property if the name is already in use or reserved.
while ( ( checkKeywords && this.isReservedKeyword( name ) ) || declarations[ property ] !== undefined ) {
name = baseName + '_' + index ++;
node.name = name;
property = this.getPropertyName( node );
}
if ( name !== baseName ) {
warn( `TSL: Declaration name '${ baseName }' of '${ node.type }' is a reserved keyword or already in use. Renamed to '${ name }'.` );
}
declarations[ property ] = node;
}
/**
* Returns an instance of {@link NodeCode} for the given code node.
*
* @param {CodeNode} node - The code node.
* @param {string} type - The node type.
* @param {('vertex'|'fragment'|'compute'|'any')} [shaderStage=this.shaderStage] - The shader stage.
* @return {NodeCode} The node code.
*/
getCodeFromNode( node, type, shaderStage = this.shaderStage ) {
const nodeData = this.getDataFromNode( node );
let nodeCode = nodeData.code;
if ( nodeCode === undefined ) {
const codes = this.codes[ shaderStage ] || ( this.codes[ shaderStage ] = [] );
const index = codes.length;
nodeCode = new NodeCode( 'nodeCode' + index, type );
codes.push( nodeCode );
nodeData.code = nodeCode;
}
return nodeCode;
}
/**
* Adds a code flow based on the code-block hierarchy.
* This is used so that code-blocks like If,Else create their variables locally if the Node
* is only used inside one of these conditionals in the current shader stage.
*
* @param {Node} node - The node to add.
* @param {Node} nodeBlock - Node-based code-block. Usually 'ConditionalNode'.
*/
addFlowCodeHierarchy( node, nodeBlock ) {
const { flowCodes, flowCodeBlock } = this.getDataFromNode( node );
let needsFlowCode = true;
let nodeBlockHierarchy = nodeBlock;
while ( nodeBlockHierarchy ) {
if ( flowCodeBlock.get( nodeBlockHierarchy ) === true ) {
needsFlowCode = false;
break;
}
nodeBlockHierarchy = this.getDataFromNode( nodeBlockHierarchy ).parentNodeBlock;
}
if ( needsFlowCode ) {
for ( const flowCode of flowCodes ) {
this.addLineFlowCode( flowCode );
}
}
}
/**
* Add a inline-code to the current flow code-block.
*
* @param {Node} node - The node to add.
* @param {string} code - The code to add.
* @param {Node} nodeBlock - Current ConditionalNode
*/
addLineFlowCodeBlock( node, code, nodeBlock ) {
const nodeData = this.getDataFromNode( node );
const flowCodes = nodeData.flowCodes || ( nodeData.flowCodes = [] );
const codeBlock = nodeData.flowCodeBlock || ( nodeData.flowCodeBlock = new WeakMap() );
flowCodes.push( code );
codeBlock.set( nodeBlock, true );
}
/**
* Add a inline-code to the current flow.
*
* @param {string} code - The code to add.
* @param {?Node} [node= null] - Optional Node, can help the system understand if the Node is part of a code-block.
* @return {NodeBuilder} A reference to this node builder.
*/
addLineFlowCode( code, node = null ) {
if ( code === '' ) return this;
if ( node !== null && this.context.nodeBlock ) {
this.addLineFlowCodeBlock( node, code, this.context.nodeBlock );
}
code = this.tab + code;
if ( ! /;\s*$/.test( code ) ) {
code = code + ';\n';
}
this.flow.code += code;
return this;
}
/**
* Adds a code to the current code flow.
*
* @param {string} code - Shader code.
* @return {NodeBuilder} A reference to this node builder.
*/
addFlowCode( code ) {
this.flow.code += code;
return this;
}
/**
* Add tab in the code that will be generated so that other snippets respect the current tabulation.
* Typically used in codes with If,Else.
*
* @return {NodeBuilder} A reference to this node builder.
*/
addFlowTab() {
this.tab += '\t';
return this;
}
/**
* Removes a tab.
*
* @return {NodeBuilder} A reference to this node builder.
*/
removeFlowTab() {
this.tab = this.tab.slice( 0, - 1 );
return this;
}
/**
* Gets the current flow data based on a Node.
*
* @param {Node} node - Node that the flow was started.
* @param {('vertex'|'fragment'|'compute'|'any')} shaderStage - The shader stage.
* @return {Object} The flow data.
*/
getFlowData( node/*, shaderStage*/ ) {
return this.flowsData.get( node );
}
/**
* Executes the node flow based on a root node to generate the final shader code.
*
* @param {Node} node - The node to execute.
* @return {Object} The code flow.
*/
flowNode( node ) {
const output = node.getNodeType( this );
const flowData = this.flowChildNode( node, output );
this.flowsData.set( node, flowData );
return flowData;
}
/**
* Includes a node in the current function node.
*
* @param {Node} node - The node to include.
* @returns {void}
*/
addInclude( node ) {
if ( this.currentFunctionNode !== null ) {
this.currentFunctionNode.includes.push( node );
}
}
/**
* Returns the native shader operator name for a given generic name.
* It is a similar type of method like {@link NodeBuilder#getMethod}.
*
* @param {ShaderNodeInternal} shaderNode - The shader node to build the function node with.
* @return {FunctionNode} The build function node.
*/
buildFunctionNode( shaderNode ) {
const backend = this.renderer.backend;
let cache = _functionNodeCache.get( backend );
if ( cache === undefined ) {
cache = new WeakMap();
_functionNodeCache.set( backend, cache );
}
let fn = cache.get( shaderNode );
if ( fn === undefined ) {
fn = new FunctionNode();
const previous = this.currentFunctionNode;
this.currentFunctionNode = fn;
fn.code = this.buildFunctionCode( shaderNode );
this.currentFunctionNode = previous;
cache.set( shaderNode, fn );
}
return fn;
}
/**
* Generates a code flow based on a TSL function: Fn().
*
* @param {ShaderNodeInternal} shaderNode - A function code will be generated based on the input.
* @return {Object}
*/
flowShaderNode( shaderNode ) {
const layout = shaderNode.layout;
const inputs = {
[ Symbol.iterator ]() {
let index = 0;
const values = Object.values( this );
return {
next: () => ( {
value: values[ index ],
done: index ++ >= values.length
} )
};
}
};
for ( const input of layout.inputs ) {
inputs[ input.name ] = new ParameterNode( input.type, input.name );
}
//
shaderNode.layout = null;
const callNode = shaderNode.call( inputs );
const flowData = this.flowStagesNode( callNode, layout.type );
shaderNode.layout = layout;
return flowData;
}
/**
* Executes the node in a specific build stage.
*
* This function can be used to arbitrarily execute the specified build stage
* outside of the standard build process. For instance, if a node's type depends
* on properties created by the 'setup' stage, then flowBuildStage(node, 'setup')
* can be used to execute the setup build stage and access its generated nodes
* before the standard build process begins.
*
* @param {Node} node - The node to execute.
* @param {string} buildStage - The build stage to execute the node in.
* @param {?(Node|string)} [output=null] - Expected output type. For example 'vec3'.
* @return {?(Node|string)} The result of the node build.
*/
flowBuildStage( node, buildStage, output = null ) {
const previousBuildStage = this.getBuildStage();
this.setBuildStage( buildStage );
const result = node.build( this, output );
this.setBuildStage( previousBuildStage );
return result;
}
/**
* Runs the node flow through all the steps of creation, 'setup', 'analyze', 'generate'.
*
* @param {Node} node - The node to execute.
* @param {?string} output - Expected output type. For example 'vec3'.
* @return {Object}
*/
flowStagesNode( node, output = null ) {
const previousFlow = this.flow;
const previousVars = this.vars;
const previousDeclarations = this.declarations;
const previousCache = this.cache;
const previousBuildStage = this.buildStage;
const previousStack = this.stack;
const flow = {
code: ''
};
this.flow = flow;
this.vars = {};
this.declarations = {};
this.cache = new NodeCache();
this.stack = stack();
for ( const buildStage of defaultBuildStages ) {
this.setBuildStage( buildStage );
flow.result = node.build( this, output );
}
flow.vars = this.getVars( this.shaderStage );
this.flow = previousFlow;
this.vars = previousVars;
this.declarations = previousDeclarations;
this.cache = previousCache;
this.stack = previousStack;
this.setBuildStage( previousBuildStage );
return flow;
}
/**
* Returns the native shader operator name for a given generic name.
* It is a similar type of method like {@link NodeBuilder#getMethod}.
*
* @abstract
* @param {string} op - The operator name to resolve.
* @return {?string} The resolved operator name.
*/
getFunctionOperator( /* op */ ) {
return null;
}
/**
* Builds the given shader node.
*
* @abstract
* @param {ShaderNodeInternal} shaderNode - The shader node.
* @return {string} The function code.
*/
buildFunctionCode( /* shaderNode */ ) {
warn( 'Abstract function.' );
}
/**
* Generates a code flow based on a child Node.
*
* @param {Node} node - The node to execute.
* @param {?string} output - Expected output type. For example 'vec3'.
* @return {Object} The code flow.
*/
flowChildNode( node, output = null ) {
const previousFlow = this.flow;
const flow = {
code: ''
};
this.flow = flow;
flow.result = node.build( this, output );
this.flow = previousFlow;
return flow;
}
/**
* Executes a flow of code in a different stage.
*
* Some nodes like `varying()` have the ability to compute code in vertex-stage and
* return the value in fragment-stage even if it is being executed in an input fragment.
*
* @param {('vertex'|'fragment'|'compute'|'any')} shaderStage - The shader stage.
* @param {Node} node - The node to execute.
* @param {?string} output - Expected output type. For example 'vec3'.
* @param {?string} propertyName - The property name to assign the result.
* @return {?(Object|Node)} The code flow or node.build() result.
*/
flowNodeFromShaderStage( shaderStage, node, output = null, propertyName = null ) {
const previousTab = this.tab;
const previousCache = this.cache;
const previousShaderStage = this.shaderStage;
const previousContext = this.context;
this.setShaderStage( shaderStage );
const context = { ...this.context };
delete context.nodeBlock;
this.cache = this.globalCache;
this.tab = '\t';
this.context = context;
let result = null;
if ( this.buildStage === 'generate' ) {
const flowData = this.flowChildNode( node, output );
if ( propertyName !== null ) {
flowData.code += `${ this.tab + propertyName } = ${ flowData.result };\n`;
}
this.flowCode[ shaderStage ] = this.flowCode[ shaderStage ] + flowData.code;
result = flowData;
} else {
result = node.build( this );
}
this.setShaderStage( previousShaderStage );
this.cache = previousCache;
this.tab = previousTab;
this.context = previousContext;
return result;
}
/**
* Returns an array holding all node attributes of this node builder.
*
* @return {Array<NodeAttribute>} The node attributes of this builder.
*/
getAttributesArray() {
return this.attributes.concat( this.bufferAttributes );
}
/**
* Returns the attribute definitions as a shader string for the given shader stage.
*
* @abstract
* @param {('vertex'|'fragment'|'compute'|'any')} shaderStage - The shader stage.
* @return {string} The attribute code section.
*/
getAttributes( /*shaderStage*/ ) {
warn( 'Abstract function.' );
}
/**
* Returns the varying definitions as a shader string for the given shader stage.
*
* @abstract
* @param {('vertex'|'fragment'|'compute'|'any')} shaderStage - The shader stage.
* @return {string} The varying code section.
*/
getVaryings( /*shaderStage*/ ) {
warn( 'Abstract function.' );
}
/**
* Returns a single variable definition as a shader string for the given variable type and name.
*
* @param {string} type - The variable's type.
* @param {string} name - The variable's name.
* @param {?number} [count=null] - The array length.
* @return {string} The shader string.
*/
getVar( type, name, count = null ) {
return `${ count !== null ? this.generateArrayDeclaration( type, count ) : this.getType( type ) } ${ name }`;
}
/**
* Returns the variable definitions as a shader string for the given shader stage.
*
* @param {('vertex'|'fragment'|'compute'|'any')} shaderStage - The shader stage.
* @param {boolean} [global=false] - Whether the variables are global.
* @return {string} The variable code section.
*/
getVars( shaderStage, global = false ) {
const snippets = [];
const vars = this.vars[ shaderStage ];
if ( vars !== undefined ) {
for ( const variable of vars ) {
snippets.push( `${ this.getVar( variable.type, variable.name, variable.count ) };` );
}
}
return snippets.join( global ? '\n' : '\n\t' );
}
/**
* Returns the uniform definitions as a shader string for the given shader stage.
*
* @abstract
* @param {('vertex'|'fragment'|'compute'|'any')} shaderStage - The shader stage.
* @return {string} The uniform code section.
*/
getUniforms( /*shaderStage*/ ) {
warn( 'Abstract function.' );
}
/**
* Returns the native code definitions as a shader string for the given shader stage.
*
* @param {('vertex'|'fragment'|'compute'|'any')} shaderStage - The shader stage.
* @return {string} The native code section.
*/
getCodes( shaderStage ) {
const codes = this.codes[ shaderStage ];
let code = '';
if ( codes !== undefined ) {
for ( const nodeCode of codes ) {
code += nodeCode.code + '\n';
}
}
return code;
}
/**
* Returns the hash of this node builder.
*
* @return {string} The hash.
*/
getHash() {
return this.vertexShader + this.fragmentShader + this.computeShader;
}
/**
* Sets the current shader stage.
*
* @param {?('vertex'|'fragment'|'compute'|'any')} shaderStage - The shader stage to set.
*/
setShaderStage( shaderStage ) {
this.shaderStage = shaderStage;
}
/**
* Returns the current shader stage.
*
* @return {?('vertex'|'fragment'|'compute'|'any')} The current shader stage.
*/
getShaderStage() {
return this.shaderStage;
}
/**
* Sets the current build stage.
*
* @param {?('setup'|'analyze'|'generate')} buildStage - The build stage to set.
*/
setBuildStage( buildStage ) {
this.buildStage = buildStage;
}
/**
* Returns the current build stage.
*
* @return {?('setup'|'analyze'|'generate')} The current build stage.
*/
getBuildStage() {
return this.buildStage;
}
/**
* Controls the code build of the shader stages.
*
* @abstract
*/
buildCode() {
warn( 'Abstract function.' );
}
/**
* Returns the current sub-build layer.
*
* @return {SubBuildNode} The current sub-build layers.
*/
get subBuild() {
return this.subBuildLayers[ this.subBuildLayers.length - 1 ] || null;
}
/**
* Adds a sub-build layer to the node builder.
*
* @param {SubBuildNode} subBuild - The sub-build layer to add.
*/
addSubBuild( subBuild ) {
this.subBuildLayers.push( subBuild );
}
/**
* Removes the last sub-build layer from the node builder.
*
* @return {SubBuildNode} The removed sub-build layer.
*/
removeSubBuild() {
return this.subBuildLayers.pop();
}
/**
* Returns the closest sub-build layer for the given data.
*
* @param {Node|Set<string>|Array<string>} data - The data to get the closest sub-build layer from.
* @return {?string} The closest sub-build name or null if none found.
*/
getClosestSubBuild( data ) {
let subBuilds;
if ( data && data.isNode ) {
if ( data.isShaderCallNodeInternal ) {
subBuilds = data.shaderNode.subBuilds;
} else if ( data.isStackNode ) {
subBuilds = [ data.subBuild ];
} else {
subBuilds = this.getDataFromNode( data, 'any' ).subBuilds;
}
} else if ( data instanceof Set ) {
subBuilds = [ ...data ];
} else {
subBuilds = data;
}
if ( ! subBuilds ) return null;
const subBuildLayers = this.subBuildLayers;
for ( let i = subBuilds.length - 1; i >= 0; i -- ) {
const subBuild = subBuilds[ i ];
if ( subBuildLayers.includes( subBuild ) ) {
return subBuild;
}
}
return null;
}
/**
* Returns the output node of a sub-build layer.
*
* @param {Node} node - The node to get the output from.
* @return {string} The output node name.
*/
getSubBuildOutput( node ) {
return this.getSubBuildProperty( 'outputNode', node );
}
/**
* Returns the sub-build property name for the given property and node.
*
* @param {string} [property=''] - The property name.
* @param {?Node} [node=null] - The node to get the sub-build from.
* @return {string} The sub-build property name.
*/
getSubBuildProperty( property = '', node = null ) {
let subBuild;
if ( node !== null ) {
subBuild = this.getClosestSubBuild( node );
} else {
subBuild = this.subBuildFn;
}
let result;
if ( subBuild ) {
result = property ? ( subBuild + '_' + property ) : subBuild;
} else {
result = property;
}
return result;
}
/**
* Prebuild the node builder.
*/
prebuild() {
const { renderer, material } = this;
// < renderer.contextNode >
if ( renderer.contextNode.isContextNode === true ) {
this.context = { ...this.context, ...renderer.contextNode.getFlowContextData() };
} else {
error( 'NodeBuilder: "renderer.contextNode" must be an instance of `context()`.' );
}
// < material.contextNode >
if ( material && material.contextNode ) {
if ( material.contextNode.isContextNode === true ) {
this.context = { ...this.context, ...material.contextNode.getFlowContextData() };
} else {
error( 'NodeBuilder: "material.contextNode" must be an instance of `context()`.' );
}
}
// < nodeMaterial >
if ( material !== null ) {
let nodeMaterial = renderer.library.fromMaterial( material );
if ( nodeMaterial === null ) {
error( `NodeBuilder: Material "${ material.type }" is not compatible.` );
nodeMaterial = new NodeMaterial();
}
nodeMaterial.build( this );
} else {
this.addFlow( 'compute', this.compute );
}
}
/**
* Central build method which controls the build for the given object.
*
* @return {NodeBuilder} A reference to this node builder.
*/
build() {
this.prebuild();
// setup() -> stage 1: create possible new nodes and/or return an output reference node
// analyze() -> stage 2: analyze nodes to possible optimization and validation
// generate() -> stage 3: generate shader
for ( const buildStage of defaultBuildStages ) {
this.setBuildStage( buildStage );
if ( this.context.position && this.context.position.isNode ) {
this.flowNodeFromShaderStage( 'vertex', this.context.position );
}
for ( const shaderStage of shaderStages ) {
this.setShaderStage( shaderStage );
const flowNodes = this.flowNodes[ shaderStage ];
for ( const node of flowNodes ) {
if ( buildStage === 'generate' ) {
this.flowNode( node );
} else {
node.build( this );
}
}
}
}
this.setBuildStage( null );
this.setShaderStage( null );
// stage 4: build code for a specific output
this.buildCode();
this.buildUpdateNodes();
return this;
}
/**
* Async version of build() that yields to main thread between shader stages.
* Use this in compileAsync() to prevent blocking the main thread.
*
* @return {Promise<NodeBuilder>} A promise that resolves to this node builder.
*/
async buildAsync() {
this.prebuild();
// setup() -> stage 1: create possible new nodes and/or return an output reference node
// analyze() -> stage 2: analyze nodes to possible optimization and validation
// generate() -> stage 3: generate shader
for ( const buildStage of defaultBuildStages ) {
this.setBuildStage( buildStage );
if ( this.context.position && this.context.position.isNode ) {
this.flowNodeFromShaderStage( 'vertex', this.context.position );
}
for ( const shaderStage of shaderStages ) {
this.setShaderStage( shaderStage );
const flowNodes = this.flowNodes[ shaderStage ];
for ( const node of flowNodes ) {
if ( buildStage === 'generate' ) {
this.flowNode( node );
} else {
node.build( this );
}
}
// Yield to main thread after each shader stage to prevent blocking
await yieldToMain();
}
}
this.setBuildStage( null );
this.setShaderStage( null );
// stage 4: build code for a specific output
this.buildCode();
this.buildUpdateNodes();
return this;
}
/**
* Returns shared data object for the given node.
*
* @param {Node} node - The node to get shared data from.
* @return {Object} The shared data.
*/
getSharedDataFromNode( node ) {
let data = sharedNodeData.get( node );
if ( data === undefined ) {
data = {};
}
return data;
}
/**
* Returns a uniform representation which is later used for UBO generation and rendering.
*
* @param {NodeUniform} uniformNode - The uniform node.
* @param {string} type - The requested type.
* @return {Uniform} The uniform.
*/
getNodeUniform( uniformNode, type ) {
const nodeData = this.getSharedDataFromNode( uniformNode );
let node = nodeData.cache;
if ( node === undefined ) {
if ( type === 'float' || type === 'int' || type === 'uint' ) node = new NumberNodeUniform( uniformNode );
else if ( type === 'vec2' || type === 'ivec2' || type === 'uvec2' ) node = new Vector2NodeUniform( uniformNode );
else if ( type === 'vec3' || type === 'ivec3' || type === 'uvec3' ) node = new Vector3NodeUniform( uniformNode );
else if ( type === 'vec4' || type === 'ivec4' || type === 'uvec4' ) node = new Vector4NodeUniform( uniformNode );
else if ( type === 'color' ) node = new ColorNodeUniform( uniformNode );
else if ( type === 'mat2' ) node = new Matrix2NodeUniform( uniformNode );
else if ( type === 'mat3' ) node = new Matrix3NodeUniform( uniformNode );
else if ( type === 'mat4' ) node = new Matrix4NodeUniform( uniformNode );
else {
throw new Error( `THREE.NodeBuilder: Uniform "${ type }" not implemented.` );
}
nodeData.cache = node;
}
return node;
}
/**
* Formats the given shader snippet from a given type into another one. E.g.
* this method might be used to convert a simple float string `"1.0"` into a
* `vec3` representation: `"vec3<f32>( 1.0 )"`.
*
* @param {string} snippet - The shader snippet.
* @param {string} fromType - The source type.
* @param {string} toType - The target type.
* @return {string} The updated shader string.
*/
format( snippet, fromType, toType ) {
fromType = this.getVectorType( fromType );
toType = this.getVectorType( toType );
if ( fromType === toType || toType === null || this.isReference( toType ) ) {
return snippet;
}
const fromTypeLength = this.getTypeLength( fromType );
const toTypeLength = this.getTypeLength( toType );
if ( fromTypeLength === 16 && toTypeLength === 9 ) {
return `${ this.getType( toType ) }( ${ snippet }[ 0 ].xyz, ${ snippet }[ 1 ].xyz, ${ snippet }[ 2 ].xyz )`;
}
if ( fromTypeLength === 9 && toTypeLength === 4 ) {
return `${ this.getType( toType ) }( ${ snippet }[ 0 ].xy, ${ snippet }[ 1 ].xy )`;
}
if ( fromTypeLength > 4 ) { // fromType is matrix-like
// @TODO: ignore for now
return snippet;
}
if ( toTypeLength > 4 || toTypeLength === 0 ) { // toType is matrix-like or unknown
// @TODO: ignore for now
return snippet;
}
if ( fromTypeLength === toTypeLength ) {
return `${ this.getType( toType ) }( ${ snippet } )`;
}
if ( fromTypeLength > toTypeLength ) {
snippet = toType === 'bool' ? `all( ${ snippet } )` : `${ snippet }.${ 'xyz'.slice( 0, toTypeLength ) }`;
return this.format( snippet, this.getTypeFromLength( toTypeLength, this.getComponentType( fromType ) ), toType );
}
if ( toTypeLength === 4 && fromTypeLength > 1 ) { // toType is vec4-like
return `${ this.getType( toType ) }( ${ this.format( snippet, fromType, 'vec3' ) }, 1.0 )`;
}
if ( fromTypeLength === 2 ) { // fromType is vec2-like and toType is vec3-like
return `${ this.getType( toType ) }( ${ this.format( snippet, fromType, 'vec2' ) }, 0.0 )`;
}
if ( fromTypeLength === 1 && toTypeLength > 1 && fromType !== this.getComponentType( toType ) ) { // fromType is float-like
// convert a number value to vector type, e.g:
// vec3( 1u ) -> vec3( float( 1u ) )
snippet = `${ this.getType( this.getComponentType( toType ) ) }( ${ snippet } )`;
}
return `${ this.getType( toType ) }( ${ snippet } )`; // fromType is float-like
}
/**
* Returns a signature with the engine's current revision.
*
* @return {string} The signature.
*/
getSignature() {
return `// Three.js r${ REVISION } - Node System\n`;
}
/**
* Returns `true` if data from the previous frame are required. Relevant
* when computing motion vectors with {@link VelocityNode}.
*
* @return {boolean} Whether data from the previous frame are required or not.
*/
needsPreviousData() {
const mrt = this.renderer.getMRT();
return ( mrt && mrt.has( 'velocity' ) ) || ( this.object !== null && getDataFromObject( this.object ).useVelocity === true );
}
}
export default NodeBuilder;