# What Are the Main Components of Renodx? A Deep Dive into the Architecture

> Explore the five core architectural layers of Renodx: runtime, utility addons, game modules, UI, and test harness. Understand Renodx components for enhanced graphics.

- Repository: [Carlos Lopez/renodx](https://github.com/clshortfuse/renodx)
- Tags: deep-dive
- Published: 2026-09-06

---

**Renodx is organized into five architectural layers: a core runtime that hooks DirectX 12 and Vulkan via ReShade, generic utility addons, game-specific integration modules, a web-based configuration UI, and a comprehensive test harness.**

The `clshortfuse/renodx` repository provides a modular framework for modifying modern PC games at the graphics API level. Understanding the main components of renodx reveals how it intercepts rendering calls, applies compatibility fixes, and exposes developer tools without modifying game binaries directly.

## Core Runtime Engine

The core runtime sits between the game executable and the graphics driver, implemented as a ReShade-compatible addon layer in `src/addons/`. This layer handles resource virtualization, synchronization primitives, and shader pipeline modifications.

### Swapchain Proxy and Resource Management

The **swapchain proxy** implements a virtual swapchain that intercepts, replays, or modifies presented frames. It enables HDR-to-SDR tonemapping, custom barrier handling, and resource-state tracking. The implementation resides in `src/addons/swapchain_proxy/`, with validation logic in `test/swapchain_change_detection/` and barrier-state tests in `test/swapchain_proxy_barrier_states/`.

```cpp
#include "renodx/swapchain_proxy.h"

renodx::SwapChainProxy proxy;
proxy.Initialize(originalSwapChain);          // Wrap the original DX12 swap chain
proxy.SetPresentHook([](UINT sync) {          // Hook the Present call
    // Insert custom post‑process here
    return proxy.DefaultPresent(sync);
});

```

### Descriptor Cache Race Handling

To protect the DirectX 12 descriptor heap from concurrent updates that cause GPU crashes, the runtime includes a **descriptor cache race handler**. This component serializes access to descriptor heaps during multithreaded command list recording. The source is located at [`src/addons/descriptor_cache_race/addon.cpp`](https://github.com/clshortfuse/renodx/blob/main/src/addons/descriptor_cache_race/addon.cpp), with thread-safety tests in `test/descriptor_cache_race/`.

### Render Pass Behavior and Shader Injection

The runtime tracks render-pass lifetimes to correctly insert custom passes or debug overlays. This **render pass behavior** module lives in `src/addons/render_pass_behavior/` and is exercised by `test/render_pass_behavior/`. Complementing this, the **shader injection** system parses and rewrites HLSL/GLSL shaders at runtime, providing fallback paths for missing features. Integration tests for this pipeline live in `test/shader_injection_behavior/` and `test/shader_source_compatibility/`.

## Generic Addons (Cross-Game Utilities)

Renodx distributes reusable functionality as standalone addons that any supported game can load. These modules are compiled into separate DLLs and registered via ReShade’s addon manifest system.

### FPS Limiter

The **FPS limiter** addon caps the frame rate to a user-defined value, preventing GPU overuse and reducing power consumption. The implementation is contained entirely within [[`src/addons/fpslimiter/addon.cpp`](https://github.com/clshortfuse/renodx/blob/main/src/addons/fpslimiter/addon.cpp)](https://github.com/clshortfuse/renodx/blob/main/src/addons/fpslimiter/addon.cpp).

### DLSS Fix

The **DLSS fix** addon works around known compatibility issues with NVIDIA’s Deep Learning Super Sampling by inserting resource-barrier shims before DLSS dispatch calls. Source code is available in [[`src/addons/dlssfix/addon.cpp`](https://github.com/clshortfuse/renodx/blob/main/src/addons/dlssfix/addon.cpp)](https://github.com/clshortfuse/renodx/blob/main/src/addons/dlssfix/addon.cpp).

### Developer Kit

The **DevKit** addon exposes internal diagnostics, live shader reloading, and frame-capture triggers for developers. It is implemented in [[`src/addons/devkit/addon.cpp`](https://github.com/clshortfuse/renodx/blob/main/src/addons/devkit/addon.cpp)](https://github.com/clshortfuse/renodx/blob/main/src/addons/devkit/addon.cpp).

```ini
; Example ReShade configuration loading a renodx addon
[Addon]
Enable = true
Path = "renodx/addons/fpslimiter/addon.dll"

```

## Game-Specific Addons (Per-Title Integration)

Each supported title receives a dedicated integration layer under `src/games/`. These folders contain an [`addon.cpp`](https://github.com/clshortfuse/renodx/blob/main/addon.cpp) wrapper that registers game-specific resource upgrades, workaround hooks, and entry-point patches required for that particular engine.

For example, the *Zelda: Echoes of Wisdom* integration is located at [[`src/games/zelda-eow/addon.cpp`](https://github.com/clshortfuse/renodx/blob/main/src/games/zelda-eow/addon.cpp)](https://github.com/clshortfuse/renodx/blob/main/src/games/zelda-eow/addon.cpp). Similar wrappers exist for other titles in parallel directories such as `src/games/xfextremeformula/` and `src/games/xenobladechronicles/`.

## Web UI and Static Assets

Renodx includes an embedded web server that serves a configuration interface. The static assets—HTML, CSS, and JavaScript—are stored in `src/web/static/`. Key files include [`index.html`](https://github.com/clshortfuse/renodx/blob/main/index.html) for the dashboard and [`mods.html`](https://github.com/clshortfuse/renodx/blob/main/mods.html) for per-game mod management. These files are served directly by the runtime to allow in-game configuration without external editors.

## Command-Line Tools and Analysis Utilities

The repository provides standalone CLI utilities for offline shader analysis and pipeline debugging:

- **Shader Dependency Analyzer**: Parses HLSL source to output JSON dependency graphs. Implemented in [[`src/analyze_shader_deps.cpp`](https://github.com/clshortfuse/renodx/blob/main/src/analyze_shader_deps.cpp)](https://github.com/clshortfuse/renodx/blob/main/src/analyze_shader_deps.cpp).
- **Bytecode Decompiler**: Converts compiled shader bytecode back to readable intermediate representations. Entry point is [[`src/decompiler/cli.cpp`](https://github.com/clshortfuse/renodx/blob/main/src/decompiler/cli.cpp)](https://github.com/clshortfuse/renodx/blob/main/src/decompiler/cli.cpp).
- **MCP Bridge**: Provides a network bridge for the Mod Control Protocol, allowing external tools to trigger renodx actions. Source resides in [[`src/apps/mcp_bridge/main.cpp`](https://github.com/clshortfuse/renodx/blob/main/src/apps/mcp_bridge/main.cpp)](https://github.com/clshortfuse/renodx/blob/main/src/apps/mcp_bridge/main.cpp).

```bash

# Analyze shader dependencies for compatibility checking

renodx-analyze-shader-deps --input my_shader.hlsl --output deps.json

```

## Test Harness and Validation Suite

Stability is enforced by a **test harness** located in the `test/` directory. This suite compiles small DirectX 12 and Vulkan demo applications to validate that renodx interceptors behave correctly across driver versions.

Key validation modules include:

- `test/resource_upgrade_transfer/` – Validates legacy-to-modern resource format upgrades and Vulkan-to-DirectX memory transfers.
- `test/swapchain_proxy_barrier_states/` – Verifies correct resource barrier insertion by the swapchain proxy.
- `test/descriptor_cache_race/` – Stress-tests thread safety of the descriptor cache.

## Summary

- **Core Runtime**: Intercepts graphics APIs via swapchain proxies, descriptor cache protection, and render-pass tracking.
- **Generic Addons**: Reusable modules for framerate limiting, DLSS compatibility, and developer diagnostics.
- **Game-Specific Addons**: Per-title wrappers that register unique fixes and resource hooks.
- **Web UI**: Static assets served by the runtime for in-game configuration.
- **CLI Tools**: Offline utilities for shader analysis, decompilation, and protocol bridging.
- **Test Harness**: Integration tests ensuring stability across swapchain, resource, and shader subsystems.

## Frequently Asked Questions

### How does renodx hook into games without modifying game files?

Renodx operates as a **ReShade addon**, loading as a DLL into the game process at runtime. It intercepts DirectX 12 and Vulkan calls through the ReShade injection layer, allowing it to wrap swapchains and modify command lists without touching the original executable.

### What is the purpose of the descriptor cache race handler?

The descriptor cache race handler in [`src/addons/descriptor_cache_race/addon.cpp`](https://github.com/clshortfuse/renodx/blob/main/src/addons/descriptor_cache_race/addon.cpp) prevents crashes caused by multiple CPU threads simultaneously writing to the DirectX 12 descriptor heap. It implements a synchronization wrapper that serializes these updates, which is essential for stability in heavily multithreaded game engines.

### Where should I place game-specific compatibility fixes?

Game-specific fixes belong in the `src/games/<title>/addon.cpp` file corresponding to that title. This wrapper registers the necessary resource upgrades and workaround hooks only when the specific game executable is detected, keeping the core runtime clean of title-specific logic.

### How can developers test changes to the core runtime?

Developers should use the **test harness** in the `test/` directory. Each subsystem has a dedicated folder (e.g., `test/swapchain_proxy_barrier_states/`) containing small graphics applications that exercise renodx’s interceptors. Running these tests validates that changes do not break barrier states, descriptor caching, or resource upgrading.