- 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