WebGL2RenderingContext.isSync() — Methode · JavaScript-Referenz

Signatur

WebGL2RenderingContext.prototype.isSync(sync)

Beschreibung

Die Methode isSync() des WebGL2RenderingContext prüft, ob ein Wert ein gültiges Sync-Objekt ist. Sync-Objekte (Fences) legt man mit fenceSync() an. Mit ihnen lässt sich feststellen, ob die GPU alle Befehle bis zu einem bestimmten Punkt im Befehlsstrom abgearbeitet hat.

Das ist vor allem bei der Ressourcenverwaltung nützlich. Bevor du clientWaitSync(), getSyncParameter() oder deleteSync() aufrufst, kannst du absichern, dass das Objekt noch existiert und zum aktuellen Kontext gehört. So vermeidest du WebGL-Fehler wie INVALID_VALUE oder INVALID_OPERATION.

Die Methode gibt false zurück, wenn das Objekt mit deleteSync() gelöscht wurde, wenn null übergeben wird oder wenn der Kontext verloren gegangen ist (webglcontextlost). Sie sagt nichts darüber aus, ob das Sync-Objekt schon signalisiert ist. Dafür brauchst du getSyncParameter(sync, gl.SYNC_STATUS) oder clientWaitSync().

Parameter

Name	Typ	Default	Beschreibung
$sync Pflicht	WebGLSync \| null		Das zu prüfende Objekt, normalerweise ein Rückgabewert von `fenceSync()`.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn sync ein gültiges, nicht gelöschtes WebGLSync-Objekt ist, sonst false.

Beispiele

Sync-Objekt anlegen, prüfen und löschen

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

if (!gl) {
  console.log('WebGL 2 wird nicht unterstützt');
} else {
  const sync = gl.fenceSync(gl.SYNC_GPU_COMMANDS_COMPLETE, 0);
  console.log(gl.isSync(sync)); // gültig

  gl.deleteSync(sync);
  console.log(gl.isSync(sync)); // nach dem Löschen ungültig
  console.log(gl.isSync(null));
}

true false false

Nicht blockierend auf die GPU warten (Polling)

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

const waitForGpu = (gl) => new Promise((resolve, reject) => {
  const sync = gl.fenceSync(gl.SYNC_GPU_COMMANDS_COMPLETE, 0);
  gl.flush(); // Befehle sicher an die GPU senden

  const poll = () => {
    if (!gl.isSync(sync)) {
      reject(new Error('Sync-Objekt ungültig (Kontext verloren?)'));
      return;
    }
    const status = gl.clientWaitSync(sync, 0, 0);
    if (status === gl.WAIT_FAILED) {
      gl.deleteSync(sync);
      reject(new Error('clientWaitSync fehlgeschlagen'));
    } else if (status === gl.TIMEOUT_EXPIRED) {
      requestAnimationFrame(poll);
    } else {
      gl.deleteSync(sync);
      resolve();
    }
  };
  poll();
});

(async () => {
  gl.clearColor(0, 0, 1, 1);
  gl.clear(gl.COLOR_BUFFER_BIT);
  await waitForGpu(gl);
  console.log('GPU fertig');
})();

GPU fertig

Sicheres Aufräumen in einer Ressourcenverwaltung

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

const track = () => {
  const sync = gl.fenceSync(gl.SYNC_GPU_COMMANDS_COMPLETE, 0);
  pendingSyncs.add(sync);
  return sync;
};

const cleanup = () => {
  for (const sync of pendingSyncs) {
    if (gl.isSync(sync)) gl.deleteSync(sync);
  }
  pendingSyncs.clear();
};

track();
track();
console.log('Offen:', pendingSyncs.size);
cleanup();
console.log('Offen:', pendingSyncs.size);

Offen: 2 Offen: 0

// Wichtig · Fallstricke

Nicht mit dem Status verwechseln: isSync() prüft nur, ob das Objekt gültig ist. Ob der Fence schon signalisiert ist, erfährst du über getSyncParameter(sync, gl.SYNC_STATUS) (gl.SIGNALED / gl.UNSIGNALED).
Nur in WebGL 2: In einem WebGLRenderingContext (WebGL 1) gibt es die Methode nicht. Prüfe vorher, ob getContext('webgl2') ein Objekt zurückgibt.
Kontextverlust: Nach webglcontextlost liefert isSync() für alle Objekte false. Nach der Wiederherstellung musst du Sync-Objekte neu anlegen.
Anderer Kontext: Ein Sync-Objekt aus einem anderen WebGL-Kontext gilt als ungültig. Übergibst du einen Wert, der kein WebGLSync ist (z. B. einen WebGLBuffer), wirft die Methode einen TypeError.
Leistung: Häufige Abfragen des GPU-Zustands können die Pipeline bremsen. Sync-Objekte sparsam einsetzen und nicht mehr benötigte mit deleteSync() freigeben.
Browser-Kompatibilität: Wird in allen aktuellen Browsern mit WebGL 2 unterstützt (Chrome 56+, Firefox 51+, Safari 15+).

Siehe auch

WebGL2RenderingContext.fenceSync() WebGL2RenderingContext.deleteSync() WebGL2RenderingContext.clientWaitSync() WebGL2RenderingContext.waitSync() WebGL2RenderingContext.getSyncParameter() WebGLSync WebGL2RenderingContext