GPUTexture.mipLevelCount — Eigenschaft · JavaScript-Referenz

Signatur

GPUTexture.mipLevelCount

Beschreibung

Die Eigenschaft mipLevelCount des Interfaces GPUTexture gibt an, wie viele Mip-Levels die Textur besitzt. Der Wert entspricht genau dem Wert, der beim Erzeugen der Textur über GPUDevice.createTexture() im Deskriptor-Feld mipLevelCount angegeben wurde. Fehlt dort die Angabe, ist der Wert 1.

Mipmaps sind schrittweise verkleinerte Versionen einer Textur. Jedes Level ist in jeder Dimension halb so groß wie das vorherige (abgerundet, mindestens 1). Sie verringern Aliasing-Artefakte und verbessern die Cache-Nutzung beim Sampling weit entfernter Flächen. Die höchstmögliche Anzahl für eine 2D-Textur ist Math.floor(Math.log2(Math.max(width, height))) + 1.

Die Eigenschaft ist praktisch, wenn Code Texturen verarbeiten soll, die er nicht selbst erzeugt hat. Beispiele sind generische Mipmap-Generatoren, Views mit createView({ baseMipLevel, mipLevelCount }) oder Kopiervorgänge über alle Levels. Sie ist schreibgeschützt: Um die Anzahl der Levels zu ändern, muss man eine neue Textur anlegen.

Rückgabewert

Typ

number

Beschreibung

Eine positive Ganzzahl (GPUIntegerCoordinateOut, mindestens 1) mit der Anzahl der Mip-Levels der Textur.

Beispiele

Mip-Level-Anzahl einer neuen Textur auslesen

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

const size = 512;
const levels = Math.floor(Math.log2(size)) + 1; // 10

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

console.log(texture.mipLevelCount);

10

Standardwert ohne Angabe im Deskriptor

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

const tex = device.createTexture({
  size: [256, 256],
  format: 'bgra8unorm',
  usage: GPUTextureUsage.TEXTURE_BINDING
});

console.log(tex.mipLevelCount);

1

Für jedes Mip-Level eine eigene View anlegen (z. B. zur Mipmap-Erzeugung)

const createMipViews = (texture) => {
  const views = [];
  for (let level = 0; level < texture.mipLevelCount; level++) {
    views.push(texture.createView({
      baseMipLevel: level,
      mipLevelCount: 1
    }));
  }
  return views;
};

// Größe eines bestimmten Levels berechnen
const mipSize = (texture, level) => [
  Math.max(1, texture.width >> level),
  Math.max(1, texture.height >> level)
];

const views = createMipViews(texture); // texture aus Beispiel 1
console.log(views.length, mipSize(texture, 3));

10 [64, 64]

// Wichtig · Fallstricke

Nur lesbar: Eine Zuweisung an mipLevelCount hat keine Wirkung. Die Anzahl wird ausschließlich beim Aufruf von createTexture() festgelegt.
Obergrenze: Ist mipLevelCount im Deskriptor größer als die maximal mögliche Anzahl für die Texturgröße, ist die Textur ungültig und es entsteht ein Validierungsfehler. Den fängt man mit device.pushErrorScope('validation') ab.
Keine automatische Erzeugung: WebGPU füllt die Mip-Levels nicht selbst (anders als gl.generateMipmap() in WebGL). Man muss sie per Render- oder Compute-Pass selbst erzeugen. Dafür braucht man üblicherweise RENDER_ATTACHMENT oder STORAGE_BINDING im usage.
Multisampling: Texturen mit sampleCount > 1 dürfen nur mipLevelCount: 1 haben.
Kompatibilität: WebGPU steht nur in sicheren Kontexten (HTTPS) zur Verfügung und wird noch nicht von allen Browsern bzw. auf allen Plattformen unterstützt. Deshalb vorher auf navigator.gpu prüfen. Die Eigenschaft ist auch in Web Workers verfügbar.

Siehe auch

GPUTexture GPUDevice.createTexture() GPUTexture.createView() GPUTexture.width GPUTexture.height GPUTexture.sampleCount GPUTexture.depthOrArrayLayers