DXGKDDI_CREATEALLOCATION Rückruffunktion (d3dkmddi.h)

Artikel
05/26/2023

Die DxgkDdiCreateAllocation-Funktion erstellt Zuordnungen des System- oder Videospeichers.

Syntax

DXGKDDI_CREATEALLOCATION DxgkddiCreateallocation;

NTSTATUS DxgkddiCreateallocation(
  [in]     IN_CONST_HANDLE hAdapter,
  [in/out] INOUT_PDXGKARG_CREATEALLOCATION pCreateAllocation
)
{...}

Parameter

[in] hAdapter

Ein Handle für einen Kontextblock, der einem Anzeigeadapter zugeordnet ist. Der Anzeigeminiporttreiber hat dieses Handle zuvor für das Microsoft DirectX-Grafikkernsubsystem im Ausgabeparameter MiniportDeviceContext der DxgkDdiAddDevice-Funktion bereitgestellt.

[in/out] pCreateAllocation

Ein Zeiger auf eine DXGKARG_CREATEALLOCATION-Struktur , die Informationen zum Erstellen von Zuordnungen enthält.

Rückgabewert

DxgkDdiCreateAllocation gibt einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
STATUS_SUCCESS	DxgkDdiCreateAllocation hat die Zuordnung erfolgreich erstellt.
STATUS_INVALID_PARAMETER	Parameter, die an DxgkDdiCreateAllocation übergeben wurden, enthielten Fehler, die den Abschluss verhinderten.
STATUS_NO_MEMORY	DxgkDdiCreateAllocation konnte keinen Speicher zuordnen, der für den Abschluss erforderlich war.
STATUS_GRAPHICS_DRIVER_MISMATCH	Der Anzeigeminiporttreiber ist nicht mit dem Anzeigetreiber für den Benutzermodus kompatibel, der den Aufruf von DxgkDdiCreateAllocation initiiert hat.

Hinweise

Nachdem der Benutzermodusanzeigetreiber die Funktion pfnAllocateCb aufgerufen hat , ruft das DirectX-Grafikkernsubsystem die DxgkDdiCreateAllocation-Funktion des Anzeigeminiporttreibers auf, um die Zuordnungen zu erstellen. Der Anzeigeminiporttreiber muss die privaten Daten (im pPrivateDriverData-Member der DXGK_ALLOCATIONINFO-Struktur für jede Zuordnung) interpretieren, die vom Benutzermodusanzeigetreiber übergeben werden, und die Liste der Parameter bestimmen, die zum Erstellen jeder Zuordnung über den Videospeicher-Manager erforderlich sind. Weitere Informationen dazu, wie der Anzeigeminiporttreiber diese Parameter an den Videospeicher-Manager bereitstellt, finden Sie unter Angeben von Segmenten beim Erstellen von Zuordnungen.

Der Anzeigeminiporttreiber muss ein Zuordnungshandle zurückgeben, bei dem es sich in der Regel um einen Zeiger auf eine private Treiberdatenstruktur handelt, die Informationen zur Zuordnung enthält. Der Anzeigeminiporttreiber kann die DxgkCbGetHandleData-Funktion jederzeit aufrufen, um die privaten Daten für ein Zuordnungshandle abzurufen. Daher ist der Anzeigeminiporttreiber nicht erforderlich, um eine private Zuordnungshandle-Tabelle zu verwalten. In der Tat wird dringend von privaten Handle-Tabellen abgeraten, da sie in Displaymodus-Switch-Szenarien wie schnellem Benutzerwechsel, Hot-Unplug usw. veraltet oder nicht mehr mit dem DirectX-Grafikkernsubsystem synchronisiert werden könnten.

Der Benutzermodusanzeigetreiber weist entweder einer Ressource oder einem Gerät eine Zuordnung zu. Um zu bestimmen, ob die Zuordnung zu einer Ressource gehört, kann der Anzeigeminiporttreiber überprüfen, ob das Resource-Bitfeldflag im Flags-Element der DXGKARG_CREATEALLOCATION-Struktur festgelegt ist, auf die der pCreateAllocation-Parameter von DxgkDdiCreateAllocation verweist. Wenn die Zuordnung zu einer Ressource gehört, kann der Anzeigeminiporttreiber ein Ressourcenhandle zurückgeben (ist aber nicht erforderlich), wobei es sich in der Regel um einen Zeiger auf eine private Treiberdatenstruktur handelt, die die Ressource beschreibt. Wenn das DirectX-Grafikkernsubsystem DxgkDdiCreateAllocation aufruft, um eine zusätzliche Zuordnung für eine vorhandene Ressource zu erstellen, enthält das hResource-Mitglied von DXGKARG_CREATEALLOCATION das Handle, das vom vorherigen DxgkDdiCreateAllocation-Aufruf für diese Ressource zurückgegeben wurde. Bei Bedarf kann der Anzeigeminiporttreiber den Ressourcenhandle während eines Aufrufs von DxgkDdiCreateAllocation ändern.

Wenn der Benutzermodusanzeigetreiber ein Ressourcenhandle in einem Befehlspuffer platziert, kann der Anzeigeminiporttreiber die privaten Daten abrufen, indem er DxgkCbGetHandleData aufruft. Der Anzeigeminiporttreiber kann auch alle untergeordneten Zuordnungen der Ressource auflisten, indem er die DxgkCbEnumHandleChildren-Funktion aufruft .

Wenn ab Windows 7 ein Anzeigeminiporttreiber einen Aufruf der DxgkDdiCreateAllocation-Funktion verarbeitet, um Zuordnungen für die GDI-Hardwarebeschleunigung zu erstellen, sollte der Treiber die Größe der Zuordnung (einschließlich des Pitchwerts für sichtbare CPU-Zuordnungen) festlegen, pCreateAllocation-pAllocationInfo-Size>.>

Die Ressourcen, die im DxgkDdiCreateAllocation-Aufruf erstellt werden, gehören zum Adapter und nicht zum Gerät. Der Anzeigeminiporttreiber sollte nicht auf die Gerätedaten innerhalb der privaten Zuordnungs- und Ressourcendatenstrukturen verweisen. Aufgrund der Gemeinsamen Nutzung von Oberflächen kann eine Ressource nach der Zerstörung des Geräts verwendet werden, aus dem der Benutzermodusanzeigetreiber die Ressource erstellt hat.

DxgkDdiCreateAllocation sollte seitenfähig gemacht werden.

Zuweisung von Verlaufspuffern

Ab Windows 8.1 kann der Anzeigeminiporttreiber beim Aufruf von DxgkDdiCreateAllocation die DXGK_ALLOCATIONINFOFLAGS festlegen.HistoryBuffer-Member, um anzugeben, dass der Benutzermodustreiber die Erstellung und Zerstörung von Verlaufspuffern verwalten kann.