WebGLSampler — Schnittstelle · JavaScript-Referenz

Signatur

interface WebGLSampler extends WebGLObject

Beschreibung

WebGLSampler gehört zur WebGL 2 API (WebGL2RenderingContext). Ein Sampler-Objekt enthält den Abtastzustand, also die Angaben dazu, wie aus einer Textur gelesen wird: Vergrößerungs- und Verkleinerungsfilter (TEXTURE_MAG_FILTER, TEXTURE_MIN_FILTER), Wrap-Modi (TEXTURE_WRAP_S/T/R), LOD-Grenzen (TEXTURE_MIN_LOD, TEXTURE_MAX_LOD) sowie den Tiefenvergleich (TEXTURE_COMPARE_MODE, TEXTURE_COMPARE_FUNC).

In WebGL 1 hängen diese Parameter immer direkt an der Textur. Mit Samplern trennt man Bilddaten und Abtastverhalten. Dieselbe Textur lässt sich so gleichzeitig mit unterschiedlichen Filtern lesen, zum Beispiel einmal pixelgenau mit NEAREST und einmal geglättet mit LINEAR. Außerdem kann man einen einzigen Sampler für viele Texturen verwenden, ohne jede Textur einzeln mit texParameteri() einzustellen.

Das Interface hat keine eigenen Eigenschaften oder Methoden. Man arbeitet damit über Methoden des Kontexts:

gl.createSampler(): legt ein neues Sampler-Objekt an
gl.samplerParameteri() / gl.samplerParameterf(): setzen Parameter
gl.getSamplerParameter(): liest Parameter aus
gl.bindSampler(unit, sampler): bindet den Sampler an eine Textureinheit
gl.isSampler(): prüft, ob ein gültiger Sampler vorliegt
gl.deleteSampler(): gibt den Sampler frei

Ist ein Sampler an eine Textureinheit gebunden, überschreibt er die Abtastparameter der Textur, die an derselben Einheit hängt. Mit gl.bindSampler(unit, null) gelten wieder die Parameter der Textur.

Parameter

Name	Typ	Beschreibung
$unit Pflicht	GLuint	Bei `gl.bindSampler(unit, sampler)`: Index der Textureinheit (z. B. `0`), nicht `gl.TEXTURE0`.
$sampler Pflicht	WebGLSampler \| null	Das zu bindende bzw. zu konfigurierende Sampler-Objekt. `null` löst die Bindung.
$pname Pflicht	GLenum	Bei `samplerParameteri/f`: der Parameter, z. B. `gl.TEXTURE_MIN_FILTER`, `gl.TEXTURE_WRAP_S`, `gl.TEXTURE_COMPARE_MODE`, `gl.TEXTURE_MAX_LOD`.
$param Pflicht	GLint \| GLfloat	Der neue Wert, z. B. `gl.LINEAR`, `gl.CLAMP_TO_EDGE` oder eine Zahl für die LOD-Grenzen.

Beispiele

Sampler anlegen und konfigurieren

const canvas = document.createElement('canvas');
const gl = canvas.getContext('webgl2');
if (!gl) throw new Error('WebGL 2 wird nicht unterstützt');

const sampler = gl.createSampler();
gl.samplerParameteri(sampler, gl.TEXTURE_MIN_FILTER, gl.LINEAR_MIPMAP_LINEAR);
gl.samplerParameteri(sampler, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
gl.samplerParameteri(sampler, gl.TEXTURE_WRAP_S, gl.REPEAT);
gl.samplerParameteri(sampler, gl.TEXTURE_WRAP_T, gl.REPEAT);
gl.samplerParameterf(sampler, gl.TEXTURE_MAX_LOD, 8.0);

console.log(sampler instanceof WebGLSampler, gl.isSampler(sampler));
console.log(gl.getSamplerParameter(sampler, gl.TEXTURE_MAG_FILTER) === gl.LINEAR);

true true true

Dieselbe Textur mit zwei Filtern abtasten

// Voraussetzung: gl (WebGL2), program mit uniform sampler2D uPixel, uSmooth
// und eine fertig geladene Textur `texture`
const nearest = gl.createSampler();
gl.samplerParameteri(nearest, gl.TEXTURE_MIN_FILTER, gl.NEAREST);
gl.samplerParameteri(nearest, gl.TEXTURE_MAG_FILTER, gl.NEAREST);

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

// Gleiche Textur an Einheit 0 und 1 binden
gl.activeTexture(gl.TEXTURE0);
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.activeTexture(gl.TEXTURE1);
gl.bindTexture(gl.TEXTURE_2D, texture);

// Sampler pro Einheit – Index, nicht gl.TEXTUREn!
gl.bindSampler(0, nearest);
gl.bindSampler(1, linear);

gl.useProgram(program);
gl.uniform1i(gl.getUniformLocation(program, 'uPixel'), 0);
gl.uniform1i(gl.getUniformLocation(program, 'uSmooth'), 1);
gl.drawArrays(gl.TRIANGLES, 0, 6);

Sampler für Schattenabgleich (Depth Compare) und Aufräumen

const shadowSampler = gl.createSampler();
gl.samplerParameteri(shadowSampler, gl.TEXTURE_COMPARE_MODE, gl.COMPARE_REF_TO_TEXTURE);
gl.samplerParameteri(shadowSampler, gl.TEXTURE_COMPARE_FUNC, gl.LEQUAL);
gl.samplerParameteri(shadowSampler, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
gl.samplerParameteri(shadowSampler, gl.TEXTURE_MAG_FILTER, gl.LINEAR);
gl.samplerParameteri(shadowSampler, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
gl.samplerParameteri(shadowSampler, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);

gl.bindSampler(2, shadowSampler); // im Shader: uniform sampler2DShadow
// ... rendern ...

// Bindung lösen und freigeben
gl.bindSampler(2, null);
gl.deleteSampler(shadowSampler);
console.log(gl.isSampler(shadowSampler));

false

Siehe auch

WebGLShader GPUSampler WebGLBuffer WebGLQuery WebGLSync