Sphinx Python Documentation (#1567) - Added docstrings to PyMaterialX…

…GenShader.

source/PyMaterialX/PyMaterialXGenShader/PyColorManagement.cpp

@@ -47,15 +47,30 @@ void bindPyColorManagement(py::module& mod)
         .def(py::init<const std::string&, const std::string&, const mx::TypeDesc*>())
         .def_readwrite("sourceSpace", &mx::ColorSpaceTransform::sourceSpace)
         .def_readwrite("targetSpace", &mx::ColorSpaceTransform::targetSpace)
-        .def_readwrite("type", &mx::ColorSpaceTransform::type);
+        .def_readwrite("type", &mx::ColorSpaceTransform::type)
+        .doc() = R"docstring(
+    Structure that represents color space transform information.
+
+    :see: https://materialx.org/docs/api/struct_color_space_transform.html
+)docstring";
 
     py::class_<mx::ColorManagementSystem, PyColorManagementSystem, mx::ColorManagementSystemPtr>(mod, "ColorManagementSystem")
         .def(py::init<>())
         .def("getName", &mx::ColorManagementSystem::getName)
         .def("loadLibrary", &mx::ColorManagementSystem::loadLibrary)
-        .def("supportsTransform", &mx::ColorManagementSystem::supportsTransform);
+        .def("supportsTransform", &mx::ColorManagementSystem::supportsTransform)
+        .doc() = R"docstring(
+    Abstract base class for color management systems.
+
+    :see: https://materialx.org/docs/api/class_color_management_system.html
+)docstring";
 
     py::class_<mx::DefaultColorManagementSystem, mx::DefaultColorManagementSystemPtr, mx::ColorManagementSystem>(mod, "DefaultColorManagementSystem")
         .def_static("create", &mx::DefaultColorManagementSystem::create)
-        .def("getName", &mx::DefaultColorManagementSystem::getName);
+        .def("getName", &mx::DefaultColorManagementSystem::getName)
+        .doc() = R"docstring(
+    Class for a default color management system.
+
+    :see: https://materialx.org/docs/api/class_default_color_management_system.html
+)docstring";
 }

source/PyMaterialX/PyMaterialXGenShader/PyGenContext.cpp

@@ -13,7 +13,13 @@ namespace mx = MaterialX;
 
 void bindPyGenContext(py::module& mod)
 {
-    py::class_<mx::ApplicationVariableHandler>(mod, "ApplicationVariableHandler");
+    py::class_<mx::ApplicationVariableHandler>(mod, "ApplicationVariableHandler")
+        .doc() = R"docstring(
+    Class representing a function to allow for handling of application
+    variables for a given node.
+
+    Is expected to take a `ShaderNode` and a `GenContext`, and return `None`.
+)docstring";
 
     py::class_<mx::GenContext, mx::GenContextPtr>(mod, "GenContext")
         .def(py::init<mx::ShaderGeneratorPtr>())
@@ -24,11 +30,21 @@ void bindPyGenContext(py::module& mod)
         .def("resolveSourceFile", &mx::GenContext::resolveSourceFile)
         .def("pushUserData", &mx::GenContext::pushUserData)
         .def("setApplicationVariableHandler", &mx::GenContext::setApplicationVariableHandler)
-        .def("getApplicationVariableHandler", &mx::GenContext::getApplicationVariableHandler);
+        .def("getApplicationVariableHandler", &mx::GenContext::getApplicationVariableHandler)
+        .doc() = R"docstring(
+    A context class for shader generation.
+
+    :see: https://materialx.org/docs/api/class_gen_context.html
+)docstring";
 }
 
 void bindPyGenUserData(py::module& mod)
 {
     py::class_<mx::GenUserData, mx::GenUserDataPtr>(mod, "GenUserData")
-        .def("getSelf", static_cast<mx::GenUserDataPtr(mx::GenUserData::*)()>(&mx::GenUserData::getSelf));
+        .def("getSelf", static_cast<mx::GenUserDataPtr(mx::GenUserData::*)()>(&mx::GenUserData::getSelf))
+        .doc() = R"docstring(
+    Base class for custom user data needed during shader generation.
+
+    :see: https://materialx.org/docs/api/class_gen_user_data.html
+)docstring";
 }

source/PyMaterialX/PyMaterialXGenShader/PyGenOptions.cpp

@@ -12,12 +12,16 @@ namespace mx = MaterialX;
 
 void bindPyGenOptions(py::module& mod)
 {
-    py::enum_<mx::ShaderInterfaceType>(mod, "ShaderInterfaceType")
+    py::enum_<mx::ShaderInterfaceType>(mod, "ShaderInterfaceType", R"docstring(
+    Enumeration of the type of shader interface to be generated.
+)docstring")
         .value("SHADER_INTERFACE_COMPLETE", mx::ShaderInterfaceType::SHADER_INTERFACE_COMPLETE)
         .value("SHADER_INTERFACE_REDUCED", mx::ShaderInterfaceType::SHADER_INTERFACE_REDUCED)
         .export_values();
 
-    py::enum_<mx::HwSpecularEnvironmentMethod>(mod, "HwSpecularEnvironmentMethod")
+    py::enum_<mx::HwSpecularEnvironmentMethod>(mod, "HwSpecularEnvironmentMethod", R"docstring(
+    Enumeration of the method to use for specular environment lighting.
+)docstring")
         .value("SPECULAR_ENVIRONMENT_PREFILTER", mx::HwSpecularEnvironmentMethod::SPECULAR_ENVIRONMENT_PREFILTER)
         .value("SPECULAR_ENVIRONMENT_FIS", mx::HwSpecularEnvironmentMethod::SPECULAR_ENVIRONMENT_FIS)
         .value("SPECULAR_ENVIRONMENT_NONE", mx::HwSpecularEnvironmentMethod::SPECULAR_ENVIRONMENT_NONE)
@@ -40,5 +44,126 @@ void bindPyGenOptions(py::module& mod)
         .def_readwrite("hwWriteAlbedoTable", &mx::GenOptions::hwWriteAlbedoTable)
         .def_readwrite("hwImplicitBitangents", &mx::GenOptions::hwImplicitBitangents)
         .def_readwrite("emitColorTransforms", &mx::GenOptions::emitColorTransforms)
-        .def(py::init<>());
+        .def(py::init<>())
+        .doc() = R"docstring(
+    Class holding options to configure shader generation.
+
+    :see: https://materialx.org/docs/api/class_gen_options.html
+)docstring";
+
+    auto GenOptions = mod.attr("GenOptions");
+
+    GenOptions.attr("shaderInterfaceType").doc() = R"docstring(
+    (`ShaderInterfaceType`)
+    Sets the type of shader interface to be generated.
+)docstring";
+
+    GenOptions.attr("fileTextureVerticalFlip").doc() = R"docstring(
+    (`bool`)
+    If `True` the y-component of texture coordinates used for sampling
+    file textures will be flipped before sampling. This can be used if
+    file textures need to be flipped vertically to match the target's
+    texture space convention. By default this option is `False`.
+)docstring";
+
+    GenOptions.attr("targetColorSpaceOverride").doc() = R"docstring(
+    (`str`)
+    An optional override for the target color space.
+    Shader fragments will be generated to transform
+    input values and textures into this color space.
+)docstring";
+
+    GenOptions.attr("addUpstreamDependencies").doc() = R"docstring(
+    (`bool`)
+    Sets whether to include upstream dependencies
+    for the element to generate a shader for.
+)docstring";
+
+    GenOptions.attr("libraryPrefix").doc() = R"docstring(
+    (`FilePath`)
+    The standard library prefix, which will be applied to
+    calls to emitLibraryInclude during code generation.
+    Defaults to `"libraries"`.
+)docstring";
+
+    GenOptions.attr("targetDistanceUnit").doc() = R"docstring(
+    (`str`)
+    Define the target distance unit.
+    Shader fragments will be generated to transform
+    input distance values to the given unit.
+)docstring";
+
+    GenOptions.attr("hwTransparency").doc() = R"docstring(
+    (`bool`)
+    Sets if transparency is needed or not for HW shaders.
+    If a surface shader has potential of being transparent
+    this must be set to true, otherwise no transparency
+    code fragments will be generated for the shader and
+    the surface will be fully opaque.
+)docstring";
+
+    GenOptions.attr("hwSpecularEnvironmentMethod").doc() = R"docstring(
+    (`HwSpecularEnvironmentMethod`)
+    Sets the method to use for specular environment lighting
+    for HW shader targets.
+)docstring";
+
+    GenOptions.attr("hwWriteDepthMoments").doc() = R"docstring(
+    (`bool`)
+    Enables the writing of depth moments for HW shader targets.
+    Defaults to `False`.
+)docstring";
+
+    GenOptions.attr("hwShadowMap").doc() = R"docstring(
+    (`bool`)
+    Enables shadow mapping for HW shader targets.
+    Defaults to `False`.
+)docstring";
+
+    GenOptions.attr("hwMaxActiveLightSources").doc() = R"docstring(
+    (`int`)
+    Sets the maximum number of light sources that can
+    be active at once.
+)docstring";
+
+    GenOptions.attr("hwNormalizeUdimTexCoords").doc() = R"docstring(
+    (`bool`)
+    Sets whether to transform texture coordinates to normalize
+    uv space when UDIMs images are bound to an image. Can be
+    enabled for when texture atlas generation is performed to
+    compress a set of UDIMs into a single normalized image for
+    hardware rendering.
+)docstring";
+
+    GenOptions.attr("hwAmbientOcclusion").doc() = R"docstring(
+    (`bool`)
+    Enables ambient occlusion rendering for HW shader targets.
+    Defaults to `False`.
+)docstring";
+
+    GenOptions.attr("hwWriteAlbedoTable").doc() = R"docstring(
+    (`bool`)
+    Enables the writing of a directional albedo table.
+    Defaults to `False`.
+)docstring";
+
+    GenOptions.attr("hwImplicitBitangents").doc() = R"docstring(
+    (`bool`)
+    Calculate fallback bitangents from existing normals and tangents
+    inside the bitangent node.
+)docstring";
+
+    GenOptions.attr("emitColorTransforms").doc() = R"docstring(
+    (`bool`)
+    Enable emitting colorspace transform code if a color management
+    system is defined. Defaults to `True`.
+)docstring";
+
+    // FIXME(SH): Expose hwDirectionalAlbedoMethod and hwTransmissionRenderMethod?
+    // Sets the method to use for directional albedo evaluation
+    // for HW shader targets.
+    // HwDirectionalAlbedoMethod hwDirectionalAlbedoMethod;
+    // Sets the method to use for transmission rendering
+    // for HW shader targets.
+    // HwTransmissionRenderMethod hwTransmissionRenderMethod;
 }

source/PyMaterialX/PyMaterialXGenShader/PyHwShaderGenerator.cpp

@@ -30,12 +30,22 @@ void bindPyHwShaderGenerator(py::module& mod)
         .def("getClosureContexts", &mx::HwShaderGenerator::getClosureContexts)
         .def("bindLightShader", &mx::HwShaderGenerator::bindLightShader)
         .def("unbindLightShader", &mx::HwShaderGenerator::unbindLightShader)
-        .def("unbindLightShaders", &mx::HwShaderGenerator::unbindLightShaders);
+        .def("unbindLightShaders", &mx::HwShaderGenerator::unbindLightShaders)
+        .doc() = R"docstring(
+    Base class for shader generators targeting HW rendering.
+
+    :see: https://materialx.org/docs/api/class_hw_shader_generator.html
+)docstring";
 }
 
 void bindPyHwResourceBindingContext(py::module& mod)
 {
     py::class_<mx::HwResourceBindingContext, mx::GenUserData, mx::HwResourceBindingContextPtr>(mod, "HwResourceBindingContext")
         .def("emitDirectives", &mx::HwResourceBindingContext::emitDirectives)
-        .def("emitResourceBindings", &mx::HwResourceBindingContext::emitResourceBindings);
+        .def("emitResourceBindings", &mx::HwResourceBindingContext::emitResourceBindings)
+        .doc() = R"docstring(
+    Class representing a context for resource binding for hardware resources.
+
+    :see: https://materialx.org/docs/api/class_hw_resource_binding_context.html
+)docstring";
 }

source/PyMaterialX/PyMaterialXGenShader/PyModule.cpp

@@ -24,7 +24,74 @@ void bindPyUnitSystem(py::module& mod);
 
 PYBIND11_MODULE(PyMaterialXGenShader, mod)
 {
-    mod.doc() = "Core functionality for shader generation";
+    mod.doc() = R"docstring(
+    Core shader generation support.
+
+    Shader Generation Classes
+    -------------------------
+
+    .. autosummary::
+        :toctree: shader-generation
+
+        ShaderGenerator
+        HwShaderGenerator
+        HwResourceBindingContext
+        GenContext
+        GenOptions
+        GenUserData
+        ApplicationVariableHandler
+        Shader
+        ShaderPort
+        ShaderPortPredicate
+        ShaderStage
+        ShaderTranslator
+        TypeDesc
+        VariableBlock
+
+    Enumeration Classes
+    -------------------
+
+    .. autosummary::
+        :toctree: enumeration
+
+        ShaderInterfaceType
+        HwSpecularEnvironmentMethod
+
+    Color Management Classes
+    ------------------------
+
+    .. autosummary::
+        :toctree: color-management
+
+        ColorManagementSystem
+        DefaultColorManagementSystem
+        ColorSpaceTransform
+
+    Unit System Classes
+    -------------------
+
+    .. autosummary::
+        :toctree: unit-system
+
+        UnitSystem
+        UnitTransform
+
+    Utility Functions
+    -----------------
+
+    .. autofunction:: connectsToWorldSpaceNode
+    .. autofunction:: elementRequiresShading
+    .. autofunction:: findRenderableElements
+    .. autofunction:: findRenderableMaterialNodes
+    .. autofunction:: getNodeDefInput
+    .. autofunction:: getUdimCoordinates
+    .. autofunction:: getUdimScaleAndOffset
+    .. autofunction:: hasElementAttributes
+    .. autofunction:: isTransparentSurface
+    .. autofunction:: mapValueToColor
+    .. autofunction:: requiresImplementation
+    .. autofunction:: tokenSubstitution
+)docstring";
 
     bindPyColorManagement(mod);
     bindPyShaderPort(mod);

source/PyMaterialX/PyMaterialXGenShader/PyShader.cpp

@@ -28,5 +28,16 @@ void bindPyShader(py::module& mod)
         .def("hasAttribute", &mx::Shader::hasAttribute)
         .def("getAttribute", &mx::Shader::getAttribute)
         .def("setAttribute", static_cast<void (mx::Shader::*)(const std::string&)>(&mx::Shader::setAttribute))
-        .def("setAttribute", static_cast<void (mx::Shader::*)(const std::string&, mx::ValuePtr)>(&mx::Shader::setAttribute));
+        .def("setAttribute", static_cast<void (mx::Shader::*)(const std::string&, mx::ValuePtr)>(&mx::Shader::setAttribute))
+        .doc() = R"docstring(
+    Class containing all data needed during shader generation.
+    After generation is completed it will contain the resulting source code
+    emitted by shader generators.
+
+    The class contains a default implementation using a single shader stage.
+    Derived shaders can override this, as well as overriding all methods
+    that add code to the shader.
+
+    :see: https://materialx.org/docs/api/class_shader.html
+)docstring";
 }

source/PyMaterialX/PyMaterialXGenShader/PyShaderGenerator.cpp

@@ -22,5 +22,11 @@ void bindPyShaderGenerator(py::module& mod)
         .def("setUnitSystem", &mx::ShaderGenerator::setUnitSystem)
         .def("getUnitSystem", &mx::ShaderGenerator::getUnitSystem)
         .def("getTokenSubstitutions", &mx::ShaderGenerator::getTokenSubstitutions)
-        .def("registerShaderMetadata", &mx::ShaderGenerator::registerShaderMetadata);
+        .def("registerShaderMetadata", &mx::ShaderGenerator::registerShaderMetadata)
+        .doc() = R"docstring(
+    Base class for shader generators.
+    All third-party shader generators should derive from this class.
+
+    :see: https://materialx.org/docs/api/class_shader_generator.html
+)docstring";
 }

source/PyMaterialX/PyMaterialXGenShader/PyShaderPort.cpp

@@ -34,5 +34,10 @@ void bindPyShaderPort(py::module& mod)
         .def("setColorSpace", &mx::ShaderPort::setColorSpace)
         .def("getColorSpace", &mx::ShaderPort::getColorSpace)
         .def("isUniform", &mx::ShaderPort::isUniform)
-        .def("isEmitted", &mx::ShaderPort::isEmitted);
+        .def("isEmitted", &mx::ShaderPort::isEmitted)
+        .doc() = R"docstring(
+    Class representing an input or output port on a `ShaderNode`.
+
+    :see: https://materialx.org/docs/api/class_shader_port.html
+)docstring";
 }