Skip to main content

XDisplayTryEnableHdrMode

嘗試為連接的顯示器啟用 HDR (高動態範圍) 模式。

語法

參數

displayModePreference   _In_
類型:XDisplayHdrModePreference
在連接的電視不支援同時使用兩者的情況下,用來偏好 HDR 或最高 120Hz 之改善畫面播放速率的列舉。 displayHdrModeInfo   _Out_opt_
類型:XDisplayHdrModeInfo*
如果已啟用 HDR 模式,則為連接之顯示器的最小和最大色調對應亮度值。

傳回值

類型:XDisplayHdrModeResult 如果函式成功,當 HDR 模式已啟用時,傳回值會設定為 XDisplayHdrModeResult::Enabled;當 HDR 模式未啟用時,則設定為 XDisplayHdrModeResult::Disabled。如果函式失敗,傳回值會設定為 XDisplayHdrModeResult::Unknown。

備註

在時間敏感執行緒上呼叫此函式並不安全。如需詳細資訊,請參閱時間敏感執行緒。
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 Gaming Interest Group 網站上的 For a Better HDR Gaming Experience 簡報。 下列範例會嘗試為連接的顯示器啟用 HDR 模式。如果傳回 XDisplayHdrModeInfo::Enabled,表示已為顯示器啟用 HDR 模式,遊戲會使用所傳回 XDisplayHdrModeInfo 結構中的亮度值以 HDR 模式初始化;否則,表示 HDR 模式無法使用或已停用,遊戲會以 SDR (標準動態範圍) 模式初始化。
如需 HDR 支援的詳細資訊,請參閱高動態範圍 (HDR) 輸出 (NDA 主題)。

需求

標頭: XDisplay.h 程式庫: xgameruntime.lib 支援的平台: XBOX One 系列主機和 XBOX Series 主機

概念文件

另請參閱

XDisplayHdrModePreference
XDisplayHdrModeInfo
XDisplayHdrModeResult
XDisplay
Last modified on October 6, 2026