WebGLRenderingContext.validateProgram() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.validateProgram(program)

Beschreibung

Die Methode validateProgram() prüft, ob ein bereits gelinktes WebGLProgram mit dem aktuellen Zustand des WebGL-Kontexts ausgeführt werden kann. Dazu gehören zum Beispiel die Belegung der Textur-Einheiten: Samplern unterschiedlichen Typs (etwa sampler2D und samplerCube) darf nicht dieselbe Textur-Einheit zugewiesen sein.

Die Methode gibt selbst nichts zurück. Das Ergebnis fragt man danach mit gl.getProgramParameter(program, gl.VALIDATE_STATUS) ab. Details zu einem Fehler liefert gl.getProgramInfoLog(program).

Gedacht ist validateProgram() vor allem für die Entwicklung und Fehlersuche. Rufen Sie die Methode direkt vor einem Zeichenaufruf auf, wenn alle Uniforms und Texturen gesetzt sind. Direkt nach linkProgram() ist das Ergebnis weniger aussagekräftig. Im Produktivcode sollte die Methode nicht in jedem Frame laufen, weil sie Leistung kostet.

Parameter

Name	Typ	Default	Beschreibung
$program Pflicht	WebGLProgram		Das zu prüfende, bereits mit `linkProgram()` gelinkte Programm-Objekt.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Das Ergebnis steht danach in getProgramParameter(program, gl.VALIDATE_STATUS).

Beispiele

Programm linken und validieren

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

const compile = (type, source) => {
  const shader = gl.createShader(type);
  gl.shaderSource(shader, source);
  gl.compileShader(shader);
  if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
    throw new Error(gl.getShaderInfoLog(shader));
  }
  return shader;
};

const vs = compile(gl.VERTEX_SHADER, `
  attribute vec2 position;
  void main() { gl_Position = vec4(position, 0.0, 1.0); }
`);
const fs = compile(gl.FRAGMENT_SHADER, `
  precision mediump float;
  void main() { gl_FragColor = vec4(1.0, 0.5, 0.0, 1.0); }
`);

const program = gl.createProgram();
gl.attachShader(program, vs);
gl.attachShader(program, fs);
gl.linkProgram(program);

if (!gl.getProgramParameter(program, gl.LINK_STATUS)) {
  throw new Error(gl.getProgramInfoLog(program));
}

gl.validateProgram(program);
console.log('Gültig:', gl.getProgramParameter(program, gl.VALIDATE_STATUS));

Gültig: true

Hilfsfunktion zur Validierung nur im Entwicklungsmodus

const DEBUG = true;

const checkProgram = (gl, program) => {
  if (!DEBUG) return true;
  gl.validateProgram(program);
  const ok = gl.getProgramParameter(program, gl.VALIDATE_STATUS);
  if (!ok) {
    console.warn('Programm ungültig:', gl.getProgramInfoLog(program));
  }
  return ok;
};

// Aufruf direkt vor dem Zeichnen, wenn Uniforms und Texturen gesetzt sind
// gl.useProgram(program);
// if (checkProgram(gl, program)) gl.drawArrays(gl.TRIANGLES, 0, 3);

Sampler-Konflikt aufdecken

// Voraussetzung: program enthält die Uniforms 'uTex' (sampler2D) und 'uEnv' (samplerCube)
const setupAndValidate = (gl, program) => {
  gl.useProgram(program);
  // Fehler: beide Sampler zeigen auf Textur-Einheit 0
  gl.uniform1i(gl.getUniformLocation(program, 'uTex'), 0);
  gl.uniform1i(gl.getUniformLocation(program, 'uEnv'), 0);

  gl.validateProgram(program);
  console.log(gl.getProgramParameter(program, gl.VALIDATE_STATUS));
  console.log(gl.getProgramInfoLog(program));
};

false (browserabhängige Meldung zum Sampler-Konflikt)

// Wichtig · Fallstricke

Kein Rückgabewert: Ein häufiger Fehler ist if (gl.validateProgram(p)). Das ist immer falsch (falsy), weil die Methode undefined zurückgibt. Fragen Sie stattdessen VALIDATE_STATUS ab.
Abhängig vom Zeitpunkt: Die Prüfung bezieht sich auf den aktuellen Zustand des Kontexts. Ein Programm kann direkt nach dem Linken gültig sein und nach anderen Uniform- oder Texturbelegungen ungültig werden.
Leistung: Die Methode kann die GPU-Pipeline zum Warten zwingen (Synchronisation). Das gilt auch für getProgramParameter. Nutzen Sie beide nur beim Debuggen und nicht in jedem Frame.
Info-Log: Die Meldungen von getProgramInfoLog() hängen von Browser und Treiber ab und können leer sein.
Ein bereits gelöschtes Programm (deleteProgram()) erzeugt den Fehler INVALID_VALUE. Ein Programm aus einem anderen Kontext erzeugt INVALID_OPERATION.
Kompatibilität: Die Methode gibt es in allen Browsern mit WebGL 1 und genauso in WebGL2RenderingContext.

Siehe auch

WebGLRenderingContext.linkProgram() WebGLRenderingContext.getProgramParameter() WebGLRenderingContext.getProgramInfoLog() WebGLRenderingContext.useProgram() WebGLRenderingContext.createProgram() WebGLProgram