PFND3DDDI_UNLOCKCB Rückruffunktion (d3dumddi.h)

Artikel
02/23/2024

Die pfnUnlockCb-Funktion entsperrt eine Zuordnung, die durch einen Aufruf der pfnLockCb-Funktion gesperrt wurde.

Syntax

PFND3DDDI_UNLOCKCB Pfnd3dddiUnlockcb;

HRESULT Pfnd3dddiUnlockcb(
  HANDLE hDevice,
  const D3DDDICB_UNLOCK *unnamedParam2
)
{...}

Parameter

hDevice

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

unnamedParam2

pData [in]

Ein Zeiger auf eine D3DDDICB_UNLOCK Struktur, die die zu entsperrende Zuordnung beschreibt.

Rückgabewert

pfnUnlockCb gibt einen der folgenden Werte zurück:

Rückgabecode	Beschreibung
S_OK	Die Zuordnung wurde erfolgreich entsperrt.
E_OUTOFMEMORY	pfnUnlockCb konnte aufgrund von unzureichendem Arbeitsspeicher nicht abgeschlossen werden. (Dieser Fehler tritt auf, wenn sich das System in einer extrem niedrigen Speichersituation befindet und nicht genügend Speicherplatz zum Zuordnen des Seitenarrays vorhanden ist.)
E_INVALIDARG	Parameter wurden überprüft und als falsch ermittelt.

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

Hinweise

Der Benutzermodusanzeigetreiber muss die PfnUnlockCb-Funktion aufrufen, um eine Zuordnung zu entsperren, die zuvor in einem Aufruf der pfnLockCb-Funktion gesperrt wurde. Wenn der Treiber pfnUnlockCb nicht aufruft, geht die Koordination zwischen der Microsoft Direct3D-Runtime, dem Benutzermodusanzeigetreiber und dem Anzeigeminiporttreiber verloren.

Der Benutzermodusanzeigetreiber ruft in der Regel pfnUnlockCb als Reaktion auf einen Aufruf seiner Unlock - oder ResourceUnmap-Funktion (oder andere Variationen von ResourceUnmap wie DynamicIABufferUnmap) auf, um eine Ressource oder eine Oberfläche innerhalb der Ressource zu entsperren. Bevor der Aufruf vom Unlock - oder ResourceUnmap-Aufruf zurückgegeben wird, muss der Benutzermodusanzeigetreiber zuerst die Ressource oder Oberfläche der entsprechenden Zuordnung zuordnen und dann pfnUnlockCb aufrufen, um die Zuordnung zu entsperren.

Der Benutzermodusanzeigetreiber kann auch pfnUnlockCb als Reaktion auf einen Aufruf seiner DestroyDevice - oder DestroyDevice(D3D10)-Funktion aufrufen, um alle Ressourcen freizugeben, die er dem Gerät zugewiesen hat. Während der Lebensdauer eines Geräts muss jeder Aufruf von pfnLockCb zum Sperren einer Zuordnung mit einem Aufruf der pfnUnlockCb-Funktion gekoppelt werden, um die Zuordnung zu entsperren.

Der Benutzermodusanzeigetreiber kann mehrere Zuordnungen in einem Aufruf von pfnUnlockCb entsperren, indem das NumAllocations-Element der D3DDDICB_UNLOCK-Struktur auf die Anzahl der Zuordnungen in dem Array festgelegt wird, das vom phAllocations-Member von D3DDDICB_UNLOCK angegeben wird.

Der Benutzermodusanzeigetreiber sollte pfnUnlockCb aufrufen, um alle Zuordnungen zu entsperren, auf die im Befehlsstream verwiesen wird, bevor die PfnRenderCb-Funktion aufgerufen wird. Der Treiber könnte Zuordnungen für die Unterstützung gesperrt haben, z. B. das NoOverwrite-Bitfeldflag . Wenn der Treiber nicht alle diese Zuordnungen entsperrt, ist der Videospeicher-Manager möglicherweise erforderlich, um diese Zuordnungen im AGP-Arbeitsspeicher zu platzieren.

Der Benutzermodusanzeigetreiber sollte pfnUnlockCb nicht aufrufen, um eine Zuordnung zu entsperren, die eine Anwendung verwenden könnte. Der Treiber wird benachrichtigt, dass die Anwendung nicht mehr aus der Zuordnung liest oder in diese schreibt, wenn der Treiber einen Aufruf seiner Unlock - oder ResourceUnmap-Funktion für die entsprechende Ressource empfängt.

Beispiele

Im folgenden Codebeispiel wird das Entsperren einer Zuordnung veranschaulicht.

HRESULT CD3DContext::SyncEnginesUsingLock(VOID) {
    HRESULT hr;
    D3DDDICB_LOCK   lockCB;
    D3DDDICB_UNLOCK Unlock;

    memset(&lockCB, 0, sizeof(D3DDDICB_LOCK));
    lockCB.hAllocation = m_HandleUsedInLastSubmit;
    lockCB.PrivateDriverData = 0;                       
    hr = m_d3dCallbacks.pfnLockCb(m_hD3D, &lockCB);
    if (FAILED(hr)) {
        DBG_BREAK;
        return hr;
    }
    Unlock.NumAllocations = 1;
    Unlock.phAllocations = &m_HandleUsedInLastSubmit;
    m_d3dCallbacks.pfnUnlockCb(m_hD3D, &Unlock);   
    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)