glTexSubImage2D Subroutine

OpenGL 1.2 for AIX: Reference Manual

glTexSubImage2D Subroutine

Purpose

Specifies a two-dimensional (2D) texture subimage.

Library

OpenGL C bindings library: libGL.a

C Syntax

void glTexSubImage2D(GLenum target,
                     GLint level,
                     GLint xoffset,
                     GLint yoffset,
                     GLsizei width,
                     GLsizei height,
                     GLenum format,
                     GLenum type,
                     const GLvoid *pixels)

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.
xoffset	Specifies a texel offset in the x direction within the texture array.
yoffset	Specifies a texel offset in the y direction within the texture array.
width	Specifies the width of the texture subimage.
height	Specifies the height of the texture subimage.
format	Specifies the format of the pixel data. Symbolic constants GL_COLOR_INDEX, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_BGR, GL_BGRA, GL_ABGR_EXT, GL_LUMINANCE, and GL_LUMINANCE_ALPHA are accepted.
type	Specifies the data type for Pixels. Symbolic constants 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, GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5, GL_UNSIGNED_SHORT_5_6_5_REV, 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, and GL_UNSIGNED_INT_2_10_10_10_REV are accepted.
pixels	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, and GL_FLOAT.

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.

The glTexSubImage2D subroutine redefines a contiguous subregion of an existing two-dimensional texture image. The texels referenced by pixels replace the portion of the existing texture array with x indices xoffset and xoffset + width - 1, inclusive, and y indices yoffset and yoffset + height - 1, inclusive. This region may not include any texels outside the range of the texture array as it was originally specified. It is not an error to specify a subtexture with zero width or height, but such a specification has no effect.

GL_COLOR_INDEX	Each pixel is a single value, a color index. It is converted to fixed point, with an unspecified number of bits to the right of the binary point, regardless of the memory data type. Floating-point values convert to true fixed-point values. Signed and unsigned integer data is converted with all fraction bits set to 0 (zero). Bitmap data converts to either 0.0 or 1.0. Each fixed-point index is then shifted left by GL_INDEX_SHIFT bits and added to GL_INDEX_OFFSET. If GL_INDEX_SHIFT is negative, the shift is to the right. In either case, 0 bits fill otherwise unspecified bit locations in the result. If the GL is in red, green, blue, alpha (RGBA) mode, the resulting index is converted to an RGBA pixel 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. If the GL is in color index mode and GL_MAP_COLOR is True, the index is replaced with the value that it references in the lookup table GL_PIXEL_MAP_I_TO_I. Whether the lookup replacement of the index is done or not, the integer part of the index is then ANDed with 2b -1, where b is the number of bits in a color index buffer. The resulting indices or RGBA colors are then converted to fragments by attaching the current raster position z coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that xn = xr + n mod Width and yn = yr + [n/Width], where (xr, yr) is the current raster position. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer.
GL_RED	Each pixel is a single red component. This component is converted to the internal floating-point format in the same way as the red component of an RGBA pixel is, then it is converted to an RGBA pixel with green and blue set to 0.0, and alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.
GL_GREEN	Each pixel is a single green component. This component is converted to the internal floating-point format in the same way as the green component of an RGBA pixel is, then it is converted to an RGBA pixel with red and blue set to 0.0, and alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.
GL_BLUE	Each pixel is a single blue component. This component is converted to the internal floating-point format in the same way as the blue component of an RGBA pixel is, then it is converted to an RGBA pixel with red and green set to 0.0, and alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.
GL_ALPHA	Each pixel is a single alpha component. This component is converted to the internal floating-point format in the same way as the alpha component of an RGBA pixel is, then it is converted to an RGBA pixel with red, green, and blue set to 0.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.
GL_RGB	Each pixel is a three-component group, red first, followed by green, followed by blue. Each component is converted to the internal floating-point format in the same way as the red, green, and blue components of an RGBA pixel are. The color triple is converted to an RGBA pixel with alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.
GL_RGBA	Each pixel is a four-component group, red first, followed by green, followed by blue, followed by alpha. Floating-point values are converted directly to an internal floating-point format with unspecified precision. Signed integer values are mapped linearly to the internal floating-point format such that the most positive representable integer value maps to 1.0, and the most negative representable value maps to -1.0. Unsigned integer data are mapped similarly: the largest integer value maps to 1.0, and 0 maps to 0.0. The resulting floating-point color values are then multiplied by GL_c_SCALE and added to GL_c_BIAS, where c is RED, GREEN, BLUE, and ALPHA for the respective color components. The results are clamped to the range [0,1]. If GL_MAP_COLOR is True, each color component is scaled by the size of the lookup table GL_PIXEL_MAP_c_TO_c, then replaced by the value that it references in that table. c is R, G, B, or A, respectively. The resulting RGBA colors are then converted to fragments by attaching the current raster position z coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that xn = xr + n mod Width and yn = yr + [n/Width], where (xr, yr) is the current raster position. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer.
GL_BGR	Each pixel is a three-component group, blue first, followed by green, followed by red. Each component is converted to the internal floating-point format in the same way as the blue, green, and red components of an BGRA pixel are. The color triple is converted to an BGRA pixel with alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an BGRA pixel.
GL_BGRA	Each pixel is a four-component group, blue first, followed by green, followed by red, followed by alpha. Floating-point values are converted directly to an internal floating-point format with unspecified precision. Signed integer values are mapped linearly to the internal floating-point format such that the most positive representable integer value maps to 1.0, and the most negative representable value maps to -1.0. Unsigned integer data are mapped similarly: the largest integer value maps to 1.0, and 0 maps to 0.0. The resulting floating-point color values are then multiplied by GL_c_SCALE and added to GL_c_BIAS, where c is BLUE, GREEN, RED, and ALPHA for the respective color components. The results are clamped to the range [0,1]. If GL_MAP_COLOR is True, each color component is scaled by the size of the lookup table GL_PIXEL_MAP_c_TO_c, then replaced by the value that it references in that table. c is B, G, R, or A, respectively. The resulting BGRA colors are then converted to fragments by attaching the current raster position z coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that xn = xr + n mod Width and yn = yr + [n/Width], where (xr, yr) is the current raster position. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer.
GL_ABGR_EXT	Each pixel is a four-component group: for GL_RGBA, the red component is first, followed by green, followed by blue, followed by alpha; for GL_BGRA, the blue component is first, followed by green, followed by red, followed by alpha; for GL_ABGR_EXT the order is alpha, blue, green, and then red. Floating-point values are converted directly to an internal floatingpoint format with unspecified precision. Signed integer values are mapped linearly to the internal floating-point format such that the most positive representable integer value maps to 1.0, and the most negative representable value maps to -1.0. Unsigned integer data is mapped similarly: the largest integer value maps to 1.0, and zero maps to 0.0. The resulting floating-point color values are then multiplied by GL_c_SCALE and added to GL_c_BIAS, where c is RED, GREEN, BLUE, and ALPHA for the respective color components. The results are clamped to the range [0,1]. If GL_MAP_COLOR is true, each color component is scaled by the size of lookup table GL_PIXEL_MAP_c_TO _c, then replaced by the value that it references in that table. c is R, G, B, or A, respectively. The resulting RGBA colors are then converted to fragments by attaching the current raster position z coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that xn = xr + n mod width yn = yr + \| n bwidthc where (xr,yr) is the current raster position. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer.
GL_LUMINANCE	Each pixel is a single luminance component. This component is converted to the internal floating-point format in the same way as the red component of an RGBA pixel is, then it is converted to an RGBA pixel with red, green, and blue set to the converted luminance value, and alpha set to 1.0. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.
GL_LUMINANCE_ALPHA	Each pixel is a two-component group, luminance first, followed by alpha. The two components are converted to the internal floating-point format in the same way as the red component of an RGBA pixel is, then they are converted to an RGBA pixel with red, green, and blue set to the converted luminance value, and alpha set to the converted alpha value. After this conversion, the pixel is treated just as if it had been read as an RGBA pixel.

Notes

Texturing has no effect in color index mode.

The glPixelStore and glPixelTransfer modes affect texture images in exactly the way they affect glDrawPixels.

Format of GL_ABGR_EXT is part of the _extname (EXT_abgr) extension, not part of the core GL command set.

Errors

GL_INVALID_ENUM is generated if target is not GL_TEXTURE_2D.

GL_INVALID_OPERATION is generated if the texture array has not been defined by a previous glTexImage2D operation.

GL_INVALID_VALUE is generated if level is less than zero.

GL_INVALID_VALUE may be generated if level is greater than log2(max), where max is the returned value of GL_MAX_TEXTURE_SIZE.

GL_INVALID_VALUE is generated if width < -b or if height < -b, where b is the border width of the texture array.

GL_INVALID_VALUE is generated if xoffset < -b, (xoffset + width) > (w - b), yoffset < -b, or (yoffset + height) > (h - b). Where w is the GL_TEXTURE_WIDTH, h is the GL_TEXTURE_HEIGHT, and b is the border width of the texture image being modified. Note that w and h include twice the border width.

GL_INVALID_ENUM is generated if format is not an accepted format constant.

GL_INVALID_ENUM is generated if type is not a type constant.

GL_INVALID_ENUM is generated if type is GL_BITMAP and format is not GL_COLOR_INDEX.

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

Associated Gets

glGetTexImage

glIsEnabled with argument GL_TEXTURE_2D

Related Information

The glDrawPixels subroutine, glFog subroutine, glPixelStore subroutine, glPixelTransfer subroutine, glTexEnv subroutine, glTexGen subroutine, glTexImage2D subroutine, glTexParameter subroutine.