Dieser Inhalt wurde automatisch aus dem Englischen übersetzt, und kann Fehler enthalten. Erfahre mehr über dieses Experiment.

View in English Always switch to English

WebGLRenderingContext: Methode texImage2D()

Eingeschränkt verfügbar

Diese Funktion ist nicht Baseline, da sie in einigen der am weitesten verbreiteten Browser nicht funktioniert.

Hinweis: Diese Funktion ist in Web Workers verfügbar.

Die Methode texImage2D() der Schnittstelle WebGLRenderingContext der WebGL-API definiert ein zweidimensionales Texturbild.

Syntax

js
// WebGL 1:
texImage2D(target, level, internalformat, width, height, border, format, type, srcData)
texImage2D(target, level, internalformat, format, type, source)

// Additionally available in WebGL 2:
texImage2D(target, level, internalformat, width, height, border, format, type, srcData, srcOffset)
texImage2D(target, level, internalformat, width, height, border, format, type, source)
texImage2D(target, level, internalformat, width, height, border, format, type, offset)

Parameter

target

Ein GLenum, der den Bindungspunkt (das Ziel) der aktiven Textur angibt. Mögliche Werte:

  • gl.TEXTURE_2D: Eine zweidimensionale Textur.
  • gl.TEXTURE_CUBE_MAP_POSITIVE_X: Positive X-Seite einer Cube-Map-Textur.
  • gl.TEXTURE_CUBE_MAP_NEGATIVE_X: Negative X-Seite einer Cube-Map-Textur.
  • gl.TEXTURE_CUBE_MAP_POSITIVE_Y: Positive Y-Seite einer Cube-Map-Textur.
  • gl.TEXTURE_CUBE_MAP_NEGATIVE_Y: Negative Y-Seite einer Cube-Map-Textur.
  • gl.TEXTURE_CUBE_MAP_POSITIVE_Z: Positive Z-Seite einer Cube-Map-Textur.
  • gl.TEXTURE_CUBE_MAP_NEGATIVE_Z: Negative Z-Seite einer Cube-Map-Textur.
level

Ein GLint, der die Detailebene angibt. Ebene 0 ist die Ebene des Basisbilds; Ebene n ist die n-te Mipmap-Reduktionsstufe.

internalformat

Ein GLenum, der angibt, wie die Textur nach dem Laden gespeichert werden soll. Die verfügbaren Werte sind unten aufgeführt.

width

Ein GLsizei, der die Breite der Textur in Texeln angibt.

height

Ein GLsizei, der die Höhe der Textur in Texeln angibt.

border

Ein GLint, der die Breite des Rands angibt. Muss 0 sein.

format

Ein GLenum, der angibt, wie jedes Ganzzahlelement der Roh-Texeldaten als Farbkomponente interpretiert werden soll. In WebGL 1 muss dieser Wert mit internalformat übereinstimmen. Die verfügbaren Werte sind unten aufgeführt.

type

Ein GLenum, der die Größe jedes Ganzzahlelements der Roh-Texeldaten angibt.

Die Werte für internalformat, format und type müssen miteinander kompatibel sein. Die folgenden Kombinationen sind sowohl in WebGL 1 als auch in WebGL 2 möglich. Diese internen Formate haben keine festgelegte Größe, da sich nicht angeben lässt, wie viele Bytes ein Pixel intern belegt:

internalformat format type Eingabebytes pro Pixel Layout der Eingabepixel (Bits pro Kanal)
RGB RGB UNSIGNED_BYTE 3 (R, G, B) = (8, 8, 8)
RGB RGB UNSIGNED_SHORT_5_6_5 2 (R, G, B) = (5, 6, 5)
RGBA RGBA UNSIGNED_BYTE 4 (R, G, B, A) = (8, 8, 8, 8)
RGBA RGBA UNSIGNED_SHORT_4_4_4_4 2 (R, G, B, A) = (4, 4, 4, 4)
RGBA RGBA UNSIGNED_SHORT_5_5_5_1 2 (R, G, B, A) = (5, 5, 5, 1)
LUMINANCE_ALPHA LUMINANCE_ALPHA UNSIGNED_BYTE 2 (L, A) = (8, 8)
LUMINANCE LUMINANCE UNSIGNED_BYTE 1 (L) = (8)
ALPHA ALPHA UNSIGNED_BYTE 1 (A) = (8)

In WebGL 1 kann type zusätzlich FLOAT sein, wenn die Erweiterung OES_texture_float aktiviert ist. Wenn die Erweiterung OES_texture_half_float aktiviert ist, kann type zusätzlich ext.HALF_FLOAT_OES sein (eine von der Erweiterung bereitgestellte Konstante).

Wenn die Erweiterung EXT_sRGB aktiviert ist, kann internalformat zusätzlich ext.SRGB_EXT oder ext.SRGB_ALPHA_EXT sein.

In WebGL 2 sind bei Angabe der Quelle als srcData oder offset zusätzlich die folgenden Kombinationen verfügbar. Die Größe dieser internen Formate ist festgelegt, da das interne Pixellayout genau definiert ist. Das Eingabelayout wird hier nicht aufgeführt, da es analog zum obigen funktioniert. Die Spalte Als Farb-Renderziel verwendbar kennzeichnet Formate, die in WebGL 2 ohne zusätzliche Erweiterungen als Farb-Renderziel verwendet werden können.

internalformat format type Internes Pixellayout Als Farb-Renderziel verwendbar Textur filterbar
R8 RED UNSIGNED_BYTE (R) = (8) Y Y
R8_SNORM RED BYTE (R) = (s8) Y
R16F RED HALF_FLOAT, FLOAT (R) = (f16) Y
R32F RED FLOAT (R) = (f32)
R8UI RED_INTEGER UNSIGNED_BYTE (R) = (ui8) Y
R8I RED_INTEGER BYTE (R) = (i8) Y
R16UI RED_INTEGER UNSIGNED_SHORT (R) = (ui16) Y
R16I RED_INTEGER SHORT (R) = (i16) Y
R32UI RED_INTEGER UNSIGNED_INT (R) = (ui32) Y
R32I RED_INTEGER INT (R) = (i32) Y
RG8 RG UNSIGNED_BYTE (R, G) = (8, 8) Y Y
RG8_SNORM RG BYTE (R, G) = (s8, s8) Y
RG16F RG HALF_FLOAT, FLOAT (R, G) = (f16, f16) Y
RG32F RG FLOAT (R, G) = (f32, f32)
RG8UI RG_INTEGER UNSIGNED_BYTE (R, G) = (ui8, ui8) Y
RG8I RG_INTEGER BYTE (R, G) = (i8, i8) Y
RG16UI RG_INTEGER UNSIGNED_SHORT (R, G) = (ui16, ui16) Y
RG16I RG_INTEGER SHORT (R, G) = (i16, i16) Y
RG32UI RG_INTEGER UNSIGNED_INT (R, G) = (ui32, ui32) Y
RG32I RG_INTEGER INT (R, G) = (i32, i32) Y
RGB8 RGB UNSIGNED_BYTE (R, G, B) = (8, 8, 8) Y Y
SRGB8 RGB UNSIGNED_BYTE (R, G, B) = (8, 8, 8) Y
RGB565 RGB UNSIGNED_BYTE, UNSIGNED_SHORT_5_6_5 (R, G, B) = (5, 6, 5) Y Y
RGB8_SNORM RGB BYTE (R, G, B) = (s8, s8, s8) Y
R11F_G11F_B10F RGB UNSIGNED_INT_10F_11F_11F_REV, HALF_FLOAT, FLOAT (R, G, B) = (f11, f11, f10) Y
RGB9_E5 RGB UNSIGNED_INT_5_9_9_9_REV, HALF_FLOAT, FLOAT (R, G, B) = (f9, f9, f9), 5 gemeinsame Bits Y
RGB16F RGB HALF_FLOAT, FLOAT (R, G, B) = (f16, f16, f16) Y
RGB32F RGB FLOAT (R, G, B) = (f32, f32, f32)
RGB8UI RGB_INTEGER UNSIGNED_BYTE (R, G, B) = (ui8, ui8, ui8) Y
RGB8I RGB_INTEGER BYTE (R, G, B) = (i8, i8, i8) Y
RGB16UI RGB_INTEGER UNSIGNED_SHORT (R, G, B) = (ui16, ui16, ui16) Y
RGB16I RGB_INTEGER SHORT (R, G, B) = (i16, i16, i16) Y
RGB32UI RGB_INTEGER UNSIGNED_INT (R, G, B) = (ui32, ui32, ui32) Y
RGB32I RGB_INTEGER INT (R, G, B) = (i32, i32, i32) Y
RGBA8 RGBA UNSIGNED_BYTE (R, G, B, A) = (8, 8, 8, 8) Y Y
SRGB8_ALPHA8 RGBA UNSIGNED_BYTE (R, G, B, A) = (8, 8, 8, 8) Y Y
RGBA8_SNORM RGBA BYTE (R, G, B, A) = (s8, s8, s8, s8) Y
RGB5_A1 RGBA UNSIGNED_BYTE, UNSIGNED_SHORT_5_5_5_1, UNSIGNED_INT_2_10_10_10_REV (R, G, B, A) = (5, 5, 5, 1) Y Y
RGBA4 RGBA UNSIGNED_BYTE, UNSIGNED_SHORT_4_4_4_4 (R, G, B, A) = (4, 4, 4, 4) Y Y
RGB10_A2 RGBA UNSIGNED_INT_2_10_10_10_REV (R, G, B, A) = (10, 10, 10, 2) Y Y
RGBA16F RGBA HALF_FLOAT, FLOAT (R, G, B, A) = (f16, f16, f16, f16) Y
RGBA32F RGBA FLOAT (R, G, B, A) = (f32, f32, f32, f32)
RGBA8UI RGBA_INTEGER UNSIGNED_BYTE (R, G, B, A) = (ui8, ui8, ui8, ui8) Y
RGBA8I RGBA_INTEGER BYTE (R, G, B, A) = (i8, i8, i8, i8) Y
RGBA10_A2UI RGBA_INTEGER UNSIGNED_INT_2_10_10_10_REV (R, G, B, A) = (ui10, ui10, ui10, ui2) Y
RGBA16UI RGBA_INTEGER UNSIGNED_SHORT (R, G, B, A) = (ui16, ui16, ui16, ui16) Y
RGBA16I RGBA_INTEGER SHORT (R, G, B, A) = (i16, i16, i16, i16) Y
RGBA32UI RGBA_INTEGER UNSIGNED_INT (R, G, B, A) = (ui32, ui32, ui32, ui32) Y
RGBA32I RGBA_INTEGER INT (R, G, B, A) = (i32, i32, i32, i32) Y

Hinweis: Einige Gleitkommaformate, die in WebGL 2 standardmäßig nicht als Farb-Renderziel verwendet werden können, lassen sich durch Aktivieren der entsprechenden Erweiterung dafür nutzbar machen. Mit der Erweiterung EXT_color_buffer_float können R16F, RG16F, RGBA16F, R32F, RG32F, RGBA32F und R11F_G11F_B10F als Farb-Renderziel verwendet werden. In WebGL 2 ermöglicht EXT_color_buffer_half_float dies zusätzlich für R16F, RG16F und RGBA16F auf Plattformen, die 16-Bit-Gleitkomma-Renderziele unterstützen, jedoch keine 32-Bit-Gleitkomma-Renderziele.

In WebGL 2 sind bei Angabe der Quelle als srcData oder offset zusätzlich die folgenden Kombinationen verfügbar. In WebGL 1 können sie über die Erweiterung WEBGL_depth_texture aktiviert werden:

internalformat format type Internes Pixellayout
DEPTH_COMPONENT16 DEPTH_COMPONENT UNSIGNED_SHORT, UNSIGNED_INT (D) = (16)
DEPTH_COMPONENT24 DEPTH_COMPONENT UNSIGNED_INT (D) = (24)
DEPTH_COMPONENT32F DEPTH_COMPONENT FLOAT (D) = (f32)
DEPTH24_STENCIL8 DEPTH_STENCIL UNSIGNED_INT_24_8 (ext.UNSIGNED_INT_24_8_WEBGL) (D, S) = (24, 8)
DEPTH32F_STENCIL8 DEPTH_STENCIL FLOAT_32_UNSIGNED_INT_24_8_REV (D, S) = (f32, 8)

Bei einer DOM-Pixelquelle wird jeder Kanal üblicherweise durch einen vorzeichenlosen Ganzzahltyp mit mindestens 8 Bit dargestellt. Die Umwandlung einer solchen Darstellung in vorzeichenbehaftete Ganzzahlen oder in vorzeichenlose Ganzzahlen mit mehr Bits ist nicht eindeutig definiert. Bei der Umwandlung von RGBA8 in RGBA16UI ist beispielsweise unklar, ob die Werte auf den gesamten Wertebereich einer vorzeichenlosen 16-Bit-Ganzzahl skaliert werden sollen. Daher ist nur die Umwandlung in vorzeichenlose Ganzzahlen mit höchstens 8 Bit, Halbpräzisions-Gleitkommazahlen oder Gleitkommazahlen zulässig.

Die Texturquelle kann auf drei Arten bereitgestellt werden: aus einem ArrayBuffer (gegebenenfalls einem gemeinsam genutzten) über srcData und srcOffset, aus einer DOM-Pixelquelle über source oder, in WebGL 2, aus gl.PIXEL_UNPACK_BUFFER über offset.

srcData

Ein TypedArray oder DataView mit den Pixeldaten des Bilds oder null, um Texturspeicher zuzuweisen, ohne Pixel hochzuladen (die zugewiesene Textur wird mit Nullen initialisiert). Falls der Wert nicht null ist, muss sein Typ zum Parameter type passen:

Typ von srcData Wert von type
Int8Array BYTE
Uint8Array, Uint8ClampedArray UNSIGNED_BYTE
Int16Array SHORT
Uint16Array UNSIGNED_SHORT, UNSIGNED_SHORT_5_6_5, UNSIGNED_SHORT_5_5_5_1, UNSIGNED_SHORT_4_4_4_4, HALF_FLOAT
Int32Array INT
Uint32Array UNSIGNED_INT, UNSIGNED_INT_5_9_9_9_REV, UNSIGNED_INT_2_10_10_10_REV, UNSIGNED_INT_10F_11F_11F_REV, UNSIGNED_INT_24_8
Float32Array FLOAT

Wenn type den Wert FLOAT_32_UNSIGNED_INT_24_8_REV hat, muss srcData den Wert null haben.

srcOffset Optional

(Nur WebGL 2) Eine Ganzzahl, die den Index in srcData angibt, ab dem gelesen werden soll. Der Standardwert ist 0.

source

Liest aus einer DOM-Pixelquelle, bei der es sich um eines der folgenden Objekte handeln kann:

In WebGL 1 werden width und height immer aus der Quelle abgeleitet. In WebGL 2 können sie auch ausdrücklich angegeben werden.

offset

(Nur WebGL 2) Ein GLintptr, der die Startadresse im an gl.PIXEL_UNPACK_BUFFER gebundenen Puffer angibt.

Rückgabewert

Keiner (undefined).

Beispiele

js
gl.texImage2D(gl.TEXTURE_2D, 0, gl.RGBA, gl.RGBA, gl.UNSIGNED_BYTE, image);

Spezifikationen

Spezifikation
WebGL Specification
# 5.14.8
WebGL 2.0 Specification
# 4.7.6

Browser-Kompatibilität

Siehe auch