WebGL2RenderingContext.bindSampler() — Methode · JavaScript-Referenz

Signatur

WebGL2RenderingContext.prototype.bindSampler(unit, sampler)

Beschreibung

Mit bindSampler() verknüpfst du ein WebGLSampler-Objekt mit einer Textureinheit. Ein Sampler legt fest, wie aus einer Textur gelesen wird: Filterung (TEXTURE_MIN_FILTER, TEXTURE_MAG_FILTER), Wrapping (TEXTURE_WRAP_S/T/R), LOD-Grenzen und Vergleichsmodus. Solange ein Sampler an eine Einheit gebunden ist, haben seine Parameter Vorrang vor den Parametern, die per texParameteri() direkt an der Textur gesetzt wurden.

Der große Vorteil: Du trennst Texturdaten und Sampling-Zustand. Dieselbe Textur kann im selben Frame auf verschiedenen Einheiten mit unterschiedlicher Filterung (z. B. einmal NEAREST, einmal LINEAR_MIPMAP_LINEAR) gelesen werden, und ein einzelner Sampler lässt sich für viele Texturen wiederverwenden. Das reduziert Zustandswechsel und macht Renderer-Code übersichtlicher.

Wichtig: Der Parameter unit ist ein reiner Index (0, 1, 2 …) – anders als bei activeTexture() wird nicht gl.TEXTURE0 + i übergeben. Mit null als Sampler wird die Bindung aufgehoben; die Einheit nutzt dann wieder die Parameter der gebundenen Textur.

Parameter

Name	Typ	Default	Beschreibung
$unit Pflicht	GLuint (number)		Index der Textureinheit (0 bis `MAX_COMBINED_TEXTURE_IMAGE_UNITS - 1`). Nicht `gl.TEXTURE0 + i`, sondern nur `i`.
$sampler Pflicht	WebGLSampler \| null		Das zu bindende Sampler-Objekt aus `createSampler()`, oder `null`, um die Bindung an dieser Einheit zu lösen.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Fehler werden über gl.getError() gemeldet.

Beispiele

Sampler erzeugen, konfigurieren und binden

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);

// An Textureinheit 0 binden – Index, nicht gl.TEXTURE0!
gl.bindSampler(0, sampler);

console.log(gl.getParameter(gl.SAMPLER_BINDING) === sampler);

true

Eine Textur mit zwei unterschiedlichen Filtern lesen

// Voraussetzung: gl (WebGL2), program und texture existieren bereits
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);

// Dieselbe Textur auf Einheit 0 und 1
gl.activeTexture(gl.TEXTURE0);
gl.bindTexture(gl.TEXTURE_2D, texture);
gl.activeTexture(gl.TEXTURE1);
gl.bindTexture(gl.TEXTURE_2D, texture);

gl.bindSampler(0, nearest);
gl.bindSampler(1, linear);

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

Bindung lösen und Sampler aufräumen

// Einheit 0 nutzt danach wieder die texParameteri-Werte der Textur
gl.bindSampler(0, null);
gl.deleteSampler(sampler);

console.log(gl.getParameter(gl.SAMPLER_BINDING));

null

// Wichtig · Fallstricke

Häufigster Fehler: gl.bindSampler(gl.TEXTURE0, s) – gl.TEXTURE0 ist 33984 und liegt weit außerhalb des gültigen Bereichs, was INVALID_VALUE auslöst. Übergib nur den Index.
Ist unit größer oder gleich MAX_COMBINED_TEXTURE_IMAGE_UNITS, entsteht INVALID_VALUE. Wurde der Sampler bereits gelöscht, entsteht INVALID_OPERATION.
Ein gebundener Sampler überschreibt alle Sampling-Parameter der Textur – auch wenn du am Sampler nur einzelne gesetzt hast, gelten für den Rest seine Standardwerte (z. B. MIN_FILTER = NEAREST_MIPMAP_LINEAR). Fehlen die Mipmaps, bleibt die Textur dann schwarz.
SAMPLER_BINDING gibt den Sampler der aktuell aktiven Textureinheit zurück (siehe activeTexture()).
Nur im WebGL-2-Kontext verfügbar (getContext('webgl2')); in WebGL 1 gibt es keine Sampler-Objekte. Unterstützt von allen aktuellen Browsern, Safari ab Version 15.

Siehe auch

WebGL2RenderingContext.createSampler() WebGL2RenderingContext.deleteSampler() WebGL2RenderingContext.isSampler() WebGLSampler WebGLRenderingContext.activeTexture() WebGLRenderingContext.bindTexture()