117 lines
5.4 KiB
Markdown
117 lines
5.4 KiB
Markdown
# hdr-helper 💻
|
|
Linux script to control and automatically toggle HDR on KDE Plasma.
|
|
|
|
|
|
|
|
I've personally tested this on Fedora 41 & 42, and Arch Linux (all running the Plasma DE) 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 :)
|
|
|
|
## Supported Features 📋
|
|
- Automatically & manually toggling HDR on and off.
|
|
- Notifying you whether HDR has been successfully activated.
|
|
- Setting a target SDR brightness level whilst in HDR mode.
|
|
- Setting a target SDR to HDR coversion brightness level in nits.
|
|
- Your original non-HDR brightness level will be preserved when switching back.
|
|
|
|
# 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 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
|
|
after also changing 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
|
|
To start with, clone this repository and create a symbolic link to the file:
|
|
```bash
|
|
git clone https://github.com/dunestorm333/hdr-helper.git
|
|
cd hdr-helper
|
|
chmod +x hdr-helper
|
|
|
|
# For Fedora based distros (more portable)
|
|
mkdir ~/.local/bin/
|
|
ln -s $PWD/hdr-helper ~/.local/bin/
|
|
# For Arch based distros (more compatible)
|
|
sudo ln -s $PWD/hdr-helper /usr/bin/
|
|
|
|
# You will also need to copy monitor.conf into ~/.config/hdr-helper
|
|
mkdir ~/.config/hdr-helper
|
|
cp monitor.conf ~/.config/hdr-helper
|
|
```
|
|
|
|
**Ensure to modify `monitor.conf` with your desired settings.**
|
|
|
|
`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 monitor.conf.
|
|
```
|
|
|
|
# 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`.
|
|
``` bash
|
|
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 compositor to properly function in addition to working drivers.
|
|
``` bash
|
|
hdr-helper; gamescope -W 3440 -H 1440 -r 165 -f --hdr-enabled ~/my-app-or-game; hdr-helper
|
|
```
|
|
## Manual Approach
|
|
If you'd like to manually bind HDR Helper to a shortcut key for example, this can easily by configured in most desktop environments.
|
|
|
|
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!
|
|
|
|
|
|
|