GPUComputePassEncoder.insertDebugMarker() — Methode · JavaScript-Referenz

Signatur

GPUComputePassEncoder.prototype.insertDebugMarker(markerLabel)

Beschreibung

insertDebugMarker() setzt einen einzelnen, punktuellen Marker mit frei wählbarem Text in den Befehlsstrom eines GPUComputePassEncoder. Im Unterschied zu pushDebugGroup()/popDebugGroup(), die einen Bereich von Befehlen einklammern, kennzeichnet der Marker genau einen Zeitpunkt, etwa „vor dem Dispatch des Partikel-Updates“.

Solche Marker werden von nativen Grafik-Debuggern und Profilern (z. B. PIX, RenderDoc, Xcode GPU Frame Capture) angezeigt und helfen dabei, im aufgezeichneten Befehlsstrom schnell die Stelle zu finden, die zum eigenen Code gehört. Auch Validierungsfehlermeldungen des Browsers können den Kontext von Debug-Labels mit angeben.

Auf die Programmlogik oder die Ergebnisse der Berechnung hat die Methode keinen Einfluss. Sie ist also reines Hilfsmittel beim Entwickeln und kann in Produktions-Builds ohne Folgen weggelassen werden.

Parameter

Name	Typ	Default	Beschreibung
$markerLabel Pflicht	string		Text des Markers, z. B. `"Dispatch: Blur horizontal"`. Er erscheint unverändert in Debugging-Werkzeugen.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert.

Beispiele

Marker vor einem Dispatch setzen

const adapter = await navigator.gpu.requestAdapter();
const device = await adapter.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) {
      if (id.x < arrayLength(&data)) { data[id.x] = data[id.x] * 2.0; }
    }`
});

const pipeline = device.createComputePipeline({
  layout: 'auto',
  compute: { module, entryPoint: 'main' }
});

const buffer = device.createBuffer({
  size: 1024 * 4,
  usage: GPUBufferUsage.STORAGE
});

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

const encoder = device.createCommandEncoder();
const pass = encoder.beginComputePass({ label: 'Verdoppeln-Pass' });
pass.setPipeline(pipeline);
pass.setBindGroup(0, bindGroup);

// Punktuelle Markierung im Befehlsstrom
pass.insertDebugMarker('Dispatch: Werte verdoppeln');
pass.dispatchWorkgroups(Math.ceil(1024 / 64));
pass.end();

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

Marker innerhalb einer Debug-Gruppe kombinieren

// Annahme: device, pipelineA, pipelineB, bindGroup existieren bereits
const encoder = device.createCommandEncoder();
const pass = encoder.beginComputePass();

pass.pushDebugGroup('Bildfilter');

pass.setBindGroup(0, bindGroup);
pass.setPipeline(pipelineA);
pass.insertDebugMarker('Blur horizontal');
pass.dispatchWorkgroups(32, 32);

pass.setPipeline(pipelineB);
pass.insertDebugMarker('Blur vertikal');
pass.dispatchWorkgroups(32, 32);

pass.popDebugGroup();
pass.end();

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

Marker nur im Entwicklungsmodus einfügen

const DEBUG = location.hostname === 'localhost';

const mark = (pass, text) => {
  if (DEBUG) pass.insertDebugMarker(text);
};

// Verwendung in einer Simulationsschleife
const runSimulation = (device, pipeline, bindGroup, steps) => {
  const encoder = device.createCommandEncoder();
  const pass = encoder.beginComputePass();
  pass.setPipeline(pipeline);
  pass.setBindGroup(0, bindGroup);
  for (let i = 0; i < steps; i++) {
    mark(pass, `Simulationsschritt ${i}`);
    pass.dispatchWorkgroups(256);
  }
  pass.end();
  device.queue.submit([encoder.finish()]);
};

// Wichtig · Fallstricke

Kein Einfluss auf das Ergebnis: Marker sind reine Metadaten. Ob und wie sie angezeigt werden, hängt vom Browser und vom verwendeten GPU-Werkzeug ab. In den DevTools des Browsers erscheinen sie in der Regel nicht.
Nur auf offenen Pässen: Wird die Methode nach end() aufgerufen, ist der Encoder ungültig. Es wird dann keine Ausnahme geworfen, sondern ein Validierungsfehler erzeugt, der erst bei finish()/submit() oder über device.pushErrorScope('validation') sichtbar wird.
Marker oder Gruppe: Für Bereiche nimm pushDebugGroup()/popDebugGroup(). Jeder push braucht innerhalb desselben Passes einen passenden pop, für insertDebugMarker() gilt diese Regel nicht.
Datenschutz/Leistung: Schreib keine sensiblen Daten in Marker-Texte. Marker in sehr engen Schleifen erzeugen außerdem etwas Mehraufwand beim Kodieren, deshalb solltest du sie in Produktions-Builds abschalten.
Kompatibilität: WebGPU ist nicht überall verfügbar. Prüfe vorher mit if (!navigator.gpu) und nutze nur sichere Kontexte (HTTPS).

Siehe auch

GPUComputePassEncoder GPUComputePassEncoder.pushDebugGroup() GPUComputePassEncoder.popDebugGroup() GPUComputePassEncoder.dispatchWorkgroups() GPURenderPassEncoder.insertDebugMarker() GPUCommandEncoder.insertDebugMarker()