# libcg/grvk architecture

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

- Interactive diagram: https://gitdiagram.com/libcg/grvk
- Repository: https://github.com/libcg/grvk

## Overview

##### Main components
- API Frontends (DLLs): These are the mantle*.dll libraries (both 32-bit and 64-bit) along with the mantleaxl*.dll. They form the interfaces that games load. They intercept Mantle (and Mantle extension library) API calls.
- Translation and Adaptation Layers: The core code in the “src/mantle”, “src/mantleaxl”, and “src/mantleinfo” directories implement the translation logic. They take the intercepted Mantle calls and translate them into Vulkan calls.
- AMDIL Compiler Subsystem: The “src/amdilc” directory contains the AMDIL compiler’s source code. This module handles compiling, decoding, and converting AMD’s intermediate language (possibly to SPIR-V) as needed.
- Vulkan Loader & Integration: Look at the files like “src/mantle/vulkan_loader.c/h” that bridge the calls once translated. They invoke Vulkan API functions from the rendered Vulkan library.
- Logging and Debugging Components: The “src/logger” directory provides logging functionality to capture runtime details, errors, and information about the translation process.
- & Library Files: The “include” directories (with subdirectories for “amdil”, “mantle”, “spirv”, “vulkan”) supply the necessary headers, while the “lib” directories link the Vulkan loader. These represent external dependencies and interface definitions.

##### Relationships and interactions
- When a game calls a Mantle API function (via the DLL dropped into its directory), the API call is intercepted by one of the mantle/mantleaxl DLL modules.
- These DLL frontends then route the call to the translation layer (the logic in “src/mantle” and “src/mantleaxl”), which performs any necessary processing or state management.
- If shader compilation or intermediate language decoding is necessary, the call passes into the AMDIL subsystem (“src/amdilc”) for conversion, producing output in SPIR-V format using headers under “include/spirv”.
- Finally, the translation layer uses the Vulkan loader (e.g., “src/mantle/vulkan_loader.c”) to make Vulkan API calls to the underlying graphics drivers.
- Throughout this process, the logging module captures key events and errors, writing to log files as determined by environment variables.

##### Architectural patterns and design principles
- Layered Architecture: Clearly separate the interceptor DLLs (API frontend), translation logic (core conversion engine), and the external dependencies (Vulkan and logging).
- Modularity: Different components (Mantle core, AXL extension, AMDIL compiler, and logger) are isolated in their own directories, suggesting independent modules that interact through well-defined interfaces.
- Adaptation: Emphasize the translator design pattern, as the system adapts Mantle calls to Vulkan calls.
- Cross-Platform Considerations: The use of Meson build files for configuring both 32-bit and 64-bit builds hints at careful deployment planning.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Level: Game Client
    G["Game (Client)"]:::external

    %% API Frontends Subgraph
    subgraph "API Frontends"
        MGL32["Mantle DLL (32-bit)"]:::frontend
        MGL64["Mantle DLL (64-bit)"]:::frontend
        MAXL32["Mantle AXL DLL (32-bit)"]:::frontend
        MAXL64["Mantle AXL DLL (64-bit)"]:::frontend
    end

    %% Translation Layer Subgraph
    subgraph "Translation Layer"
        MT["Mantle Translation"]:::translation
        MAXLT["Mantle AXL Translation"]:::translation
        MIL["Mantle Info Loader"]:::translation
    end

    %% Shader Compilation (AMDIL Compiler)
    AMDIL["Shader Compilation (AMDIL Compiler)"]:::shader

    %% Vulkan Loader & API Invocation
    VL["Vulkan Loader & API Invocation"]:::loader

    %% Vulkan Driver / GPU
    VD["Vulkan Driver / GPU"]:::external

    %% Auxiliary Logging Module
    LOG["Logging Module"]:::logging

    %% External Dependencies Subgraph
    subgraph "External Dependencies"
        IH["Include Headers"]:::external
        VL_lib["Vulkan Libraries"]:::external
    end

    %% Flow Connections
    G -->|"calls"| MGL32
    G -->|"calls"| MGL64
    G -->|"calls"| MAXL32
    G -->|"calls"| MAXL64

    MGL32 -->|"routes"| MT
    MGL64 -->|"routes"| MT
    MAXL32 -->|"routes"| MAXLT
    MAXL64 -->|"routes"| MAXLT

    %% Merge translation paths
    MT -->|"integrates"| MIL
    MAXLT -->|"integrates"| MIL

    %% Translation flow to shader compilation and Vulkan calls
    MIL -->|"shaderCompilation"| AMDIL
    AMDIL -->|"vulkanCall"| VL
    VL -->|"invokes"| VD

    %% Logging arrows from key modules
    MT ---|"log"| LOG
    MAXLT ---|"log"| LOG
    MIL ---|"log"| LOG
    AMDIL ---|"log"| LOG
    VL ---|"log"| LOG

    %% External dependencies connections
    IH ---|"headers"| AMDIL
    VL_lib ---|"link"| VL

    %% Click Events for API Frontends
    click MGL32 "https://github.com/libcg/grvk/blob/master/src/mantle/mantle32.def"
    click MGL64 "https://github.com/libcg/grvk/blob/master/src/mantle/mantle64.def"
    click MAXL32 "https://github.com/libcg/grvk/blob/master/src/mantleaxl/mantleaxl32.def"
    click MAXL64 "https://github.com/libcg/grvk/blob/master/src/mantleaxl/mantleaxl64.def"

    %% Click Events for Translation and Adaptation Layers
    click MT "https://github.com/libcg/grvk/blob/master/src/mantle/main.c"
    click MAXLT "https://github.com/libcg/grvk/blob/master/src/mantleaxl/main.c"
    click MIL "https://github.com/libcg/grvk/blob/master/src/mantleinfo/mantle_loader.c"

    %% Click Event for AMDIL Compiler
    click AMDIL "https://github.com/libcg/grvk/blob/master/src/amdilc/amdilc.c"

    %% Click Event for Vulkan Loader
    click VL "https://github.com/libcg/grvk/blob/master/src/mantle/vulkan_loader.c"

    %% Click Event for Logger
    click LOG "https://github.com/libcg/grvk/blob/master/src/logger/logger.c"

    %% Click Events for External Dependencies
    click IH "https://github.com/libcg/grvk/tree/master/include/mantle"
    click VL_lib "https://github.com/libcg/grvk/blob/master/lib/vulkan-1.lib"

    %% Styles
    classDef frontend fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef translation fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef shader fill:#FFA07A,stroke:#000,stroke-width:2px;
    classDef loader fill:#FFD700,stroke:#000,stroke-width:2px;
    classDef logging fill:#DDA0DD,stroke:#000,stroke-width:2px;
    classDef external fill:#E6E6FA,stroke:#000,stroke-width:2px;
```
