WebGL2RenderingContext.vertexAttribI4[u]i[v]() — Methode · JavaScript-Referenz

Signatur

WebGL2RenderingContext.prototype.vertexAttribI4i(index, v0, v1, v2, v3) / vertexAttribI4ui(index, v0, v1, v2, v3) / vertexAttribI4iv(index, value) / vertexAttribI4uiv(index, value)

Beschreibung

Die Methodenfamilie vertexAttribI4[u]i[v]() legt für ein generisches Vertex-Attribut einen konstanten Integer-Wert fest. Er gilt für alle Vertices eines Zeichenaufrufs, solange für diesen Attribut-Index kein Vertex-Array aktiviert ist (also nach gl.disableVertexAttribArray(index) bzw. wenn es nie aktiviert wurde).

Es gibt vier Varianten:

vertexAttribI4i(): vier vorzeichenbehaftete 32-Bit-Integer als einzelne Argumente – passend zu GLSL-Typen int, ivec2, ivec3, ivec4.
vertexAttribI4ui(): vier vorzeichenlose 32-Bit-Integer – passend zu uint bzw. uvec2–uvec4.
vertexAttribI4iv() / vertexAttribI4uiv(): dieselben Werte als Array bzw. Int32Array/Uint32Array mit mindestens vier Elementen.

Im Gegensatz zu vertexAttrib4f() werden die Werte nicht in Gleitkommazahlen umgewandelt. Sie sind daher notwendig, wenn der Shader ein Attribut als in int, in ivec4 oder in uvec4 deklariert – etwa für Material-IDs, Bone-Indizes beim Skinning oder Bitmasken. Nicht benötigte Komponenten werden vom Shader einfach ignoriert, müssen aber trotzdem übergeben werden.

Der gesetzte Wert ist Teil des globalen Kontext-Zustands (nicht des Vertex Array Objects) und lässt sich mit gl.getVertexAttrib(index, gl.CURRENT_VERTEX_ATTRIB) wieder auslesen.

Parameter

Name	Typ	Beschreibung
$index Pflicht	GLuint (number)	Position des Vertex-Attributs, z. B. aus `gl.getAttribLocation(program, name)` oder per `layout(location = n)` im Shader festgelegt. Muss kleiner als `gl.MAX_VERTEX_ATTRIBS` sein.
$v0, v1, v2, v3 Pflicht	number	Nur bei `vertexAttribI4i`/`vertexAttribI4ui`: die vier Komponenten (x, y, z, w) als Ganzzahlen. Bei `I4i` als `GLint` (−2³¹ bis 2³¹−1), bei `I4ui` als `GLuint` (0 bis 2³²−1).
$value Pflicht	Int32Array \| Uint32Array \| number[]	Nur bei den `v`-Varianten: Array mit mindestens vier Werten. `vertexAttribI4iv` erwartet ein `Int32Array` oder Array, `vertexAttribI4uiv` ein `Uint32Array` oder Array.

Rückgabewert

Typ

void

Beschreibung

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

Beispiele

Konstante Material-ID für ein ganzes Objekt setzen

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

const vsSource = `#version 300 es
layout(location = 0) in vec2 aPos;
layout(location = 1) in int aMaterialId;
flat out int vMaterialId;
void main() {
  vMaterialId = aMaterialId;
  gl_Position = vec4(aPos, 0.0, 1.0);
}`;

const fsSource = `#version 300 es
precision highp float;
flat in int vMaterialId;
out vec4 outColor;
void main() {
  outColor = vMaterialId == 3 ? vec4(1, 0, 0, 1) : vec4(0, 0, 1, 1);
}`;

const compile = (type, src) => {
  const s = gl.createShader(type);
  gl.shaderSource(s, src);
  gl.compileShader(s);
  return s;
};
const program = gl.createProgram();
gl.attachShader(program, compile(gl.VERTEX_SHADER, vsSource));
gl.attachShader(program, compile(gl.FRAGMENT_SHADER, fsSource));
gl.linkProgram(program);
gl.useProgram(program);

// Attribut 1 kommt NICHT aus einem Puffer, sondern ist konstant
gl.disableVertexAttribArray(1);
gl.vertexAttribI4i(1, 3, 0, 0, 0); // nur x wird im Shader genutzt

console.log(gl.getVertexAttrib(1, gl.CURRENT_VERTEX_ATTRIB));

Int32Array(4) [3, 0, 0, 0]

Bone-Indizes als uvec4 per Array übergeben

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

// Im Shader: layout(location = 2) in uvec4 aBoneIds;
const boneIds = new Uint32Array([0, 4, 7, 12]);

gl.disableVertexAttribArray(2);
gl.vertexAttribI4uiv(2, boneIds);

const current = gl.getVertexAttrib(2, gl.CURRENT_VERTEX_ATTRIB);
console.log(current instanceof Uint32Array, Array.from(current));

true [0, 4, 7, 12]

Vorzeichenbehaftete Werte und Fehlerprüfung

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

gl.vertexAttribI4iv(0, [-1, 2, -3, 4]);
console.log(Array.from(gl.getVertexAttrib(0, gl.CURRENT_VERTEX_ATTRIB)));

// Ungültiger Index erzeugt INVALID_VALUE
const max = gl.getParameter(gl.MAX_VERTEX_ATTRIBS);
gl.vertexAttribI4i(max, 1, 1, 1, 1);
console.log(gl.getError() === gl.INVALID_VALUE);

[-1, 2, -3, 4] true

// Wichtig · Fallstricke

Nur WebGL 2: Die Methoden existieren nicht auf WebGLRenderingContext (WebGL 1). Vorher prüfen, ob canvas.getContext('webgl2') nicht null liefert. Alle aktuellen Browser unterstützen WebGL 2, Safari seit Version 15.
Typ muss zum Shader passen: Ist das Attribut im Shader als ivec4 deklariert, muss vertexAttribI4i[v] verwendet werden, bei uvec4 vertexAttribI4ui[v]. Stimmt der Typ nicht überein (z. B. vertexAttrib4f für ein int-Attribut), erzeugt der folgende Zeichenaufruf INVALID_OPERATION.
Wirkt nur bei deaktiviertem Array: Ist enableVertexAttribArray(index) aktiv, werden die Pufferdaten verwendet und der konstante Wert ignoriert.
Für Integer-Attribute aus Puffern ist vertexAttribIPointer() statt vertexAttribPointer() nötig – sonst werden die Werte in Gleitkommazahlen umgewandelt.
Nicht ganzzahlige Zahlen werden nach WebIDL-Regeln abgeschnitten, Werte außerhalb des Wertebereichs laufen modulo 2³² über (z. B. -1 bei I4ui ergibt 4294967295).
Die v-Varianten erzeugen INVALID_VALUE, wenn das Array weniger als vier Elemente enthält; ein index ≥ MAX_VERTEX_ATTRIBS ebenfalls.
Varyings mit Integer-Typ müssen im Shader als flat deklariert werden.

Siehe auch

WebGL2RenderingContext.vertexAttribIPointer() WebGLRenderingContext.getVertexAttrib() WebGLRenderingContext.disableVertexAttribArray() WebGLRenderingContext.getAttribLocation() WebGL2RenderingContext