WebGLRenderingContext.blendColor() — Methode · JavaScript-Referenz

Signatur

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

Beschreibung

Mit blendColor() legt man eine konstante Farbe fest, auf die die Blending-Stufe von WebGL zugreifen kann. Die MDN-Kurzbeschreibung, laut der hier die Quell- und Ziel-Mischfaktoren gesetzt werden, stimmt so nicht ganz: Diese Faktoren legt man mit blendFunc() bzw. blendFuncSeparate() fest. blendColor() gibt nur den Farbwert vor, den die Faktoren gl.CONSTANT_COLOR, gl.ONE_MINUS_CONSTANT_COLOR, gl.CONSTANT_ALPHA und gl.ONE_MINUS_CONSTANT_ALPHA verwenden.

Typische Einsätze sind globale Überblendungen (z. B. ein ganzes Objekt mit 30 % Deckkraft zeichnen, ohne den Shader oder die Texturen zu ändern), Einfärben (Tint) über einen konstanten Farbfaktor und Ein- und Ausblend-Übergänge zwischen zwei Szenen. Die Konstante ist Teil des globalen WebGL-Zustands. Sie gilt also für alle folgenden Zeichenaufrufe, bis man sie erneut setzt.

Damit die Farbe überhaupt wirkt, muss Blending mit gl.enable(gl.BLEND) eingeschaltet sein, und blendFunc()/blendFuncSeparate() muss einen der konstanten Faktoren verwenden. Der aktuelle Wert lässt sich mit gl.getParameter(gl.BLEND_COLOR) auslesen. Voreingestellt ist [0, 0, 0, 0].

Parameter

Name	Typ	Beschreibung
$red Pflicht	number (GLclampf)	Rot-Anteil der konstanten Mischfarbe, 0 bis 1.
$green Pflicht	number (GLclampf)	Grün-Anteil der konstanten Mischfarbe, 0 bis 1.
$blue Pflicht	number (GLclampf)	Blau-Anteil der konstanten Mischfarbe, 0 bis 1.
$alpha Pflicht	number (GLclampf)	Alpha-Anteil der konstanten Mischfarbe, 0 bis 1. Wird von `CONSTANT_ALPHA` und `ONE_MINUS_CONSTANT_ALPHA` verwendet.

Rückgabewert

Typ

undefined

Beschreibung

Kein Rückgabewert. Die Methode ändert nur den WebGL-Zustand.

Beispiele

Objekt mit globaler Deckkraft zeichnen

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

// Blending aktivieren und die konstante Alpha als Faktor verwenden
gl.enable(gl.BLEND);
gl.blendColor(0, 0, 0, 0.3); // 30 % Deckkraft
gl.blendFunc(gl.CONSTANT_ALPHA, gl.ONE_MINUS_CONSTANT_ALPHA);

gl.clearColor(1, 1, 1, 1);
gl.clear(gl.COLOR_BUFFER_BIT);
// ... Shader-Programm binden und gl.drawArrays(...) aufrufen
// Die Geometrie erscheint nun mit 30 % Deckkraft über dem Hintergrund.

Aktuelle Mischfarbe auslesen

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

console.log(gl.getParameter(gl.BLEND_COLOR));
gl.blendColor(1, 0.5, 0.25, 1);
console.log(gl.getParameter(gl.BLEND_COLOR));

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

Szenenübergang: Einblenden über mehrere Frames

const gl = document.querySelector('canvas').getContext('webgl');
gl.enable(gl.BLEND);
gl.blendFunc(gl.CONSTANT_ALPHA, gl.ONE_MINUS_CONSTANT_ALPHA);

const drawScene = () => {
  // ... Geometrie der neuen Szene zeichnen (gl.drawArrays/drawElements)
};

const start = performance.now();
const dauer = 1000; // 1 Sekunde

const frame = (now) => {
  const t = Math.min((now - start) / dauer, 1);
  gl.blendColor(0, 0, 0, t); // Deckkraft von 0 auf 1
  drawScene();
  if (t < 1) requestAnimationFrame(frame);
};
requestAnimationFrame(frame);

Einfärben mit einem konstanten Farbfaktor

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

// Quellfarbe komponentenweise mit der Konstante multiplizieren (Rot-Stich)
gl.blendColor(1.0, 0.4, 0.4, 1.0);
gl.blendFunc(gl.CONSTANT_COLOR, gl.ZERO);
// ... gl.drawArrays(...) – gezeichnete Pixel erscheinen rötlich getönt

// Wichtig · Fallstricke

Wirkt nur mit passenden Faktoren: Ohne gl.enable(gl.BLEND) und ohne einen CONSTANT_*-Faktor in blendFunc()/blendFuncSeparate() hat blendColor() keine sichtbare Wirkung.
WebGL-1-Einschränkung: Wird CONSTANT_COLOR bzw. ONE_MINUS_CONSTANT_COLOR als Quellfaktor und CONSTANT_ALPHA bzw. ONE_MINUS_CONSTANT_ALPHA als Zielfaktor verwendet (oder umgekehrt), löst blendFunc() den Fehler gl.INVALID_OPERATION aus. Prüfen lässt sich das mit gl.getError().
Wertebereich: Die Werte werden auf 0–1 begrenzt (GLclampf). Werte außerhalb dieses Bereichs werden stillschweigend abgeschnitten.
Globaler Zustand: Die Konstante bleibt gesetzt, bis man sie neu setzt. Wer mehrere Render-Durchgänge oder Bibliotheken kombiniert, sollte sie vor jedem Zeichenaufruf gezielt setzen oder danach zurücksetzen.
Vormultipliziertes Alpha: Ist der Canvas mit premultipliedAlpha: true angelegt (Standard), müssen die Farben dazu passen. Sonst entstehen beim Zusammensetzen mit der Seite helle oder dunkle Ränder.
Kompatibilität: Die Methode wird in allen modernen Browsern unterstützt und steht genauso in WebGL2RenderingContext zur Verfügung.

Siehe auch

WebGLRenderingContext.blendFunc() WebGLRenderingContext.blendFuncSeparate() WebGLRenderingContext.blendEquation() WebGLRenderingContext.enable() WebGLRenderingContext.getParameter() WebGLRenderingContext