GPUTexture.depthOrArrayLayers — Eigenschaft · JavaScript-Referenz

Signatur

GPUTexture.depthOrArrayLayers

Beschreibung

depthOrArrayLayers gibt den dritten Wert der Texturgröße zurück, also die dritte Komponente von size, die beim Aufruf von GPUDevice.createTexture() angegeben wurde. Welche Bedeutung der Wert hat, hängt von der dimension der Textur ab:

"3d": die Tiefe der Volumentextur in Texeln.
"2d": die Anzahl der Array-Schichten, z. B. 6 bei einer Cubemap oder N bei einem texture_2d_array.
"1d": immer 1.

Die Eigenschaft ist nützlich, wenn eine Textur an Hilfsfunktionen weitergegeben wird und dort ohne zusätzliche Metadaten Views, Kopiervorgänge (copyTextureToTexture, writeTexture) oder Render-Durchläufe pro Schicht aufgebaut werden sollen. Zusammen mit width, height und dimension lässt sich so die komplette Geometrie der Textur bestimmen.

Wird im Deskriptor von createTexture() kein dritter Größenwert angegeben, ist der Standardwert 1. Der Wert gilt für Mip-Level 0. Bei 3D-Texturen wird die Tiefe in tieferen Mip-Stufen halbiert, die Anzahl der Array-Schichten bei 2D-Arrays dagegen nicht.

Rückgabewert

Typ

number

Beschreibung

Eine positive ganze Zahl (GPUIntegerCoordinateOut): die Tiefe bei 3D-Texturen, die Anzahl der Schichten bei 2D-Texturen bzw. 1 bei 1D-Texturen.

Beispiele

Schichtanzahl einer Cubemap auslesen

const adapter = await navigator.gpu?.requestAdapter();
if (!adapter) throw new Error('WebGPU nicht verfügbar');
const device = await adapter.requestDevice();

const cubemap = device.createTexture({
  size: [512, 512, 6], // 6 Seiten
  format: 'rgba8unorm',
  usage: GPUTextureUsage.TEXTURE_BINDING | GPUTextureUsage.COPY_DST,
});

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

2d 6

Tiefe einer 3D-Volumentextur

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

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

console.log(`${volume.width}×${volume.height}×${volume.depthOrArrayLayers}`);

// Ohne Angabe ist der Wert 1
const flat = device.createTexture({
  size: [256, 256],
  format: 'rgba8unorm',
  usage: GPUTextureUsage.TEXTURE_BINDING,
});
console.log(flat.depthOrArrayLayers);

64×64×32 1

Für jede Schicht eines Texture-Arrays eine View anlegen

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

const shadowMaps = device.createTexture({
  size: [1024, 1024, 4], // 4 Kaskaden
  format: 'depth32float',
  usage: GPUTextureUsage.RENDER_ATTACHMENT | GPUTextureUsage.TEXTURE_BINDING,
});

// Hilfsfunktion kommt ohne zusätzliche Metadaten aus
const createLayerViews = (texture) =>
  Array.from({ length: texture.depthOrArrayLayers }, (_, layer) =>
    texture.createView({
      dimension: '2d',
      baseArrayLayer: layer,
      arrayLayerCount: 1,
    })
  );

const views = createLayerViews(shadowMaps);
console.log(views.length);

4

// Wichtig · Fallstricke

Schreibgeschützt: Eine Zuweisung hat keine Wirkung. Die Größe einer Textur lässt sich nachträglich nicht ändern, dafür muss eine neue Textur erzeugt werden.
Bedeutung hängt von dimension ab: Wert immer zusammen mit GPUTexture.dimension auswerten. Eine 2D-Textur mit dem Wert 6 ist nicht automatisch eine Cubemap. Das wird erst durch createView({ dimension: 'cube' }) festgelegt.
Mip-Levels: Der Wert bezieht sich auf Mip-Level 0. Bei 3D-Texturen ist die Tiefe auf Level n gleich Math.max(1, depth >> n). Array-Schichten bleiben dagegen auf allen Stufen gleich.
Limits: Die Obergrenzen sind device.limits.maxTextureArrayLayers (Standard 256) für Array-Schichten und maxTextureDimension3D (Standard 2048) für die 3D-Tiefe.
Kompatibilität: WebGPU ist nur in sicheren Kontexten verfügbar und wird noch nicht von allen Browsern bzw. Plattformen unterstützt. Deshalb vorher mit navigator.gpu prüfen, ob die API vorhanden ist.

Siehe auch

GPUTexture GPUTexture.width GPUTexture.height GPUTexture.dimension GPUTexture.mipLevelCount GPUTexture.createView() GPUDevice.createTexture()