GPUCommandEncoder: Methode copyTextureToBuffer()

Eingeschränkt verfügbar

Diese Funktion ist nicht Baseline, da sie in einigen der am weitesten verbreiteten Browser nicht funktioniert.

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

Die Methode copyTextureToBuffer() des GPUCommandEncoder-Interfaces kodiert einen Befehl, der Daten von einer GPUTexture in einen GPUBuffer kopiert.

Ein Objekt, das die Textur definiert, von der die Daten kopiert werden. Zusammen mit copySize definiert es den Bereich der Quellentextur-Teilressource. source kann die folgenden Eigenschaften haben:

aspect Optional

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

"all": Alle verfügbaren Aspekte des Texturformats werden kopiert, was je nach Format alle oder beliebige von Farbe, Tiefe und Stencil bedeuten kann.
"depth-only": Nur der Tiefenaspekt eines Depth-or-Stencil-Formats wird kopiert.
"stencil-only": Nur der Stencil-Aspekt eines Depth-or-Stencil-Formats wird kopiert.

Wenn weggelassen, hat aspect den Wert "all".

mipLevel Optional

Eine Zahl, die die Mip-Map-Stufe der Textur darstellt, von der die Daten kopiert werden. Wenn weggelassen, ist der Standardwert von mipLevel 0.

origin Optional

Ein Objekt oder Array, das den Ursprung des Kopiervorgangs spezifiziert — die minimale Ecke des Texturbereichs, von dem die Daten kopiert werden. Zusammen mit size definiert dies den gesamten Umfang des zu kopierenden Bereichs. Die Werte x, y und z sind 0, wenn jegliche Komponenten von origin weggelassen werden.

Sie können beispielsweise ein Array [0, 0, 0] oder sein äquivalentes Objekt { x: 0, y: 0, z: 0 } übergeben.

texture

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

destination

Ein Objekt, das den Buffer definiert, in den geschrieben wird, sowie das Layout der zu schreibenden Daten. Zusammen mit copySize definiert es den Bereich des Ziel-Buffers. source kann die folgenden Eigenschaften haben:

buffer: Der GPUBuffer, in den geschrieben wird.
offset Optional: Der Versatz in Bytes vom Anfang der data zur Startposition, an die die kopierten Daten geschrieben werden. Wenn weggelassen, beträgt der Standardwert für offset 0.
bytesPerRow Optional: Eine Zahl, die die Schrittweite in Bytes zwischen dem Beginn jeder Blockreihe (d.h. einer Reihe kompletter Texelblöcke) und der nachfolgenden Blockreihe darstellt. Dies ist erforderlich, wenn mehrere Blockreihen vorhanden sind (d.h. die Kopierhöhe oder -tiefe ist mehr als ein Block).
rowsPerImage Optional: Die Anzahl der Blockreihen pro einzelnes Bild innerhalb der Daten. bytesPerRow × rowsPerImage gibt den Abstand in Bytes zwischen dem Beginn jedes vollständigen Bildes an. Dies ist erforderlich, wenn mehrere Bilder kopiert werden sollen.

copySize

Ein Objekt oder Array, das die Breite, Höhe und Tiefe/Anzahl von Array-Schichten der kopierten Daten spezifiziert. Der Wert der Breite muss immer angegeben werden, während die Werte für Höhe und Tiefe/Anzahl von Array-Schichten optional sind und auf 1 standardmäßig gesetzt werden, wenn sie weggelassen werden.

Sie können beispielsweise ein Array [16, 16, 2] oder dessen äquivalentes Objekt { width: 16, height: 16, depthOrArrayLayers: 2 } übergeben.

Rückgabewert

Keiner (undefined).

Validierung

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

Für source:

mipLevel ist kleiner als der GPUTexture.mipLevelCount.
origin.x ist ein Vielfaches der Texelblock-Breite des GPUTexture.format.
origin.y ist ein Vielfaches der Texelblock-Höhe des GPUTexture.format.
Wenn das GPUTexture.format ein Depth-or-Stencil-Format ist oder GPUTexture.sampleCount mehr als 1 ist, muss die Größe der Teilressource gleich size sein.
Die source-Eigenschaft GPUTexture.usage enthält das GPUTextureUsage.COPY_SRC-Flag.
Die source-Eigenschaft GPUTexture.sampleCount ist 1.
source.aspect bezieht sich auf einen einzigen Aspekt des GPUTexture.format.
Dieser Aspekt ist eine gültige Bildkopierquelle gemäß Depth-or-Stencil-Formaten.
Die source ist mit copySize kompatibel.

Für destination:

destination.bytesPerRow ist ein Vielfaches von 256.
Der destination.buffer-Eigenschaft GPUBuffer.usage enthält das GPUBufferUsage.COPY_DST-Flag.

Beispiele

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