SetDisplayConfig-Funktion (winuser.h)

Artikel
08/28/2023

Die SetDisplayConfig-Funktion ändert den Anzeigetopologie-, Quell- und Zielmodus, indem die angegebenen Pfade in der aktuellen Sitzung ausschließlich aktiviert werden.

Syntax

LONG SetDisplayConfig(
  [in]           UINT32                  numPathArrayElements,
  [in, optional] DISPLAYCONFIG_PATH_INFO *pathArray,
  [in]           UINT32                  numModeInfoArrayElements,
  [in, optional] DISPLAYCONFIG_MODE_INFO *modeInfoArray,
  [in]           UINT32                  flags
);

Parameter

[in] numPathArrayElements

Anzahl der Elemente in pathArray.

[in, optional] pathArray

Array aller anzeigepfade, die festgelegt werden sollen. Es werden nur die Pfade innerhalb dieses Arrays festgelegt, für die das DISPLAYCONFIG_PATH_ACTIVE-Flag im Flags-Elementvon DISPLAYCONFIG_PATH_INFO festgelegt ist. Dieser Parameter kann NULL sein. Die Reihenfolge, in der aktive Pfade in diesem Array angezeigt werden, bestimmt die Pfadpriorität. Weitere Informationen zur Reihenfolge der Pfadpriorität finden Sie unter Pfadprioritätsreihenfolge.

[in] numModeInfoArrayElements

Anzahl der Elemente in modeInfoArray.

[in, optional] modeInfoArray

Array von Anzeigequellen- und Zielmodusinformationen (DISPLAYCONFIG_MODE_INFO), auf das vom modeInfoIdx-Member von DISPLAYCONFIG_PATH_SOURCE_INFO und DISPLAYCONFIG_PATH_TARGET_INFO Element der Pfadinformationen aus pathArray verwiesen wird. Dieser Parameter kann NULL sein.

[in] flags

Ein bitweiser OR mit Flagwerten, der das Verhalten dieser Funktion angibt. Dieser Parameter kann einer der folgenden Werte oder eine Kombination der folgenden Werte sein: 0 ist ungültig. Eine Beschreibung der gültigen Flagkombinationen finden Sie unten.

Wert	Bedeutung
SDC_APPLY 0x00000080	Der resultierende Topologie-, Quell- und Zielmodus wird festgelegt.
SDC_NO_OPTIMIZATION 0x00000100	Ein Modifizierer für das SDC_APPLY-Flag. Dadurch wird der Änderungsmodus bis zum Treiber für jede aktive Anzeige erzwungen.
SDC_USE_SUPPLIED_DISPLAY_CONFIG 0x00000020	Anstelle der Konfiguration in der Datenbank werden die Topologie-, Quell- und Zielmodusinformationen verwendet, die in den Parametern pathArray und modeInfoArray bereitgestellt werden.
SDC_SAVE_TO_DATABASE 0x00000200	Die resultierende Topologie, die Quelle und der Zielmodus werden in der Datenbank gespeichert.
SDC_VALIDATE 0x00000040	Das System testet die angeforderten Topologie-, Quell- und Zielmodusinformationen, um zu bestimmen, ob sie festgelegt werden können.
SDC_ALLOW_CHANGES 0x00000400	Bei Bedarf kann die Funktion die angegebenen Quell- und Zielmodusinformationen ändern, um einen Funktionsanzeigepfadsatz zu erstellen.
SDC_TOPOLOGY_CLONE 0x00000002	Der Aufrufer fordert die letzte Klonkonfiguration aus der Persistenzdatenbank an.
SDC_TOPOLOGY_EXTEND 0x00000004	Der Aufrufer fordert die letzte erweiterte Konfiguration aus der Persistenzdatenbank an.
SDC_TOPOLOGY_INTERNAL 0x00000001	Der Aufrufer fordert die letzte interne Konfiguration aus der Persistenzdatenbank an.
SDC_TOPOLOGY_EXTERNAL 0x00000008	Der Aufrufer fordert die letzte externe Konfiguration aus der Persistenzdatenbank an.
SDC_TOPOLOGY_SUPPLIED 0x00000010	Der Aufrufer stellt die Pfaddaten bereit, sodass die Funktion nur die Persistenzdatenbank abfragt, um den Quell- und Zielmodus zu finden und zu verwenden.
SDC_USE_DATABASE_CURRENT (SDC_TOPOLOGY_INTERNAL \| SDC_TOPOLOGY_CLONE \| SDC_TOPOLOGY_EXTEND \| SDC_TOPOLOGY_EXTERNAL)	Der Aufrufer fordert eine Kombination aller vier SDC_TOPOLOGY_XXX-Konfigurationen an. Dieser Wert informiert die API, die letzte bekannte Anzeigekonfiguration für die aktuell verbundenen Monitore festzulegen.
SDC_PATH_PERSIST_IF_REQUIRED 0x00000800	Wenn die Funktion eine SDC_TOPOLOGY_XXX-Anforderung verarbeitet, kann sie die Pfadpersistenz für ein Ziel erzwingen, um die Anforderung bei Bedarf zu erfüllen. Informationen zu den anderen Flags, mit denen dieses Flag kombiniert werden kann, finden Sie in der folgenden Liste.
SDC_FORCE_MODE_ENUMERATION 0x00001000	Der Aufrufer fordert an, dass der Treiber die Möglichkeit erhält, die GDI-Modusliste zu aktualisieren, während SetDisplayConfig die neue Anzeigekonfiguration festlegt. Dieser Flagwert ist nur gültig, wenn die SDC_USE_SUPPLIED_DISPLAY_CONFIG- und SDC_APPLY-Flagwerte ebenfalls angegeben werden.
SDC_ALLOW_PATH_ORDER_CHANGES 0x00002000	Ein Modifizierer für das SDC_TOPOLOGY_SUPPLIED-Flag, der angibt, dass SetDisplayConfig die Pfadreihenfolge der angegebenen Topologie beim Durchsuchen der Datenbank ignorieren soll. Wenn dieses Flag festgelegt ist, ist der Topologiesatz die neueste Topologie, die unabhängig von der Pfadreihenfolge alle Pfade enthält.
SDC_VIRTUAL_MODE_AWARE 0x00008000	Ein Modifizierer für die SDC_USE_SUPPLIED_DISPLAY_CONFIG und SDC_TOPOLOGY_SUPPLIED Flags, die dem Aufrufer virtuelle Modi bekannt sind. Wird ab Windows 10 unterstützt.
SDC_VIRTUAL_REFRESH_RATE_AWARE 0x00020000	Ein Modifizierer für die SDC_USE_SUPPLIED_DISPLAY_CONFIG und SDC_TOPOLOGY_SUPPLIED Flags, dass der Aufrufer die virtuellen Aktualisierungsraten kennt. Wird ab Windows 11 unterstützt.

Die folgende Liste enthält gültige Kombinationen von Werten für den Flags-Parameter :

Es muss entweder SDC_APPLY oder SDC_VALIDATE festgelegt werden, aber nicht beides.
Es müssen entweder SDC_USE_SUPPLIED_DISPLAY_CONFIG oder beliebige Kombinationen von SDC_TOPOLOGY_XXX festgelegt werden. SDC_USE_SUPPLIED_DISPLAY_CONFIG kann nicht mit einem SDC_TOPOLOGY_XXX-Flag festgelegt werden.
SDC_NO_OPTIMIZATION kann nur mit SDC_APPLY festgelegt werden.
SDC_ALLOW_CHANGES ist mit jeder anderen gültigen Kombination zulässig.
SDC_SAVE_TO_DATABASE kann nur mit SDC_USE_SUPPLIED_DISPLAY_CONFIG festgelegt werden.
SDC_PATH_PERSIST_IF_REQUIRED können nicht mit SDC_USE_SUPPLIED_DISPLAY_CONFIG oder SDC_TOPOLOGY_SUPPLIED verwendet werden.
SDC_FORCE_MODE_ENUMERATION ist nur gültig, wenn SDC_APPLY und SDC_USE_SUPPLIED_DISPLAY_CONFIG angegeben werden.
SDC_ALLOW_PATH_ORDER_CHANGES ist nur zulässig, wenn SDC_TOPOLOGY_SUPPLIED angegeben ist.
SDC_TOPOLOGY_SUPPLIED können nicht mit anderen SDC_TOPOLOGY_XXX-Flags verwendet werden. Aufgrund eines Validierungsproblems schlägt SetDisplayConfig nicht fehl, wenn ein Aufrufer gegen diese Regel verstößt. SetDisplayConfig ignoriert jedoch das SDC_TOPOLOGY_SUPPLIED-Flag.

SDC_TOPOLOGY_XXX Flags können in Kombinationen verwendet werden. Wenn beispielsweise SDC_TOPOLOGY_CLONE und SDC_TOPOLOGY_EXTEND festgelegt sind, verwendet die API die neueste Klon- oder Erweiterungstopologie, mit der jede Topologie zuletzt für die aktuell verbundenen Monitore festgelegt wurde.

Rückgabewert

Die Funktion gibt einen der folgenden Rückgabecodes zurück.

Rückgabecode	Beschreibung
ERROR_SUCCESS	Die Funktion wurde erfolgreich ausgeführt.
ERROR_INVALID_PARAMETER	Die angegebene Kombination von Parametern und Flags ist ungültig.
ERROR_NOT_SUPPORTED	Das System führt keinen Grafiktreiber aus, der gemäß dem Windows Display Driver Model (WDDM) geschrieben wurde. Die Funktion wird nur auf einem System unterstützt, auf dem ein WDDM-Treiber ausgeführt wird.
ERROR_ACCESS_DENIED	Der Aufrufer hat keinen Zugriff auf die Konsolensitzung. Dieser Fehler tritt auf, wenn der aufrufende Prozess keinen Zugriff auf den aktuellen Desktop hat oder in einer Remotesitzung ausgeführt wird.
ERROR_GEN_FAILURE	Es ist ein unbekannter Fehler aufgetreten.
ERROR_BAD_CONFIGURATION	Die Funktion konnte keine funktionsfähige Lösung für die Quell- und Zielmodi finden, die der Aufrufer nicht angegeben hat.

Hinweise

Die SetDisplayConfig-Funktion übernimmt die aktiven Anzeigepfade mit allen angegebenen Quell- und Zielmodusinformationen und verwendet die Logik des besten Modus, um fehlende Quell- und Zielmodusinformationen zu generieren. Diese Funktion legt dann den vollständigen Anzeigepfad fest.

Die ModeInfoIdx-Member in den DISPLAYCONFIG_PATH_SOURCE_INFO - und DISPLAYCONFIG_PATH_TARGET_INFO-Strukturen werden verwendet, um anzugeben, ob der Quell- und Zielmodus für einen bestimmten aktiven Pfad angegeben wird. Wenn der Indexwert für beide DISPLAYCONFIG_PATH_MODE_IDX_INVALID ist, gibt dies an, dass die Modusinformationen nicht angegeben werden. Sie ist gültig für den Pfad plus Quellmodus oder den Pfad plus Quell- und Zielmodusinformationen, die für einen bestimmten Pfad angegeben werden sollen. Es ist jedoch nicht gültig, dass der Pfad- und Zielmodus ohne den Quellmodus angegeben wird.

Die Quell- und Zielmodi für die einzelnen Quell- und Zielbezeichner können nur einmal im array modeInfoArray angezeigt werden. Beispielsweise kann ein Quellmodus für den Quellbezeichner S1 nur einmal in der Tabelle angezeigt werden. wenn mehrere Pfade auf dieselbe Quelle verweisen, müssen sie dieselbe ModeInfoIdx verwenden.

Es wird erwartet, dass die meisten Aufrufer QueryDisplayConfig verwenden, um die aktuelle Konfiguration zusammen mit anderen gültigen Möglichkeiten abzurufen und dann SetDisplayConfig zum Testen und Festlegen der Konfiguration zu verwenden.

Die Reihenfolge, in der die aktiven Pfade im PathArray-Array angezeigt werden, bestimmt die Pfadpriorität.

Standardmäßig ändert SetDisplayConfig niemals informationen zu Pfad, Quellmodus oder Zielmodus. Wenn die Beste Moduslogik keine Lösung finden kann, ohne die angegebenen Anzeigepfadinformationen zu ändern, schlägt SetDisplayConfig mit ERROR_BAD_CONFIGURATION fehl. In diesem Fall sollte der Aufrufer das SDC_ALLOW_CHANGES Flag angeben, damit die Funktion einige der angegebenen Quell- und Modusdetails optimieren kann, damit die Änderung des Anzeigepfads erfolgreich ist.

Wenn die angegebenen oder berechneten Quell- und Zielmodi dieselben Dimensionen aufweisen, legt SetDisplayConfig die Pfadskalierung automatisch auf DISPLAYCONFIG_PPR_IDENTITY fest, bevor der Anzeigepfad festgelegt und in der Datenbank gespeichert wird. Informationen zur Verarbeitung der Skalierung durch SetDisplayConfig finden Sie unter Skalieren des Desktopimages.

Wenn der Aufrufer das SDC_USE_SUPPLIED_DISPLAY_CONFIG-Flag angibt, um einen Klonpfad festzulegen, und wenn Quellmodusindizes im Pfadarray ungültig sind, bestimmt SetDisplayConfig , dass alle Quellmodusindizes aus dieser Quelle ungültig sind. SetDisplayConfig verwendet die beste Moduslogik, um die Quellmodusinformationen zu bestimmen.

Mit Ausnahme des flags SDC_TOPOLOGY_SUPPLIED (weitere Informationen zu SDC_TOPOLOGY_SUPPLIED finden Sie im folgenden Absatz), legen die SDC_TOPOLOGY_XXX-Flags letzte Anzeigepfadeinstellungen fest, einschließlich der Quell- und Zielmodusinformationen für diesen Topologietyp. Informationen zu gültigen SDC_TOPOLOGY_XXX Flagkombinationen finden Sie in der Beschreibung des Flags-Parameters . Die Parameter pathArray und modeInfoArray müssen NULL sein, und die zugeordneten Größen müssen 0 sein. Wenn beispielsweise SDC_TOPOLOGY_CLONE und SDC_TOPOLOGY_EXTEND festgelegt sind, verwendet diese Funktion die neueste Konfiguration des Anzeigepfads klonen oder erweitern. Wenn ein einzelner Topologietyp angefordert wird, wird die letzte Konfiguration dieses Typs verwendet. Wenn diese Topologie noch nie festgelegt wurde, verwendet SetDisplayConfig die beste Topologielogik, um die beste Topologie zu finden, und dann die logik des besten Modus, um den besten Quell- und Zielmodus zu finden. Wenn eine Kombination der Topologieflags festgelegt wurde und keines von ihnen Datenbankeinträge aufweist, wird die folgende Priorität verwendet. Für Laptops: klonen, erweitern, intern und dann extern; für Desktops ist die Priorität erweitern und dann klonen.

Der Aufrufer kann das SDC_TOPOLOGY_SUPPLIED-Flag angeben, um anzugeben, dass er nur die Pfadinformationen (Topologie) und Anforderungen festlegt, die SetDisplayConfig abruft und dann die Quell- und Zielmodusinformationen aus der Persistenzdatenbank verwendet. Wenn die aktiven Pfade, die der Aufrufer bereitstellt, keinen Eintrag in der Persistenzdatenbank enthalten, schlägt SetDisplayConfig fehl. Wenn der Aufrufer in diesem Fall SetDisplayConfig erneut mit denselben Pfaddaten, aber mit dem SDC_USE_SUPPLIED_DISPLAY_CONFIG Flags aufruft, verwendet SetDisplayConfig die Logik des besten Modus, um die Quell- und Zielmodusinformationen zu erstellen. Wenn der Aufrufer SDC_TOPOLOGY_SUPPLIED angibt, muss der Aufrufer den numModeInfoArrayElements-Parameter auf Null und den modeInfoArray-Parameter auf NULL festlegen. Der Aufrufer muss jedoch die Parameter pathArray und numPathArrayElements für die Pfadinformationen festlegen, die der Aufrufer benötigt. Der Aufrufer muss alle Quell- und Zielmodusindizes in diesen Pfaddaten als ungültig (DISPLAYCONFIG_PATH_MODE_IDX_INVALID) markieren.

Die folgende Tabelle enthält einige gängige Szenarien, in denen SetDisplayConfig zusammen mit den Flagkombinationen aufgerufen wird, die der Aufrufer an den Flags-Parameter übergibt, um die Szenarien zu erreichen.

Szenario	Flag-Kombination
Testen, ob eine angegebene Anzeigekonfiguration auf dem Computer unterstützt wird	SDC_VALIDATE \| SDC_USE_SUPPLIED_DISPLAY_CONFIG
Festlegen einer angegebenen Anzeigekonfiguration und Speichern in der Datenbank	SDC_APPLY \| SDC_USE_SUPPLIED_DISPLAY_CONFIG \| SDC_SAVE_TO_DATABASE
Festlegen einer temporären Anzeigekonfiguration (d. h. die Anzeigekonfiguration wird nicht gespeichert)	SDC_APPLY \| SDC_USE_SUPPLIED_DISPLAY_CONFIG
Testen, ob klonen auf dem Computer unterstützt wird	SDC_VALIDATE \| SDC_TOPOLOGY_CLONE
Festlegen der Klontopologie	SDC_APPLY \| SDC_TOPOLOGY_CLONE
Legen Sie die Klontopologie fest, und lassen Sie die Pfadpersistenz zu, wenn dies erforderlich ist, um die Anforderung zu erfüllen.	SDC_APPLY \| SDC_TOPOLOGY_CLONE \| SDC_PATH_PERSIST_IF_REQUIRED
Zurück von einem temporären Modus zur zuletzt gespeicherten Anzeigekonfiguration	SDC_APPLY\| SDC_USE_DATABASE_CURRENT
Legen Sie die Anzeigekonfiguration mit den Quell- und Zielinformationen aus der Datenbank für die Pfade fest, und ignorieren Sie die Pfadreihenfolge.	SDC_APPLY \| SDC_TOPOLOGY_SUPPLIED \| SDC_ALLOW_PATH_ORDER_CHANGES

DPI-Virtualisierung

Diese API ist nicht an der DPI-Virtualisierung beteiligt. Alle Größen in der DEVMODE-Struktur beziehen sich auf physische Pixel und beziehen sich nicht auf den aufrufenden Kontext.

Anforderungen


Unterstützte Mindestversion (Client)	Verfügbar in Windows 7 und höheren Versionen der Windows-Betriebssysteme.
Zielplattform	Universell
Header	winuser.h (einschließlich Windows.h)
Bibliothek	User32.lib
DLL	User32.dll
APIs	ext-ms-win-ntuser-sysparams-ext-l1-1-1 (eingeführt in Windows 10, Version 10.0.14393)