ID3D11DeviceContext::CopySubresourceRegion-Methode (d3d11.h)

  • Artikel

Kopieren Sie eine Region aus einer Quellressource in eine Zielressource.

Syntax

void CopySubresourceRegion(
  [in]           ID3D11Resource  *pDstResource,
  [in]           UINT            DstSubresource,
  [in]           UINT            DstX,
  [in]           UINT            DstY,
  [in]           UINT            DstZ,
  [in]           ID3D11Resource  *pSrcResource,
  [in]           UINT            SrcSubresource,
  [in, optional] const D3D11_BOX *pSrcBox
);

Parameter

[in] pDstResource

Typ: ID3D11Resource*

Ein Zeiger auf die Zielressource (siehe ID3D11Resource).

[in] DstSubresource

Typ: UINT

Zielunterressourcenindex.

[in] DstX

Typ: UINT

Die x-Koordinate der oberen linken Ecke des Zielbereichs.

[in] DstY

Typ: UINT

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

[in] DstZ

Typ: UINT

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

[in] pSrcResource

Typ: ID3D11Resource*

Ein Zeiger auf die Quellressource (siehe ID3D11Resource).

[in] SrcSubresource

Typ: UINT

Quellunterressourcenindex.

[in, optional] pSrcBox

Typ: const D3D11_BOX*

Ein Zeiger auf ein 3D-Feld (siehe D3D11_BOX), das die zu kopierende Quellunterressource definiert. Bei NULL wird die gesamte Quellunterressource kopiert. Das Feld muss in die Quellressource passen.

Ein leeres Feld führt zu einem No-Op. Ein Feld ist leer, wenn der obere Wert größer oder gleich dem unteren Wert oder der linke Wert größer oder gleich dem rechten Wert ist oder der vordere Wert größer oder gleich dem back-Wert ist. Wenn das Feld leer ist, führt CopySubresourceRegion keinen Kopiervorgang aus.

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 CopySubresourceRegion nicht definiert. Wenn Sie ein Gerät erstellt haben, das die Debugebene unterstützt, meldet die Debugausgabe einen Fehler für diesen ungültigen CopySubresourceRegion-Aufruf . Ungültige Parameter für CopySubresourceRegion führen zu undefiniertem Verhalten und können zu falschem Rendering, Clipping, keinem Kopieren 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. D3D11CalcSubresource ist eine Hilfsfunktion zum Berechnen von Unterressourcenindizes.

CopySubresourceRegion führt die Kopie auf der GPU aus (ähnlich einem Memcpy durch die 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 der gleiche Typ sein.
  • Muss über kompatible DXGI-Formate verfü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. CopySubresourceRegion kann zwischen einigen Formattypen kopiert werden. Weitere Informationen finden Sie unter Formatkonvertierung mit Direct3D 10.1.
  • Möglicherweise wird derzeit nicht zugeordnet.
**CopySubresourceRegion** unterstützt nur Das Kopieren; Es unterstützt keine Stretch-, Farbtasten oder Blenden. **CopySubresourceRegion** kann die Ressourcendaten zwischen einigen Formattypen neu interpretieren. Weitere Informationen finden Sie unter [Formatkonvertierung mit Direct3D 10.1](/windows/win32/direct3d10/d3d10-graphics-programming-guide-resources-block-compression#format-conversion-using-direct3d-101).

Wenn Ihre App eine gesamte Ressource kopieren muss, wird empfohlen, stattdessen ID3D11DeviceContext::CopyResource zu verwenden.

CopySubresourceRegion ist ein asynchroner Aufruf, der der Befehlspufferwarteschlange hinzugefügt werden kann. Dadurch wird versucht, Pipeline-Stags zu entfernen, die beim Kopieren von Daten auftreten können. Weitere Informationen zu Pipelinestags finden Sie unter Überlegungen zur Leistung.

HinweisGilt nur für Hardware auf Featureebene 9_x Wenn Sie ID3D11DeviceContext::UpdateSubresource oder CopySubresourceRegion verwenden, um von einer Stagingressource in eine Standardressource zu kopieren, können Sie den Zielinhalt beschädigen. Dies tritt auf, wenn Sie ein NULL-Quellfeld übergeben und die Quellressource andere Dimensionen als die der Zielressource aufweist oder wenn Sie Zieloffsets (x, y und z) verwenden. Übergeben Sie in diesem Fall immer ein Quellfeld, das der vollständigen Größe der Quellressource entspricht.
 
HinweisGilt nur für Featureebene 9_x Hardware Sie können CopySubresourceRegion nicht verwenden, um mipmappenbasierte Volumetexturen zu kopieren.
 
HinweisGilt nur für Featureebenen 9_x Mit dem Flag D3D11_BIND_DEPTH_STENCIL erstellte Unterressourcen können nur als Quelle für CopySubresourceRegion verwendet werden.
 
Hinweis Wenn Sie CopySubresourceRegion mit einem Tiefenschablonenpuffer oder einer Multisampled-Ressource verwenden, müssen Sie die gesamte Unterressource 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.
 

Beispiel

Der folgende Codeausschnitt kopiert ein Feld (bei (120,100),(200,220)) aus einer Quelltextur in einen Bereich (10,20),(90,140) in einer Zieltextur. 
D3D11_BOX sourceRegion;
sourceRegion.left = 120;
sourceRegion.right = 200;
sourceRegion.top = 100;
sourceRegion.bottom = 220;
sourceRegion.front = 0;
sourceRegion.back = 1;

pd3dDeviceContext->CopySubresourceRegion( pDestTexture, 0, 10, 20, 0, pSourceTexture, 0, &sourceRegion );

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

Anforderungen

Anforderung Wert
Zielplattform Windows
Kopfzeile d3d11.h
Bibliothek D3D11.lib

Weitere Informationen

ID3D11DeviceContext

ID3D11Resource