No Vulkan HDR metadata (causes brightness issues on linux)

[CallieEZ]

Is there an existing issue for this?

• This is a bug in RetroArch frontend
• I have searched the existing issues

Description

Enabling HDR on linux using KDE's built in HDR support results in overbrightened colors. This is most likely related to how mesa handles the brightness of VK_COLOR_SPACE_HDR10_ST2084_EXT differently compared to the windows implementation, as detailed in this issue: https://gitlab.freedesktop.org/mesa/mesa/-/issues/12689. This issue can be circumvented for now by using http://github.com/Zamundaaa/VK_hdr_layer and running retroarch with ENABLE_HDR_WSI=1.

Expected behavior

No response

Steps to reproduce the bug

1. Boot retroarch with HDR enabled using the vulkan video driver on plasma 6.4
2. Enable HDR in video settings
3. Observe extremely inaccurate and bright colors

Version/Commit

1.20.0

Bisect Results

No response

Present in the nightly version

I don't know

Platform & operating system

Linux AMD64

Affected Cores

No response

Environment information

No response

Relevant log output

[gouchi]

Hi,

Can you make a test with nightly build ? And provide some log.

Also if possible to provide some screenshots ?

Thank you.

[matheuswillder]

I can confirm that this issue also occurs in Gnome (log file at the end).

For some reason, the HDR option doesn't appear in the AppImage build, either the latest stable or the nightly one above, but it does appear in the Flatpak build, so the videos below are from that.

Video showing the issue described (if the video doesn't load, right click on it>Save video as..., save it to some folder and open it with a player):

1.mp4

Also, I don't know if this is the same issue as above, but with HDR enabled, if I load an HDR shader (/shaders_slang/hdr folder), the menu background image has the colors distorted. This is particularly noticeable in the XMB menu, as it allows you to use a custom background image, but it also occurs in the Ozone menu, where it change the background to solid black, and if I use a On-Screen Overlay (like RGPad), its colors change as well. This also occurs on Android.

Video showing this (also in Gnome) (if the video doesn't load, right click on it>Save video as..., save it to some folder and open it with a player):

2.mp4

Video showing this (Android) (if the video doesn't load, right click on it>Save video as..., save it to some folder and open it with a player):

3.mp4

I couldn't generate a log using those commands in the Flatpak build, but I enabled logging in the settings, closed RetroArch, opened it, and followed exactly the steps in the first video (open RetroArch, enable HDR, load the ROM, waited a few seconds, and closed it).

retroarch__2025_08_19__23_01_03.log

I noticed all of this a few weeks ago. I was trying to set up an HDR shader, but the results weren't good. After exchanging some comments with CyberLabSystems on the RetroArch subreddit, I noticed that HDR was buggy in RetroArch on Linux.

But due to personal issues I'm short on time at the moment, so just now I made these videos and posted the log. I hope this helps fix the issue.

Edit: I've added a video showing the issue on Android. The HDR shader actually appears to be working correctly, but the background image and overlay aren't (notice that the B button, which should be yellow, turns red after loading the HDR shader).

Also, since the HDR option doesn't appear in the AppImage build, I think the best way to test this would be to use the Flathub test builds: https://github.com/flathub/org.libretro.RetroArch. I can do more testing if needed when I have some free time.

[gouchi]

@MajorPainTheCactus @CRefice might have some input.

Thank you for your help.

[matheuswillder]

Looking at the links above, it seems that upgrading Mesa to 25.1 or up should solve the problem.

NOTE: Mesa 25.1+ implements the color management protocol directly, this Vulkan layer is no longer necessary with that.

This should be easy to do with Flatpak, as it can use its own runtime versions regardless of the version installed on the system. @RobLoach, should I open an issue about it in https://github.com/flathub/org.libretro.RetroArch?

[Zamundaaa]

Enabling HDR on linux using KDE's built in HDR support results in overbrightened colors. This is most likely related to how mesa handles the brightness of VK_COLOR_SPACE_HDR10_ST2084_EXT differently compared to the windows implementation, as detailed in this issue: https://gitlab.freedesktop.org/mesa/mesa/-/issues/12689. This issue can be circumvented for now by using http://github.com/Zamundaaa/VK_hdr_layer and running retroarch with ENABLE_HDR_WSI=1.

The Vulkan layer shouldn't behave differently from Mesa, it does exactly the same for PQ. Only scRGB is handled differently (on compositors that support it).

This issue probably comes down to two things:

• RetroArch doesn't seem to set any HDR metadata, which is often required for properly displaying HDR content
• your configuration is most likely wrong. Indeed, Wayland (and MacOS, and Android, really everything except Windows) does HDR differently from Windows. For correct behavior, you need either
  • paper white and max luminance to both match the Wayland compositor. Vulkan has no way to set that, so that would likely be a bit larger change in RetroArch; you'd need to use VK_COLOR_SPACE_PASS_THROUGH_EXT in Vulkan and set colorspace data through Wayland directly instead. OR
  • paper white to be 203 (for PQ), and peak luminance to be preferred_peak * 203 / preferred_reference. The preferred HDR metadata of a window can be looked up with the Wayland color management protocol's wp_color_management_surface_feedback_v1

Ideally, Retroarch would just hide the HDR luminance settings on Wayland and always automatically use the compositor settings.

[CallieEZ]

Enabling HDR on linux using KDE's built in HDR support results in overbrightened colors. This is most likely related to how mesa handles the brightness of VK_COLOR_SPACE_HDR10_ST2084_EXT differently compared to the windows implementation, as detailed in this issue: https://gitlab.freedesktop.org/mesa/mesa/-/issues/12689. This issue can be circumvented for now by using http://github.com/Zamundaaa/VK_hdr_layer and running retroarch with ENABLE_HDR_WSI=1.

The Vulkan layer shouldn't behave differently from Mesa, it does exactly the same for PQ. Only scRGB is handled differently (on compositors that support it).

This issue probably comes down to two things:

* RetroArch doesn't seem to set any HDR metadata, which is often required for properly displaying HDR content

* your configuration is most likely wrong. Indeed, Wayland (and MacOS, and Android, really everything except Windows) does HDR differently from Windows. For correct behavior, you need either
  
  * paper white and max luminance to both match the Wayland compositor. Vulkan has no way to set that, so that would likely be a bit larger change in RetroArch; you'd need to use `VK_COLOR_SPACE_PASS_THROUGH_EXT` in Vulkan and set colorspace data through Wayland directly instead. OR
  * paper white to be 203 (for PQ), and peak luminance to be `preferred_peak * 203 / preferred_reference`. The preferred HDR metadata of a window can be looked up with the Wayland color management protocol's `wp_color_management_surface_feedback_v1`

Ideally, Retroarch would just hide the HDR luminance settings on Wayland and always automatically use the compositor settings.

I have Paperwhite set to 200 in both retroarch and kde and peak set to the same as in kde settings and still get oversaturation.

[Zamundaaa]

Then there's likely some additional issue present in your case. Please run

WAYLAND_DEBUG=1 retroarch 2>&1 | grep 'image_description'

and post the output here.

[CallieEZ]

Then there's likely some additional issue present in your case. Please run

WAYLAND_DEBUG=1 retroarch 2>&1 | grep 'image_description'

and post the output here.

[3660656.630] {mesa vk display queue}  -> wp_color_manager_v1#52.create_parametric_creator(new id wp_image_description_creator_params_v1#67)
[3660656.632] {mesa vk display queue}  -> wp_image_description_creator_params_v1#67.set_primaries_named(6)
[3660656.634] {mesa vk display queue}  -> wp_image_description_creator_params_v1#67.set_tf_named(11)
[3660656.635] {mesa vk display queue}  -> wp_image_description_creator_params_v1#67.create(new id wp_image_description_v1#63)
[3660656.684] {mesa vk display queue} wp_image_description_v1#63.ready(277)
[3660656.689] {mesa vk display queue}  -> wp_color_management_surface_v1#71.set_image_description(wp_image_description_v1#63, 0)
[3660656.692] {mesa vk display queue}  -> wp_image_description_v1#63.destroy()

[Zamundaaa]

Just to be sure, maybe also add your complete display settings (kscreen-doctor -o), but it looks like on the Wayland side everything's correct.

[CallieEZ]

Just to be sure, maybe also add your complete display settings (kscreen-doctor -o), but it looks like on the Wayland side everything's correct.

Output: 1 DP-1 243fa9e8-9144-4cb1-bbda-0ab8a18f2a50
        enabled
        connected
        priority 1
        DisplayPort
        replication source:0
        Modes:  1:2560x1440@60!  2:2560x1440@240*  3:2560x1440@180  4:2560x1440@144  5:2560x1440@120  6:1920x1200@60  7:1920x1080@240  8:1920x1080@120  9:1920x1080@120  10:1920x1080@100  11:1920x1080@60  12:1920x1080@60  13:1920x1080@60  14:1920x1080@50  15:1920x1080@30  16:1920x1080@30  17:1920x1080@25  18:1920x1080@24  19:1920x1080@24  20:1600x1200@60  21:1680x1050@60  22:1280x1024@60  23:1440x900@60  24:1280x960@60  25:1280x800@60  26:1280x720@60  27:1280x720@60  28:1280x720@50  29:1024x768@75  30:1024x768@60  31:800x600@75  32:800x600@60  33:720x576@50  34:720x576@50  35:720x480@60  36:720x480@60  37:720x480@60  38:720x480@60  39:640x480@75  40:640x480@60  41:640x480@60  42:640x480@60  43:1600x1200@240  44:1280x1024@240  45:1024x768@240  46:1920x1200@240  47:1280x800@240  48:1600x900@60  49:1600x900@240  50:1368x768@60  51:1368x768@240  52:1280x720@240 
        Geometry: 0,0 2560x1440
        Scale: 1
        Rotation: 1
        Overscan: 0
        Vrr: Automatic
        RgbRange: Full
        HDR: enabled
                SDR brightness: 200 nits
                SDR gamut wideness: 0%
                Peak brightness: 630 nits, overridden with: 630 nits
                Max average brightness: 259 nits
                Min brightness: 0.0011 nits
        Wide Color Gamut: enabled
        ICC profile: /home/cncz/XG27AQDMG.icm
        Color profile source: EDID
        Color power preference: prefer efficiency and performance
        Brightness control: supported, set to 100% and dimming to 100%
        Color resolution: automatic (10), range: [8; 16] bits per color
        Allow EDR: unsupported
Output: 2 DP-2 20f02f07-d651-4a37-8e30-7f4e73cbc880
        enabled
        connected
        priority 2
        DisplayPort
        replication source:0
        Modes:  53:2560x1440@165*!  54:2560x1440@144  55:2560x1440@120  56:2560x1440@100  57:2560x1440@60  58:1920x1200@165  59:1920x1080@120  60:1920x1080@120  61:1920x1080@100  62:1920x1080@60  63:1920x1080@60  64:1920x1080@60  65:1920x1080@50  66:1600x1200@165  67:1680x1050@165  68:1280x1024@165  69:1440x900@165  70:1280x800@165  71:1280x720@60  72:1280x720@60  73:1280x720@50  74:1024x768@60  75:800x600@60  76:720x480@60  77:720x480@60  78:640x480@60  79:640x480@60  80:640x480@60  81:1600x1200@60  82:1280x1024@60  83:1024x768@165  84:1920x1200@60  85:1280x800@60  86:1920x1080@165  87:1600x900@60  88:1600x900@165  89:1368x768@60  90:1368x768@165  91:1280x720@165 
        Geometry: 2560,0 2560x1440
        Scale: 1
        Rotation: 1
        Overscan: 0
        Vrr: Automatic
        RgbRange: Full
        HDR: disabled
        Wide Color Gamut: disabled
        ICC profile: /home/cncz/.local/share/DisplayCAL/storage/Monitor_2 #2 2025-08-23 15-51 S XYZLUT+MTX/Monitor_2 #2 2025-08-23 15-51 S XYZLUT+MTX.icc
        Color profile source: sRGB
        Color power preference: prefer efficiency and performance
        Brightness control: supported, set to 100% and dimming to 100%
        Color resolution: automatic (10), range: [8; 16] bits per color
        Allow EDR: unsupported

[Zamundaaa]

Yeah, nothing wrong or weird there.

[CallieEZ]

Guess I'll send in a comparison video just in case the default mode is supposed to look this saturated, any clue how to capture HDR desktop video on kde?

[Zamundaaa]

There's unfortunately no way to do that yet. I wanted to look into whether or not it can be added to Pipewire and adding support for it in KWin, but didn't get around to it yet.

[CallieEZ]

Here's some tone mapped screenshots for now I guess, not 100% indicative but gets the gist of it (taken with expand gamut off):

No HDR:

Default HDR (brightness isn't consistent, skin is red-ish, some similar colors are hard to distinguish in highlights):

HDR WSI (bright but distinguishable, although not in the screenshot, colors are very much in-line with SDR):

[Zamundaaa]

Ah, I think I see what's going on. The WSI layer uses the frog protocol, with which (as of Plasma 6.4) KWin happens to be more forgiving with missing HDR metadata. It will generally work well with that, as long as the screen has enough HDR headroom to perfectly show the image. When it doesn't have enough headroom, it's very bad though.

So adding HDR metadata should take care of this.