GPUBindGroup.label — Eigenschaft · JavaScript-Referenz

Signatur

GPUBindGroup.label

Beschreibung

Die Eigenschaft label gehört zum Mixin GPUObjectBase und ist daher auf allen WebGPU-Objekten vorhanden, auch auf GPUBindGroup. Sie enthält einen frei wählbaren Text, den der Browser in Validierungsfehlern, GPUError.message, Konsolenwarnungen und Grafik-Debuggern (z. B. PIX, RenderDoc, Xcode GPU Frame Capture) anzeigt.

Das Label lässt sich auf zwei Arten setzen:

beim Erzeugen über das Deskriptorfeld label in GPUDevice.createBindGroup(),
später durch direktes Zuweisen, z. B. bindGroup.label = "Kamera-Uniforms".

Gerade in Anwendungen mit vielen Bind Groups (pro Material, pro Objekt, pro Frame) wird die Fehlersuche ohne sprechende Labels schnell mühsam. Meldungen wie „[BindGroup "Material: Holz"] is invalid“ zeigen sofort, welche Ressource betroffen ist. Wird kein Label angegeben, ist der Wert eine leere Zeichenkette "".

Das Label hat keinen Einfluss auf das Rendering oder die Leistung. Es dient allein der Diagnose.

Rückgabewert

Typ

string

Beschreibung

Das aktuelle Label der Bind Group. Ohne Angabe beim Erzeugen ist es ein leerer String "". Die Eigenschaft ist beschreibbar.

Beispiele

Label beim Erzeugen setzen und auslesen

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

const uniformBuffer = device.createBuffer({
  label: 'Kamera-Uniform-Buffer',
  size: 64,
  usage: GPUBufferUsage.UNIFORM | GPUBufferUsage.COPY_DST,
});

const layout = device.createBindGroupLayout({
  label: 'Kamera-Layout',
  entries: [{
    binding: 0,
    visibility: GPUShaderStage.VERTEX,
    buffer: { type: 'uniform' },
  }],
});

const bindGroup = device.createBindGroup({
  label: 'Kamera-BindGroup',
  layout,
  entries: [{ binding: 0, resource: { buffer: uniformBuffer } }],
});

console.log(bindGroup.label);

Kamera-BindGroup

Label nachträglich zuweisen

const bindGroup = device.createBindGroup({
  layout,
  entries: [{ binding: 0, resource: { buffer: uniformBuffer } }],
});

console.log(JSON.stringify(bindGroup.label)); // noch leer

bindGroup.label = 'Material: Holz';
console.log(bindGroup.label);

"" Material: Holz

Label in Validierungsfehlern sehen

device.pushErrorScope('validation');

// Fehler: Buffer ist kleiner, als das Layout verlangt (minBindingSize)
const tinyBuffer = device.createBuffer({
  label: 'Zu kleiner Buffer',
  size: 4,
  usage: GPUBufferUsage.UNIFORM,
});

const strictLayout = device.createBindGroupLayout({
  entries: [{
    binding: 0,
    visibility: GPUShaderStage.FRAGMENT,
    buffer: { type: 'uniform', minBindingSize: 64 },
  }],
});

device.createBindGroup({
  label: 'Licht-BindGroup',
  layout: strictLayout,
  entries: [{ binding: 0, resource: { buffer: tinyBuffer } }],
});

const error = await device.popErrorScope();
if (error) {
  console.warn(error.message); // enthält "Licht-BindGroup"
}

z. B.: Binding size (4) is smaller than the minimum binding size (64). - While validating entries[0] ... - While calling [Device].CreateBindGroup([BindGroupDescriptor "Licht-BindGroup"]). (genauer Text je nach Browser)

// Wichtig · Fallstricke

Nur zur Diagnose: Das Label muss nicht eindeutig sein und wird von der GPU nicht ausgewertet. Die Anwendungslogik sollte sich nicht darauf stützen, etwa zum Wiederfinden von Objekten.
Formulierung der Meldungen: Wie und ob das Label in Fehlermeldungen auftaucht, bestimmt der Browser. Chrome (Dawn) und Firefox (wgpu) formatieren unterschiedlich.
Keine sensiblen Daten: Labels können in Absturzberichten, Konsolenausgaben und GPU-Captures landen. Nutzer- oder geheime Daten gehören daher nicht hinein.
Kompatibilität: WebGPU gibt es nur in sicheren Kontexten und noch nicht in allen Browsern bzw. auf allen Plattformen. Vorher mit if (!navigator.gpu) prüfen. Die Eigenschaft funktioniert auch in Web Workern.
Ohne Angabe ist der Wert "", nicht undefined. Wer einen anderen Wert als einen String zuweist, bekommt ihn in einen String umgewandelt.

Siehe auch

GPUBindGroup GPUDevice.createBindGroup() GPUBindGroupLayout.label GPUError GPUDevice.pushErrorScope() GPUBuffer.label GPUPipelineLayout.label