Each element is a single value, a color index. The GL converts it to fixed point (with an unspecified number of zero 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. 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 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. The GL converts it to floating point and assembles it into an RGBA element by attaching 0 for red and blue, and 1 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. The GL converts it to floating point and assembles it into an RGBA element by attaching 0 for red and green, and 1 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. The GL converts it to floating point and assembles it into an RGBA element by attaching 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_INTENSITY
Each element is a single intensity value. The GL converts it to floating point, then assembles it into an RGBA element by replicating the intensity value three times for red, green, blue, and 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_RGB
GL_BGR
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 GL_c_SCALE, added to the signed bias GL_c_BIAS, and clamped to the range [0,1] (see glPixelTransfer).
GL_RGBA
GL_BGRA
Each element contains all four components. Each component is 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. The GL converts it to floating point, then assembles it into an RGBA element by replicating the luminance value three times for red, green, and blue and attaching 1 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. The GL converts it to floating point, then assembles it 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).
Refer to the glDrawPixels reference page for a description of the acceptable values for the type parameter.
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 internalFormat. The GL will choose an internal representation that closely approximates that requested by internalFormat, but it may not match exactly. (The representations specified by GL_LUMINANCE, GL_LUMINANCE_ALPHA, GL_RGB, and GL_RGBA must match exactly. The numeric values 1, 2, 3, and 4 may also be used to specify the above representations.)
If the internalFormat parameter is one of the generic compressed formats, GL_COMPRESSED_ALPHA, GL_COMPRESSED_INTENSITY, GL_COMPRESSED_LUMINANCE, GL_COMPRESSED_LUMINANCE_ALPHA, GL_COMPRESSED_RGB, or GL_COMPRESSED_RGBA, 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.
If the internalFormat parameter is GL_SRGB, GL_SRGB8, GL_SRGB_ALPHA, GL_SRGB8_ALPHA8, GL_SLUMINANCE, GL_SLUMINANCE8, GL_SLUMINANCE_ALPHA, or GL_SLUMINANCE8_ALPHA8, the texture is treated as if the red, green, blue, or luminance components are encoded in the sRGB color space. Any alpha component is left unchanged. The conversion from the sRGB encoded component cs to a linear component cl is:
Assume cs is the sRGB component in the range [0,1].
Use the GL_PROXY_TEXTURE_3D 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 glGetTexLevelParameter. If the texture cannot be accommodated, texture state is set to 0.
A one-component texture image uses only the red component of the RGBA color extracted from data. A two-component image uses the R and A values. A three-component image uses the R, G, and B values. A four-component image uses all of the RGBA components.
Notes
Texturing has no effect in color index mode.
The texture image 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. glPixelStore and glPixelTransfer modes affect texture images in exactly the way they affect glDrawPixels.
glTexImage3D is available only if the GL version is 1.2 or greater.
Internal formats other than 1, 2, 3, or 4 may be used only if the GL version is 1.1 or greater.
data may be a null pointer. In this case texture memory is allocated to accommodate a texture of width width, height height, and depth depth. You can then download subtextures to initialize this texture memory. The image is undefined if the program tries to apply an uninitialized portion of the texture image to a primitive.
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, glTexImage3D specifies the three-dimensional texture for the current texture unit, specified with glActiveTexture.
If the ARB_imaging extension is supported, RGBA elements may also be processed by the imaging pipeline. The following stages may be applied to an RGBA color before color component clamping to the range [0,1]:
1. Color component replacement by the color table specified for GL_COLOR_TABLE, if enabled. See glColorTable.
2. Color component replacement by the color table specified for GL_POST_CONVOLUTION_COLOR_TABLE, if enabled. See glColorTable.
3. Transformation by the color matrix. See glMatrixMode.
4. RGBA components may be multiplied by GL_POST_COLOR_MATRIX_c_SCALE, and added to GL_POST_COLOR_MATRIX_c_BIAS, if enabled. See glPixelTransfer.
5. Color component replacement by the color table specified for GL_POST_COLOR_MATRIX_COLOR_TABLE, if enabled. See glColorTable.
Non-power-of-two textures are supported if the GL version is 2.0 or greater, or if the implementation exports the GL_ARB_texture_non_power_of_two extension.
The GL_SRGB, GL_SRGB8, GL_SRGB_ALPHA, GL_SRGB8_ALPHA8, GL_SLUMINANCE, GL_SLUMINANCE8, GL_SLUMINANCE_ALPHA, and GL_SLUMINANCE8_ALPHA8 internal formats are only available if the GL version is 2.1 or greater.
Errors
GL_INVALID_ENUM is generated if target is not GL_TEXTURE_3D or GL_PROXY_TEXTURE_3D.
GL_INVALID_ENUM is generated if format is not an accepted format constant. Format constants other than GL_STENCIL_INDEX and GL_DEPTH_COMPONENT are accepted.
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 log2(max), where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE is generated if internalFormat is not 1, 2, 3, 4, or one of the accepted resolution and format symbolic constants.
GL_INVALID_VALUE is generated if width, height, or depth is less than 0 or greater than 2 + GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE is generated if non-power-of-two textures are not supported and the width, depth, or depth cannot be represented as 2k + 2(border) for some integer value of k.
GL_INVALID_VALUE is generated if border is not 0 or 1.
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 format or internalFormat is GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24, or GL_DEPTH_COMPONENT32.
GL_INVALID_OPERATION is generated if a nonzero 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 nonzero 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 nonzero 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 glTexImage3D is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetTexImage
glIsEnabled with argument GL_TEXTURE_3D
glGet with argument GL_PIXEL_UNPACK_BUFFER_BINDING
See Also
glActiveTexture, glColorTable, glCompressedTexImage1D, glCompressedTexImage2D, glCompressedTexImage3D, glCompressedTexSubImage1D, glCompressedTexSubImage2D, glCompressedTexSubImage3D, glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glGetCompressedTexImage, glMatrixMode, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage1D, glTexImage2D, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D, glTexParameter
glTexParameter
Set texture parameters
C Specification
Parameters
C Specification
Description
Texture mapping is a technique that applies an image onto an object’s surface as if the image were a decal or cellophane shrink-wrap. The image is created in texture space, with an (s, t) coordinate system. A texture is a one- or two-dimensional image and a set of parameters that determine how samples are derived from the image.
glTexParameter assigns the value or values in params to the texture parameter specified as pname. target defines the target texture, either GL_TEXTURE_1D, GL_TEXTURE_2D, or GL_TEXTURE_3D. The following symbols are accepted in pname:
GL_TEXTURE_MIN_FILTER
The texture minifying function is used whenever the pixel being textured maps to an area greater than one texture element. There are six defined minifying functions. Two of them use the nearest one or nearest four texture elements to compute the texture value. The other four use mipmaps.
A mipmap is an ordered set of arrays representing the same image at progressively lower resolutions. If the texture has dimensions 2n × 2m, there are max(n,m) + 1 mipmaps. The first mipmap is the original texture, with dimensions 2n × 2m. Each subsequent mipmap has dimensions 2k–1 × 2l–1, where 2k × 2l are the dimensions of the previous mipmap, until either k = 0 or l = 0. At that point, subsequent mipmaps have dimension 1 × 2l–1 or 2k–1 × 1 until the final mipmap, which has dimension 1 × 1. To define the mipmaps, call glTexImage1D, glTexImage2D, glTexImage3D, glCopyTexImage1D, or glCopyTexImage2D with the level argument indicating the order of the mipmaps. Level 0 is the original texture; level max(n,m) is the final 1 × 1 mipmap.
params supplies a function for minifying the texture as one of the following:
GL_NEAREST
Returns the value of the texture element that is nearest (in Manhattan distance) to the center of the pixel being textured.
GL_LINEAR
Returns the weighted average of the four texture elements that are closest to the center of the pixel being textured. These can include border texture elements, depending on the values of GL_TEXTURE_WRAP_S and GL_TEXTURE_WRAP_T, and on the exact mapping.
GL_NEAREST_MIPMAP_NEAREST
Chooses the mipmap that most closely matches the size of the pixel being textured and uses the GL_NEAREST criterion (the texture element nearest to the center of the pixel) to produce a texture value.
GL_LINEAR_MIPMAP_NEAREST
Chooses the mipmap that most closely matches the size of the pixel being textured and uses the GL_LINEAR criterion (a weighted average of the four texture elements that are closest to the center of the pixel) to produce a texture value.
GL_NEAREST_MIPMAP_LINEAR
Chooses the two mipmaps that most closely match the size of the pixel being textured and uses the GL_NEAREST criterion (the texture element nearest to the center of the pixel) to produce a texture value from each mipmap. The final texture value is a weighted average of those two values.
Chooses the two mipmaps that most closely match the size of the pixel being textured and uses the GL_LINEAR criterion (a weighted average of the four texture elements that are closest to the center of the pixel) to produce a texture value from each mipmap. The final texture value is a weighted average of those two values.
As more texture elements are sampled in the minification process, fewer aliasing artifacts will be apparent. While the GL_NEAREST and GL_LINEAR minification functions can be faster than the other four, they sample only one or four texture elements to determine the texture value of the pixel being rendered and can produce moire patterns or ragged transitions. The initial value of GL_TEXTURE_MIN_FILTER is GL_NEAREST_MIPMAP_LINEAR.
GL_TEXTURE_MAG_FILTER
The texture magnification function is used when the pixel being textured maps to an area less than or equal to one texture element. It sets the texture magnification function to either GL_NEAREST or GL_LINEAR (see below). GL_NEAREST is generally faster than GL_LINEAR, but it can produce textured images with sharper edges because the transition between texture elements is not as smooth. The initial value of GL_TEXTURE_MAG_FILTER is GL_LINEAR.
GL_NEAREST
Returns the value of the texture element that is nearest (in Manhattan distance) to the center of the pixel being textured.
GL_LINEAR
Returns the weighted average of the four texture elements that are closest to the center of the pixel being textured. These can include border texture elements, depending on the values of GL_TEXTURE_WRAP_S and GL_TEXTURE_WRAP_T, and on the exact mapping.
GL_TEXTURE_MIN_LOD
Sets the minimum level-of-detail parameter. This floating-point value limits the selection of highest resolution mipmap (lowest mipmap level). The initial value is -1000.
GL_TEXTURE_MAX_LOD
Sets the maximum level-of-detail parameter. This floating-point value limits the selection of the lowest resolution mipmap (highest mipmap level). The initial value is 1000.
GL_TEXTURE_BASE_LEVEL
Specifies the index of the lowest defined mipmap level. This is an integer value. The initial value is 0.
GL_TEXTURE_MAX_LEVEL
Sets the index of the highest defined mipmap level. This is an integer value. The initial value is 1000.
GL_TEXTURE_WRAP_S
Sets the wrap parameter for texture coordinate s to either GL_CLAMP, GL_CLAMP_TO_BORDER, GL_CLAMP_TO_EDGE, GL_MIRRORED_REPEAT, or GL_REPEAT. GL_CLAMP causes s coordinates to be clamped to the range [0,1] and is useful for preventing wrapping artifacts when mapping a single image onto an object. GL_CLAMP_TO_BORDER causes the s coordinate to be clamped to the range 
, where N is the size of the texture in the direction of clamping.GL_CLAMP_TO_EDGE causes s coordinates to be clamped to the range 
, where N is the size of the texture in the direction of clamping.
GL_REPEAT causes the integer part of the s coordinate to be ignored; the GL uses only the fractional part, thereby creating a repeating pattern. GL_MIRRORED_REPEAT causes the s coordinate to be set to the fractional part of the texture coordinate if the integer part of s is even; if the integer part of s is odd, then the s texture coordinate is set to 1 – frac (s), where frac (s) represents the fractional part of s. Border texture elements are accessed only if wrapping is set to GL_CLAMP or GL_CLAMP_TO_BORDER. Initially, GL_TEXTURE_WRAP_S is set to GL_REPEAT.
Sets the wrap parameter for texture coordinate t to either GL_CLAMP, GL_CLAMP_TO_BORDER, GL_CLAMP_TO_EDGE, GL_MIRRORED_REPEAT, or GL_REPEAT. See the discussion under GL_TEXTURE_WRAP_S. Initially, GL_TEXTURE_WRAP_T is set to GL_REPEAT.
GL_TEXTURE_WRAP_R
Sets the wrap parameter for texture coordinate r to either GL_CLAMP, GL_CLAMP_TO_BORDER, GL_CLAMP_TO_EDGE, GL_MIRRORED_REPEAT, or GL_REPEAT. See the discussion under GL_TEXTURE_WRAP_S. Initially, GL_TEXTURE_WRAP_R is set to GL_REPEAT.
GL_TEXTURE_BORDER_COLOR
Sets a border color. params contains four values that comprise the RGBA color of the texture border. Integer color components are interpreted linearly such that the most positive integer maps to 1.0, and the most negative integer maps to -1.0. The values are clamped to the range [0,1] when they are specified. Initially, the border color is (0, 0, 0, 0).
GL_TEXTURE_PRIORITY
Specifies the texture residence priority of the currently bound texture. Permissible values are in the range [0,1]. See glPrioritizeTextures and glBindTexture for more information.
GL_TEXTURE_COMPARE_MODE
Specifies the texture comparison mode for currently bound depth textures. That is, a texture whose internal format is GL_DEPTH_COMPONENT_*; see glTexImage2D) Permissible values are:
GL_COMPARE_R_TO_TEXTURE
Specifies that the interpolated and clamped r texture coordinate should be compared to the value in the currently bound depth texture. See the discussion of GL_TEXTURE_COMPARE_FUNC for details of how the comparison is evaluated. The result of the comparison is assigned to luminance, intensity, or alpha (as specified by GL_DEPTH_TEXTURE_MODE).
GL_NONE
Specifies that the luminance, intensity, or alpha (as specified by GL_DEPTH_TEXTURE_MODE) should be assigned the appropriate value from the currently bound depth texture.
GL_TEXTURE_COMPARE_FUNC
Specifies the comparison operator used when GL_TEXTURE_COMPARE_MODE is set to GL_COMPARE_R_TO_TEXTURE. Permissible values are:
where r is the current interpolated texture coordinate, and Dt is the depth texture value sampled from the currently bound depth texture. result is assigned to the either the luminance, intensity, or alpha (as specified by GL_DEPTH_TEXTURE_MODE).
GL_DEPTH_TEXTURE_MODE
Specifies a single symbolic constant indicating how depth values should be treated during filtering and texture application. Accepted values are GL_LUMINANCE, GL_INTENSITY, and GL_ALPHA. The initial value is GL_LUMINANCE.
GL_GENERATE_MIPMAP
Specifies a boolean value that indicates if all levels of a mipmap array should be automatically updated when any modification to the base level mipmap is done. The initial value is GL_FALSE.
Notes
GL_TEXTURE_3D, GL_TEXTURE_MIN_LOD, GL_TEXTURE_MAX_LOD, GL_CLAMP_TO_EDGE, GL_TEXTURE_BASE_LEVEL, and GL_TEXTURE_MAX_LEVEL are available only if the GL version is 1.2 or greater.
GL_CLAMP_TO_BORDER is available only if the GL version is 1.3 or greater.
GL_MIRRORED_REPEAT, GL_TEXTURE_COMPARE_MODE, GL_TEXTURE_COMPARE_FUNC, GL_DEPTH_TEXTURE_MODE, and GL_GENERATE_MIPMAP are available only if the GL version is 1.4 or greater.
GL_TEXTURE_COMPARE_FUNC allows the following additional comparison modes only if the GL version is 1.5 or greater: GL_LESS, GL_GREATER, GL_EQUAL, GL_NOTEQUAL, GL_ALWAYS, and GL_NEVER.
Suppose that a program has enabled texturing (by calling glEnable with argument GL_TEXTURE_1D, GL_TEXTURE_2D, or GL_TEXTURE_3D) and has set GL_TEXTURE_MIN_FILTER to one of the functions that requires a mipmap. If either the dimensions of the texture images currently defined (with previous calls to glTexImage1D, glTexImage2D, glTexImage3D, glCopyTexImage1D, or glCopyTexImage2D) do not follow the proper sequence for mipmaps (described above), or there are fewer texture images defined than are needed, or the set of texture images have differing numbers of texture components, then it is as if texture mapping were disabled.
Linear filtering accesses the four nearest texture elements only in 2D textures. In 1D textures, linear filtering accesses the two nearest texture elements.
For OpenGL versions 1.3 and greater, or when the ARB_multitexture extension is supported, glTexParameter specifies the texture parameters for the active texture unit, specified by calling glActiveTexture.
Errors
GL_INVALID_ENUM is generated if target or pname is not one of the accepted defined values.
GL_INVALID_ENUM is generated if params should have a defined constant value (based on the value of pname) and does not.
GL_INVALID_OPERATION is generated if glTexParameter is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetTexParameter
glGetTexLevelParameter
See Also
glActiveTexture, glBindTexture, glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glPixelStore, glPixelTransfer, glPrioritizeTextures, glTexEnv, glTexGen, glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D
glTexSubImage1D
Specify a one-dimensional texture subimage
C Specification
Parameters
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 nonzero 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 log2max, 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 nonzero 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 nonzero 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 nonzero 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
glTexSubImage2D
Specify a two-dimensional texture subimage
C Specification
Parameters
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.
glTexSubImage2D redefines a contiguous subregion of an existing two-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, 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.
If a nonzero 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
glTexSubImage2D 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, glTexSubImage2D specifies a two-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 GL_TEXTURE_2D.
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 log2max, where max is the returned value of GL_MAX_TEXTURE_SIZE.
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_VALUE is generated if width or height is less than 0.
GL_INVALID_OPERATION is generated if the texture array has not been defined by a previous glTexImage2D 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 nonzero 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 nonzero 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 nonzero 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 glTexSubImage2D is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetTexImage
glIsEnabled with argument GL_TEXTURE_2D
glGet with argument GL_PIXEL_UNPACK_BUFFER_BINDING
See Also
glActiveTexture, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage3D, glTexParameter
glTexSubImage3D
Specify a three-dimensional texture subimage
C Specification
Parameters
Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is enabled. To enable and disable three-dimensional texturing, call glEnable and glDisable with argument GL_TEXTURE_3D.
glTexSubImage3D redefines a contiguous subregion of an existing three-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, y indices yoffset and yoffset + height – 1, inclusive, and z indices zoffset and zoffset + depth – 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, height, or depth but such a specification has no effect.
If a nonzero 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
glTexSubImage3D is available only if the GL version is 1.2 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, glTexSubImage3D specifies a three-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 glTexImage3D for specific details.
Errors
GL_INVALID_ENUM is generated if target is not GL_TEXTURE_3D.
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 log2max, where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE is generated if xoffset<–b, (xoffset + width) > (w – b), yoffset<–b, or (yoffset + height) > (h – b), or zoffset<–b, or (zoffset + depth) > (d – b), where w is the GL_TEXTURE_WIDTH, h is the GL_TEXTURE_HEIGHT, d is the GL_TEXTURE_DEPTH and b is the border width of the texture image being modified. Note that w, h, and d include twice the border width.
GL_INVALID_VALUE is generated if width, height, or depth is less than 0.
GL_INVALID_OPERATION is generated if the texture array has not been defined by a previous glTexImage3D 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 nonzero 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 nonzero 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 nonzero 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 glTexSubImage3D is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetTexImage
glIsEnabled with argument GL_TEXTURE_3D
glGet with argument GL_PIXEL_UNPACK_BUFFER_BINDING
See Also
glActiveTexture, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, glTexParameter
glTranslate
Multiply the current matrix by a translation matrix
C Specification
Parameters
Description
glTranslate produces a translation by (x,y,z). The current matrix (see glMatrixMode) is multiplied by this translation matrix, with the product replacing the current matrix, as if glMultMatrix were called with the following matrix for its argument:
If the matrix mode is either GL_MODELVIEW or GL_PROJECTION, all objects drawn after a call to glTranslate are translated.
Use glPushMatrix and glPopMatrix to save and restore the untranslated coordinate system.
Errors
GL_INVALID_OPERATION is generated if glTranslate is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_MATRIX_MODE
glGet with argument GL_COLOR_MATRIX
glGet with argument GL_MODELVIEW_MATRIX
glGet with argument GL_PROJECTION_MATRIX
glGet with argument GL_TEXTURE_MATRIX
See Also
glMatrixMode, glMultMatrix, glPushMatrix, glRotate, glScale
glUniform
Specify the value of a uniform variable for the current program object
C Specification
Parameters
Parameters
C Specification
Description
glUniform modifies the value of a uniform variable or a uniform variable array. The location of the uniform variable to be modified is specified by location, which should be a value returned by glGetUniformLocation. glUniform operates on the program object that was made part of current state by calling glUseProgram.
The commands glUniform{1|2|3|4}{f|i} are used to change the value of the uniform variable specified by location using the values passed as arguments. The number specified in the command should match the number of components in the data type of the specified uniform variable (e.g., 1 for float, int, bool; 2 for vec2, ivec2, bvec2, etc.). The suffix f indicates that floating-point values are being passed; the suffix i indicates that integer values are being passed, and this type should also match the data type of the specified uniform variable. The i variants of this function should be used to provide values for uniform variables defined as int, ivec2, ivec3, ivec4, or arrays of these. The f variants should be used to provide values for uniform variables of type float, vec2, vec3, vec4, or arrays of these. Either the i or the f variants may be used to provide values for uniform variables of type bool, bvec2, bvec3, bvec4, or arrays of these. The uniform variable will be set to false if the input value is 0 or 0.0f, and it will be set to true otherwise.
All active uniform variables defined in a program object are initialized to 0 when the program object is linked successfully. They retain the values assigned to them by a call to glUniform until the next successful link operation occurs on the program object, when they are once again initialized to 0.
The commands glUniform{1|2|3|4}{f|i}v can be used to modify a single uniform variable or a uniform variable array. These commands pass a count and a pointer to the values to be loaded into a uniform variable or a uniform variable array. A count of 1 should be used if modifying the value of a single uniform variable, and a count of 1 or greater can be used to modify an entire array or part of an array. When loading n elements starting at an arbitrary position m in a uniform variable array, elements m + n - 1 in the array will be replaced with the new values. If m + n - 1 is larger than the size of the uniform variable array, values for all array elements beyond the end of the array will be ignored. The number specified in the name of the command indicates the number of components for each element in value, and it should match the number of components in the data type of the specified uniform variable (e.g., 1 for float, int, bool; 2 for vec2, ivec2, bvec2, etc.). The data type specified in the name of the command must match the data type for the specified uniform variable as described previously for glUniform{1|2|3|4}{f|i}.
For uniform variable arrays, each element of the array is considered to be of the type indicated in the name of the command (e.g., glUniform3f or glUniform3fv can be used to load a uniform variable array of type vec3). The number of elements of the uniform variable array to be modified is specified by count.
The commands glUniformFloatMatrix{2|3|4|2x3|3x2|2x4|4x2|3x4|4x3}fv are used to modify a matrix or an array of matrices. The numbers in the command name are interpreted as the dimensionality of the matrix. The number 2 indicates a 2 × 2 matrix (i.e., 4 values), the number 3 indicates a 3 × 3 matrix (i.e., 9 values), and the number 4 indicates a 4 × 4 matrix (i.e., 16 values). Non-square matrix dimensionality is explicit, with the first number representing the number of columns and the second number representing the number of rows. For example, 2x4 indicates a 2 × 4 matrix with 2 columns and 4 rows (i.e., 8 values). If transpose is GL_FALSE, each matrix is assumed to be supplied in column major order. If transpose is GL_TRUE, each matrix is assumed to be supplied in row major order. The count argument indicates the number of matrices to be passed. A count of 1 should be used if modifying the value of a single matrix, and a count greater than 1 can be used to modify an array of matrices.
Notes
glUniform is available only if the GL version is 2.0 or greater.
glUniformMatrix{2x3|3x2|2x4|4x2|3x4|4x3}fv is available only if the GL version is 2.1 or greater.
glUniform1i and glUniform1iv are the only two functions that may be used to load uniform variables defined as sampler types. Loading samplers with any other function will result in a GL_INVALID_OPERATION error.
If count is greater than 1 and the indicated uniform variable is not an array, a GL_INVALID_OPERATION error is generated and the specified uniform variable will remain unchanged.
Other than the preceding exceptions, if the type and size of the uniform variable as defined in the shader do not match the type and size specified in the name of the command used to load its value, a GL_INVALID_OPERATION error will be generated and the specified uniform variable will remain unchanged.
If location is a value other than -1 and it does not represent a valid uniform variable location in the current program object, an error will be generated, and no changes will be made to the uniform variable storage of the current program object. If location is equal to -1, the data passed in will be silently ignored and the specified uniform variable will not be changed.
Errors
GL_INVALID_OPERATION is generated if there is no current program object.
GL_INVALID_OPERATION is generated if the size of the uniform variable declared in the shader does not match the size indicated by the glUniform command.
GL_INVALID_OPERATION is generated if one of the integer variants of this function is used to load a uniform variable of type float, vec2, vec3, vec4, or an array of these, or if one of the floating-point variants of this function is used to load a uniform variable of type int, ivec2, ivec3, or ivec4, or an array of these.
GL_INVALID_OPERATION is generated if location is an invalid uniform location for the current program object and location is not equal to -1.
GL_INVALID_VALUE is generated if count is less than 0.
GL_INVALID_OPERATION is generated if count is greater than 1 and the indicated uniform variable is not an array variable.
GL_INVALID_OPERATION is generated if a sampler is loaded using a command other than glUniform1i and glUniform1iv.
GL_INVALID_OPERATION is generated if glUniform is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with the argument GL_CURRENT_PROGRAM
glGetActiveUniform with the handle of a program object and the index of an active uniform variable
glGetUniform with the handle of a program object and the location of a uniform variable
glGetUniformLocation with the handle of a program object and the name of a uniform variable
See Also
glLinkProgram, glUseProgram
glUseProgram
Installs a program object as part of current rendering state
C Specification
void glUseProgram(GLuint program);
Parameters
Description
glUseProgram installs the program object specified by program as part of current rendering state. One or more executables are created in a program object by successfully attaching shader objects to it with glAttachShader, successfully compiling the shader objects with glCompileShader, and successfully linking the program object with glLinkProgram.
A program object will contain an executable that will run on the vertex processor if it contains one or more shader objects of type GL_VERTEX_SHADER that have been successfully compiled and linked. Similarly, a program object will contain an executable that will run on the fragment processor if it contains one or more shader objects of type GL_FRAGMENT_SHADER that have been successfully compiled and linked.
Successfully installing an executable on a programmable processor will cause the corresponding fixed functionality of OpenGL to be disabled. Specifically, if an executable is installed on the vertex processor, the OpenGL fixed functionality will be disabled as follows.
• The modelview matrix is not applied to vertex coordinates.
• The projection matrix is not applied to vertex coordinates.
• The texture matrices are not applied to texture coordinates.
• Normals are not transformed to eye coordinates.
• Normals are not rescaled or normalized.
• Normalization of GL_AUTO_NORMAL evaluated normals is not performed.
• Texture coordinates are not generated automatically.
• Per-vertex lighting is not performed.
• Color material computations are not performed.
• Color index lighting is not performed.
• This list also applies when setting the current raster position.
The executable that is installed on the vertex processor is expected to implement any or all of the desired functionality from the preceding list. Similarly, if an executable is installed on the fragment processor, the OpenGL fixed functionality will be disabled as follows.
• Texture environment and texture functions are not applied.
• Texture application is not applied.
• Color sum is not applied.
• Fog is not applied.
Again, the fragment shader that is installed is expected to implement any or all of the desired functionality from the preceding list.
While a program object is in use, applications are free to modify attached shader objects, compile attached shader objects, attach additional shader objects, and detach or delete shader objects. None of these operations will affect the executables that are part of the current state. However, relinking the program object that is currently in use will install the program object as part of the current rendering state if the link operation was successful (see glLinkProgram). If the program object currently in use is relinked unsuccessfully, its link status will be set to GL_FALSE, but the executables and associated state will remain part of the current state until a subsequent call to glUseProgram removes it from use. After it is removed from use, it cannot be made part of current state until it has been successfully relinked.
If program contains shader objects of type GL_VERTEX_SHADER but it does not contain shader objects of type GL_FRAGMENT_SHADER, an executable will be installed on the vertex processor, but fixed functionality will be used for fragment processing. Similarly, if program contains shader objects of type GL_FRAGMENT_SHADER but it does not contain shader objects of type GL_VERTEX_SHADER, an executable will be installed on the fragment processor, but fixed functionality will be used for vertex processing. If program is 0, the programmable processors will be disabled, and fixed functionality will be used for both vertex and fragment processing.
Notes
glUseProgram is available only if the GL version is 2.0 or greater.
While a program object is in use, the state that controls the disabled fixed functionality may also be updated using the normal OpenGL calls.
Like display lists and texture objects, the name space for program objects may be shared across a set of contexts, as long as the server sides of the contexts share the same address space. If the name space is shared across contexts, any attached objects and the data associated with those attached objects are shared as well.
Applications are responsible for providing the synchronization across API calls when objects are accessed from different execution threads.
Errors
GL_INVALID_VALUE is generated if program is neither 0 nor a value generated by OpenGL.
GL_INVALID_OPERATION is generated if program is not a program object.
GL_INVALID_OPERATION is generated if program could not be made part of current state.
GL_INVALID_OPERATION is generated if glUseProgram is executed between the execution of glBegin and the corresponding execution of glEnd.
glGet with the argument GL_CURRENT_PROGRAM
glGetActiveAttrib with a valid program object and the index of an active attribute variable
glGetActiveUniform with a valid program object and the index of an active uniform variable
glGetAttachedShaders with a valid program object
glGetAttribLocation with a valid program object and the name of an attribute variable
glGetProgram with a valid program object and the parameter to be queried
glGetProgramInfoLog with a valid program object
glGetUniform with a valid program object and the location of a uniform variable
glGetUniformLocation with a valid program object and the name of a uniform variable
glIsProgram
See Also
gllAttachShader, glBindAttribLocation, glCompileShader, glCreateProgram, glDeleteProgram, glDetachShader, glLinkProgram, glUniform, glValidateProgram, glVertexAttrib
glValidateProgram
Validates a program object
C Specification
void glValidateProgram(GLuint program);
Parameters
Description
glValidateProgram checks to see whether the executables contained in program can execute given the current OpenGL state. The information generated by the validation process will be stored in program’s information log. The validation information may consist of an empty string, or it may be a string containing information about how the current program object interacts with the rest of current OpenGL state. This provides a way for OpenGL implementers to convey more information about why the current program is inefficient, suboptimal, failing to execute, and so on.
The status of the validation operation will be stored as part of the program object’s state. This value will be set to GL_TRUE if the validation succeeded, and GL_FALSE otherwise. It can be queried by calling glGetProgram with arguments program and GL_VALIDATE_STATUS. If validation is successful, program is guaranteed to execute given the current state. Otherwise, program is guaranteed to not execute.
This function is typically useful only during application development. The informational string stored in the information log is completely implementation dependent; therefore, an application should not expect different OpenGL implementations to produce identical information strings.
Notes
glValidateProgram is available only if the GL version is 2.0 or greater.
This function mimics the validation operation that OpenGL implementations must perform when rendering commands are issued while programmable shaders are part of current state. The error GL_INVALID_OPERATION will be generated by glBegin, glRasterPos, or any command that performs an implicit call to glBegin if:
• any two active samplers in the current program object are of different types, but refer to the same texture image unit,
• any active sampler in the current program object refers to a texture image unit where fixed-function fragment processing accesses a texture target that does not match the sampler type, or
• the sum of the number of active samplers in the program and the number of texture image units enabled for fixed-function fragment processing exceeds the combined limit on the total number of texture image units allowed.
It may be difficult or cause a performance degradation for applications to catch these errors when rendering commands are issued. Therefore, applications are advised to make calls to glValidateProgram to detect these issues during application development.
Errors
GL_INVALID_VALUE is generated if program is not a value generated by OpenGL.
GL_INVALID_OPERATION is generated if program is not a program object.
GL_INVALID_OPERATION is generated if glValidateProgram is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetProgram with arguments program and GL_VALIDATE_STATUS
glGetProgramInfoLog with argument program
glIsProgram
See Also
glLinkProgram, glUseProgram
glVertex
Specify a vertex
C Specification
C Specification
Parameters
Description
glVertex commands are used within glBegin/glEnd pairs to specify point, line, and polygon vertices. The current color, normal, texture coordinates, and fog coordinate are associated with the vertex when glVertex is called.
When only x and y are specified, z defaults to 0 and w defaults to 1. When x, y, and z are specified, w defaults to 1.
Notes
Invoking glVertex outside of a glBegin/glEnd pair results in undefined behavior.
See Also
glBegin, glCallList, glColor, glEdgeFlag, glEvalCoord, glFogCoord, glIndex, glMaterial, glMultiTexCoord, glNormal, glRect, glTexCoord, glVertexPointer
glVertexAttrib
Specifies the value of a generic vertex attribute
C Specification
Parameters
C Specification
Parameters
Description
OpenGL defines a number of standard vertex attributes that applications can modify with standard API entry points (color, normal, texture coordinates, etc.). The glVertexAttrib family of entry points allows an application to pass generic vertex attributes in numbered locations.
Generic attributes are defined as four-component values that are organized into an array. The first entry of this array is numbered 0, and the size of the array is specified by the implementation-dependent constant GL_MAX_VERTEX_ATTRIBS. Individual elements of this array can be modified with a glVertexAttrib call that specifies the index of the element to be modified and a value for that element.
These commands can be used to specify one, two, three, or all four components of the generic vertex attribute specified by index. A 1 in the name of the command indicates that only one value is passed, and it will be used to modify the first component of the generic vertex attribute. The second and third components will be set to 0, and the fourth component will be set to 1. Similarly, a 2 in the name of the command indicates that values are provided for the first two components, the third component will be set to 0, and the fourth component will be set to 1. A 3 in the name of the command indicates that values are provided for the first three components and the fourth component will be set to 1, whereas a 4 in the name indicates that values are provided for all four components.
The letters s, f, i, d, ub, us, and ui indicate whether the arguments are of type short, float, int, double, unsigned byte, unsigned short, or unsigned int. When v is appended to the name, the commands can take a pointer to an array of such values. The commands containing N indicate that the arguments will be passed as fixed-point values that are scaled to a normalized range according to the component conversion rules defined by the OpenGL specification. Signed values are understood to represent fixed-point values in the range [-1,1], and unsigned values are understood to represent fixed-point values in the range [0,1].
OpenGL Shading Language attribute variables are allowed to be of type mat2, mat3, or mat4. Attributes of these types may be loaded using the glVertexAttrib entry points. Matrices must be loaded into successive generic attribute slots in column major order, with one column of the matrix in each generic attribute slot.
A user-defined attribute variable declared in a vertex shader can be bound to a generic attribute index by calling glBindAttribLocation. This allows an application to use more descriptive variable names in a vertex shader. A subsequent change to the specified generic vertex attribute will be immediately reflected as a change to the corresponding attribute variable in the vertex shader.
The binding between a generic vertex attribute index and a user-defined attribute variable in a vertex shader is part of the state of a program object, but the current value of the generic vertex attribute is not. The value of each generic vertex attribute is part of current state, just like standard vertex attributes, and it is maintained even if a different program object is used.
An application may freely modify generic vertex attributes that are not bound to a named vertex shader attribute variable. These values are simply maintained as part of current state and will not be accessed by the vertex shader. If a generic vertex attribute bound to an attribute variable in a vertex shader is not updated while the vertex shader is executing, the vertex shader will repeatedly use the current value for the generic vertex attribute.
The generic vertex attribute with index 0 is the same as the vertex position attribute previously defined by OpenGL. A glVertex2, glVertex3, or glVertex4 command is completely equivalent to the corresponding glVertexAttrib command with an index argument of 0. A vertex shader can access generic vertex attribute 0 by using the built-in attribute variable gl_Vertex. There are no current values for generic vertex attribute 0. This is the only generic vertex attribute with this property; calls to set other standard vertex attributes can be freely mixed with calls to set any of the other generic vertex attributes.
Notes
glVertexAttrib is available only if the GL version is 2.0 or greater.
Generic vertex attributes can be updated at any time. In particular, glVertexAttrib can be called between a call to glBegin and the corresponding call to glEnd.
It is possible for an application to bind more than one attribute name to the same generic vertex attribute index. This is referred to as aliasing, and it is allowed only if just one of the aliased attribute variables is active in the vertex shader, or if no path through the vertex shader consumes more than one of the attributes aliased to the same location. OpenGL implementations are not required to do error checking to detect aliasing, they are allowed to assume that aliasing will not occur, and they are allowed to employ optimizations that work only in the absence of aliasing.
There is no provision for binding standard vertex attributes; therefore, it is not possible to alias generic attributes with standard attributes.
Errors
GL_INVALID_VALUE is generated if index is greater than or equal to GL_MAX_VERTEX_ATTRIBS.
Associated Gets
glGet with the argument GL_CURRENT_PROGRAM
glGetActiveAttrib with argument program and the index of an active attribute variable
glGetAttribLocation with argument program and an attribute variable name
glGetVertexAttrib with arguments GL_CURRENT_VERTEX_ATTRIB and index
See Also
glBindAttribLocation, glVertex, glVertexAttribPointer
glVertexAttribPointer
Define an array of generic vertex attribute data
C Specification
Parameters
Description
glVertexAttribPointer specifies the location and data format of the array of generic vertex attributes at index index to use when rendering. size specifies the number of components per attribute and must be 1, 2, 3, or 4. type specifies the data type of each component, and stride specifies the byte stride from one attribute to the next, allowing vertices and attributes to be packed into a single array or stored in separate arrays. If set to GL_TRUE, normalized indicates that values stored in an integer format are to be mapped to the range [-1,1] (for signed values) or [0,1] (for unsigned values) when they are accessed and converted to floating point. Otherwise, values will be converted to floats directly without normalization.
If a nonzero named buffer object is bound to the GL_ARRAY_BUFFER target (see glBindBuffer) while a generic vertex attribute array is specified, pointer is treated as a byte offset into the buffer object’s data store. Also, the buffer object binding (GL_ARRAY_BUFFER_BINDING) is saved as generic vertex attribute array client-side state (GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING) for index index.
When a generic vertex attribute array is specified, size, type, normalized, stride, and pointer are saved as client-side state, in addition to the current vertex array buffer object binding. To enable and disable a generic vertex attribute array, call glEnableVertexAttribArray and glDisableVertexAttribArray with index. If enabled, the generic vertex attribute array is used when glArrayElement, glDrawArrays, glMultiDrawArrays, glDrawElements, glMultiDrawElements, or glDrawRangeElements is called.
Notes
glVertexAttribPointer is available only if the GL version is 2.0 or greater.
Each generic vertex attribute array is initially disabled and isn’t accessed when glArrayElement, glDrawElements, glDrawRangeElements, glDrawArrays, glMultiDrawArrays, or glMultiDrawElements is called.
Execution of glVertexAttribPointer is not allowed between the execution of glBegin and the corresponding execution of glEnd, but an error may or may not be generated. If no error is generated, the operation is undefined.
glVertexAttribPointer is typically implemented on the client side.
Generic vertex attribute array parameters are client-side state and are therefore not saved or restored by glPushAttrib and glPopAttrib. Use glPushClientAttrib and glPopClientAttrib instead.
Errors
GL_INVALID_VALUE is generated if index is greater than or equal to GL_MAX_VERTEX_ATTRIBS.
GL_INVALID_VALUE is generated if size is not 1, 2, 3, or 4.
GL_INVALID_ENUM is generated if type is not an accepted value.
GL_INVALID_VALUE is generated if stride is negative.
Associated Gets
glGet with argument GL_MAX_VERTEX_ATTRIBS
glGetVertexAttrib with arguments index and GL_VERTEX_ATTRIB_ARRAY_ENABLED
glGetVertexAttrib with arguments index and GL_VERTEX_ATTRIB_ARRAY_SIZE
glGetVertexAttrib with arguments index and GL_VERTEX_ATTRIB_ARRAY_TYPE
glGetVertexAttrib with arguments index and GL_VERTEX_ATTRIB_ARRAY_NORMALIZED
glGetVertexAttrib with arguments index and GL_VERTEX_ATTRIB_ARRAY_STRIDE
glGetVertexAttrib with arguments index and GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING
glGet with argument GL_ARRAY_BUFFER_BINDING
glGetVertexAttribPointerv with arguments index and GL_VERTEX_ATTRIB_ARRAY_POINTER
See Also
glArrayElement, glBindAttribLocation, glBindBuffer, glColorPointer, glDisableVertexAttribArray, glDrawArrays, glDrawElements, glDrawRangeElements, glEnableVertexAttribArray, glEdgeFlagPointer, glFogCoordPointer, glIndexPointer, glInterleavedArrays, glMultiDrawArrays, glMultiDrawElements, glNormalPointer, glPopClientAttrib, glPushClientAttrib, glSecondaryColorPointer, glTexCoordPointer, glVertexAttrib, glVertexPointer
glVertexPointer
Define an array of vertex data
C Specification
Parameters
Description
glVertexPointer specifies the location and data format of an array of vertex coordinates to use when rendering. size specifies the number of coordinates per vertex, and must be 2, 3, or 4. type specifies the data type of each coordinate, and stride specifies the byte stride from one vertex to the next, allowing vertices and attributes to be packed into a single array or stored in separate arrays. (Single-array storage may be more efficient on some implementations; see glInterleavedArrays.)
If a nonzero named buffer object is bound to the GL_ARRAY_BUFFER target (see glBindBuffer) while a vertex array is specified, pointer is treated as a byte offset into the buffer object’s data store. Also, the buffer object binding (GL_ARRAY_BUFFER_BINDING) is saved as vertex array client-side state (GL_VERTEX_ARRAY_BUFFER_BINDING).
When a vertex array is specified, size, type, stride, and pointer are saved as client-side state, in addition to the current vertex array buffer object binding.
To enable and disable the vertex array, call glEnableClientState and glDisableClientState with the argument GL_VERTEX_ARRAY. If enabled, the vertex array is used when glArrayElement, glDrawArrays, glMultiDrawArrays, glDrawElements, glMultiDrawElements, or glDrawRangeElements is called.
Notes
glVertexPointer is available only if the GL version is 1.1 or greater.
The vertex array is initially disabled and isn’t accessed when glArrayElement, glDrawElements, glDrawRangeElements, glDrawArrays, glMultiDrawArrays, or glMultiDrawElements is called.
Execution of glVertexPointer is not allowed between the execution of glBegin and the corresponding execution of glEnd, but an error may or may not be generated. If no error is generated, the operation is undefined.
glVertexPointer is typically implemented on the client side.
Vertex array parameters are client-side state and are therefore not saved or restored by glPushAttrib and glPopAttrib. Use glPushClientAttrib and glPopClientAttrib instead.
Errors
GL_INVALID_VALUE is generated if size is not 2, 3, or 4.
GL_INVALID_ENUM is generated if type is not an accepted value.
GL_INVALID_VALUE is generated if stride is negative.
glIsEnabled with argument GL_VERTEX_ARRAY
glGet with argument GL_VERTEX_ARRAY_SIZE
glGet with argument GL_VERTEX_ARRAY_TYPE
glGet with argument GL_VERTEX_ARRAY_STRIDE
glGet with argument GL_VERTEX_ARRAY_BUFFER_BINDING
glGet with argument GL_ARRAY_BUFFER_BINDING
glGetPointerv with argument GL_VERTEX_ARRAY_POINTER
See Also
glArrayElement, glBindBuffer, glColorPointer, glDisableClientState, glDrawArrays, glDrawElements, glDrawRangeElements, glEdgeFlagPointer, glEnableClientState, glFogCoordPointer, glIndexPointer, glInterleavedArrays, glMultiDrawArrays, glMultiDrawElements, glNormalPointer, glPopClientAttrib, glPushClientAttrib, glSecondaryColorPointer, glTexCoordPointer, glVertex, glVertexAttribPointer
glViewport
Set the viewport
C Specification
Parameters
Description
glViewport specifies the affine transformation of x and y from normalized device coordinates to window coordinates. Let (xnd,ynd) be normalized device coordinates. Then the window coordinates (xw,yw) are computed as follows:
Viewport width and height are silently clamped to a range that depends on the implementation. To query this range, call glGet with argument GL_MAX_VIEWPORT_DIMS.
Errors
GL_INVALID_VALUE is generated if either width or height is negative.
GL_INVALID_OPE RATION is generated if glViewport is executed between the execution of glBegin and the corresponding execution of glEnd.
glGet with argument GL_VIEWPORT
glGet with argument GL_MAX_VIEWPORT_DIMS
See Also
glDepthRange
glWindowPos
Specify the raster position in window coordinates for pixel operations
C Specification
Parameters
C Specification
Parameters
Description
The GL maintains a 3D position in window coordinates. This position, called the raster position, is used to position pixel and bitmap write operations. It is maintained with subpixel accuracy. See glBitmap, glDrawPixels, and glCopyPixels.
glWindowPos2 specifies the x and y coordinates, while z is implicitly set to 0. glWindowPos3 specifies all three coordinates. The w coordinate of the current raster position is always set to 1.0.
glWindowPos directly updates the x and y coordinates of the current raster position with the values specified. That is, the values are neither transformed by the current modelview and projection matrices, nor by the viewport-to-window transform. The z coordinate of the current raster position is updated in the following manner:
where n is GL_DEPTH_RANGE’s near value, and f is GL_DEPTH_RANGE’s far value. See glDepthRange. The specified coordinates are not clip-tested, causing the raster position to always be valid.
The current raster position also includes some associated color data and texture coordinates. If lighting is enabled, then GL_CURRENT_RASTER_COLOR (in RGBA mode) or GL_CURRENT_RASTER_INDEX (in color index mode) is set to the color produced by the lighting calculation (see glLight, glLightModel, and glShadeModel). If lighting is disabled, current color (in RGBA mode, state variable GL_CURRENT_COLOR) or color index (in color index mode, state variable GL_CURRENT_INDEX) is used to update the current raster color.
GL_CURRENT_RASTER_SECONDARY_COLOR (in RGBA mode) is likewise updated.
Likewise, GL_CURRENT_RASTER_TEXTURE_COORDS is updated as a function of GL_CURRENT_TEXTURE_COORDS, based on the texture matrix and the texture generation functions (see glTexGen). The GL_CURRENT_RASTER_DISTANCE is set to the GL_CURRENT_FOG_COORD.
Notes
glWindowPos is available only if the GL version is 1.4 or greater.
The raster position is modified by glRasterPos, glBitmap, and glWindowPos.
Calling glDrawElements, or glDrawRangeElements may leave the current color or index indeterminate. If glWindowPos is executed while the current color or index is indeterminate, the current raster color or current raster index remains indeterminate.
There are distinct raster texture coordinates for each texture unit. Each texture unit’s current raster texture coordinates are updated by glWindowPos.
Errors
GL_INVALID_OPERATION is generated if glWindowPos is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_CURRENT_RASTER_POSITION
glGet with argument GL_CURRENT_RASTER_POSITION_VALID
glGet with argument GL_CURRENT_RASTER_DISTANCE
glGet with argument GL_CURRENT_RASTER_COLOR
glGet with argument GL_CURRENT_RASTER_SECONDARY_COLOR
glGet with argument GL_CURRENT_RASTER_INDEX
glGet with argument GL_CURRENT_RASTER_TEXTURE_COORDS
See Also
glBitmap, glCopyPixels, glDrawArrays, glDrawElements, glDrawRangeElements, glDrawPixels, glMultiTexCoord, glRasterPos, glTexCoord, glTexGen, glVertex