- 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