# aap/librw architecture

> Architecture diagram of the GitHub repository aap/librw, 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/aap/librw
- Repository: https://github.com/aap/librw

## Overview

##### Project Type and Purpose
- The project is a graphics library that re-implements RenderWare. Its purpose is to provide a cross-platform means of rendering by supporting multiple file formats and rendering backends.
- The README indicates that it supports rendering for GTA (through re3) and includes conversion mechanisms for different platforms.

##### File Structure – Key Observations
- Top-Level Build/Configuration Files: You have CMakeLists.txt files, premake scripts (premake5.lua, premake-vs2019.cmd), a Dockerfile, and CI configuration files (.appveyor, Travis, GitHub workflows). This suggests that the project is built with a flexible, multi-platform build system.
- cmake Directory: Contains custom find and configuration scripts for external libraries (e.g., SDL2) and toolchain configurations for PS2 and NX, suggesting customized build support for various platforms.
- src Directory: Holds the main library code. Notice the breakdown into subdirectories:
– d3d: Contains source files for the Direct3D backends (including D3D8, D3D9) along with associated shader files.
– gl: Contains OpenGL-specific code and shaders.
– ps2: Contains code and header files dedicated to the PlayStation 2’s capabilities.
– Other core functionality files (engine, pipeline, texture handling, etc.).
- skeleton: Contains sample code and integrations (using imgui and SDL2) demonstrating minimal usage.
- tools: Provides utilities and sample programs (e.g., camera demo, shader viewing, ps2test) that show how to use the library.
- Third-party or external dependencies: Notice the inclusion of lodepng (for PNG support) and libraries (like imgui) packaged within the repository.

##### Key Components to Be Represented
a. Core Library Engine and Subsystems
– Core Engine (src/engine.cpp, pipeline, error handling, file formats, etc.)
– Data Handling: Support for multiple file formats (DFF, TXD) as indicated by multiple source files.
– Rendering Abstraction: Abstract interfaces that allow the engine to direct rendering commands to different backends.

b. Rendering Backends
– Direct3D Backend: Located in src/d3d (with specific subcomponents like d3d8, d3d9, shaders, and device management).
– OpenGL Backend: Located in src/gl (with shader files and gl-specific implementations).
– PS2 Backend: Located in src/ps2, representing a platform-specific pipeline.
– Possibly Xbox support (files in src/d3d that mention Xbox-related processing).

c. Build and Configuration Infrastructure
– CMake/premake integration: Represent how multiple build systems are responsible for compiling cross-platform code.
– Custom cmake toolchain scripts (for PS2 and NX) that facilitate cross-compilation or platform-specific build configurations.
– Docker and CI scripts indicate automated builds/test environments.

d. Tools and Utilities
– Various tools in the “tools” directory (camera viewers, ps2test, dumprwtree, etc.) which utilize the library as client applications.
– These can be drawn as separate modules that interact with the core library API.

##### Relationships and Data Flow
- The Core Library should be placed centrally as the “heart” of the architecture.
- How Tools (client applications) interact with the Core Library via the public API.
- “build/config” as an overlay or a separate block that affects all source modules, representing the integration with CMake/premake and custom scripts.

##### Architectural Patterns and Design Principles
- Modular Abstraction: Clearly separate platform-dependent code (for rendering) from the common engine functionalities.
- Layered Architecture: Present the system as multiple layers:
– Presentation / Rendering Layer (D3D, OpenGL, PS2)
– Business/Processing Layer (core engine, pipeline, error management)
– Interface Layer (APIs that tools call into)
- Use of Adapter/Bridge Patterns: To abstract differences between rendering APIs while providing a common interface.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Configuration Block
    subgraph "Build & Configuration"
        BConfig["Build & Configuration"]:::build
    end

    %% Core Engine and File Format Support
    subgraph "Core Engine & File Formats"
        Core["librw Core Engine"]:::core
        FFS["File Format Support"]:::fileSupport
    end

    %% Rendering Backends Block
    subgraph "Rendering Backends"
        D3D["Direct3D Backend\n(D3D8,D3D9,Shaders)"]:::backend
        OpenGL["OpenGL Backend\n(Shaders,GL Init)"]:::backend
        PS2["PS2 Backend"]:::backend
    end

    %% Client Applications Block
    subgraph "Client Applications"
        Tools["Tools & Utilities"]:::tools
        Skeleton["Sample Applications"]:::sample
    end

    %% Connections from Build & Configuration to all modules
    BConfig -->|"configures"| Core
    BConfig -->|"configures"| D3D
    BConfig -->|"configures"| OpenGL
    BConfig -->|"configures"| PS2
    BConfig -->|"configures"| Tools
    BConfig -->|"configures"| Skeleton

    %% Connections between Core Engine and File Format Support
    FFS ---|"data flow"| Core

    %% Core Engine invoking Rendering Backends
    Core -->|"calls_rendering"| D3D
    Core -->|"calls_rendering"| OpenGL
    Core -->|"calls_rendering"| PS2

    %% Client Applications interacting with Core Engine
    Tools -->|"API_call"| Core
    Skeleton -->|"API_call"| Core

    %% Click Events
    click Core "https://github.com/aap/librw/blob/master/src/engine.cpp"
    click FFS "https://github.com/aap/librw/blob/master/src/clump.cpp"
    click D3D "https://github.com/aap/librw/tree/master/src/d3d"
    click OpenGL "https://github.com/aap/librw/tree/master/src/gl"
    click PS2 "https://github.com/aap/librw/tree/master/src/ps2"
    click BConfig "https://github.com/aap/librw/blob/master/CMakeLists.txt"
    click Tools "https://github.com/aap/librw/tree/master/tools"
    click Skeleton "https://github.com/aap/librw/tree/master/skeleton"

    %% Styles
    classDef core fill:#ADD8E6,stroke:#000,stroke-width:2px;
    classDef backend fill:#90EE90,stroke:#000,stroke-width:2px;
    classDef fileSupport fill:#FFC0CB,stroke:#000,stroke-width:2px;
    classDef build fill:#FFFF99,stroke:#000,stroke-width:2px;
    classDef tools fill:#D3D3D3,stroke:#000,stroke-width:2px;
    classDef sample fill:#FFDEAD,stroke:#000,stroke-width:2px;
```
