hdr-helper

Linux script to control and automatically toggle HDR on KDE Plasma.

I've personally tested this on Fedora 41 Plasma Edition on an RX 6800XT using the standard RADV drivers which are built into the Linux Kernel. I only have one display, I've not accounted for multi-display scenarios so please take this into consideration :)

The Problem

At this moment in time, pretty much all games require HDR to be manually enabled for it to properly function. Normally this isn't a problem when using Gamescope as your native compositor. Most normal people however run a fully fledged desktop environment on their PCs unless they're using SteamOS or Bazzite.

This can be annoying because running Gamescope from within KDE Plasma with the HDR flag enabled still won't magically make HDR work, unless it's also enabled from your compositor's side too; in this case, KWin. Although KWin has a way to enable HDR from the command line, the implementation is flawed as most monitors will only properly display HDR prior to switching video modes. In other words, the HDR signal must be present BEFORE HDR-compatible monitors will recognise what to do; this happens usually once the monitor is forced to change resolution or refresh rate.

The Solution

I've created a script which will toggle HDR from KDE Plasma's in-built kscreen-doctor helper and also force change video modes. This means that whenever you launch a HDR-compatible game, you won't ever need to manually enable HDR again since this script can be used as a launch parameter for Steam and third party apps. Of course you may also call this script manually and force HDR to be on or off if you so desire.

Some configuration is required!

---

Setup

Simply copy the script to a location within your $PATH for ease of access, such as ~/.local/usr/bin.

-OR-

You may also clone this respository and create a symbolic link to the file to receive any future updates:

git clone https://github.com/dunestorm333/hdr-helper.git
cd hdr-helper
ln -s hdr-helper ~/.local/usr/bin/
chmod +x ~/.local/usr/bin/hdr-helper

You will then need to modify the following three values within the script specific to your system configuration:

# MONITOR=<DP-1 | Enter your monitor ID from xrandr>
# NATIVE_RES=<3440x1440@165 | Enter your native monitor resolution followed by the refresh rate>
# TEMP_RES=<2560x1440@144 | Enter a different resolution or refresh rate from your native>

xrandr will give you the following output; in the below example DP-3 is the value we need to use to target the active monitor.

Screen 0: minimum 16 x 16, current 3440 x 1440, maximum 32767 x 32767
DP-3 connected primary 3440x1440+0+0 (normal left inverted right x axis y axis) 800mm x 337mm
...

Below is an example of the help output of the script:

--- Usage ---
hdr-helper    | The default behaviour will automatically enable or disable HDR
hdr-helper -e | Force enables HDR
hdr-helper -d | Force disables HDR
hdr-helper -s | Shows detected HDR status as a system notification
hdr-helper -v | Displays version information
hdr-helper -h | Displays this help screen

--- Info ---
Currently only KDE Plasma is supported running Wayland. Ensure that kscreen-doctor
is present on your system for HDR Helper to function.

--- Config ---
Please modify the MONITOR, NATIVE_RES and TEMP_RES values in this script.

Usage

Using with Steam & Gamescope

Firstly, ensure that Gamescope is installed and working. From Steam, right click on the game you'd like to automatically enable HDR for and click on Properties...

Now enter the below command into the launch options:

Effectively what we're doing here is affixing and suffixing the standard Gamescope launch commands with hdr-helper.

hdr-helper ; gamescope -W 3440 -H 1440 -r 165 -f --hdr-enabled -- %command% ; hdr-helper

Using with standalone Apps & Gamescope

The commands you need to get this working with pretty much any app or game is very similar to the Steam method. Note that in both cases, Gamescope is required as HDR requires a valid HDR layer and compositior to properly function in addition to working drivers.

hdr-helper; gamescope -W 3440 -w 1920 -H 1440 -h 1080 -r 165 -f --hdr-enabled ~/my-app-or-game; hdr-helper

Manual Approach

If you'd like to manually bind HDR Helper to a shotcut key for example, this can easily by configured in most desktop enviornments.

Using KDE Plasma, you may do this from the System Shortcuts page. Click Add New > Command or Script...

Now specify the hdr-helper command in the command field and give the shortcut a name.

You may now assign a key-combination to toggle the shortcut. Remember to click Apply when done!