WebGLRenderingContext.sampleCoverage() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.sampleCoverage(value, invert)

Beschreibung

Mit sampleCoverage() steuerst du, wie beim Multisample-Anti-Aliasing (MSAA) die Abdeckungsmaske (Coverage Mask) eines Fragments verändert wird. Der Wert value gibt an, welcher Anteil der Samples eines Pixels als abgedeckt gilt. invert kehrt die daraus erzeugte Maske um.

Die Einstellung wirkt nur, wenn gl.enable(gl.SAMPLE_COVERAGE) aktiv ist und der Framebuffer Multisampling nutzt. Beim Standard-Zeichenpuffer bedeutet das antialias: true beim Erstellen des Kontexts, bei WebGL2 auch ein Multisample-Renderbuffer. Die temporäre Maske wird bitweise UND-verknüpft mit der Abdeckung, die bei der Rasterisierung entsteht.

Typische Einsatzfälle sind Screen-Door-Transparenz ohne Sortierung (etwa beim Ein- und Ausblenden von Objekten) und Überblend-Effekte. Mit einem Paar aus normaler und invertierter Maske füllen sich zwei Objekte die Samples eines Pixels ohne Überlappung.

Die aktuellen Werte liest du mit gl.getParameter(gl.SAMPLE_COVERAGE_VALUE) und gl.getParameter(gl.SAMPLE_COVERAGE_INVERT) aus.

Parameter

Name	Typ	Default	Beschreibung
$value Pflicht	number (GLclampf)	1.0	Coverage-Wert im Bereich `0.0` bis `1.0`. Werte außerhalb werden auf diesen Bereich begrenzt.
$invert Pflicht	boolean (GLboolean)	false	Bei `true` wird die aus `value` erzeugte Maske invertiert.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined).

Beispiele

Sample Coverage aktivieren und Werte auslesen

const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl', { antialias: true });

gl.enable(gl.SAMPLE_COVERAGE);
gl.sampleCoverage(0.5, false);

console.log(gl.getParameter(gl.SAMPLE_COVERAGE_VALUE));
console.log(gl.getParameter(gl.SAMPLE_COVERAGE_INVERT));
console.log(gl.getParameter(gl.SAMPLES)); // Anzahl Samples, z. B. 4

0.5 false 4

Überblenden zweier Objekte ohne Überlappung

const drawCrossfade = (gl, drawA, drawB, t) => {
  gl.enable(gl.SAMPLE_COVERAGE);

  // Objekt A belegt einen Anteil von (1 - t) der Samples
  gl.sampleCoverage(1 - t, false);
  drawA();

  // Objekt B belegt genau die übrigen Samples
  gl.sampleCoverage(1 - t, true);
  drawB();

  // Zustand zurücksetzen
  gl.sampleCoverage(1.0, false);
  gl.disable(gl.SAMPLE_COVERAGE);
};

Prüfen, ob Multisampling überhaupt verfügbar ist

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

if (samples > 1) {
  gl.enable(gl.SAMPLE_COVERAGE);
  gl.sampleCoverage(0.25, false);
} else {
  console.warn('Kein Multisampling – sampleCoverage bleibt wirkungslos.');
}

// Wichtig · Fallstricke

Keine sichtbare Wirkung ohne MSAA: Ist gl.SAMPLES gleich 0 oder 1 (etwa bei antialias: false), passiert nichts sichtbar. Wenn du antialias: true anforderst, ist MSAA trotzdem nicht garantiert.
Die Einstellung wirkt nur, solange gl.SAMPLE_COVERAGE per gl.enable() aktiv ist. gl.SAMPLE_ALPHA_TO_COVERAGE ist ein eigener Schalter.
Die Granularität hängt von der Sample-Anzahl ab: Bei 4 Samples gibt es praktisch nur 5 Stufen. Welches Muster für einen bestimmten Wert entsteht, legt die Implementierung fest.
Die Einstellung ist globaler Zustand des Kontexts. Setze sie nach dem Zeichnen zurück auf sampleCoverage(1.0, false).
In WebGL2RenderingContext ist die Methode ebenfalls verfügbar. Alle modernen Browser unterstützen sie.

Siehe auch

WebGLRenderingContext.enable() WebGLRenderingContext.disable() WebGLRenderingContext.getParameter() WebGLRenderingContext.getContextAttributes() WebGL2RenderingContext.renderbufferStorageMultisample() WebGLRenderingContext