1991-2006
Silicon Graphics, Inc.
glTexSubImage1D
3G

# glTexSubImage1D

specify a one-dimensional texture subimage

## C Specification

                    void glTexSubImage1D
                    GLenum target
                    GLint level
                    GLint xoffset
                    GLsizei width
                    GLenum format
                    GLenum type
                    const GLvoid * data

## Parameters

`target`

  Specifies the target texture. Must be `GL_TEXTURE_1D`.

`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.

`width`

  Specifies the width of the texture subimage.

`format`

  Specifies the format 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`.

`type`

  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`, `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`.

`data`

  Specifies a pointer to the image data in memory.

## Description

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

`glTexSubImage1D` redefines a contiguous subregion of an existing one-dimensional texture image. The texels referenced by `data` replace the portion of the existing texture array with x indices `xoffset` and xoffset + width - 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 width of 0, but such a specification has no effect.

If a non-zero named buffer object is bound to the `GL_PIXEL_UNPACK_BUFFER` target (see glBindBuffer) while a texture image is specified, `data` is treated as a byte offset into the buffer object's data store.

## Notes

`glTexSubImage1D` is available only if the GL version is 1.1 or greater.

Texturing has no effect in color index mode.

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

Formats `GL_BGR`, and `GL_BGRA` and types `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 available only if the GL version is 1.2 or greater.

For OpenGL versions 1.3 and greater, or when the `ARB_multitexture` extension is supported, `glTexSubImage1D` specifies a one-dimensional subtexture for the current texture unit, specified with glActiveTexture.

When the `ARB_imaging` extension is supported, the RGBA components specified in `data` may be processed by the imaging pipeline. See glTexImage1D for specific details.

## Errors

`GL_INVALID_ENUM` is generated if `target` is not one of the allowable values.

`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_VALUE` is generated if `level` is less than 0.

`GL_INVALID_VALUE` may be generated if `level` is greater than log 2 max, where max is the returned value of `GL_MAX_TEXTURE_SIZE`.

`GL_INVALID_VALUE` is generated if xoffset < - b , or if xoffset + width > w - b , where w is the `GL_TEXTURE_WIDTH`, and b is the width of the `GL_TEXTURE_BORDER` of the texture image being modified. Note that w includes twice the border width.

`GL_INVALID_VALUE` is generated if `width` is less than 0.

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

`GL_INVALID_OPERATION` is generated if `type` 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 `format` is not `GL_RGB`.

`GL_INVALID_OPERATION` is generated if `type` 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 `format` is neither `GL_RGBA` nor `GL_BGRA`.

`GL_INVALID_OPERATION` is generated if a non-zero buffer object name is bound to the `GL_PIXEL_UNPACK_BUFFER` target and the buffer object's data store is currently mapped.

`GL_INVALID_OPERATION` is generated if a non-zero buffer object name is bound to the `GL_PIXEL_UNPACK_BUFFER` target and the data would be unpacked from the buffer object such that the memory reads required would exceed the data store size.

`GL_INVALID_OPERATION` is generated if a non-zero buffer object name is bound to the `GL_PIXEL_UNPACK_BUFFER` target and `data` is not evenly divisible into the number of bytes needed to store in memory a datum indicated by `type`.

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

## Associated Gets

glGetTexImage

glIsEnabled with argument `GL_TEXTURE_1D`

glGet with argument `GL_PIXEL_UNPACK_BUFFER_BINDING`

## See Also

glActiveTexture, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage1D, glTexImage2D, glTexImage3D, glTexParameter, glTexSubImage2D, glTexSubImage3D

## Copyright

Copyright 1991-2006 Silicon Graphics, Inc. This document is licensed under the SGI Free Software B License. For details, see http://oss.sgi.com/projects/FreeB/.