4 The functions from this section may be had by loading the module:
7 (use-modules (figl gl low-level)
11 This section of the manual was derived from the upstream OpenGL
12 documentation. Each function's documentation has its own copyright
13 statement; for full details, see the upstream documentation. The
14 copyright notices and licenses present in this section are as follows.
16 Copyright @copyright{} 1991-2006 Silicon Graphics, Inc. This document is
17 licensed under the SGI Free Software B License. For details, see
18 @uref{http://oss.sgi.com/projects/FreeB/,http://oss.sgi.com/projects/FreeB/}.
20 Copyright @copyright{} 2003-2005 3Dlabs Inc. Ltd. This material may be
21 distributed subject to the terms and conditions set forth in the Open
22 Publication License, v 1.0, 8 June 1999.
23 @uref{http://opencontent.org/openpub/,http://opencontent.org/openpub/}.
25 Copyright @copyright{} 2005 Addison-Wesley. This material may be
26 distributed subject to the terms and conditions set forth in the Open
27 Publication License, v 1.0, 8 June 1999.
28 @uref{http://opencontent.org/openpub/,http://opencontent.org/openpub/}.
30 Copyright @copyright{} 2006 Khronos Group. This material may be
31 distributed subject to the terms and conditions set forth in the Open
32 Publication License, v 1.0, 8 June 1999.
33 @uref{http://opencontent.org/openpub/,http://opencontent.org/openpub/}.
37 @deftypefun void glAccum op value
38 Operate on the accumulation buffer.
42 Specifies the accumulation buffer operation. Symbolic constants
43 @code{GL_ACCUM}, @code{GL_LOAD}, @code{GL_ADD}, @code{GL_MULT}, and
44 @code{GL_RETURN} are accepted.
47 Specifies a floating-point value used in the accumulation buffer
48 operation. @var{op} determines how @var{value} is used.
52 The accumulation buffer is an extended-range color buffer. Images are
53 not rendered into it. Rather, images rendered into one of the color
54 buffers are added to the contents of the accumulation buffer after
55 rendering. Effects such as antialiasing (of points, lines, and
56 polygons), motion blur, and depth of field can be created by
57 accumulating images generated with different transformation matrices.
59 Each pixel in the accumulation buffer consists of red, green, blue, and
60 alpha values. The number of bits per component in the accumulation
61 buffer depends on the implementation. You can examine this number by
62 calling @code{glGetIntegerv} four times, with arguments
63 @code{GL_ACCUM_RED_BITS}, @code{GL_ACCUM_GREEN_BITS},
64 @code{GL_ACCUM_BLUE_BITS}, and @code{GL_ACCUM_ALPHA_BITS}. Regardless of
65 the number of bits per component, the range of values stored by each
66 component is @r{[-1,1]}. The accumulation buffer pixels are mapped
67 one-to-one with frame buffer pixels.
69 @code{glAccum} operates on the accumulation buffer. The first argument,
70 @var{op}, is a symbolic constant that selects an accumulation buffer
71 operation. The second argument, @var{value}, is a floating-point value
72 to be used in that operation. Five operations are specified:
73 @code{GL_ACCUM}, @code{GL_LOAD}, @code{GL_ADD}, @code{GL_MULT}, and
76 All accumulation buffer operations are limited to the area of the
77 current scissor box and applied identically to the red, green, blue, and
78 alpha components of each pixel. If a @code{glAccum} operation results in
79 a value outside the range @r{[-1,1]}, the contents of an accumulation
80 buffer pixel component are undefined.
82 The operations are as follows:
86 Obtains R, G, B, and A values from the buffer currently selected for
87 reading (see @code{glReadBuffer}). Each component value is divided by
88 @r{2^@var{n}-1}, where @r{@var{n}} is the number of bits allocated to
89 each color component in the currently selected buffer. The result is a
90 floating-point value in the range @r{[0,1]}, which is multiplied by
91 @var{value} and added to the corresponding pixel component in the
92 accumulation buffer, thereby updating the accumulation buffer.
95 Similar to @code{GL_ACCUM}, except that the current value in the
96 accumulation buffer is not used in the calculation of the new value.
97 That is, the R, G, B, and A values from the currently selected buffer
98 are divided by @r{2^@var{n}-1}, multiplied by @var{value}, and then
99 stored in the corresponding accumulation buffer cell, overwriting the
103 Adds @var{value} to each R, G, B, and A in the accumulation buffer.
106 Multiplies each R, G, B, and A in the accumulation buffer by @var{value}
107 and returns the scaled component to its corresponding accumulation
110 @item @code{GL_RETURN}
111 Transfers accumulation buffer values to the color buffer or buffers
112 currently selected for writing. Each R, G, B, and A component is
113 multiplied by @var{value}, then multiplied by @r{2^@var{n}-1}, clamped
114 to the range @r{[0,2^@var{n}-1]}, and stored in the corresponding
115 display buffer cell. The only fragment operations that are applied to
116 this transfer are pixel ownership, scissor, dithering, and color
121 To clear the accumulation buffer, call @code{glClearAccum} with R, G, B,
122 and A values to set it to, then call @code{glClear} with the
123 accumulation buffer enabled.
125 @code{GL_INVALID_ENUM} is generated if @var{op} is not an accepted
128 @code{GL_INVALID_OPERATION} is generated if there is no accumulation
131 @code{GL_INVALID_OPERATION} is generated if @code{glAccum} is executed
132 between the execution of @code{glBegin} and the corresponding execution
137 @deftypefun void glActiveTexture texture
138 Select active texture unit.
142 Specifies which texture unit to make active. The number of texture units
143 is implementation dependent, but must be at least two. @var{texture}
144 must be one of @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to
145 the larger of (@code{GL_MAX_TEXTURE_COORDS} - 1) and
146 (@code{GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS} - 1). The initial value is
151 @code{glActiveTexture} selects which texture unit subsequent texture
152 state calls will affect. The number of texture units an implementation
153 supports is implementation dependent, but must be at least 2.
155 Vertex arrays are client-side GL resources, which are selected by the
156 @code{glClientActiveTexture} routine.
158 @code{GL_INVALID_ENUM} is generated if @var{texture} is not one of
159 @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to the larger of
160 (@code{GL_MAX_TEXTURE_COORDS} - 1) and
161 (@code{GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS} - 1).
165 @deftypefun void glAlphaFunc func ref
166 Specify the alpha test function.
170 Specifies the alpha comparison function. Symbolic constants
171 @code{GL_NEVER}, @code{GL_LESS}, @code{GL_EQUAL}, @code{GL_LEQUAL},
172 @code{GL_GREATER}, @code{GL_NOTEQUAL}, @code{GL_GEQUAL}, and
173 @code{GL_ALWAYS} are accepted. The initial value is @code{GL_ALWAYS}.
176 Specifies the reference value that incoming alpha values are compared
177 to. This value is clamped to the range @r{[0,1]}, where 0 represents the
178 lowest possible alpha value and 1 the highest possible value. The
179 initial reference value is 0.
183 The alpha test discards fragments depending on the outcome of a
184 comparison between an incoming fragment's alpha value and a constant
185 reference value. @code{glAlphaFunc} specifies the reference value and
186 the comparison function. The comparison is performed only if alpha
187 testing is enabled. By default, it is not enabled. (See @code{glEnable}
188 and @code{glDisable} of @code{GL_ALPHA_TEST}.)
190 @var{func} and @var{ref} specify the conditions under which the pixel is
191 drawn. The incoming alpha value is compared to @var{ref} using the
192 function specified by @var{func}. If the value passes the comparison,
193 the incoming fragment is drawn if it also passes subsequent stencil and
194 depth buffer tests. If the value fails the comparison, no change is made
195 to the frame buffer at that pixel location. The comparison functions are
199 @item @code{GL_NEVER}
203 Passes if the incoming alpha value is less than the reference value.
205 @item @code{GL_EQUAL}
206 Passes if the incoming alpha value is equal to the reference value.
208 @item @code{GL_LEQUAL}
209 Passes if the incoming alpha value is less than or equal to the
212 @item @code{GL_GREATER}
213 Passes if the incoming alpha value is greater than the reference value.
215 @item @code{GL_NOTEQUAL}
216 Passes if the incoming alpha value is not equal to the reference value.
218 @item @code{GL_GEQUAL}
219 Passes if the incoming alpha value is greater than or equal to the
222 @item @code{GL_ALWAYS}
223 Always passes (initial value).
227 @code{glAlphaFunc} operates on all pixel write operations, including
228 those resulting from the scan conversion of points, lines, polygons, and
229 bitmaps, and from pixel draw and copy operations. @code{glAlphaFunc}
230 does not affect screen clear operations.
232 @code{GL_INVALID_ENUM} is generated if @var{func} is not an accepted
235 @code{GL_INVALID_OPERATION} is generated if @code{glAlphaFunc} is
236 executed between the execution of @code{glBegin} and the corresponding
237 execution of @code{glEnd}.
241 @deftypefun GLboolean glAreTexturesResident n textures residences
242 Determine if textures are loaded in texture memory.
246 Specifies the number of textures to be queried.
249 Specifies an array containing the names of the textures to be queried.
251 @item @var{residences}
252 Specifies an array in which the texture residence status is returned.
253 The residence status of a texture named by an element of @var{textures}
254 is returned in the corresponding element of @var{residences}.
258 GL establishes a ``working set'' of textures that are resident in
259 texture memory. These textures can be bound to a texture target much
260 more efficiently than textures that are not resident.
262 @code{glAreTexturesResident} queries the texture residence status of the
263 @var{n} textures named by the elements of @var{textures}. If all the
264 named textures are resident, @code{glAreTexturesResident} returns
265 @code{GL_TRUE}, and the contents of @var{residences} are undisturbed. If
266 not all the named textures are resident, @code{glAreTexturesResident}
267 returns @code{GL_FALSE}, and detailed status is returned in the @var{n}
268 elements of @var{residences}. If an element of @var{residences} is
269 @code{GL_TRUE}, then the texture named by the corresponding element of
270 @var{textures} is resident.
272 The residence status of a single bound texture may also be queried by
273 calling @code{glGetTexParameter} with the @var{target} argument set to
274 the target to which the texture is bound, and the @var{pname} argument
275 set to @code{GL_TEXTURE_RESIDENT}. This is the only way that the
276 residence status of a default texture can be queried.
278 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
280 @code{GL_INVALID_VALUE} is generated if any element in @var{textures} is
281 0 or does not name a texture. In that case, the function returns
282 @code{GL_FALSE} and the contents of @var{residences} is indeterminate.
284 @code{GL_INVALID_OPERATION} is generated if @code{glAreTexturesResident}
285 is executed between the execution of @code{glBegin} and the
286 corresponding execution of @code{glEnd}.
290 @deftypefun void glArrayElement i
291 Render a vertex using the specified vertex array element.
295 Specifies an index into the enabled vertex data arrays.
299 @code{glArrayElement} commands are used within
300 @code{glBegin}/@code{glEnd} pairs to specify vertex and attribute data
301 for point, line, and polygon primitives. If @code{GL_VERTEX_ARRAY} is
302 enabled when @code{glArrayElement} is called, a single vertex is drawn,
303 using vertex and attribute data taken from location @var{i} of the
304 enabled arrays. If @code{GL_VERTEX_ARRAY} is not enabled, no drawing
305 occurs but the attributes corresponding to the enabled arrays are
308 Use @code{glArrayElement} to construct primitives by indexing vertex
309 data, rather than by streaming through arrays of data in first-to-last
310 order. Because each call specifies only a single vertex, it is possible
311 to explicitly specify per-primitive attributes such as a single normal
314 Changes made to array data between the execution of @code{glBegin} and
315 the corresponding execution of @code{glEnd} may affect calls to
316 @code{glArrayElement} that are made within the same
317 @code{glBegin}/@code{glEnd} period in nonsequential ways. That is, a
318 call to @code{glArrayElement} that precedes a change to array data may
319 access the changed data, and a call that follows a change to array data
320 may access original data.
322 @code{GL_INVALID_VALUE} may be generated if @var{i} is negative.
324 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
325 name is bound to an enabled array and the buffer object's data store is
330 @deftypefun void glAttachShader program shader
331 Attaches a shader object to a program object.
335 Specifies the program object to which a shader object will be attached.
338 Specifies the shader object that is to be attached.
342 In order to create an executable, there must be a way to specify the
343 list of things that will be linked together. Program objects provide
344 this mechanism. Shaders that are to be linked together in a program
345 object must first be attached to that program object.
346 @code{glAttachShader} attaches the shader object specified by
347 @var{shader} to the program object specified by @var{program}. This
348 indicates that @var{shader} will be included in link operations that
349 will be performed on @var{program}.
351 All operations that can be performed on a shader object are valid
352 whether or not the shader object is attached to a program object. It is
353 permissible to attach a shader object to a program object before source
354 code has been loaded into the shader object or before the shader object
355 has been compiled. It is permissible to attach multiple shader objects
356 of the same type because each may contain a portion of the complete
357 shader. It is also permissible to attach a shader object to more than
358 one program object. If a shader object is deleted while it is attached
359 to a program object, it will be flagged for deletion, and deletion will
360 not occur until @code{glDetachShader} is called to detach it from all
361 program objects to which it is attached.
363 @code{GL_INVALID_VALUE} is generated if either @var{program} or
364 @var{shader} is not a value generated by OpenGL.
366 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
369 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
372 @code{GL_INVALID_OPERATION} is generated if @var{shader} is already
373 attached to @var{program}.
375 @code{GL_INVALID_OPERATION} is generated if @code{glAttachShader} is
376 executed between the execution of @code{glBegin} and the corresponding
377 execution of @code{glEnd}.
381 @deftypefun void glBeginQuery target id
382 @deftypefunx void glEndQuery target
383 Delimit the boundaries of a query object.
387 Specifies the target type of query object established between
388 @code{glBeginQuery} and the subsequent @code{glEndQuery}. The symbolic
389 constant must be @code{GL_SAMPLES_PASSED}.
392 Specifies the name of a query object.
396 @code{glBeginQuery} and @code{glEndQuery} delimit the boundaries of a
397 query object. If a query object with name @var{id} does not yet exist it
400 When @code{glBeginQuery} is executed, the query object's samples-passed
401 counter is reset to 0. Subsequent rendering will increment the counter
402 once for every sample that passes the depth test. When @code{glEndQuery}
403 is executed, the samples-passed counter is assigned to the query
404 object's result value. This value can be queried by calling
405 @code{glGetQueryObject} with @var{pname}@code{GL_QUERY_RESULT}.
407 Querying the @code{GL_QUERY_RESULT} implicitly flushes the GL pipeline
408 until the rendering delimited by the query object has completed and the
409 result is available. @code{GL_QUERY_RESULT_AVAILABLE} can be queried to
410 determine if the result is immediately available or if the rendering is
413 @code{GL_INVALID_ENUM} is generated if @var{target} is not
414 @code{GL_SAMPLES_PASSED}.
416 @code{GL_INVALID_OPERATION} is generated if @code{glBeginQuery} is
417 executed while a query object of the same @var{target} is already
420 @code{GL_INVALID_OPERATION} is generated if @code{glEndQuery} is
421 executed when a query object of the same @var{target} is not active.
423 @code{GL_INVALID_OPERATION} is generated if @var{id} is 0.
425 @code{GL_INVALID_OPERATION} is generated if @var{id} is the name of an
426 already active query object.
428 @code{GL_INVALID_OPERATION} is generated if @code{glBeginQuery} or
429 @code{glEndQuery} is executed between the execution of @code{glBegin}
430 and the corresponding execution of @code{glEnd}.
434 @deftypefun void glBegin mode
435 @deftypefunx void glEnd
436 Delimit the vertices of a primitive or a group of like primitives.
440 Specifies the primitive or primitives that will be created from vertices
441 presented between @code{glBegin} and the subsequent @code{glEnd}. Ten
442 symbolic constants are accepted: @code{GL_POINTS}, @code{GL_LINES},
443 @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, @code{GL_TRIANGLES},
444 @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, @code{GL_QUADS},
445 @code{GL_QUAD_STRIP}, and @code{GL_POLYGON}.
449 @code{glBegin} and @code{glEnd} delimit the vertices that define a
450 primitive or a group of like primitives. @code{glBegin} accepts a single
451 argument that specifies in which of ten ways the vertices are
452 interpreted. Taking @r{@var{n}} as an integer count starting at one, and
453 @r{@var{N}} as the total number of vertices specified, the
454 interpretations are as follows:
457 @item @code{GL_POINTS}
458 Treats each vertex as a single point. Vertex @r{@var{n}} defines point
459 @r{@var{n}}. @r{@var{N}} points are drawn.
461 @item @code{GL_LINES}
462 Treats each pair of vertices as an independent line segment. Vertices
463 @r{2@var{n}-1} and @r{2@var{n}} define line @r{@var{n}}. @r{@var{N}/2}
466 @item @code{GL_LINE_STRIP}
467 Draws a connected group of line segments from the first vertex to the
468 last. Vertices @r{@var{n}} and @r{@var{n}+1} define line @r{@var{n}}.
469 @r{@var{N}-1} lines are drawn.
471 @item @code{GL_LINE_LOOP}
472 Draws a connected group of line segments from the first vertex to the
473 last, then back to the first. Vertices @r{@var{n}} and @r{@var{n}+1}
474 define line @r{@var{n}}. The last line, however, is defined by vertices
475 @r{@var{N}} and @r{1}. @r{@var{N}} lines are drawn.
477 @item @code{GL_TRIANGLES}
478 Treats each triplet of vertices as an independent triangle. Vertices
479 @r{3@var{n}-2}, @r{3@var{n}-1}, and @r{3@var{n}} define triangle
480 @r{@var{n}}. @r{@var{N}/3} triangles are drawn.
482 @item @code{GL_TRIANGLE_STRIP}
483 Draws a connected group of triangles. One triangle is defined for each
484 vertex presented after the first two vertices. For odd @r{@var{n}},
485 vertices @r{@var{n}}, @r{@var{n}+1}, and @r{@var{n}+2} define triangle
486 @r{@var{n}}. For even @r{@var{n}}, vertices @r{@var{n}+1}, @r{@var{n}},
487 and @r{@var{n}+2} define triangle @r{@var{n}}. @r{@var{N}-2} triangles
490 @item @code{GL_TRIANGLE_FAN}
491 Draws a connected group of triangles. One triangle is defined for each
492 vertex presented after the first two vertices. Vertices @r{1},
493 @r{@var{n}+1}, and @r{@var{n}+2} define triangle @r{@var{n}}.
494 @r{@var{N}-2} triangles are drawn.
496 @item @code{GL_QUADS}
497 Treats each group of four vertices as an independent quadrilateral.
498 Vertices @r{4@var{n}-3}, @r{4@var{n}-2}, @r{4@var{n}-1}, and
499 @r{4@var{n}} define quadrilateral @r{@var{n}}. @r{@var{N}/4}
500 quadrilaterals are drawn.
502 @item @code{GL_QUAD_STRIP}
503 Draws a connected group of quadrilaterals. One quadrilateral is defined
504 for each pair of vertices presented after the first pair. Vertices
505 @r{2@var{n}-1}, @r{2@var{n}}, @r{2@var{n}+2}, and @r{2@var{n}+1}
506 define quadrilateral @r{@var{n}}. @r{@var{N}/2-1} quadrilaterals are
507 drawn. Note that the order in which vertices are used to construct a
508 quadrilateral from strip data is different from that used with
511 @item @code{GL_POLYGON}
512 Draws a single, convex polygon. Vertices @r{1} through @r{@var{N}}
517 Only a subset of GL commands can be used between @code{glBegin} and
518 @code{glEnd}. The commands are @code{glVertex}, @code{glColor},
519 @code{glSecondaryColor}, @code{glIndex}, @code{glNormal},
520 @code{glFogCoord}, @code{glTexCoord}, @code{glMultiTexCoord},
521 @code{glVertexAttrib}, @code{glEvalCoord}, @code{glEvalPoint},
522 @code{glArrayElement}, @code{glMaterial}, and @code{glEdgeFlag}. Also,
523 it is acceptable to use @code{glCallList} or @code{glCallLists} to
524 execute display lists that include only the preceding commands. If any
525 other GL command is executed between @code{glBegin} and @code{glEnd},
526 the error flag is set and the command is ignored.
528 Regardless of the value chosen for @var{mode}, there is no limit to the
529 number of vertices that can be defined between @code{glBegin} and
530 @code{glEnd}. Lines, triangles, quadrilaterals, and polygons that are
531 incompletely specified are not drawn. Incomplete specification results
532 when either too few vertices are provided to specify even a single
533 primitive or when an incorrect multiple of vertices is specified. The
534 incomplete primitive is ignored; the rest are drawn.
536 The minimum specification of vertices for each primitive is as follows:
537 1 for a point, 2 for a line, 3 for a triangle, 4 for a quadrilateral,
538 and 3 for a polygon. Modes that require a certain multiple of vertices
539 are @code{GL_LINES} (2), @code{GL_TRIANGLES} (3), @code{GL_QUADS} (4),
540 and @code{GL_QUAD_STRIP} (2).
542 @code{GL_INVALID_ENUM} is generated if @var{mode} is set to an
545 @code{GL_INVALID_OPERATION} is generated if @code{glBegin} is executed
546 between a @code{glBegin} and the corresponding execution of
549 @code{GL_INVALID_OPERATION} is generated if @code{glEnd} is executed
550 without being preceded by a @code{glBegin}.
552 @code{GL_INVALID_OPERATION} is generated if a command other than
553 @code{glVertex}, @code{glColor}, @code{glSecondaryColor},
554 @code{glIndex}, @code{glNormal}, @code{glFogCoord}, @code{glTexCoord},
555 @code{glMultiTexCoord}, @code{glVertexAttrib}, @code{glEvalCoord},
556 @code{glEvalPoint}, @code{glArrayElement}, @code{glMaterial},
557 @code{glEdgeFlag}, @code{glCallList}, or @code{glCallLists} is executed
558 between the execution of @code{glBegin} and the corresponding execution
561 Execution of @code{glEnableClientState}, @code{glDisableClientState},
562 @code{glEdgeFlagPointer}, @code{glFogCoordPointer},
563 @code{glTexCoordPointer}, @code{glColorPointer},
564 @code{glSecondaryColorPointer}, @code{glIndexPointer},
565 @code{glNormalPointer}, @code{glVertexPointer},
566 @code{glVertexAttribPointer}, @code{glInterleavedArrays}, or
567 @code{glPixelStore} is not allowed after a call to @code{glBegin} and
568 before the corresponding call to @code{glEnd}, but an error may or may
573 @deftypefun void glBindAttribLocation program index name
574 Associates a generic vertex attribute index with a named attribute
579 Specifies the handle of the program object in which the association is
583 Specifies the index of the generic vertex attribute to be bound.
586 Specifies a null terminated string containing the name of the vertex
587 shader attribute variable to which @var{index} is to be bound.
591 @code{glBindAttribLocation} is used to associate a user-defined
592 attribute variable in the program object specified by @var{program} with
593 a generic vertex attribute index. The name of the user-defined attribute
594 variable is passed as a null terminated string in @var{name}. The
595 generic vertex attribute index to be bound to this variable is specified
596 by @var{index}. When @var{program} is made part of current state, values
597 provided via the generic vertex attribute @var{index} will modify the
598 value of the user-defined attribute variable specified by @var{name}.
600 If @var{name} refers to a matrix attribute variable, @var{index} refers
601 to the first column of the matrix. Other matrix columns are then
602 automatically bound to locations @var{index+1} for a matrix of type
603 mat2; @var{index+1} and @var{index+2} for a matrix of type mat3; and
604 @var{index+1}, @var{index+2}, and @var{index+3} for a matrix of type
607 This command makes it possible for vertex shaders to use descriptive
608 names for attribute variables rather than generic variables that are
609 numbered from 0 to @code{GL_MAX_VERTEX_ATTRIBS} -1. The values sent to
610 each generic attribute index are part of current state, just like
611 standard vertex attributes such as color, normal, and vertex position.
612 If a different program object is made current by calling
613 @code{glUseProgram}, the generic vertex attributes are tracked in such a
614 way that the same values will be observed by attributes in the new
615 program object that are also bound to @var{index}.
617 Attribute variable name-to-generic attribute index bindings for a
618 program object can be explicitly assigned at any time by calling
619 @code{glBindAttribLocation}. Attribute bindings do not go into effect
620 until @code{glLinkProgram} is called. After a program object has been
621 linked successfully, the index values for generic attributes remain
622 fixed (and their values can be queried) until the next link command
625 Applications are not allowed to bind any of the standard OpenGL vertex
626 attributes using this command, as they are bound automatically when
627 needed. Any attribute binding that occurs after the program object has
628 been linked will not take effect until the next time the program object
631 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
632 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
634 @code{GL_INVALID_OPERATION} is generated if @var{name} starts with the
635 reserved prefix "gl_".
637 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
640 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
643 @code{GL_INVALID_OPERATION} is generated if @code{glBindAttribLocation}
644 is executed between the execution of @code{glBegin} and the
645 corresponding execution of @code{glEnd}.
649 @deftypefun void glBindBuffer target buffer
650 Bind a named buffer object.
654 Specifies the target to which the buffer object is bound. The symbolic
655 constant must be @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
656 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
659 Specifies the name of a buffer object.
663 @code{glBindBuffer} lets you create or use a named buffer object.
664 Calling @code{glBindBuffer} with @var{target} set to
665 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
666 @code{GL_PIXEL_PACK_BUFFER} or @code{GL_PIXEL_UNPACK_BUFFER} and
667 @var{buffer} set to the name of the new buffer object binds the buffer
668 object name to the target. When a buffer object is bound to a target,
669 the previous binding for that target is automatically broken.
671 Buffer object names are unsigned integers. The value zero is reserved,
672 but there is no default buffer object for each buffer object target.
673 Instead, @var{buffer} set to zero effectively unbinds any buffer object
674 previously bound, and restores client memory usage for that buffer
675 object target. Buffer object names and the corresponding buffer object
676 contents are local to the shared display-list space (see
677 @code{glXCreateContext}) of the current GL rendering context; two
678 rendering contexts share buffer object names only if they also share
681 You may use @code{glGenBuffers} to generate a set of new buffer object
684 The state of a buffer object immediately after it is first bound is an
685 unmapped zero-sized memory buffer with @code{GL_READ_WRITE} access and
686 @code{GL_STATIC_DRAW} usage.
688 While a non-zero buffer object name is bound, GL operations on the
689 target to which it is bound affect the bound buffer object, and queries
690 of the target to which it is bound return state from the bound buffer
691 object. While buffer object name zero is bound, as in the initial state,
692 attempts to modify or query state on the target to which it is bound
693 generates an @code{GL_INVALID_OPERATION} error.
695 When vertex array pointer state is changed, for example by a call to
696 @code{glNormalPointer}, the current buffer object binding
697 (@code{GL_ARRAY_BUFFER_BINDING}) is copied into the corresponding client
698 state for the vertex array type being changed, for example
699 @code{GL_NORMAL_ARRAY_BUFFER_BINDING}. While a non-zero buffer object is
700 bound to the @code{GL_ARRAY_BUFFER} target, the vertex array pointer
701 parameter that is traditionally interpreted as a pointer to client-side
702 memory is instead interpreted as an offset within the buffer object
703 measured in basic machine units.
705 While a non-zero buffer object is bound to the
706 @code{GL_ELEMENT_ARRAY_BUFFER} target, the indices parameter of
707 @code{glDrawElements}, @code{glDrawRangeElements}, or
708 @code{glMultiDrawElements} that is traditionally interpreted as a
709 pointer to client-side memory is instead interpreted as an offset within
710 the buffer object measured in basic machine units.
712 While a non-zero buffer object is bound to the
713 @code{GL_PIXEL_PACK_BUFFER} target, the following commands are affected:
714 @code{glGetCompressedTexImage}, @code{glGetConvolutionFilter},
715 @code{glGetHistogram}, @code{glGetMinmax}, @code{glGetPixelMap},
716 @code{glGetPolygonStipple}, @code{glGetSeparableFilter},
717 @code{glGetTexImage}, and @code{glReadPixels}. The pointer parameter
718 that is traditionally interpreted as a pointer to client-side memory
719 where the pixels are to be packed is instead interpreted as an offset
720 within the buffer object measured in basic machine units.
722 While a non-zero buffer object is bound to the
723 @code{GL_PIXEL_UNPACK_BUFFER} target, the following commands are
724 affected: @code{glBitmap}, @code{glColorSubTable}, @code{glColorTable},
725 @code{glCompressedTexImage1D}, @code{glCompressedTexImage2D},
726 @code{glCompressedTexImage3D}, @code{glCompressedTexSubImage1D},
727 @code{glCompressedTexSubImage2D}, @code{glCompressedTexSubImage3D},
728 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D},
729 @code{glDrawPixels}, @code{glPixelMap}, @code{glPolygonStipple},
730 @code{glSeparableFilter2D}, @code{glTexImage1D}, @code{glTexImage2D},
731 @code{glTexImage3D}, @code{glTexSubImage1D}, @code{glTexSubImage2D}, and
732 @code{glTexSubImage3D}. The pointer parameter that is traditionally
733 interpreted as a pointer to client-side memory from which the pixels are
734 to be unpacked is instead interpreted as an offset within the buffer
735 object measured in basic machine units.
737 A buffer object binding created with @code{glBindBuffer} remains active
738 until a different buffer object name is bound to the same target, or
739 until the bound buffer object is deleted with @code{glDeleteBuffers}.
741 Once created, a named buffer object may be re-bound to any target as
742 often as needed. However, the GL implementation may make choices about
743 how to optimize the storage of a buffer object based on its initial
746 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
749 @code{GL_INVALID_OPERATION} is generated if @code{glBindBuffer} is
750 executed between the execution of @code{glBegin} and the corresponding
751 execution of @code{glEnd}.
755 @deftypefun void glBindTexture target texture
756 Bind a named texture to a texturing target.
760 Specifies the target to which the texture is bound. Must be either
761 @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, or
762 @code{GL_TEXTURE_CUBE_MAP}.
765 Specifies the name of a texture.
769 @code{glBindTexture} lets you create or use a named texture. Calling
770 @code{glBindTexture} with @var{target} set to @code{GL_TEXTURE_1D},
771 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D} or @code{GL_TEXTURE_CUBE_MAP}
772 and @var{texture} set to the name of the new texture binds the texture
773 name to the target. When a texture is bound to a target, the previous
774 binding for that target is automatically broken.
776 Texture names are unsigned integers. The value zero is reserved to
777 represent the default texture for each texture target. Texture names and
778 the corresponding texture contents are local to the shared display-list
779 space (see @code{glXCreateContext}) of the current GL rendering context;
780 two rendering contexts share texture names only if they also share
783 You may use @code{glGenTextures} to generate a set of new texture names.
785 When a texture is first bound, it assumes the specified target: A
786 texture first bound to @code{GL_TEXTURE_1D} becomes one-dimensional
787 texture, a texture first bound to @code{GL_TEXTURE_2D} becomes
788 two-dimensional texture, a texture first bound to @code{GL_TEXTURE_3D}
789 becomes three-dimensional texture, and a texture first bound to
790 @code{GL_TEXTURE_CUBE_MAP} becomes a cube-mapped texture. The state of a
791 one-dimensional texture immediately after it is first bound is
792 equivalent to the state of the default @code{GL_TEXTURE_1D} at GL
793 initialization, and similarly for two- and three-dimensional textures
794 and cube-mapped textures.
796 While a texture is bound, GL operations on the target to which it is
797 bound affect the bound texture, and queries of the target to which it is
798 bound return state from the bound texture. If texture mapping is active
799 on the target to which a texture is bound, the bound texture is used. In
800 effect, the texture targets become aliases for the textures currently
801 bound to them, and the texture name zero refers to the default textures
802 that were bound to them at initialization.
804 A texture binding created with @code{glBindTexture} remains active until
805 a different texture is bound to the same target, or until the bound
806 texture is deleted with @code{glDeleteTextures}.
808 Once created, a named texture may be re-bound to its same original
809 target as often as needed. It is usually much faster to use
810 @code{glBindTexture} to bind an existing named texture to one of the
811 texture targets than it is to reload the texture image using
812 @code{glTexImage1D}, @code{glTexImage2D}, or @code{glTexImage3D}. For
813 additional control over performance, use @code{glPrioritizeTextures}.
815 @code{glBindTexture} is included in display lists.
817 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
820 @code{GL_INVALID_OPERATION} is generated if @var{texture} was previously
821 created with a target that doesn't match that of @var{target}.
823 @code{GL_INVALID_OPERATION} is generated if @code{glBindTexture} is
824 executed between the execution of @code{glBegin} and the corresponding
825 execution of @code{glEnd}.
829 @deftypefun void glBitmap width height xorig yorig xmove ymove bitmap
835 Specify the pixel width and height of the bitmap image.
839 Specify the location of the origin in the bitmap image. The origin is
840 measured from the lower left corner of the bitmap, with right and up
841 being the positive axes.
845 Specify the @var{x} and @var{y} offsets to be added to the current
846 raster position after the bitmap is drawn.
849 Specifies the address of the bitmap image.
853 A bitmap is a binary image. When drawn, the bitmap is positioned
854 relative to the current raster position, and frame buffer pixels
855 corresponding to 1's in the bitmap are written using the current raster
856 color or index. Frame buffer pixels corresponding to 0's in the bitmap
859 @code{glBitmap} takes seven arguments. The first pair specifies the
860 width and height of the bitmap image. The second pair specifies the
861 location of the bitmap origin relative to the lower left corner of the
862 bitmap image. The third pair of arguments specifies @var{x} and @var{y}
863 offsets to be added to the current raster position after the bitmap has
864 been drawn. The final argument is a pointer to the bitmap image itself.
866 If a non-zero named buffer object is bound to the
867 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
868 bitmap image is specified, @var{bitmap} is treated as a byte offset into
869 the buffer object's data store.
871 The bitmap image is interpreted like image data for the
872 @code{glDrawPixels} command, with @var{width} and @var{height}
873 corresponding to the width and height arguments of that command, and
874 with @var{type} set to @code{GL_BITMAP} and @var{format} set to
875 @code{GL_COLOR_INDEX}. Modes specified using @code{glPixelStore} affect
876 the interpretation of bitmap image data; modes specified using
877 @code{glPixelTransfer} do not.
879 If the current raster position is invalid, @code{glBitmap} is ignored.
880 Otherwise, the lower left corner of the bitmap image is positioned at
881 the window coordinates
883 @r{@var{x}_@var{w}=⌊@var{x}_@var{r}-@var{x}_@var{o},⌋}
885 @r{@var{y}_@var{w}=⌊@var{y}_@var{r}-@var{y}_@var{o},⌋}
887 where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the raster position and
888 @r{(@var{x}_@var{o},@var{y}_@var{o})} is the bitmap origin. Fragments
889 are then generated for each pixel corresponding to a 1 (one) in the
890 bitmap image. These fragments are generated using the current raster
891 @var{z} coordinate, color or color index, and current raster texture
892 coordinates. They are then treated just as if they had been generated by
893 a point, line, or polygon, including texture mapping, fogging, and all
894 per-fragment operations such as alpha and depth testing.
896 After the bitmap has been drawn, the @var{x} and @var{y} coordinates of
897 the current raster position are offset by @var{xmove} and @var{ymove}.
898 No change is made to the @var{z} coordinate of the current raster
899 position, or to the current raster color, texture coordinates, or index.
901 @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is
904 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
905 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
906 object's data store is currently mapped.
908 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
909 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
910 would be unpacked from the buffer object such that the memory reads
911 required would exceed the data store size.
913 @code{GL_INVALID_OPERATION} is generated if @code{glBitmap} is executed
914 between the execution of @code{glBegin} and the corresponding execution
919 @deftypefun void glBlendColor red green blue alpha
927 specify the components of @code{GL_BLEND_COLOR}
931 The @code{GL_BLEND_COLOR} may be used to calculate the source and
932 destination blending factors. The color components are clamped to the
933 range @r{[0,1]} before being stored. See @code{glBlendFunc} for a
934 complete description of the blending operations. Initially the
935 @code{GL_BLEND_COLOR} is set to (0, 0, 0, 0).
937 @code{GL_INVALID_OPERATION} is generated if @code{glBlendColor} is
938 executed between the execution of @code{glBegin} and the corresponding
939 execution of @code{glEnd}.
945 @deftypefun void glBlendEquationSeparate modeRGB modeAlpha
946 Set the RGB blend equation and the alpha blend equation separately.
950 specifies the RGB blend equation, how the red, green, and blue
951 components of the source and destination colors are combined. It must be
952 @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT},
953 @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN}, @code{GL_MAX}.
955 @item @var{modeAlpha}
956 specifies the alpha blend equation, how the alpha component of the
957 source and destination colors are combined. It must be
958 @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT},
959 @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN}, @code{GL_MAX}.
963 The blend equations determines how a new pixel (the ''source'' color) is
964 combined with a pixel already in the framebuffer (the ''destination''
965 color). This function specifies one blend equation for the RGB-color
966 components and one blend equation for the alpha component.
968 The blend equations use the source and destination blend factors
969 specified by either @code{glBlendFunc} or @code{glBlendFuncSeparate}.
970 See @code{glBlendFunc} or @code{glBlendFuncSeparate} for a description
971 of the various blend factors.
973 In the equations that follow, source and destination color components
975 @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and
976 @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})},
977 respectively. The result color is referred to as
978 @r{(@var{R}_@var{r},@var{G}_@var{r}@var{B}_@var{r}@var{A}_@var{r})}. The
979 source and destination blend factors are denoted
980 @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and
981 @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})},
982 respectively. For these equations all color components are understood to
983 have values in the range @r{[0,1]}.
987 @strong{RGB Components}, @strong{Alpha Component}
989 @item @code{GL_FUNC_ADD}
990 @r{@var{Rr}=@var{R}_@var{s}@var{s}_@var{R}+@var{R}_@var{d}@var{d}_@var{R}}@r{@var{Gr}=@var{G}_@var{s}@var{s}_@var{G}+@var{G}_@var{d}@var{d}_@var{G}}@r{@var{Br}=@var{B}_@var{s}@var{s}_@var{B}+@var{B}_@var{d}@var{d}_@var{B}},
991 @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}+@var{A}_@var{d}@var{d}_@var{A}}
993 @item @code{GL_FUNC_SUBTRACT}
994 @r{@var{Rr}=@var{R}_@var{s}@var{s}_@var{R}-@var{R}_@var{d}@var{d}_@var{R}}@r{@var{Gr}=@var{G}_@var{s}@var{s}_@var{G}-@var{G}_@var{d}@var{d}_@var{G}}@r{@var{Br}=@var{B}_@var{s}@var{s}_@var{B}-@var{B}_@var{d}@var{d}_@var{B}},
995 @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}-@var{A}_@var{d}@var{d}_@var{A}}
997 @item @code{GL_FUNC_REVERSE_SUBTRACT}
998 @r{@var{Rr}=@var{R}_@var{d}@var{d}_@var{R}-@var{R}_@var{s}@var{s}_@var{R}}@r{@var{Gr}=@var{G}_@var{d}@var{d}_@var{G}-@var{G}_@var{s}@var{s}_@var{G}}@r{@var{Br}=@var{B}_@var{d}@var{d}_@var{B}-@var{B}_@var{s}@var{s}_@var{B}},
999 @r{@var{Ar}=@var{A}_@var{d}@var{d}_@var{A}-@var{A}_@var{s}@var{s}_@var{A}}
1002 @r{@var{Rr}=@var{min}(@var{R}_@var{s},@var{R}_@var{d})}@r{@var{Gr}=@var{min}(@var{G}_@var{s},@var{G}_@var{d})}@r{@var{Br}=@var{min}(@var{B}_@var{s},@var{B}_@var{d})},
1003 @r{@var{Ar}=@var{min}(@var{A}_@var{s},@var{A}_@var{d})}
1006 @r{@var{Rr}=@var{max}(@var{R}_@var{s},@var{R}_@var{d})}@r{@var{Gr}=@var{max}(@var{G}_@var{s},@var{G}_@var{d})}@r{@var{Br}=@var{max}(@var{B}_@var{s},@var{B}_@var{d})},
1007 @r{@var{Ar}=@var{max}(@var{A}_@var{s},@var{A}_@var{d})}
1011 The results of these equations are clamped to the range @r{[0,1]}.
1013 The @code{GL_MIN} and @code{GL_MAX} equations are useful for
1014 applications that analyze image data (image thresholding against a
1015 constant color, for example). The @code{GL_FUNC_ADD} equation is useful
1016 for antialiasing and transparency, among other things.
1018 Initially, both the RGB blend equation and the alpha blend equation are
1019 set to @code{GL_FUNC_ADD}.
1023 @code{GL_INVALID_ENUM} is generated if either @var{modeRGB} or
1024 @var{modeAlpha} is not one of @code{GL_FUNC_ADD},
1025 @code{GL_FUNC_SUBTRACT}, @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MAX},
1028 @code{GL_INVALID_OPERATION} is generated if
1029 @code{glBlendEquationSeparate} is executed between the execution of
1030 @code{glBegin} and the corresponding execution of @code{glEnd}.
1034 @deftypefun void glBlendEquation mode
1035 Specify the equation used for both the RGB blend equation and the Alpha
1040 specifies how source and destination colors are combined. It must be
1041 @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT},
1042 @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN}, @code{GL_MAX}.
1046 The blend equations determine how a new pixel (the ''source'' color) is
1047 combined with a pixel already in the framebuffer (the ''destination''
1048 color). This function sets both the RGB blend equation and the alpha
1049 blend equation to a single equation.
1051 These equations use the source and destination blend factors specified
1052 by either @code{glBlendFunc} or @code{glBlendFuncSeparate}. See
1053 @code{glBlendFunc} or @code{glBlendFuncSeparate} for a description of
1054 the various blend factors.
1056 In the equations that follow, source and destination color components
1058 @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and
1059 @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})},
1060 respectively. The result color is referred to as
1061 @r{(@var{R}_@var{r},@var{G}_@var{r}@var{B}_@var{r}@var{A}_@var{r})}. The
1062 source and destination blend factors are denoted
1063 @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and
1064 @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})},
1065 respectively. For these equations all color components are understood to
1066 have values in the range @r{[0,1]}.
1070 @strong{RGB Components}, @strong{Alpha Component}
1072 @item @code{GL_FUNC_ADD}
1073 @r{@var{Rr}=@var{R}_@var{s}@var{s}_@var{R}+@var{R}_@var{d}@var{d}_@var{R}}@r{@var{Gr}=@var{G}_@var{s}@var{s}_@var{G}+@var{G}_@var{d}@var{d}_@var{G}}@r{@var{Br}=@var{B}_@var{s}@var{s}_@var{B}+@var{B}_@var{d}@var{d}_@var{B}},
1074 @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}+@var{A}_@var{d}@var{d}_@var{A}}
1076 @item @code{GL_FUNC_SUBTRACT}
1077 @r{@var{Rr}=@var{R}_@var{s}@var{s}_@var{R}-@var{R}_@var{d}@var{d}_@var{R}}@r{@var{Gr}=@var{G}_@var{s}@var{s}_@var{G}-@var{G}_@var{d}@var{d}_@var{G}}@r{@var{Br}=@var{B}_@var{s}@var{s}_@var{B}-@var{B}_@var{d}@var{d}_@var{B}},
1078 @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}-@var{A}_@var{d}@var{d}_@var{A}}
1080 @item @code{GL_FUNC_REVERSE_SUBTRACT}
1081 @r{@var{Rr}=@var{R}_@var{d}@var{d}_@var{R}-@var{R}_@var{s}@var{s}_@var{R}}@r{@var{Gr}=@var{G}_@var{d}@var{d}_@var{G}-@var{G}_@var{s}@var{s}_@var{G}}@r{@var{Br}=@var{B}_@var{d}@var{d}_@var{B}-@var{B}_@var{s}@var{s}_@var{B}},
1082 @r{@var{Ar}=@var{A}_@var{d}@var{d}_@var{A}-@var{A}_@var{s}@var{s}_@var{A}}
1085 @r{@var{Rr}=@var{min}(@var{R}_@var{s},@var{R}_@var{d})}@r{@var{Gr}=@var{min}(@var{G}_@var{s},@var{G}_@var{d})}@r{@var{Br}=@var{min}(@var{B}_@var{s},@var{B}_@var{d})},
1086 @r{@var{Ar}=@var{min}(@var{A}_@var{s},@var{A}_@var{d})}
1089 @r{@var{Rr}=@var{max}(@var{R}_@var{s},@var{R}_@var{d})}@r{@var{Gr}=@var{max}(@var{G}_@var{s},@var{G}_@var{d})}@r{@var{Br}=@var{max}(@var{B}_@var{s},@var{B}_@var{d})},
1090 @r{@var{Ar}=@var{max}(@var{A}_@var{s},@var{A}_@var{d})}
1094 The results of these equations are clamped to the range @r{[0,1]}.
1096 The @code{GL_MIN} and @code{GL_MAX} equations are useful for
1097 applications that analyze image data (image thresholding against a
1098 constant color, for example). The @code{GL_FUNC_ADD} equation is useful
1099 for antialiasing and transparency, among other things.
1101 Initially, both the RGB blend equation and the alpha blend equation are
1102 set to @code{GL_FUNC_ADD}.
1106 @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of
1107 @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT},
1108 @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MAX}, or @code{GL_MIN}.
1110 @code{GL_INVALID_OPERATION} is generated if @code{glBlendEquation} is
1111 executed between the execution of @code{glBegin} and the corresponding
1112 execution of @code{glEnd}.
1116 @deftypefun void glBlendFuncSeparate srcRGB dstRGB srcAlpha dstAlpha
1117 Specify pixel arithmetic for RGB and alpha components separately.
1121 Specifies how the red, green, and blue blending factors are computed.
1122 The following symbolic constants are accepted: @code{GL_ZERO},
1123 @code{GL_ONE}, @code{GL_SRC_COLOR}, @code{GL_ONE_MINUS_SRC_COLOR},
1124 @code{GL_DST_COLOR}, @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA},
1125 @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA},
1126 @code{GL_ONE_MINUS_DST_ALPHA}, @code{GL_CONSTANT_COLOR},
1127 @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA},
1128 @code{GL_ONE_MINUS_CONSTANT_ALPHA}, and @code{GL_SRC_ALPHA_SATURATE}.
1129 The initial value is @code{GL_ONE}.
1132 Specifies how the red, green, and blue destination blending factors are
1133 computed. The following symbolic constants are accepted: @code{GL_ZERO},
1134 @code{GL_ONE}, @code{GL_SRC_COLOR}, @code{GL_ONE_MINUS_SRC_COLOR},
1135 @code{GL_DST_COLOR}, @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA},
1136 @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA},
1137 @code{GL_ONE_MINUS_DST_ALPHA}. @code{GL_CONSTANT_COLOR},
1138 @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA}, and
1139 @code{GL_ONE_MINUS_CONSTANT_ALPHA}. The initial value is @code{GL_ZERO}.
1141 @item @var{srcAlpha}
1142 Specified how the alpha source blending factor is computed. The same
1143 symbolic constants are accepted as for @var{srcRGB}. The initial value
1146 @item @var{dstAlpha}
1147 Specified how the alpha destination blending factor is computed. The
1148 same symbolic constants are accepted as for @var{dstRGB}. The initial
1149 value is @code{GL_ZERO}.
1153 In RGBA mode, pixels can be drawn using a function that blends the
1154 incoming (source) RGBA values with the RGBA values that are already in
1155 the frame buffer (the destination values). Blending is initially
1156 disabled. Use @code{glEnable} and @code{glDisable} with argument
1157 @code{GL_BLEND} to enable and disable blending.
1159 @code{glBlendFuncSeparate} defines the operation of blending when it is
1160 enabled. @var{srcRGB} specifies which method is used to scale the source
1161 RGB-color components. @var{dstRGB} specifies which method is used to
1162 scale the destination RGB-color components. Likewise, @var{srcAlpha}
1163 specifies which method is used to scale the source alpha color
1164 component, and @var{dstAlpha} specifies which method is used to scale
1165 the destination alpha component. The possible methods are described in
1166 the following table. Each method defines four scale factors, one each
1167 for red, green, blue, and alpha.
1169 In the table and in subsequent equations, source and destination color
1170 components are referred to as
1171 @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and
1172 @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})}. The
1173 color specified by @code{glBlendColor} is referred to as
1174 @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})}.
1175 They are understood to have integer values between 0 and
1176 @r{(@var{k}_@var{R},@var{k}_@var{G}@var{k}_@var{B}@var{k}_@var{A})},
1179 @r{@var{k}_@var{c}=2^@var{m}_@var{c},-1}
1181 and @r{(@var{m}_@var{R},@var{m}_@var{G}@var{m}_@var{B}@var{m}_@var{A})}
1182 is the number of red, green, blue, and alpha bitplanes.
1184 Source and destination scale factors are referred to as
1185 @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and
1186 @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})}. All
1187 scale factors have range @r{[0,1]}.
1192 @item @strong{Parameter}
1193 @strong{RGB Factor}, @strong{Alpha Factor}
1195 @item @code{GL_ZERO}
1201 @item @code{GL_SRC_COLOR}
1202 @r{(@var{R}_@var{s}/@var{k}_@var{R},@var{G}_@var{s}/@var{k}_@var{G}@var{B}_@var{s}/@var{k}_@var{B})},
1203 @r{@var{A}_@var{s}/@var{k}_@var{A}}
1205 @item @code{GL_ONE_MINUS_SRC_COLOR}
1206 @r{(1,111)-(@var{R}_@var{s}/@var{k}_@var{R},@var{G}_@var{s}/@var{k}_@var{G}@var{B}_@var{s}/@var{k}_@var{B})},
1207 @r{1-@var{A}_@var{s}/@var{k}_@var{A}}
1209 @item @code{GL_DST_COLOR}
1210 @r{(@var{R}_@var{d}/@var{k}_@var{R},@var{G}_@var{d}/@var{k}_@var{G}@var{B}_@var{d}/@var{k}_@var{B})},
1211 @r{@var{A}_@var{d}/@var{k}_@var{A}}
1213 @item @code{GL_ONE_MINUS_DST_COLOR}
1214 @r{(1,11)-(@var{R}_@var{d}/@var{k}_@var{R},@var{G}_@var{d}/@var{k}_@var{G}@var{B}_@var{d}/@var{k}_@var{B})},
1215 @r{1-@var{A}_@var{d}/@var{k}_@var{A}}
1217 @item @code{GL_SRC_ALPHA}
1218 @r{(@var{A}_@var{s}/@var{k}_@var{A},@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A})},
1219 @r{@var{A}_@var{s}/@var{k}_@var{A}}
1221 @item @code{GL_ONE_MINUS_SRC_ALPHA}
1222 @r{(1,11)-(@var{A}_@var{s}/@var{k}_@var{A},@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A})},
1223 @r{1-@var{A}_@var{s}/@var{k}_@var{A}}
1225 @item @code{GL_DST_ALPHA}
1226 @r{(@var{A}_@var{d}/@var{k}_@var{A},@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A})},
1227 @r{@var{A}_@var{d}/@var{k}_@var{A}}
1229 @item @code{GL_ONE_MINUS_DST_ALPHA}
1230 @r{(1,11)-(@var{A}_@var{d}/@var{k}_@var{A},@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A})},
1231 @r{1-@var{A}_@var{d}/@var{k}_@var{A}}
1233 @item @code{GL_CONSTANT_COLOR}
1234 @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c})},
1237 @item @code{GL_ONE_MINUS_CONSTANT_COLOR}
1238 @r{(1,11)-(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c})},
1239 @r{1-@var{A}_@var{c}}
1241 @item @code{GL_CONSTANT_ALPHA}
1242 @r{(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c})},
1245 @item @code{GL_ONE_MINUS_CONSTANT_ALPHA}
1246 @r{(1,11)-(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c})},
1247 @r{1-@var{A}_@var{c}}
1249 @item @code{GL_SRC_ALPHA_SATURATE}
1250 @r{(@var{i},@var{i}@var{i})}, @r{1}
1256 @r{@var{i}=@var{min}(@var{A}_@var{s},1-@var{A}_@var{d},)}
1258 To determine the blended RGBA values of a pixel when drawing in RGBA
1259 mode, the system uses the following equations:
1261 @r{@var{R}_@var{d}=@var{min}(@var{k}_@var{R},@var{R}_@var{s}@var{s}_@var{R}+@var{R}_@var{d}@var{d}_@var{R})}@r{@var{G}_@var{d}=@var{min}(@var{k}_@var{G},@var{G}_@var{s}@var{s}_@var{G}+@var{G}_@var{d}@var{d}_@var{G})}@r{@var{B}_@var{d}=@var{min}(@var{k}_@var{B},@var{B}_@var{s}@var{s}_@var{B}+@var{B}_@var{d}@var{d}_@var{B})}@r{@var{A}_@var{d}=@var{min}(@var{k}_@var{A},@var{A}_@var{s}@var{s}_@var{A}+@var{A}_@var{d}@var{d}_@var{A})}
1263 Despite the apparent precision of the above equations, blending
1264 arithmetic is not exactly specified, because blending operates with
1265 imprecise integer color values. However, a blend factor that should be
1266 equal to 1 is guaranteed not to modify its multiplicand, and a blend
1267 factor equal to 0 reduces its multiplicand to 0. For example, when
1268 @var{srcRGB} is @code{GL_SRC_ALPHA}, @var{dstRGB} is
1269 @code{GL_ONE_MINUS_SRC_ALPHA}, and @r{@var{A}_@var{s}} is equal to
1270 @r{@var{k}_@var{A}}, the equations reduce to simple replacement:
1272 @r{@var{R}_@var{d}=@var{R}_@var{s}}@r{@var{G}_@var{d}=@var{G}_@var{s}}@r{@var{B}_@var{d}=@var{B}_@var{s}}@r{@var{A}_@var{d}=@var{A}_@var{s}}
1276 @code{GL_INVALID_ENUM} is generated if either @var{srcRGB} or
1277 @var{dstRGB} is not an accepted value.
1279 @code{GL_INVALID_OPERATION} is generated if @code{glBlendFuncSeparate}
1280 is executed between the execution of @code{glBegin} and the
1281 corresponding execution of @code{glEnd}.
1285 @deftypefun void glBlendFunc sfactor dfactor
1286 Specify pixel arithmetic.
1290 Specifies how the red, green, blue, and alpha source blending factors
1291 are computed. The following symbolic constants are accepted:
1292 @code{GL_ZERO}, @code{GL_ONE}, @code{GL_SRC_COLOR},
1293 @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_DST_COLOR},
1294 @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA},
1295 @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA},
1296 @code{GL_ONE_MINUS_DST_ALPHA}, @code{GL_CONSTANT_COLOR},
1297 @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA},
1298 @code{GL_ONE_MINUS_CONSTANT_ALPHA}, and @code{GL_SRC_ALPHA_SATURATE}.
1299 The initial value is @code{GL_ONE}.
1302 Specifies how the red, green, blue, and alpha destination blending
1303 factors are computed. The following symbolic constants are accepted:
1304 @code{GL_ZERO}, @code{GL_ONE}, @code{GL_SRC_COLOR},
1305 @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_DST_COLOR},
1306 @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA},
1307 @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA},
1308 @code{GL_ONE_MINUS_DST_ALPHA}. @code{GL_CONSTANT_COLOR},
1309 @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA}, and
1310 @code{GL_ONE_MINUS_CONSTANT_ALPHA}. The initial value is @code{GL_ZERO}.
1314 In RGBA mode, pixels can be drawn using a function that blends the
1315 incoming (source) RGBA values with the RGBA values that are already in
1316 the frame buffer (the destination values). Blending is initially
1317 disabled. Use @code{glEnable} and @code{glDisable} with argument
1318 @code{GL_BLEND} to enable and disable blending.
1320 @code{glBlendFunc} defines the operation of blending when it is enabled.
1321 @var{sfactor} specifies which method is used to scale the source color
1322 components. @var{dfactor} specifies which method is used to scale the
1323 destination color components. The possible methods are described in the
1324 following table. Each method defines four scale factors, one each for
1325 red, green, blue, and alpha. In the table and in subsequent equations,
1326 source and destination color components are referred to as
1327 @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and
1328 @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})}. The
1329 color specified by @code{glBlendColor} is referred to as
1330 @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})}.
1331 They are understood to have integer values between 0 and
1332 @r{(@var{k}_@var{R},@var{k}_@var{G}@var{k}_@var{B}@var{k}_@var{A})},
1335 @r{@var{k}_@var{c}=2^@var{m}_@var{c},-1}
1337 and @r{(@var{m}_@var{R},@var{m}_@var{G}@var{m}_@var{B}@var{m}_@var{A})}
1338 is the number of red, green, blue, and alpha bitplanes.
1340 Source and destination scale factors are referred to as
1341 @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and
1342 @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})}. The
1343 scale factors described in the table, denoted
1344 @r{(@var{f}_@var{R},@var{f}_@var{G}@var{f}_@var{B}@var{f}_@var{A})},
1345 represent either source or destination factors. All scale factors have
1351 @item @strong{Parameter}
1352 @strong{@r{(@var{f}_@var{R},@var{f}_@var{G}@var{f}_@var{B}@var{f}_@var{A})}}
1354 @item @code{GL_ZERO}
1360 @item @code{GL_SRC_COLOR}
1361 @r{(@var{R}_@var{s}/@var{k}_@var{R},@var{G}_@var{s}/@var{k}_@var{G}@var{B}_@var{s}/@var{k}_@var{B}@var{A}_@var{s}/@var{k}_@var{A})}
1363 @item @code{GL_ONE_MINUS_SRC_COLOR}
1364 @r{(1,111)-(@var{R}_@var{s}/@var{k}_@var{R},@var{G}_@var{s}/@var{k}_@var{G}@var{B}_@var{s}/@var{k}_@var{B}@var{A}_@var{s}/@var{k}_@var{A})}
1366 @item @code{GL_DST_COLOR}
1367 @r{(@var{R}_@var{d}/@var{k}_@var{R},@var{G}_@var{d}/@var{k}_@var{G}@var{B}_@var{d}/@var{k}_@var{B}@var{A}_@var{d}/@var{k}_@var{A})}
1369 @item @code{GL_ONE_MINUS_DST_COLOR}
1370 @r{(1,111)-(@var{R}_@var{d}/@var{k}_@var{R},@var{G}_@var{d}/@var{k}_@var{G}@var{B}_@var{d}/@var{k}_@var{B}@var{A}_@var{d}/@var{k}_@var{A})}
1372 @item @code{GL_SRC_ALPHA}
1373 @r{(@var{A}_@var{s}/@var{k}_@var{A},@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A})}
1375 @item @code{GL_ONE_MINUS_SRC_ALPHA}
1376 @r{(1,111)-(@var{A}_@var{s}/@var{k}_@var{A},@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A})}
1378 @item @code{GL_DST_ALPHA}
1379 @r{(@var{A}_@var{d}/@var{k}_@var{A},@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A})}
1381 @item @code{GL_ONE_MINUS_DST_ALPHA}
1382 @r{(1,111)-(@var{A}_@var{d}/@var{k}_@var{A},@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A})}
1384 @item @code{GL_CONSTANT_COLOR}
1385 @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})}
1387 @item @code{GL_ONE_MINUS_CONSTANT_COLOR}
1388 @r{(1,111)-(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})}
1390 @item @code{GL_CONSTANT_ALPHA}
1391 @r{(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c}@var{A}_@var{c})}
1393 @item @code{GL_ONE_MINUS_CONSTANT_ALPHA}
1394 @r{(1,111)-(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c}@var{A}_@var{c})}
1396 @item @code{GL_SRC_ALPHA_SATURATE}
1397 @r{(@var{i},@var{i}@var{i}1)}
1403 @r{@var{i}=@var{min}(@var{A}_@var{s},@var{k}_@var{A}-@var{A}_@var{d})/@var{k}_@var{A}}
1405 To determine the blended RGBA values of a pixel when drawing in RGBA
1406 mode, the system uses the following equations:
1408 @r{@var{R}_@var{d}=@var{min}(@var{k}_@var{R},@var{R}_@var{s}@var{s}_@var{R}+@var{R}_@var{d}@var{d}_@var{R})}@r{@var{G}_@var{d}=@var{min}(@var{k}_@var{G},@var{G}_@var{s}@var{s}_@var{G}+@var{G}_@var{d}@var{d}_@var{G})}@r{@var{B}_@var{d}=@var{min}(@var{k}_@var{B},@var{B}_@var{s}@var{s}_@var{B}+@var{B}_@var{d}@var{d}_@var{B})}@r{@var{A}_@var{d}=@var{min}(@var{k}_@var{A},@var{A}_@var{s}@var{s}_@var{A}+@var{A}_@var{d}@var{d}_@var{A})}
1410 Despite the apparent precision of the above equations, blending
1411 arithmetic is not exactly specified, because blending operates with
1412 imprecise integer color values. However, a blend factor that should be
1413 equal to 1 is guaranteed not to modify its multiplicand, and a blend
1414 factor equal to 0 reduces its multiplicand to 0. For example, when
1415 @var{sfactor} is @code{GL_SRC_ALPHA}, @var{dfactor} is
1416 @code{GL_ONE_MINUS_SRC_ALPHA}, and @r{@var{A}_@var{s}} is equal to
1417 @r{@var{k}_@var{A}}, the equations reduce to simple replacement:
1419 @r{@var{R}_@var{d}=@var{R}_@var{s}}@r{@var{G}_@var{d}=@var{G}_@var{s}}@r{@var{B}_@var{d}=@var{B}_@var{s}}@r{@var{A}_@var{d}=@var{A}_@var{s}}
1423 @code{GL_INVALID_ENUM} is generated if either @var{sfactor} or
1424 @var{dfactor} is not an accepted value.
1426 @code{GL_INVALID_OPERATION} is generated if @code{glBlendFunc} is
1427 executed between the execution of @code{glBegin} and the corresponding
1428 execution of @code{glEnd}.
1432 @deftypefun void glBufferData target size data usage
1433 Creates and initializes a buffer object's data store.
1437 Specifies the target buffer object. The symbolic constant must be
1438 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
1439 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
1442 Specifies the size in bytes of the buffer object's new data store.
1445 Specifies a pointer to data that will be copied into the data store for
1446 initialization, or @code{NULL} if no data is to be copied.
1449 Specifies the expected usage pattern of the data store. The symbolic
1450 constant must be @code{GL_STREAM_DRAW}, @code{GL_STREAM_READ},
1451 @code{GL_STREAM_COPY}, @code{GL_STATIC_DRAW}, @code{GL_STATIC_READ},
1452 @code{GL_STATIC_COPY}, @code{GL_DYNAMIC_DRAW}, @code{GL_DYNAMIC_READ},
1453 or @code{GL_DYNAMIC_COPY}.
1457 @code{glBufferData} creates a new data store for the buffer object
1458 currently bound to @var{target}. Any pre-existing data store is deleted.
1459 The new data store is created with the specified @var{size} in bytes and
1460 @var{usage}. If @var{data} is not @code{NULL}, the data store is
1461 initialized with data from this pointer. In its initial state, the new
1462 data store is not mapped, it has a @code{NULL} mapped pointer, and its
1463 mapped access is @code{GL_READ_WRITE}.
1465 @var{usage} is a hint to the GL implementation as to how a buffer
1466 object's data store will be accessed. This enables the GL implementation
1467 to make more intelligent decisions that may significantly impact buffer
1468 object performance. It does not, however, constrain the actual usage of
1469 the data store. @var{usage} can be broken down into two parts: first,
1470 the frequency of access (modification and usage), and second, the nature
1471 of that access. The frequency of access may be one of these:
1475 The data store contents will be modified once and used at most a few
1479 The data store contents will be modified once and used many times.
1482 The data store contents will be modified repeatedly and used many times.
1486 The nature of access may be one of these:
1490 The data store contents are modified by the application, and used as the
1491 source for GL drawing and image specification commands.
1494 The data store contents are modified by reading data from the GL, and
1495 used to return that data when queried by the application.
1498 The data store contents are modified by reading data from the GL, and
1499 used as the source for GL drawing and image specification commands.
1503 @code{GL_INVALID_ENUM} is generated if @var{target} is not
1504 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
1505 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
1507 @code{GL_INVALID_ENUM} is generated if @var{usage} is not
1508 @code{GL_STREAM_DRAW}, @code{GL_STREAM_READ}, @code{GL_STREAM_COPY},
1509 @code{GL_STATIC_DRAW}, @code{GL_STATIC_READ}, @code{GL_STATIC_COPY},
1510 @code{GL_DYNAMIC_DRAW}, @code{GL_DYNAMIC_READ}, or
1511 @code{GL_DYNAMIC_COPY}.
1513 @code{GL_INVALID_VALUE} is generated if @var{size} is negative.
1515 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
1516 name 0 is bound to @var{target}.
1518 @code{GL_OUT_OF_MEMORY} is generated if the GL is unable to create a
1519 data store with the specified @var{size}.
1521 @code{GL_INVALID_OPERATION} is generated if @code{glBufferData} is
1522 executed between the execution of @code{glBegin} and the corresponding
1523 execution of @code{glEnd}.
1527 @deftypefun void glBufferSubData target offset size data
1528 Updates a subset of a buffer object's data store.
1532 Specifies the target buffer object. The symbolic constant must be
1533 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
1534 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
1537 Specifies the offset into the buffer object's data store where data
1538 replacement will begin, measured in bytes.
1541 Specifies the size in bytes of the data store region being replaced.
1544 Specifies a pointer to the new data that will be copied into the data
1549 @code{glBufferSubData} redefines some or all of the data store for the
1550 buffer object currently bound to @var{target}. Data starting at byte
1551 offset @var{offset} and extending for @var{size} bytes is copied to the
1552 data store from the memory pointed to by @var{data}. An error is thrown
1553 if @var{offset} and @var{size} together define a range beyond the bounds
1554 of the buffer object's data store.
1556 @code{GL_INVALID_ENUM} is generated if @var{target} is not
1557 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
1558 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
1560 @code{GL_INVALID_VALUE} is generated if @var{offset} or @var{size} is
1561 negative, or if together they define a region of memory that extends
1562 beyond the buffer object's allocated data store.
1564 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
1565 name 0 is bound to @var{target}.
1567 @code{GL_INVALID_OPERATION} is generated if the buffer object being
1570 @code{GL_INVALID_OPERATION} is generated if @code{glBufferSubData} is
1571 executed between the execution of @code{glBegin} and the corresponding
1572 execution of @code{glEnd}.
1576 @deftypefun void glCallLists n type lists
1577 Execute a list of display lists.
1581 Specifies the number of display lists to be executed.
1584 Specifies the type of values in @var{lists}. Symbolic constants
1585 @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
1586 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
1587 @code{GL_FLOAT}, @code{GL_2_BYTES}, @code{GL_3_BYTES}, and
1588 @code{GL_4_BYTES} are accepted.
1591 Specifies the address of an array of name offsets in the display list.
1592 The pointer type is void because the offsets can be bytes, shorts, ints,
1593 or floats, depending on the value of @var{type}.
1597 @code{glCallLists} causes each display list in the list of names passed
1598 as @var{lists} to be executed. As a result, the commands saved in each
1599 display list are executed in order, just as if they were called without
1600 using a display list. Names of display lists that have not been defined
1603 @code{glCallLists} provides an efficient means for executing more than
1604 one display list. @var{type} allows lists with various name formats to
1605 be accepted. The formats are as follows:
1608 @item @code{GL_BYTE}
1609 @var{lists} is treated as an array of signed bytes, each in the range
1610 @r{-128} through 127.
1612 @item @code{GL_UNSIGNED_BYTE}
1613 @var{lists} is treated as an array of unsigned bytes, each in the range
1616 @item @code{GL_SHORT}
1617 @var{lists} is treated as an array of signed two-byte integers, each in
1618 the range @r{-32768} through 32767.
1620 @item @code{GL_UNSIGNED_SHORT}
1621 @var{lists} is treated as an array of unsigned two-byte integers, each
1622 in the range 0 through 65535.
1625 @var{lists} is treated as an array of signed four-byte integers.
1627 @item @code{GL_UNSIGNED_INT}
1628 @var{lists} is treated as an array of unsigned four-byte integers.
1630 @item @code{GL_FLOAT}
1631 @var{lists} is treated as an array of four-byte floating-point values.
1633 @item @code{GL_2_BYTES}
1634 @var{lists} is treated as an array of unsigned bytes. Each pair of bytes
1635 specifies a single display-list name. The value of the pair is computed
1636 as 256 times the unsigned value of the first byte plus the unsigned
1637 value of the second byte.
1639 @item @code{GL_3_BYTES}
1640 @var{lists} is treated as an array of unsigned bytes. Each triplet of
1641 bytes specifies a single display-list name. The value of the triplet is
1642 computed as 65536 times the unsigned value of the first byte, plus 256
1643 times the unsigned value of the second byte, plus the unsigned value of
1646 @item @code{GL_4_BYTES}
1647 @var{lists} is treated as an array of unsigned bytes. Each quadruplet of
1648 bytes specifies a single display-list name. The value of the quadruplet
1649 is computed as 16777216 times the unsigned value of the first byte, plus
1650 65536 times the unsigned value of the second byte, plus 256 times the
1651 unsigned value of the third byte, plus the unsigned value of the fourth
1656 The list of display-list names is not null-terminated. Rather, @var{n}
1657 specifies how many names are to be taken from @var{lists}.
1659 An additional level of indirection is made available with the
1660 @code{glListBase} command, which specifies an unsigned offset that is
1661 added to each display-list name specified in @var{lists} before that
1662 display list is executed.
1664 @code{glCallLists} can appear inside a display list. To avoid the
1665 possibility of infinite recursion resulting from display lists calling
1666 one another, a limit is placed on the nesting level of display lists
1667 during display-list execution. This limit must be at least 64, and it
1668 depends on the implementation.
1670 GL state is not saved and restored across a call to @code{glCallLists}.
1671 Thus, changes made to GL state during the execution of the display lists
1672 remain after execution is completed. Use @code{glPushAttrib},
1673 @code{glPopAttrib}, @code{glPushMatrix}, and @code{glPopMatrix} to
1674 preserve GL state across @code{glCallLists} calls.
1676 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
1678 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of
1679 @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
1680 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
1681 @code{GL_FLOAT}, @code{GL_2_BYTES}, @code{GL_3_BYTES},
1686 @deftypefun void glCallList list
1687 Execute a display list.
1691 Specifies the integer name of the display list to be executed.
1695 @code{glCallList} causes the named display list to be executed. The
1696 commands saved in the display list are executed in order, just as if
1697 they were called without using a display list. If @var{list} has not
1698 been defined as a display list, @code{glCallList} is ignored.
1700 @code{glCallList} can appear inside a display list. To avoid the
1701 possibility of infinite recursion resulting from display lists calling
1702 one another, a limit is placed on the nesting level of display lists
1703 during display-list execution. This limit is at least 64, and it depends
1704 on the implementation.
1706 GL state is not saved and restored across a call to @code{glCallList}.
1707 Thus, changes made to GL state during the execution of a display list
1708 remain after execution of the display list is completed. Use
1709 @code{glPushAttrib}, @code{glPopAttrib}, @code{glPushMatrix}, and
1710 @code{glPopMatrix} to preserve GL state across @code{glCallList} calls.
1714 @deftypefun void glClearAccum red green blue alpha
1715 Specify clear values for the accumulation buffer.
1722 Specify the red, green, blue, and alpha values used when the
1723 accumulation buffer is cleared. The initial values are all 0.
1727 @code{glClearAccum} specifies the red, green, blue, and alpha values
1728 used by @code{glClear} to clear the accumulation buffer.
1730 Values specified by @code{glClearAccum} are clamped to the range
1733 @code{GL_INVALID_OPERATION} is generated if @code{glClearAccum} is
1734 executed between the execution of @code{glBegin} and the corresponding
1735 execution of @code{glEnd}.
1739 @deftypefun void glClearColor red green blue alpha
1740 Specify clear values for the color buffers.
1747 Specify the red, green, blue, and alpha values used when the color
1748 buffers are cleared. The initial values are all 0.
1752 @code{glClearColor} specifies the red, green, blue, and alpha values
1753 used by @code{glClear} to clear the color buffers. Values specified by
1754 @code{glClearColor} are clamped to the range @r{[0,1]}.
1756 @code{GL_INVALID_OPERATION} is generated if @code{glClearColor} is
1757 executed between the execution of @code{glBegin} and the corresponding
1758 execution of @code{glEnd}.
1762 @deftypefun void glClearDepth depth
1763 Specify the clear value for the depth buffer.
1767 Specifies the depth value used when the depth buffer is cleared. The
1772 @code{glClearDepth} specifies the depth value used by @code{glClear} to
1773 clear the depth buffer. Values specified by @code{glClearDepth} are
1774 clamped to the range @r{[0,1]}.
1776 @code{GL_INVALID_OPERATION} is generated if @code{glClearDepth} is
1777 executed between the execution of @code{glBegin} and the corresponding
1778 execution of @code{glEnd}.
1782 @deftypefun void glClearIndex c
1783 Specify the clear value for the color index buffers.
1787 Specifies the index used when the color index buffers are cleared. The
1792 @code{glClearIndex} specifies the index used by @code{glClear} to clear
1793 the color index buffers. @var{c} is not clamped. Rather, @var{c} is
1794 converted to a fixed-point value with unspecified precision to the right
1795 of the binary point. The integer part of this value is then masked with
1796 @r{2^@var{m}-1}, where @r{@var{m}} is the number of bits in a color
1797 index stored in the frame buffer.
1799 @code{GL_INVALID_OPERATION} is generated if @code{glClearIndex} is
1800 executed between the execution of @code{glBegin} and the corresponding
1801 execution of @code{glEnd}.
1805 @deftypefun void glClearStencil s
1806 Specify the clear value for the stencil buffer.
1810 Specifies the index used when the stencil buffer is cleared. The initial
1815 @code{glClearStencil} specifies the index used by @code{glClear} to
1816 clear the stencil buffer. @var{s} is masked with @r{2^@var{m}-1}, where
1817 @r{@var{m}} is the number of bits in the stencil buffer.
1819 @code{GL_INVALID_OPERATION} is generated if @code{glClearStencil} is
1820 executed between the execution of @code{glBegin} and the corresponding
1821 execution of @code{glEnd}.
1825 @deftypefun void glClear mask
1826 Clear buffers to preset values.
1830 Bitwise OR of masks that indicate the buffers to be cleared. The four
1831 masks are @code{GL_COLOR_BUFFER_BIT}, @code{GL_DEPTH_BUFFER_BIT},
1832 @code{GL_ACCUM_BUFFER_BIT}, and @code{GL_STENCIL_BUFFER_BIT}.
1836 @code{glClear} sets the bitplane area of the window to values previously
1837 selected by @code{glClearColor}, @code{glClearIndex},
1838 @code{glClearDepth}, @code{glClearStencil}, and @code{glClearAccum}.
1839 Multiple color buffers can be cleared simultaneously by selecting more
1840 than one buffer at a time using @code{glDrawBuffer}.
1842 The pixel ownership test, the scissor test, dithering, and the buffer
1843 writemasks affect the operation of @code{glClear}. The scissor box
1844 bounds the cleared region. Alpha function, blend function, logical
1845 operation, stenciling, texture mapping, and depth-buffering are ignored
1848 @code{glClear} takes a single argument that is the bitwise OR of several
1849 values indicating which buffer is to be cleared.
1851 The values are as follows:
1854 @item @code{GL_COLOR_BUFFER_BIT}
1855 Indicates the buffers currently enabled for color writing.
1857 @item @code{GL_DEPTH_BUFFER_BIT}
1858 Indicates the depth buffer.
1860 @item @code{GL_ACCUM_BUFFER_BIT}
1861 Indicates the accumulation buffer.
1863 @item @code{GL_STENCIL_BUFFER_BIT}
1864 Indicates the stencil buffer.
1868 The value to which each buffer is cleared depends on the setting of the
1869 clear value for that buffer.
1871 @code{GL_INVALID_VALUE} is generated if any bit other than the four
1872 defined bits is set in @var{mask}.
1874 @code{GL_INVALID_OPERATION} is generated if @code{glClear} is executed
1875 between the execution of @code{glBegin} and the corresponding execution
1880 @deftypefun void glClientActiveTexture texture
1881 Select active texture unit.
1885 Specifies which texture unit to make active. The number of texture units
1886 is implementation dependent, but must be at least two. @var{texture}
1887 must be one of @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to
1888 the value of @code{GL_MAX_TEXTURE_COORDS} - 1, which is an
1889 implementation-dependent value. The initial value is @code{GL_TEXTURE0}.
1893 @code{glClientActiveTexture} selects the vertex array client state
1894 parameters to be modified by @code{glTexCoordPointer}, and enabled or
1895 disabled with @code{glEnableClientState} or @code{glDisableClientState},
1896 respectively, when called with a parameter of
1897 @code{GL_TEXTURE_COORD_ARRAY}.
1899 @code{GL_INVALID_ENUM} is generated if @var{texture} is not one of
1900 @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to the value of
1901 @code{GL_MAX_TEXTURE_COORDS} - 1.
1905 @deftypefun void glClipPlane plane equation
1906 Specify a plane against which all geometry is clipped.
1910 Specifies which clipping plane is being positioned. Symbolic names of
1911 the form @code{GL_CLIP_PLANE}@var{i}, where @var{i} is an integer
1912 between 0 and @code{GL_MAX_CLIP_PLANES}@r{-1}, are accepted.
1914 @item @var{equation}
1915 Specifies the address of an array of four double-precision
1916 floating-point values. These values are interpreted as a plane equation.
1920 Geometry is always clipped against the boundaries of a six-plane frustum
1921 in @var{x}, @var{y}, and @var{z}. @code{glClipPlane} allows the
1922 specification of additional planes, not necessarily perpendicular to the
1923 @var{x}, @var{y}, or @var{z} axis, against which all geometry is
1924 clipped. To determine the maximum number of additional clipping planes,
1925 call @code{glGetIntegerv} with argument @code{GL_MAX_CLIP_PLANES}. All
1926 implementations support at least six such clipping planes. Because the
1927 resulting clipping region is the intersection of the defined
1928 half-spaces, it is always convex.
1930 @code{glClipPlane} specifies a half-space using a four-component plane
1931 equation. When @code{glClipPlane} is called, @var{equation} is
1932 transformed by the inverse of the modelview matrix and stored in the
1933 resulting eye coordinates. Subsequent changes to the modelview matrix
1934 have no effect on the stored plane-equation components. If the dot
1935 product of the eye coordinates of a vertex with the stored plane
1936 equation components is positive or zero, the vertex is @var{in} with
1937 respect to that clipping plane. Otherwise, it is @var{out}.
1939 To enable and disable clipping planes, call @code{glEnable} and
1940 @code{glDisable} with the argument @code{GL_CLIP_PLANE}@var{i}, where
1941 @var{i} is the plane number.
1943 All clipping planes are initially defined as (0, 0, 0, 0) in eye
1944 coordinates and are disabled.
1946 @code{GL_INVALID_ENUM} is generated if @var{plane} is not an accepted
1949 @code{GL_INVALID_OPERATION} is generated if @code{glClipPlane} is
1950 executed between the execution of @code{glBegin} and the corresponding
1951 execution of @code{glEnd}.
1955 @deftypefun void glColorMask red green blue alpha
1956 Enable and disable writing of frame buffer color components.
1963 Specify whether red, green, blue, and alpha can or cannot be written
1964 into the frame buffer. The initial values are all @code{GL_TRUE},
1965 indicating that the color components can be written.
1969 @code{glColorMask} specifies whether the individual color components in
1970 the frame buffer can or cannot be written. If @var{red} is
1971 @code{GL_FALSE}, for example, no change is made to the red component of
1972 any pixel in any of the color buffers, regardless of the drawing
1973 operation attempted.
1975 Changes to individual bits of components cannot be controlled. Rather,
1976 changes are either enabled or disabled for entire color components.
1978 @code{GL_INVALID_OPERATION} is generated if @code{glColorMask} is
1979 executed between the execution of @code{glBegin} and the corresponding
1980 execution of @code{glEnd}.
1984 @deftypefun void glColorMaterial face mode
1985 Cause a material color to track the current color.
1989 Specifies whether front, back, or both front and back material
1990 parameters should track the current color. Accepted values are
1991 @code{GL_FRONT}, @code{GL_BACK}, and @code{GL_FRONT_AND_BACK}. The
1992 initial value is @code{GL_FRONT_AND_BACK}.
1995 Specifies which of several material parameters track the current color.
1996 Accepted values are @code{GL_EMISSION}, @code{GL_AMBIENT},
1997 @code{GL_DIFFUSE}, @code{GL_SPECULAR}, and
1998 @code{GL_AMBIENT_AND_DIFFUSE}. The initial value is
1999 @code{GL_AMBIENT_AND_DIFFUSE}.
2003 @code{glColorMaterial} specifies which material parameters track the
2004 current color. When @code{GL_COLOR_MATERIAL} is enabled, the material
2005 parameter or parameters specified by @var{mode}, of the material or
2006 materials specified by @var{face}, track the current color at all times.
2008 To enable and disable @code{GL_COLOR_MATERIAL}, call @code{glEnable} and
2009 @code{glDisable} with argument @code{GL_COLOR_MATERIAL}.
2010 @code{GL_COLOR_MATERIAL} is initially disabled.
2012 @code{GL_INVALID_ENUM} is generated if @var{face} or @var{mode} is not
2015 @code{GL_INVALID_OPERATION} is generated if @code{glColorMaterial} is
2016 executed between the execution of @code{glBegin} and the corresponding
2017 execution of @code{glEnd}.
2021 @deftypefun void glColorPointer size type stride pointer
2022 Define an array of colors.
2026 Specifies the number of components per color. Must be 3 or 4. The
2030 Specifies the data type of each color component in the array. Symbolic
2031 constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
2032 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
2033 @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value is
2037 Specifies the byte offset between consecutive colors. If @var{stride} is
2038 0, the colors are understood to be tightly packed in the array. The
2042 Specifies a pointer to the first component of the first color element in
2043 the array. The initial value is 0.
2047 @code{glColorPointer} specifies the location and data format of an array
2048 of color components to use when rendering. @var{size} specifies the
2049 number of components per color, and must be 3 or 4. @var{type} specifies
2050 the data type of each color component, and @var{stride} specifies the
2051 byte stride from one color to the next, allowing vertices and attributes
2052 to be packed into a single array or stored in separate arrays.
2053 (Single-array storage may be more efficient on some implementations; see
2054 @code{glInterleavedArrays}.)
2056 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
2057 target (see @code{glBindBuffer}) while a color array is specified,
2058 @var{pointer} is treated as a byte offset into the buffer object's data
2059 store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING})
2060 is saved as color vertex array client-side state
2061 (@code{GL_COLOR_ARRAY_BUFFER_BINDING}).
2063 When a color array is specified, @var{size}, @var{type}, @var{stride},
2064 and @var{pointer} are saved as client-side state, in addition to the
2065 current vertex array buffer object binding.
2067 To enable and disable the color array, call @code{glEnableClientState}
2068 and @code{glDisableClientState} with the argument @code{GL_COLOR_ARRAY}.
2069 If enabled, the color array is used when @code{glDrawArrays},
2070 @code{glMultiDrawArrays}, @code{glDrawElements},
2071 @code{glMultiDrawElements}, @code{glDrawRangeElements}, or
2072 @code{glArrayElement} is called.
2074 @code{GL_INVALID_VALUE} is generated if @var{size} is not 3 or 4.
2076 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
2079 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
2083 @deftypefun void glColorSubTable target start count format type data
2084 Respecify a portion of a color table.
2088 Must be one of @code{GL_COLOR_TABLE},
2089 @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
2090 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}.
2093 The starting index of the portion of the color table to be replaced.
2096 The number of table entries to replace.
2099 The format of the pixel data in @var{data}. The allowable values are
2100 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
2101 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB},
2102 @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}.
2105 The type of the pixel data in @var{data}. The allowable values are
2106 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT},
2107 @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT},
2108 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
2109 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
2110 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
2111 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
2112 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
2113 @code{GL_UNSIGNED_INT_10_10_10_2}, and
2114 @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
2117 Pointer to a one-dimensional array of pixel data that is processed to
2118 replace the specified region of the color table.
2122 @code{glColorSubTable} is used to respecify a contiguous portion of a
2123 color table previously defined using @code{glColorTable}. The pixels
2124 referenced by @var{data} replace the portion of the existing table from
2125 indices @var{start} to @r{@var{start}+@var{count}-1}, inclusive. This
2126 region may not include any entries outside the range of the color table
2127 as it was originally specified. It is not an error to specify a
2128 subtexture with width of 0, but such a specification has no effect.
2130 If a non-zero named buffer object is bound to the
2131 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2132 portion of a color table is respecified, @var{data} is treated as a byte
2133 offset into the buffer object's data store.
2135 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
2138 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
2141 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
2144 @code{GL_INVALID_VALUE} is generated if
2145 @r{@var{start}+@var{count}>@var{width}}.
2147 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2148 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2149 object's data store is currently mapped.
2151 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2152 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2153 would be unpacked from the buffer object such that the memory reads
2154 required would exceed the data store size.
2156 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2157 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
2158 is not evenly divisible into the number of bytes needed to store in
2159 memory a datum indicated by @var{type}.
2161 @code{GL_INVALID_OPERATION} is generated if @code{glColorSubTable} is
2162 executed between the execution of @code{glBegin} and the corresponding
2163 execution of @code{glEnd}.
2167 @deftypefun void glColorTableParameterfv target pname params
2168 @deftypefunx void glColorTableParameteriv target pname params
2169 Set color lookup table parameters.
2173 The target color table. Must be @code{GL_COLOR_TABLE},
2174 @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
2175 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}.
2178 The symbolic name of a texture color lookup table parameter. Must be one
2179 of @code{GL_COLOR_TABLE_SCALE} or @code{GL_COLOR_TABLE_BIAS}.
2182 A pointer to an array where the values of the parameters are stored.
2186 @code{glColorTableParameter} is used to specify the scale factors and
2187 bias terms applied to color components when they are loaded into a color
2188 table. @var{target} indicates which color table the scale and bias terms
2189 apply to; it must be set to @code{GL_COLOR_TABLE},
2190 @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
2191 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}.
2193 @var{pname} must be @code{GL_COLOR_TABLE_SCALE} to set the scale
2194 factors. In this case, @var{params} points to an array of four values,
2195 which are the scale factors for red, green, blue, and alpha, in that
2198 @var{pname} must be @code{GL_COLOR_TABLE_BIAS} to set the bias terms. In
2199 this case, @var{params} points to an array of four values, which are the
2200 bias terms for red, green, blue, and alpha, in that order.
2202 The color tables themselves are specified by calling
2203 @code{glColorTable}.
2205 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
2206 not an acceptable value.
2208 @code{GL_INVALID_OPERATION} is generated if @code{glColorTableParameter}
2209 is executed between the execution of @code{glBegin} and the
2210 corresponding execution of @code{glEnd}.
2214 @deftypefun void glColorTable target internalformat width format type data
2215 Define a color lookup table.
2219 Must be one of @code{GL_COLOR_TABLE},
2220 @code{GL_POST_CONVOLUTION_COLOR_TABLE},
2221 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{GL_PROXY_COLOR_TABLE},
2222 @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or
2223 @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}.
2225 @item @var{internalformat}
2226 The internal format of the color table. The allowable values are
2227 @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
2228 @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
2229 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
2230 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
2231 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
2232 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
2233 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY},
2234 @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12},
2235 @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
2236 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
2237 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
2238 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
2239 @code{GL_RGBA12}, and @code{GL_RGBA16}.
2242 The number of entries in the color lookup table specified by @var{data}.
2245 The format of the pixel data in @var{data}. The allowable values are
2246 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
2247 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB},
2248 @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}.
2251 The type of the pixel data in @var{data}. The allowable values are
2252 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT},
2253 @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT},
2254 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
2255 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
2256 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
2257 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
2258 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
2259 @code{GL_UNSIGNED_INT_10_10_10_2}, and
2260 @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
2263 Pointer to a one-dimensional array of pixel data that is processed to
2264 build the color table.
2268 @code{glColorTable} may be used in two ways: to test the actual size and
2269 color resolution of a lookup table given a particular set of parameters,
2270 or to load the contents of a color lookup table. Use the targets
2271 @code{GL_PROXY_*} for the first case and the other targets for the
2274 If a non-zero named buffer object is bound to the
2275 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2276 color table is specified, @var{data} is treated as a byte offset into
2277 the buffer object's data store.
2279 If @var{target} is @code{GL_COLOR_TABLE},
2280 @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
2281 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{glColorTable} builds a
2282 color lookup table from an array of pixels. The pixel array specified by
2283 @var{width}, @var{format}, @var{type}, and @var{data} is extracted from
2284 memory and processed just as if @code{glDrawPixels} were called, but
2285 processing stops after the final expansion to RGBA is completed.
2287 The four scale parameters and the four bias parameters that are defined
2288 for the table are then used to scale and bias the R, G, B, and A
2289 components of each pixel. (Use @code{glColorTableParameter} to set these
2290 scale and bias parameters.)
2292 Next, the R, G, B, and A values are clamped to the range @r{[0,1]}. Each
2293 pixel is then converted to the internal format specified by
2294 @var{internalformat}. This conversion simply maps the component values
2295 of the pixel (R, G, B, and A) to the values included in the internal
2296 format (red, green, blue, alpha, luminance, and intensity). The mapping
2302 @item @strong{Internal Format}
2303 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
2304 @strong{Luminance}, @strong{Intensity}
2306 @item @code{GL_ALPHA}
2309 @item @code{GL_LUMINANCE}
2312 @item @code{GL_LUMINANCE_ALPHA}
2315 @item @code{GL_INTENSITY}
2321 @item @code{GL_RGBA}
2326 Finally, the red, green, blue, alpha, luminance, and/or intensity
2327 components of the resulting pixels are stored in the color table. They
2328 form a one-dimensional table with indices in the range
2329 @r{[0,@var{width}-1]}.
2331 If @var{target} is @code{GL_PROXY_*}, @code{glColorTable} recomputes and
2332 stores the values of the proxy color table's state variables
2333 @code{GL_COLOR_TABLE_FORMAT}, @code{GL_COLOR_TABLE_WIDTH},
2334 @code{GL_COLOR_TABLE_RED_SIZE}, @code{GL_COLOR_TABLE_GREEN_SIZE},
2335 @code{GL_COLOR_TABLE_BLUE_SIZE}, @code{GL_COLOR_TABLE_ALPHA_SIZE},
2336 @code{GL_COLOR_TABLE_LUMINANCE_SIZE}, and
2337 @code{GL_COLOR_TABLE_INTENSITY_SIZE}. There is no effect on the image or
2338 state of any actual color table. If the specified color table is too
2339 large to be supported, then all the proxy state variables listed above
2340 are set to zero. Otherwise, the color table could be supported by
2341 @code{glColorTable} using the corresponding non-proxy target, and the
2342 proxy state variables are set as if that target were being defined.
2344 The proxy state variables can be retrieved by calling
2345 @code{glGetColorTableParameter} with a target of @code{GL_PROXY_*}. This
2346 allows the application to decide if a particular @code{glColorTable}
2347 command would succeed, and to determine what the resulting color table
2348 attributes would be.
2350 If a color table is enabled, and its width is non-zero, then its
2351 contents are used to replace a subset of the components of each RGBA
2352 pixel group, based on the internal format of the table.
2354 Each pixel group has color components (R, G, B, A) that are in the range
2355 @r{[0.0,1.0]}. The color components are rescaled to the size of the
2356 color lookup table to form an index. Then a subset of the components
2357 based on the internal format of the table are replaced by the table
2358 entry selected by that index. If the color components and contents of
2359 the table are represented as follows:
2364 @item @strong{Representation}
2368 Table index computed from @code{R}
2371 Table index computed from @code{G}
2374 Table index computed from @code{B}
2377 Table index computed from @code{A}
2380 Luminance value at table index @code{i}
2383 Intensity value at table index @code{i}
2386 Red value at table index @code{i}
2389 Green value at table index @code{i}
2392 Blue value at table index @code{i}
2395 Alpha value at table index @code{i}
2399 then the result of color table lookup is as follows:
2405 @strong{Resulting Texture Components}
2407 @item @strong{Table Internal Format}
2408 @strong{R}, @strong{G}, @strong{B}, @strong{A}
2410 @item @code{GL_ALPHA}
2411 @code{R}, @code{G}, @code{B}, @code{A[a]}
2413 @item @code{GL_LUMINANCE}
2414 @code{L[r]}, @code{L[g]}, @code{L[b]}, @code{At}
2416 @item @code{GL_LUMINANCE_ALPHA}
2417 @code{L[r]}, @code{L[g]}, @code{L[b]}, @code{A[a]}
2419 @item @code{GL_INTENSITY}
2420 @code{I[r]}, @code{I[g]}, @code{I[b]}, @code{I[a]}
2423 @code{R[r]}, @code{G[g]}, @code{B[b]}, @code{A}
2425 @item @code{GL_RGBA}
2426 @code{R[r]}, @code{G[g]}, @code{B[b]}, @code{A[a]}
2430 When @code{GL_COLOR_TABLE} is enabled, the colors resulting from the
2431 pixel map operation (if it is enabled) are mapped by the color lookup
2432 table before being passed to the convolution operation. The colors
2433 resulting from the convolution operation are modified by the post
2434 convolution color lookup table when
2435 @code{GL_POST_CONVOLUTION_COLOR_TABLE} is enabled. These modified colors
2436 are then sent to the color matrix operation. Finally, if
2437 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} is enabled, the colors resulting
2438 from the color matrix operation are mapped by the post color matrix
2439 color lookup table before being used by the histogram operation.
2443 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
2446 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
2447 of the allowable values.
2449 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
2452 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
2455 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero.
2457 @code{GL_TABLE_TOO_LARGE} is generated if the requested color table is
2458 too large to be supported by the implementation, and @var{target} is not
2459 a @code{GL_PROXY_*} target.
2461 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2462 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2463 object's data store is currently mapped.
2465 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2466 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2467 would be unpacked from the buffer object such that the memory reads
2468 required would exceed the data store size.
2470 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2471 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
2472 is not evenly divisible into the number of bytes needed to store in
2473 memory a datum indicated by @var{type}.
2475 @code{GL_INVALID_OPERATION} is generated if @code{glColorTable} is
2476 executed between the execution of @code{glBegin} and the corresponding
2477 execution of @code{glEnd}.
2481 @deftypefun void glColor3b red green blue
2482 @deftypefunx void glColor3s red green blue
2483 @deftypefunx void glColor3i red green blue
2484 @deftypefunx void glColor3f red green blue
2485 @deftypefunx void glColor3d red green blue
2486 @deftypefunx void glColor3ub red green blue
2487 @deftypefunx void glColor3us red green blue
2488 @deftypefunx void glColor3ui red green blue
2489 @deftypefunx void glColor4b red green blue alpha
2490 @deftypefunx void glColor4s red green blue alpha
2491 @deftypefunx void glColor4i red green blue alpha
2492 @deftypefunx void glColor4f red green blue alpha
2493 @deftypefunx void glColor4d red green blue alpha
2494 @deftypefunx void glColor4ub red green blue alpha
2495 @deftypefunx void glColor4us red green blue alpha
2496 @deftypefunx void glColor4ui red green blue alpha
2497 @deftypefunx void glColor3bv v
2498 @deftypefunx void glColor3sv v
2499 @deftypefunx void glColor3iv v
2500 @deftypefunx void glColor3fv v
2501 @deftypefunx void glColor3dv v
2502 @deftypefunx void glColor3ubv v
2503 @deftypefunx void glColor3usv v
2504 @deftypefunx void glColor3uiv v
2505 @deftypefunx void glColor4bv v
2506 @deftypefunx void glColor4sv v
2507 @deftypefunx void glColor4iv v
2508 @deftypefunx void glColor4fv v
2509 @deftypefunx void glColor4dv v
2510 @deftypefunx void glColor4ubv v
2511 @deftypefunx void glColor4usv v
2512 @deftypefunx void glColor4uiv v
2513 Set the current color.
2519 Specify new red, green, and blue values for the current color.
2522 Specifies a new alpha value for the current color. Included only in the
2523 four-argument @code{glColor4} commands.
2527 The GL stores both a current single-valued color index and a current
2528 four-valued RGBA color. @code{glColor} sets a new four-valued RGBA
2529 color. @code{glColor} has two major variants: @code{glColor3} and
2530 @code{glColor4}. @code{glColor3} variants specify new red, green, and
2531 blue values explicitly and set the current alpha value to 1.0 (full
2532 intensity) implicitly. @code{glColor4} variants specify all four color
2533 components explicitly.
2535 @code{glColor3b}, @code{glColor4b}, @code{glColor3s}, @code{glColor4s},
2536 @code{glColor3i}, and @code{glColor4i} take three or four signed byte,
2537 short, or long integers as arguments. When @strong{v} is appended to the
2538 name, the color commands can take a pointer to an array of such values.
2540 Current color values are stored in floating-point format, with
2541 unspecified mantissa and exponent sizes. Unsigned integer color
2542 components, when specified, are linearly mapped to floating-point values
2543 such that the largest representable value maps to 1.0 (full intensity),
2544 and 0 maps to 0.0 (zero intensity). Signed integer color components,
2545 when specified, are linearly mapped to floating-point values such that
2546 the most positive representable value maps to 1.0, and the most negative
2547 representable value maps to @r{-1.0}. (Note that this mapping does not
2548 convert 0 precisely to 0.0.) Floating-point values are mapped directly.
2550 Neither floating-point nor signed integer values are clamped to the
2551 range @r{[0,1]} before the current color is updated. However, color
2552 components are clamped to this range before they are interpolated or
2553 written into a color buffer.
2557 @deftypefun void glCompileShader shader
2558 Compiles a shader object.
2562 Specifies the shader object to be compiled.
2566 @code{glCompileShader} compiles the source code strings that have been
2567 stored in the shader object specified by @var{shader}.
2569 The compilation status will be stored as part of the shader object's
2570 state. This value will be set to @code{GL_TRUE} if the shader was
2571 compiled without errors and is ready for use, and @code{GL_FALSE}
2572 otherwise. It can be queried by calling @code{glGetShader} with
2573 arguments @var{shader} and @code{GL_COMPILE_STATUS}.
2575 Compilation of a shader can fail for a number of reasons as specified by
2576 the OpenGL Shading Language Specification. Whether or not the
2577 compilation was successful, information about the compilation can be
2578 obtained from the shader object's information log by calling
2579 @code{glGetShaderInfoLog}.
2581 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
2582 generated by OpenGL.
2584 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
2587 @code{GL_INVALID_OPERATION} is generated if @code{glCompileShader} is
2588 executed between the execution of @code{glBegin} and the corresponding
2589 execution of @code{glEnd}.
2593 @deftypefun void glCompressedTexImage1D target level internalformat width border imageSize data
2594 Specify a one-dimensional texture image in a compressed format.
2598 Specifies the target texture. Must be @code{GL_TEXTURE_1D} or
2599 @code{GL_PROXY_TEXTURE_1D}.
2602 Specifies the level-of-detail number. Level 0 is the base image level.
2603 Level @var{n} is the @var{n}th mipmap reduction image.
2605 @item @var{internalformat}
2606 Specifies the format of the compressed image data stored at address
2610 Specifies the width of the texture image including the border if any. If
2611 the GL version does not support non-power-of-two sizes, this value must
2612 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
2613 implementations support texture images that are at least 64 texels wide.
2614 The height of the 1D texture image is 1.
2617 Specifies the width of the border. Must be either 0 or 1.
2619 @item @var{imageSize}
2620 Specifies the number of unsigned bytes of image data starting at the
2621 address specified by @var{data}.
2624 Specifies a pointer to the compressed image data in memory.
2628 Texturing maps a portion of a specified texture image onto each
2629 graphical primitive for which texturing is enabled. To enable and
2630 disable one-dimensional texturing, call @code{glEnable} and
2631 @code{glDisable} with argument @code{GL_TEXTURE_1D}.
2633 @code{glCompressedTexImage1D} loads a previously defined, and retrieved,
2634 compressed one-dimensional texture image if @var{target} is
2635 @code{GL_TEXTURE_1D} (see @code{glTexImage1D}).
2637 If @var{target} is @code{GL_PROXY_TEXTURE_1D}, no data is read from
2638 @var{data}, but all of the texture image state is recalculated, checked
2639 for consistency, and checked against the implementation's capabilities.
2640 If the implementation cannot handle a texture of the requested texture
2641 size, it sets all of the image state to 0, but does not generate an
2642 error (see @code{glGetError}). To query for an entire mipmap array, use
2643 an image array level greater than or equal to 1.
2645 @var{internalformat} must be extension-specified compressed-texture
2646 format. When a texture is loaded with @code{glTexImage1D} using a
2647 generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}) the
2648 GL selects from one of its extensions supporting compressed textures. In
2649 order to load the compressed texture image using
2650 @code{glCompressedTexImage1D}, query the compressed texture image's size
2651 and format using @code{glGetTexLevelParameter}.
2653 If a non-zero named buffer object is bound to the
2654 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2655 texture image is specified, @var{data} is treated as a byte offset into
2656 the buffer object's data store.
2658 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of
2659 the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
2660 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
2661 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or
2662 @code{GL_COMPRESSED_RGBA}.
2664 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
2665 consistent with the format, dimensions, and contents of the specified
2666 compressed image data.
2668 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
2669 not supported by the specific compressed internal format as specified in
2670 the specific texture compression extension.
2672 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2673 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2674 object's data store is currently mapped.
2676 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2677 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2678 would be unpacked from the buffer object such that the memory reads
2679 required would exceed the data store size.
2681 @code{GL_INVALID_OPERATION} is generated if
2682 @code{glCompressedTexImage1D} is executed between the execution of
2683 @code{glBegin} and the corresponding execution of @code{glEnd}.
2685 Undefined results, including abnormal program termination, are generated
2686 if @var{data} is not encoded in a manner consistent with the extension
2687 specification defining the internal compression format.
2691 @deftypefun void glCompressedTexImage2D target level internalformat width height border imageSize data
2692 Specify a two-dimensional texture image in a compressed format.
2696 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
2697 @code{GL_PROXY_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
2698 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
2699 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
2700 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
2701 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z},
2702 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or
2703 @code{GL_PROXY_TEXTURE_CUBE_MAP}.
2706 Specifies the level-of-detail number. Level 0 is the base image level.
2707 Level @var{n} is the @var{n}th mipmap reduction image.
2709 @item @var{internalformat}
2710 Specifies the format of the compressed image data stored at address
2714 Specifies the width of the texture image including the border if any. If
2715 the GL version does not support non-power-of-two sizes, this value must
2716 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
2717 implementations support 2D texture images that are at least 64 texels
2718 wide and cube-mapped texture images that are at least 16 texels wide.
2721 Specifies the height of the texture image including the border if any.
2722 If the GL version does not support non-power-of-two sizes, this value
2723 must be Must be @r{2^@var{n}+2(@var{border},)} for some integer
2724 @r{@var{n}}. All implementations support 2D texture images that are at
2725 least 64 texels high and cube-mapped texture images that are at least 16
2729 Specifies the width of the border. Must be either 0 or 1.
2731 @item @var{imageSize}
2732 Specifies the number of unsigned bytes of image data starting at the
2733 address specified by @var{data}.
2736 Specifies a pointer to the compressed image data in memory.
2740 Texturing maps a portion of a specified texture image onto each
2741 graphical primitive for which texturing is enabled. To enable and
2742 disable two-dimensional texturing, call @code{glEnable} and
2743 @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and
2744 disable texturing using cube-mapped textures, call @code{glEnable} and
2745 @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}.
2747 @code{glCompressedTexImage2D} loads a previously defined, and retrieved,
2748 compressed two-dimensional texture image if @var{target} is
2749 @code{GL_TEXTURE_2D} (see @code{glTexImage2D}).
2751 If @var{target} is @code{GL_PROXY_TEXTURE_2D}, no data is read from
2752 @var{data}, but all of the texture image state is recalculated, checked
2753 for consistency, and checked against the implementation's capabilities.
2754 If the implementation cannot handle a texture of the requested texture
2755 size, it sets all of the image state to 0, but does not generate an
2756 error (see @code{glGetError}). To query for an entire mipmap array, use
2757 an image array level greater than or equal to 1.
2759 @var{internalformat} must be an extension-specified compressed-texture
2760 format. When a texture is loaded with @code{glTexImage2D} using a
2761 generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}), the
2762 GL selects from one of its extensions supporting compressed textures. In
2763 order to load the compressed texture image using
2764 @code{glCompressedTexImage2D}, query the compressed texture image's size
2765 and format using @code{glGetTexLevelParameter}.
2767 If a non-zero named buffer object is bound to the
2768 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2769 texture image is specified, @var{data} is treated as a byte offset into
2770 the buffer object's data store.
2772 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of
2773 the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
2774 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
2775 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or
2776 @code{GL_COMPRESSED_RGBA}.
2778 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
2779 consistent with the format, dimensions, and contents of the specified
2780 compressed image data.
2782 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
2783 not supported by the specific compressed internal format as specified in
2784 the specific texture compression extension.
2786 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2787 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2788 object's data store is currently mapped.
2790 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2791 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2792 would be unpacked from the buffer object such that the memory reads
2793 required would exceed the data store size.
2795 @code{GL_INVALID_OPERATION} is generated if
2796 @code{glCompressedTexImage2D} is executed between the execution of
2797 @code{glBegin} and the corresponding execution of @code{glEnd}.
2799 Undefined results, including abnormal program termination, are generated
2800 if @var{data} is not encoded in a manner consistent with the extension
2801 specification defining the internal compression format.
2805 @deftypefun void glCompressedTexImage3D target level internalformat width height depth border imageSize data
2806 Specify a three-dimensional texture image in a compressed format.
2810 Specifies the target texture. Must be @code{GL_TEXTURE_3D} or
2811 @code{GL_PROXY_TEXTURE_3D}.
2814 Specifies the level-of-detail number. Level 0 is the base image level.
2815 Level @var{n} is the @var{n}th mipmap reduction image.
2817 @item @var{internalformat}
2818 Specifies the format of the compressed image data stored at address
2822 Specifies the width of the texture image including the border if any. If
2823 the GL version does not support non-power-of-two sizes, this value must
2824 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
2825 implementations support 3D texture images that are at least 16 texels
2829 Specifies the height of the texture image including the border if any.
2830 If the GL version does not support non-power-of-two sizes, this value
2831 must be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}.
2832 All implementations support 3D texture images that are at least 16
2836 Specifies the depth of the texture image including the border if any. If
2837 the GL version does not support non-power-of-two sizes, this value must
2838 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
2839 implementations support 3D texture images that are at least 16 texels
2843 Specifies the width of the border. Must be either 0 or 1.
2845 @item @var{imageSize}
2846 Specifies the number of unsigned bytes of image data starting at the
2847 address specified by @var{data}.
2850 Specifies a pointer to the compressed image data in memory.
2854 Texturing maps a portion of a specified texture image onto each
2855 graphical primitive for which texturing is enabled. To enable and
2856 disable three-dimensional texturing, call @code{glEnable} and
2857 @code{glDisable} with argument @code{GL_TEXTURE_3D}.
2859 @code{glCompressedTexImage3D} loads a previously defined, and retrieved,
2860 compressed three-dimensional texture image if @var{target} is
2861 @code{GL_TEXTURE_3D} (see @code{glTexImage3D}).
2863 If @var{target} is @code{GL_PROXY_TEXTURE_3D}, no data is read from
2864 @var{data}, but all of the texture image state is recalculated, checked
2865 for consistency, and checked against the implementation's capabilities.
2866 If the implementation cannot handle a texture of the requested texture
2867 size, it sets all of the image state to 0, but does not generate an
2868 error (see @code{glGetError}). To query for an entire mipmap array, use
2869 an image array level greater than or equal to 1.
2871 @var{internalformat} must be an extension-specified compressed-texture
2872 format. When a texture is loaded with @code{glTexImage2D} using a
2873 generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}), the
2874 GL selects from one of its extensions supporting compressed textures. In
2875 order to load the compressed texture image using
2876 @code{glCompressedTexImage3D}, query the compressed texture image's size
2877 and format using @code{glGetTexLevelParameter}.
2879 If a non-zero named buffer object is bound to the
2880 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2881 texture image is specified, @var{data} is treated as a byte offset into
2882 the buffer object's data store.
2884 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of
2885 the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
2886 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
2887 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or
2888 @code{GL_COMPRESSED_RGBA}.
2890 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
2891 consistent with the format, dimensions, and contents of the specified
2892 compressed image data.
2894 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
2895 not supported by the specific compressed internal format as specified in
2896 the specific texture compression extension.
2898 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2899 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2900 object's data store is currently mapped.
2902 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2903 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2904 would be unpacked from the buffer object such that the memory reads
2905 required would exceed the data store size.
2907 @code{GL_INVALID_OPERATION} is generated if
2908 @code{glCompressedTexImage3D} is executed between the execution of
2909 @code{glBegin} and the corresponding execution of @code{glEnd}.
2911 Undefined results, including abnormal program termination, are generated
2912 if @var{data} is not encoded in a manner consistent with the extension
2913 specification defining the internal compression format.
2917 @deftypefun void glCompressedTexSubImage1D target level xoffset width format imageSize data
2918 Specify a one-dimensional texture subimage in a compressed format.
2922 Specifies the target texture. Must be @code{GL_TEXTURE_1D}.
2925 Specifies the level-of-detail number. Level 0 is the base image level.
2926 Level @var{n} is the @var{n}th mipmap reduction image.
2929 Specifies a texel offset in the x direction within the texture array.
2932 Specifies the width of the texture subimage.
2935 Specifies the format of the compressed image data stored at address
2938 @item @var{imageSize}
2939 Specifies the number of unsigned bytes of image data starting at the
2940 address specified by @var{data}.
2943 Specifies a pointer to the compressed image data in memory.
2947 Texturing maps a portion of a specified texture image onto each
2948 graphical primitive for which texturing is enabled. To enable and
2949 disable one-dimensional texturing, call @code{glEnable} and
2950 @code{glDisable} with argument @code{GL_TEXTURE_1D}.
2952 @code{glCompressedTexSubImage1D} redefines a contiguous subregion of an
2953 existing one-dimensional texture image. The texels referenced by
2954 @var{data} replace the portion of the existing texture array with x
2955 indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive.
2956 This region may not include any texels outside the range of the texture
2957 array as it was originally specified. It is not an error to specify a
2958 subtexture with width of 0, but such a specification has no effect.
2960 @var{format} must be an extension-specified compressed-texture format.
2961 The @var{format} of the compressed texture image is selected by the GL
2962 implementation that compressed it (see @code{glTexImage1D}), and should
2963 be queried at the time the texture was compressed with
2964 @code{glGetTexLevelParameter}.
2966 If a non-zero named buffer object is bound to the
2967 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2968 texture image is specified, @var{data} is treated as a byte offset into
2969 the buffer object's data store.
2971 @code{GL_INVALID_ENUM} is generated if @var{format} is one of these
2972 generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
2973 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
2974 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
2975 @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE},
2976 @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB},
2977 @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}.
2979 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
2980 consistent with the format, dimensions, and contents of the specified
2981 compressed image data.
2983 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
2984 not supported by the specific compressed internal format as specified in
2985 the specific texture compression extension.
2987 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2988 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2989 object's data store is currently mapped.
2991 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2992 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2993 would be unpacked from the buffer object such that the memory reads
2994 required would exceed the data store size.
2996 @code{GL_INVALID_OPERATION} is generated if
2997 @code{glCompressedTexSubImage1D} is executed between the execution of
2998 @code{glBegin} and the corresponding execution of @code{glEnd}.
3000 Undefined results, including abnormal program termination, are generated
3001 if @var{data} is not encoded in a manner consistent with the extension
3002 specification defining the internal compression format.
3006 @deftypefun void glCompressedTexSubImage2D target level xoffset yoffset width height format imageSize data
3007 Specify a two-dimensional texture subimage in a compressed format.
3011 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
3012 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
3013 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
3014 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
3015 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
3016 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
3017 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
3020 Specifies the level-of-detail number. Level 0 is the base image level.
3021 Level @var{n} is the @var{n}th mipmap reduction image.
3024 Specifies a texel offset in the x direction within the texture array.
3027 Specifies a texel offset in the y direction within the texture array.
3030 Specifies the width of the texture subimage.
3033 Specifies the height of the texture subimage.
3036 Specifies the format of the compressed image data stored at address
3039 @item @var{imageSize}
3040 Specifies the number of unsigned bytes of image data starting at the
3041 address specified by @var{data}.
3044 Specifies a pointer to the compressed image data in memory.
3048 Texturing maps a portion of a specified texture image onto each
3049 graphical primitive for which texturing is enabled. To enable and
3050 disable two-dimensional texturing, call @code{glEnable} and
3051 @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and
3052 disable texturing using cube-mapped texture, call @code{glEnable} and
3053 @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}.
3055 @code{glCompressedTexSubImage2D} redefines a contiguous subregion of an
3056 existing two-dimensional texture image. The texels referenced by
3057 @var{data} replace the portion of the existing texture array with x
3058 indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, and the y
3059 indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive.
3060 This region may not include any texels outside the range of the texture
3061 array as it was originally specified. It is not an error to specify a
3062 subtexture with width of 0, but such a specification has no effect.
3064 @var{format} must be an extension-specified compressed-texture format.
3065 The @var{format} of the compressed texture image is selected by the GL
3066 implementation that compressed it (see @code{glTexImage2D}) and should
3067 be queried at the time the texture was compressed with
3068 @code{glGetTexLevelParameter}.
3070 If a non-zero named buffer object is bound to the
3071 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
3072 texture image is specified, @var{data} is treated as a byte offset into
3073 the buffer object's data store.
3075 @code{GL_INVALID_ENUM} is generated if @var{format} is one of these
3076 generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
3077 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
3078 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
3079 @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE},
3080 @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB},
3081 @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}.
3083 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
3084 consistent with the format, dimensions, and contents of the specified
3085 compressed image data.
3087 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
3088 not supported by the specific compressed internal format as specified in
3089 the specific texture compression extension.
3091 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3092 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
3093 object's data store is currently mapped.
3095 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3096 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
3097 would be unpacked from the buffer object such that the memory reads
3098 required would exceed the data store size.
3100 @code{GL_INVALID_OPERATION} is generated if
3101 @code{glCompressedTexSubImage2D} is executed between the execution of
3102 @code{glBegin} and the corresponding execution of @code{glEnd}.
3104 Undefined results, including abnormal program termination, are generated
3105 if @var{data} is not encoded in a manner consistent with the extension
3106 specification defining the internal compression format.
3110 @deftypefun void glCompressedTexSubImage3D target level xoffset yoffset zoffset width height depth format imageSize data
3111 Specify a three-dimensional texture subimage in a compressed format.
3115 Specifies the target texture. Must be @code{GL_TEXTURE_3D}.
3118 Specifies the level-of-detail number. Level 0 is the base image level.
3119 Level @var{n} is the @var{n}th mipmap reduction image.
3122 Specifies a texel offset in the x direction within the texture array.
3125 Specifies a texel offset in the y direction within the texture array.
3128 Specifies the width of the texture subimage.
3131 Specifies the height of the texture subimage.
3134 Specifies the depth of the texture subimage.
3137 Specifies the format of the compressed image data stored at address
3140 @item @var{imageSize}
3141 Specifies the number of unsigned bytes of image data starting at the
3142 address specified by @var{data}.
3145 Specifies a pointer to the compressed image data in memory.
3149 Texturing maps a portion of a specified texture image onto each
3150 graphical primitive for which texturing is enabled. To enable and
3151 disable three-dimensional texturing, call @code{glEnable} and
3152 @code{glDisable} with argument @code{GL_TEXTURE_3D}.
3154 @code{glCompressedTexSubImage3D} redefines a contiguous subregion of an
3155 existing three-dimensional texture image. The texels referenced by
3156 @var{data} replace the portion of the existing texture array with x
3157 indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, and the y
3158 indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, and the z
3159 indices @var{zoffset} and @r{@var{zoffset}+@var{depth}-1}, inclusive.
3160 This region may not include any texels outside the range of the texture
3161 array as it was originally specified. It is not an error to specify a
3162 subtexture with width of 0, but such a specification has no effect.
3164 @var{format} must be an extension-specified compressed-texture format.
3165 The @var{format} of the compressed texture image is selected by the GL
3166 implementation that compressed it (see @code{glTexImage3D}) and should
3167 be queried at the time the texture was compressed with
3168 @code{glGetTexLevelParameter}.
3170 If a non-zero named buffer object is bound to the
3171 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
3172 texture image is specified, @var{data} is treated as a byte offset into
3173 the buffer object's data store.
3175 @code{GL_INVALID_ENUM} is generated if @var{format} is one of these
3176 generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
3177 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
3178 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
3179 @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE},
3180 @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB},
3181 @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}.
3183 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
3184 consistent with the format, dimensions, and contents of the specified
3185 compressed image data.
3187 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
3188 not supported by the specific compressed internal format as specified in
3189 the specific texture compression extension.
3191 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3192 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
3193 object's data store is currently mapped.
3195 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3196 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
3197 would be unpacked from the buffer object such that the memory reads
3198 required would exceed the data store size.
3200 @code{GL_INVALID_OPERATION} is generated if
3201 @code{glCompressedTexSubImage3D} is executed between the execution of
3202 @code{glBegin} and the corresponding execution of @code{glEnd}.
3204 Undefined results, including abnormal program termination, are generated
3205 if @var{data} is not encoded in a manner consistent with the extension
3206 specification defining the internal compression format.
3210 @deftypefun void glConvolutionFilter1D target internalformat width format type data
3211 Define a one-dimensional convolution filter.
3215 Must be @code{GL_CONVOLUTION_1D}.
3217 @item @var{internalformat}
3218 The internal format of the convolution filter kernel. The allowable
3219 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
3220 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
3221 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
3222 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3223 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3224 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3225 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3226 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3227 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3228 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3229 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3230 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3231 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3234 The width of the pixel array referenced by @var{data}.
3237 The format of the pixel data in @var{data}. The allowable values are
3238 @code{GL_ALPHA}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA},
3239 @code{GL_INTENSITY}, @code{GL_RGB}, and @code{GL_RGBA}.
3242 The type of the pixel data in @var{data}. Symbolic constants
3243 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
3244 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
3245 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
3246 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
3247 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
3248 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
3249 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
3250 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
3251 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
3254 Pointer to a one-dimensional array of pixel data that is processed to
3255 build the convolution filter kernel.
3259 @code{glConvolutionFilter1D} builds a one-dimensional convolution filter
3260 kernel from an array of pixels.
3262 The pixel array specified by @var{width}, @var{format}, @var{type}, and
3263 @var{data} is extracted from memory and processed just as if
3264 @code{glDrawPixels} were called, but processing stops after the final
3265 expansion to RGBA is completed.
3267 If a non-zero named buffer object is bound to the
3268 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
3269 convolution filter is specified, @var{data} is treated as a byte offset
3270 into the buffer object's data store.
3272 The R, G, B, and A components of each pixel are next scaled by the four
3273 1D @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four
3274 1D @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
3275 parameters are set by @code{glConvolutionParameter} using the
3276 @code{GL_CONVOLUTION_1D} target and the names
3277 @code{GL_CONVOLUTION_FILTER_SCALE} and
3278 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors
3279 of four values that are applied to red, green, blue, and alpha, in that
3280 order.) The R, G, B, and A values are not clamped to [0,1] at any time
3281 during this process.
3283 Each pixel is then converted to the internal format specified by
3284 @var{internalformat}. This conversion simply maps the component values
3285 of the pixel (R, G, B, and A) to the values included in the internal
3286 format (red, green, blue, alpha, luminance, and intensity). The mapping
3292 @item @strong{Internal Format}
3293 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
3294 @strong{Luminance}, @strong{Intensity}
3296 @item @code{GL_ALPHA}
3299 @item @code{GL_LUMINANCE}
3302 @item @code{GL_LUMINANCE_ALPHA}
3305 @item @code{GL_INTENSITY}
3311 @item @code{GL_RGBA}
3316 The red, green, blue, alpha, luminance, and/or intensity components of
3317 the resulting pixels are stored in floating-point rather than integer
3318 format. They form a one-dimensional filter kernel image indexed with
3319 coordinate @var{i} such that @var{i} starts at 0 and increases from left
3320 to right. Kernel location @var{i} is derived from the @var{i}th pixel,
3323 Note that after a convolution is performed, the resulting color
3324 components are also scaled by their corresponding
3325 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
3326 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
3327 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
3328 and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}.
3330 @code{GL_INVALID_ENUM} is generated if @var{target} is not
3331 @code{GL_CONVOLUTION_1D}.
3333 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
3334 of the allowable values.
3336 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
3339 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
3342 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
3343 greater than the maximum supported value. This value may be queried with
3344 @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_1D}
3345 and name @code{GL_MAX_CONVOLUTION_WIDTH}.
3347 @code{GL_INVALID_OPERATION} is generated if @var{format} is one of
3348 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
3349 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
3350 and @var{type} is not @code{GL_RGB}.
3352 @code{GL_INVALID_OPERATION} is generated if @var{format} is one of
3353 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
3354 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
3355 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
3356 @code{GL_UNSIGNED_INT_10_10_10_2}, or
3357 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{type} is neither
3358 @code{GL_RGBA} nor @code{GL_BGRA}.
3360 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3361 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
3362 object's data store is currently mapped.
3364 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3365 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
3366 would be unpacked from the buffer object such that the memory reads
3367 required would exceed the data store size.
3369 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3370 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
3371 is not evenly divisible into the number of bytes needed to store in
3372 memory a datum indicated by @var{type}.
3374 @code{GL_INVALID_OPERATION} is generated if @code{glConvolutionFilter1D}
3375 is executed between the execution of @code{glBegin} and the
3376 corresponding execution of @code{glEnd}.
3380 @deftypefun void glConvolutionFilter2D target internalformat width height format type data
3381 Define a two-dimensional convolution filter.
3385 Must be @code{GL_CONVOLUTION_2D}.
3387 @item @var{internalformat}
3388 The internal format of the convolution filter kernel. The allowable
3389 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
3390 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
3391 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
3392 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3393 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3394 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3395 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3396 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3397 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3398 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3399 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3400 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3401 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3404 The width of the pixel array referenced by @var{data}.
3407 The height of the pixel array referenced by @var{data}.
3410 The format of the pixel data in @var{data}. The allowable values are
3411 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
3412 @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA},
3413 @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA}.
3416 The type of the pixel data in @var{data}. Symbolic constants
3417 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
3418 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
3419 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
3420 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
3421 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
3422 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
3423 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
3424 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
3425 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
3428 Pointer to a two-dimensional array of pixel data that is processed to
3429 build the convolution filter kernel.
3433 @code{glConvolutionFilter2D} builds a two-dimensional convolution filter
3434 kernel from an array of pixels.
3436 The pixel array specified by @var{width}, @var{height}, @var{format},
3437 @var{type}, and @var{data} is extracted from memory and processed just
3438 as if @code{glDrawPixels} were called, but processing stops after the
3439 final expansion to RGBA is completed.
3441 If a non-zero named buffer object is bound to the
3442 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
3443 convolution filter is specified, @var{data} is treated as a byte offset
3444 into the buffer object's data store.
3446 The R, G, B, and A components of each pixel are next scaled by the four
3447 2D @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four
3448 2D @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
3449 parameters are set by @code{glConvolutionParameter} using the
3450 @code{GL_CONVOLUTION_2D} target and the names
3451 @code{GL_CONVOLUTION_FILTER_SCALE} and
3452 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors
3453 of four values that are applied to red, green, blue, and alpha, in that
3454 order.) The R, G, B, and A values are not clamped to [0,1] at any time
3455 during this process.
3457 Each pixel is then converted to the internal format specified by
3458 @var{internalformat}. This conversion simply maps the component values
3459 of the pixel (R, G, B, and A) to the values included in the internal
3460 format (red, green, blue, alpha, luminance, and intensity). The mapping
3466 @item @strong{Internal Format}
3467 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
3468 @strong{Luminance}, @strong{Intensity}
3470 @item @code{GL_ALPHA}
3473 @item @code{GL_LUMINANCE}
3476 @item @code{GL_LUMINANCE_ALPHA}
3479 @item @code{GL_INTENSITY}
3485 @item @code{GL_RGBA}
3490 The red, green, blue, alpha, luminance, and/or intensity components of
3491 the resulting pixels are stored in floating-point rather than integer
3492 format. They form a two-dimensional filter kernel image indexed with
3493 coordinates @var{i} and @var{j} such that @var{i} starts at zero and
3494 increases from left to right, and @var{j} starts at zero and increases
3495 from bottom to top. Kernel location @var{i,j} is derived from the
3496 @var{N}th pixel, where @var{N} is @var{i}+@var{j}*@var{width}.
3498 Note that after a convolution is performed, the resulting color
3499 components are also scaled by their corresponding
3500 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
3501 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
3502 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
3503 and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}.
3505 @code{GL_INVALID_ENUM} is generated if @var{target} is not
3506 @code{GL_CONVOLUTION_2D}.
3508 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
3509 of the allowable values.
3511 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
3514 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
3517 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
3518 greater than the maximum supported value. This value may be queried with
3519 @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_2D}
3520 and name @code{GL_MAX_CONVOLUTION_WIDTH}.
3522 @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero
3523 or greater than the maximum supported value. This value may be queried
3524 with @code{glGetConvolutionParameter} using target
3525 @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}.
3527 @code{GL_INVALID_OPERATION} is generated if @var{height} is one of
3528 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
3529 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
3530 and @var{format} is not @code{GL_RGB}.
3532 @code{GL_INVALID_OPERATION} is generated if @var{height} is one of
3533 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
3534 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
3535 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
3536 @code{GL_UNSIGNED_INT_10_10_10_2}, or
3537 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
3538 @code{GL_RGBA} nor @code{GL_BGRA}.
3540 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3541 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
3542 object's data store is currently mapped.
3544 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3545 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
3546 would be unpacked from the buffer object such that the memory reads
3547 required would exceed the data store size.
3549 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3550 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
3551 is not evenly divisible into the number of bytes needed to store in
3552 memory a datum indicated by @var{type}.
3554 @code{GL_INVALID_OPERATION} is generated if @code{glConvolutionFilter2D}
3555 is executed between the execution of @code{glBegin} and the
3556 corresponding execution of @code{glEnd}.
3560 @deftypefun void glConvolutionParameterf target pname params
3561 @deftypefunx void glConvolutionParameteri target pname params
3562 @deftypefunx void glConvolutionParameterfv target pname params
3563 @deftypefunx void glConvolutionParameteriv target pname params
3564 Set convolution parameters.
3568 The target for the convolution parameter. Must be one of
3569 @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or
3570 @code{GL_SEPARABLE_2D}.
3573 The parameter to be set. Must be @code{GL_CONVOLUTION_BORDER_MODE}.
3576 The parameter value. Must be one of @code{GL_REDUCE},
3577 @code{GL_CONSTANT_BORDER}, @code{GL_REPLICATE_BORDER}.
3583 @code{glConvolutionParameter} sets the value of a convolution parameter.
3585 @var{target} selects the convolution filter to be affected:
3586 @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or
3587 @code{GL_SEPARABLE_2D} for the 1D, 2D, or separable 2D filter,
3590 @var{pname} selects the parameter to be changed.
3591 @code{GL_CONVOLUTION_FILTER_SCALE} and @code{GL_CONVOLUTION_FILTER_BIAS}
3592 affect the definition of the convolution filter kernel; see
3593 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and
3594 @code{glSeparableFilter2D} for details. In these cases, @var{params}v is
3595 an array of four values to be applied to red, green, blue, and alpha
3596 values, respectively. The initial value for
3597 @code{GL_CONVOLUTION_FILTER_SCALE} is (1, 1, 1, 1), and the initial
3598 value for @code{GL_CONVOLUTION_FILTER_BIAS} is (0, 0, 0, 0).
3600 A @var{pname} value of @code{GL_CONVOLUTION_BORDER_MODE} controls the
3601 convolution border mode. The accepted modes are:
3604 @item @code{GL_REDUCE}
3605 The image resulting from convolution is smaller than the source image.
3606 If the filter width is @r{@var{Wf}} and height is @r{@var{Hf}}, and the
3607 source image width is @r{@var{Ws}} and height is @r{@var{Hs}}, then the
3608 convolved image width will be @r{@var{Ws}-@var{Wf}+1} and height will be
3609 @r{@var{Hs}-@var{Hf}+1}. (If this reduction would generate an image with
3610 zero or negative width and/or height, the output is simply null, with no
3611 error generated.) The coordinates of the image resulting from
3612 convolution are zero through @r{@var{Ws}-@var{Wf}} in width and zero
3613 through @r{@var{Hs}-@var{Hf}} in height.
3615 @item @code{GL_CONSTANT_BORDER}
3616 The image resulting from convolution is the same size as the source
3617 image, and processed as if the source image were surrounded by pixels
3618 with their color specified by the @code{GL_CONVOLUTION_BORDER_COLOR}.
3620 @item @code{GL_REPLICATE_BORDER}
3621 The image resulting from convolution is the same size as the source
3622 image, and processed as if the outermost pixel on the border of the
3623 source image were replicated.
3627 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
3630 @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the
3633 @code{GL_INVALID_ENUM} is generated if @var{pname} is
3634 @code{GL_CONVOLUTION_BORDER_MODE} and @var{params} is not one of
3635 @code{GL_REDUCE}, @code{GL_CONSTANT_BORDER}, or
3636 @code{GL_REPLICATE_BORDER}.
3638 @code{GL_INVALID_OPERATION} is generated if
3639 @code{glConvolutionParameter} is executed between the execution of
3640 @code{glBegin} and the corresponding execution of @code{glEnd}.
3644 @deftypefun void glCopyColorSubTable target start x y width
3645 Respecify a portion of a color table.
3649 Must be one of @code{GL_COLOR_TABLE},
3650 @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
3651 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}.
3654 The starting index of the portion of the color table to be replaced.
3658 The window coordinates of the left corner of the row of pixels to be
3662 The number of table entries to replace.
3666 @code{glCopyColorSubTable} is used to respecify a contiguous portion of
3667 a color table previously defined using @code{glColorTable}. The pixels
3668 copied from the framebuffer replace the portion of the existing table
3669 from indices @var{start} to @r{@var{start}+@var{x}-1}, inclusive. This
3670 region may not include any entries outside the range of the color table,
3671 as was originally specified. It is not an error to specify a subtexture
3672 with width of 0, but such a specification has no effect.
3674 @code{GL_INVALID_VALUE} is generated if @var{target} is not a previously
3675 defined color table.
3677 @code{GL_INVALID_VALUE} is generated if @var{target} is not one of the
3680 @code{GL_INVALID_VALUE} is generated if
3681 @r{@var{start}+@var{x}>@var{width}}.
3683 @code{GL_INVALID_OPERATION} is generated if @code{glCopyColorSubTable}
3684 is executed between the execution of @code{glBegin} and the
3685 corresponding execution of @code{glEnd}.
3689 @deftypefun void glCopyColorTable target internalformat x y width
3690 Copy pixels into a color table.
3694 The color table target. Must be @code{GL_COLOR_TABLE},
3695 @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
3696 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}.
3698 @item @var{internalformat}
3699 The internal storage format of the texture image. Must be one of the
3700 following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4},
3701 @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16},
3702 @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8},
3703 @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3704 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3705 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3706 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3707 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3708 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3709 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3710 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3711 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3712 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3715 The x coordinate of the lower-left corner of the pixel rectangle to be
3716 transferred to the color table.
3719 The y coordinate of the lower-left corner of the pixel rectangle to be
3720 transferred to the color table.
3723 The width of the pixel rectangle.
3727 @code{glCopyColorTable} loads a color table with pixels from the current
3728 @code{GL_READ_BUFFER} (rather than from main memory, as is the case for
3729 @code{glColorTable}).
3731 The screen-aligned pixel rectangle with lower-left corner at (@var{x},\
3732 @var{y}) having width @var{width} and height 1 is loaded into the color
3733 table. If any pixels within this region are outside the window that is
3734 associated with the GL context, the values obtained for those pixels are
3737 The pixels in the rectangle are processed just as if @code{glReadPixels}
3738 were called, with @var{internalformat} set to RGBA, but processing stops
3739 after the final conversion to RGBA.
3741 The four scale parameters and the four bias parameters that are defined
3742 for the table are then used to scale and bias the R, G, B, and A
3743 components of each pixel. The scale and bias parameters are set by
3744 calling @code{glColorTableParameter}.
3746 Next, the R, G, B, and A values are clamped to the range @r{[0,1]}. Each
3747 pixel is then converted to the internal format specified by
3748 @var{internalformat}. This conversion simply maps the component values
3749 of the pixel (R, G, B, and A) to the values included in the internal
3750 format (red, green, blue, alpha, luminance, and intensity). The mapping
3756 @item @strong{Internal Format}
3757 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
3758 @strong{Luminance}, @strong{Intensity}
3760 @item @code{GL_ALPHA}
3763 @item @code{GL_LUMINANCE}
3766 @item @code{GL_LUMINANCE_ALPHA}
3769 @item @code{GL_INTENSITY}
3775 @item @code{GL_RGBA}
3780 Finally, the red, green, blue, alpha, luminance, and/or intensity
3781 components of the resulting pixels are stored in the color table. They
3782 form a one-dimensional table with indices in the range
3783 @r{[0,@var{width}-1]}.
3787 @code{GL_INVALID_ENUM} is generated when @var{target} is not one of the
3790 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero.
3792 @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not one
3793 of the allowable values.
3795 @code{GL_TABLE_TOO_LARGE} is generated if the requested color table is
3796 too large to be supported by the implementation.
3798 @code{GL_INVALID_OPERATION} is generated if @code{glCopyColorTable} is
3799 executed between the execution of @code{glBegin} and the corresponding
3800 execution of @code{glEnd}.
3804 @deftypefun void glCopyConvolutionFilter1D target internalformat x y width
3805 Copy pixels into a one-dimensional convolution filter.
3809 Must be @code{GL_CONVOLUTION_1D}.
3811 @item @var{internalformat}
3812 The internal format of the convolution filter kernel. The allowable
3813 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
3814 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
3815 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
3816 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3817 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3818 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3819 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3820 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3821 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3822 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3823 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3824 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3825 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3829 The window space coordinates of the lower-left coordinate of the pixel
3833 The width of the pixel array to copy.
3837 @code{glCopyConvolutionFilter1D} defines a one-dimensional convolution
3838 filter kernel with pixels from the current @code{GL_READ_BUFFER} (rather
3839 than from main memory, as is the case for @code{glConvolutionFilter1D}).
3841 The screen-aligned pixel rectangle with lower-left corner at (@var{x},\
3842 @var{y}), width @var{width} and height 1 is used to define the
3843 convolution filter. If any pixels within this region are outside the
3844 window that is associated with the GL context, the values obtained for
3845 those pixels are undefined.
3847 The pixels in the rectangle are processed exactly as if
3848 @code{glReadPixels} had been called with @var{format} set to RGBA, but
3849 the process stops just before final conversion. The R, G, B, and A
3850 components of each pixel are next scaled by the four 1D
3851 @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four 1D
3852 @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
3853 parameters are set by @code{glConvolutionParameter} using the
3854 @code{GL_CONVOLUTION_1D} target and the names
3855 @code{GL_CONVOLUTION_FILTER_SCALE} and
3856 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors
3857 of four values that are applied to red, green, blue, and alpha, in that
3858 order.) The R, G, B, and A values are not clamped to [0,1] at any time
3859 during this process.
3861 Each pixel is then converted to the internal format specified by
3862 @var{internalformat}. This conversion simply maps the component values
3863 of the pixel (R, G, B, and A) to the values included in the internal
3864 format (red, green, blue, alpha, luminance, and intensity). The mapping
3870 @item @strong{Internal Format}
3871 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
3872 @strong{Luminance}, @strong{Intensity}
3874 @item @code{GL_ALPHA}
3877 @item @code{GL_LUMINANCE}
3880 @item @code{GL_LUMINANCE_ALPHA}
3883 @item @code{GL_INTENSITY}
3889 @item @code{GL_RGBA}
3894 The red, green, blue, alpha, luminance, and/or intensity components of
3895 the resulting pixels are stored in floating-point rather than integer
3898 Pixel ordering is such that lower x screen coordinates correspond to
3899 lower @var{i} filter image coordinates.
3901 Note that after a convolution is performed, the resulting color
3902 components are also scaled by their corresponding
3903 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
3904 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
3905 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
3906 and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}.
3908 @code{GL_INVALID_ENUM} is generated if @var{target} is not
3909 @code{GL_CONVOLUTION_1D}.
3911 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
3912 of the allowable values.
3914 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
3915 greater than the maximum supported value. This value may be queried with
3916 @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_1D}
3917 and name @code{GL_MAX_CONVOLUTION_WIDTH}.
3919 @code{GL_INVALID_OPERATION} is generated if
3920 @code{glCopyConvolutionFilter1D} is executed between the execution of
3921 @code{glBegin} and the corresponding execution of @code{glEnd}.
3925 @deftypefun void glCopyConvolutionFilter2D target internalformat x y width height
3926 Copy pixels into a two-dimensional convolution filter.
3930 Must be @code{GL_CONVOLUTION_2D}.
3932 @item @var{internalformat}
3933 The internal format of the convolution filter kernel. The allowable
3934 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
3935 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
3936 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
3937 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3938 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3939 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3940 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3941 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3942 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3943 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3944 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3945 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3946 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3950 The window space coordinates of the lower-left coordinate of the pixel
3954 The width of the pixel array to copy.
3957 The height of the pixel array to copy.
3961 @code{glCopyConvolutionFilter2D} defines a two-dimensional convolution
3962 filter kernel with pixels from the current @code{GL_READ_BUFFER} (rather
3963 than from main memory, as is the case for @code{glConvolutionFilter2D}).
3965 The screen-aligned pixel rectangle with lower-left corner at (@var{x},\
3966 @var{y}), width @var{width} and height @var{height} is used to define
3967 the convolution filter. If any pixels within this region are outside the
3968 window that is associated with the GL context, the values obtained for
3969 those pixels are undefined.
3971 The pixels in the rectangle are processed exactly as if
3972 @code{glReadPixels} had been called with @var{format} set to RGBA, but
3973 the process stops just before final conversion. The R, G, B, and A
3974 components of each pixel are next scaled by the four 2D
3975 @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four 2D
3976 @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
3977 parameters are set by @code{glConvolutionParameter} using the
3978 @code{GL_CONVOLUTION_2D} target and the names
3979 @code{GL_CONVOLUTION_FILTER_SCALE} and
3980 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors
3981 of four values that are applied to red, green, blue, and alpha, in that
3982 order.) The R, G, B, and A values are not clamped to [0,1] at any time
3983 during this process.
3985 Each pixel is then converted to the internal format specified by
3986 @var{internalformat}. This conversion simply maps the component values
3987 of the pixel (R, G, B, and A) to the values included in the internal
3988 format (red, green, blue, alpha, luminance, and intensity). The mapping
3994 @item @strong{Internal Format}
3995 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
3996 @strong{Luminance}, @strong{Intensity}
3998 @item @code{GL_ALPHA}
4001 @item @code{GL_LUMINANCE}
4004 @item @code{GL_LUMINANCE_ALPHA}
4007 @item @code{GL_INTENSITY}
4013 @item @code{GL_RGBA}
4018 The red, green, blue, alpha, luminance, and/or intensity components of
4019 the resulting pixels are stored in floating-point rather than integer
4022 Pixel ordering is such that lower x screen coordinates correspond to
4023 lower @var{i} filter image coordinates, and lower y screen coordinates
4024 correspond to lower @var{j} filter image coordinates.
4026 Note that after a convolution is performed, the resulting color
4027 components are also scaled by their corresponding
4028 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
4029 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
4030 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
4031 and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}.
4033 @code{GL_INVALID_ENUM} is generated if @var{target} is not
4034 @code{GL_CONVOLUTION_2D}.
4036 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
4037 of the allowable values.
4039 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
4040 greater than the maximum supported value. This value may be queried with
4041 @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_2D}
4042 and name @code{GL_MAX_CONVOLUTION_WIDTH}.
4044 @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero
4045 or greater than the maximum supported value. This value may be queried
4046 with @code{glGetConvolutionParameter} using target
4047 @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}.
4049 @code{GL_INVALID_OPERATION} is generated if
4050 @code{glCopyConvolutionFilter2D} is executed between the execution of
4051 @code{glBegin} and the corresponding execution of @code{glEnd}.
4055 @deftypefun void glCopyPixels x y width height type
4056 Copy pixels in the frame buffer.
4061 Specify the window coordinates of the lower left corner of the
4062 rectangular region of pixels to be copied.
4066 Specify the dimensions of the rectangular region of pixels to be copied.
4067 Both must be nonnegative.
4070 Specifies whether color values, depth values, or stencil values are to
4071 be copied. Symbolic constants @code{GL_COLOR}, @code{GL_DEPTH}, and
4072 @code{GL_STENCIL} are accepted.
4076 @code{glCopyPixels} copies a screen-aligned rectangle of pixels from the
4077 specified frame buffer location to a region relative to the current
4078 raster position. Its operation is well defined only if the entire pixel
4079 source region is within the exposed portion of the window. Results of
4080 copies from outside the window, or from regions of the window that are
4081 not exposed, are hardware dependent and undefined.
4083 @var{x} and @var{y} specify the window coordinates of the lower left
4084 corner of the rectangular region to be copied. @var{width} and
4085 @var{height} specify the dimensions of the rectangular region to be
4086 copied. Both @var{width} and @var{height} must not be negative.
4088 Several parameters control the processing of the pixel data while it is
4089 being copied. These parameters are set with three commands:
4090 @code{glPixelTransfer}, @code{glPixelMap}, and @code{glPixelZoom}. This
4091 reference page describes the effects on @code{glCopyPixels} of most, but
4092 not all, of the parameters specified by these three commands.
4094 @code{glCopyPixels} copies values from each pixel with the lower
4095 left-hand corner at @r{(@var{x}+@var{i},@var{y}+@var{j})} for
4096 @r{0<=@var{i}<@var{width}} and @r{0<=@var{j}<@var{height}}. This pixel
4097 is said to be the @r{@var{i}}th pixel in the @r{@var{j}}th row. Pixels
4098 are copied in row order from the lowest to the highest row, left to
4101 @var{type} specifies whether color, depth, or stencil data is to be
4102 copied. The details of the transfer for each data type are as follows:
4105 @item @code{GL_COLOR}
4106 Indices or RGBA colors are read from the buffer currently specified as
4107 the read source buffer (see @code{glReadBuffer}). If the GL is in color
4108 index mode, each index that is read from this buffer is converted to a
4109 fixed-point format with an unspecified number of bits to the right of
4110 the binary point. Each index is then shifted left by
4111 @code{GL_INDEX_SHIFT} bits, and added to @code{GL_INDEX_OFFSET}. If
4112 @code{GL_INDEX_SHIFT} is negative, the shift is to the right. In either
4113 case, zero bits fill otherwise unspecified bit locations in the result.
4114 If @code{GL_MAP_COLOR} is true, the index is replaced with the value
4115 that it references in lookup table @code{GL_PIXEL_MAP_I_TO_I}. Whether
4116 the lookup replacement of the index is done or not, the integer part of
4117 the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the
4118 number of bits in a color index buffer.
4120 If the GL is in RGBA mode, the red, green, blue, and alpha components of
4121 each pixel that is read are converted to an internal floating-point
4122 format with unspecified precision. The conversion maps the largest
4123 representable component value to 1.0, and component value 0 to 0.0. The
4124 resulting floating-point color values are then multiplied by
4125 @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is RED,
4126 GREEN, BLUE, and ALPHA for the respective color components. The results
4127 are clamped to the range [0,1]. If @code{GL_MAP_COLOR} is true, each
4128 color component is scaled by the size of lookup table
4129 @code{GL_PIXEL_MAP_c_TO_c}, then replaced by the value that it
4130 references in that table. @var{c} is R, G, B, or A.
4132 If the @code{ARB_imaging} extension is supported, the color values may
4133 be additionally processed by color-table lookups, color-matrix
4134 transformations, and convolution filters.
4136 The GL then converts the resulting indices or RGBA colors to fragments
4137 by attaching the current raster position @var{z} coordinate and texture
4138 coordinates to each pixel, then assigning window coordinates
4139 @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where
4140 @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position,
4141 and the pixel was the @r{@var{i}}th pixel in the @r{@var{j}}th row.
4142 These pixel fragments are then treated just like the fragments generated
4143 by rasterizing points, lines, or polygons. Texture mapping, fog, and all
4144 the fragment operations are applied before the fragments are written to
4147 @item @code{GL_DEPTH}
4148 Depth values are read from the depth buffer and converted directly to an
4149 internal floating-point format with unspecified precision. The resulting
4150 floating-point depth value is then multiplied by @code{GL_DEPTH_SCALE}
4151 and added to @code{GL_DEPTH_BIAS}. The result is clamped to the range
4154 The GL then converts the resulting depth components to fragments by
4155 attaching the current raster position color or color index and texture
4156 coordinates to each pixel, then assigning window coordinates
4157 @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where
4158 @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position,
4159 and the pixel was the @r{@var{i}}th pixel in the @r{@var{j}}th row.
4160 These pixel fragments are then treated just like the fragments generated
4161 by rasterizing points, lines, or polygons. Texture mapping, fog, and all
4162 the fragment operations are applied before the fragments are written to
4165 @item @code{GL_STENCIL}
4166 Stencil indices are read from the stencil buffer and converted to an
4167 internal fixed-point format with an unspecified number of bits to the
4168 right of the binary point. Each fixed-point index is then shifted left
4169 by @code{GL_INDEX_SHIFT} bits, and added to @code{GL_INDEX_OFFSET}. If
4170 @code{GL_INDEX_SHIFT} is negative, the shift is to the right. In either
4171 case, zero bits fill otherwise unspecified bit locations in the result.
4172 If @code{GL_MAP_STENCIL} is true, the index is replaced with the value
4173 that it references in lookup table @code{GL_PIXEL_MAP_S_TO_S}. Whether
4174 the lookup replacement of the index is done or not, the integer part of
4175 the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the
4176 number of bits in the stencil buffer. The resulting stencil indices are
4177 then written to the stencil buffer such that the index read from the
4178 @r{@var{i}}th location of the @r{@var{j}}th row is written to location
4179 @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where
4180 @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position.
4181 Only the pixel ownership test, the scissor test, and the stencil
4182 writemask affect these write operations.
4186 The rasterization described thus far assumes pixel zoom factors of 1.0.
4187 If @code{glPixelZoom} is used to change the @r{@var{x}} and @r{@var{y}}
4188 pixel zoom factors, pixels are converted to fragments as follows. If
4189 @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position,
4190 and a given pixel is in the @r{@var{i}}th location in the @r{@var{j}}th
4191 row of the source pixel rectangle, then fragments are generated for
4192 pixels whose centers are in the rectangle with corners at
4194 @r{(@var{x}_@var{r}+@var{zoom}_@var{x},@var{i},@var{y}_@var{r}+@var{zoom}_@var{y},@var{j})}
4198 @r{(@var{x}_@var{r}+@var{zoom}_@var{x},(@var{i}+1,),@var{y}_@var{r}+@var{zoom}_@var{y},(@var{j}+1,))}
4200 where @r{@var{zoom}_@var{x}} is the value of @code{GL_ZOOM_X} and
4201 @r{@var{zoom}_@var{y}} is the value of @code{GL_ZOOM_Y}.
4203 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
4206 @code{GL_INVALID_VALUE} is generated if either @var{width} or
4207 @var{height} is negative.
4209 @code{GL_INVALID_OPERATION} is generated if @var{type} is
4210 @code{GL_DEPTH} and there is no depth buffer.
4212 @code{GL_INVALID_OPERATION} is generated if @var{type} is
4213 @code{GL_STENCIL} and there is no stencil buffer.
4215 @code{GL_INVALID_OPERATION} is generated if @code{glCopyPixels} is
4216 executed between the execution of @code{glBegin} and the corresponding
4217 execution of @code{glEnd}.
4221 @deftypefun void glCopyTexImage1D target level internalformat x y width border
4222 Copy pixels into a 1D texture image.
4226 Specifies the target texture. Must be @code{GL_TEXTURE_1D}.
4229 Specifies the level-of-detail number. Level 0 is the base image level.
4230 Level @var{n} is the @var{n}th mipmap reduction image.
4232 @item @var{internalformat}
4233 Specifies the internal format of the texture. Must be one of the
4234 following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4},
4235 @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16},
4236 @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_LUMINANCE},
4237 @code{GL_COMPRESSED_LUMINANCE_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
4238 @code{GL_COMPRESSED_RGB}, @code{GL_COMPRESSED_RGBA},
4239 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
4240 @code{GL_DEPTH_COMPONENT24}, @code{GL_DEPTH_COMPONENT32},
4241 @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8},
4242 @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
4243 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
4244 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
4245 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
4246 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
4247 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_RGB},
4248 @code{GL_R3_G3_B2}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
4249 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
4250 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
4251 @code{GL_RGB10_A2}, @code{GL_RGBA12}, @code{GL_RGBA16},
4252 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
4253 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
4254 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
4258 Specify the window coordinates of the left corner of the row of pixels
4262 Specifies the width of the texture image. Must be 0 or
4263 @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. The height
4264 of the texture image is 1.
4267 Specifies the width of the border. Must be either 0 or 1.
4271 @code{glCopyTexImage1D} defines a one-dimensional texture image with
4272 pixels from the current @code{GL_READ_BUFFER}.
4274 The screen-aligned pixel row with left corner at @r{(@var{x},@var{y})}
4275 and with a length of @r{@var{width}+2(@var{border},)} defines the
4276 texture array at the mipmap level specified by @var{level}.
4277 @var{internalformat} specifies the internal format of the texture array.
4279 The pixels in the row are processed exactly as if @code{glCopyPixels}
4280 had been called, but the process stops just before final conversion. At
4281 this point all pixel component values are clamped to the range @r{[0,1]}
4282 and then converted to the texture's internal format for storage in the
4285 Pixel ordering is such that lower @r{@var{x}} screen coordinates
4286 correspond to lower texture coordinates.
4288 If any of the pixels within the specified row of the current
4289 @code{GL_READ_BUFFER} are outside the window associated with the current
4290 rendering context, then the values obtained for those pixels are
4293 @code{glCopyTexImage1D} defines a one-dimensional texture image with
4294 pixels from the current @code{GL_READ_BUFFER}.
4296 When @var{internalformat} is one of the sRGB types, the GL does not
4297 automatically convert the source pixels to the sRGB color space. In this
4298 case, the @code{glPixelMap} function can be used to accomplish the
4301 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
4304 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4306 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
4307 @r{@var{log}_2@var{max}}, where @r{@var{max}} is the returned value of
4308 @code{GL_MAX_TEXTURE_SIZE}.
4310 @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not an
4313 @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or
4314 greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
4316 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
4317 not supported and the @var{width} cannot be represented as
4318 @r{2^@var{n}+2(@var{border},)} for some integer value of @var{n}.
4320 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
4322 @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexImage1D} is
4323 executed between the execution of @code{glBegin} and the corresponding
4324 execution of @code{glEnd}.
4326 @code{GL_INVALID_OPERATION} is generated if @var{internalformat} is
4327 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
4328 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32} and there is
4333 @deftypefun void glCopyTexImage2D target level internalformat x y width height border
4334 Copy pixels into a 2D texture image.
4338 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
4339 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
4340 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
4341 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
4342 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
4343 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
4344 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
4347 Specifies the level-of-detail number. Level 0 is the base image level.
4348 Level @var{n} is the @var{n}th mipmap reduction image.
4350 @item @var{internalformat}
4351 Specifies the internal format of the texture. Must be one of the
4352 following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4},
4353 @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16},
4354 @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_LUMINANCE},
4355 @code{GL_COMPRESSED_LUMINANCE_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
4356 @code{GL_COMPRESSED_RGB}, @code{GL_COMPRESSED_RGBA},
4357 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
4358 @code{GL_DEPTH_COMPONENT24}, @code{GL_DEPTH_COMPONENT32},
4359 @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8},
4360 @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
4361 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
4362 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
4363 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
4364 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
4365 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_RGB},
4366 @code{GL_R3_G3_B2}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
4367 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
4368 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
4369 @code{GL_RGB10_A2}, @code{GL_RGBA12}, @code{GL_RGBA16},
4370 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
4371 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
4372 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
4376 Specify the window coordinates of the lower left corner of the
4377 rectangular region of pixels to be copied.
4380 Specifies the width of the texture image. Must be 0 or
4381 @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}.
4384 Specifies the height of the texture image. Must be 0 or
4385 @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}.
4388 Specifies the width of the border. Must be either 0 or 1.
4392 @code{glCopyTexImage2D} defines a two-dimensional texture image, or
4393 cube-map texture image with pixels from the current
4394 @code{GL_READ_BUFFER}.
4396 The screen-aligned pixel rectangle with lower left corner at (@var{x},
4397 @var{y}) and with a width of @r{@var{width}+2(@var{border},)} and a
4398 height of @r{@var{height}+2(@var{border},)} defines the texture array
4399 at the mipmap level specified by @var{level}. @var{internalformat}
4400 specifies the internal format of the texture array.
4402 The pixels in the rectangle are processed exactly as if
4403 @code{glCopyPixels} had been called, but the process stops just before
4404 final conversion. At this point all pixel component values are clamped
4405 to the range @r{[0,1]} and then converted to the texture's internal
4406 format for storage in the texel array.
4408 Pixel ordering is such that lower @r{@var{x}} and @r{@var{y}} screen
4409 coordinates correspond to lower @r{@var{s}} and @r{@var{t}} texture
4412 If any of the pixels within the specified rectangle of the current
4413 @code{GL_READ_BUFFER} are outside the window associated with the current
4414 rendering context, then the values obtained for those pixels are
4417 When @var{internalformat} is one of the sRGB types, the GL does not
4418 automatically convert the source pixels to the sRGB color space. In this
4419 case, the @code{glPixelMap} function can be used to accomplish the
4422 @code{GL_INVALID_ENUM} is generated if @var{target} is not
4423 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
4424 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
4425 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
4426 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
4427 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
4428 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
4430 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4432 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
4433 @r{@var{log}_2@var{max}}, where @r{@var{max}} is the returned value of
4434 @code{GL_MAX_TEXTURE_SIZE}.
4436 @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or
4437 greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
4439 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
4440 not supported and the @var{width} or @var{depth} cannot be represented
4441 as @r{2^@var{k}+2(@var{border},)} for some integer @r{@var{k}}.
4443 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
4445 @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not an
4448 @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexImage2D} is
4449 executed between the execution of @code{glBegin} and the corresponding
4450 execution of @code{glEnd}.
4452 @code{GL_INVALID_OPERATION} is generated if @var{internalformat} is
4453 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
4454 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32} and there is
4459 @deftypefun void glCopyTexSubImage1D target level xoffset x y width
4460 Copy a one-dimensional texture subimage.
4464 Specifies the target texture. Must be @code{GL_TEXTURE_1D}.
4467 Specifies the level-of-detail number. Level 0 is the base image level.
4468 Level @var{n} is the @var{n}th mipmap reduction image.
4471 Specifies the texel offset within the texture array.
4475 Specify the window coordinates of the left corner of the row of pixels
4479 Specifies the width of the texture subimage.
4483 @code{glCopyTexSubImage1D} replaces a portion of a one-dimensional
4484 texture image with pixels from the current @code{GL_READ_BUFFER} (rather
4485 than from main memory, as is the case for @code{glTexSubImage1D}).
4487 The screen-aligned pixel row with left corner at (@var{x},\ @var{y}),
4488 and with length @var{width} replaces the portion of the texture array
4489 with x indices @var{xoffset} through @r{@var{xoffset}+@var{width}-1},
4490 inclusive. The destination in the texture array may not include any
4491 texels outside the texture array as it was originally specified.
4493 The pixels in the row are processed exactly as if @code{glCopyPixels}
4494 had been called, but the process stops just before final conversion. At
4495 this point, all pixel component values are clamped to the range
4496 @r{[0,1]} and then converted to the texture's internal format for
4497 storage in the texel array.
4499 It is not an error to specify a subtexture with zero width, but such a
4500 specification has no effect. If any of the pixels within the specified
4501 row of the current @code{GL_READ_BUFFER} are outside the read window
4502 associated with the current rendering context, then the values obtained
4503 for those pixels are undefined.
4505 No change is made to the @var{internalformat}, @var{width}, or
4506 @var{border} parameters of the specified texture array or to texel
4507 values outside the specified subregion.
4509 @code{GL_INVALID_ENUM} is generated if /@var{target} is not
4510 @code{GL_TEXTURE_1D}.
4512 @code{GL_INVALID_OPERATION} is generated if the texture array has not
4513 been defined by a previous @code{glTexImage1D} or
4514 @code{glCopyTexImage1D} operation.
4516 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4518 @code{GL_INVALID_VALUE} may be generated if
4519 @r{@var{level}>@var{log}_2(@var{max},)}, where @var{max} is the
4520 returned value of @code{GL_MAX_TEXTURE_SIZE}.
4522 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, or
4523 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, where @r{@var{w}}
4524 is the @code{GL_TEXTURE_WIDTH} and @r{@var{b}} is the
4525 @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that
4526 @r{@var{w}} includes twice the border width.
4532 @deftypefun void glCopyTexSubImage2D target level xoffset yoffset x y width height
4533 Copy a two-dimensional texture subimage.
4537 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
4538 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
4539 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
4540 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
4541 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
4542 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
4543 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
4546 Specifies the level-of-detail number. Level 0 is the base image level.
4547 Level @var{n} is the @var{n}th mipmap reduction image.
4550 Specifies a texel offset in the x direction within the texture array.
4553 Specifies a texel offset in the y direction within the texture array.
4557 Specify the window coordinates of the lower left corner of the
4558 rectangular region of pixels to be copied.
4561 Specifies the width of the texture subimage.
4564 Specifies the height of the texture subimage.
4568 @code{glCopyTexSubImage2D} replaces a rectangular portion of a
4569 two-dimensional texture image or cube-map texture image with pixels from
4570 the current @code{GL_READ_BUFFER} (rather than from main memory, as is
4571 the case for @code{glTexSubImage2D}).
4573 The screen-aligned pixel rectangle with lower left corner at
4574 @r{(@var{x},@var{y})} and with width @var{width} and height @var{height}
4575 replaces the portion of the texture array with x indices @var{xoffset}
4576 through @r{@var{xoffset}+@var{width}-1}, inclusive, and y indices
4577 @var{yoffset} through @r{@var{yoffset}+@var{height}-1}, inclusive, at
4578 the mipmap level specified by @var{level}.
4580 The pixels in the rectangle are processed exactly as if
4581 @code{glCopyPixels} had been called, but the process stops just before
4582 final conversion. At this point, all pixel component values are clamped
4583 to the range @r{[0,1]} and then converted to the texture's internal
4584 format for storage in the texel array.
4586 The destination rectangle in the texture array may not include any
4587 texels outside the texture array as it was originally specified. It is
4588 not an error to specify a subtexture with zero width or height, but such
4589 a specification has no effect.
4591 If any of the pixels within the specified rectangle of the current
4592 @code{GL_READ_BUFFER} are outside the read window associated with the
4593 current rendering context, then the values obtained for those pixels are
4596 No change is made to the @var{internalformat}, @var{width},
4597 @var{height}, or @var{border} parameters of the specified texture array
4598 or to texel values outside the specified subregion.
4600 @code{GL_INVALID_ENUM} is generated if @var{target} is not
4601 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
4602 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
4603 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
4604 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
4605 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
4606 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
4608 @code{GL_INVALID_OPERATION} is generated if the texture array has not
4609 been defined by a previous @code{glTexImage2D} or
4610 @code{glCopyTexImage2D} operation.
4612 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4614 @code{GL_INVALID_VALUE} may be generated if
4615 @r{@var{level}>@var{log}_2(@var{max},)}, where @r{@var{max}} is the
4616 returned value of @code{GL_MAX_TEXTURE_SIZE}.
4618 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}},
4619 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)},
4620 @r{@var{yoffset}<-@var{b}}, or
4621 @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, where @r{@var{w}}
4622 is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the
4623 @code{GL_TEXTURE_HEIGHT}, and @r{@var{b}} is the
4624 @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that
4625 @r{@var{w}} and @r{@var{h}} include twice the border width.
4627 @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexSubImage2D}
4628 is executed between the execution of @code{glBegin} and the
4629 corresponding execution of @code{glEnd}.
4633 @deftypefun void glCopyTexSubImage3D target level xoffset yoffset zoffset x y width height
4634 Copy a three-dimensional texture subimage.
4638 Specifies the target texture. Must be @code{GL_TEXTURE_3D}
4641 Specifies the level-of-detail number. Level 0 is the base image level.
4642 Level @var{n} is the @var{n}th mipmap reduction image.
4645 Specifies a texel offset in the x direction within the texture array.
4648 Specifies a texel offset in the y direction within the texture array.
4651 Specifies a texel offset in the z direction within the texture array.
4655 Specify the window coordinates of the lower left corner of the
4656 rectangular region of pixels to be copied.
4659 Specifies the width of the texture subimage.
4662 Specifies the height of the texture subimage.
4666 @code{glCopyTexSubImage3D} replaces a rectangular portion of a
4667 three-dimensional texture image with pixels from the current
4668 @code{GL_READ_BUFFER} (rather than from main memory, as is the case for
4669 @code{glTexSubImage3D}).
4671 The screen-aligned pixel rectangle with lower left corner at (@var{x},\
4672 @var{y}) and with width @var{width} and height @var{height} replaces the
4673 portion of the texture array with x indices @var{xoffset} through
4674 @r{@var{xoffset}+@var{width}-1}, inclusive, and y indices @var{yoffset}
4675 through @r{@var{yoffset}+@var{height}-1}, inclusive, at z index
4676 @var{zoffset} and at the mipmap level specified by @var{level}.
4678 The pixels in the rectangle are processed exactly as if
4679 @code{glCopyPixels} had been called, but the process stops just before
4680 final conversion. At this point, all pixel component values are clamped
4681 to the range @r{[0,1]} and then converted to the texture's internal
4682 format for storage in the texel array.
4684 The destination rectangle in the texture array may not include any
4685 texels outside the texture array as it was originally specified. It is
4686 not an error to specify a subtexture with zero width or height, but such
4687 a specification has no effect.
4689 If any of the pixels within the specified rectangle of the current
4690 @code{GL_READ_BUFFER} are outside the read window associated with the
4691 current rendering context, then the values obtained for those pixels are
4694 No change is made to the @var{internalformat}, @var{width},
4695 @var{height}, @var{depth}, or @var{border} parameters of the specified
4696 texture array or to texel values outside the specified subregion.
4698 @code{GL_INVALID_ENUM} is generated if /@var{target} is not
4699 @code{GL_TEXTURE_3D}.
4701 @code{GL_INVALID_OPERATION} is generated if the texture array has not
4702 been defined by a previous @code{glTexImage3D} operation.
4704 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4706 @code{GL_INVALID_VALUE} may be generated if
4707 @r{@var{level}>@var{log}_2(@var{max},)}, where @r{@var{max}} is the
4708 returned value of @code{GL_MAX_3D_TEXTURE_SIZE}.
4710 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}},
4711 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)},
4712 @r{@var{yoffset}<-@var{b}},
4713 @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)},
4714 @r{@var{zoffset}<-@var{b}}, or
4715 @r{(@var{zoffset}+1,)>(@var{d}-@var{b},)}, where @r{@var{w}} is the
4716 @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the @code{GL_TEXTURE_HEIGHT},
4717 @r{@var{d}} is the @code{GL_TEXTURE_DEPTH}, and @r{@var{b}} is the
4718 @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that
4719 @r{@var{w}}, @r{@var{h}}, and @r{@var{d}} include twice the border
4722 @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexSubImage3D}
4723 is executed between the execution of @code{glBegin} and the
4724 corresponding execution of @code{glEnd}.
4728 @deftypefun GLuint glCreateProgram
4729 Creates a program object.
4731 @code{glCreateProgram} creates an empty program object and returns a
4732 non-zero value by which it can be referenced. A program object is an
4733 object to which shader objects can be attached. This provides a
4734 mechanism to specify the shader objects that will be linked to create a
4735 program. It also provides a means for checking the compatibility of the
4736 shaders that will be used to create a program (for instance, checking
4737 the compatibility between a vertex shader and a fragment shader). When
4738 no longer needed as part of a program object, shader objects can be
4741 One or more executables are created in a program object by successfully
4742 attaching shader objects to it with @code{glAttachShader}, successfully
4743 compiling the shader objects with @code{glCompileShader}, and
4744 successfully linking the program object with @code{glLinkProgram}. These
4745 executables are made part of current state when @code{glUseProgram} is
4746 called. Program objects can be deleted by calling
4747 @code{glDeleteProgram}. The memory associated with the program object
4748 will be deleted when it is no longer part of current rendering state for
4751 This function returns 0 if an error occurs creating the program object.
4753 @code{GL_INVALID_OPERATION} is generated if @code{glCreateProgram} is
4754 executed between the execution of @code{glBegin} and the corresponding
4755 execution of @code{glEnd}.
4759 @deftypefun GLuint glCreateShader shaderType
4760 Creates a shader object.
4763 @item @var{shaderType}
4764 Specifies the type of shader to be created. Must be either
4765 @code{GL_VERTEX_SHADER} or @code{GL_FRAGMENT_SHADER}.
4769 @code{glCreateShader} creates an empty shader object and returns a
4770 non-zero value by which it can be referenced. A shader object is used to
4771 maintain the source code strings that define a shader. @var{shaderType}
4772 indicates the type of shader to be created. Two types of shaders are
4773 supported. A shader of type @code{GL_VERTEX_SHADER} is a shader that is
4774 intended to run on the programmable vertex processor and replace the
4775 fixed functionality vertex processing in OpenGL. A shader of type
4776 @code{GL_FRAGMENT_SHADER} is a shader that is intended to run on the
4777 programmable fragment processor and replace the fixed functionality
4778 fragment processing in OpenGL.
4780 When created, a shader object's @code{GL_SHADER_TYPE} parameter is set
4781 to either @code{GL_VERTEX_SHADER} or @code{GL_FRAGMENT_SHADER},
4782 depending on the value of @var{shaderType}.
4784 This function returns 0 if an error occurs creating the shader object.
4786 @code{GL_INVALID_ENUM} is generated if @var{shaderType} is not an
4789 @code{GL_INVALID_OPERATION} is generated if @code{glCreateShader} is
4790 executed between the execution of @code{glBegin} and the corresponding
4791 execution of @code{glEnd}.
4795 @deftypefun void glCullFace mode
4796 Specify whether front- or back-facing facets can be culled.
4800 Specifies whether front- or back-facing facets are candidates for
4801 culling. Symbolic constants @code{GL_FRONT}, @code{GL_BACK}, and
4802 @code{GL_FRONT_AND_BACK} are accepted. The initial value is
4807 @code{glCullFace} specifies whether front- or back-facing facets are
4808 culled (as specified by @var{mode}) when facet culling is enabled. Facet
4809 culling is initially disabled. To enable and disable facet culling, call
4810 the @code{glEnable} and @code{glDisable} commands with the argument
4811 @code{GL_CULL_FACE}. Facets include triangles, quadrilaterals, polygons,
4814 @code{glFrontFace} specifies which of the clockwise and counterclockwise
4815 facets are front-facing and back-facing. See @code{glFrontFace}.
4817 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
4820 @code{GL_INVALID_OPERATION} is generated if @code{glCullFace} is
4821 executed between the execution of @code{glBegin} and the corresponding
4822 execution of @code{glEnd}.
4826 @deftypefun void glDeleteBuffers n buffers
4827 Delete named buffer objects.
4831 Specifies the number of buffer objects to be deleted.
4834 Specifies an array of buffer objects to be deleted.
4838 @code{glDeleteBuffers} deletes @var{n} buffer objects named by the
4839 elements of the array @var{buffers}. After a buffer object is deleted,
4840 it has no contents, and its name is free for reuse (for example by
4841 @code{glGenBuffers}). If a buffer object that is currently bound is
4842 deleted, the binding reverts to 0 (the absence of any buffer object,
4843 which reverts to client memory usage).
4845 @code{glDeleteBuffers} silently ignores 0's and names that do not
4846 correspond to existing buffer objects.
4848 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
4850 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteBuffers} is
4851 executed between the execution of @code{glBegin} and the corresponding
4852 execution of @code{glEnd}.
4856 @deftypefun void glDeleteLists list range
4857 Delete a contiguous group of display lists.
4861 Specifies the integer name of the first display list to delete.
4864 Specifies the number of display lists to delete.
4868 @code{glDeleteLists} causes a contiguous group of display lists to be
4869 deleted. @var{list} is the name of the first display list to be deleted,
4870 and @var{range} is the number of display lists to delete. All display
4871 lists @r{@var{d}} with @r{@var{list}<=@var{d}<=@var{list}+@var{range}-1}
4874 All storage locations allocated to the specified display lists are
4875 freed, and the names are available for reuse at a later time. Names
4876 within the range that do not have an associated display list are
4877 ignored. If @var{range} is 0, nothing happens.
4879 @code{GL_INVALID_VALUE} is generated if @var{range} is negative.
4881 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteLists} is
4882 executed between the execution of @code{glBegin} and the corresponding
4883 execution of @code{glEnd}.
4887 @deftypefun void glDeleteProgram program
4888 Deletes a program object.
4892 Specifies the program object to be deleted.
4896 @code{glDeleteProgram} frees the memory and invalidates the name
4897 associated with the program object specified by @var{program.} This
4898 command effectively undoes the effects of a call to
4899 @code{glCreateProgram}.
4901 If a program object is in use as part of current rendering state, it
4902 will be flagged for deletion, but it will not be deleted until it is no
4903 longer part of current state for any rendering context. If a program
4904 object to be deleted has shader objects attached to it, those shader
4905 objects will be automatically detached but not deleted unless they have
4906 already been flagged for deletion by a previous call to
4907 @code{glDeleteShader}. A value of 0 for @var{program} will be silently
4910 To determine whether a program object has been flagged for deletion,
4911 call @code{glGetProgram} with arguments @var{program} and
4912 @code{GL_DELETE_STATUS}.
4914 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
4915 generated by OpenGL.
4917 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteProgram} is
4918 executed between the execution of @code{glBegin} and the corresponding
4919 execution of @code{glEnd}.
4923 @deftypefun void glDeleteQueries n ids
4924 Delete named query objects.
4928 Specifies the number of query objects to be deleted.
4931 Specifies an array of query objects to be deleted.
4935 @code{glDeleteQueries} deletes @var{n} query objects named by the
4936 elements of the array @var{ids}. After a query object is deleted, it has
4937 no contents, and its name is free for reuse (for example by
4938 @code{glGenQueries}).
4940 @code{glDeleteQueries} silently ignores 0's and names that do not
4941 correspond to existing query objects.
4943 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
4945 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteQueries} is
4946 executed between the execution of @code{glBegin} and the corresponding
4947 execution of @code{glEnd}.
4951 @deftypefun void glDeleteShader shader
4952 Deletes a shader object.
4956 Specifies the shader object to be deleted.
4960 @code{glDeleteShader} frees the memory and invalidates the name
4961 associated with the shader object specified by @var{shader}. This
4962 command effectively undoes the effects of a call to
4963 @code{glCreateShader}.
4965 If a shader object to be deleted is attached to a program object, it
4966 will be flagged for deletion, but it will not be deleted until it is no
4967 longer attached to any program object, for any rendering context (i.e.,
4968 it must be detached from wherever it was attached before it will be
4969 deleted). A value of 0 for @var{shader} will be silently ignored.
4971 To determine whether an object has been flagged for deletion, call
4972 @code{glGetShader} with arguments @var{shader} and
4973 @code{GL_DELETE_STATUS}.
4975 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
4976 generated by OpenGL.
4978 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteShader} is
4979 executed between the execution of @code{glBegin} and the corresponding
4980 execution of @code{glEnd}.
4984 @deftypefun void glDeleteTextures n textures
4985 Delete named textures.
4989 Specifies the number of textures to be deleted.
4991 @item @var{textures}
4992 Specifies an array of textures to be deleted.
4996 @code{glDeleteTextures} deletes @var{n} textures named by the elements
4997 of the array @var{textures}. After a texture is deleted, it has no
4998 contents or dimensionality, and its name is free for reuse (for example
4999 by @code{glGenTextures}). If a texture that is currently bound is
5000 deleted, the binding reverts to 0 (the default texture).
5002 @code{glDeleteTextures} silently ignores 0's and names that do not
5003 correspond to existing textures.
5005 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
5007 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteTextures} is
5008 executed between the execution of @code{glBegin} and the corresponding
5009 execution of @code{glEnd}.
5013 @deftypefun void glDepthFunc func
5014 Specify the value used for depth buffer comparisons.
5018 Specifies the depth comparison function. Symbolic constants
5019 @code{GL_NEVER}, @code{GL_LESS}, @code{GL_EQUAL}, @code{GL_LEQUAL},
5020 @code{GL_GREATER}, @code{GL_NOTEQUAL}, @code{GL_GEQUAL}, and
5021 @code{GL_ALWAYS} are accepted. The initial value is @code{GL_LESS}.
5025 @code{glDepthFunc} specifies the function used to compare each incoming
5026 pixel depth value with the depth value present in the depth buffer. The
5027 comparison is performed only if depth testing is enabled. (See
5028 @code{glEnable} and @code{glDisable} of @code{GL_DEPTH_TEST}.)
5030 @var{func} specifies the conditions under which the pixel will be drawn.
5031 The comparison functions are as follows:
5034 @item @code{GL_NEVER}
5037 @item @code{GL_LESS}
5038 Passes if the incoming depth value is less than the stored depth value.
5040 @item @code{GL_EQUAL}
5041 Passes if the incoming depth value is equal to the stored depth value.
5043 @item @code{GL_LEQUAL}
5044 Passes if the incoming depth value is less than or equal to the stored
5047 @item @code{GL_GREATER}
5048 Passes if the incoming depth value is greater than the stored depth
5051 @item @code{GL_NOTEQUAL}
5052 Passes if the incoming depth value is not equal to the stored depth
5055 @item @code{GL_GEQUAL}
5056 Passes if the incoming depth value is greater than or equal to the
5059 @item @code{GL_ALWAYS}
5064 The initial value of @var{func} is @code{GL_LESS}. Initially, depth
5065 testing is disabled. If depth testing is disabled or if no depth buffer
5066 exists, it is as if the depth test always passes.
5068 @code{GL_INVALID_ENUM} is generated if @var{func} is not an accepted
5071 @code{GL_INVALID_OPERATION} is generated if @code{glDepthFunc} is
5072 executed between the execution of @code{glBegin} and the corresponding
5073 execution of @code{glEnd}.
5077 @deftypefun void glDepthMask flag
5078 Enable or disable writing into the depth buffer.
5082 Specifies whether the depth buffer is enabled for writing. If @var{flag}
5083 is @code{GL_FALSE}, depth buffer writing is disabled. Otherwise, it is
5084 enabled. Initially, depth buffer writing is enabled.
5088 @code{glDepthMask} specifies whether the depth buffer is enabled for
5089 writing. If @var{flag} is @code{GL_FALSE}, depth buffer writing is
5090 disabled. Otherwise, it is enabled. Initially, depth buffer writing is
5093 @code{GL_INVALID_OPERATION} is generated if @code{glDepthMask} is
5094 executed between the execution of @code{glBegin} and the corresponding
5095 execution of @code{glEnd}.
5099 @deftypefun void glDepthRange nearVal farVal
5100 Specify mapping of depth values from normalized device coordinates to
5105 Specifies the mapping of the near clipping plane to window coordinates.
5106 The initial value is 0.
5109 Specifies the mapping of the far clipping plane to window coordinates.
5110 The initial value is 1.
5114 After clipping and division by @var{w}, depth coordinates range from
5115 @r{-1} to 1, corresponding to the near and far clipping planes.
5116 @code{glDepthRange} specifies a linear mapping of the normalized depth
5117 coordinates in this range to window depth coordinates. Regardless of the
5118 actual depth buffer implementation, window coordinate depth values are
5119 treated as though they range from 0 through 1 (like color components).
5120 Thus, the values accepted by @code{glDepthRange} are both clamped to
5121 this range before they are accepted.
5123 The setting of (0,1) maps the near plane to 0 and the far plane to 1.
5124 With this mapping, the depth buffer range is fully utilized.
5126 @code{GL_INVALID_OPERATION} is generated if @code{glDepthRange} is
5127 executed between the execution of @code{glBegin} and the corresponding
5128 execution of @code{glEnd}.
5132 @deftypefun void glDetachShader program shader
5133 Detaches a shader object from a program object to which it is attached.
5137 Specifies the program object from which to detach the shader object.
5140 Specifies the shader object to be detached.
5144 @code{glDetachShader} detaches the shader object specified by
5145 @var{shader} from the program object specified by @var{program}. This
5146 command can be used to undo the effect of the command
5147 @code{glAttachShader}.
5149 If @var{shader} has already been flagged for deletion by a call to
5150 @code{glDeleteShader} and it is not attached to any other program
5151 object, it will be deleted after it has been detached.
5153 @code{GL_INVALID_VALUE} is generated if either @var{program} or
5154 @var{shader} is a value that was not generated by OpenGL.
5156 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
5159 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
5162 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not attached
5165 @code{GL_INVALID_OPERATION} is generated if @code{glDetachShader} is
5166 executed between the execution of @code{glBegin} and the corresponding
5167 execution of @code{glEnd}.
5171 @deftypefun void glDrawArrays mode first count
5172 Render primitives from array data.
5176 Specifies what kind of primitives to render. Symbolic constants
5177 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
5178 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
5179 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
5180 @code{GL_POLYGON} are accepted.
5183 Specifies the starting index in the enabled arrays.
5186 Specifies the number of indices to be rendered.
5190 @code{glDrawArrays} specifies multiple geometric primitives with very
5191 few subroutine calls. Instead of calling a GL procedure to pass each
5192 individual vertex, normal, texture coordinate, edge flag, or color, you
5193 can prespecify separate arrays of vertices, normals, and colors and use
5194 them to construct a sequence of primitives with a single call to
5195 @code{glDrawArrays}.
5197 When @code{glDrawArrays} is called, it uses @var{count} sequential
5198 elements from each enabled array to construct a sequence of geometric
5199 primitives, beginning with element @var{first}. @var{mode} specifies
5200 what kind of primitives are constructed and how the array elements
5201 construct those primitives. If @code{GL_VERTEX_ARRAY} is not enabled, no
5202 geometric primitives are generated.
5204 Vertex attributes that are modified by @code{glDrawArrays} have an
5205 unspecified value after @code{glDrawArrays} returns. For example, if
5206 @code{GL_COLOR_ARRAY} is enabled, the value of the current color is
5207 undefined after @code{glDrawArrays} executes. Attributes that aren't
5208 modified remain well defined.
5210 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
5213 @code{GL_INVALID_VALUE} is generated if @var{count} is negative.
5215 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5216 name is bound to an enabled array and the buffer object's data store is
5219 @code{GL_INVALID_OPERATION} is generated if @code{glDrawArrays} is
5220 executed between the execution of @code{glBegin} and the corresponding
5225 @deftypefun void glDrawBuffers n bufs
5226 Specifies a list of color buffers to be drawn into.
5230 Specifies the number of buffers in @var{bufs}.
5233 Points to an array of symbolic constants specifying the buffers into
5234 which fragment colors or data values will be written.
5238 @code{glDrawBuffers} defines an array of buffers into which fragment
5239 color values or fragment data will be written. If no fragment shader is
5240 active, rendering operations will generate only one fragment color per
5241 fragment and it will be written into each of the buffers specified by
5242 @var{bufs}. If a fragment shader is active and it writes a value to the
5243 output variable @code{gl_FragColor}, then that value will be written
5244 into each of the buffers specified by @var{bufs}. If a fragment shader
5245 is active and it writes a value to one or more elements of the output
5246 array variable @code{gl_FragData[]}, then the value of
5247 @code{gl_FragData[0] } will be written into the first buffer specified
5248 by @var{bufs}, the value of @code{gl_FragData[1] } will be written into
5249 the second buffer specified by @var{bufs}, and so on up to
5250 @code{gl_FragData[n-1]}. The draw buffer used for @code{gl_FragData[n]}
5251 and beyond is implicitly set to be @code{GL_NONE}.
5253 The symbolic constants contained in @var{bufs} may be any of the
5257 @item @code{GL_NONE}
5258 The fragment color/data value is not written into any color buffer.
5260 @item @code{GL_FRONT_LEFT}
5261 The fragment color/data value is written into the front left color
5264 @item @code{GL_FRONT_RIGHT}
5265 The fragment color/data value is written into the front right color
5268 @item @code{GL_BACK_LEFT}
5269 The fragment color/data value is written into the back left color
5272 @item @code{GL_BACK_RIGHT}
5273 The fragment color/data value is written into the back right color
5276 @item @code{GL_AUXi}
5277 The fragment color/data value is written into auxiliary buffer @code{i}.
5281 Except for @code{GL_NONE}, the preceding symbolic constants may not
5282 appear more than once in @var{bufs}. The maximum number of draw buffers
5283 supported is implementation dependent and can be queried by calling
5284 @code{glGet} with the argument @code{GL_MAX_DRAW_BUFFERS}. The number of
5285 auxiliary buffers can be queried by calling @code{glGet} with the
5286 argument @code{GL_AUX_BUFFERS}.
5288 @code{GL_INVALID_ENUM} is generated if one of the values in @var{bufs}
5289 is not an accepted value.
5291 @code{GL_INVALID_ENUM} is generated if @var{n} is less than 0.
5293 @code{GL_INVALID_OPERATION} is generated if a symbolic constant other
5294 than @code{GL_NONE} appears more than once in @var{bufs}.
5296 @code{GL_INVALID_OPERATION} is generated if any of the entries in
5297 @var{bufs} (other than @code{GL_NONE} ) indicates a color buffer that
5298 does not exist in the current GL context.
5300 @code{GL_INVALID_VALUE} is generated if @var{n} is greater than
5301 @code{GL_MAX_DRAW_BUFFERS}.
5303 @code{GL_INVALID_OPERATION} is generated if @code{glDrawBuffers} is
5304 executed between the execution of @code{glBegin} and the corresponding
5305 execution of @code{glEnd}.
5309 @deftypefun void glDrawBuffer mode
5310 Specify which color buffers are to be drawn into.
5314 Specifies up to four color buffers to be drawn into. Symbolic constants
5315 @code{GL_NONE}, @code{GL_FRONT_LEFT}, @code{GL_FRONT_RIGHT},
5316 @code{GL_BACK_LEFT}, @code{GL_BACK_RIGHT}, @code{GL_FRONT},
5317 @code{GL_BACK}, @code{GL_LEFT}, @code{GL_RIGHT},
5318 @code{GL_FRONT_AND_BACK}, and @code{GL_AUX}@var{i}, where @var{i} is
5319 between 0 and the value of @code{GL_AUX_BUFFERS} minus 1, are accepted.
5320 (@code{GL_AUX_BUFFERS} is not the upper limit; use @code{glGet} to query
5321 the number of available aux buffers.) The initial value is
5322 @code{GL_FRONT} for single-buffered contexts, and @code{GL_BACK} for
5323 double-buffered contexts.
5327 When colors are written to the frame buffer, they are written into the
5328 color buffers specified by @code{glDrawBuffer}. The specifications are
5332 @item @code{GL_NONE}
5333 No color buffers are written.
5335 @item @code{GL_FRONT_LEFT}
5336 Only the front left color buffer is written.
5338 @item @code{GL_FRONT_RIGHT}
5339 Only the front right color buffer is written.
5341 @item @code{GL_BACK_LEFT}
5342 Only the back left color buffer is written.
5344 @item @code{GL_BACK_RIGHT}
5345 Only the back right color buffer is written.
5347 @item @code{GL_FRONT}
5348 Only the front left and front right color buffers are written. If there
5349 is no front right color buffer, only the front left color buffer is
5352 @item @code{GL_BACK}
5353 Only the back left and back right color buffers are written. If there is
5354 no back right color buffer, only the back left color buffer is written.
5356 @item @code{GL_LEFT}
5357 Only the front left and back left color buffers are written. If there is
5358 no back left color buffer, only the front left color buffer is written.
5360 @item @code{GL_RIGHT}
5361 Only the front right and back right color buffers are written. If there
5362 is no back right color buffer, only the front right color buffer is
5365 @item @code{GL_FRONT_AND_BACK}
5366 All the front and back color buffers (front left, front right, back
5367 left, back right) are written. If there are no back color buffers, only
5368 the front left and front right color buffers are written. If there are
5369 no right color buffers, only the front left and back left color buffers
5370 are written. If there are no right or back color buffers, only the front
5371 left color buffer is written.
5373 @item @code{GL_AUX}@var{i}
5374 Only auxiliary color buffer @var{i} is written.
5378 If more than one color buffer is selected for drawing, then blending or
5379 logical operations are computed and applied independently for each color
5380 buffer and can produce different results in each buffer.
5382 Monoscopic contexts include only @var{left} buffers, and stereoscopic
5383 contexts include both @var{left} and @var{right} buffers. Likewise,
5384 single-buffered contexts include only @var{front} buffers, and
5385 double-buffered contexts include both @var{front} and @var{back}
5386 buffers. The context is selected at GL initialization.
5388 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
5391 @code{GL_INVALID_OPERATION} is generated if none of the buffers
5392 indicated by @var{mode} exists.
5394 @code{GL_INVALID_OPERATION} is generated if @code{glDrawBuffer} is
5395 executed between the execution of @code{glBegin} and the corresponding
5396 execution of @code{glEnd}.
5400 @deftypefun void glDrawElements mode count type indices
5401 Render primitives from array data.
5405 Specifies what kind of primitives to render. Symbolic constants
5406 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
5407 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
5408 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
5409 @code{GL_POLYGON} are accepted.
5412 Specifies the number of elements to be rendered.
5415 Specifies the type of the values in @var{indices}. Must be one of
5416 @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or
5417 @code{GL_UNSIGNED_INT}.
5420 Specifies a pointer to the location where the indices are stored.
5424 @code{glDrawElements} specifies multiple geometric primitives with very
5425 few subroutine calls. Instead of calling a GL function to pass each
5426 individual vertex, normal, texture coordinate, edge flag, or color, you
5427 can prespecify separate arrays of vertices, normals, and so on, and use
5428 them to construct a sequence of primitives with a single call to
5429 @code{glDrawElements}.
5431 When @code{glDrawElements} is called, it uses @var{count} sequential
5432 elements from an enabled array, starting at @var{indices} to construct a
5433 sequence of geometric primitives. @var{mode} specifies what kind of
5434 primitives are constructed and how the array elements construct these
5435 primitives. If more than one array is enabled, each is used. If
5436 @code{GL_VERTEX_ARRAY} is not enabled, no geometric primitives are
5439 Vertex attributes that are modified by @code{glDrawElements} have an
5440 unspecified value after @code{glDrawElements} returns. For example, if
5441 @code{GL_COLOR_ARRAY} is enabled, the value of the current color is
5442 undefined after @code{glDrawElements} executes. Attributes that aren't
5443 modified maintain their previous values.
5445 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
5448 @code{GL_INVALID_VALUE} is generated if @var{count} is negative.
5450 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5451 name is bound to an enabled array or the element array and the buffer
5452 object's data store is currently mapped.
5454 @code{GL_INVALID_OPERATION} is generated if @code{glDrawElements} is
5455 executed between the execution of @code{glBegin} and the corresponding
5460 @deftypefun void glDrawPixels width height format type data
5461 Write a block of pixels to the frame buffer.
5466 Specify the dimensions of the pixel rectangle to be written into the
5470 Specifies the format of the pixel data. Symbolic constants
5471 @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX},
5472 @code{GL_DEPTH_COMPONENT}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA},
5473 @code{GL_BGRA}, @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE},
5474 @code{GL_ALPHA}, @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA} are
5478 Specifies the data type for @var{data}. Symbolic constants
5479 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
5480 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
5481 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
5482 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
5483 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
5484 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
5485 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
5486 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
5487 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
5490 Specifies a pointer to the pixel data.
5494 @code{glDrawPixels} reads pixel data from memory and writes it into the
5495 frame buffer relative to the current raster position, provided that the
5496 raster position is valid. Use @code{glRasterPos} or @code{glWindowPos}
5497 to set the current raster position; use @code{glGet} with argument
5498 @code{GL_CURRENT_RASTER_POSITION_VALID} to determine if the specified
5499 raster position is valid, and @code{glGet} with argument
5500 @code{GL_CURRENT_RASTER_POSITION} to query the raster position.
5502 Several parameters define the encoding of pixel data in memory and
5503 control the processing of the pixel data before it is placed in the
5504 frame buffer. These parameters are set with four commands:
5505 @code{glPixelStore}, @code{glPixelTransfer}, @code{glPixelMap}, and
5506 @code{glPixelZoom}. This reference page describes the effects on
5507 @code{glDrawPixels} of many, but not all, of the parameters specified by
5508 these four commands.
5510 Data is read from @var{data} as a sequence of signed or unsigned bytes,
5511 signed or unsigned shorts, signed or unsigned integers, or
5512 single-precision floating-point values, depending on @var{type}. When
5513 @var{type} is one of @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE},
5514 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
5515 @code{GL_INT}, or @code{GL_FLOAT} each of these bytes, shorts, integers,
5516 or floating-point values is interpreted as one color or depth component,
5517 or one index, depending on @var{format}. When @var{type} is one of
5518 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_SHORT_5_6_5},
5519 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
5520 @code{GL_UNSIGNED_INT_8_8_8_8}, or @code{GL_UNSIGNED_INT_10_10_10_2},
5521 each unsigned value is interpreted as containing all the components for
5522 a single pixel, with the color components arranged according to
5523 @var{format}. When @var{type} is one of
5524 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
5525 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
5526 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
5527 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, or
5528 @code{GL_UNSIGNED_INT_2_10_10_10_REV}, each unsigned value is
5529 interpreted as containing all color components, specified by
5530 @var{format}, for a single pixel in a reversed order. Indices are always
5531 treated individually. Color components are treated as groups of one,
5532 two, three, or four values, again based on @var{format}. Both individual
5533 indices and groups of components are referred to as pixels. If
5534 @var{type} is @code{GL_BITMAP}, the data must be unsigned bytes, and
5535 @var{format} must be either @code{GL_COLOR_INDEX} or
5536 @code{GL_STENCIL_INDEX}. Each unsigned byte is treated as eight 1-bit
5537 pixels, with bit ordering determined by @code{GL_UNPACK_LSB_FIRST} (see
5538 @code{glPixelStore}).
5540 @r{@var{width}×@var{height}} pixels are read from memory, starting at
5541 location @var{data}. By default, these pixels are taken from adjacent
5542 memory locations, except that after all @var{width} pixels are read, the
5543 read pointer is advanced to the next four-byte boundary. The four-byte
5544 row alignment is specified by @code{glPixelStore} with argument
5545 @code{GL_UNPACK_ALIGNMENT}, and it can be set to one, two, four, or
5546 eight bytes. Other pixel store parameters specify different read pointer
5547 advancements, both before the first pixel is read and after all
5548 @var{width} pixels are read. See the @code{glPixelStore} reference page
5549 for details on these options.
5551 If a non-zero named buffer object is bound to the
5552 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
5553 block of pixels is specified, @var{data} is treated as a byte offset
5554 into the buffer object's data store.
5556 The @r{@var{width}×@var{height}} pixels that are read from memory are
5557 each operated on in the same way, based on the values of several
5558 parameters specified by @code{glPixelTransfer} and @code{glPixelMap}.
5559 The details of these operations, as well as the target buffer into which
5560 the pixels are drawn, are specific to the format of the pixels, as
5561 specified by @var{format}. @var{format} can assume one of 13 symbolic
5565 @item @code{GL_COLOR_INDEX}
5566 Each pixel is a single value, a color index. It is converted to
5567 fixed-point format, with an unspecified number of bits to the right of
5568 the binary point, regardless of the memory data type. Floating-point
5569 values convert to true fixed-point values. Signed and unsigned integer
5570 data is converted with all fraction bits set to 0. Bitmap data convert
5573 Each fixed-point index is then shifted left by @code{GL_INDEX_SHIFT}
5574 bits and added to @code{GL_INDEX_OFFSET}. If @code{GL_INDEX_SHIFT} is
5575 negative, the shift is to the right. In either case, zero bits fill
5576 otherwise unspecified bit locations in the result.
5578 If the GL is in RGBA mode, the resulting index is converted to an RGBA
5579 pixel with the help of the @code{GL_PIXEL_MAP_I_TO_R},
5580 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
5581 @code{GL_PIXEL_MAP_I_TO_A} tables. If the GL is in color index mode, and
5582 if @code{GL_MAP_COLOR} is true, the index is replaced with the value
5583 that it references in lookup table @code{GL_PIXEL_MAP_I_TO_I}. Whether
5584 the lookup replacement of the index is done or not, the integer part of
5585 the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the
5586 number of bits in a color index buffer.
5588 The GL then converts the resulting indices or RGBA colors to fragments
5589 by attaching the current raster position @var{z} coordinate and texture
5590 coordinates to each pixel, then assigning @r{@var{x}} and @r{@var{y}}
5591 window coordinates to the @r{@var{n}}th fragment such that
5592 @r{@var{x}_@var{n}=@var{x}_@var{r}+@var{n}%@var{width}}@r{@var{y}_@var{n}=@var{y}_@var{r}+⌊@var{n}/@var{width},⌋}
5594 where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster
5595 position. These pixel fragments are then treated just like the fragments
5596 generated by rasterizing points, lines, or polygons. Texture mapping,
5597 fog, and all the fragment operations are applied before the fragments
5598 are written to the frame buffer.
5600 @item @code{GL_STENCIL_INDEX}
5601 Each pixel is a single value, a stencil index. It is converted to
5602 fixed-point format, with an unspecified number of bits to the right of
5603 the binary point, regardless of the memory data type. Floating-point
5604 values convert to true fixed-point values. Signed and unsigned integer
5605 data is converted with all fraction bits set to 0. Bitmap data convert
5608 Each fixed-point index is then shifted left by @code{GL_INDEX_SHIFT}
5609 bits, and added to @code{GL_INDEX_OFFSET}. If @code{GL_INDEX_SHIFT} is
5610 negative, the shift is to the right. In either case, zero bits fill
5611 otherwise unspecified bit locations in the result. If
5612 @code{GL_MAP_STENCIL} is true, the index is replaced with the value that
5613 it references in lookup table @code{GL_PIXEL_MAP_S_TO_S}. Whether the
5614 lookup replacement of the index is done or not, the integer part of the
5615 index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the
5616 number of bits in the stencil buffer. The resulting stencil indices are
5617 then written to the stencil buffer such that the @r{@var{n}}th index is
5620 @r{@var{x}_@var{n}=@var{x}_@var{r}+@var{n}%@var{width}}@r{@var{y}_@var{n}=@var{y}_@var{r}+⌊@var{n}/@var{width},⌋}
5622 where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster
5623 position. Only the pixel ownership test, the scissor test, and the
5624 stencil writemask affect these write operations.
5626 @item @code{GL_DEPTH_COMPONENT}
5627 Each pixel is a single-depth component. Floating-point data is converted
5628 directly to an internal floating-point format with unspecified
5629 precision. Signed integer data is mapped linearly to the internal
5630 floating-point format such that the most positive representable integer
5631 value maps to 1.0, and the most negative representable value maps to
5632 @r{-1.0}. Unsigned integer data is mapped similarly: the largest integer
5633 value maps to 1.0, and 0 maps to 0.0. The resulting floating-point depth
5634 value is then multiplied by @code{GL_DEPTH_SCALE} and added to
5635 @code{GL_DEPTH_BIAS}. The result is clamped to the range @r{[0,1]}.
5637 The GL then converts the resulting depth components to fragments by
5638 attaching the current raster position color or color index and texture
5639 coordinates to each pixel, then assigning @r{@var{x}} and @r{@var{y}}
5640 window coordinates to the @r{@var{n}}th fragment such that
5642 @r{@var{x}_@var{n}=@var{x}_@var{r}+@var{n}%@var{width}}@r{@var{y}_@var{n}=@var{y}_@var{r}+⌊@var{n}/@var{width},⌋}
5644 where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster
5645 position. These pixel fragments are then treated just like the fragments
5646 generated by rasterizing points, lines, or polygons. Texture mapping,
5647 fog, and all the fragment operations are applied before the fragments
5648 are written to the frame buffer.
5650 @item @code{GL_RGBA}
5651 @item @code{GL_BGRA}
5652 Each pixel is a four-component group: For @code{GL_RGBA}, the red
5653 component is first, followed by green, followed by blue, followed by
5654 alpha; for @code{GL_BGRA} the order is blue, green, red and then alpha.
5655 Floating-point values are converted directly to an internal
5656 floating-point format with unspecified precision. Signed integer values
5657 are mapped linearly to the internal floating-point format such that the
5658 most positive representable integer value maps to 1.0, and the most
5659 negative representable value maps to @r{-1.0}. (Note that this mapping
5660 does not convert 0 precisely to 0.0.) Unsigned integer data is mapped
5661 similarly: The largest integer value maps to 1.0, and 0 maps to 0.0. The
5662 resulting floating-point color values are then multiplied by
5663 @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is RED,
5664 GREEN, BLUE, and ALPHA for the respective color components. The results
5665 are clamped to the range @r{[0,1]}.
5667 If @code{GL_MAP_COLOR} is true, each color component is scaled by the
5668 size of lookup table @code{GL_PIXEL_MAP_c_TO_c}, then replaced by the
5669 value that it references in that table. @var{c} is R, G, B, or A
5672 The GL then converts the resulting RGBA colors to fragments by attaching
5673 the current raster position @var{z} coordinate and texture coordinates
5674 to each pixel, then assigning @r{@var{x}} and @r{@var{y}} window
5675 coordinates to the @r{@var{n}}th fragment such that
5677 @r{@var{x}_@var{n}=@var{x}_@var{r}+@var{n}%@var{width}}@r{@var{y}_@var{n}=@var{y}_@var{r}+⌊@var{n}/@var{width},⌋}
5679 where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster
5680 position. These pixel fragments are then treated just like the fragments
5681 generated by rasterizing points, lines, or polygons. Texture mapping,
5682 fog, and all the fragment operations are applied before the fragments
5683 are written to the frame buffer.
5686 Each pixel is a single red component. This component is converted to the
5687 internal floating-point format in the same way the red component of an
5688 RGBA pixel is. It is then converted to an RGBA pixel with green and blue
5689 set to 0, and alpha set to 1. After this conversion, the pixel is
5690 treated as if it had been read as an RGBA pixel.
5692 @item @code{GL_GREEN}
5693 Each pixel is a single green component. This component is converted to
5694 the internal floating-point format in the same way the green component
5695 of an RGBA pixel is. It is then converted to an RGBA pixel with red and
5696 blue set to 0, and alpha set to 1. After this conversion, the pixel is
5697 treated as if it had been read as an RGBA pixel.
5699 @item @code{GL_BLUE}
5700 Each pixel is a single blue component. This component is converted to
5701 the internal floating-point format in the same way the blue component of
5702 an RGBA pixel is. It is then converted to an RGBA pixel with red and
5703 green set to 0, and alpha set to 1. After this conversion, the pixel is
5704 treated as if it had been read as an RGBA pixel.
5706 @item @code{GL_ALPHA}
5707 Each pixel is a single alpha component. This component is converted to
5708 the internal floating-point format in the same way the alpha component
5709 of an RGBA pixel is. It is then converted to an RGBA pixel with red,
5710 green, and blue set to 0. After this conversion, the pixel is treated as
5711 if it had been read as an RGBA pixel.
5715 Each pixel is a three-component group: red first, followed by green,
5716 followed by blue; for @code{GL_BGR}, the first component is blue,
5717 followed by green and then red. Each component is converted to the
5718 internal floating-point format in the same way the red, green, and blue
5719 components of an RGBA pixel are. The color triple is converted to an
5720 RGBA pixel with alpha set to 1. After this conversion, the pixel is
5721 treated as if it had been read as an RGBA pixel.
5723 @item @code{GL_LUMINANCE}
5724 Each pixel is a single luminance component. This component is converted
5725 to the internal floating-point format in the same way the red component
5726 of an RGBA pixel is. It is then converted to an RGBA pixel with red,
5727 green, and blue set to the converted luminance value, and alpha set to
5728 1. After this conversion, the pixel is treated as if it had been read as
5731 @item @code{GL_LUMINANCE_ALPHA}
5732 Each pixel is a two-component group: luminance first, followed by alpha.
5733 The two components are converted to the internal floating-point format
5734 in the same way the red component of an RGBA pixel is. They are then
5735 converted to an RGBA pixel with red, green, and blue set to the
5736 converted luminance value, and alpha set to the converted alpha value.
5737 After this conversion, the pixel is treated as if it had been read as an
5742 The following table summarizes the meaning of the valid constants for
5743 the @var{type} parameter:
5749 @strong{Corresponding Type}
5751 @item @code{GL_UNSIGNED_BYTE}
5752 unsigned 8-bit integer
5754 @item @code{GL_BYTE}
5755 signed 8-bit integer
5757 @item @code{GL_BITMAP}
5758 single bits in unsigned 8-bit integers
5760 @item @code{GL_UNSIGNED_SHORT}
5761 unsigned 16-bit integer
5763 @item @code{GL_SHORT}
5764 signed 16-bit integer
5766 @item @code{GL_UNSIGNED_INT}
5767 unsigned 32-bit integer
5772 @item @code{GL_FLOAT}
5773 single-precision floating-point
5775 @item @code{GL_UNSIGNED_BYTE_3_3_2}
5776 unsigned 8-bit integer
5778 @item @code{GL_UNSIGNED_BYTE_2_3_3_REV}
5779 unsigned 8-bit integer with reversed component ordering
5781 @item @code{GL_UNSIGNED_SHORT_5_6_5}
5782 unsigned 16-bit integer
5784 @item @code{GL_UNSIGNED_SHORT_5_6_5_REV}
5785 unsigned 16-bit integer with reversed component ordering
5787 @item @code{GL_UNSIGNED_SHORT_4_4_4_4}
5788 unsigned 16-bit integer
5790 @item @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}
5791 unsigned 16-bit integer with reversed component ordering
5793 @item @code{GL_UNSIGNED_SHORT_5_5_5_1}
5794 unsigned 16-bit integer
5796 @item @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}
5797 unsigned 16-bit integer with reversed component ordering
5799 @item @code{GL_UNSIGNED_INT_8_8_8_8}
5800 unsigned 32-bit integer
5802 @item @code{GL_UNSIGNED_INT_8_8_8_8_REV}
5803 unsigned 32-bit integer with reversed component ordering
5805 @item @code{GL_UNSIGNED_INT_10_10_10_2}
5806 unsigned 32-bit integer
5808 @item @code{GL_UNSIGNED_INT_2_10_10_10_REV}
5809 unsigned 32-bit integer with reversed component ordering
5815 The rasterization described so far assumes pixel zoom factors of 1. If
5816 @code{glPixelZoom} is used to change the @r{@var{x}} and @r{@var{y}}
5817 pixel zoom factors, pixels are converted to fragments as follows. If
5818 @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position,
5819 and a given pixel is in the @r{@var{n}}th column and @r{@var{m}}th row
5820 of the pixel rectangle, then fragments are generated for pixels whose
5821 centers are in the rectangle with corners at
5823 @r{(@var{x}_@var{r}+@var{zoom}_@var{x},@var{n},@var{y}_@var{r}+@var{zoom}_@var{y},@var{m})}@r{(@var{x}_@var{r}+@var{zoom}_@var{x},(@var{n}+1,),@var{y}_@var{r}+@var{zoom}_@var{y},(@var{m}+1,))}
5825 where @r{@var{zoom}_@var{x}} is the value of @code{GL_ZOOM_X} and
5826 @r{@var{zoom}_@var{y}} is the value of @code{GL_ZOOM_Y}.
5828 @code{GL_INVALID_ENUM} is generated if @var{format} or @var{type} is not
5829 one of the accepted values.
5831 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
5832 and @var{format} is not either @code{GL_COLOR_INDEX} or
5833 @code{GL_STENCIL_INDEX}.
5835 @code{GL_INVALID_VALUE} is generated if either @var{width} or
5836 @var{height} is negative.
5838 @code{GL_INVALID_OPERATION} is generated if @var{format} is
5839 @code{GL_STENCIL_INDEX} and there is no stencil buffer.
5841 @code{GL_INVALID_OPERATION} is generated if @var{format} is
5842 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
5843 @code{GL_RGB}, @code{GL_RGBA}, @code{GL_BGR}, @code{GL_BGRA},
5844 @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}, and the GL is in
5847 @code{GL_INVALID_OPERATION} is generated if @var{format} is one of
5848 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
5849 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
5850 and @var{format} is not @code{GL_RGB}.
5852 @code{GL_INVALID_OPERATION} is generated if @var{format} is one of
5853 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
5854 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
5855 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
5856 @code{GL_UNSIGNED_INT_10_10_10_2}, or
5857 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
5858 @code{GL_RGBA} nor @code{GL_BGRA}.
5860 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5861 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
5862 object's data store is currently mapped.
5864 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5865 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
5866 would be unpacked from the buffer object such that the memory reads
5867 required would exceed the data store size.
5869 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5870 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
5871 is not evenly divisible into the number of bytes needed to store in
5872 memory a datum indicated by @var{type}.
5874 @code{GL_INVALID_OPERATION} is generated if @code{glDrawPixels} is
5875 executed between the execution of @code{glBegin} and the corresponding
5876 execution of @code{glEnd}.
5880 @deftypefun void glDrawRangeElements mode start end count type indices
5881 Render primitives from array data.
5885 Specifies what kind of primitives to render. Symbolic constants
5886 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
5887 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
5888 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
5889 @code{GL_POLYGON} are accepted.
5892 Specifies the minimum array index contained in @var{indices}.
5895 Specifies the maximum array index contained in @var{indices}.
5898 Specifies the number of elements to be rendered.
5901 Specifies the type of the values in @var{indices}. Must be one of
5902 @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or
5903 @code{GL_UNSIGNED_INT}.
5906 Specifies a pointer to the location where the indices are stored.
5910 @code{glDrawRangeElements} is a restricted form of
5911 @code{glDrawElements}. @var{mode}, @var{start}, @var{end}, and
5912 @var{count} match the corresponding arguments to @code{glDrawElements},
5913 with the additional constraint that all values in the arrays @var{count}
5914 must lie between @var{start} and @var{end}, inclusive.
5916 Implementations denote recommended maximum amounts of vertex and index
5917 data, which may be queried by calling @code{glGet} with argument
5918 @code{GL_MAX_ELEMENTS_VERTICES} and @code{GL_MAX_ELEMENTS_INDICES}. If
5919 @r{@var{end}-@var{start}+1} is greater than the value of
5920 @code{GL_MAX_ELEMENTS_VERTICES}, or if @var{count} is greater than the
5921 value of @code{GL_MAX_ELEMENTS_INDICES}, then the call may operate at
5922 reduced performance. There is no requirement that all vertices in the
5923 range @r{[@var{start},@var{end}]} be referenced. However, the
5924 implementation may partially process unused vertices, reducing
5925 performance from what could be achieved with an optimal index set.
5927 When @code{glDrawRangeElements} is called, it uses @var{count}
5928 sequential elements from an enabled array, starting at @var{start} to
5929 construct a sequence of geometric primitives. @var{mode} specifies what
5930 kind of primitives are constructed, and how the array elements construct
5931 these primitives. If more than one array is enabled, each is used. If
5932 @code{GL_VERTEX_ARRAY} is not enabled, no geometric primitives are
5935 Vertex attributes that are modified by @code{glDrawRangeElements} have
5936 an unspecified value after @code{glDrawRangeElements} returns. For
5937 example, if @code{GL_COLOR_ARRAY} is enabled, the value of the current
5938 color is undefined after @code{glDrawRangeElements} executes. Attributes
5939 that aren't modified maintain their previous values.
5941 It is an error for indices to lie outside the range
5942 @r{[@var{start},@var{end}]}, but implementations may not check for this
5943 situation. Such indices cause implementation-dependent behavior.
5945 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
5948 @code{GL_INVALID_VALUE} is generated if @var{count} is negative.
5950 @code{GL_INVALID_VALUE} is generated if @r{@var{end}<@var{start}}.
5952 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5953 name is bound to an enabled array or the element array and the buffer
5954 object's data store is currently mapped.
5956 @code{GL_INVALID_OPERATION} is generated if @code{glDrawRangeElements}
5957 is executed between the execution of @code{glBegin} and the
5958 corresponding @code{glEnd}.
5962 @deftypefun void glEdgeFlagPointer stride pointer
5963 Define an array of edge flags.
5967 Specifies the byte offset between consecutive edge flags. If
5968 @var{stride} is 0, the edge flags are understood to be tightly packed in
5969 the array. The initial value is 0.
5972 Specifies a pointer to the first edge flag in the array. The initial
5977 @code{glEdgeFlagPointer} specifies the location and data format of an
5978 array of boolean edge flags to use when rendering. @var{stride}
5979 specifies the byte stride from one edge flag to the next, allowing
5980 vertices and attributes to be packed into a single array or stored in
5983 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
5984 target (see @code{glBindBuffer}) while an edge flag array is specified,
5985 @var{pointer} is treated as a byte offset into the buffer object's data
5986 store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING})
5987 is saved as edge flag vertex array client-side state
5988 (@code{GL_EDGE_FLAG_ARRAY_BUFFER_BINDING}).
5990 When an edge flag array is specified, @var{stride} and @var{pointer} are
5991 saved as client-side state, in addition to the current vertex array
5992 buffer object binding.
5994 To enable and disable the edge flag array, call
5995 @code{glEnableClientState} and @code{glDisableClientState} with the
5996 argument @code{GL_EDGE_FLAG_ARRAY}. If enabled, the edge flag array is
5997 used when @code{glDrawArrays}, @code{glMultiDrawArrays},
5998 @code{glDrawElements}, @code{glMultiDrawElements},
5999 @code{glDrawRangeElements}, or @code{glArrayElement} is called.
6001 @code{GL_INVALID_ENUM} is generated if @var{stride} is negative.
6005 @deftypefun void glEdgeFlag flag
6006 @deftypefunx void glEdgeFlagv flag
6007 Flag edges as either boundary or nonboundary.
6011 Specifies the current edge flag value, either @code{GL_TRUE} or
6012 @code{GL_FALSE}. The initial value is @code{GL_TRUE}.
6016 Each vertex of a polygon, separate triangle, or separate quadrilateral
6017 specified between a @code{glBegin}/@code{glEnd} pair is marked as the
6018 start of either a boundary or nonboundary edge. If the current edge flag
6019 is true when the vertex is specified, the vertex is marked as the start
6020 of a boundary edge. Otherwise, the vertex is marked as the start of a
6021 nonboundary edge. @code{glEdgeFlag} sets the edge flag bit to
6022 @code{GL_TRUE} if @var{flag} is @code{GL_TRUE} and to @code{GL_FALSE}
6025 The vertices of connected triangles and connected quadrilaterals are
6026 always marked as boundary, regardless of the value of the edge flag.
6028 Boundary and nonboundary edge flags on vertices are significant only if
6029 @code{GL_POLYGON_MODE} is set to @code{GL_POINT} or @code{GL_LINE}. See
6030 @code{glPolygonMode}.
6034 @deftypefun void glEnableClientState cap
6035 @deftypefunx void glDisableClientState cap
6036 Enable or disable client-side capability.
6040 Specifies the capability to enable. Symbolic constants
6041 @code{GL_COLOR_ARRAY}, @code{GL_EDGE_FLAG_ARRAY},
6042 @code{GL_FOG_COORD_ARRAY}, @code{GL_INDEX_ARRAY},
6043 @code{GL_NORMAL_ARRAY}, @code{GL_SECONDARY_COLOR_ARRAY},
6044 @code{GL_TEXTURE_COORD_ARRAY}, and @code{GL_VERTEX_ARRAY} are accepted.
6048 @code{glEnableClientState} and @code{glDisableClientState} enable or
6049 disable individual client-side capabilities. By default, all client-side
6050 capabilities are disabled. Both @code{glEnableClientState} and
6051 @code{glDisableClientState} take a single argument, @var{cap}, which can
6052 assume one of the following values:
6055 @item @code{GL_COLOR_ARRAY}
6056 If enabled, the color array is enabled for writing and used during
6057 rendering when @code{glArrayElement}, @code{glDrawArrays},
6058 @code{glDrawElements},
6059 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6060 @code{glMultiDrawElements} is called. See @code{glColorPointer}.
6062 @item @code{GL_EDGE_FLAG_ARRAY}
6063 If enabled, the edge flag array is enabled for writing and used during
6064 rendering when @code{glArrayElement}, @code{glDrawArrays},
6065 @code{glDrawElements},
6066 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6067 @code{glMultiDrawElements} is called. See @code{glEdgeFlagPointer}.
6069 @item @code{GL_FOG_COORD_ARRAY}
6070 If enabled, the fog coordinate array is enabled for writing and used
6071 during rendering when @code{glArrayElement}, @code{glDrawArrays},
6072 @code{glDrawElements},
6073 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6074 @code{glMultiDrawElements} is called. See @code{glFogCoordPointer}.
6076 @item @code{GL_INDEX_ARRAY}
6077 If enabled, the index array is enabled for writing and used during
6078 rendering when @code{glArrayElement}, @code{glDrawArrays},
6079 @code{glDrawElements},
6080 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6081 @code{glMultiDrawElements} is called. See @code{glIndexPointer}.
6083 @item @code{GL_NORMAL_ARRAY}
6084 If enabled, the normal array is enabled for writing and used during
6085 rendering when @code{glArrayElement}, @code{glDrawArrays},
6086 @code{glDrawElements},
6087 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6088 @code{glMultiDrawElements} is called. See @code{glNormalPointer}.
6090 @item @code{GL_SECONDARY_COLOR_ARRAY}
6091 If enabled, the secondary color array is enabled for writing and used
6092 during rendering when @code{glArrayElement}, @code{glDrawArrays},
6093 @code{glDrawElements},
6094 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6095 @code{glMultiDrawElements} is called. See @code{glColorPointer}.
6097 @item @code{GL_TEXTURE_COORD_ARRAY}
6098 If enabled, the texture coordinate array is enabled for writing and used
6099 during rendering when @code{glArrayElement}, @code{glDrawArrays},
6100 @code{glDrawElements},
6101 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6102 @code{glMultiDrawElements} is called. See @code{glTexCoordPointer}.
6104 @item @code{GL_VERTEX_ARRAY}
6105 If enabled, the vertex array is enabled for writing and used during
6106 rendering when @code{glArrayElement}, @code{glDrawArrays},
6107 @code{glDrawElements},
6108 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6109 @code{glMultiDrawElements} is called. See @code{glVertexPointer}.
6113 @code{GL_INVALID_ENUM} is generated if @var{cap} is not an accepted
6116 @code{glEnableClientState} is not allowed between the execution of
6117 @code{glBegin} and the corresponding @code{glEnd}, but an error may or
6118 may not be generated. If no error is generated, the behavior is
6123 @deftypefun void glEnableVertexAttribArray index
6124 @deftypefunx void glDisableVertexAttribArray index
6125 Enable or disable a generic vertex attribute array.
6129 Specifies the index of the generic vertex attribute to be enabled or
6134 @code{glEnableVertexAttribArray} enables the generic vertex attribute
6135 array specified by @var{index}. @code{glDisableVertexAttribArray}
6136 disables the generic vertex attribute array specified by @var{index}. By
6137 default, all client-side capabilities are disabled, including all
6138 generic vertex attribute arrays. If enabled, the values in the generic
6139 vertex attribute array will be accessed and used for rendering when
6140 calls are made to vertex array commands such as @code{glDrawArrays},
6141 @code{glDrawElements}, @code{glDrawRangeElements},
6142 @code{glArrayElement}, @code{glMultiDrawElements}, or
6143 @code{glMultiDrawArrays}.
6145 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
6146 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
6148 @code{GL_INVALID_OPERATION} is generated if either
6149 @code{glEnableVertexAttribArray } or @code{glDisableVertexAttribArray }
6150 is executed between the execution of @code{glBegin} and the
6151 corresponding execution of @code{glEnd}.
6155 @deftypefun void glEnable cap
6156 @deftypefunx void glDisable cap
6157 Enable or disable server-side GL capabilities.
6161 Specifies a symbolic constant indicating a GL capability.
6165 @code{glEnable} and @code{glDisable} enable and disable various
6166 capabilities. Use @code{glIsEnabled} or @code{glGet} to determine the
6167 current setting of any capability. The initial value for each capability
6168 with the exception of @code{GL_DITHER} and @code{GL_MULTISAMPLE} is
6169 @code{GL_FALSE}. The initial value for @code{GL_DITHER} and
6170 @code{GL_MULTISAMPLE} is @code{GL_TRUE}.
6172 Both @code{glEnable} and @code{glDisable} take a single argument,
6173 @var{cap}, which can assume one of the following values:
6176 @item @code{GL_ALPHA_TEST}
6179 If enabled, do alpha testing. See @code{glAlphaFunc}.
6181 @item @code{GL_AUTO_NORMAL}
6184 If enabled, generate normal vectors when either @code{GL_MAP2_VERTEX_3}
6185 or @code{GL_MAP2_VERTEX_4} is used to generate vertices. See
6188 @item @code{GL_BLEND}
6191 If enabled, blend the computed fragment color values with the values in
6192 the color buffers. See @code{glBlendFunc}.
6194 @item @code{GL_CLIP_PLANE}@var{i}
6197 If enabled, clip geometry against user-defined clipping plane @var{i}.
6198 See @code{glClipPlane}.
6200 @item @code{GL_COLOR_LOGIC_OP}
6203 If enabled, apply the currently selected logical operation to the
6204 computed fragment color and color buffer values. See @code{glLogicOp}.
6206 @item @code{GL_COLOR_MATERIAL}
6209 If enabled, have one or more material parameters track the current
6210 color. See @code{glColorMaterial}.
6212 @item @code{GL_COLOR_SUM}
6215 If enabled and no fragment shader is active, add the secondary color
6216 value to the computed fragment color. See @code{glSecondaryColor}.
6218 @item @code{GL_COLOR_TABLE}
6221 If enabled, perform a color table lookup on the incoming RGBA color
6222 values. See @code{glColorTable}.
6224 @item @code{GL_CONVOLUTION_1D}
6227 If enabled, perform a 1D convolution operation on incoming RGBA color
6228 values. See @code{glConvolutionFilter1D}.
6230 @item @code{GL_CONVOLUTION_2D}
6233 If enabled, perform a 2D convolution operation on incoming RGBA color
6234 values. See @code{glConvolutionFilter2D}.
6236 @item @code{GL_CULL_FACE}
6239 If enabled, cull polygons based on their winding in window coordinates.
6240 See @code{glCullFace}.
6242 @item @code{GL_DEPTH_TEST}
6245 If enabled, do depth comparisons and update the depth buffer. Note that
6246 even if the depth buffer exists and the depth mask is non-zero, the
6247 depth buffer is not updated if the depth test is disabled. See
6248 @code{glDepthFunc} and @code{glDepthRange}.
6250 @item @code{GL_DITHER}
6253 If enabled, dither color components or indices before they are written
6254 to the color buffer.
6259 If enabled and no fragment shader is active, blend a fog color into the
6260 post-texturing color. See @code{glFog}.
6262 @item @code{GL_HISTOGRAM}
6265 If enabled, histogram incoming RGBA color values. See
6268 @item @code{GL_INDEX_LOGIC_OP}
6271 If enabled, apply the currently selected logical operation to the
6272 incoming index and color buffer indices. See @code{glLogicOp}.
6274 @item @code{GL_LIGHT}@var{i}
6277 If enabled, include light @var{i} in the evaluation of the lighting
6278 equation. See @code{glLightModel} and @code{glLight}.
6280 @item @code{GL_LIGHTING}
6283 If enabled and no vertex shader is active, use the current lighting
6284 parameters to compute the vertex color or index. Otherwise, simply
6285 associate the current color or index with each vertex. See
6286 @code{glMaterial}, @code{glLightModel}, and @code{glLight}.
6288 @item @code{GL_LINE_SMOOTH}
6291 If enabled, draw lines with correct filtering. Otherwise, draw aliased
6292 lines. See @code{glLineWidth}.
6294 @item @code{GL_LINE_STIPPLE}
6297 If enabled, use the current line stipple pattern when drawing lines. See
6298 @code{glLineStipple}.
6300 @item @code{GL_MAP1_COLOR_4}
6303 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6304 @code{glEvalPoint1} generate RGBA values. See @code{glMap1}.
6306 @item @code{GL_MAP1_INDEX}
6309 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6310 @code{glEvalPoint1} generate color indices. See @code{glMap1}.
6312 @item @code{GL_MAP1_NORMAL}
6315 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6316 @code{glEvalPoint1} generate normals. See @code{glMap1}.
6318 @item @code{GL_MAP1_TEXTURE_COORD_1}
6321 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6322 @code{glEvalPoint1} generate @var{s} texture coordinates. See
6325 @item @code{GL_MAP1_TEXTURE_COORD_2}
6328 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6329 @code{glEvalPoint1} generate @var{s} and @var{t} texture coordinates.
6332 @item @code{GL_MAP1_TEXTURE_COORD_3}
6335 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6336 @code{glEvalPoint1} generate @var{s}, @var{t}, and @var{r} texture
6337 coordinates. See @code{glMap1}.
6339 @item @code{GL_MAP1_TEXTURE_COORD_4}
6342 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6343 @code{glEvalPoint1} generate @var{s}, @var{t}, @var{r}, and @var{q}
6344 texture coordinates. See @code{glMap1}.
6346 @item @code{GL_MAP1_VERTEX_3}
6349 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6350 @code{glEvalPoint1} generate @var{x}, @var{y}, and @var{z} vertex
6351 coordinates. See @code{glMap1}.
6353 @item @code{GL_MAP1_VERTEX_4}
6356 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6357 @code{glEvalPoint1} generate homogeneous @var{x}, @var{y}, @var{z}, and
6358 @var{w} vertex coordinates. See @code{glMap1}.
6360 @item @code{GL_MAP2_COLOR_4}
6363 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6364 @code{glEvalPoint2} generate RGBA values. See @code{glMap2}.
6366 @item @code{GL_MAP2_INDEX}
6369 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6370 @code{glEvalPoint2} generate color indices. See @code{glMap2}.
6372 @item @code{GL_MAP2_NORMAL}
6375 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6376 @code{glEvalPoint2} generate normals. See @code{glMap2}.
6378 @item @code{GL_MAP2_TEXTURE_COORD_1}
6381 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6382 @code{glEvalPoint2} generate @var{s} texture coordinates. See
6385 @item @code{GL_MAP2_TEXTURE_COORD_2}
6388 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6389 @code{glEvalPoint2} generate @var{s} and @var{t} texture coordinates.
6392 @item @code{GL_MAP2_TEXTURE_COORD_3}
6395 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6396 @code{glEvalPoint2} generate @var{s}, @var{t}, and @var{r} texture
6397 coordinates. See @code{glMap2}.
6399 @item @code{GL_MAP2_TEXTURE_COORD_4}
6402 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6403 @code{glEvalPoint2} generate @var{s}, @var{t}, @var{r}, and @var{q}
6404 texture coordinates. See @code{glMap2}.
6406 @item @code{GL_MAP2_VERTEX_3}
6409 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6410 @code{glEvalPoint2} generate @var{x}, @var{y}, and @var{z} vertex
6411 coordinates. See @code{glMap2}.
6413 @item @code{GL_MAP2_VERTEX_4}
6416 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6417 @code{glEvalPoint2} generate homogeneous @var{x}, @var{y}, @var{z}, and
6418 @var{w} vertex coordinates. See @code{glMap2}.
6420 @item @code{GL_MINMAX}
6423 If enabled, compute the minimum and maximum values of incoming RGBA
6424 color values. See @code{glMinmax}.
6426 @item @code{GL_MULTISAMPLE}
6429 If enabled, use multiple fragment samples in computing the final color
6430 of a pixel. See @code{glSampleCoverage}.
6432 @item @code{GL_NORMALIZE}
6435 If enabled and no vertex shader is active, normal vectors are normalized
6436 to unit length after transformation and before lighting. This method is
6437 generally less efficient than @code{GL_RESCALE_NORMAL}. See
6438 @code{glNormal} and @code{glNormalPointer}.
6440 @item @code{GL_POINT_SMOOTH}
6443 If enabled, draw points with proper filtering. Otherwise, draw aliased
6444 points. See @code{glPointSize}.
6446 @item @code{GL_POINT_SPRITE}
6449 If enabled, calculate texture coordinates for points based on texture
6450 environment and point parameter settings. Otherwise texture coordinates
6451 are constant across points.
6453 @item @code{GL_POLYGON_OFFSET_FILL}
6456 If enabled, and if the polygon is rendered in @code{GL_FILL} mode, an
6457 offset is added to depth values of a polygon's fragments before the
6458 depth comparison is performed. See @code{glPolygonOffset}.
6460 @item @code{GL_POLYGON_OFFSET_LINE}
6463 If enabled, and if the polygon is rendered in @code{GL_LINE} mode, an
6464 offset is added to depth values of a polygon's fragments before the
6465 depth comparison is performed. See @code{glPolygonOffset}.
6467 @item @code{GL_POLYGON_OFFSET_POINT}
6470 If enabled, an offset is added to depth values of a polygon's fragments
6471 before the depth comparison is performed, if the polygon is rendered in
6472 @code{GL_POINT} mode. See @code{glPolygonOffset}.
6474 @item @code{GL_POLYGON_SMOOTH}
6477 If enabled, draw polygons with proper filtering. Otherwise, draw aliased
6478 polygons. For correct antialiased polygons, an alpha buffer is needed
6479 and the polygons must be sorted front to back.
6481 @item @code{GL_POLYGON_STIPPLE}
6484 If enabled, use the current polygon stipple pattern when rendering
6485 polygons. See @code{glPolygonStipple}.
6487 @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}
6490 If enabled, perform a color table lookup on RGBA color values after
6491 color matrix transformation. See @code{glColorTable}.
6493 @item @code{GL_POST_CONVOLUTION_COLOR_TABLE}
6496 If enabled, perform a color table lookup on RGBA color values after
6497 convolution. See @code{glColorTable}.
6499 @item @code{GL_RESCALE_NORMAL}
6502 If enabled and no vertex shader is active, normal vectors are scaled
6503 after transformation and before lighting by a factor computed from the
6504 modelview matrix. If the modelview matrix scales space uniformly, this
6505 has the effect of restoring the transformed normal to unit length. This
6506 method is generally more efficient than @code{GL_NORMALIZE}. See
6507 @code{glNormal} and @code{glNormalPointer}.
6509 @item @code{GL_SAMPLE_ALPHA_TO_COVERAGE}
6512 If enabled, compute a temporary coverage value where each bit is
6513 determined by the alpha value at the corresponding sample location. The
6514 temporary coverage value is then ANDed with the fragment coverage value.
6516 @item @code{GL_SAMPLE_ALPHA_TO_ONE}
6519 If enabled, each sample alpha value is replaced by the maximum
6520 representable alpha value.
6522 @item @code{GL_SAMPLE_COVERAGE}
6525 If enabled, the fragment's coverage is ANDed with the temporary coverage
6526 value. If @code{GL_SAMPLE_COVERAGE_INVERT} is set to @code{GL_TRUE},
6527 invert the coverage value. See @code{glSampleCoverage}.
6529 @item @code{GL_SEPARABLE_2D}
6532 If enabled, perform a two-dimensional convolution operation using a
6533 separable convolution filter on incoming RGBA color values. See
6534 @code{glSeparableFilter2D}.
6536 @item @code{GL_SCISSOR_TEST}
6539 If enabled, discard fragments that are outside the scissor rectangle.
6540 See @code{glScissor}.
6542 @item @code{GL_STENCIL_TEST}
6545 If enabled, do stencil testing and update the stencil buffer. See
6546 @code{glStencilFunc} and @code{glStencilOp}.
6548 @item @code{GL_TEXTURE_1D}
6551 If enabled and no fragment shader is active, one-dimensional texturing
6552 is performed (unless two- or three-dimensional or cube-mapped texturing
6553 is also enabled). See @code{glTexImage1D}.
6555 @item @code{GL_TEXTURE_2D}
6558 If enabled and no fragment shader is active, two-dimensional texturing
6559 is performed (unless three-dimensional or cube-mapped texturing is also
6560 enabled). See @code{glTexImage2D}.
6562 @item @code{GL_TEXTURE_3D}
6565 If enabled and no fragment shader is active, three-dimensional texturing
6566 is performed (unless cube-mapped texturing is also enabled). See
6567 @code{glTexImage3D}.
6569 @item @code{GL_TEXTURE_CUBE_MAP}
6572 If enabled and no fragment shader is active, cube-mapped texturing is
6573 performed. See @code{glTexImage2D}.
6575 @item @code{GL_TEXTURE_GEN_Q}
6578 If enabled and no vertex shader is active, the @var{q} texture
6579 coordinate is computed using the texture generation function defined
6580 with @code{glTexGen}. Otherwise, the current @var{q} texture coordinate
6581 is used. See @code{glTexGen}.
6583 @item @code{GL_TEXTURE_GEN_R}
6586 If enabled and no vertex shader is active, the @var{r} texture
6587 coordinate is computed using the texture generation function defined
6588 with @code{glTexGen}. Otherwise, the current @var{r} texture coordinate
6589 is used. See @code{glTexGen}.
6591 @item @code{GL_TEXTURE_GEN_S}
6594 If enabled and no vertex shader is active, the @var{s} texture
6595 coordinate is computed using the texture generation function defined
6596 with @code{glTexGen}. Otherwise, the current @var{s} texture coordinate
6597 is used. See @code{glTexGen}.
6599 @item @code{GL_TEXTURE_GEN_T}
6602 If enabled and no vertex shader is active, the @var{t} texture
6603 coordinate is computed using the texture generation function defined
6604 with @code{glTexGen}. Otherwise, the current @var{t} texture coordinate
6605 is used. See @code{glTexGen}.
6607 @item @code{GL_VERTEX_PROGRAM_POINT_SIZE}
6610 If enabled and a vertex shader is active, then the derived point size is
6611 taken from the (potentially clipped) shader builtin @code{gl_PointSize}
6612 and clamped to the implementation-dependent point size range.
6614 @item @code{GL_VERTEX_PROGRAM_TWO_SIDE}
6617 If enabled and a vertex shader is active, it specifies that the GL will
6618 choose between front and back colors based on the polygon's face
6619 direction of which the vertex being shaded is a part. It has no effect
6624 @code{GL_INVALID_ENUM} is generated if @var{cap} is not one of the
6625 values listed previously.
6627 @code{GL_INVALID_OPERATION} is generated if @code{glEnable} or
6628 @code{glDisable} is executed between the execution of @code{glBegin} and
6629 the corresponding execution of @code{glEnd}.
6633 @deftypefun void glEvalCoord1f u
6634 @deftypefunx void glEvalCoord1d u
6635 @deftypefunx void glEvalCoord2f u v
6636 @deftypefunx void glEvalCoord2d u v
6637 @deftypefunx void glEvalCoord1fv u
6638 @deftypefunx void glEvalCoord1dv u
6639 @deftypefunx void glEvalCoord2fv u
6640 @deftypefunx void glEvalCoord2dv u
6641 Evaluate enabled one- and two-dimensional maps.
6645 Specifies a value that is the domain coordinate @r{@var{u}} to the basis
6646 function defined in a previous @code{glMap1} or @code{glMap2} command.
6649 Specifies a value that is the domain coordinate @r{@var{v}} to the basis
6650 function defined in a previous @code{glMap2} command. This argument is
6651 not present in a @code{glEvalCoord1} command.
6655 @code{glEvalCoord1} evaluates enabled one-dimensional maps at argument
6656 @var{u}. @code{glEvalCoord2} does the same for two-dimensional maps
6657 using two domain values, @var{u} and @var{v}. To define a map, call
6658 @code{glMap1} and @code{glMap2}; to enable and disable it, call
6659 @code{glEnable} and @code{glDisable}.
6661 When one of the @code{glEvalCoord} commands is issued, all currently
6662 enabled maps of the indicated dimension are evaluated. Then, for each
6663 enabled map, it is as if the corresponding GL command had been issued
6664 with the computed value. That is, if @code{GL_MAP1_INDEX} or
6665 @code{GL_MAP2_INDEX} is enabled, a @code{glIndex} command is simulated.
6666 If @code{GL_MAP1_COLOR_4} or @code{GL_MAP2_COLOR_4} is enabled, a
6667 @code{glColor} command is simulated. If @code{GL_MAP1_NORMAL} or
6668 @code{GL_MAP2_NORMAL} is enabled, a normal vector is produced, and if
6669 any of @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2},
6670 @code{GL_MAP1_TEXTURE_COORD_3}, @code{GL_MAP1_TEXTURE_COORD_4},
6671 @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2},
6672 @code{GL_MAP2_TEXTURE_COORD_3}, or @code{GL_MAP2_TEXTURE_COORD_4} is
6673 enabled, then an appropriate @code{glTexCoord} command is simulated.
6675 For color, color index, normal, and texture coordinates the GL uses
6676 evaluated values instead of current values for those evaluations that
6677 are enabled, and current values otherwise, However, the evaluated values
6678 do not update the current values. Thus, if @code{glVertex} commands are
6679 interspersed with @code{glEvalCoord} commands, the color, normal, and
6680 texture coordinates associated with the @code{glVertex} commands are not
6681 affected by the values generated by the @code{glEvalCoord} commands, but
6682 only by the most recent @code{glColor}, @code{glIndex}, @code{glNormal},
6683 and @code{glTexCoord} commands.
6685 No commands are issued for maps that are not enabled. If more than one
6686 texture evaluation is enabled for a particular dimension (for example,
6687 @code{GL_MAP2_TEXTURE_COORD_1} and @code{GL_MAP2_TEXTURE_COORD_2}), then
6688 only the evaluation of the map that produces the larger number of
6689 coordinates (in this case, @code{GL_MAP2_TEXTURE_COORD_2}) is carried
6690 out. @code{GL_MAP1_VERTEX_4} overrides @code{GL_MAP1_VERTEX_3}, and
6691 @code{GL_MAP2_VERTEX_4} overrides @code{GL_MAP2_VERTEX_3}, in the same
6692 manner. If neither a three- nor a four-component vertex map is enabled
6693 for the specified dimension, the @code{glEvalCoord} command is ignored.
6695 If you have enabled automatic normal generation, by calling
6696 @code{glEnable} with argument @code{GL_AUTO_NORMAL}, @code{glEvalCoord2}
6697 generates surface normals analytically, regardless of the contents or
6698 enabling of the @code{GL_MAP2_NORMAL} map. Let
6700 @r{@code{m}=∂@code{p},/∂@var{u},,×∂@code{p},/∂@var{v},,}
6702 Then the generated normal @r{@code{n}} is
6703 @r{@code{n}=@code{m}/∥@code{m},∥,}
6705 If automatic normal generation is disabled, the corresponding normal map
6706 @code{GL_MAP2_NORMAL}, if enabled, is used to produce a normal. If
6707 neither automatic normal generation nor a normal map is enabled, no
6708 normal is generated for @code{glEvalCoord2} commands.
6712 @deftypefun void glEvalMesh1 mode i1 i2
6713 @deftypefunx void glEvalMesh2 mode i1 i2 j1 j2
6714 Compute a one- or two-dimensional grid of points or lines.
6718 In @code{glEvalMesh1}, specifies whether to compute a one-dimensional
6719 mesh of points or lines. Symbolic constants @code{GL_POINT} and
6720 @code{GL_LINE} are accepted.
6724 Specify the first and last integer values for grid domain variable
6729 @code{glMapGrid} and @code{glEvalMesh} are used in tandem to efficiently
6730 generate and evaluate a series of evenly-spaced map domain values.
6731 @code{glEvalMesh} steps through the integer domain of a one- or
6732 two-dimensional grid, whose range is the domain of the evaluation maps
6733 specified by @code{glMap1} and @code{glMap2}. @var{mode} determines
6734 whether the resulting vertices are connected as points, lines, or filled
6737 In the one-dimensional case, @code{glEvalMesh1}, the mesh is generated
6738 as if the following code fragment were executed:
6744 glBegin( @var{type} );
6745 for ( i = @var{i1}; i <= @var{i2}; i += 1 )
6746 glEvalCoord1( @r{i·Δ@var{u}+@var{u}_1} );
6750 @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}
6752 and @r{@var{n}}, @r{@var{u}_1}, and @r{@var{u}_2} are the arguments to
6753 the most recent @code{glMapGrid1} command. @var{type} is
6754 @code{GL_POINTS} if @var{mode} is @code{GL_POINT}, or @code{GL_LINES} if
6755 @var{mode} is @code{GL_LINE}.
6757 The one absolute numeric requirement is that if @r{@var{i}=@var{n}},
6758 then the value computed from @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly
6761 In the two-dimensional case, @code{glEvalMesh2}, let .cp
6762 @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}
6764 @r{Δ@var{v}=(@var{v}_2-@var{v}_1,)/@var{m}}
6766 where @r{@var{n}}, @r{@var{u}_1}, @r{@var{u}_2}, @r{@var{m}},
6767 @r{@var{v}_1}, and @r{@var{v}_2} are the arguments to the most recent
6768 @code{glMapGrid2} command. Then, if @var{mode} is @code{GL_FILL}, the
6769 @code{glEvalMesh2} command is equivalent to:
6775 for ( j = @var{j1}; j < @var{j2}; j += 1 ) @{
6776 glBegin( GL_QUAD_STRIP );
6777 for ( i = @var{i1}; i <= @var{i2}; i += 1 ) @{
6778 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6779 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,(j+1,)·Δ@var{v}+@var{v}_1} );
6785 If @var{mode} is @code{GL_LINE}, then a call to @code{glEvalMesh2} is
6792 for ( j = @var{j1}; j <= @var{j2}; j += 1 ) @{
6793 glBegin( GL_LINE_STRIP );
6794 for ( i = @var{i1}; i <= @var{i2}; i += 1 )
6795 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6799 for ( i = @var{i1}; i <= @var{i2}; i += 1 ) @{
6800 glBegin( GL_LINE_STRIP );
6801 for ( j = @var{j1}; j <= @var{j1}; j += 1 )
6802 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6807 And finally, if @var{mode} is @code{GL_POINT}, then a call to
6808 @code{glEvalMesh2} is equivalent to:
6814 glBegin( GL_POINTS );
6815 for ( j = @var{j1}; j <= @var{j2}; j += 1 )
6816 for ( i = @var{i1}; i <= @var{i2}; i += 1 )
6817 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6821 In all three cases, the only absolute numeric requirements are that if
6822 @r{@var{i}=@var{n}}, then the value computed from
6823 @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}, and if
6824 @r{@var{j}=@var{m}}, then the value computed from
6825 @r{@var{j}·Δ@var{v}+@var{v}_1} is exactly @r{@var{v}_2}.
6827 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
6830 @code{GL_INVALID_OPERATION} is generated if @code{glEvalMesh} is
6831 executed between the execution of @code{glBegin} and the corresponding
6832 execution of @code{glEnd}.
6836 @deftypefun void glEvalPoint1 i
6837 @deftypefunx void glEvalPoint2 i j
6838 Generate and evaluate a single point in a mesh.
6842 Specifies the integer value for grid domain variable @r{@var{i}}.
6845 Specifies the integer value for grid domain variable @r{@var{j}}
6846 (@code{glEvalPoint2} only).
6850 @code{glMapGrid} and @code{glEvalMesh} are used in tandem to efficiently
6851 generate and evaluate a series of evenly spaced map domain values.
6852 @code{glEvalPoint} can be used to evaluate a single grid point in the
6853 same gridspace that is traversed by @code{glEvalMesh}. Calling
6854 @code{glEvalPoint1} is equivalent to calling where
6855 @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}
6859 glEvalCoord1( @r{i·Δ@var{u}+@var{u}_1} );
6862 and @r{@var{n}}, @r{@var{u}_1}, and @r{@var{u}_2} are the arguments to
6863 the most recent @code{glMapGrid1} command. The one absolute numeric
6864 requirement is that if @r{@var{i}=@var{n}}, then the value computed from
6865 @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}.
6867 In the two-dimensional case, @code{glEvalPoint2}, let
6869 @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}@r{Δ@var{v}=(@var{v}_2-@var{v}_1,)/@var{m}}
6871 where @r{@var{n}}, @r{@var{u}_1}, @r{@var{u}_2}, @r{@var{m}},
6872 @r{@var{v}_1}, and @r{@var{v}_2} are the arguments to the most recent
6873 @code{glMapGrid2} command. Then the @code{glEvalPoint2} command is
6874 equivalent to calling The only absolute numeric requirements are that if
6875 @r{@var{i}=@var{n}}, then the value computed from
6876 @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}, and if
6877 @r{@var{j}=@var{m}}, then the value computed from
6878 @r{@var{j}·Δ@var{v}+@var{v}_1} is exactly @r{@var{v}_2}.
6882 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6887 @deftypefun void glFeedbackBuffer size type buffer
6888 Controls feedback mode.
6892 Specifies the maximum number of values that can be written into
6896 Specifies a symbolic constant that describes the information that will
6897 be returned for each vertex. @code{GL_2D}, @code{GL_3D},
6898 @code{GL_3D_COLOR}, @code{GL_3D_COLOR_TEXTURE}, and
6899 @code{GL_4D_COLOR_TEXTURE} are accepted.
6902 Returns the feedback data.
6906 The @code{glFeedbackBuffer} function controls feedback. Feedback, like
6907 selection, is a GL mode. The mode is selected by calling
6908 @code{glRenderMode} with @code{GL_FEEDBACK}. When the GL is in feedback
6909 mode, no pixels are produced by rasterization. Instead, information
6910 about primitives that would have been rasterized is fed back to the
6911 application using the GL.
6913 @code{glFeedbackBuffer} has three arguments: @var{buffer} is a pointer
6914 to an array of floating-point values into which feedback information is
6915 placed. @var{size} indicates the size of the array. @var{type} is a
6916 symbolic constant describing the information that is fed back for each
6917 vertex. @code{glFeedbackBuffer} must be issued before feedback mode is
6918 enabled (by calling @code{glRenderMode} with argument
6919 @code{GL_FEEDBACK}). Setting @code{GL_FEEDBACK} without establishing the
6920 feedback buffer, or calling @code{glFeedbackBuffer} while the GL is in
6921 feedback mode, is an error.
6923 When @code{glRenderMode} is called while in feedback mode, it returns
6924 the number of entries placed in the feedback array and resets the
6925 feedback array pointer to the base of the feedback buffer. The returned
6926 value never exceeds @var{size}. If the feedback data required more room
6927 than was available in @var{buffer}, @code{glRenderMode} returns a
6928 negative value. To take the GL out of feedback mode, call
6929 @code{glRenderMode} with a parameter value other than
6932 While in feedback mode, each primitive, bitmap, or pixel rectangle that
6933 would be rasterized generates a block of values that are copied into the
6934 feedback array. If doing so would cause the number of entries to exceed
6935 the maximum, the block is partially written so as to fill the array (if
6936 there is any room left at all), and an overflow flag is set. Each block
6937 begins with a code indicating the primitive type, followed by values
6938 that describe the primitive's vertices and associated data. Entries are
6939 also written for bitmaps and pixel rectangles. Feedback occurs after
6940 polygon culling and @code{glPolygonMode} interpretation of polygons has
6941 taken place, so polygons that are culled are not returned in the
6942 feedback buffer. It can also occur after polygons with more than three
6943 edges are broken up into triangles, if the GL implementation renders
6944 polygons by performing this decomposition.
6946 The @code{glPassThrough} command can be used to insert a marker into the
6947 feedback buffer. See @code{glPassThrough}.
6949 Following is the grammar for the blocks of values written into the
6950 feedback buffer. Each primitive is indicated with a unique identifying
6951 value followed by some number of vertices. Polygon entries include an
6952 integer value indicating how many vertices follow. A vertex is fed back
6953 as some number of floating-point values, as determined by @var{type}.
6954 Colors are fed back as four values in RGBA mode and one value in color
6957 feedbackList @r{←} feedbackItem feedbackList | feedbackItem feedbackItem
6958 @r{←} point | lineSegment | polygon | bitmap | pixelRectangle | passThru
6959 point @r{←}@code{GL_POINT_TOKEN} vertex lineSegment
6960 @r{←}@code{GL_LINE_TOKEN} vertex vertex | @code{GL_LINE_RESET_TOKEN}
6961 vertex vertex polygon @r{←}@code{GL_POLYGON_TOKEN} n polySpec polySpec
6962 @r{←} polySpec vertex | vertex vertex vertex bitmap
6963 @r{←}@code{GL_BITMAP_TOKEN} vertex pixelRectangle
6964 @r{←}@code{GL_DRAW_PIXEL_TOKEN} vertex | @code{GL_COPY_PIXEL_TOKEN}
6965 vertex passThru @r{←}@code{GL_PASS_THROUGH_TOKEN} value vertex @r{←} 2d
6966 | 3d | 3dColor | 3dColorTexture | 4dColorTexture 2d @r{←} value value 3d
6967 @r{←} value value value 3dColor @r{←} value value value color
6968 3dColorTexture @r{←} value value value color tex 4dColorTexture @r{←}
6969 value value value value color tex color @r{←} rgba | index rgba @r{←}
6970 value value value value index @r{←} value tex @r{←} value value value
6973 @var{value} is a floating-point number, and @var{n} is a floating-point
6974 integer giving the number of vertices in the polygon.
6975 @code{GL_POINT_TOKEN}, @code{GL_LINE_TOKEN}, @code{GL_LINE_RESET_TOKEN},
6976 @code{GL_POLYGON_TOKEN}, @code{GL_BITMAP_TOKEN},
6977 @code{GL_DRAW_PIXEL_TOKEN}, @code{GL_COPY_PIXEL_TOKEN} and
6978 @code{GL_PASS_THROUGH_TOKEN} are symbolic floating-point constants.
6979 @code{GL_LINE_RESET_TOKEN} is returned whenever the line stipple pattern
6980 is reset. The data returned as a vertex depends on the feedback
6983 The following table gives the correspondence between @var{type} and the
6984 number of values per vertex. @var{k} is 1 in color index mode and 4 in
6991 @strong{Coordinates}, @strong{Color}, @strong{Texture}, @strong{Total
6995 @var{x}, @var{y}, , , 2
6998 @var{x}, @var{y}, @var{z}, , , 3
7000 @item @code{GL_3D_COLOR}
7001 @var{x}, @var{y}, @var{z}, @r{@var{k}}, , @r{3+@var{k}}
7003 @item @code{GL_3D_COLOR_TEXTURE}
7004 @var{x}, @var{y}, @var{z}, @r{@var{k}}, 4 , @r{7+@var{k}}
7006 @item @code{GL_4D_COLOR_TEXTURE}
7007 @var{x}, @var{y}, @var{z}, @var{w}, @r{@var{k}}, 4 , @r{8+@var{k}}
7011 Feedback vertex coordinates are in window coordinates, except @var{w},
7012 which is in clip coordinates. Feedback colors are lighted, if lighting
7013 is enabled. Feedback texture coordinates are generated, if texture
7014 coordinate generation is enabled. They are always transformed by the
7017 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
7020 @code{GL_INVALID_VALUE} is generated if @var{size} is negative.
7022 @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is
7023 called while the render mode is @code{GL_FEEDBACK}, or if
7024 @code{glRenderMode} is called with argument @code{GL_FEEDBACK} before
7025 @code{glFeedbackBuffer} is called at least once.
7027 @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is
7028 executed between the execution of @code{glBegin} and the corresponding
7029 execution of @code{glEnd}.
7033 @deftypefun void glFinish
7034 Block until all GL execution is complete.
7036 @code{glFinish} does not return until the effects of all previously
7037 called GL commands are complete. Such effects include all changes to GL
7038 state, all changes to connection state, and all changes to the frame
7041 @code{GL_INVALID_OPERATION} is generated if @code{glFinish} is executed
7042 between the execution of @code{glBegin} and the corresponding execution
7047 @deftypefun void glFlush
7048 Force execution of GL commands in finite time.
7050 Different GL implementations buffer commands in several different
7051 locations, including network buffers and the graphics accelerator
7052 itself. @code{glFlush} empties all of these buffers, causing all issued
7053 commands to be executed as quickly as they are accepted by the actual
7054 rendering engine. Though this execution may not be completed in any
7055 particular time period, it does complete in finite time.
7057 Because any GL program might be executed over a network, or on an
7058 accelerator that buffers commands, all programs should call
7059 @code{glFlush} whenever they count on having all of their previously
7060 issued commands completed. For example, call @code{glFlush} before
7061 waiting for user input that depends on the generated image.
7063 @code{GL_INVALID_OPERATION} is generated if @code{glFlush} is executed
7064 between the execution of @code{glBegin} and the corresponding execution
7069 @deftypefun void glFogCoordPointer type stride pointer
7070 Define an array of fog coordinates.
7074 Specifies the data type of each fog coordinate. Symbolic constants
7075 @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is
7079 Specifies the byte offset between consecutive fog coordinates. If
7080 @var{stride} is 0, the array elements are understood to be tightly
7081 packed. The initial value is 0.
7084 Specifies a pointer to the first coordinate of the first fog coordinate
7085 in the array. The initial value is 0.
7089 @code{glFogCoordPointer} specifies the location and data format of an
7090 array of fog coordinates to use when rendering. @var{type} specifies the
7091 data type of each fog coordinate, and @var{stride} specifies the byte
7092 stride from one fog coordinate to the next, allowing vertices and
7093 attributes to be packed into a single array or stored in separate
7096 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
7097 target (see @code{glBindBuffer}) while a fog coordinate array is
7098 specified, @var{pointer} is treated as a byte offset into the buffer
7099 object's data store. Also, the buffer object binding
7100 (@code{GL_ARRAY_BUFFER_BINDING}) is saved as fog coordinate vertex array
7101 client-side state (@code{GL_FOG_COORD_ARRAY_BUFFER_BINDING}).
7103 When a fog coordinate array is specified, @var{type}, @var{stride}, and
7104 @var{pointer} are saved as client-side state, in addition to the current
7105 vertex array buffer object binding.
7107 To enable and disable the fog coordinate array, call
7108 @code{glEnableClientState} and @code{glDisableClientState} with the
7109 argument @code{GL_FOG_COORD_ARRAY}. If enabled, the fog coordinate array
7110 is used when @code{glDrawArrays}, @code{glMultiDrawArrays},
7111 @code{glDrawElements}, @code{glMultiDrawElements},
7112 @code{glDrawRangeElements}, or @code{glArrayElement} is called.
7114 @code{GL_INVALID_ENUM} is generated if @var{type} is not either
7115 @code{GL_FLOAT} or @code{GL_DOUBLE}.
7117 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
7121 @deftypefun void glFogCoordd coord
7122 @deftypefunx void glFogCoordf coord
7123 @deftypefunx void glFogCoorddv coord
7124 @deftypefunx void glFogCoordfv coord
7125 Set the current fog coordinates.
7129 Specify the fog distance.
7133 @code{glFogCoord} specifies the fog coordinate that is associated with
7134 each vertex and the current raster position. The value specified is
7135 interpolated and used in computing the fog color (see @code{glFog}).
7139 @deftypefun void glFogf pname param
7140 @deftypefunx void glFogi pname param
7141 @deftypefunx void glFogfv pname params
7142 @deftypefunx void glFogiv pname params
7143 Specify fog parameters.
7147 Specifies a single-valued fog parameter. @code{GL_FOG_MODE},
7148 @code{GL_FOG_DENSITY}, @code{GL_FOG_START}, @code{GL_FOG_END},
7149 @code{GL_FOG_INDEX}, and @code{GL_FOG_COORD_SRC} are accepted.
7152 Specifies the value that @var{pname} will be set to.
7156 Fog is initially disabled. While enabled, fog affects rasterized
7157 geometry, bitmaps, and pixel blocks, but not buffer clear operations. To
7158 enable and disable fog, call @code{glEnable} and @code{glDisable} with
7159 argument @code{GL_FOG}.
7161 @code{glFog} assigns the value or values in @var{params} to the fog
7162 parameter specified by @var{pname}. The following values are accepted
7166 @item @code{GL_FOG_MODE}
7167 @var{params} is a single integer or floating-point value that specifies
7168 the equation to be used to compute the fog blend factor, @r{@var{f}}.
7169 Three symbolic constants are accepted: @code{GL_LINEAR}, @code{GL_EXP},
7170 and @code{GL_EXP2}. The equations corresponding to these symbolic
7171 constants are defined below. The initial fog mode is @code{GL_EXP}.
7173 @item @code{GL_FOG_DENSITY}
7174 @var{params} is a single integer or floating-point value that specifies
7175 @r{@var{density}}, the fog density used in both exponential fog
7176 equations. Only nonnegative densities are accepted. The initial fog
7179 @item @code{GL_FOG_START}
7180 @var{params} is a single integer or floating-point value that specifies
7181 @r{@var{start}}, the near distance used in the linear fog equation. The
7182 initial near distance is 0.
7184 @item @code{GL_FOG_END}
7185 @var{params} is a single integer or floating-point value that specifies
7186 @r{@var{end}}, the far distance used in the linear fog equation. The
7187 initial far distance is 1.
7189 @item @code{GL_FOG_INDEX}
7190 @var{params} is a single integer or floating-point value that specifies
7191 @r{@var{i}_@var{f}}, the fog color index. The initial fog index is 0.
7193 @item @code{GL_FOG_COLOR}
7194 @var{params} contains four integer or floating-point values that specify
7195 @r{@var{C}_@var{f}}, the fog color. Integer values are mapped linearly
7196 such that the most positive representable value maps to 1.0, and the
7197 most negative representable value maps to @r{-1.0}. Floating-point
7198 values are mapped directly. After conversion, all color components are
7199 clamped to the range @r{[0,1]}. The initial fog color is (0, 0, 0, 0).
7201 @item @code{GL_FOG_COORD_SRC}
7202 @var{params} contains either of the following symbolic constants:
7203 @code{GL_FOG_COORD} or @code{GL_FRAGMENT_DEPTH}. @code{GL_FOG_COORD}
7204 specifies that the current fog coordinate should be used as distance
7205 value in the fog color computation. @code{GL_FRAGMENT_DEPTH} specifies
7206 that the current fragment depth should be used as distance value in the
7211 Fog blends a fog color with each rasterized pixel fragment's
7212 post-texturing color using a blending factor @r{@var{f}}. Factor
7213 @r{@var{f}} is computed in one of three ways, depending on the fog mode.
7214 Let @r{@var{c}} be either the distance in eye coordinate from the origin
7215 (in the case that the @code{GL_FOG_COORD_SRC} is
7216 @code{GL_FRAGMENT_DEPTH}) or the current fog coordinate (in the case
7217 that @code{GL_FOG_COORD_SRC} is @code{GL_FOG_COORD}). The equation for
7218 @code{GL_LINEAR} fog is
7219 @r{@var{f}=@var{end}-@var{c},/@var{end}-@var{start},}
7221 The equation for @code{GL_EXP} fog is
7222 @r{@var{f}=@var{e}^-(@var{density}·@var{c},),}
7224 The equation for @code{GL_EXP2} fog is
7225 @r{@var{f}=@var{e}^-(@var{density}·@var{c},),^2}
7227 Regardless of the fog mode, @r{@var{f}} is clamped to the range
7228 @r{[0,1]} after it is computed. Then, if the GL is in RGBA color mode,
7229 the fragment's red, green, and blue colors, represented by
7230 @r{@var{C}_@var{r}}, are replaced by
7232 @r{@var{C}_@var{r},^″=@var{f}×@var{C}_@var{r}+(1-@var{f},)×@var{C}_@var{f}}
7234 Fog does not affect a fragment's alpha component.
7236 In color index mode, the fragment's color index @r{@var{i}_@var{r}} is
7239 @r{@var{i}_@var{r},^″=@var{i}_@var{r}+(1-@var{f},)×@var{i}_@var{f}}
7243 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
7244 value, or if @var{pname} is @code{GL_FOG_MODE} and @var{params} is not
7247 @code{GL_INVALID_VALUE} is generated if @var{pname} is
7248 @code{GL_FOG_DENSITY} and @var{params} is negative.
7250 @code{GL_INVALID_OPERATION} is generated if @code{glFog} is executed
7251 between the execution of @code{glBegin} and the corresponding execution
7256 @deftypefun void glFrontFace mode
7257 Define front- and back-facing polygons.
7261 Specifies the orientation of front-facing polygons. @code{GL_CW} and
7262 @code{GL_CCW} are accepted. The initial value is @code{GL_CCW}.
7266 In a scene composed entirely of opaque closed surfaces, back-facing
7267 polygons are never visible. Eliminating these invisible polygons has the
7268 obvious benefit of speeding up the rendering of the image. To enable and
7269 disable elimination of back-facing polygons, call @code{glEnable} and
7270 @code{glDisable} with argument @code{GL_CULL_FACE}.
7272 The projection of a polygon to window coordinates is said to have
7273 clockwise winding if an imaginary object following the path from its
7274 first vertex, its second vertex, and so on, to its last vertex, and
7275 finally back to its first vertex, moves in a clockwise direction about
7276 the interior of the polygon. The polygon's winding is said to be
7277 counterclockwise if the imaginary object following the same path moves
7278 in a counterclockwise direction about the interior of the polygon.
7279 @code{glFrontFace} specifies whether polygons with clockwise winding in
7280 window coordinates, or counterclockwise winding in window coordinates,
7281 are taken to be front-facing. Passing @code{GL_CCW} to @var{mode}
7282 selects counterclockwise polygons as front-facing; @code{GL_CW} selects
7283 clockwise polygons as front-facing. By default, counterclockwise
7284 polygons are taken to be front-facing.
7286 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
7289 @code{GL_INVALID_OPERATION} is generated if @code{glFrontFace} is
7290 executed between the execution of @code{glBegin} and the corresponding
7291 execution of @code{glEnd}.
7295 @deftypefun void glFrustum left right bottom top nearVal farVal
7296 Multiply the current matrix by a perspective matrix.
7301 Specify the coordinates for the left and right vertical clipping planes.
7305 Specify the coordinates for the bottom and top horizontal clipping
7310 Specify the distances to the near and far depth clipping planes. Both
7311 distances must be positive.
7315 @code{glFrustum} describes a perspective matrix that produces a
7316 perspective projection. The current matrix (see @code{glMatrixMode}) is
7317 multiplied by this matrix and the result replaces the current matrix, as
7318 if @code{glMultMatrix} were called with the following matrix as its
7323 @r{[(2@var{nearVal},/@var{right}-@var{left},, 0 @var{A} 0), (0
7324 2@var{nearVal},/@var{top}-@var{bottom},, @var{B} 0), (0 0 @var{C}
7325 @var{D}), (0 0 -1 0),]}
7327 @r{@var{A}=@var{right}+@var{left},/@var{right}-@var{left},}
7329 @r{@var{B}=@var{top}+@var{bottom},/@var{top}-@var{bottom},}
7331 @r{@var{C}=-@var{farVal}+@var{nearVal},/@var{farVal}-@var{nearVal},,}
7333 @r{@var{D}=-2@var{farVal}@var{nearVal},/@var{farVal}-@var{nearVal},,}
7337 Typically, the matrix mode is @code{GL_PROJECTION}, and
7338 @r{(@var{left},@var{bottom}-@var{nearVal})} and
7339 @r{(@var{right},@var{top}-@var{nearVal})} specify the points on the near
7340 clipping plane that are mapped to the lower left and upper right corners
7341 of the window, assuming that the eye is located at (0, 0, 0).
7342 @r{-@var{farVal}} specifies the location of the far clipping plane. Both
7343 @var{nearVal} and @var{farVal} must be positive.
7345 Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the
7346 current matrix stack.
7348 @code{GL_INVALID_VALUE} is generated if @var{nearVal} or @var{farVal} is
7349 not positive, or if @var{left} = @var{right}, or @var{bottom} =
7350 @var{top}, or @var{near} = @var{far}.
7352 @code{GL_INVALID_OPERATION} is generated if @code{glFrustum} is executed
7353 between the execution of @code{glBegin} and the corresponding execution
7358 @deftypefun void glGenBuffers n buffers
7359 Generate buffer object names.
7363 Specifies the number of buffer object names to be generated.
7366 Specifies an array in which the generated buffer object names are
7371 @code{glGenBuffers} returns @var{n} buffer object names in
7372 @var{buffers}. There is no guarantee that the names form a contiguous
7373 set of integers; however, it is guaranteed that none of the returned
7374 names was in use immediately before the call to @code{glGenBuffers}.
7376 Buffer object names returned by a call to @code{glGenBuffers} are not
7377 returned by subsequent calls, unless they are first deleted with
7378 @code{glDeleteBuffers}.
7380 No buffer objects are associated with the returned buffer object names
7381 until they are first bound by calling @code{glBindBuffer}.
7383 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
7385 @code{GL_INVALID_OPERATION} is generated if @code{glGenBuffers} is
7386 executed between the execution of @code{glBegin} and the corresponding
7387 execution of @code{glEnd}.
7391 @deftypefun GLuint glGenLists range
7392 Generate a contiguous set of empty display lists.
7396 Specifies the number of contiguous empty display lists to be generated.
7400 @code{glGenLists} has one argument, @var{range}. It returns an integer
7401 @var{n} such that @var{range} contiguous empty display lists, named
7402 @r{@var{n}}, @r{@var{n}+1}, @r{@var{...}}, @r{@var{n}+@var{range}-1},
7403 are created. If @var{range} is 0, if there is no group of @var{range}
7404 contiguous names available, or if any error is generated, no display
7405 lists are generated, and 0 is returned.
7407 @code{GL_INVALID_VALUE} is generated if @var{range} is negative.
7409 @code{GL_INVALID_OPERATION} is generated if @code{glGenLists} is
7410 executed between the execution of @code{glBegin} and the corresponding
7411 execution of @code{glEnd}.
7415 @deftypefun void glGenQueries n ids
7416 Generate query object names.
7420 Specifies the number of query object names to be generated.
7423 Specifies an array in which the generated query object names are stored.
7427 @code{glGenQueries} returns @var{n} query object names in @var{ids}.
7428 There is no guarantee that the names form a contiguous set of integers;
7429 however, it is guaranteed that none of the returned names was in use
7430 immediately before the call to @code{glGenQueries}.
7432 Query object names returned by a call to @code{glGenQueries} are not
7433 returned by subsequent calls, unless they are first deleted with
7434 @code{glDeleteQueries}.
7436 No query objects are associated with the returned query object names
7437 until they are first used by calling @code{glBeginQuery}.
7439 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
7441 @code{GL_INVALID_OPERATION} is generated if @code{glGenQueries} is
7442 executed between the execution of @code{glBegin} and the corresponding
7443 execution of @code{glEnd}.
7447 @deftypefun void glGenTextures n textures
7448 Generate texture names.
7452 Specifies the number of texture names to be generated.
7454 @item @var{textures}
7455 Specifies an array in which the generated texture names are stored.
7459 @code{glGenTextures} returns @var{n} texture names in @var{textures}.
7460 There is no guarantee that the names form a contiguous set of integers;
7461 however, it is guaranteed that none of the returned names was in use
7462 immediately before the call to @code{glGenTextures}.
7464 The generated textures have no dimensionality; they assume the
7465 dimensionality of the texture target to which they are first bound (see
7466 @code{glBindTexture}).
7468 Texture names returned by a call to @code{glGenTextures} are not
7469 returned by subsequent calls, unless they are first deleted with
7470 @code{glDeleteTextures}.
7472 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
7474 @code{GL_INVALID_OPERATION} is generated if @code{glGenTextures} is
7475 executed between the execution of @code{glBegin} and the corresponding
7476 execution of @code{glEnd}.
7480 @deftypefun void glGetActiveAttrib program index bufSize length size type name
7481 Returns information about an active attribute variable for the specified
7486 Specifies the program object to be queried.
7489 Specifies the index of the attribute variable to be queried.
7492 Specifies the maximum number of characters OpenGL is allowed to write in
7493 the character buffer indicated by @var{name}.
7496 Returns the number of characters actually written by OpenGL in the
7497 string indicated by @var{name} (excluding the null terminator) if a
7498 value other than @code{NULL} is passed.
7501 Returns the size of the attribute variable.
7504 Returns the data type of the attribute variable.
7507 Returns a null terminated string containing the name of the attribute
7512 @code{glGetActiveAttrib} returns information about an active attribute
7513 variable in the program object specified by @var{program}. The number of
7514 active attributes can be obtained by calling @code{glGetProgram} with
7515 the value @code{GL_ACTIVE_ATTRIBUTES}. A value of 0 for @var{index}
7516 selects the first active attribute variable. Permissible values for
7517 @var{index} range from 0 to the number of active attribute variables
7520 A vertex shader may use either built-in attribute variables,
7521 user-defined attribute variables, or both. Built-in attribute variables
7522 have a prefix of "gl_" and reference conventional OpenGL vertex
7523 attribtes (e.g., @var{gl_Vertex}, @var{gl_Normal}, etc., see the OpenGL
7524 Shading Language specification for a complete list.) User-defined
7525 attribute variables have arbitrary names and obtain their values through
7526 numbered generic vertex attributes. An attribute variable (either
7527 built-in or user-defined) is considered active if it is determined
7528 during the link operation that it may be accessed during program
7529 execution. Therefore, @var{program} should have previously been the
7530 target of a call to @code{glLinkProgram}, but it is not necessary for it
7531 to have been linked successfully.
7533 The size of the character buffer required to store the longest attribute
7534 variable name in @var{program} can be obtained by calling
7535 @code{glGetProgram} with the value
7536 @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH}. This value should be used to
7537 allocate a buffer of sufficient size to store the returned attribute
7538 name. The size of this character buffer is passed in @var{bufSize}, and
7539 a pointer to this character buffer is passed in @var{name}.
7541 @code{glGetActiveAttrib} returns the name of the attribute variable
7542 indicated by @var{index}, storing it in the character buffer specified
7543 by @var{name}. The string returned will be null terminated. The actual
7544 number of characters written into this buffer is returned in
7545 @var{length}, and this count does not include the null termination
7546 character. If the length of the returned string is not required, a value
7547 of @code{NULL} can be passed in the @var{length} argument.
7549 The @var{type} argument will return a pointer to the attribute
7550 variable's data type. The symbolic constants @code{GL_FLOAT},
7551 @code{GL_FLOAT_VEC2}, @code{GL_FLOAT_VEC3}, @code{GL_FLOAT_VEC4},
7552 @code{GL_FLOAT_MAT2}, @code{GL_FLOAT_MAT3}, @code{GL_FLOAT_MAT4},
7553 @code{GL_FLOAT_MAT2x3}, @code{GL_FLOAT_MAT2x4}, @code{GL_FLOAT_MAT3x2},
7554 @code{GL_FLOAT_MAT3x4}, @code{GL_FLOAT_MAT4x2}, or
7555 @code{GL_FLOAT_MAT4x3} may be returned. The @var{size} argument will
7556 return the size of the attribute, in units of the type returned in
7559 The list of active attribute variables may include both built-in
7560 attribute variables (which begin with the prefix "gl_") as well as
7561 user-defined attribute variable names.
7563 This function will return as much information as it can about the
7564 specified active attribute variable. If no information is available,
7565 @var{length} will be 0, and @var{name} will be an empty string. This
7566 situation could occur if this function is called after a link operation
7567 that failed. If an error occurs, the return values @var{length},
7568 @var{size}, @var{type}, and @var{name} will be unmodified.
7570 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
7571 generated by OpenGL.
7573 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
7576 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
7577 equal to the number of active attribute variables in @var{program}.
7579 @code{GL_INVALID_OPERATION} is generated if @code{glGetActiveAttrib} is
7580 executed between the execution of @code{glBegin} and the corresponding
7581 execution of @code{glEnd}.
7583 @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0.
7587 @deftypefun void glGetActiveUniform program index bufSize length size type name
7588 Returns information about an active uniform variable for the specified
7593 Specifies the program object to be queried.
7596 Specifies the index of the uniform variable to be queried.
7599 Specifies the maximum number of characters OpenGL is allowed to write in
7600 the character buffer indicated by @var{name}.
7603 Returns the number of characters actually written by OpenGL in the
7604 string indicated by @var{name} (excluding the null terminator) if a
7605 value other than @code{NULL} is passed.
7608 Returns the size of the uniform variable.
7611 Returns the data type of the uniform variable.
7614 Returns a null terminated string containing the name of the uniform
7619 @code{glGetActiveUniform} returns information about an active uniform
7620 variable in the program object specified by @var{program}. The number of
7621 active uniform variables can be obtained by calling @code{glGetProgram}
7622 with the value @code{GL_ACTIVE_UNIFORMS}. A value of 0 for @var{index}
7623 selects the first active uniform variable. Permissible values for
7624 @var{index} range from 0 to the number of active uniform variables minus
7627 Shaders may use either built-in uniform variables, user-defined uniform
7628 variables, or both. Built-in uniform variables have a prefix of "gl_"
7629 and reference existing OpenGL state or values derived from such state
7630 (e.g., @var{gl_Fog}, @var{gl_ModelViewMatrix}, etc., see the OpenGL
7631 Shading Language specification for a complete list.) User-defined
7632 uniform variables have arbitrary names and obtain their values from the
7633 application through calls to @code{glUniform}. A uniform variable
7634 (either built-in or user-defined) is considered active if it is
7635 determined during the link operation that it may be accessed during
7636 program execution. Therefore, @var{program} should have previously been
7637 the target of a call to @code{glLinkProgram}, but it is not necessary
7638 for it to have been linked successfully.
7640 The size of the character buffer required to store the longest uniform
7641 variable name in @var{program} can be obtained by calling
7642 @code{glGetProgram} with the value @code{GL_ACTIVE_UNIFORM_MAX_LENGTH}.
7643 This value should be used to allocate a buffer of sufficient size to
7644 store the returned uniform variable name. The size of this character
7645 buffer is passed in @var{bufSize}, and a pointer to this character
7646 buffer is passed in @var{name.}
7648 @code{glGetActiveUniform} returns the name of the uniform variable
7649 indicated by @var{index}, storing it in the character buffer specified
7650 by @var{name}. The string returned will be null terminated. The actual
7651 number of characters written into this buffer is returned in
7652 @var{length}, and this count does not include the null termination
7653 character. If the length of the returned string is not required, a value
7654 of @code{NULL} can be passed in the @var{length} argument.
7656 The @var{type} argument will return a pointer to the uniform variable's
7657 data type. The symbolic constants @code{GL_FLOAT}, @code{GL_FLOAT_VEC2},
7658 @code{GL_FLOAT_VEC3}, @code{GL_FLOAT_VEC4}, @code{GL_INT},
7659 @code{GL_INT_VEC2}, @code{GL_INT_VEC3}, @code{GL_INT_VEC4},
7660 @code{GL_BOOL}, @code{GL_BOOL_VEC2}, @code{GL_BOOL_VEC3},
7661 @code{GL_BOOL_VEC4}, @code{GL_FLOAT_MAT2}, @code{GL_FLOAT_MAT3},
7662 @code{GL_FLOAT_MAT4}, @code{GL_FLOAT_MAT2x3}, @code{GL_FLOAT_MAT2x4},
7663 @code{GL_FLOAT_MAT3x2}, @code{GL_FLOAT_MAT3x4}, @code{GL_FLOAT_MAT4x2},
7664 @code{GL_FLOAT_MAT4x3}, @code{GL_SAMPLER_1D}, @code{GL_SAMPLER_2D},
7665 @code{GL_SAMPLER_3D}, @code{GL_SAMPLER_CUBE},
7666 @code{GL_SAMPLER_1D_SHADOW}, or @code{GL_SAMPLER_2D_SHADOW} may be
7669 If one or more elements of an array are active, the name of the array is
7670 returned in @var{name}, the type is returned in @var{type}, and the
7671 @var{size} parameter returns the highest array element index used, plus
7672 one, as determined by the compiler and/or linker. Only one active
7673 uniform variable will be reported for a uniform array.
7675 Uniform variables that are declared as structures or arrays of
7676 structures will not be returned directly by this function. Instead, each
7677 of these uniform variables will be reduced to its fundamental components
7678 containing the "." and "[]" operators such that each of the names is
7679 valid as an argument to @code{glGetUniformLocation}. Each of these
7680 reduced uniform variables is counted as one active uniform variable and
7681 is assigned an index. A valid name cannot be a structure, an array of
7682 structures, or a subcomponent of a vector or matrix.
7684 The size of the uniform variable will be returned in @var{size}. Uniform
7685 variables other than arrays will have a size of 1. Structures and arrays
7686 of structures will be reduced as described earlier, such that each of
7687 the names returned will be a data type in the earlier list. If this
7688 reduction results in an array, the size returned will be as described
7689 for uniform arrays; otherwise, the size returned will be 1.
7691 The list of active uniform variables may include both built-in uniform
7692 variables (which begin with the prefix "gl_") as well as user-defined
7693 uniform variable names.
7695 This function will return as much information as it can about the
7696 specified active uniform variable. If no information is available,
7697 @var{length} will be 0, and @var{name} will be an empty string. This
7698 situation could occur if this function is called after a link operation
7699 that failed. If an error occurs, the return values @var{length},
7700 @var{size}, @var{type}, and @var{name} will be unmodified.
7702 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
7703 generated by OpenGL.
7705 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
7708 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
7709 equal to the number of active uniform variables in @var{program}.
7711 @code{GL_INVALID_OPERATION} is generated if @code{glGetActiveUniform} is
7712 executed between the execution of @code{glBegin} and the corresponding
7713 execution of @code{glEnd}.
7715 @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0.
7719 @deftypefun void glGetAttachedShaders program maxCount count shaders
7720 Returns the handles of the shader objects attached to a program object.
7724 Specifies the program object to be queried.
7726 @item @var{maxCount}
7727 Specifies the size of the array for storing the returned object names.
7730 Returns the number of names actually returned in @var{objects}.
7733 Specifies an array that is used to return the names of attached shader
7738 @code{glGetAttachedShaders} returns the names of the shader objects
7739 attached to @var{program}. The names of shader objects that are attached
7740 to @var{program} will be returned in @var{shaders.} The actual number of
7741 shader names written into @var{shaders} is returned in @var{count.} If
7742 no shader objects are attached to @var{program}, @var{count} is set to
7743 0. The maximum number of shader names that may be returned in
7744 @var{shaders} is specified by @var{maxCount}.
7746 If the number of names actually returned is not required (for instance,
7747 if it has just been obtained by calling @code{glGetProgram}), a value of
7748 @code{NULL} may be passed for count. If no shader objects are attached
7749 to @var{program}, a value of 0 will be returned in @var{count}. The
7750 actual number of attached shaders can be obtained by calling
7751 @code{glGetProgram} with the value @code{GL_ATTACHED_SHADERS}.
7753 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
7754 generated by OpenGL.
7756 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
7759 @code{GL_INVALID_VALUE} is generated if @var{maxCount} is less than 0.
7761 @code{GL_INVALID_OPERATION} is generated if @code{glGetAttachedShaders}
7762 is executed between the execution of @code{glBegin} and the
7763 corresponding execution of @code{glEnd}.
7767 @deftypefun GLint glGetAttribLocation program name
7768 Returns the location of an attribute variable.
7772 Specifies the program object to be queried.
7775 Points to a null terminated string containing the name of the attribute
7776 variable whose location is to be queried.
7780 @code{glGetAttribLocation} queries the previously linked program object
7781 specified by @var{program} for the attribute variable specified by
7782 @var{name} and returns the index of the generic vertex attribute that is
7783 bound to that attribute variable. If @var{name} is a matrix attribute
7784 variable, the index of the first column of the matrix is returned. If
7785 the named attribute variable is not an active attribute in the specified
7786 program object or if @var{name} starts with the reserved prefix "gl_", a
7787 value of -1 is returned.
7789 The association between an attribute variable name and a generic
7790 attribute index can be specified at any time by calling
7791 @code{glBindAttribLocation}. Attribute bindings do not go into effect
7792 until @code{glLinkProgram} is called. After a program object has been
7793 linked successfully, the index values for attribute variables remain
7794 fixed until the next link command occurs. The attribute values can only
7795 be queried after a link if the link was successful.
7796 @code{glGetAttribLocation} returns the binding that actually went into
7797 effect the last time @code{glLinkProgram} was called for the specified
7798 program object. Attribute bindings that have been specified since the
7799 last link operation are not returned by @code{glGetAttribLocation}.
7801 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a value
7802 generated by OpenGL.
7804 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
7807 @code{GL_INVALID_OPERATION} is generated if @var{program} has not been
7808 successfully linked.
7810 @code{GL_INVALID_OPERATION} is generated if @code{glGetAttribLocation}
7811 is executed between the execution of @code{glBegin} and the
7812 corresponding execution of @code{glEnd}.
7816 @deftypefun void glGetBufferParameteriv target value data
7817 Return parameters of a buffer object.
7821 Specifies the target buffer object. The symbolic constant must be
7822 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
7823 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
7826 Specifies the symbolic name of a buffer object parameter. Accepted
7827 values are @code{GL_BUFFER_ACCESS}, @code{GL_BUFFER_MAPPED},
7828 @code{GL_BUFFER_SIZE}, or @code{GL_BUFFER_USAGE}.
7831 Returns the requested parameter.
7835 @code{glGetBufferParameteriv} returns in @var{data} a selected parameter
7836 of the buffer object specified by @var{target}.
7838 @var{value} names a specific buffer object parameter, as follows:
7841 @item @code{GL_BUFFER_ACCESS}
7842 @var{params} returns the access policy set while mapping the buffer
7843 object. The initial value is @code{GL_READ_WRITE}.
7845 @item @code{GL_BUFFER_MAPPED}
7846 @var{params} returns a flag indicating whether the buffer object is
7847 currently mapped. The initial value is @code{GL_FALSE}.
7849 @item @code{GL_BUFFER_SIZE}
7850 @var{params} returns the size of the buffer object, measured in bytes.
7851 The initial value is 0.
7853 @item @code{GL_BUFFER_USAGE}
7854 @var{params} returns the buffer object's usage pattern. The initial
7855 value is @code{GL_STATIC_DRAW}.
7859 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{value} is
7860 not an accepted value.
7862 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
7863 name 0 is bound to @var{target}.
7865 @code{GL_INVALID_OPERATION} is generated if
7866 @code{glGetBufferParameteriv} is executed between the execution of
7867 @code{glBegin} and the corresponding execution of @code{glEnd}.
7871 @deftypefun void glGetBufferPointerv target pname params
7872 Return the pointer to a mapped buffer object's data store.
7876 Specifies the target buffer object. The symbolic constant must be
7877 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
7878 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
7881 Specifies the pointer to be returned. The symbolic constant must be
7882 @code{GL_BUFFER_MAP_POINTER}.
7885 Returns the pointer value specified by @var{pname}.
7889 @code{glGetBufferPointerv} returns pointer information. @var{pname} is a
7890 symbolic constant indicating the pointer to be returned, which must be
7891 @code{GL_BUFFER_MAP_POINTER}, the pointer to which the buffer object's
7892 data store is mapped. If the data store is not currently mapped,
7893 @code{NULL} is returned. @var{params} is a pointer to a location in
7894 which to place the returned pointer value.
7896 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
7897 not an accepted value.
7899 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
7900 name 0 is bound to @var{target}.
7902 @code{GL_INVALID_OPERATION} is generated if @code{glGetBufferPointerv}
7903 is executed between the execution of @code{glBegin} and the
7904 corresponding execution of @code{glEnd}.
7908 @deftypefun void glGetBufferSubData target offset size data
7909 Returns a subset of a buffer object's data store.
7913 Specifies the target buffer object. The symbolic constant must be
7914 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
7915 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
7918 Specifies the offset into the buffer object's data store from which data
7919 will be returned, measured in bytes.
7922 Specifies the size in bytes of the data store region being returned.
7925 Specifies a pointer to the location where buffer object data is
7930 @code{glGetBufferSubData} returns some or all of the data from the
7931 buffer object currently bound to @var{target}. Data starting at byte
7932 offset @var{offset} and extending for @var{size} bytes is copied from
7933 the data store to the memory pointed to by @var{data}. An error is
7934 thrown if the buffer object is currently mapped, or if @var{offset} and
7935 @var{size} together define a range beyond the bounds of the buffer
7936 object's data store.
7938 @code{GL_INVALID_ENUM} is generated if @var{target} is not
7939 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
7940 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
7942 @code{GL_INVALID_VALUE} is generated if @var{offset} or @var{size} is
7943 negative, or if together they define a region of memory that extends
7944 beyond the buffer object's allocated data store.
7946 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
7947 name 0 is bound to @var{target}.
7949 @code{GL_INVALID_OPERATION} is generated if the buffer object being
7952 @code{GL_INVALID_OPERATION} is generated if @code{glGetBufferSubData} is
7953 executed between the execution of @code{glBegin} and the corresponding
7954 execution of @code{glEnd}.
7958 @deftypefun void glGetClipPlane plane equation
7959 Return the coefficients of the specified clipping plane.
7963 Specifies a clipping plane. The number of clipping planes depends on the
7964 implementation, but at least six clipping planes are supported. They are
7965 identified by symbolic names of the form @code{GL_CLIP_PLANE}@r{@var{i}}
7966 where i ranges from 0 to the value of @code{GL_MAX_CLIP_PLANES} - 1.
7968 @item @var{equation}
7969 Returns four double-precision values that are the coefficients of the
7970 plane equation of @var{plane} in eye coordinates. The initial value is
7975 @code{glGetClipPlane} returns in @var{equation} the four coefficients of
7976 the plane equation for @var{plane}.
7978 @code{GL_INVALID_ENUM} is generated if @var{plane} is not an accepted
7981 @code{GL_INVALID_OPERATION} is generated if @code{glGetClipPlane} is
7982 executed between the execution of @code{glBegin} and the corresponding
7983 execution of @code{glEnd}.
7987 @deftypefun void glGetColorTableParameterfv target pname params
7988 @deftypefunx void glGetColorTableParameteriv target pname params
7989 Get color lookup table parameters.
7993 The target color table. Must be @code{GL_COLOR_TABLE},
7994 @code{GL_POST_CONVOLUTION_COLOR_TABLE},
7995 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{GL_PROXY_COLOR_TABLE},
7996 @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or
7997 @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}.
8000 The symbolic name of a color lookup table parameter. Must be one of
8001 @code{GL_COLOR_TABLE_BIAS}, @code{GL_COLOR_TABLE_SCALE},
8002 @code{GL_COLOR_TABLE_FORMAT}, @code{GL_COLOR_TABLE_WIDTH},
8003 @code{GL_COLOR_TABLE_RED_SIZE}, @code{GL_COLOR_TABLE_GREEN_SIZE},
8004 @code{GL_COLOR_TABLE_BLUE_SIZE}, @code{GL_COLOR_TABLE_ALPHA_SIZE},
8005 @code{GL_COLOR_TABLE_LUMINANCE_SIZE}, or
8006 @code{GL_COLOR_TABLE_INTENSITY_SIZE}.
8009 A pointer to an array where the values of the parameter will be stored.
8013 Returns parameters specific to color table @var{target}.
8015 When @var{pname} is set to @code{GL_COLOR_TABLE_SCALE} or
8016 @code{GL_COLOR_TABLE_BIAS}, @code{glGetColorTableParameter} returns the
8017 color table scale or bias parameters for the table specified by
8018 @var{target}. For these queries, @var{target} must be set to
8019 @code{GL_COLOR_TABLE}, @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
8020 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} and @var{params} points to an
8021 array of four elements, which receive the scale or bias factors for red,
8022 green, blue, and alpha, in that order.
8024 @code{glGetColorTableParameter} can also be used to retrieve the format
8025 and size parameters for a color table. For these queries, set
8026 @var{target} to either the color table target or the proxy color table
8027 target. The format and size parameters are set by @code{glColorTable}.
8029 The following table lists the format and size parameters that may be
8030 queried. For each symbolic constant listed below for @var{pname},
8031 @var{params} must point to an array of the given length and receive the
8037 @item @strong{Parameter}
8038 @strong{N}, @strong{Meaning}
8040 @item @code{GL_COLOR_TABLE_FORMAT}
8041 1 , Internal format (e.g., @code{GL_RGBA})
8043 @item @code{GL_COLOR_TABLE_WIDTH}
8044 1 , Number of elements in table
8046 @item @code{GL_COLOR_TABLE_RED_SIZE}
8047 1 , Size of red component, in bits
8049 @item @code{GL_COLOR_TABLE_GREEN_SIZE}
8050 1 , Size of green component
8052 @item @code{GL_COLOR_TABLE_BLUE_SIZE}
8053 1 , Size of blue component
8055 @item @code{GL_COLOR_TABLE_ALPHA_SIZE}
8056 1 , Size of alpha component
8058 @item @code{GL_COLOR_TABLE_LUMINANCE_SIZE}
8059 1 , Size of luminance component
8061 @item @code{GL_COLOR_TABLE_INTENSITY_SIZE}
8062 1 , Size of intensity component
8068 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
8069 not an acceptable value.
8071 @code{GL_INVALID_OPERATION} is generated if
8072 @code{glGetColorTableParameter} is executed between the execution of
8073 @code{glBegin} and the corresponding execution of @code{glEnd}.
8077 @deftypefun void glGetColorTable target format type table
8078 Retrieve contents of a color lookup table.
8082 Must be @code{GL_COLOR_TABLE}, @code{GL_POST_CONVOLUTION_COLOR_TABLE},
8083 or @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}.
8086 The format of the pixel data in @var{table}. The possible values are
8087 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
8088 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB},
8089 @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}.
8092 The type of the pixel data in @var{table}. Symbolic constants
8093 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
8094 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
8095 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
8096 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
8097 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
8098 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
8099 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
8100 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
8101 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
8104 Pointer to a one-dimensional array of pixel data containing the contents
8109 @code{glGetColorTable} returns in @var{table} the contents of the color
8110 table specified by @var{target}. No pixel transfer operations are
8111 performed, but pixel storage modes that are applicable to
8112 @code{glReadPixels} are performed.
8114 If a non-zero named buffer object is bound to the
8115 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
8116 histogram table is requested, @var{table} is treated as a byte offset
8117 into the buffer object's data store.
8119 Color components that are requested in the specified @var{format}, but
8120 which are not included in the internal format of the color lookup table,
8121 are returned as zero. The assignments of internal color components to
8122 the components requested by @var{format} are
8125 @item @strong{Internal Component}
8126 @strong{Resulting Component}
8156 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
8159 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
8162 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
8165 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8166 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
8167 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
8168 and @var{format} is not @code{GL_RGB}.
8170 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8171 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
8172 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
8173 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
8174 @code{GL_UNSIGNED_INT_10_10_10_2}, or
8175 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
8176 @code{GL_RGBA} nor @code{GL_BGRA}.
8178 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8179 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
8180 object's data store is currently mapped.
8182 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8183 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
8184 would be packed to the buffer object such that the memory writes
8185 required would exceed the data store size.
8187 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8188 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{table}
8189 is not evenly divisible into the number of bytes needed to store in
8190 memory a datum indicated by @var{type}.
8192 @code{GL_INVALID_OPERATION} is generated if @code{glGetColorTable} is
8193 executed between the execution of @code{glBegin} and the corresponding
8194 execution of @code{glEnd}.
8198 @deftypefun void glGetCompressedTexImage target lod img
8199 Return a compressed texture image.
8203 Specifies which texture is to be obtained. @code{GL_TEXTURE_1D},
8204 @code{GL_TEXTURE_2D}, and
8205 @code{GL_TEXTURE_3D}@code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
8206 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
8207 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
8208 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
8209 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, and
8210 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z} are accepted.
8213 Specifies the level-of-detail number of the desired image. Level 0 is
8214 the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap
8218 Returns the compressed texture image.
8222 @code{glGetCompressedTexImage} returns the compressed texture image
8223 associated with @var{target} and @var{lod} into @var{img}. @var{img}
8224 should be an array of @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} bytes.
8225 @var{target} specifies whether the desired texture image was one
8226 specified by @code{glTexImage1D} (@code{GL_TEXTURE_1D}),
8227 @code{glTexImage2D} (@code{GL_TEXTURE_2D} or any of
8228 @code{GL_TEXTURE_CUBE_MAP_*}), or @code{glTexImage3D}
8229 (@code{GL_TEXTURE_3D}). @var{lod} specifies the level-of-detail number
8230 of the desired image.
8232 If a non-zero named buffer object is bound to the
8233 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
8234 texture image is requested, @var{img} is treated as a byte offset into
8235 the buffer object's data store.
8237 To minimize errors, first verify that the texture is compressed by
8238 calling @code{glGetTexLevelParameter} with argument
8239 @code{GL_TEXTURE_COMPRESSED}. If the texture is compressed, then
8240 determine the amount of memory required to store the compressed texture
8241 by calling @code{glGetTexLevelParameter} with argument
8242 @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE}. Finally, retrieve the internal
8243 format of the texture by calling @code{glGetTexLevelParameter} with
8244 argument @code{GL_TEXTURE_INTERNAL_FORMAT}. To store the texture for
8245 later use, associate the internal format and size with the retrieved
8246 texture image. These data can be used by the respective texture or
8247 subtexture loading routine used for loading @var{target} textures.
8249 @code{GL_INVALID_VALUE} is generated if @var{lod} is less than zero or
8250 greater than the maximum number of LODs permitted by the implementation.
8252 @code{GL_INVALID_OPERATION} is generated if
8253 @code{glGetCompressedTexImage} is used to retrieve a texture that is in
8254 an uncompressed internal format.
8256 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8257 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
8258 object's data store is currently mapped.
8260 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8261 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
8262 would be packed to the buffer object such that the memory writes
8263 required would exceed the data store size.
8265 @code{GL_INVALID_OPERATION} is generated if
8266 @code{glGetCompressedTexImage} is executed between the execution of
8267 @code{glBegin} and the corresponding execution of @code{glEnd}.
8271 @deftypefun void glGetConvolutionFilter target format type image
8272 Get current 1D or 2D convolution filter kernel.
8276 The filter to be retrieved. Must be one of @code{GL_CONVOLUTION_1D} or
8277 @code{GL_CONVOLUTION_2D}.
8280 Format of the output image. Must be one of @code{GL_RED},
8281 @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB},
8282 @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, or
8283 @code{GL_LUMINANCE_ALPHA}.
8286 Data type of components in the output image. Symbolic constants
8287 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
8288 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
8289 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
8290 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
8291 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
8292 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
8293 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
8294 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
8295 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
8298 Pointer to storage for the output image.
8302 @code{glGetConvolutionFilter} returns the current 1D or 2D convolution
8303 filter kernel as an image. The one- or two-dimensional image is placed
8304 in @var{image} according to the specifications in @var{format} and
8305 @var{type}. No pixel transfer operations are performed on this image,
8306 but the relevant pixel storage modes are applied.
8308 If a non-zero named buffer object is bound to the
8309 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
8310 convolution filter is requested, @var{image} is treated as a byte offset
8311 into the buffer object's data store.
8313 Color components that are present in @var{format} but not included in
8314 the internal format of the filter are returned as zero. The assignments
8315 of internal color components to the components of @var{format} are as
8319 @item @strong{Internal Component}
8320 @strong{Resulting Component}
8350 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
8353 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
8356 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
8359 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8360 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
8361 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
8362 and @var{format} is not @code{GL_RGB}.
8364 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8365 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
8366 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
8367 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
8368 @code{GL_UNSIGNED_INT_10_10_10_2}, or
8369 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
8370 @code{GL_RGBA} nor @code{GL_BGRA}.
8372 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8373 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
8374 object's data store is currently mapped.
8376 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8377 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
8378 would be packed to the buffer object such that the memory writes
8379 required would exceed the data store size.
8381 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8382 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{image}
8383 is not evenly divisible into the number of bytes needed to store in
8384 memory a datum indicated by @var{type}.
8386 @code{GL_INVALID_OPERATION} is generated if
8387 @code{glGetConvolutionFilter} is executed between the execution of
8388 @code{glBegin} and the corresponding execution of @code{glEnd}.
8392 @deftypefun void glGetConvolutionParameterfv target pname params
8393 @deftypefunx void glGetConvolutionParameteriv target pname params
8394 Get convolution parameters.
8398 The filter whose parameters are to be retrieved. Must be one of
8399 @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or
8400 @code{GL_SEPARABLE_2D}.
8403 The parameter to be retrieved. Must be one of
8404 @code{GL_CONVOLUTION_BORDER_MODE}, @code{GL_CONVOLUTION_BORDER_COLOR},
8405 @code{GL_CONVOLUTION_FILTER_SCALE}, @code{GL_CONVOLUTION_FILTER_BIAS},
8406 @code{GL_CONVOLUTION_FORMAT}, @code{GL_CONVOLUTION_WIDTH},
8407 @code{GL_CONVOLUTION_HEIGHT}, @code{GL_MAX_CONVOLUTION_WIDTH}, or
8408 @code{GL_MAX_CONVOLUTION_HEIGHT}.
8411 Pointer to storage for the parameters to be retrieved.
8415 @code{glGetConvolutionParameter} retrieves convolution parameters.
8416 @var{target} determines which convolution filter is queried. @var{pname}
8417 determines which parameter is returned:
8420 @item @code{GL_CONVOLUTION_BORDER_MODE}
8423 The convolution border mode. See @code{glConvolutionParameter} for a
8424 list of border modes.
8426 @item @code{GL_CONVOLUTION_BORDER_COLOR}
8429 The current convolution border color. @var{params} must be a pointer to
8430 an array of four elements, which will receive the red, green, blue, and
8431 alpha border colors.
8433 @item @code{GL_CONVOLUTION_FILTER_SCALE}
8436 The current filter scale factors. @var{params} must be a pointer to an
8437 array of four elements, which will receive the red, green, blue, and
8438 alpha filter scale factors in that order.
8440 @item @code{GL_CONVOLUTION_FILTER_BIAS}
8443 The current filter bias factors. @var{params} must be a pointer to an
8444 array of four elements, which will receive the red, green, blue, and
8445 alpha filter bias terms in that order.
8447 @item @code{GL_CONVOLUTION_FORMAT}
8450 The current internal format. See @code{glConvolutionFilter1D},
8451 @code{glConvolutionFilter2D}, and @code{glSeparableFilter2D} for lists
8452 of allowable formats.
8454 @item @code{GL_CONVOLUTION_WIDTH}
8457 The current filter image width.
8459 @item @code{GL_CONVOLUTION_HEIGHT}
8462 The current filter image height.
8464 @item @code{GL_MAX_CONVOLUTION_WIDTH}
8467 The maximum acceptable filter image width.
8469 @item @code{GL_MAX_CONVOLUTION_HEIGHT}
8472 The maximum acceptable filter image height.
8476 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
8479 @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the
8482 @code{GL_INVALID_ENUM} is generated if @var{target} is
8483 @code{GL_CONVOLUTION_1D} and @var{pname} is @code{GL_CONVOLUTION_HEIGHT}
8484 or @code{GL_MAX_CONVOLUTION_HEIGHT}.
8486 @code{GL_INVALID_OPERATION} is generated if
8487 @code{glGetConvolutionParameter} is executed between the execution of
8488 @code{glBegin} and the corresponding execution of @code{glEnd}.
8492 @deftypefun GLenum glGetError
8493 Return error information.
8495 @code{glGetError} returns the value of the error flag. Each detectable
8496 error is assigned a numeric code and symbolic name. When an error
8497 occurs, the error flag is set to the appropriate error code value. No
8498 other errors are recorded until @code{glGetError} is called, the error
8499 code is returned, and the flag is reset to @code{GL_NO_ERROR}. If a call
8500 to @code{glGetError} returns @code{GL_NO_ERROR}, there has been no
8501 detectable error since the last call to @code{glGetError}, or since the
8504 To allow for distributed implementations, there may be several error
8505 flags. If any single error flag has recorded an error, the value of that
8506 flag is returned and that flag is reset to @code{GL_NO_ERROR} when
8507 @code{glGetError} is called. If more than one flag has recorded an
8508 error, @code{glGetError} returns and clears an arbitrary error flag
8509 value. Thus, @code{glGetError} should always be called in a loop, until
8510 it returns @code{GL_NO_ERROR}, if all error flags are to be reset.
8512 Initially, all error flags are set to @code{GL_NO_ERROR}.
8514 The following errors are currently defined:
8517 @item @code{GL_NO_ERROR}
8518 No error has been recorded. The value of this symbolic constant is
8521 @item @code{GL_INVALID_ENUM}
8522 An unacceptable value is specified for an enumerated argument. The
8523 offending command is ignored and has no other side effect than to set
8526 @item @code{GL_INVALID_VALUE}
8527 A numeric argument is out of range. The offending command is ignored and
8528 has no other side effect than to set the error flag.
8530 @item @code{GL_INVALID_OPERATION}
8531 The specified operation is not allowed in the current state. The
8532 offending command is ignored and has no other side effect than to set
8535 @item @code{GL_STACK_OVERFLOW}
8536 This command would cause a stack overflow. The offending command is
8537 ignored and has no other side effect than to set the error flag.
8539 @item @code{GL_STACK_UNDERFLOW}
8540 This command would cause a stack underflow. The offending command is
8541 ignored and has no other side effect than to set the error flag.
8543 @item @code{GL_OUT_OF_MEMORY}
8544 There is not enough memory left to execute the command. The state of the
8545 GL is undefined, except for the state of the error flags, after this
8548 @item @code{GL_TABLE_TOO_LARGE}
8549 The specified table exceeds the implementation's maximum supported table
8550 size. The offending command is ignored and has no other side effect than
8551 to set the error flag.
8555 When an error flag is set, results of a GL operation are undefined only
8556 if @code{GL_OUT_OF_MEMORY} has occurred. In all other cases, the command
8557 generating the error is ignored and has no effect on the GL state or
8558 frame buffer contents. If the generating command returns a value, it
8559 returns 0. If @code{glGetError} itself generates an error, it returns 0.
8561 @code{GL_INVALID_OPERATION} is generated if @code{glGetError} is
8562 executed between the execution of @code{glBegin} and the corresponding
8563 execution of @code{glEnd}. In this case, @code{glGetError} returns 0.
8567 @deftypefun void glGetHistogramParameterfv target pname params
8568 @deftypefunx void glGetHistogramParameteriv target pname params
8569 Get histogram parameters.
8573 Must be one of @code{GL_HISTOGRAM} or @code{GL_PROXY_HISTOGRAM}.
8576 The name of the parameter to be retrieved. Must be one of
8577 @code{GL_HISTOGRAM_WIDTH}, @code{GL_HISTOGRAM_FORMAT},
8578 @code{GL_HISTOGRAM_RED_SIZE}, @code{GL_HISTOGRAM_GREEN_SIZE},
8579 @code{GL_HISTOGRAM_BLUE_SIZE}, @code{GL_HISTOGRAM_ALPHA_SIZE},
8580 @code{GL_HISTOGRAM_LUMINANCE_SIZE}, or @code{GL_HISTOGRAM_SINK}.
8583 Pointer to storage for the returned values.
8587 @code{glGetHistogramParameter} is used to query parameter values for the
8588 current histogram or for a proxy. The histogram state information may be
8589 queried by calling @code{glGetHistogramParameter} with a @var{target} of
8590 @code{GL_HISTOGRAM} (to obtain information for the current histogram
8591 table) or @code{GL_PROXY_HISTOGRAM} (to obtain information from the most
8592 recent proxy request) and one of the following values for the
8593 @var{pname} argument:
8598 @item @strong{Parameter}
8599 @strong{Description}
8601 @item @code{GL_HISTOGRAM_WIDTH}
8602 Histogram table width
8604 @item @code{GL_HISTOGRAM_FORMAT}
8607 @item @code{GL_HISTOGRAM_RED_SIZE}
8608 Red component counter size, in bits
8610 @item @code{GL_HISTOGRAM_GREEN_SIZE}
8611 Green component counter size, in bits
8613 @item @code{GL_HISTOGRAM_BLUE_SIZE}
8614 Blue component counter size, in bits
8616 @item @code{GL_HISTOGRAM_ALPHA_SIZE}
8617 Alpha component counter size, in bits
8619 @item @code{GL_HISTOGRAM_LUMINANCE_SIZE}
8620 Luminance component counter size, in bits
8622 @item @code{GL_HISTOGRAM_SINK}
8623 Value of the @var{sink} parameter
8629 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
8632 @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the
8635 @code{GL_INVALID_OPERATION} is generated if
8636 @code{glGetHistogramParameter} is executed between the execution of
8637 @code{glBegin} and the corresponding execution of @code{glEnd}.
8641 @deftypefun void glGetHistogram target reset format type values
8642 Get histogram table.
8646 Must be @code{GL_HISTOGRAM}.
8649 If @code{GL_TRUE}, each component counter that is actually returned is
8650 reset to zero. (Other counters are unaffected.) If @code{GL_FALSE}, none
8651 of the counters in the histogram table is modified.
8654 The format of values to be returned in @var{values}. Must be one of
8655 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
8656 @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA},
8657 @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}.
8660 The type of values to be returned in @var{values}. Symbolic constants
8661 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
8662 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
8663 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
8664 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
8665 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
8666 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
8667 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
8668 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
8669 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
8672 A pointer to storage for the returned histogram table.
8676 @code{glGetHistogram} returns the current histogram table as a
8677 one-dimensional image with the same width as the histogram. No pixel
8678 transfer operations are performed on this image, but pixel storage modes
8679 that are applicable to 1D images are honored.
8681 If a non-zero named buffer object is bound to the
8682 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
8683 histogram table is requested, @var{values} is treated as a byte offset
8684 into the buffer object's data store.
8686 Color components that are requested in the specified @var{format}, but
8687 which are not included in the internal format of the histogram, are
8688 returned as zero. The assignments of internal color components to the
8689 components requested by @var{format} are:
8692 @item @strong{Internal Component}
8693 @strong{Resulting Component}
8719 @code{GL_INVALID_ENUM} is generated if @var{target} is not
8720 @code{GL_HISTOGRAM}.
8722 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
8725 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
8728 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8729 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
8730 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
8731 and @var{format} is not @code{GL_RGB}.
8733 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8734 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
8735 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
8736 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
8737 @code{GL_UNSIGNED_INT_10_10_10_2}, or
8738 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
8739 @code{GL_RGBA} nor @code{GL_BGRA}.
8741 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8742 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
8743 object's data store is currently mapped.
8745 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8746 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
8747 would be packed to the buffer object such that the memory writes
8748 required would exceed the data store size.
8750 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8751 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{values}
8752 is not evenly divisible into the number of bytes needed to store in
8753 memory a datum indicated by @var{type}.
8755 @code{GL_INVALID_OPERATION} is generated if @code{glGetHistogram} is
8756 executed between the execution of @code{glBegin} and the corresponding
8757 execution of @code{glEnd}.
8761 @deftypefun void glGetLightfv light pname params
8762 @deftypefunx void glGetLightiv light pname params
8763 Return light source parameter values.
8767 Specifies a light source. The number of possible lights depends on the
8768 implementation, but at least eight lights are supported. They are
8769 identified by symbolic names of the form @code{GL_LIGHT}@r{@var{i}}
8770 where @r{@var{i}} ranges from 0 to the value of @code{GL_MAX_LIGHTS} -
8774 Specifies a light source parameter for @var{light}. Accepted symbolic
8775 names are @code{GL_AMBIENT}, @code{GL_DIFFUSE}, @code{GL_SPECULAR},
8776 @code{GL_POSITION}, @code{GL_SPOT_DIRECTION}, @code{GL_SPOT_EXPONENT},
8777 @code{GL_SPOT_CUTOFF}, @code{GL_CONSTANT_ATTENUATION},
8778 @code{GL_LINEAR_ATTENUATION}, and @code{GL_QUADRATIC_ATTENUATION}.
8781 Returns the requested data.
8785 @code{glGetLight} returns in @var{params} the value or values of a light
8786 source parameter. @var{light} names the light and is a symbolic name of
8787 the form @code{GL_LIGHT}@r{@var{i}} where i ranges from 0 to the value
8788 of @code{GL_MAX_LIGHTS} - 1. @code{GL_MAX_LIGHTS} is an implementation
8789 dependent constant that is greater than or equal to eight. @var{pname}
8790 specifies one of ten light source parameters, again by symbolic name.
8792 The following parameters are defined:
8795 @item @code{GL_AMBIENT}
8796 @var{params} returns four integer or floating-point values representing
8797 the ambient intensity of the light source. Integer values, when
8798 requested, are linearly mapped from the internal floating-point
8799 representation such that 1.0 maps to the most positive representable
8800 integer value, and @r{-1.0} maps to the most negative representable
8801 integer value. If the internal value is outside the range @r{[-1,1]},
8802 the corresponding integer return value is undefined. The initial value
8805 @item @code{GL_DIFFUSE}
8806 @var{params} returns four integer or floating-point values representing
8807 the diffuse intensity of the light source. Integer values, when
8808 requested, are linearly mapped from the internal floating-point
8809 representation such that 1.0 maps to the most positive representable
8810 integer value, and @r{-1.0} maps to the most negative representable
8811 integer value. If the internal value is outside the range @r{[-1,1]},
8812 the corresponding integer return value is undefined. The initial value
8813 for @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial
8814 value is (0, 0, 0, 0).
8816 @item @code{GL_SPECULAR}
8817 @var{params} returns four integer or floating-point values representing
8818 the specular intensity of the light source. Integer values, when
8819 requested, are linearly mapped from the internal floating-point
8820 representation such that 1.0 maps to the most positive representable
8821 integer value, and @r{-1.0} maps to the most negative representable
8822 integer value. If the internal value is outside the range @r{[-1,1]},
8823 the corresponding integer return value is undefined. The initial value
8824 for @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial
8825 value is (0, 0, 0, 0).
8827 @item @code{GL_POSITION}
8828 @var{params} returns four integer or floating-point values representing
8829 the position of the light source. Integer values, when requested, are
8830 computed by rounding the internal floating-point values to the nearest
8831 integer value. The returned values are those maintained in eye
8832 coordinates. They will not be equal to the values specified using
8833 @code{glLight}, unless the modelview matrix was identity at the time
8834 @code{glLight} was called. The initial value is (0, 0, 1, 0).
8836 @item @code{GL_SPOT_DIRECTION}
8837 @var{params} returns three integer or floating-point values representing
8838 the direction of the light source. Integer values, when requested, are
8839 computed by rounding the internal floating-point values to the nearest
8840 integer value. The returned values are those maintained in eye
8841 coordinates. They will not be equal to the values specified using
8842 @code{glLight}, unless the modelview matrix was identity at the time
8843 @code{glLight} was called. Although spot direction is normalized before
8844 being used in the lighting equation, the returned values are the
8845 transformed versions of the specified values prior to normalization. The
8846 initial value is @r{(0,0-1)}.
8848 @item @code{GL_SPOT_EXPONENT}
8849 @var{params} returns a single integer or floating-point value
8850 representing the spot exponent of the light. An integer value, when
8851 requested, is computed by rounding the internal floating-point
8852 representation to the nearest integer. The initial value is 0.
8854 @item @code{GL_SPOT_CUTOFF}
8855 @var{params} returns a single integer or floating-point value
8856 representing the spot cutoff angle of the light. An integer value, when
8857 requested, is computed by rounding the internal floating-point
8858 representation to the nearest integer. The initial value is 180.
8860 @item @code{GL_CONSTANT_ATTENUATION}
8861 @var{params} returns a single integer or floating-point value
8862 representing the constant (not distance-related) attenuation of the
8863 light. An integer value, when requested, is computed by rounding the
8864 internal floating-point representation to the nearest integer. The
8867 @item @code{GL_LINEAR_ATTENUATION}
8868 @var{params} returns a single integer or floating-point value
8869 representing the linear attenuation of the light. An integer value, when
8870 requested, is computed by rounding the internal floating-point
8871 representation to the nearest integer. The initial value is 0.
8873 @item @code{GL_QUADRATIC_ATTENUATION}
8874 @var{params} returns a single integer or floating-point value
8875 representing the quadratic attenuation of the light. An integer value,
8876 when requested, is computed by rounding the internal floating-point
8877 representation to the nearest integer. The initial value is 0.
8881 @code{GL_INVALID_ENUM} is generated if @var{light} or @var{pname} is not
8884 @code{GL_INVALID_OPERATION} is generated if @code{glGetLight} is
8885 executed between the execution of @code{glBegin} and the corresponding
8886 execution of @code{glEnd}.
8890 @deftypefun void glGetMapdv target query v
8891 @deftypefunx void glGetMapfv target query v
8892 @deftypefunx void glGetMapiv target query v
8893 Return evaluator parameters.
8897 Specifies the symbolic name of a map. Accepted values are
8898 @code{GL_MAP1_COLOR_4}, @code{GL_MAP1_INDEX}, @code{GL_MAP1_NORMAL},
8899 @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2},
8900 @code{GL_MAP1_TEXTURE_COORD_3}, @code{GL_MAP1_TEXTURE_COORD_4},
8901 @code{GL_MAP1_VERTEX_3}, @code{GL_MAP1_VERTEX_4},
8902 @code{GL_MAP2_COLOR_4}, @code{GL_MAP2_INDEX}, @code{GL_MAP2_NORMAL},
8903 @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2},
8904 @code{GL_MAP2_TEXTURE_COORD_3}, @code{GL_MAP2_TEXTURE_COORD_4},
8905 @code{GL_MAP2_VERTEX_3}, and @code{GL_MAP2_VERTEX_4}.
8908 Specifies which parameter to return. Symbolic names @code{GL_COEFF},
8909 @code{GL_ORDER}, and @code{GL_DOMAIN} are accepted.
8912 Returns the requested data.
8916 @code{glMap1} and @code{glMap2} define evaluators. @code{glGetMap}
8917 returns evaluator parameters. @var{target} chooses a map, @var{query}
8918 selects a specific parameter, and @var{v} points to storage where the
8919 values will be returned.
8921 The acceptable values for the @var{target} parameter are described in
8922 the @code{glMap1} and @code{glMap2} reference pages.
8924 @var{query} can assume the following values:
8927 @item @code{GL_COEFF}
8928 @var{v} returns the control points for the evaluator function.
8929 One-dimensional evaluators return @r{@var{order}} control points, and
8930 two-dimensional evaluators return @r{@var{uorder}×@var{vorder}} control
8931 points. Each control point consists of one, two, three, or four integer,
8932 single-precision floating-point, or double-precision floating-point
8933 values, depending on the type of the evaluator. The GL returns
8934 two-dimensional control points in row-major order, incrementing the
8935 @r{@var{uorder}} index quickly and the @r{@var{vorder}} index after each
8936 row. Integer values, when requested, are computed by rounding the
8937 internal floating-point values to the nearest integer values.
8939 @item @code{GL_ORDER}
8940 @var{v} returns the order of the evaluator function. One-dimensional
8941 evaluators return a single value, @r{@var{order}}. The initial value is
8942 1. Two-dimensional evaluators return two values, @r{@var{uorder}} and
8943 @r{@var{vorder}}. The initial value is 1,1.
8945 @item @code{GL_DOMAIN}
8946 @var{v} returns the linear @r{@var{u}} and @r{@var{v}} mapping
8947 parameters. One-dimensional evaluators return two values, @r{@var{u1}}
8948 and @r{@var{u2}}, as specified by @code{glMap1}. Two-dimensional
8949 evaluators return four values (@r{@var{u1}}, @r{@var{u2}}, @r{@var{v1}},
8950 and @r{@var{v2}}) as specified by @code{glMap2}. Integer values, when
8951 requested, are computed by rounding the internal floating-point values
8952 to the nearest integer values.
8956 @code{GL_INVALID_ENUM} is generated if either @var{target} or
8957 @var{query} is not an accepted value.
8959 @code{GL_INVALID_OPERATION} is generated if @code{glGetMap} is executed
8960 between the execution of @code{glBegin} and the corresponding execution
8965 @deftypefun void glGetMaterialfv face pname params
8966 @deftypefunx void glGetMaterialiv face pname params
8967 Return material parameters.
8971 Specifies which of the two materials is being queried. @code{GL_FRONT}
8972 or @code{GL_BACK} are accepted, representing the front and back
8973 materials, respectively.
8976 Specifies the material parameter to return. @code{GL_AMBIENT},
8977 @code{GL_DIFFUSE}, @code{GL_SPECULAR}, @code{GL_EMISSION},
8978 @code{GL_SHININESS}, and @code{GL_COLOR_INDEXES} are accepted.
8981 Returns the requested data.
8985 @code{glGetMaterial} returns in @var{params} the value or values of
8986 parameter @var{pname} of material @var{face}. Six parameters are
8990 @item @code{GL_AMBIENT}
8991 @var{params} returns four integer or floating-point values representing
8992 the ambient reflectance of the material. Integer values, when requested,
8993 are linearly mapped from the internal floating-point representation such
8994 that 1.0 maps to the most positive representable integer value, and
8995 @r{-1.0} maps to the most negative representable integer value. If the
8996 internal value is outside the range @r{[-1,1]}, the corresponding
8997 integer return value is undefined. The initial value is (0.2, 0.2, 0.2,
9000 @item @code{GL_DIFFUSE}
9001 @var{params} returns four integer or floating-point values representing
9002 the diffuse reflectance of the material. Integer values, when requested,
9003 are linearly mapped from the internal floating-point representation such
9004 that 1.0 maps to the most positive representable integer value, and
9005 @r{-1.0} maps to the most negative representable integer value. If the
9006 internal value is outside the range @r{[-1,1]}, the corresponding
9007 integer return value is undefined. The initial value is (0.8, 0.8, 0.8,
9010 @item @code{GL_SPECULAR}
9011 @var{params} returns four integer or floating-point values representing
9012 the specular reflectance of the material. Integer values, when
9013 requested, are linearly mapped from the internal floating-point
9014 representation such that 1.0 maps to the most positive representable
9015 integer value, and @r{-1.0} maps to the most negative representable
9016 integer value. If the internal value is outside the range @r{[-1,1]},
9017 the corresponding integer return value is undefined. The initial value
9020 @item @code{GL_EMISSION}
9021 @var{params} returns four integer or floating-point values representing
9022 the emitted light intensity of the material. Integer values, when
9023 requested, are linearly mapped from the internal floating-point
9024 representation such that 1.0 maps to the most positive representable
9025 integer value, and @r{-1.0} maps to the most negative representable
9026 integer value. If the internal value is outside the range @r{[-1,1]},
9027 the corresponding integer return value is undefined. The initial value
9030 @item @code{GL_SHININESS}
9031 @var{params} returns one integer or floating-point value representing
9032 the specular exponent of the material. Integer values, when requested,
9033 are computed by rounding the internal floating-point value to the
9034 nearest integer value. The initial value is 0.
9036 @item @code{GL_COLOR_INDEXES}
9037 @var{params} returns three integer or floating-point values representing
9038 the ambient, diffuse, and specular indices of the material. These
9039 indices are used only for color index lighting. (All the other
9040 parameters are used only for RGBA lighting.) Integer values, when
9041 requested, are computed by rounding the internal floating-point values
9042 to the nearest integer values.
9046 @code{GL_INVALID_ENUM} is generated if @var{face} or @var{pname} is not
9049 @code{GL_INVALID_OPERATION} is generated if @code{glGetMaterial} is
9050 executed between the execution of @code{glBegin} and the corresponding
9051 execution of @code{glEnd}.
9055 @deftypefun void glGetMinmaxParameterfv target pname params
9056 @deftypefunx void glGetMinmaxParameteriv target pname params
9057 Get minmax parameters.
9061 Must be @code{GL_MINMAX}.
9064 The parameter to be retrieved. Must be one of @code{GL_MINMAX_FORMAT} or
9065 @code{GL_MINMAX_SINK}.
9068 A pointer to storage for the retrieved parameters.
9072 @code{glGetMinmaxParameter} retrieves parameters for the current minmax
9073 table by setting @var{pname} to one of the following values:
9078 @item @strong{Parameter}
9079 @strong{Description}
9081 @item @code{GL_MINMAX_FORMAT}
9082 Internal format of minmax table
9084 @item @code{GL_MINMAX_SINK}
9085 Value of the @var{sink} parameter
9091 @code{GL_INVALID_ENUM} is generated if @var{target} is not
9094 @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the
9097 @code{GL_INVALID_OPERATION} is generated if @code{glGetMinmaxParameter}
9098 is executed between the execution of @code{glBegin} and the
9099 corresponding execution of @code{glEnd}.
9103 @deftypefun void glGetMinmax target reset format types values
9104 Get minimum and maximum pixel values.
9108 Must be @code{GL_MINMAX}.
9111 If @code{GL_TRUE}, all entries in the minmax table that are actually
9112 returned are reset to their initial values. (Other entries are
9113 unaltered.) If @code{GL_FALSE}, the minmax table is unaltered.
9116 The format of the data to be returned in @var{values}. Must be one of
9117 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
9118 @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA},
9119 @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}.
9122 The type of the data to be returned in @var{values}. Symbolic constants
9123 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
9124 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
9125 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
9126 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
9127 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
9128 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
9129 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
9130 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
9131 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
9134 A pointer to storage for the returned values.
9138 @code{glGetMinmax} returns the accumulated minimum and maximum pixel
9139 values (computed on a per-component basis) in a one-dimensional image of
9140 width 2. The first set of return values are the minima, and the second
9141 set of return values are the maxima. The format of the return values is
9142 determined by @var{format}, and their type is determined by @var{types}.
9144 If a non-zero named buffer object is bound to the
9145 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while
9146 minimum and maximum pixel values are requested, @var{values} is treated
9147 as a byte offset into the buffer object's data store.
9149 No pixel transfer operations are performed on the return values, but
9150 pixel storage modes that are applicable to one-dimensional images are
9151 performed. Color components that are requested in the specified
9152 @var{format}, but that are not included in the internal format of the
9153 minmax table, are returned as zero. The assignment of internal color
9154 components to the components requested by @var{format} are as follows:
9159 @item @strong{Internal Component}
9160 @strong{Resulting Component}
9184 If @var{reset} is @code{GL_TRUE}, the minmax table entries corresponding
9185 to the return values are reset to their initial values. Minimum and
9186 maximum values that are not returned are not modified, even if
9187 @var{reset} is @code{GL_TRUE}.
9189 @code{GL_INVALID_ENUM} is generated if @var{target} is not
9192 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
9195 @code{GL_INVALID_ENUM} is generated if @var{types} is not one of the
9198 @code{GL_INVALID_OPERATION} is generated if @var{types} is one of
9199 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
9200 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
9201 and @var{format} is not @code{GL_RGB}.
9203 @code{GL_INVALID_OPERATION} is generated if @var{types} is one of
9204 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
9205 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
9206 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
9207 @code{GL_UNSIGNED_INT_10_10_10_2}, or
9208 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
9209 @code{GL_RGBA} nor @code{GL_BGRA}.
9211 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9212 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
9213 object's data store is currently mapped.
9215 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9216 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
9217 would be packed to the buffer object such that the memory writes
9218 required would exceed the data store size.
9220 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9221 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{values}
9222 is not evenly divisible into the number of bytes needed to store in
9223 memory a datum indicated by @var{type}.
9225 @code{GL_INVALID_OPERATION} is generated if @code{glGetMinmax} is
9226 executed between the execution of @code{glBegin} and the corresponding
9227 execution of @code{glEnd}.
9231 @deftypefun void glGetPixelMapfv map data
9232 @deftypefunx void glGetPixelMapuiv map data
9233 @deftypefunx void glGetPixelMapusv map data
9234 Return the specified pixel map.
9238 Specifies the name of the pixel map to return. Accepted values are
9239 @code{GL_PIXEL_MAP_I_TO_I}, @code{GL_PIXEL_MAP_S_TO_S},
9240 @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G},
9241 @code{GL_PIXEL_MAP_I_TO_B}, @code{GL_PIXEL_MAP_I_TO_A},
9242 @code{GL_PIXEL_MAP_R_TO_R}, @code{GL_PIXEL_MAP_G_TO_G},
9243 @code{GL_PIXEL_MAP_B_TO_B}, and @code{GL_PIXEL_MAP_A_TO_A}.
9246 Returns the pixel map contents.
9250 See the @code{glPixelMap} reference page for a description of the
9251 acceptable values for the @var{map} parameter. @code{glGetPixelMap}
9252 returns in @var{data} the contents of the pixel map specified in
9253 @var{map}. Pixel maps are used during the execution of
9254 @code{glReadPixels}, @code{glDrawPixels}, @code{glCopyPixels},
9255 @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D},
9256 @code{glTexSubImage1D}, @code{glTexSubImage2D}, @code{glTexSubImage3D},
9257 @code{glCopyTexImage1D}, @code{glCopyTexImage2D},
9258 @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D}, and
9259 @code{glCopyTexSubImage3D}. to map color indices, stencil indices, color
9260 components, and depth components to other values.
9262 If a non-zero named buffer object is bound to the
9263 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
9264 pixel map is requested, @var{data} is treated as a byte offset into the
9265 buffer object's data store.
9267 Unsigned integer values, if requested, are linearly mapped from the
9268 internal fixed or floating-point representation such that 1.0 maps to
9269 the largest representable integer value, and 0.0 maps to 0. Return
9270 unsigned integer values are undefined if the map value was not in the
9273 To determine the required size of @var{map}, call @code{glGet} with the
9274 appropriate symbolic constant.
9276 @code{GL_INVALID_ENUM} is generated if @var{map} is not an accepted
9279 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9280 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
9281 object's data store is currently mapped.
9283 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9284 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
9285 would be packed to the buffer object such that the memory writes
9286 required would exceed the data store size.
9288 @code{GL_INVALID_OPERATION} is generated by @code{glGetPixelMapfv} if a
9289 non-zero buffer object name is bound to the @code{GL_PIXEL_PACK_BUFFER}
9290 target and @var{data} is not evenly divisible into the number of bytes
9291 needed to store in memory a GLfloat datum.
9293 @code{GL_INVALID_OPERATION} is generated by @code{glGetPixelMapuiv} if a
9294 non-zero buffer object name is bound to the @code{GL_PIXEL_PACK_BUFFER}
9295 target and @var{data} is not evenly divisible into the number of bytes
9296 needed to store in memory a GLuint datum.
9298 @code{GL_INVALID_OPERATION} is generated by @code{glGetPixelMapusv} if a
9299 non-zero buffer object name is bound to the @code{GL_PIXEL_PACK_BUFFER}
9300 target and @var{data} is not evenly divisible into the number of bytes
9301 needed to store in memory a GLushort datum.
9303 @code{GL_INVALID_OPERATION} is generated if @code{glGetPixelMap} is
9304 executed between the execution of @code{glBegin} and the corresponding
9305 execution of @code{glEnd}.
9309 @deftypefun void glGetPointerv pname params
9310 Return the address of the specified pointer.
9314 Specifies the array or buffer pointer to be returned. Symbolic constants
9315 @code{GL_COLOR_ARRAY_POINTER}, @code{GL_EDGE_FLAG_ARRAY_POINTER},
9316 @code{GL_FOG_COORD_ARRAY_POINTER}, @code{GL_FEEDBACK_BUFFER_POINTER},
9317 @code{GL_INDEX_ARRAY_POINTER}, @code{GL_NORMAL_ARRAY_POINTER},
9318 @code{GL_SECONDARY_COLOR_ARRAY_POINTER},
9319 @code{GL_SELECTION_BUFFER_POINTER},
9320 @code{GL_TEXTURE_COORD_ARRAY_POINTER}, or @code{GL_VERTEX_ARRAY_POINTER}
9324 Returns the pointer value specified by @var{pname}.
9328 @code{glGetPointerv} returns pointer information. @var{pname} is a
9329 symbolic constant indicating the pointer to be returned, and
9330 @var{params} is a pointer to a location in which to place the returned
9333 For all @var{pname} arguments except @code{GL_FEEDBACK_BUFFER_POINTER}
9334 and @code{GL_SELECTION_BUFFER_POINTER}, if a non-zero named buffer
9335 object was bound to the @code{GL_ARRAY_BUFFER} target (see
9336 @code{glBindBuffer}) when the desired pointer was previously specified,
9337 the pointer returned is a byte offset into the buffer object's data
9338 store. Buffer objects are only available in OpenGL versions 1.5 and
9341 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
9346 @deftypefun void glGetPolygonStipple pattern
9347 Return the polygon stipple pattern.
9351 Returns the stipple pattern. The initial value is all 1's.
9355 @code{glGetPolygonStipple} returns to @var{pattern} a @r{32×32} polygon
9356 stipple pattern. The pattern is packed into memory as if
9357 @code{glReadPixels} with both @var{height} and @var{width} of 32,
9358 @var{type} of @code{GL_BITMAP}, and @var{format} of
9359 @code{GL_COLOR_INDEX} were called, and the stipple pattern were stored
9360 in an internal @r{32×32} color index buffer. Unlike @code{glReadPixels},
9361 however, pixel transfer operations (shift, offset, pixel map) are not
9362 applied to the returned stipple image.
9364 If a non-zero named buffer object is bound to the
9365 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
9366 polygon stipple pattern is requested, @var{pattern} is treated as a byte
9367 offset into the buffer object's data store.
9369 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9370 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
9371 object's data store is currently mapped.
9373 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9374 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
9375 would be packed to the buffer object such that the memory writes
9376 required would exceed the data store size.
9378 @code{GL_INVALID_OPERATION} is generated if @code{glGetPolygonStipple}
9379 is executed between the execution of @code{glBegin} and the
9380 corresponding execution of @code{glEnd}.
9384 @deftypefun void glGetProgramInfoLog program maxLength length infoLog
9385 Returns the information log for a program object.
9389 Specifies the program object whose information log is to be queried.
9391 @item @var{maxLength}
9392 Specifies the size of the character buffer for storing the returned
9396 Returns the length of the string returned in @var{infoLog} (excluding
9397 the null terminator).
9400 Specifies an array of characters that is used to return the information
9405 @code{glGetProgramInfoLog} returns the information log for the specified
9406 program object. The information log for a program object is modified
9407 when the program object is linked or validated. The string that is
9408 returned will be null terminated.
9410 @code{glGetProgramInfoLog} returns in @var{infoLog} as much of the
9411 information log as it can, up to a maximum of @var{maxLength}
9412 characters. The number of characters actually returned, excluding the
9413 null termination character, is specified by @var{length}. If the length
9414 of the returned string is not required, a value of @code{NULL} can be
9415 passed in the @var{length} argument. The size of the buffer required to
9416 store the returned information log can be obtained by calling
9417 @code{glGetProgram} with the value @code{GL_INFO_LOG_LENGTH}.
9419 The information log for a program object is either an empty string, or a
9420 string containing information about the last link operation, or a string
9421 containing information about the last validation operation. It may
9422 contain diagnostic messages, warning messages, and other information.
9423 When a program object is created, its information log will be a string
9426 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
9427 generated by OpenGL.
9429 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
9432 @code{GL_INVALID_VALUE} is generated if @var{maxLength} is less than 0.
9434 @code{GL_INVALID_OPERATION} is generated if @code{glGetProgramInfoLog}
9435 is executed between the execution of @code{glBegin} and the
9436 corresponding execution of @code{glEnd}.
9440 @deftypefun void glGetProgramiv program pname params
9441 Returns a parameter from a program object.
9445 Specifies the program object to be queried.
9448 Specifies the object parameter. Accepted symbolic names are
9449 @code{GL_DELETE_STATUS}, @code{GL_LINK_STATUS},
9450 @code{GL_VALIDATE_STATUS}, @code{GL_INFO_LOG_LENGTH},
9451 @code{GL_ATTACHED_SHADERS}, @code{GL_ACTIVE_ATTRIBUTES},
9452 @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH}, @code{GL_ACTIVE_UNIFORMS},
9453 @code{GL_ACTIVE_UNIFORM_MAX_LENGTH}.
9456 Returns the requested object parameter.
9460 @code{glGetProgram} returns in @var{params} the value of a parameter for
9461 a specific program object. The following parameters are defined:
9464 @item @code{GL_DELETE_STATUS}
9467 @var{params} returns @code{GL_TRUE} if @var{program} is currently
9468 flagged for deletion, and @code{GL_FALSE} otherwise.
9470 @item @code{GL_LINK_STATUS}
9473 @var{params} returns @code{GL_TRUE} if the last link operation on
9474 @var{program} was successful, and @code{GL_FALSE} otherwise.
9476 @item @code{GL_VALIDATE_STATUS}
9479 @var{params} returns @code{GL_TRUE} or if the last validation operation
9480 on @var{program} was successful, and @code{GL_FALSE} otherwise.
9482 @item @code{GL_INFO_LOG_LENGTH}
9485 @var{params} returns the number of characters in the information log for
9486 @var{program} including the null termination character (i.e., the size
9487 of the character buffer required to store the information log). If
9488 @var{program} has no information log, a value of 0 is returned.
9490 @item @code{GL_ATTACHED_SHADERS}
9493 @var{params} returns the number of shader objects attached to
9496 @item @code{GL_ACTIVE_ATTRIBUTES}
9499 @var{params} returns the number of active attribute variables for
9502 @item @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH}
9505 @var{params} returns the length of the longest active attribute name for
9506 @var{program}, including the null termination character (i.e., the size
9507 of the character buffer required to store the longest attribute name).
9508 If no active attributes exist, 0 is returned.
9510 @item @code{GL_ACTIVE_UNIFORMS}
9513 @var{params} returns the number of active uniform variables for
9516 @item @code{GL_ACTIVE_UNIFORM_MAX_LENGTH}
9519 @var{params} returns the length of the longest active uniform variable
9520 name for @var{program}, including the null termination character (i.e.,
9521 the size of the character buffer required to store the longest uniform
9522 variable name). If no active uniform variables exist, 0 is returned.
9526 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
9527 generated by OpenGL.
9529 @code{GL_INVALID_OPERATION} is generated if @var{program} does not refer
9530 to a program object.
9532 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
9535 @code{GL_INVALID_OPERATION} is generated if @code{glGetProgram} is
9536 executed between the execution of @code{glBegin} and the corresponding
9537 execution of @code{glEnd}.
9541 @deftypefun void glGetQueryiv target pname params
9542 Return parameters of a query object target.
9546 Specifies a query object target. Must be @code{GL_SAMPLES_PASSED}.
9549 Specifies the symbolic name of a query object target parameter. Accepted
9550 values are @code{GL_CURRENT_QUERY} or @code{GL_QUERY_COUNTER_BITS}.
9553 Returns the requested data.
9557 @code{glGetQueryiv} returns in @var{params} a selected parameter of the
9558 query object target specified by @var{target}.
9560 @var{pname} names a specific query object target parameter. When
9561 @var{target} is @code{GL_SAMPLES_PASSED}, @var{pname} can be as follows:
9564 @item @code{GL_CURRENT_QUERY}
9565 @var{params} returns the name of the currently active occlusion query
9566 object. If no occlusion query is active, 0 is returned. The initial
9569 @item @code{GL_QUERY_COUNTER_BITS}
9570 @var{params} returns the number of bits in the query counter used to
9571 accumulate passing samples. If the number of bits returned is 0, the
9572 implementation does not support a query counter, and the results
9573 obtained from @code{glGetQueryObject} are useless.
9577 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
9578 not an accepted value.
9580 @code{GL_INVALID_OPERATION} is generated if @code{glGetQueryiv} is
9581 executed between the execution of @code{glBegin} and the corresponding
9582 execution of @code{glEnd}.
9586 @deftypefun void glGetQueryObjectiv id pname params
9587 @deftypefunx void glGetQueryObjectuiv id pname params
9588 Return parameters of a query object.
9592 Specifies the name of a query object.
9595 Specifies the symbolic name of a query object parameter. Accepted values
9596 are @code{GL_QUERY_RESULT} or @code{GL_QUERY_RESULT_AVAILABLE}.
9599 Returns the requested data.
9603 @code{glGetQueryObject} returns in @var{params} a selected parameter of
9604 the query object specified by @var{id}.
9606 @var{pname} names a specific query object parameter. @var{pname} can be
9610 @item @code{GL_QUERY_RESULT}
9611 @var{params} returns the value of the query object's passed samples
9612 counter. The initial value is 0.
9614 @item @code{GL_QUERY_RESULT_AVAILABLE}
9615 @var{params} returns whether the passed samples counter is immediately
9616 available. If a delay would occur waiting for the query result,
9617 @code{GL_FALSE} is returned. Otherwise, @code{GL_TRUE} is returned,
9618 which also indicates that the results of all previous queries are
9623 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
9626 @code{GL_INVALID_OPERATION} is generated if @var{id} is not the name of
9629 @code{GL_INVALID_OPERATION} is generated if @var{id} is the name of a
9630 currently active query object.
9632 @code{GL_INVALID_OPERATION} is generated if @code{glGetQueryObject} is
9633 executed between the execution of @code{glBegin} and the corresponding
9634 execution of @code{glEnd}.
9638 @deftypefun void glGetSeparableFilter target format type row column span
9639 Get separable convolution filter kernel images.
9643 The separable filter to be retrieved. Must be @code{GL_SEPARABLE_2D}.
9646 Format of the output images. Must be one of @code{GL_RED},
9647 @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB},
9648 @code{GL_BGR}@code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, or
9649 @code{GL_LUMINANCE_ALPHA}.
9652 Data type of components in the output images. Symbolic constants
9653 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
9654 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
9655 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
9656 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
9657 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
9658 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
9659 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
9660 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
9661 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
9664 Pointer to storage for the row filter image.
9667 Pointer to storage for the column filter image.
9670 Pointer to storage for the span filter image (currently unused).
9674 @code{glGetSeparableFilter} returns the two one-dimensional filter
9675 kernel images for the current separable 2D convolution filter. The row
9676 image is placed in @var{row} and the column image is placed in
9677 @var{column} according to the specifications in @var{format} and
9678 @var{type}. (In the current implementation, @var{span} is not affected
9679 in any way.) No pixel transfer operations are performed on the images,
9680 but the relevant pixel storage modes are applied.
9682 If a non-zero named buffer object is bound to the
9683 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
9684 separable convolution filter is requested, @var{row}, @var{column}, and
9685 @var{span} are treated as a byte offset into the buffer object's data
9688 Color components that are present in @var{format} but not included in
9689 the internal format of the filters are returned as zero. The assignments
9690 of internal color components to the components of @var{format} are as
9696 @item @strong{Internal Component}
9697 @strong{Resulting Component}
9727 @code{GL_INVALID_ENUM} is generated if @var{target} is not
9728 @code{GL_SEPARABLE_2D}.
9730 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
9733 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
9736 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
9737 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
9738 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
9739 and @var{format} is not @code{GL_RGB}.
9741 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
9742 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
9743 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
9744 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
9745 @code{GL_UNSIGNED_INT_10_10_10_2}, or
9746 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
9747 @code{GL_RGBA} nor @code{GL_BGRA}.
9749 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9750 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
9751 object's data store is currently mapped.
9753 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9754 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
9755 would be packed to the buffer object such that the memory writes
9756 required would exceed the data store size.
9758 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9759 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{row} or
9760 @var{column} is not evenly divisible into the number of bytes needed to
9761 store in memory a datum indicated by @var{type}.
9763 @code{GL_INVALID_OPERATION} is generated if @code{glGetSeparableFilter}
9764 is executed between the execution of @code{glBegin} and the
9765 corresponding execution of @code{glEnd}.
9769 @deftypefun void glGetShaderInfoLog shader maxLength length infoLog
9770 Returns the information log for a shader object.
9774 Specifies the shader object whose information log is to be queried.
9776 @item @var{maxLength}
9777 Specifies the size of the character buffer for storing the returned
9781 Returns the length of the string returned in @var{infoLog} (excluding
9782 the null terminator).
9785 Specifies an array of characters that is used to return the information
9790 @code{glGetShaderInfoLog} returns the information log for the specified
9791 shader object. The information log for a shader object is modified when
9792 the shader is compiled. The string that is returned will be null
9795 @code{glGetShaderInfoLog} returns in @var{infoLog} as much of the
9796 information log as it can, up to a maximum of @var{maxLength}
9797 characters. The number of characters actually returned, excluding the
9798 null termination character, is specified by @var{length}. If the length
9799 of the returned string is not required, a value of @code{NULL} can be
9800 passed in the @var{length} argument. The size of the buffer required to
9801 store the returned information log can be obtained by calling
9802 @code{glGetShader} with the value @code{GL_INFO_LOG_LENGTH}.
9804 The information log for a shader object is a string that may contain
9805 diagnostic messages, warning messages, and other information about the
9806 last compile operation. When a shader object is created, its information
9807 log will be a string of length 0.
9809 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
9810 generated by OpenGL.
9812 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
9815 @code{GL_INVALID_VALUE} is generated if @var{maxLength} is less than 0.
9817 @code{GL_INVALID_OPERATION} is generated if @code{glGetShaderInfoLog} is
9818 executed between the execution of @code{glBegin} and the corresponding
9819 execution of @code{glEnd}.
9823 @deftypefun void glGetShaderSource shader bufSize length source
9824 Returns the source code string from a shader object.
9828 Specifies the shader object to be queried.
9831 Specifies the size of the character buffer for storing the returned
9835 Returns the length of the string returned in @var{source} (excluding the
9839 Specifies an array of characters that is used to return the source code
9844 @code{glGetShaderSource} returns the concatenation of the source code
9845 strings from the shader object specified by @var{shader}. The source
9846 code strings for a shader object are the result of a previous call to
9847 @code{glShaderSource}. The string returned by the function will be null
9850 @code{glGetShaderSource} returns in @var{source} as much of the source
9851 code string as it can, up to a maximum of @var{bufSize} characters. The
9852 number of characters actually returned, excluding the null termination
9853 character, is specified by @var{length}. If the length of the returned
9854 string is not required, a value of @code{NULL} can be passed in the
9855 @var{length} argument. The size of the buffer required to store the
9856 returned source code string can be obtained by calling
9857 @code{glGetShader} with the value @code{GL_SHADER_SOURCE_LENGTH}.
9859 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
9860 generated by OpenGL.
9862 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
9865 @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0.
9867 @code{GL_INVALID_OPERATION} is generated if @code{glGetShaderSource} is
9868 executed between the execution of @code{glBegin} and the corresponding
9869 execution of @code{glEnd}.
9873 @deftypefun void glGetShaderiv shader pname params
9874 Returns a parameter from a shader object.
9878 Specifies the shader object to be queried.
9881 Specifies the object parameter. Accepted symbolic names are
9882 @code{GL_SHADER_TYPE}, @code{GL_DELETE_STATUS},
9883 @code{GL_COMPILE_STATUS}, @code{GL_INFO_LOG_LENGTH},
9884 @code{GL_SHADER_SOURCE_LENGTH}.
9887 Returns the requested object parameter.
9891 @code{glGetShader} returns in @var{params} the value of a parameter for
9892 a specific shader object. The following parameters are defined:
9895 @item @code{GL_SHADER_TYPE}
9896 @var{params} returns @code{GL_VERTEX_SHADER} if @var{shader} is a vertex
9897 shader object, and @code{GL_FRAGMENT_SHADER} if @var{shader} is a
9898 fragment shader object.
9900 @item @code{GL_DELETE_STATUS}
9901 @var{params} returns @code{GL_TRUE} if @var{shader} is currently flagged
9902 for deletion, and @code{GL_FALSE} otherwise.
9904 @item @code{GL_COMPILE_STATUS}
9905 @var{params} returns @code{GL_TRUE} if the last compile operation on
9906 @var{shader} was successful, and @code{GL_FALSE} otherwise.
9908 @item @code{GL_INFO_LOG_LENGTH}
9909 @var{params} returns the number of characters in the information log for
9910 @var{shader} including the null termination character (i.e., the size of
9911 the character buffer required to store the information log). If
9912 @var{shader} has no information log, a value of 0 is returned.
9914 @item @code{GL_SHADER_SOURCE_LENGTH}
9915 @var{params} returns the length of the concatenation of the source
9916 strings that make up the shader source for the @var{shader}, including
9917 the null termination character. (i.e., the size of the character buffer
9918 required to store the shader source). If no source code exists, 0 is
9923 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
9924 generated by OpenGL.
9926 @code{GL_INVALID_OPERATION} is generated if @var{shader} does not refer
9929 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
9932 @code{GL_INVALID_OPERATION} is generated if @code{glGetShader} is
9933 executed between the execution of @code{glBegin} and the corresponding
9934 execution of @code{glEnd}.
9938 @deftypefun const-GLubyte* glGetString name
9939 Return a string describing the current GL connection.
9943 Specifies a symbolic constant, one of @code{GL_VENDOR},
9944 @code{GL_RENDERER}, @code{GL_VERSION},
9945 @code{GL_SHADING_LANGUAGE_VERSION}, or @code{GL_EXTENSIONS}.
9949 @code{glGetString} returns a pointer to a static string describing some
9950 aspect of the current GL connection. @var{name} can be one of the
9954 @item @code{GL_VENDOR}
9957 Returns the company responsible for this GL implementation. This name
9958 does not change from release to release.
9960 @item @code{GL_RENDERER}
9963 Returns the name of the renderer. This name is typically specific to a
9964 particular configuration of a hardware platform. It does not change from
9967 @item @code{GL_VERSION}
9970 Returns a version or release number.
9972 @item @code{GL_SHADING_LANGUAGE_VERSION}
9975 Returns a version or release number for the shading language.
9977 @item @code{GL_EXTENSIONS}
9980 Returns a space-separated list of supported extensions to GL.
9984 Because the GL does not include queries for the performance
9985 characteristics of an implementation, some applications are written to
9986 recognize known platforms and modify their GL usage based on known
9987 performance characteristics of these platforms. Strings @code{GL_VENDOR}
9988 and @code{GL_RENDERER} together uniquely specify a platform. They do not
9989 change from release to release and should be used by
9990 platform-recognition algorithms.
9992 Some applications want to make use of features that are not part of the
9993 standard GL. These features may be implemented as extensions to the
9994 standard GL. The @code{GL_EXTENSIONS} string is a space-separated list
9995 of supported GL extensions. (Extension names never contain a space
9998 The @code{GL_VERSION} and @code{GL_SHADING_LANGUAGE_VERSION} strings
9999 begin with a version number. The version number uses one of these forms:
10001 @var{major_number.minor_number}@var{major_number.minor_number.release_number}
10003 Vendor-specific information may follow the version number. Its format
10004 depends on the implementation, but a space always separates the version
10005 number and the vendor-specific information.
10007 All strings are null-terminated.
10009 @code{GL_INVALID_ENUM} is generated if @var{name} is not an accepted
10012 @code{GL_INVALID_OPERATION} is generated if @code{glGetString} is
10013 executed between the execution of @code{glBegin} and the corresponding
10014 execution of @code{glEnd}.
10018 @deftypefun void glGetTexEnvfv target pname params
10019 @deftypefunx void glGetTexEnviv target pname params
10020 Return texture environment parameters.
10024 Specifies a texture environment. May be @code{GL_TEXTURE_ENV},
10025 @code{GL_TEXTURE_FILTER_CONTROL}, or @code{GL_POINT_SPRITE}.
10028 Specifies the symbolic name of a texture environment parameter. Accepted
10029 values are @code{GL_TEXTURE_ENV_MODE}, @code{GL_TEXTURE_ENV_COLOR},
10030 @code{GL_TEXTURE_LOD_BIAS}, @code{GL_COMBINE_RGB},
10031 @code{GL_COMBINE_ALPHA}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB},
10032 @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA},
10033 @code{GL_SRC2_ALPHA}, @code{GL_OPERAND0_RGB}, @code{GL_OPERAND1_RGB},
10034 @code{GL_OPERAND2_RGB}, @code{GL_OPERAND0_ALPHA},
10035 @code{GL_OPERAND1_ALPHA}, @code{GL_OPERAND2_ALPHA}, @code{GL_RGB_SCALE},
10036 @code{GL_ALPHA_SCALE}, or @code{GL_COORD_REPLACE}.
10039 Returns the requested data.
10043 @code{glGetTexEnv} returns in @var{params} selected values of a texture
10044 environment that was specified with @code{glTexEnv}. @var{target}
10045 specifies a texture environment.
10047 When @var{target} is @code{GL_TEXTURE_FILTER_CONTROL}, @var{pname} must
10048 be @code{GL_TEXTURE_LOD_BIAS}. When @var{target} is
10049 @code{GL_POINT_SPRITE}, @var{pname} must be @code{GL_COORD_REPLACE}.
10050 When @var{target} is @code{GL_TEXTURE_ENV}, @var{pname} can be
10051 @code{GL_TEXTURE_ENV_MODE}, @code{GL_TEXTURE_ENV_COLOR},
10052 @code{GL_COMBINE_RGB}, @code{GL_COMBINE_ALPHA}, @code{GL_RGB_SCALE},
10053 @code{GL_ALPHA_SCALE}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB},
10054 @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, or
10055 @code{GL_SRC2_ALPHA}.
10057 @var{pname} names a specific texture environment parameter, as follows:
10060 @item @code{GL_TEXTURE_ENV_MODE}
10061 @var{params} returns the single-valued texture environment mode, a
10062 symbolic constant. The initial value is @code{GL_MODULATE}.
10064 @item @code{GL_TEXTURE_ENV_COLOR}
10065 @var{params} returns four integer or floating-point values that are the
10066 texture environment color. Integer values, when requested, are linearly
10067 mapped from the internal floating-point representation such that 1.0
10068 maps to the most positive representable integer, and @r{-1.0} maps to
10069 the most negative representable integer. The initial value is (0, 0, 0,
10072 @item @code{GL_TEXTURE_LOD_BIAS}
10073 @var{params} returns a single floating-point value that is the texture
10074 level-of-detail bias. The initial value is 0.
10076 @item @code{GL_COMBINE_RGB}
10077 @var{params} returns a single symbolic constant value representing the
10078 current RGB combine mode. The initial value is @code{GL_MODULATE}.
10080 @item @code{GL_COMBINE_ALPHA}
10081 @var{params} returns a single symbolic constant value representing the
10082 current alpha combine mode. The initial value is @code{GL_MODULATE}.
10084 @item @code{GL_SRC0_RGB}
10085 @var{params} returns a single symbolic constant value representing the
10086 texture combiner zero's RGB source. The initial value is
10089 @item @code{GL_SRC1_RGB}
10090 @var{params} returns a single symbolic constant value representing the
10091 texture combiner one's RGB source. The initial value is
10092 @code{GL_PREVIOUS}.
10094 @item @code{GL_SRC2_RGB}
10095 @var{params} returns a single symbolic constant value representing the
10096 texture combiner two's RGB source. The initial value is
10097 @code{GL_CONSTANT}.
10099 @item @code{GL_SRC0_ALPHA}
10100 @var{params} returns a single symbolic constant value representing the
10101 texture combiner zero's alpha source. The initial value is
10104 @item @code{GL_SRC1_ALPHA}
10105 @var{params} returns a single symbolic constant value representing the
10106 texture combiner one's alpha source. The initial value is
10107 @code{GL_PREVIOUS}.
10109 @item @code{GL_SRC2_ALPHA}
10110 @var{params} returns a single symbolic constant value representing the
10111 texture combiner two's alpha source. The initial value is
10112 @code{GL_CONSTANT}.
10114 @item @code{GL_OPERAND0_RGB}
10115 @var{params} returns a single symbolic constant value representing the
10116 texture combiner zero's RGB operand. The initial value is
10117 @code{GL_SRC_COLOR}.
10119 @item @code{GL_OPERAND1_RGB}
10120 @var{params} returns a single symbolic constant value representing the
10121 texture combiner one's RGB operand. The initial value is
10122 @code{GL_SRC_COLOR}.
10124 @item @code{GL_OPERAND2_RGB}
10125 @var{params} returns a single symbolic constant value representing the
10126 texture combiner two's RGB operand. The initial value is
10127 @code{GL_SRC_ALPHA}.
10129 @item @code{GL_OPERAND0_ALPHA}
10130 @var{params} returns a single symbolic constant value representing the
10131 texture combiner zero's alpha operand. The initial value is
10132 @code{GL_SRC_ALPHA}.
10134 @item @code{GL_OPERAND1_ALPHA}
10135 @var{params} returns a single symbolic constant value representing the
10136 texture combiner one's alpha operand. The initial value is
10137 @code{GL_SRC_ALPHA}.
10139 @item @code{GL_OPERAND2_ALPHA}
10140 @var{params} returns a single symbolic constant value representing the
10141 texture combiner two's alpha operand. The initial value is
10142 @code{GL_SRC_ALPHA}.
10144 @item @code{GL_RGB_SCALE}
10145 @var{params} returns a single floating-point value representing the
10146 current RGB texture combiner scaling factor. The initial value is 1.0.
10148 @item @code{GL_ALPHA_SCALE}
10149 @var{params} returns a single floating-point value representing the
10150 current alpha texture combiner scaling factor. The initial value is 1.0.
10152 @item @code{GL_COORD_REPLACE}
10153 @var{params} returns a single boolean value representing the current
10154 point sprite texture coordinate replacement enable state. The initial
10155 value is @code{GL_FALSE}.
10159 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
10160 not an accepted value.
10162 @code{GL_INVALID_OPERATION} is generated if @code{glGetTexEnv} is
10163 executed between the execution of @code{glBegin} and the corresponding
10164 execution of @code{glEnd}.
10168 @deftypefun void glGetTexGendv coord pname params
10169 @deftypefunx void glGetTexGenfv coord pname params
10170 @deftypefunx void glGetTexGeniv coord pname params
10171 Return texture coordinate generation parameters.
10175 Specifies a texture coordinate. Must be @code{GL_S}, @code{GL_T},
10176 @code{GL_R}, or @code{GL_Q}.
10179 Specifies the symbolic name of the value(s) to be returned. Must be
10180 either @code{GL_TEXTURE_GEN_MODE} or the name of one of the texture
10181 generation plane equations: @code{GL_OBJECT_PLANE} or
10182 @code{GL_EYE_PLANE}.
10185 Returns the requested data.
10189 @code{glGetTexGen} returns in @var{params} selected parameters of a
10190 texture coordinate generation function that was specified using
10191 @code{glTexGen}. @var{coord} names one of the (@var{s}, @var{t},
10192 @var{r}, @var{q}) texture coordinates, using the symbolic constant
10193 @code{GL_S}, @code{GL_T}, @code{GL_R}, or @code{GL_Q}.
10195 @var{pname} specifies one of three symbolic names:
10198 @item @code{GL_TEXTURE_GEN_MODE}
10199 @var{params} returns the single-valued texture generation function, a
10200 symbolic constant. The initial value is @code{GL_EYE_LINEAR}.
10202 @item @code{GL_OBJECT_PLANE}
10203 @var{params} returns the four plane equation coefficients that specify
10204 object linear-coordinate generation. Integer values, when requested, are
10205 mapped directly from the internal floating-point representation.
10207 @item @code{GL_EYE_PLANE}
10208 @var{params} returns the four plane equation coefficients that specify
10209 eye linear-coordinate generation. Integer values, when requested, are
10210 mapped directly from the internal floating-point representation. The
10211 returned values are those maintained in eye coordinates. They are not
10212 equal to the values specified using @code{glTexGen}, unless the
10213 modelview matrix was identity when @code{glTexGen} was called.
10217 @code{GL_INVALID_ENUM} is generated if @var{coord} or @var{pname} is not
10220 @code{GL_INVALID_OPERATION} is generated if @code{glGetTexGen} is
10221 executed between the execution of @code{glBegin} and the corresponding
10222 execution of @code{glEnd}.
10226 @deftypefun void glGetTexImage target level format type img
10227 Return a texture image.
10231 Specifies which texture is to be obtained. @code{GL_TEXTURE_1D},
10232 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D},
10233 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
10234 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
10235 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
10236 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
10237 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, and
10238 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z} are accepted.
10241 Specifies the level-of-detail number of the desired image. Level 0 is
10242 the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap
10246 Specifies a pixel format for the returned data. The supported formats
10247 are @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
10248 @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA},
10249 @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA}.
10252 Specifies a pixel type for the returned data. The supported types are
10253 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT},
10254 @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT},
10255 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
10256 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
10257 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
10258 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
10259 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
10260 @code{GL_UNSIGNED_INT_10_10_10_2}, and
10261 @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
10264 Returns the texture image. Should be a pointer to an array of the type
10265 specified by @var{type}.
10269 @code{glGetTexImage} returns a texture image into @var{img}.
10270 @var{target} specifies whether the desired texture image is one
10271 specified by @code{glTexImage1D} (@code{GL_TEXTURE_1D}),
10272 @code{glTexImage2D} (@code{GL_TEXTURE_2D} or any of
10273 @code{GL_TEXTURE_CUBE_MAP_*}), or @code{glTexImage3D}
10274 (@code{GL_TEXTURE_3D}). @var{level} specifies the level-of-detail number
10275 of the desired image. @var{format} and @var{type} specify the format and
10276 type of the desired image array. See the reference pages
10277 @code{glTexImage1D} and @code{glDrawPixels} for a description of the
10278 acceptable values for the @var{format} and @var{type} parameters,
10281 If a non-zero named buffer object is bound to the
10282 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
10283 texture image is requested, @var{img} is treated as a byte offset into
10284 the buffer object's data store.
10286 To understand the operation of @code{glGetTexImage}, consider the
10287 selected internal four-component texture image to be an RGBA color
10288 buffer the size of the image. The semantics of @code{glGetTexImage} are
10289 then identical to those of @code{glReadPixels}, with the exception that
10290 no pixel transfer operations are performed, when called with the same
10291 @var{format} and @var{type}, with @var{x} and @var{y} set to 0,
10292 @var{width} set to the width of the texture image (including border if
10293 one was specified), and @var{height} set to 1 for 1D images, or to the
10294 height of the texture image (including border if one was specified) for
10295 2D images. Because the internal texture image is an RGBA image, pixel
10296 formats @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, and
10297 @code{GL_DEPTH_COMPONENT} are not accepted, and pixel type
10298 @code{GL_BITMAP} is not accepted.
10300 If the selected texture image does not contain four components, the
10301 following mappings are applied. Single-component textures are treated as
10302 RGBA buffers with red set to the single-component value, green set to 0,
10303 blue set to 0, and alpha set to 1. Two-component textures are treated as
10304 RGBA buffers with red set to the value of component zero, alpha set to
10305 the value of component one, and green and blue set to 0. Finally,
10306 three-component textures are treated as RGBA buffers with red set to
10307 component zero, green set to component one, blue set to component two,
10308 and alpha set to 1.
10310 To determine the required size of @var{img}, use
10311 @code{glGetTexLevelParameter} to determine the dimensions of the
10312 internal texture image, then scale the required number of pixels by the
10313 storage required for each pixel, based on @var{format} and @var{type}.
10314 Be sure to take the pixel storage parameters into account, especially
10315 @code{GL_PACK_ALIGNMENT}.
10317 @code{GL_INVALID_ENUM} is generated if @var{target}, @var{format}, or
10318 @var{type} is not an accepted value.
10320 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
10322 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
10323 @r{@var{log}_2(@var{max},)}, where @r{@var{max}} is the returned value
10324 of @code{GL_MAX_TEXTURE_SIZE}.
10326 @code{GL_INVALID_OPERATION} is returned if @var{type} is one of
10327 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
10328 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
10329 and @var{format} is not @code{GL_RGB}.
10331 @code{GL_INVALID_OPERATION} is returned if @var{type} is one of
10332 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
10333 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
10334 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
10335 @code{GL_UNSIGNED_INT_10_10_10_2}, or
10336 @code{GL_UNSIGNED_INT_2_10_10_10_REV}, and @var{format} is neither
10337 @code{GL_RGBA} or @code{GL_BGRA}.
10339 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
10340 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
10341 object's data store is currently mapped.
10343 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
10344 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
10345 would be packed to the buffer object such that the memory writes
10346 required would exceed the data store size.
10348 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
10349 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{img} is
10350 not evenly divisible into the number of bytes needed to store in memory
10351 a datum indicated by @var{type}.
10353 @code{GL_INVALID_OPERATION} is generated if @code{glGetTexImage} is
10354 executed between the execution of @code{glBegin} and the corresponding
10355 execution of @code{glEnd}.
10359 @deftypefun void glGetTexLevelParameterfv target level pname params
10360 @deftypefunx void glGetTexLevelParameteriv target level pname params
10361 Return texture parameter values for a specific level of detail.
10365 Specifies the symbolic name of the target texture, either
10366 @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D},
10367 @code{GL_PROXY_TEXTURE_1D}, @code{GL_PROXY_TEXTURE_2D},
10368 @code{GL_PROXY_TEXTURE_3D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
10369 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
10370 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
10371 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
10372 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z},
10373 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or
10374 @code{GL_PROXY_TEXTURE_CUBE_MAP}.
10377 Specifies the level-of-detail number of the desired image. Level 0 is
10378 the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap
10382 Specifies the symbolic name of a texture parameter.
10383 @code{GL_TEXTURE_WIDTH}, @code{GL_TEXTURE_HEIGHT},
10384 @code{GL_TEXTURE_DEPTH}, @code{GL_TEXTURE_INTERNAL_FORMAT},
10385 @code{GL_TEXTURE_BORDER}, @code{GL_TEXTURE_RED_SIZE},
10386 @code{GL_TEXTURE_GREEN_SIZE}, @code{GL_TEXTURE_BLUE_SIZE},
10387 @code{GL_TEXTURE_ALPHA_SIZE}, @code{GL_TEXTURE_LUMINANCE_SIZE},
10388 @code{GL_TEXTURE_INTENSITY_SIZE}, @code{GL_TEXTURE_DEPTH_SIZE},
10389 @code{GL_TEXTURE_COMPRESSED}, and
10390 @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} are accepted.
10393 Returns the requested data.
10397 @code{glGetTexLevelParameter} returns in @var{params} texture parameter
10398 values for a specific level-of-detail value, specified as @var{level}.
10399 @var{target} defines the target texture, either @code{GL_TEXTURE_1D},
10400 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, @code{GL_PROXY_TEXTURE_1D},
10401 @code{GL_PROXY_TEXTURE_2D}, @code{GL_PROXY_TEXTURE_3D},
10402 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
10403 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
10404 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
10405 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
10406 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z},
10407 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or
10408 @code{GL_PROXY_TEXTURE_CUBE_MAP}.
10410 @code{GL_MAX_TEXTURE_SIZE}, and @code{GL_MAX_3D_TEXTURE_SIZE} are not
10411 really descriptive enough. It has to report the largest square texture
10412 image that can be accommodated with mipmaps and borders, but a long
10413 skinny texture, or a texture without mipmaps and borders, may easily fit
10414 in texture memory. The proxy targets allow the user to more accurately
10415 query whether the GL can accommodate a texture of a given configuration.
10416 If the texture cannot be accommodated, the texture state variables,
10417 which may be queried with @code{glGetTexLevelParameter}, are set to 0.
10418 If the texture can be accommodated, the texture state values will be set
10419 as they would be set for a non-proxy target.
10421 @var{pname} specifies the texture parameter whose value or values will
10424 The accepted parameter names are as follows:
10427 @item @code{GL_TEXTURE_WIDTH}
10430 @var{params} returns a single value, the width of the texture image.
10431 This value includes the border of the texture image. The initial value
10434 @item @code{GL_TEXTURE_HEIGHT}
10437 @var{params} returns a single value, the height of the texture image.
10438 This value includes the border of the texture image. The initial value
10441 @item @code{GL_TEXTURE_DEPTH}
10444 @var{params} returns a single value, the depth of the texture image.
10445 This value includes the border of the texture image. The initial value
10448 @item @code{GL_TEXTURE_INTERNAL_FORMAT}
10451 @var{params} returns a single value, the internal format of the texture
10454 @item @code{GL_TEXTURE_BORDER}
10457 @var{params} returns a single value, the width in pixels of the border
10458 of the texture image. The initial value is 0.
10460 @item @code{GL_TEXTURE_RED_SIZE},
10461 @item @code{GL_TEXTURE_GREEN_SIZE},
10462 @item @code{GL_TEXTURE_BLUE_SIZE},
10463 @item @code{GL_TEXTURE_ALPHA_SIZE},
10464 @item @code{GL_TEXTURE_LUMINANCE_SIZE},
10465 @item @code{GL_TEXTURE_INTENSITY_SIZE},
10466 @item @code{GL_TEXTURE_DEPTH_SIZE}
10469 The internal storage resolution of an individual component. The
10470 resolution chosen by the GL will be a close match for the resolution
10471 requested by the user with the component argument of
10472 @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D},
10473 @code{glCopyTexImage1D}, and @code{glCopyTexImage2D}. The initial value
10476 @item @code{GL_TEXTURE_COMPRESSED}
10479 @var{params} returns a single boolean value indicating if the texture
10480 image is stored in a compressed internal format. The initiali value is
10483 @item @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE}
10486 @var{params} returns a single integer value, the number of unsigned
10487 bytes of the compressed texture image that would be returned from
10488 @code{glGetCompressedTexImage}.
10492 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
10493 not an accepted value.
10495 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
10497 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
10498 @r{@var{log}_2}@var{max}, where @var{max} is the returned value of
10499 @code{GL_MAX_TEXTURE_SIZE}.
10501 @code{GL_INVALID_OPERATION} is generated if
10502 @code{glGetTexLevelParameter} is executed between the execution of
10503 @code{glBegin} and the corresponding execution of @code{glEnd}.
10505 @code{GL_INVALID_OPERATION} is generated if
10506 @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} is queried on texture images
10507 with an uncompressed internal format or on proxy targets.
10511 @deftypefun void glGetTexParameterfv target pname params
10512 @deftypefunx void glGetTexParameteriv target pname params
10513 Return texture parameter values.
10517 Specifies the symbolic name of the target texture. @code{GL_TEXTURE_1D},
10518 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, and
10519 @code{GL_TEXTURE_CUBE_MAP} are accepted.
10522 Specifies the symbolic name of a texture parameter.
10523 @code{GL_TEXTURE_MAG_FILTER}, @code{GL_TEXTURE_MIN_FILTER},
10524 @code{GL_TEXTURE_MIN_LOD}, @code{GL_TEXTURE_MAX_LOD},
10525 @code{GL_TEXTURE_BASE_LEVEL}, @code{GL_TEXTURE_MAX_LEVEL},
10526 @code{GL_TEXTURE_WRAP_S}, @code{GL_TEXTURE_WRAP_T},
10527 @code{GL_TEXTURE_WRAP_R}, @code{GL_TEXTURE_BORDER_COLOR},
10528 @code{GL_TEXTURE_PRIORITY}, @code{GL_TEXTURE_RESIDENT},
10529 @code{GL_TEXTURE_COMPARE_MODE}, @code{GL_TEXTURE_COMPARE_FUNC},
10530 @code{GL_DEPTH_TEXTURE_MODE}, and @code{GL_GENERATE_MIPMAP} are
10534 Returns the texture parameters.
10538 @code{glGetTexParameter} returns in @var{params} the value or values of
10539 the texture parameter specified as @var{pname}. @var{target} defines the
10540 target texture, either @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D},
10541 @code{GL_TEXTURE_3D}, or @code{GL_TEXTURE_CUBE_MAP}, to specify one-,
10542 two-, or three-dimensional or cube-mapped texturing. @var{pname} accepts
10543 the same symbols as @code{glTexParameter}, with the same
10547 @item @code{GL_TEXTURE_MAG_FILTER}
10548 Returns the single-valued texture magnification filter, a symbolic
10549 constant. The initial value is @code{GL_LINEAR}.
10551 @item @code{GL_TEXTURE_MIN_FILTER}
10552 Returns the single-valued texture minification filter, a symbolic
10553 constant. The initial value is @code{GL_NEAREST_MIPMAP_LINEAR}.
10555 @item @code{GL_TEXTURE_MIN_LOD}
10556 Returns the single-valued texture minimum level-of-detail value. The
10557 initial value is @r{-1000}.
10559 @item @code{GL_TEXTURE_MAX_LOD}
10560 Returns the single-valued texture maximum level-of-detail value. The
10561 initial value is 1000.
10563 @item @code{GL_TEXTURE_BASE_LEVEL}
10564 Returns the single-valued base texture mipmap level. The initial value
10567 @item @code{GL_TEXTURE_MAX_LEVEL}
10568 Returns the single-valued maximum texture mipmap array level. The
10569 initial value is 1000.
10571 @item @code{GL_TEXTURE_WRAP_S}
10572 Returns the single-valued wrapping function for texture coordinate
10573 @r{@var{s}}, a symbolic constant. The initial value is @code{GL_REPEAT}.
10575 @item @code{GL_TEXTURE_WRAP_T}
10576 Returns the single-valued wrapping function for texture coordinate
10577 @r{@var{t}}, a symbolic constant. The initial value is @code{GL_REPEAT}.
10579 @item @code{GL_TEXTURE_WRAP_R}
10580 Returns the single-valued wrapping function for texture coordinate
10581 @r{@var{r}}, a symbolic constant. The initial value is @code{GL_REPEAT}.
10583 @item @code{GL_TEXTURE_BORDER_COLOR}
10584 Returns four integer or floating-point numbers that comprise the RGBA
10585 color of the texture border. Floating-point values are returned in the
10586 range @r{[0,1]}. Integer values are returned as a linear mapping of the
10587 internal floating-point representation such that 1.0 maps to the most
10588 positive representable integer and @r{-1.0} maps to the most negative
10589 representable integer. The initial value is (0, 0, 0, 0).
10591 @item @code{GL_TEXTURE_PRIORITY}
10592 Returns the residence priority of the target texture (or the named
10593 texture bound to it). The initial value is 1. See
10594 @code{glPrioritizeTextures}.
10596 @item @code{GL_TEXTURE_RESIDENT}
10597 Returns the residence status of the target texture. If the value
10598 returned in @var{params} is @code{GL_TRUE}, the texture is resident in
10599 texture memory. See @code{glAreTexturesResident}.
10601 @item @code{GL_TEXTURE_COMPARE_MODE}
10602 Returns a single-valued texture comparison mode, a symbolic constant.
10603 The initial value is @code{GL_NONE}. See @code{glTexParameter}.
10605 @item @code{GL_TEXTURE_COMPARE_FUNC}
10606 Returns a single-valued texture comparison function, a symbolic
10607 constant. The initial value is @code{GL_LEQUAL}. See
10608 @code{glTexParameter}.
10610 @item @code{GL_DEPTH_TEXTURE_MODE}
10611 Returns a single-valued texture format indicating how the depth values
10612 should be converted into color components. The initial value is
10613 @code{GL_LUMINANCE}. See @code{glTexParameter}.
10615 @item @code{GL_GENERATE_MIPMAP}
10616 Returns a single boolean value indicating if automatic mipmap level
10617 updates are enabled. See @code{glTexParameter}.
10621 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
10622 not an accepted value.
10624 @code{GL_INVALID_OPERATION} is generated if @code{glGetTexParameter} is
10625 executed between the execution of @code{glBegin} and the corresponding
10626 execution of @code{glEnd}.
10630 @deftypefun GLint glGetUniformLocation program name
10631 Returns the location of a uniform variable.
10634 @item @var{program}
10635 Specifies the program object to be queried.
10638 Points to a null terminated string containing the name of the uniform
10639 variable whose location is to be queried.
10643 @code{glGetUniformLocation } returns an integer that represents the
10644 location of a specific uniform variable within a program object.
10645 @var{name} must be a null terminated string that contains no white
10646 space. @var{name} must be an active uniform variable name in
10647 @var{program} that is not a structure, an array of structures, or a
10648 subcomponent of a vector or a matrix. This function returns -1 if
10649 @var{name} does not correspond to an active uniform variable in
10650 @var{program} or if @var{name} starts with the reserved prefix "gl_".
10652 Uniform variables that are structures or arrays of structures may be
10653 queried by calling @code{glGetUniformLocation} for each field within the
10654 structure. The array element operator "[]" and the structure field
10655 operator "." may be used in @var{name} in order to select elements
10656 within an array or fields within a structure. The result of using these
10657 operators is not allowed to be another structure, an array of
10658 structures, or a subcomponent of a vector or a matrix. Except if the
10659 last part of @var{name} indicates a uniform variable array, the location
10660 of the first element of an array can be retrieved by using the name of
10661 the array, or by using the name appended by "[0]".
10663 The actual locations assigned to uniform variables are not known until
10664 the program object is linked successfully. After linking has occurred,
10665 the command @code{glGetUniformLocation} can be used to obtain the
10666 location of a uniform variable. This location value can then be passed
10667 to @code{glUniform} to set the value of the uniform variable or to
10668 @code{glGetUniform} in order to query the current value of the uniform
10669 variable. After a program object has been linked successfully, the index
10670 values for uniform variables remain fixed until the next link command
10671 occurs. Uniform variable locations and values can only be queried after
10672 a link if the link was successful.
10674 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
10675 generated by OpenGL.
10677 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
10680 @code{GL_INVALID_OPERATION} is generated if @var{program} has not been
10681 successfully linked.
10683 @code{GL_INVALID_OPERATION} is generated if @code{glGetUniformLocation}
10684 is executed between the execution of @code{glBegin} and the
10685 corresponding execution of @code{glEnd}.
10689 @deftypefun void glGetUniformfv program location params
10690 @deftypefunx void glGetUniformiv program location params
10691 Returns the value of a uniform variable.
10694 @item @var{program}
10695 Specifies the program object to be queried.
10697 @item @var{location}
10698 Specifies the location of the uniform variable to be queried.
10701 Returns the value of the specified uniform variable.
10705 @code{glGetUniform} returns in @var{params} the value(s) of the
10706 specified uniform variable. The type of the uniform variable specified
10707 by @var{location} determines the number of values returned. If the
10708 uniform variable is defined in the shader as a boolean, int, or float, a
10709 single value will be returned. If it is defined as a vec2, ivec2, or
10710 bvec2, two values will be returned. If it is defined as a vec3, ivec3,
10711 or bvec3, three values will be returned, and so on. To query values
10712 stored in uniform variables declared as arrays, call @code{glGetUniform}
10713 for each element of the array. To query values stored in uniform
10714 variables declared as structures, call @code{glGetUniform} for each
10715 field in the structure. The values for uniform variables declared as a
10716 matrix will be returned in column major order.
10718 The locations assigned to uniform variables are not known until the
10719 program object is linked. After linking has occurred, the command
10720 @code{glGetUniformLocation} can be used to obtain the location of a
10721 uniform variable. This location value can then be passed to
10722 @code{glGetUniform} in order to query the current value of the uniform
10723 variable. After a program object has been linked successfully, the index
10724 values for uniform variables remain fixed until the next link command
10725 occurs. The uniform variable values can only be queried after a link if
10726 the link was successful.
10728 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
10729 generated by OpenGL.
10731 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
10734 @code{GL_INVALID_OPERATION} is generated if @var{program} has not been
10735 successfully linked.
10737 @code{GL_INVALID_OPERATION} is generated if @var{location} does not
10738 correspond to a valid uniform variable location for the specified
10741 @code{GL_INVALID_OPERATION} is generated if @code{glGetUniform} is
10742 executed between the execution of @code{glBegin} and the corresponding
10743 execution of @code{glEnd}.
10747 @deftypefun void glGetVertexAttribPointerv index pname pointer
10748 Return the address of the specified generic vertex attribute pointer.
10752 Specifies the generic vertex attribute parameter to be returned.
10755 Specifies the symbolic name of the generic vertex attribute parameter to
10756 be returned. Must be @code{GL_VERTEX_ATTRIB_ARRAY_POINTER}.
10758 @item @var{pointer}
10759 Returns the pointer value.
10763 @code{glGetVertexAttribPointerv} returns pointer information.
10764 @var{index} is the generic vertex attribute to be queried, @var{pname}
10765 is a symbolic constant indicating the pointer to be returned, and
10766 @var{params} is a pointer to a location in which to place the returned
10769 If a non-zero named buffer object was bound to the
10770 @code{GL_ARRAY_BUFFER} target (see @code{glBindBuffer}) when the desired
10771 pointer was previously specified, the @var{pointer} returned is a byte
10772 offset into the buffer object's data store.
10774 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
10775 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
10777 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
10782 @deftypefun void glGetVertexAttribdv index pname params
10783 @deftypefunx void glGetVertexAttribfv index pname params
10784 @deftypefunx void glGetVertexAttribiv index pname params
10785 Return a generic vertex attribute parameter.
10789 Specifies the generic vertex attribute parameter to be queried.
10792 Specifies the symbolic name of the vertex attribute parameter to be
10793 queried. Accepted values are
10794 @code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING},
10795 @code{GL_VERTEX_ATTRIB_ARRAY_ENABLED},
10796 @code{GL_VERTEX_ATTRIB_ARRAY_SIZE},
10797 @code{GL_VERTEX_ATTRIB_ARRAY_STRIDE},
10798 @code{GL_VERTEX_ATTRIB_ARRAY_TYPE},
10799 @code{GL_VERTEX_ATTRIB_ARRAY_NORMALIZED}, or
10800 @code{GL_CURRENT_VERTEX_ATTRIB}.
10803 Returns the requested data.
10807 @code{glGetVertexAttrib} returns in @var{params} the value of a generic
10808 vertex attribute parameter. The generic vertex attribute to be queried
10809 is specified by @var{index}, and the parameter to be queried is
10810 specified by @var{pname}.
10812 The accepted parameter names are as follows:
10815 @item @code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING}
10818 @var{params} returns a single value, the name of the buffer object
10819 currently bound to the binding point corresponding to generic vertex
10820 attribute array @var{index}. If no buffer object is bound, 0 is
10821 returned. The initial value is 0.
10823 @item @code{GL_VERTEX_ATTRIB_ARRAY_ENABLED}
10826 @var{params} returns a single value that is non-zero (true) if the
10827 vertex attribute array for @var{index} is enabled and 0 (false) if it is
10828 disabled. The initial value is @code{GL_FALSE}.
10830 @item @code{GL_VERTEX_ATTRIB_ARRAY_SIZE}
10833 @var{params} returns a single value, the size of the vertex attribute
10834 array for @var{index}. The size is the number of values for each element
10835 of the vertex attribute array, and it will be 1, 2, 3, or 4. The initial
10838 @item @code{GL_VERTEX_ATTRIB_ARRAY_STRIDE}
10841 @var{params} returns a single value, the array stride for (number of
10842 bytes between successive elements in) the vertex attribute array for
10843 @var{index}. A value of 0 indicates that the array elements are stored
10844 sequentially in memory. The initial value is 0.
10846 @item @code{GL_VERTEX_ATTRIB_ARRAY_TYPE}
10849 @var{params} returns a single value, a symbolic constant indicating the
10850 array type for the vertex attribute array for @var{index}. Possible
10851 values are @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
10852 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
10853 @code{GL_FLOAT}, and @code{GL_DOUBLE}. The initial value is
10856 @item @code{GL_VERTEX_ATTRIB_ARRAY_NORMALIZED}
10859 @var{params} returns a single value that is non-zero (true) if
10860 fixed-point data types for the vertex attribute array indicated by
10861 @var{index} are normalized when they are converted to floating point,
10862 and 0 (false) otherwise. The initial value is @code{GL_FALSE}.
10864 @item @code{GL_CURRENT_VERTEX_ATTRIB}
10867 @var{params} returns four values that represent the current value for
10868 the generic vertex attribute specified by index. Generic vertex
10869 attribute 0 is unique in that it has no current state, so an error will
10870 be generated if @var{index} is 0. The initial value for all other
10871 generic vertex attributes is (0,0,0,1).
10875 All of the parameters except @code{GL_CURRENT_VERTEX_ATTRIB} represent
10878 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
10879 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
10881 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
10884 @code{GL_INVALID_OPERATION} is generated if @var{index} is 0 and
10885 @var{pname} is @code{GL_CURRENT_VERTEX_ATTRIB}.
10889 @deftypefun void glGetBooleanv pname params
10890 @deftypefunx void glGetDoublev pname params
10891 @deftypefunx void glGetFloatv pname params
10892 @deftypefunx void glGetIntegerv pname params
10893 Return the value or values of a selected parameter.
10897 Specifies the parameter value to be returned. The symbolic constants in
10898 the list below are accepted.
10901 Returns the value or values of the specified parameter.
10905 These four commands return values for simple state variables in GL.
10906 @var{pname} is a symbolic constant indicating the state variable to be
10907 returned, and @var{params} is a pointer to an array of the indicated
10908 type in which to place the returned data.
10910 Type conversion is performed if @var{params} has a different type than
10911 the state variable value being requested. If @code{glGetBooleanv} is
10912 called, a floating-point (or integer) value is converted to
10913 @code{GL_FALSE} if and only if it is 0.0 (or 0). Otherwise, it is
10914 converted to @code{GL_TRUE}. If @code{glGetIntegerv} is called, boolean
10915 values are returned as @code{GL_TRUE} or @code{GL_FALSE}, and most
10916 floating-point values are rounded to the nearest integer value.
10917 Floating-point colors and normals, however, are returned with a linear
10918 mapping that maps 1.0 to the most positive representable integer value
10919 and @r{-1.0} to the most negative representable integer value. If
10920 @code{glGetFloatv} or @code{glGetDoublev} is called, boolean values are
10921 returned as @code{GL_TRUE} or @code{GL_FALSE}, and integer values are
10922 converted to floating-point values.
10924 The following symbolic constants are accepted by @var{pname}:
10927 @item @code{GL_ACCUM_ALPHA_BITS}
10930 @var{params} returns one value, the number of alpha bitplanes in the
10931 accumulation buffer.
10933 @item @code{GL_ACCUM_BLUE_BITS}
10936 @var{params} returns one value, the number of blue bitplanes in the
10937 accumulation buffer.
10939 @item @code{GL_ACCUM_CLEAR_VALUE}
10942 @var{params} returns four values: the red, green, blue, and alpha values
10943 used to clear the accumulation buffer. Integer values, if requested, are
10944 linearly mapped from the internal floating-point representation such
10945 that 1.0 returns the most positive representable integer value, and
10946 @r{-1.0} returns the most negative representable integer value. The
10947 initial value is (0, 0, 0, 0). See @code{glClearAccum}.
10949 @item @code{GL_ACCUM_GREEN_BITS}
10952 @var{params} returns one value, the number of green bitplanes in the
10953 accumulation buffer.
10955 @item @code{GL_ACCUM_RED_BITS}
10958 @var{params} returns one value, the number of red bitplanes in the
10959 accumulation buffer.
10961 @item @code{GL_ACTIVE_TEXTURE}
10964 @var{params} returns a single value indicating the active multitexture
10965 unit. The initial value is @code{GL_TEXTURE0}. See
10966 @code{glActiveTexture}.
10968 @item @code{GL_ALIASED_POINT_SIZE_RANGE}
10971 @var{params} returns two values, the smallest and largest supported
10972 sizes for aliased points.
10974 @item @code{GL_ALIASED_LINE_WIDTH_RANGE}
10977 @var{params} returns two values, the smallest and largest supported
10978 widths for aliased lines.
10980 @item @code{GL_ALPHA_BIAS}
10983 @var{params} returns one value, the alpha bias factor used during pixel
10984 transfers. The initial value is 0. See @code{glPixelTransfer}.
10986 @item @code{GL_ALPHA_BITS}
10989 @var{params} returns one value, the number of alpha bitplanes in each
10992 @item @code{GL_ALPHA_SCALE}
10995 @var{params} returns one value, the alpha scale factor used during pixel
10996 transfers. The initial value is 1. See @code{glPixelTransfer}.
10998 @item @code{GL_ALPHA_TEST}
11001 @var{params} returns a single boolean value indicating whether alpha
11002 testing of fragments is enabled. The initial value is @code{GL_FALSE}.
11003 See @code{glAlphaFunc}.
11005 @item @code{GL_ALPHA_TEST_FUNC}@var{params} returns one value,
11008 the symbolic name of the alpha test function. The initial value is
11009 @code{GL_ALWAYS}. See @code{glAlphaFunc}.
11011 @item @code{GL_ALPHA_TEST_REF}
11014 @var{params} returns one value, the reference value for the alpha test.
11015 The initial value is 0. See @code{glAlphaFunc}. An integer value, if
11016 requested, is linearly mapped from the internal floating-point
11017 representation such that 1.0 returns the most positive representable
11018 integer value, and @r{-1.0} returns the most negative representable
11021 @item @code{GL_ARRAY_BUFFER_BINDING}
11024 @var{params} returns a single value, the name of the buffer object
11025 currently bound to the target @code{GL_ARRAY_BUFFER}. If no buffer
11026 object is bound to this target, 0 is returned. The initial value is 0.
11027 See @code{glBindBuffer}.
11029 @item @code{GL_ATTRIB_STACK_DEPTH}
11032 @var{params} returns one value, the depth of the attribute stack. If the
11033 stack is empty, 0 is returned. The initial value is 0. See
11034 @code{glPushAttrib}.
11036 @item @code{GL_AUTO_NORMAL}
11039 @var{params} returns a single boolean value indicating whether 2D map
11040 evaluation automatically generates surface normals. The initial value is
11041 @code{GL_FALSE}. See @code{glMap2}.
11043 @item @code{GL_AUX_BUFFERS}
11046 @var{params} returns one value, the number of auxiliary color buffers
11049 @item @code{GL_BLEND}
11052 @var{params} returns a single boolean value indicating whether blending
11053 is enabled. The initial value is @code{GL_FALSE}. See
11054 @code{glBlendFunc}.
11056 @item @code{GL_BLEND_COLOR}
11059 @var{params} returns four values, the red, green, blue, and alpha values
11060 which are the components of the blend color. See @code{glBlendColor}.
11062 @item @code{GL_BLEND_DST_ALPHA}
11065 @var{params} returns one value, the symbolic constant identifying the
11066 alpha destination blend function. The initial value is @code{GL_ZERO}.
11067 See @code{glBlendFunc} and @code{glBlendFuncSeparate}.
11069 @item @code{GL_BLEND_DST_RGB}
11072 @var{params} returns one value, the symbolic constant identifying the
11073 RGB destination blend function. The initial value is @code{GL_ZERO}. See
11074 @code{glBlendFunc} and @code{glBlendFuncSeparate}.
11076 @item @code{GL_BLEND_EQUATION_RGB}
11079 @var{params} returns one value, a symbolic constant indicating whether
11080 the RGB blend equation is @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT},
11081 @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN} or @code{GL_MAX}. See
11082 @code{glBlendEquationSeparate}.
11084 @item @code{GL_BLEND_EQUATION_ALPHA}
11087 @var{params} returns one value, a symbolic constant indicating whether
11088 the Alpha blend equation is @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT},
11089 @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN} or @code{GL_MAX}. See
11090 @code{glBlendEquationSeparate}.
11092 @item @code{GL_BLEND_SRC_ALPHA}
11095 @var{params} returns one value, the symbolic constant identifying the
11096 alpha source blend function. The initial value is @code{GL_ONE}. See
11097 @code{glBlendFunc} and @code{glBlendFuncSeparate}.
11099 @item @code{GL_BLEND_SRC_RGB}
11102 @var{params} returns one value, the symbolic constant identifying the
11103 RGB source blend function. The initial value is @code{GL_ONE}. See
11104 @code{glBlendFunc} and @code{glBlendFuncSeparate}.
11106 @item @code{GL_BLUE_BIAS}
11109 @var{params} returns one value, the blue bias factor used during pixel
11110 transfers. The initial value is 0. See @code{glPixelTransfer}.
11112 @item @code{GL_BLUE_BITS}
11115 @var{params} returns one value, the number of blue bitplanes in each
11118 @item @code{GL_BLUE_SCALE}
11121 @var{params} returns one value, the blue scale factor used during pixel
11122 transfers. The initial value is 1. See @code{glPixelTransfer}.
11124 @item @code{GL_CLIENT_ACTIVE_TEXTURE}
11127 @var{params} returns a single integer value indicating the current
11128 client active multitexture unit. The initial value is
11129 @code{GL_TEXTURE0}. See @code{glClientActiveTexture}.
11131 @item @code{GL_CLIENT_ATTRIB_STACK_DEPTH}
11134 @var{params} returns one value indicating the depth of the attribute
11135 stack. The initial value is 0. See @code{glPushClientAttrib}.
11137 @item @code{GL_CLIP_PLANE}@var{i}
11140 @var{params} returns a single boolean value indicating whether the
11141 specified clipping plane is enabled. The initial value is
11142 @code{GL_FALSE}. See @code{glClipPlane}.
11144 @item @code{GL_COLOR_ARRAY}
11147 @var{params} returns a single boolean value indicating whether the color
11148 array is enabled. The initial value is @code{GL_FALSE}. See
11149 @code{glColorPointer}.
11151 @item @code{GL_COLOR_ARRAY_BUFFER_BINDING}
11154 @var{params} returns a single value, the name of the buffer object
11155 associated with the color array. This buffer object would have been
11156 bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
11157 recent call to @code{glColorPointer}. If no buffer object was bound to
11158 this target, 0 is returned. The initial value is 0. See
11159 @code{glBindBuffer}.
11161 @item @code{GL_COLOR_ARRAY_SIZE}
11164 @var{params} returns one value, the number of components per color in
11165 the color array. The initial value is 4. See @code{glColorPointer}.
11167 @item @code{GL_COLOR_ARRAY_STRIDE}
11170 @var{params} returns one value, the byte offset between consecutive
11171 colors in the color array. The initial value is 0. See
11172 @code{glColorPointer}.
11174 @item @code{GL_COLOR_ARRAY_TYPE}
11177 @var{params} returns one value, the data type of each component in the
11178 color array. The initial value is @code{GL_FLOAT}. See
11179 @code{glColorPointer}.
11181 @item @code{GL_COLOR_CLEAR_VALUE}
11184 @var{params} returns four values: the red, green, blue, and alpha values
11185 used to clear the color buffers. Integer values, if requested, are
11186 linearly mapped from the internal floating-point representation such
11187 that 1.0 returns the most positive representable integer value, and
11188 @r{-1.0} returns the most negative representable integer value. The
11189 initial value is (0, 0, 0, 0). See @code{glClearColor}.
11191 @item @code{GL_COLOR_LOGIC_OP}
11194 @var{params} returns a single boolean value indicating whether a
11195 fragment's RGBA color values are merged into the framebuffer using a
11196 logical operation. The initial value is @code{GL_FALSE}. See
11199 @item @code{GL_COLOR_MATERIAL}
11202 @var{params} returns a single boolean value indicating whether one or
11203 more material parameters are tracking the current color. The initial
11204 value is @code{GL_FALSE}. See @code{glColorMaterial}.
11206 @item @code{GL_COLOR_MATERIAL_FACE}
11209 @var{params} returns one value, a symbolic constant indicating which
11210 materials have a parameter that is tracking the current color. The
11211 initial value is @code{GL_FRONT_AND_BACK}. See @code{glColorMaterial}.
11213 @item @code{GL_COLOR_MATERIAL_PARAMETER}
11216 @var{params} returns one value, a symbolic constant indicating which
11217 material parameters are tracking the current color. The initial value is
11218 @code{GL_AMBIENT_AND_DIFFUSE}. See @code{glColorMaterial}.
11220 @item @code{GL_COLOR_MATRIX}
11223 @var{params} returns sixteen values: the color matrix on the top of the
11224 color matrix stack. Initially this matrix is the identity matrix. See
11225 @code{glPushMatrix}.
11227 @item @code{GL_COLOR_MATRIX_STACK_DEPTH}
11230 @var{params} returns one value, the maximum supported depth of the
11231 projection matrix stack. The value must be at least 2. See
11232 @code{glPushMatrix}.
11234 @item @code{GL_COLOR_SUM}
11237 @var{params} returns a single boolean value indicating whether primary
11238 and secondary color sum is enabled. See @code{glSecondaryColor}.
11240 @item @code{GL_COLOR_TABLE}
11243 @var{params} returns a single boolean value indicating whether the color
11244 table lookup is enabled. See @code{glColorTable}.
11246 @item @code{GL_COLOR_WRITEMASK}
11249 @var{params} returns four boolean values: the red, green, blue, and
11250 alpha write enables for the color buffers. The initial value is
11251 (@code{GL_TRUE}, @code{GL_TRUE}, @code{GL_TRUE}, @code{GL_TRUE}). See
11252 @code{glColorMask}.
11254 @item @code{GL_COMPRESSED_TEXTURE_FORMATS}
11257 @var{params} returns a list of symbolic constants of length
11258 @code{GL_NUM_COMPRESSED_TEXTURE_FORMATS} indicating which compressed
11259 texture formats are available. See @code{glCompressedTexImage2D}.
11261 @item @code{GL_CONVOLUTION_1D}
11264 @var{params} returns a single boolean value indicating whether 1D
11265 convolution is enabled. The initial value is @code{GL_FALSE}. See
11266 @code{glConvolutionFilter1D}.
11268 @item @code{GL_CONVOLUTION_2D}
11271 @var{params} returns a single boolean value indicating whether 2D
11272 convolution is enabled. The initial value is @code{GL_FALSE}. See
11273 @code{glConvolutionFilter2D}.
11275 @item @code{GL_CULL_FACE}
11278 @var{params} returns a single boolean value indicating whether polygon
11279 culling is enabled. The initial value is @code{GL_FALSE}. See
11282 @item @code{GL_CULL_FACE_MODE}
11285 @var{params} returns one value, a symbolic constant indicating which
11286 polygon faces are to be culled. The initial value is @code{GL_BACK}. See
11289 @item @code{GL_CURRENT_COLOR}
11292 @var{params} returns four values: the red, green, blue, and alpha values
11293 of the current color. Integer values, if requested, are linearly mapped
11294 from the internal floating-point representation such that 1.0 returns
11295 the most positive representable integer value, and @r{-1.0} returns the
11296 most negative representable integer value. The initial value is (1, 1,
11297 1, 1). See @code{glColor}.
11299 @item @code{GL_CURRENT_FOG_COORD}
11302 @var{params} returns one value, the current fog coordinate. The initial
11303 value is 0. See @code{glFogCoord}.
11305 @item @code{GL_CURRENT_INDEX}
11308 @var{params} returns one value, the current color index. The initial
11309 value is 1. See @code{glIndex}.
11311 @item @code{GL_CURRENT_NORMAL}
11314 @var{params} returns three values: the @var{x}, @var{y}, and @var{z}
11315 values of the current normal. Integer values, if requested, are linearly
11316 mapped from the internal floating-point representation such that 1.0
11317 returns the most positive representable integer value, and @r{-1.0}
11318 returns the most negative representable integer value. The initial value
11319 is (0, 0, 1). See @code{glNormal}.
11321 @item @code{GL_CURRENT_PROGRAM}
11324 @var{params} returns one value, the name of the program object that is
11325 currently active, or 0 if no program object is active. See
11326 @code{glUseProgram}.
11328 @item @code{GL_CURRENT_RASTER_COLOR}
11331 @var{params} returns four values: the red, green, blue, and alpha color
11332 values of the current raster position. Integer values, if requested, are
11333 linearly mapped from the internal floating-point representation such
11334 that 1.0 returns the most positive representable integer value, and
11335 @r{-1.0} returns the most negative representable integer value. The
11336 initial value is (1, 1, 1, 1). See @code{glRasterPos}.
11338 @item @code{GL_CURRENT_RASTER_DISTANCE}
11341 @var{params} returns one value, the distance from the eye to the current
11342 raster position. The initial value is 0. See @code{glRasterPos}.
11344 @item @code{GL_CURRENT_RASTER_INDEX}
11347 @var{params} returns one value, the color index of the current raster
11348 position. The initial value is 1. See @code{glRasterPos}.
11350 @item @code{GL_CURRENT_RASTER_POSITION}
11353 @var{params} returns four values: the @var{x}, @var{y}, @var{z}, and
11354 @var{w} components of the current raster position. @var{x}, @var{y}, and
11355 @var{z} are in window coordinates, and @var{w} is in clip coordinates.
11356 The initial value is (0, 0, 0, 1). See @code{glRasterPos}.
11358 @item @code{GL_CURRENT_RASTER_POSITION_VALID}
11361 @var{params} returns a single boolean value indicating whether the
11362 current raster position is valid. The initial value is @code{GL_TRUE}.
11363 See @code{glRasterPos}.
11365 @item @code{GL_CURRENT_RASTER_SECONDARY_COLOR}
11368 @var{params} returns four values: the red, green, blue, and alpha
11369 secondary color values of the current raster position. Integer values,
11370 if requested, are linearly mapped from the internal floating-point
11371 representation such that 1.0 returns the most positive representable
11372 integer value, and @r{-1.0} returns the most negative representable
11373 integer value. The initial value is (1, 1, 1, 1). See
11374 @code{glRasterPos}.
11376 @item @code{GL_CURRENT_RASTER_TEXTURE_COORDS}
11379 @var{params} returns four values: the @var{s}, @var{t}, @var{r}, and
11380 @var{q} texture coordinates of the current raster position. The initial
11381 value is (0, 0, 0, 1). See @code{glRasterPos} and
11382 @code{glMultiTexCoord}.
11384 @item @code{GL_CURRENT_SECONDARY_COLOR}
11387 @var{params} returns four values: the red, green, blue, and alpha values
11388 of the current secondary color. Integer values, if requested, are
11389 linearly mapped from the internal floating-point representation such
11390 that 1.0 returns the most positive representable integer value, and
11391 @r{-1.0} returns the most negative representable integer value. The
11392 initial value is (0, 0, 0, 0). See @code{glSecondaryColor}.
11394 @item @code{GL_CURRENT_TEXTURE_COORDS}
11397 @var{params} returns four values: the @var{s}, @var{t}, @var{r}, and
11398 @var{q} current texture coordinates. The initial value is (0, 0, 0, 1).
11399 See @code{glMultiTexCoord}.
11401 @item @code{GL_DEPTH_BIAS}
11404 @var{params} returns one value, the depth bias factor used during pixel
11405 transfers. The initial value is 0. See @code{glPixelTransfer}.
11407 @item @code{GL_DEPTH_BITS}
11410 @var{params} returns one value, the number of bitplanes in the depth
11413 @item @code{GL_DEPTH_CLEAR_VALUE}
11416 @var{params} returns one value, the value that is used to clear the
11417 depth buffer. Integer values, if requested, are linearly mapped from the
11418 internal floating-point representation such that 1.0 returns the most
11419 positive representable integer value, and @r{-1.0} returns the most
11420 negative representable integer value. The initial value is 1. See
11421 @code{glClearDepth}.
11423 @item @code{GL_DEPTH_FUNC}
11426 @var{params} returns one value, the symbolic constant that indicates the
11427 depth comparison function. The initial value is @code{GL_LESS}. See
11428 @code{glDepthFunc}.
11430 @item @code{GL_DEPTH_RANGE}
11433 @var{params} returns two values: the near and far mapping limits for the
11434 depth buffer. Integer values, if requested, are linearly mapped from the
11435 internal floating-point representation such that 1.0 returns the most
11436 positive representable integer value, and @r{-1.0} returns the most
11437 negative representable integer value. The initial value is (0, 1). See
11438 @code{glDepthRange}.
11440 @item @code{GL_DEPTH_SCALE}
11443 @var{params} returns one value, the depth scale factor used during pixel
11444 transfers. The initial value is 1. See @code{glPixelTransfer}.
11446 @item @code{GL_DEPTH_TEST}
11449 @var{params} returns a single boolean value indicating whether depth
11450 testing of fragments is enabled. The initial value is @code{GL_FALSE}.
11451 See @code{glDepthFunc} and @code{glDepthRange}.
11453 @item @code{GL_DEPTH_WRITEMASK}
11456 @var{params} returns a single boolean value indicating if the depth
11457 buffer is enabled for writing. The initial value is @code{GL_TRUE}. See
11458 @code{glDepthMask}.
11460 @item @code{GL_DITHER}
11463 @var{params} returns a single boolean value indicating whether dithering
11464 of fragment colors and indices is enabled. The initial value is
11467 @item @code{GL_DOUBLEBUFFER}
11470 @var{params} returns a single boolean value indicating whether double
11471 buffering is supported.
11473 @item @code{GL_DRAW_BUFFER}
11476 @var{params} returns one value, a symbolic constant indicating which
11477 buffers are being drawn to. See @code{glDrawBuffer}. The initial value
11478 is @code{GL_BACK} if there are back buffers, otherwise it is
11481 @item @code{GL_DRAW_BUFFER}@var{i}
11484 @var{params} returns one value, a symbolic constant indicating which
11485 buffers are being drawn to by the corresponding output color. See
11486 @code{glDrawBuffers}. The initial value of @code{GL_DRAW_BUFFER0} is
11487 @code{GL_BACK} if there are back buffers, otherwise it is
11488 @code{GL_FRONT}. The initial values of draw buffers for all other output
11489 colors is @code{GL_NONE}.
11491 @item @code{GL_EDGE_FLAG}
11494 @var{params} returns a single boolean value indicating whether the
11495 current edge flag is @code{GL_TRUE} or @code{GL_FALSE}. The initial
11496 value is @code{GL_TRUE}. See @code{glEdgeFlag}.
11498 @item @code{GL_EDGE_FLAG_ARRAY}
11501 @var{params} returns a single boolean value indicating whether the edge
11502 flag array is enabled. The initial value is @code{GL_FALSE}. See
11503 @code{glEdgeFlagPointer}.
11505 @item @code{GL_EDGE_FLAG_ARRAY_BUFFER_BINDING}
11508 @var{params} returns a single value, the name of the buffer object
11509 associated with the edge flag array. This buffer object would have been
11510 bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
11511 recent call to @code{glEdgeFlagPointer}. If no buffer object was bound
11512 to this target, 0 is returned. The initial value is 0. See
11513 @code{glBindBuffer}.
11515 @item @code{GL_EDGE_FLAG_ARRAY_STRIDE}
11518 @var{params} returns one value, the byte offset between consecutive edge
11519 flags in the edge flag array. The initial value is 0. See
11520 @code{glEdgeFlagPointer}.
11522 @item @code{GL_ELEMENT_ARRAY_BUFFER_BINDING}
11525 @var{params} returns a single value, the name of the buffer object
11526 currently bound to the target @code{GL_ELEMENT_ARRAY_BUFFER}. If no
11527 buffer object is bound to this target, 0 is returned. The initial value
11528 is 0. See @code{glBindBuffer}.
11530 @item @code{GL_FEEDBACK_BUFFER_SIZE}
11533 @var{params} returns one value, the size of the feedback buffer. See
11534 @code{glFeedbackBuffer}.
11536 @item @code{GL_FEEDBACK_BUFFER_TYPE}
11539 @var{params} returns one value, the type of the feedback buffer. See
11540 @code{glFeedbackBuffer}.
11542 @item @code{GL_FOG}
11545 @var{params} returns a single boolean value indicating whether fogging
11546 is enabled. The initial value is @code{GL_FALSE}. See @code{glFog}.
11548 @item @code{GL_FOG_COORD_ARRAY}
11551 @var{params} returns a single boolean value indicating whether the fog
11552 coordinate array is enabled. The initial value is @code{GL_FALSE}. See
11553 @code{glFogCoordPointer}.
11555 @item @code{GL_FOG_COORD_ARRAY_BUFFER_BINDING}
11558 @var{params} returns a single value, the name of the buffer object
11559 associated with the fog coordinate array. This buffer object would have
11560 been bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
11561 recent call to @code{glFogCoordPointer}. If no buffer object was bound
11562 to this target, 0 is returned. The initial value is 0. See
11563 @code{glBindBuffer}.
11565 @item @code{GL_FOG_COORD_ARRAY_STRIDE}
11568 @var{params} returns one value, the byte offset between consecutive fog
11569 coordinates in the fog coordinate array. The initial value is 0. See
11570 @code{glFogCoordPointer}.
11572 @item @code{GL_FOG_COORD_ARRAY_TYPE}
11575 @var{params} returns one value, the type of the fog coordinate array.
11576 The initial value is @code{GL_FLOAT}. See @code{glFogCoordPointer}.
11578 @item @code{GL_FOG_COORD_SRC}
11581 @var{params} returns one value, a symbolic constant indicating the
11582 source of the fog coordinate. The initial value is
11583 @code{GL_FRAGMENT_DEPTH}. See @code{glFog}.
11585 @item @code{GL_FOG_COLOR}
11588 @var{params} returns four values: the red, green, blue, and alpha
11589 components of the fog color. Integer values, if requested, are linearly
11590 mapped from the internal floating-point representation such that 1.0
11591 returns the most positive representable integer value, and @r{-1.0}
11592 returns the most negative representable integer value. The initial value
11593 is (0, 0, 0, 0). See @code{glFog}.
11595 @item @code{GL_FOG_DENSITY}
11598 @var{params} returns one value, the fog density parameter. The initial
11599 value is 1. See @code{glFog}.
11601 @item @code{GL_FOG_END}
11604 @var{params} returns one value, the end factor for the linear fog
11605 equation. The initial value is 1. See @code{glFog}.
11607 @item @code{GL_FOG_HINT}
11610 @var{params} returns one value, a symbolic constant indicating the mode
11611 of the fog hint. The initial value is @code{GL_DONT_CARE}. See
11614 @item @code{GL_FOG_INDEX}
11617 @var{params} returns one value, the fog color index. The initial value
11618 is 0. See @code{glFog}.
11620 @item @code{GL_FOG_MODE}
11623 @var{params} returns one value, a symbolic constant indicating which fog
11624 equation is selected. The initial value is @code{GL_EXP}. See
11627 @item @code{GL_FOG_START}
11630 @var{params} returns one value, the start factor for the linear fog
11631 equation. The initial value is 0. See @code{glFog}.
11633 @item @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT}
11636 @var{params} returns one value, a symbolic constant indicating the mode
11637 of the derivative accuracy hint for fragment shaders. The initial value
11638 is @code{GL_DONT_CARE}. See @code{glHint}.
11640 @item @code{GL_FRONT_FACE}
11643 @var{params} returns one value, a symbolic constant indicating whether
11644 clockwise or counterclockwise polygon winding is treated as
11645 front-facing. The initial value is @code{GL_CCW}. See
11646 @code{glFrontFace}.
11648 @item @code{GL_GENERATE_MIPMAP_HINT}
11651 @var{params} returns one value, a symbolic constant indicating the mode
11652 of the mipmap generation filtering hint. The initial value is
11653 @code{GL_DONT_CARE}. See @code{glHint}.
11655 @item @code{GL_GREEN_BIAS}
11658 @var{params} returns one value, the green bias factor used during pixel
11659 transfers. The initial value is 0.
11661 @item @code{GL_GREEN_BITS}
11664 @var{params} returns one value, the number of green bitplanes in each
11667 @item @code{GL_GREEN_SCALE}
11670 @var{params} returns one value, the green scale factor used during pixel
11671 transfers. The initial value is 1. See @code{glPixelTransfer}.
11673 @item @code{GL_HISTOGRAM}
11676 @var{params} returns a single boolean value indicating whether histogram
11677 is enabled. The initial value is @code{GL_FALSE}. See
11678 @code{glHistogram}.
11680 @item @code{GL_INDEX_ARRAY}
11683 @var{params} returns a single boolean value indicating whether the color
11684 index array is enabled. The initial value is @code{GL_FALSE}. See
11685 @code{glIndexPointer}.
11687 @item @code{GL_INDEX_ARRAY_BUFFER_BINDING}
11690 @var{params} returns a single value, the name of the buffer object
11691 associated with the color index array. This buffer object would have
11692 been bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
11693 recent call to @code{glIndexPointer}. If no buffer object was bound to
11694 this target, 0 is returned. The initial value is 0. See
11695 @code{glBindBuffer}.
11697 @item @code{GL_INDEX_ARRAY_STRIDE}
11700 @var{params} returns one value, the byte offset between consecutive
11701 color indexes in the color index array. The initial value is 0. See
11702 @code{glIndexPointer}.
11704 @item @code{GL_INDEX_ARRAY_TYPE}
11707 @var{params} returns one value, the data type of indexes in the color
11708 index array. The initial value is @code{GL_FLOAT}. See
11709 @code{glIndexPointer}.
11711 @item @code{GL_INDEX_BITS}
11714 @var{params} returns one value, the number of bitplanes in each color
11717 @item @code{GL_INDEX_CLEAR_VALUE}
11720 @var{params} returns one value, the color index used to clear the color
11721 index buffers. The initial value is 0. See @code{glClearIndex}.
11723 @item @code{GL_INDEX_LOGIC_OP}
11726 @var{params} returns a single boolean value indicating whether a
11727 fragment's index values are merged into the framebuffer using a logical
11728 operation. The initial value is @code{GL_FALSE}. See @code{glLogicOp}.
11730 @item @code{GL_INDEX_MODE}
11733 @var{params} returns a single boolean value indicating whether the GL is
11734 in color index mode (@code{GL_TRUE}) or RGBA mode (@code{GL_FALSE}).
11736 @item @code{GL_INDEX_OFFSET}
11739 @var{params} returns one value, the offset added to color and stencil
11740 indices during pixel transfers. The initial value is 0. See
11741 @code{glPixelTransfer}.
11743 @item @code{GL_INDEX_SHIFT}
11746 @var{params} returns one value, the amount that color and stencil
11747 indices are shifted during pixel transfers. The initial value is 0. See
11748 @code{glPixelTransfer}.
11750 @item @code{GL_INDEX_WRITEMASK}
11753 @var{params} returns one value, a mask indicating which bitplanes of
11754 each color index buffer can be written. The initial value is all 1's.
11755 See @code{glIndexMask}.
11757 @item @code{GL_LIGHT}@var{i}
11760 @var{params} returns a single boolean value indicating whether the
11761 specified light is enabled. The initial value is @code{GL_FALSE}. See
11762 @code{glLight} and @code{glLightModel}.
11764 @item @code{GL_LIGHTING}
11767 @var{params} returns a single boolean value indicating whether lighting
11768 is enabled. The initial value is @code{GL_FALSE}. See
11769 @code{glLightModel}.
11771 @item @code{GL_LIGHT_MODEL_AMBIENT}
11774 @var{params} returns four values: the red, green, blue, and alpha
11775 components of the ambient intensity of the entire scene. Integer values,
11776 if requested, are linearly mapped from the internal floating-point
11777 representation such that 1.0 returns the most positive representable
11778 integer value, and @r{-1.0} returns the most negative representable
11779 integer value. The initial value is (0.2, 0.2, 0.2, 1.0). See
11780 @code{glLightModel}.
11782 @item @code{GL_LIGHT_MODEL_COLOR_CONTROL}
11785 @var{params} returns single enumerated value indicating whether specular
11786 reflection calculations are separated from normal lighting computations.
11787 The initial value is @code{GL_SINGLE_COLOR}.
11789 @item @code{GL_LIGHT_MODEL_LOCAL_VIEWER}
11792 @var{params} returns a single boolean value indicating whether specular
11793 reflection calculations treat the viewer as being local to the scene.
11794 The initial value is @code{GL_FALSE}. See @code{glLightModel}.
11796 @item @code{GL_LIGHT_MODEL_TWO_SIDE}
11799 @var{params} returns a single boolean value indicating whether separate
11800 materials are used to compute lighting for front- and back-facing
11801 polygons. The initial value is @code{GL_FALSE}. See @code{glLightModel}.
11803 @item @code{GL_LINE_SMOOTH}
11806 @var{params} returns a single boolean value indicating whether
11807 antialiasing of lines is enabled. The initial value is @code{GL_FALSE}.
11808 See @code{glLineWidth}.
11810 @item @code{GL_LINE_SMOOTH_HINT}
11813 @var{params} returns one value, a symbolic constant indicating the mode
11814 of the line antialiasing hint. The initial value is @code{GL_DONT_CARE}.
11817 @item @code{GL_LINE_STIPPLE}
11820 @var{params} returns a single boolean value indicating whether stippling
11821 of lines is enabled. The initial value is @code{GL_FALSE}. See
11822 @code{glLineStipple}.
11824 @item @code{GL_LINE_STIPPLE_PATTERN}
11827 @var{params} returns one value, the 16-bit line stipple pattern. The
11828 initial value is all 1's. See @code{glLineStipple}.
11830 @item @code{GL_LINE_STIPPLE_REPEAT}
11833 @var{params} returns one value, the line stipple repeat factor. The
11834 initial value is 1. See @code{glLineStipple}.
11836 @item @code{GL_LINE_WIDTH}
11839 @var{params} returns one value, the line width as specified with
11840 @code{glLineWidth}. The initial value is 1.
11842 @item @code{GL_LINE_WIDTH_GRANULARITY}
11845 @var{params} returns one value, the width difference between adjacent
11846 supported widths for antialiased lines. See @code{glLineWidth}.
11848 @item @code{GL_LINE_WIDTH_RANGE}
11851 @var{params} returns two values: the smallest and largest supported
11852 widths for antialiased lines. See @code{glLineWidth}.
11854 @item @code{GL_LIST_BASE}
11857 @var{params} returns one value, the base offset added to all names in
11858 arrays presented to @code{glCallLists}. The initial value is 0. See
11861 @item @code{GL_LIST_INDEX}
11864 @var{params} returns one value, the name of the display list currently
11865 under construction. 0 is returned if no display list is currently under
11866 construction. The initial value is 0. See @code{glNewList}.
11868 @item @code{GL_LIST_MODE}
11871 @var{params} returns one value, a symbolic constant indicating the
11872 construction mode of the display list currently under construction. The
11873 initial value is 0. See @code{glNewList}.
11875 @item @code{GL_LOGIC_OP_MODE}
11878 @var{params} returns one value, a symbolic constant indicating the
11879 selected logic operation mode. The initial value is @code{GL_COPY}. See
11882 @item @code{GL_MAP1_COLOR_4}
11885 @var{params} returns a single boolean value indicating whether 1D
11886 evaluation generates colors. The initial value is @code{GL_FALSE}. See
11889 @item @code{GL_MAP1_GRID_DOMAIN}
11892 @var{params} returns two values: the endpoints of the 1D map's grid
11893 domain. The initial value is (0, 1). See @code{glMapGrid}.
11895 @item @code{GL_MAP1_GRID_SEGMENTS}
11898 @var{params} returns one value, the number of partitions in the 1D map's
11899 grid domain. The initial value is 1. See @code{glMapGrid}.
11901 @item @code{GL_MAP1_INDEX}
11904 @var{params} returns a single boolean value indicating whether 1D
11905 evaluation generates color indices. The initial value is
11906 @code{GL_FALSE}. See @code{glMap1}.
11908 @item @code{GL_MAP1_NORMAL}
11911 @var{params} returns a single boolean value indicating whether 1D
11912 evaluation generates normals. The initial value is @code{GL_FALSE}. See
11915 @item @code{GL_MAP1_TEXTURE_COORD_1}
11918 @var{params} returns a single boolean value indicating whether 1D
11919 evaluation generates 1D texture coordinates. The initial value is
11920 @code{GL_FALSE}. See @code{glMap1}.
11922 @item @code{GL_MAP1_TEXTURE_COORD_2}
11925 @var{params} returns a single boolean value indicating whether 1D
11926 evaluation generates 2D texture coordinates. The initial value is
11927 @code{GL_FALSE}. See @code{glMap1}.
11929 @item @code{GL_MAP1_TEXTURE_COORD_3}
11932 @var{params} returns a single boolean value indicating whether 1D
11933 evaluation generates 3D texture coordinates. The initial value is
11934 @code{GL_FALSE}. See @code{glMap1}.
11936 @item @code{GL_MAP1_TEXTURE_COORD_4}
11939 @var{params} returns a single boolean value indicating whether 1D
11940 evaluation generates 4D texture coordinates. The initial value is
11941 @code{GL_FALSE}. See @code{glMap1}.
11943 @item @code{GL_MAP1_VERTEX_3}
11946 @var{params} returns a single boolean value indicating whether 1D
11947 evaluation generates 3D vertex coordinates. The initial value is
11948 @code{GL_FALSE}. See @code{glMap1}.
11950 @item @code{GL_MAP1_VERTEX_4}
11953 @var{params} returns a single boolean value indicating whether 1D
11954 evaluation generates 4D vertex coordinates. The initial value is
11955 @code{GL_FALSE}. See @code{glMap1}.
11957 @item @code{GL_MAP2_COLOR_4}
11960 @var{params} returns a single boolean value indicating whether 2D
11961 evaluation generates colors. The initial value is @code{GL_FALSE}. See
11964 @item @code{GL_MAP2_GRID_DOMAIN}
11967 @var{params} returns four values: the endpoints of the 2D map's
11968 @r{@var{i}} and @r{@var{j}} grid domains. The initial value is (0,1;
11969 0,1). See @code{glMapGrid}.
11971 @item @code{GL_MAP2_GRID_SEGMENTS}
11974 @var{params} returns two values: the number of partitions in the 2D
11975 map's @r{@var{i}} and @r{@var{j}} grid domains. The initial value is
11976 (1,1). See @code{glMapGrid}.
11978 @item @code{GL_MAP2_INDEX}
11981 @var{params} returns a single boolean value indicating whether 2D
11982 evaluation generates color indices. The initial value is
11983 @code{GL_FALSE}. See @code{glMap2}.
11985 @item @code{GL_MAP2_NORMAL}
11988 @var{params} returns a single boolean value indicating whether 2D
11989 evaluation generates normals. The initial value is @code{GL_FALSE}. See
11992 @item @code{GL_MAP2_TEXTURE_COORD_1}
11995 @var{params} returns a single boolean value indicating whether 2D
11996 evaluation generates 1D texture coordinates. The initial value is
11997 @code{GL_FALSE}. See @code{glMap2}.
11999 @item @code{GL_MAP2_TEXTURE_COORD_2}
12002 @var{params} returns a single boolean value indicating whether 2D
12003 evaluation generates 2D texture coordinates. The initial value is
12004 @code{GL_FALSE}. See @code{glMap2}.
12006 @item @code{GL_MAP2_TEXTURE_COORD_3}
12009 @var{params} returns a single boolean value indicating whether 2D
12010 evaluation generates 3D texture coordinates. The initial value is
12011 @code{GL_FALSE}. See @code{glMap2}.
12013 @item @code{GL_MAP2_TEXTURE_COORD_4}
12016 @var{params} returns a single boolean value indicating whether 2D
12017 evaluation generates 4D texture coordinates. The initial value is
12018 @code{GL_FALSE}. See @code{glMap2}.
12020 @item @code{GL_MAP2_VERTEX_3}
12023 @var{params} returns a single boolean value indicating whether 2D
12024 evaluation generates 3D vertex coordinates. The initial value is
12025 @code{GL_FALSE}. See @code{glMap2}.
12027 @item @code{GL_MAP2_VERTEX_4}
12030 @var{params} returns a single boolean value indicating whether 2D
12031 evaluation generates 4D vertex coordinates. The initial value is
12032 @code{GL_FALSE}. See @code{glMap2}.
12034 @item @code{GL_MAP_COLOR}
12037 @var{params} returns a single boolean value indicating if colors and
12038 color indices are to be replaced by table lookup during pixel transfers.
12039 The initial value is @code{GL_FALSE}. See @code{glPixelTransfer}.
12041 @item @code{GL_MAP_STENCIL}
12044 @var{params} returns a single boolean value indicating if stencil
12045 indices are to be replaced by table lookup during pixel transfers. The
12046 initial value is @code{GL_FALSE}. See @code{glPixelTransfer}.
12048 @item @code{GL_MATRIX_MODE}
12051 @var{params} returns one value, a symbolic constant indicating which
12052 matrix stack is currently the target of all matrix operations. The
12053 initial value is @code{GL_MODELVIEW}. See @code{glMatrixMode}.
12055 @item @code{GL_MAX_3D_TEXTURE_SIZE}
12058 @var{params} returns one value, a rough estimate of the largest 3D
12059 texture that the GL can handle. The value must be at least 16. If the GL
12060 version is 1.2 or greater, use @code{GL_PROXY_TEXTURE_3D} to determine
12061 if a texture is too large. See @code{glTexImage3D}.
12063 @item @code{GL_MAX_CLIENT_ATTRIB_STACK_DEPTH}
12066 @var{params} returns one value indicating the maximum supported depth of
12067 the client attribute stack. See @code{glPushClientAttrib}.
12069 @item @code{GL_MAX_ATTRIB_STACK_DEPTH}
12072 @var{params} returns one value, the maximum supported depth of the
12073 attribute stack. The value must be at least 16. See @code{glPushAttrib}.
12075 @item @code{GL_MAX_CLIP_PLANES}
12078 @var{params} returns one value, the maximum number of
12079 application-defined clipping planes. The value must be at least 6. See
12080 @code{glClipPlane}.
12082 @item @code{GL_MAX_COLOR_MATRIX_STACK_DEPTH}
12085 @var{params} returns one value, the maximum supported depth of the color
12086 matrix stack. The value must be at least 2. See @code{glPushMatrix}.
12088 @item @code{GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS}
12091 @var{params} returns one value, the maximum supported texture image
12092 units that can be used to access texture maps from the vertex shader and
12093 the fragment processor combined. If both the vertex shader and the
12094 fragment processing stage access the same texture image unit, then that
12095 counts as using two texture image units against this limit. The value
12096 must be at least 2. See @code{glActiveTexture}.
12098 @item @code{GL_MAX_CUBE_MAP_TEXTURE_SIZE}
12101 @var{params} returns one value. The value gives a rough estimate of the
12102 largest cube-map texture that the GL can handle. The value must be at
12103 least 16. If the GL version is 1.3 or greater, use
12104 @code{GL_PROXY_TEXTURE_CUBE_MAP} to determine if a texture is too large.
12105 See @code{glTexImage2D}.
12107 @item @code{GL_MAX_DRAW_BUFFERS}
12110 @var{params} returns one value, the maximum number of simultaneous
12111 output colors allowed from a fragment shader using the
12112 @code{gl_FragData} built-in array. The value must be at least 1. See
12113 @code{glDrawBuffers}.
12115 @item @code{GL_MAX_ELEMENTS_INDICES}
12118 @var{params} returns one value, the recommended maximum number of vertex
12119 array indices. See @code{glDrawRangeElements}.
12121 @item @code{GL_MAX_ELEMENTS_VERTICES}
12124 @var{params} returns one value, the recommended maximum number of vertex
12125 array vertices. See @code{glDrawRangeElements}.
12127 @item @code{GL_MAX_EVAL_ORDER}
12130 @var{params} returns one value, the maximum equation order supported by
12131 1D and 2D evaluators. The value must be at least 8. See @code{glMap1}
12134 @item @code{GL_MAX_FRAGMENT_UNIFORM_COMPONENTS}
12137 @var{params} returns one value, the maximum number of individual
12138 floating-point, integer, or boolean values that can be held in uniform
12139 variable storage for a fragment shader. The value must be at least 64.
12140 See @code{glUniform}.
12142 @item @code{GL_MAX_LIGHTS}
12145 @var{params} returns one value, the maximum number of lights. The value
12146 must be at least 8. See @code{glLight}.
12148 @item @code{GL_MAX_LIST_NESTING}
12151 @var{params} returns one value, the maximum recursion depth allowed
12152 during display-list traversal. The value must be at least 64. See
12155 @item @code{GL_MAX_MODELVIEW_STACK_DEPTH}
12158 @var{params} returns one value, the maximum supported depth of the
12159 modelview matrix stack. The value must be at least 32. See
12160 @code{glPushMatrix}.
12162 @item @code{GL_MAX_NAME_STACK_DEPTH}
12165 @var{params} returns one value, the maximum supported depth of the
12166 selection name stack. The value must be at least 64. See
12169 @item @code{GL_MAX_PIXEL_MAP_TABLE}
12172 @var{params} returns one value, the maximum supported size of a
12173 @code{glPixelMap} lookup table. The value must be at least 32. See
12176 @item @code{GL_MAX_PROJECTION_STACK_DEPTH}
12179 @var{params} returns one value, the maximum supported depth of the
12180 projection matrix stack. The value must be at least 2. See
12181 @code{glPushMatrix}.
12183 @item @code{GL_MAX_TEXTURE_COORDS}
12186 @var{params} returns one value, the maximum number of texture coordinate
12187 sets available to vertex and fragment shaders. The value must be at
12188 least 2. See @code{glActiveTexture} and @code{glClientActiveTexture}.
12190 @item @code{GL_MAX_TEXTURE_IMAGE_UNITS}
12193 @var{params} returns one value, the maximum supported texture image
12194 units that can be used to access texture maps from the fragment shader.
12195 The value must be at least 2. See @code{glActiveTexture}.
12197 @item @code{GL_MAX_TEXTURE_LOD_BIAS}
12200 @var{params} returns one value, the maximum, absolute value of the
12201 texture level-of-detail bias. The value must be at least 4.
12203 @item @code{GL_MAX_TEXTURE_SIZE}
12206 @var{params} returns one value. The value gives a rough estimate of the
12207 largest texture that the GL can handle. The value must be at least 64.
12208 If the GL version is 1.1 or greater, use @code{GL_PROXY_TEXTURE_1D} or
12209 @code{GL_PROXY_TEXTURE_2D} to determine if a texture is too large. See
12210 @code{glTexImage1D} and @code{glTexImage2D}.
12212 @item @code{GL_MAX_TEXTURE_STACK_DEPTH}
12215 @var{params} returns one value, the maximum supported depth of the
12216 texture matrix stack. The value must be at least 2. See
12217 @code{glPushMatrix}.
12219 @item @code{GL_MAX_TEXTURE_UNITS}
12222 @var{params} returns a single value indicating the number of
12223 conventional texture units supported. Each conventional texture unit
12224 includes both a texture coordinate set and a texture image unit.
12225 Conventional texture units may be used for fixed-function (non-shader)
12226 rendering. The value must be at least 2. Additional texture coordinate
12227 sets and texture image units may be accessed from vertex and fragment
12228 shaders. See @code{glActiveTexture} and @code{glClientActiveTexture}.
12230 @item @code{GL_MAX_VARYING_FLOATS}
12233 @var{params} returns one value, the maximum number of interpolators
12234 available for processing varying variables used by vertex and fragment
12235 shaders. This value represents the number of individual floating-point
12236 values that can be interpolated; varying variables declared as vectors,
12237 matrices, and arrays will all consume multiple interpolators. The value
12238 must be at least 32.
12240 @item @code{GL_MAX_VERTEX_ATTRIBS}
12243 @var{params} returns one value, the maximum number of 4-component
12244 generic vertex attributes accessible to a vertex shader. The value must
12245 be at least 16. See @code{glVertexAttrib}.
12247 @item @code{GL_MAX_VERTEX_TEXTURE_IMAGE_UNITS}
12250 @var{params} returns one value, the maximum supported texture image
12251 units that can be used to access texture maps from the vertex shader.
12252 The value may be 0. See @code{glActiveTexture}.
12254 @item @code{GL_MAX_VERTEX_UNIFORM_COMPONENTS}
12257 @var{params} returns one value, the maximum number of individual
12258 floating-point, integer, or boolean values that can be held in uniform
12259 variable storage for a vertex shader. The value must be at least 512.
12260 See @code{glUniform}.
12262 @item @code{GL_MAX_VIEWPORT_DIMS}
12265 @var{params} returns two values: the maximum supported width and height
12266 of the viewport. These must be at least as large as the visible
12267 dimensions of the display being rendered to. See @code{glViewport}.
12269 @item @code{GL_MINMAX}
12272 @var{params} returns a single boolean value indicating whether pixel
12273 minmax values are computed. The initial value is @code{GL_FALSE}. See
12276 @item @code{GL_MODELVIEW_MATRIX}
12279 @var{params} returns sixteen values: the modelview matrix on the top of
12280 the modelview matrix stack. Initially this matrix is the identity
12281 matrix. See @code{glPushMatrix}.
12283 @item @code{GL_MODELVIEW_STACK_DEPTH}
12286 @var{params} returns one value, the number of matrices on the modelview
12287 matrix stack. The initial value is 1. See @code{glPushMatrix}.
12289 @item @code{GL_NAME_STACK_DEPTH}
12292 @var{params} returns one value, the number of names on the selection
12293 name stack. The initial value is 0. See @code{glPushName}.
12295 @item @code{GL_NORMAL_ARRAY}
12298 @var{params} returns a single boolean value, indicating whether the
12299 normal array is enabled. The initial value is @code{GL_FALSE}. See
12300 @code{glNormalPointer}.
12302 @item @code{GL_NORMAL_ARRAY_BUFFER_BINDING}
12305 @var{params} returns a single value, the name of the buffer object
12306 associated with the normal array. This buffer object would have been
12307 bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
12308 recent call to @code{glNormalPointer}. If no buffer object was bound to
12309 this target, 0 is returned. The initial value is 0. See
12310 @code{glBindBuffer}.
12312 @item @code{GL_NORMAL_ARRAY_STRIDE}
12315 @var{params} returns one value, the byte offset between consecutive
12316 normals in the normal array. The initial value is 0. See
12317 @code{glNormalPointer}.
12319 @item @code{GL_NORMAL_ARRAY_TYPE}
12322 @var{params} returns one value, the data type of each coordinate in the
12323 normal array. The initial value is @code{GL_FLOAT}. See
12324 @code{glNormalPointer}.
12326 @item @code{GL_NORMALIZE}
12329 @var{params} returns a single boolean value indicating whether normals
12330 are automatically scaled to unit length after they have been transformed
12331 to eye coordinates. The initial value is @code{GL_FALSE}. See
12334 @item @code{GL_NUM_COMPRESSED_TEXTURE_FORMATS}
12337 @var{params} returns a single integer value indicating the number of
12338 available compressed texture formats. The minimum value is 0. See
12339 @code{glCompressedTexImage2D}.
12341 @item @code{GL_PACK_ALIGNMENT}
12344 @var{params} returns one value, the byte alignment used for writing
12345 pixel data to memory. The initial value is 4. See @code{glPixelStore}.
12347 @item @code{GL_PACK_IMAGE_HEIGHT}
12350 @var{params} returns one value, the image height used for writing pixel
12351 data to memory. The initial value is 0. See @code{glPixelStore}.
12353 @item @code{GL_PACK_LSB_FIRST}
12356 @var{params} returns a single boolean value indicating whether
12357 single-bit pixels being written to memory are written first to the least
12358 significant bit of each unsigned byte. The initial value is
12359 @code{GL_FALSE}. See @code{glPixelStore}.
12361 @item @code{GL_PACK_ROW_LENGTH}
12364 @var{params} returns one value, the row length used for writing pixel
12365 data to memory. The initial value is 0. See @code{glPixelStore}.
12367 @item @code{GL_PACK_SKIP_IMAGES}
12370 @var{params} returns one value, the number of pixel images skipped
12371 before the first pixel is written into memory. The initial value is 0.
12372 See @code{glPixelStore}.
12374 @item @code{GL_PACK_SKIP_PIXELS}
12377 @var{params} returns one value, the number of pixel locations skipped
12378 before the first pixel is written into memory. The initial value is 0.
12379 See @code{glPixelStore}.
12381 @item @code{GL_PACK_SKIP_ROWS}
12384 @var{params} returns one value, the number of rows of pixel locations
12385 skipped before the first pixel is written into memory. The initial value
12386 is 0. See @code{glPixelStore}.
12388 @item @code{GL_PACK_SWAP_BYTES}
12391 @var{params} returns a single boolean value indicating whether the bytes
12392 of two-byte and four-byte pixel indices and components are swapped
12393 before being written to memory. The initial value is @code{GL_FALSE}.
12394 See @code{glPixelStore}.
12396 @item @code{GL_PERSPECTIVE_CORRECTION_HINT}
12399 @var{params} returns one value, a symbolic constant indicating the mode
12400 of the perspective correction hint. The initial value is
12401 @code{GL_DONT_CARE}. See @code{glHint}.
12403 @item @code{GL_PIXEL_MAP_A_TO_A_SIZE}
12406 @var{params} returns one value, the size of the alpha-to-alpha pixel
12407 translation table. The initial value is 1. See @code{glPixelMap}.
12409 @item @code{GL_PIXEL_MAP_B_TO_B_SIZE}
12412 @var{params} returns one value, the size of the blue-to-blue pixel
12413 translation table. The initial value is 1. See @code{glPixelMap}.
12415 @item @code{GL_PIXEL_MAP_G_TO_G_SIZE}
12418 @var{params} returns one value, the size of the green-to-green pixel
12419 translation table. The initial value is 1. See @code{glPixelMap}.
12421 @item @code{GL_PIXEL_MAP_I_TO_A_SIZE}
12424 @var{params} returns one value, the size of the index-to-alpha pixel
12425 translation table. The initial value is 1. See @code{glPixelMap}.
12427 @item @code{GL_PIXEL_MAP_I_TO_B_SIZE}
12430 @var{params} returns one value, the size of the index-to-blue pixel
12431 translation table. The initial value is 1. See @code{glPixelMap}.
12433 @item @code{GL_PIXEL_MAP_I_TO_G_SIZE}
12436 @var{params} returns one value, the size of the index-to-green pixel
12437 translation table. The initial value is 1. See @code{glPixelMap}.
12439 @item @code{GL_PIXEL_MAP_I_TO_I_SIZE}
12442 @var{params} returns one value, the size of the index-to-index pixel
12443 translation table. The initial value is 1. See @code{glPixelMap}.
12445 @item @code{GL_PIXEL_MAP_I_TO_R_SIZE}
12448 @var{params} returns one value, the size of the index-to-red pixel
12449 translation table. The initial value is 1. See @code{glPixelMap}.
12451 @item @code{GL_PIXEL_MAP_R_TO_R_SIZE}
12454 @var{params} returns one value, the size of the red-to-red pixel
12455 translation table. The initial value is 1. See @code{glPixelMap}.
12457 @item @code{GL_PIXEL_MAP_S_TO_S_SIZE}
12460 @var{params} returns one value, the size of the stencil-to-stencil pixel
12461 translation table. The initial value is 1. See @code{glPixelMap}.
12463 @item @code{GL_PIXEL_PACK_BUFFER_BINDING}
12466 @var{params} returns a single value, the name of the buffer object
12467 currently bound to the target @code{GL_PIXEL_PACK_BUFFER}. If no buffer
12468 object is bound to this target, 0 is returned. The initial value is 0.
12469 See @code{glBindBuffer}.
12471 @item @code{GL_PIXEL_UNPACK_BUFFER_BINDING}
12474 @var{params} returns a single value, the name of the buffer object
12475 currently bound to the target @code{GL_PIXEL_UNPACK_BUFFER}. If no
12476 buffer object is bound to this target, 0 is returned. The initial value
12477 is 0. See @code{glBindBuffer}.
12479 @item @code{GL_POINT_DISTANCE_ATTENUATION}
12482 @var{params} returns three values, the coefficients for computing the
12483 attenuation value for points. See @code{glPointParameter}.
12485 @item @code{GL_POINT_FADE_THRESHOLD_SIZE}
12488 @var{params} returns one value, the point size threshold for determining
12489 the point size. See @code{glPointParameter}.
12491 @item @code{GL_POINT_SIZE}
12494 @var{params} returns one value, the point size as specified by
12495 @code{glPointSize}. The initial value is 1.
12497 @item @code{GL_POINT_SIZE_GRANULARITY}
12500 @var{params} returns one value, the size difference between adjacent
12501 supported sizes for antialiased points. See @code{glPointSize}.
12503 @item @code{GL_POINT_SIZE_MAX}
12506 @var{params} returns one value, the upper bound for the attenuated point
12507 sizes. The initial value is 0.0. See @code{glPointParameter}.
12509 @item @code{GL_POINT_SIZE_MIN}
12512 @var{params} returns one value, the lower bound for the attenuated point
12513 sizes. The initial value is 1.0. See @code{glPointParameter}.
12515 @item @code{GL_POINT_SIZE_RANGE}
12518 @var{params} returns two values: the smallest and largest supported
12519 sizes for antialiased points. The smallest size must be at most 1, and
12520 the largest size must be at least 1. See @code{glPointSize}.
12522 @item @code{GL_POINT_SMOOTH}
12525 @var{params} returns a single boolean value indicating whether
12526 antialiasing of points is enabled. The initial value is @code{GL_FALSE}.
12527 See @code{glPointSize}.
12529 @item @code{GL_POINT_SMOOTH_HINT}
12532 @var{params} returns one value, a symbolic constant indicating the mode
12533 of the point antialiasing hint. The initial value is
12534 @code{GL_DONT_CARE}. See @code{glHint}.
12536 @item @code{GL_POINT_SPRITE}
12539 @var{params} returns a single boolean value indicating whether point
12540 sprite is enabled. The initial value is @code{GL_FALSE}.
12542 @item @code{GL_POLYGON_MODE}
12545 @var{params} returns two values: symbolic constants indicating whether
12546 front-facing and back-facing polygons are rasterized as points, lines,
12547 or filled polygons. The initial value is @code{GL_FILL}. See
12548 @code{glPolygonMode}.
12550 @item @code{GL_POLYGON_OFFSET_FACTOR}
12553 @var{params} returns one value, the scaling factor used to determine the
12554 variable offset that is added to the depth value of each fragment
12555 generated when a polygon is rasterized. The initial value is 0. See
12556 @code{glPolygonOffset}.
12558 @item @code{GL_POLYGON_OFFSET_UNITS}
12561 @var{params} returns one value. This value is multiplied by an
12562 implementation-specific value and then added to the depth value of each
12563 fragment generated when a polygon is rasterized. The initial value is 0.
12564 See @code{glPolygonOffset}.
12566 @item @code{GL_POLYGON_OFFSET_FILL}
12569 @var{params} returns a single boolean value indicating whether polygon
12570 offset is enabled for polygons in fill mode. The initial value is
12571 @code{GL_FALSE}. See @code{glPolygonOffset}.
12573 @item @code{GL_POLYGON_OFFSET_LINE}
12576 @var{params} returns a single boolean value indicating whether polygon
12577 offset is enabled for polygons in line mode. The initial value is
12578 @code{GL_FALSE}. See @code{glPolygonOffset}.
12580 @item @code{GL_POLYGON_OFFSET_POINT}
12583 @var{params} returns a single boolean value indicating whether polygon
12584 offset is enabled for polygons in point mode. The initial value is
12585 @code{GL_FALSE}. See @code{glPolygonOffset}.
12587 @item @code{GL_POLYGON_SMOOTH}
12590 @var{params} returns a single boolean value indicating whether
12591 antialiasing of polygons is enabled. The initial value is
12592 @code{GL_FALSE}. See @code{glPolygonMode}.
12594 @item @code{GL_POLYGON_SMOOTH_HINT}
12597 @var{params} returns one value, a symbolic constant indicating the mode
12598 of the polygon antialiasing hint. The initial value is
12599 @code{GL_DONT_CARE}. See @code{glHint}.
12601 @item @code{GL_POLYGON_STIPPLE}
12604 @var{params} returns a single boolean value indicating whether polygon
12605 stippling is enabled. The initial value is @code{GL_FALSE}. See
12606 @code{glPolygonStipple}.
12608 @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}
12611 @var{params} returns a single boolean value indicating whether post
12612 color matrix transformation lookup is enabled. The initial value is
12613 @code{GL_FALSE}. See @code{glColorTable}.
12615 @item @code{GL_POST_COLOR_MATRIX_RED_BIAS}
12618 @var{params} returns one value, the red bias factor applied to RGBA
12619 fragments after color matrix transformations. The initial value is 0.
12620 See @code{glPixelTransfer}.
12622 @item @code{GL_POST_COLOR_MATRIX_GREEN_BIAS}
12625 @var{params} returns one value, the green bias factor applied to RGBA
12626 fragments after color matrix transformations. The initial value is 0.
12627 See @code{glPixelTransfer}
12629 @item @code{GL_POST_COLOR_MATRIX_BLUE_BIAS}
12632 @var{params} returns one value, the blue bias factor applied to RGBA
12633 fragments after color matrix transformations. The initial value is 0.
12634 See @code{glPixelTransfer}.
12636 @item @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS}
12639 @var{params} returns one value, the alpha bias factor applied to RGBA
12640 fragments after color matrix transformations. The initial value is 0.
12641 See @code{glPixelTransfer}.
12643 @item @code{GL_POST_COLOR_MATRIX_RED_SCALE}
12646 @var{params} returns one value, the red scale factor applied to RGBA
12647 fragments after color matrix transformations. The initial value is 1.
12648 See @code{glPixelTransfer}.
12650 @item @code{GL_POST_COLOR_MATRIX_GREEN_SCALE}
12653 @var{params} returns one value, the green scale factor applied to RGBA
12654 fragments after color matrix transformations. The initial value is 1.
12655 See @code{glPixelTransfer}.
12657 @item @code{GL_POST_COLOR_MATRIX_BLUE_SCALE}
12660 @var{params} returns one value, the blue scale factor applied to RGBA
12661 fragments after color matrix transformations. The initial value is 1.
12662 See @code{glPixelTransfer}.
12664 @item @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE}
12667 @var{params} returns one value, the alpha scale factor applied to RGBA
12668 fragments after color matrix transformations. The initial value is 1.
12669 See @code{glPixelTransfer}.
12671 @item @code{GL_POST_CONVOLUTION_COLOR_TABLE}
12674 @var{params} returns a single boolean value indicating whether post
12675 convolution lookup is enabled. The initial value is @code{GL_FALSE}. See
12676 @code{glColorTable}.
12678 @item @code{GL_POST_CONVOLUTION_RED_BIAS}
12681 @var{params} returns one value, the red bias factor applied to RGBA
12682 fragments after convolution. The initial value is 0. See
12683 @code{glPixelTransfer}.
12685 @item @code{GL_POST_CONVOLUTION_GREEN_BIAS}
12688 @var{params} returns one value, the green bias factor applied to RGBA
12689 fragments after convolution. The initial value is 0. See
12690 @code{glPixelTransfer}.
12692 @item @code{GL_POST_CONVOLUTION_BLUE_BIAS}
12695 @var{params} returns one value, the blue bias factor applied to RGBA
12696 fragments after convolution. The initial value is 0. See
12697 @code{glPixelTransfer}.
12699 @item @code{GL_POST_CONVOLUTION_ALPHA_BIAS}
12702 @var{params} returns one value, the alpha bias factor applied to RGBA
12703 fragments after convolution. The initial value is 0. See
12704 @code{glPixelTransfer}.
12706 @item @code{GL_POST_CONVOLUTION_RED_SCALE}
12709 @var{params} returns one value, the red scale factor applied to RGBA
12710 fragments after convolution. The initial value is 1. See
12711 @code{glPixelTransfer}.
12713 @item @code{GL_POST_CONVOLUTION_GREEN_SCALE}
12716 @var{params} returns one value, the green scale factor applied to RGBA
12717 fragments after convolution. The initial value is 1. See
12718 @code{glPixelTransfer}.
12720 @item @code{GL_POST_CONVOLUTION_BLUE_SCALE}
12723 @var{params} returns one value, the blue scale factor applied to RGBA
12724 fragments after convolution. The initial value is 1. See
12725 @code{glPixelTransfer}.
12727 @item @code{GL_POST_CONVOLUTION_ALPHA_SCALE}
12730 @var{params} returns one value, the alpha scale factor applied to RGBA
12731 fragments after convolution. The initial value is 1. See
12732 @code{glPixelTransfer}.
12734 @item @code{GL_PROJECTION_MATRIX}
12737 @var{params} returns sixteen values: the projection matrix on the top of
12738 the projection matrix stack. Initially this matrix is the identity
12739 matrix. See @code{glPushMatrix}.
12741 @item @code{GL_PROJECTION_STACK_DEPTH}
12744 @var{params} returns one value, the number of matrices on the projection
12745 matrix stack. The initial value is 1. See @code{glPushMatrix}.
12747 @item @code{GL_READ_BUFFER}
12750 @var{params} returns one value, a symbolic constant indicating which
12751 color buffer is selected for reading. The initial value is
12752 @code{GL_BACK} if there is a back buffer, otherwise it is
12753 @code{GL_FRONT}. See @code{glReadPixels} and @code{glAccum}.
12755 @item @code{GL_RED_BIAS}
12758 @var{params} returns one value, the red bias factor used during pixel
12759 transfers. The initial value is 0.
12761 @item @code{GL_RED_BITS}
12764 @var{params} returns one value, the number of red bitplanes in each
12767 @item @code{GL_RED_SCALE}
12770 @var{params} returns one value, the red scale factor used during pixel
12771 transfers. The initial value is 1. See @code{glPixelTransfer}.
12773 @item @code{GL_RENDER_MODE}
12776 @var{params} returns one value, a symbolic constant indicating whether
12777 the GL is in render, select, or feedback mode. The initial value is
12778 @code{GL_RENDER}. See @code{glRenderMode}.
12780 @item @code{GL_RESCALE_NORMAL}
12783 @var{params} returns single boolean value indicating whether normal
12784 rescaling is enabled. See @code{glEnable}.
12786 @item @code{GL_RGBA_MODE}
12789 @var{params} returns a single boolean value indicating whether the GL is
12790 in RGBA mode (true) or color index mode (false). See @code{glColor}.
12792 @item @code{GL_SAMPLE_BUFFERS}
12795 @var{params} returns a single integer value indicating the number of
12796 sample buffers associated with the framebuffer. See
12797 @code{glSampleCoverage}.
12799 @item @code{GL_SAMPLE_COVERAGE_VALUE}
12802 @var{params} returns a single positive floating-point value indicating
12803 the current sample coverage value. See @code{glSampleCoverage}.
12805 @item @code{GL_SAMPLE_COVERAGE_INVERT}
12808 @var{params} returns a single boolean value indicating if the temporary
12809 coverage value should be inverted. See @code{glSampleCoverage}.
12811 @item @code{GL_SAMPLES}
12814 @var{params} returns a single integer value indicating the coverage mask
12815 size. See @code{glSampleCoverage}.
12817 @item @code{GL_SCISSOR_BOX}
12820 @var{params} returns four values: the @r{@var{x}} and @r{@var{y}} window
12821 coordinates of the scissor box, followed by its width and height.
12822 Initially the @r{@var{x}} and @r{@var{y}} window coordinates are both 0
12823 and the width and height are set to the size of the window. See
12826 @item @code{GL_SCISSOR_TEST}
12829 @var{params} returns a single boolean value indicating whether
12830 scissoring is enabled. The initial value is @code{GL_FALSE}. See
12833 @item @code{GL_SECONDARY_COLOR_ARRAY}
12836 @var{params} returns a single boolean value indicating whether the
12837 secondary color array is enabled. The initial value is @code{GL_FALSE}.
12838 See @code{glSecondaryColorPointer}.
12840 @item @code{GL_SECONDARY_COLOR_ARRAY_BUFFER_BINDING}
12843 @var{params} returns a single value, the name of the buffer object
12844 associated with the secondary color array. This buffer object would have
12845 been bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
12846 recent call to @code{glSecondaryColorPointer}. If no buffer object was
12847 bound to this target, 0 is returned. The initial value is 0. See
12848 @code{glBindBuffer}.
12850 @item @code{GL_SECONDARY_COLOR_ARRAY_SIZE}
12853 @var{params} returns one value, the number of components per color in
12854 the secondary color array. The initial value is 3. See
12855 @code{glSecondaryColorPointer}.
12857 @item @code{GL_SECONDARY_COLOR_ARRAY_STRIDE}
12860 @var{params} returns one value, the byte offset between consecutive
12861 colors in the secondary color array. The initial value is 0. See
12862 @code{glSecondaryColorPointer}.
12864 @item @code{GL_SECONDARY_COLOR_ARRAY_TYPE}
12867 @var{params} returns one value, the data type of each component in the
12868 secondary color array. The initial value is @code{GL_FLOAT}. See
12869 @code{glSecondaryColorPointer}.
12871 @item @code{GL_SELECTION_BUFFER_SIZE}
12874 @var{params} return one value, the size of the selection buffer. See
12875 @code{glSelectBuffer}.
12877 @item @code{GL_SEPARABLE_2D}
12880 @var{params} returns a single boolean value indicating whether 2D
12881 separable convolution is enabled. The initial value is @code{GL_FALSE}.
12882 See @code{glSeparableFilter2D}.
12884 @item @code{GL_SHADE_MODEL}
12887 @var{params} returns one value, a symbolic constant indicating whether
12888 the shading mode is flat or smooth. The initial value is
12889 @code{GL_SMOOTH}. See @code{glShadeModel}.
12891 @item @code{GL_SMOOTH_LINE_WIDTH_RANGE}
12894 @var{params} returns two values, the smallest and largest supported
12895 widths for antialiased lines. See @code{glLineWidth}.
12897 @item @code{GL_SMOOTH_LINE_WIDTH_GRANULARITY}
12900 @var{params} returns one value, the granularity of widths for
12901 antialiased lines. See @code{glLineWidth}.
12903 @item @code{GL_SMOOTH_POINT_SIZE_RANGE}
12906 @var{params} returns two values, the smallest and largest supported
12907 widths for antialiased points. See @code{glPointSize}.
12909 @item @code{GL_SMOOTH_POINT_SIZE_GRANULARITY}
12912 @var{params} returns one value, the granularity of sizes for antialiased
12913 points. See @code{glPointSize}.
12915 @item @code{GL_STENCIL_BACK_FAIL}
12918 @var{params} returns one value, a symbolic constant indicating what
12919 action is taken for back-facing polygons when the stencil test fails.
12920 The initial value is @code{GL_KEEP}. See @code{glStencilOpSeparate}.
12922 @item @code{GL_STENCIL_BACK_FUNC}
12925 @var{params} returns one value, a symbolic constant indicating what
12926 function is used for back-facing polygons to compare the stencil
12927 reference value with the stencil buffer value. The initial value is
12928 @code{GL_ALWAYS}. See @code{glStencilFuncSeparate}.
12930 @item @code{GL_STENCIL_BACK_PASS_DEPTH_FAIL}
12933 @var{params} returns one value, a symbolic constant indicating what
12934 action is taken for back-facing polygons when the stencil test passes,
12935 but the depth test fails. The initial value is @code{GL_KEEP}. See
12936 @code{glStencilOpSeparate}.
12938 @item @code{GL_STENCIL_BACK_PASS_DEPTH_PASS}
12941 @var{params} returns one value, a symbolic constant indicating what
12942 action is taken for back-facing polygons when the stencil test passes
12943 and the depth test passes. The initial value is @code{GL_KEEP}. See
12944 @code{glStencilOpSeparate}.
12946 @item @code{GL_STENCIL_BACK_REF}
12949 @var{params} returns one value, the reference value that is compared
12950 with the contents of the stencil buffer for back-facing polygons. The
12951 initial value is 0. See @code{glStencilFuncSeparate}.
12953 @item @code{GL_STENCIL_BACK_VALUE_MASK}
12956 @var{params} returns one value, the mask that is used for back-facing
12957 polygons to mask both the stencil reference value and the stencil buffer
12958 value before they are compared. The initial value is all 1's. See
12959 @code{glStencilFuncSeparate}.
12961 @item @code{GL_STENCIL_BACK_WRITEMASK}
12964 @var{params} returns one value, the mask that controls writing of the
12965 stencil bitplanes for back-facing polygons. The initial value is all
12966 1's. See @code{glStencilMaskSeparate}.
12968 @item @code{GL_STENCIL_BITS}
12971 @var{params} returns one value, the number of bitplanes in the stencil
12974 @item @code{GL_STENCIL_CLEAR_VALUE}
12977 @var{params} returns one value, the index to which the stencil bitplanes
12978 are cleared. The initial value is 0. See @code{glClearStencil}.
12980 @item @code{GL_STENCIL_FAIL}
12983 @var{params} returns one value, a symbolic constant indicating what
12984 action is taken when the stencil test fails. The initial value is
12985 @code{GL_KEEP}. See @code{glStencilOp}. If the GL version is 2.0 or
12986 greater, this stencil state only affects non-polygons and front-facing
12987 polygons. Back-facing polygons use separate stencil state. See
12988 @code{glStencilOpSeparate}.
12990 @item @code{GL_STENCIL_FUNC}
12993 @var{params} returns one value, a symbolic constant indicating what
12994 function is used to compare the stencil reference value with the stencil
12995 buffer value. The initial value is @code{GL_ALWAYS}. See
12996 @code{glStencilFunc}. If the GL version is 2.0 or greater, this stencil
12997 state only affects non-polygons and front-facing polygons. Back-facing
12998 polygons use separate stencil state. See @code{glStencilFuncSeparate}.
13000 @item @code{GL_STENCIL_PASS_DEPTH_FAIL}
13003 @var{params} returns one value, a symbolic constant indicating what
13004 action is taken when the stencil test passes, but the depth test fails.
13005 The initial value is @code{GL_KEEP}. See @code{glStencilOp}. If the GL
13006 version is 2.0 or greater, this stencil state only affects non-polygons
13007 and front-facing polygons. Back-facing polygons use separate stencil
13008 state. See @code{glStencilOpSeparate}.
13010 @item @code{GL_STENCIL_PASS_DEPTH_PASS}
13013 @var{params} returns one value, a symbolic constant indicating what
13014 action is taken when the stencil test passes and the depth test passes.
13015 The initial value is @code{GL_KEEP}. See @code{glStencilOp}. If the GL
13016 version is 2.0 or greater, this stencil state only affects non-polygons
13017 and front-facing polygons. Back-facing polygons use separate stencil
13018 state. See @code{glStencilOpSeparate}.
13020 @item @code{GL_STENCIL_REF}
13023 @var{params} returns one value, the reference value that is compared
13024 with the contents of the stencil buffer. The initial value is 0. See
13025 @code{glStencilFunc}. If the GL version is 2.0 or greater, this stencil
13026 state only affects non-polygons and front-facing polygons. Back-facing
13027 polygons use separate stencil state. See @code{glStencilFuncSeparate}.
13029 @item @code{GL_STENCIL_TEST}
13032 @var{params} returns a single boolean value indicating whether stencil
13033 testing of fragments is enabled. The initial value is @code{GL_FALSE}.
13034 See @code{glStencilFunc} and @code{glStencilOp}.
13036 @item @code{GL_STENCIL_VALUE_MASK}
13039 @var{params} returns one value, the mask that is used to mask both the
13040 stencil reference value and the stencil buffer value before they are
13041 compared. The initial value is all 1's. See @code{glStencilFunc}. If the
13042 GL version is 2.0 or greater, this stencil state only affects
13043 non-polygons and front-facing polygons. Back-facing polygons use
13044 separate stencil state. See @code{glStencilFuncSeparate}.
13046 @item @code{GL_STENCIL_WRITEMASK}
13049 @var{params} returns one value, the mask that controls writing of the
13050 stencil bitplanes. The initial value is all 1's. See
13051 @code{glStencilMask}. If the GL version is 2.0 or greater, this stencil
13052 state only affects non-polygons and front-facing polygons. Back-facing
13053 polygons use separate stencil state. See @code{glStencilMaskSeparate}.
13055 @item @code{GL_STEREO}
13058 @var{params} returns a single boolean value indicating whether stereo
13059 buffers (left and right) are supported.
13061 @item @code{GL_SUBPIXEL_BITS}
13064 @var{params} returns one value, an estimate of the number of bits of
13065 subpixel resolution that are used to position rasterized geometry in
13066 window coordinates. The value must be at least 4.
13068 @item @code{GL_TEXTURE_1D}
13071 @var{params} returns a single boolean value indicating whether 1D
13072 texture mapping is enabled. The initial value is @code{GL_FALSE}. See
13073 @code{glTexImage1D}.
13075 @item @code{GL_TEXTURE_BINDING_1D}
13078 @var{params} returns a single value, the name of the texture currently
13079 bound to the target @code{GL_TEXTURE_1D}. The initial value is 0. See
13080 @code{glBindTexture}.
13082 @item @code{GL_TEXTURE_2D}
13085 @var{params} returns a single boolean value indicating whether 2D
13086 texture mapping is enabled. The initial value is @code{GL_FALSE}. See
13087 @code{glTexImage2D}.
13089 @item @code{GL_TEXTURE_BINDING_2D}
13092 @var{params} returns a single value, the name of the texture currently
13093 bound to the target @code{GL_TEXTURE_2D}. The initial value is 0. See
13094 @code{glBindTexture}.
13096 @item @code{GL_TEXTURE_3D}
13099 @var{params} returns a single boolean value indicating whether 3D
13100 texture mapping is enabled. The initial value is @code{GL_FALSE}. See
13101 @code{glTexImage3D}.
13103 @item @code{GL_TEXTURE_BINDING_3D}
13106 @var{params} returns a single value, the name of the texture currently
13107 bound to the target @code{GL_TEXTURE_3D}. The initial value is 0. See
13108 @code{glBindTexture}.
13110 @item @code{GL_TEXTURE_BINDING_CUBE_MAP}
13113 @var{params} returns a single value, the name of the texture currently
13114 bound to the target @code{GL_TEXTURE_CUBE_MAP}. The initial value is 0.
13115 See @code{glBindTexture}.
13117 @item @code{GL_TEXTURE_COMPRESSION_HINT}
13120 @var{params} returns a single value indicating the mode of the texture
13121 compression hint. The initial value is @code{GL_DONT_CARE}.
13123 @item @code{GL_TEXTURE_COORD_ARRAY}
13126 @var{params} returns a single boolean value indicating whether the
13127 texture coordinate array is enabled. The initial value is
13128 @code{GL_FALSE}. See @code{glTexCoordPointer}.
13130 @item @code{GL_TEXTURE_COORD_ARRAY_BUFFER_BINDING}
13133 @var{params} returns a single value, the name of the buffer object
13134 associated with the texture coordinate array. This buffer object would
13135 have been bound to the target @code{GL_ARRAY_BUFFER} at the time of the
13136 most recent call to @code{glTexCoordPointer}. If no buffer object was
13137 bound to this target, 0 is returned. The initial value is 0. See
13138 @code{glBindBuffer}.
13140 @item @code{GL_TEXTURE_COORD_ARRAY_SIZE}
13143 @var{params} returns one value, the number of coordinates per element in
13144 the texture coordinate array. The initial value is 4. See
13145 @code{glTexCoordPointer}.
13147 @item @code{GL_TEXTURE_COORD_ARRAY_STRIDE}
13150 @var{params} returns one value, the byte offset between consecutive
13151 elements in the texture coordinate array. The initial value is 0. See
13152 @code{glTexCoordPointer}.
13154 @item @code{GL_TEXTURE_COORD_ARRAY_TYPE}
13157 @var{params} returns one value, the data type of the coordinates in the
13158 texture coordinate array. The initial value is @code{GL_FLOAT}. See
13159 @code{glTexCoordPointer}.
13161 @item @code{GL_TEXTURE_CUBE_MAP}
13164 @var{params} returns a single boolean value indicating whether
13165 cube-mapped texture mapping is enabled. The initial value is
13166 @code{GL_FALSE}. See @code{glTexImage2D}.
13168 @item @code{GL_TEXTURE_GEN_Q}
13171 @var{params} returns a single boolean value indicating whether automatic
13172 generation of the @var{q} texture coordinate is enabled. The initial
13173 value is @code{GL_FALSE}. See @code{glTexGen}.
13175 @item @code{GL_TEXTURE_GEN_R}
13178 @var{params} returns a single boolean value indicating whether automatic
13179 generation of the @var{r} texture coordinate is enabled. The initial
13180 value is @code{GL_FALSE}. See @code{glTexGen}.
13182 @item @code{GL_TEXTURE_GEN_S}
13185 @var{params} returns a single boolean value indicating whether automatic
13186 generation of the @var{S} texture coordinate is enabled. The initial
13187 value is @code{GL_FALSE}. See @code{glTexGen}.
13189 @item @code{GL_TEXTURE_GEN_T}
13192 @var{params} returns a single boolean value indicating whether automatic
13193 generation of the T texture coordinate is enabled. The initial value is
13194 @code{GL_FALSE}. See @code{glTexGen}.
13196 @item @code{GL_TEXTURE_MATRIX}
13199 @var{params} returns sixteen values: the texture matrix on the top of
13200 the texture matrix stack. Initially this matrix is the identity matrix.
13201 See @code{glPushMatrix}.
13203 @item @code{GL_TEXTURE_STACK_DEPTH}
13206 @var{params} returns one value, the number of matrices on the texture
13207 matrix stack. The initial value is 1. See @code{glPushMatrix}.
13209 @item @code{GL_TRANSPOSE_COLOR_MATRIX}
13212 @var{params} returns 16 values, the elements of the color matrix in
13213 row-major order. See @code{glLoadTransposeMatrix}.
13215 @item @code{GL_TRANSPOSE_MODELVIEW_MATRIX}
13218 @var{params} returns 16 values, the elements of the modelview matrix in
13219 row-major order. See @code{glLoadTransposeMatrix}.
13221 @item @code{GL_TRANSPOSE_PROJECTION_MATRIX}
13224 @var{params} returns 16 values, the elements of the projection matrix in
13225 row-major order. See @code{glLoadTransposeMatrix}.
13227 @item @code{GL_TRANSPOSE_TEXTURE_MATRIX}
13230 @var{params} returns 16 values, the elements of the texture matrix in
13231 row-major order. See @code{glLoadTransposeMatrix}.
13233 @item @code{GL_UNPACK_ALIGNMENT}
13236 @var{params} returns one value, the byte alignment used for reading
13237 pixel data from memory. The initial value is 4. See @code{glPixelStore}.
13239 @item @code{GL_UNPACK_IMAGE_HEIGHT}
13242 @var{params} returns one value, the image height used for reading pixel
13243 data from memory. The initial is 0. See @code{glPixelStore}.
13245 @item @code{GL_UNPACK_LSB_FIRST}
13248 @var{params} returns a single boolean value indicating whether
13249 single-bit pixels being read from memory are read first from the least
13250 significant bit of each unsigned byte. The initial value is
13251 @code{GL_FALSE}. See @code{glPixelStore}.
13253 @item @code{GL_UNPACK_ROW_LENGTH}
13256 @var{params} returns one value, the row length used for reading pixel
13257 data from memory. The initial value is 0. See @code{glPixelStore}.
13259 @item @code{GL_UNPACK_SKIP_IMAGES}
13262 @var{params} returns one value, the number of pixel images skipped
13263 before the first pixel is read from memory. The initial value is 0. See
13264 @code{glPixelStore}.
13266 @item @code{GL_UNPACK_SKIP_PIXELS}
13269 @var{params} returns one value, the number of pixel locations skipped
13270 before the first pixel is read from memory. The initial value is 0. See
13271 @code{glPixelStore}.
13273 @item @code{GL_UNPACK_SKIP_ROWS}
13276 @var{params} returns one value, the number of rows of pixel locations
13277 skipped before the first pixel is read from memory. The initial value is
13278 0. See @code{glPixelStore}.
13280 @item @code{GL_UNPACK_SWAP_BYTES}
13283 @var{params} returns a single boolean value indicating whether the bytes
13284 of two-byte and four-byte pixel indices and components are swapped after
13285 being read from memory. The initial value is @code{GL_FALSE}. See
13286 @code{glPixelStore}.
13288 @item @code{GL_VERTEX_ARRAY}
13291 @var{params} returns a single boolean value indicating whether the
13292 vertex array is enabled. The initial value is @code{GL_FALSE}. See
13293 @code{glVertexPointer}.
13295 @item @code{GL_VERTEX_ARRAY_BUFFER_BINDING}
13298 @var{params} returns a single value, the name of the buffer object
13299 associated with the vertex array. This buffer object would have been
13300 bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
13301 recent call to @code{glVertexPointer}. If no buffer object was bound to
13302 this target, 0 is returned. The initial value is 0. See
13303 @code{glBindBuffer}.
13305 @item @code{GL_VERTEX_ARRAY_SIZE}
13308 @var{params} returns one value, the number of coordinates per vertex in
13309 the vertex array. The initial value is 4. See @code{glVertexPointer}.
13311 @item @code{GL_VERTEX_ARRAY_STRIDE}
13314 @var{params} returns one value, the byte offset between consecutive
13315 vertices in the vertex array. The initial value is 0. See
13316 @code{glVertexPointer}.
13318 @item @code{GL_VERTEX_ARRAY_TYPE}
13321 @var{params} returns one value, the data type of each coordinate in the
13322 vertex array. The initial value is @code{GL_FLOAT}. See
13323 @code{glVertexPointer}.
13325 @item @code{GL_VERTEX_PROGRAM_POINT_SIZE}
13328 @var{params} returns a single boolean value indicating whether vertex
13329 program point size mode is enabled. If enabled, and a vertex shader is
13330 active, then the point size is taken from the shader built-in
13331 @code{gl_PointSize}. If disabled, and a vertex shader is active, then
13332 the point size is taken from the point state as specified by
13333 @code{glPointSize}. The initial value is @code{GL_FALSE}.
13335 @item @code{GL_VERTEX_PROGRAM_TWO_SIDE}
13338 @var{params} returns a single boolean value indicating whether vertex
13339 program two-sided color mode is enabled. If enabled, and a vertex shader
13340 is active, then the GL chooses the back color output for back-facing
13341 polygons, and the front color output for non-polygons and front-facing
13342 polygons. If disabled, and a vertex shader is active, then the front
13343 color output is always selected. The initial value is @code{GL_FALSE}.
13345 @item @code{GL_VIEWPORT}
13348 @var{params} returns four values: the @r{@var{x}} and @r{@var{y}} window
13349 coordinates of the viewport, followed by its width and height. Initially
13350 the @r{@var{x}} and @r{@var{y}} window coordinates are both set to 0,
13351 and the width and height are set to the width and height of the window
13352 into which the GL will do its rendering. See @code{glViewport}.
13354 @item @code{GL_ZOOM_X}
13357 @var{params} returns one value, the @r{@var{x}} pixel zoom factor. The
13358 initial value is 1. See @code{glPixelZoom}.
13360 @item @code{GL_ZOOM_Y}
13363 @var{params} returns one value, the @r{@var{y}} pixel zoom factor. The
13364 initial value is 1. See @code{glPixelZoom}.
13368 Many of the boolean parameters can also be queried more easily using
13369 @code{glIsEnabled}.
13371 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
13374 @code{GL_INVALID_OPERATION} is generated if @code{glGet} is executed
13375 between the execution of @code{glBegin} and the corresponding execution
13382 @deftypefun void glHint target mode
13383 Specify implementation-specific hints.
13387 Specifies a symbolic constant indicating the behavior to be controlled.
13388 @code{GL_FOG_HINT}, @code{GL_GENERATE_MIPMAP_HINT},
13389 @code{GL_LINE_SMOOTH_HINT}, @code{GL_PERSPECTIVE_CORRECTION_HINT},
13390 @code{GL_POINT_SMOOTH_HINT}, @code{GL_POLYGON_SMOOTH_HINT},
13391 @code{GL_TEXTURE_COMPRESSION_HINT}, and
13392 @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT} are accepted.
13395 Specifies a symbolic constant indicating the desired behavior.
13396 @code{GL_FASTEST}, @code{GL_NICEST}, and @code{GL_DONT_CARE} are
13401 Certain aspects of GL behavior, when there is room for interpretation,
13402 can be controlled with hints. A hint is specified with two arguments.
13403 @var{target} is a symbolic constant indicating the behavior to be
13404 controlled, and @var{mode} is another symbolic constant indicating the
13405 desired behavior. The initial value for each @var{target} is
13406 @code{GL_DONT_CARE}. @var{mode} can be one of the following:
13409 @item @code{GL_FASTEST}
13412 The most efficient option should be chosen.
13414 @item @code{GL_NICEST}
13417 The most correct, or highest quality, option should be chosen.
13419 @item @code{GL_DONT_CARE}
13426 Though the implementation aspects that can be hinted are well defined,
13427 the interpretation of the hints depends on the implementation. The hint
13428 aspects that can be specified with @var{target}, along with suggested
13429 semantics, are as follows:
13432 @item @code{GL_FOG_HINT}
13435 Indicates the accuracy of fog calculation. If per-pixel fog calculation
13436 is not efficiently supported by the GL implementation, hinting
13437 @code{GL_DONT_CARE} or @code{GL_FASTEST} can result in per-vertex
13438 calculation of fog effects.
13440 @item @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT}
13443 Indicates the accuracy of the derivative calculation for the GL shading
13444 language fragment processing built-in functions: @code{dFdx},
13445 @code{dFdy}, and @code{fwidth}.
13447 @item @code{GL_GENERATE_MIPMAP_HINT}
13450 Indicates the quality of filtering when generating mipmap images.
13452 @item @code{GL_LINE_SMOOTH_HINT}
13455 Indicates the sampling quality of antialiased lines. If a larger filter
13456 function is applied, hinting @code{GL_NICEST} can result in more pixel
13457 fragments being generated during rasterization.
13459 @item @code{GL_PERSPECTIVE_CORRECTION_HINT}
13462 Indicates the quality of color, texture coordinate, and fog coordinate
13463 interpolation. If perspective-corrected parameter interpolation is not
13464 efficiently supported by the GL implementation, hinting
13465 @code{GL_DONT_CARE} or @code{GL_FASTEST} can result in simple linear
13466 interpolation of colors and/or texture coordinates.
13468 @item @code{GL_POINT_SMOOTH_HINT}
13471 Indicates the sampling quality of antialiased points. If a larger filter
13472 function is applied, hinting @code{GL_NICEST} can result in more pixel
13473 fragments being generated during rasterization.
13475 @item @code{GL_POLYGON_SMOOTH_HINT}
13478 Indicates the sampling quality of antialiased polygons. Hinting
13479 @code{GL_NICEST} can result in more pixel fragments being generated
13480 during rasterization, if a larger filter function is applied.
13482 @item @code{GL_TEXTURE_COMPRESSION_HINT}
13485 Indicates the quality and performance of the compressing texture images.
13486 Hinting @code{GL_FASTEST} indicates that texture images should be
13487 compressed as quickly as possible, while @code{GL_NICEST} indicates that
13488 texture images should be compressed with as little image quality loss as
13489 possible. @code{GL_NICEST} should be selected if the texture is to be
13490 retrieved by @code{glGetCompressedTexImage} for reuse.
13494 @code{GL_INVALID_ENUM} is generated if either @var{target} or @var{mode}
13495 is not an accepted value.
13497 @code{GL_INVALID_OPERATION} is generated if @code{glHint} is executed
13498 between the execution of @code{glBegin} and the corresponding execution
13503 @deftypefun void glHistogram target width internalformat sink
13504 Define histogram table.
13508 The histogram whose parameters are to be set. Must be one of
13509 @code{GL_HISTOGRAM} or @code{GL_PROXY_HISTOGRAM}.
13512 The number of entries in the histogram table. Must be a power of 2.
13514 @item @var{internalformat}
13515 The format of entries in the histogram table. Must be one of
13516 @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
13517 @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
13518 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
13519 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
13520 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
13521 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
13522 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
13523 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
13524 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
13525 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
13526 @code{GL_RGBA12}, or @code{GL_RGBA16}.
13529 If @code{GL_TRUE}, pixels will be consumed by the histogramming process
13530 and no drawing or texture loading will take place. If @code{GL_FALSE},
13531 pixels will proceed to the minmax process after histogramming.
13535 When @code{GL_HISTOGRAM} is enabled, RGBA color components are converted
13536 to histogram table indices by clamping to the range [0,1], multiplying
13537 by the width of the histogram table, and rounding to the nearest
13538 integer. The table entries selected by the RGBA indices are then
13539 incremented. (If the internal format of the histogram table includes
13540 luminance, then the index derived from the R color component determines
13541 the luminance table entry to be incremented.) If a histogram table entry
13542 is incremented beyond its maximum value, then its value becomes
13543 undefined. (This is not an error.)
13545 Histogramming is performed only for RGBA pixels (though these may be
13546 specified originally as color indices and converted to RGBA by index
13547 table lookup). Histogramming is enabled with @code{glEnable} and
13548 disabled with @code{glDisable}.
13550 When @var{target} is @code{GL_HISTOGRAM}, @code{glHistogram} redefines
13551 the current histogram table to have @var{width} entries of the format
13552 specified by @var{internalformat}. The entries are indexed 0 through
13553 @r{@var{width}-1}, and all entries are initialized to zero. The values
13554 in the previous histogram table, if any, are lost. If @var{sink} is
13555 @code{GL_TRUE}, then pixels are discarded after histogramming; no
13556 further processing of the pixels takes place, and no drawing, texture
13557 loading, or pixel readback will result.
13559 When @var{target} is @code{GL_PROXY_HISTOGRAM}, @code{glHistogram}
13560 computes all state information as if the histogram table were to be
13561 redefined, but does not actually define the new table. If the requested
13562 histogram table is too large to be supported, then the state information
13563 will be set to zero. This provides a way to determine if a histogram
13564 table with the given parameters can be supported.
13568 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
13571 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
13572 is not a power of 2.
13574 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
13575 of the allowable values.
13577 @code{GL_TABLE_TOO_LARGE} is generated if @var{target} is
13578 @code{GL_HISTOGRAM} and the histogram table specified is too large for
13579 the implementation.
13581 @code{GL_INVALID_OPERATION} is generated if @code{glHistogram} is
13582 executed between the execution of @code{glBegin} and the corresponding
13583 execution of @code{glEnd}.
13587 @deftypefun void glIndexMask mask
13588 Control the writing of individual bits in the color index buffers.
13592 Specifies a bit mask to enable and disable the writing of individual
13593 bits in the color index buffers. Initially, the mask is all 1's.
13597 @code{glIndexMask} controls the writing of individual bits in the color
13598 index buffers. The least significant @r{@var{n}} bits of @var{mask},
13599 where @r{@var{n}} is the number of bits in a color index buffer, specify
13600 a mask. Where a 1 (one) appears in the mask, it's possible to write to
13601 the corresponding bit in the color index buffer (or buffers). Where a 0
13602 (zero) appears, the corresponding bit is write-protected.
13604 This mask is used only in color index mode, and it affects only the
13605 buffers currently selected for writing (see @code{glDrawBuffer}).
13606 Initially, all bits are enabled for writing.
13608 @code{GL_INVALID_OPERATION} is generated if @code{glIndexMask} is
13609 executed between the execution of @code{glBegin} and the corresponding
13610 execution of @code{glEnd}.
13614 @deftypefun void glIndexPointer type stride pointer
13615 Define an array of color indexes.
13619 Specifies the data type of each color index in the array. Symbolic
13620 constants @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, @code{GL_INT},
13621 @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value is
13625 Specifies the byte offset between consecutive color indexes. If
13626 @var{stride} is 0, the color indexes are understood to be tightly packed
13627 in the array. The initial value is 0.
13629 @item @var{pointer}
13630 Specifies a pointer to the first index in the array. The initial value
13635 @code{glIndexPointer} specifies the location and data format of an array
13636 of color indexes to use when rendering. @var{type} specifies the data
13637 type of each color index and @var{stride} specifies the byte stride from
13638 one color index to the next, allowing vertices and attributes to be
13639 packed into a single array or stored in separate arrays.
13641 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
13642 target (see @code{glBindBuffer}) while a color index array is specified,
13643 @var{pointer} is treated as a byte offset into the buffer object's data
13644 store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING})
13645 is saved as color index vertex array client-side state
13646 (@code{GL_INDEX_ARRAY_BUFFER_BINDING}).
13648 When a color index array is specified, @var{type}, @var{stride}, and
13649 @var{pointer} are saved as client-side state, in addition to the current
13650 vertex array buffer object binding.
13652 To enable and disable the color index array, call
13653 @code{glEnableClientState} and @code{glDisableClientState} with the
13654 argument @code{GL_INDEX_ARRAY}. If enabled, the color index array is
13655 used when @code{glDrawArrays}, @code{glMultiDrawArrays},
13656 @code{glDrawElements}, @code{glMultiDrawElements},
13657 @code{glDrawRangeElements}, or @code{glArrayElement} is called.
13659 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
13662 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
13666 @deftypefun void glIndexs c
13667 @deftypefunx void glIndexi c
13668 @deftypefunx void glIndexf c
13669 @deftypefunx void glIndexd c
13670 @deftypefunx void glIndexub c
13671 @deftypefunx void glIndexsv c
13672 @deftypefunx void glIndexiv c
13673 @deftypefunx void glIndexfv c
13674 @deftypefunx void glIndexdv c
13675 @deftypefunx void glIndexubv c
13676 Set the current color index.
13680 Specifies the new value for the current color index.
13686 @code{glIndex} updates the current (single-valued) color index. It takes
13687 one argument, the new value for the current color index.
13689 The current index is stored as a floating-point value. Integer values
13690 are converted directly to floating-point values, with no special
13691 mapping. The initial value is 1.
13693 Index values outside the representable range of the color index buffer
13694 are not clamped. However, before an index is dithered (if enabled) and
13695 written to the frame buffer, it is converted to fixed-point format. Any
13696 bits in the integer portion of the resulting fixed-point value that do
13697 not correspond to bits in the frame buffer are masked out.
13701 @deftypefun void glInitNames
13702 Initialize the name stack.
13704 The name stack is used during selection mode to allow sets of rendering
13705 commands to be uniquely identified. It consists of an ordered set of
13706 unsigned integers. @code{glInitNames} causes the name stack to be
13707 initialized to its default empty state.
13709 The name stack is always empty while the render mode is not
13710 @code{GL_SELECT}. Calls to @code{glInitNames} while the render mode is
13711 not @code{GL_SELECT} are ignored.
13713 @code{GL_INVALID_OPERATION} is generated if @code{glInitNames} is
13714 executed between the execution of @code{glBegin} and the corresponding
13715 execution of @code{glEnd}.
13719 @deftypefun void glInterleavedArrays format stride pointer
13720 Simultaneously specify and enable several interleaved arrays.
13724 Specifies the type of array to enable. Symbolic constants @code{GL_V2F},
13725 @code{GL_V3F}, @code{GL_C4UB_V2F}, @code{GL_C4UB_V3F},
13726 @code{GL_C3F_V3F}, @code{GL_N3F_V3F}, @code{GL_C4F_N3F_V3F},
13727 @code{GL_T2F_V3F}, @code{GL_T4F_V4F}, @code{GL_T2F_C4UB_V3F},
13728 @code{GL_T2F_C3F_V3F}, @code{GL_T2F_N3F_V3F}, @code{GL_T2F_C4F_N3F_V3F},
13729 and @code{GL_T4F_C4F_N3F_V4F} are accepted.
13732 Specifies the offset in bytes between each aggregate array element.
13736 @code{glInterleavedArrays} lets you specify and enable individual color,
13737 normal, texture and vertex arrays whose elements are part of a larger
13738 aggregate array element. For some implementations, this is more
13739 efficient than specifying the arrays separately.
13741 If @var{stride} is 0, the aggregate elements are stored consecutively.
13742 Otherwise, @var{stride} bytes occur between the beginning of one
13743 aggregate array element and the beginning of the next aggregate array
13746 @var{format} serves as a ``key'' describing the extraction of individual
13747 arrays from the aggregate array. If @var{format} contains a T, then
13748 texture coordinates are extracted from the interleaved array. If C is
13749 present, color values are extracted. If N is present, normal coordinates
13750 are extracted. Vertex coordinates are always extracted.
13752 The digits 2, 3, and 4 denote how many values are extracted. F indicates
13753 that values are extracted as floating-point values. Colors may also be
13754 extracted as 4 unsigned bytes if 4UB follows the C. If a color is
13755 extracted as 4 unsigned bytes, the vertex array element which follows is
13756 located at the first possible floating-point aligned address.
13758 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
13761 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
13765 @deftypefun GLboolean glIsBuffer buffer
13766 Determine if a name corresponds to a buffer object.
13770 Specifies a value that may be the name of a buffer object.
13774 @code{glIsBuffer} returns @code{GL_TRUE} if @var{buffer} is currently
13775 the name of a buffer object. If @var{buffer} is zero, or is a non-zero
13776 value that is not currently the name of a buffer object, or if an error
13777 occurs, @code{glIsBuffer} returns @code{GL_FALSE}.
13779 A name returned by @code{glGenBuffers}, but not yet associated with a
13780 buffer object by calling @code{glBindBuffer}, is not the name of a
13783 @code{GL_INVALID_OPERATION} is generated if @code{glIsBuffer} is
13784 executed between the execution of @code{glBegin} and the corresponding
13785 execution of @code{glEnd}.
13789 @deftypefun GLboolean glIsEnabled cap
13790 Test whether a capability is enabled.
13794 Specifies a symbolic constant indicating a GL capability.
13798 @code{glIsEnabled} returns @code{GL_TRUE} if @var{cap} is an enabled
13799 capability and returns @code{GL_FALSE} otherwise. Initially all
13800 capabilities except @code{GL_DITHER} are disabled; @code{GL_DITHER} is
13803 The following capabilities are accepted for @var{cap}:
13808 @item @strong{Constant}
13811 @item @code{GL_ALPHA_TEST}
13814 @item @code{GL_AUTO_NORMAL}
13817 @item @code{GL_BLEND}
13818 @code{glBlendFunc}, @code{glLogicOp}
13820 @item @code{GL_CLIP_PLANE}@var{i}
13823 @item @code{GL_COLOR_ARRAY}
13824 @code{glColorPointer}
13826 @item @code{GL_COLOR_LOGIC_OP}
13829 @item @code{GL_COLOR_MATERIAL}
13830 @code{glColorMaterial}
13832 @item @code{GL_COLOR_SUM}
13833 @code{glSecondaryColor}
13835 @item @code{GL_COLOR_TABLE}
13836 @code{glColorTable}
13838 @item @code{GL_CONVOLUTION_1D}
13839 @code{glConvolutionFilter1D}
13841 @item @code{GL_CONVOLUTION_2D}
13842 @code{glConvolutionFilter2D}
13844 @item @code{GL_CULL_FACE}
13847 @item @code{GL_DEPTH_TEST}
13848 @code{glDepthFunc}, @code{glDepthRange}
13850 @item @code{GL_DITHER}
13853 @item @code{GL_EDGE_FLAG_ARRAY}
13854 @code{glEdgeFlagPointer}
13856 @item @code{GL_FOG}
13859 @item @code{GL_FOG_COORD_ARRAY}
13860 @code{glFogCoordPointer}
13862 @item @code{GL_HISTOGRAM}
13865 @item @code{GL_INDEX_ARRAY}
13866 @code{glIndexPointer}
13868 @item @code{GL_INDEX_LOGIC_OP}
13871 @item @code{GL_LIGHT}@var{i}
13872 @code{glLightModel}, @code{glLight}
13874 @item @code{GL_LIGHTING}
13875 @code{glMaterial}, @code{glLightModel}, @code{glLight}
13877 @item @code{GL_LINE_SMOOTH}
13880 @item @code{GL_LINE_STIPPLE}
13881 @code{glLineStipple}
13883 @item @code{GL_MAP1_COLOR_4}
13886 @item @code{GL_MAP1_INDEX}
13889 @item @code{GL_MAP1_NORMAL}
13892 @item @code{GL_MAP1_TEXTURE_COORD_1}
13895 @item @code{GL_MAP1_TEXTURE_COORD_2}
13898 @item @code{GL_MAP1_TEXTURE_COORD_3}
13901 @item @code{GL_MAP1_TEXTURE_COORD_4}
13904 @item @code{GL_MAP2_COLOR_4}
13907 @item @code{GL_MAP2_INDEX}
13910 @item @code{GL_MAP2_NORMAL}
13913 @item @code{GL_MAP2_TEXTURE_COORD_1}
13916 @item @code{GL_MAP2_TEXTURE_COORD_2}
13919 @item @code{GL_MAP2_TEXTURE_COORD_3}
13922 @item @code{GL_MAP2_TEXTURE_COORD_4}
13925 @item @code{GL_MAP2_VERTEX_3}
13928 @item @code{GL_MAP2_VERTEX_4}
13931 @item @code{GL_MINMAX}
13934 @item @code{GL_MULTISAMPLE}
13935 @code{glSampleCoverage}
13937 @item @code{GL_NORMAL_ARRAY}
13938 @code{glNormalPointer}
13940 @item @code{GL_NORMALIZE}
13943 @item @code{GL_POINT_SMOOTH}
13946 @item @code{GL_POINT_SPRITE}
13949 @item @code{GL_POLYGON_SMOOTH}
13950 @code{glPolygonMode}
13952 @item @code{GL_POLYGON_OFFSET_FILL}
13953 @code{glPolygonOffset}
13955 @item @code{GL_POLYGON_OFFSET_LINE}
13956 @code{glPolygonOffset}
13958 @item @code{GL_POLYGON_OFFSET_POINT}
13959 @code{glPolygonOffset}
13961 @item @code{GL_POLYGON_STIPPLE}
13962 @code{glPolygonStipple}
13964 @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}
13965 @code{glColorTable}
13967 @item @code{GL_POST_CONVOLUTION_COLOR_TABLE}
13968 @code{glColorTable}
13970 @item @code{GL_RESCALE_NORMAL}
13973 @item @code{GL_SAMPLE_ALPHA_TO_COVERAGE}
13974 @code{glSampleCoverage}
13976 @item @code{GL_SAMPLE_ALPHA_TO_ONE}
13977 @code{glSampleCoverage}
13979 @item @code{GL_SAMPLE_COVERAGE}
13980 @code{glSampleCoverage}
13982 @item @code{GL_SCISSOR_TEST}
13985 @item @code{GL_SECONDARY_COLOR_ARRAY}
13986 @code{glSecondaryColorPointer}
13988 @item @code{GL_SEPARABLE_2D}
13989 @code{glSeparableFilter2D}
13991 @item @code{GL_STENCIL_TEST}
13992 @code{glStencilFunc}, @code{glStencilOp}
13994 @item @code{GL_TEXTURE_1D}
13995 @code{glTexImage1D}
13997 @item @code{GL_TEXTURE_2D}
13998 @code{glTexImage2D}
14000 @item @code{GL_TEXTURE_3D}
14001 @code{glTexImage3D}
14003 @item @code{GL_TEXTURE_COORD_ARRAY}
14004 @code{glTexCoordPointer}
14006 @item @code{GL_TEXTURE_CUBE_MAP}
14007 @code{glTexImage2D}
14009 @item @code{GL_TEXTURE_GEN_Q}
14012 @item @code{GL_TEXTURE_GEN_R}
14015 @item @code{GL_TEXTURE_GEN_S}
14018 @item @code{GL_TEXTURE_GEN_T}
14021 @item @code{GL_VERTEX_ARRAY}
14022 @code{glVertexPointer}
14024 @item @code{GL_VERTEX_PROGRAM_POINT_SIZE}
14027 @item @code{GL_VERTEX_PROGRAM_TWO_SIDE}
14034 @code{GL_INVALID_ENUM} is generated if @var{cap} is not an accepted
14037 @code{GL_INVALID_OPERATION} is generated if @code{glIsEnabled} is
14038 executed between the execution of @code{glBegin} and the corresponding
14039 execution of @code{glEnd}.
14043 @deftypefun GLboolean glIsList list
14044 Determine if a name corresponds to a display list.
14048 Specifies a potential display list name.
14052 @code{glIsList} returns @code{GL_TRUE} if @var{list} is the name of a
14053 display list and returns @code{GL_FALSE} if it is not, or if an error
14056 A name returned by @code{glGenLists}, but not yet associated with a
14057 display list by calling @code{glNewList}, is not the name of a display
14060 @code{GL_INVALID_OPERATION} is generated if @code{glIsList} is executed
14061 between the execution of @code{glBegin} and the corresponding execution
14066 @deftypefun GLboolean glIsProgram program
14067 Determines if a name corresponds to a program object.
14070 @item @var{program}
14071 Specifies a potential program object.
14075 @code{glIsProgram} returns @code{GL_TRUE} if @var{program} is the name
14076 of a program object previously created with @code{glCreateProgram} and
14077 not yet deleted with @code{glDeleteProgram}. If @var{program} is zero or
14078 a non-zero value that is not the name of a program object, or if an
14079 error occurs, @code{glIsProgram} returns @code{GL_FALSE}.
14081 @code{GL_INVALID_OPERATION} is generated if @code{glIsProgram} is
14082 executed between the execution of @code{glBegin} and the corresponding
14083 execution of @code{glEnd}.
14087 @deftypefun GLboolean glIsQuery id
14088 Determine if a name corresponds to a query object.
14092 Specifies a value that may be the name of a query object.
14096 @code{glIsQuery} returns @code{GL_TRUE} if @var{id} is currently the
14097 name of a query object. If @var{id} is zero, or is a non-zero value that
14098 is not currently the name of a query object, or if an error occurs,
14099 @code{glIsQuery} returns @code{GL_FALSE}.
14101 A name returned by @code{glGenQueries}, but not yet associated with a
14102 query object by calling @code{glBeginQuery}, is not the name of a query
14105 @code{GL_INVALID_OPERATION} is generated if @code{glIsQuery} is executed
14106 between the execution of @code{glBegin} and the corresponding execution
14111 @deftypefun GLboolean glIsShader shader
14112 Determines if a name corresponds to a shader object.
14116 Specifies a potential shader object.
14120 @code{glIsShader} returns @code{GL_TRUE} if @var{shader} is the name of
14121 a shader object previously created with @code{glCreateShader} and not
14122 yet deleted with @code{glDeleteShader}. If @var{shader} is zero or a
14123 non-zero value that is not the name of a shader object, or if an error
14124 occurs, @code{glIsShader } returns @code{GL_FALSE}.
14126 @code{GL_INVALID_OPERATION} is generated if @code{glIsShader} is
14127 executed between the execution of @code{glBegin} and the corresponding
14128 execution of @code{glEnd}.
14132 @deftypefun GLboolean glIsTexture texture
14133 Determine if a name corresponds to a texture.
14136 @item @var{texture}
14137 Specifies a value that may be the name of a texture.
14141 @code{glIsTexture} returns @code{GL_TRUE} if @var{texture} is currently
14142 the name of a texture. If @var{texture} is zero, or is a non-zero value
14143 that is not currently the name of a texture, or if an error occurs,
14144 @code{glIsTexture} returns @code{GL_FALSE}.
14146 A name returned by @code{glGenTextures}, but not yet associated with a
14147 texture by calling @code{glBindTexture}, is not the name of a texture.
14149 @code{GL_INVALID_OPERATION} is generated if @code{glIsTexture} is
14150 executed between the execution of @code{glBegin} and the corresponding
14151 execution of @code{glEnd}.
14155 @deftypefun void glLightModelf pname param
14156 @deftypefunx void glLightModeli pname param
14157 @deftypefunx void glLightModelfv pname params
14158 @deftypefunx void glLightModeliv pname params
14159 Set the lighting model parameters.
14163 Specifies a single-valued lighting model parameter.
14164 @code{GL_LIGHT_MODEL_LOCAL_VIEWER}, @code{GL_LIGHT_MODEL_COLOR_CONTROL},
14165 and @code{GL_LIGHT_MODEL_TWO_SIDE} are accepted.
14168 Specifies the value that @var{param} will be set to.
14172 @code{glLightModel} sets the lighting model parameter. @var{pname} names
14173 a parameter and @var{params} gives the new value. There are three
14174 lighting model parameters:
14177 @item @code{GL_LIGHT_MODEL_AMBIENT}
14180 @var{params} contains four integer or floating-point values that specify
14181 the ambient RGBA intensity of the entire scene. Integer values are
14182 mapped linearly such that the most positive representable value maps to
14183 1.0, and the most negative representable value maps to @r{-1.0}.
14184 Floating-point values are mapped directly. Neither integer nor
14185 floating-point values are clamped. The initial ambient scene intensity
14186 is (0.2, 0.2, 0.2, 1.0).
14188 @item @code{GL_LIGHT_MODEL_COLOR_CONTROL}
14191 @var{params} must be either @code{GL_SEPARATE_SPECULAR_COLOR} or
14192 @code{GL_SINGLE_COLOR}. @code{GL_SINGLE_COLOR} specifies that a single
14193 color is generated from the lighting computation for a vertex.
14194 @code{GL_SEPARATE_SPECULAR_COLOR} specifies that the specular color
14195 computation of lighting be stored separately from the remainder of the
14196 lighting computation. The specular color is summed into the generated
14197 fragment's color after the application of texture mapping (if enabled).
14198 The initial value is @code{GL_SINGLE_COLOR}.
14200 @item @code{GL_LIGHT_MODEL_LOCAL_VIEWER}
14203 @var{params} is a single integer or floating-point value that specifies
14204 how specular reflection angles are computed. If @var{params} is 0 (or
14205 0.0), specular reflection angles take the view direction to be parallel
14206 to and in the direction of the -@var{z} axis, regardless of the location
14207 of the vertex in eye coordinates. Otherwise, specular reflections are
14208 computed from the origin of the eye coordinate system. The initial value
14211 @item @code{GL_LIGHT_MODEL_TWO_SIDE}
14214 @var{params} is a single integer or floating-point value that specifies
14215 whether one- or two-sided lighting calculations are done for polygons.
14216 It has no effect on the lighting calculations for points, lines, or
14217 bitmaps. If @var{params} is 0 (or 0.0), one-sided lighting is specified,
14218 and only the @var{front} material parameters are used in the lighting
14219 equation. Otherwise, two-sided lighting is specified. In this case,
14220 vertices of back-facing polygons are lighted using the @var{back}
14221 material parameters and have their normals reversed before the lighting
14222 equation is evaluated. Vertices of front-facing polygons are always
14223 lighted using the @var{front} material parameters, with no change to
14224 their normals. The initial value is 0.
14228 In RGBA mode, the lighted color of a vertex is the sum of the material
14229 emission intensity, the product of the material ambient reflectance and
14230 the lighting model full-scene ambient intensity, and the contribution of
14231 each enabled light source. Each light source contributes the sum of
14232 three terms: ambient, diffuse, and specular. The ambient light source
14233 contribution is the product of the material ambient reflectance and the
14234 light's ambient intensity. The diffuse light source contribution is the
14235 product of the material diffuse reflectance, the light's diffuse
14236 intensity, and the dot product of the vertex's normal with the
14237 normalized vector from the vertex to the light source. The specular
14238 light source contribution is the product of the material specular
14239 reflectance, the light's specular intensity, and the dot product of the
14240 normalized vertex-to-eye and vertex-to-light vectors, raised to the
14241 power of the shininess of the material. All three light source
14242 contributions are attenuated equally based on the distance from the
14243 vertex to the light source and on light source direction, spread
14244 exponent, and spread cutoff angle. All dot products are replaced with 0
14245 if they evaluate to a negative value.
14247 The alpha component of the resulting lighted color is set to the alpha
14248 value of the material diffuse reflectance.
14250 In color index mode, the value of the lighted index of a vertex ranges
14251 from the ambient to the specular values passed to @code{glMaterial}
14252 using @code{GL_COLOR_INDEXES}. Diffuse and specular coefficients,
14253 computed with a (.30, .59, .11) weighting of the lights' colors, the
14254 shininess of the material, and the same reflection and attenuation
14255 equations as in the RGBA case, determine how much above ambient the
14256 resulting index is.
14258 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
14261 @code{GL_INVALID_ENUM} is generated if @var{pname} is
14262 @code{GL_LIGHT_MODEL_COLOR_CONTROL} and @var{params} is not one of
14263 @code{GL_SINGLE_COLOR} or @code{GL_SEPARATE_SPECULAR_COLOR}.
14265 @code{GL_INVALID_OPERATION} is generated if @code{glLightModel} is
14266 executed between the execution of @code{glBegin} and the corresponding
14267 execution of @code{glEnd}.
14271 @deftypefun void glLightf light pname param
14272 @deftypefunx void glLighti light pname param
14273 @deftypefunx void glLightfv light pname params
14274 @deftypefunx void glLightiv light pname params
14275 Set light source parameters.
14279 Specifies a light. The number of lights depends on the implementation,
14280 but at least eight lights are supported. They are identified by symbolic
14281 names of the form @code{GL_LIGHT}@r{@var{i}}, where i ranges from 0 to
14282 the value of @code{GL_MAX_LIGHTS} - 1.
14285 Specifies a single-valued light source parameter for @var{light}.
14286 @code{GL_SPOT_EXPONENT}, @code{GL_SPOT_CUTOFF},
14287 @code{GL_CONSTANT_ATTENUATION}, @code{GL_LINEAR_ATTENUATION}, and
14288 @code{GL_QUADRATIC_ATTENUATION} are accepted.
14291 Specifies the value that parameter @var{pname} of light source
14292 @var{light} will be set to.
14296 @code{glLight} sets the values of individual light source parameters.
14297 @var{light} names the light and is a symbolic name of the form
14298 @code{GL_LIGHT}@r{@var{i}}, where i ranges from 0 to the value of
14299 @code{GL_MAX_LIGHTS} - 1. @var{pname} specifies one of ten light source
14300 parameters, again by symbolic name. @var{params} is either a single
14301 value or a pointer to an array that contains the new values.
14303 To enable and disable lighting calculation, call @code{glEnable} and
14304 @code{glDisable} with argument @code{GL_LIGHTING}. Lighting is initially
14305 disabled. When it is enabled, light sources that are enabled contribute
14306 to the lighting calculation. Light source @r{@var{i}} is enabled and
14307 disabled using @code{glEnable} and @code{glDisable} with argument
14308 @code{GL_LIGHT}@r{@var{i}}.
14310 The ten light parameters are as follows:
14313 @item @code{GL_AMBIENT}
14314 @var{params} contains four integer or floating-point values that specify
14315 the ambient RGBA intensity of the light. Integer values are mapped
14316 linearly such that the most positive representable value maps to 1.0,
14317 and the most negative representable value maps to @r{-1.0}.
14318 Floating-point values are mapped directly. Neither integer nor
14319 floating-point values are clamped. The initial ambient light intensity
14322 @item @code{GL_DIFFUSE}
14323 @var{params} contains four integer or floating-point values that specify
14324 the diffuse RGBA intensity of the light. Integer values are mapped
14325 linearly such that the most positive representable value maps to 1.0,
14326 and the most negative representable value maps to @r{-1.0}.
14327 Floating-point values are mapped directly. Neither integer nor
14328 floating-point values are clamped. The initial value for
14329 @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial value is
14332 @item @code{GL_SPECULAR}
14333 @var{params} contains four integer or floating-point values that specify
14334 the specular RGBA intensity of the light. Integer values are mapped
14335 linearly such that the most positive representable value maps to 1.0,
14336 and the most negative representable value maps to @r{-1.0}.
14337 Floating-point values are mapped directly. Neither integer nor
14338 floating-point values are clamped. The initial value for
14339 @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial value is
14342 @item @code{GL_POSITION}
14343 @var{params} contains four integer or floating-point values that specify
14344 the position of the light in homogeneous object coordinates. Both
14345 integer and floating-point values are mapped directly. Neither integer
14346 nor floating-point values are clamped.
14348 The position is transformed by the modelview matrix when @code{glLight}
14349 is called (just as if it were a point), and it is stored in eye
14350 coordinates. If the @r{@var{w}} component of the position is 0, the
14351 light is treated as a directional source. Diffuse and specular lighting
14352 calculations take the light's direction, but not its actual position,
14353 into account, and attenuation is disabled. Otherwise, diffuse and
14354 specular lighting calculations are based on the actual location of the
14355 light in eye coordinates, and attenuation is enabled. The initial
14356 position is (0, 0, 1, 0); thus, the initial light source is directional,
14357 parallel to, and in the direction of the @r{-@var{z}} axis.
14359 @item @code{GL_SPOT_DIRECTION}
14360 @var{params} contains three integer or floating-point values that
14361 specify the direction of the light in homogeneous object coordinates.
14362 Both integer and floating-point values are mapped directly. Neither
14363 integer nor floating-point values are clamped.
14365 The spot direction is transformed by the upper 3x3 of the modelview
14366 matrix when @code{glLight} is called, and it is stored in eye
14367 coordinates. It is significant only when @code{GL_SPOT_CUTOFF} is not
14368 180, which it is initially. The initial direction is @r{(0,0-1)}.
14370 @item @code{GL_SPOT_EXPONENT}
14371 @var{params} is a single integer or floating-point value that specifies
14372 the intensity distribution of the light. Integer and floating-point
14373 values are mapped directly. Only values in the range @r{[0,128]} are
14376 Effective light intensity is attenuated by the cosine of the angle
14377 between the direction of the light and the direction from the light to
14378 the vertex being lighted, raised to the power of the spot exponent.
14379 Thus, higher spot exponents result in a more focused light source,
14380 regardless of the spot cutoff angle (see @code{GL_SPOT_CUTOFF}, next
14381 paragraph). The initial spot exponent is 0, resulting in uniform light
14384 @item @code{GL_SPOT_CUTOFF}
14385 @var{params} is a single integer or floating-point value that specifies
14386 the maximum spread angle of a light source. Integer and floating-point
14387 values are mapped directly. Only values in the range @r{[0,90]} and the
14388 special value 180 are accepted. If the angle between the direction of
14389 the light and the direction from the light to the vertex being lighted
14390 is greater than the spot cutoff angle, the light is completely masked.
14391 Otherwise, its intensity is controlled by the spot exponent and the
14392 attenuation factors. The initial spot cutoff is 180, resulting in
14393 uniform light distribution.
14395 @item @code{GL_CONSTANT_ATTENUATION}
14396 @item @code{GL_LINEAR_ATTENUATION}
14397 @item @code{GL_QUADRATIC_ATTENUATION}
14398 @var{params} is a single integer or floating-point value that specifies
14399 one of the three light attenuation factors. Integer and floating-point
14400 values are mapped directly. Only nonnegative values are accepted. If the
14401 light is positional, rather than directional, its intensity is
14402 attenuated by the reciprocal of the sum of the constant factor, the
14403 linear factor times the distance between the light and the vertex being
14404 lighted, and the quadratic factor times the square of the same distance.
14405 The initial attenuation factors are (1, 0, 0), resulting in no
14410 @code{GL_INVALID_ENUM} is generated if either @var{light} or @var{pname}
14411 is not an accepted value.
14413 @code{GL_INVALID_VALUE} is generated if a spot exponent value is
14414 specified outside the range @r{[0,128]}, or if spot cutoff is specified
14415 outside the range @r{[0,90]} (except for the special value 180), or if a
14416 negative attenuation factor is specified.
14418 @code{GL_INVALID_OPERATION} is generated if @code{glLight} is executed
14419 between the execution of @code{glBegin} and the corresponding execution
14424 @deftypefun void glLineStipple factor pattern
14425 Specify the line stipple pattern.
14429 Specifies a multiplier for each bit in the line stipple pattern. If
14430 @var{factor} is 3, for example, each bit in the pattern is used three
14431 times before the next bit in the pattern is used. @var{factor} is
14432 clamped to the range [1, 256] and defaults to 1.
14434 @item @var{pattern}
14435 Specifies a 16-bit integer whose bit pattern determines which fragments
14436 of a line will be drawn when the line is rasterized. Bit zero is used
14437 first; the default pattern is all 1's.
14441 Line stippling masks out certain fragments produced by rasterization;
14442 those fragments will not be drawn. The masking is achieved by using
14443 three parameters: the 16-bit line stipple pattern @var{pattern}, the
14444 repeat count @var{factor}, and an integer stipple counter @r{@var{s}}.
14446 Counter @r{@var{s}} is reset to 0 whenever @code{glBegin} is called and
14447 before each line segment of a
14448 @code{glBegin}(@code{GL_LINES})/@code{glEnd} sequence is generated. It
14449 is incremented after each fragment of a unit width aliased line segment
14450 is generated or after each @r{@var{i}} fragments of an @r{@var{i}} width
14451 line segment are generated. The @r{@var{i}} fragments associated with
14452 count @r{@var{s}} are masked out if
14454 @var{pattern} bit @r{(@var{s}/@var{factor},)%16}
14456 is 0, otherwise these fragments are sent to the frame buffer. Bit zero
14457 of @var{pattern} is the least significant bit.
14459 Antialiased lines are treated as a sequence of @r{1×@var{width}}
14460 rectangles for purposes of stippling. Whether rectangle @r{@var{s}} is
14461 rasterized or not depends on the fragment rule described for aliased
14462 lines, counting rectangles rather than groups of fragments.
14464 To enable and disable line stippling, call @code{glEnable} and
14465 @code{glDisable} with argument @code{GL_LINE_STIPPLE}. When enabled, the
14466 line stipple pattern is applied as described above. When disabled, it is
14467 as if the pattern were all 1's. Initially, line stippling is disabled.
14469 @code{GL_INVALID_OPERATION} is generated if @code{glLineStipple} is
14470 executed between the execution of @code{glBegin} and the corresponding
14471 execution of @code{glEnd}.
14475 @deftypefun void glLineWidth width
14476 Specify the width of rasterized lines.
14480 Specifies the width of rasterized lines. The initial value is 1.
14484 @code{glLineWidth} specifies the rasterized width of both aliased and
14485 antialiased lines. Using a line width other than 1 has different
14486 effects, depending on whether line antialiasing is enabled. To enable
14487 and disable line antialiasing, call @code{glEnable} and @code{glDisable}
14488 with argument @code{GL_LINE_SMOOTH}. Line antialiasing is initially
14491 If line antialiasing is disabled, the actual width is determined by
14492 rounding the supplied width to the nearest integer. (If the rounding
14493 results in the value 0, it is as if the line width were 1.) If
14494 @r{∣Δ@var{x},∣>=∣Δ@var{y},∣}, @var{i} pixels are filled in each column
14495 that is rasterized, where @var{i} is the rounded value of @var{width}.
14496 Otherwise, @var{i} pixels are filled in each row that is rasterized.
14498 If antialiasing is enabled, line rasterization produces a fragment for
14499 each pixel square that intersects the region lying within the rectangle
14500 having width equal to the current line width, length equal to the actual
14501 length of the line, and centered on the mathematical line segment. The
14502 coverage value for each fragment is the window coordinate area of the
14503 intersection of the rectangular region with the corresponding pixel
14504 square. This value is saved and used in the final rasterization step.
14506 Not all widths can be supported when line antialiasing is enabled. If an
14507 unsupported width is requested, the nearest supported width is used.
14508 Only width 1 is guaranteed to be supported; others depend on the
14509 implementation. Likewise, there is a range for aliased line widths as
14510 well. To query the range of supported widths and the size difference
14511 between supported widths within the range, call @code{glGet} with
14512 arguments @code{GL_ALIASED_LINE_WIDTH_RANGE},
14513 @code{GL_SMOOTH_LINE_WIDTH_RANGE}, and
14514 @code{GL_SMOOTH_LINE_WIDTH_GRANULARITY}.
14516 @code{GL_INVALID_VALUE} is generated if @var{width} is less than or
14519 @code{GL_INVALID_OPERATION} is generated if @code{glLineWidth} is
14520 executed between the execution of @code{glBegin} and the corresponding
14521 execution of @code{glEnd}.
14525 @deftypefun void glLinkProgram program
14526 Links a program object.
14529 @item @var{program}
14530 Specifies the handle of the program object to be linked.
14534 @code{glLinkProgram} links the program object specified by
14535 @var{program}. If any shader objects of type @code{GL_VERTEX_SHADER} are
14536 attached to @var{program}, they will be used to create an executable
14537 that will run on the programmable vertex processor. If any shader
14538 objects of type @code{GL_FRAGMENT_SHADER} are attached to @var{program},
14539 they will be used to create an executable that will run on the
14540 programmable fragment processor.
14542 The status of the link operation will be stored as part of the program
14543 object's state. This value will be set to @code{GL_TRUE} if the program
14544 object was linked without errors and is ready for use, and
14545 @code{GL_FALSE} otherwise. It can be queried by calling
14546 @code{glGetProgram} with arguments @var{program} and
14547 @code{GL_LINK_STATUS}.
14549 As a result of a successful link operation, all active user-defined
14550 uniform variables belonging to @var{program} will be initialized to 0,
14551 and each of the program object's active uniform variables will be
14552 assigned a location that can be queried by calling
14553 @code{glGetUniformLocation}. Also, any active user-defined attribute
14554 variables that have not been bound to a generic vertex attribute index
14555 will be bound to one at this time.
14557 Linking of a program object can fail for a number of reasons as
14558 specified in the @var{OpenGL Shading Language Specification}. The
14559 following lists some of the conditions that will cause a link error.
14563 The number of active attribute variables supported by the implementation
14567 The storage limit for uniform variables has been exceeded.
14570 The number of active uniform variables supported by the implementation
14574 The @code{main} function is missing for the vertex shader or the
14578 A varying variable actually used in the fragment shader is not declared
14579 in the same way (or is not declared at all) in the vertex shader.
14582 A reference to a function or variable name is unresolved.
14585 A shared global is declared with two different types or two different
14589 One or more of the attached shader objects has not been successfully
14593 Binding a generic attribute matrix caused some rows of the matrix to
14594 fall outside the allowed maximum of @code{GL_MAX_VERTEX_ATTRIBS}.
14597 Not enough contiguous vertex attribute slots could be found to bind
14598 attribute matrices.
14602 When a program object has been successfully linked, the program object
14603 can be made part of current state by calling @code{glUseProgram}.
14604 Whether or not the link operation was successful, the program object's
14605 information log will be overwritten. The information log can be
14606 retrieved by calling @code{glGetProgramInfoLog}.
14608 @code{glLinkProgram} will also install the generated executables as part
14609 of the current rendering state if the link operation was successful and
14610 the specified program object is already currently in use as a result of
14611 a previous call to @code{glUseProgram}. If the program object currently
14612 in use is relinked unsuccessfully, its link status will be set to
14613 @code{GL_FALSE} , but the executables and associated state will remain
14614 part of the current state until a subsequent call to @code{glUseProgram}
14615 removes it from use. After it is removed from use, it cannot be made
14616 part of current state until it has been successfully relinked.
14618 If @var{program} contains shader objects of type @code{GL_VERTEX_SHADER}
14619 but does not contain shader objects of type @code{GL_FRAGMENT_SHADER},
14620 the vertex shader will be linked against the implicit interface for
14621 fixed functionality fragment processing. Similarly, if @var{program}
14622 contains shader objects of type @code{GL_FRAGMENT_SHADER} but it does
14623 not contain shader objects of type @code{GL_VERTEX_SHADER}, the fragment
14624 shader will be linked against the implicit interface for fixed
14625 functionality vertex processing.
14627 The program object's information log is updated and the program is
14628 generated at the time of the link operation. After the link operation,
14629 applications are free to modify attached shader objects, compile
14630 attached shader objects, detach shader objects, delete shader objects,
14631 and attach additional shader objects. None of these operations affects
14632 the information log or the program that is part of the program object.
14634 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
14635 generated by OpenGL.
14637 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
14640 @code{GL_INVALID_OPERATION} is generated if @code{glLinkProgram} is
14641 executed between the execution of @code{glBegin} and the corresponding
14642 execution of @code{glEnd}.
14646 @deftypefun void glListBase base
14647 Set the display-list base for .
14651 Specifies an integer offset that will be added to @code{glCallLists}
14652 offsets to generate display-list names. The initial value is 0.
14656 @code{glCallLists} specifies an array of offsets. Display-list names are
14657 generated by adding @var{base} to each offset. Names that reference
14658 valid display lists are executed; the others are ignored.
14660 @code{GL_INVALID_OPERATION} is generated if @code{glListBase} is
14661 executed between the execution of @code{glBegin} and the corresponding
14662 execution of @code{glEnd}.
14666 @deftypefun void glLoadIdentity
14667 Replace the current matrix with the identity matrix.
14669 @code{glLoadIdentity} replaces the current matrix with the identity
14670 matrix. It is semantically equivalent to calling @code{glLoadMatrix}
14671 with the identity matrix
14675 @r{((1 0 0 0), (0 1 0 0), (0 0 1 0), (0 0 0 1),,)}
14679 but in some cases it is more efficient.
14681 @code{GL_INVALID_OPERATION} is generated if @code{glLoadIdentity} is
14682 executed between the execution of @code{glBegin} and the corresponding
14683 execution of @code{glEnd}.
14687 @deftypefun void glLoadMatrixd m
14688 @deftypefunx void glLoadMatrixf m
14689 Replace the current matrix with the specified matrix.
14693 Specifies a pointer to 16 consecutive values, which are used as the
14694 elements of a @r{4×4} column-major matrix.
14698 @code{glLoadMatrix} replaces the current matrix with the one whose
14699 elements are specified by @var{m}. The current matrix is the projection
14700 matrix, modelview matrix, or texture matrix, depending on the current
14701 matrix mode (see @code{glMatrixMode}).
14703 The current matrix, M, defines a transformation of coordinates. For
14704 instance, assume M refers to the modelview matrix. If
14705 @r{@var{v}=(@var{v}[0,],@var{v}[1,]@var{v}[2,]@var{v}[3,])} is the
14706 set of object coordinates of a vertex, and @var{m} points to an array of
14707 @r{16} single- or double-precision floating-point values
14708 @r{@var{m}=@{@var{m}[0,],@var{m}[1,]@var{...}@var{m}[15,]@}}, then
14709 the modelview transformation @r{@var{M}(@var{v},)} does the following:
14711 @r{@var{M}(@var{v},)=((@var{m}[0,] @var{m}[4,] @var{m}[8,]
14712 @var{m}[12,]), (@var{m}[1,] @var{m}[5,] @var{m}[9,] @var{m}[13,]),
14713 (@var{m}[2,] @var{m}[6,] @var{m}[10,] @var{m}[14,]), (@var{m}[3,]
14714 @var{m}[7,] @var{m}[11,] @var{m}[15,]),)×((@var{v}[0,]),
14715 (@var{v}[1,]), (@var{v}[2,]), (@var{v}[3,]),)}
14719 Projection and texture transformations are similarly defined.
14721 @code{GL_INVALID_OPERATION} is generated if @code{glLoadMatrix} is
14722 executed between the execution of @code{glBegin} and the corresponding
14723 execution of @code{glEnd}.
14727 @deftypefun void glLoadName name
14728 Load a name onto the name stack.
14732 Specifies a name that will replace the top value on the name stack.
14736 The name stack is used during selection mode to allow sets of rendering
14737 commands to be uniquely identified. It consists of an ordered set of
14738 unsigned integers and is initially empty.
14740 @code{glLoadName} causes @var{name} to replace the value on the top of
14743 The name stack is always empty while the render mode is not
14744 @code{GL_SELECT}. Calls to @code{glLoadName} while the render mode is
14745 not @code{GL_SELECT} are ignored.
14747 @code{GL_INVALID_OPERATION} is generated if @code{glLoadName} is called
14748 while the name stack is empty.
14750 @code{GL_INVALID_OPERATION} is generated if @code{glLoadName} is
14751 executed between the execution of @code{glBegin} and the corresponding
14752 execution of @code{glEnd}.
14756 @deftypefun void glLoadTransposeMatrixd m
14757 @deftypefunx void glLoadTransposeMatrixf m
14758 Replace the current matrix with the specified row-major ordered matrix.
14762 Specifies a pointer to 16 consecutive values, which are used as the
14763 elements of a @r{4×4} row-major matrix.
14767 @code{glLoadTransposeMatrix} replaces the current matrix with the one
14768 whose elements are specified by @var{m}. The current matrix is the
14769 projection matrix, modelview matrix, or texture matrix, depending on the
14770 current matrix mode (see @code{glMatrixMode}).
14772 The current matrix, M, defines a transformation of coordinates. For
14773 instance, assume M refers to the modelview matrix. If
14774 @r{@var{v}=(@var{v}[0,],@var{v}[1,]@var{v}[2,]@var{v}[3,])} is the
14775 set of object coordinates of a vertex, and @var{m} points to an array of
14776 @r{16} single- or double-precision floating-point values
14777 @r{@var{m}=@{@var{m}[0,],@var{m}[1,]@var{...}@var{m}[15,]@}}, then
14778 the modelview transformation @r{@var{M}(@var{v},)} does the following:
14780 @r{@var{M}(@var{v},)=((@var{m}[0,] @var{m}[1,] @var{m}[2,]
14781 @var{m}[3,]), (@var{m}[4,] @var{m}[5,] @var{m}[6,] @var{m}[7,]),
14782 (@var{m}[8,] @var{m}[9,] @var{m}[10,] @var{m}[11,]), (@var{m}[12,]
14783 @var{m}[13,] @var{m}[14,] @var{m}[15,]),)×((@var{v}[0,]),
14784 (@var{v}[1,]), (@var{v}[2,]), (@var{v}[3,]),)}
14788 Projection and texture transformations are similarly defined.
14790 Calling @code{glLoadTransposeMatrix} with matrix @r{@var{M}} is
14791 identical in operation to @code{glLoadMatrix} with @r{@var{M}^@var{T}},
14792 where @r{@var{T}} represents the transpose.
14794 @code{GL_INVALID_OPERATION} is generated if @code{glLoadTransposeMatrix}
14795 is executed between the execution of @code{glBegin} and the
14796 corresponding execution of @code{glEnd}.
14800 @deftypefun void glLogicOp opcode
14801 Specify a logical pixel operation for color index rendering.
14805 Specifies a symbolic constant that selects a logical operation. The
14806 following symbols are accepted: @code{GL_CLEAR}, @code{GL_SET},
14807 @code{GL_COPY}, @code{GL_COPY_INVERTED}, @code{GL_NOOP},
14808 @code{GL_INVERT}, @code{GL_AND}, @code{GL_NAND}, @code{GL_OR},
14809 @code{GL_NOR}, @code{GL_XOR}, @code{GL_EQUIV}, @code{GL_AND_REVERSE},
14810 @code{GL_AND_INVERTED}, @code{GL_OR_REVERSE}, and @code{GL_OR_INVERTED}.
14811 The initial value is @code{GL_COPY}.
14815 @code{glLogicOp} specifies a logical operation that, when enabled, is
14816 applied between the incoming color index or RGBA color and the color
14817 index or RGBA color at the corresponding location in the frame buffer.
14818 To enable or disable the logical operation, call @code{glEnable} and
14819 @code{glDisable} using the symbolic constant @code{GL_COLOR_LOGIC_OP}
14820 for RGBA mode or @code{GL_INDEX_LOGIC_OP} for color index mode. The
14821 initial value is disabled for both operations.
14826 @item @strong{Opcode}
14827 @strong{Resulting Operation}
14829 @item @code{GL_CLEAR}
14832 @item @code{GL_SET}
14835 @item @code{GL_COPY}
14838 @item @code{GL_COPY_INVERTED}
14841 @item @code{GL_NOOP}
14844 @item @code{GL_INVERT}
14847 @item @code{GL_AND}
14850 @item @code{GL_NAND}
14856 @item @code{GL_NOR}
14859 @item @code{GL_XOR}
14862 @item @code{GL_EQUIV}
14865 @item @code{GL_AND_REVERSE}
14868 @item @code{GL_AND_INVERTED}
14871 @item @code{GL_OR_REVERSE}
14874 @item @code{GL_OR_INVERTED}
14879 @var{opcode} is a symbolic constant chosen from the list above. In the
14880 explanation of the logical operations, @var{s} represents the incoming
14881 color index and @var{d} represents the index in the frame buffer.
14882 Standard C-language operators are used. As these bitwise operators
14883 suggest, the logical operation is applied independently to each bit pair
14884 of the source and destination indices or colors.
14886 @code{GL_INVALID_ENUM} is generated if @var{opcode} is not an accepted
14889 @code{GL_INVALID_OPERATION} is generated if @code{glLogicOp} is executed
14890 between the execution of @code{glBegin} and the corresponding execution
14895 @deftypefun void glMap1f target u1 u2 stride order points
14896 @deftypefunx void glMap1d target u1 u2 stride order points
14897 Define a one-dimensional evaluator.
14901 Specifies the kind of values that are generated by the evaluator.
14902 Symbolic constants @code{GL_MAP1_VERTEX_3}, @code{GL_MAP1_VERTEX_4},
14903 @code{GL_MAP1_INDEX}, @code{GL_MAP1_COLOR_4}, @code{GL_MAP1_NORMAL},
14904 @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2},
14905 @code{GL_MAP1_TEXTURE_COORD_3}, and @code{GL_MAP1_TEXTURE_COORD_4} are
14910 Specify a linear mapping of @r{@var{u}}, as presented to
14911 @code{glEvalCoord1}, to @r{@var{u}^}, the variable that is evaluated by
14912 the equations specified by this command.
14915 Specifies the number of floats or doubles between the beginning of one
14916 control point and the beginning of the next one in the data structure
14917 referenced in @var{points}. This allows control points to be embedded in
14918 arbitrary data structures. The only constraint is that the values for a
14919 particular control point must occupy contiguous memory locations.
14922 Specifies the number of control points. Must be positive.
14925 Specifies a pointer to the array of control points.
14929 Evaluators provide a way to use polynomial or rational polynomial
14930 mapping to produce vertices, normals, texture coordinates, and colors.
14931 The values produced by an evaluator are sent to further stages of GL
14932 processing just as if they had been presented using @code{glVertex},
14933 @code{glNormal}, @code{glTexCoord}, and @code{glColor} commands, except
14934 that the generated values do not update the current normal, texture
14935 coordinates, or color.
14937 All polynomial or rational polynomial splines of any degree (up to the
14938 maximum degree supported by the GL implementation) can be described
14939 using evaluators. These include almost all splines used in computer
14940 graphics: B-splines, Bezier curves, Hermite splines, and so on.
14942 Evaluators define curves based on Bernstein polynomials. Define
14943 @r{@var{p}(@var{u}^,)} as
14945 @r{@var{p}(@var{u}^,)=Σ@var{i}=0@var{n}@var{B}_@var{i},^@var{n}(@var{u}^,)@var{R}_@var{i}}
14949 where @r{@var{R}_@var{i}} is a control point and
14950 @r{@var{B}_@var{i},^@var{n}(@var{u}^,)} is the @r{@var{i}}th Bernstein
14951 polynomial of degree @r{@var{n}} (@var{order} = @r{@var{n}+1}):
14953 @r{@var{B}_@var{i},^@var{n}(@var{u}^,)=((@var{n}),
14954 (@var{i}),,)@var{u}^,^@var{i}(1-@var{u}^,)^@var{n}-@var{i},,}
14958 @r{0^0==1} and @r{((@var{n}), (0),,)==1}
14960 @code{glMap1} is used to define the basis and to specify what kind of
14961 values are produced. Once defined, a map can be enabled and disabled by
14962 calling @code{glEnable} and @code{glDisable} with the map name, one of
14963 the nine predefined values for @var{target} described below.
14964 @code{glEvalCoord1} evaluates the one-dimensional maps that are enabled.
14965 When @code{glEvalCoord1} presents a value @r{@var{u}}, the Bernstein
14966 functions are evaluated using @r{@var{u}^}, where
14967 @r{@var{u}^=@var{u}-@var{u1},/@var{u2}-@var{u1},}
14969 @var{target} is a symbolic constant that indicates what kind of control
14970 points are provided in @var{points}, and what output is generated when
14971 the map is evaluated. It can assume one of nine predefined values:
14974 @item @code{GL_MAP1_VERTEX_3}
14975 Each control point is three floating-point values representing
14976 @r{@var{x}}, @r{@var{y}}, and @r{@var{z}}. Internal @code{glVertex3}
14977 commands are generated when the map is evaluated.
14979 @item @code{GL_MAP1_VERTEX_4}
14980 Each control point is four floating-point values representing
14981 @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}. Internal
14982 @code{glVertex4} commands are generated when the map is evaluated.
14984 @item @code{GL_MAP1_INDEX}
14985 Each control point is a single floating-point value representing a color
14986 index. Internal @code{glIndex} commands are generated when the map is
14987 evaluated but the current index is not updated with the value of these
14988 @code{glIndex} commands.
14990 @item @code{GL_MAP1_COLOR_4}
14991 Each control point is four floating-point values representing red,
14992 green, blue, and alpha. Internal @code{glColor4} commands are generated
14993 when the map is evaluated but the current color is not updated with the
14994 value of these @code{glColor4} commands.
14996 @item @code{GL_MAP1_NORMAL}
14997 Each control point is three floating-point values representing the
14998 @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} components of a normal vector.
14999 Internal @code{glNormal} commands are generated when the map is
15000 evaluated but the current normal is not updated with the value of these
15001 @code{glNormal} commands.
15003 @item @code{GL_MAP1_TEXTURE_COORD_1}
15004 Each control point is a single floating-point value representing the
15005 @r{@var{s}} texture coordinate. Internal @code{glTexCoord1} commands are
15006 generated when the map is evaluated but the current texture coordinates
15007 are not updated with the value of these @code{glTexCoord} commands.
15009 @item @code{GL_MAP1_TEXTURE_COORD_2}
15010 Each control point is two floating-point values representing the
15011 @r{@var{s}} and @r{@var{t}} texture coordinates. Internal
15012 @code{glTexCoord2} commands are generated when the map is evaluated but
15013 the current texture coordinates are not updated with the value of these
15014 @code{glTexCoord} commands.
15016 @item @code{GL_MAP1_TEXTURE_COORD_3}
15017 Each control point is three floating-point values representing the
15018 @r{@var{s}}, @r{@var{t}}, and @r{@var{r}} texture coordinates. Internal
15019 @code{glTexCoord3} commands are generated when the map is evaluated but
15020 the current texture coordinates are not updated with the value of these
15021 @code{glTexCoord} commands.
15023 @item @code{GL_MAP1_TEXTURE_COORD_4}
15024 Each control point is four floating-point values representing the
15025 @r{@var{s}}, @r{@var{t}}, @r{@var{r}}, and @r{@var{q}} texture
15026 coordinates. Internal @code{glTexCoord4} commands are generated when the
15027 map is evaluated but the current texture coordinates are not updated
15028 with the value of these @code{glTexCoord} commands.
15032 @var{stride}, @var{order}, and @var{points} define the array addressing
15033 for accessing the control points. @var{points} is the location of the
15034 first control point, which occupies one, two, three, or four contiguous
15035 memory locations, depending on which map is being defined. @var{order}
15036 is the number of control points in the array. @var{stride} specifies how
15037 many float or double locations to advance the internal memory pointer to
15038 reach the next control point.
15040 @code{GL_INVALID_ENUM} is generated if @var{target} is not an accepted
15043 @code{GL_INVALID_VALUE} is generated if @var{u1} is equal to @var{u2}.
15045 @code{GL_INVALID_VALUE} is generated if @var{stride} is less than the
15046 number of values in a control point.
15048 @code{GL_INVALID_VALUE} is generated if @var{order} is less than 1 or
15049 greater than the return value of @code{GL_MAX_EVAL_ORDER}.
15051 @code{GL_INVALID_OPERATION} is generated if @code{glMap1} is executed
15052 between the execution of @code{glBegin} and the corresponding execution
15055 @code{GL_INVALID_OPERATION} is generated if @code{glMap1} is called and
15056 the value of @code{GL_ACTIVE_TEXTURE} is not @code{GL_TEXTURE0}.
15060 @deftypefun void glMap2f target u1 u2 ustride uorder v1 v2 vstride vorder points
15061 @deftypefunx void glMap2d target u1 u2 ustride uorder v1 v2 vstride vorder points
15062 Define a two-dimensional evaluator.
15066 Specifies the kind of values that are generated by the evaluator.
15067 Symbolic constants @code{GL_MAP2_VERTEX_3}, @code{GL_MAP2_VERTEX_4},
15068 @code{GL_MAP2_INDEX}, @code{GL_MAP2_COLOR_4}, @code{GL_MAP2_NORMAL},
15069 @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2},
15070 @code{GL_MAP2_TEXTURE_COORD_3}, and @code{GL_MAP2_TEXTURE_COORD_4} are
15075 Specify a linear mapping of @r{@var{u}}, as presented to
15076 @code{glEvalCoord2}, to @r{@var{u}^}, one of the two variables that are
15077 evaluated by the equations specified by this command. Initially,
15078 @var{u1} is 0 and @var{u2} is 1.
15080 @item @var{ustride}
15081 Specifies the number of floats or doubles between the beginning of
15082 control point @r{@var{R}_@var{ij}} and the beginning of control point
15083 @r{@var{R}_(@var{i}+1,)@var{j},}, where @r{@var{i}} and @r{@var{j}} are
15084 the @r{@var{u}} and @r{@var{v}} control point indices, respectively.
15085 This allows control points to be embedded in arbitrary data structures.
15086 The only constraint is that the values for a particular control point
15087 must occupy contiguous memory locations. The initial value of
15088 @var{ustride} is 0.
15091 Specifies the dimension of the control point array in the @r{@var{u}}
15092 axis. Must be positive. The initial value is 1.
15096 Specify a linear mapping of @r{@var{v}}, as presented to
15097 @code{glEvalCoord2}, to @r{@var{v}^}, one of the two variables that are
15098 evaluated by the equations specified by this command. Initially,
15099 @var{v1} is 0 and @var{v2} is 1.
15101 @item @var{vstride}
15102 Specifies the number of floats or doubles between the beginning of
15103 control point @r{@var{R}_@var{ij}} and the beginning of control point
15104 @r{@var{R}_@var{i}(@var{j}+1,),}, where @r{@var{i}} and @r{@var{j}} are
15105 the @r{@var{u}} and @r{@var{v}} control point indices, respectively.
15106 This allows control points to be embedded in arbitrary data structures.
15107 The only constraint is that the values for a particular control point
15108 must occupy contiguous memory locations. The initial value of
15109 @var{vstride} is 0.
15112 Specifies the dimension of the control point array in the @r{@var{v}}
15113 axis. Must be positive. The initial value is 1.
15116 Specifies a pointer to the array of control points.
15120 Evaluators provide a way to use polynomial or rational polynomial
15121 mapping to produce vertices, normals, texture coordinates, and colors.
15122 The values produced by an evaluator are sent on to further stages of GL
15123 processing just as if they had been presented using @code{glVertex},
15124 @code{glNormal}, @code{glTexCoord}, and @code{glColor} commands, except
15125 that the generated values do not update the current normal, texture
15126 coordinates, or color.
15128 All polynomial or rational polynomial splines of any degree (up to the
15129 maximum degree supported by the GL implementation) can be described
15130 using evaluators. These include almost all surfaces used in computer
15131 graphics, including B-spline surfaces, NURBS surfaces, Bezier surfaces,
15134 Evaluators define surfaces based on bivariate Bernstein polynomials.
15135 Define @r{@var{p}(@var{u}^,@var{v}^)} as
15137 @r{@var{p}(@var{u}^,@var{v}^)=Σ@var{i}=0@var{n}Σ@var{j}=0@var{m}@var{B}_@var{i},^@var{n}(@var{u}^,)@var{B}_@var{j},^@var{m}(@var{v}^,)@var{R}_@var{ij}}
15141 where @r{@var{R}_@var{ij}} is a control point,
15142 @r{@var{B}_@var{i},^@var{n}(@var{u}^,)} is the @r{@var{i}}th Bernstein
15143 polynomial of degree @r{@var{n}} (@var{uorder} = @r{@var{n}+1})
15145 @r{@var{B}_@var{i},^@var{n}(@var{u}^,)=((@var{n}),
15146 (@var{i}),,)@var{u}^,^@var{i}(1-@var{u}^,)^@var{n}-@var{i},,}
15148 and @r{@var{B}_@var{j},^@var{m}(@var{v}^,)} is the @r{@var{j}}th
15149 Bernstein polynomial of degree @r{@var{m}} (@var{vorder} =
15152 @r{@var{B}_@var{j},^@var{m}(@var{v}^,)=((@var{m}),
15153 (@var{j}),,)@var{v}^,^@var{j}(1-@var{v}^,)^@var{m}-@var{j},,}
15155 Recall that @r{0^0==1} and @r{((@var{n}), (0),,)==1}
15157 @code{glMap2} is used to define the basis and to specify what kind of
15158 values are produced. Once defined, a map can be enabled and disabled by
15159 calling @code{glEnable} and @code{glDisable} with the map name, one of
15160 the nine predefined values for @var{target}, described below. When
15161 @code{glEvalCoord2} presents values @r{@var{u}} and @r{@var{v}}, the
15162 bivariate Bernstein polynomials are evaluated using @r{@var{u}^} and
15163 @r{@var{v}^}, where
15165 @r{@var{u}^=@var{u}-@var{u1},/@var{u2}-@var{u1},}
15167 @r{@var{v}^=@var{v}-@var{v1},/@var{v2}-@var{v1},}
15169 @var{target} is a symbolic constant that indicates what kind of control
15170 points are provided in @var{points}, and what output is generated when
15171 the map is evaluated. It can assume one of nine predefined values:
15174 @item @code{GL_MAP2_VERTEX_3}
15175 Each control point is three floating-point values representing
15176 @r{@var{x}}, @r{@var{y}}, and @r{@var{z}}. Internal @code{glVertex3}
15177 commands are generated when the map is evaluated.
15179 @item @code{GL_MAP2_VERTEX_4}
15180 Each control point is four floating-point values representing
15181 @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}. Internal
15182 @code{glVertex4} commands are generated when the map is evaluated.
15184 @item @code{GL_MAP2_INDEX}
15185 Each control point is a single floating-point value representing a color
15186 index. Internal @code{glIndex} commands are generated when the map is
15187 evaluated but the current index is not updated with the value of these
15188 @code{glIndex} commands.
15190 @item @code{GL_MAP2_COLOR_4}
15191 Each control point is four floating-point values representing red,
15192 green, blue, and alpha. Internal @code{glColor4} commands are generated
15193 when the map is evaluated but the current color is not updated with the
15194 value of these @code{glColor4} commands.
15196 @item @code{GL_MAP2_NORMAL}
15197 Each control point is three floating-point values representing the
15198 @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} components of a normal vector.
15199 Internal @code{glNormal} commands are generated when the map is
15200 evaluated but the current normal is not updated with the value of these
15201 @code{glNormal} commands.
15203 @item @code{GL_MAP2_TEXTURE_COORD_1}
15204 Each control point is a single floating-point value representing the
15205 @r{@var{s}} texture coordinate. Internal @code{glTexCoord1} commands are
15206 generated when the map is evaluated but the current texture coordinates
15207 are not updated with the value of these @code{glTexCoord} commands.
15209 @item @code{GL_MAP2_TEXTURE_COORD_2}
15210 Each control point is two floating-point values representing the
15211 @r{@var{s}} and @r{@var{t}} texture coordinates. Internal
15212 @code{glTexCoord2} commands are generated when the map is evaluated but
15213 the current texture coordinates are not updated with the value of these
15214 @code{glTexCoord} commands.
15216 @item @code{GL_MAP2_TEXTURE_COORD_3}
15217 Each control point is three floating-point values representing the
15218 @r{@var{s}}, @r{@var{t}}, and @r{@var{r}} texture coordinates. Internal
15219 @code{glTexCoord3} commands are generated when the map is evaluated but
15220 the current texture coordinates are not updated with the value of these
15221 @code{glTexCoord} commands.
15223 @item @code{GL_MAP2_TEXTURE_COORD_4}
15224 Each control point is four floating-point values representing the
15225 @r{@var{s}}, @r{@var{t}}, @r{@var{r}}, and @r{@var{q}} texture
15226 coordinates. Internal @code{glTexCoord4} commands are generated when the
15227 map is evaluated but the current texture coordinates are not updated
15228 with the value of these @code{glTexCoord} commands.
15232 @var{ustride}, @var{uorder}, @var{vstride}, @var{vorder}, and
15233 @var{points} define the array addressing for accessing the control
15234 points. @var{points} is the location of the first control point, which
15235 occupies one, two, three, or four contiguous memory locations, depending
15236 on which map is being defined. There are @r{@var{uorder}×@var{vorder}}
15237 control points in the array. @var{ustride} specifies how many float or
15238 double locations are skipped to advance the internal memory pointer from
15239 control point @r{@var{R}_@var{i}@var{j},} to control point
15240 @r{@var{R}_(@var{i}+1,)@var{j},}. @var{vstride} specifies how many
15241 float or double locations are skipped to advance the internal memory
15242 pointer from control point @r{@var{R}_@var{i}@var{j},} to control point
15243 @r{@var{R}_@var{i}(@var{j}+1,),}.
15245 @code{GL_INVALID_ENUM} is generated if @var{target} is not an accepted
15248 @code{GL_INVALID_VALUE} is generated if @var{u1} is equal to @var{u2},
15249 or if @var{v1} is equal to @var{v2}.
15251 @code{GL_INVALID_VALUE} is generated if either @var{ustride} or
15252 @var{vstride} is less than the number of values in a control point.
15254 @code{GL_INVALID_VALUE} is generated if either @var{uorder} or
15255 @var{vorder} is less than 1 or greater than the return value of
15256 @code{GL_MAX_EVAL_ORDER}.
15258 @code{GL_INVALID_OPERATION} is generated if @code{glMap2} is executed
15259 between the execution of @code{glBegin} and the corresponding execution
15262 @code{GL_INVALID_OPERATION} is generated if @code{glMap2} is called and
15263 the value of @code{GL_ACTIVE_TEXTURE} is not @code{GL_TEXTURE0}.
15267 @deftypefun void-* glMapBuffer target access
15268 @deftypefunx GLboolean glUnmapBuffer target
15269 Map a buffer object's data store.
15273 Specifies the target buffer object being mapped. The symbolic constant
15274 must be @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
15275 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
15278 Specifies the access policy, indicating whether it will be possible to
15279 read from, write to, or both read from and write to the buffer object's
15280 mapped data store. The symbolic constant must be @code{GL_READ_ONLY},
15281 @code{GL_WRITE_ONLY}, or @code{GL_READ_WRITE}.
15285 @code{glMapBuffer} maps to the client's address space the entire data
15286 store of the buffer object currently bound to @var{target}. The data can
15287 then be directly read and/or written relative to the returned pointer,
15288 depending on the specified @var{access} policy. If the GL is unable to
15289 map the buffer object's data store, @code{glMapBuffer} generates an
15290 error and returns @code{NULL}. This may occur for system-specific
15291 reasons, such as low virtual memory availability.
15293 If a mapped data store is accessed in a way inconsistent with the
15294 specified @var{access} policy, no error is generated, but performance
15295 may be negatively impacted and system errors, including program
15296 termination, may result. Unlike the @var{usage} parameter of
15297 @code{glBufferData}, @var{access} is not a hint, and does in fact
15298 constrain the usage of the mapped data store on some GL implementations.
15299 In order to achieve the highest performance available, a buffer object's
15300 data store should be used in ways consistent with both its specified
15301 @var{usage} and @var{access} parameters.
15303 A mapped data store must be unmapped with @code{glUnmapBuffer} before
15304 its buffer object is used. Otherwise an error will be generated by any
15305 GL command that attempts to dereference the buffer object's data store.
15306 When a data store is unmapped, the pointer to its data store becomes
15307 invalid. @code{glUnmapBuffer} returns @code{GL_TRUE} unless the data
15308 store contents have become corrupt during the time the data store was
15309 mapped. This can occur for system-specific reasons that affect the
15310 availability of graphics memory, such as screen mode changes. In such
15311 situations, @code{GL_FALSE} is returned and the data store contents are
15312 undefined. An application must detect this rare condition and
15313 reinitialize the data store.
15315 A buffer object's mapped data store is automatically unmapped when the
15316 buffer object is deleted or its data store is recreated with
15317 @code{glBufferData}.
15319 @code{GL_INVALID_ENUM} is generated if @var{target} is not
15320 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
15321 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
15323 @code{GL_INVALID_ENUM} is generated if @var{access} is not
15324 @code{GL_READ_ONLY}, @code{GL_WRITE_ONLY}, or @code{GL_READ_WRITE}.
15326 @code{GL_OUT_OF_MEMORY} is generated when @code{glMapBuffer} is executed
15327 if the GL is unable to map the buffer object's data store. This may
15328 occur for a variety of system-specific reasons, such as the absence of
15329 sufficient remaining virtual memory.
15331 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
15332 name 0 is bound to @var{target}.
15334 @code{GL_INVALID_OPERATION} is generated if @code{glMapBuffer} is
15335 executed for a buffer object whose data store is already mapped.
15337 @code{GL_INVALID_OPERATION} is generated if @code{glUnmapBuffer} is
15338 executed for a buffer object whose data store is not currently mapped.
15340 @code{GL_INVALID_OPERATION} is generated if @code{glMapBuffer} or
15341 @code{glUnmapBuffer} is executed between the execution of @code{glBegin}
15342 and the corresponding execution of @code{glEnd}.
15346 @deftypefun void glMapGrid1d un u1 u2
15347 @deftypefunx void glMapGrid1f un u1 u2
15348 @deftypefunx void glMapGrid2d un u1 u2 vn v1 v2
15349 @deftypefunx void glMapGrid2f un u1 u2 vn v1 v2
15350 Define a one- or two-dimensional mesh.
15354 Specifies the number of partitions in the grid range interval [@var{u1},
15355 @var{u2}]. Must be positive.
15359 Specify the mappings for integer grid domain values @r{@var{i}=0} and
15360 @r{@var{i}=@var{un}}.
15363 Specifies the number of partitions in the grid range interval [@var{v1},
15364 @var{v2}] (@code{glMapGrid2} only).
15368 Specify the mappings for integer grid domain values @r{@var{j}=0} and
15369 @r{@var{j}=@var{vn}} (@code{glMapGrid2} only).
15373 @code{glMapGrid} and @code{glEvalMesh} are used together to efficiently
15374 generate and evaluate a series of evenly-spaced map domain values.
15375 @code{glEvalMesh} steps through the integer domain of a one- or
15376 two-dimensional grid, whose range is the domain of the evaluation maps
15377 specified by @code{glMap1} and @code{glMap2}.
15379 @code{glMapGrid1} and @code{glMapGrid2} specify the linear grid mappings
15380 between the @r{@var{i}} (or @r{@var{i}} and @r{@var{j}}) integer grid
15381 coordinates, to the @r{@var{u}} (or @r{@var{u}} and @r{@var{v}})
15382 floating-point evaluation map coordinates. See @code{glMap1} and
15383 @code{glMap2} for details of how @r{@var{u}} and @r{@var{v}} coordinates
15386 @code{glMapGrid1} specifies a single linear mapping such that integer
15387 grid coordinate 0 maps exactly to @var{u1}, and integer grid coordinate
15388 @var{un} maps exactly to @var{u2}. All other integer grid coordinates
15389 @r{@var{i}} are mapped so that
15391 @r{@var{u}=@var{i}(@var{u2}-@var{u1},)/@var{un}+@var{u1}}
15393 @code{glMapGrid2} specifies two such linear mappings. One maps integer
15394 grid coordinate @r{@var{i}=0} exactly to @var{u1}, and integer grid
15395 coordinate @r{@var{i}=@var{un}} exactly to @var{u2}. The other maps
15396 integer grid coordinate @r{@var{j}=0} exactly to @var{v1}, and integer
15397 grid coordinate @r{@var{j}=@var{vn}} exactly to @var{v2}. Other integer
15398 grid coordinates @r{@var{i}} and @r{@var{j}} are mapped such that
15400 @r{@var{u}=@var{i}(@var{u2}-@var{u1},)/@var{un}+@var{u1}}
15402 @r{@var{v}=@var{j}(@var{v2}-@var{v1},)/@var{vn}+@var{v1}}
15404 The mappings specified by @code{glMapGrid} are used identically by
15405 @code{glEvalMesh} and @code{glEvalPoint}.
15407 @code{GL_INVALID_VALUE} is generated if either @var{un} or @var{vn} is
15410 @code{GL_INVALID_OPERATION} is generated if @code{glMapGrid} is executed
15411 between the execution of @code{glBegin} and the corresponding execution
15416 @deftypefun void glMaterialf face pname param
15417 @deftypefunx void glMateriali face pname param
15418 @deftypefunx void glMaterialfv face pname params
15419 @deftypefunx void glMaterialiv face pname params
15420 Specify material parameters for the lighting model.
15424 Specifies which face or faces are being updated. Must be one of
15425 @code{GL_FRONT}, @code{GL_BACK}, or @code{GL_FRONT_AND_BACK}.
15428 Specifies the single-valued material parameter of the face or faces that
15429 is being updated. Must be @code{GL_SHININESS}.
15432 Specifies the value that parameter @code{GL_SHININESS} will be set to.
15436 @code{glMaterial} assigns values to material parameters. There are two
15437 matched sets of material parameters. One, the @var{front-facing} set, is
15438 used to shade points, lines, bitmaps, and all polygons (when two-sided
15439 lighting is disabled), or just front-facing polygons (when two-sided
15440 lighting is enabled). The other set, @var{back-facing}, is used to shade
15441 back-facing polygons only when two-sided lighting is enabled. Refer to
15442 the @code{glLightModel} reference page for details concerning one- and
15443 two-sided lighting calculations.
15445 @code{glMaterial} takes three arguments. The first, @var{face},
15446 specifies whether the @code{GL_FRONT} materials, the @code{GL_BACK}
15447 materials, or both @code{GL_FRONT_AND_BACK} materials will be modified.
15448 The second, @var{pname}, specifies which of several parameters in one or
15449 both sets will be modified. The third, @var{params}, specifies what
15450 value or values will be assigned to the specified parameter.
15452 Material parameters are used in the lighting equation that is optionally
15453 applied to each vertex. The equation is discussed in the
15454 @code{glLightModel} reference page. The parameters that can be specified
15455 using @code{glMaterial}, and their interpretations by the lighting
15456 equation, are as follows:
15459 @item @code{GL_AMBIENT}
15460 @var{params} contains four integer or floating-point values that specify
15461 the ambient RGBA reflectance of the material. Integer values are mapped
15462 linearly such that the most positive representable value maps to 1.0,
15463 and the most negative representable value maps to @r{-1.0}.
15464 Floating-point values are mapped directly. Neither integer nor
15465 floating-point values are clamped. The initial ambient reflectance for
15466 both front- and back-facing materials is (0.2, 0.2, 0.2, 1.0).
15468 @item @code{GL_DIFFUSE}
15469 @var{params} contains four integer or floating-point values that specify
15470 the diffuse RGBA reflectance of the material. Integer values are mapped
15471 linearly such that the most positive representable value maps to 1.0,
15472 and the most negative representable value maps to @r{-1.0}.
15473 Floating-point values are mapped directly. Neither integer nor
15474 floating-point values are clamped. The initial diffuse reflectance for
15475 both front- and back-facing materials is (0.8, 0.8, 0.8, 1.0).
15477 @item @code{GL_SPECULAR}
15478 @var{params} contains four integer or floating-point values that specify
15479 the specular RGBA reflectance of the material. Integer values are mapped
15480 linearly such that the most positive representable value maps to 1.0,
15481 and the most negative representable value maps to @r{-1.0}.
15482 Floating-point values are mapped directly. Neither integer nor
15483 floating-point values are clamped. The initial specular reflectance for
15484 both front- and back-facing materials is (0, 0, 0, 1).
15486 @item @code{GL_EMISSION}
15487 @var{params} contains four integer or floating-point values that specify
15488 the RGBA emitted light intensity of the material. Integer values are
15489 mapped linearly such that the most positive representable value maps to
15490 1.0, and the most negative representable value maps to @r{-1.0}.
15491 Floating-point values are mapped directly. Neither integer nor
15492 floating-point values are clamped. The initial emission intensity for
15493 both front- and back-facing materials is (0, 0, 0, 1).
15495 @item @code{GL_SHININESS}
15496 @var{params} is a single integer or floating-point value that specifies
15497 the RGBA specular exponent of the material. Integer and floating-point
15498 values are mapped directly. Only values in the range @r{[0,128]} are
15499 accepted. The initial specular exponent for both front- and back-facing
15502 @item @code{GL_AMBIENT_AND_DIFFUSE}
15503 Equivalent to calling @code{glMaterial} twice with the same parameter
15504 values, once with @code{GL_AMBIENT} and once with @code{GL_DIFFUSE}.
15506 @item @code{GL_COLOR_INDEXES}
15507 @var{params} contains three integer or floating-point values specifying
15508 the color indices for ambient, diffuse, and specular lighting. These
15509 three values, and @code{GL_SHININESS}, are the only material values used
15510 by the color index mode lighting equation. Refer to the
15511 @code{glLightModel} reference page for a discussion of color index
15516 @code{GL_INVALID_ENUM} is generated if either @var{face} or @var{pname}
15517 is not an accepted value.
15519 @code{GL_INVALID_VALUE} is generated if a specular exponent outside the
15520 range @r{[0,128]} is specified.
15524 @deftypefun void glMatrixMode mode
15525 Specify which matrix is the current matrix.
15529 Specifies which matrix stack is the target for subsequent matrix
15530 operations. Three values are accepted: @code{GL_MODELVIEW},
15531 @code{GL_PROJECTION}, and @code{GL_TEXTURE}. The initial value is
15532 @code{GL_MODELVIEW}. Additionally, if the @code{ARB_imaging} extension
15533 is supported, @code{GL_COLOR} is also accepted.
15537 @code{glMatrixMode} sets the current matrix mode. @var{mode} can assume
15538 one of four values:
15541 @item @code{GL_MODELVIEW}
15542 Applies subsequent matrix operations to the modelview matrix stack.
15544 @item @code{GL_PROJECTION}
15545 Applies subsequent matrix operations to the projection matrix stack.
15547 @item @code{GL_TEXTURE}
15548 Applies subsequent matrix operations to the texture matrix stack.
15550 @item @code{GL_COLOR}
15551 Applies subsequent matrix operations to the color matrix stack.
15555 To find out which matrix stack is currently the target of all matrix
15556 operations, call @code{glGet} with argument @code{GL_MATRIX_MODE}. The
15557 initial value is @code{GL_MODELVIEW}.
15559 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
15562 @code{GL_INVALID_OPERATION} is generated if @code{glMatrixMode} is
15563 executed between the execution of @code{glBegin} and the corresponding
15564 execution of @code{glEnd}.
15568 @deftypefun void glMinmax target internalformat sink
15569 Define minmax table.
15573 The minmax table whose parameters are to be set. Must be
15576 @item @var{internalformat}
15577 The format of entries in the minmax table. Must be one of
15578 @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
15579 @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
15580 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
15581 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
15582 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
15583 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
15584 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
15585 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
15586 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
15587 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
15588 @code{GL_RGBA12}, or @code{GL_RGBA16}.
15591 If @code{GL_TRUE}, pixels will be consumed by the minmax process and no
15592 drawing or texture loading will take place. If @code{GL_FALSE}, pixels
15593 will proceed to the final conversion process after minmax.
15597 When @code{GL_MINMAX} is enabled, the RGBA components of incoming pixels
15598 are compared to the minimum and maximum values for each component, which
15599 are stored in the two-element minmax table. (The first element stores
15600 the minima, and the second element stores the maxima.) If a pixel
15601 component is greater than the corresponding component in the maximum
15602 element, then the maximum element is updated with the pixel component
15603 value. If a pixel component is less than the corresponding component in
15604 the minimum element, then the minimum element is updated with the pixel
15605 component value. (In both cases, if the internal format of the minmax
15606 table includes luminance, then the R color component of incoming pixels
15607 is used for comparison.) The contents of the minmax table may be
15608 retrieved at a later time by calling @code{glGetMinmax}. The minmax
15609 operation is enabled or disabled by calling @code{glEnable} or
15610 @code{glDisable}, respectively, with an argument of @code{GL_MINMAX}.
15612 @code{glMinmax} redefines the current minmax table to have entries of
15613 the format specified by @var{internalformat}. The maximum element is
15614 initialized with the smallest possible component values, and the minimum
15615 element is initialized with the largest possible component values. The
15616 values in the previous minmax table, if any, are lost. If @var{sink} is
15617 @code{GL_TRUE}, then pixels are discarded after minmax; no further
15618 processing of the pixels takes place, and no drawing, texture loading,
15619 or pixel readback will result.
15623 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
15626 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
15627 of the allowable values.
15629 @code{GL_INVALID_OPERATION} is generated if @code{glMinmax} is executed
15630 between the execution of @code{glBegin} and the corresponding execution
15635 @deftypefun void glMultiDrawArrays mode first count primcount
15636 Render multiple sets of primitives from array data.
15640 Specifies what kind of primitives to render. Symbolic constants
15641 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
15642 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
15643 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
15644 @code{GL_POLYGON} are accepted.
15647 Points to an array of starting indices in the enabled arrays.
15650 Points to an array of the number of indices to be rendered.
15652 @item @var{primcount}
15653 Specifies the size of the first and count
15657 @code{glMultiDrawArrays} specifies multiple sets of geometric primitives
15658 with very few subroutine calls. Instead of calling a GL procedure to
15659 pass each individual vertex, normal, texture coordinate, edge flag, or
15660 color, you can prespecify separate arrays of vertices, normals, and
15661 colors and use them to construct a sequence of primitives with a single
15662 call to @code{glMultiDrawArrays}.
15664 @code{glMultiDrawArrays} behaves identically to @code{glDrawArrays}
15665 except that @var{primcount} separate ranges of elements are specified
15668 When @code{glMultiDrawArrays} is called, it uses @var{count} sequential
15669 elements from each enabled array to construct a sequence of geometric
15670 primitives, beginning with element @var{first}. @var{mode} specifies
15671 what kind of primitives are constructed, and how the array elements
15672 construct those primitives. If @code{GL_VERTEX_ARRAY} is not enabled, no
15673 geometric primitives are generated.
15675 Vertex attributes that are modified by @code{glMultiDrawArrays} have an
15676 unspecified value after @code{glMultiDrawArrays} returns. For example,
15677 if @code{GL_COLOR_ARRAY} is enabled, the value of the current color is
15678 undefined after @code{glMultiDrawArrays} executes. Attributes that
15679 aren't modified remain well defined.
15681 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
15684 @code{GL_INVALID_VALUE} is generated if @var{primcount} is negative.
15686 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
15687 name is bound to an enabled array and the buffer object's data store is
15690 @code{GL_INVALID_OPERATION} is generated if @code{glMultiDrawArrays} is
15691 executed between the execution of @code{glBegin} and the corresponding
15696 @deftypefun void glMultiDrawElements mode count type indices primcount
15697 Render multiple sets of primitives by specifying indices of array data
15702 Specifies what kind of primitives to render. Symbolic constants
15703 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
15704 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
15705 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
15706 @code{GL_POLYGON} are accepted.
15709 Points to an array of the elements counts.
15712 Specifies the type of the values in @var{indices}. Must be one of
15713 @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or
15714 @code{GL_UNSIGNED_INT}.
15716 @item @var{indices}
15717 Specifies a pointer to the location where the indices are stored.
15719 @item @var{primcount}
15720 Specifies the size of the @var{count} array.
15724 @code{glMultiDrawElements} specifies multiple sets of geometric
15725 primitives with very few subroutine calls. Instead of calling a GL
15726 function to pass each individual vertex, normal, texture coordinate,
15727 edge flag, or color, you can prespecify separate arrays of vertices,
15728 normals, and so on, and use them to construct a sequence of primitives
15729 with a single call to @code{glMultiDrawElements}.
15731 @code{glMultiDrawElements} is identical in operation to
15732 @code{glDrawElements} except that @var{primcount} separate lists of
15733 elements are specified.
15735 Vertex attributes that are modified by @code{glMultiDrawElements} have
15736 an unspecified value after @code{glMultiDrawElements} returns. For
15737 example, if @code{GL_COLOR_ARRAY} is enabled, the value of the current
15738 color is undefined after @code{glMultiDrawElements} executes. Attributes
15739 that aren't modified maintain their previous values.
15741 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
15744 @code{GL_INVALID_VALUE} is generated if @var{primcount} is negative.
15746 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
15747 name is bound to an enabled array or the element array and the buffer
15748 object's data store is currently mapped.
15750 @code{GL_INVALID_OPERATION} is generated if @code{glMultiDrawElements}
15751 is executed between the execution of @code{glBegin} and the
15752 corresponding @code{glEnd}.
15756 @deftypefun void glMultiTexCoord1s target s
15757 @deftypefunx void glMultiTexCoord1i target s
15758 @deftypefunx void glMultiTexCoord1f target s
15759 @deftypefunx void glMultiTexCoord1d target s
15760 @deftypefunx void glMultiTexCoord2s target s t
15761 @deftypefunx void glMultiTexCoord2i target s t
15762 @deftypefunx void glMultiTexCoord2f target s t
15763 @deftypefunx void glMultiTexCoord2d target s t
15764 @deftypefunx void glMultiTexCoord3s target s t r
15765 @deftypefunx void glMultiTexCoord3i target s t r
15766 @deftypefunx void glMultiTexCoord3f target s t r
15767 @deftypefunx void glMultiTexCoord3d target s t r
15768 @deftypefunx void glMultiTexCoord4s target s t r q
15769 @deftypefunx void glMultiTexCoord4i target s t r q
15770 @deftypefunx void glMultiTexCoord4f target s t r q
15771 @deftypefunx void glMultiTexCoord4d target s t r q
15772 @deftypefunx void glMultiTexCoord1sv target v
15773 @deftypefunx void glMultiTexCoord1iv target v
15774 @deftypefunx void glMultiTexCoord1fv target v
15775 @deftypefunx void glMultiTexCoord1dv target v
15776 @deftypefunx void glMultiTexCoord2sv target v
15777 @deftypefunx void glMultiTexCoord2iv target v
15778 @deftypefunx void glMultiTexCoord2fv target v
15779 @deftypefunx void glMultiTexCoord2dv target v
15780 @deftypefunx void glMultiTexCoord3sv target v
15781 @deftypefunx void glMultiTexCoord3iv target v
15782 @deftypefunx void glMultiTexCoord3fv target v
15783 @deftypefunx void glMultiTexCoord3dv target v
15784 @deftypefunx void glMultiTexCoord4sv target v
15785 @deftypefunx void glMultiTexCoord4iv target v
15786 @deftypefunx void glMultiTexCoord4fv target v
15787 @deftypefunx void glMultiTexCoord4dv target v
15788 Set the current texture coordinates.
15792 Specifies the texture unit whose coordinates should be modified. The
15793 number of texture units is implementation dependent, but must be at
15794 least two. Symbolic constant must be one of
15795 @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to
15796 @code{GL_MAX_TEXTURE_COORDS} - 1, which is an implementation-dependent
15803 Specify @var{s}, @var{t}, @var{r}, and @var{q} texture coordinates for
15804 @var{target} texture unit. Not all parameters are present in all forms
15809 @code{glMultiTexCoord} specifies texture coordinates in one, two, three,
15810 or four dimensions. @code{glMultiTexCoord1} sets the current texture
15811 coordinates to @r{(@var{s},001)}; a call to @code{glMultiTexCoord2} sets
15812 them to @r{(@var{s},@var{t}01)}. Similarly, @code{glMultiTexCoord3}
15813 specifies the texture coordinates as @r{(@var{s},@var{t}@var{r}1)}, and
15814 @code{glMultiTexCoord4} defines all four components explicitly as
15815 @r{(@var{s},@var{t}@var{r}@var{q})}.
15817 The current texture coordinates are part of the data that is associated
15818 with each vertex and with the current raster position. Initially, the
15819 values for @r{(@var{s},@var{t}@var{r}@var{q})} are @r{(0,001)}.
15825 @deftypefun void glMultMatrixd m
15826 @deftypefunx void glMultMatrixf m
15827 Multiply the current matrix with the specified matrix.
15831 Points to 16 consecutive values that are used as the elements of a
15832 @r{4×4} column-major matrix.
15836 @code{glMultMatrix} multiplies the current matrix with the one specified
15837 using @var{m}, and replaces the current matrix with the product.
15839 The current matrix is determined by the current matrix mode (see
15840 @code{glMatrixMode}). It is either the projection matrix, modelview
15841 matrix, or the texture matrix.
15843 @code{GL_INVALID_OPERATION} is generated if @code{glMultMatrix} is
15844 executed between the execution of @code{glBegin} and the corresponding
15845 execution of @code{glEnd}.
15849 @deftypefun void glMultTransposeMatrixd m
15850 @deftypefunx void glMultTransposeMatrixf m
15851 Multiply the current matrix with the specified row-major ordered matrix.
15855 Points to 16 consecutive values that are used as the elements of a
15856 @r{4×4} row-major matrix.
15860 @code{glMultTransposeMatrix} multiplies the current matrix with the one
15861 specified using @var{m}, and replaces the current matrix with the
15864 The current matrix is determined by the current matrix mode (see
15865 @code{glMatrixMode}). It is either the projection matrix, modelview
15866 matrix, or the texture matrix.
15868 @code{GL_INVALID_OPERATION} is generated if @code{glMultTransposeMatrix}
15869 is executed between the execution of @code{glBegin} and the
15870 corresponding execution of @code{glEnd}.
15874 @deftypefun void glNewList list mode
15875 @deftypefunx void glEndList
15876 Create or replace a display list.
15880 Specifies the display-list name.
15883 Specifies the compilation mode, which can be @code{GL_COMPILE} or
15884 @code{GL_COMPILE_AND_EXECUTE}.
15888 Display lists are groups of GL commands that have been stored for
15889 subsequent execution. Display lists are created with @code{glNewList}.
15890 All subsequent commands are placed in the display list, in the order
15891 issued, until @code{glEndList} is called.
15893 @code{glNewList} has two arguments. The first argument, @var{list}, is a
15894 positive integer that becomes the unique name for the display list.
15895 Names can be created and reserved with @code{glGenLists} and tested for
15896 uniqueness with @code{glIsList}. The second argument, @var{mode}, is a
15897 symbolic constant that can assume one of two values:
15900 @item @code{GL_COMPILE}
15901 Commands are merely compiled.
15903 @item @code{GL_COMPILE_AND_EXECUTE}
15904 Commands are executed as they are compiled into the display list.
15908 Certain commands are not compiled into the display list but are executed
15909 immediately, regardless of the display-list mode. These commands are
15910 @code{glAreTexturesResident}, @code{glColorPointer},
15911 @code{glDeleteLists}, @code{glDeleteTextures},
15912 @code{glDisableClientState}, @code{glEdgeFlagPointer},
15913 @code{glEnableClientState}, @code{glFeedbackBuffer}, @code{glFinish},
15914 @code{glFlush}, @code{glGenLists}, @code{glGenTextures},
15915 @code{glIndexPointer}, @code{glInterleavedArrays}, @code{glIsEnabled},
15916 @code{glIsList}, @code{glIsTexture}, @code{glNormalPointer},
15917 @code{glPopClientAttrib}, @code{glPixelStore},
15918 @code{glPushClientAttrib}, @code{glReadPixels}, @code{glRenderMode},
15919 @code{glSelectBuffer}, @code{glTexCoordPointer}, @code{glVertexPointer},
15920 and all of the @code{glGet} commands.
15922 Similarly, @code{glTexImage1D}, @code{glTexImage2D}, and
15923 @code{glTexImage3D} are executed immediately and not compiled into the
15924 display list when their first argument is @code{GL_PROXY_TEXTURE_1D},
15925 @code{GL_PROXY_TEXTURE_1D}, or @code{GL_PROXY_TEXTURE_3D}, respectively.
15927 When the @code{ARB_imaging} extension is supported, @code{glHistogram}
15928 executes immediately when its argument is @code{GL_PROXY_HISTOGRAM}.
15929 Similarly, @code{glColorTable} executes immediately when its first
15930 argument is @code{GL_PROXY_COLOR_TABLE},
15931 @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or
15932 @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}.
15934 For OpenGL versions 1.3 and greater, or when the @code{ARB_multitexture}
15935 extension is supported, @code{glClientActiveTexture} is not compiled
15936 into display lists, but executed immediately.
15938 When @code{glEndList} is encountered, the display-list definition is
15939 completed by associating the list with the unique name @var{list}
15940 (specified in the @code{glNewList} command). If a display list with name
15941 @var{list} already exists, it is replaced only when @code{glEndList} is
15944 @code{GL_INVALID_VALUE} is generated if @var{list} is 0.
15946 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
15949 @code{GL_INVALID_OPERATION} is generated if @code{glEndList} is called
15950 without a preceding @code{glNewList}, or if @code{glNewList} is called
15951 while a display list is being defined.
15953 @code{GL_INVALID_OPERATION} is generated if @code{glNewList} or
15954 @code{glEndList} is executed between the execution of @code{glBegin} and
15955 the corresponding execution of @code{glEnd}.
15957 @code{GL_OUT_OF_MEMORY} is generated if there is insufficient memory to
15958 compile the display list. If the GL version is 1.1 or greater, no change
15959 is made to the previous contents of the display list, if any, and no
15960 other change is made to the GL state. (It is as if no attempt had been
15961 made to create the new display list.)
15965 @deftypefun void glNormalPointer type stride pointer
15966 Define an array of normals.
15970 Specifies the data type of each coordinate in the array. Symbolic
15971 constants @code{GL_BYTE}, @code{GL_SHORT}, @code{GL_INT},
15972 @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value is
15976 Specifies the byte offset between consecutive normals. If @var{stride}
15977 is 0, the normals are understood to be tightly packed in the array. The
15978 initial value is 0.
15980 @item @var{pointer}
15981 Specifies a pointer to the first coordinate of the first normal in the
15982 array. The initial value is 0.
15986 @code{glNormalPointer} specifies the location and data format of an
15987 array of normals to use when rendering. @var{type} specifies the data
15988 type of each normal coordinate, and @var{stride} specifies the byte
15989 stride from one normal to the next, allowing vertices and attributes to
15990 be packed into a single array or stored in separate arrays.
15991 (Single-array storage may be more efficient on some implementations; see
15992 @code{glInterleavedArrays}.)
15994 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
15995 target (see @code{glBindBuffer}) while a normal array is specified,
15996 @var{pointer} is treated as a byte offset into the buffer object's data
15997 store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING})
15998 is saved as normal vertex array client-side state
15999 (@code{GL_NORMAL_ARRAY_BUFFER_BINDING}).
16001 When a normal array is specified, @var{type}, @var{stride}, and
16002 @var{pointer} are saved as client-side state, in addition to the current
16003 vertex array buffer object binding.
16005 To enable and disable the normal array, call @code{glEnableClientState}
16006 and @code{glDisableClientState} with the argument
16007 @code{GL_NORMAL_ARRAY}. If enabled, the normal array is used when
16008 @code{glDrawArrays}, @code{glMultiDrawArrays}, @code{glDrawElements},
16009 @code{glMultiDrawElements}, @code{glDrawRangeElements}, or
16010 @code{glArrayElement} is called.
16012 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
16015 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
16019 @deftypefun void glNormal3b nx ny nz
16020 @deftypefunx void glNormal3d nx ny nz
16021 @deftypefunx void glNormal3f nx ny nz
16022 @deftypefunx void glNormal3i nx ny nz
16023 @deftypefunx void glNormal3s nx ny nz
16024 @deftypefunx void glNormal3bv v
16025 @deftypefunx void glNormal3dv v
16026 @deftypefunx void glNormal3fv v
16027 @deftypefunx void glNormal3iv v
16028 @deftypefunx void glNormal3sv v
16029 Set the current normal vector.
16035 Specify the @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} coordinates of the
16036 new current normal. The initial value of the current normal is the unit
16043 The current normal is set to the given coordinates whenever
16044 @code{glNormal} is issued. Byte, short, or integer arguments are
16045 converted to floating-point format with a linear mapping that maps the
16046 most positive representable integer value to 1.0 and the most negative
16047 representable integer value to @r{-1.0}.
16049 Normals specified with @code{glNormal} need not have unit length. If
16050 @code{GL_NORMALIZE} is enabled, then normals of any length specified
16051 with @code{glNormal} are normalized after transformation. If
16052 @code{GL_RESCALE_NORMAL} is enabled, normals are scaled by a scaling
16053 factor derived from the modelview matrix. @code{GL_RESCALE_NORMAL}
16054 requires that the originally specified normals were of unit length, and
16055 that the modelview matrix contain only uniform scales for proper
16056 results. To enable and disable normalization, call @code{glEnable} and
16057 @code{glDisable} with either @code{GL_NORMALIZE} or
16058 @code{GL_RESCALE_NORMAL}. Normalization is initially disabled.
16062 @deftypefun void glOrtho left right bottom top nearVal farVal
16063 Multiply the current matrix with an orthographic matrix.
16068 Specify the coordinates for the left and right vertical clipping planes.
16072 Specify the coordinates for the bottom and top horizontal clipping
16075 @item @var{nearVal}
16076 @itemx @var{farVal}
16077 Specify the distances to the nearer and farther depth clipping planes.
16078 These values are negative if the plane is to be behind the viewer.
16082 @code{glOrtho} describes a transformation that produces a parallel
16083 projection. The current matrix (see @code{glMatrixMode}) is multiplied
16084 by this matrix and the result replaces the current matrix, as if
16085 @code{glMultMatrix} were called with the following matrix as its
16088 @r{((2/@var{right}-@var{left},, 0 0 @var{t}_@var{x},), (0
16089 2/@var{top}-@var{bottom},, 0 @var{t}_@var{y},), (0 0
16090 -2/@var{farVal}-@var{nearVal},, @var{t}_@var{z},), (0 0 0 1),)}
16093 @r{@var{t}_@var{x}=-@var{right}+@var{left},/@var{right}-@var{left},,}@r{@var{t}_@var{y}=-@var{top}+@var{bottom},/@var{top}-@var{bottom},,}@r{@var{t}_@var{z}=-@var{farVal}+@var{nearVal},/@var{farVal}-@var{nearVal},,}
16095 Typically, the matrix mode is @code{GL_PROJECTION}, and
16096 @r{(@var{left},@var{bottom}-@var{nearVal})} and
16097 @r{(@var{right},@var{top}-@var{nearVal})} specify the points on the near
16098 clipping plane that are mapped to the lower left and upper right corners
16099 of the window, respectively, assuming that the eye is located at (0, 0,
16100 0). @r{-@var{farVal}} specifies the location of the far clipping plane.
16101 Both @var{nearVal} and @var{farVal} can be either positive or negative.
16103 Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the
16104 current matrix stack.
16106 @code{GL_INVALID_VALUE} is generated if @var{left} = @var{right}, or
16107 @var{bottom} = @var{top}, or @var{near} = @var{far}.
16109 @code{GL_INVALID_OPERATION} is generated if @code{glOrtho} is executed
16110 between the execution of @code{glBegin} and the corresponding execution
16115 @deftypefun void glPassThrough token
16116 Place a marker in the feedback buffer.
16120 Specifies a marker value to be placed in the feedback buffer following a
16121 @code{GL_PASS_THROUGH_TOKEN}.
16127 Feedback is a GL render mode. The mode is selected by calling
16128 @code{glRenderMode} with @code{GL_FEEDBACK}. When the GL is in feedback
16129 mode, no pixels are produced by rasterization. Instead, information
16130 about primitives that would have been rasterized is fed back to the
16131 application using the GL. See the @code{glFeedbackBuffer} reference page
16132 for a description of the feedback buffer and the values in it.
16134 @code{glPassThrough} inserts a user-defined marker in the feedback
16135 buffer when it is executed in feedback mode. @var{token} is returned as
16136 if it were a primitive; it is indicated with its own unique identifying
16137 value: @code{GL_PASS_THROUGH_TOKEN}. The order of @code{glPassThrough}
16138 commands with respect to the specification of graphics primitives is
16141 @code{GL_INVALID_OPERATION} is generated if @code{glPassThrough} is
16142 executed between the execution of @code{glBegin} and the corresponding
16143 execution of @code{glEnd}.
16147 @deftypefun void glPixelMapfv map mapsize values
16148 @deftypefunx void glPixelMapuiv map mapsize values
16149 @deftypefunx void glPixelMapusv map mapsize values
16150 Set up pixel transfer maps.
16154 Specifies a symbolic map name. Must be one of the following:
16155 @code{GL_PIXEL_MAP_I_TO_I}, @code{GL_PIXEL_MAP_S_TO_S},
16156 @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G},
16157 @code{GL_PIXEL_MAP_I_TO_B}, @code{GL_PIXEL_MAP_I_TO_A},
16158 @code{GL_PIXEL_MAP_R_TO_R}, @code{GL_PIXEL_MAP_G_TO_G},
16159 @code{GL_PIXEL_MAP_B_TO_B}, or @code{GL_PIXEL_MAP_A_TO_A}.
16161 @item @var{mapsize}
16162 Specifies the size of the map being defined.
16165 Specifies an array of @var{mapsize} values.
16169 @code{glPixelMap} sets up translation tables, or @var{maps}, used by
16170 @code{glCopyPixels}, @code{glCopyTexImage1D}, @code{glCopyTexImage2D},
16171 @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D},
16172 @code{glCopyTexSubImage3D}, @code{glDrawPixels}, @code{glReadPixels},
16173 @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D},
16174 @code{glTexSubImage1D}, @code{glTexSubImage2D}, and
16175 @code{glTexSubImage3D}. Additionally, if the @code{ARB_imaging} subset
16176 is supported, the routines @code{glColorTable}, @code{glColorSubTable},
16177 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D},
16178 @code{glHistogram}, @code{glMinmax}, and @code{glSeparableFilter2D}. Use
16179 of these maps is described completely in the @code{glPixelTransfer}
16180 reference page, and partly in the reference pages for the pixel and
16181 texture image commands. Only the specification of the maps is described
16182 in this reference page.
16184 @var{map} is a symbolic map name, indicating one of ten maps to set.
16185 @var{mapsize} specifies the number of entries in the map, and
16186 @var{values} is a pointer to an array of @var{mapsize} map values.
16188 If a non-zero named buffer object is bound to the
16189 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
16190 pixel transfer map is specified, @var{values} is treated as a byte
16191 offset into the buffer object's data store.
16193 The ten maps are as follows:
16196 @item @code{GL_PIXEL_MAP_I_TO_I}
16197 Maps color indices to color indices.
16199 @item @code{GL_PIXEL_MAP_S_TO_S}
16200 Maps stencil indices to stencil indices.
16202 @item @code{GL_PIXEL_MAP_I_TO_R}
16203 Maps color indices to red components.
16205 @item @code{GL_PIXEL_MAP_I_TO_G}
16206 Maps color indices to green components.
16208 @item @code{GL_PIXEL_MAP_I_TO_B}
16209 Maps color indices to blue components.
16211 @item @code{GL_PIXEL_MAP_I_TO_A}
16212 Maps color indices to alpha components.
16214 @item @code{GL_PIXEL_MAP_R_TO_R}
16215 Maps red components to red components.
16217 @item @code{GL_PIXEL_MAP_G_TO_G}
16218 Maps green components to green components.
16220 @item @code{GL_PIXEL_MAP_B_TO_B}
16221 Maps blue components to blue components.
16223 @item @code{GL_PIXEL_MAP_A_TO_A}
16224 Maps alpha components to alpha components.
16228 The entries in a map can be specified as single-precision floating-point
16229 numbers, unsigned short integers, or unsigned int integers. Maps that
16230 store color component values (all but @code{GL_PIXEL_MAP_I_TO_I} and
16231 @code{GL_PIXEL_MAP_S_TO_S}) retain their values in floating-point
16232 format, with unspecified mantissa and exponent sizes. Floating-point
16233 values specified by @code{glPixelMapfv} are converted directly to the
16234 internal floating-point format of these maps, then clamped to the range
16235 [0,1]. Unsigned integer values specified by @code{glPixelMapusv} and
16236 @code{glPixelMapuiv} are converted linearly such that the largest
16237 representable integer maps to 1.0, and 0 maps to 0.0.
16239 Maps that store indices, @code{GL_PIXEL_MAP_I_TO_I} and
16240 @code{GL_PIXEL_MAP_S_TO_S}, retain their values in fixed-point format,
16241 with an unspecified number of bits to the right of the binary point.
16242 Floating-point values specified by @code{glPixelMapfv} are converted
16243 directly to the internal fixed-point format of these maps. Unsigned
16244 integer values specified by @code{glPixelMapusv} and
16245 @code{glPixelMapuiv} specify integer values, with all 0's to the right
16246 of the binary point.
16248 The following table shows the initial sizes and values for each of the
16249 maps. Maps that are indexed by either color or stencil indices must have
16250 @var{mapsize} = @r{2^@var{n}} for some @r{@var{n}} or the results are
16251 undefined. The maximum allowable size for each map depends on the
16252 implementation and can be determined by calling @code{glGet} with
16253 argument @code{GL_MAX_PIXEL_MAP_TABLE}. The single maximum applies to
16254 all maps; it is at least 32.
16257 @item @strong{@var{map}}
16258 @strong{Lookup Index}, @strong{Lookup Value}, @strong{Initial Size},
16259 @strong{Initial Value}
16261 @item @code{GL_PIXEL_MAP_I_TO_I}
16262 color index , color index , 1 , 0
16264 @item @code{GL_PIXEL_MAP_S_TO_S}
16265 stencil index , stencil index , 1 , 0
16267 @item @code{GL_PIXEL_MAP_I_TO_R}
16268 color index , R , 1 , 0
16270 @item @code{GL_PIXEL_MAP_I_TO_G}
16271 color index , G , 1 , 0
16273 @item @code{GL_PIXEL_MAP_I_TO_B}
16274 color index , B , 1 , 0
16276 @item @code{GL_PIXEL_MAP_I_TO_A}
16277 color index , A , 1 , 0
16279 @item @code{GL_PIXEL_MAP_R_TO_R}
16282 @item @code{GL_PIXEL_MAP_G_TO_G}
16285 @item @code{GL_PIXEL_MAP_B_TO_B}
16288 @item @code{GL_PIXEL_MAP_A_TO_A}
16293 @code{GL_INVALID_ENUM} is generated if @var{map} is not an accepted
16296 @code{GL_INVALID_VALUE} is generated if @var{mapsize} is less than one
16297 or larger than @code{GL_MAX_PIXEL_MAP_TABLE}.
16299 @code{GL_INVALID_VALUE} is generated if @var{map} is
16300 @code{GL_PIXEL_MAP_I_TO_I}, @code{GL_PIXEL_MAP_S_TO_S},
16301 @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G},
16302 @code{GL_PIXEL_MAP_I_TO_B}, or @code{GL_PIXEL_MAP_I_TO_A}, and
16303 @var{mapsize} is not a power of two.
16305 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
16306 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
16307 object's data store is currently mapped.
16309 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
16310 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
16311 would be unpacked from the buffer object such that the memory reads
16312 required would exceed the data store size.
16314 @code{GL_INVALID_OPERATION} is generated by @code{glPixelMapfv} if a
16315 non-zero buffer object name is bound to the
16316 @code{GL_PIXEL_UNPACK_BUFFER} target and @var{values} is not evenly
16317 divisible into the number of bytes needed to store in memory a GLfloat
16320 @code{GL_INVALID_OPERATION} is generated by @code{glPixelMapuiv} if a
16321 non-zero buffer object name is bound to the
16322 @code{GL_PIXEL_UNPACK_BUFFER} target and @var{values} is not evenly
16323 divisible into the number of bytes needed to store in memory a GLuint
16326 @code{GL_INVALID_OPERATION} is generated by @code{glPixelMapusv} if a
16327 non-zero buffer object name is bound to the
16328 @code{GL_PIXEL_UNPACK_BUFFER} target and @var{values} is not evenly
16329 divisible into the number of bytes needed to store in memory a GLushort
16332 @code{GL_INVALID_OPERATION} is generated if @code{glPixelMap} is
16333 executed between the execution of @code{glBegin} and the corresponding
16334 execution of @code{glEnd}.
16338 @deftypefun void glPixelStoref pname param
16339 @deftypefunx void glPixelStorei pname param
16340 Set pixel storage modes.
16344 Specifies the symbolic name of the parameter to be set. Six values
16345 affect the packing of pixel data into memory: @code{GL_PACK_SWAP_BYTES},
16346 @code{GL_PACK_LSB_FIRST}, @code{GL_PACK_ROW_LENGTH},
16347 @code{GL_PACK_IMAGE_HEIGHT}, @code{GL_PACK_SKIP_PIXELS},
16348 @code{GL_PACK_SKIP_ROWS}, @code{GL_PACK_SKIP_IMAGES}, and
16349 @code{GL_PACK_ALIGNMENT}. Six more affect the unpacking of pixel data
16350 @var{from} memory: @code{GL_UNPACK_SWAP_BYTES},
16351 @code{GL_UNPACK_LSB_FIRST}, @code{GL_UNPACK_ROW_LENGTH},
16352 @code{GL_UNPACK_IMAGE_HEIGHT}, @code{GL_UNPACK_SKIP_PIXELS},
16353 @code{GL_UNPACK_SKIP_ROWS}, @code{GL_UNPACK_SKIP_IMAGES}, and
16354 @code{GL_UNPACK_ALIGNMENT}.
16357 Specifies the value that @var{pname} is set to.
16361 @code{glPixelStore} sets pixel storage modes that affect the operation
16362 of subsequent @code{glDrawPixels} and @code{glReadPixels} as well as the
16363 unpacking of polygon stipple patterns (see @code{glPolygonStipple}),
16364 bitmaps (see @code{glBitmap}), texture patterns (see
16365 @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D},
16366 @code{glTexSubImage1D}, @code{glTexSubImage2D}, @code{glTexSubImage3D}).
16367 Additionally, if the @code{ARB_imaging} extension is supported, pixel
16368 storage modes affect convolution filters (see
16369 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and
16370 @code{glSeparableFilter2D}, color table (see @code{glColorTable}, and
16371 @code{glColorSubTable}, and unpacking histogram (See
16372 @code{glHistogram}), and minmax (See @code{glMinmax}) data.
16374 @var{pname} is a symbolic constant indicating the parameter to be set,
16375 and @var{param} is the new value. Six of the twelve storage parameters
16376 affect how pixel data is returned to client memory. They are as follows:
16379 @item @code{GL_PACK_SWAP_BYTES}
16380 If true, byte ordering for multibyte color components, depth components,
16381 color indices, or stencil indices is reversed. That is, if a four-byte
16382 component consists of bytes @r{@var{b}_0}, @r{@var{b}_1}, @r{@var{b}_2},
16383 @r{@var{b}_3}, it is stored in memory as @r{@var{b}_3}, @r{@var{b}_2},
16384 @r{@var{b}_1}, @r{@var{b}_0} if @code{GL_PACK_SWAP_BYTES} is true.
16385 @code{GL_PACK_SWAP_BYTES} has no effect on the memory order of
16386 components within a pixel, only on the order of bytes within components
16387 or indices. For example, the three components of a @code{GL_RGB} format
16388 pixel are always stored with red first, green second, and blue third,
16389 regardless of the value of @code{GL_PACK_SWAP_BYTES}.
16391 @item @code{GL_PACK_LSB_FIRST}
16392 If true, bits are ordered within a byte from least significant to most
16393 significant; otherwise, the first bit in each byte is the most
16394 significant one. This parameter is significant for bitmap data only.
16396 @item @code{GL_PACK_ROW_LENGTH}
16397 If greater than 0, @code{GL_PACK_ROW_LENGTH} defines the number of
16398 pixels in a row. If the first pixel of a row is placed at location
16399 @r{@var{p}} in memory, then the location of the first pixel of the next
16400 row is obtained by skipping
16402 @r{@var{k}=@{(@var{n}@var{l}),
16403 (@var{a}/@var{s},⌈@var{s}@var{n}@var{l},/@var{a},⌉)(@var{s}>=@var{a}),
16404 (@var{s}<@var{a}),}
16406 components or indices, where @r{@var{n}} is the number of components or
16407 indices in a pixel, @r{@var{l}} is the number of pixels in a row
16408 (@code{GL_PACK_ROW_LENGTH} if it is greater than 0, the @r{@var{width}}
16409 argument to the pixel routine otherwise), @r{@var{a}} is the value of
16410 @code{GL_PACK_ALIGNMENT}, and @r{@var{s}} is the size, in bytes, of a
16411 single component (if @r{@var{a}<@var{s}}, then it is as if
16412 @r{@var{a}=@var{s}}). In the case of 1-bit values, the location of the
16413 next row is obtained by skipping
16415 @r{@var{k}=8@var{a}⌈@var{n}@var{l},/8@var{a},,⌉}
16417 components or indices.
16419 The word @var{component} in this description refers to the nonindex
16420 values red, green, blue, alpha, and depth. Storage format @code{GL_RGB},
16421 for example, has three components per pixel: first red, then green, and
16424 @item @code{GL_PACK_IMAGE_HEIGHT}
16425 If greater than 0, @code{GL_PACK_IMAGE_HEIGHT} defines the number of
16426 pixels in an image three-dimensional texture volume, where ``image'' is
16427 defined by all pixels sharing the same third dimension index. If the
16428 first pixel of a row is placed at location @r{@var{p}} in memory, then
16429 the location of the first pixel of the next row is obtained by skipping
16431 @r{@var{k}=@{(@var{n}@var{l}@var{h}),
16432 (@var{a}/@var{s},⌈@var{s}@var{n}@var{l}@var{h},/@var{a},⌉)(@var{s}>=@var{a}),
16433 (@var{s}<@var{a}),}
16435 components or indices, where @r{@var{n}} is the number of components or
16436 indices in a pixel, @r{@var{l}} is the number of pixels in a row
16437 (@code{GL_PACK_ROW_LENGTH} if it is greater than 0, the @r{@var{width}}
16438 argument to @code{glTexImage3D} otherwise), @r{@var{h}} is the number of
16439 rows in a pixel image (@code{GL_PACK_IMAGE_HEIGHT} if it is greater than
16440 0, the @r{@var{height}} argument to the @code{glTexImage3D} routine
16441 otherwise), @r{@var{a}} is the value of @code{GL_PACK_ALIGNMENT}, and
16442 @r{@var{s}} is the size, in bytes, of a single component (if
16443 @r{@var{a}<@var{s}}, then it is as if @r{@var{a}=@var{s}}).
16445 The word @var{component} in this description refers to the nonindex
16446 values red, green, blue, alpha, and depth. Storage format @code{GL_RGB},
16447 for example, has three components per pixel: first red, then green, and
16450 @item @code{GL_PACK_SKIP_PIXELS}, @code{GL_PACK_SKIP_ROWS}, and @code{GL_PACK_SKIP_IMAGES}
16451 These values are provided as a convenience to the programmer; they
16452 provide no functionality that cannot be duplicated simply by
16453 incrementing the pointer passed to @code{glReadPixels}. Setting
16454 @code{GL_PACK_SKIP_PIXELS} to @r{@var{i}} is equivalent to incrementing
16455 the pointer by @r{@var{i}@var{n}} components or indices, where
16456 @r{@var{n}} is the number of components or indices in each pixel.
16457 Setting @code{GL_PACK_SKIP_ROWS} to @r{@var{j}} is equivalent to
16458 incrementing the pointer by @r{@var{j}@var{m}} components or indices,
16459 where @r{@var{m}} is the number of components or indices per row, as
16460 just computed in the @code{GL_PACK_ROW_LENGTH} section. Setting
16461 @code{GL_PACK_SKIP_IMAGES} to @r{@var{k}} is equivalent to incrementing
16462 the pointer by @r{@var{k}@var{p}}, where @r{@var{p}} is the number of
16463 components or indices per image, as computed in the
16464 @code{GL_PACK_IMAGE_HEIGHT} section.
16466 @item @code{GL_PACK_ALIGNMENT}
16467 Specifies the alignment requirements for the start of each pixel row in
16468 memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to
16469 even-numbered bytes), 4 (word-alignment), and 8 (rows start on
16470 double-word boundaries).
16474 The other six of the twelve storage parameters affect how pixel data is
16475 read from client memory. These values are significant for
16476 @code{glDrawPixels}, @code{glTexImage1D}, @code{glTexImage2D},
16477 @code{glTexImage3D}, @code{glTexSubImage1D}, @code{glTexSubImage2D},
16478 @code{glTexSubImage3D}, @code{glBitmap}, and @code{glPolygonStipple}.
16480 Additionally, if the @code{ARB_imaging} extension is supported,
16481 @code{glColorTable}, @code{glColorSubTable},
16482 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and
16483 @code{glSeparableFilter2D}. They are as follows:
16486 @item @code{GL_UNPACK_SWAP_BYTES}
16487 If true, byte ordering for multibyte color components, depth components,
16488 color indices, or stencil indices is reversed. That is, if a four-byte
16489 component consists of bytes @r{@var{b}_0}, @r{@var{b}_1}, @r{@var{b}_2},
16490 @r{@var{b}_3}, it is taken from memory as @r{@var{b}_3}, @r{@var{b}_2},
16491 @r{@var{b}_1}, @r{@var{b}_0} if @code{GL_UNPACK_SWAP_BYTES} is true.
16492 @code{GL_UNPACK_SWAP_BYTES} has no effect on the memory order of
16493 components within a pixel, only on the order of bytes within components
16494 or indices. For example, the three components of a @code{GL_RGB} format
16495 pixel are always stored with red first, green second, and blue third,
16496 regardless of the value of @code{GL_UNPACK_SWAP_BYTES}.
16498 @item @code{GL_UNPACK_LSB_FIRST}
16499 If true, bits are ordered within a byte from least significant to most
16500 significant; otherwise, the first bit in each byte is the most
16501 significant one. This is relevant only for bitmap data.
16503 @item @code{GL_UNPACK_ROW_LENGTH}
16504 If greater than 0, @code{GL_UNPACK_ROW_LENGTH} defines the number of
16505 pixels in a row. If the first pixel of a row is placed at location
16506 @r{@var{p}} in memory, then the location of the first pixel of the next
16507 row is obtained by skipping
16509 @r{@var{k}=@{(@var{n}@var{l}),
16510 (@var{a}/@var{s},⌈@var{s}@var{n}@var{l},/@var{a},⌉)(@var{s}>=@var{a}),
16511 (@var{s}<@var{a}),}
16513 components or indices, where @r{@var{n}} is the number of components or
16514 indices in a pixel, @r{@var{l}} is the number of pixels in a row
16515 (@code{GL_UNPACK_ROW_LENGTH} if it is greater than 0, the
16516 @r{@var{width}} argument to the pixel routine otherwise), @r{@var{a}} is
16517 the value of @code{GL_UNPACK_ALIGNMENT}, and @r{@var{s}} is the size, in
16518 bytes, of a single component (if @r{@var{a}<@var{s}}, then it is as if
16519 @r{@var{a}=@var{s}}). In the case of 1-bit values, the location of the
16520 next row is obtained by skipping
16522 @r{@var{k}=8@var{a}⌈@var{n}@var{l},/8@var{a},,⌉}
16524 components or indices.
16526 The word @var{component} in this description refers to the nonindex
16527 values red, green, blue, alpha, and depth. Storage format @code{GL_RGB},
16528 for example, has three components per pixel: first red, then green, and
16531 @item @code{GL_UNPACK_IMAGE_HEIGHT}
16532 If greater than 0, @code{GL_UNPACK_IMAGE_HEIGHT} defines the number of
16533 pixels in an image of a three-dimensional texture volume. Where
16534 ``image'' is defined by all pixel sharing the same third dimension
16535 index. If the first pixel of a row is placed at location @r{@var{p}} in
16536 memory, then the location of the first pixel of the next row is obtained
16539 @r{@var{k}=@{(@var{n}@var{l}@var{h}),
16540 (@var{a}/@var{s},⌈@var{s}@var{n}@var{l}@var{h},/@var{a},⌉)(@var{s}>=@var{a}),
16541 (@var{s}<@var{a}),}
16543 components or indices, where @r{@var{n}} is the number of components or
16544 indices in a pixel, @r{@var{l}} is the number of pixels in a row
16545 (@code{GL_UNPACK_ROW_LENGTH} if it is greater than 0, the
16546 @r{@var{width}} argument to @code{glTexImage3D} otherwise), @r{@var{h}}
16547 is the number of rows in an image (@code{GL_UNPACK_IMAGE_HEIGHT} if it
16548 is greater than 0, the @r{@var{height}} argument to @code{glTexImage3D}
16549 otherwise), @r{@var{a}} is the value of @code{GL_UNPACK_ALIGNMENT}, and
16550 @r{@var{s}} is the size, in bytes, of a single component (if
16551 @r{@var{a}<@var{s}}, then it is as if @r{@var{a}=@var{s}}).
16553 The word @var{component} in this description refers to the nonindex
16554 values red, green, blue, alpha, and depth. Storage format @code{GL_RGB},
16555 for example, has three components per pixel: first red, then green, and
16558 @item @code{GL_UNPACK_SKIP_PIXELS} and @code{GL_UNPACK_SKIP_ROWS}
16559 These values are provided as a convenience to the programmer; they
16560 provide no functionality that cannot be duplicated by incrementing the
16561 pointer passed to @code{glDrawPixels}, @code{glTexImage1D},
16562 @code{glTexImage2D}, @code{glTexSubImage1D}, @code{glTexSubImage2D},
16563 @code{glBitmap}, or @code{glPolygonStipple}. Setting
16564 @code{GL_UNPACK_SKIP_PIXELS} to @r{@var{i}} is equivalent to
16565 incrementing the pointer by @r{@var{i}@var{n}} components or indices,
16566 where @r{@var{n}} is the number of components or indices in each pixel.
16567 Setting @code{GL_UNPACK_SKIP_ROWS} to @r{@var{j}} is equivalent to
16568 incrementing the pointer by @r{@var{j}@var{k}} components or indices,
16569 where @r{@var{k}} is the number of components or indices per row, as
16570 just computed in the @code{GL_UNPACK_ROW_LENGTH} section.
16572 @item @code{GL_UNPACK_ALIGNMENT}
16573 Specifies the alignment requirements for the start of each pixel row in
16574 memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to
16575 even-numbered bytes), 4 (word-alignment), and 8 (rows start on
16576 double-word boundaries).
16580 The following table gives the type, initial value, and range of valid
16581 values for each storage parameter that can be set with
16582 @code{glPixelStore}.
16587 @item @strong{@var{pname}}
16588 @strong{Type}, @strong{Initial Value}, @strong{Valid Range}
16590 @item @code{GL_PACK_SWAP_BYTES}
16591 boolean , false , true or false
16593 @item @code{GL_PACK_LSB_FIRST}
16594 boolean , false , true or false
16596 @item @code{GL_PACK_ROW_LENGTH}
16597 integer , 0 , @r{[0,∞)}
16599 @item @code{GL_PACK_IMAGE_HEIGHT}
16600 integer , 0 , @r{[0,∞)}
16602 @item @code{GL_PACK_SKIP_ROWS}
16603 integer , 0 , @r{[0,∞)}
16605 @item @code{GL_PACK_SKIP_PIXELS}
16606 integer , 0 , @r{[0,∞)}
16608 @item @code{GL_PACK_SKIP_IMAGES}
16609 integer , 0 , @r{[0,∞)}
16611 @item @code{GL_PACK_ALIGNMENT}
16612 integer , 4 , 1, 2, 4, or 8
16614 @item @code{GL_UNPACK_SWAP_BYTES}
16615 boolean , false , true or false
16617 @item @code{GL_UNPACK_LSB_FIRST}
16618 boolean , false , true or false
16620 @item @code{GL_UNPACK_ROW_LENGTH}
16621 integer , 0 , @r{[0,∞)}
16623 @item @code{GL_UNPACK_IMAGE_HEIGHT}
16624 integer , 0 , @r{[0,∞)}
16626 @item @code{GL_UNPACK_SKIP_ROWS}
16627 integer , 0 , @r{[0,∞)}
16629 @item @code{GL_UNPACK_SKIP_PIXELS}
16630 integer , 0 , @r{[0,∞)}
16632 @item @code{GL_UNPACK_SKIP_IMAGES}
16633 integer , 0 , @r{[0,∞)}
16635 @item @code{GL_UNPACK_ALIGNMENT}
16636 integer , 4 , 1, 2, 4, or 8
16640 @code{glPixelStoref} can be used to set any pixel store parameter. If
16641 the parameter type is boolean, then if @var{param} is 0, the parameter
16642 is false; otherwise it is set to true. If @var{pname} is a integer type
16643 parameter, @var{param} is rounded to the nearest integer.
16645 Likewise, @code{glPixelStorei} can also be used to set any of the pixel
16646 store parameters. Boolean parameters are set to false if @var{param} is
16647 0 and true otherwise.
16649 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
16652 @code{GL_INVALID_VALUE} is generated if a negative row length, pixel
16653 skip, or row skip value is specified, or if alignment is specified as
16654 other than 1, 2, 4, or 8.
16656 @code{GL_INVALID_OPERATION} is generated if @code{glPixelStore} is
16657 executed between the execution of @code{glBegin} and the corresponding
16658 execution of @code{glEnd}.
16662 @deftypefun void glPixelTransferf pname param
16663 @deftypefunx void glPixelTransferi pname param
16664 Set pixel transfer modes.
16668 Specifies the symbolic name of the pixel transfer parameter to be set.
16669 Must be one of the following: @code{GL_MAP_COLOR},
16670 @code{GL_MAP_STENCIL}, @code{GL_INDEX_SHIFT}, @code{GL_INDEX_OFFSET},
16671 @code{GL_RED_SCALE}, @code{GL_RED_BIAS}, @code{GL_GREEN_SCALE},
16672 @code{GL_GREEN_BIAS}, @code{GL_BLUE_SCALE}, @code{GL_BLUE_BIAS},
16673 @code{GL_ALPHA_SCALE}, @code{GL_ALPHA_BIAS}, @code{GL_DEPTH_SCALE}, or
16674 @code{GL_DEPTH_BIAS}.
16676 Additionally, if the @code{ARB_imaging} extension is supported, the
16677 following symbolic names are accepted:
16678 @code{GL_POST_COLOR_MATRIX_RED_SCALE},
16679 @code{GL_POST_COLOR_MATRIX_GREEN_SCALE},
16680 @code{GL_POST_COLOR_MATRIX_BLUE_SCALE},
16681 @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE},
16682 @code{GL_POST_COLOR_MATRIX_RED_BIAS},
16683 @code{GL_POST_COLOR_MATRIX_GREEN_BIAS},
16684 @code{GL_POST_COLOR_MATRIX_BLUE_BIAS},
16685 @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS},
16686 @code{GL_POST_CONVOLUTION_RED_SCALE},
16687 @code{GL_POST_CONVOLUTION_GREEN_SCALE},
16688 @code{GL_POST_CONVOLUTION_BLUE_SCALE},
16689 @code{GL_POST_CONVOLUTION_ALPHA_SCALE},
16690 @code{GL_POST_CONVOLUTION_RED_BIAS},
16691 @code{GL_POST_CONVOLUTION_GREEN_BIAS},
16692 @code{GL_POST_CONVOLUTION_BLUE_BIAS}, and
16693 @code{GL_POST_CONVOLUTION_ALPHA_BIAS}.
16696 Specifies the value that @var{pname} is set to.
16700 @code{glPixelTransfer} sets pixel transfer modes that affect the
16701 operation of subsequent @code{glCopyPixels}, @code{glCopyTexImage1D},
16702 @code{glCopyTexImage2D}, @code{glCopyTexSubImage1D},
16703 @code{glCopyTexSubImage2D}, @code{glCopyTexSubImage3D},
16704 @code{glDrawPixels}, @code{glReadPixels}, @code{glTexImage1D},
16705 @code{glTexImage2D}, @code{glTexImage3D}, @code{glTexSubImage1D},
16706 @code{glTexSubImage2D}, and @code{glTexSubImage3D} commands.
16707 Additionally, if the @code{ARB_imaging} subset is supported, the
16708 routines @code{glColorTable}, @code{glColorSubTable},
16709 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D},
16710 @code{glHistogram}, @code{glMinmax}, and @code{glSeparableFilter2D} are
16711 also affected. The algorithms that are specified by pixel transfer modes
16712 operate on pixels after they are read from the frame buffer
16713 (@code{glCopyPixels}@code{glCopyTexImage1D}, @code{glCopyTexImage2D},
16714 @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D},
16715 @code{glCopyTexSubImage3D}, and @code{glReadPixels}), or unpacked from
16716 client memory (@code{glDrawPixels}, @code{glTexImage1D},
16717 @code{glTexImage2D}, @code{glTexImage3D}, @code{glTexSubImage1D},
16718 @code{glTexSubImage2D}, and @code{glTexSubImage3D}). Pixel transfer
16719 operations happen in the same order, and in the same manner, regardless
16720 of the command that resulted in the pixel operation. Pixel storage modes
16721 (see @code{glPixelStore}) control the unpacking of pixels being read
16722 from client memory and the packing of pixels being written back into
16725 Pixel transfer operations handle four fundamental pixel types:
16726 @var{color}, @var{color index}, @var{depth}, and @var{stencil}.
16727 @var{Color} pixels consist of four floating-point values with
16728 unspecified mantissa and exponent sizes, scaled such that 0 represents
16729 zero intensity and 1 represents full intensity. @var{Color indices}
16730 comprise a single fixed-point value, with unspecified precision to the
16731 right of the binary point. @var{Depth} pixels comprise a single
16732 floating-point value, with unspecified mantissa and exponent sizes,
16733 scaled such that 0.0 represents the minimum depth buffer value, and 1.0
16734 represents the maximum depth buffer value. Finally, @var{stencil} pixels
16735 comprise a single fixed-point value, with unspecified precision to the
16736 right of the binary point.
16738 The pixel transfer operations performed on the four basic pixel types
16743 Each of the four color components is multiplied by a scale factor, then
16744 added to a bias factor. That is, the red component is multiplied by
16745 @code{GL_RED_SCALE}, then added to @code{GL_RED_BIAS}; the green
16746 component is multiplied by @code{GL_GREEN_SCALE}, then added to
16747 @code{GL_GREEN_BIAS}; the blue component is multiplied by
16748 @code{GL_BLUE_SCALE}, then added to @code{GL_BLUE_BIAS}; and the alpha
16749 component is multiplied by @code{GL_ALPHA_SCALE}, then added to
16750 @code{GL_ALPHA_BIAS}. After all four color components are scaled and
16751 biased, each is clamped to the range @r{[0,1]}. All color, scale, and
16752 bias values are specified with @code{glPixelTransfer}.
16754 If @code{GL_MAP_COLOR} is true, each color component is scaled by the
16755 size of the corresponding color-to-color map, then replaced by the
16756 contents of that map indexed by the scaled component. That is, the red
16757 component is scaled by @code{GL_PIXEL_MAP_R_TO_R_SIZE}, then replaced by
16758 the contents of @code{GL_PIXEL_MAP_R_TO_R} indexed by itself. The green
16759 component is scaled by @code{GL_PIXEL_MAP_G_TO_G_SIZE}, then replaced by
16760 the contents of @code{GL_PIXEL_MAP_G_TO_G} indexed by itself. The blue
16761 component is scaled by @code{GL_PIXEL_MAP_B_TO_B_SIZE}, then replaced by
16762 the contents of @code{GL_PIXEL_MAP_B_TO_B} indexed by itself. And the
16763 alpha component is scaled by @code{GL_PIXEL_MAP_A_TO_A_SIZE}, then
16764 replaced by the contents of @code{GL_PIXEL_MAP_A_TO_A} indexed by
16765 itself. All components taken from the maps are then clamped to the range
16766 @r{[0,1]}. @code{GL_MAP_COLOR} is specified with @code{glPixelTransfer}.
16767 The contents of the various maps are specified with @code{glPixelMap}.
16769 If the @code{ARB_imaging} extension is supported, each of the four color
16770 components may be scaled and biased after transformation by the color
16771 matrix. That is, the red component is multiplied by
16772 @code{GL_POST_COLOR_MATRIX_RED_SCALE}, then added to
16773 @code{GL_POST_COLOR_MATRIX_RED_BIAS}; the green component is multiplied
16774 by @code{GL_POST_COLOR_MATRIX_GREEN_SCALE}, then added to
16775 @code{GL_POST_COLOR_MATRIX_GREEN_BIAS}; the blue component is multiplied
16776 by @code{GL_POST_COLOR_MATRIX_BLUE_SCALE}, then added to
16777 @code{GL_POST_COLOR_MATRIX_BLUE_BIAS}; and the alpha component is
16778 multiplied by @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE}, then added to
16779 @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS}. After all four color components
16780 are scaled and biased, each is clamped to the range @r{[0,1]}.
16782 Similarly, if the @code{ARB_imaging} extension is supported, each of the
16783 four color components may be scaled and biased after processing by the
16784 enabled convolution filter. That is, the red component is multiplied by
16785 @code{GL_POST_CONVOLUTION_RED_SCALE}, then added to
16786 @code{GL_POST_CONVOLUTION_RED_BIAS}; the green component is multiplied
16787 by @code{GL_POST_CONVOLUTION_GREEN_SCALE}, then added to
16788 @code{GL_POST_CONVOLUTION_GREEN_BIAS}; the blue component is multiplied
16789 by @code{GL_POST_CONVOLUTION_BLUE_SCALE}, then added to
16790 @code{GL_POST_CONVOLUTION_BLUE_BIAS}; and the alpha component is
16791 multiplied by @code{GL_POST_CONVOLUTION_ALPHA_SCALE}, then added to
16792 @code{GL_POST_CONVOLUTION_ALPHA_BIAS}. After all four color components
16793 are scaled and biased, each is clamped to the range @r{[0,1]}.
16795 @item @var{Color index}
16796 Each color index is shifted left by @code{GL_INDEX_SHIFT} bits; any bits
16797 beyond the number of fraction bits carried by the fixed-point index are
16798 filled with zeros. If @code{GL_INDEX_SHIFT} is negative, the shift is to
16799 the right, again zero filled. Then @code{GL_INDEX_OFFSET} is added to
16800 the index. @code{GL_INDEX_SHIFT} and @code{GL_INDEX_OFFSET} are
16801 specified with @code{glPixelTransfer}.
16803 From this point, operation diverges depending on the required format of
16804 the resulting pixels. If the resulting pixels are to be written to a
16805 color index buffer, or if they are being read back to client memory in
16806 @code{GL_COLOR_INDEX} format, the pixels continue to be treated as
16807 indices. If @code{GL_MAP_COLOR} is true, each index is masked by
16808 @r{2^@var{n}-1}, where @r{@var{n}} is @code{GL_PIXEL_MAP_I_TO_I_SIZE},
16809 then replaced by the contents of @code{GL_PIXEL_MAP_I_TO_I} indexed by
16810 the masked value. @code{GL_MAP_COLOR} is specified with
16811 @code{glPixelTransfer}. The contents of the index map is specified with
16814 If the resulting pixels are to be written to an RGBA color buffer, or if
16815 they are read back to client memory in a format other than
16816 @code{GL_COLOR_INDEX}, the pixels are converted from indices to colors
16817 by referencing the four maps @code{GL_PIXEL_MAP_I_TO_R},
16818 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
16819 @code{GL_PIXEL_MAP_I_TO_A}. Before being dereferenced, the index is
16820 masked by @r{2^@var{n}-1}, where @r{@var{n}} is
16821 @code{GL_PIXEL_MAP_I_TO_R_SIZE} for the red map,
16822 @code{GL_PIXEL_MAP_I_TO_G_SIZE} for the green map,
16823 @code{GL_PIXEL_MAP_I_TO_B_SIZE} for the blue map, and
16824 @code{GL_PIXEL_MAP_I_TO_A_SIZE} for the alpha map. All components taken
16825 from the maps are then clamped to the range @r{[0,1]}. The contents of
16826 the four maps is specified with @code{glPixelMap}.
16829 Each depth value is multiplied by @code{GL_DEPTH_SCALE}, added to
16830 @code{GL_DEPTH_BIAS}, then clamped to the range @r{[0,1]}.
16832 @item @var{Stencil}
16833 Each index is shifted @code{GL_INDEX_SHIFT} bits just as a color index
16834 is, then added to @code{GL_INDEX_OFFSET}. If @code{GL_MAP_STENCIL} is
16835 true, each index is masked by @r{2^@var{n}-1}, where @r{@var{n}} is
16836 @code{GL_PIXEL_MAP_S_TO_S_SIZE}, then replaced by the contents of
16837 @code{GL_PIXEL_MAP_S_TO_S} indexed by the masked value.
16841 The following table gives the type, initial value, and range of valid
16842 values for each of the pixel transfer parameters that are set with
16843 @code{glPixelTransfer}.
16848 @item @strong{@var{pname}}
16849 @strong{Type}, @strong{Initial Value}, @strong{Valid Range}
16851 @item @code{GL_MAP_COLOR}
16852 boolean , false , true/false
16854 @item @code{GL_MAP_STENCIL}
16855 boolean , false , true/false
16857 @item @code{GL_INDEX_SHIFT}
16858 integer , 0 , @r{(-∞,∞)}
16860 @item @code{GL_INDEX_OFFSET}
16861 integer , 0 , @r{(-∞,∞)}
16863 @item @code{GL_RED_SCALE}
16864 float , 1 , @r{(-∞,∞)}
16866 @item @code{GL_GREEN_SCALE}
16867 float , 1 , @r{(-∞,∞)}
16869 @item @code{GL_BLUE_SCALE}
16870 float , 1 , @r{(-∞,∞)}
16872 @item @code{GL_ALPHA_SCALE}
16873 float , 1 , @r{(-∞,∞)}
16875 @item @code{GL_DEPTH_SCALE}
16876 float , 1 , @r{(-∞,∞)}
16878 @item @code{GL_RED_BIAS}
16879 float , 0 , @r{(-∞,∞)}
16881 @item @code{GL_GREEN_BIAS}
16882 float , 0 , @r{(-∞,∞)}
16884 @item @code{GL_BLUE_BIAS}
16885 float , 0 , @r{(-∞,∞)}
16887 @item @code{GL_ALPHA_BIAS}
16888 float , 0 , @r{(-∞,∞)}
16890 @item @code{GL_DEPTH_BIAS}
16891 float , 0 , @r{(-∞,∞)}
16893 @item @code{GL_POST_COLOR_MATRIX_RED_SCALE}
16894 float , 1 , @r{(-∞,∞)}
16896 @item @code{GL_POST_COLOR_MATRIX_GREEN_SCALE}
16897 float , 1 , @r{(-∞,∞)}
16899 @item @code{GL_POST_COLOR_MATRIX_BLUE_SCALE}
16900 float , 1 , @r{(-∞,∞)}
16902 @item @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE}
16903 float , 1 , @r{(-∞,∞)}
16905 @item @code{GL_POST_COLOR_MATRIX_RED_BIAS}
16906 float , 0 , @r{(-∞,∞)}
16908 @item @code{GL_POST_COLOR_MATRIX_GREEN_BIAS}
16909 float , 0 , @r{(-∞,∞)}
16911 @item @code{GL_POST_COLOR_MATRIX_BLUE_BIAS}
16912 float , 0 , @r{(-∞,∞)}
16914 @item @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS}
16915 float , 0 , @r{(-∞,∞)}
16917 @item @code{GL_POST_CONVOLUTION_RED_SCALE}
16918 float , 1 , @r{(-∞,∞)}
16920 @item @code{GL_POST_CONVOLUTION_GREEN_SCALE}
16921 float , 1 , @r{(-∞,∞)}
16923 @item @code{GL_POST_CONVOLUTION_BLUE_SCALE}
16924 float , 1 , @r{(-∞,∞)}
16926 @item @code{GL_POST_CONVOLUTION_ALPHA_SCALE}
16927 float , 1 , @r{(-∞,∞)}
16929 @item @code{GL_POST_CONVOLUTION_RED_BIAS}
16930 float , 0 , @r{(-∞,∞)}
16932 @item @code{GL_POST_CONVOLUTION_GREEN_BIAS}
16933 float , 0 , @r{(-∞,∞)}
16935 @item @code{GL_POST_CONVOLUTION_BLUE_BIAS}
16936 float , 0 , @r{(-∞,∞)}
16938 @item @code{GL_POST_CONVOLUTION_ALPHA_BIAS}
16939 float , 0 , @r{(-∞,∞)}
16943 @code{glPixelTransferf} can be used to set any pixel transfer parameter.
16944 If the parameter type is boolean, 0 implies false and any other value
16945 implies true. If @var{pname} is an integer parameter, @var{param} is
16946 rounded to the nearest integer.
16948 Likewise, @code{glPixelTransferi} can be used to set any of the pixel
16949 transfer parameters. Boolean parameters are set to false if @var{param}
16950 is 0 and to true otherwise. @var{param} is converted to floating point
16951 before being assigned to real-valued parameters.
16953 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
16956 @code{GL_INVALID_OPERATION} is generated if @code{glPixelTransfer} is
16957 executed between the execution of @code{glBegin} and the corresponding
16958 execution of @code{glEnd}.
16962 @deftypefun void glPixelZoom xfactor yfactor
16963 Specify the pixel zoom factors.
16966 @item @var{xfactor}
16967 @itemx @var{yfactor}
16968 Specify the @r{@var{x}} and @r{@var{y}} zoom factors for pixel write
16973 @code{glPixelZoom} specifies values for the @r{@var{x}} and @r{@var{y}}
16974 zoom factors. During the execution of @code{glDrawPixels} or
16975 @code{glCopyPixels}, if (@r{@var{xr}}, @r{@var{yr}}) is the current
16976 raster position, and a given element is in the @r{@var{m}}th row and
16977 @r{@var{n}}th column of the pixel rectangle, then pixels whose centers
16978 are in the rectangle with corners at
16980 (@r{@var{xr}+@var{n}·@var{xfactor}}, @r{@var{yr}+@var{m}·@var{yfactor}})
16982 (@r{@var{xr}+(@var{n}+1,)·@var{xfactor}},
16983 @r{@var{yr}+(@var{m}+1,)·@var{yfactor}})
16985 are candidates for replacement. Any pixel whose center lies on the
16986 bottom or left edge of this rectangular region is also modified.
16988 Pixel zoom factors are not limited to positive values. Negative zoom
16989 factors reflect the resulting image about the current raster position.
16991 @code{GL_INVALID_OPERATION} is generated if @code{glPixelZoom} is
16992 executed between the execution of @code{glBegin} and the corresponding
16993 execution of @code{glEnd}.
16997 @deftypefun void glPointParameterf pname param
16998 @deftypefunx void glPointParameteri pname param
16999 @deftypefunx void glPointParameterfv pname params
17000 @deftypefunx void glPointParameteriv pname params
17001 Specify point parameters.
17005 Specifies a single-valued point parameter. @code{GL_POINT_SIZE_MIN},
17006 @code{GL_POINT_SIZE_MAX}, @code{GL_POINT_FADE_THRESHOLD_SIZE}, and
17007 @code{GL_POINT_SPRITE_COORD_ORIGIN} are accepted.
17010 Specifies the value that @var{pname} will be set to.
17014 The following values are accepted for @var{pname}:
17017 @item @code{GL_POINT_SIZE_MIN}
17020 @var{params} is a single floating-point value that specifies the minimum
17021 point size. The default value is 0.0.
17023 @item @code{GL_POINT_SIZE_MAX}
17026 @var{params} is a single floating-point value that specifies the maximum
17027 point size. The default value is 1.0.
17029 @item @code{GL_POINT_FADE_THRESHOLD_SIZE}
17032 @var{params} is a single floating-point value that specifies the
17033 threshold value to which point sizes are clamped if they exceed the
17034 specified value. The default value is 1.0.
17036 @item @code{GL_POINT_DISTANCE_ATTENUATION}
17039 @var{params} is an array of three floating-point values that specify the
17040 coefficients used for scaling the computed point size. The default
17041 values are @r{(1,00)}.
17043 @item @code{GL_POINT_SPRITE_COORD_ORIGIN}
17046 @var{params} is a single enum specifying the point sprite texture
17047 coordinate origin, either @code{GL_LOWER_LEFT} or @code{GL_UPPER_LEFT}.
17048 The default value is @code{GL_UPPER_LEFT}.
17052 @code{GL_INVALID_VALUE} is generated If the value specified for
17053 @code{GL_POINT_SIZE_MIN}, @code{GL_POINT_SIZE_MAX}, or
17054 @code{GL_POINT_FADE_THRESHOLD_SIZE} is less than zero.
17056 @code{GL_INVALID_ENUM} is generated If the value specified for
17057 @code{GL_POINT_SPRITE_COORD_ORIGIN} is not @code{GL_LOWER_LEFT} or
17058 @code{GL_UPPER_LEFT}.
17060 If the value for @code{GL_POINT_SIZE_MIN} is greater than
17061 @code{GL_POINT_SIZE_MAX}, the point size after clamping is undefined,
17062 but no error is generated.
17068 @deftypefun void glPointSize size
17069 Specify the diameter of rasterized points.
17073 Specifies the diameter of rasterized points. The initial value is 1.
17077 @code{glPointSize} specifies the rasterized diameter of both aliased and
17078 antialiased points. Using a point size other than 1 has different
17079 effects, depending on whether point antialiasing is enabled. To enable
17080 and disable point antialiasing, call @code{glEnable} and
17081 @code{glDisable} with argument @code{GL_POINT_SMOOTH}. Point
17082 antialiasing is initially disabled.
17084 The specified point size is multiplied with a distance attenuation
17085 factor and clamped to the specified point size range, and further
17086 clamped to the implementation-dependent point size range to produce the
17087 derived point size using
17089 @r{@var{pointSize}=@var{clamp}(@var{size}×√(1/@var{a}+@var{b}×@var{d}+@var{c}×@var{d}^2,,,),,)}
17091 where @r{@var{d}} is the eye-coordinate distance from the eye to the
17092 vertex, and @r{@var{a}}, @r{@var{b}}, and @r{@var{c}} are the distance
17093 attenuation coefficients (see @code{glPointParameter}).
17095 If multisampling is disabled, the computed point size is used as the
17098 If multisampling is enabled, the point may be faded by modifying the
17099 point alpha value (see @code{glSampleCoverage}) instead of allowing the
17100 point width to go below a given threshold (see @code{glPointParameter}).
17101 In this case, the width is further modified in the following manner:
17103 @r{@var{pointWidth}=@{(@var{pointSize}),
17104 (@var{threshold})(@var{pointSize}>=@var{threshold}),
17105 (@var{otherwise}),}
17107 The point alpha value is modified by computing:
17109 @r{@var{pointAlpha}=@{(1),
17110 ((@var{pointSize}/@var{threshold},)^2)(@var{pointSize}>=@var{threshold}),
17111 (@var{otherwise}),}
17113 If point antialiasing is disabled, the actual size is determined by
17114 rounding the supplied size to the nearest integer. (If the rounding
17115 results in the value 0, it is as if the point size were 1.) If the
17116 rounded size is odd, then the center point (@r{@var{x}}, @r{@var{y}}) of
17117 the pixel fragment that represents the point is computed as
17119 @r{(⌊@var{x}_@var{w},⌋+.5,⌊@var{y}_@var{w},⌋+.5)}
17121 where @r{@var{w}} subscripts indicate window coordinates. All pixels
17122 that lie within the square grid of the rounded size centered at
17123 (@r{@var{x}}, @r{@var{y}}) make up the fragment. If the size is even,
17124 the center point is
17126 @r{(⌊@var{x}_@var{w}+.5,⌋,⌊@var{y}_@var{w}+.5,⌋)}
17128 and the rasterized fragment's centers are the half-integer window
17129 coordinates within the square of the rounded size centered at
17130 @r{(@var{x},@var{y})}. All pixel fragments produced in rasterizing a
17131 nonantialiased point are assigned the same associated data, that of the
17132 vertex corresponding to the point.
17134 If antialiasing is enabled, then point rasterization produces a fragment
17135 for each pixel square that intersects the region lying within the circle
17136 having diameter equal to the current point size and centered at the
17137 point's @r{(@var{x}_@var{w},@var{y}_@var{w})}. The coverage value for
17138 each fragment is the window coordinate area of the intersection of the
17139 circular region with the corresponding pixel square. This value is saved
17140 and used in the final rasterization step. The data associated with each
17141 fragment is the data associated with the point being rasterized.
17143 Not all sizes are supported when point antialiasing is enabled. If an
17144 unsupported size is requested, the nearest supported size is used. Only
17145 size 1 is guaranteed to be supported; others depend on the
17146 implementation. To query the range of supported sizes and the size
17147 difference between supported sizes within the range, call @code{glGet}
17148 with arguments @code{GL_SMOOTH_POINT_SIZE_RANGE} and
17149 @code{GL_SMOOTH_POINT_SIZE_GRANULARITY}. For aliased points, query the
17150 supported ranges and granularity with @code{glGet} with arguments
17151 @code{GL_ALIASED_POINT_SIZE_RANGE}.
17153 @code{GL_INVALID_VALUE} is generated if @var{size} is less than or equal
17156 @code{GL_INVALID_OPERATION} is generated if @code{glPointSize} is
17157 executed between the execution of @code{glBegin} and the corresponding
17158 execution of @code{glEnd}.
17162 @deftypefun void glPolygonMode face mode
17163 Select a polygon rasterization mode.
17167 Specifies the polygons that @var{mode} applies to. Must be
17168 @code{GL_FRONT} for front-facing polygons, @code{GL_BACK} for
17169 back-facing polygons, or @code{GL_FRONT_AND_BACK} for front- and
17170 back-facing polygons.
17173 Specifies how polygons will be rasterized. Accepted values are
17174 @code{GL_POINT}, @code{GL_LINE}, and @code{GL_FILL}. The initial value
17175 is @code{GL_FILL} for both front- and back-facing polygons.
17179 @code{glPolygonMode} controls the interpretation of polygons for
17180 rasterization. @var{face} describes which polygons @var{mode} applies
17181 to: front-facing polygons (@code{GL_FRONT}), back-facing polygons
17182 (@code{GL_BACK}), or both (@code{GL_FRONT_AND_BACK}). The polygon mode
17183 affects only the final rasterization of polygons. In particular, a
17184 polygon's vertices are lit and the polygon is clipped and possibly
17185 culled before these modes are applied.
17187 Three modes are defined and can be specified in @var{mode}:
17190 @item @code{GL_POINT}
17191 Polygon vertices that are marked as the start of a boundary edge are
17192 drawn as points. Point attributes such as @code{GL_POINT_SIZE} and
17193 @code{GL_POINT_SMOOTH} control the rasterization of the points. Polygon
17194 rasterization attributes other than @code{GL_POLYGON_MODE} have no
17197 @item @code{GL_LINE}
17198 Boundary edges of the polygon are drawn as line segments. They are
17199 treated as connected line segments for line stippling; the line stipple
17200 counter and pattern are not reset between segments (see
17201 @code{glLineStipple}). Line attributes such as @code{GL_LINE_WIDTH} and
17202 @code{GL_LINE_SMOOTH} control the rasterization of the lines. Polygon
17203 rasterization attributes other than @code{GL_POLYGON_MODE} have no
17206 @item @code{GL_FILL}
17207 The interior of the polygon is filled. Polygon attributes such as
17208 @code{GL_POLYGON_STIPPLE} and @code{GL_POLYGON_SMOOTH} control the
17209 rasterization of the polygon.
17213 @code{GL_INVALID_ENUM} is generated if either @var{face} or @var{mode}
17214 is not an accepted value.
17216 @code{GL_INVALID_OPERATION} is generated if @code{glPolygonMode} is
17217 executed between the execution of @code{glBegin} and the corresponding
17218 execution of @code{glEnd}.
17222 @deftypefun void glPolygonOffset factor units
17223 Set the scale and units used to calculate depth values.
17227 Specifies a scale factor that is used to create a variable depth offset
17228 for each polygon. The initial value is 0.
17231 Is multiplied by an implementation-specific value to create a constant
17232 depth offset. The initial value is 0.
17236 When @code{GL_POLYGON_OFFSET_FILL}, @code{GL_POLYGON_OFFSET_LINE}, or
17237 @code{GL_POLYGON_OFFSET_POINT} is enabled, each fragment's @var{depth}
17238 value will be offset after it is interpolated from the @var{depth}
17239 values of the appropriate vertices. The value of the offset is
17240 @r{@var{factor}×@var{DZ}+@var{r}×@var{units}}, where @r{@var{DZ}} is a
17241 measurement of the change in depth relative to the screen area of the
17242 polygon, and @r{@var{r}} is the smallest value that is guaranteed to
17243 produce a resolvable offset for a given implementation. The offset is
17244 added before the depth test is performed and before the value is written
17245 into the depth buffer.
17247 @code{glPolygonOffset} is useful for rendering hidden-line images, for
17248 applying decals to surfaces, and for rendering solids with highlighted
17251 @code{GL_INVALID_OPERATION} is generated if @code{glPolygonOffset} is
17252 executed between the execution of @code{glBegin} and the corresponding
17253 execution of @code{glEnd}.
17257 @deftypefun void glPolygonStipple pattern
17258 Set the polygon stippling pattern.
17261 @item @var{pattern}
17262 Specifies a pointer to a @r{32×32} stipple pattern that will be unpacked
17263 from memory in the same way that @code{glDrawPixels} unpacks pixels.
17267 Polygon stippling, like line stippling (see @code{glLineStipple}), masks
17268 out certain fragments produced by rasterization, creating a pattern.
17269 Stippling is independent of polygon antialiasing.
17271 @var{pattern} is a pointer to a @r{32×32} stipple pattern that is stored
17272 in memory just like the pixel data supplied to a @code{glDrawPixels}
17273 call with height and @var{width} both equal to 32, a pixel format of
17274 @code{GL_COLOR_INDEX}, and data type of @code{GL_BITMAP}. That is, the
17275 stipple pattern is represented as a @r{32×32} array of 1-bit color
17276 indices packed in unsigned bytes. @code{glPixelStore} parameters like
17277 @code{GL_UNPACK_SWAP_BYTES} and @code{GL_UNPACK_LSB_FIRST} affect the
17278 assembling of the bits into a stipple pattern. Pixel transfer operations
17279 (shift, offset, pixel map) are not applied to the stipple image,
17282 If a non-zero named buffer object is bound to the
17283 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
17284 stipple pattern is specified, @var{pattern} is treated as a byte offset
17285 into the buffer object's data store.
17287 To enable and disable polygon stippling, call @code{glEnable} and
17288 @code{glDisable} with argument @code{GL_POLYGON_STIPPLE}. Polygon
17289 stippling is initially disabled. If it's enabled, a rasterized polygon
17290 fragment with window coordinates @r{@var{x}_@var{w}} and
17291 @r{@var{y}_@var{w}} is sent to the next stage of the GL if and only if
17292 the (@r{@var{x}_@var{w}%32})th bit in the (@r{@var{y}_@var{w}%32})th row
17293 of the stipple pattern is 1 (one). When polygon stippling is disabled,
17294 it is as if the stipple pattern consists of all 1's.
17296 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
17297 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
17298 object's data store is currently mapped.
17300 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
17301 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
17302 would be unpacked from the buffer object such that the memory reads
17303 required would exceed the data store size.
17305 @code{GL_INVALID_OPERATION} is generated if @code{glPolygonStipple} is
17306 executed between the execution of @code{glBegin} and the corresponding
17307 execution of @code{glEnd}.
17311 @deftypefun void glPrioritizeTextures n textures priorities
17312 Set texture residence priority.
17316 Specifies the number of textures to be prioritized.
17318 @item @var{textures}
17319 Specifies an array containing the names of the textures to be
17322 @item @var{priorities}
17323 Specifies an array containing the texture priorities. A priority given
17324 in an element of @var{priorities} applies to the texture named by the
17325 corresponding element of @var{textures}.
17329 @code{glPrioritizeTextures} assigns the @var{n} texture priorities given
17330 in @var{priorities} to the @var{n} textures named in @var{textures}.
17332 The GL establishes a ``working set'' of textures that are resident in
17333 texture memory. These textures may be bound to a texture target much
17334 more efficiently than textures that are not resident. By specifying a
17335 priority for each texture, @code{glPrioritizeTextures} allows
17336 applications to guide the GL implementation in determining which
17337 textures should be resident.
17339 The priorities given in @var{priorities} are clamped to the range
17340 @r{[0,1]} before they are assigned. 0 indicates the lowest priority;
17341 textures with priority 0 are least likely to be resident. 1 indicates
17342 the highest priority; textures with priority 1 are most likely to be
17343 resident. However, textures are not guaranteed to be resident until they
17346 @code{glPrioritizeTextures} silently ignores attempts to prioritize
17347 texture 0 or any texture name that does not correspond to an existing
17350 @code{glPrioritizeTextures} does not require that any of the textures
17351 named by @var{textures} be bound to a texture target.
17352 @code{glTexParameter} may also be used to set a texture's priority, but
17353 only if the texture is currently bound. This is the only way to set the
17354 priority of a default texture.
17356 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
17358 @code{GL_INVALID_OPERATION} is generated if @code{glPrioritizeTextures}
17359 is executed between the execution of @code{glBegin} and the
17360 corresponding execution of @code{glEnd}.
17364 @deftypefun void glPushAttrib mask
17365 @deftypefunx void glPopAttrib
17366 Push and pop the server attribute stack.
17370 Specifies a mask that indicates which attributes to save. Values for
17371 @var{mask} are listed below.
17375 @code{glPushAttrib} takes one argument, a mask that indicates which
17376 groups of state variables to save on the attribute stack. Symbolic
17377 constants are used to set bits in the mask. @var{mask} is typically
17378 constructed by specifying the bitwise-or of several of these constants
17379 together. The special mask @code{GL_ALL_ATTRIB_BITS} can be used to save
17380 all stackable states.
17382 The symbolic mask constants and their associated GL state are as follows
17383 (the second column lists which attributes are saved):
17388 @item @code{GL_ACCUM_BUFFER_BIT}
17389 Accumulation buffer clear value
17391 @item @code{GL_COLOR_BUFFER_BIT}
17392 @code{GL_ALPHA_TEST} enable bit
17395 Alpha test function and reference value
17398 @code{GL_BLEND} enable bit
17401 Blending source and destination functions
17404 Constant blend color
17410 @code{GL_DITHER} enable bit
17413 @code{GL_DRAW_BUFFER} setting
17416 @code{GL_COLOR_LOGIC_OP} enable bit
17419 @code{GL_INDEX_LOGIC_OP} enable bit
17425 Color mode and index mode clear values
17428 Color mode and index mode writemasks
17430 @item @code{GL_CURRENT_BIT}
17434 Current color index
17437 Current normal vector
17440 Current texture coordinates
17443 Current raster position
17446 @code{GL_CURRENT_RASTER_POSITION_VALID} flag
17449 RGBA color associated with current raster position
17452 Color index associated with current raster position
17455 Texture coordinates associated with current raster position
17458 @code{GL_EDGE_FLAG} flag
17460 @item @code{GL_DEPTH_BUFFER_BIT}
17461 @code{GL_DEPTH_TEST} enable bit
17464 Depth buffer test function
17467 Depth buffer clear value
17470 @code{GL_DEPTH_WRITEMASK} enable bit
17472 @item @code{GL_ENABLE_BIT}
17473 @code{GL_ALPHA_TEST} flag
17476 @code{GL_AUTO_NORMAL} flag
17479 @code{GL_BLEND} flag
17482 Enable bits for the user-definable clipping planes
17485 @code{GL_COLOR_MATERIAL}
17488 @code{GL_CULL_FACE} flag
17491 @code{GL_DEPTH_TEST} flag
17494 @code{GL_DITHER} flag
17500 @code{GL_LIGHT}@var{i} where @code{0} <= @var{i} < @code{GL_MAX_LIGHTS}
17503 @code{GL_LIGHTING} flag
17506 @code{GL_LINE_SMOOTH} flag
17509 @code{GL_LINE_STIPPLE} flag
17512 @code{GL_COLOR_LOGIC_OP} flag
17515 @code{GL_INDEX_LOGIC_OP} flag
17518 @code{GL_MAP1_}@var{x} where @var{x} is a map type
17521 @code{GL_MAP2_}@var{x} where @var{x} is a map type
17524 @code{GL_MULTISAMPLE} flag
17527 @code{GL_NORMALIZE} flag
17530 @code{GL_POINT_SMOOTH} flag
17533 @code{GL_POLYGON_OFFSET_LINE} flag
17536 @code{GL_POLYGON_OFFSET_FILL} flag
17539 @code{GL_POLYGON_OFFSET_POINT} flag
17542 @code{GL_POLYGON_SMOOTH} flag
17545 @code{GL_POLYGON_STIPPLE} flag
17548 @code{GL_SAMPLE_ALPHA_TO_COVERAGE} flag
17551 @code{GL_SAMPLE_ALPHA_TO_ONE} flag
17554 @code{GL_SAMPLE_COVERAGE} flag
17557 @code{GL_SCISSOR_TEST} flag
17560 @code{GL_STENCIL_TEST} flag
17563 @code{GL_TEXTURE_1D} flag
17566 @code{GL_TEXTURE_2D} flag
17569 @code{GL_TEXTURE_3D} flag
17572 Flags @code{GL_TEXTURE_GEN_}@var{x} where @var{x} is S, T, R, or Q
17574 @item @code{GL_EVAL_BIT}
17575 @code{GL_MAP1_}@var{x} enable bits, where @var{x} is a map type
17578 @code{GL_MAP2_}@var{x} enable bits, where @var{x} is a map type
17581 1D grid endpoints and divisions
17584 2D grid endpoints and divisions
17587 @code{GL_AUTO_NORMAL} enable bit
17589 @item @code{GL_FOG_BIT}
17590 @code{GL_FOG} enable bit
17608 @code{GL_FOG_MODE} value
17610 @item @code{GL_HINT_BIT}
17611 @code{GL_PERSPECTIVE_CORRECTION_HINT} setting
17614 @code{GL_POINT_SMOOTH_HINT} setting
17617 @code{GL_LINE_SMOOTH_HINT} setting
17620 @code{GL_POLYGON_SMOOTH_HINT} setting
17623 @code{GL_FOG_HINT} setting
17626 @code{GL_GENERATE_MIPMAP_HINT} setting
17629 @code{GL_TEXTURE_COMPRESSION_HINT} setting
17631 @item @code{GL_LIGHTING_BIT}
17632 @code{GL_COLOR_MATERIAL} enable bit
17635 @code{GL_COLOR_MATERIAL_FACE} value
17638 Color material parameters that are tracking the current color
17641 Ambient scene color
17644 @code{GL_LIGHT_MODEL_LOCAL_VIEWER} value
17647 @code{GL_LIGHT_MODEL_TWO_SIDE} setting
17650 @code{GL_LIGHTING} enable bit
17653 Enable bit for each light
17656 Ambient, diffuse, and specular intensity for each light
17659 Direction, position, exponent, and cutoff angle for each light
17662 Constant, linear, and quadratic attenuation factors for each light
17665 Ambient, diffuse, specular, and emissive color for each material
17668 Ambient, diffuse, and specular color indices for each material
17671 Specular exponent for each material
17674 @code{GL_SHADE_MODEL} setting
17676 @item @code{GL_LINE_BIT}
17677 @code{GL_LINE_SMOOTH} flag
17680 @code{GL_LINE_STIPPLE} enable bit
17683 Line stipple pattern and repeat counter
17688 @item @code{GL_LIST_BIT}
17689 @code{GL_LIST_BASE} setting
17691 @item @code{GL_MULTISAMPLE_BIT}
17692 @code{GL_MULTISAMPLE} flag
17695 @code{GL_SAMPLE_ALPHA_TO_COVERAGE} flag
17698 @code{GL_SAMPLE_ALPHA_TO_ONE} flag
17701 @code{GL_SAMPLE_COVERAGE} flag
17704 @code{GL_SAMPLE_COVERAGE_VALUE} value
17707 @code{GL_SAMPLE_COVERAGE_INVERT} value
17709 @item @code{GL_PIXEL_MODE_BIT}
17710 @code{GL_RED_BIAS} and @code{GL_RED_SCALE} settings
17713 @code{GL_GREEN_BIAS} and @code{GL_GREEN_SCALE} values
17716 @code{GL_BLUE_BIAS} and @code{GL_BLUE_SCALE}
17719 @code{GL_ALPHA_BIAS} and @code{GL_ALPHA_SCALE}
17722 @code{GL_DEPTH_BIAS} and @code{GL_DEPTH_SCALE}
17725 @code{GL_INDEX_OFFSET} and @code{GL_INDEX_SHIFT} values
17728 @code{GL_MAP_COLOR} and @code{GL_MAP_STENCIL} flags
17731 @code{GL_ZOOM_X} and @code{GL_ZOOM_Y} factors
17734 @code{GL_READ_BUFFER} setting
17736 @item @code{GL_POINT_BIT}
17737 @code{GL_POINT_SMOOTH} flag
17742 @item @code{GL_POLYGON_BIT}
17743 @code{GL_CULL_FACE} enable bit
17746 @code{GL_CULL_FACE_MODE} value
17749 @code{GL_FRONT_FACE} indicator
17752 @code{GL_POLYGON_MODE} setting
17755 @code{GL_POLYGON_SMOOTH} flag
17758 @code{GL_POLYGON_STIPPLE} enable bit
17761 @code{GL_POLYGON_OFFSET_FILL} flag
17764 @code{GL_POLYGON_OFFSET_LINE} flag
17767 @code{GL_POLYGON_OFFSET_POINT} flag
17770 @code{GL_POLYGON_OFFSET_FACTOR}
17773 @code{GL_POLYGON_OFFSET_UNITS}
17775 @item @code{GL_POLYGON_STIPPLE_BIT}
17776 Polygon stipple image
17778 @item @code{GL_SCISSOR_BIT}
17779 @code{GL_SCISSOR_TEST} flag
17784 @item @code{GL_STENCIL_BUFFER_BIT}
17785 @code{GL_STENCIL_TEST} enable bit
17788 Stencil function and reference value
17794 Stencil fail, pass, and depth buffer pass actions
17797 Stencil buffer clear value
17800 Stencil buffer writemask
17802 @item @code{GL_TEXTURE_BIT}
17803 Enable bits for the four texture coordinates
17806 Border color for each texture image
17809 Minification function for each texture image
17812 Magnification function for each texture image
17815 Texture coordinates and wrap mode for each texture image
17818 Color and mode for each texture environment
17821 Enable bits @code{GL_TEXTURE_GEN_}@var{x}, @var{x} is S, T, R, and Q
17824 @code{GL_TEXTURE_GEN_MODE} setting for S, T, R, and Q
17827 @code{glTexGen} plane equations for S, T, R, and Q
17830 Current texture bindings (for example, @code{GL_TEXTURE_BINDING_2D})
17832 @item @code{GL_TRANSFORM_BIT}
17833 Coefficients of the six clipping planes
17836 Enable bits for the user-definable clipping planes
17839 @code{GL_MATRIX_MODE} value
17842 @code{GL_NORMALIZE} flag
17845 @code{GL_RESCALE_NORMAL} flag
17847 @item @code{GL_VIEWPORT_BIT}
17848 Depth range (near and far)
17851 Viewport origin and extent
17855 @code{glPopAttrib} restores the values of the state variables saved with
17856 the last @code{glPushAttrib} command. Those not saved are left
17859 It is an error to push attributes onto a full stack or to pop attributes
17860 off an empty stack. In either case, the error flag is set and no other
17861 change is made to GL state.
17863 Initially, the attribute stack is empty.
17865 @code{GL_STACK_OVERFLOW} is generated if @code{glPushAttrib} is called
17866 while the attribute stack is full.
17868 @code{GL_STACK_UNDERFLOW} is generated if @code{glPopAttrib} is called
17869 while the attribute stack is empty.
17871 @code{GL_INVALID_OPERATION} is generated if @code{glPushAttrib} or
17872 @code{glPopAttrib} is executed between the execution of @code{glBegin}
17873 and the corresponding execution of @code{glEnd}.
17877 @deftypefun void glPushClientAttrib mask
17878 @deftypefunx void glPopClientAttrib
17879 Push and pop the client attribute stack.
17883 Specifies a mask that indicates which attributes to save. Values for
17884 @var{mask} are listed below.
17888 @code{glPushClientAttrib} takes one argument, a mask that indicates
17889 which groups of client-state variables to save on the client attribute
17890 stack. Symbolic constants are used to set bits in the mask. @var{mask}
17891 is typically constructed by specifying the bitwise-or of several of
17892 these constants together. The special mask
17893 @code{GL_CLIENT_ALL_ATTRIB_BITS} can be used to save all stackable
17896 The symbolic mask constants and their associated GL client state are as
17897 follows (the second column lists which attributes are saved):
17899 @code{GL_CLIENT_PIXEL_STORE_BIT} Pixel storage modes
17900 @code{GL_CLIENT_VERTEX_ARRAY_BIT} Vertex arrays (and enables)
17902 @code{glPopClientAttrib} restores the values of the client-state
17903 variables saved with the last @code{glPushClientAttrib}. Those not saved
17904 are left unchanged.
17906 It is an error to push attributes onto a full client attribute stack or
17907 to pop attributes off an empty stack. In either case, the error flag is
17908 set, and no other change is made to GL state.
17910 Initially, the client attribute stack is empty.
17912 @code{GL_STACK_OVERFLOW} is generated if @code{glPushClientAttrib} is
17913 called while the attribute stack is full.
17915 @code{GL_STACK_UNDERFLOW} is generated if @code{glPopClientAttrib} is
17916 called while the attribute stack is empty.
17920 @deftypefun void glPushMatrix
17921 @deftypefunx void glPopMatrix
17922 Push and pop the current matrix stack.
17924 There is a stack of matrices for each of the matrix modes. In
17925 @code{GL_MODELVIEW} mode, the stack depth is at least 32. In the other
17926 modes, @code{GL_COLOR}, @code{GL_PROJECTION}, and @code{GL_TEXTURE}, the
17927 depth is at least 2. The current matrix in any mode is the matrix on the
17928 top of the stack for that mode.
17930 @code{glPushMatrix} pushes the current matrix stack down by one,
17931 duplicating the current matrix. That is, after a @code{glPushMatrix}
17932 call, the matrix on top of the stack is identical to the one below it.
17934 @code{glPopMatrix} pops the current matrix stack, replacing the current
17935 matrix with the one below it on the stack.
17937 Initially, each of the stacks contains one matrix, an identity matrix.
17939 It is an error to push a full matrix stack or to pop a matrix stack that
17940 contains only a single matrix. In either case, the error flag is set and
17941 no other change is made to GL state.
17943 @code{GL_STACK_OVERFLOW} is generated if @code{glPushMatrix} is called
17944 while the current matrix stack is full.
17946 @code{GL_STACK_UNDERFLOW} is generated if @code{glPopMatrix} is called
17947 while the current matrix stack contains only a single matrix.
17949 @code{GL_INVALID_OPERATION} is generated if @code{glPushMatrix} or
17950 @code{glPopMatrix} is executed between the execution of @code{glBegin}
17951 and the corresponding execution of @code{glEnd}.
17955 @deftypefun void glPushName name
17956 @deftypefunx void glPopName
17957 Push and pop the name stack.
17961 Specifies a name that will be pushed onto the name stack.
17965 The name stack is used during selection mode to allow sets of rendering
17966 commands to be uniquely identified. It consists of an ordered set of
17967 unsigned integers and is initially empty.
17969 @code{glPushName} causes @var{name} to be pushed onto the name stack.
17970 @code{glPopName} pops one name off the top of the stack.
17972 The maximum name stack depth is implementation-dependent; call
17973 @code{GL_MAX_NAME_STACK_DEPTH} to find out the value for a particular
17974 implementation. It is an error to push a name onto a full stack or to
17975 pop a name off an empty stack. It is also an error to manipulate the
17976 name stack between the execution of @code{glBegin} and the corresponding
17977 execution of @code{glEnd}. In any of these cases, the error flag is set
17978 and no other change is made to GL state.
17980 The name stack is always empty while the render mode is not
17981 @code{GL_SELECT}. Calls to @code{glPushName} or @code{glPopName} while
17982 the render mode is not @code{GL_SELECT} are ignored.
17984 @code{GL_STACK_OVERFLOW} is generated if @code{glPushName} is called
17985 while the name stack is full.
17987 @code{GL_STACK_UNDERFLOW} is generated if @code{glPopName} is called
17988 while the name stack is empty.
17990 @code{GL_INVALID_OPERATION} is generated if @code{glPushName} or
17991 @code{glPopName} is executed between a call to @code{glBegin} and the
17992 corresponding call to @code{glEnd}.
17996 @deftypefun void glRasterPos2s x y
17997 @deftypefunx void glRasterPos2i x y
17998 @deftypefunx void glRasterPos2f x y
17999 @deftypefunx void glRasterPos2d x y
18000 @deftypefunx void glRasterPos3s x y z
18001 @deftypefunx void glRasterPos3i x y z
18002 @deftypefunx void glRasterPos3f x y z
18003 @deftypefunx void glRasterPos3d x y z
18004 @deftypefunx void glRasterPos4s x y z w
18005 @deftypefunx void glRasterPos4i x y z w
18006 @deftypefunx void glRasterPos4f x y z w
18007 @deftypefunx void glRasterPos4d x y z w
18008 @deftypefunx void glRasterPos2sv v
18009 @deftypefunx void glRasterPos2iv v
18010 @deftypefunx void glRasterPos2fv v
18011 @deftypefunx void glRasterPos2dv v
18012 @deftypefunx void glRasterPos3sv v
18013 @deftypefunx void glRasterPos3iv v
18014 @deftypefunx void glRasterPos3fv v
18015 @deftypefunx void glRasterPos3dv v
18016 @deftypefunx void glRasterPos4sv v
18017 @deftypefunx void glRasterPos4iv v
18018 @deftypefunx void glRasterPos4fv v
18019 @deftypefunx void glRasterPos4dv v
18020 Specify the raster position for pixel operations.
18027 Specify the @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}
18028 object coordinates (if present) for the raster position.
18032 The GL maintains a 3D position in window coordinates. This position,
18033 called the raster position, is used to position pixel and bitmap write
18034 operations. It is maintained with subpixel accuracy. See
18035 @code{glBitmap}, @code{glDrawPixels}, and @code{glCopyPixels}.
18037 The current raster position consists of three window coordinates
18038 (@r{@var{x}}, @r{@var{y}}, @r{@var{z}}), a clip coordinate value
18039 (@r{@var{w}}), an eye coordinate distance, a valid bit, and associated
18040 color data and texture coordinates. The @r{@var{w}} coordinate is a clip
18041 coordinate, because @r{@var{w}} is not projected to window coordinates.
18042 @code{glRasterPos4} specifies object coordinates @r{@var{x}},
18043 @r{@var{y}}, @r{@var{z}}, and @r{@var{w}} explicitly.
18044 @code{glRasterPos3} specifies object coordinate @r{@var{x}},
18045 @r{@var{y}}, and @r{@var{z}} explicitly, while @r{@var{w}} is implicitly
18046 set to 1. @code{glRasterPos2} uses the argument values for @r{@var{x}}
18047 and @r{@var{y}} while implicitly setting @r{@var{z}} and @r{@var{w}} to
18050 The object coordinates presented by @code{glRasterPos} are treated just
18051 like those of a @code{glVertex} command: They are transformed by the
18052 current modelview and projection matrices and passed to the clipping
18053 stage. If the vertex is not culled, then it is projected and scaled to
18054 window coordinates, which become the new current raster position, and
18055 the @code{GL_CURRENT_RASTER_POSITION_VALID} flag is set. If the vertex
18056 @var{is} culled, then the valid bit is cleared and the current raster
18057 position and associated color and texture coordinates are undefined.
18059 The current raster position also includes some associated color data and
18060 texture coordinates. If lighting is enabled, then
18061 @code{GL_CURRENT_RASTER_COLOR} (in RGBA mode) or
18062 @code{GL_CURRENT_RASTER_INDEX} (in color index mode) is set to the color
18063 produced by the lighting calculation (see @code{glLight},
18064 @code{glLightModel}, and @code{glShadeModel}). If lighting is disabled,
18065 current color (in RGBA mode, state variable @code{GL_CURRENT_COLOR}) or
18066 color index (in color index mode, state variable
18067 @code{GL_CURRENT_INDEX}) is used to update the current raster color.
18068 @code{GL_CURRENT_RASTER_SECONDARY_COLOR} (in RGBA mode) is likewise
18071 Likewise, @code{GL_CURRENT_RASTER_TEXTURE_COORDS} is updated as a
18072 function of @code{GL_CURRENT_TEXTURE_COORDS}, based on the texture
18073 matrix and the texture generation functions (see @code{glTexGen}).
18074 Finally, the distance from the origin of the eye coordinate system to
18075 the vertex as transformed by only the modelview matrix replaces
18076 @code{GL_CURRENT_RASTER_DISTANCE}.
18078 Initially, the current raster position is (0, 0, 0, 1), the current
18079 raster distance is 0, the valid bit is set, the associated RGBA color is
18080 (1, 1, 1, 1), the associated color index is 1, and the associated
18081 texture coordinates are (0, 0, 0, 1). In RGBA mode,
18082 @code{GL_CURRENT_RASTER_INDEX} is always 1; in color index mode, the
18083 current raster RGBA color always maintains its initial value.
18085 @code{GL_INVALID_OPERATION} is generated if @code{glRasterPos} is
18086 executed between the execution of @code{glBegin} and the corresponding
18087 execution of @code{glEnd}.
18091 @deftypefun void glReadBuffer mode
18092 Select a color buffer source for pixels.
18096 Specifies a color buffer. Accepted values are @code{GL_FRONT_LEFT},
18097 @code{GL_FRONT_RIGHT}, @code{GL_BACK_LEFT}, @code{GL_BACK_RIGHT},
18098 @code{GL_FRONT}, @code{GL_BACK}, @code{GL_LEFT}, @code{GL_RIGHT}, and
18099 @code{GL_AUX}@var{i}, where @var{i} is between 0 and the value of
18100 @code{GL_AUX_BUFFERS} minus 1.
18104 @code{glReadBuffer} specifies a color buffer as the source for
18105 subsequent @code{glReadPixels}, @code{glCopyTexImage1D},
18106 @code{glCopyTexImage2D}, @code{glCopyTexSubImage1D},
18107 @code{glCopyTexSubImage2D}, @code{glCopyTexSubImage3D}, and
18108 @code{glCopyPixels} commands. @var{mode} accepts one of twelve or more
18109 predefined values. (@code{GL_AUX0} through @code{GL_AUX3} are always
18110 defined.) In a fully configured system, @code{GL_FRONT}, @code{GL_LEFT},
18111 and @code{GL_FRONT_LEFT} all name the front left buffer,
18112 @code{GL_FRONT_RIGHT} and @code{GL_RIGHT} name the front right buffer,
18113 and @code{GL_BACK_LEFT} and @code{GL_BACK} name the back left buffer.
18115 Nonstereo double-buffered configurations have only a front left and a
18116 back left buffer. Single-buffered configurations have a front left and a
18117 front right buffer if stereo, and only a front left buffer if nonstereo.
18118 It is an error to specify a nonexistent buffer to @code{glReadBuffer}.
18120 @var{mode} is initially @code{GL_FRONT} in single-buffered
18121 configurations and @code{GL_BACK} in double-buffered configurations.
18123 @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of the
18124 twelve (or more) accepted values.
18126 @code{GL_INVALID_OPERATION} is generated if @var{mode} specifies a
18127 buffer that does not exist.
18129 @code{GL_INVALID_OPERATION} is generated if @code{glReadBuffer} is
18130 executed between the execution of @code{glBegin} and the corresponding
18131 execution of @code{glEnd}.
18135 @deftypefun void glReadPixels x y width height format type data
18136 Read a block of pixels from the frame buffer.
18141 Specify the window coordinates of the first pixel that is read from the
18142 frame buffer. This location is the lower left corner of a rectangular
18146 @itemx @var{height}
18147 Specify the dimensions of the pixel rectangle. @var{width} and
18148 @var{height} of one correspond to a single pixel.
18151 Specifies the format of the pixel data. The following symbolic values
18152 are accepted: @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX},
18153 @code{GL_DEPTH_COMPONENT}, @code{GL_RED}, @code{GL_GREEN},
18154 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
18155 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
18156 @code{GL_LUMINANCE_ALPHA}.
18159 Specifies the data type of the pixel data. Must be one of
18160 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
18161 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
18162 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
18163 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
18164 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
18165 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
18166 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
18167 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
18168 or @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
18171 Returns the pixel data.
18175 @code{glReadPixels} returns pixel data from the frame buffer, starting
18176 with the pixel whose lower left corner is at location (@var{x},
18177 @var{y}), into client memory starting at location @var{data}. Several
18178 parameters control the processing of the pixel data before it is placed
18179 into client memory. These parameters are set with three commands:
18180 @code{glPixelStore}, @code{glPixelTransfer}, and @code{glPixelMap}. This
18181 reference page describes the effects on @code{glReadPixels} of most, but
18182 not all of the parameters specified by these three commands.
18184 If a non-zero named buffer object is bound to the
18185 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
18186 block of pixels is requested, @var{data} is treated as a byte offset
18187 into the buffer object's data store rather than a pointer to client
18190 When the @code{ARB_imaging} extension is supported, the pixel data may
18191 be processed by additional operations including color table lookup,
18192 color matrix transformations, convolutions, histograms, and minimum and
18193 maximum pixel value computations.
18195 @code{glReadPixels} returns values from each pixel with lower left
18196 corner at @r{(@var{x}+@var{i},@var{y}+@var{j})} for
18197 @r{0<=@var{i}<@var{width}} and @r{0<=@var{j}<@var{height}}. This pixel
18198 is said to be the @r{@var{i}}th pixel in the @r{@var{j}}th row. Pixels
18199 are returned in row order from the lowest to the highest row, left to
18202 @var{format} specifies the format for the returned pixel values;
18203 accepted values are:
18206 @item @code{GL_COLOR_INDEX}
18207 Color indices are read from the color buffer selected by
18208 @code{glReadBuffer}. Each index is converted to fixed point, shifted
18209 left or right depending on the value and sign of @code{GL_INDEX_SHIFT},
18210 and added to @code{GL_INDEX_OFFSET}. If @code{GL_MAP_COLOR} is
18211 @code{GL_TRUE}, indices are replaced by their mappings in the table
18212 @code{GL_PIXEL_MAP_I_TO_I}.
18214 @item @code{GL_STENCIL_INDEX}
18215 Stencil values are read from the stencil buffer. Each index is converted
18216 to fixed point, shifted left or right depending on the value and sign of
18217 @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET}. If
18218 @code{GL_MAP_STENCIL} is @code{GL_TRUE}, indices are replaced by their
18219 mappings in the table @code{GL_PIXEL_MAP_S_TO_S}.
18221 @item @code{GL_DEPTH_COMPONENT}
18222 Depth values are read from the depth buffer. Each component is converted
18223 to floating point such that the minimum depth value maps to 0 and the
18224 maximum value maps to 1. Each component is then multiplied by
18225 @code{GL_DEPTH_SCALE}, added to @code{GL_DEPTH_BIAS}, and finally
18226 clamped to the range @r{[0,1]}.
18228 @item @code{GL_RED}
18229 @item @code{GL_GREEN}
18230 @item @code{GL_BLUE}
18231 @item @code{GL_ALPHA}
18232 @item @code{GL_RGB}
18233 @item @code{GL_BGR}
18234 @item @code{GL_RGBA}
18235 @item @code{GL_BGRA}
18236 @item @code{GL_LUMINANCE}
18237 @item @code{GL_LUMINANCE_ALPHA}
18238 Processing differs depending on whether color buffers store color
18239 indices or RGBA color components. If color indices are stored, they are
18240 read from the color buffer selected by @code{glReadBuffer}. Each index
18241 is converted to fixed point, shifted left or right depending on the
18242 value and sign of @code{GL_INDEX_SHIFT}, and added to
18243 @code{GL_INDEX_OFFSET}. Indices are then replaced by the red, green,
18244 blue, and alpha values obtained by indexing the tables
18245 @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G},
18246 @code{GL_PIXEL_MAP_I_TO_B}, and @code{GL_PIXEL_MAP_I_TO_A}. Each table
18247 must be of size @r{2^@var{n}}, but @r{@var{n}} may be different for
18248 different tables. Before an index is used to look up a value in a table
18249 of size @r{2^@var{n}}, it must be masked against @r{2^@var{n}-1}.
18251 If RGBA color components are stored in the color buffers, they are read
18252 from the color buffer selected by @code{glReadBuffer}. Each color
18253 component is converted to floating point such that zero intensity maps
18254 to 0.0 and full intensity maps to 1.0. Each component is then multiplied
18255 by @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is
18256 RED, GREEN, BLUE, or ALPHA. Finally, if @code{GL_MAP_COLOR} is
18257 @code{GL_TRUE}, each component is clamped to the range @r{[0,1]}, scaled
18258 to the size of its corresponding table, and is then replaced by its
18259 mapping in the table @code{GL_PIXEL_MAP_c_TO_c}, where @var{c} is R, G,
18262 Unneeded data is then discarded. For example, @code{GL_RED} discards the
18263 green, blue, and alpha components, while @code{GL_RGB} discards only the
18264 alpha component. @code{GL_LUMINANCE} computes a single-component value
18265 as the sum of the red, green, and blue components, and
18266 @code{GL_LUMINANCE_ALPHA} does the same, while keeping alpha as a second
18267 value. The final values are clamped to the range @r{[0,1]}.
18271 The shift, scale, bias, and lookup factors just described are all
18272 specified by @code{glPixelTransfer}. The lookup table contents
18273 themselves are specified by @code{glPixelMap}.
18275 Finally, the indices or components are converted to the proper format,
18276 as specified by @var{type}. If @var{format} is @code{GL_COLOR_INDEX} or
18277 @code{GL_STENCIL_INDEX} and @var{type} is not @code{GL_FLOAT}, each
18278 index is masked with the mask value given in the following table. If
18279 @var{type} is @code{GL_FLOAT}, then each integer index is converted to
18280 single-precision floating-point format.
18282 If @var{format} is @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE},
18283 @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA},
18284 @code{GL_BGRA}, @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA} and
18285 @var{type} is not @code{GL_FLOAT}, each component is multiplied by the
18286 multiplier shown in the following table. If type is @code{GL_FLOAT},
18287 then each component is passed as is (or converted to the client's
18288 single-precision floating-point format if it is different from the one
18295 @strong{Index Mask}, @strong{Component Conversion}
18297 @item @code{GL_UNSIGNED_BYTE}
18298 @r{2^8-1}, @r{(2^8-1,)@var{c}}
18300 @item @code{GL_BYTE}
18301 @r{2^7-1}, @r{(2^8-1,)@var{c}-1,/2}
18303 @item @code{GL_BITMAP}
18306 @item @code{GL_UNSIGNED_SHORT}
18307 @r{2^16-1}, @r{(2^16-1,)@var{c}}
18309 @item @code{GL_SHORT}
18310 @r{2^15-1}, @r{(2^16-1,)@var{c}-1,/2}
18312 @item @code{GL_UNSIGNED_INT}
18313 @r{2^32-1}, @r{(2^32-1,)@var{c}}
18315 @item @code{GL_INT}
18316 @r{2^31-1}, @r{(2^32-1,)@var{c}-1,/2}
18318 @item @code{GL_FLOAT}
18323 Return values are placed in memory as follows. If @var{format} is
18324 @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX},
18325 @code{GL_DEPTH_COMPONENT}, @code{GL_RED}, @code{GL_GREEN},
18326 @code{GL_BLUE}, @code{GL_ALPHA}, or @code{GL_LUMINANCE}, a single value
18327 is returned and the data for the @r{@var{i}}th pixel in the
18328 @r{@var{j}}th row is placed in location
18329 @r{(@var{j},)@var{width}+@var{i}}. @code{GL_RGB} and @code{GL_BGR}
18330 return three values, @code{GL_RGBA} and @code{GL_BGRA} return four
18331 values, and @code{GL_LUMINANCE_ALPHA} returns two values for each pixel,
18332 with all values corresponding to a single pixel occupying contiguous
18333 space in @var{data}. Storage parameters set by @code{glPixelStore}, such
18334 as @code{GL_PACK_LSB_FIRST} and @code{GL_PACK_SWAP_BYTES}, affect the
18335 way that data is written into memory. See @code{glPixelStore} for a
18338 @code{GL_INVALID_ENUM} is generated if @var{format} or @var{type} is not
18341 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
18342 and @var{format} is not @code{GL_COLOR_INDEX} or
18343 @code{GL_STENCIL_INDEX}.
18345 @code{GL_INVALID_VALUE} is generated if either @var{width} or
18346 @var{height} is negative.
18348 @code{GL_INVALID_OPERATION} is generated if @var{format} is
18349 @code{GL_COLOR_INDEX} and the color buffers store RGBA color components.
18351 @code{GL_INVALID_OPERATION} is generated if @var{format} is
18352 @code{GL_STENCIL_INDEX} and there is no stencil buffer.
18354 @code{GL_INVALID_OPERATION} is generated if @var{format} is
18355 @code{GL_DEPTH_COMPONENT} and there is no depth buffer.
18357 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
18358 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
18359 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
18360 and @var{format} is not @code{GL_RGB}.
18362 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
18363 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
18364 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
18365 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
18366 @code{GL_UNSIGNED_INT_10_10_10_2}, or
18367 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
18368 @code{GL_RGBA} nor @code{GL_BGRA}.
18370 The formats @code{GL_BGR}, and @code{GL_BGRA} and types
18371 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
18372 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
18373 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
18374 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
18375 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
18376 @code{GL_UNSIGNED_INT_10_10_10_2}, and
18377 @code{GL_UNSIGNED_INT_2_10_10_10_REV} are available only if the GL
18378 version is 1.2 or greater.
18380 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
18381 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
18382 object's data store is currently mapped.
18384 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
18385 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
18386 would be packed to the buffer object such that the memory writes
18387 required would exceed the data store size.
18389 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
18390 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{data}
18391 is not evenly divisible into the number of bytes needed to store in
18392 memory a datum indicated by @var{type}.
18394 @code{GL_INVALID_OPERATION} is generated if @code{glReadPixels} is
18395 executed between the execution of @code{glBegin} and the corresponding
18396 execution of @code{glEnd}.
18400 @deftypefun void glRectd x1 y1 x2 y2
18401 @deftypefunx void glRectf x1 y1 x2 y2
18402 @deftypefunx void glRecti x1 y1 x2 y2
18403 @deftypefunx void glRects x1 y1 x2 y2
18404 @deftypefunx void glRectdv v1 v2
18405 @deftypefunx void glRectfv v1 v2
18406 @deftypefunx void glRectiv v1 v2
18407 @deftypefunx void glRectsv v1 v2
18413 Specify one vertex of a rectangle.
18417 Specify the opposite vertex of the rectangle.
18421 @code{glRect} supports efficient specification of rectangles as two
18422 corner points. Each rectangle command takes four arguments, organized
18423 either as two consecutive pairs of @r{(@var{x},@var{y})} coordinates or
18424 as two pointers to arrays, each containing an @r{(@var{x},@var{y})}
18425 pair. The resulting rectangle is defined in the @r{@var{z}=0} plane.
18427 @code{glRect}(@var{x1}, @var{y1}, @var{x2}, @var{y2}) is exactly
18428 equivalent to the following sequence: Note that if the second vertex is
18429 above and to the right of the first vertex, the rectangle is constructed
18430 with a counterclockwise winding.
18434 glBegin(@code{GL_POLYGON});
18435 glVertex2(@var{x1}, @var{y1});
18436 glVertex2(@var{x2}, @var{y1});
18437 glVertex2(@var{x2}, @var{y2});
18438 glVertex2(@var{x1}, @var{y2});
18442 @code{GL_INVALID_OPERATION} is generated if @code{glRect} is executed
18443 between the execution of @code{glBegin} and the corresponding execution
18448 @deftypefun GLint glRenderMode mode
18449 Set rasterization mode.
18453 Specifies the rasterization mode. Three values are accepted:
18454 @code{GL_RENDER}, @code{GL_SELECT}, and @code{GL_FEEDBACK}. The initial
18455 value is @code{GL_RENDER}.
18459 @code{glRenderMode} sets the rasterization mode. It takes one argument,
18460 @var{mode}, which can assume one of three predefined values:
18463 @item @code{GL_RENDER}
18464 Render mode. Primitives are rasterized, producing pixel fragments, which
18465 are written into the frame buffer. This is the normal mode and also the
18468 @item @code{GL_SELECT}
18469 Selection mode. No pixel fragments are produced, and no change to the
18470 frame buffer contents is made. Instead, a record of the names of
18471 primitives that would have been drawn if the render mode had been
18472 @code{GL_RENDER} is returned in a select buffer, which must be created
18473 (see @code{glSelectBuffer}) before selection mode is entered.
18475 @item @code{GL_FEEDBACK}
18476 Feedback mode. No pixel fragments are produced, and no change to the
18477 frame buffer contents is made. Instead, the coordinates and attributes
18478 of vertices that would have been drawn if the render mode had been
18479 @code{GL_RENDER} is returned in a feedback buffer, which must be created
18480 (see @code{glFeedbackBuffer}) before feedback mode is entered.
18484 The return value of @code{glRenderMode} is determined by the render mode
18485 at the time @code{glRenderMode} is called, rather than by @var{mode}.
18486 The values returned for the three render modes are as follows:
18489 @item @code{GL_RENDER}
18492 @item @code{GL_SELECT}
18493 The number of hit records transferred to the select buffer.
18495 @item @code{GL_FEEDBACK}
18496 The number of values (not vertices) transferred to the feedback buffer.
18500 See the @code{glSelectBuffer} and @code{glFeedbackBuffer} reference
18501 pages for more details concerning selection and feedback operation.
18503 @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of the
18504 three accepted values.
18506 @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is
18507 called while the render mode is @code{GL_SELECT}, or if
18508 @code{glRenderMode} is called with argument @code{GL_SELECT} before
18509 @code{glSelectBuffer} is called at least once.
18511 @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is
18512 called while the render mode is @code{GL_FEEDBACK}, or if
18513 @code{glRenderMode} is called with argument @code{GL_FEEDBACK} before
18514 @code{glFeedbackBuffer} is called at least once.
18516 @code{GL_INVALID_OPERATION} is generated if @code{glRenderMode} is
18517 executed between the execution of @code{glBegin} and the corresponding
18518 execution of @code{glEnd}.
18522 @deftypefun void glResetHistogram target
18523 Reset histogram table entries to zero.
18527 Must be @code{GL_HISTOGRAM}.
18531 @code{glResetHistogram} resets all the elements of the current histogram
18534 @code{GL_INVALID_ENUM} is generated if @var{target} is not
18535 @code{GL_HISTOGRAM}.
18537 @code{GL_INVALID_OPERATION} is generated if @code{glResetHistogram} is
18538 executed between the execution of @code{glBegin} and the corresponding
18539 execution of @code{glEnd}.
18543 @deftypefun void glResetMinmax target
18544 Reset minmax table entries to initial values.
18548 Must be @code{GL_MINMAX}.
18552 @code{glResetMinmax} resets the elements of the current minmax table to
18553 their initial values: the ``maximum'' element receives the minimum
18554 possible component values, and the ``minimum'' element receives the
18555 maximum possible component values.
18557 @code{GL_INVALID_ENUM} is generated if @var{target} is not
18560 @code{GL_INVALID_OPERATION} is generated if @code{glResetMinmax} is
18561 executed between the execution of @code{glBegin} and the corresponding
18562 execution of @code{glEnd}.
18566 @deftypefun void glRotated angle x y z
18567 @deftypefunx void glRotatef angle x y z
18568 Multiply the current matrix by a rotation matrix.
18572 Specifies the angle of rotation, in degrees.
18577 Specify the @var{x}, @var{y}, and @var{z} coordinates of a vector,
18582 @code{glRotate} produces a rotation of @var{angle} degrees around the
18583 vector @r{(@var{x},@var{y}@var{z})}. The current matrix (see
18584 @code{glMatrixMode}) is multiplied by a rotation matrix with the product
18585 replacing the current matrix, as if @code{glMultMatrix} were called with
18586 the following matrix as its argument:
18588 @r{((@var{x}^2(1-@var{c},)+@var{c}
18589 @var{x}@var{y}(1-@var{c},)-@var{z}@var{s}
18590 @var{x}@var{z}(1-@var{c},)+@var{y}@var{s} 0),
18591 (@var{y}@var{x}(1-@var{c},)+@var{z}@var{s}
18592 @var{y}^2(1-@var{c},)+@var{c}
18593 @var{y}@var{z}(1-@var{c},)-@var{x}@var{s} 0),
18594 (@var{x}@var{z}(1-@var{c},)-@var{y}@var{s}
18595 @var{y}@var{z}(1-@var{c},)+@var{x}@var{s}
18596 @var{z}^2(1-@var{c},)+@var{c} 0), (0 0 0 1),)}
18600 Where @r{@var{c}=@var{cos}(@var{angle},)},
18601 @r{@var{s}=@var{sin}(@var{angle},)}, and
18602 @r{∥(@var{x},@var{y}@var{z}),∥=1} (if not, the GL will normalize this
18609 If the matrix mode is either @code{GL_MODELVIEW} or
18610 @code{GL_PROJECTION}, all objects drawn after @code{glRotate} is called
18611 are rotated. Use @code{glPushMatrix} and @code{glPopMatrix} to save and
18612 restore the unrotated coordinate system.
18614 @code{GL_INVALID_OPERATION} is generated if @code{glRotate} is executed
18615 between the execution of @code{glBegin} and the corresponding execution
18620 @deftypefun void glSampleCoverage value invert
18621 Specify multisample coverage parameters.
18625 Specify a single floating-point sample coverage value. The value is
18626 clamped to the range @r{[0,1]}. The initial value is 1.0.
18629 Specify a single boolean value representing if the coverage masks should
18630 be inverted. @code{GL_TRUE} and @code{GL_FALSE} are accepted. The
18631 initial value is @code{GL_FALSE}.
18635 Multisampling samples a pixel multiple times at various
18636 implementation-dependent subpixel locations to generate antialiasing
18637 effects. Multisampling transparently antialiases points, lines,
18638 polygons, bitmaps, and images if it is enabled.
18640 @var{value} is used in constructing a temporary mask used in determining
18641 which samples will be used in resolving the final fragment color. This
18642 mask is bitwise-anded with the coverage mask generated from the
18643 multisampling computation. If the @var{invert} flag is set, the
18644 temporary mask is inverted (all bits flipped) and then the bitwise-and
18647 If an implementation does not have any multisample buffers available, or
18648 multisampling is disabled, rasterization occurs with only a single
18649 sample computing a pixel's final RGB color.
18651 Provided an implementation supports multisample buffers, and
18652 multisampling is enabled, then a pixel's final color is generated by
18653 combining several samples per pixel. Each sample contains color, depth,
18654 and stencil information, allowing those operations to be performed on
18657 @code{GL_INVALID_OPERATION} is generated if @code{glSampleCoverage} is
18658 executed between the execution of @code{glBegin} and the corresponding
18659 execution of @code{glEnd}.
18663 @deftypefun void glScaled x y z
18664 @deftypefunx void glScalef x y z
18665 Multiply the current matrix by a general scaling matrix.
18671 Specify scale factors along the @var{x}, @var{y}, and @var{z} axes,
18676 @code{glScale} produces a nonuniform scaling along the @var{x}, @var{y},
18677 and @var{z} axes. The three parameters indicate the desired scale factor
18678 along each of the three axes.
18680 The current matrix (see @code{glMatrixMode}) is multiplied by this scale
18681 matrix, and the product replaces the current matrix as if
18682 @code{glMultMatrix} were called with the following matrix as its
18685 @r{((@var{x} 0 0 0), (0 @var{y} 0 0), (0 0 @var{z} 0), (0 0 0 1),)}
18687 If the matrix mode is either @code{GL_MODELVIEW} or
18688 @code{GL_PROJECTION}, all objects drawn after @code{glScale} is called
18691 Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the
18692 unscaled coordinate system.
18694 @code{GL_INVALID_OPERATION} is generated if @code{glScale} is executed
18695 between the execution of @code{glBegin} and the corresponding execution
18700 @deftypefun void glScissor x y width height
18701 Define the scissor box.
18706 Specify the lower left corner of the scissor box. Initially (0, 0).
18709 @itemx @var{height}
18710 Specify the width and height of the scissor box. When a GL context is
18711 first attached to a window, @var{width} and @var{height} are set to the
18712 dimensions of that window.
18716 @code{glScissor} defines a rectangle, called the scissor box, in window
18717 coordinates. The first two arguments, @var{x} and @var{y}, specify the
18718 lower left corner of the box. @var{width} and @var{height} specify the
18719 width and height of the box.
18721 To enable and disable the scissor test, call @code{glEnable} and
18722 @code{glDisable} with argument @code{GL_SCISSOR_TEST}. The test is
18723 initially disabled. While the test is enabled, only pixels that lie
18724 within the scissor box can be modified by drawing commands. Window
18725 coordinates have integer values at the shared corners of frame buffer
18726 pixels. @code{glScissor(0,0,1,1)} allows modification of only the lower
18727 left pixel in the window, and @code{glScissor(0,0,0,0)} doesn't allow
18728 modification of any pixels in the window.
18730 When the scissor test is disabled, it is as though the scissor box
18731 includes the entire window.
18733 @code{GL_INVALID_VALUE} is generated if either @var{width} or
18734 @var{height} is negative.
18736 @code{GL_INVALID_OPERATION} is generated if @code{glScissor} is executed
18737 between the execution of @code{glBegin} and the corresponding execution
18742 @deftypefun void glSecondaryColorPointer size type stride pointer
18743 Define an array of secondary colors.
18747 Specifies the number of components per color. Must be 3.
18750 Specifies the data type of each color component in the array. Symbolic
18751 constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
18752 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
18753 @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is
18757 Specifies the byte offset between consecutive colors. If @var{stride} is
18758 0, the colors are understood to be tightly packed in the array. The
18759 initial value is 0.
18761 @item @var{pointer}
18762 Specifies a pointer to the first component of the first color element in
18763 the array. The initial value is 0.
18767 @code{glSecondaryColorPointer} specifies the location and data format of
18768 an array of color components to use when rendering. @var{size} specifies
18769 the number of components per color, and must be 3. @var{type} specifies
18770 the data type of each color component, and @var{stride} specifies the
18771 byte stride from one color to the next, allowing vertices and attributes
18772 to be packed into a single array or stored in separate arrays.
18774 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
18775 target (see @code{glBindBuffer}) while a secondary color array is
18776 specified, @var{pointer} is treated as a byte offset into the buffer
18777 object's data store. Also, the buffer object binding
18778 (@code{GL_ARRAY_BUFFER_BINDING}) is saved as secondary color vertex
18779 array client-side state
18780 (@code{GL_SECONDARY_COLOR_ARRAY_BUFFER_BINDING}).
18782 When a secondary color array is specified, @var{size}, @var{type},
18783 @var{stride}, and @var{pointer} are saved as client-side state, in
18784 addition to the current vertex array buffer object binding.
18786 To enable and disable the secondary color array, call
18787 @code{glEnableClientState} and @code{glDisableClientState} with the
18788 argument @code{GL_SECONDARY_COLOR_ARRAY}. If enabled, the secondary
18789 color array is used when @code{glArrayElement}, @code{glDrawArrays},
18790 @code{glMultiDrawArrays}, @code{glDrawElements},
18791 @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called.
18793 @code{GL_INVALID_VALUE} is generated if @var{size} is not 3.
18795 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
18798 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
18802 @deftypefun void glSecondaryColor3b red green blue
18803 @deftypefunx void glSecondaryColor3s red green blue
18804 @deftypefunx void glSecondaryColor3i red green blue
18805 @deftypefunx void glSecondaryColor3f red green blue
18806 @deftypefunx void glSecondaryColor3d red green blue
18807 @deftypefunx void glSecondaryColor3ub red green blue
18808 @deftypefunx void glSecondaryColor3us red green blue
18809 @deftypefunx void glSecondaryColor3ui red green blue
18810 @deftypefunx void glSecondaryColor3bv v
18811 @deftypefunx void glSecondaryColor3sv v
18812 @deftypefunx void glSecondaryColor3iv v
18813 @deftypefunx void glSecondaryColor3fv v
18814 @deftypefunx void glSecondaryColor3dv v
18815 @deftypefunx void glSecondaryColor3ubv v
18816 @deftypefunx void glSecondaryColor3usv v
18817 @deftypefunx void glSecondaryColor3uiv v
18818 Set the current secondary color.
18824 Specify new red, green, and blue values for the current secondary color.
18828 The GL stores both a primary four-valued RGBA color and a secondary
18829 four-valued RGBA color (where alpha is always set to 0.0) that is
18830 associated with every vertex.
18832 The secondary color is interpolated and applied to each fragment during
18833 rasterization when @code{GL_COLOR_SUM} is enabled. When lighting is
18834 enabled, and @code{GL_SEPARATE_SPECULAR_COLOR} is specified, the value
18835 of the secondary color is assigned the value computed from the specular
18836 term of the lighting computation. Both the primary and secondary current
18837 colors are applied to each fragment, regardless of the state of
18838 @code{GL_COLOR_SUM}, under such conditions. When
18839 @code{GL_SEPARATE_SPECULAR_COLOR} is specified, the value returned from
18840 querying the current secondary color is undefined.
18842 @code{glSecondaryColor3b}, @code{glSecondaryColor3s}, and
18843 @code{glSecondaryColor3i} take three signed byte, short, or long
18844 integers as arguments. When @strong{v} is appended to the name, the
18845 color commands can take a pointer to an array of such values.
18847 Color values are stored in floating-point format, with unspecified
18848 mantissa and exponent sizes. Unsigned integer color components, when
18849 specified, are linearly mapped to floating-point values such that the
18850 largest representable value maps to 1.0 (full intensity), and 0 maps to
18851 0.0 (zero intensity). Signed integer color components, when specified,
18852 are linearly mapped to floating-point values such that the most positive
18853 representable value maps to 1.0, and the most negative representable
18854 value maps to @r{-1.0}. (Note that this mapping does not convert 0
18855 precisely to 0.0). Floating-point values are mapped directly.
18857 Neither floating-point nor signed integer values are clamped to the
18858 range @r{[0,1]} before the current color is updated. However, color
18859 components are clamped to this range before they are interpolated or
18860 written into a color buffer.
18864 @deftypefun void glSelectBuffer size buffer
18865 Establish a buffer for selection mode values.
18869 Specifies the size of @var{buffer}.
18872 Returns the selection data.
18876 @code{glSelectBuffer} has two arguments: @var{buffer} is a pointer to an
18877 array of unsigned integers, and @var{size} indicates the size of the
18878 array. @var{buffer} returns values from the name stack (see
18879 @code{glInitNames}, @code{glLoadName}, @code{glPushName}) when the
18880 rendering mode is @code{GL_SELECT} (see @code{glRenderMode}).
18881 @code{glSelectBuffer} must be issued before selection mode is enabled,
18882 and it must not be issued while the rendering mode is @code{GL_SELECT}.
18884 A programmer can use selection to determine which primitives are drawn
18885 into some region of a window. The region is defined by the current
18886 modelview and perspective matrices.
18888 In selection mode, no pixel fragments are produced from rasterization.
18889 Instead, if a primitive or a raster position intersects the clipping
18890 volume defined by the viewing frustum and the user-defined clipping
18891 planes, this primitive causes a selection hit. (With polygons, no hit
18892 occurs if the polygon is culled.) When a change is made to the name
18893 stack, or when @code{glRenderMode} is called, a hit record is copied to
18894 @var{buffer} if any hits have occurred since the last such event (name
18895 stack change or @code{glRenderMode} call). The hit record consists of
18896 the number of names in the name stack at the time of the event, followed
18897 by the minimum and maximum depth values of all vertices that hit since
18898 the previous event, followed by the name stack contents, bottom name
18901 Depth values (which are in the range [0,1]) are multiplied by
18902 @r{2^32-1}, before being placed in the hit record.
18904 An internal index into @var{buffer} is reset to 0 whenever selection
18905 mode is entered. Each time a hit record is copied into @var{buffer}, the
18906 index is incremented to point to the cell just past the end of the block
18907 of names\(emthat is, to the next available cell If the hit record is
18908 larger than the number of remaining locations in @var{buffer}, as much
18909 data as can fit is copied, and the overflow flag is set. If the name
18910 stack is empty when a hit record is copied, that record consists of 0
18911 followed by the minimum and maximum depth values.
18913 To exit selection mode, call @code{glRenderMode} with an argument other
18914 than @code{GL_SELECT}. Whenever @code{glRenderMode} is called while the
18915 render mode is @code{GL_SELECT}, it returns the number of hit records
18916 copied to @var{buffer}, resets the overflow flag and the selection
18917 buffer pointer, and initializes the name stack to be empty. If the
18918 overflow bit was set when @code{glRenderMode} was called, a negative hit
18919 record count is returned.
18921 @code{GL_INVALID_VALUE} is generated if @var{size} is negative.
18923 @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is
18924 called while the render mode is @code{GL_SELECT}, or if
18925 @code{glRenderMode} is called with argument @code{GL_SELECT} before
18926 @code{glSelectBuffer} is called at least once.
18928 @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is
18929 executed between the execution of @code{glBegin} and the corresponding
18930 execution of @code{glEnd}.
18934 @deftypefun void glSeparableFilter2D target internalformat width height format type row column
18935 Define a separable two-dimensional convolution filter.
18939 Must be @code{GL_SEPARABLE_2D}.
18941 @item @var{internalformat}
18942 The internal format of the convolution filter kernel. The allowable
18943 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
18944 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
18945 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
18946 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
18947 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
18948 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
18949 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
18950 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
18951 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
18952 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
18953 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
18954 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
18955 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
18958 The number of elements in the pixel array referenced by @var{row}. (This
18959 is the width of the separable filter kernel.)
18962 The number of elements in the pixel array referenced by @var{column}.
18963 (This is the height of the separable filter kernel.)
18966 The format of the pixel data in @var{row} and @var{column}. The
18967 allowable values are @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE},
18968 @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA},
18969 @code{GL_BGRA}, @code{GL_INTENSITY}, @code{GL_LUMINANCE}, and
18970 @code{GL_LUMINANCE_ALPHA}.
18973 The type of the pixel data in @var{row} and @var{column}. Symbolic
18974 constants @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
18975 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
18976 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
18977 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
18978 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
18979 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
18980 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
18981 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
18982 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
18985 Pointer to a one-dimensional array of pixel data that is processed to
18986 build the row filter kernel.
18989 Pointer to a one-dimensional array of pixel data that is processed to
18990 build the column filter kernel.
18994 @code{glSeparableFilter2D} builds a two-dimensional separable
18995 convolution filter kernel from two arrays of pixels.
18997 The pixel arrays specified by (@var{width}, @var{format}, @var{type},
18998 @var{row}) and (@var{height}, @var{format}, @var{type}, @var{column})
18999 are processed just as if they had been passed to @code{glDrawPixels},
19000 but processing stops after the final expansion to RGBA is completed.
19002 If a non-zero named buffer object is bound to the
19003 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
19004 convolution filter is specified, @var{row} and @var{column} are treated
19005 as byte offsets into the buffer object's data store.
19007 Next, the R, G, B, and A components of all pixels in both arrays are
19008 scaled by the four separable 2D @code{GL_CONVOLUTION_FILTER_SCALE}
19009 parameters and biased by the four separable 2D
19010 @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
19011 parameters are set by @code{glConvolutionParameter} using the
19012 @code{GL_SEPARABLE_2D} target and the names
19013 @code{GL_CONVOLUTION_FILTER_SCALE} and
19014 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors
19015 of four values that are applied to red, green, blue, and alpha, in that
19016 order.) The R, G, B, and A values are not clamped to [0,1] at any time
19017 during this process.
19019 Each pixel is then converted to the internal format specified by
19020 @var{internalformat}. This conversion simply maps the component values
19021 of the pixel (R, G, B, and A) to the values included in the internal
19022 format (red, green, blue, alpha, luminance, and intensity). The mapping
19026 @item @strong{Internal Format}
19027 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
19028 @strong{Luminance}, @strong{Intensity}
19030 @item @code{GL_LUMINANCE}
19033 @item @code{GL_LUMINANCE_ALPHA}
19036 @item @code{GL_INTENSITY}
19039 @item @code{GL_RGB}
19042 @item @code{GL_RGBA}
19047 The red, green, blue, alpha, luminance, and/or intensity components of
19048 the resulting pixels are stored in floating-point rather than integer
19049 format. They form two one-dimensional filter kernel images. The row
19050 image is indexed by coordinate @var{i} starting at zero and increasing
19051 from left to right. Each location in the row image is derived from
19052 element @var{i} of @var{row}. The column image is indexed by coordinate
19053 @var{j} starting at zero and increasing from bottom to top. Each
19054 location in the column image is derived from element @var{j} of
19057 Note that after a convolution is performed, the resulting color
19058 components are also scaled by their corresponding
19059 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
19060 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
19061 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
19062 and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}.
19064 @code{GL_INVALID_ENUM} is generated if @var{target} is not
19065 @code{GL_SEPARABLE_2D}.
19067 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
19068 of the allowable values.
19070 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
19073 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
19076 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
19077 greater than the maximum supported value. This value may be queried with
19078 @code{glGetConvolutionParameter} using target @code{GL_SEPARABLE_2D} and
19079 name @code{GL_MAX_CONVOLUTION_WIDTH}.
19081 @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero
19082 or greater than the maximum supported value. This value may be queried
19083 with @code{glGetConvolutionParameter} using target
19084 @code{GL_SEPARABLE_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}.
19086 @code{GL_INVALID_OPERATION} is generated if @var{height} is one of
19087 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
19088 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
19089 and @var{format} is not @code{GL_RGB}.
19091 @code{GL_INVALID_OPERATION} is generated if @var{height} is one of
19092 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
19093 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
19094 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
19095 @code{GL_UNSIGNED_INT_10_10_10_2}, or
19096 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
19097 @code{GL_RGBA} nor @code{GL_BGRA}.
19099 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
19100 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
19101 object's data store is currently mapped.
19103 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
19104 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
19105 would be unpacked from the buffer object such that the memory reads
19106 required would exceed the data store size.
19108 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
19109 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{row}
19110 or @var{column} is not evenly divisible into the number of bytes needed
19111 to store in memory a datum indicated by @var{type}.
19113 @code{GL_INVALID_OPERATION} is generated if @code{glSeparableFilter2D}
19114 is executed between the execution of @code{glBegin} and the
19115 corresponding execution of @code{glEnd}.
19119 @deftypefun void glShadeModel mode
19120 Select flat or smooth shading.
19124 Specifies a symbolic value representing a shading technique. Accepted
19125 values are @code{GL_FLAT} and @code{GL_SMOOTH}. The initial value is
19130 GL primitives can have either flat or smooth shading. Smooth shading,
19131 the default, causes the computed colors of vertices to be interpolated
19132 as the primitive is rasterized, typically assigning different colors to
19133 each resulting pixel fragment. Flat shading selects the computed color
19134 of just one vertex and assigns it to all the pixel fragments generated
19135 by rasterizing a single primitive. In either case, the computed color of
19136 a vertex is the result of lighting if lighting is enabled, or it is the
19137 current color at the time the vertex was specified if lighting is
19140 Flat and smooth shading are indistinguishable for points. Starting when
19141 @code{glBegin} is issued and counting vertices and primitives from 1,
19142 the GL gives each flat-shaded line segment @r{@var{i}} the computed
19143 color of vertex @r{@var{i}+1}, its second vertex. Counting similarly
19144 from 1, the GL gives each flat-shaded polygon the computed color of the
19145 vertex listed in the following table. This is the last vertex to specify
19146 the polygon in all cases except single polygons, where the first vertex
19147 specifies the flat-shaded color.
19153 Primitive Type of Polygon @r{@var{i}}}
19170 Independent triangle
19183 Flat and smooth shading are specified by @code{glShadeModel} with
19184 @var{mode} set to @code{GL_FLAT} and @code{GL_SMOOTH}, respectively.
19186 @code{GL_INVALID_ENUM} is generated if @var{mode} is any value other
19187 than @code{GL_FLAT} or @code{GL_SMOOTH}.
19189 @code{GL_INVALID_OPERATION} is generated if @code{glShadeModel} is
19190 executed between the execution of @code{glBegin} and the corresponding
19191 execution of @code{glEnd}.
19195 @deftypefun void glShaderSource shader count string length
19196 Replaces the source code in a shader object.
19200 Specifies the handle of the shader object whose source code is to be
19204 Specifies the number of elements in the @var{string} and @var{length}
19208 Specifies an array of pointers to strings containing the source code to
19209 be loaded into the shader.
19212 Specifies an array of string lengths.
19216 @code{glShaderSource} sets the source code in @var{shader} to the source
19217 code in the array of strings specified by @var{string}. Any source code
19218 previously stored in the shader object is completely replaced. The
19219 number of strings in the array is specified by @var{count}. If
19220 @var{length} is @code{NULL}, each string is assumed to be null
19221 terminated. If @var{length} is a value other than @code{NULL}, it points
19222 to an array containing a string length for each of the corresponding
19223 elements of @var{string}. Each element in the @var{length} array may
19224 contain the length of the corresponding string (the null character is
19225 not counted as part of the string length) or a value less than 0 to
19226 indicate that the string is null terminated. The source code strings are
19227 not scanned or parsed at this time; they are simply copied into the
19228 specified shader object.
19230 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
19231 generated by OpenGL.
19233 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
19236 @code{GL_INVALID_VALUE} is generated if @var{count} is less than 0.
19238 @code{GL_INVALID_OPERATION} is generated if @code{glShaderSource} is
19239 executed between the execution of @code{glBegin} and the corresponding
19240 execution of @code{glEnd}.
19244 @deftypefun void glStencilFuncSeparate face func ref mask
19245 Set front and/or back function and reference value for stencil testing.
19249 Specifies whether front and/or back stencil state is updated. Three
19250 symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and
19251 @code{GL_FRONT_AND_BACK}.
19254 Specifies the test function. Eight symbolic constants are valid:
19255 @code{GL_NEVER}, @code{GL_LESS}, @code{GL_LEQUAL}, @code{GL_GREATER},
19256 @code{GL_GEQUAL}, @code{GL_EQUAL}, @code{GL_NOTEQUAL}, and
19257 @code{GL_ALWAYS}. The initial value is @code{GL_ALWAYS}.
19260 Specifies the reference value for the stencil test. @var{ref} is clamped
19261 to the range @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of
19262 bitplanes in the stencil buffer. The initial value is 0.
19265 Specifies a mask that is ANDed with both the reference value and the
19266 stored stencil value when the test is done. The initial value is all
19271 Stenciling, like depth-buffering, enables and disables drawing on a
19272 per-pixel basis. You draw into the stencil planes using GL drawing
19273 primitives, then render geometry and images, using the stencil planes to
19274 mask out portions of the screen. Stenciling is typically used in
19275 multipass rendering algorithms to achieve special effects, such as
19276 decals, outlining, and constructive solid geometry rendering.
19278 The stencil test conditionally eliminates a pixel based on the outcome
19279 of a comparison between the reference value and the value in the stencil
19280 buffer. To enable and disable the test, call @code{glEnable} and
19281 @code{glDisable} with argument @code{GL_STENCIL_TEST}. To specify
19282 actions based on the outcome of the stencil test, call
19283 @code{glStencilOp} or @code{glStencilOpSeparate}.
19285 There can be two separate sets of @var{func}, @var{ref}, and @var{mask}
19286 parameters; one affects back-facing polygons, and the other affects
19287 front-facing polygons as well as other non-polygon primitives.
19288 @code{glStencilFunc} sets both front and back stencil state to the same
19289 values, as if @code{glStencilFuncSeparate} were called with @var{face}
19290 set to @code{GL_FRONT_AND_BACK}.
19292 @var{func} is a symbolic constant that determines the stencil comparison
19293 function. It accepts one of eight values, shown in the following list.
19294 @var{ref} is an integer reference value that is used in the stencil
19295 comparison. It is clamped to the range @r{[0,2^@var{n}-1]}, where
19296 @r{@var{n}} is the number of bitplanes in the stencil buffer. @var{mask}
19297 is bitwise ANDed with both the reference value and the stored stencil
19298 value, with the ANDed values participating in the comparison.
19300 If @var{stencil} represents the value stored in the corresponding
19301 stencil buffer location, the following list shows the effect of each
19302 comparison function that can be specified by @var{func}. Only if the
19303 comparison succeeds is the pixel passed through to the next stage in the
19304 rasterization process (see @code{glStencilOp}). All tests treat
19305 @var{stencil} values as unsigned integers in the range
19306 @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of bitplanes in the
19309 The following values are accepted by @var{func}:
19312 @item @code{GL_NEVER}
19315 @item @code{GL_LESS}
19316 Passes if ( @var{ref} & @var{mask} ) < ( @var{stencil} & @var{mask} ).
19318 @item @code{GL_LEQUAL}
19319 Passes if ( @var{ref} & @var{mask} ) <= ( @var{stencil} & @var{mask} ).
19321 @item @code{GL_GREATER}
19322 Passes if ( @var{ref} & @var{mask} ) > ( @var{stencil} & @var{mask} ).
19324 @item @code{GL_GEQUAL}
19325 Passes if ( @var{ref} & @var{mask} ) >= ( @var{stencil} & @var{mask} ).
19327 @item @code{GL_EQUAL}
19328 Passes if ( @var{ref} & @var{mask} ) = ( @var{stencil} & @var{mask} ).
19330 @item @code{GL_NOTEQUAL}
19331 Passes if ( @var{ref} & @var{mask} ) != ( @var{stencil} & @var{mask} ).
19333 @item @code{GL_ALWAYS}
19338 @code{GL_INVALID_ENUM} is generated if @var{func} is not one of the
19339 eight accepted values.
19341 @code{GL_INVALID_OPERATION} is generated if @code{glStencilFuncSeparate}
19342 is executed between the execution of @code{glBegin} and the
19343 corresponding execution of @code{glEnd}.
19347 @deftypefun void glStencilFunc func ref mask
19348 Set front and back function and reference value for stencil testing.
19352 Specifies the test function. Eight symbolic constants are valid:
19353 @code{GL_NEVER}, @code{GL_LESS}, @code{GL_LEQUAL}, @code{GL_GREATER},
19354 @code{GL_GEQUAL}, @code{GL_EQUAL}, @code{GL_NOTEQUAL}, and
19355 @code{GL_ALWAYS}. The initial value is @code{GL_ALWAYS}.
19358 Specifies the reference value for the stencil test. @var{ref} is clamped
19359 to the range @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of
19360 bitplanes in the stencil buffer. The initial value is 0.
19363 Specifies a mask that is ANDed with both the reference value and the
19364 stored stencil value when the test is done. The initial value is all
19369 Stenciling, like depth-buffering, enables and disables drawing on a
19370 per-pixel basis. Stencil planes are first drawn into using GL drawing
19371 primitives, then geometry and images are rendered using the stencil
19372 planes to mask out portions of the screen. Stenciling is typically used
19373 in multipass rendering algorithms to achieve special effects, such as
19374 decals, outlining, and constructive solid geometry rendering.
19376 The stencil test conditionally eliminates a pixel based on the outcome
19377 of a comparison between the reference value and the value in the stencil
19378 buffer. To enable and disable the test, call @code{glEnable} and
19379 @code{glDisable} with argument @code{GL_STENCIL_TEST}. To specify
19380 actions based on the outcome of the stencil test, call
19381 @code{glStencilOp} or @code{glStencilOpSeparate}.
19383 There can be two separate sets of @var{func}, @var{ref}, and @var{mask}
19384 parameters; one affects back-facing polygons, and the other affects
19385 front-facing polygons as well as other non-polygon primitives.
19386 @code{glStencilFunc} sets both front and back stencil state to the same
19387 values. Use @code{glStencilFuncSeparate} to set front and back stencil
19388 state to different values.
19390 @var{func} is a symbolic constant that determines the stencil comparison
19391 function. It accepts one of eight values, shown in the following list.
19392 @var{ref} is an integer reference value that is used in the stencil
19393 comparison. It is clamped to the range @r{[0,2^@var{n}-1]}, where
19394 @r{@var{n}} is the number of bitplanes in the stencil buffer. @var{mask}
19395 is bitwise ANDed with both the reference value and the stored stencil
19396 value, with the ANDed values participating in the comparison.
19398 If @var{stencil} represents the value stored in the corresponding
19399 stencil buffer location, the following list shows the effect of each
19400 comparison function that can be specified by @var{func}. Only if the
19401 comparison succeeds is the pixel passed through to the next stage in the
19402 rasterization process (see @code{glStencilOp}). All tests treat
19403 @var{stencil} values as unsigned integers in the range
19404 @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of bitplanes in the
19407 The following values are accepted by @var{func}:
19410 @item @code{GL_NEVER}
19413 @item @code{GL_LESS}
19414 Passes if ( @var{ref} & @var{mask} ) < ( @var{stencil} & @var{mask} ).
19416 @item @code{GL_LEQUAL}
19417 Passes if ( @var{ref} & @var{mask} ) <= ( @var{stencil} & @var{mask} ).
19419 @item @code{GL_GREATER}
19420 Passes if ( @var{ref} & @var{mask} ) > ( @var{stencil} & @var{mask} ).
19422 @item @code{GL_GEQUAL}
19423 Passes if ( @var{ref} & @var{mask} ) >= ( @var{stencil} & @var{mask} ).
19425 @item @code{GL_EQUAL}
19426 Passes if ( @var{ref} & @var{mask} ) = ( @var{stencil} & @var{mask} ).
19428 @item @code{GL_NOTEQUAL}
19429 Passes if ( @var{ref} & @var{mask} ) != ( @var{stencil} & @var{mask} ).
19431 @item @code{GL_ALWAYS}
19436 @code{GL_INVALID_ENUM} is generated if @var{func} is not one of the
19437 eight accepted values.
19439 @code{GL_INVALID_OPERATION} is generated if @code{glStencilFunc} is
19440 executed between the execution of @code{glBegin} and the corresponding
19441 execution of @code{glEnd}.
19445 @deftypefun void glStencilMaskSeparate face mask
19446 Control the front and/or back writing of individual bits in the stencil
19451 Specifies whether the front and/or back stencil writemask is updated.
19452 Three symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and
19453 @code{GL_FRONT_AND_BACK}.
19456 Specifies a bit mask to enable and disable writing of individual bits in
19457 the stencil planes. Initially, the mask is all 1's.
19461 @code{glStencilMaskSeparate} controls the writing of individual bits in
19462 the stencil planes. The least significant @r{@var{n}} bits of
19463 @var{mask}, where @r{@var{n}} is the number of bits in the stencil
19464 buffer, specify a mask. Where a 1 appears in the mask, it's possible to
19465 write to the corresponding bit in the stencil buffer. Where a 0 appears,
19466 the corresponding bit is write-protected. Initially, all bits are
19467 enabled for writing.
19469 There can be two separate @var{mask} writemasks; one affects back-facing
19470 polygons, and the other affects front-facing polygons as well as other
19471 non-polygon primitives. @code{glStencilMask} sets both front and back
19472 stencil writemasks to the same values, as if
19473 @code{glStencilMaskSeparate} were called with @var{face} set to
19474 @code{GL_FRONT_AND_BACK}.
19476 @code{GL_INVALID_OPERATION} is generated if @code{glStencilMaskSeparate}
19477 is executed between the execution of @code{glBegin} and the
19478 corresponding execution of @code{glEnd}.
19482 @deftypefun void glStencilMask mask
19483 Control the front and back writing of individual bits in the stencil
19488 Specifies a bit mask to enable and disable writing of individual bits in
19489 the stencil planes. Initially, the mask is all 1's.
19493 @code{glStencilMask} controls the writing of individual bits in the
19494 stencil planes. The least significant @r{@var{n}} bits of @var{mask},
19495 where @r{@var{n}} is the number of bits in the stencil buffer, specify a
19496 mask. Where a 1 appears in the mask, it's possible to write to the
19497 corresponding bit in the stencil buffer. Where a 0 appears, the
19498 corresponding bit is write-protected. Initially, all bits are enabled
19501 There can be two separate @var{mask} writemasks; one affects back-facing
19502 polygons, and the other affects front-facing polygons as well as other
19503 non-polygon primitives. @code{glStencilMask} sets both front and back
19504 stencil writemasks to the same values. Use @code{glStencilMaskSeparate}
19505 to set front and back stencil writemasks to different values.
19507 @code{GL_INVALID_OPERATION} is generated if @code{glStencilMask} is
19508 executed between the execution of @code{glBegin} and the corresponding
19509 execution of @code{glEnd}.
19513 @deftypefun void glStencilOpSeparate face sfail dpfail dppass
19514 Set front and/or back stencil test actions.
19518 Specifies whether front and/or back stencil state is updated. Three
19519 symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and
19520 @code{GL_FRONT_AND_BACK}.
19523 Specifies the action to take when the stencil test fails. Eight symbolic
19524 constants are accepted: @code{GL_KEEP}, @code{GL_ZERO},
19525 @code{GL_REPLACE}, @code{GL_INCR}, @code{GL_INCR_WRAP}, @code{GL_DECR},
19526 @code{GL_DECR_WRAP}, and @code{GL_INVERT}. The initial value is
19530 Specifies the stencil action when the stencil test passes, but the depth
19531 test fails. @var{dpfail} accepts the same symbolic constants as
19532 @var{sfail}. The initial value is @code{GL_KEEP}.
19535 Specifies the stencil action when both the stencil test and the depth
19536 test pass, or when the stencil test passes and either there is no depth
19537 buffer or depth testing is not enabled. @var{dppass} accepts the same
19538 symbolic constants as @var{sfail}. The initial value is @code{GL_KEEP}.
19542 Stenciling, like depth-buffering, enables and disables drawing on a
19543 per-pixel basis. You draw into the stencil planes using GL drawing
19544 primitives, then render geometry and images, using the stencil planes to
19545 mask out portions of the screen. Stenciling is typically used in
19546 multipass rendering algorithms to achieve special effects, such as
19547 decals, outlining, and constructive solid geometry rendering.
19549 The stencil test conditionally eliminates a pixel based on the outcome
19550 of a comparison between the value in the stencil buffer and a reference
19551 value. To enable and disable the test, call @code{glEnable} and
19552 @code{glDisable} with argument @code{GL_STENCIL_TEST}; to control it,
19553 call @code{glStencilFunc} or @code{glStencilFuncSeparate}.
19555 There can be two separate sets of @var{sfail}, @var{dpfail}, and
19556 @var{dppass} parameters; one affects back-facing polygons, and the other
19557 affects front-facing polygons as well as other non-polygon primitives.
19558 @code{glStencilOp} sets both front and back stencil state to the same
19559 values, as if @code{glStencilOpSeparate} were called with @var{face} set
19560 to @code{GL_FRONT_AND_BACK}.
19562 @code{glStencilOpSeparate} takes three arguments that indicate what
19563 happens to the stored stencil value while stenciling is enabled. If the
19564 stencil test fails, no change is made to the pixel's color or depth
19565 buffers, and @var{sfail} specifies what happens to the stencil buffer
19566 contents. The following eight actions are possible.
19569 @item @code{GL_KEEP}
19570 Keeps the current value.
19572 @item @code{GL_ZERO}
19573 Sets the stencil buffer value to 0.
19575 @item @code{GL_REPLACE}
19576 Sets the stencil buffer value to @var{ref}, as specified by
19577 @code{glStencilFunc}.
19579 @item @code{GL_INCR}
19580 Increments the current stencil buffer value. Clamps to the maximum
19581 representable unsigned value.
19583 @item @code{GL_INCR_WRAP}
19584 Increments the current stencil buffer value. Wraps stencil buffer value
19585 to zero when incrementing the maximum representable unsigned value.
19587 @item @code{GL_DECR}
19588 Decrements the current stencil buffer value. Clamps to 0.
19590 @item @code{GL_DECR_WRAP}
19591 Decrements the current stencil buffer value. Wraps stencil buffer value
19592 to the maximum representable unsigned value when decrementing a stencil
19593 buffer value of zero.
19595 @item @code{GL_INVERT}
19596 Bitwise inverts the current stencil buffer value.
19600 Stencil buffer values are treated as unsigned integers. When incremented
19601 and decremented, values are clamped to 0 and @r{2^@var{n}-1}, where
19602 @r{@var{n}} is the value returned by querying @code{GL_STENCIL_BITS}.
19604 The other two arguments to @code{glStencilOpSeparate} specify stencil
19605 buffer actions that depend on whether subsequent depth buffer tests
19606 succeed (@var{dppass}) or fail (@var{dpfail}) (see @code{glDepthFunc}).
19607 The actions are specified using the same eight symbolic constants as
19608 @var{sfail}. Note that @var{dpfail} is ignored when there is no depth
19609 buffer, or when the depth buffer is not enabled. In these cases,
19610 @var{sfail} and @var{dppass} specify stencil action when the stencil
19611 test fails and passes, respectively.
19613 @code{GL_INVALID_ENUM} is generated if @var{face} is any value other
19614 than @code{GL_FRONT}, @code{GL_BACK}, or @code{GL_FRONT_AND_BACK}.
19616 @code{GL_INVALID_ENUM} is generated if @var{sfail}, @var{dpfail}, or
19617 @var{dppass} is any value other than the eight defined constant values.
19619 @code{GL_INVALID_OPERATION} is generated if @code{glStencilOpSeparate}
19620 is executed between the execution of @code{glBegin} and the
19621 corresponding execution of @code{glEnd}.
19625 @deftypefun void glStencilOp sfail dpfail dppass
19626 Set front and back stencil test actions.
19630 Specifies the action to take when the stencil test fails. Eight symbolic
19631 constants are accepted: @code{GL_KEEP}, @code{GL_ZERO},
19632 @code{GL_REPLACE}, @code{GL_INCR}, @code{GL_INCR_WRAP}, @code{GL_DECR},
19633 @code{GL_DECR_WRAP}, and @code{GL_INVERT}. The initial value is
19637 Specifies the stencil action when the stencil test passes, but the depth
19638 test fails. @var{dpfail} accepts the same symbolic constants as
19639 @var{sfail}. The initial value is @code{GL_KEEP}.
19642 Specifies the stencil action when both the stencil test and the depth
19643 test pass, or when the stencil test passes and either there is no depth
19644 buffer or depth testing is not enabled. @var{dppass} accepts the same
19645 symbolic constants as @var{sfail}. The initial value is @code{GL_KEEP}.
19649 Stenciling, like depth-buffering, enables and disables drawing on a
19650 per-pixel basis. You draw into the stencil planes using GL drawing
19651 primitives, then render geometry and images, using the stencil planes to
19652 mask out portions of the screen. Stenciling is typically used in
19653 multipass rendering algorithms to achieve special effects, such as
19654 decals, outlining, and constructive solid geometry rendering.
19656 The stencil test conditionally eliminates a pixel based on the outcome
19657 of a comparison between the value in the stencil buffer and a reference
19658 value. To enable and disable the test, call @code{glEnable} and
19659 @code{glDisable} with argument @code{GL_STENCIL_TEST}; to control it,
19660 call @code{glStencilFunc} or @code{glStencilFuncSeparate}.
19662 There can be two separate sets of @var{sfail}, @var{dpfail}, and
19663 @var{dppass} parameters; one affects back-facing polygons, and the other
19664 affects front-facing polygons as well as other non-polygon primitives.
19665 @code{glStencilOp} sets both front and back stencil state to the same
19666 values. Use @code{glStencilOpSeparate} to set front and back stencil
19667 state to different values.
19669 @code{glStencilOp} takes three arguments that indicate what happens to
19670 the stored stencil value while stenciling is enabled. If the stencil
19671 test fails, no change is made to the pixel's color or depth buffers, and
19672 @var{sfail} specifies what happens to the stencil buffer contents. The
19673 following eight actions are possible.
19676 @item @code{GL_KEEP}
19677 Keeps the current value.
19679 @item @code{GL_ZERO}
19680 Sets the stencil buffer value to 0.
19682 @item @code{GL_REPLACE}
19683 Sets the stencil buffer value to @var{ref}, as specified by
19684 @code{glStencilFunc}.
19686 @item @code{GL_INCR}
19687 Increments the current stencil buffer value. Clamps to the maximum
19688 representable unsigned value.
19690 @item @code{GL_INCR_WRAP}
19691 Increments the current stencil buffer value. Wraps stencil buffer value
19692 to zero when incrementing the maximum representable unsigned value.
19694 @item @code{GL_DECR}
19695 Decrements the current stencil buffer value. Clamps to 0.
19697 @item @code{GL_DECR_WRAP}
19698 Decrements the current stencil buffer value. Wraps stencil buffer value
19699 to the maximum representable unsigned value when decrementing a stencil
19700 buffer value of zero.
19702 @item @code{GL_INVERT}
19703 Bitwise inverts the current stencil buffer value.
19707 Stencil buffer values are treated as unsigned integers. When incremented
19708 and decremented, values are clamped to 0 and @r{2^@var{n}-1}, where
19709 @r{@var{n}} is the value returned by querying @code{GL_STENCIL_BITS}.
19711 The other two arguments to @code{glStencilOp} specify stencil buffer
19712 actions that depend on whether subsequent depth buffer tests succeed
19713 (@var{dppass}) or fail (@var{dpfail}) (see @code{glDepthFunc}). The
19714 actions are specified using the same eight symbolic constants as
19715 @var{sfail}. Note that @var{dpfail} is ignored when there is no depth
19716 buffer, or when the depth buffer is not enabled. In these cases,
19717 @var{sfail} and @var{dppass} specify stencil action when the stencil
19718 test fails and passes, respectively.
19720 @code{GL_INVALID_ENUM} is generated if @var{sfail}, @var{dpfail}, or
19721 @var{dppass} is any value other than the eight defined constant values.
19723 @code{GL_INVALID_OPERATION} is generated if @code{glStencilOp} is
19724 executed between the execution of @code{glBegin} and the corresponding
19725 execution of @code{glEnd}.
19729 @deftypefun void glTexCoordPointer size type stride pointer
19730 Define an array of texture coordinates.
19734 Specifies the number of coordinates per array element. Must be 1, 2, 3,
19735 or 4. The initial value is 4.
19738 Specifies the data type of each texture coordinate. Symbolic constants
19739 @code{GL_SHORT}, @code{GL_INT}, @code{GL_FLOAT}, or @code{GL_DOUBLE} are
19740 accepted. The initial value is @code{GL_FLOAT}.
19743 Specifies the byte offset between consecutive texture coordinate sets.
19744 If @var{stride} is 0, the array elements are understood to be tightly
19745 packed. The initial value is 0.
19747 @item @var{pointer}
19748 Specifies a pointer to the first coordinate of the first texture
19749 coordinate set in the array. The initial value is 0.
19753 @code{glTexCoordPointer} specifies the location and data format of an
19754 array of texture coordinates to use when rendering. @var{size} specifies
19755 the number of coordinates per texture coordinate set, and must be 1, 2,
19756 3, or 4. @var{type} specifies the data type of each texture coordinate,
19757 and @var{stride} specifies the byte stride from one texture coordinate
19758 set to the next, allowing vertices and attributes to be packed into a
19759 single array or stored in separate arrays. (Single-array storage may be
19760 more efficient on some implementations; see @code{glInterleavedArrays}.)
19762 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
19763 target (see @code{glBindBuffer}) while a texture coordinate array is
19764 specified, @var{pointer} is treated as a byte offset into the buffer
19765 object's data store. Also, the buffer object binding
19766 (@code{GL_ARRAY_BUFFER_BINDING}) is saved as texture coordinate vertex
19767 array client-side state (@code{GL_TEXTURE_COORD_ARRAY_BUFFER_BINDING}).
19769 When a texture coordinate array is specified, @var{size}, @var{type},
19770 @var{stride}, and @var{pointer} are saved as client-side state, in
19771 addition to the current vertex array buffer object binding.
19773 To enable and disable a texture coordinate array, call
19774 @code{glEnableClientState} and @code{glDisableClientState} with the
19775 argument @code{GL_TEXTURE_COORD_ARRAY}. If enabled, the texture
19776 coordinate array is used when @code{glArrayElement},
19777 @code{glDrawArrays}, @code{glMultiDrawArrays}, @code{glDrawElements},
19778 @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called.
19780 @code{GL_INVALID_VALUE} is generated if @var{size} is not 1, 2, 3, or 4.
19782 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
19785 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
19789 @deftypefun void glTexCoord1s s
19790 @deftypefunx void glTexCoord1i s
19791 @deftypefunx void glTexCoord1f s
19792 @deftypefunx void glTexCoord1d s
19793 @deftypefunx void glTexCoord2s s t
19794 @deftypefunx void glTexCoord2i s t
19795 @deftypefunx void glTexCoord2f s t
19796 @deftypefunx void glTexCoord2d s t
19797 @deftypefunx void glTexCoord3s s t r
19798 @deftypefunx void glTexCoord3i s t r
19799 @deftypefunx void glTexCoord3f s t r
19800 @deftypefunx void glTexCoord3d s t r
19801 @deftypefunx void glTexCoord4s s t r q
19802 @deftypefunx void glTexCoord4i s t r q
19803 @deftypefunx void glTexCoord4f s t r q
19804 @deftypefunx void glTexCoord4d s t r q
19805 @deftypefunx void glTexCoord1sv v
19806 @deftypefunx void glTexCoord1iv v
19807 @deftypefunx void glTexCoord1fv v
19808 @deftypefunx void glTexCoord1dv v
19809 @deftypefunx void glTexCoord2sv v
19810 @deftypefunx void glTexCoord2iv v
19811 @deftypefunx void glTexCoord2fv v
19812 @deftypefunx void glTexCoord2dv v
19813 @deftypefunx void glTexCoord3sv v
19814 @deftypefunx void glTexCoord3iv v
19815 @deftypefunx void glTexCoord3fv v
19816 @deftypefunx void glTexCoord3dv v
19817 @deftypefunx void glTexCoord4sv v
19818 @deftypefunx void glTexCoord4iv v
19819 @deftypefunx void glTexCoord4fv v
19820 @deftypefunx void glTexCoord4dv v
19821 Set the current texture coordinates.
19828 Specify @var{s}, @var{t}, @var{r}, and @var{q} texture coordinates. Not
19829 all parameters are present in all forms of the command.
19833 @code{glTexCoord} specifies texture coordinates in one, two, three, or
19834 four dimensions. @code{glTexCoord1} sets the current texture coordinates
19835 to @r{(@var{s},001)}; a call to @code{glTexCoord2} sets them to
19836 @r{(@var{s},@var{t}01)}. Similarly, @code{glTexCoord3} specifies the
19837 texture coordinates as @r{(@var{s},@var{t}@var{r}1)}, and
19838 @code{glTexCoord4} defines all four components explicitly as
19839 @r{(@var{s},@var{t}@var{r}@var{q})}.
19841 The current texture coordinates are part of the data that is associated
19842 with each vertex and with the current raster position. Initially, the
19843 values for @var{s}, @var{t}, @var{r}, and @var{q} are (0, 0, 0, 1).
19849 @deftypefun void glTexEnvf target pname param
19850 @deftypefunx void glTexEnvi target pname param
19851 @deftypefunx void glTexEnvfv target pname params
19852 @deftypefunx void glTexEnviv target pname params
19853 Set texture environment parameters.
19857 Specifies a texture environment. May be @code{GL_TEXTURE_ENV},
19858 @code{GL_TEXTURE_FILTER_CONTROL} or @code{GL_POINT_SPRITE}.
19861 Specifies the symbolic name of a single-valued texture environment
19862 parameter. May be either @code{GL_TEXTURE_ENV_MODE},
19863 @code{GL_TEXTURE_LOD_BIAS}, @code{GL_COMBINE_RGB},
19864 @code{GL_COMBINE_ALPHA}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB},
19865 @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA},
19866 @code{GL_SRC2_ALPHA}, @code{GL_OPERAND0_RGB}, @code{GL_OPERAND1_RGB},
19867 @code{GL_OPERAND2_RGB}, @code{GL_OPERAND0_ALPHA},
19868 @code{GL_OPERAND1_ALPHA}, @code{GL_OPERAND2_ALPHA}, @code{GL_RGB_SCALE},
19869 @code{GL_ALPHA_SCALE}, or @code{GL_COORD_REPLACE}.
19872 Specifies a single symbolic constant, one of @code{GL_ADD},
19873 @code{GL_ADD_SIGNED}, @code{GL_INTERPOLATE}, @code{GL_MODULATE},
19874 @code{GL_DECAL}, @code{GL_BLEND}, @code{GL_REPLACE}, @code{GL_SUBTRACT},
19875 @code{GL_COMBINE}, @code{GL_TEXTURE}, @code{GL_CONSTANT},
19876 @code{GL_PRIMARY_COLOR}, @code{GL_PREVIOUS}, @code{GL_SRC_COLOR},
19877 @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_SRC_ALPHA},
19878 @code{GL_ONE_MINUS_SRC_ALPHA}, a single boolean value for the point
19879 sprite texture coordinate replacement, a single floating-point value for
19880 the texture level-of-detail bias, or 1.0, 2.0, or 4.0 when specifying
19881 the @code{GL_RGB_SCALE} or @code{GL_ALPHA_SCALE}.
19885 A texture environment specifies how texture values are interpreted when
19886 a fragment is textured. When @var{target} is
19887 @code{GL_TEXTURE_FILTER_CONTROL}, @var{pname} must be
19888 @code{GL_TEXTURE_LOD_BIAS}. When @var{target} is @code{GL_TEXTURE_ENV},
19889 @var{pname} can be @code{GL_TEXTURE_ENV_MODE},
19890 @code{GL_TEXTURE_ENV_COLOR}, @code{GL_COMBINE_RGB},
19891 @code{GL_COMBINE_ALPHA}, @code{GL_RGB_SCALE}, @code{GL_ALPHA_SCALE},
19892 @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, @code{GL_SRC2_RGB},
19893 @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, or @code{GL_SRC2_ALPHA}.
19895 If @var{pname} is @code{GL_TEXTURE_ENV_MODE}, then @var{params} is (or
19896 points to) the symbolic name of a texture function. Six texture
19897 functions may be specified: @code{GL_ADD}, @code{GL_MODULATE},
19898 @code{GL_DECAL}, @code{GL_BLEND}, @code{GL_REPLACE}, or
19901 The following table shows the correspondence of filtered texture values
19902 @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}},
19903 @r{@var{A}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{I}_@var{t}} to texture
19904 source components. @r{@var{C}_@var{s}} and @r{@var{A}_@var{s}} are used
19905 by the texture functions described below.
19911 Texture Base Internal Format
19912 @r{@code{C}_@var{s}}, @r{@code{A}_@var{s}}
19914 @item @code{GL_ALPHA}
19915 (0, 0, 0) , @r{@var{A}_@var{t}}
19917 @item @code{GL_LUMINANCE}
19918 ( @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}} ) , 1
19920 @item @code{GL_LUMINANCE_ALPHA}
19921 ( @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}} ) ,
19922 @r{@var{A}_@var{t}}
19924 @item @code{GL_INTENSITY}
19925 ( @r{@var{I}_@var{t}}, @r{@var{I}_@var{t}}, @r{@var{I}_@var{t}} ) ,
19926 @r{@var{I}_@var{t}}
19928 @item @code{GL_RGB}
19929 ( @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}} ) , 1
19931 @item @code{GL_RGBA}
19932 ( @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}} ) ,
19933 @r{@var{A}_@var{t}}
19937 A texture function acts on the fragment to be textured using the texture
19938 image value that applies to the fragment (see @code{glTexParameter}) and
19939 produces an RGBA color for that fragment. The following table shows how
19940 the RGBA color is produced for each of the first five texture functions
19941 that can be chosen. @r{@var{C}} is a triple of color values (RGB) and
19942 @r{@var{A}} is the associated alpha value. RGBA values extracted from a
19943 texture image are in the range [0,1]. The subscript @r{@var{p}} refers
19944 to the color computed from the previous texture stage (or the incoming
19945 fragment if processing texture stage 0), the subscript @r{@var{s}} to
19946 the texture source color, the subscript @r{@var{c}} to the texture
19947 environment color, and the subscript @r{@var{v}} indicates a value
19948 produced by the texture function.
19954 Texture Base Internal Format
19955 @code{Value}, @code{GL_REPLACE} Function , @code{GL_MODULATE} Function ,
19956 @code{GL_DECAL} Function , @code{GL_BLEND} Function , @code{GL_ADD}
19959 @item @code{GL_ALPHA}
19960 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{p}}, @r{@var{C}_@var{p}},
19961 undefined , @r{@var{C}_@var{p}}, @r{@var{C}_@var{p}}
19964 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}},
19965 @r{@var{A}_@var{p}@var{A}_@var{s}}, ,
19966 @r{@var{A}_@var{v}=@var{A}_@var{p}@var{A}_@var{s}},
19967 @r{@var{A}_@var{p}@var{A}_@var{s}}
19969 @item @code{GL_LUMINANCE}
19970 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
19971 @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined ,
19972 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
19973 @r{@var{C}_@var{p}+@var{C}_@var{s}}
19977 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, ,
19978 @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}
19980 @item @code{GL_LUMINANCE_ALPHA}
19981 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
19982 @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined ,
19983 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
19984 @r{@var{C}_@var{p}+@var{C}_@var{s}}
19988 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}},
19989 @r{@var{A}_@var{p}@var{A}_@var{s}}, ,
19990 @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}@var{A}_@var{s}}
19992 @item @code{GL_INTENSITY}
19993 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
19994 @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined ,
19995 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
19996 @r{@var{C}_@var{p}+@var{C}_@var{s}}
19999 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}},
20000 @r{@var{A}_@var{p}@var{A}_@var{s}}, ,
20001 @r{@var{A}_@var{p}(1-@var{A}_@var{s},)+@var{A}_@var{c}@var{A}_@var{s}},
20002 @r{@var{A}_@var{p}+@var{A}_@var{s}}
20004 @item @code{GL_RGB}
20005 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
20006 @r{@var{C}_@var{p}@var{C}_@var{s}}, @r{@var{C}_@var{s}},
20007 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
20008 @r{@var{C}_@var{p}+@var{C}_@var{s}}
20012 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}},
20013 @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}
20015 @item @code{GL_RGBA}
20016 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
20017 @r{@var{C}_@var{p}@var{C}_@var{s}},
20018 @r{@var{C}_@var{p}(1-@var{A}_@var{s},)+@var{C}_@var{s}@var{A}_@var{s}},
20019 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
20020 @r{@var{C}_@var{p}+@var{C}_@var{s}}
20024 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}},
20025 @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}},
20026 @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}@var{A}_@var{s}}
20030 If @var{pname} is @code{GL_TEXTURE_ENV_MODE}, and @var{params} is
20031 @code{GL_COMBINE}, the form of the texture function depends on the
20032 values of @code{GL_COMBINE_RGB} and @code{GL_COMBINE_ALPHA}.
20034 The following describes how the texture sources, as specified by
20035 @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, @code{GL_SRC2_RGB},
20036 @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, and @code{GL_SRC2_ALPHA},
20037 are combined to produce a final texture color. In the following tables,
20038 @code{GL_SRC0_c} is represented by @r{@var{Arg0}}, @code{GL_SRC1_c} is
20039 represented by @r{@var{Arg1}}, and @code{GL_SRC2_c} is represented by
20042 @code{GL_COMBINE_RGB} accepts any of @code{GL_REPLACE},
20043 @code{GL_MODULATE}, @code{GL_ADD}, @code{GL_ADD_SIGNED},
20044 @code{GL_INTERPOLATE}, @code{GL_SUBTRACT}, @code{GL_DOT3_RGB}, or
20045 @code{GL_DOT3_RGBA}.
20050 @item @strong{@code{GL_COMBINE_RGB}}
20051 @strong{Texture Function}
20053 @item @code{GL_REPLACE}
20056 @item @code{GL_MODULATE}
20057 @r{@var{Arg0}×@var{Arg1}}
20059 @item @code{GL_ADD}
20060 @r{@var{Arg0}+@var{Arg1}}
20062 @item @code{GL_ADD_SIGNED}
20063 @r{@var{Arg0}+@var{Arg1}-0.5}
20065 @item @code{GL_INTERPOLATE}
20066 @r{@var{Arg0}×@var{Arg2}+@var{Arg1}×(1-@var{Arg2},)}
20068 @item @code{GL_SUBTRACT}
20069 @r{@var{Arg0}-@var{Arg1}}
20071 @item @code{GL_DOT3_RGB}
20072 or @code{GL_DOT3_RGBA}
20073 @r{4×(((@var{Arg0}_@var{r},-0.5,)×(@var{Arg1}_@var{r},-0.5,),)+((@var{Arg0}_@var{g},-0.5,)×(@var{Arg1}_@var{g},-0.5,),)+((@var{Arg0}_@var{b},-0.5,)×(@var{Arg1}_@var{b},-0.5,),),)}
20077 The scalar results for @code{GL_DOT3_RGB} and @code{GL_DOT3_RGBA} are
20078 placed into each of the 3 (RGB) or 4 (RGBA) components on output.
20080 Likewise, @code{GL_COMBINE_ALPHA} accepts any of @code{GL_REPLACE},
20081 @code{GL_MODULATE}, @code{GL_ADD}, @code{GL_ADD_SIGNED},
20082 @code{GL_INTERPOLATE}, or @code{GL_SUBTRACT}. The following table
20083 describes how alpha values are combined:
20088 @item @strong{@code{GL_COMBINE_ALPHA}}
20089 @strong{Texture Function}
20091 @item @code{GL_REPLACE}
20094 @item @code{GL_MODULATE}
20095 @r{@var{Arg0}×@var{Arg1}}
20097 @item @code{GL_ADD}
20098 @r{@var{Arg0}+@var{Arg1}}
20100 @item @code{GL_ADD_SIGNED}
20101 @r{@var{Arg0}+@var{Arg1}-0.5}
20103 @item @code{GL_INTERPOLATE}
20104 @r{@var{Arg0}×@var{Arg2}+@var{Arg1}×(1-@var{Arg2},)}
20106 @item @code{GL_SUBTRACT}
20107 @r{@var{Arg0}-@var{Arg1}}
20111 In the following tables, the value @r{@var{C}_@var{s}} represents the
20112 color sampled from the currently bound texture, @r{@var{C}_@var{c}}
20113 represents the constant texture-environment color, @r{@var{C}_@var{f}}
20114 represents the primary color of the incoming fragment, and
20115 @r{@var{C}_@var{p}} represents the color computed from the previous
20116 texture stage or @r{@var{C}_@var{f}} if processing texture stage 0.
20117 Likewise, @r{@var{A}_@var{s}}, @r{@var{A}_@var{c}}, @r{@var{A}_@var{f}},
20118 and @r{@var{A}_@var{p}} represent the respective alpha values.
20120 The following table describes the values assigned to @r{@var{Arg0}},
20121 @r{@var{Arg1}}, and @r{@var{Arg2}} based upon the RGB sources and
20127 @item @strong{@code{GL_SRCn_RGB}}
20128 @strong{@code{GL_OPERANDn_RGB}}, @strong{Argument Value}
20130 @item @code{GL_TEXTURE}
20131 @code{GL_SRC_COLOR}, @r{@var{C}_@var{s},}
20134 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{s},}
20137 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},}
20140 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},}
20142 @item @code{GL_TEXTUREn}
20143 @code{GL_SRC_COLOR}, @r{@var{C}_@var{s},}
20146 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{s},}
20149 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},}
20152 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},}
20154 @item @code{GL_CONSTANT}
20155 @code{GL_SRC_COLOR}, @r{@var{C}_@var{c},}
20158 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{c},}
20161 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{c},}
20164 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{c},}
20166 @item @code{GL_PRIMARY_COLOR}
20167 @code{GL_SRC_COLOR}, @r{@var{C}_@var{f},}
20170 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{f},}
20173 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{f},}
20176 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{f},}
20178 @item @code{GL_PREVIOUS}
20179 @code{GL_SRC_COLOR}, @r{@var{C}_@var{p},}
20182 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{p},}
20185 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{p},}
20188 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{p},}
20192 For @code{GL_TEXTUREn} sources, @r{@var{C}_@var{s}} and
20193 @r{@var{A}_@var{s}} represent the color and alpha, respectively,
20194 produced from texture stage @r{@var{n}}.
20196 The follow table describes the values assigned to @r{@var{Arg0}},
20197 @r{@var{Arg1}}, and @r{@var{Arg2}} based upon the alpha sources and
20203 @item @strong{@code{GL_SRCn_ALPHA}}
20204 @strong{@code{GL_OPERANDn_ALPHA}}, @strong{Argument Value}
20206 @item @code{GL_TEXTURE}
20207 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},}
20210 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},}
20212 @item @code{GL_TEXTUREn}
20213 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},}
20216 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},}
20218 @item @code{GL_CONSTANT}
20219 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{c},}
20222 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{c},}
20224 @item @code{GL_PRIMARY_COLOR}
20225 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{f},}
20228 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{f},}
20230 @item @code{GL_PREVIOUS}
20231 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{p},}
20234 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{p},}
20238 The RGB and alpha results of the texture function are multipled by the
20239 values of @code{GL_RGB_SCALE} and @code{GL_ALPHA_SCALE}, respectively,
20240 and clamped to the range @r{[0,1]}.
20242 If @var{pname} is @code{GL_TEXTURE_ENV_COLOR}, @var{params} is a pointer
20243 to an array that holds an RGBA color consisting of four values. Integer
20244 color components are interpreted linearly such that the most positive
20245 integer maps to 1.0, and the most negative integer maps to -1.0. The
20246 values are clamped to the range [0,1] when they are specified.
20247 @r{@var{C}_@var{c}} takes these four values.
20249 If @var{pname} is @code{GL_TEXTURE_LOD_BIAS}, the value specified is
20250 added to the texture level-of-detail parameter, that selects which
20251 mipmap, or mipmaps depending upon the selected
20252 @code{GL_TEXTURE_MIN_FILTER}, will be sampled.
20254 @code{GL_TEXTURE_ENV_MODE} defaults to @code{GL_MODULATE} and
20255 @code{GL_TEXTURE_ENV_COLOR} defaults to (0, 0, 0, 0).
20257 If @var{target} is @code{GL_POINT_SPRITE} and @var{pname} is
20258 @code{GL_COORD_REPLACE}, the boolean value specified is used to either
20259 enable or disable point sprite texture coordinate replacement. The
20260 default value is @code{GL_FALSE}.
20262 @code{GL_INVALID_ENUM} is generated when @var{target} or @var{pname} is
20263 not one of the accepted defined values, or when @var{params} should have
20264 a defined constant value (based on the value of @var{pname}) and does
20267 @code{GL_INVALID_VALUE} is generated if the @var{params} value for
20268 @code{GL_RGB_SCALE} or @code{GL_ALPHA_SCALE} are not one of 1.0, 2.0, or
20271 @code{GL_INVALID_OPERATION} is generated if @code{glTexEnv} is executed
20272 between the execution of @code{glBegin} and the corresponding execution
20277 @deftypefun void glTexGeni coord pname param
20278 @deftypefunx void glTexGenf coord pname param
20279 @deftypefunx void glTexGend coord pname param
20280 @deftypefunx void glTexGeniv coord pname params
20281 @deftypefunx void glTexGenfv coord pname params
20282 @deftypefunx void glTexGendv coord pname params
20283 Control the generation of texture coordinates.
20287 Specifies a texture coordinate. Must be one of @code{GL_S}, @code{GL_T},
20288 @code{GL_R}, or @code{GL_Q}.
20291 Specifies the symbolic name of the texture-coordinate generation
20292 function. Must be @code{GL_TEXTURE_GEN_MODE}.
20295 Specifies a single-valued texture generation parameter, one of
20296 @code{GL_OBJECT_LINEAR}, @code{GL_EYE_LINEAR}, @code{GL_SPHERE_MAP},
20297 @code{GL_NORMAL_MAP}, or @code{GL_REFLECTION_MAP}.
20301 @code{glTexGen} selects a texture-coordinate generation function or
20302 supplies coefficients for one of the functions. @var{coord} names one of
20303 the (@var{s}, @var{t}, @var{r}, @var{q}) texture coordinates; it must be
20304 one of the symbols @code{GL_S}, @code{GL_T}, @code{GL_R}, or
20305 @code{GL_Q}. @var{pname} must be one of three symbolic constants:
20306 @code{GL_TEXTURE_GEN_MODE}, @code{GL_OBJECT_PLANE}, or
20307 @code{GL_EYE_PLANE}. If @var{pname} is @code{GL_TEXTURE_GEN_MODE}, then
20308 @var{params} chooses a mode, one of @code{GL_OBJECT_LINEAR},
20309 @code{GL_EYE_LINEAR}, @code{GL_SPHERE_MAP}, @code{GL_NORMAL_MAP}, or
20310 @code{GL_REFLECTION_MAP}. If @var{pname} is either
20311 @code{GL_OBJECT_PLANE} or @code{GL_EYE_PLANE}, @var{params} contains
20312 coefficients for the corresponding texture generation function.
20314 If the texture generation function is @code{GL_OBJECT_LINEAR}, the
20317 @r{@var{g}=@var{p}_1×@var{x}_@var{o}+@var{p}_2×@var{y}_@var{o}+@var{p}_3×@var{z}_@var{o}+@var{p}_4×@var{w}_@var{o}}
20319 is used, where @r{@var{g}} is the value computed for the coordinate
20320 named in @var{coord}, @r{@var{p}_1}, @r{@var{p}_2}, @r{@var{p}_3}, and
20321 @r{@var{p}_4} are the four values supplied in @var{params}, and
20322 @r{@var{x}_@var{o}}, @r{@var{y}_@var{o}}, @r{@var{z}_@var{o}}, and
20323 @r{@var{w}_@var{o}} are the object coordinates of the vertex. This
20324 function can be used, for example, to texture-map terrain using sea
20325 level as a reference plane (defined by @r{@var{p}_1}, @r{@var{p}_2},
20326 @r{@var{p}_3}, and @r{@var{p}_4}). The altitude of a terrain vertex is
20327 computed by the @code{GL_OBJECT_LINEAR} coordinate generation function
20328 as its distance from sea level; that altitude can then be used to index
20329 the texture image to map white snow onto peaks and green grass onto
20332 If the texture generation function is @code{GL_EYE_LINEAR}, the function
20334 @r{@var{g}=@var{p}_1,^″×@var{x}_@var{e}+@var{p}_2,^″×@var{y}_@var{e}+@var{p}_3,^″×@var{z}_@var{e}+@var{p}_4,^″×@var{w}_@var{e}}
20338 @r{(@var{p}_1,^″@var{p}_2,^″@var{p}_3,^″@var{p}_4,^″,)=(@var{p}_1@var{p}_2@var{p}_3@var{p}_4,)@var{M}^-1}
20340 and @r{@var{x}_@var{e}}, @r{@var{y}_@var{e}}, @r{@var{z}_@var{e}}, and
20341 @r{@var{w}_@var{e}} are the eye coordinates of the vertex,
20342 @r{@var{p}_1}, @r{@var{p}_2}, @r{@var{p}_3}, and @r{@var{p}_4} are the
20343 values supplied in @var{params}, and @r{@var{M}} is the modelview matrix
20344 when @code{glTexGen} is invoked. If @r{@var{M}} is poorly conditioned or
20345 singular, texture coordinates generated by the resulting function may be
20346 inaccurate or undefined.
20348 Note that the values in @var{params} define a reference plane in eye
20349 coordinates. The modelview matrix that is applied to them may not be the
20350 same one in effect when the polygon vertices are transformed. This
20351 function establishes a field of texture coordinates that can produce
20352 dynamic contour lines on moving objects.
20354 If the texture generation function is @code{GL_SPHERE_MAP} and
20355 @var{coord} is either @code{GL_S} or @code{GL_T}, @r{@var{s}} and
20356 @r{@var{t}} texture coordinates are generated as follows. Let @var{u} be
20357 the unit vector pointing from the origin to the polygon vertex (in eye
20358 coordinates). Let @var{n} sup prime be the current normal, after
20359 transformation to eye coordinates. Let
20361 @r{@var{f}=(@var{f}_@var{x}@var{f}_@var{y}@var{f}_@var{z},)^@var{T}}
20362 be the reflection vector such that
20364 @r{@var{f}=@var{u}-2@var{n}^″@var{n}^″,^@var{T}@var{u}}
20367 @r{@var{m}=2√(@var{f}_@var{x},^2+@var{f}_@var{y},^2+(@var{f}_@var{z}+1,)^2,)}.
20368 Then the values assigned to the @r{@var{s}} and @r{@var{t}} texture
20371 @r{@var{s}=@var{f}_@var{x}/@var{m}+1/2}
20373 @r{@var{t}=@var{f}_@var{y}/@var{m}+1/2}
20375 To enable or disable a texture-coordinate generation function, call
20376 @code{glEnable} or @code{glDisable} with one of the symbolic
20377 texture-coordinate names (@code{GL_TEXTURE_GEN_S},
20378 @code{GL_TEXTURE_GEN_T}, @code{GL_TEXTURE_GEN_R}, or
20379 @code{GL_TEXTURE_GEN_Q}) as the argument. When enabled, the specified
20380 texture coordinate is computed according to the generating function
20381 associated with that coordinate. When disabled, subsequent vertices take
20382 the specified texture coordinate from the current set of texture
20383 coordinates. Initially, all texture generation functions are set to
20384 @code{GL_EYE_LINEAR} and are disabled. Both @r{@var{s}} plane equations
20385 are (1, 0, 0, 0), both @r{@var{t}} plane equations are (0, 1, 0, 0), and
20386 all @r{@var{r}} and @r{@var{q}} plane equations are (0, 0, 0, 0).
20388 When the @code{ARB_multitexture} extension is supported, @code{glTexGen}
20389 sets the texture generation parameters for the currently active texture
20390 unit, selected with @code{glActiveTexture}.
20392 @code{GL_INVALID_ENUM} is generated when @var{coord} or @var{pname} is
20393 not an accepted defined value, or when @var{pname} is
20394 @code{GL_TEXTURE_GEN_MODE} and @var{params} is not an accepted defined
20397 @code{GL_INVALID_ENUM} is generated when @var{pname} is
20398 @code{GL_TEXTURE_GEN_MODE}, @var{params} is @code{GL_SPHERE_MAP}, and
20399 @var{coord} is either @code{GL_R} or @code{GL_Q}.
20401 @code{GL_INVALID_OPERATION} is generated if @code{glTexGen} is executed
20402 between the execution of @code{glBegin} and the corresponding execution
20407 @deftypefun void glTexImage1D target level internalFormat width border format type data
20408 Specify a one-dimensional texture image.
20412 Specifies the target texture. Must be @code{GL_TEXTURE_1D} or
20413 @code{GL_PROXY_TEXTURE_1D}.
20416 Specifies the level-of-detail number. Level 0 is the base image level.
20417 Level @var{n} is the @var{n}th mipmap reduction image.
20419 @item @var{internalFormat}
20420 Specifies the number of color components in the texture. Must be 1, 2,
20421 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA},
20422 @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
20423 @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA},
20424 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
20425 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
20426 @code{GL_COMPRESSED_RGBA}, @code{GL_DEPTH_COMPONENT},
20427 @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24},
20428 @code{GL_DEPTH_COMPONENT32}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
20429 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
20430 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
20431 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
20432 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
20433 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY},
20434 @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12},
20435 @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
20436 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
20437 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
20438 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
20439 @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE},
20440 @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
20441 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
20442 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
20445 Specifies the width of the texture image including the border if any. If
20446 the GL version does not support non-power-of-two sizes, this value must
20447 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
20448 implementations support texture images that are at least 64 texels wide.
20449 The height of the 1D texture image is 1.
20452 Specifies the width of the border. Must be either 0 or 1.
20455 Specifies the format of the pixel data. The following symbolic values
20456 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
20457 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
20458 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
20459 @code{GL_LUMINANCE_ALPHA}.
20462 Specifies the data type of the pixel data. The following symbolic values
20463 are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
20464 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
20465 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
20466 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
20467 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
20468 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
20469 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
20470 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
20471 and @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
20474 Specifies a pointer to the image data in memory.
20478 Texturing maps a portion of a specified texture image onto each
20479 graphical primitive for which texturing is enabled. To enable and
20480 disable one-dimensional texturing, call @code{glEnable} and
20481 @code{glDisable} with argument @code{GL_TEXTURE_1D}.
20483 Texture images are defined with @code{glTexImage1D}. The arguments
20484 describe the parameters of the texture image, such as width, width of
20485 the border, level-of-detail number (see @code{glTexParameter}), and the
20486 internal resolution and format used to store the image. The last three
20487 arguments describe how the image is represented in memory; they are
20488 identical to the pixel formats used for @code{glDrawPixels}.
20490 If @var{target} is @code{GL_PROXY_TEXTURE_1D}, no data is read from
20491 @var{data}, but all of the texture image state is recalculated, checked
20492 for consistency, and checked against the implementation's capabilities.
20493 If the implementation cannot handle a texture of the requested texture
20494 size, it sets all of the image state to 0, but does not generate an
20495 error (see @code{glGetError}). To query for an entire mipmap array, use
20496 an image array level greater than or equal to 1.
20498 If @var{target} is @code{GL_TEXTURE_1D}, data is read from @var{data} as
20499 a sequence of signed or unsigned bytes, shorts, or longs, or
20500 single-precision floating-point values, depending on @var{type}. These
20501 values are grouped into sets of one, two, three, or four values,
20502 depending on @var{format}, to form elements. If @var{type} is
20503 @code{GL_BITMAP}, the data is considered as a string of unsigned bytes
20504 (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is
20505 treated as eight 1-bit elements, with bit ordering determined by
20506 @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}).
20508 If a non-zero named buffer object is bound to the
20509 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
20510 texture image is specified, @var{data} is treated as a byte offset into
20511 the buffer object's data store.
20513 The first element corresponds to the left end of the texture array.
20514 Subsequent elements progress left-to-right through the remaining texels
20515 in the texture array. The final element corresponds to the right end of
20518 @var{format} determines the composition of each element in @var{data}.
20519 It can assume one of these symbolic values:
20522 @item @code{GL_COLOR_INDEX}
20523 Each element is a single value, a color index. The GL converts it to
20524 fixed point (with an unspecified number of zero bits to the right of the
20525 binary point), shifted left or right depending on the value and sign of
20526 @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see
20527 @code{glPixelTransfer}). The resulting index is converted to a set of
20528 color components using the @code{GL_PIXEL_MAP_I_TO_R},
20529 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
20530 @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1].
20532 @item @code{GL_RED}
20533 Each element is a single red component. The GL converts it to floating
20534 point and assembles it into an RGBA element by attaching 0 for green and
20535 blue, and 1 for alpha. Each component is then multiplied by the signed
20536 scale factor @code{GL_c_SCALE}, added to the signed bias
20537 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20538 @code{glPixelTransfer}).
20540 @item @code{GL_GREEN}
20541 Each element is a single green component. The GL converts it to floating
20542 point and assembles it into an RGBA element by attaching 0 for red and
20543 blue, and 1 for alpha. Each component is then multiplied by the signed
20544 scale factor @code{GL_c_SCALE}, added to the signed bias
20545 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20546 @code{glPixelTransfer}).
20548 @item @code{GL_BLUE}
20549 Each element is a single blue component. The GL converts it to floating
20550 point and assembles it into an RGBA element by attaching 0 for red and
20551 green, and 1 for alpha. Each component is then multiplied by the signed
20552 scale factor @code{GL_c_SCALE}, added to the signed bias
20553 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20554 @code{glPixelTransfer}).
20556 @item @code{GL_ALPHA}
20557 Each element is a single alpha component. The GL converts it to floating
20558 point and assembles it into an RGBA element by attaching 0 for red,
20559 green, and blue. Each component is then multiplied by the signed scale
20560 factor @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20561 clamped to the range [0,1] (see @code{glPixelTransfer}).
20563 @item @code{GL_INTENSITY}
20564 Each element is a single intensity value. The GL converts it to floating
20565 point, then assembles it into an RGBA element by replicating the
20566 intensity value three times for red, green, blue, and alpha. Each
20567 component is then multiplied by the signed scale factor
20568 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20569 clamped to the range [0,1] (see @code{glPixelTransfer}).
20571 @item @code{GL_RGB}
20572 @item @code{GL_BGR}
20573 Each element is an RGB triple. The GL converts it to floating point and
20574 assembles it into an RGBA element by attaching 1 for alpha. Each
20575 component is then multiplied by the signed scale factor
20576 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20577 clamped to the range [0,1] (see @code{glPixelTransfer}).
20579 @item @code{GL_RGBA}
20580 @item @code{GL_BGRA}
20581 Each element contains all four components. Each component is multiplied
20582 by the signed scale factor @code{GL_c_SCALE}, added to the signed bias
20583 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20584 @code{glPixelTransfer}).
20586 @item @code{GL_LUMINANCE}
20587 Each element is a single luminance value. The GL converts it to floating
20588 point, then assembles it into an RGBA element by replicating the
20589 luminance value three times for red, green, and blue and attaching 1 for
20590 alpha. Each component is then multiplied by the signed scale factor
20591 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20592 clamped to the range [0,1] (see @code{glPixelTransfer}).
20594 @item @code{GL_LUMINANCE_ALPHA}
20595 Each element is a luminance/alpha pair. The GL converts it to floating
20596 point, then assembles it into an RGBA element by replicating the
20597 luminance value three times for red, green, and blue. Each component is
20598 then multiplied by the signed scale factor @code{GL_c_SCALE}, added to
20599 the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20600 @code{glPixelTransfer}).
20602 @item @code{GL_DEPTH_COMPONENT}
20603 Each element is a single depth value. The GL converts it to floating
20604 point, multiplies by the signed scale factor @code{GL_DEPTH_SCALE}, adds
20605 the signed bias @code{GL_DEPTH_BIAS}, and clamps to the range [0,1] (see
20606 @code{glPixelTransfer}).
20610 Refer to the @code{glDrawPixels} reference page for a description of the
20611 acceptable values for the @var{type} parameter.
20613 If an application wants to store the texture at a certain resolution or
20614 in a certain format, it can request the resolution and format with
20615 @var{internalFormat}. The GL will choose an internal representation that
20616 closely approximates that requested by @var{internalFormat}, but it may
20617 not match exactly. (The representations specified by
20618 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and
20619 @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 may
20620 also be used to specify the above representations.)
20622 If the @var{internalFormat} parameter is one of the generic compressed
20623 formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
20624 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
20625 @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will
20626 replace the internal format with the symbolic constant for a specific
20627 internal format and compress the texture before storage. If no
20628 corresponding internal format is available, or the GL can not compress
20629 that image for any reason, the internal format is instead replaced with
20630 a corresponding base internal format.
20632 If the @var{internalFormat} parameter is @code{GL_SRGB},
20633 @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8},
20634 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
20635 or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red,
20636 green, blue, or luminance components are encoded in the sRGB color
20637 space. Any alpha component is left unchanged. The conversion from the
20638 sRGB encoded component @r{@var{c}_@var{s}} to a linear component
20639 @r{@var{c}_@var{l}} is:
20641 @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045),
20642 ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)}
20644 Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1].
20646 Use the @code{GL_PROXY_TEXTURE_1D} target to try out a resolution and
20647 format. The implementation will update and recompute its best match for
20648 the requested storage resolution and format. To then query this state,
20649 call @code{glGetTexLevelParameter}. If the texture cannot be
20650 accommodated, texture state is set to 0.
20652 A one-component texture image uses only the red component of the RGBA
20653 color from @var{data}. A two-component image uses the R and A values. A
20654 three-component image uses the R, G, and B values. A four-component
20655 image uses all of the RGBA components.
20657 Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA textures
20658 during texture filtering and application. Image-based shadowing can be
20659 enabled by comparing texture r coordinates to depth texture values to
20660 generate a boolean result. See @code{glTexParameter} for details on
20661 texture comparison.
20663 @code{GL_INVALID_ENUM} is generated if @var{target} is not
20664 @code{GL_TEXTURE_1D} or @code{GL_PROXY_TEXTURE_1D}.
20666 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
20667 format constant. Format constants other than @code{GL_STENCIL_INDEX} are
20670 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
20673 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
20674 and @var{format} is not @code{GL_COLOR_INDEX}.
20676 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
20678 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
20679 @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of
20680 @code{GL_MAX_TEXTURE_SIZE}.
20682 @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1,
20683 2, 3, 4, or one of the accepted resolution and format symbolic
20686 @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or
20687 greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
20689 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
20690 not supported and the @var{width} cannot be represented as
20691 @r{2^@var{n}+2(@var{border},)} for some integer value of @var{n}.
20693 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
20695 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
20696 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
20697 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
20698 and @var{format} is not @code{GL_RGB}.
20700 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
20701 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
20702 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
20703 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
20704 @code{GL_UNSIGNED_INT_10_10_10_2}, or
20705 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
20706 @code{GL_RGBA} nor @code{GL_BGRA}.
20708 @code{GL_INVALID_OPERATION} is generated if @var{format} is
20709 @code{GL_DEPTH_COMPONENT} and @var{internalFormat} is not
20710 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
20711 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}.
20713 @code{GL_INVALID_OPERATION} is generated if @var{internalFormat} is
20714 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
20715 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}, and
20716 @var{format} is not @code{GL_DEPTH_COMPONENT}.
20718 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
20719 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
20720 object's data store is currently mapped.
20722 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
20723 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
20724 would be unpacked from the buffer object such that the memory reads
20725 required would exceed the data store size.
20727 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
20728 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
20729 is not evenly divisible into the number of bytes needed to store in
20730 memory a datum indicated by @var{type}.
20732 @code{GL_INVALID_OPERATION} is generated if @code{glTexImage1D} is
20733 executed between the execution of @code{glBegin} and the corresponding
20734 execution of @code{glEnd}.
20738 @deftypefun void glTexImage2D target level internalFormat width height border format type data
20739 Specify a two-dimensional texture image.
20743 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
20744 @code{GL_PROXY_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
20745 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
20746 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
20747 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
20748 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z},
20749 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or
20750 @code{GL_PROXY_TEXTURE_CUBE_MAP}.
20753 Specifies the level-of-detail number. Level 0 is the base image level.
20754 Level @var{n} is the @var{n}th mipmap reduction image.
20756 @item @var{internalFormat}
20757 Specifies the number of color components in the texture. Must be 1, 2,
20758 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA},
20759 @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
20760 @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA},
20761 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
20762 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
20763 @code{GL_COMPRESSED_RGBA}, @code{GL_DEPTH_COMPONENT},
20764 @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24},
20765 @code{GL_DEPTH_COMPONENT32}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
20766 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
20767 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
20768 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
20769 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
20770 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY},
20771 @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12},
20772 @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
20773 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
20774 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
20775 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
20776 @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE},
20777 @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
20778 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
20779 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
20782 Specifies the width of the texture image including the border if any. If
20783 the GL version does not support non-power-of-two sizes, this value must
20784 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
20785 implementations support texture images that are at least 64 texels wide.
20788 Specifies the height of the texture image including the border if any.
20789 If the GL version does not support non-power-of-two sizes, this value
20790 must be @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}.
20791 All implementations support texture images that are at least 64 texels
20795 Specifies the width of the border. Must be either 0 or 1.
20798 Specifies the format of the pixel data. The following symbolic values
20799 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
20800 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
20801 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
20802 @code{GL_LUMINANCE_ALPHA}.
20805 Specifies the data type of the pixel data. The following symbolic values
20806 are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
20807 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
20808 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
20809 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
20810 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
20811 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
20812 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
20813 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
20814 and @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
20817 Specifies a pointer to the image data in memory.
20821 Texturing maps a portion of a specified texture image onto each
20822 graphical primitive for which texturing is enabled. To enable and
20823 disable two-dimensional texturing, call @code{glEnable} and
20824 @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and
20825 disable texturing using cube-mapped texture, call @code{glEnable} and
20826 @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}.
20828 To define texture images, call @code{glTexImage2D}. The arguments
20829 describe the parameters of the texture image, such as height, width,
20830 width of the border, level-of-detail number (see @code{glTexParameter}),
20831 and number of color components provided. The last three arguments
20832 describe how the image is represented in memory; they are identical to
20833 the pixel formats used for @code{glDrawPixels}.
20835 If @var{target} is @code{GL_PROXY_TEXTURE_2D} or
20836 @code{GL_PROXY_TEXTURE_CUBE_MAP}, no data is read from @var{data}, but
20837 all of the texture image state is recalculated, checked for consistency,
20838 and checked against the implementation's capabilities. If the
20839 implementation cannot handle a texture of the requested texture size, it
20840 sets all of the image state to 0, but does not generate an error (see
20841 @code{glGetError}). To query for an entire mipmap array, use an image
20842 array level greater than or equal to 1.
20844 If @var{target} is @code{GL_TEXTURE_2D}, or one of the
20845 @code{GL_TEXTURE_CUBE_MAP} targets, data is read from @var{data} as a
20846 sequence of signed or unsigned bytes, shorts, or longs, or
20847 single-precision floating-point values, depending on @var{type}. These
20848 values are grouped into sets of one, two, three, or four values,
20849 depending on @var{format}, to form elements. If @var{type} is
20850 @code{GL_BITMAP}, the data is considered as a string of unsigned bytes
20851 (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is
20852 treated as eight 1-bit elements, with bit ordering determined by
20853 @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}).
20855 If a non-zero named buffer object is bound to the
20856 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
20857 texture image is specified, @var{data} is treated as a byte offset into
20858 the buffer object's data store.
20860 The first element corresponds to the lower left corner of the texture
20861 image. Subsequent elements progress left-to-right through the remaining
20862 texels in the lowest row of the texture image, and then in successively
20863 higher rows of the texture image. The final element corresponds to the
20864 upper right corner of the texture image.
20866 @var{format} determines the composition of each element in @var{data}.
20867 It can assume one of these symbolic values:
20870 @item @code{GL_COLOR_INDEX}
20871 Each element is a single value, a color index. The GL converts it to
20872 fixed point (with an unspecified number of zero bits to the right of the
20873 binary point), shifted left or right depending on the value and sign of
20874 @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see
20875 @code{glPixelTransfer}). The resulting index is converted to a set of
20876 color components using the @code{GL_PIXEL_MAP_I_TO_R},
20877 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
20878 @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1].
20880 @item @code{GL_RED}
20881 Each element is a single red component. The GL converts it to floating
20882 point and assembles it into an RGBA element by attaching 0 for green and
20883 blue, and 1 for alpha. Each component is then multiplied by the signed
20884 scale factor @code{GL_c_SCALE}, added to the signed bias
20885 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20886 @code{glPixelTransfer}).
20888 @item @code{GL_GREEN}
20889 Each element is a single green component. The GL converts it to floating
20890 point and assembles it into an RGBA element by attaching 0 for red and
20891 blue, and 1 for alpha. Each component is then multiplied by the signed
20892 scale factor @code{GL_c_SCALE}, added to the signed bias
20893 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20894 @code{glPixelTransfer}).
20896 @item @code{GL_BLUE}
20897 Each element is a single blue component. The GL converts it to floating
20898 point and assembles it into an RGBA element by attaching 0 for red and
20899 green, and 1 for alpha. Each component is then multiplied by the signed
20900 scale factor @code{GL_c_SCALE}, added to the signed bias
20901 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20902 @code{glPixelTransfer}).
20904 @item @code{GL_ALPHA}
20905 Each element is a single alpha component. The GL converts it to floating
20906 point and assembles it into an RGBA element by attaching 0 for red,
20907 green, and blue. Each component is then multiplied by the signed scale
20908 factor @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20909 clamped to the range [0,1] (see @code{glPixelTransfer}).
20911 @item @code{GL_INTENSITY}
20912 Each element is a single intensity value. The GL converts it to floating
20913 point, then assembles it into an RGBA element by replicating the
20914 intensity value three times for red, green, blue, and alpha. Each
20915 component is then multiplied by the signed scale factor
20916 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20917 clamped to the range [0,1] (see @code{glPixelTransfer}).
20919 @item @code{GL_RGB}
20920 @item @code{GL_BGR}
20921 Each element is an RGB triple. The GL converts it to floating point and
20922 assembles it into an RGBA element by attaching 1 for alpha. Each
20923 component is then multiplied by the signed scale factor
20924 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20925 clamped to the range [0,1] (see @code{glPixelTransfer}).
20927 @item @code{GL_RGBA}
20928 @item @code{GL_BGRA}
20929 Each element contains all four components. Each component is multiplied
20930 by the signed scale factor @code{GL_c_SCALE}, added to the signed bias
20931 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20932 @code{glPixelTransfer}).
20934 @item @code{GL_LUMINANCE}
20935 Each element is a single luminance value. The GL converts it to floating
20936 point, then assembles it into an RGBA element by replicating the
20937 luminance value three times for red, green, and blue and attaching 1 for
20938 alpha. Each component is then multiplied by the signed scale factor
20939 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20940 clamped to the range [0,1] (see @code{glPixelTransfer}).
20942 @item @code{GL_LUMINANCE_ALPHA}
20943 Each element is a luminance/alpha pair. The GL converts it to floating
20944 point, then assembles it into an RGBA element by replicating the
20945 luminance value three times for red, green, and blue. Each component is
20946 then multiplied by the signed scale factor @code{GL_c_SCALE}, added to
20947 the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20948 @code{glPixelTransfer}).
20950 @item @code{GL_DEPTH_COMPONENT}
20951 Each element is a single depth value. The GL converts it to floating
20952 point, multiplies by the signed scale factor @code{GL_DEPTH_SCALE}, adds
20953 the signed bias @code{GL_DEPTH_BIAS}, and clamps to the range [0,1] (see
20954 @code{glPixelTransfer}).
20958 Refer to the @code{glDrawPixels} reference page for a description of the
20959 acceptable values for the @var{type} parameter.
20961 If an application wants to store the texture at a certain resolution or
20962 in a certain format, it can request the resolution and format with
20963 @var{internalFormat}. The GL will choose an internal representation that
20964 closely approximates that requested by @var{internalFormat}, but it may
20965 not match exactly. (The representations specified by
20966 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and
20967 @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 may
20968 also be used to specify the above representations.)
20970 If the @var{internalFormat} parameter is one of the generic compressed
20971 formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
20972 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
20973 @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will
20974 replace the internal format with the symbolic constant for a specific
20975 internal format and compress the texture before storage. If no
20976 corresponding internal format is available, or the GL can not compress
20977 that image for any reason, the internal format is instead replaced with
20978 a corresponding base internal format.
20980 If the @var{internalFormat} parameter is @code{GL_SRGB},
20981 @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8},
20982 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
20983 or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red,
20984 green, blue, or luminance components are encoded in the sRGB color
20985 space. Any alpha component is left unchanged. The conversion from the
20986 sRGB encoded component @r{@var{c}_@var{s}} to a linear component
20987 @r{@var{c}_@var{l}} is:
20989 @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045),
20990 ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)}
20992 Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1].
20994 Use the @code{GL_PROXY_TEXTURE_2D} or @code{GL_PROXY_TEXTURE_CUBE_MAP}
20995 target to try out a resolution and format. The implementation will
20996 update and recompute its best match for the requested storage resolution
20997 and format. To then query this state, call
20998 @code{glGetTexLevelParameter}. If the texture cannot be accommodated,
20999 texture state is set to 0.
21001 A one-component texture image uses only the red component of the RGBA
21002 color extracted from @var{data}. A two-component image uses the R and A
21003 values. A three-component image uses the R, G, and B values. A
21004 four-component image uses all of the RGBA components.
21006 Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA textures
21007 during texture filtering and application. Image-based shadowing can be
21008 enabled by comparing texture r coordinates to depth texture values to
21009 generate a boolean result. See @code{glTexParameter} for details on
21010 texture comparison.
21012 @code{GL_INVALID_ENUM} is generated if @var{target} is not
21013 @code{GL_TEXTURE_2D}, @code{GL_PROXY_TEXTURE_2D},
21014 @code{GL_PROXY_TEXTURE_CUBE_MAP}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
21015 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
21016 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
21017 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
21018 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
21019 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
21021 @code{GL_INVALID_ENUM} is generated if @var{target} is one of the six
21022 cube map 2D image targets and the width and height parameters are not
21025 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
21028 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
21029 and @var{format} is not @code{GL_COLOR_INDEX}.
21031 @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is
21032 less than 0 or greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
21034 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
21036 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
21037 @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of
21038 @code{GL_MAX_TEXTURE_SIZE}.
21040 @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1,
21041 2, 3, 4, or one of the accepted resolution and format symbolic
21044 @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is
21045 less than 0 or greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
21047 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
21048 not supported and the @var{width} or @var{height} cannot be represented
21049 as @r{2^@var{k}+2(@var{border},)} for some integer value of @var{k}.
21051 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
21053 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21054 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
21055 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
21056 and @var{format} is not @code{GL_RGB}.
21058 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21059 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
21060 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
21061 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
21062 @code{GL_UNSIGNED_INT_10_10_10_2}, or
21063 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
21064 @code{GL_RGBA} nor @code{GL_BGRA}.
21066 @code{GL_INVALID_OPERATION} is generated if @var{target} is not
21067 @code{GL_TEXTURE_2D} or @code{GL_PROXY_TEXTURE_2D} and
21068 @var{internalFormat} is @code{GL_DEPTH_COMPONENT},
21069 @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, or
21070 @code{GL_DEPTH_COMPONENT32}.
21072 @code{GL_INVALID_OPERATION} is generated if @var{format} is
21073 @code{GL_DEPTH_COMPONENT} and @var{internalFormat} is not
21074 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
21075 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}.
21077 @code{GL_INVALID_OPERATION} is generated if @var{internalFormat} is
21078 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
21079 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}, and
21080 @var{format} is not @code{GL_DEPTH_COMPONENT}.
21082 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21083 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
21084 object's data store is currently mapped.
21086 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21087 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
21088 would be unpacked from the buffer object such that the memory reads
21089 required would exceed the data store size.
21091 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21092 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
21093 is not evenly divisible into the number of bytes needed to store in
21094 memory a datum indicated by @var{type}.
21096 @code{GL_INVALID_OPERATION} is generated if @code{glTexImage2D} is
21097 executed between the execution of @code{glBegin} and the corresponding
21098 execution of @code{glEnd}.
21102 @deftypefun void glTexImage3D target level internalFormat width height depth border format type data
21103 Specify a three-dimensional texture image.
21107 Specifies the target texture. Must be @code{GL_TEXTURE_3D} or
21108 @code{GL_PROXY_TEXTURE_3D}.
21111 Specifies the level-of-detail number. Level 0 is the base image level.
21112 Level @r{@var{n}} is the @r{@var{n}^@var{th}} mipmap reduction image.
21114 @item @var{internalFormat}
21115 Specifies the number of color components in the texture. Must be 1, 2,
21116 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA},
21117 @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
21118 @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA},
21119 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
21120 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
21121 @code{GL_COMPRESSED_RGBA}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
21122 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
21123 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
21124 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
21125 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
21126 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY},
21127 @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12},
21128 @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
21129 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
21130 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
21131 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
21132 @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE},
21133 @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
21134 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
21135 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
21138 Specifies the width of the texture image including the border if any. If
21139 the GL version does not support non-power-of-two sizes, this value must
21140 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
21141 implementations support 3D texture images that are at least 16 texels
21145 Specifies the height of the texture image including the border if any.
21146 If the GL version does not support non-power-of-two sizes, this value
21147 must be @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}.
21148 All implementations support 3D texture images that are at least 16
21152 Specifies the depth of the texture image including the border if any. If
21153 the GL version does not support non-power-of-two sizes, this value must
21154 be @r{2^@var{k}+2(@var{border},)} for some integer @r{@var{k}}. All
21155 implementations support 3D texture images that are at least 16 texels
21159 Specifies the width of the border. Must be either 0 or 1.
21162 Specifies the format of the pixel data. The following symbolic values
21163 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
21164 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
21165 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
21166 @code{GL_LUMINANCE_ALPHA}.
21169 Specifies the data type of the pixel data. The following symbolic values
21170 are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
21171 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
21172 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
21173 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
21174 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
21175 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
21176 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
21177 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
21178 and @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
21181 Specifies a pointer to the image data in memory.
21185 Texturing maps a portion of a specified texture image onto each
21186 graphical primitive for which texturing is enabled. To enable and
21187 disable three-dimensional texturing, call @code{glEnable} and
21188 @code{glDisable} with argument @code{GL_TEXTURE_3D}.
21190 To define texture images, call @code{glTexImage3D}. The arguments
21191 describe the parameters of the texture image, such as height, width,
21192 depth, width of the border, level-of-detail number (see
21193 @code{glTexParameter}), and number of color components provided. The
21194 last three arguments describe how the image is represented in memory;
21195 they are identical to the pixel formats used for @code{glDrawPixels}.
21197 If @var{target} is @code{GL_PROXY_TEXTURE_3D}, no data is read from
21198 @var{data}, but all of the texture image state is recalculated, checked
21199 for consistency, and checked against the implementation's capabilities.
21200 If the implementation cannot handle a texture of the requested texture
21201 size, it sets all of the image state to 0, but does not generate an
21202 error (see @code{glGetError}). To query for an entire mipmap array, use
21203 an image array level greater than or equal to 1.
21205 If @var{target} is @code{GL_TEXTURE_3D}, data is read from @var{data} as
21206 a sequence of signed or unsigned bytes, shorts, or longs, or
21207 single-precision floating-point values, depending on @var{type}. These
21208 values are grouped into sets of one, two, three, or four values,
21209 depending on @var{format}, to form elements. If @var{type} is
21210 @code{GL_BITMAP}, the data is considered as a string of unsigned bytes
21211 (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is
21212 treated as eight 1-bit elements, with bit ordering determined by
21213 @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}).
21215 If a non-zero named buffer object is bound to the
21216 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
21217 texture image is specified, @var{data} is treated as a byte offset into
21218 the buffer object's data store.
21220 The first element corresponds to the lower left corner of the texture
21221 image. Subsequent elements progress left-to-right through the remaining
21222 texels in the lowest row of the texture image, and then in successively
21223 higher rows of the texture image. The final element corresponds to the
21224 upper right corner of the texture image.
21226 @var{format} determines the composition of each element in @var{data}.
21227 It can assume one of these symbolic values:
21230 @item @code{GL_COLOR_INDEX}
21231 Each element is a single value, a color index. The GL converts it to
21232 fixed point (with an unspecified number of zero bits to the right of the
21233 binary point), shifted left or right depending on the value and sign of
21234 @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see
21235 @code{glPixelTransfer}). The resulting index is converted to a set of
21236 color components using the @code{GL_PIXEL_MAP_I_TO_R},
21237 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
21238 @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1].
21240 @item @code{GL_RED}
21241 Each element is a single red component. The GL converts it to floating
21242 point and assembles it into an RGBA element by attaching 0 for green and
21243 blue, and 1 for alpha. Each component is then multiplied by the signed
21244 scale factor @code{GL_c_SCALE}, added to the signed bias
21245 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
21246 @code{glPixelTransfer}).
21248 @item @code{GL_GREEN}
21249 Each element is a single green component. The GL converts it to floating
21250 point and assembles it into an RGBA element by attaching 0 for red and
21251 blue, and 1 for alpha. Each component is then multiplied by the signed
21252 scale factor @code{GL_c_SCALE}, added to the signed bias
21253 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
21254 @code{glPixelTransfer}).
21256 @item @code{GL_BLUE}
21257 Each element is a single blue component. The GL converts it to floating
21258 point and assembles it into an RGBA element by attaching 0 for red and
21259 green, and 1 for alpha. Each component is then multiplied by the signed
21260 scale factor @code{GL_c_SCALE}, added to the signed bias
21261 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
21262 @code{glPixelTransfer}).
21264 @item @code{GL_ALPHA}
21265 Each element is a single alpha component. The GL converts it to floating
21266 point and assembles it into an RGBA element by attaching 0 for red,
21267 green, and blue. Each component is then multiplied by the signed scale
21268 factor @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
21269 clamped to the range [0,1] (see @code{glPixelTransfer}).
21271 @item @code{GL_INTENSITY}
21272 Each element is a single intensity value. The GL converts it to floating
21273 point, then assembles it into an RGBA element by replicating the
21274 intensity value three times for red, green, blue, and alpha. Each
21275 component is then multiplied by the signed scale factor
21276 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
21277 clamped to the range [0,1] (see @code{glPixelTransfer}).
21279 @item @code{GL_RGB}
21280 @item @code{GL_BGR}
21281 Each element is an RGB triple. The GL converts it to floating point and
21282 assembles it into an RGBA element by attaching 1 for alpha. Each
21283 component is then multiplied by the signed scale factor
21284 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
21285 clamped to the range [0,1] (see @code{glPixelTransfer}).
21287 @item @code{GL_RGBA}
21288 @item @code{GL_BGRA}
21289 Each element contains all four components. Each component is multiplied
21290 by the signed scale factor @code{GL_c_SCALE}, added to the signed bias
21291 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
21292 @code{glPixelTransfer}).
21294 @item @code{GL_LUMINANCE}
21295 Each element is a single luminance value. The GL converts it to floating
21296 point, then assembles it into an RGBA element by replicating the
21297 luminance value three times for red, green, and blue and attaching 1 for
21298 alpha. Each component is then multiplied by the signed scale factor
21299 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
21300 clamped to the range [0,1] (see @code{glPixelTransfer}).
21302 @item @code{GL_LUMINANCE_ALPHA}
21303 Each element is a luminance/alpha pair. The GL converts it to floating
21304 point, then assembles it into an RGBA element by replicating the
21305 luminance value three times for red, green, and blue. Each component is
21306 then multiplied by the signed scale factor @code{GL_c_SCALE}, added to
21307 the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see
21308 @code{glPixelTransfer}).
21312 Refer to the @code{glDrawPixels} reference page for a description of the
21313 acceptable values for the @var{type} parameter.
21315 If an application wants to store the texture at a certain resolution or
21316 in a certain format, it can request the resolution and format with
21317 @var{internalFormat}. The GL will choose an internal representation that
21318 closely approximates that requested by @var{internalFormat}, but it may
21319 not match exactly. (The representations specified by
21320 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and
21321 @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 may
21322 also be used to specify the above representations.)
21324 If the @var{internalFormat} parameter is one of the generic compressed
21325 formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
21326 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
21327 @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will
21328 replace the internal format with the symbolic constant for a specific
21329 internal format and compress the texture before storage. If no
21330 corresponding internal format is available, or the GL can not compress
21331 that image for any reason, the internal format is instead replaced with
21332 a corresponding base internal format.
21334 If the @var{internalFormat} parameter is @code{GL_SRGB},
21335 @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8},
21336 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
21337 or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red,
21338 green, blue, or luminance components are encoded in the sRGB color
21339 space. Any alpha component is left unchanged. The conversion from the
21340 sRGB encoded component @r{@var{c}_@var{s}} to a linear component
21341 @r{@var{c}_@var{l}} is:
21343 @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045),
21344 ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)}
21346 Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1].
21348 Use the @code{GL_PROXY_TEXTURE_3D} target to try out a resolution and
21349 format. The implementation will update and recompute its best match for
21350 the requested storage resolution and format. To then query this state,
21351 call @code{glGetTexLevelParameter}. If the texture cannot be
21352 accommodated, texture state is set to 0.
21354 A one-component texture image uses only the red component of the RGBA
21355 color extracted from @var{data}. A two-component image uses the R and A
21356 values. A three-component image uses the R, G, and B values. A
21357 four-component image uses all of the RGBA components.
21359 @code{GL_INVALID_ENUM} is generated if @var{target} is not
21360 @code{GL_TEXTURE_3D} or @code{GL_PROXY_TEXTURE_3D}.
21362 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
21363 format constant. Format constants other than @code{GL_STENCIL_INDEX} and
21364 @code{GL_DEPTH_COMPONENT} are accepted.
21366 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
21369 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
21370 and @var{format} is not @code{GL_COLOR_INDEX}.
21372 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
21374 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
21375 @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of
21376 @code{GL_MAX_TEXTURE_SIZE}.
21378 @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1,
21379 2, 3, 4, or one of the accepted resolution and format symbolic
21382 @code{GL_INVALID_VALUE} is generated if @var{width}, @var{height}, or
21383 @var{depth} is less than 0 or greater than 2 +
21384 @code{GL_MAX_TEXTURE_SIZE}.
21386 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
21387 not supported and the @var{width}, @var{height}, or @var{depth} cannot
21388 be represented as @r{2^@var{k}+2(@var{border},)} for some integer value
21391 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
21393 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21394 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
21395 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
21396 and @var{format} is not @code{GL_RGB}.
21398 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21399 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
21400 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
21401 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
21402 @code{GL_UNSIGNED_INT_10_10_10_2}, or
21403 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
21404 @code{GL_RGBA} nor @code{GL_BGRA}.
21406 @code{GL_INVALID_OPERATION} is generated if @var{format} or
21407 @var{internalFormat} is @code{GL_DEPTH_COMPONENT},
21408 @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, or
21409 @code{GL_DEPTH_COMPONENT32}.
21411 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21412 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
21413 object's data store is currently mapped.
21415 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21416 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
21417 would be unpacked from the buffer object such that the memory reads
21418 required would exceed the data store size.
21420 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21421 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
21422 is not evenly divisible into the number of bytes needed to store in
21423 memory a datum indicated by @var{type}.
21425 @code{GL_INVALID_OPERATION} is generated if @code{glTexImage3D} is
21426 executed between the execution of @code{glBegin} and the corresponding
21427 execution of @code{glEnd}.
21431 @deftypefun void glTexParameterf target pname param
21432 @deftypefunx void glTexParameteri target pname param
21433 @deftypefunx void glTexParameterfv target pname params
21434 @deftypefunx void glTexParameteriv target pname params
21435 Set texture parameters.
21439 Specifies the target texture, which must be either @code{GL_TEXTURE_1D},
21440 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, or
21441 @code{GL_TEXTURE_CUBE_MAP}.
21444 Specifies the symbolic name of a single-valued texture parameter.
21445 @var{pname} can be one of the following: @code{GL_TEXTURE_MIN_FILTER},
21446 @code{GL_TEXTURE_MAG_FILTER}, @code{GL_TEXTURE_MIN_LOD},
21447 @code{GL_TEXTURE_MAX_LOD}, @code{GL_TEXTURE_BASE_LEVEL},
21448 @code{GL_TEXTURE_MAX_LEVEL}, @code{GL_TEXTURE_WRAP_S},
21449 @code{GL_TEXTURE_WRAP_T}, @code{GL_TEXTURE_WRAP_R},
21450 @code{GL_TEXTURE_PRIORITY}, @code{GL_TEXTURE_COMPARE_MODE},
21451 @code{GL_TEXTURE_COMPARE_FUNC}, @code{GL_DEPTH_TEXTURE_MODE}, or
21452 @code{GL_GENERATE_MIPMAP}.
21455 Specifies the value of @var{pname}.
21459 Texture mapping is a technique that applies an image onto an object's
21460 surface as if the image were a decal or cellophane shrink-wrap. The
21461 image is created in texture space, with an (@r{@var{s}}, @r{@var{t}})
21462 coordinate system. A texture is a one- or two-dimensional image and a
21463 set of parameters that determine how samples are derived from the image.
21465 @code{glTexParameter} assigns the value or values in @var{params} to the
21466 texture parameter specified as @var{pname}. @var{target} defines the
21467 target texture, either @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, or
21468 @code{GL_TEXTURE_3D}. The following symbols are accepted in @var{pname}:
21471 @item @code{GL_TEXTURE_MIN_FILTER}
21472 The texture minifying function is used whenever the pixel being textured
21473 maps to an area greater than one texture element. There are six defined
21474 minifying functions. Two of them use the nearest one or nearest four
21475 texture elements to compute the texture value. The other four use
21478 A mipmap is an ordered set of arrays representing the same image at
21479 progressively lower resolutions. If the texture has dimensions
21480 @r{2^@var{n}×2^@var{m}}, there are @r{@var{max}(@var{n},@var{m})+1}
21481 mipmaps. The first mipmap is the original texture, with dimensions
21482 @r{2^@var{n}×2^@var{m}}. Each subsequent mipmap has dimensions
21483 @r{2^@var{k}-1,×2^@var{l}-1,}, where @r{2^@var{k}×2^@var{l}} are the
21484 dimensions of the previous mipmap, until either @r{@var{k}=0} or
21485 @r{@var{l}=0}. At that point, subsequent mipmaps have dimension
21486 @r{1×2^@var{l}-1,} or @r{2^@var{k}-1,×1} until the final mipmap, which
21487 has dimension @r{1×1}. To define the mipmaps, call @code{glTexImage1D},
21488 @code{glTexImage2D}, @code{glTexImage3D}, @code{glCopyTexImage1D}, or
21489 @code{glCopyTexImage2D} with the @var{level} argument indicating the
21490 order of the mipmaps. Level 0 is the original texture; level
21491 @r{@var{max}(@var{n},@var{m})} is the final @r{1×1} mipmap.
21493 @var{params} supplies a function for minifying the texture as one of the
21496 As more texture elements are sampled in the minification process, fewer
21497 aliasing artifacts will be apparent. While the @code{GL_NEAREST} and
21498 @code{GL_LINEAR} minification functions can be faster than the other
21499 four, they sample only one or four texture elements to determine the
21500 texture value of the pixel being rendered and can produce moire patterns
21501 or ragged transitions. The initial value of @code{GL_TEXTURE_MIN_FILTER}
21502 is @code{GL_NEAREST_MIPMAP_LINEAR}.
21504 @item @code{GL_TEXTURE_MAG_FILTER}
21505 The texture magnification function is used when the pixel being textured
21506 maps to an area less than or equal to one texture element. It sets the
21507 texture magnification function to either @code{GL_NEAREST} or
21508 @code{GL_LINEAR} (see below). @code{GL_NEAREST} is generally faster than
21509 @code{GL_LINEAR}, but it can produce textured images with sharper edges
21510 because the transition between texture elements is not as smooth. The
21511 initial value of @code{GL_TEXTURE_MAG_FILTER} is @code{GL_LINEAR}.
21516 @item @code{GL_NEAREST}
21517 Returns the value of the texture element that is nearest (in Manhattan
21518 distance) to the center of the pixel being textured.
21520 @item @code{GL_LINEAR}
21521 Returns the weighted average of the four texture elements that are
21522 closest to the center of the pixel being textured. These can include
21523 border texture elements, depending on the values of
21524 @code{GL_TEXTURE_WRAP_S} and @code{GL_TEXTURE_WRAP_T}, and on the exact
21527 @item @code{GL_NEAREST_MIPMAP_NEAREST}
21528 Chooses the mipmap that most closely matches the size of the pixel being
21529 textured and uses the @code{GL_NEAREST} criterion (the texture element
21530 nearest to the center of the pixel) to produce a texture value.
21532 @item @code{GL_LINEAR_MIPMAP_NEAREST}
21533 Chooses the mipmap that most closely matches the size of the pixel being
21534 textured and uses the @code{GL_LINEAR} criterion (a weighted average of
21535 the four texture elements that are closest to the center of the pixel)
21536 to produce a texture value.
21538 @item @code{GL_NEAREST_MIPMAP_LINEAR}
21539 Chooses the two mipmaps that most closely match the size of the pixel
21540 being textured and uses the @code{GL_NEAREST} criterion (the texture
21541 element nearest to the center of the pixel) to produce a texture value
21542 from each mipmap. The final texture value is a weighted average of those
21545 @item @code{GL_LINEAR_MIPMAP_LINEAR}
21546 Chooses the two mipmaps that most closely match the size of the pixel
21547 being textured and uses the @code{GL_LINEAR} criterion (a weighted
21548 average of the four texture elements that are closest to the center of
21549 the pixel) to produce a texture value from each mipmap. The final
21550 texture value is a weighted average of those two values.
21555 @item @code{GL_NEAREST}
21556 Returns the value of the texture element that is nearest (in Manhattan
21557 distance) to the center of the pixel being textured.
21559 @item @code{GL_LINEAR}
21560 Returns the weighted average of the four texture elements that are
21561 closest to the center of the pixel being textured. These can include
21562 border texture elements, depending on the values of
21563 @code{GL_TEXTURE_WRAP_S} and @code{GL_TEXTURE_WRAP_T}, and on the exact
21571 @item @code{GL_TEXTURE_MIN_LOD}
21572 Sets the minimum level-of-detail parameter. This floating-point value
21573 limits the selection of highest resolution mipmap (lowest mipmap level).
21574 The initial value is -1000.
21581 @item @code{GL_TEXTURE_MAX_LOD}
21582 Sets the maximum level-of-detail parameter. This floating-point value
21583 limits the selection of the lowest resolution mipmap (highest mipmap
21584 level). The initial value is 1000.
21591 @item @code{GL_TEXTURE_BASE_LEVEL}
21592 Specifies the index of the lowest defined mipmap level. This is an
21593 integer value. The initial value is 0.
21600 @item @code{GL_TEXTURE_MAX_LEVEL}
21601 Sets the index of the highest defined mipmap level. This is an integer
21602 value. The initial value is 1000.
21609 @item @code{GL_TEXTURE_WRAP_S}
21610 Sets the wrap parameter for texture coordinate @r{@var{s}} to either
21611 @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE},
21612 @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. @code{GL_CLAMP} causes
21613 @r{@var{s}} coordinates to be clamped to the range [0,1] and is useful
21614 for preventing wrapping artifacts when mapping a single image onto an
21615 object. @code{GL_CLAMP_TO_BORDER} causes the @r{@var{s}} coordinate to
21616 be clamped to the range @r{[-1/2@var{N},,1+1/2@var{N},]}, where
21617 @r{@var{N}} is the size of the texture in the direction of
21618 clamping.@code{GL_CLAMP_TO_EDGE} causes @r{@var{s}} coordinates to be
21619 clamped to the range @r{[1/2@var{N},,1-1/2@var{N},]}, where @r{@var{N}}
21620 is the size of the texture in the direction of clamping.
21621 @code{GL_REPEAT} causes the integer part of the @r{@var{s}} coordinate
21622 to be ignored; the GL uses only the fractional part, thereby creating a
21623 repeating pattern. @code{GL_MIRRORED_REPEAT} causes the @r{@var{s}}
21624 coordinate to be set to the fractional part of the texture coordinate if
21625 the integer part of @r{@var{s}} is even; if the integer part of
21626 @r{@var{s}} is odd, then the @r{@var{s}} texture coordinate is set to
21627 @r{1-@var{frac}(@var{s},)}, where @r{@var{frac}(@var{s},)} represents
21628 the fractional part of @r{@var{s}}. Border texture elements are accessed
21629 only if wrapping is set to @code{GL_CLAMP} or @code{GL_CLAMP_TO_BORDER}.
21630 Initially, @code{GL_TEXTURE_WRAP_S} is set to @code{GL_REPEAT}.
21637 @item @code{GL_TEXTURE_WRAP_T}
21638 Sets the wrap parameter for texture coordinate @r{@var{t}} to either
21639 @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE},
21640 @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. See the discussion under
21641 @code{GL_TEXTURE_WRAP_S}. Initially, @code{GL_TEXTURE_WRAP_T} is set to
21644 @item @code{GL_TEXTURE_WRAP_R}
21645 Sets the wrap parameter for texture coordinate @r{@var{r}} to either
21646 @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE},
21647 @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. See the discussion under
21648 @code{GL_TEXTURE_WRAP_S}. Initially, @code{GL_TEXTURE_WRAP_R} is set to
21651 @item @code{GL_TEXTURE_BORDER_COLOR}
21652 Sets a border color. @var{params} contains four values that comprise the
21653 RGBA color of the texture border. Integer color components are
21654 interpreted linearly such that the most positive integer maps to 1.0,
21655 and the most negative integer maps to -1.0. The values are clamped to
21656 the range [0,1] when they are specified. Initially, the border color is
21659 @item @code{GL_TEXTURE_PRIORITY}
21660 Specifies the texture residence priority of the currently bound texture.
21661 Permissible values are in the range @r{[0,1]}. See
21662 @code{glPrioritizeTextures} and @code{glBindTexture} for more
21665 @item @code{GL_TEXTURE_COMPARE_MODE}
21666 Specifies the texture comparison mode for currently bound depth
21667 textures. That is, a texture whose internal format is
21668 @code{GL_DEPTH_COMPONENT_*}; see @code{glTexImage2D}) Permissible values
21671 @item @code{GL_TEXTURE_COMPARE_FUNC}
21672 Specifies the comparison operator used when
21673 @code{GL_TEXTURE_COMPARE_MODE} is set to @code{GL_COMPARE_R_TO_TEXTURE}.
21674 Permissible values are: where @r{@var{r}} is the current interpolated
21675 texture coordinate, and @r{@var{D}_@var{t}} is the depth texture value
21676 sampled from the currently bound depth texture. @r{@var{result}} is
21677 assigned to the either the luminance, intensity, or alpha (as specified
21678 by @code{GL_DEPTH_TEXTURE_MODE}.)
21680 @item @code{GL_DEPTH_TEXTURE_MODE}
21681 Specifies a single symbolic constant indicating how depth values should
21682 be treated during filtering and texture application. Accepted values are
21683 @code{GL_LUMINANCE}, @code{GL_INTENSITY}, and @code{GL_ALPHA}. The
21684 initial value is @code{GL_LUMINANCE}.
21686 @item @code{GL_GENERATE_MIPMAP}
21687 Specifies a boolean value that indicates if all levels of a mipmap array
21688 should be automatically updated when any modification to the base level
21689 mipmap is done. The initial value is @code{GL_FALSE}.
21694 @item @code{GL_COMPARE_R_TO_TEXTURE}
21695 Specifies that the interpolated and clamped @r{@var{r}} texture
21696 coordinate should be compared to the value in the currently bound depth
21697 texture. See the discussion of @code{GL_TEXTURE_COMPARE_FUNC} for
21698 details of how the comparison is evaluated. The result of the comparison
21699 is assigned to luminance, intensity, or alpha (as specified by
21700 @code{GL_DEPTH_TEXTURE_MODE}).
21702 @item @code{GL_NONE}
21703 Specifies that the luminance, intensity, or alpha (as specified by
21704 @code{GL_DEPTH_TEXTURE_MODE}) should be assigned the appropriate value
21705 from the currently bound depth texture.
21710 @item @strong{Texture Comparison Function}
21711 @strong{Computed result}
21713 @item @code{GL_LEQUAL}
21714 @r{@var{result}=@{(1.0), (0.0) (@var{r}<=@var{D}_@var{t},),
21715 (@var{r}>@var{D}_@var{t},),}
21717 @item @code{GL_GEQUAL}
21718 @r{@var{result}=@{(1.0), (0.0) (@var{r}>=@var{D}_@var{t},),
21719 (@var{r}<@var{D}_@var{t},),}
21721 @item @code{GL_LESS}
21722 @r{@var{result}=@{(1.0), (0.0) (@var{r}<@var{D}_@var{t},),
21723 (@var{r}>=@var{D}_@var{t},),}
21725 @item @code{GL_GREATER}
21726 @r{@var{result}=@{(1.0), (0.0) (@var{r}>@var{D}_@var{t},),
21727 (@var{r}<=@var{D}_@var{t},),}
21729 @item @code{GL_EQUAL}
21730 @r{@var{result}=@{(1.0), (0.0) (@var{r}=@var{D}_@var{t},),
21731 (@var{r}≠@var{D}_@var{t},),}
21733 @item @code{GL_NOTEQUAL}
21734 @r{@var{result}=@{(1.0), (0.0) (@var{r}≠@var{D}_@var{t},),
21735 (@var{r}=@var{D}_@var{t},),}
21737 @item @code{GL_ALWAYS}
21738 @r{@var{result}=@code{1.0}}
21740 @item @code{GL_NEVER}
21741 @r{@var{result}=@code{0.0}}
21745 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
21746 not one of the accepted defined values.
21748 @code{GL_INVALID_ENUM} is generated if @var{params} should have a
21749 defined constant value (based on the value of @var{pname}) and does not.
21751 @code{GL_INVALID_OPERATION} is generated if @code{glTexParameter} is
21752 executed between the execution of @code{glBegin} and the corresponding
21753 execution of @code{glEnd}.
21757 @deftypefun void glTexSubImage1D target level xoffset width format type data
21758 Specify a one-dimensional texture subimage.
21762 Specifies the target texture. Must be @code{GL_TEXTURE_1D}.
21765 Specifies the level-of-detail number. Level 0 is the base image level.
21766 Level @var{n} is the @var{n}th mipmap reduction image.
21768 @item @var{xoffset}
21769 Specifies a texel offset in the x direction within the texture array.
21772 Specifies the width of the texture subimage.
21775 Specifies the format of the pixel data. The following symbolic values
21776 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
21777 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
21778 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
21779 @code{GL_LUMINANCE_ALPHA}.
21782 Specifies the data type of the pixel data. The following symbolic values
21783 are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
21784 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
21785 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
21786 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
21787 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
21788 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
21789 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
21790 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
21791 and @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
21794 Specifies a pointer to the image data in memory.
21798 Texturing maps a portion of a specified texture image onto each
21799 graphical primitive for which texturing is enabled. To enable or disable
21800 one-dimensional texturing, call @code{glEnable} and @code{glDisable}
21801 with argument @code{GL_TEXTURE_1D}.
21803 @code{glTexSubImage1D} redefines a contiguous subregion of an existing
21804 one-dimensional texture image. The texels referenced by @var{data}
21805 replace the portion of the existing texture array with x indices
21806 @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive. This
21807 region may not include any texels outside the range of the texture array
21808 as it was originally specified. It is not an error to specify a
21809 subtexture with width of 0, but such a specification has no effect.
21811 If a non-zero named buffer object is bound to the
21812 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
21813 texture image is specified, @var{data} is treated as a byte offset into
21814 the buffer object's data store.
21816 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
21819 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
21822 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
21825 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
21826 and @var{format} is not @code{GL_COLOR_INDEX}.
21828 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
21830 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
21831 @r{@var{log}_2}@var{max}, where @var{max} is the returned value of
21832 @code{GL_MAX_TEXTURE_SIZE}.
21834 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, or
21835 if @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, where
21836 @r{@var{w}} is the @code{GL_TEXTURE_WIDTH}, and @r{@var{b}} is the width
21837 of the @code{GL_TEXTURE_BORDER} of the texture image being modified.
21838 Note that @r{@var{w}} includes twice the border width.
21840 @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0.
21842 @code{GL_INVALID_OPERATION} is generated if the texture array has not
21843 been defined by a previous @code{glTexImage1D} operation.
21845 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21846 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
21847 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
21848 and @var{format} is not @code{GL_RGB}.
21850 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21851 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
21852 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
21853 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
21854 @code{GL_UNSIGNED_INT_10_10_10_2}, or
21855 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
21856 @code{GL_RGBA} nor @code{GL_BGRA}.
21858 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21859 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
21860 object's data store is currently mapped.
21862 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21863 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
21864 would be unpacked from the buffer object such that the memory reads
21865 required would exceed the data store size.
21867 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21868 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
21869 is not evenly divisible into the number of bytes needed to store in
21870 memory a datum indicated by @var{type}.
21872 @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage1D} is
21873 executed between the execution of @code{glBegin} and the corresponding
21874 execution of @code{glEnd}.
21878 @deftypefun void glTexSubImage2D target level xoffset yoffset width height format type data
21879 Specify a two-dimensional texture subimage.
21883 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
21884 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
21885 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
21886 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
21887 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
21888 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
21889 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
21892 Specifies the level-of-detail number. Level 0 is the base image level.
21893 Level @var{n} is the @var{n}th mipmap reduction image.
21895 @item @var{xoffset}
21896 Specifies a texel offset in the x direction within the texture array.
21898 @item @var{yoffset}
21899 Specifies a texel offset in the y direction within the texture array.
21902 Specifies the width of the texture subimage.
21905 Specifies the height of the texture subimage.
21908 Specifies the format of the pixel data. The following symbolic values
21909 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
21910 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
21911 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
21912 @code{GL_LUMINANCE_ALPHA}.
21915 Specifies the data type of the pixel data. The following symbolic values
21916 are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
21917 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
21918 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
21919 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
21920 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
21921 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
21922 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
21923 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
21924 and @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
21927 Specifies a pointer to the image data in memory.
21931 Texturing maps a portion of a specified texture image onto each
21932 graphical primitive for which texturing is enabled. To enable and
21933 disable two-dimensional texturing, call @code{glEnable} and
21934 @code{glDisable} with argument @code{GL_TEXTURE_2D}.
21936 @code{glTexSubImage2D} redefines a contiguous subregion of an existing
21937 two-dimensional texture image. The texels referenced by @var{data}
21938 replace the portion of the existing texture array with x indices
21939 @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive, and y
21940 indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive.
21941 This region may not include any texels outside the range of the texture
21942 array as it was originally specified. It is not an error to specify a
21943 subtexture with zero width or height, but such a specification has no
21946 If a non-zero named buffer object is bound to the
21947 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
21948 texture image is specified, @var{data} is treated as a byte offset into
21949 the buffer object's data store.
21951 @code{GL_INVALID_ENUM} is generated if @var{target} is not
21952 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
21953 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
21954 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
21955 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
21956 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
21957 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
21959 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
21962 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
21965 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
21966 and @var{format} is not @code{GL_COLOR_INDEX}.
21968 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
21970 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
21971 @r{@var{log}_2}@var{max}, where @var{max} is the returned value of
21972 @code{GL_MAX_TEXTURE_SIZE}.
21974 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}},
21975 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)},
21976 @r{@var{yoffset}<-@var{b}}, or
21977 @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, where @r{@var{w}}
21978 is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the
21979 @code{GL_TEXTURE_HEIGHT}, and @r{@var{b}} is the border width of the
21980 texture image being modified. Note that @r{@var{w}} and @r{@var{h}}
21981 include twice the border width.
21983 @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is
21986 @code{GL_INVALID_OPERATION} is generated if the texture array has not
21987 been defined by a previous @code{glTexImage2D} operation.
21989 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21990 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
21991 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
21992 and @var{format} is not @code{GL_RGB}.
21994 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21995 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
21996 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
21997 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
21998 @code{GL_UNSIGNED_INT_10_10_10_2}, or
21999 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
22000 @code{GL_RGBA} nor @code{GL_BGRA}.
22002 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
22003 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
22004 object's data store is currently mapped.
22006 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
22007 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
22008 would be unpacked from the buffer object such that the memory reads
22009 required would exceed the data store size.
22011 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
22012 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
22013 is not evenly divisible into the number of bytes needed to store in
22014 memory a datum indicated by @var{type}.
22016 @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage2D} is
22017 executed between the execution of @code{glBegin} and the corresponding
22018 execution of @code{glEnd}.
22022 @deftypefun void glTexSubImage3D target level xoffset yoffset zoffset width height depth format type data
22023 Specify a three-dimensional texture subimage.
22027 Specifies the target texture. Must be @code{GL_TEXTURE_3D}.
22030 Specifies the level-of-detail number. Level 0 is the base image level.
22031 Level @var{n} is the @var{n}th mipmap reduction image.
22033 @item @var{xoffset}
22034 Specifies a texel offset in the x direction within the texture array.
22036 @item @var{yoffset}
22037 Specifies a texel offset in the y direction within the texture array.
22039 @item @var{zoffset}
22040 Specifies a texel offset in the z direction within the texture array.
22043 Specifies the width of the texture subimage.
22046 Specifies the height of the texture subimage.
22049 Specifies the depth of the texture subimage.
22052 Specifies the format of the pixel data. The following symbolic values
22053 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
22054 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
22055 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
22056 @code{GL_LUMINANCE_ALPHA}.
22059 Specifies the data type of the pixel data. The following symbolic values
22060 are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
22061 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
22062 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
22063 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
22064 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
22065 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
22066 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
22067 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
22068 and @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
22071 Specifies a pointer to the image data in memory.
22075 Texturing maps a portion of a specified texture image onto each
22076 graphical primitive for which texturing is enabled. To enable and
22077 disable three-dimensional texturing, call @code{glEnable} and
22078 @code{glDisable} with argument @code{GL_TEXTURE_3D}.
22080 @code{glTexSubImage3D} redefines a contiguous subregion of an existing
22081 three-dimensional texture image. The texels referenced by @var{data}
22082 replace the portion of the existing texture array with x indices
22083 @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive, y indices
22084 @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive, and z
22085 indices @var{zoffset} and @r{@var{zoffset}+@var{depth}-1}, inclusive.
22086 This region may not include any texels outside the range of the texture
22087 array as it was originally specified. It is not an error to specify a
22088 subtexture with zero width, height, or depth but such a specification
22091 If a non-zero named buffer object is bound to the
22092 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
22093 texture image is specified, @var{data} is treated as a byte offset into
22094 the buffer object's data store.
22096 @code{GL_INVALID_ENUM} is generated if /@var{target} is not
22097 @code{GL_TEXTURE_3D}.
22099 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
22102 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
22105 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
22106 and @var{format} is not @code{GL_COLOR_INDEX}.
22108 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
22110 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
22111 @r{@var{log}_2}@var{max}, where @var{max} is the returned value of
22112 @code{GL_MAX_TEXTURE_SIZE}.
22114 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}},
22115 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)},
22116 @r{@var{yoffset}<-@var{b}}, or
22117 @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, or
22118 @r{@var{zoffset}<-@var{b}}, or
22119 @r{(@var{zoffset}+@var{depth},)>(@var{d}-@var{b},)}, where @r{@var{w}}
22120 is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the
22121 @code{GL_TEXTURE_HEIGHT}, @r{@var{d}} is the @code{GL_TEXTURE_DEPTH} and
22122 @r{@var{b}} is the border width of the texture image being modified.
22123 Note that @r{@var{w}}, @r{@var{h}}, and @r{@var{d}} include twice the
22126 @code{GL_INVALID_VALUE} is generated if @var{width}, @var{height}, or
22127 @var{depth} is less than 0.
22129 @code{GL_INVALID_OPERATION} is generated if the texture array has not
22130 been defined by a previous @code{glTexImage3D} operation.
22132 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
22133 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
22134 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
22135 and @var{format} is not @code{GL_RGB}.
22137 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
22138 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
22139 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
22140 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
22141 @code{GL_UNSIGNED_INT_10_10_10_2}, or
22142 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
22143 @code{GL_RGBA} nor @code{GL_BGRA}.
22145 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
22146 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
22147 object's data store is currently mapped.
22149 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
22150 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
22151 would be unpacked from the buffer object such that the memory reads
22152 required would exceed the data store size.
22154 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
22155 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
22156 is not evenly divisible into the number of bytes needed to store in
22157 memory a datum indicated by @var{type}.
22159 @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage3D} is
22160 executed between the execution of @code{glBegin} and the corresponding
22161 execution of @code{glEnd}.
22165 @deftypefun void glTranslated x y z
22166 @deftypefunx void glTranslatef x y z
22167 Multiply the current matrix by a translation matrix.
22173 Specify the @var{x}, @var{y}, and @var{z} coordinates of a translation
22178 @code{glTranslate} produces a translation by
22179 @r{(@var{x},@var{y}@var{z})}. The current matrix (see
22180 @code{glMatrixMode}) is multiplied by this translation matrix, with the
22181 product replacing the current matrix, as if @code{glMultMatrix} were
22182 called with the following matrix for its argument:
22184 @r{((1 0 0 @var{x}), (0 1 0 @var{y}), (0 0 1 @var{z}), (0 0 0 1),)}
22188 If the matrix mode is either @code{GL_MODELVIEW} or
22189 @code{GL_PROJECTION}, all objects drawn after a call to
22190 @code{glTranslate} are translated.
22192 Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the
22193 untranslated coordinate system.
22195 @code{GL_INVALID_OPERATION} is generated if @code{glTranslate} is
22196 executed between the execution of @code{glBegin} and the corresponding
22197 execution of @code{glEnd}.
22201 @deftypefun void glUniform1f location v0
22202 @deftypefunx void glUniform2f location v0 v1
22203 @deftypefunx void glUniform3f location v0 v1 v2
22204 @deftypefunx void glUniform4f location v0 v1 v2 v3
22205 @deftypefunx void glUniform1i location v0
22206 @deftypefunx void glUniform2i location v0 v1
22207 @deftypefunx void glUniform3i location v0 v1 v2
22208 @deftypefunx void glUniform4i location v0 v1 v2 v3
22209 @deftypefunx void glUniform1fv location count value
22210 @deftypefunx void glUniform2fv location count value
22211 @deftypefunx void glUniform3fv location count value
22212 @deftypefunx void glUniform4fv location count value
22213 @deftypefunx void glUniform1iv location count value
22214 @deftypefunx void glUniform2iv location count value
22215 @deftypefunx void glUniform3iv location count value
22216 @deftypefunx void glUniform4iv location count value
22217 @deftypefunx void glUniformMatrix2fv location count transpose value
22218 @deftypefunx void glUniformMatrix3fv location count transpose value
22219 @deftypefunx void glUniformMatrix4fv location count transpose value
22220 @deftypefunx void glUniformMatrix2x3fv location count transpose value
22221 @deftypefunx void glUniformMatrix3x2fv location count transpose value
22222 @deftypefunx void glUniformMatrix2x4fv location count transpose value
22223 @deftypefunx void glUniformMatrix4x2fv location count transpose value
22224 @deftypefunx void glUniformMatrix3x4fv location count transpose value
22225 @deftypefunx void glUniformMatrix4x3fv location count transpose value
22226 Specify the value of a uniform variable for the current program object.
22229 @item @var{location}
22230 Specifies the location of the uniform variable to be modified.
22232 @item @var{v0}, @var{v1}, @var{v2}, @var{v3}
22233 Specifies the new values to be used for the specified uniform variable.
22237 @code{glUniform} modifies the value of a uniform variable or a uniform
22238 variable array. The location of the uniform variable to be modified is
22239 specified by @var{location}, which should be a value returned by
22240 @code{glGetUniformLocation}. @code{glUniform} operates on the program
22241 object that was made part of current state by calling
22242 @code{glUseProgram}.
22244 The commands @code{glUniform@{1|2|3|4@}@{f|i@}} are used to change the
22245 value of the uniform variable specified by @var{location} using the
22246 values passed as arguments. The number specified in the command should
22247 match the number of components in the data type of the specified uniform
22248 variable (e.g., @code{1} for float, int, bool; @code{2} for vec2, ivec2,
22249 bvec2, etc.). The suffix @code{f} indicates that floating-point values
22250 are being passed; the suffix @code{i} indicates that integer values are
22251 being passed, and this type should also match the data type of the
22252 specified uniform variable. The @code{i} variants of this function
22253 should be used to provide values for uniform variables defined as int,
22254 ivec2, ivec3, ivec4, or arrays of these. The @code{f} variants should be
22255 used to provide values for uniform variables of type float, vec2, vec3,
22256 vec4, or arrays of these. Either the @code{i} or the @code{f} variants
22257 may be used to provide values for uniform variables of type bool, bvec2,
22258 bvec3, bvec4, or arrays of these. The uniform variable will be set to
22259 false if the input value is 0 or 0.0f, and it will be set to true
22262 All active uniform variables defined in a program object are initialized
22263 to 0 when the program object is linked successfully. They retain the
22264 values assigned to them by a call to @code{glUniform } until the next
22265 successful link operation occurs on the program object, when they are
22266 once again initialized to 0.
22268 The commands @code{glUniform@{1|2|3|4@}@{f|i@}v} can be used to modify a
22269 single uniform variable or a uniform variable array. These commands pass
22270 a count and a pointer to the values to be loaded into a uniform variable
22271 or a uniform variable array. A count of 1 should be used if modifying
22272 the value of a single uniform variable, and a count of 1 or greater can
22273 be used to modify an entire array or part of an array. When loading
22274 @var{n} elements starting at an arbitrary position @var{m} in a uniform
22275 variable array, elements @var{m} + @var{n} - 1 in the array will be
22276 replaced with the new values. If @var{m} + @var{n} - 1 is larger than
22277 the size of the uniform variable array, values for all array elements
22278 beyond the end of the array will be ignored. The number specified in the
22279 name of the command indicates the number of components for each element
22280 in @var{value}, and it should match the number of components in the data
22281 type of the specified uniform variable (e.g., @code{1} for float, int,
22282 bool; @code{2} for vec2, ivec2, bvec2, etc.). The data type specified in
22283 the name of the command must match the data type for the specified
22284 uniform variable as described previously for
22285 @code{glUniform@{1|2|3|4@}@{f|i@}}.
22287 For uniform variable arrays, each element of the array is considered to
22288 be of the type indicated in the name of the command (e.g.,
22289 @code{glUniform3f} or @code{glUniform3fv} can be used to load a uniform
22290 variable array of type vec3). The number of elements of the uniform
22291 variable array to be modified is specified by @var{count}
22293 The commands @code{glUniformMatrix@{2|3|4|2x3|3x2|2x4|4x2|3x4|4x3@}fv}
22294 are used to modify a matrix or an array of matrices. The numbers in the
22295 command name are interpreted as the dimensionality of the matrix. The
22296 number @code{2} indicates a 2 × 2 matrix (i.e., 4 values), the number
22297 @code{3} indicates a 3 × 3 matrix (i.e., 9 values), and the number
22298 @code{4} indicates a 4 × 4 matrix (i.e., 16 values). Non-square matrix
22299 dimensionality is explicit, with the first number representing the
22300 number of columns and the second number representing the number of rows.
22301 For example, @code{2x4} indicates a 2 × 4 matrix with 2 columns and 4
22302 rows (i.e., 8 values). If @var{transpose} is @code{GL_FALSE}, each
22303 matrix is assumed to be supplied in column major order. If
22304 @var{transpose} is @code{GL_TRUE}, each matrix is assumed to be supplied
22305 in row major order. The @var{count} argument indicates the number of
22306 matrices to be passed. A count of 1 should be used if modifying the
22307 value of a single matrix, and a count greater than 1 can be used to
22308 modify an array of matrices.
22310 @code{GL_INVALID_OPERATION} is generated if there is no current program
22313 @code{GL_INVALID_OPERATION} is generated if the size of the uniform
22314 variable declared in the shader does not match the size indicated by the
22315 @code{glUniform} command.
22317 @code{GL_INVALID_OPERATION} is generated if one of the integer variants
22318 of this function is used to load a uniform variable of type float, vec2,
22319 vec3, vec4, or an array of these, or if one of the floating-point
22320 variants of this function is used to load a uniform variable of type
22321 int, ivec2, ivec3, or ivec4, or an array of these.
22323 @code{GL_INVALID_OPERATION} is generated if @var{location} is an invalid
22324 uniform location for the current program object and @var{location} is
22327 @code{GL_INVALID_VALUE} is generated if @var{count} is less than 0.
22329 @code{GL_INVALID_OPERATION} is generated if @var{count} is greater than
22330 1 and the indicated uniform variable is not an array variable.
22332 @code{GL_INVALID_OPERATION} is generated if a sampler is loaded using a
22333 command other than @code{glUniform1i} and @code{glUniform1iv}.
22335 @code{GL_INVALID_OPERATION} is generated if @code{glUniform} is executed
22336 between the execution of @code{glBegin} and the corresponding execution
22341 @deftypefun void glUseProgram program
22342 Installs a program object as part of current rendering state.
22345 @item @var{program}
22346 Specifies the handle of the program object whose executables are to be
22347 used as part of current rendering state.
22351 @code{glUseProgram} installs the program object specified by
22352 @var{program} as part of current rendering state. One or more
22353 executables are created in a program object by successfully attaching
22354 shader objects to it with @code{glAttachShader}, successfully compiling
22355 the shader objects with @code{glCompileShader}, and successfully linking
22356 the program object with @code{glLinkProgram}.
22358 A program object will contain an executable that will run on the vertex
22359 processor if it contains one or more shader objects of type
22360 @code{GL_VERTEX_SHADER} that have been successfully compiled and linked.
22361 Similarly, a program object will contain an executable that will run on
22362 the fragment processor if it contains one or more shader objects of type
22363 @code{GL_FRAGMENT_SHADER} that have been successfully compiled and
22366 Successfully installing an executable on a programmable processor will
22367 cause the corresponding fixed functionality of OpenGL to be disabled.
22368 Specifically, if an executable is installed on the vertex processor, the
22369 OpenGL fixed functionality will be disabled as follows.
22373 The modelview matrix is not applied to vertex coordinates.
22376 The projection matrix is not applied to vertex coordinates.
22379 The texture matrices are not applied to texture coordinates.
22382 Normals are not transformed to eye coordinates.
22385 Normals are not rescaled or normalized.
22388 Normalization of @code{GL_AUTO_NORMAL} evaluated normals is not
22392 Texture coordinates are not generated automatically.
22395 Per-vertex lighting is not performed.
22398 Color material computations are not performed.
22401 Color index lighting is not performed.
22404 This list also applies when setting the current raster position.
22408 The executable that is installed on the vertex processor is expected to
22409 implement any or all of the desired functionality from the preceding
22410 list. Similarly, if an executable is installed on the fragment
22411 processor, the OpenGL fixed functionality will be disabled as follows.
22415 Texture environment and texture functions are not applied.
22418 Texture application is not applied.
22421 Color sum is not applied.
22424 Fog is not applied.
22428 Again, the fragment shader that is installed is expected to implement
22429 any or all of the desired functionality from the preceding list.
22431 While a program object is in use, applications are free to modify
22432 attached shader objects, compile attached shader objects, attach
22433 additional shader objects, and detach or delete shader objects. None of
22434 these operations will affect the executables that are part of the
22435 current state. However, relinking the program object that is currently
22436 in use will install the program object as part of the current rendering
22437 state if the link operation was successful (see @code{glLinkProgram} ).
22438 If the program object currently in use is relinked unsuccessfully, its
22439 link status will be set to @code{GL_FALSE}, but the executables and
22440 associated state will remain part of the current state until a
22441 subsequent call to @code{glUseProgram} removes it from use. After it is
22442 removed from use, it cannot be made part of current state until it has
22443 been successfully relinked.
22445 If @var{program} contains shader objects of type @code{GL_VERTEX_SHADER}
22446 but it does not contain shader objects of type
22447 @code{GL_FRAGMENT_SHADER}, an executable will be installed on the vertex
22448 processor, but fixed functionality will be used for fragment processing.
22449 Similarly, if @var{program} contains shader objects of type
22450 @code{GL_FRAGMENT_SHADER} but it does not contain shader objects of type
22451 @code{GL_VERTEX_SHADER}, an executable will be installed on the fragment
22452 processor, but fixed functionality will be used for vertex processing.
22453 If @var{program} is 0, the programmable processors will be disabled, and
22454 fixed functionality will be used for both vertex and fragment
22457 @code{GL_INVALID_VALUE} is generated if @var{program} is neither 0 nor a
22458 value generated by OpenGL.
22460 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
22463 @code{GL_INVALID_OPERATION} is generated if @var{program} could not be
22464 made part of current state.
22466 @code{GL_INVALID_OPERATION} is generated if @code{glUseProgram} is
22467 executed between the execution of @code{glBegin} and the corresponding
22468 execution of @code{glEnd}.
22472 @deftypefun void glValidateProgram program
22473 Validates a program object.
22476 @item @var{program}
22477 Specifies the handle of the program object to be validated.
22481 @code{glValidateProgram} checks to see whether the executables contained
22482 in @var{program} can execute given the current OpenGL state. The
22483 information generated by the validation process will be stored in
22484 @var{program}'s information log. The validation information may consist
22485 of an empty string, or it may be a string containing information about
22486 how the current program object interacts with the rest of current OpenGL
22487 state. This provides a way for OpenGL implementers to convey more
22488 information about why the current program is inefficient, suboptimal,
22489 failing to execute, and so on.
22491 The status of the validation operation will be stored as part of the
22492 program object's state. This value will be set to @code{GL_TRUE} if the
22493 validation succeeded, and @code{GL_FALSE} otherwise. It can be queried
22494 by calling @code{glGetProgram} with arguments @var{program} and
22495 @code{GL_VALIDATE_STATUS}. If validation is successful, @var{program} is
22496 guaranteed to execute given the current state. Otherwise, @var{program}
22497 is guaranteed to not execute.
22499 This function is typically useful only during application development.
22500 The informational string stored in the information log is completely
22501 implementation dependent; therefore, an application should not expect
22502 different OpenGL implementations to produce identical information
22505 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
22506 generated by OpenGL.
22508 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
22511 @code{GL_INVALID_OPERATION} is generated if @code{glValidateProgram} is
22512 executed between the execution of @code{glBegin} and the corresponding
22513 execution of @code{glEnd}.
22517 @deftypefun void glVertexAttribPointer index size type normalized stride pointer
22518 Define an array of generic vertex attribute data.
22522 Specifies the index of the generic vertex attribute to be modified.
22525 Specifies the number of components per generic vertex attribute. Must be
22526 1, 2, 3, or 4. The initial value is 4.
22529 Specifies the data type of each component in the array. Symbolic
22530 constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
22531 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
22532 @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is
22535 @item @var{normalized}
22536 Specifies whether fixed-point data values should be normalized
22537 (@code{GL_TRUE}) or converted directly as fixed-point values
22538 (@code{GL_FALSE}) when they are accessed.
22541 Specifies the byte offset between consecutive generic vertex attributes.
22542 If @var{stride} is 0, the generic vertex attributes are understood to be
22543 tightly packed in the array. The initial value is 0.
22545 @item @var{pointer}
22546 Specifies a pointer to the first component of the first generic vertex
22547 attribute in the array. The initial value is 0.
22551 @code{glVertexAttribPointer} specifies the location and data format of
22552 the array of generic vertex attributes at index @var{index} to use when
22553 rendering. @var{size} specifies the number of components per attribute
22554 and must be 1, 2, 3, or 4. @var{type} specifies the data type of each
22555 component, and @var{stride} specifies the byte stride from one attribute
22556 to the next, allowing vertices and attributes to be packed into a single
22557 array or stored in separate arrays. If set to @code{GL_TRUE},
22558 @var{normalized} indicates that values stored in an integer format are
22559 to be mapped to the range [-1,1] (for signed values) or [0,1] (for
22560 unsigned values) when they are accessed and converted to floating point.
22561 Otherwise, values will be converted to floats directly without
22564 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
22565 target (see @code{glBindBuffer}) while a generic vertex attribute array
22566 is specified, @var{pointer} is treated as a byte offset into the buffer
22567 object's data store. Also, the buffer object binding
22568 (@code{GL_ARRAY_BUFFER_BINDING}) is saved as generic vertex attribute
22569 array client-side state (@code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING})
22570 for index @var{index}.
22572 When a generic vertex attribute array is specified, @var{size},
22573 @var{type}, @var{normalized}, @var{stride}, and @var{pointer} are saved
22574 as client-side state, in addition to the current vertex array buffer
22577 To enable and disable a generic vertex attribute array, call
22578 @code{glEnableVertexAttribArray} and @code{glDisableVertexAttribArray}
22579 with @var{index}. If enabled, the generic vertex attribute array is used
22580 when @code{glArrayElement}, @code{glDrawArrays},
22581 @code{glMultiDrawArrays}, @code{glDrawElements},
22582 @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called.
22584 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
22585 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
22587 @code{GL_INVALID_VALUE} is generated if @var{size} is not 1, 2, 3, or 4.
22589 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
22592 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
22596 @deftypefun void glVertexAttrib1f index v0
22597 @deftypefunx void glVertexAttrib1s index v0
22598 @deftypefunx void glVertexAttrib1d index v0
22599 @deftypefunx void glVertexAttrib2f index v0 v1
22600 @deftypefunx void glVertexAttrib2s index v0 v1
22601 @deftypefunx void glVertexAttrib2d index v0 v1
22602 @deftypefunx void glVertexAttrib3f index v0 v1 v2
22603 @deftypefunx void glVertexAttrib3s index v0 v1 v2
22604 @deftypefunx void glVertexAttrib3d index v0 v1 v2
22605 @deftypefunx void glVertexAttrib4f index v0 v1 v2 v3
22606 @deftypefunx void glVertexAttrib4s index v0 v1 v2 v3
22607 @deftypefunx void glVertexAttrib4d index v0 v1 v2 v3
22608 @deftypefunx void glVertexAttrib4Nub index v0 v1 v2 v3
22609 @deftypefunx void glVertexAttrib1fv index v
22610 @deftypefunx void glVertexAttrib1sv index v
22611 @deftypefunx void glVertexAttrib1dv index v
22612 @deftypefunx void glVertexAttrib2fv index v
22613 @deftypefunx void glVertexAttrib2sv index v
22614 @deftypefunx void glVertexAttrib2dv index v
22615 @deftypefunx void glVertexAttrib3fv index v
22616 @deftypefunx void glVertexAttrib3sv index v
22617 @deftypefunx void glVertexAttrib3dv index v
22618 @deftypefunx void glVertexAttrib4fv index v
22619 @deftypefunx void glVertexAttrib4sv index v
22620 @deftypefunx void glVertexAttrib4dv index v
22621 @deftypefunx void glVertexAttrib4iv index v
22622 @deftypefunx void glVertexAttrib4bv index v
22623 @deftypefunx void glVertexAttrib4ubv index v
22624 @deftypefunx void glVertexAttrib4usv index v
22625 @deftypefunx void glVertexAttrib4uiv index v
22626 @deftypefunx void glVertexAttrib4Nbv index v
22627 @deftypefunx void glVertexAttrib4Nsv index v
22628 @deftypefunx void glVertexAttrib4Niv index v
22629 @deftypefunx void glVertexAttrib4Nubv index v
22630 @deftypefunx void glVertexAttrib4Nusv index v
22631 @deftypefunx void glVertexAttrib4Nuiv index v
22632 Specifies the value of a generic vertex attribute.
22636 Specifies the index of the generic vertex attribute to be modified.
22638 @item @var{v0}, @var{v1}, @var{v2}, @var{v3}
22639 Specifies the new values to be used for the specified vertex attribute.
22643 OpenGL defines a number of standard vertex attributes that applications
22644 can modify with standard API entry points (color, normal, texture
22645 coordinates, etc.). The @code{glVertexAttrib} family of entry points
22646 allows an application to pass generic vertex attributes in numbered
22649 Generic attributes are defined as four-component values that are
22650 organized into an array. The first entry of this array is numbered 0,
22651 and the size of the array is specified by the implementation-dependent
22652 constant @code{GL_MAX_VERTEX_ATTRIBS}. Individual elements of this array
22653 can be modified with a @code{glVertexAttrib} call that specifies the
22654 index of the element to be modified and a value for that element.
22656 These commands can be used to specify one, two, three, or all four
22657 components of the generic vertex attribute specified by @var{index}. A
22658 @code{1} in the name of the command indicates that only one value is
22659 passed, and it will be used to modify the first component of the generic
22660 vertex attribute. The second and third components will be set to 0, and
22661 the fourth component will be set to 1. Similarly, a @code{2} in the name
22662 of the command indicates that values are provided for the first two
22663 components, the third component will be set to 0, and the fourth
22664 component will be set to 1. A @code{3} in the name of the command
22665 indicates that values are provided for the first three components and
22666 the fourth component will be set to 1, whereas a @code{4} in the name
22667 indicates that values are provided for all four components.
22669 The letters @code{s}, @code{f}, @code{i}, @code{d}, @code{ub},
22670 @code{us}, and @code{ui} indicate whether the arguments are of type
22671 short, float, int, double, unsigned byte, unsigned short, or unsigned
22672 int. When @code{v} is appended to the name, the commands can take a
22673 pointer to an array of such values. The commands containing @code{N}
22674 indicate that the arguments will be passed as fixed-point values that
22675 are scaled to a normalized range according to the component conversion
22676 rules defined by the OpenGL specification. Signed values are understood
22677 to represent fixed-point values in the range [-1,1], and unsigned values
22678 are understood to represent fixed-point values in the range [0,1].
22680 OpenGL Shading Language attribute variables are allowed to be of type
22681 mat2, mat3, or mat4. Attributes of these types may be loaded using the
22682 @code{glVertexAttrib} entry points. Matrices must be loaded into
22683 successive generic attribute slots in column major order, with one
22684 column of the matrix in each generic attribute slot.
22686 A user-defined attribute variable declared in a vertex shader can be
22687 bound to a generic attribute index by calling
22688 @code{glBindAttribLocation}. This allows an application to use more
22689 descriptive variable names in a vertex shader. A subsequent change to
22690 the specified generic vertex attribute will be immediately reflected as
22691 a change to the corresponding attribute variable in the vertex shader.
22693 The binding between a generic vertex attribute index and a user-defined
22694 attribute variable in a vertex shader is part of the state of a program
22695 object, but the current value of the generic vertex attribute is not.
22696 The value of each generic vertex attribute is part of current state,
22697 just like standard vertex attributes, and it is maintained even if a
22698 different program object is used.
22700 An application may freely modify generic vertex attributes that are not
22701 bound to a named vertex shader attribute variable. These values are
22702 simply maintained as part of current state and will not be accessed by
22703 the vertex shader. If a generic vertex attribute bound to an attribute
22704 variable in a vertex shader is not updated while the vertex shader is
22705 executing, the vertex shader will repeatedly use the current value for
22706 the generic vertex attribute.
22708 The generic vertex attribute with index 0 is the same as the vertex
22709 position attribute previously defined by OpenGL. A @code{glVertex2},
22710 @code{glVertex3}, or @code{glVertex4} command is completely equivalent
22711 to the corresponding @code{glVertexAttrib} command with an index
22712 argument of 0. A vertex shader can access generic vertex attribute 0 by
22713 using the built-in attribute variable @var{gl_Vertex}. There are no
22714 current values for generic vertex attribute 0. This is the only generic
22715 vertex attribute with this property; calls to set other standard vertex
22716 attributes can be freely mixed with calls to set any of the other
22717 generic vertex attributes.
22719 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
22720 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
22724 @deftypefun void glVertexPointer size type stride pointer
22725 Define an array of vertex data.
22729 Specifies the number of coordinates per vertex. Must be 2, 3, or 4. The
22730 initial value is 4.
22733 Specifies the data type of each coordinate in the array. Symbolic
22734 constants @code{GL_SHORT}, @code{GL_INT}, @code{GL_FLOAT}, or
22735 @code{GL_DOUBLE} are accepted. The initial value is @code{GL_FLOAT}.
22738 Specifies the byte offset between consecutive vertices. If @var{stride}
22739 is 0, the vertices are understood to be tightly packed in the array. The
22740 initial value is 0.
22742 @item @var{pointer}
22743 Specifies a pointer to the first coordinate of the first vertex in the
22744 array. The initial value is 0.
22748 @code{glVertexPointer} specifies the location and data format of an
22749 array of vertex coordinates to use when rendering. @var{size} specifies
22750 the number of coordinates per vertex, and must be 2, 3, or 4. @var{type}
22751 specifies the data type of each coordinate, and @var{stride} specifies
22752 the byte stride from one vertex to the next, allowing vertices and
22753 attributes to be packed into a single array or stored in separate
22754 arrays. (Single-array storage may be more efficient on some
22755 implementations; see @code{glInterleavedArrays}.)
22757 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
22758 target (see @code{glBindBuffer}) while a vertex array is specified,
22759 @var{pointer} is treated as a byte offset into the buffer object's data
22760 store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING})
22761 is saved as vertex array client-side state
22762 (@code{GL_VERTEX_ARRAY_BUFFER_BINDING}).
22764 When a vertex array is specified, @var{size}, @var{type}, @var{stride},
22765 and @var{pointer} are saved as client-side state, in addition to the
22766 current vertex array buffer object binding.
22768 To enable and disable the vertex array, call @code{glEnableClientState}
22769 and @code{glDisableClientState} with the argument
22770 @code{GL_VERTEX_ARRAY}. If enabled, the vertex array is used when
22771 @code{glArrayElement}, @code{glDrawArrays}, @code{glMultiDrawArrays},
22772 @code{glDrawElements}, @code{glMultiDrawElements}, or
22773 @code{glDrawRangeElements} is called.
22775 @code{GL_INVALID_VALUE} is generated if @var{size} is not 2, 3, or 4.
22777 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
22780 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
22784 @deftypefun void glVertex2s x y
22785 @deftypefunx void glVertex2i x y
22786 @deftypefunx void glVertex2f x y
22787 @deftypefunx void glVertex2d x y
22788 @deftypefunx void glVertex3s x y z
22789 @deftypefunx void glVertex3i x y z
22790 @deftypefunx void glVertex3f x y z
22791 @deftypefunx void glVertex3d x y z
22792 @deftypefunx void glVertex4s x y z w
22793 @deftypefunx void glVertex4i x y z w
22794 @deftypefunx void glVertex4f x y z w
22795 @deftypefunx void glVertex4d x y z w
22796 @deftypefunx void glVertex2sv v
22797 @deftypefunx void glVertex2iv v
22798 @deftypefunx void glVertex2fv v
22799 @deftypefunx void glVertex2dv v
22800 @deftypefunx void glVertex3sv v
22801 @deftypefunx void glVertex3iv v
22802 @deftypefunx void glVertex3fv v
22803 @deftypefunx void glVertex3dv v
22804 @deftypefunx void glVertex4sv v
22805 @deftypefunx void glVertex4iv v
22806 @deftypefunx void glVertex4fv v
22807 @deftypefunx void glVertex4dv v
22815 Specify @var{x}, @var{y}, @var{z}, and @var{w} coordinates of a vertex.
22816 Not all parameters are present in all forms of the command.
22820 @code{glVertex} commands are used within @code{glBegin}/@code{glEnd}
22821 pairs to specify point, line, and polygon vertices. The current color,
22822 normal, texture coordinates, and fog coordinate are associated with the
22823 vertex when @code{glVertex} is called.
22825 When only @r{@var{x}} and @r{@var{y}} are specified, @r{@var{z}}
22826 defaults to 0 and @r{@var{w}} defaults to 1. When @r{@var{x}},
22827 @r{@var{y}}, and @r{@var{z}} are specified, @r{@var{w}} defaults to 1.
22831 @deftypefun void glViewport x y width height
22837 Specify the lower left corner of the viewport rectangle, in pixels. The
22838 initial value is (0,0).
22841 @itemx @var{height}
22842 Specify the width and height of the viewport. When a GL context is first
22843 attached to a window, @var{width} and @var{height} are set to the
22844 dimensions of that window.
22848 @code{glViewport} specifies the affine transformation of @r{@var{x}} and
22849 @r{@var{y}} from normalized device coordinates to window coordinates.
22850 Let @r{(@var{x}_@var{nd},@var{y}_@var{nd})} be normalized device
22851 coordinates. Then the window coordinates
22852 @r{(@var{x}_@var{w},@var{y}_@var{w})} are computed as follows:
22854 @r{@var{x}_@var{w}=(@var{x}_@var{nd}+1,)(@var{width}/2,)+@var{x}}
22856 @r{@var{y}_@var{w}=(@var{y}_@var{nd}+1,)(@var{height}/2,)+@var{y}}
22858 Viewport width and height are silently clamped to a range that depends
22859 on the implementation. To query this range, call @code{glGet} with
22860 argument @code{GL_MAX_VIEWPORT_DIMS}.
22862 @code{GL_INVALID_VALUE} is generated if either @var{width} or
22863 @var{height} is negative.
22865 @code{GL_INVALID_OPERATION} is generated if @code{glViewport} is
22866 executed between the execution of @code{glBegin} and the corresponding
22867 execution of @code{glEnd}.
22871 @deftypefun void glWindowPos2s x y
22872 @deftypefunx void glWindowPos2i x y
22873 @deftypefunx void glWindowPos2f x y
22874 @deftypefunx void glWindowPos2d x y
22875 @deftypefunx void glWindowPos3s x y z
22876 @deftypefunx void glWindowPos3i x y z
22877 @deftypefunx void glWindowPos3f x y z
22878 @deftypefunx void glWindowPos3d x y z
22879 @deftypefunx void glWindowPos2sv v
22880 @deftypefunx void glWindowPos2iv v
22881 @deftypefunx void glWindowPos2fv v
22882 @deftypefunx void glWindowPos2dv v
22883 @deftypefunx void glWindowPos3sv v
22884 @deftypefunx void glWindowPos3iv v
22885 @deftypefunx void glWindowPos3fv v
22886 @deftypefunx void glWindowPos3dv v
22887 Specify the raster position in window coordinates for pixel operations.
22893 Specify the @r{@var{x}}, @r{@var{y}}, @r{@var{z}} coordinates for the
22898 The GL maintains a 3D position in window coordinates. This position,
22899 called the raster position, is used to position pixel and bitmap write
22900 operations. It is maintained with subpixel accuracy. See
22901 @code{glBitmap}, @code{glDrawPixels}, and @code{glCopyPixels}.
22903 @code{glWindowPos2} specifies the @r{@var{x}} and @r{@var{y}}
22904 coordinates, while @r{@var{z}} is implicitly set to 0.
22905 @code{glWindowPos3} specifies all three coordinates. The @r{@var{w}}
22906 coordinate of the current raster position is always set to 1.0.
22908 @code{glWindowPos} directly updates the @r{@var{x}} and @r{@var{y}}
22909 coordinates of the current raster position with the values specified.
22910 That is, the values are neither transformed by the current modelview and
22911 projection matrices, nor by the viewport-to-window transform. The
22912 @r{@var{z}} coordinate of the current raster position is updated in the
22915 @r{@var{z}=@{(@var{n}), (@var{f}),
22916 (@var{n}+@var{z}×(@var{f}-@var{n},),)(@var{if}@var{z}<=0),
22917 (@var{if}@var{z}>=1), (@code{otherwise},),}
22921 where @r{@var{n}} is @code{GL_DEPTH_RANGE}'s near value, and @r{@var{f}}
22922 is @code{GL_DEPTH_RANGE}'s far value. See @code{glDepthRange}.
22924 The specified coordinates are not clip-tested, causing the raster
22925 position to always be valid.
22927 The current raster position also includes some associated color data and
22928 texture coordinates. If lighting is enabled, then
22929 @code{GL_CURRENT_RASTER_COLOR} (in RGBA mode) or
22930 @code{GL_CURRENT_RASTER_INDEX} (in color index mode) is set to the color
22931 produced by the lighting calculation (see @code{glLight},
22932 @code{glLightModel}, and @code{glShadeModel}). If lighting is disabled,
22933 current color (in RGBA mode, state variable @code{GL_CURRENT_COLOR}) or
22934 color index (in color index mode, state variable
22935 @code{GL_CURRENT_INDEX}) is used to update the current raster color.
22936 @code{GL_CURRENT_RASTER_SECONDARY_COLOR} (in RGBA mode) is likewise
22939 Likewise, @code{GL_CURRENT_RASTER_TEXTURE_COORDS} is updated as a
22940 function of @code{GL_CURRENT_TEXTURE_COORDS}, based on the texture
22941 matrix and the texture generation functions (see @code{glTexGen}). The
22942 @code{GL_CURRENT_RASTER_DISTANCE} is set to the
22943 @code{GL_CURRENT_FOG_COORD}.
22947 @code{GL_INVALID_OPERATION} is generated if @code{glWindowPos} is
22948 executed between the execution of @code{glBegin} and the corresponding
22949 execution of @code{glEnd}.
22954 @c %end of fragment