Add code generation hints support (#1954)

Initial implementation of code generation hints, as described in the 1.39 specification

Author: kwokcb

libraries/bxdf/open_pbr_surface.mtlx

@@ -23,7 +23,7 @@
            doc="Index of refraction of the dielectric base." />
     <input name="specular_roughness_anisotropy" type="float" value="0.0" uimin="0.0" uimax="1.0" uiname="Specular Anisotropy" uifolder="Specular" uiadvanced="true"
            doc="The directional bias of the roughness of the metal/dielectric base, resulting in increasingly stretched highlights along the tangent direction." />
-    <input name="transmission_weight" type="float" value="0.0" uimin="0.0" uimax="1.0" uiname="Transmission Weight" uifolder="Transmission" uiadvanced="true"
+    <input name="transmission_weight" type="float" value="0.0" uimin="0.0" uimax="1.0" uiname="Transmission Weight" uifolder="Transmission" uiadvanced="true" hint="transparency"
            doc="Mixture weight between the transparent and opaque dielectric base. The greater the value the more transparent the material." />
     <input name="transmission_color" type="color3" value="1, 1, 1" uimin="0,0,0" uimax="1,1,1" uiname="Transmission Color" uifolder="Transmission" uiadvanced="true"
            doc="Controls color of the transparent base due to Beer's law volumetric absorption under the surface (reverts to a non-physical tint when transmission_depth is zero)." />
@@ -75,7 +75,7 @@
            doc="The amount of emitted light, as a luminance in nits." />
     <input name="emission_color" type="color3" value="1, 1, 1" uimin="0,0,0" uimax="1,1,1" uiname="Emission Color" uifolder="Emission"
            doc="The color of the emitted light." />
-    <input name="geometry_opacity" type="float" value="1" uimin="0" uimax="1" uiname="Opacity" uifolder="Geometry"
+    <input name="geometry_opacity" type="float" value="1" uimin="0" uimax="1" uiname="Opacity" uifolder="Geometry" hint="opacity"
            doc="The opacity of the entire material." />
     <input name="geometry_thin_walled" type="boolean" value="false" uiname="Thin Walled" uifolder="Geometry" uiadvanced="true"
            doc="If true the surface is double-sided and represents an infinitesimally thin shell. Suitable for extremely geometrically thin objects such as leaves or paper." />

resources/Materials/TestSuite/pbrlib/surfaceshader/transparency_hints.mtlx

@@ -0,0 +1,15 @@
+<?xml version="1.0"?>
+<materialx version="1.39" colorspace="lin_rec709">
+  <surfacematerial name="geom_hint" type="material">
+    <input name="surfaceshader" type="surfaceshader" nodename="geometric_opacity_hint" />
+  </surfacematerial>
+  <open_pbr_surface name="geometric_opacity_hint" type="surfaceshader">
+    <input name="geometry_opacity" type="float" value="0.5" />
+  </open_pbr_surface>
+  <surfacematerial name="transp_hint" type="material">
+    <input name="surfaceshader" type="surfaceshader" nodename="transparency_weight_hint" />
+  </surfacematerial>
+  <open_pbr_surface name="transparency_weight_hint" type="surfaceshader">
+    <input name="transmission_weight" type="float" value="0.8" />
+  </open_pbr_surface>
+</materialx>

source/MaterialXCore/Definition.cpp

@@ -100,6 +100,19 @@ InterfaceElementPtr NodeDef::getImplementation(const string& target) const
     return InterfaceElementPtr();
 }
 
+const StringMap NodeDef::getInputHints() const
+{
+    StringMap hints;
+    for (InputPtr input : getActiveInputs())
+    {
+        if (input->hasHint())
+        {
+            hints[input->getName()] = input->getHint();
+        }
+    }
+    return hints;
+}
+
 bool NodeDef::validate(string* message) const
 {
     bool res = true;

source/MaterialXCore/Definition.h

@@ -146,6 +146,13 @@ class MX_CORE_API NodeDef : public InterfaceElement
     ///    an Implementation element or a NodeGraph element.
     InterfaceElementPtr getImplementation(const string& target = EMPTY_STRING) const;
 
+    /// @}
+    /// @name Hints
+    /// @{
+
+    /// Return list of input hint pairs of the form { input_name, hint_string }
+    const StringMap getInputHints() const;
+
     /// @}
     /// @name Validation
     /// @{

source/MaterialXCore/Interface.cpp

@@ -20,6 +20,10 @@ const string InterfaceElement::TARGET_ATTRIBUTE = "target";
 const string InterfaceElement::VERSION_ATTRIBUTE = "version";
 const string InterfaceElement::DEFAULT_VERSION_ATTRIBUTE = "isdefaultversion";
 const string Input::DEFAULT_GEOM_PROP_ATTRIBUTE = "defaultgeomprop";
+const string Input::HINT_ATTRIBUTE = "hint";
+const string Input::TRANSPARENCY_HINT = "transparency";
+const string Input::OPACITY_HINT = "opacity";
+const string Input::ANISOTROPY_HINT = "anisotropy";
 const string Output::DEFAULT_INPUT_ATTRIBUTE = "defaultinput";
 
 //

source/MaterialXCore/Interface.h

@@ -219,6 +219,28 @@ class MX_CORE_API Input : public PortElement
     /// for this input.
     InputPtr getInterfaceInput() const;
 
+    /// @}
+    /// @name Hints
+    /// @{
+
+    /// Return true if the input has a hint
+    bool hasHint() const
+    {
+        return hasAttribute(HINT_ATTRIBUTE);
+    }
+
+    /// Return the code generation hint
+    const string& getHint() const
+    {
+        return getAttribute(HINT_ATTRIBUTE);
+    }
+
+    // Set the code generation hint
+    void setHint(const string& hint)
+    {
+        setAttribute(HINT_ATTRIBUTE, hint);
+    }
+
     /// @}
     /// @name Validation
     /// @{
@@ -232,6 +254,10 @@ class MX_CORE_API Input : public PortElement
   public:
     static const string CATEGORY;
     static const string DEFAULT_GEOM_PROP_ATTRIBUTE;
+    static const string HINT_ATTRIBUTE;
+    static const string TRANSPARENCY_HINT;
+    static const string OPACITY_HINT;
+    static const string ANISOTROPY_HINT;
 };
 
 /// @class Output

source/MaterialXGenShader/Util.cpp

@@ -16,10 +16,10 @@ using OpaqueTestPair = std::pair<string, float>;
 using OpaqueTestPairList = vector<OpaqueTestPair>;
 
 // Inputs on a surface shader which are checked for transparency
-const OpaqueTestPairList inputPairList = { { "opacity", 1.0f },
-                                           { "existence", 1.0f },
-                                           { "alpha", 1.0f },
-                                           { "transmission", 0.0f } };
+const OpaqueTestPairList DEFAULT_INPUT_PAIR_LIST = { { "opacity", 1.0f },
+                                                     { "existence", 1.0f },
+                                                     { "alpha", 1.0f },
+                                                     { "transmission", 0.0f } };
 
 const string MIX_CATEGORY("mix");
 const string MIX_FG_INPUT("fg");
@@ -116,6 +116,23 @@ bool isTransparentShaderNode(NodePtr node, NodePtr interfaceNode)
         return false;
     }
 
+    // Check against nodedef input hints
+    OpaqueTestPairList inputPairList = DEFAULT_INPUT_PAIR_LIST;
+    NodeDefPtr nodeDef = node->getNodeDef();
+    StringMap nodeDefList = nodeDef ? nodeDef->getInputHints() : StringMap();
+    for (auto &item : nodeDefList)
+    {
+        string inputName = item.first;
+        if (item.second == Input::TRANSPARENCY_HINT)
+        {
+            inputPairList.push_back(std::make_pair(inputName, 0.0f) );
+        }
+        else if (item.second == Input::OPACITY_HINT)
+        {
+            inputPairList.push_back(std::make_pair(inputName, 1.0f));
+        }
+    }
+
     // Check against the interface if a node is passed in to check against
     OpaqueTestPairList interfaceNames;
     if (interfaceNode)
@@ -167,8 +184,8 @@ bool isTransparentShaderNode(NodePtr node, NodePtr interfaceNode)
             NodePtr inputNode = checkInput->getConnectedNode();
             if (inputNode)
             {
-                NodeDefPtr nodeDef = inputNode->getNodeDef();
-                string nodeGroup = nodeDef ? nodeDef->getAttribute(NodeDef::NODE_GROUP_ATTRIBUTE) : EMPTY_STRING;
+                NodeDefPtr inputNodeDef = inputNode->getNodeDef();
+                string nodeGroup = inputNodeDef ? inputNodeDef->getAttribute(NodeDef::NODE_GROUP_ATTRIBUTE) : EMPTY_STRING;
                 if (nodeGroup != NodeDef::ADJUSTMENT_NODE_GROUP &&
                     nodeGroup != NodeDef::CHANNEL_NODE_GROUP)
                 {