MATX-236 - Code documentation and some cleanup. (#595)

* Moved VP2 smart pointers to MayaUtil for better discoverability.

* WIP MayaUtil documentation.

* WIP on doxygen comments.

* Doxygen comments for the remaining headers plus minor fixes.

* Minor doxygen fixes.

* "One or more"

source/MaterialXContrib/MaterialXMaya/CreateMaterialXNodeCmd.h

@@ -1,6 +1,9 @@
 #ifndef MATERIALX_MAYA_CREATENODECMD_H
 #define MATERIALX_MAYA_CREATENODECMD_H
 
+/// @file
+/// Maya command for creating MaterialX shading nodes.
+
 #include <maya/MPxCommand.h>
 #include <maya/MDGModifier.h>
 
@@ -14,21 +17,25 @@ namespace mx = MaterialX;
 namespace MaterialXMaya
 {
 
-///
-///
+/// @class CreateMaterialXNodeCmd
+/// Creates one or more MaterialX nodes from the specified MaterialX document.
 ///
 class CreateMaterialXNodeCmd : MPxCommand
 {
   public:
     CreateMaterialXNodeCmd();
     ~CreateMaterialXNodeCmd() override;
 
+    /// @name Maya API methods
+    /// @{
     MStatus doIt(const MArgList&) override;
     bool isUndoable() { return false; }
 
     static MSyntax newSyntax();
     static void* creator();
+    /// @}
 
+    /// The name of the command in MEL
     static MString NAME;
 
   private:
@@ -40,13 +47,16 @@ class CreateMaterialXNodeCmd : MPxCommand
         TEXTURE     ///< A texture shading node
     };
 
-    /// Create a new Maya node for a given renderable element
-    /// @param document Document containing the element
-    /// @param renderableElement Element to use
-    /// @param nodeTypeToCreate The type of shading node to create
-    /// @param documentFilePath Path to document
-    /// @param searchPath Shader generation source paths
-    /// @return Name of Maya node created
+    /// Create a new Maya node for a given renderable element.
+    /// @param document The document containing the element.
+    /// @param renderableElement The element to use.
+    /// @param nodeTypeToCreate The type of shading node to create.
+    /// @param documentFilePath Path to the document.
+    /// @param searchPath Shader generation source paths.
+    /// @param envRadianceFileName The file name of the environment map to use for specular shading.
+    /// @param envIrradianceFileName The file name of the environment map to use for diffuse shading.
+    /// @return Name of Maya node created.
+    ///
     std::string createNode(
         mx::DocumentPtr document,
         mx::TypedElementPtr renderableElement,
@@ -56,6 +66,7 @@ class CreateMaterialXNodeCmd : MPxCommand
         const MString& envRadianceFileName,
         const MString& envIrradianceFileName );
 
+    /// Used to make the necessary changes to Maya's dependency graph.
     MDGModifier _dgModifier;
 };
 

source/MaterialXContrib/MaterialXMaya/MaterialXNode.cpp

@@ -38,11 +38,11 @@ MObject MaterialXNode::ENV_IRRADIANCE_ATTRIBUTE;
 
 MObject MaterialXNode::OUT_ATTRIBUTE;
 
-const MTypeId MaterialXTextureNode::MATERIALX_TEXTURE_NODE_TYPEID(0x00042403);
-const MString MaterialXTextureNode::MATERIALX_TEXTURE_NODE_TYPENAME("MaterialXTexture");
+const MTypeId MaterialXTextureNode::MATERIALX_TEXTURE_NODE_TYPEID = 0x00042403;
+const MString MaterialXTextureNode::MATERIALX_TEXTURE_NODE_TYPENAME = "MaterialXTexture";
 
-const MTypeId MaterialXSurfaceNode::MATERIALX_SURFACE_NODE_TYPEID(0x00042404);
-const MString MaterialXSurfaceNode::MATERIALX_SURFACE_NODE_TYPENAME("MaterialXSurface");
+const MTypeId MaterialXSurfaceNode::MATERIALX_SURFACE_NODE_TYPEID = 0x00042404;
+const MString MaterialXSurfaceNode::MATERIALX_SURFACE_NODE_TYPENAME = "MaterialXSurface";
 
 MObject MaterialXSurfaceNode::VP2_TRANSPARENCY_ATTRIBUTE;
 

source/MaterialXContrib/MaterialXMaya/MaterialXNode.h

@@ -1,6 +1,9 @@
 #ifndef MATERIALX_MAYA_MATERIALXNODE_H
 #define MATERIALX_MAYA_MATERIALXNODE_H
 
+/// @file
+/// Maya shading node classes.
+
 #include <MaterialXCore/Document.h>
 
 #include <maya/MPxNode.h>
@@ -13,12 +16,16 @@ namespace MaterialXMaya
 
 class OgsFragment;
 
+/// @class MaterialXNode
+/// The base class for both surface and texture shading nodes.
 class MaterialXNode : public MPxNode
 {
   public:
     MaterialXNode();
     ~MaterialXNode() override;
 
+    /// @name Maya API methods
+    /// @{
     static void* creator();
     static MStatus initialize();
 
@@ -27,30 +34,45 @@ class MaterialXNode : public MPxNode
 
     bool getInternalValue(const MPlug&, MDataHandle&) override;
     bool setInternalValue(const MPlug&, const MDataHandle&) override;
-
+    /// @}
+
+    /// Set the attribute values and the OGS fragment owned by the node
+    /// when creating the node with CreateMaterialXNodeCmd.
+    /// @param documentFilePath The path to the MaterialX document file.
+    /// @param elementPath The path to the MaterialX element within the document.
+    /// @param envRadianceFileName The file name of the environment map to use for specular shading.
+    /// @param envIrradianceFileName The file name of the environment map to use for diffuse shading.
+    /// @param ogsFragment An object representing an OGS shade fragment created by the command for this node.
+    ///     The ownership of the fragment is transfered to the node.
+    ///
     void setData(   const MString& documentFilePath,
                     const MString& elementPath,
                     const MString& envRadianceFileName,
                     const MString& envIrradianceFileName,
-                    std::unique_ptr<OgsFragment>&& ); 
+                    std::unique_ptr<OgsFragment>&& ogsFragment );
 
+    /// Reloads the document, regenerates the OGS fragment and refreshes the node in the viewport.
     void reloadDocument();
 
+    /// Return the OGS fragment.
     const OgsFragment* getOgsFragment() const
     {
         return _ogsFragment.get();
     }
 
+    /// Return the document file path.
     const MString& getDocumentFilePath() const
     {
         return _documentFilePath;
     }
 
+    /// Return the file name of the environment map to use for specular shading.
     const MString& getEnvRadianceFileName() const
     {
         return _envRadianceFileName;
     }
 
+    /// Return the file name of the environment map to use for diffuse shading.
     const MString& getEnvIrradianceFileName() const
     {
         return _envIrradianceFileName;
@@ -59,36 +81,56 @@ class MaterialXNode : public MPxNode
     static const MTypeId MATERIALX_NODE_TYPEID;
     static const MString MATERIALX_NODE_TYPENAME;
 
-    /// Attribute holding a path to MaterialX document file
+    /// @name Attribute holding the path to the MaterialX document file.
+    /// @{
     static const MString DOCUMENT_ATTRIBUTE_LONG_NAME;
     static const MString DOCUMENT_ATTRIBUTE_SHORT_NAME;
     static MObject DOCUMENT_ATTRIBUTE;
+    /// @}
 
-    /// Attribute holding a MaterialX element name
+    /// @name Attribute holding the path to the MaterialX element within the document.
+    /// @{
     static const MString ELEMENT_ATTRIBUTE_LONG_NAME;
     static const MString ELEMENT_ATTRIBUTE_SHORT_NAME;
     static MObject ELEMENT_ATTRIBUTE;
+    /// @}
 
+    /// @name Attribute holding the file name of the environment map to use for specular shading.
+    /// @{
     static const MString ENV_RADIANCE_ATTRIBUTE_LONG_NAME;
     static const MString ENV_RADIANCE_ATTRIBUTE_SHORT_NAME;
     static MObject ENV_RADIANCE_ATTRIBUTE;
+    /// @}
 
+    /// @name Attribute holding the file name of the environment map to use for diffuse shading.
+    /// @{
     static const MString ENV_IRRADIANCE_ATTRIBUTE_LONG_NAME;
     static const MString ENV_IRRADIANCE_ATTRIBUTE_SHORT_NAME;
     static MObject ENV_IRRADIANCE_ATTRIBUTE;
+    /// @}
 
+    /// The output color attribute, required to correctly connect the node to a shading group.
+    /// Maps onto an output parameter with the same name in the generated OGS shade fragment.
     static MObject OUT_ATTRIBUTE;
 
   protected:
+    /// An object representing an OGS shade fragment generated for this node.
     std::unique_ptr<OgsFragment> _ogsFragment;
 
   private:
+    /// If the current document pointer is null, creates a new document based
+    /// on the the document file path attribute.
+    /// (Re)generates the OGS fragment based on the element path attribute and
+    /// registers it in VP2 under a unique name.
     void createAndRegisterFragment();
 
+    /// @name Storage for internal Maya attributes.
+    /// @{
     MString _documentFilePath, _elementPath;
 
     MString _envRadianceFileName = "goegap_4k_dim.hdr";
     MString _envIrradianceFileName = "goegap_4k_dim.convolved.hdr";
+    /// @}
 
     /// The OgsFragment keeps a shared pointer to the document it was created
     /// from but we also keep another shared pointer here to avoid reloading
@@ -97,6 +139,10 @@ class MaterialXNode : public MPxNode
     mx::DocumentPtr _document;
 };
 
+/// @class MaterialXTextureNode
+/// MaterialX texture shading node, accessible from the Hypershade under the
+/// 2D Textures category. The output attribute can be connected to an input on
+/// a surface node.
 class MaterialXTextureNode : public MaterialXNode
 {
 public:
@@ -108,6 +154,10 @@ class MaterialXTextureNode : public MaterialXNode
     static const MString MATERIALX_TEXTURE_NODE_TYPENAME;
 };
 
+/// @class MaterialXSurfaceNode
+/// MaterialX surface shading node, accessible from the Hypershade under the
+/// Surface category and available for assignment to a shape via the Marking
+/// Menu.
 class MaterialXSurfaceNode : public MaterialXNode
 {
 public:
@@ -120,6 +170,11 @@ class MaterialXSurfaceNode : public MaterialXNode
     static const MTypeId MATERIALX_SURFACE_NODE_TYPEID;
     static const MString MATERIALX_SURFACE_NODE_TYPENAME;
 
+    /// The input transparency attribute, registered in VP2 as such by
+    /// MaterialXMaya::SurfaceOverride::transparencyParameter().
+    /// Stores a dummy value set above 0 if the surface is internally
+    /// determined by MaterialX to be transparent. This makes VP2 render this
+    /// surface in transparency passes.
     static MObject VP2_TRANSPARENCY_ATTRIBUTE;
 };
 

source/MaterialXContrib/MaterialXMaya/MaterialXUtil.cpp

@@ -60,8 +60,6 @@ mx::TypedElementPtr getRenderableElement(mx::DocumentPtr document,
                                          const std::vector<mx::TypedElementPtr>& renderableElements, 
                                          const std::string& desiredElementPath)
 {
-
-
     if (!desiredElementPath.empty())
     {
         mx::ElementPtr element = document->getDescendant(desiredElementPath);

source/MaterialXContrib/MaterialXMaya/MaterialXUtil.h

@@ -1,6 +1,9 @@
 #ifndef MATERIALX_MAYA_MATERIALXUTIL_H
 #define MATERIALX_MAYA_MATERIALXUTIL_H
 
+/// @file
+/// MaterialX utilities.
+
 #include <MaterialXCore/Document.h>
 #include <MaterialXCore/Interface.h>
 #include <MaterialXFormat/File.h>
@@ -17,14 +20,15 @@ namespace MaterialXUtil
 mx::FilePath findInSubdirectories(const mx::FileSearchPath& searchPaths,
                                   const mx::FilePath& filePath);
 
-/// Load in a document and import associated libraries
+/// Load in a document and import associated libraries.
 mx::DocumentPtr loadDocument(const std::string& materialXDocumentPath,
                              mx::ConstDocumentPtr libraryDocument);
 
-/// Given an element path return a pointer to it within a document if it is considered to be renderable.
-/// @param document Document to examine
+/// Given an element path return a pointer to the element within a document if
+/// it is considered to be renderable.
+/// @param document Document to examine.
 /// @param renderableElements List of elements in the document that are considered to be renderable.
-/// @param elementPath Path to element to find
+/// @param desiredElementPath Path to element to find.
 mx::TypedElementPtr getRenderableElement(mx::DocumentPtr document,
                                         const std::vector<mx::TypedElementPtr>& renderableElements,
                                         const std::string& desiredElementPath);

source/MaterialXContrib/MaterialXMaya/MayaUtil.cpp

@@ -44,5 +44,37 @@ void registerFragment(const std::string& fragmentName, const std::string& fragme
     }
 }
 
+void TextureDeleter::operator()(MHWRender::MTexture* texture)
+{
+    if (!texture)
+    {
+        return;
+    }
+
+    MHWRender::MRenderer* const renderer = MRenderer::theRenderer();
+    if (!renderer)
+    {
+        return;
+    }
+
+    MHWRender::MTextureManager* const
+        textureMgr = renderer->getTextureManager();
+
+    if (!textureMgr)
+    {
+        return;
+    }
+
+    textureMgr->releaseTexture(texture);
+};
+
+void SamplerDeleter::operator () (const MHWRender::MSamplerState* sampler)
+{
+    if (sampler)
+    {
+        MHWRender::MStateManager::releaseSamplerState(sampler);
+    }
+};
+
 } // namespace MayaUtil
 } // namespace MaterialXMaya

source/MaterialXContrib/MaterialXMaya/MayaUtil.h

@@ -1,14 +1,49 @@
 #ifndef MATERIALX_MAYA_MAYAUTIL_H
 #define MATERIALX_MAYA_MAYAUTIL_H
 
+/// @file
+/// Maya Viewport 2.0 utilities.
+
+#include <maya/MTextureManager.h>
+#include <maya/MStateManager.h>
+
 #include <string>
+#include <memory>
 
 namespace MaterialXMaya
 {
 namespace MayaUtil
 {
+
+/// Registers an OGS shade fragment in VP2. Throws an exception if a fragment
+/// with the same name is already registered.
+/// @param The unique name of the fragment to use for registration.
+/// @param The code of the fragment stored in a string.
 void registerFragment(const std::string& fragmentName, const std::string& fragmentSource);
-}
-}
+
+struct TextureDeleter
+{
+    /// Releases the reference to the VP2 texture owned by a smart pointer.
+    void operator()(MHWRender::MTexture* texture);
+};
+
+using TextureUniquePtr = std::unique_ptr<
+    MHWRender::MTexture,
+    TextureDeleter
+>;
+
+struct SamplerDeleter
+{
+    /// Releases the reference to the VP2 sampler owned by a smart pointer.
+    void operator()(const MHWRender::MSamplerState* sampler);
+};
+
+using SamplerUniquePtr = std::unique_ptr<
+    const MHWRender::MSamplerState,
+    SamplerDeleter
+>;
+
+} // namespace MayaUtil
+} // namespace MaterialXMaya
 
 #endif