GPUBuffer.label — Eigenschaft · JavaScript-Referenz

Signatur

GPUBuffer.label

Beschreibung

Die Eigenschaft label gibt einem GPUBuffer einen für Menschen lesbaren Namen. Die Browser-Implementierung von WebGPU nutzt diesen Namen in Validierungsfehlern (GPUValidationError), in Konsolenwarnungen und teilweise auch in nativen GPU-Debuggern wie PIX, RenderDoc oder Xcode. So lässt sich schnell erkennen, welcher Buffer ein Problem verursacht hat.

Ein Label kann auf zwei Wegen gesetzt werden: beim Erzeugen über die Eigenschaft label im Deskriptor von GPUDevice.createBuffer() oder später durch direktes Zuweisen an buffer.label. Wurde kein Label angegeben, ist der Wert ein leerer String ("").

Labels haben keinen Einfluss auf die Darstellung oder die Leistung. Sie gehören aber zu den wirksamsten Debugging-Hilfen in WebGPU. Deshalb sollte man sie in der Entwicklung grundsätzlich vergeben, am besten mit Angaben zum Verwendungszweck, etwa "Vertex-Buffer: Würfel" oder "Uniforms: Kamera".

Rückgabewert

Typ

string

Beschreibung

Das aktuelle Label des Buffers. Ohne gesetztes Label ist es ein leerer String. Die Eigenschaft ist auch beschreibbar.

Beispiele

Label beim Erzeugen setzen und auslesen

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

const vertexBuffer = device.createBuffer({
  label: 'Vertex-Buffer: Dreieck',
  size: 3 * 2 * 4, // 3 Punkte × (x, y) × Float32
  usage: GPUBufferUsage.VERTEX | GPUBufferUsage.COPY_DST,
});

console.log(vertexBuffer.label);

Vertex-Buffer: Dreieck

Label nachträglich zuweisen

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

const buffer = device.createBuffer({
  size: 64,
  usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
});

console.log(JSON.stringify(buffer.label)); // noch kein Label
buffer.label = 'Uniforms: Kamera-Matrix';
console.log(buffer.label);

"" Uniforms: Kamera-Matrix

Label in Validierungsfehlern sichtbar machen

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

device.pushErrorScope('validation');

// Ungültig: MAP_READ darf nur mit COPY_DST kombiniert werden
const badBuffer = device.createBuffer({
  label: 'Readback-Buffer: Partikel',
  size: 256,
  usage: GPUBufferUsage.MAP_READ | GPUBufferUsage.VERTEX,
});

const error = await device.popErrorScope();
if (error) {
  // Die Meldung enthält das Label, z. B. [Buffer "Readback-Buffer: Partikel"]
  console.error(error.message);
}

Beispielhaft: Buffer usage (...) is invalid ... - While calling [Device].CreateBuffer([BufferDescriptor "Readback-Buffer: Partikel"])

// Wichtig · Fallstricke

Kompatibilität: WebGPU ist noch nicht in allen Browsern verfügbar und läuft nur in sicheren Kontexten (HTTPS oder localhost). Prüfen Sie vorher mit if (navigator.gpu), ob die API vorhanden ist.
Der genaue Wortlaut von Fehlermeldungen hängt von der Implementierung ab (Dawn in Chromium, wgpu in Firefox, WebKit). Werten Sie Labels in Meldungen daher nie maschinell aus.
Wenn Sie ein Label nachträglich ändern, erscheint in bereits ausgegebenen Meldungen weiterhin der alte Name. Manche nativen Debugger übernehmen die Änderung außerdem erst verzögert oder gar nicht.
Legen Sie keine sensiblen Daten wie Benutzernamen oder Tokens in Labels ab, denn sie können in Konsolenausgaben und Absturzberichten landen.
Alle WebGPU-Objekte haben ein label, zum Beispiel GPUTexture, GPURenderPipeline und GPUCommandEncoder. Einheitliche Namen erleichtern das Debugging.

Siehe auch

GPUBuffer GPUDevice.createBuffer() GPUBuffer.size GPUBuffer.usage GPUDevice.pushErrorScope() GPUError GPUBindGroup.label