GPUCanvasContext.unconfigure() — Methode · JavaScript-Referenz

Signatur

GPUCanvasContext.prototype.unconfigure()

Beschreibung

unconfigure() hebt die Wirkung eines früheren Aufrufs von GPUCanvasContext.configure() auf. Der Kontext ist danach nicht mehr an ein GPUDevice gebunden, und alle Texturen, die zuvor über getCurrentTexture() ausgegeben wurden, werden zerstört. Der Canvas-Kontext als solcher bleibt aber erhalten und lässt sich später mit configure() wieder einrichten.

Die Methode brauchen Sie vor allem in drei Fällen:

Gerätewechsel: Nach einem Geräteverlust (device.lost) oder beim Wechsel auf einen anderen Adapter geben Sie die alte Konfiguration frei, bevor Sie mit dem neuen Gerät konfigurieren.
Ressourcen freigeben: Wenn eine Ansicht ausgeblendet oder eine Komponente entfernt wird, wird die Bindung an das Gerät gelöst. Die Swap-Chain-Texturen können dann freigegeben werden.
Sauberes Aufräumen: Bevor Sie device.destroy() aufrufen, lösen Sie den Canvas zuerst vom Gerät.

Nach unconfigure() löst ein Aufruf von getCurrentTexture() einen InvalidStateError aus, bis Sie erneut configure() aufrufen. Was der Canvas anschließend anzeigt, hängt vom Browser ab. Meist bleibt das zuletzt dargestellte Bild stehen oder der Canvas wird transparent bzw. leer.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Die Methode arbeitet synchron und hat nur Nebeneffekte: Die Konfiguration wird entfernt und die Texturen werden zerstört.

Beispiele

Konfigurieren, rendern und wieder lösen

const canvas = document.querySelector('#gpu-canvas');
const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
const context = canvas.getContext('webgpu');

context.configure({
  device,
  format: navigator.gpu.getPreferredCanvasFormat(),
  alphaMode: 'premultiplied'
});

// Einen Frame in Blau löschen
const encoder = device.createCommandEncoder();
const pass = encoder.beginRenderPass({
  colorAttachments: [{
    view: context.getCurrentTexture().createView(),
    clearValue: { r: 0, g: 0.3, b: 0.8, a: 1 },
    loadOp: 'clear',
    storeOp: 'store'
  }]
});
pass.end();
device.queue.submit([encoder.finish()]);

// Konfiguration entfernen – Swap-Chain-Texturen werden zerstört
context.unconfigure();

try {
  context.getCurrentTexture();
} catch (err) {
  console.log(err.name);
}

InvalidStateError

Nach Geräteverlust neu konfigurieren

const context = document.querySelector('canvas').getContext('webgpu');
const format = navigator.gpu.getPreferredCanvasFormat();

const initDevice = async () => {
  const adapter = await navigator.gpu.requestAdapter();
  const device = await adapter.requestDevice();

  context.configure({ device, format });

  device.lost.then(async (info) => {
    console.warn('Gerät verloren:', info.reason, info.message);
    context.unconfigure(); // alte Bindung lösen
    if (info.reason !== 'destroyed') {
      await initDevice(); // mit neuem Gerät neu konfigurieren
    }
  });

  return device;
};

const device = await initDevice();

Aufräumen beim Entfernen einer Komponente

class GpuView {
  constructor(canvas, device) {
    this.device = device;
    this.context = canvas.getContext('webgpu');
    this.context.configure({
      device,
      format: navigator.gpu.getPreferredCanvasFormat()
    });
    this.running = true;
    const loop = () => {
      if (!this.running) return;
      // ... Frame rendern mit this.context.getCurrentTexture()
      requestAnimationFrame(loop);
    };
    requestAnimationFrame(loop);
  }

  dispose() {
    this.running = false;     // zuerst die Render-Schleife stoppen
    this.context.unconfigure(); // dann den Canvas vom Gerät lösen
    console.log('GpuView freigegeben');
  }
}

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.requestDevice();
const view = new GpuView(document.querySelector('canvas'), device);
setTimeout(() => view.dispose(), 5000);

GpuView freigegeben

// Wichtig · Fallstricke

Zuerst die Render-Schleife stoppen: Wenn ein requestAnimationFrame-Callback nach unconfigure() noch getCurrentTexture() aufruft, wird ein InvalidStateError ausgelöst.
Zerstörte Texturen: Ein bereits geholtes GPUTexture-Objekt aus getCurrentTexture() ist danach ungültig. Wenn Sie es in Befehlen verwenden, die noch übermittelt werden, führt das zu Validierungsfehlern (siehe device.onuncapturederror).
Mehrfacher Aufruf: Ein wiederholter Aufruf ohne vorherige Konfiguration ist unschädlich und löst keinen Fehler aus.
Kein Ersatz für device.destroy(): Die Methode gibt nur die Canvas-Konfiguration frei. Das Gerät und dessen Puffer und Texturen bleiben bestehen.
Nicht erforderlich vor einem erneuten configure(): Ein erneuter Aufruf von configure() ersetzt die alte Konfiguration auch ohne vorheriges unconfigure(). Der explizite Aufruf macht den Ablauf beim Gerätewechsel aber klarer.
Kompatibilität: WebGPU steht nur in sicheren Kontexten (HTTPS) zur Verfügung und ist noch nicht in allen Browsern und auf allen Plattformen aktiviert. Prüfen Sie vorher mit if (!navigator.gpu). Mit OffscreenCanvas funktioniert die Methode auch in Web Workern.

Siehe auch

GPUCanvasContext GPUCanvasContext.configure() GPUCanvasContext.getCurrentTexture() GPUDevice.destroy() GPUDevice.lost GPU.getPreferredCanvasFormat() GPUCanvasContext.getConfiguration()