QRhiSwapChainHdrInfo Struct

Describes the high dynamic range related information of the swapchain's associated output. More...

Header:	`#include <rhi/qrhi.h>`
CMake:	`find_package(Qt6 REQUIRED COMPONENTS Gui)` `target_link_libraries(mytarget PRIVATE Qt6::GuiPrivate)`
qmake:	`QT += gui-private`
Since:	Qt 6.6

List of all members, including inherited members

Public Types

enum	LimitsType { LuminanceInNits, ColorComponentValue }
enum	LuminanceBehavior { SceneReferred, DisplayReferred }

Public Variables

union QRhiSwapChainHdrInfo::(unnamed union at /data/snapshot-qt6-6.8-rel/qt5/qtbase/src/gui/rhi/qrhi.h:1524:5)	limits
QRhiSwapChainHdrInfo::LimitsType	limitsType
QRhiSwapChainHdrInfo::LuminanceBehavior	luminanceBehavior
float	sdrWhiteLevel

Detailed Description

To perform HDR-compatible tonemapping, where the target range is not [0,1], one often needs to know the maximum luminance of the display the swapchain's window is associated with. While this is often made user-configurable (think brightness, gamma and similar settings in games), it can be highly useful to set defaults based on the values reported by the display itself, thus providing a decent starting point.

There are some problems however: the information is exposed in different forms on different platforms, whereas with cross-platform graphics APIs there is often no associated solution at all, because managing such information is not in the scope of the API (and may rather be retrievable via other platform-specific means, if any).

With Metal on macOS/iOS, there is no luminance values exposed in the platform APIs. Instead, the maximum color component value, that would be 1.0 in a non-HDR setup, is provided. The limitsType field indicates what kind of information is available. It is then up to the clients of QRhi to access the correct data from the limits union and use it as they see fit.

With an API like Vulkan, where there is no way to get such information, the values are always the built-in defaults.

Therefore, the struct returned from QRhiSwapChain::hdrInfo() contains either some hard-coded defaults or real values received from an API such as DXGI (IDXGIOutput6) or Cocoa (NSScreen). When no platform queries are available (or needs using platform facilities out of scope for QRhi), the hard-coded defaults are a maximum luminance of 1000 nits and an SDR white level of 200.

The struct also exposes the presumed luminance behavior of the platform and its compositor, to indicate what a color component value of 1.0 is treated as in a HDR color buffer. In some cases it will be necessary to perform color correction of non-HDR content composited with HDR content. To enable this, the SDR white level is queried from the system on some platforms (Windows) and exposed here.

Note: This is a RHI API with limited compatibility guarantees, see QRhi for details.

See also QRhiSwapChain::hdrInfo().

Member Type Documentation

enum QRhiSwapChainHdrInfo::LimitsType

Constant	Value	Description
`QRhiSwapChainHdrInfo::LuminanceInNits`	`0`	Indicates that the limits union has its `luminanceInNits` struct set
`QRhiSwapChainHdrInfo::ColorComponentValue`	`1`	Indicates that the limits union has its `colorComponentValue` struct set

enum QRhiSwapChainHdrInfo::LuminanceBehavior

Constant	Value	Description
`QRhiSwapChainHdrInfo::SceneReferred`	`0`	Indicates that the color value of 1.0 is interpreted as 80 nits. This is the behavior of HDR-enabled windows with the Windows compositor. See this page for more information on HDR on Windows.
`QRhiSwapChainHdrInfo::DisplayReferred`	`1`	Indicates that the color value of 1.0 is interpreted as the value of the SDR white. (which can be e.g. 200 nits, but will vary depending on screen brightness) This is the behavior of HDR-enabled windows on Apple platforms. See this page for more information on Apple's EDR system.

Member Variable Documentation

union QRhiSwapChainHdrInfo::(unnamed union at /data/snapshot-qt6-6.8-rel/qt5/qtbase/src/gui/rhi/qrhi.h:1524:5) QRhiSwapChainHdrInfo::limits

Contains the actual values queried from the graphics API or the platform. The type of data is indicated by limitsType. This is therefore a union. There are currently two options:

Luminance values in nits:

struct {
    float minLuminance;
    float maxLuminance;
} luminanceInNits;

On Windows the minimum and maximum luminance depends on the screen brightness. While not relevant for desktops, on laptops the screen brightness may change at any time. Increasing brightness implies decreased maximum luminance. In addition, the results may also be dependent on the HDR Content Brightness set in Windows Settings' System/Display/HDR view, if there is such a setting.

Note however that the changes made to the laptop screen's brightness or in the system settings while the application is running are not necessarily reflected in the returned values, meaning calling hdrInfo() again may still return the same luminance range as before for the rest of the process' lifetime. The exact behavior is up to DXGI and Qt has no control over it.

Note: The Windows compositor works in scene-referred mode for HDR content. A color component value of 1.0 corresponds to a luminance of 80 nits. When rendering non-HDR content (e.g. 2D UI elements), the correction of the white level is often necessary. (e.g., outputting the fragment color (1, 1, 1) will likely lead to showing a shade of white that is too dim on-screen) See sdrWhiteLevel.

For macOS/iOS, the current maximum and potential maximum color component values are provided:

struct {
    float maxColorComponentValue;
    float maxPotentialColorComponentValue;
} colorComponentValue;

The value may depend on the screen brightness, which on laptops means that the result may change in the next call to hdrInfo() if the brightness was changed in the meantime. The maximum screen brightness implies a maximum color value of 1.0.

Note: Apple's EDR is display-referred. 1.0 corresponds to a luminance level of SDR white (e.g. 200 nits), the value of which varies based on the screen brightness and possibly other settings. The exact luminance value for that, or the maximum luminance of the display, are not exposed to the applications.

Note: It has been observed that the color component values are not set to the correct larger-than-1 value right away on startup on some macOS systems, but the values tend to change during or after the first frame.

See also QRhiSwapChain::hdrInfo().

QRhiSwapChainHdrInfo::LimitsType QRhiSwapChainHdrInfo::limitsType

See also QRhiSwapChain::hdrInfo().

QRhiSwapChainHdrInfo::LuminanceBehavior QRhiSwapChainHdrInfo::luminanceBehavior

Describes the platform's presumed behavior with regards to color values.

See also sdrWhiteLevel.

float QRhiSwapChainHdrInfo::sdrWhiteLevel

On Windows this is the dynamic SDR white level in nits. The value is dependent on the screen brightness (on laptops), and the SDR or HDR Content Brightness settings in the Windows settings' System/Display/HDR view.

To perform white level correction for non-HDR (SDR) content, such as 2D UI elemenents, multiply the final color with sdrWhiteLevel / 80.0 whenever luminanceBehavior is SceneReferred. (assuming Windows and a linear extended sRGB (scRGB) color space)

On other platforms the value is always a pre-defined value, 200. This may not match the system's actual SDR white level, but the value of this variable is not relevant in practice when the luminanceBehavior is DisplayReferred, because then the color component value of 1.0 refers to the SDR white by default.

See also luminanceBehavior.

© 2024 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.