GPUQueue: writeTexture()-Methode

Syntax

writeTexture(destination, data, dataLayout, size)

Parameter

destination

Ein Objekt, das die Textur-Subressource und den Ursprung definiert, um die Datenquelle zu schreiben, welches die folgenden Eigenschaften haben kann:

aspect Optional

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

"all"

Alle verfügbaren Aspekte des Texturformats werden beschrieben, was alle oder beliebige von Farbe, Tiefe und Stencil bedeuten kann, abhängig von der Art des Formats, mit dem Sie arbeiten.

"depth-only"

Nur der Tiefenaspekt eines depth-or-stencil format wird beschrieben.

"stencil-only"

Nur der Stencilaspekt eines depth-or-stencil formats wird beschrieben.

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

mipLevel Optional

Eine Zahl, die die Mip-Map-Ebene der Textur darstellt, auf die die Daten geschrieben werden sollen. Wenn weggelassen, ist der Standardwert von mipLevel 0.

origin Optional

Ein Objekt oder ein Array, das den Ursprung der Kopie angibt — die minimale Ecke des Texturbereichs, auf den die Daten geschrieben werden sollen. Zusammen mit size definiert dies den vollständigen Umfang des zu kopierenden Bereichs. Die x, y und z Werte sind standardmäßig 0, wenn origin weggelassen wird.

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

texture

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

data

Ein Objekt, das die Datenquelle darstellt, die in die GPUTexture geschrieben werden soll. Dies kann ein ArrayBuffer, TypedArray oder DataView sein.

dataLayout

Ein Objekt, das das Layout des Inhalts in data definiert. Mögliche Werte sind:

offset Optional

Der Versatz, in Byte, vom Beginn von data bis zum Start der Bilddaten, die kopiert werden sollen. Wenn weggelassen, ist der Standardwert von offset 0.

bytesPerRow Optional

Eine Zahl, die die Breite, in Bytes, zwischen dem Anfang jeder Blockreihe (d.h. einer Reihe vollständiger Texel-Blöcke) und der nachfolgenden 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 Einzelbild der Textur. bytesPerRow × rowsPerImage ergibt die Breite, in Bytes, zwischen dem Anfang jedes vollständigen Bildes. Dies ist erforderlich, wenn es mehrere Bilder zum Kopieren gibt.

size

Ein Objekt oder ein Array, das den Umfang der Kopie angibt — die entfernte Ecke des Texturbereichs, auf die die Daten geschrieben werden sollen. Zusammen mit destination.origin definiert dies den vollständigen Umfang des zu kopierenden Bereichs. Siehe destination.origin für Beispiele zur Objekt-/Array-Struktur.

Rückgabewert

Keiner (undefined).

Validierung

Die folgenden Kriterien müssen erfüllt sein, wenn writeTexture() aufgerufen wird, andernfalls wird ein GPUValidationError erzeugt und die GPUQueue wird ungültig:

• mipLevel ist kleiner als die GPUTexture.mipLevelCount des Ziels.
• origin.x ist ein Vielfaches der Texel-Blockbreite des GPUTexture.format des Ziels.
• origin.y ist ein Vielfaches der Texel-Blockhöhe des GPUTexture.format des Ziels.
• Wenn das GPUTexture.format des Ziels ein depth-or-stencil format ist oder GPUTexture.sampleCount mehr als 1 ist, ist die Größe der Subressource gleich der size.
• Das GPUTexture.usage des Ziels beinhaltet das GPUTextureUsage.COPY_DST Flag.
• Das GPUTexture.sampleCount des Ziels ist 1.
• destination.origin.x + die destination GPUTexture.width ist kleiner oder gleich der Breite der Subressource, die in die destination GPUTexture geschrieben werden soll.
• destination.origin.y + die destination GPUTexture.height ist kleiner oder gleich der Höhe der Subressource, die in die destination GPUTexture geschrieben werden soll.
• destination.origin.z + die destination GPUTexture.depthOrArrayLayers ist kleiner oder gleich der depthOrArrayLayers der Subressource, die in die destination GPUTexture geschrieben werden soll.
• Die destination GPUTexture.width ist ein Vielfaches der Texel-Blockbreite des GPUTexture.format des Ziels.
• Die destination GPUTexture.height ist ein Vielfaches der Texel-Blockhöhe des GPUTexture.format des Ziels.
• destination.aspect bezieht sich auf einen einzelnen Aspekt des GPUTexture.format des Ziels.
• Dieser Aspekt ist ein gültiges Ziel für das Kopieren von Bildern gemäß depth-or-stencil formats.
• Die destination ist anderweitig kompatibel mit dem GPUTexture.format.

Beispiele

In Efficiently rendering glTF models wird eine Funktion für das Erstellen einer einfarbigen Textur definiert:

function createSolidColorTexture(r, g, b, a) {
  const data = new Uint8Array([r * 255, g * 255, b * 255, a * 255]);
  const texture = device.createTexture({
    size: { width: 1, height: 1 },
    format: "rgba8unorm",
    usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
  });
  device.queue.writeTexture({ texture }, data, {}, { width: 1, height: 1 });
  return texture;
}

Dies kann verwendet werden, um Standardtexturen für die Verwendung in Materialbibliotheken zu definieren:

const opaqueWhiteTexture = createSolidColorTexture(1, 1, 1, 1);
const transparentBlackTexture = createSolidColorTexture(0, 0, 0, 0);
const defaultNormalTexture = createSolidColorTexture(0.5, 0.5, 1, 1);

Spezifikationen

Browser-Kompatibilität

Siehe auch

• Die WebGPU API