![[Previous Section]](../shared/b_prev.gif){kind=small}
![[Back to Table of Contents]](../shared/b_toc.gif){kind=small}
![[Next Section]](../shared/b_next.gif){kind=small}
|
|
OpenGL Reference Manual (Addison-Wesley Publishing Company) |
This chapter contains the reference pages, in alphabetical order, for all the OpenGL commands. Each reference page may describe more than one related command, as shown in the following list of pages. The OpenGL Utility Library routines and those comprising the OpenGL extension to the X Window System are described in the following chapters
glAccum - operate on the accumulation buffer
void glAccum( GLenum op, GLfloat value )
The accumulation buffer is an extended-range color buffer. Images are not rendered into it. Rather, images rendered into one of the color buffers are added to the contents of the accumulation buffer after rendering. Effects such as antialiasing (of points, lines, and polygons), motion blur, and depth of field can be created by accumulating images generated with different transformation matrices.
Each pixel in the accumulation buffer consists of red, green, blue, and alpha values. The number of bits per component in the accumulation buffer depends on the implementation. You can examine this number by calling glGetIntegerv four times, with arguments GL_ACCUM_RED_BITS, GL_ACCUM_GREEN_BITS, GL_ACCUM_BLUE_BITS, and GL_ACCUM_ALPHA_BITS, respectively. Regardless of the number of bits per component, however, the range of values stored by each component is [-1, 1]. The accumulation buffer pixels are mapped one-to-one with frame buffer pixels.
glAccum operates on the accumulation buffer. The first argument, op, is a symbolic constant that selects an accumulation buffer operation. The second argument, value, is a floating-point value to be used in that operation. Five operations are specified: GL_ACCUM, GL_LOAD, GL_ADD, GL_MULT, and GL_RETURN.
All accumulation buffer operations are limited to the area of the current scissor box and are applied identically to the red, green, blue, and alpha components of each pixel. The contents of an accumulation buffer pixel component are undefined if the glAccum operation results in a value outside the range [-1,1]. The operations are as follows:
The accumulation buffer is cleared by specifying R, G, B, and A values to set it to with the glClearAccum directive, and issuing a glClear command with the accumulation buffer enabled.
Only those pixels within the current scissor box are updated by any glAccum operation.
GL_INVALID_ENUM is generated if op is not an accepted value.
GL_INVALID_OPERATION is generated if there is no accumulation buffer.
GL_INVALID_OPERATION is generated if glAccum is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_ACCUM_RED_BITS
glGet with argument GL_ACCUM_GREEN_BITS
glGet with argument GL_ACCUM_BLUE_BITS
glGet with argument GL_ACCUM_ALPHA_BITS
"glBlendFunc", "glClear", "glClearAccum", "glCopyPixels", "glGet", "glLogicOp", "glPixelStore", "glPixelTransfer", "glReadPixels", "glReadBuffer", "glScissor", "glStencilOp"
glAlphaFunc - specify the alpha test function
void glAlphaFunc( GLenum func, GLclampf ref )
The alpha test discards fragments depending on the outcome of a comparison between the incoming fragment's alpha value and a constant reference value. glAlphaFunc specifies the reference and comparison function. The comparison is performed only if alpha testing is enabled. (See "glEnable" and "glDisable" of GL_ALPHA_TEST.)
func and ref specify the conditions under which the pixel is drawn. The incoming alpha value is compared to ref using the function specified by func. If the comparison passes, the incoming fragment is drawn, conditional on subsequent stencil and depth buffer tests. If the comparison fails, no change is made to the frame buffer at that pixel location.
The comparison functions are as follows:
glAlphaFunc operates on all pixel writes, including those resulting from the scan conversion of points, lines, polygons, and bitmaps, and from pixel draw and copy operations. glAlphaFunc does not affect screen clear operations.
Alpha testing is done only in RGBA mode.
GL_INVALID_ENUM is generated if func is not an accepted value.
GL_INVALID_OPERATION is generated if glAlphaFunc is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_ALPHA_TEST_FUNC
glGet with argument GL_ALPHA_TEST_REF
glIsEnabled with argument GL_ALPHA_TEST
"glBlendFunc", "glClear", "glDepthFunc", "glEnable", "glStencilFunc"
glAreTexturesResident - determine if textures are loaded in texture memory
GLboolean glAreTexturesResident( GLsizei n, const GLuint *textures, GLboolean *residences )
On machines with a limited amount of texture memory, OpenGL 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.
The glAreTexturesResident subroutine queries the texture residence status of the n textures named by the elements of textures. If all the named textures are resident, glAreTexturesResident returns GL_TRUE and the contents of residences are undisturbed. If not all the named textures are resident, glAreTexturesResidentreturns GL_FALSE and detailed status is returned in the n elements of residences. If an element of residencesis GL_TRUE, then the texture named by the corresponding element of textures is resident.
The residence status of a single bound texture may also be queried by calling glGetTexParameter with the target argument set to the target to which the texture is bound, and the parameter name argument set to GL_TEXTURE_RESIDENT. This is the only way that the residence status of a default texture can be queried.
The glAreTexturesResident subroutine is not included in display lists.
The glAreTexturesResident subroutine is available only if the GL version is 1.1 or greater.
The glAreTexturesResident subroutine returns the residency status of the textures at the time of invocation. It does not guarantee that the textures will remain resident at any other time.
If textures live in virtual memory (there is no texture memory) they are considered always resident.
GL_INVALID_VALUE is generated if n is negative.
GL_INVALID_VALUE is generated if any element in textures is zero or does not name a texture. In that case, the function returns GL_FALSE and the contents of residences is indeterminate.
GL_INVALID_OPERATION is generated if glAreTexturesResident is executed between the execution of glBegin and the corresponding execution of glEnd.
glGetTexParameter with argument GL_TEXTURE_RESIDENT
"glBindTexture", "glPrioritizeTextures", "glTexImage1D", "glTexImage2D", "glTexParameter"
glArrayElement - render a vertex using the specified vertex array element
void glArrayElement( GLint i )
The glArrayElement commands are used within glBegin/glEnd pairs to specify vertex and attribute data for point, line, and polygon primitives. If GL_VERTEX_ARRAY is enabled when glArrayElement is called, a single vertex is drawn, using vertex and attribute data taken from location i of the enabled arrays. If GL_VERTEX_ARRAY is not enabled, no drawing occurs but the attributes corresponding to the enabled arrays are modified.
Use glArrayElement to construct primitives by indexing vertex data, rather than by streaming through arrays of data in first-to-last order. Because each call specifies only a single vertex, it is possible to explicitly specify per- primitive attributes, such as a single normal per individual triangle.
Changes made to array data between the execution of glBegin and the corresponding execution of glEnd may affect calls to glArrayElement that are made within the same glBegin/glEnd period in non-sequential ways. That is, a call to glArrayElement that precedes a change to array data may access the changed data, and a call that follows a change to array data may access original data.
The glArrayElement subroutine is available only if the GL version is 1.1 or greater.
The glArrayElement subroutine is included in display lists. If glArrayElement is entered into a display list, the necessary array data (determined by the array pointers and enables) is also entered into the display list. Because the array pointers and enables are client side state, their values affect display lists when the lists are created, not when the lists are executed.
"glColorPointer", "glDrawArrays", "glEdgeFlagPointer", "glGetPointerv", "glIndexPointer", "glNormalPointer", "glVertexPointer"
glBegin, glEnd - delimit the vertices of a primitive or a group of like primitives
void glBegin( GLenum mode )
void glEnd( void )
glBegin and glEnd delimit the vertices that define a primitive or a group of like primitives. glBegin accepts a single argument that specifies which of ten ways the vertices are interpreted. Taking n as an integer count starting at one, and N as the total number of vertices specified, the interpretations are as follows:
Only a subset of GL commands can be used between glBegin and glEnd. The commands are glVertex, glColor, glIndex, glNormal, glTexCoord, glEvalCoord, glEvalPoint, glMaterial, and glEdgeFlag. Also, it is acceptable to use glCallList or glCallLists to execute display lists that include only the preceding commands. If any other GL command is called between glBegin and glEnd, the error flag is set and the command is ignored.
Regardless of the value chosen for mode, there is no limit to the number of vertices that can be defined between glBegin and glEnd. Lines, triangles, quadrilaterals, and polygons that are incompletely specified are not drawn. Incomplete specification results when either too few vertices are provided to specify even a single primitive or when an incorrect multiple of vertices is specified. The incomplete primitive is ignored; the rest are drawn.
The minimum specification of vertices for each primitive is as follows: 1 for a point, 2 for a line, 3 for a triangle, 4 for a quadrilateral, and 3 for a polygon. Modes that require a certain multiple of vertices are GL_LINES (2), GL_TRIANGLES (3), GL_QUADS (4), and GL_QUAD_STRIP (2).
GL_INVALID_ENUM is generated if mode is set to an unaccepted value.
GL_INVALID_OPERATION is generated if a command other than glVertex, glColor, glIndex, glNormal, glTexCoord, glEvalCoord, glEvalPoint, glMaterial, glEdgeFlag, glCallList, or glCallLists is called between glBegin and the corresponding glEnd.
GL_INVALID_OPERATION is generated if glEnd is called before the corresponding glBegin is called, or if glBegin is called within a glBegin/glEnd sequence.
"glCallList", "glCallLists", "glColor", "glEdgeFlag", "glEvalCoord", "glEvalPoint", "glIndex", "glMaterial", "glNormal", "glTexCoord", "glVertex"
glBindTexture - bind a named texture to a texturing target
void glBindTexture( GLenum target, GLuint texture )
The glBindTexture subroutine lets you create or use a named texture. Calling glBindTexture with target set to GL_TEXTURE_1D, GL_TEXTURE_2D, GL_TEXTURE_3D, or GL_TEXTURE_3D_EXT and texture set to the name of the new texture binds the texture name to the target. When a texture is bound to a target, the previous binding for that target is automatically broken.
Texture names are unsigned integers. The value zero is reserved to represent the default texture for each texture target. Texture names and the corresponding texture contents are local to the shared display-list space (see glXCreateContext) of the current GL rendering context; two rendering contexts share texture names only if they also share display lists.
You can use glGenTextures to generate a set of new texture names.
When a texture is first bound, it assumes the dimensionality of its target: A texture first bound to GL_TEXTURE_1D becomes one-dimensional (1D), a texture first bound to GL_TEXTURE_2D becomes two-dimensional (2D), a texture first bound to GL_TEXTURE_3D becomes three-dimensional (3D), a texture first bound to GL_TEXTURE_3D_EXT becomes three-dimensional (3D). The state of a (1D) texture immediately after it is first bound is equivalent to the state of the default GL_TEXTURE_1D at GL initialization, and similarly for 2D and 3D textures.
While a texture is bound, GL operations on the target to which it is bound affect the bound texture, and queries of the target to which it is bound return state from the bound texture. If texture mapping of the dimensionality of the target to which a texture is bound is active, the bound texture is used. In effect, the texture targets become aliases for the textures currently bound to them, and the texture name zero refers to the default textures that were bound to them at initialization.
A texture binding created with glBindTexture remains active until a different texture is bound to the same target, or until the bound texture is deleted with glDeleteTextures.
Once created, a named texture may be rebound to the target of the matching dimensionality as often as needed. It is usually much faster to use glBindTexture to bind an existing named texture to one of the texture targets than it is to reload the texture image using glTexImage1D or glTexImage2D. For additional control over performance, use glPrioritizeTextures.
The glBindTexture subroutine is included in display lists.
GL_INVALID_ENUM is generated if target is not one of the allowable values.
GL_INVALID_OPERATION is generated if texture has a dimensionality which doesn't match that of target.
GL_INVALID_OPERATION is generated if glBindTexture is executed between the execution of glBegin and the corresponding execution of glEnd.
glGet with argument GL_TEXTURE_1D_BINDING
glGet with argument GL_TEXTURE_2D_BINDING
glGet with argument GL_TEXTURE_3D_BINDING
glGet with argument GL_TEXTURE_3D_BINDING_EXT
"glAreTexturesResident", "glDeleteTextures", "glGenTextures", "glGet", "glGetTexParameter", "glIsTexture", "glPrioritizeTextures", "glTexImage1D", "glTexImage2D", "glTexParameter"
glBitmap - draw a bitmap
void glBitmap( GLsizei width, GLsizei height, GLfloat xorig, GLfloat yorig, GLfloat xmove, GLfloat ymove, const GLubyte *bitmap )
A bitmap is a binary image. When drawn, the bitmap is positioned relative to the current raster position, and frame buffer pixels corresponding to ones in the bitmap are written using the current raster color or index. Frame buffer pixels corresponding to zeros in the bitmap are not modified.
glBitmap takes seven arguments. The first pair specify the width and height of the bitmap image. The second pair specify the location of the bitmap origin relative to the lower left corner of the bitmap image. The third pair of arguments specify x and y offsets to be added to the current raster position after the bitmap has been drawn. The final argument is a pointer to the bitmap image itself.
The bitmap image is interpreted like image data for the glDrawPixels command, with width and height corresponding to the width and height arguments of that command, and with type set to GL_BITMAP and format set to GL_COLOR_INDEX. Modes specified using glPixelStore affect the interpretation of bitmap image data; modes specified using glPixelTransfer do not.
If the current raster position is invalid, glBitmap is ignored. Otherwise, the lower left corner of the bitmap image is positioned at the window coordinates
where ( xr , yr ) is the raster position and ( xo , yo ) is the bitmap origin. Fragments are then generated for each pixel corresponding to a one in the bitmap image. These fragments are generated using the current raster z coordinate, color or color index, and current raster texture coordinates. They are then treated just as if they had been generated by a point, line, or polygon, including texture mapping, fogging, and all per-fragment operations such as alpha and depth testing.
After the bitmap has been drawn, the x and y coordinates of the current raster position are offset by xmove and ymove. No change is made to the z coordinate of the current raster position, or to the current raster color, index, or texture coordinates.
GL_INVALID_VALUE is generated if width or height is negative.
GL_INVALID_OPERATION is generated if glBitmap is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_CURRENT_RASTER_POSITION
glGet with argument GL_CURRENT_RASTER_COLOR
glGet with argument GL_CURRENT_RASTER_INDEX
glGet with argument GL_CURRENT_RASTER_TEXTURE_COORDS
glGet with argument GL_CURRENT_RASTER_POSITION_VALID
"glDrawPixels", "glRasterPos", "glPixelStore", "glPixelTransfer"
glBlendFunc - specify pixel arithmetic
void glBlendFunc( GLenum sfactor, GLenum dfactor )
In RGB mode, pixels can be drawn using a function that blends the incoming (source) RGBA values with the RGBA values that are already in the frame buffer (the destination values). By default, blending is disabled. Use glEnable and glDisable with argument GL_BLEND to enable and disable blending.
glBlendFunc defines the operation of blending when it is enabled. sfactor specifies which of nine methods is used to scale the source color components. dfactor specifies which of eight methods is used to scale the destination color components. The eleven possible methods are described in the table below. Each method defines four scale factors, one each for red, green, blue, and alpha.
In the table and in subsequent equations, source and destination color components are referred to as (Rs , Gs , Bs , As ) and (Rd , Gd , Bd , Ad ). They are understood to have integer values between zero and (kR , kG , kB , kA ), where
and (mR , mG , mB , mA ) is the number of red, green, blue, and alpha bitplanes.
Source and destination scale factors are referred to as (sR , sG , sB , sA ) and (dR , dG , dB , dA ). The scale factors described in the table, denoted (fR , fG , fB , fA ), represent either source or destination factors. All scale factors have range [0,1].
| parameter | (fR , fG , fB , fA ) |
|---|---|
GL_ZERO |
(0, 0, 0, 0 ) |
GL_ONE |
(1, 1, 1, 1 ) |
GL_SRC_COLOR |
(Rs / kR , Gs / kG , Bs / kB , As / kA ) |
GL_ONE_MINUS_SRC_COLOR |
(1, 1, 1, 1 ) - (Rs / kR , Gs / kG , Bs / kB , As / kA) |
GL_DST_COLOR |
(Rd / kR , Gd / kG , Bd / kB , Ad / kA) |
GL_ONE_MINUS_DST_COLOR |
(1, 1, 1, 1 ) - (Rd / kR , Gd / kG , Bd / kB , Ad / kA ) |
GL_SRC_ALPHA |
(As / kA , As / kA , As / kA , As / kA ) |
GL_ONE_MINUS_SRC_ALPHA |
(1, 1, 1, 1 ) - (As / kA , As / kA , As / kA , As / kA) |
GL_DST_ALPHA |
(Ad / kA , Ad / kA , Ad / kA , Ad / kA) |
GL_ONE_MINUS_DST_ALPHA |
(1, 1, 1, 1 ) - (Ad / kA , Ad / kA , Ad / kA , Ad / kA) |
GL_SRC_ALPHA_SATURATE |
(i, i, i, 1 ) |
In the table,
i = min (As , kA - Ad ) / kA
To determine the blended RGBA values of a pixel when drawing in RGB mode, the system uses the following equations:
Rd = min ( kR , Rs sR + Rd dR )
Gd = min ( kG , Gs sG + Gd dG )
Bd = min ( kB , Bs sB + Bd dB )
Ad = min ( kA , As sA + Ad dA )
Despite the apparent precision of the above equations, blending arithmetic is not exactly specified, because blending operates with imprecise integer color values. However, a blend factor that should be equal to one is guaranteed not to modify its multiplicand, and a blend factor equal to zero reduces its multiplicand to zero. Thus, for example, when sfactor is GL_SRC_ALPHA, dfactor is GL_ONE_MINUS_SRC_ALPHA, and As is equal to kA, the equations reduce to simple replacement:
Rd = Rs
Gd = Gs
Bd = Bs
Ad = As
Transparency is best implemented using blend function (GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA) with primitives sorted from farthest to nearest. Note that this transparency calculation does not require the presence of alpha bitplanes in the frame buffer.
Blend function (GL_SRC_ALPHA, GL_ONE_MINUS_SRC_ALPHA) is also useful for rendering antialiased points and lines in arbitrary order.
Polygon antialiasing is optimized using blend function (GL_SRC_ALPHA_SATURATE, GL_ONE) with polygons sorted from nearest to farthest. (See the "glEnable", "glDisable" reference page and the GL_POLYGON_SMOOTH argument for information on polygon antialiasing.) Destination alpha bitplanes, which must be present for this blend function to operate correctly, store the accumulated coverage.
Incoming (source) alpha is correctly thought of as a material opacity, ranging from 1.0 (KA), representing complete opacity, to 0.0 (0), representing completely transparency.
When more than one color buffer is enabled for drawing, blending is done separately for each enabled buffer, using for destination color the contents of that buffer. (See "glDrawBuffer").
Blending affects only RGB rendering. It is ignored by color index renderers.
GL_INVALID_ENUM is generated if either sfactor or dfactor is not an accepted value.
GL_INVALID_OPERATION is generated if glBlendFunc is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_BLEND_SRC
glGet with argument GL_BLEND_DST
glIsEnabled with argument GL_BLEND
"glAlphaFunc", "glClear", "glDrawBuffer", "glEnable", "glLogicOp", "glStencilFunc"
glCallList - execute a display list
void glCallList( GLuint list )
glCallList causes the named display list to be executed. The commands saved in the display list are executed in order, just as if they were called without using a display list. If list has not been defined as a display list, glCallList is ignored.
glCallList can appear inside a display list. To avoid the possibility of infinite recursion resulting from display lists calling one another, a limit is placed on the nesting level of display lists during display-list execution. This limit is at least 64, and it depends on the implementation.
GL state is not saved and restored across a call to glCallList. Thus, changes made to GL state during the execution of a display list remain after execution of the display list is completed. Use glPushAttrib, glPopAttrib, glPushMatrix, and glPopMatrix to preserve GL state across glCallList calls.
Display lists can be executed between a call to glBegin and the corresponding call to glEnd, as long as the display list includes only commands that are allowed in this interval.
glGet with argument GL_MAX_LIST_NESTING
glIsList
"glCallLists", "glDeleteLists", "glGenLists", "glNewList", "glPushAttrib", "glPushMatrix"
glCallLists - execute a list of display lists
void glCallLists( GLsizei n, GLenum type, const GLvoid *lists )
glCallLists causes each display list in the list of names passed as lists to be executed. As a result, the commands saved in each display list are executed in order, just as if they were called without using a display list. Names of display lists that have not been defined are ignored.
glCallLists provides an efficient means for executing display lists. n allows lists with various name formats to be accepted. The formats are as follows:
The list of display list names is not null-terminated. Rather, n specifies how many names are to be taken from lists.
An additional level of indirection is made available with the glListBase command, which specifies an unsigned offset that is added to each display-list name specified in lists before that display list is executed.
glCallLists can appear inside a display list. To avoid the possibility of infinite recursion resulting from display lists calling one another, a limit is placed on the nesting level of display lists during display-list execution. This limit must be at least 64, and it depends on the implementation.
GL state is not saved and restored across a call to glCallLists. Thus, changes made to GL state during the execution of the display lists remain after execution is completed. Use glPushAttrib, glPopAttrib, glPushMatrix, and glPopMatrix to preserve GL state across glCallLists calls.
Display lists can be executed between a call to glBegin and the corresponding call to glEnd, as long as the display list includes only commands that are allowed in this interval.
glGet with argument GL_LIST_BASE
glGet with argument GL_MAX_LIST_NESTING
glIsList
"glCallList", "glDeleteLists", "glGenLists", "glListBase", "glNewList", "glPushAttrib", "glPushMatrix"
glClear - clear buffers within the viewport
void glClear( GLbitfield mask )
glClear sets the bitplane area of the window to values previously selected by glClearColor, glClearIndex, glClearDepth, glClearStencil, and glClearAccum. Multiple color buffers can be cleared simultaneously by selecting more than one buffer at a time using glDrawBuffer.
The pixel ownership test, the scissor test, dithering, and the buffer writemasks affect the operation of glClear. The scissor box bounds the cleared region. Alpha function, blend function, logical operation, stenciling, texture mapping, and z-buffering are ignored by glClear.
glClear takes a single argument that is the bitwise OR of several values indicating which buffer is to be cleared.
The values are as follows:
The value to which each buffer is cleared depends on the setting of the clear value for that buffer.
If a buffer is not present, then a glClear directed at that buffer has no effect.
GL_INVALID_VALUE is generated if any bit other than the four defined bits is set in mask.
GL_INVALID_OPERATION is generated if glClear is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_ACCUM_CLEAR_VALUE
glGet with argument GL_DEPTH_CLEAR_VALUE
glGet with argument GL_INDEX_CLEAR_VALUE
glGet with argument GL_COLOR_CLEAR_VALUE
glGet with argument GL_STENCIL_CLEAR_VALUE
"glClearAccum", "glClearColor", "glClearDepth", "glClearIndex", "glClearStencil", "glDrawBuffer", "glScissor"
glClearAccum - specify clear values for the accumulation buffer
void glClearAccum( GLfloat red, GLfloat green, GLfloat blue, GLfloat alpha )
glClearAccum specifies the red, green, blue, and alpha values used by glClear to clear the accumulation buffer.
Values specified by glClearAccum are clamped to the range [-1,1].
GL_INVALID_OPERATION is generated if glClearAccum is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_ACCUM_CLEAR_VALUE
glClearColor - specify clear values for the color buffers
void glClearColor( GLclampf red, GLclampf green, GLclampf blue, GLclampf alpha )
glClearColor specifies the red, green, blue, and alpha values used by glClear to clear the color buffers. Values specified by glClearColor are clamped to the range [0,1].
GL_INVALID_OPERATION is generated if glClearColor is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_COLOR_CLEAR_VALUE
glClearDepth - specify the clear value for the depth buffer
void glClearDepth( GLclampd depth )
glClearDepth specifies the depth value used by glClear to clear the depth buffer. Values specified by glClearDepth are clamped to the range [0,1].
GL_INVALID_OPERATION is generated if glClearDepth is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_DEPTH_CLEAR_VALUE
glClearIndex - specify the clear value for the color index buffers
void glClearIndex( GLfloat c )
glClearIndex specifies the index used by glClear to clear the color index buffers. c is not clamped. Rather, c is converted to a fixed-point value with unspecified precision to the right of the binary point. The integer part of this value is then masked with 2m -1, where m is the number of bits in a color index stored in the frame buffer.
GL_INVALID_OPERATION is generated if glClearIndex is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_INDEX_CLEAR_VALUE
glGet with argument GL_INDEX_BITS
glClearStencil - specify the clear value for the stencil buffer
void glClearStencil( GLint s )
glClearStencil specifies the index used by glClear to clear the stencil buffer. s is masked with 2m - 1, where m is the number of bits in the stencil buffer.
GL_INVALID_OPERATION is generated if glClearStencil is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_STENCIL_CLEAR_VALUE
glGet with argument GL_STENCIL_BITS
glClipPlane - specify a plane against which all geometry is clipped
void glClipPlane( GLenum plane, const GLdouble *equation )
Geometry is always clipped against the boundaries of a six-plane frustum in x, y, and z. glClipPlane allows the specification of additional planes, not necessarily perpendicular to the x, y, or z axis, against which all geometry is clipped. Up to GL_MAX_CLIP_PLANES planes can be specified, where GL_MAX_CLIP_PLANES is at least six in all implementations. Because the resulting clipping region is the intersection of the defined half-spaces, it is always convex.
glClipPlane specifies a half-space using a four-component plane equation. When glClipPlane is called, equation is transformed by the inverse of the modelview matrix and stored in the resulting eye coordinates. Subsequent changes to the modelview matrix have no effect on the stored plane-equation components. If the dot product of the eye coordinates of a vertex with the stored plane equation components is positive or zero, the vertex is in with respect to that clipping plane. Otherwise, it is out.
Clipping planes are enabled and disabled with glEnable and glDisable, and called with the argument GL_CLIP_PLANEi, where i is the plane number.
By default, all clipping planes are defined as (0,0,0,0) in eye coordinates and are disabled.
It is always the case that GL_CLIP_PLANEi = GL_CLIP_PLANE0 + i.
GL_INVALID_ENUM is generated if plane is not an accepted value.
GL_INVALID_OPERATION is generated if glClipPlane is called between a call to glBegin and the corresponding call to glEnd.
glGetClipPlane
glIsEnabled with argument GL_CLIP_PLANEi
glColor3b, glColor3d, glColor3f, glColor3i, glColor3s, glColor3ub, glColor3ui, glColor3us, glColor4b, glColor4d, glColor4f, glColor4i, glColor4s, glColor4ub, glColor4ui, glColor4us, glColor3bv, glColor3dv, glColor3fv, glColor3iv, glColor3sv, glColor3ubv, glColor3uiv, glColor3usv, glColor4bv, glColor4dv, glColor4fv, glColor4iv, glColor4sv, glColor4ubv, glColor4uiv, glColor4usv - set the current color
void glColor3b( GLbyte red, GLbyte green, GLbyte blue )
void glColor3d( GLdouble red, GLdouble green, GLdouble blue )
void glColor3f( GLfloat red, GLfloat green, GLfloat blue )
void glColor3i( GLint red, GLint green, GLint blue )
void glColor3s( GLshort red, GLshort green, GLshort blue )
void glColor3ub( GLubyte red, GLubyte green, GLubyte blue )
void glColor3ui( GLuint red, GLuint green, GLuint blue )
void glColor3us( GLushort red, GLushort green, GLushort blue )
void glColor4b( GLbyte red, GLbyte green, GLbyte blue,
GLbyte alpha )
void glColor4d( GLdouble red, GLdouble green, GLdouble blue,
GLdouble alpha )
void glColor4f( GLfloat red, GLfloat green, GLfloat blue,
GLfloat alpha )
void glColor4i( GLint red, GLint green, GLint blue,
GLint alpha )
void glColor4s( GLshort red, GLshort green, GLshort blue,
GLshort alpha )
void glColor4ub( GLubyte red, GLubyte green, GLubyte blue,
GLubyte alpha )
void glColor4ui( GLuint red, GLuint green, GLuint blue,
GLuint alpha )
void glColor4us( GLushort red, GLushort green, GLushort blue,
GLushort alpha )
void glColor3bv( const GLbyte *v )
void glColor3dv( const GLdouble *v )
void glColor3fv( const GLfloat *v )
void glColor3iv( const GLint *v )
void glColor3sv( const GLshort *v )
void glColor3ubv( const GLubyte *v )
void glColor3uiv( const GLuint *v )
void glColor3usv( const GLushort *v )
void glColor4bv( const GLbyte *v )
void glColor4dv( const GLdouble *v )
void glColor4fv( const GLfloat *v )
void glColor4iv( const GLint *v )
void glColor4sv( const GLshort *v )
void glColor4ubv( const GLubyte *v )
void glColor4uiv( const GLuint *v )
void glColor4usv( const GLushort *v )
The GL stores both a current single-valued color index and a current four-valued RGBA color. glColor sets a new four-valued RGBA color. glColor has two major variants: glColor3 and glColor4. glColor3 variants specify new red, green, and blue values explicitly, and set the current alpha value to 1.0 implicitly. glColor4 variants specify all four color components explicitly.
glColor3b, glColor4b, glColor3s, glColor4s, glColor3i, and glColor4i take three or four unsigned 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.
Current 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 zero 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. Floating-point values are mapped directly.
Neither floating-point nor signed integer values are clamped to the range [0,1] before updating the current color. However, color components are clamped to this range before they are interpolated or written into a color buffer.
The current color can be updated at any time. In particular, glColor can be called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_CURRENT_COLOR
glGet with argument GL_RGBA_MODE
glColorMask - enable and disable writing of frame buffer color components
void glColorMask( GLboolean red, GLboolean green, GLboolean blue, GLboolean alpha )
glColorMask specifies whether the individual color components in the frame buffer can or cannot be written. If red is GL_FALSE, for example, no change is made to the red component of any pixel in any of the color buffers, regardless of the drawing operation attempted.
Changes to individual bits of components cannot be controlled. Rather, changes are either enabled or disabled for entire color components.
GL_INVALID_OPERATION is generated if glColorMask is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_COLOR_WRITEMASK
glGet with argument GL_RGBA_MODE
"glColor", "glIndex", "glIndexMask", "glDepthMask", "glStencilMask"
glColorMaterial - cause a material color to track the current color
void glColorMaterial( GLenum face, GLenum mode )
glColorMaterial specifies which material parameters track the current color. When GL_COLOR_MATERIAL is enabled, the material parameter or parameters specified by mode, of the material or materials specified by face, track the current color at all times. GL_COLOR_MATERIAL is enabled and disabled using the commands glEnable and glDisable, called with GL_COLOR_MATERIAL as their argument. By default, it is disabled.
glColorMaterial allows a subset of material parameters to be changed for each vertex using only the glColor command, without calling glMaterial. If only such a subset of parameters is to be specified for each vertex, glColorMaterial is preferred over calling glMaterial.
GL_INVALID_ENUM is generated if face or mode is not an accepted value.
GL_INVALID_OPERATION is generated if glColorMaterial is called between a call to glBegin and the corresponding call to glEnd.
glIsEnabled with argument GL_COLOR_MATERIAL
glGet with argument GL_COLOR_MATERIAL_PARAMETER
glGet with argument GL_COLOR_MATERIAL_FACE
"glColor", "glEnable", "glLight", "glLightModel", "glMaterial"
glColorPointer - define an array of colors
void glColorPointer( GLint size, GLenum type, GLsizei stride, const GLvoid *pointer )
The glColorPointer subroutine specifies the location and data format of an array of color components to use when rendering. The size parameter specifies the number of components per color, and must be 3 or 4. The type parameter specifies the data type of each color component and stride gives the byte stride from one color to the next allowing vertexes 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).
When a color array is specified, size, type, stride, and pointer are saved as client side state.
To enable and disable the color array, call glEnableClientState and glDisableClientState with the argument GL_COLOR_ARRAY. If enabled, the color array is used when glDrawArrays, glDrawElements or glArrayElement is called.
Use glDrawArrays to draw a sequence of elements (all of the same type) from prespecified vertex and vertex attribute arrays. Use glDrawElements to draw nonsequential elements from prespecified arrays. Use glArrayElement to draw individual elements.
The glColorPointer subroutine is available only if the GL version is 1.1 or greater.
The color array is initially disabled and it won't be accessed when glArrayElement, glDrawElements, or glDrawArrays is called.
Execution of glColorPointer 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.
The glColorPointer subroutine is typically implemented on the client side with no protocol.
Since the color array parameters are client side state, they are not saved or restored by glPushAttrib and glPopAttrib. Use glPushClientAttrib and glPopClientAttrib instead.
The glColorPointer commands are not included in display lists.
GL_INVALID_VALUE is generated if size is not 3 or 4.
GL_INVALID_ENUM is generated if type is not an accepted value.
GL_INVALID_VALUE is generated if stride is negative.
glIsEnabled with argument GL_COLOR_ARRAY
glGet with argument GL_COLOR_ARRAY_SIZE
glGet with argument GL_COLOR_ARRAY_TYPE
glGet with argument GL_COLOR_ARRAY_STRIDE
glGetPointerv with argument GL_COLOR_ARRAY_POINTER
"glArrayElement", "glDrawArrays", "glDrawElements", "glEdgeFlagPointer", "glEnable", "glGetPointerv", "glIndexPointer", "glInterleavedArrays", "glNormalPointer", "glPopClientAttrib", "glPushClientAttrib", "glTexCoordPointer", "glVertexPointer"
glCopyPixels - copy pixels in the frame buffer
void glCopyPixels( GLint x, GLint y, GLsizei width, GLsizei height, GLenum type )
glCopyPixels copies a screen-aligned rectangle of pixels from the specified frame buffer location to a region relative to the current raster position. Its operation is well defined only if the entire pixel source region is within the exposed portion of the window. Results of copies from outside the window, or from regions of the window that are not exposed, are hardware dependent and undefined.
x and y specify the window coordinates of the lower left corner of the rectangular region to be copied. width and height specify the dimensions of the rectangular region to be copied. Both width and height must not be negative.
Several parameters control the processing of the pixel data while it is being copied. These parameters are set with three commands: glPixelTransfer, glPixelMap, and glPixelZoom. This reference page describes the effects on glCopyPixels of most, but not all, of the parameters specified by these three commands.
glCopyPixels copies values from each pixel with the lower left-hand 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 copied in row order from the lowest to the highest row, left to right in each row.
type specifies whether color, depth, or stencil data is to be copied. The details of the transfer for each data type are as follows:
The rasterization described thus far assumes pixel zoom factors of 1.0. If glPixelZoom is used to change the x and y pixel zoom factors, pixels are converted to fragments as follows. If (xr, yr) is the current raster position, and a given pixel is in the ith location in the jth row of the source pixel rectangle, then fragments are generated for pixels whose centers are in the rectangle with corners at
(xr + zoomx i, yr + zoomy j)
and
(xr + zoomx (i + 1), yr + zoomy ( j + 1 ))
where zoomx is the value of GL_ZOOM_X and zoomy is the value of GL_ZOOM_Y.
To copy the color pixel in the lower left corner of the window to the current raster position, use
glCopyPixels(0, 0, 1, 1, GL_COLOR);
Modes specified by glPixelStore have no effect on the operation of glCopyPixels.
GL_INVALID_ENUM is generated if type is not an accepted value.
GL_INVALID_VALUE is generated if either width or height is negative.
GL_INVALID_OPERATION is generated if type is GL_DEPTH and there is no depth buffer.
GL_INVALID_OPERATION is generated if type is GL_STENCIL and there is no stencil buffer.
GL_INVALID_OPERATION is generated if glCopyPixels is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_CURRENT_RASTER_POSITION
glGet with argument GL_CURRENT_RASTER_POSITION_VALID
"glDepthFunc", "glDrawBuffer", "glDrawPixels", "glPixelMap", "glPixelTransfer", "glPixelZoom", "glRasterPos", "glReadBuffer", "glReadPixels", "glStencilFunc"
glCopyTexImage1D - define a one-dimensional (1D) texture image
void glCopyTexImage1D( GLenum target, GLint level, GLenum internalFormat, GLint xCoordinate, GLint yCoordinate, GLsizei width, GLint border )
The glCopyTexImage1D subroutine defines a one dimensional texture image with pixels from the current GL_READ_BUFFER.
The screen aligned pixel row with left corner at (x,y) and with a length of width + 2 * border defines the texture array at the mipmap level specified by level. internalFormat specifies the internal format of the texture array.
The pixels in the row are processed exactly as if glCopyPixels had been called, but the process stops just before final conversion. At this point all pixel component values are clamped to the range [0, 1] and then converted to the texture's internal format for storage in the texel array.
Pixel ordering is such that lower x screen coordinates correspond to lower texture coordinates.
If any of the pixels within the specified row of the current GL_READ_BUFFER are outside the window associated with the current rendering context, then the values obtained for those pixels are undefined.
The glCopyTexImage1D subroutine is available only if the GL version is 1.1 or greater.
1, 2, 3, or 4 are not accepted values for internalFormat.
An image with zero width indicates a null texture.
GL_INVALID_ENUM is generated if target is not one of the allowable values.
GL_INVALID_VALUE is generated if level is less than zero.
GL_INVALID_VALUE may be generated if level is greater than log2max, where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE is generated if border is not 0 or 1.
GL_INVALID_VALUE is generated if width is less than zero, greater than 2 + GL_MAX_TEXTURE_SIZE, or if width cannot be represented as 2**k+ 2 * border for some integer k.
GL_INVALID_VALUE is generated if width is less than zero or greater than 2 + GL_MAX_TEXTURE_SIZE, or if it cannot be represented as 2**n + 2 * border for some integer value of n.
GL_INVALID_OPERATION is generated if glCopyTexImage1D is executed between the execution of glBegin and the corresponding execution of glEnd.
glGetTexImage
glIsEnabled with argument GL_TEXTURE_1D
"glCopyTexImage2D", "glDrawPixels", "glFog", "glPixelStore", "glPixelTransfer", "glTexEnv", "glGetTexGen", "glTexGen", "glTexImage1D", "glTexParameter"
glCopyTexImage2D - define a two-dimensional (2D) texture image
void glCopyTexImage2D( GLenum target, GLint level, GLenum internalFormat, GLint xCoordinate, GLint yCoordinate, GLsizei width, GLsizei height, GLint border )
The glCopyTexImage2D subroutine defines a two-dimensional texture image with pixels from the current GL_READ_BUFFER.
The screen aligned pixel rectangle with lower left corner at (x, y) and with a width of width + 2 * border and height height + 2 * border defines the texture array at the mipmap level specified by level. internalFormat specifies the internal format of the texture array.
The pixels in the rectangle are processed exactly as if glCopyPixels had been called, but the process stops just before final conversion. At this point all pixel component values are clamped to the range [0.0,1.0] and then converted to the texture's internal format for storage in the texel array.
Pixel ordering is such that lower x and y screen coordinates correspond to lower s and t texture coordinates.
If any of the pixels within the specified rectangle of the current GL_READ_BUFFER are outside the window associated with the current rendering context, then the values obtained for those pixels are undefined.
The glCopyTexImage2D subroutine is available only if the GL version is 1.1 or greater.
1, 2, 3, or 4 are not accepted values for internalFormat.
An image with height or width of 0 indicates a NULL texture.
GL_INVALID_ENUM is generated if target is not GL_TEXTURE_2D.
GL_INVALID_VALUE is generated if level is less than zero.
GL_INVALID_VALUE may be generated if level is greater than log2max, where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE is generated if width or height is less than zero, greater than 2 + GL_MAX_TEXTURE_SIZE, or if width or height cannot be represented as 2**k + 2 * border for some integer k.
GL_INVALID_VALUE is generated if border is not 0 or 1.
GL_INVALID_VALUE is generated if internalFormat is not one of the allowable values.
GL_INVALID_OPERATION is generated if glCopyTexImage2D is executed between the execution of glBegin and the corresponding execution of glEnd.
glGetTexImage
glIsEnabled with argument GL_TEXTURE_2D
"glCopyPixels", "glCopyTexImage1D", "glPixelStore", "glPixelTransfer", "glTexEnv", "glTexImage2D", "glTexParameter"
glCopyTexSubImage1D - copy a one-dimensional (1D) texture subimage
void glCopyTexSubImage1D( GLenum target, GLint level, GLint xoffset, GLint xCoordinate, GLint yCoordinate, GLsizei width )
The glCopyTexSubImage1D subroutine replaces a portion of a one dimensional texture image with pixels from the current GL_READ_BUFFER (rather than from main memory, as is the case for glTexSubImage1D).
The screen aligned pixel row with left corner at (x, y), and with length width replaces the portion of the texture array with x indices xoffset through xoffset + width - 1, inclusive. The destination in the texture array may not include any texels outside the texture array as it was originally specified.
The pixels in the row are processed exactly as if glCopyPixels had been called, but the process stops just before final conversion. At this point all pixel component values are clamped to the range [0, 1] and then converted to the texture's internal format for storage in the texel array.
It is not an error to specify a subtexture with zero width, but such a specification has no effect. If any of the pixels within the specified row of the current GL_READ_BUFFER are outside the read window associated with the current rendering context, then the values obtained for those pixels are undefined.
No change is made to the internalFormat, width, or border parameters of the specified texture array or to texel values outside the specified subregion.
The glCopyTexSubImage1D subroutine is available only if the GL version is 1.1 or greater.
Texturing has no effect in color index mode.
The glPixelTransfer mode affects texture images in exactly the way they affect glDrawPixels.
GL_INVALID_ENUM is generated if target is not GL_TEXTURE_1D.
GL_INVALID_OPERATION is generated if the texture array has not been defined by a previous glTexImage1D operation.
GL_INVALID_VALUE is generated if width is less than zero.
GL_INVALID_VALUE may be generated if level > log2 max, where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE is generated if y < -b or if width < -b, where b is the border width of the texture array.
GL_INVALID_VALUE is generated if xoffset < -b, or (xoffset + width) > (w-b). Where w is the GL_TEXTURE_WIDTH, and b is the GL_TEXTURE_BORDER of the texture image being modified. Note that w includes twice the border width.
glGetTexImage
glIsEnabled with argument GL_TEXTURE_1D
"glCopyTexSubImage2D", "glDrawPixels", "glFog", "glPixelStore", "glPixelTransfer", "glTexEnv", "glGetTexGen", "glTexGen", "glTexImage1D", "glTexSubImage1D", "glTexParameter"
glCopyTexSubImage2D - copy a two-dimensional (2D) texture subimage
void glCopyTexSubImage2D( GLenum target, GLint level, GLint xoffset, GLint yoffset, GLint xCoordinate, GLint yCoordinate, GLsizei width, GLsizei height )
The glCopyTexSubImage2D subroutine replaces a portion of a two dimensional texture image with pixels from the current GL_READ_BUFFER (rather than from main memory, as is the case for glTexSubImage2D).
The screen aligned pixel rectangle with lower left corner at (x, y) and with width width and height height replaces the portion of the texture array with x indices xoffset through xoffset + width - 1, inclusive, and y indices yoffset through yoffset + height - 1, inclusive, at the mipmap level specified by level.
The pixels in the rectangle are processed exactly as if glCopyPixels had been called, but the process stops just before final conversion. At this point all pixel component values are clamped to the range [0, 1] and then converted to the texture's internal format for storage in the texel array.
The destination rectangle in the texture array may not include any texels outside the texture array as it was originally specified. It is not an error to specify a subtexture with zero width or height, but such a specification has no effect.
If any of the pixels within the specified rectangle of the current GL_READ_BUFFER are outside the read window associated with the current rendering context, then the values obtained for those pixels are undefined.
No change is made to the internalformat, width, height, or border parameters of the specified texture array or to texel values outside the specified subregion.
The glCopyTexSubImage2D subroutine is available only if the GL version is 1.1 or greater.
Texturing has no effect in color index mode.
The glPixelTransfer mode affects texture images in exactly the way they affect glDrawPixels.
GL_INVALID_ENUM is generated if target is not GL_TEXTURE_2D.
GL_INVALID_OPERATION is generated if the texture array has not been defined by a previous glTexImage2D operation.
GL_INVALID_VALUE is generated if level is less than zero.
GL_INVALID_VALUE may be generated if level is greater than log2max, where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE is generated if x < -b or if y < -b, where b is the border width of the texture array.
GL_INVALID_VALUE is generated if xoffset < -b, (xoffset + width) > (w - b), yoffset < -b, or (yoffset + height) > (h - b). Where w is the GL_TEXTURE_WIDTH, h is the GL_TEXTURE_HEIGHT, and b is the GL_TEXTURE_BORDER of the texture image being modified. Note that w and h include twice the border width.
GL_INVALID_OPERATION is generated if glCopyTexSubImage2D is executed between the execution of glBegin and the corresponding execution of glEnd.
glGetTexImage
glIsEnabled with argument GL_TEXTURE_2D
"glCopyTexImage2D", "glDrawPixels", "glFog", "glPixelStore", "glPixelTransfer", "glTexEnv", "glGetTexGen", "glTexGen", "glTexImage2D", "glTexParameter"
glCullFace - specify whether front- or back-facing facets can be culled
void glCullFace( GLenum mode )
glCullFace specifies whether front- or back-facing facets are culled (as specified by mode) when facet culling is enabled. Facet culling is enabled and disabled using the glEnable and glDisable commands with the argument GL_CULL_FACE. Facets include triangles, quadrilaterals, polygons, and rectangles.
glFrontFace specifies which of the clockwise and counterclockwise facets are front-facing and back-facing. See "glFrontFace".
GL_INVALID_ENUM is generated if mode is not an accepted value.
GL_INVALID_OPERATION is generated if glCullFace is called between a call to glBegin and the corresponding call to glEnd.
glIsEnabled with argument GL_CULL_FACE
glGet with argument GL_CULL_FACE_MODE
glDeleteLists - delete a contiguous group of display lists
void glDeleteLists( GLuint list, GLsizei range )
glDeleteLists causes a contiguous group of display lists to be deleted. list is the name of the first display list to be deleted, and range is the number of display lists to delete. All display lists d with list ≤ d ≤ list + range - 1 are deleted.
All storage locations allocated to the specified display lists are freed, and the names are available for reuse at a later time. Names within the range that do not have an associated display list are ignored. If range is zero, nothing happens.
GL_INVALID_VALUE is generated if range is negative.
GL_INVALID_OPERATION is generated if glDeleteLists is called between a call to glBegin and the corresponding call to glEnd.
"glCallList", "glCallLists", "glGenLists", "glIsList", "glNewList"
glDeleteTextures - delete named textures
void glDeleteTextures( GLsizei n, const GLuint *textures )
The glDeleteTextures subroutine deletes n textures named by the elements of the array textures. After a texture is deleted, it has no contents or dimensionality, and its name is free for reuse (for example by glGenTextures). If a texture that is currently bound is deleted, the binding reverts to 0 (the default texture).
The glDeleteTextures subroutine silently ignores zeros and names that do not correspond to existing textures.
The glDeleteTextures subroutine is available only if the GL version is 1.1 or greater.
The glDeleteTextures subroutine is not included in display lists.
GL_INVALID_VALUE is generated if n is negative.
GL_INVALID_OPERATION is generated if glDeleteTextures is executed between the execution of glBegin and the corresponding execution of glEnd.
"glAreTexturesResident", "glBindTexture", "glGenTextures", "glGet", "glGetTexParameter", "glPrioritizeTextures", "glTexImage1D", "glTexImage2D", "glTexParameter"
glDepthFunc - specify the value used for depth buffer comparisons
void glDepthFunc( GLenum func )
glDepthFunc specifies the function used to compare each incoming pixel z value with the z value present in the depth buffer. The comparison is performed only if depth testing is enabled. (See "glEnable" and "glDisable" of GL_DEPTH_TEST.)
func specifies the conditions under which the pixel will be drawn. The comparison functions are as follows:
The default value of func is GL_LESS. Initially, depth testing is disabled.
GL_INVALID_ENUM is generated if func is not an accepted value.
GL_INVALID_OPERATION is generated if glDepthFunc is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_DEPTH_FUNC
glIsEnabled with argument GL_DEPTH_TEST
glDepthMask - enable or disable writing into the depth buffer
void glDepthMask( GLboolean flag )
glDepthMask specifies whether the depth buffer is enabled for writing. If flag is zero, depth buffer writing is disabled. Otherwise, it is enabled. Initially, depth buffer writing is enabled.
GL_INVALID_OPERATION is generated if glDepthMask is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_DEPTH_WRITEMASK
"glColorMask", "glDepthFunc", "glDepthRange", "glIndexMask", "glStencilMask"
glDepthRange - specify the mapping of z values from normalized device coordinates to window coordinates
void glDepthRange( GLclampd near, GLclampd far )
After clipping and division by w, z coordinates range from -1.0 to 1.0, corresponding to the near and far clipping planes. glDepthRange specifies a linear mapping of the normalized z coordinates in this range to window z coordinates. Regardless of the actual depth buffer implementation, window coordinate depth values are treated as though they range from 0.0 through 1.0 (like color components). Thus, the values accepted by glDepthRange are both clamped to this range before they are accepted.
The default mapping of 0,1 maps the near plane to 0 and the far plane to 1. With this mapping, the depth buffer range is fully utilized.
It is not necessary that near be less than far. Reverse mappings such as 1,0 are acceptable.
GL_INVALID_OPERATION is generated if glDepthRange is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_DEPTH_RANGE
glDrawArrays - render primitives from array data
void glDrawArrays( GLenum mode, GLint first, GLsizei count )
The glDrawArrays subroutine lets you specify multiple geometric primitives with very few subroutine calls. Instead of calling a GL procedure to pass each individual vertex, normal, texture coordinate, edge flage, or color, you can prespecify separate arrays of vertexes, normals, and colors and use them to construct a sequence of primitives with a single call to glDrawArrays.
When glDrawArrays is called, it uses count sequential elements from each enabled array to construct a sequence of geometric primitives, beginning with element first. The mode parameter specifies what kind of primitives are constructed, and how the array elements construct these primitives. If GL_VERTEX_ARRAY is not enabled, no geometric primitives are generated.
Vertex attributes that are modified by glDrawArrays have an unspecified value after glDrawArrays returns. For example, if GL_COLOR_ARRAY is enabled, the value of the current color is undefined after glDrawArrays executes. Attributes that are not modified remain well defined.
The glDrawArrays subroutine is available only if the GL version is 1.1 or greater.
The glDrawArrays subroutine is included in display lists. If glDrawArrays is entered into a display list, the necessary array data (determined by the array pointers and enables) is also entered into the display list. Because the array pointers and enables are client side state, their values affect display lists when the lists are created, not when the lists are executed.
GL_INVALID_ENUM is generated if mode is not an accepted value.
GL_INVALID_VALUE is generated if count is negative.
GL_INVALID_OPERATION is generated if glDrawArrays is executed between the execution of glBegin and the corresponding glEnd.
"glArrayElement", "glColorPointer", "glDrawElements", "glEdgeFlagPointer", "glGetPointerv", "glIndexPointer", "glNormalPointer", "glTexCoordPointer", "glVertexPointer"
glDrawBuffer - specify which color buffers are to be drawn into
void glDrawBuffer( GLenum mode )
When colors are written to the frame buffer, they are written into the color buffers specified by glDrawBuffer. The specifications are as follows:
If more than one color buffer is selected for drawing, then blending or logical operations are computed and applied independently for each color buffer and can produce different results in each buffer.
Monoscopic contexts include only left buffers, and stereoscopic contexts include both left and right buffers. Likewise, single-buffered contexts include only front buffers, and double-buffered contexts include both front and back buffers. The context is selected at GL initialization.
It is always the case that GL_AUXi = GL_AUX0 + i.
GL_INVALID_ENUM is generated if mode is not an accepted value.
GL_INVALID_OPERATION is generated if none of the buffers indicated by mode exists.
GL_INVALID_OPERATION is generated if glDrawBuffer is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_DRAW_BUFFER
glGet with argument GL_AUX_BUFFERS
"glBlendFunc", "glColorMask", "glIndexMask", "glLogicOp"
glDrawElements - render primitives from array data
void glDrawElements( GLenum mode, GLsizei count, GLenum type, const GLvoid *indices )
The glDrawElements subroutine lets you specify multiple geometric primitives with very few subroutine calls. Instead of calling a GL function to pass each individual vertex, normal, texture coordinate, edge flage, or color, you can prespecify separate arrays of vertexes, normals, and so on and use them to construct a sequence of primitives with a single call to glDrawElements.
When glDrawElements is called, it uses count sequential elements from indices to construct a sequence of geometric primitives. GLenum mode specifies what kind of primitives are constructed and how the array elements construct these primitives. If GL_VERTEX_ARRAY is not enabled, no geometric primitives are generated.
Vertex attributes that are modified by glDrawElements have an unspecified value after glDrawElements returns. For example, if GL_COLOR_ARRAY is enabled, the value of the current color is undefined after glDrawElements executes. Attributes that are not modified remain well defined.
The glDrawElements subroutine is available only if the GL version is 1.1 or greater.
The glDrawElements subroutine is included in display lists. If glDrawElements is entered into a display list, the necessary array data (determined by the array pointers and enables) is also entered into the display list. Because the array pointers and enables are client side state, their values affect display lists when the lists are created, not when the lists are executed.
GL_INVALID_ENUM is generated if mode is not an accepted value.
GL_INVALID_VALUE is generated if count is negative.
GL_INVALID_OPERATION is generated if glDrawElements is executed between the execution of glBegin and the corresponding glEnd.
"glArrayElement", "glColorPointer", "glDrawArrays", "glEdgeFlagPointer", "glGetPointerv", "glIndexPointer", "glNormalPointer", "glTexCoordPointer", "glVertexPointer"
glDrawPixels - write a block of pixels to the frame buffer
void glDrawPixels( GLsizei width, GLsizei height, GLenum format, GLenum type, const GLvoid *pixels )
glDrawPixels reads pixel data from memory and writes it into the frame buffer relative to the current raster position. Use glRasterPos to set the current raster position, and use glGet with argument GL_CURRENT_RASTER_POSITION to query the raster position.
Several parameters define the encoding of pixel data in memory and control the processing of the pixel data before it is placed in the frame buffer. These parameters are set with four commands: glPixelStore, glPixelTransfer, glPixelMap, and glPixelZoom. This reference page describes the effects on glDrawPixels of many, but not all, of the parameters specified by these four commands.
Data is read from pixels as a sequence of signed or unsigned bytes, signed or unsigned shorts, signed or unsigned integers, or single-precision floating-point values, depending on type. Each of these bytes, shorts, integers, or floating-point values is interpreted as one color or depth component, or one index, depending on format. Indices are always treated individually. Color components are treated as groups of one, two, three, or four values, again based on format. Both individual indices and groups of components are referred to as pixels. If type is GL_BITMAP, the data must be unsigned bytes, and format must be either GL_COLOR_INDEX or GL_STENCIL_INDEX. Each unsigned byte is treated as eight 1-bit pixels, with bit ordering determined by GL_UNPACK_LSB_FIRST (see "glPixelStore").
widthxheight pixels are read from memory, starting at location pixels. By default, these pixels are taken from adjacent memory locations, except that after all width pixels are read, the read pointer is advanced to the next four-byte boundary. The four-byte row alignment is specified by glPixelStore with argument GL_UNPACK_ALIGNMENT, and it can be set to one, two, four, or eight bytes. Other pixel store parameters specify different read pointer advancements, both before the first pixel is read, and after all width pixels are read. Refer to the glPixelStore reference page for details on these options.
The widthxheight pixels that are read from memory are each operated on in the same way, based on the values of several parameters specified by glPixelTransfer and glPixelMap. The details of these operations, as well as the target buffer into which the pixels are drawn, are specific to the format of the pixels, as specified by format. format can assume one of eleven symbolic values:
The following table summarizes the meaning of the valid constants for the type parameter:
| type | corresponding type |
|---|---|
GL_UNSIGNED_BYTE |
unsigned 8-bit integer |
GL_BYTE |
signed 8-bit integer |
GL_BITMAP |
single bits in unsigned 8-bit integers |
GL_UNSIGNED_SHORT |
unsigned 16-bit integer |
GL_SHORT |
signed 16-bit integer |
GL_UNSIGNED_INT |
unsigned 32-bit integer |
GL_INT |
32-bit integer |
GL_FLOAT |
single-precision floating-point |
The rasterization described thus far assumes pixel zoom factors of 1.0. If glPixelZoom is used to change the x and y pixel zoom factors, pixels are converted to fragments as follows. If (xr, yr) is the current raster position, and a given pixel is in the nth column and mth row of the pixel rectangle, then fragments are generated for pixels whose centers are in the rectangle with corners at
(xr + zoomx n, yr + zoomy m)
(xr + zoomx (n + 1), yr + zoomy ( m + 1 ))
where zoomx is the value of GL_ZOOM_X and zoomy is the value of GL_ZOOM_Y.
GL_INVALID_VALUE is generated if either width or height is negative.
GL_INVALID_ENUM is generated if format or type is not one of the accepted values.
GL_INVALID_OPERATION is generated if format is GL_RED, GL_GREEN, GL_BLUE, GL_ALPHA, GL_RGB, GL_RGBA, GL_LUMINANCE, or GL_LUMINANCE_ALPHA, and the GL is in color index mode.
GL_INVALID_ENUM is generated if type is GL_BITMAP and format is not either GL_COLOR_INDEX or GL_STENCIL_INDEX.
GL_INVALID_OPERATION is generated if format is GL_STENCIL_INDEX and there is no stencil buffer.
GL_INVALID_OPERATION is generated if glDrawPixels is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_CURRENT_RASTER_POSITION
glGet with argument GL_CURRENT_RASTER_POSITION_VALID
"glAlphaFunc", "glBlendFunc", "glCopyPixels", "glDepthFunc", "glLogicOp", "glPixelMap", "glPixelStore", "glPixelTransfer", "glPixelZoom", "glRasterPos", "glReadPixels", "glScissor", "glStencilFunc"
glEdgeFlag, glEdgeFlagv - flag edges as either boundary or nonboundary
void glEdgeFlag( GLboolean flag )
void glEdgeFlagv( const GLboolean *flag )
Each vertex of a polygon, separate triangle, or separate quadrilateral specified between a glBegin/glEnd pair is marked as the start of either a boundary or nonboundary edge. If the current edge flag is true when the vertex is specified, the vertex is marked as the start of a boundary edge. Otherwise, the vertex is marked as the start of a nonboundary edge. glEdgeFlag sets the edge flag to true if flag is nonzero, false otherwise.
The vertices of connected triangles and connected quadrilaterals are always marked as boundary, regardless of the value of the edge flag.
Boundary and nonboundary edge flags on vertices are significant only if GL_POLYGON_MODE is set to GL_POINT or GL_LINE. See "glPolygonMode".
Initially, the edge flag bit is true.
The current edge flag can be updated at any time. In particular, glEdgeFlag can be called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_EDGE_FLAG
glEdgeFlagPointer - define an array of edge flags
void glEdgeFlagPointer( GLsizei stride, const GLvoid *pointer )
The glEdgeFlagPointer subroutine specifies the location and data format of an array of Boolean edge flags to use when rendering. The stride parameter gives the byte stride from one edge flag to the next allowing vertexes 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.)
When an edge flag array is specified, stride and pointer are saved as client side state.
To enable and disable the edge flag array, call glEnableClientState and glDisableClientState with the argument GL_EDGE_FLAG_ARRAY. If enabled, the edge flag array is used when glDrawArrays, glDrawElements or glArrayElement is called.
Use glDrawArrays to construct a sequence of primitives (all of the same type) from prespecified vertex and vertex attribute arrays. Use glArrayElement to specify primitives by indexing vertexes and vertex attributes and glDrawElements to construct a sequence of primitives by indexing vertexes and vertex attributes.
The glEdgeFlagPointer subroutine is available only if the GL version is 1.1 or greater.
The edge flag array is initially disabled and it won't be accessed when glArrayElement, glDrawElements, or glDrawArrays is called.
Execution of glEdgeFlagPointer 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.
The glEdgeFlagPointer subroutine is typically implemented on the client side with no protocol.
Since the edge flag array parameters are client side state, they are not saved or restored by glPushAttrib and glPopAttrib. Use glPushClientAttrib and glPopClientAttrib instead.
The glEdgeFlagPointer subroutine is not included in display lists.
GL_INVALID_ENUM is generated if stride is negative.
glIsEnabled with argument GL_EDGE_FLAG_ARRAY
glGet with argument GL_EDGE_FLAG_ARRAY_STRIDE
glGetPointerv with argument GL_EDGE_FLAG_ARRAY_POINTER
"glArrayElement", "glColorPointer", "glDrawArrays", "glDrawElements", "glEnable", "glGetPointerv", "glIndexPointer", "glNormalPointer", "glPopClientAttrib", "glPushClientAttrib", "glTexCoordPointer", "glVertexPointer"
glEnable, glDisable - enable or disable GL capabilities
void glEnable( GLenum cap )
void glDisable( GLenum cap )
glEnable and glDisable enable and disable various capabilities. Use glIsEnabled or glGet to determine the current setting of any capability.
Both glEnable and glDisable take a single argument, cap, which can assume one of the following values:
GL_INVALID_ENUM is generated if cap is not one of the values listed above.
GL_INVALID_OPERATION is generated if glEnable is called between a call to glBegin and the corresponding call to glEnd.
"glAlphaFunc", "glBlendFunc", "glClipPlane", "glColorMaterial", "glCullFace", "glDepthFunc", "glDepthRange", "glFog", "glGet", "glIsEnabled", "glLight", "glLightModel", "glLineWidth", "glLineStipple", "glLogicOp", "glMap1", "glMap2", "glMaterial", "glNormal", "glPointSize", "glPolygonMode", "glPolygonStipple", "glScissor", "glStencilFunc", "glStencilOp", "glTexGen", "glTexImage1D", "glTexImage2D"
glEnableClientState, glDisableClientState - enable or disable an array
void glEnableClientState( GLenum array )
void glDisableClientState( GLenum array )
The glEnableClientState subroutine lets you enable individual arrays, and glDisableClientState lets you disable individual arrays.
The glEnableClientState and glDisableClientState subroutines are available only if the GL version is 1.1 or greater.
GL_INVALID_ENUM is generated if array is not an accepted value.
The glEnableClientState subroutine is not allowed between the execution of glBegin and the corresponding glEnd, but an error may or may not be generated. If no error is generated then the behavior is undefined.
"glArrayElement", "glColorPointer", "glDrawArrays", "glDrawElements", "glEdgeFlagPointer", "glGetPointerv", "glIndexPointer", "glInterleavedArrays", "glNormalPointer", "glTexCoordPointer", "glVertexPointer"
glEvalCoord1d, glEvalCoord1f, glEvalCoord2d, glEvalCoord2f, glEvalCoord1dv, glEvalCoord1fv, glEvalCoord2dv, glEvalCoord2fv - evaluate enabled one- and two-dimensional maps
void glEvalCoord1d( GLdouble u )
void glEvalCoord1f( GLfloat u )
void glEvalCoord2d( GLdouble u, GLdouble v )
void glEvalCoord2f( GLfloat u, GLfloat v )
void glEvalCoord1dv( const GLdouble *u )
void glEvalCoord1fv( const GLfloat *u )
void glEvalCoord2dv( const GLdouble *u )
void glEvalCoord2fv( const GLfloat *u )
glEvalCoord1 evaluates enabled one-dimensional maps at argument u. glEvalCoord2 does the same for two-dimensional maps using two domain values, u and v. Maps are defined with glMap1 and glMap2 and enabled and disabled with glEnable and glDisable.
When one of the glEvalCoord commands is issued, all currently enabled maps of the indicated dimension are evaluated. Then, for each enabled map, it is as if the corresponding GL command was issued with the computed value. That is, if GL_MAP1_INDEX or GL_MAP2_INDEX is enabled, a glIndex command is simulated. If GL_MAP1_COLOR_4 or GL_MAP2_COLOR_4 is enabled, a glColor command is simulated. If GL_MAP1_NORMAL or GL_MAP2_NORMAL is enabled, a normal vector is produced, and if any of GL_MAP1_TEXTURE_COORD_1, GL_MAP1_TEXTURE_COORD_2, GL_MAP1_TEXTURE_COORD_3, GL_MAP1_TEXTURE_COORD_4, GL_MAP2_TEXTURE_COORD_1, GL_MAP2_TEXTURE_COORD_2, GL_MAP2_TEXTURE_COORD_3, or GL_MAP2_TEXTURE_COORD_4 is enabled, then an appropriate glTexCoord command is simulated.
The GL uses evaluated values instead of current values for those evaluations that are enabled, and current values otherwise, for color, color index, normal, and texture coordinates. However, the evaluated values do not update the current values. Thus, if glVertex commands are interspersed with glEvalCoord commands, the color, normal, and texture coordinates associated with the glVertex commands are not affected by the values generated by the glEvalCoord commands, but rather only by the most recent glColor, glIndex, glNormal, and glTexCoord commands.
No commands are issued for maps that are not enabled. If more than one texture evaluation is enabled for a particular dimension (for example, GL_MAP2_TEXTURE_COORD_1 and GL_MAP2_TEXTURE_COORD_2), then only the evaluation of the map that produces the larger number of coordinates (in this case, GL_MAP2_TEXTURE_COORD_2) is carried out. GL_MAP1_VERTEX_4 overrides GL_MAP1_VERTEX_3, and GL_MAP2_VERTEX_4 overrides GL_MAP2_VERTEX_3, in the same manner. If neither a three- nor four-component vertex map is enabled for the specified dimension, the glEvalCoord command is ignored.
If automatic normal generation is enabled, by calling glEnable with argument GL_AUTO_NORMAL, glEvalCoord2 generates surface normals analytically, regardless of the contents or enabling of the GL_MAP2_NORMAL map. Let
Then the generated normal n is
If automatic normal generation is disabled, the corresponding normal map GL_MAP2_NORMAL, if enabled, is used to produce a normal. If neither automatic normal generation nor a normal map is enabled, no normal is generated for glEvalCoord2 commands.
glIsEnabled with argument GL_MAP1_VERTEX_3
glIsEnabled with argument GL_MAP1_VERTEX_4
glIsEnabled with argument GL_MAP1_INDEX
glIsEnabled with argument GL_MAP1_COLOR_4
glIsEnabled with argument GL_MAP1_NORMAL
glIsEnabled with argument GL_MAP1_TEXTURE_COORD_1
glIsEnabled with argument GL_MAP1_TEXTURE_COORD_2
glIsEnabled with argument GL_MAP1_TEXTURE_COORD_3
glIsEnabled with argument GL_MAP1_TEXTURE_COORD_4
glIsEnabled with argument GL_MAP2_VERTEX_3
glIsEnabled with argument GL_MAP2_VERTEX_4
glIsEnabled with argument GL_MAP2_INDEX
glIsEnabled with argument GL_MAP2_COLOR_4
glIsEnabled with argument GL_MAP2_NORMAL
glIsEnabled with argument GL_MAP2_TEXTURE_COORD_1
glIsEnabled with argument GL_MAP2_TEXTURE_COORD_2
glIsEnabled with argument GL_MAP2_TEXTURE_COORD_3
glIsEnabled with argument GL_MAP2_TEXTURE_COORD_4
glIsEnabled with argument GL_AUTO_NORMAL
glGetMap
"glBegin", "glColor", "glEnable", "glEvalMesh", "glEvalPoint", "glIndex", "glMap1", "glMap2", "glMapGrid", "glNormal", "glTexCoord", "glVertex"
glEvalMesh1, glEvalMesh2 - compute a one- or two-dimensional grid of points or lines
void glEvalMesh1( GLenum mode, GLint i1, GLint i2 )
void glEvalMesh2( GLenum mode, GLint i1, Lint i2, GLint j1, GLint j2 )
glMapGrid and glEvalMesh are used in tandem to efficiently generate and evaluate a series of evenly spaced map domain values. glEvalMesh steps through the integer domain of a one- or two-dimensional grid, whose range is the domain of the evaluation maps specified by glMap1 and glMap2. mode determines whether the resulting vertices are connected as points, lines, or filled polygons.
In the one-dimensional case, glEvalMesh1, the mesh is generated as if the following code fragment were executed:
glBegin(type);
for (i = i1; i <= i2; i += 1)
glEvalCoord1(i · Du + u1)
glEnd();
where
Du = (u2 - u1) / n
and n, u1, and u2 are the arguments to the most recent glMapGrid1 command. type is GL_POINTS if mode is GL_POINT, or GL_LINES if mode is GL_LINE. The one absolute numeric requirement is that if i = n, then the value computed from i · Du + u1 is exactly u2.
In the two-dimensional case, glEvalMesh2, let
Du = (u2 - u1)/n
Dv = (v2 - v1)/m,
where n, u1, u2, m, v1, and v2 are the arguments to the most recent glMapGrid2 command. Then, if mode is GL_FILL, the glEvalMesh2 command is equivalent to:
for (j = j1; j < j2; j += 1) {
glBegin(GL_QUAD_STRIP);
for (i = i1; i <= i2; i += 1) {
glEvalCoord2(i · Du + u1, j · Dv + v1);
glEvalCoord2(i · Du + u1, (j+1) · Dv + v1);
}
glEnd();
}
If mode is GL_LINE, then a call to glEvalMesh2 is equivalent to:
for (j = j1; j <= j2; j += 1) {
glBegin(GL_LINE_STRIP);
for (i = i1; i <= i2; i += 1)
glEvalCoord2(i · Du + u1, j · Dv + v1);
glEnd();
}
for (i = i1; i <= i2; i += 1) {
glBegin(GL_LINE_STRIP);
for (j = j1; j <= j1; j += 1)
glEvalCoord2(i · Du + u1, j · Dv + v1);
glEnd();
}
And finally, if mode is GL_POINT, then a call to glEvalMesh2 is equivalent to:
glBegin(GL_POINTS);
for (j = j1; j <= j2; j += 1) {
for (i = i1; i <= i2; i += 1) {
glEvalCoord2(i · Du + u1, j · Dv + v1);
}
}
glEnd();
In all three cases, the only absolute numeric requirements are that if i = n, then the value computed from i · Du + u1 is exactly u2, and if j = m, then the value computed from j · Dv + v1 is exactly v2.
GL_INVALID_ENUM is generated if mode is not an accepted value.
GL_INVALID_OPERATION is generated if glEvalMesh is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_MAP1_GRID_DOMAIN
glGet with argument GL_MAP2_GRID_DOMAIN
glGet with argument GL_MAP1_GRID_SEGMENTS
glGet with argument GL_MAP2_GRID_SEGMENTS
"glBegin", "glEvalCoord", "glEvalPoint", "glMap1", "glMap2", "glMapGrid"
glEvalPoint1, glEvalPoint2 - generate and evaluate a single point in a mesh
void glEvalPoint1( GLint i )
void glEvalPoint2( GLint i, GLint j )
glMapGrid and glEvalMesh are used in tandem to efficiently generate and evaluate a series of evenly spaced map domain values. glEvalPoint can be used to evaluate a single grid point in the same gridspace that is traversed by glEvalMesh. Calling glEvalPoint1 is equivalent to calling
glEvalCoord1(i · Du + u1);
where
Du = (u2 - u1)/n
and n, u1, and u2 are the arguments to the most recent glMapGrid1 command. The one absolute numeric requirement is that if i = n, then the value computed from i · Du + u1 is exactly u2.
In the two-dimensional case, glEvalPoint2, let
Du = (u2 - u1)/n
Dv = (v2 - v1)/m
where n, u1, u2, m, v1, and v2 are the arguments to the most recent glMapGrid2 command. Then the glEvalPoint2 command is equivalent to calling
glEvalCoord2(i · Du + u1, j · Dv + v1);
The only absolute numeric requirements are that if i = n, then the value computed from i · Du + u1 is exactly u2, and if j = m, then the value computed from j · Dv + v1 is exactly v2.
glGet with argument GL_MAP1_GRID_DOMAIN
glGet with argument GL_MAP2_GRID_DOMAIN
glGet with argument GL_MAP1_GRID_SEGMENTS
glGet with argument GL_MAP2_GRID_SEGMENTS
"glEvalCoord", "glEvalMesh", "glMap1", "glMap2", "glMapGrid"
glFeedbackBuffer - controls feedback mode
void glFeedbackBuffer( GLsizei size, GLenum type, GLfloat *buffer )
The glFeedbackBuffer function controls feedback. Feedback, like selection, is a GL 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.
glFeedbackBuffer has three arguments: buffer is a pointer to an array of floating-point values into which feedback information is placed. size indicates the size of the array. type is a symbolic constant describing the information that is fed back for each vertex. glFeedbackBuffer must be issued before feedback mode is enabled (by calling glRenderMode with argument GL_FEEDBACK). Setting GL_FEEDBACK without establishing the feedback buffer, or calling glFeedbackBuffer while the GL is in feedback mode, is an error.
The GL is taken out of feedback mode by calling glRenderMode with a parameter value other than GL_FEEDBACK. When this is done while the GL is in feedback mode, glRenderMode returns the number of entries placed in the feedback array. The returned value never exceeds size. If the feedback data required more room than was available in buffer, glRenderMode returns a negative value.
While in feedback mode, each primitive that would be rasterized generates a block of values that get copied into the feedback array. If doing so would cause the number of entries to exceed the maximum, the block is partially written so as to fill the array (if there is any room left at all), and an overflow flag is set. Each block begins with a code indicating the primitive type, followed by values that describe the primitive's vertices and associated data. Entries are also written for bitmaps and pixel rectangles. Feedback occurs after polygon culling and glPolygonMode interpretation of polygons has taken place, so polygons that are culled are not returned in the feedback buffer. It can also occur after polygons with more than three edges are broken up into triangles, if the GL implementation renders polygons by performing this decomposition.
The glPassThrough command can be used to insert a marker into the feedback buffer. See "glPassThrough".
Following is the grammar for the blocks of values written into the feedback buffer. Each primitive is indicated with a unique identifying value followed by some number of vertices. Polygon entries include an integer value indicating how many vertices follow. A vertex is fed back as some number of floating-point values, as determined by type. Colors are fed back as four values in RGBA mode and one value in color index mode.
feedbackList <-- feedbackItem feedbackList | feedbackItem
feedbackItem <-- point | lineSegment | polygon | bitmap | pixelRectangle | passThru
point <-- GL_POINT_TOKEN vertex
lineSegment <-- GL_LINE_TOKEN vertex vertex | GL_LINE_RESET_TOKEN vertex vertex
polygon <-- GL_POLYGON_TOKEN n polySpec
polySpec <-- polySpec vertex | vertex vertex vertex
bitmap <-- GL_BITMAP_TOKEN vertex
pixelRectangle <-- GL_DRAW_PIXEL_TOKEN vertex | GL_COPY_PIXEL_TOKEN vertex
passThru <-- GL_PASS_THROUGH_TOKEN value
vertex <-- 2d | 3d | 3dColor | 3dColorTexture | 4dColorTexture
2d <-- value value
3d <-- value value value
3dColor <-- value value value color
3dColorTexture <-- value value value color tex
4dColorTexture <-- value value value value color tex
color <-- rgba | index
rgba <-- value value value value
index <-- value
tex <-- value value value value
value is a floating-point number, and n is a floating-point integer giving the number of vertices in the polygon. GL_POINT_TOKEN, GL_LINE_TOKEN, GL_LINE_RESET_TOKEN, GL_POLYGON_TOKEN, GL_BITMAP_TOKEN, GL_DRAW_PIXEL_TOKEN, GL_COPY_PIXEL_TOKEN and GL_PASS_THROUGH_TOKEN are symbolic floating-point constants. GL_LINE_RESET_TOKEN is returned whenever the line stipple pattern is reset. The data returned as a vertex depends on the feedback type.
The following table gives the correspondence between type and the number of values per vertex. k is 1 in color index mode and 4 in RGBA mode.
| type | coordinates | color | texture | total number of values |
|---|---|---|---|---|
GL_2D |
x, y |
2 |
||
GL_3D |
x, y, z |
3 |
||
GL_3D_COLOR |
x, y, z |
k |
3 + k |
|
GL_3D_COLOR_TEXTURE |
x, y, z, |
k |
4 |
7 + k |
GL_4D_COLOR_TEXTURE |
x, y, z, w |
k |
4 |
8 + k |
Feedback vertex coordinates are in window coordinates, except w, which is in clip coordinates. Feedback colors are lighted, if lighting is enabled. Feedback texture coordinates are generated, if texture coordinate generation is enabled. They are always transformed by the texture matrix.
glFeedbackBuffer, when used in a display list, is not compiled into the display list but rather is executed immediately.
GL_INVALID_ENUM is generated if type is not an accepted value.
GL_INVALID_VALUE is generated if size is negative.
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 glFeedbackBuffer is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_RENDER_MODE
"glBegin", "glLineStipple", "glPassThrough", "glPolygonMode", "glRenderMode", "glSelectBuffer"
glFinish - block until all GL execution is complete
void glFinish( void )
glFinish does not return until the effects of all previously called GL commands are complete. Such effects include all changes to GL state, all changes to connection state, and all changes to the frame buffer contents.
glFinish requires a round trip to the server.
GL_INVALID_OPERATION is generated if glFinish is called between a call to glBegin and the corresponding call to glEnd.
"glFlush", "glXWaitGL", "glXWaitX"
glFlush - force execution of GL commands in finite time
void glFlush( void )
Different GL implementations buffer commands in several different locations, including network buffers and the graphics accelerator itself. glFlush empties all of these buffers, causing all issued commands to be executed as quickly as they are accepted by the actual rendering engine. Though this execution may not be completed in any particular time period, it does complete in finite time.
Because any GL program might be executed over a network, or on an accelerator that buffers commands, all programs should call glFlush whenever they count on having all of their previously issued commands completed. For example, call glFlush before waiting for user input that depends on the generated image.
glFlush can return at any time. It does not wait until the execution of all previously issued OpenGL commands is complete.
GL_INVALID_OPERATION is generated if glFlush is called between a call to glBegin and the corresponding call to glEnd.
glFogf, glFogi, glFogfv, glFogiv - specify fog parameters
void glFogf( GLenum pname, GLfloat param )
void glFogi( GLenum pname, GLint param )
void glFogfv( GLenum pname, const GLfloat *params )
void glFogiv( GLenum pname, const GLint *params )
Fog is enabled and disabled with glEnable and glDisable using the argument GL_FOG. While enabled, fog affects rasterized geometry, bitmaps, and pixel blocks, but not buffer clear operations.
glFog assigns the value or values in params to the fog parameter specified by pname. The accepted values for pname are as follows:
Fog blends a fog color with each rasterized pixel fragment's posttexturing color using a blending factor f. Factor f is computed in one of three ways, depending on the fog mode. Let z be the distance in eye coordinates from the origin to the fragment being fogged. The equation for GL_LINEAR fog is
The equation for GL_EXP fog is
The equation for GL_EXP2 fog is
Regardless of the fog mode, f is clamped to the range [0,1] after it is computed. Then, if the GL is in RGBA color mode, the fragment's color Cr is replaced by
Cr'=fCr+(1-f)Cf
In color index mode, the fragment's color index ir is replaced by
ir'=ir+(1-f)if
GL_INVALID_ENUM is generated if pname is not an accepted value, or if pname is GL_FOG_MODE and params is not an accepted value.
GL_INVALID_VALUE is generated if pname is GL_FOG_DENSITY and params is negative.
GL_INVALID_OPERATION is generated if glFog is called between a call to glBegin and the corresponding call to glEnd.
glIsEnabled with argument GL_FOG
glGet with argument GL_FOG_COLOR
glGet with argument GL_FOG_INDEX
glGet with argument GL_FOG_DENSITY
glGet with argument GL_FOG_START
glGet with argument GL_FOG_END
glGet with argument GL_FOG_MODE
glFrontFace - define front- and back-facing polygons
void glFrontFace( GLenum mode )
In a scene composed entirely of opaque closed surfaces, back-facing polygons are never visible. Eliminating these invisible polygons has the obvious benefit of speeding up the rendering of the image. Elimination of back-facing polygons is enabled and disabled with glEnable and glDisable using argument GL_CULL_FACE.
The projection of a polygon to window coordinates is said to have clockwise winding if an imaginary object following the path from its first vertex, its second vertex, and so on, to its last vertex, and finally back to its first vertex, moves in a clockwise direction about the interior of the polygon. The polygon's winding is said to be counterclockwise if the imaginary object following the same path moves in a counterclockwise direction about the interior of the polygon. glFrontFace specifies whether polygons with clockwise winding in window coordinates, or counterclockwise winding in window coordinates, are taken to be front-facing. Passing GL_CCW to mode selects counterclockwise polygons as front-facing; GL_CW selects clockwise polygons as front-facing. By default, counterclockwise polygons are taken to be front-facing.
GL_INVALID_ENUM is generated if mode is not an accepted value.
GL_INVALID_OPERATION is generated if glFrontFace is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_FRONT_FACE
glFrustum - multiply the current matrix by a perspective matrix
void glFrustum( GLdouble left, GLdouble right, GLdouble bottom, GLdouble top, GLdouble near, GLdouble far )
glFrustum describes a perspective matrix that produces a perspective projection. (left, bottom, -near) and (right, top, -near) 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). -far specifies the location of the far clipping plane. Both near and far must be positive. The corresponding matrix is
The current matrix is multiplied by this matrix with the result replacing the current matrix. That is, if M is the current matrix and F is the frustum perspective matrix, then M is replaced with M o F.
Use glPushMatrix and glPopMatrix to save and restore the current matrix stack.
Depth buffer precision is affected by the values specified for near and far. The greater the ratio of far to near is, the less effective the depth buffer will be at distinguishing between surfaces that are near each other. If
roughly log2 r bits of depth buffer precision are lost. Because r approaches infinity as near approaches zero, near must never be set to zero.
GL_INVALID_VALUE is generated if near or far is not positive.
GL_INVALID_OPERATION is generated if glFrustum is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_MATRIX_MODE
glGet with argument GL_MODELVIEW_MATRIX
glGet with argument GL_PROJECTION_MATRIX
glGet with argument GL_TEXTURE_MATRIX
"glOrtho", "glMatrixMode", "glMultMatrix", "glPushMatrix", "glViewport"
glGenLists - generate a contiguous set of empty display lists
GLuint glGenLists( GLsizei range )
glGenLists has one argument, range. It returns an integer n such that range contiguous empty display lists, named n, n+1, ..., n+range -1, are created. If range is zero, if there is no group of range contiguous names available, or if any error is generated, no display lists are generated, and zero is returned.
GL_INVALID_VALUE is generated if range is negative.
GL_INVALID_OPERATION is generated if glGenLists is called between a call to glBegin and the corresponding call to glEnd.
"glCallList", "glCallLists", "glDeleteLists", "glNewList"
glGenTextures - generate texture names
void glGenTextures( GLsizei n, GLuint *textures )
The glGenTextures subroutine returns n texture names in textures. There is no guarantee that the names form a contiguous set of integers; however, it is guaranteed that none of the returned names was in use immediately before the call to glGenTextures.
The generated textures have no dimensionality; they assume the dimensionality of the texture target to which they are first bound (see glBindTexture).
Texture names returned by a call to glGenTextures are not returned by subsequent calls, unless they are first deleted with glDeleteTextures.
The glGenTextures subroutine is not included in display lists.
The glGenTextures subroutine is available only if the GL version is 1.1 or greater.
GL_INVALID_VALUE is generated if n is negative.
GL_INVALID_OPERATION is generated if glGenTextures is executed between the execution of glBegin and the corresponding execution of glEnd.
"glBindTexture", "glDeleteTextures", "glTexParameter"
glGetBooleanv, glGetDoublev, glGetFloatv, glGetIntegerv - return the value or values of a selected parameter
void glGetBooleanv( GLenum pname, GLboolean *params )
void glGetDoublev( GLenum pname, GLdouble *params )
void glGetFloatv( GLenum pname, GLfloat *params )
void glGetIntegerv( GLenum pname, GLint *params )
These four commands return values for simple state variables in GL. pname is a symbolic constant indicating the state variable to be returned, and params is a pointer to an array of the indicated type in which to place the returned data.
Type conversion is performed if params has a different type than the state variable value being requested. If glGetBooleanv is called, a floating-point or integer value is converted to GL_FALSE if and only if it is zero. Otherwise, it is converted to GL_TRUE. If glGetIntegerv is called, Boolean values are returned as GL_TRUE or GL_FALSE, and most floating-point values are rounded to the nearest integer value. Floating-point colors and normals, however, are returned with a linear mapping that maps 1.0 to the most positive representable integer value, and -1.0 to the most negative representable integer value. If glGetFloatv or glGetDoublev is called, Boolean values are returned as GL_TRUE or GL_FALSE, and integer values are converted to floating-point values.
The following symbolic constants are accepted by pname:
Many of the Boolean parameters can also be queried more easily using glIsEnabled.
GL_INVALID_ENUM is generated if pname is not an accepted value.
GL_INVALID_OPERATION is generated if glGet is called between a call to glBegin and the corresponding call to glEnd.
"glGetClipPlane", "glGetError", "glGetLight", "glGetMap", "glGetMaterial", "glGetPixelMap", "glGetPolygonStipple", "glGetString", "glGetTexEnv", "glGetTexGen", "glGetTexImage", "glGetTexLevelParameter", "glGetTexParameter", "glIsEnabled"
glGetClipPlane - return the coefficients of the specified clipping plane
void glGetClipPlane( GLenum plane, GLdouble *equation )
glGetClipPlane returns in equation the four coefficients of the plane equation for plane.
It is always the case that GL_CLIP_PLANEi = GL_CLIP_PLANE0 + i.
If an error is generated, no change is made to the contents of equation.
GL_INVALID_ENUM is generated if plane is not an accepted value.
GL_INVALID_OPERATION is generated if glGetClipPlane is called between a call to glBegin and the corresponding call to glEnd.
glGetError - return error information
GLenum glGetError( void )
glGetError returns the value of the error flag. Each detectable error is assigned a numeric code and symbolic name. When an error occurs, the error flag is set to the appropriate error code value. No other errors are recorded until glGetError is called, the error code is returned, and the flag is reset to GL_NO_ERROR. If a call to glGetError returns GL_NO_ERROR, there has been no detectable error since the last call to glGetError, or since the GL was initialized.
To allow for distributed implementations, there may be several error flags. If any single error flag has recorded an error, the value of that flag is returned and that flag is reset to GL_NO_ERROR when glGetError is called. If more than one flag has recorded an error, glGetError returns and clears an arbitrary error flag value. Thus, glGetError should always be called in a loop, until it returns GL_NO_ERROR, if all error flags are to be reset.
Initially, all error flags are set to GL_NO_ERROR.
The currently defined errors are as follows:
When an error flag is set, results of a GL operation are undefined only if GL_OUT_OF_MEMORY has occurred. In all other cases, the command generating the error is ignored and has no effect on the GL state or frame buffer contents.
GL_INVALID_OPERATION is generated if glGetError is called between a call to glBegin and the corresponding call to glEnd.
glGetLightfv, glGetLightiv - return light source parameter values
void glGetLightfv( GLenum light, GLenum pname, GLfloat *params )
void glGetLightiv( GLenum light, GLenum pname, GLint *params )
glGetLight returns in params the value or values of a light source parameter. light names the light and is a symbolic name of the form GL_LIGHTi for 0 ≤ i<GL_MAX_LIGHTS, where GL_MAX_LIGHTS is an implementation dependent constant that is greater than or equal to eight. pname specifies one of ten light source parameters, again by symbolic name.
The parameters are as follows:
It is always the case that GL_LIGHTi = GL_LIGHT0 + i.
If an error is generated, no change is made to the contents of params.
GL_INVALID_ENUM is generated if light or pname is not an accepted value.
GL_INVALID_OPERATION is generated if glGetLight is called between a call to glBegin and the corresponding call to glEnd.
glGetMapdv, glGetMapfv, glGetMapiv - return evaluator parameters
void glGetMapdv( GLenum target, GLenum query, GLdouble *v )
void glGetMapfv( GLenum target, GLenum query, GLfloat *v )
void glGetMapiv( GLenum target, GLenum query, GLint *v )
glMap1 and glMap2 define evaluators. glGetMap returns evaluator parameters. target chooses a map, query selects a specific parameter, and v points to storage where the values will be returned.
The acceptable values for the target parameter are described in the glMap1 and glMap2 reference pages.
query can assume the following values:
If an error is generated, no change is made to the contents of v.
GL_INVALID_ENUM is generated if either target or query is not an accepted value.
GL_INVALID_OPERATION is generated if glGetMap is called between a call to glBegin and the corresponding call to glEnd.
"glEvalCoord", "glMap1", "glMap2"
glGetMaterialfv, glGetMaterialiv - return material parameters
void glGetMaterialfv( GLenum face, GLenum pname, GLfloat *params )
void glGetMaterialiv( GLenum face, GLenum pname, GLint *params )
glGetMaterial returns in params the value or values of parameter pname of material face. Six parameters are defined:
If an error is generated, no change is made to the contents of params.
GL_INVALID_ENUM is generated if face or pname is not an accepted value.
GL_INVALID_OPERATION is generated if glGetMaterial is called between a call to glBegin and the corresponding call to glEnd.
glGetPixelMapfv, glGetPixelMapuiv, glGetPixelMapusv - return the specified pixel map
void glGetPixelMapfv( GLenum map, GLfloat *values )
void glGetPixelMapuiv( GLenum map, GLuint *values )
void glGetPixelMapusv( GLenum map, GLushort *values )
Please see the "glPixelMap" reference page for a description of the acceptable values for the map parameter. glGetPixelMap returns in values the contents of the pixel map specified in map. Pixel maps are used during the execution of glReadPixels, glDrawPixels, glCopyPixels, glTexImage1D, and glTexImage2D to map color indices, stencil indices, color components, and depth components to other values.
Unsigned integer values, if requested, are linearly mapped from the internal fixed or floating-point representation such that 1.0 maps to the largest representable integer value, and 0.0 maps to zero. Return unsigned integer values are undefined if the map value was not in the range [0,1].
To determine the required size of map, call glGet with the appropriate symbolic constant.
If an error is generated, no change is made to the contents of values.
GL_INVALID_ENUM is generated if map is not an accepted value.
GL_INVALID_OPERATION is generated if glGetPixelMap is called between a call to glBegin and the corresponding call to glEnd.
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
"glCopyPixels", "glDrawPixels", "glPixelMap", "glPixelTransfer", "glReadPixels", "glTexImage1D", "glTexImage2D"
glGetPointerv - return the address of the specified pointer
void glGetPointerv( GLenum pname, GLvoid* *params )
The glGetPointerv subroutine returns pointer information. The pname parameter is a symbolic constant indicating the pointer to be returned, and params is a pointer to a location in which to place the returned data.
The glGetPointerv subroutine is available only if the GL version is 1.1 or greater.
The pointers are all client side state.
The initial value for each pointer is 0.
GL_INVALID_ENUM is generated if pname is not an accepted value.
"glArrayElement", "glColorPointer", "glDrawArrays", "glEdgeFlagPointer", "glIndexPointer", "glNormalPointer", "glTexCoordPointer", "glVertexPointer"
glGetPolygonStipple - return the polygon stipple pattern
void glGetPolygonStipple( GLubyte *mask )
glGetPolygonStipple returns to mask a 32 × 32 polygon stipple pattern. The pattern is packed into memory as if glReadPixels with both height and width of 32, type of GL_BITMAP, and format of GL_COLOR_INDEX were called, and the stipple pattern were stored in an internal 32 × 32 color index buffer. Unlike glReadPixels, however, pixel transfer operations (shift, offset, pixel map) are not applied to the returned stipple image.
If an error is generated, no change is made to the contents of mask.
GL_INVALID_OPERATION is generated if glGetPolygonStipple is called between a call to glBegin and the corresponding call to glEnd.
"glPixelStore", "glPixelTransfer", "glPolygonStipple", "glReadPixels"
glGetString - returns a string describing the current GL connection
const GLubyte * glGetString( GLenum name )
glGetString returns a pointer to a static string describing some aspect of the current GL connection. name can be one of the following:
Because GL does not include queries for the performance characteristics of an implementation, it is expected that some applications will be written to recognize known platforms and will modify their GL usage based on known performance characteristics of these platforms. Strings GL_VENDOR and GL_RENDERER together uniquely specify a platform, and will not change from release to release. They should be used by such platform recognition algorithms.
The format and contents of the string that glGetString returns depend on the implementation, except that extension names will not include space characters and will be separated by space characters in the GL_EXTENSIONS string, and that all strings are null-terminated.
If an error is generated, glGetString returns zero.
GL_INVALID_ENUM is generated if name is not an accepted value.
GL_INVALID_OPERATION is generated if glGetString is called between a call to glBegin and the corresponding call to glEnd.
glGetTexEnvfv, glGetTexEnviv - return texture environment parameters
void glGetTexEnvfv( GLenum target, GLenum pname, GLfloat *params )
void glGetTexEnviv( GLenum target, GLenum pname, GLint *params )
glGetTexEnv returns in params selected values of a texture environment that was specified with glTexEnv. target specifies a texture environment. Currently, only one texture environment is defined and supported: GL_TEXTURE_ENV.
pname names a specific texture environment parameter. The two parameters are as follows:
If an error is generated, no change is made to the contents of params.
GL_INVALID_ENUM is generated if target or pname is not an accepted value.
GL_INVALID_OPERATION is generated if glGetTexEnv is called between a call to glBegin and the corresponding call to glEnd.
glGetTexGendv, glGetTexGenfv, glGetTexGeniv - return texture coordinate generation parameters
void glGetTexGendv( GLenum coord, GLenum pname, GLdouble *params )
void glGetTexGenfv( GLenum coord, GLenum pname, GLfloat *params )
void glGetTexGeniv( GLenum coord, GLenum pname, GLint *params )
glGetTexGen returns in params selected parameters of a texture coordinate generation function that was specified using glTexGen. coord names one of the (s ,t ,r ,q) texture coordinates, using the symbolic constant GL_S, GL_T, GL_R, or GL_Q.
pname specifies one of three symbolic names:
If an error is generated, no change is made to the contents of params.
GL_INVALID_ENUM is generated if coord or pname is not an accepted value.
GL_INVALID_OPERATION is generated if glGetTexGen is called between a call to glBegin and the corresponding call to glEnd.
glGetTexImage - return a texture image
void glGetTexImage( GLenum target, GLint level, GLenum format, GLenum type, GLvoid *pixels )
glGetTexImage returns a texture image into pixels. target specifies whether the desired texture image is one specified by glTexImage1D (GL_TEXTURE_1D) or by glTexImage2D (GL_TEXTURE_2D). level specifies the level-of-detail number of the desired image. format and type specify the format and type of the desired image array. Please see the reference pages "glTexImage1D" and "glDrawPixels" for a description of the acceptable values for the format and type parameters, respectively.
Operation of glGetTexImage is best understood by considering the selected internal four-component texture image to be an RGBA color buffer the size of the image. The semantics of glGetTexImage are then identical to those of glReadPixels called with the same format and type, with x and y set to zero, width set to the width of the texture image (including border if one was specified), and height set to one for 1-D images, or to the height of the texture image (including border if one was specified) for 2-D images. Because the internal texture image is an RGBA image, pixel formats GL_COLOR_INDEX, GL_STENCIL_INDEX, and GL_DEPTH_COMPONENT are not accepted, and pixel type GL_BITMAP is not accepted.
If the selected texture image does not contain four components, the following mappings are applied. Single-component textures are treated as RGBA buffers with red set to the single-component value, and green, blue, and alpha set to zero. Two-component textures are treated as RGBA buffers with red set to the value of component zero, alpha set to the value of component one, and green and blue set to zero. Finally, three-component textures are treated as RGBA buffers with red set to component zero, green set to component one, blue set to component two, and alpha set to zero.
To determine the required size of pixels, use glGetTexLevelParameter to ascertain the dimensions of the internal texture image, then scale the required number of pixels by the storage required for each pixel, based on format and type. Be sure to take the pixel storage parameters into account, especially GL_PACK_ALIGNMENT.
If an error is generated, no change is made to the contents of pixels.
GL_INVALID_ENUM is generated if target, format, or type is not an accepted value.
GL_INVALID_VALUE is generated if level is less than zero or greater than log2 max, where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_OPERATION is generated if glGetTexImage is called between a call to glBegin and the corresponding call to glEnd.
glGetTexLevelParameter with argument
GL_TEXTURE_WIDTH
glGetTexLevelParameter with argument
GL_TEXTURE_HEIGHT
glGetTexLevelParameter with argument
GL_TEXTURE_BORDER
glGetTexLevelParameter with argument
GL_TEXTURE_COMPONENTS
glGet with arguments GL_PACK_ALIGNMENT and others
"glDrawPixels", "glReadPixels", "glTexImage1D", "glTexImage2D"
glGetTexLevelParameterfv, glGetTexLevelParameteriv - return texture parameter values for a specific level of detail
void glGetTexLevelParameterfv( GLenum target, GLint level,
GLenum pname, GLfloat *params )
void glGetTexLevelParameteriv( GLenum target, GLint level,
GLenum pname, GLint *params )
glGetTexLevelParameter returns in params texture parameter values for a specific level-of-detail value, specified as level. target defines the target texture, either GL_TEXTURE_1D or GL_TEXTURE_2D, to specify one- or two-dimensional texturing. pname specifies the texture parameter whose value or values will be returned.
The accepted parameter names are as follows:
If an error is generated, no change is made to the contents of params.
GL_INVALID_ENUM is generated if target or pname is not an accepted value.
GL_INVALID_VALUE is generated if level is less than zero or greater than log2 max, where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_OPERATION is generated if glGetTexLevelParameter is called between a call to glBegin and the corresponding call to glEnd.
"glGetTexParameter", "glTexImage1D", "glTexImage2D", "glTexParameter"
glGetTexParameterfv, glGetTexParameteriv - return texture parameter values
void glGetTexParameterfv( GLenum target, GLenum pname,
GLfloat *params )
void glGetTexParameteriv( GLenum target, GLenum pname, GLint *params )
glGetTexParameter returns in params the value or values of the texture parameter specified as pname. target defines the target texture, either GL_TEXTURE_1D or GL_TEXTURE_2D, to specify one- or two-dimensional texturing. pname accepts the same symbols as glTexParameter, with the same interpretations:
If an error is generated, no change is made to the contents of params.
GL_INVALID_ENUM is generated if target or pname is not an accepted value.
GL_INVALID_OPERATION is generated if glGetTexParameter is called between a call to glBegin and the corresponding call to glEnd.
glHint - specify implementation-specific hints
void glHint( GLenum target, GLenum mode )
Certain aspects of GL behavior, when there is room for interpretation, can be controlled with hints. A hint is specified with two arguments. target is a symbolic constant indicating the behavior to be controlled, and mode is another symbolic constant indicating the desired behavior. mode can be one of the following:
Though the implementation aspects that can be hinted are well defined, the interpretation of the hints depends on the implementation. The hint aspects that can be specified with target, along with suggested semantics, are as follows:
The interpretation of hints depends on the implementation. glHint can be ignored.
GL_INVALID_ENUM is generated if either target or mode is not an accepted value.
GL_INVALID_OPERATION is generated if glHint is called between a call to glBegin and the corresponding call to glEnd.
glIndexd, glIndexf, glIndexi, glIndexs, glIndexdv, glIndexfv, glIndexiv, glIndexsv - set the current color index
void glIndexd( GLdouble c )
void glIndexf( GLfloat c )
void glIndexi( GLint c )
void glIndexs( GLshort c )
void glIndexdv( const GLdouble *c )
void glIndexfv( const GLfloat *c )
void glIndexiv( const GLint *c )
void glIndexsv( const GLshort *c )
glIndex updates the current (single-valued) color index. It takes one argument: the new value for the current color index.
The current index is stored as a floating-point value. Integer values are converted directly to floating-point values, with no special mapping.
Index values outside the representable range of the color index buffer are not clamped. However, before an index is dithered (if enabled) and written to the frame buffer, it is converted to fixed-point format. Any bits in the integer portion of the resulting fixed-point value that do not correspond to bits in the frame buffer are masked out.
The current index can be updated at any time. In particular, glIndex can be called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_CURRENT_INDEX
glIndexMask - control the writing of individual bits in the color index buffers
void glIndexMask( GLuint mask )
glIndexMask controls the writing of individual bits in the color index buffers. The least significant n bits of mask, where n is the number of bits in a color index buffer, specify a mask. Wherever a one appears in the mask, the corresponding bit in the color index buffer (or buffers) is made writable. Where a zero appears, the bit is write-protected.
This mask is used only in color index mode, and it affects only the buffers currently selected for writing (see "glDrawBuffer".) Initially, all bits are enabled for writing.
GL_INVALID_OPERATION is generated if glIndexMask is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_INDEX_WRITEMASK
"glColorMask", "glDepthMask", "glDrawBuffer", "glIndex", "glStencilMask"
glIndexPointer - define an array of color indexes
void glIndexPointer( GLenum type, GLsizei stride, const GLvoid *pointer )
The glIndexPointer subroutine specifies the location and data format of an array of color indexes to use when rendering. The type parameter specifies the data type of each color index and stride gives the byte stride from one color index to the next allowing vertexes 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.)
The parameters type, stride, and pointer are saved as client-side state.
The color index array is initially disabled. To enable and disable the array, call glEnableClientState and glDisableClientState with the argument GL_INDEX_ARRAY. If enabled, the color index array is used when glDrawArrays, glDrawElements or glArrayElement is called.
Use glDrawArrays to construct a sequence of primitives (all of the same type) from prespecified vertex and vertex attribute arrays. Use glArrayElement to specify primitives by indexing vertexes and vertex attributes and glDrawElements to construct a sequence of primitives by indexing vertexes and vertex attributes.
The glIndexPointer subroutine is available only if the GL version is 1.1 or greater.
The color index array is initially disabled, and it won't be accessed when glArrayElement, glDrawElements or glDrawArrays is called.
Execution of glIndexPointer 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.
The glIndexPointer subroutine is typically implemented on the client side with no protocol.
Since the color index array parameters are client side state, they are not saved or restored by glPushAttrib and glPopAttrib. Use glPushClientAttrib and glPopClientAttrib instead.
The glIndexPointer subroutine is not included in display lists.
GL_INVALID_ENUM is generated if type is not an accepted value.
GL_INVALID_VALUE is generated if stride is negative.
glIsEnabled with argument GL_INDEX_ARRAY
glGet with argument GL_INDEX_ARRAY_TYPE
glGet with argument GL_INDEX_ARRAY_STRIDE
glGetPointerv with argument GL_INDEX_ARRAY_POINTER
"glArrayElement", "glColorPointer", "glDrawArrays", "glDrawElements", "glEdgeFlagPointer", "glGetPointerv", "glNormalPointer", "glPopClientAttrib", "glPushClientAttrib", "glTexCoordPointer", "glVertexPointer"
glInitNames - initialize the name stack
void glInitNames( void )
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. glInitNames causes the name stack to be initialized to its default empty state.
The name stack is always empty while the render mode is not GL_SELECT. Calls to glInitNames while the render mode is not GL_SELECT are ignored.
GL_INVALID_OPERATION is generated if glInitNames is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_NAME_STACK_DEPTH
glGet with argument GL_MAX_NAME_STACK_DEPTH
"glLoadName", "glPushName", "glRenderMode", "glSelectBuffer"
glInterleavedArrays - simultaneously specify and enable several interleaved arrays
void glInterleavedArrays( GLenum format, GLsizei stride, const GLvoid *pointer )
The glInterleavedArrays subroutine lets you specify and enable individual color, normal, texture and vertex arrays whose elements are part of a larger aggregate array element. For some implementations, this is more efficient than specifying the arrays seperately.
If stride is zero then the aggregate element are stored consecutively, otherwise stride bytes occur between aggregate array elements.
The format enumerant serves as a 'key' describing the extraction of individual arrays from the aggregate array. If format contains a T, then texture coordinates are extracted from the interleaved array. If C is present, color values are extracted. If N is present, normal coordinates are extracted; Vertex coordinates are always extracted.
The digits 2, 3, and 4 denote how many values are extracted. F indicates that values are extracted as floating point values. Colors may also be extracted as 4 unsigned bytes if 4UB follows the C. If a color is extracted as 4 unsigned bytes, the vertex array element which follows is located at the first possible floating point aligned address.
The glInterleavedArrays subroutine is available only if the GL version is 1.1 or greater.
If glInterleavedArrays is called while compiling a display list, it is not compiled into the list, and it is executed immediately.
Execution of glInterleavedArrays 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.
The glInterleavedArrays subroutine is typically implemented on the client side with no protocol.
Since the vertex array parameters are client side state, they are not saved or restored by glPushAttrib and glPopAttrib. Use glPushClientAttrib and glPopClientAttrib instead.
GL_INVALID_ENUM is generated if format is not an accepted value.
GL_INVALID_VALUE is generated if stride is negative.
"glArrayElement", "glColorPointer", "glDrawArrays", "glDrawElements", "glEdgeFlagPointer", "glEnableClientState", "glGetPointerv", "glIndexPointer", "glNormalPointer", "glPopClientAttrib", "glPushClientAttrib", "glTexCoordPointer", "glVertexPointer"
glIsEnabled - test whether a capability is enabled
GLboolean glIsEnabled( GLenum cap )
glIsEnabled returns GL_TRUE if cap is an enabled capability and returns GL_FALSE otherwise. The following capabilities are accepted for cap:
If an error is generated, glIsEnabled returns zero.
GL_INVALID_ENUM is generated if cap is not an accepted value.
GL_INVALID_OPERATION is generated if glIsEnabled is called between a call to glBegin and the corresponding call to glEnd.
glIsList - test for display-list existence
GLboolean glIsList( GLuint list )
glIsList returns GL_TRUE if list is the name of a display list and returns GL_FALSE otherwise.
GL_INVALID_OPERATION is generated if glIsList is called between a call to glBegin and the corresponding call to glEnd.
"glCallList", "glCallLists", "glDeleteLists", "glGenLists", "glNewList"
glIsTexture - determine if a name corresponds to a texture
GLboolean glIsTexture( GLuint texture )
The glIsTexture subroutine returns GL_TRUE if texture is currently the name of a texture. If texture is zero, or is a non-zero value that is not currently the name of a texture, or if an error occurs, glIsTexture returns GL_FALSE.
The glIsTexture subroutine is not included in display lists.
The glIsTexture subroutine is available only if the GL version is 1.1 or greater.
GL_INVALID_OPERATION is generated if glIsTexture is executed between the execution of glBegin and the corresponding execution of glEnd.
"glBindTexture", "glDeleteTextures", "glGenTextures", "glGet", "glGetTexParameter", "glTexImage1D", "glTexImage2D", "glTexParameter"
glLightf, glLighti, glLightfv, glLightiv - set light source parameters
void glLightf( GLenum light, GLenum pname, GLfloat param )
void glLighti( GLenum light, GLenum pname, GLint param )
void glLightfv( GLenum light, GLenum pname, const GLfloat *params )
void glLightiv( GLenum light, GLenum pname, const GLint *params )
glLight sets the values of individual light source parameters. light names the light and is a symbolic name of the form GL_LIGHTi, where 0 ≤ i < GL_MAX_LIGHTS. pname specifies one of ten light source parameters, again by symbolic name. params is either a single value or a pointer to an array that contains the new values.
Lighting calculation is enabled and disabled using glEnable and glDisable with argument GL_LIGHTING. When lighting is enabled, light sources that are enabled contribute to the lighting calculation. Light source i is enabled and disabled using glEnable and glDisable with argument GL_LIGHTi.
The ten light parameters are as follows:
It is always the case that GL_LIGHTi = GL_LIGHT0 + i.
GL_INVALID_ENUM is generated if either light or pname is not an accepted value.
GL_INVALID_VALUE is generated if a spot exponent value is specified outside the range [0,128], or if spot cutoff is specified outside the range [0,90] (except for the special value 180), or if a negative attenuation factor is specified.
GL_INVALID_OPERATION is generated if glLight is called between a call to glBegin and the corresponding call to glEnd.
glGetLight
glIsEnabled with argument GL_LIGHTING
"glColorMaterial", "glLightModel", "glMaterial"
glLightModelf, glLightModeli, glLightModelfv, glLightModeliv - set the lighting model parameters
void glLightModelf( GLenum pname, GLfloat param )
void glLightModeli( GLenum pname, GLint param )
void glLightModelfv( GLenum pname, const GLfloat *params )
void glLightModeliv( GLenum pname, const GLint *params )
glLightModel sets the lighting model parameter. pname names a parameter and params gives the new value. There are three lighting model parameters:
In RGBA mode, the lighted color of a vertex is the sum of the material emission intensity, the product of the material ambient reflectance and the lighting model full-scene ambient intensity, and the contribution of each enabled light source. Each light source contributes the sum of three terms: ambient, diffuse, and specular. The ambient light source contribution is the product of the material ambient reflectance and the light's ambient intensity. The diffuse light source contribution is the product of the material diffuse reflectance, the light's diffuse intensity, and the dot product of the vertex's normal with the normalized vector from the vertex to the light source. The specular light source contribution is the product of the material specular reflectance, the light's specular intensity, and the dot product of the normalized vertex-to-eye and vertex-to-light vectors, raised to the power of the shininess of the material. All three light source contributions are attenuated equally based on the distance from the vertex to the light source and on light source direction, spread exponent, and spread cutoff angle. All dot products are replaced with zero if they evaluate to a negative value.
The alpha component of the resulting lighted color is set to the alpha value of the material diffuse reflectance.
In color index mode, the value of the lighted index of a vertex ranges from the ambient to the specular values passed to glMaterial using GL_COLOR_INDEXES. Diffuse and specular coefficients, computed with a (.30, .59, .11) weighting of the lights' colors, the shininess of the material, and the same reflection and attenuation equations as in the RGBA case, determine how much above ambient the resulting index is.
GL_INVALID_ENUM is generated if pname is not an accepted value.
GL_INVALID_OPERATION is generated if glLightModel is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_LIGHT_MODEL_AMBIENT
glGet with argument GL_LIGHT_MODEL_LOCAL_VIEWER
glGet with argument GL_LIGHT_MODEL_TWO_SIDE
glIsEnabled with argument GL_LIGHTING
glLineStipple - specify the line stipple pattern
void glLineStipple( GLint factor, GLushort pattern )
Line stippling masks out certain fragments produced by rasterization; those fragments will not be drawn. The masking is achieved by using three parameters: the 16-bit line stipple pattern pattern, the repeat count factor, and an integer stipple counter s.
Counter s is reset to zero whenever glBegin is called, and before each line segment of a glBegin(GL_LINES)/glEnd sequence is generated. It is incremented after each fragment of a unit width aliased line segment is generated, or after each i fragments of an i width line segment are generated. The i fragments associated with count s are masked out if
pattern bit (s factor) mod 16
is zero, otherwise these fragments are sent to the frame buffer. Bit zero of pattern is the least significant bit.
Antialiased lines are treated as a sequence of 1 × width rectangles for purposes of stippling. Rectangle s is rasterized or not based on the fragment rule described for aliased lines, counting rectangles rather than groups of fragments.
Line stippling is enabled or disabled using glEnable and glDisable with argument GL_LINE_STIPPLE. When enabled, the line stipple pattern is applied as described above. When disabled, it is as if the pattern were all ones. Initially, line stippling is disabled.
GL_INVALID_OPERATION is generated if glLineStipple is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_LINE_STIPPLE_PATTERN
glGet with argument GL_LINE_STIPPLE_REPEAT
glIsEnabled with argument GL_LINE_STIPPLE
"glLineWidth", "glPolygonStipple"
glLineWidth - specify the width of rasterized lines
void glLineWidth( GLfloat width )
glLineWidth specifies the rasterized width of both aliased and antialiased lines. Using a line width other than 1.0 has different effects, depending on whether line antialiasing is enabled. Line antialiasing is controlled by calling glEnable and glDisable with argument GL_LINE_SMOOTH.
If line antialiasing is disabled, the actual width is determined by rounding the supplied width to the nearest integer. (If the rounding results in the value 0, it is as if the line width were 1.) If | Dx | ≥ | Dy |, i pixels are filled in each column that is rasterized, where i is the rounded value of width. Otherwise, i pixels are filled in each row that is rasterized.
If antialiasing is enabled, line rasterization produces a fragment for each pixel square that intersects the region lying within the rectangle having width equal to the current line width, length equal to the actual length of the line, and centered on the mathematical line segment. The coverage value for each fragment is the window coordinate area of the intersection of the rectangular region with the corresponding pixel square. This value is saved and used in the final rasterization step.
Not all widths can be supported when line antialiasing is enabled. If an unsupported width is requested, the nearest supported width is used. Only width 1.0 is guaranteed to be supported; others depend on the implementation. The range of supported widths and the size difference between supported widths within the range can be queried by calling glGet with arguments GL_LINE_WIDTH_RANGE and GL_LINE_WIDTH_GRANULARITY.
The line width specified by glLineWidth is always returned when GL_LINE_WIDTH is queried. Clamping and rounding for aliased and antialiased lines have no effect on the specified value.
Non-antialiased line width 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 lines, rounded to the nearest integer value.
GL_INVALID_VALUE is generated if width is less than or equal to zero.
GL_INVALID_OPERATION is generated if glLineWidth is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_LINE_WIDTH
glGet with argument GL_LINE_WIDTH_RANGE
glGet with argument GL_LINE_WIDTH_GRANULARITY
glIsEnabled with argument GL_LINE_SMOOTH
glListBase - set the display-list base for glCallLists
void glListBase( GLuint base )
glCallLists specifies an array of offsets. Display-list names are generated by adding base to each offset. Names that reference valid display lists are executed; the others are ignored.
GL_INVALID_OPERATION is generated if glListBase is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_LIST_BASE
glLoadIdentity - replace the current matrix with the identity matrix
void glLoadIdentity( void )
glLoadIdentity replaces the current matrix with the identity matrix. It is semantically equivalent to calling glLoadMatrix with the identity matrix
but in some cases it is more efficient.
GL_INVALID_OPERATION is generated if glLoadIdentity is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_MATRIX_MODE
glGet with argument GL_MODELVIEW_MATRIX
glGet with argument GL_PROJECTION_MATRIX
glGet with argument GL_TEXTURE_MATRIX
"glLoadMatrix", "glMatrixMode", "glMultMatrix", "glPushMatrix"
glLoadMatrixd, glLoadMatrixf - replace the current matrix with an arbitrary matrix
void glLoadMatrixd( const GLdouble *m )
void glLoadMatrixf( const GLfloat *m )
glLoadMatrix replaces the current matrix with the one specified in m. The current matrix is the projection matrix, modelview matrix, or texture matrix, determined by the current matrix mode (see "glMatrixMode").
m points to a 4 × 4 matrix of single- or double-precision floating-point values stored in column-major order. That is, the matrix is stored as follows:
GL_INVALID_OPERATION is generated if glLoadMatrix is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_MATRIX_MODE
glGet with argument GL_MODELVIEW_MATRIX
glGet with argument GL_PROJECTION_MATRIX
glGet with argument GL_TEXTURE_MATRIX
"glLoadIdentity", "glMatrixMode", "glMultMatrix", "glPushMatrix"
glLoadName - load a name onto the name stack
void glLoadName( GLuint name )
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. glLoadName causes name to replace the value on the top of the name stack, which is initially empty.
The name stack is always empty while the render mode is not GL_SELECT. Calls to glLoadName while the render mode is not GL_SELECT are ignored.
GL_INVALID_OPERATION is generated if glLoadName is called while the name stack is empty.
GL_INVALID_OPERATION is generated if glLoadName is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_NAME_STACK_DEPTH
glGet with argument GL_MAX_NAME_STACK_DEPTH
"glInitNames", "glPushName", "glRenderMode", "glSelectBuffer"
glLogicOp - specify a logical pixel operation for color index rendering
void glLogicOp( GLenum opcode )
glLogicOp specifies a logical operation that, when enabled, is applied between the incoming color index and the color index at the corresponding location in the frame buffer. The logical operation is enabled or disabled with glEnable and glDisable using the symbolic constant GL_LOGIC_OP.
opcode is a symbolic constant chosen from the list below. In the explanation of the logical operations, s represents the incoming color index and d represents the index in the frame buffer. Standard C-language operators are used. As these bitwise operators suggest, the logical operation is applied independently to each bit pair of the source and destination indices.
| opcode | resulting value |
|---|---|
GL_CLEAR |
0 |
GL_SET |
1 |
GL_COPY |
s |
GL_COPY_INVERTED |
!s |
GL_NOOP |
d |
GL_INVERT |
!d |
GL_AND |
s & d |
GL_NAND |
!(s & d) |
GL_OR |
s | d |
GL_NOR |
!(s | d) |
GL_XOR |
s ^ d |
GL_EQUIV |
!(s ^ d) |
GL_AND_REVERSE |
s & !d |
GL_AND_INVERTED |
!s & d |
GL_OR_REVERSE |
s | !d |
GL_OR_INVERTED |
!s | d |
Logical pixel operations are not applied to RGBA color buffers.
When more than one color index buffer is enabled for drawing, logical operations are done separately for each enabled buffer, using for the destination index the contents of that buffer (see "glDrawBuffer").
opcode must be one of the sixteen accepted values. Other values result in an error.
GL_INVALID_ENUM is generated if opcode is not an accepted value.
GL_INVALID_OPERATION is generated if glLogicOp is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_LOGIC_OP_MODE
glIsEnabled with argument GL_LOGIC_OP
"glAlphaFunc", "glBlendFunc", "glDrawBuffer", "glEnable", "glStencilOp"
glMap1d, glMap1f - define a one-dimensional evaluator
void glMap1d( GLenum target, GLdouble u1, GLdouble u2,
GLint stride, GLint order, const GLdouble *points )
void glMap1f( GLenum target, GLfloat u1, GLfloat u2,
GLint stride, GLint order, const GLfloat *points )
Evaluators provide a way to use polynomial or rational polynomial mapping to produce vertices, normals, texture coordinates, and colors. The values produced by an evaluator are sent to further stages of GL processing just as if they had been presented using glVertex, glNormal, glTexCoord, and glColor commands, except that the generated values do not update the current normal, texture coordinates, or color.
All polynomial or rational polynomial splines of any degree (up to the maximum degree supported by the GL implementation) can be described using evaluators. These include almost all splines used in computer graphics, including B-splines, Bezier curves, Hermite splines, and so on.
Evaluators define curves based on Bernstein polynomials. Define p (û) as
where Ri is a control point and Bin (û) is the ith Bernstein polynomial of degree n (order = n + 1):
Recall that
glMap1 is used to define the basis and to specify what kind of values are produced. Once defined, a map can be enabled and disabled by calling glEnable and glDisable with the map name, one of the nine predefined values for target described below. glEvalCoord1 evaluates the one-dimensional maps that are enabled. When glEvalCoord1 presents a value u, the Bernstein functions are evaluated using û, where
target is a symbolic constant that indicates what kind of control points are provided in points, and what output is generated when the map is evaluated. It can assume one of nine predefined values:
stride, order, and points define the array addressing for accessing the control points. points is the location of the first control point, which occupies one, two, three, or four contiguous memory locations, depending on which map is being defined. order is the number of control points in the array. stride tells how many float or double locations to advance the internal memory pointer to reach the next control point.
As is the case with all GL commands that accept pointers to data, it is as if the contents of points were copied by glMap1 before it returned. Changes to the contents of points have no effect after glMap1 is called.
GL_INVALID_ENUM is generated if target is not an accepted value.
GL_INVALID_VALUE is generated if u1 is equal to u2.
GL_INVALID_VALUE is generated if stride is less than the number of values in a control point.
GL_INVALID_VALUE is generated if order is less than one or greater than GL_MAX_EVAL_ORDER.
GL_INVALID_OPERATION is generated if glMap1 is called between a call to glBegin and the corresponding call to glEnd.
glGetMap
glGet with argument GL_MAX_EVAL_ORDER
glIsEnabled with argument GL_MAP1_VERTEX_3
glIsEnabled with argument GL_MAP1_VERTEX_4
glIsEnabled with argument GL_MAP1_INDEX
glIsEnabled with argument GL_MAP1_COLOR_4
glIsEnabled with argument GL_MAP1_NORMAL
glIsEnabled with argument GL_MAP1_TEXTURE_COORD_1
glIsEnabled with argument GL_MAP1_TEXTURE_COORD_2
glIsEnabled with argument GL_MAP1_TEXTURE_COORD_3
glIsEnabled with argument GL_MAP1_TEXTURE_COORD_4
"glBegin", "glColor", "glEnable", "glEvalCoord", "glEvalMesh", "glEvalPoint", "glMap2", "glMapGrid", "glNormal", "glTexCoord", "glVertex"
glMap2d, glMap2f - define a two-dimensional evaluator
void glMap2d( GLenum target, GLdouble u1, GLdouble u2,
GLintustride, GLint uorder, GLdouble v1, GLdouble v2,
GLnt vstride, GLint vorder, const GLdouble *points )
void glMap2f( GLenum target, GLfloat u1, GLfloat u2,
GLint ustride, GLint uorder, GLfloat v1, GLfloat v2,
GLint vstride, GLint vorder, const GLfloat *points )
Evaluators provide a way to use polynomial or rational polynomial mapping to produce vertices, normals, texture coordinates, and colors. The values produced by an evaluator are sent on to further stages of GL processing just as if they had been presented using glVertex, glNormal, glTexCoord, and glColor commands, except that the generated values do not update the current normal, texture coordinates, or color.
All polynomial or rational polynomial splines of any degree (up to the maximum degree supported by the GL implementation) can be described using evaluators. These include almost all surfaces used in computer graphics, including B-spline surfaces, NURBS surfaces, Bezier surfaces, and so on.
Evaluators define surfaces based on bivariate Bernstein polynomials. Define
as
where Rij is a control point, Bin (û) is the ith Bernstein polynomial of degree
n (uorder = n + 1)
and Bjm ( v^ ) is the jth Bernstein polynomial of degree m (vorder = m + 1)
Recall that
glMap2 is used to define the basis and to specify what kind of values are produced. Once defined, a map can be enabled and disabled by calling glEnable and glDisable with the map name, one of the nine predefined values for target, described below. When glEvalCoord2 presents values u and v, the bivariate Bernstein polynomials are evaluated using û and v^, where
target is a symbolic constant that indicates what kind of control points are provided in points, and what output is generated when the map is evaluated. It can assume one of nine predefined values:
ustride, uorder, vstride, vorder, and points define the array addressing for accessing the control points. points is the location of the first control point, which occupies one, two, three, or four contiguous memory locations, depending on which map is being defined. There are uorder × vorder control points in the array. ustride tells how many float or double locations are skipped to advance the internal memory pointer from control point Ri j to control point R(i+1) j . vstride tells how many float or double locations are skipped to advance the internal memory pointer from control point Ri j to control point Ri (j+1) .
As is the case with all GL commands that accept pointers to data, it is as if the contents of points were copied by glMap2 before it returned. Changes to the contents of points have no effect after glMap2 is called.
GL_INVALID_ENUM is generated if target is not an accepted value.
GL_INVALID_VALUE is generated if u1 is equal to u2, or if v1 is equal to v2.
GL_INVALID_VALUE is generated if either ustride or vstride is less than the number of values in a control point.
GL_INVALID_VALUE is generated if either uorder or vorder is less than one or greater than GL_MAX_EVAL_ORDER.
GL_INVALID_OPERATION is generated if glMap2 is called between a call to glBegin and the corresponding call to glEnd.
glGetMap
glGet with argument GL_MAX_EVAL_ORDER
glIsEnabled with argument GL_MAP2_VERTEX_3
glIsEnabled with argument GL_MAP2_VERTEX_4
glIsEnabled with argument GL_MAP2_INDEX
glIsEnabled with argument GL_MAP2_COLOR_4
glIsEnabled with argument GL_MAP2_NORMAL
glIsEnabled with argument GL_MAP2_TEXTURE_COORD_1
glIsEnabled with argument GL_MAP2_TEXTURE_COORD_2
glIsEnabled with argument GL_MAP2_TEXTURE_COORD_3
glIsEnabled with argument GL_MAP2_TEXTURE_COORD_4
"glBegin", "glColor", "glEnable", "glEvalCoord", "glEvalMesh", "glEvalPoint", "glMap1", "glMapGrid", "glNormal", "glTexCoord", "glVertex"
glMapGrid1d, glMapGrid1f, glMapGrid2d, glMapGrid2f - define a one- or two-dimensional mesh
void glMapGrid1d( GLint un, GLdouble u1, GLdouble u2 )
void glMapGrid1f( GLint un, GLfloat u1, GLfloat u2 )
void glMapGrid2d( GLint un, GLdouble u1, GLdouble u2,
GLint vn, GLdouble v1, GLdouble v2 )
void glMapGrid2f( GLint un, GLfloat u1, GLfloat u2,
GLint vn, GLfloat v1, GLfloat v2 )
glMapGrid and glEvalMesh are used in tandem to efficiently generate and evaluate a series of evenly spaced map domain values. glEvalMesh steps through the integer domain of a one- or two-dimensional grid, whose range is the domain of the evaluation maps specified by glMap1 and glMap2.
glMapGrid1 and glMapGrid2 specify the linear grid mappings between the i (or i and j) integer grid coordinates, to the u (or u and v) floating-point evaluation map coordinates. See "glMap1" and "glMap2" for details of how u and v coordinates are evaluated.
glMapGrid1 specifies a single linear mapping such that integer grid coordinate 0 maps exactly to u1, and integer grid coordinate un maps exactly to u2. All other integer grid coordinates i are mapped such that
u=i(u2-u1)/un+u1
glMapGrid2 specifies two such linear mappings. One maps integer grid coordinate i=0 exactly to u1, and integer grid coordinate i=un exactly to u2. The other maps integer grid coordinate j=0 exactly to v1, and integer grid coordinate j=vn exactly to v2. Other integer grid coordinates i and j are mapped such that
u=i(u2-u1)/un+u1
v=j(v2-v1)/vn+v1
The mappings specified by glMapGrid are used identically by glEvalMesh and glEvalPoint.
GL_INVALID_VALUE is generated if either un or vn is not positive.
GL_INVALID_OPERATION is generated if glMapGrid is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_MAP1_GRID_DOMAIN
glGet with argument GL_MAP2_GRID_DOMAIN
glGet with argument GL_MAP1_GRID_SEGMENTS
glGet with argument GL_MAP2_GRID_SEGMENTS
"glEvalCoord", "glEvalMesh", "glEvalPoint", "glMap1", "glMap2"
glMaterialf, glMateriali, glMaterialfv, glMaterialiv - specify material parameters for the lighting model
void glMaterialf( GLenum face, GLenum pname, GLfloat param )
void glMateriali( GLenum face, GLenum pname, GLint param )
void glMaterialfv( GLenum face, GLenum pname, const GLfloat *params )
void glMaterialiv( GLenum face, GLenum pname, const GLint *params )
glMaterial assigns values to material parameters. There are two matched sets of material parameters. One, the front-facing set, is used to shade points, lines, bitmaps, and all polygons (when two-sided lighting is disabled), or just front-facing polygons (when two-sided lighting is enabled). The other set, back-facing, is used to shade back-facing polygons only when two-sided lighting is enabled. Refer to the glLightModel reference page for details concerning one- and two-sided lighting calculations.
glMaterial takes three arguments. The first, face, specifies whether the GL_FRONT materials, the GL_BACK materials, or both GL_FRONT_AND_BACK materials will be modified. The second, pname, specifies which of several parameters in one or both sets will be modified. The third, params, specifies what value or values will be assigned to the specified parameter.
Material parameters are used in the lighting equation that is optionally applied to each vertex. The equation is discussed in the glLightModel reference page. The parameters that can be specified using glMaterial, and their interpretations by the lighting equation, are as follows:
The material parameters can be updated at any time. In particular, glMaterial can be called between a call to glBegin and the corresponding call to glEnd. If only a single material parameter is to be changed per vertex, however, glColorMaterial is preferred over glMaterial (see "glColorMaterial").
GL_INVALID_ENUM is generated if either face or pname is not an accepted value.
GL_INVALID_VALUE is generated if a specular exponent outside the range [0,128] is specified.
"glColorMaterial", "glLight", "glLightModel"
glMatrixMode - specify which matrix is the current matrix
void glMatrixMode( GLenum mode )
glMatrixMode sets the current matrix mode. mode can assume one of three values:
GL_INVALID_ENUM is generated if mode is not an accepted value.
GL_INVALID_OPERATION is generated if glMatrixMode is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_MATRIX_MODE
"glLoadMatrix", "glPushMatrix"
glMultMatrixd, glMultMatrixf - multiply the current matrix by an arbitrary matrix
void glMultMatrixd( const GLdouble *m )
void glMultMatrixf( const GLfloat *m )
glMultMatrix multiplies the current matrix with the one specified in m. That is, if M is the current matrix and T is the matrix passed to glMultMatrix, then M is replaced with MT.
The current matrix is the projection matrix, modelview matrix, or texture matrix, determined by the current matrix mode (see "glMatrixMode").
m points to a 4 × 4 matrix of single- or double-precision floating-point values stored in column-major order. That is, the matrix is stored as
GL_INVALID_OPERATION is generated if glMultMatrix is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_MATRIX_MODE
glGet with argument GL_MODELVIEW_MATRIX
glGet with argument GL_PROJECTION_MATRIX
glGet with argument GL_TEXTURE_MATRIX
"glMatrixMode", "glLoadIdentity", "glLoadMatrix", "glPushMatrix"
glNewList, glEndList - create or replace a display list
void glNewList( GLuint list, GLenum mode )
void glEndList( void )
Display lists are groups of GL commands that have been stored for subsequent execution. The display lists are created with glNewList. All subsequent commands are placed in the display list, in the order issued, until glEndList is called.
glNewList has two arguments. The first argument, list, is a positive integer that becomes the unique name for the display list. Names can be created and reserved with glGenLists and tested for uniqueness with glIsList. The second argument, mode, is a symbolic constant that can assume one of two values:
Certain commands are not compiled into the display list, but are executed immediately, regardless of the display-list mode. These commands are glIsList, glGenLists, glDeleteLists, glFeedbackBuffer, glSelectBuffer, glRenderMode, glReadPixels, glPixelStore, glFlush, glFinish, glIsEnabled, and all of the glGet routines.
When glEndList is encountered, the display-list definition is completed by associating the list with the unique name list (specified in the glNewList command). If a display list with name list already exists, it is replaced only when glEndList is called.
glCallList and glCallLists can be entered into display lists. The commands in the display list or lists executed by glCallList or glCallLists are not included in the display list being created, even if the list creation mode is GL_COMPILE_AND_EXECUTE.
GL_INVALID_VALUE is generated if list is zero.
GL_INVALID_ENUM is generated if mode is not an accepted value.
GL_INVALID_OPERATION is generated if glEndList is called without a preceding glNewList, or if glNewList is called while a display list is being defined.
GL_INVALID_OPERATION is generated if glNewList is called between a call to glBegin and the corresponding call to glEnd.
"glCallList", "glCallLists", "glDeleteLists", "glGenLists"
glNormal3b, glNormal3d, glNormal3f, glNormal3i, glNormal3s, glNormal3bv, glNormal3dv, glNormal3fv, glNormal3iv, glNormal3sv - set the current normal vector
void glNormal3b( GLbyte nx, GLbyte ny, GLbyte nz )
void glNormal3d( GLdouble nx, GLdouble ny, GLdouble nz )
void glNormal3f( GLfloat nx, GLfloat ny, GLfloat nz )
void glNormal3i( GLint nx, GLint ny, GLint nz )
void glNormal3s( GLshort nx, GLshort ny, GLshort nz )
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 )
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 normalization is enabled, then normals specified with glNormal are normalized after transformation. Normalization is controlled using glEnable and glDisable with the argument GL_NORMALIZE. By default, normalization is disabled.
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.
glGet with argument GL_CURRENT_NORMAL
glIsEnabled with argument GL_NORMALIZE
"glBegin", "glColor", "glIndex", "glTexCoord", "glVertex"
glNormalPointer - define an array of normals
void glNormalPointer( GLenum type, GLsizei stride, const GLvoid *pointer )
The glNormalPointer subroutine specifies the location and data format of an array of normals to use when rendering. The type parameter specifies the data type of the normal coordinates and stride gives the byte stride from one normal to the next allowing vertexes 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). When a normal array is specified, type, stride, and pointer are saved as client side state.
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, glDrawElements or glArrayElement is called.
Use glDrawArrays to constructe a sequence of primitives (all of the same type) from prespecified vertex and vertex attribute arrays. Use glArrayElement to specify primitives by indexing vertexes and vertex attributes and glDrawElements to construct a sequence of primitives by indexing vertexes and vertex attributes.
The glNormalPointer subroutine is available only if the GL version is 1.1 or greater.
The normal array is initially disabled and it won't be accessed when glArrayElement, glDrawElements or glDrawArrays 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.
The glNormalPointer subroutine is typically implemented on the client side with no protocol.
Since the normal array parameters are client side state, they are not saved or restored by glPushAttrib and glPopAttrib. Use glPushClientAttrib and glPopClientAttrib instead.
The glNormalPointer subroutine is not included in display lists.
GL_INVALID_ENUM is generated if type is not an accepted value.
GL_INVALID_VALUE is generated if stride is negative.
glIsEnabled with argument GL_NORMAL_ARRAY
glGet with argument GL_NORMAL_ARRAY_TYPE
glGet with argument GL_NORMAL_ARRAY_STRIDE
glGetPointerv with argument GL_NORMAL_ARRAY_POINTER
"glArrayElement", "glColorPointer", "glDrawArrays", "glDrawElements", "glEdgeFlagPointer", "glGetPointerv", "glIndexPointer", "glPopClientAttrib", "glPushClientAttrib", "glTexCoordPointer", "glVertexPointer"
glOrtho - multiply the current matrix by an orthographic matrix
void glOrtho( GLdouble left, GLdouble right, GLdouble bottom, GLdouble top, GLdouble near, GLdouble far )
glOrtho describes a perspective matrix that produces a parallel projection. (left, bottom, -near) and (right, top, -near) 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). -far specifies the location of the far clipping plane. Both near and far can be either positive or negative. The corresponding matrix is
where
The current matrix is multiplied by this matrix with the result replacing the current matrix. That is, if M is the current matrix and O is the ortho matrix, then M is replaced with M o O.
Use glPushMatrix and glPopMatrix to save and restore the current matrix stack.
GL_INVALID_OPERATION is generated if glOrtho is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_MATRIX_MODE
glGet with argument GL_MODELVIEW_MATRIX
glGet with argument GL_PROJECTION_MATRIX
glGet with argument GL_TEXTURE_MATRIX
"glFrustum", "glMatrixMode", "glMultMatrix", "glPushMatrix", "glViewport"
glPassThrough - place a marker in the feedback buffer
void glPassThrough( GLfloat token )
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 "glFeedbackBuffer" 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.
glPassThrough is ignored if the GL is not in feedback mode.
GL_INVALID_OPERATION is generated if glPassThrough is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_RENDER_MODE
"glFeedbackBuffer", "glRenderMode"
glPixelMapfv, glPixelMapuiv, glPixelMapusv - set up pixel transfer maps
void glPixelMapfv( GLenum map, GLint mapsize,
const GLfloat *values )
void glPixelMapuiv( GLenum map, GLint mapsize,
const GLuint *values )
void glPixelMapusv( GLenum map, GLint mapsize,
const GLushort *values )
glPixelMap sets up translation tables, or maps, used by glDrawPixels, glReadPixels, glCopyPixels, glTexImage1D, and glTexImage2D. 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.
The ten maps are as follows:
The entries in a map can be specified as single-precision floating-point numbers, unsigned short integers, or unsigned long 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 zero 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 zeros to the right of the binary point.
The table below 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 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, and it is at least 32.
| map | lookup index | lookup value | initial size | initial value |
|---|---|---|---|---|
GL_PIXEL_MAP_I_TO_I |
color index |
color index |
1 |
0.0 |
GL_PIXEL_MAP_S_TO_S |
stencil index |
stencil index |
1 |
0 |
GL_PIXEL_MAP_I_TO_R |
color index |
R |
1 |
0.0 |
GL_PIXEL_MAP_I_TO_G |
color index |
G |
1 |
0.0 |
GL_PIXEL_MAP_I_TO_B |
color index |
B |
1 |
0.0 |
GL_PIXEL_MAP_I_TO_A |
color index |
A |
1 |
0.0 |
GL_PIXEL_MAP_R_TO_R |
R |
R |
1 |
0.0 |
GL_PIXEL_MAP_G_TO_G |
G |
G |
1 |
0.0 |
GL_PIXEL_MAP_B_TO_B |
B |
B |
1 |
0.0 |
GL_PIXEL_MAP_A_TO_A |
A |
A |
1 |
0.0 |
GL_INVALID_ENUM is generated if map is not an accepted value.
GL_INVALID_VALUE is generated if mapsize is negative 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 glPixelMap is called between a call to glBegin and the corresponding call to glEnd.
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
"glCopyPixels", "glDrawPixels", "glPixelStore", "glPixelTransfer", "glReadPixels", "glTexImage1D", "glTexImage2D"
glPixelStoref, glPixelStorei - set pixel storage modes
void glPixelStoref( GLenum pname, GLfloat param )
void glPixelStorei( GLenum pname, GLint param )
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"), and texture patterns (see "glTexImage1D" and "glTexImage2D").
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, and are therefore significant only for glReadPixels commands. They are as follows:
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, glBitmap, and glPolygonStipple. They are as follows:
The following table gives the type, initial value, and range of valid values for each of the storage parameters that can be set with glPixelStore.
| pname | type | initial value | valid range |
|---|---|---|---|
GL_PACK_SWAP_BYTES |
Boolean |
false |
true or false |
GL_PACK_LSB_FIRST |
Boolean |
false |
true or false |
GL_PACK_ROW_LENGTH |
integer |
0 |
[0, inf) |
GL_PACK_SKIP_ROWS |
integer |
0 |
[0, inf) |
GL_PACK_SKIP_PIXELS |
integer |
0 |
[0, inf) |
GL_PACK_ALIGNMENT |
integer |
4 |
1, 2, 4, or 8 |
GL_UNPACK_SWAP_BYTES |
Boolean |
false |
true or false |
GL_UNPACK_LSB_FIRST |
Boolean |
false |
true or false |
GL_UNPACK_ROW_LENGTH |
integer |
0 |
[0, inf) |
GL_UNPACK_SKIP_ROWS |
integer |
0 |
[0, inf) |
GL_UNPACK_SKIP_PIXELS |
integer |
0 |
[0, inf) |
GL_UNPACK_ALIGNMENT |
integer |
4 |
1, 2, 4, or 8 |
glPixelStoref can be used to set any pixel store parameter. If the parameter type is Boolean, then if param is 0.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. param is converted to floating point before being assigned to real-valued parameters.
The pixel storage modes in effect when glDrawPixels, glReadPixels, glTexImage1D, glTexImage2D, glBitmap, or glPolygonStipple 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.
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 called between a call to glBegin and the corresponding call to glEnd.
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_SKIP_ROWS
glGet with argument GL_PACK_SKIP_PIXELS
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_SKIP_ROWS
glGet with argument GL_UNPACK_SKIP_PIXELS
glGet with argument GL_UNPACK_ALIGNMENT
"glBitmap", "glDrawPixels", "glPixelMap", "glPixelTransfer", "glPixelZoom", "glPolygonStipple", "glReadPixels", "glTexImage1D", "glTexImage2D"
glPixelTransferf, glPixelTransferi - set pixel transfer modes
void glPixelTransferf( GLenum pname, GLfloat param )
void glPixelTransferi( GLenum pname, GLint param )
glPixelTransfer sets pixel transfer modes that affect the operation of subsequent glDrawPixels, glReadPixels, glCopyPixels, glTexImage1D, and glTexImage2D commands. The algorithms that are specified by pixel transfer modes operate on pixels after they are read from the frame buffer (glReadPixels and glCopyPixels) or unpacked from client memory (glDrawPixels, glTexImage1D, and glTexImage2D). 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 are made up of four floating-point values with unspecified mantissa and exponent sizes, scaled such that 0.0 represents zero intensity and 1.0 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:
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.
| pname | type | initial value | valid range |
|---|---|---|---|
GL_MAP_COLOR |
Boolean |
false |
true/false |
GL_MAP_STENCIL |
Boolean |
false |
true/false |
GL_INDEX_SHIFT |
integer |
0 |
(-inf, inf) |
GL_INDEX_OFFSET |
integer |
0 |
(-inf, inf) |
GL_RED_SCALE |
float |
1.0 |
(-inf, inf) |
GL_GREEN_SCALE |
float |
1.0 |
(-inf, inf) |
GL_BLUE_SCALE |
float |
1.0 |
(-inf, inf) |
GL_ALPHA_SCALE |
float |
1.0 |
(-inf, inf) |
GL_DEPTH_SCALE |
float |
1.0 |
(-inf, inf) |
GL_RED_BIAS |
float |
0.0 |
(-inf, inf) |
GL_GREEN_BIAS |
float |
0.0 |
(-inf, inf) |
GL_BLUE_BIAS |
float |
0.0 |
(-inf, inf) |
GL_ALPHA_BIAS |
float |
0.0 |
(-inf, inf) |
GL_DEPTH_BIAS |
float |
0.0 |
(-inf, inf) |
glPixelTransferf can be used to set any pixel transfer parameter. If the parameter type is Boolean, 0.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 also be used to set any of the pixel transfer parameters. Boolean parameters are set to false if param is 0 and true otherwise. param is converted to floating point before being assigned to real-valued parameters.
If a glDrawPixels, glReadPixels, glCopyPixels, glTexImage1D, or glTexImage2D 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.
GL_INVALID_ENUM is generated if pname is not an accepted value.
GL_INVALID_OPERATION is generated if glPixelTransfer is called between a call to glBegin and the corresponding call to glEnd.
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
"glCallList", "glCopyPixels", "glDrawPixels", "glNewList", "glPixelMap", "glPixelStore", "glPixelZoom", "glReadPixels", "glTexImage1D", "glTexImage2D"
glPixelZoom - specify the pixel zoom factors
void glPixelZoom( GLfloat xfactor, GLfloat yfactor )
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 nth row and mth 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.
GL_INVALID_OPERATION is generated if glPixelZoom is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_ZOOM_X
glGet with argument GL_ZOOM_Y
"glCopyPixels", "glDrawPixels"
glPointSize - specify the diameter of rasterized points
void glPointSize( GLfloat size )
glPointSize specifies the rasterized diameter of both aliased and antialiased points. Using a point size other than 1.0 has different effects, depending on whether point antialiasing is enabled. Point antialiasing is controlled by calling glEnable and glDisable with argument GL_POINT_SMOOTH.
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
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
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.0 is guaranteed to be supported; others depend on the implementation. The range of supported sizes and the size difference between supported sizes within the range can be queried by calling glGet with arguments GL_POINT_SIZE_RANGE and GL_POINT_SIZE_GRANULARITY.
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.
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_INVALID_VALUE is generated if size is less than or equal to zero.
GL_INVALID_OPERATION is generated if glPointSize is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_POINT_SIZE
glGet with argument GL_POINT_SIZE_RANGE
glGet with argument GL_POINT_SIZE_GRANULARITY
glIsEnabled with argument GL_POINT_SMOOTH
glPolygonMode - select a polygon rasterization mode
void glPolygonMode( GLenum face, GLenum mode )
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:
To draw a surface with filled back-facing polygons and outlined front-facing polygons, call
glPolygonMode(GL_FRONT, GL_LINE);
Vertices are marked as boundary or nonboundary with an edge flag. Edge flags are generated internally by the GL when it decomposes polygons, and they can be set explicitly using glEdgeFlag.
GL_INVALID_ENUM is generated if either face or mode is not an accepted value.
GL_INVALID_OPERATION is generated if glPolygonMode is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_POLYGON_MODE
"glBegin", "glEdgeFlag", "glLineStipple", "glLineWidth", "glPointSize", "glPolygonStipple"
glPolygonOffset - set the scale and bias used to calculate depth values
void glPolygonOffset( GLfloat factor, GLfloat units )
When GL_POLYGON_OFFSET 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 which is guaranteed to produce a resolveable 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.
This is useful for rendering hidden line images, for applying decals to surfaces, and for rendering solids with highlighted edges.
The glPolygonOffset subroutine is available only if the GL version is 1.1 or greater.
GL_INVALID_OPERATION is generated if glPolygonOffset is executed between the execution of glBegin and the corresponding execution of glEnd.
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.
"glDepthFunc", "glDisable", "glEnable", "glGet", "glIsEnabled", "glLineWidth", "glStencilOp", "glTexEnv"
glPolygonStipple - set the polygon stippling pattern
void glPolygonStipple( const GLubyte *mask )
Polygon stippling, like line stippling (see "glLineStipple"), masks out certain fragments produced by rasterization, creating a pattern. Stippling is independent of polygon antialiasing.
mask is a pointer to a 32 × 32 stipple pattern that is stored in memory just like the pixel data supplied to a glDrawPixels 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.
Polygon stippling is enabled and disabled with glEnable and glDisable, using argument GL_POLYGON_STIPPLE. If 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 mod 32)th bit in the (yw mod 32)th row of the stipple pattern is one. When polygon stippling is disabled, it is as if the stipple pattern were all ones.
GL_INVALID_OPERATION is generated if glPolygonStipple is called between a call to glBegin and the corresponding call to glEnd.
glGetPolygonStipple
glIsEnabled with argument GL_POLYGON_STIPPLE
"glDrawPixels", "glLineStipple", "glPixelStore", "glPixelTransfer"
glPrioritizeTextures - set texture residence priority
void glPrioritizeTextures( GLsizei n, const GLuint *textures, const GLclampf *priorities )
The glPrioritizeTextures subroutine assigns the n texture priorities given in priorities to the n textures named in textures.
On machines with a limited amount of texture memory, 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.0, 1.0] before being assigned. Zero indicates the lowest priority; textures with priority zero are least likely to be resident. One indicates the highest priority; textures with priority one are most likely to be resident. However, textures are not guaranteed to be resident until they are bound.
The glPrioritizeTextures subroutine silently ignores attempts to prioritize texture zero, or any texture name that does not correspond to an existing texture.
The glPrioritizeTextures subroutine does not require that any of the textures named by textures be bound to a texture target. It can also be used to set the priority of a texture, but only if the texture is currently bound. This is the only way to set the priority of a default texture.
The glPrioritizeTextures subroutine is included in display lists.
The glPrioritizeTextures subroutine is available only if the GL version is 1.1 or greater.
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.
glGetTexParameter with parameter name GL_TEXTURE_PRIORITY retrieves the priority of a currently bound texture.
"glAreTexturesResident", "glBindTexture", "glTexParameter"
glPushAttrib, glPopAttrib - push and pop the attribute stack
void glPushAttrib( GLbitfield mask )
void glPopAttrib( void )
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 ORing 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.
Not all values for GL state can be saved on the attribute stack. For example, pixel pack and unpack state, render mode state, and select and feedback state cannot be saved.
The depth of the attribute stack depends on the implementation, but it must be at least 16.
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 is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_ATTRIB_STACK_DEPTH
glGet with argument GL_MAX_ATTRIB_STACK_DEPTH
"glGet", "glGetClipPlane", "glGetError", "glGetLight", "glGetMap", "glGetMaterial", "glGetPixelMap", "glGetPolygonStipple", "glGetString", "glGetTexEnv", "glGetTexGen", "glGetTexImage", "glGetTexLevelParameter", "glGetTexParameter", "glIsEnabled"
glPushClientAttrib, glPopClientAttrib - push and pop the attribute stack
void glPushClientAttrib( GLbitfield mask )
void glPopClientAttrib( void )
The glPushClientAttrib subroutine 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. The mask parameter is typically constructed by OR'ing 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):
The glPopClientAttrib subroutine 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.
The glPushClientAttrib subroutine 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.
The glPushClientAttrib and glPopClientAttrib subroutines are not compiled into display lists, but are executed immediately.
Use glPushAttrib and glPopAttrib to push and restore state which is kept on the server. Only pixel storage modes and vertex array state may be pushed and popped with glPushClientAttrib and glPopClientAttrib.
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.
glGet with argument GL_ATTRIB_STACK_DEPTH
glGet with argument GL_MAX_CLIENT_ATTRIB_STACK_DEPTH
"glColorPointer", "glDisableClientState", "glEdgeFlagPointer", "glEnableClientState", "glGet", "glIndexPointer", "glNormalPointer", "glPixelStore", "glTexCoordPointer", "glVertexPointer"
glPushMatrix, glPopMatrix - push and pop the current matrix stack
void glPushMatrix( void )
void glPopMatrix( void )
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 two modes, 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 the 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.
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 is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_MATRIX_MODE
glGet with argument GL_MODELVIEW_MATRIX
glGet with argument GL_PROJECTION_MATRIX
glGet with argument GL_TEXTURE_MATRIX
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
"glFrustum", "glLoadIdentity", "glLoadMatrix", "glMatrixMode", "glMultMatrix", "glOrtho", "glRotate", "glScale", "glTranslate", "glViewport"
glPushName, glPopName - push and pop the name stack
void glPushName( GLuint name )
void glPopName( void )
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. glPushName causes name to be pushed onto the name stack, which is initially empty. glPopName pops one name off the top of the stack.
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 a call to glBegin and the corresponding call to 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.
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 called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_NAME_STACK_DEPTH
glGet with argument GL_MAX_NAME_STACK_DEPTH
"glInitNames", "glLoadName", "glRenderMode", "glSelectBuffer"
glRasterPos2d, glRasterPos2f, glRasterPos2i, glRasterPos2s, glRasterPos3d, glRasterPos3f, glRasterPos3i, glRasterPos3s, glRasterPos4d, glRasterPos4f, glRasterPos4i, glRasterPos4s, glRasterPos2dv, glRasterPos2fv, glRasterPos2iv, glRasterPos2sv, glRasterPos3dv, glRasterPos3fv, glRasterPos3iv, glRasterPos3sv, glRasterPos4dv, glRasterPos4fv, glRasterPos4iv, glRasterPos4sv - specify the raster position for pixel operations
void glRasterPos2d( GLdouble x, GLdouble y )
void glRasterPos2f( GLfloat x, GLfloat y )
void glRasterPos2i( GLint x, GLint y )
void glRasterPos2s( GLshort x, GLshort y )
void glRasterPos3d( GLdouble x, GLdouble y, Ldouble z )
void glRasterPos3f( GLfloat x, GLfloat y, GLfloat z )
void glRasterPos3i( GLint x, GLint y, GLint z )
void glRasterPos3s( GLshort x, GLshort y, GLshort z )
void glRasterPos4d( GLdouble x, GLdouble y, GLdouble z,
GLdouble w )
void glRasterPos4f( GLfloat x, GLfloat y, GLfloat z,
GLfloat w )
void glRasterPos4i( GLint x, GLint y, GLint z,
GLint w )
void glRasterPos4s( GLshort x, GLshort y GLshort z,
GLshort w )
void glRasterPos2dv( const GLdouble *v )
void glRasterPos2fv( const GLfloat *v )
void glRasterPos2iv( const GLint *v )
void glRasterPos2sv( const GLshort *v )
void glRasterPos3dv( const GLdouble *v )
void glRasterPos3fv( const GLfloat *v )
void glRasterPos3iv( const GLint *v )
void glRasterPos3sv( const GLshort *v )
void glRasterPos4dv( const GLdouble *v )
void glRasterPos4fv( const GLfloat *v )
void glRasterPos4iv( const GLint *v )
void glRasterPos4sv( const GLshort *v )
The GL maintains a 3-D position in window coordinates. This position, called the raster position, is maintained with subpixel accuracy. It is used to position pixel and bitmap write operations. See "glBitmap", "glDrawPixels", and "glCopyPixels".
The current raster position consists of three window coordinates (x, y, z), a clip coordinate w value, 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 one. glRasterPos2 uses the argument values for x and y while implicitly setting z and w to zero and one.
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 the 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.
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.
The raster position is modified both by glRasterPos and by glBitmap.
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).
GL_INVALID_OPERATION is generated if glRasterPos is called between a call to glBegin and the corresponding call to glEnd.
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_INDEX
glGet with argument GL_CURRENT_RASTER_TEXTURE_COORDS
"glBitmap", "glCopyPixels", "glDrawPixels", "glLight", "glLightModel", "glShadeModel", "glTexCoord", "glTexGen", "glVertex"
glReadBuffer - select a color buffer source for pixels
void glReadBuffer( GLenum mode )
glReadBuffer specifies a color buffer as the source for subsequent glReadPixels 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 configurations have only a left buffer, or a front left and a back left buffer if double-buffered. Single-buffered configurations have only a front buffer, or a front left and a front right buffer if stereo. It is an error to specify a nonexistent buffer to glReadBuffer.
By default, mode is GL_FRONT in single-buffered configurations, and GL_BACK in double-buffered configurations.
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 called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_READ_BUFFER
"glCopyPixels", "glDrawBuffer", "glReadPixels"
glReadPixels - read a block of pixels from the frame buffer
void glReadPixels( GLint x, GLint y, GLsizei width, GLsizei height, GLenum format, GLenum type, GLvoid *pixels )
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 pixels. 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.
glReadPixels returns values from each pixel with lower left-hand 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 for format are as follows:
The shift, scale, bias, and lookup factors described above are all specified by glPixelTransfer. The lookup table contents themselves are specified by glPixelMap.
The final step involves converting the indices or components 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_RGBA, 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).
| type | index mask | component conversion |
|---|---|---|
GL_UNSIGNED_BYTE |
28 - 1 |
(28 - 1) c |
GL_BYTE |
27 - 1 |
[(27 - 1) c - 1] / 2 |
GL_BITMAP |
1 |
1 |
GL_UNSIGNED_SHORT |
216 - 1 |
(216 - 1) c |
GL_SHORT |
215 - 1 |
[(215 - 1) c - 1] / 2 |
GL_UNSIGNED_INT |
232 - 1 |
(232 - 1) c |
GL_INT |
231 - 1 |
[(231 - 1) c - 1] / 2 |
GL_FLOAT |
none |
c |
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 returns three values, GL_RGBA returns four values, and GL_LUMINANCE_ALPHA returns two values for each pixel, with all values corresponding to a single pixel occupying contiguous space in pixels. Storage parameters set by glPixelStore, such as GL_PACK_SWAP_BYTES and GL_PACK_LSB_FIRST, affect the way that data is written into memory. See "glPixelStore" for a description.
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 pixels.
GL_INVALID_ENUM is generated if format or type is not an accepted value.
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 glReadPixels is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_INDEX_MODE
"glCopyPixels", "glDrawPixels", "glPixelMap", "glPixelStore", "glPixelTransfer", "glReadBuffer"
glRectd, glRectf, glRecti, glRects, glRectdv, glRectfv, glRectiv, glRectsv - draw a rectangle
void glRectd( GLdouble x1, GLdouble y1, GLdouble x2,
GLdouble y2 )
void glRectf( GLfloat x1, GLfloat y1, GLfloat x2,
GLfloat y2 )
void glRecti( GLint x1, GLint y1, GLint x2,
GLint y2 )
void glRects( GLshort x1, GLshort y1, GLshort x2,
GLshort y2 )
void glRectdv( const GLdouble *v1, const GLdouble *v2 )
void glRectfv( const GLfloat *v1, const GLfloat *v2 )
void glRectiv( const GLint *v1, const GLint *v2 )
void glRectsv( const GLshort *v1, const GLshort *v2 )
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.
GL_INVALID_OPERATION is generated if glRect is called between a call to glBegin and the corresponding call to glEnd.
glRenderMode - set rasterization mode
GLint glRenderMode( GLenum mode )
glRenderMode sets the rasterization mode. It takes one argument, mode, which can assume one of three predefined values:
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:
Refer to the glSelectBuffer and glFeedbackBuffer reference pages for more details concerning selection and feedback operation.
If an error is generated, glRenderMode returns zero regardless of the current render mode.
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 called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_RENDER_MODE
"glFeedbackBuffer", "glInitNames", "glLoadName", "glPassThrough", "glPushName", "glSelectBuffer"
glRotated, glRotatef - multiply the current matrix by a rotation matrix
void glRotated( GLdouble angle, GLdouble x, GLdouble y,
GLdouble z )
void glRotatef( GLfloat angle, GLfloat x, GLfloat y,
GLfloat z )
glRotate computes a matrix that performs a counterclockwise rotation of angle degrees about the vector from the origin through the point (x, y, z).
The current matrix (see "glMatrixMode") is multiplied by this rotation matrix, with the product replacing the current matrix. That is, if M is the current matrix and R is the translation matrix, then M is replaced with M o R.
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.
GL_INVALID_OPERATION is generated if glRotate is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_MATRIX_MODE
glGet with argument GL_MODELVIEW_MATRIX
glGet with argument GL_PROJECTION_MATRIX
glGet with argument GL_TEXTURE_MATRIX
"glMatrixMode", "glMultMatrix", "glPushMatrix", "glScale", "glTranslate"
glScaled, glScalef - multiply the current matrix by a general scaling matrix
void glScaled( GLdouble x, GLdouble y, GLdouble z )
void glScalef( GLfloat x, GLfloat y, GLfloat z )
glScale produces a general scaling along the x, y, and z axes. The three arguments indicate the desired scale factors along each of the three axes. The resulting matrix is
The current matrix (see "glMatrixMode") is multiplied by this scale matrix, with the product replacing the current matrix. That is, if M is the current matrix and S is the scale matrix, then M is replaced with M o S.
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.
If scale factors other than 1.0 are applied to the modelview matrix and lighting is enabled, automatic normalization of normals should probably also be enabled (glEnable and glDisable with argument GL_NORMALIZE).
GL_INVALID_OPERATION is generated if glScale is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_MATRIX_MODE
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
void glScissor( GLint x, GLint y, GLsizei width, GLsizei height )
The glScissor routine 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.
The scissor test is enabled and disabled using glEnable and glDisable with argument GL_SCISSOR_TEST. While the scissor 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, so glScissor(0,0,1,1) allows only the lower left pixel in the window to be modified, and glScissor(0,0,0,0) disallows modification to all pixels in the window.
When the scissor test is disabled, it is as though the scissor box includes the entire window.
GL_INVALID_VALUE is generated if either width or height is negative.
GL_INVALID_OPERATION is generated if glScissor is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_SCISSOR_BOX
glIsEnabled with argument GL_SCISSOR_TEST
glSelectBuffer - establish a buffer for selection mode values
void glSelectBuffer( GLsizei size, GLuint *buffer )
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.
Selection is used by a programmer 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 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.
Returned depth values are mapped such that the largest unsigned integer value corresponds to window coordinate depth 1.0, and zero corresponds to window coordinate depth 0.0.
An internal index into buffer is reset to zero 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 - that 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 zero followed by the minimum and maximum depth values.
Selection mode is exited by calling 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.
The contents of buffer are undefined until glRenderMode is called with an argument other than GL_SELECT.
glBegin/glEnd primitives and calls to glRasterPos can result in hits.
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 called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_NAME_STACK_DEPTH
"glFeedbackBuffer", "glInitNames", "glLoadName", "glPushName", "glRenderMode"
glShadeModel - select flat or smooth shading
void glShadeModel( GLenum mode )
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. Counting vertices and primitives from one starting when glBegin is issued, each flat-shaded line segment i is given the computed color of vertex i + 1, its second vertex. Counting similarly from one, each flat-shaded polygon is given 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.
| primitive type of polygon i | vertex |
|---|---|
Single polygon ( i ≡ 1) |
1 |
Triangle strip |
i + 2 |
Triangle fan |
i + 2 |
Independent triangle |
3i |
Quad strip |
2i + 2 |
Independent quad |
4i |
Flat and smooth shading are specified by glShadeModel with mode set to GL_FLAT and GL_SMOOTH, respectively.
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 called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_SHADE_MODEL
"glBegin", "glColor", "glLight", "glLightModel"
glStencilFunc - set function and reference value for stencil testing
void glStencilFunc( GLenum func, GLint ref, GLuint mask )
Stenciling, like z-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. The test is enabled by glEnable and glDisable with argument GL_STENCIL. Actions taken based on the outcome of the stencil test are specified with glStencilOp.
func is a symbolic constant that determines the stencil comparison function. It accepts one of eight values, shown below. 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.
Here are the values accepted by func:
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.
GL_INVALID_ENUM is generated if func is not one of the eight accepted values.
GL_INVALID_OPERATION is generated if glStencilFunc is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_STENCIL_FUNC
glGet with argument GL_STENCIL_VALUE_MASK
glGet with argument GL_STENCIL_REF
glGet with argument GL_STENCIL_BITS
glIsEnabled with argument GL_STENCIL_TEST
"glAlphaFunc", "glBlendFunc", "glDepthFunc", "glEnable", "glIsEnabled", "glLogicOp", "glStencilOp"
glStencilMask - control the writing of individual bits in the stencil planes
void glStencilMask( GLuint mask )
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. Wherever a one appears in the mask, the corresponding bit in the stencil buffer is made writable. Where a zero appears, the bit is write-protected. Initially, all bits are enabled for writing.
GL_INVALID_OPERATION is generated if glStencilMask is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_STENCIL_WRITEMASK
glGet with argument GL_STENCIL_BITS
"glColorMask", "glDepthMask", "glIndexMask", "glStencilFunc", "glStencilOp"
glStencilOp - set stencil test actions
void glStencilOp( GLenum fail, GLenum zfail, GLenum zpass )
Stenciling, like z-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. The test is enabled with glEnable and glDisable calls with argument GL_STENCIL, and controlled with glStencilFunc.
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 fail specifies what happens to the stencil buffer contents. The six possible actions are as follows:
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 should subsequent depth buffer tests succeed (zpass) or fail (zfail). (See "glDepthFunc".) They are specified using the same six symbolic constants as fail. Note that zfail is ignored when there is no depth buffer, or when the depth buffer is not enabled. In these cases, fail and zpass specify stencil action when the stencil test fails and passes, respectively.
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.
GL_INVALID_ENUM is generated if fail, zfail, or zpass is any value other than the six defined constant values.
GL_INVALID_OPERATION is generated if glStencilOp is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_STENCIL_FAIL
glGet with argument GL_STENCIL_PASS_DEPTH_PASS
glGet with argument GL_STENCIL_PASS_DEPTH_FAIL
glGet with argument GL_STENCIL_BITS
glIsEnabled with argument GL_STENCIL_TEST
"glAlphaFunc", "glBlendFunc", "glDepthFunc", "glEnable", "glLogicOp", "glStencilFunc"
glTexCoord1d, glTexCoord1f, glTexCoord1i, glTexCoord1s, glTexCoord2d, glTexCoord2f, glTexCoord2i, glTexCoord2s, glTexCoord3d, glTexCoord3f, glTexCoord3i, glTexCoord3s, glTexCoord4d, glTexCoord4f, glTexCoord4i, glTexCoord4s, glTexCoord1dv, glTexCoord1fv, glTexCoord1iv, glTexCoord1sv, glTexCoord2dv, glTexCoord2fv, glTexCoord2iv, glTexCoord2sv , glTexCoord3dv, glTexCoord3fv, glTexCoord3iv, glTexCoord3sv, glTexCoord4dv, glTexCoord4fv, glTexCoord4iv, glTexCoord4sv - set the current texture coordinates
void glTexCoord1d( GLdouble s )
void glTexCoord1f( GLfloat s )
void glTexCoord1i( GLint s )
void glTexCoord1s( GLshort s )
void glTexCoord2d( GLdouble s, GLdouble t )
void glTexCoord2f( GLfloat s, GLfloat t )
void glTexCoord2i( GLint s, GLint t )
void glTexCoord2s( GLshort s, GLshort t )
void glTexCoord3d( GLdouble s, GLdouble t, GLdouble r )
void glTexCoord3f( GLfloat s, GLfloat t, GLfloat r )
void glTexCoord3i( GLint s, GLint t, GLint r )
void glTexCoord3s( GLshort s, GLshort t, GLshort r )
void glTexCoord4d( GLdouble s, GLdouble t, GLdouble r,
GLdouble q )
void glTexCoord4f( GLfloat s, GLfloat t, GLfloat r,
GLfloat q )
void glTexCoord4i( GLint s, GLint t, GLint r,
GLint q )
void glTexCoord4s( GLshort s, GLshort t GLshort r,
GLshort q )
void glTexCoord1dv( const GLdouble *v )
void glTexCoord1fv( const GLfloat *v )
void glTexCoord1iv( const GLint *v )
void glTexCoord1sv( const GLshort *v )
void glTexCoord2dv( const GLdouble *v )
void glTexCoord2fv( const GLfloat *v )
void glTexCoord2iv( const GLint *v )
void glTexCoord2sv( const GLshort *v )
void glTexCoord3dv( const GLdouble *v )
void glTexCoord3fv( const GLfloat *v )
void glTexCoord3iv( const GLint *v )
void glTexCoord3sv( const GLshort *v )
void glTexCoord4dv( const GLdouble *v )
void glTexCoord4fv( const GLfloat *v )
void glTexCoord4iv( const GLint *v )
void glTexCoord4sv( const GLshort *v )
The current texture coordinates are part of the data that is associated with polygon vertices. They are set with glTexCoord.
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 can be updated at any time. In particular, glTexCoord can be called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_CURRENT_TEXTURE_COORDS
glTexCoordPointer - define an array of texture coordinates
void glTexCoordPointer( GLint size, GLenum type, GLsizei stride, const GLvoid *pointer )
The glTexCoordPointer subroutine specifies the location and data format of an array of texture coordinates to use when rendering. The size parameter specifies the number of coordinates per element, and must be 1, 2, 3, or 4. The type parameter specifies the data type of each texture coordinate and stride gives the byte stride from one array element to the next allowing vertexes 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). When a texture coordinate array is specified, size, type, stride, and pointer are saved client side state.
To enable and disable the texture coordinate array, call glEnableClientState and glDisableClientState with the argument GL_TEXTURE_COORD_ARRAY. If enabled, the texture coordinate array is used when glDrawArrays, glDrawElements or glArrayElement is called.
Use glDrawArrays to construct a sequence of primitives (all of the same type) from prespecified vertex and vertex attribute arrays. Use glArrayElement to specify primitives by indexing vertexes and vertex attributes and glDrawElements to construct a sequence of primitives by indexing vertexes and vertex attributes.
The glTexCoordPointer subroutine is available only if the GL version is 1.1 or greater.
The texture coordinate array is initially disabled and it won't be accessed when glArrayElement, glDrawElements or glDrawArrays is called.
Execution of glTexCoordPointer 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.
The glTexCoordPointer subroutine is typically implemented on the client side with no protocol.
Since the texture coordinate array parameters are client side state, they are not saved or restored by glPushAttrib and glPopAttrib. Use glPushClientAttrib and glPopClientAttrib instead.
The glTexCoordPointer subroutine is not included in display lists.
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.
glIsEnabled with argument GL_TEXTURE_COORD_ARRAY
glGet with argument GL_TEXTURE_COORD_ARRAY_SIZE
glGet with argument GL_TEXTURE_COORD_ARRAY_TYPE
glGetPointerv with argument GL_TEXTURE_COORD_ARRAY_POINTER
"glArrayElement", "glColorPointer", "glDrawArrays", "glDrawElements", "glEdgeFlagPointer", "glGetPointerv", "glIndexPointer", "glPopClientAttrib", "glPushClientAttrib", "glVertexPointer"
glTexEnvf, glTexEnvi, glTexEnvfv, glTexEnviv - set texture environment parameters
void glTexEnvf( GLenum target, GLenum pname, GLfloat param )
void glTexEnvi( GLenum target, GLenum pname, GLint param )
void glTexEnvfv( GLenum target, GLenum pname, const GLfloat *params )
void glTexEnviv( GLenum target, GLenum pname, const GLint *params )
A texture environment specifies how texture values are interpreted when a fragment is textured. target must be GL_TEXTURE_ENV. pname can be either GL_TEXTURE_ENV_MODE or GL_TEXTURE_ENV_COLOR.
If pname is GL_TEXTURE_ENV_MODE, then params is (or points to) the symbolic name of a texture function. Three texture functions are defined: GL_MODULATE, GL_DECAL, and GL_BLEND
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" and "glTexImage2D"). 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.
| Number of components | texture function GL_MODULATE |
texture function GL_DECAL |
texture function GL_BLEND |
|---|---|---|---|
1 |
Cv = Lt Cf |
undefined |
Cv = ( 1 - Lt )
Cf + Lt |
2 |
Cv = Lt Cf |
undefined |
Cv = ( 1 - Lt )
Cf + Lt Cc |
3 |
Cv = Ct Cf |
Cv = Ct |
undefined |
4 |
Cv = Ct |
Cv = ( 1 - At )
Cf + At Ct |
undefined |
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.
GL_TEXTURE_ENV_MODE defaults to GL_MODULATE and GL_TEXTURE_ENV_COLOR defaults to (0,0,0,0).
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_OPERATION is generated if glTexEnv is called between a call to glBegin and the corresponding call to glEnd.
"glTexImage1D", "glTexImage2D", "glTexParameter"
glTexGend, glTexGenf, glTexGeni, glTexGendv, glTexGenfv, glTexGeniv - control the generation of texture coordinates
void glTexGend( GLenum coord, GLenum pname, GLdouble param )
void glTexGenf( GLenum coord, GLenum pname, GLfloat param )
void glTexGeni( GLenum coord, GLenum pname, GLint param )
void glTexGendv( GLenum coord, GLenum pname, const GLdouble *params )
void glTexGenfv( GLenum coord, GLenum pname, const GLfloat *params )
void glTexGeniv( GLenum coord, GLenum pname, const GLint *params )
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, and it must be one of these 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, or GL_SPHERE_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 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 is used to index the texture image to map white snow onto peaks and green grass onto foothills, for example.
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' ) = ( p1 p2 p3 p4 ) 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 prime be the current normal, after transformation to eye coordinates. Let f = ( fx fy fz )T be the reflection vector such that
f = u - 2 n' n' T u
Finally, let
Then the values assigned to the s and t texture coordinates are
A texture-coordinate generation function is enabled or disabled using 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).
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 called between a call to glBegin and the corresponding call to glEnd.
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
"glTexEnv", "glTexImage1D", "glTexImage2D", "glTexParameter"
glTexImage1D - specify a one-dimensional texture image
void glTexImage1D( GLenum target, GLint level, GLint components, GLsizei width, GLint border, GLenum format, GLenum type, const GLvoid *pixels )
Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is enabled. One-dimensional texturing is enabled and disabled using 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 number of color components provided. The last three arguments describe the way the image is represented in memory, and they are identical to the pixel formats used for glDrawPixels.
Data is read from pixels 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").
format determines the composition of each element in pixels. It can assume one of nine symbolic values:
A texture image can have up to four components per texture element, depending on components. A one-component texture image uses only the red component of the RGBA color extracted from pixels. 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.
Texturing has no effect in color index mode.
The texture image can be represented by the same data formats as the pixels in a glDrawPixels command, except that GL_STENCIL_INDEX and GL_DEPTH_COMPONENT cannot be used. glPixelStore and glPixelTransfer modes affect texture images in exactly the way they affect glDrawPixels.
A texture image with zero width indicates the null texture. If the null texture is specified for level-of-detail 0, it is as if texturing were disabled.
GL_INVALID_ENUM is generated when target is not GL_TEXTURE_1D.
GL_INVALID_ENUM is generated when format is not an accepted format constant. Format constants other than GL_STENCIL_INDEX and GL_DEPTH_COMPONENT are accepted.
GL_INVALID_ENUM is generated when 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 zero or greater than log2max, where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE is generated if components is not 1, 2, 3, or 4.
GL_INVALID_VALUE is generated if width is less than zero or greater than 2 + GL_MAX_TEXTURE_SIZE, or if it 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 glTexImage1D is called between a call to glBegin and the corresponding call to glEnd.
glGetTexImage
glIsEnabled with argument GL_TEXTURE_1D
"glDrawPixels", "glFog", "glPixelStore", "glPixelTransfer", "glTexEnv", "glTexGen", "glTexImage2D", "glTexParameter"
glTexImage2D - specify a two-dimensional texture image
void glTexImage2D( GLenum target, GLint level, GLint components, GLsizei width, GLsizei height, GLint border, GLenum format, GLenum type, const GLvoid *pixels )
Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is enabled. Two-dimensional texturing is enabled and disabled using glEnable and glDisable with argument GL_TEXTURE_2D.
Texture images are defined with 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 the way the image is represented in memory, and they are identical to the pixel formats used for glDrawPixels.
Data is read from pixels 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").
format determines the composition of each element in pixels. It can assume one of nine symbolic values:
Please refer to the glDrawPixels reference page for a description of the acceptable values for the type parameter. A texture image can have up to four components per texture element, depending on components. A one-component texture image uses only the red component of the RGBA color extracted from pixels. 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.
Texturing has no effect in color index mode.
The texture image can be represented by the same data formats as the pixels in a glDrawPixels command, except that GL_STENCIL_INDEX and GL_DEPTH_COMPONENT cannot be used. glPixelStore and glPixelTransfer modes affect texture images in exactly the way they affect glDrawPixels.
A texture image with zero height or width indicates the null texture. If the null texture is specified for level-of-detail 0, it is as if texturing were disabled.
GL_INVALID_ENUM is generated when target is not GL_TEXTURE_2D.
GL_INVALID_ENUM is generated when format is not an accepted format constant. Format constants other than GL_STENCIL_INDEX and GL_DEPTH_COMPONENT are accepted.
GL_INVALID_ENUM is generated when 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 zero or greater than log2 max, where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE is generated if components is not 1, 2, 3, or 4.
GL_INVALID_VALUE is generated if width or height is less than zero or greater than 2 + GL_MAX_TEXTURE_SIZE, or if either 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 glTexImage2D is called between a call to glBegin and the corresponding call to glEnd.
glGetTexImage
glIsEnabled with argument GL_TEXTURE_2D
"glDrawPixels", "glFog", "glPixelStore", "glPixelTransfer", "glTexEnv", "glTexGen", "glTexImage1D", "glTexParameter"
glTexParameterf, glTexParameteri, glTexParameterfv, glTexParameteriv - set texture parameters
void glTexParameterf( GLenum target, GLenum pname, GLfloat param )
void glTexParameteri( GLenum target, GLenum pname, GLint param )
void glTexParameterfv( GLenum target, GLenum pname,
const GLfloat *params )
void glTexParameteriv( GLenum target, GLenum pname,
const GLint *params )
Texture mapping is a technique that applies an image onto an object's surface as if the image were a decal or cellophane shrink-wrap. The image is created in texture space, with an (s, t) coordinate system. A texture is a one- or two-dimensional image and a set of parameters that determine how samples are derived from the image.
glTexParameter assigns the value or values in params to the texture parameter specified as pname. target defines the target texture, either GL_TEXTURE_1D or GL_TEXTURE_2D. The following symbols are accepted in pname:
Suppose texturing is enabled (by calling glEnable with argument GL_TEXTURE_1D or GL_TEXTURE_2D) and GL_TEXTURE_MIN_FILTER is set to one of the functions that requires a mipmap. If either the dimensions of the texture images currently defined (with previous calls to glTexImage1D or glTexImage2D) do not follow the proper sequence for mipmaps (described above), or there are fewer texture images defined than are needed, or the set of texture images have differing numbers of texture components, then it is as if texture mapping were disabled.
Linear filtering accesses the four nearest texture elements only in 2-D textures. In 1-D textures, linear filtering accesses the two nearest texture elements.
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_OPERATION is generated if glTexParameter is called between a call to glBegin and the corresponding call to glEnd.
glGetTexParameter
glGetTexLevelParameter
"glTexEnv", "glTexImage1D", "glTexImage2D", "glTexGen"
glTexSubImage1D - specify a one-dimensional (1D) texture subimage
void glTexSubImage1D( GLenum target, GLint level, GLint xoffset, GLsizei width, GLenum format, GLenum type, GLvoid *pixels )
Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is enabled. To enable or disable one-dimensional texturing, call glEnable and glDisable with argument GL_TEXTURE_1D.
The glTexSubImage1D subroutine redefines a contiguous subregion of an existing one-dimensional texture image. The texels referenced by pixels replace the portion of the existing texture array with x indices xoffset and xoffset + width - 1, inclusive. This region may not include any texels outside the range of the texture array as it was originally specified. It is not an error to specify a subtexture with zero width, but such a specification has no effect.
Each fixed-point index is then shifted left by GL_INDEX_SHIFT bits and added to GL_INDEX_OFFSET. If GL_INDEX_SHIFT is negative, the shift is to the right. In either case, 0 bits fill otherwise unspecified bit locations in the result.
If the GL is in red, green, blue, alpha (RGBA) mode, the resulting index is converted to an RGBA pixel using the GL_PIXEL_MAP_I_TO_R, GL_PIXEL_MAP_I_TO_G, GL_PIXEL_MAP_I_TO_B, and GL_PIXEL_MAP_I_TO_A tables. If the GL is in color index mode and GL_MAP_COLOR is True, the index is replaced with the value that it references in the lookup table GL_PIXEL_MAP_I_TO_I. Whether the lookup replacement of the index is done or not, the integer part of the index is then ANDed with 2b -1, where b is the number of bits in a color index buffer.
The resulting indices or RGBA colors are then converted to fragments by attaching the current raster position z coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that xn = xr + n mod Width and yn = yr + [n/Width], where (xr, yr) is the current raster position. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer.
If GL_MAP_COLOR is True, each color component is scaled by the size of the lookup table GL_PIXEL_MAP_c_TO_c, then replaced by the value that it references in that table. c is R, G, B, or A, respectively.
The resulting RGBA colors are then converted to fragments by attaching the current raster position z coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that xn = xr + n mod Width and yn = yr + [n/Width], where (xr, yr) is the current raster position. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer.
If GL_MAP_COLOR is True, each color component is scaled by the size of the lookup table GL_PIXEL_MAP_c_TO_c, then replaced by the value that it references in that table. c is B, G, R, or A, respectively.
The resulting BGRA colors are then converted to fragments by attaching the current raster position z coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that xn = xr + n mod Width and yn = yr + [n/Width], where (xr, yr) is the current raster position. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer.
If GL_MAP_COLOR is true, each color component is scaled by the size of lookup table GL_PIXEL_MAP_c_TO_c, then replaced by the value that it references in that table. c is R, G, B, or A, respectively.
The resulting RGBA colors are then converted to fragments by attaching the current raster position z coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that
xn = xr + n mod width
yn = yr + | n bwidthc
where (xr,yr) is the current raster position. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer.
Texturing has no effect in color index mode.
The glPixelStore and glPixelTransfer modes affect texture images in exactly the way they affect glDrawPixels.
Format of GL_ABGR_EXT is part of the _extname (EXT_abgr) extension, not part of the core GL command set.
GL_INVALID_ENUM is generated if target is not one of the allowable values.
GL_INVALID_OPERATION is generated if the texture array has not been defined by a previous glTexImage1D operation.
GL_INVALID_VALUE is generated if level is less than zero.
GL_INVALID_VALUE may be generated if level is greater than log2(max), where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE is generated if width < -b, where b is the border width of the texture array.
GL_INVALID_VALUE is generated if xoffset < -b, or if (xoffset + width) > (w - b). Where w is the GL_TEXTURE_WIDTH, and b is the width of the GL_TEXTURE_BORDER of the texture image being modified. Note that w includes twice the border width.
GL_INVALID_ENUM is generated if format is not an accepted format constant.
GL_INVALID_ENUM is generated if type is not a type constant.
GL_INVALID_ENUM is generated if type is GL_BITMAP and format is not GL_COLOR_INDEX.
GL_INVALID_OPERATION is generated if glTexSubImage1D is executed between the execution of glBegin and the corresponding execution of glEnd.
glGetTexImage
glIsEnabled with argument GL_TEXTURE_1D
"glDrawPixels", "glFog", "glPixelStore", "glPixelTransfer", "glTexEnv", "glTexGen", "glTexImage1D", "glTexParameter"
glTexSubImage2D - specify a two-dimensional (2D) texture subimage
void glTexSubImage2D( GLenum target, GLint level, GLint xoffset, GLint yoffset, GLsizei width, GLsizei height, GLenum format, GLenum type, const GLvoid *pixels )
Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is enabled. To enable and disable two-dimensional texturing, call glEnable and glDisable with argument GL_TEXTURE_2D.
The glTexSubImage2D subroutine redefines a contiguous subregion of an existing two-dimensional texture image. The texels referenced by pixels replace the portion of the existing texture array with x indices xoffset and xoffset + width - 1, inclusive, and y indices yoffset and yoffset + height - 1, inclusive. This region may not include any texels outside the range of the texture array as it was originally specified. It is not an error to specify a subtexture with zero width or height, but such a specification has no effect.
Each fixed-point index is then shifted left by GL_INDEX_SHIFT bits and added to GL_INDEX_OFFSET. If GL_INDEX_SHIFT is negative, the shift is to the right. In either case, 0 bits fill otherwise unspecified bit locations in the result.
If the GL is in red, green, blue, alpha (RGBA) mode, the resulting index is converted to an RGBA pixel using the GL_PIXEL_MAP_I_TO_R, GL_PIXEL_MAP_I_TO_G, GL_PIXEL_MAP_I_TO_B, and GL_PIXEL_MAP_I_TO_A tables. If the GL is in color index mode and GL_MAP_COLOR is True, the index is replaced with the value that it references in the lookup table GL_PIXEL_MAP_I_TO_I. Whether the lookup replacement of the index is done or not, the integer part of the index is then ANDed with 2b -1, where b is the number of bits in a color index buffer.
The resulting indices or RGBA colors are then converted to fragments by attaching the current raster position z coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that xn = xr + n mod Width and yn = yr + [n/Width], where (xr, yr) is the current raster position. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer.
If GL_MAP_COLOR is True, each color component is scaled by the size of the lookup table GL_PIXEL_MAP_c_TO_c, then replaced by the value that it references in that table. c is R, G, B, or A, respectively.
The resulting RGBA colors are then converted to fragments by attaching the current raster position z coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that xn = xr + n mod Width and yn = yr + [n/Width], where (xr, yr) is the current raster position. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer.
If GL_MAP_COLOR is True, each color component is scaled by the size of the lookup table GL_PIXEL_MAP_c_TO_c, then replaced by the value that it references in that table. c is B, G, R, or A, respectively.
The resulting BGRA colors are then converted to fragments by attaching the current raster position z coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that xn = xr + n mod Width and yn = yr + [n/Width], where (xr, yr) is the current raster position. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer.
If GL_MAP_COLOR is true, each color component is scaled by the size of lookup table GL_PIXEL_MAP_c_TO_c, then replaced by the value that it references in that table. c is R, G, B, or A, respectively.
The resulting RGBA colors are then converted to fragments by attaching the current raster position z coordinate and texture coordinates to each pixel, then assigning x and y window coordinates to the nth fragment such that
xn = xr + n mod width
yn = yr + | n bwidthc
where (xr,yr) is the current raster position. These pixel fragments are then treated just like the fragments generated by rasterizing points, lines, or polygons. Texture mapping, fog, and all the fragment operations are applied before the fragments are written to the frame buffer.
Texturing has no effect in color index mode.
The glPixelStore and glPixelTransfer modes affect texture images in exactly the way they affect glDrawPixels.
Format of GL_ABGR_EXT is part of the _extname (EXT_abgr) extension, not part of the core GL command set.
GL_INVALID_ENUM is generated if target is not GL_TEXTURE_2D.
GL_INVALID_OPERATION is generated if the texture array has not been defined by a previous glTexImage2D operation.
GL_INVALID_VALUE is generated if level is less than zero.
GL_INVALID_VALUE may be generated if level is greater than log2(max), where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE is generated if width < -b or if height < -b, where b is the border width of the texture array.
GL_INVALID_VALUE is generated if xoffset < -b, (xoffset + width) > (w - b), yoffset < -b, or (yoffset + height) > (h - b). Where w is the GL_TEXTURE_WIDTH, h is the GL_TEXTURE_HEIGHT, and b is the border width of the texture image being modified. Note that w and h include twice the border width.
GL_INVALID_ENUM is generated if format is not an accepted format constant.
GL_INVALID_ENUM is generated if type is not a type constant.
GL_INVALID_ENUM is generated if type is GL_BITMAP and format is not GL_COLOR_INDEX.
GL_INVALID_OPERATION is generated if glTexSubImage2D is executed between the execution of glBegin and the corresponding execution of glEnd.
glGetTexImage
glIsEnabled with argument GL_TEXTURE_2D
"glDrawPixels", "glFog", "glPixelStore", "glPixelTransfer", "glTexEnv", "glTexGen", "glTexImage2D", "glTexParameter"
glTranslated, glTranslatef - multiply the current matrix by a translation matrix
void glTranslated( GLdouble x, GLdouble y, GLdouble z )
void glTranslatef( GLfloat x, GLfloat y, GLfloat z )
glTranslate moves the coordinate system origin to the point specified by (x,y,z). The translation vector is used to compute a 4 × 4 translation matrix:
The current matrix (see "glMatrixMode") is multiplied by this translation matrix, with the product replacing the current matrix. That is, if M is the current matrix and T is the translation matrix, then M is replaced with M o T.
If the matrix mode is either GL_MODELVIEW or GL_PROJECTION, all objects drawn after glTranslate is called are translated. Use glPushMatrix and glPopMatrix to save and restore the untranslated coordinate system.
GL_INVALID_OPERATION is generated if glTranslate is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_MATRIX_MODE
glGet with argument GL_MODELVIEW_MATRIX
glGet with argument GL_PROJECTION_MATRIX
glGet with argument GL_TEXTURE_MATRIX
"glMatrixMode", "glMultMatrix", "glPushMatrix", "glRotate", "glScale"
glVertex2d, glVertex2f, glVertex2i, glVertex2s, glVertex3d, glVertex3f, glVertex3i, glVertex3s, glVertex4d, glVertex4f, glVertex4i, glVertex4s, glVertex2dv, glVertex2fv, glVertex2iv, glVertex2sv, glVertex3dv, glVertex3fv, glVertex3iv, glVertex3sv, glVertex4dv, glVertex4fv, glVertex4iv, glVertex4sv - specify a vertex
void glVertex2d( GLdouble x, GLdouble y )
void glVertex2f( GLfloat x, GLfloat y )
void glVertex2i( GLint x, GLint y )
void glVertex2s( GLshort x, GLshort y )
void glVertex3d( GLdouble x, GLdouble y, GLdouble z )
void glVertex3f( GLfloat x, GLfloat y, GLfloat z )
void glVertex3i( GLint x, GLint y, GLint z )
void glVertex3s( GLshort x, GLshort y, GLshort z )
void glVertex4d( GLdouble x, GLdouble y, GLdouble z,
GLdouble w )
void glVertex4f( GLfloat x, GLfloat y, GLfloat z,
GLfloat w )
void glVertex4i( GLint x, GLint y, GLint z,
GLint w )
void glVertex4s( GLshort x, GLshort y, GLshort z,
GLshort w )
void glVertex2dv( const GLdouble *v )
void glVertex2fv( const GLfloat *v )
void glVertex2iv( const GLint *v )
void glVertex2sv( const GLshort *v )
void glVertex3dv( const GLdouble *v )
void glVertex3fv( const GLfloat *v )
void glVertex3iv( const GLint *v )
void glVertex3sv( const GLshort *v )
void glVertex4dv( const GLdouble *v )
void glVertex4fv( const GLfloat *v )
void glVertex4iv( const GLint *v )
void glVertex4sv( const GLshort *v )
glVertex commands are used within glBegin/glEnd pairs to specify point, line, and polygon vertices. The current color, normal, and texture coordinates are associated with the vertex when glVertex is called.
When only x and y are specified, z defaults to 0.0 and w defaults to 1.0. When x, y, and z are specified, w defaults to 1.0.
Invoking glVertex outside of a glBegin/glEnd pair results in undefined behavior.
"glBegin", "glCallList", "glColor", "glEdgeFlag", "glEvalCoord", "glIndex", "glMaterial", "glNormal", "glRect", "glTexCoord"
glVertexPointer - define an array of vertex data
void glVertexPointer( GLint size, GLenum type, GLsizei stride, const GLvoid *pointer )
The glVertexPointer subroutine specifies the location and data format of an array of vertex coordinates to use when rendering. The size parameter specifies the number of coordinates per vertex and type the data type of the coordinates. The stride parameter specifies the byte stride from one vertex to the next allowing vertexes 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). When a vertex array is specified, size, type, stride, and pointer are saved as client side state.
To enable and disable the vertex array, call glEnableClientState and glDisableClientState with the argument GL_VERTEX_ARRAY. If enabled, the vertex array is used when glDrawArrays, glDrawElements, or glArrayElement is called.
Use glDrawArrays to construct a sequence of primitives (all of the same type) from prespecified vertex and vertex attribute arrays. Use glArrayElement to specify primitives by indexing vertexes and vertex attributes and glDrawElements to construct a sequence of primitives by indexing vertexes and vertex attributes.
The glVertexPointer subroutine is available only if the GL version is 1.1 or greater.
The vertex array is initially disabled and it won't be accessed when glArrayElement, glDrawElements or glDrawArrays is called.
Execution of glVertexPointer 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.
The glVertexPointer subroutine is typically implemented on the client side with no protocol.
Since the vertex array parameters are client side state, they are not saved or restored by glPushAttrib and glPopAttrib. Use glPushClientAttrib and glPopClientAttrib instead.
The glVertexPointer subroutine is not included in display lists.
GL_INVALID_VALUE is generated if size is not 2, 3, or 4.
GL_INVALID_ENUM is generated if type is is not an accepted value.
GL_INVALID_VALUE is generated if stride is negative.
glIsEnabled with argument GL_VERTEX_ARRAY
glGet with argument GL_VERTEX_ARRAY_SIZE
glGet with argument GL_VERTEX_ARRAY_TYPE
glGet with argument GL_VERTEX_ARRAY_STRIDE
glGetPointerv with argument GL_VERTEX_ARRAY_POINTER
"glArrayElement", "glColorPointer", "glDrawArrays", "glDrawElements", "glEdgeFlagPointer", "glGetPointerv", "glIndexPointer", "glNormalPointer", "glPopClientAttrib", "glPushClientAttrib", "glTexCoordPointer"
glViewport - set the viewport
void glViewport( GLint x, GLint y, GLsizei width, GLsizei height )
glViewport specifies the affine transformation of x and y from normalized device coordinates to window coordinates. Let (xnd, ynd) be normalized device coordinates. Then the window coordinates (xw, yw) are computed as follows:
Viewport width and height are silently clamped to a range that depends on the implementation. This range is queried by calling glGet with argument GL_MAX_VIEWPORT_DIMS.
GL_INVALID_VALUE is generated if either width or height is negative.
GL_INVALID_OPERATION is generated if glViewport is called between a call to glBegin and the corresponding call to glEnd.
glGet with argument GL_VIEWPORT
glGet with argument GL_MAX_VIEWPORT_DIMS
|
|
OpenGL Reference Manual (Addison-Wesley Publishing Company) |