Docstrings for PyMaterialXRender classes.

Similar to AcademySoftwareFoundation#2051, AcademySoftwareFoundation#2061, AcademySoftwareFoundation#2063, and AcademySoftwareFoundation#2064. Split from AcademySoftwareFoundation#1567. Update AcademySoftwareFoundation#342. Signed-off-by: Stefan Habel <[email protected]>
StefanHabel · Oct 13, 2024 · fe111f1 · fe111f1
1 parent 0ba2ad0
commit fe111f1
Show file tree

Hide file tree

Showing 11 changed files with 87 additions and 8 deletions.
diff --git 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
@@ -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
@@ -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_<mx::GeometryHandler, mx::GeometryHandlerPtr>(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
@@ -12,14 +12,18 @@ namespace mx = MaterialX;
 
 void bindPyImage(py::module& mod)
 {
-    py::enum_<mx::Image::BaseType>(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_<mx::Image::BaseType>(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_<mx::ImageBufferDeallocator>(mod, "ImageBufferDeallocator");
+    mod.attr("ImageBufferDeallocator").doc() = R"docstring(
+    A function to perform image buffer deallocation.)docstring";
 
     py::class_<mx::Image, mx::ImagePtr>(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
@@ -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_<mx::ImageLoader, mx::ImageLoaderPtr>(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_<mx::ImageHandler, mx::ImageHandlerPtr>(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
@@ -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
@@ -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_<mx::MeshPartition, mx::MeshPartitionPtr>(mod, "MeshPartition")
         .def_static("create", &mx::MeshPartition::create)
@@ -44,6 +48,12 @@ void bindPyMesh(py::module& mod)
         .def("getIndices", static_cast<mx::MeshIndexBuffer& (mx::MeshPartition::*)()>(&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_<mx::Mesh, mx::MeshPtr>(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
@@ -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
@@ -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<mx::ExceptionRenderError> pyExceptionRenderError(mod, "ExceptionRenderError");
 

diff --git 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
@@ -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";
 }