From b589282f4b5553b19d5be6c0dee788615b98264e Mon Sep 17 00:00:00 2001 From: Stefan Habel <19556655+StefanHabel@users.noreply.github.com> Date: Tue, 31 Oct 2023 00:08:24 -0700 Subject: [PATCH] Docstrings for PyMaterialXRenderOsl. (#1567) Signed-off-by: Stefan Habel <19556655+StefanHabel@users.noreply.github.com> --- .../PyMaterialXRenderOsl/PyOslRenderer.cpp | 241 ++++++++++++++++-- 1 file changed, 221 insertions(+), 20 deletions(-) diff --git a/source/PyMaterialX/PyMaterialXRenderOsl/PyOslRenderer.cpp b/source/PyMaterialX/PyMaterialXRenderOsl/PyOslRenderer.cpp index 13f5ec00f4..6b9af1ad1e 100644 --- a/source/PyMaterialX/PyMaterialXRenderOsl/PyOslRenderer.cpp +++ b/source/PyMaterialX/PyMaterialXRenderOsl/PyOslRenderer.cpp @@ -13,26 +13,227 @@ namespace mx = MaterialX; void bindPyOslRenderer(py::module& mod) { py::class_(mod, "OslRenderer") - .def_static("create", &mx::OslRenderer::create) - .def_readwrite_static("OSL_CLOSURE_COLOR_STRING", &mx::OslRenderer::OSL_CLOSURE_COLOR_STRING) - .def("initialize", &mx::OslRenderer::initialize, py::arg("renderContextHandle") = nullptr) - .def("createProgram", static_cast(&mx::OslRenderer::createProgram)) - .def("createProgram", static_cast(&mx::OslRenderer::createProgram)) - .def("validateInputs", &mx::OslRenderer::validateInputs) - .def("render", &mx::OslRenderer::render) - .def("captureImage", &mx::OslRenderer::captureImage) - .def("setOslCompilerExecutable", &mx::OslRenderer::setOslCompilerExecutable) - .def("setOslIncludePath", &mx::OslRenderer::setOslIncludePath) - .def("setOslOutputFilePath", &mx::OslRenderer::setOslOutputFilePath) - .def("setShaderParameterOverrides", &mx::OslRenderer::setShaderParameterOverrides) - .def("setOslShaderOutput", &mx::OslRenderer::setOslShaderOutput) - .def("setOslTestShadeExecutable", &mx::OslRenderer::setOslTestShadeExecutable) - .def("setOslTestRenderExecutable", &mx::OslRenderer::setOslTestRenderExecutable) - .def("setOslTestRenderSceneTemplateFile", &mx::OslRenderer::setOslTestRenderSceneTemplateFile) - .def("setOslShaderName", &mx::OslRenderer::setOslShaderName) - .def("setOslUtilityOSOPath", &mx::OslRenderer::setOslUtilityOSOPath) - .def("useTestRender", &mx::OslRenderer::useTestRender) - .def("compileOSL", &mx::OslRenderer::compileOSL) + + .def_static("create", &mx::OslRenderer::create, + py::arg("width") = 512, + py::arg("height") = 512, + py::arg_v("baseType", + mx::Image::BaseType::UINT8, + "BaseType.UINT8"), + PYMATERIALX_DOCSTRING(R"docstring( + Create an OSL renderer instance for rendering an image of the specified + resolution. +)docstring")) + + .def_readwrite_static("OSL_CLOSURE_COLOR_STRING", + &mx::OslRenderer::OSL_CLOSURE_COLOR_STRING, + PYMATERIALX_DOCSTRING(R"docstring( + Color closure OSL string. +)docstring")) + + .def("initialize", &mx::OslRenderer::initialize, + py::arg("renderContextHandle") = nullptr, + PYMATERIALX_DOCSTRING(R"docstring( + Initialize the renderer. + + Takes care of the internal initialization required for program validation + and rendering. + + :param renderContextHandle: Not currently used by the OSL renderer. + :type renderContextHandle: RenderContextHandle + :raises Exception: In case of initialization errors, listing them. +)docstring")) + + .def("createProgram", + static_cast(&mx::OslRenderer::createProgram), + py::arg("shader"), + PYMATERIALX_DOCSTRING(R"docstring( + Create OSL program based on an input shader. + + A valid executable and include path must be specified before calling this + method. + + :see: `setOslCompilerExecutable()` + :see: `setOslIncludePath()` + + Additionally, `setOslOutputFilePath()` should be set to allow for output of + `.osl` and `.oso` files to the appropriate path location to be used as + input for render validation. + + If render validation is not required, then the same temporary name will be + used for all shaders validated using this method. + + :param shader: Input shader. + :type shader: Shader +)docstring")) + + .def("createProgram", + static_cast(&mx::OslRenderer::createProgram), + py::arg("stages"), + PYMATERIALX_DOCSTRING(R"docstring( + Create OSL program based on shader stage source code. + + :param stages: Map of name and source code for the shader stages. + :type stages: Dict[str, str] +)docstring")) + + .def("validateInputs", &mx::OslRenderer::validateInputs, + PYMATERIALX_DOCSTRING(R"docstring( + Validate inputs for the program. +)docstring")) + + .def("render", &mx::OslRenderer::render, + PYMATERIALX_DOCSTRING(R"docstring( + Render OSL program to disk. + This is done by using either `testshade` or `testrender`. + Currently only `testshade` is supported. + + Usage of both executables requires compiled source (`.oso`) files as input. + A shader output must be set before running this test via the + `setOslOutputName()` method to ensure that the appropriate `.oso` files can + be located. +)docstring")) + + .def("captureImage", &mx::OslRenderer::captureImage, + py::arg("image") = nullptr, + PYMATERIALX_DOCSTRING(R"docstring( + Capture the current rendered output as an image. +)docstring")) + + .def("setOslCompilerExecutable", &mx::OslRenderer::setOslCompilerExecutable, + py::arg("executableFilePath"), + PYMATERIALX_DOCSTRING(R"docstring( + Set the path to the OSL executable. + + Note that it is assumed that this references the location of the `oslc` + executable. + + :param executableFilePath: Path to OSL compiler executable. + :type executableFilePath: FilePath +)docstring")) + + .def("setOslIncludePath", &mx::OslRenderer::setOslIncludePath, + py::arg("dirPath"), + PYMATERIALX_DOCSTRING(R"docstring( + Set the search locations for OSL include files. + + :param dirPath: Include path(s) for the OSL compiler. This should include + the path to `stdosl.h`. + :type dirPath: FileSearchPath +)docstring")) + + .def("setOslOutputFilePath", &mx::OslRenderer::setOslOutputFilePath, + py::arg("dirPath"), + PYMATERIALX_DOCSTRING(R"docstring( + Set the location where compiled OSL files will reside. + + :param dirPath: Path to output location. + :type dirPath: FilePath +)docstring")) + + .def("setShaderParameterOverrides", &mx::OslRenderer::setShaderParameterOverrides, + py::arg("parameterOverrides"), + PYMATERIALX_DOCSTRING(R"docstring( + Set shader parameter strings to be added to the scene XML file. + These strings will set parameter overrides for the shader. +)docstring")) + + .def("setOslShaderOutput", &mx::OslRenderer::setOslShaderOutput, + py::arg("outputName"), + py::arg("outputType"), + PYMATERIALX_DOCSTRING(R"docstring( + Set the OSL shader output. + + This is used during render validation if `testshade` or `testrender` is + executed. + + For `testrender` this value is used to replace the `%shader_output%` token + in the input scene file. + + :param outputName: Name of shader output. + :type outputName: str + :param outputType: The MaterialX type of the output. +)docstring")) + + .def("setOslTestShadeExecutable", &mx::OslRenderer::setOslTestShadeExecutable, + py::arg("executableFilePath"), + PYMATERIALX_DOCSTRING(R"docstring( + Set the path to the OSL shading tester. + + Note that it is assumed that this references the location of the `testshade` + executable. + + :param executableFilePath: Path to OSL `testshade` executable. + :type executableFilePath: FilePath +)docstring")) + + .def("setOslTestRenderExecutable", &mx::OslRenderer::setOslTestRenderExecutable, + py::arg("executableFilePath"), + PYMATERIALX_DOCSTRING(R"docstring( + Set the path to the OSL rendering tester. + + Note that it is assumed that this references the location of the `testrender` + executable. + + :param executableFilePath: Path to OSL `testrender` executable. + :type executableFilePath: FilePath +)docstring")) + + .def("setOslTestRenderSceneTemplateFile", &mx::OslRenderer::setOslTestRenderSceneTemplateFile, + py::arg("templateFilePath"), + PYMATERIALX_DOCSTRING(R"docstring( + Set the XML scene file to use for `testrender`. + + This is a template file with the following tokens for replacement: + - `%shader%` -- replaced with the name of the shader to use + - `%shader_output%` -- replaced with the name of the shader output to use + + :param templateFilePath: Scene file name. + :type templateFilePath: FilePath +)docstring")) + + .def("setOslShaderName", &mx::OslRenderer::setOslShaderName, + py::arg("shaderName"), + PYMATERIALX_DOCSTRING(R"docstring( + Set the name of the shader to be used for the input XML scene file. + + The value is used to replace the `%shader%` token in the file. + + :param shaderName: Name of shader. + :type shaderName: str +)docstring")) + + .def("setOslUtilityOSOPath", &mx::OslRenderer::setOslUtilityOSOPath, + py::arg("dirPath"), + PYMATERIALX_DOCSTRING(R"docstring( + Set the search path for dependent shaders (`.oso` files) which are used + when rendering with `testrender`. + + :param dirPath: Path to location containing `.oso` files. + :type dirPath: FilePath +)docstring")) + + .def("useTestRender", &mx::OslRenderer::useTestRender, + py::arg("useTestRender"), + PYMATERIALX_DOCSTRING(R"docstring( + Used to toggle to either use `testrender` or `testshade` during render + validation. + + By default `testshade` is used. + + :param useTestRender: Indicate whether to use `testrender`. +)docstring")) + + .def("compileOSL", &mx::OslRenderer::compileOSL, + py::arg("oslFilePath"), + PYMATERIALX_DOCSTRING(R"docstring( + Compile OSL code stored in a file. + + :param oslFilePath: OSL file path. + :type oslFilePath: FilePath + :raises Exception: If an error occurs. +)docstring")) + .doc() = R"docstring( Helper class for rendering generated OSL code to produce images.