GPUCommandEncoder: Methode copyTextureToBuffer()

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

Experimentell: Dies ist eine experimentelle Technologie
Überprüfen Sie die Browser-Kompatibilitätstabelle sorgfältig vor der Verwendung auf produktiven Webseiten.

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Die copyTextureToBuffer()-Methode der GPUCommandEncoder-Schnittstelle codiert einen Befehl, der Daten von einer GPUTexture zu einem GPUBuffer kopiert.

Syntax

js
copyTextureToBuffer(source, destination, copySize)

Parameter

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
}

Rückgabewert

Keiner (Undefined).

Validierung

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:

Für die destination:

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

Beispiele

js
commandEncoder.copyTextureToBuffer(
  {
    texture: sourceTexture,
  },
  {
    buffer: destinationBuffer,
  },
  {
    width: 16,
    height: 16,
    depthOrArrayLayers: 2,
  },
);

Spezifikationen

Specification
WebGPU
# dom-gpucommandencoder-copytexturetobuffer

Browser-Kompatibilität

Report problems with this compatibility data on GitHub
desktopmobileserver
Chrome
Edge
Firefox
Opera
Safari
Chrome Android
Firefox for Android
Opera Android
Safari on iOS
Samsung Internet
WebView Android
WebView on iOS
Deno
copyTextureToBuffer
Experimental

Legend

Tip: you can click/tap on a cell for more information.

Full support
Full support
Partial support
Partial support
In development. Supported in a pre-release version.
In development. Supported in a pre-release version.
No support
No support
Experimental. Expect behavior to change in the future.
See implementation notes.
User must explicitly enable this feature.
Has more compatibility info.

Siehe auch