WebGLRenderingContext.clear() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.clear(mask)

Beschreibung

Mit clear() setzt man einen oder mehrere Puffer des gerade gebundenen Framebuffers auf festgelegte Startwerte zurück. Normalerweise ruft man das am Anfang jedes Frames in der Render-Schleife auf, damit nichts vom vorherigen Bild übrig bleibt. Ohne Löschen bleiben alte Pixel und Tiefenwerte stehen, und Tiefentests liefern falsche Ergebnisse.

Welche Puffer gelöscht werden, bestimmt der Parameter mask. Das ist eine Bitmaske aus den Konstanten gl.COLOR_BUFFER_BIT, gl.DEPTH_BUFFER_BIT und gl.STENCIL_BUFFER_BIT. Mehrere Puffer verknüpft man mit dem bitweisen ODER (|). Die Werte, auf die zurückgesetzt wird, sind Zustand des Kontexts. Man legt sie vorher mit clearColor(), clearDepth() und clearStencil() fest. Standardwerte sind (0, 0, 0, 0) für Farbe, 1.0 für Tiefe und 0 für Stencil.

Auch andere Zustände des Kontexts wirken sich auf clear() aus: Der Scissor-Test (gl.SCISSOR_TEST mit gl.scissor()) beschränkt das Löschen auf ein Rechteck. colorMask(), depthMask() und stencilMask() legen fest, welche Kanäle bzw. Bits überhaupt beschrieben werden. Der Viewport, Dithering und das gebundene Shader-Programm spielen dagegen keine Rolle.

Parameter

Name	Typ	Default	Beschreibung
$mask Pflicht	GLbitfield (number)		Bitweise ODER-Verknüpfung der Puffer, die gelöscht werden sollen: `gl.COLOR_BUFFER_BIT`, `gl.DEPTH_BUFFER_BIT`, `gl.STENCIL_BUFFER_BIT`. Andere Bits lösen den Fehler `gl.INVALID_VALUE` aus.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Fehler meldet die Methode nicht über eine Ausnahme, sondern über gl.getError().

Beispiele

Canvas einfarbig löschen

const canvas = document.querySelector('#glcanvas');
const gl = canvas.getContext('webgl');

// Löschfarbe festlegen (RGBA, Werte 0–1)
gl.clearColor(0.1, 0.2, 0.3, 1.0);
// Farbpuffer löschen
gl.clear(gl.COLOR_BUFFER_BIT);

console.log(gl.getParameter(gl.COLOR_CLEAR_VALUE));

Float32Array(4) [0.1, 0.2, 0.3, 1]

Render-Schleife mit Farb- und Tiefenpuffer

const gl = document.querySelector('#glcanvas').getContext('webgl');

gl.enable(gl.DEPTH_TEST);
gl.clearColor(0, 0, 0, 1);
gl.clearDepth(1.0);

const render = (time) => {
  // Zu Beginn jedes Frames beide Puffer zurücksetzen
  gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);

  // ... hier Geometrie zeichnen (drawArrays/drawElements)

  requestAnimationFrame(render);
};
requestAnimationFrame(render);

Nur einen Bildausschnitt löschen (Scissor-Test)

const gl = document.querySelector('#glcanvas').getContext('webgl');

// Gesamte Fläche weiß
gl.clearColor(1, 1, 1, 1);
gl.clear(gl.COLOR_BUFFER_BIT);

// Nur ein 100×100-Rechteck unten links rot löschen
gl.enable(gl.SCISSOR_TEST);
gl.scissor(0, 0, 100, 100);
gl.clearColor(1, 0, 0, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
gl.disable(gl.SCISSOR_TEST);

Fehler bei ungültiger Maske prüfen

const gl = document.createElement('canvas').getContext('webgl');

gl.clear(0x0001); // kein gültiges Puffer-Bit
const err = gl.getError();
console.log(err === gl.INVALID_VALUE);

true

// Wichtig · Fallstricke

Reihenfolge: Die Löschwerte (clearColor usw.) müssen vor clear() gesetzt werden. clear() selbst nimmt keine Farbe als Argument.
Tiefenpuffer vergessen: Wer mit aktivem DEPTH_TEST nur COLOR_BUFFER_BIT löscht, bekommt ab dem zweiten Frame fehlende oder flackernde Geometrie. Der Stencil-Puffer ist nur vorhanden, wenn der Kontext mit { stencil: true } erzeugt wurde.
Masken wirken mit: Mit depthMask(false) oder colorMask(false, …) werden die betroffenen Puffer bzw. Kanäle nicht gelöscht. Das ist eine häufige Fehlerquelle.
Alpha und Transparenz: Ein Alpha-Wert kleiner als 1 in clearColor lässt die Webseite durch das Canvas scheinen, wenn der Kontext mit alpha: true erzeugt wurde (das ist der Standard). Mit premultipliedAlpha: true sollten die RGB-Werte vorher mit Alpha multipliert werden.
preserveDrawingBuffer: Standardmäßig löscht der Browser den Zeichenpuffer ohnehin nach jeder Darstellung. Mit preserveDrawingBuffer: true bleibt der Inhalt erhalten, und nur explizites clear() setzt ihn zurück.
Kompatibilität: Die Methode ist in allen modernen Browsern verfügbar, auch in WebGL2RenderingContext. Für Framebuffer mit mehreren Farb-Anhängen bzw. Integer-Formaten bietet WebGL 2 zusätzlich clearBufferfv(), clearBufferiv() und clearBufferuiv().

Siehe auch

WebGLRenderingContext.clearColor() WebGLRenderingContext.clearDepth() WebGLRenderingContext.clearStencil() WebGLRenderingContext.scissor() WebGLRenderingContext.colorMask() WebGLRenderingContext