WebGLRenderingContext.clearColor() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.clearColor(red, green, blue, alpha)

Beschreibung

clearColor() legt die Löschfarbe des WebGL-Kontexts fest. Die Methode löscht selbst nichts. Sie setzt nur einen Zustandswert, den der nächste Aufruf von gl.clear(gl.COLOR_BUFFER_BIT) verwendet. Die Farbe bleibt gültig, bis sie erneut gesetzt wird. Deshalb reicht es, sie einmal bei der Initialisierung zu setzen, wenn sie sich nicht ändert.

Die Farbwerte werden als Gleitkommazahlen im Bereich 0.0 bis 1.0 übergeben, nicht als 0–255 wie bei CSS. Werte außerhalb dieses Bereichs werden in WebGL 1 auf [0, 1] begrenzt. Der Standardwert ist (0, 0, 0, 0), also transparentes Schwarz.

Typischerweise ruft man clearColor() und clear() am Anfang jedes Frames in der Render-Schleife auf. So wird der Inhalt des vorherigen Bildes entfernt, bevor neu gezeichnet wird. Der aktuelle Wert lässt sich mit gl.getParameter(gl.COLOR_CLEAR_VALUE) auslesen.

Parameter

Name	Typ	Beschreibung
$red Pflicht	number	Rotanteil der Löschfarbe, `0.0`–`1.0`.
$green Pflicht	number	Grünanteil der Löschfarbe, `0.0`–`1.0`.
$blue Pflicht	number	Blauanteil der Löschfarbe, `0.0`–`1.0`.
$alpha Pflicht	number	Alpha-Wert (Deckkraft) der Löschfarbe, `0.0` (transparent) bis `1.0` (deckend).

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Canvas mit Farbe füllen

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

if (!gl) {
  throw new Error('WebGL wird nicht unterstützt');
}

// Dunkles Blaugrau, voll deckend
gl.clearColor(0.1, 0.15, 0.2, 1.0);
gl.clear(gl.COLOR_BUFFER_BIT);

Aktuelle Löschfarbe auslesen

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

gl.clearColor(1, 0.5, 0, 1);
const farbe = gl.getParameter(gl.COLOR_CLEAR_VALUE);
console.log(farbe);

Float32Array(4) [1, 0.5, 0, 1]

Render-Schleife mit animierter Hintergrundfarbe

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

const render = (zeit) => {
  const t = zeit / 1000;
  const r = (Math.sin(t) + 1) / 2; // pendelt zwischen 0 und 1

  gl.viewport(0, 0, gl.drawingBufferWidth, gl.drawingBufferHeight);
  gl.clearColor(r, 0.2, 1 - r, 1.0);
  gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);

  // ... hier Geometrie zeichnen ...
  requestAnimationFrame(render);
};

requestAnimationFrame(render);

Hex-Farbe in clearColor-Werte umrechnen

const hexZuGl = (hex) => {
  const n = parseInt(hex.replace('#', ''), 16);
  return [(n >> 16 & 255) / 255, (n >> 8 & 255) / 255, (n & 255) / 255];
};

const gl = document.createElement('canvas').getContext('webgl');
const [r, g, b] = hexZuGl('#3366cc');
gl.clearColor(r, g, b, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
console.log([r, g, b].map((v) => v.toFixed(2)));

["0.20", "0.40", "0.80"]

// Wichtig · Fallstricke

Häufiger Fehler: Farbwerte im Bereich 0–255 statt 0–1 übergeben. gl.clearColor(255, 0, 0, 1) funktioniert zwar zufällig, weil der Wert auf 1 begrenzt wird, aber Zwischenwerte wie 128 ergeben ebenfalls volle Intensität.
clearColor() allein zeigt keine Wirkung. Erst gl.clear(gl.COLOR_BUFFER_BIT) wendet die Farbe an.
Ein Alpha-Wert unter 1.0 macht den Canvas durchsichtig, sodass der Seitenhintergrund durchscheint. Das gilt, solange der Kontext mit alpha: true erstellt wurde, was der Standard ist. Bei premultipliedAlpha: true (ebenfalls Standard) sollten die RGB-Werte nicht größer als der Alpha-Wert sein, sonst entstehen undefinierte Farbwerte.
Das Löschen wird durch gl.colorMask() und bei aktiviertem SCISSOR_TEST durch gl.scissor() eingeschränkt.
Ist der Kontext verloren (webglcontextlost), wird der Aufruf still ignoriert.
Auch in WebGL2RenderingContext verfügbar. Für Integer-Farbpuffer in WebGL 2 stattdessen clearBufferiv()/clearBufferuiv() verwenden.

Siehe auch

WebGLRenderingContext.clear() WebGLRenderingContext.clearDepth() WebGLRenderingContext.clearStencil() WebGLRenderingContext.colorMask() WebGLRenderingContext.getParameter() WebGLRenderingContext