PFND3DDDI_CREATERESOURCE2 fonction de rappel (d3dumddi.h)

Article
08/07/2023

Crée une ressource. Implémenté par les pilotes d’affichage en mode utilisateur windows WDDM (Windows Display Driver Model) 1.2 et versions ultérieures.

Syntaxe

PFND3DDDI_CREATERESOURCE2 Pfnd3dddiCreateresource2;

HRESULT Pfnd3dddiCreateresource2(
  [in] HANDLE hDevice,
       D3DDDIARG_CREATERESOURCE2 *unnamedParam2
)
{...}

Paramètres

[in] hDevice

Handle du périphérique d’affichage (contexte graphique) utilisé pour créer la ressource.

unnamedParam2

pResource2 [in, out]

Pointeur vers une structure D3DDDIARG_CREATERESOURCE2 qui décrit la ressource créée.

Valeur retournée

Retourne S_OK ou un résultat d’erreur approprié. Les pilotes WDDM 1.3 et versions ultérieures Direct3D Level 9 doivent retourner ce code d’erreur :

Code de retour	Description
E_INVALIDARG	D3DDDIARG_CREATERESOURCE2 . Flagsmember a la valeur de l’indicateur CaptureBuffer définie et la ressource dépasse ce que le pilote peut prendre en charge.

Remarques

L’appel à CreateResource2 peut contenir une liste de surfaces. Le membre SurfCount de la structure D3DDDIARG_CREATERESOURCE2 spécifiée par le paramètre pResource2 spécifie le nombre de surfaces à créer, y compris les niveaux de carte MIP. Par exemple, une ressource MIP-map de texture 256x256x9 contient une liste de neuf surfaces où le membre SurfCount et le nombre de niveaux de carte MIP sont tous deux définis sur 9. Une carte de cube qui contient neuf niveaux de carte MIP doit avoir le nombre de niveaux de carte MIP défini sur 9 et SurfCount sur 54. Une chaîne de permutation à trois surfaces doit avoir SurfCount défini sur 3 et le nombre de niveaux de carte MIP défini sur 0. Notez que le nombre de niveaux de carte MIP est toujours inférieur ou égal à la valeur dans SurfCount.

En réponse à l’appel CreateResource2 , le pilote d’affichage en mode utilisateur peut appeler la fonction pfnAllocateCb pour créer une ou plusieurs allocations de mémoire. Le pilote d’affichage en mode utilisateur doit déterminer s’il doit créer plusieurs allocations par surface, une allocation pour toutes les surfaces ou une allocation par surface. Pour plus d’informations sur les allocations, consultez Gestion de la mémoire vidéo et planification GPU.

Note La fonction CreateResource2 du pilote n’est pas nécessaire pour appeler pfnAllocateCb avant de retourner ; au lieu de cela, le pilote peut différer la création de l’allocation.

Note Une ressource ne peut être partagée que si toutes les allocations de la ressource sont effectuées de manière atomique dans un seul appel à pfnAllocateCb.

Le membre hResource de la structure D3DDDIARG_CREATERESOURCE2 est un handle utilisé pour identifier la ressource. Le pilote d’affichage en mode utilisateur doit stocker la valeur de hResource qui a été passée dans l’appel CreateResource2 et remplacer la valeur par une autre valeur que le runtime Microsoft Direct3D peut utiliser lorsque l’appel CreateResource2 est retourné. En d’autres termes, dans les appels au runtime, le pilote d’affichage en mode utilisateur utilise la valeur hResource qui a été passée à CreateResource2 ; dans les appels au pilote d’affichage en mode utilisateur (par exemple, dans les appels aux fonctions SetTexture ou SetStreamSource ), le runtime utilise la valeur hResource retournée à partir de CreateResource2. Notez que chaque surface n’a pas de handle explicite ; si la surface doit être référencée individuellement (par exemple dans un appel à la fonction Blt ), elle est désignée par un handle et un index. L’index identifie la surface au sein de la ressource. L’index est identique à l’index de la surface dans le tableau contenu dans le membre pSurfList de D3DDDIARG_CREATERESOURCE2.

Les ressources peuvent être partagées par plusieurs appareils (hDevice) et processus. Le runtime spécifie qu’une ressource est partagée en définissant l’indicateur de champ bit SharedResource dans le membre Flags de D3DDDIARG_CREATERESOURCE2. Si cet indicateur de champ de bits est défini, le pilote d’affichage en mode utilisateur doit respecter les restrictions suivantes sur les ressources partagées :

Le pilote d’affichage en mode utilisateur peut appeler les fonctions pfnAllocateCb et pfnDeallocateCb exactement une fois chacune.
Le pilote d’affichage en mode utilisateur ne peut pas créer d’allocations supplémentaires pour la ressource après la création initiale de la ressource et ne peut également détruire les allocations de ressources qu’au moment où la ressource elle-même est détruite.
Lorsque la fonction DestroyResource du pilote d’affichage en mode utilisateur est appelée pour une ressource partagée qui a été créée ou ouverte via un appel à la fonction CreateResource2 ou OpenResource du pilote, le pilote doit définir le membre hResource de la structure D3DDDICB_DEALLOCATE sur non NULL et le membre NumAllocations de D3DDDICB_DEALLOCATE sur zéro dans un appel à la fonction pfnDeallocateCb pour détruire ou fermer la ressource. Autrement dit, les allocations associées à une ressource partagée ne peuvent pas être détruites ou fermées individuellement ; la ressource doit être détruite ou fermée atomiquement en un seul appel à pfnDeallocateCb.
Le nombre d’allocations doit être cohérent pour le type de ressource (autrement dit, un autre processus qui crée le même type de ressource doit générer le même nombre et le même type d’allocations). En outre, le changement de nom n’est pas autorisé pour ces ressources.

Les indicateurs de champ bits spécifiés dans la structure D3DDDI_RESOURCEFLAGS2 sont transmis dans le membre Indicateurs de D3DDDIARG_CREATERESOURCE2.

Note Une ressource peut être créée sans spécifier d’indicateur. Les surfaces associées à une telle ressource peuvent potentiellement être verrouillées et peuvent être une source ou une destination dans une opération de transfert de bloc de bits (bitblt). Toutefois, ces surfaces ne peuvent pas être utilisées pour autre chose.

Note Les surfaces ordinaires sont différenciées des textures ou des cibles de rendu autonomes par l’absence de l’indicateur Texture ou Champ binaire principal . Par exemple, la présence de l’indicateur de champ bit principal indique une cible de rendu autonome et l’absence de cet indicateur indique une cible de rendu qui est une mémoire tampon arrière.

Note Pour garantir que les modifications apportées au runtime n’interrompent pas les pilotes existants, les pilotes ne doivent pas utiliser les membres réservés suivants de la structure D3DDDIARG_CREATERESOURCE2 dans les appels à leur fonction CreateResource2 pour affecter le comportement des pilotes :

Les bits non définis du membre Flags sont réservés .
Si l’indicateur de champ de bits principal n’est pas défini dans Indicateurs, les membres RefreshRate et Output sont réservés.
Si l’indicateur de champ de bits RenderTarget, DecodeRenderTarget ou VideoProcessRenderTarget n’est pas défini dans Indicateurs, les membres MultisampleType et MultisampleQuality sont réservés .
Si l’indicateur de champ de bits VertexBuffer n’est pas défini dans Indicateurs, le membre Fvf est réservé.
Si les indicateurs de champ de bits Texture, CubeMap et Volume ne sont pas définis dans Indicateurs, le membre MipLevels est réservé.

Pour plus d’informations sur la création et la destruction de ressources, consultez Gestion de la création et de la destruction des ressources.

Pour une ressource de mémoire système, le pilote miniport d’affichage peut choisir d’encapsuler une allocation autour de la mémoire système si la mémoire système est correctement alignée pour un accès direct par l’unité de traitement graphique (GPU). Le pilote miniport d’affichage encapsule une allocation autour de la mémoire système en définissant l’indicateur ExistingSysMem dans le membre Flags de la structure DXGK_ALLOCATIONINFO lors de la création de l’allocation à l’aide de sa fonction DxgkDdiCreateAllocation . Si le pilote de miniport d’affichage ne peut pas encapsuler une allocation autour de la mémoire système ou si l’habillage échoue, le pilote doit toujours réussir la création de la ressource et utiliser le processeur pour accéder à la ressource.

Si le runtime demande de créer une mémoire tampon de vertex ou d’index et si le pilote d’affichage en mode utilisateur ne peut pas créer la mémoire tampon pour des raisons autres que de mémoire insuffisante (par exemple, un manque de prise en charge matérielle), le pilote doit échouer avec D3DERR_NOTAVAILABLE.

Configuration requise

Condition requise	Valeur
Client minimal pris en charge	Windows 8
Serveur minimal pris en charge	Windows Server 2012
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	d3dumddi.h (inclure D3dumddi.h)