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
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. Diex
,y
undz
Werte sind standardmäßig 0, wenn Teile oder alle vonorigin
weggelassen werden.Nachfolgend ein Beispielarray:
jsorigin: [0, 0, 0];
Das entsprechende Objekt sieht so aus:
jsorigin: { 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 einArrayBuffer
,TypedArray
, oderDataView
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üroffset
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. Siehedestination.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:
mipLevel
ist kleiner als die ZielGPUTexture.mipLevelCount
.origin.x
ist ein Vielfaches der Texelblockbreite des ZielsGPUTexture.format
.origin.y
ist ein Vielfaches der Texelblockhöhe des ZielsGPUTexture.format
.- Wenn das Ziel
GPUTexture.format
ein Tiefen-oder-Schablonenformat ist oderGPUTexture.sampleCount
mehr als 1 beträgt, entspricht die Unterressourcengrößesize
. - Die Nutzung des Ziels
GPUTexture.usage
umfasst dasGPUTextureUsage.COPY_DST
-Flag. - Die Abtastanzahl des Ziels
GPUTexture.sampleCount
ist 1. destination.origin.x
+ diedestination
GPUTexture.width
ist kleiner oder gleich der Breite der Unterressource, die auf dasdestination
GPUTexture
geschrieben wird.destination.origin.y
+ diedestination
GPUTexture.height
ist kleiner oder gleich der Höhe der Unterressource, die auf dasdestination
GPUTexture
geschrieben wird.destination.origin.z
+ diedestination
GPUTexture.depthOrArrayLayers
ist kleiner oder gleich der depthOrArrayLayers der Unterressource, die auf dasdestination
GPUTexture
geschrieben wird.- Die
destination
GPUTexture.width
ist ein Vielfaches der Texelblockbreite des ZielsGPUTexture.format
. - Die
destination
GPUTexture.height
ist ein Vielfaches der Texelblockhöhe des ZielsGPUTexture.format
. destination.aspect
bezieht sich auf einen einzigen Aspekt des ZielsGPUTexture.format
.- Dieser Aspekt ist ein gültiges Bildkopierziel gemäß Tiefen-oder-Schablonenformate.
- Das
destination
ist ansonsten kompatibel mit demGPUTexture.format
.
Beispiele
In Efficiently rendering glTF models wird eine Funktion zum Erstellen einer Vollfarbtextur 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 den Einsatz 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
Specification |
---|
WebGPU # dom-gpuqueue-writetexture |
Browser-Kompatibilität
BCD tables only load in the browser
Siehe auch
- Die WebGPU API