WebGL2RenderingContext.getSamplerParameter() — Methode · JavaScript-Referenz

Signatur

WebGL2RenderingContext.prototype.getSamplerParameter(sampler, pname)

Beschreibung

Mit getSamplerParameter() liest man den Zustand eines WebGLSampler-Objekts aus. Sampler-Objekte gibt es in WebGL 2. Sie trennen die Abtast-Einstellungen, also Filterung, Wrap-Modus, Detailstufe (LOD) und Tiefenvergleich, von der eigentlichen Textur. So lässt sich dieselbe Textur mit unterschiedlichen Einstellungen abtasten.

Die Methode ist das Gegenstück zu samplerParameteri() und samplerParameterf(). Sie hilft vor allem beim Debuggen, beim Prüfen von Standardwerten und in Hilfsfunktionen, die den Sampler-Zustand protokollieren oder vergleichen.

Welchen Typ der Rückgabewert hat, hängt vom abgefragten Parameter ab. Enum-Parameter wie Filter oder Wrap-Modus liefern eine GLenum-Zahl. TEXTURE_MIN_LOD und TEXTURE_MAX_LOD liefern eine Gleitkommazahl (GLfloat).

Parameter

Name	Typ	Default	Beschreibung
$sampler Pflicht	WebGLSampler		Das Sampler-Objekt, das abgefragt wird. Es wird mit `gl.createSampler()` erzeugt.
$pname Pflicht	GLenum		Der abzufragende Parameter. Erlaubt sind: `gl.TEXTURE_MAG_FILTER`, `gl.TEXTURE_MIN_FILTER`, `gl.TEXTURE_WRAP_S`, `gl.TEXTURE_WRAP_T`, `gl.TEXTURE_WRAP_R`, `gl.TEXTURE_MIN_LOD`, `gl.TEXTURE_MAX_LOD`, `gl.TEXTURE_COMPARE_MODE` und `gl.TEXTURE_COMPARE_FUNC`.

Rückgabewert

Typ

GLenum | GLfloat | null

Beschreibung

Der Wert des Parameters: eine GLenum-Zahl bei Filter-, Wrap- und Vergleichsparametern, eine GLfloat-Zahl bei TEXTURE_MIN_LOD und TEXTURE_MAX_LOD. Bei einem Fehler ist der Wert null, zum Beispiel bei einem ungültigen pname oder einem verlorenen Kontext.

Beispiele

Sampler erzeugen und Filter abfragen

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

const sampler = gl.createSampler();
gl.samplerParameteri(sampler, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
gl.samplerParameteri(sampler, gl.TEXTURE_MAG_FILTER, gl.LINEAR);

const minFilter = gl.getSamplerParameter(sampler, gl.TEXTURE_MIN_FILTER);
console.log(minFilter === gl.LINEAR_MIPMAP_LINEAR);

true

Standardwerte prüfen (LOD als Gleitkommazahl)

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

console.log(gl.getSamplerParameter(sampler, gl.TEXTURE_MIN_LOD));
console.log(gl.getSamplerParameter(sampler, gl.TEXTURE_MAX_LOD));
console.log(gl.getSamplerParameter(sampler, gl.TEXTURE_WRAP_S) === gl.REPEAT);

-1000 1000 true

Debug-Hilfe: Sampler-Zustand lesbar protokollieren

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

// Umkehr-Tabelle: Enum-Zahl -> Name
const enumName = (value) =>
  Object.keys(WebGL2RenderingContext.prototype)
    .find((key) => /^[A-Z_0-9]+$/.test(key) && gl[key] === value) ?? value;

const dumpSampler = (sampler) => {
  const params = ['TEXTURE_MIN_FILTER', 'TEXTURE_MAG_FILTER', 'TEXTURE_WRAP_S',
    'TEXTURE_WRAP_T', 'TEXTURE_COMPARE_MODE'];
  return Object.fromEntries(
    params.map((p) => [p, enumName(gl.getSamplerParameter(sampler, gl[p]))])
  );
};

const shadowSampler = gl.createSampler();
gl.samplerParameteri(shadowSampler, gl.TEXTURE_COMPARE_MODE, gl.COMPARE_REF_TO_TEXTURE);
gl.samplerParameteri(shadowSampler, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
console.table(dumpSampler(shadowSampler));

TEXTURE_MIN_FILTER: NEAREST_MIPMAP_LINEAR, TEXTURE_MAG_FILTER: LINEAR, TEXTURE_WRAP_S: CLAMP_TO_EDGE, TEXTURE_WRAP_T: REPEAT, TEXTURE_COMPARE_MODE: COMPARE_REF_TO_TEXTURE

// Wichtig · Fallstricke

Nur WebGL 2: Die Methode steht nur auf einem WebGL2RenderingContext zur Verfügung, also mit getContext('webgl2'). In WebGL 1 gibt es keine Sampler-Objekte. Dort verwendet man stattdessen getTexParameter().
Ungültiger pname: Die Methode gibt dann null zurück und setzt gl.INVALID_ENUM. Den Fehler kann man mit gl.getError() auslesen.
Performance: get*-Abfragen können die GPU-Pipeline synchronisieren. Deshalb sollte man sie nicht in jedem Frame im Render-Loop aufrufen. Besser ist es, den Zustand in JavaScript selbst zu verwalten.
Vorrang vor der Textur: Solange ein Sampler mit bindSampler() an eine Textureinheit gebunden ist, gelten seine Parameter. Die Textur-Parameter an derselben Einheit werden dann ignoriert. getTexParameter() zeigt diese Überschreibung nicht an.
Bei einem verlorenen Kontext (webglcontextlost) liefert die Methode null.

Siehe auch

WebGL2RenderingContext.createSampler() WebGL2RenderingContext.bindSampler() WebGL2RenderingContext.deleteSampler() WebGLRenderingContext.getTexParameter() WebGLSampler WebGL2RenderingContext.samplerParameter[if]()