How to Integrate RenoDX with Other Projects: A Complete Developer Guide

Embed RenoDX into your CMake project, link against its shader and swapchain APIs, and compile a Reshade add-on (.addon64) to inject custom shaders into DirectX or Vulkan games.

To integrate RenoDX with other projects, you add the clshortfuse/renodx repository as a CMake subdirectory, include the public headers from src/mods/, and implement the RENODX_API InitAddon entry point. The resulting binary loads into Reshade at runtime, giving you access to RenoDX’s shader injection, swapchain upgrading, and runtime settings frameworks without modifying game source code.

Understanding the RenoDX Architecture

RenoDX is a Reshade-based add-on framework that intercepts graphics API calls through Reshade’s hook system. When you integrate RenoDX, you are building a Reshade add-on that leverages RenoDX’s abstraction layers for safe, versioned shader injection.

The architecture centers on three core subsystems:

• renodx::mods::shader – Handles custom shader creation and pipeline-layout manipulation. Defined in src/mods/shader.hpp, this namespace provides CustomShader objects and the CreateCustomShader factory function.
• renodx::mods::swapchain – Manages swapchain version selection (v1 vs. v2) and resource upgrades. The selector logic lives in src/mods/swapchain.hpp, with implementations in src/mods/swapchain_v2.hpp.
• renodx::utils::settings – Exposes runtime UI settings (sliders, toggles) that persist to disk. See src/utils/settings.hpp for the Setting class definition.

All hooks, such as OnCreatePipelineLayout and OnInitDevice, are called by Reshade and handled internally by RenoDX’s inline callback system.

Prerequisites and Build Environment

Before attempting to integrate RenoDX with other projects, ensure your environment meets the requirements outlined in docs/CONTRIBUTING.md. You need a Windows SDK compatible with DirectX 12 and a C++20 capable compiler (Clang or MSVC).

Clone RenoDX into your project structure:

git clone https://github.com/clshortfuse/renodx.git external/renodx

# Or as a submodule:

git submodule add https://github.com/clshortfuse/renodx.git external/renodx

Step-by-Step Integration Process

Add RenoDX as a CMake Subdirectory

In your project’s CMakeLists.txt, add RenoDX as a subdirectory and link the renodx target:

cmake_minimum_required(VERSION 3.21)
project(MyRenoDXMod LANGUAGES CXX)

add_subdirectory("external/renodx" EXCLUDE_FROM_ALL)

add_library(my_mod SHARED my_mod.cpp)
target_link_libraries(my_mod PRIVATE renodx)
target_include_directories(my_mod PRIVATE "${CMAKE_CURRENT_SOURCE_DIR}/external/renodx/src")

The renodx target exposes all necessary include paths and compiler definitions required for Reshade add-on development.

Include Required Headers

In your add-on source file, include the specific RenoDX modules you need:

#include <renodx/mods/shader.hpp>
#include <renodx/mods/swapchain.hpp>
#include <renodx/utils/settings.hpp>  // Optional: for runtime UI

These headers define the public API surface for shader injection and swapchain proxying.

Implement the Add-on Entry Point

Every RenoDX add-on must export an initialization function. Register your custom shaders in the global custom_shaders concurrent hash map:

extern "C" __declspec(dllexport) bool RENODX_API InitAddon()
{
    // Register a custom shader by CRC32 hash
    renodx::mods::shader::custom_shaders.emplace(
        0x12345678, 
        renodx::mods::shader::CreateCustomShader(
            0x12345678, 
            {shader_bytecode, sizeof(shader_bytecode)}
        )
    );
    
    // Enable custom shader replacement globally
    renodx::mods::shader::using_custom_replace = true;
    
    return true;
}

The RENODX_API macro ensures proper symbol visibility for Reshade’s loader.

Build and Deploy the Add-on

Configure your output name to match Reshade’s convention:

set_target_properties(my_mod PROPERTIES
    OUTPUT_NAME "my_mod.addon64"
    RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}"
)

Build your project, then copy my_mod.addon64 to the game’s Reshade addons folder. Enable the add-on through the Reshade in-game UI to activate RenoDX integration.

Minimal Working Example

Below is a complete, runnable example that injects a color-inverting pixel shader into every pipeline creation. This demonstrates how to integrate RenoDX with other projects using the shader modification API.

// my_mod.cpp
#include <renodx/mods/shader.hpp>

// Compiled SPIR-V or DXIL bytecode for a simple invert shader
static constexpr uint8_t invert_shader_code[] = {
    /* ... shader bytes ... */
};

static const renodx::mods::shader::CustomShader g_invert_shader = 
    renodx::mods::shader::CreateCustomShader(
        0xDEADBEEF, 
        {invert_shader_code, sizeof(invert_shader_code)}
    );

extern "C" __declspec(dllexport) bool RENODX_API InitAddon()
{
    // Insert into global registry defined in src/mods/shader.hpp
    renodx::mods::shader::custom_shaders.emplace(
        g_invert_shader.crc32, 
        g_invert_shader
    );
    
    renodx::mods::shader::using_custom_replace = true;
    return true;
}

When this .addon64 file loads, RenoDX intercepts OnCreatePipelineLayout calls and injects your shader whenever the CRC32 hash matches a game shader.

Key Source Files for Integration Reference

When integrating RenoDX with other projects, reference these specific source files to understand implementation details:

• src/mods/shader.hpp – Defines CustomShader struct, CreateCustomShader function, and OnCreatePipelineLayout hooks for pipeline injection.
• src/mods/swapchain.hpp – Entry point for swapchain versioning; selects between v1 and v2 implementations via RENO_DX_MODS_SWAPCHAIN_VERSION macro.
• src/mods/swapchain_v2.hpp – Modern swapchain proxy with HDR resource upgrade support.
• src/utils/settings.hpp – Implements renodx::utils::settings::Setting for runtime UI configuration.
• src/games/zelda-eow/addon.cpp – Production example showing shader injection, swapchain upgrades, and settings UI integration.
• docs/DEVKIT_MCP.md – Documentation for the devkit and MCP bridge tools used to debug shader injection failures.

Summary

• RenoDX integration requires adding the repository as a CMake subdirectory and linking the renodx target.
• Shader injection works by creating CustomShader objects and registering them in renodx::mods::shader::custom_shaders before returning from InitAddon.
• Swapchain upgrades are handled automatically by including renodx/mods/swapchain.hpp and selecting the appropriate version macro.
• Deployment involves compiling to a .addon64 (or .addon32) file and placing it in Reshade’s addons directory.
• Debugging is supported via the devkit add-on and MCP bridge referenced in docs/DEVKIT_MCP.md.

Frequently Asked Questions

Do I need to modify game source code to use RenoDX?

No. RenoDX operates entirely through Reshade’s add-on API. You compile a standalone .addon64 file that Reshade loads at game startup. The framework intercepts graphics API calls via OnCreatePipelineLayout and other hooks defined in src/mods/shader.hpp, requiring no changes to the original game executable.

Can I use RenoDX with Vulkan games or only DirectX?

RenoDX supports both. The APIs in src/mods/shader.hpp and src/mods/swapchain.hpp are graphics-API agnostic. The OnCreatePipelineLayout implementation handles device_api::vulkan alongside DirectX 9/11/12, allowing your add-on to inject shaders into Vulkan games using the same codebase.

How do I conditionally enable my custom shader for specific pipelines?

Provide an on_replace or on_inject callback when constructing your CustomShader. Return false from the callback to skip injection for specific pipelines. The reference implementation in src/games/zelda-eow/addon.cpp demonstrates checking the shader’s CRC32 hash within these callbacks to filter targets dynamically.

What is the difference between swapchain v1 and v2, and which should I use?

Swapchain v2 (src/mods/swapchain_v2.hpp) is the modern implementation supporting HDR resource upgrades and improved proxy handling, while v1 provides legacy compatibility. Set RENO_DX_MODS_SWAPCHAIN_VERSION to 2 in your CMake configuration or source to enable v2. Unless you require backward compatibility with older RenoDX add-ons, v2 is recommended for new projects integrating with DirectX 12 or Vulkan.

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