> ## 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 (高動態範圍) 模式。

## 語法

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

### 參數

*displayModePreference*   \_In\_\
類型：[XDisplayHdrModePreference](/zh-TW/reference/system/xdisplay/enums/xdisplayhdrmodepreference)

在連接的電視不支援同時使用兩者的情況下，用來偏好 HDR 或最高 120Hz 之改善畫面播放速率的列舉。

*displayHdrModeInfo*   \_Out\_opt\_\
類型：[XDisplayHdrModeInfo\*](/zh-TW/reference/system/xdisplay/structs/xdisplayhdrmodeinfo)

如果已啟用 HDR 模式，則為連接之顯示器的最小和最大色調對應亮度值。

### 傳回值

類型：[XDisplayHdrModeResult](/zh-TW/reference/system/xdisplay/enums/xdisplayhdrmoderesult)

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

## 備註

<Note>在時間敏感執行緒上呼叫此函式並不安全。如需詳細資訊，請參閱[時間敏感執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)。</Note>

*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](/zh-TW/reference/system/xdisplay/enums/xdisplayhdrmodepreference)：

* 您的遊戲只實作 HDR，完全不支援 120hz。
* 使用者已在遊戲內設定中表示不想要 120Hz 重新整理頻率，或偏好 HDR (例如偏好品質勝過效能)。
* 遊戲處於不支援 120Hz 重新整理頻率的遊戲模式中。

在下列情況下，遊戲應使用 [XDisplayHdrModePreference::PreferRefreshRate](/zh-TW/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](/zh-TW/reference/system/xdisplay/structs/xdisplayhdrmodeinfo) 結構，其中包含顯示器 HDR 模式的相關資訊，包括 HDR 模式的最小和最大色調對應亮度值。根據預設，如果已啟用 HDR 模式，**XDisplayTryEnableHdrMode** 函式會為 **XDisplayHdrModeInfo** 的成員傳回下列值：

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

如需 HDR 亮度值和色調對應的詳細資訊，請參閱 [HDR Gaming Interest Group](https://www.hgig.org/) 網站上的 [For a Better HDR Gaming Experience](https://www.hgig.org/doc/ForBetterHDRGaming.pdf) 簡報。

下列範例會嘗試為連接的顯示器啟用 HDR 模式。如果傳回 [XDisplayHdrModeInfo::Enabled](/zh-TW/reference/system/xdisplay/enums/xdisplayhdrmoderesult)，表示已為顯示器啟用 HDR 模式，遊戲會使用所傳回 [XDisplayHdrModeInfo](/zh-TW/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 主題)](/zh-TW/build/core-features/graphics/overviews/hdr-support)。

## 需求

**標頭：** XDisplay.h

**程式庫：** xgameruntime.lib

**支援的平台：** XBOX One 系列主機和 XBOX Series 主機

## 概念文件

* [時間敏感執行緒](https://learn.microsoft.com/gaming/gdk/docs/gdk-dev/console-dev/overviews/threads/time-sensitive-threads)

## 另請參閱

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


## Related topics

- [XDisplayTryEnableHdrMode](/ja-jp/reference/system/xdisplay/functions/xdisplaytryenablehdrmode.md)
- [XDisplayHdrModeResult](/reference/system/xdisplay/enums/xdisplayhdrmoderesult.md)
- [XDisplayHdrModeInfo](/reference/system/xdisplay/structs/xdisplayhdrmodeinfo.md)