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 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 copyBufferToTexture()-Methode der GPUCommandEncoder-Schnittstelle kodiert einen Befehl, der Daten von einem GPUBuffer zu einer GPUTexture kopiert.

Ein Objekt, das den Puffer definiert, aus 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, aus dem kopiert werden soll.
offset Optional: Der Offset in Bytes vom Anfang von data bis zum Beginn der zu kopierenden Bilddaten. Wenn nicht angegeben, ist offset standardmäßig 0.
bytesPerRow Optional: Eine Zahl, die die Größe in Bytes zwischen dem Beginn jeder Blockzeile (d.h. einer Zeile vollständiger Texelblöcke) und der nachfolgenden Blockzeile angibt. Dies ist erforderlich, wenn es mehrere Blockzeilen gibt (d.h. die Kopierhöhe oder -tiefe ist mehr als ein Block).
rowsPerImage Optional: Die Anzahl der Blockzeilen pro Bild innerhalb der Daten. bytesPerRow × rowsPerImage gibt Ihnen die Größe in Bytes zwischen dem Beginn jedes vollständigen Bildes. Dies ist erforderlich, wenn mehrere Bilder kopiert werden sollen.

destination

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

aspect Optional

Ein enumerierter Wert, der definiert, auf welche Aspekte der Textur die Daten geschrieben werden sollen. Mögliche Werte sind:

"all": Alle verfügbaren Aspekte des Texturformats werden beschrieben, was je nach Format alle oder einige der Aspekte Farbe, Tiefe und Stencil umfassen kann.
"depth-only": Es wird nur der Tiefe-Aspekt eines Tiefen- oder Stencil-Formats beschrieben.
"stencil-only": Es wird nur der Stencil-Aspekt eines Tiefen- oder Stencil-Formats beschrieben.

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

mipLevel Optional

Eine Zahl, die die Mip-Map-Ebene der Textur angibt, in die die Daten geschrieben werden sollen. Wenn nicht angegeben, ist mipLevel standardmäßig 0.

origin Optional

Ein Objekt oder Array, das den Ursprung der Kopie angibt — die minimale Ecke des Texturbereichs, in den die Daten geschrieben werden sollen. Zusammen mit size definiert dies den vollständigen Umfang des Bereichs, der kopiert werden soll. Die x-, y- und z-Werte sind standardmäßig 0, wenn Teile oder alle von origin nicht angegeben sind.

Zum Beispiel können Sie ein Array wie [0, 0, 0] oder das äquivalente Objekt { x: 0, y: 0, z: 0 } übergeben.

texture

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

copySize

Ein Objekt oder Array, das die Breite, Höhe und Tiefe/Array-Schichtanzahl der kopierten Daten spezifiziert. Der Breitenwert muss immer angegeben werden, während die Werte für die Höhe und die Tiefe/Array-Schichtanzahl optional sind und standardmäßig 1 sind, wenn nicht angegeben.

Zum Beispiel können Sie ein Array [16, 16, 2] oder das äquivalente Objekt { width: 16, height: 16, depthOrArrayLayers: 2 } übergeben.

Rückgabewert

Keiner (Undefined).

Validierung

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

Für den source:

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

Für den destination:

mipLevel ist kleiner als der 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 der GPUTexture.sampleCount mehr als 1 ist, ist die Unterressourcengröße gleich size.
Der GPUTexture.usage des destination enthält das GPUTextureUsage.COPY_DST-Flag.
Der GPUTexture.sampleCount des destination ist 1.
destination.aspect bezieht sich auf einen einzelnen Aspekt des GPUTexture.format.
Dieser Aspekt ist ein gültiges Ziel für das Kopieren von Bildern gemäß Tiefen- oder Stencil-Formaten.
Das destination ist mit der copySize kompatibel.

Beispiele

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

Spezifikationen

Specification
WebGPU # dom-gpucommandencoder-copybuffertotexture

Browser-Kompatibilität

Siehe auch

Die WebGPU API