WebGLRenderingContext.pixelStorei() — Methode · JavaScript-Referenz

Signatur

WebGLRenderingContext.prototype.pixelStorei(pname, param)

Beschreibung

Mit pixelStorei() stellst du die Pixel-Speichermodi des WebGL-Kontexts ein. Sie bestimmen, wie Bilddaten zwischen JavaScript-Speicher (z. B. Uint8Array, HTMLImageElement, ImageBitmap) und der GPU übertragen werden. Das betrifft die Zeilenausrichtung, ob Bilder beim Hochladen vertikal gespiegelt werden, ob der Alphakanal vormultipliziert wird und ob eine Farbraumkonvertierung stattfindet.

Die Einstellungen sind globaler Zustand des Kontexts: Sie gelten für alle folgenden Aufrufe von texImage2D(), texSubImage2D(), compressedTexImage2D() bzw. readPixels(), bis sie erneut geändert werden. Du rufst pixelStorei() also vor dem eigentlichen Upload bzw. Auslesen auf.

Unterstützte Werte für pname in WebGL 1:

gl.PACK_ALIGNMENT – Zeilenausrichtung beim Auslesen mit readPixels() (1, 2, 4 oder 8; Standard 4).
gl.UNPACK_ALIGNMENT – Zeilenausrichtung beim Hochladen (1, 2, 4 oder 8; Standard 4).
gl.UNPACK_FLIP_Y_WEBGL – spiegelt die Quelldaten vertikal (Boolean-artig, Standard false).
gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL – multipliziert RGB mit Alpha vor (Standard false).
gl.UNPACK_COLORSPACE_CONVERSION_WEBGL – gl.BROWSER_DEFAULT_WEBGL (Standard) oder gl.NONE.

In einem WebGL2RenderingContext kommen weitere Parameter hinzu, u. a. PACK_ROW_LENGTH, PACK_SKIP_PIXELS, PACK_SKIP_ROWS, UNPACK_ROW_LENGTH, UNPACK_IMAGE_HEIGHT, UNPACK_SKIP_PIXELS, UNPACK_SKIP_ROWS und UNPACK_SKIP_IMAGES, mit denen sich Teilbereiche eines größeren Puffers hochladen lassen.

Parameter

Name	Typ	Default	Beschreibung
$pname Pflicht	GLenum		Der zu setzende Speichermodus, z. B. `gl.UNPACK_ALIGNMENT`, `gl.PACK_ALIGNMENT`, `gl.UNPACK_FLIP_Y_WEBGL`, `gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL` oder `gl.UNPACK_COLORSPACE_CONVERSION_WEBGL` (WebGL 2: zusätzliche `PACK_`/`UNPACK_`-Konstanten).
$param Pflicht	GLint \| boolean		Der neue Wert. Für Ausrichtungen 1, 2, 4 oder 8; für die `*_WEBGL`-Flags `true`/`false` (bzw. 1/0); für die Farbraumkonvertierung `gl.BROWSER_DEFAULT_WEBGL` oder `gl.NONE`.

Rückgabewert

Typ

void

Beschreibung

Kein Rückgabewert (undefined). Bei ungültigen Werten setzt WebGL einen Fehler, abrufbar über gl.getError().

Beispiele

Bildtextur richtig herum hochladen

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

const loadTexture = async (url) => {
  const img = new Image();
  img.src = url;
  await img.decode();

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

  // Bildursprung oben links -> WebGL-Ursprung unten links: vertikal spiegeln
  gl.pixelStorei(gl.UNPACK_FLIP_Y_WEBGL, true);
  gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, img);

  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);
  return texture;
};

const tex = await loadTexture('holz.png');
console.log(gl.getParameter(gl.UNPACK_FLIP_Y_WEBGL));

true

RGB-Daten mit ungerader Breite hochladen (UNPACK_ALIGNMENT)

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

// 3×2 Pixel RGB = 9 Byte pro Zeile – nicht durch 4 teilbar!
const width = 3, height = 2;
const pixels = new Uint8Array([
  255, 0, 0,   0, 255, 0,   0, 0, 255,
  255, 255, 0, 0, 255, 255, 255, 0, 255
]);

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

// Ohne diese Zeile erwartet WebGL 12 Byte pro Zeile -> INVALID_OPERATION
gl.pixelStorei(gl.UNPACK_ALIGNMENT, 1);
gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGB, width, height, 0,
  gl.RGB, gl.UNSIGNED_BYTE, pixels);

console.log(gl.getError() === gl.NO_ERROR);

true

Vormultipliziertes Alpha und Farbraum steuern, danach zurücksetzen

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

const uploadRaw = (source) => {
  // Daten 1:1 übernehmen, z. B. für Normal- oder Datentexturen
  gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, true);
  gl.pixelStorei(gl.UNPACK_COLORSPACE_CONVERSION_WEBGL, gl.NONE);

  gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, source);

  // Globalen Zustand wieder auf Standard setzen
  gl.pixelStorei(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL, false);
  gl.pixelStorei(gl.UNPACK_COLORSPACE_CONVERSION_WEBGL, gl.BROWSER_DEFAULT_WEBGL);
};

const bitmap = await createImageBitmap(await (await fetch('normal.png')).blob());
gl.bindTexture(gl.TEXTURE_2D, gl.createTexture());
uploadRaw(bitmap);
console.log(gl.getParameter(gl.UNPACK_PREMULTIPLY_ALPHA_WEBGL));

false

Siehe auch

WebGLRenderingContext.isTexture() WebGLRenderingContext.viewport() WebGLRenderingContext.bindTexture() WebGLRenderingContext.disable() WebGLRenderingContext.getError() WebGLRenderingContext.polygonOffset()