GPUCommandEncoder: copyTextureToBuffer() Methode

Limited availability

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

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 kodiert einen Befehl, der Daten von einer GPUTexture in einen GPUBuffer kopiert.

Ein Objekt, das die Textur definiert, aus der die Daten kopiert werden. In Kombination mit copySize definiert es den Bereich der Quelltextur-Subressource. 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 alle oder beliebige von Farbe, Tiefe und Stencil bedeuten kann, abhängig vom verwendeten Format.
"depth-only": Nur der Tiefenaspekt eines depth-or-stencil format wird kopiert.
"stencil-only": Nur der Stencil-Aspekt eines depth-or-stencil format wird kopiert.

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

mipLevel Optional

Eine Zahl, die die Mip-Map-Ebene der Textur darstellt, aus der die Daten kopiert werden sollen. Wenn ausgelassen, wird mipLevel auf 0 festgelegt.

origin Optional

Ein Objekt oder Array, das den Ursprung der Kopie angibt — die minimalen Ecken des Texturbereichs, aus dem die Daten kopiert werden sollen. Zusammen mit size definiert dies das gesamte Ausmaß des zu kopierenden Bereichs. Die Werte x, y und z werden auf 0 festgelegt, wenn ein Teil von origin weggelassen wird.

Beispielsweise können Sie ein Array [0, 0, 0] oder das entsprechende Objekt { x: 0, y: 0, z: 0 } übergeben.

texture

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

destination

Ein Objekt, das den Puffer definiert, in den geschrieben werden soll, sowie das Layout der Daten, die in den Puffer geschrieben werden sollen. 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 Versatz, in Bytes, vom Beginn von data zur Startposition, an die die kopierten Daten geschrieben werden sollen. Wenn ausgelassen, wird offset auf 0 festgelegt.
bytesPerRow Optional: Eine Zahl, die den Abstand, in Bytes, zwischen dem Beginn jeder Blockreihe (d.h. einer Reihe vollständiger Texelblöcke) und der folgenden Blockreihe darstellt. Dies ist erforderlich, wenn es mehrere Blockreihen gibt (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 Ihnen den Abstand, 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 die Tiefe/Array-Ebenenzahl der kopierten Daten angibt. Der Breitenwert muss immer angegeben werden, während die Höhen- und Tiefen/Array-Ebenenzahl-Werte optional sind und, wenn weggelassen, auf 1 festgelegt werden.

Beispielsweise können Sie ein Array [16, 16, 2] oder das entsprechende 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 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 depth-or-stencil format ist oder GPUTexture.sampleCount mehr als 1 ist, ist die Subressourcengröße gleich size.
Der source-GPUTexture.usage](/de/docs/Web/API/GPUTexture/usage) enthält das GPUTextureUsage.COPY_SRC Flag.
Der source-GPUTexture.sampleCount](/de/docs/Web/API/GPUTexture/sampleCount) ist 1.
source.aspect bezieht sich auf einen einzelnen Aspekt des GPUTexture.format.
Dieser Aspekt ist eine gültige Bildkopiequelle gemäß depth-or-stencil formats.
Der source ist kompatibel mit der copySize.

Für die destination:

destination.bytesPerRow ist ein Vielfaches von 256.
Der destination.buffer-GPUBuffer.usage](/de/docs/Web/API/GPUBuffer/usage) enthält das GPUBufferUsage.COPY_DST Flag.

Beispiele

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