A modular rendering runtime for Grand Theft Auto: San Andreas.
D3D9 compatibility. Vulkan execution. Inspectable rendering.
English | Português (Brasil) | Español | Русский | 简体中文
Download | Quick Start | Architecture | API Modules | Build | Documentation
SA RenderStack brings a D3D9 Bridge, a GTA-compatible DXVK fork, and rendering diagnostics into one source project. The Bridge manages the entry point, configured third-party integration, and compatibility adapters. DXVK implements D3D9 and owns Vulkan execution.
Release baseline:
v0.1.0-alpha.1, GTA San Andreas 1.0 US / x86, with two runtime DLLs. This README also describes the current development tree, including its C++23 API subprojects. A source feature is not proof that the published archive contains it.
| Layer | What It Provides |
|---|---|
| Bridge | One root D3D9 entry point, ordered module registration, hook-ownership metadata, and optional plugin lifecycle callbacks. |
| DXVK Backend | D3D9-to-Vulkan translation with DXGI factory exports merged into the backend DLL. |
| Third-Party Integration | Compatibility adapters, selective native state journaling, and DirectConstants state batching where eligible. |
| API1–API7 | Seven C++23 subprojects attached to Bridge, with library sources, development examples, and tests. |
| Diagnostics | State attribution, CPU hotspot sampling, draw traces, and backend execution statistics. |
| Release Tooling | Source provenance, ABI/export checks, build metadata, package manifests, and rollback-file verification. |
State-block filtering, deferred bindings, resource caches, and optional thread scheduling are configurable experiments. Their presence does not establish a performance gain for every workload.
- Download
SA-RenderStack-v0.1.0-alpha.1-split.zipfrom the release page. - Close the game and loader processes. Back up every file that the package will replace, including both runtime DLLs and configuration files.
- Extract into the game directory containing
gta_sa.exe, preserving the archive's paths. - Verify menu-to-save loading, then validate representative scenes and the intended mod configuration.
The split archive is the runtime package. The SDK and symbols archives are development aids; installation does not require a compiler or PowerShell.
Read the installation and rollback guide before replacing an existing setup.
<GTA directory>/
gta_sa.exe
d3d9.dll # Bridge entry point
SA.RenderStack.ini # Bridge configuration
dxvk.conf # Backend configuration
backend/
dxvk-gta/d3d9.dll # DXVK D3D9 + DXGI backend
scripts/
BridgeD3D9.ini # Legacy configuration location
Keep both DLLs at their assigned paths. Copying the backend over the root d3d9.dll bypasses the Bridge. The merged DXGI exports belong to the backend; this is still a split-DLL runtime.
flowchart TD
game["GTA San Andreas · D3D9"] --> bridge["Bridge · root d3d9.dll"]
bridge --> backend["DXVK · backend/dxvk-gta/d3d9.dll"]
backend --> gpu["Vulkan driver · GPU"]
bridge --- modules["API1–API7 · attached C++23 modules"]
bridge -.-> adapters["Third-party adapters · optional plugins"]
adapters -. "supported compatibility calls" .-> backend
classDef application fill:#f0f9ff,stroke:#0284c7,color:#0c4a6e
classDef control fill:#f0fdf4,stroke:#15803d,color:#14532d
classDef execution fill:#fff1f2,stroke:#be123c,color:#881337
class game application
class bridge,modules,adapters control
class backend,gpu execution
The Bridge manages integration and diagnostics. DXVK owns the authoritative D3D9 state, Vulkan device, resources, command stream, and queue submission. State optimizations must account for native journal restoration and state-block changes in that authoritative layer.
API2 callbacks record into the existing Present command buffer. They must restore any image layouts they change and must not independently submit, end, reset, or recursively register from their callback. See the module map and backend API contract.
One parent runtime, seven code modules. Both Bridge Win32 projects include these implementations from src/bridge/legacy/api-projects/. Their examples and tests are development targets, not seven independently deployed programs.
| API | Attached Subproject | Responsibility |
|---|---|---|
| 1 | Status | Version/capability inspection and Vulkan interop access. |
| 2 | Vulkan Pass | Pass registration, ordering, and unregistration. |
| 3 | State Batch | Shader-constant ranges and texture-binding submission. |
| 4 | State Journal | Capture and restore supported pipeline state. |
| 5 | Effect Batch | Submit final effect-pass state as a batch. |
| 6 | State + Draw | Submit a state batch and one immediate DP/DIP call. |
| 7 | Selective Journal | Scope capture to owned effect operations. |
Interface availability, compilation into Bridge, and production adoption are separate facts. The current profile exercises API3 and API7 through a configured third-party integration path. API2 needs a registered pass; API5/API6 libraries and examples do not establish adoption in the game's hot path. API6 is a single-draw interface, not a multi-object or multi-draw queue.
These are backend compatibility API versions. The separate Bridge plugin API uses its own v1/v2 versioning.
| File | Ownership |
|---|---|
| SA.RenderStack.ini | Bridge integration, module registry, diagnostics, and optional scheduling. |
| dxvk.conf | DXVK options, GTA compatibility features, frame pacing, and HUD. |
The current Bridge reads the root SA.RenderStack.ini first and falls back to scripts/BridgeD3D9.ini. Keep the two copies synchronized when using older builds. Use the configuration shipped with the selected release as its baseline.
The registry observes configured third-party modules and provides disabled entries for optional integration. Missing third-party components are not installed by the registry. Details are in proxy and plugin hosting.
Development configuration: Optional
[Affinity] PerThreadandMmcssdefault to0. Enabling them is an experiment, not a real-time or exclusive-core guarantee. Diagnostic HUD contents and optimization switches can differ from the published alpha profile.
The main build targets Windows / Release / x86. The current source uses C++23; the Bridge projects select MSVC's stdcpplatest mode, and the API CMake targets require cxx_std_23.
| Toolchain | Purpose |
|---|---|
| PowerShell 7 and Git | Build orchestration and historical provenance checks. |
| Visual Studio 18 C++ Build Tools | Bridge and MSVC test targets; toolset v145. |
| LLVM-MinGW, Python 3, Meson, Ninja, glslang | x86 DXVK backend and shader build. |
| CMake 3.25+ | Optional aggregate build of API examples and unit tests. |
Run from the repository root:
pwsh -NoProfile -File tools/build.ps1 `
-Configuration Release -Architecture x86 -Component All -Clean
pwsh -NoProfile -File tools/test.ps1 `
-Configuration Release -Architecture x86Build outputs go to out/; these commands do not deploy to the game directory. Use each script's -Help for explicit tool paths and environment-specific options.
Build the attached API examples and tests
Configure the parent aggregate, not an individual API directory:
cmake -S src/bridge/legacy/api-projects -B out/api-project-build/all `
-G "Visual Studio 18 2026" -A Win32
cmake --build out/api-project-build/all --config Release
ctest --test-dir out/api-project-build/all -C Release --output-on-failureThe main MSBuild path compiles the API library sources into Bridge. This optional CMake path additionally builds the examples and their unit tests. Run GPU examples against the intended backend with an explicit DXVK compatibility configuration.
After a successful build and test run:
pwsh -NoProfile -File tools/package.ps1 `
-Version 0.1.0-alpha.1 -Configuration Release
pwsh -NoProfile -File tests/package-layout-test.ps1
pwsh -NoProfile -File tools/release-gate.ps1 `
-Version 0.1.0-alpha.1 -Configuration Release| Evidence | Output |
|---|---|
| Build identity and binary hashes | out/build-metadata.json |
| Per-test results, failures, and skips | out/test-results.json |
| Split, SDK, symbols, and source manifest | out/packages/ |
| Local release-gate verdict | out/reports/phase-1-release-gate.md |
Windows CI runs build, test, packaging, and package checks. Hosted runs explicitly skip GPU probes and local-game evidence checks, recording reasons in the test report. A green CI badge does not replace game testing or the local release gate.
| Capture | Output | Use |
|---|---|---|
| F7 | scripts/BridgeD3D9.state-attribution.log and DXVK session logs |
Effect/state attribution and backend batching. |
| F8 | scripts/BridgeD3D9.cpuhotspots.log, Diagnostics/CPU/ |
CPU hotspot samples and capture images. |
| F9 | scripts/BridgeD3D9.callsites.log |
Optional D3D9 call-site sampling. |
| F10 | scripts/BridgeD3D9.drawtrace.log |
Optional per-draw state tracing. |
| Backend | Diagnostics/DXVK/ |
Device, configuration, and session diagnostics. |
Keys and outputs depend on enabled configuration. Detailed captures and HUD queries add overhead; benchmark normal rendering separately using the same scene, binaries, and configuration.
The baseline is GTA San Andreas 1.0 US, 32-bit, using the Bridge entry point and a DXVK v3.0.1-derived Vulkan backend. A working Vulkan driver is required for that backend.
The published package targets the x86 split-DLL runtime for GTA San Andreas 1.0 US. The registry and compatibility APIs provide extension points for third-party integrations; support for a particular combination depends on its interface contract and validation results. The single-DLL runtime remains a separate development target.
FPS, texture streaming, shader appearance, input latency, and long-session stability must be measured with a fixed workload. See known findings and manual checks.
| Guide | Focus |
|---|---|
| Installation | Archive layout, first launch, and rollback. |
| Architecture | Module ownership and rendering contracts. |
| API Subprojects | The seven Bridge-owned code modules. |
| Maintainer Handoff | Build and release context. |
| Audit Findings | Known limits and validation requirements. |
| Release Notes | Published alpha scope. |
backend/dxvk/ Vulkan backend and GTA compatibility layer
src/bridge/legacy/ Main Bridge runtime and adapters
api-projects/ Seven attached C++23 API subprojects
sdk/include/sa_renderstack/ Public backend API
config/ Versioned runtime profiles
docs/ Architecture, development, and release notes
packaging/ Package layout contracts
tests/ Source, ABI, packaging, and regression checks
tools/ Build, test, package, and release automation
The backend derives from official DXVK v3.0.1. Its upstream identity and dependency revisions are recorded in the source tree.
SA RenderStack-specific code uses the zlib/libpng license. Vendored components retain their own licenses, listed in Third-Party Notices. Generated source manifests record file hashes and toolchain metadata for each release candidate.