DXGKDDI_PRESENT funzione di callback (d3dkmddi.h)

Articolo
02/25/2024

La funzione DxgkDdiPresent copia il contenuto dalle allocazioni di origine a una superficie primaria (e talvolta alle allocazioni di memoria del sistema fuori schermo).

Sintassi

DXGKDDI_PRESENT DxgkddiPresent;

NTSTATUS DxgkddiPresent(
  [in]     IN_CONST_HANDLE hContext,
  [in/out] INOUT_PDXGKARG_PRESENT pPresent
)
{...}

Parametri

[in] hContext

Handle per il contesto del dispositivo per le informazioni di copia. La funzione DxgkDdiCreateContext del driver miniport di visualizzazione ha restituito in precedenza questo handle nel membro hContext della struttura DXGKARG_CREATECONTEXT a cui punta il parametro pCreateContext di DxgkDdiCreateContext .

Se il driver non supporta la creazione del contesto, il sottosistema kernel della grafica Microsoft DirectX sostituisce l'handle nel contesto con un handle per il dispositivo. La funzione DxgkDdiCreateDevice del driver miniport di visualizzazione ha restituito in precedenza l'handle del dispositivo nel membro hDevice della struttura DXGKARG_CREATEDEVICE a cui punta il parametro pCreateDevice di DxgkDdiCreateDevice .

[in/out] pPresent

Puntatore a una struttura DXGKARG_PRESENT contenente informazioni sull'operazione di copia.

Valore restituito

DxgkDdiPresent restituisce uno dei valori seguenti:

Codice restituito	Descrizione
STATUS_SUCCESS	DxgkDdiPresent ha copiato correttamente il contenuto.
STATUS_NO_MEMORY o STATUS_INSUFFICIENT_RESOURCES	DxgkDdiPresent non è riuscito ad allocare memoria necessaria per il completamento.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	Il buffer DMA (Direct Memory Access) corrente è esaurito.
STATUS_GRAPHICS_CANNOTCOLORCONVERT	Il driver miniport di visualizzazione ha rilevato un trasferimento bit-block (bitblt) per la conversione dei colori che il dispositivo non è riuscito a eseguire. Il runtime Di Microsoft Direct3D impedisce l'esecuzione dell'applicazione e l'applicazione riceve un errore di copia del contenuto.
STATUS_PRIVILEGED_INSTRUCTION	DxgkDdiPresent ha rilevato istruzioni non privilegiate, ovvero istruzioni che accedono alla memoria oltre il privilegio del processo di elaborazione centrale corrente [CPU].
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiPresent ha rilevato istruzioni che l'hardware grafico non può supportare.
STATUS_INVALID_HANDLE	DxgkDdiPresent ha rilevato un handle non valido nel buffer dei comandi.
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	Il driver miniport di visualizzazione ha rilevato un errore nel flusso DMA. Il dispositivo del contesto grafico viene inserito in uno stato perso se il driver restituisce questo codice di errore.

Commenti

Il sottosistema kernel grafico DirectX chiama la funzione DxgkDdiPresent del driver miniport di visualizzazione per copiare il contenuto dalle allocazioni di origine in genere alla superficie primaria. Questa funzione può anche copiare il contenuto in un'allocazione di memoria di sistema fuori schermo. Poiché una superficie primaria è definita in modo debole, DxgkDdiPresent può essere implementata per gli scenari seguenti:

A seconda della posizione della finestra, la funzione DxgkDdiPresent deve essere eseguita in primarie diverse che possono trovarsi nella stessa scheda o in schede diverse.
Il database primario si trova in un monitoraggio remoto ed è accessibile tramite un client di servizi terminal o Microsoft NetMeeting.
Si è verificato di recente un cambio di modalità e il formato principale è diverso dal formato di origine, quindi è necessaria una conversione del colore. Inoltre, l'operazione DxgkDdiPresent può essere ritagliata a causa del ritaglio e dell'ordinamento delle finestre.

Poiché gli scenari precedenti possono cambiare in modo asincrono, il driver di visualizzazione in modalità utente non può compilare istruzioni hardware per la funzione DxgkDdiPresent del driver miniport di visualizzazione in anticipo. Il driver miniport di visualizzazione deve creare comandi hardware per l'operazione DxgkDdiPresent effettiva e devono essere inseriti in un buffer DMA di output. Dopo la chiamata della funzione DxgkDdiPresent del driver miniport di visualizzazione per generare il buffer DMA, il sistema operativo garantisce che una modifica dello scenario non venga eseguita prima del rendering del buffer.

Il driver miniport di visualizzazione non deve essere a conoscenza delle specifiche degli scenari precedenti, purché il driver supporti le astrazioni seguenti:

In un'operazione di copia da un'origine di memoria video a una destinazione di memoria video o di sistema primaria, una copia da un'origine di memoria di sistema fuori schermo alla destinazione primaria, una copia da e verso l'origine primaria o una copia dall'origine primaria a una destinazione di memoria di sistema fuori schermo, l'origine viene specificata dal membro hDeviceSpecificAllocationAllocation dell'elemento matrice pAllocationList[DXGK_PRESENT_SOURCE_INDEX] della struttura DXGKARG_PRESENT della struttura pPresent il parametro di DxgkDdiPresent punta a . La destinazione, che è la replica primaria corrente del dispositivo o un'allocazione di memoria di sistema fuori schermo, viene specificata dal membro hDeviceSpecificAllocation dell'elemento matrice pAllocationList[DXGK_PRESENT_DESTINATION_INDEX] di DXGKARG_PRESENT. Se la destinazione è uguale all'origine (ovvero destinazione == origine), l'operazione di copia è un trasferimento a blocco di bit da schermata a schermo (bitblt). Di conseguenza, il sottosistema grafico imposta l'origine e la destinazione sui valori seguenti:
- destination != NULL (ovvero destinazione == nonNULL)
- source != NULL (ovvero source == nonNULL)
In una memoria video passare dall'allocazione corrente a un'altra allocazione, l'origine può essere specificata dal sistema operativo e impostata nel membro hDeviceSpecificAllocation dell'elemento matrice pAllocationList[DXGK_PRESENT_SOURCE_INDEX] di DXGKARG_PRESENT. Il sottosistema grafico imposta l'origine e la destinazione sui valori seguenti:
- destination == NULL
- source != NULL (ovvero source == nonNULL)
Nota Un capovolgimento no-op può essere eseguito dalla stessa allocazione di origine dell'allocazione attualmente analizzata. Un capovolgimento no-op viene usato per inserire un'attesa in coda per un vuoto verticale nel flusso di rendering. Il driver miniport di visualizzazione deve inserire un comando di scorrimento hardware come se fosse stato capovolto a un'altra allocazione.
In un'operazione di riempimento a colori sulla superficie primaria non è necessaria alcuna allocazione di origine e la destinazione è un handle di allocazione primario specificato dal membro hDeviceSpecificAllocation dell'elemento matrice pAllocationList[DXGK_PRESENT_DESTINATION_INDEX] di DXGKARG_PRESENT. Il membro Color di DXGKARG_PRESENT è in genere nel formato D3DDDIFMT_A8R8G8B8 dal tipo di enumerazione D3DDDIFORMAT . Tuttavia, quando il formato primario è pallido RGB, Color contiene l'indice della tavolozza. Di conseguenza, il sottosistema grafico imposta l'origine e la destinazione sui valori seguenti:
- destination != NULL (ovvero destinazione == nonNULL)
- source == NULL

Per il corretto funzionamento di tutti gli scenari DxgkDdiPresent , la funzione DxgkDdiCreateDevice del driver miniport di visualizzazione deve impostare il membro DmaBufferSize della struttura DXGK_DEVICEINFO per contenere i comandi hardware necessari per presentare almeno un rettangolo RECT alla destinazione dello schermo o fuori schermo. Tuttavia, la funzione DxgkDdiPresent del driver può restituire STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER se il numero di sottorestri nello scenario DxgkDdiPresent esaurisce il buffer DMA corrente e il driver richiede un altro buffer DMA per continuare.

Il sottosistema grafico acquisisce quindi un nuovo buffer DMA e chiama di nuovo la funzione DxgkDdiPresent del driver con lo stesso elenco di strutture RECT della precedente chiamata DxgkDdiPresent . Il driver deve usare il membro MultipassOffset della struttura DXGKARG_PRESENT a cui punta pPresent per registrare la quantità di avanzamento apportata nel completamento dell'elenco RECT nella chiamata precedente a DxgkDdiPresent in modo che il driver possa continuare da dove si è arrestato con il nuovo buffer DMA. Quando la funzione DxgkDdiPresent del driver completa l'elenco delle strutture RECT, restituisce STATUS_SUCCESS.

Oltre a generare un buffer DMA, il driver miniport di visualizzazione deve generare un elenco di percorsi patch che indica i vari offset all'interno del buffer DMA che devono essere patchati in un secondo momento quando sono noti indirizzi fisici per le allocazioni. A volte, gestione memoria video fornisce al driver informazioni pre-patch (ovvero gli ultimi indirizzi fisici noti per l'origine e la destinazione) nell'elenco di allocazione.

Quando la gestione memoria video fornisce queste informazioni, il driver deve generare il buffer DMA determinando che questi indirizzi fisici sono gli indirizzi finali forniti dal sottosistema kernel grafico DirectX. Il sottosistema grafico potrebbe non chiamare la funzione DxgkDdiPatch nel buffer DMA per applicare nuovamente patch in un secondo momento. Pertanto, il driver deve usare le informazioni di pre-patch per generare correttamente il buffer DMA. Le informazioni pre-patch vengono fornite per l'elemento N quando il membro SegmentIddell'elemento Ndella matrice pAllocationList di DXGKARG_PRESENT è diverso da zero.

Nota Anche se la funzione DxgkDdiPresent del driver pre-patch il buffer DMA, il driver deve comunque inserire tutti i riferimenti alle allocazioni nell'elenco di percorsi patch di output specificato dal membro pPatchLocationListOut di DXGKARG_PRESENT . Il driver deve inserire questi riferimenti perché gli indirizzi delle allocazioni potrebbero cambiare prima che il buffer DMA venga inviato alla GPU; pertanto, il sottosistema del kernel grafico DirectX chiamerà la funzione DxgkDdiPatch per eseguire il repository del buffer DMA.

Se il driver supporta la rotazione , ovvero segnala il supporto per le modalità ruotate nel membro RotationSupport della struttura di D3DKMDT_VIDPN_PRESENT_PATH_TRANSFORMATION in una chiamata alla relativa funzione DxgkDdiEnumVidPnCofuncModality , il driver deve essere in grado di eseguire trasferimenti di blocchi di bit ruotati (bitblt) da origine a destinazione. Quando il flag di campo di bit Rotate viene specificato nella struttura DXGK_PRESENTFLAGS per il membro Flags di DXGKARG_PRESENT, il driver deve applicare la rotazione come se passasse da una superficie non ruotata all'orientamento finale dell'origine corrente.

L'allocazione primaria di un'origine viene specificata nella funzione DxgkDdiCommitVidPn . Se più percorsi provengono dall'origine specificata (modalità clone), il driver miniport di visualizzazione deve assicurarsi che gli output vengano ruotati correttamente in base alla modalità di rotazione del percorso per le diverse destinazioni. Tutti i parametri forniti a DxgkDdiPresent sono indipendenti dalla rotazione. I rettangoli di origine e di destinazione possono essere entrambi l'intero schermo mentre i client lo percepiscono (ad esempio, 768 x 1024).

Nota Questa situazione non riguarda le applicazioni Direct3D a schermo intero in modalità ruotata.

Se il driver miniport visualizzato indicato in precedenza, in una chiamata alla relativa funzione DxgkDdiQueryAdapterInfo , che supporta un capovolgimento basato su I/O mappato alla memoria (MMIO) (impostando il flag di campo di bit FlipOnVSyncMmIo nel membro FlipCaps della struttura DXGK_DRIVERCAPS su TRUE), la funzione DxgkDdiPresent del driver viene successivamente chiamata con il membro pDmaBuffer di DXGKARG_PRESENT impostato su NULL poiché un capovolgimento basato su MMIO non richiede l'esecuzione di un buffer DMA sulla GPU. Al contrario, la funzione DxgkDdiPresent del driver deve convalidare l'hardware di scorrimento della superficie di origine e del programma in base alle esigenze. Il sottosistema kernel della grafica DirectX chiama la funzione DxgkDdiSetVidSourceAddress del driver per eseguire questo tipo di flip.

DxgkDdiPresent deve essere reso pageable.