PFND3DDDI_ALLOCATECB Rückruffunktion (d3dumddi.h)

Artikel
02/06/2025

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- [in, out]

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

Rückgabewert

pfnAllocateCb einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
S_OK	Der Speicher wurde erfolgreich zugeordnet.
E_INVALIDARG	Parameter wurden überprüft und ermittelt, dass sie falsch sind.
E_OUTOFMEMORY	pfnAllocateCb konnte keinen Speicher zuordnen, der für den Abschluss erforderlich war.
D3DERR_OUTOFVIDEOMEMORY	pfnAllocateCb konnte aufgrund unzureichender Videospeicher nicht abgeschlossen werden. Der Videospeicher-Manager versucht, den Videospeicher zu virtualisieren; Wenn die Virtualisierung jedoch fehlschlägt (z. B. wenn der virtuelle Adressraum ausläuft), gibt der Speicher-Manager möglicherweise diesen Fehlercode zurück.
D3DDDIERR_DEVICEREMOVED	pfnAllocateCb konnte keinen Aufruf des DxgkDdiCreateAllocation-Funktion des Anzeigeminiporttreibers initiieren, da ein Plug and Play (PnP)-Stopp oder ein Timeout-Erkennungs- und Wiederherstellungsereignis (Timeout Detection and Recovery, TDR) aufgetreten ist. Die Anzeigetreiberfunktion für den Benutzermodus, die pfnAllocateCb (in der Regel die CreateResource-, CreateResource(D3D10)-oder CreateResource(D3D11)--Funktion) aufgerufen hat, muss diesen Fehlercode wieder an die Direct3D-Laufzeit zurückgeben. Direct3D Version 9 Hinweis: Weitere Informationen zum Zurückgeben von Fehlercodes finden Sie unter Rückgabe von Fehlercodes, die von Laufzeitfunktionenempfangen wurden. Direct3D-Versionen 10 und 11 Hinweis: Wenn die Treiberfunktion keinen Wert zurückgibt (d. h. leer für einen Rückgabeparametertyp), ruft die Treiberfunktion die pfnSetErrorCb--Funktion auf, um einen Fehlercode zurück an die Laufzeit zu senden. Weitere Informationen zum Behandeln von Fehlercodes finden Sie unter Behandlung von Fehlern.

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

Bemerkungen

Ein Benutzermodus-Anzeigetreiber ruft pfnAllocateCb auf, um System- oder Videospeicher zuzuweisen (auch bekannt als Zuordnung). Das Microsoft DirectX-Grafik-Kernel-Subsystem (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 Aufrufen zurück, den der Videospeicher-Manager (der Teil von Dxgkrnl.sysist) verwendet, um den Speicher tatsächlich zuzuweisen.

Der Anzeigetreiber für den Benutzermodus erstellt in der Regel eine Zuordnung als Reaktion auf einen Aufruf der CreateResource, CreateResource(D3D10)oder CreateResource(D3D11) Funktion. Der Anzeigetreiber im Benutzermodus kann jedoch jederzeit eine Zuordnung erstellen, z. B. wenn die CreateDevice-des Benutzermodus oder CreateDevice(D3D10) Funktion Kratzerbereiche im Videospeicher erstellt.

Der Anzeigetreiber für den Benutzermodus kann die folgenden Zuordnungstypen erstellen:

Systemspeicherzuweisungen, in denen die Microsoft Direct3D-Laufzeit den Systemspeicher vorschreibt. In diesem Fall kann der Anzeigetreiber für den Benutzermodus keine Ausrichtung oder einen anderen Parameter festlegen. Wenn der Anzeigetreiber für den Benutzermodus vorab zugewiesenen Systemspeicher benötigt, auf den die Hardware zugreifen kann, wird pfnAllocateCbaufgerufen. Die Direct3D-Laufzeit 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 Anzeigetreiber für den Benutzermodus keinen vorab zugewiesenen Systemspeicher erfordert, auf den die Hardware zugreifen kann, sollte pfnAllocateCb- für diesen Speichertyp nicht aufgerufen werden.
System- und Videospeicherzuweisungen, 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 Flippingkette, in der jeder Backbuffer eine individuelle Zuordnung ist). Der Treiber kann eine solche Zuordnung ausführen, indem das hResource Member der D3DDDICB_ALLOCATE-Struktur festgelegt wird, auf die pData- auf den Wert festgelegt wird, der an die CreateResource-des Treibers übergeben wurde, CreateResource(D3D10)oder CreateResource(D3D11) Funktion. Als Reaktion gibt die Direct3D-Laufzeit ein Kernelmodus-Ressourcenhandle (das vom datentyp D3DKMT_HANDLE ist) im hKMResource Mitglied von D3DDDICB_ALLOCATE zurück. Der Anzeigetreiber für den Benutzermodus kann anschließend dieses Kernelmodusressourcenhandle in den Befehlsdatenstrom einfügen, der vom Anzeigeminiporttreiber verwendet werden kann.

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

Beachten Sie, dass, wenn das hResource Member von D3DDDICB_ALLOCATE auf NULL- festgelegt ist, wenn der Benutzermodustreiber pfnAllocateCbaufruft, die Zuordnung dem Gerät anstelle einer Ressource zugeordnet ist. Der Treiber kann nur bestimmen, 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 Umgang mit der Ressourcenerstellung und -zerstörung.

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

Das folgende Codebeispiel zeigt, wie Speicher für eine Ressource zugewiesen wird.

    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
mindestens unterstützte Client-	Verfügbar in Windows Vista und höheren Versionen der Windows-Betriebssysteme.
Zielplattform-	Desktop
Header-	d3dumddi.h (include D3dumddi.h)