GPUCommandEncoder: Methode copyTextureToBuffer()

source

Ein Objekt, das die Textur definiert, von der die Daten kopiert werden. In Kombination mit copySize definiert es den Bereich der Quell-Textur-Subressource. source kann die folgenden Eigenschaften haben:

aspect Optional

Ein enumerierter Wert, der angibt, welche Aspekte der Textur kopiert werden sollen. Mögliche Werte sind:

"all"

Alle verfügbaren Aspekte des Texturformats werden kopiert, was je nach Art des Formats alle oder einige der Farb-, Tiefen- und Stencil-Aspekte sein können.

"depth-only"

Nur der Tiefenaspekt eines Tiefen-oder-Stencil-Formats wird kopiert.

"stencil-only"

Nur der Stencil-Aspekt eines Tiefen-oder-Stencil-Formats wird kopiert.

Wenn weggelassen, nimmt aspect den Wert "all" an.

mipLevel Optional

Eine Zahl, die die Mip-Map-Ebene der Textur darstellt, von der die Daten kopiert werden. Wird mipLevel weggelassen, wird es standardmäßig auf 0 gesetzt.

origin Optional

Ein Objekt oder Array, das den Ursprung des Kopierens spezifiziert — die minimale Ecke des Texturbereichs, von dem die Daten kopiert werden. Zusammen mit size definiert dies den gesamten zu kopierenden Bereich. Die Werte x, y und z werden auf 0 gesetzt, wenn origin in Teilen oder vollständig ausgelassen wird.

Hier ist ein Beispiel für ein Array:

js

[0, 0, 0];

Das entsprechende Objekt würde so aussehen:

js

{
  x: 0,
  y: 0,
  z: 0
}

texture

Ein GPUTexture-Objekt, das die Textur darstellt, von der die Daten kopiert werden.

destination

Ein Objekt, das definiert, zu welchem Puffer geschrieben wird, sowie das Layout der zu schreibenden Daten in den Puffer. In Kombination mit copySize definiert es den Bereich des Zielpuffers. source kann die folgenden Eigenschaften haben:

buffer

Der GPUBuffer, in den geschrieben werden soll.

offset Optional

Der Offset in Bytes vom Beginn der data bis zur Startposition, an der die kopierten Daten geschrieben werden sollen. Wird offset weggelassen, wird es standardmäßig auf 0 gesetzt.

bytesPerRow Optional

Eine Zahl, die die Distanz in Bytes zwischen dem Beginn jeder Blockreihe (d. h. einer Reihe vollständiger Texelblöcke) und der darauf folgenden Blockreihe angibt. Dies ist erforderlich, wenn mehrere Blockreihen vorhanden sind (d. h. die Kopierhöhe oder -tiefe beträgt mehr als einen Block).

rowsPerImage Optional

Die Anzahl der Blockreihen pro einzelnes Bild innerhalb der Daten. bytesPerRow × rowsPerImage gibt Ihnen die Distanz in Bytes zwischen dem Beginn jedes vollständigen Bildes. Dies ist erforderlich, wenn mehrere Bilder kopiert werden sollen.

copySize

Ein Objekt oder Array, das die Breite, Höhe und Tiefe/Array-Lagenschichtenanzahl der kopierten Daten spezifiziert. Der Breitenwert muss immer angegeben werden, während die Höhen- und Tiefen-/Array-Lagenschichtenanzahl optional sind und, wenn nicht angegeben, standardmäßig auf 1 gesetzt werden.

Hier ist ein Beispiel für ein copySize-Array:

js

[16, 16, 2];

Das entsprechende Objekt würde so aussehen:

js

{
  width: 16,
  height: 16,
  depthOrArrayLayers: 2
}

Keiner (Undefined).

Die folgenden Kriterien müssen beim Aufruf von copyTextureToBuffer() erfüllt sein, andernfalls wird ein GPUValidationError erzeugt und der GPUCommandEncoder wird ungültig.

Für die source:

• mipLevel ist kleiner als die GPUTexture.mipLevelCount.
• origin.x ist ein Vielfaches der Texelblockbreite des GPUTexture.format.
• origin.y ist ein Vielfaches der Texelblockhöhe des GPUTexture.format.
• Wenn das GPUTexture.format ein Tiefen-oder-Stencil-Format ist oder GPUTexture.sampleCount mehr als 1 ist, ist die Subressourcengröße gleich size.
• Die GPUTexture.usage der source enthält das GPUTextureUsage.COPY_SRC-Flag.
• Die GPUTexture.sampleCount der source ist 1.
• source.aspect bezieht sich auf einen einzelnen Aspekt des GPUTexture.format.
• Dieser Aspekt ist eine gültige Bildkopierquelle gemäß den Tiefen-oder-Stencil-Formaten.
• Die source ist mit der copySize kompatibel.

Für die destination:

• destination.bytesPerRow ist ein Vielfaches von 256.
• Die GPUBuffer.usage des destination.buffer enthält das GPUBufferUsage.COPY_DST-Flag.

• Die WebGPU API