WebGLRenderingContext.colorMask() — Methode · JavaScript-Referenz

Signatur

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

Beschreibung

colorMask() setzt eine Schreibmaske für den Farbpuffer. Für jeden der vier Kanäle gibt ein boolescher Wert an, ob Fragment-Shader-Ausgaben und gl.clear(gl.COLOR_BUFFER_BIT) diesen Kanal verändern dürfen. Ein Kanal mit false behält einfach seinen bisherigen Wert im Framebuffer, egal was gezeichnet wird.

Typische Einsatzfälle sind:

Anaglyphen-3D (Rot/Cyan): die Szene zweimal rendern, einmal nur in den Rotkanal, einmal nur in Grün/Blau.
Stencil- oder Tiefen-Vorpass: mit colorMask(false, false, false, false) Geometrie nur in den Tiefen- oder Stencilpuffer schreiben, ohne sichtbare Farbe zu erzeugen.
Alphakanal schützen: bei einem Kontext mit alpha: true verhindern, dass halbtransparente Alphawerte ungewollt mit der HTML-Seite verrechnet werden.

Die Maske ist Teil des globalen WebGL-Zustands und bleibt wirksam, bis sie erneut gesetzt wird. Den aktuellen Wert fragt man mit gl.getParameter(gl.COLOR_WRITEMASK) ab. Das Ergebnis ist ein Array mit vier booleschen Werten.

Parameter

Name	Typ	Default	Beschreibung
$red Pflicht	boolean	true	Ob der Rotkanal geschrieben werden darf.
$green Pflicht	boolean	true	Ob der Grünkanal geschrieben werden darf.
$blue Pflicht	boolean	true	Ob der Blaukanal geschrieben werden darf.
$alpha Pflicht	boolean	true	Ob der Alphakanal geschrieben werden darf.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Maske setzen und abfragen

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

// Nur Rot und Alpha dürfen geschrieben werden
gl.colorMask(true, false, false, true);

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

[true, false, false, true]

clear() respektiert die Maske

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

// Zuerst komplett weiß löschen
gl.colorMask(true, true, true, true);
gl.clearColor(1, 1, 1, 1);
gl.clear(gl.COLOR_BUFFER_BIT);

// Jetzt nur den Blaukanal auf 0 setzen, Ergebnis: Gelb
gl.colorMask(false, false, true, false);
gl.clearColor(0, 0, 0, 1);
gl.clear(gl.COLOR_BUFFER_BIT);

const pixel = new Uint8Array(4);
gl.readPixels(0, 0, 1, 1, gl.RGBA, gl.UNSIGNED_BYTE, pixel);
console.log(pixel);

Uint8Array(4) [255, 255, 0, 255]

Anaglyphen-Rendering (Rot/Cyan)

// drawScene(eye) ist eine eigene Funktion, die die Szene
// aus Sicht des linken oder rechten Auges zeichnet
const renderAnaglyph = (gl, drawScene) => {
  gl.colorMask(true, true, true, true);
  gl.clear(gl.COLOR_BUFFER_BIT | gl.DEPTH_BUFFER_BIT);

  // Linkes Auge nur in den Rotkanal
  gl.colorMask(true, false, false, true);
  drawScene('left');

  // Tiefenpuffer leeren, damit das rechte Auge nicht verdeckt wird
  gl.clear(gl.DEPTH_BUFFER_BIT);

  // Rechtes Auge nur in Grün und Blau (Cyan)
  gl.colorMask(false, true, true, true);
  drawScene('right');

  // Zustand zurücksetzen
  gl.colorMask(true, true, true, true);
};

Tiefen-Vorpass ohne Farbausgabe

const depthPrepass = (gl, drawOpaque) => {
  gl.enable(gl.DEPTH_TEST);
  gl.colorMask(false, false, false, false); // keine Farbe schreiben
  gl.depthMask(true);
  drawOpaque(); // füllt nur den Tiefenpuffer

  gl.colorMask(true, true, true, true);
  gl.depthFunc(gl.LEQUAL);
  gl.depthMask(false);
  drawOpaque(); // Farbe nur für sichtbare Fragmente
  gl.depthMask(true);
};

// Wichtig · Fallstricke

Globaler Zustand: Die Maske bleibt auch für spätere clear()-Aufrufe aktiv. Häufiger Fehler: Nach einem Vorpass vergessen, sie auf (true, true, true, true) zurückzusetzen. Das Canvas bleibt dann scheinbar grundlos schwarz oder zeigt alte Inhalte.
Nur Farbpuffer: colorMask() wirkt nicht auf Tiefen- oder Stencilpuffer. Dafür gibt es depthMask() und stencilMask().
Alphakanal und Kompositing: Bei alpha: true (Standard) und premultipliedAlpha: true können Farbwerte über dem Alphawert zu falschen Farben beim Einblenden in die Seite führen. Wer Alpha maskiert, sollte das Ergebnis prüfen.
In WebGL 2 gilt die Maske für alle Draw-Buffers gemeinsam. Masken pro Zeichenpuffer gibt es nur über die Erweiterung OES_draw_buffers_indexed (colorMaskiOES()).
Werte, die kein Boolean sind, werden in einen Boolean umgewandelt (z. B. 0 wird zu false).
Die Methode wird in allen aktuellen Browsern mit WebGL-Unterstützung unterstützt, auch in WebGL2RenderingContext.

Siehe auch

WebGLRenderingContext.depthMask() WebGLRenderingContext.stencilMask() WebGLRenderingContext.clear() WebGLRenderingContext.clearColor() WebGLRenderingContext.getParameter() WebGLRenderingContext