Signatur
Beschreibung
Die Eigenschaft label des GPUBindGroupLayout-Interfaces enthält einen frei wählbaren Text, mit dem ein Bind-Group-Layout benannt wird. Die WebGPU-Implementierung des Browsers nutzt diesen Namen in Validierungsfehlern (GPUValidationError), in Konsolenwarnungen und in Werkzeugen zur GPU-Analyse. Bei Fehlern steht dann statt eines anonymen Objekts z. B. [BindGroupLayout "Kamera-Uniforms"] in der Meldung.
Ein Label lässt sich auf zwei Arten setzen: direkt beim Erzeugen über die Eigenschaft label im Deskriptor von GPUDevice.createBindGroupLayout() oder später durch Zuweisen an bindGroupLayout.label. Wird das Layout implizit über GPURenderPipeline.getBindGroupLayout() bzw. GPUComputePipeline.getBindGroupLayout() geholt (bei layout: "auto"), ist das Label anfangs ein leerer String und kann nachträglich gesetzt werden.
Die Eigenschaft hat keinerlei Einfluss auf das Verhalten beim Rendern oder Rechnen. Sie dient ausschließlich dem Debugging. Gerade bei größeren Anwendungen mit vielen Layouts, Pipelines und Bind Groups werden Fehlermeldungen dadurch deutlich leichter nachvollziehbar.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | string | "" | Beim Setzen: der neue Label-Text. Andere Werte werden in einen String umgewandelt (IDL-Typ USVString). |
Rückgabewert
"".Beispiele
Label beim Erzeugen im Deskriptor setzen
const adapter = await navigator.gpu?.requestAdapter();
if (!adapter) throw new Error('WebGPU wird nicht unterstützt');
const device = await adapter.requestDevice();
const bindGroupLayout = device.createBindGroupLayout({
label: 'Kamera-Uniforms',
entries: [
{
binding: 0,
visibility: GPUShaderStage.VERTEX,
buffer: { type: 'uniform' }
}
]
});
console.log(bindGroupLayout.label);Label nachträglich zuweisen
const device = await (await navigator.gpu.requestAdapter()).requestDevice();
const layout = device.createBindGroupLayout({
entries: [
{ binding: 0, visibility: GPUShaderStage.COMPUTE, buffer: { type: 'storage' } }
]
});
console.log(JSON.stringify(layout.label)); // noch leer
layout.label = 'Partikel-Storage-Layout';
console.log(layout.label);Implizites Layout einer Pipeline benennen und Fehler abfangen
const device = await (await navigator.gpu.requestAdapter()).requestDevice();
const module = device.createShaderModule({
code: `
@group(0) @binding(0) var<storage, read_write> data: array<f32>;
@compute @workgroup_size(64)
fn main(@builtin(global_invocation_id) id: vec3u) {
data[id.x] = data[id.x] * 2.0;
}
`
});
const pipeline = device.createComputePipeline({
label: 'Verdoppler-Pipeline',
layout: 'auto',
compute: { module, entryPoint: 'main' }
});
const layout = pipeline.getBindGroupLayout(0);
layout.label = 'Verdoppler-Layout (Gruppe 0)';
device.pushErrorScope('validation');
// Absichtlich fehlerhaft: Eintrag für binding 0 fehlt
device.createBindGroup({ label: 'Kaputte Bind Group', layout, entries: [] });
const error = await device.popErrorScope();
if (error) console.warn(error.message);// Wichtig · Fallstricke
- Nur Debugging: Das Label hat keine funktionale Wirkung. Es muss nicht eindeutig sein und wird nicht geprüft.
- Keine sensiblen Daten: Labels können in Fehlermeldungen, in der Konsole und in Profiling-Werkzeugen auftauchen. Nutzerdaten oder Geheimnisse gehören deshalb nicht hinein.
- Layouts mit
layout: "auto": Jeder Aufruf vongetBindGroupLayout()kann ein neues JavaScript-Objekt liefern. Ein gesetztes Label gilt dann nur für genau dieses Objekt. - Format der Meldungen: Wie Labels in Fehlertexten dargestellt werden, ist nicht standardisiert und unterscheidet sich zwischen Chrome (Dawn), Firefox (wgpu) und Safari. Fehlertexte sollten daher nicht per Code ausgewertet werden.
- Kompatibilität: WebGPU steht nur in sicheren Kontexten (HTTPS) zur Verfügung und ist noch nicht auf allen Plattformen aktiviert. Vorher mit
if (navigator.gpu)prüfen, ob die API vorhanden ist. In Workern ist die API ebenfalls verfügbar.