GPUCommandEncoder: copyBufferToTexture() Methode

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, bevor Sie diese produktiv verwenden.

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

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

Syntax

js
copyBufferToTexture(source, destination, copySize)

Parameter

source

Ein Objekt, das den Puffer definiert, von dem kopiert werden soll, sowie das Layout der Daten im Puffer, die in die Textur kopiert werden sollen. Zusammen mit copySize definiert es den Bereich des Quellpuffers. source kann die folgenden Eigenschaften haben:

buffer

Der GPUBuffer, von dem kopiert werden soll.

offset Optional

Der Versatz in Bytes vom Anfang der data bis zum Start der zu kopierenden Bilddaten. Falls nicht angegeben, beträgt der Standardwert von offset 0.

bytesPerRow Optional

Eine Zahl, die den Abstand in Bytes zwischen dem Anfang jeder Blockreihe (d.h. einer Reihe vollständiger Texelblöcke) und der darauffolgenden 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 Bild innerhalb der Daten. bytesPerRow × rowsPerImage ergibt den Abstand in Bytes zwischen dem Anfang jedes vollständigen Bildes. Dies ist erforderlich, wenn mehrere Bilder kopiert werden sollen.

destination

Ein Objekt, das die Textur definiert, wohin die Daten geschrieben werden sollen. Zusammen mit copySize definiert es den Bereich der Zieltextursubressource. destination kann die folgenden Eigenschaften haben:

aspect Optional

Ein enumerierter Wert, der definiert, welche Aspekte der Textur mit den Daten beschrieben werden sollen. Mögliche Werte sind:

"all"

Alle verfügbaren Aspekte des Texturformats werden beschrieben, was je nach Format alle oder einige der folgenden umfassen kann: Farbe, Tiefe und Schablone.

"depth-only"

Nur der Tiefenaspekt eines Tiefen- oder Schablonenformats wird beschrieben.

"stencil-only"

Nur der Schablonaspekt eines Tiefen- oder Schablonenformats wird beschrieben.

Falls nicht angegeben, nimmt aspect den Wert "all" an.

mipLevel Optional

Eine Zahl, die die Mip-Map-Ebene der Textur darstellt, zu der die Daten geschrieben werden sollen. Falls nicht angegeben, beträgt der Standardwert von mipLevel 0.

origin Optional

Ein Objekt oder Array, das den Ursprung der Kopie angibt — die minimale Ecke der Texturregion, zu der die Daten geschrieben werden sollen. Zusammen mit size definiert dies das gesamte Ausmaß des Bereichs, der beschrieben werden soll. Wenn einer oder alle Werte von origin ausgelassen werden, nehmen x, y und z den Standardwert von 0 an.

Im Folgenden ist ein Beispiel-Array dargestellt:

js
[0, 0, 0];

Das entsprechende Objekt sieht folgendermaßen aus:

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

Ein GPUTexture-Objekt, das die Textur darstellt, zu der die Daten geschrieben werden sollen.

copySize

Ein Objekt oder Array, das die Breite, Höhe und Tiefen-/Array-Ebenenzahl der kopierten Daten angibt. Der Breitenwert muss immer angegeben werden, während die Höhen- und Tiefen-/Array-Ebenenzählwerte optional sind und, wenn ausgelassen, standardmäßig 1 betragen.

Im Folgenden ist ein Beispiel-copySize-Array dargestellt:

js
[16, 16, 2];

Das entsprechende Objekt sieht folgendermaßen aus:

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

Rückgabewert

Keiner (Undefined).

Validierung

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

Für die source:

  • source.bytesPerRow ist ein Vielfaches von 256.
  • Der source.buffer's GPUBuffer.usage enthält das GPUBufferUsage.COPY_SRC-Flag.

Für die destination:

Beispiele

js
commandEncoder.copyBufferToTexture(
  {
    buffer: sourceBuffer,
  },
  {
    texture: destinationTexture,
  },
  {
    width: 16,
    height: 16,
    depthOrArrayLayers: 2,
  },
);

Spezifikationen

Specification
WebGPU
# dom-gpucommandencoder-copybuffertotexture

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch