WebGLRenderingContext.getParameter() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.getParameter(pname)

Beschreibung

getParameter() ist die zentrale Abfragemethode für den Zustand eines WebGL-Kontexts. Du übergibst eine Konstante wie gl.MAX_TEXTURE_SIZE, gl.VIEWPORT oder gl.CURRENT_PROGRAM und bekommst den passenden Wert zurück. Das kann eine Zahl, ein Boolean, ein String, ein typisiertes Array oder ein WebGL-Objekt wie WebGLProgram oder WebGLBuffer sein.

Typische Anwendungsfälle sind:

Grenzen der Hardware prüfen, etwa die maximale Texturgröße, die Zahl der Vertex-Attribute oder der Textur-Einheiten. So kannst du Qualitätsstufen oder Rückfallpfade festlegen.
Den aktuellen Zustand auslesen, z. B. Viewport, Clear-Farbe, Blend-Modus oder gebundene Puffer, um ihn in Bibliotheken zu sichern und später wiederherzustellen.
Diagnose und Logging, z. B. mit gl.VERSION, gl.SHADING_LANGUAGE_VERSION, gl.VENDOR und gl.RENDERER.

Die Methode gibt es auch in WebGL2RenderingContext. Dort sind zusätzliche Konstanten erlaubt, etwa gl.MAX_3D_TEXTURE_SIZE oder gl.MAX_SAMPLES. Welchen Typ der Rückgabewert hat, hängt vom Parameter ab: Vektoren kommen als Int32Array oder Float32Array zurück, Farbmasken als Array von Booleans.

Parameter

Name	Typ	Default	Beschreibung
$pname Pflicht	GLenum (number)		Konstante für den gewünschten Parameter, z. B. `gl.MAX_TEXTURE_SIZE`, `gl.VIEWPORT`, `gl.BLEND`, `gl.ARRAY_BUFFER_BINDING`, `gl.VERSION`. Mit Erweiterungen kommen weitere Konstanten hinzu, z. B. `ext.UNMASKED_RENDERER_WEBGL`.

Rückgabewert

Typ

Beschreibung

Der Wert des angefragten Parameters. Der Typ hängt von pname ab. Bei einem ungültigen pname gibt die Methode null zurück und setzt den Fehler gl.INVALID_ENUM. Den Fehler kannst du mit gl.getError() abfragen.

Beispiele

Grenzen der Hardware abfragen

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

if (!gl) {
  console.log('WebGL wird nicht unterstützt');
} else {
  const limits = {
    maxTextureSize: gl.getParameter(gl.MAX_TEXTURE_SIZE),
    maxVertexAttribs: gl.getParameter(gl.MAX_VERTEX_ATTRIBS),
    maxTextureUnits: gl.getParameter(gl.MAX_TEXTURE_IMAGE_UNITS),
    maxViewport: gl.getParameter(gl.MAX_VIEWPORT_DIMS) // Int32Array [w, h]
  };
  console.log(limits);
}

{ maxTextureSize: 16384, maxVertexAttribs: 16, maxTextureUnits: 16, maxViewport: Int32Array(2) [32767, 32767] }

Zustand sichern und wiederherstellen

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

const withSavedState = (gl, fn) => {
  // Aktuellen Zustand merken
  const viewport = gl.getParameter(gl.VIEWPORT);          // Int32Array
  const clearColor = gl.getParameter(gl.COLOR_CLEAR_VALUE); // Float32Array
  const blend = gl.getParameter(gl.BLEND);                // boolean
  const program = gl.getParameter(gl.CURRENT_PROGRAM);    // WebGLProgram | null

  fn();

  // Zustand wiederherstellen
  gl.viewport(...viewport);
  gl.clearColor(...clearColor);
  blend ? gl.enable(gl.BLEND) : gl.disable(gl.BLEND);
  gl.useProgram(program);
};

withSavedState(gl, () => {
  gl.viewport(0, 0, 64, 64);
  gl.clearColor(1, 0, 0, 1);
  gl.clear(gl.COLOR_BUFFER_BIT);
});

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

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

Versions- und GPU-Informationen auslesen

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

console.log(gl.getParameter(gl.VERSION));
console.log(gl.getParameter(gl.SHADING_LANGUAGE_VERSION));

// Echten GPU-Namen nur über die Erweiterung (falls verfügbar)
const dbg = gl.getExtension('WEBGL_debug_renderer_info');
const renderer = dbg
  ? gl.getParameter(dbg.UNMASKED_RENDERER_WEBGL)
  : gl.getParameter(gl.RENDERER);
console.log(renderer);

WebGL 1.0 (OpenGL ES 2.0 Chromium) WebGL GLSL ES 1.0 (OpenGL ES GLSL ES 1.0 Chromium) ANGLE (NVIDIA, NVIDIA GeForce RTX 3060 Direct3D11 vs_5_0 ps_5_0, D3D11)

Ungültigen Parameter erkennen

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

// Eine WebGL2-Konstante in einem WebGL1-Kontext abfragen
const value = gl.getParameter(0x8073); // MAX_3D_TEXTURE_SIZE
console.log(value, gl.getError() === gl.INVALID_ENUM);

null true

// Wichtig · Fallstricke

Leistung: Jeder Aufruf von getParameter() kann die GPU-Pipeline synchronisieren, besonders in Chrome mit GPU-Prozess und bei ANGLE. Vermeide Aufrufe in der Render-Schleife. Frage Grenzen einmal beim Start ab und speichere sie. Den Zustand verfolgst du besser selbst in JavaScript.
Kopien statt Referenzen: Typisierte Arrays wie VIEWPORT oder COLOR_CLEAR_VALUE sind Momentaufnahmen. Wenn du sie veränderst, ändert sich der GL-Zustand nicht.
Ungültige Konstanten: Die Methode wirft keine Ausnahme. Sie gibt null zurück und setzt INVALID_ENUM. WebGL2-Konstanten funktionieren in einem WebGL1-Kontext nur mit der passenden Erweiterung.
Datenschutz und Fingerprinting: gl.VENDOR und gl.RENDERER liefern meist nur allgemeine Werte wie „WebKit“ oder „WebKit WebGL“. UNMASKED_RENDERER_WEBGL aus WEBGL_debug_renderer_info kann Firefox (mit resistFingerprinting) blockieren. Andere Browser können den Wert verschleiern oder die Erweiterung als veraltet markieren. Verlass dich für Funktionsentscheidungen nicht darauf.
Kontextverlust: Nach webglcontextlost gibt getParameter() null zurück.
Kompatibilität: Wird in allen modernen Browsern unterstützt. In Web Workers ist die Methode über OffscreenCanvas verfügbar.

Siehe auch

WebGLRenderingContext WebGL2RenderingContext WebGLRenderingContext.getError() WebGLRenderingContext.getExtension() WebGLRenderingContext.getProgramParameter() WebGLRenderingContext.getTexParameter() HTMLCanvasElement.getContext()