GPUExternalTexture.label — Eigenschaft · JavaScript-Referenz

Signatur

GPUExternalTexture.label

Beschreibung

Die Eigenschaft label der Schnittstelle GPUExternalTexture enthält einen frei wählbaren String, mit dem sich die externe Textur beim Debuggen identifizieren lässt. Browser verwenden das Label in Validierungsfehlern (GPUValidationError), in Konsolenwarnungen und in GPU-Debugging-Werkzeugen. So sehen Sie auf einen Blick, welche Textur ein Problem verursacht, statt nur einen allgemeinen Objektverweis zu bekommen.

Eine GPUExternalTexture entsteht über GPUDevice.importExternalTexture(). Das Label lässt sich direkt über die Eigenschaft label im Deskriptor-Objekt setzen oder später per Zuweisung an externalTexture.label ändern. Ohne Angabe ist das Label ein leerer String.

Gerade bei externen Texturen lohnt sich ein aussagekräftiges Label, weil sie meist pro Frame neu aus einem HTMLVideoElement oder VideoFrame importiert werden. Ein Label wie "Kamera-Frame 42" macht leichter nachvollziehbar, ob ein Fehler durch eine abgelaufene Textur entsteht, die in einem späteren Frame noch verwendet wurde.

Rückgabewert

Typ

string

Beschreibung

Das aktuell gesetzte Label. Ist keines gesetzt, ist es ein leerer String (""). Die Eigenschaft ist beschreibbar.

Beispiele

Label beim Import über den Deskriptor setzen

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

const video = document.querySelector('video');
await video.play();

const externalTexture = device.importExternalTexture({
  source: video,
  label: 'Hintergrund-Video'
});

console.log(externalTexture.label);

Hintergrund-Video

Label nachträglich zuweisen und auslesen

const externalTexture = device.importExternalTexture({ source: video });
console.log(`Vorher: "${externalTexture.label}"`);

externalTexture.label = 'Webcam-Stream';
console.log(`Nachher: "${externalTexture.label}"`);

Vorher: "" Nachher: "Webcam-Stream"

Label pro Frame für Fehlersuche im Render-Loop

let frameNr = 0;

const renderFrame = async () => {
  frameNr++;
  device.pushErrorScope('validation');

  const externalTexture = device.importExternalTexture({
    source: video,
    label: `Video-Frame ${frameNr}`
  });

  const bindGroup = device.createBindGroup({
    layout: pipeline.getBindGroupLayout(0),
    entries: [
      { binding: 0, resource: sampler },
      { binding: 1, resource: externalTexture }
    ]
  });

  // ... Render-Pass mit bindGroup kodieren und abschicken ...

  const error = await device.popErrorScope();
  if (error) {
    // Die Meldung enthält das Label, z. B. [ExternalTexture "Video-Frame 17"]
    console.error(`Fehler bei ${externalTexture.label}:`, error.message);
  }

  video.requestVideoFrameCallback(renderFrame);
};

video.requestVideoFrameCallback(renderFrame);

// Wichtig · Fallstricke

Nur zum Debuggen: Das Label hat keinen Einfluss auf das Rendern. Legen Sie keine Programmlogik darauf an, und schreiben Sie keine sensiblen Daten hinein, denn es kann in Fehlermeldungen und Werkzeugen sichtbar werden.
Kurzlebige Objekte: Eine GPUExternalTexture läuft meist nach dem aktuellen Task bzw. beim nächsten Videoframe ab. Das Label bleibt zwar lesbar, die Textur ist dann aber nicht mehr gültig. In Fehlermeldungen hilft ein Label mit Frame-Nummer, solche Fälle zu finden.
Wie genau das Label in Meldungen auftaucht, hängt vom Browser ab. Chrome zeigt es z. B. als [ExternalTexture "Name"].
Kompatibilität: WebGPU gibt es nur in sicheren Kontexten. Die Unterstützung ist noch nicht in allen Browsern und auf allen Plattformen vollständig, deshalb vorher navigator.gpu prüfen. Die Eigenschaft label stammt aus dem Mixin GPUObjectBase und funktioniert bei allen WebGPU-Objekten gleich.

Siehe auch

GPURenderBundleEncoder.label GPUTexture.label GPUQuerySet.label GPURenderPassEncoder.label GPURenderPipeline.label