PFND3DDDI_LOCKASYNC fonction de rappel (d3dumddi.h)

Article
02/23/2024

La fonction LockAsync verrouille la ressource spécifiée ou une surface dans la ressource.

Syntaxe

PFND3DDDI_LOCKASYNC Pfnd3dddiLockasync;

HRESULT Pfnd3dddiLockasync(
  HANDLE hDevice,
  D3DDDIARG_LOCKASYNC *unnamedParam2
)
{...}

Paramètres

hDevice

Handle pour le périphérique d’affichage (contexte graphique).

unnamedParam2

pData [in, out]

Pointeur vers une structure D3DDDIARG_LOCKASYNC qui décrit la ressource ou la surface dans la ressource à verrouiller.

Valeur retournée

LockAsync retourne l’une des valeurs suivantes :

Code de retour	Description
S_OK	La ressource est correctement verrouillée.
E_OUTOFMEMORY	LockAsync n’a pas pu allouer la mémoire nécessaire pour qu’elle se termine.
D3DDDIERR_WASSTILLDRAWING	Renommage de l’allocation qui correspond à la ressource que la structure D3DDDIARG_LOCKASYNC spécifie a échoué. Le pilote retourne cette valeur uniquement si l’indicateur Ignorer le champ binaire a été défini dans le membre Indicateurs de D3DDDIARG_LOCKASYNC.
E_NOTIMPL	Le pilote d’affichage en mode utilisateur ne prend pas en charge LockAsync pour la ressource spécifiée.

Remarques

Sur les ordinateurs à plusieurs processeurs, le runtime Microsoft Direct3D peut appeler la plupart des fonctions du pilote d’affichage en mode utilisateur à partir d’un thread de travail plutôt que du thread d’application main. Cette optimisation à plusieurs processeurs est transparente pour le pilote d’affichage en mode utilisateur. Lorsque le runtime utilise l’optimisation à plusieurs processeurs, il peut appeler LockAsync plutôt que la fonction Lock pour verrouiller une ressource.

Un pilote d’affichage en mode utilisateur implémente éventuellement LockAsync ; Le runtime Direct3D appelle LockAsync uniquement si le pilote implémente les fonctions LockAsync, UnlockAsync et Rename . Toutefois, un pilote d’affichage en mode utilisateur doit implémenter LockAsync et les fonctions UnlockAsync et Rename , car les applications qui verrouillent fréquemment des ressources dynamiques peuvent ensuite obtenir des performances plus élevées.

Lorsque le runtime Direct3D utilise l’optimisation à plusieurs processeurs, il appelle la plupart des fonctions de pilote d’affichage en mode utilisateur à partir d’un thread de travail que le runtime gère ; Toutefois, le runtime appelle LockAsync sur le thread main de l’application.

Si un pilote d’affichage en mode utilisateur expose une version DDI de 0x0000000B ou supérieure (le pilote retourne cette valeur dans le membre DriverVersion de la structure D3D10DDIARG_OPENADAPTER dans un appel à la fonction OpenAdapter du pilote), le runtime Direct3D appelle LockAsync de manière réentrante. Lorsque le runtime appelle LockAsync de manière réentrante, un thread peut s’exécuter dans LockAsync, tandis qu’un autre thread qui référence le même périphérique d’affichage s’exécute à l’intérieur d’une autre fonction de pilote d’affichage en mode utilisateur. En outre, sur ce type de pilote, le runtime appelle LockAsync pour les surfaces de mémoire système. Si l’indicateur Ignorer le champ binaire est défini dans le membre Indicateurs de D3DDDIARG_LOCKASYNC, le pilote doit tenter de renommer l’allocation qui correspond à la ressource. En règle générale, pour renommer une allocation, le pilote appelle la fonction pfnLockCb avec le handle d’allocation qui correspond à la ressource à verrouiller.

Le pilote doit définir l’indicateur ignorer le champ binaire dans le membre Indicateurs de la structure D3DDDICB_LOCK lorsque le pilote appelle pfnLockCb. Le pilote doit définir l’indicateur de champ de bits NoExistingReference de D3DDDICB_LOCK lorsque le pilote appelle pfnLockCb uniquement si l’indicateur de champ de bits NoExistingReferences a la valeur TRUE dans le membre Flags de D3DDDIARG_LOCKASYNC et que le pilote n’a aucune référence en file d’attente interne à la ressource.

Si le pilote ne parvient pas à renommer l’allocation, la fonction LockAsync du pilote doit renvoyer l’échec au runtime et le pilote ne doit pas vider sa mémoire tampon de commandes. Si le renommage réussit, le pilote doit retourner des pointeurs vers la mémoire de ressource, le pitch et le pitch de tranche, ainsi qu’un handle vers la ressource qui représente l’allocation renommée dans les membres de D3DDDIARG_LOCKASYNC. Le pilote ne doit pas mettre à jour ses structures de suivi interne avec le nouveau handle d’allocation retourné par pfnLockCb . Au lieu de cela, le pilote doit attendre que sa fonction Rename soit appelée.

Si l’indicateur de champ de bits NoOverwrite est défini dans le membre Indicateurs de D3DDDIARG_LOCKASYNC, le pilote doit verrouiller l’allocation correspondante avec une sémantique sans remplacement. Le pilote doit appeler pfnLockCb avec l’indicateur de champ binaire IgnoreSync défini dans le membre Indicateurs de D3DDDICB_LOCK , puis retourner des pointeurs vers la mémoire de ressource, le pitch et le pitch de coupe vers le runtime Direct3D dans les membres de D3DDDIARG_LOCKASYNC. Si le pilote retourne success (S_OK) à partir d’un appel à son LockAsync avec l’indicateur de champ de bits NoOverwrite défini, il peut être appelé pour le rendu avec une surface verrouillée. Le pilote doit retourner la réussite d’un appel à son lockAsync avec NoOverwrite défini uniquement pour les surfaces qui peuvent être rendues pendant le verrouillage. Le gestionnaire de mémoire vidéo exige que les allocations qui correspondent aux surfaces soient prises en charge dans les segments AGP ou d’ouverture ; sinon, les appels à la fonction pfnRenderCb échouent lorsque la mémoire tampon de commande fait référence à une allocation verrouillée.

En résumé, le pilote doit échouer à appeler sa fonction LockAsync si le renommage échoue ou si la sémantique sans remplacement n’est pas prise en charge pour la ressource. Toutefois, le runtime Direct3D récupère après ces échecs. Pour toutes les autres situations, les pilotes doivent retourner la réussite de LockAsync pour améliorer les performances sur les ordinateurs à processeurs multiples.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Disponible dans Windows Vista et versions ultérieures des systèmes d’exploitation Windows.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	d3dumddi.h (inclure D3dumddi.h)