WebGLRenderingContext.getContextAttributes() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.getContextAttributes()

Beschreibung

Beim Erzeugen eines WebGL-Kontexts über canvas.getContext("webgl", attribute) übergibt man Wünsche, z. B. antialias, alpha oder preserveDrawingBuffer. Der Browser muss nicht jeden Wunsch erfüllen, etwa weil die Hardware kein Multisampling unterstützt oder der Treiber einen Stencil-Puffer ohnehin anlegt. getContextAttributes() verrät, welche Einstellungen der Kontext tatsächlich verwendet.

Das zurückgegebene Objekt enthält unter anderem diese Eigenschaften:

alpha, depth, stencil: vorhandene Puffer bzw. Alphakanal
antialias: Multisampling aktiv?
premultipliedAlpha, preserveDrawingBuffer
powerPreference ("default", "low-power", "high-performance")
failIfMajorPerformanceCaveat, desynchronized und, je nach Browser, xrCompatible

Typische Einsatzfälle: Du prüfst, ob Kantenglättung wirklich aktiv ist (sonst greift ein eigenes FXAA-Verfahren als Ersatz), ob ein Stencil-Puffer für Masken bereitsteht, oder du protokollierst die Fähigkeiten zur Fehlersuche. Die Methode existiert in gleicher Form auch in WebGL2RenderingContext.

Rückgabewert

Typ

WebGLContextAttributes | null

Beschreibung

Ein einfaches Objekt mit den tatsächlichen Kontextattributen. Ist der Kontext verloren (gl.isContextLost() === true), wird null zurückgegeben.

Beispiele

Tatsächliche Attribute auslesen

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

const attrs = gl.getContextAttributes();
console.log(attrs);

{ alpha: true, antialias: true, depth: true, desynchronized: false, failIfMajorPerformanceCaveat: false, powerPreference: 'default', premultipliedAlpha: true, preserveDrawingBuffer: false, stencil: true, xrCompatible: false }

Wunsch mit Ergebnis vergleichen

const requested = { antialias: true, stencil: true, alpha: false };
const gl = document.querySelector('canvas').getContext('webgl', requested);
const actual = gl.getContextAttributes();

for (const [key, wanted] of Object.entries(requested)) {
  if (actual[key] !== wanted) {
    console.warn(`Attribut ${key}: gewünscht ${wanted}, erhalten ${actual[key]}`);
  }
}

Attribut antialias: gewünscht true, erhalten false // z. B. auf Geräten ohne MSAA

Ersatz-Kantenglättung und Absicherung gegen Kontextverlust

const canvas = document.querySelector('#scene');
const gl = canvas.getContext('webgl2') ?? canvas.getContext('webgl');

const setupRenderer = () => {
  const attrs = gl.getContextAttributes();
  if (attrs === null) {
    console.warn('WebGL-Kontext verloren – warte auf Wiederherstellung.');
    return;
  }
  const useFxaa = !attrs.antialias;
  const canMask = attrs.stencil;
  console.log({ useFxaa, canMask });
};

setupRenderer();
canvas.addEventListener('webglcontextrestored', setupRenderer);

{ useFxaa: false, canMask: true }

// Wichtig · Fallstricke

Rückgabe null: Nach einem Kontextverlust (webglcontextlost) liefert die Methode null. Vor dem Zugriff auf Eigenschaften also prüfen, z. B. mit gl.getContextAttributes()?.antialias.
Wünsche sind keine Garantie: antialias: true kann ignoriert werden. Umgekehrt kann stencil oder depth auch ohne ausdrückliche Anforderung true sein. Verlass dich immer auf den ausgelesenen Wert, nicht auf die übergebenen Optionen.
Kein Ändern möglich: Das zurückgegebene Objekt ist eine Kopie. Wenn du es änderst, wirkt sich das nicht auf den Kontext aus. Andere Attribute bekommst du nur über einen neuen Kontext auf einem neuen Canvas, denn ein zweiter getContext()-Aufruf auf demselben Canvas liefert den bestehenden Kontext zurück.
Uneinheitliche Felder: desynchronized und xrCompatible gibt es nicht in allen Browsern. Fehlen sie, sind sie undefined.
Datenschutz: Kontextattribute können zum Fingerprinting beitragen. Manche Browser (z. B. mit Tracking-Schutz) melden deshalb vereinheitlichte Werte.

Siehe auch

WebGLRenderingContext.getVertexAttrib() WebGLRenderingContext.getVertexAttribOffset() WebGLRenderingContext.getActiveAttrib() WebGLRenderingContext.getTexParameter() WebGLRenderingContext.vertexAttribPointer()