Export (0) Print
Expand All
Expand Minimize

glTexSubImage1D function

Applies to: desktop apps only

The glTexSubImage1D function specifies a portion of an existing one-dimensional texture image. You cannot define a new texture with glTexSubImage1D.

Syntax

void WINAPI glTexSubImage1D(
  GLenum target,
  GLint level,
  GLint xoffset,
  GLsizei width,
  GLenum format,
  GLenum type,
  const GLvoid *pixels
);

Parameters

target

The target texture. Must be GL_TEXTURE_1D.

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.

width

The width of the texture sub-image.

format

The format of the pixel data. This parameter can assume one of the following symbolic values.

ValueMeaning
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 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 format. 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.

Return value

This function does not return a value.

Error codes

The following error codes can be retrieved by the glGetError function.

NameMeaning
GL_INVALID_ENUM

target was not GL_TEXTURE_1D.

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 log2 max, where max was the returned value of GL_MAX_TEXTURE_SIZE.

GL_INVALID_VALUE

xoffset was less than b, or offset + width was greater than wb, 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

width was 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 texure array was not defined by a previous glTexImage1D operation.

GL_INVALID_OPERATION

The function was called between a call to glBegin and the corresponding call to glEnd.

Remarks

One-dimensional texturing for a primitive is enabled using glEnable and glDisable with the argument GL_TEXTURE_1D. During texturing, part of a specified texture image is mapped into each enabled primitive. You use the glTexSubImage1D 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. 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 glTexSubImage1D:

glGetTexImage

glIsEnabled with argument GL_TEXTURE_1D

Requirements

Minimum supported client

Windows 2000 Professional

Minimum supported server

Windows 2000 Server

Header

Gl.h

Library

Opengl32.lib

DLL

Opengl32.dll

See also

glCopyTexImage1D
glCopyTexImage2D
glCopyTexSubImage1D
glCopyTexSubImage2D
glDrawPixels
glEnable
glFog
glGetTexImage
glIsEnabled
glPixelStore
glPixelTransfer
glTexEnv
glTexGen
glTexImage1D
glTexImage2D
glTexParameter
glTexSubImage2D

 

 

Send comments about this topic to Microsoft

Build date: 3/6/2012

Community Additions

ADD
Show:
© 2014 Microsoft