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
// 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 mitinternalformatü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,formatundtypemü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:internalformatformattypeEingabebytes pro Pixel Layout der Eingabepixel (Bits pro Kanal) RGBRGBUNSIGNED_BYTE3 (R, G, B) = (8, 8, 8) RGBRGBUNSIGNED_SHORT_5_6_52 (R, G, B) = (5, 6, 5) RGBARGBAUNSIGNED_BYTE4 (R, G, B, A) = (8, 8, 8, 8) RGBARGBAUNSIGNED_SHORT_4_4_4_42 (R, G, B, A) = (4, 4, 4, 4) RGBARGBAUNSIGNED_SHORT_5_5_5_12 (R, G, B, A) = (5, 5, 5, 1) LUMINANCE_ALPHALUMINANCE_ALPHAUNSIGNED_BYTE2 (L, A) = (8, 8) LUMINANCELUMINANCEUNSIGNED_BYTE1 (L) = (8) ALPHAALPHAUNSIGNED_BYTE1 (A) = (8) In WebGL 1 kann
typezusätzlichFLOATsein, wenn die ErweiterungOES_texture_floataktiviert ist. Wenn die ErweiterungOES_texture_half_floataktiviert ist, kanntypezusätzlichext.HALF_FLOAT_OESsein (eine von der Erweiterung bereitgestellte Konstante).Wenn die Erweiterung
EXT_sRGBaktiviert ist, kanninternalformatzusätzlichext.SRGB_EXToderext.SRGB_ALPHA_EXTsein.In WebGL 2 sind bei Angabe der Quelle als
srcDataoderoffsetzusä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.internalformatformattypeInternes Pixellayout Als Farb-Renderziel verwendbar Textur filterbar R8REDUNSIGNED_BYTE(R) = (8) Y Y R8_SNORMREDBYTE(R) = (s8) Y R16FREDHALF_FLOAT,FLOAT(R) = (f16) Y R32FREDFLOAT(R) = (f32) R8UIRED_INTEGERUNSIGNED_BYTE(R) = (ui8) Y R8IRED_INTEGERBYTE(R) = (i8) Y R16UIRED_INTEGERUNSIGNED_SHORT(R) = (ui16) Y R16IRED_INTEGERSHORT(R) = (i16) Y R32UIRED_INTEGERUNSIGNED_INT(R) = (ui32) Y R32IRED_INTEGERINT(R) = (i32) Y RG8RGUNSIGNED_BYTE(R, G) = (8, 8) Y Y RG8_SNORMRGBYTE(R, G) = (s8, s8) Y RG16FRGHALF_FLOAT,FLOAT(R, G) = (f16, f16) Y RG32FRGFLOAT(R, G) = (f32, f32) RG8UIRG_INTEGERUNSIGNED_BYTE(R, G) = (ui8, ui8) Y RG8IRG_INTEGERBYTE(R, G) = (i8, i8) Y RG16UIRG_INTEGERUNSIGNED_SHORT(R, G) = (ui16, ui16) Y RG16IRG_INTEGERSHORT(R, G) = (i16, i16) Y RG32UIRG_INTEGERUNSIGNED_INT(R, G) = (ui32, ui32) Y RG32IRG_INTEGERINT(R, G) = (i32, i32) Y RGB8RGBUNSIGNED_BYTE(R, G, B) = (8, 8, 8) Y Y SRGB8RGBUNSIGNED_BYTE(R, G, B) = (8, 8, 8) Y RGB565RGBUNSIGNED_BYTE,UNSIGNED_SHORT_5_6_5(R, G, B) = (5, 6, 5) Y Y RGB8_SNORMRGBBYTE(R, G, B) = (s8, s8, s8) Y R11F_G11F_B10FRGBUNSIGNED_INT_10F_11F_11F_REV,HALF_FLOAT,FLOAT(R, G, B) = (f11, f11, f10) Y RGB9_E5RGBUNSIGNED_INT_5_9_9_9_REV,HALF_FLOAT,FLOAT(R, G, B) = (f9, f9, f9), 5 gemeinsame Bits Y RGB16FRGBHALF_FLOAT,FLOAT(R, G, B) = (f16, f16, f16) Y RGB32FRGBFLOAT(R, G, B) = (f32, f32, f32) RGB8UIRGB_INTEGERUNSIGNED_BYTE(R, G, B) = (ui8, ui8, ui8) Y RGB8IRGB_INTEGERBYTE(R, G, B) = (i8, i8, i8) Y RGB16UIRGB_INTEGERUNSIGNED_SHORT(R, G, B) = (ui16, ui16, ui16) Y RGB16IRGB_INTEGERSHORT(R, G, B) = (i16, i16, i16) Y RGB32UIRGB_INTEGERUNSIGNED_INT(R, G, B) = (ui32, ui32, ui32) Y RGB32IRGB_INTEGERINT(R, G, B) = (i32, i32, i32) Y RGBA8RGBAUNSIGNED_BYTE(R, G, B, A) = (8, 8, 8, 8) Y Y SRGB8_ALPHA8RGBAUNSIGNED_BYTE(R, G, B, A) = (8, 8, 8, 8) Y Y RGBA8_SNORMRGBABYTE(R, G, B, A) = (s8, s8, s8, s8) Y RGB5_A1RGBAUNSIGNED_BYTE,UNSIGNED_SHORT_5_5_5_1,UNSIGNED_INT_2_10_10_10_REV(R, G, B, A) = (5, 5, 5, 1) Y Y RGBA4RGBAUNSIGNED_BYTE,UNSIGNED_SHORT_4_4_4_4(R, G, B, A) = (4, 4, 4, 4) Y Y RGB10_A2RGBAUNSIGNED_INT_2_10_10_10_REV(R, G, B, A) = (10, 10, 10, 2) Y Y RGBA16FRGBAHALF_FLOAT,FLOAT(R, G, B, A) = (f16, f16, f16, f16) Y RGBA32FRGBAFLOAT(R, G, B, A) = (f32, f32, f32, f32) RGBA8UIRGBA_INTEGERUNSIGNED_BYTE(R, G, B, A) = (ui8, ui8, ui8, ui8) Y RGBA8IRGBA_INTEGERBYTE(R, G, B, A) = (i8, i8, i8, i8) Y RGBA10_A2UIRGBA_INTEGERUNSIGNED_INT_2_10_10_10_REV(R, G, B, A) = (ui10, ui10, ui10, ui2) Y RGBA16UIRGBA_INTEGERUNSIGNED_SHORT(R, G, B, A) = (ui16, ui16, ui16, ui16) Y RGBA16IRGBA_INTEGERSHORT(R, G, B, A) = (i16, i16, i16, i16) Y RGBA32UIRGBA_INTEGERUNSIGNED_INT(R, G, B, A) = (ui32, ui32, ui32, ui32) Y RGBA32IRGBA_INTEGERINT(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_floatkönnenR16F,RG16F,RGBA16F,R32F,RG32F,RGBA32FundR11F_G11F_B10Fals Farb-Renderziel verwendet werden. In WebGL 2 ermöglichtEXT_color_buffer_half_floatdies zusätzlich fürR16F,RG16FundRGBA16Fauf Plattformen, die 16-Bit-Gleitkomma-Renderziele unterstützen, jedoch keine 32-Bit-Gleitkomma-Renderziele.In WebGL 2 sind bei Angabe der Quelle als
srcDataoderoffsetzusätzlich die folgenden Kombinationen verfügbar. In WebGL 1 können sie über die ErweiterungWEBGL_depth_textureaktiviert werden:internalformatformattypeInternes Pixellayout DEPTH_COMPONENT16DEPTH_COMPONENTUNSIGNED_SHORT,UNSIGNED_INT(D) = (16) DEPTH_COMPONENT24DEPTH_COMPONENTUNSIGNED_INT(D) = (24) DEPTH_COMPONENT32FDEPTH_COMPONENTFLOAT(D) = (f32) DEPTH24_STENCIL8DEPTH_STENCILUNSIGNED_INT_24_8(ext.UNSIGNED_INT_24_8_WEBGL)(D, S) = (24, 8) DEPTH32F_STENCIL8DEPTH_STENCILFLOAT_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
RGBA8inRGBA16UIist 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
TypedArrayoderDataViewmit den Pixeldaten des Bilds odernull, um Texturspeicher zuzuweisen, ohne Pixel hochzuladen (die zugewiesene Textur wird mit Nullen initialisiert). Falls der Wert nichtnullist, muss sein Typ zum Parametertypepassen:Typ von srcDataWert von typeInt8ArrayBYTEUint8Array,Uint8ClampedArrayUNSIGNED_BYTEInt16ArraySHORTUint16ArrayUNSIGNED_SHORT,UNSIGNED_SHORT_5_6_5,UNSIGNED_SHORT_5_5_5_1,UNSIGNED_SHORT_4_4_4_4,HALF_FLOATInt32ArrayINTUint32ArrayUNSIGNED_INT,UNSIGNED_INT_5_9_9_9_REV,UNSIGNED_INT_2_10_10_10_REV,UNSIGNED_INT_10F_11F_11F_REV,UNSIGNED_INT_24_8Float32ArrayFLOATWenn
typeden WertFLOAT_32_UNSIGNED_INT_24_8_REVhat, musssrcDataden Wertnullhaben. srcOffsetOptional-
(Nur WebGL 2) Eine Ganzzahl, die den Index in
srcDataangibt, ab dem gelesen werden soll. Der Standardwert ist0. source-
Liest aus einer DOM-Pixelquelle, bei der es sich um eines der folgenden Objekte handeln kann:
ImageBitmapImageDataHTMLImageElementHTMLCanvasElementHTMLVideoElementOffscreenCanvasVideoFrame
In WebGL 1 werden
widthundheightimmer 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 angl.PIXEL_UNPACK_BUFFERgebundenen Puffer angibt.
Rückgabewert
Keiner (undefined).
Beispiele
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
WebGLRenderingContext.createTexture()WebGLRenderingContext.bindTexture()WebGLRenderingContext.texSubImage2D()WebGLRenderingContext.compressedTexImage2D()WebGLRenderingContext.copyTexImage2D()WebGLRenderingContext.getTexParameter()WEBGL_depth_textureOES_texture_floatOES_texture_half_floatEXT_texture_norm16EXT_sRGB