# ipotrick/daxa architecture

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

- Interactive diagram: https://gitdiagram.com/ipotrick/daxa
- Repository: https://github.com/ipotrick/daxa

## Overview

##### Project Type and Purpose
- Daxa is a low-level graphics abstraction library built over Vulkan.
- Its purpose is to simplify advanced GPU programming (including raytracing, mesh shaders, async compute, and more) by providing a high-level, ergonomic API while retaining predictable performance.
- The README highlights its focus on modern GPUs and features like a fully integrated bindless system, a render-graph for automatic synchronization, a shader build system, and extensive validation checks.

##### Analyzing the File Structure
- Top-Level Components:
- Build System Files: Files such as CMakeLists.txt, CMakePresets.json, and cmake/toolchains indicate that the project utilizes CMake to support multiple platforms and toolchains.
- Library Code: The “include/daxa” directory (with both C and C++ headers) and “src” folder provide the core API implementations.
- Utilities & Extensions: There are shader utilities (files ending in .glsl, .slang) and helper modules, especially under “include/daxa/utils” and “src/utils.”
- Testing and Samples: The “tests” directory contains a comprehensive suite from basic setups to complete sample applications that not only exercise the API (including raytracing, mesh shaders, bindless integration, and more) but also serve as usage examples.
- Configuration Modules: Various cmake modules and vcpkg overlay ports (for dependencies like FSR2 and GLFW) reveal that dependency and packaging management is integrated.

##### Key Components
a. Core Daxa Library:
- API Abstraction Layer: Display modules for instance, device, command recorder, pipeline, swapchain, and synchronization.
- Bindless System: Illustrate how buffers, images, and acceleration structures are managed via a fully abstracted bindless API (removing the need for descriptor sets and layouts).
- Render-Graph & Shader Integration: Clearly identify the integration mechanisms for the render-graph, shader build system (including hot reloading and include management), and shader-host shared utilities.
- Memory Management: Highlight the automated memory allocation for buffers and images (with VMA integration) and transient memory pools.

b. Build and Configuration Components:
- CMake Build System: Represent CMake and its associated modules (toolchains, vcpkg overlays) which govern the build configuration and packaging.
- Platform Abstraction: Show how different toolchain files (for GCC, Clang, MSVC) tailor the build for various targets.

c. Testing and Samples:
- Sample Applications: Separate out sample/demo folders (like “4_hello_daxa”, “3_samples”) that serve as integration examples for end users.

##### Relationships and Interactions
- Abstraction Layers: Show a layered architecture where the low-level Vulkan calls are encapsulated by Daxa’s higher-level abstractions—indicate that the core modules (instance, device, pipeline, etc.) call directly into Vulkan functions.
- Shader and Render-Graph Integration: Demonstrate how the shader build system ties into the render graph – that is, changes in shader code trigger updates in the pipeline configuration.

##### Architectural Patterns & Design Principles
- Modularity: Each core part (device, pipeline, swapchain, etc.) should be shown as an independently defined module (especially visible from the segregated source files in “src” and “include”).
- Safety & Predictability: Indicate that every object contains methods for safety checks and metadata (as highlighted by the extensive validation checks and thread-safety descriptors).
- Extendability: Given the integrated shader utilities and render-graph capabilities, highlight that Daxa is designed to be extensible for varied rendering tasks (e.g., mesh shaders, raytracing).

##### Additional Notes
- Finally, be certain to indicate that the testing suite serves as both a verification layer and a set of practical examples for how the components interact in real-world scenarios.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Daxa API Abstraction
    subgraph "Core Daxa API Abstraction"
        subgraph "Instance Manager"
            IM_H("Header"):::coreModule
            IM_I("Implementation"):::coreModule
        end
        subgraph "Device Abstraction"
            DA_H("Header"):::coreModule
            DA_I("Implementation"):::coreModule
        end
        subgraph "Command Recorder"
            CR_H("Header"):::coreModule
            CR_I("Implementation"):::coreModule
        end
        subgraph "Pipeline Manager"
            PM_H("Header"):::coreModule
            PM_I("Implementation"):::coreModule
            subgraph "Pipeline Manager Utilities"
                PMU_H("Header"):::coreModule
                PMU_I("Implementation"):::coreModule
            end
        end
        subgraph "Swapchain Management"
            SC_H("Header"):::coreModule
            SC_I("Implementation"):::coreModule
        end
        subgraph "Synchronization"
            SYNC_H("Header"):::coreModule
            SYNC_I("Implementation"):::coreModule
        end
        subgraph "GPU Resources Management"
            GR_H("Header"):::coreModule
            GR_I("Implementation"):::coreModule
        end
    end

    %% Bindless Resource & Shader Integration
    subgraph "Bindless Resource & Shader Integration"
        subgraph "Bindless System & Shader Build"
            DGL("daxa.glsl"):::shaderModule
            DSL("daxa.slang"):::shaderModule
            DH("daxa.hpp"):::shaderModule
            DI("daxa.inl"):::shaderModule
        end
        subgraph "Render-Graph / Task Graph"
            TG_H("task_graph.hpp"):::shaderModule
            TGT_H("task_graph_types.hpp"):::shaderModule
            TGI("task_graph.inl"):::shaderModule
            TGI2("impl_task_graph.cpp"):::shaderModule
        end
    end

    %% Memory Management
    subgraph "Memory Management"
        MEM_H("mem.hpp"):::coreModule
        MEM_I("impl_mem.cpp"):::coreModule
    end

    %% Build & Configuration
    subgraph "Build & Configuration"
        CML("CMakeLists.txt"):::buildModule
        CMP("CMakePresets.json"):::buildModule
        CMA("cmake/"):::buildModule
        VCPKG("vcpkg-overlay-ports/ & vcpkg.json"):::buildModule
    end

    %% Utilities & Extensions
    subgraph "Utilities & Extensions"
        subgraph "ImGui Integration"
            IMGUI_H("imgui.hpp"):::utilityModule
            IMGUI_I("impl_imgui.cpp"):::utilityModule
        end
        subgraph "FSR2 Upscaling"
            FSR2_H("fsr2.hpp"):::utilityModule
            FSR2_I("impl_fsr2.cpp"):::utilityModule
        end
    end

    %% Testing & Samples
    subgraph "Testing & Samples"
        TESTS("tests/"):::testModule
        S3("tests/3_samples"):::testModule
        S4("tests/4_hello_daxa"):::testModule
    end

    %% External Dependencies
    subgraph "External Dependencies"
        VULKAN("Vulkan API"):::external
    end

    %% Relationships and Data Flow
    IM_H --> DA_H
    DA_H --> CR_H
    DA_H --> PM_H
    DA_H --> SC_H
    DA_H --> SYNC_H
    DA_H --> GR_H

    PM_H --> PMU_H

    PM_H --> TGI

    GR_H --> MEM_H

    CML --> IM_H
    CMP --> IM_H
    CMA --> IM_H
    VCPKG --> IM_H

    TESTS --> IM_H
    S3 --> TESTS
    S4 --> TESTS

    VULKAN --- IM_H

    DA_H --> DH
    DH --> DI
    DGL --> TG_H

    %% Styles
    classDef coreModule fill:#cce5ff,stroke:#004085,stroke-width:2px;
    classDef shaderModule fill:#d4edda,stroke:#155724,stroke-width:2px;
    classDef buildModule fill:#fff3cd,stroke:#856404,stroke-width:2px;
    classDef utilityModule fill:#e2e3e5,stroke:#d6d8db,stroke-width:2px;
    classDef testModule fill:#f8d7da,stroke:#721c24,stroke-width:2px;
    classDef external fill:#d1ecf1,stroke:#0c5460,stroke-width:2px;

    %% Click Events for Core Daxa API Abstraction
    click IM_H "https://github.com/ipotrick/daxa/blob/master/include/daxa/instance.hpp"
    click IM_I "https://github.com/ipotrick/daxa/blob/master/src/impl_instance.cpp"
    click DA_H "https://github.com/ipotrick/daxa/blob/master/include/daxa/device.hpp"
    click DA_I "https://github.com/ipotrick/daxa/blob/master/src/impl_device.cpp"
    click CR_H "https://github.com/ipotrick/daxa/blob/master/include/daxa/command_recorder.hpp"
    click CR_I "https://github.com/ipotrick/daxa/blob/master/src/impl_command_recorder.cpp"
    click PM_H "https://github.com/ipotrick/daxa/blob/master/include/daxa/pipeline.hpp"
    click PM_I "https://github.com/ipotrick/daxa/blob/master/src/impl_pipeline.cpp"
    click PMU_H "https://github.com/ipotrick/daxa/blob/master/include/daxa/utils/pipeline_manager.hpp"
    click PMU_I "https://github.com/ipotrick/daxa/blob/master/src/utils/impl_pipeline_manager.cpp"
    click SC_H "https://github.com/ipotrick/daxa/blob/master/include/daxa/swapchain.hpp"
    click SC_I "https://github.com/ipotrick/daxa/blob/master/src/impl_swapchain.cpp"
    click SYNC_H "https://github.com/ipotrick/daxa/blob/master/include/daxa/sync.hpp"
    click SYNC_I "https://github.com/ipotrick/daxa/blob/master/src/impl_sync.cpp"
    click GR_H "https://github.com/ipotrick/daxa/blob/master/include/daxa/gpu_resources.hpp"
    click GR_I "https://github.com/ipotrick/daxa/blob/master/src/impl_gpu_resources.cpp"

    %% Click Events for Bindless Resource & Shader Integration
    click DGL "https://github.com/ipotrick/daxa/blob/master/include/daxa/daxa.glsl"
    click DSL "https://github.com/ipotrick/daxa/blob/master/include/daxa/daxa.slang"
    click DH "https://github.com/ipotrick/daxa/blob/master/include/daxa/daxa.hpp"
    click DI "https://github.com/ipotrick/daxa/blob/master/include/daxa/daxa.inl"
    click TG_H "https://github.com/ipotrick/daxa/blob/master/include/daxa/utils/task_graph.hpp"
    click TGT_H "https://github.com/ipotrick/daxa/blob/master/include/daxa/utils/task_graph_types.hpp"
    click TGI "https://github.com/ipotrick/daxa/blob/master/include/daxa/utils/task_graph.inl"
    click TGI2 "https://github.com/ipotrick/daxa/blob/master/src/utils/impl_task_graph.cpp"

    %% Click Events for Memory Management
    click MEM_H "https://github.com/ipotrick/daxa/blob/master/include/daxa/utils/mem.hpp"
    click MEM_I "https://github.com/ipotrick/daxa/blob/master/src/utils/impl_mem.cpp"

    %% Click Events for Build & Configuration
    click CML "https://github.com/ipotrick/daxa/blob/master/CMakeLists.txt"
    click CMP "https://github.com/ipotrick/daxa/blob/master/CMakePresets.json"
    click CMA "https://github.com/ipotrick/daxa/tree/master/cmake/"
    click VCPKG "https://github.com/ipotrick/daxa/tree/master/cmake/vcpkg-overlay-ports/"

    %% Click Events for Utilities & Extensions
    click IMGUI_H "https://github.com/ipotrick/daxa/blob/master/include/daxa/utils/imgui.hpp"
    click IMGUI_I "https://github.com/ipotrick/daxa/blob/master/src/utils/impl_imgui.cpp"
    click FSR2_H "https://github.com/ipotrick/daxa/blob/master/include/daxa/utils/fsr2.hpp"
    click FSR2_I "https://github.com/ipotrick/daxa/blob/master/src/utils/impl_fsr2.cpp"

    %% Click Events for Testing & Samples
    click TESTS "https://github.com/ipotrick/daxa/tree/master/tests/"
    click S3 "https://github.com/ipotrick/daxa/tree/master/tests/3_samples"
    click S4 "https://github.com/ipotrick/daxa/tree/master/tests/4_hello_daxa"

    %% Legend (as a note)
    LEGEND["Legend: Blue=Core API | Green=Shader Integration | Yellow=Build & Config | Gray=Utilities & Extensions | Red=Testing & Samples | Teal=External Dependencies"]
    style LEGEND fill:#ffffff,stroke:#000000,stroke-width:1px,stroke-dasharray: 5 5
```
