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
17 is 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
65 of 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
79 in 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
143 units is implementation dependent, but must be at least two.
144 @var{texture} must be one of @code{GL_TEXTURE}@r{@var{i}}, where i
145 ranges from 0 to 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
178 the 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
188 @code{glEnable} 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
195 made to the frame buffer at that pixel location. The comparison
196 functions are as follows:
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
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
403 @code{glEndQuery} is executed, the samples-passed counter is assigned to
404 the query 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
451 single argument that specifies in which of ten ways the vertices are
452 interpreted. Taking @r{@var{n}} as an integer count starting at one,
453 and @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
594 attribute variable is passed as a null terminated string in @var{name}.
595 The generic vertex attribute index to be bound to this variable is
596 specified by @var{index}. When @var{program} is made part of current
597 state, values provided via the generic vertex attribute @var{index} will
598 modify the value of the user-defined attribute variable specified by
601 If @var{name} refers to a matrix attribute variable, @var{index} refers
602 to the first column of the matrix. Other matrix columns are then
603 automatically bound to locations @var{index+1} for a matrix of type
604 mat2; @var{index+1} and @var{index+2} for a matrix of type mat3; and
605 @var{index+1}, @var{index+2}, and @var{index+3} for a matrix of type
608 This command makes it possible for vertex shaders to use descriptive
609 names for attribute variables rather than generic variables that are
610 numbered from 0 to @code{GL_MAX_VERTEX_ATTRIBS} -1. The values sent to
611 each generic attribute index are part of current state, just like
612 standard vertex attributes such as color, normal, and vertex position.
613 If a different program object is made current by calling
614 @code{glUseProgram}, the generic vertex attributes are tracked in such a
615 way that the same values will be observed by attributes in the new
616 program object that are also bound to @var{index}.
618 Attribute variable name-to-generic attribute index bindings for a
619 program object can be explicitly assigned at any time by calling
620 @code{glBindAttribLocation}. Attribute bindings do not go into effect
621 until @code{glLinkProgram} is called. After a program object has been
622 linked successfully, the index values for generic attributes remain
623 fixed (and their values can be queried) until the next link command
626 Applications are not allowed to bind any of the standard OpenGL vertex
627 attributes using this command, as they are bound automatically when
628 needed. Any attribute binding that occurs after the program object has
629 been linked will not take effect until the next time the program object
632 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
633 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
635 @code{GL_INVALID_OPERATION} is generated if @var{name} starts with the
636 reserved prefix "gl_".
638 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
641 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
644 @code{GL_INVALID_OPERATION} is generated if @code{glBindAttribLocation}
645 is executed between the execution of @code{glBegin} and the
646 corresponding execution of @code{glEnd}.
650 @deftypefun void glBindBuffer target buffer
651 Bind a named buffer object.
655 Specifies the target to which the buffer object is bound. The symbolic
656 constant must be @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
657 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
660 Specifies the name of a buffer object.
664 @code{glBindBuffer} lets you create or use a named buffer object.
665 Calling @code{glBindBuffer} with @var{target} set to
666 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
667 @code{GL_PIXEL_PACK_BUFFER} or @code{GL_PIXEL_UNPACK_BUFFER} and
668 @var{buffer} set to the name of the new buffer object binds the buffer
669 object name to the target. When a buffer object is bound to a target,
670 the previous binding for that target is automatically broken.
672 Buffer object names are unsigned integers. The value zero is reserved,
673 but there is no default buffer object for each buffer object target.
674 Instead, @var{buffer} set to zero effectively unbinds any buffer object
675 previously bound, and restores client memory usage for that buffer
676 object target. Buffer object names and the corresponding buffer object
677 contents are local to the shared display-list space (see
678 @code{glXCreateContext}) of the current GL rendering context; two
679 rendering contexts share buffer object names only if they also share
682 You may use @code{glGenBuffers} to generate a set of new buffer object
685 The state of a buffer object immediately after it is first bound is an
686 unmapped zero-sized memory buffer with @code{GL_READ_WRITE} access and
687 @code{GL_STATIC_DRAW} usage.
689 While a non-zero buffer object name is bound, GL operations on the
690 target to which it is bound affect the bound buffer object, and queries
691 of the target to which it is bound return state from the bound buffer
692 object. While buffer object name zero is bound, as in the initial
693 state, attempts to modify or query state on the target to which it is
694 bound generates an @code{GL_INVALID_OPERATION} error.
696 When vertex array pointer state is changed, for example by a call to
697 @code{glNormalPointer}, the current buffer object binding
698 (@code{GL_ARRAY_BUFFER_BINDING}) is copied into the corresponding client
699 state for the vertex array type being changed, for example
700 @code{GL_NORMAL_ARRAY_BUFFER_BINDING}. While a non-zero buffer object
701 is bound to the @code{GL_ARRAY_BUFFER} target, the vertex array pointer
702 parameter that is traditionally interpreted as a pointer to client-side
703 memory is instead interpreted as an offset within the buffer object
704 measured in basic machine units.
706 While a non-zero buffer object is bound to the
707 @code{GL_ELEMENT_ARRAY_BUFFER} target, the indices parameter of
708 @code{glDrawElements}, @code{glDrawRangeElements}, or
709 @code{glMultiDrawElements} that is traditionally interpreted as a
710 pointer to client-side memory is instead interpreted as an offset within
711 the buffer object measured in basic machine units.
713 While a non-zero buffer object is bound to the
714 @code{GL_PIXEL_PACK_BUFFER} target, the following commands are affected:
715 @code{glGetCompressedTexImage}, @code{glGetConvolutionFilter},
716 @code{glGetHistogram}, @code{glGetMinmax}, @code{glGetPixelMap},
717 @code{glGetPolygonStipple}, @code{glGetSeparableFilter},
718 @code{glGetTexImage}, and @code{glReadPixels}. The pointer parameter
719 that is traditionally interpreted as a pointer to client-side memory
720 where the pixels are to be packed is instead interpreted as an offset
721 within the buffer object measured in basic machine units.
723 While a non-zero buffer object is bound to the
724 @code{GL_PIXEL_UNPACK_BUFFER} target, the following commands are
725 affected: @code{glBitmap}, @code{glColorSubTable}, @code{glColorTable},
726 @code{glCompressedTexImage1D}, @code{glCompressedTexImage2D},
727 @code{glCompressedTexImage3D}, @code{glCompressedTexSubImage1D},
728 @code{glCompressedTexSubImage2D}, @code{glCompressedTexSubImage3D},
729 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D},
730 @code{glDrawPixels}, @code{glPixelMap}, @code{glPolygonStipple},
731 @code{glSeparableFilter2D}, @code{glTexImage1D}, @code{glTexImage2D},
732 @code{glTexImage3D}, @code{glTexSubImage1D}, @code{glTexSubImage2D}, and
733 @code{glTexSubImage3D}. The pointer parameter that is traditionally
734 interpreted as a pointer to client-side memory from which the pixels are
735 to be unpacked is instead interpreted as an offset within the buffer
736 object measured in basic machine units.
738 A buffer object binding created with @code{glBindBuffer} remains active
739 until a different buffer object name is bound to the same target, or
740 until the bound buffer object is deleted with @code{glDeleteBuffers}.
742 Once created, a named buffer object may be re-bound to any target as
743 often as needed. However, the GL implementation may make choices about
744 how to optimize the storage of a buffer object based on its initial
747 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
750 @code{GL_INVALID_OPERATION} is generated if @code{glBindBuffer} is
751 executed between the execution of @code{glBegin} and the corresponding
752 execution of @code{glEnd}.
756 @deftypefun void glBindTexture target texture
757 Bind a named texture to a texturing target.
761 Specifies the target to which the texture is bound. Must be either
762 @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, or
763 @code{GL_TEXTURE_CUBE_MAP}.
766 Specifies the name of a texture.
770 @code{glBindTexture} lets you create or use a named texture. Calling
771 @code{glBindTexture} with @var{target} set to @code{GL_TEXTURE_1D},
772 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D} or @code{GL_TEXTURE_CUBE_MAP}
773 and @var{texture} set to the name of the new texture binds the texture
774 name to the target. When a texture is bound to a target, the previous
775 binding for that target is automatically broken.
777 Texture names are unsigned integers. The value zero is reserved to
778 represent the default texture for each texture target. Texture names
779 and the corresponding texture contents are local to the shared
780 display-list space (see @code{glXCreateContext}) of the current GL
781 rendering context; two rendering contexts share texture names only if
782 they also share display lists.
784 You may use @code{glGenTextures} to generate a set of new texture names.
786 When a texture is first bound, it assumes the specified target: A
787 texture first bound to @code{GL_TEXTURE_1D} becomes one-dimensional
788 texture, a texture first bound to @code{GL_TEXTURE_2D} becomes
789 two-dimensional texture, a texture first bound to @code{GL_TEXTURE_3D}
790 becomes three-dimensional texture, and a texture first bound to
791 @code{GL_TEXTURE_CUBE_MAP} becomes a cube-mapped texture. The state of
792 a one-dimensional texture immediately after it is first bound is
793 equivalent to the state of the default @code{GL_TEXTURE_1D} at GL
794 initialization, and similarly for two- and three-dimensional textures
795 and cube-mapped textures.
797 While a texture is bound, GL operations on the target to which it is
798 bound affect the bound texture, and queries of the target to which it is
799 bound return state from the bound texture. If texture mapping is active
800 on the target to which a texture is bound, the bound texture is used. In
801 effect, the texture targets become aliases for the textures currently
802 bound to them, and the texture name zero refers to the default textures
803 that were bound to them at initialization.
805 A texture binding created with @code{glBindTexture} remains active until
806 a different texture is bound to the same target, or until the bound
807 texture is deleted with @code{glDeleteTextures}.
809 Once created, a named texture may be re-bound to its same original
810 target as often as needed. It is usually much faster to use
811 @code{glBindTexture} to bind an existing named texture to one of the
812 texture targets than it is to reload the texture image using
813 @code{glTexImage1D}, @code{glTexImage2D}, or @code{glTexImage3D}. For
814 additional control over performance, use @code{glPrioritizeTextures}.
816 @code{glBindTexture} is included in display lists.
818 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
821 @code{GL_INVALID_OPERATION} is generated if @var{texture} was previously
822 created with a target that doesn't match that of @var{target}.
824 @code{GL_INVALID_OPERATION} is generated if @code{glBindTexture} is
825 executed between the execution of @code{glBegin} and the corresponding
826 execution of @code{glEnd}.
830 @deftypefun void glBitmap width height xorig yorig xmove ymove bitmap
836 Specify the pixel width and height of the bitmap image.
840 Specify the location of the origin in the bitmap image. The origin is
841 measured from the lower left corner of the bitmap, with right and up
842 being the positive axes.
846 Specify the @var{x} and @var{y} offsets to be added to the current
847 raster position after the bitmap is drawn.
850 Specifies the address of the bitmap image.
854 A bitmap is a binary image. When drawn, the bitmap is positioned
855 relative to the current raster position, and frame buffer pixels
856 corresponding to 1's in the bitmap are written using the current raster
857 color or index. Frame buffer pixels corresponding to 0's in the bitmap
860 @code{glBitmap} takes seven arguments. The first pair specifies the
861 width and height of the bitmap image. The second pair specifies the
862 location of the bitmap origin relative to the lower left corner of the
863 bitmap image. The third pair of arguments specifies @var{x} and @var{y}
864 offsets to be added to the current raster position after the bitmap has
865 been drawn. The final argument is a pointer to the bitmap image itself.
867 If a non-zero named buffer object is bound to the
868 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
869 bitmap image is specified, @var{bitmap} is treated as a byte offset into
870 the buffer object's data store.
872 The bitmap image is interpreted like image data for the
873 @code{glDrawPixels} command, with @var{width} and @var{height}
874 corresponding to the width and height arguments of that command, and
875 with @var{type} set to @code{GL_BITMAP} and @var{format} set to
876 @code{GL_COLOR_INDEX}. Modes specified using @code{glPixelStore} affect
877 the interpretation of bitmap image data; modes specified using
878 @code{glPixelTransfer} do not.
880 If the current raster position is invalid, @code{glBitmap} is ignored.
881 Otherwise, the lower left corner of the bitmap image is positioned at
882 the window coordinates
884 @r{@var{x}_@var{w}=⌊@var{x}_@var{r}-@var{x}_@var{o},⌋}
886 @r{@var{y}_@var{w}=⌊@var{y}_@var{r}-@var{y}_@var{o},⌋}
888 where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the raster position and
889 @r{(@var{x}_@var{o},@var{y}_@var{o})} is the bitmap origin. Fragments
890 are then generated for each pixel corresponding to a 1 (one) in the
891 bitmap image. These fragments are generated using the current raster
892 @var{z} coordinate, color or color index, and current raster texture
893 coordinates. They are then treated just as if they had been generated
894 by a point, line, or polygon, including texture mapping, fogging, and
895 all per-fragment operations such as alpha and depth testing.
897 After the bitmap has been drawn, the @var{x} and @var{y} coordinates of
898 the current raster position are offset by @var{xmove} and @var{ymove}.
899 No change is made to the @var{z} coordinate of the current raster
900 position, or to the current raster color, texture coordinates, or index.
902 @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is
905 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
906 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
907 object's data store is currently mapped.
909 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
910 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
911 would be unpacked from the buffer object such that the memory reads
912 required would exceed the data store size.
914 @code{GL_INVALID_OPERATION} is generated if @code{glBitmap} is executed
915 between the execution of @code{glBegin} and the corresponding execution
920 @deftypefun void glBlendColor red green blue alpha
928 specify the components of @code{GL_BLEND_COLOR}
932 The @code{GL_BLEND_COLOR} may be used to calculate the source and
933 destination blending factors. The color components are clamped to the
934 range @r{[0,1]} before being stored. See @code{glBlendFunc} for a
935 complete description of the blending operations. Initially the
936 @code{GL_BLEND_COLOR} is set to (0, 0, 0, 0).
938 @code{GL_INVALID_OPERATION} is generated if @code{glBlendColor} is
939 executed between the execution of @code{glBegin} and the corresponding
940 execution of @code{glEnd}.
946 @deftypefun void glBlendEquationSeparate modeRGB modeAlpha
947 Set the RGB blend equation and the alpha blend equation separately.
951 specifies the RGB blend equation, how the red, green, and blue
952 components of the source and destination colors are combined. It must
953 be @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT},
954 @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN}, @code{GL_MAX}.
956 @item @var{modeAlpha}
957 specifies the alpha blend equation, how the alpha component of the
958 source and destination colors are combined. It must be
959 @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT},
960 @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN}, @code{GL_MAX}.
964 The blend equations determines how a new pixel (the ''source'' color) is
965 combined with a pixel already in the framebuffer (the ''destination''
966 color). This function specifies one blend equation for the RGB-color
967 components and one blend equation for the alpha component.
969 The blend equations use the source and destination blend factors
970 specified by either @code{glBlendFunc} or @code{glBlendFuncSeparate}.
971 See @code{glBlendFunc} or @code{glBlendFuncSeparate} for a description
972 of the various blend factors.
974 In the equations that follow, source and destination color components
976 @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and
977 @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})},
978 respectively. The result color is referred to as
979 @r{(@var{R}_@var{r},@var{G}_@var{r}@var{B}_@var{r}@var{A}_@var{r})}. The
980 source and destination blend factors are denoted
981 @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and
982 @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})},
983 respectively. For these equations all color components are understood
984 to have values in the range @r{[0,1]}.
988 @strong{RGB Components}, @strong{Alpha Component}
990 @item @code{GL_FUNC_ADD}
991 @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}},
992 @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}+@var{A}_@var{d}@var{d}_@var{A}}
994 @item @code{GL_FUNC_SUBTRACT}
995 @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}},
996 @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}-@var{A}_@var{d}@var{d}_@var{A}}
998 @item @code{GL_FUNC_REVERSE_SUBTRACT}
999 @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}},
1000 @r{@var{Ar}=@var{A}_@var{d}@var{d}_@var{A}-@var{A}_@var{s}@var{s}_@var{A}}
1003 @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})},
1004 @r{@var{Ar}=@var{min}(@var{A}_@var{s},@var{A}_@var{d})}
1007 @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})},
1008 @r{@var{Ar}=@var{max}(@var{A}_@var{s},@var{A}_@var{d})}
1012 The results of these equations are clamped to the range @r{[0,1]}.
1014 The @code{GL_MIN} and @code{GL_MAX} equations are useful for
1015 applications that analyze image data (image thresholding against a
1016 constant color, for example). The @code{GL_FUNC_ADD} equation is useful
1017 for antialiasing and transparency, among other things.
1019 Initially, both the RGB blend equation and the alpha blend equation are
1020 set to @code{GL_FUNC_ADD}.
1024 @code{GL_INVALID_ENUM} is generated if either @var{modeRGB} or
1025 @var{modeAlpha} is not one of @code{GL_FUNC_ADD},
1026 @code{GL_FUNC_SUBTRACT}, @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MAX},
1029 @code{GL_INVALID_OPERATION} is generated if
1030 @code{glBlendEquationSeparate} is executed between the execution of
1031 @code{glBegin} and the corresponding execution of @code{glEnd}.
1035 @deftypefun void glBlendEquation mode
1036 Specify the equation used for both the RGB blend equation and the Alpha
1041 specifies how source and destination colors are combined. It must be
1042 @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT},
1043 @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN}, @code{GL_MAX}.
1047 The blend equations determine how a new pixel (the ''source'' color) is
1048 combined with a pixel already in the framebuffer (the ''destination''
1049 color). This function sets both the RGB blend equation and the alpha
1050 blend equation to a single equation.
1052 These equations use the source and destination blend factors specified
1053 by either @code{glBlendFunc} or @code{glBlendFuncSeparate}. See
1054 @code{glBlendFunc} or @code{glBlendFuncSeparate} for a description of
1055 the various blend factors.
1057 In the equations that follow, source and destination color components
1059 @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and
1060 @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})},
1061 respectively. The result color is referred to as
1062 @r{(@var{R}_@var{r},@var{G}_@var{r}@var{B}_@var{r}@var{A}_@var{r})}. The
1063 source and destination blend factors are denoted
1064 @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and
1065 @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})},
1066 respectively. For these equations all color components are understood
1067 to have values in the range @r{[0,1]}.
1071 @strong{RGB Components}, @strong{Alpha Component}
1073 @item @code{GL_FUNC_ADD}
1074 @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}},
1075 @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}+@var{A}_@var{d}@var{d}_@var{A}}
1077 @item @code{GL_FUNC_SUBTRACT}
1078 @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}},
1079 @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}-@var{A}_@var{d}@var{d}_@var{A}}
1081 @item @code{GL_FUNC_REVERSE_SUBTRACT}
1082 @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}},
1083 @r{@var{Ar}=@var{A}_@var{d}@var{d}_@var{A}-@var{A}_@var{s}@var{s}_@var{A}}
1086 @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})},
1087 @r{@var{Ar}=@var{min}(@var{A}_@var{s},@var{A}_@var{d})}
1090 @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})},
1091 @r{@var{Ar}=@var{max}(@var{A}_@var{s},@var{A}_@var{d})}
1095 The results of these equations are clamped to the range @r{[0,1]}.
1097 The @code{GL_MIN} and @code{GL_MAX} equations are useful for
1098 applications that analyze image data (image thresholding against a
1099 constant color, for example). The @code{GL_FUNC_ADD} equation is useful
1100 for antialiasing and transparency, among other things.
1102 Initially, both the RGB blend equation and the alpha blend equation are
1103 set to @code{GL_FUNC_ADD}.
1107 @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of
1108 @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT},
1109 @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MAX}, or @code{GL_MIN}.
1111 @code{GL_INVALID_OPERATION} is generated if @code{glBlendEquation} is
1112 executed between the execution of @code{glBegin} and the corresponding
1113 execution of @code{glEnd}.
1117 @deftypefun void glBlendFuncSeparate srcRGB dstRGB srcAlpha dstAlpha
1118 Specify pixel arithmetic for RGB and alpha components separately.
1122 Specifies how the red, green, and blue blending factors are computed.
1123 The following symbolic constants are accepted: @code{GL_ZERO},
1124 @code{GL_ONE}, @code{GL_SRC_COLOR}, @code{GL_ONE_MINUS_SRC_COLOR},
1125 @code{GL_DST_COLOR}, @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA},
1126 @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA},
1127 @code{GL_ONE_MINUS_DST_ALPHA}, @code{GL_CONSTANT_COLOR},
1128 @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA},
1129 @code{GL_ONE_MINUS_CONSTANT_ALPHA}, and @code{GL_SRC_ALPHA_SATURATE}.
1130 The initial value is @code{GL_ONE}.
1133 Specifies how the red, green, and blue destination blending factors are
1134 computed. The following symbolic constants are accepted:
1135 @code{GL_ZERO}, @code{GL_ONE}, @code{GL_SRC_COLOR},
1136 @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_DST_COLOR},
1137 @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA},
1138 @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA},
1139 @code{GL_ONE_MINUS_DST_ALPHA}. @code{GL_CONSTANT_COLOR},
1140 @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA}, and
1141 @code{GL_ONE_MINUS_CONSTANT_ALPHA}. The initial value is
1144 @item @var{srcAlpha}
1145 Specified how the alpha source blending factor is computed. The same
1146 symbolic constants are accepted as for @var{srcRGB}. The initial value
1149 @item @var{dstAlpha}
1150 Specified how the alpha destination blending factor is computed. The
1151 same symbolic constants are accepted as for @var{dstRGB}. The initial
1152 value is @code{GL_ZERO}.
1156 In RGBA mode, pixels can be drawn using a function that blends the
1157 incoming (source) RGBA values with the RGBA values that are already in
1158 the frame buffer (the destination values). Blending is initially
1159 disabled. Use @code{glEnable} and @code{glDisable} with argument
1160 @code{GL_BLEND} to enable and disable blending.
1162 @code{glBlendFuncSeparate} defines the operation of blending when it is
1163 enabled. @var{srcRGB} specifies which method is used to scale the
1164 source RGB-color components. @var{dstRGB} specifies which method is
1165 used to scale the destination RGB-color components. Likewise,
1166 @var{srcAlpha} specifies which method is used to scale the source alpha
1167 color component, and @var{dstAlpha} specifies which method is used to
1168 scale the destination alpha component. The possible methods are
1169 described in the following table. Each method defines four scale
1170 factors, one each for red, green, blue, and alpha.
1172 In the table and in subsequent equations, source and destination color
1173 components are referred to as
1174 @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and
1175 @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})}. The
1176 color specified by @code{glBlendColor} is referred to as
1177 @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})}.
1178 They are understood to have integer values between 0 and
1179 @r{(@var{k}_@var{R},@var{k}_@var{G}@var{k}_@var{B}@var{k}_@var{A})},
1182 @r{@var{k}_@var{c}=2^@var{m}_@var{c},-1}
1184 and @r{(@var{m}_@var{R},@var{m}_@var{G}@var{m}_@var{B}@var{m}_@var{A})}
1185 is the number of red, green, blue, and alpha bitplanes.
1187 Source and destination scale factors are referred to as
1188 @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and
1189 @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})}. All
1190 scale factors have range @r{[0,1]}.
1195 @item @strong{Parameter}
1196 @strong{RGB Factor}, @strong{Alpha Factor}
1198 @item @code{GL_ZERO}
1204 @item @code{GL_SRC_COLOR}
1205 @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})},
1206 @r{@var{A}_@var{s}/@var{k}_@var{A}}
1208 @item @code{GL_ONE_MINUS_SRC_COLOR}
1209 @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})},
1210 @r{1-@var{A}_@var{s}/@var{k}_@var{A}}
1212 @item @code{GL_DST_COLOR}
1213 @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})},
1214 @r{@var{A}_@var{d}/@var{k}_@var{A}}
1216 @item @code{GL_ONE_MINUS_DST_COLOR}
1217 @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})},
1218 @r{1-@var{A}_@var{d}/@var{k}_@var{A}}
1220 @item @code{GL_SRC_ALPHA}
1221 @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})},
1222 @r{@var{A}_@var{s}/@var{k}_@var{A}}
1224 @item @code{GL_ONE_MINUS_SRC_ALPHA}
1225 @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})},
1226 @r{1-@var{A}_@var{s}/@var{k}_@var{A}}
1228 @item @code{GL_DST_ALPHA}
1229 @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})},
1230 @r{@var{A}_@var{d}/@var{k}_@var{A}}
1232 @item @code{GL_ONE_MINUS_DST_ALPHA}
1233 @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})},
1234 @r{1-@var{A}_@var{d}/@var{k}_@var{A}}
1236 @item @code{GL_CONSTANT_COLOR}
1237 @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c})},
1240 @item @code{GL_ONE_MINUS_CONSTANT_COLOR}
1241 @r{(1,11)-(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c})},
1242 @r{1-@var{A}_@var{c}}
1244 @item @code{GL_CONSTANT_ALPHA}
1245 @r{(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c})},
1248 @item @code{GL_ONE_MINUS_CONSTANT_ALPHA}
1249 @r{(1,11)-(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c})},
1250 @r{1-@var{A}_@var{c}}
1252 @item @code{GL_SRC_ALPHA_SATURATE}
1253 @r{(@var{i},@var{i}@var{i})}, @r{1}
1259 @r{@var{i}=@var{min}(@var{A}_@var{s},1-@var{A}_@var{d},)}
1261 To determine the blended RGBA values of a pixel when drawing in RGBA
1262 mode, the system uses the following equations:
1264 @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})}
1266 Despite the apparent precision of the above equations, blending
1267 arithmetic is not exactly specified, because blending operates with
1268 imprecise integer color values. However, a blend factor that should be
1269 equal to 1 is guaranteed not to modify its multiplicand, and a blend
1270 factor equal to 0 reduces its multiplicand to 0. For example, when
1271 @var{srcRGB} is @code{GL_SRC_ALPHA}, @var{dstRGB} is
1272 @code{GL_ONE_MINUS_SRC_ALPHA}, and @r{@var{A}_@var{s}} is equal to
1273 @r{@var{k}_@var{A}}, the equations reduce to simple replacement:
1275 @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}}
1279 @code{GL_INVALID_ENUM} is generated if either @var{srcRGB} or
1280 @var{dstRGB} is not an accepted value.
1282 @code{GL_INVALID_OPERATION} is generated if @code{glBlendFuncSeparate}
1283 is executed between the execution of @code{glBegin} and the
1284 corresponding execution of @code{glEnd}.
1288 @deftypefun void glBlendFunc sfactor dfactor
1289 Specify pixel arithmetic.
1293 Specifies how the red, green, blue, and alpha source blending factors
1294 are computed. The following symbolic constants are accepted:
1295 @code{GL_ZERO}, @code{GL_ONE}, @code{GL_SRC_COLOR},
1296 @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_DST_COLOR},
1297 @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA},
1298 @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA},
1299 @code{GL_ONE_MINUS_DST_ALPHA}, @code{GL_CONSTANT_COLOR},
1300 @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA},
1301 @code{GL_ONE_MINUS_CONSTANT_ALPHA}, and @code{GL_SRC_ALPHA_SATURATE}.
1302 The initial value is @code{GL_ONE}.
1305 Specifies how the red, green, blue, and alpha destination blending
1306 factors are computed. The following symbolic constants are accepted:
1307 @code{GL_ZERO}, @code{GL_ONE}, @code{GL_SRC_COLOR},
1308 @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_DST_COLOR},
1309 @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA},
1310 @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA},
1311 @code{GL_ONE_MINUS_DST_ALPHA}. @code{GL_CONSTANT_COLOR},
1312 @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA}, and
1313 @code{GL_ONE_MINUS_CONSTANT_ALPHA}. The initial value is
1318 In RGBA mode, pixels can be drawn using a function that blends the
1319 incoming (source) RGBA values with the RGBA values that are already in
1320 the frame buffer (the destination values). Blending is initially
1321 disabled. Use @code{glEnable} and @code{glDisable} with argument
1322 @code{GL_BLEND} to enable and disable blending.
1324 @code{glBlendFunc} defines the operation of blending when it is enabled.
1325 @var{sfactor} specifies which method is used to scale the source color
1326 components. @var{dfactor} specifies which method is used to scale the
1327 destination color components. The possible methods are described in the
1328 following table. Each method defines four scale factors, one each for
1329 red, green, blue, and alpha. In the table and in subsequent equations,
1330 source and destination color components are referred to as
1331 @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and
1332 @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})}. The
1333 color specified by @code{glBlendColor} is referred to as
1334 @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})}.
1335 They are understood to have integer values between 0 and
1336 @r{(@var{k}_@var{R},@var{k}_@var{G}@var{k}_@var{B}@var{k}_@var{A})},
1339 @r{@var{k}_@var{c}=2^@var{m}_@var{c},-1}
1341 and @r{(@var{m}_@var{R},@var{m}_@var{G}@var{m}_@var{B}@var{m}_@var{A})}
1342 is the number of red, green, blue, and alpha bitplanes.
1344 Source and destination scale factors are referred to as
1345 @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and
1346 @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})}. The
1347 scale factors described in the table, denoted
1348 @r{(@var{f}_@var{R},@var{f}_@var{G}@var{f}_@var{B}@var{f}_@var{A})},
1349 represent either source or destination factors. All scale factors have
1355 @item @strong{Parameter}
1356 @strong{@r{(@var{f}_@var{R},@var{f}_@var{G}@var{f}_@var{B}@var{f}_@var{A})}}
1358 @item @code{GL_ZERO}
1364 @item @code{GL_SRC_COLOR}
1365 @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})}
1367 @item @code{GL_ONE_MINUS_SRC_COLOR}
1368 @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})}
1370 @item @code{GL_DST_COLOR}
1371 @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})}
1373 @item @code{GL_ONE_MINUS_DST_COLOR}
1374 @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})}
1376 @item @code{GL_SRC_ALPHA}
1377 @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})}
1379 @item @code{GL_ONE_MINUS_SRC_ALPHA}
1380 @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})}
1382 @item @code{GL_DST_ALPHA}
1383 @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})}
1385 @item @code{GL_ONE_MINUS_DST_ALPHA}
1386 @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})}
1388 @item @code{GL_CONSTANT_COLOR}
1389 @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})}
1391 @item @code{GL_ONE_MINUS_CONSTANT_COLOR}
1392 @r{(1,111)-(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})}
1394 @item @code{GL_CONSTANT_ALPHA}
1395 @r{(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c}@var{A}_@var{c})}
1397 @item @code{GL_ONE_MINUS_CONSTANT_ALPHA}
1398 @r{(1,111)-(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c}@var{A}_@var{c})}
1400 @item @code{GL_SRC_ALPHA_SATURATE}
1401 @r{(@var{i},@var{i}@var{i}1)}
1407 @r{@var{i}=@var{min}(@var{A}_@var{s},@var{k}_@var{A}-@var{A}_@var{d})/@var{k}_@var{A}}
1409 To determine the blended RGBA values of a pixel when drawing in RGBA
1410 mode, the system uses the following equations:
1412 @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})}
1414 Despite the apparent precision of the above equations, blending
1415 arithmetic is not exactly specified, because blending operates with
1416 imprecise integer color values. However, a blend factor that should be
1417 equal to 1 is guaranteed not to modify its multiplicand, and a blend
1418 factor equal to 0 reduces its multiplicand to 0. For example, when
1419 @var{sfactor} is @code{GL_SRC_ALPHA}, @var{dfactor} is
1420 @code{GL_ONE_MINUS_SRC_ALPHA}, and @r{@var{A}_@var{s}} is equal to
1421 @r{@var{k}_@var{A}}, the equations reduce to simple replacement:
1423 @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}}
1427 @code{GL_INVALID_ENUM} is generated if either @var{sfactor} or
1428 @var{dfactor} is not an accepted value.
1430 @code{GL_INVALID_OPERATION} is generated if @code{glBlendFunc} is
1431 executed between the execution of @code{glBegin} and the corresponding
1432 execution of @code{glEnd}.
1436 @deftypefun void glBufferData target size data usage
1437 Creates and initializes a buffer object's data store.
1441 Specifies the target buffer object. The symbolic constant must be
1442 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
1443 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
1446 Specifies the size in bytes of the buffer object's new data store.
1449 Specifies a pointer to data that will be copied into the data store for
1450 initialization, or @code{NULL} if no data is to be copied.
1453 Specifies the expected usage pattern of the data store. The symbolic
1454 constant must be @code{GL_STREAM_DRAW}, @code{GL_STREAM_READ},
1455 @code{GL_STREAM_COPY}, @code{GL_STATIC_DRAW}, @code{GL_STATIC_READ},
1456 @code{GL_STATIC_COPY}, @code{GL_DYNAMIC_DRAW}, @code{GL_DYNAMIC_READ},
1457 or @code{GL_DYNAMIC_COPY}.
1461 @code{glBufferData} creates a new data store for the buffer object
1462 currently bound to @var{target}. Any pre-existing data store is
1463 deleted. The new data store is created with the specified @var{size} in
1464 bytes and @var{usage}. If @var{data} is not @code{NULL}, the data store
1465 is initialized with data from this pointer. In its initial state, the
1466 new data store is not mapped, it has a @code{NULL} mapped pointer, and
1467 its mapped access is @code{GL_READ_WRITE}.
1469 @var{usage} is a hint to the GL implementation as to how a buffer
1470 object's data store will be accessed. This enables the GL
1471 implementation to make more intelligent decisions that may significantly
1472 impact buffer object performance. It does not, however, constrain the
1473 actual usage of the data store. @var{usage} can be broken down into two
1474 parts: first, the frequency of access (modification and usage), and
1475 second, the nature of that access. The frequency of access may be one
1480 The data store contents will be modified once and used at most a few
1484 The data store contents will be modified once and used many times.
1487 The data store contents will be modified repeatedly and used many times.
1491 The nature of access may be one of these:
1495 The data store contents are modified by the application, and used as the
1496 source for GL drawing and image specification commands.
1499 The data store contents are modified by reading data from the GL, and
1500 used to return that data when queried by the application.
1503 The data store contents are modified by reading data from the GL, and
1504 used as the source for GL drawing and image specification commands.
1508 @code{GL_INVALID_ENUM} is generated if @var{target} is not
1509 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
1510 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
1512 @code{GL_INVALID_ENUM} is generated if @var{usage} is not
1513 @code{GL_STREAM_DRAW}, @code{GL_STREAM_READ}, @code{GL_STREAM_COPY},
1514 @code{GL_STATIC_DRAW}, @code{GL_STATIC_READ}, @code{GL_STATIC_COPY},
1515 @code{GL_DYNAMIC_DRAW}, @code{GL_DYNAMIC_READ}, or
1516 @code{GL_DYNAMIC_COPY}.
1518 @code{GL_INVALID_VALUE} is generated if @var{size} is negative.
1520 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
1521 name 0 is bound to @var{target}.
1523 @code{GL_OUT_OF_MEMORY} is generated if the GL is unable to create a
1524 data store with the specified @var{size}.
1526 @code{GL_INVALID_OPERATION} is generated if @code{glBufferData} is
1527 executed between the execution of @code{glBegin} and the corresponding
1528 execution of @code{glEnd}.
1532 @deftypefun void glBufferSubData target offset size data
1533 Updates a subset of a buffer object's data store.
1537 Specifies the target buffer object. The symbolic constant must be
1538 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
1539 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
1542 Specifies the offset into the buffer object's data store where data
1543 replacement will begin, measured in bytes.
1546 Specifies the size in bytes of the data store region being replaced.
1549 Specifies a pointer to the new data that will be copied into the data
1554 @code{glBufferSubData} redefines some or all of the data store for the
1555 buffer object currently bound to @var{target}. Data starting at byte
1556 offset @var{offset} and extending for @var{size} bytes is copied to the
1557 data store from the memory pointed to by @var{data}. An error is thrown
1558 if @var{offset} and @var{size} together define a range beyond the bounds
1559 of the buffer object's data store.
1561 @code{GL_INVALID_ENUM} is generated if @var{target} is not
1562 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
1563 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
1565 @code{GL_INVALID_VALUE} is generated if @var{offset} or @var{size} is
1566 negative, or if together they define a region of memory that extends
1567 beyond the buffer object's allocated data store.
1569 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
1570 name 0 is bound to @var{target}.
1572 @code{GL_INVALID_OPERATION} is generated if the buffer object being
1575 @code{GL_INVALID_OPERATION} is generated if @code{glBufferSubData} is
1576 executed between the execution of @code{glBegin} and the corresponding
1577 execution of @code{glEnd}.
1581 @deftypefun void glCallLists n type lists
1582 Execute a list of display lists.
1586 Specifies the number of display lists to be executed.
1589 Specifies the type of values in @var{lists}. Symbolic constants
1590 @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
1591 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
1592 @code{GL_FLOAT}, @code{GL_2_BYTES}, @code{GL_3_BYTES}, and
1593 @code{GL_4_BYTES} are accepted.
1596 Specifies the address of an array of name offsets in the display list.
1597 The pointer type is void because the offsets can be bytes, shorts, ints,
1598 or floats, depending on the value of @var{type}.
1602 @code{glCallLists} causes each display list in the list of names passed
1603 as @var{lists} to be executed. As a result, the commands saved in each
1604 display list are executed in order, just as if they were called without
1605 using a display list. Names of display lists that have not been defined
1608 @code{glCallLists} provides an efficient means for executing more than
1609 one display list. @var{type} allows lists with various name formats to
1610 be accepted. The formats are as follows:
1613 @item @code{GL_BYTE}
1614 @var{lists} is treated as an array of signed bytes, each in the range
1615 @r{-128} through 127.
1617 @item @code{GL_UNSIGNED_BYTE}
1618 @var{lists} is treated as an array of unsigned bytes, each in the range
1621 @item @code{GL_SHORT}
1622 @var{lists} is treated as an array of signed two-byte integers, each in
1623 the range @r{-32768} through 32767.
1625 @item @code{GL_UNSIGNED_SHORT}
1626 @var{lists} is treated as an array of unsigned two-byte integers, each
1627 in the range 0 through 65535.
1630 @var{lists} is treated as an array of signed four-byte integers.
1632 @item @code{GL_UNSIGNED_INT}
1633 @var{lists} is treated as an array of unsigned four-byte integers.
1635 @item @code{GL_FLOAT}
1636 @var{lists} is treated as an array of four-byte floating-point values.
1638 @item @code{GL_2_BYTES}
1639 @var{lists} is treated as an array of unsigned bytes. Each pair of
1640 bytes specifies a single display-list name. The value of the pair is
1641 computed as 256 times the unsigned value of the first byte plus the
1642 unsigned value of the second byte.
1644 @item @code{GL_3_BYTES}
1645 @var{lists} is treated as an array of unsigned bytes. Each triplet of
1646 bytes specifies a single display-list name. The value of the triplet is
1647 computed as 65536 times the unsigned value of the first byte, plus 256
1648 times the unsigned value of the second byte, plus the unsigned value of
1651 @item @code{GL_4_BYTES}
1652 @var{lists} is treated as an array of unsigned bytes. Each quadruplet
1653 of bytes specifies a single display-list name. The value of the
1654 quadruplet is computed as 16777216 times the unsigned value of the first
1655 byte, plus 65536 times the unsigned value of the second byte, plus 256
1656 times the unsigned value of the third byte, plus the unsigned value of
1661 The list of display-list names is not null-terminated. Rather, @var{n}
1662 specifies how many names are to be taken from @var{lists}.
1664 An additional level of indirection is made available with the
1665 @code{glListBase} command, which specifies an unsigned offset that is
1666 added to each display-list name specified in @var{lists} before that
1667 display list is executed.
1669 @code{glCallLists} can appear inside a display list. To avoid the
1670 possibility of infinite recursion resulting from display lists calling
1671 one another, a limit is placed on the nesting level of display lists
1672 during display-list execution. This limit must be at least 64, and it
1673 depends on the implementation.
1675 GL state is not saved and restored across a call to @code{glCallLists}.
1676 Thus, changes made to GL state during the execution of the display lists
1677 remain after execution is completed. Use @code{glPushAttrib},
1678 @code{glPopAttrib}, @code{glPushMatrix}, and @code{glPopMatrix} to
1679 preserve GL state across @code{glCallLists} calls.
1681 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
1683 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of
1684 @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
1685 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
1686 @code{GL_FLOAT}, @code{GL_2_BYTES}, @code{GL_3_BYTES},
1691 @deftypefun void glCallList list
1692 Execute a display list.
1696 Specifies the integer name of the display list to be executed.
1700 @code{glCallList} causes the named display list to be executed. The
1701 commands saved in the display list are executed in order, just as if
1702 they were called without using a display list. If @var{list} has not
1703 been defined as a display list, @code{glCallList} is ignored.
1705 @code{glCallList} can appear inside a display list. To avoid the
1706 possibility of infinite recursion resulting from display lists calling
1707 one another, a limit is placed on the nesting level of display lists
1708 during display-list execution. This limit is at least 64, and it
1709 depends on the implementation.
1711 GL state is not saved and restored across a call to @code{glCallList}.
1712 Thus, changes made to GL state during the execution of a display list
1713 remain after execution of the display list is completed. Use
1714 @code{glPushAttrib}, @code{glPopAttrib}, @code{glPushMatrix}, and
1715 @code{glPopMatrix} to preserve GL state across @code{glCallList} calls.
1719 @deftypefun void glClearAccum red green blue alpha
1720 Specify clear values for the accumulation buffer.
1727 Specify the red, green, blue, and alpha values used when the
1728 accumulation buffer is cleared. The initial values are all 0.
1732 @code{glClearAccum} specifies the red, green, blue, and alpha values
1733 used by @code{glClear} to clear the accumulation buffer.
1735 Values specified by @code{glClearAccum} are clamped to the range
1738 @code{GL_INVALID_OPERATION} is generated if @code{glClearAccum} is
1739 executed between the execution of @code{glBegin} and the corresponding
1740 execution of @code{glEnd}.
1744 @deftypefun void glClearColor red green blue alpha
1745 Specify clear values for the color buffers.
1752 Specify the red, green, blue, and alpha values used when the color
1753 buffers are cleared. The initial values are all 0.
1757 @code{glClearColor} specifies the red, green, blue, and alpha values
1758 used by @code{glClear} to clear the color buffers. Values specified by
1759 @code{glClearColor} are clamped to the range @r{[0,1]}.
1761 @code{GL_INVALID_OPERATION} is generated if @code{glClearColor} is
1762 executed between the execution of @code{glBegin} and the corresponding
1763 execution of @code{glEnd}.
1767 @deftypefun void glClearDepth depth
1768 Specify the clear value for the depth buffer.
1772 Specifies the depth value used when the depth buffer is cleared. The
1777 @code{glClearDepth} specifies the depth value used by @code{glClear} to
1778 clear the depth buffer. Values specified by @code{glClearDepth} are
1779 clamped to the range @r{[0,1]}.
1781 @code{GL_INVALID_OPERATION} is generated if @code{glClearDepth} is
1782 executed between the execution of @code{glBegin} and the corresponding
1783 execution of @code{glEnd}.
1787 @deftypefun void glClearIndex c
1788 Specify the clear value for the color index buffers.
1792 Specifies the index used when the color index buffers are cleared. The
1797 @code{glClearIndex} specifies the index used by @code{glClear} to clear
1798 the color index buffers. @var{c} is not clamped. Rather, @var{c} is
1799 converted to a fixed-point value with unspecified precision to the right
1800 of the binary point. The integer part of this value is then masked with
1801 @r{2^@var{m}-1}, where @r{@var{m}} is the number of bits in a color
1802 index stored in the frame buffer.
1804 @code{GL_INVALID_OPERATION} is generated if @code{glClearIndex} is
1805 executed between the execution of @code{glBegin} and the corresponding
1806 execution of @code{glEnd}.
1810 @deftypefun void glClearStencil s
1811 Specify the clear value for the stencil buffer.
1815 Specifies the index used when the stencil buffer is cleared. The
1820 @code{glClearStencil} specifies the index used by @code{glClear} to
1821 clear the stencil buffer. @var{s} is masked with @r{2^@var{m}-1}, where
1822 @r{@var{m}} is the number of bits in the stencil buffer.
1824 @code{GL_INVALID_OPERATION} is generated if @code{glClearStencil} is
1825 executed between the execution of @code{glBegin} and the corresponding
1826 execution of @code{glEnd}.
1830 @deftypefun void glClear mask
1831 Clear buffers to preset values.
1835 Bitwise OR of masks that indicate the buffers to be cleared. The four
1836 masks are @code{GL_COLOR_BUFFER_BIT}, @code{GL_DEPTH_BUFFER_BIT},
1837 @code{GL_ACCUM_BUFFER_BIT}, and @code{GL_STENCIL_BUFFER_BIT}.
1841 @code{glClear} sets the bitplane area of the window to values previously
1842 selected by @code{glClearColor}, @code{glClearIndex},
1843 @code{glClearDepth}, @code{glClearStencil}, and @code{glClearAccum}.
1844 Multiple color buffers can be cleared simultaneously by selecting more
1845 than one buffer at a time using @code{glDrawBuffer}.
1847 The pixel ownership test, the scissor test, dithering, and the buffer
1848 writemasks affect the operation of @code{glClear}. The scissor box
1849 bounds the cleared region. Alpha function, blend function, logical
1850 operation, stenciling, texture mapping, and depth-buffering are ignored
1853 @code{glClear} takes a single argument that is the bitwise OR of several
1854 values indicating which buffer is to be cleared.
1856 The values are as follows:
1859 @item @code{GL_COLOR_BUFFER_BIT}
1860 Indicates the buffers currently enabled for color writing.
1862 @item @code{GL_DEPTH_BUFFER_BIT}
1863 Indicates the depth buffer.
1865 @item @code{GL_ACCUM_BUFFER_BIT}
1866 Indicates the accumulation buffer.
1868 @item @code{GL_STENCIL_BUFFER_BIT}
1869 Indicates the stencil buffer.
1873 The value to which each buffer is cleared depends on the setting of the
1874 clear value for that buffer.
1876 @code{GL_INVALID_VALUE} is generated if any bit other than the four
1877 defined bits is set in @var{mask}.
1879 @code{GL_INVALID_OPERATION} is generated if @code{glClear} is executed
1880 between the execution of @code{glBegin} and the corresponding execution
1885 @deftypefun void glClientActiveTexture texture
1886 Select active texture unit.
1890 Specifies which texture unit to make active. The number of texture
1891 units is implementation dependent, but must be at least two.
1892 @var{texture} must be one of @code{GL_TEXTURE}@r{@var{i}}, where i
1893 ranges from 0 to the value of @code{GL_MAX_TEXTURE_COORDS} - 1, which is
1894 an implementation-dependent value. The initial value is
1899 @code{glClientActiveTexture} selects the vertex array client state
1900 parameters to be modified by @code{glTexCoordPointer}, and enabled or
1901 disabled with @code{glEnableClientState} or @code{glDisableClientState},
1902 respectively, when called with a parameter of
1903 @code{GL_TEXTURE_COORD_ARRAY}.
1905 @code{GL_INVALID_ENUM} is generated if @var{texture} is not one of
1906 @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to the value of
1907 @code{GL_MAX_TEXTURE_COORDS} - 1.
1911 @deftypefun void glClipPlane plane equation
1912 Specify a plane against which all geometry is clipped.
1916 Specifies which clipping plane is being positioned. Symbolic names of
1917 the form @code{GL_CLIP_PLANE}@var{i}, where @var{i} is an integer
1918 between 0 and @code{GL_MAX_CLIP_PLANES}@r{-1}, are accepted.
1920 @item @var{equation}
1921 Specifies the address of an array of four double-precision
1922 floating-point values. These values are interpreted as a plane
1927 Geometry is always clipped against the boundaries of a six-plane frustum
1928 in @var{x}, @var{y}, and @var{z}. @code{glClipPlane} allows the
1929 specification of additional planes, not necessarily perpendicular to the
1930 @var{x}, @var{y}, or @var{z} axis, against which all geometry is
1931 clipped. To determine the maximum number of additional clipping planes,
1932 call @code{glGetIntegerv} with argument @code{GL_MAX_CLIP_PLANES}. All
1933 implementations support at least six such clipping planes. Because the
1934 resulting clipping region is the intersection of the defined
1935 half-spaces, it is always convex.
1937 @code{glClipPlane} specifies a half-space using a four-component plane
1938 equation. When @code{glClipPlane} is called, @var{equation} is
1939 transformed by the inverse of the modelview matrix and stored in the
1940 resulting eye coordinates. Subsequent changes to the modelview matrix
1941 have no effect on the stored plane-equation components. If the dot
1942 product of the eye coordinates of a vertex with the stored plane
1943 equation components is positive or zero, the vertex is @var{in} with
1944 respect to that clipping plane. Otherwise, it is @var{out}.
1946 To enable and disable clipping planes, call @code{glEnable} and
1947 @code{glDisable} with the argument @code{GL_CLIP_PLANE}@var{i}, where
1948 @var{i} is the plane number.
1950 All clipping planes are initially defined as (0, 0, 0, 0) in eye
1951 coordinates and are disabled.
1953 @code{GL_INVALID_ENUM} is generated if @var{plane} is not an accepted
1956 @code{GL_INVALID_OPERATION} is generated if @code{glClipPlane} is
1957 executed between the execution of @code{glBegin} and the corresponding
1958 execution of @code{glEnd}.
1962 @deftypefun void glColorMask red green blue alpha
1963 Enable and disable writing of frame buffer color components.
1970 Specify whether red, green, blue, and alpha can or cannot be written
1971 into the frame buffer. The initial values are all @code{GL_TRUE},
1972 indicating that the color components can be written.
1976 @code{glColorMask} specifies whether the individual color components in
1977 the frame buffer can or cannot be written. If @var{red} is
1978 @code{GL_FALSE}, for example, no change is made to the red component of
1979 any pixel in any of the color buffers, regardless of the drawing
1980 operation attempted.
1982 Changes to individual bits of components cannot be controlled. Rather,
1983 changes are either enabled or disabled for entire color components.
1985 @code{GL_INVALID_OPERATION} is generated if @code{glColorMask} is
1986 executed between the execution of @code{glBegin} and the corresponding
1987 execution of @code{glEnd}.
1991 @deftypefun void glColorMaterial face mode
1992 Cause a material color to track the current color.
1996 Specifies whether front, back, or both front and back material
1997 parameters should track the current color. Accepted values are
1998 @code{GL_FRONT}, @code{GL_BACK}, and @code{GL_FRONT_AND_BACK}. The
1999 initial value is @code{GL_FRONT_AND_BACK}.
2002 Specifies which of several material parameters track the current color.
2003 Accepted values are @code{GL_EMISSION}, @code{GL_AMBIENT},
2004 @code{GL_DIFFUSE}, @code{GL_SPECULAR}, and
2005 @code{GL_AMBIENT_AND_DIFFUSE}. The initial value is
2006 @code{GL_AMBIENT_AND_DIFFUSE}.
2010 @code{glColorMaterial} specifies which material parameters track the
2011 current color. When @code{GL_COLOR_MATERIAL} is enabled, the material
2012 parameter or parameters specified by @var{mode}, of the material or
2013 materials specified by @var{face}, track the current color at all times.
2015 To enable and disable @code{GL_COLOR_MATERIAL}, call @code{glEnable} and
2016 @code{glDisable} with argument @code{GL_COLOR_MATERIAL}.
2017 @code{GL_COLOR_MATERIAL} is initially disabled.
2019 @code{GL_INVALID_ENUM} is generated if @var{face} or @var{mode} is not
2022 @code{GL_INVALID_OPERATION} is generated if @code{glColorMaterial} is
2023 executed between the execution of @code{glBegin} and the corresponding
2024 execution of @code{glEnd}.
2028 @deftypefun void glColorPointer size type stride pointer
2029 Define an array of colors.
2033 Specifies the number of components per color. Must be 3 or 4. The
2037 Specifies the data type of each color component in the array. Symbolic
2038 constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
2039 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
2040 @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value
2044 Specifies the byte offset between consecutive colors. If @var{stride}
2045 is 0, the colors are understood to be tightly packed in the array. The
2049 Specifies a pointer to the first component of the first color element in
2050 the array. The initial value is 0.
2054 @code{glColorPointer} specifies the location and data format of an array
2055 of color components to use when rendering. @var{size} specifies the
2056 number of components per color, and must be 3 or 4. @var{type}
2057 specifies the data type of each color component, and @var{stride}
2058 specifies the byte stride from one color to the next, allowing vertices
2059 and attributes to be packed into a single array or stored in separate
2060 arrays. (Single-array storage may be more efficient on some
2061 implementations; see @code{glInterleavedArrays}.)
2063 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
2064 target (see @code{glBindBuffer}) while a color array is specified,
2065 @var{pointer} is treated as a byte offset into the buffer object's data
2066 store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING})
2067 is saved as color vertex array client-side state
2068 (@code{GL_COLOR_ARRAY_BUFFER_BINDING}).
2070 When a color array is specified, @var{size}, @var{type}, @var{stride},
2071 and @var{pointer} are saved as client-side state, in addition to the
2072 current vertex array buffer object binding.
2074 To enable and disable the color array, call @code{glEnableClientState}
2075 and @code{glDisableClientState} with the argument @code{GL_COLOR_ARRAY}.
2076 If enabled, the color array is used when @code{glDrawArrays},
2077 @code{glMultiDrawArrays}, @code{glDrawElements},
2078 @code{glMultiDrawElements}, @code{glDrawRangeElements}, or
2079 @code{glArrayElement} is called.
2081 @code{GL_INVALID_VALUE} is generated if @var{size} is not 3 or 4.
2083 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
2086 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
2090 @deftypefun void glColorSubTable target start count format type data
2091 Respecify a portion of a color table.
2095 Must be one of @code{GL_COLOR_TABLE},
2096 @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
2097 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}.
2100 The starting index of the portion of the color table to be replaced.
2103 The number of table entries to replace.
2106 The format of the pixel data in @var{data}. The allowable values are
2107 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
2108 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB},
2109 @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}.
2112 The type of the pixel data in @var{data}. The allowable values are
2113 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT},
2114 @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT},
2115 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
2116 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
2117 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
2118 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
2119 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
2120 @code{GL_UNSIGNED_INT_10_10_10_2}, and
2121 @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
2124 Pointer to a one-dimensional array of pixel data that is processed to
2125 replace the specified region of the color table.
2129 @code{glColorSubTable} is used to respecify a contiguous portion of a
2130 color table previously defined using @code{glColorTable}. The pixels
2131 referenced by @var{data} replace the portion of the existing table from
2132 indices @var{start} to @r{@var{start}+@var{count}-1}, inclusive. This
2133 region may not include any entries outside the range of the color table
2134 as it was originally specified. It is not an error to specify a
2135 subtexture with width of 0, but such a specification has no effect.
2137 If a non-zero named buffer object is bound to the
2138 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2139 portion of a color table is respecified, @var{data} is treated as a byte
2140 offset into the buffer object's data store.
2142 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
2145 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
2148 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
2151 @code{GL_INVALID_VALUE} is generated if
2152 @r{@var{start}+@var{count}>@var{width}}.
2154 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2155 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2156 object's data store is currently mapped.
2158 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2159 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2160 would be unpacked from the buffer object such that the memory reads
2161 required would exceed the data store size.
2163 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2164 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
2165 is not evenly divisible into the number of bytes needed to store in
2166 memory a datum indicated by @var{type}.
2168 @code{GL_INVALID_OPERATION} is generated if @code{glColorSubTable} is
2169 executed between the execution of @code{glBegin} and the corresponding
2170 execution of @code{glEnd}.
2174 @deftypefun void glColorTableParameterfv target pname params
2175 @deftypefunx void glColorTableParameteriv target pname params
2176 Set color lookup table parameters.
2180 The target color table. Must be @code{GL_COLOR_TABLE},
2181 @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
2182 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}.
2185 The symbolic name of a texture color lookup table parameter. Must be
2186 one of @code{GL_COLOR_TABLE_SCALE} or @code{GL_COLOR_TABLE_BIAS}.
2189 A pointer to an array where the values of the parameters are stored.
2193 @code{glColorTableParameter} is used to specify the scale factors and
2194 bias terms applied to color components when they are loaded into a color
2195 table. @var{target} indicates which color table the scale and bias
2196 terms apply to; it must be set to @code{GL_COLOR_TABLE},
2197 @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
2198 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}.
2200 @var{pname} must be @code{GL_COLOR_TABLE_SCALE} to set the scale
2201 factors. In this case, @var{params} points to an array of four values,
2202 which are the scale factors for red, green, blue, and alpha, in that
2205 @var{pname} must be @code{GL_COLOR_TABLE_BIAS} to set the bias terms. In
2206 this case, @var{params} points to an array of four values, which are the
2207 bias terms for red, green, blue, and alpha, in that order.
2209 The color tables themselves are specified by calling
2210 @code{glColorTable}.
2212 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
2213 not an acceptable value.
2215 @code{GL_INVALID_OPERATION} is generated if @code{glColorTableParameter}
2216 is executed between the execution of @code{glBegin} and the
2217 corresponding execution of @code{glEnd}.
2221 @deftypefun void glColorTable target internalformat width format type data
2222 Define a color lookup table.
2226 Must be one of @code{GL_COLOR_TABLE},
2227 @code{GL_POST_CONVOLUTION_COLOR_TABLE},
2228 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{GL_PROXY_COLOR_TABLE},
2229 @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or
2230 @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}.
2232 @item @var{internalformat}
2233 The internal format of the color table. The allowable values are
2234 @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
2235 @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
2236 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
2237 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
2238 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
2239 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
2240 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY},
2241 @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12},
2242 @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
2243 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
2244 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
2245 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
2246 @code{GL_RGBA12}, and @code{GL_RGBA16}.
2249 The number of entries in the color lookup table specified by @var{data}.
2252 The format of the pixel data in @var{data}. The allowable values are
2253 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
2254 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB},
2255 @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}.
2258 The type of the pixel data in @var{data}. The allowable values are
2259 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT},
2260 @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT},
2261 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
2262 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
2263 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
2264 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
2265 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
2266 @code{GL_UNSIGNED_INT_10_10_10_2}, and
2267 @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
2270 Pointer to a one-dimensional array of pixel data that is processed to
2271 build the color table.
2275 @code{glColorTable} may be used in two ways: to test the actual size and
2276 color resolution of a lookup table given a particular set of parameters,
2277 or to load the contents of a color lookup table. Use the targets
2278 @code{GL_PROXY_*} for the first case and the other targets for the
2281 If a non-zero named buffer object is bound to the
2282 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2283 color table is specified, @var{data} is treated as a byte offset into
2284 the buffer object's data store.
2286 If @var{target} is @code{GL_COLOR_TABLE},
2287 @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
2288 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{glColorTable} builds a
2289 color lookup table from an array of pixels. The pixel array specified
2290 by @var{width}, @var{format}, @var{type}, and @var{data} is extracted
2291 from memory and processed just as if @code{glDrawPixels} were called,
2292 but processing stops after the final expansion to RGBA is completed.
2294 The four scale parameters and the four bias parameters that are defined
2295 for the table are then used to scale and bias the R, G, B, and A
2296 components of each pixel. (Use @code{glColorTableParameter} to set
2297 these scale and bias parameters.)
2299 Next, the R, G, B, and A values are clamped to the range @r{[0,1]}. Each
2300 pixel is then converted to the internal format specified by
2301 @var{internalformat}. This conversion simply maps the component values
2302 of the pixel (R, G, B, and A) to the values included in the internal
2303 format (red, green, blue, alpha, luminance, and intensity). The mapping
2309 @item @strong{Internal Format}
2310 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
2311 @strong{Luminance}, @strong{Intensity}
2313 @item @code{GL_ALPHA}
2316 @item @code{GL_LUMINANCE}
2319 @item @code{GL_LUMINANCE_ALPHA}
2322 @item @code{GL_INTENSITY}
2328 @item @code{GL_RGBA}
2333 Finally, the red, green, blue, alpha, luminance, and/or intensity
2334 components of the resulting pixels are stored in the color table. They
2335 form a one-dimensional table with indices in the range
2336 @r{[0,@var{width}-1]}.
2338 If @var{target} is @code{GL_PROXY_*}, @code{glColorTable} recomputes and
2339 stores the values of the proxy color table's state variables
2340 @code{GL_COLOR_TABLE_FORMAT}, @code{GL_COLOR_TABLE_WIDTH},
2341 @code{GL_COLOR_TABLE_RED_SIZE}, @code{GL_COLOR_TABLE_GREEN_SIZE},
2342 @code{GL_COLOR_TABLE_BLUE_SIZE}, @code{GL_COLOR_TABLE_ALPHA_SIZE},
2343 @code{GL_COLOR_TABLE_LUMINANCE_SIZE}, and
2344 @code{GL_COLOR_TABLE_INTENSITY_SIZE}. There is no effect on the image
2345 or state of any actual color table. If the specified color table is too
2346 large to be supported, then all the proxy state variables listed above
2347 are set to zero. Otherwise, the color table could be supported by
2348 @code{glColorTable} using the corresponding non-proxy target, and the
2349 proxy state variables are set as if that target were being defined.
2351 The proxy state variables can be retrieved by calling
2352 @code{glGetColorTableParameter} with a target of @code{GL_PROXY_*}. This
2353 allows the application to decide if a particular @code{glColorTable}
2354 command would succeed, and to determine what the resulting color table
2355 attributes would be.
2357 If a color table is enabled, and its width is non-zero, then its
2358 contents are used to replace a subset of the components of each RGBA
2359 pixel group, based on the internal format of the table.
2361 Each pixel group has color components (R, G, B, A) that are in the range
2362 @r{[0.0,1.0]}. The color components are rescaled to the size of the
2363 color lookup table to form an index. Then a subset of the components
2364 based on the internal format of the table are replaced by the table
2365 entry selected by that index. If the color components and contents of
2366 the table are represented as follows:
2371 @item @strong{Representation}
2375 Table index computed from @code{R}
2378 Table index computed from @code{G}
2381 Table index computed from @code{B}
2384 Table index computed from @code{A}
2387 Luminance value at table index @code{i}
2390 Intensity value at table index @code{i}
2393 Red value at table index @code{i}
2396 Green value at table index @code{i}
2399 Blue value at table index @code{i}
2402 Alpha value at table index @code{i}
2406 then the result of color table lookup is as follows:
2412 @strong{Resulting Texture Components}
2414 @item @strong{Table Internal Format}
2415 @strong{R}, @strong{G}, @strong{B}, @strong{A}
2417 @item @code{GL_ALPHA}
2418 @code{R}, @code{G}, @code{B}, @code{A[a]}
2420 @item @code{GL_LUMINANCE}
2421 @code{L[r]}, @code{L[g]}, @code{L[b]}, @code{At}
2423 @item @code{GL_LUMINANCE_ALPHA}
2424 @code{L[r]}, @code{L[g]}, @code{L[b]}, @code{A[a]}
2426 @item @code{GL_INTENSITY}
2427 @code{I[r]}, @code{I[g]}, @code{I[b]}, @code{I[a]}
2430 @code{R[r]}, @code{G[g]}, @code{B[b]}, @code{A}
2432 @item @code{GL_RGBA}
2433 @code{R[r]}, @code{G[g]}, @code{B[b]}, @code{A[a]}
2437 When @code{GL_COLOR_TABLE} is enabled, the colors resulting from the
2438 pixel map operation (if it is enabled) are mapped by the color lookup
2439 table before being passed to the convolution operation. The colors
2440 resulting from the convolution operation are modified by the post
2441 convolution color lookup table when
2442 @code{GL_POST_CONVOLUTION_COLOR_TABLE} is enabled. These modified
2443 colors are then sent to the color matrix operation. Finally, if
2444 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} is enabled, the colors resulting
2445 from the color matrix operation are mapped by the post color matrix
2446 color lookup table before being used by the histogram operation.
2450 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
2453 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
2454 of the allowable values.
2456 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
2459 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
2462 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero.
2464 @code{GL_TABLE_TOO_LARGE} is generated if the requested color table is
2465 too large to be supported by the implementation, and @var{target} is not
2466 a @code{GL_PROXY_*} target.
2468 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2469 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2470 object's data store is currently mapped.
2472 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2473 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2474 would be unpacked from the buffer object such that the memory reads
2475 required would exceed the data store size.
2477 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2478 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
2479 is not evenly divisible into the number of bytes needed to store in
2480 memory a datum indicated by @var{type}.
2482 @code{GL_INVALID_OPERATION} is generated if @code{glColorTable} is
2483 executed between the execution of @code{glBegin} and the corresponding
2484 execution of @code{glEnd}.
2488 @deftypefun void glColor3b red green blue
2489 @deftypefunx void glColor3s red green blue
2490 @deftypefunx void glColor3i red green blue
2491 @deftypefunx void glColor3f red green blue
2492 @deftypefunx void glColor3d red green blue
2493 @deftypefunx void glColor3ub red green blue
2494 @deftypefunx void glColor3us red green blue
2495 @deftypefunx void glColor3ui red green blue
2496 @deftypefunx void glColor4b red green blue alpha
2497 @deftypefunx void glColor4s red green blue alpha
2498 @deftypefunx void glColor4i red green blue alpha
2499 @deftypefunx void glColor4f red green blue alpha
2500 @deftypefunx void glColor4d red green blue alpha
2501 @deftypefunx void glColor4ub red green blue alpha
2502 @deftypefunx void glColor4us red green blue alpha
2503 @deftypefunx void glColor4ui red green blue alpha
2504 @deftypefunx void glColor3bv v
2505 @deftypefunx void glColor3sv v
2506 @deftypefunx void glColor3iv v
2507 @deftypefunx void glColor3fv v
2508 @deftypefunx void glColor3dv v
2509 @deftypefunx void glColor3ubv v
2510 @deftypefunx void glColor3usv v
2511 @deftypefunx void glColor3uiv v
2512 @deftypefunx void glColor4bv v
2513 @deftypefunx void glColor4sv v
2514 @deftypefunx void glColor4iv v
2515 @deftypefunx void glColor4fv v
2516 @deftypefunx void glColor4dv v
2517 @deftypefunx void glColor4ubv v
2518 @deftypefunx void glColor4usv v
2519 @deftypefunx void glColor4uiv v
2520 Set the current color.
2526 Specify new red, green, and blue values for the current color.
2529 Specifies a new alpha value for the current color. Included only in the
2530 four-argument @code{glColor4} commands.
2534 The GL stores both a current single-valued color index and a current
2535 four-valued RGBA color. @code{glColor} sets a new four-valued RGBA
2536 color. @code{glColor} has two major variants: @code{glColor3} and
2537 @code{glColor4}. @code{glColor3} variants specify new red, green, and
2538 blue values explicitly and set the current alpha value to 1.0 (full
2539 intensity) implicitly. @code{glColor4} variants specify all four color
2540 components explicitly.
2542 @code{glColor3b}, @code{glColor4b}, @code{glColor3s}, @code{glColor4s},
2543 @code{glColor3i}, and @code{glColor4i} take three or four signed byte,
2544 short, or long integers as arguments. When @strong{v} is appended to
2545 the name, the color commands can take a pointer to an array of such
2548 Current color values are stored in floating-point format, with
2549 unspecified mantissa and exponent sizes. Unsigned integer color
2550 components, when specified, are linearly mapped to floating-point values
2551 such that the largest representable value maps to 1.0 (full intensity),
2552 and 0 maps to 0.0 (zero intensity). Signed integer color components,
2553 when specified, are linearly mapped to floating-point values such that
2554 the most positive representable value maps to 1.0, and the most negative
2555 representable value maps to @r{-1.0}. (Note that this mapping does not
2556 convert 0 precisely to 0.0.) Floating-point values are mapped directly.
2558 Neither floating-point nor signed integer values are clamped to the
2559 range @r{[0,1]} before the current color is updated. However, color
2560 components are clamped to this range before they are interpolated or
2561 written into a color buffer.
2565 @deftypefun void glCompileShader shader
2566 Compiles a shader object.
2570 Specifies the shader object to be compiled.
2574 @code{glCompileShader} compiles the source code strings that have been
2575 stored in the shader object specified by @var{shader}.
2577 The compilation status will be stored as part of the shader object's
2578 state. This value will be set to @code{GL_TRUE} if the shader was
2579 compiled without errors and is ready for use, and @code{GL_FALSE}
2580 otherwise. It can be queried by calling @code{glGetShader} with
2581 arguments @var{shader} and @code{GL_COMPILE_STATUS}.
2583 Compilation of a shader can fail for a number of reasons as specified by
2584 the OpenGL Shading Language Specification. Whether or not the
2585 compilation was successful, information about the compilation can be
2586 obtained from the shader object's information log by calling
2587 @code{glGetShaderInfoLog}.
2589 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
2590 generated by OpenGL.
2592 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
2595 @code{GL_INVALID_OPERATION} is generated if @code{glCompileShader} is
2596 executed between the execution of @code{glBegin} and the corresponding
2597 execution of @code{glEnd}.
2601 @deftypefun void glCompressedTexImage1D target level internalformat width border imageSize data
2602 Specify a one-dimensional texture image in a compressed format.
2606 Specifies the target texture. Must be @code{GL_TEXTURE_1D} or
2607 @code{GL_PROXY_TEXTURE_1D}.
2610 Specifies the level-of-detail number. Level 0 is the base image level.
2611 Level @var{n} is the @var{n}th mipmap reduction image.
2613 @item @var{internalformat}
2614 Specifies the format of the compressed image data stored at address
2618 Specifies the width of the texture image including the border if any. If
2619 the GL version does not support non-power-of-two sizes, this value must
2620 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
2621 implementations support texture images that are at least 64 texels wide.
2622 The height of the 1D texture image is 1.
2625 Specifies the width of the border. Must be either 0 or 1.
2627 @item @var{imageSize}
2628 Specifies the number of unsigned bytes of image data starting at the
2629 address specified by @var{data}.
2632 Specifies a pointer to the compressed image data in memory.
2636 Texturing maps a portion of a specified texture image onto each
2637 graphical primitive for which texturing is enabled. To enable and
2638 disable one-dimensional texturing, call @code{glEnable} and
2639 @code{glDisable} with argument @code{GL_TEXTURE_1D}.
2641 @code{glCompressedTexImage1D} loads a previously defined, and retrieved,
2642 compressed one-dimensional texture image if @var{target} is
2643 @code{GL_TEXTURE_1D} (see @code{glTexImage1D}).
2645 If @var{target} is @code{GL_PROXY_TEXTURE_1D}, no data is read from
2646 @var{data}, but all of the texture image state is recalculated, checked
2647 for consistency, and checked against the implementation's capabilities.
2648 If the implementation cannot handle a texture of the requested texture
2649 size, it sets all of the image state to 0, but does not generate an
2650 error (see @code{glGetError}). To query for an entire mipmap array, use
2651 an image array level greater than or equal to 1.
2653 @var{internalformat} must be extension-specified compressed-texture
2654 format. When a texture is loaded with @code{glTexImage1D} using a
2655 generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}) the
2656 GL selects from one of its extensions supporting compressed textures. In
2657 order to load the compressed texture image using
2658 @code{glCompressedTexImage1D}, query the compressed texture image's size
2659 and format using @code{glGetTexLevelParameter}.
2661 If a non-zero named buffer object is bound to the
2662 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2663 texture image is specified, @var{data} is treated as a byte offset into
2664 the buffer object's data store.
2666 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of
2667 the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
2668 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
2669 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or
2670 @code{GL_COMPRESSED_RGBA}.
2672 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
2673 consistent with the format, dimensions, and contents of the specified
2674 compressed image data.
2676 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
2677 not supported by the specific compressed internal format as specified in
2678 the specific texture compression extension.
2680 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2681 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2682 object's data store is currently mapped.
2684 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2685 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2686 would be unpacked from the buffer object such that the memory reads
2687 required would exceed the data store size.
2689 @code{GL_INVALID_OPERATION} is generated if
2690 @code{glCompressedTexImage1D} is executed between the execution of
2691 @code{glBegin} and the corresponding execution of @code{glEnd}.
2693 Undefined results, including abnormal program termination, are generated
2694 if @var{data} is not encoded in a manner consistent with the extension
2695 specification defining the internal compression format.
2699 @deftypefun void glCompressedTexImage2D target level internalformat width height border imageSize data
2700 Specify a two-dimensional texture image in a compressed format.
2704 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
2705 @code{GL_PROXY_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
2706 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
2707 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
2708 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
2709 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z},
2710 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or
2711 @code{GL_PROXY_TEXTURE_CUBE_MAP}.
2714 Specifies the level-of-detail number. Level 0 is the base image level.
2715 Level @var{n} is the @var{n}th mipmap reduction image.
2717 @item @var{internalformat}
2718 Specifies the format of the compressed image data stored at address
2722 Specifies the width of the texture image including the border if any. If
2723 the GL version does not support non-power-of-two sizes, this value must
2724 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
2725 implementations support 2D texture images that are at least 64 texels
2726 wide and cube-mapped texture images that are at least 16 texels wide.
2729 Specifies the height of the texture image including the border if any.
2730 If the GL version does not support non-power-of-two sizes, this value
2731 must be Must be @r{2^@var{n}+2(@var{border},)} for some integer
2732 @r{@var{n}}. All implementations support 2D texture images that are at
2733 least 64 texels high and cube-mapped texture images that are at least 16
2737 Specifies the width of the border. Must be either 0 or 1.
2739 @item @var{imageSize}
2740 Specifies the number of unsigned bytes of image data starting at the
2741 address specified by @var{data}.
2744 Specifies a pointer to the compressed image data in memory.
2748 Texturing maps a portion of a specified texture image onto each
2749 graphical primitive for which texturing is enabled. To enable and
2750 disable two-dimensional texturing, call @code{glEnable} and
2751 @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and
2752 disable texturing using cube-mapped textures, call @code{glEnable} and
2753 @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}.
2755 @code{glCompressedTexImage2D} loads a previously defined, and retrieved,
2756 compressed two-dimensional texture image if @var{target} is
2757 @code{GL_TEXTURE_2D} (see @code{glTexImage2D}).
2759 If @var{target} is @code{GL_PROXY_TEXTURE_2D}, no data is read from
2760 @var{data}, but all of the texture image state is recalculated, checked
2761 for consistency, and checked against the implementation's capabilities.
2762 If the implementation cannot handle a texture of the requested texture
2763 size, it sets all of the image state to 0, but does not generate an
2764 error (see @code{glGetError}). To query for an entire mipmap array, use
2765 an image array level greater than or equal to 1.
2767 @var{internalformat} must be an extension-specified compressed-texture
2768 format. When a texture is loaded with @code{glTexImage2D} using a
2769 generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}), the
2770 GL selects from one of its extensions supporting compressed textures. In
2771 order to load the compressed texture image using
2772 @code{glCompressedTexImage2D}, query the compressed texture image's size
2773 and format using @code{glGetTexLevelParameter}.
2775 If a non-zero named buffer object is bound to the
2776 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2777 texture image is specified, @var{data} is treated as a byte offset into
2778 the buffer object's data store.
2780 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of
2781 the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
2782 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
2783 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or
2784 @code{GL_COMPRESSED_RGBA}.
2786 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
2787 consistent with the format, dimensions, and contents of the specified
2788 compressed image data.
2790 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
2791 not supported by the specific compressed internal format as specified in
2792 the specific texture compression extension.
2794 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2795 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2796 object's data store is currently mapped.
2798 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2799 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2800 would be unpacked from the buffer object such that the memory reads
2801 required would exceed the data store size.
2803 @code{GL_INVALID_OPERATION} is generated if
2804 @code{glCompressedTexImage2D} is executed between the execution of
2805 @code{glBegin} and the corresponding execution of @code{glEnd}.
2807 Undefined results, including abnormal program termination, are generated
2808 if @var{data} is not encoded in a manner consistent with the extension
2809 specification defining the internal compression format.
2813 @deftypefun void glCompressedTexImage3D target level internalformat width height depth border imageSize data
2814 Specify a three-dimensional texture image in a compressed format.
2818 Specifies the target texture. Must be @code{GL_TEXTURE_3D} or
2819 @code{GL_PROXY_TEXTURE_3D}.
2822 Specifies the level-of-detail number. Level 0 is the base image level.
2823 Level @var{n} is the @var{n}th mipmap reduction image.
2825 @item @var{internalformat}
2826 Specifies the format of the compressed image data stored at address
2830 Specifies the width of the texture image including the border if any. If
2831 the GL version does not support non-power-of-two sizes, this value must
2832 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
2833 implementations support 3D texture images that are at least 16 texels
2837 Specifies the height of the texture image including the border if any.
2838 If the GL version does not support non-power-of-two sizes, this value
2839 must be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}.
2840 All implementations support 3D texture images that are at least 16
2844 Specifies the depth of the texture image including the border if any. If
2845 the GL version does not support non-power-of-two sizes, this value must
2846 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
2847 implementations support 3D texture images that are at least 16 texels
2851 Specifies the width of the border. Must be either 0 or 1.
2853 @item @var{imageSize}
2854 Specifies the number of unsigned bytes of image data starting at the
2855 address specified by @var{data}.
2858 Specifies a pointer to the compressed image data in memory.
2862 Texturing maps a portion of a specified texture image onto each
2863 graphical primitive for which texturing is enabled. To enable and
2864 disable three-dimensional texturing, call @code{glEnable} and
2865 @code{glDisable} with argument @code{GL_TEXTURE_3D}.
2867 @code{glCompressedTexImage3D} loads a previously defined, and retrieved,
2868 compressed three-dimensional texture image if @var{target} is
2869 @code{GL_TEXTURE_3D} (see @code{glTexImage3D}).
2871 If @var{target} is @code{GL_PROXY_TEXTURE_3D}, no data is read from
2872 @var{data}, but all of the texture image state is recalculated, checked
2873 for consistency, and checked against the implementation's capabilities.
2874 If the implementation cannot handle a texture of the requested texture
2875 size, it sets all of the image state to 0, but does not generate an
2876 error (see @code{glGetError}). To query for an entire mipmap array, use
2877 an image array level greater than or equal to 1.
2879 @var{internalformat} must be an extension-specified compressed-texture
2880 format. When a texture is loaded with @code{glTexImage2D} using a
2881 generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}), the
2882 GL selects from one of its extensions supporting compressed textures. In
2883 order to load the compressed texture image using
2884 @code{glCompressedTexImage3D}, query the compressed texture image's size
2885 and format using @code{glGetTexLevelParameter}.
2887 If a non-zero named buffer object is bound to the
2888 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2889 texture image is specified, @var{data} is treated as a byte offset into
2890 the buffer object's data store.
2892 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of
2893 the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
2894 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
2895 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or
2896 @code{GL_COMPRESSED_RGBA}.
2898 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
2899 consistent with the format, dimensions, and contents of the specified
2900 compressed image data.
2902 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
2903 not supported by the specific compressed internal format as specified in
2904 the specific texture compression extension.
2906 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2907 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2908 object's data store is currently mapped.
2910 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2911 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2912 would be unpacked from the buffer object such that the memory reads
2913 required would exceed the data store size.
2915 @code{GL_INVALID_OPERATION} is generated if
2916 @code{glCompressedTexImage3D} is executed between the execution of
2917 @code{glBegin} and the corresponding execution of @code{glEnd}.
2919 Undefined results, including abnormal program termination, are generated
2920 if @var{data} is not encoded in a manner consistent with the extension
2921 specification defining the internal compression format.
2925 @deftypefun void glCompressedTexSubImage1D target level xoffset width format imageSize data
2926 Specify a one-dimensional texture subimage in a compressed format.
2930 Specifies the target texture. Must be @code{GL_TEXTURE_1D}.
2933 Specifies the level-of-detail number. Level 0 is the base image level.
2934 Level @var{n} is the @var{n}th mipmap reduction image.
2937 Specifies a texel offset in the x direction within the texture array.
2940 Specifies the width of the texture subimage.
2943 Specifies the format of the compressed image data stored at address
2946 @item @var{imageSize}
2947 Specifies the number of unsigned bytes of image data starting at the
2948 address specified by @var{data}.
2951 Specifies a pointer to the compressed image data in memory.
2955 Texturing maps a portion of a specified texture image onto each
2956 graphical primitive for which texturing is enabled. To enable and
2957 disable one-dimensional texturing, call @code{glEnable} and
2958 @code{glDisable} with argument @code{GL_TEXTURE_1D}.
2960 @code{glCompressedTexSubImage1D} redefines a contiguous subregion of an
2961 existing one-dimensional texture image. The texels referenced by
2962 @var{data} replace the portion of the existing texture array with x
2963 indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive.
2964 This region may not include any texels outside the range of the texture
2965 array as it was originally specified. It is not an error to specify a
2966 subtexture with width of 0, but such a specification has no effect.
2968 @var{format} must be an extension-specified compressed-texture format.
2969 The @var{format} of the compressed texture image is selected by the GL
2970 implementation that compressed it (see @code{glTexImage1D}), and should
2971 be queried at the time the texture was compressed with
2972 @code{glGetTexLevelParameter}.
2974 If a non-zero named buffer object is bound to the
2975 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2976 texture image is specified, @var{data} is treated as a byte offset into
2977 the buffer object's data store.
2979 @code{GL_INVALID_ENUM} is generated if @var{format} is one of these
2980 generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
2981 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
2982 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
2983 @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE},
2984 @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB},
2985 @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}.
2987 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
2988 consistent with the format, dimensions, and contents of the specified
2989 compressed image data.
2991 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
2992 not supported by the specific compressed internal format as specified in
2993 the specific texture compression extension.
2995 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2996 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2997 object's data store is currently mapped.
2999 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3000 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
3001 would be unpacked from the buffer object such that the memory reads
3002 required would exceed the data store size.
3004 @code{GL_INVALID_OPERATION} is generated if
3005 @code{glCompressedTexSubImage1D} is executed between the execution of
3006 @code{glBegin} and the corresponding execution of @code{glEnd}.
3008 Undefined results, including abnormal program termination, are generated
3009 if @var{data} is not encoded in a manner consistent with the extension
3010 specification defining the internal compression format.
3014 @deftypefun void glCompressedTexSubImage2D target level xoffset yoffset width height format imageSize data
3015 Specify a two-dimensional texture subimage in a compressed format.
3019 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
3020 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
3021 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
3022 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
3023 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
3024 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
3025 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
3028 Specifies the level-of-detail number. Level 0 is the base image level.
3029 Level @var{n} is the @var{n}th mipmap reduction image.
3032 Specifies a texel offset in the x direction within the texture array.
3035 Specifies a texel offset in the y direction within the texture array.
3038 Specifies the width of the texture subimage.
3041 Specifies the height of the texture subimage.
3044 Specifies the format of the compressed image data stored at address
3047 @item @var{imageSize}
3048 Specifies the number of unsigned bytes of image data starting at the
3049 address specified by @var{data}.
3052 Specifies a pointer to the compressed image data in memory.
3056 Texturing maps a portion of a specified texture image onto each
3057 graphical primitive for which texturing is enabled. To enable and
3058 disable two-dimensional texturing, call @code{glEnable} and
3059 @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and
3060 disable texturing using cube-mapped texture, call @code{glEnable} and
3061 @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}.
3063 @code{glCompressedTexSubImage2D} redefines a contiguous subregion of an
3064 existing two-dimensional texture image. The texels referenced by
3065 @var{data} replace the portion of the existing texture array with x
3066 indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, and the y
3067 indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive.
3068 This region may not include any texels outside the range of the texture
3069 array as it was originally specified. It is not an error to specify a
3070 subtexture with width of 0, but such a specification has no effect.
3072 @var{format} must be an extension-specified compressed-texture format.
3073 The @var{format} of the compressed texture image is selected by the GL
3074 implementation that compressed it (see @code{glTexImage2D}) and should
3075 be queried at the time the texture was compressed with
3076 @code{glGetTexLevelParameter}.
3078 If a non-zero named buffer object is bound to the
3079 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
3080 texture image is specified, @var{data} is treated as a byte offset into
3081 the buffer object's data store.
3083 @code{GL_INVALID_ENUM} is generated if @var{format} is one of these
3084 generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
3085 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
3086 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
3087 @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE},
3088 @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB},
3089 @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}.
3091 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
3092 consistent with the format, dimensions, and contents of the specified
3093 compressed image data.
3095 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
3096 not supported by the specific compressed internal format as specified in
3097 the specific texture compression extension.
3099 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3100 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
3101 object's data store is currently mapped.
3103 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3104 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
3105 would be unpacked from the buffer object such that the memory reads
3106 required would exceed the data store size.
3108 @code{GL_INVALID_OPERATION} is generated if
3109 @code{glCompressedTexSubImage2D} is executed between the execution of
3110 @code{glBegin} and the corresponding execution of @code{glEnd}.
3112 Undefined results, including abnormal program termination, are generated
3113 if @var{data} is not encoded in a manner consistent with the extension
3114 specification defining the internal compression format.
3118 @deftypefun void glCompressedTexSubImage3D target level xoffset yoffset zoffset width height depth format imageSize data
3119 Specify a three-dimensional texture subimage in a compressed format.
3123 Specifies the target texture. Must be @code{GL_TEXTURE_3D}.
3126 Specifies the level-of-detail number. Level 0 is the base image level.
3127 Level @var{n} is the @var{n}th mipmap reduction image.
3130 Specifies a texel offset in the x direction within the texture array.
3133 Specifies a texel offset in the y direction within the texture array.
3136 Specifies the width of the texture subimage.
3139 Specifies the height of the texture subimage.
3142 Specifies the depth of the texture subimage.
3145 Specifies the format of the compressed image data stored at address
3148 @item @var{imageSize}
3149 Specifies the number of unsigned bytes of image data starting at the
3150 address specified by @var{data}.
3153 Specifies a pointer to the compressed image data in memory.
3157 Texturing maps a portion of a specified texture image onto each
3158 graphical primitive for which texturing is enabled. To enable and
3159 disable three-dimensional texturing, call @code{glEnable} and
3160 @code{glDisable} with argument @code{GL_TEXTURE_3D}.
3162 @code{glCompressedTexSubImage3D} redefines a contiguous subregion of an
3163 existing three-dimensional texture image. The texels referenced by
3164 @var{data} replace the portion of the existing texture array with x
3165 indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, and the y
3166 indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, and the z
3167 indices @var{zoffset} and @r{@var{zoffset}+@var{depth}-1}, inclusive.
3168 This region may not include any texels outside the range of the texture
3169 array as it was originally specified. It is not an error to specify a
3170 subtexture with width of 0, but such a specification has no effect.
3172 @var{format} must be an extension-specified compressed-texture format.
3173 The @var{format} of the compressed texture image is selected by the GL
3174 implementation that compressed it (see @code{glTexImage3D}) and should
3175 be queried at the time the texture was compressed with
3176 @code{glGetTexLevelParameter}.
3178 If a non-zero named buffer object is bound to the
3179 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
3180 texture image is specified, @var{data} is treated as a byte offset into
3181 the buffer object's data store.
3183 @code{GL_INVALID_ENUM} is generated if @var{format} is one of these
3184 generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
3185 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
3186 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
3187 @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE},
3188 @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB},
3189 @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}.
3191 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
3192 consistent with the format, dimensions, and contents of the specified
3193 compressed image data.
3195 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
3196 not supported by the specific compressed internal format as specified in
3197 the specific texture compression extension.
3199 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3200 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
3201 object's data store is currently mapped.
3203 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3204 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
3205 would be unpacked from the buffer object such that the memory reads
3206 required would exceed the data store size.
3208 @code{GL_INVALID_OPERATION} is generated if
3209 @code{glCompressedTexSubImage3D} is executed between the execution of
3210 @code{glBegin} and the corresponding execution of @code{glEnd}.
3212 Undefined results, including abnormal program termination, are generated
3213 if @var{data} is not encoded in a manner consistent with the extension
3214 specification defining the internal compression format.
3218 @deftypefun void glConvolutionFilter1D target internalformat width format type data
3219 Define a one-dimensional convolution filter.
3223 Must be @code{GL_CONVOLUTION_1D}.
3225 @item @var{internalformat}
3226 The internal format of the convolution filter kernel. The allowable
3227 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
3228 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
3229 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
3230 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3231 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3232 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3233 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3234 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3235 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3236 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3237 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3238 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3239 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3242 The width of the pixel array referenced by @var{data}.
3245 The format of the pixel data in @var{data}. The allowable values are
3246 @code{GL_ALPHA}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA},
3247 @code{GL_INTENSITY}, @code{GL_RGB}, and @code{GL_RGBA}.
3250 The type of the pixel data in @var{data}. Symbolic constants
3251 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
3252 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
3253 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
3254 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
3255 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
3256 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
3257 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
3258 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
3259 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
3262 Pointer to a one-dimensional array of pixel data that is processed to
3263 build the convolution filter kernel.
3267 @code{glConvolutionFilter1D} builds a one-dimensional convolution filter
3268 kernel from an array of pixels.
3270 The pixel array specified by @var{width}, @var{format}, @var{type}, and
3271 @var{data} is extracted from memory and processed just as if
3272 @code{glDrawPixels} were called, but processing stops after the final
3273 expansion to RGBA is completed.
3275 If a non-zero named buffer object is bound to the
3276 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
3277 convolution filter is specified, @var{data} is treated as a byte offset
3278 into the buffer object's data store.
3280 The R, G, B, and A components of each pixel are next scaled by the four
3281 1D @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four
3282 1D @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
3283 parameters are set by @code{glConvolutionParameter} using the
3284 @code{GL_CONVOLUTION_1D} target and the names
3285 @code{GL_CONVOLUTION_FILTER_SCALE} and
3286 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are
3287 vectors of four values that are applied to red, green, blue, and alpha,
3288 in that order.) The R, G, B, and A values are not clamped to [0,1] at
3289 any time during this process.
3291 Each pixel is then converted to the internal format specified by
3292 @var{internalformat}. This conversion simply maps the component values
3293 of the pixel (R, G, B, and A) to the values included in the internal
3294 format (red, green, blue, alpha, luminance, and intensity). The mapping
3300 @item @strong{Internal Format}
3301 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
3302 @strong{Luminance}, @strong{Intensity}
3304 @item @code{GL_ALPHA}
3307 @item @code{GL_LUMINANCE}
3310 @item @code{GL_LUMINANCE_ALPHA}
3313 @item @code{GL_INTENSITY}
3319 @item @code{GL_RGBA}
3324 The red, green, blue, alpha, luminance, and/or intensity components of
3325 the resulting pixels are stored in floating-point rather than integer
3326 format. They form a one-dimensional filter kernel image indexed with
3327 coordinate @var{i} such that @var{i} starts at 0 and increases from left
3328 to right. Kernel location @var{i} is derived from the @var{i}th pixel,
3331 Note that after a convolution is performed, the resulting color
3332 components are also scaled by their corresponding
3333 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
3334 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
3335 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
3336 and @strong{ALPHA}). These parameters are set by
3337 @code{glPixelTransfer}.
3339 @code{GL_INVALID_ENUM} is generated if @var{target} is not
3340 @code{GL_CONVOLUTION_1D}.
3342 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
3343 of the allowable values.
3345 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
3348 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
3351 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
3352 greater than the maximum supported value. This value may be queried
3353 with @code{glGetConvolutionParameter} using target
3354 @code{GL_CONVOLUTION_1D} and name @code{GL_MAX_CONVOLUTION_WIDTH}.
3356 @code{GL_INVALID_OPERATION} is generated if @var{format} is one of
3357 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
3358 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
3359 and @var{type} is not @code{GL_RGB}.
3361 @code{GL_INVALID_OPERATION} is generated if @var{format} is one of
3362 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
3363 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
3364 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
3365 @code{GL_UNSIGNED_INT_10_10_10_2}, or
3366 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{type} is neither
3367 @code{GL_RGBA} nor @code{GL_BGRA}.
3369 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3370 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
3371 object's data store is currently mapped.
3373 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3374 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
3375 would be unpacked from the buffer object such that the memory reads
3376 required would exceed the data store size.
3378 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3379 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
3380 is not evenly divisible into the number of bytes needed to store in
3381 memory a datum indicated by @var{type}.
3383 @code{GL_INVALID_OPERATION} is generated if @code{glConvolutionFilter1D}
3384 is executed between the execution of @code{glBegin} and the
3385 corresponding execution of @code{glEnd}.
3389 @deftypefun void glConvolutionFilter2D target internalformat width height format type data
3390 Define a two-dimensional convolution filter.
3394 Must be @code{GL_CONVOLUTION_2D}.
3396 @item @var{internalformat}
3397 The internal format of the convolution filter kernel. The allowable
3398 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
3399 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
3400 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
3401 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3402 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3403 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3404 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3405 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3406 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3407 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3408 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3409 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3410 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3413 The width of the pixel array referenced by @var{data}.
3416 The height of the pixel array referenced by @var{data}.
3419 The format of the pixel data in @var{data}. The allowable values are
3420 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
3421 @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA},
3422 @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA}.
3425 The type of the pixel data in @var{data}. Symbolic constants
3426 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
3427 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
3428 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
3429 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
3430 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
3431 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
3432 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
3433 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
3434 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
3437 Pointer to a two-dimensional array of pixel data that is processed to
3438 build the convolution filter kernel.
3442 @code{glConvolutionFilter2D} builds a two-dimensional convolution filter
3443 kernel from an array of pixels.
3445 The pixel array specified by @var{width}, @var{height}, @var{format},
3446 @var{type}, and @var{data} is extracted from memory and processed just
3447 as if @code{glDrawPixels} were called, but processing stops after the
3448 final expansion to RGBA is completed.
3450 If a non-zero named buffer object is bound to the
3451 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
3452 convolution filter is specified, @var{data} is treated as a byte offset
3453 into the buffer object's data store.
3455 The R, G, B, and A components of each pixel are next scaled by the four
3456 2D @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four
3457 2D @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
3458 parameters are set by @code{glConvolutionParameter} using the
3459 @code{GL_CONVOLUTION_2D} target and the names
3460 @code{GL_CONVOLUTION_FILTER_SCALE} and
3461 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are
3462 vectors of four values that are applied to red, green, blue, and alpha,
3463 in that order.) The R, G, B, and A values are not clamped to [0,1] at
3464 any time during this process.
3466 Each pixel is then converted to the internal format specified by
3467 @var{internalformat}. This conversion simply maps the component values
3468 of the pixel (R, G, B, and A) to the values included in the internal
3469 format (red, green, blue, alpha, luminance, and intensity). The mapping
3475 @item @strong{Internal Format}
3476 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
3477 @strong{Luminance}, @strong{Intensity}
3479 @item @code{GL_ALPHA}
3482 @item @code{GL_LUMINANCE}
3485 @item @code{GL_LUMINANCE_ALPHA}
3488 @item @code{GL_INTENSITY}
3494 @item @code{GL_RGBA}
3499 The red, green, blue, alpha, luminance, and/or intensity components of
3500 the resulting pixels are stored in floating-point rather than integer
3501 format. They form a two-dimensional filter kernel image indexed with
3502 coordinates @var{i} and @var{j} such that @var{i} starts at zero and
3503 increases from left to right, and @var{j} starts at zero and increases
3504 from bottom to top. Kernel location @var{i,j} is derived from the
3505 @var{N}th pixel, where @var{N} is @var{i}+@var{j}*@var{width}.
3507 Note that after a convolution is performed, the resulting color
3508 components are also scaled by their corresponding
3509 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
3510 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
3511 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
3512 and @strong{ALPHA}). These parameters are set by
3513 @code{glPixelTransfer}.
3515 @code{GL_INVALID_ENUM} is generated if @var{target} is not
3516 @code{GL_CONVOLUTION_2D}.
3518 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
3519 of the allowable values.
3521 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
3524 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
3527 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
3528 greater than the maximum supported value. This value may be queried
3529 with @code{glGetConvolutionParameter} using target
3530 @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_WIDTH}.
3532 @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero
3533 or greater than the maximum supported value. This value may be queried
3534 with @code{glGetConvolutionParameter} using target
3535 @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}.
3537 @code{GL_INVALID_OPERATION} is generated if @var{height} is one of
3538 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
3539 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
3540 and @var{format} is not @code{GL_RGB}.
3542 @code{GL_INVALID_OPERATION} is generated if @var{height} is one of
3543 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
3544 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
3545 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
3546 @code{GL_UNSIGNED_INT_10_10_10_2}, or
3547 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
3548 @code{GL_RGBA} nor @code{GL_BGRA}.
3550 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3551 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
3552 object's data store is currently mapped.
3554 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3555 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
3556 would be unpacked from the buffer object such that the memory reads
3557 required would exceed the data store size.
3559 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3560 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
3561 is not evenly divisible into the number of bytes needed to store in
3562 memory a datum indicated by @var{type}.
3564 @code{GL_INVALID_OPERATION} is generated if @code{glConvolutionFilter2D}
3565 is executed between the execution of @code{glBegin} and the
3566 corresponding execution of @code{glEnd}.
3570 @deftypefun void glConvolutionParameterf target pname params
3571 @deftypefunx void glConvolutionParameteri target pname params
3572 @deftypefunx void glConvolutionParameterfv target pname params
3573 @deftypefunx void glConvolutionParameteriv target pname params
3574 Set convolution parameters.
3578 The target for the convolution parameter. Must be one of
3579 @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or
3580 @code{GL_SEPARABLE_2D}.
3583 The parameter to be set. Must be @code{GL_CONVOLUTION_BORDER_MODE}.
3586 The parameter value. Must be one of @code{GL_REDUCE},
3587 @code{GL_CONSTANT_BORDER}, @code{GL_REPLICATE_BORDER}.
3593 @code{glConvolutionParameter} sets the value of a convolution parameter.
3595 @var{target} selects the convolution filter to be affected:
3596 @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or
3597 @code{GL_SEPARABLE_2D} for the 1D, 2D, or separable 2D filter,
3600 @var{pname} selects the parameter to be changed.
3601 @code{GL_CONVOLUTION_FILTER_SCALE} and @code{GL_CONVOLUTION_FILTER_BIAS}
3602 affect the definition of the convolution filter kernel; see
3603 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and
3604 @code{glSeparableFilter2D} for details. In these cases, @var{params}v
3605 is an array of four values to be applied to red, green, blue, and alpha
3606 values, respectively. The initial value for
3607 @code{GL_CONVOLUTION_FILTER_SCALE} is (1, 1, 1, 1), and the initial
3608 value for @code{GL_CONVOLUTION_FILTER_BIAS} is (0, 0, 0, 0).
3610 A @var{pname} value of @code{GL_CONVOLUTION_BORDER_MODE} controls the
3611 convolution border mode. The accepted modes are:
3614 @item @code{GL_REDUCE}
3615 The image resulting from convolution is smaller than the source image.
3616 If the filter width is @r{@var{Wf}} and height is @r{@var{Hf}}, and the
3617 source image width is @r{@var{Ws}} and height is @r{@var{Hs}}, then the
3618 convolved image width will be @r{@var{Ws}-@var{Wf}+1} and height will be
3619 @r{@var{Hs}-@var{Hf}+1}. (If this reduction would generate an image
3620 with zero or negative width and/or height, the output is simply null,
3621 with no error generated.) The coordinates of the image resulting from
3622 convolution are zero through @r{@var{Ws}-@var{Wf}} in width and zero
3623 through @r{@var{Hs}-@var{Hf}} in height.
3625 @item @code{GL_CONSTANT_BORDER}
3626 The image resulting from convolution is the same size as the source
3627 image, and processed as if the source image were surrounded by pixels
3628 with their color specified by the @code{GL_CONVOLUTION_BORDER_COLOR}.
3630 @item @code{GL_REPLICATE_BORDER}
3631 The image resulting from convolution is the same size as the source
3632 image, and processed as if the outermost pixel on the border of the
3633 source image were replicated.
3637 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
3640 @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the
3643 @code{GL_INVALID_ENUM} is generated if @var{pname} is
3644 @code{GL_CONVOLUTION_BORDER_MODE} and @var{params} is not one of
3645 @code{GL_REDUCE}, @code{GL_CONSTANT_BORDER}, or
3646 @code{GL_REPLICATE_BORDER}.
3648 @code{GL_INVALID_OPERATION} is generated if
3649 @code{glConvolutionParameter} is executed between the execution of
3650 @code{glBegin} and the corresponding execution of @code{glEnd}.
3654 @deftypefun void glCopyColorSubTable target start x y width
3655 Respecify a portion of a color table.
3659 Must be one of @code{GL_COLOR_TABLE},
3660 @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
3661 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}.
3664 The starting index of the portion of the color table to be replaced.
3668 The window coordinates of the left corner of the row of pixels to be
3672 The number of table entries to replace.
3676 @code{glCopyColorSubTable} is used to respecify a contiguous portion of
3677 a color table previously defined using @code{glColorTable}. The pixels
3678 copied from the framebuffer replace the portion of the existing table
3679 from indices @var{start} to @r{@var{start}+@var{x}-1}, inclusive. This
3680 region may not include any entries outside the range of the color table,
3681 as was originally specified. It is not an error to specify a subtexture
3682 with width of 0, but such a specification has no effect.
3684 @code{GL_INVALID_VALUE} is generated if @var{target} is not a previously
3685 defined color table.
3687 @code{GL_INVALID_VALUE} is generated if @var{target} is not one of the
3690 @code{GL_INVALID_VALUE} is generated if
3691 @r{@var{start}+@var{x}>@var{width}}.
3693 @code{GL_INVALID_OPERATION} is generated if @code{glCopyColorSubTable}
3694 is executed between the execution of @code{glBegin} and the
3695 corresponding execution of @code{glEnd}.
3699 @deftypefun void glCopyColorTable target internalformat x y width
3700 Copy pixels into a color table.
3704 The color table target. Must be @code{GL_COLOR_TABLE},
3705 @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
3706 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}.
3708 @item @var{internalformat}
3709 The internal storage format of the texture image. Must be one of the
3710 following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4},
3711 @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16},
3712 @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8},
3713 @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3714 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3715 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3716 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3717 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3718 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3719 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3720 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3721 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3722 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3725 The x coordinate of the lower-left corner of the pixel rectangle to be
3726 transferred to the color table.
3729 The y coordinate of the lower-left corner of the pixel rectangle to be
3730 transferred to the color table.
3733 The width of the pixel rectangle.
3737 @code{glCopyColorTable} loads a color table with pixels from the current
3738 @code{GL_READ_BUFFER} (rather than from main memory, as is the case for
3739 @code{glColorTable}).
3741 The screen-aligned pixel rectangle with lower-left corner at (@var{x},\
3742 @var{y}) having width @var{width} and height 1 is loaded into the color
3743 table. If any pixels within this region are outside the window that is
3744 associated with the GL context, the values obtained for those pixels are
3747 The pixels in the rectangle are processed just as if @code{glReadPixels}
3748 were called, with @var{internalformat} set to RGBA, but processing stops
3749 after the final conversion to RGBA.
3751 The four scale parameters and the four bias parameters that are defined
3752 for the table are then used to scale and bias the R, G, B, and A
3753 components of each pixel. The scale and bias parameters are set by
3754 calling @code{glColorTableParameter}.
3756 Next, the R, G, B, and A values are clamped to the range @r{[0,1]}. Each
3757 pixel is then converted to the internal format specified by
3758 @var{internalformat}. This conversion simply maps the component values
3759 of the pixel (R, G, B, and A) to the values included in the internal
3760 format (red, green, blue, alpha, luminance, and intensity). The mapping
3766 @item @strong{Internal Format}
3767 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
3768 @strong{Luminance}, @strong{Intensity}
3770 @item @code{GL_ALPHA}
3773 @item @code{GL_LUMINANCE}
3776 @item @code{GL_LUMINANCE_ALPHA}
3779 @item @code{GL_INTENSITY}
3785 @item @code{GL_RGBA}
3790 Finally, the red, green, blue, alpha, luminance, and/or intensity
3791 components of the resulting pixels are stored in the color table. They
3792 form a one-dimensional table with indices in the range
3793 @r{[0,@var{width}-1]}.
3797 @code{GL_INVALID_ENUM} is generated when @var{target} is not one of the
3800 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero.
3802 @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not one
3803 of the allowable values.
3805 @code{GL_TABLE_TOO_LARGE} is generated if the requested color table is
3806 too large to be supported by the implementation.
3808 @code{GL_INVALID_OPERATION} is generated if @code{glCopyColorTable} is
3809 executed between the execution of @code{glBegin} and the corresponding
3810 execution of @code{glEnd}.
3814 @deftypefun void glCopyConvolutionFilter1D target internalformat x y width
3815 Copy pixels into a one-dimensional convolution filter.
3819 Must be @code{GL_CONVOLUTION_1D}.
3821 @item @var{internalformat}
3822 The internal format of the convolution filter kernel. The allowable
3823 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
3824 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
3825 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
3826 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3827 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3828 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3829 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3830 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3831 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3832 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3833 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3834 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3835 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3839 The window space coordinates of the lower-left coordinate of the pixel
3843 The width of the pixel array to copy.
3847 @code{glCopyConvolutionFilter1D} defines a one-dimensional convolution
3848 filter kernel with pixels from the current @code{GL_READ_BUFFER} (rather
3849 than from main memory, as is the case for @code{glConvolutionFilter1D}).
3851 The screen-aligned pixel rectangle with lower-left corner at (@var{x},\
3852 @var{y}), width @var{width} and height 1 is used to define the
3853 convolution filter. If any pixels within this region are outside the
3854 window that is associated with the GL context, the values obtained for
3855 those pixels are undefined.
3857 The pixels in the rectangle are processed exactly as if
3858 @code{glReadPixels} had been called with @var{format} set to RGBA, but
3859 the process stops just before final conversion. The R, G, B, and A
3860 components of each pixel are next scaled by the four 1D
3861 @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four 1D
3862 @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
3863 parameters are set by @code{glConvolutionParameter} using the
3864 @code{GL_CONVOLUTION_1D} target and the names
3865 @code{GL_CONVOLUTION_FILTER_SCALE} and
3866 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are
3867 vectors of four values that are applied to red, green, blue, and alpha,
3868 in that order.) The R, G, B, and A values are not clamped to [0,1] at
3869 any time during this process.
3871 Each pixel is then converted to the internal format specified by
3872 @var{internalformat}. This conversion simply maps the component values
3873 of the pixel (R, G, B, and A) to the values included in the internal
3874 format (red, green, blue, alpha, luminance, and intensity). The mapping
3880 @item @strong{Internal Format}
3881 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
3882 @strong{Luminance}, @strong{Intensity}
3884 @item @code{GL_ALPHA}
3887 @item @code{GL_LUMINANCE}
3890 @item @code{GL_LUMINANCE_ALPHA}
3893 @item @code{GL_INTENSITY}
3899 @item @code{GL_RGBA}
3904 The red, green, blue, alpha, luminance, and/or intensity components of
3905 the resulting pixels are stored in floating-point rather than integer
3908 Pixel ordering is such that lower x screen coordinates correspond to
3909 lower @var{i} filter image coordinates.
3911 Note that after a convolution is performed, the resulting color
3912 components are also scaled by their corresponding
3913 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
3914 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
3915 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
3916 and @strong{ALPHA}). These parameters are set by
3917 @code{glPixelTransfer}.
3919 @code{GL_INVALID_ENUM} is generated if @var{target} is not
3920 @code{GL_CONVOLUTION_1D}.
3922 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
3923 of the allowable values.
3925 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
3926 greater than the maximum supported value. This value may be queried
3927 with @code{glGetConvolutionParameter} using target
3928 @code{GL_CONVOLUTION_1D} and name @code{GL_MAX_CONVOLUTION_WIDTH}.
3930 @code{GL_INVALID_OPERATION} is generated if
3931 @code{glCopyConvolutionFilter1D} is executed between the execution of
3932 @code{glBegin} and the corresponding execution of @code{glEnd}.
3936 @deftypefun void glCopyConvolutionFilter2D target internalformat x y width height
3937 Copy pixels into a two-dimensional convolution filter.
3941 Must be @code{GL_CONVOLUTION_2D}.
3943 @item @var{internalformat}
3944 The internal format of the convolution filter kernel. The allowable
3945 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
3946 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
3947 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
3948 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3949 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3950 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3951 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3952 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3953 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3954 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3955 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3956 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3957 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3961 The window space coordinates of the lower-left coordinate of the pixel
3965 The width of the pixel array to copy.
3968 The height of the pixel array to copy.
3972 @code{glCopyConvolutionFilter2D} defines a two-dimensional convolution
3973 filter kernel with pixels from the current @code{GL_READ_BUFFER} (rather
3974 than from main memory, as is the case for @code{glConvolutionFilter2D}).
3976 The screen-aligned pixel rectangle with lower-left corner at (@var{x},\
3977 @var{y}), width @var{width} and height @var{height} is used to define
3978 the convolution filter. If any pixels within this region are outside
3979 the window that is associated with the GL context, the values obtained
3980 for those pixels are undefined.
3982 The pixels in the rectangle are processed exactly as if
3983 @code{glReadPixels} had been called with @var{format} set to RGBA, but
3984 the process stops just before final conversion. The R, G, B, and A
3985 components of each pixel are next scaled by the four 2D
3986 @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four 2D
3987 @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
3988 parameters are set by @code{glConvolutionParameter} using the
3989 @code{GL_CONVOLUTION_2D} target and the names
3990 @code{GL_CONVOLUTION_FILTER_SCALE} and
3991 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are
3992 vectors of four values that are applied to red, green, blue, and alpha,
3993 in that order.) The R, G, B, and A values are not clamped to [0,1] at
3994 any time during this process.
3996 Each pixel is then converted to the internal format specified by
3997 @var{internalformat}. This conversion simply maps the component values
3998 of the pixel (R, G, B, and A) to the values included in the internal
3999 format (red, green, blue, alpha, luminance, and intensity). The mapping
4005 @item @strong{Internal Format}
4006 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
4007 @strong{Luminance}, @strong{Intensity}
4009 @item @code{GL_ALPHA}
4012 @item @code{GL_LUMINANCE}
4015 @item @code{GL_LUMINANCE_ALPHA}
4018 @item @code{GL_INTENSITY}
4024 @item @code{GL_RGBA}
4029 The red, green, blue, alpha, luminance, and/or intensity components of
4030 the resulting pixels are stored in floating-point rather than integer
4033 Pixel ordering is such that lower x screen coordinates correspond to
4034 lower @var{i} filter image coordinates, and lower y screen coordinates
4035 correspond to lower @var{j} filter image coordinates.
4037 Note that after a convolution is performed, the resulting color
4038 components are also scaled by their corresponding
4039 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
4040 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
4041 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
4042 and @strong{ALPHA}). These parameters are set by
4043 @code{glPixelTransfer}.
4045 @code{GL_INVALID_ENUM} is generated if @var{target} is not
4046 @code{GL_CONVOLUTION_2D}.
4048 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
4049 of the allowable values.
4051 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
4052 greater than the maximum supported value. This value may be queried
4053 with @code{glGetConvolutionParameter} using target
4054 @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_WIDTH}.
4056 @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero
4057 or greater than the maximum supported value. This value may be queried
4058 with @code{glGetConvolutionParameter} using target
4059 @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}.
4061 @code{GL_INVALID_OPERATION} is generated if
4062 @code{glCopyConvolutionFilter2D} is executed between the execution of
4063 @code{glBegin} and the corresponding execution of @code{glEnd}.
4067 @deftypefun void glCopyPixels x y width height type
4068 Copy pixels in the frame buffer.
4073 Specify the window coordinates of the lower left corner of the
4074 rectangular region of pixels to be copied.
4078 Specify the dimensions of the rectangular region of pixels to be copied.
4079 Both must be nonnegative.
4082 Specifies whether color values, depth values, or stencil values are to
4083 be copied. Symbolic constants @code{GL_COLOR}, @code{GL_DEPTH}, and
4084 @code{GL_STENCIL} are accepted.
4088 @code{glCopyPixels} copies a screen-aligned rectangle of pixels from the
4089 specified frame buffer location to a region relative to the current
4090 raster position. Its operation is well defined only if the entire pixel
4091 source region is within the exposed portion of the window. Results of
4092 copies from outside the window, or from regions of the window that are
4093 not exposed, are hardware dependent and undefined.
4095 @var{x} and @var{y} specify the window coordinates of the lower left
4096 corner of the rectangular region to be copied. @var{width} and
4097 @var{height} specify the dimensions of the rectangular region to be
4098 copied. Both @var{width} and @var{height} must not be negative.
4100 Several parameters control the processing of the pixel data while it is
4101 being copied. These parameters are set with three commands:
4102 @code{glPixelTransfer}, @code{glPixelMap}, and @code{glPixelZoom}. This
4103 reference page describes the effects on @code{glCopyPixels} of most, but
4104 not all, of the parameters specified by these three commands.
4106 @code{glCopyPixels} copies values from each pixel with the lower
4107 left-hand corner at @r{(@var{x}+@var{i},@var{y}+@var{j})} for
4108 @r{0<=@var{i}<@var{width}} and @r{0<=@var{j}<@var{height}}. This pixel
4109 is said to be the @r{@var{i}}th pixel in the @r{@var{j}}th row. Pixels
4110 are copied in row order from the lowest to the highest row, left to
4113 @var{type} specifies whether color, depth, or stencil data is to be
4114 copied. The details of the transfer for each data type are as follows:
4117 @item @code{GL_COLOR}
4118 Indices or RGBA colors are read from the buffer currently specified as
4119 the read source buffer (see @code{glReadBuffer}). If the GL is in color
4120 index mode, each index that is read from this buffer is converted to a
4121 fixed-point format with an unspecified number of bits to the right of
4122 the binary point. Each index is then shifted left by
4123 @code{GL_INDEX_SHIFT} bits, and added to @code{GL_INDEX_OFFSET}. If
4124 @code{GL_INDEX_SHIFT} is negative, the shift is to the right. In either
4125 case, zero bits fill otherwise unspecified bit locations in the result.
4126 If @code{GL_MAP_COLOR} is true, the index is replaced with the value
4127 that it references in lookup table @code{GL_PIXEL_MAP_I_TO_I}. Whether
4128 the lookup replacement of the index is done or not, the integer part of
4129 the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the
4130 number of bits in a color index buffer.
4132 If the GL is in RGBA mode, the red, green, blue, and alpha components of
4133 each pixel that is read are converted to an internal floating-point
4134 format with unspecified precision. The conversion maps the largest
4135 representable component value to 1.0, and component value 0 to 0.0. The
4136 resulting floating-point color values are then multiplied by
4137 @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is RED,
4138 GREEN, BLUE, and ALPHA for the respective color components. The results
4139 are clamped to the range [0,1]. If @code{GL_MAP_COLOR} is true, each
4140 color component is scaled by the size of lookup table
4141 @code{GL_PIXEL_MAP_c_TO_c}, then replaced by the value that it
4142 references in that table. @var{c} is R, G, B, or A.
4144 If the @code{ARB_imaging} extension is supported, the color values may
4145 be additionally processed by color-table lookups, color-matrix
4146 transformations, and convolution filters.
4148 The GL then converts the resulting indices or RGBA colors to fragments
4149 by attaching the current raster position @var{z} coordinate and texture
4150 coordinates to each pixel, then assigning window coordinates
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 and the pixel was the @r{@var{i}}th pixel in the @r{@var{j}}th row.
4154 These pixel fragments are then treated just like the fragments generated
4155 by rasterizing points, lines, or polygons. Texture mapping, fog, and
4156 all the fragment operations are applied before the fragments are written
4157 to the frame buffer.
4159 @item @code{GL_DEPTH}
4160 Depth values are read from the depth buffer and converted directly to an
4161 internal floating-point format with unspecified precision. The
4162 resulting floating-point depth value is then multiplied by
4163 @code{GL_DEPTH_SCALE} and added to @code{GL_DEPTH_BIAS}. The result is
4164 clamped to the range [0,1].
4166 The GL then converts the resulting depth components to fragments by
4167 attaching the current raster position color or color index and texture
4168 coordinates to each pixel, then assigning window coordinates
4169 @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where
4170 @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position,
4171 and the pixel was the @r{@var{i}}th pixel in the @r{@var{j}}th row.
4172 These pixel fragments are then treated just like the fragments generated
4173 by rasterizing points, lines, or polygons. Texture mapping, fog, and
4174 all the fragment operations are applied before the fragments are written
4175 to the frame buffer.
4177 @item @code{GL_STENCIL}
4178 Stencil indices are read from the stencil buffer and converted to an
4179 internal fixed-point format with an unspecified number of bits to the
4180 right of the binary point. Each fixed-point index is then shifted left
4181 by @code{GL_INDEX_SHIFT} bits, and added to @code{GL_INDEX_OFFSET}. If
4182 @code{GL_INDEX_SHIFT} is negative, the shift is to the right. In either
4183 case, zero bits fill otherwise unspecified bit locations in the result.
4184 If @code{GL_MAP_STENCIL} is true, the index is replaced with the value
4185 that it references in lookup table @code{GL_PIXEL_MAP_S_TO_S}. Whether
4186 the lookup replacement of the index is done or not, the integer part of
4187 the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the
4188 number of bits in the stencil buffer. The resulting stencil indices are
4189 then written to the stencil buffer such that the index read from the
4190 @r{@var{i}}th location of the @r{@var{j}}th row is written to location
4191 @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where
4192 @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position.
4193 Only the pixel ownership test, the scissor test, and the stencil
4194 writemask affect these write operations.
4198 The rasterization described thus far assumes pixel zoom factors of 1.0.
4199 If @code{glPixelZoom} is used to change the @r{@var{x}} and @r{@var{y}}
4200 pixel zoom factors, pixels are converted to fragments as follows. If
4201 @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position,
4202 and a given pixel is in the @r{@var{i}}th location in the @r{@var{j}}th
4203 row of the source pixel rectangle, then fragments are generated for
4204 pixels whose centers are in the rectangle with corners at
4206 @r{(@var{x}_@var{r}+@var{zoom}_@var{x},@var{i},@var{y}_@var{r}+@var{zoom}_@var{y},@var{j})}
4210 @r{(@var{x}_@var{r}+@var{zoom}_@var{x},(@var{i}+1,),@var{y}_@var{r}+@var{zoom}_@var{y},(@var{j}+1,))}
4212 where @r{@var{zoom}_@var{x}} is the value of @code{GL_ZOOM_X} and
4213 @r{@var{zoom}_@var{y}} is the value of @code{GL_ZOOM_Y}.
4215 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
4218 @code{GL_INVALID_VALUE} is generated if either @var{width} or
4219 @var{height} is negative.
4221 @code{GL_INVALID_OPERATION} is generated if @var{type} is
4222 @code{GL_DEPTH} and there is no depth buffer.
4224 @code{GL_INVALID_OPERATION} is generated if @var{type} is
4225 @code{GL_STENCIL} and there is no stencil buffer.
4227 @code{GL_INVALID_OPERATION} is generated if @code{glCopyPixels} is
4228 executed between the execution of @code{glBegin} and the corresponding
4229 execution of @code{glEnd}.
4233 @deftypefun void glCopyTexImage1D target level internalformat x y width border
4234 Copy pixels into a 1D texture image.
4238 Specifies the target texture. Must be @code{GL_TEXTURE_1D}.
4241 Specifies the level-of-detail number. Level 0 is the base image level.
4242 Level @var{n} is the @var{n}th mipmap reduction image.
4244 @item @var{internalformat}
4245 Specifies the internal format of the texture. Must be one of the
4246 following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4},
4247 @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16},
4248 @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_LUMINANCE},
4249 @code{GL_COMPRESSED_LUMINANCE_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
4250 @code{GL_COMPRESSED_RGB}, @code{GL_COMPRESSED_RGBA},
4251 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
4252 @code{GL_DEPTH_COMPONENT24}, @code{GL_DEPTH_COMPONENT32},
4253 @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8},
4254 @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
4255 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
4256 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
4257 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
4258 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
4259 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_RGB},
4260 @code{GL_R3_G3_B2}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
4261 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
4262 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
4263 @code{GL_RGB10_A2}, @code{GL_RGBA12}, @code{GL_RGBA16},
4264 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
4265 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
4266 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
4270 Specify the window coordinates of the left corner of the row of pixels
4274 Specifies the width of the texture image. Must be 0 or
4275 @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. The
4276 height of the texture image is 1.
4279 Specifies the width of the border. Must be either 0 or 1.
4283 @code{glCopyTexImage1D} defines a one-dimensional texture image with
4284 pixels from the current @code{GL_READ_BUFFER}.
4286 The screen-aligned pixel row with left corner at @r{(@var{x},@var{y})}
4287 and with a length of @r{@var{width}+2(@var{border},)} defines the
4288 texture array at the mipmap level specified by @var{level}.
4289 @var{internalformat} specifies the internal format of the texture array.
4291 The pixels in the row are processed exactly as if @code{glCopyPixels}
4292 had been called, but the process stops just before final conversion. At
4293 this point all pixel component values are clamped to the range @r{[0,1]}
4294 and then converted to the texture's internal format for storage in the
4297 Pixel ordering is such that lower @r{@var{x}} screen coordinates
4298 correspond to lower texture coordinates.
4300 If any of the pixels within the specified row of the current
4301 @code{GL_READ_BUFFER} are outside the window associated with the current
4302 rendering context, then the values obtained for those pixels are
4305 @code{glCopyTexImage1D} defines a one-dimensional texture image with
4306 pixels from the current @code{GL_READ_BUFFER}.
4308 When @var{internalformat} is one of the sRGB types, the GL does not
4309 automatically convert the source pixels to the sRGB color space. In
4310 this case, the @code{glPixelMap} function can be used to accomplish the
4313 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
4316 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4318 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
4319 @r{@var{log}_2@var{max}}, where @r{@var{max}} is the returned value of
4320 @code{GL_MAX_TEXTURE_SIZE}.
4322 @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not an
4325 @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or
4326 greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
4328 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
4329 not supported and the @var{width} cannot be represented as
4330 @r{2^@var{n}+2(@var{border},)} for some integer value of @var{n}.
4332 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
4334 @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexImage1D} is
4335 executed between the execution of @code{glBegin} and the corresponding
4336 execution of @code{glEnd}.
4338 @code{GL_INVALID_OPERATION} is generated if @var{internalformat} is
4339 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
4340 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32} and there is
4345 @deftypefun void glCopyTexImage2D target level internalformat x y width height border
4346 Copy pixels into a 2D texture image.
4350 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
4351 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
4352 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
4353 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
4354 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
4355 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
4356 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
4359 Specifies the level-of-detail number. Level 0 is the base image level.
4360 Level @var{n} is the @var{n}th mipmap reduction image.
4362 @item @var{internalformat}
4363 Specifies the internal format of the texture. Must be one of the
4364 following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4},
4365 @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16},
4366 @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_LUMINANCE},
4367 @code{GL_COMPRESSED_LUMINANCE_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
4368 @code{GL_COMPRESSED_RGB}, @code{GL_COMPRESSED_RGBA},
4369 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
4370 @code{GL_DEPTH_COMPONENT24}, @code{GL_DEPTH_COMPONENT32},
4371 @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8},
4372 @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
4373 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
4374 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
4375 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
4376 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
4377 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_RGB},
4378 @code{GL_R3_G3_B2}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
4379 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
4380 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
4381 @code{GL_RGB10_A2}, @code{GL_RGBA12}, @code{GL_RGBA16},
4382 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
4383 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
4384 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
4388 Specify the window coordinates of the lower left corner of the
4389 rectangular region of pixels to be copied.
4392 Specifies the width of the texture image. Must be 0 or
4393 @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}.
4396 Specifies the height of the texture image. Must be 0 or
4397 @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}.
4400 Specifies the width of the border. Must be either 0 or 1.
4404 @code{glCopyTexImage2D} defines a two-dimensional texture image, or
4405 cube-map texture image with pixels from the current
4406 @code{GL_READ_BUFFER}.
4408 The screen-aligned pixel rectangle with lower left corner at (@var{x},
4409 @var{y}) and with a width of @r{@var{width}+2(@var{border},)} and a
4410 height of @r{@var{height}+2(@var{border},)} defines the texture array
4411 at the mipmap level specified by @var{level}. @var{internalformat}
4412 specifies the internal format of the texture array.
4414 The pixels in the rectangle are processed exactly as if
4415 @code{glCopyPixels} had been called, but the process stops just before
4416 final conversion. At this point all pixel component values are clamped
4417 to the range @r{[0,1]} and then converted to the texture's internal
4418 format for storage in the texel array.
4420 Pixel ordering is such that lower @r{@var{x}} and @r{@var{y}} screen
4421 coordinates correspond to lower @r{@var{s}} and @r{@var{t}} texture
4424 If any of the pixels within the specified rectangle of the current
4425 @code{GL_READ_BUFFER} are outside the window associated with the current
4426 rendering context, then the values obtained for those pixels are
4429 When @var{internalformat} is one of the sRGB types, the GL does not
4430 automatically convert the source pixels to the sRGB color space. In
4431 this case, the @code{glPixelMap} function can be used to accomplish the
4434 @code{GL_INVALID_ENUM} is generated if @var{target} is not
4435 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
4436 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
4437 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
4438 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
4439 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
4440 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
4442 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4444 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
4445 @r{@var{log}_2@var{max}}, where @r{@var{max}} is the returned value of
4446 @code{GL_MAX_TEXTURE_SIZE}.
4448 @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or
4449 greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
4451 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
4452 not supported and the @var{width} or @var{depth} cannot be represented
4453 as @r{2^@var{k}+2(@var{border},)} for some integer @r{@var{k}}.
4455 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
4457 @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not an
4460 @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexImage2D} is
4461 executed between the execution of @code{glBegin} and the corresponding
4462 execution of @code{glEnd}.
4464 @code{GL_INVALID_OPERATION} is generated if @var{internalformat} is
4465 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
4466 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32} and there is
4471 @deftypefun void glCopyTexSubImage1D target level xoffset x y width
4472 Copy a one-dimensional texture subimage.
4476 Specifies the target texture. Must be @code{GL_TEXTURE_1D}.
4479 Specifies the level-of-detail number. Level 0 is the base image level.
4480 Level @var{n} is the @var{n}th mipmap reduction image.
4483 Specifies the texel offset within the texture array.
4487 Specify the window coordinates of the left corner of the row of pixels
4491 Specifies the width of the texture subimage.
4495 @code{glCopyTexSubImage1D} replaces a portion of a one-dimensional
4496 texture image with pixels from the current @code{GL_READ_BUFFER} (rather
4497 than from main memory, as is the case for @code{glTexSubImage1D}).
4499 The screen-aligned pixel row with left corner at (@var{x},\ @var{y}),
4500 and with length @var{width} replaces the portion of the texture array
4501 with x indices @var{xoffset} through @r{@var{xoffset}+@var{width}-1},
4502 inclusive. The destination in the texture array may not include any
4503 texels outside the texture array as it was originally specified.
4505 The pixels in the row are processed exactly as if @code{glCopyPixels}
4506 had been called, but the process stops just before final conversion. At
4507 this point, all pixel component values are clamped to the range
4508 @r{[0,1]} and then converted to the texture's internal format for
4509 storage in the texel array.
4511 It is not an error to specify a subtexture with zero width, but such a
4512 specification has no effect. If any of the pixels within the specified
4513 row of the current @code{GL_READ_BUFFER} are outside the read window
4514 associated with the current rendering context, then the values obtained
4515 for those pixels are undefined.
4517 No change is made to the @var{internalformat}, @var{width}, or
4518 @var{border} parameters of the specified texture array or to texel
4519 values outside the specified subregion.
4521 @code{GL_INVALID_ENUM} is generated if /@var{target} is not
4522 @code{GL_TEXTURE_1D}.
4524 @code{GL_INVALID_OPERATION} is generated if the texture array has not
4525 been defined by a previous @code{glTexImage1D} or
4526 @code{glCopyTexImage1D} operation.
4528 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4530 @code{GL_INVALID_VALUE} may be generated if
4531 @r{@var{level}>@var{log}_2(@var{max},)}, where @var{max} is the
4532 returned value of @code{GL_MAX_TEXTURE_SIZE}.
4534 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, or
4535 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, where @r{@var{w}}
4536 is the @code{GL_TEXTURE_WIDTH} and @r{@var{b}} is the
4537 @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that
4538 @r{@var{w}} includes twice the border width.
4544 @deftypefun void glCopyTexSubImage2D target level xoffset yoffset x y width height
4545 Copy a two-dimensional texture subimage.
4549 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
4550 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
4551 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
4552 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
4553 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
4554 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
4555 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
4558 Specifies the level-of-detail number. Level 0 is the base image level.
4559 Level @var{n} is the @var{n}th mipmap reduction image.
4562 Specifies a texel offset in the x direction within the texture array.
4565 Specifies a texel offset in the y direction within the texture array.
4569 Specify the window coordinates of the lower left corner of the
4570 rectangular region of pixels to be copied.
4573 Specifies the width of the texture subimage.
4576 Specifies the height of the texture subimage.
4580 @code{glCopyTexSubImage2D} replaces a rectangular portion of a
4581 two-dimensional texture image or cube-map texture image with pixels from
4582 the current @code{GL_READ_BUFFER} (rather than from main memory, as is
4583 the case for @code{glTexSubImage2D}).
4585 The screen-aligned pixel rectangle with lower left corner at
4586 @r{(@var{x},@var{y})} and with width @var{width} and height @var{height}
4587 replaces the portion of the texture array with x indices @var{xoffset}
4588 through @r{@var{xoffset}+@var{width}-1}, inclusive, and y indices
4589 @var{yoffset} through @r{@var{yoffset}+@var{height}-1}, inclusive, at
4590 the mipmap level specified by @var{level}.
4592 The pixels in the rectangle are processed exactly as if
4593 @code{glCopyPixels} had been called, but the process stops just before
4594 final conversion. At this point, all pixel component values are clamped
4595 to the range @r{[0,1]} and then converted to the texture's internal
4596 format for storage in the texel array.
4598 The destination rectangle in the texture array may not include any
4599 texels outside the texture array as it was originally specified. It is
4600 not an error to specify a subtexture with zero width or height, but such
4601 a specification has no effect.
4603 If any of the pixels within the specified rectangle of the current
4604 @code{GL_READ_BUFFER} are outside the read window associated with the
4605 current rendering context, then the values obtained for those pixels are
4608 No change is made to the @var{internalformat}, @var{width},
4609 @var{height}, or @var{border} parameters of the specified texture array
4610 or to texel values outside the specified subregion.
4612 @code{GL_INVALID_ENUM} is generated if @var{target} is not
4613 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
4614 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
4615 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
4616 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
4617 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
4618 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
4620 @code{GL_INVALID_OPERATION} is generated if the texture array has not
4621 been defined by a previous @code{glTexImage2D} or
4622 @code{glCopyTexImage2D} operation.
4624 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4626 @code{GL_INVALID_VALUE} may be generated if
4627 @r{@var{level}>@var{log}_2(@var{max},)}, where @r{@var{max}} is the
4628 returned value of @code{GL_MAX_TEXTURE_SIZE}.
4630 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}},
4631 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)},
4632 @r{@var{yoffset}<-@var{b}}, or
4633 @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, where @r{@var{w}}
4634 is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the
4635 @code{GL_TEXTURE_HEIGHT}, and @r{@var{b}} is the
4636 @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that
4637 @r{@var{w}} and @r{@var{h}} include twice the border width.
4639 @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexSubImage2D}
4640 is executed between the execution of @code{glBegin} and the
4641 corresponding execution of @code{glEnd}.
4645 @deftypefun void glCopyTexSubImage3D target level xoffset yoffset zoffset x y width height
4646 Copy a three-dimensional texture subimage.
4650 Specifies the target texture. Must be @code{GL_TEXTURE_3D}
4653 Specifies the level-of-detail number. Level 0 is the base image level.
4654 Level @var{n} is the @var{n}th mipmap reduction image.
4657 Specifies a texel offset in the x direction within the texture array.
4660 Specifies a texel offset in the y direction within the texture array.
4663 Specifies a texel offset in the z direction within the texture array.
4667 Specify the window coordinates of the lower left corner of the
4668 rectangular region of pixels to be copied.
4671 Specifies the width of the texture subimage.
4674 Specifies the height of the texture subimage.
4678 @code{glCopyTexSubImage3D} replaces a rectangular portion of a
4679 three-dimensional texture image with pixels from the current
4680 @code{GL_READ_BUFFER} (rather than from main memory, as is the case for
4681 @code{glTexSubImage3D}).
4683 The screen-aligned pixel rectangle with lower left corner at (@var{x},\
4684 @var{y}) and with width @var{width} and height @var{height} replaces the
4685 portion of the texture array with x indices @var{xoffset} through
4686 @r{@var{xoffset}+@var{width}-1}, inclusive, and y indices @var{yoffset}
4687 through @r{@var{yoffset}+@var{height}-1}, inclusive, at z index
4688 @var{zoffset} and at the mipmap level specified by @var{level}.
4690 The pixels in the rectangle are processed exactly as if
4691 @code{glCopyPixels} had been called, but the process stops just before
4692 final conversion. At this point, all pixel component values are clamped
4693 to the range @r{[0,1]} and then converted to the texture's internal
4694 format for storage in the texel array.
4696 The destination rectangle in the texture array may not include any
4697 texels outside the texture array as it was originally specified. It is
4698 not an error to specify a subtexture with zero width or height, but such
4699 a specification has no effect.
4701 If any of the pixels within the specified rectangle of the current
4702 @code{GL_READ_BUFFER} are outside the read window associated with the
4703 current rendering context, then the values obtained for those pixels are
4706 No change is made to the @var{internalformat}, @var{width},
4707 @var{height}, @var{depth}, or @var{border} parameters of the specified
4708 texture array or to texel values outside the specified subregion.
4710 @code{GL_INVALID_ENUM} is generated if /@var{target} is not
4711 @code{GL_TEXTURE_3D}.
4713 @code{GL_INVALID_OPERATION} is generated if the texture array has not
4714 been defined by a previous @code{glTexImage3D} operation.
4716 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4718 @code{GL_INVALID_VALUE} may be generated if
4719 @r{@var{level}>@var{log}_2(@var{max},)}, where @r{@var{max}} is the
4720 returned value of @code{GL_MAX_3D_TEXTURE_SIZE}.
4722 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}},
4723 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)},
4724 @r{@var{yoffset}<-@var{b}},
4725 @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)},
4726 @r{@var{zoffset}<-@var{b}}, or
4727 @r{(@var{zoffset}+1,)>(@var{d}-@var{b},)}, where @r{@var{w}} is the
4728 @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the @code{GL_TEXTURE_HEIGHT},
4729 @r{@var{d}} is the @code{GL_TEXTURE_DEPTH}, and @r{@var{b}} is the
4730 @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that
4731 @r{@var{w}}, @r{@var{h}}, and @r{@var{d}} include twice the border
4734 @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexSubImage3D}
4735 is executed between the execution of @code{glBegin} and the
4736 corresponding execution of @code{glEnd}.
4740 @deftypefun GLuint glCreateProgram
4741 Creates a program object.
4743 @code{glCreateProgram} creates an empty program object and returns a
4744 non-zero value by which it can be referenced. A program object is an
4745 object to which shader objects can be attached. This provides a
4746 mechanism to specify the shader objects that will be linked to create a
4747 program. It also provides a means for checking the compatibility of the
4748 shaders that will be used to create a program (for instance, checking
4749 the compatibility between a vertex shader and a fragment shader). When
4750 no longer needed as part of a program object, shader objects can be
4753 One or more executables are created in a program object by successfully
4754 attaching shader objects to it with @code{glAttachShader}, successfully
4755 compiling the shader objects with @code{glCompileShader}, and
4756 successfully linking the program object with @code{glLinkProgram}. These
4757 executables are made part of current state when @code{glUseProgram} is
4758 called. Program objects can be deleted by calling
4759 @code{glDeleteProgram}. The memory associated with the program object
4760 will be deleted when it is no longer part of current rendering state for
4763 This function returns 0 if an error occurs creating the program object.
4765 @code{GL_INVALID_OPERATION} is generated if @code{glCreateProgram} is
4766 executed between the execution of @code{glBegin} and the corresponding
4767 execution of @code{glEnd}.
4771 @deftypefun GLuint glCreateShader shaderType
4772 Creates a shader object.
4775 @item @var{shaderType}
4776 Specifies the type of shader to be created. Must be either
4777 @code{GL_VERTEX_SHADER} or @code{GL_FRAGMENT_SHADER}.
4781 @code{glCreateShader} creates an empty shader object and returns a
4782 non-zero value by which it can be referenced. A shader object is used
4783 to maintain the source code strings that define a shader.
4784 @var{shaderType} indicates the type of shader to be created. Two types
4785 of shaders are supported. A shader of type @code{GL_VERTEX_SHADER} is a
4786 shader that is intended to run on the programmable vertex processor and
4787 replace the fixed functionality vertex processing in OpenGL. A shader
4788 of type @code{GL_FRAGMENT_SHADER} is a shader that is intended to run on
4789 the programmable fragment processor and replace the fixed functionality
4790 fragment processing in OpenGL.
4792 When created, a shader object's @code{GL_SHADER_TYPE} parameter is set
4793 to either @code{GL_VERTEX_SHADER} or @code{GL_FRAGMENT_SHADER},
4794 depending on the value of @var{shaderType}.
4796 This function returns 0 if an error occurs creating the shader object.
4798 @code{GL_INVALID_ENUM} is generated if @var{shaderType} is not an
4801 @code{GL_INVALID_OPERATION} is generated if @code{glCreateShader} is
4802 executed between the execution of @code{glBegin} and the corresponding
4803 execution of @code{glEnd}.
4807 @deftypefun void glCullFace mode
4808 Specify whether front- or back-facing facets can be culled.
4812 Specifies whether front- or back-facing facets are candidates for
4813 culling. Symbolic constants @code{GL_FRONT}, @code{GL_BACK}, and
4814 @code{GL_FRONT_AND_BACK} are accepted. The initial value is
4819 @code{glCullFace} specifies whether front- or back-facing facets are
4820 culled (as specified by @var{mode}) when facet culling is enabled. Facet
4821 culling is initially disabled. To enable and disable facet culling,
4822 call the @code{glEnable} and @code{glDisable} commands with the argument
4823 @code{GL_CULL_FACE}. Facets include triangles, quadrilaterals,
4824 polygons, and rectangles.
4826 @code{glFrontFace} specifies which of the clockwise and counterclockwise
4827 facets are front-facing and back-facing. See @code{glFrontFace}.
4829 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
4832 @code{GL_INVALID_OPERATION} is generated if @code{glCullFace} is
4833 executed between the execution of @code{glBegin} and the corresponding
4834 execution of @code{glEnd}.
4838 @deftypefun void glDeleteBuffers n buffers
4839 Delete named buffer objects.
4843 Specifies the number of buffer objects to be deleted.
4846 Specifies an array of buffer objects to be deleted.
4850 @code{glDeleteBuffers} deletes @var{n} buffer objects named by the
4851 elements of the array @var{buffers}. After a buffer object is deleted,
4852 it has no contents, and its name is free for reuse (for example by
4853 @code{glGenBuffers}). If a buffer object that is currently bound is
4854 deleted, the binding reverts to 0 (the absence of any buffer object,
4855 which reverts to client memory usage).
4857 @code{glDeleteBuffers} silently ignores 0's and names that do not
4858 correspond to existing buffer objects.
4860 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
4862 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteBuffers} is
4863 executed between the execution of @code{glBegin} and the corresponding
4864 execution of @code{glEnd}.
4868 @deftypefun void glDeleteLists list range
4869 Delete a contiguous group of display lists.
4873 Specifies the integer name of the first display list to delete.
4876 Specifies the number of display lists to delete.
4880 @code{glDeleteLists} causes a contiguous group of display lists to be
4881 deleted. @var{list} is the name of the first display list to be
4882 deleted, and @var{range} is the number of display lists to delete. All
4883 display lists @r{@var{d}} with
4884 @r{@var{list}<=@var{d}<=@var{list}+@var{range}-1} are deleted.
4886 All storage locations allocated to the specified display lists are
4887 freed, and the names are available for reuse at a later time. Names
4888 within the range that do not have an associated display list are
4889 ignored. If @var{range} is 0, nothing happens.
4891 @code{GL_INVALID_VALUE} is generated if @var{range} is negative.
4893 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteLists} is
4894 executed between the execution of @code{glBegin} and the corresponding
4895 execution of @code{glEnd}.
4899 @deftypefun void glDeleteProgram program
4900 Deletes a program object.
4904 Specifies the program object to be deleted.
4908 @code{glDeleteProgram} frees the memory and invalidates the name
4909 associated with the program object specified by @var{program.} This
4910 command effectively undoes the effects of a call to
4911 @code{glCreateProgram}.
4913 If a program object is in use as part of current rendering state, it
4914 will be flagged for deletion, but it will not be deleted until it is no
4915 longer part of current state for any rendering context. If a program
4916 object to be deleted has shader objects attached to it, those shader
4917 objects will be automatically detached but not deleted unless they have
4918 already been flagged for deletion by a previous call to
4919 @code{glDeleteShader}. A value of 0 for @var{program} will be silently
4922 To determine whether a program object has been flagged for deletion,
4923 call @code{glGetProgram} with arguments @var{program} and
4924 @code{GL_DELETE_STATUS}.
4926 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
4927 generated by OpenGL.
4929 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteProgram} is
4930 executed between the execution of @code{glBegin} and the corresponding
4931 execution of @code{glEnd}.
4935 @deftypefun void glDeleteQueries n ids
4936 Delete named query objects.
4940 Specifies the number of query objects to be deleted.
4943 Specifies an array of query objects to be deleted.
4947 @code{glDeleteQueries} deletes @var{n} query objects named by the
4948 elements of the array @var{ids}. After a query object is deleted, it
4949 has no contents, and its name is free for reuse (for example by
4950 @code{glGenQueries}).
4952 @code{glDeleteQueries} silently ignores 0's and names that do not
4953 correspond to existing query objects.
4955 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
4957 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteQueries} is
4958 executed between the execution of @code{glBegin} and the corresponding
4959 execution of @code{glEnd}.
4963 @deftypefun void glDeleteShader shader
4964 Deletes a shader object.
4968 Specifies the shader object to be deleted.
4972 @code{glDeleteShader} frees the memory and invalidates the name
4973 associated with the shader object specified by @var{shader}. This
4974 command effectively undoes the effects of a call to
4975 @code{glCreateShader}.
4977 If a shader object to be deleted is attached to a program object, it
4978 will be flagged for deletion, but it will not be deleted until it is no
4979 longer attached to any program object, for any rendering context (i.e.,
4980 it must be detached from wherever it was attached before it will be
4981 deleted). A value of 0 for @var{shader} will be silently ignored.
4983 To determine whether an object has been flagged for deletion, call
4984 @code{glGetShader} with arguments @var{shader} and
4985 @code{GL_DELETE_STATUS}.
4987 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
4988 generated by OpenGL.
4990 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteShader} is
4991 executed between the execution of @code{glBegin} and the corresponding
4992 execution of @code{glEnd}.
4996 @deftypefun void glDeleteTextures n textures
4997 Delete named textures.
5001 Specifies the number of textures to be deleted.
5003 @item @var{textures}
5004 Specifies an array of textures to be deleted.
5008 @code{glDeleteTextures} deletes @var{n} textures named by the elements
5009 of the array @var{textures}. After a texture is deleted, it has no
5010 contents or dimensionality, and its name is free for reuse (for example
5011 by @code{glGenTextures}). If a texture that is currently bound is
5012 deleted, the binding reverts to 0 (the default texture).
5014 @code{glDeleteTextures} silently ignores 0's and names that do not
5015 correspond to existing textures.
5017 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
5019 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteTextures} is
5020 executed between the execution of @code{glBegin} and the corresponding
5021 execution of @code{glEnd}.
5025 @deftypefun void glDepthFunc func
5026 Specify the value used for depth buffer comparisons.
5030 Specifies the depth comparison function. Symbolic constants
5031 @code{GL_NEVER}, @code{GL_LESS}, @code{GL_EQUAL}, @code{GL_LEQUAL},
5032 @code{GL_GREATER}, @code{GL_NOTEQUAL}, @code{GL_GEQUAL}, and
5033 @code{GL_ALWAYS} are accepted. The initial value is @code{GL_LESS}.
5037 @code{glDepthFunc} specifies the function used to compare each incoming
5038 pixel depth value with the depth value present in the depth buffer. The
5039 comparison is performed only if depth testing is enabled. (See
5040 @code{glEnable} and @code{glDisable} of @code{GL_DEPTH_TEST}.)
5042 @var{func} specifies the conditions under which the pixel will be drawn.
5043 The comparison functions are as follows:
5046 @item @code{GL_NEVER}
5049 @item @code{GL_LESS}
5050 Passes if the incoming depth value is less than the stored depth value.
5052 @item @code{GL_EQUAL}
5053 Passes if the incoming depth value is equal to the stored depth value.
5055 @item @code{GL_LEQUAL}
5056 Passes if the incoming depth value is less than or equal to the stored
5059 @item @code{GL_GREATER}
5060 Passes if the incoming depth value is greater than the stored depth
5063 @item @code{GL_NOTEQUAL}
5064 Passes if the incoming depth value is not equal to the stored depth
5067 @item @code{GL_GEQUAL}
5068 Passes if the incoming depth value is greater than or equal to the
5071 @item @code{GL_ALWAYS}
5076 The initial value of @var{func} is @code{GL_LESS}. Initially, depth
5077 testing is disabled. If depth testing is disabled or if no depth buffer
5078 exists, it is as if the depth test always passes.
5080 @code{GL_INVALID_ENUM} is generated if @var{func} is not an accepted
5083 @code{GL_INVALID_OPERATION} is generated if @code{glDepthFunc} is
5084 executed between the execution of @code{glBegin} and the corresponding
5085 execution of @code{glEnd}.
5089 @deftypefun void glDepthMask flag
5090 Enable or disable writing into the depth buffer.
5094 Specifies whether the depth buffer is enabled for writing. If
5095 @var{flag} is @code{GL_FALSE}, depth buffer writing is disabled.
5096 Otherwise, it is enabled. Initially, depth buffer writing is enabled.
5100 @code{glDepthMask} specifies whether the depth buffer is enabled for
5101 writing. If @var{flag} is @code{GL_FALSE}, depth buffer writing is
5102 disabled. Otherwise, it is enabled. Initially, depth buffer writing is
5105 @code{GL_INVALID_OPERATION} is generated if @code{glDepthMask} is
5106 executed between the execution of @code{glBegin} and the corresponding
5107 execution of @code{glEnd}.
5111 @deftypefun void glDepthRange nearVal farVal
5112 Specify mapping of depth values from normalized device coordinates to
5117 Specifies the mapping of the near clipping plane to window coordinates.
5118 The initial value is 0.
5121 Specifies the mapping of the far clipping plane to window coordinates.
5122 The initial value is 1.
5126 After clipping and division by @var{w}, depth coordinates range from
5127 @r{-1} to 1, corresponding to the near and far clipping planes.
5128 @code{glDepthRange} specifies a linear mapping of the normalized depth
5129 coordinates in this range to window depth coordinates. Regardless of
5130 the actual depth buffer implementation, window coordinate depth values
5131 are treated as though they range from 0 through 1 (like color
5132 components). Thus, the values accepted by @code{glDepthRange} are both
5133 clamped to this range before they are accepted.
5135 The setting of (0,1) maps the near plane to 0 and the far plane to 1.
5136 With this mapping, the depth buffer range is fully utilized.
5138 @code{GL_INVALID_OPERATION} is generated if @code{glDepthRange} is
5139 executed between the execution of @code{glBegin} and the corresponding
5140 execution of @code{glEnd}.
5144 @deftypefun void glDetachShader program shader
5145 Detaches a shader object from a program object to which it is attached.
5149 Specifies the program object from which to detach the shader object.
5152 Specifies the shader object to be detached.
5156 @code{glDetachShader} detaches the shader object specified by
5157 @var{shader} from the program object specified by @var{program}. This
5158 command can be used to undo the effect of the command
5159 @code{glAttachShader}.
5161 If @var{shader} has already been flagged for deletion by a call to
5162 @code{glDeleteShader} and it is not attached to any other program
5163 object, it will be deleted after it has been detached.
5165 @code{GL_INVALID_VALUE} is generated if either @var{program} or
5166 @var{shader} is a value that was not generated by OpenGL.
5168 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
5171 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
5174 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not attached
5177 @code{GL_INVALID_OPERATION} is generated if @code{glDetachShader} is
5178 executed between the execution of @code{glBegin} and the corresponding
5179 execution of @code{glEnd}.
5183 @deftypefun void glDrawArrays mode first count
5184 Render primitives from array data.
5188 Specifies what kind of primitives to render. Symbolic constants
5189 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
5190 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
5191 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
5192 @code{GL_POLYGON} are accepted.
5195 Specifies the starting index in the enabled arrays.
5198 Specifies the number of indices to be rendered.
5202 @code{glDrawArrays} specifies multiple geometric primitives with very
5203 few subroutine calls. Instead of calling a GL procedure to pass each
5204 individual vertex, normal, texture coordinate, edge flag, or color, you
5205 can prespecify separate arrays of vertices, normals, and colors and use
5206 them to construct a sequence of primitives with a single call to
5207 @code{glDrawArrays}.
5209 When @code{glDrawArrays} is called, it uses @var{count} sequential
5210 elements from each enabled array to construct a sequence of geometric
5211 primitives, beginning with element @var{first}. @var{mode} specifies
5212 what kind of primitives are constructed and how the array elements
5213 construct those primitives. If @code{GL_VERTEX_ARRAY} is not enabled,
5214 no geometric primitives are generated.
5216 Vertex attributes that are modified by @code{glDrawArrays} have an
5217 unspecified value after @code{glDrawArrays} returns. For example, if
5218 @code{GL_COLOR_ARRAY} is enabled, the value of the current color is
5219 undefined after @code{glDrawArrays} executes. Attributes that aren't
5220 modified remain well defined.
5222 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
5225 @code{GL_INVALID_VALUE} is generated if @var{count} is negative.
5227 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5228 name is bound to an enabled array and the buffer object's data store is
5231 @code{GL_INVALID_OPERATION} is generated if @code{glDrawArrays} is
5232 executed between the execution of @code{glBegin} and the corresponding
5237 @deftypefun void glDrawBuffers n bufs
5238 Specifies a list of color buffers to be drawn into.
5242 Specifies the number of buffers in @var{bufs}.
5245 Points to an array of symbolic constants specifying the buffers into
5246 which fragment colors or data values will be written.
5250 @code{glDrawBuffers} defines an array of buffers into which fragment
5251 color values or fragment data will be written. If no fragment shader is
5252 active, rendering operations will generate only one fragment color per
5253 fragment and it will be written into each of the buffers specified by
5254 @var{bufs}. If a fragment shader is active and it writes a value to the
5255 output variable @code{gl_FragColor}, then that value will be written
5256 into each of the buffers specified by @var{bufs}. If a fragment shader
5257 is active and it writes a value to one or more elements of the output
5258 array variable @code{gl_FragData[]}, then the value of
5259 @code{gl_FragData[0] } will be written into the first buffer specified
5260 by @var{bufs}, the value of @code{gl_FragData[1] } will be written into
5261 the second buffer specified by @var{bufs}, and so on up to
5262 @code{gl_FragData[n-1]}. The draw buffer used for @code{gl_FragData[n]}
5263 and beyond is implicitly set to be @code{GL_NONE}.
5265 The symbolic constants contained in @var{bufs} may be any of the
5269 @item @code{GL_NONE}
5270 The fragment color/data value is not written into any color buffer.
5272 @item @code{GL_FRONT_LEFT}
5273 The fragment color/data value is written into the front left color
5276 @item @code{GL_FRONT_RIGHT}
5277 The fragment color/data value is written into the front right color
5280 @item @code{GL_BACK_LEFT}
5281 The fragment color/data value is written into the back left color
5284 @item @code{GL_BACK_RIGHT}
5285 The fragment color/data value is written into the back right color
5288 @item @code{GL_AUXi}
5289 The fragment color/data value is written into auxiliary buffer @code{i}.
5293 Except for @code{GL_NONE}, the preceding symbolic constants may not
5294 appear more than once in @var{bufs}. The maximum number of draw buffers
5295 supported is implementation dependent and can be queried by calling
5296 @code{glGet} with the argument @code{GL_MAX_DRAW_BUFFERS}. The number
5297 of auxiliary buffers can be queried by calling @code{glGet} with the
5298 argument @code{GL_AUX_BUFFERS}.
5300 @code{GL_INVALID_ENUM} is generated if one of the values in @var{bufs}
5301 is not an accepted value.
5303 @code{GL_INVALID_ENUM} is generated if @var{n} is less than 0.
5305 @code{GL_INVALID_OPERATION} is generated if a symbolic constant other
5306 than @code{GL_NONE} appears more than once in @var{bufs}.
5308 @code{GL_INVALID_OPERATION} is generated if any of the entries in
5309 @var{bufs} (other than @code{GL_NONE} ) indicates a color buffer that
5310 does not exist in the current GL context.
5312 @code{GL_INVALID_VALUE} is generated if @var{n} is greater than
5313 @code{GL_MAX_DRAW_BUFFERS}.
5315 @code{GL_INVALID_OPERATION} is generated if @code{glDrawBuffers} is
5316 executed between the execution of @code{glBegin} and the corresponding
5317 execution of @code{glEnd}.
5321 @deftypefun void glDrawBuffer mode
5322 Specify which color buffers are to be drawn into.
5326 Specifies up to four color buffers to be drawn into. Symbolic constants
5327 @code{GL_NONE}, @code{GL_FRONT_LEFT}, @code{GL_FRONT_RIGHT},
5328 @code{GL_BACK_LEFT}, @code{GL_BACK_RIGHT}, @code{GL_FRONT},
5329 @code{GL_BACK}, @code{GL_LEFT}, @code{GL_RIGHT},
5330 @code{GL_FRONT_AND_BACK}, and @code{GL_AUX}@var{i}, where @var{i} is
5331 between 0 and the value of @code{GL_AUX_BUFFERS} minus 1, are accepted.
5332 (@code{GL_AUX_BUFFERS} is not the upper limit; use @code{glGet} to query
5333 the number of available aux buffers.) The initial value is
5334 @code{GL_FRONT} for single-buffered contexts, and @code{GL_BACK} for
5335 double-buffered contexts.
5339 When colors are written to the frame buffer, they are written into the
5340 color buffers specified by @code{glDrawBuffer}. The specifications are
5344 @item @code{GL_NONE}
5345 No color buffers are written.
5347 @item @code{GL_FRONT_LEFT}
5348 Only the front left color buffer is written.
5350 @item @code{GL_FRONT_RIGHT}
5351 Only the front right color buffer is written.
5353 @item @code{GL_BACK_LEFT}
5354 Only the back left color buffer is written.
5356 @item @code{GL_BACK_RIGHT}
5357 Only the back right color buffer is written.
5359 @item @code{GL_FRONT}
5360 Only the front left and front right color buffers are written. If there
5361 is no front right color buffer, only the front left color buffer is
5364 @item @code{GL_BACK}
5365 Only the back left and back right color buffers are written. If there
5366 is no back right color buffer, only the back left color buffer is
5369 @item @code{GL_LEFT}
5370 Only the front left and back left color buffers are written. If there
5371 is no back left color buffer, only the front left color buffer is
5374 @item @code{GL_RIGHT}
5375 Only the front right and back right color buffers are written. If there
5376 is no back right color buffer, only the front right color buffer is
5379 @item @code{GL_FRONT_AND_BACK}
5380 All the front and back color buffers (front left, front right, back
5381 left, back right) are written. If there are no back color buffers, only
5382 the front left and front right color buffers are written. If there are
5383 no right color buffers, only the front left and back left color buffers
5384 are written. If there are no right or back color buffers, only the
5385 front left color buffer is written.
5387 @item @code{GL_AUX}@var{i}
5388 Only auxiliary color buffer @var{i} is written.
5392 If more than one color buffer is selected for drawing, then blending or
5393 logical operations are computed and applied independently for each color
5394 buffer and can produce different results in each buffer.
5396 Monoscopic contexts include only @var{left} buffers, and stereoscopic
5397 contexts include both @var{left} and @var{right} buffers. Likewise,
5398 single-buffered contexts include only @var{front} buffers, and
5399 double-buffered contexts include both @var{front} and @var{back}
5400 buffers. The context is selected at GL initialization.
5402 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
5405 @code{GL_INVALID_OPERATION} is generated if none of the buffers
5406 indicated by @var{mode} exists.
5408 @code{GL_INVALID_OPERATION} is generated if @code{glDrawBuffer} is
5409 executed between the execution of @code{glBegin} and the corresponding
5410 execution of @code{glEnd}.
5414 @deftypefun void glDrawElements mode count type indices
5415 Render primitives from array data.
5419 Specifies what kind of primitives to render. Symbolic constants
5420 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
5421 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
5422 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
5423 @code{GL_POLYGON} are accepted.
5426 Specifies the number of elements to be rendered.
5429 Specifies the type of the values in @var{indices}. Must be one of
5430 @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or
5431 @code{GL_UNSIGNED_INT}.
5434 Specifies a pointer to the location where the indices are stored.
5438 @code{glDrawElements} specifies multiple geometric primitives with very
5439 few subroutine calls. Instead of calling a GL function to pass each
5440 individual vertex, normal, texture coordinate, edge flag, or color, you
5441 can prespecify separate arrays of vertices, normals, and so on, and use
5442 them to construct a sequence of primitives with a single call to
5443 @code{glDrawElements}.
5445 When @code{glDrawElements} is called, it uses @var{count} sequential
5446 elements from an enabled array, starting at @var{indices} to construct a
5447 sequence of geometric primitives. @var{mode} specifies what kind of
5448 primitives are constructed and how the array elements construct these
5449 primitives. If more than one array is enabled, each is used. If
5450 @code{GL_VERTEX_ARRAY} is not enabled, no geometric primitives are
5453 Vertex attributes that are modified by @code{glDrawElements} have an
5454 unspecified value after @code{glDrawElements} returns. For example, if
5455 @code{GL_COLOR_ARRAY} is enabled, the value of the current color is
5456 undefined after @code{glDrawElements} executes. Attributes that aren't
5457 modified maintain their previous values.
5459 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
5462 @code{GL_INVALID_VALUE} is generated if @var{count} is negative.
5464 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5465 name is bound to an enabled array or the element array and the buffer
5466 object's data store is currently mapped.
5468 @code{GL_INVALID_OPERATION} is generated if @code{glDrawElements} is
5469 executed between the execution of @code{glBegin} and the corresponding
5474 @deftypefun void glDrawPixels width height format type data
5475 Write a block of pixels to the frame buffer.
5480 Specify the dimensions of the pixel rectangle to be written into the
5484 Specifies the format of the pixel data. Symbolic constants
5485 @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX},
5486 @code{GL_DEPTH_COMPONENT}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA},
5487 @code{GL_BGRA}, @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE},
5488 @code{GL_ALPHA}, @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA} are
5492 Specifies the data type for @var{data}. Symbolic constants
5493 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
5494 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
5495 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
5496 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
5497 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
5498 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
5499 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
5500 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
5501 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
5504 Specifies a pointer to the pixel data.
5508 @code{glDrawPixels} reads pixel data from memory and writes it into the
5509 frame buffer relative to the current raster position, provided that the
5510 raster position is valid. Use @code{glRasterPos} or @code{glWindowPos}
5511 to set the current raster position; use @code{glGet} with argument
5512 @code{GL_CURRENT_RASTER_POSITION_VALID} to determine if the specified
5513 raster position is valid, and @code{glGet} with argument
5514 @code{GL_CURRENT_RASTER_POSITION} to query the raster position.
5516 Several parameters define the encoding of pixel data in memory and
5517 control the processing of the pixel data before it is placed in the
5518 frame buffer. These parameters are set with four commands:
5519 @code{glPixelStore}, @code{glPixelTransfer}, @code{glPixelMap}, and
5520 @code{glPixelZoom}. This reference page describes the effects on
5521 @code{glDrawPixels} of many, but not all, of the parameters specified by
5522 these four commands.
5524 Data is read from @var{data} as a sequence of signed or unsigned bytes,
5525 signed or unsigned shorts, signed or unsigned integers, or
5526 single-precision floating-point values, depending on @var{type}. When
5527 @var{type} is one of @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE},
5528 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
5529 @code{GL_INT}, or @code{GL_FLOAT} each of these bytes, shorts, integers,
5530 or floating-point values is interpreted as one color or depth component,
5531 or one index, depending on @var{format}. When @var{type} is one of
5532 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_SHORT_5_6_5},
5533 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
5534 @code{GL_UNSIGNED_INT_8_8_8_8}, or @code{GL_UNSIGNED_INT_10_10_10_2},
5535 each unsigned value is interpreted as containing all the components for
5536 a single pixel, with the color components arranged according to
5537 @var{format}. When @var{type} is one of
5538 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
5539 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
5540 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
5541 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, or
5542 @code{GL_UNSIGNED_INT_2_10_10_10_REV}, each unsigned value is
5543 interpreted as containing all color components, specified by
5544 @var{format}, for a single pixel in a reversed order. Indices are
5545 always treated individually. Color components are treated as groups of
5546 one, two, three, or four values, again based on @var{format}. Both
5547 individual indices and groups of components are referred to as pixels.
5548 If @var{type} is @code{GL_BITMAP}, the data must be unsigned bytes, and
5549 @var{format} must be either @code{GL_COLOR_INDEX} or
5550 @code{GL_STENCIL_INDEX}. Each unsigned byte is treated as eight 1-bit
5551 pixels, with bit ordering determined by @code{GL_UNPACK_LSB_FIRST} (see
5552 @code{glPixelStore}).
5554 @r{@var{width}×@var{height}} pixels are read from memory, starting at
5555 location @var{data}. By default, these pixels are taken from adjacent
5556 memory locations, except that after all @var{width} pixels are read, the
5557 read pointer is advanced to the next four-byte boundary. The four-byte
5558 row alignment is specified by @code{glPixelStore} with argument
5559 @code{GL_UNPACK_ALIGNMENT}, and it can be set to one, two, four, or
5560 eight bytes. Other pixel store parameters specify different read
5561 pointer advancements, both before the first pixel is read and after all
5562 @var{width} pixels are read. See the @code{glPixelStore} reference page
5563 for details on these options.
5565 If a non-zero named buffer object is bound to the
5566 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
5567 block of pixels is specified, @var{data} is treated as a byte offset
5568 into the buffer object's data store.
5570 The @r{@var{width}×@var{height}} pixels that are read from memory are
5571 each operated on in the same way, based on the values of several
5572 parameters specified by @code{glPixelTransfer} and @code{glPixelMap}.
5573 The details of these operations, as well as the target buffer into which
5574 the pixels are drawn, are specific to the format of the pixels, as
5575 specified by @var{format}. @var{format} can assume one of 13 symbolic
5579 @item @code{GL_COLOR_INDEX}
5580 Each pixel is a single value, a color index. It is converted to
5581 fixed-point format, with an unspecified number of bits to the right of
5582 the binary point, regardless of the memory data type. Floating-point
5583 values convert to true fixed-point values. Signed and unsigned integer
5584 data is converted with all fraction bits set to 0. Bitmap data convert
5587 Each fixed-point index is then shifted left by @code{GL_INDEX_SHIFT}
5588 bits and added to @code{GL_INDEX_OFFSET}. If @code{GL_INDEX_SHIFT} is
5589 negative, the shift is to the right. In either case, zero bits fill
5590 otherwise unspecified bit locations in the result.
5592 If the GL is in RGBA mode, the resulting index is converted to an RGBA
5593 pixel with the help of the @code{GL_PIXEL_MAP_I_TO_R},
5594 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
5595 @code{GL_PIXEL_MAP_I_TO_A} tables. If the GL is in color index mode,
5596 and if @code{GL_MAP_COLOR} is true, the index is replaced with the value
5597 that it references in lookup table @code{GL_PIXEL_MAP_I_TO_I}. Whether
5598 the lookup replacement of the index is done or not, the integer part of
5599 the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the
5600 number of bits in a color index buffer.
5602 The GL then converts the resulting indices or RGBA colors to fragments
5603 by attaching the current raster position @var{z} coordinate and texture
5604 coordinates to each pixel, then assigning @r{@var{x}} and @r{@var{y}}
5605 window coordinates to the @r{@var{n}}th fragment such that
5606 @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},⌋}
5608 where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster
5609 position. These pixel fragments are then treated just like the
5610 fragments generated by rasterizing points, lines, or polygons. Texture
5611 mapping, fog, and all the fragment operations are applied before the
5612 fragments are written to the frame buffer.
5614 @item @code{GL_STENCIL_INDEX}
5615 Each pixel is a single value, a stencil index. It is converted to
5616 fixed-point format, with an unspecified number of bits to the right of
5617 the binary point, regardless of the memory data type. Floating-point
5618 values convert to true fixed-point values. Signed and unsigned integer
5619 data is converted with all fraction bits set to 0. Bitmap data convert
5622 Each fixed-point index is then shifted left by @code{GL_INDEX_SHIFT}
5623 bits, and added to @code{GL_INDEX_OFFSET}. If @code{GL_INDEX_SHIFT} is
5624 negative, the shift is to the right. In either case, zero bits fill
5625 otherwise unspecified bit locations in the result. If
5626 @code{GL_MAP_STENCIL} is true, the index is replaced with the value that
5627 it references in lookup table @code{GL_PIXEL_MAP_S_TO_S}. Whether the
5628 lookup replacement of the index is done or not, the integer part of the
5629 index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the
5630 number of bits in the stencil buffer. The resulting stencil indices are
5631 then written to the stencil buffer such that the @r{@var{n}}th index is
5634 @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},⌋}
5636 where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster
5637 position. Only the pixel ownership test, the scissor test, and the
5638 stencil writemask affect these write operations.
5640 @item @code{GL_DEPTH_COMPONENT}
5641 Each pixel is a single-depth component. Floating-point data is
5642 converted directly to an internal floating-point format with unspecified
5643 precision. Signed integer data is mapped linearly to the internal
5644 floating-point format such that the most positive representable integer
5645 value maps to 1.0, and the most negative representable value maps to
5646 @r{-1.0}. Unsigned integer data is mapped similarly: the largest
5647 integer value maps to 1.0, and 0 maps to 0.0. The resulting
5648 floating-point depth value is then multiplied by @code{GL_DEPTH_SCALE}
5649 and added to @code{GL_DEPTH_BIAS}. The result is clamped to the range
5652 The GL then converts the resulting depth components to fragments by
5653 attaching the current raster position color or color index and texture
5654 coordinates to each pixel, then assigning @r{@var{x}} and @r{@var{y}}
5655 window coordinates to the @r{@var{n}}th fragment such that
5657 @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},⌋}
5659 where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster
5660 position. These pixel fragments are then treated just like the
5661 fragments generated by rasterizing points, lines, or polygons. Texture
5662 mapping, fog, and all the fragment operations are applied before the
5663 fragments are written to the frame buffer.
5665 @item @code{GL_RGBA}
5666 @item @code{GL_BGRA}
5667 Each pixel is a four-component group: For @code{GL_RGBA}, the red
5668 component is first, followed by green, followed by blue, followed by
5669 alpha; for @code{GL_BGRA} the order is blue, green, red and then alpha.
5670 Floating-point values are converted directly to an internal
5671 floating-point format with unspecified precision. Signed integer values
5672 are mapped linearly to the internal floating-point format such that the
5673 most positive representable integer value maps to 1.0, and the most
5674 negative representable value maps to @r{-1.0}. (Note that this mapping
5675 does not convert 0 precisely to 0.0.) Unsigned integer data is mapped
5676 similarly: The largest integer value maps to 1.0, and 0 maps to 0.0. The
5677 resulting floating-point color values are then multiplied by
5678 @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is RED,
5679 GREEN, BLUE, and ALPHA for the respective color components. The results
5680 are clamped to the range @r{[0,1]}.
5682 If @code{GL_MAP_COLOR} is true, each color component is scaled by the
5683 size of lookup table @code{GL_PIXEL_MAP_c_TO_c}, then replaced by the
5684 value that it references in that table. @var{c} is R, G, B, or A
5687 The GL then converts the resulting RGBA colors to fragments by attaching
5688 the current raster position @var{z} coordinate and texture coordinates
5689 to each pixel, then assigning @r{@var{x}} and @r{@var{y}} window
5690 coordinates to the @r{@var{n}}th fragment such that
5692 @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},⌋}
5694 where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster
5695 position. These pixel fragments are then treated just like the
5696 fragments generated by rasterizing points, lines, or polygons. Texture
5697 mapping, fog, and all the fragment operations are applied before the
5698 fragments are written to the frame buffer.
5701 Each pixel is a single red component. This component is converted to
5702 the internal floating-point format in the same way the red component of
5703 an RGBA pixel is. It is then converted to an RGBA pixel with green and
5704 blue set to 0, and alpha set to 1. After this conversion, the pixel is
5705 treated as if it had been read as an RGBA pixel.
5707 @item @code{GL_GREEN}
5708 Each pixel is a single green component. This component is converted to
5709 the internal floating-point format in the same way the green component
5710 of an RGBA pixel is. It is then converted to an RGBA pixel with red and
5711 blue set to 0, and alpha set to 1. After this conversion, the pixel is
5712 treated as if it had been read as an RGBA pixel.
5714 @item @code{GL_BLUE}
5715 Each pixel is a single blue component. This component is converted to
5716 the internal floating-point format in the same way the blue component of
5717 an RGBA pixel is. It is then converted to an RGBA pixel with red and
5718 green set to 0, and alpha set to 1. After this conversion, the pixel is
5719 treated as if it had been read as an RGBA pixel.
5721 @item @code{GL_ALPHA}
5722 Each pixel is a single alpha component. This component is converted to
5723 the internal floating-point format in the same way the alpha component
5724 of an RGBA pixel is. It is then converted to an RGBA pixel with red,
5725 green, and blue set to 0. After this conversion, the pixel is treated
5726 as if it had been read as an RGBA pixel.
5730 Each pixel is a three-component group: red first, followed by green,
5731 followed by blue; for @code{GL_BGR}, the first component is blue,
5732 followed by green and then red. Each component is converted to the
5733 internal floating-point format in the same way the red, green, and blue
5734 components of an RGBA pixel are. The color triple is converted to an
5735 RGBA pixel with alpha set to 1. After this conversion, the pixel is
5736 treated as if it had been read as an RGBA pixel.
5738 @item @code{GL_LUMINANCE}
5739 Each pixel is a single luminance component. This component is converted
5740 to the internal floating-point format in the same way the red component
5741 of an RGBA pixel is. It is then converted to an RGBA pixel with red,
5742 green, and blue set to the converted luminance value, and alpha set to
5743 1. After this conversion, the pixel is treated as if it had been read
5746 @item @code{GL_LUMINANCE_ALPHA}
5747 Each pixel is a two-component group: luminance first, followed by alpha.
5748 The two components are converted to the internal floating-point format
5749 in the same way the red component of an RGBA pixel is. They are then
5750 converted to an RGBA pixel with red, green, and blue set to the
5751 converted luminance value, and alpha set to the converted alpha value.
5752 After this conversion, the pixel is treated as if it had been read as an
5757 The following table summarizes the meaning of the valid constants for
5758 the @var{type} parameter:
5764 @strong{Corresponding Type}
5766 @item @code{GL_UNSIGNED_BYTE}
5767 unsigned 8-bit integer
5769 @item @code{GL_BYTE}
5770 signed 8-bit integer
5772 @item @code{GL_BITMAP}
5773 single bits in unsigned 8-bit integers
5775 @item @code{GL_UNSIGNED_SHORT}
5776 unsigned 16-bit integer
5778 @item @code{GL_SHORT}
5779 signed 16-bit integer
5781 @item @code{GL_UNSIGNED_INT}
5782 unsigned 32-bit integer
5787 @item @code{GL_FLOAT}
5788 single-precision floating-point
5790 @item @code{GL_UNSIGNED_BYTE_3_3_2}
5791 unsigned 8-bit integer
5793 @item @code{GL_UNSIGNED_BYTE_2_3_3_REV}
5794 unsigned 8-bit integer with reversed component ordering
5796 @item @code{GL_UNSIGNED_SHORT_5_6_5}
5797 unsigned 16-bit integer
5799 @item @code{GL_UNSIGNED_SHORT_5_6_5_REV}
5800 unsigned 16-bit integer with reversed component ordering
5802 @item @code{GL_UNSIGNED_SHORT_4_4_4_4}
5803 unsigned 16-bit integer
5805 @item @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}
5806 unsigned 16-bit integer with reversed component ordering
5808 @item @code{GL_UNSIGNED_SHORT_5_5_5_1}
5809 unsigned 16-bit integer
5811 @item @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}
5812 unsigned 16-bit integer with reversed component ordering
5814 @item @code{GL_UNSIGNED_INT_8_8_8_8}
5815 unsigned 32-bit integer
5817 @item @code{GL_UNSIGNED_INT_8_8_8_8_REV}
5818 unsigned 32-bit integer with reversed component ordering
5820 @item @code{GL_UNSIGNED_INT_10_10_10_2}
5821 unsigned 32-bit integer
5823 @item @code{GL_UNSIGNED_INT_2_10_10_10_REV}
5824 unsigned 32-bit integer with reversed component ordering
5830 The rasterization described so far assumes pixel zoom factors of 1. If
5831 @code{glPixelZoom} is used to change the @r{@var{x}} and @r{@var{y}}
5832 pixel zoom factors, pixels are converted to fragments as follows. If
5833 @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position,
5834 and a given pixel is in the @r{@var{n}}th column and @r{@var{m}}th row
5835 of the pixel rectangle, then fragments are generated for pixels whose
5836 centers are in the rectangle with corners at
5838 @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,))}
5840 where @r{@var{zoom}_@var{x}} is the value of @code{GL_ZOOM_X} and
5841 @r{@var{zoom}_@var{y}} is the value of @code{GL_ZOOM_Y}.
5843 @code{GL_INVALID_ENUM} is generated if @var{format} or @var{type} is not
5844 one of the accepted values.
5846 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
5847 and @var{format} is not either @code{GL_COLOR_INDEX} or
5848 @code{GL_STENCIL_INDEX}.
5850 @code{GL_INVALID_VALUE} is generated if either @var{width} or
5851 @var{height} is negative.
5853 @code{GL_INVALID_OPERATION} is generated if @var{format} is
5854 @code{GL_STENCIL_INDEX} and there is no stencil buffer.
5856 @code{GL_INVALID_OPERATION} is generated if @var{format} is
5857 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
5858 @code{GL_RGB}, @code{GL_RGBA}, @code{GL_BGR}, @code{GL_BGRA},
5859 @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}, and the GL is in
5862 @code{GL_INVALID_OPERATION} is generated if @var{format} is one of
5863 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
5864 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
5865 and @var{format} is not @code{GL_RGB}.
5867 @code{GL_INVALID_OPERATION} is generated if @var{format} is one of
5868 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
5869 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
5870 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
5871 @code{GL_UNSIGNED_INT_10_10_10_2}, or
5872 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
5873 @code{GL_RGBA} nor @code{GL_BGRA}.
5875 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5876 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
5877 object's data store is currently mapped.
5879 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5880 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
5881 would be unpacked from the buffer object such that the memory reads
5882 required would exceed the data store size.
5884 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5885 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
5886 is not evenly divisible into the number of bytes needed to store in
5887 memory a datum indicated by @var{type}.
5889 @code{GL_INVALID_OPERATION} is generated if @code{glDrawPixels} is
5890 executed between the execution of @code{glBegin} and the corresponding
5891 execution of @code{glEnd}.
5895 @deftypefun void glDrawRangeElements mode start end count type indices
5896 Render primitives from array data.
5900 Specifies what kind of primitives to render. Symbolic constants
5901 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
5902 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
5903 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
5904 @code{GL_POLYGON} are accepted.
5907 Specifies the minimum array index contained in @var{indices}.
5910 Specifies the maximum array index contained in @var{indices}.
5913 Specifies the number of elements to be rendered.
5916 Specifies the type of the values in @var{indices}. Must be one of
5917 @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or
5918 @code{GL_UNSIGNED_INT}.
5921 Specifies a pointer to the location where the indices are stored.
5925 @code{glDrawRangeElements} is a restricted form of
5926 @code{glDrawElements}. @var{mode}, @var{start}, @var{end}, and
5927 @var{count} match the corresponding arguments to @code{glDrawElements},
5928 with the additional constraint that all values in the arrays @var{count}
5929 must lie between @var{start} and @var{end}, inclusive.
5931 Implementations denote recommended maximum amounts of vertex and index
5932 data, which may be queried by calling @code{glGet} with argument
5933 @code{GL_MAX_ELEMENTS_VERTICES} and @code{GL_MAX_ELEMENTS_INDICES}. If
5934 @r{@var{end}-@var{start}+1} is greater than the value of
5935 @code{GL_MAX_ELEMENTS_VERTICES}, or if @var{count} is greater than the
5936 value of @code{GL_MAX_ELEMENTS_INDICES}, then the call may operate at
5937 reduced performance. There is no requirement that all vertices in the
5938 range @r{[@var{start},@var{end}]} be referenced. However, the
5939 implementation may partially process unused vertices, reducing
5940 performance from what could be achieved with an optimal index set.
5942 When @code{glDrawRangeElements} is called, it uses @var{count}
5943 sequential elements from an enabled array, starting at @var{start} to
5944 construct a sequence of geometric primitives. @var{mode} specifies what
5945 kind of primitives are constructed, and how the array elements construct
5946 these primitives. If more than one array is enabled, each is used. If
5947 @code{GL_VERTEX_ARRAY} is not enabled, no geometric primitives are
5950 Vertex attributes that are modified by @code{glDrawRangeElements} have
5951 an unspecified value after @code{glDrawRangeElements} returns. For
5952 example, if @code{GL_COLOR_ARRAY} is enabled, the value of the current
5953 color is undefined after @code{glDrawRangeElements} executes. Attributes
5954 that aren't modified maintain their previous values.
5956 It is an error for indices to lie outside the range
5957 @r{[@var{start},@var{end}]}, but implementations may not check for this
5958 situation. Such indices cause implementation-dependent behavior.
5960 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
5963 @code{GL_INVALID_VALUE} is generated if @var{count} is negative.
5965 @code{GL_INVALID_VALUE} is generated if @r{@var{end}<@var{start}}.
5967 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5968 name is bound to an enabled array or the element array and the buffer
5969 object's data store is currently mapped.
5971 @code{GL_INVALID_OPERATION} is generated if @code{glDrawRangeElements}
5972 is executed between the execution of @code{glBegin} and the
5973 corresponding @code{glEnd}.
5977 @deftypefun void glEdgeFlagPointer stride pointer
5978 Define an array of edge flags.
5982 Specifies the byte offset between consecutive edge flags. If
5983 @var{stride} is 0, the edge flags are understood to be tightly packed in
5984 the array. The initial value is 0.
5987 Specifies a pointer to the first edge flag in the array. The initial
5992 @code{glEdgeFlagPointer} specifies the location and data format of an
5993 array of boolean edge flags to use when rendering. @var{stride}
5994 specifies the byte stride from one edge flag to the next, allowing
5995 vertices and attributes to be packed into a single array or stored in
5998 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
5999 target (see @code{glBindBuffer}) while an edge flag array is specified,
6000 @var{pointer} is treated as a byte offset into the buffer object's data
6001 store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING})
6002 is saved as edge flag vertex array client-side state
6003 (@code{GL_EDGE_FLAG_ARRAY_BUFFER_BINDING}).
6005 When an edge flag array is specified, @var{stride} and @var{pointer} are
6006 saved as client-side state, in addition to the current vertex array
6007 buffer object binding.
6009 To enable and disable the edge flag array, call
6010 @code{glEnableClientState} and @code{glDisableClientState} with the
6011 argument @code{GL_EDGE_FLAG_ARRAY}. If enabled, the edge flag array is
6012 used when @code{glDrawArrays}, @code{glMultiDrawArrays},
6013 @code{glDrawElements}, @code{glMultiDrawElements},
6014 @code{glDrawRangeElements}, or @code{glArrayElement} is called.
6016 @code{GL_INVALID_ENUM} is generated if @var{stride} is negative.
6020 @deftypefun void glEdgeFlag flag
6021 @deftypefunx void glEdgeFlagv flag
6022 Flag edges as either boundary or nonboundary.
6026 Specifies the current edge flag value, either @code{GL_TRUE} or
6027 @code{GL_FALSE}. The initial value is @code{GL_TRUE}.
6031 Each vertex of a polygon, separate triangle, or separate quadrilateral
6032 specified between a @code{glBegin}/@code{glEnd} pair is marked as the
6033 start of either a boundary or nonboundary edge. If the current edge
6034 flag is true when the vertex is specified, the vertex is marked as the
6035 start of a boundary edge. Otherwise, the vertex is marked as the start
6036 of a nonboundary edge. @code{glEdgeFlag} sets the edge flag bit to
6037 @code{GL_TRUE} if @var{flag} is @code{GL_TRUE} and to @code{GL_FALSE}
6040 The vertices of connected triangles and connected quadrilaterals are
6041 always marked as boundary, regardless of the value of the edge flag.
6043 Boundary and nonboundary edge flags on vertices are significant only if
6044 @code{GL_POLYGON_MODE} is set to @code{GL_POINT} or @code{GL_LINE}. See
6045 @code{glPolygonMode}.
6049 @deftypefun void glEnableClientState cap
6050 @deftypefunx void glDisableClientState cap
6051 Enable or disable client-side capability.
6055 Specifies the capability to enable. Symbolic constants
6056 @code{GL_COLOR_ARRAY}, @code{GL_EDGE_FLAG_ARRAY},
6057 @code{GL_FOG_COORD_ARRAY}, @code{GL_INDEX_ARRAY},
6058 @code{GL_NORMAL_ARRAY}, @code{GL_SECONDARY_COLOR_ARRAY},
6059 @code{GL_TEXTURE_COORD_ARRAY}, and @code{GL_VERTEX_ARRAY} are accepted.
6063 @code{glEnableClientState} and @code{glDisableClientState} enable or
6064 disable individual client-side capabilities. By default, all
6065 client-side capabilities are disabled. Both @code{glEnableClientState}
6066 and @code{glDisableClientState} take a single argument, @var{cap}, which
6067 can assume one of the following values:
6070 @item @code{GL_COLOR_ARRAY}
6071 If enabled, the color array is enabled for writing and used during
6072 rendering when @code{glArrayElement}, @code{glDrawArrays},
6073 @code{glDrawElements},
6074 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6075 @code{glMultiDrawElements} is called. See @code{glColorPointer}.
6077 @item @code{GL_EDGE_FLAG_ARRAY}
6078 If enabled, the edge flag array is enabled for writing and used during
6079 rendering when @code{glArrayElement}, @code{glDrawArrays},
6080 @code{glDrawElements},
6081 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6082 @code{glMultiDrawElements} is called. See @code{glEdgeFlagPointer}.
6084 @item @code{GL_FOG_COORD_ARRAY}
6085 If enabled, the fog coordinate array is enabled for writing and used
6086 during rendering when @code{glArrayElement}, @code{glDrawArrays},
6087 @code{glDrawElements},
6088 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6089 @code{glMultiDrawElements} is called. See @code{glFogCoordPointer}.
6091 @item @code{GL_INDEX_ARRAY}
6092 If enabled, the index array is enabled for writing and used during
6093 rendering when @code{glArrayElement}, @code{glDrawArrays},
6094 @code{glDrawElements},
6095 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6096 @code{glMultiDrawElements} is called. See @code{glIndexPointer}.
6098 @item @code{GL_NORMAL_ARRAY}
6099 If enabled, the normal array is enabled for writing and used during
6100 rendering when @code{glArrayElement}, @code{glDrawArrays},
6101 @code{glDrawElements},
6102 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6103 @code{glMultiDrawElements} is called. See @code{glNormalPointer}.
6105 @item @code{GL_SECONDARY_COLOR_ARRAY}
6106 If enabled, the secondary color array is enabled for writing and used
6107 during rendering when @code{glArrayElement}, @code{glDrawArrays},
6108 @code{glDrawElements},
6109 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6110 @code{glMultiDrawElements} is called. See @code{glColorPointer}.
6112 @item @code{GL_TEXTURE_COORD_ARRAY}
6113 If enabled, the texture coordinate array is enabled for writing and used
6114 during rendering when @code{glArrayElement}, @code{glDrawArrays},
6115 @code{glDrawElements},
6116 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6117 @code{glMultiDrawElements} is called. See @code{glTexCoordPointer}.
6119 @item @code{GL_VERTEX_ARRAY}
6120 If enabled, the vertex array is enabled for writing and used during
6121 rendering when @code{glArrayElement}, @code{glDrawArrays},
6122 @code{glDrawElements},
6123 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6124 @code{glMultiDrawElements} is called. See @code{glVertexPointer}.
6128 @code{GL_INVALID_ENUM} is generated if @var{cap} is not an accepted
6131 @code{glEnableClientState} is not allowed between the execution of
6132 @code{glBegin} and the corresponding @code{glEnd}, but an error may or
6133 may not be generated. If no error is generated, the behavior is
6138 @deftypefun void glEnableVertexAttribArray index
6139 @deftypefunx void glDisableVertexAttribArray index
6140 Enable or disable a generic vertex attribute array.
6144 Specifies the index of the generic vertex attribute to be enabled or
6149 @code{glEnableVertexAttribArray} enables the generic vertex attribute
6150 array specified by @var{index}. @code{glDisableVertexAttribArray}
6151 disables the generic vertex attribute array specified by @var{index}. By
6152 default, all client-side capabilities are disabled, including all
6153 generic vertex attribute arrays. If enabled, the values in the generic
6154 vertex attribute array will be accessed and used for rendering when
6155 calls are made to vertex array commands such as @code{glDrawArrays},
6156 @code{glDrawElements}, @code{glDrawRangeElements},
6157 @code{glArrayElement}, @code{glMultiDrawElements}, or
6158 @code{glMultiDrawArrays}.
6160 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
6161 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
6163 @code{GL_INVALID_OPERATION} is generated if either
6164 @code{glEnableVertexAttribArray } or @code{glDisableVertexAttribArray }
6165 is executed between the execution of @code{glBegin} and the
6166 corresponding execution of @code{glEnd}.
6170 @deftypefun void glEnable cap
6171 @deftypefunx void glDisable cap
6172 Enable or disable server-side GL capabilities.
6176 Specifies a symbolic constant indicating a GL capability.
6180 @code{glEnable} and @code{glDisable} enable and disable various
6181 capabilities. Use @code{glIsEnabled} or @code{glGet} to determine the
6182 current setting of any capability. The initial value for each
6183 capability with the exception of @code{GL_DITHER} and
6184 @code{GL_MULTISAMPLE} is @code{GL_FALSE}. The initial value for
6185 @code{GL_DITHER} and @code{GL_MULTISAMPLE} is @code{GL_TRUE}.
6187 Both @code{glEnable} and @code{glDisable} take a single argument,
6188 @var{cap}, which can assume one of the following values:
6191 @item @code{GL_ALPHA_TEST}
6194 If enabled, do alpha testing. See @code{glAlphaFunc}.
6196 @item @code{GL_AUTO_NORMAL}
6199 If enabled, generate normal vectors when either @code{GL_MAP2_VERTEX_3}
6200 or @code{GL_MAP2_VERTEX_4} is used to generate vertices. See
6203 @item @code{GL_BLEND}
6206 If enabled, blend the computed fragment color values with the values in
6207 the color buffers. See @code{glBlendFunc}.
6209 @item @code{GL_CLIP_PLANE}@var{i}
6212 If enabled, clip geometry against user-defined clipping plane @var{i}.
6213 See @code{glClipPlane}.
6215 @item @code{GL_COLOR_LOGIC_OP}
6218 If enabled, apply the currently selected logical operation to the
6219 computed fragment color and color buffer values. See @code{glLogicOp}.
6221 @item @code{GL_COLOR_MATERIAL}
6224 If enabled, have one or more material parameters track the current
6225 color. See @code{glColorMaterial}.
6227 @item @code{GL_COLOR_SUM}
6230 If enabled and no fragment shader is active, add the secondary color
6231 value to the computed fragment color. See @code{glSecondaryColor}.
6233 @item @code{GL_COLOR_TABLE}
6236 If enabled, perform a color table lookup on the incoming RGBA color
6237 values. See @code{glColorTable}.
6239 @item @code{GL_CONVOLUTION_1D}
6242 If enabled, perform a 1D convolution operation on incoming RGBA color
6243 values. See @code{glConvolutionFilter1D}.
6245 @item @code{GL_CONVOLUTION_2D}
6248 If enabled, perform a 2D convolution operation on incoming RGBA color
6249 values. See @code{glConvolutionFilter2D}.
6251 @item @code{GL_CULL_FACE}
6254 If enabled, cull polygons based on their winding in window coordinates.
6255 See @code{glCullFace}.
6257 @item @code{GL_DEPTH_TEST}
6260 If enabled, do depth comparisons and update the depth buffer. Note that
6261 even if the depth buffer exists and the depth mask is non-zero, the
6262 depth buffer is not updated if the depth test is disabled. See
6263 @code{glDepthFunc} and @code{glDepthRange}.
6265 @item @code{GL_DITHER}
6268 If enabled, dither color components or indices before they are written
6269 to the color buffer.
6274 If enabled and no fragment shader is active, blend a fog color into the
6275 post-texturing color. See @code{glFog}.
6277 @item @code{GL_HISTOGRAM}
6280 If enabled, histogram incoming RGBA color values. See
6283 @item @code{GL_INDEX_LOGIC_OP}
6286 If enabled, apply the currently selected logical operation to the
6287 incoming index and color buffer indices. See @code{glLogicOp}.
6289 @item @code{GL_LIGHT}@var{i}
6292 If enabled, include light @var{i} in the evaluation of the lighting
6293 equation. See @code{glLightModel} and @code{glLight}.
6295 @item @code{GL_LIGHTING}
6298 If enabled and no vertex shader is active, use the current lighting
6299 parameters to compute the vertex color or index. Otherwise, simply
6300 associate the current color or index with each vertex. See
6301 @code{glMaterial}, @code{glLightModel}, and @code{glLight}.
6303 @item @code{GL_LINE_SMOOTH}
6306 If enabled, draw lines with correct filtering. Otherwise, draw aliased
6307 lines. See @code{glLineWidth}.
6309 @item @code{GL_LINE_STIPPLE}
6312 If enabled, use the current line stipple pattern when drawing lines. See
6313 @code{glLineStipple}.
6315 @item @code{GL_MAP1_COLOR_4}
6318 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6319 @code{glEvalPoint1} generate RGBA values. See @code{glMap1}.
6321 @item @code{GL_MAP1_INDEX}
6324 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6325 @code{glEvalPoint1} generate color indices. See @code{glMap1}.
6327 @item @code{GL_MAP1_NORMAL}
6330 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6331 @code{glEvalPoint1} generate normals. See @code{glMap1}.
6333 @item @code{GL_MAP1_TEXTURE_COORD_1}
6336 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6337 @code{glEvalPoint1} generate @var{s} texture coordinates. See
6340 @item @code{GL_MAP1_TEXTURE_COORD_2}
6343 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6344 @code{glEvalPoint1} generate @var{s} and @var{t} texture coordinates.
6347 @item @code{GL_MAP1_TEXTURE_COORD_3}
6350 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6351 @code{glEvalPoint1} generate @var{s}, @var{t}, and @var{r} texture
6352 coordinates. See @code{glMap1}.
6354 @item @code{GL_MAP1_TEXTURE_COORD_4}
6357 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6358 @code{glEvalPoint1} generate @var{s}, @var{t}, @var{r}, and @var{q}
6359 texture coordinates. See @code{glMap1}.
6361 @item @code{GL_MAP1_VERTEX_3}
6364 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6365 @code{glEvalPoint1} generate @var{x}, @var{y}, and @var{z} vertex
6366 coordinates. See @code{glMap1}.
6368 @item @code{GL_MAP1_VERTEX_4}
6371 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6372 @code{glEvalPoint1} generate homogeneous @var{x}, @var{y}, @var{z}, and
6373 @var{w} vertex coordinates. See @code{glMap1}.
6375 @item @code{GL_MAP2_COLOR_4}
6378 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6379 @code{glEvalPoint2} generate RGBA values. See @code{glMap2}.
6381 @item @code{GL_MAP2_INDEX}
6384 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6385 @code{glEvalPoint2} generate color indices. See @code{glMap2}.
6387 @item @code{GL_MAP2_NORMAL}
6390 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6391 @code{glEvalPoint2} generate normals. See @code{glMap2}.
6393 @item @code{GL_MAP2_TEXTURE_COORD_1}
6396 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6397 @code{glEvalPoint2} generate @var{s} texture coordinates. See
6400 @item @code{GL_MAP2_TEXTURE_COORD_2}
6403 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6404 @code{glEvalPoint2} generate @var{s} and @var{t} texture coordinates.
6407 @item @code{GL_MAP2_TEXTURE_COORD_3}
6410 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6411 @code{glEvalPoint2} generate @var{s}, @var{t}, and @var{r} texture
6412 coordinates. See @code{glMap2}.
6414 @item @code{GL_MAP2_TEXTURE_COORD_4}
6417 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6418 @code{glEvalPoint2} generate @var{s}, @var{t}, @var{r}, and @var{q}
6419 texture coordinates. See @code{glMap2}.
6421 @item @code{GL_MAP2_VERTEX_3}
6424 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6425 @code{glEvalPoint2} generate @var{x}, @var{y}, and @var{z} vertex
6426 coordinates. See @code{glMap2}.
6428 @item @code{GL_MAP2_VERTEX_4}
6431 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6432 @code{glEvalPoint2} generate homogeneous @var{x}, @var{y}, @var{z}, and
6433 @var{w} vertex coordinates. See @code{glMap2}.
6435 @item @code{GL_MINMAX}
6438 If enabled, compute the minimum and maximum values of incoming RGBA
6439 color values. See @code{glMinmax}.
6441 @item @code{GL_MULTISAMPLE}
6444 If enabled, use multiple fragment samples in computing the final color
6445 of a pixel. See @code{glSampleCoverage}.
6447 @item @code{GL_NORMALIZE}
6450 If enabled and no vertex shader is active, normal vectors are normalized
6451 to unit length after transformation and before lighting. This method is
6452 generally less efficient than @code{GL_RESCALE_NORMAL}. See
6453 @code{glNormal} and @code{glNormalPointer}.
6455 @item @code{GL_POINT_SMOOTH}
6458 If enabled, draw points with proper filtering. Otherwise, draw aliased
6459 points. See @code{glPointSize}.
6461 @item @code{GL_POINT_SPRITE}
6464 If enabled, calculate texture coordinates for points based on texture
6465 environment and point parameter settings. Otherwise texture coordinates
6466 are constant across points.
6468 @item @code{GL_POLYGON_OFFSET_FILL}
6471 If enabled, and if the polygon is rendered in @code{GL_FILL} mode, an
6472 offset is added to depth values of a polygon's fragments before the
6473 depth comparison is performed. See @code{glPolygonOffset}.
6475 @item @code{GL_POLYGON_OFFSET_LINE}
6478 If enabled, and if the polygon is rendered in @code{GL_LINE} mode, an
6479 offset is added to depth values of a polygon's fragments before the
6480 depth comparison is performed. See @code{glPolygonOffset}.
6482 @item @code{GL_POLYGON_OFFSET_POINT}
6485 If enabled, an offset is added to depth values of a polygon's fragments
6486 before the depth comparison is performed, if the polygon is rendered in
6487 @code{GL_POINT} mode. See @code{glPolygonOffset}.
6489 @item @code{GL_POLYGON_SMOOTH}
6492 If enabled, draw polygons with proper filtering. Otherwise, draw
6493 aliased polygons. For correct antialiased polygons, an alpha buffer is
6494 needed and the polygons must be sorted front to back.
6496 @item @code{GL_POLYGON_STIPPLE}
6499 If enabled, use the current polygon stipple pattern when rendering
6500 polygons. See @code{glPolygonStipple}.
6502 @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}
6505 If enabled, perform a color table lookup on RGBA color values after
6506 color matrix transformation. See @code{glColorTable}.
6508 @item @code{GL_POST_CONVOLUTION_COLOR_TABLE}
6511 If enabled, perform a color table lookup on RGBA color values after
6512 convolution. See @code{glColorTable}.
6514 @item @code{GL_RESCALE_NORMAL}
6517 If enabled and no vertex shader is active, normal vectors are scaled
6518 after transformation and before lighting by a factor computed from the
6519 modelview matrix. If the modelview matrix scales space uniformly, this
6520 has the effect of restoring the transformed normal to unit length. This
6521 method is generally more efficient than @code{GL_NORMALIZE}. See
6522 @code{glNormal} and @code{glNormalPointer}.
6524 @item @code{GL_SAMPLE_ALPHA_TO_COVERAGE}
6527 If enabled, compute a temporary coverage value where each bit is
6528 determined by the alpha value at the corresponding sample location. The
6529 temporary coverage value is then ANDed with the fragment coverage value.
6531 @item @code{GL_SAMPLE_ALPHA_TO_ONE}
6534 If enabled, each sample alpha value is replaced by the maximum
6535 representable alpha value.
6537 @item @code{GL_SAMPLE_COVERAGE}
6540 If enabled, the fragment's coverage is ANDed with the temporary coverage
6541 value. If @code{GL_SAMPLE_COVERAGE_INVERT} is set to @code{GL_TRUE},
6542 invert the coverage value. See @code{glSampleCoverage}.
6544 @item @code{GL_SEPARABLE_2D}
6547 If enabled, perform a two-dimensional convolution operation using a
6548 separable convolution filter on incoming RGBA color values. See
6549 @code{glSeparableFilter2D}.
6551 @item @code{GL_SCISSOR_TEST}
6554 If enabled, discard fragments that are outside the scissor rectangle.
6555 See @code{glScissor}.
6557 @item @code{GL_STENCIL_TEST}
6560 If enabled, do stencil testing and update the stencil buffer. See
6561 @code{glStencilFunc} and @code{glStencilOp}.
6563 @item @code{GL_TEXTURE_1D}
6566 If enabled and no fragment shader is active, one-dimensional texturing
6567 is performed (unless two- or three-dimensional or cube-mapped texturing
6568 is also enabled). See @code{glTexImage1D}.
6570 @item @code{GL_TEXTURE_2D}
6573 If enabled and no fragment shader is active, two-dimensional texturing
6574 is performed (unless three-dimensional or cube-mapped texturing is also
6575 enabled). See @code{glTexImage2D}.
6577 @item @code{GL_TEXTURE_3D}
6580 If enabled and no fragment shader is active, three-dimensional texturing
6581 is performed (unless cube-mapped texturing is also enabled). See
6582 @code{glTexImage3D}.
6584 @item @code{GL_TEXTURE_CUBE_MAP}
6587 If enabled and no fragment shader is active, cube-mapped texturing is
6588 performed. See @code{glTexImage2D}.
6590 @item @code{GL_TEXTURE_GEN_Q}
6593 If enabled and no vertex shader is active, the @var{q} texture
6594 coordinate is computed using the texture generation function defined
6595 with @code{glTexGen}. Otherwise, the current @var{q} texture coordinate
6596 is used. See @code{glTexGen}.
6598 @item @code{GL_TEXTURE_GEN_R}
6601 If enabled and no vertex shader is active, the @var{r} texture
6602 coordinate is computed using the texture generation function defined
6603 with @code{glTexGen}. Otherwise, the current @var{r} texture coordinate
6604 is used. See @code{glTexGen}.
6606 @item @code{GL_TEXTURE_GEN_S}
6609 If enabled and no vertex shader is active, the @var{s} texture
6610 coordinate is computed using the texture generation function defined
6611 with @code{glTexGen}. Otherwise, the current @var{s} texture coordinate
6612 is used. See @code{glTexGen}.
6614 @item @code{GL_TEXTURE_GEN_T}
6617 If enabled and no vertex shader is active, the @var{t} texture
6618 coordinate is computed using the texture generation function defined
6619 with @code{glTexGen}. Otherwise, the current @var{t} texture coordinate
6620 is used. See @code{glTexGen}.
6622 @item @code{GL_VERTEX_PROGRAM_POINT_SIZE}
6625 If enabled and a vertex shader is active, then the derived point size is
6626 taken from the (potentially clipped) shader builtin @code{gl_PointSize}
6627 and clamped to the implementation-dependent point size range.
6629 @item @code{GL_VERTEX_PROGRAM_TWO_SIDE}
6632 If enabled and a vertex shader is active, it specifies that the GL will
6633 choose between front and back colors based on the polygon's face
6634 direction of which the vertex being shaded is a part. It has no effect
6639 @code{GL_INVALID_ENUM} is generated if @var{cap} is not one of the
6640 values listed previously.
6642 @code{GL_INVALID_OPERATION} is generated if @code{glEnable} or
6643 @code{glDisable} is executed between the execution of @code{glBegin} and
6644 the corresponding execution of @code{glEnd}.
6648 @deftypefun void glEvalCoord1f u
6649 @deftypefunx void glEvalCoord1d u
6650 @deftypefunx void glEvalCoord2f u v
6651 @deftypefunx void glEvalCoord2d u v
6652 @deftypefunx void glEvalCoord1fv u
6653 @deftypefunx void glEvalCoord1dv u
6654 @deftypefunx void glEvalCoord2fv u
6655 @deftypefunx void glEvalCoord2dv u
6656 Evaluate enabled one- and two-dimensional maps.
6660 Specifies a value that is the domain coordinate @r{@var{u}} to the basis
6661 function defined in a previous @code{glMap1} or @code{glMap2} command.
6664 Specifies a value that is the domain coordinate @r{@var{v}} to the basis
6665 function defined in a previous @code{glMap2} command. This argument is
6666 not present in a @code{glEvalCoord1} command.
6670 @code{glEvalCoord1} evaluates enabled one-dimensional maps at argument
6671 @var{u}. @code{glEvalCoord2} does the same for two-dimensional maps
6672 using two domain values, @var{u} and @var{v}. To define a map, call
6673 @code{glMap1} and @code{glMap2}; to enable and disable it, call
6674 @code{glEnable} and @code{glDisable}.
6676 When one of the @code{glEvalCoord} commands is issued, all currently
6677 enabled maps of the indicated dimension are evaluated. Then, for each
6678 enabled map, it is as if the corresponding GL command had been issued
6679 with the computed value. That is, if @code{GL_MAP1_INDEX} or
6680 @code{GL_MAP2_INDEX} is enabled, a @code{glIndex} command is simulated.
6681 If @code{GL_MAP1_COLOR_4} or @code{GL_MAP2_COLOR_4} is enabled, a
6682 @code{glColor} command is simulated. If @code{GL_MAP1_NORMAL} or
6683 @code{GL_MAP2_NORMAL} is enabled, a normal vector is produced, and if
6684 any of @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2},
6685 @code{GL_MAP1_TEXTURE_COORD_3}, @code{GL_MAP1_TEXTURE_COORD_4},
6686 @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2},
6687 @code{GL_MAP2_TEXTURE_COORD_3}, or @code{GL_MAP2_TEXTURE_COORD_4} is
6688 enabled, then an appropriate @code{glTexCoord} command is simulated.
6690 For color, color index, normal, and texture coordinates the GL uses
6691 evaluated values instead of current values for those evaluations that
6692 are enabled, and current values otherwise, However, the evaluated values
6693 do not update the current values. Thus, if @code{glVertex} commands are
6694 interspersed with @code{glEvalCoord} commands, the color, normal, and
6695 texture coordinates associated with the @code{glVertex} commands are not
6696 affected by the values generated by the @code{glEvalCoord} commands, but
6697 only by the most recent @code{glColor}, @code{glIndex}, @code{glNormal},
6698 and @code{glTexCoord} commands.
6700 No commands are issued for maps that are not enabled. If more than one
6701 texture evaluation is enabled for a particular dimension (for example,
6702 @code{GL_MAP2_TEXTURE_COORD_1} and @code{GL_MAP2_TEXTURE_COORD_2}), then
6703 only the evaluation of the map that produces the larger number of
6704 coordinates (in this case, @code{GL_MAP2_TEXTURE_COORD_2}) is carried
6705 out. @code{GL_MAP1_VERTEX_4} overrides @code{GL_MAP1_VERTEX_3}, and
6706 @code{GL_MAP2_VERTEX_4} overrides @code{GL_MAP2_VERTEX_3}, in the same
6707 manner. If neither a three- nor a four-component vertex map is enabled
6708 for the specified dimension, the @code{glEvalCoord} command is ignored.
6710 If you have enabled automatic normal generation, by calling
6711 @code{glEnable} with argument @code{GL_AUTO_NORMAL}, @code{glEvalCoord2}
6712 generates surface normals analytically, regardless of the contents or
6713 enabling of the @code{GL_MAP2_NORMAL} map. Let
6715 @r{@code{m}=∂@code{p},/∂@var{u},,×∂@code{p},/∂@var{v},,}
6717 Then the generated normal @r{@code{n}} is
6718 @r{@code{n}=@code{m}/∥@code{m},∥,}
6720 If automatic normal generation is disabled, the corresponding normal map
6721 @code{GL_MAP2_NORMAL}, if enabled, is used to produce a normal. If
6722 neither automatic normal generation nor a normal map is enabled, no
6723 normal is generated for @code{glEvalCoord2} commands.
6727 @deftypefun void glEvalMesh1 mode i1 i2
6728 @deftypefunx void glEvalMesh2 mode i1 i2 j1 j2
6729 Compute a one- or two-dimensional grid of points or lines.
6733 In @code{glEvalMesh1}, specifies whether to compute a one-dimensional
6734 mesh of points or lines. Symbolic constants @code{GL_POINT} and
6735 @code{GL_LINE} are accepted.
6739 Specify the first and last integer values for grid domain variable
6744 @code{glMapGrid} and @code{glEvalMesh} are used in tandem to efficiently
6745 generate and evaluate a series of evenly-spaced map domain values.
6746 @code{glEvalMesh} steps through the integer domain of a one- or
6747 two-dimensional grid, whose range is the domain of the evaluation maps
6748 specified by @code{glMap1} and @code{glMap2}. @var{mode} determines
6749 whether the resulting vertices are connected as points, lines, or filled
6752 In the one-dimensional case, @code{glEvalMesh1}, the mesh is generated
6753 as if the following code fragment were executed:
6759 glBegin( @var{type} );
6760 for ( i = @var{i1}; i <= @var{i2}; i += 1 )
6761 glEvalCoord1( @r{i·Δ@var{u}+@var{u}_1} );
6765 @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}
6767 and @r{@var{n}}, @r{@var{u}_1}, and @r{@var{u}_2} are the arguments to
6768 the most recent @code{glMapGrid1} command. @var{type} is
6769 @code{GL_POINTS} if @var{mode} is @code{GL_POINT}, or @code{GL_LINES} if
6770 @var{mode} is @code{GL_LINE}.
6772 The one absolute numeric requirement is that if @r{@var{i}=@var{n}},
6773 then the value computed from @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly
6776 In the two-dimensional case, @code{glEvalMesh2}, let .cp
6777 @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}
6779 @r{Δ@var{v}=(@var{v}_2-@var{v}_1,)/@var{m}}
6781 where @r{@var{n}}, @r{@var{u}_1}, @r{@var{u}_2}, @r{@var{m}},
6782 @r{@var{v}_1}, and @r{@var{v}_2} are the arguments to the most recent
6783 @code{glMapGrid2} command. Then, if @var{mode} is @code{GL_FILL}, the
6784 @code{glEvalMesh2} command is equivalent to:
6790 for ( j = @var{j1}; j < @var{j2}; j += 1 ) @{
6791 glBegin( GL_QUAD_STRIP );
6792 for ( i = @var{i1}; i <= @var{i2}; i += 1 ) @{
6793 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6794 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,(j+1,)·Δ@var{v}+@var{v}_1} );
6800 If @var{mode} is @code{GL_LINE}, then a call to @code{glEvalMesh2} is
6807 for ( j = @var{j1}; j <= @var{j2}; j += 1 ) @{
6808 glBegin( GL_LINE_STRIP );
6809 for ( i = @var{i1}; i <= @var{i2}; i += 1 )
6810 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6814 for ( i = @var{i1}; i <= @var{i2}; i += 1 ) @{
6815 glBegin( GL_LINE_STRIP );
6816 for ( j = @var{j1}; j <= @var{j1}; j += 1 )
6817 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6822 And finally, if @var{mode} is @code{GL_POINT}, then a call to
6823 @code{glEvalMesh2} is equivalent to:
6829 glBegin( GL_POINTS );
6830 for ( j = @var{j1}; j <= @var{j2}; j += 1 )
6831 for ( i = @var{i1}; i <= @var{i2}; i += 1 )
6832 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6836 In all three cases, the only absolute numeric requirements are that if
6837 @r{@var{i}=@var{n}}, then the value computed from
6838 @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}, and if
6839 @r{@var{j}=@var{m}}, then the value computed from
6840 @r{@var{j}·Δ@var{v}+@var{v}_1} is exactly @r{@var{v}_2}.
6842 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
6845 @code{GL_INVALID_OPERATION} is generated if @code{glEvalMesh} is
6846 executed between the execution of @code{glBegin} and the corresponding
6847 execution of @code{glEnd}.
6851 @deftypefun void glEvalPoint1 i
6852 @deftypefunx void glEvalPoint2 i j
6853 Generate and evaluate a single point in a mesh.
6857 Specifies the integer value for grid domain variable @r{@var{i}}.
6860 Specifies the integer value for grid domain variable @r{@var{j}}
6861 (@code{glEvalPoint2} only).
6865 @code{glMapGrid} and @code{glEvalMesh} are used in tandem to efficiently
6866 generate and evaluate a series of evenly spaced map domain values.
6867 @code{glEvalPoint} can be used to evaluate a single grid point in the
6868 same gridspace that is traversed by @code{glEvalMesh}. Calling
6869 @code{glEvalPoint1} is equivalent to calling where
6870 @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}
6874 glEvalCoord1( @r{i·Δ@var{u}+@var{u}_1} );
6877 and @r{@var{n}}, @r{@var{u}_1}, and @r{@var{u}_2} are the arguments to
6878 the most recent @code{glMapGrid1} command. The one absolute numeric
6879 requirement is that if @r{@var{i}=@var{n}}, then the value computed from
6880 @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}.
6882 In the two-dimensional case, @code{glEvalPoint2}, let
6884 @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}@r{Δ@var{v}=(@var{v}_2-@var{v}_1,)/@var{m}}
6886 where @r{@var{n}}, @r{@var{u}_1}, @r{@var{u}_2}, @r{@var{m}},
6887 @r{@var{v}_1}, and @r{@var{v}_2} are the arguments to the most recent
6888 @code{glMapGrid2} command. Then the @code{glEvalPoint2} command is
6889 equivalent to calling The only absolute numeric requirements are that if
6890 @r{@var{i}=@var{n}}, then the value computed from
6891 @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}, and if
6892 @r{@var{j}=@var{m}}, then the value computed from
6893 @r{@var{j}·Δ@var{v}+@var{v}_1} is exactly @r{@var{v}_2}.
6897 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6902 @deftypefun void glFeedbackBuffer size type buffer
6903 Controls feedback mode.
6907 Specifies the maximum number of values that can be written into
6911 Specifies a symbolic constant that describes the information that will
6912 be returned for each vertex. @code{GL_2D}, @code{GL_3D},
6913 @code{GL_3D_COLOR}, @code{GL_3D_COLOR_TEXTURE}, and
6914 @code{GL_4D_COLOR_TEXTURE} are accepted.
6917 Returns the feedback data.
6921 The @code{glFeedbackBuffer} function controls feedback. Feedback, like
6922 selection, is a GL mode. The mode is selected by calling
6923 @code{glRenderMode} with @code{GL_FEEDBACK}. When the GL is in feedback
6924 mode, no pixels are produced by rasterization. Instead, information
6925 about primitives that would have been rasterized is fed back to the
6926 application using the GL.
6928 @code{glFeedbackBuffer} has three arguments: @var{buffer} is a pointer
6929 to an array of floating-point values into which feedback information is
6930 placed. @var{size} indicates the size of the array. @var{type} is a
6931 symbolic constant describing the information that is fed back for each
6932 vertex. @code{glFeedbackBuffer} must be issued before feedback mode is
6933 enabled (by calling @code{glRenderMode} with argument
6934 @code{GL_FEEDBACK}). Setting @code{GL_FEEDBACK} without establishing
6935 the feedback buffer, or calling @code{glFeedbackBuffer} while the GL is
6936 in feedback mode, is an error.
6938 When @code{glRenderMode} is called while in feedback mode, it returns
6939 the number of entries placed in the feedback array and resets the
6940 feedback array pointer to the base of the feedback buffer. The returned
6941 value never exceeds @var{size}. If the feedback data required more room
6942 than was available in @var{buffer}, @code{glRenderMode} returns a
6943 negative value. To take the GL out of feedback mode, call
6944 @code{glRenderMode} with a parameter value other than
6947 While in feedback mode, each primitive, bitmap, or pixel rectangle that
6948 would be rasterized generates a block of values that are copied into the
6949 feedback array. If doing so would cause the number of entries to exceed
6950 the maximum, the block is partially written so as to fill the array (if
6951 there is any room left at all), and an overflow flag is set. Each block
6952 begins with a code indicating the primitive type, followed by values
6953 that describe the primitive's vertices and associated data. Entries are
6954 also written for bitmaps and pixel rectangles. Feedback occurs after
6955 polygon culling and @code{glPolygonMode} interpretation of polygons has
6956 taken place, so polygons that are culled are not returned in the
6957 feedback buffer. It can also occur after polygons with more than three
6958 edges are broken up into triangles, if the GL implementation renders
6959 polygons by performing this decomposition.
6961 The @code{glPassThrough} command can be used to insert a marker into the
6962 feedback buffer. See @code{glPassThrough}.
6964 Following is the grammar for the blocks of values written into the
6965 feedback buffer. Each primitive is indicated with a unique identifying
6966 value followed by some number of vertices. Polygon entries include an
6967 integer value indicating how many vertices follow. A vertex is fed back
6968 as some number of floating-point values, as determined by @var{type}.
6969 Colors are fed back as four values in RGBA mode and one value in color
6972 feedbackList @r{←} feedbackItem feedbackList | feedbackItem feedbackItem
6973 @r{←} point | lineSegment | polygon | bitmap | pixelRectangle | passThru
6974 point @r{←}@code{GL_POINT_TOKEN} vertex lineSegment
6975 @r{←}@code{GL_LINE_TOKEN} vertex vertex | @code{GL_LINE_RESET_TOKEN}
6976 vertex vertex polygon @r{←}@code{GL_POLYGON_TOKEN} n polySpec polySpec
6977 @r{←} polySpec vertex | vertex vertex vertex bitmap
6978 @r{←}@code{GL_BITMAP_TOKEN} vertex pixelRectangle
6979 @r{←}@code{GL_DRAW_PIXEL_TOKEN} vertex | @code{GL_COPY_PIXEL_TOKEN}
6980 vertex passThru @r{←}@code{GL_PASS_THROUGH_TOKEN} value vertex @r{←} 2d
6981 | 3d | 3dColor | 3dColorTexture | 4dColorTexture 2d @r{←} value value 3d
6982 @r{←} value value value 3dColor @r{←} value value value color
6983 3dColorTexture @r{←} value value value color tex 4dColorTexture @r{←}
6984 value value value value color tex color @r{←} rgba | index rgba @r{←}
6985 value value value value index @r{←} value tex @r{←} value value value
6988 @var{value} is a floating-point number, and @var{n} is a floating-point
6989 integer giving the number of vertices in the polygon.
6990 @code{GL_POINT_TOKEN}, @code{GL_LINE_TOKEN}, @code{GL_LINE_RESET_TOKEN},
6991 @code{GL_POLYGON_TOKEN}, @code{GL_BITMAP_TOKEN},
6992 @code{GL_DRAW_PIXEL_TOKEN}, @code{GL_COPY_PIXEL_TOKEN} and
6993 @code{GL_PASS_THROUGH_TOKEN} are symbolic floating-point constants.
6994 @code{GL_LINE_RESET_TOKEN} is returned whenever the line stipple pattern
6995 is reset. The data returned as a vertex depends on the feedback
6998 The following table gives the correspondence between @var{type} and the
6999 number of values per vertex. @var{k} is 1 in color index mode and 4 in
7006 @strong{Coordinates}, @strong{Color}, @strong{Texture}, @strong{Total
7010 @var{x}, @var{y}, , , 2
7013 @var{x}, @var{y}, @var{z}, , , 3
7015 @item @code{GL_3D_COLOR}
7016 @var{x}, @var{y}, @var{z}, @r{@var{k}}, , @r{3+@var{k}}
7018 @item @code{GL_3D_COLOR_TEXTURE}
7019 @var{x}, @var{y}, @var{z}, @r{@var{k}}, 4 , @r{7+@var{k}}
7021 @item @code{GL_4D_COLOR_TEXTURE}
7022 @var{x}, @var{y}, @var{z}, @var{w}, @r{@var{k}}, 4 , @r{8+@var{k}}
7026 Feedback vertex coordinates are in window coordinates, except @var{w},
7027 which is in clip coordinates. Feedback colors are lighted, if lighting
7028 is enabled. Feedback texture coordinates are generated, if texture
7029 coordinate generation is enabled. They are always transformed by the
7032 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
7035 @code{GL_INVALID_VALUE} is generated if @var{size} is negative.
7037 @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is
7038 called while the render mode is @code{GL_FEEDBACK}, or if
7039 @code{glRenderMode} is called with argument @code{GL_FEEDBACK} before
7040 @code{glFeedbackBuffer} is called at least once.
7042 @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is
7043 executed between the execution of @code{glBegin} and the corresponding
7044 execution of @code{glEnd}.
7048 @deftypefun void glFinish
7049 Block until all GL execution is complete.
7051 @code{glFinish} does not return until the effects of all previously
7052 called GL commands are complete. Such effects include all changes to GL
7053 state, all changes to connection state, and all changes to the frame
7056 @code{GL_INVALID_OPERATION} is generated if @code{glFinish} is executed
7057 between the execution of @code{glBegin} and the corresponding execution
7062 @deftypefun void glFlush
7063 Force execution of GL commands in finite time.
7065 Different GL implementations buffer commands in several different
7066 locations, including network buffers and the graphics accelerator
7067 itself. @code{glFlush} empties all of these buffers, causing all issued
7068 commands to be executed as quickly as they are accepted by the actual
7069 rendering engine. Though this execution may not be completed in any
7070 particular time period, it does complete in finite time.
7072 Because any GL program might be executed over a network, or on an
7073 accelerator that buffers commands, all programs should call
7074 @code{glFlush} whenever they count on having all of their previously
7075 issued commands completed. For example, call @code{glFlush} before
7076 waiting for user input that depends on the generated image.
7078 @code{GL_INVALID_OPERATION} is generated if @code{glFlush} is executed
7079 between the execution of @code{glBegin} and the corresponding execution
7084 @deftypefun void glFogCoordPointer type stride pointer
7085 Define an array of fog coordinates.
7089 Specifies the data type of each fog coordinate. Symbolic constants
7090 @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is
7094 Specifies the byte offset between consecutive fog coordinates. If
7095 @var{stride} is 0, the array elements are understood to be tightly
7096 packed. The initial value is 0.
7099 Specifies a pointer to the first coordinate of the first fog coordinate
7100 in the array. The initial value is 0.
7104 @code{glFogCoordPointer} specifies the location and data format of an
7105 array of fog coordinates to use when rendering. @var{type} specifies
7106 the data type of each fog coordinate, and @var{stride} specifies the
7107 byte stride from one fog coordinate to the next, allowing vertices and
7108 attributes to be packed into a single array or stored in separate
7111 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
7112 target (see @code{glBindBuffer}) while a fog coordinate array is
7113 specified, @var{pointer} is treated as a byte offset into the buffer
7114 object's data store. Also, the buffer object binding
7115 (@code{GL_ARRAY_BUFFER_BINDING}) is saved as fog coordinate vertex array
7116 client-side state (@code{GL_FOG_COORD_ARRAY_BUFFER_BINDING}).
7118 When a fog coordinate array is specified, @var{type}, @var{stride}, and
7119 @var{pointer} are saved as client-side state, in addition to the current
7120 vertex array buffer object binding.
7122 To enable and disable the fog coordinate array, call
7123 @code{glEnableClientState} and @code{glDisableClientState} with the
7124 argument @code{GL_FOG_COORD_ARRAY}. If enabled, the fog coordinate
7125 array is used when @code{glDrawArrays}, @code{glMultiDrawArrays},
7126 @code{glDrawElements}, @code{glMultiDrawElements},
7127 @code{glDrawRangeElements}, or @code{glArrayElement} is called.
7129 @code{GL_INVALID_ENUM} is generated if @var{type} is not either
7130 @code{GL_FLOAT} or @code{GL_DOUBLE}.
7132 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
7136 @deftypefun void glFogCoordd coord
7137 @deftypefunx void glFogCoordf coord
7138 @deftypefunx void glFogCoorddv coord
7139 @deftypefunx void glFogCoordfv coord
7140 Set the current fog coordinates.
7144 Specify the fog distance.
7148 @code{glFogCoord} specifies the fog coordinate that is associated with
7149 each vertex and the current raster position. The value specified is
7150 interpolated and used in computing the fog color (see @code{glFog}).
7154 @deftypefun void glFogf pname param
7155 @deftypefunx void glFogi pname param
7156 @deftypefunx void glFogfv pname params
7157 @deftypefunx void glFogiv pname params
7158 Specify fog parameters.
7162 Specifies a single-valued fog parameter. @code{GL_FOG_MODE},
7163 @code{GL_FOG_DENSITY}, @code{GL_FOG_START}, @code{GL_FOG_END},
7164 @code{GL_FOG_INDEX}, and @code{GL_FOG_COORD_SRC} are accepted.
7167 Specifies the value that @var{pname} will be set to.
7171 Fog is initially disabled. While enabled, fog affects rasterized
7172 geometry, bitmaps, and pixel blocks, but not buffer clear operations. To
7173 enable and disable fog, call @code{glEnable} and @code{glDisable} with
7174 argument @code{GL_FOG}.
7176 @code{glFog} assigns the value or values in @var{params} to the fog
7177 parameter specified by @var{pname}. The following values are accepted
7181 @item @code{GL_FOG_MODE}
7182 @var{params} is a single integer or floating-point value that specifies
7183 the equation to be used to compute the fog blend factor, @r{@var{f}}.
7184 Three symbolic constants are accepted: @code{GL_LINEAR}, @code{GL_EXP},
7185 and @code{GL_EXP2}. The equations corresponding to these symbolic
7186 constants are defined below. The initial fog mode is @code{GL_EXP}.
7188 @item @code{GL_FOG_DENSITY}
7189 @var{params} is a single integer or floating-point value that specifies
7190 @r{@var{density}}, the fog density used in both exponential fog
7191 equations. Only nonnegative densities are accepted. The initial fog
7194 @item @code{GL_FOG_START}
7195 @var{params} is a single integer or floating-point value that specifies
7196 @r{@var{start}}, the near distance used in the linear fog equation. The
7197 initial near distance is 0.
7199 @item @code{GL_FOG_END}
7200 @var{params} is a single integer or floating-point value that specifies
7201 @r{@var{end}}, the far distance used in the linear fog equation. The
7202 initial far distance is 1.
7204 @item @code{GL_FOG_INDEX}
7205 @var{params} is a single integer or floating-point value that specifies
7206 @r{@var{i}_@var{f}}, the fog color index. The initial fog index is 0.
7208 @item @code{GL_FOG_COLOR}
7209 @var{params} contains four integer or floating-point values that specify
7210 @r{@var{C}_@var{f}}, the fog color. Integer values are mapped linearly
7211 such that the most positive representable value maps to 1.0, and the
7212 most negative representable value maps to @r{-1.0}. Floating-point
7213 values are mapped directly. After conversion, all color components are
7214 clamped to the range @r{[0,1]}. The initial fog color is (0, 0, 0, 0).
7216 @item @code{GL_FOG_COORD_SRC}
7217 @var{params} contains either of the following symbolic constants:
7218 @code{GL_FOG_COORD} or @code{GL_FRAGMENT_DEPTH}. @code{GL_FOG_COORD}
7219 specifies that the current fog coordinate should be used as distance
7220 value in the fog color computation. @code{GL_FRAGMENT_DEPTH} specifies
7221 that the current fragment depth should be used as distance value in the
7226 Fog blends a fog color with each rasterized pixel fragment's
7227 post-texturing color using a blending factor @r{@var{f}}. Factor
7228 @r{@var{f}} is computed in one of three ways, depending on the fog mode.
7229 Let @r{@var{c}} be either the distance in eye coordinate from the origin
7230 (in the case that the @code{GL_FOG_COORD_SRC} is
7231 @code{GL_FRAGMENT_DEPTH}) or the current fog coordinate (in the case
7232 that @code{GL_FOG_COORD_SRC} is @code{GL_FOG_COORD}). The equation for
7233 @code{GL_LINEAR} fog is
7234 @r{@var{f}=@var{end}-@var{c},/@var{end}-@var{start},}
7236 The equation for @code{GL_EXP} fog is
7237 @r{@var{f}=@var{e}^-(@var{density}·@var{c},),}
7239 The equation for @code{GL_EXP2} fog is
7240 @r{@var{f}=@var{e}^-(@var{density}·@var{c},),^2}
7242 Regardless of the fog mode, @r{@var{f}} is clamped to the range
7243 @r{[0,1]} after it is computed. Then, if the GL is in RGBA color mode,
7244 the fragment's red, green, and blue colors, represented by
7245 @r{@var{C}_@var{r}}, are replaced by
7247 @r{@var{C}_@var{r},^″=@var{f}×@var{C}_@var{r}+(1-@var{f},)×@var{C}_@var{f}}
7249 Fog does not affect a fragment's alpha component.
7251 In color index mode, the fragment's color index @r{@var{i}_@var{r}} is
7254 @r{@var{i}_@var{r},^″=@var{i}_@var{r}+(1-@var{f},)×@var{i}_@var{f}}
7258 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
7259 value, or if @var{pname} is @code{GL_FOG_MODE} and @var{params} is not
7262 @code{GL_INVALID_VALUE} is generated if @var{pname} is
7263 @code{GL_FOG_DENSITY} and @var{params} is negative.
7265 @code{GL_INVALID_OPERATION} is generated if @code{glFog} is executed
7266 between the execution of @code{glBegin} and the corresponding execution
7271 @deftypefun void glFrontFace mode
7272 Define front- and back-facing polygons.
7276 Specifies the orientation of front-facing polygons. @code{GL_CW} and
7277 @code{GL_CCW} are accepted. The initial value is @code{GL_CCW}.
7281 In a scene composed entirely of opaque closed surfaces, back-facing
7282 polygons are never visible. Eliminating these invisible polygons has
7283 the obvious benefit of speeding up the rendering of the image. To
7284 enable and disable elimination of back-facing polygons, call
7285 @code{glEnable} and @code{glDisable} with argument @code{GL_CULL_FACE}.
7287 The projection of a polygon to window coordinates is said to have
7288 clockwise winding if an imaginary object following the path from its
7289 first vertex, its second vertex, and so on, to its last vertex, and
7290 finally back to its first vertex, moves in a clockwise direction about
7291 the interior of the polygon. The polygon's winding is said to be
7292 counterclockwise if the imaginary object following the same path moves
7293 in a counterclockwise direction about the interior of the polygon.
7294 @code{glFrontFace} specifies whether polygons with clockwise winding in
7295 window coordinates, or counterclockwise winding in window coordinates,
7296 are taken to be front-facing. Passing @code{GL_CCW} to @var{mode}
7297 selects counterclockwise polygons as front-facing; @code{GL_CW} selects
7298 clockwise polygons as front-facing. By default, counterclockwise
7299 polygons are taken to be front-facing.
7301 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
7304 @code{GL_INVALID_OPERATION} is generated if @code{glFrontFace} is
7305 executed between the execution of @code{glBegin} and the corresponding
7306 execution of @code{glEnd}.
7310 @deftypefun void glFrustum left right bottom top nearVal farVal
7311 Multiply the current matrix by a perspective matrix.
7316 Specify the coordinates for the left and right vertical clipping planes.
7320 Specify the coordinates for the bottom and top horizontal clipping
7325 Specify the distances to the near and far depth clipping planes. Both
7326 distances must be positive.
7330 @code{glFrustum} describes a perspective matrix that produces a
7331 perspective projection. The current matrix (see @code{glMatrixMode}) is
7332 multiplied by this matrix and the result replaces the current matrix, as
7333 if @code{glMultMatrix} were called with the following matrix as its
7338 @r{[(2@var{nearVal},/@var{right}-@var{left},, 0 @var{A} 0), (0
7339 2@var{nearVal},/@var{top}-@var{bottom},, @var{B} 0), (0 0 @var{C}
7340 @var{D}), (0 0 -1 0),]}
7342 @r{@var{A}=@var{right}+@var{left},/@var{right}-@var{left},}
7344 @r{@var{B}=@var{top}+@var{bottom},/@var{top}-@var{bottom},}
7346 @r{@var{C}=-@var{farVal}+@var{nearVal},/@var{farVal}-@var{nearVal},,}
7348 @r{@var{D}=-2@var{farVal}@var{nearVal},/@var{farVal}-@var{nearVal},,}
7352 Typically, the matrix mode is @code{GL_PROJECTION}, and
7353 @r{(@var{left},@var{bottom}-@var{nearVal})} and
7354 @r{(@var{right},@var{top}-@var{nearVal})} specify the points on the near
7355 clipping plane that are mapped to the lower left and upper right corners
7356 of the window, assuming that the eye is located at (0, 0, 0).
7357 @r{-@var{farVal}} specifies the location of the far clipping plane. Both
7358 @var{nearVal} and @var{farVal} must be positive.
7360 Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the
7361 current matrix stack.
7363 @code{GL_INVALID_VALUE} is generated if @var{nearVal} or @var{farVal} is
7364 not positive, or if @var{left} = @var{right}, or @var{bottom} =
7365 @var{top}, or @var{near} = @var{far}.
7367 @code{GL_INVALID_OPERATION} is generated if @code{glFrustum} is executed
7368 between the execution of @code{glBegin} and the corresponding execution
7373 @deftypefun void glGenBuffers n buffers
7374 Generate buffer object names.
7378 Specifies the number of buffer object names to be generated.
7381 Specifies an array in which the generated buffer object names are
7386 @code{glGenBuffers} returns @var{n} buffer object names in
7387 @var{buffers}. There is no guarantee that the names form a contiguous
7388 set of integers; however, it is guaranteed that none of the returned
7389 names was in use immediately before the call to @code{glGenBuffers}.
7391 Buffer object names returned by a call to @code{glGenBuffers} are not
7392 returned by subsequent calls, unless they are first deleted with
7393 @code{glDeleteBuffers}.
7395 No buffer objects are associated with the returned buffer object names
7396 until they are first bound by calling @code{glBindBuffer}.
7398 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
7400 @code{GL_INVALID_OPERATION} is generated if @code{glGenBuffers} is
7401 executed between the execution of @code{glBegin} and the corresponding
7402 execution of @code{glEnd}.
7406 @deftypefun GLuint glGenLists range
7407 Generate a contiguous set of empty display lists.
7411 Specifies the number of contiguous empty display lists to be generated.
7415 @code{glGenLists} has one argument, @var{range}. It returns an integer
7416 @var{n} such that @var{range} contiguous empty display lists, named
7417 @r{@var{n}}, @r{@var{n}+1}, @r{@var{...}}, @r{@var{n}+@var{range}-1},
7418 are created. If @var{range} is 0, if there is no group of @var{range}
7419 contiguous names available, or if any error is generated, no display
7420 lists are generated, and 0 is returned.
7422 @code{GL_INVALID_VALUE} is generated if @var{range} is negative.
7424 @code{GL_INVALID_OPERATION} is generated if @code{glGenLists} is
7425 executed between the execution of @code{glBegin} and the corresponding
7426 execution of @code{glEnd}.
7430 @deftypefun void glGenQueries n ids
7431 Generate query object names.
7435 Specifies the number of query object names to be generated.
7438 Specifies an array in which the generated query object names are stored.
7442 @code{glGenQueries} returns @var{n} query object names in @var{ids}.
7443 There is no guarantee that the names form a contiguous set of integers;
7444 however, it is guaranteed that none of the returned names was in use
7445 immediately before the call to @code{glGenQueries}.
7447 Query object names returned by a call to @code{glGenQueries} are not
7448 returned by subsequent calls, unless they are first deleted with
7449 @code{glDeleteQueries}.
7451 No query objects are associated with the returned query object names
7452 until they are first used by calling @code{glBeginQuery}.
7454 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
7456 @code{GL_INVALID_OPERATION} is generated if @code{glGenQueries} is
7457 executed between the execution of @code{glBegin} and the corresponding
7458 execution of @code{glEnd}.
7462 @deftypefun void glGenTextures n textures
7463 Generate texture names.
7467 Specifies the number of texture names to be generated.
7469 @item @var{textures}
7470 Specifies an array in which the generated texture names are stored.
7474 @code{glGenTextures} returns @var{n} texture names in @var{textures}.
7475 There is no guarantee that the names form a contiguous set of integers;
7476 however, it is guaranteed that none of the returned names was in use
7477 immediately before the call to @code{glGenTextures}.
7479 The generated textures have no dimensionality; they assume the
7480 dimensionality of the texture target to which they are first bound (see
7481 @code{glBindTexture}).
7483 Texture names returned by a call to @code{glGenTextures} are not
7484 returned by subsequent calls, unless they are first deleted with
7485 @code{glDeleteTextures}.
7487 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
7489 @code{GL_INVALID_OPERATION} is generated if @code{glGenTextures} is
7490 executed between the execution of @code{glBegin} and the corresponding
7491 execution of @code{glEnd}.
7495 @deftypefun void glGetActiveAttrib program index bufSize length size type name
7496 Returns information about an active attribute variable for the specified
7501 Specifies the program object to be queried.
7504 Specifies the index of the attribute variable to be queried.
7507 Specifies the maximum number of characters OpenGL is allowed to write in
7508 the character buffer indicated by @var{name}.
7511 Returns the number of characters actually written by OpenGL in the
7512 string indicated by @var{name} (excluding the null terminator) if a
7513 value other than @code{NULL} is passed.
7516 Returns the size of the attribute variable.
7519 Returns the data type of the attribute variable.
7522 Returns a null terminated string containing the name of the attribute
7527 @code{glGetActiveAttrib} returns information about an active attribute
7528 variable in the program object specified by @var{program}. The number
7529 of active attributes can be obtained by calling @code{glGetProgram} with
7530 the value @code{GL_ACTIVE_ATTRIBUTES}. A value of 0 for @var{index}
7531 selects the first active attribute variable. Permissible values for
7532 @var{index} range from 0 to the number of active attribute variables
7535 A vertex shader may use either built-in attribute variables,
7536 user-defined attribute variables, or both. Built-in attribute variables
7537 have a prefix of "gl_" and reference conventional OpenGL vertex
7538 attribtes (e.g., @var{gl_Vertex}, @var{gl_Normal}, etc., see the OpenGL
7539 Shading Language specification for a complete list.) User-defined
7540 attribute variables have arbitrary names and obtain their values through
7541 numbered generic vertex attributes. An attribute variable (either
7542 built-in or user-defined) is considered active if it is determined
7543 during the link operation that it may be accessed during program
7544 execution. Therefore, @var{program} should have previously been the
7545 target of a call to @code{glLinkProgram}, but it is not necessary for it
7546 to have been linked successfully.
7548 The size of the character buffer required to store the longest attribute
7549 variable name in @var{program} can be obtained by calling
7550 @code{glGetProgram} with the value
7551 @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH}. This value should be used to
7552 allocate a buffer of sufficient size to store the returned attribute
7553 name. The size of this character buffer is passed in @var{bufSize}, and
7554 a pointer to this character buffer is passed in @var{name}.
7556 @code{glGetActiveAttrib} returns the name of the attribute variable
7557 indicated by @var{index}, storing it in the character buffer specified
7558 by @var{name}. The string returned will be null terminated. The actual
7559 number of characters written into this buffer is returned in
7560 @var{length}, and this count does not include the null termination
7561 character. If the length of the returned string is not required, a
7562 value of @code{NULL} can be passed in the @var{length} argument.
7564 The @var{type} argument will return a pointer to the attribute
7565 variable's data type. The symbolic constants @code{GL_FLOAT},
7566 @code{GL_FLOAT_VEC2}, @code{GL_FLOAT_VEC3}, @code{GL_FLOAT_VEC4},
7567 @code{GL_FLOAT_MAT2}, @code{GL_FLOAT_MAT3}, @code{GL_FLOAT_MAT4},
7568 @code{GL_FLOAT_MAT2x3}, @code{GL_FLOAT_MAT2x4}, @code{GL_FLOAT_MAT3x2},
7569 @code{GL_FLOAT_MAT3x4}, @code{GL_FLOAT_MAT4x2}, or
7570 @code{GL_FLOAT_MAT4x3} may be returned. The @var{size} argument will
7571 return the size of the attribute, in units of the type returned in
7574 The list of active attribute variables may include both built-in
7575 attribute variables (which begin with the prefix "gl_") as well as
7576 user-defined attribute variable names.
7578 This function will return as much information as it can about the
7579 specified active attribute variable. If no information is available,
7580 @var{length} will be 0, and @var{name} will be an empty string. This
7581 situation could occur if this function is called after a link operation
7582 that failed. If an error occurs, the return values @var{length},
7583 @var{size}, @var{type}, and @var{name} will be unmodified.
7585 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
7586 generated by OpenGL.
7588 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
7591 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
7592 equal to the number of active attribute variables in @var{program}.
7594 @code{GL_INVALID_OPERATION} is generated if @code{glGetActiveAttrib} is
7595 executed between the execution of @code{glBegin} and the corresponding
7596 execution of @code{glEnd}.
7598 @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0.
7602 @deftypefun void glGetActiveUniform program index bufSize length size type name
7603 Returns information about an active uniform variable for the specified
7608 Specifies the program object to be queried.
7611 Specifies the index of the uniform variable to be queried.
7614 Specifies the maximum number of characters OpenGL is allowed to write in
7615 the character buffer indicated by @var{name}.
7618 Returns the number of characters actually written by OpenGL in the
7619 string indicated by @var{name} (excluding the null terminator) if a
7620 value other than @code{NULL} is passed.
7623 Returns the size of the uniform variable.
7626 Returns the data type of the uniform variable.
7629 Returns a null terminated string containing the name of the uniform
7634 @code{glGetActiveUniform} returns information about an active uniform
7635 variable in the program object specified by @var{program}. The number
7636 of active uniform variables can be obtained by calling
7637 @code{glGetProgram} with the value @code{GL_ACTIVE_UNIFORMS}. A value
7638 of 0 for @var{index} selects the first active uniform variable.
7639 Permissible values for @var{index} range from 0 to the number of active
7640 uniform variables minus 1.
7642 Shaders may use either built-in uniform variables, user-defined uniform
7643 variables, or both. Built-in uniform variables have a prefix of "gl_"
7644 and reference existing OpenGL state or values derived from such state
7645 (e.g., @var{gl_Fog}, @var{gl_ModelViewMatrix}, etc., see the OpenGL
7646 Shading Language specification for a complete list.) User-defined
7647 uniform variables have arbitrary names and obtain their values from the
7648 application through calls to @code{glUniform}. A uniform variable
7649 (either built-in or user-defined) is considered active if it is
7650 determined during the link operation that it may be accessed during
7651 program execution. Therefore, @var{program} should have previously been
7652 the target of a call to @code{glLinkProgram}, but it is not necessary
7653 for it to have been linked successfully.
7655 The size of the character buffer required to store the longest uniform
7656 variable name in @var{program} can be obtained by calling
7657 @code{glGetProgram} with the value @code{GL_ACTIVE_UNIFORM_MAX_LENGTH}.
7658 This value should be used to allocate a buffer of sufficient size to
7659 store the returned uniform variable name. The size of this character
7660 buffer is passed in @var{bufSize}, and a pointer to this character
7661 buffer is passed in @var{name.}
7663 @code{glGetActiveUniform} returns the name of the uniform variable
7664 indicated by @var{index}, storing it in the character buffer specified
7665 by @var{name}. The string returned will be null terminated. The actual
7666 number of characters written into this buffer is returned in
7667 @var{length}, and this count does not include the null termination
7668 character. If the length of the returned string is not required, a
7669 value of @code{NULL} can be passed in the @var{length} argument.
7671 The @var{type} argument will return a pointer to the uniform variable's
7672 data type. The symbolic constants @code{GL_FLOAT},
7673 @code{GL_FLOAT_VEC2}, @code{GL_FLOAT_VEC3}, @code{GL_FLOAT_VEC4},
7674 @code{GL_INT}, @code{GL_INT_VEC2}, @code{GL_INT_VEC3},
7675 @code{GL_INT_VEC4}, @code{GL_BOOL}, @code{GL_BOOL_VEC2},
7676 @code{GL_BOOL_VEC3}, @code{GL_BOOL_VEC4}, @code{GL_FLOAT_MAT2},
7677 @code{GL_FLOAT_MAT3}, @code{GL_FLOAT_MAT4}, @code{GL_FLOAT_MAT2x3},
7678 @code{GL_FLOAT_MAT2x4}, @code{GL_FLOAT_MAT3x2}, @code{GL_FLOAT_MAT3x4},
7679 @code{GL_FLOAT_MAT4x2}, @code{GL_FLOAT_MAT4x3}, @code{GL_SAMPLER_1D},
7680 @code{GL_SAMPLER_2D}, @code{GL_SAMPLER_3D}, @code{GL_SAMPLER_CUBE},
7681 @code{GL_SAMPLER_1D_SHADOW}, or @code{GL_SAMPLER_2D_SHADOW} may be
7684 If one or more elements of an array are active, the name of the array is
7685 returned in @var{name}, the type is returned in @var{type}, and the
7686 @var{size} parameter returns the highest array element index used, plus
7687 one, as determined by the compiler and/or linker. Only one active
7688 uniform variable will be reported for a uniform array.
7690 Uniform variables that are declared as structures or arrays of
7691 structures will not be returned directly by this function. Instead,
7692 each of these uniform variables will be reduced to its fundamental
7693 components containing the "." and "[]" operators such that each of the
7694 names is valid as an argument to @code{glGetUniformLocation}. Each of
7695 these reduced uniform variables is counted as one active uniform
7696 variable and is assigned an index. A valid name cannot be a structure,
7697 an array of structures, or a subcomponent of a vector or matrix.
7699 The size of the uniform variable will be returned in @var{size}. Uniform
7700 variables other than arrays will have a size of 1. Structures and
7701 arrays of structures will be reduced as described earlier, such that
7702 each of the names returned will be a data type in the earlier list. If
7703 this reduction results in an array, the size returned will be as
7704 described for uniform arrays; otherwise, the size returned will be 1.
7706 The list of active uniform variables may include both built-in uniform
7707 variables (which begin with the prefix "gl_") as well as user-defined
7708 uniform variable names.
7710 This function will return as much information as it can about the
7711 specified active uniform variable. If no information is available,
7712 @var{length} will be 0, and @var{name} will be an empty string. This
7713 situation could occur if this function is called after a link operation
7714 that failed. If an error occurs, the return values @var{length},
7715 @var{size}, @var{type}, and @var{name} will be unmodified.
7717 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
7718 generated by OpenGL.
7720 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
7723 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
7724 equal to the number of active uniform variables in @var{program}.
7726 @code{GL_INVALID_OPERATION} is generated if @code{glGetActiveUniform} is
7727 executed between the execution of @code{glBegin} and the corresponding
7728 execution of @code{glEnd}.
7730 @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0.
7734 @deftypefun void glGetAttachedShaders program maxCount count shaders
7735 Returns the handles of the shader objects attached to a program object.
7739 Specifies the program object to be queried.
7741 @item @var{maxCount}
7742 Specifies the size of the array for storing the returned object names.
7745 Returns the number of names actually returned in @var{objects}.
7748 Specifies an array that is used to return the names of attached shader
7753 @code{glGetAttachedShaders} returns the names of the shader objects
7754 attached to @var{program}. The names of shader objects that are
7755 attached to @var{program} will be returned in @var{shaders.} The actual
7756 number of shader names written into @var{shaders} is returned in
7757 @var{count.} If no shader objects are attached to @var{program},
7758 @var{count} is set to 0. The maximum number of shader names that may be
7759 returned in @var{shaders} is specified by @var{maxCount}.
7761 If the number of names actually returned is not required (for instance,
7762 if it has just been obtained by calling @code{glGetProgram}), a value of
7763 @code{NULL} may be passed for count. If no shader objects are attached
7764 to @var{program}, a value of 0 will be returned in @var{count}. The
7765 actual number of attached shaders can be obtained by calling
7766 @code{glGetProgram} with the value @code{GL_ATTACHED_SHADERS}.
7768 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
7769 generated by OpenGL.
7771 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
7774 @code{GL_INVALID_VALUE} is generated if @var{maxCount} is less than 0.
7776 @code{GL_INVALID_OPERATION} is generated if @code{glGetAttachedShaders}
7777 is executed between the execution of @code{glBegin} and the
7778 corresponding execution of @code{glEnd}.
7782 @deftypefun GLint glGetAttribLocation program name
7783 Returns the location of an attribute variable.
7787 Specifies the program object to be queried.
7790 Points to a null terminated string containing the name of the attribute
7791 variable whose location is to be queried.
7795 @code{glGetAttribLocation} queries the previously linked program object
7796 specified by @var{program} for the attribute variable specified by
7797 @var{name} and returns the index of the generic vertex attribute that is
7798 bound to that attribute variable. If @var{name} is a matrix attribute
7799 variable, the index of the first column of the matrix is returned. If
7800 the named attribute variable is not an active attribute in the specified
7801 program object or if @var{name} starts with the reserved prefix "gl_", a
7802 value of -1 is returned.
7804 The association between an attribute variable name and a generic
7805 attribute index can be specified at any time by calling
7806 @code{glBindAttribLocation}. Attribute bindings do not go into effect
7807 until @code{glLinkProgram} is called. After a program object has been
7808 linked successfully, the index values for attribute variables remain
7809 fixed until the next link command occurs. The attribute values can only
7810 be queried after a link if the link was successful.
7811 @code{glGetAttribLocation} returns the binding that actually went into
7812 effect the last time @code{glLinkProgram} was called for the specified
7813 program object. Attribute bindings that have been specified since the
7814 last link operation are not returned by @code{glGetAttribLocation}.
7816 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a value
7817 generated by OpenGL.
7819 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
7822 @code{GL_INVALID_OPERATION} is generated if @var{program} has not been
7823 successfully linked.
7825 @code{GL_INVALID_OPERATION} is generated if @code{glGetAttribLocation}
7826 is executed between the execution of @code{glBegin} and the
7827 corresponding execution of @code{glEnd}.
7831 @deftypefun void glGetBufferParameteriv target value data
7832 Return parameters of a buffer object.
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 symbolic name of a buffer object parameter. Accepted
7842 values are @code{GL_BUFFER_ACCESS}, @code{GL_BUFFER_MAPPED},
7843 @code{GL_BUFFER_SIZE}, or @code{GL_BUFFER_USAGE}.
7846 Returns the requested parameter.
7850 @code{glGetBufferParameteriv} returns in @var{data} a selected parameter
7851 of the buffer object specified by @var{target}.
7853 @var{value} names a specific buffer object parameter, as follows:
7856 @item @code{GL_BUFFER_ACCESS}
7857 @var{params} returns the access policy set while mapping the buffer
7858 object. The initial value is @code{GL_READ_WRITE}.
7860 @item @code{GL_BUFFER_MAPPED}
7861 @var{params} returns a flag indicating whether the buffer object is
7862 currently mapped. The initial value is @code{GL_FALSE}.
7864 @item @code{GL_BUFFER_SIZE}
7865 @var{params} returns the size of the buffer object, measured in bytes.
7866 The initial value is 0.
7868 @item @code{GL_BUFFER_USAGE}
7869 @var{params} returns the buffer object's usage pattern. The initial
7870 value is @code{GL_STATIC_DRAW}.
7874 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{value} is
7875 not an accepted value.
7877 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
7878 name 0 is bound to @var{target}.
7880 @code{GL_INVALID_OPERATION} is generated if
7881 @code{glGetBufferParameteriv} is executed between the execution of
7882 @code{glBegin} and the corresponding execution of @code{glEnd}.
7886 @deftypefun void glGetBufferPointerv target pname params
7887 Return the pointer to a mapped buffer object's data store.
7891 Specifies the target buffer object. The symbolic constant must be
7892 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
7893 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
7896 Specifies the pointer to be returned. The symbolic constant must be
7897 @code{GL_BUFFER_MAP_POINTER}.
7900 Returns the pointer value specified by @var{pname}.
7904 @code{glGetBufferPointerv} returns pointer information. @var{pname} is
7905 a symbolic constant indicating the pointer to be returned, which must be
7906 @code{GL_BUFFER_MAP_POINTER}, the pointer to which the buffer object's
7907 data store is mapped. If the data store is not currently mapped,
7908 @code{NULL} is returned. @var{params} is a pointer to a location in
7909 which to place the returned pointer value.
7911 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
7912 not an accepted value.
7914 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
7915 name 0 is bound to @var{target}.
7917 @code{GL_INVALID_OPERATION} is generated if @code{glGetBufferPointerv}
7918 is executed between the execution of @code{glBegin} and the
7919 corresponding execution of @code{glEnd}.
7923 @deftypefun void glGetBufferSubData target offset size data
7924 Returns a subset of a buffer object's data store.
7928 Specifies the target buffer object. The symbolic constant must be
7929 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
7930 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
7933 Specifies the offset into the buffer object's data store from which data
7934 will be returned, measured in bytes.
7937 Specifies the size in bytes of the data store region being returned.
7940 Specifies a pointer to the location where buffer object data is
7945 @code{glGetBufferSubData} returns some or all of the data from the
7946 buffer object currently bound to @var{target}. Data starting at byte
7947 offset @var{offset} and extending for @var{size} bytes is copied from
7948 the data store to the memory pointed to by @var{data}. An error is
7949 thrown if the buffer object is currently mapped, or if @var{offset} and
7950 @var{size} together define a range beyond the bounds of the buffer
7951 object's data store.
7953 @code{GL_INVALID_ENUM} is generated if @var{target} is not
7954 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
7955 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
7957 @code{GL_INVALID_VALUE} is generated if @var{offset} or @var{size} is
7958 negative, or if together they define a region of memory that extends
7959 beyond the buffer object's allocated data store.
7961 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
7962 name 0 is bound to @var{target}.
7964 @code{GL_INVALID_OPERATION} is generated if the buffer object being
7967 @code{GL_INVALID_OPERATION} is generated if @code{glGetBufferSubData} is
7968 executed between the execution of @code{glBegin} and the corresponding
7969 execution of @code{glEnd}.
7973 @deftypefun void glGetClipPlane plane equation
7974 Return the coefficients of the specified clipping plane.
7978 Specifies a clipping plane. The number of clipping planes depends on
7979 the implementation, but at least six clipping planes are supported. They
7980 are identified by symbolic names of the form
7981 @code{GL_CLIP_PLANE}@r{@var{i}} where i ranges from 0 to the value of
7982 @code{GL_MAX_CLIP_PLANES} - 1.
7984 @item @var{equation}
7985 Returns four double-precision values that are the coefficients of the
7986 plane equation of @var{plane} in eye coordinates. The initial value is
7991 @code{glGetClipPlane} returns in @var{equation} the four coefficients of
7992 the plane equation for @var{plane}.
7994 @code{GL_INVALID_ENUM} is generated if @var{plane} is not an accepted
7997 @code{GL_INVALID_OPERATION} is generated if @code{glGetClipPlane} is
7998 executed between the execution of @code{glBegin} and the corresponding
7999 execution of @code{glEnd}.
8003 @deftypefun void glGetColorTableParameterfv target pname params
8004 @deftypefunx void glGetColorTableParameteriv target pname params
8005 Get color lookup table parameters.
8009 The target color table. Must be @code{GL_COLOR_TABLE},
8010 @code{GL_POST_CONVOLUTION_COLOR_TABLE},
8011 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{GL_PROXY_COLOR_TABLE},
8012 @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or
8013 @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}.
8016 The symbolic name of a color lookup table parameter. Must be one of
8017 @code{GL_COLOR_TABLE_BIAS}, @code{GL_COLOR_TABLE_SCALE},
8018 @code{GL_COLOR_TABLE_FORMAT}, @code{GL_COLOR_TABLE_WIDTH},
8019 @code{GL_COLOR_TABLE_RED_SIZE}, @code{GL_COLOR_TABLE_GREEN_SIZE},
8020 @code{GL_COLOR_TABLE_BLUE_SIZE}, @code{GL_COLOR_TABLE_ALPHA_SIZE},
8021 @code{GL_COLOR_TABLE_LUMINANCE_SIZE}, or
8022 @code{GL_COLOR_TABLE_INTENSITY_SIZE}.
8025 A pointer to an array where the values of the parameter will be stored.
8029 Returns parameters specific to color table @var{target}.
8031 When @var{pname} is set to @code{GL_COLOR_TABLE_SCALE} or
8032 @code{GL_COLOR_TABLE_BIAS}, @code{glGetColorTableParameter} returns the
8033 color table scale or bias parameters for the table specified by
8034 @var{target}. For these queries, @var{target} must be set to
8035 @code{GL_COLOR_TABLE}, @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
8036 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} and @var{params} points to an
8037 array of four elements, which receive the scale or bias factors for red,
8038 green, blue, and alpha, in that order.
8040 @code{glGetColorTableParameter} can also be used to retrieve the format
8041 and size parameters for a color table. For these queries, set
8042 @var{target} to either the color table target or the proxy color table
8043 target. The format and size parameters are set by @code{glColorTable}.
8045 The following table lists the format and size parameters that may be
8046 queried. For each symbolic constant listed below for @var{pname},
8047 @var{params} must point to an array of the given length and receive the
8053 @item @strong{Parameter}
8054 @strong{N}, @strong{Meaning}
8056 @item @code{GL_COLOR_TABLE_FORMAT}
8057 1 , Internal format (e.g., @code{GL_RGBA})
8059 @item @code{GL_COLOR_TABLE_WIDTH}
8060 1 , Number of elements in table
8062 @item @code{GL_COLOR_TABLE_RED_SIZE}
8063 1 , Size of red component, in bits
8065 @item @code{GL_COLOR_TABLE_GREEN_SIZE}
8066 1 , Size of green component
8068 @item @code{GL_COLOR_TABLE_BLUE_SIZE}
8069 1 , Size of blue component
8071 @item @code{GL_COLOR_TABLE_ALPHA_SIZE}
8072 1 , Size of alpha component
8074 @item @code{GL_COLOR_TABLE_LUMINANCE_SIZE}
8075 1 , Size of luminance component
8077 @item @code{GL_COLOR_TABLE_INTENSITY_SIZE}
8078 1 , Size of intensity component
8084 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
8085 not an acceptable value.
8087 @code{GL_INVALID_OPERATION} is generated if
8088 @code{glGetColorTableParameter} is executed between the execution of
8089 @code{glBegin} and the corresponding execution of @code{glEnd}.
8093 @deftypefun void glGetColorTable target format type table
8094 Retrieve contents of a color lookup table.
8098 Must be @code{GL_COLOR_TABLE}, @code{GL_POST_CONVOLUTION_COLOR_TABLE},
8099 or @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}.
8102 The format of the pixel data in @var{table}. The possible values are
8103 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
8104 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB},
8105 @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}.
8108 The type of the pixel data in @var{table}. Symbolic constants
8109 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
8110 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
8111 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
8112 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
8113 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
8114 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
8115 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
8116 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
8117 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
8120 Pointer to a one-dimensional array of pixel data containing the contents
8125 @code{glGetColorTable} returns in @var{table} the contents of the color
8126 table specified by @var{target}. No pixel transfer operations are
8127 performed, but pixel storage modes that are applicable to
8128 @code{glReadPixels} are performed.
8130 If a non-zero named buffer object is bound to the
8131 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
8132 histogram table is requested, @var{table} is treated as a byte offset
8133 into the buffer object's data store.
8135 Color components that are requested in the specified @var{format}, but
8136 which are not included in the internal format of the color lookup table,
8137 are returned as zero. The assignments of internal color components to
8138 the components requested by @var{format} are
8141 @item @strong{Internal Component}
8142 @strong{Resulting Component}
8172 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
8175 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
8178 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
8181 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8182 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
8183 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
8184 and @var{format} is not @code{GL_RGB}.
8186 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8187 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
8188 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
8189 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
8190 @code{GL_UNSIGNED_INT_10_10_10_2}, or
8191 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
8192 @code{GL_RGBA} nor @code{GL_BGRA}.
8194 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8195 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
8196 object's data store is currently mapped.
8198 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8199 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
8200 would be packed to the buffer object such that the memory writes
8201 required would exceed the data store size.
8203 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8204 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{table}
8205 is not evenly divisible into the number of bytes needed to store in
8206 memory a datum indicated by @var{type}.
8208 @code{GL_INVALID_OPERATION} is generated if @code{glGetColorTable} is
8209 executed between the execution of @code{glBegin} and the corresponding
8210 execution of @code{glEnd}.
8214 @deftypefun void glGetCompressedTexImage target lod img
8215 Return a compressed texture image.
8219 Specifies which texture is to be obtained. @code{GL_TEXTURE_1D},
8220 @code{GL_TEXTURE_2D}, and
8221 @code{GL_TEXTURE_3D}@code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
8222 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
8223 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
8224 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
8225 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, and
8226 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z} are accepted.
8229 Specifies the level-of-detail number of the desired image. Level 0 is
8230 the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap
8234 Returns the compressed texture image.
8238 @code{glGetCompressedTexImage} returns the compressed texture image
8239 associated with @var{target} and @var{lod} into @var{img}. @var{img}
8240 should be an array of @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} bytes.
8241 @var{target} specifies whether the desired texture image was one
8242 specified by @code{glTexImage1D} (@code{GL_TEXTURE_1D}),
8243 @code{glTexImage2D} (@code{GL_TEXTURE_2D} or any of
8244 @code{GL_TEXTURE_CUBE_MAP_*}), or @code{glTexImage3D}
8245 (@code{GL_TEXTURE_3D}). @var{lod} specifies the level-of-detail number
8246 of the desired image.
8248 If a non-zero named buffer object is bound to the
8249 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
8250 texture image is requested, @var{img} is treated as a byte offset into
8251 the buffer object's data store.
8253 To minimize errors, first verify that the texture is compressed by
8254 calling @code{glGetTexLevelParameter} with argument
8255 @code{GL_TEXTURE_COMPRESSED}. If the texture is compressed, then
8256 determine the amount of memory required to store the compressed texture
8257 by calling @code{glGetTexLevelParameter} with argument
8258 @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE}. Finally, retrieve the internal
8259 format of the texture by calling @code{glGetTexLevelParameter} with
8260 argument @code{GL_TEXTURE_INTERNAL_FORMAT}. To store the texture for
8261 later use, associate the internal format and size with the retrieved
8262 texture image. These data can be used by the respective texture or
8263 subtexture loading routine used for loading @var{target} textures.
8265 @code{GL_INVALID_VALUE} is generated if @var{lod} is less than zero or
8266 greater than the maximum number of LODs permitted by the implementation.
8268 @code{GL_INVALID_OPERATION} is generated if
8269 @code{glGetCompressedTexImage} is used to retrieve a texture that is in
8270 an uncompressed internal format.
8272 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8273 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
8274 object's data store is currently mapped.
8276 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8277 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
8278 would be packed to the buffer object such that the memory writes
8279 required would exceed the data store size.
8281 @code{GL_INVALID_OPERATION} is generated if
8282 @code{glGetCompressedTexImage} is executed between the execution of
8283 @code{glBegin} and the corresponding execution of @code{glEnd}.
8287 @deftypefun void glGetConvolutionFilter target format type image
8288 Get current 1D or 2D convolution filter kernel.
8292 The filter to be retrieved. Must be one of @code{GL_CONVOLUTION_1D} or
8293 @code{GL_CONVOLUTION_2D}.
8296 Format of the output image. Must be one of @code{GL_RED},
8297 @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB},
8298 @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, or
8299 @code{GL_LUMINANCE_ALPHA}.
8302 Data type of components in the output image. Symbolic constants
8303 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
8304 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
8305 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
8306 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
8307 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
8308 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
8309 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
8310 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
8311 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
8314 Pointer to storage for the output image.
8318 @code{glGetConvolutionFilter} returns the current 1D or 2D convolution
8319 filter kernel as an image. The one- or two-dimensional image is placed
8320 in @var{image} according to the specifications in @var{format} and
8321 @var{type}. No pixel transfer operations are performed on this image,
8322 but the relevant pixel storage modes are applied.
8324 If a non-zero named buffer object is bound to the
8325 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
8326 convolution filter is requested, @var{image} is treated as a byte offset
8327 into the buffer object's data store.
8329 Color components that are present in @var{format} but not included in
8330 the internal format of the filter are returned as zero. The assignments
8331 of internal color components to the components of @var{format} are as
8335 @item @strong{Internal Component}
8336 @strong{Resulting Component}
8366 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
8369 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
8372 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
8375 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8376 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
8377 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
8378 and @var{format} is not @code{GL_RGB}.
8380 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8381 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
8382 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
8383 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
8384 @code{GL_UNSIGNED_INT_10_10_10_2}, or
8385 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
8386 @code{GL_RGBA} nor @code{GL_BGRA}.
8388 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8389 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
8390 object's data store is currently mapped.
8392 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8393 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
8394 would be packed to the buffer object such that the memory writes
8395 required would exceed the data store size.
8397 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8398 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{image}
8399 is not evenly divisible into the number of bytes needed to store in
8400 memory a datum indicated by @var{type}.
8402 @code{GL_INVALID_OPERATION} is generated if
8403 @code{glGetConvolutionFilter} is executed between the execution of
8404 @code{glBegin} and the corresponding execution of @code{glEnd}.
8408 @deftypefun void glGetConvolutionParameterfv target pname params
8409 @deftypefunx void glGetConvolutionParameteriv target pname params
8410 Get convolution parameters.
8414 The filter whose parameters are to be retrieved. Must be one of
8415 @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or
8416 @code{GL_SEPARABLE_2D}.
8419 The parameter to be retrieved. Must be one of
8420 @code{GL_CONVOLUTION_BORDER_MODE}, @code{GL_CONVOLUTION_BORDER_COLOR},
8421 @code{GL_CONVOLUTION_FILTER_SCALE}, @code{GL_CONVOLUTION_FILTER_BIAS},
8422 @code{GL_CONVOLUTION_FORMAT}, @code{GL_CONVOLUTION_WIDTH},
8423 @code{GL_CONVOLUTION_HEIGHT}, @code{GL_MAX_CONVOLUTION_WIDTH}, or
8424 @code{GL_MAX_CONVOLUTION_HEIGHT}.
8427 Pointer to storage for the parameters to be retrieved.
8431 @code{glGetConvolutionParameter} retrieves convolution parameters.
8432 @var{target} determines which convolution filter is queried. @var{pname}
8433 determines which parameter is returned:
8436 @item @code{GL_CONVOLUTION_BORDER_MODE}
8439 The convolution border mode. See @code{glConvolutionParameter} for a
8440 list of border modes.
8442 @item @code{GL_CONVOLUTION_BORDER_COLOR}
8445 The current convolution border color. @var{params} must be a pointer to
8446 an array of four elements, which will receive the red, green, blue, and
8447 alpha border colors.
8449 @item @code{GL_CONVOLUTION_FILTER_SCALE}
8452 The current filter scale factors. @var{params} must be a pointer to an
8453 array of four elements, which will receive the red, green, blue, and
8454 alpha filter scale factors in that order.
8456 @item @code{GL_CONVOLUTION_FILTER_BIAS}
8459 The current filter bias factors. @var{params} must be a pointer to an
8460 array of four elements, which will receive the red, green, blue, and
8461 alpha filter bias terms in that order.
8463 @item @code{GL_CONVOLUTION_FORMAT}
8466 The current internal format. See @code{glConvolutionFilter1D},
8467 @code{glConvolutionFilter2D}, and @code{glSeparableFilter2D} for lists
8468 of allowable formats.
8470 @item @code{GL_CONVOLUTION_WIDTH}
8473 The current filter image width.
8475 @item @code{GL_CONVOLUTION_HEIGHT}
8478 The current filter image height.
8480 @item @code{GL_MAX_CONVOLUTION_WIDTH}
8483 The maximum acceptable filter image width.
8485 @item @code{GL_MAX_CONVOLUTION_HEIGHT}
8488 The maximum acceptable filter image height.
8492 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
8495 @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the
8498 @code{GL_INVALID_ENUM} is generated if @var{target} is
8499 @code{GL_CONVOLUTION_1D} and @var{pname} is @code{GL_CONVOLUTION_HEIGHT}
8500 or @code{GL_MAX_CONVOLUTION_HEIGHT}.
8502 @code{GL_INVALID_OPERATION} is generated if
8503 @code{glGetConvolutionParameter} is executed between the execution of
8504 @code{glBegin} and the corresponding execution of @code{glEnd}.
8508 @deftypefun GLenum glGetError
8509 Return error information.
8511 @code{glGetError} returns the value of the error flag. Each detectable
8512 error is assigned a numeric code and symbolic name. When an error
8513 occurs, the error flag is set to the appropriate error code value. No
8514 other errors are recorded until @code{glGetError} is called, the error
8515 code is returned, and the flag is reset to @code{GL_NO_ERROR}. If a
8516 call to @code{glGetError} returns @code{GL_NO_ERROR}, there has been no
8517 detectable error since the last call to @code{glGetError}, or since the
8520 To allow for distributed implementations, there may be several error
8521 flags. If any single error flag has recorded an error, the value of
8522 that flag is returned and that flag is reset to @code{GL_NO_ERROR} when
8523 @code{glGetError} is called. If more than one flag has recorded an
8524 error, @code{glGetError} returns and clears an arbitrary error flag
8525 value. Thus, @code{glGetError} should always be called in a loop, until
8526 it returns @code{GL_NO_ERROR}, if all error flags are to be reset.
8528 Initially, all error flags are set to @code{GL_NO_ERROR}.
8530 The following errors are currently defined:
8533 @item @code{GL_NO_ERROR}
8534 No error has been recorded. The value of this symbolic constant is
8537 @item @code{GL_INVALID_ENUM}
8538 An unacceptable value is specified for an enumerated argument. The
8539 offending command is ignored and has no other side effect than to set
8542 @item @code{GL_INVALID_VALUE}
8543 A numeric argument is out of range. The offending command is ignored
8544 and has no other side effect than to set the error flag.
8546 @item @code{GL_INVALID_OPERATION}
8547 The specified operation is not allowed in the current state. The
8548 offending command is ignored and has no other side effect than to set
8551 @item @code{GL_STACK_OVERFLOW}
8552 This command would cause a stack overflow. The offending command is
8553 ignored and has no other side effect than to set the error flag.
8555 @item @code{GL_STACK_UNDERFLOW}
8556 This command would cause a stack underflow. The offending command is
8557 ignored and has no other side effect than to set the error flag.
8559 @item @code{GL_OUT_OF_MEMORY}
8560 There is not enough memory left to execute the command. The state of
8561 the GL is undefined, except for the state of the error flags, after this
8564 @item @code{GL_TABLE_TOO_LARGE}
8565 The specified table exceeds the implementation's maximum supported table
8566 size. The offending command is ignored and has no other side effect
8567 than to set the error flag.
8571 When an error flag is set, results of a GL operation are undefined only
8572 if @code{GL_OUT_OF_MEMORY} has occurred. In all other cases, the
8573 command generating the error is ignored and has no effect on the GL
8574 state or frame buffer contents. If the generating command returns a
8575 value, it returns 0. If @code{glGetError} itself generates an error, it
8578 @code{GL_INVALID_OPERATION} is generated if @code{glGetError} is
8579 executed between the execution of @code{glBegin} and the corresponding
8580 execution of @code{glEnd}. In this case, @code{glGetError} returns 0.
8584 @deftypefun void glGetHistogramParameterfv target pname params
8585 @deftypefunx void glGetHistogramParameteriv target pname params
8586 Get histogram parameters.
8590 Must be one of @code{GL_HISTOGRAM} or @code{GL_PROXY_HISTOGRAM}.
8593 The name of the parameter to be retrieved. Must be one of
8594 @code{GL_HISTOGRAM_WIDTH}, @code{GL_HISTOGRAM_FORMAT},
8595 @code{GL_HISTOGRAM_RED_SIZE}, @code{GL_HISTOGRAM_GREEN_SIZE},
8596 @code{GL_HISTOGRAM_BLUE_SIZE}, @code{GL_HISTOGRAM_ALPHA_SIZE},
8597 @code{GL_HISTOGRAM_LUMINANCE_SIZE}, or @code{GL_HISTOGRAM_SINK}.
8600 Pointer to storage for the returned values.
8604 @code{glGetHistogramParameter} is used to query parameter values for the
8605 current histogram or for a proxy. The histogram state information may
8606 be queried by calling @code{glGetHistogramParameter} with a @var{target}
8607 of @code{GL_HISTOGRAM} (to obtain information for the current histogram
8608 table) or @code{GL_PROXY_HISTOGRAM} (to obtain information from the most
8609 recent proxy request) and one of the following values for the
8610 @var{pname} argument:
8615 @item @strong{Parameter}
8616 @strong{Description}
8618 @item @code{GL_HISTOGRAM_WIDTH}
8619 Histogram table width
8621 @item @code{GL_HISTOGRAM_FORMAT}
8624 @item @code{GL_HISTOGRAM_RED_SIZE}
8625 Red component counter size, in bits
8627 @item @code{GL_HISTOGRAM_GREEN_SIZE}
8628 Green component counter size, in bits
8630 @item @code{GL_HISTOGRAM_BLUE_SIZE}
8631 Blue component counter size, in bits
8633 @item @code{GL_HISTOGRAM_ALPHA_SIZE}
8634 Alpha component counter size, in bits
8636 @item @code{GL_HISTOGRAM_LUMINANCE_SIZE}
8637 Luminance component counter size, in bits
8639 @item @code{GL_HISTOGRAM_SINK}
8640 Value of the @var{sink} parameter
8646 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
8649 @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the
8652 @code{GL_INVALID_OPERATION} is generated if
8653 @code{glGetHistogramParameter} is executed between the execution of
8654 @code{glBegin} and the corresponding execution of @code{glEnd}.
8658 @deftypefun void glGetHistogram target reset format type values
8659 Get histogram table.
8663 Must be @code{GL_HISTOGRAM}.
8666 If @code{GL_TRUE}, each component counter that is actually returned is
8667 reset to zero. (Other counters are unaffected.) If @code{GL_FALSE},
8668 none of the counters in the histogram table is modified.
8671 The format of values to be returned in @var{values}. Must be one of
8672 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
8673 @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA},
8674 @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}.
8677 The type of values to be returned in @var{values}. Symbolic constants
8678 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
8679 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
8680 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
8681 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
8682 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
8683 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
8684 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
8685 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
8686 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
8689 A pointer to storage for the returned histogram table.
8693 @code{glGetHistogram} returns the current histogram table as a
8694 one-dimensional image with the same width as the histogram. No pixel
8695 transfer operations are performed on this image, but pixel storage modes
8696 that are applicable to 1D images are honored.
8698 If a non-zero named buffer object is bound to the
8699 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
8700 histogram table is requested, @var{values} is treated as a byte offset
8701 into the buffer object's data store.
8703 Color components that are requested in the specified @var{format}, but
8704 which are not included in the internal format of the histogram, are
8705 returned as zero. The assignments of internal color components to the
8706 components requested by @var{format} are:
8709 @item @strong{Internal Component}
8710 @strong{Resulting Component}
8736 @code{GL_INVALID_ENUM} is generated if @var{target} is not
8737 @code{GL_HISTOGRAM}.
8739 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
8742 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
8745 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8746 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
8747 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
8748 and @var{format} is not @code{GL_RGB}.
8750 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8751 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
8752 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
8753 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
8754 @code{GL_UNSIGNED_INT_10_10_10_2}, or
8755 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
8756 @code{GL_RGBA} nor @code{GL_BGRA}.
8758 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8759 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
8760 object's data store is currently mapped.
8762 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8763 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
8764 would be packed to the buffer object such that the memory writes
8765 required would exceed the data store size.
8767 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8768 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{values}
8769 is not evenly divisible into the number of bytes needed to store in
8770 memory a datum indicated by @var{type}.
8772 @code{GL_INVALID_OPERATION} is generated if @code{glGetHistogram} is
8773 executed between the execution of @code{glBegin} and the corresponding
8774 execution of @code{glEnd}.
8778 @deftypefun void glGetLightfv light pname params
8779 @deftypefunx void glGetLightiv light pname params
8780 Return light source parameter values.
8784 Specifies a light source. The number of possible lights depends on the
8785 implementation, but at least eight lights are supported. They are
8786 identified by symbolic names of the form @code{GL_LIGHT}@r{@var{i}}
8787 where @r{@var{i}} ranges from 0 to the value of @code{GL_MAX_LIGHTS} -
8791 Specifies a light source parameter for @var{light}. Accepted symbolic
8792 names are @code{GL_AMBIENT}, @code{GL_DIFFUSE}, @code{GL_SPECULAR},
8793 @code{GL_POSITION}, @code{GL_SPOT_DIRECTION}, @code{GL_SPOT_EXPONENT},
8794 @code{GL_SPOT_CUTOFF}, @code{GL_CONSTANT_ATTENUATION},
8795 @code{GL_LINEAR_ATTENUATION}, and @code{GL_QUADRATIC_ATTENUATION}.
8798 Returns the requested data.
8802 @code{glGetLight} returns in @var{params} the value or values of a light
8803 source parameter. @var{light} names the light and is a symbolic name of
8804 the form @code{GL_LIGHT}@r{@var{i}} where i ranges from 0 to the value
8805 of @code{GL_MAX_LIGHTS} - 1. @code{GL_MAX_LIGHTS} is an implementation
8806 dependent constant that is greater than or equal to eight. @var{pname}
8807 specifies one of ten light source parameters, again by symbolic name.
8809 The following parameters are defined:
8812 @item @code{GL_AMBIENT}
8813 @var{params} returns four integer or floating-point values representing
8814 the ambient intensity of the light source. Integer values, when
8815 requested, are linearly mapped from the internal floating-point
8816 representation such that 1.0 maps to the most positive representable
8817 integer value, and @r{-1.0} maps to the most negative representable
8818 integer value. If the internal value is outside the range @r{[-1,1]},
8819 the corresponding integer return value is undefined. The initial value
8822 @item @code{GL_DIFFUSE}
8823 @var{params} returns four integer or floating-point values representing
8824 the diffuse intensity of the light source. Integer values, when
8825 requested, are linearly mapped from the internal floating-point
8826 representation such that 1.0 maps to the most positive representable
8827 integer value, and @r{-1.0} maps to the most negative representable
8828 integer value. If the internal value is outside the range @r{[-1,1]},
8829 the corresponding integer return value is undefined. The initial value
8830 for @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial
8831 value is (0, 0, 0, 0).
8833 @item @code{GL_SPECULAR}
8834 @var{params} returns four integer or floating-point values representing
8835 the specular intensity of the light source. Integer values, when
8836 requested, are linearly mapped from the internal floating-point
8837 representation such that 1.0 maps to the most positive representable
8838 integer value, and @r{-1.0} maps to the most negative representable
8839 integer value. If the internal value is outside the range @r{[-1,1]},
8840 the corresponding integer return value is undefined. The initial value
8841 for @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial
8842 value is (0, 0, 0, 0).
8844 @item @code{GL_POSITION}
8845 @var{params} returns four integer or floating-point values representing
8846 the position of the light source. Integer values, when requested, are
8847 computed by rounding the internal floating-point values to the nearest
8848 integer value. The returned values are those maintained in eye
8849 coordinates. They will not be equal to the values specified using
8850 @code{glLight}, unless the modelview matrix was identity at the time
8851 @code{glLight} was called. The initial value is (0, 0, 1, 0).
8853 @item @code{GL_SPOT_DIRECTION}
8854 @var{params} returns three integer or floating-point values representing
8855 the direction of the light source. Integer values, when requested, are
8856 computed by rounding the internal floating-point values to the nearest
8857 integer value. The returned values are those maintained in eye
8858 coordinates. They will not be equal to the values specified using
8859 @code{glLight}, unless the modelview matrix was identity at the time
8860 @code{glLight} was called. Although spot direction is normalized before
8861 being used in the lighting equation, the returned values are the
8862 transformed versions of the specified values prior to normalization. The
8863 initial value is @r{(0,0-1)}.
8865 @item @code{GL_SPOT_EXPONENT}
8866 @var{params} returns a single integer or floating-point value
8867 representing the spot exponent of the light. An integer value, when
8868 requested, is computed by rounding the internal floating-point
8869 representation to the nearest integer. The initial value is 0.
8871 @item @code{GL_SPOT_CUTOFF}
8872 @var{params} returns a single integer or floating-point value
8873 representing the spot cutoff angle of the light. An integer value, when
8874 requested, is computed by rounding the internal floating-point
8875 representation to the nearest integer. The initial value is 180.
8877 @item @code{GL_CONSTANT_ATTENUATION}
8878 @var{params} returns a single integer or floating-point value
8879 representing the constant (not distance-related) attenuation of the
8880 light. An integer value, when requested, is computed by rounding the
8881 internal floating-point representation to the nearest integer. The
8884 @item @code{GL_LINEAR_ATTENUATION}
8885 @var{params} returns a single integer or floating-point value
8886 representing the linear attenuation of the light. An integer value,
8887 when requested, is computed by rounding the internal floating-point
8888 representation to the nearest integer. The initial value is 0.
8890 @item @code{GL_QUADRATIC_ATTENUATION}
8891 @var{params} returns a single integer or floating-point value
8892 representing the quadratic attenuation of the light. An integer value,
8893 when requested, is computed by rounding the internal floating-point
8894 representation to the nearest integer. The initial value is 0.
8898 @code{GL_INVALID_ENUM} is generated if @var{light} or @var{pname} is not
8901 @code{GL_INVALID_OPERATION} is generated if @code{glGetLight} is
8902 executed between the execution of @code{glBegin} and the corresponding
8903 execution of @code{glEnd}.
8907 @deftypefun void glGetMapdv target query v
8908 @deftypefunx void glGetMapfv target query v
8909 @deftypefunx void glGetMapiv target query v
8910 Return evaluator parameters.
8914 Specifies the symbolic name of a map. Accepted values are
8915 @code{GL_MAP1_COLOR_4}, @code{GL_MAP1_INDEX}, @code{GL_MAP1_NORMAL},
8916 @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2},
8917 @code{GL_MAP1_TEXTURE_COORD_3}, @code{GL_MAP1_TEXTURE_COORD_4},
8918 @code{GL_MAP1_VERTEX_3}, @code{GL_MAP1_VERTEX_4},
8919 @code{GL_MAP2_COLOR_4}, @code{GL_MAP2_INDEX}, @code{GL_MAP2_NORMAL},
8920 @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2},
8921 @code{GL_MAP2_TEXTURE_COORD_3}, @code{GL_MAP2_TEXTURE_COORD_4},
8922 @code{GL_MAP2_VERTEX_3}, and @code{GL_MAP2_VERTEX_4}.
8925 Specifies which parameter to return. Symbolic names @code{GL_COEFF},
8926 @code{GL_ORDER}, and @code{GL_DOMAIN} are accepted.
8929 Returns the requested data.
8933 @code{glMap1} and @code{glMap2} define evaluators. @code{glGetMap}
8934 returns evaluator parameters. @var{target} chooses a map, @var{query}
8935 selects a specific parameter, and @var{v} points to storage where the
8936 values will be returned.
8938 The acceptable values for the @var{target} parameter are described in
8939 the @code{glMap1} and @code{glMap2} reference pages.
8941 @var{query} can assume the following values:
8944 @item @code{GL_COEFF}
8945 @var{v} returns the control points for the evaluator function.
8946 One-dimensional evaluators return @r{@var{order}} control points, and
8947 two-dimensional evaluators return @r{@var{uorder}×@var{vorder}} control
8948 points. Each control point consists of one, two, three, or four
8949 integer, single-precision floating-point, or double-precision
8950 floating-point values, depending on the type of the evaluator. The GL
8951 returns two-dimensional control points in row-major order, incrementing
8952 the @r{@var{uorder}} index quickly and the @r{@var{vorder}} index after
8953 each row. Integer values, when requested, are computed by rounding the
8954 internal floating-point values to the nearest integer values.
8956 @item @code{GL_ORDER}
8957 @var{v} returns the order of the evaluator function. One-dimensional
8958 evaluators return a single value, @r{@var{order}}. The initial value is
8959 1. Two-dimensional evaluators return two values, @r{@var{uorder}} and
8960 @r{@var{vorder}}. The initial value is 1,1.
8962 @item @code{GL_DOMAIN}
8963 @var{v} returns the linear @r{@var{u}} and @r{@var{v}} mapping
8964 parameters. One-dimensional evaluators return two values, @r{@var{u1}}
8965 and @r{@var{u2}}, as specified by @code{glMap1}. Two-dimensional
8966 evaluators return four values (@r{@var{u1}}, @r{@var{u2}}, @r{@var{v1}},
8967 and @r{@var{v2}}) as specified by @code{glMap2}. Integer values, when
8968 requested, are computed by rounding the internal floating-point values
8969 to the nearest integer values.
8973 @code{GL_INVALID_ENUM} is generated if either @var{target} or
8974 @var{query} is not an accepted value.
8976 @code{GL_INVALID_OPERATION} is generated if @code{glGetMap} is executed
8977 between the execution of @code{glBegin} and the corresponding execution
8982 @deftypefun void glGetMaterialfv face pname params
8983 @deftypefunx void glGetMaterialiv face pname params
8984 Return material parameters.
8988 Specifies which of the two materials is being queried. @code{GL_FRONT}
8989 or @code{GL_BACK} are accepted, representing the front and back
8990 materials, respectively.
8993 Specifies the material parameter to return. @code{GL_AMBIENT},
8994 @code{GL_DIFFUSE}, @code{GL_SPECULAR}, @code{GL_EMISSION},
8995 @code{GL_SHININESS}, and @code{GL_COLOR_INDEXES} are accepted.
8998 Returns the requested data.
9002 @code{glGetMaterial} returns in @var{params} the value or values of
9003 parameter @var{pname} of material @var{face}. Six parameters are
9007 @item @code{GL_AMBIENT}
9008 @var{params} returns four integer or floating-point values representing
9009 the ambient reflectance of the material. Integer values, when
9010 requested, are linearly mapped from the internal floating-point
9011 representation such that 1.0 maps to the most positive representable
9012 integer value, and @r{-1.0} maps to the most negative representable
9013 integer value. If the internal value is outside the range @r{[-1,1]},
9014 the corresponding integer return value is undefined. The initial value
9015 is (0.2, 0.2, 0.2, 1.0)
9017 @item @code{GL_DIFFUSE}
9018 @var{params} returns four integer or floating-point values representing
9019 the diffuse reflectance of the material. Integer values, when
9020 requested, are linearly mapped from the internal floating-point
9021 representation such that 1.0 maps to the most positive representable
9022 integer value, and @r{-1.0} maps to the most negative representable
9023 integer value. If the internal value is outside the range @r{[-1,1]},
9024 the corresponding integer return value is undefined. The initial value
9025 is (0.8, 0.8, 0.8, 1.0).
9027 @item @code{GL_SPECULAR}
9028 @var{params} returns four integer or floating-point values representing
9029 the specular reflectance of the material. Integer values, when
9030 requested, are linearly mapped from the internal floating-point
9031 representation such that 1.0 maps to the most positive representable
9032 integer value, and @r{-1.0} maps to the most negative representable
9033 integer value. If the internal value is outside the range @r{[-1,1]},
9034 the corresponding integer return value is undefined. The initial value
9037 @item @code{GL_EMISSION}
9038 @var{params} returns four integer or floating-point values representing
9039 the emitted light intensity of the material. Integer values, when
9040 requested, are linearly mapped from the internal floating-point
9041 representation such that 1.0 maps to the most positive representable
9042 integer value, and @r{-1.0} maps to the most negative representable
9043 integer value. If the internal value is outside the range @r{[-1,1]},
9044 the corresponding integer return value is undefined. The initial value
9047 @item @code{GL_SHININESS}
9048 @var{params} returns one integer or floating-point value representing
9049 the specular exponent of the material. Integer values, when requested,
9050 are computed by rounding the internal floating-point value to the
9051 nearest integer value. The initial value is 0.
9053 @item @code{GL_COLOR_INDEXES}
9054 @var{params} returns three integer or floating-point values representing
9055 the ambient, diffuse, and specular indices of the material. These
9056 indices are used only for color index lighting. (All the other
9057 parameters are used only for RGBA lighting.) Integer values, when
9058 requested, are computed by rounding the internal floating-point values
9059 to the nearest integer values.
9063 @code{GL_INVALID_ENUM} is generated if @var{face} or @var{pname} is not
9066 @code{GL_INVALID_OPERATION} is generated if @code{glGetMaterial} is
9067 executed between the execution of @code{glBegin} and the corresponding
9068 execution of @code{glEnd}.
9072 @deftypefun void glGetMinmaxParameterfv target pname params
9073 @deftypefunx void glGetMinmaxParameteriv target pname params
9074 Get minmax parameters.
9078 Must be @code{GL_MINMAX}.
9081 The parameter to be retrieved. Must be one of @code{GL_MINMAX_FORMAT}
9082 or @code{GL_MINMAX_SINK}.
9085 A pointer to storage for the retrieved parameters.
9089 @code{glGetMinmaxParameter} retrieves parameters for the current minmax
9090 table by setting @var{pname} to one of the following values:
9095 @item @strong{Parameter}
9096 @strong{Description}
9098 @item @code{GL_MINMAX_FORMAT}
9099 Internal format of minmax table
9101 @item @code{GL_MINMAX_SINK}
9102 Value of the @var{sink} parameter
9108 @code{GL_INVALID_ENUM} is generated if @var{target} is not
9111 @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the
9114 @code{GL_INVALID_OPERATION} is generated if @code{glGetMinmaxParameter}
9115 is executed between the execution of @code{glBegin} and the
9116 corresponding execution of @code{glEnd}.
9120 @deftypefun void glGetMinmax target reset format types values
9121 Get minimum and maximum pixel values.
9125 Must be @code{GL_MINMAX}.
9128 If @code{GL_TRUE}, all entries in the minmax table that are actually
9129 returned are reset to their initial values. (Other entries are
9130 unaltered.) If @code{GL_FALSE}, the minmax table is unaltered.
9133 The format of the data to be returned in @var{values}. Must be one of
9134 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
9135 @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA},
9136 @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}.
9139 The type of the data to be returned in @var{values}. Symbolic constants
9140 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
9141 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
9142 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
9143 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
9144 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
9145 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
9146 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
9147 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
9148 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
9151 A pointer to storage for the returned values.
9155 @code{glGetMinmax} returns the accumulated minimum and maximum pixel
9156 values (computed on a per-component basis) in a one-dimensional image of
9157 width 2. The first set of return values are the minima, and the second
9158 set of return values are the maxima. The format of the return values is
9159 determined by @var{format}, and their type is determined by @var{types}.
9161 If a non-zero named buffer object is bound to the
9162 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while
9163 minimum and maximum pixel values are requested, @var{values} is treated
9164 as a byte offset into the buffer object's data store.
9166 No pixel transfer operations are performed on the return values, but
9167 pixel storage modes that are applicable to one-dimensional images are
9168 performed. Color components that are requested in the specified
9169 @var{format}, but that are not included in the internal format of the
9170 minmax table, are returned as zero. The assignment of internal color
9171 components to the components requested by @var{format} are as follows:
9176 @item @strong{Internal Component}
9177 @strong{Resulting Component}
9201 If @var{reset} is @code{GL_TRUE}, the minmax table entries corresponding
9202 to the return values are reset to their initial values. Minimum and
9203 maximum values that are not returned are not modified, even if
9204 @var{reset} is @code{GL_TRUE}.
9206 @code{GL_INVALID_ENUM} is generated if @var{target} is not
9209 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
9212 @code{GL_INVALID_ENUM} is generated if @var{types} is not one of the
9215 @code{GL_INVALID_OPERATION} is generated if @var{types} is one of
9216 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
9217 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
9218 and @var{format} is not @code{GL_RGB}.
9220 @code{GL_INVALID_OPERATION} is generated if @var{types} is one of
9221 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
9222 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
9223 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
9224 @code{GL_UNSIGNED_INT_10_10_10_2}, or
9225 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
9226 @code{GL_RGBA} nor @code{GL_BGRA}.
9228 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9229 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
9230 object's data store is currently mapped.
9232 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9233 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
9234 would be packed to the buffer object such that the memory writes
9235 required would exceed the data store size.
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 @var{values}
9239 is not evenly divisible into the number of bytes needed to store in
9240 memory a datum indicated by @var{type}.
9242 @code{GL_INVALID_OPERATION} is generated if @code{glGetMinmax} is
9243 executed between the execution of @code{glBegin} and the corresponding
9244 execution of @code{glEnd}.
9248 @deftypefun void glGetPixelMapfv map data
9249 @deftypefunx void glGetPixelMapuiv map data
9250 @deftypefunx void glGetPixelMapusv map data
9251 Return the specified pixel map.
9255 Specifies the name of the pixel map to return. Accepted values are
9256 @code{GL_PIXEL_MAP_I_TO_I}, @code{GL_PIXEL_MAP_S_TO_S},
9257 @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G},
9258 @code{GL_PIXEL_MAP_I_TO_B}, @code{GL_PIXEL_MAP_I_TO_A},
9259 @code{GL_PIXEL_MAP_R_TO_R}, @code{GL_PIXEL_MAP_G_TO_G},
9260 @code{GL_PIXEL_MAP_B_TO_B}, and @code{GL_PIXEL_MAP_A_TO_A}.
9263 Returns the pixel map contents.
9267 See the @code{glPixelMap} reference page for a description of the
9268 acceptable values for the @var{map} parameter. @code{glGetPixelMap}
9269 returns in @var{data} the contents of the pixel map specified in
9270 @var{map}. Pixel maps are used during the execution of
9271 @code{glReadPixels}, @code{glDrawPixels}, @code{glCopyPixels},
9272 @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D},
9273 @code{glTexSubImage1D}, @code{glTexSubImage2D}, @code{glTexSubImage3D},
9274 @code{glCopyTexImage1D}, @code{glCopyTexImage2D},
9275 @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D}, and
9276 @code{glCopyTexSubImage3D}. to map color indices, stencil indices,
9277 color components, and depth components to other values.
9279 If a non-zero named buffer object is bound to the
9280 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
9281 pixel map is requested, @var{data} is treated as a byte offset into the
9282 buffer object's data store.
9284 Unsigned integer values, if requested, are linearly mapped from the
9285 internal fixed or floating-point representation such that 1.0 maps to
9286 the largest representable integer value, and 0.0 maps to 0. Return
9287 unsigned integer values are undefined if the map value was not in the
9290 To determine the required size of @var{map}, call @code{glGet} with the
9291 appropriate symbolic constant.
9293 @code{GL_INVALID_ENUM} is generated if @var{map} is not an accepted
9296 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9297 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
9298 object's data store is currently mapped.
9300 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9301 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
9302 would be packed to the buffer object such that the memory writes
9303 required would exceed the data store size.
9305 @code{GL_INVALID_OPERATION} is generated by @code{glGetPixelMapfv} if a
9306 non-zero buffer object name is bound to the @code{GL_PIXEL_PACK_BUFFER}
9307 target and @var{data} is not evenly divisible into the number of bytes
9308 needed to store in memory a GLfloat datum.
9310 @code{GL_INVALID_OPERATION} is generated by @code{glGetPixelMapuiv} if a
9311 non-zero buffer object name is bound to the @code{GL_PIXEL_PACK_BUFFER}
9312 target and @var{data} is not evenly divisible into the number of bytes
9313 needed to store in memory a GLuint datum.
9315 @code{GL_INVALID_OPERATION} is generated by @code{glGetPixelMapusv} if a
9316 non-zero buffer object name is bound to the @code{GL_PIXEL_PACK_BUFFER}
9317 target and @var{data} is not evenly divisible into the number of bytes
9318 needed to store in memory a GLushort datum.
9320 @code{GL_INVALID_OPERATION} is generated if @code{glGetPixelMap} is
9321 executed between the execution of @code{glBegin} and the corresponding
9322 execution of @code{glEnd}.
9326 @deftypefun void glGetPointerv pname params
9327 Return the address of the specified pointer.
9331 Specifies the array or buffer pointer to be returned. Symbolic
9332 constants @code{GL_COLOR_ARRAY_POINTER},
9333 @code{GL_EDGE_FLAG_ARRAY_POINTER}, @code{GL_FOG_COORD_ARRAY_POINTER},
9334 @code{GL_FEEDBACK_BUFFER_POINTER}, @code{GL_INDEX_ARRAY_POINTER},
9335 @code{GL_NORMAL_ARRAY_POINTER}, @code{GL_SECONDARY_COLOR_ARRAY_POINTER},
9336 @code{GL_SELECTION_BUFFER_POINTER},
9337 @code{GL_TEXTURE_COORD_ARRAY_POINTER}, or @code{GL_VERTEX_ARRAY_POINTER}
9341 Returns the pointer value specified by @var{pname}.
9345 @code{glGetPointerv} returns pointer information. @var{pname} is a
9346 symbolic constant indicating the pointer to be returned, and
9347 @var{params} is a pointer to a location in which to place the returned
9350 For all @var{pname} arguments except @code{GL_FEEDBACK_BUFFER_POINTER}
9351 and @code{GL_SELECTION_BUFFER_POINTER}, if a non-zero named buffer
9352 object was bound to the @code{GL_ARRAY_BUFFER} target (see
9353 @code{glBindBuffer}) when the desired pointer was previously specified,
9354 the pointer returned is a byte offset into the buffer object's data
9355 store. Buffer objects are only available in OpenGL versions 1.5 and
9358 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
9363 @deftypefun void glGetPolygonStipple pattern
9364 Return the polygon stipple pattern.
9368 Returns the stipple pattern. The initial value is all 1's.
9372 @code{glGetPolygonStipple} returns to @var{pattern} a @r{32×32} polygon
9373 stipple pattern. The pattern is packed into memory as if
9374 @code{glReadPixels} with both @var{height} and @var{width} of 32,
9375 @var{type} of @code{GL_BITMAP}, and @var{format} of
9376 @code{GL_COLOR_INDEX} were called, and the stipple pattern were stored
9377 in an internal @r{32×32} color index buffer. Unlike
9378 @code{glReadPixels}, however, pixel transfer operations (shift, offset,
9379 pixel map) are not applied to the returned stipple image.
9381 If a non-zero named buffer object is bound to the
9382 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
9383 polygon stipple pattern is requested, @var{pattern} is treated as a byte
9384 offset into the buffer object's data store.
9386 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9387 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
9388 object's data store is currently mapped.
9390 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9391 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
9392 would be packed to the buffer object such that the memory writes
9393 required would exceed the data store size.
9395 @code{GL_INVALID_OPERATION} is generated if @code{glGetPolygonStipple}
9396 is executed between the execution of @code{glBegin} and the
9397 corresponding execution of @code{glEnd}.
9401 @deftypefun void glGetProgramInfoLog program maxLength length infoLog
9402 Returns the information log for a program object.
9406 Specifies the program object whose information log is to be queried.
9408 @item @var{maxLength}
9409 Specifies the size of the character buffer for storing the returned
9413 Returns the length of the string returned in @var{infoLog} (excluding
9414 the null terminator).
9417 Specifies an array of characters that is used to return the information
9422 @code{glGetProgramInfoLog} returns the information log for the specified
9423 program object. The information log for a program object is modified
9424 when the program object is linked or validated. The string that is
9425 returned will be null terminated.
9427 @code{glGetProgramInfoLog} returns in @var{infoLog} as much of the
9428 information log as it can, up to a maximum of @var{maxLength}
9429 characters. The number of characters actually returned, excluding the
9430 null termination character, is specified by @var{length}. If the length
9431 of the returned string is not required, a value of @code{NULL} can be
9432 passed in the @var{length} argument. The size of the buffer required to
9433 store the returned information log can be obtained by calling
9434 @code{glGetProgram} with the value @code{GL_INFO_LOG_LENGTH}.
9436 The information log for a program object is either an empty string, or a
9437 string containing information about the last link operation, or a string
9438 containing information about the last validation operation. It may
9439 contain diagnostic messages, warning messages, and other information.
9440 When a program object is created, its information log will be a string
9443 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
9444 generated by OpenGL.
9446 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
9449 @code{GL_INVALID_VALUE} is generated if @var{maxLength} is less than 0.
9451 @code{GL_INVALID_OPERATION} is generated if @code{glGetProgramInfoLog}
9452 is executed between the execution of @code{glBegin} and the
9453 corresponding execution of @code{glEnd}.
9457 @deftypefun void glGetProgramiv program pname params
9458 Returns a parameter from a program object.
9462 Specifies the program object to be queried.
9465 Specifies the object parameter. Accepted symbolic names are
9466 @code{GL_DELETE_STATUS}, @code{GL_LINK_STATUS},
9467 @code{GL_VALIDATE_STATUS}, @code{GL_INFO_LOG_LENGTH},
9468 @code{GL_ATTACHED_SHADERS}, @code{GL_ACTIVE_ATTRIBUTES},
9469 @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH}, @code{GL_ACTIVE_UNIFORMS},
9470 @code{GL_ACTIVE_UNIFORM_MAX_LENGTH}.
9473 Returns the requested object parameter.
9477 @code{glGetProgram} returns in @var{params} the value of a parameter for
9478 a specific program object. The following parameters are defined:
9481 @item @code{GL_DELETE_STATUS}
9484 @var{params} returns @code{GL_TRUE} if @var{program} is currently
9485 flagged for deletion, and @code{GL_FALSE} otherwise.
9487 @item @code{GL_LINK_STATUS}
9490 @var{params} returns @code{GL_TRUE} if the last link operation on
9491 @var{program} was successful, and @code{GL_FALSE} otherwise.
9493 @item @code{GL_VALIDATE_STATUS}
9496 @var{params} returns @code{GL_TRUE} or if the last validation operation
9497 on @var{program} was successful, and @code{GL_FALSE} otherwise.
9499 @item @code{GL_INFO_LOG_LENGTH}
9502 @var{params} returns the number of characters in the information log for
9503 @var{program} including the null termination character (i.e., the size
9504 of the character buffer required to store the information log). If
9505 @var{program} has no information log, a value of 0 is returned.
9507 @item @code{GL_ATTACHED_SHADERS}
9510 @var{params} returns the number of shader objects attached to
9513 @item @code{GL_ACTIVE_ATTRIBUTES}
9516 @var{params} returns the number of active attribute variables for
9519 @item @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH}
9522 @var{params} returns the length of the longest active attribute name for
9523 @var{program}, including the null termination character (i.e., the size
9524 of the character buffer required to store the longest attribute name).
9525 If no active attributes exist, 0 is returned.
9527 @item @code{GL_ACTIVE_UNIFORMS}
9530 @var{params} returns the number of active uniform variables for
9533 @item @code{GL_ACTIVE_UNIFORM_MAX_LENGTH}
9536 @var{params} returns the length of the longest active uniform variable
9537 name for @var{program}, including the null termination character (i.e.,
9538 the size of the character buffer required to store the longest uniform
9539 variable name). If no active uniform variables exist, 0 is returned.
9543 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
9544 generated by OpenGL.
9546 @code{GL_INVALID_OPERATION} is generated if @var{program} does not refer
9547 to a program object.
9549 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
9552 @code{GL_INVALID_OPERATION} is generated if @code{glGetProgram} is
9553 executed between the execution of @code{glBegin} and the corresponding
9554 execution of @code{glEnd}.
9558 @deftypefun void glGetQueryiv target pname params
9559 Return parameters of a query object target.
9563 Specifies a query object target. Must be @code{GL_SAMPLES_PASSED}.
9566 Specifies the symbolic name of a query object target parameter. Accepted
9567 values are @code{GL_CURRENT_QUERY} or @code{GL_QUERY_COUNTER_BITS}.
9570 Returns the requested data.
9574 @code{glGetQueryiv} returns in @var{params} a selected parameter of the
9575 query object target specified by @var{target}.
9577 @var{pname} names a specific query object target parameter. When
9578 @var{target} is @code{GL_SAMPLES_PASSED}, @var{pname} can be as follows:
9581 @item @code{GL_CURRENT_QUERY}
9582 @var{params} returns the name of the currently active occlusion query
9583 object. If no occlusion query is active, 0 is returned. The initial
9586 @item @code{GL_QUERY_COUNTER_BITS}
9587 @var{params} returns the number of bits in the query counter used to
9588 accumulate passing samples. If the number of bits returned is 0, the
9589 implementation does not support a query counter, and the results
9590 obtained from @code{glGetQueryObject} are useless.
9594 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
9595 not an accepted value.
9597 @code{GL_INVALID_OPERATION} is generated if @code{glGetQueryiv} is
9598 executed between the execution of @code{glBegin} and the corresponding
9599 execution of @code{glEnd}.
9603 @deftypefun void glGetQueryObjectiv id pname params
9604 @deftypefunx void glGetQueryObjectuiv id pname params
9605 Return parameters of a query object.
9609 Specifies the name of a query object.
9612 Specifies the symbolic name of a query object parameter. Accepted
9613 values are @code{GL_QUERY_RESULT} or @code{GL_QUERY_RESULT_AVAILABLE}.
9616 Returns the requested data.
9620 @code{glGetQueryObject} returns in @var{params} a selected parameter of
9621 the query object specified by @var{id}.
9623 @var{pname} names a specific query object parameter. @var{pname} can be
9627 @item @code{GL_QUERY_RESULT}
9628 @var{params} returns the value of the query object's passed samples
9629 counter. The initial value is 0.
9631 @item @code{GL_QUERY_RESULT_AVAILABLE}
9632 @var{params} returns whether the passed samples counter is immediately
9633 available. If a delay would occur waiting for the query result,
9634 @code{GL_FALSE} is returned. Otherwise, @code{GL_TRUE} is returned,
9635 which also indicates that the results of all previous queries are
9640 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
9643 @code{GL_INVALID_OPERATION} is generated if @var{id} is not the name of
9646 @code{GL_INVALID_OPERATION} is generated if @var{id} is the name of a
9647 currently active query object.
9649 @code{GL_INVALID_OPERATION} is generated if @code{glGetQueryObject} is
9650 executed between the execution of @code{glBegin} and the corresponding
9651 execution of @code{glEnd}.
9655 @deftypefun void glGetSeparableFilter target format type row column span
9656 Get separable convolution filter kernel images.
9660 The separable filter to be retrieved. Must be @code{GL_SEPARABLE_2D}.
9663 Format of the output images. Must be one of @code{GL_RED},
9664 @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB},
9665 @code{GL_BGR}@code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, or
9666 @code{GL_LUMINANCE_ALPHA}.
9669 Data type of components in the output images. Symbolic constants
9670 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
9671 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
9672 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
9673 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
9674 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
9675 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
9676 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
9677 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
9678 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
9681 Pointer to storage for the row filter image.
9684 Pointer to storage for the column filter image.
9687 Pointer to storage for the span filter image (currently unused).
9691 @code{glGetSeparableFilter} returns the two one-dimensional filter
9692 kernel images for the current separable 2D convolution filter. The row
9693 image is placed in @var{row} and the column image is placed in
9694 @var{column} according to the specifications in @var{format} and
9695 @var{type}. (In the current implementation, @var{span} is not affected
9696 in any way.) No pixel transfer operations are performed on the images,
9697 but the relevant pixel storage modes are applied.
9699 If a non-zero named buffer object is bound to the
9700 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
9701 separable convolution filter is requested, @var{row}, @var{column}, and
9702 @var{span} are treated as a byte offset into the buffer object's data
9705 Color components that are present in @var{format} but not included in
9706 the internal format of the filters are returned as zero. The
9707 assignments of internal color components to the components of
9708 @var{format} are as follows:
9713 @item @strong{Internal Component}
9714 @strong{Resulting Component}
9744 @code{GL_INVALID_ENUM} is generated if @var{target} is not
9745 @code{GL_SEPARABLE_2D}.
9747 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
9750 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
9753 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
9754 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
9755 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
9756 and @var{format} is not @code{GL_RGB}.
9758 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
9759 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
9760 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
9761 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
9762 @code{GL_UNSIGNED_INT_10_10_10_2}, or
9763 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
9764 @code{GL_RGBA} nor @code{GL_BGRA}.
9766 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9767 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
9768 object's data store is currently mapped.
9770 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9771 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
9772 would be packed to the buffer object such that the memory writes
9773 required would exceed the data store size.
9775 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
9776 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{row} or
9777 @var{column} is not evenly divisible into the number of bytes needed to
9778 store in memory a datum indicated by @var{type}.
9780 @code{GL_INVALID_OPERATION} is generated if @code{glGetSeparableFilter}
9781 is executed between the execution of @code{glBegin} and the
9782 corresponding execution of @code{glEnd}.
9786 @deftypefun void glGetShaderInfoLog shader maxLength length infoLog
9787 Returns the information log for a shader object.
9791 Specifies the shader object whose information log is to be queried.
9793 @item @var{maxLength}
9794 Specifies the size of the character buffer for storing the returned
9798 Returns the length of the string returned in @var{infoLog} (excluding
9799 the null terminator).
9802 Specifies an array of characters that is used to return the information
9807 @code{glGetShaderInfoLog} returns the information log for the specified
9808 shader object. The information log for a shader object is modified when
9809 the shader is compiled. The string that is returned will be null
9812 @code{glGetShaderInfoLog} returns in @var{infoLog} as much of the
9813 information log as it can, up to a maximum of @var{maxLength}
9814 characters. The number of characters actually returned, excluding the
9815 null termination character, is specified by @var{length}. If the length
9816 of the returned string is not required, a value of @code{NULL} can be
9817 passed in the @var{length} argument. The size of the buffer required to
9818 store the returned information log can be obtained by calling
9819 @code{glGetShader} with the value @code{GL_INFO_LOG_LENGTH}.
9821 The information log for a shader object is a string that may contain
9822 diagnostic messages, warning messages, and other information about the
9823 last compile operation. When a shader object is created, its
9824 information log will be a string of length 0.
9826 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
9827 generated by OpenGL.
9829 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
9832 @code{GL_INVALID_VALUE} is generated if @var{maxLength} is less than 0.
9834 @code{GL_INVALID_OPERATION} is generated if @code{glGetShaderInfoLog} is
9835 executed between the execution of @code{glBegin} and the corresponding
9836 execution of @code{glEnd}.
9840 @deftypefun void glGetShaderSource shader bufSize length source
9841 Returns the source code string from a shader object.
9845 Specifies the shader object to be queried.
9848 Specifies the size of the character buffer for storing the returned
9852 Returns the length of the string returned in @var{source} (excluding the
9856 Specifies an array of characters that is used to return the source code
9861 @code{glGetShaderSource} returns the concatenation of the source code
9862 strings from the shader object specified by @var{shader}. The source
9863 code strings for a shader object are the result of a previous call to
9864 @code{glShaderSource}. The string returned by the function will be null
9867 @code{glGetShaderSource} returns in @var{source} as much of the source
9868 code string as it can, up to a maximum of @var{bufSize} characters. The
9869 number of characters actually returned, excluding the null termination
9870 character, is specified by @var{length}. If the length of the returned
9871 string is not required, a value of @code{NULL} can be passed in the
9872 @var{length} argument. The size of the buffer required to store the
9873 returned source code string can be obtained by calling
9874 @code{glGetShader} with the value @code{GL_SHADER_SOURCE_LENGTH}.
9876 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
9877 generated by OpenGL.
9879 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
9882 @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0.
9884 @code{GL_INVALID_OPERATION} is generated if @code{glGetShaderSource} is
9885 executed between the execution of @code{glBegin} and the corresponding
9886 execution of @code{glEnd}.
9890 @deftypefun void glGetShaderiv shader pname params
9891 Returns a parameter from a shader object.
9895 Specifies the shader object to be queried.
9898 Specifies the object parameter. Accepted symbolic names are
9899 @code{GL_SHADER_TYPE}, @code{GL_DELETE_STATUS},
9900 @code{GL_COMPILE_STATUS}, @code{GL_INFO_LOG_LENGTH},
9901 @code{GL_SHADER_SOURCE_LENGTH}.
9904 Returns the requested object parameter.
9908 @code{glGetShader} returns in @var{params} the value of a parameter for
9909 a specific shader object. The following parameters are defined:
9912 @item @code{GL_SHADER_TYPE}
9913 @var{params} returns @code{GL_VERTEX_SHADER} if @var{shader} is a vertex
9914 shader object, and @code{GL_FRAGMENT_SHADER} if @var{shader} is a
9915 fragment shader object.
9917 @item @code{GL_DELETE_STATUS}
9918 @var{params} returns @code{GL_TRUE} if @var{shader} is currently flagged
9919 for deletion, and @code{GL_FALSE} otherwise.
9921 @item @code{GL_COMPILE_STATUS}
9922 @var{params} returns @code{GL_TRUE} if the last compile operation on
9923 @var{shader} was successful, and @code{GL_FALSE} otherwise.
9925 @item @code{GL_INFO_LOG_LENGTH}
9926 @var{params} returns the number of characters in the information log for
9927 @var{shader} including the null termination character (i.e., the size of
9928 the character buffer required to store the information log). If
9929 @var{shader} has no information log, a value of 0 is returned.
9931 @item @code{GL_SHADER_SOURCE_LENGTH}
9932 @var{params} returns the length of the concatenation of the source
9933 strings that make up the shader source for the @var{shader}, including
9934 the null termination character. (i.e., the size of the character buffer
9935 required to store the shader source). If no source code exists, 0 is
9940 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
9941 generated by OpenGL.
9943 @code{GL_INVALID_OPERATION} is generated if @var{shader} does not refer
9946 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
9949 @code{GL_INVALID_OPERATION} is generated if @code{glGetShader} is
9950 executed between the execution of @code{glBegin} and the corresponding
9951 execution of @code{glEnd}.
9955 @deftypefun const-GLubyte* glGetString name
9956 Return a string describing the current GL connection.
9960 Specifies a symbolic constant, one of @code{GL_VENDOR},
9961 @code{GL_RENDERER}, @code{GL_VERSION},
9962 @code{GL_SHADING_LANGUAGE_VERSION}, or @code{GL_EXTENSIONS}.
9966 @code{glGetString} returns a pointer to a static string describing some
9967 aspect of the current GL connection. @var{name} can be one of the
9971 @item @code{GL_VENDOR}
9974 Returns the company responsible for this GL implementation. This name
9975 does not change from release to release.
9977 @item @code{GL_RENDERER}
9980 Returns the name of the renderer. This name is typically specific to a
9981 particular configuration of a hardware platform. It does not change
9982 from release to release.
9984 @item @code{GL_VERSION}
9987 Returns a version or release number.
9989 @item @code{GL_SHADING_LANGUAGE_VERSION}
9992 Returns a version or release number for the shading language.
9994 @item @code{GL_EXTENSIONS}
9997 Returns a space-separated list of supported extensions to GL.
10001 Because the GL does not include queries for the performance
10002 characteristics of an implementation, some applications are written to
10003 recognize known platforms and modify their GL usage based on known
10004 performance characteristics of these platforms. Strings
10005 @code{GL_VENDOR} and @code{GL_RENDERER} together uniquely specify a
10006 platform. They do not change from release to release and should be used
10007 by platform-recognition algorithms.
10009 Some applications want to make use of features that are not part of the
10010 standard GL. These features may be implemented as extensions to the
10011 standard GL. The @code{GL_EXTENSIONS} string is a space-separated list
10012 of supported GL extensions. (Extension names never contain a space
10015 The @code{GL_VERSION} and @code{GL_SHADING_LANGUAGE_VERSION} strings
10016 begin with a version number. The version number uses one of these
10019 @var{major_number.minor_number}@var{major_number.minor_number.release_number}
10021 Vendor-specific information may follow the version number. Its format
10022 depends on the implementation, but a space always separates the version
10023 number and the vendor-specific information.
10025 All strings are null-terminated.
10027 @code{GL_INVALID_ENUM} is generated if @var{name} is not an accepted
10030 @code{GL_INVALID_OPERATION} is generated if @code{glGetString} is
10031 executed between the execution of @code{glBegin} and the corresponding
10032 execution of @code{glEnd}.
10036 @deftypefun void glGetTexEnvfv target pname params
10037 @deftypefunx void glGetTexEnviv target pname params
10038 Return texture environment parameters.
10042 Specifies a texture environment. May be @code{GL_TEXTURE_ENV},
10043 @code{GL_TEXTURE_FILTER_CONTROL}, or @code{GL_POINT_SPRITE}.
10046 Specifies the symbolic name of a texture environment parameter. Accepted
10047 values are @code{GL_TEXTURE_ENV_MODE}, @code{GL_TEXTURE_ENV_COLOR},
10048 @code{GL_TEXTURE_LOD_BIAS}, @code{GL_COMBINE_RGB},
10049 @code{GL_COMBINE_ALPHA}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB},
10050 @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA},
10051 @code{GL_SRC2_ALPHA}, @code{GL_OPERAND0_RGB}, @code{GL_OPERAND1_RGB},
10052 @code{GL_OPERAND2_RGB}, @code{GL_OPERAND0_ALPHA},
10053 @code{GL_OPERAND1_ALPHA}, @code{GL_OPERAND2_ALPHA}, @code{GL_RGB_SCALE},
10054 @code{GL_ALPHA_SCALE}, or @code{GL_COORD_REPLACE}.
10057 Returns the requested data.
10061 @code{glGetTexEnv} returns in @var{params} selected values of a texture
10062 environment that was specified with @code{glTexEnv}. @var{target}
10063 specifies a texture environment.
10065 When @var{target} is @code{GL_TEXTURE_FILTER_CONTROL}, @var{pname} must
10066 be @code{GL_TEXTURE_LOD_BIAS}. When @var{target} is
10067 @code{GL_POINT_SPRITE}, @var{pname} must be @code{GL_COORD_REPLACE}.
10068 When @var{target} is @code{GL_TEXTURE_ENV}, @var{pname} can be
10069 @code{GL_TEXTURE_ENV_MODE}, @code{GL_TEXTURE_ENV_COLOR},
10070 @code{GL_COMBINE_RGB}, @code{GL_COMBINE_ALPHA}, @code{GL_RGB_SCALE},
10071 @code{GL_ALPHA_SCALE}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB},
10072 @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, or
10073 @code{GL_SRC2_ALPHA}.
10075 @var{pname} names a specific texture environment parameter, as follows:
10078 @item @code{GL_TEXTURE_ENV_MODE}
10079 @var{params} returns the single-valued texture environment mode, a
10080 symbolic constant. The initial value is @code{GL_MODULATE}.
10082 @item @code{GL_TEXTURE_ENV_COLOR}
10083 @var{params} returns four integer or floating-point values that are the
10084 texture environment color. Integer values, when requested, are linearly
10085 mapped from the internal floating-point representation such that 1.0
10086 maps to the most positive representable integer, and @r{-1.0} maps to
10087 the most negative representable integer. The initial value is (0, 0, 0,
10090 @item @code{GL_TEXTURE_LOD_BIAS}
10091 @var{params} returns a single floating-point value that is the texture
10092 level-of-detail bias. The initial value is 0.
10094 @item @code{GL_COMBINE_RGB}
10095 @var{params} returns a single symbolic constant value representing the
10096 current RGB combine mode. The initial value is @code{GL_MODULATE}.
10098 @item @code{GL_COMBINE_ALPHA}
10099 @var{params} returns a single symbolic constant value representing the
10100 current alpha combine mode. The initial value is @code{GL_MODULATE}.
10102 @item @code{GL_SRC0_RGB}
10103 @var{params} returns a single symbolic constant value representing the
10104 texture combiner zero's RGB source. The initial value is
10107 @item @code{GL_SRC1_RGB}
10108 @var{params} returns a single symbolic constant value representing the
10109 texture combiner one's RGB source. The initial value is
10110 @code{GL_PREVIOUS}.
10112 @item @code{GL_SRC2_RGB}
10113 @var{params} returns a single symbolic constant value representing the
10114 texture combiner two's RGB source. The initial value is
10115 @code{GL_CONSTANT}.
10117 @item @code{GL_SRC0_ALPHA}
10118 @var{params} returns a single symbolic constant value representing the
10119 texture combiner zero's alpha source. The initial value is
10122 @item @code{GL_SRC1_ALPHA}
10123 @var{params} returns a single symbolic constant value representing the
10124 texture combiner one's alpha source. The initial value is
10125 @code{GL_PREVIOUS}.
10127 @item @code{GL_SRC2_ALPHA}
10128 @var{params} returns a single symbolic constant value representing the
10129 texture combiner two's alpha source. The initial value is
10130 @code{GL_CONSTANT}.
10132 @item @code{GL_OPERAND0_RGB}
10133 @var{params} returns a single symbolic constant value representing the
10134 texture combiner zero's RGB operand. The initial value is
10135 @code{GL_SRC_COLOR}.
10137 @item @code{GL_OPERAND1_RGB}
10138 @var{params} returns a single symbolic constant value representing the
10139 texture combiner one's RGB operand. The initial value is
10140 @code{GL_SRC_COLOR}.
10142 @item @code{GL_OPERAND2_RGB}
10143 @var{params} returns a single symbolic constant value representing the
10144 texture combiner two's RGB operand. The initial value is
10145 @code{GL_SRC_ALPHA}.
10147 @item @code{GL_OPERAND0_ALPHA}
10148 @var{params} returns a single symbolic constant value representing the
10149 texture combiner zero's alpha operand. The initial value is
10150 @code{GL_SRC_ALPHA}.
10152 @item @code{GL_OPERAND1_ALPHA}
10153 @var{params} returns a single symbolic constant value representing the
10154 texture combiner one's alpha operand. The initial value is
10155 @code{GL_SRC_ALPHA}.
10157 @item @code{GL_OPERAND2_ALPHA}
10158 @var{params} returns a single symbolic constant value representing the
10159 texture combiner two's alpha operand. The initial value is
10160 @code{GL_SRC_ALPHA}.
10162 @item @code{GL_RGB_SCALE}
10163 @var{params} returns a single floating-point value representing the
10164 current RGB texture combiner scaling factor. The initial value is 1.0.
10166 @item @code{GL_ALPHA_SCALE}
10167 @var{params} returns a single floating-point value representing the
10168 current alpha texture combiner scaling factor. The initial value is
10171 @item @code{GL_COORD_REPLACE}
10172 @var{params} returns a single boolean value representing the current
10173 point sprite texture coordinate replacement enable state. The initial
10174 value is @code{GL_FALSE}.
10178 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
10179 not an accepted value.
10181 @code{GL_INVALID_OPERATION} is generated if @code{glGetTexEnv} is
10182 executed between the execution of @code{glBegin} and the corresponding
10183 execution of @code{glEnd}.
10187 @deftypefun void glGetTexGendv coord pname params
10188 @deftypefunx void glGetTexGenfv coord pname params
10189 @deftypefunx void glGetTexGeniv coord pname params
10190 Return texture coordinate generation parameters.
10194 Specifies a texture coordinate. Must be @code{GL_S}, @code{GL_T},
10195 @code{GL_R}, or @code{GL_Q}.
10198 Specifies the symbolic name of the value(s) to be returned. Must be
10199 either @code{GL_TEXTURE_GEN_MODE} or the name of one of the texture
10200 generation plane equations: @code{GL_OBJECT_PLANE} or
10201 @code{GL_EYE_PLANE}.
10204 Returns the requested data.
10208 @code{glGetTexGen} returns in @var{params} selected parameters of a
10209 texture coordinate generation function that was specified using
10210 @code{glTexGen}. @var{coord} names one of the (@var{s}, @var{t},
10211 @var{r}, @var{q}) texture coordinates, using the symbolic constant
10212 @code{GL_S}, @code{GL_T}, @code{GL_R}, or @code{GL_Q}.
10214 @var{pname} specifies one of three symbolic names:
10217 @item @code{GL_TEXTURE_GEN_MODE}
10218 @var{params} returns the single-valued texture generation function, a
10219 symbolic constant. The initial value is @code{GL_EYE_LINEAR}.
10221 @item @code{GL_OBJECT_PLANE}
10222 @var{params} returns the four plane equation coefficients that specify
10223 object linear-coordinate generation. Integer values, when requested,
10224 are mapped directly from the internal floating-point representation.
10226 @item @code{GL_EYE_PLANE}
10227 @var{params} returns the four plane equation coefficients that specify
10228 eye linear-coordinate generation. Integer values, when requested, are
10229 mapped directly from the internal floating-point representation. The
10230 returned values are those maintained in eye coordinates. They are not
10231 equal to the values specified using @code{glTexGen}, unless the
10232 modelview matrix was identity when @code{glTexGen} was called.
10236 @code{GL_INVALID_ENUM} is generated if @var{coord} or @var{pname} is not
10239 @code{GL_INVALID_OPERATION} is generated if @code{glGetTexGen} is
10240 executed between the execution of @code{glBegin} and the corresponding
10241 execution of @code{glEnd}.
10245 @deftypefun void glGetTexImage target level format type img
10246 Return a texture image.
10250 Specifies which texture is to be obtained. @code{GL_TEXTURE_1D},
10251 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D},
10252 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
10253 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
10254 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
10255 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
10256 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, and
10257 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z} are accepted.
10260 Specifies the level-of-detail number of the desired image. Level 0 is
10261 the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap
10265 Specifies a pixel format for the returned data. The supported formats
10266 are @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
10267 @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA},
10268 @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA}.
10271 Specifies a pixel type for the returned data. The supported types are
10272 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT},
10273 @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT},
10274 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
10275 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
10276 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
10277 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
10278 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
10279 @code{GL_UNSIGNED_INT_10_10_10_2}, and
10280 @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
10283 Returns the texture image. Should be a pointer to an array of the type
10284 specified by @var{type}.
10288 @code{glGetTexImage} returns a texture image into @var{img}.
10289 @var{target} specifies whether the desired texture image is one
10290 specified by @code{glTexImage1D} (@code{GL_TEXTURE_1D}),
10291 @code{glTexImage2D} (@code{GL_TEXTURE_2D} or any of
10292 @code{GL_TEXTURE_CUBE_MAP_*}), or @code{glTexImage3D}
10293 (@code{GL_TEXTURE_3D}). @var{level} specifies the level-of-detail
10294 number of the desired image. @var{format} and @var{type} specify the
10295 format and type of the desired image array. See the reference pages
10296 @code{glTexImage1D} and @code{glDrawPixels} for a description of the
10297 acceptable values for the @var{format} and @var{type} parameters,
10300 If a non-zero named buffer object is bound to the
10301 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
10302 texture image is requested, @var{img} is treated as a byte offset into
10303 the buffer object's data store.
10305 To understand the operation of @code{glGetTexImage}, consider the
10306 selected internal four-component texture image to be an RGBA color
10307 buffer the size of the image. The semantics of @code{glGetTexImage} are
10308 then identical to those of @code{glReadPixels}, with the exception that
10309 no pixel transfer operations are performed, when called with the same
10310 @var{format} and @var{type}, with @var{x} and @var{y} set to 0,
10311 @var{width} set to the width of the texture image (including border if
10312 one was specified), and @var{height} set to 1 for 1D images, or to the
10313 height of the texture image (including border if one was specified) for
10314 2D images. Because the internal texture image is an RGBA image, pixel
10315 formats @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, and
10316 @code{GL_DEPTH_COMPONENT} are not accepted, and pixel type
10317 @code{GL_BITMAP} is not accepted.
10319 If the selected texture image does not contain four components, the
10320 following mappings are applied. Single-component textures are treated
10321 as RGBA buffers with red set to the single-component value, green set to
10322 0, blue set to 0, and alpha set to 1. Two-component textures are
10323 treated as RGBA buffers with red set to the value of component zero,
10324 alpha set to the value of component one, and green and blue set to 0.
10325 Finally, three-component textures are treated as RGBA buffers with red
10326 set to component zero, green set to component one, blue set to component
10327 two, and alpha set to 1.
10329 To determine the required size of @var{img}, use
10330 @code{glGetTexLevelParameter} to determine the dimensions of the
10331 internal texture image, then scale the required number of pixels by the
10332 storage required for each pixel, based on @var{format} and @var{type}.
10333 Be sure to take the pixel storage parameters into account, especially
10334 @code{GL_PACK_ALIGNMENT}.
10336 @code{GL_INVALID_ENUM} is generated if @var{target}, @var{format}, or
10337 @var{type} is not an accepted value.
10339 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
10341 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
10342 @r{@var{log}_2(@var{max},)}, where @r{@var{max}} is the returned value
10343 of @code{GL_MAX_TEXTURE_SIZE}.
10345 @code{GL_INVALID_OPERATION} is returned if @var{type} is one of
10346 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
10347 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
10348 and @var{format} is not @code{GL_RGB}.
10350 @code{GL_INVALID_OPERATION} is returned if @var{type} is one of
10351 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
10352 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
10353 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
10354 @code{GL_UNSIGNED_INT_10_10_10_2}, or
10355 @code{GL_UNSIGNED_INT_2_10_10_10_REV}, and @var{format} is neither
10356 @code{GL_RGBA} or @code{GL_BGRA}.
10358 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
10359 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
10360 object's data store is currently mapped.
10362 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
10363 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
10364 would be packed to the buffer object such that the memory writes
10365 required would exceed the data store size.
10367 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
10368 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{img} is
10369 not evenly divisible into the number of bytes needed to store in memory
10370 a datum indicated by @var{type}.
10372 @code{GL_INVALID_OPERATION} is generated if @code{glGetTexImage} is
10373 executed between the execution of @code{glBegin} and the corresponding
10374 execution of @code{glEnd}.
10378 @deftypefun void glGetTexLevelParameterfv target level pname params
10379 @deftypefunx void glGetTexLevelParameteriv target level pname params
10380 Return texture parameter values for a specific level of detail.
10384 Specifies the symbolic name of the target texture, either
10385 @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D},
10386 @code{GL_PROXY_TEXTURE_1D}, @code{GL_PROXY_TEXTURE_2D},
10387 @code{GL_PROXY_TEXTURE_3D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
10388 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
10389 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
10390 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
10391 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z},
10392 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or
10393 @code{GL_PROXY_TEXTURE_CUBE_MAP}.
10396 Specifies the level-of-detail number of the desired image. Level 0 is
10397 the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap
10401 Specifies the symbolic name of a texture parameter.
10402 @code{GL_TEXTURE_WIDTH}, @code{GL_TEXTURE_HEIGHT},
10403 @code{GL_TEXTURE_DEPTH}, @code{GL_TEXTURE_INTERNAL_FORMAT},
10404 @code{GL_TEXTURE_BORDER}, @code{GL_TEXTURE_RED_SIZE},
10405 @code{GL_TEXTURE_GREEN_SIZE}, @code{GL_TEXTURE_BLUE_SIZE},
10406 @code{GL_TEXTURE_ALPHA_SIZE}, @code{GL_TEXTURE_LUMINANCE_SIZE},
10407 @code{GL_TEXTURE_INTENSITY_SIZE}, @code{GL_TEXTURE_DEPTH_SIZE},
10408 @code{GL_TEXTURE_COMPRESSED}, and
10409 @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} are accepted.
10412 Returns the requested data.
10416 @code{glGetTexLevelParameter} returns in @var{params} texture parameter
10417 values for a specific level-of-detail value, specified as @var{level}.
10418 @var{target} defines the target texture, either @code{GL_TEXTURE_1D},
10419 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, @code{GL_PROXY_TEXTURE_1D},
10420 @code{GL_PROXY_TEXTURE_2D}, @code{GL_PROXY_TEXTURE_3D},
10421 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
10422 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
10423 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
10424 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
10425 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z},
10426 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or
10427 @code{GL_PROXY_TEXTURE_CUBE_MAP}.
10429 @code{GL_MAX_TEXTURE_SIZE}, and @code{GL_MAX_3D_TEXTURE_SIZE} are not
10430 really descriptive enough. It has to report the largest square texture
10431 image that can be accommodated with mipmaps and borders, but a long
10432 skinny texture, or a texture without mipmaps and borders, may easily fit
10433 in texture memory. The proxy targets allow the user to more accurately
10434 query whether the GL can accommodate a texture of a given configuration.
10435 If the texture cannot be accommodated, the texture state variables,
10436 which may be queried with @code{glGetTexLevelParameter}, are set to 0.
10437 If the texture can be accommodated, the texture state values will be set
10438 as they would be set for a non-proxy target.
10440 @var{pname} specifies the texture parameter whose value or values will
10443 The accepted parameter names are as follows:
10446 @item @code{GL_TEXTURE_WIDTH}
10449 @var{params} returns a single value, the width of the texture image.
10450 This value includes the border of the texture image. The initial value
10453 @item @code{GL_TEXTURE_HEIGHT}
10456 @var{params} returns a single value, the height of the texture image.
10457 This value includes the border of the texture image. The initial value
10460 @item @code{GL_TEXTURE_DEPTH}
10463 @var{params} returns a single value, the depth of the texture image.
10464 This value includes the border of the texture image. The initial value
10467 @item @code{GL_TEXTURE_INTERNAL_FORMAT}
10470 @var{params} returns a single value, the internal format of the texture
10473 @item @code{GL_TEXTURE_BORDER}
10476 @var{params} returns a single value, the width in pixels of the border
10477 of the texture image. The initial value is 0.
10479 @item @code{GL_TEXTURE_RED_SIZE},
10480 @item @code{GL_TEXTURE_GREEN_SIZE},
10481 @item @code{GL_TEXTURE_BLUE_SIZE},
10482 @item @code{GL_TEXTURE_ALPHA_SIZE},
10483 @item @code{GL_TEXTURE_LUMINANCE_SIZE},
10484 @item @code{GL_TEXTURE_INTENSITY_SIZE},
10485 @item @code{GL_TEXTURE_DEPTH_SIZE}
10488 The internal storage resolution of an individual component. The
10489 resolution chosen by the GL will be a close match for the resolution
10490 requested by the user with the component argument of
10491 @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D},
10492 @code{glCopyTexImage1D}, and @code{glCopyTexImage2D}. The initial value
10495 @item @code{GL_TEXTURE_COMPRESSED}
10498 @var{params} returns a single boolean value indicating if the texture
10499 image is stored in a compressed internal format. The initiali value is
10502 @item @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE}
10505 @var{params} returns a single integer value, the number of unsigned
10506 bytes of the compressed texture image that would be returned from
10507 @code{glGetCompressedTexImage}.
10511 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
10512 not an accepted value.
10514 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
10516 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
10517 @r{@var{log}_2}@var{max}, where @var{max} is the returned value of
10518 @code{GL_MAX_TEXTURE_SIZE}.
10520 @code{GL_INVALID_OPERATION} is generated if
10521 @code{glGetTexLevelParameter} is executed between the execution of
10522 @code{glBegin} and the corresponding execution of @code{glEnd}.
10524 @code{GL_INVALID_OPERATION} is generated if
10525 @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} is queried on texture images
10526 with an uncompressed internal format or on proxy targets.
10530 @deftypefun void glGetTexParameterfv target pname params
10531 @deftypefunx void glGetTexParameteriv target pname params
10532 Return texture parameter values.
10536 Specifies the symbolic name of the target texture. @code{GL_TEXTURE_1D},
10537 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, and
10538 @code{GL_TEXTURE_CUBE_MAP} are accepted.
10541 Specifies the symbolic name of a texture parameter.
10542 @code{GL_TEXTURE_MAG_FILTER}, @code{GL_TEXTURE_MIN_FILTER},
10543 @code{GL_TEXTURE_MIN_LOD}, @code{GL_TEXTURE_MAX_LOD},
10544 @code{GL_TEXTURE_BASE_LEVEL}, @code{GL_TEXTURE_MAX_LEVEL},
10545 @code{GL_TEXTURE_WRAP_S}, @code{GL_TEXTURE_WRAP_T},
10546 @code{GL_TEXTURE_WRAP_R}, @code{GL_TEXTURE_BORDER_COLOR},
10547 @code{GL_TEXTURE_PRIORITY}, @code{GL_TEXTURE_RESIDENT},
10548 @code{GL_TEXTURE_COMPARE_MODE}, @code{GL_TEXTURE_COMPARE_FUNC},
10549 @code{GL_DEPTH_TEXTURE_MODE}, and @code{GL_GENERATE_MIPMAP} are
10553 Returns the texture parameters.
10557 @code{glGetTexParameter} returns in @var{params} the value or values of
10558 the texture parameter specified as @var{pname}. @var{target} defines
10559 the target texture, either @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D},
10560 @code{GL_TEXTURE_3D}, or @code{GL_TEXTURE_CUBE_MAP}, to specify one-,
10561 two-, or three-dimensional or cube-mapped texturing. @var{pname}
10562 accepts the same symbols as @code{glTexParameter}, with the same
10566 @item @code{GL_TEXTURE_MAG_FILTER}
10567 Returns the single-valued texture magnification filter, a symbolic
10568 constant. The initial value is @code{GL_LINEAR}.
10570 @item @code{GL_TEXTURE_MIN_FILTER}
10571 Returns the single-valued texture minification filter, a symbolic
10572 constant. The initial value is @code{GL_NEAREST_MIPMAP_LINEAR}.
10574 @item @code{GL_TEXTURE_MIN_LOD}
10575 Returns the single-valued texture minimum level-of-detail value. The
10576 initial value is @r{-1000}.
10578 @item @code{GL_TEXTURE_MAX_LOD}
10579 Returns the single-valued texture maximum level-of-detail value. The
10580 initial value is 1000.
10582 @item @code{GL_TEXTURE_BASE_LEVEL}
10583 Returns the single-valued base texture mipmap level. The initial value
10586 @item @code{GL_TEXTURE_MAX_LEVEL}
10587 Returns the single-valued maximum texture mipmap array level. The
10588 initial value is 1000.
10590 @item @code{GL_TEXTURE_WRAP_S}
10591 Returns the single-valued wrapping function for texture coordinate
10592 @r{@var{s}}, a symbolic constant. The initial value is
10595 @item @code{GL_TEXTURE_WRAP_T}
10596 Returns the single-valued wrapping function for texture coordinate
10597 @r{@var{t}}, a symbolic constant. The initial value is
10600 @item @code{GL_TEXTURE_WRAP_R}
10601 Returns the single-valued wrapping function for texture coordinate
10602 @r{@var{r}}, a symbolic constant. The initial value is
10605 @item @code{GL_TEXTURE_BORDER_COLOR}
10606 Returns four integer or floating-point numbers that comprise the RGBA
10607 color of the texture border. Floating-point values are returned in the
10608 range @r{[0,1]}. Integer values are returned as a linear mapping of the
10609 internal floating-point representation such that 1.0 maps to the most
10610 positive representable integer and @r{-1.0} maps to the most negative
10611 representable integer. The initial value is (0, 0, 0, 0).
10613 @item @code{GL_TEXTURE_PRIORITY}
10614 Returns the residence priority of the target texture (or the named
10615 texture bound to it). The initial value is 1. See
10616 @code{glPrioritizeTextures}.
10618 @item @code{GL_TEXTURE_RESIDENT}
10619 Returns the residence status of the target texture. If the value
10620 returned in @var{params} is @code{GL_TRUE}, the texture is resident in
10621 texture memory. See @code{glAreTexturesResident}.
10623 @item @code{GL_TEXTURE_COMPARE_MODE}
10624 Returns a single-valued texture comparison mode, a symbolic constant.
10625 The initial value is @code{GL_NONE}. See @code{glTexParameter}.
10627 @item @code{GL_TEXTURE_COMPARE_FUNC}
10628 Returns a single-valued texture comparison function, a symbolic
10629 constant. The initial value is @code{GL_LEQUAL}. See
10630 @code{glTexParameter}.
10632 @item @code{GL_DEPTH_TEXTURE_MODE}
10633 Returns a single-valued texture format indicating how the depth values
10634 should be converted into color components. The initial value is
10635 @code{GL_LUMINANCE}. See @code{glTexParameter}.
10637 @item @code{GL_GENERATE_MIPMAP}
10638 Returns a single boolean value indicating if automatic mipmap level
10639 updates are enabled. See @code{glTexParameter}.
10643 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
10644 not an accepted value.
10646 @code{GL_INVALID_OPERATION} is generated if @code{glGetTexParameter} is
10647 executed between the execution of @code{glBegin} and the corresponding
10648 execution of @code{glEnd}.
10652 @deftypefun GLint glGetUniformLocation program name
10653 Returns the location of a uniform variable.
10656 @item @var{program}
10657 Specifies the program object to be queried.
10660 Points to a null terminated string containing the name of the uniform
10661 variable whose location is to be queried.
10665 @code{glGetUniformLocation } returns an integer that represents the
10666 location of a specific uniform variable within a program object.
10667 @var{name} must be a null terminated string that contains no white
10668 space. @var{name} must be an active uniform variable name in
10669 @var{program} that is not a structure, an array of structures, or a
10670 subcomponent of a vector or a matrix. This function returns -1 if
10671 @var{name} does not correspond to an active uniform variable in
10672 @var{program} or if @var{name} starts with the reserved prefix "gl_".
10674 Uniform variables that are structures or arrays of structures may be
10675 queried by calling @code{glGetUniformLocation} for each field within the
10676 structure. The array element operator "[]" and the structure field
10677 operator "." may be used in @var{name} in order to select elements
10678 within an array or fields within a structure. The result of using these
10679 operators is not allowed to be another structure, an array of
10680 structures, or a subcomponent of a vector or a matrix. Except if the
10681 last part of @var{name} indicates a uniform variable array, the location
10682 of the first element of an array can be retrieved by using the name of
10683 the array, or by using the name appended by "[0]".
10685 The actual locations assigned to uniform variables are not known until
10686 the program object is linked successfully. After linking has occurred,
10687 the command @code{glGetUniformLocation} can be used to obtain the
10688 location of a uniform variable. This location value can then be passed
10689 to @code{glUniform} to set the value of the uniform variable or to
10690 @code{glGetUniform} in order to query the current value of the uniform
10691 variable. After a program object has been linked successfully, the
10692 index values for uniform variables remain fixed until the next link
10693 command occurs. Uniform variable locations and values can only be
10694 queried after a link if the link was successful.
10696 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
10697 generated by OpenGL.
10699 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
10702 @code{GL_INVALID_OPERATION} is generated if @var{program} has not been
10703 successfully linked.
10705 @code{GL_INVALID_OPERATION} is generated if @code{glGetUniformLocation}
10706 is executed between the execution of @code{glBegin} and the
10707 corresponding execution of @code{glEnd}.
10711 @deftypefun void glGetUniformfv program location params
10712 @deftypefunx void glGetUniformiv program location params
10713 Returns the value of a uniform variable.
10716 @item @var{program}
10717 Specifies the program object to be queried.
10719 @item @var{location}
10720 Specifies the location of the uniform variable to be queried.
10723 Returns the value of the specified uniform variable.
10727 @code{glGetUniform} returns in @var{params} the value(s) of the
10728 specified uniform variable. The type of the uniform variable specified
10729 by @var{location} determines the number of values returned. If the
10730 uniform variable is defined in the shader as a boolean, int, or float, a
10731 single value will be returned. If it is defined as a vec2, ivec2, or
10732 bvec2, two values will be returned. If it is defined as a vec3, ivec3,
10733 or bvec3, three values will be returned, and so on. To query values
10734 stored in uniform variables declared as arrays, call @code{glGetUniform}
10735 for each element of the array. To query values stored in uniform
10736 variables declared as structures, call @code{glGetUniform} for each
10737 field in the structure. The values for uniform variables declared as a
10738 matrix will be returned in column major order.
10740 The locations assigned to uniform variables are not known until the
10741 program object is linked. After linking has occurred, the command
10742 @code{glGetUniformLocation} can be used to obtain the location of a
10743 uniform variable. This location value can then be passed to
10744 @code{glGetUniform} in order to query the current value of the uniform
10745 variable. After a program object has been linked successfully, the
10746 index values for uniform variables remain fixed until the next link
10747 command occurs. The uniform variable values can only be queried after a
10748 link if the link was successful.
10750 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
10751 generated by OpenGL.
10753 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
10756 @code{GL_INVALID_OPERATION} is generated if @var{program} has not been
10757 successfully linked.
10759 @code{GL_INVALID_OPERATION} is generated if @var{location} does not
10760 correspond to a valid uniform variable location for the specified
10763 @code{GL_INVALID_OPERATION} is generated if @code{glGetUniform} is
10764 executed between the execution of @code{glBegin} and the corresponding
10765 execution of @code{glEnd}.
10769 @deftypefun void glGetVertexAttribPointerv index pname pointer
10770 Return the address of the specified generic vertex attribute pointer.
10774 Specifies the generic vertex attribute parameter to be returned.
10777 Specifies the symbolic name of the generic vertex attribute parameter to
10778 be returned. Must be @code{GL_VERTEX_ATTRIB_ARRAY_POINTER}.
10780 @item @var{pointer}
10781 Returns the pointer value.
10785 @code{glGetVertexAttribPointerv} returns pointer information.
10786 @var{index} is the generic vertex attribute to be queried, @var{pname}
10787 is a symbolic constant indicating the pointer to be returned, and
10788 @var{params} is a pointer to a location in which to place the returned
10791 If a non-zero named buffer object was bound to the
10792 @code{GL_ARRAY_BUFFER} target (see @code{glBindBuffer}) when the desired
10793 pointer was previously specified, the @var{pointer} returned is a byte
10794 offset into the buffer object's data store.
10796 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
10797 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
10799 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
10804 @deftypefun void glGetVertexAttribdv index pname params
10805 @deftypefunx void glGetVertexAttribfv index pname params
10806 @deftypefunx void glGetVertexAttribiv index pname params
10807 Return a generic vertex attribute parameter.
10811 Specifies the generic vertex attribute parameter to be queried.
10814 Specifies the symbolic name of the vertex attribute parameter to be
10815 queried. Accepted values are
10816 @code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING},
10817 @code{GL_VERTEX_ATTRIB_ARRAY_ENABLED},
10818 @code{GL_VERTEX_ATTRIB_ARRAY_SIZE},
10819 @code{GL_VERTEX_ATTRIB_ARRAY_STRIDE},
10820 @code{GL_VERTEX_ATTRIB_ARRAY_TYPE},
10821 @code{GL_VERTEX_ATTRIB_ARRAY_NORMALIZED}, or
10822 @code{GL_CURRENT_VERTEX_ATTRIB}.
10825 Returns the requested data.
10829 @code{glGetVertexAttrib} returns in @var{params} the value of a generic
10830 vertex attribute parameter. The generic vertex attribute to be queried
10831 is specified by @var{index}, and the parameter to be queried is
10832 specified by @var{pname}.
10834 The accepted parameter names are as follows:
10837 @item @code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING}
10840 @var{params} returns a single value, the name of the buffer object
10841 currently bound to the binding point corresponding to generic vertex
10842 attribute array @var{index}. If no buffer object is bound, 0 is
10843 returned. The initial value is 0.
10845 @item @code{GL_VERTEX_ATTRIB_ARRAY_ENABLED}
10848 @var{params} returns a single value that is non-zero (true) if the
10849 vertex attribute array for @var{index} is enabled and 0 (false) if it is
10850 disabled. The initial value is @code{GL_FALSE}.
10852 @item @code{GL_VERTEX_ATTRIB_ARRAY_SIZE}
10855 @var{params} returns a single value, the size of the vertex attribute
10856 array for @var{index}. The size is the number of values for each
10857 element of the vertex attribute array, and it will be 1, 2, 3, or 4. The
10858 initial value is 4.
10860 @item @code{GL_VERTEX_ATTRIB_ARRAY_STRIDE}
10863 @var{params} returns a single value, the array stride for (number of
10864 bytes between successive elements in) the vertex attribute array for
10865 @var{index}. A value of 0 indicates that the array elements are stored
10866 sequentially in memory. The initial value is 0.
10868 @item @code{GL_VERTEX_ATTRIB_ARRAY_TYPE}
10871 @var{params} returns a single value, a symbolic constant indicating the
10872 array type for the vertex attribute array for @var{index}. Possible
10873 values are @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
10874 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
10875 @code{GL_FLOAT}, and @code{GL_DOUBLE}. The initial value is
10878 @item @code{GL_VERTEX_ATTRIB_ARRAY_NORMALIZED}
10881 @var{params} returns a single value that is non-zero (true) if
10882 fixed-point data types for the vertex attribute array indicated by
10883 @var{index} are normalized when they are converted to floating point,
10884 and 0 (false) otherwise. The initial value is @code{GL_FALSE}.
10886 @item @code{GL_CURRENT_VERTEX_ATTRIB}
10889 @var{params} returns four values that represent the current value for
10890 the generic vertex attribute specified by index. Generic vertex
10891 attribute 0 is unique in that it has no current state, so an error will
10892 be generated if @var{index} is 0. The initial value for all other
10893 generic vertex attributes is (0,0,0,1).
10897 All of the parameters except @code{GL_CURRENT_VERTEX_ATTRIB} represent
10900 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
10901 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
10903 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
10906 @code{GL_INVALID_OPERATION} is generated if @var{index} is 0 and
10907 @var{pname} is @code{GL_CURRENT_VERTEX_ATTRIB}.
10911 @deftypefun void glGetBooleanv pname params
10912 @deftypefunx void glGetDoublev pname params
10913 @deftypefunx void glGetFloatv pname params
10914 @deftypefunx void glGetIntegerv pname params
10915 Return the value or values of a selected parameter.
10919 Specifies the parameter value to be returned. The symbolic constants in
10920 the list below are accepted.
10923 Returns the value or values of the specified parameter.
10927 These four commands return values for simple state variables in GL.
10928 @var{pname} is a symbolic constant indicating the state variable to be
10929 returned, and @var{params} is a pointer to an array of the indicated
10930 type in which to place the returned data.
10932 Type conversion is performed if @var{params} has a different type than
10933 the state variable value being requested. If @code{glGetBooleanv} is
10934 called, a floating-point (or integer) value is converted to
10935 @code{GL_FALSE} if and only if it is 0.0 (or 0). Otherwise, it is
10936 converted to @code{GL_TRUE}. If @code{glGetIntegerv} is called, boolean
10937 values are returned as @code{GL_TRUE} or @code{GL_FALSE}, and most
10938 floating-point values are rounded to the nearest integer value.
10939 Floating-point colors and normals, however, are returned with a linear
10940 mapping that maps 1.0 to the most positive representable integer value
10941 and @r{-1.0} to the most negative representable integer value. If
10942 @code{glGetFloatv} or @code{glGetDoublev} is called, boolean values are
10943 returned as @code{GL_TRUE} or @code{GL_FALSE}, and integer values are
10944 converted to floating-point values.
10946 The following symbolic constants are accepted by @var{pname}:
10949 @item @code{GL_ACCUM_ALPHA_BITS}
10952 @var{params} returns one value, the number of alpha bitplanes in the
10953 accumulation buffer.
10955 @item @code{GL_ACCUM_BLUE_BITS}
10958 @var{params} returns one value, the number of blue bitplanes in the
10959 accumulation buffer.
10961 @item @code{GL_ACCUM_CLEAR_VALUE}
10964 @var{params} returns four values: the red, green, blue, and alpha values
10965 used to clear the accumulation buffer. Integer values, if requested,
10966 are linearly mapped from the internal floating-point representation such
10967 that 1.0 returns the most positive representable integer value, and
10968 @r{-1.0} returns the most negative representable integer value. The
10969 initial value is (0, 0, 0, 0). See @code{glClearAccum}.
10971 @item @code{GL_ACCUM_GREEN_BITS}
10974 @var{params} returns one value, the number of green bitplanes in the
10975 accumulation buffer.
10977 @item @code{GL_ACCUM_RED_BITS}
10980 @var{params} returns one value, the number of red bitplanes in the
10981 accumulation buffer.
10983 @item @code{GL_ACTIVE_TEXTURE}
10986 @var{params} returns a single value indicating the active multitexture
10987 unit. The initial value is @code{GL_TEXTURE0}. See
10988 @code{glActiveTexture}.
10990 @item @code{GL_ALIASED_POINT_SIZE_RANGE}
10993 @var{params} returns two values, the smallest and largest supported
10994 sizes for aliased points.
10996 @item @code{GL_ALIASED_LINE_WIDTH_RANGE}
10999 @var{params} returns two values, the smallest and largest supported
11000 widths for aliased lines.
11002 @item @code{GL_ALPHA_BIAS}
11005 @var{params} returns one value, the alpha bias factor used during pixel
11006 transfers. The initial value is 0. See @code{glPixelTransfer}.
11008 @item @code{GL_ALPHA_BITS}
11011 @var{params} returns one value, the number of alpha bitplanes in each
11014 @item @code{GL_ALPHA_SCALE}
11017 @var{params} returns one value, the alpha scale factor used during pixel
11018 transfers. The initial value is 1. See @code{glPixelTransfer}.
11020 @item @code{GL_ALPHA_TEST}
11023 @var{params} returns a single boolean value indicating whether alpha
11024 testing of fragments is enabled. The initial value is @code{GL_FALSE}.
11025 See @code{glAlphaFunc}.
11027 @item @code{GL_ALPHA_TEST_FUNC}@var{params} returns one value,
11030 the symbolic name of the alpha test function. The initial value is
11031 @code{GL_ALWAYS}. See @code{glAlphaFunc}.
11033 @item @code{GL_ALPHA_TEST_REF}
11036 @var{params} returns one value, the reference value for the alpha test.
11037 The initial value is 0. See @code{glAlphaFunc}. An integer value, if
11038 requested, is linearly mapped from the internal floating-point
11039 representation such that 1.0 returns the most positive representable
11040 integer value, and @r{-1.0} returns the most negative representable
11043 @item @code{GL_ARRAY_BUFFER_BINDING}
11046 @var{params} returns a single value, the name of the buffer object
11047 currently bound to the target @code{GL_ARRAY_BUFFER}. If no buffer
11048 object is bound to this target, 0 is returned. The initial value is 0.
11049 See @code{glBindBuffer}.
11051 @item @code{GL_ATTRIB_STACK_DEPTH}
11054 @var{params} returns one value, the depth of the attribute stack. If
11055 the stack is empty, 0 is returned. The initial value is 0. See
11056 @code{glPushAttrib}.
11058 @item @code{GL_AUTO_NORMAL}
11061 @var{params} returns a single boolean value indicating whether 2D map
11062 evaluation automatically generates surface normals. The initial value
11063 is @code{GL_FALSE}. See @code{glMap2}.
11065 @item @code{GL_AUX_BUFFERS}
11068 @var{params} returns one value, the number of auxiliary color buffers
11071 @item @code{GL_BLEND}
11074 @var{params} returns a single boolean value indicating whether blending
11075 is enabled. The initial value is @code{GL_FALSE}. See
11076 @code{glBlendFunc}.
11078 @item @code{GL_BLEND_COLOR}
11081 @var{params} returns four values, the red, green, blue, and alpha values
11082 which are the components of the blend color. See @code{glBlendColor}.
11084 @item @code{GL_BLEND_DST_ALPHA}
11087 @var{params} returns one value, the symbolic constant identifying the
11088 alpha destination blend function. The initial value is @code{GL_ZERO}.
11089 See @code{glBlendFunc} and @code{glBlendFuncSeparate}.
11091 @item @code{GL_BLEND_DST_RGB}
11094 @var{params} returns one value, the symbolic constant identifying the
11095 RGB destination blend function. The initial value is @code{GL_ZERO}.
11096 See @code{glBlendFunc} and @code{glBlendFuncSeparate}.
11098 @item @code{GL_BLEND_EQUATION_RGB}
11101 @var{params} returns one value, a symbolic constant indicating whether
11102 the RGB blend equation is @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT},
11103 @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN} or @code{GL_MAX}. See
11104 @code{glBlendEquationSeparate}.
11106 @item @code{GL_BLEND_EQUATION_ALPHA}
11109 @var{params} returns one value, a symbolic constant indicating whether
11110 the Alpha blend equation is @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT},
11111 @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN} or @code{GL_MAX}. See
11112 @code{glBlendEquationSeparate}.
11114 @item @code{GL_BLEND_SRC_ALPHA}
11117 @var{params} returns one value, the symbolic constant identifying the
11118 alpha source blend function. The initial value is @code{GL_ONE}. See
11119 @code{glBlendFunc} and @code{glBlendFuncSeparate}.
11121 @item @code{GL_BLEND_SRC_RGB}
11124 @var{params} returns one value, the symbolic constant identifying the
11125 RGB source blend function. The initial value is @code{GL_ONE}. See
11126 @code{glBlendFunc} and @code{glBlendFuncSeparate}.
11128 @item @code{GL_BLUE_BIAS}
11131 @var{params} returns one value, the blue bias factor used during pixel
11132 transfers. The initial value is 0. See @code{glPixelTransfer}.
11134 @item @code{GL_BLUE_BITS}
11137 @var{params} returns one value, the number of blue bitplanes in each
11140 @item @code{GL_BLUE_SCALE}
11143 @var{params} returns one value, the blue scale factor used during pixel
11144 transfers. The initial value is 1. See @code{glPixelTransfer}.
11146 @item @code{GL_CLIENT_ACTIVE_TEXTURE}
11149 @var{params} returns a single integer value indicating the current
11150 client active multitexture unit. The initial value is
11151 @code{GL_TEXTURE0}. See @code{glClientActiveTexture}.
11153 @item @code{GL_CLIENT_ATTRIB_STACK_DEPTH}
11156 @var{params} returns one value indicating the depth of the attribute
11157 stack. The initial value is 0. See @code{glPushClientAttrib}.
11159 @item @code{GL_CLIP_PLANE}@var{i}
11162 @var{params} returns a single boolean value indicating whether the
11163 specified clipping plane is enabled. The initial value is
11164 @code{GL_FALSE}. See @code{glClipPlane}.
11166 @item @code{GL_COLOR_ARRAY}
11169 @var{params} returns a single boolean value indicating whether the color
11170 array is enabled. The initial value is @code{GL_FALSE}. See
11171 @code{glColorPointer}.
11173 @item @code{GL_COLOR_ARRAY_BUFFER_BINDING}
11176 @var{params} returns a single value, the name of the buffer object
11177 associated with the color array. This buffer object would have been
11178 bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
11179 recent call to @code{glColorPointer}. If no buffer object was bound to
11180 this target, 0 is returned. The initial value is 0. See
11181 @code{glBindBuffer}.
11183 @item @code{GL_COLOR_ARRAY_SIZE}
11186 @var{params} returns one value, the number of components per color in
11187 the color array. The initial value is 4. See @code{glColorPointer}.
11189 @item @code{GL_COLOR_ARRAY_STRIDE}
11192 @var{params} returns one value, the byte offset between consecutive
11193 colors in the color array. The initial value is 0. See
11194 @code{glColorPointer}.
11196 @item @code{GL_COLOR_ARRAY_TYPE}
11199 @var{params} returns one value, the data type of each component in the
11200 color array. The initial value is @code{GL_FLOAT}. See
11201 @code{glColorPointer}.
11203 @item @code{GL_COLOR_CLEAR_VALUE}
11206 @var{params} returns four values: the red, green, blue, and alpha values
11207 used to clear the color buffers. Integer values, if requested, are
11208 linearly mapped from the internal floating-point representation such
11209 that 1.0 returns the most positive representable integer value, and
11210 @r{-1.0} returns the most negative representable integer value. The
11211 initial value is (0, 0, 0, 0). See @code{glClearColor}.
11213 @item @code{GL_COLOR_LOGIC_OP}
11216 @var{params} returns a single boolean value indicating whether a
11217 fragment's RGBA color values are merged into the framebuffer using a
11218 logical operation. The initial value is @code{GL_FALSE}. See
11221 @item @code{GL_COLOR_MATERIAL}
11224 @var{params} returns a single boolean value indicating whether one or
11225 more material parameters are tracking the current color. The initial
11226 value is @code{GL_FALSE}. See @code{glColorMaterial}.
11228 @item @code{GL_COLOR_MATERIAL_FACE}
11231 @var{params} returns one value, a symbolic constant indicating which
11232 materials have a parameter that is tracking the current color. The
11233 initial value is @code{GL_FRONT_AND_BACK}. See @code{glColorMaterial}.
11235 @item @code{GL_COLOR_MATERIAL_PARAMETER}
11238 @var{params} returns one value, a symbolic constant indicating which
11239 material parameters are tracking the current color. The initial value
11240 is @code{GL_AMBIENT_AND_DIFFUSE}. See @code{glColorMaterial}.
11242 @item @code{GL_COLOR_MATRIX}
11245 @var{params} returns sixteen values: the color matrix on the top of the
11246 color matrix stack. Initially this matrix is the identity matrix. See
11247 @code{glPushMatrix}.
11249 @item @code{GL_COLOR_MATRIX_STACK_DEPTH}
11252 @var{params} returns one value, the maximum supported depth of the
11253 projection matrix stack. The value must be at least 2. See
11254 @code{glPushMatrix}.
11256 @item @code{GL_COLOR_SUM}
11259 @var{params} returns a single boolean value indicating whether primary
11260 and secondary color sum is enabled. See @code{glSecondaryColor}.
11262 @item @code{GL_COLOR_TABLE}
11265 @var{params} returns a single boolean value indicating whether the color
11266 table lookup is enabled. See @code{glColorTable}.
11268 @item @code{GL_COLOR_WRITEMASK}
11271 @var{params} returns four boolean values: the red, green, blue, and
11272 alpha write enables for the color buffers. The initial value is
11273 (@code{GL_TRUE}, @code{GL_TRUE}, @code{GL_TRUE}, @code{GL_TRUE}). See
11274 @code{glColorMask}.
11276 @item @code{GL_COMPRESSED_TEXTURE_FORMATS}
11279 @var{params} returns a list of symbolic constants of length
11280 @code{GL_NUM_COMPRESSED_TEXTURE_FORMATS} indicating which compressed
11281 texture formats are available. See @code{glCompressedTexImage2D}.
11283 @item @code{GL_CONVOLUTION_1D}
11286 @var{params} returns a single boolean value indicating whether 1D
11287 convolution is enabled. The initial value is @code{GL_FALSE}. See
11288 @code{glConvolutionFilter1D}.
11290 @item @code{GL_CONVOLUTION_2D}
11293 @var{params} returns a single boolean value indicating whether 2D
11294 convolution is enabled. The initial value is @code{GL_FALSE}. See
11295 @code{glConvolutionFilter2D}.
11297 @item @code{GL_CULL_FACE}
11300 @var{params} returns a single boolean value indicating whether polygon
11301 culling is enabled. The initial value is @code{GL_FALSE}. See
11304 @item @code{GL_CULL_FACE_MODE}
11307 @var{params} returns one value, a symbolic constant indicating which
11308 polygon faces are to be culled. The initial value is @code{GL_BACK}.
11309 See @code{glCullFace}.
11311 @item @code{GL_CURRENT_COLOR}
11314 @var{params} returns four values: the red, green, blue, and alpha values
11315 of the current color. Integer values, if requested, are linearly mapped
11316 from the internal floating-point representation such that 1.0 returns
11317 the most positive representable integer value, and @r{-1.0} returns the
11318 most negative representable integer value. The initial value is (1, 1,
11319 1, 1). See @code{glColor}.
11321 @item @code{GL_CURRENT_FOG_COORD}
11324 @var{params} returns one value, the current fog coordinate. The initial
11325 value is 0. See @code{glFogCoord}.
11327 @item @code{GL_CURRENT_INDEX}
11330 @var{params} returns one value, the current color index. The initial
11331 value is 1. See @code{glIndex}.
11333 @item @code{GL_CURRENT_NORMAL}
11336 @var{params} returns three values: the @var{x}, @var{y}, and @var{z}
11337 values of the current normal. Integer values, if requested, are
11338 linearly mapped from the internal floating-point representation such
11339 that 1.0 returns the most positive representable integer value, and
11340 @r{-1.0} returns the most negative representable integer value. The
11341 initial value is (0, 0, 1). See @code{glNormal}.
11343 @item @code{GL_CURRENT_PROGRAM}
11346 @var{params} returns one value, the name of the program object that is
11347 currently active, or 0 if no program object is active. See
11348 @code{glUseProgram}.
11350 @item @code{GL_CURRENT_RASTER_COLOR}
11353 @var{params} returns four values: the red, green, blue, and alpha color
11354 values of the current raster position. Integer values, if requested,
11355 are linearly mapped from the internal floating-point representation such
11356 that 1.0 returns the most positive representable integer value, and
11357 @r{-1.0} returns the most negative representable integer value. The
11358 initial value is (1, 1, 1, 1). See @code{glRasterPos}.
11360 @item @code{GL_CURRENT_RASTER_DISTANCE}
11363 @var{params} returns one value, the distance from the eye to the current
11364 raster position. The initial value is 0. See @code{glRasterPos}.
11366 @item @code{GL_CURRENT_RASTER_INDEX}
11369 @var{params} returns one value, the color index of the current raster
11370 position. The initial value is 1. See @code{glRasterPos}.
11372 @item @code{GL_CURRENT_RASTER_POSITION}
11375 @var{params} returns four values: the @var{x}, @var{y}, @var{z}, and
11376 @var{w} components of the current raster position. @var{x}, @var{y},
11377 and @var{z} are in window coordinates, and @var{w} is in clip
11378 coordinates. The initial value is (0, 0, 0, 1). See
11379 @code{glRasterPos}.
11381 @item @code{GL_CURRENT_RASTER_POSITION_VALID}
11384 @var{params} returns a single boolean value indicating whether the
11385 current raster position is valid. The initial value is @code{GL_TRUE}.
11386 See @code{glRasterPos}.
11388 @item @code{GL_CURRENT_RASTER_SECONDARY_COLOR}
11391 @var{params} returns four values: the red, green, blue, and alpha
11392 secondary color values of the current raster position. Integer values,
11393 if requested, are linearly mapped from the internal floating-point
11394 representation such that 1.0 returns the most positive representable
11395 integer value, and @r{-1.0} returns the most negative representable
11396 integer value. The initial value is (1, 1, 1, 1). See
11397 @code{glRasterPos}.
11399 @item @code{GL_CURRENT_RASTER_TEXTURE_COORDS}
11402 @var{params} returns four values: the @var{s}, @var{t}, @var{r}, and
11403 @var{q} texture coordinates of the current raster position. The initial
11404 value is (0, 0, 0, 1). See @code{glRasterPos} and
11405 @code{glMultiTexCoord}.
11407 @item @code{GL_CURRENT_SECONDARY_COLOR}
11410 @var{params} returns four values: the red, green, blue, and alpha values
11411 of the current secondary color. Integer values, if requested, are
11412 linearly mapped from the internal floating-point representation such
11413 that 1.0 returns the most positive representable integer value, and
11414 @r{-1.0} returns the most negative representable integer value. The
11415 initial value is (0, 0, 0, 0). See @code{glSecondaryColor}.
11417 @item @code{GL_CURRENT_TEXTURE_COORDS}
11420 @var{params} returns four values: the @var{s}, @var{t}, @var{r}, and
11421 @var{q} current texture coordinates. The initial value is (0, 0, 0, 1).
11422 See @code{glMultiTexCoord}.
11424 @item @code{GL_DEPTH_BIAS}
11427 @var{params} returns one value, the depth bias factor used during pixel
11428 transfers. The initial value is 0. See @code{glPixelTransfer}.
11430 @item @code{GL_DEPTH_BITS}
11433 @var{params} returns one value, the number of bitplanes in the depth
11436 @item @code{GL_DEPTH_CLEAR_VALUE}
11439 @var{params} returns one value, the value that is used to clear the
11440 depth buffer. Integer values, if requested, are linearly mapped from
11441 the internal floating-point representation such that 1.0 returns the
11442 most positive representable integer value, and @r{-1.0} returns the most
11443 negative representable integer value. The initial value is 1. See
11444 @code{glClearDepth}.
11446 @item @code{GL_DEPTH_FUNC}
11449 @var{params} returns one value, the symbolic constant that indicates the
11450 depth comparison function. The initial value is @code{GL_LESS}. See
11451 @code{glDepthFunc}.
11453 @item @code{GL_DEPTH_RANGE}
11456 @var{params} returns two values: the near and far mapping limits for the
11457 depth buffer. Integer values, if requested, are linearly mapped from
11458 the internal floating-point representation such that 1.0 returns the
11459 most positive representable integer value, and @r{-1.0} returns the most
11460 negative representable integer value. The initial value is (0, 1). See
11461 @code{glDepthRange}.
11463 @item @code{GL_DEPTH_SCALE}
11466 @var{params} returns one value, the depth scale factor used during pixel
11467 transfers. The initial value is 1. See @code{glPixelTransfer}.
11469 @item @code{GL_DEPTH_TEST}
11472 @var{params} returns a single boolean value indicating whether depth
11473 testing of fragments is enabled. The initial value is @code{GL_FALSE}.
11474 See @code{glDepthFunc} and @code{glDepthRange}.
11476 @item @code{GL_DEPTH_WRITEMASK}
11479 @var{params} returns a single boolean value indicating if the depth
11480 buffer is enabled for writing. The initial value is @code{GL_TRUE}. See
11481 @code{glDepthMask}.
11483 @item @code{GL_DITHER}
11486 @var{params} returns a single boolean value indicating whether dithering
11487 of fragment colors and indices is enabled. The initial value is
11490 @item @code{GL_DOUBLEBUFFER}
11493 @var{params} returns a single boolean value indicating whether double
11494 buffering is supported.
11496 @item @code{GL_DRAW_BUFFER}
11499 @var{params} returns one value, a symbolic constant indicating which
11500 buffers are being drawn to. See @code{glDrawBuffer}. The initial value
11501 is @code{GL_BACK} if there are back buffers, otherwise it is
11504 @item @code{GL_DRAW_BUFFER}@var{i}
11507 @var{params} returns one value, a symbolic constant indicating which
11508 buffers are being drawn to by the corresponding output color. See
11509 @code{glDrawBuffers}. The initial value of @code{GL_DRAW_BUFFER0} is
11510 @code{GL_BACK} if there are back buffers, otherwise it is
11511 @code{GL_FRONT}. The initial values of draw buffers for all other
11512 output colors is @code{GL_NONE}.
11514 @item @code{GL_EDGE_FLAG}
11517 @var{params} returns a single boolean value indicating whether the
11518 current edge flag is @code{GL_TRUE} or @code{GL_FALSE}. The initial
11519 value is @code{GL_TRUE}. See @code{glEdgeFlag}.
11521 @item @code{GL_EDGE_FLAG_ARRAY}
11524 @var{params} returns a single boolean value indicating whether the edge
11525 flag array is enabled. The initial value is @code{GL_FALSE}. See
11526 @code{glEdgeFlagPointer}.
11528 @item @code{GL_EDGE_FLAG_ARRAY_BUFFER_BINDING}
11531 @var{params} returns a single value, the name of the buffer object
11532 associated with the edge flag array. This buffer object would have been
11533 bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
11534 recent call to @code{glEdgeFlagPointer}. If no buffer object was bound
11535 to this target, 0 is returned. The initial value is 0. See
11536 @code{glBindBuffer}.
11538 @item @code{GL_EDGE_FLAG_ARRAY_STRIDE}
11541 @var{params} returns one value, the byte offset between consecutive edge
11542 flags in the edge flag array. The initial value is 0. See
11543 @code{glEdgeFlagPointer}.
11545 @item @code{GL_ELEMENT_ARRAY_BUFFER_BINDING}
11548 @var{params} returns a single value, the name of the buffer object
11549 currently bound to the target @code{GL_ELEMENT_ARRAY_BUFFER}. If no
11550 buffer object is bound to this target, 0 is returned. The initial value
11551 is 0. See @code{glBindBuffer}.
11553 @item @code{GL_FEEDBACK_BUFFER_SIZE}
11556 @var{params} returns one value, the size of the feedback buffer. See
11557 @code{glFeedbackBuffer}.
11559 @item @code{GL_FEEDBACK_BUFFER_TYPE}
11562 @var{params} returns one value, the type of the feedback buffer. See
11563 @code{glFeedbackBuffer}.
11565 @item @code{GL_FOG}
11568 @var{params} returns a single boolean value indicating whether fogging
11569 is enabled. The initial value is @code{GL_FALSE}. See @code{glFog}.
11571 @item @code{GL_FOG_COORD_ARRAY}
11574 @var{params} returns a single boolean value indicating whether the fog
11575 coordinate array is enabled. The initial value is @code{GL_FALSE}. See
11576 @code{glFogCoordPointer}.
11578 @item @code{GL_FOG_COORD_ARRAY_BUFFER_BINDING}
11581 @var{params} returns a single value, the name of the buffer object
11582 associated with the fog coordinate array. This buffer object would have
11583 been bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
11584 recent call to @code{glFogCoordPointer}. If no buffer object was bound
11585 to this target, 0 is returned. The initial value is 0. See
11586 @code{glBindBuffer}.
11588 @item @code{GL_FOG_COORD_ARRAY_STRIDE}
11591 @var{params} returns one value, the byte offset between consecutive fog
11592 coordinates in the fog coordinate array. The initial value is 0. See
11593 @code{glFogCoordPointer}.
11595 @item @code{GL_FOG_COORD_ARRAY_TYPE}
11598 @var{params} returns one value, the type of the fog coordinate array.
11599 The initial value is @code{GL_FLOAT}. See @code{glFogCoordPointer}.
11601 @item @code{GL_FOG_COORD_SRC}
11604 @var{params} returns one value, a symbolic constant indicating the
11605 source of the fog coordinate. The initial value is
11606 @code{GL_FRAGMENT_DEPTH}. See @code{glFog}.
11608 @item @code{GL_FOG_COLOR}
11611 @var{params} returns four values: the red, green, blue, and alpha
11612 components of the fog color. Integer values, if requested, are linearly
11613 mapped from the internal floating-point representation such that 1.0
11614 returns the most positive representable integer value, and @r{-1.0}
11615 returns the most negative representable integer value. The initial
11616 value is (0, 0, 0, 0). See @code{glFog}.
11618 @item @code{GL_FOG_DENSITY}
11621 @var{params} returns one value, the fog density parameter. The initial
11622 value is 1. See @code{glFog}.
11624 @item @code{GL_FOG_END}
11627 @var{params} returns one value, the end factor for the linear fog
11628 equation. The initial value is 1. See @code{glFog}.
11630 @item @code{GL_FOG_HINT}
11633 @var{params} returns one value, a symbolic constant indicating the mode
11634 of the fog hint. The initial value is @code{GL_DONT_CARE}. See
11637 @item @code{GL_FOG_INDEX}
11640 @var{params} returns one value, the fog color index. The initial value
11641 is 0. See @code{glFog}.
11643 @item @code{GL_FOG_MODE}
11646 @var{params} returns one value, a symbolic constant indicating which fog
11647 equation is selected. The initial value is @code{GL_EXP}. See
11650 @item @code{GL_FOG_START}
11653 @var{params} returns one value, the start factor for the linear fog
11654 equation. The initial value is 0. See @code{glFog}.
11656 @item @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT}
11659 @var{params} returns one value, a symbolic constant indicating the mode
11660 of the derivative accuracy hint for fragment shaders. The initial value
11661 is @code{GL_DONT_CARE}. See @code{glHint}.
11663 @item @code{GL_FRONT_FACE}
11666 @var{params} returns one value, a symbolic constant indicating whether
11667 clockwise or counterclockwise polygon winding is treated as
11668 front-facing. The initial value is @code{GL_CCW}. See
11669 @code{glFrontFace}.
11671 @item @code{GL_GENERATE_MIPMAP_HINT}
11674 @var{params} returns one value, a symbolic constant indicating the mode
11675 of the mipmap generation filtering hint. The initial value is
11676 @code{GL_DONT_CARE}. See @code{glHint}.
11678 @item @code{GL_GREEN_BIAS}
11681 @var{params} returns one value, the green bias factor used during pixel
11682 transfers. The initial value is 0.
11684 @item @code{GL_GREEN_BITS}
11687 @var{params} returns one value, the number of green bitplanes in each
11690 @item @code{GL_GREEN_SCALE}
11693 @var{params} returns one value, the green scale factor used during pixel
11694 transfers. The initial value is 1. See @code{glPixelTransfer}.
11696 @item @code{GL_HISTOGRAM}
11699 @var{params} returns a single boolean value indicating whether histogram
11700 is enabled. The initial value is @code{GL_FALSE}. See
11701 @code{glHistogram}.
11703 @item @code{GL_INDEX_ARRAY}
11706 @var{params} returns a single boolean value indicating whether the color
11707 index array is enabled. The initial value is @code{GL_FALSE}. See
11708 @code{glIndexPointer}.
11710 @item @code{GL_INDEX_ARRAY_BUFFER_BINDING}
11713 @var{params} returns a single value, the name of the buffer object
11714 associated with the color index array. This buffer object would have
11715 been bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
11716 recent call to @code{glIndexPointer}. If no buffer object was bound to
11717 this target, 0 is returned. The initial value is 0. See
11718 @code{glBindBuffer}.
11720 @item @code{GL_INDEX_ARRAY_STRIDE}
11723 @var{params} returns one value, the byte offset between consecutive
11724 color indexes in the color index array. The initial value is 0. See
11725 @code{glIndexPointer}.
11727 @item @code{GL_INDEX_ARRAY_TYPE}
11730 @var{params} returns one value, the data type of indexes in the color
11731 index array. The initial value is @code{GL_FLOAT}. See
11732 @code{glIndexPointer}.
11734 @item @code{GL_INDEX_BITS}
11737 @var{params} returns one value, the number of bitplanes in each color
11740 @item @code{GL_INDEX_CLEAR_VALUE}
11743 @var{params} returns one value, the color index used to clear the color
11744 index buffers. The initial value is 0. See @code{glClearIndex}.
11746 @item @code{GL_INDEX_LOGIC_OP}
11749 @var{params} returns a single boolean value indicating whether a
11750 fragment's index values are merged into the framebuffer using a logical
11751 operation. The initial value is @code{GL_FALSE}. See @code{glLogicOp}.
11753 @item @code{GL_INDEX_MODE}
11756 @var{params} returns a single boolean value indicating whether the GL is
11757 in color index mode (@code{GL_TRUE}) or RGBA mode (@code{GL_FALSE}).
11759 @item @code{GL_INDEX_OFFSET}
11762 @var{params} returns one value, the offset added to color and stencil
11763 indices during pixel transfers. The initial value is 0. See
11764 @code{glPixelTransfer}.
11766 @item @code{GL_INDEX_SHIFT}
11769 @var{params} returns one value, the amount that color and stencil
11770 indices are shifted during pixel transfers. The initial value is 0. See
11771 @code{glPixelTransfer}.
11773 @item @code{GL_INDEX_WRITEMASK}
11776 @var{params} returns one value, a mask indicating which bitplanes of
11777 each color index buffer can be written. The initial value is all 1's.
11778 See @code{glIndexMask}.
11780 @item @code{GL_LIGHT}@var{i}
11783 @var{params} returns a single boolean value indicating whether the
11784 specified light is enabled. The initial value is @code{GL_FALSE}. See
11785 @code{glLight} and @code{glLightModel}.
11787 @item @code{GL_LIGHTING}
11790 @var{params} returns a single boolean value indicating whether lighting
11791 is enabled. The initial value is @code{GL_FALSE}. See
11792 @code{glLightModel}.
11794 @item @code{GL_LIGHT_MODEL_AMBIENT}
11797 @var{params} returns four values: the red, green, blue, and alpha
11798 components of the ambient intensity of the entire scene. Integer
11799 values, if requested, are linearly mapped from the internal
11800 floating-point representation such that 1.0 returns the most positive
11801 representable integer value, and @r{-1.0} returns the most negative
11802 representable integer value. The initial value is (0.2, 0.2, 0.2, 1.0).
11803 See @code{glLightModel}.
11805 @item @code{GL_LIGHT_MODEL_COLOR_CONTROL}
11808 @var{params} returns single enumerated value indicating whether specular
11809 reflection calculations are separated from normal lighting computations.
11810 The initial value is @code{GL_SINGLE_COLOR}.
11812 @item @code{GL_LIGHT_MODEL_LOCAL_VIEWER}
11815 @var{params} returns a single boolean value indicating whether specular
11816 reflection calculations treat the viewer as being local to the scene.
11817 The initial value is @code{GL_FALSE}. See @code{glLightModel}.
11819 @item @code{GL_LIGHT_MODEL_TWO_SIDE}
11822 @var{params} returns a single boolean value indicating whether separate
11823 materials are used to compute lighting for front- and back-facing
11824 polygons. The initial value is @code{GL_FALSE}. See
11825 @code{glLightModel}.
11827 @item @code{GL_LINE_SMOOTH}
11830 @var{params} returns a single boolean value indicating whether
11831 antialiasing of lines is enabled. The initial value is @code{GL_FALSE}.
11832 See @code{glLineWidth}.
11834 @item @code{GL_LINE_SMOOTH_HINT}
11837 @var{params} returns one value, a symbolic constant indicating the mode
11838 of the line antialiasing hint. The initial value is
11839 @code{GL_DONT_CARE}. See @code{glHint}.
11841 @item @code{GL_LINE_STIPPLE}
11844 @var{params} returns a single boolean value indicating whether stippling
11845 of lines is enabled. The initial value is @code{GL_FALSE}. See
11846 @code{glLineStipple}.
11848 @item @code{GL_LINE_STIPPLE_PATTERN}
11851 @var{params} returns one value, the 16-bit line stipple pattern. The
11852 initial value is all 1's. See @code{glLineStipple}.
11854 @item @code{GL_LINE_STIPPLE_REPEAT}
11857 @var{params} returns one value, the line stipple repeat factor. The
11858 initial value is 1. See @code{glLineStipple}.
11860 @item @code{GL_LINE_WIDTH}
11863 @var{params} returns one value, the line width as specified with
11864 @code{glLineWidth}. The initial value is 1.
11866 @item @code{GL_LINE_WIDTH_GRANULARITY}
11869 @var{params} returns one value, the width difference between adjacent
11870 supported widths for antialiased lines. See @code{glLineWidth}.
11872 @item @code{GL_LINE_WIDTH_RANGE}
11875 @var{params} returns two values: the smallest and largest supported
11876 widths for antialiased lines. See @code{glLineWidth}.
11878 @item @code{GL_LIST_BASE}
11881 @var{params} returns one value, the base offset added to all names in
11882 arrays presented to @code{glCallLists}. The initial value is 0. See
11885 @item @code{GL_LIST_INDEX}
11888 @var{params} returns one value, the name of the display list currently
11889 under construction. 0 is returned if no display list is currently under
11890 construction. The initial value is 0. See @code{glNewList}.
11892 @item @code{GL_LIST_MODE}
11895 @var{params} returns one value, a symbolic constant indicating the
11896 construction mode of the display list currently under construction. The
11897 initial value is 0. See @code{glNewList}.
11899 @item @code{GL_LOGIC_OP_MODE}
11902 @var{params} returns one value, a symbolic constant indicating the
11903 selected logic operation mode. The initial value is @code{GL_COPY}. See
11906 @item @code{GL_MAP1_COLOR_4}
11909 @var{params} returns a single boolean value indicating whether 1D
11910 evaluation generates colors. The initial value is @code{GL_FALSE}. See
11913 @item @code{GL_MAP1_GRID_DOMAIN}
11916 @var{params} returns two values: the endpoints of the 1D map's grid
11917 domain. The initial value is (0, 1). See @code{glMapGrid}.
11919 @item @code{GL_MAP1_GRID_SEGMENTS}
11922 @var{params} returns one value, the number of partitions in the 1D map's
11923 grid domain. The initial value is 1. See @code{glMapGrid}.
11925 @item @code{GL_MAP1_INDEX}
11928 @var{params} returns a single boolean value indicating whether 1D
11929 evaluation generates color indices. The initial value is
11930 @code{GL_FALSE}. See @code{glMap1}.
11932 @item @code{GL_MAP1_NORMAL}
11935 @var{params} returns a single boolean value indicating whether 1D
11936 evaluation generates normals. The initial value is @code{GL_FALSE}. See
11939 @item @code{GL_MAP1_TEXTURE_COORD_1}
11942 @var{params} returns a single boolean value indicating whether 1D
11943 evaluation generates 1D texture coordinates. The initial value is
11944 @code{GL_FALSE}. See @code{glMap1}.
11946 @item @code{GL_MAP1_TEXTURE_COORD_2}
11949 @var{params} returns a single boolean value indicating whether 1D
11950 evaluation generates 2D texture coordinates. The initial value is
11951 @code{GL_FALSE}. See @code{glMap1}.
11953 @item @code{GL_MAP1_TEXTURE_COORD_3}
11956 @var{params} returns a single boolean value indicating whether 1D
11957 evaluation generates 3D texture coordinates. The initial value is
11958 @code{GL_FALSE}. See @code{glMap1}.
11960 @item @code{GL_MAP1_TEXTURE_COORD_4}
11963 @var{params} returns a single boolean value indicating whether 1D
11964 evaluation generates 4D texture coordinates. The initial value is
11965 @code{GL_FALSE}. See @code{glMap1}.
11967 @item @code{GL_MAP1_VERTEX_3}
11970 @var{params} returns a single boolean value indicating whether 1D
11971 evaluation generates 3D vertex coordinates. The initial value is
11972 @code{GL_FALSE}. See @code{glMap1}.
11974 @item @code{GL_MAP1_VERTEX_4}
11977 @var{params} returns a single boolean value indicating whether 1D
11978 evaluation generates 4D vertex coordinates. The initial value is
11979 @code{GL_FALSE}. See @code{glMap1}.
11981 @item @code{GL_MAP2_COLOR_4}
11984 @var{params} returns a single boolean value indicating whether 2D
11985 evaluation generates colors. The initial value is @code{GL_FALSE}. See
11988 @item @code{GL_MAP2_GRID_DOMAIN}
11991 @var{params} returns four values: the endpoints of the 2D map's
11992 @r{@var{i}} and @r{@var{j}} grid domains. The initial value is (0,1;
11993 0,1). See @code{glMapGrid}.
11995 @item @code{GL_MAP2_GRID_SEGMENTS}
11998 @var{params} returns two values: the number of partitions in the 2D
11999 map's @r{@var{i}} and @r{@var{j}} grid domains. The initial value is
12000 (1,1). See @code{glMapGrid}.
12002 @item @code{GL_MAP2_INDEX}
12005 @var{params} returns a single boolean value indicating whether 2D
12006 evaluation generates color indices. The initial value is
12007 @code{GL_FALSE}. See @code{glMap2}.
12009 @item @code{GL_MAP2_NORMAL}
12012 @var{params} returns a single boolean value indicating whether 2D
12013 evaluation generates normals. The initial value is @code{GL_FALSE}. See
12016 @item @code{GL_MAP2_TEXTURE_COORD_1}
12019 @var{params} returns a single boolean value indicating whether 2D
12020 evaluation generates 1D texture coordinates. The initial value is
12021 @code{GL_FALSE}. See @code{glMap2}.
12023 @item @code{GL_MAP2_TEXTURE_COORD_2}
12026 @var{params} returns a single boolean value indicating whether 2D
12027 evaluation generates 2D texture coordinates. The initial value is
12028 @code{GL_FALSE}. See @code{glMap2}.
12030 @item @code{GL_MAP2_TEXTURE_COORD_3}
12033 @var{params} returns a single boolean value indicating whether 2D
12034 evaluation generates 3D texture coordinates. The initial value is
12035 @code{GL_FALSE}. See @code{glMap2}.
12037 @item @code{GL_MAP2_TEXTURE_COORD_4}
12040 @var{params} returns a single boolean value indicating whether 2D
12041 evaluation generates 4D texture coordinates. The initial value is
12042 @code{GL_FALSE}. See @code{glMap2}.
12044 @item @code{GL_MAP2_VERTEX_3}
12047 @var{params} returns a single boolean value indicating whether 2D
12048 evaluation generates 3D vertex coordinates. The initial value is
12049 @code{GL_FALSE}. See @code{glMap2}.
12051 @item @code{GL_MAP2_VERTEX_4}
12054 @var{params} returns a single boolean value indicating whether 2D
12055 evaluation generates 4D vertex coordinates. The initial value is
12056 @code{GL_FALSE}. See @code{glMap2}.
12058 @item @code{GL_MAP_COLOR}
12061 @var{params} returns a single boolean value indicating if colors and
12062 color indices are to be replaced by table lookup during pixel transfers.
12063 The initial value is @code{GL_FALSE}. See @code{glPixelTransfer}.
12065 @item @code{GL_MAP_STENCIL}
12068 @var{params} returns a single boolean value indicating if stencil
12069 indices are to be replaced by table lookup during pixel transfers. The
12070 initial value is @code{GL_FALSE}. See @code{glPixelTransfer}.
12072 @item @code{GL_MATRIX_MODE}
12075 @var{params} returns one value, a symbolic constant indicating which
12076 matrix stack is currently the target of all matrix operations. The
12077 initial value is @code{GL_MODELVIEW}. See @code{glMatrixMode}.
12079 @item @code{GL_MAX_3D_TEXTURE_SIZE}
12082 @var{params} returns one value, a rough estimate of the largest 3D
12083 texture that the GL can handle. The value must be at least 16. If the
12084 GL version is 1.2 or greater, use @code{GL_PROXY_TEXTURE_3D} to
12085 determine if a texture is too large. See @code{glTexImage3D}.
12087 @item @code{GL_MAX_CLIENT_ATTRIB_STACK_DEPTH}
12090 @var{params} returns one value indicating the maximum supported depth of
12091 the client attribute stack. See @code{glPushClientAttrib}.
12093 @item @code{GL_MAX_ATTRIB_STACK_DEPTH}
12096 @var{params} returns one value, the maximum supported depth of the
12097 attribute stack. The value must be at least 16. See
12098 @code{glPushAttrib}.
12100 @item @code{GL_MAX_CLIP_PLANES}
12103 @var{params} returns one value, the maximum number of
12104 application-defined clipping planes. The value must be at least 6. See
12105 @code{glClipPlane}.
12107 @item @code{GL_MAX_COLOR_MATRIX_STACK_DEPTH}
12110 @var{params} returns one value, the maximum supported depth of the color
12111 matrix stack. The value must be at least 2. See @code{glPushMatrix}.
12113 @item @code{GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS}
12116 @var{params} returns one value, the maximum supported texture image
12117 units that can be used to access texture maps from the vertex shader and
12118 the fragment processor combined. If both the vertex shader and the
12119 fragment processing stage access the same texture image unit, then that
12120 counts as using two texture image units against this limit. The value
12121 must be at least 2. See @code{glActiveTexture}.
12123 @item @code{GL_MAX_CUBE_MAP_TEXTURE_SIZE}
12126 @var{params} returns one value. The value gives a rough estimate of the
12127 largest cube-map texture that the GL can handle. The value must be at
12128 least 16. If the GL version is 1.3 or greater, use
12129 @code{GL_PROXY_TEXTURE_CUBE_MAP} to determine if a texture is too large.
12130 See @code{glTexImage2D}.
12132 @item @code{GL_MAX_DRAW_BUFFERS}
12135 @var{params} returns one value, the maximum number of simultaneous
12136 output colors allowed from a fragment shader using the
12137 @code{gl_FragData} built-in array. The value must be at least 1. See
12138 @code{glDrawBuffers}.
12140 @item @code{GL_MAX_ELEMENTS_INDICES}
12143 @var{params} returns one value, the recommended maximum number of vertex
12144 array indices. See @code{glDrawRangeElements}.
12146 @item @code{GL_MAX_ELEMENTS_VERTICES}
12149 @var{params} returns one value, the recommended maximum number of vertex
12150 array vertices. See @code{glDrawRangeElements}.
12152 @item @code{GL_MAX_EVAL_ORDER}
12155 @var{params} returns one value, the maximum equation order supported by
12156 1D and 2D evaluators. The value must be at least 8. See @code{glMap1}
12159 @item @code{GL_MAX_FRAGMENT_UNIFORM_COMPONENTS}
12162 @var{params} returns one value, the maximum number of individual
12163 floating-point, integer, or boolean values that can be held in uniform
12164 variable storage for a fragment shader. The value must be at least 64.
12165 See @code{glUniform}.
12167 @item @code{GL_MAX_LIGHTS}
12170 @var{params} returns one value, the maximum number of lights. The value
12171 must be at least 8. See @code{glLight}.
12173 @item @code{GL_MAX_LIST_NESTING}
12176 @var{params} returns one value, the maximum recursion depth allowed
12177 during display-list traversal. The value must be at least 64. See
12180 @item @code{GL_MAX_MODELVIEW_STACK_DEPTH}
12183 @var{params} returns one value, the maximum supported depth of the
12184 modelview matrix stack. The value must be at least 32. See
12185 @code{glPushMatrix}.
12187 @item @code{GL_MAX_NAME_STACK_DEPTH}
12190 @var{params} returns one value, the maximum supported depth of the
12191 selection name stack. The value must be at least 64. See
12194 @item @code{GL_MAX_PIXEL_MAP_TABLE}
12197 @var{params} returns one value, the maximum supported size of a
12198 @code{glPixelMap} lookup table. The value must be at least 32. See
12201 @item @code{GL_MAX_PROJECTION_STACK_DEPTH}
12204 @var{params} returns one value, the maximum supported depth of the
12205 projection matrix stack. The value must be at least 2. See
12206 @code{glPushMatrix}.
12208 @item @code{GL_MAX_TEXTURE_COORDS}
12211 @var{params} returns one value, the maximum number of texture coordinate
12212 sets available to vertex and fragment shaders. The value must be at
12213 least 2. See @code{glActiveTexture} and @code{glClientActiveTexture}.
12215 @item @code{GL_MAX_TEXTURE_IMAGE_UNITS}
12218 @var{params} returns one value, the maximum supported texture image
12219 units that can be used to access texture maps from the fragment shader.
12220 The value must be at least 2. See @code{glActiveTexture}.
12222 @item @code{GL_MAX_TEXTURE_LOD_BIAS}
12225 @var{params} returns one value, the maximum, absolute value of the
12226 texture level-of-detail bias. The value must be at least 4.
12228 @item @code{GL_MAX_TEXTURE_SIZE}
12231 @var{params} returns one value. The value gives a rough estimate of the
12232 largest texture that the GL can handle. The value must be at least 64.
12233 If the GL version is 1.1 or greater, use @code{GL_PROXY_TEXTURE_1D} or
12234 @code{GL_PROXY_TEXTURE_2D} to determine if a texture is too large. See
12235 @code{glTexImage1D} and @code{glTexImage2D}.
12237 @item @code{GL_MAX_TEXTURE_STACK_DEPTH}
12240 @var{params} returns one value, the maximum supported depth of the
12241 texture matrix stack. The value must be at least 2. See
12242 @code{glPushMatrix}.
12244 @item @code{GL_MAX_TEXTURE_UNITS}
12247 @var{params} returns a single value indicating the number of
12248 conventional texture units supported. Each conventional texture unit
12249 includes both a texture coordinate set and a texture image unit.
12250 Conventional texture units may be used for fixed-function (non-shader)
12251 rendering. The value must be at least 2. Additional texture coordinate
12252 sets and texture image units may be accessed from vertex and fragment
12253 shaders. See @code{glActiveTexture} and @code{glClientActiveTexture}.
12255 @item @code{GL_MAX_VARYING_FLOATS}
12258 @var{params} returns one value, the maximum number of interpolators
12259 available for processing varying variables used by vertex and fragment
12260 shaders. This value represents the number of individual floating-point
12261 values that can be interpolated; varying variables declared as vectors,
12262 matrices, and arrays will all consume multiple interpolators. The value
12263 must be at least 32.
12265 @item @code{GL_MAX_VERTEX_ATTRIBS}
12268 @var{params} returns one value, the maximum number of 4-component
12269 generic vertex attributes accessible to a vertex shader. The value must
12270 be at least 16. See @code{glVertexAttrib}.
12272 @item @code{GL_MAX_VERTEX_TEXTURE_IMAGE_UNITS}
12275 @var{params} returns one value, the maximum supported texture image
12276 units that can be used to access texture maps from the vertex shader.
12277 The value may be 0. See @code{glActiveTexture}.
12279 @item @code{GL_MAX_VERTEX_UNIFORM_COMPONENTS}
12282 @var{params} returns one value, the maximum number of individual
12283 floating-point, integer, or boolean values that can be held in uniform
12284 variable storage for a vertex shader. The value must be at least 512.
12285 See @code{glUniform}.
12287 @item @code{GL_MAX_VIEWPORT_DIMS}
12290 @var{params} returns two values: the maximum supported width and height
12291 of the viewport. These must be at least as large as the visible
12292 dimensions of the display being rendered to. See @code{glViewport}.
12294 @item @code{GL_MINMAX}
12297 @var{params} returns a single boolean value indicating whether pixel
12298 minmax values are computed. The initial value is @code{GL_FALSE}. See
12301 @item @code{GL_MODELVIEW_MATRIX}
12304 @var{params} returns sixteen values: the modelview matrix on the top of
12305 the modelview matrix stack. Initially this matrix is the identity
12306 matrix. See @code{glPushMatrix}.
12308 @item @code{GL_MODELVIEW_STACK_DEPTH}
12311 @var{params} returns one value, the number of matrices on the modelview
12312 matrix stack. The initial value is 1. See @code{glPushMatrix}.
12314 @item @code{GL_NAME_STACK_DEPTH}
12317 @var{params} returns one value, the number of names on the selection
12318 name stack. The initial value is 0. See @code{glPushName}.
12320 @item @code{GL_NORMAL_ARRAY}
12323 @var{params} returns a single boolean value, indicating whether the
12324 normal array is enabled. The initial value is @code{GL_FALSE}. See
12325 @code{glNormalPointer}.
12327 @item @code{GL_NORMAL_ARRAY_BUFFER_BINDING}
12330 @var{params} returns a single value, the name of the buffer object
12331 associated with the normal array. This buffer object would have been
12332 bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
12333 recent call to @code{glNormalPointer}. If no buffer object was bound to
12334 this target, 0 is returned. The initial value is 0. See
12335 @code{glBindBuffer}.
12337 @item @code{GL_NORMAL_ARRAY_STRIDE}
12340 @var{params} returns one value, the byte offset between consecutive
12341 normals in the normal array. The initial value is 0. See
12342 @code{glNormalPointer}.
12344 @item @code{GL_NORMAL_ARRAY_TYPE}
12347 @var{params} returns one value, the data type of each coordinate in the
12348 normal array. The initial value is @code{GL_FLOAT}. See
12349 @code{glNormalPointer}.
12351 @item @code{GL_NORMALIZE}
12354 @var{params} returns a single boolean value indicating whether normals
12355 are automatically scaled to unit length after they have been transformed
12356 to eye coordinates. The initial value is @code{GL_FALSE}. See
12359 @item @code{GL_NUM_COMPRESSED_TEXTURE_FORMATS}
12362 @var{params} returns a single integer value indicating the number of
12363 available compressed texture formats. The minimum value is 0. See
12364 @code{glCompressedTexImage2D}.
12366 @item @code{GL_PACK_ALIGNMENT}
12369 @var{params} returns one value, the byte alignment used for writing
12370 pixel data to memory. The initial value is 4. See @code{glPixelStore}.
12372 @item @code{GL_PACK_IMAGE_HEIGHT}
12375 @var{params} returns one value, the image height used for writing pixel
12376 data to memory. The initial value is 0. See @code{glPixelStore}.
12378 @item @code{GL_PACK_LSB_FIRST}
12381 @var{params} returns a single boolean value indicating whether
12382 single-bit pixels being written to memory are written first to the least
12383 significant bit of each unsigned byte. The initial value is
12384 @code{GL_FALSE}. See @code{glPixelStore}.
12386 @item @code{GL_PACK_ROW_LENGTH}
12389 @var{params} returns one value, the row length used for writing pixel
12390 data to memory. The initial value is 0. See @code{glPixelStore}.
12392 @item @code{GL_PACK_SKIP_IMAGES}
12395 @var{params} returns one value, the number of pixel images skipped
12396 before the first pixel is written into memory. The initial value is 0.
12397 See @code{glPixelStore}.
12399 @item @code{GL_PACK_SKIP_PIXELS}
12402 @var{params} returns one value, the number of pixel locations skipped
12403 before the first pixel is written into memory. The initial value is 0.
12404 See @code{glPixelStore}.
12406 @item @code{GL_PACK_SKIP_ROWS}
12409 @var{params} returns one value, the number of rows of pixel locations
12410 skipped before the first pixel is written into memory. The initial
12411 value is 0. See @code{glPixelStore}.
12413 @item @code{GL_PACK_SWAP_BYTES}
12416 @var{params} returns a single boolean value indicating whether the bytes
12417 of two-byte and four-byte pixel indices and components are swapped
12418 before being written to memory. The initial value is @code{GL_FALSE}.
12419 See @code{glPixelStore}.
12421 @item @code{GL_PERSPECTIVE_CORRECTION_HINT}
12424 @var{params} returns one value, a symbolic constant indicating the mode
12425 of the perspective correction hint. The initial value is
12426 @code{GL_DONT_CARE}. See @code{glHint}.
12428 @item @code{GL_PIXEL_MAP_A_TO_A_SIZE}
12431 @var{params} returns one value, the size of the alpha-to-alpha pixel
12432 translation table. The initial value is 1. See @code{glPixelMap}.
12434 @item @code{GL_PIXEL_MAP_B_TO_B_SIZE}
12437 @var{params} returns one value, the size of the blue-to-blue pixel
12438 translation table. The initial value is 1. See @code{glPixelMap}.
12440 @item @code{GL_PIXEL_MAP_G_TO_G_SIZE}
12443 @var{params} returns one value, the size of the green-to-green pixel
12444 translation table. The initial value is 1. See @code{glPixelMap}.
12446 @item @code{GL_PIXEL_MAP_I_TO_A_SIZE}
12449 @var{params} returns one value, the size of the index-to-alpha pixel
12450 translation table. The initial value is 1. See @code{glPixelMap}.
12452 @item @code{GL_PIXEL_MAP_I_TO_B_SIZE}
12455 @var{params} returns one value, the size of the index-to-blue pixel
12456 translation table. The initial value is 1. See @code{glPixelMap}.
12458 @item @code{GL_PIXEL_MAP_I_TO_G_SIZE}
12461 @var{params} returns one value, the size of the index-to-green pixel
12462 translation table. The initial value is 1. See @code{glPixelMap}.
12464 @item @code{GL_PIXEL_MAP_I_TO_I_SIZE}
12467 @var{params} returns one value, the size of the index-to-index pixel
12468 translation table. The initial value is 1. See @code{glPixelMap}.
12470 @item @code{GL_PIXEL_MAP_I_TO_R_SIZE}
12473 @var{params} returns one value, the size of the index-to-red pixel
12474 translation table. The initial value is 1. See @code{glPixelMap}.
12476 @item @code{GL_PIXEL_MAP_R_TO_R_SIZE}
12479 @var{params} returns one value, the size of the red-to-red pixel
12480 translation table. The initial value is 1. See @code{glPixelMap}.
12482 @item @code{GL_PIXEL_MAP_S_TO_S_SIZE}
12485 @var{params} returns one value, the size of the stencil-to-stencil pixel
12486 translation table. The initial value is 1. See @code{glPixelMap}.
12488 @item @code{GL_PIXEL_PACK_BUFFER_BINDING}
12491 @var{params} returns a single value, the name of the buffer object
12492 currently bound to the target @code{GL_PIXEL_PACK_BUFFER}. If no buffer
12493 object is bound to this target, 0 is returned. The initial value is 0.
12494 See @code{glBindBuffer}.
12496 @item @code{GL_PIXEL_UNPACK_BUFFER_BINDING}
12499 @var{params} returns a single value, the name of the buffer object
12500 currently bound to the target @code{GL_PIXEL_UNPACK_BUFFER}. If no
12501 buffer object is bound to this target, 0 is returned. The initial value
12502 is 0. See @code{glBindBuffer}.
12504 @item @code{GL_POINT_DISTANCE_ATTENUATION}
12507 @var{params} returns three values, the coefficients for computing the
12508 attenuation value for points. See @code{glPointParameter}.
12510 @item @code{GL_POINT_FADE_THRESHOLD_SIZE}
12513 @var{params} returns one value, the point size threshold for determining
12514 the point size. See @code{glPointParameter}.
12516 @item @code{GL_POINT_SIZE}
12519 @var{params} returns one value, the point size as specified by
12520 @code{glPointSize}. The initial value is 1.
12522 @item @code{GL_POINT_SIZE_GRANULARITY}
12525 @var{params} returns one value, the size difference between adjacent
12526 supported sizes for antialiased points. See @code{glPointSize}.
12528 @item @code{GL_POINT_SIZE_MAX}
12531 @var{params} returns one value, the upper bound for the attenuated point
12532 sizes. The initial value is 0.0. See @code{glPointParameter}.
12534 @item @code{GL_POINT_SIZE_MIN}
12537 @var{params} returns one value, the lower bound for the attenuated point
12538 sizes. The initial value is 1.0. See @code{glPointParameter}.
12540 @item @code{GL_POINT_SIZE_RANGE}
12543 @var{params} returns two values: the smallest and largest supported
12544 sizes for antialiased points. The smallest size must be at most 1, and
12545 the largest size must be at least 1. See @code{glPointSize}.
12547 @item @code{GL_POINT_SMOOTH}
12550 @var{params} returns a single boolean value indicating whether
12551 antialiasing of points is enabled. The initial value is
12552 @code{GL_FALSE}. See @code{glPointSize}.
12554 @item @code{GL_POINT_SMOOTH_HINT}
12557 @var{params} returns one value, a symbolic constant indicating the mode
12558 of the point antialiasing hint. The initial value is
12559 @code{GL_DONT_CARE}. See @code{glHint}.
12561 @item @code{GL_POINT_SPRITE}
12564 @var{params} returns a single boolean value indicating whether point
12565 sprite is enabled. The initial value is @code{GL_FALSE}.
12567 @item @code{GL_POLYGON_MODE}
12570 @var{params} returns two values: symbolic constants indicating whether
12571 front-facing and back-facing polygons are rasterized as points, lines,
12572 or filled polygons. The initial value is @code{GL_FILL}. See
12573 @code{glPolygonMode}.
12575 @item @code{GL_POLYGON_OFFSET_FACTOR}
12578 @var{params} returns one value, the scaling factor used to determine the
12579 variable offset that is added to the depth value of each fragment
12580 generated when a polygon is rasterized. The initial value is 0. See
12581 @code{glPolygonOffset}.
12583 @item @code{GL_POLYGON_OFFSET_UNITS}
12586 @var{params} returns one value. This value is multiplied by an
12587 implementation-specific value and then added to the depth value of each
12588 fragment generated when a polygon is rasterized. The initial value is
12589 0. See @code{glPolygonOffset}.
12591 @item @code{GL_POLYGON_OFFSET_FILL}
12594 @var{params} returns a single boolean value indicating whether polygon
12595 offset is enabled for polygons in fill mode. The initial value is
12596 @code{GL_FALSE}. See @code{glPolygonOffset}.
12598 @item @code{GL_POLYGON_OFFSET_LINE}
12601 @var{params} returns a single boolean value indicating whether polygon
12602 offset is enabled for polygons in line mode. The initial value is
12603 @code{GL_FALSE}. See @code{glPolygonOffset}.
12605 @item @code{GL_POLYGON_OFFSET_POINT}
12608 @var{params} returns a single boolean value indicating whether polygon
12609 offset is enabled for polygons in point mode. The initial value is
12610 @code{GL_FALSE}. See @code{glPolygonOffset}.
12612 @item @code{GL_POLYGON_SMOOTH}
12615 @var{params} returns a single boolean value indicating whether
12616 antialiasing of polygons is enabled. The initial value is
12617 @code{GL_FALSE}. See @code{glPolygonMode}.
12619 @item @code{GL_POLYGON_SMOOTH_HINT}
12622 @var{params} returns one value, a symbolic constant indicating the mode
12623 of the polygon antialiasing hint. The initial value is
12624 @code{GL_DONT_CARE}. See @code{glHint}.
12626 @item @code{GL_POLYGON_STIPPLE}
12629 @var{params} returns a single boolean value indicating whether polygon
12630 stippling is enabled. The initial value is @code{GL_FALSE}. See
12631 @code{glPolygonStipple}.
12633 @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}
12636 @var{params} returns a single boolean value indicating whether post
12637 color matrix transformation lookup is enabled. The initial value is
12638 @code{GL_FALSE}. See @code{glColorTable}.
12640 @item @code{GL_POST_COLOR_MATRIX_RED_BIAS}
12643 @var{params} returns one value, the red bias factor applied to RGBA
12644 fragments after color matrix transformations. The initial value is 0.
12645 See @code{glPixelTransfer}.
12647 @item @code{GL_POST_COLOR_MATRIX_GREEN_BIAS}
12650 @var{params} returns one value, the green bias factor applied to RGBA
12651 fragments after color matrix transformations. The initial value is 0.
12652 See @code{glPixelTransfer}
12654 @item @code{GL_POST_COLOR_MATRIX_BLUE_BIAS}
12657 @var{params} returns one value, the blue bias factor applied to RGBA
12658 fragments after color matrix transformations. The initial value is 0.
12659 See @code{glPixelTransfer}.
12661 @item @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS}
12664 @var{params} returns one value, the alpha bias factor applied to RGBA
12665 fragments after color matrix transformations. The initial value is 0.
12666 See @code{glPixelTransfer}.
12668 @item @code{GL_POST_COLOR_MATRIX_RED_SCALE}
12671 @var{params} returns one value, the red scale factor applied to RGBA
12672 fragments after color matrix transformations. The initial value is 1.
12673 See @code{glPixelTransfer}.
12675 @item @code{GL_POST_COLOR_MATRIX_GREEN_SCALE}
12678 @var{params} returns one value, the green scale factor applied to RGBA
12679 fragments after color matrix transformations. The initial value is 1.
12680 See @code{glPixelTransfer}.
12682 @item @code{GL_POST_COLOR_MATRIX_BLUE_SCALE}
12685 @var{params} returns one value, the blue scale factor applied to RGBA
12686 fragments after color matrix transformations. The initial value is 1.
12687 See @code{glPixelTransfer}.
12689 @item @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE}
12692 @var{params} returns one value, the alpha scale factor applied to RGBA
12693 fragments after color matrix transformations. The initial value is 1.
12694 See @code{glPixelTransfer}.
12696 @item @code{GL_POST_CONVOLUTION_COLOR_TABLE}
12699 @var{params} returns a single boolean value indicating whether post
12700 convolution lookup is enabled. The initial value is @code{GL_FALSE}.
12701 See @code{glColorTable}.
12703 @item @code{GL_POST_CONVOLUTION_RED_BIAS}
12706 @var{params} returns one value, the red bias factor applied to RGBA
12707 fragments after convolution. The initial value is 0. See
12708 @code{glPixelTransfer}.
12710 @item @code{GL_POST_CONVOLUTION_GREEN_BIAS}
12713 @var{params} returns one value, the green bias factor applied to RGBA
12714 fragments after convolution. The initial value is 0. See
12715 @code{glPixelTransfer}.
12717 @item @code{GL_POST_CONVOLUTION_BLUE_BIAS}
12720 @var{params} returns one value, the blue bias factor applied to RGBA
12721 fragments after convolution. The initial value is 0. See
12722 @code{glPixelTransfer}.
12724 @item @code{GL_POST_CONVOLUTION_ALPHA_BIAS}
12727 @var{params} returns one value, the alpha bias factor applied to RGBA
12728 fragments after convolution. The initial value is 0. See
12729 @code{glPixelTransfer}.
12731 @item @code{GL_POST_CONVOLUTION_RED_SCALE}
12734 @var{params} returns one value, the red scale factor applied to RGBA
12735 fragments after convolution. The initial value is 1. See
12736 @code{glPixelTransfer}.
12738 @item @code{GL_POST_CONVOLUTION_GREEN_SCALE}
12741 @var{params} returns one value, the green scale factor applied to RGBA
12742 fragments after convolution. The initial value is 1. See
12743 @code{glPixelTransfer}.
12745 @item @code{GL_POST_CONVOLUTION_BLUE_SCALE}
12748 @var{params} returns one value, the blue scale factor applied to RGBA
12749 fragments after convolution. The initial value is 1. See
12750 @code{glPixelTransfer}.
12752 @item @code{GL_POST_CONVOLUTION_ALPHA_SCALE}
12755 @var{params} returns one value, the alpha scale factor applied to RGBA
12756 fragments after convolution. The initial value is 1. See
12757 @code{glPixelTransfer}.
12759 @item @code{GL_PROJECTION_MATRIX}
12762 @var{params} returns sixteen values: the projection matrix on the top of
12763 the projection matrix stack. Initially this matrix is the identity
12764 matrix. See @code{glPushMatrix}.
12766 @item @code{GL_PROJECTION_STACK_DEPTH}
12769 @var{params} returns one value, the number of matrices on the projection
12770 matrix stack. The initial value is 1. See @code{glPushMatrix}.
12772 @item @code{GL_READ_BUFFER}
12775 @var{params} returns one value, a symbolic constant indicating which
12776 color buffer is selected for reading. The initial value is
12777 @code{GL_BACK} if there is a back buffer, otherwise it is
12778 @code{GL_FRONT}. See @code{glReadPixels} and @code{glAccum}.
12780 @item @code{GL_RED_BIAS}
12783 @var{params} returns one value, the red bias factor used during pixel
12784 transfers. The initial value is 0.
12786 @item @code{GL_RED_BITS}
12789 @var{params} returns one value, the number of red bitplanes in each
12792 @item @code{GL_RED_SCALE}
12795 @var{params} returns one value, the red scale factor used during pixel
12796 transfers. The initial value is 1. See @code{glPixelTransfer}.
12798 @item @code{GL_RENDER_MODE}
12801 @var{params} returns one value, a symbolic constant indicating whether
12802 the GL is in render, select, or feedback mode. The initial value is
12803 @code{GL_RENDER}. See @code{glRenderMode}.
12805 @item @code{GL_RESCALE_NORMAL}
12808 @var{params} returns single boolean value indicating whether normal
12809 rescaling is enabled. See @code{glEnable}.
12811 @item @code{GL_RGBA_MODE}
12814 @var{params} returns a single boolean value indicating whether the GL is
12815 in RGBA mode (true) or color index mode (false). See @code{glColor}.
12817 @item @code{GL_SAMPLE_BUFFERS}
12820 @var{params} returns a single integer value indicating the number of
12821 sample buffers associated with the framebuffer. See
12822 @code{glSampleCoverage}.
12824 @item @code{GL_SAMPLE_COVERAGE_VALUE}
12827 @var{params} returns a single positive floating-point value indicating
12828 the current sample coverage value. See @code{glSampleCoverage}.
12830 @item @code{GL_SAMPLE_COVERAGE_INVERT}
12833 @var{params} returns a single boolean value indicating if the temporary
12834 coverage value should be inverted. See @code{glSampleCoverage}.
12836 @item @code{GL_SAMPLES}
12839 @var{params} returns a single integer value indicating the coverage mask
12840 size. See @code{glSampleCoverage}.
12842 @item @code{GL_SCISSOR_BOX}
12845 @var{params} returns four values: the @r{@var{x}} and @r{@var{y}} window
12846 coordinates of the scissor box, followed by its width and height.
12847 Initially the @r{@var{x}} and @r{@var{y}} window coordinates are both 0
12848 and the width and height are set to the size of the window. See
12851 @item @code{GL_SCISSOR_TEST}
12854 @var{params} returns a single boolean value indicating whether
12855 scissoring is enabled. The initial value is @code{GL_FALSE}. See
12858 @item @code{GL_SECONDARY_COLOR_ARRAY}
12861 @var{params} returns a single boolean value indicating whether the
12862 secondary color array is enabled. The initial value is @code{GL_FALSE}.
12863 See @code{glSecondaryColorPointer}.
12865 @item @code{GL_SECONDARY_COLOR_ARRAY_BUFFER_BINDING}
12868 @var{params} returns a single value, the name of the buffer object
12869 associated with the secondary color array. This buffer object would
12870 have been bound to the target @code{GL_ARRAY_BUFFER} at the time of the
12871 most recent call to @code{glSecondaryColorPointer}. If no buffer object
12872 was bound to this target, 0 is returned. The initial value is 0. See
12873 @code{glBindBuffer}.
12875 @item @code{GL_SECONDARY_COLOR_ARRAY_SIZE}
12878 @var{params} returns one value, the number of components per color in
12879 the secondary color array. The initial value is 3. See
12880 @code{glSecondaryColorPointer}.
12882 @item @code{GL_SECONDARY_COLOR_ARRAY_STRIDE}
12885 @var{params} returns one value, the byte offset between consecutive
12886 colors in the secondary color array. The initial value is 0. See
12887 @code{glSecondaryColorPointer}.
12889 @item @code{GL_SECONDARY_COLOR_ARRAY_TYPE}
12892 @var{params} returns one value, the data type of each component in the
12893 secondary color array. The initial value is @code{GL_FLOAT}. See
12894 @code{glSecondaryColorPointer}.
12896 @item @code{GL_SELECTION_BUFFER_SIZE}
12899 @var{params} return one value, the size of the selection buffer. See
12900 @code{glSelectBuffer}.
12902 @item @code{GL_SEPARABLE_2D}
12905 @var{params} returns a single boolean value indicating whether 2D
12906 separable convolution is enabled. The initial value is @code{GL_FALSE}.
12907 See @code{glSeparableFilter2D}.
12909 @item @code{GL_SHADE_MODEL}
12912 @var{params} returns one value, a symbolic constant indicating whether
12913 the shading mode is flat or smooth. The initial value is
12914 @code{GL_SMOOTH}. See @code{glShadeModel}.
12916 @item @code{GL_SMOOTH_LINE_WIDTH_RANGE}
12919 @var{params} returns two values, the smallest and largest supported
12920 widths for antialiased lines. See @code{glLineWidth}.
12922 @item @code{GL_SMOOTH_LINE_WIDTH_GRANULARITY}
12925 @var{params} returns one value, the granularity of widths for
12926 antialiased lines. See @code{glLineWidth}.
12928 @item @code{GL_SMOOTH_POINT_SIZE_RANGE}
12931 @var{params} returns two values, the smallest and largest supported
12932 widths for antialiased points. See @code{glPointSize}.
12934 @item @code{GL_SMOOTH_POINT_SIZE_GRANULARITY}
12937 @var{params} returns one value, the granularity of sizes for antialiased
12938 points. See @code{glPointSize}.
12940 @item @code{GL_STENCIL_BACK_FAIL}
12943 @var{params} returns one value, a symbolic constant indicating what
12944 action is taken for back-facing polygons when the stencil test fails.
12945 The initial value is @code{GL_KEEP}. See @code{glStencilOpSeparate}.
12947 @item @code{GL_STENCIL_BACK_FUNC}
12950 @var{params} returns one value, a symbolic constant indicating what
12951 function is used for back-facing polygons to compare the stencil
12952 reference value with the stencil buffer value. The initial value is
12953 @code{GL_ALWAYS}. See @code{glStencilFuncSeparate}.
12955 @item @code{GL_STENCIL_BACK_PASS_DEPTH_FAIL}
12958 @var{params} returns one value, a symbolic constant indicating what
12959 action is taken for back-facing polygons when the stencil test passes,
12960 but the depth test fails. The initial value is @code{GL_KEEP}. See
12961 @code{glStencilOpSeparate}.
12963 @item @code{GL_STENCIL_BACK_PASS_DEPTH_PASS}
12966 @var{params} returns one value, a symbolic constant indicating what
12967 action is taken for back-facing polygons when the stencil test passes
12968 and the depth test passes. The initial value is @code{GL_KEEP}. See
12969 @code{glStencilOpSeparate}.
12971 @item @code{GL_STENCIL_BACK_REF}
12974 @var{params} returns one value, the reference value that is compared
12975 with the contents of the stencil buffer for back-facing polygons. The
12976 initial value is 0. See @code{glStencilFuncSeparate}.
12978 @item @code{GL_STENCIL_BACK_VALUE_MASK}
12981 @var{params} returns one value, the mask that is used for back-facing
12982 polygons to mask both the stencil reference value and the stencil buffer
12983 value before they are compared. The initial value is all 1's. See
12984 @code{glStencilFuncSeparate}.
12986 @item @code{GL_STENCIL_BACK_WRITEMASK}
12989 @var{params} returns one value, the mask that controls writing of the
12990 stencil bitplanes for back-facing polygons. The initial value is all
12991 1's. See @code{glStencilMaskSeparate}.
12993 @item @code{GL_STENCIL_BITS}
12996 @var{params} returns one value, the number of bitplanes in the stencil
12999 @item @code{GL_STENCIL_CLEAR_VALUE}
13002 @var{params} returns one value, the index to which the stencil bitplanes
13003 are cleared. The initial value is 0. See @code{glClearStencil}.
13005 @item @code{GL_STENCIL_FAIL}
13008 @var{params} returns one value, a symbolic constant indicating what
13009 action is taken when the stencil test fails. The initial value is
13010 @code{GL_KEEP}. See @code{glStencilOp}. If the GL version is 2.0 or
13011 greater, this stencil state only affects non-polygons and front-facing
13012 polygons. Back-facing polygons use separate stencil state. See
13013 @code{glStencilOpSeparate}.
13015 @item @code{GL_STENCIL_FUNC}
13018 @var{params} returns one value, a symbolic constant indicating what
13019 function is used to compare the stencil reference value with the stencil
13020 buffer value. The initial value is @code{GL_ALWAYS}. See
13021 @code{glStencilFunc}. If the GL version is 2.0 or greater, this stencil
13022 state only affects non-polygons and front-facing polygons. Back-facing
13023 polygons use separate stencil state. See @code{glStencilFuncSeparate}.
13025 @item @code{GL_STENCIL_PASS_DEPTH_FAIL}
13028 @var{params} returns one value, a symbolic constant indicating what
13029 action is taken when the stencil test passes, but the depth test fails.
13030 The initial value is @code{GL_KEEP}. See @code{glStencilOp}. If the GL
13031 version is 2.0 or greater, this stencil state only affects non-polygons
13032 and front-facing polygons. Back-facing polygons use separate stencil
13033 state. See @code{glStencilOpSeparate}.
13035 @item @code{GL_STENCIL_PASS_DEPTH_PASS}
13038 @var{params} returns one value, a symbolic constant indicating what
13039 action is taken when the stencil test passes and the depth test passes.
13040 The initial value is @code{GL_KEEP}. See @code{glStencilOp}. If the GL
13041 version is 2.0 or greater, this stencil state only affects non-polygons
13042 and front-facing polygons. Back-facing polygons use separate stencil
13043 state. See @code{glStencilOpSeparate}.
13045 @item @code{GL_STENCIL_REF}
13048 @var{params} returns one value, the reference value that is compared
13049 with the contents of the stencil buffer. The initial value is 0. See
13050 @code{glStencilFunc}. If the GL version is 2.0 or greater, this stencil
13051 state only affects non-polygons and front-facing polygons. Back-facing
13052 polygons use separate stencil state. See @code{glStencilFuncSeparate}.
13054 @item @code{GL_STENCIL_TEST}
13057 @var{params} returns a single boolean value indicating whether stencil
13058 testing of fragments is enabled. The initial value is @code{GL_FALSE}.
13059 See @code{glStencilFunc} and @code{glStencilOp}.
13061 @item @code{GL_STENCIL_VALUE_MASK}
13064 @var{params} returns one value, the mask that is used to mask both the
13065 stencil reference value and the stencil buffer value before they are
13066 compared. The initial value is all 1's. See @code{glStencilFunc}. If
13067 the GL version is 2.0 or greater, this stencil state only affects
13068 non-polygons and front-facing polygons. Back-facing polygons use
13069 separate stencil state. See @code{glStencilFuncSeparate}.
13071 @item @code{GL_STENCIL_WRITEMASK}
13074 @var{params} returns one value, the mask that controls writing of the
13075 stencil bitplanes. The initial value is all 1's. See
13076 @code{glStencilMask}. If the GL version is 2.0 or greater, this stencil
13077 state only affects non-polygons and front-facing polygons. Back-facing
13078 polygons use separate stencil state. See @code{glStencilMaskSeparate}.
13080 @item @code{GL_STEREO}
13083 @var{params} returns a single boolean value indicating whether stereo
13084 buffers (left and right) are supported.
13086 @item @code{GL_SUBPIXEL_BITS}
13089 @var{params} returns one value, an estimate of the number of bits of
13090 subpixel resolution that are used to position rasterized geometry in
13091 window coordinates. The value must be at least 4.
13093 @item @code{GL_TEXTURE_1D}
13096 @var{params} returns a single boolean value indicating whether 1D
13097 texture mapping is enabled. The initial value is @code{GL_FALSE}. See
13098 @code{glTexImage1D}.
13100 @item @code{GL_TEXTURE_BINDING_1D}
13103 @var{params} returns a single value, the name of the texture currently
13104 bound to the target @code{GL_TEXTURE_1D}. The initial value is 0. See
13105 @code{glBindTexture}.
13107 @item @code{GL_TEXTURE_2D}
13110 @var{params} returns a single boolean value indicating whether 2D
13111 texture mapping is enabled. The initial value is @code{GL_FALSE}. See
13112 @code{glTexImage2D}.
13114 @item @code{GL_TEXTURE_BINDING_2D}
13117 @var{params} returns a single value, the name of the texture currently
13118 bound to the target @code{GL_TEXTURE_2D}. The initial value is 0. See
13119 @code{glBindTexture}.
13121 @item @code{GL_TEXTURE_3D}
13124 @var{params} returns a single boolean value indicating whether 3D
13125 texture mapping is enabled. The initial value is @code{GL_FALSE}. See
13126 @code{glTexImage3D}.
13128 @item @code{GL_TEXTURE_BINDING_3D}
13131 @var{params} returns a single value, the name of the texture currently
13132 bound to the target @code{GL_TEXTURE_3D}. The initial value is 0. See
13133 @code{glBindTexture}.
13135 @item @code{GL_TEXTURE_BINDING_CUBE_MAP}
13138 @var{params} returns a single value, the name of the texture currently
13139 bound to the target @code{GL_TEXTURE_CUBE_MAP}. The initial value is 0.
13140 See @code{glBindTexture}.
13142 @item @code{GL_TEXTURE_COMPRESSION_HINT}
13145 @var{params} returns a single value indicating the mode of the texture
13146 compression hint. The initial value is @code{GL_DONT_CARE}.
13148 @item @code{GL_TEXTURE_COORD_ARRAY}
13151 @var{params} returns a single boolean value indicating whether the
13152 texture coordinate array is enabled. The initial value is
13153 @code{GL_FALSE}. See @code{glTexCoordPointer}.
13155 @item @code{GL_TEXTURE_COORD_ARRAY_BUFFER_BINDING}
13158 @var{params} returns a single value, the name of the buffer object
13159 associated with the texture coordinate array. This buffer object would
13160 have been bound to the target @code{GL_ARRAY_BUFFER} at the time of the
13161 most recent call to @code{glTexCoordPointer}. If no buffer object was
13162 bound to this target, 0 is returned. The initial value is 0. See
13163 @code{glBindBuffer}.
13165 @item @code{GL_TEXTURE_COORD_ARRAY_SIZE}
13168 @var{params} returns one value, the number of coordinates per element in
13169 the texture coordinate array. The initial value is 4. See
13170 @code{glTexCoordPointer}.
13172 @item @code{GL_TEXTURE_COORD_ARRAY_STRIDE}
13175 @var{params} returns one value, the byte offset between consecutive
13176 elements in the texture coordinate array. The initial value is 0. See
13177 @code{glTexCoordPointer}.
13179 @item @code{GL_TEXTURE_COORD_ARRAY_TYPE}
13182 @var{params} returns one value, the data type of the coordinates in the
13183 texture coordinate array. The initial value is @code{GL_FLOAT}. See
13184 @code{glTexCoordPointer}.
13186 @item @code{GL_TEXTURE_CUBE_MAP}
13189 @var{params} returns a single boolean value indicating whether
13190 cube-mapped texture mapping is enabled. The initial value is
13191 @code{GL_FALSE}. See @code{glTexImage2D}.
13193 @item @code{GL_TEXTURE_GEN_Q}
13196 @var{params} returns a single boolean value indicating whether automatic
13197 generation of the @var{q} texture coordinate is enabled. The initial
13198 value is @code{GL_FALSE}. See @code{glTexGen}.
13200 @item @code{GL_TEXTURE_GEN_R}
13203 @var{params} returns a single boolean value indicating whether automatic
13204 generation of the @var{r} texture coordinate is enabled. The initial
13205 value is @code{GL_FALSE}. See @code{glTexGen}.
13207 @item @code{GL_TEXTURE_GEN_S}
13210 @var{params} returns a single boolean value indicating whether automatic
13211 generation of the @var{S} texture coordinate is enabled. The initial
13212 value is @code{GL_FALSE}. See @code{glTexGen}.
13214 @item @code{GL_TEXTURE_GEN_T}
13217 @var{params} returns a single boolean value indicating whether automatic
13218 generation of the T texture coordinate is enabled. The initial value is
13219 @code{GL_FALSE}. See @code{glTexGen}.
13221 @item @code{GL_TEXTURE_MATRIX}
13224 @var{params} returns sixteen values: the texture matrix on the top of
13225 the texture matrix stack. Initially this matrix is the identity matrix.
13226 See @code{glPushMatrix}.
13228 @item @code{GL_TEXTURE_STACK_DEPTH}
13231 @var{params} returns one value, the number of matrices on the texture
13232 matrix stack. The initial value is 1. See @code{glPushMatrix}.
13234 @item @code{GL_TRANSPOSE_COLOR_MATRIX}
13237 @var{params} returns 16 values, the elements of the color matrix in
13238 row-major order. See @code{glLoadTransposeMatrix}.
13240 @item @code{GL_TRANSPOSE_MODELVIEW_MATRIX}
13243 @var{params} returns 16 values, the elements of the modelview matrix in
13244 row-major order. See @code{glLoadTransposeMatrix}.
13246 @item @code{GL_TRANSPOSE_PROJECTION_MATRIX}
13249 @var{params} returns 16 values, the elements of the projection matrix in
13250 row-major order. See @code{glLoadTransposeMatrix}.
13252 @item @code{GL_TRANSPOSE_TEXTURE_MATRIX}
13255 @var{params} returns 16 values, the elements of the texture matrix in
13256 row-major order. See @code{glLoadTransposeMatrix}.
13258 @item @code{GL_UNPACK_ALIGNMENT}
13261 @var{params} returns one value, the byte alignment used for reading
13262 pixel data from memory. The initial value is 4. See
13263 @code{glPixelStore}.
13265 @item @code{GL_UNPACK_IMAGE_HEIGHT}
13268 @var{params} returns one value, the image height used for reading pixel
13269 data from memory. The initial is 0. See @code{glPixelStore}.
13271 @item @code{GL_UNPACK_LSB_FIRST}
13274 @var{params} returns a single boolean value indicating whether
13275 single-bit pixels being read from memory are read first from the least
13276 significant bit of each unsigned byte. The initial value is
13277 @code{GL_FALSE}. See @code{glPixelStore}.
13279 @item @code{GL_UNPACK_ROW_LENGTH}
13282 @var{params} returns one value, the row length used for reading pixel
13283 data from memory. The initial value is 0. See @code{glPixelStore}.
13285 @item @code{GL_UNPACK_SKIP_IMAGES}
13288 @var{params} returns one value, the number of pixel images skipped
13289 before the first pixel is read from memory. The initial value is 0. See
13290 @code{glPixelStore}.
13292 @item @code{GL_UNPACK_SKIP_PIXELS}
13295 @var{params} returns one value, the number of pixel locations skipped
13296 before the first pixel is read from memory. The initial value is 0. See
13297 @code{glPixelStore}.
13299 @item @code{GL_UNPACK_SKIP_ROWS}
13302 @var{params} returns one value, the number of rows of pixel locations
13303 skipped before the first pixel is read from memory. The initial value
13304 is 0. See @code{glPixelStore}.
13306 @item @code{GL_UNPACK_SWAP_BYTES}
13309 @var{params} returns a single boolean value indicating whether the bytes
13310 of two-byte and four-byte pixel indices and components are swapped after
13311 being read from memory. The initial value is @code{GL_FALSE}. See
13312 @code{glPixelStore}.
13314 @item @code{GL_VERTEX_ARRAY}
13317 @var{params} returns a single boolean value indicating whether the
13318 vertex array is enabled. The initial value is @code{GL_FALSE}. See
13319 @code{glVertexPointer}.
13321 @item @code{GL_VERTEX_ARRAY_BUFFER_BINDING}
13324 @var{params} returns a single value, the name of the buffer object
13325 associated with the vertex array. This buffer object would have been
13326 bound to the target @code{GL_ARRAY_BUFFER} at the time of the most
13327 recent call to @code{glVertexPointer}. If no buffer object was bound to
13328 this target, 0 is returned. The initial value is 0. See
13329 @code{glBindBuffer}.
13331 @item @code{GL_VERTEX_ARRAY_SIZE}
13334 @var{params} returns one value, the number of coordinates per vertex in
13335 the vertex array. The initial value is 4. See @code{glVertexPointer}.
13337 @item @code{GL_VERTEX_ARRAY_STRIDE}
13340 @var{params} returns one value, the byte offset between consecutive
13341 vertices in the vertex array. The initial value is 0. See
13342 @code{glVertexPointer}.
13344 @item @code{GL_VERTEX_ARRAY_TYPE}
13347 @var{params} returns one value, the data type of each coordinate in the
13348 vertex array. The initial value is @code{GL_FLOAT}. See
13349 @code{glVertexPointer}.
13351 @item @code{GL_VERTEX_PROGRAM_POINT_SIZE}
13354 @var{params} returns a single boolean value indicating whether vertex
13355 program point size mode is enabled. If enabled, and a vertex shader is
13356 active, then the point size is taken from the shader built-in
13357 @code{gl_PointSize}. If disabled, and a vertex shader is active, then
13358 the point size is taken from the point state as specified by
13359 @code{glPointSize}. The initial value is @code{GL_FALSE}.
13361 @item @code{GL_VERTEX_PROGRAM_TWO_SIDE}
13364 @var{params} returns a single boolean value indicating whether vertex
13365 program two-sided color mode is enabled. If enabled, and a vertex
13366 shader is active, then the GL chooses the back color output for
13367 back-facing polygons, and the front color output for non-polygons and
13368 front-facing polygons. If disabled, and a vertex shader is active, then
13369 the front color output is always selected. The initial value is
13372 @item @code{GL_VIEWPORT}
13375 @var{params} returns four values: the @r{@var{x}} and @r{@var{y}} window
13376 coordinates of the viewport, followed by its width and height. Initially
13377 the @r{@var{x}} and @r{@var{y}} window coordinates are both set to 0,
13378 and the width and height are set to the width and height of the window
13379 into which the GL will do its rendering. See @code{glViewport}.
13381 @item @code{GL_ZOOM_X}
13384 @var{params} returns one value, the @r{@var{x}} pixel zoom factor. The
13385 initial value is 1. See @code{glPixelZoom}.
13387 @item @code{GL_ZOOM_Y}
13390 @var{params} returns one value, the @r{@var{y}} pixel zoom factor. The
13391 initial value is 1. See @code{glPixelZoom}.
13395 Many of the boolean parameters can also be queried more easily using
13396 @code{glIsEnabled}.
13398 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
13401 @code{GL_INVALID_OPERATION} is generated if @code{glGet} is executed
13402 between the execution of @code{glBegin} and the corresponding execution
13409 @deftypefun void glHint target mode
13410 Specify implementation-specific hints.
13414 Specifies a symbolic constant indicating the behavior to be controlled.
13415 @code{GL_FOG_HINT}, @code{GL_GENERATE_MIPMAP_HINT},
13416 @code{GL_LINE_SMOOTH_HINT}, @code{GL_PERSPECTIVE_CORRECTION_HINT},
13417 @code{GL_POINT_SMOOTH_HINT}, @code{GL_POLYGON_SMOOTH_HINT},
13418 @code{GL_TEXTURE_COMPRESSION_HINT}, and
13419 @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT} are accepted.
13422 Specifies a symbolic constant indicating the desired behavior.
13423 @code{GL_FASTEST}, @code{GL_NICEST}, and @code{GL_DONT_CARE} are
13428 Certain aspects of GL behavior, when there is room for interpretation,
13429 can be controlled with hints. A hint is specified with two arguments.
13430 @var{target} is a symbolic constant indicating the behavior to be
13431 controlled, and @var{mode} is another symbolic constant indicating the
13432 desired behavior. The initial value for each @var{target} is
13433 @code{GL_DONT_CARE}. @var{mode} can be one of the following:
13436 @item @code{GL_FASTEST}
13439 The most efficient option should be chosen.
13441 @item @code{GL_NICEST}
13444 The most correct, or highest quality, option should be chosen.
13446 @item @code{GL_DONT_CARE}
13453 Though the implementation aspects that can be hinted are well defined,
13454 the interpretation of the hints depends on the implementation. The hint
13455 aspects that can be specified with @var{target}, along with suggested
13456 semantics, are as follows:
13459 @item @code{GL_FOG_HINT}
13462 Indicates the accuracy of fog calculation. If per-pixel fog calculation
13463 is not efficiently supported by the GL implementation, hinting
13464 @code{GL_DONT_CARE} or @code{GL_FASTEST} can result in per-vertex
13465 calculation of fog effects.
13467 @item @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT}
13470 Indicates the accuracy of the derivative calculation for the GL shading
13471 language fragment processing built-in functions: @code{dFdx},
13472 @code{dFdy}, and @code{fwidth}.
13474 @item @code{GL_GENERATE_MIPMAP_HINT}
13477 Indicates the quality of filtering when generating mipmap images.
13479 @item @code{GL_LINE_SMOOTH_HINT}
13482 Indicates the sampling quality of antialiased lines. If a larger filter
13483 function is applied, hinting @code{GL_NICEST} can result in more pixel
13484 fragments being generated during rasterization.
13486 @item @code{GL_PERSPECTIVE_CORRECTION_HINT}
13489 Indicates the quality of color, texture coordinate, and fog coordinate
13490 interpolation. If perspective-corrected parameter interpolation is not
13491 efficiently supported by the GL implementation, hinting
13492 @code{GL_DONT_CARE} or @code{GL_FASTEST} can result in simple linear
13493 interpolation of colors and/or texture coordinates.
13495 @item @code{GL_POINT_SMOOTH_HINT}
13498 Indicates the sampling quality of antialiased points. If a larger
13499 filter function is applied, hinting @code{GL_NICEST} can result in more
13500 pixel fragments being generated during rasterization.
13502 @item @code{GL_POLYGON_SMOOTH_HINT}
13505 Indicates the sampling quality of antialiased polygons. Hinting
13506 @code{GL_NICEST} can result in more pixel fragments being generated
13507 during rasterization, if a larger filter function is applied.
13509 @item @code{GL_TEXTURE_COMPRESSION_HINT}
13512 Indicates the quality and performance of the compressing texture images.
13513 Hinting @code{GL_FASTEST} indicates that texture images should be
13514 compressed as quickly as possible, while @code{GL_NICEST} indicates that
13515 texture images should be compressed with as little image quality loss as
13516 possible. @code{GL_NICEST} should be selected if the texture is to be
13517 retrieved by @code{glGetCompressedTexImage} for reuse.
13521 @code{GL_INVALID_ENUM} is generated if either @var{target} or @var{mode}
13522 is not an accepted value.
13524 @code{GL_INVALID_OPERATION} is generated if @code{glHint} is executed
13525 between the execution of @code{glBegin} and the corresponding execution
13530 @deftypefun void glHistogram target width internalformat sink
13531 Define histogram table.
13535 The histogram whose parameters are to be set. Must be one of
13536 @code{GL_HISTOGRAM} or @code{GL_PROXY_HISTOGRAM}.
13539 The number of entries in the histogram table. Must be a power of 2.
13541 @item @var{internalformat}
13542 The format of entries in the histogram table. Must be one of
13543 @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
13544 @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
13545 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
13546 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
13547 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
13548 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
13549 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
13550 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
13551 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
13552 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
13553 @code{GL_RGBA12}, or @code{GL_RGBA16}.
13556 If @code{GL_TRUE}, pixels will be consumed by the histogramming process
13557 and no drawing or texture loading will take place. If @code{GL_FALSE},
13558 pixels will proceed to the minmax process after histogramming.
13562 When @code{GL_HISTOGRAM} is enabled, RGBA color components are converted
13563 to histogram table indices by clamping to the range [0,1], multiplying
13564 by the width of the histogram table, and rounding to the nearest
13565 integer. The table entries selected by the RGBA indices are then
13566 incremented. (If the internal format of the histogram table includes
13567 luminance, then the index derived from the R color component determines
13568 the luminance table entry to be incremented.) If a histogram table entry
13569 is incremented beyond its maximum value, then its value becomes
13570 undefined. (This is not an error.)
13572 Histogramming is performed only for RGBA pixels (though these may be
13573 specified originally as color indices and converted to RGBA by index
13574 table lookup). Histogramming is enabled with @code{glEnable} and
13575 disabled with @code{glDisable}.
13577 When @var{target} is @code{GL_HISTOGRAM}, @code{glHistogram} redefines
13578 the current histogram table to have @var{width} entries of the format
13579 specified by @var{internalformat}. The entries are indexed 0 through
13580 @r{@var{width}-1}, and all entries are initialized to zero. The values
13581 in the previous histogram table, if any, are lost. If @var{sink} is
13582 @code{GL_TRUE}, then pixels are discarded after histogramming; no
13583 further processing of the pixels takes place, and no drawing, texture
13584 loading, or pixel readback will result.
13586 When @var{target} is @code{GL_PROXY_HISTOGRAM}, @code{glHistogram}
13587 computes all state information as if the histogram table were to be
13588 redefined, but does not actually define the new table. If the requested
13589 histogram table is too large to be supported, then the state information
13590 will be set to zero. This provides a way to determine if a histogram
13591 table with the given parameters can be supported.
13595 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
13598 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
13599 is not a power of 2.
13601 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
13602 of the allowable values.
13604 @code{GL_TABLE_TOO_LARGE} is generated if @var{target} is
13605 @code{GL_HISTOGRAM} and the histogram table specified is too large for
13606 the implementation.
13608 @code{GL_INVALID_OPERATION} is generated if @code{glHistogram} is
13609 executed between the execution of @code{glBegin} and the corresponding
13610 execution of @code{glEnd}.
13614 @deftypefun void glIndexMask mask
13615 Control the writing of individual bits in the color index buffers.
13619 Specifies a bit mask to enable and disable the writing of individual
13620 bits in the color index buffers. Initially, the mask is all 1's.
13624 @code{glIndexMask} controls the writing of individual bits in the color
13625 index buffers. The least significant @r{@var{n}} bits of @var{mask},
13626 where @r{@var{n}} is the number of bits in a color index buffer, specify
13627 a mask. Where a 1 (one) appears in the mask, it's possible to write to
13628 the corresponding bit in the color index buffer (or buffers). Where a 0
13629 (zero) appears, the corresponding bit is write-protected.
13631 This mask is used only in color index mode, and it affects only the
13632 buffers currently selected for writing (see @code{glDrawBuffer}).
13633 Initially, all bits are enabled for writing.
13635 @code{GL_INVALID_OPERATION} is generated if @code{glIndexMask} is
13636 executed between the execution of @code{glBegin} and the corresponding
13637 execution of @code{glEnd}.
13641 @deftypefun void glIndexPointer type stride pointer
13642 Define an array of color indexes.
13646 Specifies the data type of each color index in the array. Symbolic
13647 constants @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, @code{GL_INT},
13648 @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value
13649 is @code{GL_FLOAT}.
13652 Specifies the byte offset between consecutive color indexes. If
13653 @var{stride} is 0, the color indexes are understood to be tightly packed
13654 in the array. The initial value is 0.
13656 @item @var{pointer}
13657 Specifies a pointer to the first index in the array. The initial value
13662 @code{glIndexPointer} specifies the location and data format of an array
13663 of color indexes to use when rendering. @var{type} specifies the data
13664 type of each color index and @var{stride} specifies the byte stride from
13665 one color index to the next, allowing vertices and attributes to be
13666 packed into a single array or stored in separate arrays.
13668 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
13669 target (see @code{glBindBuffer}) while a color index array is specified,
13670 @var{pointer} is treated as a byte offset into the buffer object's data
13671 store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING})
13672 is saved as color index vertex array client-side state
13673 (@code{GL_INDEX_ARRAY_BUFFER_BINDING}).
13675 When a color index array is specified, @var{type}, @var{stride}, and
13676 @var{pointer} are saved as client-side state, in addition to the current
13677 vertex array buffer object binding.
13679 To enable and disable the color index array, call
13680 @code{glEnableClientState} and @code{glDisableClientState} with the
13681 argument @code{GL_INDEX_ARRAY}. If enabled, the color index array is
13682 used when @code{glDrawArrays}, @code{glMultiDrawArrays},
13683 @code{glDrawElements}, @code{glMultiDrawElements},
13684 @code{glDrawRangeElements}, or @code{glArrayElement} is called.
13686 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
13689 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
13693 @deftypefun void glIndexs c
13694 @deftypefunx void glIndexi c
13695 @deftypefunx void glIndexf c
13696 @deftypefunx void glIndexd c
13697 @deftypefunx void glIndexub c
13698 @deftypefunx void glIndexsv c
13699 @deftypefunx void glIndexiv c
13700 @deftypefunx void glIndexfv c
13701 @deftypefunx void glIndexdv c
13702 @deftypefunx void glIndexubv c
13703 Set the current color index.
13707 Specifies the new value for the current color index.
13713 @code{glIndex} updates the current (single-valued) color index. It
13714 takes one argument, the new value for the current color index.
13716 The current index is stored as a floating-point value. Integer values
13717 are converted directly to floating-point values, with no special
13718 mapping. The initial value is 1.
13720 Index values outside the representable range of the color index buffer
13721 are not clamped. However, before an index is dithered (if enabled) and
13722 written to the frame buffer, it is converted to fixed-point format. Any
13723 bits in the integer portion of the resulting fixed-point value that do
13724 not correspond to bits in the frame buffer are masked out.
13728 @deftypefun void glInitNames
13729 Initialize the name stack.
13731 The name stack is used during selection mode to allow sets of rendering
13732 commands to be uniquely identified. It consists of an ordered set of
13733 unsigned integers. @code{glInitNames} causes the name stack to be
13734 initialized to its default empty state.
13736 The name stack is always empty while the render mode is not
13737 @code{GL_SELECT}. Calls to @code{glInitNames} while the render mode is
13738 not @code{GL_SELECT} are ignored.
13740 @code{GL_INVALID_OPERATION} is generated if @code{glInitNames} is
13741 executed between the execution of @code{glBegin} and the corresponding
13742 execution of @code{glEnd}.
13746 @deftypefun void glInterleavedArrays format stride pointer
13747 Simultaneously specify and enable several interleaved arrays.
13751 Specifies the type of array to enable. Symbolic constants
13752 @code{GL_V2F}, @code{GL_V3F}, @code{GL_C4UB_V2F}, @code{GL_C4UB_V3F},
13753 @code{GL_C3F_V3F}, @code{GL_N3F_V3F}, @code{GL_C4F_N3F_V3F},
13754 @code{GL_T2F_V3F}, @code{GL_T4F_V4F}, @code{GL_T2F_C4UB_V3F},
13755 @code{GL_T2F_C3F_V3F}, @code{GL_T2F_N3F_V3F}, @code{GL_T2F_C4F_N3F_V3F},
13756 and @code{GL_T4F_C4F_N3F_V4F} are accepted.
13759 Specifies the offset in bytes between each aggregate array element.
13763 @code{glInterleavedArrays} lets you specify and enable individual color,
13764 normal, texture and vertex arrays whose elements are part of a larger
13765 aggregate array element. For some implementations, this is more
13766 efficient than specifying the arrays separately.
13768 If @var{stride} is 0, the aggregate elements are stored consecutively.
13769 Otherwise, @var{stride} bytes occur between the beginning of one
13770 aggregate array element and the beginning of the next aggregate array
13773 @var{format} serves as a ``key'' describing the extraction of individual
13774 arrays from the aggregate array. If @var{format} contains a T, then
13775 texture coordinates are extracted from the interleaved array. If C is
13776 present, color values are extracted. If N is present, normal
13777 coordinates are extracted. Vertex coordinates are always extracted.
13779 The digits 2, 3, and 4 denote how many values are extracted. F
13780 indicates that values are extracted as floating-point values. Colors
13781 may also be extracted as 4 unsigned bytes if 4UB follows the C. If a
13782 color is extracted as 4 unsigned bytes, the vertex array element which
13783 follows is located at the first possible floating-point aligned address.
13785 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
13788 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
13792 @deftypefun GLboolean glIsBuffer buffer
13793 Determine if a name corresponds to a buffer object.
13797 Specifies a value that may be the name of a buffer object.
13801 @code{glIsBuffer} returns @code{GL_TRUE} if @var{buffer} is currently
13802 the name of a buffer object. If @var{buffer} is zero, or is a non-zero
13803 value that is not currently the name of a buffer object, or if an error
13804 occurs, @code{glIsBuffer} returns @code{GL_FALSE}.
13806 A name returned by @code{glGenBuffers}, but not yet associated with a
13807 buffer object by calling @code{glBindBuffer}, is not the name of a
13810 @code{GL_INVALID_OPERATION} is generated if @code{glIsBuffer} is
13811 executed between the execution of @code{glBegin} and the corresponding
13812 execution of @code{glEnd}.
13816 @deftypefun GLboolean glIsEnabled cap
13817 Test whether a capability is enabled.
13821 Specifies a symbolic constant indicating a GL capability.
13825 @code{glIsEnabled} returns @code{GL_TRUE} if @var{cap} is an enabled
13826 capability and returns @code{GL_FALSE} otherwise. Initially all
13827 capabilities except @code{GL_DITHER} are disabled; @code{GL_DITHER} is
13830 The following capabilities are accepted for @var{cap}:
13835 @item @strong{Constant}
13838 @item @code{GL_ALPHA_TEST}
13841 @item @code{GL_AUTO_NORMAL}
13844 @item @code{GL_BLEND}
13845 @code{glBlendFunc}, @code{glLogicOp}
13847 @item @code{GL_CLIP_PLANE}@var{i}
13850 @item @code{GL_COLOR_ARRAY}
13851 @code{glColorPointer}
13853 @item @code{GL_COLOR_LOGIC_OP}
13856 @item @code{GL_COLOR_MATERIAL}
13857 @code{glColorMaterial}
13859 @item @code{GL_COLOR_SUM}
13860 @code{glSecondaryColor}
13862 @item @code{GL_COLOR_TABLE}
13863 @code{glColorTable}
13865 @item @code{GL_CONVOLUTION_1D}
13866 @code{glConvolutionFilter1D}
13868 @item @code{GL_CONVOLUTION_2D}
13869 @code{glConvolutionFilter2D}
13871 @item @code{GL_CULL_FACE}
13874 @item @code{GL_DEPTH_TEST}
13875 @code{glDepthFunc}, @code{glDepthRange}
13877 @item @code{GL_DITHER}
13880 @item @code{GL_EDGE_FLAG_ARRAY}
13881 @code{glEdgeFlagPointer}
13883 @item @code{GL_FOG}
13886 @item @code{GL_FOG_COORD_ARRAY}
13887 @code{glFogCoordPointer}
13889 @item @code{GL_HISTOGRAM}
13892 @item @code{GL_INDEX_ARRAY}
13893 @code{glIndexPointer}
13895 @item @code{GL_INDEX_LOGIC_OP}
13898 @item @code{GL_LIGHT}@var{i}
13899 @code{glLightModel}, @code{glLight}
13901 @item @code{GL_LIGHTING}
13902 @code{glMaterial}, @code{glLightModel}, @code{glLight}
13904 @item @code{GL_LINE_SMOOTH}
13907 @item @code{GL_LINE_STIPPLE}
13908 @code{glLineStipple}
13910 @item @code{GL_MAP1_COLOR_4}
13913 @item @code{GL_MAP1_INDEX}
13916 @item @code{GL_MAP1_NORMAL}
13919 @item @code{GL_MAP1_TEXTURE_COORD_1}
13922 @item @code{GL_MAP1_TEXTURE_COORD_2}
13925 @item @code{GL_MAP1_TEXTURE_COORD_3}
13928 @item @code{GL_MAP1_TEXTURE_COORD_4}
13931 @item @code{GL_MAP2_COLOR_4}
13934 @item @code{GL_MAP2_INDEX}
13937 @item @code{GL_MAP2_NORMAL}
13940 @item @code{GL_MAP2_TEXTURE_COORD_1}
13943 @item @code{GL_MAP2_TEXTURE_COORD_2}
13946 @item @code{GL_MAP2_TEXTURE_COORD_3}
13949 @item @code{GL_MAP2_TEXTURE_COORD_4}
13952 @item @code{GL_MAP2_VERTEX_3}
13955 @item @code{GL_MAP2_VERTEX_4}
13958 @item @code{GL_MINMAX}
13961 @item @code{GL_MULTISAMPLE}
13962 @code{glSampleCoverage}
13964 @item @code{GL_NORMAL_ARRAY}
13965 @code{glNormalPointer}
13967 @item @code{GL_NORMALIZE}
13970 @item @code{GL_POINT_SMOOTH}
13973 @item @code{GL_POINT_SPRITE}
13976 @item @code{GL_POLYGON_SMOOTH}
13977 @code{glPolygonMode}
13979 @item @code{GL_POLYGON_OFFSET_FILL}
13980 @code{glPolygonOffset}
13982 @item @code{GL_POLYGON_OFFSET_LINE}
13983 @code{glPolygonOffset}
13985 @item @code{GL_POLYGON_OFFSET_POINT}
13986 @code{glPolygonOffset}
13988 @item @code{GL_POLYGON_STIPPLE}
13989 @code{glPolygonStipple}
13991 @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}
13992 @code{glColorTable}
13994 @item @code{GL_POST_CONVOLUTION_COLOR_TABLE}
13995 @code{glColorTable}
13997 @item @code{GL_RESCALE_NORMAL}
14000 @item @code{GL_SAMPLE_ALPHA_TO_COVERAGE}
14001 @code{glSampleCoverage}
14003 @item @code{GL_SAMPLE_ALPHA_TO_ONE}
14004 @code{glSampleCoverage}
14006 @item @code{GL_SAMPLE_COVERAGE}
14007 @code{glSampleCoverage}
14009 @item @code{GL_SCISSOR_TEST}
14012 @item @code{GL_SECONDARY_COLOR_ARRAY}
14013 @code{glSecondaryColorPointer}
14015 @item @code{GL_SEPARABLE_2D}
14016 @code{glSeparableFilter2D}
14018 @item @code{GL_STENCIL_TEST}
14019 @code{glStencilFunc}, @code{glStencilOp}
14021 @item @code{GL_TEXTURE_1D}
14022 @code{glTexImage1D}
14024 @item @code{GL_TEXTURE_2D}
14025 @code{glTexImage2D}
14027 @item @code{GL_TEXTURE_3D}
14028 @code{glTexImage3D}
14030 @item @code{GL_TEXTURE_COORD_ARRAY}
14031 @code{glTexCoordPointer}
14033 @item @code{GL_TEXTURE_CUBE_MAP}
14034 @code{glTexImage2D}
14036 @item @code{GL_TEXTURE_GEN_Q}
14039 @item @code{GL_TEXTURE_GEN_R}
14042 @item @code{GL_TEXTURE_GEN_S}
14045 @item @code{GL_TEXTURE_GEN_T}
14048 @item @code{GL_VERTEX_ARRAY}
14049 @code{glVertexPointer}
14051 @item @code{GL_VERTEX_PROGRAM_POINT_SIZE}
14054 @item @code{GL_VERTEX_PROGRAM_TWO_SIDE}
14061 @code{GL_INVALID_ENUM} is generated if @var{cap} is not an accepted
14064 @code{GL_INVALID_OPERATION} is generated if @code{glIsEnabled} is
14065 executed between the execution of @code{glBegin} and the corresponding
14066 execution of @code{glEnd}.
14070 @deftypefun GLboolean glIsList list
14071 Determine if a name corresponds to a display list.
14075 Specifies a potential display list name.
14079 @code{glIsList} returns @code{GL_TRUE} if @var{list} is the name of a
14080 display list and returns @code{GL_FALSE} if it is not, or if an error
14083 A name returned by @code{glGenLists}, but not yet associated with a
14084 display list by calling @code{glNewList}, is not the name of a display
14087 @code{GL_INVALID_OPERATION} is generated if @code{glIsList} is executed
14088 between the execution of @code{glBegin} and the corresponding execution
14093 @deftypefun GLboolean glIsProgram program
14094 Determines if a name corresponds to a program object.
14097 @item @var{program}
14098 Specifies a potential program object.
14102 @code{glIsProgram} returns @code{GL_TRUE} if @var{program} is the name
14103 of a program object previously created with @code{glCreateProgram} and
14104 not yet deleted with @code{glDeleteProgram}. If @var{program} is zero
14105 or a non-zero value that is not the name of a program object, or if an
14106 error occurs, @code{glIsProgram} returns @code{GL_FALSE}.
14108 @code{GL_INVALID_OPERATION} is generated if @code{glIsProgram} is
14109 executed between the execution of @code{glBegin} and the corresponding
14110 execution of @code{glEnd}.
14114 @deftypefun GLboolean glIsQuery id
14115 Determine if a name corresponds to a query object.
14119 Specifies a value that may be the name of a query object.
14123 @code{glIsQuery} returns @code{GL_TRUE} if @var{id} is currently the
14124 name of a query object. If @var{id} is zero, or is a non-zero value
14125 that is not currently the name of a query object, or if an error occurs,
14126 @code{glIsQuery} returns @code{GL_FALSE}.
14128 A name returned by @code{glGenQueries}, but not yet associated with a
14129 query object by calling @code{glBeginQuery}, is not the name of a query
14132 @code{GL_INVALID_OPERATION} is generated if @code{glIsQuery} is executed
14133 between the execution of @code{glBegin} and the corresponding execution
14138 @deftypefun GLboolean glIsShader shader
14139 Determines if a name corresponds to a shader object.
14143 Specifies a potential shader object.
14147 @code{glIsShader} returns @code{GL_TRUE} if @var{shader} is the name of
14148 a shader object previously created with @code{glCreateShader} and not
14149 yet deleted with @code{glDeleteShader}. If @var{shader} is zero or a
14150 non-zero value that is not the name of a shader object, or if an error
14151 occurs, @code{glIsShader } returns @code{GL_FALSE}.
14153 @code{GL_INVALID_OPERATION} is generated if @code{glIsShader} is
14154 executed between the execution of @code{glBegin} and the corresponding
14155 execution of @code{glEnd}.
14159 @deftypefun GLboolean glIsTexture texture
14160 Determine if a name corresponds to a texture.
14163 @item @var{texture}
14164 Specifies a value that may be the name of a texture.
14168 @code{glIsTexture} returns @code{GL_TRUE} if @var{texture} is currently
14169 the name of a texture. If @var{texture} is zero, or is a non-zero value
14170 that is not currently the name of a texture, or if an error occurs,
14171 @code{glIsTexture} returns @code{GL_FALSE}.
14173 A name returned by @code{glGenTextures}, but not yet associated with a
14174 texture by calling @code{glBindTexture}, is not the name of a texture.
14176 @code{GL_INVALID_OPERATION} is generated if @code{glIsTexture} is
14177 executed between the execution of @code{glBegin} and the corresponding
14178 execution of @code{glEnd}.
14182 @deftypefun void glLightModelf pname param
14183 @deftypefunx void glLightModeli pname param
14184 @deftypefunx void glLightModelfv pname params
14185 @deftypefunx void glLightModeliv pname params
14186 Set the lighting model parameters.
14190 Specifies a single-valued lighting model parameter.
14191 @code{GL_LIGHT_MODEL_LOCAL_VIEWER}, @code{GL_LIGHT_MODEL_COLOR_CONTROL},
14192 and @code{GL_LIGHT_MODEL_TWO_SIDE} are accepted.
14195 Specifies the value that @var{param} will be set to.
14199 @code{glLightModel} sets the lighting model parameter. @var{pname}
14200 names a parameter and @var{params} gives the new value. There are three
14201 lighting model parameters:
14204 @item @code{GL_LIGHT_MODEL_AMBIENT}
14207 @var{params} contains four integer or floating-point values that specify
14208 the ambient RGBA intensity of the entire scene. Integer values are
14209 mapped linearly such that the most positive representable value maps to
14210 1.0, and the most negative representable value maps to @r{-1.0}.
14211 Floating-point values are mapped directly. Neither integer nor
14212 floating-point values are clamped. The initial ambient scene intensity
14213 is (0.2, 0.2, 0.2, 1.0).
14215 @item @code{GL_LIGHT_MODEL_COLOR_CONTROL}
14218 @var{params} must be either @code{GL_SEPARATE_SPECULAR_COLOR} or
14219 @code{GL_SINGLE_COLOR}. @code{GL_SINGLE_COLOR} specifies that a single
14220 color is generated from the lighting computation for a vertex.
14221 @code{GL_SEPARATE_SPECULAR_COLOR} specifies that the specular color
14222 computation of lighting be stored separately from the remainder of the
14223 lighting computation. The specular color is summed into the generated
14224 fragment's color after the application of texture mapping (if enabled).
14225 The initial value is @code{GL_SINGLE_COLOR}.
14227 @item @code{GL_LIGHT_MODEL_LOCAL_VIEWER}
14230 @var{params} is a single integer or floating-point value that specifies
14231 how specular reflection angles are computed. If @var{params} is 0 (or
14232 0.0), specular reflection angles take the view direction to be parallel
14233 to and in the direction of the -@var{z} axis, regardless of the location
14234 of the vertex in eye coordinates. Otherwise, specular reflections are
14235 computed from the origin of the eye coordinate system. The initial
14238 @item @code{GL_LIGHT_MODEL_TWO_SIDE}
14241 @var{params} is a single integer or floating-point value that specifies
14242 whether one- or two-sided lighting calculations are done for polygons.
14243 It has no effect on the lighting calculations for points, lines, or
14244 bitmaps. If @var{params} is 0 (or 0.0), one-sided lighting is
14245 specified, and only the @var{front} material parameters are used in the
14246 lighting equation. Otherwise, two-sided lighting is specified. In this
14247 case, vertices of back-facing polygons are lighted using the @var{back}
14248 material parameters and have their normals reversed before the lighting
14249 equation is evaluated. Vertices of front-facing polygons are always
14250 lighted using the @var{front} material parameters, with no change to
14251 their normals. The initial value is 0.
14255 In RGBA mode, the lighted color of a vertex is the sum of the material
14256 emission intensity, the product of the material ambient reflectance and
14257 the lighting model full-scene ambient intensity, and the contribution of
14258 each enabled light source. Each light source contributes the sum of
14259 three terms: ambient, diffuse, and specular. The ambient light source
14260 contribution is the product of the material ambient reflectance and the
14261 light's ambient intensity. The diffuse light source contribution is the
14262 product of the material diffuse reflectance, the light's diffuse
14263 intensity, and the dot product of the vertex's normal with the
14264 normalized vector from the vertex to the light source. The specular
14265 light source contribution is the product of the material specular
14266 reflectance, the light's specular intensity, and the dot product of the
14267 normalized vertex-to-eye and vertex-to-light vectors, raised to the
14268 power of the shininess of the material. All three light source
14269 contributions are attenuated equally based on the distance from the
14270 vertex to the light source and on light source direction, spread
14271 exponent, and spread cutoff angle. All dot products are replaced with 0
14272 if they evaluate to a negative value.
14274 The alpha component of the resulting lighted color is set to the alpha
14275 value of the material diffuse reflectance.
14277 In color index mode, the value of the lighted index of a vertex ranges
14278 from the ambient to the specular values passed to @code{glMaterial}
14279 using @code{GL_COLOR_INDEXES}. Diffuse and specular coefficients,
14280 computed with a (.30, .59, .11) weighting of the lights' colors, the
14281 shininess of the material, and the same reflection and attenuation
14282 equations as in the RGBA case, determine how much above ambient the
14283 resulting index is.
14285 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
14288 @code{GL_INVALID_ENUM} is generated if @var{pname} is
14289 @code{GL_LIGHT_MODEL_COLOR_CONTROL} and @var{params} is not one of
14290 @code{GL_SINGLE_COLOR} or @code{GL_SEPARATE_SPECULAR_COLOR}.
14292 @code{GL_INVALID_OPERATION} is generated if @code{glLightModel} is
14293 executed between the execution of @code{glBegin} and the corresponding
14294 execution of @code{glEnd}.
14298 @deftypefun void glLightf light pname param
14299 @deftypefunx void glLighti light pname param
14300 @deftypefunx void glLightfv light pname params
14301 @deftypefunx void glLightiv light pname params
14302 Set light source parameters.
14306 Specifies a light. The number of lights depends on the implementation,
14307 but at least eight lights are supported. They are identified by
14308 symbolic names of the form @code{GL_LIGHT}@r{@var{i}}, where i ranges
14309 from 0 to the value of @code{GL_MAX_LIGHTS} - 1.
14312 Specifies a single-valued light source parameter for @var{light}.
14313 @code{GL_SPOT_EXPONENT}, @code{GL_SPOT_CUTOFF},
14314 @code{GL_CONSTANT_ATTENUATION}, @code{GL_LINEAR_ATTENUATION}, and
14315 @code{GL_QUADRATIC_ATTENUATION} are accepted.
14318 Specifies the value that parameter @var{pname} of light source
14319 @var{light} will be set to.
14323 @code{glLight} sets the values of individual light source parameters.
14324 @var{light} names the light and is a symbolic name of the form
14325 @code{GL_LIGHT}@r{@var{i}}, where i ranges from 0 to the value of
14326 @code{GL_MAX_LIGHTS} - 1. @var{pname} specifies one of ten light source
14327 parameters, again by symbolic name. @var{params} is either a single
14328 value or a pointer to an array that contains the new values.
14330 To enable and disable lighting calculation, call @code{glEnable} and
14331 @code{glDisable} with argument @code{GL_LIGHTING}. Lighting is
14332 initially disabled. When it is enabled, light sources that are enabled
14333 contribute to the lighting calculation. Light source @r{@var{i}} is
14334 enabled and disabled using @code{glEnable} and @code{glDisable} with
14335 argument @code{GL_LIGHT}@r{@var{i}}.
14337 The ten light parameters are as follows:
14340 @item @code{GL_AMBIENT}
14341 @var{params} contains four integer or floating-point values that specify
14342 the ambient RGBA intensity of the light. Integer values are mapped
14343 linearly such that the most positive representable value maps to 1.0,
14344 and the most negative representable value maps to @r{-1.0}.
14345 Floating-point values are mapped directly. Neither integer nor
14346 floating-point values are clamped. The initial ambient light intensity
14349 @item @code{GL_DIFFUSE}
14350 @var{params} contains four integer or floating-point values that specify
14351 the diffuse RGBA intensity of the light. Integer values are mapped
14352 linearly such that the most positive representable value maps to 1.0,
14353 and the most negative representable value maps to @r{-1.0}.
14354 Floating-point values are mapped directly. Neither integer nor
14355 floating-point values are clamped. The initial value for
14356 @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial value is
14359 @item @code{GL_SPECULAR}
14360 @var{params} contains four integer or floating-point values that specify
14361 the specular RGBA intensity of the light. Integer values are mapped
14362 linearly such that the most positive representable value maps to 1.0,
14363 and the most negative representable value maps to @r{-1.0}.
14364 Floating-point values are mapped directly. Neither integer nor
14365 floating-point values are clamped. The initial value for
14366 @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial value is
14369 @item @code{GL_POSITION}
14370 @var{params} contains four integer or floating-point values that specify
14371 the position of the light in homogeneous object coordinates. Both
14372 integer and floating-point values are mapped directly. Neither integer
14373 nor floating-point values are clamped.
14375 The position is transformed by the modelview matrix when @code{glLight}
14376 is called (just as if it were a point), and it is stored in eye
14377 coordinates. If the @r{@var{w}} component of the position is 0, the
14378 light is treated as a directional source. Diffuse and specular lighting
14379 calculations take the light's direction, but not its actual position,
14380 into account, and attenuation is disabled. Otherwise, diffuse and
14381 specular lighting calculations are based on the actual location of the
14382 light in eye coordinates, and attenuation is enabled. The initial
14383 position is (0, 0, 1, 0); thus, the initial light source is directional,
14384 parallel to, and in the direction of the @r{-@var{z}} axis.
14386 @item @code{GL_SPOT_DIRECTION}
14387 @var{params} contains three integer or floating-point values that
14388 specify the direction of the light in homogeneous object coordinates.
14389 Both integer and floating-point values are mapped directly. Neither
14390 integer nor floating-point values are clamped.
14392 The spot direction is transformed by the upper 3x3 of the modelview
14393 matrix when @code{glLight} is called, and it is stored in eye
14394 coordinates. It is significant only when @code{GL_SPOT_CUTOFF} is not
14395 180, which it is initially. The initial direction is @r{(0,0-1)}.
14397 @item @code{GL_SPOT_EXPONENT}
14398 @var{params} is a single integer or floating-point value that specifies
14399 the intensity distribution of the light. Integer and floating-point
14400 values are mapped directly. Only values in the range @r{[0,128]} are
14403 Effective light intensity is attenuated by the cosine of the angle
14404 between the direction of the light and the direction from the light to
14405 the vertex being lighted, raised to the power of the spot exponent.
14406 Thus, higher spot exponents result in a more focused light source,
14407 regardless of the spot cutoff angle (see @code{GL_SPOT_CUTOFF}, next
14408 paragraph). The initial spot exponent is 0, resulting in uniform light
14411 @item @code{GL_SPOT_CUTOFF}
14412 @var{params} is a single integer or floating-point value that specifies
14413 the maximum spread angle of a light source. Integer and floating-point
14414 values are mapped directly. Only values in the range @r{[0,90]} and the
14415 special value 180 are accepted. If the angle between the direction of
14416 the light and the direction from the light to the vertex being lighted
14417 is greater than the spot cutoff angle, the light is completely masked.
14418 Otherwise, its intensity is controlled by the spot exponent and the
14419 attenuation factors. The initial spot cutoff is 180, resulting in
14420 uniform light distribution.
14422 @item @code{GL_CONSTANT_ATTENUATION}
14423 @item @code{GL_LINEAR_ATTENUATION}
14424 @item @code{GL_QUADRATIC_ATTENUATION}
14425 @var{params} is a single integer or floating-point value that specifies
14426 one of the three light attenuation factors. Integer and floating-point
14427 values are mapped directly. Only nonnegative values are accepted. If
14428 the light is positional, rather than directional, its intensity is
14429 attenuated by the reciprocal of the sum of the constant factor, the
14430 linear factor times the distance between the light and the vertex being
14431 lighted, and the quadratic factor times the square of the same distance.
14432 The initial attenuation factors are (1, 0, 0), resulting in no
14437 @code{GL_INVALID_ENUM} is generated if either @var{light} or @var{pname}
14438 is not an accepted value.
14440 @code{GL_INVALID_VALUE} is generated if a spot exponent value is
14441 specified outside the range @r{[0,128]}, or if spot cutoff is specified
14442 outside the range @r{[0,90]} (except for the special value 180), or if a
14443 negative attenuation factor is specified.
14445 @code{GL_INVALID_OPERATION} is generated if @code{glLight} is executed
14446 between the execution of @code{glBegin} and the corresponding execution
14451 @deftypefun void glLineStipple factor pattern
14452 Specify the line stipple pattern.
14456 Specifies a multiplier for each bit in the line stipple pattern. If
14457 @var{factor} is 3, for example, each bit in the pattern is used three
14458 times before the next bit in the pattern is used. @var{factor} is
14459 clamped to the range [1, 256] and defaults to 1.
14461 @item @var{pattern}
14462 Specifies a 16-bit integer whose bit pattern determines which fragments
14463 of a line will be drawn when the line is rasterized. Bit zero is used
14464 first; the default pattern is all 1's.
14468 Line stippling masks out certain fragments produced by rasterization;
14469 those fragments will not be drawn. The masking is achieved by using
14470 three parameters: the 16-bit line stipple pattern @var{pattern}, the
14471 repeat count @var{factor}, and an integer stipple counter @r{@var{s}}.
14473 Counter @r{@var{s}} is reset to 0 whenever @code{glBegin} is called and
14474 before each line segment of a
14475 @code{glBegin}(@code{GL_LINES})/@code{glEnd} sequence is generated. It
14476 is incremented after each fragment of a unit width aliased line segment
14477 is generated or after each @r{@var{i}} fragments of an @r{@var{i}} width
14478 line segment are generated. The @r{@var{i}} fragments associated with
14479 count @r{@var{s}} are masked out if
14481 @var{pattern} bit @r{(@var{s}/@var{factor},)%16}
14483 is 0, otherwise these fragments are sent to the frame buffer. Bit zero
14484 of @var{pattern} is the least significant bit.
14486 Antialiased lines are treated as a sequence of @r{1×@var{width}}
14487 rectangles for purposes of stippling. Whether rectangle @r{@var{s}} is
14488 rasterized or not depends on the fragment rule described for aliased
14489 lines, counting rectangles rather than groups of fragments.
14491 To enable and disable line stippling, call @code{glEnable} and
14492 @code{glDisable} with argument @code{GL_LINE_STIPPLE}. When enabled,
14493 the line stipple pattern is applied as described above. When disabled,
14494 it is as if the pattern were all 1's. Initially, line stippling is
14497 @code{GL_INVALID_OPERATION} is generated if @code{glLineStipple} is
14498 executed between the execution of @code{glBegin} and the corresponding
14499 execution of @code{glEnd}.
14503 @deftypefun void glLineWidth width
14504 Specify the width of rasterized lines.
14508 Specifies the width of rasterized lines. The initial value is 1.
14512 @code{glLineWidth} specifies the rasterized width of both aliased and
14513 antialiased lines. Using a line width other than 1 has different
14514 effects, depending on whether line antialiasing is enabled. To enable
14515 and disable line antialiasing, call @code{glEnable} and @code{glDisable}
14516 with argument @code{GL_LINE_SMOOTH}. Line antialiasing is initially
14519 If line antialiasing is disabled, the actual width is determined by
14520 rounding the supplied width to the nearest integer. (If the rounding
14521 results in the value 0, it is as if the line width were 1.) If
14522 @r{∣Δ@var{x},∣>=∣Δ@var{y},∣}, @var{i} pixels are filled in each column
14523 that is rasterized, where @var{i} is the rounded value of @var{width}.
14524 Otherwise, @var{i} pixels are filled in each row that is rasterized.
14526 If antialiasing is enabled, line rasterization produces a fragment for
14527 each pixel square that intersects the region lying within the rectangle
14528 having width equal to the current line width, length equal to the actual
14529 length of the line, and centered on the mathematical line segment. The
14530 coverage value for each fragment is the window coordinate area of the
14531 intersection of the rectangular region with the corresponding pixel
14532 square. This value is saved and used in the final rasterization step.
14534 Not all widths can be supported when line antialiasing is enabled. If
14535 an unsupported width is requested, the nearest supported width is used.
14536 Only width 1 is guaranteed to be supported; others depend on the
14537 implementation. Likewise, there is a range for aliased line widths as
14538 well. To query the range of supported widths and the size difference
14539 between supported widths within the range, call @code{glGet} with
14540 arguments @code{GL_ALIASED_LINE_WIDTH_RANGE},
14541 @code{GL_SMOOTH_LINE_WIDTH_RANGE}, and
14542 @code{GL_SMOOTH_LINE_WIDTH_GRANULARITY}.
14544 @code{GL_INVALID_VALUE} is generated if @var{width} is less than or
14547 @code{GL_INVALID_OPERATION} is generated if @code{glLineWidth} is
14548 executed between the execution of @code{glBegin} and the corresponding
14549 execution of @code{glEnd}.
14553 @deftypefun void glLinkProgram program
14554 Links a program object.
14557 @item @var{program}
14558 Specifies the handle of the program object to be linked.
14562 @code{glLinkProgram} links the program object specified by
14563 @var{program}. If any shader objects of type @code{GL_VERTEX_SHADER}
14564 are attached to @var{program}, they will be used to create an executable
14565 that will run on the programmable vertex processor. If any shader
14566 objects of type @code{GL_FRAGMENT_SHADER} are attached to @var{program},
14567 they will be used to create an executable that will run on the
14568 programmable fragment processor.
14570 The status of the link operation will be stored as part of the program
14571 object's state. This value will be set to @code{GL_TRUE} if the program
14572 object was linked without errors and is ready for use, and
14573 @code{GL_FALSE} otherwise. It can be queried by calling
14574 @code{glGetProgram} with arguments @var{program} and
14575 @code{GL_LINK_STATUS}.
14577 As a result of a successful link operation, all active user-defined
14578 uniform variables belonging to @var{program} will be initialized to 0,
14579 and each of the program object's active uniform variables will be
14580 assigned a location that can be queried by calling
14581 @code{glGetUniformLocation}. Also, any active user-defined attribute
14582 variables that have not been bound to a generic vertex attribute index
14583 will be bound to one at this time.
14585 Linking of a program object can fail for a number of reasons as
14586 specified in the @var{OpenGL Shading Language Specification}. The
14587 following lists some of the conditions that will cause a link error.
14591 The number of active attribute variables supported by the implementation
14595 The storage limit for uniform variables has been exceeded.
14598 The number of active uniform variables supported by the implementation
14602 The @code{main} function is missing for the vertex shader or the
14606 A varying variable actually used in the fragment shader is not declared
14607 in the same way (or is not declared at all) in the vertex shader.
14610 A reference to a function or variable name is unresolved.
14613 A shared global is declared with two different types or two different
14617 One or more of the attached shader objects has not been successfully
14621 Binding a generic attribute matrix caused some rows of the matrix to
14622 fall outside the allowed maximum of @code{GL_MAX_VERTEX_ATTRIBS}.
14625 Not enough contiguous vertex attribute slots could be found to bind
14626 attribute matrices.
14630 When a program object has been successfully linked, the program object
14631 can be made part of current state by calling @code{glUseProgram}.
14632 Whether or not the link operation was successful, the program object's
14633 information log will be overwritten. The information log can be
14634 retrieved by calling @code{glGetProgramInfoLog}.
14636 @code{glLinkProgram} will also install the generated executables as part
14637 of the current rendering state if the link operation was successful and
14638 the specified program object is already currently in use as a result of
14639 a previous call to @code{glUseProgram}. If the program object currently
14640 in use is relinked unsuccessfully, its link status will be set to
14641 @code{GL_FALSE} , but the executables and associated state will remain
14642 part of the current state until a subsequent call to @code{glUseProgram}
14643 removes it from use. After it is removed from use, it cannot be made
14644 part of current state until it has been successfully relinked.
14646 If @var{program} contains shader objects of type @code{GL_VERTEX_SHADER}
14647 but does not contain shader objects of type @code{GL_FRAGMENT_SHADER},
14648 the vertex shader will be linked against the implicit interface for
14649 fixed functionality fragment processing. Similarly, if @var{program}
14650 contains shader objects of type @code{GL_FRAGMENT_SHADER} but it does
14651 not contain shader objects of type @code{GL_VERTEX_SHADER}, the fragment
14652 shader will be linked against the implicit interface for fixed
14653 functionality vertex processing.
14655 The program object's information log is updated and the program is
14656 generated at the time of the link operation. After the link operation,
14657 applications are free to modify attached shader objects, compile
14658 attached shader objects, detach shader objects, delete shader objects,
14659 and attach additional shader objects. None of these operations affects
14660 the information log or the program that is part of the program object.
14662 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
14663 generated by OpenGL.
14665 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
14668 @code{GL_INVALID_OPERATION} is generated if @code{glLinkProgram} is
14669 executed between the execution of @code{glBegin} and the corresponding
14670 execution of @code{glEnd}.
14674 @deftypefun void glListBase base
14675 Set the display-list base for .
14679 Specifies an integer offset that will be added to @code{glCallLists}
14680 offsets to generate display-list names. The initial value is 0.
14684 @code{glCallLists} specifies an array of offsets. Display-list names
14685 are generated by adding @var{base} to each offset. Names that reference
14686 valid display lists are executed; the others are ignored.
14688 @code{GL_INVALID_OPERATION} is generated if @code{glListBase} is
14689 executed between the execution of @code{glBegin} and the corresponding
14690 execution of @code{glEnd}.
14694 @deftypefun void glLoadIdentity
14695 Replace the current matrix with the identity matrix.
14697 @code{glLoadIdentity} replaces the current matrix with the identity
14698 matrix. It is semantically equivalent to calling @code{glLoadMatrix}
14699 with the identity matrix
14703 @r{((1 0 0 0), (0 1 0 0), (0 0 1 0), (0 0 0 1),,)}
14707 but in some cases it is more efficient.
14709 @code{GL_INVALID_OPERATION} is generated if @code{glLoadIdentity} is
14710 executed between the execution of @code{glBegin} and the corresponding
14711 execution of @code{glEnd}.
14715 @deftypefun void glLoadMatrixd m
14716 @deftypefunx void glLoadMatrixf m
14717 Replace the current matrix with the specified matrix.
14721 Specifies a pointer to 16 consecutive values, which are used as the
14722 elements of a @r{4×4} column-major matrix.
14726 @code{glLoadMatrix} replaces the current matrix with the one whose
14727 elements are specified by @var{m}. The current matrix is the projection
14728 matrix, modelview matrix, or texture matrix, depending on the current
14729 matrix mode (see @code{glMatrixMode}).
14731 The current matrix, M, defines a transformation of coordinates. For
14732 instance, assume M refers to the modelview matrix. If
14733 @r{@var{v}=(@var{v}[0,],@var{v}[1,]@var{v}[2,]@var{v}[3,])} is the
14734 set of object coordinates of a vertex, and @var{m} points to an array of
14735 @r{16} single- or double-precision floating-point values
14736 @r{@var{m}=@{@var{m}[0,],@var{m}[1,]@var{...}@var{m}[15,]@}}, then
14737 the modelview transformation @r{@var{M}(@var{v},)} does the following:
14739 @r{@var{M}(@var{v},)=((@var{m}[0,] @var{m}[4,] @var{m}[8,]
14740 @var{m}[12,]), (@var{m}[1,] @var{m}[5,] @var{m}[9,] @var{m}[13,]),
14741 (@var{m}[2,] @var{m}[6,] @var{m}[10,] @var{m}[14,]), (@var{m}[3,]
14742 @var{m}[7,] @var{m}[11,] @var{m}[15,]),)×((@var{v}[0,]),
14743 (@var{v}[1,]), (@var{v}[2,]), (@var{v}[3,]),)}
14747 Projection and texture transformations are similarly defined.
14749 @code{GL_INVALID_OPERATION} is generated if @code{glLoadMatrix} is
14750 executed between the execution of @code{glBegin} and the corresponding
14751 execution of @code{glEnd}.
14755 @deftypefun void glLoadName name
14756 Load a name onto the name stack.
14760 Specifies a name that will replace the top value on the name stack.
14764 The name stack is used during selection mode to allow sets of rendering
14765 commands to be uniquely identified. It consists of an ordered set of
14766 unsigned integers and is initially empty.
14768 @code{glLoadName} causes @var{name} to replace the value on the top of
14771 The name stack is always empty while the render mode is not
14772 @code{GL_SELECT}. Calls to @code{glLoadName} while the render mode is
14773 not @code{GL_SELECT} are ignored.
14775 @code{GL_INVALID_OPERATION} is generated if @code{glLoadName} is called
14776 while the name stack is empty.
14778 @code{GL_INVALID_OPERATION} is generated if @code{glLoadName} is
14779 executed between the execution of @code{glBegin} and the corresponding
14780 execution of @code{glEnd}.
14784 @deftypefun void glLoadTransposeMatrixd m
14785 @deftypefunx void glLoadTransposeMatrixf m
14786 Replace the current matrix with the specified row-major ordered matrix.
14790 Specifies a pointer to 16 consecutive values, which are used as the
14791 elements of a @r{4×4} row-major matrix.
14795 @code{glLoadTransposeMatrix} replaces the current matrix with the one
14796 whose elements are specified by @var{m}. The current matrix is the
14797 projection matrix, modelview matrix, or texture matrix, depending on the
14798 current matrix mode (see @code{glMatrixMode}).
14800 The current matrix, M, defines a transformation of coordinates. For
14801 instance, assume M refers to the modelview matrix. If
14802 @r{@var{v}=(@var{v}[0,],@var{v}[1,]@var{v}[2,]@var{v}[3,])} is the
14803 set of object coordinates of a vertex, and @var{m} points to an array of
14804 @r{16} single- or double-precision floating-point values
14805 @r{@var{m}=@{@var{m}[0,],@var{m}[1,]@var{...}@var{m}[15,]@}}, then
14806 the modelview transformation @r{@var{M}(@var{v},)} does the following:
14808 @r{@var{M}(@var{v},)=((@var{m}[0,] @var{m}[1,] @var{m}[2,]
14809 @var{m}[3,]), (@var{m}[4,] @var{m}[5,] @var{m}[6,] @var{m}[7,]),
14810 (@var{m}[8,] @var{m}[9,] @var{m}[10,] @var{m}[11,]), (@var{m}[12,]
14811 @var{m}[13,] @var{m}[14,] @var{m}[15,]),)×((@var{v}[0,]),
14812 (@var{v}[1,]), (@var{v}[2,]), (@var{v}[3,]),)}
14816 Projection and texture transformations are similarly defined.
14818 Calling @code{glLoadTransposeMatrix} with matrix @r{@var{M}} is
14819 identical in operation to @code{glLoadMatrix} with @r{@var{M}^@var{T}},
14820 where @r{@var{T}} represents the transpose.
14822 @code{GL_INVALID_OPERATION} is generated if @code{glLoadTransposeMatrix}
14823 is executed between the execution of @code{glBegin} and the
14824 corresponding execution of @code{glEnd}.
14828 @deftypefun void glLogicOp opcode
14829 Specify a logical pixel operation for color index rendering.
14833 Specifies a symbolic constant that selects a logical operation. The
14834 following symbols are accepted: @code{GL_CLEAR}, @code{GL_SET},
14835 @code{GL_COPY}, @code{GL_COPY_INVERTED}, @code{GL_NOOP},
14836 @code{GL_INVERT}, @code{GL_AND}, @code{GL_NAND}, @code{GL_OR},
14837 @code{GL_NOR}, @code{GL_XOR}, @code{GL_EQUIV}, @code{GL_AND_REVERSE},
14838 @code{GL_AND_INVERTED}, @code{GL_OR_REVERSE}, and @code{GL_OR_INVERTED}.
14839 The initial value is @code{GL_COPY}.
14843 @code{glLogicOp} specifies a logical operation that, when enabled, is
14844 applied between the incoming color index or RGBA color and the color
14845 index or RGBA color at the corresponding location in the frame buffer.
14846 To enable or disable the logical operation, call @code{glEnable} and
14847 @code{glDisable} using the symbolic constant @code{GL_COLOR_LOGIC_OP}
14848 for RGBA mode or @code{GL_INDEX_LOGIC_OP} for color index mode. The
14849 initial value is disabled for both operations.
14854 @item @strong{Opcode}
14855 @strong{Resulting Operation}
14857 @item @code{GL_CLEAR}
14860 @item @code{GL_SET}
14863 @item @code{GL_COPY}
14866 @item @code{GL_COPY_INVERTED}
14869 @item @code{GL_NOOP}
14872 @item @code{GL_INVERT}
14875 @item @code{GL_AND}
14878 @item @code{GL_NAND}
14884 @item @code{GL_NOR}
14887 @item @code{GL_XOR}
14890 @item @code{GL_EQUIV}
14893 @item @code{GL_AND_REVERSE}
14896 @item @code{GL_AND_INVERTED}
14899 @item @code{GL_OR_REVERSE}
14902 @item @code{GL_OR_INVERTED}
14907 @var{opcode} is a symbolic constant chosen from the list above. In the
14908 explanation of the logical operations, @var{s} represents the incoming
14909 color index and @var{d} represents the index in the frame buffer.
14910 Standard C-language operators are used. As these bitwise operators
14911 suggest, the logical operation is applied independently to each bit pair
14912 of the source and destination indices or colors.
14914 @code{GL_INVALID_ENUM} is generated if @var{opcode} is not an accepted
14917 @code{GL_INVALID_OPERATION} is generated if @code{glLogicOp} is executed
14918 between the execution of @code{glBegin} and the corresponding execution
14923 @deftypefun void glMap1f target u1 u2 stride order points
14924 @deftypefunx void glMap1d target u1 u2 stride order points
14925 Define a one-dimensional evaluator.
14929 Specifies the kind of values that are generated by the evaluator.
14930 Symbolic constants @code{GL_MAP1_VERTEX_3}, @code{GL_MAP1_VERTEX_4},
14931 @code{GL_MAP1_INDEX}, @code{GL_MAP1_COLOR_4}, @code{GL_MAP1_NORMAL},
14932 @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2},
14933 @code{GL_MAP1_TEXTURE_COORD_3}, and @code{GL_MAP1_TEXTURE_COORD_4} are
14938 Specify a linear mapping of @r{@var{u}}, as presented to
14939 @code{glEvalCoord1}, to @r{@var{u}^}, the variable that is evaluated by
14940 the equations specified by this command.
14943 Specifies the number of floats or doubles between the beginning of one
14944 control point and the beginning of the next one in the data structure
14945 referenced in @var{points}. This allows control points to be embedded
14946 in arbitrary data structures. The only constraint is that the values
14947 for a particular control point must occupy contiguous memory locations.
14950 Specifies the number of control points. Must be positive.
14953 Specifies a pointer to the array of control points.
14957 Evaluators provide a way to use polynomial or rational polynomial
14958 mapping to produce vertices, normals, texture coordinates, and colors.
14959 The values produced by an evaluator are sent to further stages of GL
14960 processing just as if they had been presented using @code{glVertex},
14961 @code{glNormal}, @code{glTexCoord}, and @code{glColor} commands, except
14962 that the generated values do not update the current normal, texture
14963 coordinates, or color.
14965 All polynomial or rational polynomial splines of any degree (up to the
14966 maximum degree supported by the GL implementation) can be described
14967 using evaluators. These include almost all splines used in computer
14968 graphics: B-splines, Bezier curves, Hermite splines, and so on.
14970 Evaluators define curves based on Bernstein polynomials. Define
14971 @r{@var{p}(@var{u}^,)} as
14973 @r{@var{p}(@var{u}^,)=Σ@var{i}=0@var{n}@var{B}_@var{i},^@var{n}(@var{u}^,)@var{R}_@var{i}}
14977 where @r{@var{R}_@var{i}} is a control point and
14978 @r{@var{B}_@var{i},^@var{n}(@var{u}^,)} is the @r{@var{i}}th Bernstein
14979 polynomial of degree @r{@var{n}} (@var{order} = @r{@var{n}+1}):
14981 @r{@var{B}_@var{i},^@var{n}(@var{u}^,)=((@var{n}),
14982 (@var{i}),,)@var{u}^,^@var{i}(1-@var{u}^,)^@var{n}-@var{i},,}
14986 @r{0^0==1} and @r{((@var{n}), (0),,)==1}
14988 @code{glMap1} is used to define the basis and to specify what kind of
14989 values are produced. Once defined, a map can be enabled and disabled by
14990 calling @code{glEnable} and @code{glDisable} with the map name, one of
14991 the nine predefined values for @var{target} described below.
14992 @code{glEvalCoord1} evaluates the one-dimensional maps that are enabled.
14993 When @code{glEvalCoord1} presents a value @r{@var{u}}, the Bernstein
14994 functions are evaluated using @r{@var{u}^}, where
14995 @r{@var{u}^=@var{u}-@var{u1},/@var{u2}-@var{u1},}
14997 @var{target} is a symbolic constant that indicates what kind of control
14998 points are provided in @var{points}, and what output is generated when
14999 the map is evaluated. It can assume one of nine predefined values:
15002 @item @code{GL_MAP1_VERTEX_3}
15003 Each control point is three floating-point values representing
15004 @r{@var{x}}, @r{@var{y}}, and @r{@var{z}}. Internal @code{glVertex3}
15005 commands are generated when the map is evaluated.
15007 @item @code{GL_MAP1_VERTEX_4}
15008 Each control point is four floating-point values representing
15009 @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}. Internal
15010 @code{glVertex4} commands are generated when the map is evaluated.
15012 @item @code{GL_MAP1_INDEX}
15013 Each control point is a single floating-point value representing a color
15014 index. Internal @code{glIndex} commands are generated when the map is
15015 evaluated but the current index is not updated with the value of these
15016 @code{glIndex} commands.
15018 @item @code{GL_MAP1_COLOR_4}
15019 Each control point is four floating-point values representing red,
15020 green, blue, and alpha. Internal @code{glColor4} commands are generated
15021 when the map is evaluated but the current color is not updated with the
15022 value of these @code{glColor4} commands.
15024 @item @code{GL_MAP1_NORMAL}
15025 Each control point is three floating-point values representing the
15026 @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} components of a normal vector.
15027 Internal @code{glNormal} commands are generated when the map is
15028 evaluated but the current normal is not updated with the value of these
15029 @code{glNormal} commands.
15031 @item @code{GL_MAP1_TEXTURE_COORD_1}
15032 Each control point is a single floating-point value representing the
15033 @r{@var{s}} texture coordinate. Internal @code{glTexCoord1} commands
15034 are generated when the map is evaluated but the current texture
15035 coordinates are not updated with the value of these @code{glTexCoord}
15038 @item @code{GL_MAP1_TEXTURE_COORD_2}
15039 Each control point is two floating-point values representing the
15040 @r{@var{s}} and @r{@var{t}} texture coordinates. Internal
15041 @code{glTexCoord2} commands are generated when the map is evaluated but
15042 the current texture coordinates are not updated with the value of these
15043 @code{glTexCoord} commands.
15045 @item @code{GL_MAP1_TEXTURE_COORD_3}
15046 Each control point is three floating-point values representing the
15047 @r{@var{s}}, @r{@var{t}}, and @r{@var{r}} texture coordinates. Internal
15048 @code{glTexCoord3} commands are generated when the map is evaluated but
15049 the current texture coordinates are not updated with the value of these
15050 @code{glTexCoord} commands.
15052 @item @code{GL_MAP1_TEXTURE_COORD_4}
15053 Each control point is four floating-point values representing the
15054 @r{@var{s}}, @r{@var{t}}, @r{@var{r}}, and @r{@var{q}} texture
15055 coordinates. Internal @code{glTexCoord4} commands are generated when
15056 the map is evaluated but the current texture coordinates are not updated
15057 with the value of these @code{glTexCoord} commands.
15061 @var{stride}, @var{order}, and @var{points} define the array addressing
15062 for accessing the control points. @var{points} is the location of the
15063 first control point, which occupies one, two, three, or four contiguous
15064 memory locations, depending on which map is being defined. @var{order}
15065 is the number of control points in the array. @var{stride} specifies
15066 how many float or double locations to advance the internal memory
15067 pointer to reach the next control point.
15069 @code{GL_INVALID_ENUM} is generated if @var{target} is not an accepted
15072 @code{GL_INVALID_VALUE} is generated if @var{u1} is equal to @var{u2}.
15074 @code{GL_INVALID_VALUE} is generated if @var{stride} is less than the
15075 number of values in a control point.
15077 @code{GL_INVALID_VALUE} is generated if @var{order} is less than 1 or
15078 greater than the return value of @code{GL_MAX_EVAL_ORDER}.
15080 @code{GL_INVALID_OPERATION} is generated if @code{glMap1} is executed
15081 between the execution of @code{glBegin} and the corresponding execution
15084 @code{GL_INVALID_OPERATION} is generated if @code{glMap1} is called and
15085 the value of @code{GL_ACTIVE_TEXTURE} is not @code{GL_TEXTURE0}.
15089 @deftypefun void glMap2f target u1 u2 ustride uorder v1 v2 vstride vorder points
15090 @deftypefunx void glMap2d target u1 u2 ustride uorder v1 v2 vstride vorder points
15091 Define a two-dimensional evaluator.
15095 Specifies the kind of values that are generated by the evaluator.
15096 Symbolic constants @code{GL_MAP2_VERTEX_3}, @code{GL_MAP2_VERTEX_4},
15097 @code{GL_MAP2_INDEX}, @code{GL_MAP2_COLOR_4}, @code{GL_MAP2_NORMAL},
15098 @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2},
15099 @code{GL_MAP2_TEXTURE_COORD_3}, and @code{GL_MAP2_TEXTURE_COORD_4} are
15104 Specify a linear mapping of @r{@var{u}}, as presented to
15105 @code{glEvalCoord2}, to @r{@var{u}^}, one of the two variables that are
15106 evaluated by the equations specified by this command. Initially,
15107 @var{u1} is 0 and @var{u2} is 1.
15109 @item @var{ustride}
15110 Specifies the number of floats or doubles between the beginning of
15111 control point @r{@var{R}_@var{ij}} and the beginning of control point
15112 @r{@var{R}_(@var{i}+1,)@var{j},}, where @r{@var{i}} and @r{@var{j}} are
15113 the @r{@var{u}} and @r{@var{v}} control point indices, respectively.
15114 This allows control points to be embedded in arbitrary data structures.
15115 The only constraint is that the values for a particular control point
15116 must occupy contiguous memory locations. The initial value of
15117 @var{ustride} is 0.
15120 Specifies the dimension of the control point array in the @r{@var{u}}
15121 axis. Must be positive. The initial value is 1.
15125 Specify a linear mapping of @r{@var{v}}, as presented to
15126 @code{glEvalCoord2}, to @r{@var{v}^}, one of the two variables that are
15127 evaluated by the equations specified by this command. Initially,
15128 @var{v1} is 0 and @var{v2} is 1.
15130 @item @var{vstride}
15131 Specifies the number of floats or doubles between the beginning of
15132 control point @r{@var{R}_@var{ij}} and the beginning of control point
15133 @r{@var{R}_@var{i}(@var{j}+1,),}, where @r{@var{i}} and @r{@var{j}} are
15134 the @r{@var{u}} and @r{@var{v}} control point indices, respectively.
15135 This allows control points to be embedded in arbitrary data structures.
15136 The only constraint is that the values for a particular control point
15137 must occupy contiguous memory locations. The initial value of
15138 @var{vstride} is 0.
15141 Specifies the dimension of the control point array in the @r{@var{v}}
15142 axis. Must be positive. The initial value is 1.
15145 Specifies a pointer to the array of control points.
15149 Evaluators provide a way to use polynomial or rational polynomial
15150 mapping to produce vertices, normals, texture coordinates, and colors.
15151 The values produced by an evaluator are sent on to further stages of GL
15152 processing just as if they had been presented using @code{glVertex},
15153 @code{glNormal}, @code{glTexCoord}, and @code{glColor} commands, except
15154 that the generated values do not update the current normal, texture
15155 coordinates, or color.
15157 All polynomial or rational polynomial splines of any degree (up to the
15158 maximum degree supported by the GL implementation) can be described
15159 using evaluators. These include almost all surfaces used in computer
15160 graphics, including B-spline surfaces, NURBS surfaces, Bezier surfaces,
15163 Evaluators define surfaces based on bivariate Bernstein polynomials.
15164 Define @r{@var{p}(@var{u}^,@var{v}^)} as
15166 @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}}
15170 where @r{@var{R}_@var{ij}} is a control point,
15171 @r{@var{B}_@var{i},^@var{n}(@var{u}^,)} is the @r{@var{i}}th Bernstein
15172 polynomial of degree @r{@var{n}} (@var{uorder} = @r{@var{n}+1})
15174 @r{@var{B}_@var{i},^@var{n}(@var{u}^,)=((@var{n}),
15175 (@var{i}),,)@var{u}^,^@var{i}(1-@var{u}^,)^@var{n}-@var{i},,}
15177 and @r{@var{B}_@var{j},^@var{m}(@var{v}^,)} is the @r{@var{j}}th
15178 Bernstein polynomial of degree @r{@var{m}} (@var{vorder} =
15181 @r{@var{B}_@var{j},^@var{m}(@var{v}^,)=((@var{m}),
15182 (@var{j}),,)@var{v}^,^@var{j}(1-@var{v}^,)^@var{m}-@var{j},,}
15184 Recall that @r{0^0==1} and @r{((@var{n}), (0),,)==1}
15186 @code{glMap2} is used to define the basis and to specify what kind of
15187 values are produced. Once defined, a map can be enabled and disabled by
15188 calling @code{glEnable} and @code{glDisable} with the map name, one of
15189 the nine predefined values for @var{target}, described below. When
15190 @code{glEvalCoord2} presents values @r{@var{u}} and @r{@var{v}}, the
15191 bivariate Bernstein polynomials are evaluated using @r{@var{u}^} and
15192 @r{@var{v}^}, where
15194 @r{@var{u}^=@var{u}-@var{u1},/@var{u2}-@var{u1},}
15196 @r{@var{v}^=@var{v}-@var{v1},/@var{v2}-@var{v1},}
15198 @var{target} is a symbolic constant that indicates what kind of control
15199 points are provided in @var{points}, and what output is generated when
15200 the map is evaluated. It can assume one of nine predefined values:
15203 @item @code{GL_MAP2_VERTEX_3}
15204 Each control point is three floating-point values representing
15205 @r{@var{x}}, @r{@var{y}}, and @r{@var{z}}. Internal @code{glVertex3}
15206 commands are generated when the map is evaluated.
15208 @item @code{GL_MAP2_VERTEX_4}
15209 Each control point is four floating-point values representing
15210 @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}. Internal
15211 @code{glVertex4} commands are generated when the map is evaluated.
15213 @item @code{GL_MAP2_INDEX}
15214 Each control point is a single floating-point value representing a color
15215 index. Internal @code{glIndex} commands are generated when the map is
15216 evaluated but the current index is not updated with the value of these
15217 @code{glIndex} commands.
15219 @item @code{GL_MAP2_COLOR_4}
15220 Each control point is four floating-point values representing red,
15221 green, blue, and alpha. Internal @code{glColor4} commands are generated
15222 when the map is evaluated but the current color is not updated with the
15223 value of these @code{glColor4} commands.
15225 @item @code{GL_MAP2_NORMAL}
15226 Each control point is three floating-point values representing the
15227 @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} components of a normal vector.
15228 Internal @code{glNormal} commands are generated when the map is
15229 evaluated but the current normal is not updated with the value of these
15230 @code{glNormal} commands.
15232 @item @code{GL_MAP2_TEXTURE_COORD_1}
15233 Each control point is a single floating-point value representing the
15234 @r{@var{s}} texture coordinate. Internal @code{glTexCoord1} commands
15235 are generated when the map is evaluated but the current texture
15236 coordinates are not updated with the value of these @code{glTexCoord}
15239 @item @code{GL_MAP2_TEXTURE_COORD_2}
15240 Each control point is two floating-point values representing the
15241 @r{@var{s}} and @r{@var{t}} texture coordinates. Internal
15242 @code{glTexCoord2} commands are generated when the map is evaluated but
15243 the current texture coordinates are not updated with the value of these
15244 @code{glTexCoord} commands.
15246 @item @code{GL_MAP2_TEXTURE_COORD_3}
15247 Each control point is three floating-point values representing the
15248 @r{@var{s}}, @r{@var{t}}, and @r{@var{r}} texture coordinates. Internal
15249 @code{glTexCoord3} commands are generated when the map is evaluated but
15250 the current texture coordinates are not updated with the value of these
15251 @code{glTexCoord} commands.
15253 @item @code{GL_MAP2_TEXTURE_COORD_4}
15254 Each control point is four floating-point values representing the
15255 @r{@var{s}}, @r{@var{t}}, @r{@var{r}}, and @r{@var{q}} texture
15256 coordinates. Internal @code{glTexCoord4} commands are generated when
15257 the map is evaluated but the current texture coordinates are not updated
15258 with the value of these @code{glTexCoord} commands.
15262 @var{ustride}, @var{uorder}, @var{vstride}, @var{vorder}, and
15263 @var{points} define the array addressing for accessing the control
15264 points. @var{points} is the location of the first control point, which
15265 occupies one, two, three, or four contiguous memory locations, depending
15266 on which map is being defined. There are @r{@var{uorder}×@var{vorder}}
15267 control points in the array. @var{ustride} specifies how many float or
15268 double locations are skipped to advance the internal memory pointer from
15269 control point @r{@var{R}_@var{i}@var{j},} to control point
15270 @r{@var{R}_(@var{i}+1,)@var{j},}. @var{vstride} specifies how many
15271 float or double locations are skipped to advance the internal memory
15272 pointer from control point @r{@var{R}_@var{i}@var{j},} to control point
15273 @r{@var{R}_@var{i}(@var{j}+1,),}.
15275 @code{GL_INVALID_ENUM} is generated if @var{target} is not an accepted
15278 @code{GL_INVALID_VALUE} is generated if @var{u1} is equal to @var{u2},
15279 or if @var{v1} is equal to @var{v2}.
15281 @code{GL_INVALID_VALUE} is generated if either @var{ustride} or
15282 @var{vstride} is less than the number of values in a control point.
15284 @code{GL_INVALID_VALUE} is generated if either @var{uorder} or
15285 @var{vorder} is less than 1 or greater than the return value of
15286 @code{GL_MAX_EVAL_ORDER}.
15288 @code{GL_INVALID_OPERATION} is generated if @code{glMap2} is executed
15289 between the execution of @code{glBegin} and the corresponding execution
15292 @code{GL_INVALID_OPERATION} is generated if @code{glMap2} is called and
15293 the value of @code{GL_ACTIVE_TEXTURE} is not @code{GL_TEXTURE0}.
15297 @deftypefun void-* glMapBuffer target access
15298 @deftypefunx GLboolean glUnmapBuffer target
15299 Map a buffer object's data store.
15303 Specifies the target buffer object being mapped. The symbolic constant
15304 must be @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
15305 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
15308 Specifies the access policy, indicating whether it will be possible to
15309 read from, write to, or both read from and write to the buffer object's
15310 mapped data store. The symbolic constant must be @code{GL_READ_ONLY},
15311 @code{GL_WRITE_ONLY}, or @code{GL_READ_WRITE}.
15315 @code{glMapBuffer} maps to the client's address space the entire data
15316 store of the buffer object currently bound to @var{target}. The data
15317 can then be directly read and/or written relative to the returned
15318 pointer, depending on the specified @var{access} policy. If the GL is
15319 unable to map the buffer object's data store, @code{glMapBuffer}
15320 generates an error and returns @code{NULL}. This may occur for
15321 system-specific reasons, such as low virtual memory availability.
15323 If a mapped data store is accessed in a way inconsistent with the
15324 specified @var{access} policy, no error is generated, but performance
15325 may be negatively impacted and system errors, including program
15326 termination, may result. Unlike the @var{usage} parameter of
15327 @code{glBufferData}, @var{access} is not a hint, and does in fact
15328 constrain the usage of the mapped data store on some GL implementations.
15329 In order to achieve the highest performance available, a buffer object's
15330 data store should be used in ways consistent with both its specified
15331 @var{usage} and @var{access} parameters.
15333 A mapped data store must be unmapped with @code{glUnmapBuffer} before
15334 its buffer object is used. Otherwise an error will be generated by any
15335 GL command that attempts to dereference the buffer object's data store.
15336 When a data store is unmapped, the pointer to its data store becomes
15337 invalid. @code{glUnmapBuffer} returns @code{GL_TRUE} unless the data
15338 store contents have become corrupt during the time the data store was
15339 mapped. This can occur for system-specific reasons that affect the
15340 availability of graphics memory, such as screen mode changes. In such
15341 situations, @code{GL_FALSE} is returned and the data store contents are
15342 undefined. An application must detect this rare condition and
15343 reinitialize the data store.
15345 A buffer object's mapped data store is automatically unmapped when the
15346 buffer object is deleted or its data store is recreated with
15347 @code{glBufferData}.
15349 @code{GL_INVALID_ENUM} is generated if @var{target} is not
15350 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
15351 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
15353 @code{GL_INVALID_ENUM} is generated if @var{access} is not
15354 @code{GL_READ_ONLY}, @code{GL_WRITE_ONLY}, or @code{GL_READ_WRITE}.
15356 @code{GL_OUT_OF_MEMORY} is generated when @code{glMapBuffer} is executed
15357 if the GL is unable to map the buffer object's data store. This may
15358 occur for a variety of system-specific reasons, such as the absence of
15359 sufficient remaining virtual memory.
15361 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
15362 name 0 is bound to @var{target}.
15364 @code{GL_INVALID_OPERATION} is generated if @code{glMapBuffer} is
15365 executed for a buffer object whose data store is already mapped.
15367 @code{GL_INVALID_OPERATION} is generated if @code{glUnmapBuffer} is
15368 executed for a buffer object whose data store is not currently mapped.
15370 @code{GL_INVALID_OPERATION} is generated if @code{glMapBuffer} or
15371 @code{glUnmapBuffer} is executed between the execution of @code{glBegin}
15372 and the corresponding execution of @code{glEnd}.
15376 @deftypefun void glMapGrid1d un u1 u2
15377 @deftypefunx void glMapGrid1f un u1 u2
15378 @deftypefunx void glMapGrid2d un u1 u2 vn v1 v2
15379 @deftypefunx void glMapGrid2f un u1 u2 vn v1 v2
15380 Define a one- or two-dimensional mesh.
15384 Specifies the number of partitions in the grid range interval [@var{u1},
15385 @var{u2}]. Must be positive.
15389 Specify the mappings for integer grid domain values @r{@var{i}=0} and
15390 @r{@var{i}=@var{un}}.
15393 Specifies the number of partitions in the grid range interval [@var{v1},
15394 @var{v2}] (@code{glMapGrid2} only).
15398 Specify the mappings for integer grid domain values @r{@var{j}=0} and
15399 @r{@var{j}=@var{vn}} (@code{glMapGrid2} only).
15403 @code{glMapGrid} and @code{glEvalMesh} are used together to efficiently
15404 generate and evaluate a series of evenly-spaced map domain values.
15405 @code{glEvalMesh} steps through the integer domain of a one- or
15406 two-dimensional grid, whose range is the domain of the evaluation maps
15407 specified by @code{glMap1} and @code{glMap2}.
15409 @code{glMapGrid1} and @code{glMapGrid2} specify the linear grid mappings
15410 between the @r{@var{i}} (or @r{@var{i}} and @r{@var{j}}) integer grid
15411 coordinates, to the @r{@var{u}} (or @r{@var{u}} and @r{@var{v}})
15412 floating-point evaluation map coordinates. See @code{glMap1} and
15413 @code{glMap2} for details of how @r{@var{u}} and @r{@var{v}} coordinates
15416 @code{glMapGrid1} specifies a single linear mapping such that integer
15417 grid coordinate 0 maps exactly to @var{u1}, and integer grid coordinate
15418 @var{un} maps exactly to @var{u2}. All other integer grid coordinates
15419 @r{@var{i}} are mapped so that
15421 @r{@var{u}=@var{i}(@var{u2}-@var{u1},)/@var{un}+@var{u1}}
15423 @code{glMapGrid2} specifies two such linear mappings. One maps integer
15424 grid coordinate @r{@var{i}=0} exactly to @var{u1}, and integer grid
15425 coordinate @r{@var{i}=@var{un}} exactly to @var{u2}. The other maps
15426 integer grid coordinate @r{@var{j}=0} exactly to @var{v1}, and integer
15427 grid coordinate @r{@var{j}=@var{vn}} exactly to @var{v2}. Other integer
15428 grid coordinates @r{@var{i}} and @r{@var{j}} are mapped such that
15430 @r{@var{u}=@var{i}(@var{u2}-@var{u1},)/@var{un}+@var{u1}}
15432 @r{@var{v}=@var{j}(@var{v2}-@var{v1},)/@var{vn}+@var{v1}}
15434 The mappings specified by @code{glMapGrid} are used identically by
15435 @code{glEvalMesh} and @code{glEvalPoint}.
15437 @code{GL_INVALID_VALUE} is generated if either @var{un} or @var{vn} is
15440 @code{GL_INVALID_OPERATION} is generated if @code{glMapGrid} is executed
15441 between the execution of @code{glBegin} and the corresponding execution
15446 @deftypefun void glMaterialf face pname param
15447 @deftypefunx void glMateriali face pname param
15448 @deftypefunx void glMaterialfv face pname params
15449 @deftypefunx void glMaterialiv face pname params
15450 Specify material parameters for the lighting model.
15454 Specifies which face or faces are being updated. Must be one of
15455 @code{GL_FRONT}, @code{GL_BACK}, or @code{GL_FRONT_AND_BACK}.
15458 Specifies the single-valued material parameter of the face or faces that
15459 is being updated. Must be @code{GL_SHININESS}.
15462 Specifies the value that parameter @code{GL_SHININESS} will be set to.
15466 @code{glMaterial} assigns values to material parameters. There are two
15467 matched sets of material parameters. One, the @var{front-facing} set,
15468 is used to shade points, lines, bitmaps, and all polygons (when
15469 two-sided lighting is disabled), or just front-facing polygons (when
15470 two-sided lighting is enabled). The other set, @var{back-facing}, is
15471 used to shade back-facing polygons only when two-sided lighting is
15472 enabled. Refer to the @code{glLightModel} reference page for details
15473 concerning one- and two-sided lighting calculations.
15475 @code{glMaterial} takes three arguments. The first, @var{face},
15476 specifies whether the @code{GL_FRONT} materials, the @code{GL_BACK}
15477 materials, or both @code{GL_FRONT_AND_BACK} materials will be modified.
15478 The second, @var{pname}, specifies which of several parameters in one or
15479 both sets will be modified. The third, @var{params}, specifies what
15480 value or values will be assigned to the specified parameter.
15482 Material parameters are used in the lighting equation that is optionally
15483 applied to each vertex. The equation is discussed in the
15484 @code{glLightModel} reference page. The parameters that can be
15485 specified using @code{glMaterial}, and their interpretations by the
15486 lighting equation, are as follows:
15489 @item @code{GL_AMBIENT}
15490 @var{params} contains four integer or floating-point values that specify
15491 the ambient RGBA reflectance of the material. Integer values are mapped
15492 linearly such that the most positive representable value maps to 1.0,
15493 and the most negative representable value maps to @r{-1.0}.
15494 Floating-point values are mapped directly. Neither integer nor
15495 floating-point values are clamped. The initial ambient reflectance for
15496 both front- and back-facing materials is (0.2, 0.2, 0.2, 1.0).
15498 @item @code{GL_DIFFUSE}
15499 @var{params} contains four integer or floating-point values that specify
15500 the diffuse RGBA reflectance of the material. Integer values are mapped
15501 linearly such that the most positive representable value maps to 1.0,
15502 and the most negative representable value maps to @r{-1.0}.
15503 Floating-point values are mapped directly. Neither integer nor
15504 floating-point values are clamped. The initial diffuse reflectance for
15505 both front- and back-facing materials is (0.8, 0.8, 0.8, 1.0).
15507 @item @code{GL_SPECULAR}
15508 @var{params} contains four integer or floating-point values that specify
15509 the specular RGBA reflectance of the material. Integer values are
15510 mapped linearly such that the most positive representable value maps to
15511 1.0, and the most negative representable value maps to @r{-1.0}.
15512 Floating-point values are mapped directly. Neither integer nor
15513 floating-point values are clamped. The initial specular reflectance for
15514 both front- and back-facing materials is (0, 0, 0, 1).
15516 @item @code{GL_EMISSION}
15517 @var{params} contains four integer or floating-point values that specify
15518 the RGBA emitted light intensity of the material. Integer values are
15519 mapped linearly such that the most positive representable value maps to
15520 1.0, and the most negative representable value maps to @r{-1.0}.
15521 Floating-point values are mapped directly. Neither integer nor
15522 floating-point values are clamped. The initial emission intensity for
15523 both front- and back-facing materials is (0, 0, 0, 1).
15525 @item @code{GL_SHININESS}
15526 @var{params} is a single integer or floating-point value that specifies
15527 the RGBA specular exponent of the material. Integer and floating-point
15528 values are mapped directly. Only values in the range @r{[0,128]} are
15529 accepted. The initial specular exponent for both front- and back-facing
15532 @item @code{GL_AMBIENT_AND_DIFFUSE}
15533 Equivalent to calling @code{glMaterial} twice with the same parameter
15534 values, once with @code{GL_AMBIENT} and once with @code{GL_DIFFUSE}.
15536 @item @code{GL_COLOR_INDEXES}
15537 @var{params} contains three integer or floating-point values specifying
15538 the color indices for ambient, diffuse, and specular lighting. These
15539 three values, and @code{GL_SHININESS}, are the only material values used
15540 by the color index mode lighting equation. Refer to the
15541 @code{glLightModel} reference page for a discussion of color index
15546 @code{GL_INVALID_ENUM} is generated if either @var{face} or @var{pname}
15547 is not an accepted value.
15549 @code{GL_INVALID_VALUE} is generated if a specular exponent outside the
15550 range @r{[0,128]} is specified.
15554 @deftypefun void glMatrixMode mode
15555 Specify which matrix is the current matrix.
15559 Specifies which matrix stack is the target for subsequent matrix
15560 operations. Three values are accepted: @code{GL_MODELVIEW},
15561 @code{GL_PROJECTION}, and @code{GL_TEXTURE}. The initial value is
15562 @code{GL_MODELVIEW}. Additionally, if the @code{ARB_imaging} extension
15563 is supported, @code{GL_COLOR} is also accepted.
15567 @code{glMatrixMode} sets the current matrix mode. @var{mode} can assume
15568 one of four values:
15571 @item @code{GL_MODELVIEW}
15572 Applies subsequent matrix operations to the modelview matrix stack.
15574 @item @code{GL_PROJECTION}
15575 Applies subsequent matrix operations to the projection matrix stack.
15577 @item @code{GL_TEXTURE}
15578 Applies subsequent matrix operations to the texture matrix stack.
15580 @item @code{GL_COLOR}
15581 Applies subsequent matrix operations to the color matrix stack.
15585 To find out which matrix stack is currently the target of all matrix
15586 operations, call @code{glGet} with argument @code{GL_MATRIX_MODE}. The
15587 initial value is @code{GL_MODELVIEW}.
15589 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
15592 @code{GL_INVALID_OPERATION} is generated if @code{glMatrixMode} is
15593 executed between the execution of @code{glBegin} and the corresponding
15594 execution of @code{glEnd}.
15598 @deftypefun void glMinmax target internalformat sink
15599 Define minmax table.
15603 The minmax table whose parameters are to be set. Must be
15606 @item @var{internalformat}
15607 The format of entries in the minmax table. Must be one of
15608 @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
15609 @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
15610 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
15611 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
15612 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
15613 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
15614 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
15615 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
15616 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
15617 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
15618 @code{GL_RGBA12}, or @code{GL_RGBA16}.
15621 If @code{GL_TRUE}, pixels will be consumed by the minmax process and no
15622 drawing or texture loading will take place. If @code{GL_FALSE}, pixels
15623 will proceed to the final conversion process after minmax.
15627 When @code{GL_MINMAX} is enabled, the RGBA components of incoming pixels
15628 are compared to the minimum and maximum values for each component, which
15629 are stored in the two-element minmax table. (The first element stores
15630 the minima, and the second element stores the maxima.) If a pixel
15631 component is greater than the corresponding component in the maximum
15632 element, then the maximum element is updated with the pixel component
15633 value. If a pixel component is less than the corresponding component in
15634 the minimum element, then the minimum element is updated with the pixel
15635 component value. (In both cases, if the internal format of the minmax
15636 table includes luminance, then the R color component of incoming pixels
15637 is used for comparison.) The contents of the minmax table may be
15638 retrieved at a later time by calling @code{glGetMinmax}. The minmax
15639 operation is enabled or disabled by calling @code{glEnable} or
15640 @code{glDisable}, respectively, with an argument of @code{GL_MINMAX}.
15642 @code{glMinmax} redefines the current minmax table to have entries of
15643 the format specified by @var{internalformat}. The maximum element is
15644 initialized with the smallest possible component values, and the minimum
15645 element is initialized with the largest possible component values. The
15646 values in the previous minmax table, if any, are lost. If @var{sink} is
15647 @code{GL_TRUE}, then pixels are discarded after minmax; no further
15648 processing of the pixels takes place, and no drawing, texture loading,
15649 or pixel readback will result.
15653 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
15656 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
15657 of the allowable values.
15659 @code{GL_INVALID_OPERATION} is generated if @code{glMinmax} is executed
15660 between the execution of @code{glBegin} and the corresponding execution
15665 @deftypefun void glMultiDrawArrays mode first count primcount
15666 Render multiple sets of primitives from array data.
15670 Specifies what kind of primitives to render. Symbolic constants
15671 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
15672 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
15673 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
15674 @code{GL_POLYGON} are accepted.
15677 Points to an array of starting indices in the enabled arrays.
15680 Points to an array of the number of indices to be rendered.
15682 @item @var{primcount}
15683 Specifies the size of the first and count
15687 @code{glMultiDrawArrays} specifies multiple sets of geometric primitives
15688 with very few subroutine calls. Instead of calling a GL procedure to
15689 pass each individual vertex, normal, texture coordinate, edge flag, or
15690 color, you can prespecify separate arrays of vertices, normals, and
15691 colors and use them to construct a sequence of primitives with a single
15692 call to @code{glMultiDrawArrays}.
15694 @code{glMultiDrawArrays} behaves identically to @code{glDrawArrays}
15695 except that @var{primcount} separate ranges of elements are specified
15698 When @code{glMultiDrawArrays} is called, it uses @var{count} sequential
15699 elements from each enabled array to construct a sequence of geometric
15700 primitives, beginning with element @var{first}. @var{mode} specifies
15701 what kind of primitives are constructed, and how the array elements
15702 construct those primitives. If @code{GL_VERTEX_ARRAY} is not enabled,
15703 no geometric primitives are generated.
15705 Vertex attributes that are modified by @code{glMultiDrawArrays} have an
15706 unspecified value after @code{glMultiDrawArrays} returns. For example,
15707 if @code{GL_COLOR_ARRAY} is enabled, the value of the current color is
15708 undefined after @code{glMultiDrawArrays} executes. Attributes that
15709 aren't modified remain well defined.
15711 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
15714 @code{GL_INVALID_VALUE} is generated if @var{primcount} is negative.
15716 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
15717 name is bound to an enabled array and the buffer object's data store is
15720 @code{GL_INVALID_OPERATION} is generated if @code{glMultiDrawArrays} is
15721 executed between the execution of @code{glBegin} and the corresponding
15726 @deftypefun void glMultiDrawElements mode count type indices primcount
15727 Render multiple sets of primitives by specifying indices of array data
15732 Specifies what kind of primitives to render. Symbolic constants
15733 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
15734 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
15735 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
15736 @code{GL_POLYGON} are accepted.
15739 Points to an array of the elements counts.
15742 Specifies the type of the values in @var{indices}. Must be one of
15743 @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or
15744 @code{GL_UNSIGNED_INT}.
15746 @item @var{indices}
15747 Specifies a pointer to the location where the indices are stored.
15749 @item @var{primcount}
15750 Specifies the size of the @var{count} array.
15754 @code{glMultiDrawElements} specifies multiple sets of geometric
15755 primitives with very few subroutine calls. Instead of calling a GL
15756 function to pass each individual vertex, normal, texture coordinate,
15757 edge flag, or color, you can prespecify separate arrays of vertices,
15758 normals, and so on, and use them to construct a sequence of primitives
15759 with a single call to @code{glMultiDrawElements}.
15761 @code{glMultiDrawElements} is identical in operation to
15762 @code{glDrawElements} except that @var{primcount} separate lists of
15763 elements are specified.
15765 Vertex attributes that are modified by @code{glMultiDrawElements} have
15766 an unspecified value after @code{glMultiDrawElements} returns. For
15767 example, if @code{GL_COLOR_ARRAY} is enabled, the value of the current
15768 color is undefined after @code{glMultiDrawElements} executes. Attributes
15769 that aren't modified maintain their previous values.
15771 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
15774 @code{GL_INVALID_VALUE} is generated if @var{primcount} is negative.
15776 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
15777 name is bound to an enabled array or the element array and the buffer
15778 object's data store is currently mapped.
15780 @code{GL_INVALID_OPERATION} is generated if @code{glMultiDrawElements}
15781 is executed between the execution of @code{glBegin} and the
15782 corresponding @code{glEnd}.
15786 @deftypefun void glMultiTexCoord1s target s
15787 @deftypefunx void glMultiTexCoord1i target s
15788 @deftypefunx void glMultiTexCoord1f target s
15789 @deftypefunx void glMultiTexCoord1d target s
15790 @deftypefunx void glMultiTexCoord2s target s t
15791 @deftypefunx void glMultiTexCoord2i target s t
15792 @deftypefunx void glMultiTexCoord2f target s t
15793 @deftypefunx void glMultiTexCoord2d target s t
15794 @deftypefunx void glMultiTexCoord3s target s t r
15795 @deftypefunx void glMultiTexCoord3i target s t r
15796 @deftypefunx void glMultiTexCoord3f target s t r
15797 @deftypefunx void glMultiTexCoord3d target s t r
15798 @deftypefunx void glMultiTexCoord4s target s t r q
15799 @deftypefunx void glMultiTexCoord4i target s t r q
15800 @deftypefunx void glMultiTexCoord4f target s t r q
15801 @deftypefunx void glMultiTexCoord4d target s t r q
15802 @deftypefunx void glMultiTexCoord1sv target v
15803 @deftypefunx void glMultiTexCoord1iv target v
15804 @deftypefunx void glMultiTexCoord1fv target v
15805 @deftypefunx void glMultiTexCoord1dv target v
15806 @deftypefunx void glMultiTexCoord2sv target v
15807 @deftypefunx void glMultiTexCoord2iv target v
15808 @deftypefunx void glMultiTexCoord2fv target v
15809 @deftypefunx void glMultiTexCoord2dv target v
15810 @deftypefunx void glMultiTexCoord3sv target v
15811 @deftypefunx void glMultiTexCoord3iv target v
15812 @deftypefunx void glMultiTexCoord3fv target v
15813 @deftypefunx void glMultiTexCoord3dv target v
15814 @deftypefunx void glMultiTexCoord4sv target v
15815 @deftypefunx void glMultiTexCoord4iv target v
15816 @deftypefunx void glMultiTexCoord4fv target v
15817 @deftypefunx void glMultiTexCoord4dv target v
15818 Set the current texture coordinates.
15822 Specifies the texture unit whose coordinates should be modified. The
15823 number of texture units is implementation dependent, but must be at
15824 least two. Symbolic constant must be one of
15825 @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to
15826 @code{GL_MAX_TEXTURE_COORDS} - 1, which is an implementation-dependent
15833 Specify @var{s}, @var{t}, @var{r}, and @var{q} texture coordinates for
15834 @var{target} texture unit. Not all parameters are present in all forms
15839 @code{glMultiTexCoord} specifies texture coordinates in one, two, three,
15840 or four dimensions. @code{glMultiTexCoord1} sets the current texture
15841 coordinates to @r{(@var{s},001)}; a call to @code{glMultiTexCoord2} sets
15842 them to @r{(@var{s},@var{t}01)}. Similarly, @code{glMultiTexCoord3}
15843 specifies the texture coordinates as @r{(@var{s},@var{t}@var{r}1)}, and
15844 @code{glMultiTexCoord4} defines all four components explicitly as
15845 @r{(@var{s},@var{t}@var{r}@var{q})}.
15847 The current texture coordinates are part of the data that is associated
15848 with each vertex and with the current raster position. Initially, the
15849 values for @r{(@var{s},@var{t}@var{r}@var{q})} are @r{(0,001)}.
15855 @deftypefun void glMultMatrixd m
15856 @deftypefunx void glMultMatrixf m
15857 Multiply the current matrix with the specified matrix.
15861 Points to 16 consecutive values that are used as the elements of a
15862 @r{4×4} column-major matrix.
15866 @code{glMultMatrix} multiplies the current matrix with the one specified
15867 using @var{m}, and replaces the current matrix with the product.
15869 The current matrix is determined by the current matrix mode (see
15870 @code{glMatrixMode}). It is either the projection matrix, modelview
15871 matrix, or the texture matrix.
15873 @code{GL_INVALID_OPERATION} is generated if @code{glMultMatrix} is
15874 executed between the execution of @code{glBegin} and the corresponding
15875 execution of @code{glEnd}.
15879 @deftypefun void glMultTransposeMatrixd m
15880 @deftypefunx void glMultTransposeMatrixf m
15881 Multiply the current matrix with the specified row-major ordered matrix.
15885 Points to 16 consecutive values that are used as the elements of a
15886 @r{4×4} row-major matrix.
15890 @code{glMultTransposeMatrix} multiplies the current matrix with the one
15891 specified using @var{m}, and replaces the current matrix with the
15894 The current matrix is determined by the current matrix mode (see
15895 @code{glMatrixMode}). It is either the projection matrix, modelview
15896 matrix, or the texture matrix.
15898 @code{GL_INVALID_OPERATION} is generated if @code{glMultTransposeMatrix}
15899 is executed between the execution of @code{glBegin} and the
15900 corresponding execution of @code{glEnd}.
15904 @deftypefun void glNewList list mode
15905 @deftypefunx void glEndList
15906 Create or replace a display list.
15910 Specifies the display-list name.
15913 Specifies the compilation mode, which can be @code{GL_COMPILE} or
15914 @code{GL_COMPILE_AND_EXECUTE}.
15918 Display lists are groups of GL commands that have been stored for
15919 subsequent execution. Display lists are created with @code{glNewList}.
15920 All subsequent commands are placed in the display list, in the order
15921 issued, until @code{glEndList} is called.
15923 @code{glNewList} has two arguments. The first argument, @var{list}, is
15924 a positive integer that becomes the unique name for the display list.
15925 Names can be created and reserved with @code{glGenLists} and tested for
15926 uniqueness with @code{glIsList}. The second argument, @var{mode}, is a
15927 symbolic constant that can assume one of two values:
15930 @item @code{GL_COMPILE}
15931 Commands are merely compiled.
15933 @item @code{GL_COMPILE_AND_EXECUTE}
15934 Commands are executed as they are compiled into the display list.
15938 Certain commands are not compiled into the display list but are executed
15939 immediately, regardless of the display-list mode. These commands are
15940 @code{glAreTexturesResident}, @code{glColorPointer},
15941 @code{glDeleteLists}, @code{glDeleteTextures},
15942 @code{glDisableClientState}, @code{glEdgeFlagPointer},
15943 @code{glEnableClientState}, @code{glFeedbackBuffer}, @code{glFinish},
15944 @code{glFlush}, @code{glGenLists}, @code{glGenTextures},
15945 @code{glIndexPointer}, @code{glInterleavedArrays}, @code{glIsEnabled},
15946 @code{glIsList}, @code{glIsTexture}, @code{glNormalPointer},
15947 @code{glPopClientAttrib}, @code{glPixelStore},
15948 @code{glPushClientAttrib}, @code{glReadPixels}, @code{glRenderMode},
15949 @code{glSelectBuffer}, @code{glTexCoordPointer}, @code{glVertexPointer},
15950 and all of the @code{glGet} commands.
15952 Similarly, @code{glTexImage1D}, @code{glTexImage2D}, and
15953 @code{glTexImage3D} are executed immediately and not compiled into the
15954 display list when their first argument is @code{GL_PROXY_TEXTURE_1D},
15955 @code{GL_PROXY_TEXTURE_1D}, or @code{GL_PROXY_TEXTURE_3D}, respectively.
15957 When the @code{ARB_imaging} extension is supported, @code{glHistogram}
15958 executes immediately when its argument is @code{GL_PROXY_HISTOGRAM}.
15959 Similarly, @code{glColorTable} executes immediately when its first
15960 argument is @code{GL_PROXY_COLOR_TABLE},
15961 @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or
15962 @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}.
15964 For OpenGL versions 1.3 and greater, or when the @code{ARB_multitexture}
15965 extension is supported, @code{glClientActiveTexture} is not compiled
15966 into display lists, but executed immediately.
15968 When @code{glEndList} is encountered, the display-list definition is
15969 completed by associating the list with the unique name @var{list}
15970 (specified in the @code{glNewList} command). If a display list with
15971 name @var{list} already exists, it is replaced only when
15972 @code{glEndList} is called.
15974 @code{GL_INVALID_VALUE} is generated if @var{list} is 0.
15976 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
15979 @code{GL_INVALID_OPERATION} is generated if @code{glEndList} is called
15980 without a preceding @code{glNewList}, or if @code{glNewList} is called
15981 while a display list is being defined.
15983 @code{GL_INVALID_OPERATION} is generated if @code{glNewList} or
15984 @code{glEndList} is executed between the execution of @code{glBegin} and
15985 the corresponding execution of @code{glEnd}.
15987 @code{GL_OUT_OF_MEMORY} is generated if there is insufficient memory to
15988 compile the display list. If the GL version is 1.1 or greater, no
15989 change is made to the previous contents of the display list, if any, and
15990 no other change is made to the GL state. (It is as if no attempt had
15991 been made to create the new display list.)
15995 @deftypefun void glNormalPointer type stride pointer
15996 Define an array of normals.
16000 Specifies the data type of each coordinate in the array. Symbolic
16001 constants @code{GL_BYTE}, @code{GL_SHORT}, @code{GL_INT},
16002 @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value
16003 is @code{GL_FLOAT}.
16006 Specifies the byte offset between consecutive normals. If @var{stride}
16007 is 0, the normals are understood to be tightly packed in the array. The
16008 initial value is 0.
16010 @item @var{pointer}
16011 Specifies a pointer to the first coordinate of the first normal in the
16012 array. The initial value is 0.
16016 @code{glNormalPointer} specifies the location and data format of an
16017 array of normals to use when rendering. @var{type} specifies the data
16018 type of each normal coordinate, and @var{stride} specifies the byte
16019 stride from one normal to the next, allowing vertices and attributes to
16020 be packed into a single array or stored in separate arrays.
16021 (Single-array storage may be more efficient on some implementations; see
16022 @code{glInterleavedArrays}.)
16024 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
16025 target (see @code{glBindBuffer}) while a normal array is specified,
16026 @var{pointer} is treated as a byte offset into the buffer object's data
16027 store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING})
16028 is saved as normal vertex array client-side state
16029 (@code{GL_NORMAL_ARRAY_BUFFER_BINDING}).
16031 When a normal array is specified, @var{type}, @var{stride}, and
16032 @var{pointer} are saved as client-side state, in addition to the current
16033 vertex array buffer object binding.
16035 To enable and disable the normal array, call @code{glEnableClientState}
16036 and @code{glDisableClientState} with the argument
16037 @code{GL_NORMAL_ARRAY}. If enabled, the normal array is used when
16038 @code{glDrawArrays}, @code{glMultiDrawArrays}, @code{glDrawElements},
16039 @code{glMultiDrawElements}, @code{glDrawRangeElements}, or
16040 @code{glArrayElement} is called.
16042 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
16045 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
16049 @deftypefun void glNormal3b nx ny nz
16050 @deftypefunx void glNormal3d nx ny nz
16051 @deftypefunx void glNormal3f nx ny nz
16052 @deftypefunx void glNormal3i nx ny nz
16053 @deftypefunx void glNormal3s nx ny nz
16054 @deftypefunx void glNormal3bv v
16055 @deftypefunx void glNormal3dv v
16056 @deftypefunx void glNormal3fv v
16057 @deftypefunx void glNormal3iv v
16058 @deftypefunx void glNormal3sv v
16059 Set the current normal vector.
16065 Specify the @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} coordinates of the
16066 new current normal. The initial value of the current normal is the unit
16073 The current normal is set to the given coordinates whenever
16074 @code{glNormal} is issued. Byte, short, or integer arguments are
16075 converted to floating-point format with a linear mapping that maps the
16076 most positive representable integer value to 1.0 and the most negative
16077 representable integer value to @r{-1.0}.
16079 Normals specified with @code{glNormal} need not have unit length. If
16080 @code{GL_NORMALIZE} is enabled, then normals of any length specified
16081 with @code{glNormal} are normalized after transformation. If
16082 @code{GL_RESCALE_NORMAL} is enabled, normals are scaled by a scaling
16083 factor derived from the modelview matrix. @code{GL_RESCALE_NORMAL}
16084 requires that the originally specified normals were of unit length, and
16085 that the modelview matrix contain only uniform scales for proper
16086 results. To enable and disable normalization, call @code{glEnable} and
16087 @code{glDisable} with either @code{GL_NORMALIZE} or
16088 @code{GL_RESCALE_NORMAL}. Normalization is initially disabled.
16092 @deftypefun void glOrtho left right bottom top nearVal farVal
16093 Multiply the current matrix with an orthographic matrix.
16098 Specify the coordinates for the left and right vertical clipping planes.
16102 Specify the coordinates for the bottom and top horizontal clipping
16105 @item @var{nearVal}
16106 @itemx @var{farVal}
16107 Specify the distances to the nearer and farther depth clipping planes.
16108 These values are negative if the plane is to be behind the viewer.
16112 @code{glOrtho} describes a transformation that produces a parallel
16113 projection. The current matrix (see @code{glMatrixMode}) is multiplied
16114 by this matrix and the result replaces the current matrix, as if
16115 @code{glMultMatrix} were called with the following matrix as its
16118 @r{((2/@var{right}-@var{left},, 0 0 @var{t}_@var{x},), (0
16119 2/@var{top}-@var{bottom},, 0 @var{t}_@var{y},), (0 0
16120 -2/@var{farVal}-@var{nearVal},, @var{t}_@var{z},), (0 0 0 1),)}
16123 @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},,}
16125 Typically, the matrix mode is @code{GL_PROJECTION}, and
16126 @r{(@var{left},@var{bottom}-@var{nearVal})} and
16127 @r{(@var{right},@var{top}-@var{nearVal})} specify the points on the near
16128 clipping plane that are mapped to the lower left and upper right corners
16129 of the window, respectively, assuming that the eye is located at (0, 0,
16130 0). @r{-@var{farVal}} specifies the location of the far clipping plane.
16131 Both @var{nearVal} and @var{farVal} can be either positive or negative.
16133 Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the
16134 current matrix stack.
16136 @code{GL_INVALID_VALUE} is generated if @var{left} = @var{right}, or
16137 @var{bottom} = @var{top}, or @var{near} = @var{far}.
16139 @code{GL_INVALID_OPERATION} is generated if @code{glOrtho} is executed
16140 between the execution of @code{glBegin} and the corresponding execution
16145 @deftypefun void glPassThrough token
16146 Place a marker in the feedback buffer.
16150 Specifies a marker value to be placed in the feedback buffer following a
16151 @code{GL_PASS_THROUGH_TOKEN}.
16157 Feedback is a GL render mode. The mode is selected by calling
16158 @code{glRenderMode} with @code{GL_FEEDBACK}. When the GL is in feedback
16159 mode, no pixels are produced by rasterization. Instead, information
16160 about primitives that would have been rasterized is fed back to the
16161 application using the GL. See the @code{glFeedbackBuffer} reference
16162 page for a description of the feedback buffer and the values in it.
16164 @code{glPassThrough} inserts a user-defined marker in the feedback
16165 buffer when it is executed in feedback mode. @var{token} is returned as
16166 if it were a primitive; it is indicated with its own unique identifying
16167 value: @code{GL_PASS_THROUGH_TOKEN}. The order of @code{glPassThrough}
16168 commands with respect to the specification of graphics primitives is
16171 @code{GL_INVALID_OPERATION} is generated if @code{glPassThrough} is
16172 executed between the execution of @code{glBegin} and the corresponding
16173 execution of @code{glEnd}.
16177 @deftypefun void glPixelMapfv map mapsize values
16178 @deftypefunx void glPixelMapuiv map mapsize values
16179 @deftypefunx void glPixelMapusv map mapsize values
16180 Set up pixel transfer maps.
16184 Specifies a symbolic map name. Must be one of the following:
16185 @code{GL_PIXEL_MAP_I_TO_I}, @code{GL_PIXEL_MAP_S_TO_S},
16186 @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G},
16187 @code{GL_PIXEL_MAP_I_TO_B}, @code{GL_PIXEL_MAP_I_TO_A},
16188 @code{GL_PIXEL_MAP_R_TO_R}, @code{GL_PIXEL_MAP_G_TO_G},
16189 @code{GL_PIXEL_MAP_B_TO_B}, or @code{GL_PIXEL_MAP_A_TO_A}.
16191 @item @var{mapsize}
16192 Specifies the size of the map being defined.
16195 Specifies an array of @var{mapsize} values.
16199 @code{glPixelMap} sets up translation tables, or @var{maps}, used by
16200 @code{glCopyPixels}, @code{glCopyTexImage1D}, @code{glCopyTexImage2D},
16201 @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D},
16202 @code{glCopyTexSubImage3D}, @code{glDrawPixels}, @code{glReadPixels},
16203 @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D},
16204 @code{glTexSubImage1D}, @code{glTexSubImage2D}, and
16205 @code{glTexSubImage3D}. Additionally, if the @code{ARB_imaging} subset
16206 is supported, the routines @code{glColorTable}, @code{glColorSubTable},
16207 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D},
16208 @code{glHistogram}, @code{glMinmax}, and @code{glSeparableFilter2D}. Use
16209 of these maps is described completely in the @code{glPixelTransfer}
16210 reference page, and partly in the reference pages for the pixel and
16211 texture image commands. Only the specification of the maps is described
16212 in this reference page.
16214 @var{map} is a symbolic map name, indicating one of ten maps to set.
16215 @var{mapsize} specifies the number of entries in the map, and
16216 @var{values} is a pointer to an array of @var{mapsize} map values.
16218 If a non-zero named buffer object is bound to the
16219 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
16220 pixel transfer map is specified, @var{values} is treated as a byte
16221 offset into the buffer object's data store.
16223 The ten maps are as follows:
16226 @item @code{GL_PIXEL_MAP_I_TO_I}
16227 Maps color indices to color indices.
16229 @item @code{GL_PIXEL_MAP_S_TO_S}
16230 Maps stencil indices to stencil indices.
16232 @item @code{GL_PIXEL_MAP_I_TO_R}
16233 Maps color indices to red components.
16235 @item @code{GL_PIXEL_MAP_I_TO_G}
16236 Maps color indices to green components.
16238 @item @code{GL_PIXEL_MAP_I_TO_B}
16239 Maps color indices to blue components.
16241 @item @code{GL_PIXEL_MAP_I_TO_A}
16242 Maps color indices to alpha components.
16244 @item @code{GL_PIXEL_MAP_R_TO_R}
16245 Maps red components to red components.
16247 @item @code{GL_PIXEL_MAP_G_TO_G}
16248 Maps green components to green components.
16250 @item @code{GL_PIXEL_MAP_B_TO_B}
16251 Maps blue components to blue components.
16253 @item @code{GL_PIXEL_MAP_A_TO_A}
16254 Maps alpha components to alpha components.
16258 The entries in a map can be specified as single-precision floating-point
16259 numbers, unsigned short integers, or unsigned int integers. Maps that
16260 store color component values (all but @code{GL_PIXEL_MAP_I_TO_I} and
16261 @code{GL_PIXEL_MAP_S_TO_S}) retain their values in floating-point
16262 format, with unspecified mantissa and exponent sizes. Floating-point
16263 values specified by @code{glPixelMapfv} are converted directly to the
16264 internal floating-point format of these maps, then clamped to the range
16265 [0,1]. Unsigned integer values specified by @code{glPixelMapusv} and
16266 @code{glPixelMapuiv} are converted linearly such that the largest
16267 representable integer maps to 1.0, and 0 maps to 0.0.
16269 Maps that store indices, @code{GL_PIXEL_MAP_I_TO_I} and
16270 @code{GL_PIXEL_MAP_S_TO_S}, retain their values in fixed-point format,
16271 with an unspecified number of bits to the right of the binary point.
16272 Floating-point values specified by @code{glPixelMapfv} are converted
16273 directly to the internal fixed-point format of these maps. Unsigned
16274 integer values specified by @code{glPixelMapusv} and
16275 @code{glPixelMapuiv} specify integer values, with all 0's to the right
16276 of the binary point.
16278 The following table shows the initial sizes and values for each of the
16279 maps. Maps that are indexed by either color or stencil indices must
16280 have @var{mapsize} = @r{2^@var{n}} for some @r{@var{n}} or the results
16281 are undefined. The maximum allowable size for each map depends on the
16282 implementation and can be determined by calling @code{glGet} with
16283 argument @code{GL_MAX_PIXEL_MAP_TABLE}. The single maximum applies to
16284 all maps; it is at least 32.
16287 @item @strong{@var{map}}
16288 @strong{Lookup Index}, @strong{Lookup Value}, @strong{Initial Size},
16289 @strong{Initial Value}
16291 @item @code{GL_PIXEL_MAP_I_TO_I}
16292 color index , color index , 1 , 0
16294 @item @code{GL_PIXEL_MAP_S_TO_S}
16295 stencil index , stencil index , 1 , 0
16297 @item @code{GL_PIXEL_MAP_I_TO_R}
16298 color index , R , 1 , 0
16300 @item @code{GL_PIXEL_MAP_I_TO_G}
16301 color index , G , 1 , 0
16303 @item @code{GL_PIXEL_MAP_I_TO_B}
16304 color index , B , 1 , 0
16306 @item @code{GL_PIXEL_MAP_I_TO_A}
16307 color index , A , 1 , 0
16309 @item @code{GL_PIXEL_MAP_R_TO_R}
16312 @item @code{GL_PIXEL_MAP_G_TO_G}
16315 @item @code{GL_PIXEL_MAP_B_TO_B}
16318 @item @code{GL_PIXEL_MAP_A_TO_A}
16323 @code{GL_INVALID_ENUM} is generated if @var{map} is not an accepted
16326 @code{GL_INVALID_VALUE} is generated if @var{mapsize} is less than one
16327 or larger than @code{GL_MAX_PIXEL_MAP_TABLE}.
16329 @code{GL_INVALID_VALUE} is generated if @var{map} is
16330 @code{GL_PIXEL_MAP_I_TO_I}, @code{GL_PIXEL_MAP_S_TO_S},
16331 @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G},
16332 @code{GL_PIXEL_MAP_I_TO_B}, or @code{GL_PIXEL_MAP_I_TO_A}, and
16333 @var{mapsize} is not a power of two.
16335 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
16336 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
16337 object's data store is currently mapped.
16339 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
16340 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
16341 would be unpacked from the buffer object such that the memory reads
16342 required would exceed the data store size.
16344 @code{GL_INVALID_OPERATION} is generated by @code{glPixelMapfv} if a
16345 non-zero buffer object name is bound to the
16346 @code{GL_PIXEL_UNPACK_BUFFER} target and @var{values} is not evenly
16347 divisible into the number of bytes needed to store in memory a GLfloat
16350 @code{GL_INVALID_OPERATION} is generated by @code{glPixelMapuiv} if a
16351 non-zero buffer object name is bound to the
16352 @code{GL_PIXEL_UNPACK_BUFFER} target and @var{values} is not evenly
16353 divisible into the number of bytes needed to store in memory a GLuint
16356 @code{GL_INVALID_OPERATION} is generated by @code{glPixelMapusv} if a
16357 non-zero buffer object name is bound to the
16358 @code{GL_PIXEL_UNPACK_BUFFER} target and @var{values} is not evenly
16359 divisible into the number of bytes needed to store in memory a GLushort
16362 @code{GL_INVALID_OPERATION} is generated if @code{glPixelMap} is
16363 executed between the execution of @code{glBegin} and the corresponding
16364 execution of @code{glEnd}.
16368 @deftypefun void glPixelStoref pname param
16369 @deftypefunx void glPixelStorei pname param
16370 Set pixel storage modes.
16374 Specifies the symbolic name of the parameter to be set. Six values
16375 affect the packing of pixel data into memory: @code{GL_PACK_SWAP_BYTES},
16376 @code{GL_PACK_LSB_FIRST}, @code{GL_PACK_ROW_LENGTH},
16377 @code{GL_PACK_IMAGE_HEIGHT}, @code{GL_PACK_SKIP_PIXELS},
16378 @code{GL_PACK_SKIP_ROWS}, @code{GL_PACK_SKIP_IMAGES}, and
16379 @code{GL_PACK_ALIGNMENT}. Six more affect the unpacking of pixel data
16380 @var{from} memory: @code{GL_UNPACK_SWAP_BYTES},
16381 @code{GL_UNPACK_LSB_FIRST}, @code{GL_UNPACK_ROW_LENGTH},
16382 @code{GL_UNPACK_IMAGE_HEIGHT}, @code{GL_UNPACK_SKIP_PIXELS},
16383 @code{GL_UNPACK_SKIP_ROWS}, @code{GL_UNPACK_SKIP_IMAGES}, and
16384 @code{GL_UNPACK_ALIGNMENT}.
16387 Specifies the value that @var{pname} is set to.
16391 @code{glPixelStore} sets pixel storage modes that affect the operation
16392 of subsequent @code{glDrawPixels} and @code{glReadPixels} as well as the
16393 unpacking of polygon stipple patterns (see @code{glPolygonStipple}),
16394 bitmaps (see @code{glBitmap}), texture patterns (see
16395 @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D},
16396 @code{glTexSubImage1D}, @code{glTexSubImage2D}, @code{glTexSubImage3D}).
16397 Additionally, if the @code{ARB_imaging} extension is supported, pixel
16398 storage modes affect convolution filters (see
16399 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and
16400 @code{glSeparableFilter2D}, color table (see @code{glColorTable}, and
16401 @code{glColorSubTable}, and unpacking histogram (See
16402 @code{glHistogram}), and minmax (See @code{glMinmax}) data.
16404 @var{pname} is a symbolic constant indicating the parameter to be set,
16405 and @var{param} is the new value. Six of the twelve storage parameters
16406 affect how pixel data is returned to client memory. They are as
16410 @item @code{GL_PACK_SWAP_BYTES}
16411 If true, byte ordering for multibyte color components, depth components,
16412 color indices, or stencil indices is reversed. That is, if a four-byte
16413 component consists of bytes @r{@var{b}_0}, @r{@var{b}_1}, @r{@var{b}_2},
16414 @r{@var{b}_3}, it is stored in memory as @r{@var{b}_3}, @r{@var{b}_2},
16415 @r{@var{b}_1}, @r{@var{b}_0} if @code{GL_PACK_SWAP_BYTES} is true.
16416 @code{GL_PACK_SWAP_BYTES} has no effect on the memory order of
16417 components within a pixel, only on the order of bytes within components
16418 or indices. For example, the three components of a @code{GL_RGB} format
16419 pixel are always stored with red first, green second, and blue third,
16420 regardless of the value of @code{GL_PACK_SWAP_BYTES}.
16422 @item @code{GL_PACK_LSB_FIRST}
16423 If true, bits are ordered within a byte from least significant to most
16424 significant; otherwise, the first bit in each byte is the most
16425 significant one. This parameter is significant for bitmap data only.
16427 @item @code{GL_PACK_ROW_LENGTH}
16428 If greater than 0, @code{GL_PACK_ROW_LENGTH} defines the number of
16429 pixels in a row. If the first pixel of a row is placed at location
16430 @r{@var{p}} in memory, then the location of the first pixel of the next
16431 row is obtained by skipping
16433 @r{@var{k}=@{(@var{n}@var{l}),
16434 (@var{a}/@var{s},⌈@var{s}@var{n}@var{l},/@var{a},⌉)(@var{s}>=@var{a}),
16435 (@var{s}<@var{a}),}
16437 components or indices, where @r{@var{n}} is the number of components or
16438 indices in a pixel, @r{@var{l}} is the number of pixels in a row
16439 (@code{GL_PACK_ROW_LENGTH} if it is greater than 0, the @r{@var{width}}
16440 argument to the pixel routine otherwise), @r{@var{a}} is the value of
16441 @code{GL_PACK_ALIGNMENT}, and @r{@var{s}} is the size, in bytes, of a
16442 single component (if @r{@var{a}<@var{s}}, then it is as if
16443 @r{@var{a}=@var{s}}). In the case of 1-bit values, the location of the
16444 next row is obtained by skipping
16446 @r{@var{k}=8@var{a}⌈@var{n}@var{l},/8@var{a},,⌉}
16448 components or indices.
16450 The word @var{component} in this description refers to the nonindex
16451 values red, green, blue, alpha, and depth. Storage format
16452 @code{GL_RGB}, for example, has three components per pixel: first red,
16453 then green, and finally blue.
16455 @item @code{GL_PACK_IMAGE_HEIGHT}
16456 If greater than 0, @code{GL_PACK_IMAGE_HEIGHT} defines the number of
16457 pixels in an image three-dimensional texture volume, where ``image'' is
16458 defined by all pixels sharing the same third dimension index. If the
16459 first pixel of a row is placed at location @r{@var{p}} in memory, then
16460 the location of the first pixel of the next row is obtained by skipping
16462 @r{@var{k}=@{(@var{n}@var{l}@var{h}),
16463 (@var{a}/@var{s},⌈@var{s}@var{n}@var{l}@var{h},/@var{a},⌉)(@var{s}>=@var{a}),
16464 (@var{s}<@var{a}),}
16466 components or indices, where @r{@var{n}} is the number of components or
16467 indices in a pixel, @r{@var{l}} is the number of pixels in a row
16468 (@code{GL_PACK_ROW_LENGTH} if it is greater than 0, the @r{@var{width}}
16469 argument to @code{glTexImage3D} otherwise), @r{@var{h}} is the number of
16470 rows in a pixel image (@code{GL_PACK_IMAGE_HEIGHT} if it is greater than
16471 0, the @r{@var{height}} argument to the @code{glTexImage3D} routine
16472 otherwise), @r{@var{a}} is the value of @code{GL_PACK_ALIGNMENT}, and
16473 @r{@var{s}} is the size, in bytes, of a single component (if
16474 @r{@var{a}<@var{s}}, then it is as if @r{@var{a}=@var{s}}).
16476 The word @var{component} in this description refers to the nonindex
16477 values red, green, blue, alpha, and depth. Storage format
16478 @code{GL_RGB}, for example, has three components per pixel: first red,
16479 then green, and finally blue.
16481 @item @code{GL_PACK_SKIP_PIXELS}, @code{GL_PACK_SKIP_ROWS}, and @code{GL_PACK_SKIP_IMAGES}
16482 These values are provided as a convenience to the programmer; they
16483 provide no functionality that cannot be duplicated simply by
16484 incrementing the pointer passed to @code{glReadPixels}. Setting
16485 @code{GL_PACK_SKIP_PIXELS} to @r{@var{i}} is equivalent to incrementing
16486 the pointer by @r{@var{i}@var{n}} components or indices, where
16487 @r{@var{n}} is the number of components or indices in each pixel.
16488 Setting @code{GL_PACK_SKIP_ROWS} to @r{@var{j}} is equivalent to
16489 incrementing the pointer by @r{@var{j}@var{m}} components or indices,
16490 where @r{@var{m}} is the number of components or indices per row, as
16491 just computed in the @code{GL_PACK_ROW_LENGTH} section. Setting
16492 @code{GL_PACK_SKIP_IMAGES} to @r{@var{k}} is equivalent to incrementing
16493 the pointer by @r{@var{k}@var{p}}, where @r{@var{p}} is the number of
16494 components or indices per image, as computed in the
16495 @code{GL_PACK_IMAGE_HEIGHT} section.
16497 @item @code{GL_PACK_ALIGNMENT}
16498 Specifies the alignment requirements for the start of each pixel row in
16499 memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to
16500 even-numbered bytes), 4 (word-alignment), and 8 (rows start on
16501 double-word boundaries).
16505 The other six of the twelve storage parameters affect how pixel data is
16506 read from client memory. These values are significant for
16507 @code{glDrawPixels}, @code{glTexImage1D}, @code{glTexImage2D},
16508 @code{glTexImage3D}, @code{glTexSubImage1D}, @code{glTexSubImage2D},
16509 @code{glTexSubImage3D}, @code{glBitmap}, and @code{glPolygonStipple}.
16511 Additionally, if the @code{ARB_imaging} extension is supported,
16512 @code{glColorTable}, @code{glColorSubTable},
16513 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and
16514 @code{glSeparableFilter2D}. They are as follows:
16517 @item @code{GL_UNPACK_SWAP_BYTES}
16518 If true, byte ordering for multibyte color components, depth components,
16519 color indices, or stencil indices is reversed. That is, if a four-byte
16520 component consists of bytes @r{@var{b}_0}, @r{@var{b}_1}, @r{@var{b}_2},
16521 @r{@var{b}_3}, it is taken from memory as @r{@var{b}_3}, @r{@var{b}_2},
16522 @r{@var{b}_1}, @r{@var{b}_0} if @code{GL_UNPACK_SWAP_BYTES} is true.
16523 @code{GL_UNPACK_SWAP_BYTES} has no effect on the memory order of
16524 components within a pixel, only on the order of bytes within components
16525 or indices. For example, the three components of a @code{GL_RGB} format
16526 pixel are always stored with red first, green second, and blue third,
16527 regardless of the value of @code{GL_UNPACK_SWAP_BYTES}.
16529 @item @code{GL_UNPACK_LSB_FIRST}
16530 If true, bits are ordered within a byte from least significant to most
16531 significant; otherwise, the first bit in each byte is the most
16532 significant one. This is relevant only for bitmap data.
16534 @item @code{GL_UNPACK_ROW_LENGTH}
16535 If greater than 0, @code{GL_UNPACK_ROW_LENGTH} defines the number of
16536 pixels in a row. If the first pixel of a row is placed at location
16537 @r{@var{p}} in memory, then the location of the first pixel of the next
16538 row is obtained by skipping
16540 @r{@var{k}=@{(@var{n}@var{l}),
16541 (@var{a}/@var{s},⌈@var{s}@var{n}@var{l},/@var{a},⌉)(@var{s}>=@var{a}),
16542 (@var{s}<@var{a}),}
16544 components or indices, where @r{@var{n}} is the number of components or
16545 indices in a pixel, @r{@var{l}} is the number of pixels in a row
16546 (@code{GL_UNPACK_ROW_LENGTH} if it is greater than 0, the
16547 @r{@var{width}} argument to the pixel routine otherwise), @r{@var{a}} is
16548 the value of @code{GL_UNPACK_ALIGNMENT}, and @r{@var{s}} is the size, in
16549 bytes, of a single component (if @r{@var{a}<@var{s}}, then it is as if
16550 @r{@var{a}=@var{s}}). In the case of 1-bit values, the location of the
16551 next row is obtained by skipping
16553 @r{@var{k}=8@var{a}⌈@var{n}@var{l},/8@var{a},,⌉}
16555 components or indices.
16557 The word @var{component} in this description refers to the nonindex
16558 values red, green, blue, alpha, and depth. Storage format
16559 @code{GL_RGB}, for example, has three components per pixel: first red,
16560 then green, and finally blue.
16562 @item @code{GL_UNPACK_IMAGE_HEIGHT}
16563 If greater than 0, @code{GL_UNPACK_IMAGE_HEIGHT} defines the number of
16564 pixels in an image of a three-dimensional texture volume. Where
16565 ``image'' is defined by all pixel sharing the same third dimension
16566 index. If the first pixel of a row is placed at location @r{@var{p}} in
16567 memory, then the location of the first pixel of the next row is obtained
16570 @r{@var{k}=@{(@var{n}@var{l}@var{h}),
16571 (@var{a}/@var{s},⌈@var{s}@var{n}@var{l}@var{h},/@var{a},⌉)(@var{s}>=@var{a}),
16572 (@var{s}<@var{a}),}
16574 components or indices, where @r{@var{n}} is the number of components or
16575 indices in a pixel, @r{@var{l}} is the number of pixels in a row
16576 (@code{GL_UNPACK_ROW_LENGTH} if it is greater than 0, the
16577 @r{@var{width}} argument to @code{glTexImage3D} otherwise), @r{@var{h}}
16578 is the number of rows in an image (@code{GL_UNPACK_IMAGE_HEIGHT} if it
16579 is greater than 0, the @r{@var{height}} argument to @code{glTexImage3D}
16580 otherwise), @r{@var{a}} is the value of @code{GL_UNPACK_ALIGNMENT}, and
16581 @r{@var{s}} is the size, in bytes, of a single component (if
16582 @r{@var{a}<@var{s}}, then it is as if @r{@var{a}=@var{s}}).
16584 The word @var{component} in this description refers to the nonindex
16585 values red, green, blue, alpha, and depth. Storage format
16586 @code{GL_RGB}, for example, has three components per pixel: first red,
16587 then green, and finally blue.
16589 @item @code{GL_UNPACK_SKIP_PIXELS} and @code{GL_UNPACK_SKIP_ROWS}
16590 These values are provided as a convenience to the programmer; they
16591 provide no functionality that cannot be duplicated by incrementing the
16592 pointer passed to @code{glDrawPixels}, @code{glTexImage1D},
16593 @code{glTexImage2D}, @code{glTexSubImage1D}, @code{glTexSubImage2D},
16594 @code{glBitmap}, or @code{glPolygonStipple}. Setting
16595 @code{GL_UNPACK_SKIP_PIXELS} to @r{@var{i}} is equivalent to
16596 incrementing the pointer by @r{@var{i}@var{n}} components or indices,
16597 where @r{@var{n}} is the number of components or indices in each pixel.
16598 Setting @code{GL_UNPACK_SKIP_ROWS} to @r{@var{j}} is equivalent to
16599 incrementing the pointer by @r{@var{j}@var{k}} components or indices,
16600 where @r{@var{k}} is the number of components or indices per row, as
16601 just computed in the @code{GL_UNPACK_ROW_LENGTH} section.
16603 @item @code{GL_UNPACK_ALIGNMENT}
16604 Specifies the alignment requirements for the start of each pixel row in
16605 memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to
16606 even-numbered bytes), 4 (word-alignment), and 8 (rows start on
16607 double-word boundaries).
16611 The following table gives the type, initial value, and range of valid
16612 values for each storage parameter that can be set with
16613 @code{glPixelStore}.
16618 @item @strong{@var{pname}}
16619 @strong{Type}, @strong{Initial Value}, @strong{Valid Range}
16621 @item @code{GL_PACK_SWAP_BYTES}
16622 boolean , false , true or false
16624 @item @code{GL_PACK_LSB_FIRST}
16625 boolean , false , true or false
16627 @item @code{GL_PACK_ROW_LENGTH}
16628 integer , 0 , @r{[0,∞)}
16630 @item @code{GL_PACK_IMAGE_HEIGHT}
16631 integer , 0 , @r{[0,∞)}
16633 @item @code{GL_PACK_SKIP_ROWS}
16634 integer , 0 , @r{[0,∞)}
16636 @item @code{GL_PACK_SKIP_PIXELS}
16637 integer , 0 , @r{[0,∞)}
16639 @item @code{GL_PACK_SKIP_IMAGES}
16640 integer , 0 , @r{[0,∞)}
16642 @item @code{GL_PACK_ALIGNMENT}
16643 integer , 4 , 1, 2, 4, or 8
16645 @item @code{GL_UNPACK_SWAP_BYTES}
16646 boolean , false , true or false
16648 @item @code{GL_UNPACK_LSB_FIRST}
16649 boolean , false , true or false
16651 @item @code{GL_UNPACK_ROW_LENGTH}
16652 integer , 0 , @r{[0,∞)}
16654 @item @code{GL_UNPACK_IMAGE_HEIGHT}
16655 integer , 0 , @r{[0,∞)}
16657 @item @code{GL_UNPACK_SKIP_ROWS}
16658 integer , 0 , @r{[0,∞)}
16660 @item @code{GL_UNPACK_SKIP_PIXELS}
16661 integer , 0 , @r{[0,∞)}
16663 @item @code{GL_UNPACK_SKIP_IMAGES}
16664 integer , 0 , @r{[0,∞)}
16666 @item @code{GL_UNPACK_ALIGNMENT}
16667 integer , 4 , 1, 2, 4, or 8
16671 @code{glPixelStoref} can be used to set any pixel store parameter. If
16672 the parameter type is boolean, then if @var{param} is 0, the parameter
16673 is false; otherwise it is set to true. If @var{pname} is a integer type
16674 parameter, @var{param} is rounded to the nearest integer.
16676 Likewise, @code{glPixelStorei} can also be used to set any of the pixel
16677 store parameters. Boolean parameters are set to false if @var{param} is
16678 0 and true otherwise.
16680 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
16683 @code{GL_INVALID_VALUE} is generated if a negative row length, pixel
16684 skip, or row skip value is specified, or if alignment is specified as
16685 other than 1, 2, 4, or 8.
16687 @code{GL_INVALID_OPERATION} is generated if @code{glPixelStore} is
16688 executed between the execution of @code{glBegin} and the corresponding
16689 execution of @code{glEnd}.
16693 @deftypefun void glPixelTransferf pname param
16694 @deftypefunx void glPixelTransferi pname param
16695 Set pixel transfer modes.
16699 Specifies the symbolic name of the pixel transfer parameter to be set.
16700 Must be one of the following: @code{GL_MAP_COLOR},
16701 @code{GL_MAP_STENCIL}, @code{GL_INDEX_SHIFT}, @code{GL_INDEX_OFFSET},
16702 @code{GL_RED_SCALE}, @code{GL_RED_BIAS}, @code{GL_GREEN_SCALE},
16703 @code{GL_GREEN_BIAS}, @code{GL_BLUE_SCALE}, @code{GL_BLUE_BIAS},
16704 @code{GL_ALPHA_SCALE}, @code{GL_ALPHA_BIAS}, @code{GL_DEPTH_SCALE}, or
16705 @code{GL_DEPTH_BIAS}.
16707 Additionally, if the @code{ARB_imaging} extension is supported, the
16708 following symbolic names are accepted:
16709 @code{GL_POST_COLOR_MATRIX_RED_SCALE},
16710 @code{GL_POST_COLOR_MATRIX_GREEN_SCALE},
16711 @code{GL_POST_COLOR_MATRIX_BLUE_SCALE},
16712 @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE},
16713 @code{GL_POST_COLOR_MATRIX_RED_BIAS},
16714 @code{GL_POST_COLOR_MATRIX_GREEN_BIAS},
16715 @code{GL_POST_COLOR_MATRIX_BLUE_BIAS},
16716 @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS},
16717 @code{GL_POST_CONVOLUTION_RED_SCALE},
16718 @code{GL_POST_CONVOLUTION_GREEN_SCALE},
16719 @code{GL_POST_CONVOLUTION_BLUE_SCALE},
16720 @code{GL_POST_CONVOLUTION_ALPHA_SCALE},
16721 @code{GL_POST_CONVOLUTION_RED_BIAS},
16722 @code{GL_POST_CONVOLUTION_GREEN_BIAS},
16723 @code{GL_POST_CONVOLUTION_BLUE_BIAS}, and
16724 @code{GL_POST_CONVOLUTION_ALPHA_BIAS}.
16727 Specifies the value that @var{pname} is set to.
16731 @code{glPixelTransfer} sets pixel transfer modes that affect the
16732 operation of subsequent @code{glCopyPixels}, @code{glCopyTexImage1D},
16733 @code{glCopyTexImage2D}, @code{glCopyTexSubImage1D},
16734 @code{glCopyTexSubImage2D}, @code{glCopyTexSubImage3D},
16735 @code{glDrawPixels}, @code{glReadPixels}, @code{glTexImage1D},
16736 @code{glTexImage2D}, @code{glTexImage3D}, @code{glTexSubImage1D},
16737 @code{glTexSubImage2D}, and @code{glTexSubImage3D} commands.
16738 Additionally, if the @code{ARB_imaging} subset is supported, the
16739 routines @code{glColorTable}, @code{glColorSubTable},
16740 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D},
16741 @code{glHistogram}, @code{glMinmax}, and @code{glSeparableFilter2D} are
16742 also affected. The algorithms that are specified by pixel transfer
16743 modes operate on pixels after they are read from the frame buffer
16744 (@code{glCopyPixels}@code{glCopyTexImage1D}, @code{glCopyTexImage2D},
16745 @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D},
16746 @code{glCopyTexSubImage3D}, and @code{glReadPixels}), or unpacked from
16747 client memory (@code{glDrawPixels}, @code{glTexImage1D},
16748 @code{glTexImage2D}, @code{glTexImage3D}, @code{glTexSubImage1D},
16749 @code{glTexSubImage2D}, and @code{glTexSubImage3D}). Pixel transfer
16750 operations happen in the same order, and in the same manner, regardless
16751 of the command that resulted in the pixel operation. Pixel storage
16752 modes (see @code{glPixelStore}) control the unpacking of pixels being
16753 read from client memory and the packing of pixels being written back
16754 into client memory.
16756 Pixel transfer operations handle four fundamental pixel types:
16757 @var{color}, @var{color index}, @var{depth}, and @var{stencil}.
16758 @var{Color} pixels consist of four floating-point values with
16759 unspecified mantissa and exponent sizes, scaled such that 0 represents
16760 zero intensity and 1 represents full intensity. @var{Color indices}
16761 comprise a single fixed-point value, with unspecified precision to the
16762 right of the binary point. @var{Depth} pixels comprise a single
16763 floating-point value, with unspecified mantissa and exponent sizes,
16764 scaled such that 0.0 represents the minimum depth buffer value, and 1.0
16765 represents the maximum depth buffer value. Finally, @var{stencil}
16766 pixels comprise a single fixed-point value, with unspecified precision
16767 to the right of the binary point.
16769 The pixel transfer operations performed on the four basic pixel types
16774 Each of the four color components is multiplied by a scale factor, then
16775 added to a bias factor. That is, the red component is multiplied by
16776 @code{GL_RED_SCALE}, then added to @code{GL_RED_BIAS}; the green
16777 component is multiplied by @code{GL_GREEN_SCALE}, then added to
16778 @code{GL_GREEN_BIAS}; the blue component is multiplied by
16779 @code{GL_BLUE_SCALE}, then added to @code{GL_BLUE_BIAS}; and the alpha
16780 component is multiplied by @code{GL_ALPHA_SCALE}, then added to
16781 @code{GL_ALPHA_BIAS}. After all four color components are scaled and
16782 biased, each is clamped to the range @r{[0,1]}. All color, scale, and
16783 bias values are specified with @code{glPixelTransfer}.
16785 If @code{GL_MAP_COLOR} is true, each color component is scaled by the
16786 size of the corresponding color-to-color map, then replaced by the
16787 contents of that map indexed by the scaled component. That is, the red
16788 component is scaled by @code{GL_PIXEL_MAP_R_TO_R_SIZE}, then replaced by
16789 the contents of @code{GL_PIXEL_MAP_R_TO_R} indexed by itself. The green
16790 component is scaled by @code{GL_PIXEL_MAP_G_TO_G_SIZE}, then replaced by
16791 the contents of @code{GL_PIXEL_MAP_G_TO_G} indexed by itself. The blue
16792 component is scaled by @code{GL_PIXEL_MAP_B_TO_B_SIZE}, then replaced by
16793 the contents of @code{GL_PIXEL_MAP_B_TO_B} indexed by itself. And the
16794 alpha component is scaled by @code{GL_PIXEL_MAP_A_TO_A_SIZE}, then
16795 replaced by the contents of @code{GL_PIXEL_MAP_A_TO_A} indexed by
16796 itself. All components taken from the maps are then clamped to the
16797 range @r{[0,1]}. @code{GL_MAP_COLOR} is specified with
16798 @code{glPixelTransfer}. The contents of the various maps are specified
16799 with @code{glPixelMap}.
16801 If the @code{ARB_imaging} extension is supported, each of the four color
16802 components may be scaled and biased after transformation by the color
16803 matrix. That is, the red component is multiplied by
16804 @code{GL_POST_COLOR_MATRIX_RED_SCALE}, then added to
16805 @code{GL_POST_COLOR_MATRIX_RED_BIAS}; the green component is multiplied
16806 by @code{GL_POST_COLOR_MATRIX_GREEN_SCALE}, then added to
16807 @code{GL_POST_COLOR_MATRIX_GREEN_BIAS}; the blue component is multiplied
16808 by @code{GL_POST_COLOR_MATRIX_BLUE_SCALE}, then added to
16809 @code{GL_POST_COLOR_MATRIX_BLUE_BIAS}; and the alpha component is
16810 multiplied by @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE}, then added to
16811 @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS}. After all four color components
16812 are scaled and biased, each is clamped to the range @r{[0,1]}.
16814 Similarly, if the @code{ARB_imaging} extension is supported, each of the
16815 four color components may be scaled and biased after processing by the
16816 enabled convolution filter. That is, the red component is multiplied by
16817 @code{GL_POST_CONVOLUTION_RED_SCALE}, then added to
16818 @code{GL_POST_CONVOLUTION_RED_BIAS}; the green component is multiplied
16819 by @code{GL_POST_CONVOLUTION_GREEN_SCALE}, then added to
16820 @code{GL_POST_CONVOLUTION_GREEN_BIAS}; the blue component is multiplied
16821 by @code{GL_POST_CONVOLUTION_BLUE_SCALE}, then added to
16822 @code{GL_POST_CONVOLUTION_BLUE_BIAS}; and the alpha component is
16823 multiplied by @code{GL_POST_CONVOLUTION_ALPHA_SCALE}, then added to
16824 @code{GL_POST_CONVOLUTION_ALPHA_BIAS}. After all four color components
16825 are scaled and biased, each is clamped to the range @r{[0,1]}.
16827 @item @var{Color index}
16828 Each color index is shifted left by @code{GL_INDEX_SHIFT} bits; any bits
16829 beyond the number of fraction bits carried by the fixed-point index are
16830 filled with zeros. If @code{GL_INDEX_SHIFT} is negative, the shift is
16831 to the right, again zero filled. Then @code{GL_INDEX_OFFSET} is added
16832 to the index. @code{GL_INDEX_SHIFT} and @code{GL_INDEX_OFFSET} are
16833 specified with @code{glPixelTransfer}.
16835 From this point, operation diverges depending on the required format of
16836 the resulting pixels. If the resulting pixels are to be written to a
16837 color index buffer, or if they are being read back to client memory in
16838 @code{GL_COLOR_INDEX} format, the pixels continue to be treated as
16839 indices. If @code{GL_MAP_COLOR} is true, each index is masked by
16840 @r{2^@var{n}-1}, where @r{@var{n}} is @code{GL_PIXEL_MAP_I_TO_I_SIZE},
16841 then replaced by the contents of @code{GL_PIXEL_MAP_I_TO_I} indexed by
16842 the masked value. @code{GL_MAP_COLOR} is specified with
16843 @code{glPixelTransfer}. The contents of the index map is specified with
16846 If the resulting pixels are to be written to an RGBA color buffer, or if
16847 they are read back to client memory in a format other than
16848 @code{GL_COLOR_INDEX}, the pixels are converted from indices to colors
16849 by referencing the four maps @code{GL_PIXEL_MAP_I_TO_R},
16850 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
16851 @code{GL_PIXEL_MAP_I_TO_A}. Before being dereferenced, the index is
16852 masked by @r{2^@var{n}-1}, where @r{@var{n}} is
16853 @code{GL_PIXEL_MAP_I_TO_R_SIZE} for the red map,
16854 @code{GL_PIXEL_MAP_I_TO_G_SIZE} for the green map,
16855 @code{GL_PIXEL_MAP_I_TO_B_SIZE} for the blue map, and
16856 @code{GL_PIXEL_MAP_I_TO_A_SIZE} for the alpha map. All components taken
16857 from the maps are then clamped to the range @r{[0,1]}. The contents of
16858 the four maps is specified with @code{glPixelMap}.
16861 Each depth value is multiplied by @code{GL_DEPTH_SCALE}, added to
16862 @code{GL_DEPTH_BIAS}, then clamped to the range @r{[0,1]}.
16864 @item @var{Stencil}
16865 Each index is shifted @code{GL_INDEX_SHIFT} bits just as a color index
16866 is, then added to @code{GL_INDEX_OFFSET}. If @code{GL_MAP_STENCIL} is
16867 true, each index is masked by @r{2^@var{n}-1}, where @r{@var{n}} is
16868 @code{GL_PIXEL_MAP_S_TO_S_SIZE}, then replaced by the contents of
16869 @code{GL_PIXEL_MAP_S_TO_S} indexed by the masked value.
16873 The following table gives the type, initial value, and range of valid
16874 values for each of the pixel transfer parameters that are set with
16875 @code{glPixelTransfer}.
16880 @item @strong{@var{pname}}
16881 @strong{Type}, @strong{Initial Value}, @strong{Valid Range}
16883 @item @code{GL_MAP_COLOR}
16884 boolean , false , true/false
16886 @item @code{GL_MAP_STENCIL}
16887 boolean , false , true/false
16889 @item @code{GL_INDEX_SHIFT}
16890 integer , 0 , @r{(-∞,∞)}
16892 @item @code{GL_INDEX_OFFSET}
16893 integer , 0 , @r{(-∞,∞)}
16895 @item @code{GL_RED_SCALE}
16896 float , 1 , @r{(-∞,∞)}
16898 @item @code{GL_GREEN_SCALE}
16899 float , 1 , @r{(-∞,∞)}
16901 @item @code{GL_BLUE_SCALE}
16902 float , 1 , @r{(-∞,∞)}
16904 @item @code{GL_ALPHA_SCALE}
16905 float , 1 , @r{(-∞,∞)}
16907 @item @code{GL_DEPTH_SCALE}
16908 float , 1 , @r{(-∞,∞)}
16910 @item @code{GL_RED_BIAS}
16911 float , 0 , @r{(-∞,∞)}
16913 @item @code{GL_GREEN_BIAS}
16914 float , 0 , @r{(-∞,∞)}
16916 @item @code{GL_BLUE_BIAS}
16917 float , 0 , @r{(-∞,∞)}
16919 @item @code{GL_ALPHA_BIAS}
16920 float , 0 , @r{(-∞,∞)}
16922 @item @code{GL_DEPTH_BIAS}
16923 float , 0 , @r{(-∞,∞)}
16925 @item @code{GL_POST_COLOR_MATRIX_RED_SCALE}
16926 float , 1 , @r{(-∞,∞)}
16928 @item @code{GL_POST_COLOR_MATRIX_GREEN_SCALE}
16929 float , 1 , @r{(-∞,∞)}
16931 @item @code{GL_POST_COLOR_MATRIX_BLUE_SCALE}
16932 float , 1 , @r{(-∞,∞)}
16934 @item @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE}
16935 float , 1 , @r{(-∞,∞)}
16937 @item @code{GL_POST_COLOR_MATRIX_RED_BIAS}
16938 float , 0 , @r{(-∞,∞)}
16940 @item @code{GL_POST_COLOR_MATRIX_GREEN_BIAS}
16941 float , 0 , @r{(-∞,∞)}
16943 @item @code{GL_POST_COLOR_MATRIX_BLUE_BIAS}
16944 float , 0 , @r{(-∞,∞)}
16946 @item @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS}
16947 float , 0 , @r{(-∞,∞)}
16949 @item @code{GL_POST_CONVOLUTION_RED_SCALE}
16950 float , 1 , @r{(-∞,∞)}
16952 @item @code{GL_POST_CONVOLUTION_GREEN_SCALE}
16953 float , 1 , @r{(-∞,∞)}
16955 @item @code{GL_POST_CONVOLUTION_BLUE_SCALE}
16956 float , 1 , @r{(-∞,∞)}
16958 @item @code{GL_POST_CONVOLUTION_ALPHA_SCALE}
16959 float , 1 , @r{(-∞,∞)}
16961 @item @code{GL_POST_CONVOLUTION_RED_BIAS}
16962 float , 0 , @r{(-∞,∞)}
16964 @item @code{GL_POST_CONVOLUTION_GREEN_BIAS}
16965 float , 0 , @r{(-∞,∞)}
16967 @item @code{GL_POST_CONVOLUTION_BLUE_BIAS}
16968 float , 0 , @r{(-∞,∞)}
16970 @item @code{GL_POST_CONVOLUTION_ALPHA_BIAS}
16971 float , 0 , @r{(-∞,∞)}
16975 @code{glPixelTransferf} can be used to set any pixel transfer parameter.
16976 If the parameter type is boolean, 0 implies false and any other value
16977 implies true. If @var{pname} is an integer parameter, @var{param} is
16978 rounded to the nearest integer.
16980 Likewise, @code{glPixelTransferi} can be used to set any of the pixel
16981 transfer parameters. Boolean parameters are set to false if @var{param}
16982 is 0 and to true otherwise. @var{param} is converted to floating point
16983 before being assigned to real-valued parameters.
16985 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
16988 @code{GL_INVALID_OPERATION} is generated if @code{glPixelTransfer} is
16989 executed between the execution of @code{glBegin} and the corresponding
16990 execution of @code{glEnd}.
16994 @deftypefun void glPixelZoom xfactor yfactor
16995 Specify the pixel zoom factors.
16998 @item @var{xfactor}
16999 @itemx @var{yfactor}
17000 Specify the @r{@var{x}} and @r{@var{y}} zoom factors for pixel write
17005 @code{glPixelZoom} specifies values for the @r{@var{x}} and @r{@var{y}}
17006 zoom factors. During the execution of @code{glDrawPixels} or
17007 @code{glCopyPixels}, if (@r{@var{xr}}, @r{@var{yr}}) is the current
17008 raster position, and a given element is in the @r{@var{m}}th row and
17009 @r{@var{n}}th column of the pixel rectangle, then pixels whose centers
17010 are in the rectangle with corners at
17012 (@r{@var{xr}+@var{n}·@var{xfactor}}, @r{@var{yr}+@var{m}·@var{yfactor}})
17014 (@r{@var{xr}+(@var{n}+1,)·@var{xfactor}},
17015 @r{@var{yr}+(@var{m}+1,)·@var{yfactor}})
17017 are candidates for replacement. Any pixel whose center lies on the
17018 bottom or left edge of this rectangular region is also modified.
17020 Pixel zoom factors are not limited to positive values. Negative zoom
17021 factors reflect the resulting image about the current raster position.
17023 @code{GL_INVALID_OPERATION} is generated if @code{glPixelZoom} is
17024 executed between the execution of @code{glBegin} and the corresponding
17025 execution of @code{glEnd}.
17029 @deftypefun void glPointParameterf pname param
17030 @deftypefunx void glPointParameteri pname param
17031 @deftypefunx void glPointParameterfv pname params
17032 @deftypefunx void glPointParameteriv pname params
17033 Specify point parameters.
17037 Specifies a single-valued point parameter. @code{GL_POINT_SIZE_MIN},
17038 @code{GL_POINT_SIZE_MAX}, @code{GL_POINT_FADE_THRESHOLD_SIZE}, and
17039 @code{GL_POINT_SPRITE_COORD_ORIGIN} are accepted.
17042 Specifies the value that @var{pname} will be set to.
17046 The following values are accepted for @var{pname}:
17049 @item @code{GL_POINT_SIZE_MIN}
17052 @var{params} is a single floating-point value that specifies the minimum
17053 point size. The default value is 0.0.
17055 @item @code{GL_POINT_SIZE_MAX}
17058 @var{params} is a single floating-point value that specifies the maximum
17059 point size. The default value is 1.0.
17061 @item @code{GL_POINT_FADE_THRESHOLD_SIZE}
17064 @var{params} is a single floating-point value that specifies the
17065 threshold value to which point sizes are clamped if they exceed the
17066 specified value. The default value is 1.0.
17068 @item @code{GL_POINT_DISTANCE_ATTENUATION}
17071 @var{params} is an array of three floating-point values that specify the
17072 coefficients used for scaling the computed point size. The default
17073 values are @r{(1,00)}.
17075 @item @code{GL_POINT_SPRITE_COORD_ORIGIN}
17078 @var{params} is a single enum specifying the point sprite texture
17079 coordinate origin, either @code{GL_LOWER_LEFT} or @code{GL_UPPER_LEFT}.
17080 The default value is @code{GL_UPPER_LEFT}.
17084 @code{GL_INVALID_VALUE} is generated If the value specified for
17085 @code{GL_POINT_SIZE_MIN}, @code{GL_POINT_SIZE_MAX}, or
17086 @code{GL_POINT_FADE_THRESHOLD_SIZE} is less than zero.
17088 @code{GL_INVALID_ENUM} is generated If the value specified for
17089 @code{GL_POINT_SPRITE_COORD_ORIGIN} is not @code{GL_LOWER_LEFT} or
17090 @code{GL_UPPER_LEFT}.
17092 If the value for @code{GL_POINT_SIZE_MIN} is greater than
17093 @code{GL_POINT_SIZE_MAX}, the point size after clamping is undefined,
17094 but no error is generated.
17100 @deftypefun void glPointSize size
17101 Specify the diameter of rasterized points.
17105 Specifies the diameter of rasterized points. The initial value is 1.
17109 @code{glPointSize} specifies the rasterized diameter of both aliased and
17110 antialiased points. Using a point size other than 1 has different
17111 effects, depending on whether point antialiasing is enabled. To enable
17112 and disable point antialiasing, call @code{glEnable} and
17113 @code{glDisable} with argument @code{GL_POINT_SMOOTH}. Point
17114 antialiasing is initially disabled.
17116 The specified point size is multiplied with a distance attenuation
17117 factor and clamped to the specified point size range, and further
17118 clamped to the implementation-dependent point size range to produce the
17119 derived point size using
17121 @r{@var{pointSize}=@var{clamp}(@var{size}×√(1/@var{a}+@var{b}×@var{d}+@var{c}×@var{d}^2,,,),,)}
17123 where @r{@var{d}} is the eye-coordinate distance from the eye to the
17124 vertex, and @r{@var{a}}, @r{@var{b}}, and @r{@var{c}} are the distance
17125 attenuation coefficients (see @code{glPointParameter}).
17127 If multisampling is disabled, the computed point size is used as the
17130 If multisampling is enabled, the point may be faded by modifying the
17131 point alpha value (see @code{glSampleCoverage}) instead of allowing the
17132 point width to go below a given threshold (see @code{glPointParameter}).
17133 In this case, the width is further modified in the following manner:
17135 @r{@var{pointWidth}=@{(@var{pointSize}),
17136 (@var{threshold})(@var{pointSize}>=@var{threshold}),
17137 (@var{otherwise}),}
17139 The point alpha value is modified by computing:
17141 @r{@var{pointAlpha}=@{(1),
17142 ((@var{pointSize}/@var{threshold},)^2)(@var{pointSize}>=@var{threshold}),
17143 (@var{otherwise}),}
17145 If point antialiasing is disabled, the actual size is determined by
17146 rounding the supplied size to the nearest integer. (If the rounding
17147 results in the value 0, it is as if the point size were 1.) If the
17148 rounded size is odd, then the center point (@r{@var{x}}, @r{@var{y}}) of
17149 the pixel fragment that represents the point is computed as
17151 @r{(⌊@var{x}_@var{w},⌋+.5,⌊@var{y}_@var{w},⌋+.5)}
17153 where @r{@var{w}} subscripts indicate window coordinates. All pixels
17154 that lie within the square grid of the rounded size centered at
17155 (@r{@var{x}}, @r{@var{y}}) make up the fragment. If the size is even,
17156 the center point is
17158 @r{(⌊@var{x}_@var{w}+.5,⌋,⌊@var{y}_@var{w}+.5,⌋)}
17160 and the rasterized fragment's centers are the half-integer window
17161 coordinates within the square of the rounded size centered at
17162 @r{(@var{x},@var{y})}. All pixel fragments produced in rasterizing a
17163 nonantialiased point are assigned the same associated data, that of the
17164 vertex corresponding to the point.
17166 If antialiasing is enabled, then point rasterization produces a fragment
17167 for each pixel square that intersects the region lying within the circle
17168 having diameter equal to the current point size and centered at the
17169 point's @r{(@var{x}_@var{w},@var{y}_@var{w})}. The coverage value for
17170 each fragment is the window coordinate area of the intersection of the
17171 circular region with the corresponding pixel square. This value is
17172 saved and used in the final rasterization step. The data associated
17173 with each fragment is the data associated with the point being
17176 Not all sizes are supported when point antialiasing is enabled. If an
17177 unsupported size is requested, the nearest supported size is used. Only
17178 size 1 is guaranteed to be supported; others depend on the
17179 implementation. To query the range of supported sizes and the size
17180 difference between supported sizes within the range, call @code{glGet}
17181 with arguments @code{GL_SMOOTH_POINT_SIZE_RANGE} and
17182 @code{GL_SMOOTH_POINT_SIZE_GRANULARITY}. For aliased points, query the
17183 supported ranges and granularity with @code{glGet} with arguments
17184 @code{GL_ALIASED_POINT_SIZE_RANGE}.
17186 @code{GL_INVALID_VALUE} is generated if @var{size} is less than or equal
17189 @code{GL_INVALID_OPERATION} is generated if @code{glPointSize} is
17190 executed between the execution of @code{glBegin} and the corresponding
17191 execution of @code{glEnd}.
17195 @deftypefun void glPolygonMode face mode
17196 Select a polygon rasterization mode.
17200 Specifies the polygons that @var{mode} applies to. Must be
17201 @code{GL_FRONT} for front-facing polygons, @code{GL_BACK} for
17202 back-facing polygons, or @code{GL_FRONT_AND_BACK} for front- and
17203 back-facing polygons.
17206 Specifies how polygons will be rasterized. Accepted values are
17207 @code{GL_POINT}, @code{GL_LINE}, and @code{GL_FILL}. The initial value
17208 is @code{GL_FILL} for both front- and back-facing polygons.
17212 @code{glPolygonMode} controls the interpretation of polygons for
17213 rasterization. @var{face} describes which polygons @var{mode} applies
17214 to: front-facing polygons (@code{GL_FRONT}), back-facing polygons
17215 (@code{GL_BACK}), or both (@code{GL_FRONT_AND_BACK}). The polygon mode
17216 affects only the final rasterization of polygons. In particular, a
17217 polygon's vertices are lit and the polygon is clipped and possibly
17218 culled before these modes are applied.
17220 Three modes are defined and can be specified in @var{mode}:
17223 @item @code{GL_POINT}
17224 Polygon vertices that are marked as the start of a boundary edge are
17225 drawn as points. Point attributes such as @code{GL_POINT_SIZE} and
17226 @code{GL_POINT_SMOOTH} control the rasterization of the points. Polygon
17227 rasterization attributes other than @code{GL_POLYGON_MODE} have no
17230 @item @code{GL_LINE}
17231 Boundary edges of the polygon are drawn as line segments. They are
17232 treated as connected line segments for line stippling; the line stipple
17233 counter and pattern are not reset between segments (see
17234 @code{glLineStipple}). Line attributes such as @code{GL_LINE_WIDTH} and
17235 @code{GL_LINE_SMOOTH} control the rasterization of the lines. Polygon
17236 rasterization attributes other than @code{GL_POLYGON_MODE} have no
17239 @item @code{GL_FILL}
17240 The interior of the polygon is filled. Polygon attributes such as
17241 @code{GL_POLYGON_STIPPLE} and @code{GL_POLYGON_SMOOTH} control the
17242 rasterization of the polygon.
17246 @code{GL_INVALID_ENUM} is generated if either @var{face} or @var{mode}
17247 is not an accepted value.
17249 @code{GL_INVALID_OPERATION} is generated if @code{glPolygonMode} is
17250 executed between the execution of @code{glBegin} and the corresponding
17251 execution of @code{glEnd}.
17255 @deftypefun void glPolygonOffset factor units
17256 Set the scale and units used to calculate depth values.
17260 Specifies a scale factor that is used to create a variable depth offset
17261 for each polygon. The initial value is 0.
17264 Is multiplied by an implementation-specific value to create a constant
17265 depth offset. The initial value is 0.
17269 When @code{GL_POLYGON_OFFSET_FILL}, @code{GL_POLYGON_OFFSET_LINE}, or
17270 @code{GL_POLYGON_OFFSET_POINT} is enabled, each fragment's @var{depth}
17271 value will be offset after it is interpolated from the @var{depth}
17272 values of the appropriate vertices. The value of the offset is
17273 @r{@var{factor}×@var{DZ}+@var{r}×@var{units}}, where @r{@var{DZ}} is a
17274 measurement of the change in depth relative to the screen area of the
17275 polygon, and @r{@var{r}} is the smallest value that is guaranteed to
17276 produce a resolvable offset for a given implementation. The offset is
17277 added before the depth test is performed and before the value is written
17278 into the depth buffer.
17280 @code{glPolygonOffset} is useful for rendering hidden-line images, for
17281 applying decals to surfaces, and for rendering solids with highlighted
17284 @code{GL_INVALID_OPERATION} is generated if @code{glPolygonOffset} is
17285 executed between the execution of @code{glBegin} and the corresponding
17286 execution of @code{glEnd}.
17290 @deftypefun void glPolygonStipple pattern
17291 Set the polygon stippling pattern.
17294 @item @var{pattern}
17295 Specifies a pointer to a @r{32×32} stipple pattern that will be unpacked
17296 from memory in the same way that @code{glDrawPixels} unpacks pixels.
17300 Polygon stippling, like line stippling (see @code{glLineStipple}), masks
17301 out certain fragments produced by rasterization, creating a pattern.
17302 Stippling is independent of polygon antialiasing.
17304 @var{pattern} is a pointer to a @r{32×32} stipple pattern that is stored
17305 in memory just like the pixel data supplied to a @code{glDrawPixels}
17306 call with height and @var{width} both equal to 32, a pixel format of
17307 @code{GL_COLOR_INDEX}, and data type of @code{GL_BITMAP}. That is, the
17308 stipple pattern is represented as a @r{32×32} array of 1-bit color
17309 indices packed in unsigned bytes. @code{glPixelStore} parameters like
17310 @code{GL_UNPACK_SWAP_BYTES} and @code{GL_UNPACK_LSB_FIRST} affect the
17311 assembling of the bits into a stipple pattern. Pixel transfer
17312 operations (shift, offset, pixel map) are not applied to the stipple
17315 If a non-zero named buffer object is bound to the
17316 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
17317 stipple pattern is specified, @var{pattern} is treated as a byte offset
17318 into the buffer object's data store.
17320 To enable and disable polygon stippling, call @code{glEnable} and
17321 @code{glDisable} with argument @code{GL_POLYGON_STIPPLE}. Polygon
17322 stippling is initially disabled. If it's enabled, a rasterized polygon
17323 fragment with window coordinates @r{@var{x}_@var{w}} and
17324 @r{@var{y}_@var{w}} is sent to the next stage of the GL if and only if
17325 the (@r{@var{x}_@var{w}%32})th bit in the (@r{@var{y}_@var{w}%32})th row
17326 of the stipple pattern is 1 (one). When polygon stippling is disabled,
17327 it is as if the stipple pattern consists of all 1's.
17329 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
17330 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
17331 object's data store is currently mapped.
17333 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
17334 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
17335 would be unpacked from the buffer object such that the memory reads
17336 required would exceed the data store size.
17338 @code{GL_INVALID_OPERATION} is generated if @code{glPolygonStipple} is
17339 executed between the execution of @code{glBegin} and the corresponding
17340 execution of @code{glEnd}.
17344 @deftypefun void glPrioritizeTextures n textures priorities
17345 Set texture residence priority.
17349 Specifies the number of textures to be prioritized.
17351 @item @var{textures}
17352 Specifies an array containing the names of the textures to be
17355 @item @var{priorities}
17356 Specifies an array containing the texture priorities. A priority given
17357 in an element of @var{priorities} applies to the texture named by the
17358 corresponding element of @var{textures}.
17362 @code{glPrioritizeTextures} assigns the @var{n} texture priorities given
17363 in @var{priorities} to the @var{n} textures named in @var{textures}.
17365 The GL establishes a ``working set'' of textures that are resident in
17366 texture memory. These textures may be bound to a texture target much
17367 more efficiently than textures that are not resident. By specifying a
17368 priority for each texture, @code{glPrioritizeTextures} allows
17369 applications to guide the GL implementation in determining which
17370 textures should be resident.
17372 The priorities given in @var{priorities} are clamped to the range
17373 @r{[0,1]} before they are assigned. 0 indicates the lowest priority;
17374 textures with priority 0 are least likely to be resident. 1 indicates
17375 the highest priority; textures with priority 1 are most likely to be
17376 resident. However, textures are not guaranteed to be resident until
17379 @code{glPrioritizeTextures} silently ignores attempts to prioritize
17380 texture 0 or any texture name that does not correspond to an existing
17383 @code{glPrioritizeTextures} does not require that any of the textures
17384 named by @var{textures} be bound to a texture target.
17385 @code{glTexParameter} may also be used to set a texture's priority, but
17386 only if the texture is currently bound. This is the only way to set the
17387 priority of a default texture.
17389 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
17391 @code{GL_INVALID_OPERATION} is generated if @code{glPrioritizeTextures}
17392 is executed between the execution of @code{glBegin} and the
17393 corresponding execution of @code{glEnd}.
17397 @deftypefun void glPushAttrib mask
17398 @deftypefunx void glPopAttrib
17399 Push and pop the server attribute stack.
17403 Specifies a mask that indicates which attributes to save. Values for
17404 @var{mask} are listed below.
17408 @code{glPushAttrib} takes one argument, a mask that indicates which
17409 groups of state variables to save on the attribute stack. Symbolic
17410 constants are used to set bits in the mask. @var{mask} is typically
17411 constructed by specifying the bitwise-or of several of these constants
17412 together. The special mask @code{GL_ALL_ATTRIB_BITS} can be used to
17413 save all stackable states.
17415 The symbolic mask constants and their associated GL state are as follows
17416 (the second column lists which attributes are saved):
17421 @item @code{GL_ACCUM_BUFFER_BIT}
17422 Accumulation buffer clear value
17424 @item @code{GL_COLOR_BUFFER_BIT}
17425 @code{GL_ALPHA_TEST} enable bit
17428 Alpha test function and reference value
17431 @code{GL_BLEND} enable bit
17434 Blending source and destination functions
17437 Constant blend color
17443 @code{GL_DITHER} enable bit
17446 @code{GL_DRAW_BUFFER} setting
17449 @code{GL_COLOR_LOGIC_OP} enable bit
17452 @code{GL_INDEX_LOGIC_OP} enable bit
17458 Color mode and index mode clear values
17461 Color mode and index mode writemasks
17463 @item @code{GL_CURRENT_BIT}
17467 Current color index
17470 Current normal vector
17473 Current texture coordinates
17476 Current raster position
17479 @code{GL_CURRENT_RASTER_POSITION_VALID} flag
17482 RGBA color associated with current raster position
17485 Color index associated with current raster position
17488 Texture coordinates associated with current raster position
17491 @code{GL_EDGE_FLAG} flag
17493 @item @code{GL_DEPTH_BUFFER_BIT}
17494 @code{GL_DEPTH_TEST} enable bit
17497 Depth buffer test function
17500 Depth buffer clear value
17503 @code{GL_DEPTH_WRITEMASK} enable bit
17505 @item @code{GL_ENABLE_BIT}
17506 @code{GL_ALPHA_TEST} flag
17509 @code{GL_AUTO_NORMAL} flag
17512 @code{GL_BLEND} flag
17515 Enable bits for the user-definable clipping planes
17518 @code{GL_COLOR_MATERIAL}
17521 @code{GL_CULL_FACE} flag
17524 @code{GL_DEPTH_TEST} flag
17527 @code{GL_DITHER} flag
17533 @code{GL_LIGHT}@var{i} where @code{0} <= @var{i} < @code{GL_MAX_LIGHTS}
17536 @code{GL_LIGHTING} flag
17539 @code{GL_LINE_SMOOTH} flag
17542 @code{GL_LINE_STIPPLE} flag
17545 @code{GL_COLOR_LOGIC_OP} flag
17548 @code{GL_INDEX_LOGIC_OP} flag
17551 @code{GL_MAP1_}@var{x} where @var{x} is a map type
17554 @code{GL_MAP2_}@var{x} where @var{x} is a map type
17557 @code{GL_MULTISAMPLE} flag
17560 @code{GL_NORMALIZE} flag
17563 @code{GL_POINT_SMOOTH} flag
17566 @code{GL_POLYGON_OFFSET_LINE} flag
17569 @code{GL_POLYGON_OFFSET_FILL} flag
17572 @code{GL_POLYGON_OFFSET_POINT} flag
17575 @code{GL_POLYGON_SMOOTH} flag
17578 @code{GL_POLYGON_STIPPLE} flag
17581 @code{GL_SAMPLE_ALPHA_TO_COVERAGE} flag
17584 @code{GL_SAMPLE_ALPHA_TO_ONE} flag
17587 @code{GL_SAMPLE_COVERAGE} flag
17590 @code{GL_SCISSOR_TEST} flag
17593 @code{GL_STENCIL_TEST} flag
17596 @code{GL_TEXTURE_1D} flag
17599 @code{GL_TEXTURE_2D} flag
17602 @code{GL_TEXTURE_3D} flag
17605 Flags @code{GL_TEXTURE_GEN_}@var{x} where @var{x} is S, T, R, or Q
17607 @item @code{GL_EVAL_BIT}
17608 @code{GL_MAP1_}@var{x} enable bits, where @var{x} is a map type
17611 @code{GL_MAP2_}@var{x} enable bits, where @var{x} is a map type
17614 1D grid endpoints and divisions
17617 2D grid endpoints and divisions
17620 @code{GL_AUTO_NORMAL} enable bit
17622 @item @code{GL_FOG_BIT}
17623 @code{GL_FOG} enable bit
17641 @code{GL_FOG_MODE} value
17643 @item @code{GL_HINT_BIT}
17644 @code{GL_PERSPECTIVE_CORRECTION_HINT} setting
17647 @code{GL_POINT_SMOOTH_HINT} setting
17650 @code{GL_LINE_SMOOTH_HINT} setting
17653 @code{GL_POLYGON_SMOOTH_HINT} setting
17656 @code{GL_FOG_HINT} setting
17659 @code{GL_GENERATE_MIPMAP_HINT} setting
17662 @code{GL_TEXTURE_COMPRESSION_HINT} setting
17664 @item @code{GL_LIGHTING_BIT}
17665 @code{GL_COLOR_MATERIAL} enable bit
17668 @code{GL_COLOR_MATERIAL_FACE} value
17671 Color material parameters that are tracking the current color
17674 Ambient scene color
17677 @code{GL_LIGHT_MODEL_LOCAL_VIEWER} value
17680 @code{GL_LIGHT_MODEL_TWO_SIDE} setting
17683 @code{GL_LIGHTING} enable bit
17686 Enable bit for each light
17689 Ambient, diffuse, and specular intensity for each light
17692 Direction, position, exponent, and cutoff angle for each light
17695 Constant, linear, and quadratic attenuation factors for each light
17698 Ambient, diffuse, specular, and emissive color for each material
17701 Ambient, diffuse, and specular color indices for each material
17704 Specular exponent for each material
17707 @code{GL_SHADE_MODEL} setting
17709 @item @code{GL_LINE_BIT}
17710 @code{GL_LINE_SMOOTH} flag
17713 @code{GL_LINE_STIPPLE} enable bit
17716 Line stipple pattern and repeat counter
17721 @item @code{GL_LIST_BIT}
17722 @code{GL_LIST_BASE} setting
17724 @item @code{GL_MULTISAMPLE_BIT}
17725 @code{GL_MULTISAMPLE} flag
17728 @code{GL_SAMPLE_ALPHA_TO_COVERAGE} flag
17731 @code{GL_SAMPLE_ALPHA_TO_ONE} flag
17734 @code{GL_SAMPLE_COVERAGE} flag
17737 @code{GL_SAMPLE_COVERAGE_VALUE} value
17740 @code{GL_SAMPLE_COVERAGE_INVERT} value
17742 @item @code{GL_PIXEL_MODE_BIT}
17743 @code{GL_RED_BIAS} and @code{GL_RED_SCALE} settings
17746 @code{GL_GREEN_BIAS} and @code{GL_GREEN_SCALE} values
17749 @code{GL_BLUE_BIAS} and @code{GL_BLUE_SCALE}
17752 @code{GL_ALPHA_BIAS} and @code{GL_ALPHA_SCALE}
17755 @code{GL_DEPTH_BIAS} and @code{GL_DEPTH_SCALE}
17758 @code{GL_INDEX_OFFSET} and @code{GL_INDEX_SHIFT} values
17761 @code{GL_MAP_COLOR} and @code{GL_MAP_STENCIL} flags
17764 @code{GL_ZOOM_X} and @code{GL_ZOOM_Y} factors
17767 @code{GL_READ_BUFFER} setting
17769 @item @code{GL_POINT_BIT}
17770 @code{GL_POINT_SMOOTH} flag
17775 @item @code{GL_POLYGON_BIT}
17776 @code{GL_CULL_FACE} enable bit
17779 @code{GL_CULL_FACE_MODE} value
17782 @code{GL_FRONT_FACE} indicator
17785 @code{GL_POLYGON_MODE} setting
17788 @code{GL_POLYGON_SMOOTH} flag
17791 @code{GL_POLYGON_STIPPLE} enable bit
17794 @code{GL_POLYGON_OFFSET_FILL} flag
17797 @code{GL_POLYGON_OFFSET_LINE} flag
17800 @code{GL_POLYGON_OFFSET_POINT} flag
17803 @code{GL_POLYGON_OFFSET_FACTOR}
17806 @code{GL_POLYGON_OFFSET_UNITS}
17808 @item @code{GL_POLYGON_STIPPLE_BIT}
17809 Polygon stipple image
17811 @item @code{GL_SCISSOR_BIT}
17812 @code{GL_SCISSOR_TEST} flag
17817 @item @code{GL_STENCIL_BUFFER_BIT}
17818 @code{GL_STENCIL_TEST} enable bit
17821 Stencil function and reference value
17827 Stencil fail, pass, and depth buffer pass actions
17830 Stencil buffer clear value
17833 Stencil buffer writemask
17835 @item @code{GL_TEXTURE_BIT}
17836 Enable bits for the four texture coordinates
17839 Border color for each texture image
17842 Minification function for each texture image
17845 Magnification function for each texture image
17848 Texture coordinates and wrap mode for each texture image
17851 Color and mode for each texture environment
17854 Enable bits @code{GL_TEXTURE_GEN_}@var{x}, @var{x} is S, T, R, and Q
17857 @code{GL_TEXTURE_GEN_MODE} setting for S, T, R, and Q
17860 @code{glTexGen} plane equations for S, T, R, and Q
17863 Current texture bindings (for example, @code{GL_TEXTURE_BINDING_2D})
17865 @item @code{GL_TRANSFORM_BIT}
17866 Coefficients of the six clipping planes
17869 Enable bits for the user-definable clipping planes
17872 @code{GL_MATRIX_MODE} value
17875 @code{GL_NORMALIZE} flag
17878 @code{GL_RESCALE_NORMAL} flag
17880 @item @code{GL_VIEWPORT_BIT}
17881 Depth range (near and far)
17884 Viewport origin and extent
17888 @code{glPopAttrib} restores the values of the state variables saved with
17889 the last @code{glPushAttrib} command. Those not saved are left
17892 It is an error to push attributes onto a full stack or to pop attributes
17893 off an empty stack. In either case, the error flag is set and no other
17894 change is made to GL state.
17896 Initially, the attribute stack is empty.
17898 @code{GL_STACK_OVERFLOW} is generated if @code{glPushAttrib} is called
17899 while the attribute stack is full.
17901 @code{GL_STACK_UNDERFLOW} is generated if @code{glPopAttrib} is called
17902 while the attribute stack is empty.
17904 @code{GL_INVALID_OPERATION} is generated if @code{glPushAttrib} or
17905 @code{glPopAttrib} is executed between the execution of @code{glBegin}
17906 and the corresponding execution of @code{glEnd}.
17910 @deftypefun void glPushClientAttrib mask
17911 @deftypefunx void glPopClientAttrib
17912 Push and pop the client attribute stack.
17916 Specifies a mask that indicates which attributes to save. Values for
17917 @var{mask} are listed below.
17921 @code{glPushClientAttrib} takes one argument, a mask that indicates
17922 which groups of client-state variables to save on the client attribute
17923 stack. Symbolic constants are used to set bits in the mask. @var{mask}
17924 is typically constructed by specifying the bitwise-or of several of
17925 these constants together. The special mask
17926 @code{GL_CLIENT_ALL_ATTRIB_BITS} can be used to save all stackable
17929 The symbolic mask constants and their associated GL client state are as
17930 follows (the second column lists which attributes are saved):
17932 @code{GL_CLIENT_PIXEL_STORE_BIT} Pixel storage modes
17933 @code{GL_CLIENT_VERTEX_ARRAY_BIT} Vertex arrays (and enables)
17935 @code{glPopClientAttrib} restores the values of the client-state
17936 variables saved with the last @code{glPushClientAttrib}. Those not
17937 saved are left unchanged.
17939 It is an error to push attributes onto a full client attribute stack or
17940 to pop attributes off an empty stack. In either case, the error flag is
17941 set, and no other change is made to GL state.
17943 Initially, the client attribute stack is empty.
17945 @code{GL_STACK_OVERFLOW} is generated if @code{glPushClientAttrib} is
17946 called while the attribute stack is full.
17948 @code{GL_STACK_UNDERFLOW} is generated if @code{glPopClientAttrib} is
17949 called while the attribute stack is empty.
17953 @deftypefun void glPushMatrix
17954 @deftypefunx void glPopMatrix
17955 Push and pop the current matrix stack.
17957 There is a stack of matrices for each of the matrix modes. In
17958 @code{GL_MODELVIEW} mode, the stack depth is at least 32. In the other
17959 modes, @code{GL_COLOR}, @code{GL_PROJECTION}, and @code{GL_TEXTURE}, the
17960 depth is at least 2. The current matrix in any mode is the matrix on
17961 the top of the stack for that mode.
17963 @code{glPushMatrix} pushes the current matrix stack down by one,
17964 duplicating the current matrix. That is, after a @code{glPushMatrix}
17965 call, the matrix on top of the stack is identical to the one below it.
17967 @code{glPopMatrix} pops the current matrix stack, replacing the current
17968 matrix with the one below it on the stack.
17970 Initially, each of the stacks contains one matrix, an identity matrix.
17972 It is an error to push a full matrix stack or to pop a matrix stack that
17973 contains only a single matrix. In either case, the error flag is set
17974 and no other change is made to GL state.
17976 @code{GL_STACK_OVERFLOW} is generated if @code{glPushMatrix} is called
17977 while the current matrix stack is full.
17979 @code{GL_STACK_UNDERFLOW} is generated if @code{glPopMatrix} is called
17980 while the current matrix stack contains only a single matrix.
17982 @code{GL_INVALID_OPERATION} is generated if @code{glPushMatrix} or
17983 @code{glPopMatrix} is executed between the execution of @code{glBegin}
17984 and the corresponding execution of @code{glEnd}.
17988 @deftypefun void glPushName name
17989 @deftypefunx void glPopName
17990 Push and pop the name stack.
17994 Specifies a name that will be pushed onto the name stack.
17998 The name stack is used during selection mode to allow sets of rendering
17999 commands to be uniquely identified. It consists of an ordered set of
18000 unsigned integers and is initially empty.
18002 @code{glPushName} causes @var{name} to be pushed onto the name stack.
18003 @code{glPopName} pops one name off the top of the stack.
18005 The maximum name stack depth is implementation-dependent; call
18006 @code{GL_MAX_NAME_STACK_DEPTH} to find out the value for a particular
18007 implementation. It is an error to push a name onto a full stack or to
18008 pop a name off an empty stack. It is also an error to manipulate the
18009 name stack between the execution of @code{glBegin} and the corresponding
18010 execution of @code{glEnd}. In any of these cases, the error flag is set
18011 and no other change is made to GL state.
18013 The name stack is always empty while the render mode is not
18014 @code{GL_SELECT}. Calls to @code{glPushName} or @code{glPopName} while
18015 the render mode is not @code{GL_SELECT} are ignored.
18017 @code{GL_STACK_OVERFLOW} is generated if @code{glPushName} is called
18018 while the name stack is full.
18020 @code{GL_STACK_UNDERFLOW} is generated if @code{glPopName} is called
18021 while the name stack is empty.
18023 @code{GL_INVALID_OPERATION} is generated if @code{glPushName} or
18024 @code{glPopName} is executed between a call to @code{glBegin} and the
18025 corresponding call to @code{glEnd}.
18029 @deftypefun void glRasterPos2s x y
18030 @deftypefunx void glRasterPos2i x y
18031 @deftypefunx void glRasterPos2f x y
18032 @deftypefunx void glRasterPos2d x y
18033 @deftypefunx void glRasterPos3s x y z
18034 @deftypefunx void glRasterPos3i x y z
18035 @deftypefunx void glRasterPos3f x y z
18036 @deftypefunx void glRasterPos3d x y z
18037 @deftypefunx void glRasterPos4s x y z w
18038 @deftypefunx void glRasterPos4i x y z w
18039 @deftypefunx void glRasterPos4f x y z w
18040 @deftypefunx void glRasterPos4d x y z w
18041 @deftypefunx void glRasterPos2sv v
18042 @deftypefunx void glRasterPos2iv v
18043 @deftypefunx void glRasterPos2fv v
18044 @deftypefunx void glRasterPos2dv v
18045 @deftypefunx void glRasterPos3sv v
18046 @deftypefunx void glRasterPos3iv v
18047 @deftypefunx void glRasterPos3fv v
18048 @deftypefunx void glRasterPos3dv v
18049 @deftypefunx void glRasterPos4sv v
18050 @deftypefunx void glRasterPos4iv v
18051 @deftypefunx void glRasterPos4fv v
18052 @deftypefunx void glRasterPos4dv v
18053 Specify the raster position for pixel operations.
18060 Specify the @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}
18061 object coordinates (if present) for the raster position.
18065 The GL maintains a 3D position in window coordinates. This position,
18066 called the raster position, is used to position pixel and bitmap write
18067 operations. It is maintained with subpixel accuracy. See
18068 @code{glBitmap}, @code{glDrawPixels}, and @code{glCopyPixels}.
18070 The current raster position consists of three window coordinates
18071 (@r{@var{x}}, @r{@var{y}}, @r{@var{z}}), a clip coordinate value
18072 (@r{@var{w}}), an eye coordinate distance, a valid bit, and associated
18073 color data and texture coordinates. The @r{@var{w}} coordinate is a
18074 clip coordinate, because @r{@var{w}} is not projected to window
18075 coordinates. @code{glRasterPos4} specifies object coordinates
18076 @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}} explicitly.
18077 @code{glRasterPos3} specifies object coordinate @r{@var{x}},
18078 @r{@var{y}}, and @r{@var{z}} explicitly, while @r{@var{w}} is implicitly
18079 set to 1. @code{glRasterPos2} uses the argument values for @r{@var{x}}
18080 and @r{@var{y}} while implicitly setting @r{@var{z}} and @r{@var{w}} to
18083 The object coordinates presented by @code{glRasterPos} are treated just
18084 like those of a @code{glVertex} command: They are transformed by the
18085 current modelview and projection matrices and passed to the clipping
18086 stage. If the vertex is not culled, then it is projected and scaled to
18087 window coordinates, which become the new current raster position, and
18088 the @code{GL_CURRENT_RASTER_POSITION_VALID} flag is set. If the vertex
18089 @var{is} culled, then the valid bit is cleared and the current raster
18090 position and associated color and texture coordinates are undefined.
18092 The current raster position also includes some associated color data and
18093 texture coordinates. If lighting is enabled, then
18094 @code{GL_CURRENT_RASTER_COLOR} (in RGBA mode) or
18095 @code{GL_CURRENT_RASTER_INDEX} (in color index mode) is set to the color
18096 produced by the lighting calculation (see @code{glLight},
18097 @code{glLightModel}, and @code{glShadeModel}). If lighting is disabled,
18098 current color (in RGBA mode, state variable @code{GL_CURRENT_COLOR}) or
18099 color index (in color index mode, state variable
18100 @code{GL_CURRENT_INDEX}) is used to update the current raster color.
18101 @code{GL_CURRENT_RASTER_SECONDARY_COLOR} (in RGBA mode) is likewise
18104 Likewise, @code{GL_CURRENT_RASTER_TEXTURE_COORDS} is updated as a
18105 function of @code{GL_CURRENT_TEXTURE_COORDS}, based on the texture
18106 matrix and the texture generation functions (see @code{glTexGen}).
18107 Finally, the distance from the origin of the eye coordinate system to
18108 the vertex as transformed by only the modelview matrix replaces
18109 @code{GL_CURRENT_RASTER_DISTANCE}.
18111 Initially, the current raster position is (0, 0, 0, 1), the current
18112 raster distance is 0, the valid bit is set, the associated RGBA color is
18113 (1, 1, 1, 1), the associated color index is 1, and the associated
18114 texture coordinates are (0, 0, 0, 1). In RGBA mode,
18115 @code{GL_CURRENT_RASTER_INDEX} is always 1; in color index mode, the
18116 current raster RGBA color always maintains its initial value.
18118 @code{GL_INVALID_OPERATION} is generated if @code{glRasterPos} is
18119 executed between the execution of @code{glBegin} and the corresponding
18120 execution of @code{glEnd}.
18124 @deftypefun void glReadBuffer mode
18125 Select a color buffer source for pixels.
18129 Specifies a color buffer. Accepted values are @code{GL_FRONT_LEFT},
18130 @code{GL_FRONT_RIGHT}, @code{GL_BACK_LEFT}, @code{GL_BACK_RIGHT},
18131 @code{GL_FRONT}, @code{GL_BACK}, @code{GL_LEFT}, @code{GL_RIGHT}, and
18132 @code{GL_AUX}@var{i}, where @var{i} is between 0 and the value of
18133 @code{GL_AUX_BUFFERS} minus 1.
18137 @code{glReadBuffer} specifies a color buffer as the source for
18138 subsequent @code{glReadPixels}, @code{glCopyTexImage1D},
18139 @code{glCopyTexImage2D}, @code{glCopyTexSubImage1D},
18140 @code{glCopyTexSubImage2D}, @code{glCopyTexSubImage3D}, and
18141 @code{glCopyPixels} commands. @var{mode} accepts one of twelve or more
18142 predefined values. (@code{GL_AUX0} through @code{GL_AUX3} are always
18143 defined.) In a fully configured system, @code{GL_FRONT}, @code{GL_LEFT},
18144 and @code{GL_FRONT_LEFT} all name the front left buffer,
18145 @code{GL_FRONT_RIGHT} and @code{GL_RIGHT} name the front right buffer,
18146 and @code{GL_BACK_LEFT} and @code{GL_BACK} name the back left buffer.
18148 Nonstereo double-buffered configurations have only a front left and a
18149 back left buffer. Single-buffered configurations have a front left and
18150 a front right buffer if stereo, and only a front left buffer if
18151 nonstereo. It is an error to specify a nonexistent buffer to
18152 @code{glReadBuffer}.
18154 @var{mode} is initially @code{GL_FRONT} in single-buffered
18155 configurations and @code{GL_BACK} in double-buffered configurations.
18157 @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of the
18158 twelve (or more) accepted values.
18160 @code{GL_INVALID_OPERATION} is generated if @var{mode} specifies a
18161 buffer that does not exist.
18163 @code{GL_INVALID_OPERATION} is generated if @code{glReadBuffer} is
18164 executed between the execution of @code{glBegin} and the corresponding
18165 execution of @code{glEnd}.
18169 @deftypefun void glReadPixels x y width height format type data
18170 Read a block of pixels from the frame buffer.
18175 Specify the window coordinates of the first pixel that is read from the
18176 frame buffer. This location is the lower left corner of a rectangular
18180 @itemx @var{height}
18181 Specify the dimensions of the pixel rectangle. @var{width} and
18182 @var{height} of one correspond to a single pixel.
18185 Specifies the format of the pixel data. The following symbolic values
18186 are accepted: @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX},
18187 @code{GL_DEPTH_COMPONENT}, @code{GL_RED}, @code{GL_GREEN},
18188 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
18189 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
18190 @code{GL_LUMINANCE_ALPHA}.
18193 Specifies the data type of the pixel data. Must be one of
18194 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
18195 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
18196 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
18197 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
18198 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
18199 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
18200 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
18201 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
18202 or @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
18205 Returns the pixel data.
18209 @code{glReadPixels} returns pixel data from the frame buffer, starting
18210 with the pixel whose lower left corner is at location (@var{x},
18211 @var{y}), into client memory starting at location @var{data}. Several
18212 parameters control the processing of the pixel data before it is placed
18213 into client memory. These parameters are set with three commands:
18214 @code{glPixelStore}, @code{glPixelTransfer}, and @code{glPixelMap}. This
18215 reference page describes the effects on @code{glReadPixels} of most, but
18216 not all of the parameters specified by these three commands.
18218 If a non-zero named buffer object is bound to the
18219 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
18220 block of pixels is requested, @var{data} is treated as a byte offset
18221 into the buffer object's data store rather than a pointer to client
18224 When the @code{ARB_imaging} extension is supported, the pixel data may
18225 be processed by additional operations including color table lookup,
18226 color matrix transformations, convolutions, histograms, and minimum and
18227 maximum pixel value computations.
18229 @code{glReadPixels} returns values from each pixel with lower left
18230 corner at @r{(@var{x}+@var{i},@var{y}+@var{j})} for
18231 @r{0<=@var{i}<@var{width}} and @r{0<=@var{j}<@var{height}}. This pixel
18232 is said to be the @r{@var{i}}th pixel in the @r{@var{j}}th row. Pixels
18233 are returned in row order from the lowest to the highest row, left to
18236 @var{format} specifies the format for the returned pixel values;
18237 accepted values are:
18240 @item @code{GL_COLOR_INDEX}
18241 Color indices are read from the color buffer selected by
18242 @code{glReadBuffer}. Each index is converted to fixed point, shifted
18243 left or right depending on the value and sign of @code{GL_INDEX_SHIFT},
18244 and added to @code{GL_INDEX_OFFSET}. If @code{GL_MAP_COLOR} is
18245 @code{GL_TRUE}, indices are replaced by their mappings in the table
18246 @code{GL_PIXEL_MAP_I_TO_I}.
18248 @item @code{GL_STENCIL_INDEX}
18249 Stencil values are read from the stencil buffer. Each index is
18250 converted to fixed point, shifted left or right depending on the value
18251 and sign of @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET}.
18252 If @code{GL_MAP_STENCIL} is @code{GL_TRUE}, indices are replaced by
18253 their mappings in the table @code{GL_PIXEL_MAP_S_TO_S}.
18255 @item @code{GL_DEPTH_COMPONENT}
18256 Depth values are read from the depth buffer. Each component is
18257 converted to floating point such that the minimum depth value maps to 0
18258 and the maximum value maps to 1. Each component is then multiplied by
18259 @code{GL_DEPTH_SCALE}, added to @code{GL_DEPTH_BIAS}, and finally
18260 clamped to the range @r{[0,1]}.
18262 @item @code{GL_RED}
18263 @item @code{GL_GREEN}
18264 @item @code{GL_BLUE}
18265 @item @code{GL_ALPHA}
18266 @item @code{GL_RGB}
18267 @item @code{GL_BGR}
18268 @item @code{GL_RGBA}
18269 @item @code{GL_BGRA}
18270 @item @code{GL_LUMINANCE}
18271 @item @code{GL_LUMINANCE_ALPHA}
18272 Processing differs depending on whether color buffers store color
18273 indices or RGBA color components. If color indices are stored, they are
18274 read from the color buffer selected by @code{glReadBuffer}. Each index
18275 is converted to fixed point, shifted left or right depending on the
18276 value and sign of @code{GL_INDEX_SHIFT}, and added to
18277 @code{GL_INDEX_OFFSET}. Indices are then replaced by the red, green,
18278 blue, and alpha values obtained by indexing the tables
18279 @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G},
18280 @code{GL_PIXEL_MAP_I_TO_B}, and @code{GL_PIXEL_MAP_I_TO_A}. Each table
18281 must be of size @r{2^@var{n}}, but @r{@var{n}} may be different for
18282 different tables. Before an index is used to look up a value in a table
18283 of size @r{2^@var{n}}, it must be masked against @r{2^@var{n}-1}.
18285 If RGBA color components are stored in the color buffers, they are read
18286 from the color buffer selected by @code{glReadBuffer}. Each color
18287 component is converted to floating point such that zero intensity maps
18288 to 0.0 and full intensity maps to 1.0. Each component is then
18289 multiplied by @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where
18290 @var{c} is RED, GREEN, BLUE, or ALPHA. Finally, if @code{GL_MAP_COLOR}
18291 is @code{GL_TRUE}, each component is clamped to the range @r{[0,1]},
18292 scaled to the size of its corresponding table, and is then replaced by
18293 its mapping in the table @code{GL_PIXEL_MAP_c_TO_c}, where @var{c} is R,
18296 Unneeded data is then discarded. For example, @code{GL_RED} discards
18297 the green, blue, and alpha components, while @code{GL_RGB} discards only
18298 the alpha component. @code{GL_LUMINANCE} computes a single-component
18299 value as the sum of the red, green, and blue components, and
18300 @code{GL_LUMINANCE_ALPHA} does the same, while keeping alpha as a second
18301 value. The final values are clamped to the range @r{[0,1]}.
18305 The shift, scale, bias, and lookup factors just described are all
18306 specified by @code{glPixelTransfer}. The lookup table contents
18307 themselves are specified by @code{glPixelMap}.
18309 Finally, the indices or components are converted to the proper format,
18310 as specified by @var{type}. If @var{format} is @code{GL_COLOR_INDEX} or
18311 @code{GL_STENCIL_INDEX} and @var{type} is not @code{GL_FLOAT}, each
18312 index is masked with the mask value given in the following table. If
18313 @var{type} is @code{GL_FLOAT}, then each integer index is converted to
18314 single-precision floating-point format.
18316 If @var{format} is @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE},
18317 @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA},
18318 @code{GL_BGRA}, @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA} and
18319 @var{type} is not @code{GL_FLOAT}, each component is multiplied by the
18320 multiplier shown in the following table. If type is @code{GL_FLOAT},
18321 then each component is passed as is (or converted to the client's
18322 single-precision floating-point format if it is different from the one
18329 @strong{Index Mask}, @strong{Component Conversion}
18331 @item @code{GL_UNSIGNED_BYTE}
18332 @r{2^8-1}, @r{(2^8-1,)@var{c}}
18334 @item @code{GL_BYTE}
18335 @r{2^7-1}, @r{(2^8-1,)@var{c}-1,/2}
18337 @item @code{GL_BITMAP}
18340 @item @code{GL_UNSIGNED_SHORT}
18341 @r{2^16-1}, @r{(2^16-1,)@var{c}}
18343 @item @code{GL_SHORT}
18344 @r{2^15-1}, @r{(2^16-1,)@var{c}-1,/2}
18346 @item @code{GL_UNSIGNED_INT}
18347 @r{2^32-1}, @r{(2^32-1,)@var{c}}
18349 @item @code{GL_INT}
18350 @r{2^31-1}, @r{(2^32-1,)@var{c}-1,/2}
18352 @item @code{GL_FLOAT}
18357 Return values are placed in memory as follows. If @var{format} is
18358 @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX},
18359 @code{GL_DEPTH_COMPONENT}, @code{GL_RED}, @code{GL_GREEN},
18360 @code{GL_BLUE}, @code{GL_ALPHA}, or @code{GL_LUMINANCE}, a single value
18361 is returned and the data for the @r{@var{i}}th pixel in the
18362 @r{@var{j}}th row is placed in location
18363 @r{(@var{j},)@var{width}+@var{i}}. @code{GL_RGB} and @code{GL_BGR}
18364 return three values, @code{GL_RGBA} and @code{GL_BGRA} return four
18365 values, and @code{GL_LUMINANCE_ALPHA} returns two values for each pixel,
18366 with all values corresponding to a single pixel occupying contiguous
18367 space in @var{data}. Storage parameters set by @code{glPixelStore},
18368 such as @code{GL_PACK_LSB_FIRST} and @code{GL_PACK_SWAP_BYTES}, affect
18369 the way that data is written into memory. See @code{glPixelStore} for a
18372 @code{GL_INVALID_ENUM} is generated if @var{format} or @var{type} is not
18375 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
18376 and @var{format} is not @code{GL_COLOR_INDEX} or
18377 @code{GL_STENCIL_INDEX}.
18379 @code{GL_INVALID_VALUE} is generated if either @var{width} or
18380 @var{height} is negative.
18382 @code{GL_INVALID_OPERATION} is generated if @var{format} is
18383 @code{GL_COLOR_INDEX} and the color buffers store RGBA color components.
18385 @code{GL_INVALID_OPERATION} is generated if @var{format} is
18386 @code{GL_STENCIL_INDEX} and there is no stencil buffer.
18388 @code{GL_INVALID_OPERATION} is generated if @var{format} is
18389 @code{GL_DEPTH_COMPONENT} and there is no depth buffer.
18391 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
18392 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
18393 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
18394 and @var{format} is not @code{GL_RGB}.
18396 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
18397 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
18398 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
18399 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
18400 @code{GL_UNSIGNED_INT_10_10_10_2}, or
18401 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
18402 @code{GL_RGBA} nor @code{GL_BGRA}.
18404 The formats @code{GL_BGR}, and @code{GL_BGRA} and types
18405 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
18406 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
18407 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
18408 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
18409 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
18410 @code{GL_UNSIGNED_INT_10_10_10_2}, and
18411 @code{GL_UNSIGNED_INT_2_10_10_10_REV} are available only if the GL
18412 version is 1.2 or greater.
18414 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
18415 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
18416 object's data store is currently mapped.
18418 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
18419 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
18420 would be packed to the buffer object such that the memory writes
18421 required would exceed the data store size.
18423 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
18424 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{data}
18425 is not evenly divisible into the number of bytes needed to store in
18426 memory a datum indicated by @var{type}.
18428 @code{GL_INVALID_OPERATION} is generated if @code{glReadPixels} is
18429 executed between the execution of @code{glBegin} and the corresponding
18430 execution of @code{glEnd}.
18434 @deftypefun void glRectd x1 y1 x2 y2
18435 @deftypefunx void glRectf x1 y1 x2 y2
18436 @deftypefunx void glRecti x1 y1 x2 y2
18437 @deftypefunx void glRects x1 y1 x2 y2
18438 @deftypefunx void glRectdv v1 v2
18439 @deftypefunx void glRectfv v1 v2
18440 @deftypefunx void glRectiv v1 v2
18441 @deftypefunx void glRectsv v1 v2
18447 Specify one vertex of a rectangle.
18451 Specify the opposite vertex of the rectangle.
18455 @code{glRect} supports efficient specification of rectangles as two
18456 corner points. Each rectangle command takes four arguments, organized
18457 either as two consecutive pairs of @r{(@var{x},@var{y})} coordinates or
18458 as two pointers to arrays, each containing an @r{(@var{x},@var{y})}
18459 pair. The resulting rectangle is defined in the @r{@var{z}=0} plane.
18461 @code{glRect}(@var{x1}, @var{y1}, @var{x2}, @var{y2}) is exactly
18462 equivalent to the following sequence: Note that if the second vertex is
18463 above and to the right of the first vertex, the rectangle is constructed
18464 with a counterclockwise winding.
18468 glBegin(@code{GL_POLYGON});
18469 glVertex2(@var{x1}, @var{y1});
18470 glVertex2(@var{x2}, @var{y1});
18471 glVertex2(@var{x2}, @var{y2});
18472 glVertex2(@var{x1}, @var{y2});
18476 @code{GL_INVALID_OPERATION} is generated if @code{glRect} is executed
18477 between the execution of @code{glBegin} and the corresponding execution
18482 @deftypefun GLint glRenderMode mode
18483 Set rasterization mode.
18487 Specifies the rasterization mode. Three values are accepted:
18488 @code{GL_RENDER}, @code{GL_SELECT}, and @code{GL_FEEDBACK}. The initial
18489 value is @code{GL_RENDER}.
18493 @code{glRenderMode} sets the rasterization mode. It takes one argument,
18494 @var{mode}, which can assume one of three predefined values:
18497 @item @code{GL_RENDER}
18498 Render mode. Primitives are rasterized, producing pixel fragments,
18499 which are written into the frame buffer. This is the normal mode and
18500 also the default mode.
18502 @item @code{GL_SELECT}
18503 Selection mode. No pixel fragments are produced, and no change to the
18504 frame buffer contents is made. Instead, a record of the names of
18505 primitives that would have been drawn if the render mode had been
18506 @code{GL_RENDER} is returned in a select buffer, which must be created
18507 (see @code{glSelectBuffer}) before selection mode is entered.
18509 @item @code{GL_FEEDBACK}
18510 Feedback mode. No pixel fragments are produced, and no change to the
18511 frame buffer contents is made. Instead, the coordinates and attributes
18512 of vertices that would have been drawn if the render mode had been
18513 @code{GL_RENDER} is returned in a feedback buffer, which must be created
18514 (see @code{glFeedbackBuffer}) before feedback mode is entered.
18518 The return value of @code{glRenderMode} is determined by the render mode
18519 at the time @code{glRenderMode} is called, rather than by @var{mode}.
18520 The values returned for the three render modes are as follows:
18523 @item @code{GL_RENDER}
18526 @item @code{GL_SELECT}
18527 The number of hit records transferred to the select buffer.
18529 @item @code{GL_FEEDBACK}
18530 The number of values (not vertices) transferred to the feedback buffer.
18534 See the @code{glSelectBuffer} and @code{glFeedbackBuffer} reference
18535 pages for more details concerning selection and feedback operation.
18537 @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of the
18538 three accepted values.
18540 @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is
18541 called while the render mode is @code{GL_SELECT}, or if
18542 @code{glRenderMode} is called with argument @code{GL_SELECT} before
18543 @code{glSelectBuffer} is called at least once.
18545 @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is
18546 called while the render mode is @code{GL_FEEDBACK}, or if
18547 @code{glRenderMode} is called with argument @code{GL_FEEDBACK} before
18548 @code{glFeedbackBuffer} is called at least once.
18550 @code{GL_INVALID_OPERATION} is generated if @code{glRenderMode} is
18551 executed between the execution of @code{glBegin} and the corresponding
18552 execution of @code{glEnd}.
18556 @deftypefun void glResetHistogram target
18557 Reset histogram table entries to zero.
18561 Must be @code{GL_HISTOGRAM}.
18565 @code{glResetHistogram} resets all the elements of the current histogram
18568 @code{GL_INVALID_ENUM} is generated if @var{target} is not
18569 @code{GL_HISTOGRAM}.
18571 @code{GL_INVALID_OPERATION} is generated if @code{glResetHistogram} is
18572 executed between the execution of @code{glBegin} and the corresponding
18573 execution of @code{glEnd}.
18577 @deftypefun void glResetMinmax target
18578 Reset minmax table entries to initial values.
18582 Must be @code{GL_MINMAX}.
18586 @code{glResetMinmax} resets the elements of the current minmax table to
18587 their initial values: the ``maximum'' element receives the minimum
18588 possible component values, and the ``minimum'' element receives the
18589 maximum possible component values.
18591 @code{GL_INVALID_ENUM} is generated if @var{target} is not
18594 @code{GL_INVALID_OPERATION} is generated if @code{glResetMinmax} is
18595 executed between the execution of @code{glBegin} and the corresponding
18596 execution of @code{glEnd}.
18600 @deftypefun void glRotated angle x y z
18601 @deftypefunx void glRotatef angle x y z
18602 Multiply the current matrix by a rotation matrix.
18606 Specifies the angle of rotation, in degrees.
18611 Specify the @var{x}, @var{y}, and @var{z} coordinates of a vector,
18616 @code{glRotate} produces a rotation of @var{angle} degrees around the
18617 vector @r{(@var{x},@var{y}@var{z})}. The current matrix (see
18618 @code{glMatrixMode}) is multiplied by a rotation matrix with the product
18619 replacing the current matrix, as if @code{glMultMatrix} were called with
18620 the following matrix as its argument:
18622 @r{((@var{x}^2(1-@var{c},)+@var{c}
18623 @var{x}@var{y}(1-@var{c},)-@var{z}@var{s}
18624 @var{x}@var{z}(1-@var{c},)+@var{y}@var{s} 0),
18625 (@var{y}@var{x}(1-@var{c},)+@var{z}@var{s}
18626 @var{y}^2(1-@var{c},)+@var{c}
18627 @var{y}@var{z}(1-@var{c},)-@var{x}@var{s} 0),
18628 (@var{x}@var{z}(1-@var{c},)-@var{y}@var{s}
18629 @var{y}@var{z}(1-@var{c},)+@var{x}@var{s}
18630 @var{z}^2(1-@var{c},)+@var{c} 0), (0 0 0 1),)}
18634 Where @r{@var{c}=@var{cos}(@var{angle},)},
18635 @r{@var{s}=@var{sin}(@var{angle},)}, and
18636 @r{∥(@var{x},@var{y}@var{z}),∥=1} (if not, the GL will normalize this
18643 If the matrix mode is either @code{GL_MODELVIEW} or
18644 @code{GL_PROJECTION}, all objects drawn after @code{glRotate} is called
18645 are rotated. Use @code{glPushMatrix} and @code{glPopMatrix} to save and
18646 restore the unrotated coordinate system.
18648 @code{GL_INVALID_OPERATION} is generated if @code{glRotate} is executed
18649 between the execution of @code{glBegin} and the corresponding execution
18654 @deftypefun void glSampleCoverage value invert
18655 Specify multisample coverage parameters.
18659 Specify a single floating-point sample coverage value. The value is
18660 clamped to the range @r{[0,1]}. The initial value is 1.0.
18663 Specify a single boolean value representing if the coverage masks should
18664 be inverted. @code{GL_TRUE} and @code{GL_FALSE} are accepted. The
18665 initial value is @code{GL_FALSE}.
18669 Multisampling samples a pixel multiple times at various
18670 implementation-dependent subpixel locations to generate antialiasing
18671 effects. Multisampling transparently antialiases points, lines,
18672 polygons, bitmaps, and images if it is enabled.
18674 @var{value} is used in constructing a temporary mask used in determining
18675 which samples will be used in resolving the final fragment color. This
18676 mask is bitwise-anded with the coverage mask generated from the
18677 multisampling computation. If the @var{invert} flag is set, the
18678 temporary mask is inverted (all bits flipped) and then the bitwise-and
18681 If an implementation does not have any multisample buffers available, or
18682 multisampling is disabled, rasterization occurs with only a single
18683 sample computing a pixel's final RGB color.
18685 Provided an implementation supports multisample buffers, and
18686 multisampling is enabled, then a pixel's final color is generated by
18687 combining several samples per pixel. Each sample contains color, depth,
18688 and stencil information, allowing those operations to be performed on
18691 @code{GL_INVALID_OPERATION} is generated if @code{glSampleCoverage} is
18692 executed between the execution of @code{glBegin} and the corresponding
18693 execution of @code{glEnd}.
18697 @deftypefun void glScaled x y z
18698 @deftypefunx void glScalef x y z
18699 Multiply the current matrix by a general scaling matrix.
18705 Specify scale factors along the @var{x}, @var{y}, and @var{z} axes,
18710 @code{glScale} produces a nonuniform scaling along the @var{x}, @var{y},
18711 and @var{z} axes. The three parameters indicate the desired scale
18712 factor along each of the three axes.
18714 The current matrix (see @code{glMatrixMode}) is multiplied by this scale
18715 matrix, and the product replaces the current matrix as if
18716 @code{glMultMatrix} were called with the following matrix as its
18719 @r{((@var{x} 0 0 0), (0 @var{y} 0 0), (0 0 @var{z} 0), (0 0 0 1),)}
18721 If the matrix mode is either @code{GL_MODELVIEW} or
18722 @code{GL_PROJECTION}, all objects drawn after @code{glScale} is called
18725 Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the
18726 unscaled coordinate system.
18728 @code{GL_INVALID_OPERATION} is generated if @code{glScale} is executed
18729 between the execution of @code{glBegin} and the corresponding execution
18734 @deftypefun void glScissor x y width height
18735 Define the scissor box.
18740 Specify the lower left corner of the scissor box. Initially (0, 0).
18743 @itemx @var{height}
18744 Specify the width and height of the scissor box. When a GL context is
18745 first attached to a window, @var{width} and @var{height} are set to the
18746 dimensions of that window.
18750 @code{glScissor} defines a rectangle, called the scissor box, in window
18751 coordinates. The first two arguments, @var{x} and @var{y}, specify the
18752 lower left corner of the box. @var{width} and @var{height} specify the
18753 width and height of the box.
18755 To enable and disable the scissor test, call @code{glEnable} and
18756 @code{glDisable} with argument @code{GL_SCISSOR_TEST}. The test is
18757 initially disabled. While the test is enabled, only pixels that lie
18758 within the scissor box can be modified by drawing commands. Window
18759 coordinates have integer values at the shared corners of frame buffer
18760 pixels. @code{glScissor(0,0,1,1)} allows modification of only the lower
18761 left pixel in the window, and @code{glScissor(0,0,0,0)} doesn't allow
18762 modification of any pixels in the window.
18764 When the scissor test is disabled, it is as though the scissor box
18765 includes the entire window.
18767 @code{GL_INVALID_VALUE} is generated if either @var{width} or
18768 @var{height} is negative.
18770 @code{GL_INVALID_OPERATION} is generated if @code{glScissor} is executed
18771 between the execution of @code{glBegin} and the corresponding execution
18776 @deftypefun void glSecondaryColorPointer size type stride pointer
18777 Define an array of secondary colors.
18781 Specifies the number of components per color. Must be 3.
18784 Specifies the data type of each color component in the array. Symbolic
18785 constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
18786 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
18787 @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is
18791 Specifies the byte offset between consecutive colors. If @var{stride}
18792 is 0, the colors are understood to be tightly packed in the array. The
18793 initial value is 0.
18795 @item @var{pointer}
18796 Specifies a pointer to the first component of the first color element in
18797 the array. The initial value is 0.
18801 @code{glSecondaryColorPointer} specifies the location and data format of
18802 an array of color components to use when rendering. @var{size}
18803 specifies the number of components per color, and must be 3. @var{type}
18804 specifies the data type of each color component, and @var{stride}
18805 specifies the byte stride from one color to the next, allowing vertices
18806 and attributes to be packed into a single array or stored in separate
18809 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
18810 target (see @code{glBindBuffer}) while a secondary color array is
18811 specified, @var{pointer} is treated as a byte offset into the buffer
18812 object's data store. Also, the buffer object binding
18813 (@code{GL_ARRAY_BUFFER_BINDING}) is saved as secondary color vertex
18814 array client-side state
18815 (@code{GL_SECONDARY_COLOR_ARRAY_BUFFER_BINDING}).
18817 When a secondary color array is specified, @var{size}, @var{type},
18818 @var{stride}, and @var{pointer} are saved as client-side state, in
18819 addition to the current vertex array buffer object binding.
18821 To enable and disable the secondary color array, call
18822 @code{glEnableClientState} and @code{glDisableClientState} with the
18823 argument @code{GL_SECONDARY_COLOR_ARRAY}. If enabled, the secondary
18824 color array is used when @code{glArrayElement}, @code{glDrawArrays},
18825 @code{glMultiDrawArrays}, @code{glDrawElements},
18826 @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called.
18828 @code{GL_INVALID_VALUE} is generated if @var{size} is not 3.
18830 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
18833 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
18837 @deftypefun void glSecondaryColor3b red green blue
18838 @deftypefunx void glSecondaryColor3s red green blue
18839 @deftypefunx void glSecondaryColor3i red green blue
18840 @deftypefunx void glSecondaryColor3f red green blue
18841 @deftypefunx void glSecondaryColor3d red green blue
18842 @deftypefunx void glSecondaryColor3ub red green blue
18843 @deftypefunx void glSecondaryColor3us red green blue
18844 @deftypefunx void glSecondaryColor3ui red green blue
18845 @deftypefunx void glSecondaryColor3bv v
18846 @deftypefunx void glSecondaryColor3sv v
18847 @deftypefunx void glSecondaryColor3iv v
18848 @deftypefunx void glSecondaryColor3fv v
18849 @deftypefunx void glSecondaryColor3dv v
18850 @deftypefunx void glSecondaryColor3ubv v
18851 @deftypefunx void glSecondaryColor3usv v
18852 @deftypefunx void glSecondaryColor3uiv v
18853 Set the current secondary color.
18859 Specify new red, green, and blue values for the current secondary color.
18863 The GL stores both a primary four-valued RGBA color and a secondary
18864 four-valued RGBA color (where alpha is always set to 0.0) that is
18865 associated with every vertex.
18867 The secondary color is interpolated and applied to each fragment during
18868 rasterization when @code{GL_COLOR_SUM} is enabled. When lighting is
18869 enabled, and @code{GL_SEPARATE_SPECULAR_COLOR} is specified, the value
18870 of the secondary color is assigned the value computed from the specular
18871 term of the lighting computation. Both the primary and secondary
18872 current colors are applied to each fragment, regardless of the state of
18873 @code{GL_COLOR_SUM}, under such conditions. When
18874 @code{GL_SEPARATE_SPECULAR_COLOR} is specified, the value returned from
18875 querying the current secondary color is undefined.
18877 @code{glSecondaryColor3b}, @code{glSecondaryColor3s}, and
18878 @code{glSecondaryColor3i} take three signed byte, short, or long
18879 integers as arguments. When @strong{v} is appended to the name, the
18880 color commands can take a pointer to an array of such values.
18882 Color values are stored in floating-point format, with unspecified
18883 mantissa and exponent sizes. Unsigned integer color components, when
18884 specified, are linearly mapped to floating-point values such that the
18885 largest representable value maps to 1.0 (full intensity), and 0 maps to
18886 0.0 (zero intensity). Signed integer color components, when specified,
18887 are linearly mapped to floating-point values such that the most positive
18888 representable value maps to 1.0, and the most negative representable
18889 value maps to @r{-1.0}. (Note that this mapping does not convert 0
18890 precisely to 0.0). Floating-point values are mapped directly.
18892 Neither floating-point nor signed integer values are clamped to the
18893 range @r{[0,1]} before the current color is updated. However, color
18894 components are clamped to this range before they are interpolated or
18895 written into a color buffer.
18899 @deftypefun void glSelectBuffer size buffer
18900 Establish a buffer for selection mode values.
18904 Specifies the size of @var{buffer}.
18907 Returns the selection data.
18911 @code{glSelectBuffer} has two arguments: @var{buffer} is a pointer to an
18912 array of unsigned integers, and @var{size} indicates the size of the
18913 array. @var{buffer} returns values from the name stack (see
18914 @code{glInitNames}, @code{glLoadName}, @code{glPushName}) when the
18915 rendering mode is @code{GL_SELECT} (see @code{glRenderMode}).
18916 @code{glSelectBuffer} must be issued before selection mode is enabled,
18917 and it must not be issued while the rendering mode is @code{GL_SELECT}.
18919 A programmer can use selection to determine which primitives are drawn
18920 into some region of a window. The region is defined by the current
18921 modelview and perspective matrices.
18923 In selection mode, no pixel fragments are produced from rasterization.
18924 Instead, if a primitive or a raster position intersects the clipping
18925 volume defined by the viewing frustum and the user-defined clipping
18926 planes, this primitive causes a selection hit. (With polygons, no hit
18927 occurs if the polygon is culled.) When a change is made to the name
18928 stack, or when @code{glRenderMode} is called, a hit record is copied to
18929 @var{buffer} if any hits have occurred since the last such event (name
18930 stack change or @code{glRenderMode} call). The hit record consists of
18931 the number of names in the name stack at the time of the event, followed
18932 by the minimum and maximum depth values of all vertices that hit since
18933 the previous event, followed by the name stack contents, bottom name
18936 Depth values (which are in the range [0,1]) are multiplied by
18937 @r{2^32-1}, before being placed in the hit record.
18939 An internal index into @var{buffer} is reset to 0 whenever selection
18940 mode is entered. Each time a hit record is copied into @var{buffer},
18941 the index is incremented to point to the cell just past the end of the
18942 block of names\(emthat is, to the next available cell If the hit record
18943 is larger than the number of remaining locations in @var{buffer}, as
18944 much data as can fit is copied, and the overflow flag is set. If the
18945 name stack is empty when a hit record is copied, that record consists of
18946 0 followed by the minimum and maximum depth values.
18948 To exit selection mode, call @code{glRenderMode} with an argument other
18949 than @code{GL_SELECT}. Whenever @code{glRenderMode} is called while the
18950 render mode is @code{GL_SELECT}, it returns the number of hit records
18951 copied to @var{buffer}, resets the overflow flag and the selection
18952 buffer pointer, and initializes the name stack to be empty. If the
18953 overflow bit was set when @code{glRenderMode} was called, a negative hit
18954 record count is returned.
18956 @code{GL_INVALID_VALUE} is generated if @var{size} is negative.
18958 @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is
18959 called while the render mode is @code{GL_SELECT}, or if
18960 @code{glRenderMode} is called with argument @code{GL_SELECT} before
18961 @code{glSelectBuffer} is called at least once.
18963 @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is
18964 executed between the execution of @code{glBegin} and the corresponding
18965 execution of @code{glEnd}.
18969 @deftypefun void glSeparableFilter2D target internalformat width height format type row column
18970 Define a separable two-dimensional convolution filter.
18974 Must be @code{GL_SEPARABLE_2D}.
18976 @item @var{internalformat}
18977 The internal format of the convolution filter kernel. The allowable
18978 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
18979 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
18980 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
18981 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
18982 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
18983 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
18984 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
18985 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
18986 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
18987 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
18988 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
18989 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
18990 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
18993 The number of elements in the pixel array referenced by @var{row}. (This
18994 is the width of the separable filter kernel.)
18997 The number of elements in the pixel array referenced by @var{column}.
18998 (This is the height of the separable filter kernel.)
19001 The format of the pixel data in @var{row} and @var{column}. The
19002 allowable values are @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE},
19003 @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA},
19004 @code{GL_BGRA}, @code{GL_INTENSITY}, @code{GL_LUMINANCE}, and
19005 @code{GL_LUMINANCE_ALPHA}.
19008 The type of the pixel data in @var{row} and @var{column}. Symbolic
19009 constants @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
19010 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
19011 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
19012 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
19013 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
19014 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
19015 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
19016 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
19017 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
19020 Pointer to a one-dimensional array of pixel data that is processed to
19021 build the row filter kernel.
19024 Pointer to a one-dimensional array of pixel data that is processed to
19025 build the column filter kernel.
19029 @code{glSeparableFilter2D} builds a two-dimensional separable
19030 convolution filter kernel from two arrays of pixels.
19032 The pixel arrays specified by (@var{width}, @var{format}, @var{type},
19033 @var{row}) and (@var{height}, @var{format}, @var{type}, @var{column})
19034 are processed just as if they had been passed to @code{glDrawPixels},
19035 but processing stops after the final expansion to RGBA is completed.
19037 If a non-zero named buffer object is bound to the
19038 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
19039 convolution filter is specified, @var{row} and @var{column} are treated
19040 as byte offsets into the buffer object's data store.
19042 Next, the R, G, B, and A components of all pixels in both arrays are
19043 scaled by the four separable 2D @code{GL_CONVOLUTION_FILTER_SCALE}
19044 parameters and biased by the four separable 2D
19045 @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
19046 parameters are set by @code{glConvolutionParameter} using the
19047 @code{GL_SEPARABLE_2D} target and the names
19048 @code{GL_CONVOLUTION_FILTER_SCALE} and
19049 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are
19050 vectors of four values that are applied to red, green, blue, and alpha,
19051 in that order.) The R, G, B, and A values are not clamped to [0,1] at
19052 any time during this process.
19054 Each pixel is then converted to the internal format specified by
19055 @var{internalformat}. This conversion simply maps the component values
19056 of the pixel (R, G, B, and A) to the values included in the internal
19057 format (red, green, blue, alpha, luminance, and intensity). The mapping
19061 @item @strong{Internal Format}
19062 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
19063 @strong{Luminance}, @strong{Intensity}
19065 @item @code{GL_LUMINANCE}
19068 @item @code{GL_LUMINANCE_ALPHA}
19071 @item @code{GL_INTENSITY}
19074 @item @code{GL_RGB}
19077 @item @code{GL_RGBA}
19082 The red, green, blue, alpha, luminance, and/or intensity components of
19083 the resulting pixels are stored in floating-point rather than integer
19084 format. They form two one-dimensional filter kernel images. The row
19085 image is indexed by coordinate @var{i} starting at zero and increasing
19086 from left to right. Each location in the row image is derived from
19087 element @var{i} of @var{row}. The column image is indexed by coordinate
19088 @var{j} starting at zero and increasing from bottom to top. Each
19089 location in the column image is derived from element @var{j} of
19092 Note that after a convolution is performed, the resulting color
19093 components are also scaled by their corresponding
19094 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
19095 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
19096 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
19097 and @strong{ALPHA}). These parameters are set by
19098 @code{glPixelTransfer}.
19100 @code{GL_INVALID_ENUM} is generated if @var{target} is not
19101 @code{GL_SEPARABLE_2D}.
19103 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
19104 of the allowable values.
19106 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
19109 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
19112 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
19113 greater than the maximum supported value. This value may be queried
19114 with @code{glGetConvolutionParameter} using target
19115 @code{GL_SEPARABLE_2D} and name @code{GL_MAX_CONVOLUTION_WIDTH}.
19117 @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero
19118 or greater than the maximum supported value. This value may be queried
19119 with @code{glGetConvolutionParameter} using target
19120 @code{GL_SEPARABLE_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}.
19122 @code{GL_INVALID_OPERATION} is generated if @var{height} is one of
19123 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
19124 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
19125 and @var{format} is not @code{GL_RGB}.
19127 @code{GL_INVALID_OPERATION} is generated if @var{height} is one of
19128 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
19129 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
19130 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
19131 @code{GL_UNSIGNED_INT_10_10_10_2}, or
19132 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
19133 @code{GL_RGBA} nor @code{GL_BGRA}.
19135 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
19136 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
19137 object's data store is currently mapped.
19139 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
19140 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
19141 would be unpacked from the buffer object such that the memory reads
19142 required would exceed the data store size.
19144 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
19145 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{row}
19146 or @var{column} is not evenly divisible into the number of bytes needed
19147 to store in memory a datum indicated by @var{type}.
19149 @code{GL_INVALID_OPERATION} is generated if @code{glSeparableFilter2D}
19150 is executed between the execution of @code{glBegin} and the
19151 corresponding execution of @code{glEnd}.
19155 @deftypefun void glShadeModel mode
19156 Select flat or smooth shading.
19160 Specifies a symbolic value representing a shading technique. Accepted
19161 values are @code{GL_FLAT} and @code{GL_SMOOTH}. The initial value is
19166 GL primitives can have either flat or smooth shading. Smooth shading,
19167 the default, causes the computed colors of vertices to be interpolated
19168 as the primitive is rasterized, typically assigning different colors to
19169 each resulting pixel fragment. Flat shading selects the computed color
19170 of just one vertex and assigns it to all the pixel fragments generated
19171 by rasterizing a single primitive. In either case, the computed color
19172 of a vertex is the result of lighting if lighting is enabled, or it is
19173 the current color at the time the vertex was specified if lighting is
19176 Flat and smooth shading are indistinguishable for points. Starting when
19177 @code{glBegin} is issued and counting vertices and primitives from 1,
19178 the GL gives each flat-shaded line segment @r{@var{i}} the computed
19179 color of vertex @r{@var{i}+1}, its second vertex. Counting similarly
19180 from 1, the GL gives each flat-shaded polygon the computed color of the
19181 vertex listed in the following table. This is the last vertex to
19182 specify the polygon in all cases except single polygons, where the first
19183 vertex specifies the flat-shaded color.
19189 Primitive Type of Polygon @r{@var{i}}}
19206 Independent triangle
19219 Flat and smooth shading are specified by @code{glShadeModel} with
19220 @var{mode} set to @code{GL_FLAT} and @code{GL_SMOOTH}, respectively.
19222 @code{GL_INVALID_ENUM} is generated if @var{mode} is any value other
19223 than @code{GL_FLAT} or @code{GL_SMOOTH}.
19225 @code{GL_INVALID_OPERATION} is generated if @code{glShadeModel} is
19226 executed between the execution of @code{glBegin} and the corresponding
19227 execution of @code{glEnd}.
19231 @deftypefun void glShaderSource shader count string length
19232 Replaces the source code in a shader object.
19236 Specifies the handle of the shader object whose source code is to be
19240 Specifies the number of elements in the @var{string} and @var{length}
19244 Specifies an array of pointers to strings containing the source code to
19245 be loaded into the shader.
19248 Specifies an array of string lengths.
19252 @code{glShaderSource} sets the source code in @var{shader} to the source
19253 code in the array of strings specified by @var{string}. Any source code
19254 previously stored in the shader object is completely replaced. The
19255 number of strings in the array is specified by @var{count}. If
19256 @var{length} is @code{NULL}, each string is assumed to be null
19257 terminated. If @var{length} is a value other than @code{NULL}, it
19258 points to an array containing a string length for each of the
19259 corresponding elements of @var{string}. Each element in the
19260 @var{length} array may contain the length of the corresponding string
19261 (the null character is not counted as part of the string length) or a
19262 value less than 0 to indicate that the string is null terminated. The
19263 source code strings are not scanned or parsed at this time; they are
19264 simply copied into the specified shader object.
19266 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
19267 generated by OpenGL.
19269 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
19272 @code{GL_INVALID_VALUE} is generated if @var{count} is less than 0.
19274 @code{GL_INVALID_OPERATION} is generated if @code{glShaderSource} is
19275 executed between the execution of @code{glBegin} and the corresponding
19276 execution of @code{glEnd}.
19280 @deftypefun void glStencilFuncSeparate face func ref mask
19281 Set front and/or back function and reference value for stencil testing.
19285 Specifies whether front and/or back stencil state is updated. Three
19286 symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and
19287 @code{GL_FRONT_AND_BACK}.
19290 Specifies the test function. Eight symbolic constants are valid:
19291 @code{GL_NEVER}, @code{GL_LESS}, @code{GL_LEQUAL}, @code{GL_GREATER},
19292 @code{GL_GEQUAL}, @code{GL_EQUAL}, @code{GL_NOTEQUAL}, and
19293 @code{GL_ALWAYS}. The initial value is @code{GL_ALWAYS}.
19296 Specifies the reference value for the stencil test. @var{ref} is
19297 clamped to the range @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the
19298 number of bitplanes in the stencil buffer. The initial value is 0.
19301 Specifies a mask that is ANDed with both the reference value and the
19302 stored stencil value when the test is done. The initial value is all
19307 Stenciling, like depth-buffering, enables and disables drawing on a
19308 per-pixel basis. You draw into the stencil planes using GL drawing
19309 primitives, then render geometry and images, using the stencil planes to
19310 mask out portions of the screen. Stenciling is typically used in
19311 multipass rendering algorithms to achieve special effects, such as
19312 decals, outlining, and constructive solid geometry rendering.
19314 The stencil test conditionally eliminates a pixel based on the outcome
19315 of a comparison between the reference value and the value in the stencil
19316 buffer. To enable and disable the test, call @code{glEnable} and
19317 @code{glDisable} with argument @code{GL_STENCIL_TEST}. To specify
19318 actions based on the outcome of the stencil test, call
19319 @code{glStencilOp} or @code{glStencilOpSeparate}.
19321 There can be two separate sets of @var{func}, @var{ref}, and @var{mask}
19322 parameters; one affects back-facing polygons, and the other affects
19323 front-facing polygons as well as other non-polygon primitives.
19324 @code{glStencilFunc} sets both front and back stencil state to the same
19325 values, as if @code{glStencilFuncSeparate} were called with @var{face}
19326 set to @code{GL_FRONT_AND_BACK}.
19328 @var{func} is a symbolic constant that determines the stencil comparison
19329 function. It accepts one of eight values, shown in the following list.
19330 @var{ref} is an integer reference value that is used in the stencil
19331 comparison. It is clamped to the range @r{[0,2^@var{n}-1]}, where
19332 @r{@var{n}} is the number of bitplanes in the stencil buffer. @var{mask}
19333 is bitwise ANDed with both the reference value and the stored stencil
19334 value, with the ANDed values participating in the comparison.
19336 If @var{stencil} represents the value stored in the corresponding
19337 stencil buffer location, the following list shows the effect of each
19338 comparison function that can be specified by @var{func}. Only if the
19339 comparison succeeds is the pixel passed through to the next stage in the
19340 rasterization process (see @code{glStencilOp}). All tests treat
19341 @var{stencil} values as unsigned integers in the range
19342 @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of bitplanes in the
19345 The following values are accepted by @var{func}:
19348 @item @code{GL_NEVER}
19351 @item @code{GL_LESS}
19352 Passes if ( @var{ref} & @var{mask} ) < ( @var{stencil} & @var{mask} ).
19354 @item @code{GL_LEQUAL}
19355 Passes if ( @var{ref} & @var{mask} ) <= ( @var{stencil} & @var{mask} ).
19357 @item @code{GL_GREATER}
19358 Passes if ( @var{ref} & @var{mask} ) > ( @var{stencil} & @var{mask} ).
19360 @item @code{GL_GEQUAL}
19361 Passes if ( @var{ref} & @var{mask} ) >= ( @var{stencil} & @var{mask} ).
19363 @item @code{GL_EQUAL}
19364 Passes if ( @var{ref} & @var{mask} ) = ( @var{stencil} & @var{mask} ).
19366 @item @code{GL_NOTEQUAL}
19367 Passes if ( @var{ref} & @var{mask} ) != ( @var{stencil} & @var{mask} ).
19369 @item @code{GL_ALWAYS}
19374 @code{GL_INVALID_ENUM} is generated if @var{func} is not one of the
19375 eight accepted values.
19377 @code{GL_INVALID_OPERATION} is generated if @code{glStencilFuncSeparate}
19378 is executed between the execution of @code{glBegin} and the
19379 corresponding execution of @code{glEnd}.
19383 @deftypefun void glStencilFunc func ref mask
19384 Set front and back function and reference value for stencil testing.
19388 Specifies the test function. Eight symbolic constants are valid:
19389 @code{GL_NEVER}, @code{GL_LESS}, @code{GL_LEQUAL}, @code{GL_GREATER},
19390 @code{GL_GEQUAL}, @code{GL_EQUAL}, @code{GL_NOTEQUAL}, and
19391 @code{GL_ALWAYS}. The initial value is @code{GL_ALWAYS}.
19394 Specifies the reference value for the stencil test. @var{ref} is
19395 clamped to the range @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the
19396 number of bitplanes in the stencil buffer. The initial value is 0.
19399 Specifies a mask that is ANDed with both the reference value and the
19400 stored stencil value when the test is done. The initial value is all
19405 Stenciling, like depth-buffering, enables and disables drawing on a
19406 per-pixel basis. Stencil planes are first drawn into using GL drawing
19407 primitives, then geometry and images are rendered using the stencil
19408 planes to mask out portions of the screen. Stenciling is typically used
19409 in multipass rendering algorithms to achieve special effects, such as
19410 decals, outlining, and constructive solid geometry rendering.
19412 The stencil test conditionally eliminates a pixel based on the outcome
19413 of a comparison between the reference value and the value in the stencil
19414 buffer. To enable and disable the test, call @code{glEnable} and
19415 @code{glDisable} with argument @code{GL_STENCIL_TEST}. To specify
19416 actions based on the outcome of the stencil test, call
19417 @code{glStencilOp} or @code{glStencilOpSeparate}.
19419 There can be two separate sets of @var{func}, @var{ref}, and @var{mask}
19420 parameters; one affects back-facing polygons, and the other affects
19421 front-facing polygons as well as other non-polygon primitives.
19422 @code{glStencilFunc} sets both front and back stencil state to the same
19423 values. Use @code{glStencilFuncSeparate} to set front and back stencil
19424 state to different values.
19426 @var{func} is a symbolic constant that determines the stencil comparison
19427 function. It accepts one of eight values, shown in the following list.
19428 @var{ref} is an integer reference value that is used in the stencil
19429 comparison. It is clamped to the range @r{[0,2^@var{n}-1]}, where
19430 @r{@var{n}} is the number of bitplanes in the stencil buffer. @var{mask}
19431 is bitwise ANDed with both the reference value and the stored stencil
19432 value, with the ANDed values participating in the comparison.
19434 If @var{stencil} represents the value stored in the corresponding
19435 stencil buffer location, the following list shows the effect of each
19436 comparison function that can be specified by @var{func}. Only if the
19437 comparison succeeds is the pixel passed through to the next stage in the
19438 rasterization process (see @code{glStencilOp}). All tests treat
19439 @var{stencil} values as unsigned integers in the range
19440 @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of bitplanes in the
19443 The following values are accepted by @var{func}:
19446 @item @code{GL_NEVER}
19449 @item @code{GL_LESS}
19450 Passes if ( @var{ref} & @var{mask} ) < ( @var{stencil} & @var{mask} ).
19452 @item @code{GL_LEQUAL}
19453 Passes if ( @var{ref} & @var{mask} ) <= ( @var{stencil} & @var{mask} ).
19455 @item @code{GL_GREATER}
19456 Passes if ( @var{ref} & @var{mask} ) > ( @var{stencil} & @var{mask} ).
19458 @item @code{GL_GEQUAL}
19459 Passes if ( @var{ref} & @var{mask} ) >= ( @var{stencil} & @var{mask} ).
19461 @item @code{GL_EQUAL}
19462 Passes if ( @var{ref} & @var{mask} ) = ( @var{stencil} & @var{mask} ).
19464 @item @code{GL_NOTEQUAL}
19465 Passes if ( @var{ref} & @var{mask} ) != ( @var{stencil} & @var{mask} ).
19467 @item @code{GL_ALWAYS}
19472 @code{GL_INVALID_ENUM} is generated if @var{func} is not one of the
19473 eight accepted values.
19475 @code{GL_INVALID_OPERATION} is generated if @code{glStencilFunc} is
19476 executed between the execution of @code{glBegin} and the corresponding
19477 execution of @code{glEnd}.
19481 @deftypefun void glStencilMaskSeparate face mask
19482 Control the front and/or back writing of individual bits in the stencil
19487 Specifies whether the front and/or back stencil writemask is updated.
19488 Three symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and
19489 @code{GL_FRONT_AND_BACK}.
19492 Specifies a bit mask to enable and disable writing of individual bits in
19493 the stencil planes. Initially, the mask is all 1's.
19497 @code{glStencilMaskSeparate} controls the writing of individual bits in
19498 the stencil planes. The least significant @r{@var{n}} bits of
19499 @var{mask}, where @r{@var{n}} is the number of bits in the stencil
19500 buffer, specify a mask. Where a 1 appears in the mask, it's possible to
19501 write to the corresponding bit in the stencil buffer. Where a 0
19502 appears, the corresponding bit is write-protected. Initially, all bits
19503 are enabled for writing.
19505 There can be two separate @var{mask} writemasks; one affects back-facing
19506 polygons, and the other affects front-facing polygons as well as other
19507 non-polygon primitives. @code{glStencilMask} sets both front and back
19508 stencil writemasks to the same values, as if
19509 @code{glStencilMaskSeparate} were called with @var{face} set to
19510 @code{GL_FRONT_AND_BACK}.
19512 @code{GL_INVALID_OPERATION} is generated if @code{glStencilMaskSeparate}
19513 is executed between the execution of @code{glBegin} and the
19514 corresponding execution of @code{glEnd}.
19518 @deftypefun void glStencilMask mask
19519 Control the front and back writing of individual bits in the stencil
19524 Specifies a bit mask to enable and disable writing of individual bits in
19525 the stencil planes. Initially, the mask is all 1's.
19529 @code{glStencilMask} controls the writing of individual bits in the
19530 stencil planes. The least significant @r{@var{n}} bits of @var{mask},
19531 where @r{@var{n}} is the number of bits in the stencil buffer, specify a
19532 mask. Where a 1 appears in the mask, it's possible to write to the
19533 corresponding bit in the stencil buffer. Where a 0 appears, the
19534 corresponding bit is write-protected. Initially, all bits are enabled
19537 There can be two separate @var{mask} writemasks; one affects back-facing
19538 polygons, and the other affects front-facing polygons as well as other
19539 non-polygon primitives. @code{glStencilMask} sets both front and back
19540 stencil writemasks to the same values. Use @code{glStencilMaskSeparate}
19541 to set front and back stencil writemasks to different values.
19543 @code{GL_INVALID_OPERATION} is generated if @code{glStencilMask} is
19544 executed between the execution of @code{glBegin} and the corresponding
19545 execution of @code{glEnd}.
19549 @deftypefun void glStencilOpSeparate face sfail dpfail dppass
19550 Set front and/or back stencil test actions.
19554 Specifies whether front and/or back stencil state is updated. Three
19555 symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and
19556 @code{GL_FRONT_AND_BACK}.
19559 Specifies the action to take when the stencil test fails. Eight
19560 symbolic constants are accepted: @code{GL_KEEP}, @code{GL_ZERO},
19561 @code{GL_REPLACE}, @code{GL_INCR}, @code{GL_INCR_WRAP}, @code{GL_DECR},
19562 @code{GL_DECR_WRAP}, and @code{GL_INVERT}. The initial value is
19566 Specifies the stencil action when the stencil test passes, but the depth
19567 test fails. @var{dpfail} accepts the same symbolic constants as
19568 @var{sfail}. The initial value is @code{GL_KEEP}.
19571 Specifies the stencil action when both the stencil test and the depth
19572 test pass, or when the stencil test passes and either there is no depth
19573 buffer or depth testing is not enabled. @var{dppass} accepts the same
19574 symbolic constants as @var{sfail}. The initial value is @code{GL_KEEP}.
19578 Stenciling, like depth-buffering, enables and disables drawing on a
19579 per-pixel basis. You draw into the stencil planes using GL drawing
19580 primitives, then render geometry and images, using the stencil planes to
19581 mask out portions of the screen. Stenciling is typically used in
19582 multipass rendering algorithms to achieve special effects, such as
19583 decals, outlining, and constructive solid geometry rendering.
19585 The stencil test conditionally eliminates a pixel based on the outcome
19586 of a comparison between the value in the stencil buffer and a reference
19587 value. To enable and disable the test, call @code{glEnable} and
19588 @code{glDisable} with argument @code{GL_STENCIL_TEST}; to control it,
19589 call @code{glStencilFunc} or @code{glStencilFuncSeparate}.
19591 There can be two separate sets of @var{sfail}, @var{dpfail}, and
19592 @var{dppass} parameters; one affects back-facing polygons, and the other
19593 affects front-facing polygons as well as other non-polygon primitives.
19594 @code{glStencilOp} sets both front and back stencil state to the same
19595 values, as if @code{glStencilOpSeparate} were called with @var{face} set
19596 to @code{GL_FRONT_AND_BACK}.
19598 @code{glStencilOpSeparate} takes three arguments that indicate what
19599 happens to the stored stencil value while stenciling is enabled. If the
19600 stencil test fails, no change is made to the pixel's color or depth
19601 buffers, and @var{sfail} specifies what happens to the stencil buffer
19602 contents. The following eight actions are possible.
19605 @item @code{GL_KEEP}
19606 Keeps the current value.
19608 @item @code{GL_ZERO}
19609 Sets the stencil buffer value to 0.
19611 @item @code{GL_REPLACE}
19612 Sets the stencil buffer value to @var{ref}, as specified by
19613 @code{glStencilFunc}.
19615 @item @code{GL_INCR}
19616 Increments the current stencil buffer value. Clamps to the maximum
19617 representable unsigned value.
19619 @item @code{GL_INCR_WRAP}
19620 Increments the current stencil buffer value. Wraps stencil buffer value
19621 to zero when incrementing the maximum representable unsigned value.
19623 @item @code{GL_DECR}
19624 Decrements the current stencil buffer value. Clamps to 0.
19626 @item @code{GL_DECR_WRAP}
19627 Decrements the current stencil buffer value. Wraps stencil buffer value
19628 to the maximum representable unsigned value when decrementing a stencil
19629 buffer value of zero.
19631 @item @code{GL_INVERT}
19632 Bitwise inverts the current stencil buffer value.
19636 Stencil buffer values are treated as unsigned integers. When
19637 incremented and decremented, values are clamped to 0 and
19638 @r{2^@var{n}-1}, where @r{@var{n}} is the value returned by querying
19639 @code{GL_STENCIL_BITS}.
19641 The other two arguments to @code{glStencilOpSeparate} specify stencil
19642 buffer actions that depend on whether subsequent depth buffer tests
19643 succeed (@var{dppass}) or fail (@var{dpfail}) (see @code{glDepthFunc}).
19644 The actions are specified using the same eight symbolic constants as
19645 @var{sfail}. Note that @var{dpfail} is ignored when there is no depth
19646 buffer, or when the depth buffer is not enabled. In these cases,
19647 @var{sfail} and @var{dppass} specify stencil action when the stencil
19648 test fails and passes, respectively.
19650 @code{GL_INVALID_ENUM} is generated if @var{face} is any value other
19651 than @code{GL_FRONT}, @code{GL_BACK}, or @code{GL_FRONT_AND_BACK}.
19653 @code{GL_INVALID_ENUM} is generated if @var{sfail}, @var{dpfail}, or
19654 @var{dppass} is any value other than the eight defined constant values.
19656 @code{GL_INVALID_OPERATION} is generated if @code{glStencilOpSeparate}
19657 is executed between the execution of @code{glBegin} and the
19658 corresponding execution of @code{glEnd}.
19662 @deftypefun void glStencilOp sfail dpfail dppass
19663 Set front and back stencil test actions.
19667 Specifies the action to take when the stencil test fails. Eight
19668 symbolic constants are accepted: @code{GL_KEEP}, @code{GL_ZERO},
19669 @code{GL_REPLACE}, @code{GL_INCR}, @code{GL_INCR_WRAP}, @code{GL_DECR},
19670 @code{GL_DECR_WRAP}, and @code{GL_INVERT}. The initial value is
19674 Specifies the stencil action when the stencil test passes, but the depth
19675 test fails. @var{dpfail} accepts the same symbolic constants as
19676 @var{sfail}. The initial value is @code{GL_KEEP}.
19679 Specifies the stencil action when both the stencil test and the depth
19680 test pass, or when the stencil test passes and either there is no depth
19681 buffer or depth testing is not enabled. @var{dppass} accepts the same
19682 symbolic constants as @var{sfail}. The initial value is @code{GL_KEEP}.
19686 Stenciling, like depth-buffering, enables and disables drawing on a
19687 per-pixel basis. You draw into the stencil planes using GL drawing
19688 primitives, then render geometry and images, using the stencil planes to
19689 mask out portions of the screen. Stenciling is typically used in
19690 multipass rendering algorithms to achieve special effects, such as
19691 decals, outlining, and constructive solid geometry rendering.
19693 The stencil test conditionally eliminates a pixel based on the outcome
19694 of a comparison between the value in the stencil buffer and a reference
19695 value. To enable and disable the test, call @code{glEnable} and
19696 @code{glDisable} with argument @code{GL_STENCIL_TEST}; to control it,
19697 call @code{glStencilFunc} or @code{glStencilFuncSeparate}.
19699 There can be two separate sets of @var{sfail}, @var{dpfail}, and
19700 @var{dppass} parameters; one affects back-facing polygons, and the other
19701 affects front-facing polygons as well as other non-polygon primitives.
19702 @code{glStencilOp} sets both front and back stencil state to the same
19703 values. Use @code{glStencilOpSeparate} to set front and back stencil
19704 state to different values.
19706 @code{glStencilOp} takes three arguments that indicate what happens to
19707 the stored stencil value while stenciling is enabled. If the stencil
19708 test fails, no change is made to the pixel's color or depth buffers, and
19709 @var{sfail} specifies what happens to the stencil buffer contents. The
19710 following eight actions are possible.
19713 @item @code{GL_KEEP}
19714 Keeps the current value.
19716 @item @code{GL_ZERO}
19717 Sets the stencil buffer value to 0.
19719 @item @code{GL_REPLACE}
19720 Sets the stencil buffer value to @var{ref}, as specified by
19721 @code{glStencilFunc}.
19723 @item @code{GL_INCR}
19724 Increments the current stencil buffer value. Clamps to the maximum
19725 representable unsigned value.
19727 @item @code{GL_INCR_WRAP}
19728 Increments the current stencil buffer value. Wraps stencil buffer value
19729 to zero when incrementing the maximum representable unsigned value.
19731 @item @code{GL_DECR}
19732 Decrements the current stencil buffer value. Clamps to 0.
19734 @item @code{GL_DECR_WRAP}
19735 Decrements the current stencil buffer value. Wraps stencil buffer value
19736 to the maximum representable unsigned value when decrementing a stencil
19737 buffer value of zero.
19739 @item @code{GL_INVERT}
19740 Bitwise inverts the current stencil buffer value.
19744 Stencil buffer values are treated as unsigned integers. When
19745 incremented and decremented, values are clamped to 0 and
19746 @r{2^@var{n}-1}, where @r{@var{n}} is the value returned by querying
19747 @code{GL_STENCIL_BITS}.
19749 The other two arguments to @code{glStencilOp} specify stencil buffer
19750 actions that depend on whether subsequent depth buffer tests succeed
19751 (@var{dppass}) or fail (@var{dpfail}) (see @code{glDepthFunc}). The
19752 actions are specified using the same eight symbolic constants as
19753 @var{sfail}. Note that @var{dpfail} is ignored when there is no depth
19754 buffer, or when the depth buffer is not enabled. In these cases,
19755 @var{sfail} and @var{dppass} specify stencil action when the stencil
19756 test fails and passes, respectively.
19758 @code{GL_INVALID_ENUM} is generated if @var{sfail}, @var{dpfail}, or
19759 @var{dppass} is any value other than the eight defined constant values.
19761 @code{GL_INVALID_OPERATION} is generated if @code{glStencilOp} is
19762 executed between the execution of @code{glBegin} and the corresponding
19763 execution of @code{glEnd}.
19767 @deftypefun void glTexCoordPointer size type stride pointer
19768 Define an array of texture coordinates.
19772 Specifies the number of coordinates per array element. Must be 1, 2, 3,
19773 or 4. The initial value is 4.
19776 Specifies the data type of each texture coordinate. Symbolic constants
19777 @code{GL_SHORT}, @code{GL_INT}, @code{GL_FLOAT}, or @code{GL_DOUBLE} are
19778 accepted. The initial value is @code{GL_FLOAT}.
19781 Specifies the byte offset between consecutive texture coordinate sets.
19782 If @var{stride} is 0, the array elements are understood to be tightly
19783 packed. The initial value is 0.
19785 @item @var{pointer}
19786 Specifies a pointer to the first coordinate of the first texture
19787 coordinate set in the array. The initial value is 0.
19791 @code{glTexCoordPointer} specifies the location and data format of an
19792 array of texture coordinates to use when rendering. @var{size}
19793 specifies the number of coordinates per texture coordinate set, and must
19794 be 1, 2, 3, or 4. @var{type} specifies the data type of each texture
19795 coordinate, and @var{stride} specifies the byte stride from one texture
19796 coordinate set to the next, allowing vertices and attributes to be
19797 packed into a single array or stored in separate arrays. (Single-array
19798 storage may be more efficient on some implementations; see
19799 @code{glInterleavedArrays}.)
19801 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
19802 target (see @code{glBindBuffer}) while a texture coordinate array is
19803 specified, @var{pointer} is treated as a byte offset into the buffer
19804 object's data store. Also, the buffer object binding
19805 (@code{GL_ARRAY_BUFFER_BINDING}) is saved as texture coordinate vertex
19806 array client-side state (@code{GL_TEXTURE_COORD_ARRAY_BUFFER_BINDING}).
19808 When a texture coordinate array is specified, @var{size}, @var{type},
19809 @var{stride}, and @var{pointer} are saved as client-side state, in
19810 addition to the current vertex array buffer object binding.
19812 To enable and disable a texture coordinate array, call
19813 @code{glEnableClientState} and @code{glDisableClientState} with the
19814 argument @code{GL_TEXTURE_COORD_ARRAY}. If enabled, the texture
19815 coordinate array is used when @code{glArrayElement},
19816 @code{glDrawArrays}, @code{glMultiDrawArrays}, @code{glDrawElements},
19817 @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called.
19819 @code{GL_INVALID_VALUE} is generated if @var{size} is not 1, 2, 3, or 4.
19821 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
19824 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
19828 @deftypefun void glTexCoord1s s
19829 @deftypefunx void glTexCoord1i s
19830 @deftypefunx void glTexCoord1f s
19831 @deftypefunx void glTexCoord1d s
19832 @deftypefunx void glTexCoord2s s t
19833 @deftypefunx void glTexCoord2i s t
19834 @deftypefunx void glTexCoord2f s t
19835 @deftypefunx void glTexCoord2d s t
19836 @deftypefunx void glTexCoord3s s t r
19837 @deftypefunx void glTexCoord3i s t r
19838 @deftypefunx void glTexCoord3f s t r
19839 @deftypefunx void glTexCoord3d s t r
19840 @deftypefunx void glTexCoord4s s t r q
19841 @deftypefunx void glTexCoord4i s t r q
19842 @deftypefunx void glTexCoord4f s t r q
19843 @deftypefunx void glTexCoord4d s t r q
19844 @deftypefunx void glTexCoord1sv v
19845 @deftypefunx void glTexCoord1iv v
19846 @deftypefunx void glTexCoord1fv v
19847 @deftypefunx void glTexCoord1dv v
19848 @deftypefunx void glTexCoord2sv v
19849 @deftypefunx void glTexCoord2iv v
19850 @deftypefunx void glTexCoord2fv v
19851 @deftypefunx void glTexCoord2dv v
19852 @deftypefunx void glTexCoord3sv v
19853 @deftypefunx void glTexCoord3iv v
19854 @deftypefunx void glTexCoord3fv v
19855 @deftypefunx void glTexCoord3dv v
19856 @deftypefunx void glTexCoord4sv v
19857 @deftypefunx void glTexCoord4iv v
19858 @deftypefunx void glTexCoord4fv v
19859 @deftypefunx void glTexCoord4dv v
19860 Set the current texture coordinates.
19867 Specify @var{s}, @var{t}, @var{r}, and @var{q} texture coordinates. Not
19868 all parameters are present in all forms of the command.
19872 @code{glTexCoord} specifies texture coordinates in one, two, three, or
19873 four dimensions. @code{glTexCoord1} sets the current texture
19874 coordinates to @r{(@var{s},001)}; a call to @code{glTexCoord2} sets them
19875 to @r{(@var{s},@var{t}01)}. Similarly, @code{glTexCoord3} specifies the
19876 texture coordinates as @r{(@var{s},@var{t}@var{r}1)}, and
19877 @code{glTexCoord4} defines all four components explicitly as
19878 @r{(@var{s},@var{t}@var{r}@var{q})}.
19880 The current texture coordinates are part of the data that is associated
19881 with each vertex and with the current raster position. Initially, the
19882 values for @var{s}, @var{t}, @var{r}, and @var{q} are (0, 0, 0, 1).
19888 @deftypefun void glTexEnvf target pname param
19889 @deftypefunx void glTexEnvi target pname param
19890 @deftypefunx void glTexEnvfv target pname params
19891 @deftypefunx void glTexEnviv target pname params
19892 Set texture environment parameters.
19896 Specifies a texture environment. May be @code{GL_TEXTURE_ENV},
19897 @code{GL_TEXTURE_FILTER_CONTROL} or @code{GL_POINT_SPRITE}.
19900 Specifies the symbolic name of a single-valued texture environment
19901 parameter. May be either @code{GL_TEXTURE_ENV_MODE},
19902 @code{GL_TEXTURE_LOD_BIAS}, @code{GL_COMBINE_RGB},
19903 @code{GL_COMBINE_ALPHA}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB},
19904 @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA},
19905 @code{GL_SRC2_ALPHA}, @code{GL_OPERAND0_RGB}, @code{GL_OPERAND1_RGB},
19906 @code{GL_OPERAND2_RGB}, @code{GL_OPERAND0_ALPHA},
19907 @code{GL_OPERAND1_ALPHA}, @code{GL_OPERAND2_ALPHA}, @code{GL_RGB_SCALE},
19908 @code{GL_ALPHA_SCALE}, or @code{GL_COORD_REPLACE}.
19911 Specifies a single symbolic constant, one of @code{GL_ADD},
19912 @code{GL_ADD_SIGNED}, @code{GL_INTERPOLATE}, @code{GL_MODULATE},
19913 @code{GL_DECAL}, @code{GL_BLEND}, @code{GL_REPLACE}, @code{GL_SUBTRACT},
19914 @code{GL_COMBINE}, @code{GL_TEXTURE}, @code{GL_CONSTANT},
19915 @code{GL_PRIMARY_COLOR}, @code{GL_PREVIOUS}, @code{GL_SRC_COLOR},
19916 @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_SRC_ALPHA},
19917 @code{GL_ONE_MINUS_SRC_ALPHA}, a single boolean value for the point
19918 sprite texture coordinate replacement, a single floating-point value for
19919 the texture level-of-detail bias, or 1.0, 2.0, or 4.0 when specifying
19920 the @code{GL_RGB_SCALE} or @code{GL_ALPHA_SCALE}.
19924 A texture environment specifies how texture values are interpreted when
19925 a fragment is textured. When @var{target} is
19926 @code{GL_TEXTURE_FILTER_CONTROL}, @var{pname} must be
19927 @code{GL_TEXTURE_LOD_BIAS}. When @var{target} is @code{GL_TEXTURE_ENV},
19928 @var{pname} can be @code{GL_TEXTURE_ENV_MODE},
19929 @code{GL_TEXTURE_ENV_COLOR}, @code{GL_COMBINE_RGB},
19930 @code{GL_COMBINE_ALPHA}, @code{GL_RGB_SCALE}, @code{GL_ALPHA_SCALE},
19931 @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, @code{GL_SRC2_RGB},
19932 @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, or @code{GL_SRC2_ALPHA}.
19934 If @var{pname} is @code{GL_TEXTURE_ENV_MODE}, then @var{params} is (or
19935 points to) the symbolic name of a texture function. Six texture
19936 functions may be specified: @code{GL_ADD}, @code{GL_MODULATE},
19937 @code{GL_DECAL}, @code{GL_BLEND}, @code{GL_REPLACE}, or
19940 The following table shows the correspondence of filtered texture values
19941 @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}},
19942 @r{@var{A}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{I}_@var{t}} to texture
19943 source components. @r{@var{C}_@var{s}} and @r{@var{A}_@var{s}} are used
19944 by the texture functions described below.
19950 Texture Base Internal Format
19951 @r{@code{C}_@var{s}}, @r{@code{A}_@var{s}}
19953 @item @code{GL_ALPHA}
19954 (0, 0, 0) , @r{@var{A}_@var{t}}
19956 @item @code{GL_LUMINANCE}
19957 ( @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}} ) , 1
19959 @item @code{GL_LUMINANCE_ALPHA}
19960 ( @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}} ) ,
19961 @r{@var{A}_@var{t}}
19963 @item @code{GL_INTENSITY}
19964 ( @r{@var{I}_@var{t}}, @r{@var{I}_@var{t}}, @r{@var{I}_@var{t}} ) ,
19965 @r{@var{I}_@var{t}}
19967 @item @code{GL_RGB}
19968 ( @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}} ) , 1
19970 @item @code{GL_RGBA}
19971 ( @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}} ) ,
19972 @r{@var{A}_@var{t}}
19976 A texture function acts on the fragment to be textured using the texture
19977 image value that applies to the fragment (see @code{glTexParameter}) and
19978 produces an RGBA color for that fragment. The following table shows how
19979 the RGBA color is produced for each of the first five texture functions
19980 that can be chosen. @r{@var{C}} is a triple of color values (RGB) and
19981 @r{@var{A}} is the associated alpha value. RGBA values extracted from a
19982 texture image are in the range [0,1]. The subscript @r{@var{p}} refers
19983 to the color computed from the previous texture stage (or the incoming
19984 fragment if processing texture stage 0), the subscript @r{@var{s}} to
19985 the texture source color, the subscript @r{@var{c}} to the texture
19986 environment color, and the subscript @r{@var{v}} indicates a value
19987 produced by the texture function.
19993 Texture Base Internal Format
19994 @code{Value}, @code{GL_REPLACE} Function , @code{GL_MODULATE} Function ,
19995 @code{GL_DECAL} Function , @code{GL_BLEND} Function , @code{GL_ADD}
19998 @item @code{GL_ALPHA}
19999 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{p}}, @r{@var{C}_@var{p}},
20000 undefined , @r{@var{C}_@var{p}}, @r{@var{C}_@var{p}}
20003 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}},
20004 @r{@var{A}_@var{p}@var{A}_@var{s}}, ,
20005 @r{@var{A}_@var{v}=@var{A}_@var{p}@var{A}_@var{s}},
20006 @r{@var{A}_@var{p}@var{A}_@var{s}}
20008 @item @code{GL_LUMINANCE}
20009 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
20010 @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined ,
20011 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
20012 @r{@var{C}_@var{p}+@var{C}_@var{s}}
20016 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, ,
20017 @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}
20019 @item @code{GL_LUMINANCE_ALPHA}
20020 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
20021 @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined ,
20022 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
20023 @r{@var{C}_@var{p}+@var{C}_@var{s}}
20027 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}},
20028 @r{@var{A}_@var{p}@var{A}_@var{s}}, ,
20029 @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}@var{A}_@var{s}}
20031 @item @code{GL_INTENSITY}
20032 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
20033 @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined ,
20034 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
20035 @r{@var{C}_@var{p}+@var{C}_@var{s}}
20038 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}},
20039 @r{@var{A}_@var{p}@var{A}_@var{s}}, ,
20040 @r{@var{A}_@var{p}(1-@var{A}_@var{s},)+@var{A}_@var{c}@var{A}_@var{s}},
20041 @r{@var{A}_@var{p}+@var{A}_@var{s}}
20043 @item @code{GL_RGB}
20044 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
20045 @r{@var{C}_@var{p}@var{C}_@var{s}}, @r{@var{C}_@var{s}},
20046 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
20047 @r{@var{C}_@var{p}+@var{C}_@var{s}}
20051 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}},
20052 @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}
20054 @item @code{GL_RGBA}
20055 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
20056 @r{@var{C}_@var{p}@var{C}_@var{s}},
20057 @r{@var{C}_@var{p}(1-@var{A}_@var{s},)+@var{C}_@var{s}@var{A}_@var{s}},
20058 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
20059 @r{@var{C}_@var{p}+@var{C}_@var{s}}
20063 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}},
20064 @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}},
20065 @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}@var{A}_@var{s}}
20069 If @var{pname} is @code{GL_TEXTURE_ENV_MODE}, and @var{params} is
20070 @code{GL_COMBINE}, the form of the texture function depends on the
20071 values of @code{GL_COMBINE_RGB} and @code{GL_COMBINE_ALPHA}.
20073 The following describes how the texture sources, as specified by
20074 @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, @code{GL_SRC2_RGB},
20075 @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, and @code{GL_SRC2_ALPHA},
20076 are combined to produce a final texture color. In the following tables,
20077 @code{GL_SRC0_c} is represented by @r{@var{Arg0}}, @code{GL_SRC1_c} is
20078 represented by @r{@var{Arg1}}, and @code{GL_SRC2_c} is represented by
20081 @code{GL_COMBINE_RGB} accepts any of @code{GL_REPLACE},
20082 @code{GL_MODULATE}, @code{GL_ADD}, @code{GL_ADD_SIGNED},
20083 @code{GL_INTERPOLATE}, @code{GL_SUBTRACT}, @code{GL_DOT3_RGB}, or
20084 @code{GL_DOT3_RGBA}.
20089 @item @strong{@code{GL_COMBINE_RGB}}
20090 @strong{Texture Function}
20092 @item @code{GL_REPLACE}
20095 @item @code{GL_MODULATE}
20096 @r{@var{Arg0}×@var{Arg1}}
20098 @item @code{GL_ADD}
20099 @r{@var{Arg0}+@var{Arg1}}
20101 @item @code{GL_ADD_SIGNED}
20102 @r{@var{Arg0}+@var{Arg1}-0.5}
20104 @item @code{GL_INTERPOLATE}
20105 @r{@var{Arg0}×@var{Arg2}+@var{Arg1}×(1-@var{Arg2},)}
20107 @item @code{GL_SUBTRACT}
20108 @r{@var{Arg0}-@var{Arg1}}
20110 @item @code{GL_DOT3_RGB}
20111 or @code{GL_DOT3_RGBA}
20112 @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,),),)}
20116 The scalar results for @code{GL_DOT3_RGB} and @code{GL_DOT3_RGBA} are
20117 placed into each of the 3 (RGB) or 4 (RGBA) components on output.
20119 Likewise, @code{GL_COMBINE_ALPHA} accepts any of @code{GL_REPLACE},
20120 @code{GL_MODULATE}, @code{GL_ADD}, @code{GL_ADD_SIGNED},
20121 @code{GL_INTERPOLATE}, or @code{GL_SUBTRACT}. The following table
20122 describes how alpha values are combined:
20127 @item @strong{@code{GL_COMBINE_ALPHA}}
20128 @strong{Texture Function}
20130 @item @code{GL_REPLACE}
20133 @item @code{GL_MODULATE}
20134 @r{@var{Arg0}×@var{Arg1}}
20136 @item @code{GL_ADD}
20137 @r{@var{Arg0}+@var{Arg1}}
20139 @item @code{GL_ADD_SIGNED}
20140 @r{@var{Arg0}+@var{Arg1}-0.5}
20142 @item @code{GL_INTERPOLATE}
20143 @r{@var{Arg0}×@var{Arg2}+@var{Arg1}×(1-@var{Arg2},)}
20145 @item @code{GL_SUBTRACT}
20146 @r{@var{Arg0}-@var{Arg1}}
20150 In the following tables, the value @r{@var{C}_@var{s}} represents the
20151 color sampled from the currently bound texture, @r{@var{C}_@var{c}}
20152 represents the constant texture-environment color, @r{@var{C}_@var{f}}
20153 represents the primary color of the incoming fragment, and
20154 @r{@var{C}_@var{p}} represents the color computed from the previous
20155 texture stage or @r{@var{C}_@var{f}} if processing texture stage 0.
20156 Likewise, @r{@var{A}_@var{s}}, @r{@var{A}_@var{c}}, @r{@var{A}_@var{f}},
20157 and @r{@var{A}_@var{p}} represent the respective alpha values.
20159 The following table describes the values assigned to @r{@var{Arg0}},
20160 @r{@var{Arg1}}, and @r{@var{Arg2}} based upon the RGB sources and
20166 @item @strong{@code{GL_SRCn_RGB}}
20167 @strong{@code{GL_OPERANDn_RGB}}, @strong{Argument Value}
20169 @item @code{GL_TEXTURE}
20170 @code{GL_SRC_COLOR}, @r{@var{C}_@var{s},}
20173 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{s},}
20176 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},}
20179 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},}
20181 @item @code{GL_TEXTUREn}
20182 @code{GL_SRC_COLOR}, @r{@var{C}_@var{s},}
20185 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{s},}
20188 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},}
20191 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},}
20193 @item @code{GL_CONSTANT}
20194 @code{GL_SRC_COLOR}, @r{@var{C}_@var{c},}
20197 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{c},}
20200 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{c},}
20203 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{c},}
20205 @item @code{GL_PRIMARY_COLOR}
20206 @code{GL_SRC_COLOR}, @r{@var{C}_@var{f},}
20209 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{f},}
20212 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{f},}
20215 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{f},}
20217 @item @code{GL_PREVIOUS}
20218 @code{GL_SRC_COLOR}, @r{@var{C}_@var{p},}
20221 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{p},}
20224 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{p},}
20227 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{p},}
20231 For @code{GL_TEXTUREn} sources, @r{@var{C}_@var{s}} and
20232 @r{@var{A}_@var{s}} represent the color and alpha, respectively,
20233 produced from texture stage @r{@var{n}}.
20235 The follow table describes the values assigned to @r{@var{Arg0}},
20236 @r{@var{Arg1}}, and @r{@var{Arg2}} based upon the alpha sources and
20242 @item @strong{@code{GL_SRCn_ALPHA}}
20243 @strong{@code{GL_OPERANDn_ALPHA}}, @strong{Argument Value}
20245 @item @code{GL_TEXTURE}
20246 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},}
20249 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},}
20251 @item @code{GL_TEXTUREn}
20252 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},}
20255 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},}
20257 @item @code{GL_CONSTANT}
20258 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{c},}
20261 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{c},}
20263 @item @code{GL_PRIMARY_COLOR}
20264 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{f},}
20267 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{f},}
20269 @item @code{GL_PREVIOUS}
20270 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{p},}
20273 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{p},}
20277 The RGB and alpha results of the texture function are multipled by the
20278 values of @code{GL_RGB_SCALE} and @code{GL_ALPHA_SCALE}, respectively,
20279 and clamped to the range @r{[0,1]}.
20281 If @var{pname} is @code{GL_TEXTURE_ENV_COLOR}, @var{params} is a pointer
20282 to an array that holds an RGBA color consisting of four values. Integer
20283 color components are interpreted linearly such that the most positive
20284 integer maps to 1.0, and the most negative integer maps to -1.0. The
20285 values are clamped to the range [0,1] when they are specified.
20286 @r{@var{C}_@var{c}} takes these four values.
20288 If @var{pname} is @code{GL_TEXTURE_LOD_BIAS}, the value specified is
20289 added to the texture level-of-detail parameter, that selects which
20290 mipmap, or mipmaps depending upon the selected
20291 @code{GL_TEXTURE_MIN_FILTER}, will be sampled.
20293 @code{GL_TEXTURE_ENV_MODE} defaults to @code{GL_MODULATE} and
20294 @code{GL_TEXTURE_ENV_COLOR} defaults to (0, 0, 0, 0).
20296 If @var{target} is @code{GL_POINT_SPRITE} and @var{pname} is
20297 @code{GL_COORD_REPLACE}, the boolean value specified is used to either
20298 enable or disable point sprite texture coordinate replacement. The
20299 default value is @code{GL_FALSE}.
20301 @code{GL_INVALID_ENUM} is generated when @var{target} or @var{pname} is
20302 not one of the accepted defined values, or when @var{params} should have
20303 a defined constant value (based on the value of @var{pname}) and does
20306 @code{GL_INVALID_VALUE} is generated if the @var{params} value for
20307 @code{GL_RGB_SCALE} or @code{GL_ALPHA_SCALE} are not one of 1.0, 2.0, or
20310 @code{GL_INVALID_OPERATION} is generated if @code{glTexEnv} is executed
20311 between the execution of @code{glBegin} and the corresponding execution
20316 @deftypefun void glTexGeni coord pname param
20317 @deftypefunx void glTexGenf coord pname param
20318 @deftypefunx void glTexGend coord pname param
20319 @deftypefunx void glTexGeniv coord pname params
20320 @deftypefunx void glTexGenfv coord pname params
20321 @deftypefunx void glTexGendv coord pname params
20322 Control the generation of texture coordinates.
20326 Specifies a texture coordinate. Must be one of @code{GL_S},
20327 @code{GL_T}, @code{GL_R}, or @code{GL_Q}.
20330 Specifies the symbolic name of the texture-coordinate generation
20331 function. Must be @code{GL_TEXTURE_GEN_MODE}.
20334 Specifies a single-valued texture generation parameter, one of
20335 @code{GL_OBJECT_LINEAR}, @code{GL_EYE_LINEAR}, @code{GL_SPHERE_MAP},
20336 @code{GL_NORMAL_MAP}, or @code{GL_REFLECTION_MAP}.
20340 @code{glTexGen} selects a texture-coordinate generation function or
20341 supplies coefficients for one of the functions. @var{coord} names one
20342 of the (@var{s}, @var{t}, @var{r}, @var{q}) texture coordinates; it must
20343 be one of the symbols @code{GL_S}, @code{GL_T}, @code{GL_R}, or
20344 @code{GL_Q}. @var{pname} must be one of three symbolic constants:
20345 @code{GL_TEXTURE_GEN_MODE}, @code{GL_OBJECT_PLANE}, or
20346 @code{GL_EYE_PLANE}. If @var{pname} is @code{GL_TEXTURE_GEN_MODE}, then
20347 @var{params} chooses a mode, one of @code{GL_OBJECT_LINEAR},
20348 @code{GL_EYE_LINEAR}, @code{GL_SPHERE_MAP}, @code{GL_NORMAL_MAP}, or
20349 @code{GL_REFLECTION_MAP}. If @var{pname} is either
20350 @code{GL_OBJECT_PLANE} or @code{GL_EYE_PLANE}, @var{params} contains
20351 coefficients for the corresponding texture generation function.
20353 If the texture generation function is @code{GL_OBJECT_LINEAR}, the
20356 @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}}
20358 is used, where @r{@var{g}} is the value computed for the coordinate
20359 named in @var{coord}, @r{@var{p}_1}, @r{@var{p}_2}, @r{@var{p}_3}, and
20360 @r{@var{p}_4} are the four values supplied in @var{params}, and
20361 @r{@var{x}_@var{o}}, @r{@var{y}_@var{o}}, @r{@var{z}_@var{o}}, and
20362 @r{@var{w}_@var{o}} are the object coordinates of the vertex. This
20363 function can be used, for example, to texture-map terrain using sea
20364 level as a reference plane (defined by @r{@var{p}_1}, @r{@var{p}_2},
20365 @r{@var{p}_3}, and @r{@var{p}_4}). The altitude of a terrain vertex is
20366 computed by the @code{GL_OBJECT_LINEAR} coordinate generation function
20367 as its distance from sea level; that altitude can then be used to index
20368 the texture image to map white snow onto peaks and green grass onto
20371 If the texture generation function is @code{GL_EYE_LINEAR}, the function
20373 @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}}
20377 @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}
20379 and @r{@var{x}_@var{e}}, @r{@var{y}_@var{e}}, @r{@var{z}_@var{e}}, and
20380 @r{@var{w}_@var{e}} are the eye coordinates of the vertex,
20381 @r{@var{p}_1}, @r{@var{p}_2}, @r{@var{p}_3}, and @r{@var{p}_4} are the
20382 values supplied in @var{params}, and @r{@var{M}} is the modelview matrix
20383 when @code{glTexGen} is invoked. If @r{@var{M}} is poorly conditioned
20384 or singular, texture coordinates generated by the resulting function may
20385 be inaccurate or undefined.
20387 Note that the values in @var{params} define a reference plane in eye
20388 coordinates. The modelview matrix that is applied to them may not be
20389 the same one in effect when the polygon vertices are transformed. This
20390 function establishes a field of texture coordinates that can produce
20391 dynamic contour lines on moving objects.
20393 If the texture generation function is @code{GL_SPHERE_MAP} and
20394 @var{coord} is either @code{GL_S} or @code{GL_T}, @r{@var{s}} and
20395 @r{@var{t}} texture coordinates are generated as follows. Let @var{u}
20396 be the unit vector pointing from the origin to the polygon vertex (in
20397 eye coordinates). Let @var{n} sup prime be the current normal, after
20398 transformation to eye coordinates. Let
20400 @r{@var{f}=(@var{f}_@var{x}@var{f}_@var{y}@var{f}_@var{z},)^@var{T}}
20401 be the reflection vector such that
20403 @r{@var{f}=@var{u}-2@var{n}^″@var{n}^″,^@var{T}@var{u}}
20406 @r{@var{m}=2√(@var{f}_@var{x},^2+@var{f}_@var{y},^2+(@var{f}_@var{z}+1,)^2,)}.
20407 Then the values assigned to the @r{@var{s}} and @r{@var{t}} texture
20410 @r{@var{s}=@var{f}_@var{x}/@var{m}+1/2}
20412 @r{@var{t}=@var{f}_@var{y}/@var{m}+1/2}
20414 To enable or disable a texture-coordinate generation function, call
20415 @code{glEnable} or @code{glDisable} with one of the symbolic
20416 texture-coordinate names (@code{GL_TEXTURE_GEN_S},
20417 @code{GL_TEXTURE_GEN_T}, @code{GL_TEXTURE_GEN_R}, or
20418 @code{GL_TEXTURE_GEN_Q}) as the argument. When enabled, the specified
20419 texture coordinate is computed according to the generating function
20420 associated with that coordinate. When disabled, subsequent vertices
20421 take the specified texture coordinate from the current set of texture
20422 coordinates. Initially, all texture generation functions are set to
20423 @code{GL_EYE_LINEAR} and are disabled. Both @r{@var{s}} plane equations
20424 are (1, 0, 0, 0), both @r{@var{t}} plane equations are (0, 1, 0, 0), and
20425 all @r{@var{r}} and @r{@var{q}} plane equations are (0, 0, 0, 0).
20427 When the @code{ARB_multitexture} extension is supported, @code{glTexGen}
20428 sets the texture generation parameters for the currently active texture
20429 unit, selected with @code{glActiveTexture}.
20431 @code{GL_INVALID_ENUM} is generated when @var{coord} or @var{pname} is
20432 not an accepted defined value, or when @var{pname} is
20433 @code{GL_TEXTURE_GEN_MODE} and @var{params} is not an accepted defined
20436 @code{GL_INVALID_ENUM} is generated when @var{pname} is
20437 @code{GL_TEXTURE_GEN_MODE}, @var{params} is @code{GL_SPHERE_MAP}, and
20438 @var{coord} is either @code{GL_R} or @code{GL_Q}.
20440 @code{GL_INVALID_OPERATION} is generated if @code{glTexGen} is executed
20441 between the execution of @code{glBegin} and the corresponding execution
20446 @deftypefun void glTexImage1D target level internalFormat width border format type data
20447 Specify a one-dimensional texture image.
20451 Specifies the target texture. Must be @code{GL_TEXTURE_1D} or
20452 @code{GL_PROXY_TEXTURE_1D}.
20455 Specifies the level-of-detail number. Level 0 is the base image level.
20456 Level @var{n} is the @var{n}th mipmap reduction image.
20458 @item @var{internalFormat}
20459 Specifies the number of color components in the texture. Must be 1, 2,
20460 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA},
20461 @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
20462 @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA},
20463 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
20464 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
20465 @code{GL_COMPRESSED_RGBA}, @code{GL_DEPTH_COMPONENT},
20466 @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24},
20467 @code{GL_DEPTH_COMPONENT32}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
20468 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
20469 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
20470 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
20471 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
20472 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY},
20473 @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12},
20474 @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
20475 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
20476 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
20477 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
20478 @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE},
20479 @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
20480 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
20481 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
20484 Specifies the width of the texture image including the border if any. If
20485 the GL version does not support non-power-of-two sizes, this value must
20486 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
20487 implementations support texture images that are at least 64 texels wide.
20488 The height of the 1D texture image is 1.
20491 Specifies the width of the border. Must be either 0 or 1.
20494 Specifies the format of the pixel data. The following symbolic values
20495 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
20496 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
20497 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
20498 @code{GL_LUMINANCE_ALPHA}.
20501 Specifies the data type of the pixel data. The following symbolic
20502 values are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE},
20503 @code{GL_BITMAP}, @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT},
20504 @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT},
20505 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
20506 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
20507 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
20508 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
20509 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
20510 @code{GL_UNSIGNED_INT_10_10_10_2}, and
20511 @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
20514 Specifies a pointer to the image data in memory.
20518 Texturing maps a portion of a specified texture image onto each
20519 graphical primitive for which texturing is enabled. To enable and
20520 disable one-dimensional texturing, call @code{glEnable} and
20521 @code{glDisable} with argument @code{GL_TEXTURE_1D}.
20523 Texture images are defined with @code{glTexImage1D}. The arguments
20524 describe the parameters of the texture image, such as width, width of
20525 the border, level-of-detail number (see @code{glTexParameter}), and the
20526 internal resolution and format used to store the image. The last three
20527 arguments describe how the image is represented in memory; they are
20528 identical to the pixel formats used for @code{glDrawPixels}.
20530 If @var{target} is @code{GL_PROXY_TEXTURE_1D}, no data is read from
20531 @var{data}, but all of the texture image state is recalculated, checked
20532 for consistency, and checked against the implementation's capabilities.
20533 If the implementation cannot handle a texture of the requested texture
20534 size, it sets all of the image state to 0, but does not generate an
20535 error (see @code{glGetError}). To query for an entire mipmap array, use
20536 an image array level greater than or equal to 1.
20538 If @var{target} is @code{GL_TEXTURE_1D}, data is read from @var{data} as
20539 a sequence of signed or unsigned bytes, shorts, or longs, or
20540 single-precision floating-point values, depending on @var{type}. These
20541 values are grouped into sets of one, two, three, or four values,
20542 depending on @var{format}, to form elements. If @var{type} is
20543 @code{GL_BITMAP}, the data is considered as a string of unsigned bytes
20544 (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is
20545 treated as eight 1-bit elements, with bit ordering determined by
20546 @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}).
20548 If a non-zero named buffer object is bound to the
20549 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
20550 texture image is specified, @var{data} is treated as a byte offset into
20551 the buffer object's data store.
20553 The first element corresponds to the left end of the texture array.
20554 Subsequent elements progress left-to-right through the remaining texels
20555 in the texture array. The final element corresponds to the right end of
20558 @var{format} determines the composition of each element in @var{data}.
20559 It can assume one of these symbolic values:
20562 @item @code{GL_COLOR_INDEX}
20563 Each element is a single value, a color index. The GL converts it to
20564 fixed point (with an unspecified number of zero bits to the right of the
20565 binary point), shifted left or right depending on the value and sign of
20566 @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see
20567 @code{glPixelTransfer}). The resulting index is converted to a set of
20568 color components using the @code{GL_PIXEL_MAP_I_TO_R},
20569 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
20570 @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1].
20572 @item @code{GL_RED}
20573 Each element is a single red component. The GL converts it to floating
20574 point and assembles it into an RGBA element by attaching 0 for green and
20575 blue, and 1 for alpha. Each component is then multiplied by the signed
20576 scale factor @code{GL_c_SCALE}, added to the signed bias
20577 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20578 @code{glPixelTransfer}).
20580 @item @code{GL_GREEN}
20581 Each element is a single green component. The GL converts it to
20582 floating point and assembles it into an RGBA element by attaching 0 for
20583 red and blue, and 1 for alpha. Each component is then multiplied by the
20584 signed scale factor @code{GL_c_SCALE}, added to the signed bias
20585 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20586 @code{glPixelTransfer}).
20588 @item @code{GL_BLUE}
20589 Each element is a single blue component. The GL converts it to floating
20590 point and assembles it into an RGBA element by attaching 0 for red and
20591 green, and 1 for alpha. Each component is then multiplied by the signed
20592 scale factor @code{GL_c_SCALE}, added to the signed bias
20593 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20594 @code{glPixelTransfer}).
20596 @item @code{GL_ALPHA}
20597 Each element is a single alpha component. The GL converts it to
20598 floating point and assembles it into an RGBA element by attaching 0 for
20599 red, green, and blue. Each component is then multiplied by the signed
20600 scale factor @code{GL_c_SCALE}, added to the signed bias
20601 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20602 @code{glPixelTransfer}).
20604 @item @code{GL_INTENSITY}
20605 Each element is a single intensity value. The GL converts it to
20606 floating point, then assembles it into an RGBA element by replicating
20607 the intensity value three times for red, green, blue, and alpha. Each
20608 component is then multiplied by the signed scale factor
20609 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20610 clamped to the range [0,1] (see @code{glPixelTransfer}).
20612 @item @code{GL_RGB}
20613 @item @code{GL_BGR}
20614 Each element is an RGB triple. The GL converts it to floating point and
20615 assembles it into an RGBA element by attaching 1 for alpha. Each
20616 component is then multiplied by the signed scale factor
20617 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20618 clamped to the range [0,1] (see @code{glPixelTransfer}).
20620 @item @code{GL_RGBA}
20621 @item @code{GL_BGRA}
20622 Each element contains all four components. Each component is multiplied
20623 by the signed scale factor @code{GL_c_SCALE}, added to the signed bias
20624 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20625 @code{glPixelTransfer}).
20627 @item @code{GL_LUMINANCE}
20628 Each element is a single luminance value. The GL converts it to
20629 floating point, then assembles it into an RGBA element by replicating
20630 the luminance value three times for red, green, and blue and attaching 1
20631 for alpha. Each component is then multiplied by the signed scale factor
20632 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20633 clamped to the range [0,1] (see @code{glPixelTransfer}).
20635 @item @code{GL_LUMINANCE_ALPHA}
20636 Each element is a luminance/alpha pair. The GL converts it to floating
20637 point, then assembles it into an RGBA element by replicating the
20638 luminance value three times for red, green, and blue. Each component is
20639 then multiplied by the signed scale factor @code{GL_c_SCALE}, added to
20640 the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20641 @code{glPixelTransfer}).
20643 @item @code{GL_DEPTH_COMPONENT}
20644 Each element is a single depth value. The GL converts it to floating
20645 point, multiplies by the signed scale factor @code{GL_DEPTH_SCALE}, adds
20646 the signed bias @code{GL_DEPTH_BIAS}, and clamps to the range [0,1] (see
20647 @code{glPixelTransfer}).
20651 Refer to the @code{glDrawPixels} reference page for a description of the
20652 acceptable values for the @var{type} parameter.
20654 If an application wants to store the texture at a certain resolution or
20655 in a certain format, it can request the resolution and format with
20656 @var{internalFormat}. The GL will choose an internal representation
20657 that closely approximates that requested by @var{internalFormat}, but it
20658 may not match exactly. (The representations specified by
20659 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and
20660 @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4
20661 may also be used to specify the above representations.)
20663 If the @var{internalFormat} parameter is one of the generic compressed
20664 formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
20665 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
20666 @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will
20667 replace the internal format with the symbolic constant for a specific
20668 internal format and compress the texture before storage. If no
20669 corresponding internal format is available, or the GL can not compress
20670 that image for any reason, the internal format is instead replaced with
20671 a corresponding base internal format.
20673 If the @var{internalFormat} parameter is @code{GL_SRGB},
20674 @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8},
20675 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
20676 or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red,
20677 green, blue, or luminance components are encoded in the sRGB color
20678 space. Any alpha component is left unchanged. The conversion from the
20679 sRGB encoded component @r{@var{c}_@var{s}} to a linear component
20680 @r{@var{c}_@var{l}} is:
20682 @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045),
20683 ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)}
20685 Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1].
20687 Use the @code{GL_PROXY_TEXTURE_1D} target to try out a resolution and
20688 format. The implementation will update and recompute its best match for
20689 the requested storage resolution and format. To then query this state,
20690 call @code{glGetTexLevelParameter}. If the texture cannot be
20691 accommodated, texture state is set to 0.
20693 A one-component texture image uses only the red component of the RGBA
20694 color from @var{data}. A two-component image uses the R and A values. A
20695 three-component image uses the R, G, and B values. A four-component
20696 image uses all of the RGBA components.
20698 Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA textures
20699 during texture filtering and application. Image-based shadowing can be
20700 enabled by comparing texture r coordinates to depth texture values to
20701 generate a boolean result. See @code{glTexParameter} for details on
20702 texture comparison.
20704 @code{GL_INVALID_ENUM} is generated if @var{target} is not
20705 @code{GL_TEXTURE_1D} or @code{GL_PROXY_TEXTURE_1D}.
20707 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
20708 format constant. Format constants other than @code{GL_STENCIL_INDEX}
20711 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
20714 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
20715 and @var{format} is not @code{GL_COLOR_INDEX}.
20717 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
20719 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
20720 @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of
20721 @code{GL_MAX_TEXTURE_SIZE}.
20723 @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1,
20724 2, 3, 4, or one of the accepted resolution and format symbolic
20727 @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or
20728 greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
20730 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
20731 not supported and the @var{width} cannot be represented as
20732 @r{2^@var{n}+2(@var{border},)} for some integer value of @var{n}.
20734 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
20736 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
20737 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
20738 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
20739 and @var{format} is not @code{GL_RGB}.
20741 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
20742 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
20743 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
20744 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
20745 @code{GL_UNSIGNED_INT_10_10_10_2}, or
20746 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
20747 @code{GL_RGBA} nor @code{GL_BGRA}.
20749 @code{GL_INVALID_OPERATION} is generated if @var{format} is
20750 @code{GL_DEPTH_COMPONENT} and @var{internalFormat} is not
20751 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
20752 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}.
20754 @code{GL_INVALID_OPERATION} is generated if @var{internalFormat} is
20755 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
20756 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}, and
20757 @var{format} is not @code{GL_DEPTH_COMPONENT}.
20759 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
20760 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
20761 object's data store is currently mapped.
20763 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
20764 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
20765 would be unpacked from the buffer object such that the memory reads
20766 required would exceed the data store size.
20768 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
20769 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
20770 is not evenly divisible into the number of bytes needed to store in
20771 memory a datum indicated by @var{type}.
20773 @code{GL_INVALID_OPERATION} is generated if @code{glTexImage1D} is
20774 executed between the execution of @code{glBegin} and the corresponding
20775 execution of @code{glEnd}.
20779 @deftypefun void glTexImage2D target level internalFormat width height border format type data
20780 Specify a two-dimensional texture image.
20784 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
20785 @code{GL_PROXY_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
20786 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
20787 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
20788 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
20789 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z},
20790 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or
20791 @code{GL_PROXY_TEXTURE_CUBE_MAP}.
20794 Specifies the level-of-detail number. Level 0 is the base image level.
20795 Level @var{n} is the @var{n}th mipmap reduction image.
20797 @item @var{internalFormat}
20798 Specifies the number of color components in the texture. Must be 1, 2,
20799 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA},
20800 @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
20801 @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA},
20802 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
20803 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
20804 @code{GL_COMPRESSED_RGBA}, @code{GL_DEPTH_COMPONENT},
20805 @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24},
20806 @code{GL_DEPTH_COMPONENT32}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
20807 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
20808 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
20809 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
20810 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
20811 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY},
20812 @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12},
20813 @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
20814 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
20815 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
20816 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
20817 @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE},
20818 @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
20819 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
20820 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
20823 Specifies the width of the texture image including the border if any. If
20824 the GL version does not support non-power-of-two sizes, this value must
20825 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
20826 implementations support texture images that are at least 64 texels wide.
20829 Specifies the height of the texture image including the border if any.
20830 If the GL version does not support non-power-of-two sizes, this value
20831 must be @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}.
20832 All implementations support texture images that are at least 64 texels
20836 Specifies the width of the border. Must be either 0 or 1.
20839 Specifies the format of the pixel data. The following symbolic values
20840 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
20841 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
20842 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
20843 @code{GL_LUMINANCE_ALPHA}.
20846 Specifies the data type of the pixel data. The following symbolic
20847 values are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE},
20848 @code{GL_BITMAP}, @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT},
20849 @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT},
20850 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
20851 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
20852 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
20853 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
20854 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
20855 @code{GL_UNSIGNED_INT_10_10_10_2}, and
20856 @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
20859 Specifies a pointer to the image data in memory.
20863 Texturing maps a portion of a specified texture image onto each
20864 graphical primitive for which texturing is enabled. To enable and
20865 disable two-dimensional texturing, call @code{glEnable} and
20866 @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and
20867 disable texturing using cube-mapped texture, call @code{glEnable} and
20868 @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}.
20870 To define texture images, call @code{glTexImage2D}. The arguments
20871 describe the parameters of the texture image, such as height, width,
20872 width of the border, level-of-detail number (see @code{glTexParameter}),
20873 and number of color components provided. The last three arguments
20874 describe how the image is represented in memory; they are identical to
20875 the pixel formats used for @code{glDrawPixels}.
20877 If @var{target} is @code{GL_PROXY_TEXTURE_2D} or
20878 @code{GL_PROXY_TEXTURE_CUBE_MAP}, no data is read from @var{data}, but
20879 all of the texture image state is recalculated, checked for consistency,
20880 and checked against the implementation's capabilities. If the
20881 implementation cannot handle a texture of the requested texture size, it
20882 sets all of the image state to 0, but does not generate an error (see
20883 @code{glGetError}). To query for an entire mipmap array, use an image
20884 array level greater than or equal to 1.
20886 If @var{target} is @code{GL_TEXTURE_2D}, or one of the
20887 @code{GL_TEXTURE_CUBE_MAP} targets, data is read from @var{data} as a
20888 sequence of signed or unsigned bytes, shorts, or longs, or
20889 single-precision floating-point values, depending on @var{type}. These
20890 values are grouped into sets of one, two, three, or four values,
20891 depending on @var{format}, to form elements. If @var{type} is
20892 @code{GL_BITMAP}, the data is considered as a string of unsigned bytes
20893 (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is
20894 treated as eight 1-bit elements, with bit ordering determined by
20895 @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}).
20897 If a non-zero named buffer object is bound to the
20898 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
20899 texture image is specified, @var{data} is treated as a byte offset into
20900 the buffer object's data store.
20902 The first element corresponds to the lower left corner of the texture
20903 image. Subsequent elements progress left-to-right through the remaining
20904 texels in the lowest row of the texture image, and then in successively
20905 higher rows of the texture image. The final element corresponds to the
20906 upper right corner of the texture image.
20908 @var{format} determines the composition of each element in @var{data}.
20909 It can assume one of these symbolic values:
20912 @item @code{GL_COLOR_INDEX}
20913 Each element is a single value, a color index. The GL converts it to
20914 fixed point (with an unspecified number of zero bits to the right of the
20915 binary point), shifted left or right depending on the value and sign of
20916 @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see
20917 @code{glPixelTransfer}). The resulting index is converted to a set of
20918 color components using the @code{GL_PIXEL_MAP_I_TO_R},
20919 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
20920 @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1].
20922 @item @code{GL_RED}
20923 Each element is a single red component. The GL converts it to floating
20924 point and assembles it into an RGBA element by attaching 0 for green and
20925 blue, and 1 for alpha. Each component is then multiplied by the signed
20926 scale factor @code{GL_c_SCALE}, added to the signed bias
20927 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20928 @code{glPixelTransfer}).
20930 @item @code{GL_GREEN}
20931 Each element is a single green component. The GL converts it to
20932 floating point and assembles it into an RGBA element by attaching 0 for
20933 red and blue, and 1 for alpha. Each component is then multiplied by the
20934 signed scale factor @code{GL_c_SCALE}, added to the signed bias
20935 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20936 @code{glPixelTransfer}).
20938 @item @code{GL_BLUE}
20939 Each element is a single blue component. The GL converts it to floating
20940 point and assembles it into an RGBA element by attaching 0 for red and
20941 green, and 1 for alpha. Each component is then multiplied by the signed
20942 scale factor @code{GL_c_SCALE}, added to the signed bias
20943 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20944 @code{glPixelTransfer}).
20946 @item @code{GL_ALPHA}
20947 Each element is a single alpha component. The GL converts it to
20948 floating point and assembles it into an RGBA element by attaching 0 for
20949 red, green, and blue. Each component is then multiplied by the signed
20950 scale factor @code{GL_c_SCALE}, added to the signed bias
20951 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20952 @code{glPixelTransfer}).
20954 @item @code{GL_INTENSITY}
20955 Each element is a single intensity value. The GL converts it to
20956 floating point, then assembles it into an RGBA element by replicating
20957 the intensity value three times for red, green, blue, and alpha. Each
20958 component is then multiplied by the signed scale factor
20959 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20960 clamped to the range [0,1] (see @code{glPixelTransfer}).
20962 @item @code{GL_RGB}
20963 @item @code{GL_BGR}
20964 Each element is an RGB triple. The GL converts it to floating point and
20965 assembles it into an RGBA element by attaching 1 for alpha. Each
20966 component is then multiplied by the signed scale factor
20967 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20968 clamped to the range [0,1] (see @code{glPixelTransfer}).
20970 @item @code{GL_RGBA}
20971 @item @code{GL_BGRA}
20972 Each element contains all four components. Each component is multiplied
20973 by the signed scale factor @code{GL_c_SCALE}, added to the signed bias
20974 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20975 @code{glPixelTransfer}).
20977 @item @code{GL_LUMINANCE}
20978 Each element is a single luminance value. The GL converts it to
20979 floating point, then assembles it into an RGBA element by replicating
20980 the luminance value three times for red, green, and blue and attaching 1
20981 for alpha. Each component is then multiplied by the signed scale factor
20982 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
20983 clamped to the range [0,1] (see @code{glPixelTransfer}).
20985 @item @code{GL_LUMINANCE_ALPHA}
20986 Each element is a luminance/alpha pair. The GL converts it to floating
20987 point, then assembles it into an RGBA element by replicating the
20988 luminance value three times for red, green, and blue. Each component is
20989 then multiplied by the signed scale factor @code{GL_c_SCALE}, added to
20990 the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see
20991 @code{glPixelTransfer}).
20993 @item @code{GL_DEPTH_COMPONENT}
20994 Each element is a single depth value. The GL converts it to floating
20995 point, multiplies by the signed scale factor @code{GL_DEPTH_SCALE}, adds
20996 the signed bias @code{GL_DEPTH_BIAS}, and clamps to the range [0,1] (see
20997 @code{glPixelTransfer}).
21001 Refer to the @code{glDrawPixels} reference page for a description of the
21002 acceptable values for the @var{type} parameter.
21004 If an application wants to store the texture at a certain resolution or
21005 in a certain format, it can request the resolution and format with
21006 @var{internalFormat}. The GL will choose an internal representation
21007 that closely approximates that requested by @var{internalFormat}, but it
21008 may not match exactly. (The representations specified by
21009 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and
21010 @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4
21011 may also be used to specify the above representations.)
21013 If the @var{internalFormat} parameter is one of the generic compressed
21014 formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
21015 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
21016 @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will
21017 replace the internal format with the symbolic constant for a specific
21018 internal format and compress the texture before storage. If no
21019 corresponding internal format is available, or the GL can not compress
21020 that image for any reason, the internal format is instead replaced with
21021 a corresponding base internal format.
21023 If the @var{internalFormat} parameter is @code{GL_SRGB},
21024 @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8},
21025 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
21026 or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red,
21027 green, blue, or luminance components are encoded in the sRGB color
21028 space. Any alpha component is left unchanged. The conversion from the
21029 sRGB encoded component @r{@var{c}_@var{s}} to a linear component
21030 @r{@var{c}_@var{l}} is:
21032 @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045),
21033 ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)}
21035 Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1].
21037 Use the @code{GL_PROXY_TEXTURE_2D} or @code{GL_PROXY_TEXTURE_CUBE_MAP}
21038 target to try out a resolution and format. The implementation will
21039 update and recompute its best match for the requested storage resolution
21040 and format. To then query this state, call
21041 @code{glGetTexLevelParameter}. If the texture cannot be accommodated,
21042 texture state is set to 0.
21044 A one-component texture image uses only the red component of the RGBA
21045 color extracted from @var{data}. A two-component image uses the R and A
21046 values. A three-component image uses the R, G, and B values. A
21047 four-component image uses all of the RGBA components.
21049 Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA textures
21050 during texture filtering and application. Image-based shadowing can be
21051 enabled by comparing texture r coordinates to depth texture values to
21052 generate a boolean result. See @code{glTexParameter} for details on
21053 texture comparison.
21055 @code{GL_INVALID_ENUM} is generated if @var{target} is not
21056 @code{GL_TEXTURE_2D}, @code{GL_PROXY_TEXTURE_2D},
21057 @code{GL_PROXY_TEXTURE_CUBE_MAP}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
21058 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
21059 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
21060 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
21061 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
21062 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
21064 @code{GL_INVALID_ENUM} is generated if @var{target} is one of the six
21065 cube map 2D image targets and the width and height parameters are not
21068 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
21071 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
21072 and @var{format} is not @code{GL_COLOR_INDEX}.
21074 @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is
21075 less than 0 or greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
21077 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
21079 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
21080 @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of
21081 @code{GL_MAX_TEXTURE_SIZE}.
21083 @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1,
21084 2, 3, 4, or one of the accepted resolution and format symbolic
21087 @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is
21088 less than 0 or greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
21090 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
21091 not supported and the @var{width} or @var{height} cannot be represented
21092 as @r{2^@var{k}+2(@var{border},)} for some integer value of @var{k}.
21094 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
21096 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21097 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
21098 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
21099 and @var{format} is not @code{GL_RGB}.
21101 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21102 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
21103 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
21104 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
21105 @code{GL_UNSIGNED_INT_10_10_10_2}, or
21106 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
21107 @code{GL_RGBA} nor @code{GL_BGRA}.
21109 @code{GL_INVALID_OPERATION} is generated if @var{target} is not
21110 @code{GL_TEXTURE_2D} or @code{GL_PROXY_TEXTURE_2D} and
21111 @var{internalFormat} is @code{GL_DEPTH_COMPONENT},
21112 @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, or
21113 @code{GL_DEPTH_COMPONENT32}.
21115 @code{GL_INVALID_OPERATION} is generated if @var{format} is
21116 @code{GL_DEPTH_COMPONENT} and @var{internalFormat} is not
21117 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
21118 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}.
21120 @code{GL_INVALID_OPERATION} is generated if @var{internalFormat} is
21121 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
21122 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}, and
21123 @var{format} is not @code{GL_DEPTH_COMPONENT}.
21125 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21126 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
21127 object's data store is currently mapped.
21129 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21130 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
21131 would be unpacked from the buffer object such that the memory reads
21132 required would exceed the data store size.
21134 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21135 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
21136 is not evenly divisible into the number of bytes needed to store in
21137 memory a datum indicated by @var{type}.
21139 @code{GL_INVALID_OPERATION} is generated if @code{glTexImage2D} is
21140 executed between the execution of @code{glBegin} and the corresponding
21141 execution of @code{glEnd}.
21145 @deftypefun void glTexImage3D target level internalFormat width height depth border format type data
21146 Specify a three-dimensional texture image.
21150 Specifies the target texture. Must be @code{GL_TEXTURE_3D} or
21151 @code{GL_PROXY_TEXTURE_3D}.
21154 Specifies the level-of-detail number. Level 0 is the base image level.
21155 Level @r{@var{n}} is the @r{@var{n}^@var{th}} mipmap reduction image.
21157 @item @var{internalFormat}
21158 Specifies the number of color components in the texture. Must be 1, 2,
21159 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA},
21160 @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
21161 @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA},
21162 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
21163 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
21164 @code{GL_COMPRESSED_RGBA}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
21165 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
21166 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
21167 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
21168 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
21169 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY},
21170 @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12},
21171 @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
21172 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
21173 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
21174 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
21175 @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE},
21176 @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
21177 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
21178 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
21181 Specifies the width of the texture image including the border if any. If
21182 the GL version does not support non-power-of-two sizes, this value must
21183 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
21184 implementations support 3D texture images that are at least 16 texels
21188 Specifies the height of the texture image including the border if any.
21189 If the GL version does not support non-power-of-two sizes, this value
21190 must be @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}.
21191 All implementations support 3D texture images that are at least 16
21195 Specifies the depth of the texture image including the border if any. If
21196 the GL version does not support non-power-of-two sizes, this value must
21197 be @r{2^@var{k}+2(@var{border},)} for some integer @r{@var{k}}. All
21198 implementations support 3D texture images that are at least 16 texels
21202 Specifies the width of the border. Must be either 0 or 1.
21205 Specifies the format of the pixel data. The following symbolic values
21206 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
21207 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
21208 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
21209 @code{GL_LUMINANCE_ALPHA}.
21212 Specifies the data type of the pixel data. The following symbolic
21213 values are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE},
21214 @code{GL_BITMAP}, @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT},
21215 @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT},
21216 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
21217 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
21218 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
21219 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
21220 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
21221 @code{GL_UNSIGNED_INT_10_10_10_2}, and
21222 @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
21225 Specifies a pointer to the image data in memory.
21229 Texturing maps a portion of a specified texture image onto each
21230 graphical primitive for which texturing is enabled. To enable and
21231 disable three-dimensional texturing, call @code{glEnable} and
21232 @code{glDisable} with argument @code{GL_TEXTURE_3D}.
21234 To define texture images, call @code{glTexImage3D}. The arguments
21235 describe the parameters of the texture image, such as height, width,
21236 depth, width of the border, level-of-detail number (see
21237 @code{glTexParameter}), and number of color components provided. The
21238 last three arguments describe how the image is represented in memory;
21239 they are identical to the pixel formats used for @code{glDrawPixels}.
21241 If @var{target} is @code{GL_PROXY_TEXTURE_3D}, no data is read from
21242 @var{data}, but all of the texture image state is recalculated, checked
21243 for consistency, and checked against the implementation's capabilities.
21244 If the implementation cannot handle a texture of the requested texture
21245 size, it sets all of the image state to 0, but does not generate an
21246 error (see @code{glGetError}). To query for an entire mipmap array, use
21247 an image array level greater than or equal to 1.
21249 If @var{target} is @code{GL_TEXTURE_3D}, data is read from @var{data} as
21250 a sequence of signed or unsigned bytes, shorts, or longs, or
21251 single-precision floating-point values, depending on @var{type}. These
21252 values are grouped into sets of one, two, three, or four values,
21253 depending on @var{format}, to form elements. If @var{type} is
21254 @code{GL_BITMAP}, the data is considered as a string of unsigned bytes
21255 (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is
21256 treated as eight 1-bit elements, with bit ordering determined by
21257 @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}).
21259 If a non-zero named buffer object is bound to the
21260 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
21261 texture image is specified, @var{data} is treated as a byte offset into
21262 the buffer object's data store.
21264 The first element corresponds to the lower left corner of the texture
21265 image. Subsequent elements progress left-to-right through the remaining
21266 texels in the lowest row of the texture image, and then in successively
21267 higher rows of the texture image. The final element corresponds to the
21268 upper right corner of the texture image.
21270 @var{format} determines the composition of each element in @var{data}.
21271 It can assume one of these symbolic values:
21274 @item @code{GL_COLOR_INDEX}
21275 Each element is a single value, a color index. The GL converts it to
21276 fixed point (with an unspecified number of zero bits to the right of the
21277 binary point), shifted left or right depending on the value and sign of
21278 @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see
21279 @code{glPixelTransfer}). The resulting index is converted to a set of
21280 color components using the @code{GL_PIXEL_MAP_I_TO_R},
21281 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
21282 @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1].
21284 @item @code{GL_RED}
21285 Each element is a single red component. The GL converts it to floating
21286 point and assembles it into an RGBA element by attaching 0 for green and
21287 blue, and 1 for alpha. Each component is then multiplied by the signed
21288 scale factor @code{GL_c_SCALE}, added to the signed bias
21289 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
21290 @code{glPixelTransfer}).
21292 @item @code{GL_GREEN}
21293 Each element is a single green component. The GL converts it to
21294 floating point and assembles it into an RGBA element by attaching 0 for
21295 red and blue, and 1 for alpha. Each component is then multiplied by the
21296 signed scale factor @code{GL_c_SCALE}, added to the signed bias
21297 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
21298 @code{glPixelTransfer}).
21300 @item @code{GL_BLUE}
21301 Each element is a single blue component. The GL converts it to floating
21302 point and assembles it into an RGBA element by attaching 0 for red and
21303 green, and 1 for alpha. Each component is then multiplied by the signed
21304 scale factor @code{GL_c_SCALE}, added to the signed bias
21305 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
21306 @code{glPixelTransfer}).
21308 @item @code{GL_ALPHA}
21309 Each element is a single alpha component. The GL converts it to
21310 floating point and assembles it into an RGBA element by attaching 0 for
21311 red, green, and blue. Each component is then multiplied by the signed
21312 scale factor @code{GL_c_SCALE}, added to the signed bias
21313 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
21314 @code{glPixelTransfer}).
21316 @item @code{GL_INTENSITY}
21317 Each element is a single intensity value. The GL converts it to
21318 floating point, then assembles it into an RGBA element by replicating
21319 the intensity value three times for red, green, blue, and alpha. Each
21320 component is then multiplied by the signed scale factor
21321 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
21322 clamped to the range [0,1] (see @code{glPixelTransfer}).
21324 @item @code{GL_RGB}
21325 @item @code{GL_BGR}
21326 Each element is an RGB triple. The GL converts it to floating point and
21327 assembles it into an RGBA element by attaching 1 for alpha. Each
21328 component is then multiplied by the signed scale factor
21329 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
21330 clamped to the range [0,1] (see @code{glPixelTransfer}).
21332 @item @code{GL_RGBA}
21333 @item @code{GL_BGRA}
21334 Each element contains all four components. Each component is multiplied
21335 by the signed scale factor @code{GL_c_SCALE}, added to the signed bias
21336 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
21337 @code{glPixelTransfer}).
21339 @item @code{GL_LUMINANCE}
21340 Each element is a single luminance value. The GL converts it to
21341 floating point, then assembles it into an RGBA element by replicating
21342 the luminance value three times for red, green, and blue and attaching 1
21343 for alpha. Each component is then multiplied by the signed scale factor
21344 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
21345 clamped to the range [0,1] (see @code{glPixelTransfer}).
21347 @item @code{GL_LUMINANCE_ALPHA}
21348 Each element is a luminance/alpha pair. The GL converts it to floating
21349 point, then assembles it into an RGBA element by replicating the
21350 luminance value three times for red, green, and blue. Each component is
21351 then multiplied by the signed scale factor @code{GL_c_SCALE}, added to
21352 the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see
21353 @code{glPixelTransfer}).
21357 Refer to the @code{glDrawPixels} reference page for a description of the
21358 acceptable values for the @var{type} parameter.
21360 If an application wants to store the texture at a certain resolution or
21361 in a certain format, it can request the resolution and format with
21362 @var{internalFormat}. The GL will choose an internal representation
21363 that closely approximates that requested by @var{internalFormat}, but it
21364 may not match exactly. (The representations specified by
21365 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and
21366 @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4
21367 may also be used to specify the above representations.)
21369 If the @var{internalFormat} parameter is one of the generic compressed
21370 formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
21371 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
21372 @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will
21373 replace the internal format with the symbolic constant for a specific
21374 internal format and compress the texture before storage. If no
21375 corresponding internal format is available, or the GL can not compress
21376 that image for any reason, the internal format is instead replaced with
21377 a corresponding base internal format.
21379 If the @var{internalFormat} parameter is @code{GL_SRGB},
21380 @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8},
21381 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
21382 or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red,
21383 green, blue, or luminance components are encoded in the sRGB color
21384 space. Any alpha component is left unchanged. The conversion from the
21385 sRGB encoded component @r{@var{c}_@var{s}} to a linear component
21386 @r{@var{c}_@var{l}} is:
21388 @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045),
21389 ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)}
21391 Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1].
21393 Use the @code{GL_PROXY_TEXTURE_3D} target to try out a resolution and
21394 format. The implementation will update and recompute its best match for
21395 the requested storage resolution and format. To then query this state,
21396 call @code{glGetTexLevelParameter}. If the texture cannot be
21397 accommodated, texture state is set to 0.
21399 A one-component texture image uses only the red component of the RGBA
21400 color extracted from @var{data}. A two-component image uses the R and A
21401 values. A three-component image uses the R, G, and B values. A
21402 four-component image uses all of the RGBA components.
21404 @code{GL_INVALID_ENUM} is generated if @var{target} is not
21405 @code{GL_TEXTURE_3D} or @code{GL_PROXY_TEXTURE_3D}.
21407 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
21408 format constant. Format constants other than @code{GL_STENCIL_INDEX}
21409 and @code{GL_DEPTH_COMPONENT} are accepted.
21411 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
21414 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
21415 and @var{format} is not @code{GL_COLOR_INDEX}.
21417 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
21419 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
21420 @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of
21421 @code{GL_MAX_TEXTURE_SIZE}.
21423 @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1,
21424 2, 3, 4, or one of the accepted resolution and format symbolic
21427 @code{GL_INVALID_VALUE} is generated if @var{width}, @var{height}, or
21428 @var{depth} is less than 0 or greater than 2 +
21429 @code{GL_MAX_TEXTURE_SIZE}.
21431 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
21432 not supported and the @var{width}, @var{height}, or @var{depth} cannot
21433 be represented as @r{2^@var{k}+2(@var{border},)} for some integer value
21436 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
21438 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21439 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
21440 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
21441 and @var{format} is not @code{GL_RGB}.
21443 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21444 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
21445 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
21446 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
21447 @code{GL_UNSIGNED_INT_10_10_10_2}, or
21448 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
21449 @code{GL_RGBA} nor @code{GL_BGRA}.
21451 @code{GL_INVALID_OPERATION} is generated if @var{format} or
21452 @var{internalFormat} is @code{GL_DEPTH_COMPONENT},
21453 @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, or
21454 @code{GL_DEPTH_COMPONENT32}.
21456 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21457 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
21458 object's data store is currently mapped.
21460 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21461 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
21462 would be unpacked from the buffer object such that the memory reads
21463 required would exceed the data store size.
21465 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21466 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
21467 is not evenly divisible into the number of bytes needed to store in
21468 memory a datum indicated by @var{type}.
21470 @code{GL_INVALID_OPERATION} is generated if @code{glTexImage3D} is
21471 executed between the execution of @code{glBegin} and the corresponding
21472 execution of @code{glEnd}.
21476 @deftypefun void glTexParameterf target pname param
21477 @deftypefunx void glTexParameteri target pname param
21478 @deftypefunx void glTexParameterfv target pname params
21479 @deftypefunx void glTexParameteriv target pname params
21480 Set texture parameters.
21484 Specifies the target texture, which must be either @code{GL_TEXTURE_1D},
21485 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, or
21486 @code{GL_TEXTURE_CUBE_MAP}.
21489 Specifies the symbolic name of a single-valued texture parameter.
21490 @var{pname} can be one of the following: @code{GL_TEXTURE_MIN_FILTER},
21491 @code{GL_TEXTURE_MAG_FILTER}, @code{GL_TEXTURE_MIN_LOD},
21492 @code{GL_TEXTURE_MAX_LOD}, @code{GL_TEXTURE_BASE_LEVEL},
21493 @code{GL_TEXTURE_MAX_LEVEL}, @code{GL_TEXTURE_WRAP_S},
21494 @code{GL_TEXTURE_WRAP_T}, @code{GL_TEXTURE_WRAP_R},
21495 @code{GL_TEXTURE_PRIORITY}, @code{GL_TEXTURE_COMPARE_MODE},
21496 @code{GL_TEXTURE_COMPARE_FUNC}, @code{GL_DEPTH_TEXTURE_MODE}, or
21497 @code{GL_GENERATE_MIPMAP}.
21500 Specifies the value of @var{pname}.
21504 Texture mapping is a technique that applies an image onto an object's
21505 surface as if the image were a decal or cellophane shrink-wrap. The
21506 image is created in texture space, with an (@r{@var{s}}, @r{@var{t}})
21507 coordinate system. A texture is a one- or two-dimensional image and a
21508 set of parameters that determine how samples are derived from the image.
21510 @code{glTexParameter} assigns the value or values in @var{params} to the
21511 texture parameter specified as @var{pname}. @var{target} defines the
21512 target texture, either @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, or
21513 @code{GL_TEXTURE_3D}. The following symbols are accepted in
21517 @item @code{GL_TEXTURE_MIN_FILTER}
21518 The texture minifying function is used whenever the pixel being textured
21519 maps to an area greater than one texture element. There are six defined
21520 minifying functions. Two of them use the nearest one or nearest four
21521 texture elements to compute the texture value. The other four use
21524 A mipmap is an ordered set of arrays representing the same image at
21525 progressively lower resolutions. If the texture has dimensions
21526 @r{2^@var{n}×2^@var{m}}, there are @r{@var{max}(@var{n},@var{m})+1}
21527 mipmaps. The first mipmap is the original texture, with dimensions
21528 @r{2^@var{n}×2^@var{m}}. Each subsequent mipmap has dimensions
21529 @r{2^@var{k}-1,×2^@var{l}-1,}, where @r{2^@var{k}×2^@var{l}} are the
21530 dimensions of the previous mipmap, until either @r{@var{k}=0} or
21531 @r{@var{l}=0}. At that point, subsequent mipmaps have dimension
21532 @r{1×2^@var{l}-1,} or @r{2^@var{k}-1,×1} until the final mipmap, which
21533 has dimension @r{1×1}. To define the mipmaps, call @code{glTexImage1D},
21534 @code{glTexImage2D}, @code{glTexImage3D}, @code{glCopyTexImage1D}, or
21535 @code{glCopyTexImage2D} with the @var{level} argument indicating the
21536 order of the mipmaps. Level 0 is the original texture; level
21537 @r{@var{max}(@var{n},@var{m})} is the final @r{1×1} mipmap.
21539 @var{params} supplies a function for minifying the texture as one of the
21542 As more texture elements are sampled in the minification process, fewer
21543 aliasing artifacts will be apparent. While the @code{GL_NEAREST} and
21544 @code{GL_LINEAR} minification functions can be faster than the other
21545 four, they sample only one or four texture elements to determine the
21546 texture value of the pixel being rendered and can produce moire patterns
21547 or ragged transitions. The initial value of
21548 @code{GL_TEXTURE_MIN_FILTER} is @code{GL_NEAREST_MIPMAP_LINEAR}.
21550 @item @code{GL_TEXTURE_MAG_FILTER}
21551 The texture magnification function is used when the pixel being textured
21552 maps to an area less than or equal to one texture element. It sets the
21553 texture magnification function to either @code{GL_NEAREST} or
21554 @code{GL_LINEAR} (see below). @code{GL_NEAREST} is generally faster
21555 than @code{GL_LINEAR}, but it can produce textured images with sharper
21556 edges because the transition between texture elements is not as smooth.
21557 The initial value of @code{GL_TEXTURE_MAG_FILTER} is @code{GL_LINEAR}.
21562 @item @code{GL_NEAREST}
21563 Returns the value of the texture element that is nearest (in Manhattan
21564 distance) to the center of the pixel being textured.
21566 @item @code{GL_LINEAR}
21567 Returns the weighted average of the four texture elements that are
21568 closest to the center of the pixel being textured. These can include
21569 border texture elements, depending on the values of
21570 @code{GL_TEXTURE_WRAP_S} and @code{GL_TEXTURE_WRAP_T}, and on the exact
21573 @item @code{GL_NEAREST_MIPMAP_NEAREST}
21574 Chooses the mipmap that most closely matches the size of the pixel being
21575 textured and uses the @code{GL_NEAREST} criterion (the texture element
21576 nearest to the center of the pixel) to produce a texture value.
21578 @item @code{GL_LINEAR_MIPMAP_NEAREST}
21579 Chooses the mipmap that most closely matches the size of the pixel being
21580 textured and uses the @code{GL_LINEAR} criterion (a weighted average of
21581 the four texture elements that are closest to the center of the pixel)
21582 to produce a texture value.
21584 @item @code{GL_NEAREST_MIPMAP_LINEAR}
21585 Chooses the two mipmaps that most closely match the size of the pixel
21586 being textured and uses the @code{GL_NEAREST} criterion (the texture
21587 element nearest to the center of the pixel) to produce a texture value
21588 from each mipmap. The final texture value is a weighted average of
21591 @item @code{GL_LINEAR_MIPMAP_LINEAR}
21592 Chooses the two mipmaps that most closely match the size of the pixel
21593 being textured and uses the @code{GL_LINEAR} criterion (a weighted
21594 average of the four texture elements that are closest to the center of
21595 the pixel) to produce a texture value from each mipmap. The final
21596 texture value is a weighted average of those two values.
21601 @item @code{GL_NEAREST}
21602 Returns the value of the texture element that is nearest (in Manhattan
21603 distance) to the center of the pixel being textured.
21605 @item @code{GL_LINEAR}
21606 Returns the weighted average of the four texture elements that are
21607 closest to the center of the pixel being textured. These can include
21608 border texture elements, depending on the values of
21609 @code{GL_TEXTURE_WRAP_S} and @code{GL_TEXTURE_WRAP_T}, and on the exact
21617 @item @code{GL_TEXTURE_MIN_LOD}
21618 Sets the minimum level-of-detail parameter. This floating-point value
21619 limits the selection of highest resolution mipmap (lowest mipmap level).
21620 The initial value is -1000.
21627 @item @code{GL_TEXTURE_MAX_LOD}
21628 Sets the maximum level-of-detail parameter. This floating-point value
21629 limits the selection of the lowest resolution mipmap (highest mipmap
21630 level). The initial value is 1000.
21637 @item @code{GL_TEXTURE_BASE_LEVEL}
21638 Specifies the index of the lowest defined mipmap level. This is an
21639 integer value. The initial value is 0.
21646 @item @code{GL_TEXTURE_MAX_LEVEL}
21647 Sets the index of the highest defined mipmap level. This is an integer
21648 value. The initial value is 1000.
21655 @item @code{GL_TEXTURE_WRAP_S}
21656 Sets the wrap parameter for texture coordinate @r{@var{s}} to either
21657 @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE},
21658 @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. @code{GL_CLAMP} causes
21659 @r{@var{s}} coordinates to be clamped to the range [0,1] and is useful
21660 for preventing wrapping artifacts when mapping a single image onto an
21661 object. @code{GL_CLAMP_TO_BORDER} causes the @r{@var{s}} coordinate to
21662 be clamped to the range @r{[-1/2@var{N},,1+1/2@var{N},]}, where
21663 @r{@var{N}} is the size of the texture in the direction of
21664 clamping.@code{GL_CLAMP_TO_EDGE} causes @r{@var{s}} coordinates to be
21665 clamped to the range @r{[1/2@var{N},,1-1/2@var{N},]}, where @r{@var{N}}
21666 is the size of the texture in the direction of clamping.
21667 @code{GL_REPEAT} causes the integer part of the @r{@var{s}} coordinate
21668 to be ignored; the GL uses only the fractional part, thereby creating a
21669 repeating pattern. @code{GL_MIRRORED_REPEAT} causes the @r{@var{s}}
21670 coordinate to be set to the fractional part of the texture coordinate if
21671 the integer part of @r{@var{s}} is even; if the integer part of
21672 @r{@var{s}} is odd, then the @r{@var{s}} texture coordinate is set to
21673 @r{1-@var{frac}(@var{s},)}, where @r{@var{frac}(@var{s},)} represents
21674 the fractional part of @r{@var{s}}. Border texture elements are
21675 accessed only if wrapping is set to @code{GL_CLAMP} or
21676 @code{GL_CLAMP_TO_BORDER}. Initially, @code{GL_TEXTURE_WRAP_S} is set
21677 to @code{GL_REPEAT}.
21684 @item @code{GL_TEXTURE_WRAP_T}
21685 Sets the wrap parameter for texture coordinate @r{@var{t}} to either
21686 @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE},
21687 @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. See the discussion
21688 under @code{GL_TEXTURE_WRAP_S}. Initially, @code{GL_TEXTURE_WRAP_T} is
21689 set to @code{GL_REPEAT}.
21691 @item @code{GL_TEXTURE_WRAP_R}
21692 Sets the wrap parameter for texture coordinate @r{@var{r}} to either
21693 @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE},
21694 @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. See the discussion
21695 under @code{GL_TEXTURE_WRAP_S}. Initially, @code{GL_TEXTURE_WRAP_R} is
21696 set to @code{GL_REPEAT}.
21698 @item @code{GL_TEXTURE_BORDER_COLOR}
21699 Sets a border color. @var{params} contains four values that comprise
21700 the RGBA color of the texture border. Integer color components are
21701 interpreted linearly such that the most positive integer maps to 1.0,
21702 and the most negative integer maps to -1.0. The values are clamped to
21703 the range [0,1] when they are specified. Initially, the border color is
21706 @item @code{GL_TEXTURE_PRIORITY}
21707 Specifies the texture residence priority of the currently bound texture.
21708 Permissible values are in the range @r{[0,1]}. See
21709 @code{glPrioritizeTextures} and @code{glBindTexture} for more
21712 @item @code{GL_TEXTURE_COMPARE_MODE}
21713 Specifies the texture comparison mode for currently bound depth
21714 textures. That is, a texture whose internal format is
21715 @code{GL_DEPTH_COMPONENT_*}; see @code{glTexImage2D}) Permissible values
21718 @item @code{GL_TEXTURE_COMPARE_FUNC}
21719 Specifies the comparison operator used when
21720 @code{GL_TEXTURE_COMPARE_MODE} is set to @code{GL_COMPARE_R_TO_TEXTURE}.
21721 Permissible values are: where @r{@var{r}} is the current interpolated
21722 texture coordinate, and @r{@var{D}_@var{t}} is the depth texture value
21723 sampled from the currently bound depth texture. @r{@var{result}} is
21724 assigned to the either the luminance, intensity, or alpha (as specified
21725 by @code{GL_DEPTH_TEXTURE_MODE}.)
21727 @item @code{GL_DEPTH_TEXTURE_MODE}
21728 Specifies a single symbolic constant indicating how depth values should
21729 be treated during filtering and texture application. Accepted values
21730 are @code{GL_LUMINANCE}, @code{GL_INTENSITY}, and @code{GL_ALPHA}. The
21731 initial value is @code{GL_LUMINANCE}.
21733 @item @code{GL_GENERATE_MIPMAP}
21734 Specifies a boolean value that indicates if all levels of a mipmap array
21735 should be automatically updated when any modification to the base level
21736 mipmap is done. The initial value is @code{GL_FALSE}.
21741 @item @code{GL_COMPARE_R_TO_TEXTURE}
21742 Specifies that the interpolated and clamped @r{@var{r}} texture
21743 coordinate should be compared to the value in the currently bound depth
21744 texture. See the discussion of @code{GL_TEXTURE_COMPARE_FUNC} for
21745 details of how the comparison is evaluated. The result of the
21746 comparison is assigned to luminance, intensity, or alpha (as specified
21747 by @code{GL_DEPTH_TEXTURE_MODE}).
21749 @item @code{GL_NONE}
21750 Specifies that the luminance, intensity, or alpha (as specified by
21751 @code{GL_DEPTH_TEXTURE_MODE}) should be assigned the appropriate value
21752 from the currently bound depth texture.
21757 @item @strong{Texture Comparison Function}
21758 @strong{Computed result}
21760 @item @code{GL_LEQUAL}
21761 @r{@var{result}=@{(1.0), (0.0) (@var{r}<=@var{D}_@var{t},),
21762 (@var{r}>@var{D}_@var{t},),}
21764 @item @code{GL_GEQUAL}
21765 @r{@var{result}=@{(1.0), (0.0) (@var{r}>=@var{D}_@var{t},),
21766 (@var{r}<@var{D}_@var{t},),}
21768 @item @code{GL_LESS}
21769 @r{@var{result}=@{(1.0), (0.0) (@var{r}<@var{D}_@var{t},),
21770 (@var{r}>=@var{D}_@var{t},),}
21772 @item @code{GL_GREATER}
21773 @r{@var{result}=@{(1.0), (0.0) (@var{r}>@var{D}_@var{t},),
21774 (@var{r}<=@var{D}_@var{t},),}
21776 @item @code{GL_EQUAL}
21777 @r{@var{result}=@{(1.0), (0.0) (@var{r}=@var{D}_@var{t},),
21778 (@var{r}≠@var{D}_@var{t},),}
21780 @item @code{GL_NOTEQUAL}
21781 @r{@var{result}=@{(1.0), (0.0) (@var{r}≠@var{D}_@var{t},),
21782 (@var{r}=@var{D}_@var{t},),}
21784 @item @code{GL_ALWAYS}
21785 @r{@var{result}=@code{1.0}}
21787 @item @code{GL_NEVER}
21788 @r{@var{result}=@code{0.0}}
21792 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
21793 not one of the accepted defined values.
21795 @code{GL_INVALID_ENUM} is generated if @var{params} should have a
21796 defined constant value (based on the value of @var{pname}) and does not.
21798 @code{GL_INVALID_OPERATION} is generated if @code{glTexParameter} is
21799 executed between the execution of @code{glBegin} and the corresponding
21800 execution of @code{glEnd}.
21804 @deftypefun void glTexSubImage1D target level xoffset width format type data
21805 Specify a one-dimensional texture subimage.
21809 Specifies the target texture. Must be @code{GL_TEXTURE_1D}.
21812 Specifies the level-of-detail number. Level 0 is the base image level.
21813 Level @var{n} is the @var{n}th mipmap reduction image.
21815 @item @var{xoffset}
21816 Specifies a texel offset in the x direction within the texture array.
21819 Specifies the width of the texture subimage.
21822 Specifies the format of the pixel data. The following symbolic values
21823 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
21824 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
21825 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
21826 @code{GL_LUMINANCE_ALPHA}.
21829 Specifies the data type of the pixel data. The following symbolic
21830 values are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE},
21831 @code{GL_BITMAP}, @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT},
21832 @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT},
21833 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
21834 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
21835 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
21836 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
21837 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
21838 @code{GL_UNSIGNED_INT_10_10_10_2}, and
21839 @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
21842 Specifies a pointer to the image data in memory.
21846 Texturing maps a portion of a specified texture image onto each
21847 graphical primitive for which texturing is enabled. To enable or
21848 disable one-dimensional texturing, call @code{glEnable} and
21849 @code{glDisable} with argument @code{GL_TEXTURE_1D}.
21851 @code{glTexSubImage1D} redefines a contiguous subregion of an existing
21852 one-dimensional texture image. The texels referenced by @var{data}
21853 replace the portion of the existing texture array with x indices
21854 @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive. This
21855 region may not include any texels outside the range of the texture array
21856 as it was originally specified. It is not an error to specify a
21857 subtexture with width of 0, but such a specification has no effect.
21859 If a non-zero named buffer object is bound to the
21860 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
21861 texture image is specified, @var{data} is treated as a byte offset into
21862 the buffer object's data store.
21864 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
21867 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
21870 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
21873 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
21874 and @var{format} is not @code{GL_COLOR_INDEX}.
21876 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
21878 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
21879 @r{@var{log}_2}@var{max}, where @var{max} is the returned value of
21880 @code{GL_MAX_TEXTURE_SIZE}.
21882 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, or
21883 if @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, where
21884 @r{@var{w}} is the @code{GL_TEXTURE_WIDTH}, and @r{@var{b}} is the width
21885 of the @code{GL_TEXTURE_BORDER} of the texture image being modified.
21886 Note that @r{@var{w}} includes twice the border width.
21888 @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0.
21890 @code{GL_INVALID_OPERATION} is generated if the texture array has not
21891 been defined by a previous @code{glTexImage1D} operation.
21893 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21894 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
21895 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
21896 and @var{format} is not @code{GL_RGB}.
21898 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
21899 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
21900 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
21901 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
21902 @code{GL_UNSIGNED_INT_10_10_10_2}, or
21903 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
21904 @code{GL_RGBA} nor @code{GL_BGRA}.
21906 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21907 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
21908 object's data store is currently mapped.
21910 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21911 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
21912 would be unpacked from the buffer object such that the memory reads
21913 required would exceed the data store size.
21915 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
21916 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
21917 is not evenly divisible into the number of bytes needed to store in
21918 memory a datum indicated by @var{type}.
21920 @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage1D} is
21921 executed between the execution of @code{glBegin} and the corresponding
21922 execution of @code{glEnd}.
21926 @deftypefun void glTexSubImage2D target level xoffset yoffset width height format type data
21927 Specify a two-dimensional texture subimage.
21931 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
21932 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
21933 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
21934 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
21935 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
21936 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
21937 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
21940 Specifies the level-of-detail number. Level 0 is the base image level.
21941 Level @var{n} is the @var{n}th mipmap reduction image.
21943 @item @var{xoffset}
21944 Specifies a texel offset in the x direction within the texture array.
21946 @item @var{yoffset}
21947 Specifies a texel offset in the y direction within the texture array.
21950 Specifies the width of the texture subimage.
21953 Specifies the height of the texture subimage.
21956 Specifies the format of the pixel data. The following symbolic values
21957 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
21958 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
21959 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
21960 @code{GL_LUMINANCE_ALPHA}.
21963 Specifies the data type of the pixel data. The following symbolic
21964 values are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE},
21965 @code{GL_BITMAP}, @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT},
21966 @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT},
21967 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
21968 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
21969 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
21970 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
21971 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
21972 @code{GL_UNSIGNED_INT_10_10_10_2}, and
21973 @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
21976 Specifies a pointer to the image data in memory.
21980 Texturing maps a portion of a specified texture image onto each
21981 graphical primitive for which texturing is enabled. To enable and
21982 disable two-dimensional texturing, call @code{glEnable} and
21983 @code{glDisable} with argument @code{GL_TEXTURE_2D}.
21985 @code{glTexSubImage2D} redefines a contiguous subregion of an existing
21986 two-dimensional texture image. The texels referenced by @var{data}
21987 replace the portion of the existing texture array with x indices
21988 @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive, and y
21989 indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive.
21990 This region may not include any texels outside the range of the texture
21991 array as it was originally specified. It is not an error to specify a
21992 subtexture with zero width or height, but such a specification has no
21995 If a non-zero named buffer object is bound to the
21996 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
21997 texture image is specified, @var{data} is treated as a byte offset into
21998 the buffer object's data store.
22000 @code{GL_INVALID_ENUM} is generated if @var{target} is not
22001 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
22002 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
22003 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
22004 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
22005 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
22006 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
22008 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
22011 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
22014 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
22015 and @var{format} is not @code{GL_COLOR_INDEX}.
22017 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
22019 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
22020 @r{@var{log}_2}@var{max}, where @var{max} is the returned value of
22021 @code{GL_MAX_TEXTURE_SIZE}.
22023 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}},
22024 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)},
22025 @r{@var{yoffset}<-@var{b}}, or
22026 @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, where @r{@var{w}}
22027 is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the
22028 @code{GL_TEXTURE_HEIGHT}, and @r{@var{b}} is the border width of the
22029 texture image being modified. Note that @r{@var{w}} and @r{@var{h}}
22030 include twice the border width.
22032 @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is
22035 @code{GL_INVALID_OPERATION} is generated if the texture array has not
22036 been defined by a previous @code{glTexImage2D} operation.
22038 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
22039 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
22040 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
22041 and @var{format} is not @code{GL_RGB}.
22043 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
22044 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
22045 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
22046 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
22047 @code{GL_UNSIGNED_INT_10_10_10_2}, or
22048 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
22049 @code{GL_RGBA} nor @code{GL_BGRA}.
22051 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
22052 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
22053 object's data store is currently mapped.
22055 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
22056 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
22057 would be unpacked from the buffer object such that the memory reads
22058 required would exceed the data store size.
22060 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
22061 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
22062 is not evenly divisible into the number of bytes needed to store in
22063 memory a datum indicated by @var{type}.
22065 @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage2D} is
22066 executed between the execution of @code{glBegin} and the corresponding
22067 execution of @code{glEnd}.
22071 @deftypefun void glTexSubImage3D target level xoffset yoffset zoffset width height depth format type data
22072 Specify a three-dimensional texture subimage.
22076 Specifies the target texture. Must be @code{GL_TEXTURE_3D}.
22079 Specifies the level-of-detail number. Level 0 is the base image level.
22080 Level @var{n} is the @var{n}th mipmap reduction image.
22082 @item @var{xoffset}
22083 Specifies a texel offset in the x direction within the texture array.
22085 @item @var{yoffset}
22086 Specifies a texel offset in the y direction within the texture array.
22088 @item @var{zoffset}
22089 Specifies a texel offset in the z direction within the texture array.
22092 Specifies the width of the texture subimage.
22095 Specifies the height of the texture subimage.
22098 Specifies the depth of the texture subimage.
22101 Specifies the format of the pixel data. The following symbolic values
22102 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
22103 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
22104 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
22105 @code{GL_LUMINANCE_ALPHA}.
22108 Specifies the data type of the pixel data. The following symbolic
22109 values are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE},
22110 @code{GL_BITMAP}, @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT},
22111 @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT},
22112 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
22113 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
22114 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
22115 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
22116 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
22117 @code{GL_UNSIGNED_INT_10_10_10_2}, and
22118 @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
22121 Specifies a pointer to the image data in memory.
22125 Texturing maps a portion of a specified texture image onto each
22126 graphical primitive for which texturing is enabled. To enable and
22127 disable three-dimensional texturing, call @code{glEnable} and
22128 @code{glDisable} with argument @code{GL_TEXTURE_3D}.
22130 @code{glTexSubImage3D} redefines a contiguous subregion of an existing
22131 three-dimensional texture image. The texels referenced by @var{data}
22132 replace the portion of the existing texture array with x indices
22133 @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive, y indices
22134 @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive, and z
22135 indices @var{zoffset} and @r{@var{zoffset}+@var{depth}-1}, inclusive.
22136 This region may not include any texels outside the range of the texture
22137 array as it was originally specified. It is not an error to specify a
22138 subtexture with zero width, height, or depth but such a specification
22141 If a non-zero named buffer object is bound to the
22142 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
22143 texture image is specified, @var{data} is treated as a byte offset into
22144 the buffer object's data store.
22146 @code{GL_INVALID_ENUM} is generated if /@var{target} is not
22147 @code{GL_TEXTURE_3D}.
22149 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
22152 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
22155 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
22156 and @var{format} is not @code{GL_COLOR_INDEX}.
22158 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
22160 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
22161 @r{@var{log}_2}@var{max}, where @var{max} is the returned value of
22162 @code{GL_MAX_TEXTURE_SIZE}.
22164 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}},
22165 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)},
22166 @r{@var{yoffset}<-@var{b}}, or
22167 @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, or
22168 @r{@var{zoffset}<-@var{b}}, or
22169 @r{(@var{zoffset}+@var{depth},)>(@var{d}-@var{b},)}, where @r{@var{w}}
22170 is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the
22171 @code{GL_TEXTURE_HEIGHT}, @r{@var{d}} is the @code{GL_TEXTURE_DEPTH} and
22172 @r{@var{b}} is the border width of the texture image being modified.
22173 Note that @r{@var{w}}, @r{@var{h}}, and @r{@var{d}} include twice the
22176 @code{GL_INVALID_VALUE} is generated if @var{width}, @var{height}, or
22177 @var{depth} is less than 0.
22179 @code{GL_INVALID_OPERATION} is generated if the texture array has not
22180 been defined by a previous @code{glTexImage3D} operation.
22182 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
22183 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
22184 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
22185 and @var{format} is not @code{GL_RGB}.
22187 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
22188 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
22189 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
22190 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
22191 @code{GL_UNSIGNED_INT_10_10_10_2}, or
22192 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
22193 @code{GL_RGBA} nor @code{GL_BGRA}.
22195 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
22196 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
22197 object's data store is currently mapped.
22199 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
22200 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
22201 would be unpacked from the buffer object such that the memory reads
22202 required would exceed the data store size.
22204 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
22205 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
22206 is not evenly divisible into the number of bytes needed to store in
22207 memory a datum indicated by @var{type}.
22209 @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage3D} is
22210 executed between the execution of @code{glBegin} and the corresponding
22211 execution of @code{glEnd}.
22215 @deftypefun void glTranslated x y z
22216 @deftypefunx void glTranslatef x y z
22217 Multiply the current matrix by a translation matrix.
22223 Specify the @var{x}, @var{y}, and @var{z} coordinates of a translation
22228 @code{glTranslate} produces a translation by
22229 @r{(@var{x},@var{y}@var{z})}. The current matrix (see
22230 @code{glMatrixMode}) is multiplied by this translation matrix, with the
22231 product replacing the current matrix, as if @code{glMultMatrix} were
22232 called with the following matrix for its argument:
22234 @r{((1 0 0 @var{x}), (0 1 0 @var{y}), (0 0 1 @var{z}), (0 0 0 1),)}
22238 If the matrix mode is either @code{GL_MODELVIEW} or
22239 @code{GL_PROJECTION}, all objects drawn after a call to
22240 @code{glTranslate} are translated.
22242 Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the
22243 untranslated coordinate system.
22245 @code{GL_INVALID_OPERATION} is generated if @code{glTranslate} is
22246 executed between the execution of @code{glBegin} and the corresponding
22247 execution of @code{glEnd}.
22251 @deftypefun void glUniform1f location v0
22252 @deftypefunx void glUniform2f location v0 v1
22253 @deftypefunx void glUniform3f location v0 v1 v2
22254 @deftypefunx void glUniform4f location v0 v1 v2 v3
22255 @deftypefunx void glUniform1i location v0
22256 @deftypefunx void glUniform2i location v0 v1
22257 @deftypefunx void glUniform3i location v0 v1 v2
22258 @deftypefunx void glUniform4i location v0 v1 v2 v3
22259 @deftypefunx void glUniform1fv location count value
22260 @deftypefunx void glUniform2fv location count value
22261 @deftypefunx void glUniform3fv location count value
22262 @deftypefunx void glUniform4fv location count value
22263 @deftypefunx void glUniform1iv location count value
22264 @deftypefunx void glUniform2iv location count value
22265 @deftypefunx void glUniform3iv location count value
22266 @deftypefunx void glUniform4iv location count value
22267 @deftypefunx void glUniformMatrix2fv location count transpose value
22268 @deftypefunx void glUniformMatrix3fv location count transpose value
22269 @deftypefunx void glUniformMatrix4fv location count transpose value
22270 @deftypefunx void glUniformMatrix2x3fv location count transpose value
22271 @deftypefunx void glUniformMatrix3x2fv location count transpose value
22272 @deftypefunx void glUniformMatrix2x4fv location count transpose value
22273 @deftypefunx void glUniformMatrix4x2fv location count transpose value
22274 @deftypefunx void glUniformMatrix3x4fv location count transpose value
22275 @deftypefunx void glUniformMatrix4x3fv location count transpose value
22276 Specify the value of a uniform variable for the current program object.
22279 @item @var{location}
22280 Specifies the location of the uniform variable to be modified.
22282 @item @var{v0}, @var{v1}, @var{v2}, @var{v3}
22283 Specifies the new values to be used for the specified uniform variable.
22287 @code{glUniform} modifies the value of a uniform variable or a uniform
22288 variable array. The location of the uniform variable to be modified is
22289 specified by @var{location}, which should be a value returned by
22290 @code{glGetUniformLocation}. @code{glUniform} operates on the program
22291 object that was made part of current state by calling
22292 @code{glUseProgram}.
22294 The commands @code{glUniform@{1|2|3|4@}@{f|i@}} are used to change the
22295 value of the uniform variable specified by @var{location} using the
22296 values passed as arguments. The number specified in the command should
22297 match the number of components in the data type of the specified uniform
22298 variable (e.g., @code{1} for float, int, bool; @code{2} for vec2, ivec2,
22299 bvec2, etc.). The suffix @code{f} indicates that floating-point values
22300 are being passed; the suffix @code{i} indicates that integer values are
22301 being passed, and this type should also match the data type of the
22302 specified uniform variable. The @code{i} variants of this function
22303 should be used to provide values for uniform variables defined as int,
22304 ivec2, ivec3, ivec4, or arrays of these. The @code{f} variants should
22305 be used to provide values for uniform variables of type float, vec2,
22306 vec3, vec4, or arrays of these. Either the @code{i} or the @code{f}
22307 variants may be used to provide values for uniform variables of type
22308 bool, bvec2, bvec3, bvec4, or arrays of these. The uniform variable
22309 will be set to false if the input value is 0 or 0.0f, and it will be set
22312 All active uniform variables defined in a program object are initialized
22313 to 0 when the program object is linked successfully. They retain the
22314 values assigned to them by a call to @code{glUniform } until the next
22315 successful link operation occurs on the program object, when they are
22316 once again initialized to 0.
22318 The commands @code{glUniform@{1|2|3|4@}@{f|i@}v} can be used to modify a
22319 single uniform variable or a uniform variable array. These commands
22320 pass a count and a pointer to the values to be loaded into a uniform
22321 variable or a uniform variable array. A count of 1 should be used if
22322 modifying the value of a single uniform variable, and a count of 1 or
22323 greater can be used to modify an entire array or part of an array. When
22324 loading @var{n} elements starting at an arbitrary position @var{m} in a
22325 uniform variable array, elements @var{m} + @var{n} - 1 in the array will
22326 be replaced with the new values. If @var{m} + @var{n} - 1 is larger
22327 than the size of the uniform variable array, values for all array
22328 elements beyond the end of the array will be ignored. The number
22329 specified in the name of the command indicates the number of components
22330 for each element in @var{value}, and it should match the number of
22331 components in the data type of the specified uniform variable (e.g.,
22332 @code{1} for float, int, bool; @code{2} for vec2, ivec2, bvec2, etc.).
22333 The data type specified in the name of the command must match the data
22334 type for the specified uniform variable as described previously for
22335 @code{glUniform@{1|2|3|4@}@{f|i@}}.
22337 For uniform variable arrays, each element of the array is considered to
22338 be of the type indicated in the name of the command (e.g.,
22339 @code{glUniform3f} or @code{glUniform3fv} can be used to load a uniform
22340 variable array of type vec3). The number of elements of the uniform
22341 variable array to be modified is specified by @var{count}
22343 The commands @code{glUniformMatrix@{2|3|4|2x3|3x2|2x4|4x2|3x4|4x3@}fv}
22344 are used to modify a matrix or an array of matrices. The numbers in the
22345 command name are interpreted as the dimensionality of the matrix. The
22346 number @code{2} indicates a 2 × 2 matrix (i.e., 4 values), the number
22347 @code{3} indicates a 3 × 3 matrix (i.e., 9 values), and the number
22348 @code{4} indicates a 4 × 4 matrix (i.e., 16 values). Non-square matrix
22349 dimensionality is explicit, with the first number representing the
22350 number of columns and the second number representing the number of rows.
22351 For example, @code{2x4} indicates a 2 × 4 matrix with 2 columns and 4
22352 rows (i.e., 8 values). If @var{transpose} is @code{GL_FALSE}, each
22353 matrix is assumed to be supplied in column major order. If
22354 @var{transpose} is @code{GL_TRUE}, each matrix is assumed to be supplied
22355 in row major order. The @var{count} argument indicates the number of
22356 matrices to be passed. A count of 1 should be used if modifying the
22357 value of a single matrix, and a count greater than 1 can be used to
22358 modify an array of matrices.
22360 @code{GL_INVALID_OPERATION} is generated if there is no current program
22363 @code{GL_INVALID_OPERATION} is generated if the size of the uniform
22364 variable declared in the shader does not match the size indicated by the
22365 @code{glUniform} command.
22367 @code{GL_INVALID_OPERATION} is generated if one of the integer variants
22368 of this function is used to load a uniform variable of type float, vec2,
22369 vec3, vec4, or an array of these, or if one of the floating-point
22370 variants of this function is used to load a uniform variable of type
22371 int, ivec2, ivec3, or ivec4, or an array of these.
22373 @code{GL_INVALID_OPERATION} is generated if @var{location} is an invalid
22374 uniform location for the current program object and @var{location} is
22377 @code{GL_INVALID_VALUE} is generated if @var{count} is less than 0.
22379 @code{GL_INVALID_OPERATION} is generated if @var{count} is greater than
22380 1 and the indicated uniform variable is not an array variable.
22382 @code{GL_INVALID_OPERATION} is generated if a sampler is loaded using a
22383 command other than @code{glUniform1i} and @code{glUniform1iv}.
22385 @code{GL_INVALID_OPERATION} is generated if @code{glUniform} is executed
22386 between the execution of @code{glBegin} and the corresponding execution
22391 @deftypefun void glUseProgram program
22392 Installs a program object as part of current rendering state.
22395 @item @var{program}
22396 Specifies the handle of the program object whose executables are to be
22397 used as part of current rendering state.
22401 @code{glUseProgram} installs the program object specified by
22402 @var{program} as part of current rendering state. One or more
22403 executables are created in a program object by successfully attaching
22404 shader objects to it with @code{glAttachShader}, successfully compiling
22405 the shader objects with @code{glCompileShader}, and successfully linking
22406 the program object with @code{glLinkProgram}.
22408 A program object will contain an executable that will run on the vertex
22409 processor if it contains one or more shader objects of type
22410 @code{GL_VERTEX_SHADER} that have been successfully compiled and linked.
22411 Similarly, a program object will contain an executable that will run on
22412 the fragment processor if it contains one or more shader objects of type
22413 @code{GL_FRAGMENT_SHADER} that have been successfully compiled and
22416 Successfully installing an executable on a programmable processor will
22417 cause the corresponding fixed functionality of OpenGL to be disabled.
22418 Specifically, if an executable is installed on the vertex processor, the
22419 OpenGL fixed functionality will be disabled as follows.
22423 The modelview matrix is not applied to vertex coordinates.
22426 The projection matrix is not applied to vertex coordinates.
22429 The texture matrices are not applied to texture coordinates.
22432 Normals are not transformed to eye coordinates.
22435 Normals are not rescaled or normalized.
22438 Normalization of @code{GL_AUTO_NORMAL} evaluated normals is not
22442 Texture coordinates are not generated automatically.
22445 Per-vertex lighting is not performed.
22448 Color material computations are not performed.
22451 Color index lighting is not performed.
22454 This list also applies when setting the current raster position.
22458 The executable that is installed on the vertex processor is expected to
22459 implement any or all of the desired functionality from the preceding
22460 list. Similarly, if an executable is installed on the fragment
22461 processor, the OpenGL fixed functionality will be disabled as follows.
22465 Texture environment and texture functions are not applied.
22468 Texture application is not applied.
22471 Color sum is not applied.
22474 Fog is not applied.
22478 Again, the fragment shader that is installed is expected to implement
22479 any or all of the desired functionality from the preceding list.
22481 While a program object is in use, applications are free to modify
22482 attached shader objects, compile attached shader objects, attach
22483 additional shader objects, and detach or delete shader objects. None of
22484 these operations will affect the executables that are part of the
22485 current state. However, relinking the program object that is currently
22486 in use will install the program object as part of the current rendering
22487 state if the link operation was successful (see @code{glLinkProgram} ).
22488 If the program object currently in use is relinked unsuccessfully, its
22489 link status will be set to @code{GL_FALSE}, but the executables and
22490 associated state will remain part of the current state until a
22491 subsequent call to @code{glUseProgram} removes it from use. After it is
22492 removed from use, it cannot be made part of current state until it has
22493 been successfully relinked.
22495 If @var{program} contains shader objects of type @code{GL_VERTEX_SHADER}
22496 but it does not contain shader objects of type
22497 @code{GL_FRAGMENT_SHADER}, an executable will be installed on the vertex
22498 processor, but fixed functionality will be used for fragment processing.
22499 Similarly, if @var{program} contains shader objects of type
22500 @code{GL_FRAGMENT_SHADER} but it does not contain shader objects of type
22501 @code{GL_VERTEX_SHADER}, an executable will be installed on the fragment
22502 processor, but fixed functionality will be used for vertex processing.
22503 If @var{program} is 0, the programmable processors will be disabled, and
22504 fixed functionality will be used for both vertex and fragment
22507 @code{GL_INVALID_VALUE} is generated if @var{program} is neither 0 nor a
22508 value generated by OpenGL.
22510 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
22513 @code{GL_INVALID_OPERATION} is generated if @var{program} could not be
22514 made part of current state.
22516 @code{GL_INVALID_OPERATION} is generated if @code{glUseProgram} is
22517 executed between the execution of @code{glBegin} and the corresponding
22518 execution of @code{glEnd}.
22522 @deftypefun void glValidateProgram program
22523 Validates a program object.
22526 @item @var{program}
22527 Specifies the handle of the program object to be validated.
22531 @code{glValidateProgram} checks to see whether the executables contained
22532 in @var{program} can execute given the current OpenGL state. The
22533 information generated by the validation process will be stored in
22534 @var{program}'s information log. The validation information may consist
22535 of an empty string, or it may be a string containing information about
22536 how the current program object interacts with the rest of current OpenGL
22537 state. This provides a way for OpenGL implementers to convey more
22538 information about why the current program is inefficient, suboptimal,
22539 failing to execute, and so on.
22541 The status of the validation operation will be stored as part of the
22542 program object's state. This value will be set to @code{GL_TRUE} if the
22543 validation succeeded, and @code{GL_FALSE} otherwise. It can be queried
22544 by calling @code{glGetProgram} with arguments @var{program} and
22545 @code{GL_VALIDATE_STATUS}. If validation is successful, @var{program}
22546 is guaranteed to execute given the current state. Otherwise,
22547 @var{program} is guaranteed to not execute.
22549 This function is typically useful only during application development.
22550 The informational string stored in the information log is completely
22551 implementation dependent; therefore, an application should not expect
22552 different OpenGL implementations to produce identical information
22555 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
22556 generated by OpenGL.
22558 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
22561 @code{GL_INVALID_OPERATION} is generated if @code{glValidateProgram} is
22562 executed between the execution of @code{glBegin} and the corresponding
22563 execution of @code{glEnd}.
22567 @deftypefun void glVertexAttribPointer index size type normalized stride pointer
22568 Define an array of generic vertex attribute data.
22572 Specifies the index of the generic vertex attribute to be modified.
22575 Specifies the number of components per generic vertex attribute. Must
22576 be 1, 2, 3, or 4. The initial value is 4.
22579 Specifies the data type of each component in the array. Symbolic
22580 constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
22581 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
22582 @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is
22585 @item @var{normalized}
22586 Specifies whether fixed-point data values should be normalized
22587 (@code{GL_TRUE}) or converted directly as fixed-point values
22588 (@code{GL_FALSE}) when they are accessed.
22591 Specifies the byte offset between consecutive generic vertex attributes.
22592 If @var{stride} is 0, the generic vertex attributes are understood to be
22593 tightly packed in the array. The initial value is 0.
22595 @item @var{pointer}
22596 Specifies a pointer to the first component of the first generic vertex
22597 attribute in the array. The initial value is 0.
22601 @code{glVertexAttribPointer} specifies the location and data format of
22602 the array of generic vertex attributes at index @var{index} to use when
22603 rendering. @var{size} specifies the number of components per attribute
22604 and must be 1, 2, 3, or 4. @var{type} specifies the data type of each
22605 component, and @var{stride} specifies the byte stride from one attribute
22606 to the next, allowing vertices and attributes to be packed into a single
22607 array or stored in separate arrays. If set to @code{GL_TRUE},
22608 @var{normalized} indicates that values stored in an integer format are
22609 to be mapped to the range [-1,1] (for signed values) or [0,1] (for
22610 unsigned values) when they are accessed and converted to floating point.
22611 Otherwise, values will be converted to floats directly without
22614 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
22615 target (see @code{glBindBuffer}) while a generic vertex attribute array
22616 is specified, @var{pointer} is treated as a byte offset into the buffer
22617 object's data store. Also, the buffer object binding
22618 (@code{GL_ARRAY_BUFFER_BINDING}) is saved as generic vertex attribute
22619 array client-side state (@code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING})
22620 for index @var{index}.
22622 When a generic vertex attribute array is specified, @var{size},
22623 @var{type}, @var{normalized}, @var{stride}, and @var{pointer} are saved
22624 as client-side state, in addition to the current vertex array buffer
22627 To enable and disable a generic vertex attribute array, call
22628 @code{glEnableVertexAttribArray} and @code{glDisableVertexAttribArray}
22629 with @var{index}. If enabled, the generic vertex attribute array is
22630 used when @code{glArrayElement}, @code{glDrawArrays},
22631 @code{glMultiDrawArrays}, @code{glDrawElements},
22632 @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called.
22634 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
22635 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
22637 @code{GL_INVALID_VALUE} is generated if @var{size} is not 1, 2, 3, or 4.
22639 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
22642 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
22646 @deftypefun void glVertexAttrib1f index v0
22647 @deftypefunx void glVertexAttrib1s index v0
22648 @deftypefunx void glVertexAttrib1d index v0
22649 @deftypefunx void glVertexAttrib2f index v0 v1
22650 @deftypefunx void glVertexAttrib2s index v0 v1
22651 @deftypefunx void glVertexAttrib2d index v0 v1
22652 @deftypefunx void glVertexAttrib3f index v0 v1 v2
22653 @deftypefunx void glVertexAttrib3s index v0 v1 v2
22654 @deftypefunx void glVertexAttrib3d index v0 v1 v2
22655 @deftypefunx void glVertexAttrib4f index v0 v1 v2 v3
22656 @deftypefunx void glVertexAttrib4s index v0 v1 v2 v3
22657 @deftypefunx void glVertexAttrib4d index v0 v1 v2 v3
22658 @deftypefunx void glVertexAttrib4Nub index v0 v1 v2 v3
22659 @deftypefunx void glVertexAttrib1fv index v
22660 @deftypefunx void glVertexAttrib1sv index v
22661 @deftypefunx void glVertexAttrib1dv index v
22662 @deftypefunx void glVertexAttrib2fv index v
22663 @deftypefunx void glVertexAttrib2sv index v
22664 @deftypefunx void glVertexAttrib2dv index v
22665 @deftypefunx void glVertexAttrib3fv index v
22666 @deftypefunx void glVertexAttrib3sv index v
22667 @deftypefunx void glVertexAttrib3dv index v
22668 @deftypefunx void glVertexAttrib4fv index v
22669 @deftypefunx void glVertexAttrib4sv index v
22670 @deftypefunx void glVertexAttrib4dv index v
22671 @deftypefunx void glVertexAttrib4iv index v
22672 @deftypefunx void glVertexAttrib4bv index v
22673 @deftypefunx void glVertexAttrib4ubv index v
22674 @deftypefunx void glVertexAttrib4usv index v
22675 @deftypefunx void glVertexAttrib4uiv index v
22676 @deftypefunx void glVertexAttrib4Nbv index v
22677 @deftypefunx void glVertexAttrib4Nsv index v
22678 @deftypefunx void glVertexAttrib4Niv index v
22679 @deftypefunx void glVertexAttrib4Nubv index v
22680 @deftypefunx void glVertexAttrib4Nusv index v
22681 @deftypefunx void glVertexAttrib4Nuiv index v
22682 Specifies the value of a generic vertex attribute.
22686 Specifies the index of the generic vertex attribute to be modified.
22688 @item @var{v0}, @var{v1}, @var{v2}, @var{v3}
22689 Specifies the new values to be used for the specified vertex attribute.
22693 OpenGL defines a number of standard vertex attributes that applications
22694 can modify with standard API entry points (color, normal, texture
22695 coordinates, etc.). The @code{glVertexAttrib} family of entry points
22696 allows an application to pass generic vertex attributes in numbered
22699 Generic attributes are defined as four-component values that are
22700 organized into an array. The first entry of this array is numbered 0,
22701 and the size of the array is specified by the implementation-dependent
22702 constant @code{GL_MAX_VERTEX_ATTRIBS}. Individual elements of this
22703 array can be modified with a @code{glVertexAttrib} call that specifies
22704 the index of the element to be modified and a value for that element.
22706 These commands can be used to specify one, two, three, or all four
22707 components of the generic vertex attribute specified by @var{index}. A
22708 @code{1} in the name of the command indicates that only one value is
22709 passed, and it will be used to modify the first component of the generic
22710 vertex attribute. The second and third components will be set to 0, and
22711 the fourth component will be set to 1. Similarly, a @code{2} in the
22712 name of the command indicates that values are provided for the first two
22713 components, the third component will be set to 0, and the fourth
22714 component will be set to 1. A @code{3} in the name of the command
22715 indicates that values are provided for the first three components and
22716 the fourth component will be set to 1, whereas a @code{4} in the name
22717 indicates that values are provided for all four components.
22719 The letters @code{s}, @code{f}, @code{i}, @code{d}, @code{ub},
22720 @code{us}, and @code{ui} indicate whether the arguments are of type
22721 short, float, int, double, unsigned byte, unsigned short, or unsigned
22722 int. When @code{v} is appended to the name, the commands can take a
22723 pointer to an array of such values. The commands containing @code{N}
22724 indicate that the arguments will be passed as fixed-point values that
22725 are scaled to a normalized range according to the component conversion
22726 rules defined by the OpenGL specification. Signed values are understood
22727 to represent fixed-point values in the range [-1,1], and unsigned values
22728 are understood to represent fixed-point values in the range [0,1].
22730 OpenGL Shading Language attribute variables are allowed to be of type
22731 mat2, mat3, or mat4. Attributes of these types may be loaded using the
22732 @code{glVertexAttrib} entry points. Matrices must be loaded into
22733 successive generic attribute slots in column major order, with one
22734 column of the matrix in each generic attribute slot.
22736 A user-defined attribute variable declared in a vertex shader can be
22737 bound to a generic attribute index by calling
22738 @code{glBindAttribLocation}. This allows an application to use more
22739 descriptive variable names in a vertex shader. A subsequent change to
22740 the specified generic vertex attribute will be immediately reflected as
22741 a change to the corresponding attribute variable in the vertex shader.
22743 The binding between a generic vertex attribute index and a user-defined
22744 attribute variable in a vertex shader is part of the state of a program
22745 object, but the current value of the generic vertex attribute is not.
22746 The value of each generic vertex attribute is part of current state,
22747 just like standard vertex attributes, and it is maintained even if a
22748 different program object is used.
22750 An application may freely modify generic vertex attributes that are not
22751 bound to a named vertex shader attribute variable. These values are
22752 simply maintained as part of current state and will not be accessed by
22753 the vertex shader. If a generic vertex attribute bound to an attribute
22754 variable in a vertex shader is not updated while the vertex shader is
22755 executing, the vertex shader will repeatedly use the current value for
22756 the generic vertex attribute.
22758 The generic vertex attribute with index 0 is the same as the vertex
22759 position attribute previously defined by OpenGL. A @code{glVertex2},
22760 @code{glVertex3}, or @code{glVertex4} command is completely equivalent
22761 to the corresponding @code{glVertexAttrib} command with an index
22762 argument of 0. A vertex shader can access generic vertex attribute 0 by
22763 using the built-in attribute variable @var{gl_Vertex}. There are no
22764 current values for generic vertex attribute 0. This is the only generic
22765 vertex attribute with this property; calls to set other standard vertex
22766 attributes can be freely mixed with calls to set any of the other
22767 generic vertex attributes.
22769 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
22770 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
22774 @deftypefun void glVertexPointer size type stride pointer
22775 Define an array of vertex data.
22779 Specifies the number of coordinates per vertex. Must be 2, 3, or 4. The
22780 initial value is 4.
22783 Specifies the data type of each coordinate in the array. Symbolic
22784 constants @code{GL_SHORT}, @code{GL_INT}, @code{GL_FLOAT}, or
22785 @code{GL_DOUBLE} are accepted. The initial value is @code{GL_FLOAT}.
22788 Specifies the byte offset between consecutive vertices. If @var{stride}
22789 is 0, the vertices are understood to be tightly packed in the array. The
22790 initial value is 0.
22792 @item @var{pointer}
22793 Specifies a pointer to the first coordinate of the first vertex in the
22794 array. The initial value is 0.
22798 @code{glVertexPointer} specifies the location and data format of an
22799 array of vertex coordinates to use when rendering. @var{size} specifies
22800 the number of coordinates per vertex, and must be 2, 3, or 4. @var{type}
22801 specifies the data type of each coordinate, and @var{stride} specifies
22802 the byte stride from one vertex to the next, allowing vertices and
22803 attributes to be packed into a single array or stored in separate
22804 arrays. (Single-array storage may be more efficient on some
22805 implementations; see @code{glInterleavedArrays}.)
22807 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
22808 target (see @code{glBindBuffer}) while a vertex array is specified,
22809 @var{pointer} is treated as a byte offset into the buffer object's data
22810 store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING})
22811 is saved as vertex array client-side state
22812 (@code{GL_VERTEX_ARRAY_BUFFER_BINDING}).
22814 When a vertex array is specified, @var{size}, @var{type}, @var{stride},
22815 and @var{pointer} are saved as client-side state, in addition to the
22816 current vertex array buffer object binding.
22818 To enable and disable the vertex array, call @code{glEnableClientState}
22819 and @code{glDisableClientState} with the argument
22820 @code{GL_VERTEX_ARRAY}. If enabled, the vertex array is used when
22821 @code{glArrayElement}, @code{glDrawArrays}, @code{glMultiDrawArrays},
22822 @code{glDrawElements}, @code{glMultiDrawElements}, or
22823 @code{glDrawRangeElements} is called.
22825 @code{GL_INVALID_VALUE} is generated if @var{size} is not 2, 3, or 4.
22827 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
22830 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
22834 @deftypefun void glVertex2s x y
22835 @deftypefunx void glVertex2i x y
22836 @deftypefunx void glVertex2f x y
22837 @deftypefunx void glVertex2d x y
22838 @deftypefunx void glVertex3s x y z
22839 @deftypefunx void glVertex3i x y z
22840 @deftypefunx void glVertex3f x y z
22841 @deftypefunx void glVertex3d x y z
22842 @deftypefunx void glVertex4s x y z w
22843 @deftypefunx void glVertex4i x y z w
22844 @deftypefunx void glVertex4f x y z w
22845 @deftypefunx void glVertex4d x y z w
22846 @deftypefunx void glVertex2sv v
22847 @deftypefunx void glVertex2iv v
22848 @deftypefunx void glVertex2fv v
22849 @deftypefunx void glVertex2dv v
22850 @deftypefunx void glVertex3sv v
22851 @deftypefunx void glVertex3iv v
22852 @deftypefunx void glVertex3fv v
22853 @deftypefunx void glVertex3dv v
22854 @deftypefunx void glVertex4sv v
22855 @deftypefunx void glVertex4iv v
22856 @deftypefunx void glVertex4fv v
22857 @deftypefunx void glVertex4dv v
22865 Specify @var{x}, @var{y}, @var{z}, and @var{w} coordinates of a vertex.
22866 Not all parameters are present in all forms of the command.
22870 @code{glVertex} commands are used within @code{glBegin}/@code{glEnd}
22871 pairs to specify point, line, and polygon vertices. The current color,
22872 normal, texture coordinates, and fog coordinate are associated with the
22873 vertex when @code{glVertex} is called.
22875 When only @r{@var{x}} and @r{@var{y}} are specified, @r{@var{z}}
22876 defaults to 0 and @r{@var{w}} defaults to 1. When @r{@var{x}},
22877 @r{@var{y}}, and @r{@var{z}} are specified, @r{@var{w}} defaults to 1.
22881 @deftypefun void glViewport x y width height
22887 Specify the lower left corner of the viewport rectangle, in pixels. The
22888 initial value is (0,0).
22891 @itemx @var{height}
22892 Specify the width and height of the viewport. When a GL context is
22893 first attached to a window, @var{width} and @var{height} are set to the
22894 dimensions of that window.
22898 @code{glViewport} specifies the affine transformation of @r{@var{x}} and
22899 @r{@var{y}} from normalized device coordinates to window coordinates.
22900 Let @r{(@var{x}_@var{nd},@var{y}_@var{nd})} be normalized device
22901 coordinates. Then the window coordinates
22902 @r{(@var{x}_@var{w},@var{y}_@var{w})} are computed as follows:
22904 @r{@var{x}_@var{w}=(@var{x}_@var{nd}+1,)(@var{width}/2,)+@var{x}}
22906 @r{@var{y}_@var{w}=(@var{y}_@var{nd}+1,)(@var{height}/2,)+@var{y}}
22908 Viewport width and height are silently clamped to a range that depends
22909 on the implementation. To query this range, call @code{glGet} with
22910 argument @code{GL_MAX_VIEWPORT_DIMS}.
22912 @code{GL_INVALID_VALUE} is generated if either @var{width} or
22913 @var{height} is negative.
22915 @code{GL_INVALID_OPERATION} is generated if @code{glViewport} is
22916 executed between the execution of @code{glBegin} and the corresponding
22917 execution of @code{glEnd}.
22921 @deftypefun void glWindowPos2s x y
22922 @deftypefunx void glWindowPos2i x y
22923 @deftypefunx void glWindowPos2f x y
22924 @deftypefunx void glWindowPos2d x y
22925 @deftypefunx void glWindowPos3s x y z
22926 @deftypefunx void glWindowPos3i x y z
22927 @deftypefunx void glWindowPos3f x y z
22928 @deftypefunx void glWindowPos3d x y z
22929 @deftypefunx void glWindowPos2sv v
22930 @deftypefunx void glWindowPos2iv v
22931 @deftypefunx void glWindowPos2fv v
22932 @deftypefunx void glWindowPos2dv v
22933 @deftypefunx void glWindowPos3sv v
22934 @deftypefunx void glWindowPos3iv v
22935 @deftypefunx void glWindowPos3fv v
22936 @deftypefunx void glWindowPos3dv v
22937 Specify the raster position in window coordinates for pixel operations.
22943 Specify the @r{@var{x}}, @r{@var{y}}, @r{@var{z}} coordinates for the
22948 The GL maintains a 3D position in window coordinates. This position,
22949 called the raster position, is used to position pixel and bitmap write
22950 operations. It is maintained with subpixel accuracy. See
22951 @code{glBitmap}, @code{glDrawPixels}, and @code{glCopyPixels}.
22953 @code{glWindowPos2} specifies the @r{@var{x}} and @r{@var{y}}
22954 coordinates, while @r{@var{z}} is implicitly set to 0.
22955 @code{glWindowPos3} specifies all three coordinates. The @r{@var{w}}
22956 coordinate of the current raster position is always set to 1.0.
22958 @code{glWindowPos} directly updates the @r{@var{x}} and @r{@var{y}}
22959 coordinates of the current raster position with the values specified.
22960 That is, the values are neither transformed by the current modelview and
22961 projection matrices, nor by the viewport-to-window transform. The
22962 @r{@var{z}} coordinate of the current raster position is updated in the
22965 @r{@var{z}=@{(@var{n}), (@var{f}),
22966 (@var{n}+@var{z}×(@var{f}-@var{n},),)(@var{if}@var{z}<=0),
22967 (@var{if}@var{z}>=1), (@code{otherwise},),}
22971 where @r{@var{n}} is @code{GL_DEPTH_RANGE}'s near value, and @r{@var{f}}
22972 is @code{GL_DEPTH_RANGE}'s far value. See @code{glDepthRange}.
22974 The specified coordinates are not clip-tested, causing the raster
22975 position to always be valid.
22977 The current raster position also includes some associated color data and
22978 texture coordinates. If lighting is enabled, then
22979 @code{GL_CURRENT_RASTER_COLOR} (in RGBA mode) or
22980 @code{GL_CURRENT_RASTER_INDEX} (in color index mode) is set to the color
22981 produced by the lighting calculation (see @code{glLight},
22982 @code{glLightModel}, and @code{glShadeModel}). If lighting is disabled,
22983 current color (in RGBA mode, state variable @code{GL_CURRENT_COLOR}) or
22984 color index (in color index mode, state variable
22985 @code{GL_CURRENT_INDEX}) is used to update the current raster color.
22986 @code{GL_CURRENT_RASTER_SECONDARY_COLOR} (in RGBA mode) is likewise
22989 Likewise, @code{GL_CURRENT_RASTER_TEXTURE_COORDS} is updated as a
22990 function of @code{GL_CURRENT_TEXTURE_COORDS}, based on the texture
22991 matrix and the texture generation functions (see @code{glTexGen}). The
22992 @code{GL_CURRENT_RASTER_DISTANCE} is set to the
22993 @code{GL_CURRENT_FOG_COORD}.
22997 @code{GL_INVALID_OPERATION} is generated if @code{glWindowPos} is
22998 executed between the execution of @code{glBegin} and the corresponding
22999 execution of @code{glEnd}.
23004 @c %end of fragment