ID3D12Resource::Metode peta (d3d12.h)

Artikel
08/23/2023

Mendapatkan pointer CPU ke subsumber daya yang ditentukan dalam sumber daya, tetapi mungkin tidak mengungkapkan nilai pointer ke aplikasi. Peta juga membatalkan cache CPU, jika perlu, sehingga CPU membaca ke alamat ini mencerminkan modifikasi apa pun yang dibuat oleh GPU.

Sintaks

HRESULT Map(
                  UINT              Subresource,
  [in, optional]  const D3D12_RANGE *pReadRange,
  [out, optional] void              **ppData
);

Parameter

Subresource

Jenis: UINT

Menentukan nomor indeks subsumber daya.

[in, optional] pReadRange

Jenis: const D3D12_RANGE*

Penunjuk ke struktur D3D12_RANGE yang menjelaskan rentang memori yang akan diakses.

Ini menunjukkan wilayah yang mungkin dibaca CPU, dan koordinatnya relatif subsumber daya. Pointer null menunjukkan seluruh subsumber daya mungkin dibaca oleh CPU. Valid untuk menentukan CPU tidak akan membaca data apa pun dengan melewati rentang di mana Akhir kurang dari atau sama dengan Mulai.

[out, optional] ppData

Jenis: batal**

Penunjuk ke blok memori yang menerima penunjuk ke data sumber daya.

Pointer null valid dan berguna untuk menyimpan rentang alamat virtual CPU untuk metode seperti WriteToSubresource. Ketika ppData bukan NULL, penunjuk yang dikembalikan tidak pernah diimbangi oleh nilai apa pun di pReadRange.

Mengembalikan nilai

Jenis: HRESULT

Metode ini mengembalikan salah satu Kode Pengembalian Direct3D 12.

Keterangan

Peta dan Batalkan Pemetaan dapat dipanggil oleh beberapa utas dengan aman. Panggilan Peta Berlapis didukung dan dihitung ulang. Panggilan pertama ke Peta mengalokasikan rentang alamat virtual CPU untuk sumber daya. Panggilan terakhir ke Batalkan pemindahan rentang alamat virtual CPU. Alamat virtual CPU umumnya dikembalikan ke aplikasi; tetapi memanipulasi konten tekstur dengan tata letak yang tidak diketahui menghalangi pengungkapan alamat virtual CPU. Lihat WriteToSubresource untuk detail selengkapnya. Aplikasi tidak dapat mengandalkan alamat yang konsisten, kecuali Peta terus berlapis.

Pointer yang dikembalikan oleh Peta tidak dijamin memiliki semua kemampuan pointer normal, tetapi sebagian besar aplikasi tidak akan melihat perbedaan dalam penggunaan normal. Misalnya, pointer dengan perilaku WRITE_COMBINE memiliki jaminan pemesanan memori CPU yang lebih lemah daripada perilaku WRITE_BACK. Memori yang dapat diakses oleh CPU dan GPU tidak dijamin untuk berbagi jaminan memori atom yang sama yang dimiliki CPU, karena keterbatasan PCIe. Gunakan pagar untuk sinkronisasi.

Ada dua kategori model penggunaan untuk Peta, sederhana dan canggih. Model penggunaan sederhana memaksimalkan performa alat, sehingga aplikasi disarankan untuk tetap menggunakan model sederhana sampai model tingkat lanjut terbukti diperlukan oleh aplikasi.

Model Penggunaan Sederhana

Aplikasi harus menempel pada abstraksi jenis tumpukan UPLOAD, DEFAULT, dan READBACK, untuk mendukung semua arsitektur adapter dengan cukup baik.

Aplikasi harus menghindari pembacaan CPU dari pointer ke sumber daya pada heap UPLOAD, bahkan secara tidak sengaja. Pembacaan CPU akan berfungsi, tetapi dilarang lambat pada banyak arsitektur GPU umum, jadi pertimbangkan hal berikut:

Jangan membuat CPU dibaca dari sumber daya yang terkait dengan tumpukan yang D3D12_HEAP_TYPE_UPLOAD atau memiliki D3D12_CPU_PAGE_PROPERTY_WRITE_COMBINE.
Wilayah memori tempat poin pData dapat dialokasikan dengan PAGE_WRITECOMBINE, dan aplikasi Anda harus mematuhi semua batasan yang terkait dengan memori tersebut.
Bahkan kode C++ berikut dapat membaca dari memori dan memicu penalti performa karena kode dapat diperluas ke kode perakitan x86 berikut.
Kode C++:
```
*((int*)MappedResource.pData) = 0;
```
Kode rakitan x86:
```
AND DWORD PTR [EAX],0
```
Gunakan pengaturan pengoptimalan dan konstruksi bahasa yang sesuai untuk membantu menghindari penalti performa ini. Misalnya, Anda dapat menghindari pengoptimalan xor dengan menggunakan penunjuk volatil atau dengan mengoptimalkan kecepatan kode alih-alih ukuran kode.

Aplikasi didorong untuk membiarkan sumber daya tidak dipetakan sementara CPU tidak akan memodifikasinya, dan menggunakan rentang yang ketat dan akurat setiap saat. Ini memungkinkan mode tercepat untuk alat, seperti Debugging Grafis dan lapisan debug. Alat semacam itu perlu melacak semua modifikasi CPU pada memori yang dapat dibaca GPU.

Model Penggunaan Tingkat Lanjut

Sumber daya pada tumpukan yang dapat diakses CPU dapat dipetakan secara terus-menerus, yang berarti Peta dapat dipanggil sekali, segera setelah pembuatan sumber daya. Unmap tidak perlu dipanggil, tetapi alamat yang dikembalikan dari Peta tidak boleh lagi digunakan setelah referensi terakhir ke sumber daya dirilis. Saat menggunakan peta persisten, aplikasi harus memastikan CPU selesai menulis data ke dalam memori sebelum GPU menjalankan daftar perintah yang membaca atau menulis memori. Dalam skenario umum, aplikasi hanya harus menulis ke memori sebelum memanggil ExecuteCommandLists; tetapi menggunakan pagar untuk menunda eksekusi daftar perintah juga berfungsi.

Semua jenis memori yang dapat diakses CPU mendukung penggunaan pemetaan persisten, di mana sumber daya dipetakan tetapi kemudian tidak pernah dipetakan, asalkan aplikasi tidak mengakses pointer setelah sumber daya dibuang.

Contoh

Sampel D3D12Bundles menggunakan ID3D12Resource::Map sebagai berikut:

Salin data segitiga ke buffer vertex.

// 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);

Buat heap unggahan untuk buffer konstanta.

// 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)));

Lihat Contoh Kode dalam Referensi D3D12.