> ## 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 > Obtém um ponteiro de CPU para o sub-recurso especificado no recurso, mas pode não divulgar o valor do ponteiro para os aplicativos. Map também invalida o cache da CPU. Obtém um ponteiro de CPU para o sub-recurso especificado no recurso, mas pode não divulgar o valor do ponteiro para os aplicativos. **Map** também invalida o cache da CPU, quando necessário, para que as leituras da CPU nesse endereço reflitam quaisquer modificações feitas pela GPU. ## Sintaxe ```cpp theme={null} HRESULT Map( UINT Subresource, const D3D12_RANGE pReadRange, void ppData ) ``` ### Parâmetros *Subresource*
Tipo: UINT Especifica o número de índice do sub-recurso. *pReadRange \[in, optional]*
Tipo: const D3D12\_RANGE \* Um ponteiro para uma estrutura [D3D12\_RANGE](/pt-BR/reference/graphics/d3d12/structs/d3d12_range_public) que descreve o intervalo de memória a ser acessado. Isso indica a região que a CPU pode ler, e as coordenadas são relativas ao sub-recurso. Um ponteiro nulo indica que todo o sub-recurso pode ser lido pela CPU. É válido especificar que a CPU não lerá nenhum dado passando um intervalo em que **End** seja menor ou igual a **Begin**. *ppData \[out, optional]*
Tipo: void \*\* Um ponteiro para um bloco de memória que recebe um ponteiro para os dados do recurso. Um ponteiro nulo é válido e é útil para armazenar em cache um intervalo de endereços virtuais da CPU para métodos como [WriteToSubresource](/pt-BR/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_writetosubresource_public). Quando ppData não é NULL, o ponteiro retornado nunca é deslocado por nenhum valor em pReadRange. ### Valor retornado Tipo: HRESULT Este método retorna um dos [Códigos de retorno do Direct3D 12](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/d3d12-graphics-reference-returnvalues). ## Comentários **Map** e [Unmap](/pt-BR/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_unmap_public) podem ser chamados com segurança por vários threads. Chamadas aninhadas de **Map** têm suporte e são contadas por referência. A primeira chamada para **Map** aloca um intervalo de endereços virtuais da CPU para o recurso. A última chamada para **Unmap** desaloca o intervalo de endereços virtuais da CPU. O endereço virtual da CPU geralmente é retornado ao aplicativo; mas manipular o conteúdo de texturas com layouts desconhecidos impede a divulgação do endereço virtual da CPU. Consulte [WriteToSubresource](/pt-BR/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_writetosubresource_public) para obter mais detalhes. Os aplicativos não podem depender de o endereço ser consistente, a menos que **Map** esteja aninhado de forma persistente. Não há garantia de que os ponteiros retornados por **Map** tenham todos os recursos de ponteiros normais, mas a maioria dos aplicativos não notará diferença no uso normal. Por exemplo, ponteiros com comportamento WRITE\_COMBINE têm garantias de ordenação de memória da CPU mais fracas do que o comportamento WRITE\_BACK. Não há garantia de que a memória acessível tanto pela CPU quanto pela GPU compartilhe as mesmas garantias de memória atômica que a CPU tem, devido a limitações do PCIe. Use fences para sincronização. Há duas categorias de modelo de uso para **Map**: simples e avançado. Os modelos de uso simples maximizam o desempenho das ferramentas, portanto recomenda-se que os aplicativos se mantenham nos modelos simples até que se comprove que os modelos avançados são necessários para o aplicativo.

Modelos de uso simples

Os aplicativos devem se ater às abstrações de tipo de heap UPLOAD, DEFAULT e READBACK, para oferecer suporte razoavelmente bom a todas as arquiteturas de adaptador. Os aplicativos devem evitar leituras da CPU a partir de ponteiros para recursos em heaps UPLOAD, mesmo que acidentalmente. As leituras da CPU funcionarão, mas são proibitivamente lentas em muitas arquiteturas de GPU comuns, portanto considere o seguinte: Recomenda-se que os aplicativos deixem os recursos sem mapeamento enquanto a CPU não os modificar e usem intervalos precisos e restritos o tempo todo. Isso habilita os modos mais rápidos para ferramentas, como a [Depuração de gráficos](https://learn.microsoft.com/en-us/visualstudio/debugger/visual-studio-graphics-diagnostics) e a camada de depuração. Essas ferramentas precisam rastrear todas as modificações da CPU na memória que a GPU possa ler.

Modelos de uso avançados

Recursos em heaps acessíveis pela CPU podem ser mapeados de forma persistente, o que significa que **Map** pode ser chamado uma vez, imediatamente após a criação do recurso. [Unmap](/pt-BR/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_unmap_public) nunca precisa ser chamado, mas o endereço retornado por **Map** não deve mais ser usado depois que a última referência ao recurso for liberada. Ao usar o mapeamento persistente, o aplicativo deve garantir que a CPU termine de gravar os dados na memória antes que a GPU execute uma lista de comandos que leia ou grave essa memória. Em cenários comuns, o aplicativo precisa apenas gravar na memória antes de chamar [ExecuteCommandLists](/pt-BR/reference/graphics/d3d12_x/interfaces/id3d12commandqueue/methods/id3d12commandqueue_executecommandlists); mas usar uma fence para atrasar a execução da lista de comandos também funciona. Todos os tipos de memória acessíveis pela CPU dão suporte ao uso de mapeamento persistente, em que o recurso é mapeado, mas nunca tem o mapeamento desfeito, desde que o aplicativo não acesse o ponteiro após o recurso ter sido descartado. #### Exemplos O exemplo [D3D12Bundles](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/working-samples) usa **ID3D12Resource::Map** da seguinte maneira: Copie os dados do triângulo para o buffer de vértices. ```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); ``` Crie um heap de upload para os buffers 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))); ``` Consulte o [Código de exemplo na referência do D3D12](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/notes-on-example-code).
## Requisitos **Cabeçalho:** d3d12\_xs.h ou d3d12\_x.h
**Biblioteca:** d3d12\_xs.lib ou d3d12\_x.lib
**Plataformas com suporte**: consoles XBOX Series e família XBOX One ## Confira também [ID3D12Resource](/pt-BR/reference/graphics/d3d12_xs/interfaces/ID3D12Resource/id3d12resource_xs) [Sub-recursos](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/subresources) [Unmap](/pt-BR/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_unmap_public) ## Related topics - [XMemMapPhysicalPages](/pt-BR/reference/system/xmem/functions/xmemmapphysicalpages.md) - [ApuMapApuAddress](/pt-BR/reference/audio/apu/functions/apumapapuaddress.md) - [ApuMapVirtualAddress](/pt-BR/reference/audio/apu/functions/apumapvirtualaddress.md) - [XMemMapPhysicalPagesScatter](/pt-BR/reference/system/xmem/functions/xmemmapphysicalpagesscatter.md) - [Entendendo o peso das regras no matchmaking](/pt-BR/services/playfab/multiplayer/matchmaking/rule-weights.md)