glGetTexImage	- return a texture image

glGetTexImage
	glGetTexImage(target, level, format, type) -> pixels
glGetTexImageb
	glGetTexImageb(target, level, format) -> pixels[][] | pixels[][][]
glGetTexImaged
	glGetTexImagef(target, level, format) -> pixels[][] | pixels[][][]
glGetTexImagef
	glGetTexImagef(target, level, format) -> pixels[][] | pixels[][][]
glGetTexImagei
	glGetTexImagei(target, level, format) -> pixels[][] | pixels[][][]
glGetTexImages
	glGetTexImages(target, level, format) -> pixels[][] | pixels[][][]
glGetTexImageub
	glGetTexImageub(target, level, format) -> pixels[][] | pixels[][][]
glGetTexImageui
	glGetTexImageui(target, level, format) -> pixels[][] | pixels[][][]
glGetTexImageus
	glGetTexImageus(target, level, format) -> pixels[][] | pixels[][][]

void glGetTexImage( GLenum target,
                    GLint level,
                    GLenum format,
                    GLenum type,
                    GLvoid *pixels )

target  Specifies which texture is to	be obtained.
        GL_TEXTURE_1D	and GL_TEXTURE_2D 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	GL_RED,	GL_GREEN, GL_BLUE,
        GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE, and
        GL_LUMINANCE_ALPHA.

type	  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, and GL_FLOAT.

pixels  Returns the texture image.  Should be	a pointer to
        an array of the type specified by type.

glGetTexImage	returns	a texture image	into pixels.  target
specifies whether the	desired	texture	image is one specified
by glTexImage1D (GL_TEXTURE_1D) or by	glTexImage2D
(GL_TEXTURE_2D).  level specifies the	level-of-detail	number
of the desired image.	 format	and type specify the format
and type of the desired image	array.	See the	reference
pages	glTexImage1D and glDrawPixels for a description	of the
acceptable values for	the format and type 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
glGetTexImage	are then identical to those of glReadPixels
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.

To determine the required size of pixels, 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
format and type.  Be sure to take the	pixel storage
parameters into account, especially GL_PACK_ALIGNMENT.

If an	error is generated, no change is made to the contents
of pixels.

GL_INVALID_ENUM is generated if target, format, or type is
not an accepted value.

GL_INVALID_VALUE is generated	if level is less than 0.

GL_INVALID_VALUE may be generated if level is	greater	than
log max, where max is	the returned value of
GL_MAX_TEXTURE_SIZE.

GL_INVALID_OPERATION is generated if glGetTexImage is
executed between the execution of glBegin and	the
corresponding	execution of glEnd.

glGetTexLevelParameter with argument GL_TEXTURE_WIDTH
glGetTexLevelParameter with argument GL_TEXTURE_HEIGHT
glGetTexLevelParameter with argument GL_TEXTURE_BORDER
glGetTexLevelParameter with argument GL_TEXTURE_COMPONENTS
glGet	with arguments GL_PACK_ALIGNMENT and others

glDrawPixels,	glReadPixels, glTexEnv,	glTexGen,
glTexImage1D,	glTexImage2D, glTexSubImage1D,
glTexSubImage2D, glTexParameter