From 6253abc806ffcf528485b28addff478a0463c077 Mon Sep 17 00:00:00 2001 From: Stefan Habel <19556655+StefanHabel@users.noreply.github.com> Date: Tue, 31 Oct 2023 00:05:28 -0700 Subject: [PATCH] Docstrings for PyMaterialXGenShader. (#1567) Signed-off-by: Stefan Habel <19556655+StefanHabel@users.noreply.github.com> --- .../PyColorManagement.cpp | 72 +++++++-- .../PyMaterialXGenShader/PyGenContext.cpp | 87 ++++++++-- .../PyMaterialXGenShader/PyGenOptions.cpp | 152 +++++++++++------- .../PyHwShaderGenerator.cpp | 56 ++++++- .../PyMaterialXGenShader/PyShader.cpp | 87 ++++++++-- .../PyShaderGenerator.cpp | 76 ++++++++- .../PyMaterialXGenShader/PyShaderPort.cpp | 144 ++++++++++++++--- .../PyMaterialXGenShader/PyShaderStage.cpp | 141 +++++++++++++--- .../PyShaderTranslator.cpp | 24 ++- .../PyMaterialXGenShader/PyTypeDesc.cpp | 103 +++++++++--- .../PyMaterialXGenShader/PyUnitSystem.cpp | 78 +++++++-- .../PyMaterialXGenShader/PyUtil.cpp | 8 +- 12 files changed, 844 insertions(+), 184 deletions(-) diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyColorManagement.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyColorManagement.cpp index 34ccee1fc2..8510380092 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyColorManagement.cpp +++ b/source/PyMaterialX/PyMaterialXGenShader/PyColorManagement.cpp @@ -44,10 +44,31 @@ class PyColorManagementSystem : public mx::ColorManagementSystem void bindPyColorManagement(py::module& mod) { py::class_(mod, "ColorSpaceTransform") - .def(py::init()) - .def_readwrite("sourceSpace", &mx::ColorSpaceTransform::sourceSpace) - .def_readwrite("targetSpace", &mx::ColorSpaceTransform::targetSpace) - .def_readwrite("type", &mx::ColorSpaceTransform::type) + + .def(py::init(), + py::arg("sourceSpace"), + py::arg("targetSpace"), + py::arg("typeDesc"), + PYMATERIALX_DOCSTRING(R"docstring( + Initialize an instance of this class using the given source space, target + space, and type descriptor. +)docstring")) + + .def_readwrite("sourceSpace", &mx::ColorSpaceTransform::sourceSpace, + PYMATERIALX_DOCSTRING(R"docstring( + The source color space of the color space transform. +)docstring")) + + .def_readwrite("targetSpace", &mx::ColorSpaceTransform::targetSpace, + PYMATERIALX_DOCSTRING(R"docstring( + The target color space of the color space transform. +)docstring")) + + .def_readwrite("typeDesc", &mx::ColorSpaceTransform::type, + PYMATERIALX_DOCSTRING(R"docstring( + The type descriptor of the color space transform. +)docstring")) + .doc() = PYMATERIALX_DOCSTRING(R"docstring( Structure that represents color space transform information. @@ -55,10 +76,31 @@ void bindPyColorManagement(py::module& mod) )docstring"); py::class_(mod, "ColorManagementSystem") - .def(py::init<>()) - .def("getName", &mx::ColorManagementSystem::getName) - .def("loadLibrary", &mx::ColorManagementSystem::loadLibrary) - .def("supportsTransform", &mx::ColorManagementSystem::supportsTransform) + + .def(py::init<>(), + PYMATERIALX_DOCSTRING(R"docstring( + Initialize an instance of this class. +)docstring")) + + .def("getName", &mx::ColorManagementSystem::getName, + PYMATERIALX_DOCSTRING(R"docstring( + Return the name of the color management system. +)docstring")) + + .def("loadLibrary", &mx::ColorManagementSystem::loadLibrary, + py::arg("document"), + PYMATERIALX_DOCSTRING(R"docstring( + Load a library of implementations from the provided `document`, + replacing any previously loaded content. +)docstring")) + + .def("supportsTransform", &mx::ColorManagementSystem::supportsTransform, + py::arg("transform"), + PYMATERIALX_DOCSTRING(R"docstring( + Returns whether this color management system supports the provided + `transform`. +)docstring")) + .doc() = PYMATERIALX_DOCSTRING(R"docstring( Abstract base class for color management systems. @@ -66,8 +108,18 @@ void bindPyColorManagement(py::module& mod) )docstring"); py::class_(mod, "DefaultColorManagementSystem") - .def_static("create", &mx::DefaultColorManagementSystem::create) - .def("getName", &mx::DefaultColorManagementSystem::getName) + + .def_static("create", &mx::DefaultColorManagementSystem::create, + py::arg("target"), + PYMATERIALX_DOCSTRING(R"docstring( + Create a new `DefaultColorManagementSystem` instance. +)docstring")) + + .def("getName", &mx::DefaultColorManagementSystem::getName, + PYMATERIALX_DOCSTRING(R"docstring( + Return the name of the default color management system. +)docstring")) + .doc() = PYMATERIALX_DOCSTRING(R"docstring( Class for a default color management system. diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyGenContext.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyGenContext.cpp index f1d42f7c64..2a0b35d065 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyGenContext.cpp +++ b/source/PyMaterialX/PyMaterialXGenShader/PyGenContext.cpp @@ -14,6 +14,7 @@ namespace mx = MaterialX; void bindPyGenContext(py::module& mod) { py::class_(mod, "ApplicationVariableHandler") + .doc() = PYMATERIALX_DOCSTRING(R"docstring( Class representing a function to allow for handling of application variables for a given node. @@ -22,18 +23,78 @@ void bindPyGenContext(py::module& mod) )docstring"); py::class_(mod, "GenContext") - .def(py::init()) - .def("getShaderGenerator", &mx::GenContext::getShaderGenerator) - .def("getOptions", static_cast(&mx::GenContext::getOptions), py::return_value_policy::reference) - .def("registerSourceCodeSearchPath", static_cast(&mx::GenContext::registerSourceCodeSearchPath)) - .def("registerSourceCodeSearchPath", static_cast(&mx::GenContext::registerSourceCodeSearchPath)) - .def("resolveSourceFile", &mx::GenContext::resolveSourceFile) - .def("pushUserData", &mx::GenContext::pushUserData) - .def("setApplicationVariableHandler", &mx::GenContext::setApplicationVariableHandler) - .def("getApplicationVariableHandler", &mx::GenContext::getApplicationVariableHandler) + + .def(py::init(), + py::arg("shaderGenerator"), + PYMATERIALX_DOCSTRING(R"docstring( + Initialize an instance of this class using the given shader generator. +)docstring")) + + .def("getShaderGenerator", &mx::GenContext::getShaderGenerator, + PYMATERIALX_DOCSTRING(R"docstring( + Return the context's shader generator. +)docstring")) + + .def("getOptions", + static_cast(&mx::GenContext::getOptions), + py::return_value_policy::reference, + PYMATERIALX_DOCSTRING(R"docstring( + Return shader generation options. +)docstring")) + + .def("registerSourceCodeSearchPath", + static_cast(&mx::GenContext::registerSourceCodeSearchPath), + py::arg("path"), + PYMATERIALX_DOCSTRING(R"docstring( + Register a user search path for finding source code during code generation. + + :see: `resolveSourceFile()` +)docstring")) + + .def("registerSourceCodeSearchPath", + static_cast(&mx::GenContext::registerSourceCodeSearchPath), + py::arg("path"), + PYMATERIALX_DOCSTRING(R"docstring( + Register a user search path for finding source code during code generation. + + :see: `resolveSourceFile()` +)docstring")) + + .def("resolveSourceFile", &mx::GenContext::resolveSourceFile, + py::arg("filename"), + py::arg("localPath"), + PYMATERIALX_DOCSTRING(R"docstring( + Resolve a source code filename, first checking the given local path, + then checking any file paths registered by the user. + + :see: `registerSourceCodeSearchPath()` +)docstring")) + + .def("pushUserData", &mx::GenContext::pushUserData, + py::arg("name"), + py::arg("data"), + PYMATERIALX_DOCSTRING(R"docstring( + Add user data to the context to make it available during shader generation. +)docstring")) + + .def("setApplicationVariableHandler", + &mx::GenContext::setApplicationVariableHandler, + py::arg("handler"), + PYMATERIALX_DOCSTRING(R"docstring( + Set handler for application variables. +)docstring")) + + .def("getApplicationVariableHandler", + &mx::GenContext::getApplicationVariableHandler, + PYMATERIALX_DOCSTRING(R"docstring( + Return handler for application variables. +)docstring")) + .doc() = PYMATERIALX_DOCSTRING(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"); } @@ -41,7 +102,13 @@ void bindPyGenContext(py::module& mod) void bindPyGenUserData(py::module& mod) { py::class_(mod, "GenUserData") - .def("getSelf", static_cast(&mx::GenUserData::getSelf)) + + .def("getSelf", + static_cast(&mx::GenUserData::getSelf), + PYMATERIALX_DOCSTRING(R"docstring( + Return this object. +)docstring")) + .doc() = PYMATERIALX_DOCSTRING(R"docstring( Base class for custom user data needed during shader generation. diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyGenOptions.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyGenOptions.cpp index 67fc5fd8f1..2100419ab7 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyGenOptions.cpp +++ b/source/PyMaterialX/PyMaterialXGenShader/PyGenOptions.cpp @@ -16,149 +16,181 @@ void bindPyGenOptions(py::module& mod) PYMATERIALX_DOCSTRING(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) + + .value("SHADER_INTERFACE_COMPLETE", mx::ShaderInterfaceType::SHADER_INTERFACE_COMPLETE, + PYMATERIALX_DOCSTRING(R"docstring( + 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. +)docstring")) + + .value("SHADER_INTERFACE_REDUCED", mx::ShaderInterfaceType::SHADER_INTERFACE_REDUCED, + PYMATERIALX_DOCSTRING(R"docstring( + 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. +)docstring")) + .export_values(); py::enum_(mod, "HwSpecularEnvironmentMethod", PYMATERIALX_DOCSTRING(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) - .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("addUpstreamDependencies", &mx::GenOptions::addUpstreamDependencies) - .def_readwrite("libraryPrefix", &mx::GenOptions::libraryPrefix) - .def_readwrite("targetDistanceUnit", &mx::GenOptions::targetDistanceUnit) - .def_readwrite("hwTransparency", &mx::GenOptions::hwTransparency) - .def_readwrite("hwSpecularEnvironmentMethod", &mx::GenOptions::hwSpecularEnvironmentMethod) - .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("hwImplicitBitangents", &mx::GenOptions::hwImplicitBitangents) - .def_readwrite("emitColorTransforms", &mx::GenOptions::emitColorTransforms) - .def(py::init<>()) - .doc() = PYMATERIALX_DOCSTRING(R"docstring( - Class holding options to configure shader generation. + .value("SPECULAR_ENVIRONMENT_PREFILTER", mx::HwSpecularEnvironmentMethod::SPECULAR_ENVIRONMENT_PREFILTER, + PYMATERIALX_DOCSTRING(R"docstring( + Use pre-filtered environment maps for specular environment/indirect lighting. +)docstring")) - :see: https://materialx.org/docs/api/class_gen_options.html -)docstring"); + .value("SPECULAR_ENVIRONMENT_FIS", mx::HwSpecularEnvironmentMethod::SPECULAR_ENVIRONMENT_FIS, + PYMATERIALX_DOCSTRING(R"docstring( + Use Filtered Importance Sampling for specular environment/indirect lighting. +)docstring")) - auto GenOptions = mod.attr("GenOptions"); + .value("SPECULAR_ENVIRONMENT_NONE", mx::HwSpecularEnvironmentMethod::SPECULAR_ENVIRONMENT_NONE, + PYMATERIALX_DOCSTRING(R"docstring( + Do not use specular environment maps. +)docstring")) + + .export_values(); - GenOptions.attr("shaderInterfaceType").doc() = PYMATERIALX_DOCSTRING(R"docstring( + py::class_(mod, "GenOptions") + + .def_readwrite("shaderInterfaceType", &mx::GenOptions::shaderInterfaceType, + PYMATERIALX_DOCSTRING(R"docstring( (`ShaderInterfaceType`) Sets the type of shader interface to be generated. -)docstring"); +)docstring")) - GenOptions.attr("fileTextureVerticalFlip").doc() = PYMATERIALX_DOCSTRING(R"docstring( + .def_readwrite("fileTextureVerticalFlip", &mx::GenOptions::fileTextureVerticalFlip, + PYMATERIALX_DOCSTRING(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"); +)docstring")) - GenOptions.attr("targetColorSpaceOverride").doc() = PYMATERIALX_DOCSTRING(R"docstring( + .def_readwrite("targetColorSpaceOverride", &mx::GenOptions::targetColorSpaceOverride, + PYMATERIALX_DOCSTRING(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"); +)docstring")) - GenOptions.attr("addUpstreamDependencies").doc() = PYMATERIALX_DOCSTRING(R"docstring( + .def_readwrite("addUpstreamDependencies", &mx::GenOptions::addUpstreamDependencies, + PYMATERIALX_DOCSTRING(R"docstring( (`bool`) Sets whether to include upstream dependencies for the element to generate a shader for. -)docstring"); +)docstring")) - GenOptions.attr("libraryPrefix").doc() = PYMATERIALX_DOCSTRING(R"docstring( + .def_readwrite("libraryPrefix", &mx::GenOptions::libraryPrefix, + PYMATERIALX_DOCSTRING(R"docstring( (`FilePath`) The standard library prefix, which will be applied to calls to emitLibraryInclude during code generation. Defaults to `"libraries"`. -)docstring"); +)docstring")) - GenOptions.attr("targetDistanceUnit").doc() = PYMATERIALX_DOCSTRING(R"docstring( + .def_readwrite("targetDistanceUnit", &mx::GenOptions::targetDistanceUnit, + PYMATERIALX_DOCSTRING(R"docstring( (`str`) Define the target distance unit. Shader fragments will be generated to transform input distance values to the given unit. -)docstring"); +)docstring")) - GenOptions.attr("hwTransparency").doc() = PYMATERIALX_DOCSTRING(R"docstring( + .def_readwrite("hwTransparency", &mx::GenOptions::hwTransparency, + PYMATERIALX_DOCSTRING(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"); +)docstring")) - GenOptions.attr("hwSpecularEnvironmentMethod").doc() = PYMATERIALX_DOCSTRING(R"docstring( + .def_readwrite("hwSpecularEnvironmentMethod", &mx::GenOptions::hwSpecularEnvironmentMethod, + PYMATERIALX_DOCSTRING(R"docstring( (`HwSpecularEnvironmentMethod`) Sets the method to use for specular environment lighting for HW shader targets. -)docstring"); +)docstring")) - GenOptions.attr("hwWriteDepthMoments").doc() = PYMATERIALX_DOCSTRING(R"docstring( + .def_readwrite("hwWriteDepthMoments", &mx::GenOptions::hwWriteDepthMoments, + PYMATERIALX_DOCSTRING(R"docstring( (`bool`) Enables the writing of depth moments for HW shader targets. Defaults to `False`. -)docstring"); +)docstring")) - GenOptions.attr("hwShadowMap").doc() = PYMATERIALX_DOCSTRING(R"docstring( + .def_readwrite("hwShadowMap", &mx::GenOptions::hwShadowMap, + PYMATERIALX_DOCSTRING(R"docstring( (`bool`) Enables shadow mapping for HW shader targets. Defaults to `False`. -)docstring"); +)docstring")) - GenOptions.attr("hwMaxActiveLightSources").doc() = PYMATERIALX_DOCSTRING(R"docstring( + .def_readwrite("hwMaxActiveLightSources", &mx::GenOptions::hwMaxActiveLightSources, + PYMATERIALX_DOCSTRING(R"docstring( (`int`) Sets the maximum number of light sources that can be active at once. -)docstring"); +)docstring")) - GenOptions.attr("hwNormalizeUdimTexCoords").doc() = PYMATERIALX_DOCSTRING(R"docstring( + .def_readwrite("hwNormalizeUdimTexCoords", &mx::GenOptions::hwNormalizeUdimTexCoords, + PYMATERIALX_DOCSTRING(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"); +)docstring")) - GenOptions.attr("hwAmbientOcclusion").doc() = PYMATERIALX_DOCSTRING(R"docstring( + .def_readwrite("hwAmbientOcclusion", &mx::GenOptions::hwAmbientOcclusion, + PYMATERIALX_DOCSTRING(R"docstring( (`bool`) Enables ambient occlusion rendering for HW shader targets. Defaults to `False`. -)docstring"); +)docstring")) - GenOptions.attr("hwWriteAlbedoTable").doc() = PYMATERIALX_DOCSTRING(R"docstring( + .def_readwrite("hwWriteAlbedoTable", &mx::GenOptions::hwWriteAlbedoTable, + PYMATERIALX_DOCSTRING(R"docstring( (`bool`) Enables the writing of a directional albedo table. Defaults to `False`. -)docstring"); +)docstring")) - GenOptions.attr("hwImplicitBitangents").doc() = PYMATERIALX_DOCSTRING(R"docstring( + .def_readwrite("hwImplicitBitangents", &mx::GenOptions::hwImplicitBitangents, + PYMATERIALX_DOCSTRING(R"docstring( (`bool`) Calculate fallback bitangents from existing normals and tangents inside the bitangent node. -)docstring"); +)docstring")) - GenOptions.attr("emitColorTransforms").doc() = PYMATERIALX_DOCSTRING(R"docstring( + .def_readwrite("emitColorTransforms", &mx::GenOptions::emitColorTransforms, + PYMATERIALX_DOCSTRING(R"docstring( (`bool`) Enable emitting colorspace transform code if a color management system is defined. Defaults to `True`. +)docstring")) + + .def(py::init<>(), PYMATERIALX_DOCSTRING(R"docstring( + Initializes an instance of this class. +)docstring")) + + .doc() = PYMATERIALX_DOCSTRING(R"docstring( + Class holding options to configure shader generation. + + :see: https://materialx.org/docs/api/class_gen_options.html )docstring"); // FIXME(SH): Expose hwDirectionalAlbedoMethod and hwTransmissionRenderMethod? diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyHwShaderGenerator.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyHwShaderGenerator.cpp index 4192c7c938..c85b347906 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyHwShaderGenerator.cpp +++ b/source/PyMaterialX/PyMaterialXGenShader/PyHwShaderGenerator.cpp @@ -27,10 +27,40 @@ void bindPyHwShaderGenerator(py::module& mod) mod.attr("HW_ATTR_TRANSPARENT") = mx::HW::ATTR_TRANSPARENT; py::class_(mod, "HwShaderGenerator") - .def("getClosureContexts", &mx::HwShaderGenerator::getClosureContexts) - .def("bindLightShader", &mx::HwShaderGenerator::bindLightShader) - .def("unbindLightShader", &mx::HwShaderGenerator::unbindLightShader) - .def("unbindLightShaders", &mx::HwShaderGenerator::unbindLightShaders) + + .def("getClosureContexts", &mx::HwShaderGenerator::getClosureContexts, + py::arg("node"), + py::arg("cct"), + PYMATERIALX_DOCSTRING(R"docstring( + Return the closure contexts defined for the given node. +)docstring")) + + .def_static("bindLightShader", &mx::HwShaderGenerator::bindLightShader, + py::arg("nodeDef"), + py::arg("lightTypeId"), + py::arg("context"), + PYMATERIALX_DOCSTRING(R"docstring( + Bind a light shader to a light type ID, for usage in surface shaders created + by the generator. + + The `lightTypeId` should be a unique identifier for the light type (node + definition) and the same ID should be used when setting light parameters on + a generated surface shader. +)docstring")) + + .def_static("unbindLightShader", &mx::HwShaderGenerator::unbindLightShader, + py::arg("lightTypeId"), + py::arg("context"), + PYMATERIALX_DOCSTRING(R"docstring( + Unbind a light shader previously bound to the given light type ID. +)docstring")) + + .def_static("unbindLightShaders", &mx::HwShaderGenerator::unbindLightShaders, + py::arg("context"), + PYMATERIALX_DOCSTRING(R"docstring( + Unbind all light shaders previously bound. +)docstring")) + .doc() = PYMATERIALX_DOCSTRING(R"docstring( Base class for shader generators targeting HW rendering. @@ -41,8 +71,22 @@ void bindPyHwShaderGenerator(py::module& mod) void bindPyHwResourceBindingContext(py::module& mod) { py::class_(mod, "HwResourceBindingContext") - .def("emitDirectives", &mx::HwResourceBindingContext::emitDirectives) - .def("emitResourceBindings", &mx::HwResourceBindingContext::emitResourceBindings) + + .def("emitDirectives", &mx::HwResourceBindingContext::emitDirectives, + py::arg("context"), + py::arg("stage"), + PYMATERIALX_DOCSTRING(R"docstring( + Emit directives required for binding support. +)docstring")) + + .def("emitResourceBindings", &mx::HwResourceBindingContext::emitResourceBindings, + py::arg("context"), + py::arg("uniforms"), + py::arg("stage"), + PYMATERIALX_DOCSTRING(R"docstring( + Emit uniforms with binding information. +)docstring")) + .doc() = PYMATERIALX_DOCSTRING(R"docstring( Class representing a context for resource binding for hardware resources. diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyShader.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyShader.cpp index 2af5dee01f..454cad2019 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyShader.cpp +++ b/source/PyMaterialX/PyMaterialXGenShader/PyShader.cpp @@ -18,17 +18,82 @@ void bindPyShader(py::module& mod) // ShaderStage& and without this parameter it would return a copy and not a // reference py::class_(mod, "Shader") - .def(py::init()) - .def("getName", &mx::Shader::getName) - .def("hasStage", &mx::Shader::hasStage) - .def("numStages", &mx::Shader::numStages) - .def("getStage", static_cast(&mx::Shader::getStage), py::return_value_policy::reference) - .def("getStage", static_cast(&mx::Shader::getStage), py::return_value_policy::reference) - .def("getSourceCode", &mx::Shader::getSourceCode) - .def("hasAttribute", &mx::Shader::hasAttribute) - .def("getAttribute", &mx::Shader::getAttribute) - .def("setAttribute", static_cast(&mx::Shader::setAttribute)) - .def("setAttribute", static_cast(&mx::Shader::setAttribute)) + + .def(py::init(), + py::arg("name"), + py::arg("graph"), + PYMATERIALX_DOCSTRING(R"docstring( + Initialize an instance of this class using the given name and shader graph. +)docstring")) + + .def("getName", &mx::Shader::getName, + PYMATERIALX_DOCSTRING(R"docstring( + Return the shader name. +)docstring")) + + .def("hasStage", &mx::Shader::hasStage, + py::arg("name"), + PYMATERIALX_DOCSTRING(R"docstring( + Return whether a stage of the given `name` exists. +)docstring")) + + .def("numStages", &mx::Shader::numStages, + PYMATERIALX_DOCSTRING(R"docstring( + Return the number of shader stages for this shader. +)docstring")) + + .def("getStage", + static_cast(&mx::Shader::getStage), + py::return_value_policy::reference, + py::arg("index"), + PYMATERIALX_DOCSTRING(R"docstring( + Return a stage by index. +)docstring")) + + .def("getStage", + static_cast(&mx::Shader::getStage), + py::return_value_policy::reference, + py::arg("name"), + PYMATERIALX_DOCSTRING(R"docstring( + Return a stage by name. +)docstring")) + + .def("getSourceCode", &mx::Shader::getSourceCode, + py::arg_v("stage", + mx::Stage::PIXEL, + "MaterialX.PyMaterialXGenShader.PIXEL_STAGE"), + PYMATERIALX_DOCSTRING(R"docstring( + Return the shader source code for a given shader stage. +)docstring")) + + .def("hasAttribute", &mx::Shader::hasAttribute, + py::arg("attrib"), + PYMATERIALX_DOCSTRING(R"docstring( + Return `True` if the shader has a given named attribute. +)docstring")) + + .def("getAttribute", &mx::Shader::getAttribute, + py::arg("attrib"), + PYMATERIALX_DOCSTRING(R"docstring( + Return the value for a named attribute, or `None` if no such attribute is + found. +)docstring")) + + .def("setAttribute", + static_cast(&mx::Shader::setAttribute), + py::arg("attrib"), + PYMATERIALX_DOCSTRING(R"docstring( + Set a flag attribute on the shader. +)docstring")) + + .def("setAttribute", + static_cast(&mx::Shader::setAttribute), + py::arg("attrib"), + py::arg("value"), + PYMATERIALX_DOCSTRING(R"docstring( + Set a value attribute on the shader. +)docstring")) + .doc() = PYMATERIALX_DOCSTRING(R"docstring( Class containing all data needed during shader generation. After generation is completed it will contain the resulting source code diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyShaderGenerator.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyShaderGenerator.cpp index ea4db62fa9..90102d0dae 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyShaderGenerator.cpp +++ b/source/PyMaterialX/PyMaterialXGenShader/PyShaderGenerator.cpp @@ -15,14 +15,74 @@ namespace mx = MaterialX; void bindPyShaderGenerator(py::module& mod) { py::class_(mod, "ShaderGenerator") - .def("getTarget", &mx::ShaderGenerator::getTarget) - .def("generate", &mx::ShaderGenerator::generate) - .def("setColorManagementSystem", &mx::ShaderGenerator::setColorManagementSystem) - .def("getColorManagementSystem", &mx::ShaderGenerator::getColorManagementSystem) - .def("setUnitSystem", &mx::ShaderGenerator::setUnitSystem) - .def("getUnitSystem", &mx::ShaderGenerator::getUnitSystem) - .def("getTokenSubstitutions", &mx::ShaderGenerator::getTokenSubstitutions) - .def("registerShaderMetadata", &mx::ShaderGenerator::registerShaderMetadata) + + .def("getTarget", &mx::ShaderGenerator::getTarget, + PYMATERIALX_DOCSTRING(R"docstring( + Return the name of the target this generator is for. +)docstring")) + + .def("generate", &mx::ShaderGenerator::generate, + py::arg("name"), + py::arg("element"), + py::arg("context"), + PYMATERIALX_DOCSTRING(R"docstring( + Generate a shader starting from the given `element`, translating the + element and all dependencies upstream into shader code. +)docstring")) + + .def("setColorManagementSystem", + &mx::ShaderGenerator::setColorManagementSystem, + py::arg("colorManagementSystem"), + PYMATERIALX_DOCSTRING(R"docstring( + Set the color management system for the shader generator. +)docstring")) + + .def("getColorManagementSystem", + &mx::ShaderGenerator::getColorManagementSystem, + PYMATERIALX_DOCSTRING(R"docstring( + Return the color management system for the shader generator. +)docstring")) + + .def("setUnitSystem", &mx::ShaderGenerator::setUnitSystem, + py::arg("unitSystem"), + PYMATERIALX_DOCSTRING(R"docstring( + Set the unit system for the shader generator. +)docstring")) + + .def("getUnitSystem", &mx::ShaderGenerator::getUnitSystem, + PYMATERIALX_DOCSTRING(R"docstring( + Return the unit system for the shader generator. +)docstring")) + + .def("getTokenSubstitutions", + &mx::ShaderGenerator::getTokenSubstitutions, + PYMATERIALX_DOCSTRING(R"docstring( + Return the map of token substitutions used by the generator. +)docstring")) + + .def("registerShaderMetadata", + &mx::ShaderGenerator::registerShaderMetadata, + py::arg("doc"), + py::arg("context"), + PYMATERIALX_DOCSTRING(R"docstring( + Register metadata that should be exported to the generated shaders. + + Supported metadata includes standard UI attributes like `"uiname"`, + `"uifolder"`, `"uimin"`, `"uimax"`, etc. + + The metadata is extendable by defining custom attributes using + `AttributeDef` elements. + + Any `AttributeDef` in the given document with `exportable="true"` will be + exported as shader metadata when found on nodes during shader generation. + + Derived shader generators may override this method to change the + registration. + + Applications must explicitly call this method before shader generation to + enable export of metadata. +)docstring")) + .doc() = PYMATERIALX_DOCSTRING(R"docstring( Base class for shader generators. All third-party shader generators should derive from this class. diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyShaderPort.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyShaderPort.cpp index cde3b0e585..94a7b8254e 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyShaderPort.cpp +++ b/source/PyMaterialX/PyMaterialXGenShader/PyShaderPort.cpp @@ -13,28 +13,128 @@ namespace mx = MaterialX; void bindPyShaderPort(py::module& mod) { py::class_(mod, "ShaderPort") - .def("setType", &mx::ShaderPort::setType) - .def("getType", &mx::ShaderPort::getType) - .def("setName", &mx::ShaderPort::setName) - .def("getName", &mx::ShaderPort::getName) - .def("getFullName", &mx::ShaderPort::getFullName) - .def("setVariable", &mx::ShaderPort::setVariable) - .def("getVariable", &mx::ShaderPort::getVariable) - .def("setSemantic", &mx::ShaderPort::setSemantic) - .def("getSemantic", &mx::ShaderPort::getSemantic) - .def("setValue", &mx::ShaderPort::setValue) - .def("getValue", &mx::ShaderPort::getValue) - .def("getValueString", &mx::ShaderPort::getValueString) - .def("setGeomProp", &mx::ShaderPort::setGeomProp) - .def("getGeomProp", &mx::ShaderPort::getGeomProp) - .def("setPath", &mx::ShaderPort::setPath) - .def("getPath", &mx::ShaderPort::getPath) - .def("setUnit", &mx::ShaderPort::setUnit) - .def("getUnit", &mx::ShaderPort::getUnit) - .def("setColorSpace", &mx::ShaderPort::setColorSpace) - .def("getColorSpace", &mx::ShaderPort::getColorSpace) - .def("isUniform", &mx::ShaderPort::isUniform) - .def("isEmitted", &mx::ShaderPort::isEmitted) + + .def("setType", &mx::ShaderPort::setType, + py::arg("typeDesc"), + PYMATERIALX_DOCSTRING(R"docstring( + Set the data type for this port. +)docstring")) + + .def("getType", &mx::ShaderPort::getType, + PYMATERIALX_DOCSTRING(R"docstring( + Return the data type of this port. +)docstring")) + + .def("setName", &mx::ShaderPort::setName, + py::arg("name"), + PYMATERIALX_DOCSTRING(R"docstring( + Set the name of this port. +)docstring")) + + .def("getName", &mx::ShaderPort::getName, + PYMATERIALX_DOCSTRING(R"docstring( + Return the name of this port. +)docstring")) + + .def("getFullName", &mx::ShaderPort::getFullName, + PYMATERIALX_DOCSTRING(R"docstring( + Return the full name of this port. +)docstring")) + + .def("setVariable", &mx::ShaderPort::setVariable, + py::arg("name"), + PYMATERIALX_DOCSTRING(R"docstring( + Set the variable name of this port. +)docstring")) + + .def("getVariable", &mx::ShaderPort::getVariable, + PYMATERIALX_DOCSTRING(R"docstring( + Return the variable name of this port. +)docstring")) + + .def("setSemantic", &mx::ShaderPort::setSemantic, + py::arg("semantic"), + PYMATERIALX_DOCSTRING(R"docstring( + Set the variable semantic of this port. +)docstring")) + + .def("getSemantic", &mx::ShaderPort::getSemantic, + PYMATERIALX_DOCSTRING(R"docstring( + Return the variable semantic of this port. +)docstring")) + + .def("setValue", &mx::ShaderPort::setValue, + py::arg("value"), + PYMATERIALX_DOCSTRING(R"docstring( + Set a value on this port. +)docstring")) + + .def("getValue", &mx::ShaderPort::getValue, + PYMATERIALX_DOCSTRING(R"docstring( + Return the value set on this port. +)docstring")) + + .def("getValueString", &mx::ShaderPort::getValueString, + PYMATERIALX_DOCSTRING(R"docstring( + Return the value set on this port as a string, or an empty string if there + is no value. +)docstring")) + + .def("setGeomProp", &mx::ShaderPort::setGeomProp, + py::arg("geomprop"), + PYMATERIALX_DOCSTRING(R"docstring( + Set geomprop name if the input has a default geomprop to be assigned when + it is unconnected. +)docstring")) + + .def("getGeomProp", &mx::ShaderPort::getGeomProp, + PYMATERIALX_DOCSTRING(R"docstring( + Return geomprop name. +)docstring")) + + .def("setPath", &mx::ShaderPort::setPath, + py::arg("path"), + PYMATERIALX_DOCSTRING(R"docstring( + Set the path to this port. +)docstring")) + + .def("getPath", &mx::ShaderPort::getPath, + PYMATERIALX_DOCSTRING(R"docstring( + Return the path to this port. +)docstring")) + + .def("setUnit", &mx::ShaderPort::setUnit, + py::arg("unit"), + PYMATERIALX_DOCSTRING(R"docstring( + Set a unit type for the value on this port. +)docstring")) + + .def("getUnit", &mx::ShaderPort::getUnit, + PYMATERIALX_DOCSTRING(R"docstring( + Return the unit type for the value on this port. +)docstring")) + + .def("setColorSpace", &mx::ShaderPort::setColorSpace, + py::arg("colorspace"), + PYMATERIALX_DOCSTRING(R"docstring( + Set a source color space for the value on this port. +)docstring")) + + .def("getColorSpace", &mx::ShaderPort::getColorSpace, + PYMATERIALX_DOCSTRING(R"docstring( + Return the source color space for the value on this port. +)docstring")) + + .def("isUniform", &mx::ShaderPort::isUniform, + PYMATERIALX_DOCSTRING(R"docstring( + Return the uniform flag on this port. +)docstring")) + + .def("isEmitted", &mx::ShaderPort::isEmitted, + PYMATERIALX_DOCSTRING(R"docstring( + Return the emitted state of this port. +)docstring")) + .doc() = PYMATERIALX_DOCSTRING(R"docstring( Class representing an input or output port on a `ShaderNode`. diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyShaderStage.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyShaderStage.cpp index 0901b80877..ef2107a13e 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyShaderStage.cpp +++ b/source/PyMaterialX/PyMaterialXGenShader/PyShaderStage.cpp @@ -21,19 +21,58 @@ void bindPyShaderStage(py::module& mod) )docstring"); py::class_(mod, "VariableBlock") - .def(py::init()) - .def("getName", &mx::VariableBlock::getName) - .def("getInstance", &mx::VariableBlock::getInstance) - .def("empty", &mx::VariableBlock::empty) - .def("size", &mx::VariableBlock::size) - .def("find", static_cast(&mx::VariableBlock::find)) - .def("find", (mx::ShaderPort* (mx::VariableBlock::*)(const mx::ShaderPortPredicate& )) &mx::VariableBlock::find) + + .def(py::init(), + py::arg("name"), + py::arg("instance"), + PYMATERIALX_DOCSTRING(R"docstring( + Initialize an instance of this class using the given `name` and `instance` + name. +)docstring")) + + .def("getName", &mx::VariableBlock::getName, + PYMATERIALX_DOCSTRING(R"docstring( + Return the name of this block. +)docstring")) + + .def("getInstance", &mx::VariableBlock::getInstance, + PYMATERIALX_DOCSTRING(R"docstring( + Return the instance name of this block. +)docstring")) + + .def("empty", &mx::VariableBlock::empty, + PYMATERIALX_DOCSTRING(R"docstring( + Return `True` if the block has no variables. +)docstring")) + + .def("size", &mx::VariableBlock::size, + PYMATERIALX_DOCSTRING(R"docstring( + Return the number of variables in this block. +)docstring")) + + .def("find", + static_cast(&mx::VariableBlock::find), + py::arg("name"), + PYMATERIALX_DOCSTRING(R"docstring( + Return a variable by name. + + Returns `None` if no variable is found by the given `name`. +)docstring")) + + .def("find", + (mx::ShaderPort* (mx::VariableBlock::*)(const mx::ShaderPortPredicate& )) &mx::VariableBlock::find, + py::arg("predicate"), + PYMATERIALX_DOCSTRING(R"docstring( + Find a port based on a predicate. +)docstring")) + .def("__len__", &mx::VariableBlock::size) .def("__getitem__", [](const mx::VariableBlock &vb, size_t i) { if (i >= vb.size()) throw py::index_error(); return vb[i]; }, py::return_value_policy::reference_internal) + .doc() = PYMATERIALX_DOCSTRING(R"docstring( Class representing a block of variables in a shader stage. @@ -41,19 +80,81 @@ void bindPyShaderStage(py::module& mod) )docstring"); py::class_(mod, "ShaderStage") - .def(py::init()) - .def("getName", &mx::ShaderStage::getName) - .def("getFunctionName", &mx::ShaderStage::getFunctionName) - .def("getSourceCode", &mx::ShaderStage::getSourceCode) - .def("getUniformBlock", static_cast(&mx::ShaderStage::getUniformBlock)) - .def("getInputBlock", static_cast(&mx::ShaderStage::getInputBlock)) - .def("getOutputBlock", static_cast(&mx::ShaderStage::getOutputBlock)) - .def("getConstantBlock", static_cast(&mx::ShaderStage::getConstantBlock)) - .def("getUniformBlocks", &mx::ShaderStage::getUniformBlocks) - .def("getInputBlocks", &mx::ShaderStage::getInputBlocks) - .def("getIncludes", &mx::ShaderStage::getIncludes) - .def("getSourceDependencies", &mx::ShaderStage::getSourceDependencies) - .def("getOutputBlocks", &mx::ShaderStage::getOutputBlocks) + + .def(py::init(), + py::arg("name"), + py::arg("syntax"), + PYMATERIALX_DOCSTRING(R"docstring( + Initialize an instance of this class using the given `name` and `syntax`. +)docstring")) + + .def("getName", &mx::ShaderStage::getName, + PYMATERIALX_DOCSTRING(R"docstring( + Return the stage name. +)docstring")) + + .def("getFunctionName", &mx::ShaderStage::getFunctionName, + PYMATERIALX_DOCSTRING(R"docstring( + Return the stage function name. +)docstring")) + + .def("getSourceCode", &mx::ShaderStage::getSourceCode, + PYMATERIALX_DOCSTRING(R"docstring( + Return the stage source code. +)docstring")) + + .def("getUniformBlock", + static_cast(&mx::ShaderStage::getUniformBlock), + py::arg("name"), + PYMATERIALX_DOCSTRING(R"docstring( + Return the uniform variable block with given name. +)docstring")) + + .def("getInputBlock", + static_cast(&mx::ShaderStage::getInputBlock), + py::arg("name"), + PYMATERIALX_DOCSTRING(R"docstring( + Return the input variable block with given `name`. +)docstring")) + + .def("getOutputBlock", + static_cast(&mx::ShaderStage::getOutputBlock), + py::arg("name"), + PYMATERIALX_DOCSTRING(R"docstring( + Return the output variable block with given `name`. +)docstring")) + + .def("getConstantBlock", + static_cast(&mx::ShaderStage::getConstantBlock), + PYMATERIALX_DOCSTRING(R"docstring( + Return the constant variable block. +)docstring")) + + .def("getUniformBlocks", &mx::ShaderStage::getUniformBlocks, + PYMATERIALX_DOCSTRING(R"docstring( + Return a map of all uniform blocks. +)docstring")) + + .def("getInputBlocks", &mx::ShaderStage::getInputBlocks, + PYMATERIALX_DOCSTRING(R"docstring( + Return a map of all input blocks. +)docstring")) + + .def("getIncludes", &mx::ShaderStage::getIncludes, + PYMATERIALX_DOCSTRING(R"docstring( + Return a set of all include files. +)docstring")) + + .def("getSourceDependencies", &mx::ShaderStage::getSourceDependencies, + PYMATERIALX_DOCSTRING(R"docstring( + Return a set of all source dependencies +)docstring")) + + .def("getOutputBlocks", &mx::ShaderStage::getOutputBlocks, + PYMATERIALX_DOCSTRING(R"docstring( + Return a map of all output blocks. +)docstring")) + .doc() = PYMATERIALX_DOCSTRING(R"docstring( Class representing a shader stage, containing the state and resulting source code for the stage. diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyShaderTranslator.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyShaderTranslator.cpp index d8a8e1bd07..3cc922658f 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyShaderTranslator.cpp +++ b/source/PyMaterialX/PyMaterialXGenShader/PyShaderTranslator.cpp @@ -13,9 +13,27 @@ namespace mx = MaterialX; void bindPyShaderTranslator(py::module& mod) { py::class_(mod, "ShaderTranslator") - .def_static("create", &mx::ShaderTranslator::create) - .def("translateShader", &mx::ShaderTranslator::translateShader) - .def("translateAllMaterials", &mx::ShaderTranslator::translateAllMaterials) + + .def_static("create", &mx::ShaderTranslator::create, + PYMATERIALX_DOCSTRING(R"docstring( + Create an instance of this class. +)docstring")) + + .def("translateShader", &mx::ShaderTranslator::translateShader, + py::arg("shader"), + py::arg("destCategory"), + PYMATERIALX_DOCSTRING(R"docstring( + Translate a shader node to the destination shading model. +)docstring")) + + .def("translateAllMaterials", &mx::ShaderTranslator::translateAllMaterials, + py::arg("doc"), + py::arg("destShader"), + PYMATERIALX_DOCSTRING(R"docstring( + Translate each material in the input document to the destination shading + model. +)docstring")) + .doc() = PYMATERIALX_DOCSTRING(R"docstring( A helper class for translating content between shading models. diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyTypeDesc.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyTypeDesc.cpp index ad5096b10a..367188814a 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyTypeDesc.cpp +++ b/source/PyMaterialX/PyMaterialXGenShader/PyTypeDesc.cpp @@ -16,47 +16,110 @@ void bindPyTypeDesc(py::module& mod) // by the container they are stored in and should not be destroyed when // garbage collected by the python interpreter py::class_>(mod, "TypeDesc") + .def_static("get", &mx::TypeDesc::get, py::arg("name"), PYMATERIALX_DOCSTRING(R"docstring( Return a type descriptor for the given `name`. - :type name: `str` :param name: The name of the type descriptor to return. + :type name: str :return: A type descriptor for the given `name`, or `None` if no type with the given `name` could be found. )docstring")) - .def("getName", &mx::TypeDesc::getName) - .def("getBaseType", &mx::TypeDesc::getBaseType) + + .def("getName", &mx::TypeDesc::getName, + PYMATERIALX_DOCSTRING(R"docstring( + Return the name of the type. +)docstring")) + + .def("getBaseType", &mx::TypeDesc::getBaseType, + PYMATERIALX_DOCSTRING(R"docstring( + Return the basetype for the type. +)docstring")) + .def("getChannelIndex", &mx::TypeDesc::getChannelIndex, py::arg("channel"), PYMATERIALX_DOCSTRING(R"docstring( Return the channel index for the supplied channel name. - :type channel: `str` :param channel: The name of the channel whose index to return. + :type channel: str :return: The index that corresponds to the given `channel` name, or `-1` on failure to find a matching index. )docstring")) - .def("getSemantic", &mx::TypeDesc::getSemantic) - .def("getSize", &mx::TypeDesc::getSize) - .def("isEditable", &mx::TypeDesc::isEditable) - .def("isScalar", &mx::TypeDesc::isScalar) - .def("isAggregate", &mx::TypeDesc::isAggregate) - .def("isArray", &mx::TypeDesc::isArray) - .def("isFloat2", &mx::TypeDesc::isFloat2) - .def("isFloat3", &mx::TypeDesc::isFloat3) - .def("isFloat4", &mx::TypeDesc::isFloat4) + + .def("getSemantic", &mx::TypeDesc::getSemantic, + PYMATERIALX_DOCSTRING(R"docstring( + Return the semantic for the type. +)docstring")) + + .def("getSize", &mx::TypeDesc::getSize, + PYMATERIALX_DOCSTRING(R"docstring( + Return the number of elements the type is composed of. + + Will return `1` for scalar types and a size greater than `1` for aggregate + types. + + For array types, `0` is returned, since the number of elements is undefined + until an array is instantiated. +)docstring")) + + .def("isEditable", &mx::TypeDesc::isEditable, + PYMATERIALX_DOCSTRING(R"docstring( + Returns `True` if the type is editable by users. + + Editable types are allowed to be published as shader uniforms and hence + must be presentable in a user interface. +)docstring")) + + .def("isScalar", &mx::TypeDesc::isScalar, + PYMATERIALX_DOCSTRING(R"docstring( + Return `True` if the type is a scalar type. +)docstring")) + + .def("isAggregate", &mx::TypeDesc::isAggregate, + PYMATERIALX_DOCSTRING(R"docstring( + Return `True` if the type is an aggregate type. +)docstring")) + + .def("isArray", &mx::TypeDesc::isArray, + PYMATERIALX_DOCSTRING(R"docstring( + Return `True` if the type is an array type. +)docstring")) + + .def("isFloat2", &mx::TypeDesc::isFloat2, + PYMATERIALX_DOCSTRING(R"docstring( + Return `True` if the type is an aggregate of 2 floats. +)docstring")) + + .def("isFloat3", &mx::TypeDesc::isFloat3, + PYMATERIALX_DOCSTRING(R"docstring( + Return `True` if the type is an aggregate of 3 floats. +)docstring")) + + .def("isFloat4", &mx::TypeDesc::isFloat4, + PYMATERIALX_DOCSTRING(R"docstring( + Return `True` if the type is an aggregate of 4 floats. +)docstring")) + .doc() = PYMATERIALX_DOCSTRING(R"docstring( Class implementing 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. A unique type descriptor pointer is the identifier used for - types, and can be used for type comparisons as well as getting more information - about the type. All standard library data types are registered by default and their - type descriptors can be accessed from the `Type` namespace, e.g. `MaterialX::Type::FLOAT`. - If custom types are used they must be registered by calling `TypeDesc.registerType()`. - Descriptors for registered types can be retrieved using `TypeDesc.get()`, see below. + All types need to have a type descriptor registered in order for shader + generators to know about the type. + + A unique type descriptor is the identifier used for types, and can be used + for type comparisons as well as getting more information about the type. + + All standard library data types are registered by default, and their type + descriptors can be accessed from the `Type` namespace in C++, e.g. + `MaterialX::Type::FLOAT`. + + If custom types are used, they must be registered by calling + `TypeDesc::registerType()` in C++. + + Descriptors for registered types can be retrieved using `TypeDesc.get()`. :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 ee6753f207..5aeeca7e26 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyUnitSystem.cpp +++ b/source/PyMaterialX/PyMaterialXGenShader/PyUnitSystem.cpp @@ -15,11 +15,37 @@ namespace mx = MaterialX; void bindPyUnitSystem(py::module& mod) { py::class_(mod, "UnitTransform") - .def(py::init()) - .def_readwrite("sourceUnit", &mx::UnitTransform::sourceUnit) - .def_readwrite("targetUnit", &mx::UnitTransform::targetUnit) - .def_readwrite("type", &mx::UnitTransform::type) - .def_readwrite("unitType", &mx::UnitTransform::type) + + .def(py::init(), + py::arg("sourceUnit"), + py::arg("targetUnit"), + py::arg("typeDesc"), + py::arg("unitType"), + PYMATERIALX_DOCSTRING(R"docstring( + Initialize an instance of this class using the given source unit, target + unit, type descriptor, and unit type name. +)docstring")) + + .def_readwrite("sourceUnit", &mx::UnitTransform::sourceUnit, + PYMATERIALX_DOCSTRING(R"docstring( + The source unit of the unit transform. +)docstring")) + + .def_readwrite("targetUnit", &mx::UnitTransform::targetUnit, + PYMATERIALX_DOCSTRING(R"docstring( + The target unit of the unit transform. +)docstring")) + + .def_readwrite("typeDesc", &mx::UnitTransform::type, + PYMATERIALX_DOCSTRING(R"docstring( + The type descriptor of the unit transform. +)docstring")) + + .def_readwrite("unitType", &mx::UnitTransform::type, + PYMATERIALX_DOCSTRING(R"docstring( + The unit type name of the unit transform. +)docstring")) + .doc() = PYMATERIALX_DOCSTRING(R"docstring( Class implementing a structure that represents unit transform information. @@ -27,12 +53,42 @@ void bindPyUnitSystem(py::module& mod) )docstring"); py::class_(mod, "UnitSystem") - .def_static("create", &mx::UnitSystem::create) - .def("getName", &mx::UnitSystem::getName) - .def("loadLibrary", &mx::UnitSystem::loadLibrary) - .def("supportsTransform", &mx::UnitSystem::supportsTransform) - .def("setUnitConverterRegistry", &mx::UnitSystem::setUnitConverterRegistry) - .def("getUnitConverterRegistry", &mx::UnitSystem::getUnitConverterRegistry) + + .def_static("create", &mx::UnitSystem::create, + py::arg("language"), + PYMATERIALX_DOCSTRING(R"docstring( + Create an instance of this class using the given language. +)docstring")) + + .def("getName", &mx::UnitSystem::getName, + PYMATERIALX_DOCSTRING(R"docstring( + Return the UnitSystem name. +)docstring")) + + .def("loadLibrary", &mx::UnitSystem::loadLibrary, + py::arg("document"), + PYMATERIALX_DOCSTRING(R"docstring( + Assign document with unit implementations replacing any previously loaded + content. +)docstring")) + + .def("supportsTransform", &mx::UnitSystem::supportsTransform, + py::arg("transform"), + PYMATERIALX_DOCSTRING(R"docstring( + Returns whether this unit system supports the given `transform`. +)docstring")) + + .def("setUnitConverterRegistry", &mx::UnitSystem::setUnitConverterRegistry, + py::arg("registry"), + PYMATERIALX_DOCSTRING(R"docstring( + Assign unit converter registry replacing any previous assignment. +)docstring")) + + .def("getUnitConverterRegistry", &mx::UnitSystem::getUnitConverterRegistry, + PYMATERIALX_DOCSTRING(R"docstring( + Return the currently assigned unit converter registry. +)docstring")) + .doc() = PYMATERIALX_DOCSTRING(R"docstring( Class implementing base unit system support. diff --git a/source/PyMaterialX/PyMaterialXGenShader/PyUtil.cpp b/source/PyMaterialX/PyMaterialXGenShader/PyUtil.cpp index 8fbb26d7a0..2051c0a2e1 100644 --- a/source/PyMaterialX/PyMaterialXGenShader/PyUtil.cpp +++ b/source/PyMaterialX/PyMaterialXGenShader/PyUtil.cpp @@ -68,8 +68,8 @@ void bindPyUtil(py::module& mod) PYMATERIALX_DOCSTRING(R"docstring( Find all renderable material nodes in the given document. - :type doc: Document :param doc: The document to examine. + :type doc: Document :return: A list of renderable material nodes. )docstring")); @@ -81,8 +81,8 @@ void bindPyUtil(py::module& mod) nodes if present, or graph outputs of renderable types if no material nodes are found. - :type doc: Document :param doc: The document to examine. + :type doc: Document :return: A list of renderable elements. )docstring")); @@ -135,8 +135,8 @@ void bindPyUtil(py::module& mod) Determine whether the given `output` is directly connected to a node that generates world-space coordinates (e.g. the "normalmap" node). - :type output: Output :param output: The output to check. + :type output: Output :return: The node if found. )docstring")); @@ -148,6 +148,8 @@ void bindPyUtil(py::module& mod) attributes either on the starting node or any graph upstream of that node. :param output: The starting node. + :type output: Node :param attributes: Attributes to test for. + :type attributes: List[str] )docstring")); }