glActiveTexture

Name

glActiveTexture — select server-side active texture unit

C Specification

void glActiveTexture( GLenum texture);

Parameters

+ texture +: + Specifies which texture unit to make active. The + number of texture units is implementation dependent, but + must be at least two. + texture must be one of + GL_TEXTUREi, + where + + 0 + <= + i + < + GL_MAX_TEXTURE_UNITS + , + which is an implementation-dependent value. The intial value is + GL_TEXTURE0. +

Description

+ glActiveTexture + selects which texture unit subsequent texture state calls will + affect. The number of texture units an implementation supports + is implementation dependent, it must be at least 2.

Errors

+ GL_INVALID_ENUM is generated if + texture is not one of + GL_TEXTUREi, + where + + 0 + <= + i + < + GL_MAX_TEXTURE_UNITS + . +

Notes

It is always the case that + + GL_TEXTUREi = + GL_TEXTURE0+i + .

A texture unit consists of the texture enable state, + texture matrix stack, texture environment and currently bound + texture. Modifying any of these states has an effect only on + the active texture unit. +

Vertex arrays are client-side GL resources, which are + selected by the + glClientActiveTexture + routine.

Associated Gets

+ glGet + with argument GL_ACTIVE_TEXTURE or + GL_MAX_TEXTURE_UNITS +

Copyright

Name

glAlphaFunc — specify the alpha test function

C Specification

`void glAlphaFunc(`	GLenum `func`,
	GLclampf `ref)`;

`void glAlphaFuncx(`	GLenum `func`,
	GLclampx `ref)`;

Parameters

+ func +: Specifies the alpha comparison function. Symbolic + constants + GL_NEVER, + GL_LESS, + GL_EQUAL, + GL_LEQUAL, + GL_GREATER, + GL_NOTEQUAL, + GL_GEQUAL, and + GL_ALWAYS + are accepted. The initial value is + GL_ALWAYS. +
+ ref +: Specifies the reference value that incoming alpha + values are compared to. This value is clamped to the + range [0, 1], where 0 represents the lowest possible + alpha value and 1 the highest possible value. The initial + reference value is 0. +

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. + To enable and disable alpha testing, call + glEnable and + glDisable + with argument GL_ALPHA_TEST. + Alpha testing is initially disabled. When disabled, it is as if the comparison + always passes. + +

+ 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, and + polygons. + glAlphaFunc + does not affect + glClear. +

Errors

+ GL_INVALID_ENUM is generated if + func is not an accepted value. +

Copyright

Name

glBindBuffer — bind a named buffer to a target

C Specification

`void glBindBuffer(`	GLenum `target`,
	GLuint `buffer)`;

Parameters

+ target +: + Specifies the target to which the buffer is bound. + The symbolic constant must be + GL_ARRAY_BUFFER + or GL_ELEMENT_ARRAY_BUFFER. +
+ buffer +: Specifies the name of a buffer object.

Description

+ glBindBuffer + lets you create or use a named buffer object. + Calling glBindBuffer + with target + set to GL_ARRAY_BUFFER + or GL_ELEMENT_ARRAY_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. +

+ glBindBuffer lets you create or use a named buffer object. Calling glBindBuffer with + target set to + GL_ARRAY_BUFFER or GL_ELEMENT_ARRAY_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 buffer-object space (see eglCreateContext) of the current + GL rendering context. +

+ 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 + GL_READ_WRITE access and GL_STATIC_DRAW usage. +

+ While a non-zero 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 + GL_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 non-zero 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 non-zero buffer object is bound to the GL_ELEMENT_ARRAY_BUFFER target, + the indices parameter of glDrawElements + 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. +

+ 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. +

Errors

GL_INVALID_ENUM is generated if + target is not one of the allowable values.

Associated Gets

+ glGet + with argument GL_ARRAY_BUFFER_BINDING or + GL_ELEMENT_ARRAY_BUFFER_BINDING +

Copyright

Name

glBindTexture — bind a named texture to a texturing target

C Specification

`void glBindTexture(`	GLenum `target`,
	GLuint `texture)`;

Parameters

+ target +: Specifies the target to which the texture is bound. + Must be GL_TEXTURE_2D.
+ texture +: Specifies the name of a texture.

Description

glBindTexture + lets you create or use a named texture. Calling + glBindTexture + with target + set to GL_TEXTURE_2D, 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 0 is + reserved to represent the default texture for each texture + target. Texture names and the corresponding texture contents + are local to the shared texture-object space (see + eglCreateContext) + of the current GL rendering context.

You may use + glGenTextures + to generate a set of new texture names.

While a texture is bound, GL operations on the target to + which it is bound affect the bound texture. If texture mapping + of the dimensionality of the target to which a texture is bound + is active, the bound texture is used. In effect, the texture + targets become aliases for the textures currently bound to + them, and the texture name 0 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 the + target of the matching dimensionality as often as needed. It is + usually much faster to use glBindTexture + to bind an existing named texture to one of the texture targets + than it is to reload the texture image using + glTexImage2D.

Errors

GL_INVALID_ENUM is generated if + target is not one of the allowable values.

Associated Gets

+ glGet + with argument GL_TEXTURE_BINDING_2D +

Copyright

Name

glBlendFunc — specify pixel arithmetic

C Specification

`void glBlendFunc(`	GLenum `sfactor`,
	GLenum `dfactor)`;

Parameters

+ sfactor +: + Specifies how the red, green, blue, and alpha + source blending factors are computed. The following + symbolic constants are accepted: + GL_ZERO, + GL_ONE, + GL_DST_COLOR, + GL_ONE_MINUS_DST_COLOR, + GL_SRC_ALPHA, + GL_ONE_MINUS_SRC_ALPHA, + GL_DST_ALPHA, + GL_ONE_MINUS_DST_ALPHA, and + GL_SRC_ALPHA_SATURATE. + The initial value is GL_ONE. +
+ dfactor +: Specifies how the red, green, blue, and alpha + destination blending factors are computed. Eight symbolic + constants are accepted: + GL_ZERO, + GL_ONE, + GL_SRC_COLOR, + GL_ONE_MINUS_SRC_COLOR, + GL_SRC_ALPHA, + GL_ONE_MINUS_SRC_ALPHA, + GL_DST_ALPHA, and + GL_ONE_MINUS_DST_ALPHA. The initial value is + GL_ZERO.

Description

Pixels can be drawn using a function that blends the + incoming (source) values with the values that are already in + the color buffer (the destination values). Use + glEnable and + glDisable + with argument GL_BLEND + to enable and disable blending. + Blending is initially disabled. +

+ glBlendFunc + defines the operation of blending when it is enabled. + sfactor + specifies which of eleven methods is used to scale the source color components. + dfactor + specifies which of ten methods is used to scale the destination color components. + The eleven 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 + ). + 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].

Parameter	+ ( + fR, + fG, + fB, + fA + ) +
+ `GL_ZERO` +	+ ( + 0, + 0, + 0, + 0 + ) +
+ `GL_ONE` +	+ ( + 1, + 1, + 1, + 1 + ) +
+ `GL_SRC_COLOR` +	+ ( + Rs/kR, + Gs/kG, + Bs/kB, + As/kA + ) +
+ `GL_ONE_MINUS_SRC_COLOR` +	+ + ( + 1, + 1, + 1, + 1 + ) + - + ( + Rs/kR, + Gs/kG, + Bs/kB, + As/kA + ) +
+ `GL_DST_COLOR` +	+ ( + Rd/kR, + Gd/kG, + Bd/kB, + Ad/kA + ) +
+ `GL_ONE_MINUS_DST_COLOR` +	+ + ( + 1, + 1, + 1, + 1 + ) + - + ( + Rd/kR, + Gd/kG, + Bd/kB, + Ad/kA + ) +
+ `GL_SRC_ALPHA` +	+ ( + As/kA, + As/kA, + As/kA, + As/kA + ) +
+ `GL_ONE_MINUS_SRC_ALPHA` +	+ + ( + 1, + 1, + 1, + 1 + ) + - + ( + As/kA, + As/kA, + As/kA, + As/kA + ) +
+ `GL_DST_ALPHA` +	+ ( + Ad/kA, + Ad/kA, + Ad/kA, + Ad/kA + ) +
+ `GL_ONE_MINUS_DST_ALPHA` +	+ + ( + 1, + 1, + 1, + 1 + ) + - + ( + Ad/kA, + Ad/kA, + Ad/kA, + Ad/kA + ) +
+ `GL_SRC_ALPHA_SATURATE` +	+ ( + i, + i, + i, + 1 + ) +

In the table,

+ i=min( + As, + kA-Ad + ) + / + kA +

To determine the blended values of a pixel, 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 + + = + + Rs + + + Gd + + = + + Gs + + + Bd + + = + + Bs + + + Ad + + = + + As + +

+ glBlendFunc operates on all pixel write operations, + including the scan conversion of points, lines, and polygons. + glBlendFunc does not affect + glClear. +

Examples

Transparency is best implemented using + glBlendFunc(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 color buffer.

glBlendFunc(GL_SRC_ALPHA, + GL_ONE_MINUS_SRC_ALPHA) + is also useful for rendering antialiased points and lines. +

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.

Errors

GL_INVALID_ENUM is generated if either + sfactor or dfactor + is not an accepted value.

Copyright

Name

glBufferData — creates and initializes a buffer object's data store.

C Specification

`void glBufferData(`	GLenum `target`,
	GLsizeiptr `size`,
	const GLvoid * `data`,
	GLenum `usage)`;

Parameters

+ target +: + Specifies the target buffer object. The symbolic constant must be + GL_ARRAY_BUFFER + or GL_ELEMENT_ARRAY_BUFFER. +
+ size +: Specifies the size in bytes of the buffer object's new data store.
+ data +: Specifies a pointer to data that will be copied into the data store for + initialization, or NULL if no data is to be copied.
+ usage +: + Specifies the expected usage pattern of the data store. The symbolic constant + must be + GL_STATIC_DRAW or + GL_DYNAMIC_DRAW. +

Description

+ glBufferData creates a new data store for the buffer object currently bound to + target. Any pre-existing 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. +

+ 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 may be one of these: +

GL_STATIC_DRAW: + The data store contents will be modified once + and used many times as the source for GL drawing commands. +
GL_DYNAMIC_DRAW: + The data store contents will be modified repeatedly + and used many times as the source for GL drawing commands. +

+

Notes

+ 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 N bytes be a + multiple of N. +

Errors

+ GL_INVALID_ENUM is generated if target is not + GL_ARRAY_BUFFER or GL_ELEMENT_ARRAY_BUFFER. +

+ GL_INVALID_ENUM is generated if usage is not + GL_STATIC_DRAW or + GL_DYNAMIC_DRAW. +

+ 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. +

Associated Gets

+ glGetBufferParameteriv with argument GL_BUFFER_SIZE or GL_BUFFER_USAGE +

Copyright

Name

glBufferSubData — updates a subset of a buffer object's data store.

C Specification

`void glBufferSubData(`	GLenum `target`,
	GLintptr `offset`,
	GLsizeiptr `size`,
	const GLvoid * `data)`;

Parameters

+ target +: + Specifies the target buffer object. The symbolic constant must be + GL_ARRAY_BUFFER + or GL_ELEMENT_ARRAY_BUFFER. +
+ offset +: Specifies the offset into the buffer object's data store where data + replacement will begin, measured in bytes.
+ size +: Specifies the size in bytes of the data store region being replaced.
+ data +: + Specifies a pointer to the new data that will be copied into the data store.

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

+ 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 N bytes be a + multiple of N. +

Errors

+ GL_INVALID_ENUM is generated if target is not + GL_ARRAY_BUFFER or GL_ELEMENT_ARRAY_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. +

Copyright

Name

glClear — clear buffers to preset values

C Specification

void glClear( GLbitfield mask);

Parameters

+ mask +: Bitwise OR of masks that indicate the buffers to be + cleared. Valid masks are + GL_COLOR_BUFFER_BIT, + GL_DEPTH_BUFFER_BIT, and + GL_STENCIL_BUFFER_BIT.

Description

+ glClear + sets the bitplane area of the window to values previously selected by + glClearColor, + glClearDepth, + and + glClearStencil. +

The pixel ownership test, the scissor test, dithering, + and the buffer write masks 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 color buffer.
+ GL_DEPTH_BUFFER_BIT +: Indicates the depth 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 defined bits is set in + mask.

Associated Gets

+ glGet with argument GL_COLOR_CLEAR_VALUE +

+ glGet with argument GL_DEPTH_CLEAR_VALUE +

+ glGet with argument GL_STENCIL_CLEAR_VALUE +

Copyright

Name

glClearColor — specify clear values for the color buffer

C Specification

`void glClearColor(`	GLclampf `red`,
	GLclampf `green`,
	GLclampf `blue`,
	GLclampf `alpha)`;

`void glClearColorx(`	GLclampx `red`,
	GLclampx `green`,
	GLclampx `blue`,
	GLclampx `alpha)`;

Parameters

+ red, + green, + blue, + alpha +: Specify the red, green, blue, and alpha values used + when the color buffer is cleared. The initial values + are all 0.

Description

+ glClearColor + specifies the red, green, blue, and alpha values used by + glClear + to clear the color buffer. Values specified by + glClearColor + are clamped to the range [0, 1].

Associated Gets

+ glGet with argument GL_COLOR_CLEAR_VALUE +

Copyright

Name

glClearDepth — specify the clear value for the depth buffer

C Specification

void glClearDepthf( GLclampf depth);

void glClearDepthx( GLclampx depth);

Parameters

+ depth +: Specifies the depth value used when the depth + buffer is cleared. The initial value is 1.

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].

Associated Gets

+ glGet with argument GL_DEPTH_CLEAR_VALUE +

Copyright

Name

glClearStencil — specify the clear value for the stencil buffer

C Specification

void glClearStencil( GLint s);

Parameters

+ s +: Specifies the index used when the stencil buffer is + cleared. The initial value is 0.

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.

Associated Gets

+ glGet with argument GL_STENCIL_CLEAR_VALUE +

+ glGet + with argument GL_STENCIL_BITS +

Copyright

Name

glClientActiveTexture — select client-side active texture unit

C Specification

void glClientActiveTexture( GLenum texture);

Parameters

+ texture +: + Specifies which texture unit to make active. The + number of texture units is implementation dependent, but + must be at least two. + texture must be one of + GL_TEXTUREi, + + 0 + <= + i + < + GL_MAX_TEXTURE_UNITS + , + which is an implementation-dependent value. The initial + value is GL_TEXTURE0. +

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.

Errors

+ GL_INVALID_ENUM is generated if + texture is not one of + GL_TEXTUREi, + where + + 0 + <= + i + < + GL_MAX_TEXTURE_UNITS + . +

Notes

It is always the case that + + GL_TEXTUREi = + GL_TEXTURE0+i + .

Associated Gets

+ glGet + with argument GL_CLIENT_ACTIVE_TEXTURE or + GL_MAX_TEXTURE_UNITS +

Copyright

Name

glClipPlane — specify a plane against which all geometry is + clipped

C Specification

`void glClipPlanef(`	GLenum `plane`,
	const GLfloat *`equation)`;

`void glClipPlanex(`	GLenum `plane`,
	const GLfixed *`equation)`;

Parameters

plane: Specifies which clipping plane is being positioned. Symbolic + names of the form GL_CLIP_PLANEi, + where i is an integer + between 0 and GL_MAX_CLIP_PLANES + + + + -1 + , are accepted.
equation: Specifies the address of an array of four fixed-point or + floating-point values. These are the coefficients of a plane + equation in object coordinates: p1, + p2, p3, and + p4, in that order.

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 glGet with argument GL_MAX_CLIP_PLANES. + All implementations support at least one such clipping plane. 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, the coefficients given by equation are + transformed by the inverse of the modelview matrix and stored in the + resulting eye coordinates. The resulting plane equation is undefined, if + the model-view matrix M is singular and it may be + inaccurate, if M is poorly conditioned. Subsequent + changes to the modelview matrix have no effect on the stored + plane-equation coefficients. 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.

Associated Gets

glGetClipPlane, glIsEnabled with argument + GL_CLIP_PLANEi.

Copyright

Name

glColor — set the current color

C Specification

`void glColor4f(`	GLfloat `red`,
	GLfloat `green`,
	GLfloat `blue`,
	GLfloat `alpha)`;

`void glColor4x(`	GLfixed `red`,
	GLfixed `green`,
	GLfixed `blue`,
	GLfixed `alpha)`;

`void glColor4ub(`	GLubyte `red`,
	GLubyte `green`,
	GLubyte `blue`,
	GLubyte `alpha)`;

Parameters

+ red, + green, + blue, + alpha +: Specify new red, green, blue, and alpha values for + the current color.

Description

glColor sets a new four-valued current RGBA color.

Current color values are stored in fixed-point or + floating-point. In case the values are stored in + floating-point, the mantissa and exponent sizes are + unspecified.

Neither fixed-point nor floating-point 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 the color buffer.

Unsigned byte color components specified + with glColor4ub are linearly mapped to + floating-point values such that 255 maps to 1.0 (full + intensity), and 0 maps to 0.0 (zero intensity).

Notes

The initial value for the current color is (1, 1, 1, 1).

Associated Gets

+ glGet with argument GL_CURRENT_COLOR +

Copyright

Name

glColorMask — enable and disable writing of color buffer + components

C Specification

`void glColorMask(`	GLboolean `red`,
	GLboolean `green`,
	GLboolean `blue`,
	GLboolean `alpha)`;

Parameters

+ red, + green, + blue, + alpha +: Specify whether red, green, blue, and alpha can or + cannot be written into the color buffer. The initial + values are all GL_TRUE, + indicating that all color components can be written.

Description

+ glColorMask + specifies whether the individual components in the color + 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 the color buffer, regardless of the drawing operation + attempted, including + glClear. +

Changes to individual bits of components cannot be + controlled. Rather, changes are either enabled or disabled for + entire color components.

Copyright

Name

glColorPointer — define an array of colors

C Specification

`void glColorPointer(`	GLint `size`,
	GLenum `type`,
	GLsizei `stride`,
	const GLvoid * `pointer)`;

Parameters

+ size +

Specifies the number of components per color. Must + be 4. The initial value is 4.

+ type +

Specifies the data type of each color component in + the array. Symbolic constants + GL_UNSIGNED_BYTE and + GL_FIXED are accepted. + However, the initial value is + GL_FLOAT.

+ The common profile accepts the symbolic constant + GL_FLOAT as well. +

+ stride +

Specifies the byte offset between consecutive colors. If + stride + is 0, the colors are understood to be + tightly packed in the array. The initial value is 0.

+ pointer +

Specifies a pointer to the first component of the + first color element in the array.

Description

+ glColorPointer + specifies the location and data of an array of color components + to use when rendering. + size + specifies the number of components per color, and must be 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.)

When a color array is specified, + size, + type, + stride, and + pointer + are saved as client-side state.

+ If the color array is enabled, it is used when + glDrawArrays, + or + glDrawElements + is called. + To enable and disable the color array, call + glEnableClientState + and + glDisableClientState + with the argument GL_COLOR_ARRAY. + The color array is initially disabled and isn't accessed when + glDrawArrays or + glDrawElements + is called.

Use + glDrawArrays + to construct a sequence of primitives (all of the same type) + from prespecified vertex and vertex attribute arrays. Use + glDrawElements + to construct a sequence of primitives by indexing vertices and + vertex attributes.

Notes

glColorPointer + is typically implemented on the client side.

Errors

+ GL_INVALID_VALUE is generated if + size is not 4.

+ GL_INVALID_ENUM is generated if + type is not an accepted value.

+ GL_INVALID_VALUE is generated if + stride is negative.

Copyright

Name

glCompressedTexImage2D — specify a two-dimensional compressed texture image

C Specification

`void glCompressedTexImage2D(`	GLenum `target`,
	GLint `level`,
	GLenum `internalformat`,
	GLsizei `width`,
	GLsizei `height`,
	GLint `border`,
	GLsizei `imageSize`,
	const GLvoid * `data)`;

Parameters

+ target +: Specifies the target texture. Must be + GL_TEXTURE_2D.
+ level +: Specifies the level-of-detail number. For paletted formats, + where all mipmap levels are loaded at once, + this parameter is overloaded to represent the negative of the + greatest mipmap level included in data. +
+ internalformat +: Specifies the color components in the + texture. The following symbolic constants are accepted: + GL_PALETTE4_RGB8_OES, + GL_PALETTE4_RGBA8_OES, + GL_PALETTE4_R5_G6_B5_OES, + GL_PALETTE4_RGBA4_OES, + GL_PALETTE4_RGB5_A1_OES, + GL_PALETTE8_RGB8_OES, + GL_PALETTE8_RGBA8_OES, + GL_PALETTE8_R5_G6_B5_OES, + GL_PALETTE8_RGBA4_OES, and + GL_PALETTE8_RGB5_A1_OES.
+ width +: Specifies the width of the texture image. Must be + + 2n + + for some integer n. + All implementations support texture images that are at + least 64 texels wide.
+ height +: Specifies the height of the texture image. Must be + + 2m + + for some integer m. + All implementations support texture images that are at + least 64 texels high.
+ border +: Specifies the width of the border. Must be 0.
+ imageSize +: Specifies the size of the compressed image data in bytes.
+ data +: Specifies a pointer to the compressed image data in memory.

Description

+ glCompressedTexImage2D defines a two-dimensional texture image + or cube-map texture image using compressed image data from client memory. The texture + image is decoded according to the definition of the + internalformat. In addition to the paletted formats + described below, OpenGL ES provides a mechanism to obtain symbolic constants for + other formats provided by extensions. The number of compressed texture formats + supported can be obtained by querying the value of + GL_NUM_COMPRESSED_TEXTURE_FORMATS. The list of specific + compressed texture formats supported can be obtained by querying the value of + GL_COMPRESSED_TEXTURE_FORMATS. +

The required compressed formats are paletted textures. + The layout of the compressed image is a + palette followed by multiple mip-levels of + texture indices used for lookup into the palette. + The palette format can be one of + R5_G6_B5, + RGBA4, + RGB5_A1, + RGB8, or + RGBA8. + The texture indices can have a resolution of 4 or 8 bits. + As a result, the number of palette entries is either + 16 or 256. If level is 0, only one mip-level + of texture indices is described in data. Otherwise, + the negative value of level + specifies up to which mip-level the texture indices are described. + A possibly remaining pad nibble for the lowest resolution + mip-level is ignored.

Notes

glPixelStorei + has no effect on compressed texture images.

glCompressedTexImage2D + specifies the two-dimensional texture for the currently bound texture, + specified with + glBindTexture, + and the current texture + unit, specified with + glActiveTexture. +

Errors

GL_INVALID_ENUM is generated if + target is not + GL_TEXTURE_2D.

GL_INVALID_VALUE may be generated if + if internalformat is not one of the paletted formats and + level is greater than 0 or the + absolute value of level is greater than + + log2max + , where + max is the returned value of + GL_MAX_TEXTURE_SIZE.

GL_INVALID_VALUE may be generated if + if internalformat is not one of the paletted formats and + level is less than 0 or greater than + + log2max + , where + max is the returned value of + GL_MAX_TEXTURE_SIZE.

+ GL_INVALID_ENUM is generated if + internalformat + is not one of the accepted symbolic constants. +

GL_INVALID_VALUE is generated if + width or + height + is less than 0 or greater than + GL_MAX_TEXTURE_SIZE, + or if either cannot be represented as + + 2k + + for some integer k.

GL_INVALID_VALUE is generated if + border is not 0.

GL_INVALID_VALUE is generated if + imageSize is not consistent + with format, dimentions, and contents of the compressed image.

Associated Gets

+ glGet with arguments + GL_NUM_COMPRESSED_TEXTURE_FORMATS and + GL_COMPRESSED_TEXTURE_FORMATS +

+ glGet + with argument GL_MAX_TEXTURE_SIZE

Copyright

Name

glCompressedTexSubImage2D — specify a two-dimensional compressed texture subimage

C Specification

`void glCompressedTexSubImage2D(`	GLenum `target`,
	GLint `level`,
	GLint `xoffset`,
	GLint `yoffset`,
	GLsizei `width`,
	GLsizei `height`,
	GLenum `format`,
	GLsizei `imageSize`,
	const GLvoid * `data)`;

Parameters

+ target +: Specifies the target texture. Must be + GL_TEXTURE_2D.
+ level +: Specifies the level-of-detail number.
+ xoffset +: Specifies a texel offset in the x direction within + the texture array.
+ yoffset +: Specifies a texel offset in the y direction within + the texture array.
+ width +: Specifies the width of the texture subimage.
+ height +: Specifies the height of the texture subimage.
+ format +: Specifies the format of the pixel data. + Currently, there is no supported format.
+ imageSize +: Specifies the size of the compressed pixel data in bytes.
+ data +: Specifies a pointer to the compressed image data in + memory.

Description

+ glCompressedTexSubImage2D + redefines a contiguous subregion of an existing two-dimensional + compressed texture image. + The texels referenced by pixels + replace the portion of the existing texture array with x indices + xoffset and + + xoffset+width-1 + , + inclusive, and y indices yoffset and + + yoffset+height-1 + , + inclusive. This region may not include any texels outside the + range of the texture array as it was originally specified. It + is not an error to specify a subtexture with zero width or + height, but such a specification has no effect.

format must be the same compressed-texture format + previously specified by + glCompressedTexImage2D.

The required paletted formats do not allow subimage updates, + but other formats defined by extensions may.

Notes

glPixelStorei + has no effect on compressed texture images.

+ glCompressedTexSubImage2D + specifies the two-dimensional sub texture for the currently bound texture, + specified with + glBindTexture, + and the current texture + unit, specified with + glActiveTexture. +

Errors

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 + + log2max + , where + max is the returned value of + GL_MAX_TEXTURE_SIZE.

+ GL_INVALID_VALUE is generated if + + + + xoffset + < + 0 + + , + + + + + + xoffset + + + width + + + > + w + + , + + + + yoffset + < + 0 + + , + or + + + + + + yoffset + + + height + + + > + h + + , + where + w + is the width and + h + is the height + of the texture image being modified. +

GL_INVALID_VALUE is generated if + width or + height is less than 0.

+ GL_INVALID_OPERATION is generated if the texture array has not + been defined by a previous + glCompressedTexImage2D + operation whose internalformat matches the format + of glCompressedTexSubImage2D. +

+ 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. +

+ 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

+ glGet with arguments + GL_NUM_COMPRESSED_TEXTURE_FORMATS and + GL_COMPRESSED_TEXTURE_FORMATS +

+ glGet + with argument GL_MAX_TEXTURE_SIZE

Copyright

Name

glCopyTexImage2D — specify a two-dimensional texture image with pixels from the color buffer

C Specification

`void glCopyTexImage2D(`	GLenum `target`,
	GLint `level`,
	GLenum `internalformat`,
	GLint `x`,
	GLint `y`,
	GLsizei `width`,
	GLsizei `height`,
	GLint `border)`;

Parameters

+ target +: Specifies the target texture. Must be + GL_TEXTURE_2D.
+ level +: Specifies the level-of-detail number. Level 0 is + the base image level. Level n + is the nth mipmap reduction image.
+ internalformat +: Specifies the color components of the texture. Must be one + of the following symbolic constants: + GL_ALPHA, + GL_LUMINANCE, + GL_LUMINANCE_ALPHA, + GL_RGB, or + GL_RGBA.
+ x, y +: Specify the window coordinates of the lower left + corner of the rectangular region of pixels to be + copied.
+ width +: Specifies the width of the texture image. Must be 0 or + + 2n + + for some integer n.
+ height +: Specifies the height of the texture image. Must be 0 or + + 2m + + for some integer m.
+ border +: Specifies the width of the border. Must be 0.

Description

+ glCopyTexImage2D + defines a two-dimensional texture image with pixels from the + color buffer.

The screen-aligned pixel rectangle with lower left corner + at (x, y) + and with a width of + + width + + and a height of + + height + + defines the texture array at the mipmap level specified by + level. internalformat + specifies the color components of the texture.

+ The red, green, blue, and alpha + components of each pixel that is read are converted to an + internal fixed-point or 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 values are then converted to the texture's internal format for + storage in the texel array.

internalformat must be chosen such that + color buffer components can be dropped during conversion to the + internal format, but new components cannot be added. For example, + an GL_RGB color buffer can be used to create + GL_LUMINANCE or GL_RGB + textures, but not GL_ALPHA, + GL_LUMINANCE_ALPHA or GL_RGBA + textures.

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 color buffer are outside the window associated with the + current rendering context, then the values obtained for those + pixels are undefined.

Notes

An image with height or width of 0 indicates a + null-texture.

Errors

GL_INVALID_ENUM is generated if + target is not + GL_TEXTURE_2D.

GL_INVALID_OPERATION is generated if + internalformat is not compatible + with the color buffer format.

GL_INVALID_VALUE is generated if + level is less than 0.

GL_INVALID_VALUE may be generated if + level is greater than + + log2max + , where + max is the returned value of + GL_MAX_TEXTURE_SIZE.

+ GL_INVALID_VALUE is generated if + width or + height + is less than 0, greater than + GL_MAX_TEXTURE_SIZE, or if + width or height + cannot be represented as + + 2k + + for some integer k.

GL_INVALID_VALUE is generated if + border is not 0.

+ GL_INVALID_ENUM is generated if + internalformat + is not an accepted constant. +

Associated Gets

+ glGet + with argument GL_MAX_TEXTURE_SIZE

Copyright

Name

glCopyTexSubImage2D — specify a two-dimensional texture subimage with pixels from the color buffer

C Specification

`void glCopyTexSubImage2D(`	GLenum `target`,
	GLint `level`,
	GLint `xoffset`,
	GLint `yoffset`,
	GLint `x`,
	GLint `y`,
	GLsizei `width`,
	GLsizei `height)`;

Parameters

+ target +: Specifies the target texture. Must be + GL_TEXTURE_2D.
+ level +: Specifies the level-of-detail number. Level 0 is + the base image level. Level n + is the nth mipmap reduction image.
+ xoffset +: Specifies a texel offset in the x direction within + the texture array.
+ yoffset +: Specifies a texel offset in the y direction within + the texture array.
+ x, y +: Specify the window coordinates of the lower left + corner of the rectangular region of pixels to be + copied.
+ width +: Specifies the width of the texture subimage.
+ height +: Specifies the height of the texture subimage.

Description

glCopyTexSubImage2D + replaces a rectangular portion of a two-dimensional texture + image with pixels from the color buffer. +

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 the same way + as with + glCopyTexImage2D. +

glCopyTexSubImage2D requires + that the internal format of the currently bound texture is such that + color buffer components can be dropped during conversion to the + internal format, but new components cannot be added. For example, + an GL_RGB color buffer can be used to create + GL_LUMINANCE or GL_RGB + textures, but not GL_ALPHA, + GL_LUMINANCE_ALPHA or GL_RGBA + textures.

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 color 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.

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 or if the internal format of the currently bound texture + is not compatible with the color buffer format.

GL_INVALID_VALUE is generated if + level is less than 0.

GL_INVALID_VALUE may be generated if + level is greater than + + log2max + , where + max is the returned value of + GL_MAX_TEXTURE_SIZE.

GL_INVALID_VALUE is generated if + + xoffset<0 + , + + xoffset+width> + w + , + + yoffset<0 + , or + + yoffset+height> + h + , where + w is the texture width and + h is the texture height.

Associated Gets

+ glGet + with argument GL_MAX_TEXTURE_SIZE

Copyright

Name

glCullFace — specify whether front- or back-facing polygons are + culled

C Specification

void glCullFace( GLenum mode);

Parameters

+ mode +: Specifies whether front- or back-facing polygons are + culled. Symbolic constants + GL_FRONT, + GL_BACK, and + GL_FRONT_AND_BACK + are accepted. The initial value is + GL_BACK.

Description

+ glCullFace + specifies whether front- or back-facing polygons are culled (as + specified by mode) + when culling is enabled. + To enable and disable culling, call + glEnable + and + glDisable + with argument GL_CULL_FACE. + Culling is initially disabled. +

+ glFrontFace + specifies which of the clockwise and counterclockwise polygons + are front-facing and back-facing.

Notes

If mode is + GL_FRONT_AND_BACK, + no polygons are drawn, but other primitives such as points and + lines are drawn.

Errors

GL_INVALID_ENUM is generated if + mode is not an accepted value.

Associated Gets

+ glIsEnabled with argument GL_CULL_FACE +

+ glGet with argument GL_CULL_FACE_MODE +

Copyright

Name

glDeleteBuffers — delete named buffer objects

C Specification

`void glDeleteBuffers(`	GLsizei `n`,
	const GLuint * `buffers)`;

Parameters

+ n +: Specifies the number of buffer objects to be + deleted.
+ buffers +: Specifies an array of buffer object names to be + deleted.

Description

+ glDeleteBuffers + deletes n + buffer objects named by the elements of the array + buffers. + After a buffer object is deleted, it has no contents, + and its name is free for reuse.

glDeleteBuffers + silently ignores zero and names that do not correspond to + existing buffer objects.

Notes

+ If a buffer object is deleted while it is bound, all + bindings to that object in the current context (i.e. in the thread that called + glDeleteBuffers) are reset to zero. + Bindings to that buffer in other contexts and other + threads are not affected, but attempting to use a deleted buffer in another thread + produces undefined results, including but not limited to possible GL errors and + rendering corruption. Using a deleted buffer in another context or thread may not, + however, result in program termination. +

Errors

GL_INVALID_VALUE is generated if + n is negative.

Associated Gets

+ glIsBuffer +

Copyright

Name

glDeleteTextures — delete named textures

C Specification

`void glDeleteTextures(`	GLsizei `n`,
	const GLuint * `textures)`;

Parameters

+ n +: Specifies the number of textures to be + deleted.
+ textures +: Specifies an array of textures to be + deleted.

Description

+ glDeleteTextures + deletes n + textures named by the elements of the array + textures. + After a texture is deleted, it has no contents or + dimensionality, and its name is free for reuse (for example by + glGenTextures). + If a texture that is currently bound is deleted, the binding + reverts to 0 (the default texture).

glDeleteTextures + silently ignores 0's and names that do not correspond to + existing textures.

Errors

GL_INVALID_VALUE is generated if + n is negative.

Associated Gets

+ glIsTexture +

Copyright

Name

glDepthFunc — specify the value used for depth buffer comparisons

C Specification

void glDepthFunc( GLenum func);

Parameters

+ func +: Specifies the depth comparison function. Symbolic constants + GL_NEVER, + GL_LESS, + GL_EQUAL, + GL_LEQUAL, + GL_GREATER, + GL_NOTEQUAL, + GL_GEQUAL, and + GL_ALWAYS are accepted. The initial value is + GL_LESS.

Description

+ glDepthFunc + specifies the function used to compare each incoming pixel + depth value with the depth value present in the depth buffer. + The comparison is performed only if depth testing is enabled. + To enable and disable depth testing, call + glEnable and + glDisable + with argument GL_DEPTH_TEST. + Depth testing is initially disabled.

func + specifies the conditions under which the pixel will be drawn. + The comparison functions are as follows:

+ GL_NEVER +: Never passes.
+ GL_LESS +: Passes if the incoming depth value is less than the + stored depth value.
+ GL_EQUAL +: Passes if the incoming depth value is equal to the + stored depth value.
+ GL_LEQUAL +: Passes if the incoming depth value is less than or + equal to the stored depth value.
+ GL_GREATER +: Passes if the incoming depth value is greater than + the stored depth value.
+ GL_NOTEQUAL +: Passes if the incoming depth value is not equal to + the stored depth value.
+ GL_GEQUAL +: Passes if the incoming depth value is greater than + or equal to the stored depth value.
+ GL_ALWAYS +: Always passes.

The initial value of func is + GL_LESS. Initially, depth testing is disabled. + If depth testing is disabled or no depth buffer exists, it is as if the + depth test always passes. + Even if the depth buffer exists and the depth mask is non-zero, + the depth buffer is not updated if the depth test is disabled.

Errors

GL_INVALID_ENUM is generated if + func is not an accepted value.

Copyright

Name

glDepthMask — enable or disable writing into the depth buffer

C Specification

void glDepthMask( GLboolean flag);

Parameters

+ flag +: Specifies whether the depth buffer is enabled for writing. If + flag is GL_FALSE, + depth buffer writing is disabled, otherwise it is enabled. + The initial value is GL_TRUE.

Description

+ glDepthMask + specifies whether the depth buffer is enabled for writing. If + flag is GL_FALSE, + depth buffer writing is disabled. Otherwise, it is enabled. + Initially, depth buffer writing is enabled.

Copyright

Name

glDepthRange — specify mapping of depth values from normalized + device coordinates to window coordinates

C Specification

`void glDepthRangef(`	GLclampf `near`,
	GLclampf `far)`;

`void glDepthRangex(`	GLclampx `near`,
	GLclampx `far)`;

Parameters

+ near +: Specifies the mapping of the near clipping plane to + window coordinates. The initial value is 0.
+ far +: Specifies the mapping of the far clipping plane to + window coordinates. The initial value is 1.

Description

After clipping and division by w, + depth coordinates range from -1 to 1, corresponding to the + near and far clipping planes. glDepthRange + specifies a linear mapping of the normalized depth coordinates + in this range to window depth coordinates. Regardless of the + actual depth buffer implementation, window coordinate depth + values are treated as though they range from 0 through 1 (like + color components). Thus, the values accepted by + glDepthRange + are both clamped to this range before they are accepted.

The setting of (0, 1) maps the near plane to 0 and the far + plane to 1. With this mapping, the depth buffer range is fully + utilized.

Notes

It is not necessary that near + be less than far. + Reverse mappings such as + + near + = + 1 + , + and + + far + = + 0 + + are acceptable.

Copyright

Name

glDrawArrays — render primitives from array data

C Specification

`void glDrawArrays(`	GLenum `mode`,
	GLint `first`,
	GLsizei `count)`;

Parameters

+ mode +: Specifies what kind of primitives to render. + Symbolic constants + GL_POINTS, + GL_LINE_STRIP, + GL_LINE_LOOP, + GL_LINES, + GL_TRIANGLE_STRIP, + GL_TRIANGLE_FAN, and + GL_TRIANGLES are accepted.
+ first +: Specifies the starting index in the enabled arrays.
+ count +: Specifies the number of indices to be rendered.

Description

+ glDrawArrays + specifies multiple geometric primitives with very few + subroutine calls. You can prespecify separate arrays of + vertices, normals, colors, and texture coordinates and use them + to construct a sequence of primitives with a single call to + glDrawArrays.

When + glDrawArrays is called, it uses + count + sequential elements from each enabled array to construct a + sequence of geometric primitives, beginning with element + first. + mode + specifies what kind of primitives are constructed, and how the + array elements construct those primitives. If + GL_VERTEX_ARRAY + is not enabled, no geometric primitives are generated.

Vertex attributes that are modified by + glDrawArrays have an unspecified value after + glDrawArrays returns. For example, if + GL_COLOR_ARRAY + is enabled, the value of the current color is undefined after + glDrawArrays + executes. Attributes that aren't modified remain well defined.

Errors

GL_INVALID_ENUM is generated if + mode is not an accepted value.

GL_INVALID_VALUE is generated if + count is negative.

Copyright

Name

glDrawElements — render primitives from array data

C Specification

`void glDrawElements(`	GLenum `mode`,
	GLsizei `count`,
	GLenum `type`,
	const GLvoid * `indices)`;

Parameters

+ mode +: Specifies what kind of primitives to render. + Symbolic constants + GL_POINTS, + GL_LINE_STRIP, + GL_LINE_LOOP, + GL_LINES, + GL_TRIANGLE_STRIP, + GL_TRIANGLE_FAN, and + GL_TRIANGLES are accepted.
+ count +: Specifies the number of elements to be rendered.
+ type +: Specifies the type of the values in + indices. Must be either + GL_UNSIGNED_BYTE or + GL_UNSIGNED_SHORT.
+ indices +: Specifies a pointer to the location where the + indices are stored.

Description

+ glDrawElements + + specifies multiple geometric primitives with very few + subroutine calls. You can prespecify separate arrays of + vertices, normals, colors, and texture coordinates and use them + to construct a sequence of primitives with a single call to + glDrawElements.

When glDrawElements is called, it uses + count sequential indices from + indices + to lookup elements in enabled arrays to construct a sequence of + geometric primitives. + mode + specifies what kind of primitives are constructed, and how the + array elements construct these primitives. If + GL_VERTEX_ARRAY + is not enabled, no geometric primitives are constructed.

Vertex attributes that are modified by + glDrawElements have an unspecified value after + glDrawElements + returns. For example, if GL_COLOR_ARRAY + is enabled, the value of the current color is undefined after + glDrawElements + executes. Attributes that aren't modified maintain their + previous values.

Errors

GL_INVALID_ENUM is generated if + mode is not an accepted value.

GL_INVALID_ENUM is generated if + type is not an accepted value.

GL_INVALID_VALUE is generated if + count is negative.

Copyright

Name

glEnable — enable or disable server-side GL capabilities

C Specification

void glEnable( GLenum cap);

void glDisable( GLenum cap);

Parameters

+ cap +: Specifies a symbolic constant indicating a GL capability.

Description

glEnable and glDisable + enable and disable various capabilities. Use + glIsEnabled or + glGet to determine the + current setting of any capability. The initial value for + each capability with the exception of + GL_DITHER and + GL_MULTISAMPLE is + GL_FALSE. The initial value for + GL_DITHER and + GL_MULTISAMPLE is + GL_TRUE.

Both glEnable and glDisable + take a single argument, cap, + which can assume one of the following values:

+ GL_ALPHA_TEST +: If enabled, do alpha testing. See + glAlphaFunc.
+ GL_BLEND +: If enabled, blend the computed fragment color values + with the values in the color buffers. See + glBlendFunc.
+ GL_COLOR_LOGIC_OP +: If enabled, apply the currently selected logical + operation to the computed fragment color and color buffer values. See + glLogicOp.
+ GL_CLIP_PLANEi +: If enabled, clip geometry against user-defined clipping plane + i. See + glClipPlane.
+ GL_COLOR_MATERIAL +: If enabled, have ambient and diffuse material + parameters track the current color.
+ GL_CULL_FACE +: If enabled, cull polygons based on their winding in + window coordinates. See + glCullFace.
+ GL_DEPTH_TEST +: If enabled, do depth comparisons and update the + depth buffer. Note that even if the depth buffer exists + and the depth mask is non-zero, the depth buffer is not + updated if the depth test is disabled. See + glDepthFunc + and + glDepthRange.
+ GL_DITHER +: If enabled, dither color components + before they are written to the color buffer.
+ GL_FOG +: If enabled, blend a fog color into the + posttexturing color. See + glFog.
+ GL_LIGHTi +: If enabled, include light i + in the evaluation of the lighting equation. See + glLightModel + and + glLight.
+ GL_LIGHTING +: If enabled, use the current lighting parameters to + compute the vertex color. Otherwise, simply + associate the current color with each vertex. See + glMaterial, + glLightModel, and + glLight.
+ GL_LINE_SMOOTH +: If enabled, draw lines with correct filtering. + Otherwise, draw aliased lines. See + glLineWidth.
+ GL_MULTISAMPLE +: If enabled, use multiple fragment samples in computing the final color + of a pixel. See + glSampleCoverage.
+ GL_NORMALIZE +: If enabled, normal vectors are normalized to unit length after + transformation and before lighting. This method is generally + less efficient than GL_RESCALE_NORMAL. See + glNormal and + glNormalPointer.
+ GL_POINT_SMOOTH +: If enabled, draw points with proper filtering. + Otherwise, draw aliased points. See + glPointSize.
+ GL_POINT_SPRITE_OES +: + If enabled, point sprites are enabled. + See + glPointSize + and + glTexEnv +
+ GL_POLYGON_OFFSET_FILL +: If enabled, + an offset is added to depth values of a polygon's + fragments before the depth comparison is performed. See + glPolygonOffset.
+ GL_RESCALE_NORMAL +: If enabled, normal vectors are scaled after transformation and before + lighting by a factor computed from the modelview matrix. If the modelview + matrix scales space uniformly, this has the effect of restoring the + transformed normal to unit length. This method is generally more efficient than + GL_NORMALIZE. See + glNormal and + glNormalPointer.
+ GL_SAMPLE_ALPHA_TO_COVERAGE +: If enabled, compute a temporary coverage value where each bit is + determined by the alpha value at the corresponding sample location. The + temporary coverage value is then ANDed with the fragment coverage value.
+ GL_SAMPLE_ALPHA_TO_ONE +: If enabled, each sample alpha value is replaced by the maximum + representable alpha value.
+ GL_SAMPLE_COVERAGE +: If enabled, the fragment's coverage is ANDed with the temporary + coverage value. If GL_SAMPLE_COVERAGE_INVERT is set to + GL_TRUE, invert the coverage value. See + glSampleCoverage.
+ GL_SCISSOR_TEST +: If enabled, discard fragments that are outside the + scissor rectangle. See + glScissor.
+ GL_STENCIL_TEST +: If enabled, do stencil testing and update the + stencil buffer. See + glStencilFunc, + glStencilMask, + and + glStencilOp.
+ GL_TEXTURE_2D +: If enabled, two-dimensional texturing is performed + for the active texture unit. See + glActiveTexture, + glTexImage2D, + glCompressedTexImage2D, + and + glCopyTexImage2D.

Notes

+ GL_CLIP_PLANEi and + GL_POINT_SPRITE_OES are only supported if the GL version is + 1.1 or greater. +

Errors

GL_INVALID_ENUM is generated if + cap + is not one of the values listed previously.

Associated Gets

+ glIsEnabled +

+ glGet +

Copyright

Name

glEnableClientState — enable or disable client-side capability

C Specification

void glEnableClientState( GLenum array);

void glDisableClientState( GLenum array);

Parameters

+ array +: + Specifies the capability to enable or disable. + Symbolic constants + GL_COLOR_ARRAY, + + GL_NORMAL_ARRAY, + GL_POINT_SIZE_ARRAY_OES, + GL_TEXTURE_COORD_ARRAY, and + GL_VERTEX_ARRAY + + are accepted. +

Description

+ glEnableClientState and + glDisableClientState + enable or disable individual client-side capabilities. By + default, all client-side capabilities are disabled. Both + glEnableClientState and + glDisableClientState + take a single argument, array, + which can assume one of the following values:

+ GL_COLOR_ARRAY +: If enabled, the color array is enabled for writing + and used during rendering when + glDrawArrays, or + glDrawElements is called. See + glColorPointer.
+ GL_NORMAL_ARRAY +: If enabled, the normal array is enabled for writing + and used during rendering when + glDrawArrays, or + glDrawElements is called. See + glNormalPointer.
+ GL_POINT_SIZE_ARRAY_OES +: + If enabled, the point size array controls the sizes used + to render points and point sprites. In this case the point + size defined by glPointSize + is ignored. + The point sizes supplied in the point size arrays will be + the sizes used to render both points and point sprites. + See glPointSize +
+ GL_TEXTURE_COORD_ARRAY +: If enabled, the texture coordinate array is enabled + for writing and used during rendering when + glDrawArrays, or + glDrawElements is called. See + glTexCoordPointer.
+ GL_VERTEX_ARRAY +: If enabled, the vertex array is enabled for writing + and used during rendering when + glDrawArrays, or + glDrawElements is called. See + glVertexPointer.

Notes

Enabling and disabling + GL_TEXTURE_COORD_ARRAY + affects the active client texture unit. The active client + texture unit is controlled with + glClientActiveTexture.

Errors

GL_INVALID_ENUM is generated if + array is not an accepted value.

Associated Gets

+ glIsEnabled +

Copyright

Name

glFinish — block until all GL execution is complete

C Specification

void glFinish( void);

Description

+ glFinish does not return until the effects + of all previously called GL commands are complete. Such effects + include all changes to GL client and server state as well as all + changes to the frame buffer contents.

Notes

+ glFinish is NOT required before a call + to eglSwapBuffers + or glReadPixels. + glFinish can take some time and for + performance reasons it is best to use this function + infrequently and only when necessary. +

Copyright

Name

glFlush — force execution of GL commands in finite time

C Specification

void glFlush( void);

Description

Different GL implementations may buffer commands in + several different locations, including the GL client, the GL + server, and the graphics accelerator. + glFlush empties all of these buffers, + causing all issued commands to be executed as quickly as they + are accepted by the actual rendering engine. Though this + execution may not be completed in any particular time period, it + does complete in finite time.

Because any GL program might be on an implementation that + buffers commands, all programs should call + glFlush whenever they count on having all + of their previously issued commands completed. For example, call + glFlush before waiting for user input that + depends on the generated image.

Notes

+ glFlush + can return at any time. It does not wait until the execution of + all previously issued GL commands is complete. +

Copyright

Name

glFog — specify fog parameters

C Specification

`void glFogf(`	GLenum `pname`,
	GLfloat `param)`;

`void glFogx(`	GLenum `pname`,
	GLfixed `param)`;

Parameters

+ pname +: Specifies a single-valued fog parameter. + GL_FOG_MODE, + GL_FOG_DENSITY, + GL_FOG_START, and + GL_FOG_END are accepted.
+ param +: Specifies the value that + pname + + will be set to.

C Specification

`void glFogfv(`	GLenum `pname`,
	const GLfloat * `params)`;

`void glFogxv(`	GLenum `pname`,
	const GLfixed * `params)`;

Parameters

+ pname +: Specifies a fog parameter. + GL_FOG_MODE, + GL_FOG_DENSITY, + GL_FOG_START, + GL_FOG_END, and + GL_FOG_COLOR are accepted.
+ params +: Specifies the value or values to be assigned to + pname. + GL_FOG_COLOR + requires an array of four values. All other parameters + accept an array containing only a single value.

Description

If fog is enabled, fog affects + rasterized geometry, bitmaps, and pixel blocks, but not buffer + clear operations. To enable and disable fog, call + glEnable and + glDisable + with argument GL_FOG. + Fog is initially disabled. +

+ glFog assigns the value or values in + params to the fog parameter specified by + pname. The following values are accepted for + pname:

+ GL_FOG_MODE +: + params + is a single fixed-point or floating-point value that + specifies the equation to be used to compute the fog + blend factor f. + Three symbolic constants are accepted: + GL_LINEAR, + GL_EXP, and + GL_EXP2. + The equations corresponding to these symbolic constants + are defined below. The initial fog mode is + GL_EXP.
+ GL_FOG_DENSITY +: + params + is a single fixed-point or floating-point value that + specifies density, + the fog density used in both exponential fog equations. + Only nonnegative densities are accepted. The initial fog + density is 1.
+ GL_FOG_START +: + params + is a single fixed-point or floating-point value that + specifies start, + the near distance used in the linear fog equation. The + initial near distance is 0.
+ GL_FOG_END +: + params + is a single fixed-point or floating-point value that + specifies end, + the far distance used in the linear fog equation. The + initial far distance is 1.
+ GL_FOG_COLOR +: + params + contains four fixed-point or floating-point values that specify + + Cf + , + the fog color. Both fixed-point and floating-point + values are mapped directly. After conversion, all color + components are clamped to the range [0, 1]. The initial + fog color is (0, 0, 0, 0).

Fog blends a fog color with each rasterized pixel + fragment's posttexturing color using a blending factor + f. Factor f + is computed in one of three ways, depending on the fog mode. + Let z + be the distance in eye coordinates from the origin to the + fragment being fogged. The equation for GL_LINEAR + fog is

+ f= + + end-z + end-start + +

The equation for GL_EXP fog is

+ f= + + e + -(density-z) + +

The equation for GL_EXP2 fog is

+ f= + + e + + -(density-z) + 2 + + +

Regardless of the fog mode, f + is clamped to the range [0, 1] after it is computed. Then, + the fragment's red, green, and blue colors, represented by + + Cr + , + are replaced by

+ C'r= + f + + C + r + + + + 1-f + + C + f + +

Fog does not affect a fragment's alpha component.

Errors

GL_INVALID_ENUM is generated if + pname is not an accepted value, or if + pname is + GL_FOG_MODE and + params is not an accepted value.

GL_INVALID_VALUE is generated if + pname is + GL_FOG_DENSITY, and + params is negative.

Copyright

Name

glFrontFace — define front- and back-facing polygons

C Specification

void glFrontFace( GLenum mode);

Parameters

+ mode +: Specifies the orientation of front-facing polygons. + GL_CW and + GL_CCW are accepted. The initial value is + GL_CCW.

Description

In a scene composed entirely of opaque closed surfaces, + back-facing polygons are never visible. Eliminating (culling) these + invisible polygons has the obvious benefit of speeding up the + rendering of the image. To enable and disable culling, call + glEnable and + glDisable + with argument GL_CULL_FACE. + Culling is initially disabled. +

The projection of a polygon to window coordinates is said + to have clockwise winding if an imaginary object following the + path from its first vertex, its second vertex, and so on, to + its last vertex, and finally back to its first vertex, moves in + a clockwise direction about the interior of the polygon. The + polygon's winding is said to be counterclockwise if the + imaginary object following the same path moves in a + counterclockwise direction about the interior of the polygon. + glFrontFace + specifies whether polygons with clockwise winding in window + coordinates, or counterclockwise winding in window coordinates, + are taken to be front-facing. Passing + GL_CCW to mode + selects counterclockwise polygons as front-facing. + GL_CW + selects clockwise polygons as front-facing. By default, + counterclockwise polygons are taken to be front-facing.

Errors

GL_INVALID_ENUM is generated if + mode is not an accepted value.

Copyright

Name

glFrustum — multiply the current matrix by a perspective matrix

C Specification

`void glFrustumf(`	GLfloat `left`,
	GLfloat `right`,
	GLfloat `bottom`,
	GLfloat `top`,
	GLfloat `near`,
	GLfloat `far)`;

`void glFrustumx(`	GLfixed `left`,
	GLfixed `right`,
	GLfixed `bottom`,
	GLfixed `top`,
	GLfixed `near`,
	GLfixed `far)`;

Parameters

+ left, + right +: Specify the coordinates for the left and right + vertical clipping planes.
+ bottom, + top +: Specify the coordinates for the bottom and top + horizontal clipping planes.
+ near, + far +: Specify the distances to the near and far depth + clipping planes. Both distances must be positive.

Description

glFrustum + describes a perspective matrix that produces a perspective + projection. The current matrix (see + glMatrixMode) + is multiplied by this matrix and the result replaces the + current matrix, as if + glMultMatrix + were called with the following matrix as its argument:

+

+ + + + + + + + + + 2 + ⁢ + near + + + + + right + - + left + + + + + + + 0 + + + A + + + 0 + + + + + 0 + + + + + + + 2 + ⁢ + near + + + + + top + - + bottom + + + + + + + B + + + 0 + + + + + 0 + + + 0 + + + C + + + D + + + + + 0 + + + 0 + + + -1 + + + 0 + + + + +

+

+ + + A + = + + + + right + + + left + + + + + right + - + left + + + + +

+

+ + + B + = + + + + top + + + bottom + + + + + top + - + bottom + + + + +

+

+ + + C + = + + - + + + + + far + + + near + + + + + far + - + near + + + + + + +

+

+ + + D + = + + - + + + + + 2 + ⁢ + far + ⁢ + near + + + + + far + - + near + + + + + + +

+

Typically, the matrix mode is + GL_PROJECTION, and + (left, bottom, + -near) and + (right, top, + -near) + specify the points on the near clipping plane that are mapped + to the lower left and upper right corners of the window, + assuming that the eye is located at (0, 0, 0). + -far + specifies the location of the far clipping plane. Both + near and + far must be positive.

Use + glPushMatrix + and + glPopMatrix + to save and restore the current matrix stack.

Notes

Depth buffer precision is affected by the values + specified for near and + far. The greater the ratio of + far to + near + is, the less effective the depth buffer will be at + distinguishing between surfaces that are near each other. If

+ + r + = + farnear + +

roughly + + log2(r) + + bits of depth buffer precision are lost. Because + r approaches infinity as + near approaches 0, + near must never be set to 0.

Errors

+ GL_INVALID_VALUE is generated if + near or far + is not positive, or if + left = right, or + bottom = top, or + near = far. +

Copyright

Name

glGenBuffers — generate buffer object names

C Specification

`void glGenBuffers(`	GLsizei `n`,
	GLuint * `buffers)`;

Parameters

+ n +: Specifies the number of buffer object names to be generated.
+ buffers +: Specifies an array in which the generated + buffer object names are stored.

Description

glGenBuffers returns + n buffer object names in + buffers. There is no guarantee that the names form a + contiguous set of integers; however, it is guaranteed that none of the names + was in use immediately before the call to glGenBuffers.

Buffer object names returned by a call to glGenBuffers + are not returned by subsequent calls, unless they are first deleted with + glDeleteBuffers.

No buffer objects are associated with the returned buffer object names + until they are first bound by calling + glBindBuffer.

Errors

GL_INVALID_VALUE is generated if + n is negative.

Associated Gets

+ glIsBuffer +

Copyright

Name

glGenTextures — generate texture names

C Specification

`void glGenTextures(`	GLsizei `n`,
	GLuint * `textures)`;

Parameters

+ n +: Specifies the number of texture names to be generated.
+ textures +: Specifies an array in which the generated texture + names are stored.

Description

glGenTextures returns + n texture names in + textures. + There is no guarantee that the names form a contiguous set of + integers. However, it is guaranteed that none of the returned + names was in use immediately before the call to + glGenTextures.

The generated textures have no dimensionality; they + assume the dimensionality of the texture target to which they + are first bound (see + glBindTexture).

Texture names returned by a call to + glGenTextures + are not returned by subsequent calls, unless they are first deleted with + glDeleteTextures.

Errors

GL_INVALID_VALUE is generated if + n is negative.

Associated Gets

+ glIsTexture +

Copyright

Name

glGet — return the value or values of a selected parameter

C Specification

`void glGetBooleanv(`	GLenum `pname`,
	GLboolean * `params)`;

`void glGetFixedv(`	GLenum `pname`,
	GLfixed * `params)`;

`void glGetFloatv(`	GLenum `pname`,
	GLfloat * `params)`;

`void glGetIntegerv(`	GLenum `pname`,
	GLint * `params)`;

Parameters

+ pname +: Specifies the parameter value to be returned. The + symbolic constants in the list below are accepted.
+ params +: Returns the value or values of the specified parameter.

Description

+ These commands return values for static state variables in GL. + pname + is a symbolic constant indicating the static state variable to + be returned, and params + is a pointer to an array of the indicated type in which to place the + returned data.

+ If a Get command is issued that returns value types different from the type of the + value being obtained, a type conversion is performed. + If GetBooleanv is called, a floating-point or integer value converts to GL_FALSE + if and only if it is zero (otherwise it converts to GL_TRUE). + If GetIntegerv is called, a boolean value is interpreted as either 1 + or 0, and a floating-point value is rounded to the nearest integer, + unless the value is an RGBA color component, a DepthRange value, a depth buffer clear value, or a normal coordinate. + In these cases, the Get command does a linear mapping that maps 1.0 to the most positive representable + integer value, and -1.0 to the most negative representable integer value. + If GetFloatv is called, a boolean value is interpreted as either 1.0 or 0.0, an integer + is coerced to floating-point. If a value is so large in magnitude that it cannot be represented with + the requested type, then the nearest value representable using the requested type is returned. +

The following symbolic constants are accepted by + pname:

GL_ACTIVE_TEXTURE

+ params returns a single value indicating the active multitexture unit. + The initial value is GL_TEXTURE0. + See glActiveTexture. +

+ GL_ALIASED_POINT_SIZE_RANGE +

+ params + returns two values, + the smallest and largest supported sizes for + aliased points. The range must include 1. + See glPointSize. +

+ GL_ALIASED_LINE_WIDTH_RANGE +

+ params + returns two values, + the smallest and largest supported widths for + aliased lines. The range must include 1. + See glLineWidth. +

+ GL_ALPHA_BITS +

+ params + returns one value, + the number of alpha bitplanes in the + color buffer. +

+ GL_ALPHA_TEST +

+ params returns a single boolean value indicating whether alpha + testing of fragments is enabled. The initial value is GL_FALSE. + See glAlphaFunc. +

+ GL_ALPHA_TEST_FUNC +

+ params + returns one value, + the symbolic name of the alpha test function. + See glAlphaFunc. +

+ GL_ALPHA_TEST_REF +

+ params + returns one value, + the reference value for the alpha test. + An integer value, if requested, is linearly mapped from + the internal floating-point representation such that 1.0 + returns the most positive representable integer value, and -1.0 + returns the most negative representable integer value. + See glAlphaFunc. +

GL_ARRAY_BUFFER_BINDING

+

+ params returns a single value, the name of the buffer object + currently bound to the target GL_ARRAY_BUFFER. If no buffer object + is bound to this target, 0 is returned. The initial value is 0. + See glBindBuffer. +

+ GL_BLEND +

+ params returns a single boolean value indicating whether + blending of fragments is enabled. The initial value is GL_FALSE. + See glBlendFunc and + glLogicOp. +

+ GL_BLEND_DST +

+ params + returns one value, + the symbolic constant identifying the destination blend function. + See glBlendFunc. +

+ GL_BLEND_SRC +

+ params + returns one value, + the symbolic constant identifying the source blend function. + See glBlendFunc. +

+ GL_BLUE_BITS +

+ params + returns one value, + the number of blue bitplanes in the + color buffer. +

GL_CLIENT_ACTIVE_TEXTURE

+ params returns a single value indicating the current + client active multitexture unit. + The initial value is GL_TEXTURE0. + See glClientActiveTexture. +

+ GL_CLIP_PLANEi +

+ params returns a single boolean value indicating whether the + ith user clipping plane is enabled. The initial value is GL_FALSE. + See glClipPlane. +

+ GL_COLOR_ARRAY +

+ params returns a single boolean value indicating whether + the color array is enabled. The initial value is GL_FALSE. + See glColorPointer. +

+ GL_COLOR_ARRAY_BUFFER_BINDING +

+ params + returns one value, + the color array buffer binding. + See glColorPointer. +

+ GL_COLOR_ARRAY_SIZE +

+ params + returns one value, + the number of components per color in the color array. + See glColorPointer. +

+ GL_COLOR_ARRAY_STRIDE +

+ params + returns one value, + the byte offset between consecutive colors in the color array. + See glColorPointer. +

+ GL_COLOR_ARRAY_TYPE +

+ params + returns one value, + returns the data type of each component in the color array. + See glColorPointer. +

+ GL_COLOR_CLEAR_VALUE +

+ params + returns four values: + the red, green, + blue, and alpha + values used to clear the color buffers. + See glClearColor. +

+ GL_COLOR_LOGIC_OP +

+ params returns a single boolean value indicating whether + logical operation on color values is enabled. The initial value is GL_FALSE. + See glLogicOp. +

+ GL_COLOR_MATERIAL +

+ params returns a single boolean value indicating whether + color material tracking is enabled. The initial value is GL_FALSE. + See glMaterial. +

+ GL_COLOR_WRITEMASK +

+ params + returns four boolean values: + the red, green, + blue, and alpha + write enables for the color buffers. + See glColorMask. +

+ GL_COMPRESSED_TEXTURE_FORMATS +

+ params returns + GL_NUM_COMPRESSED_TEXTURE_FORMATS + values, the supported compressed texture formats. + See + glCompressedTexImage2D + and + glCompressedTexSubImage2D. +

GL_CULL_FACE

+ params returns a single boolean value indicating whether polygon culling + is enabled. The initial value is GL_FALSE. + See glCullFace. +

GL_CULL_FACE_MODE

+ params returns one value, + a symbolic constant indicating which polygon faces are to be + culled. The initial value is GL_BACK. + See glCullFace. +

GL_CURRENT_COLOR

+ params returns four values: + the red, green, blue, and alpha values of the current color. + Integer values, + if requested, + are linearly mapped from the internal floating-point representation such + that 1.0 returns the most positive representable integer value, + and + + + -1.0 + + returns the most negative representable integer value. + The initial value is (1, 1, 1, 1). + See glColor. +

GL_CURRENT_NORMAL

+ params returns three values: + the x, y, and z values of the current normal. + Integer values, + if requested, + are linearly mapped from the internal floating-point representation such + that 1.0 returns the most positive representable integer value, + and + + + -1.0 + + returns the most negative representable integer value. + The initial value is (0, 0, 1). + See glNormal. +

GL_CURRENT_TEXTURE_COORDS

+ params returns four values: + the s, t, r, and q current texture + coordinates. The initial value is (0, 0, 0, 1). + See glMultiTexCoord. +

+ GL_DEPTH_BITS +

params + returns one value, the number of bitplanes in the depth + buffer.

+ GL_DEPTH_CLEAR_VALUE +

+ params + returns one value, + the value that is used to clear the depth buffer. + See glClearDepth. +

+ GL_DEPTH_FUNC +

+ params + returns one value, + the symbolic name of the depth comparision function. + See glDepthFunc. +

+ GL_DEPTH_RANGE +

+ params + returns two values: + the near and far mapping limits for the depth buffer. + See glDepthRange. +

+ GL_DEPTH_TEST +

+ params returns a single boolean value indicating whether depth testing + of fragments is enabled. The initial value is GL_FALSE. + See glDepthFunc and glDepthRange. +

+ GL_DEPTH_WRITEMASK +

+ params + returns a single boolean value + indicating if the depth buffer is enabled for writing. + See glDepthMask. +

GL_ELEMENT_ARRAY_BUFFER_BINDING

+

+ params returns a single value, the name of the buffer object + currently bound to the target GL_ELEMENT_ARRAY_BUFFER. If no buffer object + is bound to this target, 0 is returned. The initial value is 0. + See glBindBuffer. +

+ GL_FOG +

+ params returns a single boolean value indicating whether fog + is enabled. The initial value is GL_FALSE. + See glFog. +

+ GL_FOG_COLOR +

+ params + returns four values: + the red, green, + blue, and alpha + components of the fog color. + See glFog. +

+ GL_FOG_DENSITY +

+ params + returns one value, + the fog density parameter. + See glFog. +

+ GL_FOG_END +

+ params + returns one value, + the end factor for the linear fog equation. + See glFog. +

+ GL_FOG_HINT +

+ params + returns one value, + a symbolic constant indicating the mode of the fog hint. + See glHint. +

+ GL_FOG_MODE +

+ params + returns one value, + a symbolic constant indicating which fog equation is selected. + See glFog. +

+ GL_FOG_START +

+ params + returns one value, + the start factor for the linear fog equation. + See glFog. +

+ GL_FRONT_FACE +

+ params + returns one value, + a symbolic constant indicating whether clockwise or + counterclockwise polygon winding is treated as front-facing. + See glFrontFace. +

+ GL_GREEN_BITS +

params + returns one value, the number of green bitplanes in the + color buffer.

+ GL_IMPLEMENTATION_COLOR_READ_FORMAT_OES +

params + returns one value, the preferred format for pixel read back. See + glReadPixels.

+ GL_IMPLEMENTATION_COLOR_READ_TYPE_OES +

params + returns one value, the preferred type for pixel read back. See + glReadPixels.

+ GL_LIGHT_MODEL_AMBIENT +

+ params + returns four values: + the red, green, + blue, and alpha + components of the ambient intensity of the entire scene. + See glLightModel. +

+ GL_LIGHT_MODEL_TWO_SIDE +

+ params + returns a single boolean value + indicating whether separate materials are used to compute + lighting for front and back facing polygons. + See glLightModel. +

+ GL_LIGHTi +

+ params returns a single boolean value indicating whether the + ith light is enabled. The initial value is GL_FALSE. + See glLight and + glLightModel. +

+ GL_LIGHTING +

+ params returns a single boolean value indicating whether lighting + is enabled. The initial value is GL_FALSE. + See glLight, + glLightModel, and + glMaterial. +

+ GL_LINE_SMOOTH +

+ params returns a single boolean value indicating whether line + antialiasing is enabled. The initial value is GL_FALSE. + See glLineWidth. +

+ GL_LINE_SMOOTH_HINT +

+ params + returns one value, + a symbolic constant indicating the mode of the line antialiasing hint. + See glHint. +

+ GL_LINE_WIDTH +

+ params + returns one value, + the line width as specified with + glLineWidth. +

+ GL_LOGIC_OP_MODE +

+ params + returns one value, + a symbolic constant indicating the selected logic operation mode. + See glLogicOp. +

+ GL_MATRIX_MODE +

+ params + returns one value, + a symbolic constant indicating which matrix stack is currently the + target of all matrix operations. + See glMatrixMode. +

+ GL_MAX_CLIP_PLANES +

+ params + returns one value, + the maximum number of application defined clipping planes. + The value must be at least 6. + See glClipPlane. +

+ GL_MAX_LIGHTS +

params + returns one value, the maximum number of lights. The + value must be at least 8. See + glLight.

+ GL_MAX_MODELVIEW_STACK_DEPTH +

+ params + returns one value, + the maximum supported depth of the + modelview matrix stack. + The value must be at least 16. + See glPushMatrix. +

+ GL_MAX_PROJECTION_STACK_DEPTH +

params + returns one value, the maximum supported depth of the + projection matrix stack. The value must be at least 2. + See + glPushMatrix.

+ GL_MAX_TEXTURE_SIZE +

params + returns one value. The value gives a rough estimate of the largest + texture that the GL can handle. The value must be at least 64. + See + glTexImage2D, + glCompressedTexImage2D, and + glCopyTexImage2D.

+ GL_MAX_TEXTURE_STACK_DEPTH +

params + returns one value, the maximum supported depth of the + texture matrix stack. The value must be at least 2. See + glPushMatrix.

+ GL_MAX_TEXTURE_UNITS +

params + returns a single value indicating the number of texture + units supported. The value must be at least 1. See + glActiveTexture, + glClientActiveTexture + and + glMultiTexCoord.

+ GL_MAX_VIEWPORT_DIMS +

params + returns two values: the maximum supported width and + height of the viewport. These must be at least as large + as the visible dimensions of the display being rendered + to. See + glViewport.

+ GL_MODELVIEW_MATRIX +

+ params + returns sixteen values: + the modelview matrix on the top of the modelview matrix stack. + See glPushMatrix. +

+ GL_MODELVIEW_STACK_DEPTH +

+ params + returns one value, + the number of matrices on the modelview matrix stack. + See glPushMatrix. +

+ GL_MULTISAMPLE +

+ params returns a single boolean value indicating whether multisampling + is enabled. The initial value is GL_TRUE. +

+ GL_NORMAL_ARRAY +

+ params returns a single boolean value indicating whether + the normal array is enabled. The initial value is GL_FALSE. + See glNormalPointer. +

+ GL_NORMAL_ARRAY_BUFFER_BINDING +

+ params + returns one value, + the normal array buffer binding. + See glNormalPointer. +

+ GL_NORMAL_ARRAY_STRIDE +

+ params + returns one value, + the byte offset between consective normals in the normal array. + See glNormalPointer. +

+ GL_NORMAL_ARRAY_TYPE +

+ params + returns one value, + the data type of each normal in the normal array. + See glNormalPointer. +

+ GL_NORMALIZE +

+ params returns a single boolean value indicating whether + normalization of normals is enabled. The initial value is GL_FALSE. + See glNormal. +

+ GL_NUM_COMPRESSED_TEXTURE_FORMATS +

+ params + returns one value, + the number of supportex compressed + texture formats. + The value must be at least 10. + See + glCompressedTexImage2D + and + glCompressedTexSubImage2D.

+ GL_PACK_ALIGNMENT +

+ params + returns one value, + the byte alignment used for writing pixel data to memory. + See glPixelStorei. +

+ GL_PERSPECTIVE_CORRECTION_HINT +

+ params + returns one value, + a symbolic constant indicating the mode of the perspective correction hint. + See glHint. +

+ GL_POINT_DISTANCE_ATTENUATION +

+ params + returns three values, the distance attenuation function coefficients a, + b, and c. The initial value is (1, 0, 0). See + glPointParameter. +

+ GL_POINT_FADE_THRESHOLD_SIZE +

+ params + returns one value, the point fade threshold. The initial value is 1. See + glPointParameter. +

+ GL_POINT_SIZE +

+ params + returns one value, + the point size as specified by + glPointSize. +

+ GL_POINT_SIZE_ARRAY_BUFFER_BINDING_OES +

+ params + returns one value, + the point size array buffer binding. + See glPointSizePointerOES. +

+ GL_POINT_SIZE_ARRAY_OES +

+ params returns a single boolean value indicating whether the point + size array is enabled. The initial value is GL_FALSE. + See glPointSizePointerOES. +

+ GL_POINT_SIZE_ARRAY_STRIDE_OES +

+ params + returns one value, + the byte offset between consecutive point sizes in the point size array. + See glPointSizePointerOES. +

+ GL_POINT_SIZE_ARRAY_TYPE_OES +

+ params + returns one value, + the data type of each point size in the point array. + See glPointSizePointerOES. +

+ GL_POINT_SIZE_MAX +

+ params + returns one value, + the upper bound to which the derived point size is + clamped. The initial value is the maximum of the implementation dependent max + aliased and smooth point sizes. See + glPointParameter. +

+ GL_POINT_SIZE_MIN +

+ params + returns one value, + the lower bound to which the derived point size is + clamped. The initial value is 0. See + glPointParameter. +

+ GL_POINT_SMOOTH +

+ params returns a single boolean value indicating whether point + antialiasing is enabled. The initial value is GL_FALSE. + See glPointSize. +

+ GL_POINT_SMOOTH_HINT +

+ params + returns one value, + a symbolic constant indicating the mode of the point antialiasing hint. + See glHint. +

+ GL_POINT_SPRITE_OES +

+ params returns a single boolean value indicating whether point + sprites are enabled. The initial value is GL_FALSE. + See glTexEnv. +

+ GL_POLYGON_OFFSET_FACTOR +

+ params + returns one value, + the scaling factor used to determine the variable offset that is added + to the depth value of each fragment generated when a polygon is rasterized. + See glPolygonOffset. +

+ GL_POLYGON_OFFSET_FILL +

+ params returns a single boolean value indicating whether polygon offset + is enabled for polygons in fill mode. The initial value is GL_FALSE. + See glPolygonOffset. +

+ GL_POLYGON_OFFSET_UNITS +

+ params + returns one value. + This value is multiplied by an implementation-specific value and + then added to the depth value of each fragment generated when a + polygon is rasterized. + See glPolygonOffset. +

+ GL_PROJECTION_MATRIX +

+ params + returns sixteen values: + the projection matrix on the top of the projection matrix stack. + See glPushMatrix. +

+ GL_PROJECTION_STACK_DEPTH +

+ params + returns one value, + the number of matrices on the projection matrix stack. + See glPushMatrix. +

+ GL_RED_BITS +

+ params + returns one value, + the number of red bitplanes in each color buffer. +

+ GL_RESCALE_NORMAL +

+ params returns a single boolean value indicating whether + rescaling of normals is enabled. The initial value is GL_FALSE. + See glNormal. +

GL_SAMPLE_ALPHA_TO_COVERAGE

+ params returns a single boolean value indicating if the + fragment coverage value should be ANDed with a temporary coverage value based + on the fragment's alpha value. The initial value is GL_FALSE. + See glSampleCoverage. +

GL_SAMPLE_ALPHA_TO_ONE

+ params returns a single boolean value indicating if the + fragment's alpha value should be replaced by the maximum representable alpha value + after coverage determination. The initial value is GL_FALSE. + See glSampleCoverage. +

GL_SAMPLE_BUFFERS

+ params returns a single integer value indicating the number of sample buffers + associated with the currently bound framebuffer. + See glSampleCoverage. +

GL_SAMPLE_COVERAGE

+ params returns a single boolean value indicating if the + fragment coverage value should be ANDed with a temporary coverage value based + on the current sample coverage value. The initial value is GL_FALSE. + See glSampleCoverage. +

GL_SAMPLE_COVERAGE_INVERT

+ params returns a single boolean value indicating if the temporary + coverage value should be inverted. + See glSampleCoverage. +

GL_SAMPLE_COVERAGE_VALUE

+ params returns a single positive floating-point value indicating the + current sample coverage value. + See glSampleCoverage. +

GL_SAMPLES

+ params returns a single integer value + indicating the coverage mask size of the currently bound framebuffer. + See glSampleCoverage. +

+ GL_SCISSOR_BOX +

+ params + returns four values: + the x and y window coordinates of the scissor box, + followed by its width and height. + See glScissor. +

GL_SCISSOR_TEST

+ params returns a single boolean value indicating whether scissoring is + enabled. The initial value is GL_FALSE. + See glScissor. +

+ GL_SHADE_MODEL +

+ params + returns one value, + a symbolic constant indicating whether the shading mode is + flat or smooth. + See glShadeModel. +

+ GL_SMOOTH_LINE_WIDTH_RANGE +

+ params + + returns two values, the smallest and largest supported + widths for antialiased lines. The range must include 1. See + glLineWidth.

+ GL_SMOOTH_POINT_SIZE_RANGE +

params + returns two values, the smallest and largest supported + widths for antialiased points. The range must include 1. See + glPointSize.

+ GL_STENCIL_BITS +

params + returns one value, the number of bitplanes in the stencil + buffer.

+ GL_STENCIL_CLEAR_VALUE +

+ params + returns one value, + the index to which the stencil bitplanes are cleared. + See glClearStencil. +

+ GL_STENCIL_FAIL +

+ params + returns one value, + a symbolic constant indicating what action is taken when the stencil test fails. + See glStencilOp. +

+ GL_STENCIL_FUNC +

+ params + returns one value, + a symbolic constant indicating what function is used to compare the + stencil reference value with the stencil buffer value. + See glStencilFunc. +

+ GL_STENCIL_PASS_DEPTH_FAIL +

+ params + returns one value, + a symbolic constant indicating what action is taken when the stencil + test passes, but the depth test fails. + See glStencilOp. +

+ GL_STENCIL_PASS_DEPTH_PASS +

+ params + returns one value, + a symbolic constant indicating what action is taken when the stencil + test passes, and the depth test passes. + See glStencilOp. +

+ GL_STENCIL_REF +

+ params + returns one value, + the reference value that is compared with the contents of the stencil buffer. + See glStencilFunc. +

GL_STENCIL_TEST

+ params returns a single boolean value indicating whether stencil testing + of fragments is enabled. The initial value is GL_FALSE. + See glStencilFunc and glStencilOp. +

+ GL_STENCIL_VALUE_MASK +

+ params + returns one value, + the mask that is used to mask both the stencil reference value and the + stencil buffer value before they are compared. + See glStencilFunc. +

+ GL_STENCIL_WRITEMASK +

+ params + returns one value, + the mask that controls writing of the stencil bitplanes. + See glStencilMask. +

+ GL_SUBPIXEL_BITS +

params + returns one value, an estimate of the number of bits of + subpixel resolution that are used to position rasterized + geometry in window coordinates. The value must be at + least 4.

GL_TEXTURE_2D

+ params returns a single boolean value indicating whether 2D + texturing is enabled. The initial value is GL_FALSE. + See glTexImage2D. +

+ GL_TEXTURE_BINDING_2D +

+ params + returns one value, + the name of the texture currently bound to the target GL_TEXTURE_2D. + See glBindTexture. +

+ GL_TEXTURE_COORD_ARRAY +

+ params returns a single boolean value indicating whether + the texture coordinate array is enabled. The initial value is GL_FALSE. + See glTexCoordPointer. +

+ GL_TEXTURE_COORD_ARRAY_BUFFER_BINDING +

+ params + returns one value, + the texture coordinate array buffer binding. + See glTexCoordPointer. +

+ GL_TEXTURE_COORD_ARRAY_SIZE +

+ params + returns one value, + the number of coordinates per element in the texture coordinate array. + See glTexCoordPointer. +

+ GL_TEXTURE_COORD_ARRAY_STRIDE +

+ params + returns one value, + the byte offset between consecutive elements in the texture coordinate array. + See glTexCoordPointer. +

+ GL_TEXTURE_COORD_ARRAY_TYPE +

+ params + returns one value, + returns the data type of each coordinate in the texture coordinate array. + See glTexCoordPointer. +

+ GL_TEXTURE_MATRIX +

+ params + returns sixteen values: + the texture matrix on the top of the texture matrix stack. + See glPushMatrix. +

+ GL_TEXTURE_STACK_DEPTH +

+ params + returns one value, + the number of matrices on the texture matrix stack. + See glBindTexture. +

+ GL_UNPACK_ALIGNMENT +

+ params + returns one value, + the byte alignment used for reading pixel data from memory. + See glPixelStorei. +

+ GL_VIEWPORT +

+ params + returns four values:, + the x and y window coordinates of the viewport, + followed by its width and height. + See glViewport. +

+ GL_VERTEX_ARRAY +

+ params returns a single boolean value indicating whether + the vertex array is enabled. The initial value is GL_FALSE. + See glVertexPointer. +

+ GL_VERTEX_ARRAY_BUFFER_BINDING +

+ params + returns one value, + the vertex array buffer binding. + See glVertexPointer. +

+ GL_VERTEX_ARRAY_SIZE +

+ params + returns one value, + number of coordinates per vertex in the vertex array. + See glVertexPointer. +

+ GL_VERTEX_ARRAY_STRIDE +

+ params + returns one value, + the byte offset between consecutive vertexes in the vertex array. + See glVertexPointer. +

+ GL_VERTEX_ARRAY_TYPE +

+ params + returns one value, + returns the data type of each coordinate in the vertex array. + See glVertexPointer. +

Notes

+ GL_POINT_SIZE_ARRAY_BUFFER_BINDING_OES, + GL_POINT_SIZE_ARRAY_STRIDE_OES, and + GL_POINT_SIZE_ARRAY_TYPE_OES are only accepted + if the OpenGL ES version number is 1.1 or greater. +

Errors

GL_INVALID_ENUM is generated if + pname is not an accepted value.

Copyright

Name

glGetBufferParameteriv — return parameters of a buffer object

C Specification

`void glGetBufferParameteriv(`	GLenum `target`,
	GLenum `pname`,
	GLint * `params)`;

Parameters

+ target +: + Specifies the target buffer object. + The symbolic constant must be GL_ARRAY_BUFFER or + GL_ELEMENT_ARRAY_BUFFER. +
+ pname +: + Specifies the symbolic name of a buffer object parameter. + Accepted values are + GL_BUFFER_SIZE or GL_BUFFER_USAGE. +
+ params +: Returns the requested parameter.

Description

+ glGetBufferParameteriv returns in params a selected parameter of the buffer object + specified by target. +

+ pname names a specific buffer object parameter, as follows: +

GL_BUFFER_SIZE: + params returns the size of the buffer object, measured in bytes. + The initial value is 0. +
GL_BUFFER_USAGE: + params returns the buffer object's usage pattern. The initial value is + GL_STATIC_DRAW. +

Notes

+ If an error is generated, + no change is made to the contents of params. +

Errors

+ GL_INVALID_ENUM is generated if target or pname is not an + accepted value. +

+ GL_INVALID_OPERATION is generated if the reserved buffer object name 0 is bound to target. +

Copyright

Name

glGetClipPlane — return the coefficients of the specified clipping + plane

C Specification

`void glGetClipPlanef(`	GLenum `plane`,
	GLfloat *`equation)`;

`void glGetClipPlanex(`	GLenum `plane`,
	GLfixed *`equation)`;

Parameters

plane: Specifies a clipping plane. The number of clipping planes + depends on the implementation, but at least six clipping planes are + supported. Symbolic names of the form + GL_CLIP_PLANE i, where + i is an integer between 0 and + GL_MAX_CLIP_PLANES + + + -1 + , are accepted.
equation: Returns four fixed-point or floating-point values that are the + coefficients of the plane equation of plane + in eye coordinates in the order p1, + p2, p3, and + p4. The initial value is (0, 0, 0, 0).

Description

glGetClipPlane returns in + equation the four coefficients of the plane + equation for plane. The coefficients are in eye + coordinates and are returned in the order p1, + p2, p3, and + p4.

Notes

It is always the case that + + + GL_CLIP_PLANEi + + = + + + + GL_CLIP_PLANE0 + + + + + i + + . +

If an error is generated, no change is made to the contents of + equation.

Errors

GL_INVALID_ENUM is generated if + plane is not an accepted value.

Copyright

Name

glGetError — return error information

C Specification

GLenum glGetError( void);

Description

+ glGetError + returns the value of the error flag. Each detectable error is + assigned a numeric code and symbolic name. When an error + occurs, the error flag is set to the appropriate error code + value. No other errors are recorded until + glGetError + is called, the error code is returned, and the flag is reset to + GL_NO_ERROR. If a call to + glGetError + returns GL_NO_ERROR, + there has been no detectable error since the last call to + glGetError, + or since the GL was initialized.

To allow for distributed implementations, there may be + several error flags. If any single error flag has recorded an + error, the value of that flag is returned and that flag is + reset to GL_NO_ERROR when + glGetError + is called. If more than one flag has recorded an error, + glGetError + returns and clears an arbitrary error flag value. Thus, + glGetError + should always be called in a loop, until it returns + GL_NO_ERROR, + if all error flags are to be reset.

Initially, all error flags are set to + GL_NO_ERROR.

The following errors are currently defined:

+ GL_NO_ERROR +: No error has been recorded. The value of this + symbolic constant is guaranteed to be 0.
+ GL_INVALID_ENUM +: An unacceptable value is specified for an + enumerated argument. The offending command is ignored, + and has no other side effect than to set the error + flag.
+ GL_INVALID_VALUE +: A numeric argument is out of range. The offending + command is ignored, and has no other side effect than to + set the error flag.
+ GL_INVALID_OPERATION +: The specified operation is not allowed in the + current state. The offending command is ignored, and has + no other side effect than to set the error flag.
+ GL_STACK_OVERFLOW +: This command would cause a stack overflow. The + offending command is ignored, and has no other side + effect than to set the error flag.
+ GL_STACK_UNDERFLOW +: This command would cause a stack underflow. The + offending command is ignored, and has no other side + effect than to set the error flag.
+ GL_OUT_OF_MEMORY +: There is not enough memory left to execute the + command. The state of the GL is undefined, except for the + state of the error flags, after this error is + recorded.

When an error flag is set, results of a GL operation are + undefined only if GL_OUT_OF_MEMORY + has occurred. In all other cases, the command generating the + error is ignored and has no effect on the GL state or frame + buffer contents. If the generating command returns a value, it + returns 0. If glGetError + itself generates an error, it returns 0.

Copyright

Name

glGetLight — return light source parameter values

C Specification

`void glGetLightfv(`	GLenum `light`,
	GLenum `pname`,
	GLfloat * `params)`;

`void glGetLightxv(`	GLenum `light`,
	GLenum `pname`,
	GLfixed * `params)`;

Parameters

+ light +: + Specifies a light source. The number of possible + lights depends on the implementation, but at least + eight lights are supported. They + are identified by symbolic names of the form + + GL_LIGHTi where + 0<i< + GL_MAX_LIGHTS + +
+ pname +: + Specifies a light source parameter for light. + Accepted symbolic names are + GL_AMBIENT, + GL_DIFFUSE, + GL_SPECULAR, + GL_POSITION, + GL_SPOT_DIRECTION, + GL_SPOT_EXPONENT, + GL_SPOT_CUTOFF, + GL_CONSTANT_ATTENUATION, + GL_LINEAR_ATTENUATION, and + GL_QUADRATIC_ATTENUATION. +
+ params +: + Returns the requested data. +

Description

+ glGetLight + returns in params the value or values of a light + source parameter. + light names the light and is a symbolic + name of the form + + GL_LIGHTi for + 0<i< + GL_MAX_LIGHTS + + where GL_MAX_LIGHTS is an + implementation dependent constant that + is greater than or equal to eight. + pname specifies one of + ten light source parameters, again by symbolic name. +

The ten light parameters are defined:

+ GL_AMBIENT +: + params + returns four fixed-point or floating-point values that + specify the ambient RGBA intensity of the light. Both + fixed-point and floating-point values are mapped + directly. Neither fixed-point nor floating-point values + are clamped. + The initial ambient light intensity is (0, 0, 0, 1). +
+ GL_DIFFUSE +: + params + returns four fixed-point or floating-point values that + specify the diffuse RGBA intensity of the light. Both + fixed-point and floating-point values are mapped + directly. Neither fixed-point nor floating-point values + are clamped. + The initial value for GL_LIGHT0 + is (1, 1, 1, 1). + For other lights, the initial value is (0, 0, 0, 0). +
+ GL_SPECULAR +: + params + returns four fixed-point or floating-point values that + specify the specular RGBA intensity of the light. Both + fixed-point and floating-point values are mapped + directly. Neither fixed-point nor floating-point values + are clamped. + The initial value for GL_LIGHT0 + is (1, 1, 1, 1). + For other lights, the initial value is (0, 0, 0, 0). +
GL_POSITION: + params returns four fixed-point or floating-point values representing the + position of the light source. + Both fixed-point and floating-point values are mapped + directly. + The returned values are those maintained in eye coordinates. + They will not be equal to the values specified using glLight, + unless the modelview matrix was identity at the time glLight was + called. The initial value is (0, 0, 1, 0). +
+ GL_SPOT_DIRECTION +: + params + returns three fixed-point or floating-point values that + specify the direction of the light in homogeneous object + coordinates. Both fixed-point and floating-point values + are mapped directly. Neither fixed-point nor + floating-point values are clamped. + The initial direction is (0, 0, -1). +
+ GL_SPOT_EXPONENT +: + params + returns a single fixed-point or floating-point value that + specifies the intensity distribution of the light. + Fixed-point and floating-point values are mapped + directly. Only values in the range [0, 128] are + accepted. + The initial spot exponent is 0. +
+ GL_SPOT_CUTOFF +: + params + returns a single fixed-point or floating-point value that + specifies the maximum spread angle of a light source. + Fixed-point and floating-point values are mapped + directly. Only values in the range [0, 90] and the special + value 180 are accepted. If the angle between the + direction of the light and the direction from the light + to the vertex being lighted is greater than the spot + cutoff angle, the light is completely masked. + Otherwise, its intensity is controlled by the spot + exponent and the attenuation factors. The initial spot + cutoff is 180. +
+ GL_CONSTANT_ATTENUATION, + GL_LINEAR_ATTENUATION, + GL_QUADRATIC_ATTENUATION +: params + returns a single fixed-point or floating-point value that + specifies one of the three light attenuation factors. + Fixed-point and floating-point values are mapped + directly. Only nonnegative values are accepted. If the + light is positional, rather than directional, its + intensity is attenuated by the reciprocal of the sum of + the constant factor, the linear factor times the distance + between the light and the vertex being lighted, and the + quadratic factor times the square of the same distance. + The initial attenuation factors are (1, 0, 0).

Notes

+ It is always the case that + + GL_LIGHTi= + GL_LIGHT0+i. + +

+ If an error is generated, no change is made to the contents + of params. +

Errors

+ GL_INVALID_ENUM is generated if + light or pname + is not an accepted value. +

Copyright

Name

glGetMaterial — return material parameters values

C Specification

`void glGetMaterialfv(`	GLenum `face`,
	GLenum `pname`,
	GLfloat * `params)`;

`void glGetMaterialxv(`	GLenum `face`,
	GLenum `pname`,
	GLfixed * `params)`;

Parameters

+ face +: + Specifies which of the two materials is being + queried. + GL_FRONT + or + GL_BACK are accepted, + representing the front and back materials, respectively. +
+ pname +: + Specifies the material parameter to return. + Accepted symbolic names are + GL_AMBIENT, + GL_DIFFUSE, + GL_SPECULAR, + GL_EMISSION, and + GL_SHININESS. +
+ params +: + Returns the requested data. +

Description

+ glGetMaterial + returns in params the value or values of + parameter pname of material face. +

Five parameters are defined:

+ GL_AMBIENT +: + params + returns four fixed-point or floating-point values that + specify the ambient RGBA reflectance of the material. + The values are not clamped. The initial ambient reflectance + + is (0.2, 0.2, 0.2, 1.0). +
+ GL_DIFFUSE +: + params + returns four fixed-point or floating-point values that + specify the diffuse RGBA reflectance of the material. + The values are not clamped. The initial diffuse reflectance + + is (0.8, 0.8, 0.8, 1.0). +
+ GL_SPECULAR +: + params + returns four fixed-point or floating-point values that + specify the specular RGBA reflectance of the material. + The values are not clamped. The initial specular reflectance + + is (0, 0, 0, 1). +
+ GL_EMISSION +: + params + returns four fixed-point or floating-point values that + specify the RGBA emitted light intensity of the material. + The values are not clamped. The initial emission intensity + + is (0, 0, 0, 1). +
+ GL_SHININESS +: + params + returns a single fixed-point or floating-point value that + specifies the RGBA specular exponent of the material. + The initial specular exponent + + is 0. +

Notes

+ If an error is generated, no change is made to the contents + of params. +

+ In OpenGL ES there is only one material shared by the front and back. + Therefore querying + GL_FRONT + and querying + GL_BACK + will always return the + same value. +

Errors

+ GL_INVALID_ENUM is generated if + face or pname + is not an accepted value. +

Copyright

Name

glGetPointerv — return the address of the specified pointer

C Specification

`void glGetPointerv(`	GLenum `pname`,
	GLvoid ** `params)`;

Parameters

+ pname +: + Specifies the array or buffer pointer to be returned. + Accepted symbolic names are + GL_COLOR_ARRAY_POINTER, + + GL_NORMAL_ARRAY_POINTER, + GL_POINT_SIZE_ARRAY_POINTER_OES, + GL_TEXTURE_COORD_ARRAY_POINTER, and + GL_VERTEX_ARRAY_POINTER. + +
+ params +: + Returns the pointer value specified by pname. +

Description

+ glGetPointerv + returns pointer information. + pname is a + symbolic constant indicating the pointer to be returned, and + params is a pointer to a + location in which to place the returned data. +

+ Querying the GL_TEXTURE_COORD_ARRAY_POINTER returns the value for + the active client texture unit. +

+ If a non-zero + named buffer object was bound to the GL_ARRAY_BUFFER target + (see + glBindBuffer) + when the desired pointer was previously specified, the pointer + returned is a byte offset into the buffer object's data store. +

Notes

+ glGetPointerv is only supported + if the OpenGL ES version number is 1.1 or greater. +

+ The pointers are all client-side state. +

+ The initial value for each pointer is 0. +

Errors

+ GL_INVALID_ENUM is generated if + pname is not an accepted value. +

Copyright

Name

glGetString — return a string describing the current GL + connection

C Specification

const GLubyte * glGetString( GLenum name);

Parameters

+ name +: Specifies a symbolic constant, one of + GL_VENDOR, + GL_RENDERER, + GL_VERSION, or + GL_EXTENSIONS.

Description

glGetString + returns a pointer to a static string describing some aspect of + the current GL connection. name + can be one of the following:

+ GL_VENDOR +: Returns the company responsible for this GL + implementation. This name does not change from release to + release.
+ GL_RENDERER +: Returns the name of the renderer. This name is + typically specific to a particular configuration of a + hardware platform. It does not change from release to + release.
+ GL_VERSION +: Returns a version or release number.
+ GL_EXTENSIONS +: Returns a space-separated list of supported + extensions to GL.

Because the GL does not include queries for the + performance characteristics of an implementation, some + applications are written to recognize known platforms and + modify their GL usage based on known performance + characteristics of these platforms. Strings + GL_VENDOR and + GL_RENDERER + together uniquely specify a platform. They do not change from + release to release and should be used by platform-recognition + algorithms.

Some applications want to make use of features that are + not part of the standard GL. These features may be implemented + as extensions to the standard GL. The GL_EXTENSIONS + string is a space-separated list of supported GL extensions. + (Extension names never contain a space character.)

The GL_VERSION string identifies both the version number + and the profile. The form of the string is "OpenGL ES-<profile> + <major>.<minor>", where <profile> is either "CM" + (Common) or "CL" (Common-Lite), and <major> and <minor> are + integers. OpenGL ES 1.0 and OpenGL ES 1.1 will both have <major> of 1 but + 0 or 1 for <minor>, respectively.

All strings are null-terminated.

Notes

If an error is generated, glGetString + returns NULL.

The client and server may support different versions or + extensions. glGetString + always returns a compatible version number or list of + extensions. The release number always describes the + server.

Errors

GL_INVALID_ENUM is generated if + name is not an accepted value.

Copyright

Name

glGetTexEnv — return texture environment parameters

C Specification

`void glGetTexEnvfv(`	GLenum `target`,
	GLenum `pname`,
	GLfloat * `params)`;

`void glGetTexEnviv(`	GLenum `target`,
	GLenum `pname`,
	GLint * `params)`;

`void glGetTexEnvxv(`	GLenum `target`,
	GLenum `pname`,
	GLfixed * `params)`;

Parameters

target: + Specifies a texture environment. May be + GL_TEXTURE_ENV or + GL_POINT_SPRITE_OES. +
pname: + Specifies the symbolic name of a texture environment parameter. + Accepted values are GL_TEXTURE_ENV_MODE, + GL_TEXTURE_ENV_COLOR, + GL_COMBINE_RGB, + GL_COMBINE_ALPHA, + GL_SRC0_RGB, + GL_SRC1_RGB, + GL_SRC2_RGB, + GL_SRC0_ALPHA, + GL_SRC1_ALPHA, + GL_SRC2_ALPHA, + GL_OPERAND0_RGB, + GL_OPERAND1_RGB, + GL_OPERAND2_RGB, + GL_OPERAND0_ALPHA, + GL_OPERAND1_ALPHA, + GL_OPERAND2_ALPHA, + GL_RGB_SCALE, + GL_ALPHA_SCALE, or + GL_COORD_REPLACE_OES. +
params: + Returns the requested data. +

Description

+ glGetTexEnv returns in params selected values of a texture environment that + was specified with glTexEnv. + target specifies a texture environment. +

+ When target is GL_POINT_SPRITE_OES, + pname must be GL_COORD_REPLACE_OES. + When target is + GL_TEXTURE_ENV, pname can be GL_TEXTURE_ENV_MODE, + GL_TEXTURE_ENV_COLOR, GL_COMBINE_RGB, GL_COMBINE_ALPHA, + GL_RGB_SCALE, GL_ALPHA_SCALE, + GL_OPERAND0_RGB, GL_OPERAND1_RGB, GL_OPERAND2_RGB, + GL_OPERAND0_ALPHA, GL_OPERAND1_ALPHA, GL_OPERAND2_ALPHA, + GL_SRC0_RGB, GL_SRC1_RGB, GL_SRC2_RGB, + GL_SRC0_ALPHA, GL_SRC1_ALPHA, or GL_SRC2_ALPHA. +

+ pname names a specific texture environment parameter, as follows: +

GL_TEXTURE_ENV_MODE: + params returns the single-valued texture environment mode, + a symbolic constant. The initial value is GL_MODULATE. +
GL_TEXTURE_ENV_COLOR: + params returns four integer or floating-point values that are the + texture environment color. + Integer values, + when requested, + are linearly mapped from the internal floating-point representation + such that 1.0 maps to the most positive representable integer, + and + + + -1.0 + + maps to the most negative representable integer. The initial + value is (0, 0, 0, 0). +
GL_COMBINE_RGB: + params returns a single symbolic constant value representing the current + RGB combine mode. The initial value is GL_MODULATE. +
GL_COMBINE_ALPHA: + params returns a single symbolic constant value representing the current + alpha combine mode. The initial value is GL_MODULATE. +
GL_SRC0_RGB: + params returns a single symbolic constant value representing the texture + combiner zero's RGB source. The initial value is GL_TEXTURE. +
GL_SRC1_RGB: + params returns a single symbolic constant value representing the texture + combiner one's RGB source. The initial value is GL_PREVIOUS. +
GL_SRC2_RGB: + params returns a single symbolic constant value representing the texture + combiner two's RGB source. The initial value is GL_CONSTANT. +
GL_SRC0_ALPHA: + params returns a single symbolic constant value representing the texture + combiner zero's alpha source. The initial value is GL_TEXTURE. +
GL_SRC1_ALPHA: + params returns a single symbolic constant value representing the texture + combiner one's alpha source. The initial value is GL_PREVIOUS. +
GL_SRC2_ALPHA: + params returns a single symbolic constant value representing the texture + combiner two's alpha source. The initial value is GL_CONSTANT. +
GL_OPERAND0_RGB: + params returns a single symbolic constant value representing the texture + combiner zero's RGB operand. The initial value is GL_SRC_COLOR. +
GL_OPERAND1_RGB: + params returns a single symbolic constant value representing the texture + combiner one's RGB operand. The initial value is GL_SRC_COLOR. +
GL_OPERAND2_RGB: + params returns a single symbolic constant value representing the texture + combiner two's RGB operand. The initial value is GL_SRC_ALPHA. +
GL_OPERAND0_ALPHA: + params returns a single symbolic constant value representing the texture + combiner zero's alpha operand. The initial value is GL_SRC_ALPHA. +
GL_OPERAND1_ALPHA: + params returns a single symbolic constant value representing the texture + combiner one's alpha operand. The initial value is GL_SRC_ALPHA. +
GL_OPERAND2_ALPHA: + params returns a single symbolic constant value representing the texture + combiner two's alpha operand. The initial value is GL_SRC_ALPHA. +
GL_RGB_SCALE: + params returns a single floating-point value representing the current RGB + texture combiner scaling factor. The initial value is 1.0. +
GL_ALPHA_SCALE: + params returns a single floating-point value representing the current alpha + texture combiner scaling factor. The initial value is 1.0. +
GL_COORD_REPLACE_OES: + params returns a single boolean value representing the current point sprite + texture coordinate replacement enable state. The initial value is GL_FALSE. +

Notes

+ If an error is generated, + no change is made to the contents of params. +

+ glGetTexEnv returns + the texture environment parameters for the active texture unit. +

+ GL_POINT_SPRITE_OES and GL_COORD_REPLACE_OES are available + only if the OpenGL ES version is 1.1 or greater. +

Errors

+ GL_INVALID_ENUM is generated if target or pname is not an + accepted value. +

Copyright

Name

glGetTexParameter — return texture parameter values

C Specification

`void glGetTexParameterfv(`	GLenum `target`,
	GLenum `pname`,
	GLfloat * `params)`;

`void glGetTexParameteriv(`	GLenum `target`,
	GLenum `pname`,
	GLint * `params)`;

`void glGetTexParameterxv(`	GLenum `target`,
	GLenum `pname`,
	GLfixed * `params)`;

Parameters

+ target +: Specifies the target texture, which must be + GL_TEXTURE_2D.
+ pname +: + Specifies the symbolic name of a texture parameter. + Which can be one of the following: + GL_TEXTURE_MIN_FILTER, + GL_TEXTURE_MAG_FILTER, + GL_TEXTURE_WRAP_S, + GL_TEXTURE_WRAP_T, or + GL_GENERATE_MIPMAP. +
+ params +: Returns texture parameters.

Description

+ glGetTexParameter + returns in param the value of + the texture parameter specified as pname. + target defines the target texture, + which must be GL_TEXTURE_2D + which specifies two-dimensional texturing. + pname accepts the same symbols as + glTexParameter, + with the same interpretations: +

+ GL_TEXTURE_MIN_FILTER +: + Returns the single-valued texture minifying function, a symbolic + constant, which can be one of the following: + GL_NEAREST, + GL_LINEAR, + GL_NEAREST_MIPMAP_NEAREST, + GL_LINEAR_MIPMAP_NEAREST, + GL_NEAREST_MIPMAP_LINEAR, or + GL_LINEAR_MIPMAP_LINEAR. + The initial value is + GL_NEAREST_MIPMAP_LINEAR. +
+ GL_TEXTURE_MAG_FILTER +: + Returns the single-valued texture magnification function, + a symbolic constant, which can be either + GL_NEAREST or + GL_LINEAR. + The initial value is + GL_LINEAR. +
+ GL_TEXTURE_WRAP_S +: + Returns the single-valued wrapping function for texture coordinate + s, a symbolic constant, which can be + either: + GL_CLAMP_TO_EDGE, or + GL_REPEAT. + The initial value is + GL_REPEAT. +
+ GL_TEXTURE_WRAP_T +: + Returns the single-valued wrapping function for texture coordinate + t, a symbolic constant, which can be + either: + GL_CLAMP_TO_EDGE, or + GL_REPEAT. + The initial value is + GL_REPEAT. +
+ GL_GENERATE_MIPMAP +: + Returns a single boolean value indicating if automatic mipmap level + updates are enabled. The initial value is + GL_FALSE. + See glTexParameter. +

Notes

+ If an error is generated, no change is made to the contents of + param. +

Errors

GL_INVALID_ENUM is generated if + target or + pname + is not one of the accepted defined values.

Copyright

Name

glHint — specify implementation-specific hints

C Specification

`void glHint(`	GLenum `target`,
	GLenum `mode)`;

Parameters

+ target +: Specifies a symbolic constant indicating the + behavior to be controlled. + GL_FOG_HINT , + GL_GENERATE_MIPMAP_HINT , + GL_LINE_SMOOTH_HINT , + GL_PERSPECTIVE_CORRECTION_HINT, and + GL_POINT_SMOOTH_HINT are accepted.
+ mode +: Specifies a symbolic constant indicating the + desired behavior. + GL_FASTEST, + GL_NICEST, and + GL_DONT_CARE are accepted.

Description

Certain aspects of GL behavior, when there is room for + interpretation, can be controlled with hints. A hint is + specified with two arguments. target + is a symbolic constant indicating the behavior to be + controlled, and mode + is another symbolic constant indicating the desired behavior. + The initial value for each target is + GL_DONT_CARE. + mode can be one of the following:

+ GL_FASTEST +: The most efficient option should be chosen.
+ GL_NICEST +: The most correct, or highest quality, option should + be chosen.
+ GL_DONT_CARE +: No preference.

Though the implementation aspects that can be hinted are + well defined, the interpretation of the hints depends on the + implementation. The hint aspects that can be specified with + target, + along with suggested semantics, are as follows:

+ GL_FOG_HINT +: Indicates the accuracy of fog calculation. If + per-pixel fog calculation is not efficiently supported by + the GL implementation, hinting + GL_DONT_CARE or + GL_FASTEST + can result in per-vertex calculation of fog effects.
+ GL_GENERATE_MIPMAP_HINT +: + Indicates the desired quality and performance of automatic mipmap level generation. +
+ GL_LINE_SMOOTH_HINT +: Indicates the sampling quality of antialiased + lines. If a larger filter function is applied, hinting + GL_NICEST + + can result in more pixel fragments being generated during + rasterization.
+ GL_PERSPECTIVE_CORRECTION_HINT +: Indicates the quality of color and texture + coordinate interpolation. If perspective-corrected + parameter interpolation is not efficiently supported by + the GL implementation, hinting GL_DONT_CARE or + GL_FASTEST + can result in simple linear interpolation of colors + and/or texture coordinates.
+ GL_POINT_SMOOTH_HINT +: Indicates the sampling quality of antialiased + points. If a larger filter function is applied, hinting + GL_NICEST + can result in more pixel fragments being generated during + rasterization.

Notes

The interpretation of hints depends on the + implementation. Some implementations ignore + glHint + settings.

Errors

GL_INVALID_ENUM is generated if either + target or mode + is not an accepted value.

Copyright

Name

glIsBuffer — determine if a name corresponds to a buffer object

C Specification

GLboolean glIsBuffer( GLuint buffer);

Parameters

+ buffer +: + Specifies a value that may be the name of a buffer object. +

Description

+ glIsBuffer + returns GL_TRUE if buffer + is currently the name + of a buffer object. If buffer is zero, + or is a non-zero value + that is not currently the name of a buffer object, + glIsBuffer returns GL_FALSE. +

A name returned by glGenBuffers, + but not yet associated with a buffer object by calling + glBindBuffer, is not the + name of a buffer object.

Errors

+ None. +

Copyright

Name

glIsEnabled — test whether a capability is enabled

C Specification

GLboolean glIsEnabled( GLenum cap);

Parameters

+ cap +: + Specifies a symbolic constant indicating a GL capability. +

Description

+ glIsEnabled + returns GL_TRUE if cap is an enabled + capability and returns GL_FALSE otherwise. +

+ The following capabilities are accepted for cap: +

`Constant`		`See function:`

`GL_ALPHA_TEST`		+ glAlphaFunc +
`GL_BLEND`		+ glBlendFunc, + glLogicOp +
+ `GL_CLIP_PLANEi +` +		+ glClipPlane +
`GL_COLOR_ARRAY`		+ glColorPointer +
`GL_COLOR_LOGIC_OP`		+ glLogicOp +
`GL_COLOR_MATERIAL`		+ glMaterial +
`GL_CULL_FACE`		+ glCullFace +
`GL_DEPTH_TEST`		+ glDepthFunc, + glDepthRange +
`GL_DITHER`		+ glEnable +
`GL_FOG`		+ glFog +
+ `GL_LIGHTi +` +		+ glLight, + glLightModel +
`GL_LIGHTING`		+ glLight, + glLightModel, + glMaterial +
`GL_LINE_SMOOTH`		+ glLineWidth +
`GL_MULTISAMPLE`		+ glEnable +
`GL_NORMAL_ARRAY`		+ glNormalPointer +
`GL_NORMALIZE`		+ glNormal +
`GL_POINT_SIZE_ARRAY_OES`		+ glEnableClientState +
`GL_POINT_SMOOTH`		+ glPointSize +
`GL_POINT_SPRITE_OES`		+ glTexEnv +
`GL_POLYGON_OFFSET_FILL`		+ glPolygonOffset +
`GL_RESCALE_NORMAL`		+ glNormal +
`GL_SAMPLE_ALPHA_TO_COVERAGE`		+ glSampleCoverage +
`GL_SAMPLE_ALPHA_TO_ONE`		+ glSampleCoverage +
`GL_SAMPLE_COVERAGE`		+ glSampleCoverage +
`GL_SCISSOR_TEST`		+ glScissor +
`GL_STENCIL_TEST`		+ glStencilFunc, + glStencilOp +
`GL_TEXTURE_2D`		+ glTexImage2D +
`GL_TEXTURE_COORD_ARRAY`		+ glTexCoordPointer +
`GL_VERTEX_ARRAY`		+ glVertexPointer +

Notes

+ If an error is generated, + glIsEnabled returns 0. +

Errors

+ GL_INVALID_ENUM is generated if + cap is not an accepted value. +

Copyright

Name

glIsTexture — determine if a name corresponds to a texture

C Specification

GLboolean glIsTexture( GLuint texture);

Parameters

+ texture +: + Specifies a value that may be the name of a texture. +

Description

+ glIsTexture + returns GL_TRUE if texture is currently the name + of a texture. If texture is zero, + or is a non-zero value + that is not currently the name of a texture, + glIsTexture returns GL_FALSE. +

A name returned by glGenTextures, + but not yet associated with a texture by calling + glBindTexture, is not the + name of a texture.

Errors

+ None. +

Copyright

Name

glLight — set light source parameters

C Specification

`void glLightf(`	GLenum `light`,
	GLenum `pname`,
	GLfloat `param)`;

`void glLightx(`	GLenum `light`,
	GLenum `pname`,
	GLfixed `param)`;

Parameters

+ light +: Specifies a light. The number of lights depends on + the implementation, but at least eight lights are + supported. They are identified by symbolic names of the + form GL_LIGHTi + where + + 0 + <= + i + < + GL_MAX_LIGHTS + . +
+ pname +: Specifies a single-valued light source parameter for + light. + GL_SPOT_EXPONENT, + GL_SPOT_CUTOFF, + GL_CONSTANT_ATTENUATION, + GL_LINEAR_ATTENUATION, and + GL_QUADRATIC_ATTENUATION + are accepted.
+ param +: Specifies the value that parameter pname + of light source light will be set to.

C Specification

`void glLightfv(`	GLenum `light`,
	GLenum `pname`,
	const GLfloat * `params)`;

`void glLightxv(`	GLenum `light`,
	GLenum `pname`,
	const GLfixed * `params)`;

Parameters

+ light +: Specifies a light. The number of lights depends on + the implementation, but at least eight lights are + supported. They are identified by symbolic names of the + form + GL_LIGHTi + where + + 0 + <= + i + < + GL_MAX_LIGHTS + . +
+ pname +: Specifies a light source parameter for + light. + GL_AMBIENT, + GL_DIFFUSE, + GL_SPECULAR, + GL_POSITION, + GL_SPOT_CUTOFF, + GL_SPOT_DIRECTION, + GL_SPOT_EXPONENT, + GL_CONSTANT_ATTENUATION, + GL_LINEAR_ATTENUATION, and + GL_QUADRATIC_ATTENUATION are accepted.
+ params +: Specifies a pointer to the value or values that parameter + pname of light source + light will be set to.

Description

glLight + sets the values of individual light source parameters. + light + names the light and is a symbolic name of the form + GL_LIGHTi, + where + + 0 + <= + i + < + GL_MAX_LIGHTS + . + pname + specifies one of ten light source parameters, again by symbolic + name. params + is either a single value or a pointer to an array that contains + the new values.

To enable and disable lighting calculation, call + glEnable and + glDisable + with argument GL_LIGHTING. + Lighting is initially disabled. When it is enabled, light + sources that are enabled contribute to the lighting + calculation. Light source i + is enabled and disabled using + glEnable and + glDisable + with argument GL_LIGHTi. +

The ten light parameters are as follows:

+ GL_AMBIENT +

params + contains four fixed-point or floating-point values that + specify the ambient RGBA intensity of the light. Both + fixed-point and floating-point values are mapped + directly. Neither fixed-point nor floating-point values + are clamped. The initial ambient light intensity is (0, + 0, 0, 1).

+ GL_DIFFUSE +

params + contains four fixed-point or floating-point values that + specify the diffuse RGBA intensity of the light. Both + fixed-point and floating-point values are mapped + directly. Neither fixed-point nor floating-point values + are clamped. The initial value for GL_LIGHT0 + is (1, 1, 1, 1). For other lights, the initial value is + (0, 0, 0, 0).

+ GL_SPECULAR +

params + contains four fixed-point or floating-point values that + specify the specular RGBA intensity of the light. Both + fixed-point and floating-point values are mapped + directly. Neither fixed-point nor floating-point values + are clamped. The initial value for GL_LIGHT0 + is (1, 1, 1, 1). For other lights, the initial value is + (0, 0, 0, 0).

GL_POSITION

+ params contains four fixed-point or floating-point values that specify + the position of the light in homogeneous object coordinates. + Both fixed-point and floating-point values are mapped directly. + Neither fixed-point nor floating-point values are clamped. +

+ The position is transformed by the modelview matrix when + glLight is called (just as if it were a point), + and it is stored in eye coordinates. + If the + w + component of the position is 0, + the light is treated as a directional source. + Diffuse and specular lighting calculations take the light's direction, + but not its actual position, + into account, + and attenuation is disabled. + Otherwise, + diffuse and specular lighting calculations are based on the actual location + of the light in eye coordinates, + and attenuation is enabled. + The initial position is (0, 0, 1, 0); + thus, the initial light source is directional, + parallel to, and in the direction of the + + + + - + z + + + axis. +

+ GL_SPOT_DIRECTION +

params + contains three fixed-point or floating-point values that + specify the direction of the light in homogeneous object + coordinates. Both fixed-point and floating-point values + are mapped directly. Neither fixed-point nor + floating-point values are clamped.

The spot direction is transformed by the upper 3x3 of the + modelview matrix when glLight + is called, and it is stored in + eye coordinates. It is significant only when + GL_SPOT_CUTOFF + is not 180, which it is initially. The initial direction is (0, + 0, -1).

+ GL_SPOT_EXPONENT +

params + is a single fixed-point or floating-point value that + specifies the intensity distribution of the light. + Fixed-point and floating-point values are mapped + directly. Only values in the range [0, 128] are + accepted.

Effective light intensity is attenuated by the cosine of + the angle between the direction of the light and the direction + from the light to the vertex being lighted, raised to the power + of the spot exponent. Thus, higher spot exponents result in a + more focused light source, regardless of the spot cutoff angle + (see GL_SPOT_CUTOFF, + next paragraph). The initial spot exponent is 0, resulting in + uniform light distribution.

+ GL_SPOT_CUTOFF +

params + is a single fixed-point or floating-point value that + specifies the maximum spread angle of a light source. + Fixed-point and floating-point values are mapped + directly. Only values in the range [0, 90] and the special + value 180 are accepted. If the angle between the + direction of the light and the direction from the light + to the vertex being lighted is greater than the spot + cutoff angle, the light is completely masked. + Otherwise, its intensity is controlled by the spot + exponent and the attenuation factors. The initial spot + cutoff is 180, resulting in uniform light + distribution.

+ GL_CONSTANT_ATTENUATION, + GL_LINEAR_ATTENUATION, + GL_QUADRATIC_ATTENUATION +

params + is a single fixed-point or floating-point value that + specifies one of the three light attenuation factors. + Fixed-point and floating-point values are mapped + directly. Only nonnegative values are accepted. If the + light is positional, rather than directional, its + intensity is attenuated by the reciprocal of the sum of + the constant factor, the linear factor times the distance + between the light and the vertex being lighted, and the + quadratic factor times the square of the same distance. + The initial attenuation factors are (1, 0, 0), resulting + in no attenuation.

Notes

It is always the case that + + GL_LIGHTi = + GL_LIGHT0+i + . +

Errors

GL_INVALID_ENUM is generated if either + light or + pname is not an accepted value.

GL_INVALID_VALUE + is generated if a spot exponent value is specified outside the + range [0, 128], or if spot cutoff is specified outside the range + [0, 90] (except for the special value 180), or if a negative + attenuation factor is specified.

Copyright

Name

glLightModel — set the lighting model parameters

C Specification

`void glLightModelf(`	GLenum `pname`,
	GLfloat `param)`;

`void glLightModelx(`	GLenum `pname`,
	GLfixed `param)`;

Parameters

+ pname +: Specifies a single-valued lighting model parameter. Must be + GL_LIGHT_MODEL_TWO_SIDE.
+ param +: Specifies the value that param + will be set to.

C Specification

`void glLightModelfv(`	GLenum `pname`,
	const GLfloat * `params)`;

`void glLightModelxv(`	GLenum `pname`,
	const GLfixed * `params)`;

Parameters

+ pname +: Specifies a lighting model parameter. + GL_LIGHT_MODEL_AMBIENT and + GL_LIGHT_MODEL_TWO_SIDE are accepted.
+ params +: Specifies a pointer to the value or values that + params will be set to.

Description

glLightModel sets the lighting model parameter. + pname names a parameter and + params + gives the new value. There are two lighting model parameters:

+ GL_LIGHT_MODEL_AMBIENT +: params + contains four fixed-point or floating-point values that + specify the ambient intensity of the entire scene. + The values are not clamped. The initial value is + (0.2, 0.2, 0.2, 1.0).
+ GL_LIGHT_MODEL_TWO_SIDE +: params + is a single fixed-point or floating-point value that + specifies whether one- or two-sided lighting calculations + are done for polygons. It has no effect on the lighting + calculations for points or lines. If + params + is 0, one-sided lighting is specified, and both front- and + back-facing polygons are assigned the same computed color. + Otherwise, two-sided lighting is specified. In this case, + vertices of back-facing polygons have their normals reversed + before the lighting equation is evaluated. Vertices of + front-facing polygons are always lighted with no change to + their normals. The initial value is 0. Note that there is + only one set of material properties shared by both + front- and back-facing polygons.

The lighted color of a vertex is the sum of the material + emission intensity, the product of the material ambient + reflectance and the lighting model full-scene ambient + intensity, and the contribution of each enabled light source. + Each light source contributes the sum of three terms: ambient, + diffuse, and specular. The ambient light source contribution is + the product of the material ambient reflectance and the light's + ambient intensity. The diffuse light source contribution is the + product of the material diffuse reflectance, the light's + diffuse intensity, and the dot product of the vertex's normal + with the normalized vector from the vertex to the light source. + The specular light source contribution is the product of the + material specular reflectance, the light's specular intensity, + and the dot product of the normalized vertex-to-eye and + vertex-to-light vectors, raised to the power of the shininess + of the material. All three light source contributions are + attenuated equally based on the distance from the vertex to the + light source and on light source direction, spread exponent, + and spread cutoff angle. All dot products are replaced with 0 + if they evaluate to a negative value.

The alpha component of the resulting lighted color is set + to the alpha value of the material diffuse reflectance.

Errors

GL_INVALID_ENUM is generated if + pname is not an accepted value.

Copyright

Name

glLineWidth — specify the width of rasterized lines

C Specification

void glLineWidth( GLfloat width);

void glLineWidthx( GLfixed width);

Parameters

+ width +: Specifies the width of rasterized lines. The + initial value is 1.

Description

+ glLineWidth + specifies the rasterized width of both aliased and antialiased + lines. Using a line width other than 1 has different effects, + depending on whether line antialiasing is enabled. To enable + and disable line antialiasing, call + glEnable and + glDisable + with argument GL_LINE_SMOOTH. + Line antialiasing is initially disabled.

If line antialiasing is disabled, the actual width is + determined by rounding the supplied width to the nearest + integer. (If the rounding results in the value 0, it is as if + the line width were 1.) If + + + | + Δx + | + + >= + + | + Δy + | + + , + i + pixels are filled in each column that is rasterized, where + i is the rounded value of + width. Otherwise, i + pixels are filled in each row that is rasterized.

If antialiasing is enabled, line rasterization produces a + fragment for each pixel square that intersects the region lying + within the rectangle having width equal to the current line + width, length equal to the actual length of the line, and + centered on the mathematical line segment. The coverage value + for each fragment is the window coordinate area of the + intersection of the rectangular region with the corresponding + pixel square. This value is saved and used in the final + rasterization step.

Not all widths can be supported when line antialiasing is + enabled. If an unsupported width is requested, the nearest + supported width is used. Only width 1 is guaranteed to be + supported; others depend on the implementation. Likewise, there + is a range for aliased line widths as well. To query the range + of supported widths, call + glGet + with arguments + GL_ALIASED_LINE_WIDTH_RANGE or + GL_SMOOTH_LINE_WIDTH_RANGE.

Notes

Nonantialiased line width may be clamped to an + implementation-dependent maximum. Call + glGet + with GL_ALIASED_LINE_WIDTH_RANGE + to determine the maximum width.

Errors

GL_INVALID_VALUE is generated if + width is less than or equal to 0.

Associated Gets

+ glGet + with argument GL_ALIASED_LINE_WIDTH_RANGE

+ glGet + with argument GL_SMOOTH_LINE_WIDTH_RANGE

Copyright

Name

glLoadIdentity — replace the current matrix with the identity + matrix

C Specification

void glLoadIdentity( void);

Description

+ glLoadIdentity + replaces the current matrix with the identity matrix. It is + semantically equivalent to calling + glLoadMatrix + with the identity matrix

+ + ( + + + 1 + 0 + 0 + 0 + + + 0 + 1 + 0 + 0 + + + 0 + 0 + 1 + 0 + + + 0 + 0 + 0 + 1 + + + ) + +

but in some cases it is more efficient.

Associated Gets

+ glGet with argument GL_MATRIX_MODE +

+ glGet with argument GL_MODELVIEW_MATRIX +

+ glGet with argument GL_PROJECTION_MATRIX +

+ glGet with argument GL_TEXTURE_MATRIX +

Copyright

Name

glLoadMatrix — replace the current matrix with the specified + matrix

C Specification

void glLoadMatrixf( const GLfloat * m);

void glLoadMatrixx( const GLfixed * m);

Parameters

+ m +: Specifies a pointer to 16 consecutive values, which + are used as the elements of a + + 4x4 + + column-major matrix.

Description

glLoadMatrix + replaces the current matrix with the one whose elements are + specified by m. + The current matrix is the projection matrix, modelview + matrix, or texture matrix, depending on the current matrix mode (see + glMatrixMode).

The current matrix, M, defines a transformation of + coordinates. For instance, assume M refers to the modelview + matrix. If + + v= + + v[0] + v[1] + v[2] + v[3] + + + is the set of object coordinates of a vertex, and + m points to an array of 16 + fixed-point or single-precision floating-point values + + + m[0], + m[1], + ... + m[15] + + , + + then the modelview transformation + + Mv + + does the following:

+ Mv= + ( + + + m[0] + m[4] + m[8] + m[12] + + + m[1] + m[5] + m[9] + m[13] + + + m[2] + m[6] + m[10] + m[14] + + + m[3] + m[7] + m[11] + m[15] + + + ) + x + ( + + v[0] + v[1] + v[2] + v[3] + + ) +

Where + ``x'' + denotes matrix multiplication.

Projection and texture transformations are similarly + defined.

Notes

While the elements of the matrix may be specified with + fixed point or single precision, the GL implementation may store or + operate on these values in less than single precision.

Associated Gets

+ glGet with argument GL_MATRIX_MODE +

+ glGet with argument GL_MODELVIEW_MATRIX +

+ glGet with argument GL_PROJECTION_MATRIX +

+ glGet with argument GL_TEXTURE_MATRIX +

Copyright

Name

glLogicOp — specify a logical pixel operation

C Specification

void glLogicOp( GLenum opcode);

Parameters

+ opcode +: Specifies a symbolic constant that selects a + logical operation. The following symbols are accepted: + GL_CLEAR, + GL_SET, + GL_COPY, + GL_COPY_INVERTED, + GL_NOOP, + GL_INVERT, + GL_AND, + GL_NAND, + GL_OR, + GL_NOR, + GL_XOR, + GL_EQUIV, + GL_AND_REVERSE, + GL_AND_INVERTED, + GL_OR_REVERSE, and + GL_OR_INVERTED. The initial value is + GL_COPY.

Description

glLogicOp + specifies a logical operation that, when enabled, is applied + between the incoming color and the color at the corresponding + location in the frame buffer. + To enable or disable the logical operation, call + glEnable and + glDisable + with argument GL_COLOR_LOGIC_OP. + Logical operation is initially disabled. +

Opcode	Resulting Operation
`GL_CLEAR`	0
`GL_SET`	1
`GL_COPY`	`s`
`GL_COPY_INVERTED`	+ + ~s + +
`GL_NOOP`	`d`
`GL_INVERT`	+ + ~d + +
`GL_AND`	+ + s&d + +
`GL_NAND`	+ + ~s&d + +
`GL_OR`	+ + s\|d + +
`GL_NOR`	+ + ~s\|d + +
`GL_XOR`	+ + s^d + +
`GL_EQUIV`	+ + ~s^d + +
`GL_AND_REVERSE`	+ + s&~d + +
`GL_AND_INVERTED`	+ + ~s&d + +
`GL_OR_REVERSE`	+ + s\|~d + +
`GL_OR_INVERTED`	+ + ~s\|d + +

+ opcode + is a symbolic constant chosen from the list above. In the + explanation of the logical operations, s + represents the incoming color and d + represents the color in the frame buffer. Standard C-language + operators are used. As these bitwise operators suggest, the + logical operation is applied independently to each bit pair of + the source and destination indices or colors.

Errors

GL_INVALID_ENUM is generated if + opcode is not an accepted value.

Copyright

Name

glMaterial — specify material parameters for the lighting model

C Specification

`void glMaterialf(`	GLenum `face`,
	GLenum `pname`,
	GLfloat `param)`;

`void glMaterialx(`	GLenum `face`,
	GLenum `pname`,
	GLfixed `param)`;

Parameters

+ face +: Specifies which face or faces are being updated. Must be + GL_FRONT_AND_BACK.
+ pname +: Specifies the single-valued material parameter of + the face or faces that is being updated. Must be + GL_SHININESS.
+ param +: Specifies the value that parameter + GL_SHININESS will be set to.

C Specification

`void glMaterialfv(`	GLenum `face`,
	GLenum `pname`,
	const GLfloat * `params)`;

`void glMaterialxv(`	GLenum `face`,
	GLenum `pname`,
	const GLfixed * `params)`;

Parameters

+ face +: Specifies which face or faces are being updated. + Must be GL_FRONT_AND_BACK. +
+ pname +: Specifies the material parameter of the face or + faces that is being updated. Must be one of + GL_AMBIENT, + GL_DIFFUSE, + GL_SPECULAR, + GL_EMISSION, + GL_SHININESS, or + GL_AMBIENT_AND_DIFFUSE.
+ params +: Specifies a pointer to the value or values that + pname + + will be set to.

Description

+ glMaterial + assigns values to material parameters. There are two matched + sets of material parameters. One, the front-facing + set, is used to shade points, lines, and all polygons (when + two-sided lighting is disabled), or just front-facing polygons + (when two-sided lighting is enabled). The other set, + back-facing, + is used to shade back-facing polygons only when two-sided + lighting is enabled. Refer to the + glLightModel + reference page for details concerning one- and two-sided + lighting calculations. +

+ glMaterial + takes three arguments. The first, face, + must be GL_FRONT_AND_BACK and specifies that both + front and back materials will be modified. + The second, pname, + specifies which of several parameters in one or both sets + will be modified. The third, params, + specifies what value or values will be assigned to the + specified parameter. +

+ Material parameters are used in the lighting equation + that is optionally applied to each vertex. The equation is + discussed in the + glLightModel + reference page. The parameters that can be specified using + glMaterial, + and their interpretations by the lighting equation, are as follows: +

+ GL_AMBIENT +: params + contains four fixed-point or floating-point values that + specify the ambient RGBA reflectance of the material. + The values are not clamped. The initial ambient + reflectance is + (0.2, 0.2, 0.2, 1.0).
+ GL_DIFFUSE +: params + contains four fixed-point or floating-point values that + specify the diffuse RGBA reflectance of the material. + The values are not clamped. The initial diffuse + reflectance is + (0.8, 0.8, 0.8, 1.0).
+ GL_SPECULAR +: params + contains four fixed-point or floating-point values that + specify the specular RGBA reflectance of the material. + The values are not clamped. The initial specular + reflectance is + (0, 0, 0, 1).
+ GL_EMISSION +: params + contains four fixed-point or floating-point values that + specify the RGBA emitted light intensity of the material. + The values are not clamped. The initial emission + intensity is + (0, 0, 0, 1).
+ GL_SHININESS +: params + is a single fixed-point or floating-point value that + specifies the RGBA specular exponent of the material. + Only values in the range [0, 128] are accepted. The + initial specular exponent is 0.
+ GL_AMBIENT_AND_DIFFUSE +: Equivalent to calling glMaterial + twice with the same parameter values, once with + GL_AMBIENT + and once with GL_DIFFUSE.

Notes

To change the diffuse and ambient material per vertex, + color material can be used. + To enable and disable + GL_COLOR_MATERIAL, call + glEnable and + glDisable with + argument GL_COLOR_MATERIAL. + Color material is initially disabled. +

While the ambient, diffuse, specular and emission + material parameters all have alpha components, only the diffuse + alpha component is used in the lighting computation.

Errors

+ GL_INVALID_ENUM is generated if either + face or pname + is not an accepted value. +

+ GL_INVALID_VALUE + is generated if a specular exponent outside the range [0, 128] + is specified. +

Associated Gets

+ glGetMaterial +

Copyright

Name

glMatrixMode — specify which matrix is the current matrix

C Specification

void glMatrixMode( GLenum mode);

Parameters

+ mode +: + Specifies which matrix stack is the target for + subsequent matrix operations. + These values are accepted: + GL_MODELVIEW, + GL_PROJECTION, and + GL_TEXTURE. + + The initial value is GL_MODELVIEW. +

Description

+ glMatrixMode sets the current matrix mode. + mode can assume one of these values: +

+ GL_MODELVIEW +: Applies subsequent matrix operations to the + modelview matrix stack.
+ GL_PROJECTION +: Applies subsequent matrix operations to the + projection matrix stack.
+ GL_TEXTURE +: Applies subsequent matrix operations to the texture + matrix stack.

Errors

GL_INVALID_ENUM is generated if + mode is not an accepted value.

Associated Gets

+ glGet with argument GL_MATRIX_MODE +

Copyright

Name

glMultMatrix — multiply the current matrix with the specified + matrix

C Specification

void glMultMatrixf( const GLfloat * m);

void glMultMatrixx( const GLfixed * m);

Parameters

+ m +: Points to 16 consecutive values that are used as + the elements of a + + 4x4 + + column-major matrix.

Description

glMultMatrix + multiplies the current matrix with the one specified using + m, + and replaces the current matrix with the product.

The current matrix is determined by the current matrix mode (see + glMatrixMode). + It is either the projection matrix, modelview matrix, or the + texture matrix.

Examples

If the current matrix is C, + and the coordinates to be transformed are, + + v= + + v[0] + v[1] + v[2] + v[3] + + , + then the current transformation is + + Cxv + , or +

+ ( + + + c[0] + c[4] + c[8] + c[12] + + + c[1] + c[5] + c[9] + c[13] + + + c[2] + c[6] + c[10] + c[14] + + + c[3] + c[7] + c[11] + c[15] + + + ) + x + ( + + v[0] + v[1] + v[2] + v[3] + + ) +

Calling + glMultMatrix + with an argument of + + + m= + m[0], + m[1], + ... + m[15] + + + replaces the current transformation with + + CxM + xv + , or

+ ( + + + c[0] + c[4] + c[8] + c[12] + + + c[1] + c[5] + c[9] + c[13] + + + c[2] + c[6] + c[10] + c[14] + + + c[3] + c[7] + c[11] + c[15] + + + ) + x + ( + + + m[0] + m[4] + m[8] + m[12] + + + m[1] + m[5] + m[9] + m[13] + + + m[2] + m[6] + m[10] + m[14] + + + m[3] + m[7] + m[11] + m[15] + + + ) + x + ( + + v[0] + v[1] + v[2] + v[3] + + ) +

Where + ``x'' + denotes matrix multiplication, and + v + is represented as a + + 4x1 + + matrix.

Notes

While the elements of the matrix may be specified with + fixed point or single precision, the GL may store or operate on + these values in less than single precision.

In many computer languages + + 4x4 + + arrays are represented in row-major order. The transformations + just described represent these matrices in column-major order. + The order of the multiplication is important. For example, if + the current transformation is a rotation, and + glMultMatrix + is called with a translation matrix, the translation is done + directly on the coordinates to be transformed, while the + rotation is done on the results of that translation.

Associated Gets

+ glGet with argument GL_MATRIX_MODE +

+ glGet with argument GL_MODELVIEW_MATRIX +

+ glGet with argument GL_PROJECTION_MATRIX +

+ glGet with argument GL_TEXTURE_MATRIX +

Copyright

Name

glMultiTexCoord — set the current texture coordinates

C Specification

`void glMultiTexCoord4f(`	GLenum `target`,
	GLfloat `s`,
	GLfloat `t`,
	GLfloat `r`,
	GLfloat `q)`;

`void glMultiTexCoord4x(`	GLenum `target`,
	GLfixed `s`,
	GLfixed `t`,
	GLfixed `r`,
	GLfixed `q)`;

Parameters

+ target +: Specifies the texture unit whose coordinates should be + modified. The number of texture units is implementation + dependent, but must be at least + two. + Symbolic constant must be one of + GL_TEXTUREi, + where i ranges from 0 to GL_MAX_TEXTURE_UNITS - 1, + which is an implementation-dependent value.
+ s, + t, + r, + q +: Specify + s, + t, + r, and + q texture coordinates for + target texture unit.

Description

+ glMultiTexCoord + specifies the four texture coordinates as + (s, + t, + r, + q).

The current texture coordinates are part of the data that + is associated with each vertex. + Initially, the values for + + + + s + t + r + q + + + are + + + + 0 + 0 + 0 + 1 + + .

Notes

It is always the case that + + GL_TEXTUREi = + GL_TEXTURE0+i + .

Associated Gets

+ glGet with argument GL_CURRENT_TEXTURE_COORDS with appropriate + texture unit selected. +

+ glGet + with argument GL_MAX_TEXTURE_UNITS +

Copyright

Name

glNormal — set the current normal vector

C Specification

`void glNormal3f(`	GLfloat `nx`,
	GLfloat `ny`,
	GLfloat `nz)`;

`void glNormal3x(`	GLfixed `nx`,
	GLfixed `ny`,
	GLfixed `nz)`;

Parameters

+ nx, + ny, + nz +: Specify the + x, + y, and + z coordinates of the + new current normal. The initial value is (0, 0, 1).

Description

The current normal is set to the given coordinates whenever + glNormal + is issued.

Normals specified with glNormal + need not have unit length. If GL_NORMALIZE + is enabled, then normals of any length specified with + glNormal + are normalized after transformation. If + GL_RESCALE_NORMAL + is enabled, normals are scaled by a scaling factor derived from + the modelview matrix. GL_RESCALE_NORMAL + requires that the originally specified normals were of unit + length, and that the modelview matrix contain only uniform + scales for proper results. To enable and disable normalization, + call + glEnable and + glDisable + with either + GL_NORMALIZE or GL_RESCALE_NORMAL. + Normalization is initially disabled.

Associated Gets

+ glGet with argument GL_CURRENT_NORMAL +

+ glIsEnabled with argument GL_NORMALIZE +

+ glIsEnabled with argument GL_RESCALE_NORMAL +

Copyright

Name

glNormalPointer — define an array of normals

C Specification

`void glNormalPointer(`	GLenum `type`,
	GLsizei `stride`,
	const GLvoid * `pointer)`;

Parameters

+ type +

Specifies the data type of each coordinate in the + array. Symbolic constants + GL_BYTE, + GL_SHORT, and + GL_FIXED are accepted. + However, the initial value is + GL_FLOAT.

+ The common profile accepts the symbolic constant + GL_FLOAT as well. +

+ stride +

Specifies the byte offset between consecutive + normals. If stride + is 0, the normals are understood to be + tightly packed in the array. The initial value is + 0.

+ pointer +

Specifies a pointer to the first coordinate of the + first normal in the array. The initial value is 0.

Description

glNormalPointer + specifies the location and data of an array of normals to use + when rendering. type + specifies the data type of the normal coordinates and + stride + gives the byte stride from one normal to the next, allowing + vertices and attributes to be packed into a single array or + stored in separate arrays. (Single-array storage may be more + efficient on some implementations.) When a normal array is + specified, + type , + stride , and + pointer + are saved as client-side state.

+ If the normal array is enabled, it is used when + glDrawArrays or + glDrawElements + is called. + To enable and disable the normal array, call + glEnableClientState + and + glDisableClientState + with the argument GL_NORMAL_ARRAY. + The normal array is initially disabled and isn't accessed when + glDrawArrays or + glDrawElements + is called.

Use + glDrawArrays + to construct a sequence of primitives (all of the same type) + from prespecified vertex and vertex attribute arrays. Use + glDrawElements + to construct a sequence of primitives by indexing vertices and + vertex attributes.

Notes

glNormalPointer + is typically implemented on the client side.

Errors

GL_INVALID_ENUM is generated if + type is not an accepted value.

GL_INVALID_VALUE is generated if + stride is negative.

Copyright

Name

glOrtho — multiply the current matrix with an orthographic + matrix

C Specification

`void glOrthof(`	GLfloat `left`,
	GLfloat `right`,
	GLfloat `bottom`,
	GLfloat `top`,
	GLfloat `near`,
	GLfloat `far)`;

`void glOrthox(`	GLfixed `left`,
	GLfixed `right`,
	GLfixed `bottom`,
	GLfixed `top`,
	GLfixed `near`,
	GLfixed `far)`;

Parameters

+ left, + right +: Specify the coordinates for the left and right + vertical clipping planes.
+ bottom, + top +: Specify the coordinates for the bottom and top + horizontal clipping planes.
+ near, + far +: Specify the distances to the nearer and farther + depth clipping planes. These values are negative if the + plane is to be behind the viewer.

Description

glOrtho + describes a transformation that produces a parallel projection. + The current matrix (see + glMatrixMode) + is multiplied by this matrix and the result replaces the + current matrix, as if + glMultMatrix + were called with the following matrix as its argument:

+ + ( + + + + + 2 + right-left + + + 0 + 0 + tx + + + 0 + + + 2 + top-bottom + + + 0 + ty + + + 0 + 0 + + + -2 + far-near + + + tz + + + 0 + 0 + 0 + 1 + + + ) + +

where

+ + tx + + = + + - + + right+left + right-left + + + + ty + + = + + - + + top+bottom + top-bottom + + + + tz + + = + + - + + far+near + far-near + + +

Typically, the matrix mode is + GL_PROJECTION, and + (left, bottom, + -near) and + (right, top, + -near) + specify the points on the near clipping plane that are mapped + to the lower left and upper right corners of the window, + respectively, assuming that the eye is located at (0, 0, 0). + -far + specifies the location of the far clipping plane. Both + near and far + can be either positive or negative.

Use + glPushMatrix + and + glPopMatrix + to save and restore the current matrix stack.

Errors

+ GL_INVALID_VALUE is generated if + left = right, or + bottom = top, or + near = far. +

Copyright

Name

glPixelStorei — set pixel storage modes

C Specification

`void glPixelStorei(`	GLenum `pname`,
	GLint `param)`;

Parameters

+ pname +: Specifies the symbolic name of the parameter to be set. + GL_PACK_ALIGNMENT + affects the packing of pixel data into memory. + GL_UNPACK_ALIGNMENT + affects the unpacking of pixel data + from memory.
+ param +: Specifies the value that pname + is set to.

Description

glPixelStorei + sets pixel storage modes that affect the operation of + subsequent + glReadPixels + as well as the unpacking of + glTexImage2D, + and + glTexSubImage2D. +

pname + is a symbolic constant indicating the parameter to be set, and + param + is the new value. The following storage parameter affects how + pixel data is returned to client memory. This value is + significant for + glReadPixels: +

+ GL_PACK_ALIGNMENT +: Specifies the alignment requirements for the start + of each pixel row in memory. The allowable values are 1 + (byte-alignment), 2 (rows aligned to even-numbered + bytes), 4 (word-alignment), and 8 (rows start on + double-word boundaries). The initial value is 4.

The following storage parameter affects how pixel data is + read from client memory. This value is significant for + glTexImage2D + and + glTexSubImage2D: +

+ GL_UNPACK_ALIGNMENT +: Specifies the alignment requirements for the start + of each pixel row in memory. The allowable values are 1 + (byte-alignment), 2 (rows aligned to even-numbered + bytes), 4 (word-alignment), and 8 (rows start on + double-word boundaries). The initial value is 4.

Notes

Pixel storage modes are client states.

+ glCompressedTexImage2D + and + glCompressedTexSubImage2D + are not affected by glPixelStorei. +

Errors

GL_INVALID_ENUM is generated if + pname is not an accepted value.

GL_INVALID_VALUE + is generated if alignment is specified as other than 1, 2, 4, or 8.

Associated Gets

+ glGet with argument + GL_PACK_ALIGNMENT or GL_UNPACK_ALIGNMENT +

Copyright

Name

glPointParameter — specify parameters for point rasterization

C Specification

`void glPointParameterf(`	GLenum `pname`,
	GLfloat `param)`;

`void glPointParameterx(`	GLenum `pname`,
	GLfixed `param)`;

Parameters

+ pname +: + Specifies the single-valued parameter to be updated. + Can be either + GL_POINT_SIZE_MIN, + GL_POINT_SIZE_MAX, or + GL_POINT_FADE_THRESHOLD_SIZE. +
+ param +: + Specifies the value that the parameter will be set to. +

C Specification

`void glPointParameterfv(`	GLenum `pname`,
	const GLfloat * `params)`;

`void glPointParameterxv(`	GLenum `pname`,
	const GLfixed * `params)`;

Parameters

+ pname +: + Specifies the parameter to be updated. + Can be either + GL_POINT_SIZE_MIN, + GL_POINT_SIZE_MAX, + GL_POINT_FADE_THRESHOLD_SIZE, or + GL_POINT_DISTANCE_ATTENUATION. +
+ params +: + Specifies a pointer to the value or values that + pname + will be set to. +

Description

+ glPointParameter + assigns values to point parameters. +

+ glPointParameter + takes two arguments. + pname, + specifies which of several parameters will be modified. + params, + specifies what value or values will be assigned to the + specified parameter. +

+ The parameters that can be specified using + glPointParameter, + and their interpretations are as follows: +

+ GL_POINT_SIZE_MIN +: + param specifies, + or params + points to the lower bound to which + the derived point size is clamped. +
+ GL_POINT_SIZE_MAX +: + param specifies, + or params + points to the upper bound to which + the derived point size is clamped. +
+ GL_POINT_FADE_THRESHOLD_SIZE +: + param specifies, + or params + points to the point fade threshold. +
+ GL_POINT_DISTANCE_ATTENUATION +: + params + points to the distance attenuation function coefficients + a, + b, and + c. +

Notes

+ If the point size lower bound is greater than the upper bound, + then the point size after clamping is undefined. +

Errors

+ GL_INVALID_ENUM is generated if + pname + is not an accepted value. +

+ GL_INVALID_VALUE is generated + if assigned values for + GL_POINT_SIZE_MIN, + GL_POINT_SIZE_MAX, or + GL_POINT_FADE_THRESHOLD_SIZE + are less then zero. +

Associated Gets

+ glGet + with argument GL_POINT_DISTANCE_ATTENUATION

+ glGet + with argument GL_POINT_FADE_THRESHOLD_SIZE

+ glGet + with argument GL_POINT_SIZE_MAX

+ glGet + with argument GL_POINT_SIZE_MIN

Copyright

Name

glPointSize — specify the diameter of rasterized points

C Specification

void glPointSize( GLfloat size);

void glPointSizex( GLfixed size);

Parameters

+ size +: Specifies the diameter of rasterized points. The + initial value is 1.

Description

glPointSize + specifies the rasterized diameter of both aliased and + antialiased points. Using a point size other than 1 has + different effects, depending on whether point antialiasing is + enabled. To enable and disable point antialiasing, call + glEnable + and + glDisable + with argument + GL_POINT_SMOOTH. + Point antialiasing is initially disabled.

If point antialiasing is disabled, the actual size is + determined by rounding the supplied size to the nearest + integer. (If the rounding results in the value 0, it is as if + the point size were 1.) If the rounded size is odd, then the + center point + + xy + + of the pixel fragment that represents the point is computed + as

+ + + [ + xw + ] + + + 12 + + + [ + yw + ] + + + 12 + + +

where w + subscripts indicate window coordinates. All pixels that lie + within the square grid of the rounded size centered at + + xy + + make up the fragment. If the size is even, the center point + is

+ + + [ + xw + + + 12 + ] + + + [ + yw + + + 12 + ] + + +

and the rasterized fragment's centers are the + half-integer window coordinates within the square of the + rounded size centered at + + xy + . + All pixel fragments produced in rasterizing a nonantialiased + point are assigned the same associated data, that of the vertex + corresponding to the point.

If antialiasing is enabled, then point rasterization + produces a fragment for each pixel square that intersects the + region lying within the circle having diameter equal to the + current point size and centered at the point's + + + xw + yw + + . + The coverage value for each fragment is the window + coordinate area of the intersection of the circular region with + the corresponding pixel square. This value is saved and used in + the final rasterization step. The data associated with each + fragment is the data associated with the point being + rasterized.

Not all sizes are supported when point antialiasing is + enabled. If an unsupported size is requested, the nearest + supported size is used. Only size 1 is guaranteed to be + supported; others depend on the implementation. To query the + range of supported sizes, call + glGet + with the argument + GL_SMOOTH_POINT_SIZE_RANGE. + For aliased points, query the supported ranges + glGet + with the argument + GL_ALIASED_POINT_SIZE_RANGE.

Notes

A non-antialiased point size may be clamped to an + implementation-dependent maximum. Although this maximum cannot + be queried, it must be no less than the maximum value for + antialiased points, rounded to the nearest integer + value.

Errors

+ GL_INVALID_VALUE is generated if + size is less than or equal to 0.

Associated Gets

+ glGet + with argument GL_ALIASED_POINT_SIZE_RANGE

+ glGet + with argument GL_SMOOTH_POINT_SIZE_RANGE

Copyright

Name

glPointSizePointerOES — define an array of point sizes

C Specification

`void glPointSizePointerOES(`	GLenum `type`,
	GLsizei `stride`,
	const GLvoid * `pointer)`;

Parameters

+ type +: + Specifies the data type of each point size in the + array. Symbolic constant + GL_FIXED is accepted. + However, the common profile also accepts the symbolic constant + GL_FLOAT. + The initial value is + GL_FIXED for the common lite profile, + or GL_FLOAT for the common profile. +
+ stride +: + Specifies the byte offset between consecutive + point sizes. If stride + is 0, the point sizes are understood to be tightly packed in + the array. + The initial value is 0. +
+ pointer +: + Specifies a pointer to the point size of the + first vertex in the array. + The initial value is 0. +

Description

+ glPointSizePointerOES + specifies the location and data of an array of point sizes + to use when rendering points. + type specifies the data type of the coordinates. + stride + specifies the byte stride from one point size 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.) +

+ The point sizes supplied in the + point size arrays will be the sizes used to render + both points and point sprites. +

+ Distance-based attenuation works in conjunction with + GL_POINT_SIZE_ARRAY_OES. + If distance-based attenuation is enabled + the point size from the point size array will be attenuated as defined by + glPointParameter, + to compute the final point size. +

+ When a point size array is + specified, + type, + stride, and + pointer are saved as client-side state. +

+ If the point size array is enabled, it is used to control + the sizes used to render points and point sprites. + To enable and disable the point size array, call + glEnableClientState + and + glDisableClientState + with the argument + GL_POINT_SIZE_ARRAY_OES. + The point size array is initially disabled. +

Notes

+ glPointSizePointerOES is only supported + if the OpenGL ES version number is 1.1 or greater. +

+ If point size array is enabled, the point + size defined by + glPointSize + is ignored. +

+ glPointSizePointerOES + is typically implemented on the client side. +

Errors

+ GL_INVALID_ENUM is generated if + type is is not an accepted value. +

+ GL_INVALID_VALUE is generated if + stride is negative. +

Copyright

Name

glPolygonOffset — set the scale and units used to calculate depth + values

C Specification

`void glPolygonOffset(`	GLfloat `factor`,
	GLfloat `units)`;

`void glPolygonOffsetx(`	GLfixed `factor`,
	GLfixed `units)`;

Parameters

+ factor +: Specifies a scale factor that is used to create a + variable depth offset for each polygon. The initial value + is 0.
+ units +: Is multiplied by an implementation-specific value + to create a constant depth offset. The initial value is 0.

Description

When GL_POLYGON_OFFSET_FILL + is enabled, each fragment's depth + value will be offset after it is interpolated from the + depth + values of the appropriate vertices. The value of the offset is + + m + * + factor + + + r + * + units + , + where m + is a measurement of the change in depth relative to the screen + area of the polygon, and r + is the smallest value that is guaranteed to produce a + resolvable offset for a given implementation. The offset is + added before the depth test is performed and before the value + is written into the depth buffer.

+ glPolygonOffset + is useful for for applying decals to surfaces.

Copyright

Name

glPushMatrix, glPopMatrix — push and pop the current matrix stack

C Specification

void glPushMatrix( void);

void glPopMatrix( void);

Description

+ There is a stack of matrices for each of the matrix modes. In + GL_MODELVIEW + mode, the stack depth is at least 16. In the other modes, + GL_PROJECTION, and + GL_TEXTURE, + the depth is at least 2. The current matrix in any mode is + the matrix on the top of the stack for that mode.

glPushMatrix + pushes the current matrix stack down by one, duplicating the + current matrix. That is, after a glPushMatrix + call, the matrix on top of the stack is identical to the one + below it.

glPopMatrix + pops the current matrix stack, replacing the current matrix + with the one below it on the stack.

Initially, each of the stacks contains one matrix, an + identity matrix.

It is an error to push a full matrix stack, or to pop a + matrix stack that contains only a single matrix. In either + case, the error flag is set and no other change is made to GL + state.

Notes

+ Each texture unit has its own texture matrix stack. Use + glActiveTexture + to select the desired texture matrix stack. +

Errors

GL_STACK_OVERFLOW is generated if + glPushMatrix + is called while the current matrix stack is full.

GL_STACK_UNDERFLOW is generated if + glPopMatrix + is called while the current matrix stack contains only a single + matrix.

Associated Gets

+ glGet + with argument GL_MAX_MODELVIEW_STACK_DEPTH +

+ glGet + with argument GL_MAX_PROJECTION_STACK_DEPTH +

+ glGet + with argument GL_MAX_TEXTURE_STACK_DEPTH +

+ glGet + with argument GL_MAX_TEXTURE_UNITS +

Copyright

Name

glReadPixels — read a block of pixels from the color buffer

C Specification

`void glReadPixels(`	GLint `x`,
	GLint `y`,
	GLsizei `width`,
	GLsizei `height`,
	GLenum `format`,
	GLenum `type`,
	GLvoid * `pixels)`;

Parameters

+ x, y +: Specify the window coordinates of the first pixel + that is read from the color buffer. This location is the + lower left corner of a rectangular block of pixels.
+ width, height +: Specify the dimensions of the pixel rectangle. + width and height + of one correspond to a single pixel.
+ format +: Specifies the format of the pixel data. Must be either + GL_RGBA or the value of + GL_IMPLEMENTATION_COLOR_READ_FORMAT_OES.
+ type +: Specifies the data type of the pixel data. Must be either + GL_UNSIGNED_BYTE or the value of + GL_IMPLEMENTATION_COLOR_READ_TYPE_OES.
+ pixels +: Returns the pixel data.

Description

glReadPixels + returns pixel data from the color buffer, starting with the + pixel whose lower left corner is at location + (x, y), + into client memory starting at location + pixels. + The processing of the pixel data before it is placed into + client memory can be controlled with + glPixelStorei. +

glReadPixels + returns values from each pixel with lower left corner at + + + x+i + y+j + + + for + + 0<=i<width + + and + + 0<=j<height + . + This pixel is said to be the ith pixel + in the jth row. + Pixels are returned in row order from the lowest to the + highest row, left to right in each row.

format + specifies the format of the returned pixel values; accepted values are:

GL_ALPHA
GL_RGB
GL_RGBA

+ RGBA color components are read from the color buffer. + Each color component is converted to floating point such that zero intensity + maps to 0.0 and full intensity maps to 1.0. +

Unneeded data is then discarded. For example, + GL_ALPHA + discards the red, green, and blue components, while + GL_RGB + discards only the alpha component. + GL_LUMINANCE + computes a single-component value as the sum of the red, green, + and blue components, and + GL_LUMINANCE_ALPHA + does the same, while keeping alpha as a second value. The final + values are clamped to the range [0, 1].

Finally, the components are converted to the proper, as + specified by type where each + component is multiplied by + + 2n-1 + , + where n is the number of bits + per component.

Return values are placed in memory as follows. If + format is + GL_ALPHA, + a single value is returned and the data for the + ith pixel in the + jth row is placed in location + + j*width+i + . + GL_RGB returns three values and + GL_RGBA returns four values for each pixel, with all values + corresponding to a single pixel occupying contiguous space in + pixels. + Storage parameter GL_PACK_ALIGNMENT set by + glPixelStorei, + affects the way that data is written into memory. See + glPixelStorei + for a description.

Notes

+ Only two format/type parameter pairs are + accepted. GL_RGBA/GL_UNSIGNED_BYTE is + always accepted, and the other acceptable pair can be discovered by querying + GL_IMPLEMENTATION_COLOR_READ_FORMAT_OES and + GL_IMPLEMENTATION_COLOR_READ_TYPE_OES. +

Values for pixels that lie outside the window connected + to the current GL context are undefined.

If an error is generated, no change is made to the + contents of pixels.

Errors

GL_INVALID_ENUM is generated if + format is not + GL_RGBA or the value of + GL_IMPLEMENTATION_COLOR_READ_FORMAT_OES.

GL_INVALID_ENUM is generated if + type is not + GL_UNSIGNED_BYTE or the value of + GL_IMPLEMENTATION_COLOR_READ_TYPE_OES.

GL_INVALID_VALUE is generated if either + width or + height is negative.

+ GL_INVALID_OPERATION is generated if type is + GL_UNSIGNED_SHORT_5_6_5 + and format is not GL_RGB. +

+ GL_INVALID_OPERATION is generated if type is + GL_UNSIGNED_SHORT_4_4_4_4 or + GL_UNSIGNED_SHORT_5_5_5_1 + and format is not GL_RGBA. +

+ GL_INVALID_OPERATION is generated if format + and type are neither GL_RGBA and + GL_UNSIGNED_BYTE, respectively, nor the format/type pair + returned by querying GL_IMPLEMENTATION_COLOR_READ_FORMAT_OES + and GL_IMPLEMENTATION_COLOR_READ_TYPE_OES. +

Associated Gets

+ glGet + with argument GL_IMPLEMENTATION_COLOR_READ_FORMAT_OES

+ glGet + with argument GL_IMPLEMENTATION_COLOR_READ_TYPE_OES

+ glGet with argument GL_PACK_ALIGNMENT +

Copyright

Name

glRotate — multiply the current matrix by a rotation matrix

C Specification

`void glRotatef(`	GLfloat `angle`,
	GLfloat `x`,
	GLfloat `y`,
	GLfloat `z)`;

`void glRotatex(`	GLfixed `angle`,
	GLfixed `x`,
	GLfixed `y`,
	GLfixed `z)`;

Parameters

+ angle +: Specifies the angle of rotation, in degrees.
+ x, + y, + z +: Specify the + x, + y, and + z + coordinates of a vector, respectively.

Description

glRotate produces a rotation of + angle degrees around the vector + + xyz + . + The current matrix (see + glMatrixMode) + is multiplied by a rotation matrix with the product replacing + the current matrix, as if + glMultMatrix + were called with the following matrix as its argument:

+ + ( + + + + x2 + (1-c) + +c + + + xy + (1-c) + -zs + + + xz + (1-c) + +ys + + 0 + + + + xy + (1-c) + +zs + + + y2 + (1-c) + +c + + + yz + (1-c) + -xs + + 0 + + + + xz + (1-c) + -ys + + + yz + (1-c) + +xs + + + z2 + (1-c) + +c + + 0 + + + 0 + 0 + 0 + 1 + + + ) + +

Where + + c=cosangle + , + + s=sinangle + , + and + + ||xyz|| + =1 + , + (if not, the GL will normalize this vector).

If the matrix mode is either GL_MODELVIEW or + GL_PROJECTION, all objects drawn after + glRotate is called are rotated. Use + glPushMatrix + and + glPopMatrix + to save and restore the unrotated coordinate system.

Notes

This rotation follows the right-hand rule, so if the vector + + xyz + + points toward the user, the rotation will be counterclockwise.

Associated Gets

+ glGet with argument GL_MATRIX_MODE +

+ glGet with argument GL_MODELVIEW_MATRIX +

+ glGet with argument GL_PROJECTION_MATRIX +

+ glGet with argument GL_TEXTURE_MATRIX +

Copyright

Name

glSampleCoverage — specify mask to modify multisampled pixel fragments

C Specification

`void glSampleCoverage(`	GLclampf `value`,
	GLboolean `invert)`;

`void glSampleCoveragex(`	GLclampx `value`,
	GLboolean `invert)`;

Parameters

+ value +: Specifies the coverage of the modification mask. + The value is clamped to the range [0, 1], where 0 represents + no coverage and 1 full coverage. The initial value is 1.
+ invert +: Specifies whether the modification mask implied by + value is inverted or not. + The initial value is GL_FALSE. +

Description

glSampleCoverage defines a mask to modify + the coverage of multisampled pixel fragments. This capability is used + for antialiased screen-door transparency and smooth transitions between + two renderings of an object (often for level-of-detail management in + simulation systems).

+ When multisampling is enabled (see + glEnable + with argument + GL_MULTISAMPLE) a ``fragment mask'' is computed for + each fragment + generated by a primitive. This mask reflects the amount of the pixel + covered by the fragment, and determines the frame buffer samples that may + be affected by the fragment.

+ If conversion of alpha values to masks is enabled + (glEnable + with argument + GL_SAMPLE_ALPHA_TO_COVERAGE), + the fragment alpha value is used to + generate a temporary modification mask which is then ANDed with the + fragment mask. One way to interpret this is as a form of dithering: a + multivalued alpha (coverage or opacity) for the whole fragment is + converted to simple binary values of coverage at many locations (the + samples).

+ After conversion of alpha values to masks, if replacement of alpha values + is enabled + (glEnable + with argument + GL_SAMPLE_ALPHA_TO_ONE), the + fragment's alpha is set to the maximum allowable value.

+ Finally, if fragment mask modification is enabled + (glEnable + with argument + GL_SAMPLE_COVERAGE), + glSampleCoverage defines an additional modification + mask. value is used to generate a modification mask in much the same way + alpha was used above. If invert is GL_TRUE, + then the modification mask + specified by value will be inverted. The final modification mask will + then be ANDed with the fragment mask resulting from the previous steps. + This can be viewed as an ``override'' control that selectively fades the + effects of multisampled fragments.

Note that + glSampleCoverage(value, GL_TRUE) + is not necessarily equivalent to + glSampleCoverage(1.0 - value, GL_FALSE); + due to round-off and other + issues, complementing the coverage will not necessarily yield an inverted + modification mask.

Associated Gets

+ glGet with argument GL_SAMPLE_COVERAGE_VALUE +

+ glGet with argument GL_SAMPLE_COVERAGE_INVERT +

+ glIsEnabled with argument GL_SAMPLE_ALPHA_TO_COVERAGE +

+ glIsEnabled with argument GL_SAMPLE_COVERAGE +

Copyright

Name

glScale — multiply the current matrix by a general scaling + matrix

C Specification

`void glScalef(`	GLfloat `x`,
	GLfloat `y`,
	GLfloat `z)`;

`void glScalex(`	GLfixed `x`,
	GLfixed `y`,
	GLfixed `z)`;

Parameters

+ x, + y, + z +: Specify scale factors along the + x, + y, and + z axes, respectively.

Description

+ glScale produces a nonuniform scaling along the + x, + y, and + z + axes. The three parameters indicate the desired scale factor + along each of the three axes.

The current matrix (see + glMatrixMode) + is multiplied by this scale matrix, and the product replaces + the current matrix as if glScale + were called with the following matrix as its argument:

+ + ( + + + x + 0 + 0 + 0 + + + 0 + y + 0 + 0 + + + 0 + 0 + z + 0 + + + 0 + 0 + 0 + 1 + + + ) + +

If the matrix mode is either GL_MODELVIEW or + GL_PROJECTION, all objects drawn after + glScale is called are scaled.

Use + glPushMatrix + and + glPopMatrix + to save and restore the unscaled coordinate system.

Notes

If scale factors other than 1 are applied to the + modelview matrix and lighting is enabled, lighting often + appears wrong. In that case, enable automatic normalization of + normals by calling + glEnable + with the argument GL_NORMALIZE.

Associated Gets

+ glGet with argument GL_MATRIX_MODE +

+ glGet with argument GL_MODELVIEW_MATRIX +

+ glGet with argument GL_PROJECTION_MATRIX +

+ glGet with argument GL_TEXTURE_MATRIX +

Copyright

Name

glScissor — define the scissor box

C Specification

`void glScissor(`	GLint `x`,
	GLint `y`,
	GLsizei `width`,
	GLsizei `height)`;

Parameters

+ x, y +: Specify the lower left corner of the scissor box, in pixels. + The initial value is (0, 0).
+ width, height +: Specify the width and height of the scissor box. + When a GL context is first attached to a surface (e.g. window), + width and height + are set to the dimensions of that surface.

Description

+ glScissor + defines a rectangle, called the scissor box, in window + coordinates. The first two arguments, + x and + y, specify the lower left corner of the box. + width and height + specify the width and height of the box.

To enable and disable the scissor test, call + glEnable and + glDisable + with argument GL_SCISSOR_TEST. + The scissor test is initially disabled. While scissor test is enabled, + only pixels that lie within the scissor box can be modified by + drawing commands. Window coordinates have integer values at the + shared corners of frame buffer pixels. + glScissor(0, 0, 1, 1) + allows modification of only the lower left pixel in the window, + and glScissor(0, 0, 0, 0) + doesn't allow modification of any pixels in the window.

When the scissor test is disabled, it is as though the + scissor box includes the entire window.

Errors

GL_INVALID_VALUE is generated if either + width or height + is negative.

Copyright

Name

glShadeModel — select flat or smooth shading

C Specification

void glShadeModel( GLenum mode);

Parameters

+ mode +: Specifies a symbolic value representing a shading + technique. Accepted values are GL_FLAT and + GL_SMOOTH. The initial value is + GL_SMOOTH.

Description

GL primitives can have either flat or smooth shading. + Smooth shading, the default, causes the computed colors of + vertices to be interpolated as the primitive is rasterized, + typically assigning different colors to each resulting pixel + fragment. Flat shading selects the computed color of just one + vertex and assigns it to all the pixel fragments generated by + rasterizing a single primitive. In either case, the computed + color of a vertex is the result of lighting if lighting is + enabled, or it is the current color at the time the vertex was + specified if lighting is disabled.

+ Flat and smooth shading are indistinguishable for points. + Starting when glDrawArrays + or glDrawElements + is issued and counting vertices and + primitives from 1, the GL gives each flat-shaded line segment + i + the + computed color of vertex + + + + i + + + 1 + + , + its second vertex. + Counting similarly from 1, + the GL gives each flat-shaded polygon the computed color of the vertex listed + in the following table. + This is the last vertex to specify the polygon. +

+

+ Primitive Type of Polygon + i +	+ Vertex +
+ Triangle strip +	+ + + + i + + + 2 + + +
+ Triangle fan +	+ + + + i + + + 2 + + +
+ Independent triangle +	+ + + + 3 + ⁢ + i + + +

Flat and smooth shading are specified by + glShadeModel with + mode set to + GL_FLAT and + GL_SMOOTH, respectively.

Errors

GL_INVALID_ENUM is generated if + mode is any value other than + GL_FLAT or GL_SMOOTH.

Copyright

Name

glStencilFunc — set function and reference value for stencil + testing

C Specification

`void glStencilFunc(`	GLenum `func`,
	GLint `ref`,
	GLuint `mask)`;

Parameters

+ func +: Specifies the test function. Eight tokens are valid: + GL_NEVER, + GL_LESS, + GL_LEQUAL, + GL_GREATER, + GL_GEQUAL, + GL_EQUAL, + GL_NOTEQUAL, and + GL_ALWAYS. The initial value is + GL_ALWAYS.
+ ref +: Specifies the reference value for the stencil test. + ref + is clamped to the range + + [ + 0 + , + 2n-1 + ] + , + where n is + the number of bitplanes in the stencil buffer. The + initial value is 0.
+ mask +: Specifies a mask that is ANDed with both the + reference value and the stored stencil value when the + test is done. The initial value is all 1's.

Description

Stenciling, like depth-buffering, enables and disables + drawing on a per-pixel basis. + Stencil planes are first drawn into using GL drawing primitives, then + geometry and images are rendered using the stencil planes to mask out + portions of the screen. + Stenciling is typically used in multipass rendering algorithms + to achieve special effects, such as decals, outlining, and + constructive solid geometry rendering.

The stencil test conditionally eliminates a pixel based + on the outcome of a comparison between the reference value and + the value in the stencil buffer. To enable and disable stencil + test, call + glEnable and + glDisable + with argument + GL_STENCIL_TEST. + Stencil test is initially disabled. + To specify actions based on the outcome of the stencil test, call + glStencilOp. +

+ func + is a symbolic constant that determines the stencil comparison + function. It accepts one of eight values, shown in the + following list. ref + is an integer reference value that is used in the stencil + comparison. It is clamped to the range + + [ + 0 + , + 2n-1 + ] + , where n + is the number of bitplanes in the stencil buffer. + mask + is bitwise ANDed with both the reference value and the stored + stencil value, with the ANDed values participating in the + comparison.

If stencil + represents the value stored in the corresponding stencil buffer + location, the following list shows the effect of each + comparison function that can be specified by + func. + Only if the comparison succeeds is the pixel passed through + to the next stage in the rasterization process (see + glStencilOp). + All tests treat stencil + values as unsigned integers in the range + + [ + 0 + , + 2n-1 + ] + , where n + is the number of bitplanes in the stencil buffer.

The following values are accepted by + func:

+ GL_NEVER +: Always fails.
+ GL_LESS +: Passes if + + + ref + & + mask + + < + + stencil + & + mask + + .
+ GL_LEQUAL +: Passes if + + + ref + & + mask + + <= + + stencil + & + mask + + .
+ GL_GREATER +: Passes if + + + ref + & + mask + + > + + stencil + & + mask + + .
+ GL_GEQUAL +: Passes if + + + ref + & + mask + + >= + + stencil + & + mask + + .
+ GL_EQUAL +: Passes if + + + ref + & + mask + + = + + stencil + & + mask + + .
+ GL_NOTEQUAL +: Passes if + + + ref + & + mask + + < + > + + stencil + & + mask + + .
+ GL_ALWAYS +: Always passes.

Notes

Initially, the stencil test is disabled. If there is no + stencil buffer, no stencil modification can occur and it is as + if the stencil test always passes.

Errors

GL_INVALID_ENUM is generated if + func is not one of the eight accepted values.

Associated Gets

+ glGet + with argument GL_STENCIL_BITS +

Copyright

Name

glStencilMask — control the writing of individual bits in the + stencil planes

C Specification

void glStencilMask( GLuint mask);

Parameters

+ mask +: Specifies a bit mask to enable and disable writing + of individual bits in the stencil planes. The initial value + is all 1's.

Description

glStencilMask + controls the writing of individual bits in the stencil planes. + The least significant n + bits of mask, where + n + is the number of bits in the stencil buffer, specify a mask. + Where a 1 appears in the mask, it's possible to write to the + corresponding bit in the stencil buffer. Where a 0 appears, the + corresponding bit is write-protected. Initially, all bits are + enabled for writing.

Associated Gets

+ glGet + with argument GL_STENCIL_WRITEMASK or + GL_STENCIL_BITS +

Copyright

Name

glStencilOp — set stencil test actions

C Specification

`void glStencilOp(`	GLenum `fail`,
	GLenum `zfail`,
	GLenum `zpass)`;

Parameters

+ fail +: Specifies the action to take when the stencil test + fails. Six symbolic constants are accepted: + GL_KEEP, + GL_ZERO, + GL_REPLACE, + GL_INCR, + GL_DECR, and + GL_INVERT. The initial value is + GL_KEEP.
+ zfail +: Specifies the stencil action when the stencil test + passes, but the depth test fails. + zfail accepts the same symbolic constants as + fail. The initial value is + GL_KEEP.
+ zpass +: Specifies the stencil action when both the stencil + test and the depth test pass, or when the stencil test + passes and either there is no depth buffer or depth + testing is not enabled. + zpass accepts the same symbolic constants as + fail. The initial value is + GL_KEEP.

Description

Stenciling, like depth-buffering, enables and disables + drawing on a per-pixel basis. You draw into the stencil planes + using GL drawing primitives, then render geometry and images, + using the stencil planes to mask out portions of the screen. + Stenciling is typically used in multipass rendering algorithms + to achieve special effects, such as decals, outlining, and + constructive solid geometry rendering.

The stencil test conditionally eliminates a pixel based + on the outcome of a comparison between the value in the stencil + buffer and a reference value. To enable and disable stencil test, call + glEnable and + glDisable + with argument GL_STENCIL_TEST. + To control it, call + glStencilFunc. + Stenciling is initially disabled. +

glStencilOp + takes three arguments that indicate what happens to the stored + stencil value while stenciling is enabled. If the stencil test + fails, no change is made to the pixel's color or depth buffers, + and fail + specifies what happens to the stencil buffer contents. The + following six actions are possible.

+ GL_KEEP +: Keeps the current value.
+ GL_ZERO +: Sets the stencil buffer value to 0.
+ GL_REPLACE +: Sets the stencil buffer value to + ref, as specified by + glStencilFunc.
+ GL_INCR +: Increments the current stencil buffer value. Clamps + to the maximum representable unsigned value.
+ GL_DECR +: Decrements the current stencil buffer value. Clamps + to 0.
+ GL_INVERT +: Bitwise inverts the current stencil buffer value.

Stencil buffer values are treated as unsigned integers. + When incremented and decremented, values are clamped to 0 and + + 2n-1 + , + where n is the value returned by querying + GL_STENCIL_BITS.

The other two arguments to glStencilOp + specify stencil buffer actions that depend on whether + subsequent depth buffer tests succeed (zpass) + or fail + (zfail) (see + glDepthFunc). + The actions are specified using the same six symbolic constants as + fail. Note that zfail + is ignored when there is no depth buffer, or when the depth + buffer is not enabled. In these cases, fail and + zpass + specify stencil action when the stencil test fails and passes, + respectively.

Notes

If there is no + stencil buffer, no stencil modification can occur and it is as + if the stencil tests always pass, regardless of any call to + glStencilOp.

Errors

GL_INVALID_ENUM is generated if + fail, + zfail, or + zpass + is any value other than the six defined constant values.

Associated Gets

+ glGet + with argument GL_STENCIL_BITS +

Copyright

Name

glTexCoordPointer — define an array of texture coordinates

C Specification

`void glTexCoordPointer(`	GLint `size`,
	GLenum `type`,
	GLsizei `stride`,
	const GLvoid * `pointer)`;

Parameters

+ size +

Specifies the number of coordinates per array + element. Must be 2, 3 or 4. The initial value is 4.

+ type +

Specifies the data type of each texture coordinate. + Symbolic constants + GL_BYTE, + GL_SHORT, and + GL_FIXED are accepted. + However, the initial value is + GL_FLOAT.

+ The common profile accepts the symbolic constant + GL_FLOAT as well. +

+ stride +

Specifies the byte offset between consecutive array + elements. If stride + is 0, the array elements are understood to be tightly + packed. The initial value is 0.

+ pointer +

Specifies a pointer to the first coordinate of the + first element in the array. The initial value is 0.

Description

glTexCoordPointer + specifies the location and data of an array of texture + coordinates to use when rendering. size + specifies the number of coordinates per element, and must be 2, + 3, or 4. type + specifies the data type of each texture coordinate and + stride + specifies the byte stride from one array element 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.)

When a texture coordinate array is specified, + size, + type, + stride, and + pointer are saved as client-side state.

+ If the texture coordinate array is enabled, it is used when + glDrawArrays, + or + glDrawElements + is called. + To enable and disable the texture coordinate array for the client-side + active texture unit, call + glEnableClientState + and + glDisableClientState + with the argument + GL_TEXTURE_COORD_ARRAY. + The texture coordinate array is initially disabled for all client-side + active texture units and isn't accessed when + glDrawArrays or + glDrawElements + is called.

Use + glDrawArrays + to construct a sequence of primitives (all of the same type) + from prespecified vertex and vertex attribute arrays. Use + glDrawElements + to construct a sequence of primitives by indexing vertices and + vertex attributes.

Notes

+ glTexCoordPointer + is typically implemented on the client side.

+ glTexCoordPointer + updates the texture coordinate array state of the client-side active + texture unit, specified with + glClientActiveTexture.

Errors

GL_INVALID_VALUE is generated if + size is not 2, 3, or 4.

GL_INVALID_ENUM is generated if + type is not an accepted value.

GL_INVALID_VALUE is generated if + stride is negative.

Copyright

Name

glTexEnv — set texture environment parameters

C Specification

`void glTexEnvf(`	GLenum `target`,
	GLenum `pname`,
	GLfloat `param)`;

`void glTexEnvi(`	GLenum `target`,
	GLenum `pname`,
	GLint `param)`;

`void glTexEnvx(`	GLenum `target`,
	GLenum `pname`,
	GLfixed `param)`;

Parameters

target: + Specifies a texture environment. + May be GL_TEXTURE_ENV or GL_POINT_SPRITE_OES. +
pname: + Specifies the symbolic name of a single-valued texture environment parameter. + May be either GL_TEXTURE_ENV_MODE, + GL_COMBINE_RGB, + GL_COMBINE_ALPHA, + GL_SRC0_RGB, + GL_SRC1_RGB, + GL_SRC2_RGB, + GL_SRC0_ALPHA, + GL_SRC1_ALPHA, + GL_SRC2_ALPHA, + GL_OPERAND0_RGB, + GL_OPERAND1_RGB, + GL_OPERAND2_RGB, + GL_OPERAND0_ALPHA, + GL_OPERAND1_ALPHA, + GL_OPERAND2_ALPHA, + GL_RGB_SCALE, + GL_ALPHA_SCALE, or + GL_COORD_REPLACE_OES. +
param: + Specifies a single symbolic constant, one of GL_ADD, GL_ADD_SIGNED, + GL_DOT3_RGB, GL_DOT3_RGBA, GL_INTERPOLATE, GL_MODULATE, GL_DECAL, + GL_BLEND, GL_REPLACE, GL_SUBTRACT, GL_COMBINE, + GL_TEXTURE, GL_CONSTANT, GL_PRIMARY_COLOR, GL_PREVIOUS, + GL_SRC_COLOR, GL_ONE_MINUS_SRC_COLOR, GL_SRC_ALPHA, + GL_ONE_MINUS_SRC_ALPHA, + a single boolean value for the point sprite texture coordinate replacement, + or 1.0, 2.0, or 4.0 when specifying the GL_RGB_SCALE or GL_ALPHA_SCALE. +

C Specification

`void glTexEnvfv(`	GLenum `target`,
	GLenum `pname`,
	const GLfloat * `params)`;

`void glTexEnviv(`	GLenum `target`,
	GLenum `pname`,
	const GLint * `params)`;

`void glTexEnvxv(`	GLenum `target`,
	GLenum `pname`,
	const GLfixed * `params)`;

Parameters

target: + Specifies a texture environment. + May be GL_TEXTURE_ENV or GL_POINT_SPRITE_OES. +
pname: + Specifies the symbolic name of a single-valued texture environment parameter. + May be either GL_TEXTURE_ENV_MODE, + GL_TEXTURE_ENV_COLOR, + GL_COMBINE_RGB, + GL_COMBINE_ALPHA, + GL_SRC0_RGB, + GL_SRC1_RGB, + GL_SRC2_RGB, + GL_SRC0_ALPHA, + GL_SRC1_ALPHA, + GL_SRC2_ALPHA, + GL_OPERAND0_RGB, + GL_OPERAND1_RGB, + GL_OPERAND2_RGB, + GL_OPERAND0_ALPHA, + GL_OPERAND1_ALPHA, + GL_OPERAND2_ALPHA, + GL_RGB_SCALE, + GL_ALPHA_SCALE, or + GL_COORD_REPLACE_OES. +
params: + Specifies a pointer to a parameter array that contains either an RGBA color, + a single symbolic constant, one of GL_ADD, GL_ADD_SIGNED, + GL_DOT3_RGB, GL_DOT3_RGBA, GL_INTERPOLATE, GL_MODULATE, GL_DECAL, + GL_BLEND, GL_REPLACE, GL_SUBTRACT, GL_COMBINE, + GL_TEXTURE, GL_CONSTANT, GL_PRIMARY_COLOR, GL_PREVIOUS, + GL_SRC_COLOR, GL_ONE_MINUS_SRC_COLOR, GL_SRC_ALPHA, + GL_ONE_MINUS_SRC_ALPHA, + a single boolean value for the point sprite texture coordinate replacement, + or 1.0, 2.0, or 4.0 when specifying the GL_RGB_SCALE or GL_ALPHA_SCALE. +

Description

+ A texture environment specifies how texture values are interpreted when a + fragment is textured. When target is GL_POINT_SPRITE_OES, + pname must be GL_COORD_REPLACE_OES. When target is + GL_TEXTURE_ENV, pname can be GL_TEXTURE_ENV_MODE, + GL_TEXTURE_ENV_COLOR, GL_COMBINE_RGB, GL_COMBINE_ALPHA, + GL_RGB_SCALE, GL_ALPHA_SCALE, + GL_OPERAND0_RGB, GL_OPERAND1_RGB, GL_OPERAND2_RGB, + GL_OPERAND0_ALPHA, GL_OPERAND1_ALPHA, GL_OPERAND2_ALPHA, + GL_SRC0_RGB, GL_SRC1_RGB, GL_SRC2_RGB, + GL_SRC0_ALPHA, GL_SRC1_ALPHA, or GL_SRC2_ALPHA. +

+ If pname is GL_TEXTURE_ENV_MODE, + then params is (or points to) the symbolic name of a texture function. + Six texture functions may be specified: + GL_ADD, + GL_MODULATE, + GL_DECAL, + GL_BLEND, + GL_REPLACE, or + GL_COMBINE. +

+ The following table shows the correspondence of filtered texture + values + R + t, + G + t, + B + t, + A + t, + L + t + to texture source components. + C + s + and + A + s + are used by the texture functions described below. +

+

+ Texture Base Internal Format +	+ C + s +	+ A + s +
+ `GL_ALPHA` +	+ (0, 0, 0) +	+ A + t +
+ `GL_LUMINANCE` +	+ ( + L + t, + L + t, + L + t + ) +	+ 1 +
+ `GL_LUMINANCE_ALPHA` +	+ ( + L + t, + L + t, + L + t + ) +	+ A + t +
+ `GL_RGB` +	+ ( + R + t, + G + t, + B + t + ) +	+ 1 +
+ `GL_RGBA` +	+ ( + R + t, + G + t, + B + t + ) +	+ A + t +

+ A texture function acts on the fragment to be textured using + the texture image value that applies to the fragment + (see glTexParameter) + and produces an RGBA color for that fragment. + The following table shows how the RGBA color is produced for each + of the first five texture functions that can be chosen. + C + is a triple of color values (RGB) and + A + is the associated alpha value. + RGBA values extracted from a texture image are in the range [0,1]. + The subscript + p + refers to the color computed from the previous texture stage (or the incoming fragment if processing texture stage 0), + the subscript + s + to the texture source color, + the subscript + c + to the texture environment color, + and the subscript + v + indicates a value produced by the texture function. +

+

+ Texture Base Internal Format +	+ `Value` +	+ `GL_REPLACE` Function +	+ `GL_MODULATE` Function +	+ `GL_DECAL` Function +	+ `GL_BLEND` Function +	+ `GL_ADD` Function +
+ `GL_ALPHA` +	+ + + + C + v + + = + + +	+ + + + C + p + + + +	+ + + + C + p + + + +	+ undefined +	+ + + + C + p + + + +	+ + + + C + p + + + +
+	+ + + + A + v + + = + + +	+ + + + A + s + + + +	+ + + + + A + p + + ⁢ + A + s + + + + +	+	+ + + + A + v + + = + + A + p + + ⁢ + A + s + + + + +	+ + + + + A + p + + ⁢ + A + s + + + + +
+ `GL_LUMINANCE` +	+ + + + C + v + + = + + +	+ + + + C + s + + + +	+ + + + + C + p + + ⁢ + C + s + + + + +	+ undefined +	+ + + + + C + p + + ⁢ + + + 1 + - + C + s + + + + + + C + c + + ⁢ + C + s + + + + +	+ + + + + C + p + + + + C + s + + + + +
+ (or 1) +	+ + + + A + v + + = + + +	+ + + + A + p + + + +	+ + + + A + p + + + +	+	+ + + + A + p + + + +	+ + + + A + p + + + +
+ `GL_LUMINANCE_ALPHA` +	+ + + + C + v + + = + + +	+ + + + C + s + + + +	+ + + + + C + p + + ⁢ + C + s + + + + +	+ undefined +	+ + + + + C + p + + ⁢ + + + 1 + - + C + s + + + + + + C + c + + ⁢ + C + s + + + + +	+ + + + + C + p + + + + C + s + + + + +
+ (or 2) +	+ + + + A + v + + = + + +	+ + + + A + s + + + +	+ + + + + A + p + + ⁢ + A + s + + + + +	+	+ + + + + A + p + + ⁢ + A + s + + + + +	+ + + + + A + p + + ⁢ + A + s + + + + +
+ `GL_RGB` +	+ + + + C + v + + = + + +	+ + + + C + s + + + +	+ + + + + C + p + + ⁢ + C + s + + + + +	+ + + + C + s + + + +	+ + + + + C + p + + ⁢ + + + 1 + - + C + s + + + + + + C + c + + ⁢ + C + s + + + + +	+ + + + + C + p + + + + C + s + + + + +
+ (or 3) +	+ + + + A + v + + = + + +	+ + + + A + p + + + +	+ + + + A + p + + + +	+ + + + A + p + + + +	+ + + + A + p + + + +	+ + + + A + p + + + +
+ `GL_RGBA` +	+ + + + C + v + + = + + +	+ + + + C + s + + + +	+ + + + + C + p + + ⁢ + C + s + + + + +	+ + + + + C + p + + ⁢ + + + 1 + - + A + s + + + + + + C + s + + ⁢ + A + s + + + + +	+ + + + + C + p + + ⁢ + + + 1 + - + C + s + + + + + + C + c + + ⁢ + C + s + + + + +	+ + + + + C + p + + + + C + s + + + + +
+ (or 4) +	+ + + + A + v + + = + + +	+ + + + A + s + + + +	+ + + + + A + p + + ⁢ + A + s + + + + +	+ + + + A + p + + + +	+ + + + + A + p + + ⁢ + A + s + + + + +	+ + + + + A + p + + ⁢ + A + s + + + + +

+ If pname is GL_TEXTURE_ENV_MODE, and params is GL_COMBINE, the + form of the texture function depends on the values of GL_COMBINE_RGB + and GL_COMBINE_ALPHA. +

+ The following describes how the texture sources, as specified by + GL_SRC0_RGB, GL_SRC1_RGB, GL_SRC2_RGB, + GL_SRC0_ALPHA, GL_SRC1_ALPHA, and GL_SRC2_ALPHA, + are combined to produce a final texture color. In the following tables, + GL_SRC0_c is represented by + Arg0, + GL_SRC1_c is + represented by + Arg1, + and GL_SRC2_c is represented by + Arg2. +

+ GL_COMBINE_RGB accepts any of GL_REPLACE, GL_MODULATE, + GL_ADD, GL_ADD_SIGNED, GL_INTERPOLATE, GL_SUBTRACT, + GL_DOT3_RGB, or GL_DOT3_RGBA. +

+

+ `GL_COMBINE_RGB` +	+ Texture Function +
+ `GL_REPLACE` +	+ Arg0 +
+ `GL_MODULATE` +	+ + + + Arg0 + × + Arg1 + + +
+ `GL_ADD` +	+ + + + Arg0 + + + Arg1 + + +
+ `GL_ADD_SIGNED` +	+ + + + Arg0 + + + Arg1 + - + 0.5 + + +
+ `GL_INTERPOLATE` +	+ + + + + Arg0 + × + Arg2 + + + + + Arg1 + × + + + 1 + - + Arg2 + + + + + +
+ `GL_SUBTRACT` +	+ + + + Arg0 + - + Arg1 + + +
+ `GL_DOT3_RGB` + or + `GL_DOT3_RGBA` +	+ + + + 4 + × + + + + + + + + Arg0 + r + + + - + 0.5 + + + × + + + + Arg1 + r + + + - + 0.5 + + + + + + + + + + + + Arg0 + g + + + - + 0.5 + + + × + + + + Arg1 + g + + + - + 0.5 + + + + + + + + + + + + Arg0 + b + + + - + 0.5 + + + × + + + + Arg1 + b + + + - + 0.5 + + + + + + + + +

+ The scalar results for GL_DOT3_RGB and GL_DOT3_RGBA are placed + into each of the 3 (RGB) or 4 (RGBA) components on output. +

+ Likewise, GL_COMBINE_ALPHA accepts any of GL_REPLACE, + GL_MODULATE, GL_ADD, GL_ADD_SIGNED, GL_INTERPOLATE, or + GL_SUBTRACT. The following table describes how alpha values are + combined: +

+

+ `GL_COMBINE_ALPHA` +	+ Texture Function +
+ `GL_REPLACE` +	+ Arg0 +
+ `GL_MODULATE` +	+ + + + Arg0 + × + Arg1 + + +
+ `GL_ADD` +	+ + + + Arg0 + + + Arg1 + + +
+ `GL_ADD_SIGNED` +	+ + + + Arg0 + + + Arg1 + - + 0.5 + + +
+ `GL_INTERPOLATE` +	+ + + + + Arg0 + × + Arg2 + + + + + Arg1 + × + + + 1 + - + Arg2 + + + + + +
+ `GL_SUBTRACT` +	+ + + + Arg0 + - + Arg1 + + +

+ In the following tables, the value + + + C + s + + + represents the color sampled + from the currently bound texture, + + + C + c + + + represents the constant + texture-environment color, + + + C + f + + + represents the primary color of the + incoming fragment, and + + + C + p + + + represents the color computed from the + previous texture stage or + + + C + f + + + if processing texture stage 0. Likewise, + + + A + s + + , + + + A + c + + , + + + A + f + + , + and + + + A + p + + + represent the respective + alpha values. +

+ The following table describes the values assigned to + Arg0, + Arg1, + and + Arg2 + based upon the RGB sources and operands: +

+

+ `GL_SRCn_RGB` +	+ `GL_OPERANDn_RGB` +	+ Argument Value +
+ `GL_TEXTURE` +	+ `GL_SRC_COLOR` +	+ + + + C + s + + + +
+	+ `GL_ONE_MINUS_SRC_COLOR` +	+ + + + 1 + - + + C + s + + + + +
+	+ `GL_SRC_ALPHA` +	+ + + + A + s + + + +
+	+ `GL_ONE_MINUS_SRC_ALPHA` +	+ + + + 1 + - + + A + s + + + + +
+ `GL_TEXTUREn` +	+ `GL_SRC_COLOR` +	+ + + + C + s + + + +
+	+ `GL_ONE_MINUS_SRC_COLOR` +	+ + + + 1 + - + + C + s + + + + +
+	+ `GL_SRC_ALPHA` +	+ + + + A + s + + + +
+	+ `GL_ONE_MINUS_SRC_ALPHA` +	+ + + + 1 + - + + A + s + + + + +
+ `GL_CONSTANT` +	+ `GL_SRC_COLOR` +	+ + + + C + c + + + +
+	+ `GL_ONE_MINUS_SRC_COLOR` +	+ + + + 1 + - + + C + c + + + + +
+	+ `GL_SRC_ALPHA` +	+ + + + A + c + + + +
+	+ `GL_ONE_MINUS_SRC_ALPHA` +	+ + + + 1 + - + + A + c + + + + +
+ `GL_PRIMARY_COLOR` +	+ `GL_SRC_COLOR` +	+ + + + C + f + + + +
+	+ `GL_ONE_MINUS_SRC_COLOR` +	+ + + + 1 + - + + C + f + + + + +
+	+ `GL_SRC_ALPHA` +	+ + + + A + f + + + +
+	+ `GL_ONE_MINUS_SRC_ALPHA` +	+ + + + 1 + - + + A + f + + + + +
+ `GL_PREVIOUS` +	+ `GL_SRC_COLOR` +	+ + + + C + p + + + +
+	+ `GL_ONE_MINUS_SRC_COLOR` +	+ + + + 1 + - + + C + p + + + + +
+	+ `GL_SRC_ALPHA` +	+ + + + A + p + + + +
+	+ `GL_ONE_MINUS_SRC_ALPHA` +	+ + + + 1 + - + + A + p + + + + +

+ For GL_TEXTUREn sources, + + + C + s + + + and + + + A + s + + + represent the color + and alpha, respectively, produced from texture stage + n. +

+ The follow table describes the values assigned to + Arg0, + Arg1, + and + Arg2 + based upon the alpha sources and operands: +

+

+ `GL_SRCn_ALPHA` +	+ `GL_OPERANDn_ALPHA` +	+ Argument Value +
+ `GL_TEXTURE` +	+ `GL_SRC_ALPHA` +	+ + + + A + s + + + +
+	+ `GL_ONE_MINUS_SRC_ALPHA` +	+ + + + 1 + - + + A + s + + + + +
+ `GL_TEXTUREn` +	+ `GL_SRC_ALPHA` +	+ + + + A + s + + + +
+	+ `GL_ONE_MINUS_SRC_ALPHA` +	+ + + + 1 + - + + A + s + + + + +
+ `GL_CONSTANT` +	+ `GL_SRC_ALPHA` +	+ + + + A + c + + + +
+	+ `GL_ONE_MINUS_SRC_ALPHA` +	+ + + + 1 + - + + A + c + + + + +
+ `GL_PRIMARY_COLOR` +	+ `GL_SRC_ALPHA` +	+ + + + A + f + + + +
+	+ `GL_ONE_MINUS_SRC_ALPHA` +	+ + + + 1 + - + + A + f + + + + +
+ `GL_PREVIOUS` +	+ `GL_SRC_ALPHA` +	+ + + + A + p + + + +
+	+ `GL_ONE_MINUS_SRC_ALPHA` +	+ + + + 1 + - + + A + p + + + + +

+ The RGB and alpha results of the texture function are multipled by the + values of GL_RGB_SCALE and GL_ALPHA_SCALE, respectively, and + clamped to the range + + + + 0 + 1 + + . +

+ If pname is GL_TEXTURE_ENV_COLOR, + params is a pointer to an array that holds an RGBA color consisting of four + values. + Integer color components are interpreted linearly such that the most + positive integer maps to 1.0, + and the most negative integer maps to -1.0. + The values are clamped to the range [0,1] when they are specified. + + + C + c + + + takes these four values. +

+ GL_TEXTURE_ENV_MODE defaults to GL_MODULATE and + GL_TEXTURE_ENV_COLOR defaults to (0, 0, 0, 0). +

+ If target is GL_POINT_SPRITE_OES and pname is GL_COORD_REPLACE_OES, the boolean value specified + is used to either enable or disable point sprite texture coordinate replacement. The default value is GL_FALSE. +

Notes

+ glTexEnv controls + the texture environment for the current active texture unit, selected by + glActiveTexture. +

+ GL_POINT_SPRITE_OES and GL_COORD_REPLACE_OES are available + only if the OpenGL ES version is 1.1 or greater. +

Errors

+ GL_INVALID_ENUM is generated when target or pname is not + one of the accepted defined values, + or when params should have a defined constant value + (based on the value of pname) + and does not. +

+ GL_INVALID_VALUE is generated if the params value for + GL_RGB_SCALE or GL_ALPHA_SCALE are not one of 1.0, 2.0, + or 4.0. +

Associated Gets

+ glGetTexEnv +

Copyright

Name

glTexImage2D — specify a two-dimensional texture image

C Specification

`void glTexImage2D(`	GLenum `target`,
	GLint `level`,
	GLint `internalformat`,
	GLsizei `width`,
	GLsizei `height`,
	GLint `border`,
	GLenum `format`,
	GLenum `type`,
	const GLvoid * `pixels)`;

Parameters

+ target +: Specifies the target texture. Must be + GL_TEXTURE_2D.
+ level +: Specifies the level-of-detail number. Level 0 is + the base image level. Level n is the + nth mipmap reduction image. + Must be greater or equal 0.
+ internalformat +: Specifies the color components in the + texture. Must be same as format. + The following symbolic values are accepted: + GL_ALPHA, + GL_RGB, + GL_RGBA, + GL_LUMINANCE, or + GL_LUMINANCE_ALPHA.
+ width +: Specifies the width of the texture image. Must be + + 2n + + for some integer n. + All implementations support texture images that are at + least 64 texels wide.
+ height +: Specifies the height of the texture image. Must be + + 2m + + for some integer m. + All implementations support texture images that are at + least 64 texels high.
+ border +: Specifies the width of the border. Must be 0.
+ format +: Specifies the format of the pixel data. Must be same + as internalformat. The following + symbolic values are accepted: + GL_ALPHA, + GL_RGB, + GL_RGBA, + GL_LUMINANCE, and + GL_LUMINANCE_ALPHA.
+ type +: Specifies the data type of the pixel data. The + following symbolic values are accepted: + GL_UNSIGNED_BYTE, + GL_UNSIGNED_SHORT_5_6_5, + GL_UNSIGNED_SHORT_4_4_4_4, and + GL_UNSIGNED_SHORT_5_5_5_1.
+ pixels +: Specifies a pointer to the image data in memory.

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. + Two-dimensional texturing is initially disabled. +

To define texture images, call + glTexImage2D. + The arguments describe the parameters of the texture image, + such as height, width, width of the border, level-of-detail + number (see + glTexParameter), + and number of color components provided. The last three + arguments describe how the image is represented in memory.

Data is read from pixels + as a sequence of unsigned bytes or shorts, depending on + type. + These values are grouped into sets of one, two, three, or + four values, depending on format, + to form elements.

When type is + GL_UNSIGNED_BYTE, each of these bytes is + interpreted as one color component, depending on + format. + When type is one of + GL_UNSIGNED_SHORT_5_6_5, + GL_UNSIGNED_SHORT_4_4_4_4, + GL_UNSIGNED_SHORT_5_5_5_1, + each unsigned value is interpreted as containing all the components + for a single pixel, with the color components arranged according to + format.

The first element corresponds to the lower left corner of + the texture image. Subsequent elements progress left-to-right + through the remaining texels in the lowest row of the texture + image, and then in successively higher rows of the texture + image. The final element corresponds to the upper right corner + of the texture image.

By default, adjacent pixels are taken from adjacent memory + locations, except that after all width pixels are + read, the read pointer is advanced to the next four-byte boundary. + The four-byte row alignment is specified by + glPixelStorei + with argument GL_UNPACK_ALIGNMENT, and it can be set + to one, two, four, or eight bytes.

format + determines the composition of each element in + pixels. + It can assume one of the following symbolic values:

+ GL_ALPHA +: Each element is a single alpha component. The GL + converts it to floating point and assembles it into an + RGBA element by attaching 0 for red, green, and blue.
+ GL_RGB +: Each element is an RGB triple. The GL converts it + to fixed-point or floating-point and assembles it into an + RGBA element by attaching 1 for alpha.
+ GL_RGBA +: Each element contains all four components. The GL + converts it to fixed-point or floating-point.
+ GL_LUMINANCE +: Each element is a single luminance value. The GL + converts it to fixed-point or floating-point, then + assembles it into an RGBA element by replicating the + luminance value three times for red, green, and blue and + attaching 1 for alpha.
+ GL_LUMINANCE_ALPHA +: Each element is a luminance/alpha pair. The GL + converts it to fixed-point or floating point, then + assembles it into an RGBA element by replicating the + luminance value three times for red, green, and blue.

Notes

pixels + may be NULL. In this case texture memory is allocated + to accommodate a texture of width width and height + height. + You can then download subtextures to initialize this texture + memory. The image is undefined if the user tries to apply an + uninitialized portion of the texture image to a primitive.

glTexImage2D + specifies the two-dimensional texture for the currently bound texture + specified with + glBindTexture, + and the current texture + unit, specified with + glActiveTexture. +

Errors

GL_INVALID_ENUM is generated if + target is not + GL_TEXTURE_2D.

GL_INVALID_ENUM is generated if + format is not an accepted constant.

GL_INVALID_ENUM is generated if + type is not an accepted constant.

GL_INVALID_VALUE is generated if + level is less than 0.

GL_INVALID_VALUE may be generated if + level is greater than + + log2max + , where + max is the returned value of + GL_MAX_TEXTURE_SIZE.

GL_INVALID_VALUE is generated if + internalformat + is not an accepted constant.

GL_INVALID_VALUE is generated if + width or height + is less than 0 or greater than GL_MAX_TEXTURE_SIZE, + or if either cannot be represented as + + 2k + + for some integer k.

GL_INVALID_VALUE is generated if + border is not 0.

GL_INVALID_OPERATION is generated if + internalformat and + format are not the same.

GL_INVALID_OPERATION is generated if + type is + GL_UNSIGNED_SHORT_5_6_5 and + format is not + GL_RGB.

GL_INVALID_OPERATION is generated if + type is one of + GL_UNSIGNED_SHORT_4_4_4_4, or + GL_UNSIGNED_SHORT_5_5_5_1 and + format is not + GL_RGBA.

Associated Gets

+ glGet + with argument GL_MAX_TEXTURE_SIZE

Copyright

Name

glTexParameter — set texture parameters

C Specification

`void glTexParameterf(`	GLenum `target`,
	GLenum `pname`,
	GLfloat `param)`;

`void glTexParameteri(`	GLenum `target`,
	GLenum `pname`,
	GLint `param)`;

`void glTexParameterx(`	GLenum `target`,
	GLenum `pname`,
	GLfixed `param)`;

Parameters

+ target +: Specifies the target texture, which must be + GL_TEXTURE_2D.
+ pname +: Specifies the symbolic name of a single-valued texture + parameter. Which can be one of the following: + GL_TEXTURE_MIN_FILTER, + GL_TEXTURE_MAG_FILTER, + GL_TEXTURE_WRAP_S, + GL_TEXTURE_WRAP_T, or + GL_GENERATE_MIPMAP.
+ param +: Specifies the value of pname.

C Specification

`void glTexParameterfv(`	GLenum `target`,
	GLenum `pname`,
	GLfloat * `params)`;

`void glTexParameteriv(`	GLenum `target`,
	GLenum `pname`,
	GLint * `params)`;

`void glTexParameterxv(`	GLenum `target`,
	GLenum `pname`,
	GLfixed * `params)`;

Parameters

+ target +: Specifies the target texture, which must be + GL_TEXTURE_2D.
+ pname +: Specifies the symbolic name of a texture parameter. Which can + be one of the following: GL_TEXTURE_MIN_FILTER, + GL_TEXTURE_MAG_FILTER, + GL_TEXTURE_WRAP_S, + GL_TEXTURE_WRAP_T, or + GL_GENERATE_MIPMAP.
+ params +: Specifies a pointer to an array where the value or values of + pname are stored.

Description

Texture mapping is a technique that applies an image onto an + object's surface as if the image were a decal or cellophane shrink-wrap. + The image is created in texture space, with an + + s + + t + + coordinate system. A texture is a one- or + two-dimensional image and a set of parameters that determine how samples + are derived from the image.

glTexParameter assigns the value in + param or params to the + texture parameter specified as pname. + target defines the target texture, which must be + GL_TEXTURE_2D.

The following symbols are accepted in + pname:

+ GL_TEXTURE_MIN_FILTER +

The texture minifying function is used whenever the pixel + being textured maps to an area greater than one texture element. + There are six defined minifying functions. Two of them use the + nearest one or nearest four texture elements to compute the texture + value. The other four use mipmaps.

A mipmap is an ordered set of arrays representing the same + image at progressively lower resolutions. If the texture has + dimensions + + 2 + + n + + + x + + + 2 + + m + + , there are + max + + + n + + m + + + + + + 1 + mipmaps. The first mipmap is the original + texture, with dimensions + + 2 + + n + + + x + + + 2 + + m + + . Each subsequent mipmap has dimensions + + + 2 + + + k + + - + + 1 + + + + x + + + 2 + + + l + + - + + 1 + + + , where + + 2 + + k + + + x + + + 2 + + l + + are the dimensions of the previous mipmap, until + either + k + + = + + 0 + or + l + + = + + 0 + . At that point, subsequent mipmaps have + dimension + 1 + + x + + + 2 + + + l + + - + + 1 + + + or + + 2 + + + k + + - + + 1 + + + + x + + 1 + until the final mipmap, which has dimension + + 1 + + x + + 1 + . To define the mipmaps, call glTexImage2D or glCopyTexImage2D with the level argument + indicating the order of the mipmaps. Level 0 is the original + texture. Level + max + + + n + + m + + is the final + 1 + + x + + 1 + mipmap.

param supplies a function for minifying + the texture as one of the following:

+

+ GL_NEAREST +

Returns the value of the texture element that is nearest (in + Manhattan distance) to the center of the pixel being + textured.

+ GL_LINEAR +

Returns the weighted average of the four texture elements + that are closest to the center of the pixel being textured. These + can include repeated or wrapped elements, depending on the values + of GL_TEXTURE_WRAP_S and + GL_TEXTURE_WRAP_T, and on the exact + mapping.

+ GL_NEAREST_MIPMAP_NEAREST +

Chooses the mipmap that most closely matches the size of the + pixel being textured and uses the GL_NEAREST + criterion (the texture element nearest to the center of the pixel) + to produce a texture value.

+ GL_LINEAR_MIPMAP_NEAREST +

Chooses the mipmap that most closely matches the size of the + pixel being textured and uses the GL_LINEAR + criterion (a weighted average of the four texture elements that + are closest to the center of the pixel) to produce a texture + value.

+ GL_NEAREST_MIPMAP_LINEAR +

Chooses the two mipmaps that most closely match the size of + the pixel being textured and uses the + GL_NEAREST criterion (the texture element + nearest to the center of the pixel) to produce a texture value + from each mipmap. The final texture value is a weighted average of + those two values.

+ GL_LINEAR_MIPMAP_LINEAR +

Chooses the two mipmaps that most closely match the size of + the pixel being textured and uses the + GL_LINEAR criterion (a weighted average of + the four texture elements that are closest to the center of the + pixel) to produce a texture value from each mipmap. The final + texture value is a weighted average of those two values.

As more texture elements are sampled in the minification + process, fewer aliasing artifacts will be apparent. While the + GL_NEAREST and GL_LINEAR + minification functions can be faster than the other four, they + sample only one or four texture elements to determine the texture + value of the pixel being rendered and can produce moire patterns + or ragged transitions.

+

The initial value of GL_TEXTURE_MIN_FILTER is + GL_NEAREST_MIPMAP_LINEAR.

+ GL_TEXTURE_MAG_FILTER +

The texture magnification function is used when the pixel + being textured maps to an area less than or equal to one texture + element. It sets the texture magnification function to either + GL_NEAREST or GL_LINEAR + (see below). GL_NEAREST is generally faster + than GL_LINEAR, but it can produce textured + images with sharper edges because the transition between texture + elements is not as smooth.

+

+ GL_NEAREST +: Returns the value of the texture element that is nearest (in + Manhattan distance) to the center of the pixel being + textured.
+ GL_LINEAR +: Returns the weighted average of the four texture elements + that are closest to the center of the pixel being textured. These + can include repeated or wrapped elements, depending on the values + of GL_TEXTURE_WRAP_S and + GL_TEXTURE_WRAP_T, and on the exact + mapping.

+

The initial value of GL_TEXTURE_MAG_FILTER is + GL_LINEAR.

+ GL_TEXTURE_WRAP_S +

Sets the wrap parameter for texture coordinate + s to either + GL_CLAMP_TO_EDGE or + GL_REPEAT.

+

+ GL_CLAMP_TO_EDGE +: causes s coordinates to be + clamped to the range + [ + + + 1 + + + 2 + + N + + + + , + + 1 + + - + + + 1 + + + 2 + + N + + + + ] + , where N is the + size of the texture in the direction of clamping.
+ GL_REPEAT +: causes the integer part of the + s coordinate to be ignored; the GL + uses only the fractional part, thereby creating a repeating + pattern.

+

The initial value of GL_TEXTURE_WRAP_S is + GL_REPEAT.

+ GL_TEXTURE_WRAP_T +

Sets the wrap parameter for texture coordinate + t to either + GL_CLAMP_TO_EDGE or + GL_REPEAT. See the discussion under + GL_TEXTURE_WRAP_S.

The initial value of GL_TEXTURE_WRAP_T is + GL_REPEAT.

+ GL_GENERATE_MIPMAP +

Sets the automatic mipmap generation parameter. If set to + GL_TRUE, making any change to the interior + texels of the + + level + + base + + array of a mipmap will also compute a complete + set of mipmap arrays derived from the modified + + level + + base + + array. Array levels + level + + base + +1 through + p are replaced with the derived arrays, regardless + of their previous contents. All other mipmap arrays, including the + + + level + + base + + array, are left unchanged by this + computation.

The initial value of GL_GENERATE_MIPMAP + is GL_FALSE.

Notes

Suppose that a program has enabled texturing (by calling + glEnable with argument GL_TEXTURE_2D and has + set GL_TEXTURE_MIN_FILTER to one of the functions + that requires a mipmap. If either the dimensions of the texture images + currently defined (with previous calls to glTexImage2D, or glCopyTexImage2D) do not follow the proper sequence for mipmaps + (described above), or there are fewer texture images defined than are + needed, or the set of texture images have differing numbers of texture + components, then it is as if texture mapping were disabled.

Linear filtering accesses the four nearest texture elements.

glTexParameter specifies the texture parameters + for the texture bound to the active texture unit, specified by calling glActiveTexture.

Errors

GL_INVALID_ENUM is generated if + target or pname is not one + of the accepted defined values.

GL_INVALID_ENUM is generated if + param should have a defined constant value (based + on the value of pname) and does not.

Copyright

Name

glTexSubImage2D — specify a two-dimensional texture subimage

C Specification

`void glTexSubImage2D(`	GLenum `target`,
	GLint `level`,
	GLint `xoffset`,
	GLint `yoffset`,
	GLsizei `width`,
	GLsizei `height`,
	GLenum `format`,
	GLenum `type`,
	const GLvoid * `pixels)`;

Parameters

+ target +: Specifies the target texture. Must be + GL_TEXTURE_2D.
+ level +: Specifies the level-of-detail number. Level 0 is + the base image level. Level n is the + nth mipmap reduction image.
+ xoffset +: Specifies a texel offset in the x direction within + the texture array.
+ yoffset +: Specifies a texel offset in the y direction within + the texture array.
+ width +: Specifies the width of the texture subimage.
+ height +: Specifies the height of the texture subimage.
+ format +: Specifies the of the pixel data. The following + symbolic values are accepted: + GL_ALPHA, + GL_RGB, + GL_RGBA, + GL_LUMINANCE, and + GL_LUMINANCE_ALPHA.
+ type +: Specifies the data type of the pixel data. The + following symbolic values are accepted: + GL_UNSIGNED_BYTE, + GL_UNSIGNED_SHORT_5_6_5, + GL_UNSIGNED_SHORT_4_4_4_4, and + GL_UNSIGNED_SHORT_5_5_5_1.
+ pixels +: Specifies a pointer to the image data in + memory.

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. + Two-dimensional texturing is initially disabled. +

+ glTexSubImage2D + redefines a contiguous subregion of an existing two-dimensional + texture image. The texels referenced by pixels + replace the portion of the existing texture array with x indices + xoffset and + + xoffset+width-1 + , + inclusive, and y indices yoffset and + + yoffset+height-1 + , + inclusive. This region may not include any texels outside the + range of the texture array as it was originally specified. It + is not an error to specify a subtexture with zero width or + height, but such a specification has no effect.

Notes

+ glPixelStorei + affects texture images in exactly the way it affects + glTexImage2D. +

+ glTexSubImage2D + specifies a two-dimensional sub texture for the currently bound texture, + specified with + glBindTexture + and current texture + unit, specified with + glActiveTexture. +

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.