Função SetDisplayConfig (winuser.h)
A função SetDisplayConfig modifica os modos de exibição topologia, origem e destino habilitando exclusivamente os caminhos especificados na sessão atual.
Sintaxe
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 em pathArray.
[in, optional] pathArray
Matriz de todos os caminhos de exibição que devem ser definidos. Somente os caminhos dentro dessa matriz que têm o sinalizador DISPLAYCONFIG_PATH_ACTIVE definido no membro de sinalizadores de DISPLAYCONFIG_PATH_INFO são definidos. Este parâmetro pode ser NULL. A ordem na qual os caminhos ativos aparecem nesta matriz determina a prioridade do caminho. Para obter mais informações sobre a ordem de prioridade do caminho, consulte Ordem de Prioridade do Caminho.
[in] numModeInfoArrayElements
Número de elementos em modeInfoArray.
[in, optional] modeInfoArray
Matriz de informações de modo de origem de exibição e de destino (DISPLAYCONFIG_MODE_INFO) referenciadas pelo membro modeInfoIdx de DISPLAYCONFIG_PATH_SOURCE_INFO e DISPLAYCONFIG_PATH_TARGET_INFO elemento de informações de caminho de pathArray. Este parâmetro pode ser NULL.
[in] flags
Um OR bit a bit de valores de sinalizador que indica o comportamento dessa função. Esse parâmetro pode ser um dos seguintes valores ou uma combinação dos seguintes valores; 0 não é válido. Veja abaixo uma descrição das combinações de sinalizador válidas.
A lista a seguir contém combinações válidas de valores para o parâmetro Flags :
- SDC_APPLY ou SDC_VALIDATE devem ser definidos, mas não ambos.
- SDC_USE_SUPPLIED_DISPLAY_CONFIG ou qualquer combinação de SDC_TOPOLOGY_XXX deve ser definida. SDC_USE_SUPPLIED_DISPLAY_CONFIG não pode ser definido com nenhum sinalizador de SDC_TOPOLOGY_XXX.
- SDC_NO_OPTIMIZATION só pode ser definido com SDC_APPLY.
- SDC_ALLOW_CHANGES é permitido com qualquer outra combinação válida.
- SDC_SAVE_TO_DATABASE só pode ser definido com SDC_USE_SUPPLIED_DISPLAY_CONFIG.
- SDC_PATH_PERSIST_IF_REQUIRED não pode ser usado com SDC_USE_SUPPLIED_DISPLAY_CONFIG ou SDC_TOPOLOGY_SUPPLIED.
- SDC_FORCE_MODE_ENUMERATION só é válido quando SDC_APPLY e SDC_USE_SUPPLIED_DISPLAY_CONFIG são especificados.
- SDC_ALLOW_PATH_ORDER_CHANGES é permitido somente quando SDC_TOPOLOGY_SUPPLIED é especificado.
- SDC_TOPOLOGY_SUPPLIED não pode ser usado com nenhum outro sinalizador SDC_TOPOLOGY_XXX. Devido a um problema de validação, se um chamador violar essa regra, SetDisplayConfig não falhará. No entanto, SetDisplayConfig ignora o sinalizador SDC_TOPOLOGY_SUPPLIED.
Valor retornado
A função retorna um dos seguintes códigos de retorno.
| Código de retorno | Descrição |
|---|---|
|
A função foi bem-sucedida. |
|
A combinação de parâmetros e sinalizadores especificados é inválida. |
|
O sistema não está executando um driver gráfico que foi gravado de acordo com o Modelo de Driver de Exibição do Windows (WDDM). A função só tem suporte em um sistema com um driver WDDM em execução. |
|
O chamador não tem acesso à sessão do console. Esse erro ocorrerá se o processo de chamada não tiver acesso à área de trabalho atual ou estiver em execução em uma sessão remota. |
|
Ocorreu um erro não especificado. |
|
A função não pôde encontrar uma solução viável para os modos de origem e destino que o chamador não especificou. |
Comentários
A função SetDisplayConfig usa os caminhos de exibição ativos com qualquer informação especificada do modo de origem e destino e usa a melhor lógica de modo para gerar qualquer informação de modo de origem e destino ausentes. Essa função define o caminho de exibição completo.
Os membros ModeInfoIdx nas estruturas DISPLAYCONFIG_PATH_SOURCE_INFO e DISPLAYCONFIG_PATH_TARGET_INFO são usados para indicar se o modo de origem e destino são fornecidos para um determinado caminho ativo. Se o valor do índice for DISPLAYCONFIG_PATH_MODE_IDX_INVALID para qualquer um, isso indicará que as informações do modo não estão sendo especificadas. Ela é válida para o caminho mais o modo de origem ou o caminho mais informações do modo de origem e de destino a serem especificadas para um determinado caminho. No entanto, não é válido que o caminho mais o modo de destino seja especificado sem o modo de origem.
Os modos de origem e destino para cada identificador de origem e destino só podem aparecer na matriz modeInfoArray uma vez. Por exemplo, um modo de origem para o identificador de origem S1 só pode aparecer na tabela uma vez; se vários caminhos fizerem referência à mesma origem, eles precisarão usar o mesmo ModeInfoIdx.
A expectativa é que a maioria dos chamadores use QueryDisplayConfig para obter a configuração atual junto com outras possibilidades válidas e, em seguida, use SetDisplayConfig para testar e definir a configuração.
A ordem na qual os caminhos ativos aparecem na matriz PathArray determina a prioridade do caminho.
Por padrão, SetDisplayConfig nunca altera nenhuma informação de caminho, modo de origem ou modo de destino fornecidos. Se a melhor lógica de modo não puder encontrar uma solução sem alterar as informações de caminho de exibição especificadas, SetDisplayConfig falhará com ERROR_BAD_CONFIGURATION. Nesse caso, o chamador deve especificar o sinalizador SDC_ALLOW_CHANGES para permitir que a função ajuste alguns dos detalhes de origem e modo especificados para permitir que a alteração do caminho de exibição seja bem-sucedida.
Se os modos de origem e destino especificados ou calculados tiverem as mesmas dimensões, SetDisplayConfig definirá automaticamente o dimensionamento de caminho como DISPLAYCONFIG_PPR_IDENTITY antes de definir o caminho de exibição e salvá-lo no banco de dados. Para obter informações sobre como SetDisplayConfig lida com o dimensionamento, consulte Dimensionando a imagem da área de trabalho.
Quando o chamador especifica o sinalizador SDC_USE_SUPPLIED_DISPLAY_CONFIG para definir um caminho de clone e se algum índice de modo de origem for inválido na matriz de caminho, SetDisplayConfig determinará que todos os índices do modo de origem dessa origem são inválidos. SetDisplayConfig usa a melhor lógica de modo para determinar as informações do modo de origem.
Exceto pelo sinalizador SDC_TOPOLOGY_SUPPLIED (para obter mais informações sobre SDC_TOPOLOGY_SUPPLIED, consulte o parágrafo a seguir), os sinalizadores de SDC_TOPOLOGY_XXX definem as últimas configurações de caminho de exibição, incluindo as informações de modo de origem e destino para esse tipo de topologia. Para obter informações sobre combinações de sinalizadores de SDC_TOPOLOGY_XXX válidas, consulte a descrição do parâmetro Flags . Os parâmetros pathArray e modeInfoArray devem ser NULL e seus tamanhos associados devem ser zero. Por exemplo, se SDC_TOPOLOGY_CLONE e SDC_TOPOLOGY_EXTEND estiverem definidos, essa função usará o clone mais recente ou estenderá a configuração do caminho de exibição. Se um único tipo de topologia for solicitado, a última configuração desse tipo será usada. Se essa topologia nunca tinha sido definida antes, SetDisplayConfig usa a melhor lógica de topologia para encontrar a melhor topologia e, em seguida, a melhor lógica de modo para encontrar o melhor modo de origem e destino a ser usado. Se uma combinação dos sinalizadores de topologia tiver sido definida e nenhuma delas tiver entradas de banco de dados, a prioridade a seguir será usada. Para laptops: clone, estenda, interno e, em seguida, externo; para áreas de trabalho, a prioridade é estender e clonar.
O chamador pode especificar o sinalizador SDC_TOPOLOGY_SUPPLIED para indicar que ele define apenas as informações de caminho (topologia) e as solicitações que SetDisplayConfig obtém e, em seguida, usa as informações de modo de origem e destino do banco de dados de persistência. Se os caminhos ativos fornecidos pelo chamador não tiverem uma entrada no banco de dados de persistência, SetDisplayConfig falhará. Nesse caso, se o chamador chamar SetDisplayConfig novamente com os mesmos dados de caminho, mas com o sinalizador SDC_USE_SUPPLIED_DISPLAY_CONFIG definido, SetDisplayConfig usará a melhor lógica de modo para criar as informações do modo de origem e destino. Quando o chamador especifica SDC_TOPOLOGY_SUPPLIED, o chamador deve definir o parâmetro numModeInfoArrayElements como zero e o parâmetro modeInfoArray como NULL; no entanto, o chamador deve definir os parâmetros pathArray e numPathArrayElements para as informações de caminho que o chamador requer. O chamador deve marcar todos os índices de modo de origem e destino como inválidos (DISPLAYCONFIG_PATH_MODE_IDX_INVALID) neste caminho de dados.
A tabela a seguir fornece alguns cenários comuns em que SetDisplayConfig é chamado junto com as combinações de sinalizador que o chamador passa para o parâmetro Flags para obter os cenários.
| Cenário | Combinação de sinalizadores |
|---|---|
| Teste se há suporte para uma configuração de exibição especificada no computador | SDC_VALIDATE | SDC_USE_SUPPLIED_DISPLAY_CONFIG |
| Definir uma configuração de exibição especificada e salvar no banco de dados | SDC_APPLY | SDC_USE_SUPPLIED_DISPLAY_CONFIG | SDC_SAVE_TO_DATABASE |
| Definir uma configuração de exibição temporária (ou seja, a configuração de exibição não será salva) | SDC_APPLY | SDC_USE_SUPPLIED_DISPLAY_CONFIG |
| Testar se há suporte para clonagem no computador | SDC_VALIDATE | SDC_TOPOLOGY_CLONE |
| Definir topologia de clone | SDC_APPLY | SDC_TOPOLOGY_CLONE |
| Defina a topologia de clone e permita que a persistência de caminho seja habilitada se necessário para atender à solicitação | SDC_APPLY | SDC_TOPOLOGY_CLONE | SDC_PATH_PERSIST_IF_REQUIRED |
| Retornar de um modo temporário para a última configuração de exibição salva | SDC_APPLY| SDC_USE_DATABASE_CURRENT |
| Considerando apenas as informações de caminho, defina a configuração de exibição com as informações de origem e destino do banco de dados para os caminhos e ignore a ordem do caminho | SDC_APPLY | SDC_TOPOLOGY_SUPPLIED | SDC_ALLOW_PATH_ORDER_CHANGES |
Virtualização de DPI
Essa API não participa da virtualização de DPI. Todos os tamanhos na estrutura DEVMODE estão em termos de pixels físicos e não estão relacionados ao contexto de chamada.Requisitos
| Cliente mínimo com suporte | Disponível no Windows 7 e versões posteriores dos sistemas operacionais Windows. |
| Plataforma de Destino | Universal |
| Cabeçalho | winuser.h (inclua Windows.h) |
| Biblioteca | User32.lib |
| DLL | User32.dll |
| Conjunto de APIs | ext-ms-win-ntuser-sysparams-ext-l1-1-1 (introduzido no Windows 10, versão 10.0.14393) |
Confira também
DISPLAYCONFIG_PATH_SOURCE_INFO