GPUQueue: writeTexture() Methode

Syntax

writeTexture(destination, data, dataLayout, size)

Parameter

destination

Ein Objekt, das die Textur-Subresource und den Ursprung definiert, um die Datenquelle zu schreiben. Es kann folgende Eigenschaften enthalten:

aspect Optional

Ein enumerierter Wert, der definiert, 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 Stencil umfassen kann.

"depth-only"

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

"stencil-only"

Nur der Stencil-Aspekt eines Depth-Or-Stencil-Formats wird beschrieben.

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

mipLevel Optional

Eine Zahl, die das Mip-Map-Level der Textur angibt, zu dem die Daten geschrieben werden sollen. Wenn weggelassen, ist der Standardwert für mipLevel 0.

origin Optional

Ein Objekt oder Array, das den Ursprung der Kopie spezifiziert — die minimale Ecke der Texturregion, zu der die Daten geschrieben werden sollen. Zusammen mit size definiert dies den vollständigen Bereich der zu kopierenden Region. Die x, y und z Werte haben den Standardwert 0, falls origin teilweise oder vollständig weggelassen wird.

Zum Beispiel können Sie 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, 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 des Inhalts in data definiert. Mögliche Werte sind:

offset Optional

Der Offset in Bytes vom Beginn von data bis zum Start der zu kopierenden Bilddaten. Wenn weggelassen, 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 nächsten Blockreihe darstellt. 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 der Blockreihen pro Einzelbild der Textur. bytesPerRow × rowsPerImage ergibt die Abfolge in Bytes zwischen dem Beginn jedes vollständigen Bildes. Dies ist erforderlich, wenn mehrere Bilder kopiert werden sollen.

size

Ein Objekt oder Array, das das Ausmaß der Kopie spezifiziert — die entfernte Ecke der Texturregion, in die die Daten geschrieben werden sollen. Zusammen mit destination.origin definiert dies den vollständigen Bereich der zu kopierenden Region. Siehe destination.origin für Beispiele der Objekt-/Arraystruktur.

Rückgabewert

Keiner (Undefined).

Validierung

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

• mipLevel ist kleiner als die Ziel- GPUTexture.mipLevelCount.
• origin.x ist ein Vielfaches der Texelblockbreite des Ziel- GPUTexture.format.
• origin.y ist ein Vielfaches der Texelblockhöhe des Ziel- GPUTexture.format.
• Wenn das Ziel- GPUTexture.format ein depth-or-stencil format ist oder GPUTexture.sampleCount größer als 1 ist, muss die Subresourcengröße gleich size sein.
• Das Ziel- GPUTexture.usage schließt das GPUTextureUsage.COPY_DST Flag ein.
• Das Ziel- GPUTexture.sampleCount ist 1.
• destination.origin.x + die destination GPUTexture.width ist kleiner als oder gleich der Breite der zu beschreibenden Subresource zur destination GPUTexture.
• destination.origin.y + die destination GPUTexture.height ist kleiner als oder gleich der Höhe der zu beschreibenden Subresource zur destination GPUTexture.
• destination.origin.z + die destination GPUTexture.depthOrArrayLayers ist kleiner als oder gleich der depthOrArrayLayers der zu beschreibenden Subresource zur destination GPUTexture.
• Die destination GPUTexture.width ist ein Vielfaches der Texelblockbreite des Ziel- GPUTexture.format.
• Die destination GPUTexture.height ist ein Vielfaches der Texelblockhöhe des Ziel- GPUTexture.format.
• destination.aspect bezieht sich auf einen einzelnen Aspekt des Ziel- GPUTexture.format.
• Dieser Aspekt ist ein gültiges Ziel für Bildkopien gemäß den depth-or-stencil formats.
• Die destination ist ansonsten mit dem GPUTexture.format kompatibel.

Beispiele

In Efficiently rendering glTF models 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;
}

Diese 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