PFND3DDDI_ALLOCATECB Rückruffunktion (d3dumddi.h)

Artikel
08/07/2023

Die pfnAllocateCb-Funktion weist System- oder Videospeicher zu.

Syntax

PFND3DDDI_ALLOCATECB Pfnd3dddiAllocatecb;

HRESULT Pfnd3dddiAllocatecb(
  [in] HANDLE hDevice,
       D3DDDICB_ALLOCATE *unnamedParam2
)
{...}

Parameter

[in] hDevice

Ein Handle für das Anzeigegerät (Grafikkontext).

unnamedParam2

pData [ein, aus]

Ein Zeiger auf eine D3DDDICB_ALLOCATE Struktur, die die Zuordnung beschreibt.

Rückgabewert

pfnAllocateCb gibt einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
S_OK	Der Arbeitsspeicher wurde erfolgreich zugewiesen.
E_INVALIDARG	Parameter wurden überprüft und als falsch ermittelt.
E_OUTOFMEMORY	PfnAllocateCb konnte keinen Speicher zuordnen, der für die Vervollständigung erforderlich war.
D3DERR_OUTOFVIDEOMEMORY	pfnAllocateCb konnte aufgrund unzureichendem Videospeicher nicht abgeschlossen werden. Der Videospeicher-Manager versucht, den Videospeicher zu virtualisieren. Wenn jedoch bei der Virtualisierung ein Fehler auftritt (z. B. wenn der virtuelle Adressraum nicht mehr verfügbar ist), gibt der Speicher-Manager möglicherweise diesen Fehlercode zurück.
D3DDDIERR_DEVICEREMOVED	pfnAllocateCb konnte keinen Aufruf der DxgkDdiCreateAllocation-Funktion des Anzeigeminiporttreibers initiieren, da ein Plug & Play (PnP) beendet oder ein TimeoutErkennungs- und Wiederherstellungsereignis (Timeout Detection and Recovery, TDR) aufgetreten ist. Die Benutzermodusanzeigetreiberfunktion, die pfnAllocateCb aufgerufen hat (in der Regel die Funktion CreateResource, CreateResource(D3D10) oder CreateResource(D3D11), muss diesen Fehlercode an die Direct3D-Runtime zurückgeben. Direct3D Version 9 Hinweis: Weitere Informationen zum Zurückgeben von Fehlercodes finden Sie unter Zurückgeben von Fehlercodes, die von Laufzeitfunktionen empfangen wurden. Direct3D, Versionen 10 und 11 Hinweis: Wenn die Treiberfunktion keinen Wert zurückgibt (das heißt, hat VOID für einen Rückgabeparametertyp), ruft die Treiberfunktion die Funktion pfnSetErrorCb auf, um einen Fehlercode zurück an die Runtime zu senden. Weitere Informationen zur Behandlung von Fehlercodes finden Sie unter Behandeln von Fehlern.

Diese Funktion kann auch andere HRESULT-Werte zurückgeben.

Hinweise

Ein Benutzermodusanzeigetreiber ruft pfnAllocateCb auf, um System- oder Videospeicher zuzuweisen (auch als Zuordnung bezeichnet). Das Microsoft DirectX-Grafikkernsubsystem (Dxgkrnl.sys) ruft dann die DxgkDdiCreateAllocation-Funktion des Anzeigeminiporttreibers auf, um die privaten Daten zu interpretieren und zu speichern, die in der PfnAllocateCb-Anforderung übergeben wurden. Der Anzeigeminiporttreiber gibt Informationen aus dem DxgkDdiCreateAllocation-Aufruf zurück, den der Videospeicher-Manager (der Teil vonDxgkrnl.sysist) verwendet, um den Arbeitsspeicher tatsächlich zuzuweisen.

Der Benutzermodusanzeigetreiber erstellt in der Regel eine Zuordnung als Reaktion auf einen Aufruf der Funktion CreateResource, CreateResource(D3D10) oder CreateResource(D3D11). Der Benutzermodusanzeigetreiber kann jedoch jederzeit eine Zuordnung erstellen, z. B. wenn die CreateDevice-Funktion des Treibers im Benutzermodus oder die CreateDevice(D3D10) -Funktion Scratchpad-Bereiche im Videospeicher erstellt.

Der Benutzermodusanzeigetreiber kann die folgenden Zuordnungstypen erstellen:

Systemspeicherzuordnungen, in denen die Microsoft Direct3D-Runtime den Systemspeicher vorab zugeordnet. In dieser Situation kann der Benutzermodusanzeigetreiber keine Ausrichtung oder andere Parameter festlegen. Wenn der Benutzermodusanzeigetreiber vorab zugewiesenen Systemspeicher erfordert, auf den die Hardware zugreifen kann, ruft er pfnAllocateCb auf. Die Direct3D-Runtime gibt den Systemspeicherzeiger im pSystemMem-Member der D3DDDI_ALLOCATIONINFO-Struktur für Elemente im pAllocationInfo-Member der D3DDDICB_ALLOCATE-Struktur zurück, auf die von pData verwiesen wird. Wenn der Benutzermodusanzeigetreiber keinen vorab zugewiesenen Systemspeicher erfordert, auf den die Hardware zugreifen kann, sollte pfnAllocateCb für diesen Speichertyp nicht aufgerufen werden.
System- und Videospeicherzuordnungen, an denen der Benutzermodusanzeigetreiber an der Erstellung teilnehmen kann.

Wenn der Treiber versucht, mehrere Zuordnungen zu erstellen, kann der Treiber alle Zuordnungen einer übergeordneten Ressource zuordnen (z. B. beim Erstellen einer Drehkette, in der jeder Backbuffer eine individuelle Zuordnung ist). Der Treiber kann eine solche Zuordnung ausführen, indem er das hResource-Member der D3DDDICB_ALLOCATE Struktur festlegt, auf die von pData auf den Wert festgelegt wird, der an die CreateResource -, CreateResource(D3D10)- oder CreateResource(D3D11)-Funktion des Treibers übergeben wurde. Als Antwort gibt die Direct3D-Runtime ein Kernelmodus-Ressourcenhandle (das vom datentyp D3DKMT_HANDLE ist) im hKMResource-Member von D3DDDICB_ALLOCATE zurück. Der Benutzermodusanzeigetreiber kann diesen Kernelmodus-Ressourcenhandle anschließend zur Verwendung durch den Anzeigeminiporttreiber in den Befehlsstream einfügen.

Der Anzeigeminiporttreiber kann die DxgkCbGetHandleData-Funktion für dieses Kernelmodusressourcenhandle aufrufen (in der Regel innerhalb der DxgkDdiRender-Funktion ), um private Daten abzurufen, die der Ressource zugeordnet sind, oder der Anzeigeminiporttreiber kann die DxgkCbEnumHandleChildren-Funktion aufrufen, um alle Zuordnungen abzurufen, die der Ressource zugeordnet sind. Der Anzeigeminiporttreiber kann auch die DxgkCbGetHandleParent-Funktion aufrufen, um das übergeordnete Kernelmodusressourcenhandle aus einem untergeordneten Zuordnungshandle abzurufen.

Beachten Sie, dass die Zuordnung dem Gerät und nicht einer Ressource zugeordnet wird, wenn das hResource-Element von D3DDDICB_ALLOCATE auf NULL festgelegt ist, wenn der Benutzermodusanzeigetreiber pfnAllocateCb aufruft. Der Treiber kann nur feststellen, dass der Unterschied semantisch ist. Das Zuordnen von Zuordnungen zu einer Ressource ist optional, wird jedoch für Debugging- und Diagnosezwecke empfohlen.

Direct3D Version 9 Hinweis: Weitere Informationen zum Erstellen und Zerstören von Ressourcen finden Sie unter Behandeln von Ressourcenerstellung und -zerstörung.

Direct3D Version 11 Hinweis: Weitere Informationen dazu, wie der Treiber pfnAllocateCb aufruft, finden Sie unter Änderungen von Direct3D 10.

Das folgende Codebeispiel zeigt, wie Sie Arbeitsspeicher für eine Ressource zuweisen.

    D3DDDICB_ALLOCATE           allocCB;
    D3DDDI_ALLOCATIONINFO       allocInfo;
    HRESULT                     hr;
    memset(&allocInfo,   0, sizeof(allocInfo));
    memset(&allocCB,     0, sizeof(allocCB));
    // Set the VidPN source ID for the primary and fullscreen back buffer
    if (m_dwCurResCaps.Primary) {
        allocInfo.Flags.Primary = TRUE;
        allocInfo.VidPnSourceId = m_VidPnSourceId;
    }
    // Check if the allocation is in system memory
    if (pSysMem) {
        allocInfo.pSystemMem = pSysMem;
    }
    // Use the runtime handle of the resource being created
    // NOTE: This is critical for supporting a shared resource
    allocCB.hResource = m_hCurResRuntime;

    allocCB.NumAllocations = 1;
    allocCB.pAllocationInfo = &allocInfo;

    hr = m_d3dCallbacks.pfnAllocateCb(m_hD3D, &allocCB);

    if (FAILED(hr)) {
        allocInfo.hAllocation = NULL;
    }
    else {
        *phAllocation = allocInfo.hAllocation;
    }

    return (hr);

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Verfügbar in Windows Vista und höheren Versionen der Windows-Betriebssysteme.
Zielplattform	Desktop
Kopfzeile	d3dumddi.h (include D3dumddi.h)