> ## 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 > Obtiene un puntero de CPU al subrecurso especificado del recurso, pero es posible que no revele el valor del puntero a las aplicaciones. Map también invalida la caché de la CPU. Obtiene un puntero de CPU al subrecurso especificado del recurso, pero es posible que no revele el valor del puntero a las aplicaciones. **Map** también invalida la caché de la CPU, cuando es necesario, para que las lecturas de la CPU en esta dirección reflejen las modificaciones realizadas por la GPU. ## Sintaxis ```cpp theme={null} HRESULT Map( UINT Subresource, const D3D12_RANGE pReadRange, void ppData ) ``` ### Parámetros *Subresource*
Tipo: UINT Especifica el número de índice del subrecurso. *pReadRange \[in, optional]*
Tipo: const D3D12\_RANGE \* Un puntero a una estructura [D3D12\_RANGE](/reference/graphics/d3d12/structs/d3d12_range_public) que describe el intervalo de memoria al que se va a acceder. Esto indica la región que la CPU podría leer, y las coordenadas son relativas al subrecurso. Un puntero nulo indica que la CPU podría leer todo el subrecurso. Es válido especificar que la CPU no leerá ningún dato pasando un intervalo en el que **End** sea menor o igual que **Begin**. *ppData \[out, optional]*
Tipo: void \*\* Un puntero a un bloque de memoria que recibe un puntero a los datos del recurso. Un puntero nulo es válido y resulta útil para almacenar en caché un intervalo de direcciones virtuales de CPU para métodos como [WriteToSubresource](/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_writetosubresource_public). Cuando ppData no es NULL, el puntero devuelto nunca se desplaza por ningún valor de pReadRange. ### Valor devuelto Tipo: HRESULT Este método devuelve uno de los [códigos devueltos de Direct3D 12](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/d3d12-graphics-reference-returnvalues). ## Comentarios Varios subprocesos pueden llamar a **Map** y [Unmap](/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_unmap_public) de forma segura. Se admiten llamadas anidadas a **Map** y se cuentan las referencias. La primera llamada a **Map** asigna un intervalo de direcciones virtuales de CPU para el recurso. La última llamada a **Unmap** desasigna el intervalo de direcciones virtuales de CPU. La dirección virtual de CPU se suele devolver a la aplicación; pero la manipulación del contenido de texturas con diseños desconocidos impide revelar la dirección virtual de CPU. Consulte [WriteToSubresource](/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_writetosubresource_public) para obtener más detalles. Las aplicaciones no pueden confiar en que la dirección sea coherente, a menos que **Map** se anide de forma persistente. No se garantiza que los punteros devueltos por **Map** tengan todas las capacidades de los punteros normales, pero la mayoría de las aplicaciones no notarán ninguna diferencia en el uso normal. Por ejemplo, los punteros con comportamiento WRITE\_COMBINE tienen garantías de ordenación de memoria de CPU más débiles que el comportamiento WRITE\_BACK. No se garantiza que la memoria accesible tanto por la CPU como por la GPU comparta las mismas garantías atómicas de memoria que tiene la CPU, debido a las limitaciones de PCIe. Use barreras para la sincronización. Hay dos categorías de modelos de uso para **Map**: simple y avanzado. Los modelos de uso simples maximizan el rendimiento de las herramientas, por lo que se recomienda que las aplicaciones se ciñan a los modelos simples hasta que se demuestre que la aplicación requiere los modelos avanzados.

Modelos de uso simples

Las aplicaciones deben ceñirse a las abstracciones de tipo de montón UPLOAD, DEFAULT y READBACK para admitir razonablemente bien todas las arquitecturas de adaptadores. Las aplicaciones deben evitar las lecturas de CPU desde punteros a recursos en montones UPLOAD, incluso de forma accidental. Las lecturas de CPU funcionarán, pero son prohibitivamente lentas en muchas arquitecturas de GPU comunes, por lo que debe tener en cuenta lo siguiente: Se recomienda que las aplicaciones dejen los recursos sin asignar mientras la CPU no los modifique, y que usen intervalos ajustados y precisos en todo momento. Esto habilita los modos más rápidos para herramientas como la [depuración de gráficos](https://learn.microsoft.com/en-us/visualstudio/debugger/visual-studio-graphics-diagnostics) y la capa de depuración. Estas herramientas deben realizar un seguimiento de todas las modificaciones de la CPU en la memoria que la GPU podría leer.

Modelos de uso avanzados

Los recursos de montones accesibles por la CPU se pueden asignar de forma persistente, lo que significa que se puede llamar a **Map** una sola vez, inmediatamente después de la creación del recurso. Nunca es necesario llamar a [Unmap](/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_unmap_public), pero la dirección devuelta por **Map** ya no se debe usar después de que se libere la última referencia al recurso. Cuando se usa la asignación persistente, la aplicación debe asegurarse de que la CPU termine de escribir los datos en la memoria antes de que la GPU ejecute una lista de comandos que lea o escriba la memoria. En escenarios comunes, la aplicación simplemente debe escribir en la memoria antes de llamar a [ExecuteCommandLists](/reference/graphics/d3d12_x/interfaces/id3d12commandqueue/methods/id3d12commandqueue_executecommandlists); pero usar una barrera para retrasar la ejecución de la lista de comandos también funciona. Todos los tipos de memoria accesibles por la CPU admiten el uso de asignación persistente, en el que el recurso se asigna pero nunca se desasigna, siempre que la aplicación no acceda al puntero después de que el recurso se haya eliminado. #### Ejemplos El ejemplo [D3D12Bundles](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/working-samples) usa **ID3D12Resource::Map** de la siguiente manera: Copie los datos del triángulo en el búfer 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); ``` Cree un montón de carga para los búferes 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 el [código de ejemplo de la referencia de D3D12](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/notes-on-example-code).
## Requisitos **Encabezado:** d3d12\_xs.h o d3d12\_x.h
**Biblioteca:** d3d12\_xs.lib o d3d12\_x.lib
**Plataformas compatibles**: consolas XBOX Series y familia XBOX One ## Consulte también [ID3D12Resource](/reference/graphics/d3d12_xs/interfaces/ID3D12Resource/id3d12resource_xs) [Subrecursos](https://learn.microsoft.com/en-us/windows/desktop/direct3d12/subresources) [Unmap](/reference/graphics/d3d12/interfaces/id3d12resource/methods/id3d12resource_unmap_public) ## Related topics - [XMemMapPhysicalPages](/es/reference/system/xmem/functions/xmemmapphysicalpages.md) - [ApuMapApuAddress](/es/reference/audio/apu/functions/apumapapuaddress.md) - [ApuMapVirtualAddress](/es/reference/audio/apu/functions/apumapvirtualaddress.md) - [XMemMapPhysicalPagesScatter](/es/reference/system/xmem/functions/xmemmapphysicalpagesscatter.md) - [Descripción del peso de las reglas en el emparejamiento](/es/services/playfab/multiplayer/matchmaking/rule-weights.md)