PFND3DDDI_CREATERESOURCE funzione di callback (d3dumddi.h)

Articolo
03/08/2023

La funzione CreateResource crea una risorsa.

Sintassi

PFND3DDDI_CREATERESOURCE Pfnd3dddiCreateresource;

HRESULT Pfnd3dddiCreateresource(
  HANDLE hDevice,
  D3DDDIARG_CREATERESOURCE *unnamedParam2
)
{...}

Parametri

hDevice

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

unnamedParam2

pResource [in, out]

Puntatore a una struttura D3DDDIARG_CREATERESOURCE che descrive la risorsa creata.

Valore restituito

CreateResource restituisce uno dei valori seguenti:

Codice restituito	Descrizione
S_OK	La risorsa viene creata correttamente.
E_OUTOFMEMORY	CreateResource non è riuscito ad allocare la memoria necessaria per il completamento.
D3DERR_NOTAVAILABLE	CreateResource non è riuscito a creare la risorsa per motivi diversi da non essere in grado di allocare memoria. CreateResourcecan restituisce questo errore solo durante la creazione di vertex o buffer di indice.

Commenti

La chiamata a CreateResource può contenere un elenco di superfici. Il membro SurfCount della struttura D3DDDIARG_CREATERESOURCE specificata dal parametro pResource 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 CreateResource , 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 CreateResource 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_CREATERESOURCE è un handle usato per identificare la risorsa. Il driver di visualizzazione in modalità utente deve archiviare il valore di hResource passato nella chiamata CreateResource e sovrascrivere il valore con un altro valore che il runtime di Microsoft Direct3D può usare quando viene restituita la chiamata CreateResource . In altre parole, nelle chiamate al runtime, il driver di visualizzazione in modalità utente usa il valore hResource passato a CreateResource; 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 CreateResource. 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_CREATERESOURCE.

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_CREATERESOURCE. 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 CreateResource 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_RESOURCEFLAGS vengono passati nel membro Flags di D3DDDIARG_CREATERESOURCE.

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_CREATERESOURCE nelle chiamate alla funzione CreateResource 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.

Il nuovo DDI CreateResource differisce da DdCreateSurface DDI per il modello di driver di visualizzazione di Microsoft Windows 2000 nei modi seguenti:

Nella nuova DDI CreateResource le superfici non vengono mai associate in modo esplicito. Tutti gli allegati sono impliciti nella creazione atomica.
Nella nuova DDI CreateResource non è consentita la creazione parziale delle mappe del cubo.

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 può creare il buffer per motivi diversi da memoria insufficiente (ad esempio, mancanza di supporto hardware), il driver deve avere esito negativo con D3DERR_NOTAVAILABLE.

Requisiti

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)