> ## Documentation Index > Fetch the complete documentation index at: https://devdocs.xbox.com/llms.txt > Use this file to discover all available pages before exploring further. # Map > Obtient un pointeur CPU vers la sous-ressource spécifiée dans la ressource, mais peut ne pas divulguer la valeur du pointeur aux applications. Map invalide également le cache du CPU. Obtient un pointeur CPU vers la sous-ressource spécifiée dans la ressource, mais peut ne pas divulguer la valeur du pointeur aux applications. **Map** invalide également le cache du CPU, au besoin, afin que les lectures du CPU à cette adresse reflètent toutes les modifications effectuées par le GPU. ## Syntaxe ```cpp theme={null} HRESULT Map( UINT Subresource, const D3D12_RANGE pReadRange, void ppData ) ``` ### Paramètres *Subresource*
Type : 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](/fr-CA/reference/graphics/d3d12/structs/d3d12_range_public) qui décrit la plage de mémoire à laquelle accéder. Ceci indique la région que le CPU pourrait lire, et les coordonnées sont relatives à la sous-ressource. Un pointeur nul indique que la sous-ressource entière pourrait être lue par le CPU. Il est valide de spécifier que le CPU ne lira aucune donnée en passant une plage où **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 nul est valide et utile pour mettre en cache une plage d'adresses virtuelles CPU pour des méthodes comme [WriteToSubresource](/fr-CA/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_writetosubresource_public). 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](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/d3d12-graphics-reference-returnvalues). ## Remarques **Map** et [Unmap](/fr-CA/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_unmap_public) peuvent être appelées en toute sécurité par plusieurs threads. 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. Consultez [WriteToSubresource](/fr-CA/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_writetosubresource_public) pour plus de détails. Les applications ne peuvent pas se fier à la constance de l'adresse, sauf si **Map** est imbriqué de façon 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 le 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 CPU et le GPU partage les mêmes garanties de mémoire atomique que celles du CPU, en raison des limitations de PCIe. Utilisez des clôtures pour la synchronisation. Il existe deux catégories de modèles d'utilisation pour **Map** : simple et avancée. 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 devraient 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 devraient éviter les lectures du CPU à partir de pointeurs vers des ressources situées sur des tas UPLOAD, même accidentellement. Les lectures du CPU fonctionnent, mais elles sont excessivement lentes sur de nombreuses architectures GPU courantes; tenez donc compte des points suivants : Il est recommandé aux applications de laisser les ressources non mappées tant que le CPU ne les modifie pas, et d'utiliser en tout temps des plages précises et restreintes. Cela permet d'activer les modes les plus rapides des outils, comme le [débogage graphique](https://learn.microsoft.com/en-us/visualstudio/debugger/visual-studio-graphics-diagnostics) et la couche de débogage. Ces outils doivent suivre toutes les modifications effectuées par le CPU dans la mémoire que le GPU pourrait lire.

Modèles d'utilisation avancés

Les ressources situées sur des tas accessibles par le CPU peuvent être mappées de façon persistante, ce qui signifie que **Map** peut être appelée une seule fois, immédiatement après la création de la ressource. Il n'est jamais nécessaire d'appeler [Unmap](/fr-CA/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_unmap_public), 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 CPU a terminé d'écrire les données en mémoire avant que le GPU 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](/fr-CA/reference/graphics/d3d12_x/interfaces/id3d12commandqueue/methods/id3d12commandqueue_executecommandlists); mais l'utilisation d'une clôture pour retarder l'exécution de la liste de commandes fonctionne également. Tous les types de mémoire accessibles par le CPU 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](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/working-samples) utilise **ID3D12Resource::Map** comme suit : Copiez les données du triangle dans la mémoire tampon de sommets. ```cpp theme={null} // Copy the triangle data to the vertex buffer. UINT8* pVertexDataBegin; CD3DX12_RANGE readRange(0, 0); // We do not intend to read from this resource on the CPU. ThrowIfFailed(m_vertexBuffer->Map(0, &readRange, reinterpret_cast(&pVertexDataBegin))); memcpy(pVertexDataBegin, triangleVertices, sizeof(triangleVertices)); m_vertexBuffer->Unmap(0, nullptr); ``` Créez un tas de chargement pour les mémoires tampons de constantes. ```cpp theme={null} // Create an upload heap for the constant buffers. ThrowIfFailed(pDevice->CreateCommittedResource( &CD3DX12_HEAP_PROPERTIES(D3D12_HEAP_TYPE_UPLOAD), D3D12_HEAP_FLAG_NONE, &CD3DX12_RESOURCE_DESC::Buffer(sizeof(ConstantBuffer) * m_cityRowCount * m_cityColumnCount), D3D12_RESOURCE_STATE_GENERIC_READ, nullptr, IID_PPV_ARGS(&m_cbvUploadHeap))); // Map the constant buffers. Note that unlike D3D11, the resource // does not need to be unmapped for use by the GPU. In this sample, // the resource stays 'permanently' mapped to avoid overhead with // mapping/unmapping each frame. CD3DX12_RANGE readRange(0, 0); // We do not intend to read from this resource on the CPU. ThrowIfFailed(m_cbvUploadHeap->Map(0, &readRange, reinterpret_cast(&m_pConstantBuffers))); ``` Consultez l'[exemple de code dans la référence D3D12](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/notes-on-example-code).
## Configuration requise **En-tête :** d3d12\_xs.h ou d3d12\_x.h
**Bibliothèque :** d3d12\_xs.lib ou d3d12\_x.lib
**Plateformes prises en charge :** consoles XBOX Series et famille XBOX One ## Voir aussi [ID3D12Resource](/fr-CA/reference/graphics/d3d12_xs/interfaces/ID3D12Resource/id3d12resource_xs) [Sous-ressources](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/subresources) [Unmap](/fr-CA/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_unmap_public) ## Related topics - [XMemMapPhysicalPages](/fr-CA/reference/system/xmem/functions/xmemmapphysicalpages.md) - [ApuMapApuAddress](/fr-CA/reference/audio/apu/functions/apumapapuaddress.md) - [ApuMapVirtualAddress](/fr-CA/reference/audio/apu/functions/apumapvirtualaddress.md) - [XMemMapPhysicalPagesScatter](/fr-CA/reference/system/xmem/functions/xmemmapphysicalpagesscatter.md) - [Ajout d'une valeur de champ à une règle de statistique](/fr-CA/services/xbox-services/player-data/stats-leaderboards/event-based/config/live-stat-name-value.md)