GPUCommandEncoder.insertDebugMarker() — Methode · JavaScript-Referenz

Signatur

GPUCommandEncoder.prototype.insertDebugMarker(markerLabel)

Beschreibung

insertDebugMarker() setzt einen einzelnen, benannten Punkt in die Befehlsfolge, die ein GPUCommandEncoder aufzeichnet. Die Markierung ändert nichts am Rendering oder an der Berechnung. Sie dient nur der Diagnose: Werkzeuge wie PIX, RenderDoc, Xcode GPU Frame Capture oder die Entwicklerwerkzeuge des Browsers zeigen das Label in der erfassten Befehlsliste an. Manche Implementierungen geben es auch in Validierungsfehlermeldungen aus.

Im Gegensatz zu pushDebugGroup()/popDebugGroup(), die einen Bereich von Befehlen einklammern, markiert insertDebugMarker() nur einen Zeitpunkt. Das eignet sich zum Beispiel, um anzuzeigen, wo eine Kopieroperation beginnt, oder um zwischen zwei Render-Durchgängen eine Orientierungshilfe zu setzen.

Die Methode gibt es auch auf GPURenderPassEncoder, GPUComputePassEncoder und GPURenderBundleEncoder (über das Mixin GPUDebugCommandsMixin). Innerhalb eines Durchgangs verwendet man den Marker des Pass-Encoders. Auf dem GPUCommandEncoder selbst ist der Aufruf nur gültig, solange gerade kein Durchgang offen ist.

Parameter

Name	Typ	Default	Beschreibung
$markerLabel Pflicht	string		Beliebiger Text, der als Name der Markierung in Debugging-Werkzeugen angezeigt wird.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert.

Beispiele

Marker vor einer Pufferkopie setzen

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

const src = device.createBuffer({ size: 256, usage: GPUBufferUsage.COPY_SRC });
const dst = device.createBuffer({ size: 256, usage: GPUBufferUsage.COPY_DST | GPUBufferUsage.MAP_READ });

const encoder = device.createCommandEncoder({ label: 'Readback-Encoder' });
// Punkt im Befehlsstrom markieren
encoder.insertDebugMarker('Kopiere Ergebnisse in Readback-Puffer');
encoder.copyBufferToBuffer(src, 0, dst, 0, 256);

device.queue.submit([encoder.finish()]);

Marker zwischen zwei Render-Durchgängen

const encoder = device.createCommandEncoder();

const shadowPass = encoder.beginRenderPass(shadowPassDescriptor);
// ... Schatten zeichnen
shadowPass.end();

// Erst nach end() ist der Aufruf auf dem Command-Encoder gültig
encoder.insertDebugMarker('Schatten fertig – starte Hauptdurchgang');

const mainPass = encoder.beginRenderPass(mainPassDescriptor);
mainPass.insertDebugMarker('Vor Draw-Call: Terrain'); // Marker des Pass-Encoders
mainPass.setPipeline(terrainPipeline);
mainPass.draw(vertexCount);
mainPass.end();

device.queue.submit([encoder.finish()]);

Marker mit Debug-Gruppen kombinieren und Fehler abfangen

device.pushErrorScope('validation');

const encoder = device.createCommandEncoder();
encoder.pushDebugGroup('Frame 42');
encoder.insertDebugMarker('Uploads abgeschlossen');
encoder.clearBuffer(dst);
encoder.popDebugGroup();
device.queue.submit([encoder.finish()]);

const error = await device.popErrorScope();
console.log(error ? error.message : 'Keine Validierungsfehler');

Keine Validierungsfehler

// Wichtig · Fallstricke

Nicht während eines offenen Durchgangs aufrufen: Ist gerade ein Render- oder Compute-Durchgang aktiv (also nach beginRenderPass() und vor end()), wird der Encoder ungültig. Die Methode wirft dabei keine Ausnahme. Der Fehler zeigt sich erst bei finish() bzw. submit() als Validierungsfehler. In diesem Fall stattdessen passEncoder.insertDebugMarker() verwenden.
Auch ein Aufruf nach finish() führt zu einem Validierungsfehler.
Marker kosten kaum Leistung. Dennoch empfiehlt es sich, sie in Produktions-Builds hinter einem Debug-Schalter zu halten.
Ob und wie Marker angezeigt werden, hängt vom Browser und Werkzeug ab. Garantiert ist keine Ausgabe.
WebGPU steht nur in sicheren Kontexten zur Verfügung. Browser-Support vor dem Einsatz mit if (!navigator.gpu) prüfen.
Keine sensiblen Daten in Labels schreiben: Sie können in Fehlermeldungen und Frame-Captures sichtbar werden.

Siehe auch

GPUCommandEncoder.pushDebugGroup() GPUCommandEncoder.popDebugGroup() GPURenderPassEncoder.insertDebugMarker() GPUComputePassEncoder.insertDebugMarker() GPUCommandEncoder GPUDevice.pushErrorScope()