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 が無効です。 有効なフラグの組み合わせの説明については、以下を参照してください。
次の一覧には、 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 フラグを無視します。
戻り値
関数は、次のいずれかの戻りコードを返します。
| リターン コード | 説明 |
|---|---|
|
関数が正常に実行されました。 |
|
指定されたパラメーターとフラグの組み合わせが無効です。 |
|
システムでは、 Windows ディスプレイ ドライバー モデル (WDDM) に従って記述されたグラフィックス ドライバーが実行されていません。 関数は、WDDM ドライバーが実行されているシステムでのみサポートされます。 |
|
呼び出し元はコンソール セッションにアクセスできません。 このエラーは、呼び出し元のプロセスが現在のデスクトップにアクセスできない場合、またはリモート セッションで実行されている場合に発生します。 |
|
未指定のエラーが発生しました。 |
|
関数は、呼び出し元が指定しなかったソース モードとターゲット モードの実行可能なソリューションを見つけることができませんでした。 |
解説
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_PATH_SOURCE_INFO