Función SetDisplayConfig (winuser.h)
La función SetDisplayConfig modifica la topología para mostrar, el origen y los modos de destino habilitando exclusivamente las rutas de acceso especificadas en la sesión actual.
Sintaxis
LONG SetDisplayConfig(
[in] UINT32 numPathArrayElements,
[in, optional] DISPLAYCONFIG_PATH_INFO *pathArray,
[in] UINT32 numModeInfoArrayElements,
[in, optional] DISPLAYCONFIG_MODE_INFO *modeInfoArray,
[in] UINT32 flags
);
Parámetros
[in] numPathArrayElements
Número de elementos de pathArray.
[in, optional] pathArray
Matriz de todas las rutas de acceso de presentación que se van a establecer. Solo se establecen las rutas de acceso de esta matriz que tienen la marca DISPLAYCONFIG_PATH_ACTIVE establecida en el miembro flags de DISPLAYCONFIG_PATH_INFO . Este parámetro puede ser NULL. El orden en el que aparecen las rutas de acceso activas en esta matriz determina la prioridad de ruta de acceso. Para obtener más información sobre el orden de prioridad de ruta de acceso, consulte Orden de prioridad de ruta de acceso.
[in] numModeInfoArrayElements
Número de elementos en modeInfoArray.
[in, optional] modeInfoArray
Matriz de información del modo de origen y destino de presentación (DISPLAYCONFIG_MODE_INFO) a la que hace referencia el miembro modeInfoIdx de DISPLAYCONFIG_PATH_SOURCE_INFO y DISPLAYCONFIG_PATH_TARGET_INFO elemento de información de ruta de acceso de pathArray. Este parámetro puede ser NULL.
[in] flags
Or bit a bit de valores de marca que indica el comportamiento de esta función. Este parámetro puede ser uno de los siguientes valores o una combinación de los valores siguientes; 0 no es válido. Vea a continuación una descripción de las combinaciones de marcas válidas.
La lista siguiente contiene combinaciones válidas de valores para el parámetro Flags :
- Se deben establecer SDC_APPLY o SDC_VALIDATE, pero no ambas.
- Se deben establecer SDC_USE_SUPPLIED_DISPLAY_CONFIG o cualquier combinación de SDC_TOPOLOGY_XXX. SDC_USE_SUPPLIED_DISPLAY_CONFIG no se puede establecer con ninguna marca de SDC_TOPOLOGY_XXX.
- SDC_NO_OPTIMIZATION solo se puede establecer con SDC_APPLY.
- SDC_ALLOW_CHANGES se permite con cualquier otra combinación válida.
- SDC_SAVE_TO_DATABASE solo se puede establecer con SDC_USE_SUPPLIED_DISPLAY_CONFIG.
- SDC_PATH_PERSIST_IF_REQUIRED no se puede usar con SDC_USE_SUPPLIED_DISPLAY_CONFIG o SDC_TOPOLOGY_SUPPLIED.
- SDC_FORCE_MODE_ENUMERATION solo es válido cuando se especifican SDC_APPLY y SDC_USE_SUPPLIED_DISPLAY_CONFIG.
- SDC_ALLOW_PATH_ORDER_CHANGES solo se permite cuando se especifica SDC_TOPOLOGY_SUPPLIED.
- SDC_TOPOLOGY_SUPPLIED no se puede usar con ninguna otra marca de SDC_TOPOLOGY_XXX. Debido a un problema de validación, si un autor de la llamada infringe esta regla, SetDisplayConfig no produce un error. Sin embargo, SetDisplayConfig omite la marca SDC_TOPOLOGY_SUPPLIED.
Valor devuelto
La función devuelve uno de los siguientes códigos de retorno.
| Código devuelto | Descripción |
|---|---|
|
La función se ha realizado correctamente. |
|
La combinación de parámetros y marcas especificadas no es válida. |
|
El sistema no ejecuta un controlador de gráficos que se escribió según el modelo de controlador de pantalla de Windows (WDDM). La función solo se admite en un sistema con un controlador WDDM en ejecución. |
|
El autor de la llamada no tiene acceso a la sesión de consola. Este error se produce si el proceso de llamada no tiene acceso al escritorio actual o se ejecuta en una sesión remota. |
|
Se ha producido un error no especificado. |
|
La función no pudo encontrar una solución viable para los modos de origen y destino que el autor de la llamada no especificó. |
Observaciones
La función SetDisplayConfig toma las rutas de acceso de visualización activas con cualquier información de modo de origen y de destino especificada y usa la mejor lógica de modo para generar cualquier información de modo de origen y de destino que falte. A continuación, esta función establece la ruta de acceso de presentación completa.
Los miembros ModeInfoIdx de las estructuras DISPLAYCONFIG_PATH_SOURCE_INFO y DISPLAYCONFIG_PATH_TARGET_INFO se usan para indicar si se proporcionan el modo de origen y destino para una ruta de acceso activa determinada. Si el valor de índice es DISPLAYCONFIG_PATH_MODE_IDX_INVALID para cualquiera de los dos, esto indica que no se especifica la información del modo. Es válido para la ruta de acceso más el modo de origen o la ruta de acceso más la información del modo de origen y de destino que se va a especificar para una ruta de acceso determinada. Sin embargo, no es válido para que la ruta de acceso más el modo de destino se especifique sin el modo de origen.
Los modos de origen y destino de cada identificador de origen y destino solo pueden aparecer en la matriz modeInfoArray una vez. Por ejemplo, un modo de origen para el identificador de origen S1 solo puede aparecer en la tabla una vez; si varias rutas de acceso hacen referencia al mismo origen, tienen que usar el mismo ModeInfoIdx.
La expectativa es que la mayoría de los autores de llamadas usen QueryDisplayConfig para obtener la configuración actual junto con otras posibilidades válidas y, a continuación, usar SetDisplayConfig para probar y establecer la configuración.
El orden en el que aparecen las rutas de acceso activas en la matriz PathArray determina la prioridad de la ruta de acceso.
De forma predeterminada, SetDisplayConfig nunca cambia ninguna ruta de acceso, modo de origen o información del modo de destino proporcionada. Si la mejor lógica de modo no puede encontrar una solución sin cambiar la información de ruta de acceso de visualización especificada, SetDisplayConfig produce un error con ERROR_BAD_CONFIGURATION. En este caso, el autor de la llamada debe especificar la marca de SDC_ALLOW_CHANGES para permitir que la función ajuste algunos de los detalles de origen y modo especificados para permitir que el cambio de ruta de acceso de presentación sea correcto.
Si los modos de origen y destino especificados o calculados tienen las mismas dimensiones, SetDisplayConfig establece automáticamente el escalado de ruta de acceso en DISPLAYCONFIG_PPR_IDENTITY antes de establecer la ruta de acceso de presentación y guardarla en la base de datos. Para obtener información sobre cómo SetDisplayConfig controla el escalado, consulte Escalado de la imagen de escritorio.
Cuando el autor de la llamada especifica la marca SDC_USE_SUPPLIED_DISPLAY_CONFIG para establecer una ruta de acceso de clonación y si algún índice de modo de origen no es válido en la matriz de rutas de acceso, SetDisplayConfig determina que todos los índices del modo de origen de ese origen no son válidos. SetDisplayConfig usa la mejor lógica de modo para determinar la información del modo de origen.
Excepto la marca de SDC_TOPOLOGY_SUPPLIED (para obtener más información sobre SDC_TOPOLOGY_SUPPLIED, vea el párrafo siguiente), las marcas de SDC_TOPOLOGY_XXX establecen la última configuración de ruta de acceso de presentación, incluida la información del modo de origen y de destino para ese tipo de topología. Para obtener información sobre las combinaciones de marcas de SDC_TOPOLOGY_XXX válidas, consulte la descripción del parámetro Flags . Los parámetros pathArray y modeInfoArray deben ser NULL y sus tamaños asociados deben ser cero. Por ejemplo, si se establecen SDC_TOPOLOGY_CLONE y SDC_TOPOLOGY_EXTEND, esta función usa la configuración de ruta de acceso de visualización más reciente o clonación más reciente. Si se solicita un único tipo de topología, se usa la última configuración de ese tipo. Si esa topología nunca se había establecido antes, SetDisplayConfig usa la mejor lógica de topología para encontrar la mejor topología y, a continuación, la mejor lógica de modo para encontrar el mejor modo de origen y destino que se va a usar. Si se había establecido una combinación de las marcas de topología y ninguna de ellas tenía entradas de base de datos, se usa la siguiente prioridad. Para portátiles: clone, extienda, interno y, a continuación, externo; para los escritorios, la prioridad se extiende y, a continuación, clona.
El autor de la llamada puede especificar la marca SDC_TOPOLOGY_SUPPLIED para indicar que establece solo la información de ruta de acceso (topología) y las solicitudes que SetDisplayConfig obtiene y, a continuación, usa la información del modo de origen y destino de la base de datos de persistencia. Si las rutas de acceso activas que proporciona el autor de la llamada no tienen una entrada en la base de datos de persistencia, se produce un error en SetDisplayConfig . En este caso, si el autor de la llamada llama a SetDisplayConfig de nuevo con los mismos datos de ruta de acceso, pero con el conjunto de marcas de SDC_USE_SUPPLIED_DISPLAY_CONFIG, SetDisplayConfig usa la mejor lógica de modo para crear la información del modo de origen y de destino. Cuando el llamador especifica SDC_TOPOLOGY_SUPPLIED, el llamador debe establecer el parámetro numModeInfoArrayElements en cero y el parámetro modeInfoArray enNULL; Sin embargo, el autor de la llamada debe establecer los parámetros pathArray y numPathArrayElements para la información de ruta de acceso que requiere el autor de la llamada. El autor de la llamada debe marcar todos los índices de modo de origen y destino como no válidos (DISPLAYCONFIG_PATH_MODE_IDX_INVALID) en estos datos de ruta de acceso.
En la tabla siguiente se proporcionan algunos escenarios comunes en los que se llama a SetDisplayConfig junto con las combinaciones de marcas que el autor de la llamada pasa al parámetro Flags para lograr los escenarios.
| Escenario | Combinación de marcas |
|---|---|
| Compruebe si se admite una configuración de visualización especificada en el equipo. | SDC_VALIDATE | SDC_USE_SUPPLIED_DISPLAY_CONFIG |
| Establecer una configuración de visualización especificada y guardarla en la base de datos | SDC_APPLY | SDC_USE_SUPPLIED_DISPLAY_CONFIG | SDC_SAVE_TO_DATABASE |
| Establecer una configuración de visualización temporal (es decir, la configuración de visualización no se guardará) | SDC_APPLY | SDC_USE_SUPPLIED_DISPLAY_CONFIG |
| Prueba de si se admite clonación en el equipo | SDC_VALIDATE | SDC_TOPOLOGY_CLONE |
| Establecimiento de la topología de clonación | SDC_APPLY | SDC_TOPOLOGY_CLONE |
| Establezca la topología clonada y permita que la persistencia de la ruta de acceso esté habilitada si es necesario para satisfacer la solicitud. | SDC_APPLY | SDC_TOPOLOGY_CLONE | SDC_PATH_PERSIST_IF_REQUIRED |
| Volver de un modo temporal a la última configuración de visualización guardada | SDC_APPLY| SDC_USE_DATABASE_CURRENT |
| Dada solo la información de ruta de acceso, establezca la configuración de presentación con la información de origen y destino de la base de datos para las rutas de acceso y omita el orden de la ruta de acceso. | SDC_APPLY | SDC_TOPOLOGY_SUPPLIED | SDC_ALLOW_PATH_ORDER_CHANGES |
Virtualización de PPP
Esta API no participa en la virtualización de PPP. Todos los tamaños de la estructura DEVMODE se encuentran en términos de píxeles físicos y no están relacionados con el contexto de llamada.Requisitos
| Cliente mínimo compatible | Disponible en Windows 7 y versiones posteriores de los sistemas operativos Windows. |
| Plataforma de destino | Universal |
| Encabezado | winuser.h (incluya Windows.h) |
| Library | User32.lib |
| Archivo DLL | User32.dll |
| Conjunto de API | ext-ms-win-ntuser-sysparams-ext-l1-1-1 (introducido en Windows 10, versión 10.0.14393) |
Consulte también
DISPLAYCONFIG_PATH_SOURCE_INFO