PFND3DDDI_LOCKASYNC funzione di callback (d3dumddi.h)

Articolo
02/06/2025

La funzione lockAsync blocca la risorsa specificata o una superficie all'interno della risorsa.

Sintassi

PFND3DDDI_LOCKASYNC Pfnd3dddiLockasync;

HRESULT Pfnd3dddiLockasync(
  HANDLE hDevice,
  D3DDDIARG_LOCKASYNC *unnamedParam2
)
{...}

Parametri

hDevice

Handle per il dispositivo di visualizzazione (contesto grafico).

unnamedParam2

pData [in, out]

Puntatore a una struttura D3DDDIARG_LOCKASYNC che descrive la risorsa o la superficie all'interno della risorsa da bloccare.

Valore restituito

LockAsync restituisce uno dei valori seguenti:

codice restituito	Descrizione
S_OK	La risorsa è stata bloccata correttamente.
E_OUTOFMEMORY	LockAsync non è riuscito ad allocare la memoria necessaria per il completamento.
D3DDDIERR_WASSTILLDRAWING	Ridenominazione dell'allocazione corrispondente alla risorsa specificata dalla struttura D3DDDIARG_LOCKASYNC non riuscita. Il driver restituisce questo valore solo se il flag di campo di bit Discard è stato impostato nel membro Flags di D3DDDIARG_LOCKASYNC.
E_NOTIMPL	Il driver di visualizzazione in modalità utente non supporta LockAsync per la risorsa specificata.

Osservazioni

Nei computer con più processori, il runtime di Microsoft Direct3D potrebbe chiamare la maggior parte delle funzioni del driver di visualizzazione in modalità utente da un thread di lavoro anziché dal thread dell'applicazione principale. Questa ottimizzazione a più processori è trasparente per il driver di visualizzazione in modalità utente. Quando il runtime usa l'ottimizzazione a più processori, potrebbe chiamare LockAsync anziché la funzione lock per bloccare una risorsa.

Un driver di visualizzazione in modalità utente implementa facoltativamente LockAsync; Il runtime Direct3D chiama LockAsync solo se il driver implementa le funzioni lockAsync LockAsync, UnlockAsynce Rename. Tuttavia, un driver di visualizzazione in modalità utente deve implementare LockAsync e il UnlockAsync e Rinomina funzioni perché le applicazioni che bloccano frequentemente le risorse dinamiche possono quindi ottenere prestazioni migliori.

Quando il runtime Direct3D usa l'ottimizzazione a più processori, chiama la maggior parte delle funzioni del driver di visualizzazione in modalità utente da un thread di lavoro gestito dal runtime; Tuttavia, il runtime chiama LockAsync nel thread principale dell'applicazione.

Se un driver di visualizzazione in modalità utente espone una versione DDI di 0x0000000B o versione successiva (il driver restituisce questo valore nel membro DriverVersion della struttura D3D10DDIARG_OPENADAPTER in una chiamata alla funzione OpenAdapter del driver), il runtime Direct3D chiamerà LockAsync in modo ricorsivo. Quando il runtime chiama LockAsync in modo reentrant, un thread può essere eseguito all'interno di LockAsync mentre un altro thread che fa riferimento allo stesso dispositivo di visualizzazione viene eseguito all'interno di un'altra funzione driver di visualizzazione in modalità utente. Inoltre, in questo tipo di driver, il runtime chiamerà LockAsync per le superfici di memoria di sistema. Se il flag Discard bit-field è impostato nel Flag membro di D3DDDIARG_LOCKASYNC, il driver deve tentare di rinominare l'allocazione corrispondente alla risorsa. In genere, per rinominare un'allocazione, il driver chiama la funzione pfnLockCb con l'handle di allocazione corrispondente alla risorsa da bloccare.

Il driver deve impostare il flag Discard bit-field nel membro flag della struttura D3DDDICB_LOCK quando il driver chiama pfnLockCb. Il driver deve impostare il flag di D3DDDICB_LOCK NoExistingReference bit quando il driver chiama pfnLockCb solo se il flag NoExistingReferences bit-field è impostato su TRUE nel Flag membro di D3DDDIARG_LOCKASYNC, e il driver non ha riferimenti accodati internamente alla risorsa.

Se il driver non rinomina l'allocazione, la funzione LockAsync del driver deve restituire l'errore al runtime e il driver non deve scaricare il buffer dei comandi. Se la ridenominazione ha esito positivo, il driver deve restituire puntatori alla memoria delle risorse, all'inclinazione e alla sezione e a un handle per la risorsa che rappresenta l'allocazione rinominata nei membri di D3DDDIARG_LOCKASYNC. Il driver non deve aggiornare le strutture di rilevamento interne con il nuovo handle di allocazione che pfnLockCb restituisce. Al contrario, il driver deve attendere fino a quando non viene chiamata la funzione Rename.

Se il flag di NoOverwrite campo di bit viene impostato nel membro flag di di D3DDDIARG_LOCKASYNC, il driver deve bloccare l'allocazione corrispondente senza sovrascrivere semantica. Il driver deve chiamare pfnLockCb con il flag IgnoreSync campo di bit impostato nel Flag membro di D3DDDICB_LOCK e deve restituire i puntatori alla memoria delle risorse, al passo e al passo delle sezioni al runtime Direct3D nei membri di D3DDDIARG_LOCKASYNC. Se il driver restituisce esito positivo (S_OK) da una chiamata al relativo LockAsync con il NoOverwrite set di flag di campo di bit, potrebbe essere chiamato per eseguire il rendering con una superficie bloccata. Il driver deve restituire l'esito positivo di una chiamata al relativo LockAsync con NoOverwrite impostato solo per le superfici di cui è possibile eseguire il rendering durante il blocco. La gestione della memoria video richiede che le allocazioni corrispondenti alle superfici siano supportate nei segmenti AGP o aperture; in caso contrario, le chiamate al pfnRenderCb funzione hanno esito negativo quando il buffer dei comandi fa riferimento a un'allocazione bloccata.

In sintesi, il driver deve non eseguire chiamate alla relativa funzione LockAsync se la ridenominazione ha esito negativo o se la semantica di sovrascrittura non è supportata per la risorsa. Tuttavia, il runtime Direct3D verrà ripristinato da questi errori. Per tutte le altre situazioni, i driver devono restituire risultati positivi da LockAsync per migliorare le prestazioni nei computer con più processori.

Fabbisogno

Requisito	Valore
client minimo supportato	Disponibile in Windows Vista e versioni successive dei sistemi operativi Windows.
piattaforma di destinazione	Desktop
intestazione	d3dumddi.h (include D3dumddi.h)