ChangeDisplaySettingsA 関数 (winuser.h)

[アーティクル]
03/15/2023

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

指定したディスプレイデバイスの設定を変更するには、 ChangeDisplaySettingsEx 関数を使用します。

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

構文

LONG ChangeDisplaySettingsA(
  [in] DEVMODEA *lpDevMode,
  [in] DWORD    dwFlags
);

パラメーター

[in] lpDevMode

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

DEVMODE の dmSize メンバーは、DEVMODE 構造体のサイズ (バイト単位) に初期化する必要があります。 DEVMODE 構造体に続くプライベートドライバーデータのバイト数を示すために、DEVMODE の dmDriverExtra メンバーを初期化する必要があります。さらに、 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 値を使用します。

[in] dwFlags

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

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

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

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

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

戻り値

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

リターンコード	説明
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	グラフィックスモードを機能させるには、コンピューターを再起動する必要があります。

注釈

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

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

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

DPI 仮想化

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

注意

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

要件

要件	値
サポートされている最小のクライアント	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 で導入)