> ## 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

尝试为附加的显示器启用 HDR（高动态范围）模式。

## Syntax

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

### Parameters

*displayModePreference*   \_In\_\
类型：[XDisplayHdrModePreference](/reference/system/xdisplay/enums/xdisplayhdrmodepreference)

在连接的电视不同时支持这两种情况下，用于偏向 HDR 或高达 120Hz 的更高帧速率的枚举。

*displayHdrModeInfo*   \_Out\_opt\_\
类型：[XDisplayHdrModeInfo\*](/reference/system/xdisplay/structs/xdisplayhdrmodeinfo)

如果启用了 HDR 模式，则为附加显示器的最小和最大色调映射亮度值。

### Return value

类型：[XDisplayHdrModeResult](/reference/system/xdisplay/enums/xdisplayhdrmoderesult)

如果函数成功，则如果启用了 HDR 模式，返回值设置为 **XDisplayHdrModeResult::Enabled**；如果未启用 HDR 模式，则设置为 **XDisplayHdrModeResult::Disabled**。如果函数失败，返回值将设置为 **XDisplayHdrModeResult::Unknown**。

## Remarks

<Note>此函数在时间敏感线程上调用不安全。有关详细信息，请参阅[时间敏感线程](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)。</Note>

对于不能同时支持 HDR 和 120Hz 刷新率的电视，*displayModePreference* 参数提供了偏好 HDR *或* 120Hz 刷新率的方式。

在下面的示例中，开发人员尝试为当前标题启用 HDR 模式，并声明偏好 HDR 而不是更高的帧速率（在无法同时实现两者的情况下）。

```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; 
}
```

以下情况下，标题应使用 [XDisplayHdrModePreference::PreferHdr](/reference/system/xdisplay/enums/xdisplayhdrmodepreference)：

* 标题仅实现 HDR，根本不支持 120hz。
* 终端用户已设置游戏内设置，表明他们不希望 120Hz 刷新率，或者他们偏好 HDR，例如偏好质量而非性能。
* 标题处于不支持 120Hz 刷新率的游戏模式。

以下情况下，标题应使用 [XDisplayHdrModePreference::PreferRefreshRate](/reference/system/xdisplay/enums/xdisplayhdrmodepreference)：

* 你支持 120hz，并且你或最终用户已表明它是当前场景的首选（例如，在游戏内设置或游戏模式中设置**偏好性能**）。

如果发生以下情况，请使用不同的首选项再次调用 **XDisplayTryEnableHdrMode**：

* 某些情况发生变化，影响了首选项。最有可能的是，用户已将游戏内设置从**偏好质量**更改为**偏好性能**。

<Note>不要每帧都调用 **XDisplayTryEnableHdrMode** 并来回切换；仅在有特定诱因时进行更改。</Note>

在调用 **XDisplayTryEnableHdrMode** 之后，调用 [IDXGIOutput::GetDisplayModeList](https://learn.microsoft.com/windows/win32/api/dxgi/nf-dxgi-idxgioutput-getdisplaymodelist) 来检查 120Hz 支持。

**XDisplayTryEnableHdrMode** 函数返回 **XDisplayHdrModeResult** 枚举值，指示该函数是否可以为附加显示器启用 HDR 模式。如果返回 **XDisplayHdrModeResult::Enabled**，该函数还会提供 [XDisplayHdrModeInfo](/reference/system/xdisplay/structs/xdisplayhdrmodeinfo) 结构，其中包含显示器 HDR 模式的信息，包括 HDR 模式的最小和最大色调映射亮度值。默认情况下，如果启用了 HDR 模式，**XDisplayTryEnableHdrMode** 函数将为 **XDisplayHdrModeInfo** 的成员返回以下值：

| 成员                           | 值    |
| ---------------------------- | ---- |
| minToneMapLuminance          | 0.01 |
| maxToneMapLuminance          | 1000 |
| maxFullFrameToneMapLuminance | 1000 |

有关 HDR 亮度值和色调映射的详细信息，请参阅 [HDR 游戏兴趣小组](https://www.hgig.org/)网站上的 [For a Better HDR Gaming Experience](https://www.hgig.org/doc/ForBetterHDRGaming.pdf) 演示文稿。

以下示例尝试为附加的显示器启用 HDR 模式。如果返回 [XDisplayHdrModeInfo::Enabled](/reference/system/xdisplay/enums/xdisplayhdrmoderesult)，则表示已为显示器启用 HDR 模式，游戏将使用返回的 [XDisplayHdrModeInfo](/reference/system/xdisplay/structs/xdisplayhdrmodeinfo) 结构中的亮度值以 HDR 模式初始化；否则，HDR 模式不可用或已禁用，游戏将以 SDR（标准动态范围）模式初始化。

```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();
    }
}
```

有关 HDR 支持的详细信息，请参阅[高动态范围 (HDR) 输出（NDA 主题）](/build/core-features/graphics/overviews/hdr-support)。

## Requirements

**头文件：** XDisplay.h

**库：** xgameruntime.lib

**受支持的平台：** XBOX One 系列主机和 XBOX Series 主机

## Conceptual documentation

* [时间敏感线程](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

- [XDisplayHdrModeInfo](/zh-CN/reference/system/xdisplay/structs/xdisplayhdrmodeinfo.md)
- [XDisplayHdrModeResult](/zh-CN/reference/system/xdisplay/enums/xdisplayhdrmoderesult.md)
- [XDisplayHdrModePreference](/zh-CN/reference/system/xdisplay/enums/xdisplayhdrmodepreference.md)
- [XDisplay](/zh-CN/reference/system/xdisplay/xdisplay_members.md)
- [Screen Capture (wdcapture.exe)](/zh-CN/tools/tools-pc/commandlinetools/gr-wdCapture.md)