2020-01-28 04:11:05 +00:00
# MangoHud
2020-05-18 10:40:05 +00:00
A Vulkan and OpenGL overlay for monitoring FPS, temperatures, CPU/GPU load and more.
2020-01-28 04:11:05 +00:00
2020-02-04 11:00:15 +00:00
#### Example:
2020-01-28 04:11:05 +00:00
# Installation
2020-01-28 07:39:49 +00:00
2020-03-14 18:52:23 +00:00
## Build
2020-02-04 10:30:40 +00:00
If you wish to compile MangoHud to keep up to date with any changes - first clone this repository and cd into it:
2020-01-28 07:39:49 +00:00
2020-01-29 11:17:30 +00:00
```
git clone --recurse-submodules https://github.com/flightlessmango/MangoHud.git
cd MangoHud
```
2020-01-28 07:39:49 +00:00
2020-03-14 18:52:23 +00:00
To build it, execute:
2020-01-28 07:39:49 +00:00
2020-03-14 18:52:23 +00:00
```
./build.sh build
./build.sh package
```
2020-03-16 20:43:42 +00:00
**NOTE: If you are running an Ubuntu-based, Arch-based, Fedora-based, or openSUSE-based distro, the build script will automatically detect and prompt you to install missing build dependencies. If you run into any issues with this please report them!**
2020-03-14 18:52:23 +00:00
Once done, proceed to the [installation ](#source ).
2020-01-28 04:11:05 +00:00
2020-03-14 18:52:23 +00:00
## Install
2020-02-04 10:30:40 +00:00
2020-03-14 18:52:23 +00:00
### Source
If you have compiled MangoHud from source, to install it, execute:
```
2020-03-14 19:19:50 +00:00
./build.sh install
2020-03-14 18:52:23 +00:00
```
2020-02-04 10:30:40 +00:00
2020-06-11 14:20:37 +00:00
You can then subsequently uninstall MangoHud via the following command
```
./build.sh uninstall
```
2020-03-14 18:52:23 +00:00
### Pre-packaged binaries
2020-02-20 15:31:30 +00:00
2020-03-14 18:52:23 +00:00
#### GitHub releases
2020-02-20 15:31:30 +00:00
2020-06-18 10:07:08 +00:00
If you do not wish to compile anything, simply download the file under [Releases ](https://github.com/flightlessmango/MangoHud/releases ), extract it, and from within the extracted folder in terminal, execute:
```
./mangohud-setup.sh install
```
2020-03-14 18:52:23 +00:00
#### Arch-based distributions
2020-03-14 18:54:07 +00:00
If you are using an Arch-based distribution, install [`mangohud` ](https://aur.archlinux.org/packages/mangohud/ ) and [`lib32-mangohud` ](https://aur.archlinux.org/packages/lib32-mangohud/ ) with your favourite AUR helper. [`mangohud-git` ](https://aur.archlinux.org/packages/mangohud-git/ ) and [`lib32-mangohud-git` ](https://aur.archlinux.org/packages/lib32-mangohud-git/ ) are also available on the AUR if you want the up-to-date version of MangoHud.
2020-03-14 18:52:23 +00:00
2021-04-25 21:44:26 +00:00
#### Debian 11 (Bullseye)
If you are using Debian 11 or later, to install the [MangoHud ](https://tracker.debian.org/pkg/mangohud ) package, execute:
```
sudo apt install mangohud
```
Optionally, if you also need MangoHud for 32-bit applications, execute:
```
sudo apt install mangohud:i386
```
2020-03-14 18:52:23 +00:00
#### Fedora
If you are using Fedora, to install the [MangoHud ](https://src.fedoraproject.org/rpms/mangohud ) package, execute:
```
sudo dnf install mangohud
```
2020-02-23 12:45:07 +00:00
2020-10-14 17:47:08 +00:00
#### Solus
If you are using Solus, to install [MangoHud ](https://dev.getsol.us/source/mangohud/ ) simply execute:
```
sudo eopkg it mangohud
```
2020-03-14 19:00:16 +00:00
#### Flatpak
2020-03-14 18:56:08 +00:00
2020-03-15 11:45:01 +00:00
If you are using Flatpaks, you will have to add the [Flathub repository ](https://flatpak.org/setup/ ) for your specific distribution, and then, to install it, execute:
2020-03-14 18:56:08 +00:00
2020-03-15 11:45:01 +00:00
##### For Steam flatpak
2020-03-14 18:56:08 +00:00
```
2020-03-23 13:11:20 +00:00
flatpak install com.valvesoftware.Steam.Utility.MangoHud
2020-03-14 18:56:08 +00:00
```
2020-03-15 11:45:01 +00:00
To enable MangoHud for all Steam games:
```
flatpak override --user --env=MANGOHUD=1 com.valvesoftware.Steam
```
2020-03-14 18:56:08 +00:00
2020-01-28 04:11:05 +00:00
# Normal usage
2020-08-25 17:22:20 +00:00
To enable the MangoHud overlay layer for Vulkan and OpenGL, run :
2020-01-28 04:11:05 +00:00
2020-03-14 15:34:37 +00:00
`mangohud /path/to/app`
2020-01-28 04:11:05 +00:00
2020-05-11 21:58:19 +00:00
For Lutris games, go to the System options in Lutris (make sure that advanced options are enabled) and add this to the `Command prefix` setting:
`mangohud`
2020-03-14 15:34:37 +00:00
For Steam games, you can add this as a launch option:
`mangohud %command%`
Or alternatively, add `MANGOHUD=1` to your shell profile (Vulkan only).
2020-01-28 04:11:05 +00:00
2020-05-11 17:34:39 +00:00
## OpenGL
2020-05-11 17:35:34 +00:00
OpenGL games may also need `dlsym` hooking. Add `MANGOHUD_DLSYM=1` to your command like `MANGOHUD_DLSYM=1 mangohud %command%` for Steam.
2020-05-11 17:34:39 +00:00
Some Linux native OpenGL games overrides LD_PRELOAD and stops MangoHud from working. You can sometimes fix this by editing LD_PRELOAD in the start script
2020-05-23 21:59:56 +00:00
`LD_PRELOAD=/path/to/mangohud/lib/`
2020-02-12 22:17:32 +00:00
## Hud configuration
MangoHud comes with a config file which can be used to set configuration options globally or per application. The priorities of different config files are:
1. `/path/to/application/dir/MangoHud.conf`
2. `$HOME/.config/MangoHud/{application_name}.conf`
3. `$HOME/.config/MangoHud/MangoHud.conf`
2020-03-14 16:12:58 +00:00
You can find an example config in /usr/share/doc/mangohud
2020-02-12 22:17:32 +00:00
2020-04-15 05:24:57 +00:00
[GOverlay ](https://github.com/benjamimgois/goverlay ) is a GUI application that can be used to manage the config
2020-02-12 22:17:32 +00:00
---
2020-03-28 21:59:54 +00:00
### `MANGOHUD_CONFIG` and `MANGOHUD_CONFIGFILE` environment variables
2020-02-12 22:17:32 +00:00
You can also customize the hud by using the `MANGOHUD_CONFIG` environment variable while separating different options with a comma. This takes priority over any config file.
2020-03-28 21:59:54 +00:00
You can also specify configuration file with `MANGOHUD_CONFIGFILE=/path/to/config` for applications whose names are hard to guess (java, python etc).
2020-02-12 22:17:32 +00:00
A partial list of parameters are below. See the config file for a complete list.
2020-06-29 19:24:08 +00:00
Parameters that are enabled by default have to be explicitly disabled. These (currently) are `fps` , `frame_timing` , `cpu_stats` (cpu load), `gpu_stats` (gpu load).
2020-02-12 22:17:32 +00:00
| Variable | Description |
|------------------------------------|---------------------------------------------------------------------------------------|
| `cpu_temp` < br > `gpu_temp` | Displays current CPU/GPU temperature |
| `core_load` | Displays load & frequency per core |
2020-05-03 15:45:07 +00:00
| `gpu_core_clock` < br > `gpu_mem_clock`| Displays GPU core/memory frequency |
2020-02-12 22:17:32 +00:00
| `ram` < br > `vram` | Displays system RAM/VRAM usage |
2020-06-29 19:24:08 +00:00
| `full` | Enables most of the toggleable parameters (currently excludes `histogram` ) |
2020-02-12 22:17:32 +00:00
| `font_size=` | Customizeable font size (default=24) |
2020-06-29 14:15:50 +00:00
| `font_size_text=` | Customizeable font size for other text like media metadata (default=24) |
| `font_scale=` | Set global font scale (default=1.0) |
| `font_file` | Change default font (set location to .TTF/.OTF file ) |
| `font_file_text` | Change text font. Otherwise `font_file` is used |
| `font_glyph_ranges` | Specify extra font glyph ranges, comma separated: `korean` , `chinese` , `chinese_simplified` , `japanese` , `cyrillic` , `thai` , `vietnamese` , `latin_ext_a` , `latin_ext_b` . If you experience crashes or text is just squares, reduce font size or glyph ranges. |
2020-09-23 11:02:27 +00:00
| `no_small_font` | Use primary font size for smaller text like units |
2020-02-12 22:17:32 +00:00
| `width=` < br > `height=` | Customizeable hud dimensions (in pixels) |
2020-05-17 15:59:14 +00:00
| `position=` | Location of the hud: `top-left` (default), `top-right` , `bottom-left` , `bottom-right` , `top-center` |
2020-05-02 16:40:24 +00:00
| `offset_x` `offset_y` | Hud position offsets |
2020-02-12 22:17:32 +00:00
| `no_display` | Hide the hud by default |
2020-06-10 18:31:35 +00:00
| `toggle_hud=` < br > `toggle_logging=` | Modifiable toggle hotkeys. Default are `Shift_R+F12` and `Shift_L+F2` , respectively. |
2020-05-17 12:45:31 +00:00
| `reload_cfg=` | Change keybind for reloading the config. Default = `Shift_L+F4` |
2020-06-29 19:24:08 +00:00
| `time` < br > `time_format=%T` | Displays local time. See [std::put_time ](https://en.cppreference.com/w/cpp/io/manip/put_time ) for formatting help. NOTE: Sometimes apps (or AMDVLK (should be fixed in latest)) may set `TZ` (timezone) environment variable to UTC/GMT |
2020-05-11 19:01:40 +00:00
| `gpu_color` < br > `gpu_color`< br > `vram_color`< br > `ram_color`< br > `io_color`< br > `engine_color`< br > `frametime_color`< br > `background_color`< br > `text_color`< br > `media_player_color` | Change default colors: `gpu_color=RRGGBB` |
2020-03-11 05:15:04 +00:00
| `alpha` | Set the opacity of all text and frametime graph `0.0-1.0` |
| `background_alpha` | Set the opacity of the background `0.0-1.0` |
2020-03-13 13:40:37 +00:00
| `read_cfg` | Add to MANGOHUD_CONFIG as first parameter to also load config file. Otherwise only MANGOHUD_CONFIG parameters are used. |
2020-08-16 13:07:00 +00:00
| `output_folder` | Set location of the output files (Required for logging) |
2020-03-13 15:27:45 +00:00
| `log_duration` | Set amount of time the logging will run for (in seconds) |
2020-03-13 16:16:17 +00:00
| `vsync` < br > `gl_vsync` | Set vsync for OpenGL or Vulkan |
2020-05-11 19:01:40 +00:00
| `media_player` | Show media player metadata |
2020-07-16 11:35:34 +00:00
| `media_player_name` | Force media player DBus service name without the `org.mpris.MediaPlayer2` part, like `spotify` , `vlc` , `audacious` or `cantata` . If none is set, MangoHud tries to switch between currently playing players. |
2020-06-13 19:00:36 +00:00
| `media_player_order` | Media player metadata field order. Defaults to `title,artist,album` . |
2020-06-20 16:53:17 +00:00
| `font_scale_media_player` | Change size of media player text relative to font_size |
2020-05-02 17:23:07 +00:00
| `io_read` < br > `io_write` | Show non-cached IO read/write, in MiB/s |
2020-05-02 14:49:38 +00:00
| `pci_dev` | Select GPU device in multi-gpu setups |
2020-05-02 16:40:24 +00:00
| `version` | Shows current mangohud version |
2020-09-19 10:19:20 +00:00
| `fps_limit` | Limit the apps framerate. Comma-separated list of one or more FPS values. `0` means unlimited. |
| `toggle_fps_limit` | Cycle between FPS limits. Defaults to `Shift_L+F1` . |
2020-05-03 15:45:07 +00:00
| `arch` | Show if the application is 32 or 64 bit |
2020-05-24 15:18:12 +00:00
| `histogram` | Change fps graph to histogram |
2020-06-01 00:09:32 +00:00
| `cpu_text` < br > `gpu_text` | Override CPU and GPU text |
2020-06-03 22:54:47 +00:00
| `log_interval` | Change the default log interval, `100` is default |
2020-06-10 06:02:16 +00:00
| `vulkan_driver` | Displays used vulkan driver, radv/amdgpu-pro/amdvlk |
| `gpu_name` | Displays GPU name from pci.ids |
2020-11-12 21:27:35 +00:00
| `cpu_power` < br > `gpu_power` | Display CPU/GPU draw in watts |
2020-06-11 13:25:05 +00:00
| `engine_version` | Display OpenGL or vulkan and vulkan-based render engine's version |
2020-06-19 15:50:20 +00:00
| `permit_upload` | Allow uploading of logs to Flightlessmango.com |
| `upload_log` | Change keybind for uploading log |
2020-11-27 21:58:09 +00:00
| `benchmark_percentiles` | Configure which framerate percentiles are shown in the logging summary. Default is `97,AVG,1,0.1` |
2020-08-16 13:07:00 +00:00
| `wine` | Shows current Wine or Proton version in use |
| `wine_color` | Change color of the wine/proton text |
2020-11-13 21:22:01 +00:00
| `cpu_mhz` | Shows the CPUs current MHz |
| `gpu_load_change` | Changes the color of the GPU load depending on load |
2020-11-27 21:58:09 +00:00
| `gpu_load_color` | Set the colors for the gpu load change low,medium and high. e.g `gpu_load_color=0000FF,00FFFF,FF00FF` |
| `gpu_load_value` | Set the values for medium and high load e.g `gpu_load_value=50,90` |
2020-11-13 21:22:01 +00:00
| `cpu_load_change` | Changes the color of the CPU load depending on load |
2020-11-27 21:58:09 +00:00
| `cpu_load_color` | Set the colors for the gpu load change low,medium and high. e.g `cpu_load_color=0000FF,00FFFF,FF00FF` |
| `cpu_load_value` | Set the values for medium and high load e.g `cpu_load_value=50,90` |
2020-11-16 11:53:38 +00:00
| `cellpadding_y` | Set the vertical cellpadding, default is `-0.085` |
2020-11-16 23:37:03 +00:00
| `frametime` | Display frametime next to fps text |
2020-11-17 14:09:15 +00:00
| `table_columns` | Set the number of table columns for ImGui, defaults to 3 |
2020-11-27 21:58:09 +00:00
| `blacklist` | Add a program to the blacklist. e.g `blacklist=vkcube,WatchDogs2.exe` |
2020-11-13 21:22:01 +00:00
2020-03-13 15:50:26 +00:00
Example: `MANGOHUD_CONFIG=cpu_temp,gpu_temp,position=top-right,height=500,font_size=32`
2020-11-27 22:14:32 +00:00
Because comma is also used as option delimiter and needs to be escaped for values with a backslash, you can use `+` like `MANGOHUD_CONFIG=fps_limit=60+30+0` instead.
2020-01-28 04:11:05 +00:00
Note: Width and Height are set automatically based on the font_size, but can be overridden.
2020-11-29 16:30:40 +00:00
2021-02-03 01:33:03 +00:00
Note: RAPL is currently used for Intel CPUs to show power draw with `cpu_power` which may be unreadable for non-root users due to [vulnerability ](https://platypusattack.com/ ). The corresponding `energy_uj` file has to be readable by corresponding user, e.g. by running `chmod o+r /sys/class/powercap/intel-rapl\:0/energy_uj` as root, else the power shown will be *0 W* , though having the file readable may potentially be a security vulnerability persisting until system reboots.
2020-03-13 15:50:26 +00:00
## Vsync
### OpenGL Vsync
- `-1` = Adaptive sync
- `0` = Off
- `1` = On
2020-03-13 16:07:57 +00:00
- `n` = Sync to refresh rate / n.
2020-03-13 15:50:26 +00:00
### Vulkan Vsync
2020-05-23 22:55:04 +00:00
- `0` = Adaptive VSync (FIFO_RELAXED_KHR)
- `1` = Off (IMMEDIATE_KHR)
- `2` = Mailbox (VSync with uncapped FPS) (MAILBOX_KHR)
- `3` = On (FIFO_KHR)
2020-01-28 04:11:05 +00:00
2020-05-23 22:55:04 +00:00
All vulkan vsync options might not be supported on your device, you can check what your device supports here [vulkan.gpuinfo.org ](https://vulkan.gpuinfo.org/listsurfacepresentmodes.php?platform=linux )
2020-01-28 04:11:05 +00:00
## Keybindings
2020-01-28 07:39:49 +00:00
2020-06-10 08:37:49 +00:00
- `Shift_L+F2` : Toggle Logging
- `Shift_L+F4` : Reload Config
- `Shift_R+F12` : Toggle Hud
2020-01-28 04:11:05 +00:00
2020-01-28 07:39:49 +00:00
## MangoHud FPS logging
2020-01-28 04:11:05 +00:00
2020-09-08 07:20:34 +00:00
You must set a valid path for `output_folder` in your configuration to store logs in.
2020-01-28 04:11:05 +00:00
2020-09-08 07:21:32 +00:00
When you toggle logging (using the keybind `Shift_L+F2` ), a file is created with the game name plus a date & timestamp in your `output_folder` .
2020-09-08 07:20:34 +00:00
Log files can be uploaded to [Flightlessmango.com ](https://flightlessmango.com/games/user_benchmarks ) to create graphs automatically.
You can share the created page with others, just link it.
2020-01-28 04:11:05 +00:00
#### Multiple log files
It's possible to upload multiple files when using [Flightlessmango.com ](https://flightlessmango.com/games/user_benchmarks ). You can rename them to your preferred names and upload them in a batch.
These filenames will be used as the legend in the graph.
#### Log uploading walkthrough
