Add Functional NodeDef Support

resources/Materials/TestSuite/stdlib/definition/functional_nodedef.mtlx

@@ -0,0 +1,79 @@
+<?xml version="1.0"?>
+<materialx version="1.39">
+  <nodegraph name="NG_test_colorcorrect_reference">
+    <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>
+  <test_colorcorrect name="test_colorcorrect_instance" version="1.0" type="multioutput">
+    <input name="inputColor_value" type="color3" value="0.0, 0.0, 0.0" />
+    <input name="ColorOffset_in2" type="color3" value="1.0, 0.0, 0.0" />
+    <output name="out" type="color3" />
+  </test_colorcorrect>
+  <surface_unlit name="surface_unlit" type="surfaceshader">
+    <input name="emission_color" type="color3" output="out" nodename="test_colorcorrect_instance" />
+  </surface_unlit>
+</materialx>

source/MaterialXCore/Definition.cpp

@@ -156,6 +156,12 @@ void Implementation::setNodeDef(ConstNodeDefPtr nodeDef)
 
 NodeDefPtr Implementation::getNodeDef() const
 {
+    ElementPtr parent = getSelfNonConst()->getParent();
+    NodeDefPtr nodedef = parent->asA<NodeDef>();
+    if (nodedef)
+    {
+        return nodedef;
+    }
     return resolveNameReference<NodeDef>(getNodeDefString());
 }
 

source/MaterialXCore/Document.cpp

@@ -45,6 +45,7 @@ class Document::Cache
             portElementMap.clear();
             nodeDefMap.clear();
             implementationMap.clear();
+            std::unordered_map<string, std::vector<InterfaceElementPtr>> funcNodeDefMap;
 
             // Traverse the document to build a new cache.
             for (ElementPtr elem : doc.lock()->traverseTree())
@@ -79,6 +80,14 @@ class Document::Cache
                     if (nodeDef)
                     {
                         nodeDefMap[nodeDef->getQualifiedName(nodeString)].push_back(nodeDef);
+
+                        // Look for child nodegraph implementations
+                        vector<NodeGraphPtr> nodeGraphs = nodeDef->getChildrenOfType<NodeGraph>();
+                        for (NodeGraphPtr nodeGraph : nodeGraphs)
+                        {
+                            funcNodeDefMap[elem->getName()].push_back(nodeGraph);
+                        }
+
                     }
                 }
                 if (!nodeDefString.empty())
@@ -110,6 +119,16 @@ class Document::Cache
                 }
             }
 
+            // Functional node definitions have lower precedence than non-functional ones.
+            // So append them to the back of implementation list associated
+            // with any existing nodedef entry (or create a new one if does not exist).
+            //
+            for (const auto& [nodedefKey, appendImplementations] : funcNodeDefMap)
+            {
+                auto& implementations = implementationMap[nodedefKey];
+                implementations.insert(implementations.end(), appendImplementations.begin(), appendImplementations.end());
+            }
+
             valid = true;
         }
     }
@@ -147,7 +166,8 @@ void Document::initialize()
 }
 
 NodeDefPtr Document::addNodeDefFromGraph(NodeGraphPtr nodeGraph, const string& nodeDefName,
-                                         const string& category, const string& newGraphName)
+                                         const string& category, const string& newGraphName,
+                                         DefinitionOptions *options)
 {
     if (category.empty())
     {
@@ -159,26 +179,34 @@ NodeDefPtr Document::addNodeDefFromGraph(NodeGraphPtr nodeGraph, const string& n
         throw Exception("Cannot create duplicate nodedef: " + nodeDefName);
     }
 
-    if (getNodeGraph(newGraphName))
+    bool addAsChild = options ? options->addImplementationAsChild : false;
+
+    if (!addAsChild && getNodeGraph(newGraphName))
     {
         throw Exception("Cannot create duplicate nodegraph: " + newGraphName);
     }
 
+    // Create a new nodedef and set its category
+    NodeDefPtr nodeDef = addNodeDef(nodeDefName, EMPTY_STRING);
+    nodeDef->setNodeString(category);
+
     // Create a new functional nodegraph, and copy over the
     // contents from the compound nodegraph
-    NodeGraphPtr graph = addNodeGraph(newGraphName);
+    NodeGraphPtr graph = !addAsChild ? addNodeGraph(newGraphName) : nodeDef->addChild<NodeGraph>(newGraphName);
     graph->copyContentFrom(nodeGraph);
 
     for (auto graphChild : graph->getChildren())
     {
         graphChild->removeAttribute(Element::XPOS_ATTRIBUTE);
         graphChild->removeAttribute(Element::YPOS_ATTRIBUTE);
     }
-    graph->setNodeDefString(nodeDefName);
 
-    // Create a new nodedef and set its category
-    NodeDefPtr nodeDef = addNodeDef(nodeDefName, EMPTY_STRING);
-    nodeDef->setNodeString(category);
+    // Reference from nodegraph to nodedef is not required
+    // as the graph is a child of the nodedef.
+    if (!addAsChild)
+    {
+        graph->setNodeDefString(nodeDefName);
+    }
 
     // Expose any existing interfaces from the graph.
     // Any connection attributes ("nodegraph", "nodename", "interfacename") on the

source/MaterialXCore/Document.h

@@ -23,6 +23,8 @@ using DocumentPtr = shared_ptr<Document>;
 /// A shared pointer to a const Document
 using ConstDocumentPtr = shared_ptr<const Document>;
 
+class DefinitionOptions;
+
 /// @class Document
 /// A MaterialX document, which represents the top-level element in the
 /// MaterialX ownership hierarchy.
@@ -361,9 +363,11 @@ class MX_CORE_API Document : public GraphElement
     /// @param newGraphName Name of new functional NodeGraph.
     /// @param nodeDefName Name of new NodeDef
     /// @param category Category of the new NodeDef
+    /// @param options Optional creation options. Default is nullptr.
     /// @return New declaration if successful.
     NodeDefPtr addNodeDefFromGraph(NodeGraphPtr nodeGraph, const string& nodeDefName,
-                                   const string& category, const string& newGraphName);
+                                   const string& category, const string& newGraphName,
+                                   DefinitionOptions * options = nullptr);
 
     /// Return the NodeDef, if any, with the given name.
     NodeDefPtr getNodeDef(const string& name) const
@@ -708,6 +712,15 @@ class MX_CORE_API Document : public GraphElement
     std::unique_ptr<Cache> _cache;
 };
 
+/// @class DefinitionOptions
+/// Options for defining a NodeDef from an immplementation
+class MX_CORE_API DefinitionOptions
+{
+public:
+    /// Add implementation as child of NodeDef as opposed a sibliing.
+    bool addImplementationAsChild = false;
+};
+
 /// Create a new Document.
 /// @relates Document
 MX_CORE_API DocumentPtr createDocument();

source/MaterialXCore/Node.cpp

@@ -741,7 +741,14 @@ void NodeGraph::modifyInterfaceName(const string& inputPath, const string& inter
 
 NodeDefPtr NodeGraph::getNodeDef() const
 {
-    NodeDefPtr nodedef = resolveNameReference<NodeDef>(getNodeDefString());
+    ElementPtr parent = getSelfNonConst()->getParent();
+    NodeDefPtr nodedef = parent->asA<NodeDef>();
+    if (nodedef)
+    {
+        return nodedef;
+    }
+
+    nodedef = resolveNameReference<NodeDef>(getNodeDefString());
     // If not directly defined look for an implementation which has a nodedef association
     if (!nodedef)
     {

source/MaterialXTest/MaterialXCore/Node.cpp

@@ -12,6 +12,8 @@
 #include <MaterialXFormat/XmlIo.h>
 #include <MaterialXFormat/Util.h>
 
+#include <iostream>
+
 namespace mx = MaterialX;
 
 bool isTopologicalOrder(const std::vector<mx::ElementPtr>& elems)
@@ -675,7 +677,64 @@ TEST_CASE("Organization", "[nodegraph]")
     CHECK(nodeGraph->getBackdrops().empty());
 }
 
-TEST_CASE("Node Definition Creation", "[nodedef]")
+void testFunctionalNodeDef()
+{
+    mx::FileSearchPath searchPath = mx::getDefaultDataSearchPath();
+    mx::DocumentPtr doc = mx::createDocument();
+    mx::readFromXmlFile(doc, "resources/Materials/TestSuite/stdlib/definition/functional_nodedef.mtlx", searchPath);
+
+    std::vector<mx::NodeDefPtr> nodedefs = doc->getNodeDefs();
+    for (mx::NodeDefPtr nodeDef : nodedefs)
+    {
+        std::string nodeDefName = nodeDef->getName();
+        std::string nodeGraphName = "NG_" + nodeDefName.substr(3); // Remove the 'ND_' prefix
+
+        mx::InterfaceElementPtr implementation = nodeDef->getImplementation();
+        REQUIRE(implementation != nullptr);
+        std::string msg = "Testing NodeDef: " + nodeDefName + " with implementation: " +  implementation->getName();
+        INFO(msg);
+        mx::NodeGraphPtr functionalNodeGraph = implementation->asA<mx::NodeGraph>();
+        REQUIRE(functionalNodeGraph != nullptr);
+        if (functionalNodeGraph)
+        {
+            // Test that the child nodegraph is found via implementation search
+            REQUIRE(functionalNodeGraph->getName() == nodeGraphName);
+
+            // Test that this is actually a child nodegraph of the NodeDef
+            std::vector<mx::NodeGraphPtr> childNodeGraphs = nodeDef->getChildrenOfType<mx::NodeGraph>();
+            for (mx::NodeGraphPtr childNodeGraph : childNodeGraphs)
+            {
+                if (childNodeGraph->getName() == nodeGraphName)
+                {
+                    // Test that the child nodegraph is the functional graph
+                    REQUIRE(childNodeGraph == functionalNodeGraph);
+                }
+            }
+        }
+
+        std::string referenceGraphName = nodeGraphName + "_reference";
+        mx::NodeGraphPtr referenceNodeGraph = doc->getNodeGraph(referenceGraphName);
+        REQUIRE(referenceNodeGraph != nullptr);
+        if (referenceNodeGraph)
+        {
+            referenceNodeGraph->setNodeDefString(nodeDefName);
+
+            mx::InterfaceElementPtr implementation = nodeDef->getImplementation();
+            REQUIRE(implementation != nullptr);
+            std::string msg = "Testing NodeDef: " + nodeDefName + " with implementation: " +  implementation->getName();
+            INFO(msg);
+            mx::NodeGraphPtr functionalNodeGraph = implementation->asA<mx::NodeGraph>();
+            REQUIRE(functionalNodeGraph != nullptr);
+            if (functionalNodeGraph)
+            {
+                // Test the functional node graph is the reference graph 
+                REQUIRE(functionalNodeGraph->getName() == referenceGraphName);
+            }
+        }
+    }
+}
+
+void testNodeDefCreationFromGraph(mx::DefinitionOptions options)
 {
     mx::FileSearchPath searchPath = mx::getDefaultDataSearchPath();
     mx::DocumentPtr stdlib = mx::createDocument();
@@ -714,10 +773,12 @@ TEST_CASE("Node Definition Creation", "[nodedef]")
         bool isDefaultVersion = false;
         const std::string NODENAME = graph->getName();
 
+
         // Create a new functional graph and definition from a compound graph
+        bool addAsChild = options.addImplementationAsChild;
         std::string newNodeDefName = doc->createValidChildName("ND_" + graph->getName());
         std::string newGraphName = doc->createValidChildName("NG_" + graph->getName());
-        mx::NodeDefPtr nodeDef = doc->addNodeDefFromGraph(graph, newNodeDefName, NODENAME, newGraphName);
+        mx::NodeDefPtr nodeDef = doc->addNodeDefFromGraph(graph, newNodeDefName, NODENAME, newGraphName, &options);
         REQUIRE(nodeDef != nullptr);
         nodeDef->setVersionString(VERSION1);
         nodeDef->setDefaultVersion(isDefaultVersion);
@@ -759,9 +820,16 @@ TEST_CASE("Node Definition Creation", "[nodedef]")
         }
 
         // Check validity of new functional nodegraph
-        mx::NodeGraphPtr newGraph = doc->getNodeGraph(newGraphName);
+        mx::NodeGraphPtr newGraph = !addAsChild ? doc->getNodeGraph(newGraphName) : nodeDef->getChildOfType<mx::NodeGraph>(newGraphName);
         REQUIRE(newGraph != nullptr);
-        REQUIRE(newGraph->getNodeDefString() == newNodeDefName);
+        if (!addAsChild)
+        {
+            REQUIRE(newGraph->getNodeDefString() == newNodeDefName);
+        }
+        else
+        {
+            REQUIRE(newGraph->getNodeDefString().empty());
+        }
         mx::ConstInterfaceElementPtr decl = newGraph->getDeclaration();
         REQUIRE(decl->getName() == nodeDef->getName());
         REQUIRE(doc->validate());
@@ -826,6 +894,28 @@ TEST_CASE("Node Definition Creation", "[nodedef]")
     REQUIRE(doc->validate());
 }
 
+TEST_CASE("Node Definition Creation", "[nodedef_create]")
+{
+    mx::DefinitionOptions defOptions;
+
+    SECTION("Without implementation as child")
+    {
+        defOptions.addImplementationAsChild = false;
+        testNodeDefCreationFromGraph(defOptions);
+    }
+
+    SECTION("With implementation as child")
+    {
+        defOptions.addImplementationAsChild = true;
+        testNodeDefCreationFromGraph(defOptions);
+    }
+
+    SECTION("Functional NodeDef test")
+    {
+        testFunctionalNodeDef();
+    }
+}
+
 TEST_CASE("Set Name Global", "[node, nodegraph]")
 {
     mx::DocumentPtr doc = mx::createDocument();

source/PyMaterialX/PyMaterialXCore/PyDocument.cpp

@@ -26,6 +26,9 @@ void bindPyDocument(py::module& mod)
 {
     mod.def("createDocument", &mx::createDocument);
 
+    py::class_<mx::DefinitionOptions>(mod, "DefinitionOptions")
+        .def_readwrite("addImplementationAsChild", &mx::DefinitionOptions::addImplementationAsChild);
+
     py::class_<mx::Document, mx::DocumentPtr, mx::GraphElement>(mod, "Document")
         .def("initialize", &mx::Document::initialize)
         .def("copy", &mx::Document::copy)
@@ -74,7 +77,7 @@ void bindPyDocument(py::module& mod)
         .def("removeTypeDef", &mx::Document::removeTypeDef)
         .def("addNodeDef", &mx::Document::addNodeDef,
             py::arg("name") = mx::EMPTY_STRING, py::arg("type") = mx::DEFAULT_TYPE_STRING, py::arg("node") = mx::EMPTY_STRING)
-        .def("addNodeDefFromGraph", (mx::NodeDefPtr (mx::Document::*)(mx::NodeGraphPtr, const std::string&, const std::string&, const std::string&)) & mx::Document::addNodeDefFromGraph)
+        .def("addNodeDefFromGraph", (mx::NodeDefPtr (mx::Document::*)(mx::NodeGraphPtr, const std::string&, const std::string&, const std::string&, mx::DefinitionOptions*)) & mx::Document::addNodeDefFromGraph)
         .def("addNodeDefFromGraph", (mx::NodeDefPtr(mx::Document::*)(mx::NodeGraphPtr, const std::string&, const std::string&, const std::string&,
             bool, const std::string&, const std::string& )) & PyBindDocument::old_addNodeDefFromGraph)
         .def("getNodeDef", &mx::Document::getNodeDef)