</> programmierung.net
Start · Sprachen · JavaScript · Referenz · GPUCommandEncoder.copyTextureToBuffer()

GPUCommandEncoder.copyTextureToBuffer()

Methode

Zeichnet einen Befehl auf, der einen Bereich einer <code>GPUTexture</code> in einen <code>GPUBuffer</code> kopiert, etwa um GPU-Ergebnisse auf der CPU auszulesen.

seit JavaScript WebGPU: Chrome/Edge 113+, Firefox 141+ (Windows), Kategorie: webapi

Signatur

GPUCommandEncoder.prototype.copyTextureToBuffer(source, destination, copySize)

Beschreibung

copyTextureToBuffer() kopiert nicht sofort. Die Methode schreibt nur einen Kopierbefehl in den GPUCommandEncoder. Die GPU führt ihn erst aus, wenn du den Encoder mit finish() abschließt und den entstandenen GPUCommandBuffer mit device.queue.submit() übergibst. Rufe die Methode außerhalb eines Render- oder Compute-Passes auf, also vor beginRenderPass()/beginComputePass() oder nach pass.end().

Meistens liest du damit Texturdaten zurück, zum Beispiel für Screenshots, Pixel-Picking, automatische Tests oder Compute-Ergebnisse aus einer Storage-Textur. Das Ziel ist dabei ein Staging-Puffer mit GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ. Mit mapAsync(GPUMapMode.READ) machst du ihn danach für die CPU lesbar. Die Quelltextur braucht das Usage-Flag GPUTextureUsage.COPY_SRC.

Du kannst jeden rechteckigen bzw. quaderförmigen Teilbereich einer bestimmten Mip-Stufe und Array-Ebene kopieren:

  • source.origin legt den Startpunkt in der Textur fest (in Texeln, bei Array-Texturen ist z die erste Ebene).
  • copySize legt die Größe fest.
  • offset, bytesPerRow und rowsPerImage legen fest, wie die Daten im Puffer liegen.

Die häufigste Stolperfalle ist bytesPerRow. Der Wert muss ein Vielfaches von 256 sein. Bei „krummen“ Texturbreiten sind die Zeilen im Puffer deshalb am Ende aufgefüllt. Dieses Auffüllen musst du beim Auslesen wieder entfernen. Die Formel dafür lautet Math.ceil(breite * bytesProTexel / 256) * 256.

Parameter

Name Typ Default Beschreibung
$source Pflicht GPUTexelCopyTextureInfo (früher GPUImageCopyTexture) Beschreibt die Quelle. Das Objekt hat diese Eigenschaften:
  • texture (Pflicht): die GPUTexture. Sie braucht GPUTextureUsage.COPY_SRC und sampleCount 1.
  • mipLevel: Mip-Stufe, Standard 0.
  • origin: Startpunkt als {x, y, z} oder [x, y, z], Standard {x: 0, y: 0, z: 0}. z ist die Array-Ebene bzw. die Tiefe.
  • aspect: "all" (Standard), "depth-only" oder "stencil-only".
$destination Pflicht GPUTexelCopyBufferInfo (früher GPUImageCopyBuffer) Beschreibt das Ziel. Das Objekt hat diese Eigenschaften:
  • buffer (Pflicht): der GPUBuffer. Er braucht GPUBufferUsage.COPY_DST.
  • offset: Byte-Versatz im Puffer, Standard 0. Er muss ein Vielfaches der Texel-Blockgröße sein, bei Tiefen-/Stencil-Formaten ein Vielfaches von 4.
  • bytesPerRow: Abstand zwischen zwei Zeilen in Bytes. Er muss ein Vielfaches von 256 sein und ist Pflicht, sobald mehr als eine Blockzeile kopiert wird.
  • rowsPerImage: Zeilen pro Bild bzw. Ebene. Pflicht, wenn mehr als eine Ebene kopiert wird.
$copySize Pflicht GPUExtent3D ({width, height, depthOrArrayLayers} | number[]) Größe des kopierten Bereichs in Texeln. height und depthOrArrayLayers sind standardmäßig 1. Als Array schreibst du [width, height, depth].

Rückgabewert

Typ
undefined
Beschreibung
Die Methode gibt nichts zurück. Validierungsfehler werden nicht als Ausnahme geworfen. Stattdessen wird der Encoder ungültig, und der Fehler meldet sich spätestens bei finish() bzw. submit() (abfangbar mit device.pushErrorScope()).

Siehe auch

GPUCommandEncoder.copyBufferToBuffer() GPUCommandEncoder.copyTextureToTexture() GPUCommandEncoder.clearBuffer() GPUCommandEncoder.copyBufferToTexture() GPUCommandEncoder.popDebugGroup()
← Vorheriger Eintrag GPUCommandEncoder.copyBufferToTexture()