ILM 1.37 merge update

CHANGELOG.md

@@ -1,16 +1,31 @@
 # Change Log
 
-## [1.36.5] - Development
+## [1.37.0] - Development
+
+Updated the MaterialX library to the v1.37 specification.  See the [changelist](http://www.materialx.org/assets/MaterialX.v1.37REV2.Changelist.pdf) for a complete list of updates in v1.37.  MaterialX documents from v1.36 and earlier are automatically upgraded at load-time.
+
+### Added
+- Added support for LookGroup elements.
+- Added support for the 'uisoftmin', 'uisoftmax', and 'uistep' attributes, updating Autodesk Standard Surface to leverage these features.
+- Added support for the 'doc' attribute.
+
+### Changed
+- Updated the set of standard nodes for v1.37.
+- Unified the rules for NodeDef outputs, with all NodeDefs defining their output set through Output children rather than 'type' attributes.
+- Replaced backdrop nodes with Backdrop elements.
+
+## [1.36.5] - 2020-01-11
 
 ### Added
-- Added a Load Environment option to the viewer, allowing new latitude-longitude HDR environments to be loaded at run-time.
-- Added an initial TextureBaker class, supporting baking of graph outputs to textures.
+- Added a Load Environment option to the viewer, allowing arbitrary latitude-longitude HDR environments to be loaded at run-time.
+- Added an initial TextureBaker class, supporting baking of procedural content to textures.
 - Added initial support for units, including the MaterialX\:\:Unit, MaterialX\:\:UnitDef, and MaterialX\:\:UnitTypeDef classes.
 - Added support for unit conversion in shader code generation.
 - Added support for Visual Studio 2019.
 
 ### Changed
-- Updated subsurface interface and logic for Autodesk Standard Surface.
+- Updated Autodesk Standard Surface to the latest interface and graph.
+- Updated the PyBind11 library to version 2.4.3.
 
 ## [1.36.4] - 2019-09-26
 

CONTRIBUTING.md

@@ -1,10 +1,10 @@
 Thank you for your interest in contributing to MaterialX!
 
 ## Contributor License Agreement
-Before contributing code to MaterialX, we ask that you sign a Contributor License Agreement (CLA).  In the `documents/Contributing` folder of the repo you can find the two possible CLAs:
+Before contributing code to MaterialX, we ask that you sign a Contributor License Agreement (CLA).  In the [documents/Contributing](documents/Contributing) folder of the repo you can find the two possible CLAs:
 
-- MaterialX_CLA_Corporate.pdf: please sign this one for corporate use
-- MaterialX_CLA_Individual.pdf: please sign this one if you're an individual contributor
+- [MaterialX_CLA_Corporate.pdf](documents/Contributing/MaterialX_CLA_Corporate.pdf): please sign this one for corporate use
+- [MaterialX_CLA_Individual.pdf](documents/Contributing/MaterialX_CLA_Individual.pdf): please sign this one if you're an individual contributor
 
 Once your CLA is signed, send it to [email protected] and wait for confirmation that we've received it.  After that, you can submit pull requests.
 

resources/Materials/TestSuite/_options.mtlx

@@ -78,10 +78,10 @@
       <parameter name="specularEnvironmentMethod" type="integer" value="1" />
 
       <!-- Suggested radiance IBL file path -->
-      <parameter name="radianceIBLPath" type="string" value="resources/Images/san_giuseppe_bridge.hdr" />
+      <parameter name="radianceIBLPath" type="string" value="resources/Images/Environments/san_giuseppe_bridge.hdr" />
 
       <!-- Suggested irradiance IBL file path -->
-      <parameter name="irradianceIBLPath" type="string" value="resources/Images/san_giuseppe_bridge_diffuse.hdr" />
+      <parameter name="irradianceIBLPath" type="string" value="resources/Images/Environments/san_giuseppe_bridge_diffuse.hdr" />
 
       <!-- Transforms UVs of loaded geometry -->
       <parameter name="transformUVs" type="matrix44" value="1.0f, 0.0f, 0.0f, -0.235f, 0.0f, -1.0f, 0.0f, 1.0f, 0.0f, 0.0f, 1.0f, 0.0f, 0.0f, 0.0f, 0.0f, 1.0f" />

source/MaterialXCore/Document.h

@@ -383,34 +383,6 @@ class Document : public GraphElement
     /// Return a vector of all NodeDef elements that match the given node name.
     vector<NodeDefPtr> getMatchingNodeDefs(const string& nodeName) const;
 
-    /// @}
-    /// @name Backdrop Elements
-    /// @{
-
-    /// Add a Backdrop to the document.
-    BackdropPtr addBackdrop(const string& name = EMPTY_STRING)
-    {
-        return addChild<Backdrop>(name);
-    }
-
-    /// Return the Backdrop, if any, with the given name.
-    BackdropPtr getBackdrop(const string& name) const
-    {
-        return getChildOfType<Backdrop>(name);
-    }
-
-    /// Return a vector of all Backdrop elements in the document.
-    vector<BackdropPtr> getBackdrops() const
-    {
-        return getChildrenOfType<Backdrop>();
-    }
-
-    /// Remove the Backdrop, if any, with the given name.
-    void removeBackdrop(const string& name)
-    {
-        removeChildOfType<Backdrop>(name);
-    }
-
     /// @}
     /// @name PropertySet Elements
     /// @{

source/MaterialXCore/Node.h

@@ -216,6 +216,34 @@ class GraphElement : public InterfaceElement
         removeChildOfType<Node>(name);
     }
 
+    /// @}
+    /// @name Backdrop Elements
+    /// @{
+
+    /// Add a Backdrop to the graph.
+    BackdropPtr addBackdrop(const string& name = EMPTY_STRING)
+    {
+        return addChild<Backdrop>(name);
+    }
+
+    /// Return the Backdrop, if any, with the given name.
+    BackdropPtr getBackdrop(const string& name) const
+    {
+        return getChildOfType<Backdrop>(name);
+    }
+
+    /// Return a vector of all Backdrop elements in the graph.
+    vector<BackdropPtr> getBackdrops() const
+    {
+        return getChildrenOfType<Backdrop>();
+    }
+
+    /// Remove the Backdrop, if any, with the given name.
+    void removeBackdrop(const string& name)
+    {
+        removeChildOfType<Backdrop>(name);
+    }
+
     /// @}
     /// @name Utility
     /// @{
@@ -288,7 +316,7 @@ class NodeGraph : public GraphElement
 };
 
 /// @class Backdrop
-/// A layout element used to contain, group and document other nodes.
+/// A layout element used to contain, group and document nodes within a graph.
 class Backdrop : public Element
 {
   public:

source/MaterialXGenShader/Nodes/HwImageNode.h

@@ -11,7 +11,7 @@
 namespace MaterialX
 {
 
-/// Extending the HwSourceCodeNodewith requirements for image nodes.
+/// Extending the HwSourceCodeNode with requirements for image nodes.
 class HwImageNode : public HwSourceCodeNode
 {
 public:

source/MaterialXGenShader/Nodes/SwitchNode.cpp

@@ -48,16 +48,13 @@ void SwitchNode::emitFunctionCall(const ShaderNode& node, GenContext& context, S
             {
                 shadergen.emitString("else ", stage);
             }
-            if (branch < 5)
-            {
-                // 'which' can be float, integer or boolean, 
-                // so always convert to float to make sure the comparison is valid
-                shadergen.emitString("if (float(", stage); 
-                shadergen.emitInput(which, context, stage);
-                shadergen.emitString(") < ", stage);
-                shadergen.emitValue(float(branch + 1), stage);
-                shadergen.emitString(")", stage);
-            }
+            // Convert to float to insure a valid comparison, since the 'which'
+            // input may be float, integer or boolean.
+            shadergen.emitString("if (float(", stage); 
+            shadergen.emitInput(which, context, stage);
+            shadergen.emitString(") < ", stage);
+            shadergen.emitValue(float(branch + 1), stage);
+            shadergen.emitString(")", stage);
             shadergen.emitLineEnd(stage, false);
 
             shadergen.emitScopeBegin(stage);

source/MaterialXRender/Harmonics.cpp

@@ -5,7 +5,6 @@
 
 #include <MaterialXRender/Harmonics.h>
 
-#include <cmath>
 #include <iostream>
 
 namespace MaterialX
@@ -25,6 +24,8 @@ const double COSINE_CONSTANT_0 = 1.0;
 const double COSINE_CONSTANT_1 = 2.0 / 3.0;
 const double COSINE_CONSTANT_2 = 1.0 / 4.0;
 
+const Color3d LUMA_COEFFS_REC709(0.2126, 0.7152, 0.0722);
+
 double imageXToPhi(unsigned int x, unsigned int width)
 {
     // Align spherical coordinates with texel centers by adding 0.5.
@@ -135,6 +136,41 @@ Sh3ColorCoeffs projectEnvironment(ConstImagePtr env, bool irradiance)
     return shEnv;
 }
 
+void computeDominantLight(ConstImagePtr env, Vector3& lightDir, Color3& lightColor)
+{
+    // Reference:
+    //   https://seblagarde.wordpress.com/2011/10/09/dive-in-sh-buffer-idea/
+
+    // Project the environment to spherical harmonics.
+    Sh3ColorCoeffs shEnv = projectEnvironment(env);
+
+    // Compute the dominant light direction.
+    Vector3d dir = Vector3d(shEnv[3].dot(LUMA_COEFFS_REC709),
+                            shEnv[1].dot(LUMA_COEFFS_REC709),
+                            shEnv[2].dot(LUMA_COEFFS_REC709)).getNormalized();
+
+    // Evaluate the dominant direction as spherical harmonics.
+    Sh3ScalarCoeffs shDir = evalDirection(dir);
+    Vector4d vDir(shDir[0], shDir[1], shDir[2], shDir[3]);
+
+    // Compute the dominant light color.
+    Vector4d vEnvR(shEnv[0][0], shEnv[1][0], shEnv[2][0], shEnv[3][0]);
+    Vector4d vEnvG(shEnv[0][1], shEnv[1][1], shEnv[2][1], shEnv[3][1]);
+    Vector4d vEnvB(shEnv[0][2], shEnv[1][2], shEnv[2][2], shEnv[3][2]);
+    Color3d color = Color3d(
+        std::max(vDir.dot(vEnvR), 0.0),
+        std::max(vDir.dot(vEnvG), 0.0),
+        std::max(vDir.dot(vEnvB), 0.0)) / vDir.dot(vDir);
+
+    // Convert to single-precision floats.
+    lightDir = Vector3((float) dir[0], (float) dir[1], (float) dir[2]);
+    lightColor = Color3((float) color[0], (float) color[1], (float) color[2]);
+
+    // Transform to match library conventions for latitude-longitude maps.
+    lightDir = Matrix44::createRotationY((float) PI / 2.0f).transformVector(lightDir);
+    lightDir = Matrix44::createScale(Vector3(1, 1, -1)).transformVector(lightDir);
+}
+
 ImagePtr renderEnvironment(const Sh3ColorCoeffs& shEnv, unsigned int width, unsigned int height)
 {
     ImagePtr env = Image::create(width, height, 3, Image::BaseType::FLOAT);

source/MaterialXRender/Harmonics.h

@@ -10,7 +10,6 @@
 /// Spherical harmonics functionality
 
 #include <MaterialXRender/Image.h>
-
 #include <MaterialXRender/Types.h>
 
 namespace MaterialX
@@ -53,12 +52,18 @@ using Sh3ScalarCoeffs = ShCoeffs<double, 3>;
 using Sh3ColorCoeffs = ShCoeffs<Color3d, 3>;
 
 /// Project an environment map to third-order SH, with an optional convolution
-///    to convert radiance to irradiance.
+/// to convert radiance to irradiance.
 /// @param env An environment map in lat-long format.
 /// @param irradiance If true, then the returned signal will be convolved
 ///    by a clamped cosine kernel to generate irradiance.
 /// @return The projection of the environment to third-order SH.
-Sh3ColorCoeffs projectEnvironment(ConstImagePtr env, bool irradiance);
+Sh3ColorCoeffs projectEnvironment(ConstImagePtr env, bool irradiance = false);
+
+/// Compute the dominant light direction and color of an environment map.
+/// @param env An environment map in lat-long format.
+/// @param lightDir Returns the dominant light direction of the environment.
+/// @param lightColor Returns the color of the light from the dominant direction.
+void computeDominantLight(ConstImagePtr env, Vector3& lightDir, Color3& lightColor);
 
 /// Render the given spherical harmonic signal to an environment map.
 /// @param shEnv The color signal of the environment encoded as third-order SH.

source/MaterialXRender/Image.cpp

@@ -168,6 +168,34 @@ Color4 Image::getTexelColor(unsigned int x, unsigned int y) const
     }
 }
 
+ImagePair Image::splitByLuminance(float luminance)
+{
+    ImagePtr underflowImage = Image::create(getWidth(), getHeight(), getChannelCount(), getBaseType());
+    ImagePtr overflowImage = Image::create(getWidth(), getHeight(), getChannelCount(), getBaseType());
+    underflowImage->createResourceBuffer();
+    overflowImage->createResourceBuffer();
+
+    for (unsigned int y = 0; y < getHeight(); y++)
+    {
+        for (unsigned int x = 0; x < getWidth(); x++)
+        {
+            Color4 envColor = getTexelColor(x, y);
+            Color4 underflowColor(
+                std::min(envColor[0], luminance),
+                std::min(envColor[1], luminance),
+                std::min(envColor[2], luminance), 1.0f);
+            Color4 overflowColor(
+                std::max(envColor[0] - underflowColor[0], 0.0f),
+                std::max(envColor[1] - underflowColor[1], 0.0f),
+                std::max(envColor[2] - underflowColor[2], 0.0f), 1.0f);
+            underflowImage->setTexelColor(x, y, underflowColor);
+            overflowImage->setTexelColor(x, y, overflowColor);
+        }
+    }
+
+    return std::make_pair(underflowImage, overflowImage);
+}
+
 void Image::createResourceBuffer()
 {
     releaseResourceBuffer();

source/MaterialXRender/Image.h

@@ -25,6 +25,9 @@ using ConstImagePtr = shared_ptr<const Image>;
 /// A map from strings to images.
 using ImageMap = std::unordered_map<string, ImagePtr>;
 
+/// A pair of images.
+using ImagePair = std::pair<ImagePtr, ImagePtr>;
+
 /// A function to perform image buffer deallocation
 using ImageBufferDeallocator = std::function<void(void*)>;
 
@@ -126,6 +129,10 @@ class Image
     /// or image resource buffer are invalid, then an exception is thrown.
     Color4 getTexelColor(unsigned int x, unsigned int y) const;
 
+    /// Split this image by the given luminance threshold, returning the
+    /// resulting underflow and overflow images.
+    ImagePair splitByLuminance(float luminance);
+
     /// Allocate a resource buffer for this image that matches its properties.
     void createResourceBuffer();
 

source/MaterialXRender/LightHandler.cpp

@@ -15,22 +15,23 @@ void LightHandler::addLightSource(NodePtr node)
     _lightSources.push_back(node);
 }
 
-void LightHandler::mapNodeDefToIdentiers(const vector<NodePtr>& nodes,
-                                         std::unordered_map<string, unsigned int>& ids)
+LightIdMap LightHandler::computeLightIdMap(const vector<NodePtr>& nodes)
 {
+    std::unordered_map<string, unsigned int> idMap;
     unsigned int id = 1;
     for (const auto& node : nodes)
     {
         auto nodedef = node->getNodeDef();
         if (nodedef)
         {
             const string& name = nodedef->getName();
-            if (!ids.count(name))
+            if (!idMap.count(name))
             {
-                ids[name] = id++;
+                idMap[name] = id++;
             }
         }
     }
+    return idMap;
 }
 
 void LightHandler::findLights(DocumentPtr doc, vector<NodePtr>& lights)
@@ -56,7 +57,7 @@ void LightHandler::registerLights(DocumentPtr doc, const vector<NodePtr>& lights
     if (!lights.empty())
     {
         // Create a list of unique nodedefs and ids for them
-        mapNodeDefToIdentiers(lights, _lightIdentifierMap);
+        _lightIdentifierMap = computeLightIdMap(lights);
         for (const auto& id : _lightIdentifierMap)
         {
             NodeDefPtr nodeDef = doc->getNodeDef(id.first);

source/MaterialXRender/LightHandler.h

@@ -21,10 +21,12 @@ class GenContext;
 /// Shared pointer to a LightHandler
 using LightHandlerPtr = std::shared_ptr<class LightHandler>;
 
+/// An unordered map from light names to light indices.
+using LightIdMap = std::unordered_map<string, unsigned int>;
+
 /// @class LightHandler
 /// Utility light handler for creating and providing
 /// light data for shader binding.
-///
 class LightHandler
 {
   public:
@@ -83,8 +85,7 @@ class LightHandler
 
     /// From a set of nodes, create a mapping of corresponding
     /// nodedef identifiers to numbers
-    void mapNodeDefToIdentiers(const vector<NodePtr>& nodes,
-                               std::unordered_map<string, unsigned int>& ids);
+    LightIdMap computeLightIdMap(const vector<NodePtr>& nodes);
 
     /// Find lights to use based on an input document
     /// @param doc Document to scan for lights

source/MaterialXRender/OiioImageLoader.h

@@ -18,7 +18,7 @@ namespace MaterialX
 using OiioImageLoaderPtr = std::shared_ptr<class OiioImageLoader>;
 
 /// @class OiioImageLoader
-/// Image file loader using OpenImageIO library
+/// OpenImageIO image file loader
 class OiioImageLoader : public ImageLoader
 {
   public: