# academysoftwarefoundation/materialx architecture

> Architecture diagram of the GitHub repository academysoftwarefoundation/materialx, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/academysoftwarefoundation/materialx
- Repository: https://github.com/academysoftwarefoundation/materialx

## Overview

##### 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

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "External / Platform"
        direction TB
        ext1["CMake Build System"]:::gray
        pugi["PugiXML"]:::gray
        pybindDep["PyBind11"]:::gray
        glfwDep["GLFW"]:::gray
        imguiDep["ImGui"]:::gray
        stb["stb_image"]:::gray
        tiny["tinyobjloader"]:::gray
        cgltf["Cgltf"]:::gray
    end

    subgraph "Core Libraries"
        direction TB
        core["MaterialXCore"]:::blue
        format["MaterialXFormat"]:::blue
    end

    subgraph "Shader Generation"
        direction TB
        genCore["MaterialXGenShader"]:::green
        glsl["MaterialXGenGlsl"]:::green
        osl["MaterialXGenOsl"]:::green
        mdl["MaterialXGenMdl"]:::green
        msl["MaterialXGenMsl"]:::green
    end

    subgraph "Rendering / Visualization"
        direction TB
        renderCore["MaterialXRender"]:::orange
        rglsl["MaterialXRenderGlsl"]:::orange
        rmsl["MaterialXRenderMsl"]:::orange
        rosl["MaterialXRenderOsl"]:::orange
        rhw["MaterialXRenderHw"]:::orange
    end

    subgraph "Bindings & Scripts"
        direction TB
        pybindLib["PyMaterialX"]:::purple
        pyScripts["Python CLI Scripts"]:::purple
        jsBind["JsMaterialX"]:::purple
        jsTests["JS Examples & Tests"]:::purple
    end

    subgraph "Applications & Tools"
        direction TB
        viewer(("Viewer (NanoGUI)")):::app
        editor(("Graph Editor")):::app
        cppTest(("C++ Test Suites")):::app
        jsTest(("JS Test Harness")):::app
    end

    mtlx(("MaterialX File (.mtlx)")):::data

    %% Data flow
    mtlx -->|parsed by| format
    format -->|builds graph| core
    core -->|graph into| genCore
    format -->|format IO| genCore
    genCore -->|uses| glsl
    genCore -->|uses| osl
    genCore -->|uses| mdl
    genCore -->|uses| msl

    glsl -->|shader code| rglsl
    osl -->|shader code| rosl
    msl -->|shader code| rmsl

    %% Application links
    viewer -->|links to| core
    viewer -->|links to| format
    viewer -->|uses| glsl
    viewer -->|uses| rglsl
    viewer -->|uses| ext1

    editor -->|links to| core
    editor -->|links to| format
    editor -->|uses| genCore
    editor -->|uses| imguiDep
    editor -->|uses| glfwDep

    cppTest -->|tests| core
    cppTest -->|tests| format
    cppTest -->|tests| genCore
    cppTest -->|tests| renderCore

    jsTest -->|tests| jsBind

    %% Bindings usage
    pyScripts -->|calls| pybindLib
    pybindLib -->|wraps| core
    pybindLib -->|wraps| format
    pybindLib -->|wraps| genCore
    pybindLib -->|wraps| renderCore

    jsTests -->|calls| jsBind
    jsBind -->|wraps| core
    jsBind -->|wraps| format
    jsBind -->|wraps| genCore

    %% External dependencies usage
    format -->|uses| pugi
    pybindLib -->|uses| pybindDep
    editor -->|uses| glfwDep
    editor -->|uses| imguiDep
    renderCore -->|uses| stb
    renderCore -->|uses| tiny
    renderCore -->|uses| cgltf

    %% Click Events
    click pugi "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXFormat/External/PugiXML"
    click pybindDep "https://github.com/academysoftwarefoundation/materialx/tree/main/source/PyMaterialX/External/PyBind11"
    click glfwDep "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXGraphEditor/External/Glfw"
    click imguiDep "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXGraphEditor/External/ImGui"
    click stb "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXRender/External/StbImage"
    click tiny "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXRender/External/TinyObjLoader"
    click cgltf "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXRender/External/Cgltf"
    click core "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXCore"
    click format "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXFormat"
    click genCore "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXGenShader"
    click glsl "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXGenGlsl"
    click osl "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXGenOsl"
    click mdl "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXGenMdl"
    click msl "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXGenMsl"
    click renderCore "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXRender"
    click rglsl "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXRenderGlsl"
    click rmsl "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXRenderMsl"
    click rosl "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXRenderOsl"
    click rhw "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXRenderHw"
    click pybindLib "https://github.com/academysoftwarefoundation/materialx/tree/main/source/PyMaterialX"
    click pyScripts "https://github.com/academysoftwarefoundation/materialx/tree/main/python/Scripts"
    click jsBind "https://github.com/academysoftwarefoundation/materialx/tree/main/source/JsMaterialX"
    click jsTests "https://github.com/academysoftwarefoundation/materialx/tree/main/javascript/MaterialXTest"
    click viewer "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXView"
    click editor "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXGraphEditor"
    click cppTest "https://github.com/academysoftwarefoundation/materialx/tree/main/source/MaterialXTest"
    click jsTest "https://github.com/academysoftwarefoundation/materialx/tree/main/javascript/MaterialXTest"

    %% Styles
    classDef blue fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef green fill:#90EE90,stroke:#000,stroke-width:1px
    classDef orange fill:#FFA500,stroke:#000,stroke-width:1px
    classDef purple fill:#DDA0DD,stroke:#000,stroke-width:1px
    classDef gray fill:#D3D3D3,stroke:#000,stroke-width:1px
    classDef app fill:#E0FFFF,stroke:#000,stroke-width:1px,stroke-dasharray: 5 5
    classDef data fill:#FFFACD,stroke:#000,stroke-width:1px,stroke-dasharray: 2 2
    class mtlx data
```
