METODE ID3D12GraphicsCommandList::CopyTextureRegion (d3d12.h)

  • Artikel

Metode ini menggunakan GPU untuk menyalin data tekstur di antara dua lokasi. Sumber dan tujuan dapat mereferensikan data tekstur yang terletak di dalam sumber daya buffer atau sumber daya tekstur.

Sintaks

void CopyTextureRegion(
  [in]           const D3D12_TEXTURE_COPY_LOCATION *pDst,
                 UINT                              DstX,
                 UINT                              DstY,
                 UINT                              DstZ,
  [in]           const D3D12_TEXTURE_COPY_LOCATION *pSrc,
  [in, optional] const D3D12_BOX                   *pSrcBox
);

Parameter

[in] pDst

Jenis: const D3D12_TEXTURE_COPY_LOCATION*

Menentukan D3D12_TEXTURE_COPY_LOCATION tujuan. Subsumber daya yang dimaksud harus dalam status D3D12_RESOURCE_STATE_COPY_DEST.

DstX

Jenis: UINT

Koordinat x sudut kiri atas wilayah tujuan.

DstY

Jenis: UINT

Koordinat y dari sudut kiri atas wilayah tujuan. Untuk subsumber daya 1D, ini harus nol.

DstZ

Jenis: UINT

Koordinat z dari sudut kiri atas wilayah tujuan. Untuk sub sumber daya 1D atau 2D, ini harus nol.

[in] pSrc

Jenis: const D3D12_TEXTURE_COPY_LOCATION*

Menentukan D3D12_TEXTURE_COPY_LOCATION sumber. Subsumber daya yang dimaksud harus dalam status D3D12_RESOURCE_STATE_COPY_SOURCE.

[in, optional] pSrcBox

Jenis: const D3D12_BOX*

Menentukan D3D12_BOX opsional yang mengatur ukuran tekstur sumber untuk disalin.

Nilai kembali

Tidak ada

Keterangan

Kotak sumber harus dalam ukuran sumber daya sumber. Offset tujuan, (x, y, dan z), memungkinkan kotak sumber diimbangi saat menulis ke sumber daya tujuan; namun, dimensi kotak sumber dan offset harus berada dalam ukuran sumber daya. Jika Anda mencoba dan menyalin di luar sumber daya tujuan atau menentukan kotak sumber yang lebih besar dari sumber daya sumber, perilaku CopyTextureRegion tidak terdefinisi. Jika Anda membuat perangkat yang mendukung lapisan debug, output debug melaporkan kesalahan pada panggilan CopyTextureRegion yang tidak valid ini. Parameter yang tidak valid ke CopyTextureRegion menyebabkan perilaku yang tidak terdefinisi dan dapat mengakibatkan penyajian, pengklipan, tidak ada salinan, atau bahkan penghapusan perangkat penyajian yang salah.

Jika sumber daya adalah buffer, semua koordinat berada dalam byte; jika sumber daya adalah tekstur, semua koordinat berada dalam texel.

CopyTextureRegion melakukan salinan pada GPU (mirip memcpy dengan CPU). Sebagai konsekuensinya, sumber daya sumber dan tujuan:

  • Harus subsumber daya yang berbeda (meskipun dapat berasal dari sumber daya yang sama).
  • Harus memiliki DXGI_FORMATyang kompatibel (identik atau dari grup jenis yang sama). Misalnya, tekstur DXGI_FORMAT_R32G32B32_FLOAT dapat disalin ke tekstur DXGI_FORMAT_R32G32B32_UINT karena kedua format ini berada dalam grup DXGI_FORMAT_R32G32B32_TYPELESS. CopyTextureRegion dapat menyalin antara beberapa jenis format. Untuk informasi selengkapnya, lihat Konversi Format menggunakan Direct3D 10.1.
CopyTextureRegion hanya mendukung penyalinan; tidak mendukung peregangan, kunci warna, atau perpaduan apa pun. CopyTextureRegion dapat menginterpretasikan ulang data sumber daya di antara beberapa jenis format.

Perhatikan bahwa untuk buffer stensil kedalaman, bidang kedalaman dan stensil adalah subsumber daya terpisah dalam buffer.

Untuk menyalin seluruh sumber daya, bukan hanya wilayah subsumber daya, sebaiknya gunakan CopyResource sebagai gantinya.

Catatan Jika Anda menggunakan CopyTextureRegion dengan buffer stensil kedalaman atau sumber daya multisampel, Anda harus menyalin seluruh persegi panjang subsumber daya. Dalam situasi ini, Anda harus meneruskan 0 ke parameter DstX, DstY, dan DstZ dan NULL ke parameter pSrcBox . Selain itu, sumber daya sumber dan tujuan, yang diwakili oleh parameter pSrcResource dan pDstResource , harus memiliki nilai jumlah sampel yang identik.
 
CopyTextureRegion dapat digunakan untuk menginisialisasi sumber daya yang alias memori tumpukan yang sama. Lihat CreatePlacedResource untuk detail selengkapnya.

Contoh

Cuplikan kode berikut menyalin kotak (terletak di (120.100),(200.220)) dari tekstur sumber ke wilayah (10.20),(90.140) dalam tekstur tujuan. 
D3D12_BOX sourceRegion;
sourceRegion.left = 120;
sourceRegion.top = 100;
sourceRegion.right = 200;
sourceRegion.bottom = 220;
sourceRegion.front = 0;
sourceRegion.back = 1;

pCmdList -> CopyTextureRegion(pDestTexture, 10, 20, 0, pSourceTexture, &sourceRegion);

Perhatikan, bahwa untuk tekstur 2D, depan dan belakang masing-masing diatur ke 0 dan 1.

Contoh

Sampel HelloTriangle menggunakan ID3D12GraphicsCommandList::CopyTextureRegion sebagai berikut:

inline UINT64 UpdateSubresources(
    _In_ ID3D12GraphicsCommandList* pCmdList,
    _In_ ID3D12Resource* pDestinationResource,
    _In_ ID3D12Resource* pIntermediate,
    _In_range_(0,D3D12_REQ_SUBRESOURCES) UINT FirstSubresource,
    _In_range_(0,D3D12_REQ_SUBRESOURCES-FirstSubresource) UINT NumSubresources,
    UINT64 RequiredSize,
    _In_reads_(NumSubresources) const D3D12_PLACED_SUBRESOURCE_FOOTPRINT* pLayouts,
    _In_reads_(NumSubresources) const UINT* pNumRows,
    _In_reads_(NumSubresources) const UINT64* pRowSizesInBytes,
    _In_reads_(NumSubresources) const D3D12_SUBRESOURCE_DATA* pSrcData)
{
    // Minor validation
    D3D12_RESOURCE_DESC IntermediateDesc = pIntermediate->GetDesc();
    D3D12_RESOURCE_DESC DestinationDesc = pDestinationResource->GetDesc();
    if (IntermediateDesc.Dimension != D3D12_RESOURCE_DIMENSION_BUFFER || 
        IntermediateDesc.Width < RequiredSize + pLayouts[0].Offset || 
        RequiredSize > (SIZE_T)-1 || 
        (DestinationDesc.Dimension == D3D12_RESOURCE_DIMENSION_BUFFER && 
            (FirstSubresource != 0 || NumSubresources != 1)))
    {
        return 0;
    }
    
    BYTE* pData;
    HRESULT hr = pIntermediate->Map(0, NULL, reinterpret_cast<void**>(&pData));
    if (FAILED(hr))
    {
        return 0;
    }
    
    for (UINT i = 0; i < NumSubresources; ++i)
    {
        if (pRowSizesInBytes[i] > (SIZE_T)-1) return 0;
        D3D12_MEMCPY_DEST DestData = { pData + pLayouts[i].Offset, pLayouts[i].Footprint.RowPitch, pLayouts[i].Footprint.RowPitch * pNumRows[i] };
        MemcpySubresource(&DestData, &pSrcData[i], (SIZE_T)pRowSizesInBytes[i], pNumRows[i], pLayouts[i].Footprint.Depth);
    }
    pIntermediate->Unmap(0, NULL);
    
    if (DestinationDesc.Dimension == D3D12_RESOURCE_DIMENSION_BUFFER)
    {
        CD3DX12_BOX SrcBox( UINT( pLayouts[0].Offset ), UINT( pLayouts[0].Offset + pLayouts[0].Footprint.Width ) );
        pCmdList->CopyBufferRegion(
            pDestinationResource, 0, pIntermediate, pLayouts[0].Offset, pLayouts[0].Footprint.Width);
    }
    else
    {
        for (UINT i = 0; i < NumSubresources; ++i)
        {
            CD3DX12_TEXTURE_COPY_LOCATION Dst(pDestinationResource, i + FirstSubresource);
            CD3DX12_TEXTURE_COPY_LOCATION Src(pIntermediate, pLayouts[i]);
            pCmdList->CopyTextureRegion(&Dst, 0, 0, 0, &Src, nullptr);
        }
    }
    return RequiredSize;
}

Lihat Contoh Kode dalam Referensi D3D12.

Persyaratan

Persyaratan Nilai
Target Platform Windows
Header d3d12.h
Pustaka D3d12.lib
DLL D3d12.dll

Lihat juga

CopyBufferRegion

ID3D12GraphicsCommandList