Функция 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 задан флаг DISPLAYCONFIG_PATH_ACTIVE. Этот параметр может принимать значение NULL. Порядок, в котором активные пути отображаются в этом массиве, определяет приоритет пути. Дополнительные сведения о порядке приоритета пути см. в разделе Порядок приоритета пути.
[in] numModeInfoArrayElements
Количество элементов в modeInfoArray.
[in, optional] modeInfoArray
Массив сведений об источнике отображения и режиме назначения (DISPLAYCONFIG_MODE_INFO), на который ссылается элемент modeInfoIdx DISPLAYCONFIG_PATH_SOURCE_INFO и DISPLAYCONFIG_PATH_TARGET_INFO элемент сведений о пути из pathArray. Этот параметр может принимать значение NULL.
[in] flags
Побитовое ИЛИ значений флага, указывающее поведение этой функции. Этот параметр может быть одним из следующих значений или сочетанием следующих значений: Недопустимо значение 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 принимает активные пути отображения с указанием всех указанных исходных и целевых режимов и использует логику наилучшего режима для создания отсутствующих сведений об исходном и целевом режимах. Затем эта функция задает полный путь отображения.
Элементы ModeInfoIdx в структурах DISPLAYCONFIG_PATH_SOURCE_INFO и DISPLAYCONFIG_PATH_TARGET_INFO используются для указания того, предоставляются ли исходный и целевой режимы для заданного активного пути. Если значение индекса DISPLAYCONFIG_PATH_MODE_IDX_INVALID для, это означает, что сведения о режиме не указаны. Оно допустимо для указания пути и режима источника или сведений о пути и целевом режиме для заданного пути. Однако недопустимо указывать путь и целевой режим без исходного режима.
Исходный и целевой режимы для каждого исходного и целевого идентификаторов могут отображаться в массиве modeInfoArray только один раз. Например, режим источника для идентификатора источника S1 может отображаться в таблице только один раз; Если несколько путей ссылаются на один источник, они должны использовать один и тот же 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, а связанные с ними размеры должны быть равны нулю. Например, если заданы SDC_TOPOLOGY_CLONE и SDC_TOPOLOGY_EXTEND, эта функция использует последнюю конфигурацию клонирования или расширения пути отображения. Если запрашивается один тип топологии, используется последняя конфигурация этого типа. Если эта топология никогда не была задана ранее, SetDisplayConfig использует лучшая логика топологии для поиска наилучшей топологии, а затем логику наилучшего режима для поиска оптимального исходного и целевого режимов. Если задано сочетание флагов топологии и ни одна из них не содержит записей базы данных, используется следующий приоритет. Для ноутбуков: клонирование, расширение, внутреннее, а затем внешнее; Для рабочих столов приоритетом является расширение, а затем клонирование.
Вызывающий объект может указать флаг SDC_TOPOLOGY_SUPPLIED, чтобы указать, что он задает только сведения о пути (топологию) и запрашивает, которые SetDisplayConfig получает, а затем использует сведения об исходном и целевом режимах из базы данных сохраняемости. Если активные пути, которые предоставляет вызывающий объект, не имеют записи в базе данных сохраняемости, 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. |
| Целевая платформа | Универсальное |
| Верхняя часть | winuser.h (включая Windows.h) |
| Библиотека | User32.lib |
| DLL | User32.dll |
| Набор API | ext-ms-win-ntuser-sysparams-ext-l1-1-1 (представлено в Windows 10 версии 10.0.14393) |
См. также раздел
DISPLAYCONFIG_PATH_SOURCE_INFO