glTexSubImage2D
[New
- Windows 95, OEM Service Release 2]
The glTexSubImage2D
function specifies a portion of an existing one-dimensional texture image. You
cannot define a new texture with glTexSubImage2D.
void glTexSubImage2D(
|
GLenum target, |
|
|
GLint level, |
|
|
GLint xoffset, |
|
|
GLint yoffset, |
|
|
GLsizei width, |
|
|
GLsizei height, |
|
|
GLenum format, |
|
|
GLenum type, |
|
|
const GLvoid *pixels |
|
|
); |
|
Parameters
target
The target
texture. Must be GL_TEXTURE_2D.
level
The
level-of-detail number. Level 0 is the base image. Level n is the nth
mipmap reduction image.
xoffset
A texel
offset in the x direction within the texture array.
yoffset
A texel
offset in the y direction within the texture array.
width
The width of
the texture sub-image.
height
The height of
the texture sub-image.
format
The format of
the pixel data. It can assume one of the following symbolic values:
GL_COLOR_INDEX
Each element
is a single value, a color index. It is converted to fixed point format (with
an unspecified number of 0 bits to the right of the binary point), shifted left
or right depending on the value and sign of GL_INDEX_SHIFT, and added to
GL_INDEX_OFFSET (see glPixelTransfer). The resulting index is converted 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. It is converted to floating point format and assembled
into an RGBA element by attaching 0.0 for green and blue, and 1.0 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. It is converted to floating point format and
assembled into an RGBA element by attaching 0.0 for red and blue, and 1.0 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. It is converted to floating point format and
assembled into an RGBA element by attaching 0.0 for red and green, and 1.0 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. It is converted to floating point format and
assembled into an RGBA element by attaching 0.0 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).
GL_RGB
Each element
is an RGB triple. It is converted to floating point format and assembled into
an RGBA element by attaching 1.0 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_RGBA
Each element
is a complete RGBA element. It is converted to floating point. 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
Each element
is a single luminance value. It is converted to floating point format, and then
assembled into an RGBA element by replicating the luminance value three times
for red, green, and blue, and attaching 1.0 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. It is converted to floating point format, and then
assembled into an RGBA element by replicating the luminance 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).
type
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, and GL_FLOAT.
pixels
A pointer to
the image data in memory.
Remarks
Two-dimensional
texturing for a primitive is enabled using glEnable and glDisable with
the argument GL_TEXTURE_2D. During texturing, part of a specified texture image
is mapped onto each enabled primitive. You use the glTexSubImage2D
function to specify a contiguous sub-image of an existing one-dimensional
texture image for texturing.
The texels
referenced by pixels replace a region of the existing texture array with
x indexes of xoffset and xoffset + (width - 1) inclusive and y indexes of yoffset
and Yoffset + (height - 1) inclusive. This region cannot include any texels outside the range
of the originally specified texture array.
Specifying a
sub-image with a width of zero has no effect and does not generate an
error.
Texturing has
no effect in color-index mode.
In general,
texture images can be represented by the same data formats as the pixels in a glDrawPixels command, except that
GL_STENCIL_INDEX and GL_DEPTH_COMPONENT cannot be used. The glPixelStore and glPixelTransfer modes affect texture
images in exactly the way they affect glDrawPixels.
The following
functions retrieve information related to glTexSubImage2D:
glGetTexImage
glIsEnabled with argument GL_TEXTURE_2D
Error Codes
The following
are the error codes generated and their conditions.
|
Error
Code |
Condition |
|
GL_INVALID_ENUM
|
target was not GL_TEXTURE_2D. |
|
GL_INVALID_ENUM
|
format was not an accepted constant. |
|
GL_INVALID_ENUM
|
type was not an accepted constant. |
|
GL_INVALID_ENUM
|
type was GL_BITMAP and format was not
GL_COLOR_INDEX. |
|
GL_INVALID_VALUE
|
level was less than zero or greater than log (2) max, where max was the returned value of
GL_MAX_TEXTURE_SIZE. |
|
GL_INVALID_VALUE
|
xoffset was less than -b; or xoffset + width
was greater than w - b; or yoffset was less than -b;
or yoffset + height was greater than h - b, where
w is the GL_TEXTURE_WIDTH, h is the GL_TEXTURE_HEIGHT, and b is
the width of the GL_TEXTURE_BORDER of the texture image being modified. Note that w
and h include twice the border width. |
|
GL_INVALID_VALUE
|
width was less than -b, where b is the
border width of the texture array. |
|
GL_INVALID_VALUE
|
border was not zero or 1. |
|
GL_INVALID_OPERATION
|
The texture
array was not defined by a previous glTexImage2D operation. |
|
GL_INVALID_OPERATION
|
glTexSubImage2D was called between a call to glBegin and the
corresponding call to glEnd. |
See Also