GPUQueue: Methode writeTexture()

Syntax

writeTexture(destination, data, dataLayout, size)

Parameter

destination

Ein Objekt, das die Textur-Subressource und den Ursprung angibt, in die bzw. an den die Datenquelle geschrieben werden soll. Es kann die folgenden Eigenschaften haben:

aspect Optional

Ein Aufzählungswert, der angibt, in welche Aspekte der Textur die Daten geschrieben werden. Mögliche Werte sind:

"all"

Die Daten werden in alle verfügbaren Aspekte des Texturformats geschrieben. Je nach Format können dies Farbe, Tiefe und Stencil sein.

"depth-only"

Die Daten werden nur in den Tiefenaspekt eines Tiefen- oder Stencil-Formats geschrieben.

"stencil-only"

Die Daten werden nur in den Stencil-Aspekt eines Tiefen- oder Stencil-Formats geschrieben.

Wird aspect weggelassen, hat es den Wert "all".

mipLevel Optional

Eine Zahl, die die Mipmap-Stufe der Textur angibt, in die die Daten geschrieben werden. Wird mipLevel weggelassen, ist der Standardwert 0.

origin Optional

Ein Objekt oder Array, das den Ursprung des Kopiervorgangs angibt – die minimale Ecke des Texturbereichs, in den die Daten geschrieben werden. Zusammen mit size definiert es die vollständige Ausdehnung des Zielbereichs. Die Werte x, y und z sind standardmäßig 0, wenn sie oder origin weggelassen werden.

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

texture

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

data

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

dataLayout

Ein Objekt, das das Layout der in data enthaltenen Daten definiert. Mögliche Eigenschaften sind:

offset Optional

Der Offset in Bytes vom Anfang von data bis zum Beginn der zu kopierenden Bilddaten. Wird offset weggelassen, ist der Standardwert 0.

bytesPerRow Optional

Eine Zahl, die den Abstand in Bytes zwischen dem Beginn einer Blockzeile (d.h. einer Zeile vollständiger Texel-Blöcke) und dem Beginn der nächsten Blockzeile angibt. Diese Eigenschaft ist erforderlich, wenn mehrere Blockzeilen vorhanden sind (d.h. wenn die Höhe oder Tiefe des zu kopierenden Bereichs mehr als einen Block beträgt).

rowsPerImage Optional

Die Anzahl der Blockzeilen pro Einzelbild der Textur. bytesPerRow × rowsPerImage ergibt den Abstand in Bytes zwischen den Anfängen zweier vollständiger Bilder. Diese Eigenschaft ist erforderlich, wenn mehrere Bilder kopiert werden.

size

Ein Objekt oder Array, das die Ausdehnung des Kopiervorgangs angibt – die gegenüberliegende Ecke des Texturbereichs, in den die Daten geschrieben werden. Zusammen mit destination.origin definiert es die vollständige Ausdehnung des Zielbereichs. Beispiele für die Objekt- und Array-Struktur finden Sie unter destination.origin.

Rückgabewert

Keiner (undefined).

Validierung

Beim Aufruf von writeTexture() müssen die folgenden Bedingungen erfüllt sein. Andernfalls wird ein GPUValidationError erzeugt und die GPUQueue wird ungültig:

• mipLevel ist kleiner als GPUTexture.mipLevelCount der Zieltextur.
• origin.x ist ein Vielfaches der Texel-Blockbreite des Zielformats GPUTexture.format.
• origin.y ist ein Vielfaches der Texel-Blockhöhe des Zielformats GPUTexture.format.
• Wenn GPUTexture.format der Zieltextur ein Tiefen- oder Stencil-Format ist oder GPUTexture.sampleCount größer als 1 ist, entspricht die Größe der Subressource size.
• GPUTexture.usage der Zieltextur enthält das Flag GPUTextureUsage.COPY_DST.
• GPUTexture.sampleCount der Zieltextur ist 1.
• destination.origin.x plus GPUTexture.width von destination ist kleiner oder gleich der Breite der Subressource der Zieltextur GPUTexture.
• destination.origin.y plus GPUTexture.height von destination ist kleiner oder gleich der Höhe der Subressource der Zieltextur GPUTexture.
• destination.origin.z plus GPUTexture.depthOrArrayLayers von destination ist kleiner oder gleich depthOrArrayLayers der Subressource der Zieltextur GPUTexture.
• GPUTexture.width von destination ist ein Vielfaches der Texel-Blockbreite des Zielformats GPUTexture.format.
• GPUTexture.height von destination ist ein Vielfaches der Texel-Blockhöhe des Zielformats GPUTexture.format.
• destination.aspect bezieht sich auf einen einzelnen Aspekt des Zielformats GPUTexture.format.
• Dieser Aspekt ist gemäß den Regeln für Tiefen- oder Stencil-Formate ein gültiges Ziel für einen Bildkopiervorgang.
• destination ist auch ansonsten mit GPUTexture.format kompatibel.

Beispiele

In Effizientes Rendern von glTF-Modellen wird eine Funktion zum 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;
}

Damit lassen sich Standardtexturen für die Verwendung in Materialbibliotheken 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