Crate hudhook

source ·
Expand description

§hudhook

This library implements a mechanism for hooking into the render loop of applications and drawing things on screen via dear imgui.

Currently, DirectX9, DirectX 11, DirectX 12 and OpenGL 3 are supported.

For complete, fully fledged examples of usage, check out the following projects:

It is a good idea to refer to these projects for any doubts about the API which aren’t clarified by this documentation, as this project is directly derived from them.

Refer to this post for in-depth information about the architecture of the library.

A tutorial book is also available, with end-to-end examples.

§Fair warning

hudhook provides essential, crash-safe features for memory manipulation and UI rendering. It does, alas, contain a hefty amount of FFI and unsafe code which still has to be thoroughly tested, validated and audited for soundness. It should be OK for small projects such as videogame mods, but it may crash your application at this stage.

§Examples

§Hooking the render loop and drawing things with imgui

Compile your crate with both a cdylib and an executable target. The executable will be very minimal and used to inject the DLL into the target process.

§Building the render loop

Implement the render loop trait for your hook target.

§Example

Implement the ImguiRenderLoop trait:

// lib.rs
use hudhook::*;

pub struct MyRenderLoop;

impl ImguiRenderLoop for MyRenderLoop {
    fn render(&mut self, ui: &mut imgui::Ui) {
        ui.window("My first render loop")
            .position([0., 0.], imgui::Condition::FirstUseEver)
            .size([320., 200.], imgui::Condition::FirstUseEver)
            .build(|| {
                ui.text("Hello, hello!");
            });
    }
}

{
    // Use this if hooking into a DirectX 9 application.
    use hudhook::hooks::dx9::ImguiDx9Hooks;
    hudhook!(ImguiDx9Hooks, MyRenderLoop);
}

{
    // Use this if hooking into a DirectX 11 application.
    use hudhook::hooks::dx11::ImguiDx11Hooks;
    hudhook!(ImguiDx11Hooks, MyRenderLoop);
}

{
    // Use this if hooking into a DirectX 12 application.
    use hudhook::hooks::dx12::ImguiDx12Hooks;
    hudhook!(ImguiDx12Hooks, MyRenderLoop);
}

{
    // Use this if hooking into a OpenGL 3 application.
    use hudhook::hooks::opengl3::ImguiOpenGl3Hooks;
    hudhook!(ImguiOpenGl3Hooks, MyRenderLoop);
}
§Injecting the DLL

You can use the facilities in inject in your binaries to inject the DLL in your target process.

// main.rs
use hudhook::inject::Process;

fn main() {
    let mut cur_exe = std::env::current_exe().unwrap();
    cur_exe.push("..");
    cur_exe.push("libmyhook.dll");

    let cur_dll = cur_exe.canonicalize().unwrap();

    Process::by_name("MyTargetApplication.exe").unwrap().inject(cur_dll).unwrap();
}

Re-exports§

  • pub use windows;
  • pub use imgui;
  • pub use tracing;

Modules§

  • hooks
    Implementations of render engine hooks.
  • inject
    Facilities for injecting compiled DLLs into target processes.
  • mh
    Thin FFI wrapper around minhook.
  • util
    General-purpose utilities. These are used across the crate but have proven useful in client code as well.

Macros§

  • hudhook
    Entry point generator for the library.

Structs§

Traits§

  • Hooks
    Generic trait for platform-specific hooks.
  • ImguiRenderLoop
    Implement your imgui rendering logic via this trait.
  • RenderContext
    Texture Loader for ImguiRenderLoop callbacks to load and replace textures

Functions§