Funzione SetDisplayConfig (winuser.h)
La funzione SetDisplayConfig modifica la topologia di visualizzazione, l'origine e le modalità di destinazione abilitando esclusivamente i percorsi specificati nella sessione corrente.
Sintassi
LONG SetDisplayConfig(
[in] UINT32 numPathArrayElements,
[in, optional] DISPLAYCONFIG_PATH_INFO *pathArray,
[in] UINT32 numModeInfoArrayElements,
[in, optional] DISPLAYCONFIG_MODE_INFO *modeInfoArray,
[in] UINT32 flags
);
Parametri
[in] numPathArrayElements
Numero di elementi in pathArray.
[in, optional] pathArray
Matrice di tutti i percorsi di visualizzazione da impostare. Vengono impostati solo i percorsi all'interno di questa matrice con il flag DISPLAYCONFIG_PATH_ACTIVE impostato nel membro flag di DISPLAYCONFIG_PATH_INFO . Questo parametro può essere NULL. L'ordine in cui vengono visualizzati i percorsi attivi in questa matrice determina la priorità del percorso. Per altre informazioni sull'ordine di priorità del percorso, vedere Ordine di priorità percorso.
[in] numModeInfoArrayElements
Numero di elementi in modeInfoArray.
[in, optional] modeInfoArray
Matrice di informazioni sulla modalità di origine e destinazione (DISPLAYCONFIG_MODE_INFO) a cui fa riferimento il membro modeInfoIdx di DISPLAYCONFIG_PATH_SOURCE_INFO e DISPLAYCONFIG_PATH_TARGET_INFO elemento delle informazioni sul percorso da pathArray. Questo parametro può essere NULL.
[in] flags
Or bit per bit dei valori del flag che indica il comportamento di questa funzione. Questo parametro può essere uno dei valori seguenti o una combinazione dei valori seguenti; 0 non è valido. Per una descrizione delle combinazioni di flag valide, vedere di seguito.
L'elenco seguente contiene combinazioni valide di valori per il parametro Flags :
- È necessario impostare SDC_APPLY o SDC_VALIDATE, ma non entrambi.
- È necessario impostare SDC_USE_SUPPLIED_DISPLAY_CONFIG o qualsiasi combinazione di SDC_TOPOLOGY_XXX. SDC_USE_SUPPLIED_DISPLAY_CONFIG non può essere impostato con qualsiasi flag di SDC_TOPOLOGY_XXX.
- SDC_NO_OPTIMIZATION può essere impostato solo con SDC_APPLY.
- SDC_ALLOW_CHANGES è consentito con qualsiasi altra combinazione valida.
- SDC_SAVE_TO_DATABASE può essere impostato solo con SDC_USE_SUPPLIED_DISPLAY_CONFIG.
- SDC_PATH_PERSIST_IF_REQUIRED non può essere usato con SDC_USE_SUPPLIED_DISPLAY_CONFIG o SDC_TOPOLOGY_SUPPLIED.
- SDC_FORCE_MODE_ENUMERATION è valido solo quando vengono specificati SDC_APPLY e SDC_USE_SUPPLIED_DISPLAY_CONFIG.
- SDC_ALLOW_PATH_ORDER_CHANGES è consentito solo quando viene specificato SDC_TOPOLOGY_SUPPLIED.
- SDC_TOPOLOGY_SUPPLIED non può essere usato con qualsiasi altro flag di SDC_TOPOLOGY_XXX. A causa di un problema di convalida, se un chiamante viola questa regola, SetDisplayConfig non riesce. Tuttavia, SetDisplayConfig ignora il flag di SDC_TOPOLOGY_SUPPLIED.
Valore restituito
La funzione restituisce uno dei codici restituiti seguenti.
| Codice restituito | Descrizione |
|---|---|
|
Funzione completata. |
|
La combinazione di parametri e flag specificati non è valida. |
|
Il sistema non esegue un driver grafico scritto in base al modello wdDM (Windows Display Driver Model). La funzione è supportata solo in un sistema con un driver WDDM in esecuzione. |
|
Il chiamante non ha accesso alla sessione della console. Questo errore si verifica se il processo chiamante non ha accesso al desktop corrente o è in esecuzione in una sessione remota. |
|
Si è verificato un errore non specificato. |
|
La funzione non è riuscita a trovare una soluzione funzionante per le modalità di origine e di destinazione non specificate dal chiamante. |
Commenti
La funzione SetDisplayConfig accetta i percorsi di visualizzazione attivi con le informazioni sulla modalità di origine e di destinazione specificate e usa la logica della modalità migliore per generare informazioni sulla modalità di origine e di destinazione mancanti. Questa funzione imposta quindi il percorso di visualizzazione completo.
I membri ModeInfoIdx nelle strutture DISPLAYCONFIG_PATH_SOURCE_INFO e DISPLAYCONFIG_PATH_TARGET_INFO vengono utilizzati per indicare se la modalità di origine e di destinazione viene fornita per un determinato percorso attivo. Se il valore dell'indice è DISPLAYCONFIG_PATH_MODE_IDX_INVALID per uno di questi valori, indica che le informazioni sulla modalità non vengono specificate. È valido per il percorso più la modalità di origine o il percorso più le informazioni sulla modalità di origine e di destinazione da specificare per un determinato percorso. Tuttavia, non è valido per il percorso più la modalità di destinazione da specificare senza la modalità di origine.
Le modalità di origine e di destinazione per ogni identificatore di origine e di destinazione possono essere visualizzate solo una volta nella matrice modeInfoArray . Ad esempio, una modalità di origine per l'identificatore di origine S1 può essere visualizzata solo una volta nella tabella; se più percorsi fanno riferimento alla stessa origine, devono usare lo stesso ModeInfoIdx.
La maggior parte dei chiamanti usa QueryDisplayConfig per ottenere la configurazione corrente insieme ad altre possibilità valide e quindi usare SetDisplayConfig per testare e impostare la configurazione.
L'ordine in cui i percorsi attivi vengono visualizzati nella matrice PathArray determina la priorità del percorso.
Per impostazione predefinita, SetDisplayConfig non modifica mai le informazioni sul percorso, sulla modalità di origine o sulla modalità di destinazione. Se la logica della modalità migliore non riesce a trovare una soluzione senza modificare le informazioni sul percorso di visualizzazione specificato, SetDisplayConfig ha esito negativo con ERROR_BAD_CONFIGURATION. In questo caso, il chiamante deve specificare il flag SDC_ALLOW_CHANGES per consentire alla funzione di modificare alcuni dettagli di origine e modalità specificati per consentire la corretta modifica del percorso di visualizzazione.
Se le modalità di origine e destinazione specificate o calcolate hanno le stesse dimensioni, SetDisplayConfig imposta automaticamente il ridimensionamento del percorso su DISPLAYCONFIG_PPR_IDENTITY prima di impostare il percorso di visualizzazione e salvarlo nel database. Per informazioni su come SetDisplayConfig gestisce il ridimensionamento, vedere Ridimensionamento dell'immagine desktop.
Quando il chiamante specifica il flag SDC_USE_SUPPLIED_DISPLAY_CONFIG per impostare un percorso clone e se gli indici in modalità di origine non sono validi nella matrice di percorsi, SetDisplayConfig determina che tutti gli indici della modalità di origine da tale origine non sono validi. SetDisplayConfig usa la logica della modalità migliore per determinare le informazioni sulla modalità di origine.
Ad eccezione del flag SDC_TOPOLOGY_SUPPLIED (per altre informazioni su SDC_TOPOLOGY_SUPPLIED, vedere il paragrafo seguente), i flag SDC_TOPOLOGY_XXX impostano le impostazioni dell'ultimo percorso di visualizzazione, incluse le informazioni sulla modalità di origine e di destinazione per tale tipo di topologia. Per informazioni sulle combinazioni di flag di SDC_TOPOLOGY_XXX valide, vedere la descrizione del parametro Flags . I parametri pathArray e modeInfoArray devono essere NULL e le dimensioni associate devono essere zero. Ad esempio, se sono impostate SDC_TOPOLOGY_CLONE e SDC_TOPOLOGY_EXTEND, questa funzione usa la configurazione del percorso di visualizzazione o clonazione più recente. Se viene richiesto un singolo tipo di topologia, viene utilizzata l'ultima configurazione di tale tipo. Se tale topologia non è mai stata impostata in precedenza, SetDisplayConfig usa la logica di topologia migliore per trovare la topologia migliore e quindi la logica della modalità migliore per trovare la modalità di origine e di destinazione migliore da usare. Se è stata impostata una combinazione dei flag di topologia e nessuna di esse include voci di database, viene usata la priorità seguente. Per i portatili: clonare, estendere, interno e quindi esterno; per i desktop la priorità viene estesa e quindi clona.
Il chiamante può specificare il flag SDC_TOPOLOGY_SUPPLIED per indicare che imposta solo le informazioni sul percorso (topologia) e le richieste che SetDisplayConfig ottiene e quindi usa le informazioni sulla modalità di origine e di destinazione dal database di persistenza. Se i percorsi attivi forniti dal chiamante non dispongono di una voce nel database di persistenza, SetDisplayConfig ha esito negativo. In questo caso, se il chiamante chiama nuovamente SetDisplayConfig con gli stessi dati del percorso, ma con il flag SDC_USE_SUPPLIED_DISPLAY_CONFIG impostato, SetDisplayConfig usa la logica in modalità migliore per creare le informazioni sulla modalità di origine e di destinazione. Quando il chiamante specifica SDC_TOPOLOGY_SUPPLIED, il chiamante deve impostare il parametro numModeInfoArrayElements su zero e il parametro modeInfoArray su NULL; Tuttavia, il chiamante deve impostare i parametri pathArray e numPathArrayElements per le informazioni sul percorso richieste dal chiamante. Il chiamante deve contrassegnare tutti gli indici della modalità di origine e di destinazione come non validi (DISPLAYCONFIG_PATH_MODE_IDX_INVALID) nei dati del percorso.
La tabella seguente fornisce alcuni scenari comuni in cui SetDisplayConfig viene chiamato insieme alle combinazioni di flag che il chiamante passa al parametro Flags per ottenere gli scenari.
| Scenario | Combinazione di flag |
|---|---|
| Verificare se nel computer è supportata una configurazione di visualizzazione specificata | SDC_VALIDATE | SDC_USE_SUPPLIED_DISPLAY_CONFIG |
| Impostare una configurazione di visualizzazione specificata e salvare nel database | SDC_APPLY | SDC_USE_SUPPLIED_DISPLAY_CONFIG | SDC_SAVE_TO_DATABASE |
| Impostare una configurazione di visualizzazione temporanea( ovvero la configurazione di visualizzazione non verrà salvata) | SDC_APPLY | SDC_USE_SUPPLIED_DISPLAY_CONFIG |
| Verificare se il clone è supportato nel computer | SDC_VALIDATE | SDC_TOPOLOGY_CLONE |
| Impostare la topologia clone | SDC_APPLY | SDC_TOPOLOGY_CLONE |
| Impostare la topologia clone e consentire l'abilitazione della persistenza del percorso se necessario per soddisfare la richiesta | SDC_APPLY | SDC_TOPOLOGY_CLONE | SDC_PATH_PERSIST_IF_REQUIRED |
| Tornare da una modalità temporanea all'ultima configurazione di visualizzazione salvata | SDC_APPLY| SDC_USE_DATABASE_CURRENT |
| Dato solo le informazioni sul percorso, impostare la configurazione di visualizzazione con le informazioni di origine e di destinazione dal database per i percorsi e ignorare l'ordine del percorso | SDC_APPLY | SDC_TOPOLOGY_SUPPLIED | SDC_ALLOW_PATH_ORDER_CHANGES |
Virtualizzazione DPI
Questa API non partecipa alla virtualizzazione DPI. Tutte le dimensioni della struttura DEVMODE sono in termini di pixel fisici e non sono correlate al contesto chiamante.Requisiti
| Client minimo supportato | Disponibile in Windows 7 e versioni successive dei sistemi operativi Windows. |
| Piattaforma di destinazione | Universale |
| Intestazione | winuser.h (include Windows.h) |
| Libreria | User32.lib |
| DLL | User32.dll |
| Set di API | ext-ms-win-ntuser-sysparams-ext-l1-1-1 (introdotto in Windows 10, versione 10.0.14393) |
Vedi anche
DISPLAYCONFIG_PATH_SOURCE_INFO