Signatur
Beschreibung
texImage2D() ist die zentrale Methode, um Bilddaten auf die GPU zu bringen. Sie reserviert Speicher für eine Mipmap-Stufe der Textur, die vorher mit gl.bindTexture() an das Ziel gebunden wurde, und füllt diesen Speicher mit Daten. Als Ziel dient gl.TEXTURE_2D oder eine Würfelseite wie gl.TEXTURE_CUBE_MAP_POSITIVE_X.
Es gibt zwei Aufrufvarianten:
- Rohdaten-Variante (9 Argumente): Du gibst Breite, Höhe, Rand und ein typisiertes Array (z. B.
Uint8Array) an. Übergibst dunull, wird nur Speicher reserviert. Das braucht man vor allem beim Rendern in eine Textur über ein Framebuffer-Objekt. - Quell-Variante (6 Argumente): Die Größe wird automatisch aus einem
HTMLImageElement,HTMLCanvasElement,HTMLVideoElement,ImageBitmap,ImageDataoderOffscreenCanvasübernommen.
In WebGL 1 müssen internalformat und format gleich sein (z. B. gl.RGBA). WebGL 2 (WebGL2RenderingContext) bringt Formate mit fester Bitbreite mit, etwa gl.RGBA8, gl.R32F oder gl.SRGB8_ALPHA8. Dort kann man außerdem aus einem gebundenen PIXEL_UNPACK_BUFFER hochladen und Größenangaben mit einer Bildquelle kombinieren.
Wie die Daten hochgeladen werden, steuerst du vorher mit gl.pixelStorei(): UNPACK_FLIP_Y_WEBGL spiegelt das Bild vertikal (Bildkoordinaten beginnen oben, Texturkoordinaten unten), UNPACK_PREMULTIPLY_ALPHA_WEBGL multipliziert die Farbwerte vorab mit Alpha, und UNPACK_ALIGNMENT legt die Zeilenausrichtung der Rohdaten fest (Standard: 4 Byte).
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $target Pflicht | GLenum | Texturziel: gl.TEXTURE_2D oder eine der Würfelseiten gl.TEXTURE_CUBE_MAP_POSITIVE_X … gl.TEXTURE_CUBE_MAP_NEGATIVE_Z. |
|
| $level Pflicht | GLint | Mipmap-Stufe. 0 ist das Basisbild, n die n-te verkleinerte Stufe. |
|
| $internalformat Pflicht | GLenum | Wie die Textur auf der GPU gespeichert wird. WebGL 1: gl.RGBA, gl.RGB, gl.LUMINANCE, gl.LUMINANCE_ALPHA, gl.ALPHA. WebGL 2 zusätzlich Formate mit fester Bitbreite wie gl.RGBA8, gl.R8, gl.RGBA16F, gl.R32F oder gl.SRGB8_ALPHA8. |
|
| $width | GLsizei | Nur Rohdaten-Variante: Breite des Texturbilds in Pixeln. | |
| $height | GLsizei | Nur Rohdaten-Variante: Höhe des Texturbilds in Pixeln. | |
| $border | GLint | 0 | Nur Rohdaten-Variante: Randbreite. Muss immer 0 sein, sonst gibt es INVALID_VALUE. |
| $format Pflicht | GLenum | Format der Quelldaten, z. B. gl.RGBA, gl.RGB oder (WebGL 2) gl.RED, gl.RG, gl.RGBA_INTEGER. In WebGL 1 identisch mit internalformat. |
|
| $type Pflicht | GLenum | Datentyp einer Komponente: meist gl.UNSIGNED_BYTE, außerdem gl.UNSIGNED_SHORT_5_6_5, gl.UNSIGNED_SHORT_4_4_4_4, gl.UNSIGNED_SHORT_5_5_5_1, gl.FLOAT bzw. gl.HALF_FLOAT (WebGL 2 oder mit Erweiterung). |
|
| $pixels | ArrayBufferView | null | Nur Rohdaten-Variante: Pixeldaten als typisiertes Array, das zu type passt (Uint8Array für UNSIGNED_BYTE, Float32Array für FLOAT, Uint16Array für gepackte Formate). Mit null wird nur Speicher reserviert. |
|
| $source | HTMLImageElement | HTMLCanvasElement | HTMLVideoElement | ImageBitmap | ImageData | OffscreenCanvas | VideoFrame | Nur Quell-Variante: Bildquelle, deren Größe übernommen wird. Bilder müssen vollständig geladen sein; fremde Quellen brauchen die passende CORS-Freigabe. |
Rückgabewert
undefined). Fehler meldet die Methode nicht per Exception, sondern über gl.getError() (z. B. INVALID_ENUM, INVALID_VALUE, INVALID_OPERATION). Ausnahme: Bei nicht freigegebenen Cross-Origin-Quellen wird ein SecurityError geworfen.