Skip to content

Commit

Permalink
Sphinx Python Documentation (#1567) - Added docstrings to PyMaterialX…
Browse files Browse the repository at this point in the history
…Render.
  • Loading branch information
StefanHabel committed Oct 18, 2023
1 parent 8790578 commit 0439c07
Show file tree
Hide file tree
Showing 12 changed files with 236 additions and 19 deletions.
8 changes: 7 additions & 1 deletion source/PyMaterialX/PyMaterialXRender/PyCamera.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -30,5 +30,11 @@ void bindPyCamera(py::module& mod)
.def_static("createViewMatrix", &mx::Camera::createViewMatrix)
.def_static("createPerspectiveMatrix", &mx::Camera::createPerspectiveMatrix)
.def_static("createOrthographicMatrix", &mx::Camera::createOrthographicMatrix)
.def_static("transformPointPerspective", &mx::Camera::transformPointPerspective);
.def_static("transformPointPerspective", &mx::Camera::transformPointPerspective)
.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";
}
17 changes: 16 additions & 1 deletion source/PyMaterialX/PyMaterialXRender/PyCgltfLoader.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -14,5 +14,20 @@ void bindPyCgltfLoader(py::module& mod)
py::class_<mx::CgltfLoader, mx::CgltfLoaderPtr, mx::GeometryLoader>(mod, "CgltfLoader")
.def_static("create", &mx::CgltfLoader::create)
.def(py::init<>())
.def("load", &mx::CgltfLoader::load);
.def("load", &mx::CgltfLoader::load)
.doc() = R"docstring(
Wrapper class for a geometry loader to read glTF files using the cgltf
library.
Supports the following file extensions:
* `.glb`
* `.GLB`
* `.gltf`
* `.GLTF`
:see: https://materialx.org/docs/api/class_cgltf_loader.html
:see: https://github.com/jkuhlmann/cgltf
:see: https://www.khronos.org/gltf/
)docstring";
}
18 changes: 16 additions & 2 deletions source/PyMaterialX/PyMaterialXRender/PyGeometryHandler.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -36,7 +36,14 @@ void bindPyGeometryHandler(py::module& mod)
py::class_<mx::GeometryLoader, PyGeometryLoader, mx::GeometryLoaderPtr>(mod, "GeometryLoader")
.def(py::init<>())
.def("supportedExtensions", &mx::GeometryLoader::supportedExtensions)
.def("load", &mx::GeometryLoader::load);
.def("load", &mx::GeometryLoader::load)
.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<>())
Expand All @@ -49,5 +56,12 @@ void bindPyGeometryHandler(py::module& mod)
.def("getMeshes", &mx::GeometryHandler::getMeshes)
.def("findParentMesh", &mx::GeometryHandler::findParentMesh)
.def("getMinimumBounds", &mx::GeometryHandler::getMinimumBounds)
.def("getMaximumBounds", &mx::GeometryHandler::getMaximumBounds);
.def("getMaximumBounds", &mx::GeometryHandler::getMaximumBounds)
.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";
}
18 changes: 15 additions & 3 deletions source/PyMaterialX/PyMaterialXRender/PyImage.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,21 @@ namespace mx = MaterialX;

void bindPyImage(py::module& mod)
{
py::enum_<mx::Image::BaseType>(mod, "BaseType")
py::enum_<mx::Image::BaseType>(mod, "BaseType", R"docstring(
Enumeration of `Image` base types.
:see: https://materialx.org/docs/api/class_image.html#pub-types
)docstring")
.value("UINT8", mx::Image::BaseType::UINT8)
.value("UINT16", mx::Image::BaseType::UINT16)
.value("HALF", mx::Image::BaseType::HALF)
.value("FLOAT", mx::Image::BaseType::FLOAT)
.export_values();

py::class_<mx::ImageBufferDeallocator>(mod, "ImageBufferDeallocator");
py::class_<mx::ImageBufferDeallocator>(mod, "ImageBufferDeallocator")
.doc() = R"docstring(
Class representing a function to perform image buffer deallocation.
)docstring";

py::class_<mx::Image, mx::ImagePtr>(mod, "Image")
.def_static("create", &mx::Image::create)
Expand All @@ -44,7 +51,12 @@ void bindPyImage(py::module& mod)
.def("createResourceBuffer", &mx::Image::createResourceBuffer)
.def("releaseResourceBuffer", &mx::Image::releaseResourceBuffer)
.def("setResourceBufferDeallocator", &mx::Image::setResourceBufferDeallocator)
.def("getResourceBufferDeallocator", &mx::Image::getResourceBufferDeallocator);
.def("getResourceBufferDeallocator", &mx::Image::getResourceBufferDeallocator)
.doc() = R"docstring(
Class representing an image in system memory.
:see: https://materialx.org/docs/api/class_image.html
)docstring";

mod.def("createUniformImage", &mx::createUniformImage);
mod.def("createImageStrip", &mx::createImageStrip);
Expand Down
24 changes: 21 additions & 3 deletions source/PyMaterialX/PyMaterialXRender/PyImageHandler.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -16,7 +16,12 @@ void bindPyImageHandler(py::module& mod)
.def_readwrite("uaddressMode", &mx::ImageSamplingProperties::uaddressMode)
.def_readwrite("vaddressMode", &mx::ImageSamplingProperties::vaddressMode)
.def_readwrite("filterType", &mx::ImageSamplingProperties::filterType)
.def_readwrite("defaultColor", &mx::ImageSamplingProperties::defaultColor);
.def_readwrite("defaultColor", &mx::ImageSamplingProperties::defaultColor)
.doc() = R"docstring(
Class representing an 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)
Expand All @@ -34,7 +39,12 @@ void bindPyImageHandler(py::module& mod)
.def_readonly_static("TXT_EXTENSION", &mx::ImageLoader::TXT_EXTENSION)
.def("supportedExtensions", &mx::ImageLoader::supportedExtensions)
.def("saveImage", &mx::ImageLoader::saveImage)
.def("loadImage", &mx::ImageLoader::loadImage);
.def("loadImage", &mx::ImageLoader::loadImage)
.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)
Expand All @@ -55,5 +65,13 @@ void bindPyImageHandler(py::module& mod)
py::arg("image") = nullptr)
.def("clearImageCache", &mx::ImageHandler::clearImageCache)
.def("getZeroImage", &mx::ImageHandler::getZeroImage)
.def("getReferencedImages", &mx::ImageHandler::getReferencedImages);
.def("getReferencedImages", &mx::ImageHandler::getReferencedImages)
.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";
}
8 changes: 7 additions & 1 deletion source/PyMaterialX/PyMaterialXRender/PyLightHandler.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -40,5 +40,11 @@ void bindPyLightHandler(py::module& mod)
.def("getLightIdMap", &mx::LightHandler::getLightIdMap)
.def("computeLightIdMap", &mx::LightHandler::computeLightIdMap)
.def("findLights", &mx::LightHandler::findLights)
.def("registerLights", &mx::LightHandler::registerLights);
.def("registerLights", &mx::LightHandler::registerLights)
.doc() = R"docstring(
Class representing a utility light handler for creating and providing
light data for shader binding.
:see: https://materialx.org/docs/api/class_light_handler.html
)docstring";
}
23 changes: 20 additions & 3 deletions source/PyMaterialX/PyMaterialXRender/PyMesh.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -31,7 +31,12 @@ void bindPyMesh(py::module& mod)
.def("getStride", &mx::MeshStream::getStride)
.def("setStride", &mx::MeshStream::setStride)
.def("getSize", &mx::MeshStream::getSize)
.def("transform", &mx::MeshStream::transform);
.def("transform", &mx::MeshStream::transform)
.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)
Expand All @@ -43,7 +48,14 @@ void bindPyMesh(py::module& mod)
.def("getSourceNames", &mx::MeshPartition::getSourceNames)
.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);
.def("setFaceCount", &mx::MeshPartition::setFaceCount)
.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)
Expand Down Expand Up @@ -73,5 +85,10 @@ void bindPyMesh(py::module& mod)
.def("generateTangents", &mx::Mesh::generateTangents)
.def("generateBitangents", &mx::Mesh::generateBitangents)
.def("mergePartitions", &mx::Mesh::mergePartitions)
.def("splitByUdims", &mx::Mesh::splitByUdims);
.def("splitByUdims", &mx::Mesh::splitByUdims)
.doc() = R"docstring(
Class representing a container for mesh data.
:see: https://materialx.org/docs/api/class_mesh.html
)docstring";
}
64 changes: 63 additions & 1 deletion source/PyMaterialX/PyMaterialXRender/PyModule.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,69 @@ void bindPyCgltfLoader(py::module& mod);

PYBIND11_MODULE(PyMaterialXRender, mod)
{
mod.doc() = "Core rendering functionality for MaterialX";
mod.doc() = R"docstring(
Core rendering support for MaterialX.
Core Rendering Classes
----------------------
.. autosummary::
:toctree: core-rendering
ShaderRenderer
Camera
LightHandler
Geometry Classes
----------------
.. autosummary::
:toctree: geometry
GeometryHandler
GeometryLoader
CgltfLoader
TinyObjLoader
Mesh
MeshPartition
MeshStream
Image Classes
--------------
.. autosummary::
:toctree: images
ImageHandler
ImageLoader
StbImageLoader
Image
ImageBufferDeallocator
ImageSamplingProperties
Image Functions
---------------
.. autofunction:: createImageStrip
.. autofunction:: createUniformImage
.. autofunction:: getMaxDimensions
Enumeration Classes
-------------------
.. autosummary::
:toctree: enumerations
BaseType
Exception Classes
-----------------
.. autosummary::
:toctree: exceptions
ExceptionRenderError
)docstring";

// PyMaterialXRender depends on types defined in PyMaterialXCore
pybind11::module::import("PyMaterialXCore");
Expand Down
26 changes: 25 additions & 1 deletion source/PyMaterialX/PyMaterialXRender/PyOiioImageLoader.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -16,5 +16,29 @@ void bindPyOiioImageLoader(py::module& mod)
.def_static("create", &mx::OiioImageLoader::create)
.def(py::init<>())
.def("saveImage", &mx::OiioImageLoader::saveImage)
.def("loadImage", &mx::OiioImageLoader::loadImage);
.def("loadImage", &mx::OiioImageLoader::loadImage)
.doc() = R"docstring(
Class implementing an OpenImageIO image file loader.
Supports the following file extensions:
* `.bmp`
* `.exr`
* `.gif`
* `.hdr`
* `.jpg`
* `.jpeg`
* `.pic`
* `.png`
* `.psd`
* `.tga`
* `.tif`
* `.tiff`
* `.tx`
* `.txt`
* `.txr`
:see: https://materialx.org/docs/api/class_oiio_image_loader.html
:see: https://github.com/AcademySoftwareFoundation/OpenImageIO
)docstring";
}
15 changes: 14 additions & 1 deletion source/PyMaterialX/PyMaterialXRender/PyShaderRenderer.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,22 @@ void bindPyShaderRenderer(py::module& mod)
.def("validateInputs", &mx::ShaderRenderer::validateInputs)
.def("updateUniform", &mx::ShaderRenderer::updateUniform)
.def("setSize", &mx::ShaderRenderer::setSize)
.def("render", &mx::ShaderRenderer::render);
.def("render", &mx::ShaderRenderer::render)
.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");
pyExceptionRenderError.doc() = R"docstring(
A type of exception that is raised when a rendering operation fails.
Optionally stores an additional error log, which can be used to
store and retrieve shader compilation errors.
:see: https://materialx.org/docs/api/class_exception_render_error.html
)docstring";

py::register_exception_translator(
[](std::exception_ptr errPtr)
Expand Down
20 changes: 19 additions & 1 deletion source/PyMaterialX/PyMaterialXRender/PyStbImageLoader.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -15,5 +15,23 @@ void bindPyStbImageLoader(py::module& mod)
py::class_<mx::StbImageLoader, mx::ImageLoader, mx::StbImageLoaderPtr>(mod, "StbImageLoader")
.def_static("create", &mx::StbImageLoader::create)
.def("saveImage", &mx::StbImageLoader::saveImage)
.def("loadImage", &mx::StbImageLoader::loadImage);
.def("loadImage", &mx::StbImageLoader::loadImage)
.doc() = R"docstring(
Class implementing an image loader using the stb image library.
Supports the following file extensions:
* `.bmp`
* `.gif`
* `.hdr`
* `.jpg`
* `.jpeg`
* `.pic`
* `.png`
* `.psd`
* `.tga`
:see: https://materialx.org/docs/api/class_stb_image_loader.html
:see: https://github.com/nothings/stb
)docstring";
}
14 changes: 13 additions & 1 deletion source/PyMaterialX/PyMaterialXRender/PyTinyObjLoader.cpp
Original file line number Diff line number Diff line change
Expand Up @@ -15,5 +15,17 @@ void bindPyTinyObjLoader(py::module& mod)
py::class_<mx::TinyObjLoader, mx::TinyObjLoaderPtr, mx::GeometryLoader>(mod, "TinyObjLoader")
.def_static("create", &mx::TinyObjLoader::create)
.def(py::init<>())
.def("load", &mx::TinyObjLoader::load);
.def("load", &mx::TinyObjLoader::load)
.doc() = R"docstring(
Wrapper class for a geometry loader to read OBJ files using the TinyObj
library.
Supports the following file extensions:
* `.obj`
* `.OBJ`
:see: https://materialx.org/docs/api/class_tiny_obj_loader.html
:see: https://github.com/tinyobjloader/tinyobjloader/
)docstring";
}

0 comments on commit 0439c07

Please sign in to comment.