PFND3DDDI_CREATERESOURCE fonction de rappel (d3dumddi.h)

Article
08/07/2023

La fonction CreateResource crée une ressource.

Syntaxe

PFND3DDDI_CREATERESOURCE Pfnd3dddiCreateresource;

HRESULT Pfnd3dddiCreateresource(
  HANDLE hDevice,
  D3DDDIARG_CREATERESOURCE *unnamedParam2
)
{...}

Paramètres

hDevice

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

unnamedParam2

pResource [in, out]

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

Valeur retournée

CreateResource retourne l’une des valeurs suivantes :

Code de retour	Description
S_OK	La ressource est créée avec succès.
E_OUTOFMEMORY	CreateResource n’a pas pu allouer la mémoire nécessaire pour qu’il se termine.
D3DERR_NOTAVAILABLE	CreateResource n’a pas pu créer la ressource pour des raisons autres que l’impossibilité d’allouer de la mémoire. CreateResource peut renvoyer cette erreur uniquement lors de la création de tampons de vertex ou d’index.

Remarques

L’appel à CreateResource peut contenir une liste de surfaces. Le membre SurfCount de la structure D3DDDIARG_CREATERESOURCE spécifiée par le paramètre pResource 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 CreateResource , 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 CreateResource du pilote n’est pas nécessaire pour appeler pfnAllocateCb avant le retour ; 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 dans la structure D3DDDIARG_CREATERESOURCE 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 CreateResource et remplacer la valeur par une autre valeur que le runtime Microsoft Direct3D peut utiliser lorsque l’appel CreateResource 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 à CreateResource ; 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 qui a été retournée à partir de CreateResource. 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_CREATERESOURCE.

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 Indicateurs de D3DDDIARG_CREATERESOURCE. 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 CreateResource 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 de bits spécifiés dans la structure D3DDDI_RESOURCEFLAGS sont transmis dans le membre Indicateurs de D3DDDIARG_CREATERESOURCE.

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_CREATERESOURCE dans les appels à leur fonction CreateResource 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.

La nouvelle DDI CreateResource diffère de la DDI DdCreateSurface pour le modèle de pilote d’affichage Microsoft Windows 2000 des manières suivantes :

Dans la nouvelle DDI CreateResource , les surfaces ne sont jamais attachées explicitement. Toutes les pièces jointes sont impliquées par la création atomique.
Dans la nouvelle DDI CreateResource , la création partielle de mappages de cube n’est pas autorisée.

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	Disponible dans Windows Vista et les versions ultérieures des systèmes d’exploitation Windows.
Plateforme cible	Desktop (Expérience utilisateur)
En-tête	d3dumddi.h (inclure D3dumddi.h)