ID3D12GraphicsCommandList::CopyTextureRegion-Methode (d3d12.h)

  • Artikel

Diese Methode verwendet die GPU, um Texturdaten zwischen zwei Speicherorten zu kopieren. Sowohl die Quelle als auch das Ziel können auf Texturdaten verweisen, die sich in einer Pufferressource oder einer Texturressource befinden.

Syntax

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

Typ: const D3D12_TEXTURE_COPY_LOCATION*

Gibt die Ziel-D3D12_TEXTURE_COPY_LOCATION an. Die untere Quelle, auf die verwiesen wird, muss sich im zustand D3D12_RESOURCE_STATE_COPY_DEST befinden.

DstX

Typ: UINT

Die x-Koordinate der oberen linken Ecke des Zielbereichs.

DstY

Typ: UINT

Die y-Koordinate der oberen linken Ecke des Zielbereichs. Für eine 1D-Unterressource muss dies null sein.

DstZ

Typ: UINT

Die Z-Koordinate der oberen linken Ecke des Zielbereichs. Bei einer 1D- oder 2D-Unterressource muss dies null sein.

[in] pSrc

Typ: const D3D12_TEXTURE_COPY_LOCATION*

Gibt den quell-D3D12_TEXTURE_COPY_LOCATION an. Die Unterressource, auf die verwiesen wird, muss sich im D3D12_RESOURCE_STATE_COPY_SOURCE Zustand befinden.

[in, optional] pSrcBox

Typ: const D3D12_BOX*

Gibt einen optionalen D3D12_BOX an, der die Größe der zu kopierenden Quelltextur festlegt.

Rückgabewert

Keine

Bemerkungen

Das Quellfeld muss innerhalb der Größe der Quellressource sein. Mit den Zieloffsets (x, y und z) kann das Quellfeld beim Schreiben in die Zielressource versetzt werden. Die Dimensionen des Quellfelds und die Offsets müssen jedoch innerhalb der Größe der Ressource sein. Wenn Sie versuchen, außerhalb der Zielressource zu kopieren oder ein Quellfeld anzugeben, das größer als die Quellressource ist, ist das Verhalten von CopyTextureRegion nicht definiert. Wenn Sie ein Gerät erstellt haben, das die Debugebene unterstützt, meldet die Debugausgabe einen Fehler bei diesem ungültigen CopyTextureRegion-Aufruf . Ungültige Parameter für CopyTextureRegion führen zu undefiniertem Verhalten und können zu falschem Rendering, Clipping, keine Kopie oder sogar zum Entfernen des Renderinggeräts führen.

Wenn es sich bei den Ressourcen um Puffer handelt, sind alle Koordinaten in Byte; Wenn es sich bei den Ressourcen um Texturen handelt, befinden sich alle Koordinaten in Texel.

CopyTextureRegion führt die Kopie auf der GPU aus (ähnlich wie bei der memcpy CPU). Daher führen die Quell- und Zielressourcen wie folgt aus:

  • Müssen unterschiedliche Unterressourcen sein (obwohl sie aus derselben Ressource stammen können).
  • Muss über kompatible DXGI_FORMATverfügen (identisch oder aus derselben Typgruppe). Beispielsweise kann eine DXGI_FORMAT_R32G32B32_FLOAT Textur in eine DXGI_FORMAT_R32G32B32_UINT Textur kopiert werden, da sich beide Formate in der gruppe DXGI_FORMAT_R32G32B32_TYPELESS befinden. CopyTextureRegion kann zwischen einigen Formattypen kopiert werden. Weitere Informationen finden Sie unter Formatkonvertierung mit Direct3D 10.1.
CopyTextureRegion unterstützt nur Das Kopieren. Es unterstützt keine Stretch-, Farbtasten- oder Blend-Elemente. CopyTextureRegion kann die Ressourcendaten zwischen einigen Formattypen neu interpretieren.

Beachten Sie, dass für einen Tiefenschablonenpuffer die Tiefen- und Schablonenebene separate Unterressourcen innerhalb des Puffers sind.

Zum Kopieren einer gesamten Ressource und nicht nur einer Region einer Unterressource wird stattdessen copyResource empfohlen.

Hinweis Wenn Sie CopyTextureRegion mit einem Tiefenschablonenpuffer oder einer Mehrfachsamplingressource verwenden, müssen Sie das gesamte Unterressourcenrechteck kopieren. In diesem Fall müssen Sie 0 an die Parameter DstX, DstY und DstZ und NULL an den Parameter pSrcBox übergeben. Darüber hinaus sollten Quell- und Zielressourcen, die durch die Parameter pSrcResource und pDstResource dargestellt werden, identische Stichprobenanzahlwerte aufweisen.
 
CopyTextureRegion kann verwendet werden, um Ressourcen zu initialisieren, die denselben Heapspeicher aufweisen. Weitere Informationen finden Sie unter CreatePlacedResource .

Beispiel

Der folgende Codeausschnitt kopiert das Feld (bei (120,100),(200,220)) aus einer Quelltextur in die Region (10,20),(90,140) in einer Zieltextur. 
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);

Beachten Sie, dass für eine 2D-Textur die Vorder- und Rückseite auf 0 bzw. 1 festgelegt sind.

Beispiele

Im HelloTriangle-Beispiel wird ID3D12GraphicsCommandList::CopyTextureRegion wie folgt verwendet:

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

Weitere Informationen finden Sie unter Beispielcode in der D3D12-Referenz.

Anforderungen

Anforderung Wert
Zielplattform Windows
Kopfzeile d3d12.h
Bibliothek D3d12.lib
DLL D3d12.dll

Weitere Informationen

CopyBufferRegion

ID3D12GraphicsCommandList