GPUTexture.usage — Eigenschaft · JavaScript-Referenz

Signatur

GPUTexture.usage

Beschreibung

Die schreibgeschützte Eigenschaft usage einer GPUTexture gibt die Verwendungszwecke zurück, die beim Erzeugen der Textur erlaubt wurden. Der Wert ist eine Ganzzahl, in der die einzelnen Flags der Konstanten GPUTextureUsage bitweise ODER-verknüpft sind. Er entspricht genau dem Feld usage aus dem Deskriptor von GPUDevice.createTexture(). Bei Texturen aus GPUCanvasContext.getCurrentTexture() kommt er aus dem Aufruf von configure().

Folgende Flags gibt es:

GPUTextureUsage.COPY_SRC (0x01): Die Textur darf Quelle eines Kopiervorgangs sein, z. B. bei copyTextureToBuffer().
GPUTextureUsage.COPY_DST (0x02): Die Textur darf Ziel eines Kopiervorgangs sein, z. B. bei queue.writeTexture() oder copyExternalImageToTexture().
GPUTextureUsage.TEXTURE_BINDING (0x04): Die Textur darf in einer Bind-Group als abtastbare Textur im Shader gebunden werden.
GPUTextureUsage.STORAGE_BINDING (0x08): Die Textur darf als Storage-Textur gebunden werden, d. h. der Shader kann sie beschreiben.
GPUTextureUsage.RENDER_ATTACHMENT (0x10): Die Textur darf als Farb- oder Tiefen-/Stencil-Anhang eines Render-Passes dienen.

Man braucht die Eigenschaft vor allem in generischem Code wie Hilfsbibliotheken, Mipmap-Generatoren oder Debug-Werkzeugen. Dort lässt sich damit vor einer Operation prüfen, ob die Textur sie überhaupt erlaubt. So vermeidet man Validierungsfehler, die WebGPU sonst nur asynchron über GPUDevice.popErrorScope() oder das Event uncapturederror meldet.

Rückgabewert

Typ

number

Beschreibung

Eine Bitmaske aus GPUTextureUsage-Flags. Ob ein Flag gesetzt ist, prüft man mit dem bitweisen UND-Operator, z. B. (texture.usage & GPUTextureUsage.COPY_DST) !== 0.

Beispiele

Textur erzeugen und usage auslesen

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();

const texture = device.createTexture({
  size: [256, 256],
  format: 'rgba8unorm',
  usage: GPUTextureUsage.COPY_DST |
         GPUTextureUsage.TEXTURE_BINDING |
         GPUTextureUsage.RENDER_ATTACHMENT,
});

console.log(texture.usage); // 0x02 | 0x04 | 0x10

22

Vor dem Hochladen prüfen, ob COPY_DST erlaubt ist

const uploadPixels = (device, texture, data, width, height) => {
  if ((texture.usage & GPUTextureUsage.COPY_DST) === 0) {
    throw new Error('Textur erlaubt kein COPY_DST – Upload nicht möglich.');
  }
  device.queue.writeTexture(
    { texture },
    data,
    { bytesPerRow: width * 4 },
    [width, height]
  );
};

const pixels = new Uint8Array(4 * 4 * 4).fill(255); // 4×4 weiße Pixel
try {
  uploadPixels(device, texture, pixels, 4, 4);
  console.log('Upload erfolgreich');
} catch (err) {
  console.error(err.message);
}

Upload erfolgreich

Flags für das Debugging lesbar ausgeben

const describeTextureUsage = (usage) =>
  Object.entries({
    COPY_SRC: GPUTextureUsage.COPY_SRC,
    COPY_DST: GPUTextureUsage.COPY_DST,
    TEXTURE_BINDING: GPUTextureUsage.TEXTURE_BINDING,
    STORAGE_BINDING: GPUTextureUsage.STORAGE_BINDING,
    RENDER_ATTACHMENT: GPUTextureUsage.RENDER_ATTACHMENT,
  })
    .filter(([, flag]) => (usage & flag) !== 0)
    .map(([name]) => name);

// Textur des Canvas prüfen
const context = document.querySelector('canvas').getContext('webgpu');
context.configure({
  device,
  format: navigator.gpu.getPreferredCanvasFormat(),
  usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.COPY_SRC,
});

console.log(describeTextureUsage(context.getCurrentTexture().usage));

["COPY_SRC", "RENDER_ATTACHMENT"]

// Wichtig · Fallstricke

Nicht änderbar: usage wird beim Erzeugen festgelegt. Soll die Textur später weitere Verwendungen erlauben, muss man eine neue Textur erzeugen und die Daten hineinkopieren. Plane die benötigten Flags deshalb von Anfang an ein. Setze aber nicht einfach alle Flags, denn unnötige Flags können die Leistung verschlechtern, etwa weil der Treiber dann auf Kompression verzichtet.
Operator-Rangfolge: texture.usage & GPUTextureUsage.COPY_DST !== 0 wird wegen der Rangfolge falsch ausgewertet. Setze immer Klammern: (texture.usage & GPUTextureUsage.COPY_DST) !== 0.
Einschränkungen bei der Validierung: STORAGE_BINDING ist nur mit bestimmten Formaten erlaubt (z. B. rgba8unorm, nicht rgba8unorm-srgb) und nicht bei Multisample-Texturen (sampleCount > 1). Multisample-Texturen brauchen außerdem RENDER_ATTACHMENT. Ein ungültiger Deskriptor erzeugt eine ungültige Textur und einen Validierungsfehler, aber keine synchrone Ausnahme.
Canvas-Texturen: Ohne Angabe von usage in GPUCanvasContext.configure() gilt der Standardwert GPUTextureUsage.RENDER_ATTACHMENT (16).
Kompatibilität: WebGPU steht nur in sicheren Kontexten (HTTPS) zur Verfügung und wird noch nicht überall unterstützt. Prüfe vorher mit if (!navigator.gpu) { … }, ob die API vorhanden ist. In Firefox und auf Linux ist die Unterstützung zum Teil noch eingeschränkt oder hinter Flags versteckt.

Siehe auch

GPUTexture GPUDevice.createTexture() GPUTexture.format GPUTexture.dimension GPUBuffer.usage GPUCanvasContext.configure() GPUQueue.writeTexture()