Skip to main content

XDisplayTryEnableHdrMode

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

Syntax

Parameters

displayModePreference   _In_
类型:XDisplayHdrModePreference
在连接的电视不同时支持这两种情况下,用于偏向 HDR 或高达 120Hz 的更高帧速率的枚举。 displayHdrModeInfo   _Out_opt_
类型:XDisplayHdrModeInfo*
如果启用了 HDR 模式,则为附加显示器的最小和最大色调映射亮度值。

Return value

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

Remarks

此函数在时间敏感线程上调用不安全。有关详细信息,请参阅时间敏感线程
对于不能同时支持 HDR 和 120Hz 刷新率的电视,displayModePreference 参数提供了偏好 HDR 120Hz 刷新率的方式。 在下面的示例中,开发人员尝试为当前标题启用 HDR 模式,并声明偏好 HDR 而不是更高的帧速率(在无法同时实现两者的情况下)。
以下情况下,标题应使用 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 的成员返回以下值: 有关 HDR 亮度值和色调映射的详细信息,请参阅 HDR 游戏兴趣小组网站上的 For a Better HDR Gaming Experience 演示文稿。 以下示例尝试为附加的显示器启用 HDR 模式。如果返回 XDisplayHdrModeInfo::Enabled,则表示已为显示器启用 HDR 模式,游戏将使用返回的 XDisplayHdrModeInfo 结构中的亮度值以 HDR 模式初始化;否则,HDR 模式不可用或已禁用,游戏将以 SDR(标准动态范围)模式初始化。
有关 HDR 支持的详细信息,请参阅高动态范围 (HDR) 输出(NDA 主题)

Requirements

头文件: XDisplay.h 库: xgameruntime.lib 受支持的平台: XBOX One 系列主机和 XBOX Series 主机

Conceptual documentation

See also

XDisplayHdrModePreference
XDisplayHdrModeInfo
XDisplayHdrModeResult
XDisplay
最后修改于 2026年8月24日