GPUTextureView — Schnittstelle · JavaScript-Referenz

Signatur

interface GPUTextureView

Beschreibung

GPUTextureView ist Teil der WebGPU API. Eine Texture View legt fest, wie und welcher Ausschnitt einer GPUTexture von der GPU gelesen oder beschrieben wird. Shader und Render Passes greifen nie direkt auf eine Textur zu, sondern immer über eine View.

Eine View erzeugt man mit GPUTexture.createView(descriptor). Über den optionalen Deskriptor kann man die Dimension (z. B. "2d", "2d-array", "cube"), das Format, den Aspekt (Farbe, Tiefe, Stencil) sowie einen Bereich von Mip-Stufen und Array-Ebenen auswählen. Ohne Deskriptor deckt die View die gesamte Textur ab.

Typische Einsatzgebiete:

Als view in colorAttachments bzw. depthStencilAttachment eines Render Pass (Render-Ziel).
Als resource in einem GPUBindGroup-Eintrag, um die Textur im Shader zu sampeln oder als Storage-Textur zu beschreiben.
Um eine einzelne Mip-Stufe oder eine Seite einer Cubemap gezielt zu adressieren, z. B. beim Erzeugen von Mipmaps.

Das Interface selbst besitzt nur die Eigenschaft label (ein frei wählbarer Name für Fehlermeldungen und Debugging-Werkzeuge). Es hat keinen öffentlichen Konstruktor.

Parameter

Name	Typ	Default	Beschreibung
$descriptor.label	string	""	Name der View für Debugging und Fehlermeldungen; später über `view.label` les- und schreibbar.
$descriptor.format	GPUTextureFormat	Format der Textur	Format der View; muss dem Texturformat entsprechen oder in `viewFormats` der Textur aufgeführt sein (z. B. `"rgba8unorm-srgb"`).
$descriptor.dimension	"1d" \| "2d" \| "2d-array" \| "cube" \| "cube-array" \| "3d"	abhängig von der Textur	Dimension, unter der die Textur betrachtet wird.
$descriptor.usage	number (GPUTextureUsageFlags)	0 (= Usage der Textur)	Teilmenge der Usage-Flags der Textur, die für diese View gelten sollen (neuere Spezifikationsversion).
$descriptor.aspect	"all" \| "depth-only" \| "stencil-only"	"all"	Welcher Aspekt einer Tiefen-/Stencil-Textur sichtbar ist.
$descriptor.baseMipLevel	number	0	Erste zugängliche Mip-Stufe.
$descriptor.mipLevelCount	number	alle verbleibenden	Anzahl der Mip-Stufen ab `baseMipLevel`.
$descriptor.baseArrayLayer	number	0	Erste zugängliche Array-Ebene.
$descriptor.arrayLayerCount	number	alle verbleibenden	Anzahl der Array-Ebenen ab `baseArrayLayer` (für `"cube"` genau 6).

Beispiele

Canvas-View als Render-Ziel verwenden

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
const context = document.querySelector('canvas').getContext('webgpu');
context.configure({ device, format: navigator.gpu.getPreferredCanvasFormat() });

// Pro Frame eine neue View der aktuellen Canvas-Textur erzeugen
const view = context.getCurrentTexture().createView({ label: 'Canvas-View' });

const encoder = device.createCommandEncoder();
const pass = encoder.beginRenderPass({
  colorAttachments: [{
    view,
    clearValue: { r: 0.1, g: 0.2, b: 0.3, a: 1 },
    loadOp: 'clear',
    storeOp: 'store'
  }]
});
pass.end();
device.queue.submit([encoder.finish()]);
console.log(view.label);

Canvas-View

Textur-View in einer Bind Group für den Shader

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

const bindGroup = device.createBindGroup({
  layout: pipeline.getBindGroupLayout(0), // zuvor erstellte Render-Pipeline
  entries: [
    { binding: 0, resource: sampler },
    { binding: 1, resource: texture.createView() }
  ]
});

Einzelne Mip-Stufe bzw. Cubemap-View erzeugen

const mipTexture = device.createTexture({
  size: [512, 512],
  mipLevelCount: 10,
  format: 'rgba8unorm',
  usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.RENDER_ATTACHMENT
});

// Nur Mip-Stufe 3 (64×64) als Render-Ziel
const level3 = mipTexture.createView({ baseMipLevel: 3, mipLevelCount: 1, label: 'Mip 3' });

// 6 Array-Ebenen als Cubemap interpretieren
const cubeTexture = device.createTexture({
  size: [256, 256, 6],
  format: 'rgba8unorm',
  usage: GPUTextureUsage.TEXTURE_BINDING
});
const cubeView = cubeTexture.createView({ dimension: 'cube' });
console.log(level3.label, cubeView instanceof GPUTextureView);

Mip 3 true

Nur den Tiefenaspekt einer Depth-Stencil-Textur

const depthTexture = device.createTexture({
  size: [canvas.width, canvas.height],
  format: 'depth24plus-stencil8',
  usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING
});

// Für Render Pass: kompletter Aspekt
const depthAttachmentView = depthTexture.createView();
// Für Shader-Zugriff: nur Tiefe
const depthOnlyView = depthTexture.createView({ aspect: 'depth-only' });

// Wichtig · Fallstricke

Canvas-Texturen: context.getCurrentTexture() liefert jeden Frame eine neue Textur. Die View darf daher nicht zwischengespeichert werden, sondern muss pro Frame neu erzeugt werden – sonst gibt es Validierungsfehler.
Validierungsfehler (z. B. ungültiger Mip-Bereich, "cube" ohne 6 Ebenen, nicht erlaubtes Format) werfen keine Ausnahme, sondern erzeugen eine ungültige View und einen Fehler auf dem Device. Mit device.pushErrorScope('validation') bzw. dem uncapturederror-Event abfangen; ein aussagekräftiges label hilft enorm.
Ein Render-Attachment muss genau eine Mip-Stufe und (bei 2D) genau eine Array-Ebene abdecken.
Eine View hält ihre Textur nicht am Leben: Nach texture.destroy() ist auch jede View davon unbrauchbar.
Formatwechsel (z. B. auf -srgb) nur, wenn das Zielformat bei createTexture() in viewFormats angegeben wurde.
Kompatibilität: WebGPU steht nur in sicheren Kontexten und noch nicht in allen Browsern/Plattformen zur Verfügung. Vorher mit if (!navigator.gpu) prüfen und ggf. auf WebGL zurückfallen. Auch in Web Workers verfügbar.

Siehe auch

GPUTexture GPUTexture.createView() GPUDevice.createTexture() GPUDevice.createBindGroup() GPUCommandEncoder.beginRenderPass() GPUCanvasContext.getCurrentTexture() GPUSampler