pixelsArray = gl.GetTexImage(target, level, format)
gl.GetTexImage() returns the pixels of a texture image. One-dimensional textures are returned in
a one-dimensional table whereas two-dimensional textures are returned in a table that contains
subtables for all rows in the texture. The pixels are returned as values of type #GL_FLOAT
target specifies whether the desired texture image is one specified by gl.TexImage1D()
(#GL_TEXTURE_1D) or gl.TexImage2D() (#GL_TEXTURE_2D). level specifies the
level-of-detail number of the desired image. format specifies the format of the desired image array.
See gl.TexImage2D for a description of the acceptable values for the format parameter.
To understand the operation of gl.GetTexImage(), consider the selected internal four-component texture
image to be an RGBA color buffer the size of the image. The semantics of gl.GetTexImage() are then
identical to those of gl.ReadPixels(), with the exception that no pixel
transfer operations are performed, when called with the same format and type, with x and y set to 0,
width set to the width of the texture image (including border if one was specified), and height set
to 1 for 1D images, or to the height of the texture image (including border if one was specified) for
2D images. Because the internal texture image is an RGBA image, pixel formats #GL_COLOR_INDEX, #GL_STENCIL_INDEX,
and #GL_DEPTH_COMPONENT are not accepted, and pixel type #GL_BITMAP is not accepted.
If the selected texture image does not contain four components, the following mappings are applied. Single-component textures are treated as RGBA buffers with red set to the single-component value, green set to 0, blue set to 0, and alpha set to 1. Two-component textures are treated as RGBA buffers with red set to the value of component zero, alpha set to the value of component one, and green and blue set to 0. Finally, three-component textures are treated as RGBA buffers with red set to component zero, green set to component one, blue set to component two, and alpha set to 1.
If you want to have fine-tuned control over the pixel type or if you want the pixels to be written into a memory buffer instead of a table, you can use the gl.GetTexImageRaw() function instead.
Please consult an OpenGL reference manual for more information.
#GL_TEXTURE_1D or #GL_TEXTURE_2D)#GL_RED, #GL_GREEN, #GL_BLUE, #GL_ALPHA, #GL_RGB, #GL_RGBA, #GL_LUMINANCE, and #GL_LUMINANCE_ALPHA#GL_INVALID_ENUM is generated if target or format is not an accepted value.
#GL_INVALID_VALUE is generated if level is less than zero or greater than ld(max), where max is the returned value of #GL_MAX_TEXTURE_SIZE.
#GL_INVALID_OPERATION is generated if gl.GetTexImage() is called between a call to glBegin and the corresponding call to glEnd.
#GL_TEXTURE_WIDTH
gl.GetTexLevelParameter() with argument #GL_TEXTURE_HEIGHT
gl.GetTexLevelParameter() with argument #GL_TEXTURE_BORDER
gl.GetTexLevelParameter() with argument #GL_TEXTURE_COMPONENTS
gl.Get() with arguments #GL_PACK_ALIGNMENT and others