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, cuando es necesario, para que las lecturas de la CPU en esta dirección reflejen las modificaciones realizadas por la GPU.

Sintaxis

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 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. 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.

Comentarios

Varios subprocesos pueden llamar a Map y Unmap 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 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:

No haga que la CPU lea de recursos asociados a montones que sean D3D12_HEAP_TYPE_UPLOAD o que tengan D3D12_CPU_PAGE_PROPERTY_WRITE_COMBINE.
La región de memoria a la que apunta pData se puede asignar con PAGE_WRITECOMBINE, y la aplicación debe respetar todas las restricciones asociadas a dicha memoria.
Incluso el siguiente código C++ puede leer de la memoria y desencadenar la penalización de rendimiento, ya que el código se puede expandir al siguiente código de ensamblado x86.Código C++:
*((int*)MappedResource.pData) = 0;
Código de ensamblado x86:
AND DWORD PTR [EAX],0
Use la configuración de optimización y las construcciones de lenguaje adecuadas para ayudar a evitar esta penalización de rendimiento. Por ejemplo, puede evitar la optimización xor mediante un puntero volatile u optimizando la velocidad del código en lugar del tamaño del código.

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 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, 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; 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 usa ID3D12Resource::Map de la siguiente manera: Copie los datos del triángulo en el búfer de vértices.

// 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<void**>(&pVertexDataBegin)));
memcpy(pVertexDataBegin, triangleVertices, sizeof(triangleVertices));
m_vertexBuffer->Unmap(0, nullptr);

Cree un montón de carga para los búferes de constantes.

// 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<void**>(&m_pConstantBuffers)));

Consulte el código de ejemplo de la referencia de D3D12.

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 Subrecursos Unmap

(all) API references

Error codes

Audio API reference

Chat API reference

Developer kit only API reference

Graphics API reference

Input API reference

Lighting API reference

Networking API reference

XBOX PC remote iteration API reference

System API reference

Tools API reference

Windows device portal REST API reference

XBOX services API reference

MicrosoftGame.config reference

Sintaxis

Parámetros

Valor devuelto

Comentarios

Modelos de uso simples

Modelos de uso avanzados

Ejemplos

Requisitos

Consulte también

​Sintaxis

​Parámetros

​Valor devuelto

​Comentarios

Modelos de uso simples

Modelos de uso avanzados

​Ejemplos

​Requisitos

​Consulte también

Sintaxis

Parámetros

Valor devuelto

Comentarios

Ejemplos

Requisitos

Consulte también