Parameters
void glNormal3bv(const GLbyte * v);
void glNormal3dv(const GLdouble * v);
void glNormal3fv(const GLfloat * v);
void glNormal3iv(const GLint * v);
void glNormal3sv(const GLshort * v);
Parameters
Description
The current normal is set to the given coordinates whenever glNormal is issued. Byte, short, or integer arguments are converted to floating-point format with a linear mapping that maps the most positive representable integer value to 1.0 and the most negative representable integer value to -1.0.
Normals specified with glNormal need not have unit length. If GL_NORMALIZE is enabled, then normals of any length specified with glNormal are normalized after transformation. If GL_RESCALE_NORMAL is enabled, normals are scaled by a scaling factor derived from the modelview matrix. GL_RESCALE_NORMAL requires that the originally specified normals were of unit length, and that the modelview matrix contain only uniform scales for proper results. To enable and disable normalization, call glEnable and glDisable with either GL_NORMALIZE or GL_RESCALE_NORMAL. Normalization is initially disabled.
Notes
The current normal can be updated at any time. In particular, glNormal can be called between a call to glBegin and the corresponding call to glEnd.
Associated Gets
glGet with argument GL_CURRENT_NORMAL
glIsEnabled with argument GL_NORMALIZE
glIsEnabled with argument GL_RESCALE_NORMAL
See Also
glBegin, glColor, glIndex, glMultiTexCoord, glNormalPointer, glTexCoord, glVertex
glNormalPointer
Define an array of normals
C Specification
void glNormalPointer(GLenum type,
GLsizei stride,
const GLvoid * pointer);
Parameters
glNormalPointer specifies the location and data format of an array of normals to use when rendering. type specifies the data type of each normal coordinate, and stride specifies the byte stride from one normal 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 normal 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 normal vertex array client-side state (GL_NORMAL_ARRAY_BUFFER_BINDING).
When a normal array is specified, 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 normal array, call glEnableClientState and glDisableClientState with the argument GL_NORMAL_ARRAY. If enabled, the normal array is used when glDrawArrays, glMultiDrawArrays, glDrawElements, glMultiDrawElements, glDrawRangeElements, or glArrayElement is called.
Notes
glNormalPointer is available only if the GL version is 1.1 or greater.
The normal array is initially disabled and isn’t accessed when glArrayElement, glDrawElements, glDrawRangeElements, glDrawArrays, glMultiDrawArrays, or glMultiDrawElements is called.
Execution of glNormalPointer is not allowed between glBegin and the corresponding glEnd, but an error may or may not be generated. If an error is not generated, the operation is undefined.
glNormalPointer is typically implemented on the client side.
Normal 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_ENUM is generated if type is not an accepted value.
GL_INVALID_VALUE is generated if stride is negative.
Associated Gets
glIsEnabled with argument GL_NORMAL_ARRAY
glGet with argument GL_NORMAL_ARRAY_TYPE
glGet with argument GL_NORMAL_ARRAY_STRIDE
glGet with argument GL_NORMAL_ARRAY_BUFFER_BINDING
glGet with argument GL_ARRAY_BUFFER_BINDING
glGetPointerv with argument GL_NORMAL_ARRAY_POINTER
See Also
glArrayElement, glBindBuffer, glColorPointer, glDisableClientState, glDrawArrays, glDrawElements, glDrawRangeElements, glEdgeFlagPointer, glEnableClientState, glFogCoordPointer, glIndexPointer, glInterleavedArrays, glMultiDrawArrays, glMultiDrawElements, glNormal, glPopClientAttrib, glPushClientAttrib, glSecondaryColorPointer, glTexCoordPointer, glVertexAttribPointer, glVertexPointer
glOrtho
Multiply the current matrix with an orthographic matrix
C Specification
void glOrtho(GLdouble left,
GLdouble right,
GLdouble bottom,
GLdouble top,
GLdouble nearVal,
GLdouble farVal);
Parameters
Description
glOrtho describes a transformation that produces a parallel projection. The current matrix (see glMatrixMode) is multiplied by this matrix and the result replaces the current matrix, as if glMultMatrix were called with the following matrix as its argument:
where
Typically, the matrix mode is GL_PROJECTION, and (left, bottom, -nearVal) and (right, top, -nearVal) specify the points on the near clipping plane that are mapped to the lower-left and upper-right corners of the window, respectively, assuming that the eye is located at (0, 0, 0). -farVal specifies the location of the far clipping plane. Both nearVal and farVal can be either positive or negative.
Use glPushMatrix and glPopMatrix to save and restore the current matrix stack.
Errors
GL_INVALID_OPERATION is generated if glOrtho 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
glFrustum, glMatrixMode, glMultMatrix, glPushMatrix, glViewport
glPassThrough
Place a marker in the feedback buffer
C Specification
void glPassThrough(GLfloat token);
Parameters
Description
Feedback is a GL render mode. The mode is selected by calling glRenderMode with GL_FEEDBACK. When the GL is in feedback mode, no pixels are produced by rasterization. Instead, information about primitives that would have been rasterized is fed back to the application using the GL. See the glFeedbackBuffer reference page for a description of the feedback buffer and the values in it.
glPassThrough inserts a user-defined marker in the feedback buffer when it is executed in feedback mode. token is returned as if it were a primitive; it is indicated with its own unique identifying value: GL_PASS_THROUGH_TOKEN. The order of glPassThrough commands with respect to the specification of graphics primitives is maintained.
Notes
glPassThrough is ignored if the GL is not in feedback mode.
Errors
GL_INVALID_OPERATION is generated if glPassThrough is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_RENDER_MODE
See Also
glFeedbackBuffer, glRenderMode
glPixelMap
Set up pixel transfer maps
C Specification
void glPixelMapfv(GLenum map,
GLsizei mapsize,
const GLfloat * values);
void glPixelMapuiv(GLenum map,
GLsizei mapsize,
const GLuint * values);
void glPixelMapusv(GLenum map,
GLsizei mapsize,
const GLushort * values);
Parameters
Description
glPixelMap sets up translation tables, or maps, used by glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glReadPixels, glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, and glTexSubImage3D. Additionally, if the ARB_imaging subset is supported, the routines glColorTable, glColorSubTable, glConvolutionFilter1D, glConvolutionFilter2D, glHistogram, glMinmax, and glSeparableFilter2D. Use of these maps is described completely in the glPixelTransfer reference page, and partly in the reference pages for the pixel and texture image commands. Only the specification of the maps is described in this reference page.
map is a symbolic map name, indicating one of ten maps to set. mapsize specifies the number of entries in the map, and values is a pointer to an array of mapsize map values.
If a nonzero named buffer object is bound to the GL_PIXEL_UNPACK_BUFFER target (see glBindBuffer) while a pixel transfer map is specified, values is treated as a byte offset into the buffer object’s data store.
The ten maps are as follows:
GL_PIXEL_MAP_I_TO_I
Maps color indices to color indices.
GL_PIXEL_MAP_S_TO_S
Maps stencil indices to stencil indices.
GL_PIXEL_MAP_I_TO_R
Maps color indices to red components.
GL_PIXEL_MAP_I_TO_G
Maps color indices to green components.
GL_PIXEL_MAP_I_TO_B
Maps color indices to blue components.
GL_PIXEL_MAP_I_TO_A
Maps color indices to alpha components.
GL_PIXEL_MAP_R_TO_R
Maps red components to red components.
GL_PIXEL_MAP_G_TO_G
Maps green components to green components.
GL_PIXEL_MAP_B_TO_B
Maps blue components to blue components.
GL_PIXEL_MAP_A_TO_A
Maps alpha components to alpha components.
The entries in a map can be specified as single-precision floating-point numbers, unsigned short integers, or unsigned int integers. Maps that store color component values (all but GL_PIXEL_MAP_I_TO_I and GL_PIXEL_MAP_S_TO_S) retain their values in floating-point format, with unspecified mantissa and exponent sizes. Floating-point values specified by glPixelMapfv are converted directly to the internal floating-point format of these maps, then clamped to the range [0,1]. Unsigned integer values specified by glPixelMapusv and glPixelMapuiv are converted linearly such that the largest representable integer maps to 1.0, and 0 maps to 0.0.
Maps that store indices, GL_PIXEL_MAP_I_TO_I and GL_PIXEL_MAP_S_TO_S, retain their values in fixed-point format, with an unspecified number of bits to the right of the binary point. Floating-point values specified by glPixelMapfv are converted directly to the internal fixed-point format of these maps. Unsigned integer values specified by glPixelMapusv and glPixelMapuiv specify integer values, with all 0’s to the right of the binary point.
The following table shows the initial sizes and values for each of the maps. Maps that are indexed by either color or stencil indices must have mapsize = 2n for some n or the results are undefined. The maximum allowable size for each map depends on the implementation and can be determined by calling glGet with argument GL_MAX_PIXEL_MAP_TABLE. The single maximum applies to all maps; it is at least 32.
Errors
GL_INVALID_ENUM is generated if map is not an accepted value.
GL_INVALID_VALUE is generated if mapsize is less than one or larger than GL_MAX_PIXEL_MAP_TABLE.
GL_INVALID_VALUE is generated if map is GL_PIXEL_MAP_I_TO_I, GL_PIXEL_MAP_S_TO_S, GL_PIXEL_MAP_I_TO_R, GL_PIXEL_MAP_I_TO_G, GL_PIXEL_MAP_I_TO_B, or GL_PIXEL_MAP_I_TO_A, and mapsize is not a power of two.
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 by glPixelMapfv if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and values is not evenly divisible into the number of bytes needed to store in memory a GLfloat datum.
GL_INVALID_OPERATION is generated by glPixelMapuiv if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and values is not evenly divisible into the number of bytes needed to store in memory a GLuint datum.
GL_INVALID_OPERATION is generated by glPixelMapusv if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and values is not evenly divisible into the number of bytes needed to store in memory a GLushort datum.
GL_INVALID_OPERATION is generated if glPixelMap is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetPixelMap
glGet with argument GL_PIXEL_MAP_I_TO_I_SIZE
glGet with argument GL_PIXEL_MAP_S_TO_S_SIZE
glGet with argument GL_PIXEL_MAP_I_TO_R_SIZE
glGet with argument GL_PIXEL_MAP_I_TO_G_SIZE
glGet with argument GL_PIXEL_MAP_I_TO_B_SIZE
glGet with argument GL_PIXEL_MAP_I_TO_A_SIZE
glGet with argument GL_PIXEL_MAP_R_TO_R_SIZE
glGet with argument GL_PIXEL_MAP_G_TO_G_SIZE
glGet with argument GL_PIXEL_MAP_B_TO_B_SIZE
glGet with argument GL_PIXEL_MAP_A_TO_A_SIZE
glGet with argument GL_MAX_PIXEL_MAP_TABLE
glGet with argument GL_PIXEL_UNPACK_BUFFER_BINDING
See Also
glColorTable, glColorSubTable, glConvolutionFilter1D, glConvolutionFilter2D, glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glDrawPixels, glHistogram, glMinmax, glPixelStore, glPixelTransfer, glReadPixels, glSeparableFilter2D, glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D
glPixelStore
Set pixel storage modes
C Specification
void glPixelStoref(GLenum pname,
GLfloat param);
void glPixelStorei(GLenum pname,
GLint param);
Parameters
Description
glPixelStore sets pixel storage modes that affect the operation of subsequent glDrawPixels and glReadPixels as well as the unpacking of polygon stipple patterns (see glPolygonStipple), bitmaps (see glBitmap), texture patterns (see glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D). Additionally, if the ARB_imaging extension is supported, pixel storage modes affect convolution filters (see glConvolutionFilter1D,glConvolutionFilter2D, and glSeparableFilter2D, color table (see glColorTable, and glColorSubTable, and unpacking histogram (See glHistogram), and minmax (See glMinmax) data.
pname is a symbolic constant indicating the parameter to be set, and param is the new value. Six of the twelve storage parameters affect how pixel data is returned to client memory. They are as follows:
GL_PACK_SWAP_BYTES
If true, byte ordering for multibyte color components, depth components, color indices, or stencil indices is reversed. That is, if a four-byte component consists of bytes b0, b1, b2, b3, it is stored in memory as b3, b2, b1, b0 if GL_PACK_SWAP_BYTES is true. GL_PACK_SWAP_BYTES has no effect on the memory order of components within a pixel, only on the order of bytes within components or indices. For example, the three components of a GL_RGB format pixel are always stored with red first, green second, and blue third, regardless of the value of GL_PACK_SWAP_BYTES.
GL_PACK_LSB_FIRST
If true, bits are ordered within a byte from least significant to most significant; otherwise, the first bit in each byte is the most significant one. This parameter is significant for bitmap data only.
GL_PACK_ROW_LENGTH
If greater than 0, GL_PACK_ROW_LENGTH defines the number of pixels in a row. If the first pixel of a row is placed at location p in memory, then the location of the first pixel of the next row is obtained by skipping
components or indices, where n is the number of components or indices in a pixel, l is the number of pixels in a row (GL_PACK_ROW_LENGTH if it is greater than 0, the width argument to the pixel routine otherwise), a is the value of GL_PACK_ALIGNMENT, and s is the size, in bytes, of a single component (if a<s, then it is as if a = s). In the case of 1-bit values, the location of the next row is obtained by skipping
components or indices.
The word component in this description refers to the nonindex values red, green, blue, alpha, and depth. Storage format GL_RGB, for example, has three components per pixel: first red, then green, and finally blue.
GL_PACK_IMAGE_HEIGHT
If greater than 0, GL_PACK_IMAGE_HEIGHT defines the number of pixels in an image three-dimensional texture volume, where “image” is defined by all pixels sharing the same third dimension index. If the first pixel of a row is placed at location p in memory, then the location of the first pixel of the next row is obtained by skipping
components or indices, where n is the number of components or indices in a pixel, l is the number of pixels in a row (GL_PACK_ROW_LENGTH if it is greater than 0, the width argument to glTexImage3d otherwise), h is the number of rows in a pixel image (GL_PACK_IMAGE_HEIGHT if it is greater than 0, the height argument to the glTexImage3D routine otherwise), a is the value of GL_PACK_ALIGNMENT, and s is the size, in bytes, of a single component (if a<s, then it is as if a = s).
The word component in this description refers to the nonindex values red, green, blue, alpha, and depth. Storage format GL_RGB, for example, has three components per pixel: first red, then green, and finally blue.
GL_PACK_SKIP_PIXELS, GL_PACK_SKIP_ROWS, and GL_PACK_SKIP_IMAGES
These values are provided as a convenience to the programmer; they provide no functionality that cannot be duplicated simply by incrementing the pointer passed to glReadPixels. Setting GL_PACK_SKIP_PIXELS to i is equivalent to incrementing the pointer by in components or indices, where n is the number of components or indices in each pixel. Setting GL_PACK_SKIP_ROWS to j is equivalent to incrementing the pointer by jm components or indices, where m is the number of components or indices per row, as just computed in the GL_PACK_ROW_LENGTH section. Setting GL_PACK_SKIP_IMAGES to k is equivalent to incrementing the pointer by kp, where p is the number of components or indices per image, as computed in the GL_PACK_IMAGE_HEIGHT section.
GL_PACK_ALIGNMENT
Specifies the alignment requirements for the start of each pixel row in memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to even-numbered bytes), 4 (word-alignment), and 8 (rows start on double-word boundaries).
The other six of the twelve storage parameters affect how pixel data is read from client memory. These values are significant for glDrawPixels, glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D, glBitmap, and glPolygonStipple.
Additionally, if the ARB_imaging extension is supported, glColorTable, glColorSubTable, glConvolutionFilter1D, glConvolutionFilter2D, and glSeparableFilter2D. They are as follows:
GL_UNPACK_SWAP_BYTES
If true, byte ordering for multibyte color components, depth components, color indices, or stencil indices is reversed. That is, if a four-byte component consists of bytes b0, b1, b2, b3, it is taken from memory as b3, b2, b1, b0 if GL_UNPACK_SWAP_BYTES is true. GL_UNPACK_SWAP_BYTES has no effect on the memory order of components within a pixel, only on the order of bytes within components or indices. For example, the three components of a GL_RGB format pixel are always stored with red first, green second, and blue third, regardless of the value of GL_UNPACK_SWAP_BYTES.
GL_UNPACK_LSB_FIRST
If true, bits are ordered within a byte from least significant to most significant; otherwise, the first bit in each byte is the most significant one. This is relevant only for bitmap data.
GL_UNPACK_ROW_LENGTH
If greater than 0, GL_UNPACK_ROW_LENGTH defines the number of pixels in a row. If the first pixel of a row is placed at location p in memory, then the location of the first pixel of the next row is obtained by skipping
components or indices, where n is the number of components or indices in a pixel, l is the number of pixels in a row (GL_UNPACK_ROW_LENGTH if it is greater than 0, the width argument to the pixel routine otherwise), a is the value of GL_UNPACK_ALIGNMENT, and s is the size, in bytes, of a single component (if a<s, then it is as if a = s). In the case of 1-bit values, the location of the next row is obtained by skipping
components or indices.
The word component in this description refers to the nonindex values red, green, blue, alpha, and depth. Storage format GL_RGB, for example, has three components per pixel: first red, then green, and finally blue.
GL_UNPACK_IMAGE_HEIGHT
If greater than 0, GL_UNPACK_IMAGE_HEIGHT defines the number of pixels in an image of a three-dimensional texture volume. Where “image” is defined by all pixel sharing the same third dimension index. If the first pixel of a row is placed at location p in memory, then the location of the first pixel of the next row is obtained by skipping
components or indices, where n is the number of components or indices in a pixel, l is the number of pixels in a row (GL_UNPACK_ROW_LENGTH if it is greater than 0, the width argument to glTexImage3D otherwise), h is the number of rows in an image (GL_UNPACK_IMAGE_HEIGHT if it is greater than 0, the height argument to glTexImage3D otherwise), a is the value of GL_UNPACK_ALIGNMENT, and s is the size, in bytes, of a single component (if a<s, then it is as if a = s).
The word component in this description refers to the nonindex values red, green, blue, alpha, and depth. Storage format GL_RGB, for example, has three components per pixel: first red, then green, and finally blue.
GL_UNPACK_SKIP_PIXELS and GL_UNPACK_SKIP_ROWS
These values are provided as a convenience to the programmer; they provide no functionality that cannot be duplicated by incrementing the pointer passed to glDrawPixels, glTexImage1D, glTexImage2D, glTexSubImage1D, glTexSubImage2D, glBitmap, or glPolygonStipple. Setting GL_UNPACK_SKIP_PIXELS to i is equivalent to incrementing the pointer by in components or indices, where n is the number of components or indices in each pixel. Setting GL_UNPACK_SKIP_ROWS to j is equivalent to incrementing the pointer by jk components or indices, where k is the number of components or indices per row, as just computed in the GL_UNPACK_ROW_LENGTH section.
GL_UNPACK_ALIGNMENT
Specifies the alignment requirements for the start of each pixel row in memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to even-numbered bytes), 4 (word-alignment), and 8 (rows start on double-word boundaries).
The following table gives the type, initial value, and range of valid values for each storage parameter that can be set with glPixelStore.
glPixelStoref can be used to set any pixel store parameter. If the parameter type is boolean, then if param is 0, the parameter is false; otherwise it is set to true. If pname is a integer type parameter, param is rounded to the nearest integer.
Likewise, glPixelStorei can also be used to set any of the pixel store parameters. Boolean parameters are set to false if param is 0 and true otherwise.
Notes
The pixel storage modes in effect when glDrawPixels, glReadPixels, glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D, glBitmap, or glPolygonStipple is placed in a display list control the interpretation of memory data. Likewise, if the ARB_imaging extension is supported, the pixel storage modes in effect when glColorTable, glColorSubTable, glConvolutionFilter1D, glConvolutionFilter2D, of glSeparableFilter2D is placed in a display list control the interpretation of memory data. The pixel storage modes in effect when a display list is executed are not significant.
Pixel storage modes are client state and must be pushed and restored using glPushClientAttrib and glPopClientAttrib.
Errors
GL_INVALID_ENUM is generated if pname is not an accepted value.
GL_INVALID_VALUE is generated if a negative row length, pixel skip, or row skip value is specified, or if alignment is specified as other than 1, 2, 4, or 8.
GL_INVALID_OPERATION is generated if glPixelStore is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_PACK_SWAP_BYTES
glGet with argument GL_PACK_LSB_FIRST
glGet with argument GL_PACK_ROW_LENGTH
glGet with argument GL_PACK_IMAGE_HEIGHT
glGet with argument GL_PACK_SKIP_ROWS
glGet with argument GL_PACK_SKIP_PIXELS
glGet with argument GL_PACK_SKIP_IMAGES
glGet with argument GL_PACK_ALIGNMENT
glGet with argument GL_UNPACK_SWAP_BYTES
glGet with argument GL_UNPACK_LSB_FIRST
glGet with argument GL_UNPACK_ROW_LENGTH
glGet with argument GL_UNPACK_IMAGE_HEIGHT
glGet with argument GL_UNPACK_SKIP_ROWS
glGet with argument GL_UNPACK_SKIP_PIXELS
glGet with argument GL_UNPACK_SKIP_IMAGES
glGet with argument GL_UNPACK_ALIGNMENT
See Also
glBitmap, glColorTable, glColorSubTable, glConvolutionFilter1D, glConvolutionFilter2D, glSeparableFilter2D, glDrawPixels, glHistogram, glMinmax, glPixelMap, glPixelTransfer, glPixelZoom, glPolygonStipple, glPushClientAttrib, glReadPixels, glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D
glPixelTransfer
Set pixel transfer modes
C Specification
void glPixelTransferf(GLenum pname,
GLfloat param);
void glPixelTransferi(GLenum pname,
GLint param);
Parameters
Description
glPixelTransfer sets pixel transfer modes that affect the operation of subsequent glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glReadPixels, glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, and glTexSubImage3D commands. Additionally, if the ARB_imaging subset is supported, the routines glColorTable, glColorSubTable, glConvolutionFilter1D, glConvolutionFilter2D, glHistogram, glMinmax, and glSeparableFilter2D are also affected. The algorithms that are specified by pixel transfer modes operate on pixels after they are read from the frame buffer (glCopyPixelsglCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, and glReadPixels), or unpacked from client memory (glDrawPixels, glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, and glTexSubImage3D). Pixel transfer operations happen in the same order, and in the same manner, regardless of the command that resulted in the pixel operation. Pixel storage modes (see glPixelStore) control the unpacking of pixels being read from client memory and the packing of pixels being written back into client memory.
Pixel transfer operations handle four fundamental pixel types: color, color index, depth, and stencil. Color pixels consist of four floating-point values with unspecified mantissa and exponent sizes, scaled such that 0 represents zero intensity and 1 represents full intensity. Color indices comprise a single fixed-point value, with unspecified precision to the right of the binary point. Depth pixels comprise a single floating-point value, with unspecified mantissa and exponent sizes, scaled such that 0.0 represents the minimum depth buffer value, and 1.0 represents the maximum depth buffer value. Finally, stencil pixels comprise a single fixed-point value, with unspecified precision to the right of the binary point.
The pixel transfer operations performed on the four basic pixel types are as follows:
Color
Each of the four color components is multiplied by a scale factor, then added to a bias factor. That is, the red component is multiplied by GL_RED_SCALE, then added to GL_RED_BIAS; the green component is multiplied by GL_GREEN_SCALE, then added to GL_GREEN_BIAS; the blue component is multiplied by GL_BLUE_SCALE, then added to GL_BLUE_BIAS; and the alpha component is multiplied by GL_ALPHA_SCALE, then added to GL_ALPHA_BIAS. After all four color components are scaled and biased, each is clamped to the range [0,1]. All color, scale, and bias values are specified with glPixelTransfer.
If GL_MAP_COLOR is true, each color component is scaled by the size of the corresponding color-to-color map, then replaced by the contents of that map indexed by the scaled component. That is, the red component is scaled by GL_PIXEL_MAP_R_TO_R_SIZE, then replaced by the contents of GL_PIXEL_MAP_R_TO_R indexed by itself. The green component is scaled by GL_PIXEL_MAP_G_TO_G_SIZE, then replaced by the contents of GL_PIXEL_MAP_G_TO_G indexed by itself. The blue component is scaled by GL_PIXEL_MAP_B_TO_B_SIZE, then replaced by the contents of GL_PIXEL_MAP_B_TO_B indexed by itself. And the alpha component is scaled by GL_PIXEL_MAP_A_TO_A_SIZE, then replaced by the contents of GL_PIXEL_MAP_A_TO_A indexed by itself. All components taken from the maps are then clamped to the range [0,1]. GL_MAP_COLOR is specified with glPixelTransfer. The contents of the various maps are specified with glPixelMap.
If the ARB_imaging extension is supported, each of the four color components may be scaled and biased after transformation by the color matrix. That is, the red component is multiplied by GL_POST_COLOR_MATRIX_RED_SCALE, then added to GL_POST_COLOR_MATRIX_RED_BIAS; the green component is multiplied by GL_POST_COLOR_MATRIX_GREEN_SCALE, then added to GL_POST_COLOR_MATRIX_GREEN_BIAS; the blue component is multiplied by GL_POST_COLOR_MATRIX_BLUE_SCALE, then added to GL_POST_COLOR_MATRIX_BLUE_BIAS; and the alpha component is multiplied by GL_POST_COLOR_MATRIX_ALPHA_SCALE, then added to GL_POST_COLOR_MATRIX_ALPHA_BIAS. After all four color components are scaled and biased, each is clamped to the range [0,1].
Similarly, if the ARB_imaging extension is supported, each of the four color components may be scaled and biased after processing by the enabled convolution filter. That is, the red component is multiplied by GL_POST_CONVOLUTION_RED_SCALE, then added to GL_POST_CONVOLUTION_RED_BIAS; the green component is multiplied by GL_POST_CONVOLUTION_GREEN_SCALE, then added to GL_POST_CONVOLUTION_GREEN_BIAS; the blue component is multiplied by GL_POST_CONVOLUTION_BLUE_SCALE, then added to GL_POST_CONVOLUTION_BLUE_BIAS; and the alpha component is multiplied by GL_POST_CONVOLUTION_ALPHA_SCALE, then added to GL_POST_CONVOLUTION_ALPHA_BIAS. After all four color components are scaled and biased, each is clamped to the range [0,1].
Color index
Each color index is shifted left by GL_INDEX_SHIFT bits; any bits beyond the number of fraction bits carried by the fixed-point index are filled with zeros. If GL_INDEX_SHIFT is negative, the shift is to the right, again zero filled. Then GL_INDEX_OFFSET is added to the index. GL_INDEX_SHIFT and GL_INDEX_OFFSET are specified with glPixelTransfer.
From this point, operation diverges depending on the required format of the resulting pixels. If the resulting pixels are to be written to a color index buffer, or if they are being read back to client memory in GL_COLOR_INDEX format, the pixels continue to be treated as indices. If GL_MAP_COLOR is true, each index is masked by 2n - 1, where n is GL_PIXEL_MAP_I_TO_I_SIZE, then replaced by the contents of GL_PIXEL_MAP_I_TO_I indexed by the masked value. GL_MAP_COLOR is specified with glPixelTransfer. The contents of the index map is specified with glPixelMap.
If the resulting pixels are to be written to an RGBA color buffer, or if they are read back to client memory in a format other than GL_COLOR_INDEX, the pixels are converted from indices to colors by referencing the four maps 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. Before being dereferenced, the index is masked by 2n - 1, where n is GL_PIXEL_MAP_I_TO_R_SIZE for the red map, GL_PIXEL_MAP_I_TO_G_SIZE for the green map, GL_PIXEL_MAP_I_TO_B_SIZE for the blue map, and GL_PIXEL_MAP_I_TO_A_SIZE for the alpha map. All components taken from the maps are then clamped to the range [0,1]. The contents of the four maps is specified with glPixelMap.
Depth
Each depth value is multiplied by GL_DEPTH_SCALE, added to GL_DEPTH_BIAS, then clamped to the range [0,1].
Stencil
Each index is shifted GL_INDEX_SHIFT bits just as a color index is, then added to GL_INDEX_OFFSET. If GL_MAP_STENCIL is true, each index is masked by 2n ? 1, where n is GL_PIXEL_MAP_S_TO_S_SIZE, then replaced by the contents of GL_PIXEL_MAP_S_TO_S indexed by the masked value.
The following table gives the type, initial value, and range of valid values for each of the pixel transfer parameters that are set with glPixelTransfer.
glPixelTransferf can be used to set any pixel transfer parameter. If the parameter type is boolean, 0 implies false and any other value implies true. If pname is an integer parameter, param is rounded to the nearest integer.
Likewise, glPixelTransferi can be used to set any of the pixel transfer parameters. Boolean parameters are set to false if param is 0 and to true otherwise. param is converted to floating point before being assigned to real-valued parameters.
Notes
If a glColorTable, glColorSubTable, glConvolutionFilter1D, glConvolutionFilter2D, glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glReadPixels, glSeparableFilter2D, glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, or glTexSubImage3D command is placed in a display list (see glNewList and glCallList), the pixel transfer mode settings in effect when the display list is executed are the ones that are used. They may be different from the settings when the command was compiled into the display list.
Errors
GL_INVALID_ENUM is generated if pname is not an accepted value.
GL_INVALID_OPERATION is generated if glPixelTransfer is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_MAP_COLOR
glGet with argument GL_MAP_STENCIL
glGet with argument GL_INDEX_SHIFT
glGet with argument GL_INDEX_OFFSET
glGet with argument GL_RED_SCALE
glGet with argument GL_RED_BIAS
glGet with argument GL_GREEN_SCALE
glGet with argument GL_GREEN_BIAS
glGet with argument GL_BLUE_SCALE
glGet with argument GL_BLUE_BIAS
glGet with argument GL_ALPHA_SCALE
glGet with argument GL_ALPHA_BIAS
glGet with argument GL_DEPTH_SCALE
glGet with argument GL_DEPTH_BIAS
glGet with argument GL_POST_COLOR_MATRIX_RED_SCALE
glGet with argument GL_POST_COLOR_MATRIX_RED_BIAS
glGet with argument GL_POST_COLOR_MATRIX_GREEN_SCALE
glGet with argument GL_POST_COLOR_MATRIX_GREEN_BIAS
glGet with argument GL_POST_COLOR_MATRIX_BLUE_SCALE
glGet with argument GL_POST_COLOR_MATRIX_BLUE_BIAS
glGet with argument GL_POST_COLOR_MATRIX_ALPHA_SCALE
glGet with argument GL_POST_COLOR_MATRIX_ALPHA_BIAS
glGet with argument GL_POST_CONVOLUTION_RED_SCALE
glGet with argument GL_POST_CONVOLUTION_RED_BIAS
glGet with argument GL_POST_CONVOLUTION_GREEN_SCALE
glGet with argument GL_POST_CONVOLUTION_GREEN_BIAS
glGet with argument GL_POST_CONVOLUTION_BLUE_SCALE
glGet with argument GL_POST_CONVOLUTION_BLUE_BIAS
glGet with argument GL_POST_CONVOLUTION_ALPHA_SCALE
glGet with argument GL_POST_CONVOLUTION_ALPHA_BIAS
glCallList, glColorTable, glColorSubTable, glConvolutionFilter1D, glConvolutionFilter2D, glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glNewList, glPixelMap, glPixelStore, glPixelZoom, glReadPixels, glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D
glPixelZoom
Specify the pixel zoom factors
C Specification
void glPixelZoom(GLfloat xfactor,
GLfloat yfactor);
Parameters
Description
glPixelZoom specifies values for the x and y zoom factors. During the execution of glDrawPixels or glCopyPixels, if (xr, yr) is the current raster position, and a given element is in the mth row and nth column of the pixel rectangle, then pixels whose centers are in the rectangle with corners at
(xr + n · xfactor, yr + m · yfactor)
(xr + (n + 1) · xfactor, yr + (m + 1) · yfactor)
are candidates for replacement. Any pixel whose center lies on the bottom or left edge of this rectangular region is also modified.
Pixel zoom factors are not limited to positive values. Negative zoom factors reflect the resulting image about the current raster position.
Errors
GL_INVALID_OPERATION is generated if glPixelZoom is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_ZOOM_X
glGet with argument GL_ZOOM_Y
See Also
glCopyPixels, glDrawPixels
glPointParameter
Specify point parameters
C Specification
void glPointParameterf(GLenum pname,
GLfloat param);
void glPointParameteri(GLenum pname,
GLint param);
C Specification
void glPointParameterfv(GLenum pname,
const GLfloat * params);
void glPointParameteriv(GLenum pname,
const GLint * params);
Parameters
Description
The following values are accepted for pname:
GL_POINT_SIZE_MIN
params is a single floating-point value that specifies the minimum point size. The default value is 0.0.
GL_POINT_SIZE_MAX
params is a single floating-point value that specifies the maximum point size. The default value is 1.0.
GL_POINT_FADE_THRESHOLD_SIZE
params is a single floating-point value that specifies the threshold value to which point sizes are clamped if they exceed the specified value. The default value is 1.0.
GL_POINT_DISTANCE_ATTENUATION
params is an array of three floating-point values that specify the coefficients used for scaling the computed point size. The default values are (1,0,0).
GL_POINT_SPRITE_COORD_ORIGIN
params is a single enum specifying the point sprite texture coordinate origin, either GL_LOWER_LEFT or GL_UPPER_LEFT. The default value is GL_UPPER_LEFT.
Notes
glPointParameter is available only if the GL version is 1.4 or greater.
GL_POINT_SPRITE_COORD_ORIGIN is available only if the GL version is 2.0 or greater.
Errors
GL_INVALID_VALUE is generated If the value specified for GL_POINT_SIZE_MIN, GL_POINT_SIZE_MAX, or GL_POINT_FADE_THRESHOLD_SIZE is less than zero.
GL_INVALID_ENUM is generated If the value specified for GL_POINT_SPRITE_COORD_ORIGIN is not GL_LOWER_LEFT or GL_UPPER_LEFT.
If the value for GL_POINT_SIZE_MIN is greater than GL_POINT_SIZE_MAX, the point size after clamping is undefined, but no error is generated.
glGet with argument GL_POINT_SIZE_MIN
glGet with argument GL_POINT_SIZE_MAX
glGet with argument GL_POINT_FADE_THRESHOLD_SIZE
glGet with argument GL_POINT_DISTANCE_ATTENUATION
glGet with argument GL_POINT_SPRITE_COORD_ORIGIN
See Also
glPointSize
glPointSize
Specify the diameter of rasterized points
C Specification
void glPointSize(GLfloat size);
Parameters
Description
glPointSize specifies the rasterized diameter of both aliased and antialiased points. Using a point size other than 1 has different effects, depending on whether point antialiasing is enabled. To enable and disable point antialiasing, call glEnable and glDisable with argument GL_POINT_SMOOTH. Point antialiasing is initially disabled.
The specified point size is multiplied with a distance attenuation factor and clamped to the specified point size range, and further clamped to the implementation-dependent point size range to produce the derived point size using
where d is the eye-coordinate distance from the eye to the vertex, and a, b, and c are the distance attenuation coefficients (see glPointParameter).
If multisampling is disabled, the computed point size is used as the point’s width.
If multisampling is enabled, the point may be faded by modifying the point alpha value (see glSampleCoverage) instead of allowing the point width to go below a given threshold (see glPointParameter). In this case, the width is further modified in the following manner:
The point alpha value is modified by computing:
If point antialiasing is disabled, the actual size is determined by rounding the supplied size to the nearest integer. (If the rounding results in the value 0, it is as if the point size were 1.) If the rounded size is odd, then the center point (x, y) of the pixel fragment that represents the point is computed as
(
xw
+ .5, yw + .5)
where w subscripts indicate window coordinates. All pixels that lie within the square grid of the rounded size centered at (x, y) make up the fragment. If the size is even, the center point is
(xw + .5, yw + .5)
and the rasterized fragment’s centers are the half-integer window coordinates within the square of the rounded size centered at (x,y). All pixel fragments produced in rasterizing a nonantialiased point are assigned the same associated data, that of the vertex corresponding to the point.
If antialiasing is enabled, then point rasterization produces a fragment for each pixel square that intersects the region lying within the circle having diameter equal to the current point size and centered at the point’s (xw,yw). The coverage value for each fragment is the window coordinate area of the intersection of the circular region with the corresponding pixel square. This value is saved and used in the final rasterization step. The data associated with each fragment is the data associated with the point being rasterized.
Not all sizes are supported when point antialiasing is enabled. If an unsupported size is requested, the nearest supported size is used. Only size 1 is guaranteed to be supported; others depend on the implementation. To query the range of supported sizes and the size difference between supported sizes within the range, call glGet with arguments GL_SMOOTH_POINT_SIZE_RANGE and GL_SMOOTH_POINT_SIZE_GRANULARITY. For aliased points, query the supported ranges and granularity with glGet with arguments GL_ALIASED_POINT_SIZE_RANGE.
Notes
The point size specified by glPointSize is always returned when GL_POINT_SIZE is queried. Clamping and rounding for aliased and antialiased points have no effect on the specified value.
A non-antialiased point size may be clamped to an implementation-dependent maximum. Although this maximum cannot be queried, it must be no less than the maximum value for antialiased points, rounded to the nearest integer value.
GL_POINT_SIZE_RANGE and GL_POINT_SIZE_GRANULARITY are deprecated in GL versions 1.2 and greater. Their functionality has been replaced by GL_SMOOTH_POINT_SIZE_RANGE and GL_SMOOTH_POINT_SIZE_GRANULARITY.
Errors
GL_INVALID_VALUE is generated if size is less than or equal to 0.
GL_INVALID_OPERATION is generated if glPointSize is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_ALIASED_POINT_SIZE_RANGE
glGet with argument GL_POINT_SIZE
glGet with argument GL_POINT_SIZE_MIN
glGet with argument GL_POINT_SIZE_MAX
glGet with argument GL_POINT_FADE_THRESHOLD_SIZE
glGet with argument GL_POINT_DISTANCE_ATTENUATION
glGet with argument GL_SMOOTH_POINT_SIZE_RANGE
glGet with argument GL_SMOOTH_POINT_SIZE_GRANULARITY
glIsEnabled with argument GL_POINT_SMOOTH
See Also
glEnable, glPointParameter
glPolygonMode
Select a polygon rasterization mode
C Specification
void glPolygonMode(GLenum face, GLenum mode);
Description
glPolygonMode controls the interpretation of polygons for rasterization. face describes which polygons mode applies to: front-facing polygons (GL_FRONT), back-facing polygons (GL_BACK), or both (GL_FRONT_AND_BACK). The polygon mode affects only the final rasterization of polygons. In particular, a polygon’s vertices are lit and the polygon is clipped and possibly culled before these modes are applied.
Three modes are defined and can be specified in mode:
GL_POINT
Polygon vertices that are marked as the start of a boundary edge are drawn as points. Point attributes such as GL_POINT_SIZE and GL_POINT_SMOOTH control the rasterization of the points. Polygon rasterization attributes other than GL_POLYGON_MODE have no effect.
GL_LINE
Boundary edges of the polygon are drawn as line segments. They are treated as connected line segments for line stippling; the line stipple counter and pattern are not reset between segments (see glLineStipple). Line attributes such as GL_LINE_WIDTH and GL_LINE_SMOOTH control the rasterization of the lines. Polygon rasterization attributes other than GL_POLYGON_MODE have no effect.
GL_FILL
The interior of the polygon is filled. Polygon attributes such as GL_POLYGON_STIPPLE and GL_POLYGON_SMOOTH control the rasterization of the polygon.
Examples
To draw a surface with filled back-facing polygons and outlined front-facing polygons, call glPolygonMode(GL_FRONT,GL_LINE);
Notes
Vertices are marked as boundary or nonboundary with an edge flag. Edge flags are generated internally by the GL when it decomposes polygons; they can be set explicitly using glEdgeFlag.
Errors
GL_INVALID_ENUM is generated if either face or mode is not an accepted value.
GL_INVALID_OPERATION is generated if glPolygonMode is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_POLYGON_MODE
See Also
glBegin, glEdgeFlag, glLineStipple, glLineWidth, glPointSize, glPolygonStipple
glPolygonOffset
Set the scale and units used to calculate depth values
C Specification
void glPolygonOffset(GLfloat factor,
GLfloat units);
Description
When GL_POLYGON_OFFSET_FILL, GL_POLYGON_OFFSET_LINE, or GL_POLYGON_OFFSET_POINT is enabled, each fragment’s depth value will be offset after it is interpolated from the depth values of the appropriate vertices. The value of the offset is factor × DZ + r × units, where DZ is a measurement of the change in depth relative to the screen area of the polygon, and r is the smallest value that is guaranteed to produce a resolvable offset for a given implementation. The offset is added before the depth test is performed and before the value is written into the depth buffer.
glPolygonOffset is useful for rendering hidden-line images, for applying decals to surfaces, and for rendering solids with highlighted edges.
Notes
glPolygonOffset is available only if the GL version is 1.1 or greater.
glPolygonOffset has no effect on depth coordinates placed in the feedback buffer.
glPolygonOffset has no effect on selection.
Errors
GL_INVALID_OPERATION is generated if glPolygonOffset is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glIsEnabled with argument GL_POLYGON_OFFSET_FILL, GL_POLYGON_OFFSET_LINE, or GL_POLYGON_OFFSET_POINT.
glGet with argument GL_POLYGON_OFFSET_FACTOR or GL_POLYGON_OFFSET_UNITS.
See Also
glDepthFunc, glEnable, glGet, glIsEnabled
glPolygonStipple
Set the polygon stippling pattern
C Specification
void glPolygonStipple(const GLubyte * pattern);
Parameters
Description
Polygon stippling, like line stippling (see glLineStipple), masks out certain fragments produced by rasterization, creating a pattern. Stippling is independent of polygon antialiasing.
pattern is a pointer to a 32 × 32 stipple pattern that is stored in memory just like the pixel data supplied to a glDrawPixels call with height and width both equal to 32, a pixel format of GL_COLOR_INDEX, and data type of GL_BITMAP. That is, the stipple pattern is represented as a 32 × 32 array of 1-bit color indices packed in unsigned bytes. glPixelStore parameters like GL_UNPACK_SWAP_BYTES and GL_UNPACK_LSB_FIRST affect the assembling of the bits into a stipple pattern. Pixel transfer operations (shift, offset, pixel map) are not applied to the stipple image, however.
If a nonzero named buffer object is bound to the GL_PIXEL_UNPACK_BUFFER target (see glBindBuffer) while a stipple pattern is specified, pattern is treated as a byte offset into the buffer object’s data store.
To enable and disable polygon stippling, call glEnable and glDisable with argument GL_POLYGON_STIPPLE. Polygon stippling is initially disabled. If it’s enabled, a rasterized polygon fragment with window coordinates xw and yw is sent to the next stage of the GL if and only if the (xw%32)th bit in the (yw%32)th row of the stipple pattern is 1 (one). When polygon stippling is disabled, it is as if the stipple pattern consists of all 1’s.
Errors
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 glPolygonStipple is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetPolygonStipple
glIsEnabled with argument GL_POLYGON_STIPPLE
glGet with argument GL_PIXEL_UNPACK_BUFFER_BINDING
See Also
glDrawPixels, glLineStipple, glPixelStore, glPixelTransfer
glPrioritizeTextures
Set texture residence priority
C Specification
void glPrioritizeTextures(GLsizei n,
const GLuint * textures,
const GLclampf * priorities);
Parameters
Description
glPrioritizeTextures assigns the n texture priorities given in priorities to the n textures named in textures.
The GL establishes a “working set” of textures that are resident in texture memory. These textures may be bound to a texture target much more efficiently than textures that are not resident. By specifying a priority for each texture, glPrioritizeTextures allows applications to guide the GL implementation in determining which textures should be resident.
The priorities given in priorities are clamped to the range [0,1] before they are assigned. 0 indicates the lowest priority; textures with priority 0 are least likely to be resident. 1 indicates the highest priority; textures with priority 1 are most likely to be resident. However, textures are not guaranteed to be resident until they are used.
glPrioritizeTextures silently ignores attempts to prioritize texture 0 or any texture name that does not correspond to an existing texture.
glPrioritizeTextures does not require that any of the textures named by textures be bound to a texture target. glTexParameter may also be used to set a texture’s priority, but only if the texture is currently bound. This is the only way to set the priority of a default texture.
Notes
glPrioritizeTextures is available only if the GL version is 1.1 or greater.
Errors
GL_INVALID_VALUE is generated if n is negative.
GL_INVALID_OPERATION is generated if glPrioritizeTextures is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetTexParameter with parameter name GL_TEXTURE_PRIORITY retrieves the priority of a currently bound texture.
See Also
glAreTexturesResident, glBindTexture, glCopyTexImage1D, glCopyTexImage2D, glTexImage1D, glTexImage2D, glTexImage3D, glTexParameter
glPushAttrib
Push and pop the server attribute stack
C Specification
void glPushAttrib(GLbitfield mask);
Parameters
C Specification
void glPopAttrib(void);
Description
glPushAttrib takes one argument, a mask that indicates which groups of state variables to save on the attribute stack. Symbolic constants are used to set bits in the mask. mask is typically constructed by specifying the bitwise-or of several of these constants together. The special mask GL_ALL_ATTRIB_BITS can be used to save all stackable states.
The symbolic mask constants and their associated GL state are as follows (the second column lists which attributes are saved):
glPopAttrib restores the values of the state variables saved with the last glPushAttrib command. Those not saved are left unchanged.
It is an error to push attributes onto a full stack or to pop attributes off an empty stack. In either case, the error flag is set and no other change is made to GL state.
Initially, the attribute stack is empty.
Notes
Not all values for GL state can be saved on the attribute stack. For example, render mode state, and select and feedback state cannot be saved. Client state must be saved with glPushClientAttrib.
The depth of the attribute stack depends on the implementation, but it must be at least 16.
For OpenGL versions 1.3 and greater, or when the ARB_multitexture extension is supported, pushing and popping texture state applies to all supported texture units.
Errors
GL_STACK_OVERFLOW is generated if glPushAttrib is called while the attribute stack is full.
GL_STACK_UNDERFLOW is generated if glPopAttrib is called while the attribute stack is empty.
GL_INVALID_OPERATION is generated if glPushAttrib or glPopAttrib is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_ATTRIB_STACK_DEPTH
glGet with argument GL_MAX_ATTRIB_STACK_DEPTH
See Also
glGet, glGetClipPlane, glGetError, glGetLight, glGetMap, glGetMaterial, glGetPixelMap, glGetPolygonStipple, glGetString, glGetTexEnv, glGetTexGen, glGetTexImage, glGetTexLevelParameter, glGetTexParameter, glIsEnabled, glPushClientAttrib
glPushClientAttrib
Push and pop the client attribute stack
C Specification
void glPushClientAttrib(GLbitfield mask);
Parameters
C Specification
void glPopClientAttrib(void);
Description
glPushClientAttrib takes one argument, a mask that indicates which groups of client-state variables to save on the client attribute stack. Symbolic constants are used to set bits in the mask. mask is typically constructed by specifying the bitwise-or of several of these constants together. The special mask GL_CLIENT_ALL_ATTRIB_BITS can be used to save all stackable client state.
The symbolic mask constants and their associated GL client state are as follows (the second column lists which attributes are saved):
GL_CLIENT_PIXEL_STORE_BIT Pixel storage modes GL_CLIENT_VERTEX_ARRAY_BIT Vertex arrays (and enables)
glPopClientAttrib restores the values of the client-state variables saved with the last glPushClientAttrib. Those not saved are left unchanged.
It is an error to push attributes onto a full client attribute stack or to pop attributes off an empty stack. In either case, the error flag is set, and no other change is made to GL state.
Initially, the client attribute stack is empty.
Notes
glPushClientAttrib is available only if the GL version is 1.1 or greater.
Not all values for GL client state can be saved on the attribute stack. For example, select and feedback state cannot be saved.
The depth of the attribute stack depends on the implementation, but it must be at least 16.
Use glPushAttrib and glPopAttrib to push and restore state that is kept on the server. Only pixel storage modes and vertex array state may be pushed and popped with glPushClientAttrib and glPopClientAttrib.
For OpenGL versions 1.3 and greater, or when the ARB_multitexture extension is supported, pushing and popping client vertex array state applies to all supported texture units, and the active client texture state.
Errors
GL_STACK_OVERFLOW is generated if glPushClientAttrib is called while the attribute stack is full.
GL_STACK_UNDERFLOW is generated if glPopClientAttrib is called while the attribute stack is empty.
Associated Gets
glGet with argument GL_ATTRIB_STACK_DEPTH
glGet with argument GL_MAX_CLIENT_ATTRIB_STACK_DEPTH
See Also
glColorPointer, glDisableClientState, glEdgeFlagPointer, glEnableClientState, glFogCoordPointer, glGet, glGetError, glIndexPointer, glNormalPointer, glNewList, glPixelStore, glPushAttrib, glTexCoordPointer, glVertexPointer
glPushMatrix
Push and pop the current matrix stack
C Specification
void glPushMatrix(void);
C Specification
void glPopMatrix(void);
Description
There is a stack of matrices for each of the matrix modes. In GL_MODELVIEW mode, the stack depth is at least 32. In the other modes, GL_COLOR, GL_PROJECTION, and GL_TEXTURE, the depth is at least 2. The current matrix in any mode is the matrix on the top of the stack for that mode.
glPushMatrix pushes the current matrix stack down by one, duplicating the current matrix. That is, after a glPushMatrix call, the matrix on top of the stack is identical to the one below it.
glPopMatrix pops the current matrix stack, replacing the current matrix with the one below it on the stack.
Initially, each of the stacks contains one matrix, an identity matrix.
It is an error to push a full matrix stack or to pop a matrix stack that contains only a single matrix. In either case, the error flag is set and no other change is made to GL state.
Errors
GL_STACK_OVERFLOW is generated if glPushMatrix is called while the current matrix stack is full.
GL_STACK_UNDERFLOW is generated if glPopMatrix is called while the current matrix stack contains only a single matrix.
GL_INVALID_OPERATION is generated if glPushMatrix or glPopMatrix 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
glGet with argument GL_COLOR_MATRIX_STACK_DEPTH
glGet with argument GL_MODELVIEW_STACK_DEPTH
glGet with argument GL_PROJECTION_STACK_DEPTH
glGet with argument GL_TEXTURE_STACK_DEPTH
glGet with argument GL_MAX_MODELVIEW_STACK_DEPTH
glGet with argument GL_MAX_PROJECTION_STACK_DEPTH
glGet with argument GL_MAX_TEXTURE_STACK_DEPTH
See Also
glFrustum, glLoadIdentity, glLoadMatrix, glLoadTransposeMatrix, glMatrixMode, glMultMatrix, glMultTransposeMatrix, glOrtho, glRotate, glScale, glTranslate, glViewport
glPushName
Push and pop the name stack
C Specification
void glPushName(GLuint name);
Parameters
C Specification
void glPopName(void);
Description
The name stack is used during selection mode to allow sets of rendering commands to be uniquely identified. It consists of an ordered set of unsigned integers and is initially empty.
glPushName causes name to be pushed onto the name stack. glPopName pops one name off the top of the stack.
The maximum name stack depth is implementation-dependent; call GL_MAX_NAME_STACK_DEPTH to find out the value for a particular implementation. It is an error to push a name onto a full stack or to pop a name off an empty stack. It is also an error to manipulate the name stack between the execution of glBegin and the corresponding execution of glEnd. In any of these cases, the error flag is set and no other change is made to GL state.
The name stack is always empty while the render mode is not GL_SELECT. Calls to glPushName or glPopName while the render mode is not GL_SELECT are ignored.
Errors
GL_STACK_OVERFLOW is generated if glPushName is called while the name stack is full.
GL_STACK_UNDERFLOW is generated if glPopName is called while the name stack is empty.
GL_INVALID_OPERATION is generated if glPushName or glPopName is executed between a call to glBegin and the corresponding call to glEnd.
Associated Gets
glGet with argument GL_NAME_STACK_DEPTH
glGet with argument GL_MAX_NAME_STACK_DEPTH
See Also
glInitNames, glLoadName, glRenderMode, glSelectBuffer
glRasterPos
Specify the raster position for pixel operations
C Specification
x, y, z, w
Specify the x, y, z, and w object coordinates (if present) for the raster position.
C Specification
void glRasterPos2sv(const GLshort * v);
void glRasterPos2iv(const GLint * v);
void glRasterPos2fv(const GLfloat * v);
void glRasterPos2dv(const GLdouble * v);
void glRasterPos3sv(const GLshort * v);
void glRasterPos3iv(const GLint * v);
void glRasterPos3fv(const GLfloat * v);
void glRasterPos3dv(const GLdouble * v);
void glRasterPos4sv(const GLshort * v);
void glRasterPos4iv(const GLint * v);
void glRasterPos4fv(const GLfloat * v);
void glRasterPos4dv(const GLdouble * v);
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.
The current raster position consists of three window coordinates (x, y, z), a clip coordinate value (w), an eye coordinate distance, a valid bit, and associated color data and texture coordinates. The w coordinate is a clip coordinate, because w is not projected to window coordinates. glRasterPos4 specifies object coordinates x, y, z, and w explicitly. glRasterPos3 specifies object coordinate x, y, and z explicitly, while w is implicitly set to 1. glRasterPos2 uses the argument values for x and y while implicitly setting z and w to 0 and 1.
The object coordinates presented by glRasterPos are treated just like those of a glVertex command: They are transformed by the current modelview and projection matrices and passed to the clipping stage. If the vertex is not culled, then it is projected and scaled to window coordinates, which become the new current raster position, and the GL_CURRENT_RASTER_POSITION_VALID flag is set. If the vertex is culled, then the valid bit is cleared and the current raster position and associated color and texture coordinates are undefined.
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). Finally, the distance from the origin of the eye coordinate system to the vertex as transformed by only the modelview matrix replaces GL_CURRENT_RASTER_DISTANCE.
Initially, the current raster position is (0, 0, 0, 1), the current raster distance is 0, the valid bit is set, the associated RGBA color is (1, 1, 1, 1), the associated color index is 1, and the associated texture coordinates are (0, 0, 0, 1). In RGBA mode, GL_CURRENT_RASTER_INDEX is always 1; in color index mode, the current raster RGBA color always maintains its initial value.
Notes
The raster position is modified by glRasterPos, glBitmap, and glWindowPos.
When the raster position coordinates are invalid, drawing commands that are based on the raster position are ignored (that is, they do not result in changes to GL state).
Calling glDrawElements or glDrawRangeElements may leave the current color or index indeterminate. If glRasterPos is executed while the current color or index is indeterminate, the current raster color or current raster index remains indeterminate.
To set a valid raster position outside the viewport, first set a valid raster position, then call glBitmap with NULL as the bitmap parameter.
When the ARB_imaging extension is supported, there are distinct raster texture coordinates for each texture unit. Each texture unit’s current raster texture coordinates are updated by glRasterPos.
Errors
GL_INVALID_OPERATION is generated if glRasterPos 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, glTexCoord, glTexGen, glVertex, glWindowPos
glReadBuffer
Select a color buffer source for pixels
C Specification
void glReadBuffer(GLenum mode);
Parameters
Description
glReadBuffer specifies a color buffer as the source for subsequent glReadPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, and glCopyPixels commands. mode accepts one of twelve or more predefined values. (GL_AUX0 through GL_AUX3 are always defined.) In a fully configured system, GL_FRONT, GL_LEFT, and GL_FRONT_LEFT all name the front left buffer, GL_FRONT_RIGHT and GL_RIGHT name the front right buffer, and GL_BACK_LEFT and GL_BACK name the back left buffer.
Nonstereo double-buffered configurations have only a front left and a back left buffer. Single-buffered configurations have a front left and a front right buffer if stereo, and only a front left buffer if nonstereo. It is an error to specify a nonexistent buffer to glReadBuffer.
mode is initially GL_FRONT in single-buffered configurations and GL_BACK in double-buffered configurations.
Errors
GL_INVALID_ENUM is generated if mode is not one of the twelve (or more) accepted values.
GL_INVALID_OPERATION is generated if mode specifies a buffer that does not exist.
GL_INVALID_OPERATION is generated if glReadBuffer is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_READ_BUFFER
See Also
glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawBuffer, glReadPixels
glReadPixels
Read a block of pixels from the frame buffer
C Specification
Parameters
Description
glReadPixels returns pixel data from the frame buffer, starting with the pixel whose lower-left corner is at location (x, y), into client memory starting at location data. Several parameters control the processing of the pixel data before it is placed into client memory. These parameters are set with three commands: glPixelStore, glPixelTransfer, and glPixelMap. This reference page describes the effects on glReadPixels of most, but not all of the parameters specified by these three commands.
If a nonzero named buffer object is bound to the GL_PIXEL_PACK_BUFFER target (see glBindBuffer) while a block of pixels is requested, data is treated as a byte offset into the buffer object’s data store rather than a pointer to client memory.
When the ARB_imaging extension is supported, the pixel data may be processed by additional operations including color table lookup, color matrix transformations, convolutions, histograms, and minimum and maximum pixel value computations.
glReadPixels returns values from each pixel with lower-left corner at (x + i,y + j) for 0<=i<width and 0<=j<height. This pixel is said to be the ith pixel in the jth row. Pixels are returned in row order from the lowest to the highest row, left to right in each row.
format specifies the format for the returned pixel values; accepted values are:
GL_COLOR_INDEX
Color indices are read from the color buffer selected by glReadBuffer. Each index is converted to fixed point, shifted left or right depending on the value and sign of GL_INDEX_SHIFT, and added to GL_INDEX_OFFSET. If GL_MAP_COLOR is GL_TRUE, indices are replaced by their mappings in the table GL_PIXEL_MAP_I_TO_I.
GL_STENCIL_INDEX
Stencil values are read from the stencil buffer. Each index is converted to fixed point, shifted left or right depending on the value and sign of GL_INDEX_SHIFT, and added to GL_INDEX_OFFSET. If GL_MAP_STENCIL is GL_TRUE, indices are replaced by their mappings in the table GL_PIXEL_MAP_S_TO_S.
GL_DEPTH_COMPONENT
Depth values are read from the depth buffer. Each component is converted to floating point such that the minimum depth value maps to 0 and the maximum value maps to 1. Each component is then multiplied by GL_DEPTH_SCALE, added to GL_DEPTH_BIAS, and finally clamped to the range [0,1].
GL_RED
GL_GREEN
GL_BLUE
GL_RGB
GL_BGR
GL_RGBA
GL_BGRA
GL_LUMINANCE
GL_LUMINANCE_ALPHA
Processing differs depending on whether color buffers store color indices or RGBA color components. If color indices are stored, they are read from the color buffer selected by glReadBuffer. Each index is converted to fixed point, shifted left or right depending on the value and sign of GL_INDEX_SHIFT, and added to GL_INDEX_OFFSET. Indices are then replaced by the red, green, blue, and alpha values obtained by indexing the tables 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. Each table must be of size 2n, but n may be different for different tables. Before an index is used to look up a value in a table of size 2n, it must be masked against 2n – 1.
If RGBA color components are stored in the color buffers, they are read from the color buffer selected by glReadBuffer. Each color component is converted to floating point such that zero intensity maps to 0.0 and full intensity maps to 1.0. Each component is then multiplied by GL_c_SCALE and added to GL_c_BIAS, where c is RED, GREEN, BLUE, or ALPHA. Finally, if GL_MAP_COLOR is GL_TRUE, each component is clamped to the range [0,1], scaled to the size of its corresponding table, and is then replaced by its mapping in the table GL_PIXEL_MAP_c_TO_c, where c is R, G, B, or A.
Unneeded data is then discarded. For example, GL_RED discards the green, blue, and alpha components, while GL_RGB discards only the alpha component. GL_LUMINANCE computes a single-component value as the sum of the red, green, and blue components, and GL_LUMINANCE_ALPHA does the same, while keeping alpha as a second value. The final values are clamped to the range [0,1].
The shift, scale, bias, and lookup factors just described are all specified by glPixelTransfer. The lookup table contents themselves are specified by glPixelMap.
Finally, the indices or components are converted to the proper format, as specified by type. If format is GL_COLOR_INDEX or GL_STENCIL_INDEX and type is not GL_FLOAT, each index is masked with the mask value given in the following table. If type is GL_FLOAT, then each integer index is converted to single-precision floating-point format.
If format is GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_BGR, GL_RGBA, GL_BGRA, GL_LUMINANCE, or GL_LUMINANCE_ALPHA and type is not GL_FLOAT, each component is multiplied by the multiplier shown in the following table. If type is GL_FLOAT, then each component is passed as is (or converted to the client’s single-precision floating-point format if it is different from the one used by the GL).
Return values are placed in memory as follows. If format is GL_COLOR_INDEX, GL_STENCIL_INDEX, GL_DEPTH_COMPONENT, GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, or GL_LUMINANCE, a single value is returned and the data for the ith pixel in the jth row is placed in location (j) width + i. GL_RGB and GL_BGR return three values, GL_RGBA and GL_BGRA return four values, and GL_LUMINANCE_ALPHA returns two values for each pixel, with all values corresponding to a single pixel occupying contiguous space in data. Storage parameters set by glPixelStore, such as GL_PACK_LSB_FIRST and GL_PACK_SWAP_BYTES, affect the way that data is written into memory. See glPixelStore for a description.
Notes
Values for pixels that lie outside the window connected to the current GL context are undefined. If an error is generated, no change is made to the contents of data.
Errors
GL_INVALID_ENUM is generated if format or type is not an accepted value.
GL_INVALID_ENUM is generated if type is GL_BITMAP and format is not GL_COLOR_INDEX or GL_STENCIL_INDEX.
GL_INVALID_VALUE is generated if either width or height is negative.
GL_INVALID_OPERATION is generated if format is GL_COLOR_INDEX and the color buffers store RGBA color components.
GL_INVALID_OPERATION is generated if format is GL_STENCIL_INDEX and there is no stencil buffer.
GL_INVALID_OPERATION is generated if format is GL_DEPTH_COMPONENT and there is no depth buffer.
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.
The 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.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_PACK_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_PACK_BUFFER target and the data would be packed to the buffer object such that the memory writes required would exceed the data store size.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_PACK_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 glReadPixels is executed between the execution of glBegin and the corresponding execution of glEnd.
glGet with argument GL_INDEX_MODE
glGet with argument GL_PIXEL_PACK_BUFFER_BINDING
See Also
glCopyPixels, glDrawPixels, glPixelMap, glPixelStore, glPixelTransfer, glReadBuffer
glRect
Draw a rectangle
C Specification
Parameters
C Specification
Parameters
Description
glRect supports efficient specification of rectangles as two corner points. Each rectangle command takes four arguments, organized either as two consecutive pairs of (x,y) coordinates or as two pointers to arrays, each containing an (x,y) pair. The resulting rectangle is defined in the z = 0 plane.
glRect(x1, y1, x2, y2) is exactly equivalent to the following sequence:
glBegin(GL_POLYGON);
glVertex2(x1, y1);
glVertex2(x2, y1);
glVertex2(x2, y2);
glVertex2(x1, y2);
glEnd();
Note that if the second vertex is above and to the right of the first vertex, the rectangle is constructed with a counterclockwise winding.
Errors
GL_INVALID_OPERATION is generated if glRect is executed between the execution of glBegin and the corresponding execution of glEnd.
See Also
glBegin, glVertex
glRenderMode
Set rasterization mode
C Specification
GLint glRenderMode(GLenum mode);
Parameters
Description
glRenderMode sets the rasterization mode. It takes one argument, mode, which can assume one of three predefined values:
GL_RENDER
Render mode. Primitives are rasterized, producing pixel fragments, which are written into the frame buffer. This is the normal mode and also the default mode.
GL_SELECT
Selection mode. No pixel fragments are produced, and no change to the frame buffer contents is made. Instead, a record of the names of primitives that would have been drawn if the render mode had been GL_RENDER is returned in a select buffer, which must be created (see glSelectBuffer) before selection mode is entered.
GL_FEEDBACK
Feedback mode. No pixel fragments are produced, and no change to the frame buffer contents is made. Instead, the coordinates and attributes of vertices that would have been drawn if the render mode had been GL_RENDER is returned in a feedback buffer, which must be created (see glFeedbackBuffer) before feedback mode is entered.
The return value of glRenderMode is determined by the render mode at the time glRenderMode is called, rather than by mode. The values returned for the three render modes are as follows:
GL_RENDER
0.
GL_SELECT
The number of hit records transferred to the select buffer.
GL_FEEDBACK
The number of values (not vertices) transferred to the feedback buffer.
See the glSelectBuffer and glFeedbackBuffer reference pages for more details concerning selection and feedback operation.
If an error is generated, glRenderMode returns 0 regardless of the current render mode.
Errors
GL_INVALID_ENUM is generated if mode is not one of the three accepted values.
GL_INVALID_OPERATION is generated if glSelectBuffer is called while the render mode is GL_SELECT, or if glRenderMode is called with argument GL_SELECT before glSelectBuffer is called at least once.
GL_INVALID_OPERATION is generated if glFeedbackBuffer is called while the render mode is GL_FEEDBACK, or if glRenderMode is called with argument GL_FEEDBACK before glFeedbackBuffer is called at least once.
GL_INVALID_OPERATION is generated if glRenderMode is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_RENDER_MODE
See Also
glFeedbackBuffer, glInitNames, glLoadName, glPassThrough, glPushName, glSelectBuffer
glResetHistogram
Reset histogram table entries to zero
C Specification
void glResetHistogram(GLenum target);
Parameters
Description
glResetHistogram resets all the elements of the current histogram table to zero.
Notes
glResetHistogram is present only if ARB_imaging is returned when glGetString is called with an argument of GL_EXTENSIONS.
Errors
GL_INVALID_ENUM is generated if target is not GL_HISTOGRAM.
GL_INVALID_OPERATION is generated if glResetHistogram is executed between the execution of glBegin and the corresponding execution of glEnd.
See Also
glHistogram
glResetMinmax
Reset minmax table entries to initial values
C Specification
void glResetMinmax(GLenum target);
Description
glResetMinmax resets the elements of the current minmax table to their initial values: the “maximum” element receives the minimum possible component values, and the “minimum” element receives the maximum possible component values.
Notes
glResetMinmax is present only if ARB_imaging is returned when glGetString is called with an argument of GL_EXTENSIONS.
Errors
GL_INVALID_ENUM is generated if target is not GL_MINMAX.
GL_INVALID_OPERATION is generated if glResetMinmax is executed between the execution of glBegin and the corresponding execution of glEnd.
See Also
glMinmax
glRotate
Multiply the current matrix by a rotation matrix
C Specification
Parameters
Description
glRotate produces a rotation of angle degrees around the vector (x,y,z). The current matrix (see glMatrixMode) is multiplied by a rotation matrix with the product replacing the current matrix, as if glMultMatrix were called with the following matrix as its argument:
Where c = cos(angle), s = sin(angle), and ||(x,y,z)|| = 1 (if not, the GL will normalize this vector). If the matrix mode is either GL_MODELVIEW or GL_PROJECTION, all objects drawn after glRotate is called are rotated. Use glPushMatrix and glPopMatrix to save and restore the unrotated coordinate system.
This rotation follows the right-hand rule, so if the vector (x,y,z) points toward the user, the rotation will be counterclockwise.
Errors
GL_INVALID_OPERATION is generated if glRotate 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, glScale, glTranslate
glSampleCoverage
Specify multisample coverage parameters
C Specification
void glSampleCoverage(GLclampf value,
GLboolean invert);
Parameters
Description
Multisampling samples a pixel multiple times at various implementation-dependent subpixel locations to generate antialiasing effects. Multisampling transparently antialiases points, lines, polygons, bitmaps, and images if it is enabled.
value is used in constructing a temporary mask used in determining which samples will be used in resolving the final fragment color. This mask is bitwise-anded with the coverage mask generated from the multisampling computation. If the invert flag is set, the temporary mask is inverted (all bits flipped) and then the bitwise-and is computed.
If an implementation does not have any multisample buffers available, or multisampling is disabled, rasterization occurs with only a single sample computing a pixel’s final RGB color.
Provided an implementation supports multisample buffers, and multisampling is enabled, then a pixel’s final color is generated by combining several samples per pixel. Each sample contains color, depth, and stencil information, allowing those operations to be performed on each sample.
Notes
glSampleCoverage is available only if the GL version is 1.3 or greater.
Errors
GL_INVALID_OPERATION is generated if glSampleCoverage is executed between the execution of glBegin and the corresponding execution of glEnd.
glGet with argument GL_SAMPLE_COVERAGE_VALUE
glGet with argument GL_SAMPLE_COVERAGE_INVERT
glIsEnabled with argument GL_MULTISAMPLE
glIsEnabled with argument GL_SAMPLE_ALPHA_TO_COVERAGE
glIsEnabled with argument GL_SAMPLE_ALPHA_TO_ONE
glIsEnabled with argument GL_SAMPLE_COVERAGE
See Also
glEnable, glPushAttrib
glScale
Multiply the current matrix by a general scaling matrix
C Specification
void glScaled(GLdouble x,
GLdouble y,
GLdouble z);
void glScalef(GLfloat x, GLfloat y, GLfloat z);
Parameters
Description
glScale produces a nonuniform scaling along the x, y, and z axes. The three parameters indicate the desired scale factor along each of the three axes.
The current matrix (see glMatrixMode) is multiplied by this scale matrix, and the product replaces the current matrix as if glMultMatrix were called with the following matrix as its argument:
If the matrix mode is either GL_MODELVIEW or GL_PROJECTION, all objects drawn after glScale is called are scaled.
Use glPushMatrix and glPopMatrix to save and restore the unscaled coordinate system.
Notes
If scale factors other than 1 are applied to the modelview matrix and lighting is enabled, lighting often appears wrong. In that case, enable automatic normalization of normals by calling glEnable with the argument GL_NORMALIZE.
Errors
GL_INVALID_OPERATION is generated if glScale 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
glMatrixMode, glMultMatrix, glPushMatrix, glRotate, glTranslate
glScissor
Define the scissor box
C Specification
Parameters
Description
glScissor defines a rectangle, called the scissor box, in window coordinates. The first two arguments, x and y, specify the lower-left corner of the box. width and height specify the width and height of the box.
To enable and disable the scissor test, call glEnable and glDisable with argument GL_SCISSOR_TEST. The test is initially disabled. While the test is enabled, only pixels that lie within the scissor box can be modified by drawing commands. Window coordinates have integer values at the shared corners of frame buffer pixels. glScissor(0,0,1,1) allows modification of only the lower-left pixel in the window, and glScissor(0,0,0,0) doesn’t allow modification of any pixels in the window.
When the scissor test is disabled, it is as though the scissor box includes the entire window.
Errors
GL_INVALID_VALUE is generated if either width or height is negative.
GL_INVALID_OPERATION is generated if glScissor is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_SCISSOR_BOX
glIsEnabled with argument GL_SCISSOR_TEST
See Also
glEnable, glViewport
glSecondaryColor
Set the current secondary color
C Specification
Parameters
C Specification
Parameters
Description
The GL stores both a primary four-valued RGBA color and a secondary four-valued RGBA color (where alpha is always set to 0.0) that is associated with every vertex.
The secondary color is interpolated and applied to each fragment during rasterization when GL_COLOR_SUM is enabled. When lighting is enabled, and GL_SEPARATE_SPECULAR_COLOR is specified, the value of the secondary color is assigned the value computed from the specular term of the lighting computation. Both the primary and secondary current colors are applied to each fragment, regardless of the state of GL_COLOR_SUM, under such conditions. When GL_SEPARATE_SPECULAR_COLOR is specified, the value returned from querying the current secondary color is undefined.
glSecondaryColor3b, glSecondaryColor3s, and glSecondaryColor3i take three signed byte, short, or long integers as arguments. When v is appended to the name, the color commands can take a pointer to an array of such values.
Color values are stored in floating-point format, with unspecified mantissa and exponent sizes. Unsigned integer color components, when specified, are linearly mapped to floating-point values such that the largest representable value maps to 1.0 (full intensity), and 0 maps to 0.0 (zero intensity). Signed integer color components, when specified, are linearly mapped to floating-point values such that the most positive representable value maps to 1.0, and the most negative representable value maps to -1.0. (Note that this mapping does not convert 0 precisely to 0.0). Floating-point values are mapped directly.
Neither floating-point nor signed integer values are clamped to the range [0,1] before the current color is updated. However, color components are clamped to this range before they are interpolated or written into a color buffer.
Notes
glSecondaryColor is available only if the GL version is 1.4 or greater.
The initial value for the secondary color is (0, 0, 0, 0).
The secondary color can be updated at any time. In particular, glSecondaryColor can be called between a call to glBegin and the corresponding call to glEnd.
Associated Gets
glGet with argument GL_CURRENT_SECONDARY_COLOR
glGet with argument GL_RGBA_MODE
glIsEnabled with argument GL_COLOR_SUM
See Also
glColor, glIndex, glIsEnabled, glLightModel, glSecondaryColorPointer
glSecondaryColorPointer
Define an array of secondary colors
C Specification
Parameters
Description
glSecondaryColorPointer specifies the location and data format of an array of color components to use when rendering. size specifies the number of components per color, and must be 3. type specifies the data type of each color component, and stride specifies the byte stride from one color to the next, allowing vertices and attributes to be packed into a single array or stored in separate arrays.
If a nonzero named buffer object is bound to the GL_ARRAY_BUFFER target (see glBindBuffer) while a secondary color 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 secondary color vertex array client-side state (GL_SECONDARY_COLOR_ARRAY_BUFFER_BINDING).
When a secondary color 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 secondary color array, call glEnableClientState and glDisableClientState with the argument GL_SECONDARY_COLOR_ARRAY. If enabled, the secondary color array is used when glArrayElement, glDrawArrays, glMultiDrawArrays, glDrawElements, glMultiDrawElements, or glDrawRangeElements is called.
Notes
glSecondaryColorPointer is available only if the GL version is 1.4 or greater.
Secondary colors are not supported for interleaved vertex array formats (see glInterleavedArrays).
The secondary color array is initially disabled and isn’t accessed when glArrayElement, glDrawElements, glDrawRangeElements, glDrawArrays, glMultiDrawArrays, or glMultiDrawElements is called.
Execution of glSecondaryColorPointer 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.
glSecondaryColorPointer is typically implemented on the client side.
Secondary color 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 3.
GL_INVALID_ENUM is generated if type is not an accepted value.
GL_INVALID_VALUE is generated if stride is negative.
Associated Gets
glIsEnabled with argument GL_SECONDARY_COLOR_ARRAY
glGet with argument GL_SECONDARY_COLOR_ARRAY_SIZE
glGet with argument GL_SECONDARY_COLOR_ARRAY_TYPE
glGet with argument GL_SECONDARY_COLOR_ARRAY_STRIDE
glGet with argument GL_SECONDARY_COLOR_ARRAY_BUFFER_BINDING
glGet with argument GL_ARRAY_BUFFER_BINDING
glGetPointerv with argument GL_SECONDARY_COLOR_ARRAY_POINTER
See Also
glArrayElement, glBindBuffer, glColorPointer, glDisableClientState, glDrawArrays, glDrawElements, glDrawRangeElements, glEdgeFlagPointer, glEnableClientState, glFogCoordPointer, glIndexPointer, glInterleavedArrays, glMultiDrawArrays, glMultiDrawElements, glNormalPointer, glPopClientAttrib, glPushClientAttrib, glSecondaryColor, glTexCoordPointer, glVertexAttribPointer, glVertexPointer
glSelectBuffer
Establish a buffer for selection mode values
C Specification
void glSelectBuffer(GLsizei size,
GLuint * buffer);
Parameters
glSelectBuffer has two arguments: buffer is a pointer to an array of unsigned integers, and size indicates the size of the array. buffer returns values from the name stack (see glInitNames, glLoadName, glPushName) when the rendering mode is GL_SELECT (see glRenderMode). glSelectBuffer must be issued before selection mode is enabled, and it must not be issued while the rendering mode is GL_SELECT.
A programmer can use selection to determine which primitives are drawn into some region of a window. The region is defined by the current modelview and perspective matrices.
In selection mode, no pixel fragments are produced from rasterization. Instead, if a primitive or a raster position intersects the clipping volume defined by the viewing frustum and the user-defined clipping planes, this primitive causes a selection hit. (With polygons, no hit occurs if the polygon is culled.) When a change is made to the name stack, or when glRenderMode is called, a hit record is copied to buffer if any hits have occurred since the last such event (name stack change or glRenderMode call). The hit record consists of the number of names in the name stack at the time of the event, followed by the minimum and maximum depth values of all vertices that hit since the previous event, followed by the name stack contents, bottom name first.
Depth values (which are in the range [0,1]) are multiplied by 232 – 1, before being placed in the hit record.
An internal index into buffer is reset to 0 whenever selection mode is entered. Each time a hit record is copied into buffer, the index is incremented to point to the cell just past the end of the block of names(emthat is, to the next available cell If the hit record is larger than the number of remaining locations in buffer, as much data as can fit is copied, and the overflow flag is set. If the name stack is empty when a hit record is copied, that record consists of 0 followed by the minimum and maximum depth values.
To exit selection mode, call glRenderMode with an argument other than GL_SELECT. Whenever glRenderMode is called while the render mode is GL_SELECT, it returns the number of hit records copied to buffer, resets the overflow flag and the selection buffer pointer, and initializes the name stack to be empty. If the overflow bit was set when glRenderMode was called, a negative hit record count is returned.
Notes
The contents of buffer is undefined until glRenderMode is called with an argument other than GL_SELECT.
glBegin/glEnd primitives and calls to glRasterPos can result in hits. glWindowPos will always generate a selection hit.
Errors
GL_INVALID_VALUE is generated if size is negative.
GL_INVALID_OPERATION is generated if glSelectBuffer is called while the render mode is GL_SELECT, or if glRenderMode is called with argument GL_SELECT before glSelectBuffer is called at least once.
GL_INVALID_OPERATION is generated if glSelectBuffer is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_NAME_STACK_DEPTH
glGet with argument GL_SELECTION_BUFFER_SIZE
glGetPointerv with argument GL_SELECTION_BUFFER_POINTER
See Also
glFeedbackBuffer, glInitNames, glLoadName, glPushName, glRenderMode
glSeparableFilter2D
Define a separable two-dimensional convolution filter
C Specification
Parameters
Description
glSeparableFilter2D builds a two-dimensional separable convolution filter kernel from two arrays of pixels.
The pixel arrays specified by (width, format, type, row) and (height, format, type, column) are processed just as if they had been passed to glDrawPixels, but processing stops after the final expansion to RGBA is completed.
If a nonzero named buffer object is bound to the GL_PIXEL_UNPACK_BUFFER target (see glBindBuffer) while a convolution filter is specified, row and column are treated as byte offsets into the buffer object’s data store.
Next, the R, G, B, and A components of all pixels in both arrays are scaled by the four separable 2D GL_CONVOLUTION_FILTER_SCALE parameters and biased by the four separable 2D GL_CONVOLUTION_FILTER_BIAS parameters. (The scale and bias parameters are set by glConvolutionParameter using the GL_SEPARABLE_2D target and the names GL_CONVOLUTION_FILTER_SCALE and GL_CONVOLUTION_FILTER_BIAS. The parameters themselves are vectors of four values that are applied to red, green, blue, and alpha, in that order.) The R, G, B, and A values are not clamped to [0,1] at any time during this process.
Each pixel is then converted to the internal format specified by internalformat. This conversion simply maps the component values of the pixel (R, G, B, and A) to the values included in the internal format (red, green, blue, alpha, luminance, and intensity). The mapping is as follows:
The red, green, blue, alpha, luminance, and/or intensity components of the resulting pixels are stored in floating-point rather than integer format. They form two one-dimensional filter kernel images. The row image is indexed by coordinate i starting at zero and increasing from left to right. Each location in the row image is derived from element i of row. The column image is indexed by coordinate j starting at zero and increasing from bottom to top. Each location in the column image is derived from element j of column.
Note that after a convolution is performed, the resulting color components are also scaled by their corresponding GL_POST_CONVOLUTION_c_SCALE parameters and biased by their corresponding GL_POST_CONVOLUTION_c_BIAS parameters (where c takes on the values RED, GREEN, BLUE, and ALPHA). These parameters are set by glPixelTransfer.
Notes
glSeparableFilter2D is present only if ARB_imaging is returned when glGetString is called with an argument of GL_EXTENSIONS.
Errors
GL_INVALID_ENUM is generated if target is not GL_SEPARABLE_2D.
GL_INVALID_ENUM is generated if internalformat is not one of the allowable values.
GL_INVALID_ENUM is generated if format is not one of the allowable values.
GL_INVALID_ENUM is generated if type is not one of the allowable values.
GL_INVALID_VALUE is generated if width is less than zero or greater than the maximum supported value. This value may be queried with glGetConvolutionParameter using target GL_SEPARABLE_2D and name GL_MAX_CONVOLUTION_WIDTH.
GL_INVALID_VALUE is generated if height is less than zero or greater than the maximum supported value. This value may be queried with glGetConvolutionParameter using target GL_SEPARABLE_2D and name GL_MAX_CONVOLUTION_HEIGHT.
GL_INVALID_OPERATION is generated if height 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 height 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 row or column 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 glSeparableFilter2D is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetConvolutionParameter, glGetSeparableFilter
glGet with argument GL_PIXEL_UNPACK_BUFFER_BINDING
See Also
glConvolutionFilter1D, glConvolutionFilter2D, glConvolutionParameter, glPixelTransfer
glShadeModel
Select flat or smooth shading
C Specification
void glShadeModel(GLenum mode);
Parameters
Description
GL primitives can have either flat or smooth shading. Smooth shading, the default, causes the computed colors of vertices to be interpolated as the primitive is rasterized, typically assigning different colors to each resulting pixel fragment. Flat shading selects the computed color of just one vertex and assigns it to all the pixel fragments generated by rasterizing a single primitive. In either case, the computed color of a vertex is the result of lighting if lighting is enabled, or it is the current color at the time the vertex was specified if lighting is disabled.
Flat and smooth shading are indistinguishable for points. Starting when glBegin is issued and counting vertices and primitives from 1, the GL gives each flat-shaded line segment i the computed color of vertex i + 1, its second vertex. Counting similarly from 1, the GL gives each flat-shaded polygon the computed color of the vertex listed in the following table. This is the last vertex to specify the polygon in all cases except single polygons, where the first vertex specifies the flat-shaded color.
Flat and smooth shading are specified by glShadeModel with mode set to GL_FLAT and GL_SMOOTH, respectively.
Errors
GL_INVALID_ENUM is generated if mode is any value other than GL_FLAT or GL_SMOOTH.
GL_INVALID_OPERATION is generated if glShadeModel is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_SHADE_MODEL
See Also
glBegin, glColor, glLight, glLightModel
glShaderSource
Replace the source code in a shader object
C Specification
Parameters
Description
glShaderSource sets the source code in shader to the source code in the array of strings specified by string. Any source code previously stored in the shader object is completely replaced. The number of strings in the array is specified by count. If length is NULL, each string is assumed to be null terminated. If length is a value other than NULL, it points to an array containing a string length for each of the corresponding elements of string. Each element in the length array may contain the length of the corresponding string (the null character is not counted as part of the string length) or a value less than 0 to indicate that the string is null terminated. The source code strings are not scanned or parsed at this time; they are simply copied into the specified shader object.
Notes
glShaderSource is available only if the GL version is 2.0 or greater.
OpenGL copies the shader source code strings when glShaderSource is called, so an application may free its copy of the source code strings immediately after the function returns.
GL_INVALID_VALUE is generated if shader is not a value generated by OpenGL.
GL_INVALID_OPERATION is generated if shader is not a shader object.
GL_INVALID_VALUE is generated if count is less than 0.
GL_INVALID_OPERATION is generated if glShaderSource is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetShader with arguments shader and GL_SHADER_SOURCE_LENGTH
glGetShaderSource with argument shader
glIsShader
See Also
glCompileShader, glCreateShader, glDeleteShader
glStencilFunc
Set front and back function and reference value for stencil testing
C Specification
Parameters
Description
Stenciling, like depth-buffering, enables and disables drawing on a per-pixel basis. You draw into the stencil planes using GL drawing primitives, then render geometry and images, using the stencil planes to mask out portions of the screen. Stenciling is typically used in multipass rendering algorithms to achieve special effects, such as decals, outlining, and constructive solid geometry rendering.
The stencil test conditionally eliminates a pixel based on the outcome of a comparison between the reference value and the value in the stencil buffer. To enable and disable the test, call glEnable and glDisable with argument GL_STENCIL_TEST. To specify actions based on the outcome of the stencil test, call glStencilOp or glStencilOpSeparate.
There can be two separate sets of func, ref, and mask parameters; one affects back-facing polygons, and the other affects front-facing polygons as well as other non-polygon primitives. glStencilFunc sets both front and back stencil state to the same values. Use glStencilFuncSeparate to set front and back stencil state to different values.
func is a symbolic constant that determines the stencil comparison function. It accepts one of eight values, shown in the following list. ref is an integer reference value that is used in the stencil comparison. It is clamped to the range [0,2n – 1], where n is the number of bitplanes in the stencil buffer. mask is bitwise ANDed with both the reference value and the stored stencil value, with the ANDed values participating in the comparison.
If stencil represents the value stored in the corresponding stencil buffer location, the following list shows the effect of each comparison function that can be specified by func. Only if the comparison succeeds is the pixel passed through to the next stage in the rasterization process (see glStencilOp). All tests treat stencil values as unsigned integers in the range [0,2n – 1], where n is the number of bitplanes in the stencil buffer.
The following values are accepted by func:
GL_NEVER
Always fails.
GL_LESS
Passes if ( ref & mask ) < ( stencil & mask ).
GL_LEQUAL
Passes if ( ref & mask ) <= ( stencil & mask ).
GL_GREATER
Passes if ( ref & mask ) > ( stencil & mask ).
GL_GEQUAL
Passes if ( ref & mask ) >= ( stencil & mask ).
GL_EQUAL
Passes if ( ref & mask ) = ( stencil & mask ).
GL_NOTEQUAL
Passes if ( ref & mask ) != ( stencil & mask ).
GL_ALWAYS
Always passes.
Notes
Initially, the stencil test is disabled. If there is no stencil buffer, no stencil modification can occur and it is as if the stencil test always passes.
glStencilFunc is the same as calling glStencilFuncSeparate with face set to GL_FRONT_AND_BACK.
Errors
GL_INVALID_ENUM is generated if func is not one of the eight accepted values. GL_INVALID_OPERATION is generated if glStencilFunc is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_STENCIL_FUNC, GL_STENCIL_VALUE_MASK, GL_STENCIL_REF, GL_STENCIL_BACK_FUNC, GL_STENCIL_BACK_VALUE_MASK, GL_STENCIL_BACK_REF, or GL_STENCIL_BITS
glIsEnabled with argument GL_STENCIL_TEST
See Also
glAlphaFunc, glBlendFunc, glDepthFunc, glEnable, glLogicOp, glStencilFuncSeparate, glStencilMask, glStencilMaskSeparate, glStencilOp, glStencilOpSeparate
glStencilFuncSeparate
Set front and/or back function and reference value for stencil testing
C Specification
Description
Stenciling, like depth-buffering, enables and disables drawing on a per-pixel basis. You draw into the stencil planes using GL drawing primitives, then render geometry and images, using the stencil planes to mask out portions of the screen. Stenciling is typically used in multipass rendering algorithms to achieve special effects, such as decals, outlining, and constructive solid geometry rendering.
The stencil test conditionally eliminates a pixel based on the outcome of a comparison between the reference value and the value in the stencil buffer. To enable and disable the test, call glEnable and glDisable with argument GL_STENCIL_TEST. To specify actions based on the outcome of the stencil test, call glStencilOp or glStencilOpSeparate.
There can be two separate sets of func, ref, and mask parameters; one affects back-facing polygons, and the other affects front-facing polygons as well as other non-polygon primitives. glStencilFunc sets both front and back stencil state to the same values, as if glStencilFuncSeparate were called with face set to GL_FRONT_AND_BACK.
func is a symbolic constant that determines the stencil comparison function. It accepts one of eight values, shown in the following list. ref is an integer reference value that is used in the stencil comparison. It is clamped to the range [0,2n – 1], where n is the number of bitplanes in the stencil buffer. mask is bitwise ANDed with both the reference value and the stored stencil value, with the ANDed values participating in the comparison.
If stencil represents the value stored in the corresponding stencil buffer location, the following list shows the effect of each comparison function that can be specified by func. Only if the comparison succeeds is the pixel passed through to the next stage in the rasterization process (see glStencilOp). All tests treat stencil values as unsigned integers in the range [0,2n – 1], where n is the number of bitplanes in the stencil buffer.
The following values are accepted by func:
GL_NEVER
Always fails.
GL_LESS
Passes if ( ref & mask ) < ( stencil & mask ).
GL_LEQUAL
Passes if ( ref & mask ) <= ( stencil & mask ).
GL_GREATER
Passes if ( ref & mask ) > ( stencil & mask ).
GL_GEQUAL
Passes if ( ref & mask ) >= ( stencil & mask ).
GL_EQUAL
Passes if ( ref & mask ) = ( stencil & mask ).
GL_NOTEQUAL
Passes if ( ref & mask ) != ( stencil & mask ).
GL_ALWAYS
Always passes.
glStencilFuncSeparate is available only if the GL version is 2.0 or greater.
Initially, the stencil test is disabled. If there is no stencil buffer, no stencil modification can occur and it is as if the stencil test always passes.
Errors
GL_INVALID_ENUM is generated if func is not one of the eight accepted values.
GL_INVALID_OPERATION is generated if glStencilFuncSeparate is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_STENCIL_FUNC, GL_STENCIL_VALUE_MASK, GL_STENCIL_REF, GL_STENCIL_BACK_FUNC, GL_STENCIL_BACK_VALUE_MASK, GL_STENCIL_BACK_REF, or GL_STENCIL_BITS
glIsEnabled with argument GL_STENCIL_TEST
See Also
glAlphaFunc, glBlendFunc, glDepthFunc, glEnable, glLogicOp, glStencilFunc, glStencilMask, glStencilMaskSeparate, glStencilOp, glStencilOpSeparate
glStencilMask
Control the front and back writing of individual bits in the stencil planes
C Specification
void glStencilMask(GLuint mask);
Parameters
Description
glStencilMask controls the writing of individual bits in the stencil planes. The least significant n bits of mask, where n is the number of bits in the stencil buffer, specify a mask. Where a 1 appears in the mask, it’s possible to write to the corresponding bit in the stencil buffer. Where a 0 appears, the corresponding bit is write-protected. Initially, all bits are enabled for writing.
There can be two separate mask writemasks; one affects back-facing polygons, and the other affects front-facing polygons as well as other non-polygon primitives. glStencilMask sets both front and back stencil writemasks to the same values. Use glStencilMaskSeparate to set front and back stencil writemasks to different values.
Notes
glStencilMask is the same as calling glStencilMaskSeparate with face set to GL_FRONT_AND_BACK.
Errors
GL_INVALID_OPERATION is generated if glStencilMask is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_STENCIL_WRITEMASK, GL_STENCIL_BACK_WRITEMASK, or GL_STENCIL_BITS
glColorMask, glDepthMask, glIndexMask, glStencilFunc, glStencilFuncSeparate, glStencilMaskSeparate, glStencilOp, glStencilOpSeparate
glStencilMaskSeparate
Control the front and/or back writing of individual bits in the stencil planes
C Specification
void glStencilMaskSeparate(GLenum face,
GLuint mask);
Parameters
Description
glStencilMaskSeparate controls the writing of individual bits in the stencil planes. The least significant n bits of mask, where n is the number of bits in the stencil buffer, specify a mask. Where a 1 appears in the mask, it’s possible to write to the corresponding bit in the stencil buffer. Where a 0 appears, the corresponding bit is write-protected. Initially, all bits are enabled for writing.
There can be two separate mask writemasks; one affects back-facing polygons, and the other affects front-facing polygons as well as other non-polygon primitives. glStencilMask sets both front and back stencil writemasks to the same values, as if glStencilMaskSeparate were called with face set to GL_FRONT_AND_BACK.
Notes
glStencilMaskSeparate is available only if the GL version is 2.0 or greater.
Errors
GL_INVALID_OPERATION is generated if glStencilMaskSeparate is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_STENCIL_WRITEMASK, GL_STENCIL_BACK_WRITEMASK, or GL_STENCIL_BITS
See Also
glColorMask, glDepthMask, glIndexMask, glStencilFunc, glStencilFuncSeparate, glStencilMask, glStencilOp, glStencilOpSeparate
glStencilOp
Set front and back stencil test actions
C Specification
Description
Stenciling, like depth-buffering, enables and disables drawing on a per-pixel basis. You draw into the stencil planes using GL drawing primitives, then render geometry and images, using the stencil planes to mask out portions of the screen. Stenciling is typically used in multipass rendering algorithms to achieve special effects, such as decals, outlining, and constructive solid geometry rendering.
The stencil test conditionally eliminates a pixel based on the outcome of a comparison between the value in the stencil buffer and a reference value. To enable and disable the test, call glEnable and glDisable with argument GL_STENCIL_TEST; to control it, call glStencilFunc or glStencilFuncSeparate.
There can be two separate sets of sfail, dpfail, and dppass parameters; one affects back-facing polygons, and the other affects front-facing polygons as well as other non-polygon primitives. glStencilOp sets both front and back stencil state to the same values. Use glStencilOpSeparate to set front and back stencil state to different values.
glStencilOp takes three arguments that indicate what happens to the stored stencil value while stenciling is enabled. If the stencil test fails, no change is made to the pixel’s color or depth buffers, and sfail specifies what happens to the stencil buffer contents. The following eight actions are possible.
GL_KEEP
Keeps the current value.
GL_ZERO
Sets the stencil buffer value to 0.
GL_REPLACE
Sets the stencil buffer value to ref, as specified by glStencilFunc.
GL_INCR
Increments the current stencil buffer value. Clamps to the maximum representable unsigned value.
GL_INCR_WRAP
Increments the current stencil buffer value. Wraps stencil buffer value to zero when incrementing the maximum representable unsigned value.
GL_DECR
Decrements the current stencil buffer value. Clamps to 0.
GL_DECR_WRAP
Decrements the current stencil buffer value. Wraps stencil buffer value to the maximum representable unsigned value when decrementing a stencil buffer value of zero.
GL_INVERT
Bitwise inverts the current stencil buffer value.
Stencil buffer values are treated as unsigned integers. When incremented and decremented, values are clamped to 0 and 2n – 1, where n is the value returned by querying GL_STENCIL_BITS.
The other two arguments to glStencilOp specify stencil buffer actions that depend on whether subsequent depth buffer tests succeed (dppass) or fail (dpfail) (see glDepthFunc). The actions are specified using the same eight symbolic constants as sfail. Note that dpfail is ignored when there is no depth buffer, or when the depth buffer is not enabled. In these cases, sfail and dppass specify stencil action when the stencil test fails and passes, respectively.
Notes
GL_DECR_WRAP and GL_INCR_WRAP are available only if the GL version is 1.4 or greater.
Initially the stencil test is disabled. If there is no stencil buffer, no stencil modification can occur and it is as if the stencil tests always pass, regardless of any call to glStencilOp.
glStencilOp is the same as calling glStencilOpSeparate with face set to GL_FRONT_AND_BACK.
Errors
GL_INVALID_ENUM is generated if sfail, dpfail, or dppass is any value other than the eight defined constant values.
GL_INVALID_OPERATION is generated if glStencilOp is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_STENCIL_FAIL, GL_STENCIL_PASS_DEPTH_PASS, GL_STENCIL_PASS_DEPTH_FAIL, GL_STENCIL_BACK_FAIL, GL_STENCIL_BACK_PASS_DEPTH_PASS, GL_STENCIL_BACK_PASS_DEPTH_FAIL, or GL_STENCIL_BITS
glIsEnabled with argument GL_STENCIL_TEST
See Also
glAlphaFunc, glBlendFunc, glDepthFunc, glEnable, glLogicOp, glStencilFunc, glStencilFuncSeparate, glStencilMask, glStencilMaskSeparate, glStencilOpSeparate
glStencilOpSeparate
Set front and/or back stencil test actions
C Specification
Parameters
Description
Stenciling, like depth-buffering, enables and disables drawing on a per-pixel basis. You draw into the stencil planes using GL drawing primitives, then render geometry and images, using the stencil planes to mask out portions of the screen. Stenciling is typically used in multipass rendering algorithms to achieve special effects, such as decals, outlining, and constructive solid geometry rendering.
The stencil test conditionally eliminates a pixel based on the outcome of a comparison between the value in the stencil buffer and a reference value. To enable and disable the test, call glEnable and glDisable with argument GL_STENCIL_TEST; to control it, call glStencilFunc or glStencilFuncSeparate.
There can be two separate sets of sfail, dpfail, and dppass parameters; one affects back-facing polygons, and the other affects front-facing polygons as well as other non-polygon primitives. glStencilOp sets both front and back stencil state to the same values, as if glStencilOpSeparate were called with face set to GL_FRONT_AND_BACK.
glStencilOpSeparate takes three arguments that indicate what happens to the stored stencil value while stenciling is enabled. If the stencil test fails, no change is made to the pixel’s color or depth buffers, and sfail specifies what happens to the stencil buffer contents. The following eight actions are possible.
GL_KEEP
Keeps the current value.
GL_ZERO
Sets the stencil buffer value to 0.
GL_REPLACE
Sets the stencil buffer value to ref, as specified by glStencilFunc.
GL_INCR
Increments the current stencil buffer value. Clamps to the maximum representable unsigned value.
GL_INCR_WRAP
Increments the current stencil buffer value. Wraps stencil buffer value to zero when incrementing the maximum representable unsigned value.
GL_DECR
Decrements the current stencil buffer value. Clamps to 0.
GL_DECR_WRAP
Decrements the current stencil buffer value. Wraps stencil buffer value to the maximum representable unsigned value when decrementing a stencil buffer value of zero.
GL_INVERT
Bitwise inverts the current stencil buffer value.
Stencil buffer values are treated as unsigned integers. When incremented and decremented, values are clamped to 0 and 2n – 1, where n is the value returned by querying GL_STENCIL_BITS.
The other two arguments to glStencilOpSeparate specify stencil buffer actions that depend on whether subsequent depth buffer tests succeed (dppass) or fail (dpfail) (see glDepthFunc). The actions are specified using the same eight symbolic constants as sfail. Note that dpfail is ignored when there is no depth buffer, or when the depth buffer is not enabled. In these cases, sfail and dppass specify stencil action when the stencil test fails and passes, respectively.
Notes
glStencilOpSeparate is available only if the GL version is 2.0 or greater.
Initially the stencil test is disabled. If there is no stencil buffer, no stencil modification can occur and it is as if the stencil test always passes.
Errors
GL_INVALID_ENUM is generated if face is any value other than GL_FRONT, GL_BACK, or GL_FRONT_AND_BACK.
GL_INVALID_ENUM is generated if sfail, dpfail, or dppass is any value other than the eight defined constant values.
GL_INVALID_OPERATION is generated if glStencilOpSeparate is executed between the execution of glBegin and the corresponding execution of glEnd.
glGet with argument GL_STENCIL_FAIL, GL_STENCIL_PASS_DEPTH_PASS, GL_STENCIL_PASS_DEPTH_FAIL, GL_STENCIL_BACK_FAIL, GL_STENCIL_BACK_PASS_DEPTH_PASS, GL_STENCIL_BACK_PASS_DEPTH_FAIL, or GL_STENCIL_BITS
glIsEnabled with argument GL_STENCIL_TEST
See Also
glAlphaFunc, glBlendFunc, glDepthFunc, glEnable, glLogicOp, glStencilFunc, glStencilFuncSeparate, glStencilMask, glStencilMaskSeparate, glStencilOp
glTexCoord
Set the current texture coordinates
C Specification
Parameters
Parameters
Description
glTexCoord specifies texture coordinates in one, two, three, or four dimensions. glTexCoord1 sets the current texture coordinates to (s,0,0,1); a call to glTexCoord2 sets them to (s,t,0,1). Similarly, glTexCoord3 specifies the texture coordinates as (s,t,r,1), and glTexCoord4 defines all four components explicitly as (s,t,r,q).
The current texture coordinates are part of the data that is associated with each vertex and with the current raster position. Initially, the values for s, t, r, and q are (0, 0, 0, 1).
Notes
The current texture coordinates can be updated at any time. In particular, glTexCoord can be called between a call to glBegin and the corresponding call to glEnd.
When the ARB_imaging extension is supported, glTexCoord always updates texture unit GL_TEXTURE0.
Associated Gets
glGet with argument GL_CURRENT_TEXTURE_COORDS
See Also
glMultiTexCoord, glTexCoordPointer, glVertex
glTexCoordPointer
Define an array of texture coordinates
C Specification
Description
glTexCoordPointer specifies the location and data format of an array of texture coordinates to use when rendering. size specifies the number of coordinates per texture coordinate set, and must be 1, 2, 3, or 4. type specifies the data type of each texture coordinate, and stride specifies the byte stride from one texture coordinate set 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 texture coordinate 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 texture coordinate vertex array client-side state (GL_TEXTURE_COORD_ARRAY_BUFFER_BINDING).
When a texture coordinate 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 a texture coordinate array, call glEnableClientState and glDisableClientState with the argument GL_TEXTURE_COORD_ARRAY. If enabled, the texture coordinate array is used when glArrayElement, glDrawArrays, glMultiDrawArrays, glDrawElements, glMultiDrawElements, or glDrawRangeElements is called.
Notes
glTexCoordPointer is available only if the GL version is 1.1 or greater.
For OpenGL versions 1.3 and greater, or when the ARB_multitexture extension is supported, glTexCoordPointer updates the texture coordinate array state of the active client texture unit, specified with glClientActiveTexture.
Each texture coordinate array is initially disabled and isn’t accessed when glArrayElement, glDrawElements, glDrawRangeElements, glDrawArrays, glMultiDrawArrays, or glMultiDrawElements is called.
Execution of glTexCoordPointer 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.
glTexCoordPointer is typically implemented on the client side.
Texture coordinate 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 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
glIsEnabled with argument GL_TEXTURE_COORD_ARRAY
glGet with argument GL_TEXTURE_COORD_ARRAY_SIZE
glGet with argument GL_TEXTURE_COORD_ARRAY_TYPE
glGet with argument GL_TEXTURE_COORD_ARRAY_STRIDE
glGet with argument GL_TEXTURE_COORD_ARRAY_BUFFER_BINDING
glGet with argument GL_ARRAY_BUFFER_BINDING
glGetPointerv with argument GL_TEXTURE_COORD_ARRAY_POINTER
See Also
glArrayElement, glBindBuffer, glClientActiveTexture, glColorPointer, glDisableClientState, glDrawArrays, glDrawElements, glDrawRangeElements, glEdgeFlagPointer, glEnableClientState, glFogCoordPointer, glIndexPointer, glInterleavedArrays, glMultiDrawArrays, glMultiDrawElements, glMultiTexCoord, glNormalPointer, glPopClientAttrib, glPushClientAttrib, glSecondaryColorPointer, glTexCoord, glVertexAttribPointer, glVertexPointer
glTexEnv
Set texture environment parameters
C Specification
Parameters
C Specification
Parameters
Description
A texture environment specifies how texture values are interpreted when a fragment is textured. When target is GL_TEXTURE_FILTER_CONTROL, pname must be GL_TEXTURE_LOD_BIAS. When target is GL_TEXTURE_ENV, pname can be GL_TEXTURE_ENV_MODE, GL_TEXTURE_ENV_COLOR, GL_COMBINE_RGB, GL_COMBINE_ALPHA, RGB_SCALE, ALPHA_SCALE, SRC0_RGB, SRC1_RGB, SRC2_RGB, SRC0_ALPHA, SRC1_ALPHA, or SRC2_ALPHA.
If pname is GL_TEXTURE_ENV_MODE, then params is (or points to) the symbolic name of a texture function. Six texture functions may be specified: GL_ADD, GL_MODULATE, GL_DECAL, GL_BLEND, GL_REPLACE, or GL_COMBINE.
A texture function acts on the fragment to be textured using the texture image value that applies to the fragment (see glTexParameter) and produces an RGBA color for that fragment. The following table shows how the RGBA color is produced for each of the three texture functions that can be chosen. C is a triple of color values (RGB) and A is the associated alpha value. RGBA values extracted from a texture image are in the range [0,1]. The subscript f refers to the incoming fragment, the subscript t to the texture image, the subscript c to the texture environment color, and subscript v indicates a value produced by the texture function.
A texture image can have up to four components per texture element (see glTexImage1D, glTexImage2D, glTexImage3D, glCopyTexImage1D, and glCopyTexImage2D). In a one-component image, Lt indicates that single component. A two-component image uses Lt and At. A three-component image has only a color value, Ct. A four-component image has both a color value Ct and an alpha value At.
If pname is GL_TEXTURE_ENV_MODE, and params is GL_COMBINE, the form of the texture function depends on the values of GL_COMBINE_RGB and GL_COMBINE_ALPHA.
The following describes how the texture sources, as specified by GL_SRC0_RGB, GL_SRC1_RGB, GL_SRC2_RGB, GL_SRC0_ALPHA, GL_SRC1_ALPHA, and GL_SRC2_ALPHA, are combined to produce a final texture color. In the following tables, GL_SRC0_c is represented by Arg0, GL_SRC1_c is represented by Arg1, and GL_SRC2_c is represented by Arg2.
GL_COMBINE_RGB accepts any of GL_REPLACE, GL_MODULATE, GL_ADD, GL_ADD_SIGNED, GL_INTERPOLATE, GL_SUBTRACT, GL_DOT3_RGB, or GL_DOT3_RGBA.
The scalar results for GL_DOT3_RGB and GL_DOT3_RGBA are placed into each of the 3 (RGB) or 4 (RGBA) components on output.
Likewise, GL_COMBINE_ALPHA accepts any of GL_REPLACE, GL_MODULATE, GL_ADD, GL_ADD_SIGNED, GL_INTERPOLATE, or GL_SUBTRACT. The following table describes how alpha values are combined:
In the following tables, the value Cs represents the color sampled from the currently bound texture, Cc represents the constant texture-environment color, Cf represents the primary color of the incoming fragment, and Cp represents the color computed from the previous texture stage, or zero if processing texture stage 0. Likewise, As, Ac, Af, and Ap represent the respective alpha values.
The following table describes the values assigned to Arg0, Arg1, and Arg2 based upon the RGB sources and operands:
For GL_TEXTUREn sources, Cs and As represent the color and alpha, respectively, produced from texture stage n.
The follow table describes the values assigned to Arg0, Arg1, and Arg2 based upon the alpha sources and operands:
The RGB and alpha results of the texture function are multipled by the values of GL_RGB_SCALE and GL_ALPHA_SCALE, respectively, and clamped to the range [0,1].
If pname is GL_TEXTURE_ENV_COLOR, params is a pointer to an array that holds an RGBA color consisting of four values. 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. Cc takes these four values.
If pname is GL_TEXTURE_LOD_BIAS, the value specified is added to the texture level-of-detail parameter, that selects which mipmap, or mipmaps depending upon the selected GL_TEXTURE_MIN_FILTER, will be sampled.
GL_TEXTURE_ENV_MODE defaults to GL_MODULATE and GL_TEXTURE_ENV_COLOR defaults to (0, 0, 0, 0).
If target is GL_POINT_SPRITE and pname is GL_COORD_REPLACE, the boolean value specified is used to either enable or disable point sprite texture coordinate replacement. The default value is GL_FALSE.
Notes
GL_REPLACE may only be used if the GL version is 1.1 or greater.
GL_TEXTURE_FILTER_CONTROL and GL_TEXTURE_LOD_BIAS may only be used if the GL version is 1.4 or greater.
GL_COMBINE mode and its associated constants may only be used if the GL version is 1.3 or greater.
GL_TEXTUREn may only be used if the GL version is 1.4 or greater.
Internal formats other than 1, 2, 3, or 4 may only be used if the GL version is 1.1 or greater.
For OpenGL versions 1.3 and greater, or when the ARB_multitexture extension is supported, glTexEnv controls the texture environment for the current active texture unit, selected by glActiveTexture.
GL_POINT_SPRITE and GL_COORD_REPLACE are available only if the GL version is 2.0 or greater.
Errors
GL_INVALID_ENUM is generated when target or pname is not one of the accepted defined values, or when params should have a defined constant value (based on the value of pname) and does not.
GL_INVALID_VALUE is generated if the params value for GL_RGB_SCALE is not one of 1.0, 2.0, or 4.0.
GL_INVALID_OPERATION is generated if glTexEnv is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetTexEnv
See Also
glActiveTexture, glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glTexImage1D, glTexImage2D, glTexImage3D, glTexParameter, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D
glTexGen
Control the generation of texture coordinates
C Specification
Parameters
C Specification
Parameters
Description
glTexGen selects a texture-coordinate generation function or supplies coefficients for one of the functions. coord names one of the (s, t, r, q) texture coordinates; it must be one of the symbols GL_S, GL_T, GL_R, or GL_Q. pname must be one of three symbolic constants: GL_TEXTURE_GEN_MODE, GL_OBJECT_PLANE, or GL_EYE_PLANE. If pname is GL_TEXTURE_GEN_MODE, then params chooses a mode, one of GL_OBJECT_LINEAR, GL_EYE_LINEAR, GL_SPHERE_MAP, GL_NORMAL_MAP, or GL_REFLECTION_MAP. If pname is either GL_OBJECT_PLANE or GL_EYE_PLANE, params contains coefficients for the corresponding texture generation function.
If the texture generation function is GL_OBJECT_LINEAR, the function
g = p1 × xo + p2 × yo + p3 × zo + p4 × wo
is used, where g is the value computed for the coordinate named in coord, p1, p2, p3, and p4 are the four values supplied in params, and xo, yo, zo, and wo are the object coordinates of the vertex. This function can be used, for example, to texture-map terrain using sea level as a reference plane (defined by p1, p2, p3, and p4). The altitude of a terrain vertex is computed by the GL_OBJECT_LINEAR coordinate generation function as its distance from sea level; that altitude can then be used to index the texture image to map white snow onto peaks and green grass onto foothills.
If the texture generation function is GL_EYE_LINEAR, the function
g = p1 “ × xe + p2 “ × ye + p3 “ × ze + p4 “ × we
is used, where
(p1 “ p2 “ p3 “ p4 “) = (p1p2p3p4)M-1
and xe, ye, ze, and we are the eye coordinates of the vertex, p1, p2, p3, and p4 are the values supplied in params, and M is the modelview matrix when glTexGen is invoked. If M is poorly conditioned or singular, texture coordinates generated by the resulting function may be inaccurate or undefined.
Note that the values in params define a reference plane in eye coordinates. The modelview matrix that is applied to them may not be the same one in effect when the polygon vertices are transformed. This function establishes a field of texture coordinates that can produce dynamic contour lines on moving objects.
If pname is GL_SPHERE_MAP and coord is either GL_S or GL_T, s and t texture coordinates are generated as follows. Let u be the unit vector pointing from the origin to the polygon vertex (in eye coordinates). Let n sup prime be the current normal, after transformation to eye coordinates. Let f = (fxfyfz) T be the reflection vector such that
f = u – 2n“n” Tu
Finally, let 
. Then the values assigned to the s and t texture coordinates are
To enable or disable a texture-coordinate generation function, call glEnable or glDisable with one of the symbolic texture-coordinate names (GL_TEXTURE_GEN_S, GL_TEXTURE_GEN_T, GL_TEXTURE_GEN_R, or GL_TEXTURE_GEN_Q) as the argument. When enabled, the specified texture coordinate is computed according to the generating function associated with that coordinate. When disabled, subsequent vertices take the specified texture coordinate from the current set of texture coordinates. Initially, all texture generation functions are set to GL_EYE_LINEAR and are disabled. Both s plane equations are (1, 0, 0, 0), both t plane equations are (0, 1, 0, 0), and all r and q plane equations are (0, 0, 0, 0).
When the ARB_multitexture extension is supported, glTexGen set the texture generation parameters for the currently active texture unit, selected with glActiveTexture.
Errors
GL_INVALID_ENUM is generated when coord or pname is not an accepted defined value, or when pname is GL_TEXTURE_GEN_MODE and params is not an accepted defined value.
GL_INVALID_ENUM is generated when pname is GL_TEXTURE_GEN_MODE, params is GL_SPHERE_MAP, and coord is either GL_R or GL_Q.
GL_INVALID_OPERATION is generated if glTexGen is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetTexGen
glIsEnabled with argument GL_TEXTURE_GEN_S
glIsEnabled with argument GL_TEXTURE_GEN_T
glIsEnabled with argument GL_TEXTURE_GEN_R
glIsEnabled with argument GL_TEXTURE_GEN_Q
See Also
glActiveTexture, glCopyPixels, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glTexEnv, glTexImage1D, glTexImage2D, glTexImage3D, glTexParameter, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D
glTexImage1D
Specify a one-dimensional texture image
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 one-dimensional texturing, call glEnable and glDisable with argument GL_TEXTURE_1D.
Texture images are defined with glTexImage1D. The arguments describe the parameters of the texture image, such as width, width of the border, level-of-detail number (see glTexParameter), and the internal resolution and format used to store the image. The last three arguments describe how the image is represented in memory; they are identical to the pixel formats used for glDrawPixels.
If target is GL_PROXY_TEXTURE_1D, no data is read from data, but all of the texture image state is recalculated, checked for consistency, and checked against the implementation’s capabilities. If the implementation cannot handle a texture of the requested texture size, it sets all of the image state to 0, but does not generate an error (see glGetError). To query for an entire mipmap array, use an image array level greater than or equal to 1.
If target is GL_TEXTURE_1D, data is read from data as a sequence of signed or unsigned bytes, shorts, or longs, or single-precision floating-point values, depending on type. These values are grouped into sets of one, two, three, or four values, depending on format, to form elements. If type is GL_BITMAP, the data is considered as a string of unsigned bytes (and format must be GL_COLOR_INDEX). Each data byte is treated as eight 1-bit elements, with bit ordering determined by GL_UNPACK_LSB_FIRST (see glPixelStore).
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.
The first element corresponds to the left end of the texture array. Subsequent elements progress left-to-right through the remaining texels in the texture array. The final element corresponds to the right end of the texture array.
format determines the composition of each element in data. It can assume one of these symbolic values:
GL_COLOR_INDEX
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).
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).
GL_DEPTH_COMPONENT
Each element is a single depth value. The GL converts it to floating point, multiplies by the signed scale factor GL_DEPTH_SCALE, adds the signed bias GL_DEPTH_BIAS, and clamps 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_1D 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 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.
Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA textures during texture filtering and application. Image-based shadowing can be enabled by comparing texture r coordinates to depth texture values to generate a boolean result. See glTexParameter for details on texture comparison.
Notes
Texturing has no effect in color index mode.
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. One-dimensional convolution filtering, if enabled. See glConvolutionFilter1D. If a convolution filter changes the width of the texture (by processing with a GL_CONVOLUTION_BORDER_MODE of GL_REDUCE, for example), the width must 2n + 2(border), for some integer n, after filtering.
3. RGBA components may be multiplied by GL_POST_CONVOLUTION_c_SCALE, and added to GL_POST_CONVOLUTION_c_BIAS, if enabled. See glPixelTransfer.
4. Color component replacement by the color table specified for GL_POST_CONVOLUTION_COLOR_TABLE, if enabled. See glColorTable.
5. Transformation by the color matrix.
See glMatrixMode.
6. 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.
7. Color component replacement by the color table specified for GL_POST_COLOR_MATRIX_COLOR_TABLE, if enabled. See glColorTable.
The texture image can be represented by the same data formats as the pixels in a glDrawPixels command, except that GL_STENCIL_INDEX cannot be used. glPixelStore and glPixelTransfer modes affect texture images in exactly the way they affect glDrawPixels.
GL_PROXY_TEXTURE_1D may be used only if the GL version is 1.1 or greater.
Internal formats other than 1, 2, 3, or 4 may be used only if the GL version is 1.1 or greater.
In GL version 1.1 or greater, data may be a null pointer. In this case texture memory is allocated to accommodate a texture of width width. You can then download subtextures to initialize the 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.
When the ARB_multitexture extension is supported, or the GL version is 1.3 or greater, glTexImage1D specifies the one-dimensional texture for the current texture unit, specified with glActiveTexture.
GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24, and GL_DEPTH_COMPONENT32 are available only if the GL version is 1.4 or greater.
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_1D or GL_PROXY_TEXTURE_1D.
GL_INVALID_ENUM is generated if format is not an accepted format constant. Format constants other than GL_STENCIL_INDEX 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 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 cannot be represented as 2n + 2(border) for some integer value of n.
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 is GL_DEPTH_COMPONENT and internalFormat is not GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24, or GL_DEPTH_COMPONENT32.
GL_INVALID_OPERATION is generated if internalFormat is GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24, or GL_DEPTH_COMPONENT32, and format is not GL_DEPTH_COMPONENT.
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 glTexImage1D 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, glColorTable, glCompressedTexImage1D, glCompressedTexSubImage1D, glConvolutionFilter1D, glCopyPixels, glCopyTexImage1D, glCopyTexSubImage1D, glDrawPixels, glGetCompressedTexImage, glMatrixMode, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D, glTexParameter
glTexImage2D
Specify a two-dimensional texture image
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 two-dimensional texturing, call glEnable and glDisable with argument GL_TEXTURE_2D. To enable and disable texturing using cube-mapped texture, call glEnable and glDisable with argument GL_TEXTURE_CUBE_MAP.
To define texture images, call glTexImage2D. The arguments describe the parameters of the texture image, such as height, width, width of the border, level-of-detail number (see glTexParameter), and number of color components provided. The last three arguments describe how the image is represented in memory; they are identical to the pixel formats used for glDrawPixels.
If target is GL_PROXY_TEXTURE_2D or GL_PROXY_TEXTURE_CUBE_MAP, no data is read from data, but all of the texture image state is recalculated, checked for consistency, and checked against the implementation’s capabilities. If the implementation cannot handle a texture of the requested texture size, it sets all of the image state to 0, but does not generate an error (see glGetError). To query for an entire mipmap array, use an image array level greater than or equal to 1.
If target is GL_TEXTURE_2D, or one of the GL_TEXTURE_CUBE_MAP targets, data is read from data as a sequence of signed or unsigned bytes, shorts, or longs, or single-precision floating-point values, depending on type. These values are grouped into sets of one, two, three, or four values, depending on format, to form elements. If type is GL_BITMAP, the data is considered as a string of unsigned bytes (and format must be GL_COLOR_INDEX). Each data byte is treated as eight 1-bit elements, with bit ordering determined by GL_UNPACK_LSB_FIRST (see glPixelStore).
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.
The first element corresponds to the lower-left corner of the texture image. Subsequent elements progress left-to-right through the remaining texels in the lowest row of the texture image, and then in successively higher rows of the texture image. The final element corresponds to the upper-right corner of the texture image.
format determines the composition of each element in data. It can assume one of these symbolic values:
GL_COLOR_INDEX
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).
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).
GL_DEPTH_COMPONENT
Each element is a single depth value. The GL converts it to floating point, multiplies by the signed scale factor GL_DEPTH_SCALE, adds the signed bias GL_DEPTH_BIAS, and clamps 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_2D or GL_PROXY_TEXTURE_CUBE_MAP 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.
Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA textures during texture filtering and application. Image-based shadowing can be enabled by comparing texture r coordinates to depth texture values to generate a boolean result. See glTexParameter for details on texture comparison.
Texturing has no effect in color index mode.
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. Two-dimensional Convolution filtering, if enabled.
See glConvolutionFilter1D.
If a convolution filter changes the width of the texture (by processing with a GL_CONVOLUTION_BORDER_MODE of GL_REDUCE, for example), and the GL does not support non-power-of-two textures, the width must 2n + 2(border), for some integer n, and height must be 2m + 2(border), for some integer m, after filtering.
3. RGBA components may be multiplied by GL_POST_CONVOLUTION_c_SCALE, and added to GL_POST_CONVOLUTION_c_BIAS, if enabled. See glPixelTransfer.
4. Color component replacement by the color table specified for GL_POST_CONVOLUTION_COLOR_TABLE, if enabled. See glColorTable.
5. Transformation by the color matrix.
See glMatrixMode.
6. 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.
7. Color component replacement by the color table specified for GL_POST_COLOR_MATRIX_COLOR_TABLE, if enabled. See glColorTable.
The texture image can be represented by the same data formats as the pixels in a glDrawPixels command, except that GL_STENCIL_INDEX cannot be used. glPixelStore and glPixelTransfer modes affect texture images in exactly the way they affect glDrawPixels.
glTexImage2D and GL_PROXY_TEXTURE_2D are available only if the GL version is 1.1 or greater.
Internal formats other than 1, 2, 3, or 4 may be used only if the GL version is 1.1 or greater.
In GL version 1.1 or greater, data may be a null pointer. In this case, texture memory is allocated to accommodate a texture of width width and height height. You can then download subtextures to initialize this texture memory. The image is undefined if the user 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.
When the ARB_multitexture extension is supported or the GL version is 1.3 or greater, glTexImage2D specifies the two-dimensional texture for the current texture unit, specified with glActiveTexture.
GL_TEXTURE_CUBEMAP and GL_PROXY_TEXTURE_CUBEMAP are available only if the GL version is 1.3 or greater.
GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24, and GL_DEPTH_COMPONENT32 are available only if the GL version is 1.4 or greater.
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.
GL_INVALID_ENUM is generated if target is not GL_TEXTURE_2D, GL_PROXY_TEXTURE_2D, GL_PROXY_TEXTURE_CUBE_MAP, GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL_TEXTURE_CUBE_MAP_NEGATIVE_X, GL_TEXTURE_CUBE_MAP_POSITIVE_Y, GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, GL_TEXTURE_CUBE_MAP_POSITIVE_Z, or GL_TEXTURE_CUBE_MAP_NEGATIVE_Z.
GL_INVALID_ENUM is generated if target is one of the six cube map 2D image targets and the width and height parameters are not equal.
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 width or height is less than 0 or greater than 2 + GL_MAX_TEXTURE_SIZE.
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 or height 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 or height 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 target is not GL_TEXTURE_2D or GL_PROXY_TEXTURE_2D and internalFormat is GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24, or GL_DEPTH_COMPONENT32.
GL_INVALID_OPERATION is generated if format is GL_DEPTH_COMPONENT and internalFormat is not GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24, or GL_DEPTH_COMPONENT32.
GL_INVALID_OPERATION is generated if internalFormat is GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24, or GL_DEPTH_COMPONENT32, and format is not GL_DEPTH_COMPONENT.
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 glTexImage2D is executed between the execution of glBegin and the corresponding execution of glEnd.
glGetTexImage
glIsEnabled with argument GL_TEXTURE_2D or GL_TEXTURE_CUBE_MAP
glGet with argument GL_PIXEL_UNPACK_BUFFER_BINDING
See Also
glActiveTexture, glColorTable, glConvolutionFilter2D, glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glMatrixMode, glPixelStore, glPixelTransfer, glSeparableFilter2D, glTexEnv, glTexGen, glTexImage1D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D, glTexParameter
glTexImage3D
Specify a three-dimensional texture image
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.
To define texture images, call glTexImage3D. The arguments describe the parameters of the texture image, such as height, width, depth, width of the border, level-of-detail number (see glTexParameter), and number of color components provided. The last three arguments describe how the image is represented in memory; they are identical to the pixel formats used for glDrawPixels.
If target is GL_PROXY_TEXTURE_3D, no data is read from data, but all of the texture image state is recalculated, checked for consistency, and checked against the implementation’s capabilities. If the implementation cannot handle a texture of the requested texture size, it sets all of the image state to 0, but does not generate an error (see glGetError). To query for an entire mipmap array, use an image array level greater than or equal to 1.
If target is GL_TEXTURE_3D, data is read from data as a sequence of signed or unsigned bytes, shorts, or longs, or single-precision floating-point values, depending on type. These values are grouped into sets of one, two, three, or four values, depending on format, to form elements. If type is GL_BITMAP, the data is considered as a string of unsigned bytes (and format must be GL_COLOR_INDEX). Each data byte is treated as eight 1-bit elements, with bit ordering determined by GL_UNPACK_LSB_FIRST (see glPixelStore).
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.
The first element corresponds to the lower-left corner of the texture image. Subsequent elements progress left-to-right through the remaining texels in the lowest row of the texture image, and then in successively higher rows of the texture image. The final element corresponds to the upper-right corner of the texture image.
format determines the composition of each element in data. It can assume one of these symbolic values: