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

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/.

#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, 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).

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).

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).

; 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 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). 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 for the dashboard and 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).
• 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).
• 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).

# 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}