glCopyTexImage2D(3)

NAME

       glCopyTexImage2D - copy pixels into a 2D texture image

C SPECIFICATION

       void glCopyTexImage2D( GLenum target,
                              GLint level,
                              GLenum internalformat,
                              GLint x,
                              GLint y,
                              GLsizei width,
                              GLsizei height,
                              GLint border )

       delim $$

PARAMETERS

       target          Specifies the target texture.  Must be GL_TEXTURE_2D.

       level           Specifies  the  level-of-detail number.  Level 0 is the
                       base image level.  Level n is the nth mipmap  reduction
                       image.

       internalformat  Specifies the internal  of the texture.  Must be one of
                       the following symbolic constants: GL_ALPHA,  GL_ALPHA4,
                       GL_ALPHA8,    GL_ALPHA12,   GL_ALPHA16,   GL_LUMINANCE,
                       GL_LUMINANCE4,      GL_LUMINANCE8,      GL_LUMINANCE12,
                       GL_LUMINANCE16,                     GL_LUMINANCE_ALPHA,
                       GL_LUMINANCE4_ALPHA4,             GL_LUMINANCE6_ALPHA2,
                       GL_LUMINANCE8_ALPHA8,            GL_LUMINANCE12_ALPHA4,
                       GL_LUMINANCE12_ALPHA12,         GL_LUMINANCE16_ALPHA16,
                       GL_INTENSITY,       GL_INTENSITY4,       GL_INTENSITY8,
                       GL_INTENSITY12,  GL_INTENSITY16,  GL_RGB,  GL_R3_G3_B2,
                       GL_RGB4,    GL_RGB5,   GL_RGB8,   GL_RGB10,   GL_RGB12,
                       GL_RGB16,  GL_RGBA,  GL_RGBA2,  GL_RGBA4,   GL_RGB5_A1,
                       GL_RGBA8, GL_RGB10_A2, GL_RGBA12, or GL_RGBA16.

       x, y            Specify the window coordinates of the lower left corner
                       of the rectangular region of pixels to be copied.

       width           Specifies the width of the texture image.  Must be 0 or
                       $2 sup n ~+~ 2*$border for some integer $n$.

       height          Specifies  the  height of the texture image.  Must be 0
                       or $2 sup m ~+~ 2*$border for some integer $m$.

       border          Specifies the width of the border.  Must be either 0 or
                       1.

DESCRIPTION

       glCopyTexImage2D  defines  a  two-dimensional texture image with pixels
       from the current GL_READ_BUFFER.

       The screen-aligned pixel rectangle with lower left corner at (x, y) and
       with    a    width    of   width$~+~2~*~$border   and   a   height   of
       height$~+~2~*~$border defines the texture array  at  the  mipmap  level
       specified by level.  internalformat specifies the internal  of the tex-
       ture array.

       The pixels in the rectangle are processed exactly  as  if  glCopyPixels
       had  been  called,  but the process stops just before final conversion.
       At this point all pixel component  values  are  clamped  to  the  range
       $[0,1]$  and  then  converted to the texture's internal  for storage in
       the texel array.

       Pixel ordering is such that lower $x$ and $y$ screen coordinates corre-
       spond to lower $s$ and $t$ texture coordinates.

       If  any  of  the  pixels  within the specified rectangle of the current
       GL_READ_BUFFER are outside the window associated with the current  ren-
       dering  context,  then  the  values obtained for those pixels are unde-
       fined.

NOTES

       glCopyTexImage2D is available only if the GL version is 1.1 or greater.

       Texturing has no effect in color index mode.

       1, 2, 3, and 4 are not accepted values for internalformat.

       An image with height or width of 0 indicates a NULL texture.

       When  the  GL_ARB_imaging  extension  is supported, the RGBA components
       read from the framebuffer may be processed  by  the  imaging  pipeline.
       See glTexImage1D for specific details.

ERRORS

       GL_INVALID_ENUM is generated if target is not GL_TEXTURE_2D.

       GL_INVALID_VALUE is generated if level is less than 0.

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

       GL_INVALID_VALUE is generated if  width  or  height  is  less  than  0,
       greater than $2~+~$GL_MAX_TEXTURE_SIZE, or if width or height cannot be
       represented as $2 sup k ~+~ 2~*~$border for some integer $k$.

       GL_INVALID_VALUE is generated if border is not 0 or 1.

       GL_INVALID_VALUE is generated if  internalformat  is  not  one  of  the
       allowable values.

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

ASSOCIATED GETS

       glGetTexImage
       glIsEnabled with argument GL_TEXTURE_2D

SEE ALSO

       glCopyPixels(3G),     glCopyTexImage1D(3G),    glCopyTexSubImage1D(3G),
       glCopyTexSubImage2D(3G),     glPixelStore(3G),     glPixelTransfer(3G),
       glTexEnv(3G),    glTexGen(3G),    glTexImage1D(3G),   glTexImage2D(3G),
       glTexSubImage1D(3G), glTexSubImage2D(3G),
       glTexParameter(3G)

                                                          GLCOPYTEXIMAGE2D(3G)