Syntaxe
Paramètres
SubresourceType : UINT Spécifie le numéro d’index de la sous-ressource. pReadRange [in, optional]
Type : const D3D12_RANGE * Pointeur vers une structure D3D12_RANGE qui décrit la plage de mémoire à laquelle accéder. Ceci indique la région que le processeur est susceptible de lire, et les coordonnées sont relatives à la sous-ressource. Un pointeur null indique que toute la sous-ressource peut être lue par le processeur. Il est valide d’indiquer que le processeur ne lira aucune donnée en passant une plage dans laquelle End est inférieur ou égal à Begin. ppData [out, optional]
Type : void ** Pointeur vers un bloc de mémoire qui reçoit un pointeur vers les données de la ressource. Un pointeur null est valide et permet de mettre en cache une plage d’adresses virtuelles CPU pour des méthodes comme WriteToSubresource. Lorsque ppData n’est pas NULL, le pointeur retourné n’est jamais décalé par les valeurs de pReadRange.
Valeur de retour
Type : HRESULT Cette méthode retourne l’un des codes de retour Direct3D 12.Remarques
Map et Unmap peuvent être appelées par plusieurs threads en toute sécurité. Les appels Map imbriqués sont pris en charge et font l’objet d’un décompte de références. Le premier appel à Map alloue une plage d’adresses virtuelles CPU pour la ressource. Le dernier appel à Unmap libère la plage d’adresses virtuelles CPU. L’adresse virtuelle CPU est généralement retournée à l’application ; toutefois, la manipulation du contenu de textures dont la disposition est inconnue empêche de divulguer l’adresse virtuelle CPU. Pour plus de détails, consultez WriteToSubresource. Les applications ne peuvent pas compter sur la cohérence de l’adresse, sauf si Map est imbriqué de manière persistante. Les pointeurs retournés par Map ne sont pas garantis d’avoir toutes les capacités des pointeurs normaux, mais la plupart des applications ne remarqueront aucune différence dans une utilisation normale. Par exemple, les pointeurs avec un comportement WRITE_COMBINE offrent des garanties d’ordonnancement de la mémoire CPU plus faibles que le comportement WRITE_BACK. Il n’est pas garanti que la mémoire accessible à la fois par le processeur et le GPU partage les mêmes garanties de mémoire atomique que celles du processeur, en raison des limitations de PCIe. Utilisez des barrières (fences) pour la synchronisation. Il existe deux catégories de modèles d’utilisation pour Map : simple et avancé. Les modèles d’utilisation simples maximisent les performances des outils ; il est donc recommandé aux applications de s’en tenir aux modèles simples jusqu’à ce qu’il soit prouvé que l’application a besoin des modèles avancés.Modèles d’utilisation simples
Les applications doivent s’en tenir aux abstractions de types de tas UPLOAD, DEFAULT et READBACK, afin de prendre en charge raisonnablement bien toutes les architectures d’adaptateurs. Les applications doivent éviter les lectures CPU à partir de pointeurs vers des ressources sur des tas UPLOAD, même accidentellement. Les lectures CPU fonctionnent, mais sont excessivement lentes sur de nombreuses architectures GPU courantes ; tenez donc compte des points suivants :- Ne faites pas lire par le processeur des ressources associées à des tas de type D3D12_HEAP_TYPE_UPLOAD ou ayant D3D12_CPU_PAGE_PROPERTY_WRITE_COMBINE.
- La région de mémoire vers laquelle pointe pData peut être allouée avec PAGE_WRITECOMBINE, et votre application doit respecter toutes les restrictions associées à ce type de mémoire.
- Même le code C++ suivant peut lire la mémoire et déclencher la pénalité de performances, car le code peut être converti en code assembleur x86 suivant.Code C++ :Code assembleur x86 :
- Utilisez les paramètres d’optimisation et les constructions de langage appropriés pour éviter cette pénalité de performances. Par exemple, vous pouvez éviter l’optimisation xor en utilisant un pointeur volatile ou en optimisant pour la vitesse du code plutôt que pour sa taille.
Modèles d’utilisation avancés
Les ressources situées sur des tas accessibles par le processeur peuvent être mappées de manière persistante, ce qui signifie que Map peut être appelée une seule fois, immédiatement après la création de la ressource. Unmap n’a jamais besoin d’être appelée, mais l’adresse retournée par Map ne doit plus être utilisée après la libération de la dernière référence à la ressource. Lors de l’utilisation d’un mappage persistant, l’application doit s’assurer que le processeur a fini d’écrire les données en mémoire avant que le GPU n’exécute une liste de commandes qui lit ou écrit cette mémoire. Dans les scénarios courants, l’application doit simplement écrire en mémoire avant d’appeler ExecuteCommandLists ; mais l’utilisation d’une barrière (fence) pour retarder l’exécution de la liste de commandes fonctionne également. Tous les types de mémoire accessibles par le processeur prennent en charge le mappage persistant, où la ressource est mappée puis jamais démappée, à condition que l’application n’accède pas au pointeur après la suppression de la ressource.Exemples
L’exemple D3D12Bundles utilise ID3D12Resource::Map comme suit : Copiez les données du triangle dans la mémoire tampon de sommets.Configuration requise
En-tête : d3d12_xs.h ou d3d12_x.hBibliothèque : d3d12_xs.lib ou d3d12_x.lib
Plateformes prises en charge : consoles XBOX Series et famille XBOX One