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 glColor3i red green blue
2482 @deftypefunx void glColor3f red green blue
2483 @deftypefunx void glColor3ui red green blue
2484 @deftypefunx void glColor4i red green blue alpha
2485 @deftypefunx void glColor4f red green blue alpha
2486 @deftypefunx void glColor4ui red green blue alpha
2487 Set the current color.
2493 Specify new red, green, and blue values for the current color.
2496 Specifies a new alpha value for the current color. Included only in the
2497 four-argument @code{glColor4} commands.
2501 The GL stores both a current single-valued color index and a current
2502 four-valued RGBA color. @code{glColor} sets a new four-valued RGBA
2503 color. @code{glColor} has two major variants: @code{glColor3} and
2504 @code{glColor4}. @code{glColor3} variants specify new red, green, and
2505 blue values explicitly and set the current alpha value to 1.0 (full
2506 intensity) implicitly. @code{glColor4} variants specify all four color
2507 components explicitly.
2509 @code{glColor3b}, @code{glColor4b}, @code{glColor3s}, @code{glColor4s},
2510 @code{glColor3i}, and @code{glColor4i} take three or four signed byte,
2511 short, or long integers as arguments. When @strong{v} is appended to the
2512 name, the color commands can take a pointer to an array of such values.
2514 Current color values are stored in floating-point format, with
2515 unspecified mantissa and exponent sizes. Unsigned integer color
2516 components, when specified, are linearly mapped to floating-point values
2517 such that the largest representable value maps to 1.0 (full intensity),
2518 and 0 maps to 0.0 (zero intensity). Signed integer color components,
2519 when specified, are linearly mapped to floating-point values such that
2520 the most positive representable value maps to 1.0, and the most negative
2521 representable value maps to @r{-1.0}. (Note that this mapping does not
2522 convert 0 precisely to 0.0.) Floating-point values are mapped directly.
2524 Neither floating-point nor signed integer values are clamped to the
2525 range @r{[0,1]} before the current color is updated. However, color
2526 components are clamped to this range before they are interpolated or
2527 written into a color buffer.
2531 @deftypefun void glCompileShader shader
2532 Compiles a shader object.
2536 Specifies the shader object to be compiled.
2540 @code{glCompileShader} compiles the source code strings that have been
2541 stored in the shader object specified by @var{shader}.
2543 The compilation status will be stored as part of the shader object's
2544 state. This value will be set to @code{GL_TRUE} if the shader was
2545 compiled without errors and is ready for use, and @code{GL_FALSE}
2546 otherwise. It can be queried by calling @code{glGetShader} with
2547 arguments @var{shader} and @code{GL_COMPILE_STATUS}.
2549 Compilation of a shader can fail for a number of reasons as specified by
2550 the OpenGL Shading Language Specification. Whether or not the
2551 compilation was successful, information about the compilation can be
2552 obtained from the shader object's information log by calling
2553 @code{glGetShaderInfoLog}.
2555 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
2556 generated by OpenGL.
2558 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
2561 @code{GL_INVALID_OPERATION} is generated if @code{glCompileShader} is
2562 executed between the execution of @code{glBegin} and the corresponding
2563 execution of @code{glEnd}.
2567 @deftypefun void glCompressedTexImage1D target level internalformat width border imageSize data
2568 Specify a one-dimensional texture image in a compressed format.
2572 Specifies the target texture. Must be @code{GL_TEXTURE_1D} or
2573 @code{GL_PROXY_TEXTURE_1D}.
2576 Specifies the level-of-detail number. Level 0 is the base image level.
2577 Level @var{n} is the @var{n}th mipmap reduction image.
2579 @item @var{internalformat}
2580 Specifies the format of the compressed image data stored at address
2584 Specifies the width of the texture image including the border if any. If
2585 the GL version does not support non-power-of-two sizes, this value must
2586 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
2587 implementations support texture images that are at least 64 texels wide.
2588 The height of the 1D texture image is 1.
2591 Specifies the width of the border. Must be either 0 or 1.
2593 @item @var{imageSize}
2594 Specifies the number of unsigned bytes of image data starting at the
2595 address specified by @var{data}.
2598 Specifies a pointer to the compressed image data in memory.
2602 Texturing maps a portion of a specified texture image onto each
2603 graphical primitive for which texturing is enabled. To enable and
2604 disable one-dimensional texturing, call @code{glEnable} and
2605 @code{glDisable} with argument @code{GL_TEXTURE_1D}.
2607 @code{glCompressedTexImage1D} loads a previously defined, and retrieved,
2608 compressed one-dimensional texture image if @var{target} is
2609 @code{GL_TEXTURE_1D} (see @code{glTexImage1D}).
2611 If @var{target} is @code{GL_PROXY_TEXTURE_1D}, no data is read from
2612 @var{data}, but all of the texture image state is recalculated, checked
2613 for consistency, and checked against the implementation's capabilities.
2614 If the implementation cannot handle a texture of the requested texture
2615 size, it sets all of the image state to 0, but does not generate an
2616 error (see @code{glGetError}). To query for an entire mipmap array, use
2617 an image array level greater than or equal to 1.
2619 @var{internalformat} must be extension-specified compressed-texture
2620 format. When a texture is loaded with @code{glTexImage1D} using a
2621 generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}) the
2622 GL selects from one of its extensions supporting compressed textures. In
2623 order to load the compressed texture image using
2624 @code{glCompressedTexImage1D}, query the compressed texture image's size
2625 and format using @code{glGetTexLevelParameter}.
2627 If a non-zero named buffer object is bound to the
2628 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2629 texture image is specified, @var{data} is treated as a byte offset into
2630 the buffer object's data store.
2632 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of
2633 the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
2634 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
2635 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or
2636 @code{GL_COMPRESSED_RGBA}.
2638 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
2639 consistent with the format, dimensions, and contents of the specified
2640 compressed image data.
2642 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
2643 not supported by the specific compressed internal format as specified in
2644 the specific texture compression extension.
2646 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2647 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2648 object's data store is currently mapped.
2650 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2651 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2652 would be unpacked from the buffer object such that the memory reads
2653 required would exceed the data store size.
2655 @code{GL_INVALID_OPERATION} is generated if
2656 @code{glCompressedTexImage1D} is executed between the execution of
2657 @code{glBegin} and the corresponding execution of @code{glEnd}.
2659 Undefined results, including abnormal program termination, are generated
2660 if @var{data} is not encoded in a manner consistent with the extension
2661 specification defining the internal compression format.
2665 @deftypefun void glCompressedTexImage2D target level internalformat width height border imageSize data
2666 Specify a two-dimensional texture image in a compressed format.
2670 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
2671 @code{GL_PROXY_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
2672 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
2673 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
2674 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
2675 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z},
2676 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or
2677 @code{GL_PROXY_TEXTURE_CUBE_MAP}.
2680 Specifies the level-of-detail number. Level 0 is the base image level.
2681 Level @var{n} is the @var{n}th mipmap reduction image.
2683 @item @var{internalformat}
2684 Specifies the format of the compressed image data stored at address
2688 Specifies the width of the texture image including the border if any. If
2689 the GL version does not support non-power-of-two sizes, this value must
2690 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
2691 implementations support 2D texture images that are at least 64 texels
2692 wide and cube-mapped texture images that are at least 16 texels wide.
2695 Specifies the height of the texture image including the border if any.
2696 If the GL version does not support non-power-of-two sizes, this value
2697 must be Must be @r{2^@var{n}+2(@var{border},)} for some integer
2698 @r{@var{n}}. All implementations support 2D texture images that are at
2699 least 64 texels high and cube-mapped texture images that are at least 16
2703 Specifies the width of the border. Must be either 0 or 1.
2705 @item @var{imageSize}
2706 Specifies the number of unsigned bytes of image data starting at the
2707 address specified by @var{data}.
2710 Specifies a pointer to the compressed image data in memory.
2714 Texturing maps a portion of a specified texture image onto each
2715 graphical primitive for which texturing is enabled. To enable and
2716 disable two-dimensional texturing, call @code{glEnable} and
2717 @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and
2718 disable texturing using cube-mapped textures, call @code{glEnable} and
2719 @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}.
2721 @code{glCompressedTexImage2D} loads a previously defined, and retrieved,
2722 compressed two-dimensional texture image if @var{target} is
2723 @code{GL_TEXTURE_2D} (see @code{glTexImage2D}).
2725 If @var{target} is @code{GL_PROXY_TEXTURE_2D}, no data is read from
2726 @var{data}, but all of the texture image state is recalculated, checked
2727 for consistency, and checked against the implementation's capabilities.
2728 If the implementation cannot handle a texture of the requested texture
2729 size, it sets all of the image state to 0, but does not generate an
2730 error (see @code{glGetError}). To query for an entire mipmap array, use
2731 an image array level greater than or equal to 1.
2733 @var{internalformat} must be an extension-specified compressed-texture
2734 format. When a texture is loaded with @code{glTexImage2D} using a
2735 generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}), the
2736 GL selects from one of its extensions supporting compressed textures. In
2737 order to load the compressed texture image using
2738 @code{glCompressedTexImage2D}, query the compressed texture image's size
2739 and format using @code{glGetTexLevelParameter}.
2741 If a non-zero named buffer object is bound to the
2742 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2743 texture image is specified, @var{data} is treated as a byte offset into
2744 the buffer object's data store.
2746 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of
2747 the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
2748 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
2749 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or
2750 @code{GL_COMPRESSED_RGBA}.
2752 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
2753 consistent with the format, dimensions, and contents of the specified
2754 compressed image data.
2756 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
2757 not supported by the specific compressed internal format as specified in
2758 the specific texture compression extension.
2760 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2761 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2762 object's data store is currently mapped.
2764 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2765 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2766 would be unpacked from the buffer object such that the memory reads
2767 required would exceed the data store size.
2769 @code{GL_INVALID_OPERATION} is generated if
2770 @code{glCompressedTexImage2D} is executed between the execution of
2771 @code{glBegin} and the corresponding execution of @code{glEnd}.
2773 Undefined results, including abnormal program termination, are generated
2774 if @var{data} is not encoded in a manner consistent with the extension
2775 specification defining the internal compression format.
2779 @deftypefun void glCompressedTexImage3D target level internalformat width height depth border imageSize data
2780 Specify a three-dimensional texture image in a compressed format.
2784 Specifies the target texture. Must be @code{GL_TEXTURE_3D} or
2785 @code{GL_PROXY_TEXTURE_3D}.
2788 Specifies the level-of-detail number. Level 0 is the base image level.
2789 Level @var{n} is the @var{n}th mipmap reduction image.
2791 @item @var{internalformat}
2792 Specifies the format of the compressed image data stored at address
2796 Specifies the width of the texture image including the border if any. If
2797 the GL version does not support non-power-of-two sizes, this value must
2798 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
2799 implementations support 3D texture images that are at least 16 texels
2803 Specifies the height of the texture image including the border if any.
2804 If the GL version does not support non-power-of-two sizes, this value
2805 must be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}.
2806 All implementations support 3D texture images that are at least 16
2810 Specifies the depth of the texture image including the border if any. If
2811 the GL version does not support non-power-of-two sizes, this value must
2812 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
2813 implementations support 3D texture images that are at least 16 texels
2817 Specifies the width of the border. Must be either 0 or 1.
2819 @item @var{imageSize}
2820 Specifies the number of unsigned bytes of image data starting at the
2821 address specified by @var{data}.
2824 Specifies a pointer to the compressed image data in memory.
2828 Texturing maps a portion of a specified texture image onto each
2829 graphical primitive for which texturing is enabled. To enable and
2830 disable three-dimensional texturing, call @code{glEnable} and
2831 @code{glDisable} with argument @code{GL_TEXTURE_3D}.
2833 @code{glCompressedTexImage3D} loads a previously defined, and retrieved,
2834 compressed three-dimensional texture image if @var{target} is
2835 @code{GL_TEXTURE_3D} (see @code{glTexImage3D}).
2837 If @var{target} is @code{GL_PROXY_TEXTURE_3D}, no data is read from
2838 @var{data}, but all of the texture image state is recalculated, checked
2839 for consistency, and checked against the implementation's capabilities.
2840 If the implementation cannot handle a texture of the requested texture
2841 size, it sets all of the image state to 0, but does not generate an
2842 error (see @code{glGetError}). To query for an entire mipmap array, use
2843 an image array level greater than or equal to 1.
2845 @var{internalformat} must be an extension-specified compressed-texture
2846 format. When a texture is loaded with @code{glTexImage2D} using a
2847 generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}), the
2848 GL selects from one of its extensions supporting compressed textures. In
2849 order to load the compressed texture image using
2850 @code{glCompressedTexImage3D}, query the compressed texture image's size
2851 and format using @code{glGetTexLevelParameter}.
2853 If a non-zero named buffer object is bound to the
2854 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2855 texture image is specified, @var{data} is treated as a byte offset into
2856 the buffer object's data store.
2858 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of
2859 the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
2860 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
2861 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or
2862 @code{GL_COMPRESSED_RGBA}.
2864 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
2865 consistent with the format, dimensions, and contents of the specified
2866 compressed image data.
2868 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
2869 not supported by the specific compressed internal format as specified in
2870 the specific texture compression extension.
2872 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2873 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2874 object's data store is currently mapped.
2876 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2877 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2878 would be unpacked from the buffer object such that the memory reads
2879 required would exceed the data store size.
2881 @code{GL_INVALID_OPERATION} is generated if
2882 @code{glCompressedTexImage3D} is executed between the execution of
2883 @code{glBegin} and the corresponding execution of @code{glEnd}.
2885 Undefined results, including abnormal program termination, are generated
2886 if @var{data} is not encoded in a manner consistent with the extension
2887 specification defining the internal compression format.
2891 @deftypefun void glCompressedTexSubImage1D target level xoffset width format imageSize data
2892 Specify a one-dimensional texture subimage in a compressed format.
2896 Specifies the target texture. Must be @code{GL_TEXTURE_1D}.
2899 Specifies the level-of-detail number. Level 0 is the base image level.
2900 Level @var{n} is the @var{n}th mipmap reduction image.
2903 Specifies a texel offset in the x direction within the texture array.
2906 Specifies the width of the texture subimage.
2909 Specifies the format of the compressed image data stored at address
2912 @item @var{imageSize}
2913 Specifies the number of unsigned bytes of image data starting at the
2914 address specified by @var{data}.
2917 Specifies a pointer to the compressed image data in memory.
2921 Texturing maps a portion of a specified texture image onto each
2922 graphical primitive for which texturing is enabled. To enable and
2923 disable one-dimensional texturing, call @code{glEnable} and
2924 @code{glDisable} with argument @code{GL_TEXTURE_1D}.
2926 @code{glCompressedTexSubImage1D} redefines a contiguous subregion of an
2927 existing one-dimensional texture image. The texels referenced by
2928 @var{data} replace the portion of the existing texture array with x
2929 indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive.
2930 This region may not include any texels outside the range of the texture
2931 array as it was originally specified. It is not an error to specify a
2932 subtexture with width of 0, but such a specification has no effect.
2934 @var{format} must be an extension-specified compressed-texture format.
2935 The @var{format} of the compressed texture image is selected by the GL
2936 implementation that compressed it (see @code{glTexImage1D}), and should
2937 be queried at the time the texture was compressed with
2938 @code{glGetTexLevelParameter}.
2940 If a non-zero named buffer object is bound to the
2941 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2942 texture image is specified, @var{data} is treated as a byte offset into
2943 the buffer object's data store.
2945 @code{GL_INVALID_ENUM} is generated if @var{format} is one of these
2946 generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
2947 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
2948 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
2949 @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE},
2950 @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB},
2951 @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}.
2953 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
2954 consistent with the format, dimensions, and contents of the specified
2955 compressed image data.
2957 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
2958 not supported by the specific compressed internal format as specified in
2959 the specific texture compression extension.
2961 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2962 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2963 object's data store is currently mapped.
2965 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2966 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2967 would be unpacked from the buffer object such that the memory reads
2968 required would exceed the data store size.
2970 @code{GL_INVALID_OPERATION} is generated if
2971 @code{glCompressedTexSubImage1D} is executed between the execution of
2972 @code{glBegin} and the corresponding execution of @code{glEnd}.
2974 Undefined results, including abnormal program termination, are generated
2975 if @var{data} is not encoded in a manner consistent with the extension
2976 specification defining the internal compression format.
2980 @deftypefun void glCompressedTexSubImage2D target level xoffset yoffset width height format imageSize data
2981 Specify a two-dimensional texture subimage in a compressed format.
2985 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
2986 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
2987 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
2988 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
2989 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
2990 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
2991 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
2994 Specifies the level-of-detail number. Level 0 is the base image level.
2995 Level @var{n} is the @var{n}th mipmap reduction image.
2998 Specifies a texel offset in the x direction within the texture array.
3001 Specifies a texel offset in the y direction within the texture array.
3004 Specifies the width of the texture subimage.
3007 Specifies the height of the texture subimage.
3010 Specifies the format of the compressed image data stored at address
3013 @item @var{imageSize}
3014 Specifies the number of unsigned bytes of image data starting at the
3015 address specified by @var{data}.
3018 Specifies a pointer to the compressed image data in memory.
3022 Texturing maps a portion of a specified texture image onto each
3023 graphical primitive for which texturing is enabled. To enable and
3024 disable two-dimensional texturing, call @code{glEnable} and
3025 @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and
3026 disable texturing using cube-mapped texture, call @code{glEnable} and
3027 @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}.
3029 @code{glCompressedTexSubImage2D} redefines a contiguous subregion of an
3030 existing two-dimensional texture image. The texels referenced by
3031 @var{data} replace the portion of the existing texture array with x
3032 indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, and the y
3033 indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive.
3034 This region may not include any texels outside the range of the texture
3035 array as it was originally specified. It is not an error to specify a
3036 subtexture with width of 0, but such a specification has no effect.
3038 @var{format} must be an extension-specified compressed-texture format.
3039 The @var{format} of the compressed texture image is selected by the GL
3040 implementation that compressed it (see @code{glTexImage2D}) and should
3041 be queried at the time the texture was compressed with
3042 @code{glGetTexLevelParameter}.
3044 If a non-zero named buffer object is bound to the
3045 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
3046 texture image is specified, @var{data} is treated as a byte offset into
3047 the buffer object's data store.
3049 @code{GL_INVALID_ENUM} is generated if @var{format} is one of these
3050 generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
3051 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
3052 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
3053 @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE},
3054 @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB},
3055 @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}.
3057 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
3058 consistent with the format, dimensions, and contents of the specified
3059 compressed image data.
3061 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
3062 not supported by the specific compressed internal format as specified in
3063 the specific texture compression extension.
3065 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3066 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
3067 object's data store is currently mapped.
3069 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3070 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
3071 would be unpacked from the buffer object such that the memory reads
3072 required would exceed the data store size.
3074 @code{GL_INVALID_OPERATION} is generated if
3075 @code{glCompressedTexSubImage2D} is executed between the execution of
3076 @code{glBegin} and the corresponding execution of @code{glEnd}.
3078 Undefined results, including abnormal program termination, are generated
3079 if @var{data} is not encoded in a manner consistent with the extension
3080 specification defining the internal compression format.
3084 @deftypefun void glCompressedTexSubImage3D target level xoffset yoffset zoffset width height depth format imageSize data
3085 Specify a three-dimensional texture subimage in a compressed format.
3089 Specifies the target texture. Must be @code{GL_TEXTURE_3D}.
3092 Specifies the level-of-detail number. Level 0 is the base image level.
3093 Level @var{n} is the @var{n}th mipmap reduction image.
3096 Specifies a texel offset in the x direction within the texture array.
3099 Specifies a texel offset in the y direction within the texture array.
3102 Specifies the width of the texture subimage.
3105 Specifies the height of the texture subimage.
3108 Specifies the depth of the texture subimage.
3111 Specifies the format of the compressed image data stored at address
3114 @item @var{imageSize}
3115 Specifies the number of unsigned bytes of image data starting at the
3116 address specified by @var{data}.
3119 Specifies a pointer to the compressed image data in memory.
3123 Texturing maps a portion of a specified texture image onto each
3124 graphical primitive for which texturing is enabled. To enable and
3125 disable three-dimensional texturing, call @code{glEnable} and
3126 @code{glDisable} with argument @code{GL_TEXTURE_3D}.
3128 @code{glCompressedTexSubImage3D} redefines a contiguous subregion of an
3129 existing three-dimensional texture image. The texels referenced by
3130 @var{data} replace the portion of the existing texture array with x
3131 indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, and the y
3132 indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, and the z
3133 indices @var{zoffset} and @r{@var{zoffset}+@var{depth}-1}, inclusive.
3134 This region may not include any texels outside the range of the texture
3135 array as it was originally specified. It is not an error to specify a
3136 subtexture with width of 0, but such a specification has no effect.
3138 @var{format} must be an extension-specified compressed-texture format.
3139 The @var{format} of the compressed texture image is selected by the GL
3140 implementation that compressed it (see @code{glTexImage3D}) and should
3141 be queried at the time the texture was compressed with
3142 @code{glGetTexLevelParameter}.
3144 If a non-zero named buffer object is bound to the
3145 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
3146 texture image is specified, @var{data} is treated as a byte offset into
3147 the buffer object's data store.
3149 @code{GL_INVALID_ENUM} is generated if @var{format} is one of these
3150 generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
3151 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
3152 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
3153 @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE},
3154 @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB},
3155 @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}.
3157 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
3158 consistent with the format, dimensions, and contents of the specified
3159 compressed image data.
3161 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
3162 not supported by the specific compressed internal format as specified in
3163 the specific texture compression extension.
3165 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3166 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
3167 object's data store is currently mapped.
3169 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3170 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
3171 would be unpacked from the buffer object such that the memory reads
3172 required would exceed the data store size.
3174 @code{GL_INVALID_OPERATION} is generated if
3175 @code{glCompressedTexSubImage3D} is executed between the execution of
3176 @code{glBegin} and the corresponding execution of @code{glEnd}.
3178 Undefined results, including abnormal program termination, are generated
3179 if @var{data} is not encoded in a manner consistent with the extension
3180 specification defining the internal compression format.
3184 @deftypefun void glConvolutionFilter1D target internalformat width format type data
3185 Define a one-dimensional convolution filter.
3189 Must be @code{GL_CONVOLUTION_1D}.
3191 @item @var{internalformat}
3192 The internal format of the convolution filter kernel. The allowable
3193 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
3194 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
3195 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
3196 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3197 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3198 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3199 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3200 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3201 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3202 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3203 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3204 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3205 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3208 The width of the pixel array referenced by @var{data}.
3211 The format of the pixel data in @var{data}. The allowable values are
3212 @code{GL_ALPHA}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA},
3213 @code{GL_INTENSITY}, @code{GL_RGB}, and @code{GL_RGBA}.
3216 The type of the pixel data in @var{data}. Symbolic constants
3217 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
3218 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
3219 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
3220 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
3221 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
3222 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
3223 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
3224 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
3225 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
3228 Pointer to a one-dimensional array of pixel data that is processed to
3229 build the convolution filter kernel.
3233 @code{glConvolutionFilter1D} builds a one-dimensional convolution filter
3234 kernel from an array of pixels.
3236 The pixel array specified by @var{width}, @var{format}, @var{type}, and
3237 @var{data} is extracted from memory and processed just as if
3238 @code{glDrawPixels} were called, but processing stops after the final
3239 expansion to RGBA is completed.
3241 If a non-zero named buffer object is bound to the
3242 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
3243 convolution filter is specified, @var{data} is treated as a byte offset
3244 into the buffer object's data store.
3246 The R, G, B, and A components of each pixel are next scaled by the four
3247 1D @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four
3248 1D @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
3249 parameters are set by @code{glConvolutionParameter} using the
3250 @code{GL_CONVOLUTION_1D} target and the names
3251 @code{GL_CONVOLUTION_FILTER_SCALE} and
3252 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors
3253 of four values that are applied to red, green, blue, and alpha, in that
3254 order.) The R, G, B, and A values are not clamped to [0,1] at any time
3255 during this process.
3257 Each pixel is then converted to the internal format specified by
3258 @var{internalformat}. This conversion simply maps the component values
3259 of the pixel (R, G, B, and A) to the values included in the internal
3260 format (red, green, blue, alpha, luminance, and intensity). The mapping
3266 @item @strong{Internal Format}
3267 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
3268 @strong{Luminance}, @strong{Intensity}
3270 @item @code{GL_ALPHA}
3273 @item @code{GL_LUMINANCE}
3276 @item @code{GL_LUMINANCE_ALPHA}
3279 @item @code{GL_INTENSITY}
3285 @item @code{GL_RGBA}
3290 The red, green, blue, alpha, luminance, and/or intensity components of
3291 the resulting pixels are stored in floating-point rather than integer
3292 format. They form a one-dimensional filter kernel image indexed with
3293 coordinate @var{i} such that @var{i} starts at 0 and increases from left
3294 to right. Kernel location @var{i} is derived from the @var{i}th pixel,
3297 Note that after a convolution is performed, the resulting color
3298 components are also scaled by their corresponding
3299 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
3300 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
3301 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
3302 and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}.
3304 @code{GL_INVALID_ENUM} is generated if @var{target} is not
3305 @code{GL_CONVOLUTION_1D}.
3307 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
3308 of the allowable values.
3310 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
3313 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
3316 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
3317 greater than the maximum supported value. This value may be queried with
3318 @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_1D}
3319 and name @code{GL_MAX_CONVOLUTION_WIDTH}.
3321 @code{GL_INVALID_OPERATION} is generated if @var{format} is one of
3322 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
3323 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
3324 and @var{type} is not @code{GL_RGB}.
3326 @code{GL_INVALID_OPERATION} is generated if @var{format} is one of
3327 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
3328 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
3329 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
3330 @code{GL_UNSIGNED_INT_10_10_10_2}, or
3331 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{type} is neither
3332 @code{GL_RGBA} nor @code{GL_BGRA}.
3334 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3335 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
3336 object's data store is currently mapped.
3338 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3339 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
3340 would be unpacked from the buffer object such that the memory reads
3341 required would exceed the data store size.
3343 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3344 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
3345 is not evenly divisible into the number of bytes needed to store in
3346 memory a datum indicated by @var{type}.
3348 @code{GL_INVALID_OPERATION} is generated if @code{glConvolutionFilter1D}
3349 is executed between the execution of @code{glBegin} and the
3350 corresponding execution of @code{glEnd}.
3354 @deftypefun void glConvolutionFilter2D target internalformat width height format type data
3355 Define a two-dimensional convolution filter.
3359 Must be @code{GL_CONVOLUTION_2D}.
3361 @item @var{internalformat}
3362 The internal format of the convolution filter kernel. The allowable
3363 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
3364 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
3365 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
3366 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3367 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3368 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3369 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3370 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3371 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3372 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3373 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3374 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3375 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3378 The width of the pixel array referenced by @var{data}.
3381 The height of the pixel array referenced by @var{data}.
3384 The format of the pixel data in @var{data}. The allowable values are
3385 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
3386 @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA},
3387 @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA}.
3390 The type of the pixel data in @var{data}. Symbolic constants
3391 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
3392 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
3393 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
3394 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
3395 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
3396 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
3397 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
3398 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
3399 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
3402 Pointer to a two-dimensional array of pixel data that is processed to
3403 build the convolution filter kernel.
3407 @code{glConvolutionFilter2D} builds a two-dimensional convolution filter
3408 kernel from an array of pixels.
3410 The pixel array specified by @var{width}, @var{height}, @var{format},
3411 @var{type}, and @var{data} is extracted from memory and processed just
3412 as if @code{glDrawPixels} were called, but processing stops after the
3413 final expansion to RGBA is completed.
3415 If a non-zero named buffer object is bound to the
3416 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
3417 convolution filter is specified, @var{data} is treated as a byte offset
3418 into the buffer object's data store.
3420 The R, G, B, and A components of each pixel are next scaled by the four
3421 2D @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four
3422 2D @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
3423 parameters are set by @code{glConvolutionParameter} using the
3424 @code{GL_CONVOLUTION_2D} target and the names
3425 @code{GL_CONVOLUTION_FILTER_SCALE} and
3426 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors
3427 of four values that are applied to red, green, blue, and alpha, in that
3428 order.) The R, G, B, and A values are not clamped to [0,1] at any time
3429 during this process.
3431 Each pixel is then converted to the internal format specified by
3432 @var{internalformat}. This conversion simply maps the component values
3433 of the pixel (R, G, B, and A) to the values included in the internal
3434 format (red, green, blue, alpha, luminance, and intensity). The mapping
3440 @item @strong{Internal Format}
3441 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
3442 @strong{Luminance}, @strong{Intensity}
3444 @item @code{GL_ALPHA}
3447 @item @code{GL_LUMINANCE}
3450 @item @code{GL_LUMINANCE_ALPHA}
3453 @item @code{GL_INTENSITY}
3459 @item @code{GL_RGBA}
3464 The red, green, blue, alpha, luminance, and/or intensity components of
3465 the resulting pixels are stored in floating-point rather than integer
3466 format. They form a two-dimensional filter kernel image indexed with
3467 coordinates @var{i} and @var{j} such that @var{i} starts at zero and
3468 increases from left to right, and @var{j} starts at zero and increases
3469 from bottom to top. Kernel location @var{i,j} is derived from the
3470 @var{N}th pixel, where @var{N} is @var{i}+@var{j}*@var{width}.
3472 Note that after a convolution is performed, the resulting color
3473 components are also scaled by their corresponding
3474 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
3475 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
3476 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
3477 and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}.
3479 @code{GL_INVALID_ENUM} is generated if @var{target} is not
3480 @code{GL_CONVOLUTION_2D}.
3482 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
3483 of the allowable values.
3485 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
3488 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
3491 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
3492 greater than the maximum supported value. This value may be queried with
3493 @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_2D}
3494 and name @code{GL_MAX_CONVOLUTION_WIDTH}.
3496 @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero
3497 or greater than the maximum supported value. This value may be queried
3498 with @code{glGetConvolutionParameter} using target
3499 @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}.
3501 @code{GL_INVALID_OPERATION} is generated if @var{height} is one of
3502 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
3503 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
3504 and @var{format} is not @code{GL_RGB}.
3506 @code{GL_INVALID_OPERATION} is generated if @var{height} is one of
3507 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
3508 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
3509 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
3510 @code{GL_UNSIGNED_INT_10_10_10_2}, or
3511 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
3512 @code{GL_RGBA} nor @code{GL_BGRA}.
3514 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3515 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
3516 object's data store is currently mapped.
3518 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3519 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
3520 would be unpacked from the buffer object such that the memory reads
3521 required would exceed the data store size.
3523 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3524 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
3525 is not evenly divisible into the number of bytes needed to store in
3526 memory a datum indicated by @var{type}.
3528 @code{GL_INVALID_OPERATION} is generated if @code{glConvolutionFilter2D}
3529 is executed between the execution of @code{glBegin} and the
3530 corresponding execution of @code{glEnd}.
3534 @deftypefun void glConvolutionParameterf target pname params
3535 @deftypefunx void glConvolutionParameteri target pname params
3536 Set convolution parameters.
3540 The target for the convolution parameter. Must be one of
3541 @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or
3542 @code{GL_SEPARABLE_2D}.
3545 The parameter to be set. Must be @code{GL_CONVOLUTION_BORDER_MODE}.
3548 The parameter value. Must be one of @code{GL_REDUCE},
3549 @code{GL_CONSTANT_BORDER}, @code{GL_REPLICATE_BORDER}.
3555 @code{glConvolutionParameter} sets the value of a convolution parameter.
3557 @var{target} selects the convolution filter to be affected:
3558 @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or
3559 @code{GL_SEPARABLE_2D} for the 1D, 2D, or separable 2D filter,
3562 @var{pname} selects the parameter to be changed.
3563 @code{GL_CONVOLUTION_FILTER_SCALE} and @code{GL_CONVOLUTION_FILTER_BIAS}
3564 affect the definition of the convolution filter kernel; see
3565 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and
3566 @code{glSeparableFilter2D} for details. In these cases, @var{params}v is
3567 an array of four values to be applied to red, green, blue, and alpha
3568 values, respectively. The initial value for
3569 @code{GL_CONVOLUTION_FILTER_SCALE} is (1, 1, 1, 1), and the initial
3570 value for @code{GL_CONVOLUTION_FILTER_BIAS} is (0, 0, 0, 0).
3572 A @var{pname} value of @code{GL_CONVOLUTION_BORDER_MODE} controls the
3573 convolution border mode. The accepted modes are:
3576 @item @code{GL_REDUCE}
3577 The image resulting from convolution is smaller than the source image.
3578 If the filter width is @r{@var{Wf}} and height is @r{@var{Hf}}, and the
3579 source image width is @r{@var{Ws}} and height is @r{@var{Hs}}, then the
3580 convolved image width will be @r{@var{Ws}-@var{Wf}+1} and height will be
3581 @r{@var{Hs}-@var{Hf}+1}. (If this reduction would generate an image with
3582 zero or negative width and/or height, the output is simply null, with no
3583 error generated.) The coordinates of the image resulting from
3584 convolution are zero through @r{@var{Ws}-@var{Wf}} in width and zero
3585 through @r{@var{Hs}-@var{Hf}} in height.
3587 @item @code{GL_CONSTANT_BORDER}
3588 The image resulting from convolution is the same size as the source
3589 image, and processed as if the source image were surrounded by pixels
3590 with their color specified by the @code{GL_CONVOLUTION_BORDER_COLOR}.
3592 @item @code{GL_REPLICATE_BORDER}
3593 The image resulting from convolution is the same size as the source
3594 image, and processed as if the outermost pixel on the border of the
3595 source image were replicated.
3599 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
3602 @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the
3605 @code{GL_INVALID_ENUM} is generated if @var{pname} is
3606 @code{GL_CONVOLUTION_BORDER_MODE} and @var{params} is not one of
3607 @code{GL_REDUCE}, @code{GL_CONSTANT_BORDER}, or
3608 @code{GL_REPLICATE_BORDER}.
3610 @code{GL_INVALID_OPERATION} is generated if
3611 @code{glConvolutionParameter} is executed between the execution of
3612 @code{glBegin} and the corresponding execution of @code{glEnd}.
3616 @deftypefun void glCopyColorSubTable target start x y width
3617 Respecify a portion of a color table.
3621 Must be one of @code{GL_COLOR_TABLE},
3622 @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
3623 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}.
3626 The starting index of the portion of the color table to be replaced.
3630 The window coordinates of the left corner of the row of pixels to be
3634 The number of table entries to replace.
3638 @code{glCopyColorSubTable} is used to respecify a contiguous portion of
3639 a color table previously defined using @code{glColorTable}. The pixels
3640 copied from the framebuffer replace the portion of the existing table
3641 from indices @var{start} to @r{@var{start}+@var{x}-1}, inclusive. This
3642 region may not include any entries outside the range of the color table,
3643 as was originally specified. It is not an error to specify a subtexture
3644 with width of 0, but such a specification has no effect.
3646 @code{GL_INVALID_VALUE} is generated if @var{target} is not a previously
3647 defined color table.
3649 @code{GL_INVALID_VALUE} is generated if @var{target} is not one of the
3652 @code{GL_INVALID_VALUE} is generated if
3653 @r{@var{start}+@var{x}>@var{width}}.
3655 @code{GL_INVALID_OPERATION} is generated if @code{glCopyColorSubTable}
3656 is executed between the execution of @code{glBegin} and the
3657 corresponding execution of @code{glEnd}.
3661 @deftypefun void glCopyColorTable target internalformat x y width
3662 Copy pixels into a color table.
3666 The color table target. Must be @code{GL_COLOR_TABLE},
3667 @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
3668 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}.
3670 @item @var{internalformat}
3671 The internal storage format of the texture image. Must be one of the
3672 following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4},
3673 @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16},
3674 @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8},
3675 @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3676 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3677 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3678 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3679 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3680 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3681 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3682 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3683 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3684 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3687 The x coordinate of the lower-left corner of the pixel rectangle to be
3688 transferred to the color table.
3691 The y coordinate of the lower-left corner of the pixel rectangle to be
3692 transferred to the color table.
3695 The width of the pixel rectangle.
3699 @code{glCopyColorTable} loads a color table with pixels from the current
3700 @code{GL_READ_BUFFER} (rather than from main memory, as is the case for
3701 @code{glColorTable}).
3703 The screen-aligned pixel rectangle with lower-left corner at (@var{x},\
3704 @var{y}) having width @var{width} and height 1 is loaded into the color
3705 table. If any pixels within this region are outside the window that is
3706 associated with the GL context, the values obtained for those pixels are
3709 The pixels in the rectangle are processed just as if @code{glReadPixels}
3710 were called, with @var{internalformat} set to RGBA, but processing stops
3711 after the final conversion to RGBA.
3713 The four scale parameters and the four bias parameters that are defined
3714 for the table are then used to scale and bias the R, G, B, and A
3715 components of each pixel. The scale and bias parameters are set by
3716 calling @code{glColorTableParameter}.
3718 Next, the R, G, B, and A values are clamped to the range @r{[0,1]}. Each
3719 pixel is then converted to the internal format specified by
3720 @var{internalformat}. This conversion simply maps the component values
3721 of the pixel (R, G, B, and A) to the values included in the internal
3722 format (red, green, blue, alpha, luminance, and intensity). The mapping
3728 @item @strong{Internal Format}
3729 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
3730 @strong{Luminance}, @strong{Intensity}
3732 @item @code{GL_ALPHA}
3735 @item @code{GL_LUMINANCE}
3738 @item @code{GL_LUMINANCE_ALPHA}
3741 @item @code{GL_INTENSITY}
3747 @item @code{GL_RGBA}
3752 Finally, the red, green, blue, alpha, luminance, and/or intensity
3753 components of the resulting pixels are stored in the color table. They
3754 form a one-dimensional table with indices in the range
3755 @r{[0,@var{width}-1]}.
3759 @code{GL_INVALID_ENUM} is generated when @var{target} is not one of the
3762 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero.
3764 @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not one
3765 of the allowable values.
3767 @code{GL_TABLE_TOO_LARGE} is generated if the requested color table is
3768 too large to be supported by the implementation.
3770 @code{GL_INVALID_OPERATION} is generated if @code{glCopyColorTable} is
3771 executed between the execution of @code{glBegin} and the corresponding
3772 execution of @code{glEnd}.
3776 @deftypefun void glCopyConvolutionFilter1D target internalformat x y width
3777 Copy pixels into a one-dimensional convolution filter.
3781 Must be @code{GL_CONVOLUTION_1D}.
3783 @item @var{internalformat}
3784 The internal format of the convolution filter kernel. The allowable
3785 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
3786 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
3787 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
3788 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3789 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3790 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3791 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3792 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3793 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3794 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3795 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3796 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3797 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3801 The window space coordinates of the lower-left coordinate of the pixel
3805 The width of the pixel array to copy.
3809 @code{glCopyConvolutionFilter1D} defines a one-dimensional convolution
3810 filter kernel with pixels from the current @code{GL_READ_BUFFER} (rather
3811 than from main memory, as is the case for @code{glConvolutionFilter1D}).
3813 The screen-aligned pixel rectangle with lower-left corner at (@var{x},\
3814 @var{y}), width @var{width} and height 1 is used to define the
3815 convolution filter. If any pixels within this region are outside the
3816 window that is associated with the GL context, the values obtained for
3817 those pixels are undefined.
3819 The pixels in the rectangle are processed exactly as if
3820 @code{glReadPixels} had been called with @var{format} set to RGBA, but
3821 the process stops just before final conversion. The R, G, B, and A
3822 components of each pixel are next scaled by the four 1D
3823 @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four 1D
3824 @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
3825 parameters are set by @code{glConvolutionParameter} using the
3826 @code{GL_CONVOLUTION_1D} target and the names
3827 @code{GL_CONVOLUTION_FILTER_SCALE} and
3828 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors
3829 of four values that are applied to red, green, blue, and alpha, in that
3830 order.) The R, G, B, and A values are not clamped to [0,1] at any time
3831 during this process.
3833 Each pixel is then converted to the internal format specified by
3834 @var{internalformat}. This conversion simply maps the component values
3835 of the pixel (R, G, B, and A) to the values included in the internal
3836 format (red, green, blue, alpha, luminance, and intensity). The mapping
3842 @item @strong{Internal Format}
3843 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
3844 @strong{Luminance}, @strong{Intensity}
3846 @item @code{GL_ALPHA}
3849 @item @code{GL_LUMINANCE}
3852 @item @code{GL_LUMINANCE_ALPHA}
3855 @item @code{GL_INTENSITY}
3861 @item @code{GL_RGBA}
3866 The red, green, blue, alpha, luminance, and/or intensity components of
3867 the resulting pixels are stored in floating-point rather than integer
3870 Pixel ordering is such that lower x screen coordinates correspond to
3871 lower @var{i} filter image coordinates.
3873 Note that after a convolution is performed, the resulting color
3874 components are also scaled by their corresponding
3875 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
3876 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
3877 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
3878 and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}.
3880 @code{GL_INVALID_ENUM} is generated if @var{target} is not
3881 @code{GL_CONVOLUTION_1D}.
3883 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
3884 of the allowable values.
3886 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
3887 greater than the maximum supported value. This value may be queried with
3888 @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_1D}
3889 and name @code{GL_MAX_CONVOLUTION_WIDTH}.
3891 @code{GL_INVALID_OPERATION} is generated if
3892 @code{glCopyConvolutionFilter1D} is executed between the execution of
3893 @code{glBegin} and the corresponding execution of @code{glEnd}.
3897 @deftypefun void glCopyConvolutionFilter2D target internalformat x y width height
3898 Copy pixels into a two-dimensional convolution filter.
3902 Must be @code{GL_CONVOLUTION_2D}.
3904 @item @var{internalformat}
3905 The internal format of the convolution filter kernel. The allowable
3906 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
3907 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
3908 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
3909 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3910 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3911 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3912 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3913 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3914 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3915 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3916 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3917 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3918 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3922 The window space coordinates of the lower-left coordinate of the pixel
3926 The width of the pixel array to copy.
3929 The height of the pixel array to copy.
3933 @code{glCopyConvolutionFilter2D} defines a two-dimensional convolution
3934 filter kernel with pixels from the current @code{GL_READ_BUFFER} (rather
3935 than from main memory, as is the case for @code{glConvolutionFilter2D}).
3937 The screen-aligned pixel rectangle with lower-left corner at (@var{x},\
3938 @var{y}), width @var{width} and height @var{height} is used to define
3939 the convolution filter. If any pixels within this region are outside the
3940 window that is associated with the GL context, the values obtained for
3941 those pixels are undefined.
3943 The pixels in the rectangle are processed exactly as if
3944 @code{glReadPixels} had been called with @var{format} set to RGBA, but
3945 the process stops just before final conversion. The R, G, B, and A
3946 components of each pixel are next scaled by the four 2D
3947 @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four 2D
3948 @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
3949 parameters are set by @code{glConvolutionParameter} using the
3950 @code{GL_CONVOLUTION_2D} target and the names
3951 @code{GL_CONVOLUTION_FILTER_SCALE} and
3952 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors
3953 of four values that are applied to red, green, blue, and alpha, in that
3954 order.) The R, G, B, and A values are not clamped to [0,1] at any time
3955 during this process.
3957 Each pixel is then converted to the internal format specified by
3958 @var{internalformat}. This conversion simply maps the component values
3959 of the pixel (R, G, B, and A) to the values included in the internal
3960 format (red, green, blue, alpha, luminance, and intensity). The mapping
3966 @item @strong{Internal Format}
3967 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
3968 @strong{Luminance}, @strong{Intensity}
3970 @item @code{GL_ALPHA}
3973 @item @code{GL_LUMINANCE}
3976 @item @code{GL_LUMINANCE_ALPHA}
3979 @item @code{GL_INTENSITY}
3985 @item @code{GL_RGBA}
3990 The red, green, blue, alpha, luminance, and/or intensity components of
3991 the resulting pixels are stored in floating-point rather than integer
3994 Pixel ordering is such that lower x screen coordinates correspond to
3995 lower @var{i} filter image coordinates, and lower y screen coordinates
3996 correspond to lower @var{j} filter image coordinates.
3998 Note that after a convolution is performed, the resulting color
3999 components are also scaled by their corresponding
4000 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
4001 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
4002 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
4003 and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}.
4005 @code{GL_INVALID_ENUM} is generated if @var{target} is not
4006 @code{GL_CONVOLUTION_2D}.
4008 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
4009 of the allowable values.
4011 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
4012 greater than the maximum supported value. This value may be queried with
4013 @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_2D}
4014 and name @code{GL_MAX_CONVOLUTION_WIDTH}.
4016 @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero
4017 or greater than the maximum supported value. This value may be queried
4018 with @code{glGetConvolutionParameter} using target
4019 @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}.
4021 @code{GL_INVALID_OPERATION} is generated if
4022 @code{glCopyConvolutionFilter2D} is executed between the execution of
4023 @code{glBegin} and the corresponding execution of @code{glEnd}.
4027 @deftypefun void glCopyPixels x y width height type
4028 Copy pixels in the frame buffer.
4033 Specify the window coordinates of the lower left corner of the
4034 rectangular region of pixels to be copied.
4038 Specify the dimensions of the rectangular region of pixels to be copied.
4039 Both must be nonnegative.
4042 Specifies whether color values, depth values, or stencil values are to
4043 be copied. Symbolic constants @code{GL_COLOR}, @code{GL_DEPTH}, and
4044 @code{GL_STENCIL} are accepted.
4048 @code{glCopyPixels} copies a screen-aligned rectangle of pixels from the
4049 specified frame buffer location to a region relative to the current
4050 raster position. Its operation is well defined only if the entire pixel
4051 source region is within the exposed portion of the window. Results of
4052 copies from outside the window, or from regions of the window that are
4053 not exposed, are hardware dependent and undefined.
4055 @var{x} and @var{y} specify the window coordinates of the lower left
4056 corner of the rectangular region to be copied. @var{width} and
4057 @var{height} specify the dimensions of the rectangular region to be
4058 copied. Both @var{width} and @var{height} must not be negative.
4060 Several parameters control the processing of the pixel data while it is
4061 being copied. These parameters are set with three commands:
4062 @code{glPixelTransfer}, @code{glPixelMap}, and @code{glPixelZoom}. This
4063 reference page describes the effects on @code{glCopyPixels} of most, but
4064 not all, of the parameters specified by these three commands.
4066 @code{glCopyPixels} copies values from each pixel with the lower
4067 left-hand corner at @r{(@var{x}+@var{i},@var{y}+@var{j})} for
4068 @r{0<=@var{i}<@var{width}} and @r{0<=@var{j}<@var{height}}. This pixel
4069 is said to be the @r{@var{i}}th pixel in the @r{@var{j}}th row. Pixels
4070 are copied in row order from the lowest to the highest row, left to
4073 @var{type} specifies whether color, depth, or stencil data is to be
4074 copied. The details of the transfer for each data type are as follows:
4077 @item @code{GL_COLOR}
4078 Indices or RGBA colors are read from the buffer currently specified as
4079 the read source buffer (see @code{glReadBuffer}). If the GL is in color
4080 index mode, each index that is read from this buffer is converted to a
4081 fixed-point format with an unspecified number of bits to the right of
4082 the binary point. Each index is then shifted left by
4083 @code{GL_INDEX_SHIFT} bits, and added to @code{GL_INDEX_OFFSET}. If
4084 @code{GL_INDEX_SHIFT} is negative, the shift is to the right. In either
4085 case, zero bits fill otherwise unspecified bit locations in the result.
4086 If @code{GL_MAP_COLOR} is true, the index is replaced with the value
4087 that it references in lookup table @code{GL_PIXEL_MAP_I_TO_I}. Whether
4088 the lookup replacement of the index is done or not, the integer part of
4089 the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the
4090 number of bits in a color index buffer.
4092 If the GL is in RGBA mode, the red, green, blue, and alpha components of
4093 each pixel that is read are converted to an internal floating-point
4094 format with unspecified precision. The conversion maps the largest
4095 representable component value to 1.0, and component value 0 to 0.0. The
4096 resulting floating-point color values are then multiplied by
4097 @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is RED,
4098 GREEN, BLUE, and ALPHA for the respective color components. The results
4099 are clamped to the range [0,1]. If @code{GL_MAP_COLOR} is true, each
4100 color component is scaled by the size of lookup table
4101 @code{GL_PIXEL_MAP_c_TO_c}, then replaced by the value that it
4102 references in that table. @var{c} is R, G, B, or A.
4104 If the @code{ARB_imaging} extension is supported, the color values may
4105 be additionally processed by color-table lookups, color-matrix
4106 transformations, and convolution filters.
4108 The GL then converts the resulting indices or RGBA colors to fragments
4109 by attaching the current raster position @var{z} coordinate and texture
4110 coordinates to each pixel, then assigning window coordinates
4111 @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where
4112 @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position,
4113 and the pixel was the @r{@var{i}}th pixel in the @r{@var{j}}th row.
4114 These pixel fragments are then treated just like the fragments generated
4115 by rasterizing points, lines, or polygons. Texture mapping, fog, and all
4116 the fragment operations are applied before the fragments are written to
4119 @item @code{GL_DEPTH}
4120 Depth values are read from the depth buffer and converted directly to an
4121 internal floating-point format with unspecified precision. The resulting
4122 floating-point depth value is then multiplied by @code{GL_DEPTH_SCALE}
4123 and added to @code{GL_DEPTH_BIAS}. The result is clamped to the range
4126 The GL then converts the resulting depth components to fragments by
4127 attaching the current raster position color or color index and texture
4128 coordinates to each pixel, then assigning window coordinates
4129 @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where
4130 @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position,
4131 and the pixel was the @r{@var{i}}th pixel in the @r{@var{j}}th row.
4132 These pixel fragments are then treated just like the fragments generated
4133 by rasterizing points, lines, or polygons. Texture mapping, fog, and all
4134 the fragment operations are applied before the fragments are written to
4137 @item @code{GL_STENCIL}
4138 Stencil indices are read from the stencil buffer and converted to an
4139 internal fixed-point format with an unspecified number of bits to the
4140 right of the binary point. Each fixed-point index is then shifted left
4141 by @code{GL_INDEX_SHIFT} bits, and added to @code{GL_INDEX_OFFSET}. If
4142 @code{GL_INDEX_SHIFT} is negative, the shift is to the right. In either
4143 case, zero bits fill otherwise unspecified bit locations in the result.
4144 If @code{GL_MAP_STENCIL} is true, the index is replaced with the value
4145 that it references in lookup table @code{GL_PIXEL_MAP_S_TO_S}. Whether
4146 the lookup replacement of the index is done or not, the integer part of
4147 the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the
4148 number of bits in the stencil buffer. The resulting stencil indices are
4149 then written to the stencil buffer such that the index read from the
4150 @r{@var{i}}th location of the @r{@var{j}}th row is written to location
4151 @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where
4152 @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position.
4153 Only the pixel ownership test, the scissor test, and the stencil
4154 writemask affect these write operations.
4158 The rasterization described thus far assumes pixel zoom factors of 1.0.
4159 If @code{glPixelZoom} is used to change the @r{@var{x}} and @r{@var{y}}
4160 pixel zoom factors, pixels are converted to fragments as follows. If
4161 @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position,
4162 and a given pixel is in the @r{@var{i}}th location in the @r{@var{j}}th
4163 row of the source pixel rectangle, then fragments are generated for
4164 pixels whose centers are in the rectangle with corners at
4166 @r{(@var{x}_@var{r}+@var{zoom}_@var{x},@var{i},@var{y}_@var{r}+@var{zoom}_@var{y},@var{j})}
4170 @r{(@var{x}_@var{r}+@var{zoom}_@var{x},(@var{i}+1,),@var{y}_@var{r}+@var{zoom}_@var{y},(@var{j}+1,))}
4172 where @r{@var{zoom}_@var{x}} is the value of @code{GL_ZOOM_X} and
4173 @r{@var{zoom}_@var{y}} is the value of @code{GL_ZOOM_Y}.
4175 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
4178 @code{GL_INVALID_VALUE} is generated if either @var{width} or
4179 @var{height} is negative.
4181 @code{GL_INVALID_OPERATION} is generated if @var{type} is
4182 @code{GL_DEPTH} and there is no depth buffer.
4184 @code{GL_INVALID_OPERATION} is generated if @var{type} is
4185 @code{GL_STENCIL} and there is no stencil buffer.
4187 @code{GL_INVALID_OPERATION} is generated if @code{glCopyPixels} is
4188 executed between the execution of @code{glBegin} and the corresponding
4189 execution of @code{glEnd}.
4193 @deftypefun void glCopyTexImage1D target level internalformat x y width border
4194 Copy pixels into a 1D texture image.
4198 Specifies the target texture. Must be @code{GL_TEXTURE_1D}.
4201 Specifies the level-of-detail number. Level 0 is the base image level.
4202 Level @var{n} is the @var{n}th mipmap reduction image.
4204 @item @var{internalformat}
4205 Specifies the internal format of the texture. Must be one of the
4206 following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4},
4207 @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16},
4208 @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_LUMINANCE},
4209 @code{GL_COMPRESSED_LUMINANCE_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
4210 @code{GL_COMPRESSED_RGB}, @code{GL_COMPRESSED_RGBA},
4211 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
4212 @code{GL_DEPTH_COMPONENT24}, @code{GL_DEPTH_COMPONENT32},
4213 @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8},
4214 @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
4215 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
4216 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
4217 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
4218 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
4219 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_RGB},
4220 @code{GL_R3_G3_B2}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
4221 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
4222 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
4223 @code{GL_RGB10_A2}, @code{GL_RGBA12}, @code{GL_RGBA16},
4224 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
4225 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
4226 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
4230 Specify the window coordinates of the left corner of the row of pixels
4234 Specifies the width of the texture image. Must be 0 or
4235 @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. The height
4236 of the texture image is 1.
4239 Specifies the width of the border. Must be either 0 or 1.
4243 @code{glCopyTexImage1D} defines a one-dimensional texture image with
4244 pixels from the current @code{GL_READ_BUFFER}.
4246 The screen-aligned pixel row with left corner at @r{(@var{x},@var{y})}
4247 and with a length of @r{@var{width}+2(@var{border},)} defines the
4248 texture array at the mipmap level specified by @var{level}.
4249 @var{internalformat} specifies the internal format of the texture array.
4251 The pixels in the row are processed exactly as if @code{glCopyPixels}
4252 had been called, but the process stops just before final conversion. At
4253 this point all pixel component values are clamped to the range @r{[0,1]}
4254 and then converted to the texture's internal format for storage in the
4257 Pixel ordering is such that lower @r{@var{x}} screen coordinates
4258 correspond to lower texture coordinates.
4260 If any of the pixels within the specified row of the current
4261 @code{GL_READ_BUFFER} are outside the window associated with the current
4262 rendering context, then the values obtained for those pixels are
4265 @code{glCopyTexImage1D} defines a one-dimensional texture image with
4266 pixels from the current @code{GL_READ_BUFFER}.
4268 When @var{internalformat} is one of the sRGB types, the GL does not
4269 automatically convert the source pixels to the sRGB color space. In this
4270 case, the @code{glPixelMap} function can be used to accomplish the
4273 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
4276 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4278 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
4279 @r{@var{log}_2@var{max}}, where @r{@var{max}} is the returned value of
4280 @code{GL_MAX_TEXTURE_SIZE}.
4282 @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not an
4285 @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or
4286 greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
4288 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
4289 not supported and the @var{width} cannot be represented as
4290 @r{2^@var{n}+2(@var{border},)} for some integer value of @var{n}.
4292 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
4294 @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexImage1D} is
4295 executed between the execution of @code{glBegin} and the corresponding
4296 execution of @code{glEnd}.
4298 @code{GL_INVALID_OPERATION} is generated if @var{internalformat} is
4299 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
4300 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32} and there is
4305 @deftypefun void glCopyTexImage2D target level internalformat x y width height border
4306 Copy pixels into a 2D texture image.
4310 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
4311 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
4312 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
4313 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
4314 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
4315 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
4316 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
4319 Specifies the level-of-detail number. Level 0 is the base image level.
4320 Level @var{n} is the @var{n}th mipmap reduction image.
4322 @item @var{internalformat}
4323 Specifies the internal format of the texture. Must be one of the
4324 following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4},
4325 @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16},
4326 @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_LUMINANCE},
4327 @code{GL_COMPRESSED_LUMINANCE_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
4328 @code{GL_COMPRESSED_RGB}, @code{GL_COMPRESSED_RGBA},
4329 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
4330 @code{GL_DEPTH_COMPONENT24}, @code{GL_DEPTH_COMPONENT32},
4331 @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8},
4332 @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
4333 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
4334 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
4335 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
4336 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
4337 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_RGB},
4338 @code{GL_R3_G3_B2}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
4339 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
4340 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
4341 @code{GL_RGB10_A2}, @code{GL_RGBA12}, @code{GL_RGBA16},
4342 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
4343 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
4344 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
4348 Specify the window coordinates of the lower left corner of the
4349 rectangular region of pixels to be copied.
4352 Specifies the width of the texture image. Must be 0 or
4353 @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}.
4356 Specifies the height of the texture image. Must be 0 or
4357 @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}.
4360 Specifies the width of the border. Must be either 0 or 1.
4364 @code{glCopyTexImage2D} defines a two-dimensional texture image, or
4365 cube-map texture image with pixels from the current
4366 @code{GL_READ_BUFFER}.
4368 The screen-aligned pixel rectangle with lower left corner at (@var{x},
4369 @var{y}) and with a width of @r{@var{width}+2(@var{border},)} and a
4370 height of @r{@var{height}+2(@var{border},)} defines the texture array
4371 at the mipmap level specified by @var{level}. @var{internalformat}
4372 specifies the internal format of the texture array.
4374 The pixels in the rectangle are processed exactly as if
4375 @code{glCopyPixels} had been called, but the process stops just before
4376 final conversion. At this point all pixel component values are clamped
4377 to the range @r{[0,1]} and then converted to the texture's internal
4378 format for storage in the texel array.
4380 Pixel ordering is such that lower @r{@var{x}} and @r{@var{y}} screen
4381 coordinates correspond to lower @r{@var{s}} and @r{@var{t}} texture
4384 If any of the pixels within the specified rectangle of the current
4385 @code{GL_READ_BUFFER} are outside the window associated with the current
4386 rendering context, then the values obtained for those pixels are
4389 When @var{internalformat} is one of the sRGB types, the GL does not
4390 automatically convert the source pixels to the sRGB color space. In this
4391 case, the @code{glPixelMap} function can be used to accomplish the
4394 @code{GL_INVALID_ENUM} is generated if @var{target} is not
4395 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
4396 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
4397 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
4398 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
4399 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
4400 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
4402 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4404 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
4405 @r{@var{log}_2@var{max}}, where @r{@var{max}} is the returned value of
4406 @code{GL_MAX_TEXTURE_SIZE}.
4408 @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or
4409 greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
4411 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
4412 not supported and the @var{width} or @var{depth} cannot be represented
4413 as @r{2^@var{k}+2(@var{border},)} for some integer @r{@var{k}}.
4415 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
4417 @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not an
4420 @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexImage2D} is
4421 executed between the execution of @code{glBegin} and the corresponding
4422 execution of @code{glEnd}.
4424 @code{GL_INVALID_OPERATION} is generated if @var{internalformat} is
4425 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
4426 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32} and there is
4431 @deftypefun void glCopyTexSubImage1D target level xoffset x y width
4432 Copy a one-dimensional texture subimage.
4436 Specifies the target texture. Must be @code{GL_TEXTURE_1D}.
4439 Specifies the level-of-detail number. Level 0 is the base image level.
4440 Level @var{n} is the @var{n}th mipmap reduction image.
4443 Specifies the texel offset within the texture array.
4447 Specify the window coordinates of the left corner of the row of pixels
4451 Specifies the width of the texture subimage.
4455 @code{glCopyTexSubImage1D} replaces a portion of a one-dimensional
4456 texture image with pixels from the current @code{GL_READ_BUFFER} (rather
4457 than from main memory, as is the case for @code{glTexSubImage1D}).
4459 The screen-aligned pixel row with left corner at (@var{x},\ @var{y}),
4460 and with length @var{width} replaces the portion of the texture array
4461 with x indices @var{xoffset} through @r{@var{xoffset}+@var{width}-1},
4462 inclusive. The destination in the texture array may not include any
4463 texels outside the texture array as it was originally specified.
4465 The pixels in the row are processed exactly as if @code{glCopyPixels}
4466 had been called, but the process stops just before final conversion. At
4467 this point, all pixel component values are clamped to the range
4468 @r{[0,1]} and then converted to the texture's internal format for
4469 storage in the texel array.
4471 It is not an error to specify a subtexture with zero width, but such a
4472 specification has no effect. If any of the pixels within the specified
4473 row of the current @code{GL_READ_BUFFER} are outside the read window
4474 associated with the current rendering context, then the values obtained
4475 for those pixels are undefined.
4477 No change is made to the @var{internalformat}, @var{width}, or
4478 @var{border} parameters of the specified texture array or to texel
4479 values outside the specified subregion.
4481 @code{GL_INVALID_ENUM} is generated if /@var{target} is not
4482 @code{GL_TEXTURE_1D}.
4484 @code{GL_INVALID_OPERATION} is generated if the texture array has not
4485 been defined by a previous @code{glTexImage1D} or
4486 @code{glCopyTexImage1D} operation.
4488 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4490 @code{GL_INVALID_VALUE} may be generated if
4491 @r{@var{level}>@var{log}_2(@var{max},)}, where @var{max} is the
4492 returned value of @code{GL_MAX_TEXTURE_SIZE}.
4494 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, or
4495 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, where @r{@var{w}}
4496 is the @code{GL_TEXTURE_WIDTH} and @r{@var{b}} is the
4497 @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that
4498 @r{@var{w}} includes twice the border width.
4504 @deftypefun void glCopyTexSubImage2D target level xoffset yoffset x y width height
4505 Copy a two-dimensional texture subimage.
4509 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
4510 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
4511 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
4512 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
4513 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
4514 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
4515 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
4518 Specifies the level-of-detail number. Level 0 is the base image level.
4519 Level @var{n} is the @var{n}th mipmap reduction image.
4522 Specifies a texel offset in the x direction within the texture array.
4525 Specifies a texel offset in the y direction within the texture array.
4529 Specify the window coordinates of the lower left corner of the
4530 rectangular region of pixels to be copied.
4533 Specifies the width of the texture subimage.
4536 Specifies the height of the texture subimage.
4540 @code{glCopyTexSubImage2D} replaces a rectangular portion of a
4541 two-dimensional texture image or cube-map texture image with pixels from
4542 the current @code{GL_READ_BUFFER} (rather than from main memory, as is
4543 the case for @code{glTexSubImage2D}).
4545 The screen-aligned pixel rectangle with lower left corner at
4546 @r{(@var{x},@var{y})} and with width @var{width} and height @var{height}
4547 replaces the portion of the texture array with x indices @var{xoffset}
4548 through @r{@var{xoffset}+@var{width}-1}, inclusive, and y indices
4549 @var{yoffset} through @r{@var{yoffset}+@var{height}-1}, inclusive, at
4550 the mipmap level specified by @var{level}.
4552 The pixels in the rectangle are processed exactly as if
4553 @code{glCopyPixels} had been called, but the process stops just before
4554 final conversion. At this point, all pixel component values are clamped
4555 to the range @r{[0,1]} and then converted to the texture's internal
4556 format for storage in the texel array.
4558 The destination rectangle in the texture array may not include any
4559 texels outside the texture array as it was originally specified. It is
4560 not an error to specify a subtexture with zero width or height, but such
4561 a specification has no effect.
4563 If any of the pixels within the specified rectangle of the current
4564 @code{GL_READ_BUFFER} are outside the read window associated with the
4565 current rendering context, then the values obtained for those pixels are
4568 No change is made to the @var{internalformat}, @var{width},
4569 @var{height}, or @var{border} parameters of the specified texture array
4570 or to texel values outside the specified subregion.
4572 @code{GL_INVALID_ENUM} is generated if @var{target} is not
4573 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
4574 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
4575 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
4576 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
4577 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
4578 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
4580 @code{GL_INVALID_OPERATION} is generated if the texture array has not
4581 been defined by a previous @code{glTexImage2D} or
4582 @code{glCopyTexImage2D} operation.
4584 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4586 @code{GL_INVALID_VALUE} may be generated if
4587 @r{@var{level}>@var{log}_2(@var{max},)}, where @r{@var{max}} is the
4588 returned value of @code{GL_MAX_TEXTURE_SIZE}.
4590 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}},
4591 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)},
4592 @r{@var{yoffset}<-@var{b}}, or
4593 @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, where @r{@var{w}}
4594 is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the
4595 @code{GL_TEXTURE_HEIGHT}, and @r{@var{b}} is the
4596 @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that
4597 @r{@var{w}} and @r{@var{h}} include twice the border width.
4599 @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexSubImage2D}
4600 is executed between the execution of @code{glBegin} and the
4601 corresponding execution of @code{glEnd}.
4605 @deftypefun void glCopyTexSubImage3D target level xoffset yoffset zoffset x y width height
4606 Copy a three-dimensional texture subimage.
4610 Specifies the target texture. Must be @code{GL_TEXTURE_3D}
4613 Specifies the level-of-detail number. Level 0 is the base image level.
4614 Level @var{n} is the @var{n}th mipmap reduction image.
4617 Specifies a texel offset in the x direction within the texture array.
4620 Specifies a texel offset in the y direction within the texture array.
4623 Specifies a texel offset in the z direction within the texture array.
4627 Specify the window coordinates of the lower left corner of the
4628 rectangular region of pixels to be copied.
4631 Specifies the width of the texture subimage.
4634 Specifies the height of the texture subimage.
4638 @code{glCopyTexSubImage3D} replaces a rectangular portion of a
4639 three-dimensional texture image with pixels from the current
4640 @code{GL_READ_BUFFER} (rather than from main memory, as is the case for
4641 @code{glTexSubImage3D}).
4643 The screen-aligned pixel rectangle with lower left corner at (@var{x},\
4644 @var{y}) and with width @var{width} and height @var{height} replaces the
4645 portion of the texture array with x indices @var{xoffset} through
4646 @r{@var{xoffset}+@var{width}-1}, inclusive, and y indices @var{yoffset}
4647 through @r{@var{yoffset}+@var{height}-1}, inclusive, at z index
4648 @var{zoffset} and at the mipmap level specified by @var{level}.
4650 The pixels in the rectangle are processed exactly as if
4651 @code{glCopyPixels} had been called, but the process stops just before
4652 final conversion. At this point, all pixel component values are clamped
4653 to the range @r{[0,1]} and then converted to the texture's internal
4654 format for storage in the texel array.
4656 The destination rectangle in the texture array may not include any
4657 texels outside the texture array as it was originally specified. It is
4658 not an error to specify a subtexture with zero width or height, but such
4659 a specification has no effect.
4661 If any of the pixels within the specified rectangle of the current
4662 @code{GL_READ_BUFFER} are outside the read window associated with the
4663 current rendering context, then the values obtained for those pixels are
4666 No change is made to the @var{internalformat}, @var{width},
4667 @var{height}, @var{depth}, or @var{border} parameters of the specified
4668 texture array or to texel values outside the specified subregion.
4670 @code{GL_INVALID_ENUM} is generated if /@var{target} is not
4671 @code{GL_TEXTURE_3D}.
4673 @code{GL_INVALID_OPERATION} is generated if the texture array has not
4674 been defined by a previous @code{glTexImage3D} operation.
4676 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4678 @code{GL_INVALID_VALUE} may be generated if
4679 @r{@var{level}>@var{log}_2(@var{max},)}, where @r{@var{max}} is the
4680 returned value of @code{GL_MAX_3D_TEXTURE_SIZE}.
4682 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}},
4683 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)},
4684 @r{@var{yoffset}<-@var{b}},
4685 @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)},
4686 @r{@var{zoffset}<-@var{b}}, or
4687 @r{(@var{zoffset}+1,)>(@var{d}-@var{b},)}, where @r{@var{w}} is the
4688 @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the @code{GL_TEXTURE_HEIGHT},
4689 @r{@var{d}} is the @code{GL_TEXTURE_DEPTH}, and @r{@var{b}} is the
4690 @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that
4691 @r{@var{w}}, @r{@var{h}}, and @r{@var{d}} include twice the border
4694 @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexSubImage3D}
4695 is executed between the execution of @code{glBegin} and the
4696 corresponding execution of @code{glEnd}.
4700 @deftypefun GLuint glCreateProgram
4701 Creates a program object.
4703 @code{glCreateProgram} creates an empty program object and returns a
4704 non-zero value by which it can be referenced. A program object is an
4705 object to which shader objects can be attached. This provides a
4706 mechanism to specify the shader objects that will be linked to create a
4707 program. It also provides a means for checking the compatibility of the
4708 shaders that will be used to create a program (for instance, checking
4709 the compatibility between a vertex shader and a fragment shader). When
4710 no longer needed as part of a program object, shader objects can be
4713 One or more executables are created in a program object by successfully
4714 attaching shader objects to it with @code{glAttachShader}, successfully
4715 compiling the shader objects with @code{glCompileShader}, and
4716 successfully linking the program object with @code{glLinkProgram}. These
4717 executables are made part of current state when @code{glUseProgram} is
4718 called. Program objects can be deleted by calling
4719 @code{glDeleteProgram}. The memory associated with the program object
4720 will be deleted when it is no longer part of current rendering state for
4723 This function returns 0 if an error occurs creating the program object.
4725 @code{GL_INVALID_OPERATION} is generated if @code{glCreateProgram} is
4726 executed between the execution of @code{glBegin} and the corresponding
4727 execution of @code{glEnd}.
4731 @deftypefun GLuint glCreateShader shaderType
4732 Creates a shader object.
4735 @item @var{shaderType}
4736 Specifies the type of shader to be created. Must be either
4737 @code{GL_VERTEX_SHADER} or @code{GL_FRAGMENT_SHADER}.
4741 @code{glCreateShader} creates an empty shader object and returns a
4742 non-zero value by which it can be referenced. A shader object is used to
4743 maintain the source code strings that define a shader. @var{shaderType}
4744 indicates the type of shader to be created. Two types of shaders are
4745 supported. A shader of type @code{GL_VERTEX_SHADER} is a shader that is
4746 intended to run on the programmable vertex processor and replace the
4747 fixed functionality vertex processing in OpenGL. A shader of type
4748 @code{GL_FRAGMENT_SHADER} is a shader that is intended to run on the
4749 programmable fragment processor and replace the fixed functionality
4750 fragment processing in OpenGL.
4752 When created, a shader object's @code{GL_SHADER_TYPE} parameter is set
4753 to either @code{GL_VERTEX_SHADER} or @code{GL_FRAGMENT_SHADER},
4754 depending on the value of @var{shaderType}.
4756 This function returns 0 if an error occurs creating the shader object.
4758 @code{GL_INVALID_ENUM} is generated if @var{shaderType} is not an
4761 @code{GL_INVALID_OPERATION} is generated if @code{glCreateShader} is
4762 executed between the execution of @code{glBegin} and the corresponding
4763 execution of @code{glEnd}.
4767 @deftypefun void glCullFace mode
4768 Specify whether front- or back-facing facets can be culled.
4772 Specifies whether front- or back-facing facets are candidates for
4773 culling. Symbolic constants @code{GL_FRONT}, @code{GL_BACK}, and
4774 @code{GL_FRONT_AND_BACK} are accepted. The initial value is
4779 @code{glCullFace} specifies whether front- or back-facing facets are
4780 culled (as specified by @var{mode}) when facet culling is enabled. Facet
4781 culling is initially disabled. To enable and disable facet culling, call
4782 the @code{glEnable} and @code{glDisable} commands with the argument
4783 @code{GL_CULL_FACE}. Facets include triangles, quadrilaterals, polygons,
4786 @code{glFrontFace} specifies which of the clockwise and counterclockwise
4787 facets are front-facing and back-facing. See @code{glFrontFace}.
4789 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
4792 @code{GL_INVALID_OPERATION} is generated if @code{glCullFace} is
4793 executed between the execution of @code{glBegin} and the corresponding
4794 execution of @code{glEnd}.
4798 @deftypefun void glDeleteBuffers n buffers
4799 Delete named buffer objects.
4803 Specifies the number of buffer objects to be deleted.
4806 Specifies an array of buffer objects to be deleted.
4810 @code{glDeleteBuffers} deletes @var{n} buffer objects named by the
4811 elements of the array @var{buffers}. After a buffer object is deleted,
4812 it has no contents, and its name is free for reuse (for example by
4813 @code{glGenBuffers}). If a buffer object that is currently bound is
4814 deleted, the binding reverts to 0 (the absence of any buffer object,
4815 which reverts to client memory usage).
4817 @code{glDeleteBuffers} silently ignores 0's and names that do not
4818 correspond to existing buffer objects.
4820 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
4822 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteBuffers} is
4823 executed between the execution of @code{glBegin} and the corresponding
4824 execution of @code{glEnd}.
4828 @deftypefun void glDeleteLists list range
4829 Delete a contiguous group of display lists.
4833 Specifies the integer name of the first display list to delete.
4836 Specifies the number of display lists to delete.
4840 @code{glDeleteLists} causes a contiguous group of display lists to be
4841 deleted. @var{list} is the name of the first display list to be deleted,
4842 and @var{range} is the number of display lists to delete. All display
4843 lists @r{@var{d}} with @r{@var{list}<=@var{d}<=@var{list}+@var{range}-1}
4846 All storage locations allocated to the specified display lists are
4847 freed, and the names are available for reuse at a later time. Names
4848 within the range that do not have an associated display list are
4849 ignored. If @var{range} is 0, nothing happens.
4851 @code{GL_INVALID_VALUE} is generated if @var{range} is negative.
4853 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteLists} is
4854 executed between the execution of @code{glBegin} and the corresponding
4855 execution of @code{glEnd}.
4859 @deftypefun void glDeleteProgram program
4860 Deletes a program object.
4864 Specifies the program object to be deleted.
4868 @code{glDeleteProgram} frees the memory and invalidates the name
4869 associated with the program object specified by @var{program.} This
4870 command effectively undoes the effects of a call to
4871 @code{glCreateProgram}.
4873 If a program object is in use as part of current rendering state, it
4874 will be flagged for deletion, but it will not be deleted until it is no
4875 longer part of current state for any rendering context. If a program
4876 object to be deleted has shader objects attached to it, those shader
4877 objects will be automatically detached but not deleted unless they have
4878 already been flagged for deletion by a previous call to
4879 @code{glDeleteShader}. A value of 0 for @var{program} will be silently
4882 To determine whether a program object has been flagged for deletion,
4883 call @code{glGetProgram} with arguments @var{program} and
4884 @code{GL_DELETE_STATUS}.
4886 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
4887 generated by OpenGL.
4889 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteProgram} is
4890 executed between the execution of @code{glBegin} and the corresponding
4891 execution of @code{glEnd}.
4895 @deftypefun void glDeleteQueries n ids
4896 Delete named query objects.
4900 Specifies the number of query objects to be deleted.
4903 Specifies an array of query objects to be deleted.
4907 @code{glDeleteQueries} deletes @var{n} query objects named by the
4908 elements of the array @var{ids}. After a query object is deleted, it has
4909 no contents, and its name is free for reuse (for example by
4910 @code{glGenQueries}).
4912 @code{glDeleteQueries} silently ignores 0's and names that do not
4913 correspond to existing query objects.
4915 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
4917 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteQueries} is
4918 executed between the execution of @code{glBegin} and the corresponding
4919 execution of @code{glEnd}.
4923 @deftypefun void glDeleteShader shader
4924 Deletes a shader object.
4928 Specifies the shader object to be deleted.
4932 @code{glDeleteShader} frees the memory and invalidates the name
4933 associated with the shader object specified by @var{shader}. This
4934 command effectively undoes the effects of a call to
4935 @code{glCreateShader}.
4937 If a shader object to be deleted is attached to a program object, it
4938 will be flagged for deletion, but it will not be deleted until it is no
4939 longer attached to any program object, for any rendering context (i.e.,
4940 it must be detached from wherever it was attached before it will be
4941 deleted). A value of 0 for @var{shader} will be silently ignored.
4943 To determine whether an object has been flagged for deletion, call
4944 @code{glGetShader} with arguments @var{shader} and
4945 @code{GL_DELETE_STATUS}.
4947 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
4948 generated by OpenGL.
4950 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteShader} is
4951 executed between the execution of @code{glBegin} and the corresponding
4952 execution of @code{glEnd}.
4956 @deftypefun void glDeleteTextures n textures
4957 Delete named textures.
4961 Specifies the number of textures to be deleted.
4963 @item @var{textures}
4964 Specifies an array of textures to be deleted.
4968 @code{glDeleteTextures} deletes @var{n} textures named by the elements
4969 of the array @var{textures}. After a texture is deleted, it has no
4970 contents or dimensionality, and its name is free for reuse (for example
4971 by @code{glGenTextures}). If a texture that is currently bound is
4972 deleted, the binding reverts to 0 (the default texture).
4974 @code{glDeleteTextures} silently ignores 0's and names that do not
4975 correspond to existing textures.
4977 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
4979 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteTextures} is
4980 executed between the execution of @code{glBegin} and the corresponding
4981 execution of @code{glEnd}.
4985 @deftypefun void glDepthFunc func
4986 Specify the value used for depth buffer comparisons.
4990 Specifies the depth comparison function. Symbolic constants
4991 @code{GL_NEVER}, @code{GL_LESS}, @code{GL_EQUAL}, @code{GL_LEQUAL},
4992 @code{GL_GREATER}, @code{GL_NOTEQUAL}, @code{GL_GEQUAL}, and
4993 @code{GL_ALWAYS} are accepted. The initial value is @code{GL_LESS}.
4997 @code{glDepthFunc} specifies the function used to compare each incoming
4998 pixel depth value with the depth value present in the depth buffer. The
4999 comparison is performed only if depth testing is enabled. (See
5000 @code{glEnable} and @code{glDisable} of @code{GL_DEPTH_TEST}.)
5002 @var{func} specifies the conditions under which the pixel will be drawn.
5003 The comparison functions are as follows:
5006 @item @code{GL_NEVER}
5009 @item @code{GL_LESS}
5010 Passes if the incoming depth value is less than the stored depth value.
5012 @item @code{GL_EQUAL}
5013 Passes if the incoming depth value is equal to the stored depth value.
5015 @item @code{GL_LEQUAL}
5016 Passes if the incoming depth value is less than or equal to the stored
5019 @item @code{GL_GREATER}
5020 Passes if the incoming depth value is greater than the stored depth
5023 @item @code{GL_NOTEQUAL}
5024 Passes if the incoming depth value is not equal to the stored depth
5027 @item @code{GL_GEQUAL}
5028 Passes if the incoming depth value is greater than or equal to the
5031 @item @code{GL_ALWAYS}
5036 The initial value of @var{func} is @code{GL_LESS}. Initially, depth
5037 testing is disabled. If depth testing is disabled or if no depth buffer
5038 exists, it is as if the depth test always passes.
5040 @code{GL_INVALID_ENUM} is generated if @var{func} is not an accepted
5043 @code{GL_INVALID_OPERATION} is generated if @code{glDepthFunc} is
5044 executed between the execution of @code{glBegin} and the corresponding
5045 execution of @code{glEnd}.
5049 @deftypefun void glDepthMask flag
5050 Enable or disable writing into the depth buffer.
5054 Specifies whether the depth buffer is enabled for writing. If @var{flag}
5055 is @code{GL_FALSE}, depth buffer writing is disabled. Otherwise, it is
5056 enabled. Initially, depth buffer writing is enabled.
5060 @code{glDepthMask} specifies whether the depth buffer is enabled for
5061 writing. If @var{flag} is @code{GL_FALSE}, depth buffer writing is
5062 disabled. Otherwise, it is enabled. Initially, depth buffer writing is
5065 @code{GL_INVALID_OPERATION} is generated if @code{glDepthMask} is
5066 executed between the execution of @code{glBegin} and the corresponding
5067 execution of @code{glEnd}.
5071 @deftypefun void glDepthRange nearVal farVal
5072 Specify mapping of depth values from normalized device coordinates to
5077 Specifies the mapping of the near clipping plane to window coordinates.
5078 The initial value is 0.
5081 Specifies the mapping of the far clipping plane to window coordinates.
5082 The initial value is 1.
5086 After clipping and division by @var{w}, depth coordinates range from
5087 @r{-1} to 1, corresponding to the near and far clipping planes.
5088 @code{glDepthRange} specifies a linear mapping of the normalized depth
5089 coordinates in this range to window depth coordinates. Regardless of the
5090 actual depth buffer implementation, window coordinate depth values are
5091 treated as though they range from 0 through 1 (like color components).
5092 Thus, the values accepted by @code{glDepthRange} are both clamped to
5093 this range before they are accepted.
5095 The setting of (0,1) maps the near plane to 0 and the far plane to 1.
5096 With this mapping, the depth buffer range is fully utilized.
5098 @code{GL_INVALID_OPERATION} is generated if @code{glDepthRange} is
5099 executed between the execution of @code{glBegin} and the corresponding
5100 execution of @code{glEnd}.
5104 @deftypefun void glDetachShader program shader
5105 Detaches a shader object from a program object to which it is attached.
5109 Specifies the program object from which to detach the shader object.
5112 Specifies the shader object to be detached.
5116 @code{glDetachShader} detaches the shader object specified by
5117 @var{shader} from the program object specified by @var{program}. This
5118 command can be used to undo the effect of the command
5119 @code{glAttachShader}.
5121 If @var{shader} has already been flagged for deletion by a call to
5122 @code{glDeleteShader} and it is not attached to any other program
5123 object, it will be deleted after it has been detached.
5125 @code{GL_INVALID_VALUE} is generated if either @var{program} or
5126 @var{shader} is a value that was not generated by OpenGL.
5128 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
5131 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
5134 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not attached
5137 @code{GL_INVALID_OPERATION} is generated if @code{glDetachShader} is
5138 executed between the execution of @code{glBegin} and the corresponding
5139 execution of @code{glEnd}.
5143 @deftypefun void glDrawArrays mode first count
5144 Render primitives from array data.
5148 Specifies what kind of primitives to render. Symbolic constants
5149 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
5150 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
5151 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
5152 @code{GL_POLYGON} are accepted.
5155 Specifies the starting index in the enabled arrays.
5158 Specifies the number of indices to be rendered.
5162 @code{glDrawArrays} specifies multiple geometric primitives with very
5163 few subroutine calls. Instead of calling a GL procedure to pass each
5164 individual vertex, normal, texture coordinate, edge flag, or color, you
5165 can prespecify separate arrays of vertices, normals, and colors and use
5166 them to construct a sequence of primitives with a single call to
5167 @code{glDrawArrays}.
5169 When @code{glDrawArrays} is called, it uses @var{count} sequential
5170 elements from each enabled array to construct a sequence of geometric
5171 primitives, beginning with element @var{first}. @var{mode} specifies
5172 what kind of primitives are constructed and how the array elements
5173 construct those primitives. If @code{GL_VERTEX_ARRAY} is not enabled, no
5174 geometric primitives are generated.
5176 Vertex attributes that are modified by @code{glDrawArrays} have an
5177 unspecified value after @code{glDrawArrays} returns. For example, if
5178 @code{GL_COLOR_ARRAY} is enabled, the value of the current color is
5179 undefined after @code{glDrawArrays} executes. Attributes that aren't
5180 modified remain well defined.
5182 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
5185 @code{GL_INVALID_VALUE} is generated if @var{count} is negative.
5187 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5188 name is bound to an enabled array and the buffer object's data store is
5191 @code{GL_INVALID_OPERATION} is generated if @code{glDrawArrays} is
5192 executed between the execution of @code{glBegin} and the corresponding
5197 @deftypefun void glDrawBuffers n bufs
5198 Specifies a list of color buffers to be drawn into.
5202 Specifies the number of buffers in @var{bufs}.
5205 Points to an array of symbolic constants specifying the buffers into
5206 which fragment colors or data values will be written.
5210 @code{glDrawBuffers} defines an array of buffers into which fragment
5211 color values or fragment data will be written. If no fragment shader is
5212 active, rendering operations will generate only one fragment color per
5213 fragment and it will be written into each of the buffers specified by
5214 @var{bufs}. If a fragment shader is active and it writes a value to the
5215 output variable @code{gl_FragColor}, then that value will be written
5216 into each of the buffers specified by @var{bufs}. If a fragment shader
5217 is active and it writes a value to one or more elements of the output
5218 array variable @code{gl_FragData[]}, then the value of
5219 @code{gl_FragData[0] } will be written into the first buffer specified
5220 by @var{bufs}, the value of @code{gl_FragData[1] } will be written into
5221 the second buffer specified by @var{bufs}, and so on up to
5222 @code{gl_FragData[n-1]}. The draw buffer used for @code{gl_FragData[n]}
5223 and beyond is implicitly set to be @code{GL_NONE}.
5225 The symbolic constants contained in @var{bufs} may be any of the
5229 @item @code{GL_NONE}
5230 The fragment color/data value is not written into any color buffer.
5232 @item @code{GL_FRONT_LEFT}
5233 The fragment color/data value is written into the front left color
5236 @item @code{GL_FRONT_RIGHT}
5237 The fragment color/data value is written into the front right color
5240 @item @code{GL_BACK_LEFT}
5241 The fragment color/data value is written into the back left color
5244 @item @code{GL_BACK_RIGHT}
5245 The fragment color/data value is written into the back right color
5248 @item @code{GL_AUXi}
5249 The fragment color/data value is written into auxiliary buffer @code{i}.
5253 Except for @code{GL_NONE}, the preceding symbolic constants may not
5254 appear more than once in @var{bufs}. The maximum number of draw buffers
5255 supported is implementation dependent and can be queried by calling
5256 @code{glGet} with the argument @code{GL_MAX_DRAW_BUFFERS}. The number of
5257 auxiliary buffers can be queried by calling @code{glGet} with the
5258 argument @code{GL_AUX_BUFFERS}.
5260 @code{GL_INVALID_ENUM} is generated if one of the values in @var{bufs}
5261 is not an accepted value.
5263 @code{GL_INVALID_ENUM} is generated if @var{n} is less than 0.
5265 @code{GL_INVALID_OPERATION} is generated if a symbolic constant other
5266 than @code{GL_NONE} appears more than once in @var{bufs}.
5268 @code{GL_INVALID_OPERATION} is generated if any of the entries in
5269 @var{bufs} (other than @code{GL_NONE} ) indicates a color buffer that
5270 does not exist in the current GL context.
5272 @code{GL_INVALID_VALUE} is generated if @var{n} is greater than
5273 @code{GL_MAX_DRAW_BUFFERS}.
5275 @code{GL_INVALID_OPERATION} is generated if @code{glDrawBuffers} is
5276 executed between the execution of @code{glBegin} and the corresponding
5277 execution of @code{glEnd}.
5281 @deftypefun void glDrawBuffer mode
5282 Specify which color buffers are to be drawn into.
5286 Specifies up to four color buffers to be drawn into. Symbolic constants
5287 @code{GL_NONE}, @code{GL_FRONT_LEFT}, @code{GL_FRONT_RIGHT},
5288 @code{GL_BACK_LEFT}, @code{GL_BACK_RIGHT}, @code{GL_FRONT},
5289 @code{GL_BACK}, @code{GL_LEFT}, @code{GL_RIGHT},
5290 @code{GL_FRONT_AND_BACK}, and @code{GL_AUX}@var{i}, where @var{i} is
5291 between 0 and the value of @code{GL_AUX_BUFFERS} minus 1, are accepted.
5292 (@code{GL_AUX_BUFFERS} is not the upper limit; use @code{glGet} to query
5293 the number of available aux buffers.) The initial value is
5294 @code{GL_FRONT} for single-buffered contexts, and @code{GL_BACK} for
5295 double-buffered contexts.
5299 When colors are written to the frame buffer, they are written into the
5300 color buffers specified by @code{glDrawBuffer}. The specifications are
5304 @item @code{GL_NONE}
5305 No color buffers are written.
5307 @item @code{GL_FRONT_LEFT}
5308 Only the front left color buffer is written.
5310 @item @code{GL_FRONT_RIGHT}
5311 Only the front right color buffer is written.
5313 @item @code{GL_BACK_LEFT}
5314 Only the back left color buffer is written.
5316 @item @code{GL_BACK_RIGHT}
5317 Only the back right color buffer is written.
5319 @item @code{GL_FRONT}
5320 Only the front left and front right color buffers are written. If there
5321 is no front right color buffer, only the front left color buffer is
5324 @item @code{GL_BACK}
5325 Only the back left and back right color buffers are written. If there is
5326 no back right color buffer, only the back left color buffer is written.
5328 @item @code{GL_LEFT}
5329 Only the front left and back left color buffers are written. If there is
5330 no back left color buffer, only the front left color buffer is written.
5332 @item @code{GL_RIGHT}
5333 Only the front right and back right color buffers are written. If there
5334 is no back right color buffer, only the front right color buffer is
5337 @item @code{GL_FRONT_AND_BACK}
5338 All the front and back color buffers (front left, front right, back
5339 left, back right) are written. If there are no back color buffers, only
5340 the front left and front right color buffers are written. If there are
5341 no right color buffers, only the front left and back left color buffers
5342 are written. If there are no right or back color buffers, only the front
5343 left color buffer is written.
5345 @item @code{GL_AUX}@var{i}
5346 Only auxiliary color buffer @var{i} is written.
5350 If more than one color buffer is selected for drawing, then blending or
5351 logical operations are computed and applied independently for each color
5352 buffer and can produce different results in each buffer.
5354 Monoscopic contexts include only @var{left} buffers, and stereoscopic
5355 contexts include both @var{left} and @var{right} buffers. Likewise,
5356 single-buffered contexts include only @var{front} buffers, and
5357 double-buffered contexts include both @var{front} and @var{back}
5358 buffers. The context is selected at GL initialization.
5360 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
5363 @code{GL_INVALID_OPERATION} is generated if none of the buffers
5364 indicated by @var{mode} exists.
5366 @code{GL_INVALID_OPERATION} is generated if @code{glDrawBuffer} is
5367 executed between the execution of @code{glBegin} and the corresponding
5368 execution of @code{glEnd}.
5372 @deftypefun void glDrawElements mode count type indices
5373 Render primitives from array data.
5377 Specifies what kind of primitives to render. Symbolic constants
5378 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
5379 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
5380 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
5381 @code{GL_POLYGON} are accepted.
5384 Specifies the number of elements to be rendered.
5387 Specifies the type of the values in @var{indices}. Must be one of
5388 @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or
5389 @code{GL_UNSIGNED_INT}.
5392 Specifies a pointer to the location where the indices are stored.
5396 @code{glDrawElements} specifies multiple geometric primitives with very
5397 few subroutine calls. Instead of calling a GL function to pass each
5398 individual vertex, normal, texture coordinate, edge flag, or color, you
5399 can prespecify separate arrays of vertices, normals, and so on, and use
5400 them to construct a sequence of primitives with a single call to
5401 @code{glDrawElements}.
5403 When @code{glDrawElements} is called, it uses @var{count} sequential
5404 elements from an enabled array, starting at @var{indices} to construct a
5405 sequence of geometric primitives. @var{mode} specifies what kind of
5406 primitives are constructed and how the array elements construct these
5407 primitives. If more than one array is enabled, each is used. If
5408 @code{GL_VERTEX_ARRAY} is not enabled, no geometric primitives are
5411 Vertex attributes that are modified by @code{glDrawElements} have an
5412 unspecified value after @code{glDrawElements} returns. For example, if
5413 @code{GL_COLOR_ARRAY} is enabled, the value of the current color is
5414 undefined after @code{glDrawElements} executes. Attributes that aren't
5415 modified maintain their previous values.
5417 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
5420 @code{GL_INVALID_VALUE} is generated if @var{count} is negative.
5422 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5423 name is bound to an enabled array or the element array and the buffer
5424 object's data store is currently mapped.
5426 @code{GL_INVALID_OPERATION} is generated if @code{glDrawElements} is
5427 executed between the execution of @code{glBegin} and the corresponding
5432 @deftypefun void glDrawPixels width height format type data
5433 Write a block of pixels to the frame buffer.
5438 Specify the dimensions of the pixel rectangle to be written into the
5442 Specifies the format of the pixel data. Symbolic constants
5443 @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX},
5444 @code{GL_DEPTH_COMPONENT}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA},
5445 @code{GL_BGRA}, @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE},
5446 @code{GL_ALPHA}, @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA} are
5450 Specifies the data type for @var{data}. Symbolic constants
5451 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
5452 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
5453 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
5454 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
5455 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
5456 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
5457 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
5458 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
5459 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
5462 Specifies a pointer to the pixel data.
5466 @code{glDrawPixels} reads pixel data from memory and writes it into the
5467 frame buffer relative to the current raster position, provided that the
5468 raster position is valid. Use @code{glRasterPos} or @code{glWindowPos}
5469 to set the current raster position; use @code{glGet} with argument
5470 @code{GL_CURRENT_RASTER_POSITION_VALID} to determine if the specified
5471 raster position is valid, and @code{glGet} with argument
5472 @code{GL_CURRENT_RASTER_POSITION} to query the raster position.
5474 Several parameters define the encoding of pixel data in memory and
5475 control the processing of the pixel data before it is placed in the
5476 frame buffer. These parameters are set with four commands:
5477 @code{glPixelStore}, @code{glPixelTransfer}, @code{glPixelMap}, and
5478 @code{glPixelZoom}. This reference page describes the effects on
5479 @code{glDrawPixels} of many, but not all, of the parameters specified by
5480 these four commands.
5482 Data is read from @var{data} as a sequence of signed or unsigned bytes,
5483 signed or unsigned shorts, signed or unsigned integers, or
5484 single-precision floating-point values, depending on @var{type}. When
5485 @var{type} is one of @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE},
5486 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
5487 @code{GL_INT}, or @code{GL_FLOAT} each of these bytes, shorts, integers,
5488 or floating-point values is interpreted as one color or depth component,
5489 or one index, depending on @var{format}. When @var{type} is one of
5490 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_SHORT_5_6_5},
5491 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
5492 @code{GL_UNSIGNED_INT_8_8_8_8}, or @code{GL_UNSIGNED_INT_10_10_10_2},
5493 each unsigned value is interpreted as containing all the components for
5494 a single pixel, with the color components arranged according to
5495 @var{format}. When @var{type} is one of
5496 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
5497 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
5498 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
5499 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, or
5500 @code{GL_UNSIGNED_INT_2_10_10_10_REV}, each unsigned value is
5501 interpreted as containing all color components, specified by
5502 @var{format}, for a single pixel in a reversed order. Indices are always
5503 treated individually. Color components are treated as groups of one,
5504 two, three, or four values, again based on @var{format}. Both individual
5505 indices and groups of components are referred to as pixels. If
5506 @var{type} is @code{GL_BITMAP}, the data must be unsigned bytes, and
5507 @var{format} must be either @code{GL_COLOR_INDEX} or
5508 @code{GL_STENCIL_INDEX}. Each unsigned byte is treated as eight 1-bit
5509 pixels, with bit ordering determined by @code{GL_UNPACK_LSB_FIRST} (see
5510 @code{glPixelStore}).
5512 @r{@var{width}×@var{height}} pixels are read from memory, starting at
5513 location @var{data}. By default, these pixels are taken from adjacent
5514 memory locations, except that after all @var{width} pixels are read, the
5515 read pointer is advanced to the next four-byte boundary. The four-byte
5516 row alignment is specified by @code{glPixelStore} with argument
5517 @code{GL_UNPACK_ALIGNMENT}, and it can be set to one, two, four, or
5518 eight bytes. Other pixel store parameters specify different read pointer
5519 advancements, both before the first pixel is read and after all
5520 @var{width} pixels are read. See the @code{glPixelStore} reference page
5521 for details on these options.
5523 If a non-zero named buffer object is bound to the
5524 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
5525 block of pixels is specified, @var{data} is treated as a byte offset
5526 into the buffer object's data store.
5528 The @r{@var{width}×@var{height}} pixels that are read from memory are
5529 each operated on in the same way, based on the values of several
5530 parameters specified by @code{glPixelTransfer} and @code{glPixelMap}.
5531 The details of these operations, as well as the target buffer into which
5532 the pixels are drawn, are specific to the format of the pixels, as
5533 specified by @var{format}. @var{format} can assume one of 13 symbolic
5537 @item @code{GL_COLOR_INDEX}
5538 Each pixel is a single value, a color index. It is converted to
5539 fixed-point format, with an unspecified number of bits to the right of
5540 the binary point, regardless of the memory data type. Floating-point
5541 values convert to true fixed-point values. Signed and unsigned integer
5542 data is converted with all fraction bits set to 0. Bitmap data convert
5545 Each fixed-point index is then shifted left by @code{GL_INDEX_SHIFT}
5546 bits and added to @code{GL_INDEX_OFFSET}. If @code{GL_INDEX_SHIFT} is
5547 negative, the shift is to the right. In either case, zero bits fill
5548 otherwise unspecified bit locations in the result.
5550 If the GL is in RGBA mode, the resulting index is converted to an RGBA
5551 pixel with the help of the @code{GL_PIXEL_MAP_I_TO_R},
5552 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
5553 @code{GL_PIXEL_MAP_I_TO_A} tables. If the GL is in color index mode, and
5554 if @code{GL_MAP_COLOR} is true, the index is replaced with the value
5555 that it references in lookup table @code{GL_PIXEL_MAP_I_TO_I}. Whether
5556 the lookup replacement of the index is done or not, the integer part of
5557 the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the
5558 number of bits in a color index buffer.
5560 The GL then converts the resulting indices or RGBA colors to fragments
5561 by attaching the current raster position @var{z} coordinate and texture
5562 coordinates to each pixel, then assigning @r{@var{x}} and @r{@var{y}}
5563 window coordinates to the @r{@var{n}}th fragment such that
5564 @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},⌋}
5566 where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster
5567 position. These pixel fragments are then treated just like the fragments
5568 generated by rasterizing points, lines, or polygons. Texture mapping,
5569 fog, and all the fragment operations are applied before the fragments
5570 are written to the frame buffer.
5572 @item @code{GL_STENCIL_INDEX}
5573 Each pixel is a single value, a stencil index. It is converted to
5574 fixed-point format, with an unspecified number of bits to the right of
5575 the binary point, regardless of the memory data type. Floating-point
5576 values convert to true fixed-point values. Signed and unsigned integer
5577 data is converted with all fraction bits set to 0. Bitmap data convert
5580 Each fixed-point index is then shifted left by @code{GL_INDEX_SHIFT}
5581 bits, and added to @code{GL_INDEX_OFFSET}. If @code{GL_INDEX_SHIFT} is
5582 negative, the shift is to the right. In either case, zero bits fill
5583 otherwise unspecified bit locations in the result. If
5584 @code{GL_MAP_STENCIL} is true, the index is replaced with the value that
5585 it references in lookup table @code{GL_PIXEL_MAP_S_TO_S}. Whether the
5586 lookup replacement of the index is done or not, the integer part of the
5587 index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the
5588 number of bits in the stencil buffer. The resulting stencil indices are
5589 then written to the stencil buffer such that the @r{@var{n}}th index is
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. Only the pixel ownership test, the scissor test, and the
5596 stencil writemask affect these write operations.
5598 @item @code{GL_DEPTH_COMPONENT}
5599 Each pixel is a single-depth component. Floating-point data is converted
5600 directly to an internal floating-point format with unspecified
5601 precision. Signed integer data is mapped linearly to the internal
5602 floating-point format such that the most positive representable integer
5603 value maps to 1.0, and the most negative representable value maps to
5604 @r{-1.0}. Unsigned integer data is mapped similarly: the largest integer
5605 value maps to 1.0, and 0 maps to 0.0. The resulting floating-point depth
5606 value is then multiplied by @code{GL_DEPTH_SCALE} and added to
5607 @code{GL_DEPTH_BIAS}. The result is clamped to the range @r{[0,1]}.
5609 The GL then converts the resulting depth components to fragments by
5610 attaching the current raster position color or color index and texture
5611 coordinates to each pixel, then assigning @r{@var{x}} and @r{@var{y}}
5612 window coordinates to the @r{@var{n}}th fragment such that
5614 @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},⌋}
5616 where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster
5617 position. These pixel fragments are then treated just like the fragments
5618 generated by rasterizing points, lines, or polygons. Texture mapping,
5619 fog, and all the fragment operations are applied before the fragments
5620 are written to the frame buffer.
5622 @item @code{GL_RGBA}
5623 @item @code{GL_BGRA}
5624 Each pixel is a four-component group: For @code{GL_RGBA}, the red
5625 component is first, followed by green, followed by blue, followed by
5626 alpha; for @code{GL_BGRA} the order is blue, green, red and then alpha.
5627 Floating-point values are converted directly to an internal
5628 floating-point format with unspecified precision. Signed integer values
5629 are mapped linearly to the internal floating-point format such that the
5630 most positive representable integer value maps to 1.0, and the most
5631 negative representable value maps to @r{-1.0}. (Note that this mapping
5632 does not convert 0 precisely to 0.0.) Unsigned integer data is mapped
5633 similarly: The largest integer value maps to 1.0, and 0 maps to 0.0. The
5634 resulting floating-point color values are then multiplied by
5635 @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is RED,
5636 GREEN, BLUE, and ALPHA for the respective color components. The results
5637 are clamped to the range @r{[0,1]}.
5639 If @code{GL_MAP_COLOR} is true, each color component is scaled by the
5640 size of lookup table @code{GL_PIXEL_MAP_c_TO_c}, then replaced by the
5641 value that it references in that table. @var{c} is R, G, B, or A
5644 The GL then converts the resulting RGBA colors to fragments by attaching
5645 the current raster position @var{z} coordinate and texture coordinates
5646 to each pixel, then assigning @r{@var{x}} and @r{@var{y}} window
5647 coordinates to the @r{@var{n}}th fragment such that
5649 @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},⌋}
5651 where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster
5652 position. These pixel fragments are then treated just like the fragments
5653 generated by rasterizing points, lines, or polygons. Texture mapping,
5654 fog, and all the fragment operations are applied before the fragments
5655 are written to the frame buffer.
5658 Each pixel is a single red component. This component is converted to the
5659 internal floating-point format in the same way the red component of an
5660 RGBA pixel is. It is then converted to an RGBA pixel with green and blue
5661 set to 0, and alpha set to 1. After this conversion, the pixel is
5662 treated as if it had been read as an RGBA pixel.
5664 @item @code{GL_GREEN}
5665 Each pixel is a single green component. This component is converted to
5666 the internal floating-point format in the same way the green component
5667 of an RGBA pixel is. It is then converted to an RGBA pixel with red and
5668 blue set to 0, and alpha set to 1. After this conversion, the pixel is
5669 treated as if it had been read as an RGBA pixel.
5671 @item @code{GL_BLUE}
5672 Each pixel is a single blue component. This component is converted to
5673 the internal floating-point format in the same way the blue component of
5674 an RGBA pixel is. It is then converted to an RGBA pixel with red and
5675 green set to 0, and alpha set to 1. After this conversion, the pixel is
5676 treated as if it had been read as an RGBA pixel.
5678 @item @code{GL_ALPHA}
5679 Each pixel is a single alpha component. This component is converted to
5680 the internal floating-point format in the same way the alpha component
5681 of an RGBA pixel is. It is then converted to an RGBA pixel with red,
5682 green, and blue set to 0. After this conversion, the pixel is treated as
5683 if it had been read as an RGBA pixel.
5687 Each pixel is a three-component group: red first, followed by green,
5688 followed by blue; for @code{GL_BGR}, the first component is blue,
5689 followed by green and then red. Each component is converted to the
5690 internal floating-point format in the same way the red, green, and blue
5691 components of an RGBA pixel are. The color triple is converted to an
5692 RGBA pixel with alpha set to 1. After this conversion, the pixel is
5693 treated as if it had been read as an RGBA pixel.
5695 @item @code{GL_LUMINANCE}
5696 Each pixel is a single luminance component. This component is converted
5697 to the internal floating-point format in the same way the red component
5698 of an RGBA pixel is. It is then converted to an RGBA pixel with red,
5699 green, and blue set to the converted luminance value, and alpha set to
5700 1. After this conversion, the pixel is treated as if it had been read as
5703 @item @code{GL_LUMINANCE_ALPHA}
5704 Each pixel is a two-component group: luminance first, followed by alpha.
5705 The two components are converted to the internal floating-point format
5706 in the same way the red component of an RGBA pixel is. They are then
5707 converted to an RGBA pixel with red, green, and blue set to the
5708 converted luminance value, and alpha set to the converted alpha value.
5709 After this conversion, the pixel is treated as if it had been read as an
5714 The following table summarizes the meaning of the valid constants for
5715 the @var{type} parameter:
5721 @strong{Corresponding Type}
5723 @item @code{GL_UNSIGNED_BYTE}
5724 unsigned 8-bit integer
5726 @item @code{GL_BYTE}
5727 signed 8-bit integer
5729 @item @code{GL_BITMAP}
5730 single bits in unsigned 8-bit integers
5732 @item @code{GL_UNSIGNED_SHORT}
5733 unsigned 16-bit integer
5735 @item @code{GL_SHORT}
5736 signed 16-bit integer
5738 @item @code{GL_UNSIGNED_INT}
5739 unsigned 32-bit integer
5744 @item @code{GL_FLOAT}
5745 single-precision floating-point
5747 @item @code{GL_UNSIGNED_BYTE_3_3_2}
5748 unsigned 8-bit integer
5750 @item @code{GL_UNSIGNED_BYTE_2_3_3_REV}
5751 unsigned 8-bit integer with reversed component ordering
5753 @item @code{GL_UNSIGNED_SHORT_5_6_5}
5754 unsigned 16-bit integer
5756 @item @code{GL_UNSIGNED_SHORT_5_6_5_REV}
5757 unsigned 16-bit integer with reversed component ordering
5759 @item @code{GL_UNSIGNED_SHORT_4_4_4_4}
5760 unsigned 16-bit integer
5762 @item @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}
5763 unsigned 16-bit integer with reversed component ordering
5765 @item @code{GL_UNSIGNED_SHORT_5_5_5_1}
5766 unsigned 16-bit integer
5768 @item @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}
5769 unsigned 16-bit integer with reversed component ordering
5771 @item @code{GL_UNSIGNED_INT_8_8_8_8}
5772 unsigned 32-bit integer
5774 @item @code{GL_UNSIGNED_INT_8_8_8_8_REV}
5775 unsigned 32-bit integer with reversed component ordering
5777 @item @code{GL_UNSIGNED_INT_10_10_10_2}
5778 unsigned 32-bit integer
5780 @item @code{GL_UNSIGNED_INT_2_10_10_10_REV}
5781 unsigned 32-bit integer with reversed component ordering
5787 The rasterization described so far assumes pixel zoom factors of 1. If
5788 @code{glPixelZoom} is used to change the @r{@var{x}} and @r{@var{y}}
5789 pixel zoom factors, pixels are converted to fragments as follows. If
5790 @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position,
5791 and a given pixel is in the @r{@var{n}}th column and @r{@var{m}}th row
5792 of the pixel rectangle, then fragments are generated for pixels whose
5793 centers are in the rectangle with corners at
5795 @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,))}
5797 where @r{@var{zoom}_@var{x}} is the value of @code{GL_ZOOM_X} and
5798 @r{@var{zoom}_@var{y}} is the value of @code{GL_ZOOM_Y}.
5800 @code{GL_INVALID_ENUM} is generated if @var{format} or @var{type} is not
5801 one of the accepted values.
5803 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
5804 and @var{format} is not either @code{GL_COLOR_INDEX} or
5805 @code{GL_STENCIL_INDEX}.
5807 @code{GL_INVALID_VALUE} is generated if either @var{width} or
5808 @var{height} is negative.
5810 @code{GL_INVALID_OPERATION} is generated if @var{format} is
5811 @code{GL_STENCIL_INDEX} and there is no stencil buffer.
5813 @code{GL_INVALID_OPERATION} is generated if @var{format} is
5814 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
5815 @code{GL_RGB}, @code{GL_RGBA}, @code{GL_BGR}, @code{GL_BGRA},
5816 @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}, and the GL is in
5819 @code{GL_INVALID_OPERATION} is generated if @var{format} is one of
5820 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
5821 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
5822 and @var{format} is not @code{GL_RGB}.
5824 @code{GL_INVALID_OPERATION} is generated if @var{format} is one of
5825 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
5826 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
5827 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
5828 @code{GL_UNSIGNED_INT_10_10_10_2}, or
5829 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
5830 @code{GL_RGBA} nor @code{GL_BGRA}.
5832 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5833 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
5834 object's data store is currently mapped.
5836 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5837 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
5838 would be unpacked from the buffer object such that the memory reads
5839 required would exceed the data store size.
5841 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5842 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
5843 is not evenly divisible into the number of bytes needed to store in
5844 memory a datum indicated by @var{type}.
5846 @code{GL_INVALID_OPERATION} is generated if @code{glDrawPixels} is
5847 executed between the execution of @code{glBegin} and the corresponding
5848 execution of @code{glEnd}.
5852 @deftypefun void glDrawRangeElements mode start end count type indices
5853 Render primitives from array data.
5857 Specifies what kind of primitives to render. Symbolic constants
5858 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
5859 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
5860 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
5861 @code{GL_POLYGON} are accepted.
5864 Specifies the minimum array index contained in @var{indices}.
5867 Specifies the maximum array index contained in @var{indices}.
5870 Specifies the number of elements to be rendered.
5873 Specifies the type of the values in @var{indices}. Must be one of
5874 @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or
5875 @code{GL_UNSIGNED_INT}.
5878 Specifies a pointer to the location where the indices are stored.
5882 @code{glDrawRangeElements} is a restricted form of
5883 @code{glDrawElements}. @var{mode}, @var{start}, @var{end}, and
5884 @var{count} match the corresponding arguments to @code{glDrawElements},
5885 with the additional constraint that all values in the arrays @var{count}
5886 must lie between @var{start} and @var{end}, inclusive.
5888 Implementations denote recommended maximum amounts of vertex and index
5889 data, which may be queried by calling @code{glGet} with argument
5890 @code{GL_MAX_ELEMENTS_VERTICES} and @code{GL_MAX_ELEMENTS_INDICES}. If
5891 @r{@var{end}-@var{start}+1} is greater than the value of
5892 @code{GL_MAX_ELEMENTS_VERTICES}, or if @var{count} is greater than the
5893 value of @code{GL_MAX_ELEMENTS_INDICES}, then the call may operate at
5894 reduced performance. There is no requirement that all vertices in the
5895 range @r{[@var{start},@var{end}]} be referenced. However, the
5896 implementation may partially process unused vertices, reducing
5897 performance from what could be achieved with an optimal index set.
5899 When @code{glDrawRangeElements} is called, it uses @var{count}
5900 sequential elements from an enabled array, starting at @var{start} to
5901 construct a sequence of geometric primitives. @var{mode} specifies what
5902 kind of primitives are constructed, and how the array elements construct
5903 these primitives. If more than one array is enabled, each is used. If
5904 @code{GL_VERTEX_ARRAY} is not enabled, no geometric primitives are
5907 Vertex attributes that are modified by @code{glDrawRangeElements} have
5908 an unspecified value after @code{glDrawRangeElements} returns. For
5909 example, if @code{GL_COLOR_ARRAY} is enabled, the value of the current
5910 color is undefined after @code{glDrawRangeElements} executes. Attributes
5911 that aren't modified maintain their previous values.
5913 It is an error for indices to lie outside the range
5914 @r{[@var{start},@var{end}]}, but implementations may not check for this
5915 situation. Such indices cause implementation-dependent behavior.
5917 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
5920 @code{GL_INVALID_VALUE} is generated if @var{count} is negative.
5922 @code{GL_INVALID_VALUE} is generated if @r{@var{end}<@var{start}}.
5924 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5925 name is bound to an enabled array or the element array and the buffer
5926 object's data store is currently mapped.
5928 @code{GL_INVALID_OPERATION} is generated if @code{glDrawRangeElements}
5929 is executed between the execution of @code{glBegin} and the
5930 corresponding @code{glEnd}.
5934 @deftypefun void glEdgeFlagPointer stride pointer
5935 Define an array of edge flags.
5939 Specifies the byte offset between consecutive edge flags. If
5940 @var{stride} is 0, the edge flags are understood to be tightly packed in
5941 the array. The initial value is 0.
5944 Specifies a pointer to the first edge flag in the array. The initial
5949 @code{glEdgeFlagPointer} specifies the location and data format of an
5950 array of boolean edge flags to use when rendering. @var{stride}
5951 specifies the byte stride from one edge flag to the next, allowing
5952 vertices and attributes to be packed into a single array or stored in
5955 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
5956 target (see @code{glBindBuffer}) while an edge flag array is specified,
5957 @var{pointer} is treated as a byte offset into the buffer object's data
5958 store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING})
5959 is saved as edge flag vertex array client-side state
5960 (@code{GL_EDGE_FLAG_ARRAY_BUFFER_BINDING}).
5962 When an edge flag array is specified, @var{stride} and @var{pointer} are
5963 saved as client-side state, in addition to the current vertex array
5964 buffer object binding.
5966 To enable and disable the edge flag array, call
5967 @code{glEnableClientState} and @code{glDisableClientState} with the
5968 argument @code{GL_EDGE_FLAG_ARRAY}. If enabled, the edge flag array is
5969 used when @code{glDrawArrays}, @code{glMultiDrawArrays},
5970 @code{glDrawElements}, @code{glMultiDrawElements},
5971 @code{glDrawRangeElements}, or @code{glArrayElement} is called.
5973 @code{GL_INVALID_ENUM} is generated if @var{stride} is negative.
5977 @deftypefun void glEdgeFlag flag
5978 Flag edges as either boundary or nonboundary.
5982 Specifies the current edge flag value, either @code{GL_TRUE} or
5983 @code{GL_FALSE}. The initial value is @code{GL_TRUE}.
5987 Each vertex of a polygon, separate triangle, or separate quadrilateral
5988 specified between a @code{glBegin}/@code{glEnd} pair is marked as the
5989 start of either a boundary or nonboundary edge. If the current edge flag
5990 is true when the vertex is specified, the vertex is marked as the start
5991 of a boundary edge. Otherwise, the vertex is marked as the start of a
5992 nonboundary edge. @code{glEdgeFlag} sets the edge flag bit to
5993 @code{GL_TRUE} if @var{flag} is @code{GL_TRUE} and to @code{GL_FALSE}
5996 The vertices of connected triangles and connected quadrilaterals are
5997 always marked as boundary, regardless of the value of the edge flag.
5999 Boundary and nonboundary edge flags on vertices are significant only if
6000 @code{GL_POLYGON_MODE} is set to @code{GL_POINT} or @code{GL_LINE}. See
6001 @code{glPolygonMode}.
6005 @deftypefun void glEnableClientState cap
6006 @deftypefunx void glDisableClientState cap
6007 Enable or disable client-side capability.
6011 Specifies the capability to enable. Symbolic constants
6012 @code{GL_COLOR_ARRAY}, @code{GL_EDGE_FLAG_ARRAY},
6013 @code{GL_FOG_COORD_ARRAY}, @code{GL_INDEX_ARRAY},
6014 @code{GL_NORMAL_ARRAY}, @code{GL_SECONDARY_COLOR_ARRAY},
6015 @code{GL_TEXTURE_COORD_ARRAY}, and @code{GL_VERTEX_ARRAY} are accepted.
6019 @code{glEnableClientState} and @code{glDisableClientState} enable or
6020 disable individual client-side capabilities. By default, all client-side
6021 capabilities are disabled. Both @code{glEnableClientState} and
6022 @code{glDisableClientState} take a single argument, @var{cap}, which can
6023 assume one of the following values:
6026 @item @code{GL_COLOR_ARRAY}
6027 If enabled, the color array is enabled for writing and used during
6028 rendering when @code{glArrayElement}, @code{glDrawArrays},
6029 @code{glDrawElements},
6030 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6031 @code{glMultiDrawElements} is called. See @code{glColorPointer}.
6033 @item @code{GL_EDGE_FLAG_ARRAY}
6034 If enabled, the edge flag array is enabled for writing and used during
6035 rendering when @code{glArrayElement}, @code{glDrawArrays},
6036 @code{glDrawElements},
6037 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6038 @code{glMultiDrawElements} is called. See @code{glEdgeFlagPointer}.
6040 @item @code{GL_FOG_COORD_ARRAY}
6041 If enabled, the fog coordinate array is enabled for writing and used
6042 during rendering when @code{glArrayElement}, @code{glDrawArrays},
6043 @code{glDrawElements},
6044 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6045 @code{glMultiDrawElements} is called. See @code{glFogCoordPointer}.
6047 @item @code{GL_INDEX_ARRAY}
6048 If enabled, the index array is enabled for writing and used during
6049 rendering when @code{glArrayElement}, @code{glDrawArrays},
6050 @code{glDrawElements},
6051 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6052 @code{glMultiDrawElements} is called. See @code{glIndexPointer}.
6054 @item @code{GL_NORMAL_ARRAY}
6055 If enabled, the normal array is enabled for writing and used during
6056 rendering when @code{glArrayElement}, @code{glDrawArrays},
6057 @code{glDrawElements},
6058 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6059 @code{glMultiDrawElements} is called. See @code{glNormalPointer}.
6061 @item @code{GL_SECONDARY_COLOR_ARRAY}
6062 If enabled, the secondary color array is enabled for writing and used
6063 during rendering when @code{glArrayElement}, @code{glDrawArrays},
6064 @code{glDrawElements},
6065 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6066 @code{glMultiDrawElements} is called. See @code{glColorPointer}.
6068 @item @code{GL_TEXTURE_COORD_ARRAY}
6069 If enabled, the texture coordinate array is enabled for writing and used
6070 during rendering when @code{glArrayElement}, @code{glDrawArrays},
6071 @code{glDrawElements},
6072 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6073 @code{glMultiDrawElements} is called. See @code{glTexCoordPointer}.
6075 @item @code{GL_VERTEX_ARRAY}
6076 If enabled, the vertex array is enabled for writing and used during
6077 rendering when @code{glArrayElement}, @code{glDrawArrays},
6078 @code{glDrawElements},
6079 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6080 @code{glMultiDrawElements} is called. See @code{glVertexPointer}.
6084 @code{GL_INVALID_ENUM} is generated if @var{cap} is not an accepted
6087 @code{glEnableClientState} is not allowed between the execution of
6088 @code{glBegin} and the corresponding @code{glEnd}, but an error may or
6089 may not be generated. If no error is generated, the behavior is
6094 @deftypefun void glEnableVertexAttribArray index
6095 @deftypefunx void glDisableVertexAttribArray index
6096 Enable or disable a generic vertex attribute array.
6100 Specifies the index of the generic vertex attribute to be enabled or
6105 @code{glEnableVertexAttribArray} enables the generic vertex attribute
6106 array specified by @var{index}. @code{glDisableVertexAttribArray}
6107 disables the generic vertex attribute array specified by @var{index}. By
6108 default, all client-side capabilities are disabled, including all
6109 generic vertex attribute arrays. If enabled, the values in the generic
6110 vertex attribute array will be accessed and used for rendering when
6111 calls are made to vertex array commands such as @code{glDrawArrays},
6112 @code{glDrawElements}, @code{glDrawRangeElements},
6113 @code{glArrayElement}, @code{glMultiDrawElements}, or
6114 @code{glMultiDrawArrays}.
6116 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
6117 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
6119 @code{GL_INVALID_OPERATION} is generated if either
6120 @code{glEnableVertexAttribArray } or @code{glDisableVertexAttribArray }
6121 is executed between the execution of @code{glBegin} and the
6122 corresponding execution of @code{glEnd}.
6126 @deftypefun void glEnable cap
6127 @deftypefunx void glDisable cap
6128 Enable or disable server-side GL capabilities.
6132 Specifies a symbolic constant indicating a GL capability.
6136 @code{glEnable} and @code{glDisable} enable and disable various
6137 capabilities. Use @code{glIsEnabled} or @code{glGet} to determine the
6138 current setting of any capability. The initial value for each capability
6139 with the exception of @code{GL_DITHER} and @code{GL_MULTISAMPLE} is
6140 @code{GL_FALSE}. The initial value for @code{GL_DITHER} and
6141 @code{GL_MULTISAMPLE} is @code{GL_TRUE}.
6143 Both @code{glEnable} and @code{glDisable} take a single argument,
6144 @var{cap}, which can assume one of the following values:
6147 @item @code{GL_ALPHA_TEST}
6150 If enabled, do alpha testing. See @code{glAlphaFunc}.
6152 @item @code{GL_AUTO_NORMAL}
6155 If enabled, generate normal vectors when either @code{GL_MAP2_VERTEX_3}
6156 or @code{GL_MAP2_VERTEX_4} is used to generate vertices. See
6159 @item @code{GL_BLEND}
6162 If enabled, blend the computed fragment color values with the values in
6163 the color buffers. See @code{glBlendFunc}.
6165 @item @code{GL_CLIP_PLANE}@var{i}
6168 If enabled, clip geometry against user-defined clipping plane @var{i}.
6169 See @code{glClipPlane}.
6171 @item @code{GL_COLOR_LOGIC_OP}
6174 If enabled, apply the currently selected logical operation to the
6175 computed fragment color and color buffer values. See @code{glLogicOp}.
6177 @item @code{GL_COLOR_MATERIAL}
6180 If enabled, have one or more material parameters track the current
6181 color. See @code{glColorMaterial}.
6183 @item @code{GL_COLOR_SUM}
6186 If enabled and no fragment shader is active, add the secondary color
6187 value to the computed fragment color. See @code{glSecondaryColor}.
6189 @item @code{GL_COLOR_TABLE}
6192 If enabled, perform a color table lookup on the incoming RGBA color
6193 values. See @code{glColorTable}.
6195 @item @code{GL_CONVOLUTION_1D}
6198 If enabled, perform a 1D convolution operation on incoming RGBA color
6199 values. See @code{glConvolutionFilter1D}.
6201 @item @code{GL_CONVOLUTION_2D}
6204 If enabled, perform a 2D convolution operation on incoming RGBA color
6205 values. See @code{glConvolutionFilter2D}.
6207 @item @code{GL_CULL_FACE}
6210 If enabled, cull polygons based on their winding in window coordinates.
6211 See @code{glCullFace}.
6213 @item @code{GL_DEPTH_TEST}
6216 If enabled, do depth comparisons and update the depth buffer. Note that
6217 even if the depth buffer exists and the depth mask is non-zero, the
6218 depth buffer is not updated if the depth test is disabled. See
6219 @code{glDepthFunc} and @code{glDepthRange}.
6221 @item @code{GL_DITHER}
6224 If enabled, dither color components or indices before they are written
6225 to the color buffer.
6230 If enabled and no fragment shader is active, blend a fog color into the
6231 post-texturing color. See @code{glFog}.
6233 @item @code{GL_HISTOGRAM}
6236 If enabled, histogram incoming RGBA color values. See
6239 @item @code{GL_INDEX_LOGIC_OP}
6242 If enabled, apply the currently selected logical operation to the
6243 incoming index and color buffer indices. See @code{glLogicOp}.
6245 @item @code{GL_LIGHT}@var{i}
6248 If enabled, include light @var{i} in the evaluation of the lighting
6249 equation. See @code{glLightModel} and @code{glLight}.
6251 @item @code{GL_LIGHTING}
6254 If enabled and no vertex shader is active, use the current lighting
6255 parameters to compute the vertex color or index. Otherwise, simply
6256 associate the current color or index with each vertex. See
6257 @code{glMaterial}, @code{glLightModel}, and @code{glLight}.
6259 @item @code{GL_LINE_SMOOTH}
6262 If enabled, draw lines with correct filtering. Otherwise, draw aliased
6263 lines. See @code{glLineWidth}.
6265 @item @code{GL_LINE_STIPPLE}
6268 If enabled, use the current line stipple pattern when drawing lines. See
6269 @code{glLineStipple}.
6271 @item @code{GL_MAP1_COLOR_4}
6274 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6275 @code{glEvalPoint1} generate RGBA values. See @code{glMap1}.
6277 @item @code{GL_MAP1_INDEX}
6280 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6281 @code{glEvalPoint1} generate color indices. See @code{glMap1}.
6283 @item @code{GL_MAP1_NORMAL}
6286 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6287 @code{glEvalPoint1} generate normals. See @code{glMap1}.
6289 @item @code{GL_MAP1_TEXTURE_COORD_1}
6292 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6293 @code{glEvalPoint1} generate @var{s} texture coordinates. See
6296 @item @code{GL_MAP1_TEXTURE_COORD_2}
6299 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6300 @code{glEvalPoint1} generate @var{s} and @var{t} texture coordinates.
6303 @item @code{GL_MAP1_TEXTURE_COORD_3}
6306 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6307 @code{glEvalPoint1} generate @var{s}, @var{t}, and @var{r} texture
6308 coordinates. See @code{glMap1}.
6310 @item @code{GL_MAP1_TEXTURE_COORD_4}
6313 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6314 @code{glEvalPoint1} generate @var{s}, @var{t}, @var{r}, and @var{q}
6315 texture coordinates. See @code{glMap1}.
6317 @item @code{GL_MAP1_VERTEX_3}
6320 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6321 @code{glEvalPoint1} generate @var{x}, @var{y}, and @var{z} vertex
6322 coordinates. See @code{glMap1}.
6324 @item @code{GL_MAP1_VERTEX_4}
6327 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6328 @code{glEvalPoint1} generate homogeneous @var{x}, @var{y}, @var{z}, and
6329 @var{w} vertex coordinates. See @code{glMap1}.
6331 @item @code{GL_MAP2_COLOR_4}
6334 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6335 @code{glEvalPoint2} generate RGBA values. See @code{glMap2}.
6337 @item @code{GL_MAP2_INDEX}
6340 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6341 @code{glEvalPoint2} generate color indices. See @code{glMap2}.
6343 @item @code{GL_MAP2_NORMAL}
6346 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6347 @code{glEvalPoint2} generate normals. See @code{glMap2}.
6349 @item @code{GL_MAP2_TEXTURE_COORD_1}
6352 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6353 @code{glEvalPoint2} generate @var{s} texture coordinates. See
6356 @item @code{GL_MAP2_TEXTURE_COORD_2}
6359 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6360 @code{glEvalPoint2} generate @var{s} and @var{t} texture coordinates.
6363 @item @code{GL_MAP2_TEXTURE_COORD_3}
6366 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6367 @code{glEvalPoint2} generate @var{s}, @var{t}, and @var{r} texture
6368 coordinates. See @code{glMap2}.
6370 @item @code{GL_MAP2_TEXTURE_COORD_4}
6373 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6374 @code{glEvalPoint2} generate @var{s}, @var{t}, @var{r}, and @var{q}
6375 texture coordinates. See @code{glMap2}.
6377 @item @code{GL_MAP2_VERTEX_3}
6380 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6381 @code{glEvalPoint2} generate @var{x}, @var{y}, and @var{z} vertex
6382 coordinates. See @code{glMap2}.
6384 @item @code{GL_MAP2_VERTEX_4}
6387 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6388 @code{glEvalPoint2} generate homogeneous @var{x}, @var{y}, @var{z}, and
6389 @var{w} vertex coordinates. See @code{glMap2}.
6391 @item @code{GL_MINMAX}
6394 If enabled, compute the minimum and maximum values of incoming RGBA
6395 color values. See @code{glMinmax}.
6397 @item @code{GL_MULTISAMPLE}
6400 If enabled, use multiple fragment samples in computing the final color
6401 of a pixel. See @code{glSampleCoverage}.
6403 @item @code{GL_NORMALIZE}
6406 If enabled and no vertex shader is active, normal vectors are normalized
6407 to unit length after transformation and before lighting. This method is
6408 generally less efficient than @code{GL_RESCALE_NORMAL}. See
6409 @code{glNormal} and @code{glNormalPointer}.
6411 @item @code{GL_POINT_SMOOTH}
6414 If enabled, draw points with proper filtering. Otherwise, draw aliased
6415 points. See @code{glPointSize}.
6417 @item @code{GL_POINT_SPRITE}
6420 If enabled, calculate texture coordinates for points based on texture
6421 environment and point parameter settings. Otherwise texture coordinates
6422 are constant across points.
6424 @item @code{GL_POLYGON_OFFSET_FILL}
6427 If enabled, and if the polygon is rendered in @code{GL_FILL} mode, an
6428 offset is added to depth values of a polygon's fragments before the
6429 depth comparison is performed. See @code{glPolygonOffset}.
6431 @item @code{GL_POLYGON_OFFSET_LINE}
6434 If enabled, and if the polygon is rendered in @code{GL_LINE} mode, an
6435 offset is added to depth values of a polygon's fragments before the
6436 depth comparison is performed. See @code{glPolygonOffset}.
6438 @item @code{GL_POLYGON_OFFSET_POINT}
6441 If enabled, an offset is added to depth values of a polygon's fragments
6442 before the depth comparison is performed, if the polygon is rendered in
6443 @code{GL_POINT} mode. See @code{glPolygonOffset}.
6445 @item @code{GL_POLYGON_SMOOTH}
6448 If enabled, draw polygons with proper filtering. Otherwise, draw aliased
6449 polygons. For correct antialiased polygons, an alpha buffer is needed
6450 and the polygons must be sorted front to back.
6452 @item @code{GL_POLYGON_STIPPLE}
6455 If enabled, use the current polygon stipple pattern when rendering
6456 polygons. See @code{glPolygonStipple}.
6458 @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}
6461 If enabled, perform a color table lookup on RGBA color values after
6462 color matrix transformation. See @code{glColorTable}.
6464 @item @code{GL_POST_CONVOLUTION_COLOR_TABLE}
6467 If enabled, perform a color table lookup on RGBA color values after
6468 convolution. See @code{glColorTable}.
6470 @item @code{GL_RESCALE_NORMAL}
6473 If enabled and no vertex shader is active, normal vectors are scaled
6474 after transformation and before lighting by a factor computed from the
6475 modelview matrix. If the modelview matrix scales space uniformly, this
6476 has the effect of restoring the transformed normal to unit length. This
6477 method is generally more efficient than @code{GL_NORMALIZE}. See
6478 @code{glNormal} and @code{glNormalPointer}.
6480 @item @code{GL_SAMPLE_ALPHA_TO_COVERAGE}
6483 If enabled, compute a temporary coverage value where each bit is
6484 determined by the alpha value at the corresponding sample location. The
6485 temporary coverage value is then ANDed with the fragment coverage value.
6487 @item @code{GL_SAMPLE_ALPHA_TO_ONE}
6490 If enabled, each sample alpha value is replaced by the maximum
6491 representable alpha value.
6493 @item @code{GL_SAMPLE_COVERAGE}
6496 If enabled, the fragment's coverage is ANDed with the temporary coverage
6497 value. If @code{GL_SAMPLE_COVERAGE_INVERT} is set to @code{GL_TRUE},
6498 invert the coverage value. See @code{glSampleCoverage}.
6500 @item @code{GL_SEPARABLE_2D}
6503 If enabled, perform a two-dimensional convolution operation using a
6504 separable convolution filter on incoming RGBA color values. See
6505 @code{glSeparableFilter2D}.
6507 @item @code{GL_SCISSOR_TEST}
6510 If enabled, discard fragments that are outside the scissor rectangle.
6511 See @code{glScissor}.
6513 @item @code{GL_STENCIL_TEST}
6516 If enabled, do stencil testing and update the stencil buffer. See
6517 @code{glStencilFunc} and @code{glStencilOp}.
6519 @item @code{GL_TEXTURE_1D}
6522 If enabled and no fragment shader is active, one-dimensional texturing
6523 is performed (unless two- or three-dimensional or cube-mapped texturing
6524 is also enabled). See @code{glTexImage1D}.
6526 @item @code{GL_TEXTURE_2D}
6529 If enabled and no fragment shader is active, two-dimensional texturing
6530 is performed (unless three-dimensional or cube-mapped texturing is also
6531 enabled). See @code{glTexImage2D}.
6533 @item @code{GL_TEXTURE_3D}
6536 If enabled and no fragment shader is active, three-dimensional texturing
6537 is performed (unless cube-mapped texturing is also enabled). See
6538 @code{glTexImage3D}.
6540 @item @code{GL_TEXTURE_CUBE_MAP}
6543 If enabled and no fragment shader is active, cube-mapped texturing is
6544 performed. See @code{glTexImage2D}.
6546 @item @code{GL_TEXTURE_GEN_Q}
6549 If enabled and no vertex shader is active, the @var{q} texture
6550 coordinate is computed using the texture generation function defined
6551 with @code{glTexGen}. Otherwise, the current @var{q} texture coordinate
6552 is used. See @code{glTexGen}.
6554 @item @code{GL_TEXTURE_GEN_R}
6557 If enabled and no vertex shader is active, the @var{r} texture
6558 coordinate is computed using the texture generation function defined
6559 with @code{glTexGen}. Otherwise, the current @var{r} texture coordinate
6560 is used. See @code{glTexGen}.
6562 @item @code{GL_TEXTURE_GEN_S}
6565 If enabled and no vertex shader is active, the @var{s} texture
6566 coordinate is computed using the texture generation function defined
6567 with @code{glTexGen}. Otherwise, the current @var{s} texture coordinate
6568 is used. See @code{glTexGen}.
6570 @item @code{GL_TEXTURE_GEN_T}
6573 If enabled and no vertex shader is active, the @var{t} texture
6574 coordinate is computed using the texture generation function defined
6575 with @code{glTexGen}. Otherwise, the current @var{t} texture coordinate
6576 is used. See @code{glTexGen}.
6578 @item @code{GL_VERTEX_PROGRAM_POINT_SIZE}
6581 If enabled and a vertex shader is active, then the derived point size is
6582 taken from the (potentially clipped) shader builtin @code{gl_PointSize}
6583 and clamped to the implementation-dependent point size range.
6585 @item @code{GL_VERTEX_PROGRAM_TWO_SIDE}
6588 If enabled and a vertex shader is active, it specifies that the GL will
6589 choose between front and back colors based on the polygon's face
6590 direction of which the vertex being shaded is a part. It has no effect
6595 @code{GL_INVALID_ENUM} is generated if @var{cap} is not one of the
6596 values listed previously.
6598 @code{GL_INVALID_OPERATION} is generated if @code{glEnable} or
6599 @code{glDisable} is executed between the execution of @code{glBegin} and
6600 the corresponding execution of @code{glEnd}.
6604 @deftypefun void glEvalCoord1f u
6605 @deftypefunx void glEvalCoord2f u v
6606 Evaluate enabled one- and two-dimensional maps.
6610 Specifies a value that is the domain coordinate @r{@var{u}} to the basis
6611 function defined in a previous @code{glMap1} or @code{glMap2} command.
6614 Specifies a value that is the domain coordinate @r{@var{v}} to the basis
6615 function defined in a previous @code{glMap2} command. This argument is
6616 not present in a @code{glEvalCoord1} command.
6620 @code{glEvalCoord1} evaluates enabled one-dimensional maps at argument
6621 @var{u}. @code{glEvalCoord2} does the same for two-dimensional maps
6622 using two domain values, @var{u} and @var{v}. To define a map, call
6623 @code{glMap1} and @code{glMap2}; to enable and disable it, call
6624 @code{glEnable} and @code{glDisable}.
6626 When one of the @code{glEvalCoord} commands is issued, all currently
6627 enabled maps of the indicated dimension are evaluated. Then, for each
6628 enabled map, it is as if the corresponding GL command had been issued
6629 with the computed value. That is, if @code{GL_MAP1_INDEX} or
6630 @code{GL_MAP2_INDEX} is enabled, a @code{glIndex} command is simulated.
6631 If @code{GL_MAP1_COLOR_4} or @code{GL_MAP2_COLOR_4} is enabled, a
6632 @code{glColor} command is simulated. If @code{GL_MAP1_NORMAL} or
6633 @code{GL_MAP2_NORMAL} is enabled, a normal vector is produced, and if
6634 any of @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2},
6635 @code{GL_MAP1_TEXTURE_COORD_3}, @code{GL_MAP1_TEXTURE_COORD_4},
6636 @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2},
6637 @code{GL_MAP2_TEXTURE_COORD_3}, or @code{GL_MAP2_TEXTURE_COORD_4} is
6638 enabled, then an appropriate @code{glTexCoord} command is simulated.
6640 For color, color index, normal, and texture coordinates the GL uses
6641 evaluated values instead of current values for those evaluations that
6642 are enabled, and current values otherwise, However, the evaluated values
6643 do not update the current values. Thus, if @code{glVertex} commands are
6644 interspersed with @code{glEvalCoord} commands, the color, normal, and
6645 texture coordinates associated with the @code{glVertex} commands are not
6646 affected by the values generated by the @code{glEvalCoord} commands, but
6647 only by the most recent @code{glColor}, @code{glIndex}, @code{glNormal},
6648 and @code{glTexCoord} commands.
6650 No commands are issued for maps that are not enabled. If more than one
6651 texture evaluation is enabled for a particular dimension (for example,
6652 @code{GL_MAP2_TEXTURE_COORD_1} and @code{GL_MAP2_TEXTURE_COORD_2}), then
6653 only the evaluation of the map that produces the larger number of
6654 coordinates (in this case, @code{GL_MAP2_TEXTURE_COORD_2}) is carried
6655 out. @code{GL_MAP1_VERTEX_4} overrides @code{GL_MAP1_VERTEX_3}, and
6656 @code{GL_MAP2_VERTEX_4} overrides @code{GL_MAP2_VERTEX_3}, in the same
6657 manner. If neither a three- nor a four-component vertex map is enabled
6658 for the specified dimension, the @code{glEvalCoord} command is ignored.
6660 If you have enabled automatic normal generation, by calling
6661 @code{glEnable} with argument @code{GL_AUTO_NORMAL}, @code{glEvalCoord2}
6662 generates surface normals analytically, regardless of the contents or
6663 enabling of the @code{GL_MAP2_NORMAL} map. Let
6665 @r{@code{m}=∂@code{p},/∂@var{u},,×∂@code{p},/∂@var{v},,}
6667 Then the generated normal @r{@code{n}} is
6668 @r{@code{n}=@code{m}/∥@code{m},∥,}
6670 If automatic normal generation is disabled, the corresponding normal map
6671 @code{GL_MAP2_NORMAL}, if enabled, is used to produce a normal. If
6672 neither automatic normal generation nor a normal map is enabled, no
6673 normal is generated for @code{glEvalCoord2} commands.
6677 @deftypefun void glEvalMesh1 mode i1 i2
6678 @deftypefunx void glEvalMesh2 mode i1 i2 j1 j2
6679 Compute a one- or two-dimensional grid of points or lines.
6683 In @code{glEvalMesh1}, specifies whether to compute a one-dimensional
6684 mesh of points or lines. Symbolic constants @code{GL_POINT} and
6685 @code{GL_LINE} are accepted.
6689 Specify the first and last integer values for grid domain variable
6694 @code{glMapGrid} and @code{glEvalMesh} are used in tandem to efficiently
6695 generate and evaluate a series of evenly-spaced map domain values.
6696 @code{glEvalMesh} steps through the integer domain of a one- or
6697 two-dimensional grid, whose range is the domain of the evaluation maps
6698 specified by @code{glMap1} and @code{glMap2}. @var{mode} determines
6699 whether the resulting vertices are connected as points, lines, or filled
6702 In the one-dimensional case, @code{glEvalMesh1}, the mesh is generated
6703 as if the following code fragment were executed:
6709 glBegin( @var{type} );
6710 for ( i = @var{i1}; i <= @var{i2}; i += 1 )
6711 glEvalCoord1( @r{i·Δ@var{u}+@var{u}_1} );
6715 @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}
6717 and @r{@var{n}}, @r{@var{u}_1}, and @r{@var{u}_2} are the arguments to
6718 the most recent @code{glMapGrid1} command. @var{type} is
6719 @code{GL_POINTS} if @var{mode} is @code{GL_POINT}, or @code{GL_LINES} if
6720 @var{mode} is @code{GL_LINE}.
6722 The one absolute numeric requirement is that if @r{@var{i}=@var{n}},
6723 then the value computed from @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly
6726 In the two-dimensional case, @code{glEvalMesh2}, let .cp
6727 @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}
6729 @r{Δ@var{v}=(@var{v}_2-@var{v}_1,)/@var{m}}
6731 where @r{@var{n}}, @r{@var{u}_1}, @r{@var{u}_2}, @r{@var{m}},
6732 @r{@var{v}_1}, and @r{@var{v}_2} are the arguments to the most recent
6733 @code{glMapGrid2} command. Then, if @var{mode} is @code{GL_FILL}, the
6734 @code{glEvalMesh2} command is equivalent to:
6740 for ( j = @var{j1}; j < @var{j2}; j += 1 ) @{
6741 glBegin( GL_QUAD_STRIP );
6742 for ( i = @var{i1}; i <= @var{i2}; i += 1 ) @{
6743 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6744 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,(j+1,)·Δ@var{v}+@var{v}_1} );
6750 If @var{mode} is @code{GL_LINE}, then a call to @code{glEvalMesh2} is
6757 for ( j = @var{j1}; j <= @var{j2}; j += 1 ) @{
6758 glBegin( GL_LINE_STRIP );
6759 for ( i = @var{i1}; i <= @var{i2}; i += 1 )
6760 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6764 for ( i = @var{i1}; i <= @var{i2}; i += 1 ) @{
6765 glBegin( GL_LINE_STRIP );
6766 for ( j = @var{j1}; j <= @var{j1}; j += 1 )
6767 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6772 And finally, if @var{mode} is @code{GL_POINT}, then a call to
6773 @code{glEvalMesh2} is equivalent to:
6779 glBegin( GL_POINTS );
6780 for ( j = @var{j1}; j <= @var{j2}; j += 1 )
6781 for ( i = @var{i1}; i <= @var{i2}; i += 1 )
6782 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6786 In all three cases, the only absolute numeric requirements are that if
6787 @r{@var{i}=@var{n}}, then the value computed from
6788 @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}, and if
6789 @r{@var{j}=@var{m}}, then the value computed from
6790 @r{@var{j}·Δ@var{v}+@var{v}_1} is exactly @r{@var{v}_2}.
6792 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
6795 @code{GL_INVALID_OPERATION} is generated if @code{glEvalMesh} is
6796 executed between the execution of @code{glBegin} and the corresponding
6797 execution of @code{glEnd}.
6801 @deftypefun void glEvalPoint1 i
6802 @deftypefunx void glEvalPoint2 i j
6803 Generate and evaluate a single point in a mesh.
6807 Specifies the integer value for grid domain variable @r{@var{i}}.
6810 Specifies the integer value for grid domain variable @r{@var{j}}
6811 (@code{glEvalPoint2} only).
6815 @code{glMapGrid} and @code{glEvalMesh} are used in tandem to efficiently
6816 generate and evaluate a series of evenly spaced map domain values.
6817 @code{glEvalPoint} can be used to evaluate a single grid point in the
6818 same gridspace that is traversed by @code{glEvalMesh}. Calling
6819 @code{glEvalPoint1} is equivalent to calling where
6820 @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}
6824 glEvalCoord1( @r{i·Δ@var{u}+@var{u}_1} );
6827 and @r{@var{n}}, @r{@var{u}_1}, and @r{@var{u}_2} are the arguments to
6828 the most recent @code{glMapGrid1} command. The one absolute numeric
6829 requirement is that if @r{@var{i}=@var{n}}, then the value computed from
6830 @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}.
6832 In the two-dimensional case, @code{glEvalPoint2}, let
6834 @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}@r{Δ@var{v}=(@var{v}_2-@var{v}_1,)/@var{m}}
6836 where @r{@var{n}}, @r{@var{u}_1}, @r{@var{u}_2}, @r{@var{m}},
6837 @r{@var{v}_1}, and @r{@var{v}_2} are the arguments to the most recent
6838 @code{glMapGrid2} command. Then the @code{glEvalPoint2} command is
6839 equivalent to calling The only absolute numeric requirements are that if
6840 @r{@var{i}=@var{n}}, then the value computed from
6841 @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}, and if
6842 @r{@var{j}=@var{m}}, then the value computed from
6843 @r{@var{j}·Δ@var{v}+@var{v}_1} is exactly @r{@var{v}_2}.
6847 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6852 @deftypefun void glFeedbackBuffer size type buffer
6853 Controls feedback mode.
6857 Specifies the maximum number of values that can be written into
6861 Specifies a symbolic constant that describes the information that will
6862 be returned for each vertex. @code{GL_2D}, @code{GL_3D},
6863 @code{GL_3D_COLOR}, @code{GL_3D_COLOR_TEXTURE}, and
6864 @code{GL_4D_COLOR_TEXTURE} are accepted.
6867 Returns the feedback data.
6871 The @code{glFeedbackBuffer} function controls feedback. Feedback, like
6872 selection, is a GL mode. The mode is selected by calling
6873 @code{glRenderMode} with @code{GL_FEEDBACK}. When the GL is in feedback
6874 mode, no pixels are produced by rasterization. Instead, information
6875 about primitives that would have been rasterized is fed back to the
6876 application using the GL.
6878 @code{glFeedbackBuffer} has three arguments: @var{buffer} is a pointer
6879 to an array of floating-point values into which feedback information is
6880 placed. @var{size} indicates the size of the array. @var{type} is a
6881 symbolic constant describing the information that is fed back for each
6882 vertex. @code{glFeedbackBuffer} must be issued before feedback mode is
6883 enabled (by calling @code{glRenderMode} with argument
6884 @code{GL_FEEDBACK}). Setting @code{GL_FEEDBACK} without establishing the
6885 feedback buffer, or calling @code{glFeedbackBuffer} while the GL is in
6886 feedback mode, is an error.
6888 When @code{glRenderMode} is called while in feedback mode, it returns
6889 the number of entries placed in the feedback array and resets the
6890 feedback array pointer to the base of the feedback buffer. The returned
6891 value never exceeds @var{size}. If the feedback data required more room
6892 than was available in @var{buffer}, @code{glRenderMode} returns a
6893 negative value. To take the GL out of feedback mode, call
6894 @code{glRenderMode} with a parameter value other than
6897 While in feedback mode, each primitive, bitmap, or pixel rectangle that
6898 would be rasterized generates a block of values that are copied into the
6899 feedback array. If doing so would cause the number of entries to exceed
6900 the maximum, the block is partially written so as to fill the array (if
6901 there is any room left at all), and an overflow flag is set. Each block
6902 begins with a code indicating the primitive type, followed by values
6903 that describe the primitive's vertices and associated data. Entries are
6904 also written for bitmaps and pixel rectangles. Feedback occurs after
6905 polygon culling and @code{glPolygonMode} interpretation of polygons has
6906 taken place, so polygons that are culled are not returned in the
6907 feedback buffer. It can also occur after polygons with more than three
6908 edges are broken up into triangles, if the GL implementation renders
6909 polygons by performing this decomposition.
6911 The @code{glPassThrough} command can be used to insert a marker into the
6912 feedback buffer. See @code{glPassThrough}.
6914 Following is the grammar for the blocks of values written into the
6915 feedback buffer. Each primitive is indicated with a unique identifying
6916 value followed by some number of vertices. Polygon entries include an
6917 integer value indicating how many vertices follow. A vertex is fed back
6918 as some number of floating-point values, as determined by @var{type}.
6919 Colors are fed back as four values in RGBA mode and one value in color
6922 feedbackList @r{←} feedbackItem feedbackList | feedbackItem feedbackItem
6923 @r{←} point | lineSegment | polygon | bitmap | pixelRectangle | passThru
6924 point @r{←}@code{GL_POINT_TOKEN} vertex lineSegment
6925 @r{←}@code{GL_LINE_TOKEN} vertex vertex | @code{GL_LINE_RESET_TOKEN}
6926 vertex vertex polygon @r{←}@code{GL_POLYGON_TOKEN} n polySpec polySpec
6927 @r{←} polySpec vertex | vertex vertex vertex bitmap
6928 @r{←}@code{GL_BITMAP_TOKEN} vertex pixelRectangle
6929 @r{←}@code{GL_DRAW_PIXEL_TOKEN} vertex | @code{GL_COPY_PIXEL_TOKEN}
6930 vertex passThru @r{←}@code{GL_PASS_THROUGH_TOKEN} value vertex @r{←} 2d
6931 | 3d | 3dColor | 3dColorTexture | 4dColorTexture 2d @r{←} value value 3d
6932 @r{←} value value value 3dColor @r{←} value value value color
6933 3dColorTexture @r{←} value value value color tex 4dColorTexture @r{←}
6934 value value value value color tex color @r{←} rgba | index rgba @r{←}
6935 value value value value index @r{←} value tex @r{←} value value value
6938 @var{value} is a floating-point number, and @var{n} is a floating-point
6939 integer giving the number of vertices in the polygon.
6940 @code{GL_POINT_TOKEN}, @code{GL_LINE_TOKEN}, @code{GL_LINE_RESET_TOKEN},
6941 @code{GL_POLYGON_TOKEN}, @code{GL_BITMAP_TOKEN},
6942 @code{GL_DRAW_PIXEL_TOKEN}, @code{GL_COPY_PIXEL_TOKEN} and
6943 @code{GL_PASS_THROUGH_TOKEN} are symbolic floating-point constants.
6944 @code{GL_LINE_RESET_TOKEN} is returned whenever the line stipple pattern
6945 is reset. The data returned as a vertex depends on the feedback
6948 The following table gives the correspondence between @var{type} and the
6949 number of values per vertex. @var{k} is 1 in color index mode and 4 in
6956 @strong{Coordinates}, @strong{Color}, @strong{Texture}, @strong{Total
6960 @var{x}, @var{y}, , , 2
6963 @var{x}, @var{y}, @var{z}, , , 3
6965 @item @code{GL_3D_COLOR}
6966 @var{x}, @var{y}, @var{z}, @r{@var{k}}, , @r{3+@var{k}}
6968 @item @code{GL_3D_COLOR_TEXTURE}
6969 @var{x}, @var{y}, @var{z}, @r{@var{k}}, 4 , @r{7+@var{k}}
6971 @item @code{GL_4D_COLOR_TEXTURE}
6972 @var{x}, @var{y}, @var{z}, @var{w}, @r{@var{k}}, 4 , @r{8+@var{k}}
6976 Feedback vertex coordinates are in window coordinates, except @var{w},
6977 which is in clip coordinates. Feedback colors are lighted, if lighting
6978 is enabled. Feedback texture coordinates are generated, if texture
6979 coordinate generation is enabled. They are always transformed by the
6982 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
6985 @code{GL_INVALID_VALUE} is generated if @var{size} is negative.
6987 @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is
6988 called while the render mode is @code{GL_FEEDBACK}, or if
6989 @code{glRenderMode} is called with argument @code{GL_FEEDBACK} before
6990 @code{glFeedbackBuffer} is called at least once.
6992 @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is
6993 executed between the execution of @code{glBegin} and the corresponding
6994 execution of @code{glEnd}.
6998 @deftypefun void glFinish
6999 Block until all GL execution is complete.
7001 @code{glFinish} does not return until the effects of all previously
7002 called GL commands are complete. Such effects include all changes to GL
7003 state, all changes to connection state, and all changes to the frame
7006 @code{GL_INVALID_OPERATION} is generated if @code{glFinish} is executed
7007 between the execution of @code{glBegin} and the corresponding execution
7012 @deftypefun void glFlush
7013 Force execution of GL commands in finite time.
7015 Different GL implementations buffer commands in several different
7016 locations, including network buffers and the graphics accelerator
7017 itself. @code{glFlush} empties all of these buffers, causing all issued
7018 commands to be executed as quickly as they are accepted by the actual
7019 rendering engine. Though this execution may not be completed in any
7020 particular time period, it does complete in finite time.
7022 Because any GL program might be executed over a network, or on an
7023 accelerator that buffers commands, all programs should call
7024 @code{glFlush} whenever they count on having all of their previously
7025 issued commands completed. For example, call @code{glFlush} before
7026 waiting for user input that depends on the generated image.
7028 @code{GL_INVALID_OPERATION} is generated if @code{glFlush} is executed
7029 between the execution of @code{glBegin} and the corresponding execution
7034 @deftypefun void glFogCoordPointer type stride pointer
7035 Define an array of fog coordinates.
7039 Specifies the data type of each fog coordinate. Symbolic constants
7040 @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is
7044 Specifies the byte offset between consecutive fog coordinates. If
7045 @var{stride} is 0, the array elements are understood to be tightly
7046 packed. The initial value is 0.
7049 Specifies a pointer to the first coordinate of the first fog coordinate
7050 in the array. The initial value is 0.
7054 @code{glFogCoordPointer} specifies the location and data format of an
7055 array of fog coordinates to use when rendering. @var{type} specifies the
7056 data type of each fog coordinate, and @var{stride} specifies the byte
7057 stride from one fog coordinate to the next, allowing vertices and
7058 attributes to be packed into a single array or stored in separate
7061 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
7062 target (see @code{glBindBuffer}) while a fog coordinate array is
7063 specified, @var{pointer} is treated as a byte offset into the buffer
7064 object's data store. Also, the buffer object binding
7065 (@code{GL_ARRAY_BUFFER_BINDING}) is saved as fog coordinate vertex array
7066 client-side state (@code{GL_FOG_COORD_ARRAY_BUFFER_BINDING}).
7068 When a fog coordinate array is specified, @var{type}, @var{stride}, and
7069 @var{pointer} are saved as client-side state, in addition to the current
7070 vertex array buffer object binding.
7072 To enable and disable the fog coordinate array, call
7073 @code{glEnableClientState} and @code{glDisableClientState} with the
7074 argument @code{GL_FOG_COORD_ARRAY}. If enabled, the fog coordinate array
7075 is used when @code{glDrawArrays}, @code{glMultiDrawArrays},
7076 @code{glDrawElements}, @code{glMultiDrawElements},
7077 @code{glDrawRangeElements}, or @code{glArrayElement} is called.
7079 @code{GL_INVALID_ENUM} is generated if @var{type} is not either
7080 @code{GL_FLOAT} or @code{GL_DOUBLE}.
7082 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
7086 @deftypefun void glFogCoordf coord
7087 Set the current fog coordinates.
7091 Specify the fog distance.
7095 @code{glFogCoord} specifies the fog coordinate that is associated with
7096 each vertex and the current raster position. The value specified is
7097 interpolated and used in computing the fog color (see @code{glFog}).
7101 @deftypefun void glFogf pname param
7102 @deftypefunx void glFogi pname param
7103 Specify fog parameters.
7107 Specifies a single-valued fog parameter. @code{GL_FOG_MODE},
7108 @code{GL_FOG_DENSITY}, @code{GL_FOG_START}, @code{GL_FOG_END},
7109 @code{GL_FOG_INDEX}, and @code{GL_FOG_COORD_SRC} are accepted.
7112 Specifies the value that @var{pname} will be set to.
7116 Fog is initially disabled. While enabled, fog affects rasterized
7117 geometry, bitmaps, and pixel blocks, but not buffer clear operations. To
7118 enable and disable fog, call @code{glEnable} and @code{glDisable} with
7119 argument @code{GL_FOG}.
7121 @code{glFog} assigns the value or values in @var{params} to the fog
7122 parameter specified by @var{pname}. The following values are accepted
7126 @item @code{GL_FOG_MODE}
7127 @var{params} is a single integer or floating-point value that specifies
7128 the equation to be used to compute the fog blend factor, @r{@var{f}}.
7129 Three symbolic constants are accepted: @code{GL_LINEAR}, @code{GL_EXP},
7130 and @code{GL_EXP2}. The equations corresponding to these symbolic
7131 constants are defined below. The initial fog mode is @code{GL_EXP}.
7133 @item @code{GL_FOG_DENSITY}
7134 @var{params} is a single integer or floating-point value that specifies
7135 @r{@var{density}}, the fog density used in both exponential fog
7136 equations. Only nonnegative densities are accepted. The initial fog
7139 @item @code{GL_FOG_START}
7140 @var{params} is a single integer or floating-point value that specifies
7141 @r{@var{start}}, the near distance used in the linear fog equation. The
7142 initial near distance is 0.
7144 @item @code{GL_FOG_END}
7145 @var{params} is a single integer or floating-point value that specifies
7146 @r{@var{end}}, the far distance used in the linear fog equation. The
7147 initial far distance is 1.
7149 @item @code{GL_FOG_INDEX}
7150 @var{params} is a single integer or floating-point value that specifies
7151 @r{@var{i}_@var{f}}, the fog color index. The initial fog index is 0.
7153 @item @code{GL_FOG_COLOR}
7154 @var{params} contains four integer or floating-point values that specify
7155 @r{@var{C}_@var{f}}, the fog color. Integer values are mapped linearly
7156 such that the most positive representable value maps to 1.0, and the
7157 most negative representable value maps to @r{-1.0}. Floating-point
7158 values are mapped directly. After conversion, all color components are
7159 clamped to the range @r{[0,1]}. The initial fog color is (0, 0, 0, 0).
7161 @item @code{GL_FOG_COORD_SRC}
7162 @var{params} contains either of the following symbolic constants:
7163 @code{GL_FOG_COORD} or @code{GL_FRAGMENT_DEPTH}. @code{GL_FOG_COORD}
7164 specifies that the current fog coordinate should be used as distance
7165 value in the fog color computation. @code{GL_FRAGMENT_DEPTH} specifies
7166 that the current fragment depth should be used as distance value in the
7171 Fog blends a fog color with each rasterized pixel fragment's
7172 post-texturing color using a blending factor @r{@var{f}}. Factor
7173 @r{@var{f}} is computed in one of three ways, depending on the fog mode.
7174 Let @r{@var{c}} be either the distance in eye coordinate from the origin
7175 (in the case that the @code{GL_FOG_COORD_SRC} is
7176 @code{GL_FRAGMENT_DEPTH}) or the current fog coordinate (in the case
7177 that @code{GL_FOG_COORD_SRC} is @code{GL_FOG_COORD}). The equation for
7178 @code{GL_LINEAR} fog is
7179 @r{@var{f}=@var{end}-@var{c},/@var{end}-@var{start},}
7181 The equation for @code{GL_EXP} fog is
7182 @r{@var{f}=@var{e}^-(@var{density}·@var{c},),}
7184 The equation for @code{GL_EXP2} fog is
7185 @r{@var{f}=@var{e}^-(@var{density}·@var{c},),^2}
7187 Regardless of the fog mode, @r{@var{f}} is clamped to the range
7188 @r{[0,1]} after it is computed. Then, if the GL is in RGBA color mode,
7189 the fragment's red, green, and blue colors, represented by
7190 @r{@var{C}_@var{r}}, are replaced by
7192 @r{@var{C}_@var{r},^″=@var{f}×@var{C}_@var{r}+(1-@var{f},)×@var{C}_@var{f}}
7194 Fog does not affect a fragment's alpha component.
7196 In color index mode, the fragment's color index @r{@var{i}_@var{r}} is
7199 @r{@var{i}_@var{r},^″=@var{i}_@var{r}+(1-@var{f},)×@var{i}_@var{f}}
7203 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
7204 value, or if @var{pname} is @code{GL_FOG_MODE} and @var{params} is not
7207 @code{GL_INVALID_VALUE} is generated if @var{pname} is
7208 @code{GL_FOG_DENSITY} and @var{params} is negative.
7210 @code{GL_INVALID_OPERATION} is generated if @code{glFog} is executed
7211 between the execution of @code{glBegin} and the corresponding execution
7216 @deftypefun void glFrontFace mode
7217 Define front- and back-facing polygons.
7221 Specifies the orientation of front-facing polygons. @code{GL_CW} and
7222 @code{GL_CCW} are accepted. The initial value is @code{GL_CCW}.
7226 In a scene composed entirely of opaque closed surfaces, back-facing
7227 polygons are never visible. Eliminating these invisible polygons has the
7228 obvious benefit of speeding up the rendering of the image. To enable and
7229 disable elimination of back-facing polygons, call @code{glEnable} and
7230 @code{glDisable} with argument @code{GL_CULL_FACE}.
7232 The projection of a polygon to window coordinates is said to have
7233 clockwise winding if an imaginary object following the path from its
7234 first vertex, its second vertex, and so on, to its last vertex, and
7235 finally back to its first vertex, moves in a clockwise direction about
7236 the interior of the polygon. The polygon's winding is said to be
7237 counterclockwise if the imaginary object following the same path moves
7238 in a counterclockwise direction about the interior of the polygon.
7239 @code{glFrontFace} specifies whether polygons with clockwise winding in
7240 window coordinates, or counterclockwise winding in window coordinates,
7241 are taken to be front-facing. Passing @code{GL_CCW} to @var{mode}
7242 selects counterclockwise polygons as front-facing; @code{GL_CW} selects
7243 clockwise polygons as front-facing. By default, counterclockwise
7244 polygons are taken to be front-facing.
7246 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
7249 @code{GL_INVALID_OPERATION} is generated if @code{glFrontFace} is
7250 executed between the execution of @code{glBegin} and the corresponding
7251 execution of @code{glEnd}.
7255 @deftypefun void glFrustum left right bottom top nearVal farVal
7256 Multiply the current matrix by a perspective matrix.
7261 Specify the coordinates for the left and right vertical clipping planes.
7265 Specify the coordinates for the bottom and top horizontal clipping
7270 Specify the distances to the near and far depth clipping planes. Both
7271 distances must be positive.
7275 @code{glFrustum} describes a perspective matrix that produces a
7276 perspective projection. The current matrix (see @code{glMatrixMode}) is
7277 multiplied by this matrix and the result replaces the current matrix, as
7278 if @code{glMultMatrix} were called with the following matrix as its
7283 @r{[(2@var{nearVal},/@var{right}-@var{left},, 0 @var{A} 0), (0
7284 2@var{nearVal},/@var{top}-@var{bottom},, @var{B} 0), (0 0 @var{C}
7285 @var{D}), (0 0 -1 0),]}
7287 @r{@var{A}=@var{right}+@var{left},/@var{right}-@var{left},}
7289 @r{@var{B}=@var{top}+@var{bottom},/@var{top}-@var{bottom},}
7291 @r{@var{C}=-@var{farVal}+@var{nearVal},/@var{farVal}-@var{nearVal},,}
7293 @r{@var{D}=-2@var{farVal}@var{nearVal},/@var{farVal}-@var{nearVal},,}
7297 Typically, the matrix mode is @code{GL_PROJECTION}, and
7298 @r{(@var{left},@var{bottom}-@var{nearVal})} and
7299 @r{(@var{right},@var{top}-@var{nearVal})} specify the points on the near
7300 clipping plane that are mapped to the lower left and upper right corners
7301 of the window, assuming that the eye is located at (0, 0, 0).
7302 @r{-@var{farVal}} specifies the location of the far clipping plane. Both
7303 @var{nearVal} and @var{farVal} must be positive.
7305 Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the
7306 current matrix stack.
7308 @code{GL_INVALID_VALUE} is generated if @var{nearVal} or @var{farVal} is
7309 not positive, or if @var{left} = @var{right}, or @var{bottom} =
7310 @var{top}, or @var{near} = @var{far}.
7312 @code{GL_INVALID_OPERATION} is generated if @code{glFrustum} is executed
7313 between the execution of @code{glBegin} and the corresponding execution
7318 @deftypefun void glGenBuffers n buffers
7319 Generate buffer object names.
7323 Specifies the number of buffer object names to be generated.
7326 Specifies an array in which the generated buffer object names are
7331 @code{glGenBuffers} returns @var{n} buffer object names in
7332 @var{buffers}. There is no guarantee that the names form a contiguous
7333 set of integers; however, it is guaranteed that none of the returned
7334 names was in use immediately before the call to @code{glGenBuffers}.
7336 Buffer object names returned by a call to @code{glGenBuffers} are not
7337 returned by subsequent calls, unless they are first deleted with
7338 @code{glDeleteBuffers}.
7340 No buffer objects are associated with the returned buffer object names
7341 until they are first bound by calling @code{glBindBuffer}.
7343 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
7345 @code{GL_INVALID_OPERATION} is generated if @code{glGenBuffers} is
7346 executed between the execution of @code{glBegin} and the corresponding
7347 execution of @code{glEnd}.
7351 @deftypefun GLuint glGenLists range
7352 Generate a contiguous set of empty display lists.
7356 Specifies the number of contiguous empty display lists to be generated.
7360 @code{glGenLists} has one argument, @var{range}. It returns an integer
7361 @var{n} such that @var{range} contiguous empty display lists, named
7362 @r{@var{n}}, @r{@var{n}+1}, @r{@var{...}}, @r{@var{n}+@var{range}-1},
7363 are created. If @var{range} is 0, if there is no group of @var{range}
7364 contiguous names available, or if any error is generated, no display
7365 lists are generated, and 0 is returned.
7367 @code{GL_INVALID_VALUE} is generated if @var{range} is negative.
7369 @code{GL_INVALID_OPERATION} is generated if @code{glGenLists} is
7370 executed between the execution of @code{glBegin} and the corresponding
7371 execution of @code{glEnd}.
7375 @deftypefun void glGenQueries n ids
7376 Generate query object names.
7380 Specifies the number of query object names to be generated.
7383 Specifies an array in which the generated query object names are stored.
7387 @code{glGenQueries} returns @var{n} query object names in @var{ids}.
7388 There is no guarantee that the names form a contiguous set of integers;
7389 however, it is guaranteed that none of the returned names was in use
7390 immediately before the call to @code{glGenQueries}.
7392 Query object names returned by a call to @code{glGenQueries} are not
7393 returned by subsequent calls, unless they are first deleted with
7394 @code{glDeleteQueries}.
7396 No query objects are associated with the returned query object names
7397 until they are first used by calling @code{glBeginQuery}.
7399 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
7401 @code{GL_INVALID_OPERATION} is generated if @code{glGenQueries} is
7402 executed between the execution of @code{glBegin} and the corresponding
7403 execution of @code{glEnd}.
7407 @deftypefun void glGenTextures n textures
7408 Generate texture names.
7412 Specifies the number of texture names to be generated.
7414 @item @var{textures}
7415 Specifies an array in which the generated texture names are stored.
7419 @code{glGenTextures} returns @var{n} texture names in @var{textures}.
7420 There is no guarantee that the names form a contiguous set of integers;
7421 however, it is guaranteed that none of the returned names was in use
7422 immediately before the call to @code{glGenTextures}.
7424 The generated textures have no dimensionality; they assume the
7425 dimensionality of the texture target to which they are first bound (see
7426 @code{glBindTexture}).
7428 Texture names returned by a call to @code{glGenTextures} are not
7429 returned by subsequent calls, unless they are first deleted with
7430 @code{glDeleteTextures}.
7432 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
7434 @code{GL_INVALID_OPERATION} is generated if @code{glGenTextures} is
7435 executed between the execution of @code{glBegin} and the corresponding
7436 execution of @code{glEnd}.
7440 @deftypefun void glGetActiveAttrib program index bufSize length size type name
7441 Returns information about an active attribute variable for the specified
7446 Specifies the program object to be queried.
7449 Specifies the index of the attribute variable to be queried.
7452 Specifies the maximum number of characters OpenGL is allowed to write in
7453 the character buffer indicated by @var{name}.
7456 Returns the number of characters actually written by OpenGL in the
7457 string indicated by @var{name} (excluding the null terminator) if a
7458 value other than @code{NULL} is passed.
7461 Returns the size of the attribute variable.
7464 Returns the data type of the attribute variable.
7467 Returns a null terminated string containing the name of the attribute
7472 @code{glGetActiveAttrib} returns information about an active attribute
7473 variable in the program object specified by @var{program}. The number of
7474 active attributes can be obtained by calling @code{glGetProgram} with
7475 the value @code{GL_ACTIVE_ATTRIBUTES}. A value of 0 for @var{index}
7476 selects the first active attribute variable. Permissible values for
7477 @var{index} range from 0 to the number of active attribute variables
7480 A vertex shader may use either built-in attribute variables,
7481 user-defined attribute variables, or both. Built-in attribute variables
7482 have a prefix of "gl_" and reference conventional OpenGL vertex
7483 attribtes (e.g., @var{gl_Vertex}, @var{gl_Normal}, etc., see the OpenGL
7484 Shading Language specification for a complete list.) User-defined
7485 attribute variables have arbitrary names and obtain their values through
7486 numbered generic vertex attributes. An attribute variable (either
7487 built-in or user-defined) is considered active if it is determined
7488 during the link operation that it may be accessed during program
7489 execution. Therefore, @var{program} should have previously been the
7490 target of a call to @code{glLinkProgram}, but it is not necessary for it
7491 to have been linked successfully.
7493 The size of the character buffer required to store the longest attribute
7494 variable name in @var{program} can be obtained by calling
7495 @code{glGetProgram} with the value
7496 @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH}. This value should be used to
7497 allocate a buffer of sufficient size to store the returned attribute
7498 name. The size of this character buffer is passed in @var{bufSize}, and
7499 a pointer to this character buffer is passed in @var{name}.
7501 @code{glGetActiveAttrib} returns the name of the attribute variable
7502 indicated by @var{index}, storing it in the character buffer specified
7503 by @var{name}. The string returned will be null terminated. The actual
7504 number of characters written into this buffer is returned in
7505 @var{length}, and this count does not include the null termination
7506 character. If the length of the returned string is not required, a value
7507 of @code{NULL} can be passed in the @var{length} argument.
7509 The @var{type} argument will return a pointer to the attribute
7510 variable's data type. The symbolic constants @code{GL_FLOAT},
7511 @code{GL_FLOAT_VEC2}, @code{GL_FLOAT_VEC3}, @code{GL_FLOAT_VEC4},
7512 @code{GL_FLOAT_MAT2}, @code{GL_FLOAT_MAT3}, @code{GL_FLOAT_MAT4},
7513 @code{GL_FLOAT_MAT2x3}, @code{GL_FLOAT_MAT2x4}, @code{GL_FLOAT_MAT3x2},
7514 @code{GL_FLOAT_MAT3x4}, @code{GL_FLOAT_MAT4x2}, or
7515 @code{GL_FLOAT_MAT4x3} may be returned. The @var{size} argument will
7516 return the size of the attribute, in units of the type returned in
7519 The list of active attribute variables may include both built-in
7520 attribute variables (which begin with the prefix "gl_") as well as
7521 user-defined attribute variable names.
7523 This function will return as much information as it can about the
7524 specified active attribute variable. If no information is available,
7525 @var{length} will be 0, and @var{name} will be an empty string. This
7526 situation could occur if this function is called after a link operation
7527 that failed. If an error occurs, the return values @var{length},
7528 @var{size}, @var{type}, and @var{name} will be unmodified.
7530 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
7531 generated by OpenGL.
7533 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
7536 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
7537 equal to the number of active attribute variables in @var{program}.
7539 @code{GL_INVALID_OPERATION} is generated if @code{glGetActiveAttrib} is
7540 executed between the execution of @code{glBegin} and the corresponding
7541 execution of @code{glEnd}.
7543 @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0.
7547 @deftypefun void glGetActiveUniform program index bufSize length size type name
7548 Returns information about an active uniform variable for the specified
7553 Specifies the program object to be queried.
7556 Specifies the index of the uniform variable to be queried.
7559 Specifies the maximum number of characters OpenGL is allowed to write in
7560 the character buffer indicated by @var{name}.
7563 Returns the number of characters actually written by OpenGL in the
7564 string indicated by @var{name} (excluding the null terminator) if a
7565 value other than @code{NULL} is passed.
7568 Returns the size of the uniform variable.
7571 Returns the data type of the uniform variable.
7574 Returns a null terminated string containing the name of the uniform
7579 @code{glGetActiveUniform} returns information about an active uniform
7580 variable in the program object specified by @var{program}. The number of
7581 active uniform variables can be obtained by calling @code{glGetProgram}
7582 with the value @code{GL_ACTIVE_UNIFORMS}. A value of 0 for @var{index}
7583 selects the first active uniform variable. Permissible values for
7584 @var{index} range from 0 to the number of active uniform variables minus
7587 Shaders may use either built-in uniform variables, user-defined uniform
7588 variables, or both. Built-in uniform variables have a prefix of "gl_"
7589 and reference existing OpenGL state or values derived from such state
7590 (e.g., @var{gl_Fog}, @var{gl_ModelViewMatrix}, etc., see the OpenGL
7591 Shading Language specification for a complete list.) User-defined
7592 uniform variables have arbitrary names and obtain their values from the
7593 application through calls to @code{glUniform}. A uniform variable
7594 (either built-in or user-defined) is considered active if it is
7595 determined during the link operation that it may be accessed during
7596 program execution. Therefore, @var{program} should have previously been
7597 the target of a call to @code{glLinkProgram}, but it is not necessary
7598 for it to have been linked successfully.
7600 The size of the character buffer required to store the longest uniform
7601 variable name in @var{program} can be obtained by calling
7602 @code{glGetProgram} with the value @code{GL_ACTIVE_UNIFORM_MAX_LENGTH}.
7603 This value should be used to allocate a buffer of sufficient size to
7604 store the returned uniform variable name. The size of this character
7605 buffer is passed in @var{bufSize}, and a pointer to this character
7606 buffer is passed in @var{name.}
7608 @code{glGetActiveUniform} returns the name of the uniform variable
7609 indicated by @var{index}, storing it in the character buffer specified
7610 by @var{name}. The string returned will be null terminated. The actual
7611 number of characters written into this buffer is returned in
7612 @var{length}, and this count does not include the null termination
7613 character. If the length of the returned string is not required, a value
7614 of @code{NULL} can be passed in the @var{length} argument.
7616 The @var{type} argument will return a pointer to the uniform variable's
7617 data type. The symbolic constants @code{GL_FLOAT}, @code{GL_FLOAT_VEC2},
7618 @code{GL_FLOAT_VEC3}, @code{GL_FLOAT_VEC4}, @code{GL_INT},
7619 @code{GL_INT_VEC2}, @code{GL_INT_VEC3}, @code{GL_INT_VEC4},
7620 @code{GL_BOOL}, @code{GL_BOOL_VEC2}, @code{GL_BOOL_VEC3},
7621 @code{GL_BOOL_VEC4}, @code{GL_FLOAT_MAT2}, @code{GL_FLOAT_MAT3},
7622 @code{GL_FLOAT_MAT4}, @code{GL_FLOAT_MAT2x3}, @code{GL_FLOAT_MAT2x4},
7623 @code{GL_FLOAT_MAT3x2}, @code{GL_FLOAT_MAT3x4}, @code{GL_FLOAT_MAT4x2},
7624 @code{GL_FLOAT_MAT4x3}, @code{GL_SAMPLER_1D}, @code{GL_SAMPLER_2D},
7625 @code{GL_SAMPLER_3D}, @code{GL_SAMPLER_CUBE},
7626 @code{GL_SAMPLER_1D_SHADOW}, or @code{GL_SAMPLER_2D_SHADOW} may be
7629 If one or more elements of an array are active, the name of the array is
7630 returned in @var{name}, the type is returned in @var{type}, and the
7631 @var{size} parameter returns the highest array element index used, plus
7632 one, as determined by the compiler and/or linker. Only one active
7633 uniform variable will be reported for a uniform array.
7635 Uniform variables that are declared as structures or arrays of
7636 structures will not be returned directly by this function. Instead, each
7637 of these uniform variables will be reduced to its fundamental components
7638 containing the "." and "[]" operators such that each of the names is
7639 valid as an argument to @code{glGetUniformLocation}. Each of these
7640 reduced uniform variables is counted as one active uniform variable and
7641 is assigned an index. A valid name cannot be a structure, an array of
7642 structures, or a subcomponent of a vector or matrix.
7644 The size of the uniform variable will be returned in @var{size}. Uniform
7645 variables other than arrays will have a size of 1. Structures and arrays
7646 of structures will be reduced as described earlier, such that each of
7647 the names returned will be a data type in the earlier list. If this
7648 reduction results in an array, the size returned will be as described
7649 for uniform arrays; otherwise, the size returned will be 1.
7651 The list of active uniform variables may include both built-in uniform
7652 variables (which begin with the prefix "gl_") as well as user-defined
7653 uniform variable names.
7655 This function will return as much information as it can about the
7656 specified active uniform variable. If no information is available,
7657 @var{length} will be 0, and @var{name} will be an empty string. This
7658 situation could occur if this function is called after a link operation
7659 that failed. If an error occurs, the return values @var{length},
7660 @var{size}, @var{type}, and @var{name} will be unmodified.
7662 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
7663 generated by OpenGL.
7665 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
7668 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
7669 equal to the number of active uniform variables in @var{program}.
7671 @code{GL_INVALID_OPERATION} is generated if @code{glGetActiveUniform} is
7672 executed between the execution of @code{glBegin} and the corresponding
7673 execution of @code{glEnd}.
7675 @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0.
7679 @deftypefun void glGetAttachedShaders program maxCount count shaders
7680 Returns the handles of the shader objects attached to a program object.
7684 Specifies the program object to be queried.
7686 @item @var{maxCount}
7687 Specifies the size of the array for storing the returned object names.
7690 Returns the number of names actually returned in @var{objects}.
7693 Specifies an array that is used to return the names of attached shader
7698 @code{glGetAttachedShaders} returns the names of the shader objects
7699 attached to @var{program}. The names of shader objects that are attached
7700 to @var{program} will be returned in @var{shaders.} The actual number of
7701 shader names written into @var{shaders} is returned in @var{count.} If
7702 no shader objects are attached to @var{program}, @var{count} is set to
7703 0. The maximum number of shader names that may be returned in
7704 @var{shaders} is specified by @var{maxCount}.
7706 If the number of names actually returned is not required (for instance,
7707 if it has just been obtained by calling @code{glGetProgram}), a value of
7708 @code{NULL} may be passed for count. If no shader objects are attached
7709 to @var{program}, a value of 0 will be returned in @var{count}. The
7710 actual number of attached shaders can be obtained by calling
7711 @code{glGetProgram} with the value @code{GL_ATTACHED_SHADERS}.
7713 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
7714 generated by OpenGL.
7716 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
7719 @code{GL_INVALID_VALUE} is generated if @var{maxCount} is less than 0.
7721 @code{GL_INVALID_OPERATION} is generated if @code{glGetAttachedShaders}
7722 is executed between the execution of @code{glBegin} and the
7723 corresponding execution of @code{glEnd}.
7727 @deftypefun GLint glGetAttribLocation program name
7728 Returns the location of an attribute variable.
7732 Specifies the program object to be queried.
7735 Points to a null terminated string containing the name of the attribute
7736 variable whose location is to be queried.
7740 @code{glGetAttribLocation} queries the previously linked program object
7741 specified by @var{program} for the attribute variable specified by
7742 @var{name} and returns the index of the generic vertex attribute that is
7743 bound to that attribute variable. If @var{name} is a matrix attribute
7744 variable, the index of the first column of the matrix is returned. If
7745 the named attribute variable is not an active attribute in the specified
7746 program object or if @var{name} starts with the reserved prefix "gl_", a
7747 value of -1 is returned.
7749 The association between an attribute variable name and a generic
7750 attribute index can be specified at any time by calling
7751 @code{glBindAttribLocation}. Attribute bindings do not go into effect
7752 until @code{glLinkProgram} is called. After a program object has been
7753 linked successfully, the index values for attribute variables remain
7754 fixed until the next link command occurs. The attribute values can only
7755 be queried after a link if the link was successful.
7756 @code{glGetAttribLocation} returns the binding that actually went into
7757 effect the last time @code{glLinkProgram} was called for the specified
7758 program object. Attribute bindings that have been specified since the
7759 last link operation are not returned by @code{glGetAttribLocation}.
7761 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a value
7762 generated by OpenGL.
7764 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
7767 @code{GL_INVALID_OPERATION} is generated if @var{program} has not been
7768 successfully linked.
7770 @code{GL_INVALID_OPERATION} is generated if @code{glGetAttribLocation}
7771 is executed between the execution of @code{glBegin} and the
7772 corresponding execution of @code{glEnd}.
7776 @deftypefun void glGetBufferParameteriv target value data
7777 Return parameters of a buffer object.
7781 Specifies the target buffer object. The symbolic constant must be
7782 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
7783 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
7786 Specifies the symbolic name of a buffer object parameter. Accepted
7787 values are @code{GL_BUFFER_ACCESS}, @code{GL_BUFFER_MAPPED},
7788 @code{GL_BUFFER_SIZE}, or @code{GL_BUFFER_USAGE}.
7791 Returns the requested parameter.
7795 @code{glGetBufferParameteriv} returns in @var{data} a selected parameter
7796 of the buffer object specified by @var{target}.
7798 @var{value} names a specific buffer object parameter, as follows:
7801 @item @code{GL_BUFFER_ACCESS}
7802 @var{params} returns the access policy set while mapping the buffer
7803 object. The initial value is @code{GL_READ_WRITE}.
7805 @item @code{GL_BUFFER_MAPPED}
7806 @var{params} returns a flag indicating whether the buffer object is
7807 currently mapped. The initial value is @code{GL_FALSE}.
7809 @item @code{GL_BUFFER_SIZE}
7810 @var{params} returns the size of the buffer object, measured in bytes.
7811 The initial value is 0.
7813 @item @code{GL_BUFFER_USAGE}
7814 @var{params} returns the buffer object's usage pattern. The initial
7815 value is @code{GL_STATIC_DRAW}.
7819 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{value} is
7820 not an accepted value.
7822 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
7823 name 0 is bound to @var{target}.
7825 @code{GL_INVALID_OPERATION} is generated if
7826 @code{glGetBufferParameteriv} is executed between the execution of
7827 @code{glBegin} and the corresponding execution of @code{glEnd}.
7831 @deftypefun void glGetBufferPointerv target pname params
7832 Return the pointer to a mapped buffer object's data store.
7836 Specifies the target buffer object. The symbolic constant must be
7837 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
7838 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
7841 Specifies the pointer to be returned. The symbolic constant must be
7842 @code{GL_BUFFER_MAP_POINTER}.
7845 Returns the pointer value specified by @var{pname}.
7849 @code{glGetBufferPointerv} returns pointer information. @var{pname} is a
7850 symbolic constant indicating the pointer to be returned, which must be
7851 @code{GL_BUFFER_MAP_POINTER}, the pointer to which the buffer object's
7852 data store is mapped. If the data store is not currently mapped,
7853 @code{NULL} is returned. @var{params} is a pointer to a location in
7854 which to place the returned pointer value.
7856 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
7857 not an accepted value.
7859 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
7860 name 0 is bound to @var{target}.
7862 @code{GL_INVALID_OPERATION} is generated if @code{glGetBufferPointerv}
7863 is executed between the execution of @code{glBegin} and the
7864 corresponding execution of @code{glEnd}.
7868 @deftypefun void glGetBufferSubData target offset size data
7869 Returns a subset of a buffer object's data store.
7873 Specifies the target buffer object. The symbolic constant must be
7874 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
7875 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
7878 Specifies the offset into the buffer object's data store from which data
7879 will be returned, measured in bytes.
7882 Specifies the size in bytes of the data store region being returned.
7885 Specifies a pointer to the location where buffer object data is
7890 @code{glGetBufferSubData} returns some or all of the data from the
7891 buffer object currently bound to @var{target}. Data starting at byte
7892 offset @var{offset} and extending for @var{size} bytes is copied from
7893 the data store to the memory pointed to by @var{data}. An error is
7894 thrown if the buffer object is currently mapped, or if @var{offset} and
7895 @var{size} together define a range beyond the bounds of the buffer
7896 object's data store.
7898 @code{GL_INVALID_ENUM} is generated if @var{target} is not
7899 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
7900 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
7902 @code{GL_INVALID_VALUE} is generated if @var{offset} or @var{size} is
7903 negative, or if together they define a region of memory that extends
7904 beyond the buffer object's allocated data store.
7906 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
7907 name 0 is bound to @var{target}.
7909 @code{GL_INVALID_OPERATION} is generated if the buffer object being
7912 @code{GL_INVALID_OPERATION} is generated if @code{glGetBufferSubData} is
7913 executed between the execution of @code{glBegin} and the corresponding
7914 execution of @code{glEnd}.
7918 @deftypefun void glGetClipPlane plane equation
7919 Return the coefficients of the specified clipping plane.
7923 Specifies a clipping plane. The number of clipping planes depends on the
7924 implementation, but at least six clipping planes are supported. They are
7925 identified by symbolic names of the form @code{GL_CLIP_PLANE}@r{@var{i}}
7926 where i ranges from 0 to the value of @code{GL_MAX_CLIP_PLANES} - 1.
7928 @item @var{equation}
7929 Returns four double-precision values that are the coefficients of the
7930 plane equation of @var{plane} in eye coordinates. The initial value is
7935 @code{glGetClipPlane} returns in @var{equation} the four coefficients of
7936 the plane equation for @var{plane}.
7938 @code{GL_INVALID_ENUM} is generated if @var{plane} is not an accepted
7941 @code{GL_INVALID_OPERATION} is generated if @code{glGetClipPlane} is
7942 executed between the execution of @code{glBegin} and the corresponding
7943 execution of @code{glEnd}.
7947 @deftypefun void glGetColorTableParameterfv target pname params
7948 @deftypefunx void glGetColorTableParameteriv target pname params
7949 Get color lookup table parameters.
7953 The target color table. Must be @code{GL_COLOR_TABLE},
7954 @code{GL_POST_CONVOLUTION_COLOR_TABLE},
7955 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{GL_PROXY_COLOR_TABLE},
7956 @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or
7957 @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}.
7960 The symbolic name of a color lookup table parameter. Must be one of
7961 @code{GL_COLOR_TABLE_BIAS}, @code{GL_COLOR_TABLE_SCALE},
7962 @code{GL_COLOR_TABLE_FORMAT}, @code{GL_COLOR_TABLE_WIDTH},
7963 @code{GL_COLOR_TABLE_RED_SIZE}, @code{GL_COLOR_TABLE_GREEN_SIZE},
7964 @code{GL_COLOR_TABLE_BLUE_SIZE}, @code{GL_COLOR_TABLE_ALPHA_SIZE},
7965 @code{GL_COLOR_TABLE_LUMINANCE_SIZE}, or
7966 @code{GL_COLOR_TABLE_INTENSITY_SIZE}.
7969 A pointer to an array where the values of the parameter will be stored.
7973 Returns parameters specific to color table @var{target}.
7975 When @var{pname} is set to @code{GL_COLOR_TABLE_SCALE} or
7976 @code{GL_COLOR_TABLE_BIAS}, @code{glGetColorTableParameter} returns the
7977 color table scale or bias parameters for the table specified by
7978 @var{target}. For these queries, @var{target} must be set to
7979 @code{GL_COLOR_TABLE}, @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
7980 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} and @var{params} points to an
7981 array of four elements, which receive the scale or bias factors for red,
7982 green, blue, and alpha, in that order.
7984 @code{glGetColorTableParameter} can also be used to retrieve the format
7985 and size parameters for a color table. For these queries, set
7986 @var{target} to either the color table target or the proxy color table
7987 target. The format and size parameters are set by @code{glColorTable}.
7989 The following table lists the format and size parameters that may be
7990 queried. For each symbolic constant listed below for @var{pname},
7991 @var{params} must point to an array of the given length and receive the
7997 @item @strong{Parameter}
7998 @strong{N}, @strong{Meaning}
8000 @item @code{GL_COLOR_TABLE_FORMAT}
8001 1 , Internal format (e.g., @code{GL_RGBA})
8003 @item @code{GL_COLOR_TABLE_WIDTH}
8004 1 , Number of elements in table
8006 @item @code{GL_COLOR_TABLE_RED_SIZE}
8007 1 , Size of red component, in bits
8009 @item @code{GL_COLOR_TABLE_GREEN_SIZE}
8010 1 , Size of green component
8012 @item @code{GL_COLOR_TABLE_BLUE_SIZE}
8013 1 , Size of blue component
8015 @item @code{GL_COLOR_TABLE_ALPHA_SIZE}
8016 1 , Size of alpha component
8018 @item @code{GL_COLOR_TABLE_LUMINANCE_SIZE}
8019 1 , Size of luminance component
8021 @item @code{GL_COLOR_TABLE_INTENSITY_SIZE}
8022 1 , Size of intensity component
8028 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
8029 not an acceptable value.
8031 @code{GL_INVALID_OPERATION} is generated if
8032 @code{glGetColorTableParameter} is executed between the execution of
8033 @code{glBegin} and the corresponding execution of @code{glEnd}.
8037 @deftypefun void glGetColorTable target format type table
8038 Retrieve contents of a color lookup table.
8042 Must be @code{GL_COLOR_TABLE}, @code{GL_POST_CONVOLUTION_COLOR_TABLE},
8043 or @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}.
8046 The format of the pixel data in @var{table}. The possible values are
8047 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
8048 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB},
8049 @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}.
8052 The type of the pixel data in @var{table}. Symbolic constants
8053 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
8054 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
8055 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
8056 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
8057 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
8058 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
8059 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
8060 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
8061 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
8064 Pointer to a one-dimensional array of pixel data containing the contents
8069 @code{glGetColorTable} returns in @var{table} the contents of the color
8070 table specified by @var{target}. No pixel transfer operations are
8071 performed, but pixel storage modes that are applicable to
8072 @code{glReadPixels} are performed.
8074 If a non-zero named buffer object is bound to the
8075 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
8076 histogram table is requested, @var{table} is treated as a byte offset
8077 into the buffer object's data store.
8079 Color components that are requested in the specified @var{format}, but
8080 which are not included in the internal format of the color lookup table,
8081 are returned as zero. The assignments of internal color components to
8082 the components requested by @var{format} are
8085 @item @strong{Internal Component}
8086 @strong{Resulting Component}
8116 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
8119 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
8122 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
8125 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8126 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
8127 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
8128 and @var{format} is not @code{GL_RGB}.
8130 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8131 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
8132 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
8133 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
8134 @code{GL_UNSIGNED_INT_10_10_10_2}, or
8135 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
8136 @code{GL_RGBA} nor @code{GL_BGRA}.
8138 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8139 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
8140 object's data store is currently mapped.
8142 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8143 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
8144 would be packed to the buffer object such that the memory writes
8145 required would exceed the data store size.
8147 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8148 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{table}
8149 is not evenly divisible into the number of bytes needed to store in
8150 memory a datum indicated by @var{type}.
8152 @code{GL_INVALID_OPERATION} is generated if @code{glGetColorTable} is
8153 executed between the execution of @code{glBegin} and the corresponding
8154 execution of @code{glEnd}.
8158 @deftypefun void glGetCompressedTexImage target lod img
8159 Return a compressed texture image.
8163 Specifies which texture is to be obtained. @code{GL_TEXTURE_1D},
8164 @code{GL_TEXTURE_2D}, and
8165 @code{GL_TEXTURE_3D}@code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
8166 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
8167 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
8168 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
8169 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, and
8170 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z} are accepted.
8173 Specifies the level-of-detail number of the desired image. Level 0 is
8174 the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap
8178 Returns the compressed texture image.
8182 @code{glGetCompressedTexImage} returns the compressed texture image
8183 associated with @var{target} and @var{lod} into @var{img}. @var{img}
8184 should be an array of @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} bytes.
8185 @var{target} specifies whether the desired texture image was one
8186 specified by @code{glTexImage1D} (@code{GL_TEXTURE_1D}),
8187 @code{glTexImage2D} (@code{GL_TEXTURE_2D} or any of
8188 @code{GL_TEXTURE_CUBE_MAP_*}), or @code{glTexImage3D}
8189 (@code{GL_TEXTURE_3D}). @var{lod} specifies the level-of-detail number
8190 of the desired image.
8192 If a non-zero named buffer object is bound to the
8193 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
8194 texture image is requested, @var{img} is treated as a byte offset into
8195 the buffer object's data store.
8197 To minimize errors, first verify that the texture is compressed by
8198 calling @code{glGetTexLevelParameter} with argument
8199 @code{GL_TEXTURE_COMPRESSED}. If the texture is compressed, then
8200 determine the amount of memory required to store the compressed texture
8201 by calling @code{glGetTexLevelParameter} with argument
8202 @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE}. Finally, retrieve the internal
8203 format of the texture by calling @code{glGetTexLevelParameter} with
8204 argument @code{GL_TEXTURE_INTERNAL_FORMAT}. To store the texture for
8205 later use, associate the internal format and size with the retrieved
8206 texture image. These data can be used by the respective texture or
8207 subtexture loading routine used for loading @var{target} textures.
8209 @code{GL_INVALID_VALUE} is generated if @var{lod} is less than zero or
8210 greater than the maximum number of LODs permitted by the implementation.
8212 @code{GL_INVALID_OPERATION} is generated if
8213 @code{glGetCompressedTexImage} is used to retrieve a texture that is in
8214 an uncompressed internal format.
8216 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8217 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
8218 object's data store is currently mapped.
8220 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8221 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
8222 would be packed to the buffer object such that the memory writes
8223 required would exceed the data store size.
8225 @code{GL_INVALID_OPERATION} is generated if
8226 @code{glGetCompressedTexImage} is executed between the execution of
8227 @code{glBegin} and the corresponding execution of @code{glEnd}.
8231 @deftypefun void glGetConvolutionFilter target format type image
8232 Get current 1D or 2D convolution filter kernel.
8236 The filter to be retrieved. Must be one of @code{GL_CONVOLUTION_1D} or
8237 @code{GL_CONVOLUTION_2D}.
8240 Format of the output image. Must be one of @code{GL_RED},
8241 @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB},
8242 @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, or
8243 @code{GL_LUMINANCE_ALPHA}.
8246 Data type of components in the output image. Symbolic constants
8247 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
8248 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
8249 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
8250 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
8251 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
8252 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
8253 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
8254 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
8255 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
8258 Pointer to storage for the output image.
8262 @code{glGetConvolutionFilter} returns the current 1D or 2D convolution
8263 filter kernel as an image. The one- or two-dimensional image is placed
8264 in @var{image} according to the specifications in @var{format} and
8265 @var{type}. No pixel transfer operations are performed on this image,
8266 but the relevant pixel storage modes are applied.
8268 If a non-zero named buffer object is bound to the
8269 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
8270 convolution filter is requested, @var{image} is treated as a byte offset
8271 into the buffer object's data store.
8273 Color components that are present in @var{format} but not included in
8274 the internal format of the filter are returned as zero. The assignments
8275 of internal color components to the components of @var{format} are as
8279 @item @strong{Internal Component}
8280 @strong{Resulting Component}
8310 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
8313 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
8316 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
8319 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8320 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
8321 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
8322 and @var{format} is not @code{GL_RGB}.
8324 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8325 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
8326 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
8327 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
8328 @code{GL_UNSIGNED_INT_10_10_10_2}, or
8329 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
8330 @code{GL_RGBA} nor @code{GL_BGRA}.
8332 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8333 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
8334 object's data store is currently mapped.
8336 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8337 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
8338 would be packed to the buffer object such that the memory writes
8339 required would exceed the data store size.
8341 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8342 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{image}
8343 is not evenly divisible into the number of bytes needed to store in
8344 memory a datum indicated by @var{type}.
8346 @code{GL_INVALID_OPERATION} is generated if
8347 @code{glGetConvolutionFilter} is executed between the execution of
8348 @code{glBegin} and the corresponding execution of @code{glEnd}.
8352 @deftypefun void glGetConvolutionParameterfv target pname params
8353 @deftypefunx void glGetConvolutionParameteriv target pname params
8354 Get convolution parameters.
8358 The filter whose parameters are to be retrieved. Must be one of
8359 @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or
8360 @code{GL_SEPARABLE_2D}.
8363 The parameter to be retrieved. Must be one of
8364 @code{GL_CONVOLUTION_BORDER_MODE}, @code{GL_CONVOLUTION_BORDER_COLOR},
8365 @code{GL_CONVOLUTION_FILTER_SCALE}, @code{GL_CONVOLUTION_FILTER_BIAS},
8366 @code{GL_CONVOLUTION_FORMAT}, @code{GL_CONVOLUTION_WIDTH},
8367 @code{GL_CONVOLUTION_HEIGHT}, @code{GL_MAX_CONVOLUTION_WIDTH}, or
8368 @code{GL_MAX_CONVOLUTION_HEIGHT}.
8371 Pointer to storage for the parameters to be retrieved.
8375 @code{glGetConvolutionParameter} retrieves convolution parameters.
8376 @var{target} determines which convolution filter is queried. @var{pname}
8377 determines which parameter is returned:
8380 @item @code{GL_CONVOLUTION_BORDER_MODE}
8383 The convolution border mode. See @code{glConvolutionParameter} for a
8384 list of border modes.
8386 @item @code{GL_CONVOLUTION_BORDER_COLOR}
8389 The current convolution border color. @var{params} must be a pointer to
8390 an array of four elements, which will receive the red, green, blue, and
8391 alpha border colors.
8393 @item @code{GL_CONVOLUTION_FILTER_SCALE}
8396 The current filter scale factors. @var{params} must be a pointer to an
8397 array of four elements, which will receive the red, green, blue, and
8398 alpha filter scale factors in that order.
8400 @item @code{GL_CONVOLUTION_FILTER_BIAS}
8403 The current filter bias factors. @var{params} must be a pointer to an
8404 array of four elements, which will receive the red, green, blue, and
8405 alpha filter bias terms in that order.
8407 @item @code{GL_CONVOLUTION_FORMAT}
8410 The current internal format. See @code{glConvolutionFilter1D},
8411 @code{glConvolutionFilter2D}, and @code{glSeparableFilter2D} for lists
8412 of allowable formats.
8414 @item @code{GL_CONVOLUTION_WIDTH}
8417 The current filter image width.
8419 @item @code{GL_CONVOLUTION_HEIGHT}
8422 The current filter image height.
8424 @item @code{GL_MAX_CONVOLUTION_WIDTH}
8427 The maximum acceptable filter image width.
8429 @item @code{GL_MAX_CONVOLUTION_HEIGHT}
8432 The maximum acceptable filter image height.
8436 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
8439 @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the
8442 @code{GL_INVALID_ENUM} is generated if @var{target} is
8443 @code{GL_CONVOLUTION_1D} and @var{pname} is @code{GL_CONVOLUTION_HEIGHT}
8444 or @code{GL_MAX_CONVOLUTION_HEIGHT}.
8446 @code{GL_INVALID_OPERATION} is generated if
8447 @code{glGetConvolutionParameter} is executed between the execution of
8448 @code{glBegin} and the corresponding execution of @code{glEnd}.
8452 @deftypefun GLenum glGetError
8453 Return error information.
8455 @code{glGetError} returns the value of the error flag. Each detectable
8456 error is assigned a numeric code and symbolic name. When an error
8457 occurs, the error flag is set to the appropriate error code value. No
8458 other errors are recorded until @code{glGetError} is called, the error
8459 code is returned, and the flag is reset to @code{GL_NO_ERROR}. If a call
8460 to @code{glGetError} returns @code{GL_NO_ERROR}, there has been no
8461 detectable error since the last call to @code{glGetError}, or since the
8464 To allow for distributed implementations, there may be several error
8465 flags. If any single error flag has recorded an error, the value of that
8466 flag is returned and that flag is reset to @code{GL_NO_ERROR} when
8467 @code{glGetError} is called. If more than one flag has recorded an
8468 error, @code{glGetError} returns and clears an arbitrary error flag
8469 value. Thus, @code{glGetError} should always be called in a loop, until
8470 it returns @code{GL_NO_ERROR}, if all error flags are to be reset.
8472 Initially, all error flags are set to @code{GL_NO_ERROR}.
8474 The following errors are currently defined:
8477 @item @code{GL_NO_ERROR}
8478 No error has been recorded. The value of this symbolic constant is
8481 @item @code{GL_INVALID_ENUM}
8482 An unacceptable value is specified for an enumerated argument. The
8483 offending command is ignored and has no other side effect than to set
8486 @item @code{GL_INVALID_VALUE}
8487 A numeric argument is out of range. The offending command is ignored and
8488 has no other side effect than to set the error flag.
8490 @item @code{GL_INVALID_OPERATION}
8491 The specified operation is not allowed in the current state. The
8492 offending command is ignored and has no other side effect than to set
8495 @item @code{GL_STACK_OVERFLOW}
8496 This command would cause a stack overflow. The offending command is
8497 ignored and has no other side effect than to set the error flag.
8499 @item @code{GL_STACK_UNDERFLOW}
8500 This command would cause a stack underflow. The offending command is
8501 ignored and has no other side effect than to set the error flag.
8503 @item @code{GL_OUT_OF_MEMORY}
8504 There is not enough memory left to execute the command. The state of the
8505 GL is undefined, except for the state of the error flags, after this
8508 @item @code{GL_TABLE_TOO_LARGE}
8509 The specified table exceeds the implementation's maximum supported table
8510 size. The offending command is ignored and has no other side effect than
8511 to set the error flag.
8515 When an error flag is set, results of a GL operation are undefined only
8516 if @code{GL_OUT_OF_MEMORY} has occurred. In all other cases, the command
8517 generating the error is ignored and has no effect on the GL state or
8518 frame buffer contents. If the generating command returns a value, it
8519 returns 0. If @code{glGetError} itself generates an error, it returns 0.
8521 @code{GL_INVALID_OPERATION} is generated if @code{glGetError} is
8522 executed between the execution of @code{glBegin} and the corresponding
8523 execution of @code{glEnd}. In this case, @code{glGetError} returns 0.
8527 @deftypefun void glGetHistogramParameterfv target pname params
8528 @deftypefunx void glGetHistogramParameteriv target pname params
8529 Get histogram parameters.
8533 Must be one of @code{GL_HISTOGRAM} or @code{GL_PROXY_HISTOGRAM}.
8536 The name of the parameter to be retrieved. Must be one of
8537 @code{GL_HISTOGRAM_WIDTH}, @code{GL_HISTOGRAM_FORMAT},
8538 @code{GL_HISTOGRAM_RED_SIZE}, @code{GL_HISTOGRAM_GREEN_SIZE},
8539 @code{GL_HISTOGRAM_BLUE_SIZE}, @code{GL_HISTOGRAM_ALPHA_SIZE},
8540 @code{GL_HISTOGRAM_LUMINANCE_SIZE}, or @code{GL_HISTOGRAM_SINK}.
8543 Pointer to storage for the returned values.
8547 @code{glGetHistogramParameter} is used to query parameter values for the
8548 current histogram or for a proxy. The histogram state information may be
8549 queried by calling @code{glGetHistogramParameter} with a @var{target} of
8550 @code{GL_HISTOGRAM} (to obtain information for the current histogram
8551 table) or @code{GL_PROXY_HISTOGRAM} (to obtain information from the most
8552 recent proxy request) and one of the following values for the
8553 @var{pname} argument:
8558 @item @strong{Parameter}
8559 @strong{Description}
8561 @item @code{GL_HISTOGRAM_WIDTH}
8562 Histogram table width
8564 @item @code{GL_HISTOGRAM_FORMAT}
8567 @item @code{GL_HISTOGRAM_RED_SIZE}
8568 Red component counter size, in bits
8570 @item @code{GL_HISTOGRAM_GREEN_SIZE}
8571 Green component counter size, in bits
8573 @item @code{GL_HISTOGRAM_BLUE_SIZE}
8574 Blue component counter size, in bits
8576 @item @code{GL_HISTOGRAM_ALPHA_SIZE}
8577 Alpha component counter size, in bits
8579 @item @code{GL_HISTOGRAM_LUMINANCE_SIZE}
8580 Luminance component counter size, in bits
8582 @item @code{GL_HISTOGRAM_SINK}
8583 Value of the @var{sink} parameter
8589 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
8592 @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the
8595 @code{GL_INVALID_OPERATION} is generated if
8596 @code{glGetHistogramParameter} is executed between the execution of
8597 @code{glBegin} and the corresponding execution of @code{glEnd}.
8601 @deftypefun void glGetHistogram target reset format type values
8602 Get histogram table.
8606 Must be @code{GL_HISTOGRAM}.
8609 If @code{GL_TRUE}, each component counter that is actually returned is
8610 reset to zero. (Other counters are unaffected.) If @code{GL_FALSE}, none
8611 of the counters in the histogram table is modified.
8614 The format of values to be returned in @var{values}. Must be one of
8615 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
8616 @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA},
8617 @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}.
8620 The type of values to be returned in @var{values}. Symbolic constants
8621 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
8622 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
8623 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
8624 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
8625 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
8626 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
8627 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
8628 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
8629 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
8632 A pointer to storage for the returned histogram table.
8636 @code{glGetHistogram} returns the current histogram table as a
8637 one-dimensional image with the same width as the histogram. No pixel
8638 transfer operations are performed on this image, but pixel storage modes
8639 that are applicable to 1D images are honored.
8641 If a non-zero named buffer object is bound to the
8642 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
8643 histogram table is requested, @var{values} is treated as a byte offset
8644 into the buffer object's data store.
8646 Color components that are requested in the specified @var{format}, but
8647 which are not included in the internal format of the histogram, are
8648 returned as zero. The assignments of internal color components to the
8649 components requested by @var{format} are:
8652 @item @strong{Internal Component}
8653 @strong{Resulting Component}
8679 @code{GL_INVALID_ENUM} is generated if @var{target} is not
8680 @code{GL_HISTOGRAM}.
8682 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
8685 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
8688 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8689 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
8690 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
8691 and @var{format} is not @code{GL_RGB}.
8693 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8694 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
8695 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
8696 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
8697 @code{GL_UNSIGNED_INT_10_10_10_2}, or
8698 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
8699 @code{GL_RGBA} nor @code{GL_BGRA}.
8701 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8702 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
8703 object's data store is currently mapped.
8705 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8706 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
8707 would be packed to the buffer object such that the memory writes
8708 required would exceed the data store size.
8710 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8711 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{values}
8712 is not evenly divisible into the number of bytes needed to store in
8713 memory a datum indicated by @var{type}.
8715 @code{GL_INVALID_OPERATION} is generated if @code{glGetHistogram} is
8716 executed between the execution of @code{glBegin} and the corresponding
8717 execution of @code{glEnd}.
8721 @deftypefun void glGetLightfv light pname params
8722 @deftypefunx void glGetLightiv light pname params
8723 Return light source parameter values.
8727 Specifies a light source. The number of possible lights depends on the
8728 implementation, but at least eight lights are supported. They are
8729 identified by symbolic names of the form @code{GL_LIGHT}@r{@var{i}}
8730 where @r{@var{i}} ranges from 0 to the value of @code{GL_MAX_LIGHTS} -
8734 Specifies a light source parameter for @var{light}. Accepted symbolic
8735 names are @code{GL_AMBIENT}, @code{GL_DIFFUSE}, @code{GL_SPECULAR},
8736 @code{GL_POSITION}, @code{GL_SPOT_DIRECTION}, @code{GL_SPOT_EXPONENT},
8737 @code{GL_SPOT_CUTOFF}, @code{GL_CONSTANT_ATTENUATION},
8738 @code{GL_LINEAR_ATTENUATION}, and @code{GL_QUADRATIC_ATTENUATION}.
8741 Returns the requested data.
8745 @code{glGetLight} returns in @var{params} the value or values of a light
8746 source parameter. @var{light} names the light and is a symbolic name of
8747 the form @code{GL_LIGHT}@r{@var{i}} where i ranges from 0 to the value
8748 of @code{GL_MAX_LIGHTS} - 1. @code{GL_MAX_LIGHTS} is an implementation
8749 dependent constant that is greater than or equal to eight. @var{pname}
8750 specifies one of ten light source parameters, again by symbolic name.
8752 The following parameters are defined:
8755 @item @code{GL_AMBIENT}
8756 @var{params} returns four integer or floating-point values representing
8757 the ambient intensity of the light source. Integer values, when
8758 requested, are linearly mapped from the internal floating-point
8759 representation such that 1.0 maps to the most positive representable
8760 integer value, and @r{-1.0} maps to the most negative representable
8761 integer value. If the internal value is outside the range @r{[-1,1]},
8762 the corresponding integer return value is undefined. The initial value
8765 @item @code{GL_DIFFUSE}
8766 @var{params} returns four integer or floating-point values representing
8767 the diffuse intensity of the light source. Integer values, when
8768 requested, are linearly mapped from the internal floating-point
8769 representation such that 1.0 maps to the most positive representable
8770 integer value, and @r{-1.0} maps to the most negative representable
8771 integer value. If the internal value is outside the range @r{[-1,1]},
8772 the corresponding integer return value is undefined. The initial value
8773 for @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial
8774 value is (0, 0, 0, 0).
8776 @item @code{GL_SPECULAR}
8777 @var{params} returns four integer or floating-point values representing
8778 the specular intensity of the light source. Integer values, when
8779 requested, are linearly mapped from the internal floating-point
8780 representation such that 1.0 maps to the most positive representable
8781 integer value, and @r{-1.0} maps to the most negative representable
8782 integer value. If the internal value is outside the range @r{[-1,1]},
8783 the corresponding integer return value is undefined. The initial value
8784 for @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial
8785 value is (0, 0, 0, 0).
8787 @item @code{GL_POSITION}
8788 @var{params} returns four integer or floating-point values representing
8789 the position of the light source. Integer values, when requested, are
8790 computed by rounding the internal floating-point values to the nearest
8791 integer value. The returned values are those maintained in eye
8792 coordinates. They will not be equal to the values specified using
8793 @code{glLight}, unless the modelview matrix was identity at the time
8794 @code{glLight} was called. The initial value is (0, 0, 1, 0).
8796 @item @code{GL_SPOT_DIRECTION}
8797 @var{params} returns three integer or floating-point values representing
8798 the direction of the light source. Integer values, when requested, are
8799 computed by rounding the internal floating-point values to the nearest
8800 integer value. The returned values are those maintained in eye
8801 coordinates. They will not be equal to the values specified using
8802 @code{glLight}, unless the modelview matrix was identity at the time
8803 @code{glLight} was called. Although spot direction is normalized before
8804 being used in the lighting equation, the returned values are the
8805 transformed versions of the specified values prior to normalization. The
8806 initial value is @r{(0,0-1)}.
8808 @item @code{GL_SPOT_EXPONENT}
8809 @var{params} returns a single integer or floating-point value
8810 representing the spot exponent of the light. An integer value, when
8811 requested, is computed by rounding the internal floating-point
8812 representation to the nearest integer. The initial value is 0.
8814 @item @code{GL_SPOT_CUTOFF}
8815 @var{params} returns a single integer or floating-point value
8816 representing the spot cutoff angle of the light. An integer value, when
8817 requested, is computed by rounding the internal floating-point
8818 representation to the nearest integer. The initial value is 180.
8820 @item @code{GL_CONSTANT_ATTENUATION}
8821 @var{params} returns a single integer or floating-point value
8822 representing the constant (not distance-related) attenuation of the
8823 light. An integer value, when requested, is computed by rounding the
8824 internal floating-point representation to the nearest integer. The
8827 @item @code{GL_LINEAR_ATTENUATION}
8828 @var{params} returns a single integer or floating-point value
8829 representing the linear attenuation of the light. An integer value, when
8830 requested, is computed by rounding the internal floating-point
8831 representation to the nearest integer. The initial value is 0.
8833 @item @code{GL_QUADRATIC_ATTENUATION}
8834 @var{params} returns a single integer or floating-point value
8835 representing the quadratic attenuation of the light. An integer value,
8836 when requested, is computed by rounding the internal floating-point
8837 representation to the nearest integer. The initial value is 0.
8841 @code{GL_INVALID_ENUM} is generated if @var{light} or @var{pname} is not
8844 @code{GL_INVALID_OPERATION} is generated if @code{glGetLight} is
8845 executed between the execution of @code{glBegin} and the corresponding
8846 execution of @code{glEnd}.
8850 @deftypefun void glGetMapfv target query v
8851 @deftypefunx void glGetMapiv target query v
8852 Return evaluator parameters.
8856 Specifies the symbolic name of a map. Accepted values are
8857 @code{GL_MAP1_COLOR_4}, @code{GL_MAP1_INDEX}, @code{GL_MAP1_NORMAL},
8858 @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2},
8859 @code{GL_MAP1_TEXTURE_COORD_3}, @code{GL_MAP1_TEXTURE_COORD_4},
8860 @code{GL_MAP1_VERTEX_3}, @code{GL_MAP1_VERTEX_4},
8861 @code{GL_MAP2_COLOR_4}, @code{GL_MAP2_INDEX}, @code{GL_MAP2_NORMAL},
8862 @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2},
8863 @code{GL_MAP2_TEXTURE_COORD_3}, @code{GL_MAP2_TEXTURE_COORD_4},
8864 @code{GL_MAP2_VERTEX_3}, and @code{GL_MAP2_VERTEX_4}.
8867 Specifies which parameter to return. Symbolic names @code{GL_COEFF},
8868 @code{GL_ORDER}, and @code{GL_DOMAIN} are accepted.
8871 Returns the requested data.
8875 @code{glMap1} and @code{glMap2} define evaluators. @code{glGetMap}
8876 returns evaluator parameters. @var{target} chooses a map, @var{query}
8877 selects a specific parameter, and @var{v} points to storage where the
8878 values will be returned.
8880 The acceptable values for the @var{target} parameter are described in
8881 the @code{glMap1} and @code{glMap2} reference pages.
8883 @var{query} can assume the following values:
8886 @item @code{GL_COEFF}
8887 @var{v} returns the control points for the evaluator function.
8888 One-dimensional evaluators return @r{@var{order}} control points, and
8889 two-dimensional evaluators return @r{@var{uorder}×@var{vorder}} control
8890 points. Each control point consists of one, two, three, or four integer,
8891 single-precision floating-point, or double-precision floating-point
8892 values, depending on the type of the evaluator. The GL returns
8893 two-dimensional control points in row-major order, incrementing the
8894 @r{@var{uorder}} index quickly and the @r{@var{vorder}} index after each
8895 row. Integer values, when requested, are computed by rounding the
8896 internal floating-point values to the nearest integer values.
8898 @item @code{GL_ORDER}
8899 @var{v} returns the order of the evaluator function. One-dimensional
8900 evaluators return a single value, @r{@var{order}}. The initial value is
8901 1. Two-dimensional evaluators return two values, @r{@var{uorder}} and
8902 @r{@var{vorder}}. The initial value is 1,1.
8904 @item @code{GL_DOMAIN}
8905 @var{v} returns the linear @r{@var{u}} and @r{@var{v}} mapping
8906 parameters. One-dimensional evaluators return two values, @r{@var{u1}}
8907 and @r{@var{u2}}, as specified by @code{glMap1}. Two-dimensional
8908 evaluators return four values (@r{@var{u1}}, @r{@var{u2}}, @r{@var{v1}},
8909 and @r{@var{v2}}) as specified by @code{glMap2}. Integer values, when
8910 requested, are computed by rounding the internal floating-point values
8911 to the nearest integer values.
8915 @code{GL_INVALID_ENUM} is generated if either @var{target} or
8916 @var{query} is not an accepted value.
8918 @code{GL_INVALID_OPERATION} is generated if @code{glGetMap} is executed
8919 between the execution of @code{glBegin} and the corresponding execution
8924 @deftypefun void glGetMaterialfv face pname params
8925 @deftypefunx void glGetMaterialiv face pname params
8926 Return material parameters.
8930 Specifies which of the two materials is being queried. @code{GL_FRONT}
8931 or @code{GL_BACK} are accepted, representing the front and back
8932 materials, respectively.
8935 Specifies the material parameter to return. @code{GL_AMBIENT},
8936 @code{GL_DIFFUSE}, @code{GL_SPECULAR}, @code{GL_EMISSION},
8937 @code{GL_SHININESS}, and @code{GL_COLOR_INDEXES} are accepted.
8940 Returns the requested data.
8944 @code{glGetMaterial} returns in @var{params} the value or values of
8945 parameter @var{pname} of material @var{face}. Six parameters are
8949 @item @code{GL_AMBIENT}
8950 @var{params} returns four integer or floating-point values representing
8951 the ambient reflectance of the material. Integer values, when requested,
8952 are linearly mapped from the internal floating-point representation such
8953 that 1.0 maps to the most positive representable integer value, and
8954 @r{-1.0} maps to the most negative representable integer value. If the
8955 internal value is outside the range @r{[-1,1]}, the corresponding
8956 integer return value is undefined. The initial value is (0.2, 0.2, 0.2,
8959 @item @code{GL_DIFFUSE}
8960 @var{params} returns four integer or floating-point values representing
8961 the diffuse reflectance of the material. Integer values, when requested,
8962 are linearly mapped from the internal floating-point representation such
8963 that 1.0 maps to the most positive representable integer value, and
8964 @r{-1.0} maps to the most negative representable integer value. If the
8965 internal value is outside the range @r{[-1,1]}, the corresponding
8966 integer return value is undefined. The initial value is (0.8, 0.8, 0.8,
8969 @item @code{GL_SPECULAR}
8970 @var{params} returns four integer or floating-point values representing
8971 the specular reflectance of the material. Integer values, when
8972 requested, are linearly mapped from the internal floating-point
8973 representation such that 1.0 maps to the most positive representable
8974 integer value, and @r{-1.0} maps to the most negative representable
8975 integer value. If the internal value is outside the range @r{[-1,1]},
8976 the corresponding integer return value is undefined. The initial value
8979 @item @code{GL_EMISSION}
8980 @var{params} returns four integer or floating-point values representing
8981 the emitted light intensity of the material. Integer values, when
8982 requested, are linearly mapped from the internal floating-point
8983 representation such that 1.0 maps to the most positive representable
8984 integer value, and @r{-1.0} maps to the most negative representable
8985 integer value. If the internal value is outside the range @r{[-1,1]},
8986 the corresponding integer return value is undefined. The initial value
8989 @item @code{GL_SHININESS}
8990 @var{params} returns one integer or floating-point value representing
8991 the specular exponent of the material. Integer values, when requested,
8992 are computed by rounding the internal floating-point value to the
8993 nearest integer value. The initial value is 0.
8995 @item @code{GL_COLOR_INDEXES}
8996 @var{params} returns three integer or floating-point values representing
8997 the ambient, diffuse, and specular indices of the material. These
8998 indices are used only for color index lighting. (All the other
8999 parameters are used only for RGBA lighting.) Integer values, when
9000 requested, are computed by rounding the internal floating-point values
9001 to the nearest integer values.
9005 @code{GL_INVALID_ENUM} is generated if @var{face} or @var{pname} is not
9008 @code{GL_INVALID_OPERATION} is generated if @code{glGetMaterial} is
9009 executed between the execution of @code{glBegin} and the corresponding
9010 execution of @code{glEnd}.
9014 @deftypefun void glGetMinmaxParameterfv target pname params
9015 @deftypefunx void glGetMinmaxParameteriv target pname params
9016 Get minmax parameters.
9020 Must be @code{GL_MINMAX}.
9023 The parameter to be retrieved. Must be one of @code{GL_MINMAX_FORMAT} or
9024 @code{GL_MINMAX_SINK}.
9027 A pointer to storage for the retrieved parameters.
9031 @code{glGetMinmaxParameter} retrieves parameters for the current minmax
9032 table by setting @var{pname} to one of the following values:
9037 @item @strong{Parameter}
9038 @strong{Description}
9040 @item @code{GL_MINMAX_FORMAT}
9041 Internal format of minmax table
9043 @item @code{GL_MINMAX_SINK}
9044 Value of the @var{sink} parameter
9050 @code{GL_INVALID_ENUM} is generated if @var{target} is not
9053 @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the
9056 @code{GL_INVALID_OPERATION} is generated if @code{glGetMinmaxParameter}
9057 is executed between the execution of @code{glBegin} and the
9058 corresponding execution of @code{glEnd}.
9062 @deftypefun void glGetMinmax target reset format types values
9063 Get minimum and maximum pixel values.
9067 Must be @code{GL_MINMAX}.
9070 If @code{GL_TRUE}, all entries in the minmax table that are actually
9071 returned are reset to their initial values. (Other entries are
9072 unaltered.) If @code{GL_FALSE}, the minmax table is unaltered.
9075 The format of the data to be returned in @var{values}. Must be one of
9076 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
9077 @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA},
9078 @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}.
9081 The type of the data to be returned in @var{values}. Symbolic constants
9082 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
9083 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
9084 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
9085 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
9086 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
9087 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
9088 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
9089 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
9090 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
9093 A pointer to storage for the returned values.
9097 @code{glGetMinmax} returns the accumulated minimum and maximum pixel
9098 values (computed on a per-component basis) in a one-dimensional image of
9099 width 2. The first set of return values are the minima, and the second
9100 set of return values are the maxima. The format of the return values is
9101 determined by @var{format}, and their type is determined by @var{types}.
9103 If a non-zero named buffer object is bound to the
9104 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while
9105 minimum and maximum pixel values are requested, @var{values} is treated
9106 as a byte offset into the buffer object's data store.
9108 No pixel transfer operations are performed on the return values, but
9109 pixel storage modes that are applicable to one-dimensional images are
9110 performed. Color components that are requested in the specified
9111 @var{format}, but that are not included in the internal format of the
9112 minmax table, are returned as zero. The assignment of internal color
9113 components to the components requested by @var{format} are as follows:
9118 @item @strong{Internal Component}
9119 @strong{Resulting Component}
9143 If @var{reset} is @code{GL_TRUE}, the minmax table entries corresponding
9144 to the return values are reset to their initial values. Minimum and
9145 maximum values that are not returned are not modified, even if
9146 @var{reset} is @code{GL_TRUE}.
9148 @code{GL_INVALID_ENUM} is generated if @var{target} is not
9151 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
9154 @code{GL_INVALID_ENUM} is generated if @var{types} is not one of the
9157 @code{GL_INVALID_OPERATION} is generated if @var{types} is one of
9158 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
9159 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
9160 and @var{format} is not @code{GL_RGB}.
9162 @code{GL_INVALID_OPERATION} is generated if @var{types} is one of
9163 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
9164 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
9165 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
9166 @code{GL_UNSIGNED_INT_10_10_10_2}, or
9167 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
9168 @code{GL_RGBA} nor @code{GL_BGRA}.
9170 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9171 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
9172 object's data store is currently mapped.
9174 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9175 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
9176 would be packed to the buffer object such that the memory writes
9177 required would exceed the data store size.
9179 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9180 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{values}
9181 is not evenly divisible into the number of bytes needed to store in
9182 memory a datum indicated by @var{type}.
9184 @code{GL_INVALID_OPERATION} is generated if @code{glGetMinmax} is
9185 executed between the execution of @code{glBegin} and the corresponding
9186 execution of @code{glEnd}.
9190 @deftypefun void glGetPixelMapfv map data
9191 @deftypefunx void glGetPixelMapuiv map data
9192 Return the specified pixel map.
9196 Specifies the name of the pixel map to return. Accepted values are
9197 @code{GL_PIXEL_MAP_I_TO_I}, @code{GL_PIXEL_MAP_S_TO_S},
9198 @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G},
9199 @code{GL_PIXEL_MAP_I_TO_B}, @code{GL_PIXEL_MAP_I_TO_A},
9200 @code{GL_PIXEL_MAP_R_TO_R}, @code{GL_PIXEL_MAP_G_TO_G},
9201 @code{GL_PIXEL_MAP_B_TO_B}, and @code{GL_PIXEL_MAP_A_TO_A}.
9204 Returns the pixel map contents.
9208 See the @code{glPixelMap} reference page for a description of the
9209 acceptable values for the @var{map} parameter. @code{glGetPixelMap}
9210 returns in @var{data} the contents of the pixel map specified in
9211 @var{map}. Pixel maps are used during the execution of
9212 @code{glReadPixels}, @code{glDrawPixels}, @code{glCopyPixels},
9213 @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D},
9214 @code{glTexSubImage1D}, @code{glTexSubImage2D}, @code{glTexSubImage3D},
9215 @code{glCopyTexImage1D}, @code{glCopyTexImage2D},
9216 @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D}, and
9217 @code{glCopyTexSubImage3D}. to map color indices, stencil indices, color
9218 components, and depth components to other values.
9220 If a non-zero named buffer object is bound to the
9221 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
9222 pixel map is requested, @var{data} is treated as a byte offset into the
9223 buffer object's data store.
9225 Unsigned integer values, if requested, are linearly mapped from the
9226 internal fixed or floating-point representation such that 1.0 maps to
9227 the largest representable integer value, and 0.0 maps to 0. Return
9228 unsigned integer values are undefined if the map value was not in the
9231 To determine the required size of @var{map}, call @code{glGet} with the
9232 appropriate symbolic constant.
9234 @code{GL_INVALID_ENUM} is generated if @var{map} is not an accepted
9237 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9238 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
9239 object's data store is currently mapped.
9241 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9242 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
9243 would be packed to the buffer object such that the memory writes
9244 required would exceed the data store size.
9246 @code{GL_INVALID_OPERATION} is generated by @code{glGetPixelMapfv} if a
9247 non-zero buffer object name is bound to the @code{GL_PIXEL_PACK_BUFFER}
9248 target and @var{data} is not evenly divisible into the number of bytes
9249 needed to store in memory a GLfloat datum.
9251 @code{GL_INVALID_OPERATION} is generated by @code{glGetPixelMapuiv} if a
9252 non-zero buffer object name is bound to the @code{GL_PIXEL_PACK_BUFFER}
9253 target and @var{data} is not evenly divisible into the number of bytes
9254 needed to store in memory a GLuint datum.
9256 @code{GL_INVALID_OPERATION} is generated by @code{glGetPixelMapusv} if a
9257 non-zero buffer object name is bound to the @code{GL_PIXEL_PACK_BUFFER}
9258 target and @var{data} is not evenly divisible into the number of bytes
9259 needed to store in memory a GLushort datum.
9261 @code{GL_INVALID_OPERATION} is generated if @code{glGetPixelMap} is
9262 executed between the execution of @code{glBegin} and the corresponding
9263 execution of @code{glEnd}.
9267 @deftypefun void glGetPointerv pname params
9268 Return the address of the specified pointer.
9272 Specifies the array or buffer pointer to be returned. Symbolic constants
9273 @code{GL_COLOR_ARRAY_POINTER}, @code{GL_EDGE_FLAG_ARRAY_POINTER},
9274 @code{GL_FOG_COORD_ARRAY_POINTER}, @code{GL_FEEDBACK_BUFFER_POINTER},
9275 @code{GL_INDEX_ARRAY_POINTER}, @code{GL_NORMAL_ARRAY_POINTER},
9276 @code{GL_SECONDARY_COLOR_ARRAY_POINTER},
9277 @code{GL_SELECTION_BUFFER_POINTER},
9278 @code{GL_TEXTURE_COORD_ARRAY_POINTER}, or @code{GL_VERTEX_ARRAY_POINTER}
9282 Returns the pointer value specified by @var{pname}.
9286 @code{glGetPointerv} returns pointer information. @var{pname} is a
9287 symbolic constant indicating the pointer to be returned, and
9288 @var{params} is a pointer to a location in which to place the returned
9291 For all @var{pname} arguments except @code{GL_FEEDBACK_BUFFER_POINTER}
9292 and @code{GL_SELECTION_BUFFER_POINTER}, if a non-zero named buffer
9293 object was bound to the @code{GL_ARRAY_BUFFER} target (see
9294 @code{glBindBuffer}) when the desired pointer was previously specified,
9295 the pointer returned is a byte offset into the buffer object's data
9296 store. Buffer objects are only available in OpenGL versions 1.5 and
9299 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
9304 @deftypefun void glGetPolygonStipple pattern
9305 Return the polygon stipple pattern.
9309 Returns the stipple pattern. The initial value is all 1's.
9313 @code{glGetPolygonStipple} returns to @var{pattern} a @r{32×32} polygon
9314 stipple pattern. The pattern is packed into memory as if
9315 @code{glReadPixels} with both @var{height} and @var{width} of 32,
9316 @var{type} of @code{GL_BITMAP}, and @var{format} of
9317 @code{GL_COLOR_INDEX} were called, and the stipple pattern were stored
9318 in an internal @r{32×32} color index buffer. Unlike @code{glReadPixels},
9319 however, pixel transfer operations (shift, offset, pixel map) are not
9320 applied to the returned stipple image.
9322 If a non-zero named buffer object is bound to the
9323 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
9324 polygon stipple pattern is requested, @var{pattern} is treated as a byte
9325 offset into the buffer object's data store.
9327 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9328 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
9329 object's data store is currently mapped.
9331 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9332 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
9333 would be packed to the buffer object such that the memory writes
9334 required would exceed the data store size.
9336 @code{GL_INVALID_OPERATION} is generated if @code{glGetPolygonStipple}
9337 is executed between the execution of @code{glBegin} and the
9338 corresponding execution of @code{glEnd}.
9342 @deftypefun void glGetProgramInfoLog program maxLength length infoLog
9343 Returns the information log for a program object.
9347 Specifies the program object whose information log is to be queried.
9349 @item @var{maxLength}
9350 Specifies the size of the character buffer for storing the returned
9354 Returns the length of the string returned in @var{infoLog} (excluding
9355 the null terminator).
9358 Specifies an array of characters that is used to return the information
9363 @code{glGetProgramInfoLog} returns the information log for the specified
9364 program object. The information log for a program object is modified
9365 when the program object is linked or validated. The string that is
9366 returned will be null terminated.
9368 @code{glGetProgramInfoLog} returns in @var{infoLog} as much of the
9369 information log as it can, up to a maximum of @var{maxLength}
9370 characters. The number of characters actually returned, excluding the
9371 null termination character, is specified by @var{length}. If the length
9372 of the returned string is not required, a value of @code{NULL} can be
9373 passed in the @var{length} argument. The size of the buffer required to
9374 store the returned information log can be obtained by calling
9375 @code{glGetProgram} with the value @code{GL_INFO_LOG_LENGTH}.
9377 The information log for a program object is either an empty string, or a
9378 string containing information about the last link operation, or a string
9379 containing information about the last validation operation. It may
9380 contain diagnostic messages, warning messages, and other information.
9381 When a program object is created, its information log will be a string
9384 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
9385 generated by OpenGL.
9387 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
9390 @code{GL_INVALID_VALUE} is generated if @var{maxLength} is less than 0.
9392 @code{GL_INVALID_OPERATION} is generated if @code{glGetProgramInfoLog}
9393 is executed between the execution of @code{glBegin} and the
9394 corresponding execution of @code{glEnd}.
9398 @deftypefun void glGetProgramiv program pname params
9399 Returns a parameter from a program object.
9403 Specifies the program object to be queried.
9406 Specifies the object parameter. Accepted symbolic names are
9407 @code{GL_DELETE_STATUS}, @code{GL_LINK_STATUS},
9408 @code{GL_VALIDATE_STATUS}, @code{GL_INFO_LOG_LENGTH},
9409 @code{GL_ATTACHED_SHADERS}, @code{GL_ACTIVE_ATTRIBUTES},
9410 @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH}, @code{GL_ACTIVE_UNIFORMS},
9411 @code{GL_ACTIVE_UNIFORM_MAX_LENGTH}.
9414 Returns the requested object parameter.
9418 @code{glGetProgram} returns in @var{params} the value of a parameter for
9419 a specific program object. The following parameters are defined:
9422 @item @code{GL_DELETE_STATUS}
9425 @var{params} returns @code{GL_TRUE} if @var{program} is currently
9426 flagged for deletion, and @code{GL_FALSE} otherwise.
9428 @item @code{GL_LINK_STATUS}
9431 @var{params} returns @code{GL_TRUE} if the last link operation on
9432 @var{program} was successful, and @code{GL_FALSE} otherwise.
9434 @item @code{GL_VALIDATE_STATUS}
9437 @var{params} returns @code{GL_TRUE} or if the last validation operation
9438 on @var{program} was successful, and @code{GL_FALSE} otherwise.
9440 @item @code{GL_INFO_LOG_LENGTH}
9443 @var{params} returns the number of characters in the information log for
9444 @var{program} including the null termination character (i.e., the size
9445 of the character buffer required to store the information log). If
9446 @var{program} has no information log, a value of 0 is returned.
9448 @item @code{GL_ATTACHED_SHADERS}
9451 @var{params} returns the number of shader objects attached to
9454 @item @code{GL_ACTIVE_ATTRIBUTES}
9457 @var{params} returns the number of active attribute variables for
9460 @item @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH}
9463 @var{params} returns the length of the longest active attribute name for
9464 @var{program}, including the null termination character (i.e., the size
9465 of the character buffer required to store the longest attribute name).
9466 If no active attributes exist, 0 is returned.
9468 @item @code{GL_ACTIVE_UNIFORMS}
9471 @var{params} returns the number of active uniform variables for
9474 @item @code{GL_ACTIVE_UNIFORM_MAX_LENGTH}
9477 @var{params} returns the length of the longest active uniform variable
9478 name for @var{program}, including the null termination character (i.e.,
9479 the size of the character buffer required to store the longest uniform
9480 variable name). If no active uniform variables exist, 0 is returned.
9484 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
9485 generated by OpenGL.
9487 @code{GL_INVALID_OPERATION} is generated if @var{program} does not refer
9488 to a program object.
9490 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
9493 @code{GL_INVALID_OPERATION} is generated if @code{glGetProgram} is
9494 executed between the execution of @code{glBegin} and the corresponding
9495 execution of @code{glEnd}.
9499 @deftypefun void glGetQueryiv target pname params
9500 Return parameters of a query object target.
9504 Specifies a query object target. Must be @code{GL_SAMPLES_PASSED}.
9507 Specifies the symbolic name of a query object target parameter. Accepted
9508 values are @code{GL_CURRENT_QUERY} or @code{GL_QUERY_COUNTER_BITS}.
9511 Returns the requested data.
9515 @code{glGetQueryiv} returns in @var{params} a selected parameter of the
9516 query object target specified by @var{target}.
9518 @var{pname} names a specific query object target parameter. When
9519 @var{target} is @code{GL_SAMPLES_PASSED}, @var{pname} can be as follows:
9522 @item @code{GL_CURRENT_QUERY}
9523 @var{params} returns the name of the currently active occlusion query
9524 object. If no occlusion query is active, 0 is returned. The initial
9527 @item @code{GL_QUERY_COUNTER_BITS}
9528 @var{params} returns the number of bits in the query counter used to
9529 accumulate passing samples. If the number of bits returned is 0, the
9530 implementation does not support a query counter, and the results
9531 obtained from @code{glGetQueryObject} are useless.
9535 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
9536 not an accepted value.
9538 @code{GL_INVALID_OPERATION} is generated if @code{glGetQueryiv} is
9539 executed between the execution of @code{glBegin} and the corresponding
9540 execution of @code{glEnd}.
9544 @deftypefun void glGetQueryObjectiv id pname params
9545 @deftypefunx void glGetQueryObjectuiv id pname params
9546 Return parameters of a query object.
9550 Specifies the name of a query object.
9553 Specifies the symbolic name of a query object parameter. Accepted values
9554 are @code{GL_QUERY_RESULT} or @code{GL_QUERY_RESULT_AVAILABLE}.
9557 Returns the requested data.
9561 @code{glGetQueryObject} returns in @var{params} a selected parameter of
9562 the query object specified by @var{id}.
9564 @var{pname} names a specific query object parameter. @var{pname} can be
9568 @item @code{GL_QUERY_RESULT}
9569 @var{params} returns the value of the query object's passed samples
9570 counter. The initial value is 0.
9572 @item @code{GL_QUERY_RESULT_AVAILABLE}
9573 @var{params} returns whether the passed samples counter is immediately
9574 available. If a delay would occur waiting for the query result,
9575 @code{GL_FALSE} is returned. Otherwise, @code{GL_TRUE} is returned,
9576 which also indicates that the results of all previous queries are
9581 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
9584 @code{GL_INVALID_OPERATION} is generated if @var{id} is not the name of
9587 @code{GL_INVALID_OPERATION} is generated if @var{id} is the name of a
9588 currently active query object.
9590 @code{GL_INVALID_OPERATION} is generated if @code{glGetQueryObject} is
9591 executed between the execution of @code{glBegin} and the corresponding
9592 execution of @code{glEnd}.
9596 @deftypefun void glGetSeparableFilter target format type row column span
9597 Get separable convolution filter kernel images.
9601 The separable filter to be retrieved. Must be @code{GL_SEPARABLE_2D}.
9604 Format of the output images. Must be one of @code{GL_RED},
9605 @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB},
9606 @code{GL_BGR}@code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, or
9607 @code{GL_LUMINANCE_ALPHA}.
9610 Data type of components in the output images. Symbolic constants
9611 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
9612 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
9613 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
9614 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
9615 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
9616 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
9617 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
9618 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
9619 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
9622 Pointer to storage for the row filter image.
9625 Pointer to storage for the column filter image.
9628 Pointer to storage for the span filter image (currently unused).
9632 @code{glGetSeparableFilter} returns the two one-dimensional filter
9633 kernel images for the current separable 2D convolution filter. The row
9634 image is placed in @var{row} and the column image is placed in
9635 @var{column} according to the specifications in @var{format} and
9636 @var{type}. (In the current implementation, @var{span} is not affected
9637 in any way.) No pixel transfer operations are performed on the images,
9638 but the relevant pixel storage modes are applied.
9640 If a non-zero named buffer object is bound to the
9641 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
9642 separable convolution filter is requested, @var{row}, @var{column}, and
9643 @var{span} are treated as a byte offset into the buffer object's data
9646 Color components that are present in @var{format} but not included in
9647 the internal format of the filters are returned as zero. The assignments
9648 of internal color components to the components of @var{format} are as
9654 @item @strong{Internal Component}
9655 @strong{Resulting Component}
9685 @code{GL_INVALID_ENUM} is generated if @var{target} is not
9686 @code{GL_SEPARABLE_2D}.
9688 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
9691 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
9694 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
9695 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
9696 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
9697 and @var{format} is not @code{GL_RGB}.
9699 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
9700 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
9701 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
9702 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
9703 @code{GL_UNSIGNED_INT_10_10_10_2}, or
9704 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
9705 @code{GL_RGBA} nor @code{GL_BGRA}.
9707 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9708 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
9709 object's data store is currently mapped.
9711 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9712 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
9713 would be packed to the buffer object such that the memory writes
9714 required would exceed the data store size.
9716 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9717 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{row} or
9718 @var{column} is not evenly divisible into the number of bytes needed to
9719 store in memory a datum indicated by @var{type}.
9721 @code{GL_INVALID_OPERATION} is generated if @code{glGetSeparableFilter}
9722 is executed between the execution of @code{glBegin} and the
9723 corresponding execution of @code{glEnd}.
9727 @deftypefun void glGetShaderInfoLog shader maxLength length infoLog
9728 Returns the information log for a shader object.
9732 Specifies the shader object whose information log is to be queried.
9734 @item @var{maxLength}
9735 Specifies the size of the character buffer for storing the returned
9739 Returns the length of the string returned in @var{infoLog} (excluding
9740 the null terminator).
9743 Specifies an array of characters that is used to return the information
9748 @code{glGetShaderInfoLog} returns the information log for the specified
9749 shader object. The information log for a shader object is modified when
9750 the shader is compiled. The string that is returned will be null
9753 @code{glGetShaderInfoLog} returns in @var{infoLog} as much of the
9754 information log as it can, up to a maximum of @var{maxLength}
9755 characters. The number of characters actually returned, excluding the
9756 null termination character, is specified by @var{length}. If the length
9757 of the returned string is not required, a value of @code{NULL} can be
9758 passed in the @var{length} argument. The size of the buffer required to
9759 store the returned information log can be obtained by calling
9760 @code{glGetShader} with the value @code{GL_INFO_LOG_LENGTH}.
9762 The information log for a shader object is a string that may contain
9763 diagnostic messages, warning messages, and other information about the
9764 last compile operation. When a shader object is created, its information
9765 log will be a string of length 0.
9767 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
9768 generated by OpenGL.
9770 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
9773 @code{GL_INVALID_VALUE} is generated if @var{maxLength} is less than 0.
9775 @code{GL_INVALID_OPERATION} is generated if @code{glGetShaderInfoLog} is
9776 executed between the execution of @code{glBegin} and the corresponding
9777 execution of @code{glEnd}.
9781 @deftypefun void glGetShaderSource shader bufSize length source
9782 Returns the source code string from a shader object.
9786 Specifies the shader object to be queried.
9789 Specifies the size of the character buffer for storing the returned
9793 Returns the length of the string returned in @var{source} (excluding the
9797 Specifies an array of characters that is used to return the source code
9802 @code{glGetShaderSource} returns the concatenation of the source code
9803 strings from the shader object specified by @var{shader}. The source
9804 code strings for a shader object are the result of a previous call to
9805 @code{glShaderSource}. The string returned by the function will be null
9808 @code{glGetShaderSource} returns in @var{source} as much of the source
9809 code string as it can, up to a maximum of @var{bufSize} characters. The
9810 number of characters actually returned, excluding the null termination
9811 character, is specified by @var{length}. If the length of the returned
9812 string is not required, a value of @code{NULL} can be passed in the
9813 @var{length} argument. The size of the buffer required to store the
9814 returned source code string can be obtained by calling
9815 @code{glGetShader} with the value @code{GL_SHADER_SOURCE_LENGTH}.
9817 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
9818 generated by OpenGL.
9820 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
9823 @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0.
9825 @code{GL_INVALID_OPERATION} is generated if @code{glGetShaderSource} is
9826 executed between the execution of @code{glBegin} and the corresponding
9827 execution of @code{glEnd}.
9831 @deftypefun void glGetShaderiv shader pname params
9832 Returns a parameter from a shader object.
9836 Specifies the shader object to be queried.
9839 Specifies the object parameter. Accepted symbolic names are
9840 @code{GL_SHADER_TYPE}, @code{GL_DELETE_STATUS},
9841 @code{GL_COMPILE_STATUS}, @code{GL_INFO_LOG_LENGTH},
9842 @code{GL_SHADER_SOURCE_LENGTH}.
9845 Returns the requested object parameter.
9849 @code{glGetShader} returns in @var{params} the value of a parameter for
9850 a specific shader object. The following parameters are defined:
9853 @item @code{GL_SHADER_TYPE}
9854 @var{params} returns @code{GL_VERTEX_SHADER} if @var{shader} is a vertex
9855 shader object, and @code{GL_FRAGMENT_SHADER} if @var{shader} is a
9856 fragment shader object.
9858 @item @code{GL_DELETE_STATUS}
9859 @var{params} returns @code{GL_TRUE} if @var{shader} is currently flagged
9860 for deletion, and @code{GL_FALSE} otherwise.
9862 @item @code{GL_COMPILE_STATUS}
9863 @var{params} returns @code{GL_TRUE} if the last compile operation on
9864 @var{shader} was successful, and @code{GL_FALSE} otherwise.
9866 @item @code{GL_INFO_LOG_LENGTH}
9867 @var{params} returns the number of characters in the information log for
9868 @var{shader} including the null termination character (i.e., the size of
9869 the character buffer required to store the information log). If
9870 @var{shader} has no information log, a value of 0 is returned.
9872 @item @code{GL_SHADER_SOURCE_LENGTH}
9873 @var{params} returns the length of the concatenation of the source
9874 strings that make up the shader source for the @var{shader}, including
9875 the null termination character. (i.e., the size of the character buffer
9876 required to store the shader source). If no source code exists, 0 is
9881 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
9882 generated by OpenGL.
9884 @code{GL_INVALID_OPERATION} is generated if @var{shader} does not refer
9887 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
9890 @code{GL_INVALID_OPERATION} is generated if @code{glGetShader} is
9891 executed between the execution of @code{glBegin} and the corresponding
9892 execution of @code{glEnd}.
9896 @deftypefun const-GLubyte* glGetString name
9897 Return a string describing the current GL connection.
9901 Specifies a symbolic constant, one of @code{GL_VENDOR},
9902 @code{GL_RENDERER}, @code{GL_VERSION},
9903 @code{GL_SHADING_LANGUAGE_VERSION}, or @code{GL_EXTENSIONS}.
9907 @code{glGetString} returns a pointer to a static string describing some
9908 aspect of the current GL connection. @var{name} can be one of the
9912 @item @code{GL_VENDOR}
9915 Returns the company responsible for this GL implementation. This name
9916 does not change from release to release.
9918 @item @code{GL_RENDERER}
9921 Returns the name of the renderer. This name is typically specific to a
9922 particular configuration of a hardware platform. It does not change from
9925 @item @code{GL_VERSION}
9928 Returns a version or release number.
9930 @item @code{GL_SHADING_LANGUAGE_VERSION}
9933 Returns a version or release number for the shading language.
9935 @item @code{GL_EXTENSIONS}
9938 Returns a space-separated list of supported extensions to GL.
9942 Because the GL does not include queries for the performance
9943 characteristics of an implementation, some applications are written to
9944 recognize known platforms and modify their GL usage based on known
9945 performance characteristics of these platforms. Strings @code{GL_VENDOR}
9946 and @code{GL_RENDERER} together uniquely specify a platform. They do not
9947 change from release to release and should be used by
9948 platform-recognition algorithms.
9950 Some applications want to make use of features that are not part of the
9951 standard GL. These features may be implemented as extensions to the
9952 standard GL. The @code{GL_EXTENSIONS} string is a space-separated list
9953 of supported GL extensions. (Extension names never contain a space
9956 The @code{GL_VERSION} and @code{GL_SHADING_LANGUAGE_VERSION} strings
9957 begin with a version number. The version number uses one of these forms:
9959 @var{major_number.minor_number}@var{major_number.minor_number.release_number}
9961 Vendor-specific information may follow the version number. Its format
9962 depends on the implementation, but a space always separates the version
9963 number and the vendor-specific information.
9965 All strings are null-terminated.
9967 @code{GL_INVALID_ENUM} is generated if @var{name} is not an accepted
9970 @code{GL_INVALID_OPERATION} is generated if @code{glGetString} is
9971 executed between the execution of @code{glBegin} and the corresponding
9972 execution of @code{glEnd}.
9976 @deftypefun void glGetTexEnvfv target pname params
9977 @deftypefunx void glGetTexEnviv target pname params
9978 Return texture environment parameters.
9982 Specifies a texture environment. May be @code{GL_TEXTURE_ENV},
9983 @code{GL_TEXTURE_FILTER_CONTROL}, or @code{GL_POINT_SPRITE}.
9986 Specifies the symbolic name of a texture environment parameter. Accepted
9987 values are @code{GL_TEXTURE_ENV_MODE}, @code{GL_TEXTURE_ENV_COLOR},
9988 @code{GL_TEXTURE_LOD_BIAS}, @code{GL_COMBINE_RGB},
9989 @code{GL_COMBINE_ALPHA}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB},
9990 @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA},
9991 @code{GL_SRC2_ALPHA}, @code{GL_OPERAND0_RGB}, @code{GL_OPERAND1_RGB},
9992 @code{GL_OPERAND2_RGB}, @code{GL_OPERAND0_ALPHA},
9993 @code{GL_OPERAND1_ALPHA}, @code{GL_OPERAND2_ALPHA}, @code{GL_RGB_SCALE},
9994 @code{GL_ALPHA_SCALE}, or @code{GL_COORD_REPLACE}.
9997 Returns the requested data.
10001 @code{glGetTexEnv} returns in @var{params} selected values of a texture
10002 environment that was specified with @code{glTexEnv}. @var{target}
10003 specifies a texture environment.
10005 When @var{target} is @code{GL_TEXTURE_FILTER_CONTROL}, @var{pname} must
10006 be @code{GL_TEXTURE_LOD_BIAS}. When @var{target} is
10007 @code{GL_POINT_SPRITE}, @var{pname} must be @code{GL_COORD_REPLACE}.
10008 When @var{target} is @code{GL_TEXTURE_ENV}, @var{pname} can be
10009 @code{GL_TEXTURE_ENV_MODE}, @code{GL_TEXTURE_ENV_COLOR},
10010 @code{GL_COMBINE_RGB}, @code{GL_COMBINE_ALPHA}, @code{GL_RGB_SCALE},
10011 @code{GL_ALPHA_SCALE}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB},
10012 @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, or
10013 @code{GL_SRC2_ALPHA}.
10015 @var{pname} names a specific texture environment parameter, as follows:
10018 @item @code{GL_TEXTURE_ENV_MODE}
10019 @var{params} returns the single-valued texture environment mode, a
10020 symbolic constant. The initial value is @code{GL_MODULATE}.
10022 @item @code{GL_TEXTURE_ENV_COLOR}
10023 @var{params} returns four integer or floating-point values that are the
10024 texture environment color. Integer values, when requested, are linearly
10025 mapped from the internal floating-point representation such that 1.0
10026 maps to the most positive representable integer, and @r{-1.0} maps to
10027 the most negative representable integer. The initial value is (0, 0, 0,
10030 @item @code{GL_TEXTURE_LOD_BIAS}
10031 @var{params} returns a single floating-point value that is the texture
10032 level-of-detail bias. The initial value is 0.
10034 @item @code{GL_COMBINE_RGB}
10035 @var{params} returns a single symbolic constant value representing the
10036 current RGB combine mode. The initial value is @code{GL_MODULATE}.
10038 @item @code{GL_COMBINE_ALPHA}
10039 @var{params} returns a single symbolic constant value representing the
10040 current alpha combine mode. The initial value is @code{GL_MODULATE}.
10042 @item @code{GL_SRC0_RGB}
10043 @var{params} returns a single symbolic constant value representing the
10044 texture combiner zero's RGB source. The initial value is
10047 @item @code{GL_SRC1_RGB}
10048 @var{params} returns a single symbolic constant value representing the
10049 texture combiner one's RGB source. The initial value is
10050 @code{GL_PREVIOUS}.
10052 @item @code{GL_SRC2_RGB}
10053 @var{params} returns a single symbolic constant value representing the
10054 texture combiner two's RGB source. The initial value is
10055 @code{GL_CONSTANT}.
10057 @item @code{GL_SRC0_ALPHA}
10058 @var{params} returns a single symbolic constant value representing the
10059 texture combiner zero's alpha source. The initial value is
10062 @item @code{GL_SRC1_ALPHA}
10063 @var{params} returns a single symbolic constant value representing the
10064 texture combiner one's alpha source. The initial value is
10065 @code{GL_PREVIOUS}.
10067 @item @code{GL_SRC2_ALPHA}
10068 @var{params} returns a single symbolic constant value representing the
10069 texture combiner two's alpha source. The initial value is
10070 @code{GL_CONSTANT}.
10072 @item @code{GL_OPERAND0_RGB}
10073 @var{params} returns a single symbolic constant value representing the
10074 texture combiner zero's RGB operand. The initial value is
10075 @code{GL_SRC_COLOR}.
10077 @item @code{GL_OPERAND1_RGB}
10078 @var{params} returns a single symbolic constant value representing the
10079 texture combiner one's RGB operand. The initial value is
10080 @code{GL_SRC_COLOR}.
10082 @item @code{GL_OPERAND2_RGB}
10083 @var{params} returns a single symbolic constant value representing the
10084 texture combiner two's RGB operand. The initial value is
10085 @code{GL_SRC_ALPHA}.
10087 @item @code{GL_OPERAND0_ALPHA}
10088 @var{params} returns a single symbolic constant value representing the
10089 texture combiner zero's alpha operand. The initial value is
10090 @code{GL_SRC_ALPHA}.
10092 @item @code{GL_OPERAND1_ALPHA}
10093 @var{params} returns a single symbolic constant value representing the
10094 texture combiner one's alpha operand. The initial value is
10095 @code{GL_SRC_ALPHA}.
10097 @item @code{GL_OPERAND2_ALPHA}
10098 @var{params} returns a single symbolic constant value representing the
10099 texture combiner two's alpha operand. The initial value is
10100 @code{GL_SRC_ALPHA}.
10102 @item @code{GL_RGB_SCALE}
10103 @var{params} returns a single floating-point value representing the
10104 current RGB texture combiner scaling factor. The initial value is 1.0.
10106 @item @code{GL_ALPHA_SCALE}
10107 @var{params} returns a single floating-point value representing the
10108 current alpha texture combiner scaling factor. The initial value is 1.0.
10110 @item @code{GL_COORD_REPLACE}
10111 @var{params} returns a single boolean value representing the current
10112 point sprite texture coordinate replacement enable state. The initial
10113 value is @code{GL_FALSE}.
10117 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
10118 not an accepted value.
10120 @code{GL_INVALID_OPERATION} is generated if @code{glGetTexEnv} is
10121 executed between the execution of @code{glBegin} and the corresponding
10122 execution of @code{glEnd}.
10126 @deftypefun void glGetTexGenfv coord pname params
10127 @deftypefunx void glGetTexGeniv coord pname params
10128 Return texture coordinate generation parameters.
10132 Specifies a texture coordinate. Must be @code{GL_S}, @code{GL_T},
10133 @code{GL_R}, or @code{GL_Q}.
10136 Specifies the symbolic name of the value(s) to be returned. Must be
10137 either @code{GL_TEXTURE_GEN_MODE} or the name of one of the texture
10138 generation plane equations: @code{GL_OBJECT_PLANE} or
10139 @code{GL_EYE_PLANE}.
10142 Returns the requested data.
10146 @code{glGetTexGen} returns in @var{params} selected parameters of a
10147 texture coordinate generation function that was specified using
10148 @code{glTexGen}. @var{coord} names one of the (@var{s}, @var{t},
10149 @var{r}, @var{q}) texture coordinates, using the symbolic constant
10150 @code{GL_S}, @code{GL_T}, @code{GL_R}, or @code{GL_Q}.
10152 @var{pname} specifies one of three symbolic names:
10155 @item @code{GL_TEXTURE_GEN_MODE}
10156 @var{params} returns the single-valued texture generation function, a
10157 symbolic constant. The initial value is @code{GL_EYE_LINEAR}.
10159 @item @code{GL_OBJECT_PLANE}
10160 @var{params} returns the four plane equation coefficients that specify
10161 object linear-coordinate generation. Integer values, when requested, are
10162 mapped directly from the internal floating-point representation.
10164 @item @code{GL_EYE_PLANE}
10165 @var{params} returns the four plane equation coefficients that specify
10166 eye linear-coordinate generation. Integer values, when requested, are
10167 mapped directly from the internal floating-point representation. The
10168 returned values are those maintained in eye coordinates. They are not
10169 equal to the values specified using @code{glTexGen}, unless the
10170 modelview matrix was identity when @code{glTexGen} was called.
10174 @code{GL_INVALID_ENUM} is generated if @var{coord} or @var{pname} is not
10177 @code{GL_INVALID_OPERATION} is generated if @code{glGetTexGen} is
10178 executed between the execution of @code{glBegin} and the corresponding
10179 execution of @code{glEnd}.
10183 @deftypefun void glGetTexImage target level format type img
10184 Return a texture image.
10188 Specifies which texture is to be obtained. @code{GL_TEXTURE_1D},
10189 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D},
10190 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
10191 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
10192 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
10193 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
10194 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, and
10195 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z} are accepted.
10198 Specifies the level-of-detail number of the desired image. Level 0 is
10199 the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap
10203 Specifies a pixel format for the returned data. The supported formats
10204 are @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
10205 @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA},
10206 @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA}.
10209 Specifies a pixel type for the returned data. The supported types are
10210 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT},
10211 @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT},
10212 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
10213 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
10214 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
10215 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
10216 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
10217 @code{GL_UNSIGNED_INT_10_10_10_2}, and
10218 @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
10221 Returns the texture image. Should be a pointer to an array of the type
10222 specified by @var{type}.
10226 @code{glGetTexImage} returns a texture image into @var{img}.
10227 @var{target} specifies whether the desired texture image is one
10228 specified by @code{glTexImage1D} (@code{GL_TEXTURE_1D}),
10229 @code{glTexImage2D} (@code{GL_TEXTURE_2D} or any of
10230 @code{GL_TEXTURE_CUBE_MAP_*}), or @code{glTexImage3D}
10231 (@code{GL_TEXTURE_3D}). @var{level} specifies the level-of-detail number
10232 of the desired image. @var{format} and @var{type} specify the format and
10233 type of the desired image array. See the reference pages
10234 @code{glTexImage1D} and @code{glDrawPixels} for a description of the
10235 acceptable values for the @var{format} and @var{type} parameters,
10238 If a non-zero named buffer object is bound to the
10239 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
10240 texture image is requested, @var{img} is treated as a byte offset into
10241 the buffer object's data store.
10243 To understand the operation of @code{glGetTexImage}, consider the
10244 selected internal four-component texture image to be an RGBA color
10245 buffer the size of the image. The semantics of @code{glGetTexImage} are
10246 then identical to those of @code{glReadPixels}, with the exception that
10247 no pixel transfer operations are performed, when called with the same
10248 @var{format} and @var{type}, with @var{x} and @var{y} set to 0,
10249 @var{width} set to the width of the texture image (including border if
10250 one was specified), and @var{height} set to 1 for 1D images, or to the
10251 height of the texture image (including border if one was specified) for
10252 2D images. Because the internal texture image is an RGBA image, pixel
10253 formats @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, and
10254 @code{GL_DEPTH_COMPONENT} are not accepted, and pixel type
10255 @code{GL_BITMAP} is not accepted.
10257 If the selected texture image does not contain four components, the
10258 following mappings are applied. Single-component textures are treated as
10259 RGBA buffers with red set to the single-component value, green set to 0,
10260 blue set to 0, and alpha set to 1. Two-component textures are treated as
10261 RGBA buffers with red set to the value of component zero, alpha set to
10262 the value of component one, and green and blue set to 0. Finally,
10263 three-component textures are treated as RGBA buffers with red set to
10264 component zero, green set to component one, blue set to component two,
10265 and alpha set to 1.
10267 To determine the required size of @var{img}, use
10268 @code{glGetTexLevelParameter} to determine the dimensions of the
10269 internal texture image, then scale the required number of pixels by the
10270 storage required for each pixel, based on @var{format} and @var{type}.
10271 Be sure to take the pixel storage parameters into account, especially
10272 @code{GL_PACK_ALIGNMENT}.
10274 @code{GL_INVALID_ENUM} is generated if @var{target}, @var{format}, or
10275 @var{type} is not an accepted value.
10277 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
10279 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
10280 @r{@var{log}_2(@var{max},)}, where @r{@var{max}} is the returned value
10281 of @code{GL_MAX_TEXTURE_SIZE}.
10283 @code{GL_INVALID_OPERATION} is returned if @var{type} is one of
10284 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
10285 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
10286 and @var{format} is not @code{GL_RGB}.
10288 @code{GL_INVALID_OPERATION} is returned if @var{type} is one of
10289 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
10290 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
10291 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
10292 @code{GL_UNSIGNED_INT_10_10_10_2}, or
10293 @code{GL_UNSIGNED_INT_2_10_10_10_REV}, and @var{format} is neither
10294 @code{GL_RGBA} or @code{GL_BGRA}.
10296 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
10297 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
10298 object's data store is currently mapped.
10300 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
10301 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
10302 would be packed to the buffer object such that the memory writes
10303 required would exceed the data store size.
10305 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
10306 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{img} is
10307 not evenly divisible into the number of bytes needed to store in memory
10308 a datum indicated by @var{type}.
10310 @code{GL_INVALID_OPERATION} is generated if @code{glGetTexImage} is
10311 executed between the execution of @code{glBegin} and the corresponding
10312 execution of @code{glEnd}.
10316 @deftypefun void glGetTexLevelParameterfv target level pname params
10317 @deftypefunx void glGetTexLevelParameteriv target level pname params
10318 Return texture parameter values for a specific level of detail.
10322 Specifies the symbolic name of the target texture, either
10323 @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D},
10324 @code{GL_PROXY_TEXTURE_1D}, @code{GL_PROXY_TEXTURE_2D},
10325 @code{GL_PROXY_TEXTURE_3D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
10326 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
10327 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
10328 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
10329 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z},
10330 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or
10331 @code{GL_PROXY_TEXTURE_CUBE_MAP}.
10334 Specifies the level-of-detail number of the desired image. Level 0 is
10335 the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap
10339 Specifies the symbolic name of a texture parameter.
10340 @code{GL_TEXTURE_WIDTH}, @code{GL_TEXTURE_HEIGHT},
10341 @code{GL_TEXTURE_DEPTH}, @code{GL_TEXTURE_INTERNAL_FORMAT},
10342 @code{GL_TEXTURE_BORDER}, @code{GL_TEXTURE_RED_SIZE},
10343 @code{GL_TEXTURE_GREEN_SIZE}, @code{GL_TEXTURE_BLUE_SIZE},
10344 @code{GL_TEXTURE_ALPHA_SIZE}, @code{GL_TEXTURE_LUMINANCE_SIZE},
10345 @code{GL_TEXTURE_INTENSITY_SIZE}, @code{GL_TEXTURE_DEPTH_SIZE},
10346 @code{GL_TEXTURE_COMPRESSED}, and
10347 @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} are accepted.
10350 Returns the requested data.
10354 @code{glGetTexLevelParameter} returns in @var{params} texture parameter
10355 values for a specific level-of-detail value, specified as @var{level}.
10356 @var{target} defines the target texture, either @code{GL_TEXTURE_1D},
10357 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, @code{GL_PROXY_TEXTURE_1D},
10358 @code{GL_PROXY_TEXTURE_2D}, @code{GL_PROXY_TEXTURE_3D},
10359 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
10360 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
10361 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
10362 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
10363 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z},
10364 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or
10365 @code{GL_PROXY_TEXTURE_CUBE_MAP}.
10367 @code{GL_MAX_TEXTURE_SIZE}, and @code{GL_MAX_3D_TEXTURE_SIZE} are not
10368 really descriptive enough. It has to report the largest square texture
10369 image that can be accommodated with mipmaps and borders, but a long
10370 skinny texture, or a texture without mipmaps and borders, may easily fit
10371 in texture memory. The proxy targets allow the user to more accurately
10372 query whether the GL can accommodate a texture of a given configuration.
10373 If the texture cannot be accommodated, the texture state variables,
10374 which may be queried with @code{glGetTexLevelParameter}, are set to 0.
10375 If the texture can be accommodated, the texture state values will be set
10376 as they would be set for a non-proxy target.
10378 @var{pname} specifies the texture parameter whose value or values will
10381 The accepted parameter names are as follows:
10384 @item @code{GL_TEXTURE_WIDTH}
10387 @var{params} returns a single value, the width of the texture image.
10388 This value includes the border of the texture image. The initial value
10391 @item @code{GL_TEXTURE_HEIGHT}
10394 @var{params} returns a single value, the height of the texture image.
10395 This value includes the border of the texture image. The initial value
10398 @item @code{GL_TEXTURE_DEPTH}
10401 @var{params} returns a single value, the depth of the texture image.
10402 This value includes the border of the texture image. The initial value
10405 @item @code{GL_TEXTURE_INTERNAL_FORMAT}
10408 @var{params} returns a single value, the internal format of the texture
10411 @item @code{GL_TEXTURE_BORDER}
10414 @var{params} returns a single value, the width in pixels of the border
10415 of the texture image. The initial value is 0.
10417 @item @code{GL_TEXTURE_RED_SIZE},
10418 @item @code{GL_TEXTURE_GREEN_SIZE},
10419 @item @code{GL_TEXTURE_BLUE_SIZE},
10420 @item @code{GL_TEXTURE_ALPHA_SIZE},
10421 @item @code{GL_TEXTURE_LUMINANCE_SIZE},
10422 @item @code{GL_TEXTURE_INTENSITY_SIZE},
10423 @item @code{GL_TEXTURE_DEPTH_SIZE}
10426 The internal storage resolution of an individual component. The
10427 resolution chosen by the GL will be a close match for the resolution
10428 requested by the user with the component argument of
10429 @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D},
10430 @code{glCopyTexImage1D}, and @code{glCopyTexImage2D}. The initial value
10433 @item @code{GL_TEXTURE_COMPRESSED}
10436 @var{params} returns a single boolean value indicating if the texture
10437 image is stored in a compressed internal format. The initiali value is
10440 @item @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE}
10443 @var{params} returns a single integer value, the number of unsigned
10444 bytes of the compressed texture image that would be returned from
10445 @code{glGetCompressedTexImage}.
10449 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
10450 not an accepted value.
10452 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
10454 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
10455 @r{@var{log}_2}@var{max}, where @var{max} is the returned value of
10456 @code{GL_MAX_TEXTURE_SIZE}.
10458 @code{GL_INVALID_OPERATION} is generated if
10459 @code{glGetTexLevelParameter} is executed between the execution of
10460 @code{glBegin} and the corresponding execution of @code{glEnd}.
10462 @code{GL_INVALID_OPERATION} is generated if
10463 @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} is queried on texture images
10464 with an uncompressed internal format or on proxy targets.
10468 @deftypefun void glGetTexParameterfv target pname params
10469 @deftypefunx void glGetTexParameteriv target pname params
10470 Return texture parameter values.
10474 Specifies the symbolic name of the target texture. @code{GL_TEXTURE_1D},
10475 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, and
10476 @code{GL_TEXTURE_CUBE_MAP} are accepted.
10479 Specifies the symbolic name of a texture parameter.
10480 @code{GL_TEXTURE_MAG_FILTER}, @code{GL_TEXTURE_MIN_FILTER},
10481 @code{GL_TEXTURE_MIN_LOD}, @code{GL_TEXTURE_MAX_LOD},
10482 @code{GL_TEXTURE_BASE_LEVEL}, @code{GL_TEXTURE_MAX_LEVEL},
10483 @code{GL_TEXTURE_WRAP_S}, @code{GL_TEXTURE_WRAP_T},
10484 @code{GL_TEXTURE_WRAP_R}, @code{GL_TEXTURE_BORDER_COLOR},
10485 @code{GL_TEXTURE_PRIORITY}, @code{GL_TEXTURE_RESIDENT},
10486 @code{GL_TEXTURE_COMPARE_MODE}, @code{GL_TEXTURE_COMPARE_FUNC},
10487 @code{GL_DEPTH_TEXTURE_MODE}, and @code{GL_GENERATE_MIPMAP} are
10491 Returns the texture parameters.
10495 @code{glGetTexParameter} returns in @var{params} the value or values of
10496 the texture parameter specified as @var{pname}. @var{target} defines the
10497 target texture, either @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D},
10498 @code{GL_TEXTURE_3D}, or @code{GL_TEXTURE_CUBE_MAP}, to specify one-,
10499 two-, or three-dimensional or cube-mapped texturing. @var{pname} accepts
10500 the same symbols as @code{glTexParameter}, with the same
10504 @item @code{GL_TEXTURE_MAG_FILTER}
10505 Returns the single-valued texture magnification filter, a symbolic
10506 constant. The initial value is @code{GL_LINEAR}.
10508 @item @code{GL_TEXTURE_MIN_FILTER}
10509 Returns the single-valued texture minification filter, a symbolic
10510 constant. The initial value is @code{GL_NEAREST_MIPMAP_LINEAR}.
10512 @item @code{GL_TEXTURE_MIN_LOD}
10513 Returns the single-valued texture minimum level-of-detail value. The
10514 initial value is @r{-1000}.
10516 @item @code{GL_TEXTURE_MAX_LOD}
10517 Returns the single-valued texture maximum level-of-detail value. The
10518 initial value is 1000.
10520 @item @code{GL_TEXTURE_BASE_LEVEL}
10521 Returns the single-valued base texture mipmap level. The initial value
10524 @item @code{GL_TEXTURE_MAX_LEVEL}
10525 Returns the single-valued maximum texture mipmap array level. The
10526 initial value is 1000.
10528 @item @code{GL_TEXTURE_WRAP_S}
10529 Returns the single-valued wrapping function for texture coordinate
10530 @r{@var{s}}, a symbolic constant. The initial value is @code{GL_REPEAT}.
10532 @item @code{GL_TEXTURE_WRAP_T}
10533 Returns the single-valued wrapping function for texture coordinate
10534 @r{@var{t}}, a symbolic constant. The initial value is @code{GL_REPEAT}.
10536 @item @code{GL_TEXTURE_WRAP_R}
10537 Returns the single-valued wrapping function for texture coordinate
10538 @r{@var{r}}, a symbolic constant. The initial value is @code{GL_REPEAT}.
10540 @item @code{GL_TEXTURE_BORDER_COLOR}
10541 Returns four integer or floating-point numbers that comprise the RGBA
10542 color of the texture border. Floating-point values are returned in the
10543 range @r{[0,1]}. Integer values are returned as a linear mapping of the
10544 internal floating-point representation such that 1.0 maps to the most
10545 positive representable integer and @r{-1.0} maps to the most negative
10546 representable integer. The initial value is (0, 0, 0, 0).
10548 @item @code{GL_TEXTURE_PRIORITY}
10549 Returns the residence priority of the target texture (or the named
10550 texture bound to it). The initial value is 1. See
10551 @code{glPrioritizeTextures}.
10553 @item @code{GL_TEXTURE_RESIDENT}
10554 Returns the residence status of the target texture. If the value
10555 returned in @var{params} is @code{GL_TRUE}, the texture is resident in
10556 texture memory. See @code{glAreTexturesResident}.
10558 @item @code{GL_TEXTURE_COMPARE_MODE}
10559 Returns a single-valued texture comparison mode, a symbolic constant.
10560 The initial value is @code{GL_NONE}. See @code{glTexParameter}.
10562 @item @code{GL_TEXTURE_COMPARE_FUNC}
10563 Returns a single-valued texture comparison function, a symbolic
10564 constant. The initial value is @code{GL_LEQUAL}. See
10565 @code{glTexParameter}.
10567 @item @code{GL_DEPTH_TEXTURE_MODE}
10568 Returns a single-valued texture format indicating how the depth values
10569 should be converted into color components. The initial value is
10570 @code{GL_LUMINANCE}. See @code{glTexParameter}.
10572 @item @code{GL_GENERATE_MIPMAP}
10573 Returns a single boolean value indicating if automatic mipmap level
10574 updates are enabled. See @code{glTexParameter}.
10578 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
10579 not an accepted value.
10581 @code{GL_INVALID_OPERATION} is generated if @code{glGetTexParameter} is
10582 executed between the execution of @code{glBegin} and the corresponding
10583 execution of @code{glEnd}.
10587 @deftypefun GLint glGetUniformLocation program name
10588 Returns the location of a uniform variable.
10591 @item @var{program}
10592 Specifies the program object to be queried.
10595 Points to a null terminated string containing the name of the uniform
10596 variable whose location is to be queried.
10600 @code{glGetUniformLocation } returns an integer that represents the
10601 location of a specific uniform variable within a program object.
10602 @var{name} must be a null terminated string that contains no white
10603 space. @var{name} must be an active uniform variable name in
10604 @var{program} that is not a structure, an array of structures, or a
10605 subcomponent of a vector or a matrix. This function returns -1 if
10606 @var{name} does not correspond to an active uniform variable in
10607 @var{program} or if @var{name} starts with the reserved prefix "gl_".
10609 Uniform variables that are structures or arrays of structures may be
10610 queried by calling @code{glGetUniformLocation} for each field within the
10611 structure. The array element operator "[]" and the structure field
10612 operator "." may be used in @var{name} in order to select elements
10613 within an array or fields within a structure. The result of using these
10614 operators is not allowed to be another structure, an array of
10615 structures, or a subcomponent of a vector or a matrix. Except if the
10616 last part of @var{name} indicates a uniform variable array, the location
10617 of the first element of an array can be retrieved by using the name of
10618 the array, or by using the name appended by "[0]".
10620 The actual locations assigned to uniform variables are not known until
10621 the program object is linked successfully. After linking has occurred,
10622 the command @code{glGetUniformLocation} can be used to obtain the
10623 location of a uniform variable. This location value can then be passed
10624 to @code{glUniform} to set the value of the uniform variable or to
10625 @code{glGetUniform} in order to query the current value of the uniform
10626 variable. After a program object has been linked successfully, the index
10627 values for uniform variables remain fixed until the next link command
10628 occurs. Uniform variable locations and values can only be queried after
10629 a link if the link was successful.
10631 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
10632 generated by OpenGL.
10634 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
10637 @code{GL_INVALID_OPERATION} is generated if @var{program} has not been
10638 successfully linked.
10640 @code{GL_INVALID_OPERATION} is generated if @code{glGetUniformLocation}
10641 is executed between the execution of @code{glBegin} and the
10642 corresponding execution of @code{glEnd}.
10646 @deftypefun void glGetUniformfv program location params
10647 @deftypefunx void glGetUniformiv program location params
10648 Returns the value of a uniform variable.
10651 @item @var{program}
10652 Specifies the program object to be queried.
10654 @item @var{location}
10655 Specifies the location of the uniform variable to be queried.
10658 Returns the value of the specified uniform variable.
10662 @code{glGetUniform} returns in @var{params} the value(s) of the
10663 specified uniform variable. The type of the uniform variable specified
10664 by @var{location} determines the number of values returned. If the
10665 uniform variable is defined in the shader as a boolean, int, or float, a
10666 single value will be returned. If it is defined as a vec2, ivec2, or
10667 bvec2, two values will be returned. If it is defined as a vec3, ivec3,
10668 or bvec3, three values will be returned, and so on. To query values
10669 stored in uniform variables declared as arrays, call @code{glGetUniform}
10670 for each element of the array. To query values stored in uniform
10671 variables declared as structures, call @code{glGetUniform} for each
10672 field in the structure. The values for uniform variables declared as a
10673 matrix will be returned in column major order.
10675 The locations assigned to uniform variables are not known until the
10676 program object is linked. After linking has occurred, the command
10677 @code{glGetUniformLocation} can be used to obtain the location of a
10678 uniform variable. This location value can then be passed to
10679 @code{glGetUniform} in order to query the current value of the uniform
10680 variable. After a program object has been linked successfully, the index
10681 values for uniform variables remain fixed until the next link command
10682 occurs. The uniform variable values can only be queried after a link if
10683 the link was successful.
10685 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
10686 generated by OpenGL.
10688 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
10691 @code{GL_INVALID_OPERATION} is generated if @var{program} has not been
10692 successfully linked.
10694 @code{GL_INVALID_OPERATION} is generated if @var{location} does not
10695 correspond to a valid uniform variable location for the specified
10698 @code{GL_INVALID_OPERATION} is generated if @code{glGetUniform} is
10699 executed between the execution of @code{glBegin} and the corresponding
10700 execution of @code{glEnd}.
10704 @deftypefun void glGetVertexAttribPointerv index pname pointer
10705 Return the address of the specified generic vertex attribute pointer.
10709 Specifies the generic vertex attribute parameter to be returned.
10712 Specifies the symbolic name of the generic vertex attribute parameter to
10713 be returned. Must be @code{GL_VERTEX_ATTRIB_ARRAY_POINTER}.
10715 @item @var{pointer}
10716 Returns the pointer value.
10720 @code{glGetVertexAttribPointerv} returns pointer information.
10721 @var{index} is the generic vertex attribute to be queried, @var{pname}
10722 is a symbolic constant indicating the pointer to be returned, and
10723 @var{params} is a pointer to a location in which to place the returned
10726 If a non-zero named buffer object was bound to the
10727 @code{GL_ARRAY_BUFFER} target (see @code{glBindBuffer}) when the desired
10728 pointer was previously specified, the @var{pointer} returned is a byte
10729 offset into the buffer object's data store.
10731 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
10732 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
10734 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
10739 @deftypefun void glGetVertexAttribfv index pname params
10740 @deftypefunx void glGetVertexAttribiv index pname params
10741 Return a generic vertex attribute parameter.
10745 Specifies the generic vertex attribute parameter to be queried.
10748 Specifies the symbolic name of the vertex attribute parameter to be
10749 queried. Accepted values are
10750 @code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING},
10751 @code{GL_VERTEX_ATTRIB_ARRAY_ENABLED},
10752 @code{GL_VERTEX_ATTRIB_ARRAY_SIZE},
10753 @code{GL_VERTEX_ATTRIB_ARRAY_STRIDE},
10754 @code{GL_VERTEX_ATTRIB_ARRAY_TYPE},
10755 @code{GL_VERTEX_ATTRIB_ARRAY_NORMALIZED}, or
10756 @code{GL_CURRENT_VERTEX_ATTRIB}.
10759 Returns the requested data.
10763 @code{glGetVertexAttrib} returns in @var{params} the value of a generic
10764 vertex attribute parameter. The generic vertex attribute to be queried
10765 is specified by @var{index}, and the parameter to be queried is
10766 specified by @var{pname}.
10768 The accepted parameter names are as follows:
10771 @item @code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING}
10774 @var{params} returns a single value, the name of the buffer object
10775 currently bound to the binding point corresponding to generic vertex
10776 attribute array @var{index}. If no buffer object is bound, 0 is
10777 returned. The initial value is 0.
10779 @item @code{GL_VERTEX_ATTRIB_ARRAY_ENABLED}
10782 @var{params} returns a single value that is non-zero (true) if the
10783 vertex attribute array for @var{index} is enabled and 0 (false) if it is
10784 disabled. The initial value is @code{GL_FALSE}.
10786 @item @code{GL_VERTEX_ATTRIB_ARRAY_SIZE}
10789 @var{params} returns a single value, the size of the vertex attribute
10790 array for @var{index}. The size is the number of values for each element
10791 of the vertex attribute array, and it will be 1, 2, 3, or 4. The initial
10794 @item @code{GL_VERTEX_ATTRIB_ARRAY_STRIDE}
10797 @var{params} returns a single value, the array stride for (number of
10798 bytes between successive elements in) the vertex attribute array for
10799 @var{index}. A value of 0 indicates that the array elements are stored
10800 sequentially in memory. The initial value is 0.
10802 @item @code{GL_VERTEX_ATTRIB_ARRAY_TYPE}
10805 @var{params} returns a single value, a symbolic constant indicating the
10806 array type for the vertex attribute array for @var{index}. Possible
10807 values are @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
10808 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
10809 @code{GL_FLOAT}, and @code{GL_DOUBLE}. The initial value is
10812 @item @code{GL_VERTEX_ATTRIB_ARRAY_NORMALIZED}
10815 @var{params} returns a single value that is non-zero (true) if
10816 fixed-point data types for the vertex attribute array indicated by
10817 @var{index} are normalized when they are converted to floating point,
10818 and 0 (false) otherwise. The initial value is @code{GL_FALSE}.
10820 @item @code{GL_CURRENT_VERTEX_ATTRIB}
10823 @var{params} returns four values that represent the current value for
10824 the generic vertex attribute specified by index. Generic vertex
10825 attribute 0 is unique in that it has no current state, so an error will
10826 be generated if @var{index} is 0. The initial value for all other
10827 generic vertex attributes is (0,0,0,1).
10831 All of the parameters except @code{GL_CURRENT_VERTEX_ATTRIB} represent
10834 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
10835 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
10837 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
10840 @code{GL_INVALID_OPERATION} is generated if @var{index} is 0 and
10841 @var{pname} is @code{GL_CURRENT_VERTEX_ATTRIB}.
10845 @deftypefun void glGetBooleanv pname params
10846 @deftypefunx void glGetDoublev pname params
10847 @deftypefunx void glGetFloatv pname params
10848 @deftypefunx void glGetIntegerv pname params
10849 Return the value or values of a selected parameter.
10853 Specifies the parameter value to be returned. The symbolic constants in
10854 the list below are accepted.
10857 Returns the value or values of the specified parameter.
10861 These four commands return values for simple state variables in GL.
10862 @var{pname} is a symbolic constant indicating the state variable to be
10863 returned, and @var{params} is a pointer to an array of the indicated
10864 type in which to place the returned data.
10866 Type conversion is performed if @var{params} has a different type than
10867 the state variable value being requested. If @code{glGetBooleanv} is
10868 called, a floating-point (or integer) value is converted to
10869 @code{GL_FALSE} if and only if it is 0.0 (or 0). Otherwise, it is
10870 converted to @code{GL_TRUE}. If @code{glGetIntegerv} is called, boolean
10871 values are returned as @code{GL_TRUE} or @code{GL_FALSE}, and most
10872 floating-point values are rounded to the nearest integer value.
10873 Floating-point colors and normals, however, are returned with a linear
10874 mapping that maps 1.0 to the most positive representable integer value
10875 and @r{-1.0} to the most negative representable integer value. If
10876 @code{glGetFloatv} or @code{glGetDoublev} is called, boolean values are
10877 returned as @code{GL_TRUE} or @code{GL_FALSE}, and integer values are
10878 converted to floating-point values.
10880 The following symbolic constants are accepted by @var{pname}:
10883 @item @code{GL_ACCUM_ALPHA_BITS}
10886 @var{params} returns one value, the number of alpha bitplanes in the
10887 accumulation buffer.
10889 @item @code{GL_ACCUM_BLUE_BITS}
10892 @var{params} returns one value, the number of blue bitplanes in the
10893 accumulation buffer.
10895 @item @code{GL_ACCUM_CLEAR_VALUE}
10898 @var{params} returns four values: the red, green, blue, and alpha values
10899 used to clear the accumulation buffer. Integer values, if requested, are
10900 linearly mapped from the internal floating-point representation such
10901 that 1.0 returns the most positive representable integer value, and
10902 @r{-1.0} returns the most negative representable integer value. The
10903 initial value is (0, 0, 0, 0). See @code{glClearAccum}.
10905 @item @code{GL_ACCUM_GREEN_BITS}
10908 @var{params} returns one value, the number of green bitplanes in the
10909 accumulation buffer.
10911 @item @code{GL_ACCUM_RED_BITS}
10914 @var{params} returns one value, the number of red bitplanes in the
10915 accumulation buffer.
10917 @item @code{GL_ACTIVE_TEXTURE}
10920 @var{params} returns a single value indicating the active multitexture
10921 unit. The initial value is @code{GL_TEXTURE0}. See
10922 @code{glActiveTexture}.
10924 @item @code{GL_ALIASED_POINT_SIZE_RANGE}
10927 @var{params} returns two values, the smallest and largest supported
10928 sizes for aliased points.
10930 @item @code{GL_ALIASED_LINE_WIDTH_RANGE}
10933 @var{params} returns two values, the smallest and largest supported
10934 widths for aliased lines.
10936 @item @code{GL_ALPHA_BIAS}
10939 @var{params} returns one value, the alpha bias factor used during pixel
10940 transfers. The initial value is 0. See @code{glPixelTransfer}.
10942 @item @code{GL_ALPHA_BITS}
10945 @var{params} returns one value, the number of alpha bitplanes in each
10948 @item @code{GL_ALPHA_SCALE}
10951 @var{params} returns one value, the alpha scale factor used during pixel
10952 transfers. The initial value is 1. See @code{glPixelTransfer}.
10954 @item @code{GL_ALPHA_TEST}
10957 @var{params} returns a single boolean value indicating whether alpha
10958 testing of fragments is enabled. The initial value is @code{GL_FALSE}.
10959 See @code{glAlphaFunc}.
10961 @item @code{GL_ALPHA_TEST_FUNC}@var{params} returns one value,
10964 the symbolic name of the alpha test function. The initial value is
10965 @code{GL_ALWAYS}. See @code{glAlphaFunc}.
10967 @item @code{GL_ALPHA_TEST_REF}
10970 @var{params} returns one value, the reference value for the alpha test.
10971 The initial value is 0. See @code{glAlphaFunc}. An integer value, if
10972 requested, is linearly mapped from the internal floating-point
10973 representation such that 1.0 returns the most positive representable
10974 integer value, and @r{-1.0} returns the most negative representable
10977 @item @code{GL_ARRAY_BUFFER_BINDING}
10980 @var{params} returns a single value, the name of the buffer object
10981 currently bound to the target @code{GL_ARRAY_BUFFER}. If no buffer
10982 object is bound to this target, 0 is returned. The initial value is 0.
10983 See @code{glBindBuffer}.
10985 @item @code{GL_ATTRIB_STACK_DEPTH}
10988 @var{params} returns one value, the depth of the attribute stack. If the
10989 stack is empty, 0 is returned. The initial value is 0. See
10990 @code{glPushAttrib}.
10992 @item @code{GL_AUTO_NORMAL}
10995 @var{params} returns a single boolean value indicating whether 2D map
10996 evaluation automatically generates surface normals. The initial value is
10997 @code{GL_FALSE}. See @code{glMap2}.
10999 @item @code{GL_AUX_BUFFERS}
11002 @var{params} returns one value, the number of auxiliary color buffers
11005 @item @code{GL_BLEND}
11008 @var{params} returns a single boolean value indicating whether blending
11009 is enabled. The initial value is @code{GL_FALSE}. See
11010 @code{glBlendFunc}.
11012 @item @code{GL_BLEND_COLOR}
11015 @var{params} returns four values, the red, green, blue, and alpha values
11016 which are the components of the blend color. See @code{glBlendColor}.
11018 @item @code{GL_BLEND_DST_ALPHA}
11021 @var{params} returns one value, the symbolic constant identifying the
11022 alpha destination blend function. The initial value is @code{GL_ZERO}.
11023 See @code{glBlendFunc} and @code{glBlendFuncSeparate}.
11025 @item @code{GL_BLEND_DST_RGB}
11028 @var{params} returns one value, the symbolic constant identifying the
11029 RGB destination blend function. The initial value is @code{GL_ZERO}. See
11030 @code{glBlendFunc} and @code{glBlendFuncSeparate}.
11032 @item @code{GL_BLEND_EQUATION_RGB}
11035 @var{params} returns one value, a symbolic constant indicating whether
11036 the RGB blend equation is @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT},
11037 @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN} or @code{GL_MAX}. See
11038 @code{glBlendEquationSeparate}.
11040 @item @code{GL_BLEND_EQUATION_ALPHA}
11043 @var{params} returns one value, a symbolic constant indicating whether
11044 the Alpha blend equation is @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT},
11045 @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN} or @code{GL_MAX}. See
11046 @code{glBlendEquationSeparate}.
11048 @item @code{GL_BLEND_SRC_ALPHA}
11051 @var{params} returns one value, the symbolic constant identifying the
11052 alpha source blend function. The initial value is @code{GL_ONE}. See
11053 @code{glBlendFunc} and @code{glBlendFuncSeparate}.
11055 @item @code{GL_BLEND_SRC_RGB}
11058 @var{params} returns one value, the symbolic constant identifying the
11059 RGB source blend function. The initial value is @code{GL_ONE}. See
11060 @code{glBlendFunc} and @code{glBlendFuncSeparate}.
11062 @item @code{GL_BLUE_BIAS}
11065 @var{params} returns one value, the blue bias factor used during pixel
11066 transfers. The initial value is 0. See @code{glPixelTransfer}.
11068 @item @code{GL_BLUE_BITS}
11071 @var{params} returns one value, the number of blue bitplanes in each
11074 @item @code{GL_BLUE_SCALE}
11077 @var{params} returns one value, the blue scale factor used during pixel
11078 transfers. The initial value is 1. See @code{glPixelTransfer}.
11080 @item @code{GL_CLIENT_ACTIVE_TEXTURE}
11083 @var{params} returns a single integer value indicating the current
11084 client active multitexture unit. The initial value is
11085 @code{GL_TEXTURE0}. See @code{glClientActiveTexture}.
11087 @item @code{GL_CLIENT_ATTRIB_STACK_DEPTH}
11090 @var{params} returns one value indicating the depth of the attribute
11091 stack. The initial value is 0. See @code{glPushClientAttrib}.
11093 @item @code{GL_CLIP_PLANE}@var{i}
11096 @var{params} returns a single boolean value indicating whether the
11097 specified clipping plane is enabled. The initial value is
11098 @code{GL_FALSE}. See @code{glClipPlane}.
11100 @item @code{GL_COLOR_ARRAY}
11103 @var{params} returns a single boolean value indicating whether the color
11104 array is enabled. The initial value is @code{GL_FALSE}. See
11105 @code{glColorPointer}.
11107 @item @code{GL_COLOR_ARRAY_BUFFER_BINDING}
11110 @var{params} returns a single value, the name of the buffer object
11111 associated with the color array. This buffer object would have been
11112 bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
11113 recent call to @code{glColorPointer}. If no buffer object was bound to
11114 this target, 0 is returned. The initial value is 0. See
11115 @code{glBindBuffer}.
11117 @item @code{GL_COLOR_ARRAY_SIZE}
11120 @var{params} returns one value, the number of components per color in
11121 the color array. The initial value is 4. See @code{glColorPointer}.
11123 @item @code{GL_COLOR_ARRAY_STRIDE}
11126 @var{params} returns one value, the byte offset between consecutive
11127 colors in the color array. The initial value is 0. See
11128 @code{glColorPointer}.
11130 @item @code{GL_COLOR_ARRAY_TYPE}
11133 @var{params} returns one value, the data type of each component in the
11134 color array. The initial value is @code{GL_FLOAT}. See
11135 @code{glColorPointer}.
11137 @item @code{GL_COLOR_CLEAR_VALUE}
11140 @var{params} returns four values: the red, green, blue, and alpha values
11141 used to clear the color buffers. Integer values, if requested, are
11142 linearly mapped from the internal floating-point representation such
11143 that 1.0 returns the most positive representable integer value, and
11144 @r{-1.0} returns the most negative representable integer value. The
11145 initial value is (0, 0, 0, 0). See @code{glClearColor}.
11147 @item @code{GL_COLOR_LOGIC_OP}
11150 @var{params} returns a single boolean value indicating whether a
11151 fragment's RGBA color values are merged into the framebuffer using a
11152 logical operation. The initial value is @code{GL_FALSE}. See
11155 @item @code{GL_COLOR_MATERIAL}
11158 @var{params} returns a single boolean value indicating whether one or
11159 more material parameters are tracking the current color. The initial
11160 value is @code{GL_FALSE}. See @code{glColorMaterial}.
11162 @item @code{GL_COLOR_MATERIAL_FACE}
11165 @var{params} returns one value, a symbolic constant indicating which
11166 materials have a parameter that is tracking the current color. The
11167 initial value is @code{GL_FRONT_AND_BACK}. See @code{glColorMaterial}.
11169 @item @code{GL_COLOR_MATERIAL_PARAMETER}
11172 @var{params} returns one value, a symbolic constant indicating which
11173 material parameters are tracking the current color. The initial value is
11174 @code{GL_AMBIENT_AND_DIFFUSE}. See @code{glColorMaterial}.
11176 @item @code{GL_COLOR_MATRIX}
11179 @var{params} returns sixteen values: the color matrix on the top of the
11180 color matrix stack. Initially this matrix is the identity matrix. See
11181 @code{glPushMatrix}.
11183 @item @code{GL_COLOR_MATRIX_STACK_DEPTH}
11186 @var{params} returns one value, the maximum supported depth of the
11187 projection matrix stack. The value must be at least 2. See
11188 @code{glPushMatrix}.
11190 @item @code{GL_COLOR_SUM}
11193 @var{params} returns a single boolean value indicating whether primary
11194 and secondary color sum is enabled. See @code{glSecondaryColor}.
11196 @item @code{GL_COLOR_TABLE}
11199 @var{params} returns a single boolean value indicating whether the color
11200 table lookup is enabled. See @code{glColorTable}.
11202 @item @code{GL_COLOR_WRITEMASK}
11205 @var{params} returns four boolean values: the red, green, blue, and
11206 alpha write enables for the color buffers. The initial value is
11207 (@code{GL_TRUE}, @code{GL_TRUE}, @code{GL_TRUE}, @code{GL_TRUE}). See
11208 @code{glColorMask}.
11210 @item @code{GL_COMPRESSED_TEXTURE_FORMATS}
11213 @var{params} returns a list of symbolic constants of length
11214 @code{GL_NUM_COMPRESSED_TEXTURE_FORMATS} indicating which compressed
11215 texture formats are available. See @code{glCompressedTexImage2D}.
11217 @item @code{GL_CONVOLUTION_1D}
11220 @var{params} returns a single boolean value indicating whether 1D
11221 convolution is enabled. The initial value is @code{GL_FALSE}. See
11222 @code{glConvolutionFilter1D}.
11224 @item @code{GL_CONVOLUTION_2D}
11227 @var{params} returns a single boolean value indicating whether 2D
11228 convolution is enabled. The initial value is @code{GL_FALSE}. See
11229 @code{glConvolutionFilter2D}.
11231 @item @code{GL_CULL_FACE}
11234 @var{params} returns a single boolean value indicating whether polygon
11235 culling is enabled. The initial value is @code{GL_FALSE}. See
11238 @item @code{GL_CULL_FACE_MODE}
11241 @var{params} returns one value, a symbolic constant indicating which
11242 polygon faces are to be culled. The initial value is @code{GL_BACK}. See
11245 @item @code{GL_CURRENT_COLOR}
11248 @var{params} returns four values: the red, green, blue, and alpha values
11249 of the current color. Integer values, if requested, are linearly mapped
11250 from the internal floating-point representation such that 1.0 returns
11251 the most positive representable integer value, and @r{-1.0} returns the
11252 most negative representable integer value. The initial value is (1, 1,
11253 1, 1). See @code{glColor}.
11255 @item @code{GL_CURRENT_FOG_COORD}
11258 @var{params} returns one value, the current fog coordinate. The initial
11259 value is 0. See @code{glFogCoord}.
11261 @item @code{GL_CURRENT_INDEX}
11264 @var{params} returns one value, the current color index. The initial
11265 value is 1. See @code{glIndex}.
11267 @item @code{GL_CURRENT_NORMAL}
11270 @var{params} returns three values: the @var{x}, @var{y}, and @var{z}
11271 values of the current normal. Integer values, if requested, are linearly
11272 mapped from the internal floating-point representation such that 1.0
11273 returns the most positive representable integer value, and @r{-1.0}
11274 returns the most negative representable integer value. The initial value
11275 is (0, 0, 1). See @code{glNormal}.
11277 @item @code{GL_CURRENT_PROGRAM}
11280 @var{params} returns one value, the name of the program object that is
11281 currently active, or 0 if no program object is active. See
11282 @code{glUseProgram}.
11284 @item @code{GL_CURRENT_RASTER_COLOR}
11287 @var{params} returns four values: the red, green, blue, and alpha color
11288 values of the current raster position. Integer values, if requested, are
11289 linearly mapped from the internal floating-point representation such
11290 that 1.0 returns the most positive representable integer value, and
11291 @r{-1.0} returns the most negative representable integer value. The
11292 initial value is (1, 1, 1, 1). See @code{glRasterPos}.
11294 @item @code{GL_CURRENT_RASTER_DISTANCE}
11297 @var{params} returns one value, the distance from the eye to the current
11298 raster position. The initial value is 0. See @code{glRasterPos}.
11300 @item @code{GL_CURRENT_RASTER_INDEX}
11303 @var{params} returns one value, the color index of the current raster
11304 position. The initial value is 1. See @code{glRasterPos}.
11306 @item @code{GL_CURRENT_RASTER_POSITION}
11309 @var{params} returns four values: the @var{x}, @var{y}, @var{z}, and
11310 @var{w} components of the current raster position. @var{x}, @var{y}, and
11311 @var{z} are in window coordinates, and @var{w} is in clip coordinates.
11312 The initial value is (0, 0, 0, 1). See @code{glRasterPos}.
11314 @item @code{GL_CURRENT_RASTER_POSITION_VALID}
11317 @var{params} returns a single boolean value indicating whether the
11318 current raster position is valid. The initial value is @code{GL_TRUE}.
11319 See @code{glRasterPos}.
11321 @item @code{GL_CURRENT_RASTER_SECONDARY_COLOR}
11324 @var{params} returns four values: the red, green, blue, and alpha
11325 secondary color values of the current raster position. Integer values,
11326 if requested, are linearly mapped from the internal floating-point
11327 representation such that 1.0 returns the most positive representable
11328 integer value, and @r{-1.0} returns the most negative representable
11329 integer value. The initial value is (1, 1, 1, 1). See
11330 @code{glRasterPos}.
11332 @item @code{GL_CURRENT_RASTER_TEXTURE_COORDS}
11335 @var{params} returns four values: the @var{s}, @var{t}, @var{r}, and
11336 @var{q} texture coordinates of the current raster position. The initial
11337 value is (0, 0, 0, 1). See @code{glRasterPos} and
11338 @code{glMultiTexCoord}.
11340 @item @code{GL_CURRENT_SECONDARY_COLOR}
11343 @var{params} returns four values: the red, green, blue, and alpha values
11344 of the current secondary color. Integer values, if requested, are
11345 linearly mapped from the internal floating-point representation such
11346 that 1.0 returns the most positive representable integer value, and
11347 @r{-1.0} returns the most negative representable integer value. The
11348 initial value is (0, 0, 0, 0). See @code{glSecondaryColor}.
11350 @item @code{GL_CURRENT_TEXTURE_COORDS}
11353 @var{params} returns four values: the @var{s}, @var{t}, @var{r}, and
11354 @var{q} current texture coordinates. The initial value is (0, 0, 0, 1).
11355 See @code{glMultiTexCoord}.
11357 @item @code{GL_DEPTH_BIAS}
11360 @var{params} returns one value, the depth bias factor used during pixel
11361 transfers. The initial value is 0. See @code{glPixelTransfer}.
11363 @item @code{GL_DEPTH_BITS}
11366 @var{params} returns one value, the number of bitplanes in the depth
11369 @item @code{GL_DEPTH_CLEAR_VALUE}
11372 @var{params} returns one value, the value that is used to clear the
11373 depth buffer. Integer values, if requested, are linearly mapped from the
11374 internal floating-point representation such that 1.0 returns the most
11375 positive representable integer value, and @r{-1.0} returns the most
11376 negative representable integer value. The initial value is 1. See
11377 @code{glClearDepth}.
11379 @item @code{GL_DEPTH_FUNC}
11382 @var{params} returns one value, the symbolic constant that indicates the
11383 depth comparison function. The initial value is @code{GL_LESS}. See
11384 @code{glDepthFunc}.
11386 @item @code{GL_DEPTH_RANGE}
11389 @var{params} returns two values: the near and far mapping limits for the
11390 depth buffer. Integer values, if requested, are linearly mapped from the
11391 internal floating-point representation such that 1.0 returns the most
11392 positive representable integer value, and @r{-1.0} returns the most
11393 negative representable integer value. The initial value is (0, 1). See
11394 @code{glDepthRange}.
11396 @item @code{GL_DEPTH_SCALE}
11399 @var{params} returns one value, the depth scale factor used during pixel
11400 transfers. The initial value is 1. See @code{glPixelTransfer}.
11402 @item @code{GL_DEPTH_TEST}
11405 @var{params} returns a single boolean value indicating whether depth
11406 testing of fragments is enabled. The initial value is @code{GL_FALSE}.
11407 See @code{glDepthFunc} and @code{glDepthRange}.
11409 @item @code{GL_DEPTH_WRITEMASK}
11412 @var{params} returns a single boolean value indicating if the depth
11413 buffer is enabled for writing. The initial value is @code{GL_TRUE}. See
11414 @code{glDepthMask}.
11416 @item @code{GL_DITHER}
11419 @var{params} returns a single boolean value indicating whether dithering
11420 of fragment colors and indices is enabled. The initial value is
11423 @item @code{GL_DOUBLEBUFFER}
11426 @var{params} returns a single boolean value indicating whether double
11427 buffering is supported.
11429 @item @code{GL_DRAW_BUFFER}
11432 @var{params} returns one value, a symbolic constant indicating which
11433 buffers are being drawn to. See @code{glDrawBuffer}. The initial value
11434 is @code{GL_BACK} if there are back buffers, otherwise it is
11437 @item @code{GL_DRAW_BUFFER}@var{i}
11440 @var{params} returns one value, a symbolic constant indicating which
11441 buffers are being drawn to by the corresponding output color. See
11442 @code{glDrawBuffers}. The initial value of @code{GL_DRAW_BUFFER0} is
11443 @code{GL_BACK} if there are back buffers, otherwise it is
11444 @code{GL_FRONT}. The initial values of draw buffers for all other output
11445 colors is @code{GL_NONE}.
11447 @item @code{GL_EDGE_FLAG}
11450 @var{params} returns a single boolean value indicating whether the
11451 current edge flag is @code{GL_TRUE} or @code{GL_FALSE}. The initial
11452 value is @code{GL_TRUE}. See @code{glEdgeFlag}.
11454 @item @code{GL_EDGE_FLAG_ARRAY}
11457 @var{params} returns a single boolean value indicating whether the edge
11458 flag array is enabled. The initial value is @code{GL_FALSE}. See
11459 @code{glEdgeFlagPointer}.
11461 @item @code{GL_EDGE_FLAG_ARRAY_BUFFER_BINDING}
11464 @var{params} returns a single value, the name of the buffer object
11465 associated with the edge flag array. This buffer object would have been
11466 bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
11467 recent call to @code{glEdgeFlagPointer}. If no buffer object was bound
11468 to this target, 0 is returned. The initial value is 0. See
11469 @code{glBindBuffer}.
11471 @item @code{GL_EDGE_FLAG_ARRAY_STRIDE}
11474 @var{params} returns one value, the byte offset between consecutive edge
11475 flags in the edge flag array. The initial value is 0. See
11476 @code{glEdgeFlagPointer}.
11478 @item @code{GL_ELEMENT_ARRAY_BUFFER_BINDING}
11481 @var{params} returns a single value, the name of the buffer object
11482 currently bound to the target @code{GL_ELEMENT_ARRAY_BUFFER}. If no
11483 buffer object is bound to this target, 0 is returned. The initial value
11484 is 0. See @code{glBindBuffer}.
11486 @item @code{GL_FEEDBACK_BUFFER_SIZE}
11489 @var{params} returns one value, the size of the feedback buffer. See
11490 @code{glFeedbackBuffer}.
11492 @item @code{GL_FEEDBACK_BUFFER_TYPE}
11495 @var{params} returns one value, the type of the feedback buffer. See
11496 @code{glFeedbackBuffer}.
11498 @item @code{GL_FOG}
11501 @var{params} returns a single boolean value indicating whether fogging
11502 is enabled. The initial value is @code{GL_FALSE}. See @code{glFog}.
11504 @item @code{GL_FOG_COORD_ARRAY}
11507 @var{params} returns a single boolean value indicating whether the fog
11508 coordinate array is enabled. The initial value is @code{GL_FALSE}. See
11509 @code{glFogCoordPointer}.
11511 @item @code{GL_FOG_COORD_ARRAY_BUFFER_BINDING}
11514 @var{params} returns a single value, the name of the buffer object
11515 associated with the fog coordinate array. This buffer object would have
11516 been bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
11517 recent call to @code{glFogCoordPointer}. If no buffer object was bound
11518 to this target, 0 is returned. The initial value is 0. See
11519 @code{glBindBuffer}.
11521 @item @code{GL_FOG_COORD_ARRAY_STRIDE}
11524 @var{params} returns one value, the byte offset between consecutive fog
11525 coordinates in the fog coordinate array. The initial value is 0. See
11526 @code{glFogCoordPointer}.
11528 @item @code{GL_FOG_COORD_ARRAY_TYPE}
11531 @var{params} returns one value, the type of the fog coordinate array.
11532 The initial value is @code{GL_FLOAT}. See @code{glFogCoordPointer}.
11534 @item @code{GL_FOG_COORD_SRC}
11537 @var{params} returns one value, a symbolic constant indicating the
11538 source of the fog coordinate. The initial value is
11539 @code{GL_FRAGMENT_DEPTH}. See @code{glFog}.
11541 @item @code{GL_FOG_COLOR}
11544 @var{params} returns four values: the red, green, blue, and alpha
11545 components of the fog color. Integer values, if requested, are linearly
11546 mapped from the internal floating-point representation such that 1.0
11547 returns the most positive representable integer value, and @r{-1.0}
11548 returns the most negative representable integer value. The initial value
11549 is (0, 0, 0, 0). See @code{glFog}.
11551 @item @code{GL_FOG_DENSITY}
11554 @var{params} returns one value, the fog density parameter. The initial
11555 value is 1. See @code{glFog}.
11557 @item @code{GL_FOG_END}
11560 @var{params} returns one value, the end factor for the linear fog
11561 equation. The initial value is 1. See @code{glFog}.
11563 @item @code{GL_FOG_HINT}
11566 @var{params} returns one value, a symbolic constant indicating the mode
11567 of the fog hint. The initial value is @code{GL_DONT_CARE}. See
11570 @item @code{GL_FOG_INDEX}
11573 @var{params} returns one value, the fog color index. The initial value
11574 is 0. See @code{glFog}.
11576 @item @code{GL_FOG_MODE}
11579 @var{params} returns one value, a symbolic constant indicating which fog
11580 equation is selected. The initial value is @code{GL_EXP}. See
11583 @item @code{GL_FOG_START}
11586 @var{params} returns one value, the start factor for the linear fog
11587 equation. The initial value is 0. See @code{glFog}.
11589 @item @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT}
11592 @var{params} returns one value, a symbolic constant indicating the mode
11593 of the derivative accuracy hint for fragment shaders. The initial value
11594 is @code{GL_DONT_CARE}. See @code{glHint}.
11596 @item @code{GL_FRONT_FACE}
11599 @var{params} returns one value, a symbolic constant indicating whether
11600 clockwise or counterclockwise polygon winding is treated as
11601 front-facing. The initial value is @code{GL_CCW}. See
11602 @code{glFrontFace}.
11604 @item @code{GL_GENERATE_MIPMAP_HINT}
11607 @var{params} returns one value, a symbolic constant indicating the mode
11608 of the mipmap generation filtering hint. The initial value is
11609 @code{GL_DONT_CARE}. See @code{glHint}.
11611 @item @code{GL_GREEN_BIAS}
11614 @var{params} returns one value, the green bias factor used during pixel
11615 transfers. The initial value is 0.
11617 @item @code{GL_GREEN_BITS}
11620 @var{params} returns one value, the number of green bitplanes in each
11623 @item @code{GL_GREEN_SCALE}
11626 @var{params} returns one value, the green scale factor used during pixel
11627 transfers. The initial value is 1. See @code{glPixelTransfer}.
11629 @item @code{GL_HISTOGRAM}
11632 @var{params} returns a single boolean value indicating whether histogram
11633 is enabled. The initial value is @code{GL_FALSE}. See
11634 @code{glHistogram}.
11636 @item @code{GL_INDEX_ARRAY}
11639 @var{params} returns a single boolean value indicating whether the color
11640 index array is enabled. The initial value is @code{GL_FALSE}. See
11641 @code{glIndexPointer}.
11643 @item @code{GL_INDEX_ARRAY_BUFFER_BINDING}
11646 @var{params} returns a single value, the name of the buffer object
11647 associated with the color index array. This buffer object would have
11648 been bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
11649 recent call to @code{glIndexPointer}. If no buffer object was bound to
11650 this target, 0 is returned. The initial value is 0. See
11651 @code{glBindBuffer}.
11653 @item @code{GL_INDEX_ARRAY_STRIDE}
11656 @var{params} returns one value, the byte offset between consecutive
11657 color indexes in the color index array. The initial value is 0. See
11658 @code{glIndexPointer}.
11660 @item @code{GL_INDEX_ARRAY_TYPE}
11663 @var{params} returns one value, the data type of indexes in the color
11664 index array. The initial value is @code{GL_FLOAT}. See
11665 @code{glIndexPointer}.
11667 @item @code{GL_INDEX_BITS}
11670 @var{params} returns one value, the number of bitplanes in each color
11673 @item @code{GL_INDEX_CLEAR_VALUE}
11676 @var{params} returns one value, the color index used to clear the color
11677 index buffers. The initial value is 0. See @code{glClearIndex}.
11679 @item @code{GL_INDEX_LOGIC_OP}
11682 @var{params} returns a single boolean value indicating whether a
11683 fragment's index values are merged into the framebuffer using a logical
11684 operation. The initial value is @code{GL_FALSE}. See @code{glLogicOp}.
11686 @item @code{GL_INDEX_MODE}
11689 @var{params} returns a single boolean value indicating whether the GL is
11690 in color index mode (@code{GL_TRUE}) or RGBA mode (@code{GL_FALSE}).
11692 @item @code{GL_INDEX_OFFSET}
11695 @var{params} returns one value, the offset added to color and stencil
11696 indices during pixel transfers. The initial value is 0. See
11697 @code{glPixelTransfer}.
11699 @item @code{GL_INDEX_SHIFT}
11702 @var{params} returns one value, the amount that color and stencil
11703 indices are shifted during pixel transfers. The initial value is 0. See
11704 @code{glPixelTransfer}.
11706 @item @code{GL_INDEX_WRITEMASK}
11709 @var{params} returns one value, a mask indicating which bitplanes of
11710 each color index buffer can be written. The initial value is all 1's.
11711 See @code{glIndexMask}.
11713 @item @code{GL_LIGHT}@var{i}
11716 @var{params} returns a single boolean value indicating whether the
11717 specified light is enabled. The initial value is @code{GL_FALSE}. See
11718 @code{glLight} and @code{glLightModel}.
11720 @item @code{GL_LIGHTING}
11723 @var{params} returns a single boolean value indicating whether lighting
11724 is enabled. The initial value is @code{GL_FALSE}. See
11725 @code{glLightModel}.
11727 @item @code{GL_LIGHT_MODEL_AMBIENT}
11730 @var{params} returns four values: the red, green, blue, and alpha
11731 components of the ambient intensity of the entire scene. Integer values,
11732 if requested, are linearly mapped from the internal floating-point
11733 representation such that 1.0 returns the most positive representable
11734 integer value, and @r{-1.0} returns the most negative representable
11735 integer value. The initial value is (0.2, 0.2, 0.2, 1.0). See
11736 @code{glLightModel}.
11738 @item @code{GL_LIGHT_MODEL_COLOR_CONTROL}
11741 @var{params} returns single enumerated value indicating whether specular
11742 reflection calculations are separated from normal lighting computations.
11743 The initial value is @code{GL_SINGLE_COLOR}.
11745 @item @code{GL_LIGHT_MODEL_LOCAL_VIEWER}
11748 @var{params} returns a single boolean value indicating whether specular
11749 reflection calculations treat the viewer as being local to the scene.
11750 The initial value is @code{GL_FALSE}. See @code{glLightModel}.
11752 @item @code{GL_LIGHT_MODEL_TWO_SIDE}
11755 @var{params} returns a single boolean value indicating whether separate
11756 materials are used to compute lighting for front- and back-facing
11757 polygons. The initial value is @code{GL_FALSE}. See @code{glLightModel}.
11759 @item @code{GL_LINE_SMOOTH}
11762 @var{params} returns a single boolean value indicating whether
11763 antialiasing of lines is enabled. The initial value is @code{GL_FALSE}.
11764 See @code{glLineWidth}.
11766 @item @code{GL_LINE_SMOOTH_HINT}
11769 @var{params} returns one value, a symbolic constant indicating the mode
11770 of the line antialiasing hint. The initial value is @code{GL_DONT_CARE}.
11773 @item @code{GL_LINE_STIPPLE}
11776 @var{params} returns a single boolean value indicating whether stippling
11777 of lines is enabled. The initial value is @code{GL_FALSE}. See
11778 @code{glLineStipple}.
11780 @item @code{GL_LINE_STIPPLE_PATTERN}
11783 @var{params} returns one value, the 16-bit line stipple pattern. The
11784 initial value is all 1's. See @code{glLineStipple}.
11786 @item @code{GL_LINE_STIPPLE_REPEAT}
11789 @var{params} returns one value, the line stipple repeat factor. The
11790 initial value is 1. See @code{glLineStipple}.
11792 @item @code{GL_LINE_WIDTH}
11795 @var{params} returns one value, the line width as specified with
11796 @code{glLineWidth}. The initial value is 1.
11798 @item @code{GL_LINE_WIDTH_GRANULARITY}
11801 @var{params} returns one value, the width difference between adjacent
11802 supported widths for antialiased lines. See @code{glLineWidth}.
11804 @item @code{GL_LINE_WIDTH_RANGE}
11807 @var{params} returns two values: the smallest and largest supported
11808 widths for antialiased lines. See @code{glLineWidth}.
11810 @item @code{GL_LIST_BASE}
11813 @var{params} returns one value, the base offset added to all names in
11814 arrays presented to @code{glCallLists}. The initial value is 0. See
11817 @item @code{GL_LIST_INDEX}
11820 @var{params} returns one value, the name of the display list currently
11821 under construction. 0 is returned if no display list is currently under
11822 construction. The initial value is 0. See @code{glNewList}.
11824 @item @code{GL_LIST_MODE}
11827 @var{params} returns one value, a symbolic constant indicating the
11828 construction mode of the display list currently under construction. The
11829 initial value is 0. See @code{glNewList}.
11831 @item @code{GL_LOGIC_OP_MODE}
11834 @var{params} returns one value, a symbolic constant indicating the
11835 selected logic operation mode. The initial value is @code{GL_COPY}. See
11838 @item @code{GL_MAP1_COLOR_4}
11841 @var{params} returns a single boolean value indicating whether 1D
11842 evaluation generates colors. The initial value is @code{GL_FALSE}. See
11845 @item @code{GL_MAP1_GRID_DOMAIN}
11848 @var{params} returns two values: the endpoints of the 1D map's grid
11849 domain. The initial value is (0, 1). See @code{glMapGrid}.
11851 @item @code{GL_MAP1_GRID_SEGMENTS}
11854 @var{params} returns one value, the number of partitions in the 1D map's
11855 grid domain. The initial value is 1. See @code{glMapGrid}.
11857 @item @code{GL_MAP1_INDEX}
11860 @var{params} returns a single boolean value indicating whether 1D
11861 evaluation generates color indices. The initial value is
11862 @code{GL_FALSE}. See @code{glMap1}.
11864 @item @code{GL_MAP1_NORMAL}
11867 @var{params} returns a single boolean value indicating whether 1D
11868 evaluation generates normals. The initial value is @code{GL_FALSE}. See
11871 @item @code{GL_MAP1_TEXTURE_COORD_1}
11874 @var{params} returns a single boolean value indicating whether 1D
11875 evaluation generates 1D texture coordinates. The initial value is
11876 @code{GL_FALSE}. See @code{glMap1}.
11878 @item @code{GL_MAP1_TEXTURE_COORD_2}
11881 @var{params} returns a single boolean value indicating whether 1D
11882 evaluation generates 2D texture coordinates. The initial value is
11883 @code{GL_FALSE}. See @code{glMap1}.
11885 @item @code{GL_MAP1_TEXTURE_COORD_3}
11888 @var{params} returns a single boolean value indicating whether 1D
11889 evaluation generates 3D texture coordinates. The initial value is
11890 @code{GL_FALSE}. See @code{glMap1}.
11892 @item @code{GL_MAP1_TEXTURE_COORD_4}
11895 @var{params} returns a single boolean value indicating whether 1D
11896 evaluation generates 4D texture coordinates. The initial value is
11897 @code{GL_FALSE}. See @code{glMap1}.
11899 @item @code{GL_MAP1_VERTEX_3}
11902 @var{params} returns a single boolean value indicating whether 1D
11903 evaluation generates 3D vertex coordinates. The initial value is
11904 @code{GL_FALSE}. See @code{glMap1}.
11906 @item @code{GL_MAP1_VERTEX_4}
11909 @var{params} returns a single boolean value indicating whether 1D
11910 evaluation generates 4D vertex coordinates. The initial value is
11911 @code{GL_FALSE}. See @code{glMap1}.
11913 @item @code{GL_MAP2_COLOR_4}
11916 @var{params} returns a single boolean value indicating whether 2D
11917 evaluation generates colors. The initial value is @code{GL_FALSE}. See
11920 @item @code{GL_MAP2_GRID_DOMAIN}
11923 @var{params} returns four values: the endpoints of the 2D map's
11924 @r{@var{i}} and @r{@var{j}} grid domains. The initial value is (0,1;
11925 0,1). See @code{glMapGrid}.
11927 @item @code{GL_MAP2_GRID_SEGMENTS}
11930 @var{params} returns two values: the number of partitions in the 2D
11931 map's @r{@var{i}} and @r{@var{j}} grid domains. The initial value is
11932 (1,1). See @code{glMapGrid}.
11934 @item @code{GL_MAP2_INDEX}
11937 @var{params} returns a single boolean value indicating whether 2D
11938 evaluation generates color indices. The initial value is
11939 @code{GL_FALSE}. See @code{glMap2}.
11941 @item @code{GL_MAP2_NORMAL}
11944 @var{params} returns a single boolean value indicating whether 2D
11945 evaluation generates normals. The initial value is @code{GL_FALSE}. See
11948 @item @code{GL_MAP2_TEXTURE_COORD_1}
11951 @var{params} returns a single boolean value indicating whether 2D
11952 evaluation generates 1D texture coordinates. The initial value is
11953 @code{GL_FALSE}. See @code{glMap2}.
11955 @item @code{GL_MAP2_TEXTURE_COORD_2}
11958 @var{params} returns a single boolean value indicating whether 2D
11959 evaluation generates 2D texture coordinates. The initial value is
11960 @code{GL_FALSE}. See @code{glMap2}.
11962 @item @code{GL_MAP2_TEXTURE_COORD_3}
11965 @var{params} returns a single boolean value indicating whether 2D
11966 evaluation generates 3D texture coordinates. The initial value is
11967 @code{GL_FALSE}. See @code{glMap2}.
11969 @item @code{GL_MAP2_TEXTURE_COORD_4}
11972 @var{params} returns a single boolean value indicating whether 2D
11973 evaluation generates 4D texture coordinates. The initial value is
11974 @code{GL_FALSE}. See @code{glMap2}.
11976 @item @code{GL_MAP2_VERTEX_3}
11979 @var{params} returns a single boolean value indicating whether 2D
11980 evaluation generates 3D vertex coordinates. The initial value is
11981 @code{GL_FALSE}. See @code{glMap2}.
11983 @item @code{GL_MAP2_VERTEX_4}
11986 @var{params} returns a single boolean value indicating whether 2D
11987 evaluation generates 4D vertex coordinates. The initial value is
11988 @code{GL_FALSE}. See @code{glMap2}.
11990 @item @code{GL_MAP_COLOR}
11993 @var{params} returns a single boolean value indicating if colors and
11994 color indices are to be replaced by table lookup during pixel transfers.
11995 The initial value is @code{GL_FALSE}. See @code{glPixelTransfer}.
11997 @item @code{GL_MAP_STENCIL}
12000 @var{params} returns a single boolean value indicating if stencil
12001 indices are to be replaced by table lookup during pixel transfers. The
12002 initial value is @code{GL_FALSE}. See @code{glPixelTransfer}.
12004 @item @code{GL_MATRIX_MODE}
12007 @var{params} returns one value, a symbolic constant indicating which
12008 matrix stack is currently the target of all matrix operations. The
12009 initial value is @code{GL_MODELVIEW}. See @code{glMatrixMode}.
12011 @item @code{GL_MAX_3D_TEXTURE_SIZE}
12014 @var{params} returns one value, a rough estimate of the largest 3D
12015 texture that the GL can handle. The value must be at least 16. If the GL
12016 version is 1.2 or greater, use @code{GL_PROXY_TEXTURE_3D} to determine
12017 if a texture is too large. See @code{glTexImage3D}.
12019 @item @code{GL_MAX_CLIENT_ATTRIB_STACK_DEPTH}
12022 @var{params} returns one value indicating the maximum supported depth of
12023 the client attribute stack. See @code{glPushClientAttrib}.
12025 @item @code{GL_MAX_ATTRIB_STACK_DEPTH}
12028 @var{params} returns one value, the maximum supported depth of the
12029 attribute stack. The value must be at least 16. See @code{glPushAttrib}.
12031 @item @code{GL_MAX_CLIP_PLANES}
12034 @var{params} returns one value, the maximum number of
12035 application-defined clipping planes. The value must be at least 6. See
12036 @code{glClipPlane}.
12038 @item @code{GL_MAX_COLOR_MATRIX_STACK_DEPTH}
12041 @var{params} returns one value, the maximum supported depth of the color
12042 matrix stack. The value must be at least 2. See @code{glPushMatrix}.
12044 @item @code{GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS}
12047 @var{params} returns one value, the maximum supported texture image
12048 units that can be used to access texture maps from the vertex shader and
12049 the fragment processor combined. If both the vertex shader and the
12050 fragment processing stage access the same texture image unit, then that
12051 counts as using two texture image units against this limit. The value
12052 must be at least 2. See @code{glActiveTexture}.
12054 @item @code{GL_MAX_CUBE_MAP_TEXTURE_SIZE}
12057 @var{params} returns one value. The value gives a rough estimate of the
12058 largest cube-map texture that the GL can handle. The value must be at
12059 least 16. If the GL version is 1.3 or greater, use
12060 @code{GL_PROXY_TEXTURE_CUBE_MAP} to determine if a texture is too large.
12061 See @code{glTexImage2D}.
12063 @item @code{GL_MAX_DRAW_BUFFERS}
12066 @var{params} returns one value, the maximum number of simultaneous
12067 output colors allowed from a fragment shader using the
12068 @code{gl_FragData} built-in array. The value must be at least 1. See
12069 @code{glDrawBuffers}.
12071 @item @code{GL_MAX_ELEMENTS_INDICES}
12074 @var{params} returns one value, the recommended maximum number of vertex
12075 array indices. See @code{glDrawRangeElements}.
12077 @item @code{GL_MAX_ELEMENTS_VERTICES}
12080 @var{params} returns one value, the recommended maximum number of vertex
12081 array vertices. See @code{glDrawRangeElements}.
12083 @item @code{GL_MAX_EVAL_ORDER}
12086 @var{params} returns one value, the maximum equation order supported by
12087 1D and 2D evaluators. The value must be at least 8. See @code{glMap1}
12090 @item @code{GL_MAX_FRAGMENT_UNIFORM_COMPONENTS}
12093 @var{params} returns one value, the maximum number of individual
12094 floating-point, integer, or boolean values that can be held in uniform
12095 variable storage for a fragment shader. The value must be at least 64.
12096 See @code{glUniform}.
12098 @item @code{GL_MAX_LIGHTS}
12101 @var{params} returns one value, the maximum number of lights. The value
12102 must be at least 8. See @code{glLight}.
12104 @item @code{GL_MAX_LIST_NESTING}
12107 @var{params} returns one value, the maximum recursion depth allowed
12108 during display-list traversal. The value must be at least 64. See
12111 @item @code{GL_MAX_MODELVIEW_STACK_DEPTH}
12114 @var{params} returns one value, the maximum supported depth of the
12115 modelview matrix stack. The value must be at least 32. See
12116 @code{glPushMatrix}.
12118 @item @code{GL_MAX_NAME_STACK_DEPTH}
12121 @var{params} returns one value, the maximum supported depth of the
12122 selection name stack. The value must be at least 64. See
12125 @item @code{GL_MAX_PIXEL_MAP_TABLE}
12128 @var{params} returns one value, the maximum supported size of a
12129 @code{glPixelMap} lookup table. The value must be at least 32. See
12132 @item @code{GL_MAX_PROJECTION_STACK_DEPTH}
12135 @var{params} returns one value, the maximum supported depth of the
12136 projection matrix stack. The value must be at least 2. See
12137 @code{glPushMatrix}.
12139 @item @code{GL_MAX_TEXTURE_COORDS}
12142 @var{params} returns one value, the maximum number of texture coordinate
12143 sets available to vertex and fragment shaders. The value must be at
12144 least 2. See @code{glActiveTexture} and @code{glClientActiveTexture}.
12146 @item @code{GL_MAX_TEXTURE_IMAGE_UNITS}
12149 @var{params} returns one value, the maximum supported texture image
12150 units that can be used to access texture maps from the fragment shader.
12151 The value must be at least 2. See @code{glActiveTexture}.
12153 @item @code{GL_MAX_TEXTURE_LOD_BIAS}
12156 @var{params} returns one value, the maximum, absolute value of the
12157 texture level-of-detail bias. The value must be at least 4.
12159 @item @code{GL_MAX_TEXTURE_SIZE}
12162 @var{params} returns one value. The value gives a rough estimate of the
12163 largest texture that the GL can handle. The value must be at least 64.
12164 If the GL version is 1.1 or greater, use @code{GL_PROXY_TEXTURE_1D} or
12165 @code{GL_PROXY_TEXTURE_2D} to determine if a texture is too large. See
12166 @code{glTexImage1D} and @code{glTexImage2D}.
12168 @item @code{GL_MAX_TEXTURE_STACK_DEPTH}
12171 @var{params} returns one value, the maximum supported depth of the
12172 texture matrix stack. The value must be at least 2. See
12173 @code{glPushMatrix}.
12175 @item @code{GL_MAX_TEXTURE_UNITS}
12178 @var{params} returns a single value indicating the number of
12179 conventional texture units supported. Each conventional texture unit
12180 includes both a texture coordinate set and a texture image unit.
12181 Conventional texture units may be used for fixed-function (non-shader)
12182 rendering. The value must be at least 2. Additional texture coordinate
12183 sets and texture image units may be accessed from vertex and fragment
12184 shaders. See @code{glActiveTexture} and @code{glClientActiveTexture}.
12186 @item @code{GL_MAX_VARYING_FLOATS}
12189 @var{params} returns one value, the maximum number of interpolators
12190 available for processing varying variables used by vertex and fragment
12191 shaders. This value represents the number of individual floating-point
12192 values that can be interpolated; varying variables declared as vectors,
12193 matrices, and arrays will all consume multiple interpolators. The value
12194 must be at least 32.
12196 @item @code{GL_MAX_VERTEX_ATTRIBS}
12199 @var{params} returns one value, the maximum number of 4-component
12200 generic vertex attributes accessible to a vertex shader. The value must
12201 be at least 16. See @code{glVertexAttrib}.
12203 @item @code{GL_MAX_VERTEX_TEXTURE_IMAGE_UNITS}
12206 @var{params} returns one value, the maximum supported texture image
12207 units that can be used to access texture maps from the vertex shader.
12208 The value may be 0. See @code{glActiveTexture}.
12210 @item @code{GL_MAX_VERTEX_UNIFORM_COMPONENTS}
12213 @var{params} returns one value, the maximum number of individual
12214 floating-point, integer, or boolean values that can be held in uniform
12215 variable storage for a vertex shader. The value must be at least 512.
12216 See @code{glUniform}.
12218 @item @code{GL_MAX_VIEWPORT_DIMS}
12221 @var{params} returns two values: the maximum supported width and height
12222 of the viewport. These must be at least as large as the visible
12223 dimensions of the display being rendered to. See @code{glViewport}.
12225 @item @code{GL_MINMAX}
12228 @var{params} returns a single boolean value indicating whether pixel
12229 minmax values are computed. The initial value is @code{GL_FALSE}. See
12232 @item @code{GL_MODELVIEW_MATRIX}
12235 @var{params} returns sixteen values: the modelview matrix on the top of
12236 the modelview matrix stack. Initially this matrix is the identity
12237 matrix. See @code{glPushMatrix}.
12239 @item @code{GL_MODELVIEW_STACK_DEPTH}
12242 @var{params} returns one value, the number of matrices on the modelview
12243 matrix stack. The initial value is 1. See @code{glPushMatrix}.
12245 @item @code{GL_NAME_STACK_DEPTH}
12248 @var{params} returns one value, the number of names on the selection
12249 name stack. The initial value is 0. See @code{glPushName}.
12251 @item @code{GL_NORMAL_ARRAY}
12254 @var{params} returns a single boolean value, indicating whether the
12255 normal array is enabled. The initial value is @code{GL_FALSE}. See
12256 @code{glNormalPointer}.
12258 @item @code{GL_NORMAL_ARRAY_BUFFER_BINDING}
12261 @var{params} returns a single value, the name of the buffer object
12262 associated with the normal array. This buffer object would have been
12263 bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
12264 recent call to @code{glNormalPointer}. If no buffer object was bound to
12265 this target, 0 is returned. The initial value is 0. See
12266 @code{glBindBuffer}.
12268 @item @code{GL_NORMAL_ARRAY_STRIDE}
12271 @var{params} returns one value, the byte offset between consecutive
12272 normals in the normal array. The initial value is 0. See
12273 @code{glNormalPointer}.
12275 @item @code{GL_NORMAL_ARRAY_TYPE}
12278 @var{params} returns one value, the data type of each coordinate in the
12279 normal array. The initial value is @code{GL_FLOAT}. See
12280 @code{glNormalPointer}.
12282 @item @code{GL_NORMALIZE}
12285 @var{params} returns a single boolean value indicating whether normals
12286 are automatically scaled to unit length after they have been transformed
12287 to eye coordinates. The initial value is @code{GL_FALSE}. See
12290 @item @code{GL_NUM_COMPRESSED_TEXTURE_FORMATS}
12293 @var{params} returns a single integer value indicating the number of
12294 available compressed texture formats. The minimum value is 0. See
12295 @code{glCompressedTexImage2D}.
12297 @item @code{GL_PACK_ALIGNMENT}
12300 @var{params} returns one value, the byte alignment used for writing
12301 pixel data to memory. The initial value is 4. See @code{glPixelStore}.
12303 @item @code{GL_PACK_IMAGE_HEIGHT}
12306 @var{params} returns one value, the image height used for writing pixel
12307 data to memory. The initial value is 0. See @code{glPixelStore}.
12309 @item @code{GL_PACK_LSB_FIRST}
12312 @var{params} returns a single boolean value indicating whether
12313 single-bit pixels being written to memory are written first to the least
12314 significant bit of each unsigned byte. The initial value is
12315 @code{GL_FALSE}. See @code{glPixelStore}.
12317 @item @code{GL_PACK_ROW_LENGTH}
12320 @var{params} returns one value, the row length used for writing pixel
12321 data to memory. The initial value is 0. See @code{glPixelStore}.
12323 @item @code{GL_PACK_SKIP_IMAGES}
12326 @var{params} returns one value, the number of pixel images skipped
12327 before the first pixel is written into memory. The initial value is 0.
12328 See @code{glPixelStore}.
12330 @item @code{GL_PACK_SKIP_PIXELS}
12333 @var{params} returns one value, the number of pixel locations skipped
12334 before the first pixel is written into memory. The initial value is 0.
12335 See @code{glPixelStore}.
12337 @item @code{GL_PACK_SKIP_ROWS}
12340 @var{params} returns one value, the number of rows of pixel locations
12341 skipped before the first pixel is written into memory. The initial value
12342 is 0. See @code{glPixelStore}.
12344 @item @code{GL_PACK_SWAP_BYTES}
12347 @var{params} returns a single boolean value indicating whether the bytes
12348 of two-byte and four-byte pixel indices and components are swapped
12349 before being written to memory. The initial value is @code{GL_FALSE}.
12350 See @code{glPixelStore}.
12352 @item @code{GL_PERSPECTIVE_CORRECTION_HINT}
12355 @var{params} returns one value, a symbolic constant indicating the mode
12356 of the perspective correction hint. The initial value is
12357 @code{GL_DONT_CARE}. See @code{glHint}.
12359 @item @code{GL_PIXEL_MAP_A_TO_A_SIZE}
12362 @var{params} returns one value, the size of the alpha-to-alpha pixel
12363 translation table. The initial value is 1. See @code{glPixelMap}.
12365 @item @code{GL_PIXEL_MAP_B_TO_B_SIZE}
12368 @var{params} returns one value, the size of the blue-to-blue pixel
12369 translation table. The initial value is 1. See @code{glPixelMap}.
12371 @item @code{GL_PIXEL_MAP_G_TO_G_SIZE}
12374 @var{params} returns one value, the size of the green-to-green pixel
12375 translation table. The initial value is 1. See @code{glPixelMap}.
12377 @item @code{GL_PIXEL_MAP_I_TO_A_SIZE}
12380 @var{params} returns one value, the size of the index-to-alpha pixel
12381 translation table. The initial value is 1. See @code{glPixelMap}.
12383 @item @code{GL_PIXEL_MAP_I_TO_B_SIZE}
12386 @var{params} returns one value, the size of the index-to-blue pixel
12387 translation table. The initial value is 1. See @code{glPixelMap}.
12389 @item @code{GL_PIXEL_MAP_I_TO_G_SIZE}
12392 @var{params} returns one value, the size of the index-to-green pixel
12393 translation table. The initial value is 1. See @code{glPixelMap}.
12395 @item @code{GL_PIXEL_MAP_I_TO_I_SIZE}
12398 @var{params} returns one value, the size of the index-to-index pixel
12399 translation table. The initial value is 1. See @code{glPixelMap}.
12401 @item @code{GL_PIXEL_MAP_I_TO_R_SIZE}
12404 @var{params} returns one value, the size of the index-to-red pixel
12405 translation table. The initial value is 1. See @code{glPixelMap}.
12407 @item @code{GL_PIXEL_MAP_R_TO_R_SIZE}
12410 @var{params} returns one value, the size of the red-to-red pixel
12411 translation table. The initial value is 1. See @code{glPixelMap}.
12413 @item @code{GL_PIXEL_MAP_S_TO_S_SIZE}
12416 @var{params} returns one value, the size of the stencil-to-stencil pixel
12417 translation table. The initial value is 1. See @code{glPixelMap}.
12419 @item @code{GL_PIXEL_PACK_BUFFER_BINDING}
12422 @var{params} returns a single value, the name of the buffer object
12423 currently bound to the target @code{GL_PIXEL_PACK_BUFFER}. If no buffer
12424 object is bound to this target, 0 is returned. The initial value is 0.
12425 See @code{glBindBuffer}.
12427 @item @code{GL_PIXEL_UNPACK_BUFFER_BINDING}
12430 @var{params} returns a single value, the name of the buffer object
12431 currently bound to the target @code{GL_PIXEL_UNPACK_BUFFER}. If no
12432 buffer object is bound to this target, 0 is returned. The initial value
12433 is 0. See @code{glBindBuffer}.
12435 @item @code{GL_POINT_DISTANCE_ATTENUATION}
12438 @var{params} returns three values, the coefficients for computing the
12439 attenuation value for points. See @code{glPointParameter}.
12441 @item @code{GL_POINT_FADE_THRESHOLD_SIZE}
12444 @var{params} returns one value, the point size threshold for determining
12445 the point size. See @code{glPointParameter}.
12447 @item @code{GL_POINT_SIZE}
12450 @var{params} returns one value, the point size as specified by
12451 @code{glPointSize}. The initial value is 1.
12453 @item @code{GL_POINT_SIZE_GRANULARITY}
12456 @var{params} returns one value, the size difference between adjacent
12457 supported sizes for antialiased points. See @code{glPointSize}.
12459 @item @code{GL_POINT_SIZE_MAX}
12462 @var{params} returns one value, the upper bound for the attenuated point
12463 sizes. The initial value is 0.0. See @code{glPointParameter}.
12465 @item @code{GL_POINT_SIZE_MIN}
12468 @var{params} returns one value, the lower bound for the attenuated point
12469 sizes. The initial value is 1.0. See @code{glPointParameter}.
12471 @item @code{GL_POINT_SIZE_RANGE}
12474 @var{params} returns two values: the smallest and largest supported
12475 sizes for antialiased points. The smallest size must be at most 1, and
12476 the largest size must be at least 1. See @code{glPointSize}.
12478 @item @code{GL_POINT_SMOOTH}
12481 @var{params} returns a single boolean value indicating whether
12482 antialiasing of points is enabled. The initial value is @code{GL_FALSE}.
12483 See @code{glPointSize}.
12485 @item @code{GL_POINT_SMOOTH_HINT}
12488 @var{params} returns one value, a symbolic constant indicating the mode
12489 of the point antialiasing hint. The initial value is
12490 @code{GL_DONT_CARE}. See @code{glHint}.
12492 @item @code{GL_POINT_SPRITE}
12495 @var{params} returns a single boolean value indicating whether point
12496 sprite is enabled. The initial value is @code{GL_FALSE}.
12498 @item @code{GL_POLYGON_MODE}
12501 @var{params} returns two values: symbolic constants indicating whether
12502 front-facing and back-facing polygons are rasterized as points, lines,
12503 or filled polygons. The initial value is @code{GL_FILL}. See
12504 @code{glPolygonMode}.
12506 @item @code{GL_POLYGON_OFFSET_FACTOR}
12509 @var{params} returns one value, the scaling factor used to determine the
12510 variable offset that is added to the depth value of each fragment
12511 generated when a polygon is rasterized. The initial value is 0. See
12512 @code{glPolygonOffset}.
12514 @item @code{GL_POLYGON_OFFSET_UNITS}
12517 @var{params} returns one value. This value is multiplied by an
12518 implementation-specific value and then added to the depth value of each
12519 fragment generated when a polygon is rasterized. The initial value is 0.
12520 See @code{glPolygonOffset}.
12522 @item @code{GL_POLYGON_OFFSET_FILL}
12525 @var{params} returns a single boolean value indicating whether polygon
12526 offset is enabled for polygons in fill mode. The initial value is
12527 @code{GL_FALSE}. See @code{glPolygonOffset}.
12529 @item @code{GL_POLYGON_OFFSET_LINE}
12532 @var{params} returns a single boolean value indicating whether polygon
12533 offset is enabled for polygons in line mode. The initial value is
12534 @code{GL_FALSE}. See @code{glPolygonOffset}.
12536 @item @code{GL_POLYGON_OFFSET_POINT}
12539 @var{params} returns a single boolean value indicating whether polygon
12540 offset is enabled for polygons in point mode. The initial value is
12541 @code{GL_FALSE}. See @code{glPolygonOffset}.
12543 @item @code{GL_POLYGON_SMOOTH}
12546 @var{params} returns a single boolean value indicating whether
12547 antialiasing of polygons is enabled. The initial value is
12548 @code{GL_FALSE}. See @code{glPolygonMode}.
12550 @item @code{GL_POLYGON_SMOOTH_HINT}
12553 @var{params} returns one value, a symbolic constant indicating the mode
12554 of the polygon antialiasing hint. The initial value is
12555 @code{GL_DONT_CARE}. See @code{glHint}.
12557 @item @code{GL_POLYGON_STIPPLE}
12560 @var{params} returns a single boolean value indicating whether polygon
12561 stippling is enabled. The initial value is @code{GL_FALSE}. See
12562 @code{glPolygonStipple}.
12564 @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}
12567 @var{params} returns a single boolean value indicating whether post
12568 color matrix transformation lookup is enabled. The initial value is
12569 @code{GL_FALSE}. See @code{glColorTable}.
12571 @item @code{GL_POST_COLOR_MATRIX_RED_BIAS}
12574 @var{params} returns one value, the red bias factor applied to RGBA
12575 fragments after color matrix transformations. The initial value is 0.
12576 See @code{glPixelTransfer}.
12578 @item @code{GL_POST_COLOR_MATRIX_GREEN_BIAS}
12581 @var{params} returns one value, the green bias factor applied to RGBA
12582 fragments after color matrix transformations. The initial value is 0.
12583 See @code{glPixelTransfer}
12585 @item @code{GL_POST_COLOR_MATRIX_BLUE_BIAS}
12588 @var{params} returns one value, the blue bias factor applied to RGBA
12589 fragments after color matrix transformations. The initial value is 0.
12590 See @code{glPixelTransfer}.
12592 @item @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS}
12595 @var{params} returns one value, the alpha bias factor applied to RGBA
12596 fragments after color matrix transformations. The initial value is 0.
12597 See @code{glPixelTransfer}.
12599 @item @code{GL_POST_COLOR_MATRIX_RED_SCALE}
12602 @var{params} returns one value, the red scale factor applied to RGBA
12603 fragments after color matrix transformations. The initial value is 1.
12604 See @code{glPixelTransfer}.
12606 @item @code{GL_POST_COLOR_MATRIX_GREEN_SCALE}
12609 @var{params} returns one value, the green scale factor applied to RGBA
12610 fragments after color matrix transformations. The initial value is 1.
12611 See @code{glPixelTransfer}.
12613 @item @code{GL_POST_COLOR_MATRIX_BLUE_SCALE}
12616 @var{params} returns one value, the blue scale factor applied to RGBA
12617 fragments after color matrix transformations. The initial value is 1.
12618 See @code{glPixelTransfer}.
12620 @item @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE}
12623 @var{params} returns one value, the alpha scale factor applied to RGBA
12624 fragments after color matrix transformations. The initial value is 1.
12625 See @code{glPixelTransfer}.
12627 @item @code{GL_POST_CONVOLUTION_COLOR_TABLE}
12630 @var{params} returns a single boolean value indicating whether post
12631 convolution lookup is enabled. The initial value is @code{GL_FALSE}. See
12632 @code{glColorTable}.
12634 @item @code{GL_POST_CONVOLUTION_RED_BIAS}
12637 @var{params} returns one value, the red bias factor applied to RGBA
12638 fragments after convolution. The initial value is 0. See
12639 @code{glPixelTransfer}.
12641 @item @code{GL_POST_CONVOLUTION_GREEN_BIAS}
12644 @var{params} returns one value, the green bias factor applied to RGBA
12645 fragments after convolution. The initial value is 0. See
12646 @code{glPixelTransfer}.
12648 @item @code{GL_POST_CONVOLUTION_BLUE_BIAS}
12651 @var{params} returns one value, the blue bias factor applied to RGBA
12652 fragments after convolution. The initial value is 0. See
12653 @code{glPixelTransfer}.
12655 @item @code{GL_POST_CONVOLUTION_ALPHA_BIAS}
12658 @var{params} returns one value, the alpha bias factor applied to RGBA
12659 fragments after convolution. The initial value is 0. See
12660 @code{glPixelTransfer}.
12662 @item @code{GL_POST_CONVOLUTION_RED_SCALE}
12665 @var{params} returns one value, the red scale factor applied to RGBA
12666 fragments after convolution. The initial value is 1. See
12667 @code{glPixelTransfer}.
12669 @item @code{GL_POST_CONVOLUTION_GREEN_SCALE}
12672 @var{params} returns one value, the green scale factor applied to RGBA
12673 fragments after convolution. The initial value is 1. See
12674 @code{glPixelTransfer}.
12676 @item @code{GL_POST_CONVOLUTION_BLUE_SCALE}
12679 @var{params} returns one value, the blue scale factor applied to RGBA
12680 fragments after convolution. The initial value is 1. See
12681 @code{glPixelTransfer}.
12683 @item @code{GL_POST_CONVOLUTION_ALPHA_SCALE}
12686 @var{params} returns one value, the alpha scale factor applied to RGBA
12687 fragments after convolution. The initial value is 1. See
12688 @code{glPixelTransfer}.
12690 @item @code{GL_PROJECTION_MATRIX}
12693 @var{params} returns sixteen values: the projection matrix on the top of
12694 the projection matrix stack. Initially this matrix is the identity
12695 matrix. See @code{glPushMatrix}.
12697 @item @code{GL_PROJECTION_STACK_DEPTH}
12700 @var{params} returns one value, the number of matrices on the projection
12701 matrix stack. The initial value is 1. See @code{glPushMatrix}.
12703 @item @code{GL_READ_BUFFER}
12706 @var{params} returns one value, a symbolic constant indicating which
12707 color buffer is selected for reading. The initial value is
12708 @code{GL_BACK} if there is a back buffer, otherwise it is
12709 @code{GL_FRONT}. See @code{glReadPixels} and @code{glAccum}.
12711 @item @code{GL_RED_BIAS}
12714 @var{params} returns one value, the red bias factor used during pixel
12715 transfers. The initial value is 0.
12717 @item @code{GL_RED_BITS}
12720 @var{params} returns one value, the number of red bitplanes in each
12723 @item @code{GL_RED_SCALE}
12726 @var{params} returns one value, the red scale factor used during pixel
12727 transfers. The initial value is 1. See @code{glPixelTransfer}.
12729 @item @code{GL_RENDER_MODE}
12732 @var{params} returns one value, a symbolic constant indicating whether
12733 the GL is in render, select, or feedback mode. The initial value is
12734 @code{GL_RENDER}. See @code{glRenderMode}.
12736 @item @code{GL_RESCALE_NORMAL}
12739 @var{params} returns single boolean value indicating whether normal
12740 rescaling is enabled. See @code{glEnable}.
12742 @item @code{GL_RGBA_MODE}
12745 @var{params} returns a single boolean value indicating whether the GL is
12746 in RGBA mode (true) or color index mode (false). See @code{glColor}.
12748 @item @code{GL_SAMPLE_BUFFERS}
12751 @var{params} returns a single integer value indicating the number of
12752 sample buffers associated with the framebuffer. See
12753 @code{glSampleCoverage}.
12755 @item @code{GL_SAMPLE_COVERAGE_VALUE}
12758 @var{params} returns a single positive floating-point value indicating
12759 the current sample coverage value. See @code{glSampleCoverage}.
12761 @item @code{GL_SAMPLE_COVERAGE_INVERT}
12764 @var{params} returns a single boolean value indicating if the temporary
12765 coverage value should be inverted. See @code{glSampleCoverage}.
12767 @item @code{GL_SAMPLES}
12770 @var{params} returns a single integer value indicating the coverage mask
12771 size. See @code{glSampleCoverage}.
12773 @item @code{GL_SCISSOR_BOX}
12776 @var{params} returns four values: the @r{@var{x}} and @r{@var{y}} window
12777 coordinates of the scissor box, followed by its width and height.
12778 Initially the @r{@var{x}} and @r{@var{y}} window coordinates are both 0
12779 and the width and height are set to the size of the window. See
12782 @item @code{GL_SCISSOR_TEST}
12785 @var{params} returns a single boolean value indicating whether
12786 scissoring is enabled. The initial value is @code{GL_FALSE}. See
12789 @item @code{GL_SECONDARY_COLOR_ARRAY}
12792 @var{params} returns a single boolean value indicating whether the
12793 secondary color array is enabled. The initial value is @code{GL_FALSE}.
12794 See @code{glSecondaryColorPointer}.
12796 @item @code{GL_SECONDARY_COLOR_ARRAY_BUFFER_BINDING}
12799 @var{params} returns a single value, the name of the buffer object
12800 associated with the secondary color array. This buffer object would have
12801 been bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
12802 recent call to @code{glSecondaryColorPointer}. If no buffer object was
12803 bound to this target, 0 is returned. The initial value is 0. See
12804 @code{glBindBuffer}.
12806 @item @code{GL_SECONDARY_COLOR_ARRAY_SIZE}
12809 @var{params} returns one value, the number of components per color in
12810 the secondary color array. The initial value is 3. See
12811 @code{glSecondaryColorPointer}.
12813 @item @code{GL_SECONDARY_COLOR_ARRAY_STRIDE}
12816 @var{params} returns one value, the byte offset between consecutive
12817 colors in the secondary color array. The initial value is 0. See
12818 @code{glSecondaryColorPointer}.
12820 @item @code{GL_SECONDARY_COLOR_ARRAY_TYPE}
12823 @var{params} returns one value, the data type of each component in the
12824 secondary color array. The initial value is @code{GL_FLOAT}. See
12825 @code{glSecondaryColorPointer}.
12827 @item @code{GL_SELECTION_BUFFER_SIZE}
12830 @var{params} return one value, the size of the selection buffer. See
12831 @code{glSelectBuffer}.
12833 @item @code{GL_SEPARABLE_2D}
12836 @var{params} returns a single boolean value indicating whether 2D
12837 separable convolution is enabled. The initial value is @code{GL_FALSE}.
12838 See @code{glSeparableFilter2D}.
12840 @item @code{GL_SHADE_MODEL}
12843 @var{params} returns one value, a symbolic constant indicating whether
12844 the shading mode is flat or smooth. The initial value is
12845 @code{GL_SMOOTH}. See @code{glShadeModel}.
12847 @item @code{GL_SMOOTH_LINE_WIDTH_RANGE}
12850 @var{params} returns two values, the smallest and largest supported
12851 widths for antialiased lines. See @code{glLineWidth}.
12853 @item @code{GL_SMOOTH_LINE_WIDTH_GRANULARITY}
12856 @var{params} returns one value, the granularity of widths for
12857 antialiased lines. See @code{glLineWidth}.
12859 @item @code{GL_SMOOTH_POINT_SIZE_RANGE}
12862 @var{params} returns two values, the smallest and largest supported
12863 widths for antialiased points. See @code{glPointSize}.
12865 @item @code{GL_SMOOTH_POINT_SIZE_GRANULARITY}
12868 @var{params} returns one value, the granularity of sizes for antialiased
12869 points. See @code{glPointSize}.
12871 @item @code{GL_STENCIL_BACK_FAIL}
12874 @var{params} returns one value, a symbolic constant indicating what
12875 action is taken for back-facing polygons when the stencil test fails.
12876 The initial value is @code{GL_KEEP}. See @code{glStencilOpSeparate}.
12878 @item @code{GL_STENCIL_BACK_FUNC}
12881 @var{params} returns one value, a symbolic constant indicating what
12882 function is used for back-facing polygons to compare the stencil
12883 reference value with the stencil buffer value. The initial value is
12884 @code{GL_ALWAYS}. See @code{glStencilFuncSeparate}.
12886 @item @code{GL_STENCIL_BACK_PASS_DEPTH_FAIL}
12889 @var{params} returns one value, a symbolic constant indicating what
12890 action is taken for back-facing polygons when the stencil test passes,
12891 but the depth test fails. The initial value is @code{GL_KEEP}. See
12892 @code{glStencilOpSeparate}.
12894 @item @code{GL_STENCIL_BACK_PASS_DEPTH_PASS}
12897 @var{params} returns one value, a symbolic constant indicating what
12898 action is taken for back-facing polygons when the stencil test passes
12899 and the depth test passes. The initial value is @code{GL_KEEP}. See
12900 @code{glStencilOpSeparate}.
12902 @item @code{GL_STENCIL_BACK_REF}
12905 @var{params} returns one value, the reference value that is compared
12906 with the contents of the stencil buffer for back-facing polygons. The
12907 initial value is 0. See @code{glStencilFuncSeparate}.
12909 @item @code{GL_STENCIL_BACK_VALUE_MASK}
12912 @var{params} returns one value, the mask that is used for back-facing
12913 polygons to mask both the stencil reference value and the stencil buffer
12914 value before they are compared. The initial value is all 1's. See
12915 @code{glStencilFuncSeparate}.
12917 @item @code{GL_STENCIL_BACK_WRITEMASK}
12920 @var{params} returns one value, the mask that controls writing of the
12921 stencil bitplanes for back-facing polygons. The initial value is all
12922 1's. See @code{glStencilMaskSeparate}.
12924 @item @code{GL_STENCIL_BITS}
12927 @var{params} returns one value, the number of bitplanes in the stencil
12930 @item @code{GL_STENCIL_CLEAR_VALUE}
12933 @var{params} returns one value, the index to which the stencil bitplanes
12934 are cleared. The initial value is 0. See @code{glClearStencil}.
12936 @item @code{GL_STENCIL_FAIL}
12939 @var{params} returns one value, a symbolic constant indicating what
12940 action is taken when the stencil test fails. The initial value is
12941 @code{GL_KEEP}. See @code{glStencilOp}. If the GL version is 2.0 or
12942 greater, this stencil state only affects non-polygons and front-facing
12943 polygons. Back-facing polygons use separate stencil state. See
12944 @code{glStencilOpSeparate}.
12946 @item @code{GL_STENCIL_FUNC}
12949 @var{params} returns one value, a symbolic constant indicating what
12950 function is used to compare the stencil reference value with the stencil
12951 buffer value. The initial value is @code{GL_ALWAYS}. See
12952 @code{glStencilFunc}. If the GL version is 2.0 or greater, this stencil
12953 state only affects non-polygons and front-facing polygons. Back-facing
12954 polygons use separate stencil state. See @code{glStencilFuncSeparate}.
12956 @item @code{GL_STENCIL_PASS_DEPTH_FAIL}
12959 @var{params} returns one value, a symbolic constant indicating what
12960 action is taken when the stencil test passes, but the depth test fails.
12961 The initial value is @code{GL_KEEP}. See @code{glStencilOp}. If the GL
12962 version is 2.0 or greater, this stencil state only affects non-polygons
12963 and front-facing polygons. Back-facing polygons use separate stencil
12964 state. See @code{glStencilOpSeparate}.
12966 @item @code{GL_STENCIL_PASS_DEPTH_PASS}
12969 @var{params} returns one value, a symbolic constant indicating what
12970 action is taken when the stencil test passes and the depth test passes.
12971 The initial value is @code{GL_KEEP}. See @code{glStencilOp}. If the GL
12972 version is 2.0 or greater, this stencil state only affects non-polygons
12973 and front-facing polygons. Back-facing polygons use separate stencil
12974 state. See @code{glStencilOpSeparate}.
12976 @item @code{GL_STENCIL_REF}
12979 @var{params} returns one value, the reference value that is compared
12980 with the contents of the stencil buffer. The initial value is 0. See
12981 @code{glStencilFunc}. If the GL version is 2.0 or greater, this stencil
12982 state only affects non-polygons and front-facing polygons. Back-facing
12983 polygons use separate stencil state. See @code{glStencilFuncSeparate}.
12985 @item @code{GL_STENCIL_TEST}
12988 @var{params} returns a single boolean value indicating whether stencil
12989 testing of fragments is enabled. The initial value is @code{GL_FALSE}.
12990 See @code{glStencilFunc} and @code{glStencilOp}.
12992 @item @code{GL_STENCIL_VALUE_MASK}
12995 @var{params} returns one value, the mask that is used to mask both the
12996 stencil reference value and the stencil buffer value before they are
12997 compared. The initial value is all 1's. See @code{glStencilFunc}. If the
12998 GL version is 2.0 or greater, this stencil state only affects
12999 non-polygons and front-facing polygons. Back-facing polygons use
13000 separate stencil state. See @code{glStencilFuncSeparate}.
13002 @item @code{GL_STENCIL_WRITEMASK}
13005 @var{params} returns one value, the mask that controls writing of the
13006 stencil bitplanes. The initial value is all 1's. See
13007 @code{glStencilMask}. If the GL version is 2.0 or greater, this stencil
13008 state only affects non-polygons and front-facing polygons. Back-facing
13009 polygons use separate stencil state. See @code{glStencilMaskSeparate}.
13011 @item @code{GL_STEREO}
13014 @var{params} returns a single boolean value indicating whether stereo
13015 buffers (left and right) are supported.
13017 @item @code{GL_SUBPIXEL_BITS}
13020 @var{params} returns one value, an estimate of the number of bits of
13021 subpixel resolution that are used to position rasterized geometry in
13022 window coordinates. The value must be at least 4.
13024 @item @code{GL_TEXTURE_1D}
13027 @var{params} returns a single boolean value indicating whether 1D
13028 texture mapping is enabled. The initial value is @code{GL_FALSE}. See
13029 @code{glTexImage1D}.
13031 @item @code{GL_TEXTURE_BINDING_1D}
13034 @var{params} returns a single value, the name of the texture currently
13035 bound to the target @code{GL_TEXTURE_1D}. The initial value is 0. See
13036 @code{glBindTexture}.
13038 @item @code{GL_TEXTURE_2D}
13041 @var{params} returns a single boolean value indicating whether 2D
13042 texture mapping is enabled. The initial value is @code{GL_FALSE}. See
13043 @code{glTexImage2D}.
13045 @item @code{GL_TEXTURE_BINDING_2D}
13048 @var{params} returns a single value, the name of the texture currently
13049 bound to the target @code{GL_TEXTURE_2D}. The initial value is 0. See
13050 @code{glBindTexture}.
13052 @item @code{GL_TEXTURE_3D}
13055 @var{params} returns a single boolean value indicating whether 3D
13056 texture mapping is enabled. The initial value is @code{GL_FALSE}. See
13057 @code{glTexImage3D}.
13059 @item @code{GL_TEXTURE_BINDING_3D}
13062 @var{params} returns a single value, the name of the texture currently
13063 bound to the target @code{GL_TEXTURE_3D}. The initial value is 0. See
13064 @code{glBindTexture}.
13066 @item @code{GL_TEXTURE_BINDING_CUBE_MAP}
13069 @var{params} returns a single value, the name of the texture currently
13070 bound to the target @code{GL_TEXTURE_CUBE_MAP}. The initial value is 0.
13071 See @code{glBindTexture}.
13073 @item @code{GL_TEXTURE_COMPRESSION_HINT}
13076 @var{params} returns a single value indicating the mode of the texture
13077 compression hint. The initial value is @code{GL_DONT_CARE}.
13079 @item @code{GL_TEXTURE_COORD_ARRAY}
13082 @var{params} returns a single boolean value indicating whether the
13083 texture coordinate array is enabled. The initial value is
13084 @code{GL_FALSE}. See @code{glTexCoordPointer}.
13086 @item @code{GL_TEXTURE_COORD_ARRAY_BUFFER_BINDING}
13089 @var{params} returns a single value, the name of the buffer object
13090 associated with the texture coordinate array. This buffer object would
13091 have been bound to the target @code{GL_ARRAY_BUFFER} at the time of the
13092 most recent call to @code{glTexCoordPointer}. If no buffer object was
13093 bound to this target, 0 is returned. The initial value is 0. See
13094 @code{glBindBuffer}.
13096 @item @code{GL_TEXTURE_COORD_ARRAY_SIZE}
13099 @var{params} returns one value, the number of coordinates per element in
13100 the texture coordinate array. The initial value is 4. See
13101 @code{glTexCoordPointer}.
13103 @item @code{GL_TEXTURE_COORD_ARRAY_STRIDE}
13106 @var{params} returns one value, the byte offset between consecutive
13107 elements in the texture coordinate array. The initial value is 0. See
13108 @code{glTexCoordPointer}.
13110 @item @code{GL_TEXTURE_COORD_ARRAY_TYPE}
13113 @var{params} returns one value, the data type of the coordinates in the
13114 texture coordinate array. The initial value is @code{GL_FLOAT}. See
13115 @code{glTexCoordPointer}.
13117 @item @code{GL_TEXTURE_CUBE_MAP}
13120 @var{params} returns a single boolean value indicating whether
13121 cube-mapped texture mapping is enabled. The initial value is
13122 @code{GL_FALSE}. See @code{glTexImage2D}.
13124 @item @code{GL_TEXTURE_GEN_Q}
13127 @var{params} returns a single boolean value indicating whether automatic
13128 generation of the @var{q} texture coordinate is enabled. The initial
13129 value is @code{GL_FALSE}. See @code{glTexGen}.
13131 @item @code{GL_TEXTURE_GEN_R}
13134 @var{params} returns a single boolean value indicating whether automatic
13135 generation of the @var{r} texture coordinate is enabled. The initial
13136 value is @code{GL_FALSE}. See @code{glTexGen}.
13138 @item @code{GL_TEXTURE_GEN_S}
13141 @var{params} returns a single boolean value indicating whether automatic
13142 generation of the @var{S} texture coordinate is enabled. The initial
13143 value is @code{GL_FALSE}. See @code{glTexGen}.
13145 @item @code{GL_TEXTURE_GEN_T}
13148 @var{params} returns a single boolean value indicating whether automatic
13149 generation of the T texture coordinate is enabled. The initial value is
13150 @code{GL_FALSE}. See @code{glTexGen}.
13152 @item @code{GL_TEXTURE_MATRIX}
13155 @var{params} returns sixteen values: the texture matrix on the top of
13156 the texture matrix stack. Initially this matrix is the identity matrix.
13157 See @code{glPushMatrix}.
13159 @item @code{GL_TEXTURE_STACK_DEPTH}
13162 @var{params} returns one value, the number of matrices on the texture
13163 matrix stack. The initial value is 1. See @code{glPushMatrix}.
13165 @item @code{GL_TRANSPOSE_COLOR_MATRIX}
13168 @var{params} returns 16 values, the elements of the color matrix in
13169 row-major order. See @code{glLoadTransposeMatrix}.
13171 @item @code{GL_TRANSPOSE_MODELVIEW_MATRIX}
13174 @var{params} returns 16 values, the elements of the modelview matrix in
13175 row-major order. See @code{glLoadTransposeMatrix}.
13177 @item @code{GL_TRANSPOSE_PROJECTION_MATRIX}
13180 @var{params} returns 16 values, the elements of the projection matrix in
13181 row-major order. See @code{glLoadTransposeMatrix}.
13183 @item @code{GL_TRANSPOSE_TEXTURE_MATRIX}
13186 @var{params} returns 16 values, the elements of the texture matrix in
13187 row-major order. See @code{glLoadTransposeMatrix}.
13189 @item @code{GL_UNPACK_ALIGNMENT}
13192 @var{params} returns one value, the byte alignment used for reading
13193 pixel data from memory. The initial value is 4. See @code{glPixelStore}.
13195 @item @code{GL_UNPACK_IMAGE_HEIGHT}
13198 @var{params} returns one value, the image height used for reading pixel
13199 data from memory. The initial is 0. See @code{glPixelStore}.
13201 @item @code{GL_UNPACK_LSB_FIRST}
13204 @var{params} returns a single boolean value indicating whether
13205 single-bit pixels being read from memory are read first from the least
13206 significant bit of each unsigned byte. The initial value is
13207 @code{GL_FALSE}. See @code{glPixelStore}.
13209 @item @code{GL_UNPACK_ROW_LENGTH}
13212 @var{params} returns one value, the row length used for reading pixel
13213 data from memory. The initial value is 0. See @code{glPixelStore}.
13215 @item @code{GL_UNPACK_SKIP_IMAGES}
13218 @var{params} returns one value, the number of pixel images skipped
13219 before the first pixel is read from memory. The initial value is 0. See
13220 @code{glPixelStore}.
13222 @item @code{GL_UNPACK_SKIP_PIXELS}
13225 @var{params} returns one value, the number of pixel locations skipped
13226 before the first pixel is read from memory. The initial value is 0. See
13227 @code{glPixelStore}.
13229 @item @code{GL_UNPACK_SKIP_ROWS}
13232 @var{params} returns one value, the number of rows of pixel locations
13233 skipped before the first pixel is read from memory. The initial value is
13234 0. See @code{glPixelStore}.
13236 @item @code{GL_UNPACK_SWAP_BYTES}
13239 @var{params} returns a single boolean value indicating whether the bytes
13240 of two-byte and four-byte pixel indices and components are swapped after
13241 being read from memory. The initial value is @code{GL_FALSE}. See
13242 @code{glPixelStore}.
13244 @item @code{GL_VERTEX_ARRAY}
13247 @var{params} returns a single boolean value indicating whether the
13248 vertex array is enabled. The initial value is @code{GL_FALSE}. See
13249 @code{glVertexPointer}.
13251 @item @code{GL_VERTEX_ARRAY_BUFFER_BINDING}
13254 @var{params} returns a single value, the name of the buffer object
13255 associated with the vertex array. This buffer object would have been
13256 bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
13257 recent call to @code{glVertexPointer}. If no buffer object was bound to
13258 this target, 0 is returned. The initial value is 0. See
13259 @code{glBindBuffer}.
13261 @item @code{GL_VERTEX_ARRAY_SIZE}
13264 @var{params} returns one value, the number of coordinates per vertex in
13265 the vertex array. The initial value is 4. See @code{glVertexPointer}.
13267 @item @code{GL_VERTEX_ARRAY_STRIDE}
13270 @var{params} returns one value, the byte offset between consecutive
13271 vertices in the vertex array. The initial value is 0. See
13272 @code{glVertexPointer}.
13274 @item @code{GL_VERTEX_ARRAY_TYPE}
13277 @var{params} returns one value, the data type of each coordinate in the
13278 vertex array. The initial value is @code{GL_FLOAT}. See
13279 @code{glVertexPointer}.
13281 @item @code{GL_VERTEX_PROGRAM_POINT_SIZE}
13284 @var{params} returns a single boolean value indicating whether vertex
13285 program point size mode is enabled. If enabled, and a vertex shader is
13286 active, then the point size is taken from the shader built-in
13287 @code{gl_PointSize}. If disabled, and a vertex shader is active, then
13288 the point size is taken from the point state as specified by
13289 @code{glPointSize}. The initial value is @code{GL_FALSE}.
13291 @item @code{GL_VERTEX_PROGRAM_TWO_SIDE}
13294 @var{params} returns a single boolean value indicating whether vertex
13295 program two-sided color mode is enabled. If enabled, and a vertex shader
13296 is active, then the GL chooses the back color output for back-facing
13297 polygons, and the front color output for non-polygons and front-facing
13298 polygons. If disabled, and a vertex shader is active, then the front
13299 color output is always selected. The initial value is @code{GL_FALSE}.
13301 @item @code{GL_VIEWPORT}
13304 @var{params} returns four values: the @r{@var{x}} and @r{@var{y}} window
13305 coordinates of the viewport, followed by its width and height. Initially
13306 the @r{@var{x}} and @r{@var{y}} window coordinates are both set to 0,
13307 and the width and height are set to the width and height of the window
13308 into which the GL will do its rendering. See @code{glViewport}.
13310 @item @code{GL_ZOOM_X}
13313 @var{params} returns one value, the @r{@var{x}} pixel zoom factor. The
13314 initial value is 1. See @code{glPixelZoom}.
13316 @item @code{GL_ZOOM_Y}
13319 @var{params} returns one value, the @r{@var{y}} pixel zoom factor. The
13320 initial value is 1. See @code{glPixelZoom}.
13324 Many of the boolean parameters can also be queried more easily using
13325 @code{glIsEnabled}.
13327 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
13330 @code{GL_INVALID_OPERATION} is generated if @code{glGet} is executed
13331 between the execution of @code{glBegin} and the corresponding execution
13338 @deftypefun void glHint target mode
13339 Specify implementation-specific hints.
13343 Specifies a symbolic constant indicating the behavior to be controlled.
13344 @code{GL_FOG_HINT}, @code{GL_GENERATE_MIPMAP_HINT},
13345 @code{GL_LINE_SMOOTH_HINT}, @code{GL_PERSPECTIVE_CORRECTION_HINT},
13346 @code{GL_POINT_SMOOTH_HINT}, @code{GL_POLYGON_SMOOTH_HINT},
13347 @code{GL_TEXTURE_COMPRESSION_HINT}, and
13348 @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT} are accepted.
13351 Specifies a symbolic constant indicating the desired behavior.
13352 @code{GL_FASTEST}, @code{GL_NICEST}, and @code{GL_DONT_CARE} are
13357 Certain aspects of GL behavior, when there is room for interpretation,
13358 can be controlled with hints. A hint is specified with two arguments.
13359 @var{target} is a symbolic constant indicating the behavior to be
13360 controlled, and @var{mode} is another symbolic constant indicating the
13361 desired behavior. The initial value for each @var{target} is
13362 @code{GL_DONT_CARE}. @var{mode} can be one of the following:
13365 @item @code{GL_FASTEST}
13368 The most efficient option should be chosen.
13370 @item @code{GL_NICEST}
13373 The most correct, or highest quality, option should be chosen.
13375 @item @code{GL_DONT_CARE}
13382 Though the implementation aspects that can be hinted are well defined,
13383 the interpretation of the hints depends on the implementation. The hint
13384 aspects that can be specified with @var{target}, along with suggested
13385 semantics, are as follows:
13388 @item @code{GL_FOG_HINT}
13391 Indicates the accuracy of fog calculation. If per-pixel fog calculation
13392 is not efficiently supported by the GL implementation, hinting
13393 @code{GL_DONT_CARE} or @code{GL_FASTEST} can result in per-vertex
13394 calculation of fog effects.
13396 @item @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT}
13399 Indicates the accuracy of the derivative calculation for the GL shading
13400 language fragment processing built-in functions: @code{dFdx},
13401 @code{dFdy}, and @code{fwidth}.
13403 @item @code{GL_GENERATE_MIPMAP_HINT}
13406 Indicates the quality of filtering when generating mipmap images.
13408 @item @code{GL_LINE_SMOOTH_HINT}
13411 Indicates the sampling quality of antialiased lines. If a larger filter
13412 function is applied, hinting @code{GL_NICEST} can result in more pixel
13413 fragments being generated during rasterization.
13415 @item @code{GL_PERSPECTIVE_CORRECTION_HINT}
13418 Indicates the quality of color, texture coordinate, and fog coordinate
13419 interpolation. If perspective-corrected parameter interpolation is not
13420 efficiently supported by the GL implementation, hinting
13421 @code{GL_DONT_CARE} or @code{GL_FASTEST} can result in simple linear
13422 interpolation of colors and/or texture coordinates.
13424 @item @code{GL_POINT_SMOOTH_HINT}
13427 Indicates the sampling quality of antialiased points. If a larger filter
13428 function is applied, hinting @code{GL_NICEST} can result in more pixel
13429 fragments being generated during rasterization.
13431 @item @code{GL_POLYGON_SMOOTH_HINT}
13434 Indicates the sampling quality of antialiased polygons. Hinting
13435 @code{GL_NICEST} can result in more pixel fragments being generated
13436 during rasterization, if a larger filter function is applied.
13438 @item @code{GL_TEXTURE_COMPRESSION_HINT}
13441 Indicates the quality and performance of the compressing texture images.
13442 Hinting @code{GL_FASTEST} indicates that texture images should be
13443 compressed as quickly as possible, while @code{GL_NICEST} indicates that
13444 texture images should be compressed with as little image quality loss as
13445 possible. @code{GL_NICEST} should be selected if the texture is to be
13446 retrieved by @code{glGetCompressedTexImage} for reuse.
13450 @code{GL_INVALID_ENUM} is generated if either @var{target} or @var{mode}
13451 is not an accepted value.
13453 @code{GL_INVALID_OPERATION} is generated if @code{glHint} is executed
13454 between the execution of @code{glBegin} and the corresponding execution
13459 @deftypefun void glHistogram target width internalformat sink
13460 Define histogram table.
13464 The histogram whose parameters are to be set. Must be one of
13465 @code{GL_HISTOGRAM} or @code{GL_PROXY_HISTOGRAM}.
13468 The number of entries in the histogram table. Must be a power of 2.
13470 @item @var{internalformat}
13471 The format of entries in the histogram table. Must be one of
13472 @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
13473 @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
13474 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
13475 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
13476 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
13477 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
13478 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
13479 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
13480 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
13481 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
13482 @code{GL_RGBA12}, or @code{GL_RGBA16}.
13485 If @code{GL_TRUE}, pixels will be consumed by the histogramming process
13486 and no drawing or texture loading will take place. If @code{GL_FALSE},
13487 pixels will proceed to the minmax process after histogramming.
13491 When @code{GL_HISTOGRAM} is enabled, RGBA color components are converted
13492 to histogram table indices by clamping to the range [0,1], multiplying
13493 by the width of the histogram table, and rounding to the nearest
13494 integer. The table entries selected by the RGBA indices are then
13495 incremented. (If the internal format of the histogram table includes
13496 luminance, then the index derived from the R color component determines
13497 the luminance table entry to be incremented.) If a histogram table entry
13498 is incremented beyond its maximum value, then its value becomes
13499 undefined. (This is not an error.)
13501 Histogramming is performed only for RGBA pixels (though these may be
13502 specified originally as color indices and converted to RGBA by index
13503 table lookup). Histogramming is enabled with @code{glEnable} and
13504 disabled with @code{glDisable}.
13506 When @var{target} is @code{GL_HISTOGRAM}, @code{glHistogram} redefines
13507 the current histogram table to have @var{width} entries of the format
13508 specified by @var{internalformat}. The entries are indexed 0 through
13509 @r{@var{width}-1}, and all entries are initialized to zero. The values
13510 in the previous histogram table, if any, are lost. If @var{sink} is
13511 @code{GL_TRUE}, then pixels are discarded after histogramming; no
13512 further processing of the pixels takes place, and no drawing, texture
13513 loading, or pixel readback will result.
13515 When @var{target} is @code{GL_PROXY_HISTOGRAM}, @code{glHistogram}
13516 computes all state information as if the histogram table were to be
13517 redefined, but does not actually define the new table. If the requested
13518 histogram table is too large to be supported, then the state information
13519 will be set to zero. This provides a way to determine if a histogram
13520 table with the given parameters can be supported.
13524 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
13527 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
13528 is not a power of 2.
13530 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
13531 of the allowable values.
13533 @code{GL_TABLE_TOO_LARGE} is generated if @var{target} is
13534 @code{GL_HISTOGRAM} and the histogram table specified is too large for
13535 the implementation.
13537 @code{GL_INVALID_OPERATION} is generated if @code{glHistogram} is
13538 executed between the execution of @code{glBegin} and the corresponding
13539 execution of @code{glEnd}.
13543 @deftypefun void glIndexMask mask
13544 Control the writing of individual bits in the color index buffers.
13548 Specifies a bit mask to enable and disable the writing of individual
13549 bits in the color index buffers. Initially, the mask is all 1's.
13553 @code{glIndexMask} controls the writing of individual bits in the color
13554 index buffers. The least significant @r{@var{n}} bits of @var{mask},
13555 where @r{@var{n}} is the number of bits in a color index buffer, specify
13556 a mask. Where a 1 (one) appears in the mask, it's possible to write to
13557 the corresponding bit in the color index buffer (or buffers). Where a 0
13558 (zero) appears, the corresponding bit is write-protected.
13560 This mask is used only in color index mode, and it affects only the
13561 buffers currently selected for writing (see @code{glDrawBuffer}).
13562 Initially, all bits are enabled for writing.
13564 @code{GL_INVALID_OPERATION} is generated if @code{glIndexMask} is
13565 executed between the execution of @code{glBegin} and the corresponding
13566 execution of @code{glEnd}.
13570 @deftypefun void glIndexPointer type stride pointer
13571 Define an array of color indexes.
13575 Specifies the data type of each color index in the array. Symbolic
13576 constants @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, @code{GL_INT},
13577 @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value is
13581 Specifies the byte offset between consecutive color indexes. If
13582 @var{stride} is 0, the color indexes are understood to be tightly packed
13583 in the array. The initial value is 0.
13585 @item @var{pointer}
13586 Specifies a pointer to the first index in the array. The initial value
13591 @code{glIndexPointer} specifies the location and data format of an array
13592 of color indexes to use when rendering. @var{type} specifies the data
13593 type of each color index and @var{stride} specifies the byte stride from
13594 one color index to the next, allowing vertices and attributes to be
13595 packed into a single array or stored in separate arrays.
13597 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
13598 target (see @code{glBindBuffer}) while a color index array is specified,
13599 @var{pointer} is treated as a byte offset into the buffer object's data
13600 store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING})
13601 is saved as color index vertex array client-side state
13602 (@code{GL_INDEX_ARRAY_BUFFER_BINDING}).
13604 When a color index array is specified, @var{type}, @var{stride}, and
13605 @var{pointer} are saved as client-side state, in addition to the current
13606 vertex array buffer object binding.
13608 To enable and disable the color index array, call
13609 @code{glEnableClientState} and @code{glDisableClientState} with the
13610 argument @code{GL_INDEX_ARRAY}. If enabled, the color index array is
13611 used when @code{glDrawArrays}, @code{glMultiDrawArrays},
13612 @code{glDrawElements}, @code{glMultiDrawElements},
13613 @code{glDrawRangeElements}, or @code{glArrayElement} is called.
13615 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
13618 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
13622 @deftypefun void glIndexi c
13623 @deftypefunx void glIndexf c
13624 @deftypefunx void glIndexub c
13625 Set the current color index.
13629 Specifies the new value for the current color index.
13635 @code{glIndex} updates the current (single-valued) color index. It takes
13636 one argument, the new value for the current color index.
13638 The current index is stored as a floating-point value. Integer values
13639 are converted directly to floating-point values, with no special
13640 mapping. The initial value is 1.
13642 Index values outside the representable range of the color index buffer
13643 are not clamped. However, before an index is dithered (if enabled) and
13644 written to the frame buffer, it is converted to fixed-point format. Any
13645 bits in the integer portion of the resulting fixed-point value that do
13646 not correspond to bits in the frame buffer are masked out.
13650 @deftypefun void glInitNames
13651 Initialize the name stack.
13653 The name stack is used during selection mode to allow sets of rendering
13654 commands to be uniquely identified. It consists of an ordered set of
13655 unsigned integers. @code{glInitNames} causes the name stack to be
13656 initialized to its default empty state.
13658 The name stack is always empty while the render mode is not
13659 @code{GL_SELECT}. Calls to @code{glInitNames} while the render mode is
13660 not @code{GL_SELECT} are ignored.
13662 @code{GL_INVALID_OPERATION} is generated if @code{glInitNames} is
13663 executed between the execution of @code{glBegin} and the corresponding
13664 execution of @code{glEnd}.
13668 @deftypefun void glInterleavedArrays format stride pointer
13669 Simultaneously specify and enable several interleaved arrays.
13673 Specifies the type of array to enable. Symbolic constants @code{GL_V2F},
13674 @code{GL_V3F}, @code{GL_C4UB_V2F}, @code{GL_C4UB_V3F},
13675 @code{GL_C3F_V3F}, @code{GL_N3F_V3F}, @code{GL_C4F_N3F_V3F},
13676 @code{GL_T2F_V3F}, @code{GL_T4F_V4F}, @code{GL_T2F_C4UB_V3F},
13677 @code{GL_T2F_C3F_V3F}, @code{GL_T2F_N3F_V3F}, @code{GL_T2F_C4F_N3F_V3F},
13678 and @code{GL_T4F_C4F_N3F_V4F} are accepted.
13681 Specifies the offset in bytes between each aggregate array element.
13685 @code{glInterleavedArrays} lets you specify and enable individual color,
13686 normal, texture and vertex arrays whose elements are part of a larger
13687 aggregate array element. For some implementations, this is more
13688 efficient than specifying the arrays separately.
13690 If @var{stride} is 0, the aggregate elements are stored consecutively.
13691 Otherwise, @var{stride} bytes occur between the beginning of one
13692 aggregate array element and the beginning of the next aggregate array
13695 @var{format} serves as a ``key'' describing the extraction of individual
13696 arrays from the aggregate array. If @var{format} contains a T, then
13697 texture coordinates are extracted from the interleaved array. If C is
13698 present, color values are extracted. If N is present, normal coordinates
13699 are extracted. Vertex coordinates are always extracted.
13701 The digits 2, 3, and 4 denote how many values are extracted. F indicates
13702 that values are extracted as floating-point values. Colors may also be
13703 extracted as 4 unsigned bytes if 4UB follows the C. If a color is
13704 extracted as 4 unsigned bytes, the vertex array element which follows is
13705 located at the first possible floating-point aligned address.
13707 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
13710 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
13714 @deftypefun GLboolean glIsBuffer buffer
13715 Determine if a name corresponds to a buffer object.
13719 Specifies a value that may be the name of a buffer object.
13723 @code{glIsBuffer} returns @code{GL_TRUE} if @var{buffer} is currently
13724 the name of a buffer object. If @var{buffer} is zero, or is a non-zero
13725 value that is not currently the name of a buffer object, or if an error
13726 occurs, @code{glIsBuffer} returns @code{GL_FALSE}.
13728 A name returned by @code{glGenBuffers}, but not yet associated with a
13729 buffer object by calling @code{glBindBuffer}, is not the name of a
13732 @code{GL_INVALID_OPERATION} is generated if @code{glIsBuffer} is
13733 executed between the execution of @code{glBegin} and the corresponding
13734 execution of @code{glEnd}.
13738 @deftypefun GLboolean glIsEnabled cap
13739 Test whether a capability is enabled.
13743 Specifies a symbolic constant indicating a GL capability.
13747 @code{glIsEnabled} returns @code{GL_TRUE} if @var{cap} is an enabled
13748 capability and returns @code{GL_FALSE} otherwise. Initially all
13749 capabilities except @code{GL_DITHER} are disabled; @code{GL_DITHER} is
13752 The following capabilities are accepted for @var{cap}:
13757 @item @strong{Constant}
13760 @item @code{GL_ALPHA_TEST}
13763 @item @code{GL_AUTO_NORMAL}
13766 @item @code{GL_BLEND}
13767 @code{glBlendFunc}, @code{glLogicOp}
13769 @item @code{GL_CLIP_PLANE}@var{i}
13772 @item @code{GL_COLOR_ARRAY}
13773 @code{glColorPointer}
13775 @item @code{GL_COLOR_LOGIC_OP}
13778 @item @code{GL_COLOR_MATERIAL}
13779 @code{glColorMaterial}
13781 @item @code{GL_COLOR_SUM}
13782 @code{glSecondaryColor}
13784 @item @code{GL_COLOR_TABLE}
13785 @code{glColorTable}
13787 @item @code{GL_CONVOLUTION_1D}
13788 @code{glConvolutionFilter1D}
13790 @item @code{GL_CONVOLUTION_2D}
13791 @code{glConvolutionFilter2D}
13793 @item @code{GL_CULL_FACE}
13796 @item @code{GL_DEPTH_TEST}
13797 @code{glDepthFunc}, @code{glDepthRange}
13799 @item @code{GL_DITHER}
13802 @item @code{GL_EDGE_FLAG_ARRAY}
13803 @code{glEdgeFlagPointer}
13805 @item @code{GL_FOG}
13808 @item @code{GL_FOG_COORD_ARRAY}
13809 @code{glFogCoordPointer}
13811 @item @code{GL_HISTOGRAM}
13814 @item @code{GL_INDEX_ARRAY}
13815 @code{glIndexPointer}
13817 @item @code{GL_INDEX_LOGIC_OP}
13820 @item @code{GL_LIGHT}@var{i}
13821 @code{glLightModel}, @code{glLight}
13823 @item @code{GL_LIGHTING}
13824 @code{glMaterial}, @code{glLightModel}, @code{glLight}
13826 @item @code{GL_LINE_SMOOTH}
13829 @item @code{GL_LINE_STIPPLE}
13830 @code{glLineStipple}
13832 @item @code{GL_MAP1_COLOR_4}
13835 @item @code{GL_MAP1_INDEX}
13838 @item @code{GL_MAP1_NORMAL}
13841 @item @code{GL_MAP1_TEXTURE_COORD_1}
13844 @item @code{GL_MAP1_TEXTURE_COORD_2}
13847 @item @code{GL_MAP1_TEXTURE_COORD_3}
13850 @item @code{GL_MAP1_TEXTURE_COORD_4}
13853 @item @code{GL_MAP2_COLOR_4}
13856 @item @code{GL_MAP2_INDEX}
13859 @item @code{GL_MAP2_NORMAL}
13862 @item @code{GL_MAP2_TEXTURE_COORD_1}
13865 @item @code{GL_MAP2_TEXTURE_COORD_2}
13868 @item @code{GL_MAP2_TEXTURE_COORD_3}
13871 @item @code{GL_MAP2_TEXTURE_COORD_4}
13874 @item @code{GL_MAP2_VERTEX_3}
13877 @item @code{GL_MAP2_VERTEX_4}
13880 @item @code{GL_MINMAX}
13883 @item @code{GL_MULTISAMPLE}
13884 @code{glSampleCoverage}
13886 @item @code{GL_NORMAL_ARRAY}
13887 @code{glNormalPointer}
13889 @item @code{GL_NORMALIZE}
13892 @item @code{GL_POINT_SMOOTH}
13895 @item @code{GL_POINT_SPRITE}
13898 @item @code{GL_POLYGON_SMOOTH}
13899 @code{glPolygonMode}
13901 @item @code{GL_POLYGON_OFFSET_FILL}
13902 @code{glPolygonOffset}
13904 @item @code{GL_POLYGON_OFFSET_LINE}
13905 @code{glPolygonOffset}
13907 @item @code{GL_POLYGON_OFFSET_POINT}
13908 @code{glPolygonOffset}
13910 @item @code{GL_POLYGON_STIPPLE}
13911 @code{glPolygonStipple}
13913 @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}
13914 @code{glColorTable}
13916 @item @code{GL_POST_CONVOLUTION_COLOR_TABLE}
13917 @code{glColorTable}
13919 @item @code{GL_RESCALE_NORMAL}
13922 @item @code{GL_SAMPLE_ALPHA_TO_COVERAGE}
13923 @code{glSampleCoverage}
13925 @item @code{GL_SAMPLE_ALPHA_TO_ONE}
13926 @code{glSampleCoverage}
13928 @item @code{GL_SAMPLE_COVERAGE}
13929 @code{glSampleCoverage}
13931 @item @code{GL_SCISSOR_TEST}
13934 @item @code{GL_SECONDARY_COLOR_ARRAY}
13935 @code{glSecondaryColorPointer}
13937 @item @code{GL_SEPARABLE_2D}
13938 @code{glSeparableFilter2D}
13940 @item @code{GL_STENCIL_TEST}
13941 @code{glStencilFunc}, @code{glStencilOp}
13943 @item @code{GL_TEXTURE_1D}
13944 @code{glTexImage1D}
13946 @item @code{GL_TEXTURE_2D}
13947 @code{glTexImage2D}
13949 @item @code{GL_TEXTURE_3D}
13950 @code{glTexImage3D}
13952 @item @code{GL_TEXTURE_COORD_ARRAY}
13953 @code{glTexCoordPointer}
13955 @item @code{GL_TEXTURE_CUBE_MAP}
13956 @code{glTexImage2D}
13958 @item @code{GL_TEXTURE_GEN_Q}
13961 @item @code{GL_TEXTURE_GEN_R}
13964 @item @code{GL_TEXTURE_GEN_S}
13967 @item @code{GL_TEXTURE_GEN_T}
13970 @item @code{GL_VERTEX_ARRAY}
13971 @code{glVertexPointer}
13973 @item @code{GL_VERTEX_PROGRAM_POINT_SIZE}
13976 @item @code{GL_VERTEX_PROGRAM_TWO_SIDE}
13983 @code{GL_INVALID_ENUM} is generated if @var{cap} is not an accepted
13986 @code{GL_INVALID_OPERATION} is generated if @code{glIsEnabled} is
13987 executed between the execution of @code{glBegin} and the corresponding
13988 execution of @code{glEnd}.
13992 @deftypefun GLboolean glIsList list
13993 Determine if a name corresponds to a display list.
13997 Specifies a potential display list name.
14001 @code{glIsList} returns @code{GL_TRUE} if @var{list} is the name of a
14002 display list and returns @code{GL_FALSE} if it is not, or if an error
14005 A name returned by @code{glGenLists}, but not yet associated with a
14006 display list by calling @code{glNewList}, is not the name of a display
14009 @code{GL_INVALID_OPERATION} is generated if @code{glIsList} is executed
14010 between the execution of @code{glBegin} and the corresponding execution
14015 @deftypefun GLboolean glIsProgram program
14016 Determines if a name corresponds to a program object.
14019 @item @var{program}
14020 Specifies a potential program object.
14024 @code{glIsProgram} returns @code{GL_TRUE} if @var{program} is the name
14025 of a program object previously created with @code{glCreateProgram} and
14026 not yet deleted with @code{glDeleteProgram}. If @var{program} is zero or
14027 a non-zero value that is not the name of a program object, or if an
14028 error occurs, @code{glIsProgram} returns @code{GL_FALSE}.
14030 @code{GL_INVALID_OPERATION} is generated if @code{glIsProgram} is
14031 executed between the execution of @code{glBegin} and the corresponding
14032 execution of @code{glEnd}.
14036 @deftypefun GLboolean glIsQuery id
14037 Determine if a name corresponds to a query object.
14041 Specifies a value that may be the name of a query object.
14045 @code{glIsQuery} returns @code{GL_TRUE} if @var{id} is currently the
14046 name of a query object. If @var{id} is zero, or is a non-zero value that
14047 is not currently the name of a query object, or if an error occurs,
14048 @code{glIsQuery} returns @code{GL_FALSE}.
14050 A name returned by @code{glGenQueries}, but not yet associated with a
14051 query object by calling @code{glBeginQuery}, is not the name of a query
14054 @code{GL_INVALID_OPERATION} is generated if @code{glIsQuery} is executed
14055 between the execution of @code{glBegin} and the corresponding execution
14060 @deftypefun GLboolean glIsShader shader
14061 Determines if a name corresponds to a shader object.
14065 Specifies a potential shader object.
14069 @code{glIsShader} returns @code{GL_TRUE} if @var{shader} is the name of
14070 a shader object previously created with @code{glCreateShader} and not
14071 yet deleted with @code{glDeleteShader}. If @var{shader} is zero or a
14072 non-zero value that is not the name of a shader object, or if an error
14073 occurs, @code{glIsShader } returns @code{GL_FALSE}.
14075 @code{GL_INVALID_OPERATION} is generated if @code{glIsShader} is
14076 executed between the execution of @code{glBegin} and the corresponding
14077 execution of @code{glEnd}.
14081 @deftypefun GLboolean glIsTexture texture
14082 Determine if a name corresponds to a texture.
14085 @item @var{texture}
14086 Specifies a value that may be the name of a texture.
14090 @code{glIsTexture} returns @code{GL_TRUE} if @var{texture} is currently
14091 the name of a texture. If @var{texture} is zero, or is a non-zero value
14092 that is not currently the name of a texture, or if an error occurs,
14093 @code{glIsTexture} returns @code{GL_FALSE}.
14095 A name returned by @code{glGenTextures}, but not yet associated with a
14096 texture by calling @code{glBindTexture}, is not the name of a texture.
14098 @code{GL_INVALID_OPERATION} is generated if @code{glIsTexture} is
14099 executed between the execution of @code{glBegin} and the corresponding
14100 execution of @code{glEnd}.
14104 @deftypefun void glLightModelf pname param
14105 @deftypefunx void glLightModeli pname param
14106 Set the lighting model parameters.
14110 Specifies a single-valued lighting model parameter.
14111 @code{GL_LIGHT_MODEL_LOCAL_VIEWER}, @code{GL_LIGHT_MODEL_COLOR_CONTROL},
14112 and @code{GL_LIGHT_MODEL_TWO_SIDE} are accepted.
14115 Specifies the value that @var{param} will be set to.
14119 @code{glLightModel} sets the lighting model parameter. @var{pname} names
14120 a parameter and @var{params} gives the new value. There are three
14121 lighting model parameters:
14124 @item @code{GL_LIGHT_MODEL_AMBIENT}
14127 @var{params} contains four integer or floating-point values that specify
14128 the ambient RGBA intensity of the entire scene. Integer values are
14129 mapped linearly such that the most positive representable value maps to
14130 1.0, and the most negative representable value maps to @r{-1.0}.
14131 Floating-point values are mapped directly. Neither integer nor
14132 floating-point values are clamped. The initial ambient scene intensity
14133 is (0.2, 0.2, 0.2, 1.0).
14135 @item @code{GL_LIGHT_MODEL_COLOR_CONTROL}
14138 @var{params} must be either @code{GL_SEPARATE_SPECULAR_COLOR} or
14139 @code{GL_SINGLE_COLOR}. @code{GL_SINGLE_COLOR} specifies that a single
14140 color is generated from the lighting computation for a vertex.
14141 @code{GL_SEPARATE_SPECULAR_COLOR} specifies that the specular color
14142 computation of lighting be stored separately from the remainder of the
14143 lighting computation. The specular color is summed into the generated
14144 fragment's color after the application of texture mapping (if enabled).
14145 The initial value is @code{GL_SINGLE_COLOR}.
14147 @item @code{GL_LIGHT_MODEL_LOCAL_VIEWER}
14150 @var{params} is a single integer or floating-point value that specifies
14151 how specular reflection angles are computed. If @var{params} is 0 (or
14152 0.0), specular reflection angles take the view direction to be parallel
14153 to and in the direction of the -@var{z} axis, regardless of the location
14154 of the vertex in eye coordinates. Otherwise, specular reflections are
14155 computed from the origin of the eye coordinate system. The initial value
14158 @item @code{GL_LIGHT_MODEL_TWO_SIDE}
14161 @var{params} is a single integer or floating-point value that specifies
14162 whether one- or two-sided lighting calculations are done for polygons.
14163 It has no effect on the lighting calculations for points, lines, or
14164 bitmaps. If @var{params} is 0 (or 0.0), one-sided lighting is specified,
14165 and only the @var{front} material parameters are used in the lighting
14166 equation. Otherwise, two-sided lighting is specified. In this case,
14167 vertices of back-facing polygons are lighted using the @var{back}
14168 material parameters and have their normals reversed before the lighting
14169 equation is evaluated. Vertices of front-facing polygons are always
14170 lighted using the @var{front} material parameters, with no change to
14171 their normals. The initial value is 0.
14175 In RGBA mode, the lighted color of a vertex is the sum of the material
14176 emission intensity, the product of the material ambient reflectance and
14177 the lighting model full-scene ambient intensity, and the contribution of
14178 each enabled light source. Each light source contributes the sum of
14179 three terms: ambient, diffuse, and specular. The ambient light source
14180 contribution is the product of the material ambient reflectance and the
14181 light's ambient intensity. The diffuse light source contribution is the
14182 product of the material diffuse reflectance, the light's diffuse
14183 intensity, and the dot product of the vertex's normal with the
14184 normalized vector from the vertex to the light source. The specular
14185 light source contribution is the product of the material specular
14186 reflectance, the light's specular intensity, and the dot product of the
14187 normalized vertex-to-eye and vertex-to-light vectors, raised to the
14188 power of the shininess of the material. All three light source
14189 contributions are attenuated equally based on the distance from the
14190 vertex to the light source and on light source direction, spread
14191 exponent, and spread cutoff angle. All dot products are replaced with 0
14192 if they evaluate to a negative value.
14194 The alpha component of the resulting lighted color is set to the alpha
14195 value of the material diffuse reflectance.
14197 In color index mode, the value of the lighted index of a vertex ranges
14198 from the ambient to the specular values passed to @code{glMaterial}
14199 using @code{GL_COLOR_INDEXES}. Diffuse and specular coefficients,
14200 computed with a (.30, .59, .11) weighting of the lights' colors, the
14201 shininess of the material, and the same reflection and attenuation
14202 equations as in the RGBA case, determine how much above ambient the
14203 resulting index is.
14205 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
14208 @code{GL_INVALID_ENUM} is generated if @var{pname} is
14209 @code{GL_LIGHT_MODEL_COLOR_CONTROL} and @var{params} is not one of
14210 @code{GL_SINGLE_COLOR} or @code{GL_SEPARATE_SPECULAR_COLOR}.
14212 @code{GL_INVALID_OPERATION} is generated if @code{glLightModel} is
14213 executed between the execution of @code{glBegin} and the corresponding
14214 execution of @code{glEnd}.
14218 @deftypefun void glLightf light pname param
14219 @deftypefunx void glLighti light pname param
14220 Set light source parameters.
14224 Specifies a light. The number of lights depends on the implementation,
14225 but at least eight lights are supported. They are identified by symbolic
14226 names of the form @code{GL_LIGHT}@r{@var{i}}, where i ranges from 0 to
14227 the value of @code{GL_MAX_LIGHTS} - 1.
14230 Specifies a single-valued light source parameter for @var{light}.
14231 @code{GL_SPOT_EXPONENT}, @code{GL_SPOT_CUTOFF},
14232 @code{GL_CONSTANT_ATTENUATION}, @code{GL_LINEAR_ATTENUATION}, and
14233 @code{GL_QUADRATIC_ATTENUATION} are accepted.
14236 Specifies the value that parameter @var{pname} of light source
14237 @var{light} will be set to.
14241 @code{glLight} sets the values of individual light source parameters.
14242 @var{light} names the light and is a symbolic name of the form
14243 @code{GL_LIGHT}@r{@var{i}}, where i ranges from 0 to the value of
14244 @code{GL_MAX_LIGHTS} - 1. @var{pname} specifies one of ten light source
14245 parameters, again by symbolic name. @var{params} is either a single
14246 value or a pointer to an array that contains the new values.
14248 To enable and disable lighting calculation, call @code{glEnable} and
14249 @code{glDisable} with argument @code{GL_LIGHTING}. Lighting is initially
14250 disabled. When it is enabled, light sources that are enabled contribute
14251 to the lighting calculation. Light source @r{@var{i}} is enabled and
14252 disabled using @code{glEnable} and @code{glDisable} with argument
14253 @code{GL_LIGHT}@r{@var{i}}.
14255 The ten light parameters are as follows:
14258 @item @code{GL_AMBIENT}
14259 @var{params} contains four integer or floating-point values that specify
14260 the ambient RGBA intensity of the light. Integer values are mapped
14261 linearly such that the most positive representable value maps to 1.0,
14262 and the most negative representable value maps to @r{-1.0}.
14263 Floating-point values are mapped directly. Neither integer nor
14264 floating-point values are clamped. The initial ambient light intensity
14267 @item @code{GL_DIFFUSE}
14268 @var{params} contains four integer or floating-point values that specify
14269 the diffuse RGBA intensity of the light. Integer values are mapped
14270 linearly such that the most positive representable value maps to 1.0,
14271 and the most negative representable value maps to @r{-1.0}.
14272 Floating-point values are mapped directly. Neither integer nor
14273 floating-point values are clamped. The initial value for
14274 @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial value is
14277 @item @code{GL_SPECULAR}
14278 @var{params} contains four integer or floating-point values that specify
14279 the specular RGBA intensity of the light. Integer values are mapped
14280 linearly such that the most positive representable value maps to 1.0,
14281 and the most negative representable value maps to @r{-1.0}.
14282 Floating-point values are mapped directly. Neither integer nor
14283 floating-point values are clamped. The initial value for
14284 @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial value is
14287 @item @code{GL_POSITION}
14288 @var{params} contains four integer or floating-point values that specify
14289 the position of the light in homogeneous object coordinates. Both
14290 integer and floating-point values are mapped directly. Neither integer
14291 nor floating-point values are clamped.
14293 The position is transformed by the modelview matrix when @code{glLight}
14294 is called (just as if it were a point), and it is stored in eye
14295 coordinates. If the @r{@var{w}} component of the position is 0, the
14296 light is treated as a directional source. Diffuse and specular lighting
14297 calculations take the light's direction, but not its actual position,
14298 into account, and attenuation is disabled. Otherwise, diffuse and
14299 specular lighting calculations are based on the actual location of the
14300 light in eye coordinates, and attenuation is enabled. The initial
14301 position is (0, 0, 1, 0); thus, the initial light source is directional,
14302 parallel to, and in the direction of the @r{-@var{z}} axis.
14304 @item @code{GL_SPOT_DIRECTION}
14305 @var{params} contains three integer or floating-point values that
14306 specify the direction of the light in homogeneous object coordinates.
14307 Both integer and floating-point values are mapped directly. Neither
14308 integer nor floating-point values are clamped.
14310 The spot direction is transformed by the upper 3x3 of the modelview
14311 matrix when @code{glLight} is called, and it is stored in eye
14312 coordinates. It is significant only when @code{GL_SPOT_CUTOFF} is not
14313 180, which it is initially. The initial direction is @r{(0,0-1)}.
14315 @item @code{GL_SPOT_EXPONENT}
14316 @var{params} is a single integer or floating-point value that specifies
14317 the intensity distribution of the light. Integer and floating-point
14318 values are mapped directly. Only values in the range @r{[0,128]} are
14321 Effective light intensity is attenuated by the cosine of the angle
14322 between the direction of the light and the direction from the light to
14323 the vertex being lighted, raised to the power of the spot exponent.
14324 Thus, higher spot exponents result in a more focused light source,
14325 regardless of the spot cutoff angle (see @code{GL_SPOT_CUTOFF}, next
14326 paragraph). The initial spot exponent is 0, resulting in uniform light
14329 @item @code{GL_SPOT_CUTOFF}
14330 @var{params} is a single integer or floating-point value that specifies
14331 the maximum spread angle of a light source. Integer and floating-point
14332 values are mapped directly. Only values in the range @r{[0,90]} and the
14333 special value 180 are accepted. If the angle between the direction of
14334 the light and the direction from the light to the vertex being lighted
14335 is greater than the spot cutoff angle, the light is completely masked.
14336 Otherwise, its intensity is controlled by the spot exponent and the
14337 attenuation factors. The initial spot cutoff is 180, resulting in
14338 uniform light distribution.
14340 @item @code{GL_CONSTANT_ATTENUATION}
14341 @item @code{GL_LINEAR_ATTENUATION}
14342 @item @code{GL_QUADRATIC_ATTENUATION}
14343 @var{params} is a single integer or floating-point value that specifies
14344 one of the three light attenuation factors. Integer and floating-point
14345 values are mapped directly. Only nonnegative values are accepted. If the
14346 light is positional, rather than directional, its intensity is
14347 attenuated by the reciprocal of the sum of the constant factor, the
14348 linear factor times the distance between the light and the vertex being
14349 lighted, and the quadratic factor times the square of the same distance.
14350 The initial attenuation factors are (1, 0, 0), resulting in no
14355 @code{GL_INVALID_ENUM} is generated if either @var{light} or @var{pname}
14356 is not an accepted value.
14358 @code{GL_INVALID_VALUE} is generated if a spot exponent value is
14359 specified outside the range @r{[0,128]}, or if spot cutoff is specified
14360 outside the range @r{[0,90]} (except for the special value 180), or if a
14361 negative attenuation factor is specified.
14363 @code{GL_INVALID_OPERATION} is generated if @code{glLight} is executed
14364 between the execution of @code{glBegin} and the corresponding execution
14369 @deftypefun void glLineStipple factor pattern
14370 Specify the line stipple pattern.
14374 Specifies a multiplier for each bit in the line stipple pattern. If
14375 @var{factor} is 3, for example, each bit in the pattern is used three
14376 times before the next bit in the pattern is used. @var{factor} is
14377 clamped to the range [1, 256] and defaults to 1.
14379 @item @var{pattern}
14380 Specifies a 16-bit integer whose bit pattern determines which fragments
14381 of a line will be drawn when the line is rasterized. Bit zero is used
14382 first; the default pattern is all 1's.
14386 Line stippling masks out certain fragments produced by rasterization;
14387 those fragments will not be drawn. The masking is achieved by using
14388 three parameters: the 16-bit line stipple pattern @var{pattern}, the
14389 repeat count @var{factor}, and an integer stipple counter @r{@var{s}}.
14391 Counter @r{@var{s}} is reset to 0 whenever @code{glBegin} is called and
14392 before each line segment of a
14393 @code{glBegin}(@code{GL_LINES})/@code{glEnd} sequence is generated. It
14394 is incremented after each fragment of a unit width aliased line segment
14395 is generated or after each @r{@var{i}} fragments of an @r{@var{i}} width
14396 line segment are generated. The @r{@var{i}} fragments associated with
14397 count @r{@var{s}} are masked out if
14399 @var{pattern} bit @r{(@var{s}/@var{factor},)%16}
14401 is 0, otherwise these fragments are sent to the frame buffer. Bit zero
14402 of @var{pattern} is the least significant bit.
14404 Antialiased lines are treated as a sequence of @r{1×@var{width}}
14405 rectangles for purposes of stippling. Whether rectangle @r{@var{s}} is
14406 rasterized or not depends on the fragment rule described for aliased
14407 lines, counting rectangles rather than groups of fragments.
14409 To enable and disable line stippling, call @code{glEnable} and
14410 @code{glDisable} with argument @code{GL_LINE_STIPPLE}. When enabled, the
14411 line stipple pattern is applied as described above. When disabled, it is
14412 as if the pattern were all 1's. Initially, line stippling is disabled.
14414 @code{GL_INVALID_OPERATION} is generated if @code{glLineStipple} is
14415 executed between the execution of @code{glBegin} and the corresponding
14416 execution of @code{glEnd}.
14420 @deftypefun void glLineWidth width
14421 Specify the width of rasterized lines.
14425 Specifies the width of rasterized lines. The initial value is 1.
14429 @code{glLineWidth} specifies the rasterized width of both aliased and
14430 antialiased lines. Using a line width other than 1 has different
14431 effects, depending on whether line antialiasing is enabled. To enable
14432 and disable line antialiasing, call @code{glEnable} and @code{glDisable}
14433 with argument @code{GL_LINE_SMOOTH}. Line antialiasing is initially
14436 If line antialiasing is disabled, the actual width is determined by
14437 rounding the supplied width to the nearest integer. (If the rounding
14438 results in the value 0, it is as if the line width were 1.) If
14439 @r{∣Δ@var{x},∣>=∣Δ@var{y},∣}, @var{i} pixels are filled in each column
14440 that is rasterized, where @var{i} is the rounded value of @var{width}.
14441 Otherwise, @var{i} pixels are filled in each row that is rasterized.
14443 If antialiasing is enabled, line rasterization produces a fragment for
14444 each pixel square that intersects the region lying within the rectangle
14445 having width equal to the current line width, length equal to the actual
14446 length of the line, and centered on the mathematical line segment. The
14447 coverage value for each fragment is the window coordinate area of the
14448 intersection of the rectangular region with the corresponding pixel
14449 square. This value is saved and used in the final rasterization step.
14451 Not all widths can be supported when line antialiasing is enabled. If an
14452 unsupported width is requested, the nearest supported width is used.
14453 Only width 1 is guaranteed to be supported; others depend on the
14454 implementation. Likewise, there is a range for aliased line widths as
14455 well. To query the range of supported widths and the size difference
14456 between supported widths within the range, call @code{glGet} with
14457 arguments @code{GL_ALIASED_LINE_WIDTH_RANGE},
14458 @code{GL_SMOOTH_LINE_WIDTH_RANGE}, and
14459 @code{GL_SMOOTH_LINE_WIDTH_GRANULARITY}.
14461 @code{GL_INVALID_VALUE} is generated if @var{width} is less than or
14464 @code{GL_INVALID_OPERATION} is generated if @code{glLineWidth} is
14465 executed between the execution of @code{glBegin} and the corresponding
14466 execution of @code{glEnd}.
14470 @deftypefun void glLinkProgram program
14471 Links a program object.
14474 @item @var{program}
14475 Specifies the handle of the program object to be linked.
14479 @code{glLinkProgram} links the program object specified by
14480 @var{program}. If any shader objects of type @code{GL_VERTEX_SHADER} are
14481 attached to @var{program}, they will be used to create an executable
14482 that will run on the programmable vertex processor. If any shader
14483 objects of type @code{GL_FRAGMENT_SHADER} are attached to @var{program},
14484 they will be used to create an executable that will run on the
14485 programmable fragment processor.
14487 The status of the link operation will be stored as part of the program
14488 object's state. This value will be set to @code{GL_TRUE} if the program
14489 object was linked without errors and is ready for use, and
14490 @code{GL_FALSE} otherwise. It can be queried by calling
14491 @code{glGetProgram} with arguments @var{program} and
14492 @code{GL_LINK_STATUS}.
14494 As a result of a successful link operation, all active user-defined
14495 uniform variables belonging to @var{program} will be initialized to 0,
14496 and each of the program object's active uniform variables will be
14497 assigned a location that can be queried by calling
14498 @code{glGetUniformLocation}. Also, any active user-defined attribute
14499 variables that have not been bound to a generic vertex attribute index
14500 will be bound to one at this time.
14502 Linking of a program object can fail for a number of reasons as
14503 specified in the @var{OpenGL Shading Language Specification}. The
14504 following lists some of the conditions that will cause a link error.
14508 The number of active attribute variables supported by the implementation
14512 The storage limit for uniform variables has been exceeded.
14515 The number of active uniform variables supported by the implementation
14519 The @code{main} function is missing for the vertex shader or the
14523 A varying variable actually used in the fragment shader is not declared
14524 in the same way (or is not declared at all) in the vertex shader.
14527 A reference to a function or variable name is unresolved.
14530 A shared global is declared with two different types or two different
14534 One or more of the attached shader objects has not been successfully
14538 Binding a generic attribute matrix caused some rows of the matrix to
14539 fall outside the allowed maximum of @code{GL_MAX_VERTEX_ATTRIBS}.
14542 Not enough contiguous vertex attribute slots could be found to bind
14543 attribute matrices.
14547 When a program object has been successfully linked, the program object
14548 can be made part of current state by calling @code{glUseProgram}.
14549 Whether or not the link operation was successful, the program object's
14550 information log will be overwritten. The information log can be
14551 retrieved by calling @code{glGetProgramInfoLog}.
14553 @code{glLinkProgram} will also install the generated executables as part
14554 of the current rendering state if the link operation was successful and
14555 the specified program object is already currently in use as a result of
14556 a previous call to @code{glUseProgram}. If the program object currently
14557 in use is relinked unsuccessfully, its link status will be set to
14558 @code{GL_FALSE} , but the executables and associated state will remain
14559 part of the current state until a subsequent call to @code{glUseProgram}
14560 removes it from use. After it is removed from use, it cannot be made
14561 part of current state until it has been successfully relinked.
14563 If @var{program} contains shader objects of type @code{GL_VERTEX_SHADER}
14564 but does not contain shader objects of type @code{GL_FRAGMENT_SHADER},
14565 the vertex shader will be linked against the implicit interface for
14566 fixed functionality fragment processing. Similarly, if @var{program}
14567 contains shader objects of type @code{GL_FRAGMENT_SHADER} but it does
14568 not contain shader objects of type @code{GL_VERTEX_SHADER}, the fragment
14569 shader will be linked against the implicit interface for fixed
14570 functionality vertex processing.
14572 The program object's information log is updated and the program is
14573 generated at the time of the link operation. After the link operation,
14574 applications are free to modify attached shader objects, compile
14575 attached shader objects, detach shader objects, delete shader objects,
14576 and attach additional shader objects. None of these operations affects
14577 the information log or the program that is part of the program object.
14579 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
14580 generated by OpenGL.
14582 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
14585 @code{GL_INVALID_OPERATION} is generated if @code{glLinkProgram} is
14586 executed between the execution of @code{glBegin} and the corresponding
14587 execution of @code{glEnd}.
14591 @deftypefun void glListBase base
14592 Set the display-list base for .
14596 Specifies an integer offset that will be added to @code{glCallLists}
14597 offsets to generate display-list names. The initial value is 0.
14601 @code{glCallLists} specifies an array of offsets. Display-list names are
14602 generated by adding @var{base} to each offset. Names that reference
14603 valid display lists are executed; the others are ignored.
14605 @code{GL_INVALID_OPERATION} is generated if @code{glListBase} is
14606 executed between the execution of @code{glBegin} and the corresponding
14607 execution of @code{glEnd}.
14611 @deftypefun void glLoadIdentity
14612 Replace the current matrix with the identity matrix.
14614 @code{glLoadIdentity} replaces the current matrix with the identity
14615 matrix. It is semantically equivalent to calling @code{glLoadMatrix}
14616 with the identity matrix
14620 @r{((1 0 0 0), (0 1 0 0), (0 0 1 0), (0 0 0 1),,)}
14624 but in some cases it is more efficient.
14626 @code{GL_INVALID_OPERATION} is generated if @code{glLoadIdentity} is
14627 executed between the execution of @code{glBegin} and the corresponding
14628 execution of @code{glEnd}.
14632 @deftypefun void glLoadMatrixf m
14633 Replace the current matrix with the specified matrix.
14637 Specifies a pointer to 16 consecutive values, which are used as the
14638 elements of a @r{4×4} column-major matrix.
14642 @code{glLoadMatrix} replaces the current matrix with the one whose
14643 elements are specified by @var{m}. The current matrix is the projection
14644 matrix, modelview matrix, or texture matrix, depending on the current
14645 matrix mode (see @code{glMatrixMode}).
14647 The current matrix, M, defines a transformation of coordinates. For
14648 instance, assume M refers to the modelview matrix. If
14649 @r{@var{v}=(@var{v}[0,],@var{v}[1,]@var{v}[2,]@var{v}[3,])} is the
14650 set of object coordinates of a vertex, and @var{m} points to an array of
14651 @r{16} single- or double-precision floating-point values
14652 @r{@var{m}=@{@var{m}[0,],@var{m}[1,]@var{...}@var{m}[15,]@}}, then
14653 the modelview transformation @r{@var{M}(@var{v},)} does the following:
14655 @r{@var{M}(@var{v},)=((@var{m}[0,] @var{m}[4,] @var{m}[8,]
14656 @var{m}[12,]), (@var{m}[1,] @var{m}[5,] @var{m}[9,] @var{m}[13,]),
14657 (@var{m}[2,] @var{m}[6,] @var{m}[10,] @var{m}[14,]), (@var{m}[3,]
14658 @var{m}[7,] @var{m}[11,] @var{m}[15,]),)×((@var{v}[0,]),
14659 (@var{v}[1,]), (@var{v}[2,]), (@var{v}[3,]),)}
14663 Projection and texture transformations are similarly defined.
14665 @code{GL_INVALID_OPERATION} is generated if @code{glLoadMatrix} is
14666 executed between the execution of @code{glBegin} and the corresponding
14667 execution of @code{glEnd}.
14671 @deftypefun void glLoadName name
14672 Load a name onto the name stack.
14676 Specifies a name that will replace the top value on the name stack.
14680 The name stack is used during selection mode to allow sets of rendering
14681 commands to be uniquely identified. It consists of an ordered set of
14682 unsigned integers and is initially empty.
14684 @code{glLoadName} causes @var{name} to replace the value on the top of
14687 The name stack is always empty while the render mode is not
14688 @code{GL_SELECT}. Calls to @code{glLoadName} while the render mode is
14689 not @code{GL_SELECT} are ignored.
14691 @code{GL_INVALID_OPERATION} is generated if @code{glLoadName} is called
14692 while the name stack is empty.
14694 @code{GL_INVALID_OPERATION} is generated if @code{glLoadName} is
14695 executed between the execution of @code{glBegin} and the corresponding
14696 execution of @code{glEnd}.
14700 @deftypefun void glLoadTransposeMatrixf m
14701 Replace the current matrix with the specified row-major ordered matrix.
14705 Specifies a pointer to 16 consecutive values, which are used as the
14706 elements of a @r{4×4} row-major matrix.
14710 @code{glLoadTransposeMatrix} replaces the current matrix with the one
14711 whose elements are specified by @var{m}. The current matrix is the
14712 projection matrix, modelview matrix, or texture matrix, depending on the
14713 current matrix mode (see @code{glMatrixMode}).
14715 The current matrix, M, defines a transformation of coordinates. For
14716 instance, assume M refers to the modelview matrix. If
14717 @r{@var{v}=(@var{v}[0,],@var{v}[1,]@var{v}[2,]@var{v}[3,])} is the
14718 set of object coordinates of a vertex, and @var{m} points to an array of
14719 @r{16} single- or double-precision floating-point values
14720 @r{@var{m}=@{@var{m}[0,],@var{m}[1,]@var{...}@var{m}[15,]@}}, then
14721 the modelview transformation @r{@var{M}(@var{v},)} does the following:
14723 @r{@var{M}(@var{v},)=((@var{m}[0,] @var{m}[1,] @var{m}[2,]
14724 @var{m}[3,]), (@var{m}[4,] @var{m}[5,] @var{m}[6,] @var{m}[7,]),
14725 (@var{m}[8,] @var{m}[9,] @var{m}[10,] @var{m}[11,]), (@var{m}[12,]
14726 @var{m}[13,] @var{m}[14,] @var{m}[15,]),)×((@var{v}[0,]),
14727 (@var{v}[1,]), (@var{v}[2,]), (@var{v}[3,]),)}
14731 Projection and texture transformations are similarly defined.
14733 Calling @code{glLoadTransposeMatrix} with matrix @r{@var{M}} is
14734 identical in operation to @code{glLoadMatrix} with @r{@var{M}^@var{T}},
14735 where @r{@var{T}} represents the transpose.
14737 @code{GL_INVALID_OPERATION} is generated if @code{glLoadTransposeMatrix}
14738 is executed between the execution of @code{glBegin} and the
14739 corresponding execution of @code{glEnd}.
14743 @deftypefun void glLogicOp opcode
14744 Specify a logical pixel operation for color index rendering.
14748 Specifies a symbolic constant that selects a logical operation. The
14749 following symbols are accepted: @code{GL_CLEAR}, @code{GL_SET},
14750 @code{GL_COPY}, @code{GL_COPY_INVERTED}, @code{GL_NOOP},
14751 @code{GL_INVERT}, @code{GL_AND}, @code{GL_NAND}, @code{GL_OR},
14752 @code{GL_NOR}, @code{GL_XOR}, @code{GL_EQUIV}, @code{GL_AND_REVERSE},
14753 @code{GL_AND_INVERTED}, @code{GL_OR_REVERSE}, and @code{GL_OR_INVERTED}.
14754 The initial value is @code{GL_COPY}.
14758 @code{glLogicOp} specifies a logical operation that, when enabled, is
14759 applied between the incoming color index or RGBA color and the color
14760 index or RGBA color at the corresponding location in the frame buffer.
14761 To enable or disable the logical operation, call @code{glEnable} and
14762 @code{glDisable} using the symbolic constant @code{GL_COLOR_LOGIC_OP}
14763 for RGBA mode or @code{GL_INDEX_LOGIC_OP} for color index mode. The
14764 initial value is disabled for both operations.
14769 @item @strong{Opcode}
14770 @strong{Resulting Operation}
14772 @item @code{GL_CLEAR}
14775 @item @code{GL_SET}
14778 @item @code{GL_COPY}
14781 @item @code{GL_COPY_INVERTED}
14784 @item @code{GL_NOOP}
14787 @item @code{GL_INVERT}
14790 @item @code{GL_AND}
14793 @item @code{GL_NAND}
14799 @item @code{GL_NOR}
14802 @item @code{GL_XOR}
14805 @item @code{GL_EQUIV}
14808 @item @code{GL_AND_REVERSE}
14811 @item @code{GL_AND_INVERTED}
14814 @item @code{GL_OR_REVERSE}
14817 @item @code{GL_OR_INVERTED}
14822 @var{opcode} is a symbolic constant chosen from the list above. In the
14823 explanation of the logical operations, @var{s} represents the incoming
14824 color index and @var{d} represents the index in the frame buffer.
14825 Standard C-language operators are used. As these bitwise operators
14826 suggest, the logical operation is applied independently to each bit pair
14827 of the source and destination indices or colors.
14829 @code{GL_INVALID_ENUM} is generated if @var{opcode} is not an accepted
14832 @code{GL_INVALID_OPERATION} is generated if @code{glLogicOp} is executed
14833 between the execution of @code{glBegin} and the corresponding execution
14838 @deftypefun void glMap1f target u1 u2 stride order points
14839 Define a one-dimensional evaluator.
14843 Specifies the kind of values that are generated by the evaluator.
14844 Symbolic constants @code{GL_MAP1_VERTEX_3}, @code{GL_MAP1_VERTEX_4},
14845 @code{GL_MAP1_INDEX}, @code{GL_MAP1_COLOR_4}, @code{GL_MAP1_NORMAL},
14846 @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2},
14847 @code{GL_MAP1_TEXTURE_COORD_3}, and @code{GL_MAP1_TEXTURE_COORD_4} are
14852 Specify a linear mapping of @r{@var{u}}, as presented to
14853 @code{glEvalCoord1}, to @r{@var{u}^}, the variable that is evaluated by
14854 the equations specified by this command.
14857 Specifies the number of floats or doubles between the beginning of one
14858 control point and the beginning of the next one in the data structure
14859 referenced in @var{points}. This allows control points to be embedded in
14860 arbitrary data structures. The only constraint is that the values for a
14861 particular control point must occupy contiguous memory locations.
14864 Specifies the number of control points. Must be positive.
14867 Specifies a pointer to the array of control points.
14871 Evaluators provide a way to use polynomial or rational polynomial
14872 mapping to produce vertices, normals, texture coordinates, and colors.
14873 The values produced by an evaluator are sent to further stages of GL
14874 processing just as if they had been presented using @code{glVertex},
14875 @code{glNormal}, @code{glTexCoord}, and @code{glColor} commands, except
14876 that the generated values do not update the current normal, texture
14877 coordinates, or color.
14879 All polynomial or rational polynomial splines of any degree (up to the
14880 maximum degree supported by the GL implementation) can be described
14881 using evaluators. These include almost all splines used in computer
14882 graphics: B-splines, Bezier curves, Hermite splines, and so on.
14884 Evaluators define curves based on Bernstein polynomials. Define
14885 @r{@var{p}(@var{u}^,)} as
14887 @r{@var{p}(@var{u}^,)=Σ@var{i}=0@var{n}@var{B}_@var{i},^@var{n}(@var{u}^,)@var{R}_@var{i}}
14891 where @r{@var{R}_@var{i}} is a control point and
14892 @r{@var{B}_@var{i},^@var{n}(@var{u}^,)} is the @r{@var{i}}th Bernstein
14893 polynomial of degree @r{@var{n}} (@var{order} = @r{@var{n}+1}):
14895 @r{@var{B}_@var{i},^@var{n}(@var{u}^,)=((@var{n}),
14896 (@var{i}),,)@var{u}^,^@var{i}(1-@var{u}^,)^@var{n}-@var{i},,}
14900 @r{0^0==1} and @r{((@var{n}), (0),,)==1}
14902 @code{glMap1} is used to define the basis and to specify what kind of
14903 values are produced. Once defined, a map can be enabled and disabled by
14904 calling @code{glEnable} and @code{glDisable} with the map name, one of
14905 the nine predefined values for @var{target} described below.
14906 @code{glEvalCoord1} evaluates the one-dimensional maps that are enabled.
14907 When @code{glEvalCoord1} presents a value @r{@var{u}}, the Bernstein
14908 functions are evaluated using @r{@var{u}^}, where
14909 @r{@var{u}^=@var{u}-@var{u1},/@var{u2}-@var{u1},}
14911 @var{target} is a symbolic constant that indicates what kind of control
14912 points are provided in @var{points}, and what output is generated when
14913 the map is evaluated. It can assume one of nine predefined values:
14916 @item @code{GL_MAP1_VERTEX_3}
14917 Each control point is three floating-point values representing
14918 @r{@var{x}}, @r{@var{y}}, and @r{@var{z}}. Internal @code{glVertex3}
14919 commands are generated when the map is evaluated.
14921 @item @code{GL_MAP1_VERTEX_4}
14922 Each control point is four floating-point values representing
14923 @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}. Internal
14924 @code{glVertex4} commands are generated when the map is evaluated.
14926 @item @code{GL_MAP1_INDEX}
14927 Each control point is a single floating-point value representing a color
14928 index. Internal @code{glIndex} commands are generated when the map is
14929 evaluated but the current index is not updated with the value of these
14930 @code{glIndex} commands.
14932 @item @code{GL_MAP1_COLOR_4}
14933 Each control point is four floating-point values representing red,
14934 green, blue, and alpha. Internal @code{glColor4} commands are generated
14935 when the map is evaluated but the current color is not updated with the
14936 value of these @code{glColor4} commands.
14938 @item @code{GL_MAP1_NORMAL}
14939 Each control point is three floating-point values representing the
14940 @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} components of a normal vector.
14941 Internal @code{glNormal} commands are generated when the map is
14942 evaluated but the current normal is not updated with the value of these
14943 @code{glNormal} commands.
14945 @item @code{GL_MAP1_TEXTURE_COORD_1}
14946 Each control point is a single floating-point value representing the
14947 @r{@var{s}} texture coordinate. Internal @code{glTexCoord1} commands are
14948 generated when the map is evaluated but the current texture coordinates
14949 are not updated with the value of these @code{glTexCoord} commands.
14951 @item @code{GL_MAP1_TEXTURE_COORD_2}
14952 Each control point is two floating-point values representing the
14953 @r{@var{s}} and @r{@var{t}} texture coordinates. Internal
14954 @code{glTexCoord2} commands are generated when the map is evaluated but
14955 the current texture coordinates are not updated with the value of these
14956 @code{glTexCoord} commands.
14958 @item @code{GL_MAP1_TEXTURE_COORD_3}
14959 Each control point is three floating-point values representing the
14960 @r{@var{s}}, @r{@var{t}}, and @r{@var{r}} texture coordinates. Internal
14961 @code{glTexCoord3} commands are generated when the map is evaluated but
14962 the current texture coordinates are not updated with the value of these
14963 @code{glTexCoord} commands.
14965 @item @code{GL_MAP1_TEXTURE_COORD_4}
14966 Each control point is four floating-point values representing the
14967 @r{@var{s}}, @r{@var{t}}, @r{@var{r}}, and @r{@var{q}} texture
14968 coordinates. Internal @code{glTexCoord4} commands are generated when the
14969 map is evaluated but the current texture coordinates are not updated
14970 with the value of these @code{glTexCoord} commands.
14974 @var{stride}, @var{order}, and @var{points} define the array addressing
14975 for accessing the control points. @var{points} is the location of the
14976 first control point, which occupies one, two, three, or four contiguous
14977 memory locations, depending on which map is being defined. @var{order}
14978 is the number of control points in the array. @var{stride} specifies how
14979 many float or double locations to advance the internal memory pointer to
14980 reach the next control point.
14982 @code{GL_INVALID_ENUM} is generated if @var{target} is not an accepted
14985 @code{GL_INVALID_VALUE} is generated if @var{u1} is equal to @var{u2}.
14987 @code{GL_INVALID_VALUE} is generated if @var{stride} is less than the
14988 number of values in a control point.
14990 @code{GL_INVALID_VALUE} is generated if @var{order} is less than 1 or
14991 greater than the return value of @code{GL_MAX_EVAL_ORDER}.
14993 @code{GL_INVALID_OPERATION} is generated if @code{glMap1} is executed
14994 between the execution of @code{glBegin} and the corresponding execution
14997 @code{GL_INVALID_OPERATION} is generated if @code{glMap1} is called and
14998 the value of @code{GL_ACTIVE_TEXTURE} is not @code{GL_TEXTURE0}.
15002 @deftypefun void glMap2f target u1 u2 ustride uorder v1 v2 vstride vorder points
15003 Define a two-dimensional evaluator.
15007 Specifies the kind of values that are generated by the evaluator.
15008 Symbolic constants @code{GL_MAP2_VERTEX_3}, @code{GL_MAP2_VERTEX_4},
15009 @code{GL_MAP2_INDEX}, @code{GL_MAP2_COLOR_4}, @code{GL_MAP2_NORMAL},
15010 @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2},
15011 @code{GL_MAP2_TEXTURE_COORD_3}, and @code{GL_MAP2_TEXTURE_COORD_4} are
15016 Specify a linear mapping of @r{@var{u}}, as presented to
15017 @code{glEvalCoord2}, to @r{@var{u}^}, one of the two variables that are
15018 evaluated by the equations specified by this command. Initially,
15019 @var{u1} is 0 and @var{u2} is 1.
15021 @item @var{ustride}
15022 Specifies the number of floats or doubles between the beginning of
15023 control point @r{@var{R}_@var{ij}} and the beginning of control point
15024 @r{@var{R}_(@var{i}+1,)@var{j},}, where @r{@var{i}} and @r{@var{j}} are
15025 the @r{@var{u}} and @r{@var{v}} control point indices, respectively.
15026 This allows control points to be embedded in arbitrary data structures.
15027 The only constraint is that the values for a particular control point
15028 must occupy contiguous memory locations. The initial value of
15029 @var{ustride} is 0.
15032 Specifies the dimension of the control point array in the @r{@var{u}}
15033 axis. Must be positive. The initial value is 1.
15037 Specify a linear mapping of @r{@var{v}}, as presented to
15038 @code{glEvalCoord2}, to @r{@var{v}^}, one of the two variables that are
15039 evaluated by the equations specified by this command. Initially,
15040 @var{v1} is 0 and @var{v2} is 1.
15042 @item @var{vstride}
15043 Specifies the number of floats or doubles between the beginning of
15044 control point @r{@var{R}_@var{ij}} and the beginning of control point
15045 @r{@var{R}_@var{i}(@var{j}+1,),}, where @r{@var{i}} and @r{@var{j}} are
15046 the @r{@var{u}} and @r{@var{v}} control point indices, respectively.
15047 This allows control points to be embedded in arbitrary data structures.
15048 The only constraint is that the values for a particular control point
15049 must occupy contiguous memory locations. The initial value of
15050 @var{vstride} is 0.
15053 Specifies the dimension of the control point array in the @r{@var{v}}
15054 axis. Must be positive. The initial value is 1.
15057 Specifies a pointer to the array of control points.
15061 Evaluators provide a way to use polynomial or rational polynomial
15062 mapping to produce vertices, normals, texture coordinates, and colors.
15063 The values produced by an evaluator are sent on to further stages of GL
15064 processing just as if they had been presented using @code{glVertex},
15065 @code{glNormal}, @code{glTexCoord}, and @code{glColor} commands, except
15066 that the generated values do not update the current normal, texture
15067 coordinates, or color.
15069 All polynomial or rational polynomial splines of any degree (up to the
15070 maximum degree supported by the GL implementation) can be described
15071 using evaluators. These include almost all surfaces used in computer
15072 graphics, including B-spline surfaces, NURBS surfaces, Bezier surfaces,
15075 Evaluators define surfaces based on bivariate Bernstein polynomials.
15076 Define @r{@var{p}(@var{u}^,@var{v}^)} as
15078 @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}}
15082 where @r{@var{R}_@var{ij}} is a control point,
15083 @r{@var{B}_@var{i},^@var{n}(@var{u}^,)} is the @r{@var{i}}th Bernstein
15084 polynomial of degree @r{@var{n}} (@var{uorder} = @r{@var{n}+1})
15086 @r{@var{B}_@var{i},^@var{n}(@var{u}^,)=((@var{n}),
15087 (@var{i}),,)@var{u}^,^@var{i}(1-@var{u}^,)^@var{n}-@var{i},,}
15089 and @r{@var{B}_@var{j},^@var{m}(@var{v}^,)} is the @r{@var{j}}th
15090 Bernstein polynomial of degree @r{@var{m}} (@var{vorder} =
15093 @r{@var{B}_@var{j},^@var{m}(@var{v}^,)=((@var{m}),
15094 (@var{j}),,)@var{v}^,^@var{j}(1-@var{v}^,)^@var{m}-@var{j},,}
15096 Recall that @r{0^0==1} and @r{((@var{n}), (0),,)==1}
15098 @code{glMap2} is used to define the basis and to specify what kind of
15099 values are produced. Once defined, a map can be enabled and disabled by
15100 calling @code{glEnable} and @code{glDisable} with the map name, one of
15101 the nine predefined values for @var{target}, described below. When
15102 @code{glEvalCoord2} presents values @r{@var{u}} and @r{@var{v}}, the
15103 bivariate Bernstein polynomials are evaluated using @r{@var{u}^} and
15104 @r{@var{v}^}, where
15106 @r{@var{u}^=@var{u}-@var{u1},/@var{u2}-@var{u1},}
15108 @r{@var{v}^=@var{v}-@var{v1},/@var{v2}-@var{v1},}
15110 @var{target} is a symbolic constant that indicates what kind of control
15111 points are provided in @var{points}, and what output is generated when
15112 the map is evaluated. It can assume one of nine predefined values:
15115 @item @code{GL_MAP2_VERTEX_3}
15116 Each control point is three floating-point values representing
15117 @r{@var{x}}, @r{@var{y}}, and @r{@var{z}}. Internal @code{glVertex3}
15118 commands are generated when the map is evaluated.
15120 @item @code{GL_MAP2_VERTEX_4}
15121 Each control point is four floating-point values representing
15122 @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}. Internal
15123 @code{glVertex4} commands are generated when the map is evaluated.
15125 @item @code{GL_MAP2_INDEX}
15126 Each control point is a single floating-point value representing a color
15127 index. Internal @code{glIndex} commands are generated when the map is
15128 evaluated but the current index is not updated with the value of these
15129 @code{glIndex} commands.
15131 @item @code{GL_MAP2_COLOR_4}
15132 Each control point is four floating-point values representing red,
15133 green, blue, and alpha. Internal @code{glColor4} commands are generated
15134 when the map is evaluated but the current color is not updated with the
15135 value of these @code{glColor4} commands.
15137 @item @code{GL_MAP2_NORMAL}
15138 Each control point is three floating-point values representing the
15139 @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} components of a normal vector.
15140 Internal @code{glNormal} commands are generated when the map is
15141 evaluated but the current normal is not updated with the value of these
15142 @code{glNormal} commands.
15144 @item @code{GL_MAP2_TEXTURE_COORD_1}
15145 Each control point is a single floating-point value representing the
15146 @r{@var{s}} texture coordinate. Internal @code{glTexCoord1} commands are
15147 generated when the map is evaluated but the current texture coordinates
15148 are not updated with the value of these @code{glTexCoord} commands.
15150 @item @code{GL_MAP2_TEXTURE_COORD_2}
15151 Each control point is two floating-point values representing the
15152 @r{@var{s}} and @r{@var{t}} texture coordinates. Internal
15153 @code{glTexCoord2} commands are generated when the map is evaluated but
15154 the current texture coordinates are not updated with the value of these
15155 @code{glTexCoord} commands.
15157 @item @code{GL_MAP2_TEXTURE_COORD_3}
15158 Each control point is three floating-point values representing the
15159 @r{@var{s}}, @r{@var{t}}, and @r{@var{r}} texture coordinates. Internal
15160 @code{glTexCoord3} commands are generated when the map is evaluated but
15161 the current texture coordinates are not updated with the value of these
15162 @code{glTexCoord} commands.
15164 @item @code{GL_MAP2_TEXTURE_COORD_4}
15165 Each control point is four floating-point values representing the
15166 @r{@var{s}}, @r{@var{t}}, @r{@var{r}}, and @r{@var{q}} texture
15167 coordinates. Internal @code{glTexCoord4} commands are generated when the
15168 map is evaluated but the current texture coordinates are not updated
15169 with the value of these @code{glTexCoord} commands.
15173 @var{ustride}, @var{uorder}, @var{vstride}, @var{vorder}, and
15174 @var{points} define the array addressing for accessing the control
15175 points. @var{points} is the location of the first control point, which
15176 occupies one, two, three, or four contiguous memory locations, depending
15177 on which map is being defined. There are @r{@var{uorder}×@var{vorder}}
15178 control points in the array. @var{ustride} specifies how many float or
15179 double locations are skipped to advance the internal memory pointer from
15180 control point @r{@var{R}_@var{i}@var{j},} to control point
15181 @r{@var{R}_(@var{i}+1,)@var{j},}. @var{vstride} specifies how many
15182 float or double locations are skipped to advance the internal memory
15183 pointer from control point @r{@var{R}_@var{i}@var{j},} to control point
15184 @r{@var{R}_@var{i}(@var{j}+1,),}.
15186 @code{GL_INVALID_ENUM} is generated if @var{target} is not an accepted
15189 @code{GL_INVALID_VALUE} is generated if @var{u1} is equal to @var{u2},
15190 or if @var{v1} is equal to @var{v2}.
15192 @code{GL_INVALID_VALUE} is generated if either @var{ustride} or
15193 @var{vstride} is less than the number of values in a control point.
15195 @code{GL_INVALID_VALUE} is generated if either @var{uorder} or
15196 @var{vorder} is less than 1 or greater than the return value of
15197 @code{GL_MAX_EVAL_ORDER}.
15199 @code{GL_INVALID_OPERATION} is generated if @code{glMap2} is executed
15200 between the execution of @code{glBegin} and the corresponding execution
15203 @code{GL_INVALID_OPERATION} is generated if @code{glMap2} is called and
15204 the value of @code{GL_ACTIVE_TEXTURE} is not @code{GL_TEXTURE0}.
15208 @deftypefun void-* glMapBuffer target access
15209 @deftypefunx GLboolean glUnmapBuffer target
15210 Map a buffer object's data store.
15214 Specifies the target buffer object being mapped. The symbolic constant
15215 must be @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
15216 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
15219 Specifies the access policy, indicating whether it will be possible to
15220 read from, write to, or both read from and write to the buffer object's
15221 mapped data store. The symbolic constant must be @code{GL_READ_ONLY},
15222 @code{GL_WRITE_ONLY}, or @code{GL_READ_WRITE}.
15226 @code{glMapBuffer} maps to the client's address space the entire data
15227 store of the buffer object currently bound to @var{target}. The data can
15228 then be directly read and/or written relative to the returned pointer,
15229 depending on the specified @var{access} policy. If the GL is unable to
15230 map the buffer object's data store, @code{glMapBuffer} generates an
15231 error and returns @code{NULL}. This may occur for system-specific
15232 reasons, such as low virtual memory availability.
15234 If a mapped data store is accessed in a way inconsistent with the
15235 specified @var{access} policy, no error is generated, but performance
15236 may be negatively impacted and system errors, including program
15237 termination, may result. Unlike the @var{usage} parameter of
15238 @code{glBufferData}, @var{access} is not a hint, and does in fact
15239 constrain the usage of the mapped data store on some GL implementations.
15240 In order to achieve the highest performance available, a buffer object's
15241 data store should be used in ways consistent with both its specified
15242 @var{usage} and @var{access} parameters.
15244 A mapped data store must be unmapped with @code{glUnmapBuffer} before
15245 its buffer object is used. Otherwise an error will be generated by any
15246 GL command that attempts to dereference the buffer object's data store.
15247 When a data store is unmapped, the pointer to its data store becomes
15248 invalid. @code{glUnmapBuffer} returns @code{GL_TRUE} unless the data
15249 store contents have become corrupt during the time the data store was
15250 mapped. This can occur for system-specific reasons that affect the
15251 availability of graphics memory, such as screen mode changes. In such
15252 situations, @code{GL_FALSE} is returned and the data store contents are
15253 undefined. An application must detect this rare condition and
15254 reinitialize the data store.
15256 A buffer object's mapped data store is automatically unmapped when the
15257 buffer object is deleted or its data store is recreated with
15258 @code{glBufferData}.
15260 @code{GL_INVALID_ENUM} is generated if @var{target} is not
15261 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
15262 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
15264 @code{GL_INVALID_ENUM} is generated if @var{access} is not
15265 @code{GL_READ_ONLY}, @code{GL_WRITE_ONLY}, or @code{GL_READ_WRITE}.
15267 @code{GL_OUT_OF_MEMORY} is generated when @code{glMapBuffer} is executed
15268 if the GL is unable to map the buffer object's data store. This may
15269 occur for a variety of system-specific reasons, such as the absence of
15270 sufficient remaining virtual memory.
15272 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
15273 name 0 is bound to @var{target}.
15275 @code{GL_INVALID_OPERATION} is generated if @code{glMapBuffer} is
15276 executed for a buffer object whose data store is already mapped.
15278 @code{GL_INVALID_OPERATION} is generated if @code{glUnmapBuffer} is
15279 executed for a buffer object whose data store is not currently mapped.
15281 @code{GL_INVALID_OPERATION} is generated if @code{glMapBuffer} or
15282 @code{glUnmapBuffer} is executed between the execution of @code{glBegin}
15283 and the corresponding execution of @code{glEnd}.
15287 @deftypefun void glMapGrid1f un u1 u2
15288 @deftypefunx void glMapGrid2f un u1 u2 vn v1 v2
15289 Define a one- or two-dimensional mesh.
15293 Specifies the number of partitions in the grid range interval [@var{u1},
15294 @var{u2}]. Must be positive.
15298 Specify the mappings for integer grid domain values @r{@var{i}=0} and
15299 @r{@var{i}=@var{un}}.
15302 Specifies the number of partitions in the grid range interval [@var{v1},
15303 @var{v2}] (@code{glMapGrid2} only).
15307 Specify the mappings for integer grid domain values @r{@var{j}=0} and
15308 @r{@var{j}=@var{vn}} (@code{glMapGrid2} only).
15312 @code{glMapGrid} and @code{glEvalMesh} are used together to efficiently
15313 generate and evaluate a series of evenly-spaced map domain values.
15314 @code{glEvalMesh} steps through the integer domain of a one- or
15315 two-dimensional grid, whose range is the domain of the evaluation maps
15316 specified by @code{glMap1} and @code{glMap2}.
15318 @code{glMapGrid1} and @code{glMapGrid2} specify the linear grid mappings
15319 between the @r{@var{i}} (or @r{@var{i}} and @r{@var{j}}) integer grid
15320 coordinates, to the @r{@var{u}} (or @r{@var{u}} and @r{@var{v}})
15321 floating-point evaluation map coordinates. See @code{glMap1} and
15322 @code{glMap2} for details of how @r{@var{u}} and @r{@var{v}} coordinates
15325 @code{glMapGrid1} specifies a single linear mapping such that integer
15326 grid coordinate 0 maps exactly to @var{u1}, and integer grid coordinate
15327 @var{un} maps exactly to @var{u2}. All other integer grid coordinates
15328 @r{@var{i}} are mapped so that
15330 @r{@var{u}=@var{i}(@var{u2}-@var{u1},)/@var{un}+@var{u1}}
15332 @code{glMapGrid2} specifies two such linear mappings. One maps integer
15333 grid coordinate @r{@var{i}=0} exactly to @var{u1}, and integer grid
15334 coordinate @r{@var{i}=@var{un}} exactly to @var{u2}. The other maps
15335 integer grid coordinate @r{@var{j}=0} exactly to @var{v1}, and integer
15336 grid coordinate @r{@var{j}=@var{vn}} exactly to @var{v2}. Other integer
15337 grid coordinates @r{@var{i}} and @r{@var{j}} are mapped such that
15339 @r{@var{u}=@var{i}(@var{u2}-@var{u1},)/@var{un}+@var{u1}}
15341 @r{@var{v}=@var{j}(@var{v2}-@var{v1},)/@var{vn}+@var{v1}}
15343 The mappings specified by @code{glMapGrid} are used identically by
15344 @code{glEvalMesh} and @code{glEvalPoint}.
15346 @code{GL_INVALID_VALUE} is generated if either @var{un} or @var{vn} is
15349 @code{GL_INVALID_OPERATION} is generated if @code{glMapGrid} is executed
15350 between the execution of @code{glBegin} and the corresponding execution
15355 @deftypefun void glMaterialf face pname param
15356 @deftypefunx void glMateriali face pname param
15357 Specify material parameters for the lighting model.
15361 Specifies which face or faces are being updated. Must be one of
15362 @code{GL_FRONT}, @code{GL_BACK}, or @code{GL_FRONT_AND_BACK}.
15365 Specifies the single-valued material parameter of the face or faces that
15366 is being updated. Must be @code{GL_SHININESS}.
15369 Specifies the value that parameter @code{GL_SHININESS} will be set to.
15373 @code{glMaterial} assigns values to material parameters. There are two
15374 matched sets of material parameters. One, the @var{front-facing} set, is
15375 used to shade points, lines, bitmaps, and all polygons (when two-sided
15376 lighting is disabled), or just front-facing polygons (when two-sided
15377 lighting is enabled). The other set, @var{back-facing}, is used to shade
15378 back-facing polygons only when two-sided lighting is enabled. Refer to
15379 the @code{glLightModel} reference page for details concerning one- and
15380 two-sided lighting calculations.
15382 @code{glMaterial} takes three arguments. The first, @var{face},
15383 specifies whether the @code{GL_FRONT} materials, the @code{GL_BACK}
15384 materials, or both @code{GL_FRONT_AND_BACK} materials will be modified.
15385 The second, @var{pname}, specifies which of several parameters in one or
15386 both sets will be modified. The third, @var{params}, specifies what
15387 value or values will be assigned to the specified parameter.
15389 Material parameters are used in the lighting equation that is optionally
15390 applied to each vertex. The equation is discussed in the
15391 @code{glLightModel} reference page. The parameters that can be specified
15392 using @code{glMaterial}, and their interpretations by the lighting
15393 equation, are as follows:
15396 @item @code{GL_AMBIENT}
15397 @var{params} contains four integer or floating-point values that specify
15398 the ambient RGBA reflectance of the material. Integer values are mapped
15399 linearly such that the most positive representable value maps to 1.0,
15400 and the most negative representable value maps to @r{-1.0}.
15401 Floating-point values are mapped directly. Neither integer nor
15402 floating-point values are clamped. The initial ambient reflectance for
15403 both front- and back-facing materials is (0.2, 0.2, 0.2, 1.0).
15405 @item @code{GL_DIFFUSE}
15406 @var{params} contains four integer or floating-point values that specify
15407 the diffuse RGBA reflectance of the material. Integer values are mapped
15408 linearly such that the most positive representable value maps to 1.0,
15409 and the most negative representable value maps to @r{-1.0}.
15410 Floating-point values are mapped directly. Neither integer nor
15411 floating-point values are clamped. The initial diffuse reflectance for
15412 both front- and back-facing materials is (0.8, 0.8, 0.8, 1.0).
15414 @item @code{GL_SPECULAR}
15415 @var{params} contains four integer or floating-point values that specify
15416 the specular RGBA reflectance of the material. Integer values are mapped
15417 linearly such that the most positive representable value maps to 1.0,
15418 and the most negative representable value maps to @r{-1.0}.
15419 Floating-point values are mapped directly. Neither integer nor
15420 floating-point values are clamped. The initial specular reflectance for
15421 both front- and back-facing materials is (0, 0, 0, 1).
15423 @item @code{GL_EMISSION}
15424 @var{params} contains four integer or floating-point values that specify
15425 the RGBA emitted light intensity of the material. Integer values are
15426 mapped linearly such that the most positive representable value maps to
15427 1.0, and the most negative representable value maps to @r{-1.0}.
15428 Floating-point values are mapped directly. Neither integer nor
15429 floating-point values are clamped. The initial emission intensity for
15430 both front- and back-facing materials is (0, 0, 0, 1).
15432 @item @code{GL_SHININESS}
15433 @var{params} is a single integer or floating-point value that specifies
15434 the RGBA specular exponent of the material. Integer and floating-point
15435 values are mapped directly. Only values in the range @r{[0,128]} are
15436 accepted. The initial specular exponent for both front- and back-facing
15439 @item @code{GL_AMBIENT_AND_DIFFUSE}
15440 Equivalent to calling @code{glMaterial} twice with the same parameter
15441 values, once with @code{GL_AMBIENT} and once with @code{GL_DIFFUSE}.
15443 @item @code{GL_COLOR_INDEXES}
15444 @var{params} contains three integer or floating-point values specifying
15445 the color indices for ambient, diffuse, and specular lighting. These
15446 three values, and @code{GL_SHININESS}, are the only material values used
15447 by the color index mode lighting equation. Refer to the
15448 @code{glLightModel} reference page for a discussion of color index
15453 @code{GL_INVALID_ENUM} is generated if either @var{face} or @var{pname}
15454 is not an accepted value.
15456 @code{GL_INVALID_VALUE} is generated if a specular exponent outside the
15457 range @r{[0,128]} is specified.
15461 @deftypefun void glMatrixMode mode
15462 Specify which matrix is the current matrix.
15466 Specifies which matrix stack is the target for subsequent matrix
15467 operations. Three values are accepted: @code{GL_MODELVIEW},
15468 @code{GL_PROJECTION}, and @code{GL_TEXTURE}. The initial value is
15469 @code{GL_MODELVIEW}. Additionally, if the @code{ARB_imaging} extension
15470 is supported, @code{GL_COLOR} is also accepted.
15474 @code{glMatrixMode} sets the current matrix mode. @var{mode} can assume
15475 one of four values:
15478 @item @code{GL_MODELVIEW}
15479 Applies subsequent matrix operations to the modelview matrix stack.
15481 @item @code{GL_PROJECTION}
15482 Applies subsequent matrix operations to the projection matrix stack.
15484 @item @code{GL_TEXTURE}
15485 Applies subsequent matrix operations to the texture matrix stack.
15487 @item @code{GL_COLOR}
15488 Applies subsequent matrix operations to the color matrix stack.
15492 To find out which matrix stack is currently the target of all matrix
15493 operations, call @code{glGet} with argument @code{GL_MATRIX_MODE}. The
15494 initial value is @code{GL_MODELVIEW}.
15496 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
15499 @code{GL_INVALID_OPERATION} is generated if @code{glMatrixMode} is
15500 executed between the execution of @code{glBegin} and the corresponding
15501 execution of @code{glEnd}.
15505 @deftypefun void glMinmax target internalformat sink
15506 Define minmax table.
15510 The minmax table whose parameters are to be set. Must be
15513 @item @var{internalformat}
15514 The format of entries in the minmax table. Must be one of
15515 @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
15516 @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
15517 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
15518 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
15519 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
15520 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
15521 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
15522 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
15523 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
15524 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
15525 @code{GL_RGBA12}, or @code{GL_RGBA16}.
15528 If @code{GL_TRUE}, pixels will be consumed by the minmax process and no
15529 drawing or texture loading will take place. If @code{GL_FALSE}, pixels
15530 will proceed to the final conversion process after minmax.
15534 When @code{GL_MINMAX} is enabled, the RGBA components of incoming pixels
15535 are compared to the minimum and maximum values for each component, which
15536 are stored in the two-element minmax table. (The first element stores
15537 the minima, and the second element stores the maxima.) If a pixel
15538 component is greater than the corresponding component in the maximum
15539 element, then the maximum element is updated with the pixel component
15540 value. If a pixel component is less than the corresponding component in
15541 the minimum element, then the minimum element is updated with the pixel
15542 component value. (In both cases, if the internal format of the minmax
15543 table includes luminance, then the R color component of incoming pixels
15544 is used for comparison.) The contents of the minmax table may be
15545 retrieved at a later time by calling @code{glGetMinmax}. The minmax
15546 operation is enabled or disabled by calling @code{glEnable} or
15547 @code{glDisable}, respectively, with an argument of @code{GL_MINMAX}.
15549 @code{glMinmax} redefines the current minmax table to have entries of
15550 the format specified by @var{internalformat}. The maximum element is
15551 initialized with the smallest possible component values, and the minimum
15552 element is initialized with the largest possible component values. The
15553 values in the previous minmax table, if any, are lost. If @var{sink} is
15554 @code{GL_TRUE}, then pixels are discarded after minmax; no further
15555 processing of the pixels takes place, and no drawing, texture loading,
15556 or pixel readback will result.
15560 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
15563 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
15564 of the allowable values.
15566 @code{GL_INVALID_OPERATION} is generated if @code{glMinmax} is executed
15567 between the execution of @code{glBegin} and the corresponding execution
15572 @deftypefun void glMultiDrawArrays mode first count primcount
15573 Render multiple sets of primitives from array data.
15577 Specifies what kind of primitives to render. Symbolic constants
15578 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
15579 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
15580 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
15581 @code{GL_POLYGON} are accepted.
15584 Points to an array of starting indices in the enabled arrays.
15587 Points to an array of the number of indices to be rendered.
15589 @item @var{primcount}
15590 Specifies the size of the first and count
15594 @code{glMultiDrawArrays} specifies multiple sets of geometric primitives
15595 with very few subroutine calls. Instead of calling a GL procedure to
15596 pass each individual vertex, normal, texture coordinate, edge flag, or
15597 color, you can prespecify separate arrays of vertices, normals, and
15598 colors and use them to construct a sequence of primitives with a single
15599 call to @code{glMultiDrawArrays}.
15601 @code{glMultiDrawArrays} behaves identically to @code{glDrawArrays}
15602 except that @var{primcount} separate ranges of elements are specified
15605 When @code{glMultiDrawArrays} is called, it uses @var{count} sequential
15606 elements from each enabled array to construct a sequence of geometric
15607 primitives, beginning with element @var{first}. @var{mode} specifies
15608 what kind of primitives are constructed, and how the array elements
15609 construct those primitives. If @code{GL_VERTEX_ARRAY} is not enabled, no
15610 geometric primitives are generated.
15612 Vertex attributes that are modified by @code{glMultiDrawArrays} have an
15613 unspecified value after @code{glMultiDrawArrays} returns. For example,
15614 if @code{GL_COLOR_ARRAY} is enabled, the value of the current color is
15615 undefined after @code{glMultiDrawArrays} executes. Attributes that
15616 aren't modified remain well defined.
15618 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
15621 @code{GL_INVALID_VALUE} is generated if @var{primcount} is negative.
15623 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
15624 name is bound to an enabled array and the buffer object's data store is
15627 @code{GL_INVALID_OPERATION} is generated if @code{glMultiDrawArrays} is
15628 executed between the execution of @code{glBegin} and the corresponding
15633 @deftypefun void glMultiDrawElements mode count type indices primcount
15634 Render multiple sets of primitives by specifying indices of array data
15639 Specifies what kind of primitives to render. Symbolic constants
15640 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
15641 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
15642 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
15643 @code{GL_POLYGON} are accepted.
15646 Points to an array of the elements counts.
15649 Specifies the type of the values in @var{indices}. Must be one of
15650 @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or
15651 @code{GL_UNSIGNED_INT}.
15653 @item @var{indices}
15654 Specifies a pointer to the location where the indices are stored.
15656 @item @var{primcount}
15657 Specifies the size of the @var{count} array.
15661 @code{glMultiDrawElements} specifies multiple sets of geometric
15662 primitives with very few subroutine calls. Instead of calling a GL
15663 function to pass each individual vertex, normal, texture coordinate,
15664 edge flag, or color, you can prespecify separate arrays of vertices,
15665 normals, and so on, and use them to construct a sequence of primitives
15666 with a single call to @code{glMultiDrawElements}.
15668 @code{glMultiDrawElements} is identical in operation to
15669 @code{glDrawElements} except that @var{primcount} separate lists of
15670 elements are specified.
15672 Vertex attributes that are modified by @code{glMultiDrawElements} have
15673 an unspecified value after @code{glMultiDrawElements} returns. For
15674 example, if @code{GL_COLOR_ARRAY} is enabled, the value of the current
15675 color is undefined after @code{glMultiDrawElements} executes. Attributes
15676 that aren't modified maintain their previous values.
15678 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
15681 @code{GL_INVALID_VALUE} is generated if @var{primcount} is negative.
15683 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
15684 name is bound to an enabled array or the element array and the buffer
15685 object's data store is currently mapped.
15687 @code{GL_INVALID_OPERATION} is generated if @code{glMultiDrawElements}
15688 is executed between the execution of @code{glBegin} and the
15689 corresponding @code{glEnd}.
15693 @deftypefun void glMultiTexCoord1i target s
15694 @deftypefunx void glMultiTexCoord1f target s
15695 @deftypefunx void glMultiTexCoord2i target s t
15696 @deftypefunx void glMultiTexCoord2f target s t
15697 @deftypefunx void glMultiTexCoord3i target s t r
15698 @deftypefunx void glMultiTexCoord3f target s t r
15699 @deftypefunx void glMultiTexCoord4i target s t r q
15700 @deftypefunx void glMultiTexCoord4f target s t r q
15701 Set the current texture coordinates.
15705 Specifies the texture unit whose coordinates should be modified. The
15706 number of texture units is implementation dependent, but must be at
15707 least two. Symbolic constant must be one of
15708 @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to
15709 @code{GL_MAX_TEXTURE_COORDS} - 1, which is an implementation-dependent
15716 Specify @var{s}, @var{t}, @var{r}, and @var{q} texture coordinates for
15717 @var{target} texture unit. Not all parameters are present in all forms
15722 @code{glMultiTexCoord} specifies texture coordinates in one, two, three,
15723 or four dimensions. @code{glMultiTexCoord1} sets the current texture
15724 coordinates to @r{(@var{s},001)}; a call to @code{glMultiTexCoord2} sets
15725 them to @r{(@var{s},@var{t}01)}. Similarly, @code{glMultiTexCoord3}
15726 specifies the texture coordinates as @r{(@var{s},@var{t}@var{r}1)}, and
15727 @code{glMultiTexCoord4} defines all four components explicitly as
15728 @r{(@var{s},@var{t}@var{r}@var{q})}.
15730 The current texture coordinates are part of the data that is associated
15731 with each vertex and with the current raster position. Initially, the
15732 values for @r{(@var{s},@var{t}@var{r}@var{q})} are @r{(0,001)}.
15738 @deftypefun void glMultMatrixf m
15739 Multiply the current matrix with the specified matrix.
15743 Points to 16 consecutive values that are used as the elements of a
15744 @r{4×4} column-major matrix.
15748 @code{glMultMatrix} multiplies the current matrix with the one specified
15749 using @var{m}, and replaces the current matrix with the product.
15751 The current matrix is determined by the current matrix mode (see
15752 @code{glMatrixMode}). It is either the projection matrix, modelview
15753 matrix, or the texture matrix.
15755 @code{GL_INVALID_OPERATION} is generated if @code{glMultMatrix} is
15756 executed between the execution of @code{glBegin} and the corresponding
15757 execution of @code{glEnd}.
15761 @deftypefun void glMultTransposeMatrixf m
15762 Multiply the current matrix with the specified row-major ordered matrix.
15766 Points to 16 consecutive values that are used as the elements of a
15767 @r{4×4} row-major matrix.
15771 @code{glMultTransposeMatrix} multiplies the current matrix with the one
15772 specified using @var{m}, and replaces the current matrix with the
15775 The current matrix is determined by the current matrix mode (see
15776 @code{glMatrixMode}). It is either the projection matrix, modelview
15777 matrix, or the texture matrix.
15779 @code{GL_INVALID_OPERATION} is generated if @code{glMultTransposeMatrix}
15780 is executed between the execution of @code{glBegin} and the
15781 corresponding execution of @code{glEnd}.
15785 @deftypefun void glNewList list mode
15786 @deftypefunx void glEndList
15787 Create or replace a display list.
15791 Specifies the display-list name.
15794 Specifies the compilation mode, which can be @code{GL_COMPILE} or
15795 @code{GL_COMPILE_AND_EXECUTE}.
15799 Display lists are groups of GL commands that have been stored for
15800 subsequent execution. Display lists are created with @code{glNewList}.
15801 All subsequent commands are placed in the display list, in the order
15802 issued, until @code{glEndList} is called.
15804 @code{glNewList} has two arguments. The first argument, @var{list}, is a
15805 positive integer that becomes the unique name for the display list.
15806 Names can be created and reserved with @code{glGenLists} and tested for
15807 uniqueness with @code{glIsList}. The second argument, @var{mode}, is a
15808 symbolic constant that can assume one of two values:
15811 @item @code{GL_COMPILE}
15812 Commands are merely compiled.
15814 @item @code{GL_COMPILE_AND_EXECUTE}
15815 Commands are executed as they are compiled into the display list.
15819 Certain commands are not compiled into the display list but are executed
15820 immediately, regardless of the display-list mode. These commands are
15821 @code{glAreTexturesResident}, @code{glColorPointer},
15822 @code{glDeleteLists}, @code{glDeleteTextures},
15823 @code{glDisableClientState}, @code{glEdgeFlagPointer},
15824 @code{glEnableClientState}, @code{glFeedbackBuffer}, @code{glFinish},
15825 @code{glFlush}, @code{glGenLists}, @code{glGenTextures},
15826 @code{glIndexPointer}, @code{glInterleavedArrays}, @code{glIsEnabled},
15827 @code{glIsList}, @code{glIsTexture}, @code{glNormalPointer},
15828 @code{glPopClientAttrib}, @code{glPixelStore},
15829 @code{glPushClientAttrib}, @code{glReadPixels}, @code{glRenderMode},
15830 @code{glSelectBuffer}, @code{glTexCoordPointer}, @code{glVertexPointer},
15831 and all of the @code{glGet} commands.
15833 Similarly, @code{glTexImage1D}, @code{glTexImage2D}, and
15834 @code{glTexImage3D} are executed immediately and not compiled into the
15835 display list when their first argument is @code{GL_PROXY_TEXTURE_1D},
15836 @code{GL_PROXY_TEXTURE_1D}, or @code{GL_PROXY_TEXTURE_3D}, respectively.
15838 When the @code{ARB_imaging} extension is supported, @code{glHistogram}
15839 executes immediately when its argument is @code{GL_PROXY_HISTOGRAM}.
15840 Similarly, @code{glColorTable} executes immediately when its first
15841 argument is @code{GL_PROXY_COLOR_TABLE},
15842 @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or
15843 @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}.
15845 For OpenGL versions 1.3 and greater, or when the @code{ARB_multitexture}
15846 extension is supported, @code{glClientActiveTexture} is not compiled
15847 into display lists, but executed immediately.
15849 When @code{glEndList} is encountered, the display-list definition is
15850 completed by associating the list with the unique name @var{list}
15851 (specified in the @code{glNewList} command). If a display list with name
15852 @var{list} already exists, it is replaced only when @code{glEndList} is
15855 @code{GL_INVALID_VALUE} is generated if @var{list} is 0.
15857 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
15860 @code{GL_INVALID_OPERATION} is generated if @code{glEndList} is called
15861 without a preceding @code{glNewList}, or if @code{glNewList} is called
15862 while a display list is being defined.
15864 @code{GL_INVALID_OPERATION} is generated if @code{glNewList} or
15865 @code{glEndList} is executed between the execution of @code{glBegin} and
15866 the corresponding execution of @code{glEnd}.
15868 @code{GL_OUT_OF_MEMORY} is generated if there is insufficient memory to
15869 compile the display list. If the GL version is 1.1 or greater, no change
15870 is made to the previous contents of the display list, if any, and no
15871 other change is made to the GL state. (It is as if no attempt had been
15872 made to create the new display list.)
15876 @deftypefun void glNormalPointer type stride pointer
15877 Define an array of normals.
15881 Specifies the data type of each coordinate in the array. Symbolic
15882 constants @code{GL_BYTE}, @code{GL_SHORT}, @code{GL_INT},
15883 @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value is
15887 Specifies the byte offset between consecutive normals. If @var{stride}
15888 is 0, the normals are understood to be tightly packed in the array. The
15889 initial value is 0.
15891 @item @var{pointer}
15892 Specifies a pointer to the first coordinate of the first normal in the
15893 array. The initial value is 0.
15897 @code{glNormalPointer} specifies the location and data format of an
15898 array of normals to use when rendering. @var{type} specifies the data
15899 type of each normal coordinate, and @var{stride} specifies the byte
15900 stride from one normal to the next, allowing vertices and attributes to
15901 be packed into a single array or stored in separate arrays.
15902 (Single-array storage may be more efficient on some implementations; see
15903 @code{glInterleavedArrays}.)
15905 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
15906 target (see @code{glBindBuffer}) while a normal array is specified,
15907 @var{pointer} is treated as a byte offset into the buffer object's data
15908 store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING})
15909 is saved as normal vertex array client-side state
15910 (@code{GL_NORMAL_ARRAY_BUFFER_BINDING}).
15912 When a normal array is specified, @var{type}, @var{stride}, and
15913 @var{pointer} are saved as client-side state, in addition to the current
15914 vertex array buffer object binding.
15916 To enable and disable the normal array, call @code{glEnableClientState}
15917 and @code{glDisableClientState} with the argument
15918 @code{GL_NORMAL_ARRAY}. If enabled, the normal array is used when
15919 @code{glDrawArrays}, @code{glMultiDrawArrays}, @code{glDrawElements},
15920 @code{glMultiDrawElements}, @code{glDrawRangeElements}, or
15921 @code{glArrayElement} is called.
15923 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
15926 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
15930 @deftypefun void glNormal3f nx ny nz
15931 @deftypefunx void glNormal3i nx ny nz
15932 Set the current normal vector.
15938 Specify the @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} coordinates of the
15939 new current normal. The initial value of the current normal is the unit
15946 The current normal is set to the given coordinates whenever
15947 @code{glNormal} is issued. Byte, short, or integer arguments are
15948 converted to floating-point format with a linear mapping that maps the
15949 most positive representable integer value to 1.0 and the most negative
15950 representable integer value to @r{-1.0}.
15952 Normals specified with @code{glNormal} need not have unit length. If
15953 @code{GL_NORMALIZE} is enabled, then normals of any length specified
15954 with @code{glNormal} are normalized after transformation. If
15955 @code{GL_RESCALE_NORMAL} is enabled, normals are scaled by a scaling
15956 factor derived from the modelview matrix. @code{GL_RESCALE_NORMAL}
15957 requires that the originally specified normals were of unit length, and
15958 that the modelview matrix contain only uniform scales for proper
15959 results. To enable and disable normalization, call @code{glEnable} and
15960 @code{glDisable} with either @code{GL_NORMALIZE} or
15961 @code{GL_RESCALE_NORMAL}. Normalization is initially disabled.
15965 @deftypefun void glOrtho left right bottom top nearVal farVal
15966 Multiply the current matrix with an orthographic matrix.
15971 Specify the coordinates for the left and right vertical clipping planes.
15975 Specify the coordinates for the bottom and top horizontal clipping
15978 @item @var{nearVal}
15979 @itemx @var{farVal}
15980 Specify the distances to the nearer and farther depth clipping planes.
15981 These values are negative if the plane is to be behind the viewer.
15985 @code{glOrtho} describes a transformation that produces a parallel
15986 projection. The current matrix (see @code{glMatrixMode}) is multiplied
15987 by this matrix and the result replaces the current matrix, as if
15988 @code{glMultMatrix} were called with the following matrix as its
15991 @r{((2/@var{right}-@var{left},, 0 0 @var{t}_@var{x},), (0
15992 2/@var{top}-@var{bottom},, 0 @var{t}_@var{y},), (0 0
15993 -2/@var{farVal}-@var{nearVal},, @var{t}_@var{z},), (0 0 0 1),)}
15996 @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},,}
15998 Typically, the matrix mode is @code{GL_PROJECTION}, and
15999 @r{(@var{left},@var{bottom}-@var{nearVal})} and
16000 @r{(@var{right},@var{top}-@var{nearVal})} specify the points on the near
16001 clipping plane that are mapped to the lower left and upper right corners
16002 of the window, respectively, assuming that the eye is located at (0, 0,
16003 0). @r{-@var{farVal}} specifies the location of the far clipping plane.
16004 Both @var{nearVal} and @var{farVal} can be either positive or negative.
16006 Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the
16007 current matrix stack.
16009 @code{GL_INVALID_VALUE} is generated if @var{left} = @var{right}, or
16010 @var{bottom} = @var{top}, or @var{near} = @var{far}.
16012 @code{GL_INVALID_OPERATION} is generated if @code{glOrtho} is executed
16013 between the execution of @code{glBegin} and the corresponding execution
16018 @deftypefun void glPassThrough token
16019 Place a marker in the feedback buffer.
16023 Specifies a marker value to be placed in the feedback buffer following a
16024 @code{GL_PASS_THROUGH_TOKEN}.
16030 Feedback is a GL render mode. The mode is selected by calling
16031 @code{glRenderMode} with @code{GL_FEEDBACK}. When the GL is in feedback
16032 mode, no pixels are produced by rasterization. Instead, information
16033 about primitives that would have been rasterized is fed back to the
16034 application using the GL. See the @code{glFeedbackBuffer} reference page
16035 for a description of the feedback buffer and the values in it.
16037 @code{glPassThrough} inserts a user-defined marker in the feedback
16038 buffer when it is executed in feedback mode. @var{token} is returned as
16039 if it were a primitive; it is indicated with its own unique identifying
16040 value: @code{GL_PASS_THROUGH_TOKEN}. The order of @code{glPassThrough}
16041 commands with respect to the specification of graphics primitives is
16044 @code{GL_INVALID_OPERATION} is generated if @code{glPassThrough} is
16045 executed between the execution of @code{glBegin} and the corresponding
16046 execution of @code{glEnd}.
16050 @deftypefun void glPixelMapfv map mapsize values
16051 @deftypefunx void glPixelMapuiv map mapsize values
16052 Set up pixel transfer maps.
16056 Specifies a symbolic map name. Must be one of the following:
16057 @code{GL_PIXEL_MAP_I_TO_I}, @code{GL_PIXEL_MAP_S_TO_S},
16058 @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G},
16059 @code{GL_PIXEL_MAP_I_TO_B}, @code{GL_PIXEL_MAP_I_TO_A},
16060 @code{GL_PIXEL_MAP_R_TO_R}, @code{GL_PIXEL_MAP_G_TO_G},
16061 @code{GL_PIXEL_MAP_B_TO_B}, or @code{GL_PIXEL_MAP_A_TO_A}.
16063 @item @var{mapsize}
16064 Specifies the size of the map being defined.
16067 Specifies an array of @var{mapsize} values.
16071 @code{glPixelMap} sets up translation tables, or @var{maps}, used by
16072 @code{glCopyPixels}, @code{glCopyTexImage1D}, @code{glCopyTexImage2D},
16073 @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D},
16074 @code{glCopyTexSubImage3D}, @code{glDrawPixels}, @code{glReadPixels},
16075 @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D},
16076 @code{glTexSubImage1D}, @code{glTexSubImage2D}, and
16077 @code{glTexSubImage3D}. Additionally, if the @code{ARB_imaging} subset
16078 is supported, the routines @code{glColorTable}, @code{glColorSubTable},
16079 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D},
16080 @code{glHistogram}, @code{glMinmax}, and @code{glSeparableFilter2D}. Use
16081 of these maps is described completely in the @code{glPixelTransfer}
16082 reference page, and partly in the reference pages for the pixel and
16083 texture image commands. Only the specification of the maps is described
16084 in this reference page.
16086 @var{map} is a symbolic map name, indicating one of ten maps to set.
16087 @var{mapsize} specifies the number of entries in the map, and
16088 @var{values} is a pointer to an array of @var{mapsize} map values.
16090 If a non-zero named buffer object is bound to the
16091 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
16092 pixel transfer map is specified, @var{values} is treated as a byte
16093 offset into the buffer object's data store.
16095 The ten maps are as follows:
16098 @item @code{GL_PIXEL_MAP_I_TO_I}
16099 Maps color indices to color indices.
16101 @item @code{GL_PIXEL_MAP_S_TO_S}
16102 Maps stencil indices to stencil indices.
16104 @item @code{GL_PIXEL_MAP_I_TO_R}
16105 Maps color indices to red components.
16107 @item @code{GL_PIXEL_MAP_I_TO_G}
16108 Maps color indices to green components.
16110 @item @code{GL_PIXEL_MAP_I_TO_B}
16111 Maps color indices to blue components.
16113 @item @code{GL_PIXEL_MAP_I_TO_A}
16114 Maps color indices to alpha components.
16116 @item @code{GL_PIXEL_MAP_R_TO_R}
16117 Maps red components to red components.
16119 @item @code{GL_PIXEL_MAP_G_TO_G}
16120 Maps green components to green components.
16122 @item @code{GL_PIXEL_MAP_B_TO_B}
16123 Maps blue components to blue components.
16125 @item @code{GL_PIXEL_MAP_A_TO_A}
16126 Maps alpha components to alpha components.
16130 The entries in a map can be specified as single-precision floating-point
16131 numbers, unsigned short integers, or unsigned int integers. Maps that
16132 store color component values (all but @code{GL_PIXEL_MAP_I_TO_I} and
16133 @code{GL_PIXEL_MAP_S_TO_S}) retain their values in floating-point
16134 format, with unspecified mantissa and exponent sizes. Floating-point
16135 values specified by @code{glPixelMapfv} are converted directly to the
16136 internal floating-point format of these maps, then clamped to the range
16137 [0,1]. Unsigned integer values specified by @code{glPixelMapusv} and
16138 @code{glPixelMapuiv} are converted linearly such that the largest
16139 representable integer maps to 1.0, and 0 maps to 0.0.
16141 Maps that store indices, @code{GL_PIXEL_MAP_I_TO_I} and
16142 @code{GL_PIXEL_MAP_S_TO_S}, retain their values in fixed-point format,
16143 with an unspecified number of bits to the right of the binary point.
16144 Floating-point values specified by @code{glPixelMapfv} are converted
16145 directly to the internal fixed-point format of these maps. Unsigned
16146 integer values specified by @code{glPixelMapusv} and
16147 @code{glPixelMapuiv} specify integer values, with all 0's to the right
16148 of the binary point.
16150 The following table shows the initial sizes and values for each of the
16151 maps. Maps that are indexed by either color or stencil indices must have
16152 @var{mapsize} = @r{2^@var{n}} for some @r{@var{n}} or the results are
16153 undefined. The maximum allowable size for each map depends on the
16154 implementation and can be determined by calling @code{glGet} with
16155 argument @code{GL_MAX_PIXEL_MAP_TABLE}. The single maximum applies to
16156 all maps; it is at least 32.
16159 @item @strong{@var{map}}
16160 @strong{Lookup Index}, @strong{Lookup Value}, @strong{Initial Size},
16161 @strong{Initial Value}
16163 @item @code{GL_PIXEL_MAP_I_TO_I}
16164 color index , color index , 1 , 0
16166 @item @code{GL_PIXEL_MAP_S_TO_S}
16167 stencil index , stencil index , 1 , 0
16169 @item @code{GL_PIXEL_MAP_I_TO_R}
16170 color index , R , 1 , 0
16172 @item @code{GL_PIXEL_MAP_I_TO_G}
16173 color index , G , 1 , 0
16175 @item @code{GL_PIXEL_MAP_I_TO_B}
16176 color index , B , 1 , 0
16178 @item @code{GL_PIXEL_MAP_I_TO_A}
16179 color index , A , 1 , 0
16181 @item @code{GL_PIXEL_MAP_R_TO_R}
16184 @item @code{GL_PIXEL_MAP_G_TO_G}
16187 @item @code{GL_PIXEL_MAP_B_TO_B}
16190 @item @code{GL_PIXEL_MAP_A_TO_A}
16195 @code{GL_INVALID_ENUM} is generated if @var{map} is not an accepted
16198 @code{GL_INVALID_VALUE} is generated if @var{mapsize} is less than one
16199 or larger than @code{GL_MAX_PIXEL_MAP_TABLE}.
16201 @code{GL_INVALID_VALUE} is generated if @var{map} is
16202 @code{GL_PIXEL_MAP_I_TO_I}, @code{GL_PIXEL_MAP_S_TO_S},
16203 @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G},
16204 @code{GL_PIXEL_MAP_I_TO_B}, or @code{GL_PIXEL_MAP_I_TO_A}, and
16205 @var{mapsize} is not a power of two.
16207 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
16208 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
16209 object's data store is currently mapped.
16211 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
16212 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
16213 would be unpacked from the buffer object such that the memory reads
16214 required would exceed the data store size.
16216 @code{GL_INVALID_OPERATION} is generated by @code{glPixelMapfv} if a
16217 non-zero buffer object name is bound to the
16218 @code{GL_PIXEL_UNPACK_BUFFER} target and @var{values} is not evenly
16219 divisible into the number of bytes needed to store in memory a GLfloat
16222 @code{GL_INVALID_OPERATION} is generated by @code{glPixelMapuiv} if a
16223 non-zero buffer object name is bound to the
16224 @code{GL_PIXEL_UNPACK_BUFFER} target and @var{values} is not evenly
16225 divisible into the number of bytes needed to store in memory a GLuint
16228 @code{GL_INVALID_OPERATION} is generated by @code{glPixelMapusv} if a
16229 non-zero buffer object name is bound to the
16230 @code{GL_PIXEL_UNPACK_BUFFER} target and @var{values} is not evenly
16231 divisible into the number of bytes needed to store in memory a GLushort
16234 @code{GL_INVALID_OPERATION} is generated if @code{glPixelMap} is
16235 executed between the execution of @code{glBegin} and the corresponding
16236 execution of @code{glEnd}.
16240 @deftypefun void glPixelStoref pname param
16241 @deftypefunx void glPixelStorei pname param
16242 Set pixel storage modes.
16246 Specifies the symbolic name of the parameter to be set. Six values
16247 affect the packing of pixel data into memory: @code{GL_PACK_SWAP_BYTES},
16248 @code{GL_PACK_LSB_FIRST}, @code{GL_PACK_ROW_LENGTH},
16249 @code{GL_PACK_IMAGE_HEIGHT}, @code{GL_PACK_SKIP_PIXELS},
16250 @code{GL_PACK_SKIP_ROWS}, @code{GL_PACK_SKIP_IMAGES}, and
16251 @code{GL_PACK_ALIGNMENT}. Six more affect the unpacking of pixel data
16252 @var{from} memory: @code{GL_UNPACK_SWAP_BYTES},
16253 @code{GL_UNPACK_LSB_FIRST}, @code{GL_UNPACK_ROW_LENGTH},
16254 @code{GL_UNPACK_IMAGE_HEIGHT}, @code{GL_UNPACK_SKIP_PIXELS},
16255 @code{GL_UNPACK_SKIP_ROWS}, @code{GL_UNPACK_SKIP_IMAGES}, and
16256 @code{GL_UNPACK_ALIGNMENT}.
16259 Specifies the value that @var{pname} is set to.
16263 @code{glPixelStore} sets pixel storage modes that affect the operation
16264 of subsequent @code{glDrawPixels} and @code{glReadPixels} as well as the
16265 unpacking of polygon stipple patterns (see @code{glPolygonStipple}),
16266 bitmaps (see @code{glBitmap}), texture patterns (see
16267 @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D},
16268 @code{glTexSubImage1D}, @code{glTexSubImage2D}, @code{glTexSubImage3D}).
16269 Additionally, if the @code{ARB_imaging} extension is supported, pixel
16270 storage modes affect convolution filters (see
16271 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and
16272 @code{glSeparableFilter2D}, color table (see @code{glColorTable}, and
16273 @code{glColorSubTable}, and unpacking histogram (See
16274 @code{glHistogram}), and minmax (See @code{glMinmax}) data.
16276 @var{pname} is a symbolic constant indicating the parameter to be set,
16277 and @var{param} is the new value. Six of the twelve storage parameters
16278 affect how pixel data is returned to client memory. They are as follows:
16281 @item @code{GL_PACK_SWAP_BYTES}
16282 If true, byte ordering for multibyte color components, depth components,
16283 color indices, or stencil indices is reversed. That is, if a four-byte
16284 component consists of bytes @r{@var{b}_0}, @r{@var{b}_1}, @r{@var{b}_2},
16285 @r{@var{b}_3}, it is stored in memory as @r{@var{b}_3}, @r{@var{b}_2},
16286 @r{@var{b}_1}, @r{@var{b}_0} if @code{GL_PACK_SWAP_BYTES} is true.
16287 @code{GL_PACK_SWAP_BYTES} has no effect on the memory order of
16288 components within a pixel, only on the order of bytes within components
16289 or indices. For example, the three components of a @code{GL_RGB} format
16290 pixel are always stored with red first, green second, and blue third,
16291 regardless of the value of @code{GL_PACK_SWAP_BYTES}.
16293 @item @code{GL_PACK_LSB_FIRST}
16294 If true, bits are ordered within a byte from least significant to most
16295 significant; otherwise, the first bit in each byte is the most
16296 significant one. This parameter is significant for bitmap data only.
16298 @item @code{GL_PACK_ROW_LENGTH}
16299 If greater than 0, @code{GL_PACK_ROW_LENGTH} defines the number of
16300 pixels in a row. If the first pixel of a row is placed at location
16301 @r{@var{p}} in memory, then the location of the first pixel of the next
16302 row is obtained by skipping
16304 @r{@var{k}=@{(@var{n}@var{l}),
16305 (@var{a}/@var{s},⌈@var{s}@var{n}@var{l},/@var{a},⌉)(@var{s}>=@var{a}),
16306 (@var{s}<@var{a}),}
16308 components or indices, where @r{@var{n}} is the number of components or
16309 indices in a pixel, @r{@var{l}} is the number of pixels in a row
16310 (@code{GL_PACK_ROW_LENGTH} if it is greater than 0, the @r{@var{width}}
16311 argument to the pixel routine otherwise), @r{@var{a}} is the value of
16312 @code{GL_PACK_ALIGNMENT}, and @r{@var{s}} is the size, in bytes, of a
16313 single component (if @r{@var{a}<@var{s}}, then it is as if
16314 @r{@var{a}=@var{s}}). In the case of 1-bit values, the location of the
16315 next row is obtained by skipping
16317 @r{@var{k}=8@var{a}⌈@var{n}@var{l},/8@var{a},,⌉}
16319 components or indices.
16321 The word @var{component} in this description refers to the nonindex
16322 values red, green, blue, alpha, and depth. Storage format @code{GL_RGB},
16323 for example, has three components per pixel: first red, then green, and
16326 @item @code{GL_PACK_IMAGE_HEIGHT}
16327 If greater than 0, @code{GL_PACK_IMAGE_HEIGHT} defines the number of
16328 pixels in an image three-dimensional texture volume, where ``image'' is
16329 defined by all pixels sharing the same third dimension index. If the
16330 first pixel of a row is placed at location @r{@var{p}} in memory, then
16331 the location of the first pixel of the next row is obtained by skipping
16333 @r{@var{k}=@{(@var{n}@var{l}@var{h}),
16334 (@var{a}/@var{s},⌈@var{s}@var{n}@var{l}@var{h},/@var{a},⌉)(@var{s}>=@var{a}),
16335 (@var{s}<@var{a}),}
16337 components or indices, where @r{@var{n}} is the number of components or
16338 indices in a pixel, @r{@var{l}} is the number of pixels in a row
16339 (@code{GL_PACK_ROW_LENGTH} if it is greater than 0, the @r{@var{width}}
16340 argument to @code{glTexImage3D} otherwise), @r{@var{h}} is the number of
16341 rows in a pixel image (@code{GL_PACK_IMAGE_HEIGHT} if it is greater than
16342 0, the @r{@var{height}} argument to the @code{glTexImage3D} routine
16343 otherwise), @r{@var{a}} is the value of @code{GL_PACK_ALIGNMENT}, and
16344 @r{@var{s}} is the size, in bytes, of a single component (if
16345 @r{@var{a}<@var{s}}, then it is as if @r{@var{a}=@var{s}}).
16347 The word @var{component} in this description refers to the nonindex
16348 values red, green, blue, alpha, and depth. Storage format @code{GL_RGB},
16349 for example, has three components per pixel: first red, then green, and
16352 @item @code{GL_PACK_SKIP_PIXELS}, @code{GL_PACK_SKIP_ROWS}, and @code{GL_PACK_SKIP_IMAGES}
16353 These values are provided as a convenience to the programmer; they
16354 provide no functionality that cannot be duplicated simply by
16355 incrementing the pointer passed to @code{glReadPixels}. Setting
16356 @code{GL_PACK_SKIP_PIXELS} to @r{@var{i}} is equivalent to incrementing
16357 the pointer by @r{@var{i}@var{n}} components or indices, where
16358 @r{@var{n}} is the number of components or indices in each pixel.
16359 Setting @code{GL_PACK_SKIP_ROWS} to @r{@var{j}} is equivalent to
16360 incrementing the pointer by @r{@var{j}@var{m}} components or indices,
16361 where @r{@var{m}} is the number of components or indices per row, as
16362 just computed in the @code{GL_PACK_ROW_LENGTH} section. Setting
16363 @code{GL_PACK_SKIP_IMAGES} to @r{@var{k}} is equivalent to incrementing
16364 the pointer by @r{@var{k}@var{p}}, where @r{@var{p}} is the number of
16365 components or indices per image, as computed in the
16366 @code{GL_PACK_IMAGE_HEIGHT} section.
16368 @item @code{GL_PACK_ALIGNMENT}
16369 Specifies the alignment requirements for the start of each pixel row in
16370 memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to
16371 even-numbered bytes), 4 (word-alignment), and 8 (rows start on
16372 double-word boundaries).
16376 The other six of the twelve storage parameters affect how pixel data is
16377 read from client memory. These values are significant for
16378 @code{glDrawPixels}, @code{glTexImage1D}, @code{glTexImage2D},
16379 @code{glTexImage3D}, @code{glTexSubImage1D}, @code{glTexSubImage2D},
16380 @code{glTexSubImage3D}, @code{glBitmap}, and @code{glPolygonStipple}.
16382 Additionally, if the @code{ARB_imaging} extension is supported,
16383 @code{glColorTable}, @code{glColorSubTable},
16384 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and
16385 @code{glSeparableFilter2D}. They are as follows:
16388 @item @code{GL_UNPACK_SWAP_BYTES}
16389 If true, byte ordering for multibyte color components, depth components,
16390 color indices, or stencil indices is reversed. That is, if a four-byte
16391 component consists of bytes @r{@var{b}_0}, @r{@var{b}_1}, @r{@var{b}_2},
16392 @r{@var{b}_3}, it is taken from memory as @r{@var{b}_3}, @r{@var{b}_2},
16393 @r{@var{b}_1}, @r{@var{b}_0} if @code{GL_UNPACK_SWAP_BYTES} is true.
16394 @code{GL_UNPACK_SWAP_BYTES} has no effect on the memory order of
16395 components within a pixel, only on the order of bytes within components
16396 or indices. For example, the three components of a @code{GL_RGB} format
16397 pixel are always stored with red first, green second, and blue third,
16398 regardless of the value of @code{GL_UNPACK_SWAP_BYTES}.
16400 @item @code{GL_UNPACK_LSB_FIRST}
16401 If true, bits are ordered within a byte from least significant to most
16402 significant; otherwise, the first bit in each byte is the most
16403 significant one. This is relevant only for bitmap data.
16405 @item @code{GL_UNPACK_ROW_LENGTH}
16406 If greater than 0, @code{GL_UNPACK_ROW_LENGTH} defines the number of
16407 pixels in a row. If the first pixel of a row is placed at location
16408 @r{@var{p}} in memory, then the location of the first pixel of the next
16409 row is obtained by skipping
16411 @r{@var{k}=@{(@var{n}@var{l}),
16412 (@var{a}/@var{s},⌈@var{s}@var{n}@var{l},/@var{a},⌉)(@var{s}>=@var{a}),
16413 (@var{s}<@var{a}),}
16415 components or indices, where @r{@var{n}} is the number of components or
16416 indices in a pixel, @r{@var{l}} is the number of pixels in a row
16417 (@code{GL_UNPACK_ROW_LENGTH} if it is greater than 0, the
16418 @r{@var{width}} argument to the pixel routine otherwise), @r{@var{a}} is
16419 the value of @code{GL_UNPACK_ALIGNMENT}, and @r{@var{s}} is the size, in
16420 bytes, of a single component (if @r{@var{a}<@var{s}}, then it is as if
16421 @r{@var{a}=@var{s}}). In the case of 1-bit values, the location of the
16422 next row is obtained by skipping
16424 @r{@var{k}=8@var{a}⌈@var{n}@var{l},/8@var{a},,⌉}
16426 components or indices.
16428 The word @var{component} in this description refers to the nonindex
16429 values red, green, blue, alpha, and depth. Storage format @code{GL_RGB},
16430 for example, has three components per pixel: first red, then green, and
16433 @item @code{GL_UNPACK_IMAGE_HEIGHT}
16434 If greater than 0, @code{GL_UNPACK_IMAGE_HEIGHT} defines the number of
16435 pixels in an image of a three-dimensional texture volume. Where
16436 ``image'' is defined by all pixel sharing the same third dimension
16437 index. If the first pixel of a row is placed at location @r{@var{p}} in
16438 memory, then the location of the first pixel of the next row is obtained
16441 @r{@var{k}=@{(@var{n}@var{l}@var{h}),
16442 (@var{a}/@var{s},⌈@var{s}@var{n}@var{l}@var{h},/@var{a},⌉)(@var{s}>=@var{a}),
16443 (@var{s}<@var{a}),}
16445 components or indices, where @r{@var{n}} is the number of components or
16446 indices in a pixel, @r{@var{l}} is the number of pixels in a row
16447 (@code{GL_UNPACK_ROW_LENGTH} if it is greater than 0, the
16448 @r{@var{width}} argument to @code{glTexImage3D} otherwise), @r{@var{h}}
16449 is the number of rows in an image (@code{GL_UNPACK_IMAGE_HEIGHT} if it
16450 is greater than 0, the @r{@var{height}} argument to @code{glTexImage3D}
16451 otherwise), @r{@var{a}} is the value of @code{GL_UNPACK_ALIGNMENT}, and
16452 @r{@var{s}} is the size, in bytes, of a single component (if
16453 @r{@var{a}<@var{s}}, then it is as if @r{@var{a}=@var{s}}).
16455 The word @var{component} in this description refers to the nonindex
16456 values red, green, blue, alpha, and depth. Storage format @code{GL_RGB},
16457 for example, has three components per pixel: first red, then green, and
16460 @item @code{GL_UNPACK_SKIP_PIXELS} and @code{GL_UNPACK_SKIP_ROWS}
16461 These values are provided as a convenience to the programmer; they
16462 provide no functionality that cannot be duplicated by incrementing the
16463 pointer passed to @code{glDrawPixels}, @code{glTexImage1D},
16464 @code{glTexImage2D}, @code{glTexSubImage1D}, @code{glTexSubImage2D},
16465 @code{glBitmap}, or @code{glPolygonStipple}. Setting
16466 @code{GL_UNPACK_SKIP_PIXELS} to @r{@var{i}} is equivalent to
16467 incrementing the pointer by @r{@var{i}@var{n}} components or indices,
16468 where @r{@var{n}} is the number of components or indices in each pixel.
16469 Setting @code{GL_UNPACK_SKIP_ROWS} to @r{@var{j}} is equivalent to
16470 incrementing the pointer by @r{@var{j}@var{k}} components or indices,
16471 where @r{@var{k}} is the number of components or indices per row, as
16472 just computed in the @code{GL_UNPACK_ROW_LENGTH} section.
16474 @item @code{GL_UNPACK_ALIGNMENT}
16475 Specifies the alignment requirements for the start of each pixel row in
16476 memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to
16477 even-numbered bytes), 4 (word-alignment), and 8 (rows start on
16478 double-word boundaries).
16482 The following table gives the type, initial value, and range of valid
16483 values for each storage parameter that can be set with
16484 @code{glPixelStore}.
16489 @item @strong{@var{pname}}
16490 @strong{Type}, @strong{Initial Value}, @strong{Valid Range}
16492 @item @code{GL_PACK_SWAP_BYTES}
16493 boolean , false , true or false
16495 @item @code{GL_PACK_LSB_FIRST}
16496 boolean , false , true or false
16498 @item @code{GL_PACK_ROW_LENGTH}
16499 integer , 0 , @r{[0,∞)}
16501 @item @code{GL_PACK_IMAGE_HEIGHT}
16502 integer , 0 , @r{[0,∞)}
16504 @item @code{GL_PACK_SKIP_ROWS}
16505 integer , 0 , @r{[0,∞)}
16507 @item @code{GL_PACK_SKIP_PIXELS}
16508 integer , 0 , @r{[0,∞)}
16510 @item @code{GL_PACK_SKIP_IMAGES}
16511 integer , 0 , @r{[0,∞)}
16513 @item @code{GL_PACK_ALIGNMENT}
16514 integer , 4 , 1, 2, 4, or 8
16516 @item @code{GL_UNPACK_SWAP_BYTES}
16517 boolean , false , true or false
16519 @item @code{GL_UNPACK_LSB_FIRST}
16520 boolean , false , true or false
16522 @item @code{GL_UNPACK_ROW_LENGTH}
16523 integer , 0 , @r{[0,∞)}
16525 @item @code{GL_UNPACK_IMAGE_HEIGHT}
16526 integer , 0 , @r{[0,∞)}
16528 @item @code{GL_UNPACK_SKIP_ROWS}
16529 integer , 0 , @r{[0,∞)}
16531 @item @code{GL_UNPACK_SKIP_PIXELS}
16532 integer , 0 , @r{[0,∞)}
16534 @item @code{GL_UNPACK_SKIP_IMAGES}
16535 integer , 0 , @r{[0,∞)}
16537 @item @code{GL_UNPACK_ALIGNMENT}
16538 integer , 4 , 1, 2, 4, or 8
16542 @code{glPixelStoref} can be used to set any pixel store parameter. If
16543 the parameter type is boolean, then if @var{param} is 0, the parameter
16544 is false; otherwise it is set to true. If @var{pname} is a integer type
16545 parameter, @var{param} is rounded to the nearest integer.
16547 Likewise, @code{glPixelStorei} can also be used to set any of the pixel
16548 store parameters. Boolean parameters are set to false if @var{param} is
16549 0 and true otherwise.
16551 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
16554 @code{GL_INVALID_VALUE} is generated if a negative row length, pixel
16555 skip, or row skip value is specified, or if alignment is specified as
16556 other than 1, 2, 4, or 8.
16558 @code{GL_INVALID_OPERATION} is generated if @code{glPixelStore} is
16559 executed between the execution of @code{glBegin} and the corresponding
16560 execution of @code{glEnd}.
16564 @deftypefun void glPixelTransferf pname param
16565 @deftypefunx void glPixelTransferi pname param
16566 Set pixel transfer modes.
16570 Specifies the symbolic name of the pixel transfer parameter to be set.
16571 Must be one of the following: @code{GL_MAP_COLOR},
16572 @code{GL_MAP_STENCIL}, @code{GL_INDEX_SHIFT}, @code{GL_INDEX_OFFSET},
16573 @code{GL_RED_SCALE}, @code{GL_RED_BIAS}, @code{GL_GREEN_SCALE},
16574 @code{GL_GREEN_BIAS}, @code{GL_BLUE_SCALE}, @code{GL_BLUE_BIAS},
16575 @code{GL_ALPHA_SCALE}, @code{GL_ALPHA_BIAS}, @code{GL_DEPTH_SCALE}, or
16576 @code{GL_DEPTH_BIAS}.
16578 Additionally, if the @code{ARB_imaging} extension is supported, the
16579 following symbolic names are accepted:
16580 @code{GL_POST_COLOR_MATRIX_RED_SCALE},
16581 @code{GL_POST_COLOR_MATRIX_GREEN_SCALE},
16582 @code{GL_POST_COLOR_MATRIX_BLUE_SCALE},
16583 @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE},
16584 @code{GL_POST_COLOR_MATRIX_RED_BIAS},
16585 @code{GL_POST_COLOR_MATRIX_GREEN_BIAS},
16586 @code{GL_POST_COLOR_MATRIX_BLUE_BIAS},
16587 @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS},
16588 @code{GL_POST_CONVOLUTION_RED_SCALE},
16589 @code{GL_POST_CONVOLUTION_GREEN_SCALE},
16590 @code{GL_POST_CONVOLUTION_BLUE_SCALE},
16591 @code{GL_POST_CONVOLUTION_ALPHA_SCALE},
16592 @code{GL_POST_CONVOLUTION_RED_BIAS},
16593 @code{GL_POST_CONVOLUTION_GREEN_BIAS},
16594 @code{GL_POST_CONVOLUTION_BLUE_BIAS}, and
16595 @code{GL_POST_CONVOLUTION_ALPHA_BIAS}.
16598 Specifies the value that @var{pname} is set to.
16602 @code{glPixelTransfer} sets pixel transfer modes that affect the
16603 operation of subsequent @code{glCopyPixels}, @code{glCopyTexImage1D},
16604 @code{glCopyTexImage2D}, @code{glCopyTexSubImage1D},
16605 @code{glCopyTexSubImage2D}, @code{glCopyTexSubImage3D},
16606 @code{glDrawPixels}, @code{glReadPixels}, @code{glTexImage1D},
16607 @code{glTexImage2D}, @code{glTexImage3D}, @code{glTexSubImage1D},
16608 @code{glTexSubImage2D}, and @code{glTexSubImage3D} commands.
16609 Additionally, if the @code{ARB_imaging} subset is supported, the
16610 routines @code{glColorTable}, @code{glColorSubTable},
16611 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D},
16612 @code{glHistogram}, @code{glMinmax}, and @code{glSeparableFilter2D} are
16613 also affected. The algorithms that are specified by pixel transfer modes
16614 operate on pixels after they are read from the frame buffer
16615 (@code{glCopyPixels}@code{glCopyTexImage1D}, @code{glCopyTexImage2D},
16616 @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D},
16617 @code{glCopyTexSubImage3D}, and @code{glReadPixels}), or unpacked from
16618 client memory (@code{glDrawPixels}, @code{glTexImage1D},
16619 @code{glTexImage2D}, @code{glTexImage3D}, @code{glTexSubImage1D},
16620 @code{glTexSubImage2D}, and @code{glTexSubImage3D}). Pixel transfer
16621 operations happen in the same order, and in the same manner, regardless
16622 of the command that resulted in the pixel operation. Pixel storage modes
16623 (see @code{glPixelStore}) control the unpacking of pixels being read
16624 from client memory and the packing of pixels being written back into
16627 Pixel transfer operations handle four fundamental pixel types:
16628 @var{color}, @var{color index}, @var{depth}, and @var{stencil}.
16629 @var{Color} pixels consist of four floating-point values with
16630 unspecified mantissa and exponent sizes, scaled such that 0 represents
16631 zero intensity and 1 represents full intensity. @var{Color indices}
16632 comprise a single fixed-point value, with unspecified precision to the
16633 right of the binary point. @var{Depth} pixels comprise a single
16634 floating-point value, with unspecified mantissa and exponent sizes,
16635 scaled such that 0.0 represents the minimum depth buffer value, and 1.0
16636 represents the maximum depth buffer value. Finally, @var{stencil} pixels
16637 comprise a single fixed-point value, with unspecified precision to the
16638 right of the binary point.
16640 The pixel transfer operations performed on the four basic pixel types
16645 Each of the four color components is multiplied by a scale factor, then
16646 added to a bias factor. That is, the red component is multiplied by
16647 @code{GL_RED_SCALE}, then added to @code{GL_RED_BIAS}; the green
16648 component is multiplied by @code{GL_GREEN_SCALE}, then added to
16649 @code{GL_GREEN_BIAS}; the blue component is multiplied by
16650 @code{GL_BLUE_SCALE}, then added to @code{GL_BLUE_BIAS}; and the alpha
16651 component is multiplied by @code{GL_ALPHA_SCALE}, then added to
16652 @code{GL_ALPHA_BIAS}. After all four color components are scaled and
16653 biased, each is clamped to the range @r{[0,1]}. All color, scale, and
16654 bias values are specified with @code{glPixelTransfer}.
16656 If @code{GL_MAP_COLOR} is true, each color component is scaled by the
16657 size of the corresponding color-to-color map, then replaced by the
16658 contents of that map indexed by the scaled component. That is, the red
16659 component is scaled by @code{GL_PIXEL_MAP_R_TO_R_SIZE}, then replaced by
16660 the contents of @code{GL_PIXEL_MAP_R_TO_R} indexed by itself. The green
16661 component is scaled by @code{GL_PIXEL_MAP_G_TO_G_SIZE}, then replaced by
16662 the contents of @code{GL_PIXEL_MAP_G_TO_G} indexed by itself. The blue
16663 component is scaled by @code{GL_PIXEL_MAP_B_TO_B_SIZE}, then replaced by
16664 the contents of @code{GL_PIXEL_MAP_B_TO_B} indexed by itself. And the
16665 alpha component is scaled by @code{GL_PIXEL_MAP_A_TO_A_SIZE}, then
16666 replaced by the contents of @code{GL_PIXEL_MAP_A_TO_A} indexed by
16667 itself. All components taken from the maps are then clamped to the range
16668 @r{[0,1]}. @code{GL_MAP_COLOR} is specified with @code{glPixelTransfer}.
16669 The contents of the various maps are specified with @code{glPixelMap}.
16671 If the @code{ARB_imaging} extension is supported, each of the four color
16672 components may be scaled and biased after transformation by the color
16673 matrix. That is, the red component is multiplied by
16674 @code{GL_POST_COLOR_MATRIX_RED_SCALE}, then added to
16675 @code{GL_POST_COLOR_MATRIX_RED_BIAS}; the green component is multiplied
16676 by @code{GL_POST_COLOR_MATRIX_GREEN_SCALE}, then added to
16677 @code{GL_POST_COLOR_MATRIX_GREEN_BIAS}; the blue component is multiplied
16678 by @code{GL_POST_COLOR_MATRIX_BLUE_SCALE}, then added to
16679 @code{GL_POST_COLOR_MATRIX_BLUE_BIAS}; and the alpha component is
16680 multiplied by @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE}, then added to
16681 @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS}. After all four color components
16682 are scaled and biased, each is clamped to the range @r{[0,1]}.
16684 Similarly, if the @code{ARB_imaging} extension is supported, each of the
16685 four color components may be scaled and biased after processing by the
16686 enabled convolution filter. That is, the red component is multiplied by
16687 @code{GL_POST_CONVOLUTION_RED_SCALE}, then added to
16688 @code{GL_POST_CONVOLUTION_RED_BIAS}; the green component is multiplied
16689 by @code{GL_POST_CONVOLUTION_GREEN_SCALE}, then added to
16690 @code{GL_POST_CONVOLUTION_GREEN_BIAS}; the blue component is multiplied
16691 by @code{GL_POST_CONVOLUTION_BLUE_SCALE}, then added to
16692 @code{GL_POST_CONVOLUTION_BLUE_BIAS}; and the alpha component is
16693 multiplied by @code{GL_POST_CONVOLUTION_ALPHA_SCALE}, then added to
16694 @code{GL_POST_CONVOLUTION_ALPHA_BIAS}. After all four color components
16695 are scaled and biased, each is clamped to the range @r{[0,1]}.
16697 @item @var{Color index}
16698 Each color index is shifted left by @code{GL_INDEX_SHIFT} bits; any bits
16699 beyond the number of fraction bits carried by the fixed-point index are
16700 filled with zeros. If @code{GL_INDEX_SHIFT} is negative, the shift is to
16701 the right, again zero filled. Then @code{GL_INDEX_OFFSET} is added to
16702 the index. @code{GL_INDEX_SHIFT} and @code{GL_INDEX_OFFSET} are
16703 specified with @code{glPixelTransfer}.
16705 From this point, operation diverges depending on the required format of
16706 the resulting pixels. If the resulting pixels are to be written to a
16707 color index buffer, or if they are being read back to client memory in
16708 @code{GL_COLOR_INDEX} format, the pixels continue to be treated as
16709 indices. If @code{GL_MAP_COLOR} is true, each index is masked by
16710 @r{2^@var{n}-1}, where @r{@var{n}} is @code{GL_PIXEL_MAP_I_TO_I_SIZE},
16711 then replaced by the contents of @code{GL_PIXEL_MAP_I_TO_I} indexed by
16712 the masked value. @code{GL_MAP_COLOR} is specified with
16713 @code{glPixelTransfer}. The contents of the index map is specified with
16716 If the resulting pixels are to be written to an RGBA color buffer, or if
16717 they are read back to client memory in a format other than
16718 @code{GL_COLOR_INDEX}, the pixels are converted from indices to colors
16719 by referencing the four maps @code{GL_PIXEL_MAP_I_TO_R},
16720 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
16721 @code{GL_PIXEL_MAP_I_TO_A}. Before being dereferenced, the index is
16722 masked by @r{2^@var{n}-1}, where @r{@var{n}} is
16723 @code{GL_PIXEL_MAP_I_TO_R_SIZE} for the red map,
16724 @code{GL_PIXEL_MAP_I_TO_G_SIZE} for the green map,
16725 @code{GL_PIXEL_MAP_I_TO_B_SIZE} for the blue map, and
16726 @code{GL_PIXEL_MAP_I_TO_A_SIZE} for the alpha map. All components taken
16727 from the maps are then clamped to the range @r{[0,1]}. The contents of
16728 the four maps is specified with @code{glPixelMap}.
16731 Each depth value is multiplied by @code{GL_DEPTH_SCALE}, added to
16732 @code{GL_DEPTH_BIAS}, then clamped to the range @r{[0,1]}.
16734 @item @var{Stencil}
16735 Each index is shifted @code{GL_INDEX_SHIFT} bits just as a color index
16736 is, then added to @code{GL_INDEX_OFFSET}. If @code{GL_MAP_STENCIL} is
16737 true, each index is masked by @r{2^@var{n}-1}, where @r{@var{n}} is
16738 @code{GL_PIXEL_MAP_S_TO_S_SIZE}, then replaced by the contents of
16739 @code{GL_PIXEL_MAP_S_TO_S} indexed by the masked value.
16743 The following table gives the type, initial value, and range of valid
16744 values for each of the pixel transfer parameters that are set with
16745 @code{glPixelTransfer}.
16750 @item @strong{@var{pname}}
16751 @strong{Type}, @strong{Initial Value}, @strong{Valid Range}
16753 @item @code{GL_MAP_COLOR}
16754 boolean , false , true/false
16756 @item @code{GL_MAP_STENCIL}
16757 boolean , false , true/false
16759 @item @code{GL_INDEX_SHIFT}
16760 integer , 0 , @r{(-∞,∞)}
16762 @item @code{GL_INDEX_OFFSET}
16763 integer , 0 , @r{(-∞,∞)}
16765 @item @code{GL_RED_SCALE}
16766 float , 1 , @r{(-∞,∞)}
16768 @item @code{GL_GREEN_SCALE}
16769 float , 1 , @r{(-∞,∞)}
16771 @item @code{GL_BLUE_SCALE}
16772 float , 1 , @r{(-∞,∞)}
16774 @item @code{GL_ALPHA_SCALE}
16775 float , 1 , @r{(-∞,∞)}
16777 @item @code{GL_DEPTH_SCALE}
16778 float , 1 , @r{(-∞,∞)}
16780 @item @code{GL_RED_BIAS}
16781 float , 0 , @r{(-∞,∞)}
16783 @item @code{GL_GREEN_BIAS}
16784 float , 0 , @r{(-∞,∞)}
16786 @item @code{GL_BLUE_BIAS}
16787 float , 0 , @r{(-∞,∞)}
16789 @item @code{GL_ALPHA_BIAS}
16790 float , 0 , @r{(-∞,∞)}
16792 @item @code{GL_DEPTH_BIAS}
16793 float , 0 , @r{(-∞,∞)}
16795 @item @code{GL_POST_COLOR_MATRIX_RED_SCALE}
16796 float , 1 , @r{(-∞,∞)}
16798 @item @code{GL_POST_COLOR_MATRIX_GREEN_SCALE}
16799 float , 1 , @r{(-∞,∞)}
16801 @item @code{GL_POST_COLOR_MATRIX_BLUE_SCALE}
16802 float , 1 , @r{(-∞,∞)}
16804 @item @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE}
16805 float , 1 , @r{(-∞,∞)}
16807 @item @code{GL_POST_COLOR_MATRIX_RED_BIAS}
16808 float , 0 , @r{(-∞,∞)}
16810 @item @code{GL_POST_COLOR_MATRIX_GREEN_BIAS}
16811 float , 0 , @r{(-∞,∞)}
16813 @item @code{GL_POST_COLOR_MATRIX_BLUE_BIAS}
16814 float , 0 , @r{(-∞,∞)}
16816 @item @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS}
16817 float , 0 , @r{(-∞,∞)}
16819 @item @code{GL_POST_CONVOLUTION_RED_SCALE}
16820 float , 1 , @r{(-∞,∞)}
16822 @item @code{GL_POST_CONVOLUTION_GREEN_SCALE}
16823 float , 1 , @r{(-∞,∞)}
16825 @item @code{GL_POST_CONVOLUTION_BLUE_SCALE}
16826 float , 1 , @r{(-∞,∞)}
16828 @item @code{GL_POST_CONVOLUTION_ALPHA_SCALE}
16829 float , 1 , @r{(-∞,∞)}
16831 @item @code{GL_POST_CONVOLUTION_RED_BIAS}
16832 float , 0 , @r{(-∞,∞)}
16834 @item @code{GL_POST_CONVOLUTION_GREEN_BIAS}
16835 float , 0 , @r{(-∞,∞)}
16837 @item @code{GL_POST_CONVOLUTION_BLUE_BIAS}
16838 float , 0 , @r{(-∞,∞)}
16840 @item @code{GL_POST_CONVOLUTION_ALPHA_BIAS}
16841 float , 0 , @r{(-∞,∞)}
16845 @code{glPixelTransferf} can be used to set any pixel transfer parameter.
16846 If the parameter type is boolean, 0 implies false and any other value
16847 implies true. If @var{pname} is an integer parameter, @var{param} is
16848 rounded to the nearest integer.
16850 Likewise, @code{glPixelTransferi} can be used to set any of the pixel
16851 transfer parameters. Boolean parameters are set to false if @var{param}
16852 is 0 and to true otherwise. @var{param} is converted to floating point
16853 before being assigned to real-valued parameters.
16855 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
16858 @code{GL_INVALID_OPERATION} is generated if @code{glPixelTransfer} is
16859 executed between the execution of @code{glBegin} and the corresponding
16860 execution of @code{glEnd}.
16864 @deftypefun void glPixelZoom xfactor yfactor
16865 Specify the pixel zoom factors.
16868 @item @var{xfactor}
16869 @itemx @var{yfactor}
16870 Specify the @r{@var{x}} and @r{@var{y}} zoom factors for pixel write
16875 @code{glPixelZoom} specifies values for the @r{@var{x}} and @r{@var{y}}
16876 zoom factors. During the execution of @code{glDrawPixels} or
16877 @code{glCopyPixels}, if (@r{@var{xr}}, @r{@var{yr}}) is the current
16878 raster position, and a given element is in the @r{@var{m}}th row and
16879 @r{@var{n}}th column of the pixel rectangle, then pixels whose centers
16880 are in the rectangle with corners at
16882 (@r{@var{xr}+@var{n}·@var{xfactor}}, @r{@var{yr}+@var{m}·@var{yfactor}})
16884 (@r{@var{xr}+(@var{n}+1,)·@var{xfactor}},
16885 @r{@var{yr}+(@var{m}+1,)·@var{yfactor}})
16887 are candidates for replacement. Any pixel whose center lies on the
16888 bottom or left edge of this rectangular region is also modified.
16890 Pixel zoom factors are not limited to positive values. Negative zoom
16891 factors reflect the resulting image about the current raster position.
16893 @code{GL_INVALID_OPERATION} is generated if @code{glPixelZoom} is
16894 executed between the execution of @code{glBegin} and the corresponding
16895 execution of @code{glEnd}.
16899 @deftypefun void glPointParameterf pname param
16900 @deftypefunx void glPointParameteri pname param
16901 Specify point parameters.
16905 Specifies a single-valued point parameter. @code{GL_POINT_SIZE_MIN},
16906 @code{GL_POINT_SIZE_MAX}, @code{GL_POINT_FADE_THRESHOLD_SIZE}, and
16907 @code{GL_POINT_SPRITE_COORD_ORIGIN} are accepted.
16910 Specifies the value that @var{pname} will be set to.
16914 The following values are accepted for @var{pname}:
16917 @item @code{GL_POINT_SIZE_MIN}
16920 @var{params} is a single floating-point value that specifies the minimum
16921 point size. The default value is 0.0.
16923 @item @code{GL_POINT_SIZE_MAX}
16926 @var{params} is a single floating-point value that specifies the maximum
16927 point size. The default value is 1.0.
16929 @item @code{GL_POINT_FADE_THRESHOLD_SIZE}
16932 @var{params} is a single floating-point value that specifies the
16933 threshold value to which point sizes are clamped if they exceed the
16934 specified value. The default value is 1.0.
16936 @item @code{GL_POINT_DISTANCE_ATTENUATION}
16939 @var{params} is an array of three floating-point values that specify the
16940 coefficients used for scaling the computed point size. The default
16941 values are @r{(1,00)}.
16943 @item @code{GL_POINT_SPRITE_COORD_ORIGIN}
16946 @var{params} is a single enum specifying the point sprite texture
16947 coordinate origin, either @code{GL_LOWER_LEFT} or @code{GL_UPPER_LEFT}.
16948 The default value is @code{GL_UPPER_LEFT}.
16952 @code{GL_INVALID_VALUE} is generated If the value specified for
16953 @code{GL_POINT_SIZE_MIN}, @code{GL_POINT_SIZE_MAX}, or
16954 @code{GL_POINT_FADE_THRESHOLD_SIZE} is less than zero.
16956 @code{GL_INVALID_ENUM} is generated If the value specified for
16957 @code{GL_POINT_SPRITE_COORD_ORIGIN} is not @code{GL_LOWER_LEFT} or
16958 @code{GL_UPPER_LEFT}.
16960 If the value for @code{GL_POINT_SIZE_MIN} is greater than
16961 @code{GL_POINT_SIZE_MAX}, the point size after clamping is undefined,
16962 but no error is generated.
16968 @deftypefun void glPointSize size
16969 Specify the diameter of rasterized points.
16973 Specifies the diameter of rasterized points. The initial value is 1.
16977 @code{glPointSize} specifies the rasterized diameter of both aliased and
16978 antialiased points. Using a point size other than 1 has different
16979 effects, depending on whether point antialiasing is enabled. To enable
16980 and disable point antialiasing, call @code{glEnable} and
16981 @code{glDisable} with argument @code{GL_POINT_SMOOTH}. Point
16982 antialiasing is initially disabled.
16984 The specified point size is multiplied with a distance attenuation
16985 factor and clamped to the specified point size range, and further
16986 clamped to the implementation-dependent point size range to produce the
16987 derived point size using
16989 @r{@var{pointSize}=@var{clamp}(@var{size}×√(1/@var{a}+@var{b}×@var{d}+@var{c}×@var{d}^2,,,),,)}
16991 where @r{@var{d}} is the eye-coordinate distance from the eye to the
16992 vertex, and @r{@var{a}}, @r{@var{b}}, and @r{@var{c}} are the distance
16993 attenuation coefficients (see @code{glPointParameter}).
16995 If multisampling is disabled, the computed point size is used as the
16998 If multisampling is enabled, the point may be faded by modifying the
16999 point alpha value (see @code{glSampleCoverage}) instead of allowing the
17000 point width to go below a given threshold (see @code{glPointParameter}).
17001 In this case, the width is further modified in the following manner:
17003 @r{@var{pointWidth}=@{(@var{pointSize}),
17004 (@var{threshold})(@var{pointSize}>=@var{threshold}),
17005 (@var{otherwise}),}
17007 The point alpha value is modified by computing:
17009 @r{@var{pointAlpha}=@{(1),
17010 ((@var{pointSize}/@var{threshold},)^2)(@var{pointSize}>=@var{threshold}),
17011 (@var{otherwise}),}
17013 If point antialiasing is disabled, the actual size is determined by
17014 rounding the supplied size to the nearest integer. (If the rounding
17015 results in the value 0, it is as if the point size were 1.) If the
17016 rounded size is odd, then the center point (@r{@var{x}}, @r{@var{y}}) of
17017 the pixel fragment that represents the point is computed as
17019 @r{(⌊@var{x}_@var{w},⌋+.5,⌊@var{y}_@var{w},⌋+.5)}
17021 where @r{@var{w}} subscripts indicate window coordinates. All pixels
17022 that lie within the square grid of the rounded size centered at
17023 (@r{@var{x}}, @r{@var{y}}) make up the fragment. If the size is even,
17024 the center point is
17026 @r{(⌊@var{x}_@var{w}+.5,⌋,⌊@var{y}_@var{w}+.5,⌋)}
17028 and the rasterized fragment's centers are the half-integer window
17029 coordinates within the square of the rounded size centered at
17030 @r{(@var{x},@var{y})}. All pixel fragments produced in rasterizing a
17031 nonantialiased point are assigned the same associated data, that of the
17032 vertex corresponding to the point.
17034 If antialiasing is enabled, then point rasterization produces a fragment
17035 for each pixel square that intersects the region lying within the circle
17036 having diameter equal to the current point size and centered at the
17037 point's @r{(@var{x}_@var{w},@var{y}_@var{w})}. The coverage value for
17038 each fragment is the window coordinate area of the intersection of the
17039 circular region with the corresponding pixel square. This value is saved
17040 and used in the final rasterization step. The data associated with each
17041 fragment is the data associated with the point being rasterized.
17043 Not all sizes are supported when point antialiasing is enabled. If an
17044 unsupported size is requested, the nearest supported size is used. Only
17045 size 1 is guaranteed to be supported; others depend on the
17046 implementation. To query the range of supported sizes and the size
17047 difference between supported sizes within the range, call @code{glGet}
17048 with arguments @code{GL_SMOOTH_POINT_SIZE_RANGE} and
17049 @code{GL_SMOOTH_POINT_SIZE_GRANULARITY}. For aliased points, query the
17050 supported ranges and granularity with @code{glGet} with arguments
17051 @code{GL_ALIASED_POINT_SIZE_RANGE}.
17053 @code{GL_INVALID_VALUE} is generated if @var{size} is less than or equal
17056 @code{GL_INVALID_OPERATION} is generated if @code{glPointSize} is
17057 executed between the execution of @code{glBegin} and the corresponding
17058 execution of @code{glEnd}.
17062 @deftypefun void glPolygonMode face mode
17063 Select a polygon rasterization mode.
17067 Specifies the polygons that @var{mode} applies to. Must be
17068 @code{GL_FRONT} for front-facing polygons, @code{GL_BACK} for
17069 back-facing polygons, or @code{GL_FRONT_AND_BACK} for front- and
17070 back-facing polygons.
17073 Specifies how polygons will be rasterized. Accepted values are
17074 @code{GL_POINT}, @code{GL_LINE}, and @code{GL_FILL}. The initial value
17075 is @code{GL_FILL} for both front- and back-facing polygons.
17079 @code{glPolygonMode} controls the interpretation of polygons for
17080 rasterization. @var{face} describes which polygons @var{mode} applies
17081 to: front-facing polygons (@code{GL_FRONT}), back-facing polygons
17082 (@code{GL_BACK}), or both (@code{GL_FRONT_AND_BACK}). The polygon mode
17083 affects only the final rasterization of polygons. In particular, a
17084 polygon's vertices are lit and the polygon is clipped and possibly
17085 culled before these modes are applied.
17087 Three modes are defined and can be specified in @var{mode}:
17090 @item @code{GL_POINT}
17091 Polygon vertices that are marked as the start of a boundary edge are
17092 drawn as points. Point attributes such as @code{GL_POINT_SIZE} and
17093 @code{GL_POINT_SMOOTH} control the rasterization of the points. Polygon
17094 rasterization attributes other than @code{GL_POLYGON_MODE} have no
17097 @item @code{GL_LINE}
17098 Boundary edges of the polygon are drawn as line segments. They are
17099 treated as connected line segments for line stippling; the line stipple
17100 counter and pattern are not reset between segments (see
17101 @code{glLineStipple}). Line attributes such as @code{GL_LINE_WIDTH} and
17102 @code{GL_LINE_SMOOTH} control the rasterization of the lines. Polygon
17103 rasterization attributes other than @code{GL_POLYGON_MODE} have no
17106 @item @code{GL_FILL}
17107 The interior of the polygon is filled. Polygon attributes such as
17108 @code{GL_POLYGON_STIPPLE} and @code{GL_POLYGON_SMOOTH} control the
17109 rasterization of the polygon.
17113 @code{GL_INVALID_ENUM} is generated if either @var{face} or @var{mode}
17114 is not an accepted value.
17116 @code{GL_INVALID_OPERATION} is generated if @code{glPolygonMode} is
17117 executed between the execution of @code{glBegin} and the corresponding
17118 execution of @code{glEnd}.
17122 @deftypefun void glPolygonOffset factor units
17123 Set the scale and units used to calculate depth values.
17127 Specifies a scale factor that is used to create a variable depth offset
17128 for each polygon. The initial value is 0.
17131 Is multiplied by an implementation-specific value to create a constant
17132 depth offset. The initial value is 0.
17136 When @code{GL_POLYGON_OFFSET_FILL}, @code{GL_POLYGON_OFFSET_LINE}, or
17137 @code{GL_POLYGON_OFFSET_POINT} is enabled, each fragment's @var{depth}
17138 value will be offset after it is interpolated from the @var{depth}
17139 values of the appropriate vertices. The value of the offset is
17140 @r{@var{factor}×@var{DZ}+@var{r}×@var{units}}, where @r{@var{DZ}} is a
17141 measurement of the change in depth relative to the screen area of the
17142 polygon, and @r{@var{r}} is the smallest value that is guaranteed to
17143 produce a resolvable offset for a given implementation. The offset is
17144 added before the depth test is performed and before the value is written
17145 into the depth buffer.
17147 @code{glPolygonOffset} is useful for rendering hidden-line images, for
17148 applying decals to surfaces, and for rendering solids with highlighted
17151 @code{GL_INVALID_OPERATION} is generated if @code{glPolygonOffset} is
17152 executed between the execution of @code{glBegin} and the corresponding
17153 execution of @code{glEnd}.
17157 @deftypefun void glPolygonStipple pattern
17158 Set the polygon stippling pattern.
17161 @item @var{pattern}
17162 Specifies a pointer to a @r{32×32} stipple pattern that will be unpacked
17163 from memory in the same way that @code{glDrawPixels} unpacks pixels.
17167 Polygon stippling, like line stippling (see @code{glLineStipple}), masks
17168 out certain fragments produced by rasterization, creating a pattern.
17169 Stippling is independent of polygon antialiasing.
17171 @var{pattern} is a pointer to a @r{32×32} stipple pattern that is stored
17172 in memory just like the pixel data supplied to a @code{glDrawPixels}
17173 call with height and @var{width} both equal to 32, a pixel format of
17174 @code{GL_COLOR_INDEX}, and data type of @code{GL_BITMAP}. That is, the
17175 stipple pattern is represented as a @r{32×32} array of 1-bit color
17176 indices packed in unsigned bytes. @code{glPixelStore} parameters like
17177 @code{GL_UNPACK_SWAP_BYTES} and @code{GL_UNPACK_LSB_FIRST} affect the
17178 assembling of the bits into a stipple pattern. Pixel transfer operations
17179 (shift, offset, pixel map) are not applied to the stipple image,
17182 If a non-zero named buffer object is bound to the
17183 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
17184 stipple pattern is specified, @var{pattern} is treated as a byte offset
17185 into the buffer object's data store.
17187 To enable and disable polygon stippling, call @code{glEnable} and
17188 @code{glDisable} with argument @code{GL_POLYGON_STIPPLE}. Polygon
17189 stippling is initially disabled. If it's enabled, a rasterized polygon
17190 fragment with window coordinates @r{@var{x}_@var{w}} and
17191 @r{@var{y}_@var{w}} is sent to the next stage of the GL if and only if
17192 the (@r{@var{x}_@var{w}%32})th bit in the (@r{@var{y}_@var{w}%32})th row
17193 of the stipple pattern is 1 (one). When polygon stippling is disabled,
17194 it is as if the stipple pattern consists of all 1's.
17196 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
17197 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
17198 object's data store is currently mapped.
17200 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
17201 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
17202 would be unpacked from the buffer object such that the memory reads
17203 required would exceed the data store size.
17205 @code{GL_INVALID_OPERATION} is generated if @code{glPolygonStipple} is
17206 executed between the execution of @code{glBegin} and the corresponding
17207 execution of @code{glEnd}.
17211 @deftypefun void glPrioritizeTextures n textures priorities
17212 Set texture residence priority.
17216 Specifies the number of textures to be prioritized.
17218 @item @var{textures}
17219 Specifies an array containing the names of the textures to be
17222 @item @var{priorities}
17223 Specifies an array containing the texture priorities. A priority given
17224 in an element of @var{priorities} applies to the texture named by the
17225 corresponding element of @var{textures}.
17229 @code{glPrioritizeTextures} assigns the @var{n} texture priorities given
17230 in @var{priorities} to the @var{n} textures named in @var{textures}.
17232 The GL establishes a ``working set'' of textures that are resident in
17233 texture memory. These textures may be bound to a texture target much
17234 more efficiently than textures that are not resident. By specifying a
17235 priority for each texture, @code{glPrioritizeTextures} allows
17236 applications to guide the GL implementation in determining which
17237 textures should be resident.
17239 The priorities given in @var{priorities} are clamped to the range
17240 @r{[0,1]} before they are assigned. 0 indicates the lowest priority;
17241 textures with priority 0 are least likely to be resident. 1 indicates
17242 the highest priority; textures with priority 1 are most likely to be
17243 resident. However, textures are not guaranteed to be resident until they
17246 @code{glPrioritizeTextures} silently ignores attempts to prioritize
17247 texture 0 or any texture name that does not correspond to an existing
17250 @code{glPrioritizeTextures} does not require that any of the textures
17251 named by @var{textures} be bound to a texture target.
17252 @code{glTexParameter} may also be used to set a texture's priority, but
17253 only if the texture is currently bound. This is the only way to set the
17254 priority of a default texture.
17256 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
17258 @code{GL_INVALID_OPERATION} is generated if @code{glPrioritizeTextures}
17259 is executed between the execution of @code{glBegin} and the
17260 corresponding execution of @code{glEnd}.
17264 @deftypefun void glPushAttrib mask
17265 @deftypefunx void glPopAttrib
17266 Push and pop the server attribute stack.
17270 Specifies a mask that indicates which attributes to save. Values for
17271 @var{mask} are listed below.
17275 @code{glPushAttrib} takes one argument, a mask that indicates which
17276 groups of state variables to save on the attribute stack. Symbolic
17277 constants are used to set bits in the mask. @var{mask} is typically
17278 constructed by specifying the bitwise-or of several of these constants
17279 together. The special mask @code{GL_ALL_ATTRIB_BITS} can be used to save
17280 all stackable states.
17282 The symbolic mask constants and their associated GL state are as follows
17283 (the second column lists which attributes are saved):
17288 @item @code{GL_ACCUM_BUFFER_BIT}
17289 Accumulation buffer clear value
17291 @item @code{GL_COLOR_BUFFER_BIT}
17292 @code{GL_ALPHA_TEST} enable bit
17295 Alpha test function and reference value
17298 @code{GL_BLEND} enable bit
17301 Blending source and destination functions
17304 Constant blend color
17310 @code{GL_DITHER} enable bit
17313 @code{GL_DRAW_BUFFER} setting
17316 @code{GL_COLOR_LOGIC_OP} enable bit
17319 @code{GL_INDEX_LOGIC_OP} enable bit
17325 Color mode and index mode clear values
17328 Color mode and index mode writemasks
17330 @item @code{GL_CURRENT_BIT}
17334 Current color index
17337 Current normal vector
17340 Current texture coordinates
17343 Current raster position
17346 @code{GL_CURRENT_RASTER_POSITION_VALID} flag
17349 RGBA color associated with current raster position
17352 Color index associated with current raster position
17355 Texture coordinates associated with current raster position
17358 @code{GL_EDGE_FLAG} flag
17360 @item @code{GL_DEPTH_BUFFER_BIT}
17361 @code{GL_DEPTH_TEST} enable bit
17364 Depth buffer test function
17367 Depth buffer clear value
17370 @code{GL_DEPTH_WRITEMASK} enable bit
17372 @item @code{GL_ENABLE_BIT}
17373 @code{GL_ALPHA_TEST} flag
17376 @code{GL_AUTO_NORMAL} flag
17379 @code{GL_BLEND} flag
17382 Enable bits for the user-definable clipping planes
17385 @code{GL_COLOR_MATERIAL}
17388 @code{GL_CULL_FACE} flag
17391 @code{GL_DEPTH_TEST} flag
17394 @code{GL_DITHER} flag
17400 @code{GL_LIGHT}@var{i} where @code{0} <= @var{i} < @code{GL_MAX_LIGHTS}
17403 @code{GL_LIGHTING} flag
17406 @code{GL_LINE_SMOOTH} flag
17409 @code{GL_LINE_STIPPLE} flag
17412 @code{GL_COLOR_LOGIC_OP} flag
17415 @code{GL_INDEX_LOGIC_OP} flag
17418 @code{GL_MAP1_}@var{x} where @var{x} is a map type
17421 @code{GL_MAP2_}@var{x} where @var{x} is a map type
17424 @code{GL_MULTISAMPLE} flag
17427 @code{GL_NORMALIZE} flag
17430 @code{GL_POINT_SMOOTH} flag
17433 @code{GL_POLYGON_OFFSET_LINE} flag
17436 @code{GL_POLYGON_OFFSET_FILL} flag
17439 @code{GL_POLYGON_OFFSET_POINT} flag
17442 @code{GL_POLYGON_SMOOTH} flag
17445 @code{GL_POLYGON_STIPPLE} flag
17448 @code{GL_SAMPLE_ALPHA_TO_COVERAGE} flag
17451 @code{GL_SAMPLE_ALPHA_TO_ONE} flag
17454 @code{GL_SAMPLE_COVERAGE} flag
17457 @code{GL_SCISSOR_TEST} flag
17460 @code{GL_STENCIL_TEST} flag
17463 @code{GL_TEXTURE_1D} flag
17466 @code{GL_TEXTURE_2D} flag
17469 @code{GL_TEXTURE_3D} flag
17472 Flags @code{GL_TEXTURE_GEN_}@var{x} where @var{x} is S, T, R, or Q
17474 @item @code{GL_EVAL_BIT}
17475 @code{GL_MAP1_}@var{x} enable bits, where @var{x} is a map type
17478 @code{GL_MAP2_}@var{x} enable bits, where @var{x} is a map type
17481 1D grid endpoints and divisions
17484 2D grid endpoints and divisions
17487 @code{GL_AUTO_NORMAL} enable bit
17489 @item @code{GL_FOG_BIT}
17490 @code{GL_FOG} enable bit
17508 @code{GL_FOG_MODE} value
17510 @item @code{GL_HINT_BIT}
17511 @code{GL_PERSPECTIVE_CORRECTION_HINT} setting
17514 @code{GL_POINT_SMOOTH_HINT} setting
17517 @code{GL_LINE_SMOOTH_HINT} setting
17520 @code{GL_POLYGON_SMOOTH_HINT} setting
17523 @code{GL_FOG_HINT} setting
17526 @code{GL_GENERATE_MIPMAP_HINT} setting
17529 @code{GL_TEXTURE_COMPRESSION_HINT} setting
17531 @item @code{GL_LIGHTING_BIT}
17532 @code{GL_COLOR_MATERIAL} enable bit
17535 @code{GL_COLOR_MATERIAL_FACE} value
17538 Color material parameters that are tracking the current color
17541 Ambient scene color
17544 @code{GL_LIGHT_MODEL_LOCAL_VIEWER} value
17547 @code{GL_LIGHT_MODEL_TWO_SIDE} setting
17550 @code{GL_LIGHTING} enable bit
17553 Enable bit for each light
17556 Ambient, diffuse, and specular intensity for each light
17559 Direction, position, exponent, and cutoff angle for each light
17562 Constant, linear, and quadratic attenuation factors for each light
17565 Ambient, diffuse, specular, and emissive color for each material
17568 Ambient, diffuse, and specular color indices for each material
17571 Specular exponent for each material
17574 @code{GL_SHADE_MODEL} setting
17576 @item @code{GL_LINE_BIT}
17577 @code{GL_LINE_SMOOTH} flag
17580 @code{GL_LINE_STIPPLE} enable bit
17583 Line stipple pattern and repeat counter
17588 @item @code{GL_LIST_BIT}
17589 @code{GL_LIST_BASE} setting
17591 @item @code{GL_MULTISAMPLE_BIT}
17592 @code{GL_MULTISAMPLE} flag
17595 @code{GL_SAMPLE_ALPHA_TO_COVERAGE} flag
17598 @code{GL_SAMPLE_ALPHA_TO_ONE} flag
17601 @code{GL_SAMPLE_COVERAGE} flag
17604 @code{GL_SAMPLE_COVERAGE_VALUE} value
17607 @code{GL_SAMPLE_COVERAGE_INVERT} value
17609 @item @code{GL_PIXEL_MODE_BIT}
17610 @code{GL_RED_BIAS} and @code{GL_RED_SCALE} settings
17613 @code{GL_GREEN_BIAS} and @code{GL_GREEN_SCALE} values
17616 @code{GL_BLUE_BIAS} and @code{GL_BLUE_SCALE}
17619 @code{GL_ALPHA_BIAS} and @code{GL_ALPHA_SCALE}
17622 @code{GL_DEPTH_BIAS} and @code{GL_DEPTH_SCALE}
17625 @code{GL_INDEX_OFFSET} and @code{GL_INDEX_SHIFT} values
17628 @code{GL_MAP_COLOR} and @code{GL_MAP_STENCIL} flags
17631 @code{GL_ZOOM_X} and @code{GL_ZOOM_Y} factors
17634 @code{GL_READ_BUFFER} setting
17636 @item @code{GL_POINT_BIT}
17637 @code{GL_POINT_SMOOTH} flag
17642 @item @code{GL_POLYGON_BIT}
17643 @code{GL_CULL_FACE} enable bit
17646 @code{GL_CULL_FACE_MODE} value
17649 @code{GL_FRONT_FACE} indicator
17652 @code{GL_POLYGON_MODE} setting
17655 @code{GL_POLYGON_SMOOTH} flag
17658 @code{GL_POLYGON_STIPPLE} enable bit
17661 @code{GL_POLYGON_OFFSET_FILL} flag
17664 @code{GL_POLYGON_OFFSET_LINE} flag
17667 @code{GL_POLYGON_OFFSET_POINT} flag
17670 @code{GL_POLYGON_OFFSET_FACTOR}
17673 @code{GL_POLYGON_OFFSET_UNITS}
17675 @item @code{GL_POLYGON_STIPPLE_BIT}
17676 Polygon stipple image
17678 @item @code{GL_SCISSOR_BIT}
17679 @code{GL_SCISSOR_TEST} flag
17684 @item @code{GL_STENCIL_BUFFER_BIT}
17685 @code{GL_STENCIL_TEST} enable bit
17688 Stencil function and reference value
17694 Stencil fail, pass, and depth buffer pass actions
17697 Stencil buffer clear value
17700 Stencil buffer writemask
17702 @item @code{GL_TEXTURE_BIT}
17703 Enable bits for the four texture coordinates
17706 Border color for each texture image
17709 Minification function for each texture image
17712 Magnification function for each texture image
17715 Texture coordinates and wrap mode for each texture image
17718 Color and mode for each texture environment
17721 Enable bits @code{GL_TEXTURE_GEN_}@var{x}, @var{x} is S, T, R, and Q
17724 @code{GL_TEXTURE_GEN_MODE} setting for S, T, R, and Q
17727 @code{glTexGen} plane equations for S, T, R, and Q
17730 Current texture bindings (for example, @code{GL_TEXTURE_BINDING_2D})
17732 @item @code{GL_TRANSFORM_BIT}
17733 Coefficients of the six clipping planes
17736 Enable bits for the user-definable clipping planes
17739 @code{GL_MATRIX_MODE} value
17742 @code{GL_NORMALIZE} flag
17745 @code{GL_RESCALE_NORMAL} flag
17747 @item @code{GL_VIEWPORT_BIT}
17748 Depth range (near and far)
17751 Viewport origin and extent
17755 @code{glPopAttrib} restores the values of the state variables saved with
17756 the last @code{glPushAttrib} command. Those not saved are left
17759 It is an error to push attributes onto a full stack or to pop attributes
17760 off an empty stack. In either case, the error flag is set and no other
17761 change is made to GL state.
17763 Initially, the attribute stack is empty.
17765 @code{GL_STACK_OVERFLOW} is generated if @code{glPushAttrib} is called
17766 while the attribute stack is full.
17768 @code{GL_STACK_UNDERFLOW} is generated if @code{glPopAttrib} is called
17769 while the attribute stack is empty.
17771 @code{GL_INVALID_OPERATION} is generated if @code{glPushAttrib} or
17772 @code{glPopAttrib} is executed between the execution of @code{glBegin}
17773 and the corresponding execution of @code{glEnd}.
17777 @deftypefun void glPushClientAttrib mask
17778 @deftypefunx void glPopClientAttrib
17779 Push and pop the client attribute stack.
17783 Specifies a mask that indicates which attributes to save. Values for
17784 @var{mask} are listed below.
17788 @code{glPushClientAttrib} takes one argument, a mask that indicates
17789 which groups of client-state variables to save on the client attribute
17790 stack. Symbolic constants are used to set bits in the mask. @var{mask}
17791 is typically constructed by specifying the bitwise-or of several of
17792 these constants together. The special mask
17793 @code{GL_CLIENT_ALL_ATTRIB_BITS} can be used to save all stackable
17796 The symbolic mask constants and their associated GL client state are as
17797 follows (the second column lists which attributes are saved):
17799 @code{GL_CLIENT_PIXEL_STORE_BIT} Pixel storage modes
17800 @code{GL_CLIENT_VERTEX_ARRAY_BIT} Vertex arrays (and enables)
17802 @code{glPopClientAttrib} restores the values of the client-state
17803 variables saved with the last @code{glPushClientAttrib}. Those not saved
17804 are left unchanged.
17806 It is an error to push attributes onto a full client attribute stack or
17807 to pop attributes off an empty stack. In either case, the error flag is
17808 set, and no other change is made to GL state.
17810 Initially, the client attribute stack is empty.
17812 @code{GL_STACK_OVERFLOW} is generated if @code{glPushClientAttrib} is
17813 called while the attribute stack is full.
17815 @code{GL_STACK_UNDERFLOW} is generated if @code{glPopClientAttrib} is
17816 called while the attribute stack is empty.
17820 @deftypefun void glPushMatrix
17821 @deftypefunx void glPopMatrix
17822 Push and pop the current matrix stack.
17824 There is a stack of matrices for each of the matrix modes. In
17825 @code{GL_MODELVIEW} mode, the stack depth is at least 32. In the other
17826 modes, @code{GL_COLOR}, @code{GL_PROJECTION}, and @code{GL_TEXTURE}, the
17827 depth is at least 2. The current matrix in any mode is the matrix on the
17828 top of the stack for that mode.
17830 @code{glPushMatrix} pushes the current matrix stack down by one,
17831 duplicating the current matrix. That is, after a @code{glPushMatrix}
17832 call, the matrix on top of the stack is identical to the one below it.
17834 @code{glPopMatrix} pops the current matrix stack, replacing the current
17835 matrix with the one below it on the stack.
17837 Initially, each of the stacks contains one matrix, an identity matrix.
17839 It is an error to push a full matrix stack or to pop a matrix stack that
17840 contains only a single matrix. In either case, the error flag is set and
17841 no other change is made to GL state.
17843 @code{GL_STACK_OVERFLOW} is generated if @code{glPushMatrix} is called
17844 while the current matrix stack is full.
17846 @code{GL_STACK_UNDERFLOW} is generated if @code{glPopMatrix} is called
17847 while the current matrix stack contains only a single matrix.
17849 @code{GL_INVALID_OPERATION} is generated if @code{glPushMatrix} or
17850 @code{glPopMatrix} is executed between the execution of @code{glBegin}
17851 and the corresponding execution of @code{glEnd}.
17855 @deftypefun void glPushName name
17856 @deftypefunx void glPopName
17857 Push and pop the name stack.
17861 Specifies a name that will be pushed onto the name stack.
17865 The name stack is used during selection mode to allow sets of rendering
17866 commands to be uniquely identified. It consists of an ordered set of
17867 unsigned integers and is initially empty.
17869 @code{glPushName} causes @var{name} to be pushed onto the name stack.
17870 @code{glPopName} pops one name off the top of the stack.
17872 The maximum name stack depth is implementation-dependent; call
17873 @code{GL_MAX_NAME_STACK_DEPTH} to find out the value for a particular
17874 implementation. It is an error to push a name onto a full stack or to
17875 pop a name off an empty stack. It is also an error to manipulate the
17876 name stack between the execution of @code{glBegin} and the corresponding
17877 execution of @code{glEnd}. In any of these cases, the error flag is set
17878 and no other change is made to GL state.
17880 The name stack is always empty while the render mode is not
17881 @code{GL_SELECT}. Calls to @code{glPushName} or @code{glPopName} while
17882 the render mode is not @code{GL_SELECT} are ignored.
17884 @code{GL_STACK_OVERFLOW} is generated if @code{glPushName} is called
17885 while the name stack is full.
17887 @code{GL_STACK_UNDERFLOW} is generated if @code{glPopName} is called
17888 while the name stack is empty.
17890 @code{GL_INVALID_OPERATION} is generated if @code{glPushName} or
17891 @code{glPopName} is executed between a call to @code{glBegin} and the
17892 corresponding call to @code{glEnd}.
17896 @deftypefun void glRasterPos2i x y
17897 @deftypefunx void glRasterPos2f x y
17898 @deftypefunx void glRasterPos3i x y z
17899 @deftypefunx void glRasterPos3f x y z
17900 @deftypefunx void glRasterPos4i x y z w
17901 @deftypefunx void glRasterPos4f x y z w
17902 Specify the raster position for pixel operations.
17909 Specify the @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}
17910 object coordinates (if present) for the raster position.
17914 The GL maintains a 3D position in window coordinates. This position,
17915 called the raster position, is used to position pixel and bitmap write
17916 operations. It is maintained with subpixel accuracy. See
17917 @code{glBitmap}, @code{glDrawPixels}, and @code{glCopyPixels}.
17919 The current raster position consists of three window coordinates
17920 (@r{@var{x}}, @r{@var{y}}, @r{@var{z}}), a clip coordinate value
17921 (@r{@var{w}}), an eye coordinate distance, a valid bit, and associated
17922 color data and texture coordinates. The @r{@var{w}} coordinate is a clip
17923 coordinate, because @r{@var{w}} is not projected to window coordinates.
17924 @code{glRasterPos4} specifies object coordinates @r{@var{x}},
17925 @r{@var{y}}, @r{@var{z}}, and @r{@var{w}} explicitly.
17926 @code{glRasterPos3} specifies object coordinate @r{@var{x}},
17927 @r{@var{y}}, and @r{@var{z}} explicitly, while @r{@var{w}} is implicitly
17928 set to 1. @code{glRasterPos2} uses the argument values for @r{@var{x}}
17929 and @r{@var{y}} while implicitly setting @r{@var{z}} and @r{@var{w}} to
17932 The object coordinates presented by @code{glRasterPos} are treated just
17933 like those of a @code{glVertex} command: They are transformed by the
17934 current modelview and projection matrices and passed to the clipping
17935 stage. If the vertex is not culled, then it is projected and scaled to
17936 window coordinates, which become the new current raster position, and
17937 the @code{GL_CURRENT_RASTER_POSITION_VALID} flag is set. If the vertex
17938 @var{is} culled, then the valid bit is cleared and the current raster
17939 position and associated color and texture coordinates are undefined.
17941 The current raster position also includes some associated color data and
17942 texture coordinates. If lighting is enabled, then
17943 @code{GL_CURRENT_RASTER_COLOR} (in RGBA mode) or
17944 @code{GL_CURRENT_RASTER_INDEX} (in color index mode) is set to the color
17945 produced by the lighting calculation (see @code{glLight},
17946 @code{glLightModel}, and @code{glShadeModel}). If lighting is disabled,
17947 current color (in RGBA mode, state variable @code{GL_CURRENT_COLOR}) or
17948 color index (in color index mode, state variable
17949 @code{GL_CURRENT_INDEX}) is used to update the current raster color.
17950 @code{GL_CURRENT_RASTER_SECONDARY_COLOR} (in RGBA mode) is likewise
17953 Likewise, @code{GL_CURRENT_RASTER_TEXTURE_COORDS} is updated as a
17954 function of @code{GL_CURRENT_TEXTURE_COORDS}, based on the texture
17955 matrix and the texture generation functions (see @code{glTexGen}).
17956 Finally, the distance from the origin of the eye coordinate system to
17957 the vertex as transformed by only the modelview matrix replaces
17958 @code{GL_CURRENT_RASTER_DISTANCE}.
17960 Initially, the current raster position is (0, 0, 0, 1), the current
17961 raster distance is 0, the valid bit is set, the associated RGBA color is
17962 (1, 1, 1, 1), the associated color index is 1, and the associated
17963 texture coordinates are (0, 0, 0, 1). In RGBA mode,
17964 @code{GL_CURRENT_RASTER_INDEX} is always 1; in color index mode, the
17965 current raster RGBA color always maintains its initial value.
17967 @code{GL_INVALID_OPERATION} is generated if @code{glRasterPos} is
17968 executed between the execution of @code{glBegin} and the corresponding
17969 execution of @code{glEnd}.
17973 @deftypefun void glReadBuffer mode
17974 Select a color buffer source for pixels.
17978 Specifies a color buffer. Accepted values are @code{GL_FRONT_LEFT},
17979 @code{GL_FRONT_RIGHT}, @code{GL_BACK_LEFT}, @code{GL_BACK_RIGHT},
17980 @code{GL_FRONT}, @code{GL_BACK}, @code{GL_LEFT}, @code{GL_RIGHT}, and
17981 @code{GL_AUX}@var{i}, where @var{i} is between 0 and the value of
17982 @code{GL_AUX_BUFFERS} minus 1.
17986 @code{glReadBuffer} specifies a color buffer as the source for
17987 subsequent @code{glReadPixels}, @code{glCopyTexImage1D},
17988 @code{glCopyTexImage2D}, @code{glCopyTexSubImage1D},
17989 @code{glCopyTexSubImage2D}, @code{glCopyTexSubImage3D}, and
17990 @code{glCopyPixels} commands. @var{mode} accepts one of twelve or more
17991 predefined values. (@code{GL_AUX0} through @code{GL_AUX3} are always
17992 defined.) In a fully configured system, @code{GL_FRONT}, @code{GL_LEFT},
17993 and @code{GL_FRONT_LEFT} all name the front left buffer,
17994 @code{GL_FRONT_RIGHT} and @code{GL_RIGHT} name the front right buffer,
17995 and @code{GL_BACK_LEFT} and @code{GL_BACK} name the back left buffer.
17997 Nonstereo double-buffered configurations have only a front left and a
17998 back left buffer. Single-buffered configurations have a front left and a
17999 front right buffer if stereo, and only a front left buffer if nonstereo.
18000 It is an error to specify a nonexistent buffer to @code{glReadBuffer}.
18002 @var{mode} is initially @code{GL_FRONT} in single-buffered
18003 configurations and @code{GL_BACK} in double-buffered configurations.
18005 @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of the
18006 twelve (or more) accepted values.
18008 @code{GL_INVALID_OPERATION} is generated if @var{mode} specifies a
18009 buffer that does not exist.
18011 @code{GL_INVALID_OPERATION} is generated if @code{glReadBuffer} is
18012 executed between the execution of @code{glBegin} and the corresponding
18013 execution of @code{glEnd}.
18017 @deftypefun void glReadPixels x y width height format type data
18018 Read a block of pixels from the frame buffer.
18023 Specify the window coordinates of the first pixel that is read from the
18024 frame buffer. This location is the lower left corner of a rectangular
18028 @itemx @var{height}
18029 Specify the dimensions of the pixel rectangle. @var{width} and
18030 @var{height} of one correspond to a single pixel.
18033 Specifies the format of the pixel data. The following symbolic values
18034 are accepted: @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX},
18035 @code{GL_DEPTH_COMPONENT}, @code{GL_RED}, @code{GL_GREEN},
18036 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
18037 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
18038 @code{GL_LUMINANCE_ALPHA}.
18041 Specifies the data type of the pixel data. Must be one of
18042 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
18043 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
18044 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
18045 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
18046 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
18047 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
18048 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
18049 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
18050 or @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
18053 Returns the pixel data.
18057 @code{glReadPixels} returns pixel data from the frame buffer, starting
18058 with the pixel whose lower left corner is at location (@var{x},
18059 @var{y}), into client memory starting at location @var{data}. Several
18060 parameters control the processing of the pixel data before it is placed
18061 into client memory. These parameters are set with three commands:
18062 @code{glPixelStore}, @code{glPixelTransfer}, and @code{glPixelMap}. This
18063 reference page describes the effects on @code{glReadPixels} of most, but
18064 not all of the parameters specified by these three commands.
18066 If a non-zero named buffer object is bound to the
18067 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
18068 block of pixels is requested, @var{data} is treated as a byte offset
18069 into the buffer object's data store rather than a pointer to client
18072 When the @code{ARB_imaging} extension is supported, the pixel data may
18073 be processed by additional operations including color table lookup,
18074 color matrix transformations, convolutions, histograms, and minimum and
18075 maximum pixel value computations.
18077 @code{glReadPixels} returns values from each pixel with lower left
18078 corner at @r{(@var{x}+@var{i},@var{y}+@var{j})} for
18079 @r{0<=@var{i}<@var{width}} and @r{0<=@var{j}<@var{height}}. This pixel
18080 is said to be the @r{@var{i}}th pixel in the @r{@var{j}}th row. Pixels
18081 are returned in row order from the lowest to the highest row, left to
18084 @var{format} specifies the format for the returned pixel values;
18085 accepted values are:
18088 @item @code{GL_COLOR_INDEX}
18089 Color indices are read from the color buffer selected by
18090 @code{glReadBuffer}. Each index is converted to fixed point, shifted
18091 left or right depending on the value and sign of @code{GL_INDEX_SHIFT},
18092 and added to @code{GL_INDEX_OFFSET}. If @code{GL_MAP_COLOR} is
18093 @code{GL_TRUE}, indices are replaced by their mappings in the table
18094 @code{GL_PIXEL_MAP_I_TO_I}.
18096 @item @code{GL_STENCIL_INDEX}
18097 Stencil values are read from the stencil buffer. Each index is converted
18098 to fixed point, shifted left or right depending on the value and sign of
18099 @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET}. If
18100 @code{GL_MAP_STENCIL} is @code{GL_TRUE}, indices are replaced by their
18101 mappings in the table @code{GL_PIXEL_MAP_S_TO_S}.
18103 @item @code{GL_DEPTH_COMPONENT}
18104 Depth values are read from the depth buffer. Each component is converted
18105 to floating point such that the minimum depth value maps to 0 and the
18106 maximum value maps to 1. Each component is then multiplied by
18107 @code{GL_DEPTH_SCALE}, added to @code{GL_DEPTH_BIAS}, and finally
18108 clamped to the range @r{[0,1]}.
18110 @item @code{GL_RED}
18111 @item @code{GL_GREEN}
18112 @item @code{GL_BLUE}
18113 @item @code{GL_ALPHA}
18114 @item @code{GL_RGB}
18115 @item @code{GL_BGR}
18116 @item @code{GL_RGBA}
18117 @item @code{GL_BGRA}
18118 @item @code{GL_LUMINANCE}
18119 @item @code{GL_LUMINANCE_ALPHA}
18120 Processing differs depending on whether color buffers store color
18121 indices or RGBA color components. If color indices are stored, they are
18122 read from the color buffer selected by @code{glReadBuffer}. Each index
18123 is converted to fixed point, shifted left or right depending on the
18124 value and sign of @code{GL_INDEX_SHIFT}, and added to
18125 @code{GL_INDEX_OFFSET}. Indices are then replaced by the red, green,
18126 blue, and alpha values obtained by indexing the tables
18127 @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G},
18128 @code{GL_PIXEL_MAP_I_TO_B}, and @code{GL_PIXEL_MAP_I_TO_A}. Each table
18129 must be of size @r{2^@var{n}}, but @r{@var{n}} may be different for
18130 different tables. Before an index is used to look up a value in a table
18131 of size @r{2^@var{n}}, it must be masked against @r{2^@var{n}-1}.
18133 If RGBA color components are stored in the color buffers, they are read
18134 from the color buffer selected by @code{glReadBuffer}. Each color
18135 component is converted to floating point such that zero intensity maps
18136 to 0.0 and full intensity maps to 1.0. Each component is then multiplied
18137 by @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is
18138 RED, GREEN, BLUE, or ALPHA. Finally, if @code{GL_MAP_COLOR} is
18139 @code{GL_TRUE}, each component is clamped to the range @r{[0,1]}, scaled
18140 to the size of its corresponding table, and is then replaced by its
18141 mapping in the table @code{GL_PIXEL_MAP_c_TO_c}, where @var{c} is R, G,
18144 Unneeded data is then discarded. For example, @code{GL_RED} discards the
18145 green, blue, and alpha components, while @code{GL_RGB} discards only the
18146 alpha component. @code{GL_LUMINANCE} computes a single-component value
18147 as the sum of the red, green, and blue components, and
18148 @code{GL_LUMINANCE_ALPHA} does the same, while keeping alpha as a second
18149 value. The final values are clamped to the range @r{[0,1]}.
18153 The shift, scale, bias, and lookup factors just described are all
18154 specified by @code{glPixelTransfer}. The lookup table contents
18155 themselves are specified by @code{glPixelMap}.
18157 Finally, the indices or components are converted to the proper format,
18158 as specified by @var{type}. If @var{format} is @code{GL_COLOR_INDEX} or
18159 @code{GL_STENCIL_INDEX} and @var{type} is not @code{GL_FLOAT}, each
18160 index is masked with the mask value given in the following table. If
18161 @var{type} is @code{GL_FLOAT}, then each integer index is converted to
18162 single-precision floating-point format.
18164 If @var{format} is @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE},
18165 @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA},
18166 @code{GL_BGRA}, @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA} and
18167 @var{type} is not @code{GL_FLOAT}, each component is multiplied by the
18168 multiplier shown in the following table. If type is @code{GL_FLOAT},
18169 then each component is passed as is (or converted to the client's
18170 single-precision floating-point format if it is different from the one
18177 @strong{Index Mask}, @strong{Component Conversion}
18179 @item @code{GL_UNSIGNED_BYTE}
18180 @r{2^8-1}, @r{(2^8-1,)@var{c}}
18182 @item @code{GL_BYTE}
18183 @r{2^7-1}, @r{(2^8-1,)@var{c}-1,/2}
18185 @item @code{GL_BITMAP}
18188 @item @code{GL_UNSIGNED_SHORT}
18189 @r{2^16-1}, @r{(2^16-1,)@var{c}}
18191 @item @code{GL_SHORT}
18192 @r{2^15-1}, @r{(2^16-1,)@var{c}-1,/2}
18194 @item @code{GL_UNSIGNED_INT}
18195 @r{2^32-1}, @r{(2^32-1,)@var{c}}
18197 @item @code{GL_INT}
18198 @r{2^31-1}, @r{(2^32-1,)@var{c}-1,/2}
18200 @item @code{GL_FLOAT}
18205 Return values are placed in memory as follows. If @var{format} is
18206 @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX},
18207 @code{GL_DEPTH_COMPONENT}, @code{GL_RED}, @code{GL_GREEN},
18208 @code{GL_BLUE}, @code{GL_ALPHA}, or @code{GL_LUMINANCE}, a single value
18209 is returned and the data for the @r{@var{i}}th pixel in the
18210 @r{@var{j}}th row is placed in location
18211 @r{(@var{j},)@var{width}+@var{i}}. @code{GL_RGB} and @code{GL_BGR}
18212 return three values, @code{GL_RGBA} and @code{GL_BGRA} return four
18213 values, and @code{GL_LUMINANCE_ALPHA} returns two values for each pixel,
18214 with all values corresponding to a single pixel occupying contiguous
18215 space in @var{data}. Storage parameters set by @code{glPixelStore}, such
18216 as @code{GL_PACK_LSB_FIRST} and @code{GL_PACK_SWAP_BYTES}, affect the
18217 way that data is written into memory. See @code{glPixelStore} for a
18220 @code{GL_INVALID_ENUM} is generated if @var{format} or @var{type} is not
18223 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
18224 and @var{format} is not @code{GL_COLOR_INDEX} or
18225 @code{GL_STENCIL_INDEX}.
18227 @code{GL_INVALID_VALUE} is generated if either @var{width} or
18228 @var{height} is negative.
18230 @code{GL_INVALID_OPERATION} is generated if @var{format} is
18231 @code{GL_COLOR_INDEX} and the color buffers store RGBA color components.
18233 @code{GL_INVALID_OPERATION} is generated if @var{format} is
18234 @code{GL_STENCIL_INDEX} and there is no stencil buffer.
18236 @code{GL_INVALID_OPERATION} is generated if @var{format} is
18237 @code{GL_DEPTH_COMPONENT} and there is no depth buffer.
18239 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
18240 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
18241 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
18242 and @var{format} is not @code{GL_RGB}.
18244 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
18245 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
18246 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
18247 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
18248 @code{GL_UNSIGNED_INT_10_10_10_2}, or
18249 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
18250 @code{GL_RGBA} nor @code{GL_BGRA}.
18252 The formats @code{GL_BGR}, and @code{GL_BGRA} and types
18253 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
18254 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
18255 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
18256 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
18257 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
18258 @code{GL_UNSIGNED_INT_10_10_10_2}, and
18259 @code{GL_UNSIGNED_INT_2_10_10_10_REV} are available only if the GL
18260 version is 1.2 or greater.
18262 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
18263 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
18264 object's data store is currently mapped.
18266 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
18267 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
18268 would be packed to the buffer object such that the memory writes
18269 required would exceed the data store size.
18271 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
18272 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{data}
18273 is not evenly divisible into the number of bytes needed to store in
18274 memory a datum indicated by @var{type}.
18276 @code{GL_INVALID_OPERATION} is generated if @code{glReadPixels} is
18277 executed between the execution of @code{glBegin} and the corresponding
18278 execution of @code{glEnd}.
18282 @deftypefun void glRectf x1 y1 x2 y2
18283 @deftypefunx void glRecti x1 y1 x2 y2
18289 Specify one vertex of a rectangle.
18293 Specify the opposite vertex of the rectangle.
18297 @code{glRect} supports efficient specification of rectangles as two
18298 corner points. Each rectangle command takes four arguments, organized
18299 either as two consecutive pairs of @r{(@var{x},@var{y})} coordinates or
18300 as two pointers to arrays, each containing an @r{(@var{x},@var{y})}
18301 pair. The resulting rectangle is defined in the @r{@var{z}=0} plane.
18303 @code{glRect}(@var{x1}, @var{y1}, @var{x2}, @var{y2}) is exactly
18304 equivalent to the following sequence: Note that if the second vertex is
18305 above and to the right of the first vertex, the rectangle is constructed
18306 with a counterclockwise winding.
18310 glBegin(@code{GL_POLYGON});
18311 glVertex2(@var{x1}, @var{y1});
18312 glVertex2(@var{x2}, @var{y1});
18313 glVertex2(@var{x2}, @var{y2});
18314 glVertex2(@var{x1}, @var{y2});
18318 @code{GL_INVALID_OPERATION} is generated if @code{glRect} is executed
18319 between the execution of @code{glBegin} and the corresponding execution
18324 @deftypefun GLint glRenderMode mode
18325 Set rasterization mode.
18329 Specifies the rasterization mode. Three values are accepted:
18330 @code{GL_RENDER}, @code{GL_SELECT}, and @code{GL_FEEDBACK}. The initial
18331 value is @code{GL_RENDER}.
18335 @code{glRenderMode} sets the rasterization mode. It takes one argument,
18336 @var{mode}, which can assume one of three predefined values:
18339 @item @code{GL_RENDER}
18340 Render mode. Primitives are rasterized, producing pixel fragments, which
18341 are written into the frame buffer. This is the normal mode and also the
18344 @item @code{GL_SELECT}
18345 Selection mode. No pixel fragments are produced, and no change to the
18346 frame buffer contents is made. Instead, a record of the names of
18347 primitives that would have been drawn if the render mode had been
18348 @code{GL_RENDER} is returned in a select buffer, which must be created
18349 (see @code{glSelectBuffer}) before selection mode is entered.
18351 @item @code{GL_FEEDBACK}
18352 Feedback mode. No pixel fragments are produced, and no change to the
18353 frame buffer contents is made. Instead, the coordinates and attributes
18354 of vertices that would have been drawn if the render mode had been
18355 @code{GL_RENDER} is returned in a feedback buffer, which must be created
18356 (see @code{glFeedbackBuffer}) before feedback mode is entered.
18360 The return value of @code{glRenderMode} is determined by the render mode
18361 at the time @code{glRenderMode} is called, rather than by @var{mode}.
18362 The values returned for the three render modes are as follows:
18365 @item @code{GL_RENDER}
18368 @item @code{GL_SELECT}
18369 The number of hit records transferred to the select buffer.
18371 @item @code{GL_FEEDBACK}
18372 The number of values (not vertices) transferred to the feedback buffer.
18376 See the @code{glSelectBuffer} and @code{glFeedbackBuffer} reference
18377 pages for more details concerning selection and feedback operation.
18379 @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of the
18380 three accepted values.
18382 @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is
18383 called while the render mode is @code{GL_SELECT}, or if
18384 @code{glRenderMode} is called with argument @code{GL_SELECT} before
18385 @code{glSelectBuffer} is called at least once.
18387 @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is
18388 called while the render mode is @code{GL_FEEDBACK}, or if
18389 @code{glRenderMode} is called with argument @code{GL_FEEDBACK} before
18390 @code{glFeedbackBuffer} is called at least once.
18392 @code{GL_INVALID_OPERATION} is generated if @code{glRenderMode} is
18393 executed between the execution of @code{glBegin} and the corresponding
18394 execution of @code{glEnd}.
18398 @deftypefun void glResetHistogram target
18399 Reset histogram table entries to zero.
18403 Must be @code{GL_HISTOGRAM}.
18407 @code{glResetHistogram} resets all the elements of the current histogram
18410 @code{GL_INVALID_ENUM} is generated if @var{target} is not
18411 @code{GL_HISTOGRAM}.
18413 @code{GL_INVALID_OPERATION} is generated if @code{glResetHistogram} is
18414 executed between the execution of @code{glBegin} and the corresponding
18415 execution of @code{glEnd}.
18419 @deftypefun void glResetMinmax target
18420 Reset minmax table entries to initial values.
18424 Must be @code{GL_MINMAX}.
18428 @code{glResetMinmax} resets the elements of the current minmax table to
18429 their initial values: the ``maximum'' element receives the minimum
18430 possible component values, and the ``minimum'' element receives the
18431 maximum possible component values.
18433 @code{GL_INVALID_ENUM} is generated if @var{target} is not
18436 @code{GL_INVALID_OPERATION} is generated if @code{glResetMinmax} is
18437 executed between the execution of @code{glBegin} and the corresponding
18438 execution of @code{glEnd}.
18442 @deftypefun void glRotatef angle x y z
18443 Multiply the current matrix by a rotation matrix.
18447 Specifies the angle of rotation, in degrees.
18452 Specify the @var{x}, @var{y}, and @var{z} coordinates of a vector,
18457 @code{glRotate} produces a rotation of @var{angle} degrees around the
18458 vector @r{(@var{x},@var{y}@var{z})}. The current matrix (see
18459 @code{glMatrixMode}) is multiplied by a rotation matrix with the product
18460 replacing the current matrix, as if @code{glMultMatrix} were called with
18461 the following matrix as its argument:
18463 @r{((@var{x}^2(1-@var{c},)+@var{c}
18464 @var{x}@var{y}(1-@var{c},)-@var{z}@var{s}
18465 @var{x}@var{z}(1-@var{c},)+@var{y}@var{s} 0),
18466 (@var{y}@var{x}(1-@var{c},)+@var{z}@var{s}
18467 @var{y}^2(1-@var{c},)+@var{c}
18468 @var{y}@var{z}(1-@var{c},)-@var{x}@var{s} 0),
18469 (@var{x}@var{z}(1-@var{c},)-@var{y}@var{s}
18470 @var{y}@var{z}(1-@var{c},)+@var{x}@var{s}
18471 @var{z}^2(1-@var{c},)+@var{c} 0), (0 0 0 1),)}
18475 Where @r{@var{c}=@var{cos}(@var{angle},)},
18476 @r{@var{s}=@var{sin}(@var{angle},)}, and
18477 @r{∥(@var{x},@var{y}@var{z}),∥=1} (if not, the GL will normalize this
18484 If the matrix mode is either @code{GL_MODELVIEW} or
18485 @code{GL_PROJECTION}, all objects drawn after @code{glRotate} is called
18486 are rotated. Use @code{glPushMatrix} and @code{glPopMatrix} to save and
18487 restore the unrotated coordinate system.
18489 @code{GL_INVALID_OPERATION} is generated if @code{glRotate} is executed
18490 between the execution of @code{glBegin} and the corresponding execution
18495 @deftypefun void glSampleCoverage value invert
18496 Specify multisample coverage parameters.
18500 Specify a single floating-point sample coverage value. The value is
18501 clamped to the range @r{[0,1]}. The initial value is 1.0.
18504 Specify a single boolean value representing if the coverage masks should
18505 be inverted. @code{GL_TRUE} and @code{GL_FALSE} are accepted. The
18506 initial value is @code{GL_FALSE}.
18510 Multisampling samples a pixel multiple times at various
18511 implementation-dependent subpixel locations to generate antialiasing
18512 effects. Multisampling transparently antialiases points, lines,
18513 polygons, bitmaps, and images if it is enabled.
18515 @var{value} is used in constructing a temporary mask used in determining
18516 which samples will be used in resolving the final fragment color. This
18517 mask is bitwise-anded with the coverage mask generated from the
18518 multisampling computation. If the @var{invert} flag is set, the
18519 temporary mask is inverted (all bits flipped) and then the bitwise-and
18522 If an implementation does not have any multisample buffers available, or
18523 multisampling is disabled, rasterization occurs with only a single
18524 sample computing a pixel's final RGB color.
18526 Provided an implementation supports multisample buffers, and
18527 multisampling is enabled, then a pixel's final color is generated by
18528 combining several samples per pixel. Each sample contains color, depth,
18529 and stencil information, allowing those operations to be performed on
18532 @code{GL_INVALID_OPERATION} is generated if @code{glSampleCoverage} is
18533 executed between the execution of @code{glBegin} and the corresponding
18534 execution of @code{glEnd}.
18538 @deftypefun void glScalef x y z
18539 Multiply the current matrix by a general scaling matrix.
18545 Specify scale factors along the @var{x}, @var{y}, and @var{z} axes,
18550 @code{glScale} produces a nonuniform scaling along the @var{x}, @var{y},
18551 and @var{z} axes. The three parameters indicate the desired scale factor
18552 along each of the three axes.
18554 The current matrix (see @code{glMatrixMode}) is multiplied by this scale
18555 matrix, and the product replaces the current matrix as if
18556 @code{glMultMatrix} were called with the following matrix as its
18559 @r{((@var{x} 0 0 0), (0 @var{y} 0 0), (0 0 @var{z} 0), (0 0 0 1),)}
18561 If the matrix mode is either @code{GL_MODELVIEW} or
18562 @code{GL_PROJECTION}, all objects drawn after @code{glScale} is called
18565 Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the
18566 unscaled coordinate system.
18568 @code{GL_INVALID_OPERATION} is generated if @code{glScale} is executed
18569 between the execution of @code{glBegin} and the corresponding execution
18574 @deftypefun void glScissor x y width height
18575 Define the scissor box.
18580 Specify the lower left corner of the scissor box. Initially (0, 0).
18583 @itemx @var{height}
18584 Specify the width and height of the scissor box. When a GL context is
18585 first attached to a window, @var{width} and @var{height} are set to the
18586 dimensions of that window.
18590 @code{glScissor} defines a rectangle, called the scissor box, in window
18591 coordinates. The first two arguments, @var{x} and @var{y}, specify the
18592 lower left corner of the box. @var{width} and @var{height} specify the
18593 width and height of the box.
18595 To enable and disable the scissor test, call @code{glEnable} and
18596 @code{glDisable} with argument @code{GL_SCISSOR_TEST}. The test is
18597 initially disabled. While the test is enabled, only pixels that lie
18598 within the scissor box can be modified by drawing commands. Window
18599 coordinates have integer values at the shared corners of frame buffer
18600 pixels. @code{glScissor(0,0,1,1)} allows modification of only the lower
18601 left pixel in the window, and @code{glScissor(0,0,0,0)} doesn't allow
18602 modification of any pixels in the window.
18604 When the scissor test is disabled, it is as though the scissor box
18605 includes the entire window.
18607 @code{GL_INVALID_VALUE} is generated if either @var{width} or
18608 @var{height} is negative.
18610 @code{GL_INVALID_OPERATION} is generated if @code{glScissor} is executed
18611 between the execution of @code{glBegin} and the corresponding execution
18616 @deftypefun void glSecondaryColorPointer size type stride pointer
18617 Define an array of secondary colors.
18621 Specifies the number of components per color. Must be 3.
18624 Specifies the data type of each color component in the array. Symbolic
18625 constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
18626 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
18627 @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is
18631 Specifies the byte offset between consecutive colors. If @var{stride} is
18632 0, the colors are understood to be tightly packed in the array. The
18633 initial value is 0.
18635 @item @var{pointer}
18636 Specifies a pointer to the first component of the first color element in
18637 the array. The initial value is 0.
18641 @code{glSecondaryColorPointer} specifies the location and data format of
18642 an array of color components to use when rendering. @var{size} specifies
18643 the number of components per color, and must be 3. @var{type} specifies
18644 the data type of each color component, and @var{stride} specifies the
18645 byte stride from one color to the next, allowing vertices and attributes
18646 to be packed into a single array or stored in separate arrays.
18648 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
18649 target (see @code{glBindBuffer}) while a secondary color array is
18650 specified, @var{pointer} is treated as a byte offset into the buffer
18651 object's data store. Also, the buffer object binding
18652 (@code{GL_ARRAY_BUFFER_BINDING}) is saved as secondary color vertex
18653 array client-side state
18654 (@code{GL_SECONDARY_COLOR_ARRAY_BUFFER_BINDING}).
18656 When a secondary color array is specified, @var{size}, @var{type},
18657 @var{stride}, and @var{pointer} are saved as client-side state, in
18658 addition to the current vertex array buffer object binding.
18660 To enable and disable the secondary color array, call
18661 @code{glEnableClientState} and @code{glDisableClientState} with the
18662 argument @code{GL_SECONDARY_COLOR_ARRAY}. If enabled, the secondary
18663 color array is used when @code{glArrayElement}, @code{glDrawArrays},
18664 @code{glMultiDrawArrays}, @code{glDrawElements},
18665 @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called.
18667 @code{GL_INVALID_VALUE} is generated if @var{size} is not 3.
18669 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
18672 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
18676 @deftypefun void glSecondaryColor3i red green blue
18677 @deftypefunx void glSecondaryColor3f red green blue
18678 @deftypefunx void glSecondaryColor3ui red green blue
18679 Set the current secondary color.
18685 Specify new red, green, and blue values for the current secondary color.
18689 The GL stores both a primary four-valued RGBA color and a secondary
18690 four-valued RGBA color (where alpha is always set to 0.0) that is
18691 associated with every vertex.
18693 The secondary color is interpolated and applied to each fragment during
18694 rasterization when @code{GL_COLOR_SUM} is enabled. When lighting is
18695 enabled, and @code{GL_SEPARATE_SPECULAR_COLOR} is specified, the value
18696 of the secondary color is assigned the value computed from the specular
18697 term of the lighting computation. Both the primary and secondary current
18698 colors are applied to each fragment, regardless of the state of
18699 @code{GL_COLOR_SUM}, under such conditions. When
18700 @code{GL_SEPARATE_SPECULAR_COLOR} is specified, the value returned from
18701 querying the current secondary color is undefined.
18703 @code{glSecondaryColor3b}, @code{glSecondaryColor3s}, and
18704 @code{glSecondaryColor3i} take three signed byte, short, or long
18705 integers as arguments. When @strong{v} is appended to the name, the
18706 color commands can take a pointer to an array of such values.
18708 Color values are stored in floating-point format, with unspecified
18709 mantissa and exponent sizes. Unsigned integer color components, when
18710 specified, are linearly mapped to floating-point values such that the
18711 largest representable value maps to 1.0 (full intensity), and 0 maps to
18712 0.0 (zero intensity). Signed integer color components, when specified,
18713 are linearly mapped to floating-point values such that the most positive
18714 representable value maps to 1.0, and the most negative representable
18715 value maps to @r{-1.0}. (Note that this mapping does not convert 0
18716 precisely to 0.0). Floating-point values are mapped directly.
18718 Neither floating-point nor signed integer values are clamped to the
18719 range @r{[0,1]} before the current color is updated. However, color
18720 components are clamped to this range before they are interpolated or
18721 written into a color buffer.
18725 @deftypefun void glSelectBuffer size buffer
18726 Establish a buffer for selection mode values.
18730 Specifies the size of @var{buffer}.
18733 Returns the selection data.
18737 @code{glSelectBuffer} has two arguments: @var{buffer} is a pointer to an
18738 array of unsigned integers, and @var{size} indicates the size of the
18739 array. @var{buffer} returns values from the name stack (see
18740 @code{glInitNames}, @code{glLoadName}, @code{glPushName}) when the
18741 rendering mode is @code{GL_SELECT} (see @code{glRenderMode}).
18742 @code{glSelectBuffer} must be issued before selection mode is enabled,
18743 and it must not be issued while the rendering mode is @code{GL_SELECT}.
18745 A programmer can use selection to determine which primitives are drawn
18746 into some region of a window. The region is defined by the current
18747 modelview and perspective matrices.
18749 In selection mode, no pixel fragments are produced from rasterization.
18750 Instead, if a primitive or a raster position intersects the clipping
18751 volume defined by the viewing frustum and the user-defined clipping
18752 planes, this primitive causes a selection hit. (With polygons, no hit
18753 occurs if the polygon is culled.) When a change is made to the name
18754 stack, or when @code{glRenderMode} is called, a hit record is copied to
18755 @var{buffer} if any hits have occurred since the last such event (name
18756 stack change or @code{glRenderMode} call). The hit record consists of
18757 the number of names in the name stack at the time of the event, followed
18758 by the minimum and maximum depth values of all vertices that hit since
18759 the previous event, followed by the name stack contents, bottom name
18762 Depth values (which are in the range [0,1]) are multiplied by
18763 @r{2^32-1}, before being placed in the hit record.
18765 An internal index into @var{buffer} is reset to 0 whenever selection
18766 mode is entered. Each time a hit record is copied into @var{buffer}, the
18767 index is incremented to point to the cell just past the end of the block
18768 of names\(emthat is, to the next available cell If the hit record is
18769 larger than the number of remaining locations in @var{buffer}, as much
18770 data as can fit is copied, and the overflow flag is set. If the name
18771 stack is empty when a hit record is copied, that record consists of 0
18772 followed by the minimum and maximum depth values.
18774 To exit selection mode, call @code{glRenderMode} with an argument other
18775 than @code{GL_SELECT}. Whenever @code{glRenderMode} is called while the
18776 render mode is @code{GL_SELECT}, it returns the number of hit records
18777 copied to @var{buffer}, resets the overflow flag and the selection
18778 buffer pointer, and initializes the name stack to be empty. If the
18779 overflow bit was set when @code{glRenderMode} was called, a negative hit
18780 record count is returned.
18782 @code{GL_INVALID_VALUE} is generated if @var{size} is negative.
18784 @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is
18785 called while the render mode is @code{GL_SELECT}, or if
18786 @code{glRenderMode} is called with argument @code{GL_SELECT} before
18787 @code{glSelectBuffer} is called at least once.
18789 @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is
18790 executed between the execution of @code{glBegin} and the corresponding
18791 execution of @code{glEnd}.
18795 @deftypefun void glSeparableFilter2D target internalformat width height format type row column
18796 Define a separable two-dimensional convolution filter.
18800 Must be @code{GL_SEPARABLE_2D}.
18802 @item @var{internalformat}
18803 The internal format of the convolution filter kernel. The allowable
18804 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
18805 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
18806 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
18807 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
18808 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
18809 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
18810 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
18811 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
18812 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
18813 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
18814 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
18815 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
18816 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
18819 The number of elements in the pixel array referenced by @var{row}. (This
18820 is the width of the separable filter kernel.)
18823 The number of elements in the pixel array referenced by @var{column}.
18824 (This is the height of the separable filter kernel.)
18827 The format of the pixel data in @var{row} and @var{column}. The
18828 allowable values are @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE},
18829 @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA},
18830 @code{GL_BGRA}, @code{GL_INTENSITY}, @code{GL_LUMINANCE}, and
18831 @code{GL_LUMINANCE_ALPHA}.
18834 The type of the pixel data in @var{row} and @var{column}. Symbolic
18835 constants @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
18836 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
18837 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
18838 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
18839 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
18840 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
18841 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
18842 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
18843 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
18846 Pointer to a one-dimensional array of pixel data that is processed to
18847 build the row filter kernel.
18850 Pointer to a one-dimensional array of pixel data that is processed to
18851 build the column filter kernel.
18855 @code{glSeparableFilter2D} builds a two-dimensional separable
18856 convolution filter kernel from two arrays of pixels.
18858 The pixel arrays specified by (@var{width}, @var{format}, @var{type},
18859 @var{row}) and (@var{height}, @var{format}, @var{type}, @var{column})
18860 are processed just as if they had been passed to @code{glDrawPixels},
18861 but processing stops after the final expansion to RGBA is completed.
18863 If a non-zero named buffer object is bound to the
18864 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
18865 convolution filter is specified, @var{row} and @var{column} are treated
18866 as byte offsets into the buffer object's data store.
18868 Next, the R, G, B, and A components of all pixels in both arrays are
18869 scaled by the four separable 2D @code{GL_CONVOLUTION_FILTER_SCALE}
18870 parameters and biased by the four separable 2D
18871 @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
18872 parameters are set by @code{glConvolutionParameter} using the
18873 @code{GL_SEPARABLE_2D} target and the names
18874 @code{GL_CONVOLUTION_FILTER_SCALE} and
18875 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors
18876 of four values that are applied to red, green, blue, and alpha, in that
18877 order.) The R, G, B, and A values are not clamped to [0,1] at any time
18878 during this process.
18880 Each pixel is then converted to the internal format specified by
18881 @var{internalformat}. This conversion simply maps the component values
18882 of the pixel (R, G, B, and A) to the values included in the internal
18883 format (red, green, blue, alpha, luminance, and intensity). The mapping
18887 @item @strong{Internal Format}
18888 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
18889 @strong{Luminance}, @strong{Intensity}
18891 @item @code{GL_LUMINANCE}
18894 @item @code{GL_LUMINANCE_ALPHA}
18897 @item @code{GL_INTENSITY}
18900 @item @code{GL_RGB}
18903 @item @code{GL_RGBA}
18908 The red, green, blue, alpha, luminance, and/or intensity components of
18909 the resulting pixels are stored in floating-point rather than integer
18910 format. They form two one-dimensional filter kernel images. The row
18911 image is indexed by coordinate @var{i} starting at zero and increasing
18912 from left to right. Each location in the row image is derived from
18913 element @var{i} of @var{row}. The column image is indexed by coordinate
18914 @var{j} starting at zero and increasing from bottom to top. Each
18915 location in the column image is derived from element @var{j} of
18918 Note that after a convolution is performed, the resulting color
18919 components are also scaled by their corresponding
18920 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
18921 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
18922 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
18923 and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}.
18925 @code{GL_INVALID_ENUM} is generated if @var{target} is not
18926 @code{GL_SEPARABLE_2D}.
18928 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
18929 of the allowable values.
18931 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
18934 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
18937 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
18938 greater than the maximum supported value. This value may be queried with
18939 @code{glGetConvolutionParameter} using target @code{GL_SEPARABLE_2D} and
18940 name @code{GL_MAX_CONVOLUTION_WIDTH}.
18942 @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero
18943 or greater than the maximum supported value. This value may be queried
18944 with @code{glGetConvolutionParameter} using target
18945 @code{GL_SEPARABLE_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}.
18947 @code{GL_INVALID_OPERATION} is generated if @var{height} is one of
18948 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
18949 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
18950 and @var{format} is not @code{GL_RGB}.
18952 @code{GL_INVALID_OPERATION} is generated if @var{height} is one of
18953 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
18954 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
18955 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
18956 @code{GL_UNSIGNED_INT_10_10_10_2}, or
18957 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
18958 @code{GL_RGBA} nor @code{GL_BGRA}.
18960 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
18961 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
18962 object's data store is currently mapped.
18964 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
18965 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
18966 would be unpacked from the buffer object such that the memory reads
18967 required would exceed the data store size.
18969 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
18970 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{row}
18971 or @var{column} is not evenly divisible into the number of bytes needed
18972 to store in memory a datum indicated by @var{type}.
18974 @code{GL_INVALID_OPERATION} is generated if @code{glSeparableFilter2D}
18975 is executed between the execution of @code{glBegin} and the
18976 corresponding execution of @code{glEnd}.
18980 @deftypefun void glShadeModel mode
18981 Select flat or smooth shading.
18985 Specifies a symbolic value representing a shading technique. Accepted
18986 values are @code{GL_FLAT} and @code{GL_SMOOTH}. The initial value is
18991 GL primitives can have either flat or smooth shading. Smooth shading,
18992 the default, causes the computed colors of vertices to be interpolated
18993 as the primitive is rasterized, typically assigning different colors to
18994 each resulting pixel fragment. Flat shading selects the computed color
18995 of just one vertex and assigns it to all the pixel fragments generated
18996 by rasterizing a single primitive. In either case, the computed color of
18997 a vertex is the result of lighting if lighting is enabled, or it is the
18998 current color at the time the vertex was specified if lighting is
19001 Flat and smooth shading are indistinguishable for points. Starting when
19002 @code{glBegin} is issued and counting vertices and primitives from 1,
19003 the GL gives each flat-shaded line segment @r{@var{i}} the computed
19004 color of vertex @r{@var{i}+1}, its second vertex. Counting similarly
19005 from 1, the GL gives each flat-shaded polygon the computed color of the
19006 vertex listed in the following table. This is the last vertex to specify
19007 the polygon in all cases except single polygons, where the first vertex
19008 specifies the flat-shaded color.
19014 Primitive Type of Polygon @r{@var{i}}}
19031 Independent triangle
19044 Flat and smooth shading are specified by @code{glShadeModel} with
19045 @var{mode} set to @code{GL_FLAT} and @code{GL_SMOOTH}, respectively.
19047 @code{GL_INVALID_ENUM} is generated if @var{mode} is any value other
19048 than @code{GL_FLAT} or @code{GL_SMOOTH}.
19050 @code{GL_INVALID_OPERATION} is generated if @code{glShadeModel} is
19051 executed between the execution of @code{glBegin} and the corresponding
19052 execution of @code{glEnd}.
19056 @deftypefun void glShaderSource shader count string length
19057 Replaces the source code in a shader object.
19061 Specifies the handle of the shader object whose source code is to be
19065 Specifies the number of elements in the @var{string} and @var{length}
19069 Specifies an array of pointers to strings containing the source code to
19070 be loaded into the shader.
19073 Specifies an array of string lengths.
19077 @code{glShaderSource} sets the source code in @var{shader} to the source
19078 code in the array of strings specified by @var{string}. Any source code
19079 previously stored in the shader object is completely replaced. The
19080 number of strings in the array is specified by @var{count}. If
19081 @var{length} is @code{NULL}, each string is assumed to be null
19082 terminated. If @var{length} is a value other than @code{NULL}, it points
19083 to an array containing a string length for each of the corresponding
19084 elements of @var{string}. Each element in the @var{length} array may
19085 contain the length of the corresponding string (the null character is
19086 not counted as part of the string length) or a value less than 0 to
19087 indicate that the string is null terminated. The source code strings are
19088 not scanned or parsed at this time; they are simply copied into the
19089 specified shader object.
19091 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
19092 generated by OpenGL.
19094 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
19097 @code{GL_INVALID_VALUE} is generated if @var{count} is less than 0.
19099 @code{GL_INVALID_OPERATION} is generated if @code{glShaderSource} is
19100 executed between the execution of @code{glBegin} and the corresponding
19101 execution of @code{glEnd}.
19105 @deftypefun void glStencilFuncSeparate face func ref mask
19106 Set front and/or back function and reference value for stencil testing.
19110 Specifies whether front and/or back stencil state is updated. Three
19111 symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and
19112 @code{GL_FRONT_AND_BACK}.
19115 Specifies the test function. Eight symbolic constants are valid:
19116 @code{GL_NEVER}, @code{GL_LESS}, @code{GL_LEQUAL}, @code{GL_GREATER},
19117 @code{GL_GEQUAL}, @code{GL_EQUAL}, @code{GL_NOTEQUAL}, and
19118 @code{GL_ALWAYS}. The initial value is @code{GL_ALWAYS}.
19121 Specifies the reference value for the stencil test. @var{ref} is clamped
19122 to the range @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of
19123 bitplanes in the stencil buffer. The initial value is 0.
19126 Specifies a mask that is ANDed with both the reference value and the
19127 stored stencil value when the test is done. The initial value is all
19132 Stenciling, like depth-buffering, enables and disables drawing on a
19133 per-pixel basis. You draw into the stencil planes using GL drawing
19134 primitives, then render geometry and images, using the stencil planes to
19135 mask out portions of the screen. Stenciling is typically used in
19136 multipass rendering algorithms to achieve special effects, such as
19137 decals, outlining, and constructive solid geometry rendering.
19139 The stencil test conditionally eliminates a pixel based on the outcome
19140 of a comparison between the reference value and the value in the stencil
19141 buffer. To enable and disable the test, call @code{glEnable} and
19142 @code{glDisable} with argument @code{GL_STENCIL_TEST}. To specify
19143 actions based on the outcome of the stencil test, call
19144 @code{glStencilOp} or @code{glStencilOpSeparate}.
19146 There can be two separate sets of @var{func}, @var{ref}, and @var{mask}
19147 parameters; one affects back-facing polygons, and the other affects
19148 front-facing polygons as well as other non-polygon primitives.
19149 @code{glStencilFunc} sets both front and back stencil state to the same
19150 values, as if @code{glStencilFuncSeparate} were called with @var{face}
19151 set to @code{GL_FRONT_AND_BACK}.
19153 @var{func} is a symbolic constant that determines the stencil comparison
19154 function. It accepts one of eight values, shown in the following list.
19155 @var{ref} is an integer reference value that is used in the stencil
19156 comparison. It is clamped to the range @r{[0,2^@var{n}-1]}, where
19157 @r{@var{n}} is the number of bitplanes in the stencil buffer. @var{mask}
19158 is bitwise ANDed with both the reference value and the stored stencil
19159 value, with the ANDed values participating in the comparison.
19161 If @var{stencil} represents the value stored in the corresponding
19162 stencil buffer location, the following list shows the effect of each
19163 comparison function that can be specified by @var{func}. Only if the
19164 comparison succeeds is the pixel passed through to the next stage in the
19165 rasterization process (see @code{glStencilOp}). All tests treat
19166 @var{stencil} values as unsigned integers in the range
19167 @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of bitplanes in the
19170 The following values are accepted by @var{func}:
19173 @item @code{GL_NEVER}
19176 @item @code{GL_LESS}
19177 Passes if ( @var{ref} & @var{mask} ) < ( @var{stencil} & @var{mask} ).
19179 @item @code{GL_LEQUAL}
19180 Passes if ( @var{ref} & @var{mask} ) <= ( @var{stencil} & @var{mask} ).
19182 @item @code{GL_GREATER}
19183 Passes if ( @var{ref} & @var{mask} ) > ( @var{stencil} & @var{mask} ).
19185 @item @code{GL_GEQUAL}
19186 Passes if ( @var{ref} & @var{mask} ) >= ( @var{stencil} & @var{mask} ).
19188 @item @code{GL_EQUAL}
19189 Passes if ( @var{ref} & @var{mask} ) = ( @var{stencil} & @var{mask} ).
19191 @item @code{GL_NOTEQUAL}
19192 Passes if ( @var{ref} & @var{mask} ) != ( @var{stencil} & @var{mask} ).
19194 @item @code{GL_ALWAYS}
19199 @code{GL_INVALID_ENUM} is generated if @var{func} is not one of the
19200 eight accepted values.
19202 @code{GL_INVALID_OPERATION} is generated if @code{glStencilFuncSeparate}
19203 is executed between the execution of @code{glBegin} and the
19204 corresponding execution of @code{glEnd}.
19208 @deftypefun void glStencilFunc func ref mask
19209 Set front and back function and reference value for stencil testing.
19213 Specifies the test function. Eight symbolic constants are valid:
19214 @code{GL_NEVER}, @code{GL_LESS}, @code{GL_LEQUAL}, @code{GL_GREATER},
19215 @code{GL_GEQUAL}, @code{GL_EQUAL}, @code{GL_NOTEQUAL}, and
19216 @code{GL_ALWAYS}. The initial value is @code{GL_ALWAYS}.
19219 Specifies the reference value for the stencil test. @var{ref} is clamped
19220 to the range @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of
19221 bitplanes in the stencil buffer. The initial value is 0.
19224 Specifies a mask that is ANDed with both the reference value and the
19225 stored stencil value when the test is done. The initial value is all
19230 Stenciling, like depth-buffering, enables and disables drawing on a
19231 per-pixel basis. Stencil planes are first drawn into using GL drawing
19232 primitives, then geometry and images are rendered using the stencil
19233 planes to mask out portions of the screen. Stenciling is typically used
19234 in multipass rendering algorithms to achieve special effects, such as
19235 decals, outlining, and constructive solid geometry rendering.
19237 The stencil test conditionally eliminates a pixel based on the outcome
19238 of a comparison between the reference value and the value in the stencil
19239 buffer. To enable and disable the test, call @code{glEnable} and
19240 @code{glDisable} with argument @code{GL_STENCIL_TEST}. To specify
19241 actions based on the outcome of the stencil test, call
19242 @code{glStencilOp} or @code{glStencilOpSeparate}.
19244 There can be two separate sets of @var{func}, @var{ref}, and @var{mask}
19245 parameters; one affects back-facing polygons, and the other affects
19246 front-facing polygons as well as other non-polygon primitives.
19247 @code{glStencilFunc} sets both front and back stencil state to the same
19248 values. Use @code{glStencilFuncSeparate} to set front and back stencil
19249 state to different values.
19251 @var{func} is a symbolic constant that determines the stencil comparison
19252 function. It accepts one of eight values, shown in the following list.
19253 @var{ref} is an integer reference value that is used in the stencil
19254 comparison. It is clamped to the range @r{[0,2^@var{n}-1]}, where
19255 @r{@var{n}} is the number of bitplanes in the stencil buffer. @var{mask}
19256 is bitwise ANDed with both the reference value and the stored stencil
19257 value, with the ANDed values participating in the comparison.
19259 If @var{stencil} represents the value stored in the corresponding
19260 stencil buffer location, the following list shows the effect of each
19261 comparison function that can be specified by @var{func}. Only if the
19262 comparison succeeds is the pixel passed through to the next stage in the
19263 rasterization process (see @code{glStencilOp}). All tests treat
19264 @var{stencil} values as unsigned integers in the range
19265 @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of bitplanes in the
19268 The following values are accepted by @var{func}:
19271 @item @code{GL_NEVER}
19274 @item @code{GL_LESS}
19275 Passes if ( @var{ref} & @var{mask} ) < ( @var{stencil} & @var{mask} ).
19277 @item @code{GL_LEQUAL}
19278 Passes if ( @var{ref} & @var{mask} ) <= ( @var{stencil} & @var{mask} ).
19280 @item @code{GL_GREATER}
19281 Passes if ( @var{ref} & @var{mask} ) > ( @var{stencil} & @var{mask} ).
19283 @item @code{GL_GEQUAL}
19284 Passes if ( @var{ref} & @var{mask} ) >= ( @var{stencil} & @var{mask} ).
19286 @item @code{GL_EQUAL}
19287 Passes if ( @var{ref} & @var{mask} ) = ( @var{stencil} & @var{mask} ).
19289 @item @code{GL_NOTEQUAL}
19290 Passes if ( @var{ref} & @var{mask} ) != ( @var{stencil} & @var{mask} ).
19292 @item @code{GL_ALWAYS}
19297 @code{GL_INVALID_ENUM} is generated if @var{func} is not one of the
19298 eight accepted values.
19300 @code{GL_INVALID_OPERATION} is generated if @code{glStencilFunc} is
19301 executed between the execution of @code{glBegin} and the corresponding
19302 execution of @code{glEnd}.
19306 @deftypefun void glStencilMaskSeparate face mask
19307 Control the front and/or back writing of individual bits in the stencil
19312 Specifies whether the front and/or back stencil writemask is updated.
19313 Three symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and
19314 @code{GL_FRONT_AND_BACK}.
19317 Specifies a bit mask to enable and disable writing of individual bits in
19318 the stencil planes. Initially, the mask is all 1's.
19322 @code{glStencilMaskSeparate} controls the writing of individual bits in
19323 the stencil planes. The least significant @r{@var{n}} bits of
19324 @var{mask}, where @r{@var{n}} is the number of bits in the stencil
19325 buffer, specify a mask. Where a 1 appears in the mask, it's possible to
19326 write to the corresponding bit in the stencil buffer. Where a 0 appears,
19327 the corresponding bit is write-protected. Initially, all bits are
19328 enabled for writing.
19330 There can be two separate @var{mask} writemasks; one affects back-facing
19331 polygons, and the other affects front-facing polygons as well as other
19332 non-polygon primitives. @code{glStencilMask} sets both front and back
19333 stencil writemasks to the same values, as if
19334 @code{glStencilMaskSeparate} were called with @var{face} set to
19335 @code{GL_FRONT_AND_BACK}.
19337 @code{GL_INVALID_OPERATION} is generated if @code{glStencilMaskSeparate}
19338 is executed between the execution of @code{glBegin} and the
19339 corresponding execution of @code{glEnd}.
19343 @deftypefun void glStencilMask mask
19344 Control the front and back writing of individual bits in the stencil
19349 Specifies a bit mask to enable and disable writing of individual bits in
19350 the stencil planes. Initially, the mask is all 1's.
19354 @code{glStencilMask} controls the writing of individual bits in the
19355 stencil planes. The least significant @r{@var{n}} bits of @var{mask},
19356 where @r{@var{n}} is the number of bits in the stencil buffer, specify a
19357 mask. Where a 1 appears in the mask, it's possible to write to the
19358 corresponding bit in the stencil buffer. Where a 0 appears, the
19359 corresponding bit is write-protected. Initially, all bits are enabled
19362 There can be two separate @var{mask} writemasks; one affects back-facing
19363 polygons, and the other affects front-facing polygons as well as other
19364 non-polygon primitives. @code{glStencilMask} sets both front and back
19365 stencil writemasks to the same values. Use @code{glStencilMaskSeparate}
19366 to set front and back stencil writemasks to different values.
19368 @code{GL_INVALID_OPERATION} is generated if @code{glStencilMask} is
19369 executed between the execution of @code{glBegin} and the corresponding
19370 execution of @code{glEnd}.
19374 @deftypefun void glStencilOpSeparate face sfail dpfail dppass
19375 Set front and/or back stencil test actions.
19379 Specifies whether front and/or back stencil state is updated. Three
19380 symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and
19381 @code{GL_FRONT_AND_BACK}.
19384 Specifies the action to take when the stencil test fails. Eight symbolic
19385 constants are accepted: @code{GL_KEEP}, @code{GL_ZERO},
19386 @code{GL_REPLACE}, @code{GL_INCR}, @code{GL_INCR_WRAP}, @code{GL_DECR},
19387 @code{GL_DECR_WRAP}, and @code{GL_INVERT}. The initial value is
19391 Specifies the stencil action when the stencil test passes, but the depth
19392 test fails. @var{dpfail} accepts the same symbolic constants as
19393 @var{sfail}. The initial value is @code{GL_KEEP}.
19396 Specifies the stencil action when both the stencil test and the depth
19397 test pass, or when the stencil test passes and either there is no depth
19398 buffer or depth testing is not enabled. @var{dppass} accepts the same
19399 symbolic constants as @var{sfail}. The initial value is @code{GL_KEEP}.
19403 Stenciling, like depth-buffering, enables and disables drawing on a
19404 per-pixel basis. You draw into the stencil planes using GL drawing
19405 primitives, then render geometry and images, using the stencil planes to
19406 mask out portions of the screen. Stenciling is typically used in
19407 multipass rendering algorithms to achieve special effects, such as
19408 decals, outlining, and constructive solid geometry rendering.
19410 The stencil test conditionally eliminates a pixel based on the outcome
19411 of a comparison between the value in the stencil buffer and a reference
19412 value. To enable and disable the test, call @code{glEnable} and
19413 @code{glDisable} with argument @code{GL_STENCIL_TEST}; to control it,
19414 call @code{glStencilFunc} or @code{glStencilFuncSeparate}.
19416 There can be two separate sets of @var{sfail}, @var{dpfail}, and
19417 @var{dppass} parameters; one affects back-facing polygons, and the other
19418 affects front-facing polygons as well as other non-polygon primitives.
19419 @code{glStencilOp} sets both front and back stencil state to the same
19420 values, as if @code{glStencilOpSeparate} were called with @var{face} set
19421 to @code{GL_FRONT_AND_BACK}.
19423 @code{glStencilOpSeparate} takes three arguments that indicate what
19424 happens to the stored stencil value while stenciling is enabled. If the
19425 stencil test fails, no change is made to the pixel's color or depth
19426 buffers, and @var{sfail} specifies what happens to the stencil buffer
19427 contents. The following eight actions are possible.
19430 @item @code{GL_KEEP}
19431 Keeps the current value.
19433 @item @code{GL_ZERO}
19434 Sets the stencil buffer value to 0.
19436 @item @code{GL_REPLACE}
19437 Sets the stencil buffer value to @var{ref}, as specified by
19438 @code{glStencilFunc}.
19440 @item @code{GL_INCR}
19441 Increments the current stencil buffer value. Clamps to the maximum
19442 representable unsigned value.
19444 @item @code{GL_INCR_WRAP}
19445 Increments the current stencil buffer value. Wraps stencil buffer value
19446 to zero when incrementing the maximum representable unsigned value.
19448 @item @code{GL_DECR}
19449 Decrements the current stencil buffer value. Clamps to 0.
19451 @item @code{GL_DECR_WRAP}
19452 Decrements the current stencil buffer value. Wraps stencil buffer value
19453 to the maximum representable unsigned value when decrementing a stencil
19454 buffer value of zero.
19456 @item @code{GL_INVERT}
19457 Bitwise inverts the current stencil buffer value.
19461 Stencil buffer values are treated as unsigned integers. When incremented
19462 and decremented, values are clamped to 0 and @r{2^@var{n}-1}, where
19463 @r{@var{n}} is the value returned by querying @code{GL_STENCIL_BITS}.
19465 The other two arguments to @code{glStencilOpSeparate} specify stencil
19466 buffer actions that depend on whether subsequent depth buffer tests
19467 succeed (@var{dppass}) or fail (@var{dpfail}) (see @code{glDepthFunc}).
19468 The actions are specified using the same eight symbolic constants as
19469 @var{sfail}. Note that @var{dpfail} is ignored when there is no depth
19470 buffer, or when the depth buffer is not enabled. In these cases,
19471 @var{sfail} and @var{dppass} specify stencil action when the stencil
19472 test fails and passes, respectively.
19474 @code{GL_INVALID_ENUM} is generated if @var{face} is any value other
19475 than @code{GL_FRONT}, @code{GL_BACK}, or @code{GL_FRONT_AND_BACK}.
19477 @code{GL_INVALID_ENUM} is generated if @var{sfail}, @var{dpfail}, or
19478 @var{dppass} is any value other than the eight defined constant values.
19480 @code{GL_INVALID_OPERATION} is generated if @code{glStencilOpSeparate}
19481 is executed between the execution of @code{glBegin} and the
19482 corresponding execution of @code{glEnd}.
19486 @deftypefun void glStencilOp sfail dpfail dppass
19487 Set front and back stencil test actions.
19491 Specifies the action to take when the stencil test fails. Eight symbolic
19492 constants are accepted: @code{GL_KEEP}, @code{GL_ZERO},
19493 @code{GL_REPLACE}, @code{GL_INCR}, @code{GL_INCR_WRAP}, @code{GL_DECR},
19494 @code{GL_DECR_WRAP}, and @code{GL_INVERT}. The initial value is
19498 Specifies the stencil action when the stencil test passes, but the depth
19499 test fails. @var{dpfail} accepts the same symbolic constants as
19500 @var{sfail}. The initial value is @code{GL_KEEP}.
19503 Specifies the stencil action when both the stencil test and the depth
19504 test pass, or when the stencil test passes and either there is no depth
19505 buffer or depth testing is not enabled. @var{dppass} accepts the same
19506 symbolic constants as @var{sfail}. The initial value is @code{GL_KEEP}.
19510 Stenciling, like depth-buffering, enables and disables drawing on a
19511 per-pixel basis. You draw into the stencil planes using GL drawing
19512 primitives, then render geometry and images, using the stencil planes to
19513 mask out portions of the screen. Stenciling is typically used in
19514 multipass rendering algorithms to achieve special effects, such as
19515 decals, outlining, and constructive solid geometry rendering.
19517 The stencil test conditionally eliminates a pixel based on the outcome
19518 of a comparison between the value in the stencil buffer and a reference
19519 value. To enable and disable the test, call @code{glEnable} and
19520 @code{glDisable} with argument @code{GL_STENCIL_TEST}; to control it,
19521 call @code{glStencilFunc} or @code{glStencilFuncSeparate}.
19523 There can be two separate sets of @var{sfail}, @var{dpfail}, and
19524 @var{dppass} parameters; one affects back-facing polygons, and the other
19525 affects front-facing polygons as well as other non-polygon primitives.
19526 @code{glStencilOp} sets both front and back stencil state to the same
19527 values. Use @code{glStencilOpSeparate} to set front and back stencil
19528 state to different values.
19530 @code{glStencilOp} takes three arguments that indicate what happens to
19531 the stored stencil value while stenciling is enabled. If the stencil
19532 test fails, no change is made to the pixel's color or depth buffers, and
19533 @var{sfail} specifies what happens to the stencil buffer contents. The
19534 following eight actions are possible.
19537 @item @code{GL_KEEP}
19538 Keeps the current value.
19540 @item @code{GL_ZERO}
19541 Sets the stencil buffer value to 0.
19543 @item @code{GL_REPLACE}
19544 Sets the stencil buffer value to @var{ref}, as specified by
19545 @code{glStencilFunc}.
19547 @item @code{GL_INCR}
19548 Increments the current stencil buffer value. Clamps to the maximum
19549 representable unsigned value.
19551 @item @code{GL_INCR_WRAP}
19552 Increments the current stencil buffer value. Wraps stencil buffer value
19553 to zero when incrementing the maximum representable unsigned value.
19555 @item @code{GL_DECR}
19556 Decrements the current stencil buffer value. Clamps to 0.
19558 @item @code{GL_DECR_WRAP}
19559 Decrements the current stencil buffer value. Wraps stencil buffer value
19560 to the maximum representable unsigned value when decrementing a stencil
19561 buffer value of zero.
19563 @item @code{GL_INVERT}
19564 Bitwise inverts the current stencil buffer value.
19568 Stencil buffer values are treated as unsigned integers. When incremented
19569 and decremented, values are clamped to 0 and @r{2^@var{n}-1}, where
19570 @r{@var{n}} is the value returned by querying @code{GL_STENCIL_BITS}.
19572 The other two arguments to @code{glStencilOp} specify stencil buffer
19573 actions that depend on whether subsequent depth buffer tests succeed
19574 (@var{dppass}) or fail (@var{dpfail}) (see @code{glDepthFunc}). The
19575 actions are specified using the same eight symbolic constants as
19576 @var{sfail}. Note that @var{dpfail} is ignored when there is no depth
19577 buffer, or when the depth buffer is not enabled. In these cases,
19578 @var{sfail} and @var{dppass} specify stencil action when the stencil
19579 test fails and passes, respectively.
19581 @code{GL_INVALID_ENUM} is generated if @var{sfail}, @var{dpfail}, or
19582 @var{dppass} is any value other than the eight defined constant values.
19584 @code{GL_INVALID_OPERATION} is generated if @code{glStencilOp} is
19585 executed between the execution of @code{glBegin} and the corresponding
19586 execution of @code{glEnd}.
19590 @deftypefun void glTexCoordPointer size type stride pointer
19591 Define an array of texture coordinates.
19595 Specifies the number of coordinates per array element. Must be 1, 2, 3,
19596 or 4. The initial value is 4.
19599 Specifies the data type of each texture coordinate. Symbolic constants
19600 @code{GL_SHORT}, @code{GL_INT}, @code{GL_FLOAT}, or @code{GL_DOUBLE} are
19601 accepted. The initial value is @code{GL_FLOAT}.
19604 Specifies the byte offset between consecutive texture coordinate sets.
19605 If @var{stride} is 0, the array elements are understood to be tightly
19606 packed. The initial value is 0.
19608 @item @var{pointer}
19609 Specifies a pointer to the first coordinate of the first texture
19610 coordinate set in the array. The initial value is 0.
19614 @code{glTexCoordPointer} specifies the location and data format of an
19615 array of texture coordinates to use when rendering. @var{size} specifies
19616 the number of coordinates per texture coordinate set, and must be 1, 2,
19617 3, or 4. @var{type} specifies the data type of each texture coordinate,
19618 and @var{stride} specifies the byte stride from one texture coordinate
19619 set to the next, allowing vertices and attributes to be packed into a
19620 single array or stored in separate arrays. (Single-array storage may be
19621 more efficient on some implementations; see @code{glInterleavedArrays}.)
19623 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
19624 target (see @code{glBindBuffer}) while a texture coordinate array is
19625 specified, @var{pointer} is treated as a byte offset into the buffer
19626 object's data store. Also, the buffer object binding
19627 (@code{GL_ARRAY_BUFFER_BINDING}) is saved as texture coordinate vertex
19628 array client-side state (@code{GL_TEXTURE_COORD_ARRAY_BUFFER_BINDING}).
19630 When a texture coordinate array is specified, @var{size}, @var{type},
19631 @var{stride}, and @var{pointer} are saved as client-side state, in
19632 addition to the current vertex array buffer object binding.
19634 To enable and disable a texture coordinate array, call
19635 @code{glEnableClientState} and @code{glDisableClientState} with the
19636 argument @code{GL_TEXTURE_COORD_ARRAY}. If enabled, the texture
19637 coordinate array is used when @code{glArrayElement},
19638 @code{glDrawArrays}, @code{glMultiDrawArrays}, @code{glDrawElements},
19639 @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called.
19641 @code{GL_INVALID_VALUE} is generated if @var{size} is not 1, 2, 3, or 4.
19643 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
19646 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
19650 @deftypefun void glTexCoord1i s
19651 @deftypefunx void glTexCoord1f s
19652 @deftypefunx void glTexCoord2i s t
19653 @deftypefunx void glTexCoord2f s t
19654 @deftypefunx void glTexCoord3i s t r
19655 @deftypefunx void glTexCoord3f s t r
19656 @deftypefunx void glTexCoord4i s t r q
19657 @deftypefunx void glTexCoord4f s t r q
19658 Set the current texture coordinates.
19665 Specify @var{s}, @var{t}, @var{r}, and @var{q} texture coordinates. Not
19666 all parameters are present in all forms of the command.
19670 @code{glTexCoord} specifies texture coordinates in one, two, three, or
19671 four dimensions. @code{glTexCoord1} sets the current texture coordinates
19672 to @r{(@var{s},001)}; a call to @code{glTexCoord2} sets them to
19673 @r{(@var{s},@var{t}01)}. Similarly, @code{glTexCoord3} specifies the
19674 texture coordinates as @r{(@var{s},@var{t}@var{r}1)}, and
19675 @code{glTexCoord4} defines all four components explicitly as
19676 @r{(@var{s},@var{t}@var{r}@var{q})}.
19678 The current texture coordinates are part of the data that is associated
19679 with each vertex and with the current raster position. Initially, the
19680 values for @var{s}, @var{t}, @var{r}, and @var{q} are (0, 0, 0, 1).
19686 @deftypefun void glTexEnvf target pname param
19687 @deftypefunx void glTexEnvi target pname param
19688 Set texture environment parameters.
19692 Specifies a texture environment. May be @code{GL_TEXTURE_ENV},
19693 @code{GL_TEXTURE_FILTER_CONTROL} or @code{GL_POINT_SPRITE}.
19696 Specifies the symbolic name of a single-valued texture environment
19697 parameter. May be either @code{GL_TEXTURE_ENV_MODE},
19698 @code{GL_TEXTURE_LOD_BIAS}, @code{GL_COMBINE_RGB},
19699 @code{GL_COMBINE_ALPHA}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB},
19700 @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA},
19701 @code{GL_SRC2_ALPHA}, @code{GL_OPERAND0_RGB}, @code{GL_OPERAND1_RGB},
19702 @code{GL_OPERAND2_RGB}, @code{GL_OPERAND0_ALPHA},
19703 @code{GL_OPERAND1_ALPHA}, @code{GL_OPERAND2_ALPHA}, @code{GL_RGB_SCALE},
19704 @code{GL_ALPHA_SCALE}, or @code{GL_COORD_REPLACE}.
19707 Specifies a single symbolic constant, one of @code{GL_ADD},
19708 @code{GL_ADD_SIGNED}, @code{GL_INTERPOLATE}, @code{GL_MODULATE},
19709 @code{GL_DECAL}, @code{GL_BLEND}, @code{GL_REPLACE}, @code{GL_SUBTRACT},
19710 @code{GL_COMBINE}, @code{GL_TEXTURE}, @code{GL_CONSTANT},
19711 @code{GL_PRIMARY_COLOR}, @code{GL_PREVIOUS}, @code{GL_SRC_COLOR},
19712 @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_SRC_ALPHA},
19713 @code{GL_ONE_MINUS_SRC_ALPHA}, a single boolean value for the point
19714 sprite texture coordinate replacement, a single floating-point value for
19715 the texture level-of-detail bias, or 1.0, 2.0, or 4.0 when specifying
19716 the @code{GL_RGB_SCALE} or @code{GL_ALPHA_SCALE}.
19720 A texture environment specifies how texture values are interpreted when
19721 a fragment is textured. When @var{target} is
19722 @code{GL_TEXTURE_FILTER_CONTROL}, @var{pname} must be
19723 @code{GL_TEXTURE_LOD_BIAS}. When @var{target} is @code{GL_TEXTURE_ENV},
19724 @var{pname} can be @code{GL_TEXTURE_ENV_MODE},
19725 @code{GL_TEXTURE_ENV_COLOR}, @code{GL_COMBINE_RGB},
19726 @code{GL_COMBINE_ALPHA}, @code{GL_RGB_SCALE}, @code{GL_ALPHA_SCALE},
19727 @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, @code{GL_SRC2_RGB},
19728 @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, or @code{GL_SRC2_ALPHA}.
19730 If @var{pname} is @code{GL_TEXTURE_ENV_MODE}, then @var{params} is (or
19731 points to) the symbolic name of a texture function. Six texture
19732 functions may be specified: @code{GL_ADD}, @code{GL_MODULATE},
19733 @code{GL_DECAL}, @code{GL_BLEND}, @code{GL_REPLACE}, or
19736 The following table shows the correspondence of filtered texture values
19737 @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}},
19738 @r{@var{A}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{I}_@var{t}} to texture
19739 source components. @r{@var{C}_@var{s}} and @r{@var{A}_@var{s}} are used
19740 by the texture functions described below.
19746 Texture Base Internal Format
19747 @r{@code{C}_@var{s}}, @r{@code{A}_@var{s}}
19749 @item @code{GL_ALPHA}
19750 (0, 0, 0) , @r{@var{A}_@var{t}}
19752 @item @code{GL_LUMINANCE}
19753 ( @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}} ) , 1
19755 @item @code{GL_LUMINANCE_ALPHA}
19756 ( @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}} ) ,
19757 @r{@var{A}_@var{t}}
19759 @item @code{GL_INTENSITY}
19760 ( @r{@var{I}_@var{t}}, @r{@var{I}_@var{t}}, @r{@var{I}_@var{t}} ) ,
19761 @r{@var{I}_@var{t}}
19763 @item @code{GL_RGB}
19764 ( @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}} ) , 1
19766 @item @code{GL_RGBA}
19767 ( @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}} ) ,
19768 @r{@var{A}_@var{t}}
19772 A texture function acts on the fragment to be textured using the texture
19773 image value that applies to the fragment (see @code{glTexParameter}) and
19774 produces an RGBA color for that fragment. The following table shows how
19775 the RGBA color is produced for each of the first five texture functions
19776 that can be chosen. @r{@var{C}} is a triple of color values (RGB) and
19777 @r{@var{A}} is the associated alpha value. RGBA values extracted from a
19778 texture image are in the range [0,1]. The subscript @r{@var{p}} refers
19779 to the color computed from the previous texture stage (or the incoming
19780 fragment if processing texture stage 0), the subscript @r{@var{s}} to
19781 the texture source color, the subscript @r{@var{c}} to the texture
19782 environment color, and the subscript @r{@var{v}} indicates a value
19783 produced by the texture function.
19789 Texture Base Internal Format
19790 @code{Value}, @code{GL_REPLACE} Function , @code{GL_MODULATE} Function ,
19791 @code{GL_DECAL} Function , @code{GL_BLEND} Function , @code{GL_ADD}
19794 @item @code{GL_ALPHA}
19795 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{p}}, @r{@var{C}_@var{p}},
19796 undefined , @r{@var{C}_@var{p}}, @r{@var{C}_@var{p}}
19799 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}},
19800 @r{@var{A}_@var{p}@var{A}_@var{s}}, ,
19801 @r{@var{A}_@var{v}=@var{A}_@var{p}@var{A}_@var{s}},
19802 @r{@var{A}_@var{p}@var{A}_@var{s}}
19804 @item @code{GL_LUMINANCE}
19805 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
19806 @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined ,
19807 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
19808 @r{@var{C}_@var{p}+@var{C}_@var{s}}
19812 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, ,
19813 @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}
19815 @item @code{GL_LUMINANCE_ALPHA}
19816 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
19817 @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined ,
19818 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
19819 @r{@var{C}_@var{p}+@var{C}_@var{s}}
19823 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}},
19824 @r{@var{A}_@var{p}@var{A}_@var{s}}, ,
19825 @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}@var{A}_@var{s}}
19827 @item @code{GL_INTENSITY}
19828 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
19829 @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined ,
19830 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
19831 @r{@var{C}_@var{p}+@var{C}_@var{s}}
19834 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}},
19835 @r{@var{A}_@var{p}@var{A}_@var{s}}, ,
19836 @r{@var{A}_@var{p}(1-@var{A}_@var{s},)+@var{A}_@var{c}@var{A}_@var{s}},
19837 @r{@var{A}_@var{p}+@var{A}_@var{s}}
19839 @item @code{GL_RGB}
19840 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
19841 @r{@var{C}_@var{p}@var{C}_@var{s}}, @r{@var{C}_@var{s}},
19842 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
19843 @r{@var{C}_@var{p}+@var{C}_@var{s}}
19847 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}},
19848 @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}
19850 @item @code{GL_RGBA}
19851 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
19852 @r{@var{C}_@var{p}@var{C}_@var{s}},
19853 @r{@var{C}_@var{p}(1-@var{A}_@var{s},)+@var{C}_@var{s}@var{A}_@var{s}},
19854 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
19855 @r{@var{C}_@var{p}+@var{C}_@var{s}}
19859 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}},
19860 @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}},
19861 @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}@var{A}_@var{s}}
19865 If @var{pname} is @code{GL_TEXTURE_ENV_MODE}, and @var{params} is
19866 @code{GL_COMBINE}, the form of the texture function depends on the
19867 values of @code{GL_COMBINE_RGB} and @code{GL_COMBINE_ALPHA}.
19869 The following describes how the texture sources, as specified by
19870 @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, @code{GL_SRC2_RGB},
19871 @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, and @code{GL_SRC2_ALPHA},
19872 are combined to produce a final texture color. In the following tables,
19873 @code{GL_SRC0_c} is represented by @r{@var{Arg0}}, @code{GL_SRC1_c} is
19874 represented by @r{@var{Arg1}}, and @code{GL_SRC2_c} is represented by
19877 @code{GL_COMBINE_RGB} accepts any of @code{GL_REPLACE},
19878 @code{GL_MODULATE}, @code{GL_ADD}, @code{GL_ADD_SIGNED},
19879 @code{GL_INTERPOLATE}, @code{GL_SUBTRACT}, @code{GL_DOT3_RGB}, or
19880 @code{GL_DOT3_RGBA}.
19885 @item @strong{@code{GL_COMBINE_RGB}}
19886 @strong{Texture Function}
19888 @item @code{GL_REPLACE}
19891 @item @code{GL_MODULATE}
19892 @r{@var{Arg0}×@var{Arg1}}
19894 @item @code{GL_ADD}
19895 @r{@var{Arg0}+@var{Arg1}}
19897 @item @code{GL_ADD_SIGNED}
19898 @r{@var{Arg0}+@var{Arg1}-0.5}
19900 @item @code{GL_INTERPOLATE}
19901 @r{@var{Arg0}×@var{Arg2}+@var{Arg1}×(1-@var{Arg2},)}
19903 @item @code{GL_SUBTRACT}
19904 @r{@var{Arg0}-@var{Arg1}}
19906 @item @code{GL_DOT3_RGB}
19907 or @code{GL_DOT3_RGBA}
19908 @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,),),)}
19912 The scalar results for @code{GL_DOT3_RGB} and @code{GL_DOT3_RGBA} are
19913 placed into each of the 3 (RGB) or 4 (RGBA) components on output.
19915 Likewise, @code{GL_COMBINE_ALPHA} accepts any of @code{GL_REPLACE},
19916 @code{GL_MODULATE}, @code{GL_ADD}, @code{GL_ADD_SIGNED},
19917 @code{GL_INTERPOLATE}, or @code{GL_SUBTRACT}. The following table
19918 describes how alpha values are combined:
19923 @item @strong{@code{GL_COMBINE_ALPHA}}
19924 @strong{Texture Function}
19926 @item @code{GL_REPLACE}
19929 @item @code{GL_MODULATE}
19930 @r{@var{Arg0}×@var{Arg1}}
19932 @item @code{GL_ADD}
19933 @r{@var{Arg0}+@var{Arg1}}
19935 @item @code{GL_ADD_SIGNED}
19936 @r{@var{Arg0}+@var{Arg1}-0.5}
19938 @item @code{GL_INTERPOLATE}
19939 @r{@var{Arg0}×@var{Arg2}+@var{Arg1}×(1-@var{Arg2},)}
19941 @item @code{GL_SUBTRACT}
19942 @r{@var{Arg0}-@var{Arg1}}
19946 In the following tables, the value @r{@var{C}_@var{s}} represents the
19947 color sampled from the currently bound texture, @r{@var{C}_@var{c}}
19948 represents the constant texture-environment color, @r{@var{C}_@var{f}}
19949 represents the primary color of the incoming fragment, and
19950 @r{@var{C}_@var{p}} represents the color computed from the previous
19951 texture stage or @r{@var{C}_@var{f}} if processing texture stage 0.
19952 Likewise, @r{@var{A}_@var{s}}, @r{@var{A}_@var{c}}, @r{@var{A}_@var{f}},
19953 and @r{@var{A}_@var{p}} represent the respective alpha values.
19955 The following table describes the values assigned to @r{@var{Arg0}},
19956 @r{@var{Arg1}}, and @r{@var{Arg2}} based upon the RGB sources and
19962 @item @strong{@code{GL_SRCn_RGB}}
19963 @strong{@code{GL_OPERANDn_RGB}}, @strong{Argument Value}
19965 @item @code{GL_TEXTURE}
19966 @code{GL_SRC_COLOR}, @r{@var{C}_@var{s},}
19969 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{s},}
19972 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},}
19975 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},}
19977 @item @code{GL_TEXTUREn}
19978 @code{GL_SRC_COLOR}, @r{@var{C}_@var{s},}
19981 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{s},}
19984 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},}
19987 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},}
19989 @item @code{GL_CONSTANT}
19990 @code{GL_SRC_COLOR}, @r{@var{C}_@var{c},}
19993 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{c},}
19996 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{c},}
19999 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{c},}
20001 @item @code{GL_PRIMARY_COLOR}
20002 @code{GL_SRC_COLOR}, @r{@var{C}_@var{f},}
20005 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{f},}
20008 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{f},}
20011 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{f},}
20013 @item @code{GL_PREVIOUS}
20014 @code{GL_SRC_COLOR}, @r{@var{C}_@var{p},}
20017 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{p},}
20020 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{p},}
20023 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{p},}
20027 For @code{GL_TEXTUREn} sources, @r{@var{C}_@var{s}} and
20028 @r{@var{A}_@var{s}} represent the color and alpha, respectively,
20029 produced from texture stage @r{@var{n}}.
20031 The follow table describes the values assigned to @r{@var{Arg0}},
20032 @r{@var{Arg1}}, and @r{@var{Arg2}} based upon the alpha sources and
20038 @item @strong{@code{GL_SRCn_ALPHA}}
20039 @strong{@code{GL_OPERANDn_ALPHA}}, @strong{Argument Value}
20041 @item @code{GL_TEXTURE}
20042 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},}
20045 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},}
20047 @item @code{GL_TEXTUREn}
20048 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},}
20051 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},}
20053 @item @code{GL_CONSTANT}
20054 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{c},}
20057 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{c},}
20059 @item @code{GL_PRIMARY_COLOR}
20060 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{f},}
20063 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{f},}
20065 @item @code{GL_PREVIOUS}
20066 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{p},}
20069 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{p},}
20073 The RGB and alpha results of the texture function are multipled by the
20074 values of @code{GL_RGB_SCALE} and @code{GL_ALPHA_SCALE}, respectively,
20075 and clamped to the range @r{[0,1]}.
20077 If @var{pname} is @code{GL_TEXTURE_ENV_COLOR}, @var{params} is a pointer
20078 to an array that holds an RGBA color consisting of four values. Integer
20079 color components are interpreted linearly such that the most positive
20080 integer maps to 1.0, and the most negative integer maps to -1.0. The
20081 values are clamped to the range [0,1] when they are specified.
20082 @r{@var{C}_@var{c}} takes these four values.
20084 If @var{pname} is @code{GL_TEXTURE_LOD_BIAS}, the value specified is
20085 added to the texture level-of-detail parameter, that selects which
20086 mipmap, or mipmaps depending upon the selected
20087 @code{GL_TEXTURE_MIN_FILTER}, will be sampled.
20089 @code{GL_TEXTURE_ENV_MODE} defaults to @code{GL_MODULATE} and
20090 @code{GL_TEXTURE_ENV_COLOR} defaults to (0, 0, 0, 0).
20092 If @var{target} is @code{GL_POINT_SPRITE} and @var{pname} is
20093 @code{GL_COORD_REPLACE}, the boolean value specified is used to either
20094 enable or disable point sprite texture coordinate replacement. The
20095 default value is @code{GL_FALSE}.
20097 @code{GL_INVALID_ENUM} is generated when @var{target} or @var{pname} is
20098 not one of the accepted defined values, or when @var{params} should have
20099 a defined constant value (based on the value of @var{pname}) and does
20102 @code{GL_INVALID_VALUE} is generated if the @var{params} value for
20103 @code{GL_RGB_SCALE} or @code{GL_ALPHA_SCALE} are not one of 1.0, 2.0, or
20106 @code{GL_INVALID_OPERATION} is generated if @code{glTexEnv} is executed
20107 between the execution of @code{glBegin} and the corresponding execution
20112 @deftypefun void glTexGeni coord pname param
20113 @deftypefunx void glTexGenf coord pname param
20114 Control the generation of texture coordinates.
20118 Specifies a texture coordinate. Must be one of @code{GL_S}, @code{GL_T},
20119 @code{GL_R}, or @code{GL_Q}.
20122 Specifies the symbolic name of the texture-coordinate generation
20123 function. Must be @code{GL_TEXTURE_GEN_MODE}.
20126 Specifies a single-valued texture generation parameter, one of
20127 @code{GL_OBJECT_LINEAR}, @code{GL_EYE_LINEAR}, @code{GL_SPHERE_MAP},
20128 @code{GL_NORMAL_MAP}, or @code{GL_REFLECTION_MAP}.
20132 @code{glTexGen} selects a texture-coordinate generation function or
20133 supplies coefficients for one of the functions. @var{coord} names one of
20134 the (@var{s}, @var{t}, @var{r}, @var{q}) texture coordinates; it must be
20135 one of the symbols @code{GL_S}, @code{GL_T}, @code{GL_R}, or
20136 @code{GL_Q}. @var{pname} must be one of three symbolic constants:
20137 @code{GL_TEXTURE_GEN_MODE}, @code{GL_OBJECT_PLANE}, or
20138 @code{GL_EYE_PLANE}. If @var{pname} is @code{GL_TEXTURE_GEN_MODE}, then
20139 @var{params} chooses a mode, one of @code{GL_OBJECT_LINEAR},
20140 @code{GL_EYE_LINEAR}, @code{GL_SPHERE_MAP}, @code{GL_NORMAL_MAP}, or
20141 @code{GL_REFLECTION_MAP}. If @var{pname} is either
20142 @code{GL_OBJECT_PLANE} or @code{GL_EYE_PLANE}, @var{params} contains
20143 coefficients for the corresponding texture generation function.
20145 If the texture generation function is @code{GL_OBJECT_LINEAR}, the
20148 @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}}
20150 is used, where @r{@var{g}} is the value computed for the coordinate
20151 named in @var{coord}, @r{@var{p}_1}, @r{@var{p}_2}, @r{@var{p}_3}, and
20152 @r{@var{p}_4} are the four values supplied in @var{params}, and
20153 @r{@var{x}_@var{o}}, @r{@var{y}_@var{o}}, @r{@var{z}_@var{o}}, and
20154 @r{@var{w}_@var{o}} are the object coordinates of the vertex. This
20155 function can be used, for example, to texture-map terrain using sea
20156 level as a reference plane (defined by @r{@var{p}_1}, @r{@var{p}_2},
20157 @r{@var{p}_3}, and @r{@var{p}_4}). The altitude of a terrain vertex is
20158 computed by the @code{GL_OBJECT_LINEAR} coordinate generation function
20159 as its distance from sea level; that altitude can then be used to index
20160 the texture image to map white snow onto peaks and green grass onto
20163 If the texture generation function is @code{GL_EYE_LINEAR}, the function
20165 @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}}
20169 @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}
20171 and @r{@var{x}_@var{e}}, @r{@var{y}_@var{e}}, @r{@var{z}_@var{e}}, and
20172 @r{@var{w}_@var{e}} are the eye coordinates of the vertex,
20173 @r{@var{p}_1}, @r{@var{p}_2}, @r{@var{p}_3}, and @r{@var{p}_4} are the
20174 values supplied in @var{params}, and @r{@var{M}} is the modelview matrix
20175 when @code{glTexGen} is invoked. If @r{@var{M}} is poorly conditioned or
20176 singular, texture coordinates generated by the resulting function may be
20177 inaccurate or undefined.
20179 Note that the values in @var{params} define a reference plane in eye
20180 coordinates. The modelview matrix that is applied to them may not be the
20181 same one in effect when the polygon vertices are transformed. This
20182 function establishes a field of texture coordinates that can produce
20183 dynamic contour lines on moving objects.
20185 If the texture generation function is @code{GL_SPHERE_MAP} and
20186 @var{coord} is either @code{GL_S} or @code{GL_T}, @r{@var{s}} and
20187 @r{@var{t}} texture coordinates are generated as follows. Let @var{u} be
20188 the unit vector pointing from the origin to the polygon vertex (in eye
20189 coordinates). Let @var{n} sup prime be the current normal, after
20190 transformation to eye coordinates. Let
20192 @r{@var{f}=(@var{f}_@var{x}@var{f}_@var{y}@var{f}_@var{z},)^@var{T}}
20193 be the reflection vector such that
20195 @r{@var{f}=@var{u}-2@var{n}^″@var{n}^″,^@var{T}@var{u}}
20198 @r{@var{m}=2√(@var{f}_@var{x},^2+@var{f}_@var{y},^2+(@var{f}_@var{z}+1,)^2,)}.
20199 Then the values assigned to the @r{@var{s}} and @r{@var{t}} texture
20202 @r{@var{s}=@var{f}_@var{x}/@var{m}+1/2}
20204 @r{@var{t}=@var{f}_@var{y}/@var{m}+1/2}
20206 To enable or disable a texture-coordinate generation function, call
20207 @code{glEnable} or @code{glDisable} with one of the symbolic
20208 texture-coordinate names (@code{GL_TEXTURE_GEN_S},
20209 @code{GL_TEXTURE_GEN_T}, @code{GL_TEXTURE_GEN_R}, or
20210 @code{GL_TEXTURE_GEN_Q}) as the argument. When enabled, the specified
20211 texture coordinate is computed according to the generating function
20212 associated with that coordinate. When disabled, subsequent vertices take
20213 the specified texture coordinate from the current set of texture
20214 coordinates. Initially, all texture generation functions are set to
20215 @code{GL_EYE_LINEAR} and are disabled. Both @r{@var{s}} plane equations
20216 are (1, 0, 0, 0), both @r{@var{t}} plane equations are (0, 1, 0, 0), and
20217 all @r{@var{r}} and @r{@var{q}} plane equations are (0, 0, 0, 0).
20219 When the @code{ARB_multitexture} extension is supported, @code{glTexGen}
20220 sets the texture generation parameters for the currently active texture
20221 unit, selected with @code{glActiveTexture}.
20223 @code{GL_INVALID_ENUM} is generated when @var{coord} or @var{pname} is
20224 not an accepted defined value, or when @var{pname} is
20225 @code{GL_TEXTURE_GEN_MODE} and @var{params} is not an accepted defined
20228 @code{GL_INVALID_ENUM} is generated when @var{pname} is
20229 @code{GL_TEXTURE_GEN_MODE}, @var{params} is @code{GL_SPHERE_MAP}, and
20230 @var{coord} is either @code{GL_R} or @code{GL_Q}.
20232 @code{GL_INVALID_OPERATION} is generated if @code{glTexGen} is executed
20233 between the execution of @code{glBegin} and the corresponding execution
20238 @deftypefun void glTexImage1D target level internalFormat width border format type data
20239 Specify a one-dimensional texture image.
20243 Specifies the target texture. Must be @code{GL_TEXTURE_1D} or
20244 @code{GL_PROXY_TEXTURE_1D}.
20247 Specifies the level-of-detail number. Level 0 is the base image level.
20248 Level @var{n} is the @var{n}th mipmap reduction image.
20250 @item @var{internalFormat}
20251 Specifies the number of color components in the texture. Must be 1, 2,
20252 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA},
20253 @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
20254 @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA},
20255 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
20256 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
20257 @code{GL_COMPRESSED_RGBA}, @code{GL_DEPTH_COMPONENT},
20258 @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24},
20259 @code{GL_DEPTH_COMPONENT32}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
20260 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
20261 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
20262 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
20263 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
20264 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY},
20265 @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12},
20266 @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
20267 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
20268 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
20269 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
20270 @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE},
20271 @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
20272 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
20273 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
20276 Specifies the width of the texture image including the border if any. If
20277 the GL version does not support non-power-of-two sizes, this value must
20278 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
20279 implementations support texture images that are at least 64 texels wide.
20280 The height of the 1D texture image is 1.
20283 Specifies the width of the border. Must be either 0 or 1.
20286 Specifies the format of the pixel data. The following symbolic values
20287 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
20288 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
20289 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
20290 @code{GL_LUMINANCE_ALPHA}.
20293 Specifies the data type of the pixel data. The following symbolic values
20294 are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
20295 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
20296 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
20297 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
20298 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
20299 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
20300 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
20301 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
20302 and @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
20305 Specifies a pointer to the image data in memory.
20309 Texturing maps a portion of a specified texture image onto each
20310 graphical primitive for which texturing is enabled. To enable and
20311 disable one-dimensional texturing, call @code{glEnable} and
20312 @code{glDisable} with argument @code{GL_TEXTURE_1D}.
20314 Texture images are defined with @code{glTexImage1D}. The arguments
20315 describe the parameters of the texture image, such as width, width of
20316 the border, level-of-detail number (see @code{glTexParameter}), and the
20317 internal resolution and format used to store the image. The last three
20318 arguments describe how the image is represented in memory; they are
20319 identical to the pixel formats used for @code{glDrawPixels}.
20321 If @var{target} is @code{GL_PROXY_TEXTURE_1D}, no data is read from
20322 @var{data}, but all of the texture image state is recalculated, checked
20323 for consistency, and checked against the implementation's capabilities.
20324 If the implementation cannot handle a texture of the requested texture
20325 size, it sets all of the image state to 0, but does not generate an
20326 error (see @code{glGetError}). To query for an entire mipmap array, use
20327 an image array level greater than or equal to 1.
20329 If @var{target} is @code{GL_TEXTURE_1D}, data is read from @var{data} as
20330 a sequence of signed or unsigned bytes, shorts, or longs, or
20331 single-precision floating-point values, depending on @var{type}. These
20332 values are grouped into sets of one, two, three, or four values,
20333 depending on @var{format}, to form elements. If @var{type} is
20334 @code{GL_BITMAP}, the data is considered as a string of unsigned bytes
20335 (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is
20336 treated as eight 1-bit elements, with bit ordering determined by
20337 @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}).
20339 If a non-zero named buffer object is bound to the
20340 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
20341 texture image is specified, @var{data} is treated as a byte offset into
20342 the buffer object's data store.
20344 The first element corresponds to the left end of the texture array.
20345 Subsequent elements progress left-to-right through the remaining texels
20346 in the texture array. The final element corresponds to the right end of
20349 @var{format} determines the composition of each element in @var{data}.
20350 It can assume one of these symbolic values:
20353 @item @code{GL_COLOR_INDEX}
20354 Each element is a single value, a color index. The GL converts it to
20355 fixed point (with an unspecified number of zero bits to the right of the
20356 binary point), shifted left or right depending on the value and sign of
20357 @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see
20358 @code{glPixelTransfer}). The resulting index is converted to a set of
20359 color components using the @code{GL_PIXEL_MAP_I_TO_R},
20360 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
20361 @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1].
20363 @item @code{GL_RED}
20364 Each element is a single red component. The GL converts it to floating
20365 point and assembles it into an RGBA element by attaching 0 for green and
20366 blue, and 1 for alpha. Each component is then multiplied by the signed
20367 scale factor @code{GL_c_SCALE}, added to the signed bias
20368 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20369 @code{glPixelTransfer}).
20371 @item @code{GL_GREEN}
20372 Each element is a single green component. The GL converts it to floating
20373 point and assembles it into an RGBA element by attaching 0 for red and
20374 blue, and 1 for alpha. Each component is then multiplied by the signed
20375 scale factor @code{GL_c_SCALE}, added to the signed bias
20376 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20377 @code{glPixelTransfer}).
20379 @item @code{GL_BLUE}
20380 Each element is a single blue component. The GL converts it to floating
20381 point and assembles it into an RGBA element by attaching 0 for red and
20382 green, and 1 for alpha. Each component is then multiplied by the signed
20383 scale factor @code{GL_c_SCALE}, added to the signed bias
20384 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20385 @code{glPixelTransfer}).
20387 @item @code{GL_ALPHA}
20388 Each element is a single alpha component. The GL converts it to floating
20389 point and assembles it into an RGBA element by attaching 0 for red,
20390 green, and blue. Each component is then multiplied by the signed scale
20391 factor @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20392 clamped to the range [0,1] (see @code{glPixelTransfer}).
20394 @item @code{GL_INTENSITY}
20395 Each element is a single intensity value. The GL converts it to floating
20396 point, then assembles it into an RGBA element by replicating the
20397 intensity value three times for red, green, blue, and alpha. Each
20398 component is then multiplied by the signed scale factor
20399 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20400 clamped to the range [0,1] (see @code{glPixelTransfer}).
20402 @item @code{GL_RGB}
20403 @item @code{GL_BGR}
20404 Each element is an RGB triple. The GL converts it to floating point and
20405 assembles it into an RGBA element by attaching 1 for alpha. Each
20406 component is then multiplied by the signed scale factor
20407 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20408 clamped to the range [0,1] (see @code{glPixelTransfer}).
20410 @item @code{GL_RGBA}
20411 @item @code{GL_BGRA}
20412 Each element contains all four components. Each component is multiplied
20413 by the signed scale factor @code{GL_c_SCALE}, added to the signed bias
20414 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20415 @code{glPixelTransfer}).
20417 @item @code{GL_LUMINANCE}
20418 Each element is a single luminance value. The GL converts it to floating
20419 point, then assembles it into an RGBA element by replicating the
20420 luminance value three times for red, green, and blue and attaching 1 for
20421 alpha. Each component is then multiplied by the signed scale factor
20422 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20423 clamped to the range [0,1] (see @code{glPixelTransfer}).
20425 @item @code{GL_LUMINANCE_ALPHA}
20426 Each element is a luminance/alpha pair. The GL converts it to floating
20427 point, then assembles it into an RGBA element by replicating the
20428 luminance value three times for red, green, and blue. Each component is
20429 then multiplied by the signed scale factor @code{GL_c_SCALE}, added to
20430 the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20431 @code{glPixelTransfer}).
20433 @item @code{GL_DEPTH_COMPONENT}
20434 Each element is a single depth value. The GL converts it to floating
20435 point, multiplies by the signed scale factor @code{GL_DEPTH_SCALE}, adds
20436 the signed bias @code{GL_DEPTH_BIAS}, and clamps to the range [0,1] (see
20437 @code{glPixelTransfer}).
20441 Refer to the @code{glDrawPixels} reference page for a description of the
20442 acceptable values for the @var{type} parameter.
20444 If an application wants to store the texture at a certain resolution or
20445 in a certain format, it can request the resolution and format with
20446 @var{internalFormat}. The GL will choose an internal representation that
20447 closely approximates that requested by @var{internalFormat}, but it may
20448 not match exactly. (The representations specified by
20449 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and
20450 @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 may
20451 also be used to specify the above representations.)
20453 If the @var{internalFormat} parameter is one of the generic compressed
20454 formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
20455 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
20456 @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will
20457 replace the internal format with the symbolic constant for a specific
20458 internal format and compress the texture before storage. If no
20459 corresponding internal format is available, or the GL can not compress
20460 that image for any reason, the internal format is instead replaced with
20461 a corresponding base internal format.
20463 If the @var{internalFormat} parameter is @code{GL_SRGB},
20464 @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8},
20465 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
20466 or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red,
20467 green, blue, or luminance components are encoded in the sRGB color
20468 space. Any alpha component is left unchanged. The conversion from the
20469 sRGB encoded component @r{@var{c}_@var{s}} to a linear component
20470 @r{@var{c}_@var{l}} is:
20472 @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045),
20473 ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)}
20475 Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1].
20477 Use the @code{GL_PROXY_TEXTURE_1D} target to try out a resolution and
20478 format. The implementation will update and recompute its best match for
20479 the requested storage resolution and format. To then query this state,
20480 call @code{glGetTexLevelParameter}. If the texture cannot be
20481 accommodated, texture state is set to 0.
20483 A one-component texture image uses only the red component of the RGBA
20484 color from @var{data}. A two-component image uses the R and A values. A
20485 three-component image uses the R, G, and B values. A four-component
20486 image uses all of the RGBA components.
20488 Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA textures
20489 during texture filtering and application. Image-based shadowing can be
20490 enabled by comparing texture r coordinates to depth texture values to
20491 generate a boolean result. See @code{glTexParameter} for details on
20492 texture comparison.
20494 @code{GL_INVALID_ENUM} is generated if @var{target} is not
20495 @code{GL_TEXTURE_1D} or @code{GL_PROXY_TEXTURE_1D}.
20497 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
20498 format constant. Format constants other than @code{GL_STENCIL_INDEX} are
20501 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
20504 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
20505 and @var{format} is not @code{GL_COLOR_INDEX}.
20507 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
20509 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
20510 @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of
20511 @code{GL_MAX_TEXTURE_SIZE}.
20513 @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1,
20514 2, 3, 4, or one of the accepted resolution and format symbolic
20517 @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or
20518 greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
20520 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
20521 not supported and the @var{width} cannot be represented as
20522 @r{2^@var{n}+2(@var{border},)} for some integer value of @var{n}.
20524 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
20526 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
20527 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
20528 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
20529 and @var{format} is not @code{GL_RGB}.
20531 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
20532 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
20533 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
20534 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
20535 @code{GL_UNSIGNED_INT_10_10_10_2}, or
20536 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
20537 @code{GL_RGBA} nor @code{GL_BGRA}.
20539 @code{GL_INVALID_OPERATION} is generated if @var{format} is
20540 @code{GL_DEPTH_COMPONENT} and @var{internalFormat} is not
20541 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
20542 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}.
20544 @code{GL_INVALID_OPERATION} is generated if @var{internalFormat} is
20545 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
20546 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}, and
20547 @var{format} is not @code{GL_DEPTH_COMPONENT}.
20549 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
20550 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
20551 object's data store is currently mapped.
20553 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
20554 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
20555 would be unpacked from the buffer object such that the memory reads
20556 required would exceed the data store size.
20558 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
20559 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
20560 is not evenly divisible into the number of bytes needed to store in
20561 memory a datum indicated by @var{type}.
20563 @code{GL_INVALID_OPERATION} is generated if @code{glTexImage1D} is
20564 executed between the execution of @code{glBegin} and the corresponding
20565 execution of @code{glEnd}.
20569 @deftypefun void glTexImage2D target level internalFormat width height border format type data
20570 Specify a two-dimensional texture image.
20574 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
20575 @code{GL_PROXY_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
20576 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
20577 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
20578 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
20579 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z},
20580 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or
20581 @code{GL_PROXY_TEXTURE_CUBE_MAP}.
20584 Specifies the level-of-detail number. Level 0 is the base image level.
20585 Level @var{n} is the @var{n}th mipmap reduction image.
20587 @item @var{internalFormat}
20588 Specifies the number of color components in the texture. Must be 1, 2,
20589 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA},
20590 @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
20591 @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA},
20592 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
20593 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
20594 @code{GL_COMPRESSED_RGBA}, @code{GL_DEPTH_COMPONENT},
20595 @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24},
20596 @code{GL_DEPTH_COMPONENT32}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
20597 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
20598 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
20599 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
20600 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
20601 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY},
20602 @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12},
20603 @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
20604 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
20605 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
20606 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
20607 @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE},
20608 @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
20609 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
20610 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
20613 Specifies the width of the texture image including the border if any. If
20614 the GL version does not support non-power-of-two sizes, this value must
20615 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
20616 implementations support texture images that are at least 64 texels wide.
20619 Specifies the height of the texture image including the border if any.
20620 If the GL version does not support non-power-of-two sizes, this value
20621 must be @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}.
20622 All implementations support texture images that are at least 64 texels
20626 Specifies the width of the border. Must be either 0 or 1.
20629 Specifies the format of the pixel data. The following symbolic values
20630 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
20631 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
20632 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
20633 @code{GL_LUMINANCE_ALPHA}.
20636 Specifies the data type of the pixel data. The following symbolic values
20637 are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
20638 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
20639 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
20640 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
20641 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
20642 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
20643 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
20644 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
20645 and @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
20648 Specifies a pointer to the image data in memory.
20652 Texturing maps a portion of a specified texture image onto each
20653 graphical primitive for which texturing is enabled. To enable and
20654 disable two-dimensional texturing, call @code{glEnable} and
20655 @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and
20656 disable texturing using cube-mapped texture, call @code{glEnable} and
20657 @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}.
20659 To define texture images, call @code{glTexImage2D}. The arguments
20660 describe the parameters of the texture image, such as height, width,
20661 width of the border, level-of-detail number (see @code{glTexParameter}),
20662 and number of color components provided. The last three arguments
20663 describe how the image is represented in memory; they are identical to
20664 the pixel formats used for @code{glDrawPixels}.
20666 If @var{target} is @code{GL_PROXY_TEXTURE_2D} or
20667 @code{GL_PROXY_TEXTURE_CUBE_MAP}, no data is read from @var{data}, but
20668 all of the texture image state is recalculated, checked for consistency,
20669 and checked against the implementation's capabilities. If the
20670 implementation cannot handle a texture of the requested texture size, it
20671 sets all of the image state to 0, but does not generate an error (see
20672 @code{glGetError}). To query for an entire mipmap array, use an image
20673 array level greater than or equal to 1.
20675 If @var{target} is @code{GL_TEXTURE_2D}, or one of the
20676 @code{GL_TEXTURE_CUBE_MAP} targets, data is read from @var{data} as a
20677 sequence of signed or unsigned bytes, shorts, or longs, or
20678 single-precision floating-point values, depending on @var{type}. These
20679 values are grouped into sets of one, two, three, or four values,
20680 depending on @var{format}, to form elements. If @var{type} is
20681 @code{GL_BITMAP}, the data is considered as a string of unsigned bytes
20682 (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is
20683 treated as eight 1-bit elements, with bit ordering determined by
20684 @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}).
20686 If a non-zero named buffer object is bound to the
20687 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
20688 texture image is specified, @var{data} is treated as a byte offset into
20689 the buffer object's data store.
20691 The first element corresponds to the lower left corner of the texture
20692 image. Subsequent elements progress left-to-right through the remaining
20693 texels in the lowest row of the texture image, and then in successively
20694 higher rows of the texture image. The final element corresponds to the
20695 upper right corner of the texture image.
20697 @var{format} determines the composition of each element in @var{data}.
20698 It can assume one of these symbolic values:
20701 @item @code{GL_COLOR_INDEX}
20702 Each element is a single value, a color index. The GL converts it to
20703 fixed point (with an unspecified number of zero bits to the right of the
20704 binary point), shifted left or right depending on the value and sign of
20705 @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see
20706 @code{glPixelTransfer}). The resulting index is converted to a set of
20707 color components using the @code{GL_PIXEL_MAP_I_TO_R},
20708 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
20709 @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1].
20711 @item @code{GL_RED}
20712 Each element is a single red component. The GL converts it to floating
20713 point and assembles it into an RGBA element by attaching 0 for green and
20714 blue, and 1 for alpha. Each component is then multiplied by the signed
20715 scale factor @code{GL_c_SCALE}, added to the signed bias
20716 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20717 @code{glPixelTransfer}).
20719 @item @code{GL_GREEN}
20720 Each element is a single green component. The GL converts it to floating
20721 point and assembles it into an RGBA element by attaching 0 for red and
20722 blue, and 1 for alpha. Each component is then multiplied by the signed
20723 scale factor @code{GL_c_SCALE}, added to the signed bias
20724 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20725 @code{glPixelTransfer}).
20727 @item @code{GL_BLUE}
20728 Each element is a single blue component. The GL converts it to floating
20729 point and assembles it into an RGBA element by attaching 0 for red and
20730 green, and 1 for alpha. Each component is then multiplied by the signed
20731 scale factor @code{GL_c_SCALE}, added to the signed bias
20732 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20733 @code{glPixelTransfer}).
20735 @item @code{GL_ALPHA}
20736 Each element is a single alpha component. The GL converts it to floating
20737 point and assembles it into an RGBA element by attaching 0 for red,
20738 green, and blue. Each component is then multiplied by the signed scale
20739 factor @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20740 clamped to the range [0,1] (see @code{glPixelTransfer}).
20742 @item @code{GL_INTENSITY}
20743 Each element is a single intensity value. The GL converts it to floating
20744 point, then assembles it into an RGBA element by replicating the
20745 intensity value three times for red, green, blue, and alpha. Each
20746 component is then multiplied by the signed scale factor
20747 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20748 clamped to the range [0,1] (see @code{glPixelTransfer}).
20750 @item @code{GL_RGB}
20751 @item @code{GL_BGR}
20752 Each element is an RGB triple. The GL converts it to floating point and
20753 assembles it into an RGBA element by attaching 1 for alpha. Each
20754 component is then multiplied by the signed scale factor
20755 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20756 clamped to the range [0,1] (see @code{glPixelTransfer}).
20758 @item @code{GL_RGBA}
20759 @item @code{GL_BGRA}
20760 Each element contains all four components. Each component is multiplied
20761 by the signed scale factor @code{GL_c_SCALE}, added to the signed bias
20762 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20763 @code{glPixelTransfer}).
20765 @item @code{GL_LUMINANCE}
20766 Each element is a single luminance value. The GL converts it to floating
20767 point, then assembles it into an RGBA element by replicating the
20768 luminance value three times for red, green, and blue and attaching 1 for
20769 alpha. Each component is then multiplied by the signed scale factor
20770 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20771 clamped to the range [0,1] (see @code{glPixelTransfer}).
20773 @item @code{GL_LUMINANCE_ALPHA}
20774 Each element is a luminance/alpha pair. The GL converts it to floating
20775 point, then assembles it into an RGBA element by replicating the
20776 luminance value three times for red, green, and blue. Each component is
20777 then multiplied by the signed scale factor @code{GL_c_SCALE}, added to
20778 the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20779 @code{glPixelTransfer}).
20781 @item @code{GL_DEPTH_COMPONENT}
20782 Each element is a single depth value. The GL converts it to floating
20783 point, multiplies by the signed scale factor @code{GL_DEPTH_SCALE}, adds
20784 the signed bias @code{GL_DEPTH_BIAS}, and clamps to the range [0,1] (see
20785 @code{glPixelTransfer}).
20789 Refer to the @code{glDrawPixels} reference page for a description of the
20790 acceptable values for the @var{type} parameter.
20792 If an application wants to store the texture at a certain resolution or
20793 in a certain format, it can request the resolution and format with
20794 @var{internalFormat}. The GL will choose an internal representation that
20795 closely approximates that requested by @var{internalFormat}, but it may
20796 not match exactly. (The representations specified by
20797 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and
20798 @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 may
20799 also be used to specify the above representations.)
20801 If the @var{internalFormat} parameter is one of the generic compressed
20802 formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
20803 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
20804 @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will
20805 replace the internal format with the symbolic constant for a specific
20806 internal format and compress the texture before storage. If no
20807 corresponding internal format is available, or the GL can not compress
20808 that image for any reason, the internal format is instead replaced with
20809 a corresponding base internal format.
20811 If the @var{internalFormat} parameter is @code{GL_SRGB},
20812 @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8},
20813 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
20814 or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red,
20815 green, blue, or luminance components are encoded in the sRGB color
20816 space. Any alpha component is left unchanged. The conversion from the
20817 sRGB encoded component @r{@var{c}_@var{s}} to a linear component
20818 @r{@var{c}_@var{l}} is:
20820 @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045),
20821 ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)}
20823 Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1].
20825 Use the @code{GL_PROXY_TEXTURE_2D} or @code{GL_PROXY_TEXTURE_CUBE_MAP}
20826 target to try out a resolution and format. The implementation will
20827 update and recompute its best match for the requested storage resolution
20828 and format. To then query this state, call
20829 @code{glGetTexLevelParameter}. If the texture cannot be accommodated,
20830 texture state is set to 0.
20832 A one-component texture image uses only the red component of the RGBA
20833 color extracted from @var{data}. A two-component image uses the R and A
20834 values. A three-component image uses the R, G, and B values. A
20835 four-component image uses all of the RGBA components.
20837 Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA textures
20838 during texture filtering and application. Image-based shadowing can be
20839 enabled by comparing texture r coordinates to depth texture values to
20840 generate a boolean result. See @code{glTexParameter} for details on
20841 texture comparison.
20843 @code{GL_INVALID_ENUM} is generated if @var{target} is not
20844 @code{GL_TEXTURE_2D}, @code{GL_PROXY_TEXTURE_2D},
20845 @code{GL_PROXY_TEXTURE_CUBE_MAP}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
20846 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
20847 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
20848 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
20849 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
20850 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
20852 @code{GL_INVALID_ENUM} is generated if @var{target} is one of the six
20853 cube map 2D image targets and the width and height parameters are not
20856 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
20859 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
20860 and @var{format} is not @code{GL_COLOR_INDEX}.
20862 @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is
20863 less than 0 or greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
20865 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
20867 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
20868 @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of
20869 @code{GL_MAX_TEXTURE_SIZE}.
20871 @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1,
20872 2, 3, 4, or one of the accepted resolution and format symbolic
20875 @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is
20876 less than 0 or greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
20878 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
20879 not supported and the @var{width} or @var{height} cannot be represented
20880 as @r{2^@var{k}+2(@var{border},)} for some integer value of @var{k}.
20882 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
20884 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
20885 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
20886 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
20887 and @var{format} is not @code{GL_RGB}.
20889 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
20890 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
20891 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
20892 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
20893 @code{GL_UNSIGNED_INT_10_10_10_2}, or
20894 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
20895 @code{GL_RGBA} nor @code{GL_BGRA}.
20897 @code{GL_INVALID_OPERATION} is generated if @var{target} is not
20898 @code{GL_TEXTURE_2D} or @code{GL_PROXY_TEXTURE_2D} and
20899 @var{internalFormat} is @code{GL_DEPTH_COMPONENT},
20900 @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, or
20901 @code{GL_DEPTH_COMPONENT32}.
20903 @code{GL_INVALID_OPERATION} is generated if @var{format} is
20904 @code{GL_DEPTH_COMPONENT} and @var{internalFormat} is not
20905 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
20906 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}.
20908 @code{GL_INVALID_OPERATION} is generated if @var{internalFormat} is
20909 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
20910 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}, and
20911 @var{format} is not @code{GL_DEPTH_COMPONENT}.
20913 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
20914 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
20915 object's data store is currently mapped.
20917 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
20918 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
20919 would be unpacked from the buffer object such that the memory reads
20920 required would exceed the data store size.
20922 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
20923 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
20924 is not evenly divisible into the number of bytes needed to store in
20925 memory a datum indicated by @var{type}.
20927 @code{GL_INVALID_OPERATION} is generated if @code{glTexImage2D} is
20928 executed between the execution of @code{glBegin} and the corresponding
20929 execution of @code{glEnd}.
20933 @deftypefun void glTexImage3D target level internalFormat width height depth border format type data
20934 Specify a three-dimensional texture image.
20938 Specifies the target texture. Must be @code{GL_TEXTURE_3D} or
20939 @code{GL_PROXY_TEXTURE_3D}.
20942 Specifies the level-of-detail number. Level 0 is the base image level.
20943 Level @r{@var{n}} is the @r{@var{n}^@var{th}} mipmap reduction image.
20945 @item @var{internalFormat}
20946 Specifies the number of color components in the texture. Must be 1, 2,
20947 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA},
20948 @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
20949 @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA},
20950 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
20951 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
20952 @code{GL_COMPRESSED_RGBA}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
20953 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
20954 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
20955 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
20956 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
20957 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY},
20958 @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12},
20959 @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
20960 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
20961 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
20962 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
20963 @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE},
20964 @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
20965 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
20966 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
20969 Specifies the width of the texture image including the border if any. If
20970 the GL version does not support non-power-of-two sizes, this value must
20971 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
20972 implementations support 3D texture images that are at least 16 texels
20976 Specifies the height of the texture image including the border if any.
20977 If the GL version does not support non-power-of-two sizes, this value
20978 must be @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}.
20979 All implementations support 3D texture images that are at least 16
20983 Specifies the depth of the texture image including the border if any. If
20984 the GL version does not support non-power-of-two sizes, this value must
20985 be @r{2^@var{k}+2(@var{border},)} for some integer @r{@var{k}}. All
20986 implementations support 3D texture images that are at least 16 texels
20990 Specifies the width of the border. Must be either 0 or 1.
20993 Specifies the format of the pixel data. The following symbolic values
20994 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
20995 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
20996 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
20997 @code{GL_LUMINANCE_ALPHA}.
21000 Specifies the data type of the pixel data. The following symbolic values
21001 are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
21002 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
21003 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
21004 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
21005 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
21006 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
21007 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
21008 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
21009 and @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
21012 Specifies a pointer to the image data in memory.
21016 Texturing maps a portion of a specified texture image onto each
21017 graphical primitive for which texturing is enabled. To enable and
21018 disable three-dimensional texturing, call @code{glEnable} and
21019 @code{glDisable} with argument @code{GL_TEXTURE_3D}.
21021 To define texture images, call @code{glTexImage3D}. The arguments
21022 describe the parameters of the texture image, such as height, width,
21023 depth, width of the border, level-of-detail number (see
21024 @code{glTexParameter}), and number of color components provided. The
21025 last three arguments describe how the image is represented in memory;
21026 they are identical to the pixel formats used for @code{glDrawPixels}.
21028 If @var{target} is @code{GL_PROXY_TEXTURE_3D}, no data is read from
21029 @var{data}, but all of the texture image state is recalculated, checked
21030 for consistency, and checked against the implementation's capabilities.
21031 If the implementation cannot handle a texture of the requested texture
21032 size, it sets all of the image state to 0, but does not generate an
21033 error (see @code{glGetError}). To query for an entire mipmap array, use
21034 an image array level greater than or equal to 1.
21036 If @var{target} is @code{GL_TEXTURE_3D}, data is read from @var{data} as
21037 a sequence of signed or unsigned bytes, shorts, or longs, or
21038 single-precision floating-point values, depending on @var{type}. These
21039 values are grouped into sets of one, two, three, or four values,
21040 depending on @var{format}, to form elements. If @var{type} is
21041 @code{GL_BITMAP}, the data is considered as a string of unsigned bytes
21042 (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is
21043 treated as eight 1-bit elements, with bit ordering determined by
21044 @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}).
21046 If a non-zero named buffer object is bound to the
21047 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
21048 texture image is specified, @var{data} is treated as a byte offset into
21049 the buffer object's data store.
21051 The first element corresponds to the lower left corner of the texture
21052 image. Subsequent elements progress left-to-right through the remaining
21053 texels in the lowest row of the texture image, and then in successively
21054 higher rows of the texture image. The final element corresponds to the
21055 upper right corner of the texture image.
21057 @var{format} determines the composition of each element in @var{data}.
21058 It can assume one of these symbolic values:
21061 @item @code{GL_COLOR_INDEX}
21062 Each element is a single value, a color index. The GL converts it to
21063 fixed point (with an unspecified number of zero bits to the right of the
21064 binary point), shifted left or right depending on the value and sign of
21065 @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see
21066 @code{glPixelTransfer}). The resulting index is converted to a set of
21067 color components using the @code{GL_PIXEL_MAP_I_TO_R},
21068 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
21069 @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1].
21071 @item @code{GL_RED}
21072 Each element is a single red component. The GL converts it to floating
21073 point and assembles it into an RGBA element by attaching 0 for green and
21074 blue, and 1 for alpha. Each component is then multiplied by the signed
21075 scale factor @code{GL_c_SCALE}, added to the signed bias
21076 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
21077 @code{glPixelTransfer}).
21079 @item @code{GL_GREEN}
21080 Each element is a single green component. The GL converts it to floating
21081 point and assembles it into an RGBA element by attaching 0 for red and
21082 blue, and 1 for alpha. Each component is then multiplied by the signed
21083 scale factor @code{GL_c_SCALE}, added to the signed bias
21084 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
21085 @code{glPixelTransfer}).
21087 @item @code{GL_BLUE}
21088 Each element is a single blue component. The GL converts it to floating
21089 point and assembles it into an RGBA element by attaching 0 for red and
21090 green, and 1 for alpha. Each component is then multiplied by the signed
21091 scale factor @code{GL_c_SCALE}, added to the signed bias
21092 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
21093 @code{glPixelTransfer}).
21095 @item @code{GL_ALPHA}
21096 Each element is a single alpha component. The GL converts it to floating
21097 point and assembles it into an RGBA element by attaching 0 for red,
21098 green, and blue. Each component is then multiplied by the signed scale
21099 factor @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
21100 clamped to the range [0,1] (see @code{glPixelTransfer}).
21102 @item @code{GL_INTENSITY}
21103 Each element is a single intensity value. The GL converts it to floating
21104 point, then assembles it into an RGBA element by replicating the
21105 intensity value three times for red, green, blue, and alpha. Each
21106 component is then multiplied by the signed scale factor
21107 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
21108 clamped to the range [0,1] (see @code{glPixelTransfer}).
21110 @item @code{GL_RGB}
21111 @item @code{GL_BGR}
21112 Each element is an RGB triple. The GL converts it to floating point and
21113 assembles it into an RGBA element by attaching 1 for alpha. Each
21114 component is then multiplied by the signed scale factor
21115 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
21116 clamped to the range [0,1] (see @code{glPixelTransfer}).
21118 @item @code{GL_RGBA}
21119 @item @code{GL_BGRA}
21120 Each element contains all four components. Each component is multiplied
21121 by the signed scale factor @code{GL_c_SCALE}, added to the signed bias
21122 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
21123 @code{glPixelTransfer}).
21125 @item @code{GL_LUMINANCE}
21126 Each element is a single luminance value. The GL converts it to floating
21127 point, then assembles it into an RGBA element by replicating the
21128 luminance value three times for red, green, and blue and attaching 1 for
21129 alpha. Each component is then multiplied by the signed scale factor
21130 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
21131 clamped to the range [0,1] (see @code{glPixelTransfer}).
21133 @item @code{GL_LUMINANCE_ALPHA}
21134 Each element is a luminance/alpha pair. The GL converts it to floating
21135 point, then assembles it into an RGBA element by replicating the
21136 luminance value three times for red, green, and blue. Each component is
21137 then multiplied by the signed scale factor @code{GL_c_SCALE}, added to
21138 the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see
21139 @code{glPixelTransfer}).
21143 Refer to the @code{glDrawPixels} reference page for a description of the
21144 acceptable values for the @var{type} parameter.
21146 If an application wants to store the texture at a certain resolution or
21147 in a certain format, it can request the resolution and format with
21148 @var{internalFormat}. The GL will choose an internal representation that
21149 closely approximates that requested by @var{internalFormat}, but it may
21150 not match exactly. (The representations specified by
21151 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and
21152 @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 may
21153 also be used to specify the above representations.)
21155 If the @var{internalFormat} parameter is one of the generic compressed
21156 formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
21157 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
21158 @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will
21159 replace the internal format with the symbolic constant for a specific
21160 internal format and compress the texture before storage. If no
21161 corresponding internal format is available, or the GL can not compress
21162 that image for any reason, the internal format is instead replaced with
21163 a corresponding base internal format.
21165 If the @var{internalFormat} parameter is @code{GL_SRGB},
21166 @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8},
21167 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
21168 or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red,
21169 green, blue, or luminance components are encoded in the sRGB color
21170 space. Any alpha component is left unchanged. The conversion from the
21171 sRGB encoded component @r{@var{c}_@var{s}} to a linear component
21172 @r{@var{c}_@var{l}} is:
21174 @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045),
21175 ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)}
21177 Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1].
21179 Use the @code{GL_PROXY_TEXTURE_3D} target to try out a resolution and
21180 format. The implementation will update and recompute its best match for
21181 the requested storage resolution and format. To then query this state,
21182 call @code{glGetTexLevelParameter}. If the texture cannot be
21183 accommodated, texture state is set to 0.
21185 A one-component texture image uses only the red component of the RGBA
21186 color extracted from @var{data}. A two-component image uses the R and A
21187 values. A three-component image uses the R, G, and B values. A
21188 four-component image uses all of the RGBA components.
21190 @code{GL_INVALID_ENUM} is generated if @var{target} is not
21191 @code{GL_TEXTURE_3D} or @code{GL_PROXY_TEXTURE_3D}.
21193 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
21194 format constant. Format constants other than @code{GL_STENCIL_INDEX} and
21195 @code{GL_DEPTH_COMPONENT} are accepted.
21197 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
21200 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
21201 and @var{format} is not @code{GL_COLOR_INDEX}.
21203 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
21205 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
21206 @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of
21207 @code{GL_MAX_TEXTURE_SIZE}.
21209 @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1,
21210 2, 3, 4, or one of the accepted resolution and format symbolic
21213 @code{GL_INVALID_VALUE} is generated if @var{width}, @var{height}, or
21214 @var{depth} is less than 0 or greater than 2 +
21215 @code{GL_MAX_TEXTURE_SIZE}.
21217 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
21218 not supported and the @var{width}, @var{height}, or @var{depth} cannot
21219 be represented as @r{2^@var{k}+2(@var{border},)} for some integer value
21222 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
21224 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21225 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
21226 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
21227 and @var{format} is not @code{GL_RGB}.
21229 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21230 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
21231 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
21232 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
21233 @code{GL_UNSIGNED_INT_10_10_10_2}, or
21234 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
21235 @code{GL_RGBA} nor @code{GL_BGRA}.
21237 @code{GL_INVALID_OPERATION} is generated if @var{format} or
21238 @var{internalFormat} is @code{GL_DEPTH_COMPONENT},
21239 @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, or
21240 @code{GL_DEPTH_COMPONENT32}.
21242 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21243 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
21244 object's data store is currently mapped.
21246 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21247 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
21248 would be unpacked from the buffer object such that the memory reads
21249 required would exceed the data store size.
21251 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21252 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
21253 is not evenly divisible into the number of bytes needed to store in
21254 memory a datum indicated by @var{type}.
21256 @code{GL_INVALID_OPERATION} is generated if @code{glTexImage3D} is
21257 executed between the execution of @code{glBegin} and the corresponding
21258 execution of @code{glEnd}.
21262 @deftypefun void glTexParameterf target pname param
21263 @deftypefunx void glTexParameteri target pname param
21264 Set texture parameters.
21268 Specifies the target texture, which must be either @code{GL_TEXTURE_1D},
21269 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, or
21270 @code{GL_TEXTURE_CUBE_MAP}.
21273 Specifies the symbolic name of a single-valued texture parameter.
21274 @var{pname} can be one of the following: @code{GL_TEXTURE_MIN_FILTER},
21275 @code{GL_TEXTURE_MAG_FILTER}, @code{GL_TEXTURE_MIN_LOD},
21276 @code{GL_TEXTURE_MAX_LOD}, @code{GL_TEXTURE_BASE_LEVEL},
21277 @code{GL_TEXTURE_MAX_LEVEL}, @code{GL_TEXTURE_WRAP_S},
21278 @code{GL_TEXTURE_WRAP_T}, @code{GL_TEXTURE_WRAP_R},
21279 @code{GL_TEXTURE_PRIORITY}, @code{GL_TEXTURE_COMPARE_MODE},
21280 @code{GL_TEXTURE_COMPARE_FUNC}, @code{GL_DEPTH_TEXTURE_MODE}, or
21281 @code{GL_GENERATE_MIPMAP}.
21284 Specifies the value of @var{pname}.
21288 Texture mapping is a technique that applies an image onto an object's
21289 surface as if the image were a decal or cellophane shrink-wrap. The
21290 image is created in texture space, with an (@r{@var{s}}, @r{@var{t}})
21291 coordinate system. A texture is a one- or two-dimensional image and a
21292 set of parameters that determine how samples are derived from the image.
21294 @code{glTexParameter} assigns the value or values in @var{params} to the
21295 texture parameter specified as @var{pname}. @var{target} defines the
21296 target texture, either @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, or
21297 @code{GL_TEXTURE_3D}. The following symbols are accepted in @var{pname}:
21300 @item @code{GL_TEXTURE_MIN_FILTER}
21301 The texture minifying function is used whenever the pixel being textured
21302 maps to an area greater than one texture element. There are six defined
21303 minifying functions. Two of them use the nearest one or nearest four
21304 texture elements to compute the texture value. The other four use
21307 A mipmap is an ordered set of arrays representing the same image at
21308 progressively lower resolutions. If the texture has dimensions
21309 @r{2^@var{n}×2^@var{m}}, there are @r{@var{max}(@var{n},@var{m})+1}
21310 mipmaps. The first mipmap is the original texture, with dimensions
21311 @r{2^@var{n}×2^@var{m}}. Each subsequent mipmap has dimensions
21312 @r{2^@var{k}-1,×2^@var{l}-1,}, where @r{2^@var{k}×2^@var{l}} are the
21313 dimensions of the previous mipmap, until either @r{@var{k}=0} or
21314 @r{@var{l}=0}. At that point, subsequent mipmaps have dimension
21315 @r{1×2^@var{l}-1,} or @r{2^@var{k}-1,×1} until the final mipmap, which
21316 has dimension @r{1×1}. To define the mipmaps, call @code{glTexImage1D},
21317 @code{glTexImage2D}, @code{glTexImage3D}, @code{glCopyTexImage1D}, or
21318 @code{glCopyTexImage2D} with the @var{level} argument indicating the
21319 order of the mipmaps. Level 0 is the original texture; level
21320 @r{@var{max}(@var{n},@var{m})} is the final @r{1×1} mipmap.
21322 @var{params} supplies a function for minifying the texture as one of the
21325 As more texture elements are sampled in the minification process, fewer
21326 aliasing artifacts will be apparent. While the @code{GL_NEAREST} and
21327 @code{GL_LINEAR} minification functions can be faster than the other
21328 four, they sample only one or four texture elements to determine the
21329 texture value of the pixel being rendered and can produce moire patterns
21330 or ragged transitions. The initial value of @code{GL_TEXTURE_MIN_FILTER}
21331 is @code{GL_NEAREST_MIPMAP_LINEAR}.
21333 @item @code{GL_TEXTURE_MAG_FILTER}
21334 The texture magnification function is used when the pixel being textured
21335 maps to an area less than or equal to one texture element. It sets the
21336 texture magnification function to either @code{GL_NEAREST} or
21337 @code{GL_LINEAR} (see below). @code{GL_NEAREST} is generally faster than
21338 @code{GL_LINEAR}, but it can produce textured images with sharper edges
21339 because the transition between texture elements is not as smooth. The
21340 initial value of @code{GL_TEXTURE_MAG_FILTER} is @code{GL_LINEAR}.
21345 @item @code{GL_NEAREST}
21346 Returns the value of the texture element that is nearest (in Manhattan
21347 distance) to the center of the pixel being textured.
21349 @item @code{GL_LINEAR}
21350 Returns the weighted average of the four texture elements that are
21351 closest to the center of the pixel being textured. These can include
21352 border texture elements, depending on the values of
21353 @code{GL_TEXTURE_WRAP_S} and @code{GL_TEXTURE_WRAP_T}, and on the exact
21356 @item @code{GL_NEAREST_MIPMAP_NEAREST}
21357 Chooses the mipmap that most closely matches the size of the pixel being
21358 textured and uses the @code{GL_NEAREST} criterion (the texture element
21359 nearest to the center of the pixel) to produce a texture value.
21361 @item @code{GL_LINEAR_MIPMAP_NEAREST}
21362 Chooses the mipmap that most closely matches the size of the pixel being
21363 textured and uses the @code{GL_LINEAR} criterion (a weighted average of
21364 the four texture elements that are closest to the center of the pixel)
21365 to produce a texture value.
21367 @item @code{GL_NEAREST_MIPMAP_LINEAR}
21368 Chooses the two mipmaps that most closely match the size of the pixel
21369 being textured and uses the @code{GL_NEAREST} criterion (the texture
21370 element nearest to the center of the pixel) to produce a texture value
21371 from each mipmap. The final texture value is a weighted average of those
21374 @item @code{GL_LINEAR_MIPMAP_LINEAR}
21375 Chooses the two mipmaps that most closely match the size of the pixel
21376 being textured and uses the @code{GL_LINEAR} criterion (a weighted
21377 average of the four texture elements that are closest to the center of
21378 the pixel) to produce a texture value from each mipmap. The final
21379 texture value is a weighted average of those two values.
21384 @item @code{GL_NEAREST}
21385 Returns the value of the texture element that is nearest (in Manhattan
21386 distance) to the center of the pixel being textured.
21388 @item @code{GL_LINEAR}
21389 Returns the weighted average of the four texture elements that are
21390 closest to the center of the pixel being textured. These can include
21391 border texture elements, depending on the values of
21392 @code{GL_TEXTURE_WRAP_S} and @code{GL_TEXTURE_WRAP_T}, and on the exact
21400 @item @code{GL_TEXTURE_MIN_LOD}
21401 Sets the minimum level-of-detail parameter. This floating-point value
21402 limits the selection of highest resolution mipmap (lowest mipmap level).
21403 The initial value is -1000.
21410 @item @code{GL_TEXTURE_MAX_LOD}
21411 Sets the maximum level-of-detail parameter. This floating-point value
21412 limits the selection of the lowest resolution mipmap (highest mipmap
21413 level). The initial value is 1000.
21420 @item @code{GL_TEXTURE_BASE_LEVEL}
21421 Specifies the index of the lowest defined mipmap level. This is an
21422 integer value. The initial value is 0.
21429 @item @code{GL_TEXTURE_MAX_LEVEL}
21430 Sets the index of the highest defined mipmap level. This is an integer
21431 value. The initial value is 1000.
21438 @item @code{GL_TEXTURE_WRAP_S}
21439 Sets the wrap parameter for texture coordinate @r{@var{s}} to either
21440 @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE},
21441 @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. @code{GL_CLAMP} causes
21442 @r{@var{s}} coordinates to be clamped to the range [0,1] and is useful
21443 for preventing wrapping artifacts when mapping a single image onto an
21444 object. @code{GL_CLAMP_TO_BORDER} causes the @r{@var{s}} coordinate to
21445 be clamped to the range @r{[-1/2@var{N},,1+1/2@var{N},]}, where
21446 @r{@var{N}} is the size of the texture in the direction of
21447 clamping.@code{GL_CLAMP_TO_EDGE} causes @r{@var{s}} coordinates to be
21448 clamped to the range @r{[1/2@var{N},,1-1/2@var{N},]}, where @r{@var{N}}
21449 is the size of the texture in the direction of clamping.
21450 @code{GL_REPEAT} causes the integer part of the @r{@var{s}} coordinate
21451 to be ignored; the GL uses only the fractional part, thereby creating a
21452 repeating pattern. @code{GL_MIRRORED_REPEAT} causes the @r{@var{s}}
21453 coordinate to be set to the fractional part of the texture coordinate if
21454 the integer part of @r{@var{s}} is even; if the integer part of
21455 @r{@var{s}} is odd, then the @r{@var{s}} texture coordinate is set to
21456 @r{1-@var{frac}(@var{s},)}, where @r{@var{frac}(@var{s},)} represents
21457 the fractional part of @r{@var{s}}. Border texture elements are accessed
21458 only if wrapping is set to @code{GL_CLAMP} or @code{GL_CLAMP_TO_BORDER}.
21459 Initially, @code{GL_TEXTURE_WRAP_S} is set to @code{GL_REPEAT}.
21466 @item @code{GL_TEXTURE_WRAP_T}
21467 Sets the wrap parameter for texture coordinate @r{@var{t}} to either
21468 @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE},
21469 @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. See the discussion under
21470 @code{GL_TEXTURE_WRAP_S}. Initially, @code{GL_TEXTURE_WRAP_T} is set to
21473 @item @code{GL_TEXTURE_WRAP_R}
21474 Sets the wrap parameter for texture coordinate @r{@var{r}} to either
21475 @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE},
21476 @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. See the discussion under
21477 @code{GL_TEXTURE_WRAP_S}. Initially, @code{GL_TEXTURE_WRAP_R} is set to
21480 @item @code{GL_TEXTURE_BORDER_COLOR}
21481 Sets a border color. @var{params} contains four values that comprise the
21482 RGBA color of the texture border. Integer color components are
21483 interpreted linearly such that the most positive integer maps to 1.0,
21484 and the most negative integer maps to -1.0. The values are clamped to
21485 the range [0,1] when they are specified. Initially, the border color is
21488 @item @code{GL_TEXTURE_PRIORITY}
21489 Specifies the texture residence priority of the currently bound texture.
21490 Permissible values are in the range @r{[0,1]}. See
21491 @code{glPrioritizeTextures} and @code{glBindTexture} for more
21494 @item @code{GL_TEXTURE_COMPARE_MODE}
21495 Specifies the texture comparison mode for currently bound depth
21496 textures. That is, a texture whose internal format is
21497 @code{GL_DEPTH_COMPONENT_*}; see @code{glTexImage2D}) Permissible values
21500 @item @code{GL_TEXTURE_COMPARE_FUNC}
21501 Specifies the comparison operator used when
21502 @code{GL_TEXTURE_COMPARE_MODE} is set to @code{GL_COMPARE_R_TO_TEXTURE}.
21503 Permissible values are: where @r{@var{r}} is the current interpolated
21504 texture coordinate, and @r{@var{D}_@var{t}} is the depth texture value
21505 sampled from the currently bound depth texture. @r{@var{result}} is
21506 assigned to the either the luminance, intensity, or alpha (as specified
21507 by @code{GL_DEPTH_TEXTURE_MODE}.)
21509 @item @code{GL_DEPTH_TEXTURE_MODE}
21510 Specifies a single symbolic constant indicating how depth values should
21511 be treated during filtering and texture application. Accepted values are
21512 @code{GL_LUMINANCE}, @code{GL_INTENSITY}, and @code{GL_ALPHA}. The
21513 initial value is @code{GL_LUMINANCE}.
21515 @item @code{GL_GENERATE_MIPMAP}
21516 Specifies a boolean value that indicates if all levels of a mipmap array
21517 should be automatically updated when any modification to the base level
21518 mipmap is done. The initial value is @code{GL_FALSE}.
21523 @item @code{GL_COMPARE_R_TO_TEXTURE}
21524 Specifies that the interpolated and clamped @r{@var{r}} texture
21525 coordinate should be compared to the value in the currently bound depth
21526 texture. See the discussion of @code{GL_TEXTURE_COMPARE_FUNC} for
21527 details of how the comparison is evaluated. The result of the comparison
21528 is assigned to luminance, intensity, or alpha (as specified by
21529 @code{GL_DEPTH_TEXTURE_MODE}).
21531 @item @code{GL_NONE}
21532 Specifies that the luminance, intensity, or alpha (as specified by
21533 @code{GL_DEPTH_TEXTURE_MODE}) should be assigned the appropriate value
21534 from the currently bound depth texture.
21539 @item @strong{Texture Comparison Function}
21540 @strong{Computed result}
21542 @item @code{GL_LEQUAL}
21543 @r{@var{result}=@{(1.0), (0.0) (@var{r}<=@var{D}_@var{t},),
21544 (@var{r}>@var{D}_@var{t},),}
21546 @item @code{GL_GEQUAL}
21547 @r{@var{result}=@{(1.0), (0.0) (@var{r}>=@var{D}_@var{t},),
21548 (@var{r}<@var{D}_@var{t},),}
21550 @item @code{GL_LESS}
21551 @r{@var{result}=@{(1.0), (0.0) (@var{r}<@var{D}_@var{t},),
21552 (@var{r}>=@var{D}_@var{t},),}
21554 @item @code{GL_GREATER}
21555 @r{@var{result}=@{(1.0), (0.0) (@var{r}>@var{D}_@var{t},),
21556 (@var{r}<=@var{D}_@var{t},),}
21558 @item @code{GL_EQUAL}
21559 @r{@var{result}=@{(1.0), (0.0) (@var{r}=@var{D}_@var{t},),
21560 (@var{r}≠@var{D}_@var{t},),}
21562 @item @code{GL_NOTEQUAL}
21563 @r{@var{result}=@{(1.0), (0.0) (@var{r}≠@var{D}_@var{t},),
21564 (@var{r}=@var{D}_@var{t},),}
21566 @item @code{GL_ALWAYS}
21567 @r{@var{result}=@code{1.0}}
21569 @item @code{GL_NEVER}
21570 @r{@var{result}=@code{0.0}}
21574 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
21575 not one of the accepted defined values.
21577 @code{GL_INVALID_ENUM} is generated if @var{params} should have a
21578 defined constant value (based on the value of @var{pname}) and does not.
21580 @code{GL_INVALID_OPERATION} is generated if @code{glTexParameter} is
21581 executed between the execution of @code{glBegin} and the corresponding
21582 execution of @code{glEnd}.
21586 @deftypefun void glTexSubImage1D target level xoffset width format type data
21587 Specify a one-dimensional texture subimage.
21591 Specifies the target texture. Must be @code{GL_TEXTURE_1D}.
21594 Specifies the level-of-detail number. Level 0 is the base image level.
21595 Level @var{n} is the @var{n}th mipmap reduction image.
21597 @item @var{xoffset}
21598 Specifies a texel offset in the x direction within the texture array.
21601 Specifies the width of the texture subimage.
21604 Specifies the format of the pixel data. The following symbolic values
21605 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
21606 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
21607 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
21608 @code{GL_LUMINANCE_ALPHA}.
21611 Specifies the data type of the pixel data. The following symbolic values
21612 are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
21613 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
21614 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
21615 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
21616 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
21617 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
21618 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
21619 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
21620 and @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
21623 Specifies a pointer to the image data in memory.
21627 Texturing maps a portion of a specified texture image onto each
21628 graphical primitive for which texturing is enabled. To enable or disable
21629 one-dimensional texturing, call @code{glEnable} and @code{glDisable}
21630 with argument @code{GL_TEXTURE_1D}.
21632 @code{glTexSubImage1D} redefines a contiguous subregion of an existing
21633 one-dimensional texture image. The texels referenced by @var{data}
21634 replace the portion of the existing texture array with x indices
21635 @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive. This
21636 region may not include any texels outside the range of the texture array
21637 as it was originally specified. It is not an error to specify a
21638 subtexture with width of 0, but such a specification has no effect.
21640 If a non-zero named buffer object is bound to the
21641 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
21642 texture image is specified, @var{data} is treated as a byte offset into
21643 the buffer object's data store.
21645 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
21648 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
21651 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
21654 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
21655 and @var{format} is not @code{GL_COLOR_INDEX}.
21657 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
21659 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
21660 @r{@var{log}_2}@var{max}, where @var{max} is the returned value of
21661 @code{GL_MAX_TEXTURE_SIZE}.
21663 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, or
21664 if @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, where
21665 @r{@var{w}} is the @code{GL_TEXTURE_WIDTH}, and @r{@var{b}} is the width
21666 of the @code{GL_TEXTURE_BORDER} of the texture image being modified.
21667 Note that @r{@var{w}} includes twice the border width.
21669 @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0.
21671 @code{GL_INVALID_OPERATION} is generated if the texture array has not
21672 been defined by a previous @code{glTexImage1D} operation.
21674 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21675 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
21676 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
21677 and @var{format} is not @code{GL_RGB}.
21679 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21680 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
21681 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
21682 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
21683 @code{GL_UNSIGNED_INT_10_10_10_2}, or
21684 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
21685 @code{GL_RGBA} nor @code{GL_BGRA}.
21687 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21688 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
21689 object's data store is currently mapped.
21691 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21692 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
21693 would be unpacked from the buffer object such that the memory reads
21694 required would exceed the data store size.
21696 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21697 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
21698 is not evenly divisible into the number of bytes needed to store in
21699 memory a datum indicated by @var{type}.
21701 @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage1D} is
21702 executed between the execution of @code{glBegin} and the corresponding
21703 execution of @code{glEnd}.
21707 @deftypefun void glTexSubImage2D target level xoffset yoffset width height format type data
21708 Specify a two-dimensional texture subimage.
21712 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
21713 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
21714 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
21715 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
21716 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
21717 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
21718 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
21721 Specifies the level-of-detail number. Level 0 is the base image level.
21722 Level @var{n} is the @var{n}th mipmap reduction image.
21724 @item @var{xoffset}
21725 Specifies a texel offset in the x direction within the texture array.
21727 @item @var{yoffset}
21728 Specifies a texel offset in the y direction within the texture array.
21731 Specifies the width of the texture subimage.
21734 Specifies the height of the texture subimage.
21737 Specifies the format of the pixel data. The following symbolic values
21738 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
21739 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
21740 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
21741 @code{GL_LUMINANCE_ALPHA}.
21744 Specifies the data type of the pixel data. The following symbolic values
21745 are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
21746 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
21747 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
21748 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
21749 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
21750 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
21751 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
21752 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
21753 and @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
21756 Specifies a pointer to the image data in memory.
21760 Texturing maps a portion of a specified texture image onto each
21761 graphical primitive for which texturing is enabled. To enable and
21762 disable two-dimensional texturing, call @code{glEnable} and
21763 @code{glDisable} with argument @code{GL_TEXTURE_2D}.
21765 @code{glTexSubImage2D} redefines a contiguous subregion of an existing
21766 two-dimensional texture image. The texels referenced by @var{data}
21767 replace the portion of the existing texture array with x indices
21768 @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive, and y
21769 indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive.
21770 This region may not include any texels outside the range of the texture
21771 array as it was originally specified. It is not an error to specify a
21772 subtexture with zero width or height, but such a specification has no
21775 If a non-zero named buffer object is bound to the
21776 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
21777 texture image is specified, @var{data} is treated as a byte offset into
21778 the buffer object's data store.
21780 @code{GL_INVALID_ENUM} is generated if @var{target} is not
21781 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
21782 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
21783 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
21784 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
21785 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
21786 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
21788 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
21791 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
21794 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
21795 and @var{format} is not @code{GL_COLOR_INDEX}.
21797 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
21799 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
21800 @r{@var{log}_2}@var{max}, where @var{max} is the returned value of
21801 @code{GL_MAX_TEXTURE_SIZE}.
21803 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}},
21804 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)},
21805 @r{@var{yoffset}<-@var{b}}, or
21806 @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, where @r{@var{w}}
21807 is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the
21808 @code{GL_TEXTURE_HEIGHT}, and @r{@var{b}} is the border width of the
21809 texture image being modified. Note that @r{@var{w}} and @r{@var{h}}
21810 include twice the border width.
21812 @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is
21815 @code{GL_INVALID_OPERATION} is generated if the texture array has not
21816 been defined by a previous @code{glTexImage2D} operation.
21818 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21819 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
21820 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
21821 and @var{format} is not @code{GL_RGB}.
21823 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21824 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
21825 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
21826 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
21827 @code{GL_UNSIGNED_INT_10_10_10_2}, or
21828 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
21829 @code{GL_RGBA} nor @code{GL_BGRA}.
21831 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21832 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
21833 object's data store is currently mapped.
21835 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21836 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
21837 would be unpacked from the buffer object such that the memory reads
21838 required would exceed the data store size.
21840 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21841 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
21842 is not evenly divisible into the number of bytes needed to store in
21843 memory a datum indicated by @var{type}.
21845 @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage2D} is
21846 executed between the execution of @code{glBegin} and the corresponding
21847 execution of @code{glEnd}.
21851 @deftypefun void glTexSubImage3D target level xoffset yoffset zoffset width height depth format type data
21852 Specify a three-dimensional texture subimage.
21856 Specifies the target texture. Must be @code{GL_TEXTURE_3D}.
21859 Specifies the level-of-detail number. Level 0 is the base image level.
21860 Level @var{n} is the @var{n}th mipmap reduction image.
21862 @item @var{xoffset}
21863 Specifies a texel offset in the x direction within the texture array.
21865 @item @var{yoffset}
21866 Specifies a texel offset in the y direction within the texture array.
21868 @item @var{zoffset}
21869 Specifies a texel offset in the z direction within the texture array.
21872 Specifies the width of the texture subimage.
21875 Specifies the height of the texture subimage.
21878 Specifies the depth of the texture subimage.
21881 Specifies the format of the pixel data. The following symbolic values
21882 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
21883 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
21884 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
21885 @code{GL_LUMINANCE_ALPHA}.
21888 Specifies the data type of the pixel data. The following symbolic values
21889 are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
21890 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
21891 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
21892 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
21893 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
21894 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
21895 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
21896 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
21897 and @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
21900 Specifies a pointer to the image data in memory.
21904 Texturing maps a portion of a specified texture image onto each
21905 graphical primitive for which texturing is enabled. To enable and
21906 disable three-dimensional texturing, call @code{glEnable} and
21907 @code{glDisable} with argument @code{GL_TEXTURE_3D}.
21909 @code{glTexSubImage3D} redefines a contiguous subregion of an existing
21910 three-dimensional texture image. The texels referenced by @var{data}
21911 replace the portion of the existing texture array with x indices
21912 @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive, y indices
21913 @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive, and z
21914 indices @var{zoffset} and @r{@var{zoffset}+@var{depth}-1}, inclusive.
21915 This region may not include any texels outside the range of the texture
21916 array as it was originally specified. It is not an error to specify a
21917 subtexture with zero width, height, or depth but such a specification
21920 If a non-zero named buffer object is bound to the
21921 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
21922 texture image is specified, @var{data} is treated as a byte offset into
21923 the buffer object's data store.
21925 @code{GL_INVALID_ENUM} is generated if /@var{target} is not
21926 @code{GL_TEXTURE_3D}.
21928 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
21931 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
21934 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
21935 and @var{format} is not @code{GL_COLOR_INDEX}.
21937 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
21939 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
21940 @r{@var{log}_2}@var{max}, where @var{max} is the returned value of
21941 @code{GL_MAX_TEXTURE_SIZE}.
21943 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}},
21944 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)},
21945 @r{@var{yoffset}<-@var{b}}, or
21946 @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, or
21947 @r{@var{zoffset}<-@var{b}}, or
21948 @r{(@var{zoffset}+@var{depth},)>(@var{d}-@var{b},)}, where @r{@var{w}}
21949 is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the
21950 @code{GL_TEXTURE_HEIGHT}, @r{@var{d}} is the @code{GL_TEXTURE_DEPTH} and
21951 @r{@var{b}} is the border width of the texture image being modified.
21952 Note that @r{@var{w}}, @r{@var{h}}, and @r{@var{d}} include twice the
21955 @code{GL_INVALID_VALUE} is generated if @var{width}, @var{height}, or
21956 @var{depth} is less than 0.
21958 @code{GL_INVALID_OPERATION} is generated if the texture array has not
21959 been defined by a previous @code{glTexImage3D} operation.
21961 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21962 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
21963 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
21964 and @var{format} is not @code{GL_RGB}.
21966 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21967 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
21968 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
21969 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
21970 @code{GL_UNSIGNED_INT_10_10_10_2}, or
21971 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
21972 @code{GL_RGBA} nor @code{GL_BGRA}.
21974 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21975 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
21976 object's data store is currently mapped.
21978 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21979 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
21980 would be unpacked from the buffer object such that the memory reads
21981 required would exceed the data store size.
21983 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21984 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
21985 is not evenly divisible into the number of bytes needed to store in
21986 memory a datum indicated by @var{type}.
21988 @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage3D} is
21989 executed between the execution of @code{glBegin} and the corresponding
21990 execution of @code{glEnd}.
21994 @deftypefun void glTranslatef x y z
21995 Multiply the current matrix by a translation matrix.
22001 Specify the @var{x}, @var{y}, and @var{z} coordinates of a translation
22006 @code{glTranslate} produces a translation by
22007 @r{(@var{x},@var{y}@var{z})}. The current matrix (see
22008 @code{glMatrixMode}) is multiplied by this translation matrix, with the
22009 product replacing the current matrix, as if @code{glMultMatrix} were
22010 called with the following matrix for its argument:
22012 @r{((1 0 0 @var{x}), (0 1 0 @var{y}), (0 0 1 @var{z}), (0 0 0 1),)}
22016 If the matrix mode is either @code{GL_MODELVIEW} or
22017 @code{GL_PROJECTION}, all objects drawn after a call to
22018 @code{glTranslate} are translated.
22020 Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the
22021 untranslated coordinate system.
22023 @code{GL_INVALID_OPERATION} is generated if @code{glTranslate} is
22024 executed between the execution of @code{glBegin} and the corresponding
22025 execution of @code{glEnd}.
22029 @deftypefun void glUniform1f location v0
22030 @deftypefunx void glUniform2f location v0 v1
22031 @deftypefunx void glUniform3f location v0 v1 v2
22032 @deftypefunx void glUniform4f location v0 v1 v2 v3
22033 @deftypefunx void glUniform1i location v0
22034 @deftypefunx void glUniform2i location v0 v1
22035 @deftypefunx void glUniform3i location v0 v1 v2
22036 @deftypefunx void glUniform4i location v0 v1 v2 v3
22037 @deftypefunx void glUniformMatrix2fv location count transpose value
22038 @deftypefunx void glUniformMatrix3fv location count transpose value
22039 @deftypefunx void glUniformMatrix4fv location count transpose value
22040 @deftypefunx void glUniformMatrix2x3fv location count transpose value
22041 @deftypefunx void glUniformMatrix3x2fv location count transpose value
22042 @deftypefunx void glUniformMatrix2x4fv location count transpose value
22043 @deftypefunx void glUniformMatrix4x2fv location count transpose value
22044 @deftypefunx void glUniformMatrix3x4fv location count transpose value
22045 @deftypefunx void glUniformMatrix4x3fv location count transpose value
22046 Specify the value of a uniform variable for the current program object.
22049 @item @var{location}
22050 Specifies the location of the uniform variable to be modified.
22052 @item @var{v0}, @var{v1}, @var{v2}, @var{v3}
22053 Specifies the new values to be used for the specified uniform variable.
22057 @code{glUniform} modifies the value of a uniform variable or a uniform
22058 variable array. The location of the uniform variable to be modified is
22059 specified by @var{location}, which should be a value returned by
22060 @code{glGetUniformLocation}. @code{glUniform} operates on the program
22061 object that was made part of current state by calling
22062 @code{glUseProgram}.
22064 The commands @code{glUniform@{1|2|3|4@}@{f|i@}} are used to change the
22065 value of the uniform variable specified by @var{location} using the
22066 values passed as arguments. The number specified in the command should
22067 match the number of components in the data type of the specified uniform
22068 variable (e.g., @code{1} for float, int, bool; @code{2} for vec2, ivec2,
22069 bvec2, etc.). The suffix @code{f} indicates that floating-point values
22070 are being passed; the suffix @code{i} indicates that integer values are
22071 being passed, and this type should also match the data type of the
22072 specified uniform variable. The @code{i} variants of this function
22073 should be used to provide values for uniform variables defined as int,
22074 ivec2, ivec3, ivec4, or arrays of these. The @code{f} variants should be
22075 used to provide values for uniform variables of type float, vec2, vec3,
22076 vec4, or arrays of these. Either the @code{i} or the @code{f} variants
22077 may be used to provide values for uniform variables of type bool, bvec2,
22078 bvec3, bvec4, or arrays of these. The uniform variable will be set to
22079 false if the input value is 0 or 0.0f, and it will be set to true
22082 All active uniform variables defined in a program object are initialized
22083 to 0 when the program object is linked successfully. They retain the
22084 values assigned to them by a call to @code{glUniform } until the next
22085 successful link operation occurs on the program object, when they are
22086 once again initialized to 0.
22088 The commands @code{glUniform@{1|2|3|4@}@{f|i@}v} can be used to modify a
22089 single uniform variable or a uniform variable array. These commands pass
22090 a count and a pointer to the values to be loaded into a uniform variable
22091 or a uniform variable array. A count of 1 should be used if modifying
22092 the value of a single uniform variable, and a count of 1 or greater can
22093 be used to modify an entire array or part of an array. When loading
22094 @var{n} elements starting at an arbitrary position @var{m} in a uniform
22095 variable array, elements @var{m} + @var{n} - 1 in the array will be
22096 replaced with the new values. If @var{m} + @var{n} - 1 is larger than
22097 the size of the uniform variable array, values for all array elements
22098 beyond the end of the array will be ignored. The number specified in the
22099 name of the command indicates the number of components for each element
22100 in @var{value}, and it should match the number of components in the data
22101 type of the specified uniform variable (e.g., @code{1} for float, int,
22102 bool; @code{2} for vec2, ivec2, bvec2, etc.). The data type specified in
22103 the name of the command must match the data type for the specified
22104 uniform variable as described previously for
22105 @code{glUniform@{1|2|3|4@}@{f|i@}}.
22107 For uniform variable arrays, each element of the array is considered to
22108 be of the type indicated in the name of the command (e.g.,
22109 @code{glUniform3f} or @code{glUniform3fv} can be used to load a uniform
22110 variable array of type vec3). The number of elements of the uniform
22111 variable array to be modified is specified by @var{count}
22113 The commands @code{glUniformMatrix@{2|3|4|2x3|3x2|2x4|4x2|3x4|4x3@}fv}
22114 are used to modify a matrix or an array of matrices. The numbers in the
22115 command name are interpreted as the dimensionality of the matrix. The
22116 number @code{2} indicates a 2 × 2 matrix (i.e., 4 values), the number
22117 @code{3} indicates a 3 × 3 matrix (i.e., 9 values), and the number
22118 @code{4} indicates a 4 × 4 matrix (i.e., 16 values). Non-square matrix
22119 dimensionality is explicit, with the first number representing the
22120 number of columns and the second number representing the number of rows.
22121 For example, @code{2x4} indicates a 2 × 4 matrix with 2 columns and 4
22122 rows (i.e., 8 values). If @var{transpose} is @code{GL_FALSE}, each
22123 matrix is assumed to be supplied in column major order. If
22124 @var{transpose} is @code{GL_TRUE}, each matrix is assumed to be supplied
22125 in row major order. The @var{count} argument indicates the number of
22126 matrices to be passed. A count of 1 should be used if modifying the
22127 value of a single matrix, and a count greater than 1 can be used to
22128 modify an array of matrices.
22130 @code{GL_INVALID_OPERATION} is generated if there is no current program
22133 @code{GL_INVALID_OPERATION} is generated if the size of the uniform
22134 variable declared in the shader does not match the size indicated by the
22135 @code{glUniform} command.
22137 @code{GL_INVALID_OPERATION} is generated if one of the integer variants
22138 of this function is used to load a uniform variable of type float, vec2,
22139 vec3, vec4, or an array of these, or if one of the floating-point
22140 variants of this function is used to load a uniform variable of type
22141 int, ivec2, ivec3, or ivec4, or an array of these.
22143 @code{GL_INVALID_OPERATION} is generated if @var{location} is an invalid
22144 uniform location for the current program object and @var{location} is
22147 @code{GL_INVALID_VALUE} is generated if @var{count} is less than 0.
22149 @code{GL_INVALID_OPERATION} is generated if @var{count} is greater than
22150 1 and the indicated uniform variable is not an array variable.
22152 @code{GL_INVALID_OPERATION} is generated if a sampler is loaded using a
22153 command other than @code{glUniform1i} and @code{glUniform1iv}.
22155 @code{GL_INVALID_OPERATION} is generated if @code{glUniform} is executed
22156 between the execution of @code{glBegin} and the corresponding execution
22161 @deftypefun void glUseProgram program
22162 Installs a program object as part of current rendering state.
22165 @item @var{program}
22166 Specifies the handle of the program object whose executables are to be
22167 used as part of current rendering state.
22171 @code{glUseProgram} installs the program object specified by
22172 @var{program} as part of current rendering state. One or more
22173 executables are created in a program object by successfully attaching
22174 shader objects to it with @code{glAttachShader}, successfully compiling
22175 the shader objects with @code{glCompileShader}, and successfully linking
22176 the program object with @code{glLinkProgram}.
22178 A program object will contain an executable that will run on the vertex
22179 processor if it contains one or more shader objects of type
22180 @code{GL_VERTEX_SHADER} that have been successfully compiled and linked.
22181 Similarly, a program object will contain an executable that will run on
22182 the fragment processor if it contains one or more shader objects of type
22183 @code{GL_FRAGMENT_SHADER} that have been successfully compiled and
22186 Successfully installing an executable on a programmable processor will
22187 cause the corresponding fixed functionality of OpenGL to be disabled.
22188 Specifically, if an executable is installed on the vertex processor, the
22189 OpenGL fixed functionality will be disabled as follows.
22193 The modelview matrix is not applied to vertex coordinates.
22196 The projection matrix is not applied to vertex coordinates.
22199 The texture matrices are not applied to texture coordinates.
22202 Normals are not transformed to eye coordinates.
22205 Normals are not rescaled or normalized.
22208 Normalization of @code{GL_AUTO_NORMAL} evaluated normals is not
22212 Texture coordinates are not generated automatically.
22215 Per-vertex lighting is not performed.
22218 Color material computations are not performed.
22221 Color index lighting is not performed.
22224 This list also applies when setting the current raster position.
22228 The executable that is installed on the vertex processor is expected to
22229 implement any or all of the desired functionality from the preceding
22230 list. Similarly, if an executable is installed on the fragment
22231 processor, the OpenGL fixed functionality will be disabled as follows.
22235 Texture environment and texture functions are not applied.
22238 Texture application is not applied.
22241 Color sum is not applied.
22244 Fog is not applied.
22248 Again, the fragment shader that is installed is expected to implement
22249 any or all of the desired functionality from the preceding list.
22251 While a program object is in use, applications are free to modify
22252 attached shader objects, compile attached shader objects, attach
22253 additional shader objects, and detach or delete shader objects. None of
22254 these operations will affect the executables that are part of the
22255 current state. However, relinking the program object that is currently
22256 in use will install the program object as part of the current rendering
22257 state if the link operation was successful (see @code{glLinkProgram} ).
22258 If the program object currently in use is relinked unsuccessfully, its
22259 link status will be set to @code{GL_FALSE}, but the executables and
22260 associated state will remain part of the current state until a
22261 subsequent call to @code{glUseProgram} removes it from use. After it is
22262 removed from use, it cannot be made part of current state until it has
22263 been successfully relinked.
22265 If @var{program} contains shader objects of type @code{GL_VERTEX_SHADER}
22266 but it does not contain shader objects of type
22267 @code{GL_FRAGMENT_SHADER}, an executable will be installed on the vertex
22268 processor, but fixed functionality will be used for fragment processing.
22269 Similarly, if @var{program} contains shader objects of type
22270 @code{GL_FRAGMENT_SHADER} but it does not contain shader objects of type
22271 @code{GL_VERTEX_SHADER}, an executable will be installed on the fragment
22272 processor, but fixed functionality will be used for vertex processing.
22273 If @var{program} is 0, the programmable processors will be disabled, and
22274 fixed functionality will be used for both vertex and fragment
22277 @code{GL_INVALID_VALUE} is generated if @var{program} is neither 0 nor a
22278 value generated by OpenGL.
22280 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
22283 @code{GL_INVALID_OPERATION} is generated if @var{program} could not be
22284 made part of current state.
22286 @code{GL_INVALID_OPERATION} is generated if @code{glUseProgram} is
22287 executed between the execution of @code{glBegin} and the corresponding
22288 execution of @code{glEnd}.
22292 @deftypefun void glValidateProgram program
22293 Validates a program object.
22296 @item @var{program}
22297 Specifies the handle of the program object to be validated.
22301 @code{glValidateProgram} checks to see whether the executables contained
22302 in @var{program} can execute given the current OpenGL state. The
22303 information generated by the validation process will be stored in
22304 @var{program}'s information log. The validation information may consist
22305 of an empty string, or it may be a string containing information about
22306 how the current program object interacts with the rest of current OpenGL
22307 state. This provides a way for OpenGL implementers to convey more
22308 information about why the current program is inefficient, suboptimal,
22309 failing to execute, and so on.
22311 The status of the validation operation will be stored as part of the
22312 program object's state. This value will be set to @code{GL_TRUE} if the
22313 validation succeeded, and @code{GL_FALSE} otherwise. It can be queried
22314 by calling @code{glGetProgram} with arguments @var{program} and
22315 @code{GL_VALIDATE_STATUS}. If validation is successful, @var{program} is
22316 guaranteed to execute given the current state. Otherwise, @var{program}
22317 is guaranteed to not execute.
22319 This function is typically useful only during application development.
22320 The informational string stored in the information log is completely
22321 implementation dependent; therefore, an application should not expect
22322 different OpenGL implementations to produce identical information
22325 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
22326 generated by OpenGL.
22328 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
22331 @code{GL_INVALID_OPERATION} is generated if @code{glValidateProgram} is
22332 executed between the execution of @code{glBegin} and the corresponding
22333 execution of @code{glEnd}.
22337 @deftypefun void glVertexAttribPointer index size type normalized stride pointer
22338 Define an array of generic vertex attribute data.
22342 Specifies the index of the generic vertex attribute to be modified.
22345 Specifies the number of components per generic vertex attribute. Must be
22346 1, 2, 3, or 4. The initial value is 4.
22349 Specifies the data type of each component in the array. Symbolic
22350 constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
22351 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
22352 @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is
22355 @item @var{normalized}
22356 Specifies whether fixed-point data values should be normalized
22357 (@code{GL_TRUE}) or converted directly as fixed-point values
22358 (@code{GL_FALSE}) when they are accessed.
22361 Specifies the byte offset between consecutive generic vertex attributes.
22362 If @var{stride} is 0, the generic vertex attributes are understood to be
22363 tightly packed in the array. The initial value is 0.
22365 @item @var{pointer}
22366 Specifies a pointer to the first component of the first generic vertex
22367 attribute in the array. The initial value is 0.
22371 @code{glVertexAttribPointer} specifies the location and data format of
22372 the array of generic vertex attributes at index @var{index} to use when
22373 rendering. @var{size} specifies the number of components per attribute
22374 and must be 1, 2, 3, or 4. @var{type} specifies the data type of each
22375 component, and @var{stride} specifies the byte stride from one attribute
22376 to the next, allowing vertices and attributes to be packed into a single
22377 array or stored in separate arrays. If set to @code{GL_TRUE},
22378 @var{normalized} indicates that values stored in an integer format are
22379 to be mapped to the range [-1,1] (for signed values) or [0,1] (for
22380 unsigned values) when they are accessed and converted to floating point.
22381 Otherwise, values will be converted to floats directly without
22384 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
22385 target (see @code{glBindBuffer}) while a generic vertex attribute array
22386 is specified, @var{pointer} is treated as a byte offset into the buffer
22387 object's data store. Also, the buffer object binding
22388 (@code{GL_ARRAY_BUFFER_BINDING}) is saved as generic vertex attribute
22389 array client-side state (@code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING})
22390 for index @var{index}.
22392 When a generic vertex attribute array is specified, @var{size},
22393 @var{type}, @var{normalized}, @var{stride}, and @var{pointer} are saved
22394 as client-side state, in addition to the current vertex array buffer
22397 To enable and disable a generic vertex attribute array, call
22398 @code{glEnableVertexAttribArray} and @code{glDisableVertexAttribArray}
22399 with @var{index}. If enabled, the generic vertex attribute array is used
22400 when @code{glArrayElement}, @code{glDrawArrays},
22401 @code{glMultiDrawArrays}, @code{glDrawElements},
22402 @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called.
22404 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
22405 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
22407 @code{GL_INVALID_VALUE} is generated if @var{size} is not 1, 2, 3, or 4.
22409 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
22412 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
22416 @deftypefun void glVertexAttrib1f index v0
22417 @deftypefunx void glVertexAttrib1s index v0
22418 @deftypefunx void glVertexAttrib2f index v0 v1
22419 @deftypefunx void glVertexAttrib2s index v0 v1
22420 @deftypefunx void glVertexAttrib3f index v0 v1 v2
22421 @deftypefunx void glVertexAttrib3s index v0 v1 v2
22422 @deftypefunx void glVertexAttrib4f index v0 v1 v2 v3
22423 @deftypefunx void glVertexAttrib4s index v0 v1 v2 v3
22424 @deftypefunx void glVertexAttrib4Nub index v0 v1 v2 v3
22425 @deftypefunx void glVertexAttrib4iv index v
22426 @deftypefunx void glVertexAttrib4uiv index v
22427 @deftypefunx void glVertexAttrib4Niv index v
22428 @deftypefunx void glVertexAttrib4Nuiv index v
22429 Specifies the value of a generic vertex attribute.
22433 Specifies the index of the generic vertex attribute to be modified.
22435 @item @var{v0}, @var{v1}, @var{v2}, @var{v3}
22436 Specifies the new values to be used for the specified vertex attribute.
22440 OpenGL defines a number of standard vertex attributes that applications
22441 can modify with standard API entry points (color, normal, texture
22442 coordinates, etc.). The @code{glVertexAttrib} family of entry points
22443 allows an application to pass generic vertex attributes in numbered
22446 Generic attributes are defined as four-component values that are
22447 organized into an array. The first entry of this array is numbered 0,
22448 and the size of the array is specified by the implementation-dependent
22449 constant @code{GL_MAX_VERTEX_ATTRIBS}. Individual elements of this array
22450 can be modified with a @code{glVertexAttrib} call that specifies the
22451 index of the element to be modified and a value for that element.
22453 These commands can be used to specify one, two, three, or all four
22454 components of the generic vertex attribute specified by @var{index}. A
22455 @code{1} in the name of the command indicates that only one value is
22456 passed, and it will be used to modify the first component of the generic
22457 vertex attribute. The second and third components will be set to 0, and
22458 the fourth component will be set to 1. Similarly, a @code{2} in the name
22459 of the command indicates that values are provided for the first two
22460 components, the third component will be set to 0, and the fourth
22461 component will be set to 1. A @code{3} in the name of the command
22462 indicates that values are provided for the first three components and
22463 the fourth component will be set to 1, whereas a @code{4} in the name
22464 indicates that values are provided for all four components.
22466 The letters @code{s}, @code{f}, @code{i}, @code{d}, @code{ub},
22467 @code{us}, and @code{ui} indicate whether the arguments are of type
22468 short, float, int, double, unsigned byte, unsigned short, or unsigned
22469 int. When @code{v} is appended to the name, the commands can take a
22470 pointer to an array of such values. The commands containing @code{N}
22471 indicate that the arguments will be passed as fixed-point values that
22472 are scaled to a normalized range according to the component conversion
22473 rules defined by the OpenGL specification. Signed values are understood
22474 to represent fixed-point values in the range [-1,1], and unsigned values
22475 are understood to represent fixed-point values in the range [0,1].
22477 OpenGL Shading Language attribute variables are allowed to be of type
22478 mat2, mat3, or mat4. Attributes of these types may be loaded using the
22479 @code{glVertexAttrib} entry points. Matrices must be loaded into
22480 successive generic attribute slots in column major order, with one
22481 column of the matrix in each generic attribute slot.
22483 A user-defined attribute variable declared in a vertex shader can be
22484 bound to a generic attribute index by calling
22485 @code{glBindAttribLocation}. This allows an application to use more
22486 descriptive variable names in a vertex shader. A subsequent change to
22487 the specified generic vertex attribute will be immediately reflected as
22488 a change to the corresponding attribute variable in the vertex shader.
22490 The binding between a generic vertex attribute index and a user-defined
22491 attribute variable in a vertex shader is part of the state of a program
22492 object, but the current value of the generic vertex attribute is not.
22493 The value of each generic vertex attribute is part of current state,
22494 just like standard vertex attributes, and it is maintained even if a
22495 different program object is used.
22497 An application may freely modify generic vertex attributes that are not
22498 bound to a named vertex shader attribute variable. These values are
22499 simply maintained as part of current state and will not be accessed by
22500 the vertex shader. If a generic vertex attribute bound to an attribute
22501 variable in a vertex shader is not updated while the vertex shader is
22502 executing, the vertex shader will repeatedly use the current value for
22503 the generic vertex attribute.
22505 The generic vertex attribute with index 0 is the same as the vertex
22506 position attribute previously defined by OpenGL. A @code{glVertex2},
22507 @code{glVertex3}, or @code{glVertex4} command is completely equivalent
22508 to the corresponding @code{glVertexAttrib} command with an index
22509 argument of 0. A vertex shader can access generic vertex attribute 0 by
22510 using the built-in attribute variable @var{gl_Vertex}. There are no
22511 current values for generic vertex attribute 0. This is the only generic
22512 vertex attribute with this property; calls to set other standard vertex
22513 attributes can be freely mixed with calls to set any of the other
22514 generic vertex attributes.
22516 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
22517 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
22521 @deftypefun void glVertexPointer size type stride pointer
22522 Define an array of vertex data.
22526 Specifies the number of coordinates per vertex. Must be 2, 3, or 4. The
22527 initial value is 4.
22530 Specifies the data type of each coordinate in the array. Symbolic
22531 constants @code{GL_SHORT}, @code{GL_INT}, @code{GL_FLOAT}, or
22532 @code{GL_DOUBLE} are accepted. The initial value is @code{GL_FLOAT}.
22535 Specifies the byte offset between consecutive vertices. If @var{stride}
22536 is 0, the vertices are understood to be tightly packed in the array. The
22537 initial value is 0.
22539 @item @var{pointer}
22540 Specifies a pointer to the first coordinate of the first vertex in the
22541 array. The initial value is 0.
22545 @code{glVertexPointer} specifies the location and data format of an
22546 array of vertex coordinates to use when rendering. @var{size} specifies
22547 the number of coordinates per vertex, and must be 2, 3, or 4. @var{type}
22548 specifies the data type of each coordinate, and @var{stride} specifies
22549 the byte stride from one vertex to the next, allowing vertices and
22550 attributes to be packed into a single array or stored in separate
22551 arrays. (Single-array storage may be more efficient on some
22552 implementations; see @code{glInterleavedArrays}.)
22554 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
22555 target (see @code{glBindBuffer}) while a vertex array is specified,
22556 @var{pointer} is treated as a byte offset into the buffer object's data
22557 store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING})
22558 is saved as vertex array client-side state
22559 (@code{GL_VERTEX_ARRAY_BUFFER_BINDING}).
22561 When a vertex array is specified, @var{size}, @var{type}, @var{stride},
22562 and @var{pointer} are saved as client-side state, in addition to the
22563 current vertex array buffer object binding.
22565 To enable and disable the vertex array, call @code{glEnableClientState}
22566 and @code{glDisableClientState} with the argument
22567 @code{GL_VERTEX_ARRAY}. If enabled, the vertex array is used when
22568 @code{glArrayElement}, @code{glDrawArrays}, @code{glMultiDrawArrays},
22569 @code{glDrawElements}, @code{glMultiDrawElements}, or
22570 @code{glDrawRangeElements} is called.
22572 @code{GL_INVALID_VALUE} is generated if @var{size} is not 2, 3, or 4.
22574 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
22577 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
22581 @deftypefun void glVertex2i x y
22582 @deftypefunx void glVertex2f x y
22583 @deftypefunx void glVertex3i x y z
22584 @deftypefunx void glVertex3f x y z
22585 @deftypefunx void glVertex4i x y z w
22586 @deftypefunx void glVertex4f x y z w
22594 Specify @var{x}, @var{y}, @var{z}, and @var{w} coordinates of a vertex.
22595 Not all parameters are present in all forms of the command.
22599 @code{glVertex} commands are used within @code{glBegin}/@code{glEnd}
22600 pairs to specify point, line, and polygon vertices. The current color,
22601 normal, texture coordinates, and fog coordinate are associated with the
22602 vertex when @code{glVertex} is called.
22604 When only @r{@var{x}} and @r{@var{y}} are specified, @r{@var{z}}
22605 defaults to 0 and @r{@var{w}} defaults to 1. When @r{@var{x}},
22606 @r{@var{y}}, and @r{@var{z}} are specified, @r{@var{w}} defaults to 1.
22610 @deftypefun void glViewport x y width height
22616 Specify the lower left corner of the viewport rectangle, in pixels. The
22617 initial value is (0,0).
22620 @itemx @var{height}
22621 Specify the width and height of the viewport. When a GL context is first
22622 attached to a window, @var{width} and @var{height} are set to the
22623 dimensions of that window.
22627 @code{glViewport} specifies the affine transformation of @r{@var{x}} and
22628 @r{@var{y}} from normalized device coordinates to window coordinates.
22629 Let @r{(@var{x}_@var{nd},@var{y}_@var{nd})} be normalized device
22630 coordinates. Then the window coordinates
22631 @r{(@var{x}_@var{w},@var{y}_@var{w})} are computed as follows:
22633 @r{@var{x}_@var{w}=(@var{x}_@var{nd}+1,)(@var{width}/2,)+@var{x}}
22635 @r{@var{y}_@var{w}=(@var{y}_@var{nd}+1,)(@var{height}/2,)+@var{y}}
22637 Viewport width and height are silently clamped to a range that depends
22638 on the implementation. To query this range, call @code{glGet} with
22639 argument @code{GL_MAX_VIEWPORT_DIMS}.
22641 @code{GL_INVALID_VALUE} is generated if either @var{width} or
22642 @var{height} is negative.
22644 @code{GL_INVALID_OPERATION} is generated if @code{glViewport} is
22645 executed between the execution of @code{glBegin} and the corresponding
22646 execution of @code{glEnd}.
22650 @deftypefun void glWindowPos2i x y
22651 @deftypefunx void glWindowPos2f x y
22652 @deftypefunx void glWindowPos3i x y z
22653 @deftypefunx void glWindowPos3f x y z
22654 Specify the raster position in window coordinates for pixel operations.
22660 Specify the @r{@var{x}}, @r{@var{y}}, @r{@var{z}} coordinates for the
22665 The GL maintains a 3D position in window coordinates. This position,
22666 called the raster position, is used to position pixel and bitmap write
22667 operations. It is maintained with subpixel accuracy. See
22668 @code{glBitmap}, @code{glDrawPixels}, and @code{glCopyPixels}.
22670 @code{glWindowPos2} specifies the @r{@var{x}} and @r{@var{y}}
22671 coordinates, while @r{@var{z}} is implicitly set to 0.
22672 @code{glWindowPos3} specifies all three coordinates. The @r{@var{w}}
22673 coordinate of the current raster position is always set to 1.0.
22675 @code{glWindowPos} directly updates the @r{@var{x}} and @r{@var{y}}
22676 coordinates of the current raster position with the values specified.
22677 That is, the values are neither transformed by the current modelview and
22678 projection matrices, nor by the viewport-to-window transform. The
22679 @r{@var{z}} coordinate of the current raster position is updated in the
22682 @r{@var{z}=@{(@var{n}), (@var{f}),
22683 (@var{n}+@var{z}×(@var{f}-@var{n},),)(@var{if}@var{z}<=0),
22684 (@var{if}@var{z}>=1), (@code{otherwise},),}
22688 where @r{@var{n}} is @code{GL_DEPTH_RANGE}'s near value, and @r{@var{f}}
22689 is @code{GL_DEPTH_RANGE}'s far value. See @code{glDepthRange}.
22691 The specified coordinates are not clip-tested, causing the raster
22692 position to always be valid.
22694 The current raster position also includes some associated color data and
22695 texture coordinates. If lighting is enabled, then
22696 @code{GL_CURRENT_RASTER_COLOR} (in RGBA mode) or
22697 @code{GL_CURRENT_RASTER_INDEX} (in color index mode) is set to the color
22698 produced by the lighting calculation (see @code{glLight},
22699 @code{glLightModel}, and @code{glShadeModel}). If lighting is disabled,
22700 current color (in RGBA mode, state variable @code{GL_CURRENT_COLOR}) or
22701 color index (in color index mode, state variable
22702 @code{GL_CURRENT_INDEX}) is used to update the current raster color.
22703 @code{GL_CURRENT_RASTER_SECONDARY_COLOR} (in RGBA mode) is likewise
22706 Likewise, @code{GL_CURRENT_RASTER_TEXTURE_COORDS} is updated as a
22707 function of @code{GL_CURRENT_TEXTURE_COORDS}, based on the texture
22708 matrix and the texture generation functions (see @code{glTexGen}). The
22709 @code{GL_CURRENT_RASTER_DISTANCE} is set to the
22710 @code{GL_CURRENT_FOG_COORD}.
22714 @code{GL_INVALID_OPERATION} is generated if @code{glWindowPos} is
22715 executed between the execution of @code{glBegin} and the corresponding
22716 execution of @code{glEnd}.
22721 @c %end of fragment