# nvidia-rtx/donut architecture

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

- Interactive diagram: https://gitdiagram.com/nvidia-rtx/donut
- Repository: https://github.com/nvidia-rtx/donut

## Overview

##### Project type and purpose
- This is a modular, real-time rendering framework (“Donut”) composed of four static libraries:
- donut_core
- donut_engine
- donut_render
- donut_app
- Its goal is to provide reusable rendering passes, scene loading, and application scaffolding for prototypes and code samples.
- It is _not_ a game engine (no actors, navigation), but a rendering toolkit built on top of NVRHI and other submodules.

##### File structure
- Top-level CMake scripts and modules orchestrate build of each static library.
- `include/donut/...` folders expose headers for each subsystem.
- `src/...` folders contain the implementation for each subsystem.
- `shaders/` folder and `include/donut/shaders` contain HLSL/GLSL shader definitions and binding helpers.
- `thirdparty/` holds required and optional dependencies (cgltf, JsonCpp, stb, NVRHI, ImGUI, TaskFlow, etc.).

##### README for additional insights
- Four major subsystems and their dependencies are clearly described.
- Submodule dependencies (cgltf, JsonCpp, stb, NVRHI, etc.) are listed with build-time flags.
- Graphics API support is via NVRHI, with device creation and windowing handled by the `DeviceManager` classes in donut_app.

##### Elements
- Clear labels for each static library and folder (core, engine, render, app).
- In core: VFS, math utilities, logging, JSON
- In engine: SceneGraph, MaterialBindingCache, TextureCache, ConsoleInterpreter
- In render: ForwardShadingPass, DeferredLightingPass, SSAOPass, TAA, ToneMapping
- In app: ApplicationBase, MediaFileSystem, Camera, **DeviceManager_VK**, UI helpers
- Blue for core
- Green for engine
- Orange for render
- Purple for app
- Gray for external dependencies
- Rectangles for subsystems
- Rounded rectangles for key classes

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraphs for libraries
    subgraph "donut_core"
        direction TB
        VFS["VFS"]:::core
        Math["Math Utilities"]:::core
        Logging["Logging"]:::core
        JSONCore["JSON"]:::core
    end

    subgraph "donut_engine"
        direction TB
        SceneGraph["SceneGraph"]:::engine
        MaterialCache["MaterialBindingCache"]:::engine
        TextureCache["TextureCache"]:::engine
        ConsoleInterp["ConsoleInterpreter"]:::engine
    end

    subgraph "donut_render"
        direction TB
        ForwardPass["ForwardShadingPass"]:::render
        DeferredPass["DeferredLightingPass"]:::render
        SSAOPass["SSAOPass"]:::render
        TAA["TAA"]:::render
        ToneMapping["ToneMapping"]:::render
    end

    subgraph "donut_app (Vulkan only)"
        direction TB
        AppBase["ApplicationBase"]:::app
        MediaFS["MediaFileSystem"]:::app
        Camera["Camera"]:::app
        DeviceVK["DeviceManager_VK"]:::app
        UIHelpers["UI Helpers"]:::app
    end

    %% Shader subsystem
    ShaderSub["Shader Subsystem"]:::shader

    %% External dependencies
    NVRHI["NVRHI"]:::external
    VulkanDrv["Vulkan Driver"]:::external

    cgltf["cgltf"]:::external
    JsonCPP["JsonCpp"]:::external
    stb["stb"]:::external
    ImGuiGLFW["ImGUI/glfw"]:::external
    TaskFlow["TaskFlow"]:::external
    tinyexr["tinyexr"]:::external
    LZ4["LZ4"]:::external
    miniz["miniz"]:::external

    %% Dependencies
    SceneGraph -->|depends on| VFS
    SceneGraph -->|depends on| JSONCore
    MaterialCache -->|uses| TextureCache
    ForwardPass -->|calls| SceneGraph
    ForwardPass -->|uses| MaterialCache
    DeferredPass -->|uses| SSAOPass
    TAA -->|uses| ForwardPass
    ToneMapping -->|uses| DeferredPass

    donut_engine -->|depends on| donut_core
    donut_render -->|depends on| donut_core
    donut_render -->|depends on| donut_engine
    donut_app -->|depends on| donut_core
    donut_app -->|depends on| donut_engine
    donut_app -->|depends on| donut_render

    ShaderSub -->|feeds| ForwardPass
    ShaderSub -->|feeds| MaterialCache

    DeviceVK -->|uses| NVRHI
    NVRHI -->|wraps| VulkanDrv

    %% All subsystems to NVRHI
    VFS -->|uses| NVRHI
    SceneGraph -->|uses| NVRHI
    ForwardPass -->|uses| NVRHI
    AppBase -->|uses| NVRHI

    %% External assets
    SceneGraph -->|loads| cgltf
    SceneGraph -->|uses| JsonCPP
    SceneGraph -->|uses| stb

    AppBase -->|optional UI| ImGuiGLFW
    AppBase -->|optional threading| TaskFlow
    AppBase -->|optional image I/O| tinyexr
    AppBase -->|optional compression| LZ4
    AppBase -->|optional compression| miniz

    %% Click Events
    click donut_core "https://github.com/nvidia-rtx/donut/tree/main/include/donut/core"
    click donut_core "https://github.com/nvidia-rtx/donut/tree/main/src/core"
    click donut_engine "https://github.com/nvidia-rtx/donut/tree/main/include/donut/engine"
    click donut_engine "https://github.com/nvidia-rtx/donut/tree/main/src/engine"
    click donut_render "https://github.com/nvidia-rtx/donut/tree/main/include/donut/render"
    click donut_render "https://github.com/nvidia-rtx/donut/tree/main/src/render"
    click donut_app "https://github.com/nvidia-rtx/donut/tree/main/include/donut/app"
    click donut_app "https://github.com/nvidia-rtx/donut/tree/main/src/app"
    click DeviceVK "https://github.com/nvidia-rtx/donut/blob/main/include/donut/app/DeviceManager_VK.h"
    click ShaderSub "https://github.com/nvidia-rtx/donut/tree/main/include/donut/shaders"
    click ShaderSub "https://github.com/nvidia-rtx/donut/tree/main/shaders"
    click NVRHI "https://github.com/nvidia-rtx/donut/tree/main/nvrhi"
    click cgltf "https://github.com/nvidia-rtx/donut/tree/main/thirdparty/cgltf"
    click JsonCPP "https://github.com/nvidia-rtx/donut/tree/main/thirdparty/jsoncpp"
    click stb "https://github.com/nvidia-rtx/donut/tree/main/thirdparty/stb"
    click ImGuiGLFW "https://github.com/nvidia-rtx/donut/tree/main/thirdparty/imgui"
    click ImGuiGLFW "https://github.com/nvidia-rtx/donut/tree/main/thirdparty/glfw"
    click TaskFlow "https://github.com/nvidia-rtx/donut/tree/main/thirdparty/taskflow"
    click tinyexr "https://github.com/nvidia-rtx/donut/tree/main/thirdparty/tinyexr"
    click LZ4 "https://github.com/nvidia-rtx/donut/tree/main/thirdparty/lz4"
    click miniz "https://github.com/nvidia-rtx/donut/tree/main/thirdparty/miniz"

    %% Styles
    classDef core fill:#cce5ff,stroke:#4d94ff
    classDef engine fill:#d5f5d5,stroke:#28a428
    classDef render fill:#ffe5b4,stroke:#ff8c00
    classDef app fill:#e5ccff,stroke:#9b30ff
    classDef external fill:#e0e0e0,stroke:#888888,stroke-dasharray: 5 5
    classDef shader fill:#f2f2f2,stroke:#666666,stroke-dasharray: 3 3
```
