DXGKDDI_PRESENT fonction de rappel (d3dkmddi.h)

Article
05/26/2023

La fonction DxgkDdiPresent copie le contenu des allocations sources vers une surface primaire (et parfois vers des allocations de mémoire système hors écran).

Syntaxe

DXGKDDI_PRESENT DxgkddiPresent;

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

Paramètres

[in] hContext

Handle dans le contexte de l’appareil pour les informations de copie. La fonction DxgkDdiCreateContext du pilote miniport d’affichage a précédemment retourné ce handle dans le membre hContext de la structure DXGKARG_CREATECONTEXT vers laquelle pointe le paramètre pCreateContext de DxgkDdiCreateContext .

Si le pilote ne prend pas en charge la création de contexte, le sous-système du noyau graphique Microsoft DirectX remplace le handle du contexte par un handle pour l’appareil. La fonction DxgkDdiCreateDevice du pilote miniport d’affichage a précédemment retourné le handle d’appareil dans le membre hDevice de la structure DXGKARG_CREATEDEVICE vers laquelle pointe le paramètre pCreateDevice de DxgkDdiCreateDevice .

[in/out] pPresent

Pointeur vers une structure de DXGKARG_PRESENT qui contient des informations sur l’opération de copie.

Valeur retournée

DxgkDdiPresent retourne l’une des valeurs suivantes :

Code de retour	Description
STATUS_SUCCESS	DxgkDdiPresent a correctement copié le contenu.
STATUS_NO_MEMORY ou STATUS_INSUFFICIENT_RESOURCES	DxgkDdiPresent n’a pas pu allouer la mémoire nécessaire à sa fin.
STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER	La mémoire tampon d’accès direct à la mémoire (DMA) actuelle est épuisée.
STATUS_GRAPHICS_CANNOTCOLORCONVERT	Le pilote de miniport d’affichage a détecté un transfert de bloc de bits (bitblt) pour la conversion de couleur que l’appareil n’a pas pu effectuer. Le runtime Microsoft Direct3D empêche l’application de continuer et l’application reçoit un échec de copie du contenu.
STATUS_PRIVILEGED_INSTRUCTION	DxgkDdiPresent a détecté des instructions non privilégiées (c’est-à-dire des instructions qui accèdent à la mémoire au-delà du privilège du processus actuel de l’unité de traitement centrale [UC] ).
STATUS_ILLEGAL_INSTRUCTION	DxgkDdiPresent a détecté des instructions que le matériel graphique ne peut pas prendre en charge.
STATUS_INVALID_HANDLE	DxgkDdiPresent a détecté un handle non valide dans la mémoire tampon de commande.
STATUS_GRAPHICS_GPU_EXCEPTION_ON_DEVICE	Le pilote de miniport d’affichage a détecté une erreur dans le flux DMA. Le périphérique de contexte graphique est placé dans un état perdu si le pilote retourne ce code d’erreur.

Remarques

Le sous-système du noyau graphique DirectX appelle la fonction DxgkDdiPresent du pilote miniport d’affichage pour copier le contenu des allocations sources vers la surface primaire. (Cette fonction peut également copier du contenu dans une allocation de mémoire système hors écran.) Étant donné qu’une surface primaire est définie de manière vague, DxgkDdiPresent peut être implémenté dans les scénarios suivants :

Selon la position de la fenêtre, la fonction DxgkDdiPresent doit être exécutée sur différentes primaires qui peuvent se trouver sur le même adaptateur ou sur différentes cartes.
Le principal se trouve sur un moniteur distant et est accessible via un client de services terminal ou Microsoft NetMeeting.
Un changement de mode s’est récemment produit et le format principal est différent du format source. Une conversion de couleur est donc nécessaire. En outre, l’opération DxgkDdiPresent peut être clippée en raison du découpage et de l’ordre de la fenêtre.

Étant donné que les scénarios précédents peuvent changer de manière asynchrone, le pilote d’affichage en mode utilisateur ne peut pas compiler à l’avance les instructions matérielles pour la fonction DxgkDdiPresent du pilote miniport d’affichage. Le pilote miniport d’affichage doit créer des commandes matérielles pour l’opération DxgkDdiPresent réelle, et elles doivent être placées dans une mémoire tampon DMA de sortie. Une fois que la fonction DxgkDdiPresent du pilote d’affichage est appelée pour générer la mémoire tampon DMA, le système d’exploitation garantit qu’aucune modification de scénario ne se produira avant que cette mémoire tampon ne soit rendue.

Le pilote de miniport d’affichage n’est pas nécessaire pour connaître les spécificités des scénarios précédents tant que le pilote prend en charge les abstractions suivantes :

Dans une opération de copie d’une source de mémoire vidéo vers une destination de mémoire système ou vidéo principale, une copie d’une source de mémoire système hors écran vers la destination principale, une copie de et vers la source principale ou une copie de la source primaire vers une destination de mémoire système hors écran, la source est spécifiée par le membre hDeviceSpecificAllocation de l’élément de tableau pAllocationList[DXGK_PRESENT_SOURCE_INDEX] de la structure DXGKARG_PRESENT que le pPresentent paramètre de DxgkDdiPresent pointe vers. La destination, qui est le principal actuel de l’appareil ou une allocation de mémoire système hors écran, est spécifiée par le membre hDeviceSpecificAllocation de l’élément de tableau pAllocationList[DXGK_PRESENT_DESTINATION_INDEX] de DXGKARG_PRESENT. Si la destination est égale à la source (c’est-à-dire, destination == source), l’opération de copie est un transfert de bloc de bits d’écran à écran (bitblt). Par conséquent, le sous-système graphique définit la source et la destination sur les valeurs suivantes :
- destination != NULL (autrement dit, destination == nonNULL)
- source != NULL (autrement dit, source == nonNULL)
Dans un basculement de la mémoire vidéo de l’allocation actuelle vers une autre allocation, la source peut être spécifiée par le système d’exploitation et définie dans le membre hDeviceSpecificAllocation de l’élément de tableau pAllocationList[DXGK_PRESENT_SOURCE_INDEX] de DXGKARG_PRESENT. Le sous-système graphique définit la source et la destination sur les valeurs suivantes :
- destination == NULL
- source != NULL (autrement dit, source == nonNULL)
Note Un basculement sans opération peut être effectué à partir de la même allocation source que l’allocation actuellement analysée. Un basculement sans opération est utilisé pour insérer une attente en file d’attente pour un vide vertical dans le flux de rendu. Le pilote de miniport d’affichage doit insérer une commande de basculement matérielle comme s’il s’agissait d’un basculement vers une autre allocation.
Dans une opération de remplissage de couleur sur la surface primaire, aucune allocation source n’est requise et la destination est un handle d’allocation primaire spécifié par le membre hDeviceSpecificAllocation de l’élément de tableau pAllocationList[DXGK_PRESENT_DESTINATION_INDEX] de DXGKARG_PRESENT. Le membre Color de DXGKARG_PRESENT est généralement au format D3DDDIFMT_A8R8G8B8 du type d’énumération D3DDDIFORMAT . Toutefois, lorsque le format principal est RVB palettisé, Color contient l’index de palette. Par conséquent, le sous-système graphique définit la source et la destination sur les valeurs suivantes :
- destination != NULL (autrement dit, destination == nonNULL)
- source == NULL

Pour que tous les scénarios DxgkDdiPresent fonctionnent correctement, la fonction DxgkDdiCreateDevice du pilote miniport doit définir le membre DmaBufferSize de la structure DXGK_DEVICEINFO suffisamment grande pour contenir les commandes matérielles nécessaires pour présenter au moins un rectangle RECT à la cible d’affichage ou hors écran. Toutefois, la fonction DxgkDdiPresent du pilote peut retourner STATUS_GRAPHICS_INSUFFICIENT_DMA_BUFFER si le nombre de sous-corrections dans le scénario DxgkDdiPresent épuise la mémoire tampon DMA actuelle et que le pilote nécessite une autre mémoire tampon DMA pour continuer.

Le sous-système graphique acquiert ensuite une nouvelle mémoire tampon DMA et appelle à nouveau la fonction DxgkDdiPresent du pilote avec la même liste de structures RECT que l’appel DxgkDdiPresent précédent. Le pilote doit utiliser le membre MultipassOffset de la structure DXGKARG_PRESENT pointée par pPresent pour enregistrer la progression de l’exécution de la liste RECT dans l’appel précédent à DxgkDdiPresent afin que le pilote puisse continuer à partir de l’endroit où il s’est arrêté avec la nouvelle mémoire tampon DMA. Lorsque la fonction DxgkDdiPresent du pilote termine la liste des structures RECT, elle retourne STATUS_SUCCESS.

En plus de générer une mémoire tampon DMA, le pilote miniport d’affichage doit générer une liste d’emplacements de correctif qui indique les différents décalages dans la mémoire tampon DMA qui doivent être corrigés ultérieurement lorsque les adresses physiques pour les allocations sont connues. Parfois, le gestionnaire de mémoire vidéo fournit au pilote des informations pré-corrigées (c’est-à-dire les dernières adresses physiques de la source et de la destination) dans la liste d’allocation.

Lorsque le gestionnaire de mémoire vidéo fournit ces informations, le pilote doit générer la mémoire tampon DMA en déterminant que ces adresses physiques sont les adresses finales fournies par le sous-système du noyau graphique DirectX. Le sous-système graphique n’appelle peut-être pas la fonction DxgkDdiPatch sur la mémoire tampon DMA pour la corriger ultérieurement. Par conséquent, le pilote doit utiliser les informations préalables au correctif pour générer correctement la mémoire tampon DMA. Des informations pré-corrigées sont fournies pour l’élément N lorsque le membre SegmentId du Nième élément du tableau pAllocationList de DXGKARG_PRESENT est différent de zéro.

Note Même si la fonction DxgkDdiPresent du pilote pré-patche la mémoire tampon DMA, le pilote doit toujours insérer toutes les références aux allocations dans la liste d’emplacement des correctifs de sortie que le membre pPatchLocationListOut de DXGKARG_PRESENT spécifie. Le pilote doit insérer ces références, car les adresses des allocations peuvent changer avant que la mémoire tampon DMA ne soit envoyée au GPU ; par conséquent, le sous-système du noyau graphique DirectX appelle la fonction DxgkDdiPatch pour repatchter la mémoire tampon DMA.

Si le pilote prend en charge la rotation (autrement dit, signale la prise en charge des modes pivotés dans le membre RotationSupport de la structure D3DKMDT_VIDPN_PRESENT_PATH_TRANSFORMATION dans un appel à sa fonction DxgkDdiEnumVidPnCofuncModality ), le pilote doit être en mesure d’effectuer des transferts de bloc de bits (bitblt) pivotés de la source à la destination. Lorsque l’indicateur de champ de bits Pivoter est spécifié dans la structure DXGK_PRESENTFLAGS pour le membre Indicateurs de DXGKARG_PRESENT, le pilote doit appliquer la rotation comme s’il allait d’une surface non pivotée à l’orientation finale de la source actuelle.

L’allocation primaire d’une source est spécifiée dans la fonction DxgkDdiCommitVidPn . Si plusieurs chemins proviennent de la source donnée (mode clone), le pilote miniport d’affichage doit s’assurer que les sorties sont correctement pivotées en fonction du mode de rotation du chemin pour les différentes cibles. Tous les paramètres fournis à DxgkDdiPresent sont indépendants de la rotation. Les rectangles source et cible peuvent être l’intégralité de l’écran que les clients perçoivent (par exemple, 768 x 1024).

Note Cette situation ne traite pas les applications Direct3D plein écran en mode pivoté.

Si le pilote miniport d’affichage a précédemment indiqué, lors d’un appel à sa fonction DxgkDdiQueryAdapterInfo, qu’il prend en charge un flip basé sur les E/S mappées (MMIO) mappée (en définissant l’indicateur de champ de bits FlipOnVSyncMmIo dans le membre FlipCaps de la structure DXGK_DRIVERCAPS), la fonction DxgkDdiPresent du pilote est ensuite appelée avec le membre pDmaBuffer de DXGKARG_PRESENT défini sur NULL car un flip basé sur MMIO ne nécessite pas de mémoire tampon DMA pour s’exécuter sur le GPU. Au lieu de cela, la fonction DxgkDdiPresent du pilote doit valider la surface source et programmer le matériel de retournement selon les besoins. Le sous-système du noyau graphique DirectX appelle la fonction DxgkDdiSetVidPnSourceAddress du pilote pour exécuter ce type de flip.

DxgkDdiPresent doit être rendu paginable.