glGetTexImage(3G) OpenGL Reference glGetTexImage(3G)
NAME
glGetTexImage - return a texture image
C SPECIFICATION
void glGetTexImage( GLenum target,
GLint level,
GLenum format,
GLenum type,
GLvoid *pixels )
PARAMETERS
target Specifies which texture is to be obtained. GLTEXTURE1D,
GLTEXTURE2D, GLDETAILTEXTURE2DSGIS, and GLTEXTURE3DEXT
are accepted.
level 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.
format Specifies a pixel format for the returned data. The supported
formats are GLRED, GLGREEN, GLBLUE, GLALPHA, GLRGB, GLRGBA,
GLABGREXT, GLLUMINANCE, and GLLUMINANCEALPHA.
type Specifies a pixel type for the returned data. The supported
types are GLUNSIGNEDBYTE, GLBYTE, GLUNSIGNEDSHORT, GLSHORT,
GLUNSIGNEDINT, GLINT, GLFLOAT, GLUNSIGNEDBYTE332EXT,
GLUNSIGNEDSHORT4444EXT, GLUNSIGNEDSHORT5551EXT,
GLUNSIGNEDINT8888EXT, and GLUNSIGNEDINT1010102EXT.
pixels Returns the texture image. Should be a pointer to an array of
the type specified by type.
DESCRIPTION
glGetTexImage returns a texture image into pixels. target specifies
whether the desired texture image is one specified by glTexImage1D
(GLTEXTURE1D), glTexImage2D (GLTEXTURE2D or
GLDETAILTEXTURE2DSGIS), or by glTexImage3DEXT (GLTEXTURE3DEXT).
level specifies the level-of-detail number of the desired image. format
and type specify the format and type of the desired image array. Please
see the reference pages glTexImage1D and glDrawPixels for a description
of the acceptable values for the format and type parameters,
respectively.
Operation of glGetTexImage is best understood by considering the selected
internal four-component texture image to be an RGBA color buffer the size
of the image. The semantics of glGetTexImage are then identical to those
of glReadPixels called with the same format and type, with x and y set to
zero, width set to the width of the texture image (including border if
one was specified), and height set to one for 1-D images, or to the
Page 1
glGetTexImage(3G) OpenGL Reference glGetTexImage(3G)
height of the texture image (including border if one was specified) for
2-D images. (Similar considerations apply to 3D images, though there is
no direct analogy with glReadPixels.) Because the internal texture image
is an RGBA image, pixel formats GLCOLORINDEX, GLSTENCILINDEX, and
GLDEPTHCOMPONENT are not accepted, and pixel type GLBITMAP 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, and green, blue,
and alpha set to zero. 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 zero. 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 zero.
To determine the required size of pixels, use glGetTexLevelParameter to
ascertain the dimensions of the internal texture image, then scale the
required number of pixels by the storage required for each pixel, based
on format and type. Be sure to take the pixel storage parameters into
account, especially GLPACKALIGNMENT.
NOTES
If an error is generated, no change is made to the contents of pixels.
If type is set to GLUNSIGNEDBYTE332EXT,
GLUNSIGNEDSHORT4444EXT, GLUNSIGNEDSHORT5551EXT,
GLUNSIGNEDINT8888EXT, or GLUNSIGNEDINT1010102EXT and the
EXTpackedpixels extension is not supported then a GLINVALIDENUM error
is generated.
GLABGREXT is part of the EXTabgr extension and
GLDETAILTEXTURE2DSGIS is part of the SGISdetailtexture extension.
See glIntro for more information on using extensions.
ERRORS
GLINVALIDENUM is generated if target, format, or type is not an
accepted value.
GLINVALIDVALUE is generated if level is less than zero or greater than
log max, where max is the returned value of GLMAXTEXTURESIZE.
2
GLINVALIDOPERATION is generated if glGetTexImage is executed between
the execution of glBegin and the corresponding execution of glEnd.
ASSOCIATED GETS
glGetTexLevelParameter with argument GLTEXTUREWIDTH
glGetTexLevelParameter with argument GLTEXTUREHEIGHT
glGetTexLevelParameter with argument GLTEXTUREDEPTHEXT
glGetTexLevelParameter with argument GLTEXTUREBORDER
Page 2
glGetTexImage(3G) OpenGL Reference glGetTexImage(3G)
glGetTexLevelParameter with argument GLTEXTURECOMPONENTS
glGet with arguments GLPACKALIGNMENT and others
MACHINE DEPENDENCIES
RealityEngine, RealityEngine2, and VTX systems do not support color
matrix transformations on images as they are loaded to or read back from
texture memory.
RealityEngine, RealityEngine2, and VTX systems do not support convolving
texture images as they are retrieved from texture memory.
The EXTpackedpixels extension is not supported on RealityEngine,
RealityEngine2, and VTX systems.
SEE ALSO
glDrawPixels, glReadPixels, glTexImage1D, glTexImage2D, glTexImage3DEXT
Page 3