Metodo ID3D12GraphicsCommandList::CopyTextureRegion (d3d12.h)

Questo metodo usa la GPU per copiare i dati della trama tra due posizioni. Sia l'origine che la destinazione possono fare riferimento ai dati della trama all'interno di una risorsa buffer o di una risorsa trama.

Sintassi

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

Parametri

[in] pDst

Tipo: const D3D12_TEXTURE_COPY_LOCATION*

Specifica la D3D12_TEXTURE_COPY_LOCATION di destinazione. La sottoresource a cui si fa riferimento deve trovarsi nello stato D3D12_RESOURCE_STATE_COPY_DEST.

DstX

Tipo: UINT

Coordinata x dell'angolo superiore sinistro dell'area di destinazione.

DstY

Tipo: UINT

Coordinata y dell'angolo superiore sinistro dell'area di destinazione. Per una sottoresource 1D, questo deve essere zero.

DstZ

Tipo: UINT

Coordinata z dell'angolo superiore sinistro dell'area di destinazione. Per una sottoresource 1D o 2D, questo deve essere zero.

[in] pSrc

Tipo: const D3D12_TEXTURE_COPY_LOCATION*

Specifica l'D3D12_TEXTURE_COPY_LOCATION di origine. La sottoresource a cui si fa riferimento deve trovarsi nello stato D3D12_RESOURCE_STATE_COPY_SOURCE.

[in, optional] pSrcBox

Tipo: const D3D12_BOX*

Specifica un D3D12_BOX facoltativo che imposta le dimensioni della trama di origine da copiare.

Valore restituito

nessuno

Osservazioni

La casella di origine deve essere compresa nella dimensione della risorsa di origine. Gli offset di destinazione, (x, y e z), consentono la offset della casella di origine durante la scrittura nella risorsa di destinazione; tuttavia, le dimensioni della casella di origine e gli offset devono essere entro le dimensioni della risorsa. Se si tenta di copiare e copiare all'esterno della risorsa di destinazione o specificare una casella di origine maggiore della risorsa di origine, il comportamento di CopyTextureRegion non è definito. Se è stato creato un dispositivo che supporta il livello di debug, l'output di debug segnala un errore in questa chiamata CopyTextureRegion non valida. I parametri non validi per CopyTextureRegion causano un comportamento non definito e potrebbero causare un rendering errato, ritaglio, nessuna copia o anche la rimozione del dispositivo di rendering.

Se le risorse sono buffer, tutte le coordinate sono in byte; se le risorse sono trame, tutte le coordinate sono in texel.

CopyTextureRegion esegue la copia sulla GPU (simile a una memcpy dalla CPU). Di conseguenza, le risorse di origine e destinazione:

  • Devono essere diverse sottoresource (anche se possono essere dalla stessa risorsa).
  • Deve essere compatibile DXGI_FORMATs (identico o dallo stesso gruppo di tipi). Ad esempio, una trama DXGI_FORMAT_R32G32B32_FLOAT può essere copiata in una trama DXGI_FORMAT_R32G32B32_UINT poiché entrambi questi formati si trovano nel gruppo DXGI_FORMAT_R32G32B32_TYPELESS. CopyTextureRegion può copiare tra alcuni tipi di formato. Per altre informazioni, vedere Conversione del formato con Direct3D 10.1.
CopyTextureRegion supporta solo la copia; non supporta alcuna estensione, chiave di colore o miscela. CopyTextureRegion può reinterpretare i dati delle risorse tra alcuni tipi di formato.

Si noti che per un buffer a stencil di profondità, i piani di profondità e stencil sono risorse secondarie separate all'interno del buffer.

Per copiare un'intera risorsa, anziché solo un'area di una sottoresource, è consigliabile usare invece CopyResource .

Nota Se si usa CopyTextureRegion con un buffer depth-stencil o una risorsa multisampled, è necessario copiare l'intero rettangolo di sottoresource. In questa situazione, è necessario passare 0 ai parametri DstX, DstY e DstZ e NULL al parametro pSrcBox. Inoltre, le risorse di origine e di destinazione, rappresentate dai parametri pSrcResource e pDstResource , devono avere valori di conteggio di esempio identici.
 
CopyTextureRegion può essere usato per inizializzare le risorse che aliasno la stessa memoria heap. Per altre informazioni, vedere CreatePlacedResource .

Esempio

Il frammento di codice seguente copia la casella (situata in (120.100),(200.220)) da una trama di origine nell'area (10.20),(90.140) in una trama di destinazione.
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);

Si noti che per una trama 2D, la parte anteriore e posteriore sono impostate rispettivamente su 0 e 1.

Esempio

L'esempio HelloTriangle usa ID3D12GraphicsCommandList::CopyTextureRegion come indicato di seguito:

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;
}

Vedere Codice di esempio nel riferimento D3D12.

Requisiti

Requisito Valore
Piattaforma di destinazione Windows
Intestazione d3d12.h
Libreria D3d12.lib
DLL D3d12.dll

Vedi anche

CopyBufferRegion

ID3D12GraphicsCommandList