ID3D11DeviceContext::UpdateSubresource method (d3d11.h)

Artikel
08/22/2023

CPU menyalin data dari memori ke sub sumber daya yang dibuat dalam memori yang tidak dapat dipetakan.

Sintaks

void UpdateSubresource(
  [in]           ID3D11Resource  *pDstResource,
  [in]           UINT            DstSubresource,
  [in, optional] const D3D11_BOX *pDstBox,
  [in]           const void      *pSrcData,
  [in]           UINT            SrcRowPitch,
  [in]           UINT            SrcDepthPitch
);

Parameter

[in] pDstResource

Jenis: ID3D11Resource*

Penunjuk ke sumber daya tujuan (lihat ID3D11Resource).

[in] DstSubresource

Jenis: UINT

Indeks berbasis nol, yang mengidentifikasi sub sumber daya tujuan. Lihat D3D11CalcSubresource untuk detail selengkapnya.

[in, optional] pDstBox

Jenis: const D3D11_BOX*

Penunjuk ke kotak yang menentukan bagian sub sumber daya tujuan untuk menyalin data sumber daya. Koordinat berada dalam byte untuk buffer dan dalam texel untuk tekstur. Jika NULL, data ditulis ke subsumber daya tujuan tanpa offset. Dimensi sumber harus sesuai dengan tujuan (lihat D3D11_BOX).

Kotak kosong menghasilkan no-op. Kotak kosong jika nilai atas lebih besar dari atau sama dengan nilai bawah, atau nilai kiri lebih besar dari atau sama dengan nilai kanan, atau nilai depan lebih besar dari atau sama dengan nilai belakang. Saat kotak kosong, UpdateSubresource tidak melakukan operasi pembaruan.

[in] pSrcData

Jenis: const void*

Penunjuk ke data sumber dalam memori.

[in] SrcRowPitch

Jenis: UINT

Ukuran satu baris data sumber.

[in] SrcDepthPitch

Jenis: UINT

Ukuran satu ilis kedalaman data sumber.

Mengembalikan nilai

Tidak ada

Keterangan

Untuk penyangga konstanta shader; atur pDstBox ke NULL. Tidak dimungkinkan untuk menggunakan metode ini untuk memperbarui sebagian buffer shader-constant.

Sumber daya tidak dapat digunakan sebagai tujuan jika:

sumber daya dibuat dengan penggunaan yang tidak dapat diubah atau dinamis .
sumber daya dibuat sebagai sumber daya stensil kedalaman.
sumber daya dibuat dengan kemampuan multisampling (lihat DXGI_SAMPLE_DESC).

Ketika UpdateSubresource kembali, aplikasi bebas untuk mengubah atau bahkan membebaskan data yang diacu oleh pSrcData karena metode telah menyalin/memposisikan konten asli.

Performa UpdateSubresource tergantung pada apakah ada ketidakcocokan untuk sumber daya tujuan atau tidak. Misalnya, ketidakcocokan untuk sumber daya buffer vertex terjadi ketika aplikasi menjalankan panggilan Draw dan kemudian memanggil UpdateSubresource pada buffer vertex yang sama sebelum panggilan Draw benar-benar dijalankan oleh GPU.

Ketika ada ketidakcocokan untuk sumber daya, UpdateSubresource akan melakukan 2 salinan data sumber. Pertama, data disalin oleh CPU ke ruang penyimpanan sementara yang dapat diakses oleh buffer perintah. Salinan ini terjadi sebelum metode kembali. Salinan kedua kemudian dilakukan oleh GPU untuk menyalin data sumber ke dalam memori yang tidak dapat dipetakan. Salinan kedua ini terjadi secara asinkron karena dijalankan oleh GPU ketika buffer perintah dibersihkan.
Ketika tidak ada pertikaian sumber daya, perilaku UpdateSubresource bergantung pada mana yang lebih cepat (dari perspektif CPU): menyalin data ke buffer perintah dan kemudian menjalankan salinan kedua ketika buffer perintah dihapus, atau meminta CPU menyalin data ke lokasi sumber daya akhir. Ini tergantung pada arsitektur sistem yang mendasar.

CatatanHanya berlaku untuk tingkat fitur 9_x perangkat keras Jika Anda menggunakan UpdateSubresource atau ID3D11DeviceContext::CopySubresourceRegion untuk menyalin dari sumber daya penahapan ke sumber daya default, Anda dapat merusak konten tujuan. Ini terjadi jika Anda meneruskan kotak sumber NULL dan jika sumber daya sumber memiliki dimensi yang berbeda dari sumber daya tujuan atau jika Anda menggunakan offset tujuan, (x, y, dan z). Dalam situasi ini, selalu berikan kotak sumber yang merupakan ukuran penuh sumber daya sumber.

Untuk lebih memahami pitch baris sumber dan parameter pitch kedalaman sumber, ilustrasi berikut menunjukkan tekstur volume 3D. Ilustrasi tekstur volume 3D

Setiap blok dalam visual ini mewakili elemen data, dan ukuran setiap elemen tergantung pada format sumber daya. Misalnya, jika format sumber daya DXGI_FORMAT_R32G32B32A32_FLOAT, ukuran setiap elemen akan menjadi 128 bit, atau 16 byte. Tekstur volume 3D ini memiliki lebar dua, tinggi tiga, dan kedalaman empat.

Untuk menghitung pitch baris sumber dan pitch kedalaman sumber untuk sumber daya tertentu, gunakan rumus berikut:

Pitch Baris Sumber = [ukuran satu elemen dalam byte] * [jumlah elemen dalam satu baris]
Pitch Kedalaman Sumber = [Pitch Baris Sumber] * [jumlah baris (tinggi)]

Dalam kasus contoh tekstur volume 3D ini di mana ukuran setiap elemen adalah 16 byte, rumusnya adalah sebagai berikut:

Pitch Baris Sumber = 16 * 2 = 32
Pitch Kedalaman Sumber = 16 * 2 * 3 = 96

Ilustrasi berikut menunjukkan sumber daya seperti yang ditata dalam memori. Ilustrasi tekstur volume 3D yang ditata dalam memori

Misalnya, cuplikan kode berikut menunjukkan cara menentukan wilayah tujuan dalam tekstur 2D. Asumsikan tekstur tujuan adalah 512x512 dan operasi akan menyalin data yang ditujukan oleh pData ke [(120,100).. (200.220)] dalam tekstur tujuan. Asumsikan juga bahwa rowPitch telah diinisialisasi dengan nilai yang tepat (seperti yang dijelaskan di atas). depan dan belakang masing-masing diatur ke 0 dan 1, karena dengan memiliki depan sama dengan belakang, kotak secara teknis kosong.


D3D11_BOX destRegion;
destRegion.left = 120;
destRegion.right = 200;
destRegion.top = 100;
destRegion.bottom = 220;
destRegion.front = 0;
destRegion.back = 1;

pd3dDeviceContext->UpdateSubresource( pDestTexture, 0, &destRegion, pData, rowPitch, 0 );

Kasus 1D serupa. Cuplikan berikut menunjukkan cara menentukan wilayah tujuan dalam tekstur 1D. Gunakan asumsi yang sama seperti di atas, kecuali bahwa teksturnya panjangnya 512.


D3D11_BOX destRegion;
destRegion.left = 120;
destRegion.right = 200;
destRegion.top = 0;
destRegion.bottom = 1;
destRegion.front = 0;
destRegion.back = 1;

pd3dDeviceContext->UpdateSubresource( pDestTexture, 0, &destRegion, pData, rowPitch, 0 );

Untuk informasi tentang berbagai jenis sumber daya dan cara kerja UpdateSubresource dengan setiap jenis sumber daya, lihat Pengenalan Sumber Daya di Direct3D 11.

Memanggil UpdateSubresource pada Konteks yang Ditangguhkan

Jika aplikasi Anda memanggil UpdateSubresource pada konteks yang ditangguhkan dengan kotak tujuan—di mana pDstBox menunjuk—yang memiliki offset non-(0,0,0), dan jika driver tidak mendukung daftar perintah, UpdateSubresource secara tidak tepat menerapkan offset kotak tujuan tersebut ke parameter pSrcData . Untuk mengatasi perilaku ini, gunakan kode berikut:


HRESULT UpdateSubresource_Workaround(
  ID3D11Device *pDevice,
  ID3D11DeviceContext *pDeviceContext,
  ID3D11Resource *pDstResource,
  UINT dstSubresource,
  const D3D11_BOX *pDstBox,
  const void *pSrcData,
  UINT srcBytesPerElement,
  UINT srcRowPitch,
  UINT srcDepthPitch,
  bool* pDidWorkAround )
{
     HRESULT hr = S_OK;
     bool needWorkaround = false;
     D3D11_DEVICE_CONTEXT_TYPE contextType = pDeviceContext->GetType();

     if( pDstBox && (D3D11_DEVICE_CONTEXT_DEFERRED == contextType) )
     {
          D3D11_FEATURE_DATA_THREADING threadingCaps = { FALSE, FALSE };

          hr = pDevice->CheckFeatureSupport( D3D11_FEATURE_THREADING, &threadingCaps, sizeof(threadingCaps) );
          if( SUCCEEDED(hr) )
          {
               if( !threadingCaps.DriverCommandLists )
               {
                    needWorkaround = true;
               }
          }
     }

     const void* pAdjustedSrcData = pSrcData;

     if( needWorkaround )
     {
          D3D11_BOX alignedBox = *pDstBox;
		
          // convert from pixels to blocks
          if( m_bBC )
          {
               alignedBox.left     /= 4;
               alignedBox.right    /= 4;
               alignedBox.top      /= 4;
               alignedBox.bottom   /= 4;
          }

          pAdjustedSrcData = ((const BYTE*)pSrcData) - (alignedBox.front * srcDepthPitch) - (alignedBox.top * srcRowPitch) - (alignedBox.left * srcBytesPerElement);
     }

     pDeviceContext->UpdateSubresource( pDstResource, dstSubresource, pDstBox, pAdjustedSrcData, srcRowPitch, srcDepthPitch );

     if( pDidWorkAround )
     {
          *pDidWorkAround = needWorkaround;
     }

     return hr;
}