XDisplayTryEnableHdrMode

Attempts to enable HDR (high dynamic range) mode for the attached display.

Syntax

XDisplayHdrModeResult XDisplayTryEnableHdrMode(  
         XDisplayHdrModePreference displayModePreference,  
         XDisplayHdrModeInfo* displayHdrModeInfo  
)  

Parameters

displayModePreference   _In_
Type: XDisplayHdrModePreference

Enumeration used to favor either HDR or an improved framerate up to 120Hz, in cases where both are not supported by the connected TV.

displayHdrModeInfo   _Out_opt_
Type: XDisplayHdrModeInfo*

If HDR mode is enabled, the minimum and maximum tone map luminance values for the attached display.

Return value

Type: XDisplayHdrModeResult

If the function succeeds, the return value is set to either XDisplayHdrModeResult::Enabled if HDR mode is enabled, or XDisplayHdrModeResult::Disabled if HDR mode is not enabled. If the function fails, the return value is set to XDisplayHdrModeResult::Unknown.

Remarks

The displayModePreference parameter provides a way to favor HDR or 120Hz refresh rates for TVs that don't support both simultaneously.

In example below, the developer attempts to enable HDR mode for the current title, stating preference for HDR instead of a higher framerate (in the case that both cannot be achieved).

const XDisplayHdrModeResult result = XDisplayTryEnableHdrMode( 
    XDisplayHdrModePreference::PreferHdr, 
    &displayModeHdrInfo); 

switch (result) 
{ 
  case XDisplayHdrModeResult::Unknown: 
    // HDR is currently in an unknown state. 
    break; 
  case XDisplayHdrModeResult::Enabled: 
    // HDR is currently enabled. 
    break; 
  case XDisplayHdrModeResult::Disabled: 
    // HDR is currently disabled. 
    break; 
}

Titles should use XDisplayHdrModePreference::PreferHdr when:

• Your title only implements HDR and does not support 120hz at all.
• The end user has set an in-game setting indicating they don't want 120Hz refresh rate, or they prefer HDR such as a preference for quality over performance.
• The title is in a game mode in which 120Hz refresh rate is not supported.

Titles should use XDisplayHdrModePreference::PreferRefreshRate when:

• You support 120hz and you or the end user has indicated that it is preferred for the current scenario (e.g. setting Prefer performance in an in game setting or game mode).

Call XDisplayTryEnableHdrMode a second time with a different preference if:

• Something changed that has swayed your preference. Most likely the user has changed the in-game setting from Prefer quality to Prefer performance.

After calling XDisplayTryEnableHdrMode, call IDXGIOutput::GetDisplayModeList to check for to check for 120Hz support.

The XDisplayTryEnableHdrMode function returns an XDisplayHdrModeResult enumeration value that indicates whether the function can enable HDR mode for the attached display. If XDisplayHdrModeResult::Enabled is returned, the function also provides an XDisplayHdrModeInfo structure that contains information about HDR mode for the display, including the minimum and maximum tone map luminance values for HDR mode. By default, if HDR mode is enabled, the XDisplayTryEnableHdrMode function returns the following values for the members of XDisplayHdrModeInfo:

For more information about HDR luminance values and tone mapping, see the For a Better HDR Gaming Experience presentation on the HDR Gaming Interest Group website.

The following example attempts to enable HDR mode for the attached display. If XDisplayHdrModeInfo::Enabled is returned, then HDR mode is enabled for the display and the game uses the luminance values from the returned XDisplayHdrModeInfo structure to initialize in HDR mode; otherwise, HDR mode is either unavailable or disabled, and the game initializes in SDR (standard dynamic range) mode.

void Game::InitializeHDRMode() 
{
    // Attempt to enable HDR mode, then initialize based on the 
    // result of the attempt.
    XDisplayHdrModeInfo displayModeHdrInfo;

    if (XDisplayHdrModeResult::Enabled == XDisplayTryEnableHdrMode(XDisplayHdrModePreference::PreferHdr, &displayModeHdrInfo))
    {
        // HDR mode is enabled for the attached display.
        InitializeAsHDR(
            displayModeHdrInfo.minToneMapLuminance,
            displayModeHdrInfo.maxToneMapLuminance,
            displayModeHdrInfo.maxFullFrameToneMapLuminance);
    }
    else
    {
        // Either HDR mode is disabled for the attached display, or the
        // attached display does not support HDR.
        InitializeAsSDR();
    }
}

For more information about HDR support, see High dynamic range (HDR) output (NDA topic)Autorisation obligatoire.

Requirements

Header: XDisplay.h

Library: xgameruntime.lib

Supported platforms: Xbox One family consoles and Xbox Series consoles

See also

XDisplayHdrModePreference
XDisplayHdrModeInfo
XDisplayHdrModeResult
XDisplay