- return a texture image
C SPECIFICATION
PARAMETERS
_param1 Specifies which texture is to be obtained.
GL_TEXTURE_1D, GL_TEXTURE_2D, and GL_TEXTURE_3D
are accepted.
_param2 Specifies the level-of-detail number of the
desired image. Level 0 is the base image level.
Level n is the nth mipmap reduction image.
_param3 Specifies a pixel for the returned data. The
supported formats are GL_RED, GL_GREEN, GL_BLUE,
GL_ALPHA, GL_RGB, GL_BGR, GL_RGBA, GL_BGRA,
GL_LUMINANCE, and GL_LUMINANCE_ALPHA.
_param4 Specifies a pixel type for the returned data.
The supported types are GL_UNSIGNED_BYTE,
GL_BYTE, GL_UNSIGNED_SHORT, GL_SHORT,
GL_UNSIGNED_INT, GL_INT, GL_FLOAT,
GL_UNSIGNED_BYTE_3_3_2,
GL_UNSIGNED_BYTE_2_3_3_REV,
GL_UNSIGNED_SHORT_5_6_5,
GL_UNSIGNED_SHORT_5_6_5_REV,
GL_UNSIGNED_SHORT_4_4_4_4,
GL_UNSIGNED_SHORT_4_4_4_4_REV,
GL_UNSIGNED_SHORT_5_5_5_1,
GL_UNSIGNED_SHORT_1_5_5_5_REV,
GL_UNSIGNED_INT_8_8_8_8,
GL_UNSIGNED_INT_8_8_8_8_REV,
GL_UNSIGNED_INT_10_10_10_2, and
GL_UNSIGNED_INT_2_10_10_10_REV.
_param5 Returns the texture image. Should be a pointer
to an array of the type specified by _param4.
DESCRIPTION
glGetTexImage returns a texture image into _param5.
_param1 specifies whether the desired texture image is one
specified by glTexImage1D (GL_TEXTURE_1D), glTexImage2D (-
GL_TEXTURE_2D), or glTexImage3D (GL_TEXTURE_3D). _param2
specifies the level-of-detail number of the desired image.
_param3 and _param4 specify the and type of the desired
image array. See the reference pages glTexImage1D and
glDrawPixels for a description of the acceptable values
for the _param3 and _param4 parameters, respectively.
To understand the operation of glGetTexImage, consider the
selected internal four-component texture image to be an
RGBA color buffer the size of the image. The semantics of
nent 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.
To determine the required size of _param5, use
glGetTexLevelParameter to determine the dimensions of the
internal texture image, then scale the required number of
pixels by the storage required for each pixel, based on
_param3 and _param4. Be sure to take the pixel storage
parameters into account, especially GL_PACK_ALIGNMENT.
NOTES
If an error is generated, no change is made to the con-
tents of _param5.
When the GL_ARB_multitexture extension is supported,
glGetTexImage returns the texture image for the active
texture unit.
The types GL_UNSIGNED_BYTE_3_3_2,
GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5,
GL_UNSIGNED_SHORT_5_6_5_REV, GL_UNSIGNED_SHORT_4_4_4_4,
GL_UNSIGNED_SHORT_4_4_4_4_REV, GL_UNSIGNED_SHORT_5_5_5_1,
GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8,
GL_UNSIGNED_INT_8_8_8_8_REV, GL_UNSIGNED_INT_10_10_10_2,
GL_UNSIGNED_INT_2_10_10_10_REV, and the formats GL_BGR,
and GL_BGRA are available only if the GL version is 1.2 or
greater.
ERRORS
GL_INVALID_ENUM is generated if _param1, _param3, or
_param4 is not an accepted value.
GL_INVALID_VALUE is generated if _param2 is less than 0.
GL_INVALID_VALUE may be generated if _param2 is greater
than log2max, where max is the returned value of
GL_MAX_TEXTURE_SIZE.
GL_INVALID_OPERATION is generated if glGetTexImage is exe-
cuted between the execution of glBegin and the correspond-
ing execution of glEnd.
GL_INVALID_OPERATION is returned if _param4 is one of
GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV,
GL_UNSIGNED_SHORT_5_6_5, or GL_UNSIGNED_SHORT_5_6_5_REV
glGetTexLevelParameter with argument
GL_TEXTURE_INTERNALFORMAT
glGet with arguments GL_PACK_ALIGNMENT and others
SEE ALSO
glActiveTextureARB, glDrawPixels, glReadPixels, glTexEnv,
glTexGen, glTexImage1D, glTexImage2D, glTexImage3D,
glTexSubImage1D, glTexSubImage2D, glTexSubImage3D,
glTexParameter
1