PFND3DDDI_ALLOCATECB Rückruffunktion (d3dumddi.h)

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 gibt einen der folgenden Werte zurück:

Rückgabecode Beschreibung
S_OK Der Speicher wurde erfolgreich zugewiesen.
E_INVALIDARG Parameter wurden überprüft und festgestellt, 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 Speichermanager möglicherweise diesen Fehlercode zurück.
D3DDDIERR_DEVICEREMOVED pfnAllocateCb konnte keinen Aufruf der DxgkDdiCreateAllocation-Funktion des Anzeigeminiporttreibers initiieren, da ein technologie Plug and Play (PnP)-Stopp oder ein Timeout-Erkennungs- und Wiederherstellungsereignis (TDR) aufgetreten ist. Die Anzeigetreiberfunktion des Benutzermodus, die pfnAllocateCb (in der Regel createResource, CreateResource(D3D10)- oder CreateResource(D3D11)-Funktion aufgerufen wird, muss diesen Fehlercode wieder an die Direct3D-Laufzeit 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 (d. h. VOID für einen Rückgabeparametertyp), ruft die Treiberfunktion die PfnSetErrorCb-Funktion auf, um einen Fehlercode an die Laufzeit zurückzusenden. Weitere Informationen zum Behandeln von Fehlercodes finden Sie unter Behandeln von Fehlern.

Diese Funktion gibt möglicherweise auch andere HRESULT-Werte zurück.

Bemerkungen

Ein Benutzermodus zeigt Treiberanrufe pfnAllocateCb an, um System- oder Videospeicher zuzuweisen (auch bekannt als Zuordnung). Das Microsoft DirectX-Grafik-Kernel-Subsystem (Dxgkrnl.sys) ruft dann die DxgkDdiCreateAllocation-Funktion des Display-Miniport-Treibers auf, um die privaten Daten zu interpretieren und zu speichern, die in der pfnAllocateCb-Anforderung übergeben wurden. Der Anzeige-Miniporttreiber gibt Informationen vom DxgkDdiCreateAllocation-Aufruf zurück, den der Videospeicher-Manager ( teilDxgkrnl.sys) 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 Funktion CreateResource, CreateResource(D3D10) oder CreateResource(D3D11). Der Anzeigetreiber für den Benutzermodus kann jedoch jederzeit eine Zuordnung erstellen– z. B. wenn der Benutzermodus die CreateDevice- oder CreateDevice(D3D10) -Funktion ein Scratch-Pad-Bereich im Videospeicher erstellt.

Der Anzeigetreiber für den Benutzermodus kann die folgenden Arten von Zuordnungen erstellen:

  • Systemspeicherzuweisungen, in denen die Microsoft Direct3D-Runtime den Systemspeicher vorkonfiguriert. In dieser Situation kann der Anzeigetreiber des Benutzermodus keine Ausrichtung oder einen anderen Parameter festlegen. Wenn der Anzeigetreiber für den Benutzermodus vorinstallierten Systemspeicher erfordert, auf den die Hardware zugegriffen werden kann, ruft er pfnAllocateCb auf. Die Direct3D-Laufzeit gibt den Systemspeicherzeiger im pSystemMem-Element der D3DDDI_ALLOCATIONINFO-Struktur für Elemente im pAllocationInfo-Element der D3DDDICB_ALLOCATE Struktur zurück, die von pData verweist. Wenn der Anzeigetreiber für den Benutzermodus keinen vordefinierten Systemspeicher erfordert, auf den die Hardware zugegriffen werden kann, sollte pfnAllocateCb für diesen Speichertyp nicht aufgerufen werden.
  • System- und Videospeicherzuweisungen, bei denen der Anzeigetreiber des Benutzermodus 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 Flippingchain, in der jeder Backbuffer eine einzelne Zuordnung ist). Der Treiber kann eine solche Zuordnung ausführen, indem sie das hResource-Element der D3DDDICB_ALLOCATE Struktur festlegen, auf die pData auf den Wert verweist, der an die CreateResource-, CreateResource(D3D10)- oder CreateResource(D3D11) -Funktion übergeben wurde. Als Antwort gibt die Direct3D-Laufzeit im hKMResource-Element des D3DDDICB_ALLOCATE einen Kernelmodus-Ressourcenhandpunkt (der vom Datentyp D3DKMT_HANDLE ist) zurück. Der Anzeigetreiber für den Benutzermodus kann anschließend dieses Kernelmodus-Ressourcenhandle in den Befehlsdatenstrom einfügen, um vom Anzeige-Miniport-Treiber zu verwenden.

Der Display-Miniport-Treiber kann die DxgkCbGetHandleData-Funktion auf diesem Kernelmodus-Ressourcenhandle (in der Regel innerhalb seiner DxgkDdiRender-Funktion ) aufrufen, um private Daten abzurufen, die der Ressource zugeordnet sind, oder der Anzeige-Miniport-Treiber kann die DxgkCbEnumHandleChildren-Funktion aufrufen, um alle Zuordnungen abzurufen, die der Ressource zugeordnet sind. Der Display-Miniport-Treiber kann auch die DxgkCbGetHandleParent-Funktion aufrufen, um den übergeordneten Kernelmodus-Ressourcenhandle aus einem untergeordneten Zuordnungshandle abzurufen.

Beachten Sie, dass, wenn das hResource-Element von D3DDDICB_ALLOCATE auf NULL festgelegt ist, wenn der Benutzermodus-Anzeigetreiber pfnAllocateCb aufruft, wird die Zuordnung dem Gerät anstelle einer Ressource zugeordnet. 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 Handling Resource Creation and Destruction.

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

Im folgenden Codebeispiel wird gezeigt, 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

   
Unterstützte Mindestversion (Client) Verfügbar in Windows Vista und späteren Versionen der Windows-Betriebssysteme.
Zielplattform Desktop
Header d3dumddi.h (include D3dumddi.h)

Siehe auch

CreateDevice

CreateDevice(D3D10)

CreateResource

CreateResource(D3D10)

CreateResource(D3D11)

D3DDDICB_ALLOCATE

D3DDDI_ALLOCATIONINFO

D3DDDI_DEVICECALLBACKS

DxgkCbEnumHandleChildren

DxgkCbGetHandleData

DxgkCbGetHandleParent

DxgkDdiCreateAllocation  

Direct3D-Runtime-Funktionen, die von den User-Mode Anzeigetreibern aufgerufen werden