ChangeDisplaySettingsA 函数（winuser.h）

项目
11/20/2024

ChangeDisplaySettings 函数将默认显示设备的设置更改为指定的图形模式。

若要更改指定显示设备的设置，请使用 ChangeDisplaySettingsEx 函数。

注意设计为面向 Windows 8 及更高版本的应用无法再查询或设置每个像素小于 32 位的显示模式（bpp）：这些操作将失败。这些应用具有面向 Windows 8 的兼容性清单。对于在没有 Windows 8 清单的情况下生成的桌面应用，Windows 8 仍支持 8 位和 16 位颜色模式;Windows 8 模拟这些模式，但仍以 32 位颜色模式运行。

语法

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

参数

[in] lpDevMode

指向描述新图形模式的 DEVMODE 结构的指针。如果 lpDevModeNULL，则注册表中当前的所有值都将用于显示设置。为 lpDevMode 参数传递 NULL，对于 dwFlags 参数，传递 0 是动态模式更改后返回默认模式的最简单方法。

dmSizeDEVMODE 的成员必须初始化为 DEVMODE 结构的大小（以字节为单位）。必须初始化 DEVMODE 的 dmDriverExtra 成员，以指示 DEVMODE 结构之后专用驱动程序数据的字节数。此外，可以使用以下 DEVMODE 结构的任何或全部成员。

成员	意义
dmBitsPerPel	每个像素的位数
dmPelsWidth	像素宽度
dmPelsHeight	像素高度
dmDisplayFlags	模式标志
dmDisplayFrequency	模式频率
dmPosition	设备在多监视器配置中的位置。

除了使用上述一个或多个 DEVMODE 成员之外，还必须在 dmFields 成员中设置以下一个或多个值来更改显示设置。

价值	意义
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	当前屏幕的图形模式将动态更改，图形模式将在注册表中更新。模式信息存储在用户配置文件中。

指定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 标头将 ChangeDisplaySettings 定义为一个别名，该别名根据 UNICODE 预处理器常量的定义自动选择此函数的 ANSI 或 Unicode 版本。将中性编码别名与不中性编码的代码混合使用可能会导致编译或运行时错误不匹配。有关详细信息，请参阅函数原型的约定。

要求

要求	价值
最低支持的客户端	Windows 2000 Professional [仅限桌面应用]
支持的最低服务器	Windows 2000 Server [仅限桌面应用]
目标平台	窗户
标头	winuser.h （包括 Windows.h）
库	User32.lib
DLL	User32.dll
API 集	ext-ms-win-ntuser-sysparams-ext-l1-1-1（在 Windows 10 版本 10.0.14393 中引入）