WebGL2RenderingContext.isQuery() — Methode · JavaScript-Referenz

Signatur

WebGL2RenderingContext.prototype.isQuery(query)

Beschreibung

Mit isQuery() prüfst du, ob ein WebGLQuery-Objekt im aktuellen Kontext noch gültig ist. Query-Objekte nutzt man in WebGL 2 für asynchrone Abfragen an die GPU, zum Beispiel für Occlusion Queries (gl.ANY_SAMPLES_PASSED, gl.ANY_SAMPLES_PASSED_CONSERVATIVE) oder Transform-Feedback-Zählungen (gl.TRANSFORM_FEEDBACK_PRIMITIVES_WRITTEN). Mit der Erweiterung EXT_disjoint_timer_query_webgl2 kommen noch GPU-Zeitmessungen dazu.

Die Methode gibt false zurück, wenn:

das Objekt mit gl.deleteQuery() gelöscht wurde,
der Kontext verloren gegangen ist (webglcontextlost),
das Objekt aus einem anderen WebGL-Kontext stammt,
null übergeben wurde.

Nach OpenGL-ES-3.0-Semantik wird ein mit createQuery() erzeugter Name erst beim ersten beginQuery() zu einem echten Query-Objekt. Deshalb gibt isQuery() direkt nach createQuery() in vielen Implementierungen noch false zurück. Verlässlich ist das Ergebnis erst, nachdem die Query einmal mit beginQuery() gebunden wurde.

In der Praxis brauchst du isQuery() vor allem für Debugging, für Sicherheitsprüfungen in Ressourcen-Managern und für Aufräum-Routinen, zum Beispiel nach einem Kontextverlust.

Parameter

Name	Typ	Default	Beschreibung
$query Pflicht	WebGLQuery \| null		Das zu prüfende Query-Objekt, typischerweise aus `gl.createQuery()`. Bei `null` ist das Ergebnis `false`.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn query ein gültiges Query-Objekt dieses Kontexts ist, sonst false.

Beispiele

Lebenszyklus einer Query prüfen

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

const query = gl.createQuery();
console.log('nach createQuery:', gl.isQuery(query));

gl.beginQuery(gl.ANY_SAMPLES_PASSED, query);
gl.endQuery(gl.ANY_SAMPLES_PASSED);
console.log('nach beginQuery:', gl.isQuery(query));

gl.deleteQuery(query);
console.log('nach deleteQuery:', gl.isQuery(query));

nach createQuery: false (je nach Implementierung) nach beginQuery: true nach deleteQuery: false

Occlusion Query mit Gültigkeitsprüfung auswerten

const gl = document.querySelector('canvas').getContext('webgl2');
const query = gl.createQuery();

const drawBoundingBox = () => { /* Bounding-Box-Geometrie zeichnen */ };

function renderFrame() {
  gl.beginQuery(gl.ANY_SAMPLES_PASSED_CONSERVATIVE, query);
  drawBoundingBox();
  gl.endQuery(gl.ANY_SAMPLES_PASSED_CONSERVATIVE);
  requestAnimationFrame(checkResult);
}

function checkResult() {
  // Nach Kontextverlust oder deleteQuery() nicht weiterarbeiten
  if (!gl.isQuery(query)) return;

  const available = gl.getQueryParameter(query, gl.QUERY_RESULT_AVAILABLE);
  if (available) {
    const visible = gl.getQueryParameter(query, gl.QUERY_RESULT);
    console.log('Objekt sichtbar:', visible);
  } else {
    requestAnimationFrame(checkResult);
  }
}

renderFrame();

Objekt sichtbar: true

Aufräumen in einem Query-Pool

class QueryPool {
  constructor(gl) {
    this.gl = gl;
    this.queries = new Set();
  }
  acquire() {
    const q = this.gl.createQuery();
    this.queries.add(q);
    return q;
  }
  dispose() {
    for (const q of this.queries) {
      // Nur gültige Objekte löschen
      if (this.gl.isQuery(q)) this.gl.deleteQuery(q);
    }
    this.queries.clear();
  }
}

const gl = document.createElement('canvas').getContext('webgl2');
const pool = new QueryPool(gl);
const q = pool.acquire();
gl.beginQuery(gl.ANY_SAMPLES_PASSED, q);
gl.endQuery(gl.ANY_SAMPLES_PASSED);
pool.dispose();
console.log(gl.isQuery(q));

false

// Wichtig · Fallstricke

Nur in WebGL 2: Die Methode gibt es nur auf WebGL2RenderingContext. In WebGL 1 bietet die Erweiterung EXT_disjoint_timer_query stattdessen ext.isQueryEXT() an.
Direkt nach createQuery(): Hier kann false zurückkommen, obwohl das Objekt nicht null ist. Prüfe die Gültigkeit also nicht sofort nach dem Erzeugen, um eine erfolgreiche Erstellung festzustellen. Dafür reicht ein Vergleich mit null.
Falscher Typ: Wenn du etwas anderes als ein WebGLQuery oder null übergibst (etwa ein WebGLBuffer), wirft der Browser einen TypeError.
Kontextverlust: Nach webglcontextlost liefern alle is*()-Methoden false. Nach der Wiederherstellung musst du die Queries neu erzeugen.
Leistung: Wie andere is*()-Aufrufe kann isQuery() eine Synchronisation mit dem GPU-Prozess auslösen. Rufe die Methode deshalb nicht in engen Render-Schleifen auf. Besser ist es, den Zustand selbst im JavaScript-Code mitzuführen.
Kompatibilität: Aktuelle Versionen von Chrome, Edge, Firefox und Safari (ab 15) unterstützen die Methode.

Siehe auch

WebGL2RenderingContext.createQuery() WebGL2RenderingContext.deleteQuery() WebGL2RenderingContext.beginQuery() WebGL2RenderingContext.endQuery() WebGL2RenderingContext.getQueryParameter() WebGLQuery