- specify a two-dimensional texture image



C SPECIFICATION


PARAMETERS

       _param1  Specifies    the   target   texture.    Must   be
                GL_TEXTURE_2D or GL_PROXY_TEXTURE_2D.

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

       _param3  Specifies the number of color components  in  the
                texture.   Must  be  1, 2, 3, or 4, or 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_R3_G3_B2,  GL_RGB,  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.

       _param4  Specifies the width of the texture  image.   Must
                be  2n+2(_eqnparam6)  for  some  integer  n.  All
                implementations support texture images  that  are
                at least 64 texels wide.

       _param5  Specifies  the height of the texture image.  Must
                be  2m+2(_eqnparam6)  for  some  integer  m.  All
                implementations  support  texture images that are
                at least 64 texels high.

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

       _param7  Specifies  the  of the pixel data.  The following
                symbolic  values  are  accepted:  GL_COLOR_INDEX,
                GL_RED,   GL_GREEN,  GL_BLUE,  GL_ALPHA,  GL_RGB,
                GL_BGR  GL_RGBA,   GL_BGRA,   GL_LUMINANCE,   and
                GL_LUMINANCE_ALPHA.

       _param8  Specifies  the  data type of the pixel data.  The
                following   symbolic   values    are    accepted:
                GL_UNSIGNED_BYTE,       GL_BYTE,       GL_BITMAP,
                GL_UNSIGNED_SHORT,   GL_SHORT,   GL_UNSIGNED_INT,
                GL_INT,     GL_FLOAT,     GL_UNSIGNED_BYTE_3_3_2,


DESCRIPTION

       Texturing maps a portion of a specified texture image onto
       each graphical primitive for which texturing  is  enabled.
       To  enable  and  disable  two-dimensional  texturing, call
       glEnable and glDisable with argument GL_TEXTURE_2D.

       To define texture images, call  glTexImage2D.   The  argu-
       ments  describe  the parameters of the texture image, such
       as height, width, width  of  the  border,  level-of-detail
       number  (see  glTexParameter),  and number of color compo-
       nents provided.  The last three arguments describe how the
       image  is represented in memory; they are identical to the
       pixel formats used for glDrawPixels.

       If _param1 is GL_PROXY_TEXTURE_2D, no data  is  read  from
       _param9,  but  all  of the texture image state is recalcu-
       lated, checked for consistency, and  checked  against  the
       implementation's  capabilities. If the implementation can-
       not handle a texture of the  requested  texture  size,  it
       sets all of the image state to 0, but does not generate an
       error (see glGetError). To  query  for  an  entire  mipmap
       array,  use  an image array level greater than or equal to
       1.

       If _param1 is GL_TEXTURE_2D, data is read from _param9  as
       a  sequence of signed or unsigned bytes, shorts, or longs,
       or single-precision floating-point  values,  depending  on
       _param8.   These values are grouped into sets of one, two,
       three, or four values, depending on _param7, to form  ele-
       ments.  If _param8 is GL_BITMAP, the data is considered as
       a  string  of  unsigned  bytes  (and   _param7   must   be
       GL_COLOR_INDEX).




















       the texture image, and then in successively higher rows of
       the  texture  image.  The final element corresponds to the
       upper right corner of the texture image.

       _param7 determines the  composition  of  each  element  in
       _param9.  It can assume one of eleven symbolic values:

       GL_COLOR_INDEX
                 Each  element  is a single value, a color index.
                 The GL converts  it  to  fixed  point  (with  an
                 unspecified  number of zero bits to the right of
                 the binary point), shifted left or right depend-
                 ing on the value and sign of GL_INDEX_SHIFT, and
                 added to GL_INDEX_OFFSET (see
                 glPixelTransfer).  The resulting index  is  con-
                 verted  to  a  set of color components using the
                 GL_PIXEL_MAP_I_TO_R,        GL_PIXEL_MAP_I_TO_G,
                 GL_PIXEL_MAP_I_TO_B,   and   GL_PIXEL_MAP_I_TO_A
                 tables, and clamped to the range [0,1].

       GL_RED    Each element is a single red component.  The  GL
                 converts  it  to floating point and assembles it
                 into an RGBA element by attaching  0  for  green
                 and  blue,  and  1 for alpha.  Each component is
                 then  multiplied  by  the  signed  scale  factor
                 GL_c_SCALE,  added to the signed bias GL_c_BIAS,
                 and   clamped   to   the   range   [0,1]    (see
                 glPixelTransfer).

       GL_GREEN  Each  element  is a single green component.  The
                 GL converts it to floating point  and  assembles
                 it  into  an RGBA element by attaching 0 for red
                 and blue, and 1 for alpha.   Each  component  is
                 then  multiplied  by  the  signed  scale  factor
                 GL_c_SCALE, added to the signed bias  GL_c_BIAS,
                 and    clamped   to   the   range   [0,1]   (see
                 glPixelTransfer).

       GL_BLUE   Each element is a single blue component.  The GL
                 converts  it  to floating point and assembles it
                 into an RGBA element by attaching 0 for red  and
                 green,  and 1 for alpha.  Each component is then
                 multiplied   by   the   signed   scale    factor
                 GL_c_SCALE,  added to the signed bias GL_c_BIAS,
                 and   clamped   to   the   range   [0,1]    (see
                 glPixelTransfer).

       GL_ALPHA  Each  element  is a single alpha component.  The
                 GL converts it to floating point  and  assembles
                 it  into an RGBA element by attaching 0 for red,
                 green, and blue.  Each component is then  multi-
                 plied  by  the  signed  scale factor GL_c_SCALE,

       GL_BGRA   Each element contains all four components.  Each
                 component is multiplied by the signed scale fac-
                 tor  GL_c_SCALE,  added  to  the   signed   bias
                 GL_c_BIAS,  and  clamped to the range [0,1] (see
                 glPixelTransfer).

       GL_LUMINANCE
                 Each element is a single luminance  value.   The
                 GL converts it to floating point, then assembles
                 it into an RGBA element by replicating the lumi-
                 nance value three times for red, green, and blue
                 and attaching 1 for alpha.   Each  component  is
                 then  multiplied  by  the  signed  scale  factor
                 GL_c_SCALE, added to the signed bias  GL_c_BIAS,
                 and    clamped   to   the   range   [0,1]   (see
                 glPixelTransfer).

       GL_LUMINANCE_ALPHA
                 Each element is a luminance/alpha pair.  The  GL
                 converts it to floating point, then assembles it
                 into an RGBA element by  replicating  the  lumi-
                 nance  value  three  times  for  red, green, and
                 blue.  Each component is then multiplied by  the
                 signed  scale  factor  GL_c_SCALE,  added to the
                 signed bias GL_c_BIAS, and clamped to the  range
                 [0,1] (see
                 glPixelTransfer).

       Refer to the glDrawPixels reference page for a description
       of the acceptable values for the _param8 parameter.

       If an application wants to store the texture at a  certain
       resolution or in a certain , it can request the resolution
       and  with _param3. The GL will choose an  internal  repre-
       sentation  that  closely  approximates  that  requested by
       _param3, but it may not match exactly.   (The  representa-
       tions   specified   by  GL_LUMINANCE,  GL_LUMINANCE_ALPHA,
       GL_RGB, and GL_RGBA must match exactly. The numeric values
       1,  2, 3, and 4 may also be used to specify the above rep-
       resentations.)

       Use the GL_PROXY_TEXTURE_2D target to try out a resolution
       and  update and recompute its best match for the requested
       storage resolution and . To then query  this  state,  call
       glGetTexLevelParameter.  If the texture cannot be accommo-
       dated, texture state is set to 0.

       A one-component texture image uses only the red  component
       of the RGBA color extracted from _param9.  A two-component
       image uses the R and A values.   A  three-component  image
       uses  the R, G, and B values.  A four-component image uses
       2. Two-dimensional Convolution filtering, if enabled. See
          glConvolutionFilter1D.

          If a convolution filter changes the __width of the tex-
          ture  (by  processing with a GL_CONVOLUTION_BORDER_MODE
          of GL_REDUCE, for example), the _param4 must 2n+2(_eqn-
          param5),  for  some  integer  n,  and  _param5  must be
          2m+(_eqnparam6), for some integer m,  after  filtering.

       3.      RGBA      components     may     be     multiplied
       by GL_POST_CONVOLUTION_c_SCALE,
          and  added  to  GL_POST_CONVOLUTION_c_BIAS, if enabled.
          See glPixelTransfer.

       4. Color component replacement by the color table
       specified for
          GL_POST_CONVOLUTION_COLOR_TABLE,   if   enabled.    See
          glColorTable.

       5. Transformation by the color matrix.  See glMatrixMode.

       6.     RGBA     components     may     be      multiplied
       by GL_POST_COLOR_MATRIX_c_SCALE,
          and added to GL_POST_COLOR_MATRIX_c_BIAS,  if  enabled.
          See glPixelTransfer.

       7. Color component replacement by the color table
       specified for
          GL_POST_COLOR_MATRIX_COLOR_TABLE,  if   enabled.    See
          glColorTable.

       The texture image can be represented by the same data for-
       mats as the pixels in a glDrawPixels command, except  that
       GL_STENCIL_INDEX  and  GL_DEPTH_COMPONENT  cannot be used.
       glPixelStore  and  glPixelTransfer  modes  affect  texture
       images in exactly the way they affect glDrawPixels.


       glTexImage2D and GL_PROXY_TEXTURE_2D are available only if
       the GL version is 1.1 or greater.

       Internal formats other than 1, 2, 3, or 4 may be used only
       if the GL version is 1.1 or greater.

       In  GL  version  1.1  or  greater,  _param9  may be a null
       pointer.  In this case  texture  memory  is  allocated  to
       accommodate a texture of width _param4 and height _param5.
       You can then download subtextures to initialize this  tex-
       ture  memory.  The image is undefined if the user tries to
       apply an uninitialized portion of the texture image  to  a
       primitive.


ERRORS

       GL_INVALID_ENUM   is   generated   if   _param1   is   not
       GL_TEXTURE_2D or GL_PROXY_TEXTURE_2D.

       GL_INVALID_ENUM is generated if _param7 is not an accepted
        constant.   Format  constants other than GL_STENCIL_INDEX
       and GL_DEPTH_COMPONENT are accepted.

       GL_INVALID_ENUM is generated if _param8 is not a type con-
       stant.

       GL_INVALID_ENUM  is  generated if _param8 is GL_BITMAP and
       _param7 is not GL_COLOR_INDEX.

       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_VALUE is generated if _param3 is not 1,  2,  3,
       4,  or  one  of the accepted resolution and  symbolic con-
       stants.

       GL_INVALID_VALUE is generated if  _param4  or  _param5  is
       less than 0 or greater than 2 + GL_MAX_TEXTURE_SIZE, or if
       either cannot be represented as 2k+2(_eqnparam6) for  some
       integer value of k.

       GL_INVALID_VALUE is generated if _param6 is not 0 or 1.

       GL_INVALID_OPERATION  is generated if glTexImage2D is exe-
       cuted between the execution of glBegin and the correspond-
       ing execution of glEnd.

       GL_INVALID_OPERATION  is  generated  if  _param8 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
       and _param7 is not GL_RGB.

       GL_INVALID_OPERATION is generated if  _param8  is  one  of
       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,                             or
       GL_UNSIGNED_INT_2_10_10_10_REV   and  _param7  is  neither
       GL_RGBA nor GL_BGRA.


ASSOCIATED GETS

       glGetTexImage
       glIsEnabled with argument GL_TEXTURE_2D