# autodesk/maya-hydra architecture

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

- Interactive diagram: https://gitdiagram.com/autodesk/maya-hydra
- Repository: https://github.com/autodesk/maya-hydra

## Overview

##### Main components
- Maya Host Application – This represents Maya’s environment where the plugin integrates.
- Maya Plugin & Extensions – Found in directories like “plugin/mayaHydraSceneBrowser”, “lib/mayaHydra”, and “lib/mayaHydra/hydraExtensions”. These components handle the integration with Maya’s viewport and data management.
- Hydra & USD Integration – The “lib/flowViewport” directory (with its subdirectories for API interfaces, scene indices, adapters, and samples) shows that the project is built on Hydra’s rendering API (including support for Storm). This component manages the Hydra scene graph, data production, filtering, and selection.
- Adapter Layers – The project uses a collection of adapters (in “lib/mayaHydra/hydraExtensions/adapters”) to convert Maya entities (geometric primitives, lights, cameras, etc.) into a format that Hydra and USD can work with.
- Testing & Samples – The “test” directory (with numerous subdirectories and sample scenes) demonstrates integration tests, sample usage, and ensures that the transformations between Maya and Hydra behave correctly.
- Build & Configuration Infrastructure – CMake files, pre-commit hooks, and GitHub workflows indicate a well-organized build environment, showing how the components are built and integrated.

##### Relationships and Interactions
- The Maya Host calls into the Maya Plugin, which triggers transformations via the adapter layer.
- Adapters convert Maya scene data into USD-compatible forms (utilizing SceneIndex and data producers in “lib/flowViewport”).
- Hydra (using Storm as the renderer) consumes and renders this scene graph, resulting in the viewport display.
- Testing modules simulate interactions and validate that data flows correctly between Maya, the plugin, the adapter layers, and Hydra/Storm.
- Build scripts drive compilation and integration of these elements.

##### Architectural Patterns / Design Principles
- Modularity: The system is broken into clear modules (Maya integration, Hydra viewport, adapter layers) that work together.
- Adapter/Bridge Pattern: Core to translating Maya’s native objects into Hydra’s scene graph (as seen in “hydraExtensions/adapters”).
- Plugin Architecture: Leveraging Maya’s plugin system to override its default viewport, enabling hip development and future extensibility.
- Separation of Concerns: There is a distinct separation between rendering logic (Hydra, Storm) and Maya-specific code.

##### Relevant Technologies and Frameworks
- Autodesk Maya as the host application.
- Pixar’s USD & Hydra (rendering API and Storm as the OpenGL renderer).
- CMake as the build and configuration tool.
- Testing frameworks (likely GoogleTest given the presence of googletest files under “cmake/googletest.cmake”).
- Scripting components (MEL scripts under “scripts”) for plug-in registration and control.

##### Elements
- Maya Host Environment.
- Plugin Modules & Maya-specific integrations (including parts from lib/mayaHydra and plugin/mayaHydraSceneBrowser).
- Adapter/Bridge Layer that interprets or converts the scene (with separation between different adapter types, e.g., camera, light, geometry).
- Hydra Core & Storm Renderer modules (drawn from lib/flowViewport, along with SceneIndex and Filtering/Data Producer components).
- Test and Sample Data (representing the extensive test coverage for various features and limitations).
- Build & CI/CD Infrastructure (CMake, pre-commit hooks, GitHub workflows).
- Data flow from the Maya scene into the plugin.
- Transformation through the adapter layer.
- Hand-off to Hydra for rendering.
- Feedback loops for testing and viewport selection/highlighting.
- Annotation for any noted limitations or points of extensibility (e.g., known limitations with material support or nodes that are not supported).

## Diagram (Mermaid)

```mermaid
graph TD
    %% Maya Host Environment
    subgraph "Maya Host Environment"
        M1["Maya Environment"]:::maya
        M2["Registration Script"]:::mayaScript
    end

    %% Maya Plugin & Extensions
    subgraph "Maya Plugin & Extensions"
        P1["Maya Plugin Scene Browser"]:::plugin
        P2["Core Maya Hydra Code"]:::plugin
        P3["Hydra Extensions for Maya"]:::plugin
    end

    %% Adapter Layers
    subgraph "Adapter Layers"
        A1["Maya Entity Adapters"]:::adapter
    end

    %% Hydra & USD Integration
    subgraph "Hydra & USD Integration"
        H1["Core Hydra Viewport API"]:::hydra
        H2["Storm Renderer"]:::hydra
    end

    %% Testing & Samples
    subgraph "Testing & Samples"
        T1["Integration Tests & Samples"]:::tests
    end

    %% Build & CI/CD Infrastructure
    subgraph "Build & CI/CD Infrastructure"
        B1["CMakeLists.txt"]:::build
        B2["CMake Directory"]:::build
        B3["GitHub Workflows"]:::build
    end

    %% Connections
    M1 --> M2
    M2 -->|"initiates"| P1
    P1 -->|"calls"| P2
    P2 -->|"utilizes"| P3
    P3 -->|"bridges to"| A1
    A1 -->|"translates to"| H1
    H1 -->|"renders using"| H2

    T1 -- "tests" --> P1
    T1 -- "tests" --> H1

    B1 -- "builds" --> P1
    B2 -- "configures" --> P1
    B3 -- "integrates" --> P1

    B1 -- "builds" --> H1
    B2 -- "configures" --> H1
    B3 -- "integrates" --> H1

    %% Click Events
    click M2 "https://github.com/autodesk/maya-hydra/tree/dev/scripts/mayaHydra_registerUI"
    click P1 "https://github.com/autodesk/maya-hydra/tree/dev/plugin/mayaHydraSceneBrowser"
    click P2 "https://github.com/autodesk/maya-hydra/tree/dev/lib/mayaHydra"
    click P3 "https://github.com/autodesk/maya-hydra/tree/dev/lib/mayaHydra/hydraExtensions"
    click A1 "https://github.com/autodesk/maya-hydra/tree/dev/lib/mayaHydra/hydraExtensions/adapters"
    click H1 "https://github.com/autodesk/maya-hydra/tree/dev/lib/flowViewport"
    click T1 "https://github.com/autodesk/maya-hydra/tree/dev/test"
    click B1 "https://github.com/autodesk/maya-hydra/blob/dev/CMakeLists.txt"
    click B2 "https://github.com/autodesk/maya-hydra/tree/dev/cmake"
    click B3 "https://github.com/autodesk/maya-hydra/tree/dev/.github/workflows"

    %% Styles
    classDef maya fill:#FFCCCC,stroke:#333,stroke-width:2px;
    classDef mayaScript fill:#F7A8A8,stroke:#333,stroke-width:2px;
    classDef plugin fill:#CCFFCC,stroke:#333,stroke-width:2px;
    classDef adapter fill:#CCE5FF,stroke:#333,stroke-width:2px;
    classDef hydra fill:#FFF2CC,stroke:#333,stroke-width:2px;
    classDef tests fill:#E6CCFF,stroke:#333,stroke-width:2px;
    classDef build fill:#D9D9D9,stroke:#333,stroke-width:2px;
```
