Appendix C. API Reference
Overview of Appendix C
Appendix C is composed of API reference pages, covering OpenGL. These pages come from several different sources.
The following OpenGL reference pages are Copyright © 2003-2005 3Dlabs Inc. Ltd. and may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. For details, see http://opencontent.org/openpub/.
glAttachShader, glBindAttribLocation, glCompileShader, glCreateProgram, glCreateShader, glDeleteProgram, glDeleteShader, glDetachShader, glDrawBuffers, glEnableVertexAttribArray/glDisableVertexAttribArray, glGetActiveAttrib, glGetActiveUniform, glGetAttachedShaders, glGetAttribLocation, glGetProgramiv, glGetProgramInfoLog, glGetShaderiv, glGetShaderInfoLog, glGetUniform, glGetUniformLocation, glGetVertexAttrib, glGetVertexAttribPointerv, glIsProgram, glIsShader, glLinkProgram, glShaderSource, glUniform/glUniformMatrix, glUseProgram, glValidateProgram, glVertexAttrib, glVertexAttribPointer
The following OpenGL reference pages are Copyright © 2007 The Khronos Group Inc. and licensed under the Khronos Free Use License. For details, see http://www.khronos.org/help/legal/KFUL/.
glBlendEquationSeparate, glStencilFuncSeparate, glStencilMaskSeparate, glStencilOpSeparate
The following OpenGL reference pages were written for this book and offered back to the community for free use. They are Copyright © 2005 Addison-Wesley and may be distributed subject to the terms and conditions set forth in the Open Publication License, v 1.0, 8 June 1999. For details, see http://opencontent.org/openpub/.
glBeginQuery/glEndQuery, glBindBuffer, glBufferData, glBufferSubData, glDeleteBuffers, glDeleteQueries, glGenBuffers, glGenQueries, glGetBufferParameteriv, glGetBufferPointerv, glGetBufferSubData, glGetQueryiv, glGetQueryObject, glIsBuffer, glIsQuery, glMapBuffer/glUnmapBuffer
glAccum
Operate on the accumulation buffer
C Specification
void glAccum(GLenum op, GLfloat value);
Parameters
Description
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. Regardless of the number of bits per component, 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 applied identically to the red, green, blue, and alpha components of each pixel. If a glAccum operation results in a value outside the range [-1,1], the contents of an accumulation buffer pixel component are undefined.
The operations are as follows:
GL_ACCUM
Obtains R, G, B, and A values from the buffer currently selected for reading (see glReadBuffer). Each component value is divided by 2n – 1, where n is the number of bits allocated to each color component in the currently selected buffer. The result is a floating-point value in the range [0,1], which is multiplied by value and added to the corresponding pixel component in the accumulation buffer, thereby updating the accumulation buffer.
GL_LOAD
Similar to GL_ACCUM, except that the current value in the accumulation buffer is not used in the calculation of the new value. That is, the R, G, B, and A values from the currently selected buffer are divided by 2n – 1, multiplied by value, and then stored in the corresponding accumulation buffer cell, overwriting the current value.
GL_ADD
Adds value to each R, G, B, and A in the accumulation buffer.
GL_MULT
Multiplies each R, G, B, and A in the accumulation buffer by value and returns the scaled component to its corresponding accumulation buffer location.
GL_RETURN
Transfers accumulation buffer values to the color buffer or buffers currently selected for writing. Each R, G, B, and A component is multiplied by value, then multiplied by 2n – 1, clamped to the range [0,2n – 1], and stored in the corresponding display buffer cell. The only fragment operations that are applied to this transfer are pixel ownership, scissor, dithering, and color writemasks.
To clear the accumulation buffer, call glClearAccum with R, G, B, and A values to set it to, then call glClear with the accumulation buffer enabled.
Notes
Only pixels within the current scissor box are updated by a glAccum operation.
Errors
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 executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
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
See Also
glClear, glClearAccum, glCopyPixels, glDrawBuffer, glGet, glReadBuffer,
glReadPixels, glScissor, glStencilOp
glActiveTexture
Select active texture unit
C Specification
void glActiveTexture(GLenum texture);
Parameters
Description
glActiveTexture selects which texture unit subsequent texture state calls will affect. The number of texture units an implementation supports is implementation dependent, but must be at least 2.
Vertex arrays are client-side GL resources, which are selected by the glClientActiveTexture routine.
Notes
glActiveTexture is only supported if the GL version is 1.3 or greater, or if ARB_multitexture is included in the string returned by glGetString when called with the argument GL_EXTENSIONS.
Errors
GL_INVALID_ENUM is generated if texture is not one of GL_TEXTUREi, where i ranges from 0 to the larger of (GL_MAX_TEXTURE_COORDS – 1) and (GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS – 1).
Associated Gets
glGet with argument GL_ACTIVE_TEXTURE, GL_MAX_TEXTURE_COORDS, or GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS
See Also
glClientActiveTexture, glMultiTexCoord, glTexParameter
glAlphaFunc
Specify the alpha test function
C Specification
void glAlphaFunc(GLenum func, GLclampf ref);
Parameters
Description
The alpha test discards fragments depending on the outcome of a comparison between an incoming fragment’s alpha value and a constant reference value. glAlphaFunc specifies the reference value and the comparison function. The comparison is performed only if alpha testing is enabled. By default, it is not 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 value passes the comparison, the incoming fragment is drawn if it also passes subsequent stencil and depth buffer tests. If the value fails the comparison, no change is made to the frame buffer at that pixel location. The comparison functions are as follows:
GL_NEVER
Never passes.
GL_LESS
Passes if the incoming alpha value is less than the reference value.
GL_EQUAL
Passes if the incoming alpha value is equal to the reference value.
GL_LEQUAL
Passes if the incoming alpha value is less than or equal to the reference value.
GL_GREATER
Passes if the incoming alpha value is greater than the reference value.
GL_NOTEQUAL
Passes if the incoming alpha value is not equal to the reference value.
GL_GEQUAL
Passes if the incoming alpha value is greater than or equal to the reference value.
GL_ALWAYS
Always passes (initial value).
glAlphaFunc operates on all pixel write operations, 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.
Notes
Alpha testing is performed only in RGBA mode.
Errors
GL_INVALID_ENUM is generated if func is not an accepted value.
GL_INVALID_OPERATION is generated if glAlphaFunc is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
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
C Specification
GLboolean glAreTexturesResident(GLsizei n,
const GLuint * textures,
GLboolean * residences);
Parameters
Description
GL establishes a “working set” of textures that are resident in texture memory. These textures can be bound to a texture target much more efficiently than textures that are not resident.
glAreTexturesResident 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, glAreTexturesResident returns GL_FALSE, and detailed status is returned in the n elements of residences. If an element of residences is 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 pname argument set to GL_TEXTURE_RESIDENT. This is the only way that the residence status of a default texture can be queried glAreTexturesResident.
Notes
glAreTexturesResident is available only if the GL version is 1.1 or greater.
glAreTexturesResident 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 reside in virtual memory (there is no texture memory), they are considered always resident.
Some implementations may not load a texture until the first use of that texture.
Errors
GL_INVALID_VALUE is generated if n is negative.
GL_INVALID_VALUE is generated if any element in textures is 0 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.
Associated Gets
glGetTexParameter with parameter name GL_TEXTURE_RESIDENT retrieves the residence status of a currently bound texture.
See Also
glBindTexture, glGetTexParameter, glPrioritizeTextures, glTexImage1D, glTexImage2D, glTexImage3D, glTexParameter
glArrayElement
Render a vertex using the specified vertex array element
C Specification
void glArrayElement(GLint i);
Parameters
Description
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 for each 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 nonsequential 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.
Notes
glArrayElement is available only if the GL version is 1.1 or greater.
glArrayElement 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.
Errors
GL_INVALID_VALUE may be generated if i is negative.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to an enabled array and the buffer object’s data store is currently mapped.
See Also
glClientActiveTexture, glColorPointer, glDrawArrays, glEdgeFlagPointer, glFogCoordPointer, glGetPointerv, glIndexPointer, glInterleavedArrays, glNormalPointer, glSecondaryColorPointer, glTexCoordPointer, glVertexPointer
glAttachShader
Attach a shader object to a program object
C Specification
void glAttachShader(GLuint program,
GLuint shader);
Parameters
Description
In order to create an executable, there must be a way to specify the list of things that will be linked together. Program objects provide this mechanism. Shaders that are to be linked together in a program object must first be attached to that program object. glAttachShader attaches the shader object specified by shader to the program object specified by program. This indicates that shader will be included in link operations that will be performed on program.
All operations that can be performed on a shader object are valid whether or not the shader object is attached to a program object. It is permissible to attach a shader object to a program object before source code has been loaded into the shader object or before the shader object has been compiled. It is permissible to attach multiple shader objects of the same type because each may contain a portion of the complete shader. It is also permissible to attach a shader object to more than one program object. If a shader object is deleted while it is attached to a program object, it will be flagged for deletion, and deletion will not occur until glDetachShader is called to detach it from all program objects to which it is attached.
Notes
glAttachShader is available only if the GL version is 2.0 or greater.
Errors
GL_INVALID_VALUE is generated if either program or shader is not a value generated by OpenGL.
GL_INVALID_OPERATION is generated if program is not of type GL_PROGRAM_OBJECT.
GL_INVALID_OPERATION is generated if shader is not of type GL_SHADER_OBJECT.
GL_INVALID_OPERATION is generated if shader is already attached to program.
GL_INVALID_OPERATION is generated if glAttachShader is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetAttachedShaders with the handle of a valid program object
glIsProgram
glIsShader
See Also
glCompileShader, glDetachShader, glLinkProgram, glShaderSource
glBegin
Delimit the vertices of a primitive or a group of like primitives
C Specification
void glBegin(GLenum mode);
Parameters
C Specification
void glEnd(void);
Description
glBegin and glEnd delimit the vertices that define a primitive or a group of like primitives. glBegin accepts a single argument that specifies in 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:
GL_POINTS
Treats each vertex as a single point. Vertex n defines point n. N points are drawn.
GL_LINES
Treats each pair of vertices as an independent line segment. Vertices 2n – 1 and 2n define line n.
lines are drawn.
Draws a connected group of line segments from the first vertex to the last. Vertices n and n + 1 define line n. N – 1 lines are drawn.
GL_LINE_LOOP
Draws a connected group of line segments from the first vertex to the last, then back to the first. Vertices n and n + 1 define line n. The last line, however, is defined by vertices N and 1. N lines are drawn.
GL_TRIANGLES
Treats each triplet of vertices as an independent triangle. Vertices 3n – 2, 3n – 1, and 3 n define triangle n. 
triangles are drawn.
GL_TRIANGLE_STRIP
Draws a connected group of triangles. One triangle is defined for each vertex presented after the first two vertices. For odd n, vertices n, n + 1, and n + 2 define triangle n. For even n, vertices n + 1, n, and n + 2 define triangle n. N – 2 triangles are drawn.
GL_TRIANGLE_FAN
Draws a connected group of triangles. One triangle is defined for each vertex presented after the first two vertices. Vertices 1, n + 1, and n + 2 define triangle n. N – 2 triangles are drawn.
GL_QUADS
Treats each group of four vertices as an independent quadrilateral. Vertices 4n – 3, 4n – 2, 4n – 1, and 4n define quadrilateral n. 
quadrilaterals are drawn.
GL_QUAD_STRIP
Draws a connected group of quadrilaterals. One quadrilateral is defined for each pair of vertices presented after the first pair. Vertices 2n – 1, 2n, 2n + 2, and 2n + 1 define quadrilateral n.
quadrilaterals are drawn. Note that the order in which vertices are used to construct a quadrilateral from strip data is different from that used with independent data.
GL_POLYGON
Draws a single, convex polygon. Vertices 1 through N define this polygon.
Only a subset of GL commands can be used between glBegin and glEnd. The commands are glVertex, glColor, glIndex, glNormal, glTexCoord, glEvalCoord, glEvalPoint, glArrayElement, 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 executed 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).
Errors
GL_INVALID_ENUM is generated if mode is set to an unaccepted value.
GL_INVALID_OPERATION is generated if glBegin is executed between a glBegin and the corresponding execution of glEnd.
GL_INVALID_OPERATION is generated if glEnd is executed without being preceded by a glBegin.
GL_INVALID_OPERATION is generated if a command other than glVertex, glColor, glSecondaryColor, glIndex, glNormal, glFogCoord, glTexCoord, glMultiTexCoord, glEvalCoord, glEvalPoint, glArrayElement, glMaterial, glEdgeFlag, glCallList, or glCallLists is executed between the execution of glBegin and the corresponding execution glEnd.
Execution of glEnableClientState, glDisableClientState, glEdgeFlagPointer, glFogCoordPointer, glTexCoordPointer, glColorPointer, glSecondaryColorPointer, glIndexPointer, glNormalPointer, glVertexPointer, glInterleavedArrays, or glPixelStore is not allowed after a call to glBegin and before the corresponding call to glEnd, but an error may or may not be generated.
See Also
glArrayElement, glCallList, glCallLists, glColor, glEdgeFlag, glEvalCoord, glEvalPoint, glFogCoord, glIndex, glMaterial, glMultiTexCoord, glNormal, glSecondaryColor, glTexCoord, glVertex
glBeginQuery
Delimit the boundaries of a query object
C Specification
void glBeginQuery(GLenum target, GLuint id);
Parameters
C Specification
void glEndQuery(GLenum target);
Parameters
Description
glBeginQuery and glEndQuery delimit the boundaries of a query object. If a query object with name id does not yet exist it is created.
When glBeginQuery is executed, the query object’s samples-passed counter is reset to 0. Subsequent rendering will increment the counter once for every sample that passes the depth test. When glEndQuery is executed, the samples-passed counter is assigned to the query object’s result value. This value can be queried by calling glGetQueryObject with pnameGL_QUERY_RESULT.
Querying the GL_QUERY_RESULT implicitly flushes the GL pipeline until the rendering delimited by the query object has completed and the result is available. GL_QUERY_RESULT_AVAILABLE can be queried to determine if the result is immediately available or if the rendering is not yet complete.
Notes
If the samples-passed count exceeds the maximum value representable in the number of available bits, as reported by glGetQueryiv with pnameGL_QUERY_COUNTER_BITS, the count becomes undefined.
An implementation may support 0 bits in its samples-passed counter, in which case query results are always undefined and essentially useless.
When SAMPLE_BUFFERS is 0, the samples-passed counter will increment once for each fragment that passes the depth test. When SAMPLE_BUFFERS is 1, an implementation may either increment the samples-passed counter individually for each sample of a fragment that passes the depth test, or it may choose to increment the counter for all samples of a fragment if any one of them passes the depth test.
glBeginQuery and glEndQuery are available only if the GL version is 1.5 or greater.
GL_INVALID_ENUM is generated if target is not GL_SAMPLES_PASSED.
GL_INVALID_OPERATION is generated if glBeginQuery is executed while a query object of the same target is already active.
GL_INVALID_OPERATION is generated if glEndQuery is executed when a query object of the same target is not active.
GL_INVALID_OPERATION is generated if id is 0.
GL_INVALID_OPERATION is generated if id is the name of an already active query object.
GL_INVALID_OPERATION is generated if glBeginQuery or glEndQuery is executed between the execution of glBegin and the corresponding execution of glEnd.
See Also
glDeleteQueries, glGenQueries, glGetQueryiv, glGetQueryObject, glIsQuery
glBindAttribLocation
Associate a generic vertex attribute index with a named attribute variable
C Specification
void glBindAttribLocation(GLuint program,
GLuint index,
const GLchar * name);
Parameters
Description
glBindAttribLocation is used to associate a user-defined attribute variable in the program object specified by program with a generic vertex attribute index. The name of the user-defined attribute variable is passed as a null terminated string in name. The generic vertex attribute index to be bound to this variable is specified by index. When program is made part of current state, values provided via the generic vertex attribute index will modify the value of the user-defined attribute variable specified by name.
If name refers to a matrix attribute variable, index refers to the first column of the matrix. Other matrix columns are then automatically bound to locations index + 1 for a matrix of type mat2; index + 1 and index + 2 for a matrix of type mat3; and index + 1, index + 2, and index + 3 for a matrix of type mat4.
This command makes it possible for vertex shaders to use descriptive names for attribute variables rather than generic variables that are numbered from 0 to GL_MAX_VERTEX_ATTRIBS -1. The values sent to each generic attribute index are part of current state, just like standard vertex attributes such as color, normal, and vertex position. If a different program object is made current by calling glUseProgram, the generic vertex attributes are tracked in such a way that the same values will be observed by attributes in the new program object that are also bound to index.
Attribute variable name-to-generic attribute index bindings for a program object can be explicitly assigned at any time by calling glBindAttribLocation. Attribute bindings do not go into effect until glLinkProgram is called. After a program object has been linked successfully, the index values for generic attributes remain fixed (and their values can be queried) until the next link command occurs.
Applications are not allowed to bind any of the standard OpenGL vertex attributes using this command, as they are bound automatically when needed. Any attribute binding that occurs after the program object has been linked will not take effect until the next time the program object is linked.
glBindAttribLocation is available only if the GL version is 2.0 or greater.
glBindAttribLocation can be called before any vertex shader objects are bound to the specified program object. It is also permissible to bind a generic attribute index to an attribute variable name that is never used in a vertex shader.
If name was bound previously, that information is lost. Thus you cannot bind one user-defined attribute variable to multiple indices, but you can bind multiple user-defined attribute variables to the same index.
Applications are allowed to bind more than one user-defined attribute variable to the same generic vertex attribute index. This is called aliasing, and it is allowed only if just one of the aliased attributes is active in the executable program, or if no path through the shader consumes more than one attribute of a set of attributes aliased to the same location. The compiler and linker are allowed to assume that no aliasing is done and are free to employ optimizations that work only in the absence of aliasing. OpenGL implementations are not required to do error checking to detect aliasing. Because there is no way to bind standard attributes, it is not possible to alias generic attributes with conventional ones (except for generic attribute 0).
Active attributes that are not explicitly bound will be bound by the linker when glLinkProgram is called. The locations assigned can be queried by calling glGetAttribLocation.
OpenGL copies the name string when glBindAttribLocation is called, so an application may free its copy of the name string immediately after the function returns.
Errors
GL_INVALID_VALUE is generated if index is greater than or equal to GL_MAX_VERTEX_ATTRIBS.
GL_INVALID_OPERATION is generated if name starts with the reserved prefix “gl_”.
GL_INVALID_VALUE is generated if program is not a value generated by OpenGL.
GL_INVALID_OPERATION is generated if program is not of type GL_PROGRAM_OBJECT.
GL_INVALID_OPERATION is generated if glBindAttribLocation is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_MAX_VERTEX_ATTRIBS
glGetActiveAttrib with argument program
glGetAttribLocation with arguments program and name
glIsProgram
See Also
glDisableVertexAttribArray, glEnableVertexAttribArray, glUseProgram, glVertexAttrib, glVertexAttribPointer
glBindBuffer
Bind a named buffer object
C Specification
void glBindBuffer(GLenum target,
GLuint buffer);
Parameters
glBindBuffer lets you create or use a named buffer object. Calling glBindBuffer with target set to GL_ARRAY_BUFFER, GL_ELEMENT_ARRAY_BUFFER, GL_PIXEL_PACK_BUFFER or GL_PIXEL_UNPACK_BUFFER and buffer set to the name of the new buffer object binds the buffer object name to the target. When a buffer object is bound to a target, the previous binding for that target is automatically broken.
Buffer object names are unsigned integers. The value zero is reserved, but there is no default buffer object for each buffer object target. Instead, buffer set to zero effectively unbinds any buffer object previously bound, and restores client memory usage for that buffer object target. Buffer object names and the corresponding buffer object contents are local to the shared display-list space (see glXCreateContext) of the current GL rendering context; two rendering contexts share buffer object names only if they also share display lists.
You may use glGenBuffers to generate a set of new buffer object names.
The state of a buffer object immediately after it is first bound is an unmapped zero-sized memory buffer with READ_WRITE access and STATIC_DRAW usage.
While a nonzero buffer object name is bound, GL operations on the target to which it is bound affect the bound buffer object, and queries of the target to which it is bound return state from the bound buffer object. While buffer object name zero is bound, as in the initial state, attempts to modify or query state on the target to which it is bound generates an INVALID_OPERATION error.
When vertex array pointer state is changed, for example by a call to glNormalPointer, the current buffer object binding (GL_ARRAY_BUFFER_BINDING) is copied into the corresponding client state for the vertex array type being changed, for example GL_NORMAL_ARRAY_BUFFER_BINDING. While a nonzero buffer object is bound to the GL_ARRAY_BUFFER target, the vertex array pointer parameter that is traditionally interpreted as a pointer to client-side memory is instead interpreted as an offset within the buffer object measured in basic machine units.
While a nonzero buffer object is bound to the GL_ARRAY_ELEMENT_BUFFER target, the indices parameter of glDrawElements, glDrawRangeElements, or glMultiDrawElements that is traditionally interpreted as a pointer to client-side memory is instead interpreted as an offset within the buffer object measured in basic machine units.
While a nonzero buffer object is bound to the GL_PIXEL_PACK_BUFFER target, the following commands are affected: glGetCompressedTexImage, glGetConvolutionFilter, glGetHistogram, glGetMinmax, glGetPixelMap, glGetPolygonStipple, glGetSeparableFilter, glGetTexImage, and glReadPixels. The pointer parameter that is traditionally interpreted as a pointer to client-side memory where the pixels are to be packed is instead interpreted as an offset within the buffer object measured in basic machine units.
While a nonzero buffer object is bound to the GL_PIXEL_UNPACK_BUFFER target, the following commands are affected: glBitmap, glColorSubTable, glColorTable, glCompressedTexImage1D, glCompressedTexImage2D, glCompressedTexImage3D, glCompressedTexSubImage1D, glCompressedTexSubImage2D, glCompressedTexSubImage3D, glConvolutionFilter1D, glConvolutionFilter2D, glDrawPixels, glPixelMap, glPolygonStipple, glSeparableFilter2D, glTexImage1D, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, and glTexSubImage3D. The pointer parameter that is traditionally interpreted as a pointer to client-side memory from which the pixels are to be unpacked is instead interpreted as an offset within the buffer object measured in basic machine units.
A buffer object binding created with glBindBuffer remains active until a different buffer object name is bound to the same target, or until the bound buffer object is deleted with glDeleteBuffers.
Once created, a named buffer object may be re-bound to any target as often as needed. However, the GL implementation may make choices about how to optimize the storage of a buffer object based on its initial binding target.
glBindBuffer is available only if the GL version is 1.5 or greater.
GL_PIXEL_PACK_BUFFER and GL_PIXEL_UNPACK_BUFFER are available only if the GL version is 2.1 or greater.
Errors
GL_INVALID_ENUM is generated if target is not one of the allowable values.
GL_INVALID_OPERATION is generated if glBindBuffer is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_ARRAY_BUFFER_BINDING
glGet with argument GL_ELEMENT_ARRAY_BUFFER_BINDING
glGet with argument GL_PIXEL_PACK_BUFFER_BINDING
glGet with argument GL_PIXEL_UNPACK_BUFFER_BINDING
See Also
glDeleteBuffers, glGenBuffers, glGet, glIsBuffer
glBindTexture
Bind a named texture to a texturing target
C Specification
void glBindTexture(GLenum target,
GLuint texture);
Parameters
Description
glBindTexture 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_CUBE_MAP 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 may use glGenTextures to generate a set of new texture names.
When a texture is first bound, it assumes the specified target: A texture first bound to GL_TEXTURE_1D becomes one-dimensional texture, a texture first bound to GL_TEXTURE_2D becomes two-dimensional texture, a texture first bound to GL_TEXTURE_3D becomes three-dimensional texture, and a texture first bound to GL_TEXTURE_CUBE_MAP becomes a cube-mapped texture. The state of a one-dimensional texture immediately after it is first bound is equivalent to the state of the default GL_TEXTURE_1D at GL initialization, and similarly for two- and three-dimensional textures and cube-mapped 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 is active on the target to which a texture is bound, 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 re-bound to its same original target 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, glTexImage2D, or glTexImage3D. For additional control over performance, use glPrioritizeTextures. glBindTexture is included in display lists.
Notes
glBindTexture is available only if the GL version is 1.1 or greater.
GL_TEXTURE_CUBE_MAP is available only if the GL version is 1.3 or greater.
Errors
GL_INVALID_ENUM is generated if target is not one of the allowable values.
GL_INVALID_OPERATION is generated if texture was previously created with a target that 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.
Associated Gets
glGet with argument GL_TEXTURE_BINDING_1D
glGet with argument GL_TEXTURE_BINDING_2D
glGet with argument GL_TEXTURE_BINDING_3D
See Also
glAreTexturesResident, glDeleteTextures, glGenTextures, glGet, glGetTexParameter, glIsTexture, glPrioritizeTextures, glTexImage1D, glTexImage2D, glTexParameter
glBitmap
Draw a bitmap
C Specification
void glBitmap(GLsizei width,
GLsizei height,
GLfloat xorig,
GLfloat yorig,
GLfloat xmove,
GLfloat ymove,
const GLubyte * bitmap);
Parameters
Description
A bitmap is a binary image. When drawn, the bitmap is positioned relative to the current raster position, and frame buffer pixels corresponding to 1’s in the bitmap are written using the current raster color or index. Frame buffer pixels corresponding to 0’s in the bitmap are not modified.
glBitmap takes seven arguments. The first pair specifies the width and height of the bitmap image. The second pair specifies the location of the bitmap origin relative to the lower-left corner of the bitmap image. The third pair of arguments specifies 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.
If a nonzero named buffer object is bound to the GL_PIXEL_UNPACK_BUFFER target (see glBindBuffer) while a bitmap image is specified, bitmap is treated as a byte offset into the buffer object’s data store.
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
xw = | xr – xo|
yw = | yr – yo|
where (xr,yr) is the raster position and (xo,yo) is the bitmap origin. Fragments are then generated for each pixel corresponding to a 1 (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, texture coordinates, or index.
Notes
To set a valid raster position outside the viewport, first set a valid raster position inside the viewport, then call glBitmap with NULL as the bitmap parameter and with xmove and ymove set to the offsets of the new raster position. This technique is useful when panning an image around the viewport.
Errors
GL_INVALID_VALUE is generated if width or height is negative.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the buffer object’s data store is currently mapped.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the data would be unpacked from the buffer object such that the memory reads required would exceed the data store size.
GL_INVALID_OPERATION is generated if glBitmap is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_CURRENT_RASTER_POSITION
glGet with argument GL_CURRENT_RASTER_COLOR
glGet with argument GL_CURRENT_RASTER_SECONDARY_COLOR
glGet with argument GL_CURRENT_RASTER_DISTANCE
glGet with argument GL_CURRENT_RASTER_INDEX
glGet with argument GL_CURRENT_RASTER_TEXTURE_COORDS
glGet with argument GL_CURRENT_RASTER_POSITION_VALID
glGet with argument GL_PIXEL_UNPACK_BUFFER_BINDING
See Also
glBindBuffer, glDrawPixels, glPixelStore, glPixelTransfer, glRasterPos, glWindowPos
glBlendColor
C Specification
void glBlendColor(GLclampf red,
GLclampf green,
GLclampf blue,
GLclampf alpha);
Parameters
Description
The GL_BLEND_COLOR may be used to calculate the source and destination blending factors. The color components are clamped to the range [0,1] before being stored. See glBlendFunc for a complete description of the blending operations. Initially the GL_BLEND_COLOR is set to (0, 0, 0, 0).
Notes
glBlendColor is part of the ARB_imaging subset. glBlendColor is present only if ARB_imaging is returned when glGetString is called with GL_EXTENSIONS as its argument.
Errors
GL_INVALID_OPERATION is generated if glBlendColor is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with an argument of GL_BLEND_COLOR
See Also
glBlendEquation, glBlendFunc, glGetString
glBlendEquation
Specify the equation used for both the RGB blend equation and the Alpha blend equation
C Specification
void glBlendEquation(GLenum mode);
Parameters
Description
The blend equations determine how a new pixel (the “source” color) is combined with a pixel already in the framebuffer (the “destination” color). This function sets both the RGB blend equation and the alpha blend equation to a single equation.
These equations use the source and destination blend factors specified by either glBlendFunc or glBlendFuncSeparate. See glBlendFunc or glBlendFuncSeparate for a description of the various blend factors.
In the equations that follow, source and destination color components are referred to as (Rs,Gs,Bs,As) and (Rd,Gd,Bd,Ad), respectively. The result color is referred to as (Rr,Gr,Br,Ar). The source and destination blend factors are denoted (sR,sG,sB,sA) and (dR,dG,dB,dA), respectively. For these equations all color components are understood to have values in the range [0,1].
The results of these equations are clamped to the range [0,1].
The GL_MIN and GL_MAX equations are useful for applications that analyze image data (image thresholding against a constant color, for example). The GL_FUNC_ADD equation is useful for antialiasing and transparency, among other things.
Initially, both the RGB blend equation and the alpha blend equation are set to GL_FUNC_ADD.
Notes
The GL_MIN, and GL_MAX equations do not use the source or destination factors, only the source and destination colors.
Errors
GL_INVALID_ENUM is generated if mode is not one of GL_FUNC_ADD, GL_FUNC_SUBTRACT, GL_FUNC_REVERSE_SUBTRACT, GL_MAX, or GL_MIN.
GL_INVALID_OPERATION is generated if glBlendEquation is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with an argument of GL_BLEND_EQUATION_RGB
glGet with an argument of GL_BLEND_EQUATION_ALPHA
See Also
glGetString, glBlendColor, glBlendFuncglBlendFuncSeparate
glBlendEquationSeparate
Set the RGB blend equation and the alpha blend equation separately
C Specification
void glBlendEquationSeparate(GLenum modeRGB,
GLenum modeAlpha);
Parameters
The blend equations determines how a new pixel (the “source” color) is combined with a pixel already in the framebuffer (the “destination” color). This function specifies one blend equation for the RGB-color components and one blend equation for the alpha component.
The blend equations use the source and destination blend factors specified by either glBlendFunc or glBlendFuncSeparate. See glBlendFunc or glBlendFuncSeparate for a description of the various blend factors.
In the equations that follow, source and destination color components are referred to as (Rs,Gs,Bs,As) and (Rd,Gd,Bd,Ad), respectively. The result color is referred to as (Rr,Gr,Br,Ar). The source and destination blend factors are denoted (sR,sG,sB,sA) and (dR,dG,dB,dA), respectively. For these equations all color components are understood to have values in the range [0,1].
The results of these equations are clamped to the range [0,1].
The GL_MIN and GL_MAX equations are useful for applications that analyze image data (image thresholding against a constant color, for example). The GL_FUNC_ADD equation is useful for antialiasing and transparency, among other things.
Initially, both the RGB blend equation and the alpha blend equation are set to GL_FUNC_ADD.
Notes
glBlendEquationSeparate is available only if the GL version is 2.0 or greater.
The GL_MIN, and GL_MAX equations do not use the source or destination factors, only the source and destination colors.
Errors
GL_INVALID_ENUM is generated if either modeRGB or modeAlpha is not one of GL_FUNC_ADD, GL_FUNC_SUBTRACT, GL_FUNC_REVERSE_SUBTRACT, GL_MAX, or GL_MIN.
GL_INVALID_OPERATION is generated if glBlendEquationSeparate is executed between the execution of glBegin and the corresponding execution of glEnd.
glGet with an argument of GL_BLEND_EQUATION_RGB
glGet with an argument of GL_BLEND_EQUATION_ALPHA
See Also
glGetString, glBlendColor, glBlendFunc, glBlendFuncSeparate
glBlendFunc
Specify pixel arithmetic
C Specification
void glBlendFunc(GLenum sfactor,
GLenum dfactor);
Parameters
Description
In RGBA 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). Blending is initially 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 method is used to scale the source color components. dfactor specifies which method is used to scale the destination color components. The possible methods are described in the following table. 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). The color specified by glBlendColor is referred to as (Rc,Gc,Bc,Ac). They are understood to have integer values between 0 and (kR,kG,kB,kA), where
kc = 2mc – 1
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].
In the table,
To determine the blended RGBA values of a pixel when drawing in RGBA 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 1 is guaranteed not to modify its multiplicand, and a blend factor equal to 0 reduces its multiplicand to 0. 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 = RsGd = GsBd = BsAd = As
Examples
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.
Notes
Incoming (source) alpha is correctly thought of as a material opacity, ranging from 1.0 (KA), representing complete opacity, to 0.0 (0), representing complete transparency.
When more than one color buffer is enabled for drawing, the GL performs blending separately for each enabled buffer, using the contents of that buffer for destination color. (See glDrawBuffer.)
Blending affects only RGBA rendering. It is ignored by color index renderers.
GL_CONSTANT_COLOR, GL_ONE_MINUS_CONSTANT_COLOR, GL_CONSTANT_ALPHA, GL_ONE_MINUS_CONSTANT_ALPHA are available only if the GL version is 1.4 or greater or if the ARB_imaging is supported by your implementation.
GL_SRC_COLOR and GL_ONE_MINUS_SRC_COLOR are valid only for sfactor if the GL version is 1.4 or greater.
GL_DST_COLOR and GL_ONE_MINUS_DST_COLOR are valid only for dfactor if the GL version is 1.4 or greater.
Errors
GL_INVALID_ENUM is generated if either sfactor or dfactor is not an accepted value.
GL_INVALID_OPERATION is generated if glBlendFunc is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_BLEND_SRC
glGet with argument GL_BLEND_DST
glIsEnabled with argument GL_BLEND
See Also
glAlphaFunc, glBlendColor, glBlendEquation, glBlendFuncSeparate, glClear, glDrawBuffer, glEnable, glLogicOp, glStencilFunc
glBlendFuncSeparate
Specify pixel arithmetic for RGB and alpha components separately
C Specification
void glBlendFuncSeparate(GLenum srcRGB,
GLenum dstRGB,
GLenum srcAlpha,
GLenum dstAlpha);
Description
In RGBA 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). Blending is initially disabled. Use glEnable and glDisable with argument GL_BLEND to enable and disable blending.
glBlendFuncSeparate defines the operation of blending when it is enabled. srcRGB specifies which method is used to scale the source RGB-color components. dstRGB specifies which method is used to scale the destination RGB-color components. Likewise, srcAlpha specifies which method is used to scale the source alpha color component, and dstAlpha specifies which method is used to scale the destination alpha component. The possible methods are described in the following table. 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). The color specified by glBlendColor is referred to as (Rc,Gc,Bc,Ac). They are understood to have integer values between 0 and (kR,kG,kB,kA), where
kc = 2mc – 1
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). All scale factors have range [0,1].
In the table,
i = min(As,1 – Ad)
To determine the blended RGBA values of a pixel when drawing in RGBA 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 1 is guaranteed not to modify its multiplicand, and a blend factor equal to 0 reduces its multiplicand to 0. For example, when srcRGB is GL_SRC_ALPHA, dstRGB is GL_ONE_MINUS_SRC_ALPHA, and As is equal to kA, the equations reduce to simple replacement:
Rd = RsGd = GsBd = BsAd = As
Notes
glBlendFuncSeparate is available only if the GL version is 1.4 or greater.
Incoming (source) alpha is correctly thought of as a material opacity, ranging from 1.0 (KA), representing complete opacity, to 0.0 (0), representing complete transparency.
When more than one color buffer is enabled for drawing, the GL performs blending separately for each enabled buffer, using the contents of that buffer for destination color. (See glDrawBuffer.)
Blending affects only RGBA rendering. It is ignored by color index renderers.
GL_CONSTANT_COLOR, GL_ONE_MINUS_CONSTANT_COLOR, GL_CONSTANT_ALPHA, GL_ONE_MINUS_CONSTANT_ALPHA are available only if the GL version is 1.4 or greater or if the ARB_imaging is supported by your implementation.
GL_SRC_COLOR and GL_ONE_MINUS_SRC_COLOR are valid only for srcRGB if the GL version is 1.4 or greater.
GL_DST_COLOR and GL_ONE_MINUS_DST_COLOR are valid only for dstRGB if the GL version is 1.4 or greater.
GL_INVALID_ENUM is generated if either srcRGB or dstRGB is not an accepted value.
GL_INVALID_OPERATION is generated if glBlendFuncSeparate is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_BLEND_SRC_RGB
glGet with argument GL_BLEND_SRC_ALPHA
glGet with argument GL_BLEND_DST_RGB
glGet with argument GL_BLEND_DST_ALPHA
glIsEnabled with argument GL_BLEND
See Also
glAlphaFunc, glBlendColor, glBlendFunc, glBlendEquation, glClear, glDrawBuffer, glEnable, glLogicOp, glStencilFunc
glBufferData
Create and initialize a buffer object’s data store
C Specification
void glBufferData(GLenum target,
GLsizeiptr size,
const GLvoid * data,
GLenum usage);
Parameters
Description
glBufferData creates a new data store for the buffer object currently bound to target. Any preexisting data store is deleted. The new data store is created with the specified size in bytes and usage. If data is not NULL, the data store is initialized with data from this pointer. In its initial state, the new data store is not mapped, it has a NULL mapped pointer, and its mapped access is GL_READ_WRITE.
usage is a hint to the GL implementation as to how a buffer object’s data store will be accessed. This enables the GL implementation to make more intelligent decisions that may significantly impact buffer object performance. It does not, however, constrain the actual usage of the data store. usage can be broken down into two parts: first, the frequency of access (modification and usage), and second, the nature of that access.
The frequency of access may be one of these:
STREAM
The data store contents will be modified once and used at most a few times.
STATIC
The data store contents will be modified once and used many times.
The data store contents will be modified repeatedly and used many times.
The nature of access may be one of these:
DRAW
The data store contents are modified by the application, and used as the source for GL drawing and image specification commands.
READ
The data store contents are modified by reading data from the GL, and used to return that data when queried by the application.
COPY
The data store contents are modified by reading data from the GL, and used as the source for GL drawing and image specification commands.
Notes
glBufferData is available only if the GL version is 1.5 or greater.
Targets GL_PIXEL_PACK_BUFFER and GL_PIXEL_UNPACK_BUFFER are available only if the GL version is 2.1 or greater.
If data is NULL, a data store of the specified size is still created, but its contents remain uninitialized and thus undefined.
Clients must align data elements consistent with the requirements of the client platform, with an additional base-level requirement that an offset within a buffer to a datum comprising NN.
Errors
GL_INVALID_ENUM is generated if target is not GL_ARRAY_BUFFER, GL_ELEMENT_ARRAY_BUFFER, GL_PIXEL_PACK_BUFFER, or GL_PIXEL_UNPACK_BUFFER.
GL_INVALID_ENUM is generated if usage is not GL_STREAM_DRAW, GL_STREAM_READ, GL_STREAM_COPY, GL_STATIC_DRAW, GL_STATIC_READ, GL_STATIC_COPY, GL_DYNAMIC_DRAW, GL_DYNAMIC_READ, or GL_DYNAMIC_COPY.
GL_INVALID_VALUE is generated if size is negative.
GL_INVALID_OPERATION is generated if the reserved buffer object name 0 is bound to target.
GL_OUT_OF_MEMORY is generated if the GL is unable to create a data store with the specified size.
GL_INVALID_OPERATION is generated if glBufferData is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetBufferSubData
glGetBufferParameteriv with argument GL_BUFFER_SIZE or GL_BUFFER_USAGE
See Also
glBindBuffer, glBufferSubData, glMapBuffer, glUnmapBuffer
glBufferSubData
Update a subset of a buffer object’s data store
C Specification
void glBufferSubData(GLenum target,
GLintptr offset,
GLsizeiptr size,
const GLvoid * data);
Description
glBufferSubData redefines some or all of the data store for the buffer object currently bound to target. Data starting at byte offset offset and extending for size bytes is copied to the data store from the memory pointed to by data. An error is thrown if offset and size together define a range beyond the bounds of the buffer object’s data store.
Notes
glBufferSubData is available only if the GL version is 1.5 or greater.
Targets GL_PIXEL_PACK_BUFFER and GL_PIXEL_UNPACK_BUFFER are available only if the GL version is 2.1 or greater.
When replacing the entire data store, consider using glBufferSubData rather than completely recreating the data store with glBufferData. This avoids the cost of reallocating the data store.
Consider using multiple buffer objects to avoid stalling the rendering pipeline during data store updates. If any rendering in the pipeline makes reference to data in the buffer object being updated by glBufferSubData, especially from the specific region being updated, that rendering must drain from the pipeline before the data store can be updated.
Clients must align data elements consistent with the requirements of the client platform, with an additional base-level requirement that an offset within a buffer to a datum comprising NN.
Errors
GL_INVALID_ENUM is generated if target is not GL_ARRAY_BUFFER, GL_ELEMENT_ARRAY_BUFFER, GL_PIXEL_PACK_BUFFER, or GL_PIXEL_UNPACK_BUFFER.
GL_INVALID_VALUE is generated if offset or size is negative, or if together they define a region of memory that extends beyond the buffer object’s allocated data store.
GL_INVALID_OPERATION is generated if the reserved buffer object name 0 is bound to target.
GL_INVALID_OPERATION is generated if the buffer object being updated is mapped.
GL_INVALID_OPERATION is generated if glBufferSubData is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetBufferSubData
See Also
glBindBuffer, glBufferData, glMapBuffer, glUnmapBuffer
glCallList
Execute a display list
C Specification
void glCallList(GLuint list);
Parameters
Description
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.
Notes
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.
Associated Gets
glGet with argument GL_MAX_LIST_NESTING
glIsList
See Also
glCallLists, glDeleteLists, glGenLists, glNewList, glPushAttrib, glPushMatrix
glCallLists
Execute a list of display lists
C Specification
void glCallLists(GLsizei n,
GLenum type,
const GLvoid * lists);
Parameters
Description
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 more than one display list. type allows lists with various name formats to be accepted. The formats are as follows:
GL_BYTE
lists is treated as an array of signed bytes, each in the range -128 through 127.
GL_UNSIGNED_BYTE
lists is treated as an array of unsigned bytes, each in the range 0 through 255.
GL_SHORT
lists is treated as an array of signed two-byte integers, each in the range -32768 through 32767.
GL_UNSIGNED_SHORT
lists is treated as an array of unsigned two-byte integers, each in the range 0 through 65535.
GL_INT
lists is treated as an array of signed four-byte integers.
GL_UNSIGNED_INT
lists is treated as an array of unsigned four-byte integers.
lists is treated as an array of four-byte floating-point values.
GL_2_BYTES
lists is treated as an array of unsigned bytes. Each pair of bytes specifies a single display-list name. The value of the pair is computed as 256 times the unsigned value of the first byte plus the unsigned value of the second byte.
GL_3_BYTES
lists is treated as an array of unsigned bytes. Each triplet of bytes specifies a single display-list name. The value of the triplet is computed as 65536 times the unsigned value of the first byte, plus 256 times the unsigned value of the second byte, plus the unsigned value of the third byte.
GL_4_BYTES
lists is treated as an array of unsigned bytes. Each quadruplet of bytes specifies a single display-list name. The value of the quadruplet is computed as 16777216 times the unsigned value of the first byte, plus 65536 times the unsigned value of the second byte, plus 256 times the unsigned value of the third byte, plus the unsigned value of the fourth byte.
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.
Notes
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.
Errors
GL_INVALID_VALUE is generated if n is negative.
GL_INVALID_ENUM is generated if type is not one of GL_BYTE, GL_UNSIGNED_BYTE, GL_SHORT, GL_UNSIGNED_SHORT, GL_INT, GL_UNSIGNED_INT, GL_FLOAT, GL_2_BYTES, GL_3_BYTES, GL_4_BYTES.
Associated Gets
glGet with argument GL_LIST_BASE
glGet with argument GL_MAX_LIST_NESTING
glIsList
See Also
glCallList, glDeleteLists, glGenLists, glListBase, glNewList, glPushAttrib, glPushMatrix
glClear
Clear buffers to preset values
C Specification
void glClear(GLbitfield mask);
Description
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 depth-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:
GL_COLOR_BUFFER_BIT
Indicates the buffers currently enabled for color writing.
GL_DEPTH_BUFFER_BIT
Indicates the depth buffer.
GL_ACCUM_BUFFER_BIT
Indicates the accumulation buffer.
GL_STENCIL_BUFFER_BIT
Indicates the stencil buffer.
The value to which each buffer is cleared depends on the setting of the clear value for that buffer.
Notes
If a buffer is not present, then a glClear directed at that buffer has no effect.
Errors
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 executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
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
See Also
glClearAccum, glClearColor, glClearDepth, glClearIndex, glClearStencil, glColorMask, glDepthMask, glDrawBuffer, glScissor, glStencilMask
glClearAccum
Specify clear values for the accumulation buffer
C Specification
void glClearAccum(GLfloat red,
GLfloat green,
GLfloat blue,
GLfloat alpha);
Description
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].
Errors
GL_INVALID_OPERATION is generated if glClearAccum is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_ACCUM_CLEAR_VALUE
See Also
glAccum, glClear
glClearColor
Specify clear values for the color buffers
C Specification
void glClearColor(GLclampf red,
GLclampf green,
GLclampf blue,
GLclampf alpha);
Parameters
Description
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].
Errors
GL_INVALID_OPERATION is generated if glClearColor is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_COLOR_CLEAR_VALUE
See Also
glClear
glClearDepth
Specify the clear value for the depth buffer
C Specification
void glClearDepth(GLclampd depth);
Parameters
Description
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 executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_DEPTH_CLEAR_VALUE
See Also
glClear
glClearIndex
Specify the clear value for the color index buffers
C Specification
void glClearIndex(GLfloat c);
Parameters
Description
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.
Errors
GL_INVALID_OPERATION is generated if glClearIndex is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_INDEX_CLEAR_VALUE
glGet with argument GL_INDEX_BITS
See Also
glClear
glClearStencil
Specify the clear value for the stencil buffer
C Specification
void glClearStencil(GLint s);
Parameters
Description
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.
Errors
GL_INVALID_OPERATION is generated if glClearStencil is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_STENCIL_CLEAR_VALUE
glGet with argument GL_STENCIL_BITS
See Also
glClear, glStencilFunc, glStencilFuncSeparate, glStencilMask, glStencilMaskSeparate, glStencilOp, glStencilOpSeparate
glClientActiveTexture
C Specification
void glClientActiveTexture(GLenum texture);
Parameters
Description
glClientActiveTexture selects the vertex array client state parameters to be modified by glTexCoordPointer, and enabled or disabled with glEnableClientState or glDisableClientState, respectively, when called with a parameter of GL_TEXTURE_COORD_ARRAY.
Notes
glClientActiveTexture is supported only if the GL version is 1.3 or greater, or ARB_multitexture is included in the string returned by glGetString when called with the argument GL_EXTENSIONS.
Errors
GL_INVALID_ENUM is generated if texture is not one of GL_TEXTUREi, where i ranges from 0 to the value of GL_MAX_TEXTURE_COORDS - 1.
Associated Gets
glGet with argument GL_CLIENT_ACTIVE_TEXTURE or GL_MAX_TEXTURE_COORDS
See Also
glActiveTexture, glDisableClientState, glEnableClientState, glMultiTexCoord, glTexCoordPointer
glClipPlane
Specify a plane against which all geometry is clipped
C Specification
void glClipPlane(GLenum plane,
const GLdouble * equation);
Parameters
Description
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. To determine the maximum number of additional clipping planes, call glGetIntegerv with argument GL_MAX_CLIP_PLANES. All implementations support at least six such clipping planes. 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.
To enable and disable clipping planes, call glEnable and glDisable with the argument GL_CLIP_PLANEi, where i is the plane number.
All clipping planes are initially defined as (0, 0, 0, 0) in eye coordinates and are disabled.
Notes
It is always the case that GL_CLIP_PLANEi = GL_CLIP_PLANE0 + i.
Errors
GL_INVALID_ENUM is generated if plane is not an accepted value.
GL_INVALID_OPERATION is generated if glClipPlane is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetClipPlane
glIsEnabled with argument GL_CLIP_PLANEi
See Also
glEnable
glColor
Set the current color
C Specification
Parameters
C Specification
void glColor3bv(const GLbyte * v);
void glColor3sv(const GLshort * v);
void glColor3iv(const GLint * v);
void glColor3fv(const GLfloat * v);
void glColor3dv(const GLdouble * v);
void glColor3ubv(const GLubyte * v);
void glColor3usv(const GLushort * v);
void glColor3uiv(const GLuint * v);
void glColor4bv(const GLbyte * v);
void glColor4sv(const GLshort * v);
void glColor4iv(const GLint * v);
void glColor4fv(const GLfloat * v);
void glColor4dv(const GLdouble * v);
void glColor4ubv(const GLubyte * v);
void glColor4usv(const GLushort * v);
void glColor4uiv(const GLuint * v);
Parameters
Description
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 (full intensity) implicitly. glColor4 variants specify all four color components explicitly.
glColor3b, glColor4b, glColor3s, glColor4s, glColor3i, and glColor4i take three or four signed byte, short, or long integers as arguments. When v is appended to the name, the color commands can take a pointer to an array of such values.
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 0 maps to 0.0 (zero intensity). Signed integer color components, when specified, are linearly mapped to floating-point values such that the most positive representable value maps to 1.0, and the most negative representable value maps to -1.0. (Note that this mapping does not convert 0 precisely to 0.0.) Floating-point values are mapped directly.
Neither floating-point nor signed integer values are clamped to the range [0,1] before the current color is updated. However, color components are clamped to this range before they are interpolated or written into a color buffer.
Notes
The initial value for the current color is (1, 1, 1, 1).
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.
Associated Gets
glGet with argument GL_CURRENT_COLOR
glGet with argument GL_RGBA_MODE
See Also
glColorPointer, glIndex, glSecondaryColor
glColorMask
Enable and disable writing of frame buffer color components
C Specification
void glColorMask(GLboolean red,
GLboolean green,
GLboolean blue,
GLboolean alpha);
Parameters
Description
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.
Errors
GL_INVALID_OPERATION is generated if glColorMask is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_COLOR_WRITEMASK
glGet with argument GL_RGBA_MODE
See Also
glClear, glColor, glColorPointer, glDepthMask, glIndex, glIndexPointer, glIndexMask, glStencilMask
glColorMaterial
Cause a material color to track the current color
C Specification
void glColorMaterial(GLenum face,
GLenum mode);
Parameters
Description
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.
To enable and disable GL_COLOR_MATERIAL, call glEnable and glDisable with argument GL_COLOR_MATERIAL. GL_COLOR_MATERIAL is initially disabled.
Notes
glColorMaterial makes it possible to change a subset of material parameters 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, calling glColorMaterial is preferable to calling glMaterial.
Call glColorMaterial before enabling GL_COLOR_MATERIAL.
Calling glDrawElements, glDrawArrays, or glDrawRangeElements may leave the current color indeterminate, if the color array is enabled. If glColorMaterial is enabled while the current color is indeterminate, the lighting material state specified by face and mode is also indeterminate.
If the GL version is 1.1 or greater, and GL_COLOR_MATERIAL is enabled, evaluated color values affect the results of the lighting equation as if the current color were being modified, but no change is made to the tracking lighting parameter of the current color.
Errors
GL_INVALID_ENUM is generated if face or mode is not an accepted value.
GL_INVALID_OPERATION is generated if glColorMaterial is executed between the execution of glBegin and the corresponding execution of glEnd.
glIsEnabled with argument GL_COLOR_MATERIAL
glGet with argument GL_COLOR_MATERIAL_PARAMETER
glGet with argument GL_COLOR_MATERIAL_FACE
See Also
glColor, glColorPointer, glDrawArrays, glDrawElements, glDrawRangeElements, glEnable, glLight, glLightModel, glMaterial
glColorPointer
Define an array of colors
C Specification
void glColorPointer(GLint size,
GLenum type,
GLsizei stride,
const GLvoid * pointer);
Parameters
Description
glColorPointer specifies the location and data format of an array of color components to use when rendering. size specifies the number of components per color, and must be 3 or 4. type specifies the data type of each color component, and stride specifies the byte stride from one color to the next, allowing vertices and attributes to be packed into a single array or stored in separate arrays. (Single-array storage may be more efficient on some implementations; see glInterleavedArrays.)
If a nonzero named buffer object is bound to the GL_ARRAY_BUFFER target (see glBindBuffer) while a color array is specified, pointer is treated as a byte offset into the buffer object’s data store. Also, the buffer object binding (GL_ARRAY_BUFFER_BINDING) is saved as color vertex array client-side state (GL_COLOR_ARRAY_BUFFER_BINDING).
When a color array is specified, size, type, stride, and pointer are saved as client-side state, in addition to the current vertex array buffer object binding.
To enable and disable the color array, call glEnableClientState and glDisableClientState with the argument GL_COLOR_ARRAY. If enabled, the color array is used when glDrawArrays, glMultiDrawArrays, glDrawElements, glMultiDrawElements, glDrawRangeElements, or glArrayElement is called.
Notes
glColorPointer is available only if the GL version is 1.1 or greater.
The color array is initially disabled and isn’t accessed when glArrayElement, glDrawElements, glDrawRangeElements, glDrawArrays, glMultiDrawArrays, or glMultiDrawElements is called.
Execution of glColorPointer is not allowed between the execution of glBegin and the corresponding execution of glEnd, but an error may or may not be generated. If no error is generated, the operation is undefined.
glColorPointer is typically implemented on the client side.
Color array parameters are client-side state and are therefore not saved or restored by glPushAttrib and glPopAttrib. Use glPushClientAttrib and glPopClientAttrib instead.
Errors
GL_INVALID_VALUE is generated if size is not 3 or 4.
GL_INVALID_ENUM is generated if type is not an accepted value.
GL_INVALID_VALUE is generated if stride is negative.
Associated Gets
glIsEnabled with argument GL_COLOR_ARRAY
glGet with argument GL_COLOR_ARRAY_SIZE
glGet with argument GL_COLOR_ARRAY_TYPE
glGet with argument GL_COLOR_ARRAY_STRIDE
glGet with argument GL_COLOR_ARRAY_BUFFER_BINDING
glGet with argument GL_ARRAY_BUFFER_BINDING
glGetPointerv with argument GL_COLOR_ARRAY_POINTER
See Also
glArrayElement, glBindBuffer, glColor, glDisableClientState, glDrawArrays, glDrawElements, glDrawRangeElements, glEdgeFlagPointer, glEnableClientState, glFogCoordPointer, glIndexPointer, glInterleavedArrays, glMultiDrawArrays, glMultiDrawElements, glNormalPointer, glPopClientAttrib, glPushClientAttrib, glSecondaryColorPointer, glTexCoordPointer, glVertexAttribPointer, glVertexPointer
glColorSubTable
Respecify a portion of a color table
C Specification
void glColorSubTable(GLenum target,
GLsizei start,
GLsizei count,
GLenum format,
GLenum type,
const GLvoid * data);
Parameters
glColorSubTable is used to respecify a contiguous portion of a color table previously defined using glColorTable. The pixels referenced by data replace the portion of the existing table from indices start to start + count – 1, inclusive. This region may not include any entries outside the range of the color table as it was originally specified. It is not an error to specify a subtexture with width of 0, but such a specification has no effect.
If a nonzero named buffer object is bound to the GL_PIXEL_UNPACK_BUFFER target (see glBindBuffer) while a portion of a color table is respecified, data is treated as a byte offset into the buffer object’s data store.
Notes
glColorSubTable is present only if ARB_imaging is returned when glGetString is called with an argument of GL_EXTENSIONS.
Errors
GL_INVALID_ENUM is generated if target is not one of the allowable values.
GL_INVALID_ENUM is generated if format is not one of the allowable values.
GL_INVALID_ENUM is generated if type is not one of the allowable values.
GL_INVALID_VALUE is generated if start + count > width.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the buffer object’s data store is currently mapped.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the data would be unpacked from the buffer object such that the memory reads required would exceed the data store size.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and data is not evenly divisible into the number of bytes needed to store in memory a datum indicated by type.
GL_INVALID_OPERATION is generated if glColorSubTable is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetColorTable, glGetColorTableParameter
glGet with argument GL_PIXEL_UNPACK_BUFFER_BINDING
See Also
glColorTable, glColorTableParameter, glCopyColorTable, glCopyColorSubTable, glGetColorTable
glColorTable
Define a color lookup table
C Specification
void glColorTable(GLenum target,
GLenum internalformat,
GLsizei width,
GLenum format,
GLenum type,
const GLvoid * data);
Parameters
Description
glColorTable may be used in two ways: to test the actual size and color resolution of a lookup table given a particular set of parameters, or to load the contents of a color lookup table. Use the targets GL_PROXY_* for the first case and the other targets for the second case.
If a nonzero named buffer object is bound to the GL_PIXEL_UNPACK_BUFFER target (see glBindBuffer) while a color table is specified, data is treated as a byte offset into the buffer object’s data store.
If target is GL_COLOR_TABLE, GL_POST_CONVOLUTION_COLOR_TABLE, or GL_POST_COLOR_MATRIX_COLOR_TABLE, glColorTable builds a color lookup table from an array of pixels. The pixel array specified by width, format, type, and data is extracted from memory and processed just as if glDrawPixels were called, but processing stops after the final expansion to RGBA is completed.
The four scale parameters and the four bias parameters that are defined for the table are then used to scale and bias the R, G, B, and A components of each pixel. (Use glColorTableParameter to set these scale and bias parameters.)
Next, the R, G, B, and A values are clamped to the range [0,1]. Each pixel is then converted to the internal format specified by internalformat. This conversion simply maps the component values of the pixel (R, G, B, and A) to the values included in the internal format (red, green, blue, alpha, luminance, and intensity). The mapping is as follows:
Finally, the red, green, blue, alpha, luminance, and/or intensity components of the resulting pixels are stored in the color table. They form a one-dimensional table with indices in the range [0,width – 1].
If target is GL_PROXY_*, glColorTable recomputes and stores the values of the proxy color table’s state variables GL_COLOR_TABLE_FORMAT, GL_COLOR_TABLE_WIDTH, GL_COLOR_TABLE_RED_SIZE, GL_COLOR_TABLE_GREEN_SIZE, GL_COLOR_TABLE_BLUE_SIZE, GL_COLOR_TABLE_ALPHA_SIZE, GL_COLOR_TABLE_LUMINANCE_SIZE, and GL_COLOR_TABLE_INTENSITY_SIZE. There is no effect on the image or state of any actual color table. If the specified color table is too large to be supported, then all the proxy state variables listed above are set to zero. Otherwise, the color table could be supported by glColorTable using the corresponding non-proxy target, and the proxy state variables are set as if that target were being defined.
The proxy state variables can be retrieved by calling glGetColorTableParameter with a target of GL_PROXY_*. This allows the application to decide if a particular glColorTable command would succeed, and to determine what the resulting color table attributes would be.
If a color table is enabled, and its width is nonzero, then its contents are used to replace a subset of the components of each RGBA pixel group, based on the internal format of the table.
Each pixel group has color components (R, G, B, A) that are in the range [0.0,1.0]. The color components are rescaled to the size of the color lookup table to form an index. Then a subset of the components based on the internal format of the table are replaced by the table entry selected by that index. If the color components and contents of the table are represented as follows:
then the result of color table lookup is as follows:
When GL_COLOR_TABLE is enabled, the colors resulting from the pixel map operation (if it is enabled) are mapped by the color lookup table before being passed to the convolution operation. The colors resulting from the convolution operation are modified by the post convolution color lookup table when GL_POST_CONVOLUTION_COLOR_TABLE is enabled. These modified colors are then sent to the color matrix operation. Finally, if GL_POST_COLOR_MATRIX_COLOR_TABLE is enabled, the colors resulting from the color matrix operation are mapped by the post color matrix color lookup table before being used by the histogram operation.
glColorTable is present only if ARB_imaging is returned when glGetString is called with an argument of GL_EXTENSIONS.
If target is set to GL_COLOR_TABLE, GL_POST_CONVOLUTION_COLOR_TABLE, or GL_POST_COLOR_MATRIX_COLOR_TABLE, then width must be a power of two or a GL_INVALID_VALUE error is generated.
Errors
GL_INVALID_ENUM is generated if target is not one of the allowable values.
GL_INVALID_ENUM is generated if internalformat is not one of the allowable values.
GL_INVALID_ENUM is generated if format is not one of the allowable values.
GL_INVALID_ENUM is generated if type is not one of the allowable values.
GL_INVALID_VALUE is generated if width is less than zero.
GL_TABLE_TOO_LARGE is generated if the requested color table is too large to be supported by the implementation, and target is not a GL_PROXY_* target.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the buffer object’s data store is currently mapped.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the data would be unpacked from the buffer object such that the memory reads required would exceed the data store size.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and data is not evenly divisible into the number of bytes needed to store in memory a datum indicated by type.
GL_INVALID_OPERATION is generated if glColorTable is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetColorTableParameter
glGet with argument GL_PIXEL_UNPACK_BUFFER_BINDING
See Also
glColorSubTable, glColorTableParameter, glCopyColorTable, glCopyColorSubTable, glGetColorTable
glColorTableParameter
Set color lookup table parameters
C Specification
void glColorTableParameterfv(GLenum target,
GLenum pname,
const GLfloat * params);
void glColorTableParameteriv(GLenum target,
GLenum pname,
const GLint * params);
Parameters
glColorTableParameter is used to specify the scale factors and bias terms applied to color components when they are loaded into a color table. target indicates which color table the scale and bias terms apply to; it must be set to GL_COLOR_TABLE, GL_POST_CONVOLUTION_COLOR_TABLE, or GL_POST_COLOR_MATRIX_COLOR_TABLE.
pname must be GL_COLOR_TABLE_SCALE to set the scale factors. In this case, params points to an array of four values, which are the scale factors for red, green, blue, and alpha, in that order.
pname must be GL_COLOR_TABLE_BIAS to set the bias terms. In this case, params points to an array of four values, which are the bias terms for red, green, blue, and alpha, in that order.
The color tables themselves are specified by calling glColorTable.
Notes
glColorTableParameter is available only if ARB_imaging is returned from calling glGetString with an argument of GL_EXTENSIONS.
Errors
GL_INVALID_ENUM is generated if target or pname is not an acceptable value.
GL_INVALID_OPERATION is generated if glColorTableParameter is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetColorTableParameter
See Also
glColorTable, glPixelTransfer
glCompileShader
Compile a shader object
C Specification
void glCompileShader(GLuint shader);
Parameters
Description
glCompileShader compiles the source code strings that have been stored in the shader object specified by shader.
The compilation status will be stored as part of the shader object’s state. This value will be set to GL_TRUE if the shader was compiled without errors and is ready for use, and GL_FALSE otherwise. It can be queried by calling glGetShader with arguments shader and GL_COMPILE_STATUS.
Compilation of a shader can fail for a number of reasons as specified by the OpenGL Shading Language Specification. Whether or not the compilation was successful, information about the compilation can be obtained from the shader object’s information log by calling glGetShaderInfoLog.
Notes
glCompileShader is available only if the GL version is 2.0 or greater.
Errors
GL_INVALID_VALUE is generated if shader is not a value generated by OpenGL.
GL_INVALID_OPERATION is generated if shader is not of type GL_SHADER_OBJECT.
GL_INVALID_OPERATION is generated if glCompileShader is executed between the execution of glBegin and the corresponding execution of glEnd.
glGetShaderInfoLog with argument shader
glGetShader with arguments shader and GL_COMPILE_STATUS
glIsShader
See Also
glCreateShader, glLinkProgram, glShaderSource
glCompressedTexImage1D
Specify a one-dimensional texture image in a compressed format
C Specification
void glCompressedTexImage1D(GLenum target,
GLint level,
GLenum internalformat,
GLsizei width,
GLint border,
GLsizei imageSize,
const GLvoid * data);
Parameters
Description
Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is enabled. To enable and disable one-dimensional texturing, call glEnable and glDisable with argument GL_TEXTURE_1D.
glCompressedTexImage1D loads a previously defined, and retrieved, compressed one-dimensional texture image if target is GL_TEXTURE_1D (see glTexImage1D).
If target is GL_PROXY_TEXTURE_1D, no data is read from data, but all of the texture image state is recalculated, checked for consistency, and checked against the implementation’s capabilities. If the implementation cannot handle a texture of the requested texture size, it sets all of the image state to 0, but does not generate an error (see glGetError). To query for an entire mipmap array, use an image array level greater than or equal to 1.
internalformat must be extension-specified compressed-texture format. When a texture is loaded with glTexImage1D using a generic compressed texture format (e.g., GL_COMPRESSED_RGB) the GL selects from one of its extensions supporting compressed textures. In order to load the compressed texture image using glCompressedTexImage1D, query the compressed texture image’s size and format using glGetTexLevelParameter.
If a nonzero named buffer object is bound to the GL_PIXEL_UNPACK_BUFFER target (see glBindBuffer) while a texture image is specified, data is treated as a byte offset into the buffer object’s data store.
Notes
glCompressedTexImage1D is available only if the GL version is 1.3 or greater.
Non-power-of-two textures are supported if the GL version is 2.0 or greater, or if the implementation exports the GL_ARB_texture_non_power_of_two extension.
Errors
GL_INVALID_ENUM is generated if internalformat is of the generic compressed internal formats: GL_COMPRESSED_ALPHA, GL_COMPRESSED_LUMINANCE, GL_COMPRESSED_LUMINANCE_ALPHA, GL_COMPRESSED_INTENSITY, GL_COMPRESSED_RGB, or GL_COMPRESSED_RGBA.
GL_INVALID_VALUE is generated if imageSize is not consistent with the format, dimensions, and contents of the specified compressed image data.
GL_INVALID_OPERATION is generated if parameter combinations are not supported by the specific compressed internal format as specified in the specific texture compression extension.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the buffer object’s data store is currently mapped.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the data would be unpacked from the buffer object such that the memory reads required would exceed the data store size.
GL_INVALID_OPERATION is generated if glCompressedTexImage1D is executed between the execution of glBegin and the corresponding execution of glEnd.
Undefined results, including abnormal program termination, are generated if data is not encoded in a manner consistent with the extension specification defining the internal compression format.
Associated Gets
glGetCompressedTexImage
glGet with argument GL_TEXTURE_COMPRESSED
glGet with argument GL_PIXEL_UNPACK_BUFFER_BINDING
glGetTexLevelParameter with arguments GL_TEXTURE_INTERNAL_FORMAT and GL_TEXTURE_COMPRESSED_IMAGE_SIZE
glIsEnabled with argument GL_TEXTURE_1D
See Also
glActiveTexture, glColorTable, glCompressedTexImage2D, glCompressedTexImage3D, glCompressedTexSubImage1D, glCompressedTexSubImage2D, glCompressedTexSubImage3D, glConvolutionFilter1D, glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glMatrixMode, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D, glTexParameter
glCompressedTexImage2D
Specify a two-dimensional texture image in a compressed format
C Specification
void glCompressedTexImage2D(GLenum target,
GLint level,
GLenum internalformat,
GLsizei width,
GLsizei height,
GLint border,
GLsizei imageSize,
const GLvoid * data);
Description
Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is enabled. To enable and disable two-dimensional texturing, call glEnable and glDisable with argument GL_TEXTURE_2D. To enable and disable texturing using cube-mapped textures, call glEnable and glDisable with argument GL_TEXTURE_CUBE_MAP.
glCompressedTexImage2D loads a previously defined, and retrieved, compressed two-dimensional texture image if target is GL_TEXTURE_2D (see glTexImage2D).
If target is GL_PROXY_TEXTURE_2D, no data is read from data, but all of the texture image state is recalculated, checked for consistency, and checked against the implementation’s capabilities. If the implementation cannot handle a texture of the requested texture size, it sets all of the image state to 0, but does not generate an error (see glGetError). To query for an entire mipmap array, use an image array level greater than or equal to 1.
internalformat must be an extension-specified compressed-texture format. When a texture is loaded with glTexImage2D using a generic compressed texture format (e.g., GL_COMPRESSED_RGB), the GL selects from one of its extensions supporting compressed textures. In order to load the compressed texture image using glCompressedTexImage2D, query the compressed texture image’s size and format using glGetTexLevelParameter.
If a nonzero named buffer object is bound to the GL_PIXEL_UNPACK_BUFFER target (see glBindBuffer) while a texture image is specified, data is treated as a byte offset into the buffer object’s data store.
glCompressedTexImage2D is available only if the GL version is 1.3 or greater.
Non-power-of-two textures are supported if the GL version is 2.0 or greater, or if the implementation exports the GL_ARB_texture_non_power_of_two extension.
The GL_COMPRESSED_SRGB, GL_COMPRESSED_SRGBA, GL_COMPRESSED_SRGB_ALPHA, GL_COMPRESSED_SLUMINANCE, and GL_COMPRESSED_SLUMINANCE_ALPHA internal formats are only available if the GL version is 2.1 or greater.
Errors
GL_INVALID_ENUM is generated if internalformat is not one of these generic compressed internal formats: GL_COMPRESSED_ALPHA, GL_COMPRESSED_LUMINANCE, GL_COMPRESSED_LUMINANCE_ALPHA, GL_COMPRESSED_INTENSITY, GL_COMPRESSED_RGB, GL_COMPRESSED_RGBA, GL_COMPRESSED_SLUMINANCE, GL_COMPRESSED_SLUMINANCE_ALPHA, GL_COMPRESSED_SRGB, GL_COMPRESSED_SRGBA, or GL_COMPRESSED_SRGB_ALPHA.
GL_INVALID_VALUE is generated if imageSize is not consistent with the format, dimensions, and contents of the specified compressed image data.
GL_INVALID_OPERATION is generated if parameter combinations are not supported by the specific compressed internal format as specified in the specific texture compression extension.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the buffer object’s data store is currently mapped.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the data would be unpacked from the buffer object such that the memory reads required would exceed the data store size.
GL_INVALID_OPERATION is generated if glCompressedTexImage2D is executed between the execution of glBegin and the corresponding execution of glEnd.
Undefined results, including abnormal program termination, are generated if data is not encoded in a manner consistent with the extension specification defining the internal compression format.
Associated Gets
glGetCompressedTexImage
glGet with argument GL_TEXTURE_COMPRESSED
glGet with argument GL_PIXEL_UNPACK_BUFFER_BINDING
glGetTexLevelParameter with arguments GL_TEXTURE_INTERNAL_FORMAT and GL_TEXTURE_COMPRESSED_IMAGE_SIZE
glIsEnabled with argument GL_TEXTURE_2D
See Also
glActiveTexture, glColorTable, glCompressedTexImage1D, glCompressedTexImage3D, glCompressedTexSubImage1D, glCompressedTexSubImage2D, glCompressedTexSubImage3D, glConvolutionFilter1D, glCopyPixels, glCopyTexImage1D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glMatrixMode, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D, glTexParameter
glCompressedTexImage3D
Specify a three-dimensional texture image in a compressed format
C Specification
void glCompressedTexImage3D(GLenum target,
GLint level,
GLenum internalformat,
GLsizei width,
GLsizei height,
GLsizei depth,
GLint border,
GLsizei imageSize,
const GLvoid * data);
Parameters
Description
Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is enabled. To enable and disable three-dimensional texturing, call glEnable and glDisable with argument GL_TEXTURE_3D.
glCompressedTexImage3D loads a previously defined, and retrieved, compressed three-dimensional texture image if target is GL_TEXTURE_3D (see glTexImage3D).
If target is GL_PROXY_TEXTURE_3D, no data is read from data, but all of the texture image state is recalculated, checked for consistency, and checked against the implementation’s capabilities. If the implementation cannot handle a texture of the requested texture size, it sets all of the image state to 0, but does not generate an error (see glGetError). To query for an entire mipmap array, use an image array level greater than or equal to 1.
internalformat must be an extension-specified compressed-texture format. When a texture is loaded with glTexImage2D using a generic compressed texture format (e.g., GL_COMPRESSED_RGB), the GL selects from one of its extensions supporting compressed textures. In order to load the compressed texture image using glCompressedTexImage3D, query the compressed texture image’s size and format using glGetTexLevelParameter.
If a nonzero named buffer object is bound to the GL_PIXEL_UNPACK_BUFFER target (see glBindBuffer) while a texture image is specified, data is treated as a byte offset into the buffer object’s data store.
Notes
glCompressedTexImage3D is available only if the GL version is 1.3 or greater. Non-power-of-two textures are supported if the GL version is 2.0 or greater, or if the implementation exports the GL_ARB_texture_non_power_of_two extension.
The GL_COMPRESSED_SRGB, GL_COMPRESSED_SRGBA, GL_COMPRESSED_SRGB_ALPHA, GL_COMPRESSED_SLUMINANCE, and GL_COMPRESSED_SLUMINANCE_ALPHA internal formats are only available if the GL version is 2.1 or greater.
Errors
GL_INVALID_ENUM is generated if internalformat is not one of these generic compressed internal formats: GL_COMPRESSED_ALPHA, GL_COMPRESSED_LUMINANCE, GL_COMPRESSED_LUMINANCE_ALPHA, GL_COMPRESSED_INTENSITY, GL_COMPRESSED_RGB, GL_COMPRESSED_RGBA, GL_COMPRESSED_SLUMINANCE, GL_COMPRESSED_SLUMINANCE_ALPHA, GL_COMPRESSED_SRGB, GL_COMPRESSED_SRGBA, or GL_COMPRESSED_SRGB_ALPHA.
GL_INVALID_VALUE is generated if imageSize is not consistent with the format, dimensions, and contents of the specified compressed image data.
GL_INVALID_OPERATION is generated if parameter combinations are not supported by the specific compressed internal format as specified in the specific texture compression extension.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the buffer object’s data store is currently mapped.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the data would be unpacked from the buffer object such that the memory reads required would exceed the data store size.
GL_INVALID_OPERATION is generated if glCompressedTexImage3D is executed between the execution of glBegin and the corresponding execution of glEnd.
Undefined results, including abnormal program termination, are generated if data is not encoded in a manner consistent with the extension specification defining the internal compression format.
Associated Gets
glGetCompressedTexImage
glGet with argument GL_TEXTURE_COMPRESSED
glGet with argument GL_PIXEL_UNPACK_BUFFER_BINDING
glGetTexLevelParameter with arguments GL_TEXTURE_INTERNAL_FORMAT and GL_TEXTURE_COMPRESSED_IMAGE_SIZE
glIsEnabled with argument GL_TEXTURE_3D
See Also
glActiveTexture, glColorTable, glCompressedTexImage1D, glCompressedTexImage2D, glCompressedTexSubImage1D, glCompressedTexSubImage2D, glCompressedTexSubImage3D, glConvolutionFilter1D, glCopyPixels, glCopyTexImage1D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glMatrixMode, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage1D, glTexImage2D, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D, glTexParameter
glCompressedTexSubImage1D
Specify a one-dimensional texture subimage in a compressed format
C Specification
void glCompressedTexSubImage1D(GLenum target,
GLint level,
GLint xoffset,
GLsizei width,
GLenum format,
GLsizei imageSize,
const GLvoid * data);
Parameters
Description
Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is enabled. To enable and disable one-dimensional texturing, call glEnable and glDisable with argument GL_TEXTURE_1D.
glCompressedTexSubImage1D redefines a contiguous subregion of an existing one-dimensional texture image. The texels referenced by data replace the portion of the existing texture array with x indices xoffset and xoffset + width – 1, inclusive. This region may not include any texels outside the range of the texture array as it was originally specified. It is not an error to specify a subtexture with width of 0, but such a specification has no effect.
format must be an extension-specified compressed-texture format. The format of the compressed texture image is selected by the GL implementation that compressed it (see glTexImage1D), and should be queried at the time the texture was compressed with glGetTexLevelParameter.
If a nonzero named buffer object is bound to the GL_PIXEL_UNPACK_BUFFER target (see glBindBuffer) while a texture image is specified, data is treated as a byte offset into the buffer object’s data store.
Notes
glCompressedTexSubImage1D is available only if the GL version is 1.3 or greater.
Errors
GL_INVALID_ENUM is generated if format is one of these generic compressed internal formats: GL_COMPRESSED_ALPHA, GL_COMPRESSED_LUMINANCE, GL_COMPRESSED_LUMINANCE_ALPHA, GL_COMPRESSED_INTENSITY, GL_COMPRESSED_RGB, GL_COMPRESSED_RGBA, GL_COMPRESSED_SLUMINANCE, GL_COMPRESSED_SLUMINANCE_ALPHA, GL_COMPRESSED_SRGB, GL_COMPRESSED_SRGBA, or GL_COMPRESSED_SRGB_ALPHA.
GL_INVALID_VALUE is generated if imageSize is not consistent with the format, dimensions, and contents of the specified compressed image data.
GL_INVALID_OPERATION is generated if parameter combinations are not supported by the specific compressed internal format as specified in the specific texture compression extension.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the buffer object’s data store is currently mapped.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the data would be unpacked from the buffer object such that the memory reads required would exceed the data store size.
GL_INVALID_OPERATION is generated if glCompressedTexSubImage1D is executed between the execution of glBegin and the corresponding execution of glEnd.
Undefined results, including abnormal program termination, are generated if data is not encoded in a manner consistent with the extension specification defining the internal compression format.
Associated Gets
glGetCompressedTexImage
glGet with argument GL_TEXTURE_COMPRESSED
glGet with argument GL_PIXEL_UNPACK_BUFFER_BINDING
glGetTexLevelParameter with arguments GL_TEXTURE_INTERNAL_FORMAT and GL_TEXTURE_COMPRESSED_IMAGE_SIZE
glIsEnabled with argument GL_TEXTURE_1D
See Also
glActiveTexture, glColorTable, glCompressedTexImage1D, glCompressedTexImage2D, glCompressedTexImage3D, glCompressedTexSubImage2D, glCompressedTexSubImage3D, glConvolutionFilter1D, glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glMatrixMode, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D, glTexParameter
glCompressedTexSubImage2D
Specify a two-dimensional texture subimage in a compressed format
C Specification
void glCompressedTexSubImage2D(GLenum target,
GLint level,
GLint xoffset,
GLint yoffset,
GLsizei width,
GLsizei height,
GLenum format,
GLsizei imageSize,
const GLvoid * data);
Parameters
Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is enabled. To enable and disable two-dimensional texturing, call glEnable and glDisable with argument GL_TEXTURE_2D. To enable and disable texturing using cube-mapped texture, call glEnable and glDisable with argument GL_TEXTURE_CUBE_MAP.
glCompressedTexSubImage2D redefines a contiguous subregion of an existing two-dimensional texture image. The texels referenced by data replace the portion of the existing texture array with x indices xoffset and xoffset + width – 1, and the 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 width of 0, but such a specification has no effect.
format must be an extension-specified compressed-texture format. The format of the compressed texture image is selected by the GL implementation that compressed it (see glTexImage2D) and should be queried at the time the texture was compressed with glGetTexLevelParameter.
If a nonzero named buffer object is bound to the GL_PIXEL_UNPACK_BUFFER target (see glBindBuffer) while a texture image is specified, data is treated as a byte offset into the buffer object’s data store.
Notes
glCompressedTexSubImage2D is available only if the GL version is 1.3 or greater.
GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL_TEXTURE_CUBE_MAP_NEGATIVE_X, GL_TEXTURE_CUBE_MAP_POSITIVE_Y, GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, GL_TEXTURE_CUBE_MAP_POSITIVE_Z, GL_TEXTURE_CUBE_MAP_NEGATIVE_Z, or GL_PROXY_TEXTURE_CUBE_MAP are available only if the GL version is 1.3 or greater.
Errors
GL_INVALID_ENUM is generated if format is one of these generic compressed internal formats: GL_COMPRESSED_ALPHA, GL_COMPRESSED_LUMINANCE, GL_COMPRESSED_LUMINANCE_ALPHA, GL_COMPRESSED_INTENSITY, GL_COMPRESSED_RGB, GL_COMPRESSED_RGBA, GL_COMPRESSED_SLUMINANCE, GL_COMPRESSED_SLUMINANCE_ALPHA, GL_COMPRESSED_SRGB, GL_COMPRESSED_SRGBA, or GL_COMPRESSED_SRGB_ALPHA.
GL_INVALID_VALUE is generated if imageSize is not consistent with the format, dimensions, and contents of the specified compressed image data.
GL_INVALID_OPERATION is generated if parameter combinations are not supported by the specific compressed internal format as specified in the specific texture compression extension.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the buffer object’s data store is currently mapped.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the data would be unpacked from the buffer object such that the memory reads required would exceed the data store size.
GL_INVALID_OPERATION is generated if glCompressedTexSubImage2D is executed between the execution of glBegin and the corresponding execution of glEnd.
Undefined results, including abnormal program termination, are generated if data is not encoded in a manner consistent with the extension specification defining the internal compression format.
Associated Gets
glGetCompressedTexImage
glGet with argument GL_TEXTURE_COMPRESSED
glGet with argument GL_PIXEL_UNPACK_BUFFER_BINDING
glGetTexLevelParameter with arguments GL_TEXTURE_INTERNAL_FORMAT and GL_TEXTURE_COMPRESSED_IMAGE_SIZE
glIsEnabled with argument GL_TEXTURE_2D or GL_TEXTURE_CUBE_MAP
glActiveTexture, glColorTable, glCompressedTexImage1D, glCompressedTexImage2D, glCompressedTexImage3D, glCompressedTexSubImage1D, glCompressedTexSubImage3D, glConvolutionFilter1D, glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glMatrixMode, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D, glTexParameter
glCompressedTexSubImage3D
Specify a three-dimensional texture subimage in a compressed format
C Specification
void glCompressedTexSubImage3D(GLenum target,
GLint level,
GLint xoffset,
GLint yoffset,
GLint zoffset,
GLsizei width,
GLsizei height,
GLsizei depth,
GLenum format,
GLsizei imageSize,
const GLvoid * data);
Parameters
Description
Texturing maps a portion of a specified texture image onto each graphical primitive for which texturing is enabled. To enable and disable three-dimensional texturing, call glEnable and glDisable with argument GL_TEXTURE_3D.
glCompressedTexSubImage3D redefines a contiguous subregion of an existing three-dimensional texture image. The texels referenced by data replace the portion of the existing texture array with x indices xoffset and xoffset + width – 1, and the y indices yoffset and yoffset + height – 1, and the z indices zoffset and zoffset + depth – 1, inclusive. This region may not include any texels outside the range of the texture array as it was originally specified. It is not an error to specify a subtexture with width of 0, but such a specification has no effect.
format must be an extension-specified compressed-texture format. The format of the compressed texture image is selected by the GL implementation that compressed it (see glTexImage3D) and should be queried at the time the texture was compressed with glGetTexLevelParameter.
If a nonzero named buffer object is bound to the GL_PIXEL_UNPACK_BUFFER target (see glBindBuffer) while a texture image is specified, data is treated as a byte offset into the buffer object’s data store.
Notes
glCompressedTexSubImage3D is available only if the GL version is 1.3 or greater.
Errors
GL_INVALID_ENUM is generated if format is one of these generic compressed internal formats: GL_COMPRESSED_ALPHA, GL_COMPRESSED_LUMINANCE, GL_COMPRESSED_LUMINANCE_ALPHA, GL_COMPRESSED_INTENSITY, GL_COMPRESSED_RGB, GL_COMPRESSED_RGBA, GL_COMPRESSED_SLUMINANCE, GL_COMPRESSED_SLUMINANCE_ALPHA, GL_COMPRESSED_SRGB, GL_COMPRESSED_SRGBA, or GL_COMPRESSED_SRGB_ALPHA.
GL_INVALID_VALUE is generated if imageSize is not consistent with the format, dimensions, and contents of the specified compressed image data.
GL_INVALID_OPERATION is generated if parameter combinations are not supported by the specific compressed internal format as specified in the specific texture compression extension.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the buffer object’s data store is currently mapped.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the data would be unpacked from the buffer object such that the memory reads required would exceed the data store size.
GL_INVALID_OPERATION is generated if glCompressedTexSubImage3D is executed between the execution of glBegin and the corresponding execution of glEnd.
Undefined results, including abnormal program termination, are generated if data is not encoded in a manner consistent with the extension specification defining the internal compression format.
Associated Gets
glGetCompressedTexImage
glGet with argument GL_TEXTURE_COMPRESSED
glGet with argument GL_PIXEL_UNPACK_BUFFER_BINDING
glGetTexLevelParameter with arguments GL_TEXTURE_INTERNAL_FORMAT and GL_TEXTURE_COMPRESSED_IMAGE_SIZE
glIsEnabled with argument GL_TEXTURE_3D
See Also
glActiveTexture, glColorTable, glCompressedTexImage1D, glCompressedTexImage2D, glCompressedTexImage3D, glCompressedTexSubImage1D, glCompressedTexSubImage2D, glConvolutionFilter1D, glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glCopyTexSubImage3D, glDrawPixels, glMatrixMode, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage2D, glTexImage3D, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D, glTexParameter
glConvolutionFilter1D
Define a one-dimensional convolution filter
C Specification
void glConvolutionFilter1D(GLenum target,
GLenum internalformat,
GLsizei width,
GLenum format,
GLenum type,
const GLvoid * data);
Description
glConvolutionFilter1D builds a one-dimensional convolution filter kernel from an array of pixels.
The pixel array specified by width, format, type, and data is extracted from memory and processed just as if glDrawPixels were called, but processing stops after the final expansion to RGBA is completed.
If a nonzero named buffer object is bound to the GL_PIXEL_UNPACK_BUFFER target (see glBindBuffer) while a convolution filter is specified, data is treated as a byte offset into the buffer object’s data store.
The R, G, B, and A components of each pixel are next scaled by the four 1D GL_CONVOLUTION_FILTER_SCALE parameters and biased by the four 1D GL_CONVOLUTION_FILTER_BIAS parameters. (The scale and bias parameters are set by glConvolutionParameter using the GL_CONVOLUTION_1D target and the names GL_CONVOLUTION_FILTER_SCALE and GL_CONVOLUTION_FILTER_BIAS. The parameters themselves are vectors of four values that are applied to red, green, blue, and alpha, in that order.) The R, G, B, and A values are not clamped to [0,1] at any time during this process.
Each pixel is then converted to the internal format specified by internalformat. This conversion simply maps the component values of the pixel (R, G, B, and A) to the values included in the internal format (red, green, blue, alpha, luminance, and intensity). The mapping is as follows:
The red, green, blue, alpha, luminance, and/or intensity components of the resulting pixels are stored in floating-point rather than integer format. They form a one-dimensional filter kernel image indexed with coordinate i such that i starts at 0 and increases from left to right. Kernel location i is derived from the ith pixel, counting from 0.
Note that after a convolution is performed, the resulting color components are also scaled by their corresponding GL_POST_CONVOLUTION_c_SCALE parameters and biased by their corresponding GL_POST_CONVOLUTION_c_BIAS parameters (where c takes on the values RED, GREEN, BLUE, and ALPHA). These parameters are set by glPixelTransfer.
Notes
glConvolutionFilter1D is present only if ARB_imaging is returned when glGetString is called with an argument of GL_EXTENSIONS.
Errors
GL_INVALID_ENUM is generated if target is not GL_CONVOLUTION_1D.
GL_INVALID_ENUM is generated if internalformat is not one of the allowable values.
GL_INVALID_ENUM is generated if format is not one of the allowable values.
GL_INVALID_ENUM is generated if type is not one of the allowable values.
GL_INVALID_VALUE is generated if width is less than zero or greater than the maximum supported value. This value may be queried with glGetConvolutionParameter using target GL_CONVOLUTION_1D and name GL_MAX_CONVOLUTION_WIDTH.
GL_INVALID_OPERATION is generated if format is one of GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5, or GL_UNSIGNED_SHORT_5_6_5_REV and type is not GL_RGB.
GL_INVALID_OPERATION is generated if format is one of GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV, GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV, GL_UNSIGNED_INT_10_10_10_2, or GL_UNSIGNED_INT_2_10_10_10_REV and type is neither GL_RGBA nor GL_BGRA.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the buffer object’s data store is currently mapped.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the data would be unpacked from the buffer object such that the memory reads required would exceed the data store size.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and data is not evenly divisible into the number of bytes needed to store in memory a datum indicated by type.
GL_INVALID_OPERATION is generated if glConvolutionFilter1D is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetConvolutionParameter, glGetConvolutionFilter
glGet with argument GL_PIXEL_UNPACK_BUFFER_BINDING
See Also
glConvolutionFilter2D, glSeparableFilter2D, glConvolutionParameter, glPixelTransfer
glConvolutionFilter2D
Define a two-dimensional convolution filter
C Specification
void glConvolutionFilter2D(GLenum target,
GLenum internalformat,
GLsizei width,
GLsizei height,
GLenum format,
GLenum type,
const GLvoid * data);
Parameters
Description
glConvolutionFilter2D builds a two-dimensional convolution filter kernel from an array of pixels.
The pixel array specified by width, height, format, type, and data is extracted from memory and processed just as if glDrawPixels were called, but processing stops after the final expansion to RGBA is completed.
If a nonzero named buffer object is bound to the GL_PIXEL_UNPACK_BUFFER target (see glBindBuffer) while a convolution filter is specified, data is treated as a byte offset into the buffer object’s data store.
The R, G, B, and A components of each pixel are next scaled by the four 2D GL_CONVOLUTION_FILTER_SCALE parameters and biased by the four 2D GL_CONVOLUTION_FILTER_BIAS parameters. (The scale and bias parameters are set by glConvolutionParameter using the GL_CONVOLUTION_2D target and the names GL_CONVOLUTION_FILTER_SCALE and GL_CONVOLUTION_FILTER_BIAS. The parameters themselves are vectors of four values that are applied to red, green, blue, and alpha, in that order.) The R, G, B, and A values are not clamped to [0,1] at any time during this process.
Each pixel is then converted to the internal format specified by internalformat. This conversion simply maps the component values of the pixel (R, G, B, and A) to the values included in the internal format (red, green, blue, alpha, luminance, and intensity). The mapping is as follows:
The red, green, blue, alpha, luminance, and/or intensity components of the resulting pixels are stored in floating-point rather than integer format. They form a two-dimensional filter kernel image indexed with coordinates i and j such that i starts at zero and increases from left to right, and j starts at zero and increases from bottom to top. Kernel location i,j is derived from the Nth pixel, where N is i + j*width.
Note that after a convolution is performed, the resulting color components are also scaled by their corresponding GL_POST_CONVOLUTION_c_SCALE parameters and biased by their corresponding GL_POST_CONVOLUTION_c_BIAS parameters (where c takes on the values RED, GREEN, BLUE, and ALPHA). These parameters are set by glPixelTransfer.
Notes
glConvolutionFilter2D is present only if ARB_imaging is returned when glGetString is called with an argument of GL_EXTENSIONS.
Errors
GL_INVALID_ENUM is generated if target is not GL_CONVOLUTION_2D.
GL_INVALID_ENUM is generated if internalformat is not one of the allowable values.
GL_INVALID_ENUM is generated if format is not one of the allowable values.
GL_INVALID_ENUM is generated if type is not one of the allowable values.
GL_INVALID_VALUE is generated if width is less than zero or greater than the maximum supported value. This value may be queried with glGetConvolutionParameter using target GL_CONVOLUTION_2D and name GL_MAX_CONVOLUTION_WIDTH.
GL_INVALID_VALUE is generated if height is less than zero or greater than the maximum supported value. This value may be queried with glGetConvolutionParameter using target GL_CONVOLUTION_2D and name GL_MAX_CONVOLUTION_HEIGHT.
GL_INVALID_OPERATION is generated if height is one of GL_UNSIGNED_BYTE_3_3_2, GL_UNSIGNED_BYTE_2_3_3_REV, GL_UNSIGNED_SHORT_5_6_5, or GL_UNSIGNED_SHORT_5_6_5_REV and format is not GL_RGB.
GL_INVALID_OPERATION is generated if height is one of GL_UNSIGNED_SHORT_4_4_4_4, GL_UNSIGNED_SHORT_4_4_4_4_REV, GL_UNSIGNED_SHORT_5_5_5_1, GL_UNSIGNED_SHORT_1_5_5_5_REV, GL_UNSIGNED_INT_8_8_8_8, GL_UNSIGNED_INT_8_8_8_8_REV, GL_UNSIGNED_INT_10_10_10_2, or GL_UNSIGNED_INT_2_10_10_10_REV and format is neither GL_RGBA nor GL_BGRA.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the buffer object’s data store is currently mapped.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and the data would be unpacked from the buffer object such that the memory reads required would exceed the data store size.
GL_INVALID_OPERATION is generated if a nonzero buffer object name is bound to the GL_PIXEL_UNPACK_BUFFER target and data is not evenly divisible into the number of bytes needed to store in memory a datum indicated by type.
GL_INVALID_OPERATION is generated if glConvolutionFilter2D is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetConvolutionParameter, glGetConvolutionFilter
See Also
glConvolutionFilter1D, glSeparableFilter2D, glConvolutionParameter, glPixelTransfer
glConvolutionParameter
Set convolution parameters
C Specification
void glConvolutionParameterf(GLenum target,
GLenum pname,
GLfloatparams);
void glConvolutionParameteri(GLenum target,
GLenum pname,
GLint params);
Parameters
C Specification
void glConvolutionParameterfv(GLenum target,
GLenum pname,
const GLfloat * params);
void glConvolutionParameteriv(GLenum target,
GLenum pname,
const GLint * params);
Parameters
glConvolutionParameter sets the value of a convolution parameter.
target selects the convolution filter to be affected: GL_CONVOLUTION_1D, GL_CONVOLUTION_2D, or GL_SEPARABLE_2D for the 1D, 2D, or separable 2D filter, respectively.
pname selects the parameter to be changed. GL_CONVOLUTION_FILTER_SCALE and GL_CONVOLUTION_FILTER_BIAS affect the definition of the convolution filter kernel; see glConvolutionFilter1D, glConvolutionFilter2D, and glSeparableFilter2D for details. In these cases, paramsv is an array of four values to be applied to red, green, blue, and alpha values, respectively. The initial value for GL_CONVOLUTION_FILTER_SCALE is (1, 1, 1, 1), and the initial value for GL_CONVOLUTION_FILTER_BIAS is (0, 0, 0, 0).
A pname value of GL_CONVOLUTION_BORDER_MODE controls the convolution border mode. The accepted modes are:
GL_REDUCE
The image resulting from convolution is smaller than the source image. If the filter width is Wf and height is Hf, and the source image width is Ws and height is Hs, then the convolved image width will be Ws – Wf + 1 and height will be Hs – Hf + 1. (If this reduction would generate an image with zero or negative width and/or height, the output is simply null, with no error generated.) The coordinates of the image resulting from convolution are zero through Ws – Wf in width and zero through Hs – Hf in height.
GL_CONSTANT_BORDER
The image resulting from convolution is the same size as the source image, and processed as if the source image were surrounded by pixels with their color specified by the GL_CONVOLUTION_BORDER_COLOR.
GL_REPLICATE_BORDER
The image resulting from convolution is the same size as the source image, and processed as if the outermost pixel on the border of the source image were replicated.
Notes
glConvolutionParameter is present only if ARB_imaging is returned when glGetString is called with an argument of GL_EXTENSIONS.
In cases where errors can result from the specification of invalid image dimensions, it is the dimensions after convolution that are tested, not the dimensions of the source image. For example, glTexImage1D requires power-of-two image size. When GL_REDUCE border mode is in effect, the source image must be larger than the final power-of-two size by one less than the size of the 1D filter kernel.
Errors
GL_INVALID_ENUM is generated if target is not one of the allowable values.
GL_INVALID_ENUM is generated if pname is not one of the allowable values.
GL_INVALID_ENUM is generated if pname is GL_CONVOLUTION_BORDER_MODE and params is not one of GL_REDUCE, GL_CONSTANT_BORDER, or GL_REPLICATE_BORDER.
GL_INVALID_OPERATION is generated if glConvolutionParameter is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetConvolutionParameter
See Also
glConvolutionFilter1D, glConvolutionFilter2D, glSeparableFilter2D, glGetConvolutionParameter
glCopyColorSubTable
Respecify a portion of a color table
C Specification
void glCopyColorSubTable(GLenum target,
GLsizei start,
GLint x,
GLint y,
GLsizeiwidth);
Parameters
Description
glCopyColorSubTable is used to respecify a contiguous portion of a color table previously defined using glColorTable. The pixels copied from the framebuffer replace the portion of the existing table from indices start to start + x – 1, inclusive. This region may not include any entries outside the range of the color table, as was originally specified. It is not an error to specify a subtexture with width of 0, but such a specification has no effect.
Notes
glCopyColorSubTable is present only if ARB_imaging is returned when glGetString is called with an argument of GL_EXTENSIONS.
Errors
GL_INVALID_VALUE is generated if target is not a previously defined color table.
GL_INVALID_VALUE is generated if target is not one of the allowable values.
GL_INVALID_VALUE is generated if start + x > width.
GL_INVALID_OPERATION is generated if glCopyColorSubTable is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetColorTable, glGetColorTableParameter
See Also
glColorSubTable, glColorTableParameter, glCopyColorTable, glCopyColorSubTable, glGetColorTable
glCopyColorTable
Copy pixels into a color table
C Specification
void glCopyColorTable(GLenum target,
GLenum internalformat,
GLint x,
GLint y,
GLsizeiwidth);
Parameters
Description
glCopyColorTable loads a color table with pixels from the current GL_READ_BUFFER (rather than from main memory, as is the case for glColorTable).
The screen-aligned pixel rectangle with lower-left corner at (x, y) having width width and height 1 is loaded into the color table. If any pixels within this region are outside the window that is associated with the GL context, the values obtained for those pixels are undefined.
The pixels in the rectangle are processed just as if glReadPixels were called, with internalformat set to RGBA, but processing stops after the final conversion to RGBA.
The four scale parameters and the four bias parameters that are defined for the table are then used to scale and bias the R, G, B, and A components of each pixel. The scale and bias parameters are set by calling glColorTableParameter.
Next, the R, G, B, and A values are clamped to the range [0,1]. Each pixel is then converted to the internal format specified by internalformat. This conversion simply maps the component values of the pixel (R, G, B, and A) to the values included in the internal format (red, green, blue, alpha, luminance, and intensity). The mapping is as follows:
Finally, the red, green, blue, alpha, luminance, and/or intensity components of the resulting pixels are stored in the color table. They form a one-dimensional table with indices in the range [0,width – 1].
Notes
glCopyColorTable is available only if ARB_imaging is returned from calling glGetString with an argument of GL_EXTENSIONS.
Errors
GL_INVALID_ENUM is generated when target is not one of the allowable values.
GL_INVALID_VALUE is generated if width is less than zero.
GL_INVALID_VALUE is generated if internalformat is not one of the allowable values.
GL_TABLE_TOO_LARGE is generated if the requested color table is too large to be supported by the implementation.
GL_INVALID_OPERATION is generated if glCopyColorTable is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetColorTable, glGetColorTableParameter
See Also
glColorTable, glColorTableParameter, glReadPixels
glCopyConvolutionFilter1D
Copy pixels into a one-dimensional convolution filter
C Specification
void glCopyConvolutionFilter1D(GLenum target,
GLenum internalformat,
GLint x,
GLint y,
GLsizeiwidth);
Parameters
Description
glCopyConvolutionFilter1D defines a one-dimensional convolution filter kernel with pixels from the current GL_READ_BUFFER (rather than from main memory, as is the case for glConvolutionFilter1D).
The screen-aligned pixel rectangle with lower-left corner at (x, y), width width and height 1 is used to define the convolution filter. If any pixels within this region are outside the window that is associated with the GL context, the values obtained for those pixels are undefined.
The pixels in the rectangle are processed exactly as if glReadPixels had been called with format set to RGBA, but the process stops just before final conversion. The R, G, B, and A components of each pixel are next scaled by the four 1D GL_CONVOLUTION_FILTER_SCALE parameters and biased by the four 1D GL_CONVOLUTION_FILTER_BIAS parameters. (The scale and bias parameters are set by glConvolutionParameter using the GL_CONVOLUTION_1D target and the names GL_CONVOLUTION_FILTER_SCALE and GL_CONVOLUTION_FILTER_BIAS. The parameters themselves are vectors of four values that are applied to red, green, blue, and alpha, in that order.) The R, G, B, and A values are not clamped to [0,1] at any time during this process.
Each pixel is then converted to the internal format specified by internalformat. This conversion simply maps the component values of the pixel (R, G, B, and A) to the values included in the internal format (red, green, blue, alpha, luminance, and intensity). The mapping is as follows:
The red, green, blue, alpha, luminance, and/or intensity components of the resulting pixels are stored in floating-point rather than integer format.
Pixel ordering is such that lower x screen coordinates correspond to lower i filter image coordinates.
Note that after a convolution is performed, the resulting color components are also scaled by their corresponding GL_POST_CONVOLUTION_c_SCALE parameters and biased by their corresponding GL_POST_CONVOLUTION_c_BIAS parameters (where c takes on the values RED, GREEN, BLUE, and ALPHA). These parameters are set by glPixelTransfer.
Notes
glCopyConvolutionFilter1D is present only if ARB_imaging is returned when glGetString is called with an argument of GL_EXTENSIONS.
Errors
GL_INVALID_ENUM is generated if target is not GL_CONVOLUTION_1D.
GL_INVALID_ENUM is generated if internalformat is not one of the allowable values.
GL_INVALID_VALUE is generated if width is less than zero or greater than the maximum supported value. This value may be queried with glGetConvolutionParameter using target GL_CONVOLUTION_1D and name GL_MAX_CONVOLUTION_WIDTH.
GL_INVALID_OPERATION is generated if glCopyConvolutionFilter1D is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetConvolutionParameter, glGetConvolutionFilter
See Also
glConvolutionFilter1D, glConvolutionParameter, glPixelTransfer
glCopyConvolutionFilter2D
Copy pixels into a two-dimensional convolution filter
C Specification
void glCopyConvolutionFilter2D(GLenum target,
GLenum internalformat,
GLint x,
GLint y,
GLsizeiwidth,
GLsizeiheight);
Description
glCopyConvolutionFilter2D defines a two-dimensional convolution filter kernel with pixels from the current GL_READ_BUFFER (rather than from main memory, as is the case for glConvolutionFilter2D).
The screen-aligned pixel rectangle with lower-left corner at (x, y), width width and height height is used to define the convolution filter. If any pixels within this region are outside the window that is associated with the GL context, the values obtained for those pixels are undefined.
The pixels in the rectangle are processed exactly as if glReadPixels had been called with format set to RGBA, but the process stops just before final conversion. The R, G, B, and A components of each pixel are next scaled by the four 2D GL_CONVOLUTION_FILTER_SCALE parameters and biased by the four 2D GL_CONVOLUTION_FILTER_BIAS parameters. (The scale and bias parameters are set by glConvolutionParameter using the GL_CONVOLUTION_2D target and the names GL_CONVOLUTION_FILTER_SCALE and GL_CONVOLUTION_FILTER_BIAS. The parameters themselves are vectors of four values that are applied to red, green, blue, and alpha, in that order.) The R, G, B, and A values are not clamped to [0,1] at any time during this process.
Each pixel is then converted to the internal format specified by internalformat. This conversion simply maps the component values of the pixel (R, G, B, and A) to the values included in the internal format (red, green, blue, alpha, luminance, and intensity). The mapping is as follows:
The red, green, blue, alpha, luminance, and/or intensity components of the resulting pixels are stored in floating-point rather than integer format.
Pixel ordering is such that lower x screen coordinates correspond to lower i filter image coordinates, and lower y screen coordinates correspond to lower j filter image coordinates.
Note that after a convolution is performed, the resulting color components are also scaled by their corresponding GL_POST_CONVOLUTION_c_SCALE parameters and biased by their corresponding GL_POST_CONVOLUTION_c_BIAS parameters (where c takes on the values RED, GREEN, BLUE, and ALPHA). These parameters are set by glPixelTransfer.
glCopyConvolutionFilter2D is present only if ARB_imaging is returned when glGetString is called with an argument of GL_EXTENSIONS.
Errors
GL_INVALID_ENUM is generated if target is not GL_CONVOLUTION_2D.
GL_INVALID_ENUM is generated if internalformat is not one of the allowable values.
GL_INVALID_VALUE is generated if width is less than zero or greater than the maximum supported value. This value may be queried with glGetConvolutionParameter using target GL_CONVOLUTION_2D and name GL_MAX_CONVOLUTION_WIDTH.
GL_INVALID_VALUE is generated if height is less than zero or greater than the maximum supported value. This value may be queried with glGetConvolutionParameter using target GL_CONVOLUTION_2D and name GL_MAX_CONVOLUTION_HEIGHT.
GL_INVALID_OPERATION is generated if glCopyConvolutionFilter2D is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetConvolutionParameter, glGetConvolutionFilter
See Also
glConvolutionFilter2D, glConvolutionParameter, glPixelTransfer
glCopyPixels
Copy pixels in the frame buffer
C Specification
void glCopyPixels(GLint x,
GLint y,
GLsizei width,
GLsizei height,
GLenum type);
Parameters
Description
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 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:
GL_COLOR
Indices or RGBA colors are read from the buffer currently specified as the read source buffer (see glReadBuffer). If the GL is in color index mode, each index that is read from this buffer is converted to a fixed-point format with an unspecified number of bits to the right of the binary point. Each 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, zero bits fill otherwise unspecified bit locations in the result. If GL_MAP_COLOR is true, the index is replaced with the value that it references in 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.
If the GL is in RGBA mode, the red, green, blue, and alpha components of each pixel that is read are converted to an internal floating-point format with unspecified precision. The conversion maps the largest representable component value to 1.0, and component value 0 to 0.0. The resulting floating-point color values are then multiplied by GL_c_SCALE and added to GL_c_BIAS, where c is RED, GREEN, BLUE, and ALPHA for the respective color components. The results are clamped to the range [0,1]. 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.
If the ARB_imaging extension is supported, the color values may be additionally processed by color-table lookups, color-matrix transformations, and convolution filters.
The GL then converts the resulting indices or RGBA colors to fragments by attaching the current raster position z coordinate and texture coordinates to each pixel, then assigning window coordinates (xr + i,yr + j), where (xr,yr) is the current raster position, and the pixel was the ith pixel in the jth row. 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.
GL_DEPTH
Depth values are read from the depth buffer and converted directly to an internal floating-point format with unspecified precision. The resulting floating-point depth value is then multiplied by GL_DEPTH_SCALE and added to GL_DEPTH_BIAS. The result is clamped to the range [0,1].
The GL then converts the resulting depth components to fragments by attaching the current raster position color or color index and texture coordinates to each pixel, then assigning window coordinates (xr + i,yr + j), where (xr,yr) is the current raster position, and the pixel was the ith pixel in the jth row. 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.
GL_STENCIL
Stencil indices are read from the stencil buffer and converted to an internal fixed-point format with an unspecified number of bits to the right of the binary point. 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, zero bits fill otherwise unspecified bit locations in the result. If GL_MAP_STENCIL is true, the index is replaced with the value that it references in lookup table GL_PIXEL_MAP_S_TO_S. 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 the stencil buffer. The resulting stencil indices are then written to the stencil buffer such that the index read from the ith location of the jth row is written to location (xr + i,yr + j), where (xr,yr) is the current raster position. Only the pixel ownership test, the scissor test, and the stencil writemask affect these write operations.
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.
Examples
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);
Notes
Modes specified by glPixelStore have no effect on the operation of glCopyPixels.
Errors
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 executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGet with argument GL_CURRENT_RASTER_POSITION
glGet with argument GL_CURRENT_RASTER_POSITION_VALID
See Also
glColorTable, glConvolutionFilter1D, glConvolutionFilter2D, glDepthFunc, glDrawBuffer, glDrawPixels, glMatrixMode, glPixelMap, glPixelTransfer, glPixelZoom, glRasterPos, glReadBuffer, glReadPixels, glSeparableFilter2D, glStencilFunc, glWindowPos
glCopyTexImage1D
Copy pixels into a 1D texture image
C Specification
void glCopyTexImage1D(GLenum target,
GLint level,
GLenum internalformat,
GLint x,
GLint y,
GLsizeiwidth,
GLint border);
Parameters
glCopyTexImage1D 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.
glCopyTexImage1D defines a one-dimensional texture image with pixels from the current GL_READ_BUFFER.
When internalformat is one of the sRGB types, the GL does not automatically convert the source pixels to the sRGB color space. In this case, the glPixelMap function can be used to accomplish the conversion.
Notes
glCopyTexImage1D is available only if the GL version is 1.1 or greater.
Texturing has no effect in color index mode.
1, 2, 3, and 4 are not accepted values for internalformat.
An image with 0 width indicates a NULL texture.
When the ARB_imaging extension is supported, the RGBA components copied from the framebuffer may be processed by the imaging pipeline. See glTexImage1D for specific details.
GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24, and GL_DEPTH_COMPONENT32 are available only if the GL version is 1.4 or greater.
Non-power-of-two textures are supported if the GL version is 2.0 or greater, or if the implementation exports the GL_ARB_texture_non_power_of_two extension.
The GL_SRGB, GL_SRGB8, GL_SRGB_ALPHA, GL_SRGB8_ALPHA8, GL_SLUMINANCE, GL_SLUMINANCE8, GL_SLUMINANCE_ALPHA, and GL_SLUMINANCE8_ALPHA8 internal formats are only available if the GL version is 2.1 or greater. See glTexImage1D for specific details about sRGB conversion.
GL_INVALID_ENUM is generated if target is not one of the allowable values.
GL_INVALID_VALUE is generated if level is less than 0.
GL_INVALID_VALUE may be generated if level is greater than log2 max, where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE is generated if internalformat is not an allowable value.
GL_INVALID_VALUE is generated if width is less than 0 or greater than 2 + GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE is generated if non-power-of-two textures are not supported and the width cannot be represented as 2n + 2 (border) for some integer value of n.
GL_INVALID_VALUE is generated if border is not 0 or 1.
GL_INVALID_OPERATION is generated if glCopyTexImage1D is executed between the execution of glBegin and the corresponding execution of glEnd.
GL_INVALID_OPERATION is generated if internalformat is GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24, or GL_DEPTH_COMPONENT32 and there is no depth buffer.
Associated Gets
glGetTexImage
glIsEnabled with argument GL_TEXTURE_1D
See Also
glCopyPixels, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage1D, glTexImage2D, glTexSubImage1D, glTexSubImage2D, glTexParameter
glCopyTexImage2D
Copy pixels into a 2D texture image
C Specification
void glCopyTexImage2D(GLenum target,
GLint level,
GLenum internalformat,
GLint x,
GLint y,
GLsizeiwidth,
GLsizeiheight,
GLint border);
Parameters
glCopyTexImage2D defines a two-dimensional texture image, or cube-map 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 a height of 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,1] 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.
When internalformat is one of the sRGB types, the GL does not automatically convert the source pixels to the sRGB color space. In this case, the glPixelMap function can be used to accomplish the conversion.
Notes
glCopyTexImage2D is available only if the GL version is 1.1 or greater.
Texturing has no effect in color index mode.
1, 2, 3, and 4 are not accepted values for internalformat.
An image with height or width of 0 indicates a NULL texture.
When the ARB_imaging extension is supported, the RGBA components read from the framebuffer may be processed by the imaging pipeline. See glTexImage1D for specific details.
GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL_TEXTURE_CUBE_MAP_NEGATIVE_X, GL_TEXTURE_CUBE_MAP_POSITIVE_Y, GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, GL_TEXTURE_CUBE_MAP_POSITIVE_Z, GL_TEXTURE_CUBE_MAP_NEGATIVE_Z, or GL_PROXY_TEXTURE_CUBE_MAP are available only if the GL version is 1.3 or greater.
GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24, and GL_DEPTH_COMPONENT32 are available only if the GL version is 1.4 or greater.
The GL_SRGB, GL_SRGB8, GL_SRGB_ALPHA, GL_SRGB8_ALPHA8, GL_SLUMINANCE, GL_SLUMINANCE8, GL_SLUMINANCE_ALPHA, and GL_SLUMINANCE8_ALPHA8 internal formats are only available if the GL version is 2.1 or greater. See glTexImage2D for specific details about sRGB conversion.
GL_INVALID_ENUM is generated if target is not GL_TEXTURE_2D.
GL_INVALID_VALUE is generated if level is less than 0.
GL_INVALID_VALUE may be generated if level is greater than log2 max, where max is the returned value of GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE is generated if width is less than 0 or greater than 2 + GL_MAX_TEXTURE_SIZE.
GL_INVALID_VALUE is generated if non-power-of-two textures are not supported and the width, height, or depth cannot be represented as 2k + 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 an accepted format.
GL_INVALID_OPERATION is generated if glCopyTexImage2D is executed between the execution of glBegin and the corresponding execution of glEnd.
GL_INVALID_OPERATION is generated if internalformat is GL_DEPTH_COMPONENT, GL_DEPTH_COMPONENT16, GL_DEPTH_COMPONENT24, or GL_DEPTH_COMPONENT32 and there is no depth buffer.
Associated Gets
glGetTexImage
glIsEnabled with argument GL_TEXTURE_2D or GL_TEXTURE_CUBE_MAP
See Also
glCopyPixels, glCopyTexImage1D, glCopyTexSubImage1D, glCopyTexSubImage2D, glPixelStore, glPixelTransfer, glTexEnv, glTexGen, glTexImage1D, glTexImage2D, glTexSubImage1D, glTexSubImage2D, glTexParameter
glCopyTexSubImage1D
Copy a one-dimensional texture subimage
C Specification
void glCopyTexSubImage1D(GLenum target,
GLint level,
GLint xoffset,
GLint x,
GLint y,
GLsizeiwidth);
Parameters
Description
glCopyTexSubImage1D 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.
Notes
glCopyTexSubImage1D is available only if the GL version is 1.1 or greater.
Texturing has no effect in color index mode.
glPixelStore and glPixelTransfer modes affect texture images in exactly the way they affect glDrawPixels.
When the ARB_imaging extension is supported, the RGBA components copied from the framebuffer may be processed by the imaging pipeline. See glTexImage1D for specific details.
Errors
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 or glCopyTexImage1D operation.
GL_INVALID_VALUE is generated if level is less than 0.
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 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.
Associated Gets
glGetTexImage
glIsEnabled with argument GL_TEXTURE_1D
See Also
glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage2D, glCopyTexSubImage3D, glPixelStore, glPixelTransfer, glReadBuffer, glTexEnv, glTexGen, glTexImage1D, glTexImage2D, glTexImage3D, glTexParameter, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D
glCopyTexSubImage2D
Copy a two-dimensional texture subimage
C Specification
void glCopyTexSubImage2D(GLenum target,
GLint level,
GLint xoffset,
GLint yoffset,
GLint x,
GLint y,
GLsizeiwidth,
GLsizeiheight);
Description
glCopyTexSubImage2D replaces a rectangular portion of a two-dimensional texture image or cube-map 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.
Notes
glCopyTexSubImage2D is available only if the GL version is 1.1 or greater.
GL_TEXTURE_CUBE_MAP_POSITIVE_X, GL_TEXTURE_CUBE_MAP_NEGATIVE_X, GL_TEXTURE_CUBE_MAP_POSITIVE_Y, GL_TEXTURE_CUBE_MAP_NEGATIVE_Y, GL_TEXTURE_CUBE_MAP_POSITIVE_Z, GL_TEXTURE_CUBE_MAP_NEGATIVE_Z, or GL_PROXY_TEXTURE_CUBE_MAP are available only if the GL version is 1.3 or greater.
Texturing has no effect in color index mode.
glPixelStore and glPixelTransfer modes affect texture images in exactly the way they affect glDrawPixels.
When the ARB_imaging extension is supported, the RGBA components read from the framebuffer may be processed by the imaging pipeline. See glTexImage1D for specific details.
Errors
GL_INVALID_ENUM is generated if /target is not GL_TEXTURE_2D.
GL_INVALID_OPERATION is generated if the texture array has not been defined by a previous glTexImage2D or glCopyTexImage2D operation.
GL_INVALID_VALUE is generated if level is less than 0.
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 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.
Associated Gets
glGetTexImage
glIsEnabled with argument GL_TEXTURE_2D
See Also
glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage3D, glPixelStore, glPixelTransfer, glReadBuffer, glTexEnv, glTexGen, glTexImage1D, glTexImage2D, glTexImage3D, glTexParameter, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D
glCopyTexSubImage3D
Copy a three-dimensional texture subimage
C Specification
void glCopyTexSubImage3D(GLenum target,
GLint level,
GLint xoffset,
GLint yoffset,
GLint zoffset,
GLint x,
GLint y,
GLsizeiwidth,
GLsizeiheight);
Parameters
Description
glCopyTexSubImage3D replaces a rectangular portion of a three-dimensional texture image with pixels from the current GL_READ_BUFFER (rather than from main memory, as is the case for glTexSubImage3D).
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 z index zoffset and 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, depth, or border parameters of the specified texture array or to texel values outside the specified subregion.
Notes
glCopyTexSubImage3D is available only if the GL version is 1.2 or greater.
Texturing has no effect in color index mode.
glPixelStore and glPixelTransfer modes affect texture images in exactly the way they affect glDrawPixels.
When the ARB_imaging extension is supported, the RGBA components copied from the framebuffer may be processed by the imaging pipeline, as if they were a two-dimensional texture. See glTexImage2D for specific details.
Errors
GL_INVALID_ENUM is generated if /target is not GL_TEXTURE_3D.
GL_INVALID_OPERATION is generated if the texture array has not been defined by a previous glTexImage3D operation.
GL_INVALID_VALUE is generated if level is less than 0.
GL_INVALID_VALUE may be generated if level> log2 (max), where max is the returned value of GL_MAX_3D_TEXTURE_SIZE.
GL_INVALID_VALUE is generated if xoffset<– b, (xoffset + width) > (w – b), yoffset<– b, (yoffset + height) > (h – b), zoffset<–b, or zoffset> (d – b), where w is the GL_TEXTURE_WIDTH, h is the GL_TEXTURE_HEIGHT, d is the GL_TEXTURE_DEPTH, and b is the GL_TEXTURE_BORDER of the texture image being modified. Note that w, h, and d include twice the border width.
GL_INVALID_OPERATION is generated if glCopyTexSubImage3D is executed between the execution of glBegin and the corresponding execution of glEnd.
Associated Gets
glGetTexImage
glIsEnabled with argument GL_TEXTURE_3D
See Also
glCopyPixels, glCopyTexImage1D, glCopyTexImage2D, glCopyTexSubImage1D, glCopyTexSubImage2D, glPixelStore, glPixelTransfer, glReadBuffer, glTexEnv, glTexGen, glTexImage1D, glTexImage2D, glTexImage3D, glTexParameter, glTexSubImage1D, glTexSubImage2D, glTexSubImage3D