From 3793b9d296cfd8d5e85efbb82cb7bc8f22120d05 Mon Sep 17 00:00:00 2001 From: sunag Date: Wed, 4 Dec 2024 21:53:06 -0300 Subject: [PATCH 1/2] more docs --- src/nodes/core/NodeBuilder.js | 107 ++++++++++++++++++---------------- src/nodes/core/StackNode.js | 5 +- 2 files changed, 59 insertions(+), 53 deletions(-) diff --git a/src/nodes/core/NodeBuilder.js b/src/nodes/core/NodeBuilder.js index 5ac9840a70f039..21e7c031b846db 100644 --- a/src/nodes/core/NodeBuilder.js +++ b/src/nodes/core/NodeBuilder.js @@ -232,14 +232,14 @@ class NodeBuilder { this.computeShader = null; /** - * TODO + * Nodes used in the primary flow of code generation. * - * @type {Object} + * @type {Object>} */ this.flowNodes = { vertex: [], fragment: [], compute: [] }; /** - * TODO + * Nodes code from `.flowNodes`. * * @type {Object} */ @@ -322,7 +322,8 @@ class NodeBuilder { this.vars = {}; /** - * TODO + * Current code flow. + * All code generated in this stack will be stored in `.flow`. * * @type {{code: String}} */ @@ -330,8 +331,7 @@ class NodeBuilder { /** * A chain of nodes. - * - * TODO: Explains purpose of this property. + * Used to check recursive calls in node-graph. * * @type {Array} */ @@ -339,8 +339,8 @@ class NodeBuilder { /** * The current stack. - * - * TODO: Explains purpose of this property. + * 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} */ @@ -348,8 +348,7 @@ class NodeBuilder { /** * List of stack nodes. - * - * TODO: Explains purpose of this property. + * The current stack hierarchy is stored in an array. * * @type {Array} */ @@ -580,9 +579,7 @@ class NodeBuilder { } /** - * Returns a list bindings. - * - * TODO: Add more details. + * Returns a list bindings of all shader stages separated by groups. * * @return {Array} The list of bindings. */ @@ -679,7 +676,8 @@ class NodeBuilder { } /** - * TODO: Describe the difference to `addNode()`. + * 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. * * @param {Node} node - The node to add. */ @@ -758,8 +756,7 @@ class NodeBuilder { /** * Adds the given node to the internal node chain. - * - * TODO: Describe the difference to `addNode()`. + * This is used to check recursive calls in node-graph. * * @param {Node} node - The node to add. */ @@ -822,11 +819,11 @@ class NodeBuilder { } /** - * TODO + * 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. - * @return {Node} The node + * @param {Node} node - The node to add. + * @return {Node} The node. */ addFlow( shaderStage, node ) { @@ -859,9 +856,10 @@ class NodeBuilder { } /** - * TODO + * 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} TODO. + * @return {Object} The builder's current context without material. */ getSharedContext() { @@ -1686,10 +1684,13 @@ class NodeBuilder { } /** - * TODO + * 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 - TODO. - * @param {Node} nodeBlock - TODO. + * @param {Node} node - The node to add. + * @param {Node} nodeBlock - Node-based code-block. Usually 'ConditionalNode'. */ addFlowCodeHierarchy( node, nodeBlock ) { @@ -1724,11 +1725,11 @@ class NodeBuilder { } /** - * TODO + * Add a inline-code to the current flow code-block. * - * @param {Node} node - TODO. - * @param {String} code - TODO. - * @param {Node} nodeBlock - TODO. + * @param {Node} node - The node to add. + * @param {String} code - The code to add. + * @param {Node} nodeBlock - Current ConditionalNode */ addLineFlowCodeBlock( node, code, nodeBlock ) { @@ -1742,10 +1743,10 @@ class NodeBuilder { } /** - * TODO + * Add a inline-code to the current flow. * - * @param {String} code - TODO. - * @param {Node?} [node= null] - TODO. + * @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 ) { @@ -1773,9 +1774,9 @@ class NodeBuilder { } /** - * TODO + * Adds a code to the current code flow. * - * @param {String} code - TODO. + * @param {String} code - Shader code. * @return {NodeBuilder} A reference to this node builder. */ addFlowCode( code ) { @@ -1787,7 +1788,8 @@ class NodeBuilder { } /** - * TODO + * 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. */ @@ -1800,7 +1802,7 @@ class NodeBuilder { } /** - * TODO + * Removes a tab. * * @return {NodeBuilder} A reference to this node builder. */ @@ -1813,9 +1815,9 @@ class NodeBuilder { } /** - * TODO + * Gets the current flow data based on a Node. * - * @param {Node} node - TODO. + * @param {Node} node - Node that the flow was started. * @param {('vertex'|'fragment'|'compute'|'any')} shaderStage - The shader stage. * @return {Object} */ @@ -1826,9 +1828,9 @@ class NodeBuilder { } /** - * TODO + * Executes the node flow based on a root node to generate the final shader code. * - * @param {Node} node - TODO. + * @param {Node} node - The node to execute. * @return {Object} */ flowNode( node ) { @@ -1867,9 +1869,9 @@ class NodeBuilder { } /** - * TODO + * Generates a code flow based on a TSL function: Fn(). * - * @param {ShaderNodeInternal} node - TODO. + * @param {ShaderNodeInternal} node - A function code will be generated based on the input. * @return {Object} */ flowShaderNode( shaderNode ) { @@ -1911,10 +1913,10 @@ class NodeBuilder { } /** - * TODO + * Runs the node flow through all the steps of creation, 'setup', 'analyze', 'generate'. * - * @param {Node} node - TODO. - * @param {String?} output - TODO. + * @param {Node} node - The node to execute. + * @param {String?} output - Expected output type. For example 'vec3'. * @return {Object} */ flowStagesNode( node, output = null ) { @@ -1970,10 +1972,10 @@ class NodeBuilder { } /** - * TODO + * Generates a code flow based on a child Node. * - * @param {Node} node - TODO. - * @param {String?} output - TODO. + * @param {Node} node - The node to execute. + * @param {String?} output - Expected output type. For example 'vec3'. * @return {Object} */ flowChildNode( node, output = null ) { @@ -1995,12 +1997,15 @@ class NodeBuilder { } /** - * TODO + * 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 - TODO. - * @param {String?} output - TODO. - * @param {String?} propertyName - TODO. + * @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} */ flowNodeFromShaderStage( shaderStage, node, output = null, propertyName = null ) { diff --git a/src/nodes/core/StackNode.js b/src/nodes/core/StackNode.js index 7c6f84482d69cf..f9f59dfc72ccb1 100644 --- a/src/nodes/core/StackNode.js +++ b/src/nodes/core/StackNode.js @@ -3,9 +3,10 @@ import { select } from '../math/ConditionalNode.js'; import { ShaderNode, nodeProxy, getCurrentStack, setCurrentStack } from '../tsl/TSLBase.js'; /** - * TODO + * 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`. * - * @augments Node + * @augments StackNode */ class StackNode extends Node { From 6fe3c9a05d08141d014471399e8a8517dc7a55ac Mon Sep 17 00:00:00 2001 From: Michael Herzog Date: Thu, 5 Dec 2024 20:14:48 +0100 Subject: [PATCH 2/2] Update StackNode.js --- src/nodes/core/StackNode.js | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/nodes/core/StackNode.js b/src/nodes/core/StackNode.js index f9f59dfc72ccb1..a3603d9dfdfb69 100644 --- a/src/nodes/core/StackNode.js +++ b/src/nodes/core/StackNode.js @@ -6,7 +6,7 @@ import { ShaderNode, nodeProxy, getCurrentStack, setCurrentStack } from '../tsl/ * 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`. * - * @augments StackNode + * @augments Node */ class StackNode extends Node {