Функция ChangeDisplaySettingsExW (winuser.h)

Статья
03/15/2023

Функция ChangeDisplaySettingsEx изменяет параметры указанного устройства отображения на указанный режим графики.

Примечание Приложения, предназначенные для Windows 8 и более поздних версий, больше не могут запрашивать или задавать режимы отображения менее 32 бит на пиксель (bpp). Эти операции завершатся ошибкой. Эти приложения имеют манифест совместимости, предназначенный для Windows 8. Windows 8 по-прежнему поддерживает 8- и 16-разрядные цветовые режимы для классических приложений, созданных без манифеста Windows 8; Windows 8 эмулирует эти режимы, но по-прежнему работает в 32-разрядном цветовом режиме.

Синтаксис

LONG ChangeDisplaySettingsExW(
  [in] LPCWSTR  lpszDeviceName,
  [in] DEVMODEW *lpDevMode,
       HWND     hwnd,
  [in] DWORD    dwflags,
  [in] LPVOID   lParam
);

Параметры

[in] lpszDeviceName

Указатель на строку, завершающуюся нулевым значением, которая указывает устройство отображения, режим графики которого изменится. Допустимы только имена устройств, возвращенные EnumDisplayDevices . Дополнительные сведения об именах, связанных с этими устройствами отображения, см. в разделе EnumDisplayDevices .

Параметр lpszDeviceName может иметь значение NULL. Значение NULL указывает устройство отображения по умолчанию. Устройство по умолчанию можно определить, вызвав EnumDisplayDevices и проверив флаг DISPLAY_DEVICE_PRIMARY_DEVICE.

[in] lpDevMode

Указатель на структуру DEVMODE , описывающую новый режим графики. Если lpDevMode имеет значение NULL, для параметра отображения будут использоваться все текущие значения в реестре. Передача null для параметра lpDevMode и 0 для параметра dwFlags — это самый простой способ вернуться в режим по умолчанию после изменения динамического режима.

Член dmSize должен быть инициализирован размером в байтах структуры 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 .

hwnd

Защищены; значение должно иметь значение NULL.

[in] dwflags

Указывает, как следует изменить графический режим. Этот параметр может принимать одно из указанных ниже значений.

Значение	Значение
0	Режим графики для текущего экрана будет динамически изменен.
CDS_FULLSCREEN	Режим носит временный характер. При переходе на другой рабочий стол и с другого рабочего стола этот режим не будет сброшен.
CDS_GLOBAL	Параметры будут сохранены в области глобальных параметров, чтобы они влияли на всех пользователей на компьютере. В противном случае изменяются только параметры пользователя. Этот флаг действителен, только если он указан с флагом CDS_UPDATEREGISTRY.
CDS_NORESET	Параметры будут сохранены в реестре, но не вступают в силу. Этот флаг действителен, только если он указан с флагом CDS_UPDATEREGISTRY.
CDS_RESET	Параметры следует изменить, даже если запрошенные параметры совпадают с текущими параметрами.
CDS_SET_PRIMARY	Это устройство станет основным устройством.
CDS_TEST	Система проверяет, можно ли задать запрошенный режим графики.
CDS_UPDATEREGISTRY	Графический режим для текущего экрана будет динамически изменен, а графический режим будет обновлен в реестре. Сведения о режиме хранятся в профиле ПОЛЬЗОВАТЕЛЯ.
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

Если параметр dwFlagsCDS_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	Чтобы графический режим работал, компьютер необходимо перезагрузить.

Чтобы убедиться, что структура DEVMODE , переданная в ChangeDisplaySettingsEx , является допустимой и содержит только значения, поддерживаемые драйвером отображения, используйте DEVMODE , возвращаемый функцией EnumDisplaySettings .

При программном добавлении монитора дисплея в систему с несколькими мониторами задайте для DEVMODE.dmFields значение DM_POSITION и укажите позицию (в DEVMODE.dmPosition) для добавляемого монитора, прилегающую по крайней мере к одному пикселю области отображения существующего монитора. Чтобы отсоединить монитор, задайте для DEVMODE.dmFields значение DM_POSITION но установите для devmode.dmPelsWidth и DEVMODE.dmPelsHeight значение 0. Дополнительные сведения см. в разделе Несколько мониторов отображения.

При динамическом изменении режима отображения WM_DISPLAYCHANGE сообщение отправляется всем работающим приложениям со следующими параметрами сообщения.

Параметры	Значение
wParam	Новые биты на пиксель
LOWORD(lParam)	Новая ширина пикселей
HIWORD(lParam)	Новая высота пикселей

Чтобы изменить параметры для нескольких дисплеев одновременно, сначала вызовите ChangeDisplaySettingsEx для каждого устройства по отдельности, чтобы обновить реестр без применения изменений. Затем еще раз вызовите ChangeDisplaySettingsEx с устройством NULL , чтобы применить изменения. Например, чтобы изменить параметры для двух дисплеев, сделайте следующее:


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 определяет ChangeDisplaySettingsEx как псевдоним, который автоматически выбирает версию ANSI или Юникод этой функции на основе определения константы препроцессора ЮНИКОД. Сочетание использования псевдонима, не зависящий от кодировки, с кодом, не зависящим от кодировки, может привести к несоответствиям, которые приводят к ошибкам компиляции или среды выполнения. Дополнительные сведения см. в разделе Соглашения для прототипов функций.

Требования

Требование	Значение
Минимальная версия клиента	Windows 2000 Professional [только классические приложения]
Минимальная версия сервера	Windows 2000 Server [только классические приложения]
Целевая платформа	Windows
Header	winuser.h (включая Windows.h)
Библиотека	User32.lib
DLL	User32.dll
Набор API	ext-ms-win-ntuser-sysparams-ext-l1-1-1 (представлено в Windows 10, версия 10.0.14393)