通过

XDisplayTryEnableHdrMode

  • 项目

尝试为连接的显示屏启用 HDR（高动态范围）模式。

语法

XDisplayHdrModeResult XDisplayTryEnableHdrMode(  
         XDisplayHdrModePreference displayModePreference,  
         XDisplayHdrModeInfo* displayHdrModeInfo  
)

参数

displayModePreference _In_
类型：XDisplayHdrModePreference

用于偏好 HDR 或高达 120Hz 的改进帧速率的枚举（在这二者均不受连接的 TV 支持的情况下）。

displayHdrModeInfo _Out_opt_
类型：XDisplayHdrModeInfo*

如果启用 HDR 模式，则为连接的显示屏的最小和最大色调映射亮度值。

返回值

类型：XDisplayHdrModeResult

如果该函数成功，则返回值设置为 XDisplayHdrModeResult::Enabled（如果启用 HDR 模式）或 XDisplayHdrModeResult::Disabled（如果未启用 HDR 模式）。 如果该函数失败，则返回值设置为 XDisplayHdrModeResult::Unknown。

备注

注意

在时间敏感线程上调用此函数是不安全的。 有关详细信息，请参阅时间敏感线程。

displayModePreference 参数提供了一种方式，为不同时支持 HDR 或 120Hz 刷新频率的 TV 首选这二者之一。

在下面的示例中，开发人员尝试为当前游戏启用 HDR 模式，指明首选 HDR，而不是更高的帧速率（在不能同时实现两者的情况下）。

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：

  • 游戏只实现 HDR，根本不支持 120Hz。
  • 最终用户设置了一项游戏内设置，指明他们不需要 120Hz 的刷新频率，或者他们更喜欢将 HDR 作为质量（而非性能）的首选项。
  • 游戏所处于的游戏模式中并不支持 120Hz 的刷新频率。

在以下情况中，游戏应使用 XDisplayHdrModePreference::PreferRefreshRate：

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

如果出现以下情况，使用不同的首选项第二次调用 XDisplayTryEnableHdrMode：

  • 发生了一些影响首选项的更改。 最有可能的一种情况是，用户将游戏内设置从首选质量更改为首选性能。

注意

请勿调用 XDisplayTryEnableHdrMode 并在每帧来回切换；只在有一些特定的缘由时执行更改。

在调用 XDisplayTryEnableHdrMode 后调用 IDXGIOutput::GetDisplayModeList，检查是否支持 120Hz。

XDisplayTryEnableHdrMode 函数返回一个 XDisplayHdrModeResult 枚举值，该枚举值指示该函数是否可以启用连接的显示屏的 HDR 模式。 如果返回 XDisplayHdrModeResult::Enabled，则该函数还提供一个 XDisplayHdrModeInfo 结构，该结构包含有关显示屏的 HDR 模式的信息，包括针对 HDR 模式的最小和最大色调映射亮度值。 默认情况下，如果启用了 HDR 模式，则 XDisplayTryEnableHdrMode 函数将为 XDisplayHdrModeInfo 的成员返回以下值：

成员 值
minToneMapLuminance 0.01
maxToneMapLuminance 1000
maxFullFrameToneMapLuminance 1000

有关 HDR 亮度值和色调映射的详细信息，请参阅 HDR 游戏兴趣小组网站上的获得更好的 HDR 游戏体验演示。

下面的示例尝试为连接的显示屏启用 HDR 模式。 如果返回 XDisplayHdrModeInfo::Enabled，则为显示屏启用 HDR 模式，并且游戏使用来自返回的 XDisplayHdrModeInfo 结构的亮度值来在 HDR 模式下初始化；否则，HDR 模式不可用或者被禁用，并且游戏在 SDR（标准动态范围）模式下初始化。

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 主题）。

要求

头文件：XDisplay.h

库：xgameruntime.lib

支持的平台：Xbox One 系列主机和 Xbox Series 主机

另请参阅

XDisplayHdrModePreference
XDisplayHdrModeInfo
XDisplayHdrModeResult
XDisplay