How academysoftwarefoundation/materialx works
Project Type and Purpose
• MaterialX is an open-source C++ library and toolset for defining, exchanging, and rendering rich material descriptions in computer graphics.
• It provides:
• A Core API for material and look graphs (MaterialXCore & MaterialXFormat)
• Shader generators for multiple targets (GLSL, OSL, MDL, MSL, Vulkan, etc.)
• Bindings in Python (PyBind11) and JavaScript (Emscripten/Node)
• Example applications: Viewer (NanoGUI), Graph Editor (ImGui+GLFW)
• Standalone scripts (Python), tests (Catch for C++, Jest/Karma for JS)
High-Level Architectural Layers
• External/Platform Layer
– CMake build system, third-party libs (PugiXML, PyBind11, GLFW, ImGui, stb_image, tinyobjloader, etc.)
• Core Libraries
– MaterialXCore: in-memory graph representation (Definitions, Elements, Traversal, Units, Types)
– MaterialXFormat: file IO (XmlIo, File utilities)
• Shader Generation Modules
– MaterialXGenShader: shared generation framework (GenContext, GenOptions, HwShaderGenerator)
– Language-specific generators:
· MaterialXGenGlsl / JsMaterialXGenGlsl
· MaterialXGenOsl / JsMaterialXGenOsl
· MaterialXGenMdl / JsMaterialXGenMdl
· MaterialXGenMsl / JsMaterialXGenMsl
· MaterialXGenEssl, GenVk, GenOsl (others)
• Rendering/Visualization
– MaterialXRender: scene loader, camera, lights, meshes, texture handling (Oiio/stb)
– MaterialXRenderGlsl / Msl / Osl / Hw: backend-specific render pipelines
• Bindings & Scripts
– Python: PyMaterialX exposes Core, Format, GenShader, Render via PyBind11
– JavaScript: JsMaterialX exposes Core, Format, GenShader via Emscripten + package.json
– Python Scripts folder: CLI tools (generateshader, mxvalidate, mxdoc, etc.)
– JavaScript Tests: Karma, Jest running on Node/browser
• Applications & Tools
– Viewer: uses MaterialXGenGlsl → MaterialXRenderGlsl → NanoGUI window
– Graph Editor: uses Core, Format, GenShader to provide node-graph UI via ImGui+GLFW
– Test Executables: MaterialXTest C++ catch tests per module
Component Relationships & Data Flow
• A MaterialX file (.mtlx) → parsed by MaterialXFormat → MaterialXCore graph
• Core graph → passed into GenShader modules → outputs shader source code (GLSL/OSL/MDL/Metal)
• Shader code + geometry/textures → fed into MaterialXRender* → rendered into a window (Viewer/Editor)
• Python/JS scripts call into Core, Format, GenShader, and Render libraries
• Viewer/Editor apps link against Core, Format, GenShader, Render, plus platform libs
• CMake orchestrates building each target module, generating libraries and executables
Architectural Patterns & Design Principles
• Modular layering: separation of concerns (Core vs. Format vs. Gen vs. Render vs. Bindings)
• Plugin-style generators: GenShader core + pluggable language back-ends
• Adapter/Wrappers: PyBind11 & Emscripten layers wrap the same C++ API for scripting languages
• Test harness per module ensures isolation and coverage
Essential Details to Capture
• Every generation path (GLSL, OSL, MDL, Metal, Vulkan) as separate sub-components under GenShader
• Binding layers separate from C++ core to highlight language support
• Script utilities and test suites as side-paths invoking core functionality
• External libraries and platform/framework dependencies