ChangeDisplaySettingsExA 関数 (winuser.h)

  • [アーティクル]

ChangeDisplaySettingsEx 関数は、指定したディスプレイ デバイスの設定を指定したグラフィックス モードに変更します。

メモWindows 8以降をターゲットにするように設計したアプリでは、1 ピクセルあたり 32 ビット (bpp) 未満の表示モードに対してクエリを実行したり設定したりできなくなりました。これらの操作は失敗します。 これらのアプリには、Windows 8を対象とする互換性マニフェストがあります。 Windows 8では、Windows 8 マニフェストなしでビルドされたデスクトップ アプリの 8 ビットと 16 ビットのカラー モードが引き続きサポートされます。Windows 8は、これらのモードをエミュレートしますが、32 ビット カラー モードで実行されます。
 

構文

LONG ChangeDisplaySettingsExA(
  [in] LPCSTR   lpszDeviceName,
  [in] DEVMODEA *lpDevMode,
       HWND     hwnd,
  [in] DWORD    dwflags,
  [in] LPVOID   lParam
);

パラメーター

[in] lpszDeviceName

グラフィックス モードが変更されるディスプレイ デバイスを指定する null で終わる文字列へのポインター。 EnumDisplayDevices によって返される表示デバイス名のみが有効です。 これらのディスプレイ デバイスに関連付けられている名前の詳細については、「 EnumDisplayDevices 」を参照してください。

lpszDeviceName パラメーターには NULL を指定できます。 NULL 値は、既定の表示デバイスを指定します。 既定のデバイスは、 EnumDisplayDevices を呼び出し、DISPLAY_DEVICE_PRIMARY_DEVICE フラグを確認することによって決定できます。

[in] lpDevMode

新しいグラフィックス モードを記述する DEVMODE 構造体へのポインター。 lpDevMode が NULL の場合、レジストリに現在存在するすべての値が表示設定に使用されます。 lpDevMode パラメーターに NULL を渡し、dwFlags パラメーターに 0 を渡すことが、動的モードの変更後に既定のモードに戻る最も簡単な方法です。

dmSize メンバーは、DEVMODE 構造体のサイズ (バイト単位) に初期化する必要があります。 DMDriverExtra メンバーは、DEVMODE 構造体に続くプライベート ドライバー データのバイト数を示すために初期化する必要があります。 さらに、 DEVMODE 構造体の次のいずれかのメンバーを使用できます。

メンバー 意味
dmBitsPerPel ピクセルあたりのビット数
dmPelsWidth ピクセル幅
dmPelsHeight ピクセルの高さ
dmDisplayFlags モード フラグ
dmDisplayFrequency モードの頻度
dmPosition マルチモニター構成でのデバイスの位置。
 

上記の DEVMODE メンバーの 1 つ以上を使用するだけでなく、 dmFields メンバーに次の 1 つ以上の値を設定して表示設定を変更する必要もあります。

値 意味
DM_BITSPERPEL dmBitsPerPel 値を使用します。
DM_PELSWIDTH dmPelsWidth 値を使用します。
DM_PELSHEIGHT dmPelsHeight 値を使用します。
DM_DISPLAYFLAGS dmDisplayFlags 値を使用します。
DM_DISPLAYFREQUENCY dmDisplayFrequency 値を使用します。
DM_POSITION dmPosition 値を使用します。

hwnd

予約; は NULL である必要があります。

[in] dwflags

グラフィックス モードを変更する方法を示します。 このパラメーターには、次の値のいずれかを指定できます。

値 意味
0
 現在の画面のグラフィックス モードは動的に変更されます。
CDS_FULLSCREEN
 モードは本質的に一時的なものです。

別のデスクトップとの間で切り替える場合、このモードはリセットされません。
CDS_GLOBAL
 設定は、コンピューター上のすべてのユーザーに影響を与えるように、グローバル設定領域に保存されます。 それ以外の場合は、ユーザーの設定のみが変更されます。 このフラグは、CDS_UPDATEREGISTRY フラグで指定した場合にのみ有効です。
CDS_NORESET
 設定はレジストリに保存されますが、有効になりません。 このフラグは、CDS_UPDATEREGISTRY フラグで指定した場合にのみ有効です。
CDS_RESET
 要求された設定が現在の設定と同じ場合でも、設定を変更する必要があります。
CDS_SET_PRIMARY
 このデバイスはプライマリ デバイスになります。
CDS_TEST
 システムは、要求されたグラフィックス モードを設定できるかどうかをテストします。
CDS_UPDATEREGISTRY
 現在の画面のグラフィックス モードは動的に変更され、グラフィックス モードはレジストリで更新されます。 モード情報は USER プロファイルに格納されます。
CDS_VIDEOPARAMETERS
 設定すると、 lParam パラメーターは VIDEOPARAMETERS 構造体へのポインターです。
CDS_ENABLE_UNSAFE_MODES
 安全でないグラフィックス モードの設定変更を有効にします。
CDS_DISABLE_UNSAFE_MODES
 安全でないグラフィックス モードの設定変更を無効にします。
 

CDS_TESTを指定すると、アプリケーションは、システムを変更することなく、実際に有効なグラフィックス モードを決定できます。

CDS_UPDATEREGISTRYを指定し、グラフィックス モードを動的に変更できる場合は、情報がレジストリに格納され、DISP_CHANGE_SUCCESSFULが返されます。 グラフィックス モードを動的に変更できない場合は、情報がレジストリに格納され、DISP_CHANGE_RESTARTが返されます。

CDS_UPDATEREGISTRYを指定し、情報をレジストリに格納できなかった場合、グラフィックス モードは変更されず、DISP_CHANGE_NOTUPDATEDが返されます。

[in] lParam

dwFlags がCDS_VIDEOPARAMETERS場合、lParam は VIDEOPARAMETERS 構造体へのポインターです。 それ以外の場合 、lParam は NULL である必要があります。

戻り値

ChangeDisplaySettingsEx 関数は、次のいずれかの値を返します。

リターン コード 説明
DISP_CHANGE_SUCCESSFUL
 設定の変更が成功しました。
DISP_CHANGE_BADDUALVIEW
 システムが DualView 対応であるため、設定の変更は失敗しました。
DISP_CHANGE_BADFLAGS
 無効なフラグのセットが渡されました。
DISP_CHANGE_BADMODE
 グラフィックス モードはサポートされていません。
DISP_CHANGE_BADPARAM
 無効なパラメーターが渡されました。 これには、無効なフラグやフラグの組み合わせが含まれる場合があります。
DISP_CHANGE_FAILED
 ディスプレイ ドライバーは、指定されたグラフィックス モードに失敗しました。
DISP_CHANGE_NOTUPDATED
 レジストリに設定を書き込むことができません。
DISP_CHANGE_RESTART
 グラフィックス モードを機能させるには、コンピューターを再起動する必要があります。

注釈

ChangeDisplaySettingsEx に渡される DEVMODE 構造体が有効であり、ディスプレイ ドライバーでサポートされている値のみが含まれていることを確認するには、EnumDisplaySettings 関数によって返される DEVMODE を使用します。

プログラムで複数モニター・システムにモニターを追加する場合は、 DEVMODE.dmFields をDM_POSITIONに設定し、追加するモニターの位置 ( DEVMODE.dmPosition 内) を、既存のモニターの表示領域の少なくとも 1 ピクセルに隣接する位置に指定します。 モニターをデタッチするには、 DEVMODE.dmFields を DM_POSITION に設定しますが、 DEVMODE.dmPelsWidth と DEVMODE.dmPelsHeight を 0 に設定します。 詳細については、「 複数のディスプレイ モニター」を参照してください。

表示モードが動的に変更されると、 WM_DISPLAYCHANGE メッセージは、次のメッセージ パラメーターを使用して実行中のすべてのアプリケーションに送信されます。

パラメーター 説明
wParam ピクセルあたりの新しいビット数
LOWORD(lParam) 新しいピクセル幅
HIWORD(lParam) 新しいピクセルの高さ
 

複数のディスプレイの設定を同時に変更するには、最初にデバイスごとに ChangeDisplaySettingsEx を呼び出して、変更を適用せずにレジストリを更新します。 次に、NULL デバイスを使用して ChangeDisplaySettingsEx をもう一度呼び出して、変更を適用します。 たとえば、2 つのディスプレイの設定を変更するには、次の操作を行います。


ChangeDisplaySettingsEx (lpszDeviceName1, lpDevMode1, NULL, (CDS_UPDATEREGISTRY | CDS_NORESET), NULL);
ChangeDisplaySettingsEx (lpszDeviceName2, lpDevMode2, NULL, (CDS_UPDATEREGISTRY | CDS_NORESET), NULL);
ChangeDisplaySettingsEx (NULL, NULL, NULL, 0, NULL);

DPI 仮想化

この API は、DPI 仮想化には参加しません。 指定された入力は常に物理ピクセルの観点からであり、呼び出し元のコンテキストには関連しません。

注意

winuser.h ヘッダーは、Unicode プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択するエイリアスとして ChangeDisplaySettingsEx を定義します。 エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイム エラーが発生する不一致が発生する可能性があります。 詳細については、「 関数プロトタイプの規則」を参照してください。

要件

要件 値
サポートされている最小のクライアント Windows 2000 Professional [デスクトップ アプリのみ]
サポートされている最小のサーバー Windows 2000 Server [デスクトップ アプリのみ]
対象プラットフォーム Windows
ヘッダー 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 で導入)

こちらもご覧ください

CreateDC

Devmode

デバイス コンテキスト関数

デバイス コンテキストの概要

EnumDisplayDevices

EnumDisplaySettings

VIDEOPARAMETERS

WM_DISPLAYCHANGE