> ## Documentation Index
> Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XDisplayTryEnableHdrMode

> XDisplayTryEnableHdrMode

# XDisplayTryEnableHdrMode

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

## Syntax

```cpp theme={null}
XDisplayHdrModeResult XDisplayTryEnableHdrMode(  
         XDisplayHdrModePreference displayModePreference,  
         XDisplayHdrModeInfo* displayHdrModeInfo  
)  
```

### Parameters

*displayModePreference*   \_In\_\
Type: [XDisplayHdrModePreference](/reference/system/xdisplay/enums/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\*](/reference/system/xdisplay/structs/xdisplayhdrmodeinfo)

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

### Return value

Type: [XDisplayHdrModeResult](/reference/system/xdisplay/enums/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

<Note>This function isn't safe to call on a time-sensitive thread. For more information, see [Time-sensitive threads](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads).</Note>

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).

```cpp theme={null}
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](/reference/system/xdisplay/enums/xdisplayhdrmodepreference) 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](/reference/system/xdisplay/enums/xdisplayhdrmodepreference) 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**.

<Note>Don't call **XDisplayTryEnableHdrMode** and toggle back and forth each frame; only change when there is some specific provocation.</Note>

After calling **XDisplayTryEnableHdrMode**, call [IDXGIOutput::GetDisplayModeList](https://learn.microsoft.com/windows/win32/api/dxgi/nf-dxgi-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](/reference/system/xdisplay/structs/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**:

| Member                       | Value |
| ---------------------------- | ----- |
| minToneMapLuminance          | 0.01  |
| maxToneMapLuminance          | 1000  |
| maxFullFrameToneMapLuminance | 1000  |

For more information about HDR luminance values and tone mapping, see the [For a Better HDR Gaming Experience](https://www.hgig.org/doc/ForBetterHDRGaming.pdf) presentation on the [HDR Gaming Interest Group](https://www.hgig.org/) website.

The following example attempts to enable HDR mode for the attached display. If [XDisplayHdrModeInfo::Enabled](/reference/system/xdisplay/enums/xdisplayhdrmoderesult) is returned, then HDR mode is enabled for the display and the game uses the luminance values from the returned [XDisplayHdrModeInfo](/reference/system/xdisplay/structs/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.

```cpp theme={null}
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)](/build/core-features/graphics/overviews/hdr-support).

## Requirements

**Header:** XDisplay.h

**Library:** xgameruntime.lib

**Supported platforms:** XBOX One family consoles and XBOX Series consoles

## Conceptual documentation

* [Time-sensitive threads](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## See also

[XDisplayHdrModePreference](/reference/system/xdisplay/enums/xdisplayhdrmodepreference)\
[XDisplayHdrModeInfo](/reference/system/xdisplay/structs/xdisplayhdrmodeinfo)\
[XDisplayHdrModeResult](/reference/system/xdisplay/enums/xdisplayhdrmoderesult)\
[XDisplay](/reference/system/xdisplay/xdisplay_members)


## Related topics

- [XDisplayHdrModeResult](/reference/system/xdisplay/enums/xdisplayhdrmoderesult.md)
- [XDisplayHdrModeInfo](/reference/system/xdisplay/structs/xdisplayhdrmodeinfo.md)
- [XDisplayHdrModePreference](/reference/system/xdisplay/enums/xdisplayhdrmodepreference.md)
- [XDisplay](/reference/system/xdisplay/xdisplay_members.md)
- [XR-131 Display Mode Support for Game DVR and Screenshots](/publishing/certification/xr/xr-131.md)