glTexImage2D

Definition:

include pGUI.e
include opengl.e

glTexImage2D(integer target, level, internalformat, width, height, border, fmt, datatype, atom pixels)
-- or --
glTexImage2Dc(integer target, level, internalformat, width, height, border, fmt, datatype, cdCanvas canvas)

Description:

specify a two-dimensional texture image

target: Specifies the target texture of the active texture unit. Must be GL_TEXTURE_2D.
level: The level-of-detail number. Level 0 is the base image level. Level n is the n^th mipmap reduction image.
internalformat: Specifies the internal format of the texture. Must match format, see below.
width: The width of the texture image. Must be 2n + 2(border) for some integer n.
height: The height of the texture image. Must be 2^*m* + 2(border) for some integer m.
border: Specifies the width of the border. Must be 0.
format: Specifies the format of the texel data. Must match internalformat.

pwa/p2js:

The original glTexImage2D() requires allocate() and some form of poke(), neither of which are possible in JavaScript (I suppose you could perhaps create a JavaScript Array, but then it would not be an atom), and besides JavaScript is much happier using a canvas/image. Hence glTexImage2Dc() has been written for compatibility between desktop/Phix and pwa/p2js, see glCanvasSpecialText() below.

Notes:

The following symbolic values are accepted for format:

GL_ALPHA	Each element is a single red component. It is converted to floating point and assembled into an RGBA element by attaching 0.0 for red, green, and blue. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).
GL_RGB	Each element is an RGB triple. It is converted to floating point and assembled into an RGBA element by attaching 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).
GL_RGBA	Each element is a complete RGBA element. It is converted to floating point. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).
GL_LUMINANCE	Each element is a single luminance value. It is converted to floating point, and then assembled into an RGBA element by replicating the luminance value three times for red, green, and blue, and attaching 1.0 for alpha. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).
GL_LUMINANCE_ALPHA	Each element is a luminance/alpha pair. It is converted to floating point, and then assembled into an RGBA element by replicating the luminance value three times for red, green, and blue. Each component is then multiplied by the signed scale factor GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).

datatype: Specifies the data type of the texel data. The following symbolic values are accepted: GL_UNSIGNED_BYTE, GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_4_4_4_4, and GL_UNSIGNED_SHORT_5_5_5_1.
pixels: Specifies a pointer to the image data in memory. Not supported under pwa/p2js.
canvas: For pwa/p2js a canvas must be specified, and the width, height, and border parameters are ignored, see glCanvasSpecialText() below. On desktop/Phix (see the implementation in opengl.e) it laboriously extracts the pixels.

Color components are converted to floating point based on the datatype.
When datatype is GL_UNSIGNED_BYTE, each component is divided by 2⁸-1.
When type is GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_4_4_4_4, or GL_UNSIGNED_SHORT_5_5_5_1, each component is divided by 2^N-1, where N is the number of bits in the bitfield.

Note the WebGL version is heavily overloaded, but for desktop compatibility we only support the 9-parameter variant.

internalformat must match format.
No conversion between formats is supported during texture image processing.
datatype may be used as a hint to specify how much precision is desired, but a GL implementation may choose to store the texture array at any internal resolution it chooses.

data may be a null pointer. In this case, texture memory is allocated to accommodate a texture of width width and height height.
You can then download subtextures to initialize this texture memory.
The image is undefined if the user tries to apply an uninitialized portion of the texture image to a primitive.

glTexImage2D specifies a two-dimensional or cube-map texture for the current texture unit, specified with glActiveTexture.
glTexImage2Dc specifies a canvas to the same effect.

Utilities:

atom res = glCanvasSpecialText(Ihandle cd_canvas, atom w, h, fontsize, string text) data)
This Phix-specific routine was originally written for demo\pGUI\HelloF.exw and if you have not read the detailed notes in that source I recommend you do so now. On desktop/Phix it uses cdCanvasText() but then has [via glTexImage2Dc] to manually extract all the individual pixels out into a memory array suitable for glTexImage2D() [as in the original low-level internal routine], whereas under pwa/p2js that is simply not possible (since WebGL does not allow 2d and webgl contexts on the same canvas) so instead it creates a new temporary canvas (something desktop/Phix refuses to draw on) and passes that directly to glTexImage2Dc(). All quite messy but at least it works.

Loading images and the like has all been left for another day...

Errors:

No error is returned, but on failure the following error codes can be retrieved by glGetError():
GL_INVALID_ENUM is generated if target is not GL_TEXTURE_2D, GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL_TEXTURE_CUBE_MAP_NEGATIVE_X, GL_TEXTURE_CUBE_MAP_POSITIVE_Y, GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, GL_TEXTURE_CUBE_MAP_POSITIVE_Z, or GL_TEXTURE_CUBE_MAP_NEGATIVE_Z.
GL_INVALID_ENUM is generated if format or type is not an accepted value.
GL_INVALID_VALUE is generated if target is one of the six cube map 2D image targets and the width and height parameters are not equal.
GL_INVALID_VALUE is generated if level is less than 0.
GL_INVALID_VALUE may be generated if level is greater than log2(max), where max is the returned value of GL_MAX_TEXTURE_SIZE when target is GL_TEXTURE_2D or GL_MAX_CUBE_MAP_TEXTURE_SIZE when target is not GL_TEXTURE_2D.
GL_INVALID_VALUE is generated if internalformat is not an accepted format.
GL_INVALID_VALUE is generated if width or height is less than 0 or greater than GL_MAX_TEXTURE_SIZE when target is GL_TEXTURE_2D or GL_MAX_CUBE_MAP_TEXTURE_SIZE when target is not GL_TEXTURE_2D.
GL_INVALID_VALUE is generated if border is not 0.
GL_INVALID_OPERATION is generated if format does not match internalformat.
GL_INVALID_OPERATION is generated if type is GL_UNSIGNED_SHORT_5_6_5 and format is not GL_RGB.
GL_INVALID_OPERATION is generated if type is GL_UNSIGNED_SHORT_4_4_4_4 or GL_UNSIGNED_SHORT_5_5_5_1 and format is not GL_RGBA.

Associated Gets:

glGet with argument GL_MAX_TEXTURE_SIZE or GL_MAX_CUBE_MAP_TEXTURE_SIZE

See Also:

-, xor_bits, ?, xor_bits, xor_bits, xor_bits, xor_bits, glTexParameteri
DEV See Also glActiveTexture, glCompressedTexImage2D, glCompressedTexSubImage2D, glCopyTexImage2D, glCopyTexSubImage2D, glPixelStorei, glTexSubImage2D, //glTexParameter