Docstrings for PyMaterialXGenShader classes.

Similar to AcademySoftwareFoundation#2051 and AcademySoftwareFoundation#2061.

Split from AcademySoftwareFoundation#1567.

Update AcademySoftwareFoundation#342.

Signed-off-by: Stefan Habel <[email protected]>

source/PyMaterialX/PyMaterialXGenShader/PyColorManagement.cpp

@@ -48,14 +48,26 @@ void bindPyColorManagement(py::module& mod)
         .def_readwrite("sourceSpace", &mx::ColorSpaceTransform::sourceSpace)
         .def_readwrite("targetSpace", &mx::ColorSpaceTransform::targetSpace)
         .def_readwrite("type", &mx::ColorSpaceTransform::type);
+    mod.attr("ColorSpaceTransform").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);
+    mod.attr("ColorManagementSystem").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);
+    mod.attr("DefaultColorManagementSystem").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

@@ -14,6 +14,10 @@ namespace mx = MaterialX;
 void bindPyGenContext(py::module& mod)
 {
     py::class_<mx::ApplicationVariableHandler>(mod, "ApplicationVariableHandler");
+    mod.attr("ApplicationVariableHandler").doc() = R"docstring(
+    A function to allow for handling of application variables for a given node.
+
+    Is expected to take a `ShaderNode` and a `GenContext`, and not return anything.)docstring";
 
     py::class_<mx::GenContext, mx::GenContextPtr>(mod, "GenContext")
         .def(py::init<mx::ShaderGeneratorPtr>())
@@ -25,10 +29,20 @@ void bindPyGenContext(py::module& mod)
         .def("pushUserData", &mx::GenContext::pushUserData)
         .def("setApplicationVariableHandler", &mx::GenContext::setApplicationVariableHandler)
         .def("getApplicationVariableHandler", &mx::GenContext::getApplicationVariableHandler);
+    mod.attr("GenContext").doc() = R"docstring(
+    A context class for shader generation.
+
+    Used for thread local storage of data needed during 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));
+    mod.attr("GenUserData").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,35 +12,117 @@ namespace mx = MaterialX;
 
 void bindPyGenOptions(py::module& mod)
 {
-    py::enum_<mx::ShaderInterfaceType>(mod, "ShaderInterfaceType")
-        .value("SHADER_INTERFACE_COMPLETE", mx::ShaderInterfaceType::SHADER_INTERFACE_COMPLETE)
-        .value("SHADER_INTERFACE_REDUCED", mx::ShaderInterfaceType::SHADER_INTERFACE_REDUCED)
+    py::enum_<mx::ShaderInterfaceType>(mod, "ShaderInterfaceType",
+                                       "Type of shader interface to be generated")
+        .value("SHADER_INTERFACE_COMPLETE", mx::ShaderInterfaceType::SHADER_INTERFACE_COMPLETE,
+               "Create a complete interface with uniforms for all "
+               "editable inputs on all nodes used by the shader. "
+               "This interface makes the shader fully editable by "
+               "value without requiring any rebuilds. "
+               "This is the default interface type.")
+        .value("SHADER_INTERFACE_REDUCED", mx::ShaderInterfaceType::SHADER_INTERFACE_REDUCED,
+               "Create a reduced interface with uniforms only for "
+               "the inputs that has been declared in the shaders "
+               "nodedef interface. If values on other inputs are "
+               "changed the shader needs to be rebuilt.")
         .export_values();
 
-    py::enum_<mx::HwSpecularEnvironmentMethod>(mod, "HwSpecularEnvironmentMethod")
-        .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)
+    py::enum_<mx::HwSpecularEnvironmentMethod>(mod, "HwSpecularEnvironmentMethod",
+                                               "Method to use for specular environment lighting")
+        .value("SPECULAR_ENVIRONMENT_PREFILTER", mx::HwSpecularEnvironmentMethod::SPECULAR_ENVIRONMENT_PREFILTER,
+               "Use pre-filtered environment maps for specular environment/indirect lighting.")
+        .value("SPECULAR_ENVIRONMENT_FIS", mx::HwSpecularEnvironmentMethod::SPECULAR_ENVIRONMENT_FIS,
+               "Use Filtered Importance Sampling for specular environment/indirect lighting.")
+        .value("SPECULAR_ENVIRONMENT_NONE", mx::HwSpecularEnvironmentMethod::SPECULAR_ENVIRONMENT_NONE,
+               "Do not use specular environment maps.")
         .export_values();
 
     py::class_<mx::GenOptions>(mod, "GenOptions")
-        .def_readwrite("shaderInterfaceType", &mx::GenOptions::shaderInterfaceType)
-        .def_readwrite("fileTextureVerticalFlip", &mx::GenOptions::fileTextureVerticalFlip)
-        .def_readwrite("targetColorSpaceOverride", &mx::GenOptions::targetColorSpaceOverride)
-        .def_readwrite("targetDistanceUnit", &mx::GenOptions::targetDistanceUnit)
-        .def_readwrite("addUpstreamDependencies", &mx::GenOptions::addUpstreamDependencies)
-        .def_readwrite("libraryPrefix", &mx::GenOptions::libraryPrefix)        
-        .def_readwrite("emitColorTransforms", &mx::GenOptions::emitColorTransforms)
-        .def_readwrite("hwTransparency", &mx::GenOptions::hwTransparency)
-        .def_readwrite("hwSpecularEnvironmentMethod", &mx::GenOptions::hwSpecularEnvironmentMethod)
-        .def_readwrite("hwSrgbEncodeOutput", &mx::GenOptions::hwSrgbEncodeOutput)
-        .def_readwrite("hwWriteDepthMoments", &mx::GenOptions::hwWriteDepthMoments)
-        .def_readwrite("hwShadowMap", &mx::GenOptions::hwShadowMap)
-        .def_readwrite("hwMaxActiveLightSources", &mx::GenOptions::hwMaxActiveLightSources)
-        .def_readwrite("hwNormalizeUdimTexCoords", &mx::GenOptions::hwNormalizeUdimTexCoords)
-        .def_readwrite("hwAmbientOcclusion", &mx::GenOptions::hwAmbientOcclusion)        
-        .def_readwrite("hwWriteAlbedoTable", &mx::GenOptions::hwWriteAlbedoTable)
-        .def_readwrite("hwWriteEnvPrefilter", &mx::GenOptions::hwWriteEnvPrefilter)
-        .def_readwrite("hwImplicitBitangents", &mx::GenOptions::hwImplicitBitangents)
+        .def_readwrite("shaderInterfaceType", &mx::GenOptions::shaderInterfaceType,
+                       "(`ShaderInterfaceType`)\n"
+                       "Sets the type of shader interface to be generated.")
+        .def_readwrite("fileTextureVerticalFlip", &mx::GenOptions::fileTextureVerticalFlip,
+                       "(`bool`)\n"
+                       "If `True` the y-component of texture coordinates used for sampling\n"
+                       "file textures will be flipped before sampling. This can be used if\n"
+                       "file textures need to be flipped vertically to match the target's\n"
+                       "texture space convention. By default this option is `False`.")
+        .def_readwrite("targetColorSpaceOverride", &mx::GenOptions::targetColorSpaceOverride,
+                       "(`str`)\n"
+                       "An optional override for the target color space.\n"
+                       "Shader fragments will be generated to transform\n"
+                       "input values and textures into this color space.")
+        .def_readwrite("targetDistanceUnit", &mx::GenOptions::targetDistanceUnit,
+                       "(`str`)\n"
+                       "Define the target distance unit.\n"
+                       "Shader fragments will be generated to transform\n"
+                       "input distance values to the given unit.")
+        .def_readwrite("addUpstreamDependencies", &mx::GenOptions::addUpstreamDependencies,
+                       "(`bool`)\n"
+                       "Sets whether to include upstream dependencies\n"
+                       "for the element to generate a shader for.")
+        .def_readwrite("libraryPrefix", &mx::GenOptions::libraryPrefix,
+                       "(`str`)\n"
+                       "The standard library prefix, which will be applied to\n"
+                       "calls to `emitLibraryInclude()` during code generation.\n"
+                       "Defaults to `'libraries'`.")
+        .def_readwrite("emitColorTransforms", &mx::GenOptions::emitColorTransforms,
+                       "(`bool`)\n"
+                       "Enable emitting colorspace transform code if a color management\n"
+                       "system is defined. Defaults to `True`.")
+        .def_readwrite("hwTransparency", &mx::GenOptions::hwTransparency,
+                       "(`bool`)\n"
+                       "Sets if transparency is needed or not for HW shaders.\n"
+                       "If a surface shader has potential of being transparent\n"
+                       "this must be set to `True`, otherwise no transparency\n"
+                       "code fragments will be generated for the shader and\n"
+                       "the surface will be fully opaque.")
+        .def_readwrite("hwSpecularEnvironmentMethod", &mx::GenOptions::hwSpecularEnvironmentMethod,
+                       "(`HwSpecularEnvironmentMethod`)\n"
+                       "Sets the method to use for specular environment lighting\n"
+                       "for HW shader targets.")
+        .def_readwrite("hwSrgbEncodeOutput", &mx::GenOptions::hwSrgbEncodeOutput,
+                       "(`bool`)\n"
+                       "Enables an sRGB encoding for the color output on HW shader targets.\n"
+                       "Defaults to `False`.")
+        .def_readwrite("hwWriteDepthMoments", &mx::GenOptions::hwWriteDepthMoments,
+                       "(`bool`)\n"
+                       "Enables the writing of depth moments for HW shader targets.\n"
+                       "Defaults to `False`.")
+        .def_readwrite("hwShadowMap", &mx::GenOptions::hwShadowMap,
+                       "(`bool`)\n"
+                       "Enables shadow mapping for HW shader targets.\n"
+                       "Defaults to `False`.")
+        .def_readwrite("hwMaxActiveLightSources", &mx::GenOptions::hwMaxActiveLightSources,
+                       "(`int`)\n"
+                       "Sets the maximum number of light sources that can\n"
+                       "be active at once.")
+        .def_readwrite("hwNormalizeUdimTexCoords", &mx::GenOptions::hwNormalizeUdimTexCoords,
+                       "(`bool`)\n"
+                       "Sets whether to transform texture coordinates to normalize\n"
+                       "uv space when UDIMs images are bound to an image. Can be\n"
+                       "enabled for when texture atlas generation is performed to\n"
+                       "compress a set of UDIMs into a single normalized image for\n"
+                       "hardware rendering.")
+        .def_readwrite("hwAmbientOcclusion", &mx::GenOptions::hwAmbientOcclusion,
+                       "(`bool`)\n"
+                       "Enables ambient occlusion rendering for HW shader targets.\n"
+                       "Defaults to `False`.")
+        .def_readwrite("hwWriteAlbedoTable", &mx::GenOptions::hwWriteAlbedoTable,
+                       "(`bool`)\n"
+                       "Enables the writing of a directional albedo table.\n"
+                       "Defaults to `False`.")
+        .def_readwrite("hwWriteEnvPrefilter", &mx::GenOptions::hwWriteEnvPrefilter,
+                       "(`bool`)\n"
+                       "Enables the generation of a prefiltered environment map.\n"
+                       "Defaults to `False`.")
+        .def_readwrite("hwImplicitBitangents", &mx::GenOptions::hwImplicitBitangents,
+                       "(`bool`)\n"
+                       "Calculate fallback bitangents from existing normals and tangents\n"
+                       "inside the bitangent node.")
         .def(py::init<>());
+    mod.attr("GenOptions").doc() = R"docstring(
+    Class holding options to configure shader generation.
+
+    :see: https://materialx.org/docs/api/class_gen_options.html)docstring";
 }

source/PyMaterialX/PyMaterialXGenShader/PyHwShaderGenerator.cpp

@@ -29,11 +29,19 @@ void bindPyHwShaderGenerator(py::module& mod)
         .def("bindLightShader", &mx::HwShaderGenerator::bindLightShader)
         .def("unbindLightShader", &mx::HwShaderGenerator::unbindLightShader)
         .def("unbindLightShaders", &mx::HwShaderGenerator::unbindLightShaders);
+    mod.attr("HwShaderGenerator").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);
+    mod.attr("HwResourceBindingContext").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/PyShader.cpp

@@ -29,4 +29,15 @@ void bindPyShader(py::module& mod)
         .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));
+    mod.attr("Shader").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

@@ -23,4 +23,13 @@ void bindPyShaderGenerator(py::module& mod)
         .def("getUnitSystem", &mx::ShaderGenerator::getUnitSystem)
         .def("getTokenSubstitutions", &mx::ShaderGenerator::getTokenSubstitutions)
         .def("registerShaderMetadata", &mx::ShaderGenerator::registerShaderMetadata);
+    mod.attr("ShaderGenerator").doc() = R"docstring(
+    Base class for shader generators.
+
+    All third-party shader generators should derive from this class.
+
+    Derived classes should use `DECLARE_SHADER_GENERATOR` / `DEFINE_SHADER_GENERATOR`
+    in their declaration / definition, and register with the `Registry` class.
+
+    :see: https://materialx.org/docs/api/class_shader_generator.html)docstring";
 }

source/PyMaterialX/PyMaterialXGenShader/PyShaderPort.cpp

@@ -35,4 +35,8 @@ void bindPyShaderPort(py::module& mod)
         .def("getColorSpace", &mx::ShaderPort::getColorSpace)
         .def("isUniform", &mx::ShaderPort::isUniform)
         .def("isEmitted", &mx::ShaderPort::isEmitted);
+    mod.attr("ShaderPort").doc() = R"docstring(
+    An input or output port on a `ShaderNode`.
+
+    :see: https://materialx.org/docs/api/class_shader_port.html)docstring";
 }

source/PyMaterialX/PyMaterialXGenShader/PyShaderStage.cpp

@@ -15,6 +15,8 @@ void bindPyShaderStage(py::module& mod)
     mod.attr("PIXEL_STAGE") = &mx::Stage::PIXEL;
 
     py::class_<mx::ShaderPortPredicate>(mod, "ShaderPortPredicate");
+    mod.attr("ShaderPortPredicate").doc() = R"docstring(
+    A function predicate taking a `ShaderPort` and returning a `bool`.)docstring";
 
     py::class_<mx::VariableBlock, mx::VariableBlockPtr>(mod, "VariableBlock")
         .def(py::init<const std::string&, const std::string&>())
@@ -30,6 +32,10 @@ void bindPyShaderStage(py::module& mod)
             if (i >= vb.size()) throw py::index_error();
             return vb[i];
         }, py::return_value_policy::reference_internal);
+    mod.attr("VariableBlock").doc() = R"docstring(
+    A block of variables in a shader stage.
+
+    :see: https://materialx.org/docs/api/class_variable_block.html)docstring";
 
     py::class_<mx::ShaderStage>(mod, "ShaderStage")
         .def(py::init<const std::string&, mx::ConstSyntaxPtr>())
@@ -45,4 +51,8 @@ void bindPyShaderStage(py::module& mod)
         .def("getIncludes", &mx::ShaderStage::getIncludes)
         .def("getSourceDependencies", &mx::ShaderStage::getSourceDependencies)
         .def("getOutputBlocks", &mx::ShaderStage::getOutputBlocks);
+    mod.attr("ShaderStage").doc() = R"docstring(
+    A shader stage, containing the state and resulting source code for the stage.
+
+    :see: https://materialx.org/docs/api/class_shader_stage.html)docstring";
 }

source/PyMaterialX/PyMaterialXGenShader/PyShaderTranslator.cpp

@@ -16,4 +16,8 @@ void bindPyShaderTranslator(py::module& mod)
         .def_static("create", &mx::ShaderTranslator::create)
         .def("translateShader", &mx::ShaderTranslator::translateShader)
         .def("translateAllMaterials", &mx::ShaderTranslator::translateAllMaterials);
+    mod.attr("ShaderTranslator").doc() = R"docstring(
+    A helper class for translating content between shading models.
+
+    :see: https://materialx.org/docs/api/class_shader_translator.html)docstring";
 }

source/PyMaterialX/PyMaterialXGenShader/PyTypeDesc.cpp

@@ -28,4 +28,21 @@ void bindPyTypeDesc(py::module& mod)
         .def("isFloat3", &mx::TypeDesc::isFloat3)
         .def("isFloat4", &mx::TypeDesc::isFloat4)
         .def("isClosure", &mx::TypeDesc::isClosure);
+    mod.attr("TypeDesc").doc() = R"docstring(
+    A type descriptor for MaterialX data types.
+
+    All types need to have a type descriptor registered in order for shader generators
+    to know about the type. It can be used for type comparisons as well as getting more
+    information about the type. Type descriptors for all standard library data types are
+    registered by default and can be accessed from the `Type` namespace, e.g. `Type::FLOAT`.
+
+    To register custom types use the macro `TYPEDESC_DEFINE_TYPE` to define it in a header
+    and the macro `TYPEDESC_REGISTER_TYPE` to register it in the type registry. Registration
+    must be done in order to access the type's name later using `getName()` and to find the
+    type by name using `TypeDesc.get()`.
+
+    The class is a POD type of 64-bits and can efficiently be stored and passed by value.
+    Type compare operations and hash operations are done using a precomputed hash value.
+
+    :see: https://materialx.org/docs/api/class_type_desc.html)docstring";
 }

source/PyMaterialX/PyMaterialXGenShader/PyUnitSystem.cpp

@@ -20,6 +20,10 @@ void bindPyUnitSystem(py::module& mod)
         .def_readwrite("targetUnit", &mx::UnitTransform::targetUnit)
         .def_readwrite("type", &mx::UnitTransform::type)
         .def_readwrite("unitType", &mx::UnitTransform::type);
+    mod.attr("UnitTransform").doc() = R"docstring(
+    Structure that represents unit transform information.
+
+    :see: https://materialx.org/docs/api/struct_unit_transform.html)docstring";
 
     py::class_<mx::UnitSystem, mx::UnitSystemPtr>(mod, "UnitSystem")
         .def_static("create", &mx::UnitSystem::create)
@@ -28,4 +32,8 @@ void bindPyUnitSystem(py::module& mod)
         .def("supportsTransform", &mx::UnitSystem::supportsTransform)
         .def("setUnitConverterRegistry", &mx::UnitSystem::setUnitConverterRegistry)
         .def("getUnitConverterRegistry", &mx::UnitSystem::getUnitConverterRegistry);
+    mod.attr("UnitSystem").doc() = R"docstring(
+    Base unit system support.
+
+    :see: https://materialx.org/docs/api/class_unit_system.html)docstring";
 }