GPUQueue: writeTexture() 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, bevor Sie diese produktiv verwenden.

Sicherer Kontext: Diese Funktion ist nur in sicheren Kontexten (HTTPS) in einigen oder allen unterstützenden Browsern verfügbar.

Hinweis: Dieses Feature ist verfügbar in Web Workers.

Die writeTexture()-Methode der GPUQueue-Schnittstelle schreibt eine bereitgestellte Datenquelle in eine bestimmte GPUTexture.

Dies ist eine Komfortfunktion, die eine Alternative zum Einstellen von Texturdaten über Pufferzuordnung und Puffer-zu-Textur-Kopien bietet. Sie lässt das Benutzeragent entscheiden, wie die Daten am effizientesten kopiert werden können.

Syntax

js
writeTexture(destination, data, dataLayout, size)

Parameter

destination

Ein Objekt, das die Textur-Unterressource und den Ursprung definiert, zu dem die Datenquelle geschrieben werden soll. Es kann die folgenden Eigenschaften enthalten:

aspect Optional

Ein aufgezählter 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 Formattyp Farbe, Tiefe und Schablone bedeuten kann.

"depth-only"

Nur der Tiefenaspekt eines Tiefen-oder-Schablonenformats wird beschrieben.

"stencil-only"

Nur der Schablonenaspekt eines Tiefen-oder-Schablonenformats wird beschrieben.

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

mipLevel Optional

Eine Zahl, die die Mip-Map-Ebene der Textur repräsentiert, auf die die Daten geschrieben werden sollen. Wenn nicht angegeben, ist der Standardwert für mipLevel 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 vollen Umfang des Bereichs, in den kopiert werden soll. Die x, y und z Werte sind standardmäßig 0, wenn Teile oder alle von origin weggelassen werden.

Nachfolgend ein Beispielarray:

js
origin: [0, 0, 0];

Das entsprechende Objekt sieht so aus:

js
origin: {
  x: 0,
  y: 0,
  z: 0
}
texture

Ein GPUTexture-Objekt, das die Textur repräsentiert, in die die Daten geschrieben werden sollen.

data

Ein Objekt, das die Datenquelle repräsentiert, 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 Inhalte definiert. Mögliche Werte sind:

offset Optional

Der Offset in Bytes vom Beginn von data bis zum Start der zu kopierenden Bilddaten. Wenn nicht angegeben, ist der Standardwert für offset 0.

bytesPerRow Optional

Eine Zahl, die den Abstand in Bytes zwischen dem Beginn jeder Blockreihe (d.h. einer Reihe vollständiger Texelblöcke) und der darauf folgenden Blockreihe repräsentiert. Dies ist erforderlich, wenn es mehrere Blockreihen gibt (d.h. die Kopierhöhe oder -tiefe beträgt mehr als einen Block).

rowsPerImage Optional

Die Anzahl von Blockreihen pro Einzelbild der Textur. bytesPerRow × rowsPerImage ergibt den Abstand in Bytes zwischen dem Beginn jedes vollständigen Bildes. Dies ist erforderlich, wenn mehrere Bilder kopiert werden sollen.

size

Ein Objekt oder Array, das den Umfang der Kopie angibt — die entfernte Ecke des Texturbereichs, in den die Daten geschrieben werden sollen. Zusammen mit destination.origin definiert dies den vollen Umfang des Bereichs, in den kopiert werden soll. Siehe destination.origin für Beispiele zur Objekt-/Array-Struktur.

Rückgabewert

Keiner (Undefined).

Validierung

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

Beispiele

In Efficiently rendering glTF models wird eine Funktion zum Erstellen einer Vollfarbtextur definiert:

js
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 den Einsatz in Materialbibliotheken zu definieren:

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

Spezifikationen

Specification
WebGPU
# dom-gpuqueue-writetexture

Browser-Kompatibilität

BCD tables only load in the browser

Siehe auch