'\" t
.\"     Title: glTexImage2D
.\"    Author: [FIXME: author] [see http://docbook.sf.net/el/author]
.\" Generator: DocBook XSL Stylesheets v1.76.1 <http://docbook.sf.net/>
.\"      Date: 03/08/2011
.\"    Manual: OpenGL 3.3
.\"    Source: OpenGL 3.3
.\"  Language: English
.\"
.TH "GLTEXIMAGE2D" "3G" "03/08/2011" "OpenGL 3.3" "OpenGL 3\&.3"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
glTexImage2D \- specify a two\-dimensional texture image
.SH "C SPECIFICATION"
.HP \w'void\ glTexImage2D('u
.BI "void glTexImage2D(GLenum\ " "target" ", GLint\ " "level" ", GLint\ " "internalFormat" ", GLsizei\ " "width" ", GLsizei\ " "height" ", GLint\ " "border" ", GLenum\ " "format" ", GLenum\ " "type" ", const\ GLvoid\ *\ " "data" ");"
.PP
.SH "PARAMETERS"
.PP
\fItarget\fR
.RS 4
Specifies the target texture\&. Must be
\fBGL_TEXTURE_2D\fR,
\fBGL_PROXY_TEXTURE_2D\fR,
\fBGL_TEXTURE_1D_ARRAY\fR,
\fBGL_PROXY_TEXTURE_1D_ARRAY\fR,
\fBGL_TEXTURE_RECTANGLE\fR,
\fBGL_PROXY_TEXTURE_RECTANGLE\fR,
\fBGL_TEXTURE_CUBE_MAP_POSITIVE_X\fR,
\fBGL_TEXTURE_CUBE_MAP_NEGATIVE_X\fR,
\fBGL_TEXTURE_CUBE_MAP_POSITIVE_Y\fR,
\fBGL_TEXTURE_CUBE_MAP_NEGATIVE_Y\fR,
\fBGL_TEXTURE_CUBE_MAP_POSITIVE_Z\fR,
\fBGL_TEXTURE_CUBE_MAP_NEGATIVE_Z\fR, or
\fBGL_PROXY_TEXTURE_CUBE_MAP\fR\&.
.RE
.PP
\fIlevel\fR
.RS 4
Specifies the level\-of\-detail number\&. Level 0 is the base image level\&. Level
\fIn\fR
is the
\fIn\fRth mipmap reduction image\&. If
\fItarget\fR
is
\fBGL_TEXTURE_RECTANGLE\fR
or
\fBGL_PROXY_TEXTURE_RECTANGLE\fR,
\fIlevel\fR
must be 0\&.
.RE
.PP
\fIinternalFormat\fR
.RS 4
Specifies the number of color components in the texture\&. Must be one of the following symbolic constants:
\fBGL_COMPRESSED_RED\fR,
\fBGL_COMPRESSED_RG\fR,
\fBGL_COMPRESSED_RGB\fR,
\fBGL_COMPRESSED_RGBA\fR,
\fBGL_COMPRESSED_SRGB\fR,
\fBGL_COMPRESSED_SRGB_ALPHA\fR,
\fBGL_DEPTH_COMPONENT\fR,
\fBGL_DEPTH_COMPONENT16\fR,
\fBGL_DEPTH_COMPONENT24\fR,
\fBGL_DEPTH_COMPONENT32\fR,
\fBGL_R3_G3_B2\fR,
\fBGL_RED\fR,
\fBGL_RG\fR,
\fBGL_RGB\fR,
\fBGL_RGB4\fR,
\fBGL_RGB5\fR,
\fBGL_RGB8\fR,
\fBGL_RGB10\fR,
\fBGL_RGB12\fR,
\fBGL_RGB16\fR,
\fBGL_RGBA\fR,
\fBGL_RGBA2\fR,
\fBGL_RGBA4\fR,
\fBGL_RGB5_A1\fR,
\fBGL_RGBA8\fR,
\fBGL_RGB10_A2\fR,
\fBGL_RGBA12\fR,
\fBGL_RGBA16\fR,
\fBGL_SRGB\fR,
\fBGL_SRGB8\fR,
\fBGL_SRGB_ALPHA\fR, or
\fBGL_SRGB8_ALPHA8\fR\&.
.RE
.PP
\fIwidth\fR
.RS 4
Specifies the width of the texture image\&. All implementations support texture images that are at least 1024 texels wide\&.
.RE
.PP
\fIheight\fR
.RS 4
Specifies the height of the texture image, or the number of layers in a texture array, in the case of the
\fBGL_TEXTURE_1D_ARRAY\fR
and
\fBGL_PROXY_TEXTURE_1D_ARRAY\fR
targets\&. All implementations support 2D texture images that are at least 1024 texels high, and texture arrays that are at least 256 layers deep\&.
.RE
.PP
\fIborder\fR
.RS 4
This value must be 0\&.
.RE
.PP
\fIformat\fR
.RS 4
Specifies the format of the pixel data\&. The following symbolic values are accepted:
\fBGL_RED\fR,
\fBGL_RG\fR,
\fBGL_RGB\fR,
\fBGL_BGR\fR,
\fBGL_RGBA\fR, and
\fBGL_BGRA\fR\&.
.RE
.PP
\fItype\fR
.RS 4
Specifies the data type of the pixel data\&. The following symbolic values are accepted:
\fBGL_UNSIGNED_BYTE\fR,
\fBGL_BYTE\fR,
\fBGL_UNSIGNED_SHORT\fR,
\fBGL_SHORT\fR,
\fBGL_UNSIGNED_INT\fR,
\fBGL_INT\fR,
\fBGL_FLOAT\fR,
\fBGL_UNSIGNED_BYTE_3_3_2\fR,
\fBGL_UNSIGNED_BYTE_2_3_3_REV\fR,
\fBGL_UNSIGNED_SHORT_5_6_5\fR,
\fBGL_UNSIGNED_SHORT_5_6_5_REV\fR,
\fBGL_UNSIGNED_SHORT_4_4_4_4\fR,
\fBGL_UNSIGNED_SHORT_4_4_4_4_REV\fR,
\fBGL_UNSIGNED_SHORT_5_5_5_1\fR,
\fBGL_UNSIGNED_SHORT_1_5_5_5_REV\fR,
\fBGL_UNSIGNED_INT_8_8_8_8\fR,
\fBGL_UNSIGNED_INT_8_8_8_8_REV\fR,
\fBGL_UNSIGNED_INT_10_10_10_2\fR, and
\fBGL_UNSIGNED_INT_2_10_10_10_REV\fR\&.
.RE
.PP
\fIdata\fR
.RS 4
Specifies a pointer to the image data in memory\&.
.RE
.SH "DESCRIPTION"
.PP
Texturing allows elements of an image array to be read by shaders\&.
.PP
To define texture images, call
\fBglTexImage2D\fR\&. The arguments describe the parameters of the texture image, such as height, width, width of the border, level\-of\-detail number (see
\fBglTexParameter\fR()), and number of color components provided\&. The last three arguments describe how the image is represented in memory\&.
.PP
If
\fItarget\fR
is
\fBGL_PROXY_TEXTURE_2D\fR,
\fBGL_PROXY_TEXTURE_1D_ARRAY\fR,
\fBGL_PROXY_TEXTURE_CUBE_MAP\fR, or
\fBGL_PROXY_TEXTURE_RECTANGLE\fR, no data is read from
\fIdata\fR, but all of the texture image state is recalculated, checked for consistency, and checked against the implementation\*(Aqs capabilities\&. If the implementation cannot handle a texture of the requested texture size, it sets all of the image state to 0, but does not generate an error (see
\fBglGetError\fR())\&. To query for an entire mipmap array, use an image array level greater than or equal to 1\&.
.PP
If
\fItarget\fR
is
\fBGL_TEXTURE_2D\fR,
\fBGL_TEXTURE_RECTANGLE\fR
or one of the
\fBGL_TEXTURE_CUBE_MAP\fR
targets, data is read from
\fIdata\fR
as a sequence of signed or unsigned bytes, shorts, or longs, or single\-precision floating\-point values, depending on
\fItype\fR\&. These values are grouped into sets of one, two, three, or four values, depending on
\fIformat\fR, to form elements\&. Each data byte is treated as eight 1\-bit elements, with bit ordering determined by
\fBGL_UNPACK_LSB_FIRST\fR
(see
\fBglPixelStore\fR())\&.
.PP
If
\fItarget\fR
is
\fBGL_TEXTURE_1D_ARRAY\fR, data is interpreted as an array of one\-dimensional images\&.
.PP
If a non\-zero named buffer object is bound to the
\fBGL_PIXEL_UNPACK_BUFFER\fR
target (see
\fBglBindBuffer\fR()) while a texture image is specified,
\fIdata\fR
is treated as a byte offset into the buffer object\*(Aqs data store\&.
.PP
The first element corresponds to the lower left corner of the texture image\&. Subsequent elements progress left\-to\-right through the remaining texels in the lowest row of 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\&.
.PP

\fIformat\fR
determines the composition of each element in
\fIdata\fR\&. It can assume one of these symbolic values:
.PP
\fBGL_RED\fR
.RS 4
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
\fBGL_c_SCALE\fR, added to the signed bias
\fBGL_c_BIAS\fR, and clamped to the range [0,1]\&.
.RE
.PP
\fBGL_RG\fR
.RS 4
Each element is a red/green double\&. The GL converts it to floating point and assembles it into an RGBA element by attaching 0 for blue, and 1 for alpha\&. Each component is then multiplied by the signed scale factor
\fBGL_c_SCALE\fR, added to the signed bias
\fBGL_c_BIAS\fR, and clamped to the range [0,1]\&.
.RE
.PP
\fBGL_RGB\fR
.RS 4
.RE
.PP
\fBGL_BGR\fR
.RS 4
Each element is an RGB triple\&. The GL converts it to floating point and assembles it into an RGBA element by attaching 1 for alpha\&. Each component is then multiplied by the signed scale factor
\fBGL_c_SCALE\fR, added to the signed bias
\fBGL_c_BIAS\fR, and clamped to the range [0,1]\&.
.RE
.PP
\fBGL_RGBA\fR
.RS 4
.RE
.PP
\fBGL_BGRA\fR
.RS 4
Each element contains all four components\&. Each component is multiplied by the signed scale factor
\fBGL_c_SCALE\fR, added to the signed bias
\fBGL_c_BIAS\fR, and clamped to the range [0,1]\&.
.RE
.PP
\fBGL_DEPTH_COMPONENT\fR
.RS 4
Each element is a single depth value\&. The GL converts it to floating point, multiplies by the signed scale factor
\fBGL_DEPTH_SCALE\fR, adds the signed bias
\fBGL_DEPTH_BIAS\fR, and clamps to the range [0,1]\&.
.RE
.PP
\fBGL_DEPTH_STENCIL\fR
.RS 4
Each element is a pair of depth and stencil values\&. The depth component of the pair is interpreted as in
\fBGL_DEPTH_COMPONENT\fR\&. The stencil component is interpreted based on specified the depth + stencil internal format\&.
.RE
.PP
If an application wants to store the texture at a certain resolution or in a certain format, it can request the resolution and format with
\fIinternalFormat\fR\&. The GL will choose an internal representation that closely approximates that requested by
\fIinternalFormat\fR, but it may not match exactly\&. (The representations specified by
\fBGL_RED\fR,
\fBGL_RG\fR,
\fBGL_RGB\fR, and
\fBGL_RGBA\fR
must match exactly\&.)
.PP
If the
\fIinternalFormat\fR
parameter is one of the generic compressed formats,
\fBGL_COMPRESSED_RED\fR,
\fBGL_COMPRESSED_RG\fR,
\fBGL_COMPRESSED_RGB\fR, or
\fBGL_COMPRESSED_RGBA\fR, the GL will replace the internal format with the symbolic constant for a specific internal format and compress the texture before storage\&. If no corresponding internal format is available, or the GL can not compress that image for any reason, the internal format is instead replaced with a corresponding base internal format\&.
.PP
If the
\fIinternalFormat\fR
parameter is
\fBGL_SRGB\fR,
\fBGL_SRGB8\fR,
\fBGL_SRGB_ALPHA\fR, or
\fBGL_SRGB8_ALPHA8\fR, the texture is treated as if the red, green, or blue components are encoded in the sRGB color space\&. Any alpha component is left unchanged\&. The conversion from the sRGB encoded component
c s
to a linear component
c l
is:
.PP

c l = { c s 12\&.92 if c s ≤ 0\&.04045 ( c s + 0\&.055 1\&.055 ) 2\&.4 if c s > 0\&.04045
.PP
Assume
c s
is the sRGB component in the range [0,1]\&.
.PP
Use the
\fBGL_PROXY_TEXTURE_2D\fR,
\fBGL_PROXY_TEXTURE_1D_ARRAY\fR,
\fBGL_PROXY_TEXTURE_RECTANGLE\fR, or
\fBGL_PROXY_TEXTURE_CUBE_MAP\fR
target to try out a resolution and format\&. The implementation will update and recompute its best match for the requested storage resolution and format\&. To then query this state, call
\fBglGetTexLevelParameter\fR()\&. If the texture cannot be accommodated, texture state is set to 0\&.
.PP
A one\-component texture image uses only the red component of the RGBA color extracted from
\fIdata\fR\&. A two\-component image uses the R and G values\&. A three\-component image uses the R, G, and B values\&. A four\-component image uses all of the RGBA components\&.
.PP
Image\-based shadowing can be enabled by comparing texture r coordinates to depth texture values to generate a boolean result\&. See
\fBglTexParameter\fR()
for details on texture comparison\&.
.SH "NOTES"
.PP
The
\fBglPixelStore\fR()
mode affects texture images\&.
.PP

\fIdata\fR
may be a null pointer\&. In this case, texture memory is allocated to accommodate a texture of width
\fIwidth\fR
and height
\fIheight\fR\&. You can then download subtextures to initialize this texture memory\&. The image is undefined if the user tries to apply an uninitialized portion of the texture image to a primitive\&.
.PP

\fBglTexImage2D\fR
specifies the two\-dimensional texture for the current texture unit, specified with
\fBglActiveTexture\fR()\&.
.SH "ERRORS"
.PP

\fBGL_INVALID_ENUM\fR
is generated if
\fItarget\fR
is not
\fBGL_TEXTURE_2D\fR,
\fBGL_TEXTURE_1D_ARRAY\fR,
\fBGL_TEXTURE_RECTANGLE\fR,
\fBGL_PROXY_TEXTURE_2D\fR,
\fBGL_PROXY_TEXTURE_1D_ARRAY\fR,
\fBGL_PROXY_TEXTURE_RECTANGLE\fR,
\fBGL_PROXY_TEXTURE_CUBE_MAP\fR,
\fBGL_TEXTURE_CUBE_MAP_POSITIVE_X\fR,
\fBGL_TEXTURE_CUBE_MAP_NEGATIVE_X\fR,
\fBGL_TEXTURE_CUBE_MAP_POSITIVE_Y\fR,
\fBGL_TEXTURE_CUBE_MAP_NEGATIVE_Y\fR,
\fBGL_TEXTURE_CUBE_MAP_POSITIVE_Z\fR, or
\fBGL_TEXTURE_CUBE_MAP_NEGATIVE_Z\fR\&.
.PP

\fBGL_INVALID_ENUM\fR
is generated if
\fItarget\fR
is one of the six cube map 2D image targets and the width and height parameters are not equal\&.
.PP

\fBGL_INVALID_ENUM\fR
is generated if
\fItype\fR
is not a type constant\&.
.PP

\fBGL_INVALID_VALUE\fR
is generated if
\fIwidth\fR
is less than 0 or greater than
\fBGL_MAX_TEXTURE_SIZE\fR\&.
.PP

\fBGL_INVALID_VALUE\fR
is generated if
\fItarget\fR
is not
\fBGL_TEXTURE_1D_ARRAY\fR
or
\fBGL_PROXY_TEXTURE_1D_ARRAY\fR
and
\fIheight\fR
is less than 0 or greater than
\fBGL_MAX_TEXTURE_SIZE\fR\&.
.PP

\fBGL_INVALID_VALUE\fR
is generated if
\fItarget\fR
is
\fBGL_TEXTURE_1D_ARRAY\fR
or
\fBGL_PROXY_TEXTURE_1D_ARRAY\fR
and
\fIheight\fR
is less than 0 or greater than
\fBGL_MAX_ARRAY_TEXTURE_LAYERS\fR\&.
.PP

\fBGL_INVALID_VALUE\fR
is generated if
\fIlevel\fR
is less than 0\&.
.PP

\fBGL_INVALID_VALUE\fR
may be generated if
\fIlevel\fR
is greater than
log 2 ⁡ max, where
\fImax\fR
is the returned value of
\fBGL_MAX_TEXTURE_SIZE\fR\&.
.PP

\fBGL_INVALID_VALUE\fR
is generated if
\fIinternalFormat\fR
is not one of the accepted resolution and format symbolic constants\&.
.PP

\fBGL_INVALID_VALUE\fR
is generated if
\fIwidth\fR
or
\fIheight\fR
is less than 0 or greater than
\fBGL_MAX_TEXTURE_SIZE\fR\&.
.PP

\fBGL_INVALID_VALUE\fR
is generated if non\-power\-of\-two textures are not supported and the
\fIwidth\fR
or
\fIheight\fR
cannot be represented as
2 k + 2 ⁡ border
for some integer value of
\fIk\fR\&.
.PP

\fBGL_INVALID_VALUE\fR
is generated if
\fIborder\fR
is not 0\&.
.PP

\fBGL_INVALID_OPERATION\fR
is generated if
\fItype\fR
is one of
\fBGL_UNSIGNED_BYTE_3_3_2\fR,
\fBGL_UNSIGNED_BYTE_2_3_3_REV\fR,
\fBGL_UNSIGNED_SHORT_5_6_5\fR,
\fBGL_UNSIGNED_SHORT_5_6_5_REV\fR, or
\fBGL_UNSIGNED_INT_10F_11F_11F_REV\fR, and
\fIformat\fR
is not
\fBGL_RGB\fR\&.
.PP

\fBGL_INVALID_OPERATION\fR
is generated if
\fItype\fR
is one of
\fBGL_UNSIGNED_SHORT_4_4_4_4\fR,
\fBGL_UNSIGNED_SHORT_4_4_4_4_REV\fR,
\fBGL_UNSIGNED_SHORT_5_5_5_1\fR,
\fBGL_UNSIGNED_SHORT_1_5_5_5_REV\fR,
\fBGL_UNSIGNED_INT_8_8_8_8\fR,
\fBGL_UNSIGNED_INT_8_8_8_8_REV\fR,
\fBGL_UNSIGNED_INT_10_10_10_2\fR,
\fBGL_UNSIGNED_INT_2_10_10_10_REV\fR, or
\fBGL_UNSIGNED_INT_5_9_9_9_REV\fR, and
\fIformat\fR
is neither
\fBGL_RGBA\fR
nor
\fBGL_BGRA\fR\&.
.PP

\fBGL_INVALID_OPERATION\fR
is generated if
\fItarget\fR
is not
\fBGL_TEXTURE_2D\fR,
\fBGL_PROXY_TEXTURE_2D\fR,
\fBGL_TEXTURE_RECTANGLE\fR, or
\fBGL_PROXY_TEXTURE_RECTANGLE\fR, and
\fIinternalFormat\fR
is
\fBGL_DEPTH_COMPONENT\fR,
\fBGL_DEPTH_COMPONENT16\fR,
\fBGL_DEPTH_COMPONENT24\fR, or
\fBGL_DEPTH_COMPONENT32F\fR\&.
.PP

\fBGL_INVALID_OPERATION\fR
is generated if
\fIformat\fR
is
\fBGL_DEPTH_COMPONENT\fR
and
\fIinternalFormat\fR
is not
\fBGL_DEPTH_COMPONENT\fR,
\fBGL_DEPTH_COMPONENT16\fR,
\fBGL_DEPTH_COMPONENT24\fR, or
\fBGL_DEPTH_COMPONENT32F\fR\&.
.PP

\fBGL_INVALID_OPERATION\fR
is generated if
\fIinternalFormat\fR
is
\fBGL_DEPTH_COMPONENT\fR,
\fBGL_DEPTH_COMPONENT16\fR,
\fBGL_DEPTH_COMPONENT24\fR, or
\fBGL_DEPTH_COMPONENT32F\fR, and
\fIformat\fR
is not
\fBGL_DEPTH_COMPONENT\fR\&.
.PP

\fBGL_INVALID_OPERATION\fR
is generated if a non\-zero buffer object name is bound to the
\fBGL_PIXEL_UNPACK_BUFFER\fR
target and the buffer object\*(Aqs data store is currently mapped\&.
.PP

\fBGL_INVALID_OPERATION\fR
is generated if a non\-zero buffer object name is bound to the
\fBGL_PIXEL_UNPACK_BUFFER\fR
target and the data would be unpacked from the buffer object such that the memory reads required would exceed the data store size\&.
.PP

\fBGL_INVALID_OPERATION\fR
is generated if a non\-zero buffer object name is bound to the
\fBGL_PIXEL_UNPACK_BUFFER\fR
target and
\fIdata\fR
is not evenly divisible into the number of bytes needed to store in memory a datum indicated by
\fItype\fR\&.
.PP

\fBGL_INVALID_VALUE\fR
is generated if
\fItarget\fR
is
\fBGL_TEXTURE_RECTANGLE\fR
or
\fBGL_PROXY_TEXTURE_RECTANGLE\fR
and
\fIlevel\fR
is not 0\&.
.SH "ASSOCIATED GETS"
.PP

\fBglGetTexImage\fR()
.PP

\fBglGet\fR()
with argument
\fBGL_PIXEL_UNPACK_BUFFER_BINDING\fR
.SH "SEE ALSO"
.PP

\fBglActiveTexture\fR(),
\fBglCopyTexImage1D\fR(),
\fBglCopyTexImage2D\fR(),
\fBglCopyTexSubImage1D\fR(),
\fBglCopyTexSubImage2D\fR(),
\fBglCopyTexSubImage3D\fR(),
\fBglPixelStore\fR(),
\fBglTexImage1D\fR(),
\fBglTexImage3D\fR(),
\fBglTexSubImage1D\fR(),
\fBglTexSubImage2D\fR(),
\fBglTexSubImage3D\fR(),
\fBglTexParameter\fR()
.SH "COPYRIGHT"
.PP
Copyright
\(co
1991\-2006 Silicon Graphics, Inc\&. This document is licensed under the SGI Free Software B License\&. For details, see
\m[blue]\fBhttp://oss\&.sgi\&.com/projects/FreeB/\fR\m[]\&.