HDR - ArchWiki

Jump to content

# HDR

From ArchWiki

Related articles

- Steam
- Gaming
- Gamescope

High-dynamic range (HDR) is supported by Wayland's Color management and HDR protocol, and some compositors have implemented it. X.org has no plans to support HDR.

## Requirements

- HDR-capable display
  - While many displays advertise HDR support, many may provide a suboptimal experience if they lack any form of local dimming. More information is available at RTINGS: Local Dimming on TVs.
- HDR-capable GPU and driver
  - AMDGPU and NVIDIA are both supported
  - Intel graphics has experimental HDR support with Gen 9 and newer
    - The implementation is reportedly incomplete.
- Supported compositor
- Supported application
- Vulkan WSI with HDR support

### Vulkan HDR WSI

`VK_EXT_swapchain_colorspace` and `VK_EXT_hdr_metadata` extensions are required for HDR support when using the Vulkan API.

- mesa 25.1 and later includes these extensions by default.
- nvidia-open 595.58.03 and later also includes these extensions by default.
  - NVIDIA users on drivers before 595.58.03 must install vk-hdr-layer-kwin6-gitAUR and set `ENABLE_HDR_WSI=1` in each game or application that will be used with HDR. Enabling this globally is not recommended.

## Compositor configuration

### KDE Plasma

See KDE#HDR.

### Hyprland

Hyprland >= 0.55 will automatically switch to HDR mode in its default configuration, when the monitor and fullscreen content support it. To use HDR on the desktop you must set `cm = "hdr"` and `bitdepth = 10` in your monitor configuration like so:

    hl.monitor({
        -- ...
        bitdepth = 10,
        cm = "hdr",
    })

Additional settings can be found on the Hyprland wiki: monitor color management, render variables.

### GNOME

Ensure mutter is >= 48.0.

Enable HDR in GNOME's display settings. The HDR toggle is per-monitor and is located next to the resolution and refresh rate setting.

Note Gamescope HDR appears "washed out" with GNOME as GNOME lacks scRGB or support for the `frog-color-management-v1` protocol [1] [2]. See #With Gamescope

### Gamescope with Steam session

Valve's Steam compositor gamescope offers experimental HDR support. Following these steps will allow you to try out Valve's Steam client running through the HDR capable gamescope.

Tip An AMDGPU is recommended for use with gamescope - NVIDIA is known to have critical issues.

- Install gamescope and gamescope-session-steam-gitAUR
- You may create the following optional configuration file with the following content:

    ~/.config/environment.d/gamescope-session.conf

    if [ "$XDG_SESSION_DESKTOP" = "gamescope" ] ; then
        SCREEN_WIDTH=1920
        SCREEN_HEIGHT=1080
        CONNECTOR=*,eDP-1
        CLIENTCMD="steam -gamepadui -pipewire-dmabuf"
        GAMESCOPECMD="/usr/bin/gamescope --hdr-enabled --hdr-itm-enable \
        --hide-cursor-delay 3000 --fade-out-duration 200 --xwayland-count 2 \
        -W $SCREEN_WIDTH -H $SCREEN_HEIGHT -O $CONNECTOR"
    fi

- Update the resolution values above to the correct ones. You can list your displays by running `xrandr --query`.
- You may need to set the Display `CONNECTOR` if it does not pick the right one by default.

You can now start `gamescope` from your login manager or a terminal using one of the following steps:

#### Via a login manager

Log out and select the Steam Big Picture in your login manager and log in.

#### Via the command line

1. Go to a new TTY by pressing `Ctrl+Alt+F2`
2. Log in and run `gamescope-session-plus steam` to start the standalone steam session in HDR.
   - If networking does not work you can fix it by installing and enabling NetworkManager.

#### Configure Steam

1. In the general settings, under Display, you should now see HDR settings. Enable HDR and Experimental HDR Support.
2. Select an HDR compatible game and click on the cog next to it.
3. Set Compatibility to Force Proton 8.0 or Proton Experimental.
4. Set Game Resolution to match your monitor otherwise it will launch at Steam Deck native resolution.
5. Click Play to start the game. Check the in-game settings to see if the HDR setting is available and enable it.
6. To switch back to your normal session, select Power and Switch to desktop mode from the Steam menu.

### COSMIC

The COSMIC developers have promised HDR support in the initial stable release.

### sway

Add `render_bit_depth 10` and `hdr off` to the outputs's config in your sway config file, and start sway with `WLR_RENDERER=vulkan` environment variable set.

Setup a binding to toggle hdr or toggle manually i.e.: `swaymsg output DP-1 hdr toggle`.

## Application configuration

### Wine/Proton

HDR through Wine or Steam Proton requires DXVK (2.1+) or VKD3D-Proton (2.8+), depending on DirectX version used by the game.

Tip Use either Proton 8.0+ or Proton GE 44+. All come packaged with sufficient DXVK and VKD3D versions.

#### Without Gamescope

To use HDR without gamescope run a build of Wine which includes the Wayland driver.

Note Wine's native Wayland driver is experimental and may perform better or worse than Xwayland depending on the game.

- proton-ge-custom: install proton-ge-custom-binAUR and set `PROTON_ENABLE_WAYLAND=1` and `PROTON_ENABLE_HDR=1` [3].

Note `PROTON_ENABLE_HDR` sets `DXVK_HDR=1` in proton-ge-custom [4].

- wine-tkg: install wine-tkg, set `DXVK_HDR=1`, and unset `DISPLAY`.
- proton-cachyos or wine-cachyos: install your choice of proton-cachyos-nativeAUR, wine-cachyos-optAUR, or wine-cachyosAUR and set `PROTON_ENABLE_WAYLAND=1` and `DXVK_HDR=1` [5].

Tip You can also easily install the aforementioned wine builds to Lutris, Bottles, or Steam using protonup-qtAUR or protonplusAUR.

#### With Gamescope

Gamescope with proper HDR requires scRGB and `xx-color-management-v4` protocol support or frog-color-management-v1 protocol support in your compositor.

Because of this gamescope will not work with the vk-hdr-layer-kwin6-gitAUR layer. Ensure `ENABLE_HDR_WSI` is not `1`.

You have many options for using gamescope depending on your desired configuration:

- Launch Steam with HDR enabled. All games will then have HDR enabled, but Steam and all games will be launched inside a gamescope window.

    $ gamescope --hdr-enabled --steam -- env DXVK_HDR=1 steam

- Enable HDR for a single game in Steam. Set the following Launch options:

    DXVK_HDR=1 gamescope -f --hdr-enabled -- %command%

- To launch a non-Steam game within gamescope:

    $ DXVK_HDR=1 gamescope -f --hdr-enabled -- executable

Note By default `gamescope` will launch with 1280x720 resolution. To override the default resolution, use the `-W` and `-H` parameters to a desired resolution.

### RetroArch

HDR in RetroArch is supported from version 1.10.0 with Vulkan video driver. First, select video driver Vulkan. Then, enable HDR in RetroArch video settings via Settings tab > Video > HDR > Enable HDR.

    $ retroarch

### Native SDL

To run native games that use SDL with HDR set `SDL_VIDEODRIVER=wayland`.

For example for Quake II RTX:

    $ SDL_VIDEODRIVER=wayland quake2rtx

### mpv

For best image quality mpv maintainers recommend using the `gpu-next` [6] video output driver, which is the default. `gpu-next` supports HDR with `--gpu-context=waylandvk`, which is selected by default on Wayland.

Note This requires a Vulkan WSI with HDR support, see #Vulkan HDR WSI

    $ mpv "path/to/video"

Other ways of enabling Wayland HDR support include using the `dmabuf-wayland` video output and the `drm` GPU context.

    $ mpv --vo=dmabuf-wayland "path/to/video"

- From the tty terminal, one could do (`--gpu-context=drm` is selected by default)

    $ mpv "path/to/video"

### Firefox

firefox introduces working experimental HDR in 138.0 under the hidden preference `gfx.color_management.hdr`. You can enable it at `about:config`.

Stable HDR is still in progress [7] [8].

### Chromium

chromium has work-in-progress HDR support [9]. Support has been merged as of version 141.0.7370.0.

## Troubleshooting

### HDR video samples

Kodi wiki maintains the list of fair use HDR video samples. These can be used to test the HDR output using video players that support HDR such as #mpv.

### Broken screen sharing with HDR10

Pipewire attempts to stream what it sees as BGRA, which WebRTC cannot interpret, due to its current lack of capacity to interpret it. As such, a "ParamId:EnumFormat: 0:0 Invalid argument" exception is thrown and the WebRTC socket crashes for that application [10].

### HDR option missing in games when using multiple AMD GPUs

Using multiple AMD GPUs can cause some games (e.g. RDR2) to hide the option to enable HDR in their graphics settings. This issue can be resolved by setting the `DRI_PRIME` environment variable to the desired card and excluding others (by appending a `!`) as explained in PRIME#For open source drivers—PRIME:

    DRI_PRIME=pci-0000_2d_00_0!

### HDR option missing although the display supports it

This article or section is being considered for removal.

Reason: Once libdisplay-info 0.4.0 hits the repositories, this can be removed after a few months. (Discuss in Talk:HDR)

Some panels, including Samsung ATNA-series laptop OLEDs, put the HDR Static Metadata Data Block inside a DisplayID 2.0 extension block (tag `0x70`) instead of a CTA-861 extension block (tag `0x02`). libdisplay-info only learned to read that location in 0.4.0. With older versions, compositors relying on it see no HDR support and offer no HDR toggle, in any desktop environment.

To confirm the panel is affected, compare `edid-decode` from v4l-utils with `di-edid-decode`:

    $ edid-decode /sys/class/drm/card0-eDP-1/edid | grep -A3 'HDR Static Metadata'
    $ di-edid-decode /sys/class/drm/card0-eDP-1/edid | grep -i hdr

Only the first printing anything means the installed libdisplay-info cannot reach the metadata.

Until the package is updated, the EDID can be rewritten so the same data blocks also appear in an appended CTA-861 extension block. Place the result in `/usr/lib/firmware/edid/` and load it with kernel parameters:

    drm.edid_firmware=eDP-1:edid/hdr-patched-edid.bin

Warning The DRM driver is loaded from the initramfs, so the firmware must be included there too. With mkinitcpio, add the path to `FILES` and regenerate.
Tip hdr-edid-fix rewrites the EDID for any affected panel. Remove it once libdisplay-info is updated.

### Colors washed out in GNOME with HDR enabled

With the `bt2100` color mode enabled, mutter sets the EOTF in `HDR_OUTPUT_METADATA` but leaves the mastering display primaries, white point, luminance range, MaxCLL and MaxFALL at zero. Displays that tone map on their own fall back to a default curve. KWin fills these fields in, so the same panel looks correct under KDE.

Check with `modetest` from libdrm while HDR is enabled:

    $ modetest -c | grep -A6 HDR_OUTPUT_METADATA

Many sinks are unaffected, but `00000000 02 00` followed by zeros is what causes it on the ones that are. See mutter issue 4937 and merge request 5199.

Note Separately, an unmanaged SDR desktop oversaturates sRGB content on a wide gamut panel. Any color managed mode, HDR included, looks duller by comparison; that is not this bug.

## See also

- X.Org Developers' Conference 2022 | Harry Wentland: "Is HDR Harder?"
- wlroots/wlroots | HDR10 support
- Xaver Hugl's blog | An update on HDR and color management in KWin

Categories:

- Display control
- Gaming
- Graphics
- Graphical user interfaces

Hidden category:

- Sections flagged with Template:Remove

HDR
Add topic