struttura DXGI_DDI_BASE_FUNCTIONS (dxgiddi.h)

Articolo
03/08/2023

La struttura DXGI_DDI_BASE_FUNCTIONS contiene funzioni che il driver di visualizzazione in modalità utente può implementare per eseguire attività di basso livello, ad esempio la presentazione di fotogrammi sottoposti a rendering in un output, il controllo della gamma e la gestione di una transizione a schermo intero.

Sintassi

typedef struct DXGI_DDI_BASE_FUNCTIONS {
  HRESULT()(DXGI_DDI_ARG_PRESENT *) * pfnPresent;
  HRESULT()(DXGI_DDI_ARG_GET_GAMMA_CONTROL_CAPS *) * pfnGetGammaCaps;
  HRESULT()(DXGI_DDI_ARG_SETDISPLAYMODE *) * pfnSetDisplayMode;
  HRESULT()(DXGI_DDI_ARG_SETRESOURCEPRIORITY *) * pfnSetResourcePriority;
  HRESULT()(DXGI_DDI_ARG_QUERYRESOURCERESIDENCY *) * pfnQueryResourceResidency;
  HRESULT()(DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES *) * pfnRotateResourceIdentities;
  HRESULT()(DXGI_DDI_ARG_BLT *) * pfnBlt;
} DXGI_DDI_BASE_FUNCTIONS;

Members

pfnPresent

Puntatore alla funzione PresentDXGI che notifica al driver di visualizzazione in modalità utente che un'applicazione ha completato il rendering e richiede che il driver venga visualizzato nell'area di destinazione.

Il membro hDevice della struttura DXGI_DDI_ARG_PRESENT a cui punta il parametro pPresentData è lo stesso handle a cui fa riferimento la funzione CreateDevice(D3D10) del driver passato al runtime nel membro hDrvDevice della struttura D3D10DDIARG_CREATEDEVICE . Pertanto, i writer di driver devono definire attentamente il tipo di questo handle. Inoltre, i driver possono fornire implementazioni diverse della funzione PresentDXGI in base alla quale l'implementazione DDI ha gestito la chiamata a CreateDevice(D3D10). Il runtime non combina mai handle di driver tra implementazioni DDI. Analogamente, i membri hSurfaceToPresent e hDstResource di DXGI_DDI_ARG_PRESENT sono anche handle di risorse definiti dal driver restituiti al runtime nelle chiamate precedenti alla funzione CreateResource(D3D10) del driver.

Il membro pDXGIContext di DXGI_DDI_ARG_PRESENT è un meccanismo di comunicazione opaco. Il runtime passa questo contesto DXGI al driver. Il driver deve copiare questo contesto DXGI invariato nel membro pDXGIContext della struttura DXGIDDICB_PRESENT quando il driver chiama la funzione pfnPresentCbDXGI .

Il driver deve inviare tutti i dati di rendering parzialmente compilati (buffer dei comandi) usando la funzione pfnRenderCb . Successivamente, il driver deve convertire i parametri dell'handle di risorsa in handle del kernel e usare tali handle del kernel in una chiamata a pfnPresentCbDXGI.

Nota

Quando la funzione PresentDXGI del driver copia il contenuto formattato sRGB da una superficie di origine a una superficie di destinazione non sRGB, il driver deve copiare il contenuto sRGB invariato, ovvero il driver non deve eseguire la conversione lineare sRGB.

pPresentData

[in] Puntatore a una struttura DXGI_DDI_ARG_PRESENT che descrive come visualizzare la superficie di destinazione.

pfnGetGammaCaps

La funzione GetGammaCapsDXGI recupera le funzionalità gamma.

pGammaData

[in] Puntatore a una struttura DXGI_DDI_ARG_GET_GAMMA_CONTROL_CAPS che contiene funzionalità gamma.

pfnSetDisplayMode

Puntatore alla funzione SetDisplayModeDXGI del driver.

pfnSetResourcePriority

La funzione SetResourcePriorityDXGI imposta la priorità di rimozione dalla memoria per una risorsa.

Il runtime Di Microsoft Direct3D chiama SetResourcePriorityDXGI per impostare il livello di priorità per una risorsa. Il driver di visualizzazione in modalità utente deve convertire l'handle di risorsa fornito nel membro hResource della struttura DXGI_DDI_ARG_SETRESOURCEPRIORITY a cui punta pPriorityData a un handle di allocazione. Dopo che il driver esegue questa conversione, il driver deve passare l'handle risultante in una chiamata alla funzione pfnSetPriorityCb .

pPriorityData

[in] Puntatore a una struttura DXGI_DDI_ARG_SETRESOURCEPRIORITY che descrive il livello di priorità su cui impostare una risorsa.

pfnQueryResourceResidency

Questa funzione determina la residenza dell'elenco specificato di risorse.

Il runtime di Microsoft Direct3D chiama la funzione QueryResourceResidencyDXGI del driver di visualizzazione in modalità utente per le applicazioni per determinare se il sistema operativo incorrerà in un blocco significativo in fase di disegno se il sistema deve rendere accessibili le risorse gpu. Le informazioni restituite da QueryResourceResidencyDXGI sono un'approssimazione della residenza delle risorse perché le risorse potrebbero essere abbassate di livello prima che le applicazioni usino le risorse.

QueryResourceResidencyDXGI deve chiamare la funzione pfnQueryResidencyCb . pfnQueryResidencyCb restituisce lo stato di residenza di una risorsa negli elementi della matrice specificata dal membro pResidencyStatus della struttura D3DDDICB_QUERYRESIDENCY . Se pfnQueryResidencyCb restituisce D3DDDI_RESIDENCYSTATUS_NOTRESIDENT per qualsiasi query, QueryResourceResidencyDXGI deve restituire S_NOT_RESIDENT. Se pfnQueryResidencyCb restituisce D3DDDI_RESIDENCYSTATUS_RESIDENTINSHAREDMEMORY per qualsiasi query e non restituisce D3DDDI_RESIDENCYSTATUS_NOTRESIDENT per alcuna query, QueryResourceResidencyDXGI deve restituire S_RESIDENT_IN_SHARED_MEMORY. QueryResourceResidencyDXGI deve restituire S_OK solo se tutte le chiamate a pfnQueryResidencyCb per tutte le query restituiscono D3DDDI_RESIDENCYSTATUS_RESIDENTINGPUMEMORY.

Per ogni risorsa eseguita dalla query di runtime tramite una chiamata a QueryResourceResidencyDXGI, il driver di visualizzazione in modalità utente deve determinare quali allocazioni appartengono alla risorsa per eseguire query tramite una chiamata a pfnQueryResidencyCb. Per una risorsa proprietaria di una singola allocazione, la determinazione è semplice. Il driver eseguirà una query sull'allocazione. Tuttavia, se una risorsa possiede più allocazioni, la determinazione è più difficile. Il driver deve determinare le allocazioni che un'applicazione userà probabilmente per il rendering e il driver deve eseguire query solo su tali allocazioni. Ad esempio, se una risorsa possiede un'allocazione usata per il rendering e un'allocazione scratch che gestisce un'operazione di blocco, il driver deve eseguire una query solo per la residenza della prima allocazione, perché un'applicazione probabilmente non userà la seconda allocazione per il rendering.

Nota

Poiché il runtime non supporta l'esecuzione di query di residenza delle risorse di memoria di sistema, il runtime non riuscirà sempre a eseguire richieste dalle applicazioni per lo stato di residenza delle risorse di memoria di sistema e non chiamerà mai la funzione QueryResourceResidencyDXGI del driver in modalità utente per queste risorse di memoria di sistema.

pResidencyData

[in] Puntatore a una struttura DXGI_DDI_ARG_QUERYRESOURCERESIDENCY che descrive un elenco di risorse su cui viene verificata la residenza.

pfnRotateResourceIdentities

Ruota un elenco di risorse.

La funzione RotateResourceIdentitiesDXGI deve scambiare identità della matrice di risorse passate nel membro pResources della struttura DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES a cui punta il parametro pRotateData . Ad esempio, se la matrice di risorse fa riferimento alle risorse X, Y e Z, in ordine di indice di matrice crescente, RotateResourceIdentitiesDXGI deve ruotare tali handle per fare riferimento a Y, Z e X, in ordine di indice di matrice crescente. In particolare, il driver di visualizzazione in modalità utente deve scambiare gli handle del kernel delle risorse corrispondenti. Tuttavia, il driver non deve scambiare gli handle di runtime (RT) corrispondenti. Il runtime chiama RotateResourceIdentitiesDXGI per ruotare i buffer indietro durante la presentazione. Di conseguenza, una chiamata a RotateResourceIdentitiesDXGI non è frequente. Il runtime può specificare il flag D3D10_DDI_BIND_PRESENT nel membro BindFlags della struttura D3D10DDIARG_CREATERESOURCE quando il runtime chiama la funzione CreateResource(D3D10) del driver per indicare che la risorsa può partecipare a un'operazione di rotazione.

Il driver di visualizzazione in modalità utente deve anche gestire altri aspetti dello scambio di identità. Ad esempio, in Direct3D versione 10, le visualizzazioni possono fare riferimento alle risorse; e tali visualizzazioni possono avere indirizzi di risorsa incorporati. Pertanto, il driver deve ricreare tali visualizzazioni. Inoltre, il driver potrebbe essere necessario per riapplicare le visualizzazioni attualmente associate.

A partire da Windows 8, il driver deve supportare la rotazione dei buffer back stereo.

pRotateData

[in] Puntatore a una struttura DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES che descrive un elenco di risorse da ruotare.

pfnBlt

Copia il contenuto di una superficie di origine in una superficie di destinazione e può ruotare il contenuto.

Il runtime Direct3D potrebbe impostare il membro Flags della struttura DXGI_DDI_ARG_BLT a cui punta il parametro pBltData in modo da richiedere alla funzione BltDXGI di eseguire un'operazione di trasferimento a blocchi di bit (bitblt) che risolve le risorse a più campioni, esegue la conversione in formato colore ed esegue un'estensione o compattazione contemporaneamente. Tuttavia, il runtime Direct3D non imposterà mai il membro Flags di DXGI_DDI_ARG_BLT su zero (ovvero nessun flag impostato) insieme al valore DXGI_DDI_MODE_ROTATION_IDENTITY impostato nel membro Rotate di DXGI_DDI_ARG_BLT (ovvero per indicare nessuna rotazione) per eseguire un'operazione di copia della memoria retta. A meno che entrambe le risorse non siano a campionamento multipla, il runtime Direct3D chiama invece la funzione ResourceCopy o ResourceCopyRegion del driver per eseguire un'operazione di copia della memoria diretta.

La qualità dell'estensione o della compattazione eseguita dal driver di visualizzazione in modalità utente deve essere altrettanto efficace dell'estensione o della compattazione eseguita da un filtro bilineare.

Il runtime Direct3D chiamerà raramente la funzione BltDXGI del driver. Ovvero, il runtime deve chiamare BltDXGI non più di una o due volte per fotogramma perché il runtime usa principalmente BltDXGI per supportare una presentazione.

Quando il runtime chiama BltDXGI per una presentazione, il runtime imposta il flag Present bit-field nel membro Flags di DXGI_DDI_ARG_BLT. Il runtime imposta il flag Present bit-field per informare il driver che sono previsti requisiti aggiuntivi per il bitblt e che potrebbe essere necessaria una sincronizzazione aggiuntiva( ad esempio, il runtime potrebbe dover eseguire una sincronizzazione aggiuntiva nelle configurazioni del computer che contengono due schede grafiche che ognuno gestisce parti separate dello schermo). Quando viene impostato il flag Present bit-field ,il driver deve eseguire un'operazione di copia dai buffer back di un'applicazione alla superficie condivisa di DWM. Poiché la sincronizzazione per questo tipo di operazione di copia è inesatta, gli artefatti di rimozione devono essere il tipo peggiore di artefatti che un utente riscontra. Per questo tipo di operazione di copia, il driver non deve usare un approccio a più passaggi risolvendo prima nella superficie di destinazione e quindi convertendo i risultati sul posto perché gli artefatti possibili sarebbero molto peggiori.

Se il driver supporta la restituzione di DXGI_DDI_ERR_UNSUPPORTED durante la creazione di una superficie primaria ( ovvero, restituendo DXGI_DDI_ERR_UNSUPPORTED da una chiamata alla relativa funzione CreateResource(D3D10) con il flag D3D10_DDI_BIND_PRESENT impostato nel membro BindFlags di D3D10DDIARG_CREATERESOURCE insieme al membro pPrimaryDesc di D3D10DDIARG_CREATERESOURCE impostato su non NULL), il driver deve supportare anche la rotazione durante un'operazione di copia. Se il driver non restituisce mai DXGI_DDI_ERR_UNSUPPORTED da una chiamata alla relativa funzione CreateResource(D3D10), il runtime non passerà mai il valore DXGI_DDI_MODE_ROTATION_ROTATE90, DXGI_DDI_MODE_ROTATION_ROTATE180 o DXGI_DDI_MODE_ROTATION_ROTATE270 al membro Rotate di DXGI_DDI_ARG_BLT. Pertanto, in questa situazione, la funzione BltDXGI del driver non è necessaria per supportare la rotazione.

Il runtime imposta un valore nel membro Rotate di DXGI_DDI_ARG_BLT per indicare il numero di gradi per ruotare in senso antiorario il contenuto dell'origine prima che il driver copia il contenuto nella destinazione. La rotazione viene specificata in incrementi di 90 gradi.

Nota

Quando la funzione BltDXGI del driver copia il contenuto formattato sRGB da una superficie di origine a una superficie di destinazione non sRGB, il driver deve copiare il contenuto sRGB invariato, ovvero il driver non deve eseguire sRGB per la conversione lineare.

Restrizioni di origine

La funzione BltDXGI usa sempre un'intera sottorisorsa di origine (rispetto a un'area secondaria) per eseguire l'operazione bitblt. Inoltre, l'origine è una rappresentazione D3D10DDIRESOURCE_TEXTURE2D (specificata nel membro ResourceDimension di D3D10DDIARG_CREATERESOURCE quando l'origine viene creata in una chiamata alla funzione CreateResource(D3D10) del driver di visualizzazione in modalità utente. Quando il runtime imposta il campo di bit Resolve nel membro Flags di DXGI_DDI_ARG_BLT, l'origine è una risorsa multicampo. La risorsa di origine è limitata a una risorsa in cui è stato impostato il flag D3D10_DDI_BIND_PRESENT nel membro BindFlags di D3D10DDIARG_CREATERESOURCE. Il formato dell'origine (specificato nel membro Format di D3D10DDIARG_CREATERESOURCE) è limitato ai formati di modalità di visualizzazione, specificati dai valori seguenti dell'enumerazione DXGI_FORMAT :

DXGI_FORMAT_B5G6R5_UNORM
DXGI_FORMAT_B5G5R5A1_UNORM
DXGI_FORMAT_B8G8R8A8_UNORM (vedere la nota riportata di seguito).
DXGI_FORMAT_B8G8R8X8_UNORM
DXGI_FORMAT_R16G16B16A16_FLOAT
DXGI_FORMAT_R10G10B10A2_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM_SRGB

Nota

Se il driver supporta il formato di origine DXGI_FORMAT_B8G8R8A8_UNORM, si applicano le restrizioni seguenti:

Quando il driver esegue un'operazione bitblt da un formato a virgola mobile a un formato intero, ad esempio BGRA8888, deve codificare implicitamente gamma nei risultati.
Al contrario, quando il driver esegue un'operazione bitblt da un formato intero a un formato a virgola mobile, deve rimuovere implicitamente la codifica gamma dai risultati.

Restrizioni di destinazione

La destinazione è anche una rappresentazione D3D10DDIRESOURCE_TEXTURE2D . Il formato della destinazione è limitato anche ai formati di modalità di visualizzazione. La risorsa di destinazione è limitata a una risorsa associata come destinazione di rendering (D3D10_DDI_BIND_RENDER_TARGET impostata nel membro BindFlags di D3D10DDIARG_CREATERESOURCE o D3D11DDIARG_CREATERESOURCE).

Creazione di un buffer back stereo

A partire da Windows 8, se il driver deve creare un buffer back stereo, deve impostare i membri della D3D10DDIARG_CREATERESOURCE o della struttura di D3D11DDIARG_CREATERESOURCE, rispettivamente, puntando al parametro pCreateResource del parametro CreateResource(D3D10) o CreateResource(D3D11), come indicato di seguito:

Impostare il membro ArraySize su un valore pari a 2.
Impostare il valore del flag D3D10_DDI_BIND_PRESENT nel membro BindFlags .

Inoltre, per supportare la presentazione stereo, la funzione BltDXGI deve consentire tutti i valori per i membri DstSubresource e SrcSubresource della struttura DXGI_DDI_ARG_BLT che si trovano all'interno dell'intervallo delle risorse di origine e di destinazione.