From fe111f1b1d2c6d99d6fa93cb5631ac76a942836f Mon Sep 17 00:00:00 2001 From: Stefan Habel <19556655+StefanHabel@users.noreply.github.com> Date: Sun, 13 Oct 2024 16:27:13 -0700 Subject: [PATCH] Docstrings for PyMaterialXRender classes. Similar to https://github.com/AcademySoftwareFoundation/MaterialX/pull/2051, https://github.com/AcademySoftwareFoundation/MaterialX/pull/2061, https://github.com/AcademySoftwareFoundation/MaterialX/pull/2063, and https://github.com/AcademySoftwareFoundation/MaterialX/pull/2064. Split from #1567. Update #342. Signed-off-by: Stefan Habel <19556655+StefanHabel@users.noreply.github.com> --- .../PyMaterialXRender/PyCamera.cpp | 5 ++++ .../PyMaterialXRender/PyCgltfLoader.cpp | 4 ++++ .../PyMaterialXRender/PyGeometryHandler.cpp | 12 ++++++++++ .../PyMaterialX/PyMaterialXRender/PyImage.cpp | 24 ++++++++++++------- .../PyMaterialXRender/PyImageHandler.cpp | 18 ++++++++++++++ .../PyMaterialXRender/PyLightHandler.cpp | 4 ++++ .../PyMaterialX/PyMaterialXRender/PyMesh.cpp | 14 +++++++++++ .../PyMaterialXRender/PyOiioImageLoader.cpp | 2 ++ .../PyMaterialXRender/PyShaderRenderer.cpp | 4 ++++ .../PyMaterialXRender/PyStbImageLoader.cpp | 4 ++++ .../PyMaterialXRender/PyTinyObjLoader.cpp | 4 ++++ 11 files changed, 87 insertions(+), 8 deletions(-) diff --git a/source/PyMaterialX/PyMaterialXRender/PyCamera.cpp b/source/PyMaterialX/PyMaterialXRender/PyCamera.cpp index 9c19ceb831..ec8e63fd85 100644 --- a/source/PyMaterialX/PyMaterialXRender/PyCamera.cpp +++ b/source/PyMaterialX/PyMaterialXRender/PyCamera.cpp @@ -31,4 +31,9 @@ void bindPyCamera(py::module& mod) .def_static("createPerspectiveMatrix", &mx::Camera::createPerspectiveMatrix) .def_static("createOrthographicMatrix", &mx::Camera::createOrthographicMatrix) .def_static("transformPointPerspective", &mx::Camera::transformPointPerspective); + mod.attr("Camera").doc() = R"docstring( + A simple camera class, supporting transform matrices and arcball + functionality for object-viewing applications. + + :see: https://materialx.org/docs/api/class_camera.html)docstring"; } diff --git a/source/PyMaterialX/PyMaterialXRender/PyCgltfLoader.cpp b/source/PyMaterialX/PyMaterialXRender/PyCgltfLoader.cpp index 158e6b4849..f6be91ac2b 100644 --- a/source/PyMaterialX/PyMaterialXRender/PyCgltfLoader.cpp +++ b/source/PyMaterialX/PyMaterialXRender/PyCgltfLoader.cpp @@ -15,4 +15,8 @@ void bindPyCgltfLoader(py::module& mod) .def_static("create", &mx::CgltfLoader::create) .def(py::init<>()) .def("load", &mx::CgltfLoader::load); + mod.attr("CgltfLoader").doc() = R"docstring( + Wrapper for loader to read in GLTF files using the Cgltf library. + + :see: https://materialx.org/docs/api/class_cgltf_loader.html)docstring"; } diff --git a/source/PyMaterialX/PyMaterialXRender/PyGeometryHandler.cpp b/source/PyMaterialX/PyMaterialXRender/PyGeometryHandler.cpp index 08560254bc..09318ef5fb 100644 --- a/source/PyMaterialX/PyMaterialXRender/PyGeometryHandler.cpp +++ b/source/PyMaterialX/PyMaterialXRender/PyGeometryHandler.cpp @@ -37,6 +37,12 @@ void bindPyGeometryHandler(py::module& mod) .def(py::init<>()) .def("supportedExtensions", &mx::GeometryLoader::supportedExtensions) .def("load", &mx::GeometryLoader::load); + mod.attr("GeometryLoader").doc() = R"docstring( + Base class representing a geometry loader. + + A loader can be associated with one or more file extensions. + + :see: https://materialx.org/docs/api/class_geometry_loader.html)docstring"; py::class_(mod, "GeometryHandler") .def(py::init<>()) @@ -50,4 +56,10 @@ void bindPyGeometryHandler(py::module& mod) .def("findParentMesh", &mx::GeometryHandler::findParentMesh) .def("getMinimumBounds", &mx::GeometryHandler::getMinimumBounds) .def("getMaximumBounds", &mx::GeometryHandler::getMaximumBounds); + mod.attr("GeometryHandler").doc() = R"docstring( + Class which holds a set of geometry loaders. + + Each loader is associated with a given set of file extensions. + + :see: https://materialx.org/docs/api/class_geometry_handler.html)docstring"; } diff --git a/source/PyMaterialX/PyMaterialXRender/PyImage.cpp b/source/PyMaterialX/PyMaterialXRender/PyImage.cpp index c1d2a74db0..a13468c859 100644 --- a/source/PyMaterialX/PyMaterialXRender/PyImage.cpp +++ b/source/PyMaterialX/PyMaterialXRender/PyImage.cpp @@ -12,14 +12,18 @@ namespace mx = MaterialX; void bindPyImage(py::module& mod) { - py::enum_(mod, "BaseType") - .value("UINT8", mx::Image::BaseType::UINT8) - .value("UINT16", mx::Image::BaseType::UINT16) - .value("HALF", mx::Image::BaseType::HALF) - .value("FLOAT", mx::Image::BaseType::FLOAT) + py::enum_(mod, "BaseType", + "Enumeration of `Image` base types.\n\n" + ":see: https://materialx.org/docs/api/class_image.html#pub-types") + .value("UINT8", mx::Image::BaseType::UINT8, "8-bit unsigned integer number.") + .value("UINT16", mx::Image::BaseType::UINT16, "16-bit unsigned integer number.") + .value("HALF", mx::Image::BaseType::HALF, "Half-precision floating-point number.") + .value("FLOAT", mx::Image::BaseType::FLOAT, "Full-precision floating-point number.") .export_values(); py::class_(mod, "ImageBufferDeallocator"); + mod.attr("ImageBufferDeallocator").doc() = R"docstring( + A function to perform image buffer deallocation.)docstring"; py::class_(mod, "Image") .def_static("create", &mx::Image::create) @@ -45,8 +49,12 @@ void bindPyImage(py::module& mod) .def("releaseResourceBuffer", &mx::Image::releaseResourceBuffer) .def("setResourceBufferDeallocator", &mx::Image::setResourceBufferDeallocator) .def("getResourceBufferDeallocator", &mx::Image::getResourceBufferDeallocator); + mod.attr("Image").doc() = R"docstring( + Class representing an image in system memory. - mod.def("createUniformImage", &mx::createUniformImage); - mod.def("createImageStrip", &mx::createImageStrip); - mod.def("getMaxDimensions", &mx::getMaxDimensions); + :see: https://materialx.org/docs/api/class_image.html)docstring"; + + mod.def("createUniformImage", &mx::createUniformImage); + mod.def("createImageStrip", &mx::createImageStrip); + mod.def("getMaxDimensions", &mx::getMaxDimensions); } diff --git a/source/PyMaterialX/PyMaterialXRender/PyImageHandler.cpp b/source/PyMaterialX/PyMaterialXRender/PyImageHandler.cpp index d261bc7306..ef36750dd8 100644 --- a/source/PyMaterialX/PyMaterialXRender/PyImageHandler.cpp +++ b/source/PyMaterialX/PyMaterialXRender/PyImageHandler.cpp @@ -17,6 +17,10 @@ void bindPyImageHandler(py::module& mod) .def_readwrite("vaddressMode", &mx::ImageSamplingProperties::vaddressMode) .def_readwrite("filterType", &mx::ImageSamplingProperties::filterType) .def_readwrite("defaultColor", &mx::ImageSamplingProperties::defaultColor); + mod.attr("ImageSamplingProperties").doc() = R"docstring( + Interface to describe sampling properties for images. + + :see: https://materialx.org/docs/api/class_image_sampling_properties.html)docstring"; py::class_(mod, "ImageLoader") .def_readonly_static("BMP_EXTENSION", &mx::ImageLoader::BMP_EXTENSION) @@ -35,6 +39,10 @@ void bindPyImageHandler(py::module& mod) .def("supportedExtensions", &mx::ImageLoader::supportedExtensions) .def("saveImage", &mx::ImageLoader::saveImage) .def("loadImage", &mx::ImageLoader::loadImage); + mod.attr("ImageLoader").doc() = R"docstring( + Abstract base class for file-system image loaders. + + :see: https://materialx.org/docs/api/class_image_loader.html)docstring"; py::class_(mod, "ImageHandler") .def_static("create", &mx::ImageHandler::create) @@ -56,4 +64,14 @@ void bindPyImageHandler(py::module& mod) .def("clearImageCache", &mx::ImageHandler::clearImageCache) .def("getZeroImage", &mx::ImageHandler::getZeroImage) .def("getReferencedImages", &mx::ImageHandler::getReferencedImages); + mod.attr("ImageHandler").doc() = R"docstring( + Base image handler class. + + Keeps track of images which are loaded from disk via supplied `ImageLoader`. + + Derived classes are responsible for determinining how to perform the logic + for "binding" of these resources for a given target (such as a given + shading language). + + :see: https://materialx.org/docs/api/class_image_handler.html)docstring"; } diff --git a/source/PyMaterialX/PyMaterialXRender/PyLightHandler.cpp b/source/PyMaterialX/PyMaterialXRender/PyLightHandler.cpp index 50725a7768..9eb08fecc0 100644 --- a/source/PyMaterialX/PyMaterialXRender/PyLightHandler.cpp +++ b/source/PyMaterialX/PyMaterialXRender/PyLightHandler.cpp @@ -41,4 +41,8 @@ void bindPyLightHandler(py::module& mod) .def("computeLightIdMap", &mx::LightHandler::computeLightIdMap) .def("findLights", &mx::LightHandler::findLights) .def("registerLights", &mx::LightHandler::registerLights); + mod.attr("LightHandler").doc() = R"docstring( + Utility light handler for creating and providing light data for shader binding. + + :see: https://materialx.org/docs/api/class_light_handler.html)docstring"; } diff --git a/source/PyMaterialX/PyMaterialXRender/PyMesh.cpp b/source/PyMaterialX/PyMaterialXRender/PyMesh.cpp index 5c26821436..e0cfe33b4c 100644 --- a/source/PyMaterialX/PyMaterialXRender/PyMesh.cpp +++ b/source/PyMaterialX/PyMaterialXRender/PyMesh.cpp @@ -32,6 +32,10 @@ void bindPyMesh(py::module& mod) .def("setStride", &mx::MeshStream::setStride) .def("getSize", &mx::MeshStream::getSize) .def("transform", &mx::MeshStream::transform); + mod.attr("MeshStream").doc() = R"docstring( + Class to represent a mesh data stream. + + :see: https://materialx.org/docs/api/class_mesh_stream.html)docstring"; py::class_(mod, "MeshPartition") .def_static("create", &mx::MeshPartition::create) @@ -44,6 +48,12 @@ void bindPyMesh(py::module& mod) .def("getIndices", static_cast(&mx::MeshPartition::getIndices), py::return_value_policy::reference) .def("getFaceCount", &mx::MeshPartition::getFaceCount) .def("setFaceCount", &mx::MeshPartition::setFaceCount); + mod.attr("MeshPartition").doc() = R"docstring( + Class that describes a sub-region of a mesh using vertex indexing. + + Note that a face is considered to be a triangle. + + :see: https://materialx.org/docs/api/class_mesh_partition.html)docstring"; py::class_(mod, "Mesh") .def_static("create", &mx::Mesh::create) @@ -74,4 +84,8 @@ void bindPyMesh(py::module& mod) .def("generateBitangents", &mx::Mesh::generateBitangents) .def("mergePartitions", &mx::Mesh::mergePartitions) .def("splitByUdims", &mx::Mesh::splitByUdims); + mod.attr("Mesh").doc() = R"docstring( + Container for mesh data. + + :see: https://materialx.org/docs/api/class_mesh.html)docstring"; } diff --git a/source/PyMaterialX/PyMaterialXRender/PyOiioImageLoader.cpp b/source/PyMaterialX/PyMaterialXRender/PyOiioImageLoader.cpp index 387af2714d..0449b03d68 100644 --- a/source/PyMaterialX/PyMaterialXRender/PyOiioImageLoader.cpp +++ b/source/PyMaterialX/PyMaterialXRender/PyOiioImageLoader.cpp @@ -17,4 +17,6 @@ void bindPyOiioImageLoader(py::module& mod) .def(py::init<>()) .def("saveImage", &mx::OiioImageLoader::saveImage) .def("loadImage", &mx::OiioImageLoader::loadImage); + mod.attr("OiioImageLoader").doc() = R"docstring( + OpenImageIO image file loader.)docstring"; } diff --git a/source/PyMaterialX/PyMaterialXRender/PyShaderRenderer.cpp b/source/PyMaterialX/PyMaterialXRender/PyShaderRenderer.cpp index 94c0d49cee..96b120eb87 100644 --- a/source/PyMaterialX/PyMaterialXRender/PyShaderRenderer.cpp +++ b/source/PyMaterialX/PyMaterialXRender/PyShaderRenderer.cpp @@ -28,6 +28,10 @@ void bindPyShaderRenderer(py::module& mod) .def("updateUniform", &mx::ShaderRenderer::updateUniform) .def("setSize", &mx::ShaderRenderer::setSize) .def("render", &mx::ShaderRenderer::render); + mod.attr("ShaderRenderer").doc() = R"docstring( + Base class for renderers that generate shader code to produce images. + + :see: https://materialx.org/docs/api/class_shader_renderer.html)docstring"; static py::exception pyExceptionRenderError(mod, "ExceptionRenderError"); diff --git a/source/PyMaterialX/PyMaterialXRender/PyStbImageLoader.cpp b/source/PyMaterialX/PyMaterialXRender/PyStbImageLoader.cpp index 4c710746c1..73c55531c9 100644 --- a/source/PyMaterialX/PyMaterialXRender/PyStbImageLoader.cpp +++ b/source/PyMaterialX/PyMaterialXRender/PyStbImageLoader.cpp @@ -16,4 +16,8 @@ void bindPyStbImageLoader(py::module& mod) .def_static("create", &mx::StbImageLoader::create) .def("saveImage", &mx::StbImageLoader::saveImage) .def("loadImage", &mx::StbImageLoader::loadImage); + mod.attr("StbImageLoader").doc() = R"docstring( + Stb image file loader. + + :see: https://materialx.org/docs/api/class_stb_image_loader.html)docstring"; } diff --git a/source/PyMaterialX/PyMaterialXRender/PyTinyObjLoader.cpp b/source/PyMaterialX/PyMaterialXRender/PyTinyObjLoader.cpp index 13677453b9..0455a62c48 100644 --- a/source/PyMaterialX/PyMaterialXRender/PyTinyObjLoader.cpp +++ b/source/PyMaterialX/PyMaterialXRender/PyTinyObjLoader.cpp @@ -16,4 +16,8 @@ void bindPyTinyObjLoader(py::module& mod) .def_static("create", &mx::TinyObjLoader::create) .def(py::init<>()) .def("load", &mx::TinyObjLoader::load); + mod.attr("TinyObjLoader").doc() = R"docstring( + Wrapper for geometry loader to read in OBJ files using the TinyObj library. + + :see: https://materialx.org/docs/api/class_tiny_obj_loader.html)docstring"; }