XDisplayTryEnableHdrMode

[アーティクル]
05/09/2023

接続されたディスプレイで HDR (高ダイナミックレンジ) モードの有効化を試みます。

構文

XDisplayHdrModeResult XDisplayTryEnableHdrMode(  
         XDisplayHdrModePreference displayModePreference,  
         XDisplayHdrModeInfo* displayHdrModeInfo  
)

パラメーター

displayModePreference _In_
型: XDisplayHdrModePreference

接続されているテレビが HDR と 120Hz まで向上させたフレームレートの両方をサポートしていない場合に、そのどちらかを優先するために使用される列挙型。

displayHdrModeInfo _Out_opt_
型: XDisplayHdrModeInfo*

HDR モードが有効化される場合の、接続されたディスプレイでの HDR (高ダイナミックレンジ) モードに対する最小と最大のトーンマッピング輝度値。

戻り値

型: XDisplayHdrModeResult

関数が成功した場合、戻り値は、HDR が有効になっている場合は XDisplayHdrModeResult::Enabled に設定され、HDR が有効になっていない場合は XDisplayHdrModeResult::Disabled に設定されます。関数が失敗した場合、戻り値は XDisplayHdrModeResult::Unknown に設定されます。

解説

注意

この関数は、時間依存のスレッドで呼び出すのに安全ではありません。詳細については、「時間依存のスレッド」を参照してください。

displayModePreference パラメーターは、HDR と 120Hz のリフレッシュレートの両方を同時にサポートしていないテレビで、そのどちらか一方を優先する方法を提供します。

次の例では、開発者は現在のタイトルに対して 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 をサポートしていて、開発者またはエンドユーザーが現在のシナリオに対して 120 Hz を優先するように指定している (たとえば、ゲーム内設定またはゲームモードの設定 [Prefer Performance])。

次のような場合は、別の設定を使用してもう一度 XDisplayTryEnableHdrMode を呼び出します。

何らかの変更が行われて、設定が変更された。最も可能性が高いのは、ユーザーがゲーム内設定を [Prefer Quality] から [Prefer Performance] に変更したことです。

注意

XDisplayTryEnableHdrMode を呼び出して、各フレームを切り替えないでください。変更するのは、特別な理由がある場合のみにします。

XDisplayTryEnableHdrMode を呼び出した後、IDXGIOutput::GetDisplayModeList を呼び出して、120Hz がサポートされていることを確認します。

XDisplayTryEnableHdrMode 関数からは、接続されたディスプレイの HDR モードを関数で有効にできるかどうかを示す XDisplayHdrModeResult 列挙値が返されます。 XDisplayHdrModeResult::Enabled が返された場合、関数ではディスプレイの HDR モードに関する情報が格納されている XDisplayHdrModeInfo 構造体も提供され、それには HDR モードに対する最小と最大のトーンマッピング輝度値が含まれます。既定では、HDR モードが有効になっている場合、XDisplayTryEnableHdrMode 関数からは XDisplayHdrModeInfo のメンバーに対して次の値が返されます。

メンバー	値
minToneMapLuminance	0.01
maxToneMapLuminance	1,000
maxFullFrameToneMapLuminance	1,000

HDR の輝度値とトーンマッピングの詳細については、HDR Gaming Interest Group の Web サイトのよりよい 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 本体

次の方法で共有

XDisplayTryEnableHdrMode

構文

パラメーター

戻り値

解説

要件

関連項目

その他のリソース