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. Mgliche Werte sind:

"all"

Alle verfgbaren Aspekte des Texturformats werden beschrieben, was alle oder beliebige von Farbe, Tiefe und Stencil bedeuten kann, abhngig 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 vollstndigen Umfang des zu kopierenden Bereichs. Die x, y und z Werte sind standardmig 0, wenn origin weggelassen wird.

Sie knnen 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. Mgliche 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 vollstndiger Texel-Blcke) und der nachfolgenden Blockreihe darstellt. Dies ist erforderlich, wenn es mehrere Blockreihen gibt (d.h. die Kopierhhe 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 vollstndigen 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 vollstndigen Umfang des zu kopierenden Bereichs. Siehe destination.origin fr Beispiele zur Objekt-/Array-Struktur.

Rckgabewert

Keiner (undefined).

Validierung

Die folgenden Kriterien mssen erfllt sein, wenn writeTexture() aufgerufen wird, andernfalls wird ein GPUValidationError erzeugt und die GPUQueue wird ungltig:

• 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-Blockhhe 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 Gre 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 Hhe 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-Blockhhe des GPUTexture.format des Ziels.
• destination.aspect bezieht sich auf einen einzelnen Aspekt des GPUTexture.format des Ziels.
• Dieser Aspekt ist ein gltiges Ziel fr 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 fr 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 fr 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-Kompatibilitt

Siehe auch

• Die WebGPU API