PFND3DDDI_CREATERESOURCE2 funzione di callback (d3dumddi.h)

Articolo
02/23/2024

Crea una risorsa. Implementato dai driver di visualizzazione Windows Display Driver Model (WDDM) 1.2 e versioni successive.

Sintassi

PFND3DDDI_CREATERESOURCE2 Pfnd3dddiCreateresource2;

HRESULT Pfnd3dddiCreateresource2(
  [in] HANDLE hDevice,
       D3DDDIARG_CREATERESOURCE2 *unnamedParam2
)
{...}

Parametri

[in] hDevice

Handle per il dispositivo di visualizzazione (contesto grafico) usato per creare la risorsa.

unnamedParam2

pResource2 [in, out]

Puntatore a una struttura D3DDDIARG_CREATERESOURCE2 che descrive la risorsa creata.

Valore restituito

Restituisce S_OK o un risultato di errore appropriato. I driver WDDM 1.3 e versioni successive direct3D Level 9 devono restituire questo codice di errore:

Codice restituito	Descrizione
E_INVALIDARG	Oggetto D3DDDIARG_CREATERESOURCE2 . Flagsmember ha il valore del flag CaptureBuffer impostato e la risorsa supera ciò che il driver può supportare.

Commenti

La chiamata a CreateResource2 può contenere un elenco di superfici. Il membro SurfCount della struttura D3DDDIARG_CREATERESOURCE2 specificata dal parametro pResource2 specifica il numero di superfici, inclusi i livelli della mappa MIP, da creare. Ad esempio, una risorsa mappa MIP con trama 256x256x9 contiene un elenco di nove superfici in cui il membro SurfCount e il numero di livelli della mappa MIP sono entrambi impostati su 9. Una mappa cubo che contiene nove livelli di mappa MIP deve avere il numero di livelli di mappa MIP impostati su 9 e SurfCount impostato su 54. Una catena di scambio a tre superfici deve avere SurfCount impostato su 3 e il numero di livelli della mappa MIP impostati su 0. Si noti che il numero di livelli della mappa MIP è sempre minore o uguale al valore in SurfCount.

In risposta alla chiamata CreateResource2 , il driver di visualizzazione in modalità utente può chiamare la funzione pfnAllocateCb per creare una o più allocazioni di memoria. Il driver di visualizzazione in modalità utente deve determinare se deve creare più allocazioni per superficie, un'allocazione per tutte le superfici o un'allocazione per ogni superficie. Per altre informazioni sulle allocazioni, vedere Gestione della memoria video e Pianificazione GPU.

Nota La funzione CreateResource2 del driver non è necessaria per chiamare pfnAllocateCb prima di restituire; Al contrario, il driver può rinviare la creazione dell'allocazione.

Nota Una risorsa può essere condivisa solo se tutte le allocazioni per la risorsa vengono effettuate in modo atomico in una singola chiamata a pfnAllocateCb.

Il membro hResource nella struttura D3DDDIARG_CREATERESOURCE2 è un handle usato per identificare la risorsa. Il driver di visualizzazione in modalità utente deve archiviare il valore di hResource passato nella chiamata CreateResource2 e sovrascrivere il valore con un altro valore che il runtime di Microsoft Direct3D può usare quando viene restituita la chiamata CreateResource2 . In altre parole, nelle chiamate al runtime, il driver di visualizzazione in modalità utente usa il valore hResource passato a CreateResource2; nelle chiamate al driver di visualizzazione in modalità utente (ad esempio, nelle chiamate alle funzioni SetTexture o SetStreamSource ), il runtime usa il valore hResource restituito da CreateResource2. Si noti che ogni superficie non ha un handle esplicito; se la superficie deve essere denominata singolarmente (ad esempio in una chiamata alla funzione Blt ), viene fatto riferimento a un handle e a un indice. L'indice identifica la superficie all'interno della risorsa. L'indice corrisponde all'indice della superficie nella matrice contenuta nel membro pSurfList di D3DDDIARG_CREATERESOURCE2.

Le risorse possono essere condivise da più dispositivi (hDevice) e processi. Il runtime specifica che una risorsa viene condivisa impostando il flag di campo di bit SharedResource nel membro Flags di D3DDDIARG_CREATERESOURCE2. Se questo flag di campo di bit è impostato, il driver di visualizzazione in modalità utente deve rispettare le restrizioni seguenti per le risorse condivise:

Il driver di visualizzazione in modalità utente può chiamare le funzioni pfnAllocateCb e pfnDeallocateCb esattamente una volta.
Il driver di visualizzazione in modalità utente non può creare allocazioni aggiuntive per la risorsa dopo la creazione iniziale della risorsa e in modo analogo può eliminare definitivamente le allocazioni delle risorse solo al momento in cui la risorsa stessa viene eliminata definitivamente.
Quando la funzione DestroyResource del driver di visualizzazione in modalità utente viene chiamata per una risorsa condivisa creata o aperta tramite una chiamata alla funzione CreateResource2 o OpenResource del driver, il driver deve impostare il membro hResource della struttura D3DDDICB_DEALLOCATE su non NULL e il membro NumAllocations di D3DDDICB_DEALLOCATE su zero in una chiamata alla funzione pfnDeallocateCb per eliminare o chiudere la risorsa. Ovvero, le allocazioni associate a una risorsa condivisa non possono essere eliminate o chiuse singolarmente; la risorsa deve essere eliminata o chiusa in modo atomico in una chiamata a pfnDeallocateCb.
Il numero di allocazioni deve essere coerente per il tipo di risorsa, ovvero un altro processo che sta creando lo stesso tipo di risorsa deve generare lo stesso numero e tipo di allocazioni. Inoltre, la ridenominazione non è consentita per queste risorse.

I flag di campo di bit specificati nella struttura D3DDDI_RESOURCEFLAGS2 vengono passati nel membro Flags di D3DDDIARG_CREATERESOURCE2.

Nota È possibile creare una risorsa senza specificare alcun flag. Le superfici associate a una risorsa di questo tipo possono essere potenzialmente bloccate e possono essere un'origine o una destinazione in un'operazione di trasferimento a blocchi di bit (bitblt). Tuttavia, tali superfici non possono essere utilizzate per qualsiasi altra cosa.

Nota Le superfici semplici si differenziano dalle trame o dalle destinazioni di rendering autonome in assenza del flag Trama o Campo di bit primario . Ad esempio, la presenza del flag campo di bit primario indica una destinazione di rendering autonoma e l'assenza di questo flag indica una destinazione di rendering che è un buffer nascosto.

Nota Per garantire che le modifiche apportate al runtime non interrompano i driver esistenti, i driver non devono usare i membri riservati seguenti della struttura D3DDDIARG_CREATERESOURCE2 nelle chiamate alla funzione CreateResource2 per influire sul comportamento dei driver:

I bit non definiti del membro Flags sono riservati.
Se il flag campo di bit primario non è impostato in Flag, i membri RefreshRate e Output sono riservati.
Se il flag di campo di bit RenderTarget, DecodeRenderTarget o VideoProcessRenderTarget non è impostato in Flag, i membri MultisampleType e MultisampleQuality sono riservati.
Se il flag di campo di bit VertexBuffer non è impostato in Flags, il membro Fvf è riservato.
Se i flag texture, CubeMap e Volume bit-field non sono impostati in Flags, il membro MipLevels è riservato.

Per altre informazioni sulla creazione e l'eliminazione delle risorse, vedere Gestione della creazione e della distruzione delle risorse.

Per una risorsa di memoria di sistema, il driver miniport di visualizzazione può scegliere di eseguire il wrapping di un'allocazione intorno alla memoria di sistema se la memoria di sistema è allineata correttamente per l'accesso diretto dall'unità di elaborazione grafica (GPU). Il driver miniport di visualizzazione esegue il wrapping di un'allocazione intorno alla memoria di sistema impostando il flag ExistingSysMem nel membro Flags della struttura DXGK_ALLOCATIONINFO durante la creazione dell'allocazione tramite la relativa funzione DxgkDdiCreateAllocation . Se il driver miniport di visualizzazione non può eseguire il wrapping di un'allocazione intorno alla memoria di sistema o il wrapping ha esito negativo, il driver deve comunque riuscire a creare la risorsa e usare la CPU per accedere alla risorsa.

Se il runtime richiede di creare un vertex o un buffer di indice e se il driver di visualizzazione in modalità utente non riesce a creare il buffer per motivi diversi da memoria insufficiente (ad esempio, mancanza di supporto hardware), il driver deve non riuscire con D3DERR_NOTAVAILABLE.

Requisiti

Requisito	Valore
Client minimo supportato	Windows 8
Server minimo supportato	Windows Server 2012
Piattaforma di destinazione	Desktop
Intestazione	d3dumddi.h (include D3dumddi.h)