How Linux Implements MangoHud for Vulkan and OpenGL

MangoHud is an open-source performance monitoring overlay for Linux that tracks frame rates, frame times, system temperatures, and hardware utilization in real time. Unlike traditional game overlays that rely on invasive code modification, Linux implements MangoHud by leveraging native graphics API extension architectures and dynamic linker preloading to intercept rendering pipelines. This article details the underlying mechanisms Linux uses to inject MangoHud into Vulkan and OpenGL processes, gather kernel-level telemetry, and display a customizable overlay.

Vulkan Implementation via API Layers

The Vulkan graphics API natively supports a layered architecture designed for debugging, validation, and feature injection. Linux executes MangoHud within Vulkan applications through the Vulkan Loader's layer system.

When MangoHud is installed, it places a JSON manifest file into standard Vulkan layer directories, such as /usr/share/vulkan/implicit_layer.d/ or ~/.local/share/vulkan/implicit_layer.d/. This manifest identifies MangoHud's shared library (libMangoHud.so) and defines it as an implicit layer. When a Vulkan instance initializes, the Vulkan loader parses these manifests. If triggered—either via environment variables like MANGOHUD=1 or direct application enablement—the loader inserts MangoHud into the call chain.

MangoHud hooks directly into swapchain operations, specifically intercepting the vkQueuePresentKHR function. Intercepting this function allows MangoHud to compute precise frame timings right before an image is presented to the screen. Before the presentation completes, MangoHud injects its own render pass containing the overlay elements onto the current swapchain image using an embedded rendering engine powered by Dear ImGui.

OpenGL Implementation via Dynamic Preloading

OpenGL lacks the native, standardized layering mechanism found in Vulkan. To achieve the same functionality in OpenGL applications, the Linux OS utilizes dynamic linker preloading via the LD_PRELOAD environment variable.

When launching a game with the mangohud wrapper script, the system sets LD_PRELOAD to load libMangoHud_opengl.so before any other dynamic shared libraries are linked to the executable. By doing so, MangoHud wraps and intercepts the platform-specific display system calls responsible for swapping frame buffers:

• GLX Applications (X11): Intercepts glXSwapBuffers.
• EGL Applications (Wayland or Modern X11): Intercepts eglSwapBuffers.

During each intercepted buffer swap, MangoHud measures the delta between frames, computes frame rate data, binds its internal Dear ImGui context, renders the overlay elements into the active OpenGL context, and finally invokes the real underlying swap function to display the frame.

Telemetry Acquisition from the Linux Kernel

To display hardware metrics without causing significant CPU overhead or input latency, MangoHud reads data directly from Linux virtual filesystems and platform-specific vendor APIs:

• CPU Metrics: MangoHud parses /proc/stat to calculate overall and per-core CPU utilization. CPU temperatures and frequencies are read directly from the sysfs filesystem under /sys/class/hwmon/ and /sys/devices/system/cpu/.
• AMD and Intel GPUs: Metrics such as VRAM usage, GPU core clocks, power consumption, and temperatures are collected via the Direct Rendering Manager (DRM) interfaces located in /sys/class/drm/cardX/device/.
• NVIDIA GPUs: Because proprietary NVIDIA drivers do not fully expose telemetry through standard hwmon nodes, MangoHud dynamically interfaces with the NVIDIA Management Library (NVML) to poll temperature, clock speeds, and memory consumption.

These reads occur on dedicated, throttled worker threads asynchronously to prevent blocking the application's render thread.

Configuration and Runtime Customization

Customization in MangoHud is handled decoupled from the graphics rendering code. At initialization, MangoHud looks for plain-text configuration files in hierarchical order:

1. Application-specific configurations in ~/.config/MangoHud/<application_name>.conf
2. Global user configuration in ~/.config/MangoHud/MangoHud.conf
3. Environment variables passed at execution, such as MANGOHUD_CONFIG

The configuration parser controls parameters such as displayed parameters (e.g., FPS, GPU load, CPU temp), placement coordinates, fonts, color thresholds, and hotkey listeners. Hotkeys are processed via input hooks that allow users to toggle the HUD visibility, benchmark logging, or change detail levels on the fly without restarting the graphics application.