DXGI_DDI_BASE_FUNCTIONS structure (dxgiddi.h)

Article
08/07/2023

La structure DXGI_DDI_BASE_FUNCTIONS contient des fonctions que le pilote d’affichage en mode utilisateur peut implémenter pour effectuer des tâches de bas niveau, telles que la présentation d’images rendues dans une sortie, le contrôle gamma et la gestion d’une transition plein écran.

Syntaxe

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;

Membres

pfnPresent

Pointeur vers la fonction PresentDXGI qui avertit le pilote d’affichage en mode utilisateur qu’une application a terminé le rendu et demande que le pilote s’affiche sur la surface de destination.

Le membre hDevice de la structure DXGI_DDI_ARG_PRESENT vers laquelle pointe le paramètre pPresentData est le même handle que celui que la fonction CreateDevice(D3D10) du pilote a transmis au runtime dans le membre hDrvDevice de la structure D3D10DDIARG_CREATEDEVICE . Par conséquent, les enregistreurs de pilotes doivent définir soigneusement le type de ce handle. En outre, les pilotes peuvent fournir différentes implémentations de la fonction PresentDXGI en fonction de laquelle l’implémentation DDI a géré l’appel à CreateDevice(D3D10). Le runtime ne combine jamais les handles de pilote entre les implémentations DDI. De même, les membres hSurfaceToPresent et hDstResource de DXGI_DDI_ARG_PRESENT sont également des handles de ressources définis par le pilote que le pilote a retournés au runtime lors des appels précédents à la fonction CreateResource(D3D10) du pilote.

Le membre pDXGIContext de DXGI_DDI_ARG_PRESENT est un mécanisme de communication opaque. Le runtime transmet ce contexte DXGI au pilote. Le pilote doit copier ce contexte DXGI inchangé dans le membre pDXGIContext de la structure DXGIDDICB_PRESENT lorsque le pilote appelle la fonction pfnPresentCbDXGI .

Le pilote doit envoyer toutes les données de rendu partiellement générées (mémoires tampons de commande) à l’aide de la fonction pfnRenderCb . Par la suite, le pilote doit traduire les paramètres de handle de ressource en handles de noyau et utiliser ces handles de noyau dans un appel à pfnPresentCbDXGI.

Notes

Lorsque la fonction PresentDXGI du pilote copie le contenu au format sRGB d’une surface source vers une surface de destination non-sRGB, le pilote doit copier le contenu sRGB inchangé (autrement dit, le pilote ne doit pas effectuer la conversion sRVB vers une conversion linéaire).

pPresentData

[in] Pointeur vers une structure de DXGI_DDI_ARG_PRESENT qui décrit comment s’afficher sur la surface de destination.

pfnGetGammaCaps

La fonction GetGammaCapsDXGI récupère les fonctionnalités gamma.

pGammaData

[in] Pointeur vers une structure de DXGI_DDI_ARG_GET_GAMMA_CONTROL_CAPS qui contient des fonctionnalités gamma.

pfnSetDisplayMode

Pointeur vers la fonction SetDisplayModeDXGI du pilote.

pfnSetResourcePriority

La fonction SetResourcePriorityDXGI définit la priorité d’éviction de la mémoire pour une ressource.

Le runtime Microsoft Direct3D appelle SetResourcePriorityDXGI pour définir le niveau de priorité d’une ressource. Le pilote d’affichage en mode utilisateur doit traduire le handle de ressource fourni dans le membre hResource de la structure DXGI_DDI_ARG_SETRESOURCEPRIORITY pointée par pPriorityData en handle d’allocation. Une fois que le pilote a effectué cette traduction, il doit passer le handle résultant dans un appel à la fonction pfnSetPriorityCb .

pPriorityData

[in] Pointeur vers une structure DXGI_DDI_ARG_SETRESOURCEPRIORITY qui décrit le niveau de priorité sur lequel définir une ressource.

pfnQueryResourceResidency

Cette fonction détermine la résidence de la liste de ressources donnée.

Le runtime Microsoft Direct3D appelle la fonction QueryResourceResidencyDXGI du pilote d’affichage en mode utilisateur pour que les applications déterminent si le système d’exploitation entraîne un blocage significatif au moment du tirage si le système doit rendre les ressources accessibles par GPU. Les informations retournées par QueryResourceResidencyDXGI sont une approximation de la résidence des ressources, car les ressources peuvent être rétrogradées avant que les applications n’utilisent les ressources.

QueryResourceResidencyDXGI doit appeler la fonction pfnQueryResidencyCb . pfnQueryResidencyCb retourne le status de résidence d’une ressource dans les éléments du tableau spécifié par le membre pResidencyStatus de la structure D3DDDICB_QUERYRESIDENCY. Si pfnQueryResidencyCb retourne D3DDDI_RESIDENCYSTATUS_NOTRESIDENT pour une requête, QueryResourceResidencyDXGI doit retourner S_NOT_RESIDENT. Si pfnQueryResidencyCb retourne D3DDDI_RESIDENCYSTATUS_RESIDENTINSHAREDMEMORY pour une requête et ne retourne D3DDDI_RESIDENCYSTATUS_NOTRESIDENT pour aucune requête, QueryResourceResidencyDXGI doit retourner S_RESIDENT_IN_SHARED_MEMORY. QueryResourceResidencyDXGI doit retourner S_OK uniquement si tous les appels à pfnQueryResidencyCb pour toutes les requêtes retournent D3DDDI_RESIDENCYSTATUS_RESIDENTINGPUMEMORY.

Pour chaque ressource que le runtime interroge via un appel à QueryResourceResidencyDXGI, le pilote d’affichage en mode utilisateur doit déterminer les allocations qui appartiennent à la ressource à interroger via un appel à pfnQueryResidencyCb. Pour une ressource qui possède une seule allocation, la détermination est simple : le pilote interroge cette allocation. Toutefois, si une ressource possède plusieurs allocations, la détermination est plus difficile. Le pilote doit déterminer les allocations qu’une application utilisera probablement pour le rendu, et le pilote doit interroger uniquement ces allocations. Par exemple, si une ressource possède une allocation utilisée pour le rendu et une allocation de travail qui gère une opération de verrouillage, le pilote doit interroger uniquement la résidence de la première allocation, car une application n’utilisera probablement pas la deuxième allocation pour le rendu.

Notes

Étant donné que le runtime ne prend pas en charge l’interrogation de résidence des ressources de mémoire système, le runtime échoue toujours aux demandes des applications pour le status de résidence des ressources de mémoire système et n’appelle jamais la fonction QueryResourceResidencyDXGI du pilote d’affichage en mode utilisateur pour ces ressources de mémoire système.

pResidencyData

[in] Pointeur vers une structure de DXGI_DDI_ARG_QUERYRESOURCERESIDENCY qui décrit une liste de ressources sur laquelle la résidence est vérifiée.

pfnRotateResourceIdentities

Fait pivoter une liste de ressources.

La fonction RotateResourceIdentitiesDXGI doit échanger des identités du tableau de ressources passées dans le membre pResources de la structure DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES vers laquelle pointe le paramètre pRotateData . Par exemple, si le tableau de ressources fait référence aux ressources X, Y et Z, dans l’ordre d’index du tableau croissant, RotateResourceIdentitiesDXGI doit faire pivoter ces handles pour faire référence à Y, Z et X, dans l’ordre croissant de l’index du tableau. En particulier, le pilote d’affichage en mode utilisateur doit permuter les handles de noyau des ressources correspondantes. Toutefois, le pilote ne doit pas permuter les handles d’exécution (RT) correspondants. Le runtime appelle RotateResourceIdentitiesDXGI pour faire pivoter les mémoires tampons pendant la présentation. Par conséquent, un appel à RotateResourceIdentitiesDXGI est peu fréquent. Le runtime peut spécifier l’indicateur D3D10_DDI_BIND_PRESENT dans le membre BindFlags de la structure D3D10DDIARG_CREATERESOURCE lorsque le runtime appelle la fonction CreateResource(D3D10) du pilote pour indiquer que la ressource peut participer à une opération de rotation.

Le pilote d’affichage en mode utilisateur doit également gérer d’autres aspects de l’échange d’identités. Par exemple, dans Direct3D version 10, les vues peuvent faire référence à des ressources ; et ces vues peuvent avoir des adresses de ressources incorporées. Par conséquent, le pilote doit recréer ces vues. En outre, le pilote peut être amené à réappliquer les vues actuellement liées.

À compter de Windows 8, le pilote doit prendre en charge la rotation des mémoires tampons d’arrière-plan stéréo.

pRotateData

[in] Pointeur vers une structure de DXGI_DDI_ARG_ROTATE_RESOURCE_IDENTITIES qui décrit une liste de ressources à faire pivoter.

pfnBlt

Copie le contenu d’une surface source vers une surface de destination et peut faire pivoter le contenu.

Le runtime Direct3D peut définir le membre Flags de la structure DXGI_DDI_ARG_BLT vers laquelle pointe le paramètre pBltData de manière à exiger que la fonction BltDXGI effectue une opération de transfert de bloc de bits (bitblt) qui résout les ressources échantillonnées à plusieurs échantillons, effectue une conversion au format de couleur et effectue une étirement ou une réduction à la fois. Toutefois, le runtime Direct3D ne définit jamais le membre Flags de DXGI_DDI_ARG_BLT sur zéro (c’est-à-dire, aucun indicateur défini) avec la valeur DXGI_DDI_MODE_ROTATION_IDENTITY définie dans le membre Rotate de DXGI_DDI_ARG_BLT (autrement dit, pour indiquer qu’il n’y a pas de rotation) pour effectuer une opération de copie en mémoire directe. Au lieu de cela, à moins que les deux ressources ne soient échantillonnées à plusieurs, le runtime Direct3D appelle la fonction ResourceCopy ou ResourceCopyRegion du pilote pour effectuer une opération de copie en mémoire directe.

La qualité de l’étirement ou de la réduction effectué par le pilote d’affichage en mode utilisateur doit être aussi bonne que l’étirement ou la réduction qu’effectue un filtre bilinéaire.

Le runtime Direct3D appelle rarement la fonction BltDXGI du pilote. Autrement dit, le runtime ne doit pas appeler BltDXGI plus d’une ou deux fois par image, car le runtime utilise Principalement BltDXGI pour prendre en charge une présentation.

Lorsque le runtime appelle BltDXGI pour une présentation, le runtime définit l’indicateur de champ de bits Présent dans le membre Indicateurs deDXGI_DDI_ARG_BLT. Le runtime définit l’indicateur de champ de bits Présent pour informer le pilote qu’il existe des exigences supplémentaires pour le bitblt et qu’une synchronisation supplémentaire peut être nécessaire (par exemple, le runtime peut avoir besoin d’effectuer une synchronisation supplémentaire dans les configurations d’ordinateur qui contiennent deux cartes graphiques qui gèrent chacune des parties distinctes de l’affichage). Lorsque l’indicateur de champ binaire Présent est défini, le pilote doit effectuer une opération de copie à partir des mémoires tampons arrière d’une application vers la surface partagée du DWM. Étant donné que la synchronisation pour ce type d’opération de copie est inexacte, les artefacts déchirants doivent être le pire type d’artefacts qu’un utilisateur rencontre. Pour ce type d’opération de copie, le pilote ne doit pas utiliser une approche multi-passe en résolvant d’abord dans la surface de destination, puis en convertissant les résultats sur place, car les artefacts possibles seraient bien pires.

Si le pilote prend en charge le retour d’DXGI_DDI_ERR_UNSUPPORTED lors de la création d’une surface primaire (autrement dit, le retour d’DXGI_DDI_ERR_UNSUPPORTED à partir d’un appel à sa fonction CreateResource(D3D10) avec l’indicateur D3D10_DDI_BIND_PRESENT défini dans le membre BindFlags de D3D10DDIARG_CREATERESOURCE avec le membre pPrimaryDesc de D3D10DDIARG_CREATERESOURCE défini sur non NULL), le pilote doit également prendre en charge la rotation pendant une opération de copie. Si le pilote ne retourne jamais DXGI_DDI_ERR_UNSUPPORTED d’un appel à sa fonction CreateResource(D3D10), le runtime ne transmet jamais la valeur DXGI_DDI_MODE_ROTATION_ROTATE90, DXGI_DDI_MODE_ROTATION_ROTATE180 ou DXGI_DDI_MODE_ROTATION_ROTATE270 au membre Rotate de DXGI_DDI_ARG_BLT. Par conséquent, dans ce cas, la fonction BltDXGI du pilote n’est pas nécessaire pour prendre en charge la rotation.

Le runtime définit une valeur dans le membre Rotate de DXGI_DDI_ARG_BLT pour indiquer le nombre de degrés à faire pivoter dans le sens inverse des aiguilles d’une montre le contenu de la source avant que le pilote ne copie le contenu vers la destination. La rotation est spécifiée par incréments de 90 degrés.

Notes

Lorsque la fonction BltDXGI du pilote copie le contenu au format sRGB d’une surface source vers une surface de destination non-sRGB, le pilote doit copier le contenu sRGB inchangé (autrement dit, le pilote ne doit pas effectuer la conversion sRGB vers une conversion linéaire).

Restrictions de la source

La fonction BltDXGI utilise toujours une sous-ressource source entière (par rapport à une zone sous-rectangulaire) pour effectuer l’opération bitblt. En outre, la source est une représentation D3D10DDIRESOURCE_TEXTURE2D (spécifiée dans le membre ResourceDimension de D3D10DDIARG_CREATERESOURCE lorsque la source est créée dans un appel à la fonction CreateResource(D3D10) du pilote d’affichage en mode utilisateur). Lorsque le runtime définit le champ de bits Résoudre dans le membre Flags de DXGI_DDI_ARG_BLT, la source est une ressource à échantillonnage multiple. La ressource source est limitée à une ressource dans laquelle l’indicateur D3D10_DDI_BIND_PRESENT a été défini dans le membre BindFlags de D3D10DDIARG_CREATERESOURCE. Le format de la source (spécifié dans le membre Format de D3D10DDIARG_CREATERESOURCE) est limité aux formats de mode d’affichage, spécifiés par les valeurs suivantes de l’énumération DXGI_FORMAT :

DXGI_FORMAT_B5G6R5_UNORM
DXGI_FORMAT_B5G5R5A1_UNORM
DXGI_FORMAT_B8G8R8A8_UNORM (Voir la remarque ci-dessous).)
DXGI_FORMAT_B8G8R8X8_UNORM
DXGI_FORMAT_R16G16B16A16_FLOAT
DXGI_FORMAT_R10G10B10A2_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM
DXGI_FORMAT_R8G8B8A8_UNORM_SRGB

Notes

Si le pilote prend en charge le format source DXGI_FORMAT_B8G8R8A8_UNORM, les restrictions suivantes s’appliquent :

Lorsque le pilote effectue une opération bitblt d’un format à virgule flottante vers un format entier tel que BGRA8888, il doit encoder implicitement gamma dans les résultats.
À l’inverse, lorsque le pilote effectue une opération bitblt d’un format entier vers un format à virgule flottante, il doit supprimer implicitement l’encodage gamma des résultats.

Restrictions de destination

La destination est également une représentation D3D10DDIRESOURCE_TEXTURE2D . Le format de la destination est également limité aux formats de mode d’affichage. La ressource de destination est limitée à une ressource liée en tant que cible de rendu (D3D10_DDI_BIND_RENDER_TARGET définie dans le membre BindFlags de D3D10DDIARG_CREATERESOURCE ou D3D11DDIARG_CREATERESOURCE).

Création d’une mémoire tampon d’arrière stéréo

À compter de Windows 8, si le pilote doit créer une mémoire tampon d’arrière stéréo, il doit définir les membres de la structure D3D10DDIARG_CREATERESOURCE ou D3D11DDIARG_CREATERESOURCE, respectivement, pointés vers le paramètre pCreateResource des fonctions CreateResource(D3D10) ou CreateResource(D3D11), comme suit :

Définissez le membre ArraySize sur la valeur 2.
Définissez la valeur d’indicateur D3D10_DDI_BIND_PRESENT dans le membre BindFlags .

En outre, pour prendre en charge la présentation stéréo, la fonction BltDXGI doit autoriser toutes les valeurs pour les membres DstSubresource et SrcSubresource de la structure DXGI_DDI_ARG_BLT qui se trouvent dans la plage des ressources source et de destination.