diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyColorManagement.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyColorManagement.cpp index 701b124c3c..6e02eda2f9 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyColorManagement.cpp +++ b/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_(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_(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"; } diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyGenContext.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyGenContext.cpp index 11792f317c..979d099ffb 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyGenContext.cpp +++ b/source/PyMaterialX/PyMaterialXGenShader/PyGenContext.cpp @@ -14,6 +14,10 @@ namespace mx = MaterialX; void bindPyGenContext(py::module& mod) { py::class_(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_(mod, "GenContext") .def(py::init()) @@ -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_(mod, "GenUserData") .def("getSelf", static_cast(&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"; } \ No newline at end of file diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyGenOptions.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyGenOptions.cpp index 3949d50b8d..e5d51f634c 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyGenOptions.cpp +++ b/source/PyMaterialX/PyMaterialXGenShader/PyGenOptions.cpp @@ -12,35 +12,117 @@ namespace mx = MaterialX; void bindPyGenOptions(py::module& mod) { - py::enum_(mod, "ShaderInterfaceType") - .value("SHADER_INTERFACE_COMPLETE", mx::ShaderInterfaceType::SHADER_INTERFACE_COMPLETE) - .value("SHADER_INTERFACE_REDUCED", mx::ShaderInterfaceType::SHADER_INTERFACE_REDUCED) + py::enum_(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_(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_(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_(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"; } diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyHwShaderGenerator.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyHwShaderGenerator.cpp index 286021cb90..0a424a31f9 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyHwShaderGenerator.cpp +++ b/source/PyMaterialX/PyMaterialXGenShader/PyHwShaderGenerator.cpp @@ -29,6 +29,10 @@ 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) @@ -36,4 +40,8 @@ void bindPyHwResourceBindingContext(py::module& mod) py::class_(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"; } diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyShader.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyShader.cpp index 581964aeac..dec8e5a9b4 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyShader.cpp +++ b/source/PyMaterialX/PyMaterialXGenShader/PyShader.cpp @@ -29,4 +29,15 @@ void bindPyShader(py::module& mod) .def("getAttribute", &mx::Shader::getAttribute) .def("setAttribute", static_cast(&mx::Shader::setAttribute)) .def("setAttribute", static_cast(&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"; } diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyShaderGenerator.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyShaderGenerator.cpp index b952bd4651..37cb1a162a 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyShaderGenerator.cpp +++ b/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"; } diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyShaderPort.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyShaderPort.cpp index 146674c222..52a9e8365d 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyShaderPort.cpp +++ b/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"; } diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyShaderStage.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyShaderStage.cpp index 62347caa6b..4b23dd73b5 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyShaderStage.cpp +++ b/source/PyMaterialX/PyMaterialXGenShader/PyShaderStage.cpp @@ -15,6 +15,8 @@ void bindPyShaderStage(py::module& mod) mod.attr("PIXEL_STAGE") = &mx::Stage::PIXEL; py::class_(mod, "ShaderPortPredicate"); + mod.attr("ShaderPortPredicate").doc() = R"docstring( + A function predicate taking a `ShaderPort` and returning a `bool`.)docstring"; py::class_(mod, "VariableBlock") .def(py::init()) @@ -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_(mod, "ShaderStage") .def(py::init()) @@ -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"; } diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyShaderTranslator.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyShaderTranslator.cpp index c6b3f2bfe9..66d0813f69 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyShaderTranslator.cpp +++ b/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"; } diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyTypeDesc.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyTypeDesc.cpp index dc0a6c9fe8..8bb6299d46 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyTypeDesc.cpp +++ b/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"; } diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyUnitSystem.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyUnitSystem.cpp index e5befc21e6..264b6dae53 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyUnitSystem.cpp +++ b/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_(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"; }