IDXGISwapChain4::SetHDRMetaData method (dxgi1_5.h)

Article
11/03/2022

Warning

It is no longer recommended for apps to explicitly set HDR metadata on their swap chain using SetHDRMetaData. Windows does not guarantee that swap chain metadata is sent to the monitor, and monitors do not handle HDR metadata consistently. Therefore it's recommended that apps always tone-map content into the range reported by the monitor. For more details on how to write apps that react dynamically to monitor capabilities, see Using DirectX with high dynamic range displays and Advanced Color.

See Remarks for more details.

This method sets High Dynamic Range (HDR) and Wide Color Gamut (WCG) header metadata.

Syntax

HRESULT SetHDRMetaData(
  [in]           DXGI_HDR_METADATA_TYPE Type,
  [in]           UINT                   Size,
  [in, optional] void                   *pMetaData
);

Parameters

[in] Type

Type: DXGI_HDR_METADATA_TYPE

Specifies one member of the DXGI_HDR_METADATA_TYPE enum.

[in] Size

Type: UINT

Specifies the size of pMetaData, in bytes.

[in, optional] pMetaData

Type: void*

Specifies a void pointer that references the metadata, if it exists. Refer to the DXGI_HDR_METADATA_HDR10 structure.

Return value

Type: HRESULT

This method returns an HRESULT success or error code.

Remarks

This method sets metadata to enable a monitor's output to be adjusted depending on its capabilities. However it does not change how pixel values are interpreted by Windows or monitors. To adjust the color space of the swap chain, use SetColorSpace1 instead.

Applications should not rely on the metadata being sent to the monitor as the metadata may be ignored. Monitors do not consistently process HDR metadata, resulting in varied appearance of your content across different monitors. In order to ensure more consistent output across a range of monitors, devices, and use cases, it is recommended to not use SetHDRMetaData and to instead tone-map content into the gamut and luminance range supported by the monitor. See IDXGIOutput6::GetDesc1 to retrieve the monitor's supported gamut and luminance range. Monitors adhering to the VESA DisplayHDR standard will automatically perform a form of clipping for content outside of the monitor's supported gamut and luminance range.

For more details on how to write apps that react dynamically to monitor capabilities, see Using DirectX with high dynamic range displays and Advanced Color.

Requirements

Requirement	Value
Target Platform	Windows
Header	dxgi1_5.h
Library	Dxgi1_5.lib
DLL	Dxgi1_5.dll