How aap/librw works
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.