Docstrings for PyMaterialXRender* classes.

Similar to AcademySoftwareFoundation#2051, AcademySoftwareFoundation#2061, AcademySoftwareFoundation#2063, AcademySoftwareFoundation#2064, and AcademySoftwareFoundation#2065. Also fixing a couple of typos in Metal header files. Split from AcademySoftwareFoundation#1567. Update AcademySoftwareFoundation#342. Signed-off-by: Stefan Habel <[email protected]>
StefanHabel · Oct 14, 2024 · 9675ec4 · 9675ec4
1 parent 0ba2ad0
commit 9675ec4
Show file tree

Hide file tree

Showing 12 changed files with 90 additions and 6 deletions.
diff --git a/source/MaterialXRenderMsl/MetalTextureHandler.h b/source/MaterialXRenderMsl/MetalTextureHandler.h
@@ -20,11 +20,11 @@
 
 MATERIALX_NAMESPACE_BEGIN
 
-/// Shared pointer to an Metal texture handler
+/// Shared pointer to a Metal texture handler
 using MetalTextureHandlerPtr = std::shared_ptr<class MetalTextureHandler>;
 
 /// @class MetalTextureHandler
-/// An Metal texture handler class
+/// A Metal texture handler class
 class MX_RENDERMSL_API MetalTextureHandler : public ImageHandler
 {
     friend class MslProgram;
@@ -67,10 +67,10 @@ class MX_RENDERMSL_API MetalTextureHandler : public ImageHandler
     /// Return the bound texture location for a given resource
     int getBoundTextureLocation(unsigned int resourceId);
 
-    /// Utility to map an address mode enumeration to an Metal address mode
+    /// Utility to map an address mode enumeration to a Metal address mode
     static MTLSamplerAddressMode mapAddressModeToMetal(ImageSamplingProperties::AddressMode addressModeEnum);
 
-    /// Utility to map a filter type enumeration to an Metal filter type
+    /// Utility to map a filter type enumeration to a Metal filter type
     static void mapFilterTypeToMetal(ImageSamplingProperties::FilterType filterTypeEnum, bool enableMipmaps, MTLSamplerMinMagFilter& minMagFilter, MTLSamplerMipFilter& mipFilter);
 
     /// Utility to map generic texture properties to Metal texture formats.

diff --git a/source/MaterialXRenderMsl/MslPipelineStateObject.h b/source/MaterialXRenderMsl/MslPipelineStateObject.h
@@ -278,7 +278,7 @@ class MX_RENDERMSL_API MslProgram
     // Delete any currently created pso
     void reset();
 
-    // Utility to map a MaterialX type to an METAL type
+    // Utility to map a MaterialX type to a Metal type
     static MTLDataType mapTypeToMetalType(TypeDesc type);
 
   private:

diff --git a/source/MaterialXRenderMsl/MslRenderer.h b/source/MaterialXRenderMsl/MslRenderer.h
@@ -61,7 +61,7 @@ class MX_RENDERMSL_API MslRenderer : public ShaderRenderer
     /// @name Setup
     /// @{
 
-    /// Internal initialization of stages and OpenGL constructs
+    /// Internal initialization of stages and Metal constructs
     /// required for program validation and rendering.
     /// An exception is thrown on failure.
     /// The exception will contain a list of initialization errors.

diff --git a/source/PyMaterialX/PyMaterialXRenderGlsl/PyGLTextureHandler.cpp b/source/PyMaterialX/PyMaterialXRenderGlsl/PyGLTextureHandler.cpp
@@ -19,4 +19,8 @@ void bindPyGLTextureHandler(py::module& mod)
         .def("createRenderResources", &mx::GLTextureHandler::createRenderResources)
         .def("releaseRenderResources", &mx::GLTextureHandler::releaseRenderResources,
             py::arg("image") = nullptr);
+    mod.attr("GLTextureHandler").doc() = R"docstring(
+    An OpenGL texture handler class.
+
+    :see: https://materialx.org/docs/api/class_g_l_texture_handler.html)docstring";
 }
diff --git a/source/PyMaterialX/PyMaterialXRenderGlsl/PyGlslProgram.cpp b/source/PyMaterialX/PyMaterialXRenderGlsl/PyGlslProgram.cpp
@@ -39,6 +39,14 @@ void bindPyGlslProgram(py::module& mod)
         .def("bindTimeAndFrame", &mx::GlslProgram::bindTimeAndFrame,
             py::arg("time") = 1.0f, py::arg("frame") = 1.0f)
         .def("unbind", &mx::GlslProgram::unbind);
+    mod.attr("GlslProgram").doc() = R"docstring(
+    A class representing an executable GLSL program.
+
+    There are two main interfaces which can be used:
+    one which takes in a HwShader and
+    one which allows for explicit setting of shader stage code.
+
+    :see: https://materialx.org/docs/api/class_glsl_program.html)docstring";
 
     py::class_<mx::GlslProgram::Input>(mod, "Input")
         .def_readwrite_static("INVALID_OPENGL_TYPE", &mx::GlslProgram::Input::INVALID_OPENGL_TYPE)
@@ -50,4 +58,12 @@ void bindPyGlslProgram(py::module& mod)
         .def_readwrite("isConstant", &mx::GlslProgram::Input::isConstant)
         .def_readwrite("path", &mx::GlslProgram::Input::path)
         .def(py::init<int, int, int, std::string>());
+    mod.attr("Input").doc() = R"docstring(
+    Structure to hold information about program inputs.
+
+    The structure is populated by directly scanning the program so may not contain
+    some inputs listed on any associated `HwShader` as those inputs may have been
+    optimized out if they are unused.
+
+    :see: https://materialx.org/docs/api/struct_glsl_program_1_1_input.html)docstring";
 }
diff --git a/source/PyMaterialX/PyMaterialXRenderGlsl/PyGlslRenderer.cpp b/source/PyMaterialX/PyMaterialXRenderGlsl/PyGlslRenderer.cpp
@@ -22,4 +22,20 @@ void bindPyGlslRenderer(py::module& mod)
         .def("renderTextureSpace", &mx::GlslRenderer::renderTextureSpace)
         .def("captureImage", &mx::GlslRenderer::captureImage)
         .def("getProgram", &mx::GlslRenderer::getProgram);
+    mod.attr("GlslRenderer").doc() = R"docstring(
+    Helper class for rendering generated GLSL code to produce images.
+
+    There are two main interfaces which can be used:
+    one which takes in a `HwShader` and
+    one which allows for explicit setting of shader stage code.
+
+    The main services provided are:
+        - Validation: All shader stages are compiled and atteched to a GLSL shader program.
+        - Introspection: The compiled shader program is examined for uniforms and attributes.
+        - Binding: Uniforms and attributes which match the predefined variables generated the GLSL code generator
+          will have values assigned to this. This includes matrices, attribute streams, and textures.
+        - Rendering: The program with bound inputs will be used to drawing geometry to an offscreen buffer.
+          An interface is provided to save this offscreen buffer to disk using an externally defined image handler.
+
+    :see: https://materialx.org/docs/api/class_glsl_renderer.html)docstring";
 }
diff --git a/source/PyMaterialX/PyMaterialXRenderGlsl/PyTextureBaker.cpp b/source/PyMaterialX/PyMaterialXRenderGlsl/PyTextureBaker.cpp
@@ -44,4 +44,9 @@ void bindPyTextureBaker(py::module& mod)
         .def("bakeMaterialToDoc", &mx::TextureBakerGlsl::bakeMaterialToDoc)
         .def("bakeAllMaterials", &mx::TextureBakerGlsl::bakeAllMaterials)
         .def("writeDocumentPerMaterial", &mx::TextureBakerGlsl::writeDocumentPerMaterial);
+    mod.attr("TextureBaker").doc() = R"docstring(
+    An implementation of `TextureBaker <https://materialx.org/docs/api/class_texture_baker.html>`_
+    based on GLSL shader generation.
+
+    :see: https://materialx.org/docs/api/class_texture_baker_glsl.html)docstring";
 }
diff --git a/source/PyMaterialX/PyMaterialXRenderMsl/PyMetalTextureHandler.mm b/source/PyMaterialX/PyMaterialXRenderMsl/PyMetalTextureHandler.mm
@@ -19,4 +19,6 @@ void bindPyMetalTextureHandler(py::module& mod)
         .def("createRenderResources", &mx::MetalTextureHandler::createRenderResources)
         .def("releaseRenderResources", &mx::MetalTextureHandler::releaseRenderResources,
             py::arg("image") = nullptr);
+    mod.attr("MetalTextureHandler").doc() = R"docstring(
+    A Metal texture handler class.)docstring";
 }
diff --git a/source/PyMaterialX/PyMaterialXRenderMsl/PyMslProgram.mm b/source/PyMaterialX/PyMaterialXRenderMsl/PyMslProgram.mm
@@ -35,6 +35,12 @@ void bindPyMslProgram(py::module& mod)
         .def("bindViewInformation", &mx::MslProgram::bindViewInformation)
         .def("bindTimeAndFrame", &mx::MslProgram::bindTimeAndFrame,
              py::arg("time") = 1.0f, py::arg("frame") = 1.0f);
+    mod.attr("MslProgram").doc() = R"docstring(
+    A class representing an executable MSL program.
+
+    There are two main interfaces which can be used:
+    one which takes in a HwShader and
+    one which allows for explicit setting of shader stage code.)docstring";
 
     py::class_<mx::MslProgram::Input>(mod, "Input")
         .def_readwrite("location", &mx::MslProgram::Input::location)
@@ -50,4 +56,10 @@ void bindPyMslProgram(py::module& mod)
             {
                 return mx::MslProgram::Input(inputLocation, static_cast<MTLDataType>(inputType), inputSize, inputPath);
             }));
+    mod.attr("Input").doc() = R"docstring(
+    Structure to hold information about program inputs.
+
+    The structure is populated by directly scanning the program so may not contain
+    some inputs listed on any associated `HwShader` as those inputs may have been
+    optimized out if they are unused.)docstring";
 }
diff --git a/source/PyMaterialX/PyMaterialXRenderMsl/PyMslRenderer.mm b/source/PyMaterialX/PyMaterialXRenderMsl/PyMslRenderer.mm
@@ -23,4 +23,18 @@ void bindPyMslRenderer(py::module& mod)
         .def("renderTextureSpace", &mx::MslRenderer::renderTextureSpace)
         .def("captureImage", &mx::MslRenderer::captureImage)
         .def("getProgram", &mx::MslRenderer::getProgram);
+    mod.attr("MslRenderer").doc() = R"docstring(
+    Helper class for rendering generated MSL code to produce images.
+
+    There are two main interfaces which can be used:
+    one which takes in a `HwShader` and
+    one which allows for explicit setting of shader stage code.
+
+    The main services provided are:
+        - Validation: All shader stages are compiled and atteched to an MSL shader program.
+        - Introspection: The compiled shader program is examined for uniforms and attributes.
+        - Binding: Uniforms and attributes which match the predefined variables generated the MSL code generator
+          will have values assigned to this. This includes matrices, attribute streams, and textures.
+        - Rendering: The program with bound inputs will be used to drawing geometry to an offscreen buffer.
+          An interface is provided to save this offscreen buffer to disk using an externally defined image handler.)docstring";
 }
diff --git a/source/PyMaterialX/PyMaterialXRenderMsl/PyTextureBaker.mm b/source/PyMaterialX/PyMaterialXRenderMsl/PyTextureBaker.mm
@@ -44,4 +44,7 @@ void bindPyTextureBaker(py::module& mod)
         .def("bakeMaterialToDoc", &mx::TextureBakerMsl::bakeMaterialToDoc)
         .def("bakeAllMaterials", &mx::TextureBakerMsl::bakeAllMaterials)
         .def("writeDocumentPerMaterial", &mx::TextureBakerMsl::writeDocumentPerMaterial);
+    mod.attr("TextureBaker").doc() = R"docstring(
+    An implementation of `TextureBaker <https://materialx.org/docs/api/class_texture_baker.html>`_
+    based on MSL shader generation.)docstring";
 }
diff --git a/source/PyMaterialX/PyMaterialXRenderOsl/PyOslRenderer.cpp b/source/PyMaterialX/PyMaterialXRenderOsl/PyOslRenderer.cpp
@@ -33,4 +33,16 @@ void bindPyOslRenderer(py::module& mod)
         .def("setOslUtilityOSOPath", &mx::OslRenderer::setOslUtilityOSOPath)
         .def("useTestRender", &mx::OslRenderer::useTestRender)
         .def("compileOSL", &mx::OslRenderer::compileOSL);
+    mod.attr("OslRenderer").doc() = R"docstring(
+    Helper class for rendering generated OSL code to produce images.
+
+    The main services provided are:
+        - Source code validation: Use of `oslc` to compile and test output results
+        - Introspection check: None at this time.
+        - Binding: None at this time.
+        - Render validation: Use of `testrender` to output rendered images.
+          Assumes source compliation was success as it depends on the existence
+          of corresponding `.oso` files.
+
+    :see: https://materialx.org/docs/api/class_osl_renderer.html)docstring";
 }