次の方法で共有


SetDisplayConfig 関数 (winuser.h)

SetDisplayConfig 関数は、現在のセッションで指定されたパスのみを有効にすることで、表示トポロジ、ソース、およびターゲット モードを変更します。

構文

LONG SetDisplayConfig(
  [in]           UINT32                  numPathArrayElements,
  [in, optional] DISPLAYCONFIG_PATH_INFO *pathArray,
  [in]           UINT32                  numModeInfoArrayElements,
  [in, optional] DISPLAYCONFIG_MODE_INFO *modeInfoArray,
  [in]           UINT32                  flags
);

パラメーター

[in] numPathArrayElements

pathArray 内の要素の数。

[in, optional] pathArray

設定するすべての表示パスの配列。 DISPLAYCONFIG_PATH_INFOの flags メンバーにDISPLAYCONFIG_PATH_ACTIVE フラグが 設定されている、 この配列内のパスのみが設定されます。 このパラメーターは、NULL でもかまいません。 この配列にアクティブなパスが表示される順序によって、パスの優先順位が決まります。 パスの優先順位の詳細については、「 パスの優先順位」を参照してください。

[in] numModeInfoArrayElements

modeInfoArray 内の要素の数。

[in, optional] modeInfoArray

DISPLAYCONFIG_PATH_SOURCE_INFO の modeInfoIdx メンバーによって参照される表示ソースおよびターゲット モード情報 (DISPLAYCONFIG_MODE_INFO) と pathArray からのパス情報のDISPLAYCONFIG_PATH_TARGET_INFO要素の配列。 このパラメーターは、NULL でもかまいません。

[in] flags

この関数の動作を示すフラグ値のビットごとの OR。 このパラメーターには、次の値のいずれか、または次の値の組み合わせを指定できます。0 が無効です。 有効なフラグの組み合わせの説明については、以下を参照してください。

説明
SDC_APPLY
0x00000080
結果として得られるトポロジ、ソース、ターゲット モードが設定されます。
SDC_NO_OPTIMIZATION
0x00000100
SDC_APPLY フラグの修飾子。 これにより、変更モードは、アクティブなディスプレイごとにドライバーまで強制的にダウンします。
SDC_USE_SUPPLIED_DISPLAY_CONFIG
0x00000020
データベース内の構成を調べるのではなく、 pathArray パラメーターと modeInfoArray パラメーターで提供されるトポロジ、ソース、およびターゲット モードの情報が使用されます。
SDC_SAVE_TO_DATABASE
0x00000200
結果として得られるトポロジ、ソース、およびターゲット モードは、データベースに保存されます。
SDC_VALIDATE
0x00000040
システムは、要求されたトポロジ、ソース、ターゲット モードの情報をテストして、設定できるかどうかを判断します。
SDC_ALLOW_CHANGES
0x00000400
必要に応じて、関数は、機能表示パス・セットを作成するために、指定されたソース・モードおよびターゲット・モード情報を変更できます。
SDC_TOPOLOGY_CLONE
0x00000002
呼び出し元は、永続化データベースから最後の複製構成を要求します。
SDC_TOPOLOGY_EXTEND
0x00000004
呼び出し元は、永続化データベースから最後の拡張構成を要求します。
SDC_TOPOLOGY_INTERNAL
0x00000001
呼び出し元は、永続化データベースから最後の内部構成を要求します。
SDC_TOPOLOGY_EXTERNAL
0x00000008
呼び出し元は、永続化データベースから最後の外部構成を要求します。
SDC_TOPOLOGY_SUPPLIED
0x00000010
呼び出し元はパス データを提供するため、関数は永続化データベースに対してのみクエリを実行して、ソース モードとターゲット モードを検索して使用します。
SDC_USE_DATABASE_CURRENT
(SDC_TOPOLOGY_INTERNAL |SDC_TOPOLOGY_CLONE |SDC_TOPOLOGY_EXTEND |SDC_TOPOLOGY_EXTERNAL)
呼び出し元は、4 つのSDC_TOPOLOGY_XXX構成の組み合わせを要求します。 この値は、現在接続されているモニターの最後の既知の表示構成を設定するように API に通知します。
SDC_PATH_PERSIST_IF_REQUIRED
0x00000800
関数は、SDC_TOPOLOGY_XXX要求を処理するときに、必要に応じて要求を満たすためにターゲットに対するパスの永続化を強制できます。 このフラグを組み合わせることができるその他のフラグについては、次の一覧を参照してください。
SDC_FORCE_MODE_ENUMERATION
0x00001000
呼び出し元は、 SetDisplayConfig が新しい表示構成を設定している間に、ドライバーに GDI モードの一覧を更新する機会が与えられるよう要求します。 このフラグ値は、SDC_USE_SUPPLIED_DISPLAY_CONFIGおよびSDC_APPLYフラグ値も指定されている場合にのみ有効です。
SDC_ALLOW_PATH_ORDER_CHANGES
0x00002000
データベースを検索するときに 、SetDisplayConfig が指定されたトポロジのパス順序を無視する必要があることを示す、SDC_TOPOLOGY_SUPPLIED フラグの修飾子。 このフラグが設定されている場合、トポロジ セットは、パスの順序に関係なく、すべてのパスを含む最新のトポロジです。
SDC_VIRTUAL_MODE_AWARE
0x00008000
呼び出し元が仮想モードを認識しているSDC_USE_SUPPLIED_DISPLAY_CONFIGとSDC_TOPOLOGY_SUPPLIEDフラグの修飾子。 Windows 10 以降でサポートされています。
SDC_VIRTUAL_REFRESH_RATE_AWARE
0x00020000
呼び出し元が仮想リフレッシュ レートを認識しているSDC_USE_SUPPLIED_DISPLAY_CONFIGとSDC_TOPOLOGY_SUPPLIEDフラグの修飾子。 Windows 11 以降でサポートされています。

次の一覧には、 Flags パラメーターの有効な値の組み合わせが含まれています。

  • SDC_APPLYまたはSDC_VALIDATEを設定する必要がありますが、両方を設定する必要はありません。
  • SDC_USE_SUPPLIED_DISPLAY_CONFIGまたはSDC_TOPOLOGY_XXXの任意の組み合わせを設定する必要があります。 SDC_USE_SUPPLIED_DISPLAY_CONFIGは、どのSDC_TOPOLOGY_XXX フラグでも設定できません。
  • SDC_NO_OPTIMIZATIONは、SDC_APPLYでのみ設定できます。
  • SDC_ALLOW_CHANGESは、他の有効な組み合わせでも使用できます。
  • SDC_SAVE_TO_DATABASEは、SDC_USE_SUPPLIED_DISPLAY_CONFIGでのみ設定できます。
  • SDC_PATH_PERSIST_IF_REQUIREDは、SDC_USE_SUPPLIED_DISPLAY_CONFIGやSDC_TOPOLOGY_SUPPLIEDでは使用できません。
  • SDC_FORCE_MODE_ENUMERATIONは、SDC_APPLYとSDC_USE_SUPPLIED_DISPLAY_CONFIGが指定されている場合にのみ有効です。
  • SDC_ALLOW_PATH_ORDER_CHANGESは、SDC_TOPOLOGY_SUPPLIEDが指定されている場合にのみ許可されます。
  • SDC_TOPOLOGY_SUPPLIEDを他のSDC_TOPOLOGY_XXX フラグと共に使用することはできません。 検証の問題のため、呼び出し元がこの規則に違反した場合、 SetDisplayConfig は失敗しません。 ただし、 SetDisplayConfig は SDC_TOPOLOGY_SUPPLIED フラグを無視します。
SDC_TOPOLOGY_XXXフラグは組み合わせて使用できます。 たとえば、SDC_TOPOLOGY_CLONEとSDC_TOPOLOGY_EXTENDが設定されている場合、API は最新の複製または拡張トポロジを使用します。これは、すべてのトポロジが現在の接続モニターに対して最後に設定されたトポロジです。

戻り値

関数は、次のいずれかの戻りコードを返します。

リターン コード 説明
ERROR_SUCCESS
関数が正常に実行されました。
ERROR_INVALID_PARAMETER
指定されたパラメーターとフラグの組み合わせが無効です。
ERROR_NOT_SUPPORTED
システムでは、 Windows ディスプレイ ドライバー モデル (WDDM) に従って記述されたグラフィックス ドライバーが実行されていません。 関数は、WDDM ドライバーが実行されているシステムでのみサポートされます。
ERROR_ACCESS_DENIED
呼び出し元はコンソール セッションにアクセスできません。 このエラーは、呼び出し元のプロセスが現在のデスクトップにアクセスできない場合、またはリモート セッションで実行されている場合に発生します。
ERROR_GEN_FAILURE
未指定のエラーが発生しました。
ERROR_BAD_CONFIGURATION
関数は、呼び出し元が指定しなかったソース モードとターゲット モードの実行可能なソリューションを見つけることができませんでした。

解説

SetDisplayConfig 関数は、指定されたソース モードとターゲット モード情報を含むアクティブな表示パスを受け取り、最適なモード ロジックを使用して、不足しているソース モードとターゲット モードの情報を生成します。 この関数は、完全な表示パスを設定します。

DISPLAYCONFIG_PATH_SOURCE_INFO および DISPLAYCONFIG_PATH_TARGET_INFO 構造体の ModeInfoIdx メンバーは、特定のアクティブ パスに対してソース モードとターゲット モードが指定されているかどうかを示すために使用されます。 いずれかのインデックス値がDISPLAYCONFIG_PATH_MODE_IDX_INVALIDされている場合は、モード情報が指定されていないことを示します。 パスとソース モード、または特定のパスに対して指定するパスとソース モードとターゲット モードの情報に対して有効です。 ただし、ソース モードなしでパスとターゲット モードを指定することはできません。

各ソース識別子とターゲット識別子のソース モードとターゲット モードは、 modeInfoArray 配列に 1 回だけ表示できます。 たとえば、ソース識別子 S1 のソース モードは、テーブルに 1 回だけ表示できます。複数のパスが同じソースを参照する場合は、同じ ModeInfoIdx を使用する必要があります。

ほとんどの呼び出し元では 、QueryDisplayConfig を使用して現在の構成を他の有効な可能性と共に取得し 、SetDisplayConfig を使用して構成をテストおよび設定することが想定されています。

PathArray 配列にアクティブなパスが表示される順序によって、パスの優先順位が決まります。

既定では、 SetDisplayConfig は指定されたパス、ソース モード、またはターゲット モードの情報を変更しません。 指定した表示パス情報を変更しないと、最適なモード ロジックでソリューションが見つからない場合、 SetDisplayConfig はERROR_BAD_CONFIGURATIONで失敗します。 この場合、呼び出し元は SDC_ALLOW_CHANGES フラグを指定して、指定したソースとモードの詳細の一部を関数が調整して、表示パスの変更を成功させる必要があります。

指定したモードまたは計算されるソース モードとターゲット モードのディメンションが同じである場合、 SetDisplayConfig は 、表示パスを設定してデータベースに保存する前に、パスのスケーリングをDISPLAYCONFIG_PPR_IDENTITYに自動的に設定します。 SetDisplayConfig によるスケーリングの処理方法については、「デスクトップ イメージのスケーリング」を参照してください。

呼び出し元がクローン パスを設定するために SDC_USE_SUPPLIED_DISPLAY_CONFIG フラグを指定し、パス配列内のソース モード インデックスが無効な場合、 SetDisplayConfig は、そのソースのすべてのソース モード インデックスが無効であると判断します。 SetDisplayConfig は、最適なモード ロジックを使用してソース モード情報を決定します。

SDC_TOPOLOGY_SUPPLIED フラグ (SDC_TOPOLOGY_SUPPLIEDの詳細については、次の段落を参照) を除き、SDC_TOPOLOGY_XXX フラグは、そのトポロジの種類のソース モードとターゲット モードの情報など、最後の表示パス設定を設定します。 有効なSDC_TOPOLOGY_XXXフラグの組み合わせについては、 Flags パラメーターの説明を参照してください。 pathArray パラメーターと modeInfoArray パラメーターは NULL で、関連するサイズは 0 である必要があります。 たとえば、SDC_TOPOLOGY_CLONEとSDC_TOPOLOGY_EXTENDが設定されている場合、この関数は最新の複製を使用するか、表示パスの構成を拡張します。 1 つのトポロジの種類が要求された場合は、その型の最後の構成が使用されます。 そのトポロジがこれまでに設定されていない場合、 SetDisplayConfig は最適なトポロジ ロジックを使用して最適なトポロジを見つけ、最適なモード ロジックを使用して最適なソース モードとターゲット モードを見つけます。 トポロジ フラグの組み合わせが設定されていて、いずれもデータベース エントリがない場合は、次の優先順位が使用されます。 ノート PC の場合: 複製、拡張、内部、外部。デスクトップの場合、優先度は拡張され、複製されます。

呼び出し元は、パス情報 (トポロジ) のみを設定し、 SetDisplayConfig が永続化データベースからソース モードとターゲット モード情報を取得して使用するように要求することを示すために、SDC_TOPOLOGY_SUPPLIED フラグを指定できます。 呼び出し元が提供するアクティブパスに永続性データベースにエントリがない場合、 SetDisplayConfig は失敗します。 この場合、呼び出し元が同じパス データを使用して SetDisplayConfig をもう一度呼び出すが、SDC_USE_SUPPLIED_DISPLAY_CONFIG フラグが設定されている場合、 SetDisplayConfig はソース モードとターゲット モードの情報を作成するために最適なモード ロジックを使用します。 呼び出し元がSDC_TOPOLOGY_SUPPLIEDを指定する場合、呼び出し元は numModeInfoArrayElements パラメーターを 0 に、 modeInfoArray パラメーターを NULL に設定する必要があります。ただし、呼び出し元は、呼び出し元が必要とするパス情報の pathArray パラメーターと numPathArrayElements パラメーターを設定する必要があります。 呼び出し元は、このパス データ内のすべてのソース およびターゲット モードのインデックスを無効 (DISPLAYCONFIG_PATH_MODE_IDX_INVALID) としてマークする必要があります。

次の表では、 SetDisplayConfig が呼び出される一般的なシナリオと、シナリオを実現するために呼び出し元が Flags パラメーターに渡す フラグ の組み合わせを示します。

シナリオ フラグの組み合わせ
指定した表示構成がコンピューターでサポートされているかどうかをテストする SDC_VALIDATE |SDC_USE_SUPPLIED_DISPLAY_CONFIG
指定した表示構成を設定し、データベースに保存する SDC_APPLY |SDC_USE_SUPPLIED_DISPLAY_CONFIG |SDC_SAVE_TO_DATABASE
一時的な表示構成を設定する (つまり、表示構成は保存されません) SDC_APPLY |SDC_USE_SUPPLIED_DISPLAY_CONFIG
コンピューターで複製がサポートされているかどうかをテストする SDC_VALIDATE |SDC_TOPOLOGY_CLONE
複製トポロジを設定する SDC_APPLY |SDC_TOPOLOGY_CLONE
要求を満たすために必要な場合は、複製トポロジを設定し、パスの永続化を有効にします SDC_APPLY |SDC_TOPOLOGY_CLONE |SDC_PATH_PERSIST_IF_REQUIRED
一時モードから最後に保存された表示構成に戻る SDC_APPLY|SDC_USE_DATABASE_CURRENT
パス情報のみを指定した場合は、データベースのソース情報とターゲット情報を使用してパスの表示構成を設定し、パスの順序を無視します SDC_APPLY |SDC_TOPOLOGY_SUPPLIED |SDC_ALLOW_PATH_ORDER_CHANGES
 

DPI 仮想化

この API は、DPI 仮想化には参加しません。 DEVMODE 構造体内のすべてのサイズは、物理ピクセルの観点から見たものであり、呼び出し元のコンテキストには関連しません。

要件

   
サポートされている最小のクライアント Windows 7 以降のバージョンの Windows オペレーティング システムで使用できます。
対象プラットフォーム ユニバーサル
Header winuser.h (Windows.h を含む)
Library User32.lib
[DLL] User32.dll
API セット ext-ms-win-ntuser-sysparams-ext-l1-1-1 (Windows 10 バージョン 10.0.14393 で導入)

関連項目

DISPLAYCONFIG_MODE_INFO

DISPLAYCONFIG_PATH_INFO

DISPLAYCONFIG_PATH_SOURCE_INFO

DISPLAYCONFIG_PATH_TARGET_INFO

QueryDisplayConfig