GPUTexture.dimension — Eigenschaft · JavaScript-Referenz

Signatur

GPUTexture.dimension

Beschreibung

Die Eigenschaft dimension gibt an, wie die Texel (Texturpixel) jeder Subressource einer GPUTexture angeordnet sind. Der Wert entspricht der Option dimension, die beim Anlegen der Textur an GPUDevice.createTexture() übergeben wurde. Fehlt diese Option, ist der Wert "2d".

Mögliche Werte:

"1d": Die Textur hat nur eine Breite (width). height und depthOrArrayLayers müssen 1 sein.
"2d": Die Textur hat Breite und Höhe. Optional können mehrere Array-Ebenen genutzt werden, etwa für Textur-Arrays oder Cubemaps.
"3d": Die Textur hat Breite, Höhe und Tiefe, etwa für Volumendaten oder 3D-LUTs.

Das ist vor allem dann nützlich, wenn eine Funktion Texturen unbekannter Herkunft bekommt, etwa in Hilfsbibliotheken, beim Erzeugen passender GPUTextureViews oder bei der Prüfung, ob eine Textur zu einem Bind-Group-Layout passt. Achtung: dimension beschreibt die Textur, nicht die Ansicht. Die Ansicht (GPUTextureView) kennt zusätzlich Typen wie "2d-array", "cube" und "cube-array".

Rückgabewert

Typ

"1d" | "2d" | "3d"

Beschreibung

Ein Wert aus der Aufzählung GPUTextureDimension. Er beschreibt die Dimension der Textur.

Beispiele

Standardwert einer 2D-Textur auslesen

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

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

// Keine dimension-Option angegeben, also "2d"
console.log(texture.dimension);

2d

3D-Textur für eine Farb-LUT anlegen

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

const lut = device.createTexture({
  dimension: '3d',
  size: { width: 32, height: 32, depthOrArrayLayers: 32 },
  format: 'rgba8unorm',
  usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST
});

console.log(lut.dimension, lut.depthOrArrayLayers);

3d 32

Passende Ansicht aus der Dimension ableiten

const createDefaultView = (texture) => {
  let viewDimension;
  if (texture.dimension === '1d') {
    viewDimension = '1d';
  } else if (texture.dimension === '3d') {
    viewDimension = '3d';
  } else {
    // Bei 2D-Texturen mit mehreren Ebenen braucht man eine Array-Ansicht
    viewDimension = texture.depthOrArrayLayers > 1 ? '2d-array' : '2d';
  }
  return texture.createView({ dimension: viewDimension });
};

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
const layers = device.createTexture({
  size: [128, 128, 4],
  format: 'rgba8unorm',
  usage: GPUTextureUsage.TEXTURE_BINDING
});

const view = createDefaultView(layers);
console.log(layers.dimension, view instanceof GPUTextureView);

2d true

// Wichtig · Fallstricke

Nur lesbar: Wer dimension zuweist, ändert nichts an der Textur. Für eine andere Dimension muss man eine neue Textur anlegen.
Nicht mit der Ansichtsdimension verwechseln: Werte wie "cube" oder "2d-array" gibt es nur bei GPUTextureViewDimension. Eine Cubemap ist auf Texturebene eine "2d"-Textur mit 6 Array-Ebenen.
Einschränkungen: "1d"-Texturen erlauben keine Mipmaps (mipLevelCount muss 1 sein) und kein Multisampling. Komprimierte Formate und Tiefen- bzw. Stencil-Formate sind bei "1d" gar nicht und bei "3d" nur eingeschränkt möglich. Verstöße erzeugen einen Validierungsfehler und keine Ausnahme. Ihn fängt man mit device.pushErrorScope('validation') ab.
Größenlimits: Die erlaubte Höchstgröße hängt von der Dimension ab (maxTextureDimension1D, maxTextureDimension2D, maxTextureDimension3D in device.limits).
Kompatibilität: WebGPU gibt es nur in sicheren Kontexten. Die Unterstützung in den Browsern ist noch nicht vollständig. Vor der Nutzung sollte man mit if (!navigator.gpu) prüfen, ob WebGPU verfügbar ist.

Siehe auch

GPUTexture GPUDevice.createTexture() GPUTexture.createView() GPUTexture.depthOrArrayLayers GPUTexture.format GPUTextureView PaymentAddress.region