Function NodeDef Prototype #2401

kwokcb · 2025-05-21T20:13:20Z

Draft Implementation

This are the basic changes to handle the current "functional nodedef" proposal: #2355

Changes

Update node definition dictionay in the document cache to consider nodefs with child nodegraphs (implementations). Append non-child implementations afterwards
Update definition query for implementations / nodegraphs to check for parent nodedef first.
Add DefintionOptions options class to which contains the option to add as child or not. Default is false. Additional arguments can be added here vs a list of args in the previous interface.
Update C++ and Python Documeent::addNodeDefFromGraph() interface to take
DefinitionsOptions as an optional argument.

Tests

Migrate "safepower" over. ( Done by hand but could be done via utility. )
math_operators.mtlx unit test file tests this definition
Update unit tests to run definition creation test for both sibling (current) and child (new) options as defined by DefinitionOptions.
Manual testing in graph editor.
- Value modifications
- Show definition

Unit Test Results

Definition Created with Sibling Reference

<?xml version="1.0"?>
<materialx version="1.39">
 <nodegraph name="test_colorcorrect">
   <multiply name="AlphaGain" type="float">
     <input name="in1" type="float" nodename="inputAlpha" />
     <input name="in2" type="float" interfacename="AlphaGain_in2" />
   </multiply>
   <add name="AlphaOffset" type="float">
     <input name="in1" type="float" nodename="AlphaGain" />
     <input name="in2" type="float" interfacename="AlphaOffset_in2" />
   </add>
   <multiply name="ColorGain" type="color3">
     <input name="in1" type="color3" nodename="inputColor" />
     <input name="in2" type="color3" interfacename="ColorGain_in2" />
   </multiply>
   <add name="ColorOffset" type="color3">
     <input name="in1" type="color3" nodename="ColorGain" />
     <input name="in2" type="color3" interfacename="ColorOffset_in2" />
   </add>
   <constant name="inputColor" type="color3">
     <input name="value" type="color3" interfacename="inputColor_value" />
   </constant>
   <constant name="inputAlpha" type="float">
     <input name="value" type="float" interfacename="inputAlpha_value" />
   </constant>
   <output name="out" type="color3" nodename="ColorOffset" />
   <output name="out1" type="float" nodename="AlphaOffset" />
   <input name="AlphaGain_in2" type="float" value="0.8" uiname="AlphaGain in2" uifolder="Common" />
   <input name="AlphaOffset_in2" type="float" value="1" uiname="AlphaOffset in2" uifolder="Common" />
   <input name="ColorGain_in2" type="color3" value="0.9, 0.9, 0.9" uiname="ColorGain in2" uifolder="Common" />
   <input name="ColorOffset_in2" type="color3" value="0.379147, 0.0341412, 0.0341412" uiname="ColorOffset in2" uifolder="Common" />
   <input name="inputColor_value" type="color3" value="0.5, 0.5, 0.5" uiname="inputColor value" uifolder="Common" />
   <input name="inputAlpha_value" type="float" value="1" uiname="inputAlpha value" uifolder="Common" />
 </nodegraph>
 <nodedef name="ND_test_colorcorrect" node="test_colorcorrect" version="1.0" isdefaultversion="false" nodegroup="adjustment" uiname="test_colorcorrect Version: 1.0" doc="This is version 1 of the definition for the graph: NG_test_colorcorrect">
   <input name="AlphaGain_in2" type="float" value="0.8" uiname="AlphaGain in2" uifolder="Common" />
   <input name="AlphaOffset_in2" type="float" value="1" uiname="AlphaOffset in2" uifolder="Common" />
   <input name="ColorGain_in2" type="color3" value="0.9, 0.9, 0.9" uiname="ColorGain in2" uifolder="Common" />
   <input name="ColorOffset_in2" type="color3" value="0.379147, 0.0341412, 0.0341412" uiname="ColorOffset in2" uifolder="Common" />
   <input name="inputColor_value" type="color3" value="0.5, 0.5, 0.5" uiname="inputColor value" uifolder="Common" />
   <input name="inputAlpha_value" type="float" value="1" uiname="inputAlpha value" uifolder="Common" />
   <output name="out" type="color3" />
   <output name="out1" type="float" />
 </nodedef>
 <nodegraph name="NG_test_colorcorrect" nodedef="ND_test_colorcorrect">
   <multiply name="AlphaGain" type="float">
     <input name="in1" type="float" nodename="inputAlpha" />
     <input name="in2" type="float" interfacename="AlphaGain_in2" />
   </multiply>
   <add name="AlphaOffset" type="float">
     <input name="in1" type="float" nodename="AlphaGain" />
     <input name="in2" type="float" interfacename="AlphaOffset_in2" />
   </add>
   <multiply name="ColorGain" type="color3">
     <input name="in1" type="color3" nodename="inputColor" />
     <input name="in2" type="color3" interfacename="ColorGain_in2" />
   </multiply>
   <add name="ColorOffset" type="color3">
     <input name="in1" type="color3" nodename="ColorGain" />
     <input name="in2" type="color3" interfacename="ColorOffset_in2" />
   </add>
   <constant name="inputColor" type="color3">
     <input name="value" type="color3" interfacename="inputColor_value" />
   </constant>
   <constant name="inputAlpha" type="float">
     <input name="value" type="float" interfacename="inputAlpha_value" />
   </constant>
   <output name="out" type="color3" nodename="ColorOffset" />
   <output name="out1" type="float" nodename="AlphaOffset" />
 </nodegraph>
</materialx>

Definition Created with Child

<?xml version="1.0"?>
<materialx version="1.39">
  <nodegraph name="test_colorcorrect">
    <multiply name="AlphaGain" type="float">
      <input name="in1" type="float" nodename="inputAlpha" />
      <input name="in2" type="float" interfacename="AlphaGain_in2" />
    </multiply>
    <add name="AlphaOffset" type="float">
      <input name="in1" type="float" nodename="AlphaGain" />
      <input name="in2" type="float" interfacename="AlphaOffset_in2" />
    </add>
    <multiply name="ColorGain" type="color3">
      <input name="in1" type="color3" nodename="inputColor" />
      <input name="in2" type="color3" interfacename="ColorGain_in2" />
    </multiply>
    <add name="ColorOffset" type="color3">
      <input name="in1" type="color3" nodename="ColorGain" />
      <input name="in2" type="color3" interfacename="ColorOffset_in2" />
    </add>
    <constant name="inputColor" type="color3">
      <input name="value" type="color3" interfacename="inputColor_value" />
    </constant>
    <constant name="inputAlpha" type="float">
      <input name="value" type="float" interfacename="inputAlpha_value" />
    </constant>
    <output name="out" type="color3" nodename="ColorOffset" />
    <output name="out1" type="float" nodename="AlphaOffset" />
    <input name="AlphaGain_in2" type="float" value="0.8" uiname="AlphaGain in2" uifolder="Common" />
    <input name="AlphaOffset_in2" type="float" value="1" uiname="AlphaOffset in2" uifolder="Common" />
    <input name="ColorGain_in2" type="color3" value="0.9, 0.9, 0.9" uiname="ColorGain in2" uifolder="Common" />
    <input name="ColorOffset_in2" type="color3" value="0.379147, 0.0341412, 0.0341412" uiname="ColorOffset in2" uifolder="Common" />
    <input name="inputColor_value" type="color3" value="0.5, 0.5, 0.5" uiname="inputColor value" uifolder="Common" />
    <input name="inputAlpha_value" type="float" value="1" uiname="inputAlpha value" uifolder="Common" />
  </nodegraph>
  <nodedef name="ND_test_colorcorrect" node="test_colorcorrect" version="1.0" isdefaultversion="false" nodegroup="adjustment" uiname="test_colorcorrect Version: 1.0" doc="This is version 1 of the definition for the graph: NG_test_colorcorrect">
    <nodegraph name="NG_test_colorcorrect">
      <multiply name="AlphaGain" type="float">
        <input name="in1" type="float" nodename="inputAlpha" />
        <input name="in2" type="float" interfacename="AlphaGain_in2" />
      </multiply>
      <add name="AlphaOffset" type="float">
        <input name="in1" type="float" nodename="AlphaGain" />
        <input name="in2" type="float" interfacename="AlphaOffset_in2" />
      </add>
      <multiply name="ColorGain" type="color3">
        <input name="in1" type="color3" nodename="inputColor" />
        <input name="in2" type="color3" interfacename="ColorGain_in2" />
      </multiply>
      <add name="ColorOffset" type="color3">
        <input name="in1" type="color3" nodename="ColorGain" />
        <input name="in2" type="color3" interfacename="ColorOffset_in2" />
      </add>
      <constant name="inputColor" type="color3">
        <input name="value" type="color3" interfacename="inputColor_value" />
      </constant>
      <constant name="inputAlpha" type="float">
        <input name="value" type="float" interfacename="inputAlpha_value" />
      </constant>
      <output name="out" type="color3" nodename="ColorOffset" />
      <output name="out1" type="float" nodename="AlphaOffset" />
    </nodegraph>
    <input name="AlphaGain_in2" type="float" value="0.8" uiname="AlphaGain in2" uifolder="Common" />
    <input name="AlphaOffset_in2" type="float" value="1" uiname="AlphaOffset in2" uifolder="Common" />
    <input name="ColorGain_in2" type="color3" value="0.9, 0.9, 0.9" uiname="ColorGain in2" uifolder="Common" />
    <input name="ColorOffset_in2" type="color3" value="0.379147, 0.0341412, 0.0341412" uiname="ColorOffset in2" uifolder="Common" />
    <input name="inputColor_value" type="color3" value="0.5, 0.5, 0.5" uiname="inputColor value" uifolder="Common" />
    <input name="inputAlpha_value" type="float" value="1" uiname="inputAlpha value" uifolder="Common" />
    <output name="out" type="color3" />
    <output name="out1" type="float" />
  </nodedef>
</materialx>

Graph Editor : Std Library Definition Using Child Nodegraph

func_nodedef_safepower.mp4

Graph Editor: Created Definition Using Child Nodegraph

Instance

Definition Expanded

kwokcb · 2025-05-21T20:23:18Z

source/MaterialXCore/Document.cpp

+            // So append them to the end of the implementation list assocaited 
+            // with any existing nodedef entry (or create a new one if does not exist).
+            //
+            for (const auto& [nodedefKey, appendImplementations] : nonFuncNodeDefMap)


Search order is strictly set here for definitions: functional defs first, all others after. Usage priority is decided elsewhere but generally it's a "first found" logic (per target).

For this initial check-in, we only look for child nodegraphs. Child implementations could be added if / when desired.

kwokcb · 2025-05-21T20:25:10Z

source/MaterialXCore/Node.cpp

@@ -719,7 +719,14 @@ void NodeGraph::modifyInterfaceName(const string& inputPath, const string& inter

 NodeDefPtr NodeGraph::getNodeDef() const
 {
-    NodeDefPtr nodedef = resolveNameReference<NodeDef>(getNodeDefString());
+    ElementPtr parent = getSelfNonConst()->getParent();


"Backwards" search looks for parent definitions now.

kwokcb · 2025-05-21T20:25:30Z

source/MaterialXCore/Definition.cpp

@@ -156,6 +156,12 @@ void Implementation::setNodeDef(ConstNodeDefPtr nodeDef)

 NodeDefPtr Implementation::getNodeDef() const
 {
+    ElementPtr parent = getSelfNonConst()->getParent();


"Backwards" search looks for parent definitions now.

kwokcb · 2025-05-21T20:26:43Z

libraries/stdlib/stdlib_defs.mtlx

@@ -2148,56 +2148,263 @@
    <input name="in1" type="float" value="0.0" />
    <input name="in2" type="float" value="1.0" />
    <output name="out" type="float" defaultinput="in1" />
+
+    <nodegraph name="NG_safepower_float">


Any / or all graphs could reside here. Both new and old mechanism still work.

Initial test.

f8ceb63

kwokcb mentioned this pull request May 21, 2025

Specification Proposal : "Functional" Node Definitions #2355

Open

kwokcb commented May 21, 2025

View reviewed changes

kwokcb added 7 commits May 22, 2025 07:53

Merge branch 'AcademySoftwareFoundation:main' into functional_nodedefs

a9cc157

Merge branch 'AcademySoftwareFoundation:main' into functional_nodedefs

b96d4cd

Merge branch 'AcademySoftwareFoundation:main' into functional_nodedefs

814e524

Merge branch 'AcademySoftwareFoundation:main' into functional_nodedefs

179a6d6

Merge branch 'AcademySoftwareFoundation:main' into functional_nodedefs

36a154f

Merge branch 'AcademySoftwareFoundation:main' into functional_nodedefs

cf7d0f2

Merge branch 'AcademySoftwareFoundation:main' into functional_nodedefs

8ef6904

kwokcb requested review from ld-kerley and ashwinbhat September 1, 2025 16:04

kwokcb added 5 commits September 3, 2025 07:03

Merge branch 'AcademySoftwareFoundation:main' into functional_nodedefs

c52561b

Add create options and unit test.

cad97bc

Add doc for DefinitionsOptions arg on addNodeDefFromGraph().

5ac34e5

Merge branch 'AcademySoftwareFoundation:main' into functional_nodedefs

4dc3ee1

Merge branch 'AcademySoftwareFoundation:main' into functional_nodedefs

7add695

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Function NodeDef Prototype #2401

Function NodeDef Prototype #2401

Uh oh!

kwokcb commented May 21, 2025 •

edited

Loading

Uh oh!

kwokcb May 21, 2025

Uh oh!

kwokcb May 21, 2025

Uh oh!

kwokcb May 21, 2025

Uh oh!

kwokcb May 21, 2025

Uh oh!

Uh oh!

Function NodeDef Prototype #2401

Are you sure you want to change the base?

Function NodeDef Prototype #2401

Uh oh!

Conversation

kwokcb commented May 21, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Draft Implementation

Changes

Tests

Unit Test Results

Definition Created with Sibling Reference

Definition Created with Child

Graph Editor : Std Library Definition Using Child Nodegraph

Graph Editor: Created Definition Using Child Nodegraph

Uh oh!

kwokcb May 21, 2025

Choose a reason for hiding this comment

Uh oh!

kwokcb May 21, 2025

Choose a reason for hiding this comment

Uh oh!

kwokcb May 21, 2025

Choose a reason for hiding this comment

Uh oh!

kwokcb May 21, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

kwokcb commented May 21, 2025 •

edited

Loading