WebGLRenderingContext.bindTexture() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.bindTexture(target, texture)

Beschreibung

bindTexture() verknüpft ein Texturobjekt mit einem Bindungspunkt der aktuell aktiven Textureinheit. WebGL arbeitet als Zustandsautomat: Befehle wie texImage2D(), texParameteri() oder generateMipmap() bekommen kein Texturobjekt übergeben. Sie wirken immer auf die Textur, die gerade am jeweiligen Ziel gebunden ist.

Beim ersten Binden legt WebGL fest, welcher Typ eine Textur ist (2D oder Cube-Map). Danach darf man sie nur noch an dieses Ziel binden. Wer mehrere Texturen gleichzeitig im Shader nutzen will, wählt vorher mit gl.activeTexture(gl.TEXTURE0 + n) eine Textureinheit aus, bindet dann die Textur und setzt den Sampler-Uniform mit gl.uniform1i() auf n.

Übergibt man null als texture, wird die Bindung am Ziel gelöst. Das sollte man z. B. tun, bevor man eine Textur als Rendering-Ziel eines Framebuffers verwendet, damit keine Rückkopplungsschleife entsteht.

Parameter

Name	Typ	Default	Beschreibung
$target Pflicht	GLenum		Bindungspunkt. WebGL 1: `gl.TEXTURE_2D` oder `gl.TEXTURE_CUBE_MAP`. WebGL 2 zusätzlich: `gl.TEXTURE_3D` und `gl.TEXTURE_2D_ARRAY`.
$texture Pflicht	WebGLTexture \| null		Das Texturobjekt, das gebunden werden soll (aus `gl.createTexture()`). Mit `null` wird die Bindung am Ziel gelöst.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Fehler meldet WebGL nur über gl.getError().

Beispiele

Textur anlegen, binden und mit Pixeldaten füllen

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

const texture = gl.createTexture();
gl.bindTexture(gl.TEXTURE_2D, texture);

// 1×1-Pixel in Blau als Platzhalter
gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, 1, 1, 0,
  gl.RGBA, gl.UNSIGNED_BYTE, new Uint8Array([0, 0, 255, 255]));

// Filter setzen – wirken auf die gebundene Textur
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_S, gl.CLAMP_TO_EDGE);
gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, gl.CLAMP_TO_EDGE);

console.log(gl.getParameter(gl.TEXTURE_BINDING_2D) === texture);

true

Bild asynchron laden und als Textur hochladen

const loadTexture = (gl, url) => new Promise((resolve, reject) => {
  const img = new Image();
  img.crossOrigin = 'anonymous';
  img.onload = () => {
    const tex = gl.createTexture();
    gl.bindTexture(gl.TEXTURE_2D, tex);
    gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
    gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img);
    gl.generateMipmap(gl.TEXTURE_2D); // WebGL 1: nur bei Zweierpotenz-Größen
    gl.bindTexture(gl.TEXTURE_2D, null); // Bindung lösen
    resolve(tex);
  };
  img.onerror = reject;
  img.src = url;
});

const gl = document.querySelector('canvas').getContext('webgl');
const tex = await loadTexture(gl, 'textures/stein.png');
console.log(gl.isTexture(tex));

true

Zwei Texturen gleichzeitig im Shader nutzen

// Voraussetzung: program ist verlinkt, diffuseTex und normalTex sind geladen
gl.useProgram(program);

gl.activeTexture(gl.TEXTURE0);
gl.bindTexture(gl.TEXTURE_2D, diffuseTex);
gl.uniform1i(gl.getUniformLocation(program, 'u_diffuse'), 0);

gl.activeTexture(gl.TEXTURE1);
gl.bindTexture(gl.TEXTURE_2D, normalTex);
gl.uniform1i(gl.getUniformLocation(program, 'u_normal'), 1);

gl.drawArrays(gl.TRIANGLES, 0, 6);

// Wichtig · Fallstricke

Typ festgelegt: Wurde eine Textur einmal an TEXTURE_2D gebunden, erzeugt ein späteres Binden an TEXTURE_CUBE_MAP den Fehler gl.INVALID_OPERATION.
Ein ungültiges target führt zu gl.INVALID_ENUM. TEXTURE_3D und TEXTURE_2D_ARRAY gibt es nur mit WebGL2RenderingContext.
Aktive Einheit beachten: bindTexture() wirkt immer auf die Einheit, die zuletzt mit activeTexture() gewählt wurde. Ein häufiger Fehler ist, dass man versehentlich die Textur auf Einheit 0 überschreibt.
Eine Textur, die mit deleteTexture() gelöscht wurde, lässt sich nicht erneut binden (INVALID_OPERATION).
In WebGL 1 gilt eine Textur ohne Zweierpotenz-Größe als unvollständig (sie wird schwarz gerendert), solange keine Mipmaps verwendet werden und das Wrapping nicht auf CLAMP_TO_EDGE steht.
Bilder von fremden Domains brauchen CORS-Header und crossOrigin, sonst schlägt texImage2D() mit einem SecurityError fehl.
Wird der Kontext verloren (webglcontextlost), sind alle Texturobjekte ungültig und müssen neu erzeugt werden.

Siehe auch

WebGLRenderingContext.createTexture() WebGLRenderingContext.activeTexture() WebGLRenderingContext.texImage2D() WebGLRenderingContext.deleteTexture() WebGLTexture