4 The functions from this section may be had by loading the module:
7 (use-modules (figl gl low-level)
11 This section of the manual was derived from the upstream OpenGL
12 documentation. Each function's documentation has its own copyright
13 statement; for full details, see the upstream documentation. The
14 copyright notices and licenses present in this section are as follows.
16 Copyright @copyright{} 1991-2006 Silicon Graphics, Inc. This document is
17 licensed under the SGI Free Software B License. For details, see
18 @uref{http://oss.sgi.com/projects/FreeB/,http://oss.sgi.com/projects/FreeB/}.
20 Copyright @copyright{} 2003-2005 3Dlabs Inc. Ltd. This material may be
21 distributed subject to the terms and conditions set forth in the Open
22 Publication License, v 1.0, 8 June 1999.
23 @uref{http://opencontent.org/openpub/,http://opencontent.org/openpub/}.
25 Copyright @copyright{} 2005 Addison-Wesley. This material may be
26 distributed subject to the terms and conditions set forth in the Open
27 Publication License, v 1.0, 8 June 1999.
28 @uref{http://opencontent.org/openpub/,http://opencontent.org/openpub/}.
30 Copyright @copyright{} 2006 Khronos Group. This material may be
31 distributed subject to the terms and conditions set forth in the Open
32 Publication License, v 1.0, 8 June 1999.
33 @uref{http://opencontent.org/openpub/,http://opencontent.org/openpub/}.
37 @deftypefun void glAccum op value
38 Operate on the accumulation buffer.
42 Specifies the accumulation buffer operation. Symbolic constants
43 @code{GL_ACCUM}, @code{GL_LOAD}, @code{GL_ADD}, @code{GL_MULT}, and
44 @code{GL_RETURN} are accepted.
47 Specifies a floating-point value used in the accumulation buffer
48 operation. @var{op} determines how @var{value} is used.
52 The accumulation buffer is an extended-range color buffer. Images are
53 not rendered into it. Rather, images rendered into one of the color
54 buffers are added to the contents of the accumulation buffer after
55 rendering. Effects such as antialiasing (of points, lines, and
56 polygons), motion blur, and depth of field can be created by
57 accumulating images generated with different transformation matrices.
59 Each pixel in the accumulation buffer consists of red, green, blue, and
60 alpha values. The number of bits per component in the accumulation
61 buffer depends on the implementation. You can examine this number by
62 calling @code{glGetIntegerv} four times, with arguments
63 @code{GL_ACCUM_RED_BITS}, @code{GL_ACCUM_GREEN_BITS},
64 @code{GL_ACCUM_BLUE_BITS}, and @code{GL_ACCUM_ALPHA_BITS}. Regardless of
65 the number of bits per component, the range of values stored by each
66 component is @r{[-1,1]}. The accumulation buffer pixels are mapped
67 one-to-one with frame buffer pixels.
69 @code{glAccum} operates on the accumulation buffer. The first argument,
70 @var{op}, is a symbolic constant that selects an accumulation buffer
71 operation. The second argument, @var{value}, is a floating-point value
72 to be used in that operation. Five operations are specified:
73 @code{GL_ACCUM}, @code{GL_LOAD}, @code{GL_ADD}, @code{GL_MULT}, and
76 All accumulation buffer operations are limited to the area of the
77 current scissor box and applied identically to the red, green, blue, and
78 alpha components of each pixel. If a @code{glAccum} operation results in
79 a value outside the range @r{[-1,1]}, the contents of an accumulation
80 buffer pixel component are undefined.
82 The operations are as follows:
86 Obtains R, G, B, and A values from the buffer currently selected for
87 reading (see @code{glReadBuffer}). Each component value is divided by
88 @r{2^@var{n}-1}, where @r{@var{n}} is the number of bits allocated to
89 each color component in the currently selected buffer. The result is a
90 floating-point value in the range @r{[0,1]}, which is multiplied by
91 @var{value} and added to the corresponding pixel component in the
92 accumulation buffer, thereby updating the accumulation buffer.
95 Similar to @code{GL_ACCUM}, except that the current value in the
96 accumulation buffer is not used in the calculation of the new value.
97 That is, the R, G, B, and A values from the currently selected buffer
98 are divided by @r{2^@var{n}-1}, multiplied by @var{value}, and then
99 stored in the corresponding accumulation buffer cell, overwriting the
103 Adds @var{value} to each R, G, B, and A in the accumulation buffer.
106 Multiplies each R, G, B, and A in the accumulation buffer by @var{value}
107 and returns the scaled component to its corresponding accumulation
110 @item @code{GL_RETURN}
111 Transfers accumulation buffer values to the color buffer or buffers
112 currently selected for writing. Each R, G, B, and A component is
113 multiplied by @var{value}, then multiplied by @r{2^@var{n}-1}, clamped
114 to the range @r{[0,2^@var{n}-1]}, and stored in the corresponding
115 display buffer cell. The only fragment operations that are applied to
116 this transfer are pixel ownership, scissor, dithering, and color
121 To clear the accumulation buffer, call @code{glClearAccum} with R, G, B,
122 and A values to set it to, then call @code{glClear} with the
123 accumulation buffer enabled.
125 @code{GL_INVALID_ENUM} is generated if @var{op} is not an accepted
128 @code{GL_INVALID_OPERATION} is generated if there is no accumulation
131 @code{GL_INVALID_OPERATION} is generated if @code{glAccum} is executed
132 between the execution of @code{glBegin} and the corresponding execution
137 @deftypefun void glActiveTexture texture
138 Select active texture unit.
142 Specifies which texture unit to make active. The number of texture units
143 is implementation dependent, but must be at least two. @var{texture}
144 must be one of @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to
145 the larger of (@code{GL_MAX_TEXTURE_COORDS} - 1) and
146 (@code{GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS} - 1). The initial value is
151 @code{glActiveTexture} selects which texture unit subsequent texture
152 state calls will affect. The number of texture units an implementation
153 supports is implementation dependent, but must be at least 2.
155 Vertex arrays are client-side GL resources, which are selected by the
156 @code{glClientActiveTexture} routine.
158 @code{GL_INVALID_ENUM} is generated if @var{texture} is not one of
159 @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to the larger of
160 (@code{GL_MAX_TEXTURE_COORDS} - 1) and
161 (@code{GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS} - 1).
165 @deftypefun void glAlphaFunc func ref
166 Specify the alpha test function.
170 Specifies the alpha comparison function. Symbolic constants
171 @code{GL_NEVER}, @code{GL_LESS}, @code{GL_EQUAL}, @code{GL_LEQUAL},
172 @code{GL_GREATER}, @code{GL_NOTEQUAL}, @code{GL_GEQUAL}, and
173 @code{GL_ALWAYS} are accepted. The initial value is @code{GL_ALWAYS}.
176 Specifies the reference value that incoming alpha values are compared
177 to. This value is clamped to the range @r{[0,1]}, where 0 represents the
178 lowest possible alpha value and 1 the highest possible value. The
179 initial reference value is 0.
183 The alpha test discards fragments depending on the outcome of a
184 comparison between an incoming fragment's alpha value and a constant
185 reference value. @code{glAlphaFunc} specifies the reference value and
186 the comparison function. The comparison is performed only if alpha
187 testing is enabled. By default, it is not enabled. (See @code{glEnable}
188 and @code{glDisable} of @code{GL_ALPHA_TEST}.)
190 @var{func} and @var{ref} specify the conditions under which the pixel is
191 drawn. The incoming alpha value is compared to @var{ref} using the
192 function specified by @var{func}. If the value passes the comparison,
193 the incoming fragment is drawn if it also passes subsequent stencil and
194 depth buffer tests. If the value fails the comparison, no change is made
195 to the frame buffer at that pixel location. The comparison functions are
199 @item @code{GL_NEVER}
203 Passes if the incoming alpha value is less than the reference value.
205 @item @code{GL_EQUAL}
206 Passes if the incoming alpha value is equal to the reference value.
208 @item @code{GL_LEQUAL}
209 Passes if the incoming alpha value is less than or equal to the
212 @item @code{GL_GREATER}
213 Passes if the incoming alpha value is greater than the reference value.
215 @item @code{GL_NOTEQUAL}
216 Passes if the incoming alpha value is not equal to the reference value.
218 @item @code{GL_GEQUAL}
219 Passes if the incoming alpha value is greater than or equal to the
222 @item @code{GL_ALWAYS}
223 Always passes (initial value).
227 @code{glAlphaFunc} operates on all pixel write operations, including
228 those resulting from the scan conversion of points, lines, polygons, and
229 bitmaps, and from pixel draw and copy operations. @code{glAlphaFunc}
230 does not affect screen clear operations.
232 @code{GL_INVALID_ENUM} is generated if @var{func} is not an accepted
235 @code{GL_INVALID_OPERATION} is generated if @code{glAlphaFunc} is
236 executed between the execution of @code{glBegin} and the corresponding
237 execution of @code{glEnd}.
241 @deftypefun GLboolean glAreTexturesResident n textures residences
242 Determine if textures are loaded in texture memory.
246 Specifies the number of textures to be queried.
249 Specifies an array containing the names of the textures to be queried.
251 @item @var{residences}
252 Specifies an array in which the texture residence status is returned.
253 The residence status of a texture named by an element of @var{textures}
254 is returned in the corresponding element of @var{residences}.
258 GL establishes a ``working set'' of textures that are resident in
259 texture memory. These textures can be bound to a texture target much
260 more efficiently than textures that are not resident.
262 @code{glAreTexturesResident} queries the texture residence status of the
263 @var{n} textures named by the elements of @var{textures}. If all the
264 named textures are resident, @code{glAreTexturesResident} returns
265 @code{GL_TRUE}, and the contents of @var{residences} are undisturbed. If
266 not all the named textures are resident, @code{glAreTexturesResident}
267 returns @code{GL_FALSE}, and detailed status is returned in the @var{n}
268 elements of @var{residences}. If an element of @var{residences} is
269 @code{GL_TRUE}, then the texture named by the corresponding element of
270 @var{textures} is resident.
272 The residence status of a single bound texture may also be queried by
273 calling @code{glGetTexParameter} with the @var{target} argument set to
274 the target to which the texture is bound, and the @var{pname} argument
275 set to @code{GL_TEXTURE_RESIDENT}. This is the only way that the
276 residence status of a default texture can be queried.
278 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
280 @code{GL_INVALID_VALUE} is generated if any element in @var{textures} is
281 0 or does not name a texture. In that case, the function returns
282 @code{GL_FALSE} and the contents of @var{residences} is indeterminate.
284 @code{GL_INVALID_OPERATION} is generated if @code{glAreTexturesResident}
285 is executed between the execution of @code{glBegin} and the
286 corresponding execution of @code{glEnd}.
290 @deftypefun void glArrayElement i
291 Render a vertex using the specified vertex array element.
295 Specifies an index into the enabled vertex data arrays.
299 @code{glArrayElement} commands are used within
300 @code{glBegin}/@code{glEnd} pairs to specify vertex and attribute data
301 for point, line, and polygon primitives. If @code{GL_VERTEX_ARRAY} is
302 enabled when @code{glArrayElement} is called, a single vertex is drawn,
303 using vertex and attribute data taken from location @var{i} of the
304 enabled arrays. If @code{GL_VERTEX_ARRAY} is not enabled, no drawing
305 occurs but the attributes corresponding to the enabled arrays are
308 Use @code{glArrayElement} to construct primitives by indexing vertex
309 data, rather than by streaming through arrays of data in first-to-last
310 order. Because each call specifies only a single vertex, it is possible
311 to explicitly specify per-primitive attributes such as a single normal
314 Changes made to array data between the execution of @code{glBegin} and
315 the corresponding execution of @code{glEnd} may affect calls to
316 @code{glArrayElement} that are made within the same
317 @code{glBegin}/@code{glEnd} period in nonsequential ways. That is, a
318 call to @code{glArrayElement} that precedes a change to array data may
319 access the changed data, and a call that follows a change to array data
320 may access original data.
322 @code{GL_INVALID_VALUE} may be generated if @var{i} is negative.
324 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
325 name is bound to an enabled array and the buffer object's data store is
330 @deftypefun void glAttachShader program shader
331 Attaches a shader object to a program object.
335 Specifies the program object to which a shader object will be attached.
338 Specifies the shader object that is to be attached.
342 In order to create an executable, there must be a way to specify the
343 list of things that will be linked together. Program objects provide
344 this mechanism. Shaders that are to be linked together in a program
345 object must first be attached to that program object.
346 @code{glAttachShader} attaches the shader object specified by
347 @var{shader} to the program object specified by @var{program}. This
348 indicates that @var{shader} will be included in link operations that
349 will be performed on @var{program}.
351 All operations that can be performed on a shader object are valid
352 whether or not the shader object is attached to a program object. It is
353 permissible to attach a shader object to a program object before source
354 code has been loaded into the shader object or before the shader object
355 has been compiled. It is permissible to attach multiple shader objects
356 of the same type because each may contain a portion of the complete
357 shader. It is also permissible to attach a shader object to more than
358 one program object. If a shader object is deleted while it is attached
359 to a program object, it will be flagged for deletion, and deletion will
360 not occur until @code{glDetachShader} is called to detach it from all
361 program objects to which it is attached.
363 @code{GL_INVALID_VALUE} is generated if either @var{program} or
364 @var{shader} is not a value generated by OpenGL.
366 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
369 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
372 @code{GL_INVALID_OPERATION} is generated if @var{shader} is already
373 attached to @var{program}.
375 @code{GL_INVALID_OPERATION} is generated if @code{glAttachShader} is
376 executed between the execution of @code{glBegin} and the corresponding
377 execution of @code{glEnd}.
381 @deftypefun void glBeginQuery target id
382 @deftypefunx void glEndQuery target
383 Delimit the boundaries of a query object.
387 Specifies the target type of query object established between
388 @code{glBeginQuery} and the subsequent @code{glEndQuery}. The symbolic
389 constant must be @code{GL_SAMPLES_PASSED}.
392 Specifies the name of a query object.
396 @code{glBeginQuery} and @code{glEndQuery} delimit the boundaries of a
397 query object. If a query object with name @var{id} does not yet exist it
400 When @code{glBeginQuery} is executed, the query object's samples-passed
401 counter is reset to 0. Subsequent rendering will increment the counter
402 once for every sample that passes the depth test. When @code{glEndQuery}
403 is executed, the samples-passed counter is assigned to the query
404 object's result value. This value can be queried by calling
405 @code{glGetQueryObject} with @var{pname}@code{GL_QUERY_RESULT}.
407 Querying the @code{GL_QUERY_RESULT} implicitly flushes the GL pipeline
408 until the rendering delimited by the query object has completed and the
409 result is available. @code{GL_QUERY_RESULT_AVAILABLE} can be queried to
410 determine if the result is immediately available or if the rendering is
413 @code{GL_INVALID_ENUM} is generated if @var{target} is not
414 @code{GL_SAMPLES_PASSED}.
416 @code{GL_INVALID_OPERATION} is generated if @code{glBeginQuery} is
417 executed while a query object of the same @var{target} is already
420 @code{GL_INVALID_OPERATION} is generated if @code{glEndQuery} is
421 executed when a query object of the same @var{target} is not active.
423 @code{GL_INVALID_OPERATION} is generated if @var{id} is 0.
425 @code{GL_INVALID_OPERATION} is generated if @var{id} is the name of an
426 already active query object.
428 @code{GL_INVALID_OPERATION} is generated if @code{glBeginQuery} or
429 @code{glEndQuery} is executed between the execution of @code{glBegin}
430 and the corresponding execution of @code{glEnd}.
434 @deftypefun void glBegin mode
435 @deftypefunx void glEnd
436 Delimit the vertices of a primitive or a group of like primitives.
440 Specifies the primitive or primitives that will be created from vertices
441 presented between @code{glBegin} and the subsequent @code{glEnd}. Ten
442 symbolic constants are accepted: @code{GL_POINTS}, @code{GL_LINES},
443 @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, @code{GL_TRIANGLES},
444 @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, @code{GL_QUADS},
445 @code{GL_QUAD_STRIP}, and @code{GL_POLYGON}.
449 @code{glBegin} and @code{glEnd} delimit the vertices that define a
450 primitive or a group of like primitives. @code{glBegin} accepts a single
451 argument that specifies in which of ten ways the vertices are
452 interpreted. Taking @r{@var{n}} as an integer count starting at one, and
453 @r{@var{N}} as the total number of vertices specified, the
454 interpretations are as follows:
457 @item @code{GL_POINTS}
458 Treats each vertex as a single point. Vertex @r{@var{n}} defines point
459 @r{@var{n}}. @r{@var{N}} points are drawn.
461 @item @code{GL_LINES}
462 Treats each pair of vertices as an independent line segment. Vertices
463 @r{2@var{n}-1} and @r{2@var{n}} define line @r{@var{n}}. @r{@var{N}/2}
466 @item @code{GL_LINE_STRIP}
467 Draws a connected group of line segments from the first vertex to the
468 last. Vertices @r{@var{n}} and @r{@var{n}+1} define line @r{@var{n}}.
469 @r{@var{N}-1} lines are drawn.
471 @item @code{GL_LINE_LOOP}
472 Draws a connected group of line segments from the first vertex to the
473 last, then back to the first. Vertices @r{@var{n}} and @r{@var{n}+1}
474 define line @r{@var{n}}. The last line, however, is defined by vertices
475 @r{@var{N}} and @r{1}. @r{@var{N}} lines are drawn.
477 @item @code{GL_TRIANGLES}
478 Treats each triplet of vertices as an independent triangle. Vertices
479 @r{3@var{n}-2}, @r{3@var{n}-1}, and @r{3@var{n}} define triangle
480 @r{@var{n}}. @r{@var{N}/3} triangles are drawn.
482 @item @code{GL_TRIANGLE_STRIP}
483 Draws a connected group of triangles. One triangle is defined for each
484 vertex presented after the first two vertices. For odd @r{@var{n}},
485 vertices @r{@var{n}}, @r{@var{n}+1}, and @r{@var{n}+2} define triangle
486 @r{@var{n}}. For even @r{@var{n}}, vertices @r{@var{n}+1}, @r{@var{n}},
487 and @r{@var{n}+2} define triangle @r{@var{n}}. @r{@var{N}-2} triangles
490 @item @code{GL_TRIANGLE_FAN}
491 Draws a connected group of triangles. One triangle is defined for each
492 vertex presented after the first two vertices. Vertices @r{1},
493 @r{@var{n}+1}, and @r{@var{n}+2} define triangle @r{@var{n}}.
494 @r{@var{N}-2} triangles are drawn.
496 @item @code{GL_QUADS}
497 Treats each group of four vertices as an independent quadrilateral.
498 Vertices @r{4@var{n}-3}, @r{4@var{n}-2}, @r{4@var{n}-1}, and
499 @r{4@var{n}} define quadrilateral @r{@var{n}}. @r{@var{N}/4}
500 quadrilaterals are drawn.
502 @item @code{GL_QUAD_STRIP}
503 Draws a connected group of quadrilaterals. One quadrilateral is defined
504 for each pair of vertices presented after the first pair. Vertices
505 @r{2@var{n}-1}, @r{2@var{n}}, @r{2@var{n}+2}, and @r{2@var{n}+1}
506 define quadrilateral @r{@var{n}}. @r{@var{N}/2-1} quadrilaterals are
507 drawn. Note that the order in which vertices are used to construct a
508 quadrilateral from strip data is different from that used with
511 @item @code{GL_POLYGON}
512 Draws a single, convex polygon. Vertices @r{1} through @r{@var{N}}
517 Only a subset of GL commands can be used between @code{glBegin} and
518 @code{glEnd}. The commands are @code{glVertex}, @code{glColor},
519 @code{glSecondaryColor}, @code{glIndex}, @code{glNormal},
520 @code{glFogCoord}, @code{glTexCoord}, @code{glMultiTexCoord},
521 @code{glVertexAttrib}, @code{glEvalCoord}, @code{glEvalPoint},
522 @code{glArrayElement}, @code{glMaterial}, and @code{glEdgeFlag}. Also,
523 it is acceptable to use @code{glCallList} or @code{glCallLists} to
524 execute display lists that include only the preceding commands. If any
525 other GL command is executed between @code{glBegin} and @code{glEnd},
526 the error flag is set and the command is ignored.
528 Regardless of the value chosen for @var{mode}, there is no limit to the
529 number of vertices that can be defined between @code{glBegin} and
530 @code{glEnd}. Lines, triangles, quadrilaterals, and polygons that are
531 incompletely specified are not drawn. Incomplete specification results
532 when either too few vertices are provided to specify even a single
533 primitive or when an incorrect multiple of vertices is specified. The
534 incomplete primitive is ignored; the rest are drawn.
536 The minimum specification of vertices for each primitive is as follows:
537 1 for a point, 2 for a line, 3 for a triangle, 4 for a quadrilateral,
538 and 3 for a polygon. Modes that require a certain multiple of vertices
539 are @code{GL_LINES} (2), @code{GL_TRIANGLES} (3), @code{GL_QUADS} (4),
540 and @code{GL_QUAD_STRIP} (2).
542 @code{GL_INVALID_ENUM} is generated if @var{mode} is set to an
545 @code{GL_INVALID_OPERATION} is generated if @code{glBegin} is executed
546 between a @code{glBegin} and the corresponding execution of
549 @code{GL_INVALID_OPERATION} is generated if @code{glEnd} is executed
550 without being preceded by a @code{glBegin}.
552 @code{GL_INVALID_OPERATION} is generated if a command other than
553 @code{glVertex}, @code{glColor}, @code{glSecondaryColor},
554 @code{glIndex}, @code{glNormal}, @code{glFogCoord}, @code{glTexCoord},
555 @code{glMultiTexCoord}, @code{glVertexAttrib}, @code{glEvalCoord},
556 @code{glEvalPoint}, @code{glArrayElement}, @code{glMaterial},
557 @code{glEdgeFlag}, @code{glCallList}, or @code{glCallLists} is executed
558 between the execution of @code{glBegin} and the corresponding execution
561 Execution of @code{glEnableClientState}, @code{glDisableClientState},
562 @code{glEdgeFlagPointer}, @code{glFogCoordPointer},
563 @code{glTexCoordPointer}, @code{glColorPointer},
564 @code{glSecondaryColorPointer}, @code{glIndexPointer},
565 @code{glNormalPointer}, @code{glVertexPointer},
566 @code{glVertexAttribPointer}, @code{glInterleavedArrays}, or
567 @code{glPixelStore} is not allowed after a call to @code{glBegin} and
568 before the corresponding call to @code{glEnd}, but an error may or may
573 @deftypefun void glBindAttribLocation program index name
574 Associates a generic vertex attribute index with a named attribute
579 Specifies the handle of the program object in which the association is
583 Specifies the index of the generic vertex attribute to be bound.
586 Specifies a null terminated string containing the name of the vertex
587 shader attribute variable to which @var{index} is to be bound.
591 @code{glBindAttribLocation} is used to associate a user-defined
592 attribute variable in the program object specified by @var{program} with
593 a generic vertex attribute index. The name of the user-defined attribute
594 variable is passed as a null terminated string in @var{name}. The
595 generic vertex attribute index to be bound to this variable is specified
596 by @var{index}. When @var{program} is made part of current state, values
597 provided via the generic vertex attribute @var{index} will modify the
598 value of the user-defined attribute variable specified by @var{name}.
600 If @var{name} refers to a matrix attribute variable, @var{index} refers
601 to the first column of the matrix. Other matrix columns are then
602 automatically bound to locations @var{index+1} for a matrix of type
603 mat2; @var{index+1} and @var{index+2} for a matrix of type mat3; and
604 @var{index+1}, @var{index+2}, and @var{index+3} for a matrix of type
607 This command makes it possible for vertex shaders to use descriptive
608 names for attribute variables rather than generic variables that are
609 numbered from 0 to @code{GL_MAX_VERTEX_ATTRIBS} -1. The values sent to
610 each generic attribute index are part of current state, just like
611 standard vertex attributes such as color, normal, and vertex position.
612 If a different program object is made current by calling
613 @code{glUseProgram}, the generic vertex attributes are tracked in such a
614 way that the same values will be observed by attributes in the new
615 program object that are also bound to @var{index}.
617 Attribute variable name-to-generic attribute index bindings for a
618 program object can be explicitly assigned at any time by calling
619 @code{glBindAttribLocation}. Attribute bindings do not go into effect
620 until @code{glLinkProgram} is called. After a program object has been
621 linked successfully, the index values for generic attributes remain
622 fixed (and their values can be queried) until the next link command
625 Applications are not allowed to bind any of the standard OpenGL vertex
626 attributes using this command, as they are bound automatically when
627 needed. Any attribute binding that occurs after the program object has
628 been linked will not take effect until the next time the program object
631 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
632 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
634 @code{GL_INVALID_OPERATION} is generated if @var{name} starts with the
635 reserved prefix "gl_".
637 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
640 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
643 @code{GL_INVALID_OPERATION} is generated if @code{glBindAttribLocation}
644 is executed between the execution of @code{glBegin} and the
645 corresponding execution of @code{glEnd}.
649 @deftypefun void glBindBuffer target buffer
650 Bind a named buffer object.
654 Specifies the target to which the buffer object is bound. The symbolic
655 constant must be @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
656 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
659 Specifies the name of a buffer object.
663 @code{glBindBuffer} lets you create or use a named buffer object.
664 Calling @code{glBindBuffer} with @var{target} set to
665 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
666 @code{GL_PIXEL_PACK_BUFFER} or @code{GL_PIXEL_UNPACK_BUFFER} and
667 @var{buffer} set to the name of the new buffer object binds the buffer
668 object name to the target. When a buffer object is bound to a target,
669 the previous binding for that target is automatically broken.
671 Buffer object names are unsigned integers. The value zero is reserved,
672 but there is no default buffer object for each buffer object target.
673 Instead, @var{buffer} set to zero effectively unbinds any buffer object
674 previously bound, and restores client memory usage for that buffer
675 object target. Buffer object names and the corresponding buffer object
676 contents are local to the shared display-list space (see
677 @code{glXCreateContext}) of the current GL rendering context; two
678 rendering contexts share buffer object names only if they also share
681 You may use @code{glGenBuffers} to generate a set of new buffer object
684 The state of a buffer object immediately after it is first bound is an
685 unmapped zero-sized memory buffer with @code{GL_READ_WRITE} access and
686 @code{GL_STATIC_DRAW} usage.
688 While a non-zero buffer object name is bound, GL operations on the
689 target to which it is bound affect the bound buffer object, and queries
690 of the target to which it is bound return state from the bound buffer
691 object. While buffer object name zero is bound, as in the initial state,
692 attempts to modify or query state on the target to which it is bound
693 generates an @code{GL_INVALID_OPERATION} error.
695 When vertex array pointer state is changed, for example by a call to
696 @code{glNormalPointer}, the current buffer object binding
697 (@code{GL_ARRAY_BUFFER_BINDING}) is copied into the corresponding client
698 state for the vertex array type being changed, for example
699 @code{GL_NORMAL_ARRAY_BUFFER_BINDING}. While a non-zero buffer object is
700 bound to the @code{GL_ARRAY_BUFFER} target, the vertex array pointer
701 parameter that is traditionally interpreted as a pointer to client-side
702 memory is instead interpreted as an offset within the buffer object
703 measured in basic machine units.
705 While a non-zero buffer object is bound to the
706 @code{GL_ELEMENT_ARRAY_BUFFER} target, the indices parameter of
707 @code{glDrawElements}, @code{glDrawRangeElements}, or
708 @code{glMultiDrawElements} that is traditionally interpreted as a
709 pointer to client-side memory is instead interpreted as an offset within
710 the buffer object measured in basic machine units.
712 While a non-zero buffer object is bound to the
713 @code{GL_PIXEL_PACK_BUFFER} target, the following commands are affected:
714 @code{glGetCompressedTexImage}, @code{glGetConvolutionFilter},
715 @code{glGetHistogram}, @code{glGetMinmax}, @code{glGetPixelMap},
716 @code{glGetPolygonStipple}, @code{glGetSeparableFilter},
717 @code{glGetTexImage}, and @code{glReadPixels}. The pointer parameter
718 that is traditionally interpreted as a pointer to client-side memory
719 where the pixels are to be packed is instead interpreted as an offset
720 within the buffer object measured in basic machine units.
722 While a non-zero buffer object is bound to the
723 @code{GL_PIXEL_UNPACK_BUFFER} target, the following commands are
724 affected: @code{glBitmap}, @code{glColorSubTable}, @code{glColorTable},
725 @code{glCompressedTexImage1D}, @code{glCompressedTexImage2D},
726 @code{glCompressedTexImage3D}, @code{glCompressedTexSubImage1D},
727 @code{glCompressedTexSubImage2D}, @code{glCompressedTexSubImage3D},
728 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D},
729 @code{glDrawPixels}, @code{glPixelMap}, @code{glPolygonStipple},
730 @code{glSeparableFilter2D}, @code{glTexImage1D}, @code{glTexImage2D},
731 @code{glTexImage3D}, @code{glTexSubImage1D}, @code{glTexSubImage2D}, and
732 @code{glTexSubImage3D}. The pointer parameter that is traditionally
733 interpreted as a pointer to client-side memory from which the pixels are
734 to be unpacked is instead interpreted as an offset within the buffer
735 object measured in basic machine units.
737 A buffer object binding created with @code{glBindBuffer} remains active
738 until a different buffer object name is bound to the same target, or
739 until the bound buffer object is deleted with @code{glDeleteBuffers}.
741 Once created, a named buffer object may be re-bound to any target as
742 often as needed. However, the GL implementation may make choices about
743 how to optimize the storage of a buffer object based on its initial
746 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
749 @code{GL_INVALID_OPERATION} is generated if @code{glBindBuffer} is
750 executed between the execution of @code{glBegin} and the corresponding
751 execution of @code{glEnd}.
755 @deftypefun void glBindTexture target texture
756 Bind a named texture to a texturing target.
760 Specifies the target to which the texture is bound. Must be either
761 @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, or
762 @code{GL_TEXTURE_CUBE_MAP}.
765 Specifies the name of a texture.
769 @code{glBindTexture} lets you create or use a named texture. Calling
770 @code{glBindTexture} with @var{target} set to @code{GL_TEXTURE_1D},
771 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D} or @code{GL_TEXTURE_CUBE_MAP}
772 and @var{texture} set to the name of the new texture binds the texture
773 name to the target. When a texture is bound to a target, the previous
774 binding for that target is automatically broken.
776 Texture names are unsigned integers. The value zero is reserved to
777 represent the default texture for each texture target. Texture names and
778 the corresponding texture contents are local to the shared display-list
779 space (see @code{glXCreateContext}) of the current GL rendering context;
780 two rendering contexts share texture names only if they also share
783 You may use @code{glGenTextures} to generate a set of new texture names.
785 When a texture is first bound, it assumes the specified target: A
786 texture first bound to @code{GL_TEXTURE_1D} becomes one-dimensional
787 texture, a texture first bound to @code{GL_TEXTURE_2D} becomes
788 two-dimensional texture, a texture first bound to @code{GL_TEXTURE_3D}
789 becomes three-dimensional texture, and a texture first bound to
790 @code{GL_TEXTURE_CUBE_MAP} becomes a cube-mapped texture. The state of a
791 one-dimensional texture immediately after it is first bound is
792 equivalent to the state of the default @code{GL_TEXTURE_1D} at GL
793 initialization, and similarly for two- and three-dimensional textures
794 and cube-mapped textures.
796 While a texture is bound, GL operations on the target to which it is
797 bound affect the bound texture, and queries of the target to which it is
798 bound return state from the bound texture. If texture mapping is active
799 on the target to which a texture is bound, the bound texture is used. In
800 effect, the texture targets become aliases for the textures currently
801 bound to them, and the texture name zero refers to the default textures
802 that were bound to them at initialization.
804 A texture binding created with @code{glBindTexture} remains active until
805 a different texture is bound to the same target, or until the bound
806 texture is deleted with @code{glDeleteTextures}.
808 Once created, a named texture may be re-bound to its same original
809 target as often as needed. It is usually much faster to use
810 @code{glBindTexture} to bind an existing named texture to one of the
811 texture targets than it is to reload the texture image using
812 @code{glTexImage1D}, @code{glTexImage2D}, or @code{glTexImage3D}. For
813 additional control over performance, use @code{glPrioritizeTextures}.
815 @code{glBindTexture} is included in display lists.
817 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
820 @code{GL_INVALID_OPERATION} is generated if @var{texture} was previously
821 created with a target that doesn't match that of @var{target}.
823 @code{GL_INVALID_OPERATION} is generated if @code{glBindTexture} is
824 executed between the execution of @code{glBegin} and the corresponding
825 execution of @code{glEnd}.
829 @deftypefun void glBitmap width height xorig yorig xmove ymove bitmap
835 Specify the pixel width and height of the bitmap image.
839 Specify the location of the origin in the bitmap image. The origin is
840 measured from the lower left corner of the bitmap, with right and up
841 being the positive axes.
845 Specify the @var{x} and @var{y} offsets to be added to the current
846 raster position after the bitmap is drawn.
849 Specifies the address of the bitmap image.
853 A bitmap is a binary image. When drawn, the bitmap is positioned
854 relative to the current raster position, and frame buffer pixels
855 corresponding to 1's in the bitmap are written using the current raster
856 color or index. Frame buffer pixels corresponding to 0's in the bitmap
859 @code{glBitmap} takes seven arguments. The first pair specifies the
860 width and height of the bitmap image. The second pair specifies the
861 location of the bitmap origin relative to the lower left corner of the
862 bitmap image. The third pair of arguments specifies @var{x} and @var{y}
863 offsets to be added to the current raster position after the bitmap has
864 been drawn. The final argument is a pointer to the bitmap image itself.
866 If a non-zero named buffer object is bound to the
867 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
868 bitmap image is specified, @var{bitmap} is treated as a byte offset into
869 the buffer object's data store.
871 The bitmap image is interpreted like image data for the
872 @code{glDrawPixels} command, with @var{width} and @var{height}
873 corresponding to the width and height arguments of that command, and
874 with @var{type} set to @code{GL_BITMAP} and @var{format} set to
875 @code{GL_COLOR_INDEX}. Modes specified using @code{glPixelStore} affect
876 the interpretation of bitmap image data; modes specified using
877 @code{glPixelTransfer} do not.
879 If the current raster position is invalid, @code{glBitmap} is ignored.
880 Otherwise, the lower left corner of the bitmap image is positioned at
881 the window coordinates
883 @r{@var{x}_@var{w}=⌊@var{x}_@var{r}-@var{x}_@var{o},⌋}
885 @r{@var{y}_@var{w}=⌊@var{y}_@var{r}-@var{y}_@var{o},⌋}
887 where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the raster position and
888 @r{(@var{x}_@var{o},@var{y}_@var{o})} is the bitmap origin. Fragments
889 are then generated for each pixel corresponding to a 1 (one) in the
890 bitmap image. These fragments are generated using the current raster
891 @var{z} coordinate, color or color index, and current raster texture
892 coordinates. They are then treated just as if they had been generated by
893 a point, line, or polygon, including texture mapping, fogging, and all
894 per-fragment operations such as alpha and depth testing.
896 After the bitmap has been drawn, the @var{x} and @var{y} coordinates of
897 the current raster position are offset by @var{xmove} and @var{ymove}.
898 No change is made to the @var{z} coordinate of the current raster
899 position, or to the current raster color, texture coordinates, or index.
901 @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is
904 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
905 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
906 object's data store is currently mapped.
908 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
909 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
910 would be unpacked from the buffer object such that the memory reads
911 required would exceed the data store size.
913 @code{GL_INVALID_OPERATION} is generated if @code{glBitmap} is executed
914 between the execution of @code{glBegin} and the corresponding execution
919 @deftypefun void glBlendColor red green blue alpha
927 specify the components of @code{GL_BLEND_COLOR}
931 The @code{GL_BLEND_COLOR} may be used to calculate the source and
932 destination blending factors. The color components are clamped to the
933 range @r{[0,1]} before being stored. See @code{glBlendFunc} for a
934 complete description of the blending operations. Initially the
935 @code{GL_BLEND_COLOR} is set to (0, 0, 0, 0).
937 @code{GL_INVALID_OPERATION} is generated if @code{glBlendColor} is
938 executed between the execution of @code{glBegin} and the corresponding
939 execution of @code{glEnd}.
945 @deftypefun void glBlendEquationSeparate modeRGB modeAlpha
946 Set the RGB blend equation and the alpha blend equation separately.
950 specifies the RGB blend equation, how the red, green, and blue
951 components of the source and destination colors are combined. It must be
952 @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT},
953 @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN}, @code{GL_MAX}.
955 @item @var{modeAlpha}
956 specifies the alpha blend equation, how the alpha component of the
957 source and destination colors are combined. It must be
958 @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT},
959 @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN}, @code{GL_MAX}.
963 The blend equations determines how a new pixel (the ''source'' color) is
964 combined with a pixel already in the framebuffer (the ''destination''
965 color). This function specifies one blend equation for the RGB-color
966 components and one blend equation for the alpha component.
968 The blend equations use the source and destination blend factors
969 specified by either @code{glBlendFunc} or @code{glBlendFuncSeparate}.
970 See @code{glBlendFunc} or @code{glBlendFuncSeparate} for a description
971 of the various blend factors.
973 In the equations that follow, source and destination color components
975 @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and
976 @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})},
977 respectively. The result color is referred to as
978 @r{(@var{R}_@var{r},@var{G}_@var{r}@var{B}_@var{r}@var{A}_@var{r})}. The
979 source and destination blend factors are denoted
980 @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and
981 @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})},
982 respectively. For these equations all color components are understood to
983 have values in the range @r{[0,1]}.
987 @strong{RGB Components}, @strong{Alpha Component}
989 @item @code{GL_FUNC_ADD}
990 @r{@var{Rr}=@var{R}_@var{s}@var{s}_@var{R}+@var{R}_@var{d}@var{d}_@var{R}}@r{@var{Gr}=@var{G}_@var{s}@var{s}_@var{G}+@var{G}_@var{d}@var{d}_@var{G}}@r{@var{Br}=@var{B}_@var{s}@var{s}_@var{B}+@var{B}_@var{d}@var{d}_@var{B}},
991 @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}+@var{A}_@var{d}@var{d}_@var{A}}
993 @item @code{GL_FUNC_SUBTRACT}
994 @r{@var{Rr}=@var{R}_@var{s}@var{s}_@var{R}-@var{R}_@var{d}@var{d}_@var{R}}@r{@var{Gr}=@var{G}_@var{s}@var{s}_@var{G}-@var{G}_@var{d}@var{d}_@var{G}}@r{@var{Br}=@var{B}_@var{s}@var{s}_@var{B}-@var{B}_@var{d}@var{d}_@var{B}},
995 @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}-@var{A}_@var{d}@var{d}_@var{A}}
997 @item @code{GL_FUNC_REVERSE_SUBTRACT}
998 @r{@var{Rr}=@var{R}_@var{d}@var{d}_@var{R}-@var{R}_@var{s}@var{s}_@var{R}}@r{@var{Gr}=@var{G}_@var{d}@var{d}_@var{G}-@var{G}_@var{s}@var{s}_@var{G}}@r{@var{Br}=@var{B}_@var{d}@var{d}_@var{B}-@var{B}_@var{s}@var{s}_@var{B}},
999 @r{@var{Ar}=@var{A}_@var{d}@var{d}_@var{A}-@var{A}_@var{s}@var{s}_@var{A}}
1002 @r{@var{Rr}=@var{min}(@var{R}_@var{s},@var{R}_@var{d})}@r{@var{Gr}=@var{min}(@var{G}_@var{s},@var{G}_@var{d})}@r{@var{Br}=@var{min}(@var{B}_@var{s},@var{B}_@var{d})},
1003 @r{@var{Ar}=@var{min}(@var{A}_@var{s},@var{A}_@var{d})}
1006 @r{@var{Rr}=@var{max}(@var{R}_@var{s},@var{R}_@var{d})}@r{@var{Gr}=@var{max}(@var{G}_@var{s},@var{G}_@var{d})}@r{@var{Br}=@var{max}(@var{B}_@var{s},@var{B}_@var{d})},
1007 @r{@var{Ar}=@var{max}(@var{A}_@var{s},@var{A}_@var{d})}
1011 The results of these equations are clamped to the range @r{[0,1]}.
1013 The @code{GL_MIN} and @code{GL_MAX} equations are useful for
1014 applications that analyze image data (image thresholding against a
1015 constant color, for example). The @code{GL_FUNC_ADD} equation is useful
1016 for antialiasing and transparency, among other things.
1018 Initially, both the RGB blend equation and the alpha blend equation are
1019 set to @code{GL_FUNC_ADD}.
1023 @code{GL_INVALID_ENUM} is generated if either @var{modeRGB} or
1024 @var{modeAlpha} is not one of @code{GL_FUNC_ADD},
1025 @code{GL_FUNC_SUBTRACT}, @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MAX},
1028 @code{GL_INVALID_OPERATION} is generated if
1029 @code{glBlendEquationSeparate} is executed between the execution of
1030 @code{glBegin} and the corresponding execution of @code{glEnd}.
1034 @deftypefun void glBlendEquation mode
1035 Specify the equation used for both the RGB blend equation and the Alpha
1040 specifies how source and destination colors are combined. It must be
1041 @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT},
1042 @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN}, @code{GL_MAX}.
1046 The blend equations determine how a new pixel (the ''source'' color) is
1047 combined with a pixel already in the framebuffer (the ''destination''
1048 color). This function sets both the RGB blend equation and the alpha
1049 blend equation to a single equation.
1051 These equations use the source and destination blend factors specified
1052 by either @code{glBlendFunc} or @code{glBlendFuncSeparate}. See
1053 @code{glBlendFunc} or @code{glBlendFuncSeparate} for a description of
1054 the various blend factors.
1056 In the equations that follow, source and destination color components
1058 @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and
1059 @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})},
1060 respectively. The result color is referred to as
1061 @r{(@var{R}_@var{r},@var{G}_@var{r}@var{B}_@var{r}@var{A}_@var{r})}. The
1062 source and destination blend factors are denoted
1063 @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and
1064 @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})},
1065 respectively. For these equations all color components are understood to
1066 have values in the range @r{[0,1]}.
1070 @strong{RGB Components}, @strong{Alpha Component}
1072 @item @code{GL_FUNC_ADD}
1073 @r{@var{Rr}=@var{R}_@var{s}@var{s}_@var{R}+@var{R}_@var{d}@var{d}_@var{R}}@r{@var{Gr}=@var{G}_@var{s}@var{s}_@var{G}+@var{G}_@var{d}@var{d}_@var{G}}@r{@var{Br}=@var{B}_@var{s}@var{s}_@var{B}+@var{B}_@var{d}@var{d}_@var{B}},
1074 @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}+@var{A}_@var{d}@var{d}_@var{A}}
1076 @item @code{GL_FUNC_SUBTRACT}
1077 @r{@var{Rr}=@var{R}_@var{s}@var{s}_@var{R}-@var{R}_@var{d}@var{d}_@var{R}}@r{@var{Gr}=@var{G}_@var{s}@var{s}_@var{G}-@var{G}_@var{d}@var{d}_@var{G}}@r{@var{Br}=@var{B}_@var{s}@var{s}_@var{B}-@var{B}_@var{d}@var{d}_@var{B}},
1078 @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}-@var{A}_@var{d}@var{d}_@var{A}}
1080 @item @code{GL_FUNC_REVERSE_SUBTRACT}
1081 @r{@var{Rr}=@var{R}_@var{d}@var{d}_@var{R}-@var{R}_@var{s}@var{s}_@var{R}}@r{@var{Gr}=@var{G}_@var{d}@var{d}_@var{G}-@var{G}_@var{s}@var{s}_@var{G}}@r{@var{Br}=@var{B}_@var{d}@var{d}_@var{B}-@var{B}_@var{s}@var{s}_@var{B}},
1082 @r{@var{Ar}=@var{A}_@var{d}@var{d}_@var{A}-@var{A}_@var{s}@var{s}_@var{A}}
1085 @r{@var{Rr}=@var{min}(@var{R}_@var{s},@var{R}_@var{d})}@r{@var{Gr}=@var{min}(@var{G}_@var{s},@var{G}_@var{d})}@r{@var{Br}=@var{min}(@var{B}_@var{s},@var{B}_@var{d})},
1086 @r{@var{Ar}=@var{min}(@var{A}_@var{s},@var{A}_@var{d})}
1089 @r{@var{Rr}=@var{max}(@var{R}_@var{s},@var{R}_@var{d})}@r{@var{Gr}=@var{max}(@var{G}_@var{s},@var{G}_@var{d})}@r{@var{Br}=@var{max}(@var{B}_@var{s},@var{B}_@var{d})},
1090 @r{@var{Ar}=@var{max}(@var{A}_@var{s},@var{A}_@var{d})}
1094 The results of these equations are clamped to the range @r{[0,1]}.
1096 The @code{GL_MIN} and @code{GL_MAX} equations are useful for
1097 applications that analyze image data (image thresholding against a
1098 constant color, for example). The @code{GL_FUNC_ADD} equation is useful
1099 for antialiasing and transparency, among other things.
1101 Initially, both the RGB blend equation and the alpha blend equation are
1102 set to @code{GL_FUNC_ADD}.
1106 @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of
1107 @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT},
1108 @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MAX}, or @code{GL_MIN}.
1110 @code{GL_INVALID_OPERATION} is generated if @code{glBlendEquation} is
1111 executed between the execution of @code{glBegin} and the corresponding
1112 execution of @code{glEnd}.
1116 @deftypefun void glBlendFuncSeparate srcRGB dstRGB srcAlpha dstAlpha
1117 Specify pixel arithmetic for RGB and alpha components separately.
1121 Specifies how the red, green, and blue blending factors are computed.
1122 The following symbolic constants are accepted: @code{GL_ZERO},
1123 @code{GL_ONE}, @code{GL_SRC_COLOR}, @code{GL_ONE_MINUS_SRC_COLOR},
1124 @code{GL_DST_COLOR}, @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA},
1125 @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA},
1126 @code{GL_ONE_MINUS_DST_ALPHA}, @code{GL_CONSTANT_COLOR},
1127 @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA},
1128 @code{GL_ONE_MINUS_CONSTANT_ALPHA}, and @code{GL_SRC_ALPHA_SATURATE}.
1129 The initial value is @code{GL_ONE}.
1132 Specifies how the red, green, and blue destination blending factors are
1133 computed. The following symbolic constants are accepted: @code{GL_ZERO},
1134 @code{GL_ONE}, @code{GL_SRC_COLOR}, @code{GL_ONE_MINUS_SRC_COLOR},
1135 @code{GL_DST_COLOR}, @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA},
1136 @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA},
1137 @code{GL_ONE_MINUS_DST_ALPHA}. @code{GL_CONSTANT_COLOR},
1138 @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA}, and
1139 @code{GL_ONE_MINUS_CONSTANT_ALPHA}. The initial value is @code{GL_ZERO}.
1141 @item @var{srcAlpha}
1142 Specified how the alpha source blending factor is computed. The same
1143 symbolic constants are accepted as for @var{srcRGB}. The initial value
1146 @item @var{dstAlpha}
1147 Specified how the alpha destination blending factor is computed. The
1148 same symbolic constants are accepted as for @var{dstRGB}. The initial
1149 value is @code{GL_ZERO}.
1153 In RGBA mode, pixels can be drawn using a function that blends the
1154 incoming (source) RGBA values with the RGBA values that are already in
1155 the frame buffer (the destination values). Blending is initially
1156 disabled. Use @code{glEnable} and @code{glDisable} with argument
1157 @code{GL_BLEND} to enable and disable blending.
1159 @code{glBlendFuncSeparate} defines the operation of blending when it is
1160 enabled. @var{srcRGB} specifies which method is used to scale the source
1161 RGB-color components. @var{dstRGB} specifies which method is used to
1162 scale the destination RGB-color components. Likewise, @var{srcAlpha}
1163 specifies which method is used to scale the source alpha color
1164 component, and @var{dstAlpha} specifies which method is used to scale
1165 the destination alpha component. The possible methods are described in
1166 the following table. Each method defines four scale factors, one each
1167 for red, green, blue, and alpha.
1169 In the table and in subsequent equations, source and destination color
1170 components are referred to as
1171 @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and
1172 @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})}. The
1173 color specified by @code{glBlendColor} is referred to as
1174 @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})}.
1175 They are understood to have integer values between 0 and
1176 @r{(@var{k}_@var{R},@var{k}_@var{G}@var{k}_@var{B}@var{k}_@var{A})},
1179 @r{@var{k}_@var{c}=2^@var{m}_@var{c},-1}
1181 and @r{(@var{m}_@var{R},@var{m}_@var{G}@var{m}_@var{B}@var{m}_@var{A})}
1182 is the number of red, green, blue, and alpha bitplanes.
1184 Source and destination scale factors are referred to as
1185 @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and
1186 @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})}. All
1187 scale factors have range @r{[0,1]}.
1192 @item @strong{Parameter}
1193 @strong{RGB Factor}, @strong{Alpha Factor}
1195 @item @code{GL_ZERO}
1201 @item @code{GL_SRC_COLOR}
1202 @r{(@var{R}_@var{s}/@var{k}_@var{R},@var{G}_@var{s}/@var{k}_@var{G}@var{B}_@var{s}/@var{k}_@var{B})},
1203 @r{@var{A}_@var{s}/@var{k}_@var{A}}
1205 @item @code{GL_ONE_MINUS_SRC_COLOR}
1206 @r{(1,111)-(@var{R}_@var{s}/@var{k}_@var{R},@var{G}_@var{s}/@var{k}_@var{G}@var{B}_@var{s}/@var{k}_@var{B})},
1207 @r{1-@var{A}_@var{s}/@var{k}_@var{A}}
1209 @item @code{GL_DST_COLOR}
1210 @r{(@var{R}_@var{d}/@var{k}_@var{R},@var{G}_@var{d}/@var{k}_@var{G}@var{B}_@var{d}/@var{k}_@var{B})},
1211 @r{@var{A}_@var{d}/@var{k}_@var{A}}
1213 @item @code{GL_ONE_MINUS_DST_COLOR}
1214 @r{(1,11)-(@var{R}_@var{d}/@var{k}_@var{R},@var{G}_@var{d}/@var{k}_@var{G}@var{B}_@var{d}/@var{k}_@var{B})},
1215 @r{1-@var{A}_@var{d}/@var{k}_@var{A}}
1217 @item @code{GL_SRC_ALPHA}
1218 @r{(@var{A}_@var{s}/@var{k}_@var{A},@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A})},
1219 @r{@var{A}_@var{s}/@var{k}_@var{A}}
1221 @item @code{GL_ONE_MINUS_SRC_ALPHA}
1222 @r{(1,11)-(@var{A}_@var{s}/@var{k}_@var{A},@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A})},
1223 @r{1-@var{A}_@var{s}/@var{k}_@var{A}}
1225 @item @code{GL_DST_ALPHA}
1226 @r{(@var{A}_@var{d}/@var{k}_@var{A},@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A})},
1227 @r{@var{A}_@var{d}/@var{k}_@var{A}}
1229 @item @code{GL_ONE_MINUS_DST_ALPHA}
1230 @r{(1,11)-(@var{A}_@var{d}/@var{k}_@var{A},@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A})},
1231 @r{1-@var{A}_@var{d}/@var{k}_@var{A}}
1233 @item @code{GL_CONSTANT_COLOR}
1234 @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c})},
1237 @item @code{GL_ONE_MINUS_CONSTANT_COLOR}
1238 @r{(1,11)-(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c})},
1239 @r{1-@var{A}_@var{c}}
1241 @item @code{GL_CONSTANT_ALPHA}
1242 @r{(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c})},
1245 @item @code{GL_ONE_MINUS_CONSTANT_ALPHA}
1246 @r{(1,11)-(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c})},
1247 @r{1-@var{A}_@var{c}}
1249 @item @code{GL_SRC_ALPHA_SATURATE}
1250 @r{(@var{i},@var{i}@var{i})}, @r{1}
1256 @r{@var{i}=@var{min}(@var{A}_@var{s},1-@var{A}_@var{d},)}
1258 To determine the blended RGBA values of a pixel when drawing in RGBA
1259 mode, the system uses the following equations:
1261 @r{@var{R}_@var{d}=@var{min}(@var{k}_@var{R},@var{R}_@var{s}@var{s}_@var{R}+@var{R}_@var{d}@var{d}_@var{R})}@r{@var{G}_@var{d}=@var{min}(@var{k}_@var{G},@var{G}_@var{s}@var{s}_@var{G}+@var{G}_@var{d}@var{d}_@var{G})}@r{@var{B}_@var{d}=@var{min}(@var{k}_@var{B},@var{B}_@var{s}@var{s}_@var{B}+@var{B}_@var{d}@var{d}_@var{B})}@r{@var{A}_@var{d}=@var{min}(@var{k}_@var{A},@var{A}_@var{s}@var{s}_@var{A}+@var{A}_@var{d}@var{d}_@var{A})}
1263 Despite the apparent precision of the above equations, blending
1264 arithmetic is not exactly specified, because blending operates with
1265 imprecise integer color values. However, a blend factor that should be
1266 equal to 1 is guaranteed not to modify its multiplicand, and a blend
1267 factor equal to 0 reduces its multiplicand to 0. For example, when
1268 @var{srcRGB} is @code{GL_SRC_ALPHA}, @var{dstRGB} is
1269 @code{GL_ONE_MINUS_SRC_ALPHA}, and @r{@var{A}_@var{s}} is equal to
1270 @r{@var{k}_@var{A}}, the equations reduce to simple replacement:
1272 @r{@var{R}_@var{d}=@var{R}_@var{s}}@r{@var{G}_@var{d}=@var{G}_@var{s}}@r{@var{B}_@var{d}=@var{B}_@var{s}}@r{@var{A}_@var{d}=@var{A}_@var{s}}
1276 @code{GL_INVALID_ENUM} is generated if either @var{srcRGB} or
1277 @var{dstRGB} is not an accepted value.
1279 @code{GL_INVALID_OPERATION} is generated if @code{glBlendFuncSeparate}
1280 is executed between the execution of @code{glBegin} and the
1281 corresponding execution of @code{glEnd}.
1285 @deftypefun void glBlendFunc sfactor dfactor
1286 Specify pixel arithmetic.
1290 Specifies how the red, green, blue, and alpha source blending factors
1291 are computed. The following symbolic constants are accepted:
1292 @code{GL_ZERO}, @code{GL_ONE}, @code{GL_SRC_COLOR},
1293 @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_DST_COLOR},
1294 @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA},
1295 @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA},
1296 @code{GL_ONE_MINUS_DST_ALPHA}, @code{GL_CONSTANT_COLOR},
1297 @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA},
1298 @code{GL_ONE_MINUS_CONSTANT_ALPHA}, and @code{GL_SRC_ALPHA_SATURATE}.
1299 The initial value is @code{GL_ONE}.
1302 Specifies how the red, green, blue, and alpha destination blending
1303 factors are computed. The following symbolic constants are accepted:
1304 @code{GL_ZERO}, @code{GL_ONE}, @code{GL_SRC_COLOR},
1305 @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_DST_COLOR},
1306 @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA},
1307 @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA},
1308 @code{GL_ONE_MINUS_DST_ALPHA}. @code{GL_CONSTANT_COLOR},
1309 @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA}, and
1310 @code{GL_ONE_MINUS_CONSTANT_ALPHA}. The initial value is @code{GL_ZERO}.
1314 In RGBA mode, pixels can be drawn using a function that blends the
1315 incoming (source) RGBA values with the RGBA values that are already in
1316 the frame buffer (the destination values). Blending is initially
1317 disabled. Use @code{glEnable} and @code{glDisable} with argument
1318 @code{GL_BLEND} to enable and disable blending.
1320 @code{glBlendFunc} defines the operation of blending when it is enabled.
1321 @var{sfactor} specifies which method is used to scale the source color
1322 components. @var{dfactor} specifies which method is used to scale the
1323 destination color components. The possible methods are described in the
1324 following table. Each method defines four scale factors, one each for
1325 red, green, blue, and alpha. In the table and in subsequent equations,
1326 source and destination color components are referred to as
1327 @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and
1328 @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})}. The
1329 color specified by @code{glBlendColor} is referred to as
1330 @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})}.
1331 They are understood to have integer values between 0 and
1332 @r{(@var{k}_@var{R},@var{k}_@var{G}@var{k}_@var{B}@var{k}_@var{A})},
1335 @r{@var{k}_@var{c}=2^@var{m}_@var{c},-1}
1337 and @r{(@var{m}_@var{R},@var{m}_@var{G}@var{m}_@var{B}@var{m}_@var{A})}
1338 is the number of red, green, blue, and alpha bitplanes.
1340 Source and destination scale factors are referred to as
1341 @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and
1342 @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})}. The
1343 scale factors described in the table, denoted
1344 @r{(@var{f}_@var{R},@var{f}_@var{G}@var{f}_@var{B}@var{f}_@var{A})},
1345 represent either source or destination factors. All scale factors have
1351 @item @strong{Parameter}
1352 @strong{@r{(@var{f}_@var{R},@var{f}_@var{G}@var{f}_@var{B}@var{f}_@var{A})}}
1354 @item @code{GL_ZERO}
1360 @item @code{GL_SRC_COLOR}
1361 @r{(@var{R}_@var{s}/@var{k}_@var{R},@var{G}_@var{s}/@var{k}_@var{G}@var{B}_@var{s}/@var{k}_@var{B}@var{A}_@var{s}/@var{k}_@var{A})}
1363 @item @code{GL_ONE_MINUS_SRC_COLOR}
1364 @r{(1,111)-(@var{R}_@var{s}/@var{k}_@var{R},@var{G}_@var{s}/@var{k}_@var{G}@var{B}_@var{s}/@var{k}_@var{B}@var{A}_@var{s}/@var{k}_@var{A})}
1366 @item @code{GL_DST_COLOR}
1367 @r{(@var{R}_@var{d}/@var{k}_@var{R},@var{G}_@var{d}/@var{k}_@var{G}@var{B}_@var{d}/@var{k}_@var{B}@var{A}_@var{d}/@var{k}_@var{A})}
1369 @item @code{GL_ONE_MINUS_DST_COLOR}
1370 @r{(1,111)-(@var{R}_@var{d}/@var{k}_@var{R},@var{G}_@var{d}/@var{k}_@var{G}@var{B}_@var{d}/@var{k}_@var{B}@var{A}_@var{d}/@var{k}_@var{A})}
1372 @item @code{GL_SRC_ALPHA}
1373 @r{(@var{A}_@var{s}/@var{k}_@var{A},@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A})}
1375 @item @code{GL_ONE_MINUS_SRC_ALPHA}
1376 @r{(1,111)-(@var{A}_@var{s}/@var{k}_@var{A},@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A})}
1378 @item @code{GL_DST_ALPHA}
1379 @r{(@var{A}_@var{d}/@var{k}_@var{A},@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A})}
1381 @item @code{GL_ONE_MINUS_DST_ALPHA}
1382 @r{(1,111)-(@var{A}_@var{d}/@var{k}_@var{A},@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A})}
1384 @item @code{GL_CONSTANT_COLOR}
1385 @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})}
1387 @item @code{GL_ONE_MINUS_CONSTANT_COLOR}
1388 @r{(1,111)-(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})}
1390 @item @code{GL_CONSTANT_ALPHA}
1391 @r{(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c}@var{A}_@var{c})}
1393 @item @code{GL_ONE_MINUS_CONSTANT_ALPHA}
1394 @r{(1,111)-(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c}@var{A}_@var{c})}
1396 @item @code{GL_SRC_ALPHA_SATURATE}
1397 @r{(@var{i},@var{i}@var{i}1)}
1403 @r{@var{i}=@var{min}(@var{A}_@var{s},@var{k}_@var{A}-@var{A}_@var{d})/@var{k}_@var{A}}
1405 To determine the blended RGBA values of a pixel when drawing in RGBA
1406 mode, the system uses the following equations:
1408 @r{@var{R}_@var{d}=@var{min}(@var{k}_@var{R},@var{R}_@var{s}@var{s}_@var{R}+@var{R}_@var{d}@var{d}_@var{R})}@r{@var{G}_@var{d}=@var{min}(@var{k}_@var{G},@var{G}_@var{s}@var{s}_@var{G}+@var{G}_@var{d}@var{d}_@var{G})}@r{@var{B}_@var{d}=@var{min}(@var{k}_@var{B},@var{B}_@var{s}@var{s}_@var{B}+@var{B}_@var{d}@var{d}_@var{B})}@r{@var{A}_@var{d}=@var{min}(@var{k}_@var{A},@var{A}_@var{s}@var{s}_@var{A}+@var{A}_@var{d}@var{d}_@var{A})}
1410 Despite the apparent precision of the above equations, blending
1411 arithmetic is not exactly specified, because blending operates with
1412 imprecise integer color values. However, a blend factor that should be
1413 equal to 1 is guaranteed not to modify its multiplicand, and a blend
1414 factor equal to 0 reduces its multiplicand to 0. For example, when
1415 @var{sfactor} is @code{GL_SRC_ALPHA}, @var{dfactor} is
1416 @code{GL_ONE_MINUS_SRC_ALPHA}, and @r{@var{A}_@var{s}} is equal to
1417 @r{@var{k}_@var{A}}, the equations reduce to simple replacement:
1419 @r{@var{R}_@var{d}=@var{R}_@var{s}}@r{@var{G}_@var{d}=@var{G}_@var{s}}@r{@var{B}_@var{d}=@var{B}_@var{s}}@r{@var{A}_@var{d}=@var{A}_@var{s}}
1423 @code{GL_INVALID_ENUM} is generated if either @var{sfactor} or
1424 @var{dfactor} is not an accepted value.
1426 @code{GL_INVALID_OPERATION} is generated if @code{glBlendFunc} is
1427 executed between the execution of @code{glBegin} and the corresponding
1428 execution of @code{glEnd}.
1432 @deftypefun void glBufferData target size data usage
1433 Creates and initializes a buffer object's data store.
1437 Specifies the target buffer object. The symbolic constant must be
1438 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
1439 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
1442 Specifies the size in bytes of the buffer object's new data store.
1445 Specifies a pointer to data that will be copied into the data store for
1446 initialization, or @code{NULL} if no data is to be copied.
1449 Specifies the expected usage pattern of the data store. The symbolic
1450 constant must be @code{GL_STREAM_DRAW}, @code{GL_STREAM_READ},
1451 @code{GL_STREAM_COPY}, @code{GL_STATIC_DRAW}, @code{GL_STATIC_READ},
1452 @code{GL_STATIC_COPY}, @code{GL_DYNAMIC_DRAW}, @code{GL_DYNAMIC_READ},
1453 or @code{GL_DYNAMIC_COPY}.
1457 @code{glBufferData} creates a new data store for the buffer object
1458 currently bound to @var{target}. Any pre-existing data store is deleted.
1459 The new data store is created with the specified @var{size} in bytes and
1460 @var{usage}. If @var{data} is not @code{NULL}, the data store is
1461 initialized with data from this pointer. In its initial state, the new
1462 data store is not mapped, it has a @code{NULL} mapped pointer, and its
1463 mapped access is @code{GL_READ_WRITE}.
1465 @var{usage} is a hint to the GL implementation as to how a buffer
1466 object's data store will be accessed. This enables the GL implementation
1467 to make more intelligent decisions that may significantly impact buffer
1468 object performance. It does not, however, constrain the actual usage of
1469 the data store. @var{usage} can be broken down into two parts: first,
1470 the frequency of access (modification and usage), and second, the nature
1471 of that access. The frequency of access may be one of these:
1475 The data store contents will be modified once and used at most a few
1479 The data store contents will be modified once and used many times.
1482 The data store contents will be modified repeatedly and used many times.
1486 The nature of access may be one of these:
1490 The data store contents are modified by the application, and used as the
1491 source for GL drawing and image specification commands.
1494 The data store contents are modified by reading data from the GL, and
1495 used to return that data when queried by the application.
1498 The data store contents are modified by reading data from the GL, and
1499 used as the source for GL drawing and image specification commands.
1503 @code{GL_INVALID_ENUM} is generated if @var{target} is not
1504 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
1505 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
1507 @code{GL_INVALID_ENUM} is generated if @var{usage} is not
1508 @code{GL_STREAM_DRAW}, @code{GL_STREAM_READ}, @code{GL_STREAM_COPY},
1509 @code{GL_STATIC_DRAW}, @code{GL_STATIC_READ}, @code{GL_STATIC_COPY},
1510 @code{GL_DYNAMIC_DRAW}, @code{GL_DYNAMIC_READ}, or
1511 @code{GL_DYNAMIC_COPY}.
1513 @code{GL_INVALID_VALUE} is generated if @var{size} is negative.
1515 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
1516 name 0 is bound to @var{target}.
1518 @code{GL_OUT_OF_MEMORY} is generated if the GL is unable to create a
1519 data store with the specified @var{size}.
1521 @code{GL_INVALID_OPERATION} is generated if @code{glBufferData} is
1522 executed between the execution of @code{glBegin} and the corresponding
1523 execution of @code{glEnd}.
1527 @deftypefun void glBufferSubData target offset size data
1528 Updates a subset of a buffer object's data store.
1532 Specifies the target buffer object. The symbolic constant must be
1533 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
1534 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
1537 Specifies the offset into the buffer object's data store where data
1538 replacement will begin, measured in bytes.
1541 Specifies the size in bytes of the data store region being replaced.
1544 Specifies a pointer to the new data that will be copied into the data
1549 @code{glBufferSubData} redefines some or all of the data store for the
1550 buffer object currently bound to @var{target}. Data starting at byte
1551 offset @var{offset} and extending for @var{size} bytes is copied to the
1552 data store from the memory pointed to by @var{data}. An error is thrown
1553 if @var{offset} and @var{size} together define a range beyond the bounds
1554 of the buffer object's data store.
1556 @code{GL_INVALID_ENUM} is generated if @var{target} is not
1557 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
1558 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
1560 @code{GL_INVALID_VALUE} is generated if @var{offset} or @var{size} is
1561 negative, or if together they define a region of memory that extends
1562 beyond the buffer object's allocated data store.
1564 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
1565 name 0 is bound to @var{target}.
1567 @code{GL_INVALID_OPERATION} is generated if the buffer object being
1570 @code{GL_INVALID_OPERATION} is generated if @code{glBufferSubData} is
1571 executed between the execution of @code{glBegin} and the corresponding
1572 execution of @code{glEnd}.
1576 @deftypefun void glCallLists n type lists
1577 Execute a list of display lists.
1581 Specifies the number of display lists to be executed.
1584 Specifies the type of values in @var{lists}. Symbolic constants
1585 @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
1586 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
1587 @code{GL_FLOAT}, @code{GL_2_BYTES}, @code{GL_3_BYTES}, and
1588 @code{GL_4_BYTES} are accepted.
1591 Specifies the address of an array of name offsets in the display list.
1592 The pointer type is void because the offsets can be bytes, shorts, ints,
1593 or floats, depending on the value of @var{type}.
1597 @code{glCallLists} causes each display list in the list of names passed
1598 as @var{lists} to be executed. As a result, the commands saved in each
1599 display list are executed in order, just as if they were called without
1600 using a display list. Names of display lists that have not been defined
1603 @code{glCallLists} provides an efficient means for executing more than
1604 one display list. @var{type} allows lists with various name formats to
1605 be accepted. The formats are as follows:
1608 @item @code{GL_BYTE}
1609 @var{lists} is treated as an array of signed bytes, each in the range
1610 @r{-128} through 127.
1612 @item @code{GL_UNSIGNED_BYTE}
1613 @var{lists} is treated as an array of unsigned bytes, each in the range
1616 @item @code{GL_SHORT}
1617 @var{lists} is treated as an array of signed two-byte integers, each in
1618 the range @r{-32768} through 32767.
1620 @item @code{GL_UNSIGNED_SHORT}
1621 @var{lists} is treated as an array of unsigned two-byte integers, each
1622 in the range 0 through 65535.
1625 @var{lists} is treated as an array of signed four-byte integers.
1627 @item @code{GL_UNSIGNED_INT}
1628 @var{lists} is treated as an array of unsigned four-byte integers.
1630 @item @code{GL_FLOAT}
1631 @var{lists} is treated as an array of four-byte floating-point values.
1633 @item @code{GL_2_BYTES}
1634 @var{lists} is treated as an array of unsigned bytes. Each pair of bytes
1635 specifies a single display-list name. The value of the pair is computed
1636 as 256 times the unsigned value of the first byte plus the unsigned
1637 value of the second byte.
1639 @item @code{GL_3_BYTES}
1640 @var{lists} is treated as an array of unsigned bytes. Each triplet of
1641 bytes specifies a single display-list name. The value of the triplet is
1642 computed as 65536 times the unsigned value of the first byte, plus 256
1643 times the unsigned value of the second byte, plus the unsigned value of
1646 @item @code{GL_4_BYTES}
1647 @var{lists} is treated as an array of unsigned bytes. Each quadruplet of
1648 bytes specifies a single display-list name. The value of the quadruplet
1649 is computed as 16777216 times the unsigned value of the first byte, plus
1650 65536 times the unsigned value of the second byte, plus 256 times the
1651 unsigned value of the third byte, plus the unsigned value of the fourth
1656 The list of display-list names is not null-terminated. Rather, @var{n}
1657 specifies how many names are to be taken from @var{lists}.
1659 An additional level of indirection is made available with the
1660 @code{glListBase} command, which specifies an unsigned offset that is
1661 added to each display-list name specified in @var{lists} before that
1662 display list is executed.
1664 @code{glCallLists} can appear inside a display list. To avoid the
1665 possibility of infinite recursion resulting from display lists calling
1666 one another, a limit is placed on the nesting level of display lists
1667 during display-list execution. This limit must be at least 64, and it
1668 depends on the implementation.
1670 GL state is not saved and restored across a call to @code{glCallLists}.
1671 Thus, changes made to GL state during the execution of the display lists
1672 remain after execution is completed. Use @code{glPushAttrib},
1673 @code{glPopAttrib}, @code{glPushMatrix}, and @code{glPopMatrix} to
1674 preserve GL state across @code{glCallLists} calls.
1676 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
1678 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of
1679 @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
1680 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
1681 @code{GL_FLOAT}, @code{GL_2_BYTES}, @code{GL_3_BYTES},
1686 @deftypefun void glCallList list
1687 Execute a display list.
1691 Specifies the integer name of the display list to be executed.
1695 @code{glCallList} causes the named display list to be executed. The
1696 commands saved in the display list are executed in order, just as if
1697 they were called without using a display list. If @var{list} has not
1698 been defined as a display list, @code{glCallList} is ignored.
1700 @code{glCallList} can appear inside a display list. To avoid the
1701 possibility of infinite recursion resulting from display lists calling
1702 one another, a limit is placed on the nesting level of display lists
1703 during display-list execution. This limit is at least 64, and it depends
1704 on the implementation.
1706 GL state is not saved and restored across a call to @code{glCallList}.
1707 Thus, changes made to GL state during the execution of a display list
1708 remain after execution of the display list is completed. Use
1709 @code{glPushAttrib}, @code{glPopAttrib}, @code{glPushMatrix}, and
1710 @code{glPopMatrix} to preserve GL state across @code{glCallList} calls.
1714 @deftypefun void glClearAccum red green blue alpha
1715 Specify clear values for the accumulation buffer.
1722 Specify the red, green, blue, and alpha values used when the
1723 accumulation buffer is cleared. The initial values are all 0.
1727 @code{glClearAccum} specifies the red, green, blue, and alpha values
1728 used by @code{glClear} to clear the accumulation buffer.
1730 Values specified by @code{glClearAccum} are clamped to the range
1733 @code{GL_INVALID_OPERATION} is generated if @code{glClearAccum} is
1734 executed between the execution of @code{glBegin} and the corresponding
1735 execution of @code{glEnd}.
1739 @deftypefun void glClearColor red green blue alpha
1740 Specify clear values for the color buffers.
1747 Specify the red, green, blue, and alpha values used when the color
1748 buffers are cleared. The initial values are all 0.
1752 @code{glClearColor} specifies the red, green, blue, and alpha values
1753 used by @code{glClear} to clear the color buffers. Values specified by
1754 @code{glClearColor} are clamped to the range @r{[0,1]}.
1756 @code{GL_INVALID_OPERATION} is generated if @code{glClearColor} is
1757 executed between the execution of @code{glBegin} and the corresponding
1758 execution of @code{glEnd}.
1762 @deftypefun void glClearDepth depth
1763 Specify the clear value for the depth buffer.
1767 Specifies the depth value used when the depth buffer is cleared. The
1772 @code{glClearDepth} specifies the depth value used by @code{glClear} to
1773 clear the depth buffer. Values specified by @code{glClearDepth} are
1774 clamped to the range @r{[0,1]}.
1776 @code{GL_INVALID_OPERATION} is generated if @code{glClearDepth} is
1777 executed between the execution of @code{glBegin} and the corresponding
1778 execution of @code{glEnd}.
1782 @deftypefun void glClearIndex c
1783 Specify the clear value for the color index buffers.
1787 Specifies the index used when the color index buffers are cleared. The
1792 @code{glClearIndex} specifies the index used by @code{glClear} to clear
1793 the color index buffers. @var{c} is not clamped. Rather, @var{c} is
1794 converted to a fixed-point value with unspecified precision to the right
1795 of the binary point. The integer part of this value is then masked with
1796 @r{2^@var{m}-1}, where @r{@var{m}} is the number of bits in a color
1797 index stored in the frame buffer.
1799 @code{GL_INVALID_OPERATION} is generated if @code{glClearIndex} is
1800 executed between the execution of @code{glBegin} and the corresponding
1801 execution of @code{glEnd}.
1805 @deftypefun void glClearStencil s
1806 Specify the clear value for the stencil buffer.
1810 Specifies the index used when the stencil buffer is cleared. The initial
1815 @code{glClearStencil} specifies the index used by @code{glClear} to
1816 clear the stencil buffer. @var{s} is masked with @r{2^@var{m}-1}, where
1817 @r{@var{m}} is the number of bits in the stencil buffer.
1819 @code{GL_INVALID_OPERATION} is generated if @code{glClearStencil} is
1820 executed between the execution of @code{glBegin} and the corresponding
1821 execution of @code{glEnd}.
1825 @deftypefun void glClear mask
1826 Clear buffers to preset values.
1830 Bitwise OR of masks that indicate the buffers to be cleared. The four
1831 masks are @code{GL_COLOR_BUFFER_BIT}, @code{GL_DEPTH_BUFFER_BIT},
1832 @code{GL_ACCUM_BUFFER_BIT}, and @code{GL_STENCIL_BUFFER_BIT}.
1836 @code{glClear} sets the bitplane area of the window to values previously
1837 selected by @code{glClearColor}, @code{glClearIndex},
1838 @code{glClearDepth}, @code{glClearStencil}, and @code{glClearAccum}.
1839 Multiple color buffers can be cleared simultaneously by selecting more
1840 than one buffer at a time using @code{glDrawBuffer}.
1842 The pixel ownership test, the scissor test, dithering, and the buffer
1843 writemasks affect the operation of @code{glClear}. The scissor box
1844 bounds the cleared region. Alpha function, blend function, logical
1845 operation, stenciling, texture mapping, and depth-buffering are ignored
1848 @code{glClear} takes a single argument that is the bitwise OR of several
1849 values indicating which buffer is to be cleared.
1851 The values are as follows:
1854 @item @code{GL_COLOR_BUFFER_BIT}
1855 Indicates the buffers currently enabled for color writing.
1857 @item @code{GL_DEPTH_BUFFER_BIT}
1858 Indicates the depth buffer.
1860 @item @code{GL_ACCUM_BUFFER_BIT}
1861 Indicates the accumulation buffer.
1863 @item @code{GL_STENCIL_BUFFER_BIT}
1864 Indicates the stencil buffer.
1868 The value to which each buffer is cleared depends on the setting of the
1869 clear value for that buffer.
1871 @code{GL_INVALID_VALUE} is generated if any bit other than the four
1872 defined bits is set in @var{mask}.
1874 @code{GL_INVALID_OPERATION} is generated if @code{glClear} is executed
1875 between the execution of @code{glBegin} and the corresponding execution
1880 @deftypefun void glClientActiveTexture texture
1881 Select active texture unit.
1885 Specifies which texture unit to make active. The number of texture units
1886 is implementation dependent, but must be at least two. @var{texture}
1887 must be one of @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to
1888 the value of @code{GL_MAX_TEXTURE_COORDS} - 1, which is an
1889 implementation-dependent value. The initial value is @code{GL_TEXTURE0}.
1893 @code{glClientActiveTexture} selects the vertex array client state
1894 parameters to be modified by @code{glTexCoordPointer}, and enabled or
1895 disabled with @code{glEnableClientState} or @code{glDisableClientState},
1896 respectively, when called with a parameter of
1897 @code{GL_TEXTURE_COORD_ARRAY}.
1899 @code{GL_INVALID_ENUM} is generated if @var{texture} is not one of
1900 @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to the value of
1901 @code{GL_MAX_TEXTURE_COORDS} - 1.
1905 @deftypefun void glClipPlane plane equation
1906 Specify a plane against which all geometry is clipped.
1910 Specifies which clipping plane is being positioned. Symbolic names of
1911 the form @code{GL_CLIP_PLANE}@var{i}, where @var{i} is an integer
1912 between 0 and @code{GL_MAX_CLIP_PLANES}@r{-1}, are accepted.
1914 @item @var{equation}
1915 Specifies the address of an array of four double-precision
1916 floating-point values. These values are interpreted as a plane equation.
1920 Geometry is always clipped against the boundaries of a six-plane frustum
1921 in @var{x}, @var{y}, and @var{z}. @code{glClipPlane} allows the
1922 specification of additional planes, not necessarily perpendicular to the
1923 @var{x}, @var{y}, or @var{z} axis, against which all geometry is
1924 clipped. To determine the maximum number of additional clipping planes,
1925 call @code{glGetIntegerv} with argument @code{GL_MAX_CLIP_PLANES}. All
1926 implementations support at least six such clipping planes. Because the
1927 resulting clipping region is the intersection of the defined
1928 half-spaces, it is always convex.
1930 @code{glClipPlane} specifies a half-space using a four-component plane
1931 equation. When @code{glClipPlane} is called, @var{equation} is
1932 transformed by the inverse of the modelview matrix and stored in the
1933 resulting eye coordinates. Subsequent changes to the modelview matrix
1934 have no effect on the stored plane-equation components. If the dot
1935 product of the eye coordinates of a vertex with the stored plane
1936 equation components is positive or zero, the vertex is @var{in} with
1937 respect to that clipping plane. Otherwise, it is @var{out}.
1939 To enable and disable clipping planes, call @code{glEnable} and
1940 @code{glDisable} with the argument @code{GL_CLIP_PLANE}@var{i}, where
1941 @var{i} is the plane number.
1943 All clipping planes are initially defined as (0, 0, 0, 0) in eye
1944 coordinates and are disabled.
1946 @code{GL_INVALID_ENUM} is generated if @var{plane} is not an accepted
1949 @code{GL_INVALID_OPERATION} is generated if @code{glClipPlane} is
1950 executed between the execution of @code{glBegin} and the corresponding
1951 execution of @code{glEnd}.
1955 @deftypefun void glColorMask red green blue alpha
1956 Enable and disable writing of frame buffer color components.
1963 Specify whether red, green, blue, and alpha can or cannot be written
1964 into the frame buffer. The initial values are all @code{GL_TRUE},
1965 indicating that the color components can be written.
1969 @code{glColorMask} specifies whether the individual color components in
1970 the frame buffer can or cannot be written. If @var{red} is
1971 @code{GL_FALSE}, for example, no change is made to the red component of
1972 any pixel in any of the color buffers, regardless of the drawing
1973 operation attempted.
1975 Changes to individual bits of components cannot be controlled. Rather,
1976 changes are either enabled or disabled for entire color components.
1978 @code{GL_INVALID_OPERATION} is generated if @code{glColorMask} is
1979 executed between the execution of @code{glBegin} and the corresponding
1980 execution of @code{glEnd}.
1984 @deftypefun void glColorMaterial face mode
1985 Cause a material color to track the current color.
1989 Specifies whether front, back, or both front and back material
1990 parameters should track the current color. Accepted values are
1991 @code{GL_FRONT}, @code{GL_BACK}, and @code{GL_FRONT_AND_BACK}. The
1992 initial value is @code{GL_FRONT_AND_BACK}.
1995 Specifies which of several material parameters track the current color.
1996 Accepted values are @code{GL_EMISSION}, @code{GL_AMBIENT},
1997 @code{GL_DIFFUSE}, @code{GL_SPECULAR}, and
1998 @code{GL_AMBIENT_AND_DIFFUSE}. The initial value is
1999 @code{GL_AMBIENT_AND_DIFFUSE}.
2003 @code{glColorMaterial} specifies which material parameters track the
2004 current color. When @code{GL_COLOR_MATERIAL} is enabled, the material
2005 parameter or parameters specified by @var{mode}, of the material or
2006 materials specified by @var{face}, track the current color at all times.
2008 To enable and disable @code{GL_COLOR_MATERIAL}, call @code{glEnable} and
2009 @code{glDisable} with argument @code{GL_COLOR_MATERIAL}.
2010 @code{GL_COLOR_MATERIAL} is initially disabled.
2012 @code{GL_INVALID_ENUM} is generated if @var{face} or @var{mode} is not
2015 @code{GL_INVALID_OPERATION} is generated if @code{glColorMaterial} is
2016 executed between the execution of @code{glBegin} and the corresponding
2017 execution of @code{glEnd}.
2021 @deftypefun void glColorPointer size type stride pointer
2022 Define an array of colors.
2026 Specifies the number of components per color. Must be 3 or 4. The
2030 Specifies the data type of each color component in the array. Symbolic
2031 constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
2032 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
2033 @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value is
2037 Specifies the byte offset between consecutive colors. If @var{stride} is
2038 0, the colors are understood to be tightly packed in the array. The
2042 Specifies a pointer to the first component of the first color element in
2043 the array. The initial value is 0.
2047 @code{glColorPointer} specifies the location and data format of an array
2048 of color components to use when rendering. @var{size} specifies the
2049 number of components per color, and must be 3 or 4. @var{type} specifies
2050 the data type of each color component, and @var{stride} specifies the
2051 byte stride from one color to the next, allowing vertices and attributes
2052 to be packed into a single array or stored in separate arrays.
2053 (Single-array storage may be more efficient on some implementations; see
2054 @code{glInterleavedArrays}.)
2056 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
2057 target (see @code{glBindBuffer}) while a color array is specified,
2058 @var{pointer} is treated as a byte offset into the buffer object's data
2059 store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING})
2060 is saved as color vertex array client-side state
2061 (@code{GL_COLOR_ARRAY_BUFFER_BINDING}).
2063 When a color array is specified, @var{size}, @var{type}, @var{stride},
2064 and @var{pointer} are saved as client-side state, in addition to the
2065 current vertex array buffer object binding.
2067 To enable and disable the color array, call @code{glEnableClientState}
2068 and @code{glDisableClientState} with the argument @code{GL_COLOR_ARRAY}.
2069 If enabled, the color array is used when @code{glDrawArrays},
2070 @code{glMultiDrawArrays}, @code{glDrawElements},
2071 @code{glMultiDrawElements}, @code{glDrawRangeElements}, or
2072 @code{glArrayElement} is called.
2074 @code{GL_INVALID_VALUE} is generated if @var{size} is not 3 or 4.
2076 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
2079 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
2083 @deftypefun void glColorSubTable target start count format type data
2084 Respecify a portion of a color table.
2088 Must be one of @code{GL_COLOR_TABLE},
2089 @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
2090 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}.
2093 The starting index of the portion of the color table to be replaced.
2096 The number of table entries to replace.
2099 The format of the pixel data in @var{data}. The allowable values are
2100 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
2101 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB},
2102 @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}.
2105 The type of the pixel data in @var{data}. The allowable values are
2106 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT},
2107 @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT},
2108 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
2109 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
2110 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
2111 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
2112 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
2113 @code{GL_UNSIGNED_INT_10_10_10_2}, and
2114 @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
2117 Pointer to a one-dimensional array of pixel data that is processed to
2118 replace the specified region of the color table.
2122 @code{glColorSubTable} is used to respecify a contiguous portion of a
2123 color table previously defined using @code{glColorTable}. The pixels
2124 referenced by @var{data} replace the portion of the existing table from
2125 indices @var{start} to @r{@var{start}+@var{count}-1}, inclusive. This
2126 region may not include any entries outside the range of the color table
2127 as it was originally specified. It is not an error to specify a
2128 subtexture with width of 0, but such a specification has no effect.
2130 If a non-zero named buffer object is bound to the
2131 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2132 portion of a color table is respecified, @var{data} is treated as a byte
2133 offset into the buffer object's data store.
2135 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
2138 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
2141 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
2144 @code{GL_INVALID_VALUE} is generated if
2145 @r{@var{start}+@var{count}>@var{width}}.
2147 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2148 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2149 object's data store is currently mapped.
2151 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2152 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2153 would be unpacked from the buffer object such that the memory reads
2154 required would exceed the data store size.
2156 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2157 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
2158 is not evenly divisible into the number of bytes needed to store in
2159 memory a datum indicated by @var{type}.
2161 @code{GL_INVALID_OPERATION} is generated if @code{glColorSubTable} is
2162 executed between the execution of @code{glBegin} and the corresponding
2163 execution of @code{glEnd}.
2167 @deftypefun void glColorTable target internalformat width format type data
2168 Define a color lookup table.
2172 Must be one of @code{GL_COLOR_TABLE},
2173 @code{GL_POST_CONVOLUTION_COLOR_TABLE},
2174 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{GL_PROXY_COLOR_TABLE},
2175 @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or
2176 @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}.
2178 @item @var{internalformat}
2179 The internal format of the color table. The allowable values are
2180 @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
2181 @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
2182 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
2183 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
2184 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
2185 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
2186 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY},
2187 @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12},
2188 @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
2189 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
2190 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
2191 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
2192 @code{GL_RGBA12}, and @code{GL_RGBA16}.
2195 The number of entries in the color lookup table specified by @var{data}.
2198 The format of the pixel data in @var{data}. The allowable values are
2199 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
2200 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB},
2201 @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}.
2204 The type of the pixel data in @var{data}. The allowable values are
2205 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT},
2206 @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT},
2207 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
2208 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
2209 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
2210 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
2211 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
2212 @code{GL_UNSIGNED_INT_10_10_10_2}, and
2213 @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
2216 Pointer to a one-dimensional array of pixel data that is processed to
2217 build the color table.
2221 @code{glColorTable} may be used in two ways: to test the actual size and
2222 color resolution of a lookup table given a particular set of parameters,
2223 or to load the contents of a color lookup table. Use the targets
2224 @code{GL_PROXY_*} for the first case and the other targets for the
2227 If a non-zero named buffer object is bound to the
2228 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2229 color table is specified, @var{data} is treated as a byte offset into
2230 the buffer object's data store.
2232 If @var{target} is @code{GL_COLOR_TABLE},
2233 @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
2234 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{glColorTable} builds a
2235 color lookup table from an array of pixels. The pixel array specified by
2236 @var{width}, @var{format}, @var{type}, and @var{data} is extracted from
2237 memory and processed just as if @code{glDrawPixels} were called, but
2238 processing stops after the final expansion to RGBA is completed.
2240 The four scale parameters and the four bias parameters that are defined
2241 for the table are then used to scale and bias the R, G, B, and A
2242 components of each pixel. (Use @code{glColorTableParameter} to set these
2243 scale and bias parameters.)
2245 Next, the R, G, B, and A values are clamped to the range @r{[0,1]}. Each
2246 pixel is then converted to the internal format specified by
2247 @var{internalformat}. This conversion simply maps the component values
2248 of the pixel (R, G, B, and A) to the values included in the internal
2249 format (red, green, blue, alpha, luminance, and intensity). The mapping
2255 @item @strong{Internal Format}
2256 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
2257 @strong{Luminance}, @strong{Intensity}
2259 @item @code{GL_ALPHA}
2262 @item @code{GL_LUMINANCE}
2265 @item @code{GL_LUMINANCE_ALPHA}
2268 @item @code{GL_INTENSITY}
2274 @item @code{GL_RGBA}
2279 Finally, the red, green, blue, alpha, luminance, and/or intensity
2280 components of the resulting pixels are stored in the color table. They
2281 form a one-dimensional table with indices in the range
2282 @r{[0,@var{width}-1]}.
2284 If @var{target} is @code{GL_PROXY_*}, @code{glColorTable} recomputes and
2285 stores the values of the proxy color table's state variables
2286 @code{GL_COLOR_TABLE_FORMAT}, @code{GL_COLOR_TABLE_WIDTH},
2287 @code{GL_COLOR_TABLE_RED_SIZE}, @code{GL_COLOR_TABLE_GREEN_SIZE},
2288 @code{GL_COLOR_TABLE_BLUE_SIZE}, @code{GL_COLOR_TABLE_ALPHA_SIZE},
2289 @code{GL_COLOR_TABLE_LUMINANCE_SIZE}, and
2290 @code{GL_COLOR_TABLE_INTENSITY_SIZE}. There is no effect on the image or
2291 state of any actual color table. If the specified color table is too
2292 large to be supported, then all the proxy state variables listed above
2293 are set to zero. Otherwise, the color table could be supported by
2294 @code{glColorTable} using the corresponding non-proxy target, and the
2295 proxy state variables are set as if that target were being defined.
2297 The proxy state variables can be retrieved by calling
2298 @code{glGetColorTableParameter} with a target of @code{GL_PROXY_*}. This
2299 allows the application to decide if a particular @code{glColorTable}
2300 command would succeed, and to determine what the resulting color table
2301 attributes would be.
2303 If a color table is enabled, and its width is non-zero, then its
2304 contents are used to replace a subset of the components of each RGBA
2305 pixel group, based on the internal format of the table.
2307 Each pixel group has color components (R, G, B, A) that are in the range
2308 @r{[0.0,1.0]}. The color components are rescaled to the size of the
2309 color lookup table to form an index. Then a subset of the components
2310 based on the internal format of the table are replaced by the table
2311 entry selected by that index. If the color components and contents of
2312 the table are represented as follows:
2317 @item @strong{Representation}
2321 Table index computed from @code{R}
2324 Table index computed from @code{G}
2327 Table index computed from @code{B}
2330 Table index computed from @code{A}
2333 Luminance value at table index @code{i}
2336 Intensity value at table index @code{i}
2339 Red value at table index @code{i}
2342 Green value at table index @code{i}
2345 Blue value at table index @code{i}
2348 Alpha value at table index @code{i}
2352 then the result of color table lookup is as follows:
2358 @strong{Resulting Texture Components}
2360 @item @strong{Table Internal Format}
2361 @strong{R}, @strong{G}, @strong{B}, @strong{A}
2363 @item @code{GL_ALPHA}
2364 @code{R}, @code{G}, @code{B}, @code{A[a]}
2366 @item @code{GL_LUMINANCE}
2367 @code{L[r]}, @code{L[g]}, @code{L[b]}, @code{At}
2369 @item @code{GL_LUMINANCE_ALPHA}
2370 @code{L[r]}, @code{L[g]}, @code{L[b]}, @code{A[a]}
2372 @item @code{GL_INTENSITY}
2373 @code{I[r]}, @code{I[g]}, @code{I[b]}, @code{I[a]}
2376 @code{R[r]}, @code{G[g]}, @code{B[b]}, @code{A}
2378 @item @code{GL_RGBA}
2379 @code{R[r]}, @code{G[g]}, @code{B[b]}, @code{A[a]}
2383 When @code{GL_COLOR_TABLE} is enabled, the colors resulting from the
2384 pixel map operation (if it is enabled) are mapped by the color lookup
2385 table before being passed to the convolution operation. The colors
2386 resulting from the convolution operation are modified by the post
2387 convolution color lookup table when
2388 @code{GL_POST_CONVOLUTION_COLOR_TABLE} is enabled. These modified colors
2389 are then sent to the color matrix operation. Finally, if
2390 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} is enabled, the colors resulting
2391 from the color matrix operation are mapped by the post color matrix
2392 color lookup table before being used by the histogram operation.
2396 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
2399 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
2400 of the allowable values.
2402 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
2405 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
2408 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero.
2410 @code{GL_TABLE_TOO_LARGE} is generated if the requested color table is
2411 too large to be supported by the implementation, and @var{target} is not
2412 a @code{GL_PROXY_*} target.
2414 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2415 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2416 object's data store is currently mapped.
2418 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2419 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2420 would be unpacked from the buffer object such that the memory reads
2421 required would exceed the data store size.
2423 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2424 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
2425 is not evenly divisible into the number of bytes needed to store in
2426 memory a datum indicated by @var{type}.
2428 @code{GL_INVALID_OPERATION} is generated if @code{glColorTable} is
2429 executed between the execution of @code{glBegin} and the corresponding
2430 execution of @code{glEnd}.
2434 @deftypefun void glColor3i red green blue
2435 @deftypefunx void glColor3f red green blue
2436 @deftypefunx void glColor3ui red green blue
2437 @deftypefunx void glColor4i red green blue alpha
2438 @deftypefunx void glColor4f red green blue alpha
2439 @deftypefunx void glColor4ui red green blue alpha
2440 Set the current color.
2446 Specify new red, green, and blue values for the current color.
2449 Specifies a new alpha value for the current color. Included only in the
2450 four-argument @code{glColor4} commands.
2454 The GL stores both a current single-valued color index and a current
2455 four-valued RGBA color. @code{glColor} sets a new four-valued RGBA
2456 color. @code{glColor} has two major variants: @code{glColor3} and
2457 @code{glColor4}. @code{glColor3} variants specify new red, green, and
2458 blue values explicitly and set the current alpha value to 1.0 (full
2459 intensity) implicitly. @code{glColor4} variants specify all four color
2460 components explicitly.
2462 @code{glColor3b}, @code{glColor4b}, @code{glColor3s}, @code{glColor4s},
2463 @code{glColor3i}, and @code{glColor4i} take three or four signed byte,
2464 short, or long integers as arguments. When @strong{v} is appended to the
2465 name, the color commands can take a pointer to an array of such values.
2467 Current color values are stored in floating-point format, with
2468 unspecified mantissa and exponent sizes. Unsigned integer color
2469 components, when specified, are linearly mapped to floating-point values
2470 such that the largest representable value maps to 1.0 (full intensity),
2471 and 0 maps to 0.0 (zero intensity). Signed integer color components,
2472 when specified, are linearly mapped to floating-point values such that
2473 the most positive representable value maps to 1.0, and the most negative
2474 representable value maps to @r{-1.0}. (Note that this mapping does not
2475 convert 0 precisely to 0.0.) Floating-point values are mapped directly.
2477 Neither floating-point nor signed integer values are clamped to the
2478 range @r{[0,1]} before the current color is updated. However, color
2479 components are clamped to this range before they are interpolated or
2480 written into a color buffer.
2484 @deftypefun void glCompileShader shader
2485 Compiles a shader object.
2489 Specifies the shader object to be compiled.
2493 @code{glCompileShader} compiles the source code strings that have been
2494 stored in the shader object specified by @var{shader}.
2496 The compilation status will be stored as part of the shader object's
2497 state. This value will be set to @code{GL_TRUE} if the shader was
2498 compiled without errors and is ready for use, and @code{GL_FALSE}
2499 otherwise. It can be queried by calling @code{glGetShader} with
2500 arguments @var{shader} and @code{GL_COMPILE_STATUS}.
2502 Compilation of a shader can fail for a number of reasons as specified by
2503 the OpenGL Shading Language Specification. Whether or not the
2504 compilation was successful, information about the compilation can be
2505 obtained from the shader object's information log by calling
2506 @code{glGetShaderInfoLog}.
2508 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
2509 generated by OpenGL.
2511 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
2514 @code{GL_INVALID_OPERATION} is generated if @code{glCompileShader} is
2515 executed between the execution of @code{glBegin} and the corresponding
2516 execution of @code{glEnd}.
2520 @deftypefun void glCompressedTexImage1D target level internalformat width border imageSize data
2521 Specify a one-dimensional texture image in a compressed format.
2525 Specifies the target texture. Must be @code{GL_TEXTURE_1D} or
2526 @code{GL_PROXY_TEXTURE_1D}.
2529 Specifies the level-of-detail number. Level 0 is the base image level.
2530 Level @var{n} is the @var{n}th mipmap reduction image.
2532 @item @var{internalformat}
2533 Specifies the format of the compressed image data stored at address
2537 Specifies the width of the texture image including the border if any. If
2538 the GL version does not support non-power-of-two sizes, this value must
2539 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
2540 implementations support texture images that are at least 64 texels wide.
2541 The height of the 1D texture image is 1.
2544 Specifies the width of the border. Must be either 0 or 1.
2546 @item @var{imageSize}
2547 Specifies the number of unsigned bytes of image data starting at the
2548 address specified by @var{data}.
2551 Specifies a pointer to the compressed image data in memory.
2555 Texturing maps a portion of a specified texture image onto each
2556 graphical primitive for which texturing is enabled. To enable and
2557 disable one-dimensional texturing, call @code{glEnable} and
2558 @code{glDisable} with argument @code{GL_TEXTURE_1D}.
2560 @code{glCompressedTexImage1D} loads a previously defined, and retrieved,
2561 compressed one-dimensional texture image if @var{target} is
2562 @code{GL_TEXTURE_1D} (see @code{glTexImage1D}).
2564 If @var{target} is @code{GL_PROXY_TEXTURE_1D}, no data is read from
2565 @var{data}, but all of the texture image state is recalculated, checked
2566 for consistency, and checked against the implementation's capabilities.
2567 If the implementation cannot handle a texture of the requested texture
2568 size, it sets all of the image state to 0, but does not generate an
2569 error (see @code{glGetError}). To query for an entire mipmap array, use
2570 an image array level greater than or equal to 1.
2572 @var{internalformat} must be extension-specified compressed-texture
2573 format. When a texture is loaded with @code{glTexImage1D} using a
2574 generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}) the
2575 GL selects from one of its extensions supporting compressed textures. In
2576 order to load the compressed texture image using
2577 @code{glCompressedTexImage1D}, query the compressed texture image's size
2578 and format using @code{glGetTexLevelParameter}.
2580 If a non-zero named buffer object is bound to the
2581 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2582 texture image is specified, @var{data} is treated as a byte offset into
2583 the buffer object's data store.
2585 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of
2586 the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
2587 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
2588 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or
2589 @code{GL_COMPRESSED_RGBA}.
2591 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
2592 consistent with the format, dimensions, and contents of the specified
2593 compressed image data.
2595 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
2596 not supported by the specific compressed internal format as specified in
2597 the specific texture compression extension.
2599 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2600 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2601 object's data store is currently mapped.
2603 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2604 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2605 would be unpacked from the buffer object such that the memory reads
2606 required would exceed the data store size.
2608 @code{GL_INVALID_OPERATION} is generated if
2609 @code{glCompressedTexImage1D} is executed between the execution of
2610 @code{glBegin} and the corresponding execution of @code{glEnd}.
2612 Undefined results, including abnormal program termination, are generated
2613 if @var{data} is not encoded in a manner consistent with the extension
2614 specification defining the internal compression format.
2618 @deftypefun void glCompressedTexImage2D target level internalformat width height border imageSize data
2619 Specify a two-dimensional texture image in a compressed format.
2623 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
2624 @code{GL_PROXY_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
2625 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
2626 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
2627 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
2628 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z},
2629 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or
2630 @code{GL_PROXY_TEXTURE_CUBE_MAP}.
2633 Specifies the level-of-detail number. Level 0 is the base image level.
2634 Level @var{n} is the @var{n}th mipmap reduction image.
2636 @item @var{internalformat}
2637 Specifies the format of the compressed image data stored at address
2641 Specifies the width of the texture image including the border if any. If
2642 the GL version does not support non-power-of-two sizes, this value must
2643 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
2644 implementations support 2D texture images that are at least 64 texels
2645 wide and cube-mapped texture images that are at least 16 texels wide.
2648 Specifies the height of the texture image including the border if any.
2649 If the GL version does not support non-power-of-two sizes, this value
2650 must be Must be @r{2^@var{n}+2(@var{border},)} for some integer
2651 @r{@var{n}}. All implementations support 2D texture images that are at
2652 least 64 texels high and cube-mapped texture images that are at least 16
2656 Specifies the width of the border. Must be either 0 or 1.
2658 @item @var{imageSize}
2659 Specifies the number of unsigned bytes of image data starting at the
2660 address specified by @var{data}.
2663 Specifies a pointer to the compressed image data in memory.
2667 Texturing maps a portion of a specified texture image onto each
2668 graphical primitive for which texturing is enabled. To enable and
2669 disable two-dimensional texturing, call @code{glEnable} and
2670 @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and
2671 disable texturing using cube-mapped textures, call @code{glEnable} and
2672 @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}.
2674 @code{glCompressedTexImage2D} loads a previously defined, and retrieved,
2675 compressed two-dimensional texture image if @var{target} is
2676 @code{GL_TEXTURE_2D} (see @code{glTexImage2D}).
2678 If @var{target} is @code{GL_PROXY_TEXTURE_2D}, no data is read from
2679 @var{data}, but all of the texture image state is recalculated, checked
2680 for consistency, and checked against the implementation's capabilities.
2681 If the implementation cannot handle a texture of the requested texture
2682 size, it sets all of the image state to 0, but does not generate an
2683 error (see @code{glGetError}). To query for an entire mipmap array, use
2684 an image array level greater than or equal to 1.
2686 @var{internalformat} must be an extension-specified compressed-texture
2687 format. When a texture is loaded with @code{glTexImage2D} using a
2688 generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}), the
2689 GL selects from one of its extensions supporting compressed textures. In
2690 order to load the compressed texture image using
2691 @code{glCompressedTexImage2D}, query the compressed texture image's size
2692 and format using @code{glGetTexLevelParameter}.
2694 If a non-zero named buffer object is bound to the
2695 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2696 texture image is specified, @var{data} is treated as a byte offset into
2697 the buffer object's data store.
2699 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of
2700 the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
2701 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
2702 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or
2703 @code{GL_COMPRESSED_RGBA}.
2705 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
2706 consistent with the format, dimensions, and contents of the specified
2707 compressed image data.
2709 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
2710 not supported by the specific compressed internal format as specified in
2711 the specific texture compression extension.
2713 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2714 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2715 object's data store is currently mapped.
2717 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2718 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2719 would be unpacked from the buffer object such that the memory reads
2720 required would exceed the data store size.
2722 @code{GL_INVALID_OPERATION} is generated if
2723 @code{glCompressedTexImage2D} is executed between the execution of
2724 @code{glBegin} and the corresponding execution of @code{glEnd}.
2726 Undefined results, including abnormal program termination, are generated
2727 if @var{data} is not encoded in a manner consistent with the extension
2728 specification defining the internal compression format.
2732 @deftypefun void glCompressedTexImage3D target level internalformat width height depth border imageSize data
2733 Specify a three-dimensional texture image in a compressed format.
2737 Specifies the target texture. Must be @code{GL_TEXTURE_3D} or
2738 @code{GL_PROXY_TEXTURE_3D}.
2741 Specifies the level-of-detail number. Level 0 is the base image level.
2742 Level @var{n} is the @var{n}th mipmap reduction image.
2744 @item @var{internalformat}
2745 Specifies the format of the compressed image data stored at address
2749 Specifies the width of the texture image including the border if any. If
2750 the GL version does not support non-power-of-two sizes, this value must
2751 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
2752 implementations support 3D texture images that are at least 16 texels
2756 Specifies the height of the texture image including the border if any.
2757 If the GL version does not support non-power-of-two sizes, this value
2758 must be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}.
2759 All implementations support 3D texture images that are at least 16
2763 Specifies the depth of the texture image including the border if any. If
2764 the GL version does not support non-power-of-two sizes, this value must
2765 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
2766 implementations support 3D texture images that are at least 16 texels
2770 Specifies the width of the border. Must be either 0 or 1.
2772 @item @var{imageSize}
2773 Specifies the number of unsigned bytes of image data starting at the
2774 address specified by @var{data}.
2777 Specifies a pointer to the compressed image data in memory.
2781 Texturing maps a portion of a specified texture image onto each
2782 graphical primitive for which texturing is enabled. To enable and
2783 disable three-dimensional texturing, call @code{glEnable} and
2784 @code{glDisable} with argument @code{GL_TEXTURE_3D}.
2786 @code{glCompressedTexImage3D} loads a previously defined, and retrieved,
2787 compressed three-dimensional texture image if @var{target} is
2788 @code{GL_TEXTURE_3D} (see @code{glTexImage3D}).
2790 If @var{target} is @code{GL_PROXY_TEXTURE_3D}, no data is read from
2791 @var{data}, but all of the texture image state is recalculated, checked
2792 for consistency, and checked against the implementation's capabilities.
2793 If the implementation cannot handle a texture of the requested texture
2794 size, it sets all of the image state to 0, but does not generate an
2795 error (see @code{glGetError}). To query for an entire mipmap array, use
2796 an image array level greater than or equal to 1.
2798 @var{internalformat} must be an extension-specified compressed-texture
2799 format. When a texture is loaded with @code{glTexImage2D} using a
2800 generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}), the
2801 GL selects from one of its extensions supporting compressed textures. In
2802 order to load the compressed texture image using
2803 @code{glCompressedTexImage3D}, query the compressed texture image's size
2804 and format using @code{glGetTexLevelParameter}.
2806 If a non-zero named buffer object is bound to the
2807 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2808 texture image is specified, @var{data} is treated as a byte offset into
2809 the buffer object's data store.
2811 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of
2812 the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
2813 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
2814 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or
2815 @code{GL_COMPRESSED_RGBA}.
2817 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
2818 consistent with the format, dimensions, and contents of the specified
2819 compressed image data.
2821 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
2822 not supported by the specific compressed internal format as specified in
2823 the specific texture compression extension.
2825 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2826 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2827 object's data store is currently mapped.
2829 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2830 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2831 would be unpacked from the buffer object such that the memory reads
2832 required would exceed the data store size.
2834 @code{GL_INVALID_OPERATION} is generated if
2835 @code{glCompressedTexImage3D} is executed between the execution of
2836 @code{glBegin} and the corresponding execution of @code{glEnd}.
2838 Undefined results, including abnormal program termination, are generated
2839 if @var{data} is not encoded in a manner consistent with the extension
2840 specification defining the internal compression format.
2844 @deftypefun void glCompressedTexSubImage1D target level xoffset width format imageSize data
2845 Specify a one-dimensional texture subimage in a compressed format.
2849 Specifies the target texture. Must be @code{GL_TEXTURE_1D}.
2852 Specifies the level-of-detail number. Level 0 is the base image level.
2853 Level @var{n} is the @var{n}th mipmap reduction image.
2856 Specifies a texel offset in the x direction within the texture array.
2859 Specifies the width of the texture subimage.
2862 Specifies the format of the compressed image data stored at address
2865 @item @var{imageSize}
2866 Specifies the number of unsigned bytes of image data starting at the
2867 address specified by @var{data}.
2870 Specifies a pointer to the compressed image data in memory.
2874 Texturing maps a portion of a specified texture image onto each
2875 graphical primitive for which texturing is enabled. To enable and
2876 disable one-dimensional texturing, call @code{glEnable} and
2877 @code{glDisable} with argument @code{GL_TEXTURE_1D}.
2879 @code{glCompressedTexSubImage1D} redefines a contiguous subregion of an
2880 existing one-dimensional texture image. The texels referenced by
2881 @var{data} replace the portion of the existing texture array with x
2882 indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive.
2883 This region may not include any texels outside the range of the texture
2884 array as it was originally specified. It is not an error to specify a
2885 subtexture with width of 0, but such a specification has no effect.
2887 @var{format} must be an extension-specified compressed-texture format.
2888 The @var{format} of the compressed texture image is selected by the GL
2889 implementation that compressed it (see @code{glTexImage1D}), and should
2890 be queried at the time the texture was compressed with
2891 @code{glGetTexLevelParameter}.
2893 If a non-zero named buffer object is bound to the
2894 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2895 texture image is specified, @var{data} is treated as a byte offset into
2896 the buffer object's data store.
2898 @code{GL_INVALID_ENUM} is generated if @var{format} is one of these
2899 generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
2900 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
2901 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
2902 @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE},
2903 @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB},
2904 @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}.
2906 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
2907 consistent with the format, dimensions, and contents of the specified
2908 compressed image data.
2910 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
2911 not supported by the specific compressed internal format as specified in
2912 the specific texture compression extension.
2914 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2915 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
2916 object's data store is currently mapped.
2918 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
2919 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
2920 would be unpacked from the buffer object such that the memory reads
2921 required would exceed the data store size.
2923 @code{GL_INVALID_OPERATION} is generated if
2924 @code{glCompressedTexSubImage1D} is executed between the execution of
2925 @code{glBegin} and the corresponding execution of @code{glEnd}.
2927 Undefined results, including abnormal program termination, are generated
2928 if @var{data} is not encoded in a manner consistent with the extension
2929 specification defining the internal compression format.
2933 @deftypefun void glCompressedTexSubImage2D target level xoffset yoffset width height format imageSize data
2934 Specify a two-dimensional texture subimage in a compressed format.
2938 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
2939 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
2940 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
2941 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
2942 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
2943 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
2944 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
2947 Specifies the level-of-detail number. Level 0 is the base image level.
2948 Level @var{n} is the @var{n}th mipmap reduction image.
2951 Specifies a texel offset in the x direction within the texture array.
2954 Specifies a texel offset in the y direction within the texture array.
2957 Specifies the width of the texture subimage.
2960 Specifies the height of the texture subimage.
2963 Specifies the format of the compressed image data stored at address
2966 @item @var{imageSize}
2967 Specifies the number of unsigned bytes of image data starting at the
2968 address specified by @var{data}.
2971 Specifies a pointer to the compressed image data in memory.
2975 Texturing maps a portion of a specified texture image onto each
2976 graphical primitive for which texturing is enabled. To enable and
2977 disable two-dimensional texturing, call @code{glEnable} and
2978 @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and
2979 disable texturing using cube-mapped texture, call @code{glEnable} and
2980 @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}.
2982 @code{glCompressedTexSubImage2D} redefines a contiguous subregion of an
2983 existing two-dimensional texture image. The texels referenced by
2984 @var{data} replace the portion of the existing texture array with x
2985 indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, and the y
2986 indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive.
2987 This region may not include any texels outside the range of the texture
2988 array as it was originally specified. It is not an error to specify a
2989 subtexture with width of 0, but such a specification has no effect.
2991 @var{format} must be an extension-specified compressed-texture format.
2992 The @var{format} of the compressed texture image is selected by the GL
2993 implementation that compressed it (see @code{glTexImage2D}) and should
2994 be queried at the time the texture was compressed with
2995 @code{glGetTexLevelParameter}.
2997 If a non-zero named buffer object is bound to the
2998 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
2999 texture image is specified, @var{data} is treated as a byte offset into
3000 the buffer object's data store.
3002 @code{GL_INVALID_ENUM} is generated if @var{format} is one of these
3003 generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
3004 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
3005 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
3006 @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE},
3007 @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB},
3008 @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}.
3010 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
3011 consistent with the format, dimensions, and contents of the specified
3012 compressed image data.
3014 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
3015 not supported by the specific compressed internal format as specified in
3016 the specific texture compression extension.
3018 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3019 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
3020 object's data store is currently mapped.
3022 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3023 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
3024 would be unpacked from the buffer object such that the memory reads
3025 required would exceed the data store size.
3027 @code{GL_INVALID_OPERATION} is generated if
3028 @code{glCompressedTexSubImage2D} is executed between the execution of
3029 @code{glBegin} and the corresponding execution of @code{glEnd}.
3031 Undefined results, including abnormal program termination, are generated
3032 if @var{data} is not encoded in a manner consistent with the extension
3033 specification defining the internal compression format.
3037 @deftypefun void glCompressedTexSubImage3D target level xoffset yoffset zoffset width height depth format imageSize data
3038 Specify a three-dimensional texture subimage in a compressed format.
3042 Specifies the target texture. Must be @code{GL_TEXTURE_3D}.
3045 Specifies the level-of-detail number. Level 0 is the base image level.
3046 Level @var{n} is the @var{n}th mipmap reduction image.
3049 Specifies a texel offset in the x direction within the texture array.
3052 Specifies a texel offset in the y direction within the texture array.
3055 Specifies the width of the texture subimage.
3058 Specifies the height of the texture subimage.
3061 Specifies the depth of the texture subimage.
3064 Specifies the format of the compressed image data stored at address
3067 @item @var{imageSize}
3068 Specifies the number of unsigned bytes of image data starting at the
3069 address specified by @var{data}.
3072 Specifies a pointer to the compressed image data in memory.
3076 Texturing maps a portion of a specified texture image onto each
3077 graphical primitive for which texturing is enabled. To enable and
3078 disable three-dimensional texturing, call @code{glEnable} and
3079 @code{glDisable} with argument @code{GL_TEXTURE_3D}.
3081 @code{glCompressedTexSubImage3D} redefines a contiguous subregion of an
3082 existing three-dimensional texture image. The texels referenced by
3083 @var{data} replace the portion of the existing texture array with x
3084 indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, and the y
3085 indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, and the z
3086 indices @var{zoffset} and @r{@var{zoffset}+@var{depth}-1}, inclusive.
3087 This region may not include any texels outside the range of the texture
3088 array as it was originally specified. It is not an error to specify a
3089 subtexture with width of 0, but such a specification has no effect.
3091 @var{format} must be an extension-specified compressed-texture format.
3092 The @var{format} of the compressed texture image is selected by the GL
3093 implementation that compressed it (see @code{glTexImage3D}) and should
3094 be queried at the time the texture was compressed with
3095 @code{glGetTexLevelParameter}.
3097 If a non-zero named buffer object is bound to the
3098 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
3099 texture image is specified, @var{data} is treated as a byte offset into
3100 the buffer object's data store.
3102 @code{GL_INVALID_ENUM} is generated if @var{format} is one of these
3103 generic compressed internal formats: @code{GL_COMPRESSED_ALPHA},
3104 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
3105 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
3106 @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE},
3107 @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB},
3108 @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}.
3110 @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not
3111 consistent with the format, dimensions, and contents of the specified
3112 compressed image data.
3114 @code{GL_INVALID_OPERATION} is generated if parameter combinations are
3115 not supported by the specific compressed internal format as specified in
3116 the specific texture compression extension.
3118 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3119 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
3120 object's data store is currently mapped.
3122 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3123 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
3124 would be unpacked from the buffer object such that the memory reads
3125 required would exceed the data store size.
3127 @code{GL_INVALID_OPERATION} is generated if
3128 @code{glCompressedTexSubImage3D} is executed between the execution of
3129 @code{glBegin} and the corresponding execution of @code{glEnd}.
3131 Undefined results, including abnormal program termination, are generated
3132 if @var{data} is not encoded in a manner consistent with the extension
3133 specification defining the internal compression format.
3137 @deftypefun void glConvolutionFilter1D target internalformat width format type data
3138 Define a one-dimensional convolution filter.
3142 Must be @code{GL_CONVOLUTION_1D}.
3144 @item @var{internalformat}
3145 The internal format of the convolution filter kernel. The allowable
3146 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
3147 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
3148 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
3149 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3150 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3151 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3152 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3153 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3154 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3155 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3156 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3157 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3158 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3161 The width of the pixel array referenced by @var{data}.
3164 The format of the pixel data in @var{data}. The allowable values are
3165 @code{GL_ALPHA}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA},
3166 @code{GL_INTENSITY}, @code{GL_RGB}, and @code{GL_RGBA}.
3169 The type of the pixel data in @var{data}. Symbolic constants
3170 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
3171 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
3172 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
3173 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
3174 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
3175 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
3176 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
3177 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
3178 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
3181 Pointer to a one-dimensional array of pixel data that is processed to
3182 build the convolution filter kernel.
3186 @code{glConvolutionFilter1D} builds a one-dimensional convolution filter
3187 kernel from an array of pixels.
3189 The pixel array specified by @var{width}, @var{format}, @var{type}, and
3190 @var{data} is extracted from memory and processed just as if
3191 @code{glDrawPixels} were called, but processing stops after the final
3192 expansion to RGBA is completed.
3194 If a non-zero named buffer object is bound to the
3195 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
3196 convolution filter is specified, @var{data} is treated as a byte offset
3197 into the buffer object's data store.
3199 The R, G, B, and A components of each pixel are next scaled by the four
3200 1D @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four
3201 1D @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
3202 parameters are set by @code{glConvolutionParameter} using the
3203 @code{GL_CONVOLUTION_1D} target and the names
3204 @code{GL_CONVOLUTION_FILTER_SCALE} and
3205 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors
3206 of four values that are applied to red, green, blue, and alpha, in that
3207 order.) The R, G, B, and A values are not clamped to [0,1] at any time
3208 during this process.
3210 Each pixel is then converted to the internal format specified by
3211 @var{internalformat}. This conversion simply maps the component values
3212 of the pixel (R, G, B, and A) to the values included in the internal
3213 format (red, green, blue, alpha, luminance, and intensity). The mapping
3219 @item @strong{Internal Format}
3220 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
3221 @strong{Luminance}, @strong{Intensity}
3223 @item @code{GL_ALPHA}
3226 @item @code{GL_LUMINANCE}
3229 @item @code{GL_LUMINANCE_ALPHA}
3232 @item @code{GL_INTENSITY}
3238 @item @code{GL_RGBA}
3243 The red, green, blue, alpha, luminance, and/or intensity components of
3244 the resulting pixels are stored in floating-point rather than integer
3245 format. They form a one-dimensional filter kernel image indexed with
3246 coordinate @var{i} such that @var{i} starts at 0 and increases from left
3247 to right. Kernel location @var{i} is derived from the @var{i}th pixel,
3250 Note that after a convolution is performed, the resulting color
3251 components are also scaled by their corresponding
3252 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
3253 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
3254 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
3255 and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}.
3257 @code{GL_INVALID_ENUM} is generated if @var{target} is not
3258 @code{GL_CONVOLUTION_1D}.
3260 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
3261 of the allowable values.
3263 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
3266 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
3269 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
3270 greater than the maximum supported value. This value may be queried with
3271 @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_1D}
3272 and name @code{GL_MAX_CONVOLUTION_WIDTH}.
3274 @code{GL_INVALID_OPERATION} is generated if @var{format} is one of
3275 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
3276 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
3277 and @var{type} is not @code{GL_RGB}.
3279 @code{GL_INVALID_OPERATION} is generated if @var{format} is one of
3280 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
3281 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
3282 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
3283 @code{GL_UNSIGNED_INT_10_10_10_2}, or
3284 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{type} is neither
3285 @code{GL_RGBA} nor @code{GL_BGRA}.
3287 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3288 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
3289 object's data store is currently mapped.
3291 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3292 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
3293 would be unpacked from the buffer object such that the memory reads
3294 required would exceed the data store size.
3296 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3297 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
3298 is not evenly divisible into the number of bytes needed to store in
3299 memory a datum indicated by @var{type}.
3301 @code{GL_INVALID_OPERATION} is generated if @code{glConvolutionFilter1D}
3302 is executed between the execution of @code{glBegin} and the
3303 corresponding execution of @code{glEnd}.
3307 @deftypefun void glConvolutionFilter2D target internalformat width height format type data
3308 Define a two-dimensional convolution filter.
3312 Must be @code{GL_CONVOLUTION_2D}.
3314 @item @var{internalformat}
3315 The internal format of the convolution filter kernel. The allowable
3316 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
3317 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
3318 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
3319 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3320 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3321 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3322 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3323 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3324 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3325 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3326 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3327 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3328 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3331 The width of the pixel array referenced by @var{data}.
3334 The height of the pixel array referenced by @var{data}.
3337 The format of the pixel data in @var{data}. The allowable values are
3338 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
3339 @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA},
3340 @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA}.
3343 The type of the pixel data in @var{data}. Symbolic constants
3344 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
3345 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
3346 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
3347 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
3348 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
3349 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
3350 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
3351 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
3352 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
3355 Pointer to a two-dimensional array of pixel data that is processed to
3356 build the convolution filter kernel.
3360 @code{glConvolutionFilter2D} builds a two-dimensional convolution filter
3361 kernel from an array of pixels.
3363 The pixel array specified by @var{width}, @var{height}, @var{format},
3364 @var{type}, and @var{data} is extracted from memory and processed just
3365 as if @code{glDrawPixels} were called, but processing stops after the
3366 final expansion to RGBA is completed.
3368 If a non-zero named buffer object is bound to the
3369 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
3370 convolution filter is specified, @var{data} is treated as a byte offset
3371 into the buffer object's data store.
3373 The R, G, B, and A components of each pixel are next scaled by the four
3374 2D @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four
3375 2D @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
3376 parameters are set by @code{glConvolutionParameter} using the
3377 @code{GL_CONVOLUTION_2D} target and the names
3378 @code{GL_CONVOLUTION_FILTER_SCALE} and
3379 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors
3380 of four values that are applied to red, green, blue, and alpha, in that
3381 order.) The R, G, B, and A values are not clamped to [0,1] at any time
3382 during this process.
3384 Each pixel is then converted to the internal format specified by
3385 @var{internalformat}. This conversion simply maps the component values
3386 of the pixel (R, G, B, and A) to the values included in the internal
3387 format (red, green, blue, alpha, luminance, and intensity). The mapping
3393 @item @strong{Internal Format}
3394 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
3395 @strong{Luminance}, @strong{Intensity}
3397 @item @code{GL_ALPHA}
3400 @item @code{GL_LUMINANCE}
3403 @item @code{GL_LUMINANCE_ALPHA}
3406 @item @code{GL_INTENSITY}
3412 @item @code{GL_RGBA}
3417 The red, green, blue, alpha, luminance, and/or intensity components of
3418 the resulting pixels are stored in floating-point rather than integer
3419 format. They form a two-dimensional filter kernel image indexed with
3420 coordinates @var{i} and @var{j} such that @var{i} starts at zero and
3421 increases from left to right, and @var{j} starts at zero and increases
3422 from bottom to top. Kernel location @var{i,j} is derived from the
3423 @var{N}th pixel, where @var{N} is @var{i}+@var{j}*@var{width}.
3425 Note that after a convolution is performed, the resulting color
3426 components are also scaled by their corresponding
3427 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
3428 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
3429 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
3430 and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}.
3432 @code{GL_INVALID_ENUM} is generated if @var{target} is not
3433 @code{GL_CONVOLUTION_2D}.
3435 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
3436 of the allowable values.
3438 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
3441 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
3444 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
3445 greater than the maximum supported value. This value may be queried with
3446 @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_2D}
3447 and name @code{GL_MAX_CONVOLUTION_WIDTH}.
3449 @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero
3450 or greater than the maximum supported value. This value may be queried
3451 with @code{glGetConvolutionParameter} using target
3452 @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}.
3454 @code{GL_INVALID_OPERATION} is generated if @var{height} is one of
3455 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
3456 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
3457 and @var{format} is not @code{GL_RGB}.
3459 @code{GL_INVALID_OPERATION} is generated if @var{height} is one of
3460 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
3461 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
3462 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
3463 @code{GL_UNSIGNED_INT_10_10_10_2}, or
3464 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
3465 @code{GL_RGBA} nor @code{GL_BGRA}.
3467 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3468 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
3469 object's data store is currently mapped.
3471 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3472 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
3473 would be unpacked from the buffer object such that the memory reads
3474 required would exceed the data store size.
3476 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
3477 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
3478 is not evenly divisible into the number of bytes needed to store in
3479 memory a datum indicated by @var{type}.
3481 @code{GL_INVALID_OPERATION} is generated if @code{glConvolutionFilter2D}
3482 is executed between the execution of @code{glBegin} and the
3483 corresponding execution of @code{glEnd}.
3487 @deftypefun void glConvolutionParameterf target pname params
3488 @deftypefunx void glConvolutionParameteri target pname params
3489 Set convolution parameters.
3493 The target for the convolution parameter. Must be one of
3494 @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or
3495 @code{GL_SEPARABLE_2D}.
3498 The parameter to be set. Must be @code{GL_CONVOLUTION_BORDER_MODE}.
3501 The parameter value. Must be one of @code{GL_REDUCE},
3502 @code{GL_CONSTANT_BORDER}, @code{GL_REPLICATE_BORDER}.
3508 @code{glConvolutionParameter} sets the value of a convolution parameter.
3510 @var{target} selects the convolution filter to be affected:
3511 @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or
3512 @code{GL_SEPARABLE_2D} for the 1D, 2D, or separable 2D filter,
3515 @var{pname} selects the parameter to be changed.
3516 @code{GL_CONVOLUTION_FILTER_SCALE} and @code{GL_CONVOLUTION_FILTER_BIAS}
3517 affect the definition of the convolution filter kernel; see
3518 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and
3519 @code{glSeparableFilter2D} for details. In these cases, @var{params}v is
3520 an array of four values to be applied to red, green, blue, and alpha
3521 values, respectively. The initial value for
3522 @code{GL_CONVOLUTION_FILTER_SCALE} is (1, 1, 1, 1), and the initial
3523 value for @code{GL_CONVOLUTION_FILTER_BIAS} is (0, 0, 0, 0).
3525 A @var{pname} value of @code{GL_CONVOLUTION_BORDER_MODE} controls the
3526 convolution border mode. The accepted modes are:
3529 @item @code{GL_REDUCE}
3530 The image resulting from convolution is smaller than the source image.
3531 If the filter width is @r{@var{Wf}} and height is @r{@var{Hf}}, and the
3532 source image width is @r{@var{Ws}} and height is @r{@var{Hs}}, then the
3533 convolved image width will be @r{@var{Ws}-@var{Wf}+1} and height will be
3534 @r{@var{Hs}-@var{Hf}+1}. (If this reduction would generate an image with
3535 zero or negative width and/or height, the output is simply null, with no
3536 error generated.) The coordinates of the image resulting from
3537 convolution are zero through @r{@var{Ws}-@var{Wf}} in width and zero
3538 through @r{@var{Hs}-@var{Hf}} in height.
3540 @item @code{GL_CONSTANT_BORDER}
3541 The image resulting from convolution is the same size as the source
3542 image, and processed as if the source image were surrounded by pixels
3543 with their color specified by the @code{GL_CONVOLUTION_BORDER_COLOR}.
3545 @item @code{GL_REPLICATE_BORDER}
3546 The image resulting from convolution is the same size as the source
3547 image, and processed as if the outermost pixel on the border of the
3548 source image were replicated.
3552 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
3555 @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the
3558 @code{GL_INVALID_ENUM} is generated if @var{pname} is
3559 @code{GL_CONVOLUTION_BORDER_MODE} and @var{params} is not one of
3560 @code{GL_REDUCE}, @code{GL_CONSTANT_BORDER}, or
3561 @code{GL_REPLICATE_BORDER}.
3563 @code{GL_INVALID_OPERATION} is generated if
3564 @code{glConvolutionParameter} is executed between the execution of
3565 @code{glBegin} and the corresponding execution of @code{glEnd}.
3569 @deftypefun void glCopyColorSubTable target start x y width
3570 Respecify a portion of a color table.
3574 Must be one of @code{GL_COLOR_TABLE},
3575 @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
3576 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}.
3579 The starting index of the portion of the color table to be replaced.
3583 The window coordinates of the left corner of the row of pixels to be
3587 The number of table entries to replace.
3591 @code{glCopyColorSubTable} is used to respecify a contiguous portion of
3592 a color table previously defined using @code{glColorTable}. The pixels
3593 copied from the framebuffer replace the portion of the existing table
3594 from indices @var{start} to @r{@var{start}+@var{x}-1}, inclusive. This
3595 region may not include any entries outside the range of the color table,
3596 as was originally specified. It is not an error to specify a subtexture
3597 with width of 0, but such a specification has no effect.
3599 @code{GL_INVALID_VALUE} is generated if @var{target} is not a previously
3600 defined color table.
3602 @code{GL_INVALID_VALUE} is generated if @var{target} is not one of the
3605 @code{GL_INVALID_VALUE} is generated if
3606 @r{@var{start}+@var{x}>@var{width}}.
3608 @code{GL_INVALID_OPERATION} is generated if @code{glCopyColorSubTable}
3609 is executed between the execution of @code{glBegin} and the
3610 corresponding execution of @code{glEnd}.
3614 @deftypefun void glCopyColorTable target internalformat x y width
3615 Copy pixels into a color table.
3619 The color table target. Must be @code{GL_COLOR_TABLE},
3620 @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or
3621 @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}.
3623 @item @var{internalformat}
3624 The internal storage format of the texture image. Must be one of the
3625 following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4},
3626 @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16},
3627 @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8},
3628 @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3629 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3630 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3631 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3632 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3633 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3634 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3635 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3636 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3637 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3640 The x coordinate of the lower-left corner of the pixel rectangle to be
3641 transferred to the color table.
3644 The y coordinate of the lower-left corner of the pixel rectangle to be
3645 transferred to the color table.
3648 The width of the pixel rectangle.
3652 @code{glCopyColorTable} loads a color table with pixels from the current
3653 @code{GL_READ_BUFFER} (rather than from main memory, as is the case for
3654 @code{glColorTable}).
3656 The screen-aligned pixel rectangle with lower-left corner at (@var{x},\
3657 @var{y}) having width @var{width} and height 1 is loaded into the color
3658 table. If any pixels within this region are outside the window that is
3659 associated with the GL context, the values obtained for those pixels are
3662 The pixels in the rectangle are processed just as if @code{glReadPixels}
3663 were called, with @var{internalformat} set to RGBA, but processing stops
3664 after the final conversion to RGBA.
3666 The four scale parameters and the four bias parameters that are defined
3667 for the table are then used to scale and bias the R, G, B, and A
3668 components of each pixel. The scale and bias parameters are set by
3669 calling @code{glColorTableParameter}.
3671 Next, the R, G, B, and A values are clamped to the range @r{[0,1]}. Each
3672 pixel is then converted to the internal format specified by
3673 @var{internalformat}. This conversion simply maps the component values
3674 of the pixel (R, G, B, and A) to the values included in the internal
3675 format (red, green, blue, alpha, luminance, and intensity). The mapping
3681 @item @strong{Internal Format}
3682 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
3683 @strong{Luminance}, @strong{Intensity}
3685 @item @code{GL_ALPHA}
3688 @item @code{GL_LUMINANCE}
3691 @item @code{GL_LUMINANCE_ALPHA}
3694 @item @code{GL_INTENSITY}
3700 @item @code{GL_RGBA}
3705 Finally, the red, green, blue, alpha, luminance, and/or intensity
3706 components of the resulting pixels are stored in the color table. They
3707 form a one-dimensional table with indices in the range
3708 @r{[0,@var{width}-1]}.
3712 @code{GL_INVALID_ENUM} is generated when @var{target} is not one of the
3715 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero.
3717 @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not one
3718 of the allowable values.
3720 @code{GL_TABLE_TOO_LARGE} is generated if the requested color table is
3721 too large to be supported by the implementation.
3723 @code{GL_INVALID_OPERATION} is generated if @code{glCopyColorTable} is
3724 executed between the execution of @code{glBegin} and the corresponding
3725 execution of @code{glEnd}.
3729 @deftypefun void glCopyConvolutionFilter1D target internalformat x y width
3730 Copy pixels into a one-dimensional convolution filter.
3734 Must be @code{GL_CONVOLUTION_1D}.
3736 @item @var{internalformat}
3737 The internal format of the convolution filter kernel. The allowable
3738 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
3739 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
3740 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
3741 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3742 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3743 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3744 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3745 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3746 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3747 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3748 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3749 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3750 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3754 The window space coordinates of the lower-left coordinate of the pixel
3758 The width of the pixel array to copy.
3762 @code{glCopyConvolutionFilter1D} defines a one-dimensional convolution
3763 filter kernel with pixels from the current @code{GL_READ_BUFFER} (rather
3764 than from main memory, as is the case for @code{glConvolutionFilter1D}).
3766 The screen-aligned pixel rectangle with lower-left corner at (@var{x},\
3767 @var{y}), width @var{width} and height 1 is used to define the
3768 convolution filter. If any pixels within this region are outside the
3769 window that is associated with the GL context, the values obtained for
3770 those pixels are undefined.
3772 The pixels in the rectangle are processed exactly as if
3773 @code{glReadPixels} had been called with @var{format} set to RGBA, but
3774 the process stops just before final conversion. The R, G, B, and A
3775 components of each pixel are next scaled by the four 1D
3776 @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four 1D
3777 @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
3778 parameters are set by @code{glConvolutionParameter} using the
3779 @code{GL_CONVOLUTION_1D} target and the names
3780 @code{GL_CONVOLUTION_FILTER_SCALE} and
3781 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors
3782 of four values that are applied to red, green, blue, and alpha, in that
3783 order.) The R, G, B, and A values are not clamped to [0,1] at any time
3784 during this process.
3786 Each pixel is then converted to the internal format specified by
3787 @var{internalformat}. This conversion simply maps the component values
3788 of the pixel (R, G, B, and A) to the values included in the internal
3789 format (red, green, blue, alpha, luminance, and intensity). The mapping
3795 @item @strong{Internal Format}
3796 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
3797 @strong{Luminance}, @strong{Intensity}
3799 @item @code{GL_ALPHA}
3802 @item @code{GL_LUMINANCE}
3805 @item @code{GL_LUMINANCE_ALPHA}
3808 @item @code{GL_INTENSITY}
3814 @item @code{GL_RGBA}
3819 The red, green, blue, alpha, luminance, and/or intensity components of
3820 the resulting pixels are stored in floating-point rather than integer
3823 Pixel ordering is such that lower x screen coordinates correspond to
3824 lower @var{i} filter image coordinates.
3826 Note that after a convolution is performed, the resulting color
3827 components are also scaled by their corresponding
3828 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
3829 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
3830 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
3831 and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}.
3833 @code{GL_INVALID_ENUM} is generated if @var{target} is not
3834 @code{GL_CONVOLUTION_1D}.
3836 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
3837 of the allowable values.
3839 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
3840 greater than the maximum supported value. This value may be queried with
3841 @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_1D}
3842 and name @code{GL_MAX_CONVOLUTION_WIDTH}.
3844 @code{GL_INVALID_OPERATION} is generated if
3845 @code{glCopyConvolutionFilter1D} is executed between the execution of
3846 @code{glBegin} and the corresponding execution of @code{glEnd}.
3850 @deftypefun void glCopyConvolutionFilter2D target internalformat x y width height
3851 Copy pixels into a two-dimensional convolution filter.
3855 Must be @code{GL_CONVOLUTION_2D}.
3857 @item @var{internalformat}
3858 The internal format of the convolution filter kernel. The allowable
3859 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
3860 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
3861 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
3862 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
3863 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
3864 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
3865 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
3866 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
3867 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
3868 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
3869 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
3870 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
3871 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
3875 The window space coordinates of the lower-left coordinate of the pixel
3879 The width of the pixel array to copy.
3882 The height of the pixel array to copy.
3886 @code{glCopyConvolutionFilter2D} defines a two-dimensional convolution
3887 filter kernel with pixels from the current @code{GL_READ_BUFFER} (rather
3888 than from main memory, as is the case for @code{glConvolutionFilter2D}).
3890 The screen-aligned pixel rectangle with lower-left corner at (@var{x},\
3891 @var{y}), width @var{width} and height @var{height} is used to define
3892 the convolution filter. If any pixels within this region are outside the
3893 window that is associated with the GL context, the values obtained for
3894 those pixels are undefined.
3896 The pixels in the rectangle are processed exactly as if
3897 @code{glReadPixels} had been called with @var{format} set to RGBA, but
3898 the process stops just before final conversion. The R, G, B, and A
3899 components of each pixel are next scaled by the four 2D
3900 @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four 2D
3901 @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
3902 parameters are set by @code{glConvolutionParameter} using the
3903 @code{GL_CONVOLUTION_2D} target and the names
3904 @code{GL_CONVOLUTION_FILTER_SCALE} and
3905 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors
3906 of four values that are applied to red, green, blue, and alpha, in that
3907 order.) The R, G, B, and A values are not clamped to [0,1] at any time
3908 during this process.
3910 Each pixel is then converted to the internal format specified by
3911 @var{internalformat}. This conversion simply maps the component values
3912 of the pixel (R, G, B, and A) to the values included in the internal
3913 format (red, green, blue, alpha, luminance, and intensity). The mapping
3919 @item @strong{Internal Format}
3920 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
3921 @strong{Luminance}, @strong{Intensity}
3923 @item @code{GL_ALPHA}
3926 @item @code{GL_LUMINANCE}
3929 @item @code{GL_LUMINANCE_ALPHA}
3932 @item @code{GL_INTENSITY}
3938 @item @code{GL_RGBA}
3943 The red, green, blue, alpha, luminance, and/or intensity components of
3944 the resulting pixels are stored in floating-point rather than integer
3947 Pixel ordering is such that lower x screen coordinates correspond to
3948 lower @var{i} filter image coordinates, and lower y screen coordinates
3949 correspond to lower @var{j} filter image coordinates.
3951 Note that after a convolution is performed, the resulting color
3952 components are also scaled by their corresponding
3953 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
3954 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
3955 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
3956 and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}.
3958 @code{GL_INVALID_ENUM} is generated if @var{target} is not
3959 @code{GL_CONVOLUTION_2D}.
3961 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
3962 of the allowable values.
3964 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
3965 greater than the maximum supported value. This value may be queried with
3966 @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_2D}
3967 and name @code{GL_MAX_CONVOLUTION_WIDTH}.
3969 @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero
3970 or greater than the maximum supported value. This value may be queried
3971 with @code{glGetConvolutionParameter} using target
3972 @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}.
3974 @code{GL_INVALID_OPERATION} is generated if
3975 @code{glCopyConvolutionFilter2D} is executed between the execution of
3976 @code{glBegin} and the corresponding execution of @code{glEnd}.
3980 @deftypefun void glCopyPixels x y width height type
3981 Copy pixels in the frame buffer.
3986 Specify the window coordinates of the lower left corner of the
3987 rectangular region of pixels to be copied.
3991 Specify the dimensions of the rectangular region of pixels to be copied.
3992 Both must be nonnegative.
3995 Specifies whether color values, depth values, or stencil values are to
3996 be copied. Symbolic constants @code{GL_COLOR}, @code{GL_DEPTH}, and
3997 @code{GL_STENCIL} are accepted.
4001 @code{glCopyPixels} copies a screen-aligned rectangle of pixels from the
4002 specified frame buffer location to a region relative to the current
4003 raster position. Its operation is well defined only if the entire pixel
4004 source region is within the exposed portion of the window. Results of
4005 copies from outside the window, or from regions of the window that are
4006 not exposed, are hardware dependent and undefined.
4008 @var{x} and @var{y} specify the window coordinates of the lower left
4009 corner of the rectangular region to be copied. @var{width} and
4010 @var{height} specify the dimensions of the rectangular region to be
4011 copied. Both @var{width} and @var{height} must not be negative.
4013 Several parameters control the processing of the pixel data while it is
4014 being copied. These parameters are set with three commands:
4015 @code{glPixelTransfer}, @code{glPixelMap}, and @code{glPixelZoom}. This
4016 reference page describes the effects on @code{glCopyPixels} of most, but
4017 not all, of the parameters specified by these three commands.
4019 @code{glCopyPixels} copies values from each pixel with the lower
4020 left-hand corner at @r{(@var{x}+@var{i},@var{y}+@var{j})} for
4021 @r{0<=@var{i}<@var{width}} and @r{0<=@var{j}<@var{height}}. This pixel
4022 is said to be the @r{@var{i}}th pixel in the @r{@var{j}}th row. Pixels
4023 are copied in row order from the lowest to the highest row, left to
4026 @var{type} specifies whether color, depth, or stencil data is to be
4027 copied. The details of the transfer for each data type are as follows:
4030 @item @code{GL_COLOR}
4031 Indices or RGBA colors are read from the buffer currently specified as
4032 the read source buffer (see @code{glReadBuffer}). If the GL is in color
4033 index mode, each index that is read from this buffer is converted to a
4034 fixed-point format with an unspecified number of bits to the right of
4035 the binary point. Each index is then shifted left by
4036 @code{GL_INDEX_SHIFT} bits, and added to @code{GL_INDEX_OFFSET}. If
4037 @code{GL_INDEX_SHIFT} is negative, the shift is to the right. In either
4038 case, zero bits fill otherwise unspecified bit locations in the result.
4039 If @code{GL_MAP_COLOR} is true, the index is replaced with the value
4040 that it references in lookup table @code{GL_PIXEL_MAP_I_TO_I}. Whether
4041 the lookup replacement of the index is done or not, the integer part of
4042 the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the
4043 number of bits in a color index buffer.
4045 If the GL is in RGBA mode, the red, green, blue, and alpha components of
4046 each pixel that is read are converted to an internal floating-point
4047 format with unspecified precision. The conversion maps the largest
4048 representable component value to 1.0, and component value 0 to 0.0. The
4049 resulting floating-point color values are then multiplied by
4050 @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is RED,
4051 GREEN, BLUE, and ALPHA for the respective color components. The results
4052 are clamped to the range [0,1]. If @code{GL_MAP_COLOR} is true, each
4053 color component is scaled by the size of lookup table
4054 @code{GL_PIXEL_MAP_c_TO_c}, then replaced by the value that it
4055 references in that table. @var{c} is R, G, B, or A.
4057 If the @code{ARB_imaging} extension is supported, the color values may
4058 be additionally processed by color-table lookups, color-matrix
4059 transformations, and convolution filters.
4061 The GL then converts the resulting indices or RGBA colors to fragments
4062 by attaching the current raster position @var{z} coordinate and texture
4063 coordinates to each pixel, then assigning window coordinates
4064 @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where
4065 @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position,
4066 and the pixel was the @r{@var{i}}th pixel in the @r{@var{j}}th row.
4067 These pixel fragments are then treated just like the fragments generated
4068 by rasterizing points, lines, or polygons. Texture mapping, fog, and all
4069 the fragment operations are applied before the fragments are written to
4072 @item @code{GL_DEPTH}
4073 Depth values are read from the depth buffer and converted directly to an
4074 internal floating-point format with unspecified precision. The resulting
4075 floating-point depth value is then multiplied by @code{GL_DEPTH_SCALE}
4076 and added to @code{GL_DEPTH_BIAS}. The result is clamped to the range
4079 The GL then converts the resulting depth components to fragments by
4080 attaching the current raster position color or color index and texture
4081 coordinates to each pixel, then assigning window coordinates
4082 @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where
4083 @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position,
4084 and the pixel was the @r{@var{i}}th pixel in the @r{@var{j}}th row.
4085 These pixel fragments are then treated just like the fragments generated
4086 by rasterizing points, lines, or polygons. Texture mapping, fog, and all
4087 the fragment operations are applied before the fragments are written to
4090 @item @code{GL_STENCIL}
4091 Stencil indices are read from the stencil buffer and converted to an
4092 internal fixed-point format with an unspecified number of bits to the
4093 right of the binary point. Each fixed-point index is then shifted left
4094 by @code{GL_INDEX_SHIFT} bits, and added to @code{GL_INDEX_OFFSET}. If
4095 @code{GL_INDEX_SHIFT} is negative, the shift is to the right. In either
4096 case, zero bits fill otherwise unspecified bit locations in the result.
4097 If @code{GL_MAP_STENCIL} is true, the index is replaced with the value
4098 that it references in lookup table @code{GL_PIXEL_MAP_S_TO_S}. Whether
4099 the lookup replacement of the index is done or not, the integer part of
4100 the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the
4101 number of bits in the stencil buffer. The resulting stencil indices are
4102 then written to the stencil buffer such that the index read from the
4103 @r{@var{i}}th location of the @r{@var{j}}th row is written to location
4104 @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where
4105 @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position.
4106 Only the pixel ownership test, the scissor test, and the stencil
4107 writemask affect these write operations.
4111 The rasterization described thus far assumes pixel zoom factors of 1.0.
4112 If @code{glPixelZoom} is used to change the @r{@var{x}} and @r{@var{y}}
4113 pixel zoom factors, pixels are converted to fragments as follows. If
4114 @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position,
4115 and a given pixel is in the @r{@var{i}}th location in the @r{@var{j}}th
4116 row of the source pixel rectangle, then fragments are generated for
4117 pixels whose centers are in the rectangle with corners at
4119 @r{(@var{x}_@var{r}+@var{zoom}_@var{x},@var{i},@var{y}_@var{r}+@var{zoom}_@var{y},@var{j})}
4123 @r{(@var{x}_@var{r}+@var{zoom}_@var{x},(@var{i}+1,),@var{y}_@var{r}+@var{zoom}_@var{y},(@var{j}+1,))}
4125 where @r{@var{zoom}_@var{x}} is the value of @code{GL_ZOOM_X} and
4126 @r{@var{zoom}_@var{y}} is the value of @code{GL_ZOOM_Y}.
4128 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
4131 @code{GL_INVALID_VALUE} is generated if either @var{width} or
4132 @var{height} is negative.
4134 @code{GL_INVALID_OPERATION} is generated if @var{type} is
4135 @code{GL_DEPTH} and there is no depth buffer.
4137 @code{GL_INVALID_OPERATION} is generated if @var{type} is
4138 @code{GL_STENCIL} and there is no stencil buffer.
4140 @code{GL_INVALID_OPERATION} is generated if @code{glCopyPixels} is
4141 executed between the execution of @code{glBegin} and the corresponding
4142 execution of @code{glEnd}.
4146 @deftypefun void glCopyTexImage1D target level internalformat x y width border
4147 Copy pixels into a 1D texture image.
4151 Specifies the target texture. Must be @code{GL_TEXTURE_1D}.
4154 Specifies the level-of-detail number. Level 0 is the base image level.
4155 Level @var{n} is the @var{n}th mipmap reduction image.
4157 @item @var{internalformat}
4158 Specifies the internal format of the texture. Must be one of the
4159 following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4},
4160 @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16},
4161 @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_LUMINANCE},
4162 @code{GL_COMPRESSED_LUMINANCE_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
4163 @code{GL_COMPRESSED_RGB}, @code{GL_COMPRESSED_RGBA},
4164 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
4165 @code{GL_DEPTH_COMPONENT24}, @code{GL_DEPTH_COMPONENT32},
4166 @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8},
4167 @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
4168 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
4169 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
4170 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
4171 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
4172 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_RGB},
4173 @code{GL_R3_G3_B2}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
4174 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
4175 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
4176 @code{GL_RGB10_A2}, @code{GL_RGBA12}, @code{GL_RGBA16},
4177 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
4178 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
4179 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
4183 Specify the window coordinates of the left corner of the row of pixels
4187 Specifies the width of the texture image. Must be 0 or
4188 @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. The height
4189 of the texture image is 1.
4192 Specifies the width of the border. Must be either 0 or 1.
4196 @code{glCopyTexImage1D} defines a one-dimensional texture image with
4197 pixels from the current @code{GL_READ_BUFFER}.
4199 The screen-aligned pixel row with left corner at @r{(@var{x},@var{y})}
4200 and with a length of @r{@var{width}+2(@var{border},)} defines the
4201 texture array at the mipmap level specified by @var{level}.
4202 @var{internalformat} specifies the internal format of the texture array.
4204 The pixels in the row are processed exactly as if @code{glCopyPixels}
4205 had been called, but the process stops just before final conversion. At
4206 this point all pixel component values are clamped to the range @r{[0,1]}
4207 and then converted to the texture's internal format for storage in the
4210 Pixel ordering is such that lower @r{@var{x}} screen coordinates
4211 correspond to lower texture coordinates.
4213 If any of the pixels within the specified row of the current
4214 @code{GL_READ_BUFFER} are outside the window associated with the current
4215 rendering context, then the values obtained for those pixels are
4218 @code{glCopyTexImage1D} defines a one-dimensional texture image with
4219 pixels from the current @code{GL_READ_BUFFER}.
4221 When @var{internalformat} is one of the sRGB types, the GL does not
4222 automatically convert the source pixels to the sRGB color space. In this
4223 case, the @code{glPixelMap} function can be used to accomplish the
4226 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
4229 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4231 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
4232 @r{@var{log}_2@var{max}}, where @r{@var{max}} is the returned value of
4233 @code{GL_MAX_TEXTURE_SIZE}.
4235 @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not an
4238 @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or
4239 greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
4241 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
4242 not supported and the @var{width} cannot be represented as
4243 @r{2^@var{n}+2(@var{border},)} for some integer value of @var{n}.
4245 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
4247 @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexImage1D} is
4248 executed between the execution of @code{glBegin} and the corresponding
4249 execution of @code{glEnd}.
4251 @code{GL_INVALID_OPERATION} is generated if @var{internalformat} is
4252 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
4253 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32} and there is
4258 @deftypefun void glCopyTexImage2D target level internalformat x y width height border
4259 Copy pixels into a 2D texture image.
4263 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
4264 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
4265 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
4266 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
4267 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
4268 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
4269 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
4272 Specifies the level-of-detail number. Level 0 is the base image level.
4273 Level @var{n} is the @var{n}th mipmap reduction image.
4275 @item @var{internalformat}
4276 Specifies the internal format of the texture. Must be one of the
4277 following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4},
4278 @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16},
4279 @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_LUMINANCE},
4280 @code{GL_COMPRESSED_LUMINANCE_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
4281 @code{GL_COMPRESSED_RGB}, @code{GL_COMPRESSED_RGBA},
4282 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
4283 @code{GL_DEPTH_COMPONENT24}, @code{GL_DEPTH_COMPONENT32},
4284 @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8},
4285 @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
4286 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
4287 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
4288 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
4289 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
4290 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_RGB},
4291 @code{GL_R3_G3_B2}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
4292 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
4293 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
4294 @code{GL_RGB10_A2}, @code{GL_RGBA12}, @code{GL_RGBA16},
4295 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
4296 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
4297 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
4301 Specify the window coordinates of the lower left corner of the
4302 rectangular region of pixels to be copied.
4305 Specifies the width of the texture image. Must be 0 or
4306 @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}.
4309 Specifies the height of the texture image. Must be 0 or
4310 @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}.
4313 Specifies the width of the border. Must be either 0 or 1.
4317 @code{glCopyTexImage2D} defines a two-dimensional texture image, or
4318 cube-map texture image with pixels from the current
4319 @code{GL_READ_BUFFER}.
4321 The screen-aligned pixel rectangle with lower left corner at (@var{x},
4322 @var{y}) and with a width of @r{@var{width}+2(@var{border},)} and a
4323 height of @r{@var{height}+2(@var{border},)} defines the texture array
4324 at the mipmap level specified by @var{level}. @var{internalformat}
4325 specifies the internal format of the texture array.
4327 The pixels in the rectangle are processed exactly as if
4328 @code{glCopyPixels} had been called, but the process stops just before
4329 final conversion. At this point all pixel component values are clamped
4330 to the range @r{[0,1]} and then converted to the texture's internal
4331 format for storage in the texel array.
4333 Pixel ordering is such that lower @r{@var{x}} and @r{@var{y}} screen
4334 coordinates correspond to lower @r{@var{s}} and @r{@var{t}} texture
4337 If any of the pixels within the specified rectangle of the current
4338 @code{GL_READ_BUFFER} are outside the window associated with the current
4339 rendering context, then the values obtained for those pixels are
4342 When @var{internalformat} is one of the sRGB types, the GL does not
4343 automatically convert the source pixels to the sRGB color space. In this
4344 case, the @code{glPixelMap} function can be used to accomplish the
4347 @code{GL_INVALID_ENUM} is generated if @var{target} is not
4348 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
4349 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
4350 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
4351 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
4352 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
4353 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
4355 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4357 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
4358 @r{@var{log}_2@var{max}}, where @r{@var{max}} is the returned value of
4359 @code{GL_MAX_TEXTURE_SIZE}.
4361 @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or
4362 greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
4364 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
4365 not supported and the @var{width} or @var{depth} cannot be represented
4366 as @r{2^@var{k}+2(@var{border},)} for some integer @r{@var{k}}.
4368 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
4370 @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not an
4373 @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexImage2D} is
4374 executed between the execution of @code{glBegin} and the corresponding
4375 execution of @code{glEnd}.
4377 @code{GL_INVALID_OPERATION} is generated if @var{internalformat} is
4378 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
4379 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32} and there is
4384 @deftypefun void glCopyTexSubImage1D target level xoffset x y width
4385 Copy a one-dimensional texture subimage.
4389 Specifies the target texture. Must be @code{GL_TEXTURE_1D}.
4392 Specifies the level-of-detail number. Level 0 is the base image level.
4393 Level @var{n} is the @var{n}th mipmap reduction image.
4396 Specifies the texel offset within the texture array.
4400 Specify the window coordinates of the left corner of the row of pixels
4404 Specifies the width of the texture subimage.
4408 @code{glCopyTexSubImage1D} replaces a portion of a one-dimensional
4409 texture image with pixels from the current @code{GL_READ_BUFFER} (rather
4410 than from main memory, as is the case for @code{glTexSubImage1D}).
4412 The screen-aligned pixel row with left corner at (@var{x},\ @var{y}),
4413 and with length @var{width} replaces the portion of the texture array
4414 with x indices @var{xoffset} through @r{@var{xoffset}+@var{width}-1},
4415 inclusive. The destination in the texture array may not include any
4416 texels outside the texture array as it was originally specified.
4418 The pixels in the row are processed exactly as if @code{glCopyPixels}
4419 had been called, but the process stops just before final conversion. At
4420 this point, all pixel component values are clamped to the range
4421 @r{[0,1]} and then converted to the texture's internal format for
4422 storage in the texel array.
4424 It is not an error to specify a subtexture with zero width, but such a
4425 specification has no effect. If any of the pixels within the specified
4426 row of the current @code{GL_READ_BUFFER} are outside the read window
4427 associated with the current rendering context, then the values obtained
4428 for those pixels are undefined.
4430 No change is made to the @var{internalformat}, @var{width}, or
4431 @var{border} parameters of the specified texture array or to texel
4432 values outside the specified subregion.
4434 @code{GL_INVALID_ENUM} is generated if /@var{target} is not
4435 @code{GL_TEXTURE_1D}.
4437 @code{GL_INVALID_OPERATION} is generated if the texture array has not
4438 been defined by a previous @code{glTexImage1D} or
4439 @code{glCopyTexImage1D} operation.
4441 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4443 @code{GL_INVALID_VALUE} may be generated if
4444 @r{@var{level}>@var{log}_2(@var{max},)}, where @var{max} is the
4445 returned value of @code{GL_MAX_TEXTURE_SIZE}.
4447 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, or
4448 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, where @r{@var{w}}
4449 is the @code{GL_TEXTURE_WIDTH} and @r{@var{b}} is the
4450 @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that
4451 @r{@var{w}} includes twice the border width.
4457 @deftypefun void glCopyTexSubImage2D target level xoffset yoffset x y width height
4458 Copy a two-dimensional texture subimage.
4462 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
4463 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
4464 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
4465 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
4466 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
4467 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
4468 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
4471 Specifies the level-of-detail number. Level 0 is the base image level.
4472 Level @var{n} is the @var{n}th mipmap reduction image.
4475 Specifies a texel offset in the x direction within the texture array.
4478 Specifies a texel offset in the y direction within the texture array.
4482 Specify the window coordinates of the lower left corner of the
4483 rectangular region of pixels to be copied.
4486 Specifies the width of the texture subimage.
4489 Specifies the height of the texture subimage.
4493 @code{glCopyTexSubImage2D} replaces a rectangular portion of a
4494 two-dimensional texture image or cube-map texture image with pixels from
4495 the current @code{GL_READ_BUFFER} (rather than from main memory, as is
4496 the case for @code{glTexSubImage2D}).
4498 The screen-aligned pixel rectangle with lower left corner at
4499 @r{(@var{x},@var{y})} and with width @var{width} and height @var{height}
4500 replaces the portion of the texture array with x indices @var{xoffset}
4501 through @r{@var{xoffset}+@var{width}-1}, inclusive, and y indices
4502 @var{yoffset} through @r{@var{yoffset}+@var{height}-1}, inclusive, at
4503 the mipmap level specified by @var{level}.
4505 The pixels in the rectangle are processed exactly as if
4506 @code{glCopyPixels} had been called, but the process stops just before
4507 final conversion. At this point, all pixel component values are clamped
4508 to the range @r{[0,1]} and then converted to the texture's internal
4509 format for storage in the texel array.
4511 The destination rectangle in the texture array may not include any
4512 texels outside the texture array as it was originally specified. It is
4513 not an error to specify a subtexture with zero width or height, but such
4514 a specification has no effect.
4516 If any of the pixels within the specified rectangle of the current
4517 @code{GL_READ_BUFFER} are outside the read window associated with the
4518 current rendering context, then the values obtained for those pixels are
4521 No change is made to the @var{internalformat}, @var{width},
4522 @var{height}, or @var{border} parameters of the specified texture array
4523 or to texel values outside the specified subregion.
4525 @code{GL_INVALID_ENUM} is generated if @var{target} is not
4526 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
4527 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
4528 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
4529 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
4530 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
4531 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
4533 @code{GL_INVALID_OPERATION} is generated if the texture array has not
4534 been defined by a previous @code{glTexImage2D} or
4535 @code{glCopyTexImage2D} operation.
4537 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4539 @code{GL_INVALID_VALUE} may be generated if
4540 @r{@var{level}>@var{log}_2(@var{max},)}, where @r{@var{max}} is the
4541 returned value of @code{GL_MAX_TEXTURE_SIZE}.
4543 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}},
4544 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)},
4545 @r{@var{yoffset}<-@var{b}}, or
4546 @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, where @r{@var{w}}
4547 is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the
4548 @code{GL_TEXTURE_HEIGHT}, and @r{@var{b}} is the
4549 @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that
4550 @r{@var{w}} and @r{@var{h}} include twice the border width.
4552 @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexSubImage2D}
4553 is executed between the execution of @code{glBegin} and the
4554 corresponding execution of @code{glEnd}.
4558 @deftypefun void glCopyTexSubImage3D target level xoffset yoffset zoffset x y width height
4559 Copy a three-dimensional texture subimage.
4563 Specifies the target texture. Must be @code{GL_TEXTURE_3D}
4566 Specifies the level-of-detail number. Level 0 is the base image level.
4567 Level @var{n} is the @var{n}th mipmap reduction image.
4570 Specifies a texel offset in the x direction within the texture array.
4573 Specifies a texel offset in the y direction within the texture array.
4576 Specifies a texel offset in the z direction within the texture array.
4580 Specify the window coordinates of the lower left corner of the
4581 rectangular region of pixels to be copied.
4584 Specifies the width of the texture subimage.
4587 Specifies the height of the texture subimage.
4591 @code{glCopyTexSubImage3D} replaces a rectangular portion of a
4592 three-dimensional texture image with pixels from the current
4593 @code{GL_READ_BUFFER} (rather than from main memory, as is the case for
4594 @code{glTexSubImage3D}).
4596 The screen-aligned pixel rectangle with lower left corner at (@var{x},\
4597 @var{y}) and with width @var{width} and height @var{height} replaces the
4598 portion of the texture array with x indices @var{xoffset} through
4599 @r{@var{xoffset}+@var{width}-1}, inclusive, and y indices @var{yoffset}
4600 through @r{@var{yoffset}+@var{height}-1}, inclusive, at z index
4601 @var{zoffset} and at the mipmap level specified by @var{level}.
4603 The pixels in the rectangle are processed exactly as if
4604 @code{glCopyPixels} had been called, but the process stops just before
4605 final conversion. At this point, all pixel component values are clamped
4606 to the range @r{[0,1]} and then converted to the texture's internal
4607 format for storage in the texel array.
4609 The destination rectangle in the texture array may not include any
4610 texels outside the texture array as it was originally specified. It is
4611 not an error to specify a subtexture with zero width or height, but such
4612 a specification has no effect.
4614 If any of the pixels within the specified rectangle of the current
4615 @code{GL_READ_BUFFER} are outside the read window associated with the
4616 current rendering context, then the values obtained for those pixels are
4619 No change is made to the @var{internalformat}, @var{width},
4620 @var{height}, @var{depth}, or @var{border} parameters of the specified
4621 texture array or to texel values outside the specified subregion.
4623 @code{GL_INVALID_ENUM} is generated if /@var{target} is not
4624 @code{GL_TEXTURE_3D}.
4626 @code{GL_INVALID_OPERATION} is generated if the texture array has not
4627 been defined by a previous @code{glTexImage3D} operation.
4629 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
4631 @code{GL_INVALID_VALUE} may be generated if
4632 @r{@var{level}>@var{log}_2(@var{max},)}, where @r{@var{max}} is the
4633 returned value of @code{GL_MAX_3D_TEXTURE_SIZE}.
4635 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}},
4636 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)},
4637 @r{@var{yoffset}<-@var{b}},
4638 @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)},
4639 @r{@var{zoffset}<-@var{b}}, or
4640 @r{(@var{zoffset}+1,)>(@var{d}-@var{b},)}, where @r{@var{w}} is the
4641 @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the @code{GL_TEXTURE_HEIGHT},
4642 @r{@var{d}} is the @code{GL_TEXTURE_DEPTH}, and @r{@var{b}} is the
4643 @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that
4644 @r{@var{w}}, @r{@var{h}}, and @r{@var{d}} include twice the border
4647 @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexSubImage3D}
4648 is executed between the execution of @code{glBegin} and the
4649 corresponding execution of @code{glEnd}.
4653 @deftypefun GLuint glCreateProgram
4654 Creates a program object.
4656 @code{glCreateProgram} creates an empty program object and returns a
4657 non-zero value by which it can be referenced. A program object is an
4658 object to which shader objects can be attached. This provides a
4659 mechanism to specify the shader objects that will be linked to create a
4660 program. It also provides a means for checking the compatibility of the
4661 shaders that will be used to create a program (for instance, checking
4662 the compatibility between a vertex shader and a fragment shader). When
4663 no longer needed as part of a program object, shader objects can be
4666 One or more executables are created in a program object by successfully
4667 attaching shader objects to it with @code{glAttachShader}, successfully
4668 compiling the shader objects with @code{glCompileShader}, and
4669 successfully linking the program object with @code{glLinkProgram}. These
4670 executables are made part of current state when @code{glUseProgram} is
4671 called. Program objects can be deleted by calling
4672 @code{glDeleteProgram}. The memory associated with the program object
4673 will be deleted when it is no longer part of current rendering state for
4676 This function returns 0 if an error occurs creating the program object.
4678 @code{GL_INVALID_OPERATION} is generated if @code{glCreateProgram} is
4679 executed between the execution of @code{glBegin} and the corresponding
4680 execution of @code{glEnd}.
4684 @deftypefun GLuint glCreateShader shaderType
4685 Creates a shader object.
4688 @item @var{shaderType}
4689 Specifies the type of shader to be created. Must be either
4690 @code{GL_VERTEX_SHADER} or @code{GL_FRAGMENT_SHADER}.
4694 @code{glCreateShader} creates an empty shader object and returns a
4695 non-zero value by which it can be referenced. A shader object is used to
4696 maintain the source code strings that define a shader. @var{shaderType}
4697 indicates the type of shader to be created. Two types of shaders are
4698 supported. A shader of type @code{GL_VERTEX_SHADER} is a shader that is
4699 intended to run on the programmable vertex processor and replace the
4700 fixed functionality vertex processing in OpenGL. A shader of type
4701 @code{GL_FRAGMENT_SHADER} is a shader that is intended to run on the
4702 programmable fragment processor and replace the fixed functionality
4703 fragment processing in OpenGL.
4705 When created, a shader object's @code{GL_SHADER_TYPE} parameter is set
4706 to either @code{GL_VERTEX_SHADER} or @code{GL_FRAGMENT_SHADER},
4707 depending on the value of @var{shaderType}.
4709 This function returns 0 if an error occurs creating the shader object.
4711 @code{GL_INVALID_ENUM} is generated if @var{shaderType} is not an
4714 @code{GL_INVALID_OPERATION} is generated if @code{glCreateShader} is
4715 executed between the execution of @code{glBegin} and the corresponding
4716 execution of @code{glEnd}.
4720 @deftypefun void glCullFace mode
4721 Specify whether front- or back-facing facets can be culled.
4725 Specifies whether front- or back-facing facets are candidates for
4726 culling. Symbolic constants @code{GL_FRONT}, @code{GL_BACK}, and
4727 @code{GL_FRONT_AND_BACK} are accepted. The initial value is
4732 @code{glCullFace} specifies whether front- or back-facing facets are
4733 culled (as specified by @var{mode}) when facet culling is enabled. Facet
4734 culling is initially disabled. To enable and disable facet culling, call
4735 the @code{glEnable} and @code{glDisable} commands with the argument
4736 @code{GL_CULL_FACE}. Facets include triangles, quadrilaterals, polygons,
4739 @code{glFrontFace} specifies which of the clockwise and counterclockwise
4740 facets are front-facing and back-facing. See @code{glFrontFace}.
4742 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
4745 @code{GL_INVALID_OPERATION} is generated if @code{glCullFace} is
4746 executed between the execution of @code{glBegin} and the corresponding
4747 execution of @code{glEnd}.
4751 @deftypefun void glDeleteBuffers n buffers
4752 Delete named buffer objects.
4756 Specifies the number of buffer objects to be deleted.
4759 Specifies an array of buffer objects to be deleted.
4763 @code{glDeleteBuffers} deletes @var{n} buffer objects named by the
4764 elements of the array @var{buffers}. After a buffer object is deleted,
4765 it has no contents, and its name is free for reuse (for example by
4766 @code{glGenBuffers}). If a buffer object that is currently bound is
4767 deleted, the binding reverts to 0 (the absence of any buffer object,
4768 which reverts to client memory usage).
4770 @code{glDeleteBuffers} silently ignores 0's and names that do not
4771 correspond to existing buffer objects.
4773 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
4775 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteBuffers} is
4776 executed between the execution of @code{glBegin} and the corresponding
4777 execution of @code{glEnd}.
4781 @deftypefun void glDeleteLists list range
4782 Delete a contiguous group of display lists.
4786 Specifies the integer name of the first display list to delete.
4789 Specifies the number of display lists to delete.
4793 @code{glDeleteLists} causes a contiguous group of display lists to be
4794 deleted. @var{list} is the name of the first display list to be deleted,
4795 and @var{range} is the number of display lists to delete. All display
4796 lists @r{@var{d}} with @r{@var{list}<=@var{d}<=@var{list}+@var{range}-1}
4799 All storage locations allocated to the specified display lists are
4800 freed, and the names are available for reuse at a later time. Names
4801 within the range that do not have an associated display list are
4802 ignored. If @var{range} is 0, nothing happens.
4804 @code{GL_INVALID_VALUE} is generated if @var{range} is negative.
4806 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteLists} is
4807 executed between the execution of @code{glBegin} and the corresponding
4808 execution of @code{glEnd}.
4812 @deftypefun void glDeleteProgram program
4813 Deletes a program object.
4817 Specifies the program object to be deleted.
4821 @code{glDeleteProgram} frees the memory and invalidates the name
4822 associated with the program object specified by @var{program.} This
4823 command effectively undoes the effects of a call to
4824 @code{glCreateProgram}.
4826 If a program object is in use as part of current rendering state, it
4827 will be flagged for deletion, but it will not be deleted until it is no
4828 longer part of current state for any rendering context. If a program
4829 object to be deleted has shader objects attached to it, those shader
4830 objects will be automatically detached but not deleted unless they have
4831 already been flagged for deletion by a previous call to
4832 @code{glDeleteShader}. A value of 0 for @var{program} will be silently
4835 To determine whether a program object has been flagged for deletion,
4836 call @code{glGetProgram} with arguments @var{program} and
4837 @code{GL_DELETE_STATUS}.
4839 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
4840 generated by OpenGL.
4842 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteProgram} is
4843 executed between the execution of @code{glBegin} and the corresponding
4844 execution of @code{glEnd}.
4848 @deftypefun void glDeleteQueries n ids
4849 Delete named query objects.
4853 Specifies the number of query objects to be deleted.
4856 Specifies an array of query objects to be deleted.
4860 @code{glDeleteQueries} deletes @var{n} query objects named by the
4861 elements of the array @var{ids}. After a query object is deleted, it has
4862 no contents, and its name is free for reuse (for example by
4863 @code{glGenQueries}).
4865 @code{glDeleteQueries} silently ignores 0's and names that do not
4866 correspond to existing query objects.
4868 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
4870 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteQueries} is
4871 executed between the execution of @code{glBegin} and the corresponding
4872 execution of @code{glEnd}.
4876 @deftypefun void glDeleteShader shader
4877 Deletes a shader object.
4881 Specifies the shader object to be deleted.
4885 @code{glDeleteShader} frees the memory and invalidates the name
4886 associated with the shader object specified by @var{shader}. This
4887 command effectively undoes the effects of a call to
4888 @code{glCreateShader}.
4890 If a shader object to be deleted is attached to a program object, it
4891 will be flagged for deletion, but it will not be deleted until it is no
4892 longer attached to any program object, for any rendering context (i.e.,
4893 it must be detached from wherever it was attached before it will be
4894 deleted). A value of 0 for @var{shader} will be silently ignored.
4896 To determine whether an object has been flagged for deletion, call
4897 @code{glGetShader} with arguments @var{shader} and
4898 @code{GL_DELETE_STATUS}.
4900 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
4901 generated by OpenGL.
4903 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteShader} is
4904 executed between the execution of @code{glBegin} and the corresponding
4905 execution of @code{glEnd}.
4909 @deftypefun void glDeleteTextures n textures
4910 Delete named textures.
4914 Specifies the number of textures to be deleted.
4916 @item @var{textures}
4917 Specifies an array of textures to be deleted.
4921 @code{glDeleteTextures} deletes @var{n} textures named by the elements
4922 of the array @var{textures}. After a texture is deleted, it has no
4923 contents or dimensionality, and its name is free for reuse (for example
4924 by @code{glGenTextures}). If a texture that is currently bound is
4925 deleted, the binding reverts to 0 (the default texture).
4927 @code{glDeleteTextures} silently ignores 0's and names that do not
4928 correspond to existing textures.
4930 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
4932 @code{GL_INVALID_OPERATION} is generated if @code{glDeleteTextures} is
4933 executed between the execution of @code{glBegin} and the corresponding
4934 execution of @code{glEnd}.
4938 @deftypefun void glDepthFunc func
4939 Specify the value used for depth buffer comparisons.
4943 Specifies the depth comparison function. Symbolic constants
4944 @code{GL_NEVER}, @code{GL_LESS}, @code{GL_EQUAL}, @code{GL_LEQUAL},
4945 @code{GL_GREATER}, @code{GL_NOTEQUAL}, @code{GL_GEQUAL}, and
4946 @code{GL_ALWAYS} are accepted. The initial value is @code{GL_LESS}.
4950 @code{glDepthFunc} specifies the function used to compare each incoming
4951 pixel depth value with the depth value present in the depth buffer. The
4952 comparison is performed only if depth testing is enabled. (See
4953 @code{glEnable} and @code{glDisable} of @code{GL_DEPTH_TEST}.)
4955 @var{func} specifies the conditions under which the pixel will be drawn.
4956 The comparison functions are as follows:
4959 @item @code{GL_NEVER}
4962 @item @code{GL_LESS}
4963 Passes if the incoming depth value is less than the stored depth value.
4965 @item @code{GL_EQUAL}
4966 Passes if the incoming depth value is equal to the stored depth value.
4968 @item @code{GL_LEQUAL}
4969 Passes if the incoming depth value is less than or equal to the stored
4972 @item @code{GL_GREATER}
4973 Passes if the incoming depth value is greater than the stored depth
4976 @item @code{GL_NOTEQUAL}
4977 Passes if the incoming depth value is not equal to the stored depth
4980 @item @code{GL_GEQUAL}
4981 Passes if the incoming depth value is greater than or equal to the
4984 @item @code{GL_ALWAYS}
4989 The initial value of @var{func} is @code{GL_LESS}. Initially, depth
4990 testing is disabled. If depth testing is disabled or if no depth buffer
4991 exists, it is as if the depth test always passes.
4993 @code{GL_INVALID_ENUM} is generated if @var{func} is not an accepted
4996 @code{GL_INVALID_OPERATION} is generated if @code{glDepthFunc} is
4997 executed between the execution of @code{glBegin} and the corresponding
4998 execution of @code{glEnd}.
5002 @deftypefun void glDepthMask flag
5003 Enable or disable writing into the depth buffer.
5007 Specifies whether the depth buffer is enabled for writing. If @var{flag}
5008 is @code{GL_FALSE}, depth buffer writing is disabled. Otherwise, it is
5009 enabled. Initially, depth buffer writing is enabled.
5013 @code{glDepthMask} specifies whether the depth buffer is enabled for
5014 writing. If @var{flag} is @code{GL_FALSE}, depth buffer writing is
5015 disabled. Otherwise, it is enabled. Initially, depth buffer writing is
5018 @code{GL_INVALID_OPERATION} is generated if @code{glDepthMask} is
5019 executed between the execution of @code{glBegin} and the corresponding
5020 execution of @code{glEnd}.
5024 @deftypefun void glDepthRange nearVal farVal
5025 Specify mapping of depth values from normalized device coordinates to
5030 Specifies the mapping of the near clipping plane to window coordinates.
5031 The initial value is 0.
5034 Specifies the mapping of the far clipping plane to window coordinates.
5035 The initial value is 1.
5039 After clipping and division by @var{w}, depth coordinates range from
5040 @r{-1} to 1, corresponding to the near and far clipping planes.
5041 @code{glDepthRange} specifies a linear mapping of the normalized depth
5042 coordinates in this range to window depth coordinates. Regardless of the
5043 actual depth buffer implementation, window coordinate depth values are
5044 treated as though they range from 0 through 1 (like color components).
5045 Thus, the values accepted by @code{glDepthRange} are both clamped to
5046 this range before they are accepted.
5048 The setting of (0,1) maps the near plane to 0 and the far plane to 1.
5049 With this mapping, the depth buffer range is fully utilized.
5051 @code{GL_INVALID_OPERATION} is generated if @code{glDepthRange} is
5052 executed between the execution of @code{glBegin} and the corresponding
5053 execution of @code{glEnd}.
5057 @deftypefun void glDetachShader program shader
5058 Detaches a shader object from a program object to which it is attached.
5062 Specifies the program object from which to detach the shader object.
5065 Specifies the shader object to be detached.
5069 @code{glDetachShader} detaches the shader object specified by
5070 @var{shader} from the program object specified by @var{program}. This
5071 command can be used to undo the effect of the command
5072 @code{glAttachShader}.
5074 If @var{shader} has already been flagged for deletion by a call to
5075 @code{glDeleteShader} and it is not attached to any other program
5076 object, it will be deleted after it has been detached.
5078 @code{GL_INVALID_VALUE} is generated if either @var{program} or
5079 @var{shader} is a value that was not generated by OpenGL.
5081 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
5084 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
5087 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not attached
5090 @code{GL_INVALID_OPERATION} is generated if @code{glDetachShader} is
5091 executed between the execution of @code{glBegin} and the corresponding
5092 execution of @code{glEnd}.
5096 @deftypefun void glDrawArrays mode first count
5097 Render primitives from array data.
5101 Specifies what kind of primitives to render. Symbolic constants
5102 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
5103 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
5104 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
5105 @code{GL_POLYGON} are accepted.
5108 Specifies the starting index in the enabled arrays.
5111 Specifies the number of indices to be rendered.
5115 @code{glDrawArrays} specifies multiple geometric primitives with very
5116 few subroutine calls. Instead of calling a GL procedure to pass each
5117 individual vertex, normal, texture coordinate, edge flag, or color, you
5118 can prespecify separate arrays of vertices, normals, and colors and use
5119 them to construct a sequence of primitives with a single call to
5120 @code{glDrawArrays}.
5122 When @code{glDrawArrays} is called, it uses @var{count} sequential
5123 elements from each enabled array to construct a sequence of geometric
5124 primitives, beginning with element @var{first}. @var{mode} specifies
5125 what kind of primitives are constructed and how the array elements
5126 construct those primitives. If @code{GL_VERTEX_ARRAY} is not enabled, no
5127 geometric primitives are generated.
5129 Vertex attributes that are modified by @code{glDrawArrays} have an
5130 unspecified value after @code{glDrawArrays} returns. For example, if
5131 @code{GL_COLOR_ARRAY} is enabled, the value of the current color is
5132 undefined after @code{glDrawArrays} executes. Attributes that aren't
5133 modified remain well defined.
5135 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
5138 @code{GL_INVALID_VALUE} is generated if @var{count} is negative.
5140 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5141 name is bound to an enabled array and the buffer object's data store is
5144 @code{GL_INVALID_OPERATION} is generated if @code{glDrawArrays} is
5145 executed between the execution of @code{glBegin} and the corresponding
5150 @deftypefun void glDrawBuffers n bufs
5151 Specifies a list of color buffers to be drawn into.
5155 Specifies the number of buffers in @var{bufs}.
5158 Points to an array of symbolic constants specifying the buffers into
5159 which fragment colors or data values will be written.
5163 @code{glDrawBuffers} defines an array of buffers into which fragment
5164 color values or fragment data will be written. If no fragment shader is
5165 active, rendering operations will generate only one fragment color per
5166 fragment and it will be written into each of the buffers specified by
5167 @var{bufs}. If a fragment shader is active and it writes a value to the
5168 output variable @code{gl_FragColor}, then that value will be written
5169 into each of the buffers specified by @var{bufs}. If a fragment shader
5170 is active and it writes a value to one or more elements of the output
5171 array variable @code{gl_FragData[]}, then the value of
5172 @code{gl_FragData[0] } will be written into the first buffer specified
5173 by @var{bufs}, the value of @code{gl_FragData[1] } will be written into
5174 the second buffer specified by @var{bufs}, and so on up to
5175 @code{gl_FragData[n-1]}. The draw buffer used for @code{gl_FragData[n]}
5176 and beyond is implicitly set to be @code{GL_NONE}.
5178 The symbolic constants contained in @var{bufs} may be any of the
5182 @item @code{GL_NONE}
5183 The fragment color/data value is not written into any color buffer.
5185 @item @code{GL_FRONT_LEFT}
5186 The fragment color/data value is written into the front left color
5189 @item @code{GL_FRONT_RIGHT}
5190 The fragment color/data value is written into the front right color
5193 @item @code{GL_BACK_LEFT}
5194 The fragment color/data value is written into the back left color
5197 @item @code{GL_BACK_RIGHT}
5198 The fragment color/data value is written into the back right color
5201 @item @code{GL_AUXi}
5202 The fragment color/data value is written into auxiliary buffer @code{i}.
5206 Except for @code{GL_NONE}, the preceding symbolic constants may not
5207 appear more than once in @var{bufs}. The maximum number of draw buffers
5208 supported is implementation dependent and can be queried by calling
5209 @code{glGet} with the argument @code{GL_MAX_DRAW_BUFFERS}. The number of
5210 auxiliary buffers can be queried by calling @code{glGet} with the
5211 argument @code{GL_AUX_BUFFERS}.
5213 @code{GL_INVALID_ENUM} is generated if one of the values in @var{bufs}
5214 is not an accepted value.
5216 @code{GL_INVALID_ENUM} is generated if @var{n} is less than 0.
5218 @code{GL_INVALID_OPERATION} is generated if a symbolic constant other
5219 than @code{GL_NONE} appears more than once in @var{bufs}.
5221 @code{GL_INVALID_OPERATION} is generated if any of the entries in
5222 @var{bufs} (other than @code{GL_NONE} ) indicates a color buffer that
5223 does not exist in the current GL context.
5225 @code{GL_INVALID_VALUE} is generated if @var{n} is greater than
5226 @code{GL_MAX_DRAW_BUFFERS}.
5228 @code{GL_INVALID_OPERATION} is generated if @code{glDrawBuffers} is
5229 executed between the execution of @code{glBegin} and the corresponding
5230 execution of @code{glEnd}.
5234 @deftypefun void glDrawBuffer mode
5235 Specify which color buffers are to be drawn into.
5239 Specifies up to four color buffers to be drawn into. Symbolic constants
5240 @code{GL_NONE}, @code{GL_FRONT_LEFT}, @code{GL_FRONT_RIGHT},
5241 @code{GL_BACK_LEFT}, @code{GL_BACK_RIGHT}, @code{GL_FRONT},
5242 @code{GL_BACK}, @code{GL_LEFT}, @code{GL_RIGHT},
5243 @code{GL_FRONT_AND_BACK}, and @code{GL_AUX}@var{i}, where @var{i} is
5244 between 0 and the value of @code{GL_AUX_BUFFERS} minus 1, are accepted.
5245 (@code{GL_AUX_BUFFERS} is not the upper limit; use @code{glGet} to query
5246 the number of available aux buffers.) The initial value is
5247 @code{GL_FRONT} for single-buffered contexts, and @code{GL_BACK} for
5248 double-buffered contexts.
5252 When colors are written to the frame buffer, they are written into the
5253 color buffers specified by @code{glDrawBuffer}. The specifications are
5257 @item @code{GL_NONE}
5258 No color buffers are written.
5260 @item @code{GL_FRONT_LEFT}
5261 Only the front left color buffer is written.
5263 @item @code{GL_FRONT_RIGHT}
5264 Only the front right color buffer is written.
5266 @item @code{GL_BACK_LEFT}
5267 Only the back left color buffer is written.
5269 @item @code{GL_BACK_RIGHT}
5270 Only the back right color buffer is written.
5272 @item @code{GL_FRONT}
5273 Only the front left and front right color buffers are written. If there
5274 is no front right color buffer, only the front left color buffer is
5277 @item @code{GL_BACK}
5278 Only the back left and back right color buffers are written. If there is
5279 no back right color buffer, only the back left color buffer is written.
5281 @item @code{GL_LEFT}
5282 Only the front left and back left color buffers are written. If there is
5283 no back left color buffer, only the front left color buffer is written.
5285 @item @code{GL_RIGHT}
5286 Only the front right and back right color buffers are written. If there
5287 is no back right color buffer, only the front right color buffer is
5290 @item @code{GL_FRONT_AND_BACK}
5291 All the front and back color buffers (front left, front right, back
5292 left, back right) are written. If there are no back color buffers, only
5293 the front left and front right color buffers are written. If there are
5294 no right color buffers, only the front left and back left color buffers
5295 are written. If there are no right or back color buffers, only the front
5296 left color buffer is written.
5298 @item @code{GL_AUX}@var{i}
5299 Only auxiliary color buffer @var{i} is written.
5303 If more than one color buffer is selected for drawing, then blending or
5304 logical operations are computed and applied independently for each color
5305 buffer and can produce different results in each buffer.
5307 Monoscopic contexts include only @var{left} buffers, and stereoscopic
5308 contexts include both @var{left} and @var{right} buffers. Likewise,
5309 single-buffered contexts include only @var{front} buffers, and
5310 double-buffered contexts include both @var{front} and @var{back}
5311 buffers. The context is selected at GL initialization.
5313 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
5316 @code{GL_INVALID_OPERATION} is generated if none of the buffers
5317 indicated by @var{mode} exists.
5319 @code{GL_INVALID_OPERATION} is generated if @code{glDrawBuffer} is
5320 executed between the execution of @code{glBegin} and the corresponding
5321 execution of @code{glEnd}.
5325 @deftypefun void glDrawElements mode count type indices
5326 Render primitives from array data.
5330 Specifies what kind of primitives to render. Symbolic constants
5331 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
5332 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
5333 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
5334 @code{GL_POLYGON} are accepted.
5337 Specifies the number of elements to be rendered.
5340 Specifies the type of the values in @var{indices}. Must be one of
5341 @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or
5342 @code{GL_UNSIGNED_INT}.
5345 Specifies a pointer to the location where the indices are stored.
5349 @code{glDrawElements} specifies multiple geometric primitives with very
5350 few subroutine calls. Instead of calling a GL function to pass each
5351 individual vertex, normal, texture coordinate, edge flag, or color, you
5352 can prespecify separate arrays of vertices, normals, and so on, and use
5353 them to construct a sequence of primitives with a single call to
5354 @code{glDrawElements}.
5356 When @code{glDrawElements} is called, it uses @var{count} sequential
5357 elements from an enabled array, starting at @var{indices} to construct a
5358 sequence of geometric primitives. @var{mode} specifies what kind of
5359 primitives are constructed and how the array elements construct these
5360 primitives. If more than one array is enabled, each is used. If
5361 @code{GL_VERTEX_ARRAY} is not enabled, no geometric primitives are
5364 Vertex attributes that are modified by @code{glDrawElements} have an
5365 unspecified value after @code{glDrawElements} returns. For example, if
5366 @code{GL_COLOR_ARRAY} is enabled, the value of the current color is
5367 undefined after @code{glDrawElements} executes. Attributes that aren't
5368 modified maintain their previous values.
5370 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
5373 @code{GL_INVALID_VALUE} is generated if @var{count} is negative.
5375 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5376 name is bound to an enabled array or the element array and the buffer
5377 object's data store is currently mapped.
5379 @code{GL_INVALID_OPERATION} is generated if @code{glDrawElements} is
5380 executed between the execution of @code{glBegin} and the corresponding
5385 @deftypefun void glDrawPixels width height format type data
5386 Write a block of pixels to the frame buffer.
5391 Specify the dimensions of the pixel rectangle to be written into the
5395 Specifies the format of the pixel data. Symbolic constants
5396 @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX},
5397 @code{GL_DEPTH_COMPONENT}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA},
5398 @code{GL_BGRA}, @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE},
5399 @code{GL_ALPHA}, @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA} are
5403 Specifies the data type for @var{data}. Symbolic constants
5404 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
5405 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
5406 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
5407 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
5408 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
5409 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
5410 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
5411 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
5412 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
5415 Specifies a pointer to the pixel data.
5419 @code{glDrawPixels} reads pixel data from memory and writes it into the
5420 frame buffer relative to the current raster position, provided that the
5421 raster position is valid. Use @code{glRasterPos} or @code{glWindowPos}
5422 to set the current raster position; use @code{glGet} with argument
5423 @code{GL_CURRENT_RASTER_POSITION_VALID} to determine if the specified
5424 raster position is valid, and @code{glGet} with argument
5425 @code{GL_CURRENT_RASTER_POSITION} to query the raster position.
5427 Several parameters define the encoding of pixel data in memory and
5428 control the processing of the pixel data before it is placed in the
5429 frame buffer. These parameters are set with four commands:
5430 @code{glPixelStore}, @code{glPixelTransfer}, @code{glPixelMap}, and
5431 @code{glPixelZoom}. This reference page describes the effects on
5432 @code{glDrawPixels} of many, but not all, of the parameters specified by
5433 these four commands.
5435 Data is read from @var{data} as a sequence of signed or unsigned bytes,
5436 signed or unsigned shorts, signed or unsigned integers, or
5437 single-precision floating-point values, depending on @var{type}. When
5438 @var{type} is one of @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE},
5439 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
5440 @code{GL_INT}, or @code{GL_FLOAT} each of these bytes, shorts, integers,
5441 or floating-point values is interpreted as one color or depth component,
5442 or one index, depending on @var{format}. When @var{type} is one of
5443 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_SHORT_5_6_5},
5444 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
5445 @code{GL_UNSIGNED_INT_8_8_8_8}, or @code{GL_UNSIGNED_INT_10_10_10_2},
5446 each unsigned value is interpreted as containing all the components for
5447 a single pixel, with the color components arranged according to
5448 @var{format}. When @var{type} is one of
5449 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
5450 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
5451 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
5452 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, or
5453 @code{GL_UNSIGNED_INT_2_10_10_10_REV}, each unsigned value is
5454 interpreted as containing all color components, specified by
5455 @var{format}, for a single pixel in a reversed order. Indices are always
5456 treated individually. Color components are treated as groups of one,
5457 two, three, or four values, again based on @var{format}. Both individual
5458 indices and groups of components are referred to as pixels. If
5459 @var{type} is @code{GL_BITMAP}, the data must be unsigned bytes, and
5460 @var{format} must be either @code{GL_COLOR_INDEX} or
5461 @code{GL_STENCIL_INDEX}. Each unsigned byte is treated as eight 1-bit
5462 pixels, with bit ordering determined by @code{GL_UNPACK_LSB_FIRST} (see
5463 @code{glPixelStore}).
5465 @r{@var{width}×@var{height}} pixels are read from memory, starting at
5466 location @var{data}. By default, these pixels are taken from adjacent
5467 memory locations, except that after all @var{width} pixels are read, the
5468 read pointer is advanced to the next four-byte boundary. The four-byte
5469 row alignment is specified by @code{glPixelStore} with argument
5470 @code{GL_UNPACK_ALIGNMENT}, and it can be set to one, two, four, or
5471 eight bytes. Other pixel store parameters specify different read pointer
5472 advancements, both before the first pixel is read and after all
5473 @var{width} pixels are read. See the @code{glPixelStore} reference page
5474 for details on these options.
5476 If a non-zero named buffer object is bound to the
5477 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
5478 block of pixels is specified, @var{data} is treated as a byte offset
5479 into the buffer object's data store.
5481 The @r{@var{width}×@var{height}} pixels that are read from memory are
5482 each operated on in the same way, based on the values of several
5483 parameters specified by @code{glPixelTransfer} and @code{glPixelMap}.
5484 The details of these operations, as well as the target buffer into which
5485 the pixels are drawn, are specific to the format of the pixels, as
5486 specified by @var{format}. @var{format} can assume one of 13 symbolic
5490 @item @code{GL_COLOR_INDEX}
5491 Each pixel is a single value, a color index. It is converted to
5492 fixed-point format, with an unspecified number of bits to the right of
5493 the binary point, regardless of the memory data type. Floating-point
5494 values convert to true fixed-point values. Signed and unsigned integer
5495 data is converted with all fraction bits set to 0. Bitmap data convert
5498 Each fixed-point index is then shifted left by @code{GL_INDEX_SHIFT}
5499 bits and added to @code{GL_INDEX_OFFSET}. If @code{GL_INDEX_SHIFT} is
5500 negative, the shift is to the right. In either case, zero bits fill
5501 otherwise unspecified bit locations in the result.
5503 If the GL is in RGBA mode, the resulting index is converted to an RGBA
5504 pixel with the help of the @code{GL_PIXEL_MAP_I_TO_R},
5505 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
5506 @code{GL_PIXEL_MAP_I_TO_A} tables. If the GL is in color index mode, and
5507 if @code{GL_MAP_COLOR} is true, the index is replaced with the value
5508 that it references in lookup table @code{GL_PIXEL_MAP_I_TO_I}. Whether
5509 the lookup replacement of the index is done or not, the integer part of
5510 the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the
5511 number of bits in a color index buffer.
5513 The GL then converts the resulting indices or RGBA colors to fragments
5514 by attaching the current raster position @var{z} coordinate and texture
5515 coordinates to each pixel, then assigning @r{@var{x}} and @r{@var{y}}
5516 window coordinates to the @r{@var{n}}th fragment such that
5517 @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},⌋}
5519 where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster
5520 position. These pixel fragments are then treated just like the fragments
5521 generated by rasterizing points, lines, or polygons. Texture mapping,
5522 fog, and all the fragment operations are applied before the fragments
5523 are written to the frame buffer.
5525 @item @code{GL_STENCIL_INDEX}
5526 Each pixel is a single value, a stencil index. It is converted to
5527 fixed-point format, with an unspecified number of bits to the right of
5528 the binary point, regardless of the memory data type. Floating-point
5529 values convert to true fixed-point values. Signed and unsigned integer
5530 data is converted with all fraction bits set to 0. Bitmap data convert
5533 Each fixed-point index is then shifted left by @code{GL_INDEX_SHIFT}
5534 bits, and added to @code{GL_INDEX_OFFSET}. If @code{GL_INDEX_SHIFT} is
5535 negative, the shift is to the right. In either case, zero bits fill
5536 otherwise unspecified bit locations in the result. If
5537 @code{GL_MAP_STENCIL} is true, the index is replaced with the value that
5538 it references in lookup table @code{GL_PIXEL_MAP_S_TO_S}. Whether the
5539 lookup replacement of the index is done or not, the integer part of the
5540 index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the
5541 number of bits in the stencil buffer. The resulting stencil indices are
5542 then written to the stencil buffer such that the @r{@var{n}}th index is
5545 @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},⌋}
5547 where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster
5548 position. Only the pixel ownership test, the scissor test, and the
5549 stencil writemask affect these write operations.
5551 @item @code{GL_DEPTH_COMPONENT}
5552 Each pixel is a single-depth component. Floating-point data is converted
5553 directly to an internal floating-point format with unspecified
5554 precision. Signed integer data is mapped linearly to the internal
5555 floating-point format such that the most positive representable integer
5556 value maps to 1.0, and the most negative representable value maps to
5557 @r{-1.0}. Unsigned integer data is mapped similarly: the largest integer
5558 value maps to 1.0, and 0 maps to 0.0. The resulting floating-point depth
5559 value is then multiplied by @code{GL_DEPTH_SCALE} and added to
5560 @code{GL_DEPTH_BIAS}. The result is clamped to the range @r{[0,1]}.
5562 The GL then converts the resulting depth components to fragments by
5563 attaching the current raster position color or color index and texture
5564 coordinates to each pixel, then assigning @r{@var{x}} and @r{@var{y}}
5565 window coordinates to the @r{@var{n}}th fragment such that
5567 @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},⌋}
5569 where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster
5570 position. These pixel fragments are then treated just like the fragments
5571 generated by rasterizing points, lines, or polygons. Texture mapping,
5572 fog, and all the fragment operations are applied before the fragments
5573 are written to the frame buffer.
5575 @item @code{GL_RGBA}
5576 @item @code{GL_BGRA}
5577 Each pixel is a four-component group: For @code{GL_RGBA}, the red
5578 component is first, followed by green, followed by blue, followed by
5579 alpha; for @code{GL_BGRA} the order is blue, green, red and then alpha.
5580 Floating-point values are converted directly to an internal
5581 floating-point format with unspecified precision. Signed integer values
5582 are mapped linearly to the internal floating-point format such that the
5583 most positive representable integer value maps to 1.0, and the most
5584 negative representable value maps to @r{-1.0}. (Note that this mapping
5585 does not convert 0 precisely to 0.0.) Unsigned integer data is mapped
5586 similarly: The largest integer value maps to 1.0, and 0 maps to 0.0. The
5587 resulting floating-point color values are then multiplied by
5588 @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is RED,
5589 GREEN, BLUE, and ALPHA for the respective color components. The results
5590 are clamped to the range @r{[0,1]}.
5592 If @code{GL_MAP_COLOR} is true, each color component is scaled by the
5593 size of lookup table @code{GL_PIXEL_MAP_c_TO_c}, then replaced by the
5594 value that it references in that table. @var{c} is R, G, B, or A
5597 The GL then converts the resulting RGBA colors to fragments by attaching
5598 the current raster position @var{z} coordinate and texture coordinates
5599 to each pixel, then assigning @r{@var{x}} and @r{@var{y}} window
5600 coordinates to the @r{@var{n}}th fragment such that
5602 @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},⌋}
5604 where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster
5605 position. These pixel fragments are then treated just like the fragments
5606 generated by rasterizing points, lines, or polygons. Texture mapping,
5607 fog, and all the fragment operations are applied before the fragments
5608 are written to the frame buffer.
5611 Each pixel is a single red component. This component is converted to the
5612 internal floating-point format in the same way the red component of an
5613 RGBA pixel is. It is then converted to an RGBA pixel with green and blue
5614 set to 0, and alpha set to 1. After this conversion, the pixel is
5615 treated as if it had been read as an RGBA pixel.
5617 @item @code{GL_GREEN}
5618 Each pixel is a single green component. This component is converted to
5619 the internal floating-point format in the same way the green component
5620 of an RGBA pixel is. It is then converted to an RGBA pixel with red and
5621 blue set to 0, and alpha set to 1. After this conversion, the pixel is
5622 treated as if it had been read as an RGBA pixel.
5624 @item @code{GL_BLUE}
5625 Each pixel is a single blue component. This component is converted to
5626 the internal floating-point format in the same way the blue component of
5627 an RGBA pixel is. It is then converted to an RGBA pixel with red and
5628 green set to 0, and alpha set to 1. After this conversion, the pixel is
5629 treated as if it had been read as an RGBA pixel.
5631 @item @code{GL_ALPHA}
5632 Each pixel is a single alpha component. This component is converted to
5633 the internal floating-point format in the same way the alpha component
5634 of an RGBA pixel is. It is then converted to an RGBA pixel with red,
5635 green, and blue set to 0. After this conversion, the pixel is treated as
5636 if it had been read as an RGBA pixel.
5640 Each pixel is a three-component group: red first, followed by green,
5641 followed by blue; for @code{GL_BGR}, the first component is blue,
5642 followed by green and then red. Each component is converted to the
5643 internal floating-point format in the same way the red, green, and blue
5644 components of an RGBA pixel are. The color triple is converted to an
5645 RGBA pixel with alpha set to 1. After this conversion, the pixel is
5646 treated as if it had been read as an RGBA pixel.
5648 @item @code{GL_LUMINANCE}
5649 Each pixel is a single luminance component. This component is converted
5650 to the internal floating-point format in the same way the red component
5651 of an RGBA pixel is. It is then converted to an RGBA pixel with red,
5652 green, and blue set to the converted luminance value, and alpha set to
5653 1. After this conversion, the pixel is treated as if it had been read as
5656 @item @code{GL_LUMINANCE_ALPHA}
5657 Each pixel is a two-component group: luminance first, followed by alpha.
5658 The two components are converted to the internal floating-point format
5659 in the same way the red component of an RGBA pixel is. They are then
5660 converted to an RGBA pixel with red, green, and blue set to the
5661 converted luminance value, and alpha set to the converted alpha value.
5662 After this conversion, the pixel is treated as if it had been read as an
5667 The following table summarizes the meaning of the valid constants for
5668 the @var{type} parameter:
5674 @strong{Corresponding Type}
5676 @item @code{GL_UNSIGNED_BYTE}
5677 unsigned 8-bit integer
5679 @item @code{GL_BYTE}
5680 signed 8-bit integer
5682 @item @code{GL_BITMAP}
5683 single bits in unsigned 8-bit integers
5685 @item @code{GL_UNSIGNED_SHORT}
5686 unsigned 16-bit integer
5688 @item @code{GL_SHORT}
5689 signed 16-bit integer
5691 @item @code{GL_UNSIGNED_INT}
5692 unsigned 32-bit integer
5697 @item @code{GL_FLOAT}
5698 single-precision floating-point
5700 @item @code{GL_UNSIGNED_BYTE_3_3_2}
5701 unsigned 8-bit integer
5703 @item @code{GL_UNSIGNED_BYTE_2_3_3_REV}
5704 unsigned 8-bit integer with reversed component ordering
5706 @item @code{GL_UNSIGNED_SHORT_5_6_5}
5707 unsigned 16-bit integer
5709 @item @code{GL_UNSIGNED_SHORT_5_6_5_REV}
5710 unsigned 16-bit integer with reversed component ordering
5712 @item @code{GL_UNSIGNED_SHORT_4_4_4_4}
5713 unsigned 16-bit integer
5715 @item @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}
5716 unsigned 16-bit integer with reversed component ordering
5718 @item @code{GL_UNSIGNED_SHORT_5_5_5_1}
5719 unsigned 16-bit integer
5721 @item @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}
5722 unsigned 16-bit integer with reversed component ordering
5724 @item @code{GL_UNSIGNED_INT_8_8_8_8}
5725 unsigned 32-bit integer
5727 @item @code{GL_UNSIGNED_INT_8_8_8_8_REV}
5728 unsigned 32-bit integer with reversed component ordering
5730 @item @code{GL_UNSIGNED_INT_10_10_10_2}
5731 unsigned 32-bit integer
5733 @item @code{GL_UNSIGNED_INT_2_10_10_10_REV}
5734 unsigned 32-bit integer with reversed component ordering
5740 The rasterization described so far assumes pixel zoom factors of 1. If
5741 @code{glPixelZoom} is used to change the @r{@var{x}} and @r{@var{y}}
5742 pixel zoom factors, pixels are converted to fragments as follows. If
5743 @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position,
5744 and a given pixel is in the @r{@var{n}}th column and @r{@var{m}}th row
5745 of the pixel rectangle, then fragments are generated for pixels whose
5746 centers are in the rectangle with corners at
5748 @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,))}
5750 where @r{@var{zoom}_@var{x}} is the value of @code{GL_ZOOM_X} and
5751 @r{@var{zoom}_@var{y}} is the value of @code{GL_ZOOM_Y}.
5753 @code{GL_INVALID_ENUM} is generated if @var{format} or @var{type} is not
5754 one of the accepted values.
5756 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
5757 and @var{format} is not either @code{GL_COLOR_INDEX} or
5758 @code{GL_STENCIL_INDEX}.
5760 @code{GL_INVALID_VALUE} is generated if either @var{width} or
5761 @var{height} is negative.
5763 @code{GL_INVALID_OPERATION} is generated if @var{format} is
5764 @code{GL_STENCIL_INDEX} and there is no stencil buffer.
5766 @code{GL_INVALID_OPERATION} is generated if @var{format} is
5767 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
5768 @code{GL_RGB}, @code{GL_RGBA}, @code{GL_BGR}, @code{GL_BGRA},
5769 @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}, and the GL is in
5772 @code{GL_INVALID_OPERATION} is generated if @var{format} is one of
5773 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
5774 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
5775 and @var{format} is not @code{GL_RGB}.
5777 @code{GL_INVALID_OPERATION} is generated if @var{format} is one of
5778 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
5779 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
5780 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
5781 @code{GL_UNSIGNED_INT_10_10_10_2}, or
5782 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
5783 @code{GL_RGBA} nor @code{GL_BGRA}.
5785 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5786 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
5787 object's data store is currently mapped.
5789 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5790 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
5791 would be unpacked from the buffer object such that the memory reads
5792 required would exceed the data store size.
5794 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5795 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
5796 is not evenly divisible into the number of bytes needed to store in
5797 memory a datum indicated by @var{type}.
5799 @code{GL_INVALID_OPERATION} is generated if @code{glDrawPixels} is
5800 executed between the execution of @code{glBegin} and the corresponding
5801 execution of @code{glEnd}.
5805 @deftypefun void glDrawRangeElements mode start end count type indices
5806 Render primitives from array data.
5810 Specifies what kind of primitives to render. Symbolic constants
5811 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
5812 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
5813 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
5814 @code{GL_POLYGON} are accepted.
5817 Specifies the minimum array index contained in @var{indices}.
5820 Specifies the maximum array index contained in @var{indices}.
5823 Specifies the number of elements to be rendered.
5826 Specifies the type of the values in @var{indices}. Must be one of
5827 @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or
5828 @code{GL_UNSIGNED_INT}.
5831 Specifies a pointer to the location where the indices are stored.
5835 @code{glDrawRangeElements} is a restricted form of
5836 @code{glDrawElements}. @var{mode}, @var{start}, @var{end}, and
5837 @var{count} match the corresponding arguments to @code{glDrawElements},
5838 with the additional constraint that all values in the arrays @var{count}
5839 must lie between @var{start} and @var{end}, inclusive.
5841 Implementations denote recommended maximum amounts of vertex and index
5842 data, which may be queried by calling @code{glGet} with argument
5843 @code{GL_MAX_ELEMENTS_VERTICES} and @code{GL_MAX_ELEMENTS_INDICES}. If
5844 @r{@var{end}-@var{start}+1} is greater than the value of
5845 @code{GL_MAX_ELEMENTS_VERTICES}, or if @var{count} is greater than the
5846 value of @code{GL_MAX_ELEMENTS_INDICES}, then the call may operate at
5847 reduced performance. There is no requirement that all vertices in the
5848 range @r{[@var{start},@var{end}]} be referenced. However, the
5849 implementation may partially process unused vertices, reducing
5850 performance from what could be achieved with an optimal index set.
5852 When @code{glDrawRangeElements} is called, it uses @var{count}
5853 sequential elements from an enabled array, starting at @var{start} to
5854 construct a sequence of geometric primitives. @var{mode} specifies what
5855 kind of primitives are constructed, and how the array elements construct
5856 these primitives. If more than one array is enabled, each is used. If
5857 @code{GL_VERTEX_ARRAY} is not enabled, no geometric primitives are
5860 Vertex attributes that are modified by @code{glDrawRangeElements} have
5861 an unspecified value after @code{glDrawRangeElements} returns. For
5862 example, if @code{GL_COLOR_ARRAY} is enabled, the value of the current
5863 color is undefined after @code{glDrawRangeElements} executes. Attributes
5864 that aren't modified maintain their previous values.
5866 It is an error for indices to lie outside the range
5867 @r{[@var{start},@var{end}]}, but implementations may not check for this
5868 situation. Such indices cause implementation-dependent behavior.
5870 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
5873 @code{GL_INVALID_VALUE} is generated if @var{count} is negative.
5875 @code{GL_INVALID_VALUE} is generated if @r{@var{end}<@var{start}}.
5877 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
5878 name is bound to an enabled array or the element array and the buffer
5879 object's data store is currently mapped.
5881 @code{GL_INVALID_OPERATION} is generated if @code{glDrawRangeElements}
5882 is executed between the execution of @code{glBegin} and the
5883 corresponding @code{glEnd}.
5887 @deftypefun void glEdgeFlagPointer stride pointer
5888 Define an array of edge flags.
5892 Specifies the byte offset between consecutive edge flags. If
5893 @var{stride} is 0, the edge flags are understood to be tightly packed in
5894 the array. The initial value is 0.
5897 Specifies a pointer to the first edge flag in the array. The initial
5902 @code{glEdgeFlagPointer} specifies the location and data format of an
5903 array of boolean edge flags to use when rendering. @var{stride}
5904 specifies the byte stride from one edge flag to the next, allowing
5905 vertices and attributes to be packed into a single array or stored in
5908 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
5909 target (see @code{glBindBuffer}) while an edge flag array is specified,
5910 @var{pointer} is treated as a byte offset into the buffer object's data
5911 store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING})
5912 is saved as edge flag vertex array client-side state
5913 (@code{GL_EDGE_FLAG_ARRAY_BUFFER_BINDING}).
5915 When an edge flag array is specified, @var{stride} and @var{pointer} are
5916 saved as client-side state, in addition to the current vertex array
5917 buffer object binding.
5919 To enable and disable the edge flag array, call
5920 @code{glEnableClientState} and @code{glDisableClientState} with the
5921 argument @code{GL_EDGE_FLAG_ARRAY}. If enabled, the edge flag array is
5922 used when @code{glDrawArrays}, @code{glMultiDrawArrays},
5923 @code{glDrawElements}, @code{glMultiDrawElements},
5924 @code{glDrawRangeElements}, or @code{glArrayElement} is called.
5926 @code{GL_INVALID_ENUM} is generated if @var{stride} is negative.
5930 @deftypefun void glEdgeFlag flag
5931 Flag edges as either boundary or nonboundary.
5935 Specifies the current edge flag value, either @code{GL_TRUE} or
5936 @code{GL_FALSE}. The initial value is @code{GL_TRUE}.
5940 Each vertex of a polygon, separate triangle, or separate quadrilateral
5941 specified between a @code{glBegin}/@code{glEnd} pair is marked as the
5942 start of either a boundary or nonboundary edge. If the current edge flag
5943 is true when the vertex is specified, the vertex is marked as the start
5944 of a boundary edge. Otherwise, the vertex is marked as the start of a
5945 nonboundary edge. @code{glEdgeFlag} sets the edge flag bit to
5946 @code{GL_TRUE} if @var{flag} is @code{GL_TRUE} and to @code{GL_FALSE}
5949 The vertices of connected triangles and connected quadrilaterals are
5950 always marked as boundary, regardless of the value of the edge flag.
5952 Boundary and nonboundary edge flags on vertices are significant only if
5953 @code{GL_POLYGON_MODE} is set to @code{GL_POINT} or @code{GL_LINE}. See
5954 @code{glPolygonMode}.
5958 @deftypefun void glEnableClientState cap
5959 @deftypefunx void glDisableClientState cap
5960 Enable or disable client-side capability.
5964 Specifies the capability to enable. Symbolic constants
5965 @code{GL_COLOR_ARRAY}, @code{GL_EDGE_FLAG_ARRAY},
5966 @code{GL_FOG_COORD_ARRAY}, @code{GL_INDEX_ARRAY},
5967 @code{GL_NORMAL_ARRAY}, @code{GL_SECONDARY_COLOR_ARRAY},
5968 @code{GL_TEXTURE_COORD_ARRAY}, and @code{GL_VERTEX_ARRAY} are accepted.
5972 @code{glEnableClientState} and @code{glDisableClientState} enable or
5973 disable individual client-side capabilities. By default, all client-side
5974 capabilities are disabled. Both @code{glEnableClientState} and
5975 @code{glDisableClientState} take a single argument, @var{cap}, which can
5976 assume one of the following values:
5979 @item @code{GL_COLOR_ARRAY}
5980 If enabled, the color array is enabled for writing and used during
5981 rendering when @code{glArrayElement}, @code{glDrawArrays},
5982 @code{glDrawElements},
5983 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
5984 @code{glMultiDrawElements} is called. See @code{glColorPointer}.
5986 @item @code{GL_EDGE_FLAG_ARRAY}
5987 If enabled, the edge flag array is enabled for writing and used during
5988 rendering when @code{glArrayElement}, @code{glDrawArrays},
5989 @code{glDrawElements},
5990 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
5991 @code{glMultiDrawElements} is called. See @code{glEdgeFlagPointer}.
5993 @item @code{GL_FOG_COORD_ARRAY}
5994 If enabled, the fog coordinate array is enabled for writing and used
5995 during rendering when @code{glArrayElement}, @code{glDrawArrays},
5996 @code{glDrawElements},
5997 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
5998 @code{glMultiDrawElements} is called. See @code{glFogCoordPointer}.
6000 @item @code{GL_INDEX_ARRAY}
6001 If enabled, the index array is enabled for writing and used during
6002 rendering when @code{glArrayElement}, @code{glDrawArrays},
6003 @code{glDrawElements},
6004 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6005 @code{glMultiDrawElements} is called. See @code{glIndexPointer}.
6007 @item @code{GL_NORMAL_ARRAY}
6008 If enabled, the normal array is enabled for writing and used during
6009 rendering when @code{glArrayElement}, @code{glDrawArrays},
6010 @code{glDrawElements},
6011 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6012 @code{glMultiDrawElements} is called. See @code{glNormalPointer}.
6014 @item @code{GL_SECONDARY_COLOR_ARRAY}
6015 If enabled, the secondary color array is enabled for writing and used
6016 during rendering when @code{glArrayElement}, @code{glDrawArrays},
6017 @code{glDrawElements},
6018 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6019 @code{glMultiDrawElements} is called. See @code{glColorPointer}.
6021 @item @code{GL_TEXTURE_COORD_ARRAY}
6022 If enabled, the texture coordinate array is enabled for writing and used
6023 during rendering when @code{glArrayElement}, @code{glDrawArrays},
6024 @code{glDrawElements},
6025 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6026 @code{glMultiDrawElements} is called. See @code{glTexCoordPointer}.
6028 @item @code{GL_VERTEX_ARRAY}
6029 If enabled, the vertex array is enabled for writing and used during
6030 rendering when @code{glArrayElement}, @code{glDrawArrays},
6031 @code{glDrawElements},
6032 @code{glDrawRangeElements}@code{glMultiDrawArrays}, or
6033 @code{glMultiDrawElements} is called. See @code{glVertexPointer}.
6037 @code{GL_INVALID_ENUM} is generated if @var{cap} is not an accepted
6040 @code{glEnableClientState} is not allowed between the execution of
6041 @code{glBegin} and the corresponding @code{glEnd}, but an error may or
6042 may not be generated. If no error is generated, the behavior is
6047 @deftypefun void glEnableVertexAttribArray index
6048 @deftypefunx void glDisableVertexAttribArray index
6049 Enable or disable a generic vertex attribute array.
6053 Specifies the index of the generic vertex attribute to be enabled or
6058 @code{glEnableVertexAttribArray} enables the generic vertex attribute
6059 array specified by @var{index}. @code{glDisableVertexAttribArray}
6060 disables the generic vertex attribute array specified by @var{index}. By
6061 default, all client-side capabilities are disabled, including all
6062 generic vertex attribute arrays. If enabled, the values in the generic
6063 vertex attribute array will be accessed and used for rendering when
6064 calls are made to vertex array commands such as @code{glDrawArrays},
6065 @code{glDrawElements}, @code{glDrawRangeElements},
6066 @code{glArrayElement}, @code{glMultiDrawElements}, or
6067 @code{glMultiDrawArrays}.
6069 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
6070 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
6072 @code{GL_INVALID_OPERATION} is generated if either
6073 @code{glEnableVertexAttribArray } or @code{glDisableVertexAttribArray }
6074 is executed between the execution of @code{glBegin} and the
6075 corresponding execution of @code{glEnd}.
6079 @deftypefun void glEnable cap
6080 @deftypefunx void glDisable cap
6081 Enable or disable server-side GL capabilities.
6085 Specifies a symbolic constant indicating a GL capability.
6089 @code{glEnable} and @code{glDisable} enable and disable various
6090 capabilities. Use @code{glIsEnabled} or @code{glGet} to determine the
6091 current setting of any capability. The initial value for each capability
6092 with the exception of @code{GL_DITHER} and @code{GL_MULTISAMPLE} is
6093 @code{GL_FALSE}. The initial value for @code{GL_DITHER} and
6094 @code{GL_MULTISAMPLE} is @code{GL_TRUE}.
6096 Both @code{glEnable} and @code{glDisable} take a single argument,
6097 @var{cap}, which can assume one of the following values:
6100 @item @code{GL_ALPHA_TEST}
6103 If enabled, do alpha testing. See @code{glAlphaFunc}.
6105 @item @code{GL_AUTO_NORMAL}
6108 If enabled, generate normal vectors when either @code{GL_MAP2_VERTEX_3}
6109 or @code{GL_MAP2_VERTEX_4} is used to generate vertices. See
6112 @item @code{GL_BLEND}
6115 If enabled, blend the computed fragment color values with the values in
6116 the color buffers. See @code{glBlendFunc}.
6118 @item @code{GL_CLIP_PLANE}@var{i}
6121 If enabled, clip geometry against user-defined clipping plane @var{i}.
6122 See @code{glClipPlane}.
6124 @item @code{GL_COLOR_LOGIC_OP}
6127 If enabled, apply the currently selected logical operation to the
6128 computed fragment color and color buffer values. See @code{glLogicOp}.
6130 @item @code{GL_COLOR_MATERIAL}
6133 If enabled, have one or more material parameters track the current
6134 color. See @code{glColorMaterial}.
6136 @item @code{GL_COLOR_SUM}
6139 If enabled and no fragment shader is active, add the secondary color
6140 value to the computed fragment color. See @code{glSecondaryColor}.
6142 @item @code{GL_COLOR_TABLE}
6145 If enabled, perform a color table lookup on the incoming RGBA color
6146 values. See @code{glColorTable}.
6148 @item @code{GL_CONVOLUTION_1D}
6151 If enabled, perform a 1D convolution operation on incoming RGBA color
6152 values. See @code{glConvolutionFilter1D}.
6154 @item @code{GL_CONVOLUTION_2D}
6157 If enabled, perform a 2D convolution operation on incoming RGBA color
6158 values. See @code{glConvolutionFilter2D}.
6160 @item @code{GL_CULL_FACE}
6163 If enabled, cull polygons based on their winding in window coordinates.
6164 See @code{glCullFace}.
6166 @item @code{GL_DEPTH_TEST}
6169 If enabled, do depth comparisons and update the depth buffer. Note that
6170 even if the depth buffer exists and the depth mask is non-zero, the
6171 depth buffer is not updated if the depth test is disabled. See
6172 @code{glDepthFunc} and @code{glDepthRange}.
6174 @item @code{GL_DITHER}
6177 If enabled, dither color components or indices before they are written
6178 to the color buffer.
6183 If enabled and no fragment shader is active, blend a fog color into the
6184 post-texturing color. See @code{glFog}.
6186 @item @code{GL_HISTOGRAM}
6189 If enabled, histogram incoming RGBA color values. See
6192 @item @code{GL_INDEX_LOGIC_OP}
6195 If enabled, apply the currently selected logical operation to the
6196 incoming index and color buffer indices. See @code{glLogicOp}.
6198 @item @code{GL_LIGHT}@var{i}
6201 If enabled, include light @var{i} in the evaluation of the lighting
6202 equation. See @code{glLightModel} and @code{glLight}.
6204 @item @code{GL_LIGHTING}
6207 If enabled and no vertex shader is active, use the current lighting
6208 parameters to compute the vertex color or index. Otherwise, simply
6209 associate the current color or index with each vertex. See
6210 @code{glMaterial}, @code{glLightModel}, and @code{glLight}.
6212 @item @code{GL_LINE_SMOOTH}
6215 If enabled, draw lines with correct filtering. Otherwise, draw aliased
6216 lines. See @code{glLineWidth}.
6218 @item @code{GL_LINE_STIPPLE}
6221 If enabled, use the current line stipple pattern when drawing lines. See
6222 @code{glLineStipple}.
6224 @item @code{GL_MAP1_COLOR_4}
6227 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6228 @code{glEvalPoint1} generate RGBA values. See @code{glMap1}.
6230 @item @code{GL_MAP1_INDEX}
6233 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6234 @code{glEvalPoint1} generate color indices. See @code{glMap1}.
6236 @item @code{GL_MAP1_NORMAL}
6239 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6240 @code{glEvalPoint1} generate normals. See @code{glMap1}.
6242 @item @code{GL_MAP1_TEXTURE_COORD_1}
6245 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6246 @code{glEvalPoint1} generate @var{s} texture coordinates. See
6249 @item @code{GL_MAP1_TEXTURE_COORD_2}
6252 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6253 @code{glEvalPoint1} generate @var{s} and @var{t} texture coordinates.
6256 @item @code{GL_MAP1_TEXTURE_COORD_3}
6259 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6260 @code{glEvalPoint1} generate @var{s}, @var{t}, and @var{r} texture
6261 coordinates. See @code{glMap1}.
6263 @item @code{GL_MAP1_TEXTURE_COORD_4}
6266 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6267 @code{glEvalPoint1} generate @var{s}, @var{t}, @var{r}, and @var{q}
6268 texture coordinates. See @code{glMap1}.
6270 @item @code{GL_MAP1_VERTEX_3}
6273 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6274 @code{glEvalPoint1} generate @var{x}, @var{y}, and @var{z} vertex
6275 coordinates. See @code{glMap1}.
6277 @item @code{GL_MAP1_VERTEX_4}
6280 If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and
6281 @code{glEvalPoint1} generate homogeneous @var{x}, @var{y}, @var{z}, and
6282 @var{w} vertex coordinates. See @code{glMap1}.
6284 @item @code{GL_MAP2_COLOR_4}
6287 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6288 @code{glEvalPoint2} generate RGBA values. See @code{glMap2}.
6290 @item @code{GL_MAP2_INDEX}
6293 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6294 @code{glEvalPoint2} generate color indices. See @code{glMap2}.
6296 @item @code{GL_MAP2_NORMAL}
6299 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6300 @code{glEvalPoint2} generate normals. See @code{glMap2}.
6302 @item @code{GL_MAP2_TEXTURE_COORD_1}
6305 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6306 @code{glEvalPoint2} generate @var{s} texture coordinates. See
6309 @item @code{GL_MAP2_TEXTURE_COORD_2}
6312 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6313 @code{glEvalPoint2} generate @var{s} and @var{t} texture coordinates.
6316 @item @code{GL_MAP2_TEXTURE_COORD_3}
6319 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6320 @code{glEvalPoint2} generate @var{s}, @var{t}, and @var{r} texture
6321 coordinates. See @code{glMap2}.
6323 @item @code{GL_MAP2_TEXTURE_COORD_4}
6326 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6327 @code{glEvalPoint2} generate @var{s}, @var{t}, @var{r}, and @var{q}
6328 texture coordinates. See @code{glMap2}.
6330 @item @code{GL_MAP2_VERTEX_3}
6333 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6334 @code{glEvalPoint2} generate @var{x}, @var{y}, and @var{z} vertex
6335 coordinates. See @code{glMap2}.
6337 @item @code{GL_MAP2_VERTEX_4}
6340 If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and
6341 @code{glEvalPoint2} generate homogeneous @var{x}, @var{y}, @var{z}, and
6342 @var{w} vertex coordinates. See @code{glMap2}.
6344 @item @code{GL_MINMAX}
6347 If enabled, compute the minimum and maximum values of incoming RGBA
6348 color values. See @code{glMinmax}.
6350 @item @code{GL_MULTISAMPLE}
6353 If enabled, use multiple fragment samples in computing the final color
6354 of a pixel. See @code{glSampleCoverage}.
6356 @item @code{GL_NORMALIZE}
6359 If enabled and no vertex shader is active, normal vectors are normalized
6360 to unit length after transformation and before lighting. This method is
6361 generally less efficient than @code{GL_RESCALE_NORMAL}. See
6362 @code{glNormal} and @code{glNormalPointer}.
6364 @item @code{GL_POINT_SMOOTH}
6367 If enabled, draw points with proper filtering. Otherwise, draw aliased
6368 points. See @code{glPointSize}.
6370 @item @code{GL_POINT_SPRITE}
6373 If enabled, calculate texture coordinates for points based on texture
6374 environment and point parameter settings. Otherwise texture coordinates
6375 are constant across points.
6377 @item @code{GL_POLYGON_OFFSET_FILL}
6380 If enabled, and if the polygon is rendered in @code{GL_FILL} mode, an
6381 offset is added to depth values of a polygon's fragments before the
6382 depth comparison is performed. See @code{glPolygonOffset}.
6384 @item @code{GL_POLYGON_OFFSET_LINE}
6387 If enabled, and if the polygon is rendered in @code{GL_LINE} mode, an
6388 offset is added to depth values of a polygon's fragments before the
6389 depth comparison is performed. See @code{glPolygonOffset}.
6391 @item @code{GL_POLYGON_OFFSET_POINT}
6394 If enabled, an offset is added to depth values of a polygon's fragments
6395 before the depth comparison is performed, if the polygon is rendered in
6396 @code{GL_POINT} mode. See @code{glPolygonOffset}.
6398 @item @code{GL_POLYGON_SMOOTH}
6401 If enabled, draw polygons with proper filtering. Otherwise, draw aliased
6402 polygons. For correct antialiased polygons, an alpha buffer is needed
6403 and the polygons must be sorted front to back.
6405 @item @code{GL_POLYGON_STIPPLE}
6408 If enabled, use the current polygon stipple pattern when rendering
6409 polygons. See @code{glPolygonStipple}.
6411 @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}
6414 If enabled, perform a color table lookup on RGBA color values after
6415 color matrix transformation. See @code{glColorTable}.
6417 @item @code{GL_POST_CONVOLUTION_COLOR_TABLE}
6420 If enabled, perform a color table lookup on RGBA color values after
6421 convolution. See @code{glColorTable}.
6423 @item @code{GL_RESCALE_NORMAL}
6426 If enabled and no vertex shader is active, normal vectors are scaled
6427 after transformation and before lighting by a factor computed from the
6428 modelview matrix. If the modelview matrix scales space uniformly, this
6429 has the effect of restoring the transformed normal to unit length. This
6430 method is generally more efficient than @code{GL_NORMALIZE}. See
6431 @code{glNormal} and @code{glNormalPointer}.
6433 @item @code{GL_SAMPLE_ALPHA_TO_COVERAGE}
6436 If enabled, compute a temporary coverage value where each bit is
6437 determined by the alpha value at the corresponding sample location. The
6438 temporary coverage value is then ANDed with the fragment coverage value.
6440 @item @code{GL_SAMPLE_ALPHA_TO_ONE}
6443 If enabled, each sample alpha value is replaced by the maximum
6444 representable alpha value.
6446 @item @code{GL_SAMPLE_COVERAGE}
6449 If enabled, the fragment's coverage is ANDed with the temporary coverage
6450 value. If @code{GL_SAMPLE_COVERAGE_INVERT} is set to @code{GL_TRUE},
6451 invert the coverage value. See @code{glSampleCoverage}.
6453 @item @code{GL_SEPARABLE_2D}
6456 If enabled, perform a two-dimensional convolution operation using a
6457 separable convolution filter on incoming RGBA color values. See
6458 @code{glSeparableFilter2D}.
6460 @item @code{GL_SCISSOR_TEST}
6463 If enabled, discard fragments that are outside the scissor rectangle.
6464 See @code{glScissor}.
6466 @item @code{GL_STENCIL_TEST}
6469 If enabled, do stencil testing and update the stencil buffer. See
6470 @code{glStencilFunc} and @code{glStencilOp}.
6472 @item @code{GL_TEXTURE_1D}
6475 If enabled and no fragment shader is active, one-dimensional texturing
6476 is performed (unless two- or three-dimensional or cube-mapped texturing
6477 is also enabled). See @code{glTexImage1D}.
6479 @item @code{GL_TEXTURE_2D}
6482 If enabled and no fragment shader is active, two-dimensional texturing
6483 is performed (unless three-dimensional or cube-mapped texturing is also
6484 enabled). See @code{glTexImage2D}.
6486 @item @code{GL_TEXTURE_3D}
6489 If enabled and no fragment shader is active, three-dimensional texturing
6490 is performed (unless cube-mapped texturing is also enabled). See
6491 @code{glTexImage3D}.
6493 @item @code{GL_TEXTURE_CUBE_MAP}
6496 If enabled and no fragment shader is active, cube-mapped texturing is
6497 performed. See @code{glTexImage2D}.
6499 @item @code{GL_TEXTURE_GEN_Q}
6502 If enabled and no vertex shader is active, the @var{q} texture
6503 coordinate is computed using the texture generation function defined
6504 with @code{glTexGen}. Otherwise, the current @var{q} texture coordinate
6505 is used. See @code{glTexGen}.
6507 @item @code{GL_TEXTURE_GEN_R}
6510 If enabled and no vertex shader is active, the @var{r} texture
6511 coordinate is computed using the texture generation function defined
6512 with @code{glTexGen}. Otherwise, the current @var{r} texture coordinate
6513 is used. See @code{glTexGen}.
6515 @item @code{GL_TEXTURE_GEN_S}
6518 If enabled and no vertex shader is active, the @var{s} texture
6519 coordinate is computed using the texture generation function defined
6520 with @code{glTexGen}. Otherwise, the current @var{s} texture coordinate
6521 is used. See @code{glTexGen}.
6523 @item @code{GL_TEXTURE_GEN_T}
6526 If enabled and no vertex shader is active, the @var{t} texture
6527 coordinate is computed using the texture generation function defined
6528 with @code{glTexGen}. Otherwise, the current @var{t} texture coordinate
6529 is used. See @code{glTexGen}.
6531 @item @code{GL_VERTEX_PROGRAM_POINT_SIZE}
6534 If enabled and a vertex shader is active, then the derived point size is
6535 taken from the (potentially clipped) shader builtin @code{gl_PointSize}
6536 and clamped to the implementation-dependent point size range.
6538 @item @code{GL_VERTEX_PROGRAM_TWO_SIDE}
6541 If enabled and a vertex shader is active, it specifies that the GL will
6542 choose between front and back colors based on the polygon's face
6543 direction of which the vertex being shaded is a part. It has no effect
6548 @code{GL_INVALID_ENUM} is generated if @var{cap} is not one of the
6549 values listed previously.
6551 @code{GL_INVALID_OPERATION} is generated if @code{glEnable} or
6552 @code{glDisable} is executed between the execution of @code{glBegin} and
6553 the corresponding execution of @code{glEnd}.
6557 @deftypefun void glEvalCoord1f u
6558 @deftypefunx void glEvalCoord2f u v
6559 Evaluate enabled one- and two-dimensional maps.
6563 Specifies a value that is the domain coordinate @r{@var{u}} to the basis
6564 function defined in a previous @code{glMap1} or @code{glMap2} command.
6567 Specifies a value that is the domain coordinate @r{@var{v}} to the basis
6568 function defined in a previous @code{glMap2} command. This argument is
6569 not present in a @code{glEvalCoord1} command.
6573 @code{glEvalCoord1} evaluates enabled one-dimensional maps at argument
6574 @var{u}. @code{glEvalCoord2} does the same for two-dimensional maps
6575 using two domain values, @var{u} and @var{v}. To define a map, call
6576 @code{glMap1} and @code{glMap2}; to enable and disable it, call
6577 @code{glEnable} and @code{glDisable}.
6579 When one of the @code{glEvalCoord} commands is issued, all currently
6580 enabled maps of the indicated dimension are evaluated. Then, for each
6581 enabled map, it is as if the corresponding GL command had been issued
6582 with the computed value. That is, if @code{GL_MAP1_INDEX} or
6583 @code{GL_MAP2_INDEX} is enabled, a @code{glIndex} command is simulated.
6584 If @code{GL_MAP1_COLOR_4} or @code{GL_MAP2_COLOR_4} is enabled, a
6585 @code{glColor} command is simulated. If @code{GL_MAP1_NORMAL} or
6586 @code{GL_MAP2_NORMAL} is enabled, a normal vector is produced, and if
6587 any of @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2},
6588 @code{GL_MAP1_TEXTURE_COORD_3}, @code{GL_MAP1_TEXTURE_COORD_4},
6589 @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2},
6590 @code{GL_MAP2_TEXTURE_COORD_3}, or @code{GL_MAP2_TEXTURE_COORD_4} is
6591 enabled, then an appropriate @code{glTexCoord} command is simulated.
6593 For color, color index, normal, and texture coordinates the GL uses
6594 evaluated values instead of current values for those evaluations that
6595 are enabled, and current values otherwise, However, the evaluated values
6596 do not update the current values. Thus, if @code{glVertex} commands are
6597 interspersed with @code{glEvalCoord} commands, the color, normal, and
6598 texture coordinates associated with the @code{glVertex} commands are not
6599 affected by the values generated by the @code{glEvalCoord} commands, but
6600 only by the most recent @code{glColor}, @code{glIndex}, @code{glNormal},
6601 and @code{glTexCoord} commands.
6603 No commands are issued for maps that are not enabled. If more than one
6604 texture evaluation is enabled for a particular dimension (for example,
6605 @code{GL_MAP2_TEXTURE_COORD_1} and @code{GL_MAP2_TEXTURE_COORD_2}), then
6606 only the evaluation of the map that produces the larger number of
6607 coordinates (in this case, @code{GL_MAP2_TEXTURE_COORD_2}) is carried
6608 out. @code{GL_MAP1_VERTEX_4} overrides @code{GL_MAP1_VERTEX_3}, and
6609 @code{GL_MAP2_VERTEX_4} overrides @code{GL_MAP2_VERTEX_3}, in the same
6610 manner. If neither a three- nor a four-component vertex map is enabled
6611 for the specified dimension, the @code{glEvalCoord} command is ignored.
6613 If you have enabled automatic normal generation, by calling
6614 @code{glEnable} with argument @code{GL_AUTO_NORMAL}, @code{glEvalCoord2}
6615 generates surface normals analytically, regardless of the contents or
6616 enabling of the @code{GL_MAP2_NORMAL} map. Let
6618 @r{@code{m}=∂@code{p},/∂@var{u},,×∂@code{p},/∂@var{v},,}
6620 Then the generated normal @r{@code{n}} is
6621 @r{@code{n}=@code{m}/∥@code{m},∥,}
6623 If automatic normal generation is disabled, the corresponding normal map
6624 @code{GL_MAP2_NORMAL}, if enabled, is used to produce a normal. If
6625 neither automatic normal generation nor a normal map is enabled, no
6626 normal is generated for @code{glEvalCoord2} commands.
6630 @deftypefun void glEvalMesh1 mode i1 i2
6631 @deftypefunx void glEvalMesh2 mode i1 i2 j1 j2
6632 Compute a one- or two-dimensional grid of points or lines.
6636 In @code{glEvalMesh1}, specifies whether to compute a one-dimensional
6637 mesh of points or lines. Symbolic constants @code{GL_POINT} and
6638 @code{GL_LINE} are accepted.
6642 Specify the first and last integer values for grid domain variable
6647 @code{glMapGrid} and @code{glEvalMesh} are used in tandem to efficiently
6648 generate and evaluate a series of evenly-spaced map domain values.
6649 @code{glEvalMesh} steps through the integer domain of a one- or
6650 two-dimensional grid, whose range is the domain of the evaluation maps
6651 specified by @code{glMap1} and @code{glMap2}. @var{mode} determines
6652 whether the resulting vertices are connected as points, lines, or filled
6655 In the one-dimensional case, @code{glEvalMesh1}, the mesh is generated
6656 as if the following code fragment were executed:
6662 glBegin( @var{type} );
6663 for ( i = @var{i1}; i <= @var{i2}; i += 1 )
6664 glEvalCoord1( @r{i·Δ@var{u}+@var{u}_1} );
6668 @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}
6670 and @r{@var{n}}, @r{@var{u}_1}, and @r{@var{u}_2} are the arguments to
6671 the most recent @code{glMapGrid1} command. @var{type} is
6672 @code{GL_POINTS} if @var{mode} is @code{GL_POINT}, or @code{GL_LINES} if
6673 @var{mode} is @code{GL_LINE}.
6675 The one absolute numeric requirement is that if @r{@var{i}=@var{n}},
6676 then the value computed from @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly
6679 In the two-dimensional case, @code{glEvalMesh2}, let .cp
6680 @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}
6682 @r{Δ@var{v}=(@var{v}_2-@var{v}_1,)/@var{m}}
6684 where @r{@var{n}}, @r{@var{u}_1}, @r{@var{u}_2}, @r{@var{m}},
6685 @r{@var{v}_1}, and @r{@var{v}_2} are the arguments to the most recent
6686 @code{glMapGrid2} command. Then, if @var{mode} is @code{GL_FILL}, the
6687 @code{glEvalMesh2} command is equivalent to:
6693 for ( j = @var{j1}; j < @var{j2}; j += 1 ) @{
6694 glBegin( GL_QUAD_STRIP );
6695 for ( i = @var{i1}; i <= @var{i2}; i += 1 ) @{
6696 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6697 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,(j+1,)·Δ@var{v}+@var{v}_1} );
6703 If @var{mode} is @code{GL_LINE}, then a call to @code{glEvalMesh2} is
6710 for ( j = @var{j1}; j <= @var{j2}; j += 1 ) @{
6711 glBegin( GL_LINE_STRIP );
6712 for ( i = @var{i1}; i <= @var{i2}; i += 1 )
6713 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6717 for ( i = @var{i1}; i <= @var{i2}; i += 1 ) @{
6718 glBegin( GL_LINE_STRIP );
6719 for ( j = @var{j1}; j <= @var{j1}; j += 1 )
6720 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6725 And finally, if @var{mode} is @code{GL_POINT}, then a call to
6726 @code{glEvalMesh2} is equivalent to:
6732 glBegin( GL_POINTS );
6733 for ( j = @var{j1}; j <= @var{j2}; j += 1 )
6734 for ( i = @var{i1}; i <= @var{i2}; i += 1 )
6735 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6739 In all three cases, the only absolute numeric requirements are that if
6740 @r{@var{i}=@var{n}}, then the value computed from
6741 @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}, and if
6742 @r{@var{j}=@var{m}}, then the value computed from
6743 @r{@var{j}·Δ@var{v}+@var{v}_1} is exactly @r{@var{v}_2}.
6745 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
6748 @code{GL_INVALID_OPERATION} is generated if @code{glEvalMesh} is
6749 executed between the execution of @code{glBegin} and the corresponding
6750 execution of @code{glEnd}.
6754 @deftypefun void glEvalPoint1 i
6755 @deftypefunx void glEvalPoint2 i j
6756 Generate and evaluate a single point in a mesh.
6760 Specifies the integer value for grid domain variable @r{@var{i}}.
6763 Specifies the integer value for grid domain variable @r{@var{j}}
6764 (@code{glEvalPoint2} only).
6768 @code{glMapGrid} and @code{glEvalMesh} are used in tandem to efficiently
6769 generate and evaluate a series of evenly spaced map domain values.
6770 @code{glEvalPoint} can be used to evaluate a single grid point in the
6771 same gridspace that is traversed by @code{glEvalMesh}. Calling
6772 @code{glEvalPoint1} is equivalent to calling where
6773 @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}
6777 glEvalCoord1( @r{i·Δ@var{u}+@var{u}_1} );
6780 and @r{@var{n}}, @r{@var{u}_1}, and @r{@var{u}_2} are the arguments to
6781 the most recent @code{glMapGrid1} command. The one absolute numeric
6782 requirement is that if @r{@var{i}=@var{n}}, then the value computed from
6783 @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}.
6785 In the two-dimensional case, @code{glEvalPoint2}, let
6787 @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}@r{Δ@var{v}=(@var{v}_2-@var{v}_1,)/@var{m}}
6789 where @r{@var{n}}, @r{@var{u}_1}, @r{@var{u}_2}, @r{@var{m}},
6790 @r{@var{v}_1}, and @r{@var{v}_2} are the arguments to the most recent
6791 @code{glMapGrid2} command. Then the @code{glEvalPoint2} command is
6792 equivalent to calling The only absolute numeric requirements are that if
6793 @r{@var{i}=@var{n}}, then the value computed from
6794 @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}, and if
6795 @r{@var{j}=@var{m}}, then the value computed from
6796 @r{@var{j}·Δ@var{v}+@var{v}_1} is exactly @r{@var{v}_2}.
6800 glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} );
6805 @deftypefun void glFeedbackBuffer size type buffer
6806 Controls feedback mode.
6810 Specifies the maximum number of values that can be written into
6814 Specifies a symbolic constant that describes the information that will
6815 be returned for each vertex. @code{GL_2D}, @code{GL_3D},
6816 @code{GL_3D_COLOR}, @code{GL_3D_COLOR_TEXTURE}, and
6817 @code{GL_4D_COLOR_TEXTURE} are accepted.
6820 Returns the feedback data.
6824 The @code{glFeedbackBuffer} function controls feedback. Feedback, like
6825 selection, is a GL mode. The mode is selected by calling
6826 @code{glRenderMode} with @code{GL_FEEDBACK}. When the GL is in feedback
6827 mode, no pixels are produced by rasterization. Instead, information
6828 about primitives that would have been rasterized is fed back to the
6829 application using the GL.
6831 @code{glFeedbackBuffer} has three arguments: @var{buffer} is a pointer
6832 to an array of floating-point values into which feedback information is
6833 placed. @var{size} indicates the size of the array. @var{type} is a
6834 symbolic constant describing the information that is fed back for each
6835 vertex. @code{glFeedbackBuffer} must be issued before feedback mode is
6836 enabled (by calling @code{glRenderMode} with argument
6837 @code{GL_FEEDBACK}). Setting @code{GL_FEEDBACK} without establishing the
6838 feedback buffer, or calling @code{glFeedbackBuffer} while the GL is in
6839 feedback mode, is an error.
6841 When @code{glRenderMode} is called while in feedback mode, it returns
6842 the number of entries placed in the feedback array and resets the
6843 feedback array pointer to the base of the feedback buffer. The returned
6844 value never exceeds @var{size}. If the feedback data required more room
6845 than was available in @var{buffer}, @code{glRenderMode} returns a
6846 negative value. To take the GL out of feedback mode, call
6847 @code{glRenderMode} with a parameter value other than
6850 While in feedback mode, each primitive, bitmap, or pixel rectangle that
6851 would be rasterized generates a block of values that are copied into the
6852 feedback array. If doing so would cause the number of entries to exceed
6853 the maximum, the block is partially written so as to fill the array (if
6854 there is any room left at all), and an overflow flag is set. Each block
6855 begins with a code indicating the primitive type, followed by values
6856 that describe the primitive's vertices and associated data. Entries are
6857 also written for bitmaps and pixel rectangles. Feedback occurs after
6858 polygon culling and @code{glPolygonMode} interpretation of polygons has
6859 taken place, so polygons that are culled are not returned in the
6860 feedback buffer. It can also occur after polygons with more than three
6861 edges are broken up into triangles, if the GL implementation renders
6862 polygons by performing this decomposition.
6864 The @code{glPassThrough} command can be used to insert a marker into the
6865 feedback buffer. See @code{glPassThrough}.
6867 Following is the grammar for the blocks of values written into the
6868 feedback buffer. Each primitive is indicated with a unique identifying
6869 value followed by some number of vertices. Polygon entries include an
6870 integer value indicating how many vertices follow. A vertex is fed back
6871 as some number of floating-point values, as determined by @var{type}.
6872 Colors are fed back as four values in RGBA mode and one value in color
6875 feedbackList @r{←} feedbackItem feedbackList | feedbackItem feedbackItem
6876 @r{←} point | lineSegment | polygon | bitmap | pixelRectangle | passThru
6877 point @r{←}@code{GL_POINT_TOKEN} vertex lineSegment
6878 @r{←}@code{GL_LINE_TOKEN} vertex vertex | @code{GL_LINE_RESET_TOKEN}
6879 vertex vertex polygon @r{←}@code{GL_POLYGON_TOKEN} n polySpec polySpec
6880 @r{←} polySpec vertex | vertex vertex vertex bitmap
6881 @r{←}@code{GL_BITMAP_TOKEN} vertex pixelRectangle
6882 @r{←}@code{GL_DRAW_PIXEL_TOKEN} vertex | @code{GL_COPY_PIXEL_TOKEN}
6883 vertex passThru @r{←}@code{GL_PASS_THROUGH_TOKEN} value vertex @r{←} 2d
6884 | 3d | 3dColor | 3dColorTexture | 4dColorTexture 2d @r{←} value value 3d
6885 @r{←} value value value 3dColor @r{←} value value value color
6886 3dColorTexture @r{←} value value value color tex 4dColorTexture @r{←}
6887 value value value value color tex color @r{←} rgba | index rgba @r{←}
6888 value value value value index @r{←} value tex @r{←} value value value
6891 @var{value} is a floating-point number, and @var{n} is a floating-point
6892 integer giving the number of vertices in the polygon.
6893 @code{GL_POINT_TOKEN}, @code{GL_LINE_TOKEN}, @code{GL_LINE_RESET_TOKEN},
6894 @code{GL_POLYGON_TOKEN}, @code{GL_BITMAP_TOKEN},
6895 @code{GL_DRAW_PIXEL_TOKEN}, @code{GL_COPY_PIXEL_TOKEN} and
6896 @code{GL_PASS_THROUGH_TOKEN} are symbolic floating-point constants.
6897 @code{GL_LINE_RESET_TOKEN} is returned whenever the line stipple pattern
6898 is reset. The data returned as a vertex depends on the feedback
6901 The following table gives the correspondence between @var{type} and the
6902 number of values per vertex. @var{k} is 1 in color index mode and 4 in
6909 @strong{Coordinates}, @strong{Color}, @strong{Texture}, @strong{Total
6913 @var{x}, @var{y}, , , 2
6916 @var{x}, @var{y}, @var{z}, , , 3
6918 @item @code{GL_3D_COLOR}
6919 @var{x}, @var{y}, @var{z}, @r{@var{k}}, , @r{3+@var{k}}
6921 @item @code{GL_3D_COLOR_TEXTURE}
6922 @var{x}, @var{y}, @var{z}, @r{@var{k}}, 4 , @r{7+@var{k}}
6924 @item @code{GL_4D_COLOR_TEXTURE}
6925 @var{x}, @var{y}, @var{z}, @var{w}, @r{@var{k}}, 4 , @r{8+@var{k}}
6929 Feedback vertex coordinates are in window coordinates, except @var{w},
6930 which is in clip coordinates. Feedback colors are lighted, if lighting
6931 is enabled. Feedback texture coordinates are generated, if texture
6932 coordinate generation is enabled. They are always transformed by the
6935 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
6938 @code{GL_INVALID_VALUE} is generated if @var{size} is negative.
6940 @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is
6941 called while the render mode is @code{GL_FEEDBACK}, or if
6942 @code{glRenderMode} is called with argument @code{GL_FEEDBACK} before
6943 @code{glFeedbackBuffer} is called at least once.
6945 @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is
6946 executed between the execution of @code{glBegin} and the corresponding
6947 execution of @code{glEnd}.
6951 @deftypefun void glFinish
6952 Block until all GL execution is complete.
6954 @code{glFinish} does not return until the effects of all previously
6955 called GL commands are complete. Such effects include all changes to GL
6956 state, all changes to connection state, and all changes to the frame
6959 @code{GL_INVALID_OPERATION} is generated if @code{glFinish} is executed
6960 between the execution of @code{glBegin} and the corresponding execution
6965 @deftypefun void glFlush
6966 Force execution of GL commands in finite time.
6968 Different GL implementations buffer commands in several different
6969 locations, including network buffers and the graphics accelerator
6970 itself. @code{glFlush} empties all of these buffers, causing all issued
6971 commands to be executed as quickly as they are accepted by the actual
6972 rendering engine. Though this execution may not be completed in any
6973 particular time period, it does complete in finite time.
6975 Because any GL program might be executed over a network, or on an
6976 accelerator that buffers commands, all programs should call
6977 @code{glFlush} whenever they count on having all of their previously
6978 issued commands completed. For example, call @code{glFlush} before
6979 waiting for user input that depends on the generated image.
6981 @code{GL_INVALID_OPERATION} is generated if @code{glFlush} is executed
6982 between the execution of @code{glBegin} and the corresponding execution
6987 @deftypefun void glFogCoordPointer type stride pointer
6988 Define an array of fog coordinates.
6992 Specifies the data type of each fog coordinate. Symbolic constants
6993 @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is
6997 Specifies the byte offset between consecutive fog coordinates. If
6998 @var{stride} is 0, the array elements are understood to be tightly
6999 packed. The initial value is 0.
7002 Specifies a pointer to the first coordinate of the first fog coordinate
7003 in the array. The initial value is 0.
7007 @code{glFogCoordPointer} specifies the location and data format of an
7008 array of fog coordinates to use when rendering. @var{type} specifies the
7009 data type of each fog coordinate, and @var{stride} specifies the byte
7010 stride from one fog coordinate to the next, allowing vertices and
7011 attributes to be packed into a single array or stored in separate
7014 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
7015 target (see @code{glBindBuffer}) while a fog coordinate array is
7016 specified, @var{pointer} is treated as a byte offset into the buffer
7017 object's data store. Also, the buffer object binding
7018 (@code{GL_ARRAY_BUFFER_BINDING}) is saved as fog coordinate vertex array
7019 client-side state (@code{GL_FOG_COORD_ARRAY_BUFFER_BINDING}).
7021 When a fog coordinate array is specified, @var{type}, @var{stride}, and
7022 @var{pointer} are saved as client-side state, in addition to the current
7023 vertex array buffer object binding.
7025 To enable and disable the fog coordinate array, call
7026 @code{glEnableClientState} and @code{glDisableClientState} with the
7027 argument @code{GL_FOG_COORD_ARRAY}. If enabled, the fog coordinate array
7028 is used when @code{glDrawArrays}, @code{glMultiDrawArrays},
7029 @code{glDrawElements}, @code{glMultiDrawElements},
7030 @code{glDrawRangeElements}, or @code{glArrayElement} is called.
7032 @code{GL_INVALID_ENUM} is generated if @var{type} is not either
7033 @code{GL_FLOAT} or @code{GL_DOUBLE}.
7035 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
7039 @deftypefun void glFogCoordf coord
7040 Set the current fog coordinates.
7044 Specify the fog distance.
7048 @code{glFogCoord} specifies the fog coordinate that is associated with
7049 each vertex and the current raster position. The value specified is
7050 interpolated and used in computing the fog color (see @code{glFog}).
7054 @deftypefun void glFogf pname param
7055 @deftypefunx void glFogi pname param
7056 Specify fog parameters.
7060 Specifies a single-valued fog parameter. @code{GL_FOG_MODE},
7061 @code{GL_FOG_DENSITY}, @code{GL_FOG_START}, @code{GL_FOG_END},
7062 @code{GL_FOG_INDEX}, and @code{GL_FOG_COORD_SRC} are accepted.
7065 Specifies the value that @var{pname} will be set to.
7069 Fog is initially disabled. While enabled, fog affects rasterized
7070 geometry, bitmaps, and pixel blocks, but not buffer clear operations. To
7071 enable and disable fog, call @code{glEnable} and @code{glDisable} with
7072 argument @code{GL_FOG}.
7074 @code{glFog} assigns the value or values in @var{params} to the fog
7075 parameter specified by @var{pname}. The following values are accepted
7079 @item @code{GL_FOG_MODE}
7080 @var{params} is a single integer or floating-point value that specifies
7081 the equation to be used to compute the fog blend factor, @r{@var{f}}.
7082 Three symbolic constants are accepted: @code{GL_LINEAR}, @code{GL_EXP},
7083 and @code{GL_EXP2}. The equations corresponding to these symbolic
7084 constants are defined below. The initial fog mode is @code{GL_EXP}.
7086 @item @code{GL_FOG_DENSITY}
7087 @var{params} is a single integer or floating-point value that specifies
7088 @r{@var{density}}, the fog density used in both exponential fog
7089 equations. Only nonnegative densities are accepted. The initial fog
7092 @item @code{GL_FOG_START}
7093 @var{params} is a single integer or floating-point value that specifies
7094 @r{@var{start}}, the near distance used in the linear fog equation. The
7095 initial near distance is 0.
7097 @item @code{GL_FOG_END}
7098 @var{params} is a single integer or floating-point value that specifies
7099 @r{@var{end}}, the far distance used in the linear fog equation. The
7100 initial far distance is 1.
7102 @item @code{GL_FOG_INDEX}
7103 @var{params} is a single integer or floating-point value that specifies
7104 @r{@var{i}_@var{f}}, the fog color index. The initial fog index is 0.
7106 @item @code{GL_FOG_COLOR}
7107 @var{params} contains four integer or floating-point values that specify
7108 @r{@var{C}_@var{f}}, the fog color. Integer values are mapped linearly
7109 such that the most positive representable value maps to 1.0, and the
7110 most negative representable value maps to @r{-1.0}. Floating-point
7111 values are mapped directly. After conversion, all color components are
7112 clamped to the range @r{[0,1]}. The initial fog color is (0, 0, 0, 0).
7114 @item @code{GL_FOG_COORD_SRC}
7115 @var{params} contains either of the following symbolic constants:
7116 @code{GL_FOG_COORD} or @code{GL_FRAGMENT_DEPTH}. @code{GL_FOG_COORD}
7117 specifies that the current fog coordinate should be used as distance
7118 value in the fog color computation. @code{GL_FRAGMENT_DEPTH} specifies
7119 that the current fragment depth should be used as distance value in the
7124 Fog blends a fog color with each rasterized pixel fragment's
7125 post-texturing color using a blending factor @r{@var{f}}. Factor
7126 @r{@var{f}} is computed in one of three ways, depending on the fog mode.
7127 Let @r{@var{c}} be either the distance in eye coordinate from the origin
7128 (in the case that the @code{GL_FOG_COORD_SRC} is
7129 @code{GL_FRAGMENT_DEPTH}) or the current fog coordinate (in the case
7130 that @code{GL_FOG_COORD_SRC} is @code{GL_FOG_COORD}). The equation for
7131 @code{GL_LINEAR} fog is
7132 @r{@var{f}=@var{end}-@var{c},/@var{end}-@var{start},}
7134 The equation for @code{GL_EXP} fog is
7135 @r{@var{f}=@var{e}^-(@var{density}·@var{c},),}
7137 The equation for @code{GL_EXP2} fog is
7138 @r{@var{f}=@var{e}^-(@var{density}·@var{c},),^2}
7140 Regardless of the fog mode, @r{@var{f}} is clamped to the range
7141 @r{[0,1]} after it is computed. Then, if the GL is in RGBA color mode,
7142 the fragment's red, green, and blue colors, represented by
7143 @r{@var{C}_@var{r}}, are replaced by
7145 @r{@var{C}_@var{r},^″=@var{f}×@var{C}_@var{r}+(1-@var{f},)×@var{C}_@var{f}}
7147 Fog does not affect a fragment's alpha component.
7149 In color index mode, the fragment's color index @r{@var{i}_@var{r}} is
7152 @r{@var{i}_@var{r},^″=@var{i}_@var{r}+(1-@var{f},)×@var{i}_@var{f}}
7156 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
7157 value, or if @var{pname} is @code{GL_FOG_MODE} and @var{params} is not
7160 @code{GL_INVALID_VALUE} is generated if @var{pname} is
7161 @code{GL_FOG_DENSITY} and @var{params} is negative.
7163 @code{GL_INVALID_OPERATION} is generated if @code{glFog} is executed
7164 between the execution of @code{glBegin} and the corresponding execution
7169 @deftypefun void glFrontFace mode
7170 Define front- and back-facing polygons.
7174 Specifies the orientation of front-facing polygons. @code{GL_CW} and
7175 @code{GL_CCW} are accepted. The initial value is @code{GL_CCW}.
7179 In a scene composed entirely of opaque closed surfaces, back-facing
7180 polygons are never visible. Eliminating these invisible polygons has the
7181 obvious benefit of speeding up the rendering of the image. To enable and
7182 disable elimination of back-facing polygons, call @code{glEnable} and
7183 @code{glDisable} with argument @code{GL_CULL_FACE}.
7185 The projection of a polygon to window coordinates is said to have
7186 clockwise winding if an imaginary object following the path from its
7187 first vertex, its second vertex, and so on, to its last vertex, and
7188 finally back to its first vertex, moves in a clockwise direction about
7189 the interior of the polygon. The polygon's winding is said to be
7190 counterclockwise if the imaginary object following the same path moves
7191 in a counterclockwise direction about the interior of the polygon.
7192 @code{glFrontFace} specifies whether polygons with clockwise winding in
7193 window coordinates, or counterclockwise winding in window coordinates,
7194 are taken to be front-facing. Passing @code{GL_CCW} to @var{mode}
7195 selects counterclockwise polygons as front-facing; @code{GL_CW} selects
7196 clockwise polygons as front-facing. By default, counterclockwise
7197 polygons are taken to be front-facing.
7199 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
7202 @code{GL_INVALID_OPERATION} is generated if @code{glFrontFace} is
7203 executed between the execution of @code{glBegin} and the corresponding
7204 execution of @code{glEnd}.
7208 @deftypefun void glFrustum left right bottom top nearVal farVal
7209 Multiply the current matrix by a perspective matrix.
7214 Specify the coordinates for the left and right vertical clipping planes.
7218 Specify the coordinates for the bottom and top horizontal clipping
7223 Specify the distances to the near and far depth clipping planes. Both
7224 distances must be positive.
7228 @code{glFrustum} describes a perspective matrix that produces a
7229 perspective projection. The current matrix (see @code{glMatrixMode}) is
7230 multiplied by this matrix and the result replaces the current matrix, as
7231 if @code{glMultMatrix} were called with the following matrix as its
7236 @r{[(2@var{nearVal},/@var{right}-@var{left},, 0 @var{A} 0), (0
7237 2@var{nearVal},/@var{top}-@var{bottom},, @var{B} 0), (0 0 @var{C}
7238 @var{D}), (0 0 -1 0),]}
7240 @r{@var{A}=@var{right}+@var{left},/@var{right}-@var{left},}
7242 @r{@var{B}=@var{top}+@var{bottom},/@var{top}-@var{bottom},}
7244 @r{@var{C}=-@var{farVal}+@var{nearVal},/@var{farVal}-@var{nearVal},,}
7246 @r{@var{D}=-2@var{farVal}@var{nearVal},/@var{farVal}-@var{nearVal},,}
7250 Typically, the matrix mode is @code{GL_PROJECTION}, and
7251 @r{(@var{left},@var{bottom}-@var{nearVal})} and
7252 @r{(@var{right},@var{top}-@var{nearVal})} specify the points on the near
7253 clipping plane that are mapped to the lower left and upper right corners
7254 of the window, assuming that the eye is located at (0, 0, 0).
7255 @r{-@var{farVal}} specifies the location of the far clipping plane. Both
7256 @var{nearVal} and @var{farVal} must be positive.
7258 Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the
7259 current matrix stack.
7261 @code{GL_INVALID_VALUE} is generated if @var{nearVal} or @var{farVal} is
7262 not positive, or if @var{left} = @var{right}, or @var{bottom} =
7263 @var{top}, or @var{near} = @var{far}.
7265 @code{GL_INVALID_OPERATION} is generated if @code{glFrustum} is executed
7266 between the execution of @code{glBegin} and the corresponding execution
7271 @deftypefun void glGenBuffers n buffers
7272 Generate buffer object names.
7276 Specifies the number of buffer object names to be generated.
7279 Specifies an array in which the generated buffer object names are
7284 @code{glGenBuffers} returns @var{n} buffer object names in
7285 @var{buffers}. There is no guarantee that the names form a contiguous
7286 set of integers; however, it is guaranteed that none of the returned
7287 names was in use immediately before the call to @code{glGenBuffers}.
7289 Buffer object names returned by a call to @code{glGenBuffers} are not
7290 returned by subsequent calls, unless they are first deleted with
7291 @code{glDeleteBuffers}.
7293 No buffer objects are associated with the returned buffer object names
7294 until they are first bound by calling @code{glBindBuffer}.
7296 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
7298 @code{GL_INVALID_OPERATION} is generated if @code{glGenBuffers} is
7299 executed between the execution of @code{glBegin} and the corresponding
7300 execution of @code{glEnd}.
7304 @deftypefun GLuint glGenLists range
7305 Generate a contiguous set of empty display lists.
7309 Specifies the number of contiguous empty display lists to be generated.
7313 @code{glGenLists} has one argument, @var{range}. It returns an integer
7314 @var{n} such that @var{range} contiguous empty display lists, named
7315 @r{@var{n}}, @r{@var{n}+1}, @r{@var{...}}, @r{@var{n}+@var{range}-1},
7316 are created. If @var{range} is 0, if there is no group of @var{range}
7317 contiguous names available, or if any error is generated, no display
7318 lists are generated, and 0 is returned.
7320 @code{GL_INVALID_VALUE} is generated if @var{range} is negative.
7322 @code{GL_INVALID_OPERATION} is generated if @code{glGenLists} is
7323 executed between the execution of @code{glBegin} and the corresponding
7324 execution of @code{glEnd}.
7328 @deftypefun void glGenQueries n ids
7329 Generate query object names.
7333 Specifies the number of query object names to be generated.
7336 Specifies an array in which the generated query object names are stored.
7340 @code{glGenQueries} returns @var{n} query object names in @var{ids}.
7341 There is no guarantee that the names form a contiguous set of integers;
7342 however, it is guaranteed that none of the returned names was in use
7343 immediately before the call to @code{glGenQueries}.
7345 Query object names returned by a call to @code{glGenQueries} are not
7346 returned by subsequent calls, unless they are first deleted with
7347 @code{glDeleteQueries}.
7349 No query objects are associated with the returned query object names
7350 until they are first used by calling @code{glBeginQuery}.
7352 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
7354 @code{GL_INVALID_OPERATION} is generated if @code{glGenQueries} is
7355 executed between the execution of @code{glBegin} and the corresponding
7356 execution of @code{glEnd}.
7360 @deftypefun void glGenTextures n textures
7361 Generate texture names.
7365 Specifies the number of texture names to be generated.
7367 @item @var{textures}
7368 Specifies an array in which the generated texture names are stored.
7372 @code{glGenTextures} returns @var{n} texture names in @var{textures}.
7373 There is no guarantee that the names form a contiguous set of integers;
7374 however, it is guaranteed that none of the returned names was in use
7375 immediately before the call to @code{glGenTextures}.
7377 The generated textures have no dimensionality; they assume the
7378 dimensionality of the texture target to which they are first bound (see
7379 @code{glBindTexture}).
7381 Texture names returned by a call to @code{glGenTextures} are not
7382 returned by subsequent calls, unless they are first deleted with
7383 @code{glDeleteTextures}.
7385 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
7387 @code{GL_INVALID_OPERATION} is generated if @code{glGenTextures} is
7388 executed between the execution of @code{glBegin} and the corresponding
7389 execution of @code{glEnd}.
7393 @deftypefun void glGetActiveAttrib program index bufSize length size type name
7394 Returns information about an active attribute variable for the specified
7399 Specifies the program object to be queried.
7402 Specifies the index of the attribute variable to be queried.
7405 Specifies the maximum number of characters OpenGL is allowed to write in
7406 the character buffer indicated by @var{name}.
7409 Returns the number of characters actually written by OpenGL in the
7410 string indicated by @var{name} (excluding the null terminator) if a
7411 value other than @code{NULL} is passed.
7414 Returns the size of the attribute variable.
7417 Returns the data type of the attribute variable.
7420 Returns a null terminated string containing the name of the attribute
7425 @code{glGetActiveAttrib} returns information about an active attribute
7426 variable in the program object specified by @var{program}. The number of
7427 active attributes can be obtained by calling @code{glGetProgram} with
7428 the value @code{GL_ACTIVE_ATTRIBUTES}. A value of 0 for @var{index}
7429 selects the first active attribute variable. Permissible values for
7430 @var{index} range from 0 to the number of active attribute variables
7433 A vertex shader may use either built-in attribute variables,
7434 user-defined attribute variables, or both. Built-in attribute variables
7435 have a prefix of "gl_" and reference conventional OpenGL vertex
7436 attribtes (e.g., @var{gl_Vertex}, @var{gl_Normal}, etc., see the OpenGL
7437 Shading Language specification for a complete list.) User-defined
7438 attribute variables have arbitrary names and obtain their values through
7439 numbered generic vertex attributes. An attribute variable (either
7440 built-in or user-defined) is considered active if it is determined
7441 during the link operation that it may be accessed during program
7442 execution. Therefore, @var{program} should have previously been the
7443 target of a call to @code{glLinkProgram}, but it is not necessary for it
7444 to have been linked successfully.
7446 The size of the character buffer required to store the longest attribute
7447 variable name in @var{program} can be obtained by calling
7448 @code{glGetProgram} with the value
7449 @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH}. This value should be used to
7450 allocate a buffer of sufficient size to store the returned attribute
7451 name. The size of this character buffer is passed in @var{bufSize}, and
7452 a pointer to this character buffer is passed in @var{name}.
7454 @code{glGetActiveAttrib} returns the name of the attribute variable
7455 indicated by @var{index}, storing it in the character buffer specified
7456 by @var{name}. The string returned will be null terminated. The actual
7457 number of characters written into this buffer is returned in
7458 @var{length}, and this count does not include the null termination
7459 character. If the length of the returned string is not required, a value
7460 of @code{NULL} can be passed in the @var{length} argument.
7462 The @var{type} argument will return a pointer to the attribute
7463 variable's data type. The symbolic constants @code{GL_FLOAT},
7464 @code{GL_FLOAT_VEC2}, @code{GL_FLOAT_VEC3}, @code{GL_FLOAT_VEC4},
7465 @code{GL_FLOAT_MAT2}, @code{GL_FLOAT_MAT3}, @code{GL_FLOAT_MAT4},
7466 @code{GL_FLOAT_MAT2x3}, @code{GL_FLOAT_MAT2x4}, @code{GL_FLOAT_MAT3x2},
7467 @code{GL_FLOAT_MAT3x4}, @code{GL_FLOAT_MAT4x2}, or
7468 @code{GL_FLOAT_MAT4x3} may be returned. The @var{size} argument will
7469 return the size of the attribute, in units of the type returned in
7472 The list of active attribute variables may include both built-in
7473 attribute variables (which begin with the prefix "gl_") as well as
7474 user-defined attribute variable names.
7476 This function will return as much information as it can about the
7477 specified active attribute variable. If no information is available,
7478 @var{length} will be 0, and @var{name} will be an empty string. This
7479 situation could occur if this function is called after a link operation
7480 that failed. If an error occurs, the return values @var{length},
7481 @var{size}, @var{type}, and @var{name} will be unmodified.
7483 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
7484 generated by OpenGL.
7486 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
7489 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
7490 equal to the number of active attribute variables in @var{program}.
7492 @code{GL_INVALID_OPERATION} is generated if @code{glGetActiveAttrib} is
7493 executed between the execution of @code{glBegin} and the corresponding
7494 execution of @code{glEnd}.
7496 @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0.
7500 @deftypefun void glGetActiveUniform program index bufSize length size type name
7501 Returns information about an active uniform variable for the specified
7506 Specifies the program object to be queried.
7509 Specifies the index of the uniform variable to be queried.
7512 Specifies the maximum number of characters OpenGL is allowed to write in
7513 the character buffer indicated by @var{name}.
7516 Returns the number of characters actually written by OpenGL in the
7517 string indicated by @var{name} (excluding the null terminator) if a
7518 value other than @code{NULL} is passed.
7521 Returns the size of the uniform variable.
7524 Returns the data type of the uniform variable.
7527 Returns a null terminated string containing the name of the uniform
7532 @code{glGetActiveUniform} returns information about an active uniform
7533 variable in the program object specified by @var{program}. The number of
7534 active uniform variables can be obtained by calling @code{glGetProgram}
7535 with the value @code{GL_ACTIVE_UNIFORMS}. A value of 0 for @var{index}
7536 selects the first active uniform variable. Permissible values for
7537 @var{index} range from 0 to the number of active uniform variables minus
7540 Shaders may use either built-in uniform variables, user-defined uniform
7541 variables, or both. Built-in uniform variables have a prefix of "gl_"
7542 and reference existing OpenGL state or values derived from such state
7543 (e.g., @var{gl_Fog}, @var{gl_ModelViewMatrix}, etc., see the OpenGL
7544 Shading Language specification for a complete list.) User-defined
7545 uniform variables have arbitrary names and obtain their values from the
7546 application through calls to @code{glUniform}. A uniform variable
7547 (either built-in or user-defined) is considered active if it is
7548 determined during the link operation that it may be accessed during
7549 program execution. Therefore, @var{program} should have previously been
7550 the target of a call to @code{glLinkProgram}, but it is not necessary
7551 for it to have been linked successfully.
7553 The size of the character buffer required to store the longest uniform
7554 variable name in @var{program} can be obtained by calling
7555 @code{glGetProgram} with the value @code{GL_ACTIVE_UNIFORM_MAX_LENGTH}.
7556 This value should be used to allocate a buffer of sufficient size to
7557 store the returned uniform variable name. The size of this character
7558 buffer is passed in @var{bufSize}, and a pointer to this character
7559 buffer is passed in @var{name.}
7561 @code{glGetActiveUniform} returns the name of the uniform variable
7562 indicated by @var{index}, storing it in the character buffer specified
7563 by @var{name}. The string returned will be null terminated. The actual
7564 number of characters written into this buffer is returned in
7565 @var{length}, and this count does not include the null termination
7566 character. If the length of the returned string is not required, a value
7567 of @code{NULL} can be passed in the @var{length} argument.
7569 The @var{type} argument will return a pointer to the uniform variable's
7570 data type. The symbolic constants @code{GL_FLOAT}, @code{GL_FLOAT_VEC2},
7571 @code{GL_FLOAT_VEC3}, @code{GL_FLOAT_VEC4}, @code{GL_INT},
7572 @code{GL_INT_VEC2}, @code{GL_INT_VEC3}, @code{GL_INT_VEC4},
7573 @code{GL_BOOL}, @code{GL_BOOL_VEC2}, @code{GL_BOOL_VEC3},
7574 @code{GL_BOOL_VEC4}, @code{GL_FLOAT_MAT2}, @code{GL_FLOAT_MAT3},
7575 @code{GL_FLOAT_MAT4}, @code{GL_FLOAT_MAT2x3}, @code{GL_FLOAT_MAT2x4},
7576 @code{GL_FLOAT_MAT3x2}, @code{GL_FLOAT_MAT3x4}, @code{GL_FLOAT_MAT4x2},
7577 @code{GL_FLOAT_MAT4x3}, @code{GL_SAMPLER_1D}, @code{GL_SAMPLER_2D},
7578 @code{GL_SAMPLER_3D}, @code{GL_SAMPLER_CUBE},
7579 @code{GL_SAMPLER_1D_SHADOW}, or @code{GL_SAMPLER_2D_SHADOW} may be
7582 If one or more elements of an array are active, the name of the array is
7583 returned in @var{name}, the type is returned in @var{type}, and the
7584 @var{size} parameter returns the highest array element index used, plus
7585 one, as determined by the compiler and/or linker. Only one active
7586 uniform variable will be reported for a uniform array.
7588 Uniform variables that are declared as structures or arrays of
7589 structures will not be returned directly by this function. Instead, each
7590 of these uniform variables will be reduced to its fundamental components
7591 containing the "." and "[]" operators such that each of the names is
7592 valid as an argument to @code{glGetUniformLocation}. Each of these
7593 reduced uniform variables is counted as one active uniform variable and
7594 is assigned an index. A valid name cannot be a structure, an array of
7595 structures, or a subcomponent of a vector or matrix.
7597 The size of the uniform variable will be returned in @var{size}. Uniform
7598 variables other than arrays will have a size of 1. Structures and arrays
7599 of structures will be reduced as described earlier, such that each of
7600 the names returned will be a data type in the earlier list. If this
7601 reduction results in an array, the size returned will be as described
7602 for uniform arrays; otherwise, the size returned will be 1.
7604 The list of active uniform variables may include both built-in uniform
7605 variables (which begin with the prefix "gl_") as well as user-defined
7606 uniform variable names.
7608 This function will return as much information as it can about the
7609 specified active uniform variable. If no information is available,
7610 @var{length} will be 0, and @var{name} will be an empty string. This
7611 situation could occur if this function is called after a link operation
7612 that failed. If an error occurs, the return values @var{length},
7613 @var{size}, @var{type}, and @var{name} will be unmodified.
7615 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
7616 generated by OpenGL.
7618 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
7621 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
7622 equal to the number of active uniform variables in @var{program}.
7624 @code{GL_INVALID_OPERATION} is generated if @code{glGetActiveUniform} is
7625 executed between the execution of @code{glBegin} and the corresponding
7626 execution of @code{glEnd}.
7628 @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0.
7632 @deftypefun void glGetAttachedShaders program maxCount count shaders
7633 Returns the handles of the shader objects attached to a program object.
7637 Specifies the program object to be queried.
7639 @item @var{maxCount}
7640 Specifies the size of the array for storing the returned object names.
7643 Returns the number of names actually returned in @var{objects}.
7646 Specifies an array that is used to return the names of attached shader
7651 @code{glGetAttachedShaders} returns the names of the shader objects
7652 attached to @var{program}. The names of shader objects that are attached
7653 to @var{program} will be returned in @var{shaders.} The actual number of
7654 shader names written into @var{shaders} is returned in @var{count.} If
7655 no shader objects are attached to @var{program}, @var{count} is set to
7656 0. The maximum number of shader names that may be returned in
7657 @var{shaders} is specified by @var{maxCount}.
7659 If the number of names actually returned is not required (for instance,
7660 if it has just been obtained by calling @code{glGetProgram}), a value of
7661 @code{NULL} may be passed for count. If no shader objects are attached
7662 to @var{program}, a value of 0 will be returned in @var{count}. The
7663 actual number of attached shaders can be obtained by calling
7664 @code{glGetProgram} with the value @code{GL_ATTACHED_SHADERS}.
7666 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
7667 generated by OpenGL.
7669 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
7672 @code{GL_INVALID_VALUE} is generated if @var{maxCount} is less than 0.
7674 @code{GL_INVALID_OPERATION} is generated if @code{glGetAttachedShaders}
7675 is executed between the execution of @code{glBegin} and the
7676 corresponding execution of @code{glEnd}.
7680 @deftypefun GLint glGetAttribLocation program name
7681 Returns the location of an attribute variable.
7685 Specifies the program object to be queried.
7688 Points to a null terminated string containing the name of the attribute
7689 variable whose location is to be queried.
7693 @code{glGetAttribLocation} queries the previously linked program object
7694 specified by @var{program} for the attribute variable specified by
7695 @var{name} and returns the index of the generic vertex attribute that is
7696 bound to that attribute variable. If @var{name} is a matrix attribute
7697 variable, the index of the first column of the matrix is returned. If
7698 the named attribute variable is not an active attribute in the specified
7699 program object or if @var{name} starts with the reserved prefix "gl_", a
7700 value of -1 is returned.
7702 The association between an attribute variable name and a generic
7703 attribute index can be specified at any time by calling
7704 @code{glBindAttribLocation}. Attribute bindings do not go into effect
7705 until @code{glLinkProgram} is called. After a program object has been
7706 linked successfully, the index values for attribute variables remain
7707 fixed until the next link command occurs. The attribute values can only
7708 be queried after a link if the link was successful.
7709 @code{glGetAttribLocation} returns the binding that actually went into
7710 effect the last time @code{glLinkProgram} was called for the specified
7711 program object. Attribute bindings that have been specified since the
7712 last link operation are not returned by @code{glGetAttribLocation}.
7714 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a value
7715 generated by OpenGL.
7717 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
7720 @code{GL_INVALID_OPERATION} is generated if @var{program} has not been
7721 successfully linked.
7723 @code{GL_INVALID_OPERATION} is generated if @code{glGetAttribLocation}
7724 is executed between the execution of @code{glBegin} and the
7725 corresponding execution of @code{glEnd}.
7729 @deftypefun void glGetBufferSubData target offset size data
7730 Returns a subset of a buffer object's data store.
7734 Specifies the target buffer object. The symbolic constant must be
7735 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
7736 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
7739 Specifies the offset into the buffer object's data store from which data
7740 will be returned, measured in bytes.
7743 Specifies the size in bytes of the data store region being returned.
7746 Specifies a pointer to the location where buffer object data is
7751 @code{glGetBufferSubData} returns some or all of the data from the
7752 buffer object currently bound to @var{target}. Data starting at byte
7753 offset @var{offset} and extending for @var{size} bytes is copied from
7754 the data store to the memory pointed to by @var{data}. An error is
7755 thrown if the buffer object is currently mapped, or if @var{offset} and
7756 @var{size} together define a range beyond the bounds of the buffer
7757 object's data store.
7759 @code{GL_INVALID_ENUM} is generated if @var{target} is not
7760 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
7761 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
7763 @code{GL_INVALID_VALUE} is generated if @var{offset} or @var{size} is
7764 negative, or if together they define a region of memory that extends
7765 beyond the buffer object's allocated data store.
7767 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
7768 name 0 is bound to @var{target}.
7770 @code{GL_INVALID_OPERATION} is generated if the buffer object being
7773 @code{GL_INVALID_OPERATION} is generated if @code{glGetBufferSubData} is
7774 executed between the execution of @code{glBegin} and the corresponding
7775 execution of @code{glEnd}.
7779 @deftypefun void glGetClipPlane plane equation
7780 Return the coefficients of the specified clipping plane.
7784 Specifies a clipping plane. The number of clipping planes depends on the
7785 implementation, but at least six clipping planes are supported. They are
7786 identified by symbolic names of the form @code{GL_CLIP_PLANE}@r{@var{i}}
7787 where i ranges from 0 to the value of @code{GL_MAX_CLIP_PLANES} - 1.
7789 @item @var{equation}
7790 Returns four double-precision values that are the coefficients of the
7791 plane equation of @var{plane} in eye coordinates. The initial value is
7796 @code{glGetClipPlane} returns in @var{equation} the four coefficients of
7797 the plane equation for @var{plane}.
7799 @code{GL_INVALID_ENUM} is generated if @var{plane} is not an accepted
7802 @code{GL_INVALID_OPERATION} is generated if @code{glGetClipPlane} is
7803 executed between the execution of @code{glBegin} and the corresponding
7804 execution of @code{glEnd}.
7808 @deftypefun void glGetColorTable target format type table
7809 Retrieve contents of a color lookup table.
7813 Must be @code{GL_COLOR_TABLE}, @code{GL_POST_CONVOLUTION_COLOR_TABLE},
7814 or @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}.
7817 The format of the pixel data in @var{table}. The possible values are
7818 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
7819 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB},
7820 @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}.
7823 The type of the pixel data in @var{table}. Symbolic constants
7824 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
7825 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
7826 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
7827 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
7828 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
7829 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
7830 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
7831 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
7832 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
7835 Pointer to a one-dimensional array of pixel data containing the contents
7840 @code{glGetColorTable} returns in @var{table} the contents of the color
7841 table specified by @var{target}. No pixel transfer operations are
7842 performed, but pixel storage modes that are applicable to
7843 @code{glReadPixels} are performed.
7845 If a non-zero named buffer object is bound to the
7846 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
7847 histogram table is requested, @var{table} is treated as a byte offset
7848 into the buffer object's data store.
7850 Color components that are requested in the specified @var{format}, but
7851 which are not included in the internal format of the color lookup table,
7852 are returned as zero. The assignments of internal color components to
7853 the components requested by @var{format} are
7856 @item @strong{Internal Component}
7857 @strong{Resulting Component}
7887 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
7890 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
7893 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
7896 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
7897 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
7898 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
7899 and @var{format} is not @code{GL_RGB}.
7901 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
7902 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
7903 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
7904 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
7905 @code{GL_UNSIGNED_INT_10_10_10_2}, or
7906 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
7907 @code{GL_RGBA} nor @code{GL_BGRA}.
7909 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
7910 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
7911 object's data store is currently mapped.
7913 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
7914 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
7915 would be packed to the buffer object such that the memory writes
7916 required would exceed the data store size.
7918 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
7919 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{table}
7920 is not evenly divisible into the number of bytes needed to store in
7921 memory a datum indicated by @var{type}.
7923 @code{GL_INVALID_OPERATION} is generated if @code{glGetColorTable} is
7924 executed between the execution of @code{glBegin} and the corresponding
7925 execution of @code{glEnd}.
7929 @deftypefun void glGetCompressedTexImage target lod img
7930 Return a compressed texture image.
7934 Specifies which texture is to be obtained. @code{GL_TEXTURE_1D},
7935 @code{GL_TEXTURE_2D}, and
7936 @code{GL_TEXTURE_3D}@code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
7937 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
7938 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
7939 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
7940 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, and
7941 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z} are accepted.
7944 Specifies the level-of-detail number of the desired image. Level 0 is
7945 the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap
7949 Returns the compressed texture image.
7953 @code{glGetCompressedTexImage} returns the compressed texture image
7954 associated with @var{target} and @var{lod} into @var{img}. @var{img}
7955 should be an array of @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} bytes.
7956 @var{target} specifies whether the desired texture image was one
7957 specified by @code{glTexImage1D} (@code{GL_TEXTURE_1D}),
7958 @code{glTexImage2D} (@code{GL_TEXTURE_2D} or any of
7959 @code{GL_TEXTURE_CUBE_MAP_*}), or @code{glTexImage3D}
7960 (@code{GL_TEXTURE_3D}). @var{lod} specifies the level-of-detail number
7961 of the desired image.
7963 If a non-zero named buffer object is bound to the
7964 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
7965 texture image is requested, @var{img} is treated as a byte offset into
7966 the buffer object's data store.
7968 To minimize errors, first verify that the texture is compressed by
7969 calling @code{glGetTexLevelParameter} with argument
7970 @code{GL_TEXTURE_COMPRESSED}. If the texture is compressed, then
7971 determine the amount of memory required to store the compressed texture
7972 by calling @code{glGetTexLevelParameter} with argument
7973 @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE}. Finally, retrieve the internal
7974 format of the texture by calling @code{glGetTexLevelParameter} with
7975 argument @code{GL_TEXTURE_INTERNAL_FORMAT}. To store the texture for
7976 later use, associate the internal format and size with the retrieved
7977 texture image. These data can be used by the respective texture or
7978 subtexture loading routine used for loading @var{target} textures.
7980 @code{GL_INVALID_VALUE} is generated if @var{lod} is less than zero or
7981 greater than the maximum number of LODs permitted by the implementation.
7983 @code{GL_INVALID_OPERATION} is generated if
7984 @code{glGetCompressedTexImage} is used to retrieve a texture that is in
7985 an uncompressed internal format.
7987 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
7988 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
7989 object's data store is currently mapped.
7991 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
7992 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
7993 would be packed to the buffer object such that the memory writes
7994 required would exceed the data store size.
7996 @code{GL_INVALID_OPERATION} is generated if
7997 @code{glGetCompressedTexImage} is executed between the execution of
7998 @code{glBegin} and the corresponding execution of @code{glEnd}.
8002 @deftypefun void glGetConvolutionFilter target format type image
8003 Get current 1D or 2D convolution filter kernel.
8007 The filter to be retrieved. Must be one of @code{GL_CONVOLUTION_1D} or
8008 @code{GL_CONVOLUTION_2D}.
8011 Format of the output image. Must be one of @code{GL_RED},
8012 @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB},
8013 @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, or
8014 @code{GL_LUMINANCE_ALPHA}.
8017 Data type of components in the output image. Symbolic constants
8018 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
8019 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
8020 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
8021 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
8022 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
8023 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
8024 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
8025 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
8026 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
8029 Pointer to storage for the output image.
8033 @code{glGetConvolutionFilter} returns the current 1D or 2D convolution
8034 filter kernel as an image. The one- or two-dimensional image is placed
8035 in @var{image} according to the specifications in @var{format} and
8036 @var{type}. No pixel transfer operations are performed on this image,
8037 but the relevant pixel storage modes are applied.
8039 If a non-zero named buffer object is bound to the
8040 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
8041 convolution filter is requested, @var{image} is treated as a byte offset
8042 into the buffer object's data store.
8044 Color components that are present in @var{format} but not included in
8045 the internal format of the filter are returned as zero. The assignments
8046 of internal color components to the components of @var{format} are as
8050 @item @strong{Internal Component}
8051 @strong{Resulting Component}
8081 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
8084 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
8087 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
8090 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8091 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
8092 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
8093 and @var{format} is not @code{GL_RGB}.
8095 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8096 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
8097 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
8098 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
8099 @code{GL_UNSIGNED_INT_10_10_10_2}, or
8100 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
8101 @code{GL_RGBA} nor @code{GL_BGRA}.
8103 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8104 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
8105 object's data store is currently mapped.
8107 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8108 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
8109 would be packed to the buffer object such that the memory writes
8110 required would exceed the data store size.
8112 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8113 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{image}
8114 is not evenly divisible into the number of bytes needed to store in
8115 memory a datum indicated by @var{type}.
8117 @code{GL_INVALID_OPERATION} is generated if
8118 @code{glGetConvolutionFilter} is executed between the execution of
8119 @code{glBegin} and the corresponding execution of @code{glEnd}.
8123 @deftypefun GLenum glGetError
8124 Return error information.
8126 @code{glGetError} returns the value of the error flag. Each detectable
8127 error is assigned a numeric code and symbolic name. When an error
8128 occurs, the error flag is set to the appropriate error code value. No
8129 other errors are recorded until @code{glGetError} is called, the error
8130 code is returned, and the flag is reset to @code{GL_NO_ERROR}. If a call
8131 to @code{glGetError} returns @code{GL_NO_ERROR}, there has been no
8132 detectable error since the last call to @code{glGetError}, or since the
8135 To allow for distributed implementations, there may be several error
8136 flags. If any single error flag has recorded an error, the value of that
8137 flag is returned and that flag is reset to @code{GL_NO_ERROR} when
8138 @code{glGetError} is called. If more than one flag has recorded an
8139 error, @code{glGetError} returns and clears an arbitrary error flag
8140 value. Thus, @code{glGetError} should always be called in a loop, until
8141 it returns @code{GL_NO_ERROR}, if all error flags are to be reset.
8143 Initially, all error flags are set to @code{GL_NO_ERROR}.
8145 The following errors are currently defined:
8148 @item @code{GL_NO_ERROR}
8149 No error has been recorded. The value of this symbolic constant is
8152 @item @code{GL_INVALID_ENUM}
8153 An unacceptable value is specified for an enumerated argument. The
8154 offending command is ignored and has no other side effect than to set
8157 @item @code{GL_INVALID_VALUE}
8158 A numeric argument is out of range. The offending command is ignored and
8159 has no other side effect than to set the error flag.
8161 @item @code{GL_INVALID_OPERATION}
8162 The specified operation is not allowed in the current state. The
8163 offending command is ignored and has no other side effect than to set
8166 @item @code{GL_STACK_OVERFLOW}
8167 This command would cause a stack overflow. The offending command is
8168 ignored and has no other side effect than to set the error flag.
8170 @item @code{GL_STACK_UNDERFLOW}
8171 This command would cause a stack underflow. The offending command is
8172 ignored and has no other side effect than to set the error flag.
8174 @item @code{GL_OUT_OF_MEMORY}
8175 There is not enough memory left to execute the command. The state of the
8176 GL is undefined, except for the state of the error flags, after this
8179 @item @code{GL_TABLE_TOO_LARGE}
8180 The specified table exceeds the implementation's maximum supported table
8181 size. The offending command is ignored and has no other side effect than
8182 to set the error flag.
8186 When an error flag is set, results of a GL operation are undefined only
8187 if @code{GL_OUT_OF_MEMORY} has occurred. In all other cases, the command
8188 generating the error is ignored and has no effect on the GL state or
8189 frame buffer contents. If the generating command returns a value, it
8190 returns 0. If @code{glGetError} itself generates an error, it returns 0.
8192 @code{GL_INVALID_OPERATION} is generated if @code{glGetError} is
8193 executed between the execution of @code{glBegin} and the corresponding
8194 execution of @code{glEnd}. In this case, @code{glGetError} returns 0.
8198 @deftypefun void glGetHistogram target reset format type values
8199 Get histogram table.
8203 Must be @code{GL_HISTOGRAM}.
8206 If @code{GL_TRUE}, each component counter that is actually returned is
8207 reset to zero. (Other counters are unaffected.) If @code{GL_FALSE}, none
8208 of the counters in the histogram table is modified.
8211 The format of values to be returned in @var{values}. Must be one of
8212 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
8213 @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA},
8214 @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}.
8217 The type of values to be returned in @var{values}. Symbolic constants
8218 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
8219 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
8220 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
8221 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
8222 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
8223 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
8224 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
8225 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
8226 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
8229 A pointer to storage for the returned histogram table.
8233 @code{glGetHistogram} returns the current histogram table as a
8234 one-dimensional image with the same width as the histogram. No pixel
8235 transfer operations are performed on this image, but pixel storage modes
8236 that are applicable to 1D images are honored.
8238 If a non-zero named buffer object is bound to the
8239 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
8240 histogram table is requested, @var{values} is treated as a byte offset
8241 into the buffer object's data store.
8243 Color components that are requested in the specified @var{format}, but
8244 which are not included in the internal format of the histogram, are
8245 returned as zero. The assignments of internal color components to the
8246 components requested by @var{format} are:
8249 @item @strong{Internal Component}
8250 @strong{Resulting Component}
8276 @code{GL_INVALID_ENUM} is generated if @var{target} is not
8277 @code{GL_HISTOGRAM}.
8279 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
8282 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
8285 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8286 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
8287 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
8288 and @var{format} is not @code{GL_RGB}.
8290 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8291 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
8292 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
8293 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
8294 @code{GL_UNSIGNED_INT_10_10_10_2}, or
8295 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
8296 @code{GL_RGBA} nor @code{GL_BGRA}.
8298 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8299 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
8300 object's data store is currently mapped.
8302 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8303 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
8304 would be packed to the buffer object such that the memory writes
8305 required would exceed the data store size.
8307 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8308 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{values}
8309 is not evenly divisible into the number of bytes needed to store in
8310 memory a datum indicated by @var{type}.
8312 @code{GL_INVALID_OPERATION} is generated if @code{glGetHistogram} is
8313 executed between the execution of @code{glBegin} and the corresponding
8314 execution of @code{glEnd}.
8318 @deftypefun void glGetMinmax target reset format types values
8319 Get minimum and maximum pixel values.
8323 Must be @code{GL_MINMAX}.
8326 If @code{GL_TRUE}, all entries in the minmax table that are actually
8327 returned are reset to their initial values. (Other entries are
8328 unaltered.) If @code{GL_FALSE}, the minmax table is unaltered.
8331 The format of the data to be returned in @var{values}. Must be one of
8332 @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
8333 @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA},
8334 @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}.
8337 The type of the data to be returned in @var{values}. Symbolic constants
8338 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
8339 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
8340 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
8341 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
8342 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
8343 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
8344 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
8345 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
8346 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
8349 A pointer to storage for the returned values.
8353 @code{glGetMinmax} returns the accumulated minimum and maximum pixel
8354 values (computed on a per-component basis) in a one-dimensional image of
8355 width 2. The first set of return values are the minima, and the second
8356 set of return values are the maxima. The format of the return values is
8357 determined by @var{format}, and their type is determined by @var{types}.
8359 If a non-zero named buffer object is bound to the
8360 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while
8361 minimum and maximum pixel values are requested, @var{values} is treated
8362 as a byte offset into the buffer object's data store.
8364 No pixel transfer operations are performed on the return values, but
8365 pixel storage modes that are applicable to one-dimensional images are
8366 performed. Color components that are requested in the specified
8367 @var{format}, but that are not included in the internal format of the
8368 minmax table, are returned as zero. The assignment of internal color
8369 components to the components requested by @var{format} are as follows:
8374 @item @strong{Internal Component}
8375 @strong{Resulting Component}
8399 If @var{reset} is @code{GL_TRUE}, the minmax table entries corresponding
8400 to the return values are reset to their initial values. Minimum and
8401 maximum values that are not returned are not modified, even if
8402 @var{reset} is @code{GL_TRUE}.
8404 @code{GL_INVALID_ENUM} is generated if @var{target} is not
8407 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
8410 @code{GL_INVALID_ENUM} is generated if @var{types} is not one of the
8413 @code{GL_INVALID_OPERATION} is generated if @var{types} is one of
8414 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
8415 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
8416 and @var{format} is not @code{GL_RGB}.
8418 @code{GL_INVALID_OPERATION} is generated if @var{types} is one of
8419 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
8420 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
8421 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
8422 @code{GL_UNSIGNED_INT_10_10_10_2}, or
8423 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
8424 @code{GL_RGBA} nor @code{GL_BGRA}.
8426 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8427 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
8428 object's data store is currently mapped.
8430 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8431 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
8432 would be packed to the buffer object such that the memory writes
8433 required would exceed the data store size.
8435 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8436 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{values}
8437 is not evenly divisible into the number of bytes needed to store in
8438 memory a datum indicated by @var{type}.
8440 @code{GL_INVALID_OPERATION} is generated if @code{glGetMinmax} is
8441 executed between the execution of @code{glBegin} and the corresponding
8442 execution of @code{glEnd}.
8446 @deftypefun void glGetPolygonStipple pattern
8447 Return the polygon stipple pattern.
8451 Returns the stipple pattern. The initial value is all 1's.
8455 @code{glGetPolygonStipple} returns to @var{pattern} a @r{32×32} polygon
8456 stipple pattern. The pattern is packed into memory as if
8457 @code{glReadPixels} with both @var{height} and @var{width} of 32,
8458 @var{type} of @code{GL_BITMAP}, and @var{format} of
8459 @code{GL_COLOR_INDEX} were called, and the stipple pattern were stored
8460 in an internal @r{32×32} color index buffer. Unlike @code{glReadPixels},
8461 however, pixel transfer operations (shift, offset, pixel map) are not
8462 applied to the returned stipple image.
8464 If a non-zero named buffer object is bound to the
8465 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
8466 polygon stipple pattern is requested, @var{pattern} is treated as a byte
8467 offset into the buffer object's data store.
8469 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8470 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
8471 object's data store is currently mapped.
8473 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8474 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
8475 would be packed to the buffer object such that the memory writes
8476 required would exceed the data store size.
8478 @code{GL_INVALID_OPERATION} is generated if @code{glGetPolygonStipple}
8479 is executed between the execution of @code{glBegin} and the
8480 corresponding execution of @code{glEnd}.
8484 @deftypefun void glGetProgramInfoLog program maxLength length infoLog
8485 Returns the information log for a program object.
8489 Specifies the program object whose information log is to be queried.
8491 @item @var{maxLength}
8492 Specifies the size of the character buffer for storing the returned
8496 Returns the length of the string returned in @var{infoLog} (excluding
8497 the null terminator).
8500 Specifies an array of characters that is used to return the information
8505 @code{glGetProgramInfoLog} returns the information log for the specified
8506 program object. The information log for a program object is modified
8507 when the program object is linked or validated. The string that is
8508 returned will be null terminated.
8510 @code{glGetProgramInfoLog} returns in @var{infoLog} as much of the
8511 information log as it can, up to a maximum of @var{maxLength}
8512 characters. The number of characters actually returned, excluding the
8513 null termination character, is specified by @var{length}. If the length
8514 of the returned string is not required, a value of @code{NULL} can be
8515 passed in the @var{length} argument. The size of the buffer required to
8516 store the returned information log can be obtained by calling
8517 @code{glGetProgram} with the value @code{GL_INFO_LOG_LENGTH}.
8519 The information log for a program object is either an empty string, or a
8520 string containing information about the last link operation, or a string
8521 containing information about the last validation operation. It may
8522 contain diagnostic messages, warning messages, and other information.
8523 When a program object is created, its information log will be a string
8526 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
8527 generated by OpenGL.
8529 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
8532 @code{GL_INVALID_VALUE} is generated if @var{maxLength} is less than 0.
8534 @code{GL_INVALID_OPERATION} is generated if @code{glGetProgramInfoLog}
8535 is executed between the execution of @code{glBegin} and the
8536 corresponding execution of @code{glEnd}.
8540 @deftypefun void glGetSeparableFilter target format type row column span
8541 Get separable convolution filter kernel images.
8545 The separable filter to be retrieved. Must be @code{GL_SEPARABLE_2D}.
8548 Format of the output images. Must be one of @code{GL_RED},
8549 @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB},
8550 @code{GL_BGR}@code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, or
8551 @code{GL_LUMINANCE_ALPHA}.
8554 Data type of components in the output images. Symbolic constants
8555 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
8556 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
8557 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
8558 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
8559 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
8560 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
8561 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
8562 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
8563 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
8566 Pointer to storage for the row filter image.
8569 Pointer to storage for the column filter image.
8572 Pointer to storage for the span filter image (currently unused).
8576 @code{glGetSeparableFilter} returns the two one-dimensional filter
8577 kernel images for the current separable 2D convolution filter. The row
8578 image is placed in @var{row} and the column image is placed in
8579 @var{column} according to the specifications in @var{format} and
8580 @var{type}. (In the current implementation, @var{span} is not affected
8581 in any way.) No pixel transfer operations are performed on the images,
8582 but the relevant pixel storage modes are applied.
8584 If a non-zero named buffer object is bound to the
8585 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
8586 separable convolution filter is requested, @var{row}, @var{column}, and
8587 @var{span} are treated as a byte offset into the buffer object's data
8590 Color components that are present in @var{format} but not included in
8591 the internal format of the filters are returned as zero. The assignments
8592 of internal color components to the components of @var{format} are as
8598 @item @strong{Internal Component}
8599 @strong{Resulting Component}
8629 @code{GL_INVALID_ENUM} is generated if @var{target} is not
8630 @code{GL_SEPARABLE_2D}.
8632 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
8635 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
8638 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8639 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
8640 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
8641 and @var{format} is not @code{GL_RGB}.
8643 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
8644 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
8645 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
8646 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
8647 @code{GL_UNSIGNED_INT_10_10_10_2}, or
8648 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
8649 @code{GL_RGBA} nor @code{GL_BGRA}.
8651 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8652 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
8653 object's data store is currently mapped.
8655 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8656 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
8657 would be packed to the buffer object such that the memory writes
8658 required would exceed the data store size.
8660 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8661 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{row} or
8662 @var{column} is not evenly divisible into the number of bytes needed to
8663 store in memory a datum indicated by @var{type}.
8665 @code{GL_INVALID_OPERATION} is generated if @code{glGetSeparableFilter}
8666 is executed between the execution of @code{glBegin} and the
8667 corresponding execution of @code{glEnd}.
8671 @deftypefun void glGetShaderInfoLog shader maxLength length infoLog
8672 Returns the information log for a shader object.
8676 Specifies the shader object whose information log is to be queried.
8678 @item @var{maxLength}
8679 Specifies the size of the character buffer for storing the returned
8683 Returns the length of the string returned in @var{infoLog} (excluding
8684 the null terminator).
8687 Specifies an array of characters that is used to return the information
8692 @code{glGetShaderInfoLog} returns the information log for the specified
8693 shader object. The information log for a shader object is modified when
8694 the shader is compiled. The string that is returned will be null
8697 @code{glGetShaderInfoLog} returns in @var{infoLog} as much of the
8698 information log as it can, up to a maximum of @var{maxLength}
8699 characters. The number of characters actually returned, excluding the
8700 null termination character, is specified by @var{length}. If the length
8701 of the returned string is not required, a value of @code{NULL} can be
8702 passed in the @var{length} argument. The size of the buffer required to
8703 store the returned information log can be obtained by calling
8704 @code{glGetShader} with the value @code{GL_INFO_LOG_LENGTH}.
8706 The information log for a shader object is a string that may contain
8707 diagnostic messages, warning messages, and other information about the
8708 last compile operation. When a shader object is created, its information
8709 log will be a string of length 0.
8711 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
8712 generated by OpenGL.
8714 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
8717 @code{GL_INVALID_VALUE} is generated if @var{maxLength} is less than 0.
8719 @code{GL_INVALID_OPERATION} is generated if @code{glGetShaderInfoLog} is
8720 executed between the execution of @code{glBegin} and the corresponding
8721 execution of @code{glEnd}.
8725 @deftypefun void glGetShaderSource shader bufSize length source
8726 Returns the source code string from a shader object.
8730 Specifies the shader object to be queried.
8733 Specifies the size of the character buffer for storing the returned
8737 Returns the length of the string returned in @var{source} (excluding the
8741 Specifies an array of characters that is used to return the source code
8746 @code{glGetShaderSource} returns the concatenation of the source code
8747 strings from the shader object specified by @var{shader}. The source
8748 code strings for a shader object are the result of a previous call to
8749 @code{glShaderSource}. The string returned by the function will be null
8752 @code{glGetShaderSource} returns in @var{source} as much of the source
8753 code string as it can, up to a maximum of @var{bufSize} characters. The
8754 number of characters actually returned, excluding the null termination
8755 character, is specified by @var{length}. If the length of the returned
8756 string is not required, a value of @code{NULL} can be passed in the
8757 @var{length} argument. The size of the buffer required to store the
8758 returned source code string can be obtained by calling
8759 @code{glGetShader} with the value @code{GL_SHADER_SOURCE_LENGTH}.
8761 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
8762 generated by OpenGL.
8764 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
8767 @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0.
8769 @code{GL_INVALID_OPERATION} is generated if @code{glGetShaderSource} is
8770 executed between the execution of @code{glBegin} and the corresponding
8771 execution of @code{glEnd}.
8775 @deftypefun const-GLubyte* glGetString name
8776 Return a string describing the current GL connection.
8780 Specifies a symbolic constant, one of @code{GL_VENDOR},
8781 @code{GL_RENDERER}, @code{GL_VERSION},
8782 @code{GL_SHADING_LANGUAGE_VERSION}, or @code{GL_EXTENSIONS}.
8786 @code{glGetString} returns a pointer to a static string describing some
8787 aspect of the current GL connection. @var{name} can be one of the
8791 @item @code{GL_VENDOR}
8794 Returns the company responsible for this GL implementation. This name
8795 does not change from release to release.
8797 @item @code{GL_RENDERER}
8800 Returns the name of the renderer. This name is typically specific to a
8801 particular configuration of a hardware platform. It does not change from
8804 @item @code{GL_VERSION}
8807 Returns a version or release number.
8809 @item @code{GL_SHADING_LANGUAGE_VERSION}
8812 Returns a version or release number for the shading language.
8814 @item @code{GL_EXTENSIONS}
8817 Returns a space-separated list of supported extensions to GL.
8821 Because the GL does not include queries for the performance
8822 characteristics of an implementation, some applications are written to
8823 recognize known platforms and modify their GL usage based on known
8824 performance characteristics of these platforms. Strings @code{GL_VENDOR}
8825 and @code{GL_RENDERER} together uniquely specify a platform. They do not
8826 change from release to release and should be used by
8827 platform-recognition algorithms.
8829 Some applications want to make use of features that are not part of the
8830 standard GL. These features may be implemented as extensions to the
8831 standard GL. The @code{GL_EXTENSIONS} string is a space-separated list
8832 of supported GL extensions. (Extension names never contain a space
8835 The @code{GL_VERSION} and @code{GL_SHADING_LANGUAGE_VERSION} strings
8836 begin with a version number. The version number uses one of these forms:
8838 @var{major_number.minor_number}@var{major_number.minor_number.release_number}
8840 Vendor-specific information may follow the version number. Its format
8841 depends on the implementation, but a space always separates the version
8842 number and the vendor-specific information.
8844 All strings are null-terminated.
8846 @code{GL_INVALID_ENUM} is generated if @var{name} is not an accepted
8849 @code{GL_INVALID_OPERATION} is generated if @code{glGetString} is
8850 executed between the execution of @code{glBegin} and the corresponding
8851 execution of @code{glEnd}.
8855 @deftypefun void glGetTexImage target level format type img
8856 Return a texture image.
8860 Specifies which texture is to be obtained. @code{GL_TEXTURE_1D},
8861 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D},
8862 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
8863 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
8864 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
8865 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
8866 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, and
8867 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z} are accepted.
8870 Specifies the level-of-detail number of the desired image. Level 0 is
8871 the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap
8875 Specifies a pixel format for the returned data. The supported formats
8876 are @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA},
8877 @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA},
8878 @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA}.
8881 Specifies a pixel type for the returned data. The supported types are
8882 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT},
8883 @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT},
8884 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
8885 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
8886 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
8887 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
8888 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
8889 @code{GL_UNSIGNED_INT_10_10_10_2}, and
8890 @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
8893 Returns the texture image. Should be a pointer to an array of the type
8894 specified by @var{type}.
8898 @code{glGetTexImage} returns a texture image into @var{img}.
8899 @var{target} specifies whether the desired texture image is one
8900 specified by @code{glTexImage1D} (@code{GL_TEXTURE_1D}),
8901 @code{glTexImage2D} (@code{GL_TEXTURE_2D} or any of
8902 @code{GL_TEXTURE_CUBE_MAP_*}), or @code{glTexImage3D}
8903 (@code{GL_TEXTURE_3D}). @var{level} specifies the level-of-detail number
8904 of the desired image. @var{format} and @var{type} specify the format and
8905 type of the desired image array. See the reference pages
8906 @code{glTexImage1D} and @code{glDrawPixels} for a description of the
8907 acceptable values for the @var{format} and @var{type} parameters,
8910 If a non-zero named buffer object is bound to the
8911 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
8912 texture image is requested, @var{img} is treated as a byte offset into
8913 the buffer object's data store.
8915 To understand the operation of @code{glGetTexImage}, consider the
8916 selected internal four-component texture image to be an RGBA color
8917 buffer the size of the image. The semantics of @code{glGetTexImage} are
8918 then identical to those of @code{glReadPixels}, with the exception that
8919 no pixel transfer operations are performed, when called with the same
8920 @var{format} and @var{type}, with @var{x} and @var{y} set to 0,
8921 @var{width} set to the width of the texture image (including border if
8922 one was specified), and @var{height} set to 1 for 1D images, or to the
8923 height of the texture image (including border if one was specified) for
8924 2D images. Because the internal texture image is an RGBA image, pixel
8925 formats @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, and
8926 @code{GL_DEPTH_COMPONENT} are not accepted, and pixel type
8927 @code{GL_BITMAP} is not accepted.
8929 If the selected texture image does not contain four components, the
8930 following mappings are applied. Single-component textures are treated as
8931 RGBA buffers with red set to the single-component value, green set to 0,
8932 blue set to 0, and alpha set to 1. Two-component textures are treated as
8933 RGBA buffers with red set to the value of component zero, alpha set to
8934 the value of component one, and green and blue set to 0. Finally,
8935 three-component textures are treated as RGBA buffers with red set to
8936 component zero, green set to component one, blue set to component two,
8939 To determine the required size of @var{img}, use
8940 @code{glGetTexLevelParameter} to determine the dimensions of the
8941 internal texture image, then scale the required number of pixels by the
8942 storage required for each pixel, based on @var{format} and @var{type}.
8943 Be sure to take the pixel storage parameters into account, especially
8944 @code{GL_PACK_ALIGNMENT}.
8946 @code{GL_INVALID_ENUM} is generated if @var{target}, @var{format}, or
8947 @var{type} is not an accepted value.
8949 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
8951 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
8952 @r{@var{log}_2(@var{max},)}, where @r{@var{max}} is the returned value
8953 of @code{GL_MAX_TEXTURE_SIZE}.
8955 @code{GL_INVALID_OPERATION} is returned if @var{type} is one of
8956 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
8957 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
8958 and @var{format} is not @code{GL_RGB}.
8960 @code{GL_INVALID_OPERATION} is returned if @var{type} is one of
8961 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
8962 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
8963 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
8964 @code{GL_UNSIGNED_INT_10_10_10_2}, or
8965 @code{GL_UNSIGNED_INT_2_10_10_10_REV}, and @var{format} is neither
8966 @code{GL_RGBA} or @code{GL_BGRA}.
8968 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8969 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
8970 object's data store is currently mapped.
8972 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8973 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
8974 would be packed to the buffer object such that the memory writes
8975 required would exceed the data store size.
8977 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
8978 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{img} is
8979 not evenly divisible into the number of bytes needed to store in memory
8980 a datum indicated by @var{type}.
8982 @code{GL_INVALID_OPERATION} is generated if @code{glGetTexImage} is
8983 executed between the execution of @code{glBegin} and the corresponding
8984 execution of @code{glEnd}.
8988 @deftypefun GLint glGetUniformLocation program name
8989 Returns the location of a uniform variable.
8993 Specifies the program object to be queried.
8996 Points to a null terminated string containing the name of the uniform
8997 variable whose location is to be queried.
9001 @code{glGetUniformLocation } returns an integer that represents the
9002 location of a specific uniform variable within a program object.
9003 @var{name} must be a null terminated string that contains no white
9004 space. @var{name} must be an active uniform variable name in
9005 @var{program} that is not a structure, an array of structures, or a
9006 subcomponent of a vector or a matrix. This function returns -1 if
9007 @var{name} does not correspond to an active uniform variable in
9008 @var{program} or if @var{name} starts with the reserved prefix "gl_".
9010 Uniform variables that are structures or arrays of structures may be
9011 queried by calling @code{glGetUniformLocation} for each field within the
9012 structure. The array element operator "[]" and the structure field
9013 operator "." may be used in @var{name} in order to select elements
9014 within an array or fields within a structure. The result of using these
9015 operators is not allowed to be another structure, an array of
9016 structures, or a subcomponent of a vector or a matrix. Except if the
9017 last part of @var{name} indicates a uniform variable array, the location
9018 of the first element of an array can be retrieved by using the name of
9019 the array, or by using the name appended by "[0]".
9021 The actual locations assigned to uniform variables are not known until
9022 the program object is linked successfully. After linking has occurred,
9023 the command @code{glGetUniformLocation} can be used to obtain the
9024 location of a uniform variable. This location value can then be passed
9025 to @code{glUniform} to set the value of the uniform variable or to
9026 @code{glGetUniform} in order to query the current value of the uniform
9027 variable. After a program object has been linked successfully, the index
9028 values for uniform variables remain fixed until the next link command
9029 occurs. Uniform variable locations and values can only be queried after
9030 a link if the link was successful.
9032 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
9033 generated by OpenGL.
9035 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
9038 @code{GL_INVALID_OPERATION} is generated if @var{program} has not been
9039 successfully linked.
9041 @code{GL_INVALID_OPERATION} is generated if @code{glGetUniformLocation}
9042 is executed between the execution of @code{glBegin} and the
9043 corresponding execution of @code{glEnd}.
9047 @deftypefun void glHint target mode
9048 Specify implementation-specific hints.
9052 Specifies a symbolic constant indicating the behavior to be controlled.
9053 @code{GL_FOG_HINT}, @code{GL_GENERATE_MIPMAP_HINT},
9054 @code{GL_LINE_SMOOTH_HINT}, @code{GL_PERSPECTIVE_CORRECTION_HINT},
9055 @code{GL_POINT_SMOOTH_HINT}, @code{GL_POLYGON_SMOOTH_HINT},
9056 @code{GL_TEXTURE_COMPRESSION_HINT}, and
9057 @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT} are accepted.
9060 Specifies a symbolic constant indicating the desired behavior.
9061 @code{GL_FASTEST}, @code{GL_NICEST}, and @code{GL_DONT_CARE} are
9066 Certain aspects of GL behavior, when there is room for interpretation,
9067 can be controlled with hints. A hint is specified with two arguments.
9068 @var{target} is a symbolic constant indicating the behavior to be
9069 controlled, and @var{mode} is another symbolic constant indicating the
9070 desired behavior. The initial value for each @var{target} is
9071 @code{GL_DONT_CARE}. @var{mode} can be one of the following:
9074 @item @code{GL_FASTEST}
9077 The most efficient option should be chosen.
9079 @item @code{GL_NICEST}
9082 The most correct, or highest quality, option should be chosen.
9084 @item @code{GL_DONT_CARE}
9091 Though the implementation aspects that can be hinted are well defined,
9092 the interpretation of the hints depends on the implementation. The hint
9093 aspects that can be specified with @var{target}, along with suggested
9094 semantics, are as follows:
9097 @item @code{GL_FOG_HINT}
9100 Indicates the accuracy of fog calculation. If per-pixel fog calculation
9101 is not efficiently supported by the GL implementation, hinting
9102 @code{GL_DONT_CARE} or @code{GL_FASTEST} can result in per-vertex
9103 calculation of fog effects.
9105 @item @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT}
9108 Indicates the accuracy of the derivative calculation for the GL shading
9109 language fragment processing built-in functions: @code{dFdx},
9110 @code{dFdy}, and @code{fwidth}.
9112 @item @code{GL_GENERATE_MIPMAP_HINT}
9115 Indicates the quality of filtering when generating mipmap images.
9117 @item @code{GL_LINE_SMOOTH_HINT}
9120 Indicates the sampling quality of antialiased lines. If a larger filter
9121 function is applied, hinting @code{GL_NICEST} can result in more pixel
9122 fragments being generated during rasterization.
9124 @item @code{GL_PERSPECTIVE_CORRECTION_HINT}
9127 Indicates the quality of color, texture coordinate, and fog coordinate
9128 interpolation. If perspective-corrected parameter interpolation is not
9129 efficiently supported by the GL implementation, hinting
9130 @code{GL_DONT_CARE} or @code{GL_FASTEST} can result in simple linear
9131 interpolation of colors and/or texture coordinates.
9133 @item @code{GL_POINT_SMOOTH_HINT}
9136 Indicates the sampling quality of antialiased points. If a larger filter
9137 function is applied, hinting @code{GL_NICEST} can result in more pixel
9138 fragments being generated during rasterization.
9140 @item @code{GL_POLYGON_SMOOTH_HINT}
9143 Indicates the sampling quality of antialiased polygons. Hinting
9144 @code{GL_NICEST} can result in more pixel fragments being generated
9145 during rasterization, if a larger filter function is applied.
9147 @item @code{GL_TEXTURE_COMPRESSION_HINT}
9150 Indicates the quality and performance of the compressing texture images.
9151 Hinting @code{GL_FASTEST} indicates that texture images should be
9152 compressed as quickly as possible, while @code{GL_NICEST} indicates that
9153 texture images should be compressed with as little image quality loss as
9154 possible. @code{GL_NICEST} should be selected if the texture is to be
9155 retrieved by @code{glGetCompressedTexImage} for reuse.
9159 @code{GL_INVALID_ENUM} is generated if either @var{target} or @var{mode}
9160 is not an accepted value.
9162 @code{GL_INVALID_OPERATION} is generated if @code{glHint} is executed
9163 between the execution of @code{glBegin} and the corresponding execution
9168 @deftypefun void glHistogram target width internalformat sink
9169 Define histogram table.
9173 The histogram whose parameters are to be set. Must be one of
9174 @code{GL_HISTOGRAM} or @code{GL_PROXY_HISTOGRAM}.
9177 The number of entries in the histogram table. Must be a power of 2.
9179 @item @var{internalformat}
9180 The format of entries in the histogram table. Must be one of
9181 @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
9182 @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
9183 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
9184 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
9185 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
9186 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
9187 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
9188 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
9189 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
9190 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
9191 @code{GL_RGBA12}, or @code{GL_RGBA16}.
9194 If @code{GL_TRUE}, pixels will be consumed by the histogramming process
9195 and no drawing or texture loading will take place. If @code{GL_FALSE},
9196 pixels will proceed to the minmax process after histogramming.
9200 When @code{GL_HISTOGRAM} is enabled, RGBA color components are converted
9201 to histogram table indices by clamping to the range [0,1], multiplying
9202 by the width of the histogram table, and rounding to the nearest
9203 integer. The table entries selected by the RGBA indices are then
9204 incremented. (If the internal format of the histogram table includes
9205 luminance, then the index derived from the R color component determines
9206 the luminance table entry to be incremented.) If a histogram table entry
9207 is incremented beyond its maximum value, then its value becomes
9208 undefined. (This is not an error.)
9210 Histogramming is performed only for RGBA pixels (though these may be
9211 specified originally as color indices and converted to RGBA by index
9212 table lookup). Histogramming is enabled with @code{glEnable} and
9213 disabled with @code{glDisable}.
9215 When @var{target} is @code{GL_HISTOGRAM}, @code{glHistogram} redefines
9216 the current histogram table to have @var{width} entries of the format
9217 specified by @var{internalformat}. The entries are indexed 0 through
9218 @r{@var{width}-1}, and all entries are initialized to zero. The values
9219 in the previous histogram table, if any, are lost. If @var{sink} is
9220 @code{GL_TRUE}, then pixels are discarded after histogramming; no
9221 further processing of the pixels takes place, and no drawing, texture
9222 loading, or pixel readback will result.
9224 When @var{target} is @code{GL_PROXY_HISTOGRAM}, @code{glHistogram}
9225 computes all state information as if the histogram table were to be
9226 redefined, but does not actually define the new table. If the requested
9227 histogram table is too large to be supported, then the state information
9228 will be set to zero. This provides a way to determine if a histogram
9229 table with the given parameters can be supported.
9233 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
9236 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
9237 is not a power of 2.
9239 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
9240 of the allowable values.
9242 @code{GL_TABLE_TOO_LARGE} is generated if @var{target} is
9243 @code{GL_HISTOGRAM} and the histogram table specified is too large for
9246 @code{GL_INVALID_OPERATION} is generated if @code{glHistogram} is
9247 executed between the execution of @code{glBegin} and the corresponding
9248 execution of @code{glEnd}.
9252 @deftypefun void glIndexMask mask
9253 Control the writing of individual bits in the color index buffers.
9257 Specifies a bit mask to enable and disable the writing of individual
9258 bits in the color index buffers. Initially, the mask is all 1's.
9262 @code{glIndexMask} controls the writing of individual bits in the color
9263 index buffers. The least significant @r{@var{n}} bits of @var{mask},
9264 where @r{@var{n}} is the number of bits in a color index buffer, specify
9265 a mask. Where a 1 (one) appears in the mask, it's possible to write to
9266 the corresponding bit in the color index buffer (or buffers). Where a 0
9267 (zero) appears, the corresponding bit is write-protected.
9269 This mask is used only in color index mode, and it affects only the
9270 buffers currently selected for writing (see @code{glDrawBuffer}).
9271 Initially, all bits are enabled for writing.
9273 @code{GL_INVALID_OPERATION} is generated if @code{glIndexMask} is
9274 executed between the execution of @code{glBegin} and the corresponding
9275 execution of @code{glEnd}.
9279 @deftypefun void glIndexPointer type stride pointer
9280 Define an array of color indexes.
9284 Specifies the data type of each color index in the array. Symbolic
9285 constants @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, @code{GL_INT},
9286 @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value is
9290 Specifies the byte offset between consecutive color indexes. If
9291 @var{stride} is 0, the color indexes are understood to be tightly packed
9292 in the array. The initial value is 0.
9295 Specifies a pointer to the first index in the array. The initial value
9300 @code{glIndexPointer} specifies the location and data format of an array
9301 of color indexes to use when rendering. @var{type} specifies the data
9302 type of each color index and @var{stride} specifies the byte stride from
9303 one color index to the next, allowing vertices and attributes to be
9304 packed into a single array or stored in separate arrays.
9306 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
9307 target (see @code{glBindBuffer}) while a color index array is specified,
9308 @var{pointer} is treated as a byte offset into the buffer object's data
9309 store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING})
9310 is saved as color index vertex array client-side state
9311 (@code{GL_INDEX_ARRAY_BUFFER_BINDING}).
9313 When a color index array is specified, @var{type}, @var{stride}, and
9314 @var{pointer} are saved as client-side state, in addition to the current
9315 vertex array buffer object binding.
9317 To enable and disable the color index array, call
9318 @code{glEnableClientState} and @code{glDisableClientState} with the
9319 argument @code{GL_INDEX_ARRAY}. If enabled, the color index array is
9320 used when @code{glDrawArrays}, @code{glMultiDrawArrays},
9321 @code{glDrawElements}, @code{glMultiDrawElements},
9322 @code{glDrawRangeElements}, or @code{glArrayElement} is called.
9324 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
9327 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
9331 @deftypefun void glIndexi c
9332 @deftypefunx void glIndexf c
9333 @deftypefunx void glIndexub c
9334 Set the current color index.
9338 Specifies the new value for the current color index.
9344 @code{glIndex} updates the current (single-valued) color index. It takes
9345 one argument, the new value for the current color index.
9347 The current index is stored as a floating-point value. Integer values
9348 are converted directly to floating-point values, with no special
9349 mapping. The initial value is 1.
9351 Index values outside the representable range of the color index buffer
9352 are not clamped. However, before an index is dithered (if enabled) and
9353 written to the frame buffer, it is converted to fixed-point format. Any
9354 bits in the integer portion of the resulting fixed-point value that do
9355 not correspond to bits in the frame buffer are masked out.
9359 @deftypefun void glInitNames
9360 Initialize the name stack.
9362 The name stack is used during selection mode to allow sets of rendering
9363 commands to be uniquely identified. It consists of an ordered set of
9364 unsigned integers. @code{glInitNames} causes the name stack to be
9365 initialized to its default empty state.
9367 The name stack is always empty while the render mode is not
9368 @code{GL_SELECT}. Calls to @code{glInitNames} while the render mode is
9369 not @code{GL_SELECT} are ignored.
9371 @code{GL_INVALID_OPERATION} is generated if @code{glInitNames} is
9372 executed between the execution of @code{glBegin} and the corresponding
9373 execution of @code{glEnd}.
9377 @deftypefun void glInterleavedArrays format stride pointer
9378 Simultaneously specify and enable several interleaved arrays.
9382 Specifies the type of array to enable. Symbolic constants @code{GL_V2F},
9383 @code{GL_V3F}, @code{GL_C4UB_V2F}, @code{GL_C4UB_V3F},
9384 @code{GL_C3F_V3F}, @code{GL_N3F_V3F}, @code{GL_C4F_N3F_V3F},
9385 @code{GL_T2F_V3F}, @code{GL_T4F_V4F}, @code{GL_T2F_C4UB_V3F},
9386 @code{GL_T2F_C3F_V3F}, @code{GL_T2F_N3F_V3F}, @code{GL_T2F_C4F_N3F_V3F},
9387 and @code{GL_T4F_C4F_N3F_V4F} are accepted.
9390 Specifies the offset in bytes between each aggregate array element.
9394 @code{glInterleavedArrays} lets you specify and enable individual color,
9395 normal, texture and vertex arrays whose elements are part of a larger
9396 aggregate array element. For some implementations, this is more
9397 efficient than specifying the arrays separately.
9399 If @var{stride} is 0, the aggregate elements are stored consecutively.
9400 Otherwise, @var{stride} bytes occur between the beginning of one
9401 aggregate array element and the beginning of the next aggregate array
9404 @var{format} serves as a ``key'' describing the extraction of individual
9405 arrays from the aggregate array. If @var{format} contains a T, then
9406 texture coordinates are extracted from the interleaved array. If C is
9407 present, color values are extracted. If N is present, normal coordinates
9408 are extracted. Vertex coordinates are always extracted.
9410 The digits 2, 3, and 4 denote how many values are extracted. F indicates
9411 that values are extracted as floating-point values. Colors may also be
9412 extracted as 4 unsigned bytes if 4UB follows the C. If a color is
9413 extracted as 4 unsigned bytes, the vertex array element which follows is
9414 located at the first possible floating-point aligned address.
9416 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
9419 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
9423 @deftypefun GLboolean glIsBuffer buffer
9424 Determine if a name corresponds to a buffer object.
9428 Specifies a value that may be the name of a buffer object.
9432 @code{glIsBuffer} returns @code{GL_TRUE} if @var{buffer} is currently
9433 the name of a buffer object. If @var{buffer} is zero, or is a non-zero
9434 value that is not currently the name of a buffer object, or if an error
9435 occurs, @code{glIsBuffer} returns @code{GL_FALSE}.
9437 A name returned by @code{glGenBuffers}, but not yet associated with a
9438 buffer object by calling @code{glBindBuffer}, is not the name of a
9441 @code{GL_INVALID_OPERATION} is generated if @code{glIsBuffer} is
9442 executed between the execution of @code{glBegin} and the corresponding
9443 execution of @code{glEnd}.
9447 @deftypefun GLboolean glIsEnabled cap
9448 Test whether a capability is enabled.
9452 Specifies a symbolic constant indicating a GL capability.
9456 @code{glIsEnabled} returns @code{GL_TRUE} if @var{cap} is an enabled
9457 capability and returns @code{GL_FALSE} otherwise. Initially all
9458 capabilities except @code{GL_DITHER} are disabled; @code{GL_DITHER} is
9461 The following capabilities are accepted for @var{cap}:
9466 @item @strong{Constant}
9469 @item @code{GL_ALPHA_TEST}
9472 @item @code{GL_AUTO_NORMAL}
9475 @item @code{GL_BLEND}
9476 @code{glBlendFunc}, @code{glLogicOp}
9478 @item @code{GL_CLIP_PLANE}@var{i}
9481 @item @code{GL_COLOR_ARRAY}
9482 @code{glColorPointer}
9484 @item @code{GL_COLOR_LOGIC_OP}
9487 @item @code{GL_COLOR_MATERIAL}
9488 @code{glColorMaterial}
9490 @item @code{GL_COLOR_SUM}
9491 @code{glSecondaryColor}
9493 @item @code{GL_COLOR_TABLE}
9496 @item @code{GL_CONVOLUTION_1D}
9497 @code{glConvolutionFilter1D}
9499 @item @code{GL_CONVOLUTION_2D}
9500 @code{glConvolutionFilter2D}
9502 @item @code{GL_CULL_FACE}
9505 @item @code{GL_DEPTH_TEST}
9506 @code{glDepthFunc}, @code{glDepthRange}
9508 @item @code{GL_DITHER}
9511 @item @code{GL_EDGE_FLAG_ARRAY}
9512 @code{glEdgeFlagPointer}
9517 @item @code{GL_FOG_COORD_ARRAY}
9518 @code{glFogCoordPointer}
9520 @item @code{GL_HISTOGRAM}
9523 @item @code{GL_INDEX_ARRAY}
9524 @code{glIndexPointer}
9526 @item @code{GL_INDEX_LOGIC_OP}
9529 @item @code{GL_LIGHT}@var{i}
9530 @code{glLightModel}, @code{glLight}
9532 @item @code{GL_LIGHTING}
9533 @code{glMaterial}, @code{glLightModel}, @code{glLight}
9535 @item @code{GL_LINE_SMOOTH}
9538 @item @code{GL_LINE_STIPPLE}
9539 @code{glLineStipple}
9541 @item @code{GL_MAP1_COLOR_4}
9544 @item @code{GL_MAP1_INDEX}
9547 @item @code{GL_MAP1_NORMAL}
9550 @item @code{GL_MAP1_TEXTURE_COORD_1}
9553 @item @code{GL_MAP1_TEXTURE_COORD_2}
9556 @item @code{GL_MAP1_TEXTURE_COORD_3}
9559 @item @code{GL_MAP1_TEXTURE_COORD_4}
9562 @item @code{GL_MAP2_COLOR_4}
9565 @item @code{GL_MAP2_INDEX}
9568 @item @code{GL_MAP2_NORMAL}
9571 @item @code{GL_MAP2_TEXTURE_COORD_1}
9574 @item @code{GL_MAP2_TEXTURE_COORD_2}
9577 @item @code{GL_MAP2_TEXTURE_COORD_3}
9580 @item @code{GL_MAP2_TEXTURE_COORD_4}
9583 @item @code{GL_MAP2_VERTEX_3}
9586 @item @code{GL_MAP2_VERTEX_4}
9589 @item @code{GL_MINMAX}
9592 @item @code{GL_MULTISAMPLE}
9593 @code{glSampleCoverage}
9595 @item @code{GL_NORMAL_ARRAY}
9596 @code{glNormalPointer}
9598 @item @code{GL_NORMALIZE}
9601 @item @code{GL_POINT_SMOOTH}
9604 @item @code{GL_POINT_SPRITE}
9607 @item @code{GL_POLYGON_SMOOTH}
9608 @code{glPolygonMode}
9610 @item @code{GL_POLYGON_OFFSET_FILL}
9611 @code{glPolygonOffset}
9613 @item @code{GL_POLYGON_OFFSET_LINE}
9614 @code{glPolygonOffset}
9616 @item @code{GL_POLYGON_OFFSET_POINT}
9617 @code{glPolygonOffset}
9619 @item @code{GL_POLYGON_STIPPLE}
9620 @code{glPolygonStipple}
9622 @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}
9625 @item @code{GL_POST_CONVOLUTION_COLOR_TABLE}
9628 @item @code{GL_RESCALE_NORMAL}
9631 @item @code{GL_SAMPLE_ALPHA_TO_COVERAGE}
9632 @code{glSampleCoverage}
9634 @item @code{GL_SAMPLE_ALPHA_TO_ONE}
9635 @code{glSampleCoverage}
9637 @item @code{GL_SAMPLE_COVERAGE}
9638 @code{glSampleCoverage}
9640 @item @code{GL_SCISSOR_TEST}
9643 @item @code{GL_SECONDARY_COLOR_ARRAY}
9644 @code{glSecondaryColorPointer}
9646 @item @code{GL_SEPARABLE_2D}
9647 @code{glSeparableFilter2D}
9649 @item @code{GL_STENCIL_TEST}
9650 @code{glStencilFunc}, @code{glStencilOp}
9652 @item @code{GL_TEXTURE_1D}
9655 @item @code{GL_TEXTURE_2D}
9658 @item @code{GL_TEXTURE_3D}
9661 @item @code{GL_TEXTURE_COORD_ARRAY}
9662 @code{glTexCoordPointer}
9664 @item @code{GL_TEXTURE_CUBE_MAP}
9667 @item @code{GL_TEXTURE_GEN_Q}
9670 @item @code{GL_TEXTURE_GEN_R}
9673 @item @code{GL_TEXTURE_GEN_S}
9676 @item @code{GL_TEXTURE_GEN_T}
9679 @item @code{GL_VERTEX_ARRAY}
9680 @code{glVertexPointer}
9682 @item @code{GL_VERTEX_PROGRAM_POINT_SIZE}
9685 @item @code{GL_VERTEX_PROGRAM_TWO_SIDE}
9692 @code{GL_INVALID_ENUM} is generated if @var{cap} is not an accepted
9695 @code{GL_INVALID_OPERATION} is generated if @code{glIsEnabled} is
9696 executed between the execution of @code{glBegin} and the corresponding
9697 execution of @code{glEnd}.
9701 @deftypefun GLboolean glIsList list
9702 Determine if a name corresponds to a display list.
9706 Specifies a potential display list name.
9710 @code{glIsList} returns @code{GL_TRUE} if @var{list} is the name of a
9711 display list and returns @code{GL_FALSE} if it is not, or if an error
9714 A name returned by @code{glGenLists}, but not yet associated with a
9715 display list by calling @code{glNewList}, is not the name of a display
9718 @code{GL_INVALID_OPERATION} is generated if @code{glIsList} is executed
9719 between the execution of @code{glBegin} and the corresponding execution
9724 @deftypefun GLboolean glIsProgram program
9725 Determines if a name corresponds to a program object.
9729 Specifies a potential program object.
9733 @code{glIsProgram} returns @code{GL_TRUE} if @var{program} is the name
9734 of a program object previously created with @code{glCreateProgram} and
9735 not yet deleted with @code{glDeleteProgram}. If @var{program} is zero or
9736 a non-zero value that is not the name of a program object, or if an
9737 error occurs, @code{glIsProgram} returns @code{GL_FALSE}.
9739 @code{GL_INVALID_OPERATION} is generated if @code{glIsProgram} is
9740 executed between the execution of @code{glBegin} and the corresponding
9741 execution of @code{glEnd}.
9745 @deftypefun GLboolean glIsQuery id
9746 Determine if a name corresponds to a query object.
9750 Specifies a value that may be the name of a query object.
9754 @code{glIsQuery} returns @code{GL_TRUE} if @var{id} is currently the
9755 name of a query object. If @var{id} is zero, or is a non-zero value that
9756 is not currently the name of a query object, or if an error occurs,
9757 @code{glIsQuery} returns @code{GL_FALSE}.
9759 A name returned by @code{glGenQueries}, but not yet associated with a
9760 query object by calling @code{glBeginQuery}, is not the name of a query
9763 @code{GL_INVALID_OPERATION} is generated if @code{glIsQuery} is executed
9764 between the execution of @code{glBegin} and the corresponding execution
9769 @deftypefun GLboolean glIsShader shader
9770 Determines if a name corresponds to a shader object.
9774 Specifies a potential shader object.
9778 @code{glIsShader} returns @code{GL_TRUE} if @var{shader} is the name of
9779 a shader object previously created with @code{glCreateShader} and not
9780 yet deleted with @code{glDeleteShader}. If @var{shader} is zero or a
9781 non-zero value that is not the name of a shader object, or if an error
9782 occurs, @code{glIsShader } returns @code{GL_FALSE}.
9784 @code{GL_INVALID_OPERATION} is generated if @code{glIsShader} is
9785 executed between the execution of @code{glBegin} and the corresponding
9786 execution of @code{glEnd}.
9790 @deftypefun GLboolean glIsTexture texture
9791 Determine if a name corresponds to a texture.
9795 Specifies a value that may be the name of a texture.
9799 @code{glIsTexture} returns @code{GL_TRUE} if @var{texture} is currently
9800 the name of a texture. If @var{texture} is zero, or is a non-zero value
9801 that is not currently the name of a texture, or if an error occurs,
9802 @code{glIsTexture} returns @code{GL_FALSE}.
9804 A name returned by @code{glGenTextures}, but not yet associated with a
9805 texture by calling @code{glBindTexture}, is not the name of a texture.
9807 @code{GL_INVALID_OPERATION} is generated if @code{glIsTexture} is
9808 executed between the execution of @code{glBegin} and the corresponding
9809 execution of @code{glEnd}.
9813 @deftypefun void glLightModelf pname param
9814 @deftypefunx void glLightModeli pname param
9815 Set the lighting model parameters.
9819 Specifies a single-valued lighting model parameter.
9820 @code{GL_LIGHT_MODEL_LOCAL_VIEWER}, @code{GL_LIGHT_MODEL_COLOR_CONTROL},
9821 and @code{GL_LIGHT_MODEL_TWO_SIDE} are accepted.
9824 Specifies the value that @var{param} will be set to.
9828 @code{glLightModel} sets the lighting model parameter. @var{pname} names
9829 a parameter and @var{params} gives the new value. There are three
9830 lighting model parameters:
9833 @item @code{GL_LIGHT_MODEL_AMBIENT}
9836 @var{params} contains four integer or floating-point values that specify
9837 the ambient RGBA intensity of the entire scene. Integer values are
9838 mapped linearly such that the most positive representable value maps to
9839 1.0, and the most negative representable value maps to @r{-1.0}.
9840 Floating-point values are mapped directly. Neither integer nor
9841 floating-point values are clamped. The initial ambient scene intensity
9842 is (0.2, 0.2, 0.2, 1.0).
9844 @item @code{GL_LIGHT_MODEL_COLOR_CONTROL}
9847 @var{params} must be either @code{GL_SEPARATE_SPECULAR_COLOR} or
9848 @code{GL_SINGLE_COLOR}. @code{GL_SINGLE_COLOR} specifies that a single
9849 color is generated from the lighting computation for a vertex.
9850 @code{GL_SEPARATE_SPECULAR_COLOR} specifies that the specular color
9851 computation of lighting be stored separately from the remainder of the
9852 lighting computation. The specular color is summed into the generated
9853 fragment's color after the application of texture mapping (if enabled).
9854 The initial value is @code{GL_SINGLE_COLOR}.
9856 @item @code{GL_LIGHT_MODEL_LOCAL_VIEWER}
9859 @var{params} is a single integer or floating-point value that specifies
9860 how specular reflection angles are computed. If @var{params} is 0 (or
9861 0.0), specular reflection angles take the view direction to be parallel
9862 to and in the direction of the -@var{z} axis, regardless of the location
9863 of the vertex in eye coordinates. Otherwise, specular reflections are
9864 computed from the origin of the eye coordinate system. The initial value
9867 @item @code{GL_LIGHT_MODEL_TWO_SIDE}
9870 @var{params} is a single integer or floating-point value that specifies
9871 whether one- or two-sided lighting calculations are done for polygons.
9872 It has no effect on the lighting calculations for points, lines, or
9873 bitmaps. If @var{params} is 0 (or 0.0), one-sided lighting is specified,
9874 and only the @var{front} material parameters are used in the lighting
9875 equation. Otherwise, two-sided lighting is specified. In this case,
9876 vertices of back-facing polygons are lighted using the @var{back}
9877 material parameters and have their normals reversed before the lighting
9878 equation is evaluated. Vertices of front-facing polygons are always
9879 lighted using the @var{front} material parameters, with no change to
9880 their normals. The initial value is 0.
9884 In RGBA mode, the lighted color of a vertex is the sum of the material
9885 emission intensity, the product of the material ambient reflectance and
9886 the lighting model full-scene ambient intensity, and the contribution of
9887 each enabled light source. Each light source contributes the sum of
9888 three terms: ambient, diffuse, and specular. The ambient light source
9889 contribution is the product of the material ambient reflectance and the
9890 light's ambient intensity. The diffuse light source contribution is the
9891 product of the material diffuse reflectance, the light's diffuse
9892 intensity, and the dot product of the vertex's normal with the
9893 normalized vector from the vertex to the light source. The specular
9894 light source contribution is the product of the material specular
9895 reflectance, the light's specular intensity, and the dot product of the
9896 normalized vertex-to-eye and vertex-to-light vectors, raised to the
9897 power of the shininess of the material. All three light source
9898 contributions are attenuated equally based on the distance from the
9899 vertex to the light source and on light source direction, spread
9900 exponent, and spread cutoff angle. All dot products are replaced with 0
9901 if they evaluate to a negative value.
9903 The alpha component of the resulting lighted color is set to the alpha
9904 value of the material diffuse reflectance.
9906 In color index mode, the value of the lighted index of a vertex ranges
9907 from the ambient to the specular values passed to @code{glMaterial}
9908 using @code{GL_COLOR_INDEXES}. Diffuse and specular coefficients,
9909 computed with a (.30, .59, .11) weighting of the lights' colors, the
9910 shininess of the material, and the same reflection and attenuation
9911 equations as in the RGBA case, determine how much above ambient the
9914 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
9917 @code{GL_INVALID_ENUM} is generated if @var{pname} is
9918 @code{GL_LIGHT_MODEL_COLOR_CONTROL} and @var{params} is not one of
9919 @code{GL_SINGLE_COLOR} or @code{GL_SEPARATE_SPECULAR_COLOR}.
9921 @code{GL_INVALID_OPERATION} is generated if @code{glLightModel} is
9922 executed between the execution of @code{glBegin} and the corresponding
9923 execution of @code{glEnd}.
9927 @deftypefun void glLightf light pname param
9928 @deftypefunx void glLighti light pname param
9929 Set light source parameters.
9933 Specifies a light. The number of lights depends on the implementation,
9934 but at least eight lights are supported. They are identified by symbolic
9935 names of the form @code{GL_LIGHT}@r{@var{i}}, where i ranges from 0 to
9936 the value of @code{GL_MAX_LIGHTS} - 1.
9939 Specifies a single-valued light source parameter for @var{light}.
9940 @code{GL_SPOT_EXPONENT}, @code{GL_SPOT_CUTOFF},
9941 @code{GL_CONSTANT_ATTENUATION}, @code{GL_LINEAR_ATTENUATION}, and
9942 @code{GL_QUADRATIC_ATTENUATION} are accepted.
9945 Specifies the value that parameter @var{pname} of light source
9946 @var{light} will be set to.
9950 @code{glLight} sets the values of individual light source parameters.
9951 @var{light} names the light and is a symbolic name of the form
9952 @code{GL_LIGHT}@r{@var{i}}, where i ranges from 0 to the value of
9953 @code{GL_MAX_LIGHTS} - 1. @var{pname} specifies one of ten light source
9954 parameters, again by symbolic name. @var{params} is either a single
9955 value or a pointer to an array that contains the new values.
9957 To enable and disable lighting calculation, call @code{glEnable} and
9958 @code{glDisable} with argument @code{GL_LIGHTING}. Lighting is initially
9959 disabled. When it is enabled, light sources that are enabled contribute
9960 to the lighting calculation. Light source @r{@var{i}} is enabled and
9961 disabled using @code{glEnable} and @code{glDisable} with argument
9962 @code{GL_LIGHT}@r{@var{i}}.
9964 The ten light parameters are as follows:
9967 @item @code{GL_AMBIENT}
9968 @var{params} contains four integer or floating-point values that specify
9969 the ambient RGBA intensity of the light. Integer values are mapped
9970 linearly such that the most positive representable value maps to 1.0,
9971 and the most negative representable value maps to @r{-1.0}.
9972 Floating-point values are mapped directly. Neither integer nor
9973 floating-point values are clamped. The initial ambient light intensity
9976 @item @code{GL_DIFFUSE}
9977 @var{params} contains four integer or floating-point values that specify
9978 the diffuse RGBA intensity of the light. Integer values are mapped
9979 linearly such that the most positive representable value maps to 1.0,
9980 and the most negative representable value maps to @r{-1.0}.
9981 Floating-point values are mapped directly. Neither integer nor
9982 floating-point values are clamped. The initial value for
9983 @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial value is
9986 @item @code{GL_SPECULAR}
9987 @var{params} contains four integer or floating-point values that specify
9988 the specular RGBA intensity of the light. Integer values are mapped
9989 linearly such that the most positive representable value maps to 1.0,
9990 and the most negative representable value maps to @r{-1.0}.
9991 Floating-point values are mapped directly. Neither integer nor
9992 floating-point values are clamped. The initial value for
9993 @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial value is
9996 @item @code{GL_POSITION}
9997 @var{params} contains four integer or floating-point values that specify
9998 the position of the light in homogeneous object coordinates. Both
9999 integer and floating-point values are mapped directly. Neither integer
10000 nor floating-point values are clamped.
10002 The position is transformed by the modelview matrix when @code{glLight}
10003 is called (just as if it were a point), and it is stored in eye
10004 coordinates. If the @r{@var{w}} component of the position is 0, the
10005 light is treated as a directional source. Diffuse and specular lighting
10006 calculations take the light's direction, but not its actual position,
10007 into account, and attenuation is disabled. Otherwise, diffuse and
10008 specular lighting calculations are based on the actual location of the
10009 light in eye coordinates, and attenuation is enabled. The initial
10010 position is (0, 0, 1, 0); thus, the initial light source is directional,
10011 parallel to, and in the direction of the @r{-@var{z}} axis.
10013 @item @code{GL_SPOT_DIRECTION}
10014 @var{params} contains three integer or floating-point values that
10015 specify the direction of the light in homogeneous object coordinates.
10016 Both integer and floating-point values are mapped directly. Neither
10017 integer nor floating-point values are clamped.
10019 The spot direction is transformed by the upper 3x3 of the modelview
10020 matrix when @code{glLight} is called, and it is stored in eye
10021 coordinates. It is significant only when @code{GL_SPOT_CUTOFF} is not
10022 180, which it is initially. The initial direction is @r{(0,0-1)}.
10024 @item @code{GL_SPOT_EXPONENT}
10025 @var{params} is a single integer or floating-point value that specifies
10026 the intensity distribution of the light. Integer and floating-point
10027 values are mapped directly. Only values in the range @r{[0,128]} are
10030 Effective light intensity is attenuated by the cosine of the angle
10031 between the direction of the light and the direction from the light to
10032 the vertex being lighted, raised to the power of the spot exponent.
10033 Thus, higher spot exponents result in a more focused light source,
10034 regardless of the spot cutoff angle (see @code{GL_SPOT_CUTOFF}, next
10035 paragraph). The initial spot exponent is 0, resulting in uniform light
10038 @item @code{GL_SPOT_CUTOFF}
10039 @var{params} is a single integer or floating-point value that specifies
10040 the maximum spread angle of a light source. Integer and floating-point
10041 values are mapped directly. Only values in the range @r{[0,90]} and the
10042 special value 180 are accepted. If the angle between the direction of
10043 the light and the direction from the light to the vertex being lighted
10044 is greater than the spot cutoff angle, the light is completely masked.
10045 Otherwise, its intensity is controlled by the spot exponent and the
10046 attenuation factors. The initial spot cutoff is 180, resulting in
10047 uniform light distribution.
10049 @item @code{GL_CONSTANT_ATTENUATION}
10050 @item @code{GL_LINEAR_ATTENUATION}
10051 @item @code{GL_QUADRATIC_ATTENUATION}
10052 @var{params} is a single integer or floating-point value that specifies
10053 one of the three light attenuation factors. Integer and floating-point
10054 values are mapped directly. Only nonnegative values are accepted. If the
10055 light is positional, rather than directional, its intensity is
10056 attenuated by the reciprocal of the sum of the constant factor, the
10057 linear factor times the distance between the light and the vertex being
10058 lighted, and the quadratic factor times the square of the same distance.
10059 The initial attenuation factors are (1, 0, 0), resulting in no
10064 @code{GL_INVALID_ENUM} is generated if either @var{light} or @var{pname}
10065 is not an accepted value.
10067 @code{GL_INVALID_VALUE} is generated if a spot exponent value is
10068 specified outside the range @r{[0,128]}, or if spot cutoff is specified
10069 outside the range @r{[0,90]} (except for the special value 180), or if a
10070 negative attenuation factor is specified.
10072 @code{GL_INVALID_OPERATION} is generated if @code{glLight} is executed
10073 between the execution of @code{glBegin} and the corresponding execution
10078 @deftypefun void glLineStipple factor pattern
10079 Specify the line stipple pattern.
10083 Specifies a multiplier for each bit in the line stipple pattern. If
10084 @var{factor} is 3, for example, each bit in the pattern is used three
10085 times before the next bit in the pattern is used. @var{factor} is
10086 clamped to the range [1, 256] and defaults to 1.
10088 @item @var{pattern}
10089 Specifies a 16-bit integer whose bit pattern determines which fragments
10090 of a line will be drawn when the line is rasterized. Bit zero is used
10091 first; the default pattern is all 1's.
10095 Line stippling masks out certain fragments produced by rasterization;
10096 those fragments will not be drawn. The masking is achieved by using
10097 three parameters: the 16-bit line stipple pattern @var{pattern}, the
10098 repeat count @var{factor}, and an integer stipple counter @r{@var{s}}.
10100 Counter @r{@var{s}} is reset to 0 whenever @code{glBegin} is called and
10101 before each line segment of a
10102 @code{glBegin}(@code{GL_LINES})/@code{glEnd} sequence is generated. It
10103 is incremented after each fragment of a unit width aliased line segment
10104 is generated or after each @r{@var{i}} fragments of an @r{@var{i}} width
10105 line segment are generated. The @r{@var{i}} fragments associated with
10106 count @r{@var{s}} are masked out if
10108 @var{pattern} bit @r{(@var{s}/@var{factor},)%16}
10110 is 0, otherwise these fragments are sent to the frame buffer. Bit zero
10111 of @var{pattern} is the least significant bit.
10113 Antialiased lines are treated as a sequence of @r{1×@var{width}}
10114 rectangles for purposes of stippling. Whether rectangle @r{@var{s}} is
10115 rasterized or not depends on the fragment rule described for aliased
10116 lines, counting rectangles rather than groups of fragments.
10118 To enable and disable line stippling, call @code{glEnable} and
10119 @code{glDisable} with argument @code{GL_LINE_STIPPLE}. When enabled, the
10120 line stipple pattern is applied as described above. When disabled, it is
10121 as if the pattern were all 1's. Initially, line stippling is disabled.
10123 @code{GL_INVALID_OPERATION} is generated if @code{glLineStipple} is
10124 executed between the execution of @code{glBegin} and the corresponding
10125 execution of @code{glEnd}.
10129 @deftypefun void glLineWidth width
10130 Specify the width of rasterized lines.
10134 Specifies the width of rasterized lines. The initial value is 1.
10138 @code{glLineWidth} specifies the rasterized width of both aliased and
10139 antialiased lines. Using a line width other than 1 has different
10140 effects, depending on whether line antialiasing is enabled. To enable
10141 and disable line antialiasing, call @code{glEnable} and @code{glDisable}
10142 with argument @code{GL_LINE_SMOOTH}. Line antialiasing is initially
10145 If line antialiasing is disabled, the actual width is determined by
10146 rounding the supplied width to the nearest integer. (If the rounding
10147 results in the value 0, it is as if the line width were 1.) If
10148 @r{∣Δ@var{x},∣>=∣Δ@var{y},∣}, @var{i} pixels are filled in each column
10149 that is rasterized, where @var{i} is the rounded value of @var{width}.
10150 Otherwise, @var{i} pixels are filled in each row that is rasterized.
10152 If antialiasing is enabled, line rasterization produces a fragment for
10153 each pixel square that intersects the region lying within the rectangle
10154 having width equal to the current line width, length equal to the actual
10155 length of the line, and centered on the mathematical line segment. The
10156 coverage value for each fragment is the window coordinate area of the
10157 intersection of the rectangular region with the corresponding pixel
10158 square. This value is saved and used in the final rasterization step.
10160 Not all widths can be supported when line antialiasing is enabled. If an
10161 unsupported width is requested, the nearest supported width is used.
10162 Only width 1 is guaranteed to be supported; others depend on the
10163 implementation. Likewise, there is a range for aliased line widths as
10164 well. To query the range of supported widths and the size difference
10165 between supported widths within the range, call @code{glGet} with
10166 arguments @code{GL_ALIASED_LINE_WIDTH_RANGE},
10167 @code{GL_SMOOTH_LINE_WIDTH_RANGE}, and
10168 @code{GL_SMOOTH_LINE_WIDTH_GRANULARITY}.
10170 @code{GL_INVALID_VALUE} is generated if @var{width} is less than or
10173 @code{GL_INVALID_OPERATION} is generated if @code{glLineWidth} is
10174 executed between the execution of @code{glBegin} and the corresponding
10175 execution of @code{glEnd}.
10179 @deftypefun void glLinkProgram program
10180 Links a program object.
10183 @item @var{program}
10184 Specifies the handle of the program object to be linked.
10188 @code{glLinkProgram} links the program object specified by
10189 @var{program}. If any shader objects of type @code{GL_VERTEX_SHADER} are
10190 attached to @var{program}, they will be used to create an executable
10191 that will run on the programmable vertex processor. If any shader
10192 objects of type @code{GL_FRAGMENT_SHADER} are attached to @var{program},
10193 they will be used to create an executable that will run on the
10194 programmable fragment processor.
10196 The status of the link operation will be stored as part of the program
10197 object's state. This value will be set to @code{GL_TRUE} if the program
10198 object was linked without errors and is ready for use, and
10199 @code{GL_FALSE} otherwise. It can be queried by calling
10200 @code{glGetProgram} with arguments @var{program} and
10201 @code{GL_LINK_STATUS}.
10203 As a result of a successful link operation, all active user-defined
10204 uniform variables belonging to @var{program} will be initialized to 0,
10205 and each of the program object's active uniform variables will be
10206 assigned a location that can be queried by calling
10207 @code{glGetUniformLocation}. Also, any active user-defined attribute
10208 variables that have not been bound to a generic vertex attribute index
10209 will be bound to one at this time.
10211 Linking of a program object can fail for a number of reasons as
10212 specified in the @var{OpenGL Shading Language Specification}. The
10213 following lists some of the conditions that will cause a link error.
10217 The number of active attribute variables supported by the implementation
10221 The storage limit for uniform variables has been exceeded.
10224 The number of active uniform variables supported by the implementation
10228 The @code{main} function is missing for the vertex shader or the
10232 A varying variable actually used in the fragment shader is not declared
10233 in the same way (or is not declared at all) in the vertex shader.
10236 A reference to a function or variable name is unresolved.
10239 A shared global is declared with two different types or two different
10243 One or more of the attached shader objects has not been successfully
10247 Binding a generic attribute matrix caused some rows of the matrix to
10248 fall outside the allowed maximum of @code{GL_MAX_VERTEX_ATTRIBS}.
10251 Not enough contiguous vertex attribute slots could be found to bind
10252 attribute matrices.
10256 When a program object has been successfully linked, the program object
10257 can be made part of current state by calling @code{glUseProgram}.
10258 Whether or not the link operation was successful, the program object's
10259 information log will be overwritten. The information log can be
10260 retrieved by calling @code{glGetProgramInfoLog}.
10262 @code{glLinkProgram} will also install the generated executables as part
10263 of the current rendering state if the link operation was successful and
10264 the specified program object is already currently in use as a result of
10265 a previous call to @code{glUseProgram}. If the program object currently
10266 in use is relinked unsuccessfully, its link status will be set to
10267 @code{GL_FALSE} , but the executables and associated state will remain
10268 part of the current state until a subsequent call to @code{glUseProgram}
10269 removes it from use. After it is removed from use, it cannot be made
10270 part of current state until it has been successfully relinked.
10272 If @var{program} contains shader objects of type @code{GL_VERTEX_SHADER}
10273 but does not contain shader objects of type @code{GL_FRAGMENT_SHADER},
10274 the vertex shader will be linked against the implicit interface for
10275 fixed functionality fragment processing. Similarly, if @var{program}
10276 contains shader objects of type @code{GL_FRAGMENT_SHADER} but it does
10277 not contain shader objects of type @code{GL_VERTEX_SHADER}, the fragment
10278 shader will be linked against the implicit interface for fixed
10279 functionality vertex processing.
10281 The program object's information log is updated and the program is
10282 generated at the time of the link operation. After the link operation,
10283 applications are free to modify attached shader objects, compile
10284 attached shader objects, detach shader objects, delete shader objects,
10285 and attach additional shader objects. None of these operations affects
10286 the information log or the program that is part of the program object.
10288 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
10289 generated by OpenGL.
10291 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
10294 @code{GL_INVALID_OPERATION} is generated if @code{glLinkProgram} is
10295 executed between the execution of @code{glBegin} and the corresponding
10296 execution of @code{glEnd}.
10300 @deftypefun void glListBase base
10301 Set the display-list base for .
10305 Specifies an integer offset that will be added to @code{glCallLists}
10306 offsets to generate display-list names. The initial value is 0.
10310 @code{glCallLists} specifies an array of offsets. Display-list names are
10311 generated by adding @var{base} to each offset. Names that reference
10312 valid display lists are executed; the others are ignored.
10314 @code{GL_INVALID_OPERATION} is generated if @code{glListBase} is
10315 executed between the execution of @code{glBegin} and the corresponding
10316 execution of @code{glEnd}.
10320 @deftypefun void glLoadIdentity
10321 Replace the current matrix with the identity matrix.
10323 @code{glLoadIdentity} replaces the current matrix with the identity
10324 matrix. It is semantically equivalent to calling @code{glLoadMatrix}
10325 with the identity matrix
10329 @r{((1 0 0 0), (0 1 0 0), (0 0 1 0), (0 0 0 1),,)}
10333 but in some cases it is more efficient.
10335 @code{GL_INVALID_OPERATION} is generated if @code{glLoadIdentity} is
10336 executed between the execution of @code{glBegin} and the corresponding
10337 execution of @code{glEnd}.
10341 @deftypefun void glLoadMatrixf m
10342 Replace the current matrix with the specified matrix.
10346 Specifies a pointer to 16 consecutive values, which are used as the
10347 elements of a @r{4×4} column-major matrix.
10351 @code{glLoadMatrix} replaces the current matrix with the one whose
10352 elements are specified by @var{m}. The current matrix is the projection
10353 matrix, modelview matrix, or texture matrix, depending on the current
10354 matrix mode (see @code{glMatrixMode}).
10356 The current matrix, M, defines a transformation of coordinates. For
10357 instance, assume M refers to the modelview matrix. If
10358 @r{@var{v}=(@var{v}[0,],@var{v}[1,]@var{v}[2,]@var{v}[3,])} is the
10359 set of object coordinates of a vertex, and @var{m} points to an array of
10360 @r{16} single- or double-precision floating-point values
10361 @r{@var{m}=@{@var{m}[0,],@var{m}[1,]@var{...}@var{m}[15,]@}}, then
10362 the modelview transformation @r{@var{M}(@var{v},)} does the following:
10364 @r{@var{M}(@var{v},)=((@var{m}[0,] @var{m}[4,] @var{m}[8,]
10365 @var{m}[12,]), (@var{m}[1,] @var{m}[5,] @var{m}[9,] @var{m}[13,]),
10366 (@var{m}[2,] @var{m}[6,] @var{m}[10,] @var{m}[14,]), (@var{m}[3,]
10367 @var{m}[7,] @var{m}[11,] @var{m}[15,]),)×((@var{v}[0,]),
10368 (@var{v}[1,]), (@var{v}[2,]), (@var{v}[3,]),)}
10372 Projection and texture transformations are similarly defined.
10374 @code{GL_INVALID_OPERATION} is generated if @code{glLoadMatrix} is
10375 executed between the execution of @code{glBegin} and the corresponding
10376 execution of @code{glEnd}.
10380 @deftypefun void glLoadName name
10381 Load a name onto the name stack.
10385 Specifies a name that will replace the top value on the name stack.
10389 The name stack is used during selection mode to allow sets of rendering
10390 commands to be uniquely identified. It consists of an ordered set of
10391 unsigned integers and is initially empty.
10393 @code{glLoadName} causes @var{name} to replace the value on the top of
10396 The name stack is always empty while the render mode is not
10397 @code{GL_SELECT}. Calls to @code{glLoadName} while the render mode is
10398 not @code{GL_SELECT} are ignored.
10400 @code{GL_INVALID_OPERATION} is generated if @code{glLoadName} is called
10401 while the name stack is empty.
10403 @code{GL_INVALID_OPERATION} is generated if @code{glLoadName} is
10404 executed between the execution of @code{glBegin} and the corresponding
10405 execution of @code{glEnd}.
10409 @deftypefun void glLoadTransposeMatrixf m
10410 Replace the current matrix with the specified row-major ordered matrix.
10414 Specifies a pointer to 16 consecutive values, which are used as the
10415 elements of a @r{4×4} row-major matrix.
10419 @code{glLoadTransposeMatrix} replaces the current matrix with the one
10420 whose elements are specified by @var{m}. The current matrix is the
10421 projection matrix, modelview matrix, or texture matrix, depending on the
10422 current matrix mode (see @code{glMatrixMode}).
10424 The current matrix, M, defines a transformation of coordinates. For
10425 instance, assume M refers to the modelview matrix. If
10426 @r{@var{v}=(@var{v}[0,],@var{v}[1,]@var{v}[2,]@var{v}[3,])} is the
10427 set of object coordinates of a vertex, and @var{m} points to an array of
10428 @r{16} single- or double-precision floating-point values
10429 @r{@var{m}=@{@var{m}[0,],@var{m}[1,]@var{...}@var{m}[15,]@}}, then
10430 the modelview transformation @r{@var{M}(@var{v},)} does the following:
10432 @r{@var{M}(@var{v},)=((@var{m}[0,] @var{m}[1,] @var{m}[2,]
10433 @var{m}[3,]), (@var{m}[4,] @var{m}[5,] @var{m}[6,] @var{m}[7,]),
10434 (@var{m}[8,] @var{m}[9,] @var{m}[10,] @var{m}[11,]), (@var{m}[12,]
10435 @var{m}[13,] @var{m}[14,] @var{m}[15,]),)×((@var{v}[0,]),
10436 (@var{v}[1,]), (@var{v}[2,]), (@var{v}[3,]),)}
10440 Projection and texture transformations are similarly defined.
10442 Calling @code{glLoadTransposeMatrix} with matrix @r{@var{M}} is
10443 identical in operation to @code{glLoadMatrix} with @r{@var{M}^@var{T}},
10444 where @r{@var{T}} represents the transpose.
10446 @code{GL_INVALID_OPERATION} is generated if @code{glLoadTransposeMatrix}
10447 is executed between the execution of @code{glBegin} and the
10448 corresponding execution of @code{glEnd}.
10452 @deftypefun void glLogicOp opcode
10453 Specify a logical pixel operation for color index rendering.
10457 Specifies a symbolic constant that selects a logical operation. The
10458 following symbols are accepted: @code{GL_CLEAR}, @code{GL_SET},
10459 @code{GL_COPY}, @code{GL_COPY_INVERTED}, @code{GL_NOOP},
10460 @code{GL_INVERT}, @code{GL_AND}, @code{GL_NAND}, @code{GL_OR},
10461 @code{GL_NOR}, @code{GL_XOR}, @code{GL_EQUIV}, @code{GL_AND_REVERSE},
10462 @code{GL_AND_INVERTED}, @code{GL_OR_REVERSE}, and @code{GL_OR_INVERTED}.
10463 The initial value is @code{GL_COPY}.
10467 @code{glLogicOp} specifies a logical operation that, when enabled, is
10468 applied between the incoming color index or RGBA color and the color
10469 index or RGBA color at the corresponding location in the frame buffer.
10470 To enable or disable the logical operation, call @code{glEnable} and
10471 @code{glDisable} using the symbolic constant @code{GL_COLOR_LOGIC_OP}
10472 for RGBA mode or @code{GL_INDEX_LOGIC_OP} for color index mode. The
10473 initial value is disabled for both operations.
10478 @item @strong{Opcode}
10479 @strong{Resulting Operation}
10481 @item @code{GL_CLEAR}
10484 @item @code{GL_SET}
10487 @item @code{GL_COPY}
10490 @item @code{GL_COPY_INVERTED}
10493 @item @code{GL_NOOP}
10496 @item @code{GL_INVERT}
10499 @item @code{GL_AND}
10502 @item @code{GL_NAND}
10508 @item @code{GL_NOR}
10511 @item @code{GL_XOR}
10514 @item @code{GL_EQUIV}
10517 @item @code{GL_AND_REVERSE}
10520 @item @code{GL_AND_INVERTED}
10523 @item @code{GL_OR_REVERSE}
10526 @item @code{GL_OR_INVERTED}
10531 @var{opcode} is a symbolic constant chosen from the list above. In the
10532 explanation of the logical operations, @var{s} represents the incoming
10533 color index and @var{d} represents the index in the frame buffer.
10534 Standard C-language operators are used. As these bitwise operators
10535 suggest, the logical operation is applied independently to each bit pair
10536 of the source and destination indices or colors.
10538 @code{GL_INVALID_ENUM} is generated if @var{opcode} is not an accepted
10541 @code{GL_INVALID_OPERATION} is generated if @code{glLogicOp} is executed
10542 between the execution of @code{glBegin} and the corresponding execution
10547 @deftypefun void glMap1f target u1 u2 stride order points
10548 Define a one-dimensional evaluator.
10552 Specifies the kind of values that are generated by the evaluator.
10553 Symbolic constants @code{GL_MAP1_VERTEX_3}, @code{GL_MAP1_VERTEX_4},
10554 @code{GL_MAP1_INDEX}, @code{GL_MAP1_COLOR_4}, @code{GL_MAP1_NORMAL},
10555 @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2},
10556 @code{GL_MAP1_TEXTURE_COORD_3}, and @code{GL_MAP1_TEXTURE_COORD_4} are
10561 Specify a linear mapping of @r{@var{u}}, as presented to
10562 @code{glEvalCoord1}, to @r{@var{u}^}, the variable that is evaluated by
10563 the equations specified by this command.
10566 Specifies the number of floats or doubles between the beginning of one
10567 control point and the beginning of the next one in the data structure
10568 referenced in @var{points}. This allows control points to be embedded in
10569 arbitrary data structures. The only constraint is that the values for a
10570 particular control point must occupy contiguous memory locations.
10573 Specifies the number of control points. Must be positive.
10576 Specifies a pointer to the array of control points.
10580 Evaluators provide a way to use polynomial or rational polynomial
10581 mapping to produce vertices, normals, texture coordinates, and colors.
10582 The values produced by an evaluator are sent to further stages of GL
10583 processing just as if they had been presented using @code{glVertex},
10584 @code{glNormal}, @code{glTexCoord}, and @code{glColor} commands, except
10585 that the generated values do not update the current normal, texture
10586 coordinates, or color.
10588 All polynomial or rational polynomial splines of any degree (up to the
10589 maximum degree supported by the GL implementation) can be described
10590 using evaluators. These include almost all splines used in computer
10591 graphics: B-splines, Bezier curves, Hermite splines, and so on.
10593 Evaluators define curves based on Bernstein polynomials. Define
10594 @r{@var{p}(@var{u}^,)} as
10596 @r{@var{p}(@var{u}^,)=Σ@var{i}=0@var{n}@var{B}_@var{i},^@var{n}(@var{u}^,)@var{R}_@var{i}}
10600 where @r{@var{R}_@var{i}} is a control point and
10601 @r{@var{B}_@var{i},^@var{n}(@var{u}^,)} is the @r{@var{i}}th Bernstein
10602 polynomial of degree @r{@var{n}} (@var{order} = @r{@var{n}+1}):
10604 @r{@var{B}_@var{i},^@var{n}(@var{u}^,)=((@var{n}),
10605 (@var{i}),,)@var{u}^,^@var{i}(1-@var{u}^,)^@var{n}-@var{i},,}
10609 @r{0^0==1} and @r{((@var{n}), (0),,)==1}
10611 @code{glMap1} is used to define the basis and to specify what kind of
10612 values are produced. Once defined, a map can be enabled and disabled by
10613 calling @code{glEnable} and @code{glDisable} with the map name, one of
10614 the nine predefined values for @var{target} described below.
10615 @code{glEvalCoord1} evaluates the one-dimensional maps that are enabled.
10616 When @code{glEvalCoord1} presents a value @r{@var{u}}, the Bernstein
10617 functions are evaluated using @r{@var{u}^}, where
10618 @r{@var{u}^=@var{u}-@var{u1},/@var{u2}-@var{u1},}
10620 @var{target} is a symbolic constant that indicates what kind of control
10621 points are provided in @var{points}, and what output is generated when
10622 the map is evaluated. It can assume one of nine predefined values:
10625 @item @code{GL_MAP1_VERTEX_3}
10626 Each control point is three floating-point values representing
10627 @r{@var{x}}, @r{@var{y}}, and @r{@var{z}}. Internal @code{glVertex3}
10628 commands are generated when the map is evaluated.
10630 @item @code{GL_MAP1_VERTEX_4}
10631 Each control point is four floating-point values representing
10632 @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}. Internal
10633 @code{glVertex4} commands are generated when the map is evaluated.
10635 @item @code{GL_MAP1_INDEX}
10636 Each control point is a single floating-point value representing a color
10637 index. Internal @code{glIndex} commands are generated when the map is
10638 evaluated but the current index is not updated with the value of these
10639 @code{glIndex} commands.
10641 @item @code{GL_MAP1_COLOR_4}
10642 Each control point is four floating-point values representing red,
10643 green, blue, and alpha. Internal @code{glColor4} commands are generated
10644 when the map is evaluated but the current color is not updated with the
10645 value of these @code{glColor4} commands.
10647 @item @code{GL_MAP1_NORMAL}
10648 Each control point is three floating-point values representing the
10649 @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} components of a normal vector.
10650 Internal @code{glNormal} commands are generated when the map is
10651 evaluated but the current normal is not updated with the value of these
10652 @code{glNormal} commands.
10654 @item @code{GL_MAP1_TEXTURE_COORD_1}
10655 Each control point is a single floating-point value representing the
10656 @r{@var{s}} texture coordinate. Internal @code{glTexCoord1} commands are
10657 generated when the map is evaluated but the current texture coordinates
10658 are not updated with the value of these @code{glTexCoord} commands.
10660 @item @code{GL_MAP1_TEXTURE_COORD_2}
10661 Each control point is two floating-point values representing the
10662 @r{@var{s}} and @r{@var{t}} texture coordinates. Internal
10663 @code{glTexCoord2} commands are generated when the map is evaluated but
10664 the current texture coordinates are not updated with the value of these
10665 @code{glTexCoord} commands.
10667 @item @code{GL_MAP1_TEXTURE_COORD_3}
10668 Each control point is three floating-point values representing the
10669 @r{@var{s}}, @r{@var{t}}, and @r{@var{r}} texture coordinates. Internal
10670 @code{glTexCoord3} commands are generated when the map is evaluated but
10671 the current texture coordinates are not updated with the value of these
10672 @code{glTexCoord} commands.
10674 @item @code{GL_MAP1_TEXTURE_COORD_4}
10675 Each control point is four floating-point values representing the
10676 @r{@var{s}}, @r{@var{t}}, @r{@var{r}}, and @r{@var{q}} texture
10677 coordinates. Internal @code{glTexCoord4} commands are generated when the
10678 map is evaluated but the current texture coordinates are not updated
10679 with the value of these @code{glTexCoord} commands.
10683 @var{stride}, @var{order}, and @var{points} define the array addressing
10684 for accessing the control points. @var{points} is the location of the
10685 first control point, which occupies one, two, three, or four contiguous
10686 memory locations, depending on which map is being defined. @var{order}
10687 is the number of control points in the array. @var{stride} specifies how
10688 many float or double locations to advance the internal memory pointer to
10689 reach the next control point.
10691 @code{GL_INVALID_ENUM} is generated if @var{target} is not an accepted
10694 @code{GL_INVALID_VALUE} is generated if @var{u1} is equal to @var{u2}.
10696 @code{GL_INVALID_VALUE} is generated if @var{stride} is less than the
10697 number of values in a control point.
10699 @code{GL_INVALID_VALUE} is generated if @var{order} is less than 1 or
10700 greater than the return value of @code{GL_MAX_EVAL_ORDER}.
10702 @code{GL_INVALID_OPERATION} is generated if @code{glMap1} is executed
10703 between the execution of @code{glBegin} and the corresponding execution
10706 @code{GL_INVALID_OPERATION} is generated if @code{glMap1} is called and
10707 the value of @code{GL_ACTIVE_TEXTURE} is not @code{GL_TEXTURE0}.
10711 @deftypefun void glMap2f target u1 u2 ustride uorder v1 v2 vstride vorder points
10712 Define a two-dimensional evaluator.
10716 Specifies the kind of values that are generated by the evaluator.
10717 Symbolic constants @code{GL_MAP2_VERTEX_3}, @code{GL_MAP2_VERTEX_4},
10718 @code{GL_MAP2_INDEX}, @code{GL_MAP2_COLOR_4}, @code{GL_MAP2_NORMAL},
10719 @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2},
10720 @code{GL_MAP2_TEXTURE_COORD_3}, and @code{GL_MAP2_TEXTURE_COORD_4} are
10725 Specify a linear mapping of @r{@var{u}}, as presented to
10726 @code{glEvalCoord2}, to @r{@var{u}^}, one of the two variables that are
10727 evaluated by the equations specified by this command. Initially,
10728 @var{u1} is 0 and @var{u2} is 1.
10730 @item @var{ustride}
10731 Specifies the number of floats or doubles between the beginning of
10732 control point @r{@var{R}_@var{ij}} and the beginning of control point
10733 @r{@var{R}_(@var{i}+1,)@var{j},}, where @r{@var{i}} and @r{@var{j}} are
10734 the @r{@var{u}} and @r{@var{v}} control point indices, respectively.
10735 This allows control points to be embedded in arbitrary data structures.
10736 The only constraint is that the values for a particular control point
10737 must occupy contiguous memory locations. The initial value of
10738 @var{ustride} is 0.
10741 Specifies the dimension of the control point array in the @r{@var{u}}
10742 axis. Must be positive. The initial value is 1.
10746 Specify a linear mapping of @r{@var{v}}, as presented to
10747 @code{glEvalCoord2}, to @r{@var{v}^}, one of the two variables that are
10748 evaluated by the equations specified by this command. Initially,
10749 @var{v1} is 0 and @var{v2} is 1.
10751 @item @var{vstride}
10752 Specifies the number of floats or doubles between the beginning of
10753 control point @r{@var{R}_@var{ij}} and the beginning of control point
10754 @r{@var{R}_@var{i}(@var{j}+1,),}, where @r{@var{i}} and @r{@var{j}} are
10755 the @r{@var{u}} and @r{@var{v}} control point indices, respectively.
10756 This allows control points to be embedded in arbitrary data structures.
10757 The only constraint is that the values for a particular control point
10758 must occupy contiguous memory locations. The initial value of
10759 @var{vstride} is 0.
10762 Specifies the dimension of the control point array in the @r{@var{v}}
10763 axis. Must be positive. The initial value is 1.
10766 Specifies a pointer to the array of control points.
10770 Evaluators provide a way to use polynomial or rational polynomial
10771 mapping to produce vertices, normals, texture coordinates, and colors.
10772 The values produced by an evaluator are sent on to further stages of GL
10773 processing just as if they had been presented using @code{glVertex},
10774 @code{glNormal}, @code{glTexCoord}, and @code{glColor} commands, except
10775 that the generated values do not update the current normal, texture
10776 coordinates, or color.
10778 All polynomial or rational polynomial splines of any degree (up to the
10779 maximum degree supported by the GL implementation) can be described
10780 using evaluators. These include almost all surfaces used in computer
10781 graphics, including B-spline surfaces, NURBS surfaces, Bezier surfaces,
10784 Evaluators define surfaces based on bivariate Bernstein polynomials.
10785 Define @r{@var{p}(@var{u}^,@var{v}^)} as
10787 @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}}
10791 where @r{@var{R}_@var{ij}} is a control point,
10792 @r{@var{B}_@var{i},^@var{n}(@var{u}^,)} is the @r{@var{i}}th Bernstein
10793 polynomial of degree @r{@var{n}} (@var{uorder} = @r{@var{n}+1})
10795 @r{@var{B}_@var{i},^@var{n}(@var{u}^,)=((@var{n}),
10796 (@var{i}),,)@var{u}^,^@var{i}(1-@var{u}^,)^@var{n}-@var{i},,}
10798 and @r{@var{B}_@var{j},^@var{m}(@var{v}^,)} is the @r{@var{j}}th
10799 Bernstein polynomial of degree @r{@var{m}} (@var{vorder} =
10802 @r{@var{B}_@var{j},^@var{m}(@var{v}^,)=((@var{m}),
10803 (@var{j}),,)@var{v}^,^@var{j}(1-@var{v}^,)^@var{m}-@var{j},,}
10805 Recall that @r{0^0==1} and @r{((@var{n}), (0),,)==1}
10807 @code{glMap2} is used to define the basis and to specify what kind of
10808 values are produced. Once defined, a map can be enabled and disabled by
10809 calling @code{glEnable} and @code{glDisable} with the map name, one of
10810 the nine predefined values for @var{target}, described below. When
10811 @code{glEvalCoord2} presents values @r{@var{u}} and @r{@var{v}}, the
10812 bivariate Bernstein polynomials are evaluated using @r{@var{u}^} and
10813 @r{@var{v}^}, where
10815 @r{@var{u}^=@var{u}-@var{u1},/@var{u2}-@var{u1},}
10817 @r{@var{v}^=@var{v}-@var{v1},/@var{v2}-@var{v1},}
10819 @var{target} is a symbolic constant that indicates what kind of control
10820 points are provided in @var{points}, and what output is generated when
10821 the map is evaluated. It can assume one of nine predefined values:
10824 @item @code{GL_MAP2_VERTEX_3}
10825 Each control point is three floating-point values representing
10826 @r{@var{x}}, @r{@var{y}}, and @r{@var{z}}. Internal @code{glVertex3}
10827 commands are generated when the map is evaluated.
10829 @item @code{GL_MAP2_VERTEX_4}
10830 Each control point is four floating-point values representing
10831 @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}. Internal
10832 @code{glVertex4} commands are generated when the map is evaluated.
10834 @item @code{GL_MAP2_INDEX}
10835 Each control point is a single floating-point value representing a color
10836 index. Internal @code{glIndex} commands are generated when the map is
10837 evaluated but the current index is not updated with the value of these
10838 @code{glIndex} commands.
10840 @item @code{GL_MAP2_COLOR_4}
10841 Each control point is four floating-point values representing red,
10842 green, blue, and alpha. Internal @code{glColor4} commands are generated
10843 when the map is evaluated but the current color is not updated with the
10844 value of these @code{glColor4} commands.
10846 @item @code{GL_MAP2_NORMAL}
10847 Each control point is three floating-point values representing the
10848 @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} components of a normal vector.
10849 Internal @code{glNormal} commands are generated when the map is
10850 evaluated but the current normal is not updated with the value of these
10851 @code{glNormal} commands.
10853 @item @code{GL_MAP2_TEXTURE_COORD_1}
10854 Each control point is a single floating-point value representing the
10855 @r{@var{s}} texture coordinate. Internal @code{glTexCoord1} commands are
10856 generated when the map is evaluated but the current texture coordinates
10857 are not updated with the value of these @code{glTexCoord} commands.
10859 @item @code{GL_MAP2_TEXTURE_COORD_2}
10860 Each control point is two floating-point values representing the
10861 @r{@var{s}} and @r{@var{t}} texture coordinates. Internal
10862 @code{glTexCoord2} commands are generated when the map is evaluated but
10863 the current texture coordinates are not updated with the value of these
10864 @code{glTexCoord} commands.
10866 @item @code{GL_MAP2_TEXTURE_COORD_3}
10867 Each control point is three floating-point values representing the
10868 @r{@var{s}}, @r{@var{t}}, and @r{@var{r}} texture coordinates. Internal
10869 @code{glTexCoord3} commands are generated when the map is evaluated but
10870 the current texture coordinates are not updated with the value of these
10871 @code{glTexCoord} commands.
10873 @item @code{GL_MAP2_TEXTURE_COORD_4}
10874 Each control point is four floating-point values representing the
10875 @r{@var{s}}, @r{@var{t}}, @r{@var{r}}, and @r{@var{q}} texture
10876 coordinates. Internal @code{glTexCoord4} commands are generated when the
10877 map is evaluated but the current texture coordinates are not updated
10878 with the value of these @code{glTexCoord} commands.
10882 @var{ustride}, @var{uorder}, @var{vstride}, @var{vorder}, and
10883 @var{points} define the array addressing for accessing the control
10884 points. @var{points} is the location of the first control point, which
10885 occupies one, two, three, or four contiguous memory locations, depending
10886 on which map is being defined. There are @r{@var{uorder}×@var{vorder}}
10887 control points in the array. @var{ustride} specifies how many float or
10888 double locations are skipped to advance the internal memory pointer from
10889 control point @r{@var{R}_@var{i}@var{j},} to control point
10890 @r{@var{R}_(@var{i}+1,)@var{j},}. @var{vstride} specifies how many
10891 float or double locations are skipped to advance the internal memory
10892 pointer from control point @r{@var{R}_@var{i}@var{j},} to control point
10893 @r{@var{R}_@var{i}(@var{j}+1,),}.
10895 @code{GL_INVALID_ENUM} is generated if @var{target} is not an accepted
10898 @code{GL_INVALID_VALUE} is generated if @var{u1} is equal to @var{u2},
10899 or if @var{v1} is equal to @var{v2}.
10901 @code{GL_INVALID_VALUE} is generated if either @var{ustride} or
10902 @var{vstride} is less than the number of values in a control point.
10904 @code{GL_INVALID_VALUE} is generated if either @var{uorder} or
10905 @var{vorder} is less than 1 or greater than the return value of
10906 @code{GL_MAX_EVAL_ORDER}.
10908 @code{GL_INVALID_OPERATION} is generated if @code{glMap2} is executed
10909 between the execution of @code{glBegin} and the corresponding execution
10912 @code{GL_INVALID_OPERATION} is generated if @code{glMap2} is called and
10913 the value of @code{GL_ACTIVE_TEXTURE} is not @code{GL_TEXTURE0}.
10917 @deftypefun void-* glMapBuffer target access
10918 @deftypefunx GLboolean glUnmapBuffer target
10919 Map a buffer object's data store.
10923 Specifies the target buffer object being mapped. The symbolic constant
10924 must be @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
10925 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
10928 Specifies the access policy, indicating whether it will be possible to
10929 read from, write to, or both read from and write to the buffer object's
10930 mapped data store. The symbolic constant must be @code{GL_READ_ONLY},
10931 @code{GL_WRITE_ONLY}, or @code{GL_READ_WRITE}.
10935 @code{glMapBuffer} maps to the client's address space the entire data
10936 store of the buffer object currently bound to @var{target}. The data can
10937 then be directly read and/or written relative to the returned pointer,
10938 depending on the specified @var{access} policy. If the GL is unable to
10939 map the buffer object's data store, @code{glMapBuffer} generates an
10940 error and returns @code{NULL}. This may occur for system-specific
10941 reasons, such as low virtual memory availability.
10943 If a mapped data store is accessed in a way inconsistent with the
10944 specified @var{access} policy, no error is generated, but performance
10945 may be negatively impacted and system errors, including program
10946 termination, may result. Unlike the @var{usage} parameter of
10947 @code{glBufferData}, @var{access} is not a hint, and does in fact
10948 constrain the usage of the mapped data store on some GL implementations.
10949 In order to achieve the highest performance available, a buffer object's
10950 data store should be used in ways consistent with both its specified
10951 @var{usage} and @var{access} parameters.
10953 A mapped data store must be unmapped with @code{glUnmapBuffer} before
10954 its buffer object is used. Otherwise an error will be generated by any
10955 GL command that attempts to dereference the buffer object's data store.
10956 When a data store is unmapped, the pointer to its data store becomes
10957 invalid. @code{glUnmapBuffer} returns @code{GL_TRUE} unless the data
10958 store contents have become corrupt during the time the data store was
10959 mapped. This can occur for system-specific reasons that affect the
10960 availability of graphics memory, such as screen mode changes. In such
10961 situations, @code{GL_FALSE} is returned and the data store contents are
10962 undefined. An application must detect this rare condition and
10963 reinitialize the data store.
10965 A buffer object's mapped data store is automatically unmapped when the
10966 buffer object is deleted or its data store is recreated with
10967 @code{glBufferData}.
10969 @code{GL_INVALID_ENUM} is generated if @var{target} is not
10970 @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER},
10971 @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}.
10973 @code{GL_INVALID_ENUM} is generated if @var{access} is not
10974 @code{GL_READ_ONLY}, @code{GL_WRITE_ONLY}, or @code{GL_READ_WRITE}.
10976 @code{GL_OUT_OF_MEMORY} is generated when @code{glMapBuffer} is executed
10977 if the GL is unable to map the buffer object's data store. This may
10978 occur for a variety of system-specific reasons, such as the absence of
10979 sufficient remaining virtual memory.
10981 @code{GL_INVALID_OPERATION} is generated if the reserved buffer object
10982 name 0 is bound to @var{target}.
10984 @code{GL_INVALID_OPERATION} is generated if @code{glMapBuffer} is
10985 executed for a buffer object whose data store is already mapped.
10987 @code{GL_INVALID_OPERATION} is generated if @code{glUnmapBuffer} is
10988 executed for a buffer object whose data store is not currently mapped.
10990 @code{GL_INVALID_OPERATION} is generated if @code{glMapBuffer} or
10991 @code{glUnmapBuffer} is executed between the execution of @code{glBegin}
10992 and the corresponding execution of @code{glEnd}.
10996 @deftypefun void glMapGrid1f un u1 u2
10997 @deftypefunx void glMapGrid2f un u1 u2 vn v1 v2
10998 Define a one- or two-dimensional mesh.
11002 Specifies the number of partitions in the grid range interval [@var{u1},
11003 @var{u2}]. Must be positive.
11007 Specify the mappings for integer grid domain values @r{@var{i}=0} and
11008 @r{@var{i}=@var{un}}.
11011 Specifies the number of partitions in the grid range interval [@var{v1},
11012 @var{v2}] (@code{glMapGrid2} only).
11016 Specify the mappings for integer grid domain values @r{@var{j}=0} and
11017 @r{@var{j}=@var{vn}} (@code{glMapGrid2} only).
11021 @code{glMapGrid} and @code{glEvalMesh} are used together to efficiently
11022 generate and evaluate a series of evenly-spaced map domain values.
11023 @code{glEvalMesh} steps through the integer domain of a one- or
11024 two-dimensional grid, whose range is the domain of the evaluation maps
11025 specified by @code{glMap1} and @code{glMap2}.
11027 @code{glMapGrid1} and @code{glMapGrid2} specify the linear grid mappings
11028 between the @r{@var{i}} (or @r{@var{i}} and @r{@var{j}}) integer grid
11029 coordinates, to the @r{@var{u}} (or @r{@var{u}} and @r{@var{v}})
11030 floating-point evaluation map coordinates. See @code{glMap1} and
11031 @code{glMap2} for details of how @r{@var{u}} and @r{@var{v}} coordinates
11034 @code{glMapGrid1} specifies a single linear mapping such that integer
11035 grid coordinate 0 maps exactly to @var{u1}, and integer grid coordinate
11036 @var{un} maps exactly to @var{u2}. All other integer grid coordinates
11037 @r{@var{i}} are mapped so that
11039 @r{@var{u}=@var{i}(@var{u2}-@var{u1},)/@var{un}+@var{u1}}
11041 @code{glMapGrid2} specifies two such linear mappings. One maps integer
11042 grid coordinate @r{@var{i}=0} exactly to @var{u1}, and integer grid
11043 coordinate @r{@var{i}=@var{un}} exactly to @var{u2}. The other maps
11044 integer grid coordinate @r{@var{j}=0} exactly to @var{v1}, and integer
11045 grid coordinate @r{@var{j}=@var{vn}} exactly to @var{v2}. Other integer
11046 grid coordinates @r{@var{i}} and @r{@var{j}} are mapped such that
11048 @r{@var{u}=@var{i}(@var{u2}-@var{u1},)/@var{un}+@var{u1}}
11050 @r{@var{v}=@var{j}(@var{v2}-@var{v1},)/@var{vn}+@var{v1}}
11052 The mappings specified by @code{glMapGrid} are used identically by
11053 @code{glEvalMesh} and @code{glEvalPoint}.
11055 @code{GL_INVALID_VALUE} is generated if either @var{un} or @var{vn} is
11058 @code{GL_INVALID_OPERATION} is generated if @code{glMapGrid} is executed
11059 between the execution of @code{glBegin} and the corresponding execution
11064 @deftypefun void glMaterialf face pname param
11065 @deftypefunx void glMateriali face pname param
11066 Specify material parameters for the lighting model.
11070 Specifies which face or faces are being updated. Must be one of
11071 @code{GL_FRONT}, @code{GL_BACK}, or @code{GL_FRONT_AND_BACK}.
11074 Specifies the single-valued material parameter of the face or faces that
11075 is being updated. Must be @code{GL_SHININESS}.
11078 Specifies the value that parameter @code{GL_SHININESS} will be set to.
11082 @code{glMaterial} assigns values to material parameters. There are two
11083 matched sets of material parameters. One, the @var{front-facing} set, is
11084 used to shade points, lines, bitmaps, and all polygons (when two-sided
11085 lighting is disabled), or just front-facing polygons (when two-sided
11086 lighting is enabled). The other set, @var{back-facing}, is used to shade
11087 back-facing polygons only when two-sided lighting is enabled. Refer to
11088 the @code{glLightModel} reference page for details concerning one- and
11089 two-sided lighting calculations.
11091 @code{glMaterial} takes three arguments. The first, @var{face},
11092 specifies whether the @code{GL_FRONT} materials, the @code{GL_BACK}
11093 materials, or both @code{GL_FRONT_AND_BACK} materials will be modified.
11094 The second, @var{pname}, specifies which of several parameters in one or
11095 both sets will be modified. The third, @var{params}, specifies what
11096 value or values will be assigned to the specified parameter.
11098 Material parameters are used in the lighting equation that is optionally
11099 applied to each vertex. The equation is discussed in the
11100 @code{glLightModel} reference page. The parameters that can be specified
11101 using @code{glMaterial}, and their interpretations by the lighting
11102 equation, are as follows:
11105 @item @code{GL_AMBIENT}
11106 @var{params} contains four integer or floating-point values that specify
11107 the ambient RGBA reflectance of the material. Integer values are mapped
11108 linearly such that the most positive representable value maps to 1.0,
11109 and the most negative representable value maps to @r{-1.0}.
11110 Floating-point values are mapped directly. Neither integer nor
11111 floating-point values are clamped. The initial ambient reflectance for
11112 both front- and back-facing materials is (0.2, 0.2, 0.2, 1.0).
11114 @item @code{GL_DIFFUSE}
11115 @var{params} contains four integer or floating-point values that specify
11116 the diffuse RGBA reflectance of the material. Integer values are mapped
11117 linearly such that the most positive representable value maps to 1.0,
11118 and the most negative representable value maps to @r{-1.0}.
11119 Floating-point values are mapped directly. Neither integer nor
11120 floating-point values are clamped. The initial diffuse reflectance for
11121 both front- and back-facing materials is (0.8, 0.8, 0.8, 1.0).
11123 @item @code{GL_SPECULAR}
11124 @var{params} contains four integer or floating-point values that specify
11125 the specular RGBA reflectance of the material. Integer values are mapped
11126 linearly such that the most positive representable value maps to 1.0,
11127 and the most negative representable value maps to @r{-1.0}.
11128 Floating-point values are mapped directly. Neither integer nor
11129 floating-point values are clamped. The initial specular reflectance for
11130 both front- and back-facing materials is (0, 0, 0, 1).
11132 @item @code{GL_EMISSION}
11133 @var{params} contains four integer or floating-point values that specify
11134 the RGBA emitted light intensity of the material. Integer values are
11135 mapped linearly such that the most positive representable value maps to
11136 1.0, and the most negative representable value maps to @r{-1.0}.
11137 Floating-point values are mapped directly. Neither integer nor
11138 floating-point values are clamped. The initial emission intensity for
11139 both front- and back-facing materials is (0, 0, 0, 1).
11141 @item @code{GL_SHININESS}
11142 @var{params} is a single integer or floating-point value that specifies
11143 the RGBA specular exponent of the material. Integer and floating-point
11144 values are mapped directly. Only values in the range @r{[0,128]} are
11145 accepted. The initial specular exponent for both front- and back-facing
11148 @item @code{GL_AMBIENT_AND_DIFFUSE}
11149 Equivalent to calling @code{glMaterial} twice with the same parameter
11150 values, once with @code{GL_AMBIENT} and once with @code{GL_DIFFUSE}.
11152 @item @code{GL_COLOR_INDEXES}
11153 @var{params} contains three integer or floating-point values specifying
11154 the color indices for ambient, diffuse, and specular lighting. These
11155 three values, and @code{GL_SHININESS}, are the only material values used
11156 by the color index mode lighting equation. Refer to the
11157 @code{glLightModel} reference page for a discussion of color index
11162 @code{GL_INVALID_ENUM} is generated if either @var{face} or @var{pname}
11163 is not an accepted value.
11165 @code{GL_INVALID_VALUE} is generated if a specular exponent outside the
11166 range @r{[0,128]} is specified.
11170 @deftypefun void glMatrixMode mode
11171 Specify which matrix is the current matrix.
11175 Specifies which matrix stack is the target for subsequent matrix
11176 operations. Three values are accepted: @code{GL_MODELVIEW},
11177 @code{GL_PROJECTION}, and @code{GL_TEXTURE}. The initial value is
11178 @code{GL_MODELVIEW}. Additionally, if the @code{ARB_imaging} extension
11179 is supported, @code{GL_COLOR} is also accepted.
11183 @code{glMatrixMode} sets the current matrix mode. @var{mode} can assume
11184 one of four values:
11187 @item @code{GL_MODELVIEW}
11188 Applies subsequent matrix operations to the modelview matrix stack.
11190 @item @code{GL_PROJECTION}
11191 Applies subsequent matrix operations to the projection matrix stack.
11193 @item @code{GL_TEXTURE}
11194 Applies subsequent matrix operations to the texture matrix stack.
11196 @item @code{GL_COLOR}
11197 Applies subsequent matrix operations to the color matrix stack.
11201 To find out which matrix stack is currently the target of all matrix
11202 operations, call @code{glGet} with argument @code{GL_MATRIX_MODE}. The
11203 initial value is @code{GL_MODELVIEW}.
11205 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
11208 @code{GL_INVALID_OPERATION} is generated if @code{glMatrixMode} is
11209 executed between the execution of @code{glBegin} and the corresponding
11210 execution of @code{glEnd}.
11214 @deftypefun void glMinmax target internalformat sink
11215 Define minmax table.
11219 The minmax table whose parameters are to be set. Must be
11222 @item @var{internalformat}
11223 The format of entries in the minmax table. Must be one of
11224 @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
11225 @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
11226 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
11227 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
11228 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
11229 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
11230 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
11231 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
11232 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
11233 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
11234 @code{GL_RGBA12}, or @code{GL_RGBA16}.
11237 If @code{GL_TRUE}, pixels will be consumed by the minmax process and no
11238 drawing or texture loading will take place. If @code{GL_FALSE}, pixels
11239 will proceed to the final conversion process after minmax.
11243 When @code{GL_MINMAX} is enabled, the RGBA components of incoming pixels
11244 are compared to the minimum and maximum values for each component, which
11245 are stored in the two-element minmax table. (The first element stores
11246 the minima, and the second element stores the maxima.) If a pixel
11247 component is greater than the corresponding component in the maximum
11248 element, then the maximum element is updated with the pixel component
11249 value. If a pixel component is less than the corresponding component in
11250 the minimum element, then the minimum element is updated with the pixel
11251 component value. (In both cases, if the internal format of the minmax
11252 table includes luminance, then the R color component of incoming pixels
11253 is used for comparison.) The contents of the minmax table may be
11254 retrieved at a later time by calling @code{glGetMinmax}. The minmax
11255 operation is enabled or disabled by calling @code{glEnable} or
11256 @code{glDisable}, respectively, with an argument of @code{GL_MINMAX}.
11258 @code{glMinmax} redefines the current minmax table to have entries of
11259 the format specified by @var{internalformat}. The maximum element is
11260 initialized with the smallest possible component values, and the minimum
11261 element is initialized with the largest possible component values. The
11262 values in the previous minmax table, if any, are lost. If @var{sink} is
11263 @code{GL_TRUE}, then pixels are discarded after minmax; no further
11264 processing of the pixels takes place, and no drawing, texture loading,
11265 or pixel readback will result.
11269 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
11272 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
11273 of the allowable values.
11275 @code{GL_INVALID_OPERATION} is generated if @code{glMinmax} is executed
11276 between the execution of @code{glBegin} and the corresponding execution
11281 @deftypefun void glMultiDrawArrays mode first count primcount
11282 Render multiple sets of primitives from array data.
11286 Specifies what kind of primitives to render. Symbolic constants
11287 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
11288 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
11289 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
11290 @code{GL_POLYGON} are accepted.
11293 Points to an array of starting indices in the enabled arrays.
11296 Points to an array of the number of indices to be rendered.
11298 @item @var{primcount}
11299 Specifies the size of the first and count
11303 @code{glMultiDrawArrays} specifies multiple sets of geometric primitives
11304 with very few subroutine calls. Instead of calling a GL procedure to
11305 pass each individual vertex, normal, texture coordinate, edge flag, or
11306 color, you can prespecify separate arrays of vertices, normals, and
11307 colors and use them to construct a sequence of primitives with a single
11308 call to @code{glMultiDrawArrays}.
11310 @code{glMultiDrawArrays} behaves identically to @code{glDrawArrays}
11311 except that @var{primcount} separate ranges of elements are specified
11314 When @code{glMultiDrawArrays} is called, it uses @var{count} sequential
11315 elements from each enabled array to construct a sequence of geometric
11316 primitives, beginning with element @var{first}. @var{mode} specifies
11317 what kind of primitives are constructed, and how the array elements
11318 construct those primitives. If @code{GL_VERTEX_ARRAY} is not enabled, no
11319 geometric primitives are generated.
11321 Vertex attributes that are modified by @code{glMultiDrawArrays} have an
11322 unspecified value after @code{glMultiDrawArrays} returns. For example,
11323 if @code{GL_COLOR_ARRAY} is enabled, the value of the current color is
11324 undefined after @code{glMultiDrawArrays} executes. Attributes that
11325 aren't modified remain well defined.
11327 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
11330 @code{GL_INVALID_VALUE} is generated if @var{primcount} is negative.
11332 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
11333 name is bound to an enabled array and the buffer object's data store is
11336 @code{GL_INVALID_OPERATION} is generated if @code{glMultiDrawArrays} is
11337 executed between the execution of @code{glBegin} and the corresponding
11342 @deftypefun void glMultiDrawElements mode count type indices primcount
11343 Render multiple sets of primitives by specifying indices of array data
11348 Specifies what kind of primitives to render. Symbolic constants
11349 @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP},
11350 @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN},
11351 @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and
11352 @code{GL_POLYGON} are accepted.
11355 Points to an array of the elements counts.
11358 Specifies the type of the values in @var{indices}. Must be one of
11359 @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or
11360 @code{GL_UNSIGNED_INT}.
11362 @item @var{indices}
11363 Specifies a pointer to the location where the indices are stored.
11365 @item @var{primcount}
11366 Specifies the size of the @var{count} array.
11370 @code{glMultiDrawElements} specifies multiple sets of geometric
11371 primitives with very few subroutine calls. Instead of calling a GL
11372 function to pass each individual vertex, normal, texture coordinate,
11373 edge flag, or color, you can prespecify separate arrays of vertices,
11374 normals, and so on, and use them to construct a sequence of primitives
11375 with a single call to @code{glMultiDrawElements}.
11377 @code{glMultiDrawElements} is identical in operation to
11378 @code{glDrawElements} except that @var{primcount} separate lists of
11379 elements are specified.
11381 Vertex attributes that are modified by @code{glMultiDrawElements} have
11382 an unspecified value after @code{glMultiDrawElements} returns. For
11383 example, if @code{GL_COLOR_ARRAY} is enabled, the value of the current
11384 color is undefined after @code{glMultiDrawElements} executes. Attributes
11385 that aren't modified maintain their previous values.
11387 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
11390 @code{GL_INVALID_VALUE} is generated if @var{primcount} is negative.
11392 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
11393 name is bound to an enabled array or the element array and the buffer
11394 object's data store is currently mapped.
11396 @code{GL_INVALID_OPERATION} is generated if @code{glMultiDrawElements}
11397 is executed between the execution of @code{glBegin} and the
11398 corresponding @code{glEnd}.
11402 @deftypefun void glMultiTexCoord1i target s
11403 @deftypefunx void glMultiTexCoord1f target s
11404 @deftypefunx void glMultiTexCoord2i target s t
11405 @deftypefunx void glMultiTexCoord2f target s t
11406 @deftypefunx void glMultiTexCoord3i target s t r
11407 @deftypefunx void glMultiTexCoord3f target s t r
11408 @deftypefunx void glMultiTexCoord4i target s t r q
11409 @deftypefunx void glMultiTexCoord4f target s t r q
11410 Set the current texture coordinates.
11414 Specifies the texture unit whose coordinates should be modified. The
11415 number of texture units is implementation dependent, but must be at
11416 least two. Symbolic constant must be one of
11417 @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to
11418 @code{GL_MAX_TEXTURE_COORDS} - 1, which is an implementation-dependent
11425 Specify @var{s}, @var{t}, @var{r}, and @var{q} texture coordinates for
11426 @var{target} texture unit. Not all parameters are present in all forms
11431 @code{glMultiTexCoord} specifies texture coordinates in one, two, three,
11432 or four dimensions. @code{glMultiTexCoord1} sets the current texture
11433 coordinates to @r{(@var{s},001)}; a call to @code{glMultiTexCoord2} sets
11434 them to @r{(@var{s},@var{t}01)}. Similarly, @code{glMultiTexCoord3}
11435 specifies the texture coordinates as @r{(@var{s},@var{t}@var{r}1)}, and
11436 @code{glMultiTexCoord4} defines all four components explicitly as
11437 @r{(@var{s},@var{t}@var{r}@var{q})}.
11439 The current texture coordinates are part of the data that is associated
11440 with each vertex and with the current raster position. Initially, the
11441 values for @r{(@var{s},@var{t}@var{r}@var{q})} are @r{(0,001)}.
11447 @deftypefun void glMultMatrixf m
11448 Multiply the current matrix with the specified matrix.
11452 Points to 16 consecutive values that are used as the elements of a
11453 @r{4×4} column-major matrix.
11457 @code{glMultMatrix} multiplies the current matrix with the one specified
11458 using @var{m}, and replaces the current matrix with the product.
11460 The current matrix is determined by the current matrix mode (see
11461 @code{glMatrixMode}). It is either the projection matrix, modelview
11462 matrix, or the texture matrix.
11464 @code{GL_INVALID_OPERATION} is generated if @code{glMultMatrix} is
11465 executed between the execution of @code{glBegin} and the corresponding
11466 execution of @code{glEnd}.
11470 @deftypefun void glMultTransposeMatrixf m
11471 Multiply the current matrix with the specified row-major ordered matrix.
11475 Points to 16 consecutive values that are used as the elements of a
11476 @r{4×4} row-major matrix.
11480 @code{glMultTransposeMatrix} multiplies the current matrix with the one
11481 specified using @var{m}, and replaces the current matrix with the
11484 The current matrix is determined by the current matrix mode (see
11485 @code{glMatrixMode}). It is either the projection matrix, modelview
11486 matrix, or the texture matrix.
11488 @code{GL_INVALID_OPERATION} is generated if @code{glMultTransposeMatrix}
11489 is executed between the execution of @code{glBegin} and the
11490 corresponding execution of @code{glEnd}.
11494 @deftypefun void glNewList list mode
11495 @deftypefunx void glEndList
11496 Create or replace a display list.
11500 Specifies the display-list name.
11503 Specifies the compilation mode, which can be @code{GL_COMPILE} or
11504 @code{GL_COMPILE_AND_EXECUTE}.
11508 Display lists are groups of GL commands that have been stored for
11509 subsequent execution. Display lists are created with @code{glNewList}.
11510 All subsequent commands are placed in the display list, in the order
11511 issued, until @code{glEndList} is called.
11513 @code{glNewList} has two arguments. The first argument, @var{list}, is a
11514 positive integer that becomes the unique name for the display list.
11515 Names can be created and reserved with @code{glGenLists} and tested for
11516 uniqueness with @code{glIsList}. The second argument, @var{mode}, is a
11517 symbolic constant that can assume one of two values:
11520 @item @code{GL_COMPILE}
11521 Commands are merely compiled.
11523 @item @code{GL_COMPILE_AND_EXECUTE}
11524 Commands are executed as they are compiled into the display list.
11528 Certain commands are not compiled into the display list but are executed
11529 immediately, regardless of the display-list mode. These commands are
11530 @code{glAreTexturesResident}, @code{glColorPointer},
11531 @code{glDeleteLists}, @code{glDeleteTextures},
11532 @code{glDisableClientState}, @code{glEdgeFlagPointer},
11533 @code{glEnableClientState}, @code{glFeedbackBuffer}, @code{glFinish},
11534 @code{glFlush}, @code{glGenLists}, @code{glGenTextures},
11535 @code{glIndexPointer}, @code{glInterleavedArrays}, @code{glIsEnabled},
11536 @code{glIsList}, @code{glIsTexture}, @code{glNormalPointer},
11537 @code{glPopClientAttrib}, @code{glPixelStore},
11538 @code{glPushClientAttrib}, @code{glReadPixels}, @code{glRenderMode},
11539 @code{glSelectBuffer}, @code{glTexCoordPointer}, @code{glVertexPointer},
11540 and all of the @code{glGet} commands.
11542 Similarly, @code{glTexImage1D}, @code{glTexImage2D}, and
11543 @code{glTexImage3D} are executed immediately and not compiled into the
11544 display list when their first argument is @code{GL_PROXY_TEXTURE_1D},
11545 @code{GL_PROXY_TEXTURE_1D}, or @code{GL_PROXY_TEXTURE_3D}, respectively.
11547 When the @code{ARB_imaging} extension is supported, @code{glHistogram}
11548 executes immediately when its argument is @code{GL_PROXY_HISTOGRAM}.
11549 Similarly, @code{glColorTable} executes immediately when its first
11550 argument is @code{GL_PROXY_COLOR_TABLE},
11551 @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or
11552 @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}.
11554 For OpenGL versions 1.3 and greater, or when the @code{ARB_multitexture}
11555 extension is supported, @code{glClientActiveTexture} is not compiled
11556 into display lists, but executed immediately.
11558 When @code{glEndList} is encountered, the display-list definition is
11559 completed by associating the list with the unique name @var{list}
11560 (specified in the @code{glNewList} command). If a display list with name
11561 @var{list} already exists, it is replaced only when @code{glEndList} is
11564 @code{GL_INVALID_VALUE} is generated if @var{list} is 0.
11566 @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted
11569 @code{GL_INVALID_OPERATION} is generated if @code{glEndList} is called
11570 without a preceding @code{glNewList}, or if @code{glNewList} is called
11571 while a display list is being defined.
11573 @code{GL_INVALID_OPERATION} is generated if @code{glNewList} or
11574 @code{glEndList} is executed between the execution of @code{glBegin} and
11575 the corresponding execution of @code{glEnd}.
11577 @code{GL_OUT_OF_MEMORY} is generated if there is insufficient memory to
11578 compile the display list. If the GL version is 1.1 or greater, no change
11579 is made to the previous contents of the display list, if any, and no
11580 other change is made to the GL state. (It is as if no attempt had been
11581 made to create the new display list.)
11585 @deftypefun void glNormalPointer type stride pointer
11586 Define an array of normals.
11590 Specifies the data type of each coordinate in the array. Symbolic
11591 constants @code{GL_BYTE}, @code{GL_SHORT}, @code{GL_INT},
11592 @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value is
11596 Specifies the byte offset between consecutive normals. If @var{stride}
11597 is 0, the normals are understood to be tightly packed in the array. The
11598 initial value is 0.
11600 @item @var{pointer}
11601 Specifies a pointer to the first coordinate of the first normal in the
11602 array. The initial value is 0.
11606 @code{glNormalPointer} specifies the location and data format of an
11607 array of normals to use when rendering. @var{type} specifies the data
11608 type of each normal coordinate, and @var{stride} specifies the byte
11609 stride from one normal to the next, allowing vertices and attributes to
11610 be packed into a single array or stored in separate arrays.
11611 (Single-array storage may be more efficient on some implementations; see
11612 @code{glInterleavedArrays}.)
11614 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
11615 target (see @code{glBindBuffer}) while a normal array is specified,
11616 @var{pointer} is treated as a byte offset into the buffer object's data
11617 store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING})
11618 is saved as normal vertex array client-side state
11619 (@code{GL_NORMAL_ARRAY_BUFFER_BINDING}).
11621 When a normal array is specified, @var{type}, @var{stride}, and
11622 @var{pointer} are saved as client-side state, in addition to the current
11623 vertex array buffer object binding.
11625 To enable and disable the normal array, call @code{glEnableClientState}
11626 and @code{glDisableClientState} with the argument
11627 @code{GL_NORMAL_ARRAY}. If enabled, the normal array is used when
11628 @code{glDrawArrays}, @code{glMultiDrawArrays}, @code{glDrawElements},
11629 @code{glMultiDrawElements}, @code{glDrawRangeElements}, or
11630 @code{glArrayElement} is called.
11632 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
11635 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
11639 @deftypefun void glNormal3f nx ny nz
11640 @deftypefunx void glNormal3i nx ny nz
11641 Set the current normal vector.
11647 Specify the @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} coordinates of the
11648 new current normal. The initial value of the current normal is the unit
11655 The current normal is set to the given coordinates whenever
11656 @code{glNormal} is issued. Byte, short, or integer arguments are
11657 converted to floating-point format with a linear mapping that maps the
11658 most positive representable integer value to 1.0 and the most negative
11659 representable integer value to @r{-1.0}.
11661 Normals specified with @code{glNormal} need not have unit length. If
11662 @code{GL_NORMALIZE} is enabled, then normals of any length specified
11663 with @code{glNormal} are normalized after transformation. If
11664 @code{GL_RESCALE_NORMAL} is enabled, normals are scaled by a scaling
11665 factor derived from the modelview matrix. @code{GL_RESCALE_NORMAL}
11666 requires that the originally specified normals were of unit length, and
11667 that the modelview matrix contain only uniform scales for proper
11668 results. To enable and disable normalization, call @code{glEnable} and
11669 @code{glDisable} with either @code{GL_NORMALIZE} or
11670 @code{GL_RESCALE_NORMAL}. Normalization is initially disabled.
11674 @deftypefun void glOrtho left right bottom top nearVal farVal
11675 Multiply the current matrix with an orthographic matrix.
11680 Specify the coordinates for the left and right vertical clipping planes.
11684 Specify the coordinates for the bottom and top horizontal clipping
11687 @item @var{nearVal}
11688 @itemx @var{farVal}
11689 Specify the distances to the nearer and farther depth clipping planes.
11690 These values are negative if the plane is to be behind the viewer.
11694 @code{glOrtho} describes a transformation that produces a parallel
11695 projection. The current matrix (see @code{glMatrixMode}) is multiplied
11696 by this matrix and the result replaces the current matrix, as if
11697 @code{glMultMatrix} were called with the following matrix as its
11700 @r{((2/@var{right}-@var{left},, 0 0 @var{t}_@var{x},), (0
11701 2/@var{top}-@var{bottom},, 0 @var{t}_@var{y},), (0 0
11702 -2/@var{farVal}-@var{nearVal},, @var{t}_@var{z},), (0 0 0 1),)}
11705 @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},,}
11707 Typically, the matrix mode is @code{GL_PROJECTION}, and
11708 @r{(@var{left},@var{bottom}-@var{nearVal})} and
11709 @r{(@var{right},@var{top}-@var{nearVal})} specify the points on the near
11710 clipping plane that are mapped to the lower left and upper right corners
11711 of the window, respectively, assuming that the eye is located at (0, 0,
11712 0). @r{-@var{farVal}} specifies the location of the far clipping plane.
11713 Both @var{nearVal} and @var{farVal} can be either positive or negative.
11715 Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the
11716 current matrix stack.
11718 @code{GL_INVALID_VALUE} is generated if @var{left} = @var{right}, or
11719 @var{bottom} = @var{top}, or @var{near} = @var{far}.
11721 @code{GL_INVALID_OPERATION} is generated if @code{glOrtho} is executed
11722 between the execution of @code{glBegin} and the corresponding execution
11727 @deftypefun void glPassThrough token
11728 Place a marker in the feedback buffer.
11732 Specifies a marker value to be placed in the feedback buffer following a
11733 @code{GL_PASS_THROUGH_TOKEN}.
11739 Feedback is a GL render mode. The mode is selected by calling
11740 @code{glRenderMode} with @code{GL_FEEDBACK}. When the GL is in feedback
11741 mode, no pixels are produced by rasterization. Instead, information
11742 about primitives that would have been rasterized is fed back to the
11743 application using the GL. See the @code{glFeedbackBuffer} reference page
11744 for a description of the feedback buffer and the values in it.
11746 @code{glPassThrough} inserts a user-defined marker in the feedback
11747 buffer when it is executed in feedback mode. @var{token} is returned as
11748 if it were a primitive; it is indicated with its own unique identifying
11749 value: @code{GL_PASS_THROUGH_TOKEN}. The order of @code{glPassThrough}
11750 commands with respect to the specification of graphics primitives is
11753 @code{GL_INVALID_OPERATION} is generated if @code{glPassThrough} is
11754 executed between the execution of @code{glBegin} and the corresponding
11755 execution of @code{glEnd}.
11759 @deftypefun void glPixelStoref pname param
11760 @deftypefunx void glPixelStorei pname param
11761 Set pixel storage modes.
11765 Specifies the symbolic name of the parameter to be set. Six values
11766 affect the packing of pixel data into memory: @code{GL_PACK_SWAP_BYTES},
11767 @code{GL_PACK_LSB_FIRST}, @code{GL_PACK_ROW_LENGTH},
11768 @code{GL_PACK_IMAGE_HEIGHT}, @code{GL_PACK_SKIP_PIXELS},
11769 @code{GL_PACK_SKIP_ROWS}, @code{GL_PACK_SKIP_IMAGES}, and
11770 @code{GL_PACK_ALIGNMENT}. Six more affect the unpacking of pixel data
11771 @var{from} memory: @code{GL_UNPACK_SWAP_BYTES},
11772 @code{GL_UNPACK_LSB_FIRST}, @code{GL_UNPACK_ROW_LENGTH},
11773 @code{GL_UNPACK_IMAGE_HEIGHT}, @code{GL_UNPACK_SKIP_PIXELS},
11774 @code{GL_UNPACK_SKIP_ROWS}, @code{GL_UNPACK_SKIP_IMAGES}, and
11775 @code{GL_UNPACK_ALIGNMENT}.
11778 Specifies the value that @var{pname} is set to.
11782 @code{glPixelStore} sets pixel storage modes that affect the operation
11783 of subsequent @code{glDrawPixels} and @code{glReadPixels} as well as the
11784 unpacking of polygon stipple patterns (see @code{glPolygonStipple}),
11785 bitmaps (see @code{glBitmap}), texture patterns (see
11786 @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D},
11787 @code{glTexSubImage1D}, @code{glTexSubImage2D}, @code{glTexSubImage3D}).
11788 Additionally, if the @code{ARB_imaging} extension is supported, pixel
11789 storage modes affect convolution filters (see
11790 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and
11791 @code{glSeparableFilter2D}, color table (see @code{glColorTable}, and
11792 @code{glColorSubTable}, and unpacking histogram (See
11793 @code{glHistogram}), and minmax (See @code{glMinmax}) data.
11795 @var{pname} is a symbolic constant indicating the parameter to be set,
11796 and @var{param} is the new value. Six of the twelve storage parameters
11797 affect how pixel data is returned to client memory. They are as follows:
11800 @item @code{GL_PACK_SWAP_BYTES}
11801 If true, byte ordering for multibyte color components, depth components,
11802 color indices, or stencil indices is reversed. That is, if a four-byte
11803 component consists of bytes @r{@var{b}_0}, @r{@var{b}_1}, @r{@var{b}_2},
11804 @r{@var{b}_3}, it is stored in memory as @r{@var{b}_3}, @r{@var{b}_2},
11805 @r{@var{b}_1}, @r{@var{b}_0} if @code{GL_PACK_SWAP_BYTES} is true.
11806 @code{GL_PACK_SWAP_BYTES} has no effect on the memory order of
11807 components within a pixel, only on the order of bytes within components
11808 or indices. For example, the three components of a @code{GL_RGB} format
11809 pixel are always stored with red first, green second, and blue third,
11810 regardless of the value of @code{GL_PACK_SWAP_BYTES}.
11812 @item @code{GL_PACK_LSB_FIRST}
11813 If true, bits are ordered within a byte from least significant to most
11814 significant; otherwise, the first bit in each byte is the most
11815 significant one. This parameter is significant for bitmap data only.
11817 @item @code{GL_PACK_ROW_LENGTH}
11818 If greater than 0, @code{GL_PACK_ROW_LENGTH} defines the number of
11819 pixels in a row. If the first pixel of a row is placed at location
11820 @r{@var{p}} in memory, then the location of the first pixel of the next
11821 row is obtained by skipping
11823 @r{@var{k}=@{(@var{n}@var{l}),
11824 (@var{a}/@var{s},⌈@var{s}@var{n}@var{l},/@var{a},⌉)(@var{s}>=@var{a}),
11825 (@var{s}<@var{a}),}
11827 components or indices, where @r{@var{n}} is the number of components or
11828 indices in a pixel, @r{@var{l}} is the number of pixels in a row
11829 (@code{GL_PACK_ROW_LENGTH} if it is greater than 0, the @r{@var{width}}
11830 argument to the pixel routine otherwise), @r{@var{a}} is the value of
11831 @code{GL_PACK_ALIGNMENT}, and @r{@var{s}} is the size, in bytes, of a
11832 single component (if @r{@var{a}<@var{s}}, then it is as if
11833 @r{@var{a}=@var{s}}). In the case of 1-bit values, the location of the
11834 next row is obtained by skipping
11836 @r{@var{k}=8@var{a}⌈@var{n}@var{l},/8@var{a},,⌉}
11838 components or indices.
11840 The word @var{component} in this description refers to the nonindex
11841 values red, green, blue, alpha, and depth. Storage format @code{GL_RGB},
11842 for example, has three components per pixel: first red, then green, and
11845 @item @code{GL_PACK_IMAGE_HEIGHT}
11846 If greater than 0, @code{GL_PACK_IMAGE_HEIGHT} defines the number of
11847 pixels in an image three-dimensional texture volume, where ``image'' is
11848 defined by all pixels sharing the same third dimension index. If the
11849 first pixel of a row is placed at location @r{@var{p}} in memory, then
11850 the location of the first pixel of the next row is obtained by skipping
11852 @r{@var{k}=@{(@var{n}@var{l}@var{h}),
11853 (@var{a}/@var{s},⌈@var{s}@var{n}@var{l}@var{h},/@var{a},⌉)(@var{s}>=@var{a}),
11854 (@var{s}<@var{a}),}
11856 components or indices, where @r{@var{n}} is the number of components or
11857 indices in a pixel, @r{@var{l}} is the number of pixels in a row
11858 (@code{GL_PACK_ROW_LENGTH} if it is greater than 0, the @r{@var{width}}
11859 argument to @code{glTexImage3D} otherwise), @r{@var{h}} is the number of
11860 rows in a pixel image (@code{GL_PACK_IMAGE_HEIGHT} if it is greater than
11861 0, the @r{@var{height}} argument to the @code{glTexImage3D} routine
11862 otherwise), @r{@var{a}} is the value of @code{GL_PACK_ALIGNMENT}, and
11863 @r{@var{s}} is the size, in bytes, of a single component (if
11864 @r{@var{a}<@var{s}}, then it is as if @r{@var{a}=@var{s}}).
11866 The word @var{component} in this description refers to the nonindex
11867 values red, green, blue, alpha, and depth. Storage format @code{GL_RGB},
11868 for example, has three components per pixel: first red, then green, and
11871 @item @code{GL_PACK_SKIP_PIXELS}, @code{GL_PACK_SKIP_ROWS}, and @code{GL_PACK_SKIP_IMAGES}
11872 These values are provided as a convenience to the programmer; they
11873 provide no functionality that cannot be duplicated simply by
11874 incrementing the pointer passed to @code{glReadPixels}. Setting
11875 @code{GL_PACK_SKIP_PIXELS} to @r{@var{i}} is equivalent to incrementing
11876 the pointer by @r{@var{i}@var{n}} components or indices, where
11877 @r{@var{n}} is the number of components or indices in each pixel.
11878 Setting @code{GL_PACK_SKIP_ROWS} to @r{@var{j}} is equivalent to
11879 incrementing the pointer by @r{@var{j}@var{m}} components or indices,
11880 where @r{@var{m}} is the number of components or indices per row, as
11881 just computed in the @code{GL_PACK_ROW_LENGTH} section. Setting
11882 @code{GL_PACK_SKIP_IMAGES} to @r{@var{k}} is equivalent to incrementing
11883 the pointer by @r{@var{k}@var{p}}, where @r{@var{p}} is the number of
11884 components or indices per image, as computed in the
11885 @code{GL_PACK_IMAGE_HEIGHT} section.
11887 @item @code{GL_PACK_ALIGNMENT}
11888 Specifies the alignment requirements for the start of each pixel row in
11889 memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to
11890 even-numbered bytes), 4 (word-alignment), and 8 (rows start on
11891 double-word boundaries).
11895 The other six of the twelve storage parameters affect how pixel data is
11896 read from client memory. These values are significant for
11897 @code{glDrawPixels}, @code{glTexImage1D}, @code{glTexImage2D},
11898 @code{glTexImage3D}, @code{glTexSubImage1D}, @code{glTexSubImage2D},
11899 @code{glTexSubImage3D}, @code{glBitmap}, and @code{glPolygonStipple}.
11901 Additionally, if the @code{ARB_imaging} extension is supported,
11902 @code{glColorTable}, @code{glColorSubTable},
11903 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and
11904 @code{glSeparableFilter2D}. They are as follows:
11907 @item @code{GL_UNPACK_SWAP_BYTES}
11908 If true, byte ordering for multibyte color components, depth components,
11909 color indices, or stencil indices is reversed. That is, if a four-byte
11910 component consists of bytes @r{@var{b}_0}, @r{@var{b}_1}, @r{@var{b}_2},
11911 @r{@var{b}_3}, it is taken from memory as @r{@var{b}_3}, @r{@var{b}_2},
11912 @r{@var{b}_1}, @r{@var{b}_0} if @code{GL_UNPACK_SWAP_BYTES} is true.
11913 @code{GL_UNPACK_SWAP_BYTES} has no effect on the memory order of
11914 components within a pixel, only on the order of bytes within components
11915 or indices. For example, the three components of a @code{GL_RGB} format
11916 pixel are always stored with red first, green second, and blue third,
11917 regardless of the value of @code{GL_UNPACK_SWAP_BYTES}.
11919 @item @code{GL_UNPACK_LSB_FIRST}
11920 If true, bits are ordered within a byte from least significant to most
11921 significant; otherwise, the first bit in each byte is the most
11922 significant one. This is relevant only for bitmap data.
11924 @item @code{GL_UNPACK_ROW_LENGTH}
11925 If greater than 0, @code{GL_UNPACK_ROW_LENGTH} defines the number of
11926 pixels in a row. If the first pixel of a row is placed at location
11927 @r{@var{p}} in memory, then the location of the first pixel of the next
11928 row is obtained by skipping
11930 @r{@var{k}=@{(@var{n}@var{l}),
11931 (@var{a}/@var{s},⌈@var{s}@var{n}@var{l},/@var{a},⌉)(@var{s}>=@var{a}),
11932 (@var{s}<@var{a}),}
11934 components or indices, where @r{@var{n}} is the number of components or
11935 indices in a pixel, @r{@var{l}} is the number of pixels in a row
11936 (@code{GL_UNPACK_ROW_LENGTH} if it is greater than 0, the
11937 @r{@var{width}} argument to the pixel routine otherwise), @r{@var{a}} is
11938 the value of @code{GL_UNPACK_ALIGNMENT}, and @r{@var{s}} is the size, in
11939 bytes, of a single component (if @r{@var{a}<@var{s}}, then it is as if
11940 @r{@var{a}=@var{s}}). In the case of 1-bit values, the location of the
11941 next row is obtained by skipping
11943 @r{@var{k}=8@var{a}⌈@var{n}@var{l},/8@var{a},,⌉}
11945 components or indices.
11947 The word @var{component} in this description refers to the nonindex
11948 values red, green, blue, alpha, and depth. Storage format @code{GL_RGB},
11949 for example, has three components per pixel: first red, then green, and
11952 @item @code{GL_UNPACK_IMAGE_HEIGHT}
11953 If greater than 0, @code{GL_UNPACK_IMAGE_HEIGHT} defines the number of
11954 pixels in an image of a three-dimensional texture volume. Where
11955 ``image'' is defined by all pixel sharing the same third dimension
11956 index. If the first pixel of a row is placed at location @r{@var{p}} in
11957 memory, then the location of the first pixel of the next row is obtained
11960 @r{@var{k}=@{(@var{n}@var{l}@var{h}),
11961 (@var{a}/@var{s},⌈@var{s}@var{n}@var{l}@var{h},/@var{a},⌉)(@var{s}>=@var{a}),
11962 (@var{s}<@var{a}),}
11964 components or indices, where @r{@var{n}} is the number of components or
11965 indices in a pixel, @r{@var{l}} is the number of pixels in a row
11966 (@code{GL_UNPACK_ROW_LENGTH} if it is greater than 0, the
11967 @r{@var{width}} argument to @code{glTexImage3D} otherwise), @r{@var{h}}
11968 is the number of rows in an image (@code{GL_UNPACK_IMAGE_HEIGHT} if it
11969 is greater than 0, the @r{@var{height}} argument to @code{glTexImage3D}
11970 otherwise), @r{@var{a}} is the value of @code{GL_UNPACK_ALIGNMENT}, and
11971 @r{@var{s}} is the size, in bytes, of a single component (if
11972 @r{@var{a}<@var{s}}, then it is as if @r{@var{a}=@var{s}}).
11974 The word @var{component} in this description refers to the nonindex
11975 values red, green, blue, alpha, and depth. Storage format @code{GL_RGB},
11976 for example, has three components per pixel: first red, then green, and
11979 @item @code{GL_UNPACK_SKIP_PIXELS} and @code{GL_UNPACK_SKIP_ROWS}
11980 These values are provided as a convenience to the programmer; they
11981 provide no functionality that cannot be duplicated by incrementing the
11982 pointer passed to @code{glDrawPixels}, @code{glTexImage1D},
11983 @code{glTexImage2D}, @code{glTexSubImage1D}, @code{glTexSubImage2D},
11984 @code{glBitmap}, or @code{glPolygonStipple}. Setting
11985 @code{GL_UNPACK_SKIP_PIXELS} to @r{@var{i}} is equivalent to
11986 incrementing the pointer by @r{@var{i}@var{n}} components or indices,
11987 where @r{@var{n}} is the number of components or indices in each pixel.
11988 Setting @code{GL_UNPACK_SKIP_ROWS} to @r{@var{j}} is equivalent to
11989 incrementing the pointer by @r{@var{j}@var{k}} components or indices,
11990 where @r{@var{k}} is the number of components or indices per row, as
11991 just computed in the @code{GL_UNPACK_ROW_LENGTH} section.
11993 @item @code{GL_UNPACK_ALIGNMENT}
11994 Specifies the alignment requirements for the start of each pixel row in
11995 memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to
11996 even-numbered bytes), 4 (word-alignment), and 8 (rows start on
11997 double-word boundaries).
12001 The following table gives the type, initial value, and range of valid
12002 values for each storage parameter that can be set with
12003 @code{glPixelStore}.
12008 @item @strong{@var{pname}}
12009 @strong{Type}, @strong{Initial Value}, @strong{Valid Range}
12011 @item @code{GL_PACK_SWAP_BYTES}
12012 boolean , false , true or false
12014 @item @code{GL_PACK_LSB_FIRST}
12015 boolean , false , true or false
12017 @item @code{GL_PACK_ROW_LENGTH}
12018 integer , 0 , @r{[0,∞)}
12020 @item @code{GL_PACK_IMAGE_HEIGHT}
12021 integer , 0 , @r{[0,∞)}
12023 @item @code{GL_PACK_SKIP_ROWS}
12024 integer , 0 , @r{[0,∞)}
12026 @item @code{GL_PACK_SKIP_PIXELS}
12027 integer , 0 , @r{[0,∞)}
12029 @item @code{GL_PACK_SKIP_IMAGES}
12030 integer , 0 , @r{[0,∞)}
12032 @item @code{GL_PACK_ALIGNMENT}
12033 integer , 4 , 1, 2, 4, or 8
12035 @item @code{GL_UNPACK_SWAP_BYTES}
12036 boolean , false , true or false
12038 @item @code{GL_UNPACK_LSB_FIRST}
12039 boolean , false , true or false
12041 @item @code{GL_UNPACK_ROW_LENGTH}
12042 integer , 0 , @r{[0,∞)}
12044 @item @code{GL_UNPACK_IMAGE_HEIGHT}
12045 integer , 0 , @r{[0,∞)}
12047 @item @code{GL_UNPACK_SKIP_ROWS}
12048 integer , 0 , @r{[0,∞)}
12050 @item @code{GL_UNPACK_SKIP_PIXELS}
12051 integer , 0 , @r{[0,∞)}
12053 @item @code{GL_UNPACK_SKIP_IMAGES}
12054 integer , 0 , @r{[0,∞)}
12056 @item @code{GL_UNPACK_ALIGNMENT}
12057 integer , 4 , 1, 2, 4, or 8
12061 @code{glPixelStoref} can be used to set any pixel store parameter. If
12062 the parameter type is boolean, then if @var{param} is 0, the parameter
12063 is false; otherwise it is set to true. If @var{pname} is a integer type
12064 parameter, @var{param} is rounded to the nearest integer.
12066 Likewise, @code{glPixelStorei} can also be used to set any of the pixel
12067 store parameters. Boolean parameters are set to false if @var{param} is
12068 0 and true otherwise.
12070 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
12073 @code{GL_INVALID_VALUE} is generated if a negative row length, pixel
12074 skip, or row skip value is specified, or if alignment is specified as
12075 other than 1, 2, 4, or 8.
12077 @code{GL_INVALID_OPERATION} is generated if @code{glPixelStore} is
12078 executed between the execution of @code{glBegin} and the corresponding
12079 execution of @code{glEnd}.
12083 @deftypefun void glPixelTransferf pname param
12084 @deftypefunx void glPixelTransferi pname param
12085 Set pixel transfer modes.
12089 Specifies the symbolic name of the pixel transfer parameter to be set.
12090 Must be one of the following: @code{GL_MAP_COLOR},
12091 @code{GL_MAP_STENCIL}, @code{GL_INDEX_SHIFT}, @code{GL_INDEX_OFFSET},
12092 @code{GL_RED_SCALE}, @code{GL_RED_BIAS}, @code{GL_GREEN_SCALE},
12093 @code{GL_GREEN_BIAS}, @code{GL_BLUE_SCALE}, @code{GL_BLUE_BIAS},
12094 @code{GL_ALPHA_SCALE}, @code{GL_ALPHA_BIAS}, @code{GL_DEPTH_SCALE}, or
12095 @code{GL_DEPTH_BIAS}.
12097 Additionally, if the @code{ARB_imaging} extension is supported, the
12098 following symbolic names are accepted:
12099 @code{GL_POST_COLOR_MATRIX_RED_SCALE},
12100 @code{GL_POST_COLOR_MATRIX_GREEN_SCALE},
12101 @code{GL_POST_COLOR_MATRIX_BLUE_SCALE},
12102 @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE},
12103 @code{GL_POST_COLOR_MATRIX_RED_BIAS},
12104 @code{GL_POST_COLOR_MATRIX_GREEN_BIAS},
12105 @code{GL_POST_COLOR_MATRIX_BLUE_BIAS},
12106 @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS},
12107 @code{GL_POST_CONVOLUTION_RED_SCALE},
12108 @code{GL_POST_CONVOLUTION_GREEN_SCALE},
12109 @code{GL_POST_CONVOLUTION_BLUE_SCALE},
12110 @code{GL_POST_CONVOLUTION_ALPHA_SCALE},
12111 @code{GL_POST_CONVOLUTION_RED_BIAS},
12112 @code{GL_POST_CONVOLUTION_GREEN_BIAS},
12113 @code{GL_POST_CONVOLUTION_BLUE_BIAS}, and
12114 @code{GL_POST_CONVOLUTION_ALPHA_BIAS}.
12117 Specifies the value that @var{pname} is set to.
12121 @code{glPixelTransfer} sets pixel transfer modes that affect the
12122 operation of subsequent @code{glCopyPixels}, @code{glCopyTexImage1D},
12123 @code{glCopyTexImage2D}, @code{glCopyTexSubImage1D},
12124 @code{glCopyTexSubImage2D}, @code{glCopyTexSubImage3D},
12125 @code{glDrawPixels}, @code{glReadPixels}, @code{glTexImage1D},
12126 @code{glTexImage2D}, @code{glTexImage3D}, @code{glTexSubImage1D},
12127 @code{glTexSubImage2D}, and @code{glTexSubImage3D} commands.
12128 Additionally, if the @code{ARB_imaging} subset is supported, the
12129 routines @code{glColorTable}, @code{glColorSubTable},
12130 @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D},
12131 @code{glHistogram}, @code{glMinmax}, and @code{glSeparableFilter2D} are
12132 also affected. The algorithms that are specified by pixel transfer modes
12133 operate on pixels after they are read from the frame buffer
12134 (@code{glCopyPixels}@code{glCopyTexImage1D}, @code{glCopyTexImage2D},
12135 @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D},
12136 @code{glCopyTexSubImage3D}, and @code{glReadPixels}), or unpacked from
12137 client memory (@code{glDrawPixels}, @code{glTexImage1D},
12138 @code{glTexImage2D}, @code{glTexImage3D}, @code{glTexSubImage1D},
12139 @code{glTexSubImage2D}, and @code{glTexSubImage3D}). Pixel transfer
12140 operations happen in the same order, and in the same manner, regardless
12141 of the command that resulted in the pixel operation. Pixel storage modes
12142 (see @code{glPixelStore}) control the unpacking of pixels being read
12143 from client memory and the packing of pixels being written back into
12146 Pixel transfer operations handle four fundamental pixel types:
12147 @var{color}, @var{color index}, @var{depth}, and @var{stencil}.
12148 @var{Color} pixels consist of four floating-point values with
12149 unspecified mantissa and exponent sizes, scaled such that 0 represents
12150 zero intensity and 1 represents full intensity. @var{Color indices}
12151 comprise a single fixed-point value, with unspecified precision to the
12152 right of the binary point. @var{Depth} pixels comprise a single
12153 floating-point value, with unspecified mantissa and exponent sizes,
12154 scaled such that 0.0 represents the minimum depth buffer value, and 1.0
12155 represents the maximum depth buffer value. Finally, @var{stencil} pixels
12156 comprise a single fixed-point value, with unspecified precision to the
12157 right of the binary point.
12159 The pixel transfer operations performed on the four basic pixel types
12164 Each of the four color components is multiplied by a scale factor, then
12165 added to a bias factor. That is, the red component is multiplied by
12166 @code{GL_RED_SCALE}, then added to @code{GL_RED_BIAS}; the green
12167 component is multiplied by @code{GL_GREEN_SCALE}, then added to
12168 @code{GL_GREEN_BIAS}; the blue component is multiplied by
12169 @code{GL_BLUE_SCALE}, then added to @code{GL_BLUE_BIAS}; and the alpha
12170 component is multiplied by @code{GL_ALPHA_SCALE}, then added to
12171 @code{GL_ALPHA_BIAS}. After all four color components are scaled and
12172 biased, each is clamped to the range @r{[0,1]}. All color, scale, and
12173 bias values are specified with @code{glPixelTransfer}.
12175 If @code{GL_MAP_COLOR} is true, each color component is scaled by the
12176 size of the corresponding color-to-color map, then replaced by the
12177 contents of that map indexed by the scaled component. That is, the red
12178 component is scaled by @code{GL_PIXEL_MAP_R_TO_R_SIZE}, then replaced by
12179 the contents of @code{GL_PIXEL_MAP_R_TO_R} indexed by itself. The green
12180 component is scaled by @code{GL_PIXEL_MAP_G_TO_G_SIZE}, then replaced by
12181 the contents of @code{GL_PIXEL_MAP_G_TO_G} indexed by itself. The blue
12182 component is scaled by @code{GL_PIXEL_MAP_B_TO_B_SIZE}, then replaced by
12183 the contents of @code{GL_PIXEL_MAP_B_TO_B} indexed by itself. And the
12184 alpha component is scaled by @code{GL_PIXEL_MAP_A_TO_A_SIZE}, then
12185 replaced by the contents of @code{GL_PIXEL_MAP_A_TO_A} indexed by
12186 itself. All components taken from the maps are then clamped to the range
12187 @r{[0,1]}. @code{GL_MAP_COLOR} is specified with @code{glPixelTransfer}.
12188 The contents of the various maps are specified with @code{glPixelMap}.
12190 If the @code{ARB_imaging} extension is supported, each of the four color
12191 components may be scaled and biased after transformation by the color
12192 matrix. That is, the red component is multiplied by
12193 @code{GL_POST_COLOR_MATRIX_RED_SCALE}, then added to
12194 @code{GL_POST_COLOR_MATRIX_RED_BIAS}; the green component is multiplied
12195 by @code{GL_POST_COLOR_MATRIX_GREEN_SCALE}, then added to
12196 @code{GL_POST_COLOR_MATRIX_GREEN_BIAS}; the blue component is multiplied
12197 by @code{GL_POST_COLOR_MATRIX_BLUE_SCALE}, then added to
12198 @code{GL_POST_COLOR_MATRIX_BLUE_BIAS}; and the alpha component is
12199 multiplied by @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE}, then added to
12200 @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS}. After all four color components
12201 are scaled and biased, each is clamped to the range @r{[0,1]}.
12203 Similarly, if the @code{ARB_imaging} extension is supported, each of the
12204 four color components may be scaled and biased after processing by the
12205 enabled convolution filter. That is, the red component is multiplied by
12206 @code{GL_POST_CONVOLUTION_RED_SCALE}, then added to
12207 @code{GL_POST_CONVOLUTION_RED_BIAS}; the green component is multiplied
12208 by @code{GL_POST_CONVOLUTION_GREEN_SCALE}, then added to
12209 @code{GL_POST_CONVOLUTION_GREEN_BIAS}; the blue component is multiplied
12210 by @code{GL_POST_CONVOLUTION_BLUE_SCALE}, then added to
12211 @code{GL_POST_CONVOLUTION_BLUE_BIAS}; and the alpha component is
12212 multiplied by @code{GL_POST_CONVOLUTION_ALPHA_SCALE}, then added to
12213 @code{GL_POST_CONVOLUTION_ALPHA_BIAS}. After all four color components
12214 are scaled and biased, each is clamped to the range @r{[0,1]}.
12216 @item @var{Color index}
12217 Each color index is shifted left by @code{GL_INDEX_SHIFT} bits; any bits
12218 beyond the number of fraction bits carried by the fixed-point index are
12219 filled with zeros. If @code{GL_INDEX_SHIFT} is negative, the shift is to
12220 the right, again zero filled. Then @code{GL_INDEX_OFFSET} is added to
12221 the index. @code{GL_INDEX_SHIFT} and @code{GL_INDEX_OFFSET} are
12222 specified with @code{glPixelTransfer}.
12224 From this point, operation diverges depending on the required format of
12225 the resulting pixels. If the resulting pixels are to be written to a
12226 color index buffer, or if they are being read back to client memory in
12227 @code{GL_COLOR_INDEX} format, the pixels continue to be treated as
12228 indices. If @code{GL_MAP_COLOR} is true, each index is masked by
12229 @r{2^@var{n}-1}, where @r{@var{n}} is @code{GL_PIXEL_MAP_I_TO_I_SIZE},
12230 then replaced by the contents of @code{GL_PIXEL_MAP_I_TO_I} indexed by
12231 the masked value. @code{GL_MAP_COLOR} is specified with
12232 @code{glPixelTransfer}. The contents of the index map is specified with
12235 If the resulting pixels are to be written to an RGBA color buffer, or if
12236 they are read back to client memory in a format other than
12237 @code{GL_COLOR_INDEX}, the pixels are converted from indices to colors
12238 by referencing the four maps @code{GL_PIXEL_MAP_I_TO_R},
12239 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
12240 @code{GL_PIXEL_MAP_I_TO_A}. Before being dereferenced, the index is
12241 masked by @r{2^@var{n}-1}, where @r{@var{n}} is
12242 @code{GL_PIXEL_MAP_I_TO_R_SIZE} for the red map,
12243 @code{GL_PIXEL_MAP_I_TO_G_SIZE} for the green map,
12244 @code{GL_PIXEL_MAP_I_TO_B_SIZE} for the blue map, and
12245 @code{GL_PIXEL_MAP_I_TO_A_SIZE} for the alpha map. All components taken
12246 from the maps are then clamped to the range @r{[0,1]}. The contents of
12247 the four maps is specified with @code{glPixelMap}.
12250 Each depth value is multiplied by @code{GL_DEPTH_SCALE}, added to
12251 @code{GL_DEPTH_BIAS}, then clamped to the range @r{[0,1]}.
12253 @item @var{Stencil}
12254 Each index is shifted @code{GL_INDEX_SHIFT} bits just as a color index
12255 is, then added to @code{GL_INDEX_OFFSET}. If @code{GL_MAP_STENCIL} is
12256 true, each index is masked by @r{2^@var{n}-1}, where @r{@var{n}} is
12257 @code{GL_PIXEL_MAP_S_TO_S_SIZE}, then replaced by the contents of
12258 @code{GL_PIXEL_MAP_S_TO_S} indexed by the masked value.
12262 The following table gives the type, initial value, and range of valid
12263 values for each of the pixel transfer parameters that are set with
12264 @code{glPixelTransfer}.
12269 @item @strong{@var{pname}}
12270 @strong{Type}, @strong{Initial Value}, @strong{Valid Range}
12272 @item @code{GL_MAP_COLOR}
12273 boolean , false , true/false
12275 @item @code{GL_MAP_STENCIL}
12276 boolean , false , true/false
12278 @item @code{GL_INDEX_SHIFT}
12279 integer , 0 , @r{(-∞,∞)}
12281 @item @code{GL_INDEX_OFFSET}
12282 integer , 0 , @r{(-∞,∞)}
12284 @item @code{GL_RED_SCALE}
12285 float , 1 , @r{(-∞,∞)}
12287 @item @code{GL_GREEN_SCALE}
12288 float , 1 , @r{(-∞,∞)}
12290 @item @code{GL_BLUE_SCALE}
12291 float , 1 , @r{(-∞,∞)}
12293 @item @code{GL_ALPHA_SCALE}
12294 float , 1 , @r{(-∞,∞)}
12296 @item @code{GL_DEPTH_SCALE}
12297 float , 1 , @r{(-∞,∞)}
12299 @item @code{GL_RED_BIAS}
12300 float , 0 , @r{(-∞,∞)}
12302 @item @code{GL_GREEN_BIAS}
12303 float , 0 , @r{(-∞,∞)}
12305 @item @code{GL_BLUE_BIAS}
12306 float , 0 , @r{(-∞,∞)}
12308 @item @code{GL_ALPHA_BIAS}
12309 float , 0 , @r{(-∞,∞)}
12311 @item @code{GL_DEPTH_BIAS}
12312 float , 0 , @r{(-∞,∞)}
12314 @item @code{GL_POST_COLOR_MATRIX_RED_SCALE}
12315 float , 1 , @r{(-∞,∞)}
12317 @item @code{GL_POST_COLOR_MATRIX_GREEN_SCALE}
12318 float , 1 , @r{(-∞,∞)}
12320 @item @code{GL_POST_COLOR_MATRIX_BLUE_SCALE}
12321 float , 1 , @r{(-∞,∞)}
12323 @item @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE}
12324 float , 1 , @r{(-∞,∞)}
12326 @item @code{GL_POST_COLOR_MATRIX_RED_BIAS}
12327 float , 0 , @r{(-∞,∞)}
12329 @item @code{GL_POST_COLOR_MATRIX_GREEN_BIAS}
12330 float , 0 , @r{(-∞,∞)}
12332 @item @code{GL_POST_COLOR_MATRIX_BLUE_BIAS}
12333 float , 0 , @r{(-∞,∞)}
12335 @item @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS}
12336 float , 0 , @r{(-∞,∞)}
12338 @item @code{GL_POST_CONVOLUTION_RED_SCALE}
12339 float , 1 , @r{(-∞,∞)}
12341 @item @code{GL_POST_CONVOLUTION_GREEN_SCALE}
12342 float , 1 , @r{(-∞,∞)}
12344 @item @code{GL_POST_CONVOLUTION_BLUE_SCALE}
12345 float , 1 , @r{(-∞,∞)}
12347 @item @code{GL_POST_CONVOLUTION_ALPHA_SCALE}
12348 float , 1 , @r{(-∞,∞)}
12350 @item @code{GL_POST_CONVOLUTION_RED_BIAS}
12351 float , 0 , @r{(-∞,∞)}
12353 @item @code{GL_POST_CONVOLUTION_GREEN_BIAS}
12354 float , 0 , @r{(-∞,∞)}
12356 @item @code{GL_POST_CONVOLUTION_BLUE_BIAS}
12357 float , 0 , @r{(-∞,∞)}
12359 @item @code{GL_POST_CONVOLUTION_ALPHA_BIAS}
12360 float , 0 , @r{(-∞,∞)}
12364 @code{glPixelTransferf} can be used to set any pixel transfer parameter.
12365 If the parameter type is boolean, 0 implies false and any other value
12366 implies true. If @var{pname} is an integer parameter, @var{param} is
12367 rounded to the nearest integer.
12369 Likewise, @code{glPixelTransferi} can be used to set any of the pixel
12370 transfer parameters. Boolean parameters are set to false if @var{param}
12371 is 0 and to true otherwise. @var{param} is converted to floating point
12372 before being assigned to real-valued parameters.
12374 @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted
12377 @code{GL_INVALID_OPERATION} is generated if @code{glPixelTransfer} is
12378 executed between the execution of @code{glBegin} and the corresponding
12379 execution of @code{glEnd}.
12383 @deftypefun void glPixelZoom xfactor yfactor
12384 Specify the pixel zoom factors.
12387 @item @var{xfactor}
12388 @itemx @var{yfactor}
12389 Specify the @r{@var{x}} and @r{@var{y}} zoom factors for pixel write
12394 @code{glPixelZoom} specifies values for the @r{@var{x}} and @r{@var{y}}
12395 zoom factors. During the execution of @code{glDrawPixels} or
12396 @code{glCopyPixels}, if (@r{@var{xr}}, @r{@var{yr}}) is the current
12397 raster position, and a given element is in the @r{@var{m}}th row and
12398 @r{@var{n}}th column of the pixel rectangle, then pixels whose centers
12399 are in the rectangle with corners at
12401 (@r{@var{xr}+@var{n}·@var{xfactor}}, @r{@var{yr}+@var{m}·@var{yfactor}})
12403 (@r{@var{xr}+(@var{n}+1,)·@var{xfactor}},
12404 @r{@var{yr}+(@var{m}+1,)·@var{yfactor}})
12406 are candidates for replacement. Any pixel whose center lies on the
12407 bottom or left edge of this rectangular region is also modified.
12409 Pixel zoom factors are not limited to positive values. Negative zoom
12410 factors reflect the resulting image about the current raster position.
12412 @code{GL_INVALID_OPERATION} is generated if @code{glPixelZoom} is
12413 executed between the execution of @code{glBegin} and the corresponding
12414 execution of @code{glEnd}.
12418 @deftypefun void glPointParameterf pname param
12419 @deftypefunx void glPointParameteri pname param
12420 Specify point parameters.
12424 Specifies a single-valued point parameter. @code{GL_POINT_SIZE_MIN},
12425 @code{GL_POINT_SIZE_MAX}, @code{GL_POINT_FADE_THRESHOLD_SIZE}, and
12426 @code{GL_POINT_SPRITE_COORD_ORIGIN} are accepted.
12429 Specifies the value that @var{pname} will be set to.
12433 The following values are accepted for @var{pname}:
12436 @item @code{GL_POINT_SIZE_MIN}
12439 @var{params} is a single floating-point value that specifies the minimum
12440 point size. The default value is 0.0.
12442 @item @code{GL_POINT_SIZE_MAX}
12445 @var{params} is a single floating-point value that specifies the maximum
12446 point size. The default value is 1.0.
12448 @item @code{GL_POINT_FADE_THRESHOLD_SIZE}
12451 @var{params} is a single floating-point value that specifies the
12452 threshold value to which point sizes are clamped if they exceed the
12453 specified value. The default value is 1.0.
12455 @item @code{GL_POINT_DISTANCE_ATTENUATION}
12458 @var{params} is an array of three floating-point values that specify the
12459 coefficients used for scaling the computed point size. The default
12460 values are @r{(1,00)}.
12462 @item @code{GL_POINT_SPRITE_COORD_ORIGIN}
12465 @var{params} is a single enum specifying the point sprite texture
12466 coordinate origin, either @code{GL_LOWER_LEFT} or @code{GL_UPPER_LEFT}.
12467 The default value is @code{GL_UPPER_LEFT}.
12471 @code{GL_INVALID_VALUE} is generated If the value specified for
12472 @code{GL_POINT_SIZE_MIN}, @code{GL_POINT_SIZE_MAX}, or
12473 @code{GL_POINT_FADE_THRESHOLD_SIZE} is less than zero.
12475 @code{GL_INVALID_ENUM} is generated If the value specified for
12476 @code{GL_POINT_SPRITE_COORD_ORIGIN} is not @code{GL_LOWER_LEFT} or
12477 @code{GL_UPPER_LEFT}.
12479 If the value for @code{GL_POINT_SIZE_MIN} is greater than
12480 @code{GL_POINT_SIZE_MAX}, the point size after clamping is undefined,
12481 but no error is generated.
12487 @deftypefun void glPointSize size
12488 Specify the diameter of rasterized points.
12492 Specifies the diameter of rasterized points. The initial value is 1.
12496 @code{glPointSize} specifies the rasterized diameter of both aliased and
12497 antialiased points. Using a point size other than 1 has different
12498 effects, depending on whether point antialiasing is enabled. To enable
12499 and disable point antialiasing, call @code{glEnable} and
12500 @code{glDisable} with argument @code{GL_POINT_SMOOTH}. Point
12501 antialiasing is initially disabled.
12503 The specified point size is multiplied with a distance attenuation
12504 factor and clamped to the specified point size range, and further
12505 clamped to the implementation-dependent point size range to produce the
12506 derived point size using
12508 @r{@var{pointSize}=@var{clamp}(@var{size}×√(1/@var{a}+@var{b}×@var{d}+@var{c}×@var{d}^2,,,),,)}
12510 where @r{@var{d}} is the eye-coordinate distance from the eye to the
12511 vertex, and @r{@var{a}}, @r{@var{b}}, and @r{@var{c}} are the distance
12512 attenuation coefficients (see @code{glPointParameter}).
12514 If multisampling is disabled, the computed point size is used as the
12517 If multisampling is enabled, the point may be faded by modifying the
12518 point alpha value (see @code{glSampleCoverage}) instead of allowing the
12519 point width to go below a given threshold (see @code{glPointParameter}).
12520 In this case, the width is further modified in the following manner:
12522 @r{@var{pointWidth}=@{(@var{pointSize}),
12523 (@var{threshold})(@var{pointSize}>=@var{threshold}),
12524 (@var{otherwise}),}
12526 The point alpha value is modified by computing:
12528 @r{@var{pointAlpha}=@{(1),
12529 ((@var{pointSize}/@var{threshold},)^2)(@var{pointSize}>=@var{threshold}),
12530 (@var{otherwise}),}
12532 If point antialiasing is disabled, the actual size is determined by
12533 rounding the supplied size to the nearest integer. (If the rounding
12534 results in the value 0, it is as if the point size were 1.) If the
12535 rounded size is odd, then the center point (@r{@var{x}}, @r{@var{y}}) of
12536 the pixel fragment that represents the point is computed as
12538 @r{(⌊@var{x}_@var{w},⌋+.5,⌊@var{y}_@var{w},⌋+.5)}
12540 where @r{@var{w}} subscripts indicate window coordinates. All pixels
12541 that lie within the square grid of the rounded size centered at
12542 (@r{@var{x}}, @r{@var{y}}) make up the fragment. If the size is even,
12543 the center point is
12545 @r{(⌊@var{x}_@var{w}+.5,⌋,⌊@var{y}_@var{w}+.5,⌋)}
12547 and the rasterized fragment's centers are the half-integer window
12548 coordinates within the square of the rounded size centered at
12549 @r{(@var{x},@var{y})}. All pixel fragments produced in rasterizing a
12550 nonantialiased point are assigned the same associated data, that of the
12551 vertex corresponding to the point.
12553 If antialiasing is enabled, then point rasterization produces a fragment
12554 for each pixel square that intersects the region lying within the circle
12555 having diameter equal to the current point size and centered at the
12556 point's @r{(@var{x}_@var{w},@var{y}_@var{w})}. The coverage value for
12557 each fragment is the window coordinate area of the intersection of the
12558 circular region with the corresponding pixel square. This value is saved
12559 and used in the final rasterization step. The data associated with each
12560 fragment is the data associated with the point being rasterized.
12562 Not all sizes are supported when point antialiasing is enabled. If an
12563 unsupported size is requested, the nearest supported size is used. Only
12564 size 1 is guaranteed to be supported; others depend on the
12565 implementation. To query the range of supported sizes and the size
12566 difference between supported sizes within the range, call @code{glGet}
12567 with arguments @code{GL_SMOOTH_POINT_SIZE_RANGE} and
12568 @code{GL_SMOOTH_POINT_SIZE_GRANULARITY}. For aliased points, query the
12569 supported ranges and granularity with @code{glGet} with arguments
12570 @code{GL_ALIASED_POINT_SIZE_RANGE}.
12572 @code{GL_INVALID_VALUE} is generated if @var{size} is less than or equal
12575 @code{GL_INVALID_OPERATION} is generated if @code{glPointSize} is
12576 executed between the execution of @code{glBegin} and the corresponding
12577 execution of @code{glEnd}.
12581 @deftypefun void glPolygonMode face mode
12582 Select a polygon rasterization mode.
12586 Specifies the polygons that @var{mode} applies to. Must be
12587 @code{GL_FRONT} for front-facing polygons, @code{GL_BACK} for
12588 back-facing polygons, or @code{GL_FRONT_AND_BACK} for front- and
12589 back-facing polygons.
12592 Specifies how polygons will be rasterized. Accepted values are
12593 @code{GL_POINT}, @code{GL_LINE}, and @code{GL_FILL}. The initial value
12594 is @code{GL_FILL} for both front- and back-facing polygons.
12598 @code{glPolygonMode} controls the interpretation of polygons for
12599 rasterization. @var{face} describes which polygons @var{mode} applies
12600 to: front-facing polygons (@code{GL_FRONT}), back-facing polygons
12601 (@code{GL_BACK}), or both (@code{GL_FRONT_AND_BACK}). The polygon mode
12602 affects only the final rasterization of polygons. In particular, a
12603 polygon's vertices are lit and the polygon is clipped and possibly
12604 culled before these modes are applied.
12606 Three modes are defined and can be specified in @var{mode}:
12609 @item @code{GL_POINT}
12610 Polygon vertices that are marked as the start of a boundary edge are
12611 drawn as points. Point attributes such as @code{GL_POINT_SIZE} and
12612 @code{GL_POINT_SMOOTH} control the rasterization of the points. Polygon
12613 rasterization attributes other than @code{GL_POLYGON_MODE} have no
12616 @item @code{GL_LINE}
12617 Boundary edges of the polygon are drawn as line segments. They are
12618 treated as connected line segments for line stippling; the line stipple
12619 counter and pattern are not reset between segments (see
12620 @code{glLineStipple}). Line attributes such as @code{GL_LINE_WIDTH} and
12621 @code{GL_LINE_SMOOTH} control the rasterization of the lines. Polygon
12622 rasterization attributes other than @code{GL_POLYGON_MODE} have no
12625 @item @code{GL_FILL}
12626 The interior of the polygon is filled. Polygon attributes such as
12627 @code{GL_POLYGON_STIPPLE} and @code{GL_POLYGON_SMOOTH} control the
12628 rasterization of the polygon.
12632 @code{GL_INVALID_ENUM} is generated if either @var{face} or @var{mode}
12633 is not an accepted value.
12635 @code{GL_INVALID_OPERATION} is generated if @code{glPolygonMode} is
12636 executed between the execution of @code{glBegin} and the corresponding
12637 execution of @code{glEnd}.
12641 @deftypefun void glPolygonOffset factor units
12642 Set the scale and units used to calculate depth values.
12646 Specifies a scale factor that is used to create a variable depth offset
12647 for each polygon. The initial value is 0.
12650 Is multiplied by an implementation-specific value to create a constant
12651 depth offset. The initial value is 0.
12655 When @code{GL_POLYGON_OFFSET_FILL}, @code{GL_POLYGON_OFFSET_LINE}, or
12656 @code{GL_POLYGON_OFFSET_POINT} is enabled, each fragment's @var{depth}
12657 value will be offset after it is interpolated from the @var{depth}
12658 values of the appropriate vertices. The value of the offset is
12659 @r{@var{factor}×@var{DZ}+@var{r}×@var{units}}, where @r{@var{DZ}} is a
12660 measurement of the change in depth relative to the screen area of the
12661 polygon, and @r{@var{r}} is the smallest value that is guaranteed to
12662 produce a resolvable offset for a given implementation. The offset is
12663 added before the depth test is performed and before the value is written
12664 into the depth buffer.
12666 @code{glPolygonOffset} is useful for rendering hidden-line images, for
12667 applying decals to surfaces, and for rendering solids with highlighted
12670 @code{GL_INVALID_OPERATION} is generated if @code{glPolygonOffset} is
12671 executed between the execution of @code{glBegin} and the corresponding
12672 execution of @code{glEnd}.
12676 @deftypefun void glPolygonStipple pattern
12677 Set the polygon stippling pattern.
12680 @item @var{pattern}
12681 Specifies a pointer to a @r{32×32} stipple pattern that will be unpacked
12682 from memory in the same way that @code{glDrawPixels} unpacks pixels.
12686 Polygon stippling, like line stippling (see @code{glLineStipple}), masks
12687 out certain fragments produced by rasterization, creating a pattern.
12688 Stippling is independent of polygon antialiasing.
12690 @var{pattern} is a pointer to a @r{32×32} stipple pattern that is stored
12691 in memory just like the pixel data supplied to a @code{glDrawPixels}
12692 call with height and @var{width} both equal to 32, a pixel format of
12693 @code{GL_COLOR_INDEX}, and data type of @code{GL_BITMAP}. That is, the
12694 stipple pattern is represented as a @r{32×32} array of 1-bit color
12695 indices packed in unsigned bytes. @code{glPixelStore} parameters like
12696 @code{GL_UNPACK_SWAP_BYTES} and @code{GL_UNPACK_LSB_FIRST} affect the
12697 assembling of the bits into a stipple pattern. Pixel transfer operations
12698 (shift, offset, pixel map) are not applied to the stipple image,
12701 If a non-zero named buffer object is bound to the
12702 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
12703 stipple pattern is specified, @var{pattern} is treated as a byte offset
12704 into the buffer object's data store.
12706 To enable and disable polygon stippling, call @code{glEnable} and
12707 @code{glDisable} with argument @code{GL_POLYGON_STIPPLE}. Polygon
12708 stippling is initially disabled. If it's enabled, a rasterized polygon
12709 fragment with window coordinates @r{@var{x}_@var{w}} and
12710 @r{@var{y}_@var{w}} is sent to the next stage of the GL if and only if
12711 the (@r{@var{x}_@var{w}%32})th bit in the (@r{@var{y}_@var{w}%32})th row
12712 of the stipple pattern is 1 (one). When polygon stippling is disabled,
12713 it is as if the stipple pattern consists of all 1's.
12715 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
12716 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
12717 object's data store is currently mapped.
12719 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
12720 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
12721 would be unpacked from the buffer object such that the memory reads
12722 required would exceed the data store size.
12724 @code{GL_INVALID_OPERATION} is generated if @code{glPolygonStipple} is
12725 executed between the execution of @code{glBegin} and the corresponding
12726 execution of @code{glEnd}.
12730 @deftypefun void glPrioritizeTextures n textures priorities
12731 Set texture residence priority.
12735 Specifies the number of textures to be prioritized.
12737 @item @var{textures}
12738 Specifies an array containing the names of the textures to be
12741 @item @var{priorities}
12742 Specifies an array containing the texture priorities. A priority given
12743 in an element of @var{priorities} applies to the texture named by the
12744 corresponding element of @var{textures}.
12748 @code{glPrioritizeTextures} assigns the @var{n} texture priorities given
12749 in @var{priorities} to the @var{n} textures named in @var{textures}.
12751 The GL establishes a ``working set'' of textures that are resident in
12752 texture memory. These textures may be bound to a texture target much
12753 more efficiently than textures that are not resident. By specifying a
12754 priority for each texture, @code{glPrioritizeTextures} allows
12755 applications to guide the GL implementation in determining which
12756 textures should be resident.
12758 The priorities given in @var{priorities} are clamped to the range
12759 @r{[0,1]} before they are assigned. 0 indicates the lowest priority;
12760 textures with priority 0 are least likely to be resident. 1 indicates
12761 the highest priority; textures with priority 1 are most likely to be
12762 resident. However, textures are not guaranteed to be resident until they
12765 @code{glPrioritizeTextures} silently ignores attempts to prioritize
12766 texture 0 or any texture name that does not correspond to an existing
12769 @code{glPrioritizeTextures} does not require that any of the textures
12770 named by @var{textures} be bound to a texture target.
12771 @code{glTexParameter} may also be used to set a texture's priority, but
12772 only if the texture is currently bound. This is the only way to set the
12773 priority of a default texture.
12775 @code{GL_INVALID_VALUE} is generated if @var{n} is negative.
12777 @code{GL_INVALID_OPERATION} is generated if @code{glPrioritizeTextures}
12778 is executed between the execution of @code{glBegin} and the
12779 corresponding execution of @code{glEnd}.
12783 @deftypefun void glPushAttrib mask
12784 @deftypefunx void glPopAttrib
12785 Push and pop the server attribute stack.
12789 Specifies a mask that indicates which attributes to save. Values for
12790 @var{mask} are listed below.
12794 @code{glPushAttrib} takes one argument, a mask that indicates which
12795 groups of state variables to save on the attribute stack. Symbolic
12796 constants are used to set bits in the mask. @var{mask} is typically
12797 constructed by specifying the bitwise-or of several of these constants
12798 together. The special mask @code{GL_ALL_ATTRIB_BITS} can be used to save
12799 all stackable states.
12801 The symbolic mask constants and their associated GL state are as follows
12802 (the second column lists which attributes are saved):
12807 @item @code{GL_ACCUM_BUFFER_BIT}
12808 Accumulation buffer clear value
12810 @item @code{GL_COLOR_BUFFER_BIT}
12811 @code{GL_ALPHA_TEST} enable bit
12814 Alpha test function and reference value
12817 @code{GL_BLEND} enable bit
12820 Blending source and destination functions
12823 Constant blend color
12829 @code{GL_DITHER} enable bit
12832 @code{GL_DRAW_BUFFER} setting
12835 @code{GL_COLOR_LOGIC_OP} enable bit
12838 @code{GL_INDEX_LOGIC_OP} enable bit
12844 Color mode and index mode clear values
12847 Color mode and index mode writemasks
12849 @item @code{GL_CURRENT_BIT}
12853 Current color index
12856 Current normal vector
12859 Current texture coordinates
12862 Current raster position
12865 @code{GL_CURRENT_RASTER_POSITION_VALID} flag
12868 RGBA color associated with current raster position
12871 Color index associated with current raster position
12874 Texture coordinates associated with current raster position
12877 @code{GL_EDGE_FLAG} flag
12879 @item @code{GL_DEPTH_BUFFER_BIT}
12880 @code{GL_DEPTH_TEST} enable bit
12883 Depth buffer test function
12886 Depth buffer clear value
12889 @code{GL_DEPTH_WRITEMASK} enable bit
12891 @item @code{GL_ENABLE_BIT}
12892 @code{GL_ALPHA_TEST} flag
12895 @code{GL_AUTO_NORMAL} flag
12898 @code{GL_BLEND} flag
12901 Enable bits for the user-definable clipping planes
12904 @code{GL_COLOR_MATERIAL}
12907 @code{GL_CULL_FACE} flag
12910 @code{GL_DEPTH_TEST} flag
12913 @code{GL_DITHER} flag
12919 @code{GL_LIGHT}@var{i} where @code{0} <= @var{i} < @code{GL_MAX_LIGHTS}
12922 @code{GL_LIGHTING} flag
12925 @code{GL_LINE_SMOOTH} flag
12928 @code{GL_LINE_STIPPLE} flag
12931 @code{GL_COLOR_LOGIC_OP} flag
12934 @code{GL_INDEX_LOGIC_OP} flag
12937 @code{GL_MAP1_}@var{x} where @var{x} is a map type
12940 @code{GL_MAP2_}@var{x} where @var{x} is a map type
12943 @code{GL_MULTISAMPLE} flag
12946 @code{GL_NORMALIZE} flag
12949 @code{GL_POINT_SMOOTH} flag
12952 @code{GL_POLYGON_OFFSET_LINE} flag
12955 @code{GL_POLYGON_OFFSET_FILL} flag
12958 @code{GL_POLYGON_OFFSET_POINT} flag
12961 @code{GL_POLYGON_SMOOTH} flag
12964 @code{GL_POLYGON_STIPPLE} flag
12967 @code{GL_SAMPLE_ALPHA_TO_COVERAGE} flag
12970 @code{GL_SAMPLE_ALPHA_TO_ONE} flag
12973 @code{GL_SAMPLE_COVERAGE} flag
12976 @code{GL_SCISSOR_TEST} flag
12979 @code{GL_STENCIL_TEST} flag
12982 @code{GL_TEXTURE_1D} flag
12985 @code{GL_TEXTURE_2D} flag
12988 @code{GL_TEXTURE_3D} flag
12991 Flags @code{GL_TEXTURE_GEN_}@var{x} where @var{x} is S, T, R, or Q
12993 @item @code{GL_EVAL_BIT}
12994 @code{GL_MAP1_}@var{x} enable bits, where @var{x} is a map type
12997 @code{GL_MAP2_}@var{x} enable bits, where @var{x} is a map type
13000 1D grid endpoints and divisions
13003 2D grid endpoints and divisions
13006 @code{GL_AUTO_NORMAL} enable bit
13008 @item @code{GL_FOG_BIT}
13009 @code{GL_FOG} enable bit
13027 @code{GL_FOG_MODE} value
13029 @item @code{GL_HINT_BIT}
13030 @code{GL_PERSPECTIVE_CORRECTION_HINT} setting
13033 @code{GL_POINT_SMOOTH_HINT} setting
13036 @code{GL_LINE_SMOOTH_HINT} setting
13039 @code{GL_POLYGON_SMOOTH_HINT} setting
13042 @code{GL_FOG_HINT} setting
13045 @code{GL_GENERATE_MIPMAP_HINT} setting
13048 @code{GL_TEXTURE_COMPRESSION_HINT} setting
13050 @item @code{GL_LIGHTING_BIT}
13051 @code{GL_COLOR_MATERIAL} enable bit
13054 @code{GL_COLOR_MATERIAL_FACE} value
13057 Color material parameters that are tracking the current color
13060 Ambient scene color
13063 @code{GL_LIGHT_MODEL_LOCAL_VIEWER} value
13066 @code{GL_LIGHT_MODEL_TWO_SIDE} setting
13069 @code{GL_LIGHTING} enable bit
13072 Enable bit for each light
13075 Ambient, diffuse, and specular intensity for each light
13078 Direction, position, exponent, and cutoff angle for each light
13081 Constant, linear, and quadratic attenuation factors for each light
13084 Ambient, diffuse, specular, and emissive color for each material
13087 Ambient, diffuse, and specular color indices for each material
13090 Specular exponent for each material
13093 @code{GL_SHADE_MODEL} setting
13095 @item @code{GL_LINE_BIT}
13096 @code{GL_LINE_SMOOTH} flag
13099 @code{GL_LINE_STIPPLE} enable bit
13102 Line stipple pattern and repeat counter
13107 @item @code{GL_LIST_BIT}
13108 @code{GL_LIST_BASE} setting
13110 @item @code{GL_MULTISAMPLE_BIT}
13111 @code{GL_MULTISAMPLE} flag
13114 @code{GL_SAMPLE_ALPHA_TO_COVERAGE} flag
13117 @code{GL_SAMPLE_ALPHA_TO_ONE} flag
13120 @code{GL_SAMPLE_COVERAGE} flag
13123 @code{GL_SAMPLE_COVERAGE_VALUE} value
13126 @code{GL_SAMPLE_COVERAGE_INVERT} value
13128 @item @code{GL_PIXEL_MODE_BIT}
13129 @code{GL_RED_BIAS} and @code{GL_RED_SCALE} settings
13132 @code{GL_GREEN_BIAS} and @code{GL_GREEN_SCALE} values
13135 @code{GL_BLUE_BIAS} and @code{GL_BLUE_SCALE}
13138 @code{GL_ALPHA_BIAS} and @code{GL_ALPHA_SCALE}
13141 @code{GL_DEPTH_BIAS} and @code{GL_DEPTH_SCALE}
13144 @code{GL_INDEX_OFFSET} and @code{GL_INDEX_SHIFT} values
13147 @code{GL_MAP_COLOR} and @code{GL_MAP_STENCIL} flags
13150 @code{GL_ZOOM_X} and @code{GL_ZOOM_Y} factors
13153 @code{GL_READ_BUFFER} setting
13155 @item @code{GL_POINT_BIT}
13156 @code{GL_POINT_SMOOTH} flag
13161 @item @code{GL_POLYGON_BIT}
13162 @code{GL_CULL_FACE} enable bit
13165 @code{GL_CULL_FACE_MODE} value
13168 @code{GL_FRONT_FACE} indicator
13171 @code{GL_POLYGON_MODE} setting
13174 @code{GL_POLYGON_SMOOTH} flag
13177 @code{GL_POLYGON_STIPPLE} enable bit
13180 @code{GL_POLYGON_OFFSET_FILL} flag
13183 @code{GL_POLYGON_OFFSET_LINE} flag
13186 @code{GL_POLYGON_OFFSET_POINT} flag
13189 @code{GL_POLYGON_OFFSET_FACTOR}
13192 @code{GL_POLYGON_OFFSET_UNITS}
13194 @item @code{GL_POLYGON_STIPPLE_BIT}
13195 Polygon stipple image
13197 @item @code{GL_SCISSOR_BIT}
13198 @code{GL_SCISSOR_TEST} flag
13203 @item @code{GL_STENCIL_BUFFER_BIT}
13204 @code{GL_STENCIL_TEST} enable bit
13207 Stencil function and reference value
13213 Stencil fail, pass, and depth buffer pass actions
13216 Stencil buffer clear value
13219 Stencil buffer writemask
13221 @item @code{GL_TEXTURE_BIT}
13222 Enable bits for the four texture coordinates
13225 Border color for each texture image
13228 Minification function for each texture image
13231 Magnification function for each texture image
13234 Texture coordinates and wrap mode for each texture image
13237 Color and mode for each texture environment
13240 Enable bits @code{GL_TEXTURE_GEN_}@var{x}, @var{x} is S, T, R, and Q
13243 @code{GL_TEXTURE_GEN_MODE} setting for S, T, R, and Q
13246 @code{glTexGen} plane equations for S, T, R, and Q
13249 Current texture bindings (for example, @code{GL_TEXTURE_BINDING_2D})
13251 @item @code{GL_TRANSFORM_BIT}
13252 Coefficients of the six clipping planes
13255 Enable bits for the user-definable clipping planes
13258 @code{GL_MATRIX_MODE} value
13261 @code{GL_NORMALIZE} flag
13264 @code{GL_RESCALE_NORMAL} flag
13266 @item @code{GL_VIEWPORT_BIT}
13267 Depth range (near and far)
13270 Viewport origin and extent
13274 @code{glPopAttrib} restores the values of the state variables saved with
13275 the last @code{glPushAttrib} command. Those not saved are left
13278 It is an error to push attributes onto a full stack or to pop attributes
13279 off an empty stack. In either case, the error flag is set and no other
13280 change is made to GL state.
13282 Initially, the attribute stack is empty.
13284 @code{GL_STACK_OVERFLOW} is generated if @code{glPushAttrib} is called
13285 while the attribute stack is full.
13287 @code{GL_STACK_UNDERFLOW} is generated if @code{glPopAttrib} is called
13288 while the attribute stack is empty.
13290 @code{GL_INVALID_OPERATION} is generated if @code{glPushAttrib} or
13291 @code{glPopAttrib} is executed between the execution of @code{glBegin}
13292 and the corresponding execution of @code{glEnd}.
13296 @deftypefun void glPushClientAttrib mask
13297 @deftypefunx void glPopClientAttrib
13298 Push and pop the client attribute stack.
13302 Specifies a mask that indicates which attributes to save. Values for
13303 @var{mask} are listed below.
13307 @code{glPushClientAttrib} takes one argument, a mask that indicates
13308 which groups of client-state variables to save on the client attribute
13309 stack. Symbolic constants are used to set bits in the mask. @var{mask}
13310 is typically constructed by specifying the bitwise-or of several of
13311 these constants together. The special mask
13312 @code{GL_CLIENT_ALL_ATTRIB_BITS} can be used to save all stackable
13315 The symbolic mask constants and their associated GL client state are as
13316 follows (the second column lists which attributes are saved):
13318 @code{GL_CLIENT_PIXEL_STORE_BIT} Pixel storage modes
13319 @code{GL_CLIENT_VERTEX_ARRAY_BIT} Vertex arrays (and enables)
13321 @code{glPopClientAttrib} restores the values of the client-state
13322 variables saved with the last @code{glPushClientAttrib}. Those not saved
13323 are left unchanged.
13325 It is an error to push attributes onto a full client attribute stack or
13326 to pop attributes off an empty stack. In either case, the error flag is
13327 set, and no other change is made to GL state.
13329 Initially, the client attribute stack is empty.
13331 @code{GL_STACK_OVERFLOW} is generated if @code{glPushClientAttrib} is
13332 called while the attribute stack is full.
13334 @code{GL_STACK_UNDERFLOW} is generated if @code{glPopClientAttrib} is
13335 called while the attribute stack is empty.
13339 @deftypefun void glPushMatrix
13340 @deftypefunx void glPopMatrix
13341 Push and pop the current matrix stack.
13343 There is a stack of matrices for each of the matrix modes. In
13344 @code{GL_MODELVIEW} mode, the stack depth is at least 32. In the other
13345 modes, @code{GL_COLOR}, @code{GL_PROJECTION}, and @code{GL_TEXTURE}, the
13346 depth is at least 2. The current matrix in any mode is the matrix on the
13347 top of the stack for that mode.
13349 @code{glPushMatrix} pushes the current matrix stack down by one,
13350 duplicating the current matrix. That is, after a @code{glPushMatrix}
13351 call, the matrix on top of the stack is identical to the one below it.
13353 @code{glPopMatrix} pops the current matrix stack, replacing the current
13354 matrix with the one below it on the stack.
13356 Initially, each of the stacks contains one matrix, an identity matrix.
13358 It is an error to push a full matrix stack or to pop a matrix stack that
13359 contains only a single matrix. In either case, the error flag is set and
13360 no other change is made to GL state.
13362 @code{GL_STACK_OVERFLOW} is generated if @code{glPushMatrix} is called
13363 while the current matrix stack is full.
13365 @code{GL_STACK_UNDERFLOW} is generated if @code{glPopMatrix} is called
13366 while the current matrix stack contains only a single matrix.
13368 @code{GL_INVALID_OPERATION} is generated if @code{glPushMatrix} or
13369 @code{glPopMatrix} is executed between the execution of @code{glBegin}
13370 and the corresponding execution of @code{glEnd}.
13374 @deftypefun void glPushName name
13375 @deftypefunx void glPopName
13376 Push and pop the name stack.
13380 Specifies a name that will be pushed onto the name stack.
13384 The name stack is used during selection mode to allow sets of rendering
13385 commands to be uniquely identified. It consists of an ordered set of
13386 unsigned integers and is initially empty.
13388 @code{glPushName} causes @var{name} to be pushed onto the name stack.
13389 @code{glPopName} pops one name off the top of the stack.
13391 The maximum name stack depth is implementation-dependent; call
13392 @code{GL_MAX_NAME_STACK_DEPTH} to find out the value for a particular
13393 implementation. It is an error to push a name onto a full stack or to
13394 pop a name off an empty stack. It is also an error to manipulate the
13395 name stack between the execution of @code{glBegin} and the corresponding
13396 execution of @code{glEnd}. In any of these cases, the error flag is set
13397 and no other change is made to GL state.
13399 The name stack is always empty while the render mode is not
13400 @code{GL_SELECT}. Calls to @code{glPushName} or @code{glPopName} while
13401 the render mode is not @code{GL_SELECT} are ignored.
13403 @code{GL_STACK_OVERFLOW} is generated if @code{glPushName} is called
13404 while the name stack is full.
13406 @code{GL_STACK_UNDERFLOW} is generated if @code{glPopName} is called
13407 while the name stack is empty.
13409 @code{GL_INVALID_OPERATION} is generated if @code{glPushName} or
13410 @code{glPopName} is executed between a call to @code{glBegin} and the
13411 corresponding call to @code{glEnd}.
13415 @deftypefun void glRasterPos2i x y
13416 @deftypefunx void glRasterPos2f x y
13417 @deftypefunx void glRasterPos3i x y z
13418 @deftypefunx void glRasterPos3f x y z
13419 @deftypefunx void glRasterPos4i x y z w
13420 @deftypefunx void glRasterPos4f x y z w
13421 Specify the raster position for pixel operations.
13428 Specify the @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}
13429 object coordinates (if present) for the raster position.
13433 The GL maintains a 3D position in window coordinates. This position,
13434 called the raster position, is used to position pixel and bitmap write
13435 operations. It is maintained with subpixel accuracy. See
13436 @code{glBitmap}, @code{glDrawPixels}, and @code{glCopyPixels}.
13438 The current raster position consists of three window coordinates
13439 (@r{@var{x}}, @r{@var{y}}, @r{@var{z}}), a clip coordinate value
13440 (@r{@var{w}}), an eye coordinate distance, a valid bit, and associated
13441 color data and texture coordinates. The @r{@var{w}} coordinate is a clip
13442 coordinate, because @r{@var{w}} is not projected to window coordinates.
13443 @code{glRasterPos4} specifies object coordinates @r{@var{x}},
13444 @r{@var{y}}, @r{@var{z}}, and @r{@var{w}} explicitly.
13445 @code{glRasterPos3} specifies object coordinate @r{@var{x}},
13446 @r{@var{y}}, and @r{@var{z}} explicitly, while @r{@var{w}} is implicitly
13447 set to 1. @code{glRasterPos2} uses the argument values for @r{@var{x}}
13448 and @r{@var{y}} while implicitly setting @r{@var{z}} and @r{@var{w}} to
13451 The object coordinates presented by @code{glRasterPos} are treated just
13452 like those of a @code{glVertex} command: They are transformed by the
13453 current modelview and projection matrices and passed to the clipping
13454 stage. If the vertex is not culled, then it is projected and scaled to
13455 window coordinates, which become the new current raster position, and
13456 the @code{GL_CURRENT_RASTER_POSITION_VALID} flag is set. If the vertex
13457 @var{is} culled, then the valid bit is cleared and the current raster
13458 position and associated color and texture coordinates are undefined.
13460 The current raster position also includes some associated color data and
13461 texture coordinates. If lighting is enabled, then
13462 @code{GL_CURRENT_RASTER_COLOR} (in RGBA mode) or
13463 @code{GL_CURRENT_RASTER_INDEX} (in color index mode) is set to the color
13464 produced by the lighting calculation (see @code{glLight},
13465 @code{glLightModel}, and @code{glShadeModel}). If lighting is disabled,
13466 current color (in RGBA mode, state variable @code{GL_CURRENT_COLOR}) or
13467 color index (in color index mode, state variable
13468 @code{GL_CURRENT_INDEX}) is used to update the current raster color.
13469 @code{GL_CURRENT_RASTER_SECONDARY_COLOR} (in RGBA mode) is likewise
13472 Likewise, @code{GL_CURRENT_RASTER_TEXTURE_COORDS} is updated as a
13473 function of @code{GL_CURRENT_TEXTURE_COORDS}, based on the texture
13474 matrix and the texture generation functions (see @code{glTexGen}).
13475 Finally, the distance from the origin of the eye coordinate system to
13476 the vertex as transformed by only the modelview matrix replaces
13477 @code{GL_CURRENT_RASTER_DISTANCE}.
13479 Initially, the current raster position is (0, 0, 0, 1), the current
13480 raster distance is 0, the valid bit is set, the associated RGBA color is
13481 (1, 1, 1, 1), the associated color index is 1, and the associated
13482 texture coordinates are (0, 0, 0, 1). In RGBA mode,
13483 @code{GL_CURRENT_RASTER_INDEX} is always 1; in color index mode, the
13484 current raster RGBA color always maintains its initial value.
13486 @code{GL_INVALID_OPERATION} is generated if @code{glRasterPos} is
13487 executed between the execution of @code{glBegin} and the corresponding
13488 execution of @code{glEnd}.
13492 @deftypefun void glReadBuffer mode
13493 Select a color buffer source for pixels.
13497 Specifies a color buffer. Accepted values are @code{GL_FRONT_LEFT},
13498 @code{GL_FRONT_RIGHT}, @code{GL_BACK_LEFT}, @code{GL_BACK_RIGHT},
13499 @code{GL_FRONT}, @code{GL_BACK}, @code{GL_LEFT}, @code{GL_RIGHT}, and
13500 @code{GL_AUX}@var{i}, where @var{i} is between 0 and the value of
13501 @code{GL_AUX_BUFFERS} minus 1.
13505 @code{glReadBuffer} specifies a color buffer as the source for
13506 subsequent @code{glReadPixels}, @code{glCopyTexImage1D},
13507 @code{glCopyTexImage2D}, @code{glCopyTexSubImage1D},
13508 @code{glCopyTexSubImage2D}, @code{glCopyTexSubImage3D}, and
13509 @code{glCopyPixels} commands. @var{mode} accepts one of twelve or more
13510 predefined values. (@code{GL_AUX0} through @code{GL_AUX3} are always
13511 defined.) In a fully configured system, @code{GL_FRONT}, @code{GL_LEFT},
13512 and @code{GL_FRONT_LEFT} all name the front left buffer,
13513 @code{GL_FRONT_RIGHT} and @code{GL_RIGHT} name the front right buffer,
13514 and @code{GL_BACK_LEFT} and @code{GL_BACK} name the back left buffer.
13516 Nonstereo double-buffered configurations have only a front left and a
13517 back left buffer. Single-buffered configurations have a front left and a
13518 front right buffer if stereo, and only a front left buffer if nonstereo.
13519 It is an error to specify a nonexistent buffer to @code{glReadBuffer}.
13521 @var{mode} is initially @code{GL_FRONT} in single-buffered
13522 configurations and @code{GL_BACK} in double-buffered configurations.
13524 @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of the
13525 twelve (or more) accepted values.
13527 @code{GL_INVALID_OPERATION} is generated if @var{mode} specifies a
13528 buffer that does not exist.
13530 @code{GL_INVALID_OPERATION} is generated if @code{glReadBuffer} is
13531 executed between the execution of @code{glBegin} and the corresponding
13532 execution of @code{glEnd}.
13536 @deftypefun void glReadPixels x y width height format type data
13537 Read a block of pixels from the frame buffer.
13542 Specify the window coordinates of the first pixel that is read from the
13543 frame buffer. This location is the lower left corner of a rectangular
13547 @itemx @var{height}
13548 Specify the dimensions of the pixel rectangle. @var{width} and
13549 @var{height} of one correspond to a single pixel.
13552 Specifies the format of the pixel data. The following symbolic values
13553 are accepted: @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX},
13554 @code{GL_DEPTH_COMPONENT}, @code{GL_RED}, @code{GL_GREEN},
13555 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
13556 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
13557 @code{GL_LUMINANCE_ALPHA}.
13560 Specifies the data type of the pixel data. Must be one of
13561 @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
13562 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
13563 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
13564 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
13565 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
13566 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
13567 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
13568 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
13569 or @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
13572 Returns the pixel data.
13576 @code{glReadPixels} returns pixel data from the frame buffer, starting
13577 with the pixel whose lower left corner is at location (@var{x},
13578 @var{y}), into client memory starting at location @var{data}. Several
13579 parameters control the processing of the pixel data before it is placed
13580 into client memory. These parameters are set with three commands:
13581 @code{glPixelStore}, @code{glPixelTransfer}, and @code{glPixelMap}. This
13582 reference page describes the effects on @code{glReadPixels} of most, but
13583 not all of the parameters specified by these three commands.
13585 If a non-zero named buffer object is bound to the
13586 @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a
13587 block of pixels is requested, @var{data} is treated as a byte offset
13588 into the buffer object's data store rather than a pointer to client
13591 When the @code{ARB_imaging} extension is supported, the pixel data may
13592 be processed by additional operations including color table lookup,
13593 color matrix transformations, convolutions, histograms, and minimum and
13594 maximum pixel value computations.
13596 @code{glReadPixels} returns values from each pixel with lower left
13597 corner at @r{(@var{x}+@var{i},@var{y}+@var{j})} for
13598 @r{0<=@var{i}<@var{width}} and @r{0<=@var{j}<@var{height}}. This pixel
13599 is said to be the @r{@var{i}}th pixel in the @r{@var{j}}th row. Pixels
13600 are returned in row order from the lowest to the highest row, left to
13603 @var{format} specifies the format for the returned pixel values;
13604 accepted values are:
13607 @item @code{GL_COLOR_INDEX}
13608 Color indices are read from the color buffer selected by
13609 @code{glReadBuffer}. Each index is converted to fixed point, shifted
13610 left or right depending on the value and sign of @code{GL_INDEX_SHIFT},
13611 and added to @code{GL_INDEX_OFFSET}. If @code{GL_MAP_COLOR} is
13612 @code{GL_TRUE}, indices are replaced by their mappings in the table
13613 @code{GL_PIXEL_MAP_I_TO_I}.
13615 @item @code{GL_STENCIL_INDEX}
13616 Stencil values are read from the stencil buffer. Each index is converted
13617 to fixed point, shifted left or right depending on the value and sign of
13618 @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET}. If
13619 @code{GL_MAP_STENCIL} is @code{GL_TRUE}, indices are replaced by their
13620 mappings in the table @code{GL_PIXEL_MAP_S_TO_S}.
13622 @item @code{GL_DEPTH_COMPONENT}
13623 Depth values are read from the depth buffer. Each component is converted
13624 to floating point such that the minimum depth value maps to 0 and the
13625 maximum value maps to 1. Each component is then multiplied by
13626 @code{GL_DEPTH_SCALE}, added to @code{GL_DEPTH_BIAS}, and finally
13627 clamped to the range @r{[0,1]}.
13629 @item @code{GL_RED}
13630 @item @code{GL_GREEN}
13631 @item @code{GL_BLUE}
13632 @item @code{GL_ALPHA}
13633 @item @code{GL_RGB}
13634 @item @code{GL_BGR}
13635 @item @code{GL_RGBA}
13636 @item @code{GL_BGRA}
13637 @item @code{GL_LUMINANCE}
13638 @item @code{GL_LUMINANCE_ALPHA}
13639 Processing differs depending on whether color buffers store color
13640 indices or RGBA color components. If color indices are stored, they are
13641 read from the color buffer selected by @code{glReadBuffer}. Each index
13642 is converted to fixed point, shifted left or right depending on the
13643 value and sign of @code{GL_INDEX_SHIFT}, and added to
13644 @code{GL_INDEX_OFFSET}. Indices are then replaced by the red, green,
13645 blue, and alpha values obtained by indexing the tables
13646 @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G},
13647 @code{GL_PIXEL_MAP_I_TO_B}, and @code{GL_PIXEL_MAP_I_TO_A}. Each table
13648 must be of size @r{2^@var{n}}, but @r{@var{n}} may be different for
13649 different tables. Before an index is used to look up a value in a table
13650 of size @r{2^@var{n}}, it must be masked against @r{2^@var{n}-1}.
13652 If RGBA color components are stored in the color buffers, they are read
13653 from the color buffer selected by @code{glReadBuffer}. Each color
13654 component is converted to floating point such that zero intensity maps
13655 to 0.0 and full intensity maps to 1.0. Each component is then multiplied
13656 by @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is
13657 RED, GREEN, BLUE, or ALPHA. Finally, if @code{GL_MAP_COLOR} is
13658 @code{GL_TRUE}, each component is clamped to the range @r{[0,1]}, scaled
13659 to the size of its corresponding table, and is then replaced by its
13660 mapping in the table @code{GL_PIXEL_MAP_c_TO_c}, where @var{c} is R, G,
13663 Unneeded data is then discarded. For example, @code{GL_RED} discards the
13664 green, blue, and alpha components, while @code{GL_RGB} discards only the
13665 alpha component. @code{GL_LUMINANCE} computes a single-component value
13666 as the sum of the red, green, and blue components, and
13667 @code{GL_LUMINANCE_ALPHA} does the same, while keeping alpha as a second
13668 value. The final values are clamped to the range @r{[0,1]}.
13672 The shift, scale, bias, and lookup factors just described are all
13673 specified by @code{glPixelTransfer}. The lookup table contents
13674 themselves are specified by @code{glPixelMap}.
13676 Finally, the indices or components are converted to the proper format,
13677 as specified by @var{type}. If @var{format} is @code{GL_COLOR_INDEX} or
13678 @code{GL_STENCIL_INDEX} and @var{type} is not @code{GL_FLOAT}, each
13679 index is masked with the mask value given in the following table. If
13680 @var{type} is @code{GL_FLOAT}, then each integer index is converted to
13681 single-precision floating-point format.
13683 If @var{format} is @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE},
13684 @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA},
13685 @code{GL_BGRA}, @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA} and
13686 @var{type} is not @code{GL_FLOAT}, each component is multiplied by the
13687 multiplier shown in the following table. If type is @code{GL_FLOAT},
13688 then each component is passed as is (or converted to the client's
13689 single-precision floating-point format if it is different from the one
13696 @strong{Index Mask}, @strong{Component Conversion}
13698 @item @code{GL_UNSIGNED_BYTE}
13699 @r{2^8-1}, @r{(2^8-1,)@var{c}}
13701 @item @code{GL_BYTE}
13702 @r{2^7-1}, @r{(2^8-1,)@var{c}-1,/2}
13704 @item @code{GL_BITMAP}
13707 @item @code{GL_UNSIGNED_SHORT}
13708 @r{2^16-1}, @r{(2^16-1,)@var{c}}
13710 @item @code{GL_SHORT}
13711 @r{2^15-1}, @r{(2^16-1,)@var{c}-1,/2}
13713 @item @code{GL_UNSIGNED_INT}
13714 @r{2^32-1}, @r{(2^32-1,)@var{c}}
13716 @item @code{GL_INT}
13717 @r{2^31-1}, @r{(2^32-1,)@var{c}-1,/2}
13719 @item @code{GL_FLOAT}
13724 Return values are placed in memory as follows. If @var{format} is
13725 @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX},
13726 @code{GL_DEPTH_COMPONENT}, @code{GL_RED}, @code{GL_GREEN},
13727 @code{GL_BLUE}, @code{GL_ALPHA}, or @code{GL_LUMINANCE}, a single value
13728 is returned and the data for the @r{@var{i}}th pixel in the
13729 @r{@var{j}}th row is placed in location
13730 @r{(@var{j},)@var{width}+@var{i}}. @code{GL_RGB} and @code{GL_BGR}
13731 return three values, @code{GL_RGBA} and @code{GL_BGRA} return four
13732 values, and @code{GL_LUMINANCE_ALPHA} returns two values for each pixel,
13733 with all values corresponding to a single pixel occupying contiguous
13734 space in @var{data}. Storage parameters set by @code{glPixelStore}, such
13735 as @code{GL_PACK_LSB_FIRST} and @code{GL_PACK_SWAP_BYTES}, affect the
13736 way that data is written into memory. See @code{glPixelStore} for a
13739 @code{GL_INVALID_ENUM} is generated if @var{format} or @var{type} is not
13742 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
13743 and @var{format} is not @code{GL_COLOR_INDEX} or
13744 @code{GL_STENCIL_INDEX}.
13746 @code{GL_INVALID_VALUE} is generated if either @var{width} or
13747 @var{height} is negative.
13749 @code{GL_INVALID_OPERATION} is generated if @var{format} is
13750 @code{GL_COLOR_INDEX} and the color buffers store RGBA color components.
13752 @code{GL_INVALID_OPERATION} is generated if @var{format} is
13753 @code{GL_STENCIL_INDEX} and there is no stencil buffer.
13755 @code{GL_INVALID_OPERATION} is generated if @var{format} is
13756 @code{GL_DEPTH_COMPONENT} and there is no depth buffer.
13758 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
13759 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
13760 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
13761 and @var{format} is not @code{GL_RGB}.
13763 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
13764 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
13765 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
13766 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
13767 @code{GL_UNSIGNED_INT_10_10_10_2}, or
13768 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
13769 @code{GL_RGBA} nor @code{GL_BGRA}.
13771 The formats @code{GL_BGR}, and @code{GL_BGRA} and types
13772 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
13773 @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV},
13774 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
13775 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
13776 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
13777 @code{GL_UNSIGNED_INT_10_10_10_2}, and
13778 @code{GL_UNSIGNED_INT_2_10_10_10_REV} are available only if the GL
13779 version is 1.2 or greater.
13781 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
13782 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer
13783 object's data store is currently mapped.
13785 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
13786 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data
13787 would be packed to the buffer object such that the memory writes
13788 required would exceed the data store size.
13790 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
13791 name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{data}
13792 is not evenly divisible into the number of bytes needed to store in
13793 memory a datum indicated by @var{type}.
13795 @code{GL_INVALID_OPERATION} is generated if @code{glReadPixels} is
13796 executed between the execution of @code{glBegin} and the corresponding
13797 execution of @code{glEnd}.
13801 @deftypefun void glRectf x1 y1 x2 y2
13802 @deftypefunx void glRecti x1 y1 x2 y2
13808 Specify one vertex of a rectangle.
13812 Specify the opposite vertex of the rectangle.
13816 @code{glRect} supports efficient specification of rectangles as two
13817 corner points. Each rectangle command takes four arguments, organized
13818 either as two consecutive pairs of @r{(@var{x},@var{y})} coordinates or
13819 as two pointers to arrays, each containing an @r{(@var{x},@var{y})}
13820 pair. The resulting rectangle is defined in the @r{@var{z}=0} plane.
13822 @code{glRect}(@var{x1}, @var{y1}, @var{x2}, @var{y2}) is exactly
13823 equivalent to the following sequence: Note that if the second vertex is
13824 above and to the right of the first vertex, the rectangle is constructed
13825 with a counterclockwise winding.
13829 glBegin(@code{GL_POLYGON});
13830 glVertex2(@var{x1}, @var{y1});
13831 glVertex2(@var{x2}, @var{y1});
13832 glVertex2(@var{x2}, @var{y2});
13833 glVertex2(@var{x1}, @var{y2});
13837 @code{GL_INVALID_OPERATION} is generated if @code{glRect} is executed
13838 between the execution of @code{glBegin} and the corresponding execution
13843 @deftypefun GLint glRenderMode mode
13844 Set rasterization mode.
13848 Specifies the rasterization mode. Three values are accepted:
13849 @code{GL_RENDER}, @code{GL_SELECT}, and @code{GL_FEEDBACK}. The initial
13850 value is @code{GL_RENDER}.
13854 @code{glRenderMode} sets the rasterization mode. It takes one argument,
13855 @var{mode}, which can assume one of three predefined values:
13858 @item @code{GL_RENDER}
13859 Render mode. Primitives are rasterized, producing pixel fragments, which
13860 are written into the frame buffer. This is the normal mode and also the
13863 @item @code{GL_SELECT}
13864 Selection mode. No pixel fragments are produced, and no change to the
13865 frame buffer contents is made. Instead, a record of the names of
13866 primitives that would have been drawn if the render mode had been
13867 @code{GL_RENDER} is returned in a select buffer, which must be created
13868 (see @code{glSelectBuffer}) before selection mode is entered.
13870 @item @code{GL_FEEDBACK}
13871 Feedback mode. No pixel fragments are produced, and no change to the
13872 frame buffer contents is made. Instead, the coordinates and attributes
13873 of vertices that would have been drawn if the render mode had been
13874 @code{GL_RENDER} is returned in a feedback buffer, which must be created
13875 (see @code{glFeedbackBuffer}) before feedback mode is entered.
13879 The return value of @code{glRenderMode} is determined by the render mode
13880 at the time @code{glRenderMode} is called, rather than by @var{mode}.
13881 The values returned for the three render modes are as follows:
13884 @item @code{GL_RENDER}
13887 @item @code{GL_SELECT}
13888 The number of hit records transferred to the select buffer.
13890 @item @code{GL_FEEDBACK}
13891 The number of values (not vertices) transferred to the feedback buffer.
13895 See the @code{glSelectBuffer} and @code{glFeedbackBuffer} reference
13896 pages for more details concerning selection and feedback operation.
13898 @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of the
13899 three accepted values.
13901 @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is
13902 called while the render mode is @code{GL_SELECT}, or if
13903 @code{glRenderMode} is called with argument @code{GL_SELECT} before
13904 @code{glSelectBuffer} is called at least once.
13906 @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is
13907 called while the render mode is @code{GL_FEEDBACK}, or if
13908 @code{glRenderMode} is called with argument @code{GL_FEEDBACK} before
13909 @code{glFeedbackBuffer} is called at least once.
13911 @code{GL_INVALID_OPERATION} is generated if @code{glRenderMode} is
13912 executed between the execution of @code{glBegin} and the corresponding
13913 execution of @code{glEnd}.
13917 @deftypefun void glResetHistogram target
13918 Reset histogram table entries to zero.
13922 Must be @code{GL_HISTOGRAM}.
13926 @code{glResetHistogram} resets all the elements of the current histogram
13929 @code{GL_INVALID_ENUM} is generated if @var{target} is not
13930 @code{GL_HISTOGRAM}.
13932 @code{GL_INVALID_OPERATION} is generated if @code{glResetHistogram} is
13933 executed between the execution of @code{glBegin} and the corresponding
13934 execution of @code{glEnd}.
13938 @deftypefun void glResetMinmax target
13939 Reset minmax table entries to initial values.
13943 Must be @code{GL_MINMAX}.
13947 @code{glResetMinmax} resets the elements of the current minmax table to
13948 their initial values: the ``maximum'' element receives the minimum
13949 possible component values, and the ``minimum'' element receives the
13950 maximum possible component values.
13952 @code{GL_INVALID_ENUM} is generated if @var{target} is not
13955 @code{GL_INVALID_OPERATION} is generated if @code{glResetMinmax} is
13956 executed between the execution of @code{glBegin} and the corresponding
13957 execution of @code{glEnd}.
13961 @deftypefun void glRotatef angle x y z
13962 Multiply the current matrix by a rotation matrix.
13966 Specifies the angle of rotation, in degrees.
13971 Specify the @var{x}, @var{y}, and @var{z} coordinates of a vector,
13976 @code{glRotate} produces a rotation of @var{angle} degrees around the
13977 vector @r{(@var{x},@var{y}@var{z})}. The current matrix (see
13978 @code{glMatrixMode}) is multiplied by a rotation matrix with the product
13979 replacing the current matrix, as if @code{glMultMatrix} were called with
13980 the following matrix as its argument:
13982 @r{((@var{x}^2(1-@var{c},)+@var{c}
13983 @var{x}@var{y}(1-@var{c},)-@var{z}@var{s}
13984 @var{x}@var{z}(1-@var{c},)+@var{y}@var{s} 0),
13985 (@var{y}@var{x}(1-@var{c},)+@var{z}@var{s}
13986 @var{y}^2(1-@var{c},)+@var{c}
13987 @var{y}@var{z}(1-@var{c},)-@var{x}@var{s} 0),
13988 (@var{x}@var{z}(1-@var{c},)-@var{y}@var{s}
13989 @var{y}@var{z}(1-@var{c},)+@var{x}@var{s}
13990 @var{z}^2(1-@var{c},)+@var{c} 0), (0 0 0 1),)}
13994 Where @r{@var{c}=@var{cos}(@var{angle},)},
13995 @r{@var{s}=@var{sin}(@var{angle},)}, and
13996 @r{∥(@var{x},@var{y}@var{z}),∥=1} (if not, the GL will normalize this
14003 If the matrix mode is either @code{GL_MODELVIEW} or
14004 @code{GL_PROJECTION}, all objects drawn after @code{glRotate} is called
14005 are rotated. Use @code{glPushMatrix} and @code{glPopMatrix} to save and
14006 restore the unrotated coordinate system.
14008 @code{GL_INVALID_OPERATION} is generated if @code{glRotate} is executed
14009 between the execution of @code{glBegin} and the corresponding execution
14014 @deftypefun void glSampleCoverage value invert
14015 Specify multisample coverage parameters.
14019 Specify a single floating-point sample coverage value. The value is
14020 clamped to the range @r{[0,1]}. The initial value is 1.0.
14023 Specify a single boolean value representing if the coverage masks should
14024 be inverted. @code{GL_TRUE} and @code{GL_FALSE} are accepted. The
14025 initial value is @code{GL_FALSE}.
14029 Multisampling samples a pixel multiple times at various
14030 implementation-dependent subpixel locations to generate antialiasing
14031 effects. Multisampling transparently antialiases points, lines,
14032 polygons, bitmaps, and images if it is enabled.
14034 @var{value} is used in constructing a temporary mask used in determining
14035 which samples will be used in resolving the final fragment color. This
14036 mask is bitwise-anded with the coverage mask generated from the
14037 multisampling computation. If the @var{invert} flag is set, the
14038 temporary mask is inverted (all bits flipped) and then the bitwise-and
14041 If an implementation does not have any multisample buffers available, or
14042 multisampling is disabled, rasterization occurs with only a single
14043 sample computing a pixel's final RGB color.
14045 Provided an implementation supports multisample buffers, and
14046 multisampling is enabled, then a pixel's final color is generated by
14047 combining several samples per pixel. Each sample contains color, depth,
14048 and stencil information, allowing those operations to be performed on
14051 @code{GL_INVALID_OPERATION} is generated if @code{glSampleCoverage} is
14052 executed between the execution of @code{glBegin} and the corresponding
14053 execution of @code{glEnd}.
14057 @deftypefun void glScalef x y z
14058 Multiply the current matrix by a general scaling matrix.
14064 Specify scale factors along the @var{x}, @var{y}, and @var{z} axes,
14069 @code{glScale} produces a nonuniform scaling along the @var{x}, @var{y},
14070 and @var{z} axes. The three parameters indicate the desired scale factor
14071 along each of the three axes.
14073 The current matrix (see @code{glMatrixMode}) is multiplied by this scale
14074 matrix, and the product replaces the current matrix as if
14075 @code{glMultMatrix} were called with the following matrix as its
14078 @r{((@var{x} 0 0 0), (0 @var{y} 0 0), (0 0 @var{z} 0), (0 0 0 1),)}
14080 If the matrix mode is either @code{GL_MODELVIEW} or
14081 @code{GL_PROJECTION}, all objects drawn after @code{glScale} is called
14084 Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the
14085 unscaled coordinate system.
14087 @code{GL_INVALID_OPERATION} is generated if @code{glScale} is executed
14088 between the execution of @code{glBegin} and the corresponding execution
14093 @deftypefun void glScissor x y width height
14094 Define the scissor box.
14099 Specify the lower left corner of the scissor box. Initially (0, 0).
14102 @itemx @var{height}
14103 Specify the width and height of the scissor box. When a GL context is
14104 first attached to a window, @var{width} and @var{height} are set to the
14105 dimensions of that window.
14109 @code{glScissor} defines a rectangle, called the scissor box, in window
14110 coordinates. The first two arguments, @var{x} and @var{y}, specify the
14111 lower left corner of the box. @var{width} and @var{height} specify the
14112 width and height of the box.
14114 To enable and disable the scissor test, call @code{glEnable} and
14115 @code{glDisable} with argument @code{GL_SCISSOR_TEST}. The test is
14116 initially disabled. While the test is enabled, only pixels that lie
14117 within the scissor box can be modified by drawing commands. Window
14118 coordinates have integer values at the shared corners of frame buffer
14119 pixels. @code{glScissor(0,0,1,1)} allows modification of only the lower
14120 left pixel in the window, and @code{glScissor(0,0,0,0)} doesn't allow
14121 modification of any pixels in the window.
14123 When the scissor test is disabled, it is as though the scissor box
14124 includes the entire window.
14126 @code{GL_INVALID_VALUE} is generated if either @var{width} or
14127 @var{height} is negative.
14129 @code{GL_INVALID_OPERATION} is generated if @code{glScissor} is executed
14130 between the execution of @code{glBegin} and the corresponding execution
14135 @deftypefun void glSecondaryColorPointer size type stride pointer
14136 Define an array of secondary colors.
14140 Specifies the number of components per color. Must be 3.
14143 Specifies the data type of each color component in the array. Symbolic
14144 constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
14145 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
14146 @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is
14150 Specifies the byte offset between consecutive colors. If @var{stride} is
14151 0, the colors are understood to be tightly packed in the array. The
14152 initial value is 0.
14154 @item @var{pointer}
14155 Specifies a pointer to the first component of the first color element in
14156 the array. The initial value is 0.
14160 @code{glSecondaryColorPointer} specifies the location and data format of
14161 an array of color components to use when rendering. @var{size} specifies
14162 the number of components per color, and must be 3. @var{type} specifies
14163 the data type of each color component, and @var{stride} specifies the
14164 byte stride from one color to the next, allowing vertices and attributes
14165 to be packed into a single array or stored in separate arrays.
14167 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
14168 target (see @code{glBindBuffer}) while a secondary color array is
14169 specified, @var{pointer} is treated as a byte offset into the buffer
14170 object's data store. Also, the buffer object binding
14171 (@code{GL_ARRAY_BUFFER_BINDING}) is saved as secondary color vertex
14172 array client-side state
14173 (@code{GL_SECONDARY_COLOR_ARRAY_BUFFER_BINDING}).
14175 When a secondary color array is specified, @var{size}, @var{type},
14176 @var{stride}, and @var{pointer} are saved as client-side state, in
14177 addition to the current vertex array buffer object binding.
14179 To enable and disable the secondary color array, call
14180 @code{glEnableClientState} and @code{glDisableClientState} with the
14181 argument @code{GL_SECONDARY_COLOR_ARRAY}. If enabled, the secondary
14182 color array is used when @code{glArrayElement}, @code{glDrawArrays},
14183 @code{glMultiDrawArrays}, @code{glDrawElements},
14184 @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called.
14186 @code{GL_INVALID_VALUE} is generated if @var{size} is not 3.
14188 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
14191 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
14195 @deftypefun void glSecondaryColor3i red green blue
14196 @deftypefunx void glSecondaryColor3f red green blue
14197 @deftypefunx void glSecondaryColor3ui red green blue
14198 Set the current secondary color.
14204 Specify new red, green, and blue values for the current secondary color.
14208 The GL stores both a primary four-valued RGBA color and a secondary
14209 four-valued RGBA color (where alpha is always set to 0.0) that is
14210 associated with every vertex.
14212 The secondary color is interpolated and applied to each fragment during
14213 rasterization when @code{GL_COLOR_SUM} is enabled. When lighting is
14214 enabled, and @code{GL_SEPARATE_SPECULAR_COLOR} is specified, the value
14215 of the secondary color is assigned the value computed from the specular
14216 term of the lighting computation. Both the primary and secondary current
14217 colors are applied to each fragment, regardless of the state of
14218 @code{GL_COLOR_SUM}, under such conditions. When
14219 @code{GL_SEPARATE_SPECULAR_COLOR} is specified, the value returned from
14220 querying the current secondary color is undefined.
14222 @code{glSecondaryColor3b}, @code{glSecondaryColor3s}, and
14223 @code{glSecondaryColor3i} take three signed byte, short, or long
14224 integers as arguments. When @strong{v} is appended to the name, the
14225 color commands can take a pointer to an array of such values.
14227 Color values are stored in floating-point format, with unspecified
14228 mantissa and exponent sizes. Unsigned integer color components, when
14229 specified, are linearly mapped to floating-point values such that the
14230 largest representable value maps to 1.0 (full intensity), and 0 maps to
14231 0.0 (zero intensity). Signed integer color components, when specified,
14232 are linearly mapped to floating-point values such that the most positive
14233 representable value maps to 1.0, and the most negative representable
14234 value maps to @r{-1.0}. (Note that this mapping does not convert 0
14235 precisely to 0.0). Floating-point values are mapped directly.
14237 Neither floating-point nor signed integer values are clamped to the
14238 range @r{[0,1]} before the current color is updated. However, color
14239 components are clamped to this range before they are interpolated or
14240 written into a color buffer.
14244 @deftypefun void glSelectBuffer size buffer
14245 Establish a buffer for selection mode values.
14249 Specifies the size of @var{buffer}.
14252 Returns the selection data.
14256 @code{glSelectBuffer} has two arguments: @var{buffer} is a pointer to an
14257 array of unsigned integers, and @var{size} indicates the size of the
14258 array. @var{buffer} returns values from the name stack (see
14259 @code{glInitNames}, @code{glLoadName}, @code{glPushName}) when the
14260 rendering mode is @code{GL_SELECT} (see @code{glRenderMode}).
14261 @code{glSelectBuffer} must be issued before selection mode is enabled,
14262 and it must not be issued while the rendering mode is @code{GL_SELECT}.
14264 A programmer can use selection to determine which primitives are drawn
14265 into some region of a window. The region is defined by the current
14266 modelview and perspective matrices.
14268 In selection mode, no pixel fragments are produced from rasterization.
14269 Instead, if a primitive or a raster position intersects the clipping
14270 volume defined by the viewing frustum and the user-defined clipping
14271 planes, this primitive causes a selection hit. (With polygons, no hit
14272 occurs if the polygon is culled.) When a change is made to the name
14273 stack, or when @code{glRenderMode} is called, a hit record is copied to
14274 @var{buffer} if any hits have occurred since the last such event (name
14275 stack change or @code{glRenderMode} call). The hit record consists of
14276 the number of names in the name stack at the time of the event, followed
14277 by the minimum and maximum depth values of all vertices that hit since
14278 the previous event, followed by the name stack contents, bottom name
14281 Depth values (which are in the range [0,1]) are multiplied by
14282 @r{2^32-1}, before being placed in the hit record.
14284 An internal index into @var{buffer} is reset to 0 whenever selection
14285 mode is entered. Each time a hit record is copied into @var{buffer}, the
14286 index is incremented to point to the cell just past the end of the block
14287 of names\(emthat is, to the next available cell If the hit record is
14288 larger than the number of remaining locations in @var{buffer}, as much
14289 data as can fit is copied, and the overflow flag is set. If the name
14290 stack is empty when a hit record is copied, that record consists of 0
14291 followed by the minimum and maximum depth values.
14293 To exit selection mode, call @code{glRenderMode} with an argument other
14294 than @code{GL_SELECT}. Whenever @code{glRenderMode} is called while the
14295 render mode is @code{GL_SELECT}, it returns the number of hit records
14296 copied to @var{buffer}, resets the overflow flag and the selection
14297 buffer pointer, and initializes the name stack to be empty. If the
14298 overflow bit was set when @code{glRenderMode} was called, a negative hit
14299 record count is returned.
14301 @code{GL_INVALID_VALUE} is generated if @var{size} is negative.
14303 @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is
14304 called while the render mode is @code{GL_SELECT}, or if
14305 @code{glRenderMode} is called with argument @code{GL_SELECT} before
14306 @code{glSelectBuffer} is called at least once.
14308 @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is
14309 executed between the execution of @code{glBegin} and the corresponding
14310 execution of @code{glEnd}.
14314 @deftypefun void glSeparableFilter2D target internalformat width height format type row column
14315 Define a separable two-dimensional convolution filter.
14319 Must be @code{GL_SEPARABLE_2D}.
14321 @item @var{internalformat}
14322 The internal format of the convolution filter kernel. The allowable
14323 values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8},
14324 @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE},
14325 @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12},
14326 @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA},
14327 @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2},
14328 @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4},
14329 @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16},
14330 @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8},
14331 @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2},
14332 @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8},
14333 @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA},
14334 @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8},
14335 @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}.
14338 The number of elements in the pixel array referenced by @var{row}. (This
14339 is the width of the separable filter kernel.)
14342 The number of elements in the pixel array referenced by @var{column}.
14343 (This is the height of the separable filter kernel.)
14346 The format of the pixel data in @var{row} and @var{column}. The
14347 allowable values are @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE},
14348 @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA},
14349 @code{GL_BGRA}, @code{GL_INTENSITY}, @code{GL_LUMINANCE}, and
14350 @code{GL_LUMINANCE_ALPHA}.
14353 The type of the pixel data in @var{row} and @var{column}. Symbolic
14354 constants @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
14355 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
14356 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
14357 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
14358 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
14359 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
14360 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
14361 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
14362 and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted.
14365 Pointer to a one-dimensional array of pixel data that is processed to
14366 build the row filter kernel.
14369 Pointer to a one-dimensional array of pixel data that is processed to
14370 build the column filter kernel.
14374 @code{glSeparableFilter2D} builds a two-dimensional separable
14375 convolution filter kernel from two arrays of pixels.
14377 The pixel arrays specified by (@var{width}, @var{format}, @var{type},
14378 @var{row}) and (@var{height}, @var{format}, @var{type}, @var{column})
14379 are processed just as if they had been passed to @code{glDrawPixels},
14380 but processing stops after the final expansion to RGBA is completed.
14382 If a non-zero named buffer object is bound to the
14383 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
14384 convolution filter is specified, @var{row} and @var{column} are treated
14385 as byte offsets into the buffer object's data store.
14387 Next, the R, G, B, and A components of all pixels in both arrays are
14388 scaled by the four separable 2D @code{GL_CONVOLUTION_FILTER_SCALE}
14389 parameters and biased by the four separable 2D
14390 @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias
14391 parameters are set by @code{glConvolutionParameter} using the
14392 @code{GL_SEPARABLE_2D} target and the names
14393 @code{GL_CONVOLUTION_FILTER_SCALE} and
14394 @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors
14395 of four values that are applied to red, green, blue, and alpha, in that
14396 order.) The R, G, B, and A values are not clamped to [0,1] at any time
14397 during this process.
14399 Each pixel is then converted to the internal format specified by
14400 @var{internalformat}. This conversion simply maps the component values
14401 of the pixel (R, G, B, and A) to the values included in the internal
14402 format (red, green, blue, alpha, luminance, and intensity). The mapping
14406 @item @strong{Internal Format}
14407 @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha},
14408 @strong{Luminance}, @strong{Intensity}
14410 @item @code{GL_LUMINANCE}
14413 @item @code{GL_LUMINANCE_ALPHA}
14416 @item @code{GL_INTENSITY}
14419 @item @code{GL_RGB}
14422 @item @code{GL_RGBA}
14427 The red, green, blue, alpha, luminance, and/or intensity components of
14428 the resulting pixels are stored in floating-point rather than integer
14429 format. They form two one-dimensional filter kernel images. The row
14430 image is indexed by coordinate @var{i} starting at zero and increasing
14431 from left to right. Each location in the row image is derived from
14432 element @var{i} of @var{row}. The column image is indexed by coordinate
14433 @var{j} starting at zero and increasing from bottom to top. Each
14434 location in the column image is derived from element @var{j} of
14437 Note that after a convolution is performed, the resulting color
14438 components are also scaled by their corresponding
14439 @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their
14440 corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where
14441 @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE},
14442 and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}.
14444 @code{GL_INVALID_ENUM} is generated if @var{target} is not
14445 @code{GL_SEPARABLE_2D}.
14447 @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one
14448 of the allowable values.
14450 @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the
14453 @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the
14456 @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or
14457 greater than the maximum supported value. This value may be queried with
14458 @code{glGetConvolutionParameter} using target @code{GL_SEPARABLE_2D} and
14459 name @code{GL_MAX_CONVOLUTION_WIDTH}.
14461 @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero
14462 or greater than the maximum supported value. This value may be queried
14463 with @code{glGetConvolutionParameter} using target
14464 @code{GL_SEPARABLE_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}.
14466 @code{GL_INVALID_OPERATION} is generated if @var{height} is one of
14467 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
14468 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
14469 and @var{format} is not @code{GL_RGB}.
14471 @code{GL_INVALID_OPERATION} is generated if @var{height} is one of
14472 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
14473 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
14474 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
14475 @code{GL_UNSIGNED_INT_10_10_10_2}, or
14476 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
14477 @code{GL_RGBA} nor @code{GL_BGRA}.
14479 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
14480 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
14481 object's data store is currently mapped.
14483 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
14484 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
14485 would be unpacked from the buffer object such that the memory reads
14486 required would exceed the data store size.
14488 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
14489 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{row}
14490 or @var{column} is not evenly divisible into the number of bytes needed
14491 to store in memory a datum indicated by @var{type}.
14493 @code{GL_INVALID_OPERATION} is generated if @code{glSeparableFilter2D}
14494 is executed between the execution of @code{glBegin} and the
14495 corresponding execution of @code{glEnd}.
14499 @deftypefun void glShadeModel mode
14500 Select flat or smooth shading.
14504 Specifies a symbolic value representing a shading technique. Accepted
14505 values are @code{GL_FLAT} and @code{GL_SMOOTH}. The initial value is
14510 GL primitives can have either flat or smooth shading. Smooth shading,
14511 the default, causes the computed colors of vertices to be interpolated
14512 as the primitive is rasterized, typically assigning different colors to
14513 each resulting pixel fragment. Flat shading selects the computed color
14514 of just one vertex and assigns it to all the pixel fragments generated
14515 by rasterizing a single primitive. In either case, the computed color of
14516 a vertex is the result of lighting if lighting is enabled, or it is the
14517 current color at the time the vertex was specified if lighting is
14520 Flat and smooth shading are indistinguishable for points. Starting when
14521 @code{glBegin} is issued and counting vertices and primitives from 1,
14522 the GL gives each flat-shaded line segment @r{@var{i}} the computed
14523 color of vertex @r{@var{i}+1}, its second vertex. Counting similarly
14524 from 1, the GL gives each flat-shaded polygon the computed color of the
14525 vertex listed in the following table. This is the last vertex to specify
14526 the polygon in all cases except single polygons, where the first vertex
14527 specifies the flat-shaded color.
14533 Primitive Type of Polygon @r{@var{i}}}
14550 Independent triangle
14563 Flat and smooth shading are specified by @code{glShadeModel} with
14564 @var{mode} set to @code{GL_FLAT} and @code{GL_SMOOTH}, respectively.
14566 @code{GL_INVALID_ENUM} is generated if @var{mode} is any value other
14567 than @code{GL_FLAT} or @code{GL_SMOOTH}.
14569 @code{GL_INVALID_OPERATION} is generated if @code{glShadeModel} is
14570 executed between the execution of @code{glBegin} and the corresponding
14571 execution of @code{glEnd}.
14575 @deftypefun void glShaderSource shader count string length
14576 Replaces the source code in a shader object.
14580 Specifies the handle of the shader object whose source code is to be
14584 Specifies the number of elements in the @var{string} and @var{length}
14588 Specifies an array of pointers to strings containing the source code to
14589 be loaded into the shader.
14592 Specifies an array of string lengths.
14596 @code{glShaderSource} sets the source code in @var{shader} to the source
14597 code in the array of strings specified by @var{string}. Any source code
14598 previously stored in the shader object is completely replaced. The
14599 number of strings in the array is specified by @var{count}. If
14600 @var{length} is @code{NULL}, each string is assumed to be null
14601 terminated. If @var{length} is a value other than @code{NULL}, it points
14602 to an array containing a string length for each of the corresponding
14603 elements of @var{string}. Each element in the @var{length} array may
14604 contain the length of the corresponding string (the null character is
14605 not counted as part of the string length) or a value less than 0 to
14606 indicate that the string is null terminated. The source code strings are
14607 not scanned or parsed at this time; they are simply copied into the
14608 specified shader object.
14610 @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value
14611 generated by OpenGL.
14613 @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader
14616 @code{GL_INVALID_VALUE} is generated if @var{count} is less than 0.
14618 @code{GL_INVALID_OPERATION} is generated if @code{glShaderSource} is
14619 executed between the execution of @code{glBegin} and the corresponding
14620 execution of @code{glEnd}.
14624 @deftypefun void glStencilFuncSeparate face func ref mask
14625 Set front and/or back function and reference value for stencil testing.
14629 Specifies whether front and/or back stencil state is updated. Three
14630 symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and
14631 @code{GL_FRONT_AND_BACK}.
14634 Specifies the test function. Eight symbolic constants are valid:
14635 @code{GL_NEVER}, @code{GL_LESS}, @code{GL_LEQUAL}, @code{GL_GREATER},
14636 @code{GL_GEQUAL}, @code{GL_EQUAL}, @code{GL_NOTEQUAL}, and
14637 @code{GL_ALWAYS}. The initial value is @code{GL_ALWAYS}.
14640 Specifies the reference value for the stencil test. @var{ref} is clamped
14641 to the range @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of
14642 bitplanes in the stencil buffer. The initial value is 0.
14645 Specifies a mask that is ANDed with both the reference value and the
14646 stored stencil value when the test is done. The initial value is all
14651 Stenciling, like depth-buffering, enables and disables drawing on a
14652 per-pixel basis. You draw into the stencil planes using GL drawing
14653 primitives, then render geometry and images, using the stencil planes to
14654 mask out portions of the screen. Stenciling is typically used in
14655 multipass rendering algorithms to achieve special effects, such as
14656 decals, outlining, and constructive solid geometry rendering.
14658 The stencil test conditionally eliminates a pixel based on the outcome
14659 of a comparison between the reference value and the value in the stencil
14660 buffer. To enable and disable the test, call @code{glEnable} and
14661 @code{glDisable} with argument @code{GL_STENCIL_TEST}. To specify
14662 actions based on the outcome of the stencil test, call
14663 @code{glStencilOp} or @code{glStencilOpSeparate}.
14665 There can be two separate sets of @var{func}, @var{ref}, and @var{mask}
14666 parameters; one affects back-facing polygons, and the other affects
14667 front-facing polygons as well as other non-polygon primitives.
14668 @code{glStencilFunc} sets both front and back stencil state to the same
14669 values, as if @code{glStencilFuncSeparate} were called with @var{face}
14670 set to @code{GL_FRONT_AND_BACK}.
14672 @var{func} is a symbolic constant that determines the stencil comparison
14673 function. It accepts one of eight values, shown in the following list.
14674 @var{ref} is an integer reference value that is used in the stencil
14675 comparison. It is clamped to the range @r{[0,2^@var{n}-1]}, where
14676 @r{@var{n}} is the number of bitplanes in the stencil buffer. @var{mask}
14677 is bitwise ANDed with both the reference value and the stored stencil
14678 value, with the ANDed values participating in the comparison.
14680 If @var{stencil} represents the value stored in the corresponding
14681 stencil buffer location, the following list shows the effect of each
14682 comparison function that can be specified by @var{func}. Only if the
14683 comparison succeeds is the pixel passed through to the next stage in the
14684 rasterization process (see @code{glStencilOp}). All tests treat
14685 @var{stencil} values as unsigned integers in the range
14686 @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of bitplanes in the
14689 The following values are accepted by @var{func}:
14692 @item @code{GL_NEVER}
14695 @item @code{GL_LESS}
14696 Passes if ( @var{ref} & @var{mask} ) < ( @var{stencil} & @var{mask} ).
14698 @item @code{GL_LEQUAL}
14699 Passes if ( @var{ref} & @var{mask} ) <= ( @var{stencil} & @var{mask} ).
14701 @item @code{GL_GREATER}
14702 Passes if ( @var{ref} & @var{mask} ) > ( @var{stencil} & @var{mask} ).
14704 @item @code{GL_GEQUAL}
14705 Passes if ( @var{ref} & @var{mask} ) >= ( @var{stencil} & @var{mask} ).
14707 @item @code{GL_EQUAL}
14708 Passes if ( @var{ref} & @var{mask} ) = ( @var{stencil} & @var{mask} ).
14710 @item @code{GL_NOTEQUAL}
14711 Passes if ( @var{ref} & @var{mask} ) != ( @var{stencil} & @var{mask} ).
14713 @item @code{GL_ALWAYS}
14718 @code{GL_INVALID_ENUM} is generated if @var{func} is not one of the
14719 eight accepted values.
14721 @code{GL_INVALID_OPERATION} is generated if @code{glStencilFuncSeparate}
14722 is executed between the execution of @code{glBegin} and the
14723 corresponding execution of @code{glEnd}.
14727 @deftypefun void glStencilFunc func ref mask
14728 Set front and back function and reference value for stencil testing.
14732 Specifies the test function. Eight symbolic constants are valid:
14733 @code{GL_NEVER}, @code{GL_LESS}, @code{GL_LEQUAL}, @code{GL_GREATER},
14734 @code{GL_GEQUAL}, @code{GL_EQUAL}, @code{GL_NOTEQUAL}, and
14735 @code{GL_ALWAYS}. The initial value is @code{GL_ALWAYS}.
14738 Specifies the reference value for the stencil test. @var{ref} is clamped
14739 to the range @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of
14740 bitplanes in the stencil buffer. The initial value is 0.
14743 Specifies a mask that is ANDed with both the reference value and the
14744 stored stencil value when the test is done. The initial value is all
14749 Stenciling, like depth-buffering, enables and disables drawing on a
14750 per-pixel basis. Stencil planes are first drawn into using GL drawing
14751 primitives, then geometry and images are rendered using the stencil
14752 planes to mask out portions of the screen. Stenciling is typically used
14753 in multipass rendering algorithms to achieve special effects, such as
14754 decals, outlining, and constructive solid geometry rendering.
14756 The stencil test conditionally eliminates a pixel based on the outcome
14757 of a comparison between the reference value and the value in the stencil
14758 buffer. To enable and disable the test, call @code{glEnable} and
14759 @code{glDisable} with argument @code{GL_STENCIL_TEST}. To specify
14760 actions based on the outcome of the stencil test, call
14761 @code{glStencilOp} or @code{glStencilOpSeparate}.
14763 There can be two separate sets of @var{func}, @var{ref}, and @var{mask}
14764 parameters; one affects back-facing polygons, and the other affects
14765 front-facing polygons as well as other non-polygon primitives.
14766 @code{glStencilFunc} sets both front and back stencil state to the same
14767 values. Use @code{glStencilFuncSeparate} to set front and back stencil
14768 state to different values.
14770 @var{func} is a symbolic constant that determines the stencil comparison
14771 function. It accepts one of eight values, shown in the following list.
14772 @var{ref} is an integer reference value that is used in the stencil
14773 comparison. It is clamped to the range @r{[0,2^@var{n}-1]}, where
14774 @r{@var{n}} is the number of bitplanes in the stencil buffer. @var{mask}
14775 is bitwise ANDed with both the reference value and the stored stencil
14776 value, with the ANDed values participating in the comparison.
14778 If @var{stencil} represents the value stored in the corresponding
14779 stencil buffer location, the following list shows the effect of each
14780 comparison function that can be specified by @var{func}. Only if the
14781 comparison succeeds is the pixel passed through to the next stage in the
14782 rasterization process (see @code{glStencilOp}). All tests treat
14783 @var{stencil} values as unsigned integers in the range
14784 @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of bitplanes in the
14787 The following values are accepted by @var{func}:
14790 @item @code{GL_NEVER}
14793 @item @code{GL_LESS}
14794 Passes if ( @var{ref} & @var{mask} ) < ( @var{stencil} & @var{mask} ).
14796 @item @code{GL_LEQUAL}
14797 Passes if ( @var{ref} & @var{mask} ) <= ( @var{stencil} & @var{mask} ).
14799 @item @code{GL_GREATER}
14800 Passes if ( @var{ref} & @var{mask} ) > ( @var{stencil} & @var{mask} ).
14802 @item @code{GL_GEQUAL}
14803 Passes if ( @var{ref} & @var{mask} ) >= ( @var{stencil} & @var{mask} ).
14805 @item @code{GL_EQUAL}
14806 Passes if ( @var{ref} & @var{mask} ) = ( @var{stencil} & @var{mask} ).
14808 @item @code{GL_NOTEQUAL}
14809 Passes if ( @var{ref} & @var{mask} ) != ( @var{stencil} & @var{mask} ).
14811 @item @code{GL_ALWAYS}
14816 @code{GL_INVALID_ENUM} is generated if @var{func} is not one of the
14817 eight accepted values.
14819 @code{GL_INVALID_OPERATION} is generated if @code{glStencilFunc} is
14820 executed between the execution of @code{glBegin} and the corresponding
14821 execution of @code{glEnd}.
14825 @deftypefun void glStencilMaskSeparate face mask
14826 Control the front and/or back writing of individual bits in the stencil
14831 Specifies whether the front and/or back stencil writemask is updated.
14832 Three symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and
14833 @code{GL_FRONT_AND_BACK}.
14836 Specifies a bit mask to enable and disable writing of individual bits in
14837 the stencil planes. Initially, the mask is all 1's.
14841 @code{glStencilMaskSeparate} controls the writing of individual bits in
14842 the stencil planes. The least significant @r{@var{n}} bits of
14843 @var{mask}, where @r{@var{n}} is the number of bits in the stencil
14844 buffer, specify a mask. Where a 1 appears in the mask, it's possible to
14845 write to the corresponding bit in the stencil buffer. Where a 0 appears,
14846 the corresponding bit is write-protected. Initially, all bits are
14847 enabled for writing.
14849 There can be two separate @var{mask} writemasks; one affects back-facing
14850 polygons, and the other affects front-facing polygons as well as other
14851 non-polygon primitives. @code{glStencilMask} sets both front and back
14852 stencil writemasks to the same values, as if
14853 @code{glStencilMaskSeparate} were called with @var{face} set to
14854 @code{GL_FRONT_AND_BACK}.
14856 @code{GL_INVALID_OPERATION} is generated if @code{glStencilMaskSeparate}
14857 is executed between the execution of @code{glBegin} and the
14858 corresponding execution of @code{glEnd}.
14862 @deftypefun void glStencilMask mask
14863 Control the front and back writing of individual bits in the stencil
14868 Specifies a bit mask to enable and disable writing of individual bits in
14869 the stencil planes. Initially, the mask is all 1's.
14873 @code{glStencilMask} controls the writing of individual bits in the
14874 stencil planes. The least significant @r{@var{n}} bits of @var{mask},
14875 where @r{@var{n}} is the number of bits in the stencil buffer, specify a
14876 mask. Where a 1 appears in the mask, it's possible to write to the
14877 corresponding bit in the stencil buffer. Where a 0 appears, the
14878 corresponding bit is write-protected. Initially, all bits are enabled
14881 There can be two separate @var{mask} writemasks; one affects back-facing
14882 polygons, and the other affects front-facing polygons as well as other
14883 non-polygon primitives. @code{glStencilMask} sets both front and back
14884 stencil writemasks to the same values. Use @code{glStencilMaskSeparate}
14885 to set front and back stencil writemasks to different values.
14887 @code{GL_INVALID_OPERATION} is generated if @code{glStencilMask} is
14888 executed between the execution of @code{glBegin} and the corresponding
14889 execution of @code{glEnd}.
14893 @deftypefun void glStencilOpSeparate face sfail dpfail dppass
14894 Set front and/or back stencil test actions.
14898 Specifies whether front and/or back stencil state is updated. Three
14899 symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and
14900 @code{GL_FRONT_AND_BACK}.
14903 Specifies the action to take when the stencil test fails. Eight symbolic
14904 constants are accepted: @code{GL_KEEP}, @code{GL_ZERO},
14905 @code{GL_REPLACE}, @code{GL_INCR}, @code{GL_INCR_WRAP}, @code{GL_DECR},
14906 @code{GL_DECR_WRAP}, and @code{GL_INVERT}. The initial value is
14910 Specifies the stencil action when the stencil test passes, but the depth
14911 test fails. @var{dpfail} accepts the same symbolic constants as
14912 @var{sfail}. The initial value is @code{GL_KEEP}.
14915 Specifies the stencil action when both the stencil test and the depth
14916 test pass, or when the stencil test passes and either there is no depth
14917 buffer or depth testing is not enabled. @var{dppass} accepts the same
14918 symbolic constants as @var{sfail}. The initial value is @code{GL_KEEP}.
14922 Stenciling, like depth-buffering, enables and disables drawing on a
14923 per-pixel basis. You draw into the stencil planes using GL drawing
14924 primitives, then render geometry and images, using the stencil planes to
14925 mask out portions of the screen. Stenciling is typically used in
14926 multipass rendering algorithms to achieve special effects, such as
14927 decals, outlining, and constructive solid geometry rendering.
14929 The stencil test conditionally eliminates a pixel based on the outcome
14930 of a comparison between the value in the stencil buffer and a reference
14931 value. To enable and disable the test, call @code{glEnable} and
14932 @code{glDisable} with argument @code{GL_STENCIL_TEST}; to control it,
14933 call @code{glStencilFunc} or @code{glStencilFuncSeparate}.
14935 There can be two separate sets of @var{sfail}, @var{dpfail}, and
14936 @var{dppass} parameters; one affects back-facing polygons, and the other
14937 affects front-facing polygons as well as other non-polygon primitives.
14938 @code{glStencilOp} sets both front and back stencil state to the same
14939 values, as if @code{glStencilOpSeparate} were called with @var{face} set
14940 to @code{GL_FRONT_AND_BACK}.
14942 @code{glStencilOpSeparate} takes three arguments that indicate what
14943 happens to the stored stencil value while stenciling is enabled. If the
14944 stencil test fails, no change is made to the pixel's color or depth
14945 buffers, and @var{sfail} specifies what happens to the stencil buffer
14946 contents. The following eight actions are possible.
14949 @item @code{GL_KEEP}
14950 Keeps the current value.
14952 @item @code{GL_ZERO}
14953 Sets the stencil buffer value to 0.
14955 @item @code{GL_REPLACE}
14956 Sets the stencil buffer value to @var{ref}, as specified by
14957 @code{glStencilFunc}.
14959 @item @code{GL_INCR}
14960 Increments the current stencil buffer value. Clamps to the maximum
14961 representable unsigned value.
14963 @item @code{GL_INCR_WRAP}
14964 Increments the current stencil buffer value. Wraps stencil buffer value
14965 to zero when incrementing the maximum representable unsigned value.
14967 @item @code{GL_DECR}
14968 Decrements the current stencil buffer value. Clamps to 0.
14970 @item @code{GL_DECR_WRAP}
14971 Decrements the current stencil buffer value. Wraps stencil buffer value
14972 to the maximum representable unsigned value when decrementing a stencil
14973 buffer value of zero.
14975 @item @code{GL_INVERT}
14976 Bitwise inverts the current stencil buffer value.
14980 Stencil buffer values are treated as unsigned integers. When incremented
14981 and decremented, values are clamped to 0 and @r{2^@var{n}-1}, where
14982 @r{@var{n}} is the value returned by querying @code{GL_STENCIL_BITS}.
14984 The other two arguments to @code{glStencilOpSeparate} specify stencil
14985 buffer actions that depend on whether subsequent depth buffer tests
14986 succeed (@var{dppass}) or fail (@var{dpfail}) (see @code{glDepthFunc}).
14987 The actions are specified using the same eight symbolic constants as
14988 @var{sfail}. Note that @var{dpfail} is ignored when there is no depth
14989 buffer, or when the depth buffer is not enabled. In these cases,
14990 @var{sfail} and @var{dppass} specify stencil action when the stencil
14991 test fails and passes, respectively.
14993 @code{GL_INVALID_ENUM} is generated if @var{face} is any value other
14994 than @code{GL_FRONT}, @code{GL_BACK}, or @code{GL_FRONT_AND_BACK}.
14996 @code{GL_INVALID_ENUM} is generated if @var{sfail}, @var{dpfail}, or
14997 @var{dppass} is any value other than the eight defined constant values.
14999 @code{GL_INVALID_OPERATION} is generated if @code{glStencilOpSeparate}
15000 is executed between the execution of @code{glBegin} and the
15001 corresponding execution of @code{glEnd}.
15005 @deftypefun void glStencilOp sfail dpfail dppass
15006 Set front and back stencil test actions.
15010 Specifies the action to take when the stencil test fails. Eight symbolic
15011 constants are accepted: @code{GL_KEEP}, @code{GL_ZERO},
15012 @code{GL_REPLACE}, @code{GL_INCR}, @code{GL_INCR_WRAP}, @code{GL_DECR},
15013 @code{GL_DECR_WRAP}, and @code{GL_INVERT}. The initial value is
15017 Specifies the stencil action when the stencil test passes, but the depth
15018 test fails. @var{dpfail} accepts the same symbolic constants as
15019 @var{sfail}. The initial value is @code{GL_KEEP}.
15022 Specifies the stencil action when both the stencil test and the depth
15023 test pass, or when the stencil test passes and either there is no depth
15024 buffer or depth testing is not enabled. @var{dppass} accepts the same
15025 symbolic constants as @var{sfail}. The initial value is @code{GL_KEEP}.
15029 Stenciling, like depth-buffering, enables and disables drawing on a
15030 per-pixel basis. You draw into the stencil planes using GL drawing
15031 primitives, then render geometry and images, using the stencil planes to
15032 mask out portions of the screen. Stenciling is typically used in
15033 multipass rendering algorithms to achieve special effects, such as
15034 decals, outlining, and constructive solid geometry rendering.
15036 The stencil test conditionally eliminates a pixel based on the outcome
15037 of a comparison between the value in the stencil buffer and a reference
15038 value. To enable and disable the test, call @code{glEnable} and
15039 @code{glDisable} with argument @code{GL_STENCIL_TEST}; to control it,
15040 call @code{glStencilFunc} or @code{glStencilFuncSeparate}.
15042 There can be two separate sets of @var{sfail}, @var{dpfail}, and
15043 @var{dppass} parameters; one affects back-facing polygons, and the other
15044 affects front-facing polygons as well as other non-polygon primitives.
15045 @code{glStencilOp} sets both front and back stencil state to the same
15046 values. Use @code{glStencilOpSeparate} to set front and back stencil
15047 state to different values.
15049 @code{glStencilOp} takes three arguments that indicate what happens to
15050 the stored stencil value while stenciling is enabled. If the stencil
15051 test fails, no change is made to the pixel's color or depth buffers, and
15052 @var{sfail} specifies what happens to the stencil buffer contents. The
15053 following eight actions are possible.
15056 @item @code{GL_KEEP}
15057 Keeps the current value.
15059 @item @code{GL_ZERO}
15060 Sets the stencil buffer value to 0.
15062 @item @code{GL_REPLACE}
15063 Sets the stencil buffer value to @var{ref}, as specified by
15064 @code{glStencilFunc}.
15066 @item @code{GL_INCR}
15067 Increments the current stencil buffer value. Clamps to the maximum
15068 representable unsigned value.
15070 @item @code{GL_INCR_WRAP}
15071 Increments the current stencil buffer value. Wraps stencil buffer value
15072 to zero when incrementing the maximum representable unsigned value.
15074 @item @code{GL_DECR}
15075 Decrements the current stencil buffer value. Clamps to 0.
15077 @item @code{GL_DECR_WRAP}
15078 Decrements the current stencil buffer value. Wraps stencil buffer value
15079 to the maximum representable unsigned value when decrementing a stencil
15080 buffer value of zero.
15082 @item @code{GL_INVERT}
15083 Bitwise inverts the current stencil buffer value.
15087 Stencil buffer values are treated as unsigned integers. When incremented
15088 and decremented, values are clamped to 0 and @r{2^@var{n}-1}, where
15089 @r{@var{n}} is the value returned by querying @code{GL_STENCIL_BITS}.
15091 The other two arguments to @code{glStencilOp} specify stencil buffer
15092 actions that depend on whether subsequent depth buffer tests succeed
15093 (@var{dppass}) or fail (@var{dpfail}) (see @code{glDepthFunc}). The
15094 actions are specified using the same eight symbolic constants as
15095 @var{sfail}. Note that @var{dpfail} is ignored when there is no depth
15096 buffer, or when the depth buffer is not enabled. In these cases,
15097 @var{sfail} and @var{dppass} specify stencil action when the stencil
15098 test fails and passes, respectively.
15100 @code{GL_INVALID_ENUM} is generated if @var{sfail}, @var{dpfail}, or
15101 @var{dppass} is any value other than the eight defined constant values.
15103 @code{GL_INVALID_OPERATION} is generated if @code{glStencilOp} is
15104 executed between the execution of @code{glBegin} and the corresponding
15105 execution of @code{glEnd}.
15109 @deftypefun void glTexCoordPointer size type stride pointer
15110 Define an array of texture coordinates.
15114 Specifies the number of coordinates per array element. Must be 1, 2, 3,
15115 or 4. The initial value is 4.
15118 Specifies the data type of each texture coordinate. Symbolic constants
15119 @code{GL_SHORT}, @code{GL_INT}, @code{GL_FLOAT}, or @code{GL_DOUBLE} are
15120 accepted. The initial value is @code{GL_FLOAT}.
15123 Specifies the byte offset between consecutive texture coordinate sets.
15124 If @var{stride} is 0, the array elements are understood to be tightly
15125 packed. The initial value is 0.
15127 @item @var{pointer}
15128 Specifies a pointer to the first coordinate of the first texture
15129 coordinate set in the array. The initial value is 0.
15133 @code{glTexCoordPointer} specifies the location and data format of an
15134 array of texture coordinates to use when rendering. @var{size} specifies
15135 the number of coordinates per texture coordinate set, and must be 1, 2,
15136 3, or 4. @var{type} specifies the data type of each texture coordinate,
15137 and @var{stride} specifies the byte stride from one texture coordinate
15138 set to the next, allowing vertices and attributes to be packed into a
15139 single array or stored in separate arrays. (Single-array storage may be
15140 more efficient on some implementations; see @code{glInterleavedArrays}.)
15142 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
15143 target (see @code{glBindBuffer}) while a texture coordinate array is
15144 specified, @var{pointer} is treated as a byte offset into the buffer
15145 object's data store. Also, the buffer object binding
15146 (@code{GL_ARRAY_BUFFER_BINDING}) is saved as texture coordinate vertex
15147 array client-side state (@code{GL_TEXTURE_COORD_ARRAY_BUFFER_BINDING}).
15149 When a texture coordinate array is specified, @var{size}, @var{type},
15150 @var{stride}, and @var{pointer} are saved as client-side state, in
15151 addition to the current vertex array buffer object binding.
15153 To enable and disable a texture coordinate array, call
15154 @code{glEnableClientState} and @code{glDisableClientState} with the
15155 argument @code{GL_TEXTURE_COORD_ARRAY}. If enabled, the texture
15156 coordinate array is used when @code{glArrayElement},
15157 @code{glDrawArrays}, @code{glMultiDrawArrays}, @code{glDrawElements},
15158 @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called.
15160 @code{GL_INVALID_VALUE} is generated if @var{size} is not 1, 2, 3, or 4.
15162 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
15165 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
15169 @deftypefun void glTexCoord1i s
15170 @deftypefunx void glTexCoord1f s
15171 @deftypefunx void glTexCoord2i s t
15172 @deftypefunx void glTexCoord2f s t
15173 @deftypefunx void glTexCoord3i s t r
15174 @deftypefunx void glTexCoord3f s t r
15175 @deftypefunx void glTexCoord4i s t r q
15176 @deftypefunx void glTexCoord4f s t r q
15177 Set the current texture coordinates.
15184 Specify @var{s}, @var{t}, @var{r}, and @var{q} texture coordinates. Not
15185 all parameters are present in all forms of the command.
15189 @code{glTexCoord} specifies texture coordinates in one, two, three, or
15190 four dimensions. @code{glTexCoord1} sets the current texture coordinates
15191 to @r{(@var{s},001)}; a call to @code{glTexCoord2} sets them to
15192 @r{(@var{s},@var{t}01)}. Similarly, @code{glTexCoord3} specifies the
15193 texture coordinates as @r{(@var{s},@var{t}@var{r}1)}, and
15194 @code{glTexCoord4} defines all four components explicitly as
15195 @r{(@var{s},@var{t}@var{r}@var{q})}.
15197 The current texture coordinates are part of the data that is associated
15198 with each vertex and with the current raster position. Initially, the
15199 values for @var{s}, @var{t}, @var{r}, and @var{q} are (0, 0, 0, 1).
15205 @deftypefun void glTexEnvf target pname param
15206 @deftypefunx void glTexEnvi target pname param
15207 Set texture environment parameters.
15211 Specifies a texture environment. May be @code{GL_TEXTURE_ENV},
15212 @code{GL_TEXTURE_FILTER_CONTROL} or @code{GL_POINT_SPRITE}.
15215 Specifies the symbolic name of a single-valued texture environment
15216 parameter. May be either @code{GL_TEXTURE_ENV_MODE},
15217 @code{GL_TEXTURE_LOD_BIAS}, @code{GL_COMBINE_RGB},
15218 @code{GL_COMBINE_ALPHA}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB},
15219 @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA},
15220 @code{GL_SRC2_ALPHA}, @code{GL_OPERAND0_RGB}, @code{GL_OPERAND1_RGB},
15221 @code{GL_OPERAND2_RGB}, @code{GL_OPERAND0_ALPHA},
15222 @code{GL_OPERAND1_ALPHA}, @code{GL_OPERAND2_ALPHA}, @code{GL_RGB_SCALE},
15223 @code{GL_ALPHA_SCALE}, or @code{GL_COORD_REPLACE}.
15226 Specifies a single symbolic constant, one of @code{GL_ADD},
15227 @code{GL_ADD_SIGNED}, @code{GL_INTERPOLATE}, @code{GL_MODULATE},
15228 @code{GL_DECAL}, @code{GL_BLEND}, @code{GL_REPLACE}, @code{GL_SUBTRACT},
15229 @code{GL_COMBINE}, @code{GL_TEXTURE}, @code{GL_CONSTANT},
15230 @code{GL_PRIMARY_COLOR}, @code{GL_PREVIOUS}, @code{GL_SRC_COLOR},
15231 @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_SRC_ALPHA},
15232 @code{GL_ONE_MINUS_SRC_ALPHA}, a single boolean value for the point
15233 sprite texture coordinate replacement, a single floating-point value for
15234 the texture level-of-detail bias, or 1.0, 2.0, or 4.0 when specifying
15235 the @code{GL_RGB_SCALE} or @code{GL_ALPHA_SCALE}.
15239 A texture environment specifies how texture values are interpreted when
15240 a fragment is textured. When @var{target} is
15241 @code{GL_TEXTURE_FILTER_CONTROL}, @var{pname} must be
15242 @code{GL_TEXTURE_LOD_BIAS}. When @var{target} is @code{GL_TEXTURE_ENV},
15243 @var{pname} can be @code{GL_TEXTURE_ENV_MODE},
15244 @code{GL_TEXTURE_ENV_COLOR}, @code{GL_COMBINE_RGB},
15245 @code{GL_COMBINE_ALPHA}, @code{GL_RGB_SCALE}, @code{GL_ALPHA_SCALE},
15246 @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, @code{GL_SRC2_RGB},
15247 @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, or @code{GL_SRC2_ALPHA}.
15249 If @var{pname} is @code{GL_TEXTURE_ENV_MODE}, then @var{params} is (or
15250 points to) the symbolic name of a texture function. Six texture
15251 functions may be specified: @code{GL_ADD}, @code{GL_MODULATE},
15252 @code{GL_DECAL}, @code{GL_BLEND}, @code{GL_REPLACE}, or
15255 The following table shows the correspondence of filtered texture values
15256 @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}},
15257 @r{@var{A}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{I}_@var{t}} to texture
15258 source components. @r{@var{C}_@var{s}} and @r{@var{A}_@var{s}} are used
15259 by the texture functions described below.
15265 Texture Base Internal Format
15266 @r{@code{C}_@var{s}}, @r{@code{A}_@var{s}}
15268 @item @code{GL_ALPHA}
15269 (0, 0, 0) , @r{@var{A}_@var{t}}
15271 @item @code{GL_LUMINANCE}
15272 ( @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}} ) , 1
15274 @item @code{GL_LUMINANCE_ALPHA}
15275 ( @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}} ) ,
15276 @r{@var{A}_@var{t}}
15278 @item @code{GL_INTENSITY}
15279 ( @r{@var{I}_@var{t}}, @r{@var{I}_@var{t}}, @r{@var{I}_@var{t}} ) ,
15280 @r{@var{I}_@var{t}}
15282 @item @code{GL_RGB}
15283 ( @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}} ) , 1
15285 @item @code{GL_RGBA}
15286 ( @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}} ) ,
15287 @r{@var{A}_@var{t}}
15291 A texture function acts on the fragment to be textured using the texture
15292 image value that applies to the fragment (see @code{glTexParameter}) and
15293 produces an RGBA color for that fragment. The following table shows how
15294 the RGBA color is produced for each of the first five texture functions
15295 that can be chosen. @r{@var{C}} is a triple of color values (RGB) and
15296 @r{@var{A}} is the associated alpha value. RGBA values extracted from a
15297 texture image are in the range [0,1]. The subscript @r{@var{p}} refers
15298 to the color computed from the previous texture stage (or the incoming
15299 fragment if processing texture stage 0), the subscript @r{@var{s}} to
15300 the texture source color, the subscript @r{@var{c}} to the texture
15301 environment color, and the subscript @r{@var{v}} indicates a value
15302 produced by the texture function.
15308 Texture Base Internal Format
15309 @code{Value}, @code{GL_REPLACE} Function , @code{GL_MODULATE} Function ,
15310 @code{GL_DECAL} Function , @code{GL_BLEND} Function , @code{GL_ADD}
15313 @item @code{GL_ALPHA}
15314 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{p}}, @r{@var{C}_@var{p}},
15315 undefined , @r{@var{C}_@var{p}}, @r{@var{C}_@var{p}}
15318 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}},
15319 @r{@var{A}_@var{p}@var{A}_@var{s}}, ,
15320 @r{@var{A}_@var{v}=@var{A}_@var{p}@var{A}_@var{s}},
15321 @r{@var{A}_@var{p}@var{A}_@var{s}}
15323 @item @code{GL_LUMINANCE}
15324 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
15325 @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined ,
15326 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
15327 @r{@var{C}_@var{p}+@var{C}_@var{s}}
15331 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, ,
15332 @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}
15334 @item @code{GL_LUMINANCE_ALPHA}
15335 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
15336 @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined ,
15337 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
15338 @r{@var{C}_@var{p}+@var{C}_@var{s}}
15342 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}},
15343 @r{@var{A}_@var{p}@var{A}_@var{s}}, ,
15344 @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}@var{A}_@var{s}}
15346 @item @code{GL_INTENSITY}
15347 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
15348 @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined ,
15349 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
15350 @r{@var{C}_@var{p}+@var{C}_@var{s}}
15353 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}},
15354 @r{@var{A}_@var{p}@var{A}_@var{s}}, ,
15355 @r{@var{A}_@var{p}(1-@var{A}_@var{s},)+@var{A}_@var{c}@var{A}_@var{s}},
15356 @r{@var{A}_@var{p}+@var{A}_@var{s}}
15358 @item @code{GL_RGB}
15359 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
15360 @r{@var{C}_@var{p}@var{C}_@var{s}}, @r{@var{C}_@var{s}},
15361 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
15362 @r{@var{C}_@var{p}+@var{C}_@var{s}}
15366 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}},
15367 @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}
15369 @item @code{GL_RGBA}
15370 @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}},
15371 @r{@var{C}_@var{p}@var{C}_@var{s}},
15372 @r{@var{C}_@var{p}(1-@var{A}_@var{s},)+@var{C}_@var{s}@var{A}_@var{s}},
15373 @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}},
15374 @r{@var{C}_@var{p}+@var{C}_@var{s}}
15378 @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}},
15379 @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}},
15380 @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}@var{A}_@var{s}}
15384 If @var{pname} is @code{GL_TEXTURE_ENV_MODE}, and @var{params} is
15385 @code{GL_COMBINE}, the form of the texture function depends on the
15386 values of @code{GL_COMBINE_RGB} and @code{GL_COMBINE_ALPHA}.
15388 The following describes how the texture sources, as specified by
15389 @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, @code{GL_SRC2_RGB},
15390 @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, and @code{GL_SRC2_ALPHA},
15391 are combined to produce a final texture color. In the following tables,
15392 @code{GL_SRC0_c} is represented by @r{@var{Arg0}}, @code{GL_SRC1_c} is
15393 represented by @r{@var{Arg1}}, and @code{GL_SRC2_c} is represented by
15396 @code{GL_COMBINE_RGB} accepts any of @code{GL_REPLACE},
15397 @code{GL_MODULATE}, @code{GL_ADD}, @code{GL_ADD_SIGNED},
15398 @code{GL_INTERPOLATE}, @code{GL_SUBTRACT}, @code{GL_DOT3_RGB}, or
15399 @code{GL_DOT3_RGBA}.
15404 @item @strong{@code{GL_COMBINE_RGB}}
15405 @strong{Texture Function}
15407 @item @code{GL_REPLACE}
15410 @item @code{GL_MODULATE}
15411 @r{@var{Arg0}×@var{Arg1}}
15413 @item @code{GL_ADD}
15414 @r{@var{Arg0}+@var{Arg1}}
15416 @item @code{GL_ADD_SIGNED}
15417 @r{@var{Arg0}+@var{Arg1}-0.5}
15419 @item @code{GL_INTERPOLATE}
15420 @r{@var{Arg0}×@var{Arg2}+@var{Arg1}×(1-@var{Arg2},)}
15422 @item @code{GL_SUBTRACT}
15423 @r{@var{Arg0}-@var{Arg1}}
15425 @item @code{GL_DOT3_RGB}
15426 or @code{GL_DOT3_RGBA}
15427 @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,),),)}
15431 The scalar results for @code{GL_DOT3_RGB} and @code{GL_DOT3_RGBA} are
15432 placed into each of the 3 (RGB) or 4 (RGBA) components on output.
15434 Likewise, @code{GL_COMBINE_ALPHA} accepts any of @code{GL_REPLACE},
15435 @code{GL_MODULATE}, @code{GL_ADD}, @code{GL_ADD_SIGNED},
15436 @code{GL_INTERPOLATE}, or @code{GL_SUBTRACT}. The following table
15437 describes how alpha values are combined:
15442 @item @strong{@code{GL_COMBINE_ALPHA}}
15443 @strong{Texture Function}
15445 @item @code{GL_REPLACE}
15448 @item @code{GL_MODULATE}
15449 @r{@var{Arg0}×@var{Arg1}}
15451 @item @code{GL_ADD}
15452 @r{@var{Arg0}+@var{Arg1}}
15454 @item @code{GL_ADD_SIGNED}
15455 @r{@var{Arg0}+@var{Arg1}-0.5}
15457 @item @code{GL_INTERPOLATE}
15458 @r{@var{Arg0}×@var{Arg2}+@var{Arg1}×(1-@var{Arg2},)}
15460 @item @code{GL_SUBTRACT}
15461 @r{@var{Arg0}-@var{Arg1}}
15465 In the following tables, the value @r{@var{C}_@var{s}} represents the
15466 color sampled from the currently bound texture, @r{@var{C}_@var{c}}
15467 represents the constant texture-environment color, @r{@var{C}_@var{f}}
15468 represents the primary color of the incoming fragment, and
15469 @r{@var{C}_@var{p}} represents the color computed from the previous
15470 texture stage or @r{@var{C}_@var{f}} if processing texture stage 0.
15471 Likewise, @r{@var{A}_@var{s}}, @r{@var{A}_@var{c}}, @r{@var{A}_@var{f}},
15472 and @r{@var{A}_@var{p}} represent the respective alpha values.
15474 The following table describes the values assigned to @r{@var{Arg0}},
15475 @r{@var{Arg1}}, and @r{@var{Arg2}} based upon the RGB sources and
15481 @item @strong{@code{GL_SRCn_RGB}}
15482 @strong{@code{GL_OPERANDn_RGB}}, @strong{Argument Value}
15484 @item @code{GL_TEXTURE}
15485 @code{GL_SRC_COLOR}, @r{@var{C}_@var{s},}
15488 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{s},}
15491 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},}
15494 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},}
15496 @item @code{GL_TEXTUREn}
15497 @code{GL_SRC_COLOR}, @r{@var{C}_@var{s},}
15500 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{s},}
15503 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},}
15506 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},}
15508 @item @code{GL_CONSTANT}
15509 @code{GL_SRC_COLOR}, @r{@var{C}_@var{c},}
15512 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{c},}
15515 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{c},}
15518 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{c},}
15520 @item @code{GL_PRIMARY_COLOR}
15521 @code{GL_SRC_COLOR}, @r{@var{C}_@var{f},}
15524 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{f},}
15527 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{f},}
15530 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{f},}
15532 @item @code{GL_PREVIOUS}
15533 @code{GL_SRC_COLOR}, @r{@var{C}_@var{p},}
15536 @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{p},}
15539 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{p},}
15542 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{p},}
15546 For @code{GL_TEXTUREn} sources, @r{@var{C}_@var{s}} and
15547 @r{@var{A}_@var{s}} represent the color and alpha, respectively,
15548 produced from texture stage @r{@var{n}}.
15550 The follow table describes the values assigned to @r{@var{Arg0}},
15551 @r{@var{Arg1}}, and @r{@var{Arg2}} based upon the alpha sources and
15557 @item @strong{@code{GL_SRCn_ALPHA}}
15558 @strong{@code{GL_OPERANDn_ALPHA}}, @strong{Argument Value}
15560 @item @code{GL_TEXTURE}
15561 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},}
15564 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},}
15566 @item @code{GL_TEXTUREn}
15567 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},}
15570 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},}
15572 @item @code{GL_CONSTANT}
15573 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{c},}
15576 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{c},}
15578 @item @code{GL_PRIMARY_COLOR}
15579 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{f},}
15582 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{f},}
15584 @item @code{GL_PREVIOUS}
15585 @code{GL_SRC_ALPHA}, @r{@var{A}_@var{p},}
15588 @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{p},}
15592 The RGB and alpha results of the texture function are multipled by the
15593 values of @code{GL_RGB_SCALE} and @code{GL_ALPHA_SCALE}, respectively,
15594 and clamped to the range @r{[0,1]}.
15596 If @var{pname} is @code{GL_TEXTURE_ENV_COLOR}, @var{params} is a pointer
15597 to an array that holds an RGBA color consisting of four values. Integer
15598 color components are interpreted linearly such that the most positive
15599 integer maps to 1.0, and the most negative integer maps to -1.0. The
15600 values are clamped to the range [0,1] when they are specified.
15601 @r{@var{C}_@var{c}} takes these four values.
15603 If @var{pname} is @code{GL_TEXTURE_LOD_BIAS}, the value specified is
15604 added to the texture level-of-detail parameter, that selects which
15605 mipmap, or mipmaps depending upon the selected
15606 @code{GL_TEXTURE_MIN_FILTER}, will be sampled.
15608 @code{GL_TEXTURE_ENV_MODE} defaults to @code{GL_MODULATE} and
15609 @code{GL_TEXTURE_ENV_COLOR} defaults to (0, 0, 0, 0).
15611 If @var{target} is @code{GL_POINT_SPRITE} and @var{pname} is
15612 @code{GL_COORD_REPLACE}, the boolean value specified is used to either
15613 enable or disable point sprite texture coordinate replacement. The
15614 default value is @code{GL_FALSE}.
15616 @code{GL_INVALID_ENUM} is generated when @var{target} or @var{pname} is
15617 not one of the accepted defined values, or when @var{params} should have
15618 a defined constant value (based on the value of @var{pname}) and does
15621 @code{GL_INVALID_VALUE} is generated if the @var{params} value for
15622 @code{GL_RGB_SCALE} or @code{GL_ALPHA_SCALE} are not one of 1.0, 2.0, or
15625 @code{GL_INVALID_OPERATION} is generated if @code{glTexEnv} is executed
15626 between the execution of @code{glBegin} and the corresponding execution
15631 @deftypefun void glTexGeni coord pname param
15632 @deftypefunx void glTexGenf coord pname param
15633 Control the generation of texture coordinates.
15637 Specifies a texture coordinate. Must be one of @code{GL_S}, @code{GL_T},
15638 @code{GL_R}, or @code{GL_Q}.
15641 Specifies the symbolic name of the texture-coordinate generation
15642 function. Must be @code{GL_TEXTURE_GEN_MODE}.
15645 Specifies a single-valued texture generation parameter, one of
15646 @code{GL_OBJECT_LINEAR}, @code{GL_EYE_LINEAR}, @code{GL_SPHERE_MAP},
15647 @code{GL_NORMAL_MAP}, or @code{GL_REFLECTION_MAP}.
15651 @code{glTexGen} selects a texture-coordinate generation function or
15652 supplies coefficients for one of the functions. @var{coord} names one of
15653 the (@var{s}, @var{t}, @var{r}, @var{q}) texture coordinates; it must be
15654 one of the symbols @code{GL_S}, @code{GL_T}, @code{GL_R}, or
15655 @code{GL_Q}. @var{pname} must be one of three symbolic constants:
15656 @code{GL_TEXTURE_GEN_MODE}, @code{GL_OBJECT_PLANE}, or
15657 @code{GL_EYE_PLANE}. If @var{pname} is @code{GL_TEXTURE_GEN_MODE}, then
15658 @var{params} chooses a mode, one of @code{GL_OBJECT_LINEAR},
15659 @code{GL_EYE_LINEAR}, @code{GL_SPHERE_MAP}, @code{GL_NORMAL_MAP}, or
15660 @code{GL_REFLECTION_MAP}. If @var{pname} is either
15661 @code{GL_OBJECT_PLANE} or @code{GL_EYE_PLANE}, @var{params} contains
15662 coefficients for the corresponding texture generation function.
15664 If the texture generation function is @code{GL_OBJECT_LINEAR}, the
15667 @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}}
15669 is used, where @r{@var{g}} is the value computed for the coordinate
15670 named in @var{coord}, @r{@var{p}_1}, @r{@var{p}_2}, @r{@var{p}_3}, and
15671 @r{@var{p}_4} are the four values supplied in @var{params}, and
15672 @r{@var{x}_@var{o}}, @r{@var{y}_@var{o}}, @r{@var{z}_@var{o}}, and
15673 @r{@var{w}_@var{o}} are the object coordinates of the vertex. This
15674 function can be used, for example, to texture-map terrain using sea
15675 level as a reference plane (defined by @r{@var{p}_1}, @r{@var{p}_2},
15676 @r{@var{p}_3}, and @r{@var{p}_4}). The altitude of a terrain vertex is
15677 computed by the @code{GL_OBJECT_LINEAR} coordinate generation function
15678 as its distance from sea level; that altitude can then be used to index
15679 the texture image to map white snow onto peaks and green grass onto
15682 If the texture generation function is @code{GL_EYE_LINEAR}, the function
15684 @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}}
15688 @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}
15690 and @r{@var{x}_@var{e}}, @r{@var{y}_@var{e}}, @r{@var{z}_@var{e}}, and
15691 @r{@var{w}_@var{e}} are the eye coordinates of the vertex,
15692 @r{@var{p}_1}, @r{@var{p}_2}, @r{@var{p}_3}, and @r{@var{p}_4} are the
15693 values supplied in @var{params}, and @r{@var{M}} is the modelview matrix
15694 when @code{glTexGen} is invoked. If @r{@var{M}} is poorly conditioned or
15695 singular, texture coordinates generated by the resulting function may be
15696 inaccurate or undefined.
15698 Note that the values in @var{params} define a reference plane in eye
15699 coordinates. The modelview matrix that is applied to them may not be the
15700 same one in effect when the polygon vertices are transformed. This
15701 function establishes a field of texture coordinates that can produce
15702 dynamic contour lines on moving objects.
15704 If the texture generation function is @code{GL_SPHERE_MAP} and
15705 @var{coord} is either @code{GL_S} or @code{GL_T}, @r{@var{s}} and
15706 @r{@var{t}} texture coordinates are generated as follows. Let @var{u} be
15707 the unit vector pointing from the origin to the polygon vertex (in eye
15708 coordinates). Let @var{n} sup prime be the current normal, after
15709 transformation to eye coordinates. Let
15711 @r{@var{f}=(@var{f}_@var{x}@var{f}_@var{y}@var{f}_@var{z},)^@var{T}}
15712 be the reflection vector such that
15714 @r{@var{f}=@var{u}-2@var{n}^″@var{n}^″,^@var{T}@var{u}}
15717 @r{@var{m}=2√(@var{f}_@var{x},^2+@var{f}_@var{y},^2+(@var{f}_@var{z}+1,)^2,)}.
15718 Then the values assigned to the @r{@var{s}} and @r{@var{t}} texture
15721 @r{@var{s}=@var{f}_@var{x}/@var{m}+1/2}
15723 @r{@var{t}=@var{f}_@var{y}/@var{m}+1/2}
15725 To enable or disable a texture-coordinate generation function, call
15726 @code{glEnable} or @code{glDisable} with one of the symbolic
15727 texture-coordinate names (@code{GL_TEXTURE_GEN_S},
15728 @code{GL_TEXTURE_GEN_T}, @code{GL_TEXTURE_GEN_R}, or
15729 @code{GL_TEXTURE_GEN_Q}) as the argument. When enabled, the specified
15730 texture coordinate is computed according to the generating function
15731 associated with that coordinate. When disabled, subsequent vertices take
15732 the specified texture coordinate from the current set of texture
15733 coordinates. Initially, all texture generation functions are set to
15734 @code{GL_EYE_LINEAR} and are disabled. Both @r{@var{s}} plane equations
15735 are (1, 0, 0, 0), both @r{@var{t}} plane equations are (0, 1, 0, 0), and
15736 all @r{@var{r}} and @r{@var{q}} plane equations are (0, 0, 0, 0).
15738 When the @code{ARB_multitexture} extension is supported, @code{glTexGen}
15739 sets the texture generation parameters for the currently active texture
15740 unit, selected with @code{glActiveTexture}.
15742 @code{GL_INVALID_ENUM} is generated when @var{coord} or @var{pname} is
15743 not an accepted defined value, or when @var{pname} is
15744 @code{GL_TEXTURE_GEN_MODE} and @var{params} is not an accepted defined
15747 @code{GL_INVALID_ENUM} is generated when @var{pname} is
15748 @code{GL_TEXTURE_GEN_MODE}, @var{params} is @code{GL_SPHERE_MAP}, and
15749 @var{coord} is either @code{GL_R} or @code{GL_Q}.
15751 @code{GL_INVALID_OPERATION} is generated if @code{glTexGen} is executed
15752 between the execution of @code{glBegin} and the corresponding execution
15757 @deftypefun void glTexImage1D target level internalFormat width border format type data
15758 Specify a one-dimensional texture image.
15762 Specifies the target texture. Must be @code{GL_TEXTURE_1D} or
15763 @code{GL_PROXY_TEXTURE_1D}.
15766 Specifies the level-of-detail number. Level 0 is the base image level.
15767 Level @var{n} is the @var{n}th mipmap reduction image.
15769 @item @var{internalFormat}
15770 Specifies the number of color components in the texture. Must be 1, 2,
15771 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA},
15772 @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
15773 @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA},
15774 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
15775 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
15776 @code{GL_COMPRESSED_RGBA}, @code{GL_DEPTH_COMPONENT},
15777 @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24},
15778 @code{GL_DEPTH_COMPONENT32}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
15779 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
15780 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
15781 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
15782 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
15783 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY},
15784 @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12},
15785 @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
15786 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
15787 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
15788 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
15789 @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE},
15790 @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
15791 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
15792 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
15795 Specifies the width of the texture image including the border if any. If
15796 the GL version does not support non-power-of-two sizes, this value must
15797 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
15798 implementations support texture images that are at least 64 texels wide.
15799 The height of the 1D texture image is 1.
15802 Specifies the width of the border. Must be either 0 or 1.
15805 Specifies the format of the pixel data. The following symbolic values
15806 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
15807 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
15808 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
15809 @code{GL_LUMINANCE_ALPHA}.
15812 Specifies the data type of the pixel data. The following symbolic values
15813 are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
15814 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
15815 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
15816 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
15817 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
15818 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
15819 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
15820 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
15821 and @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
15824 Specifies a pointer to the image data in memory.
15828 Texturing maps a portion of a specified texture image onto each
15829 graphical primitive for which texturing is enabled. To enable and
15830 disable one-dimensional texturing, call @code{glEnable} and
15831 @code{glDisable} with argument @code{GL_TEXTURE_1D}.
15833 Texture images are defined with @code{glTexImage1D}. The arguments
15834 describe the parameters of the texture image, such as width, width of
15835 the border, level-of-detail number (see @code{glTexParameter}), and the
15836 internal resolution and format used to store the image. The last three
15837 arguments describe how the image is represented in memory; they are
15838 identical to the pixel formats used for @code{glDrawPixels}.
15840 If @var{target} is @code{GL_PROXY_TEXTURE_1D}, no data is read from
15841 @var{data}, but all of the texture image state is recalculated, checked
15842 for consistency, and checked against the implementation's capabilities.
15843 If the implementation cannot handle a texture of the requested texture
15844 size, it sets all of the image state to 0, but does not generate an
15845 error (see @code{glGetError}). To query for an entire mipmap array, use
15846 an image array level greater than or equal to 1.
15848 If @var{target} is @code{GL_TEXTURE_1D}, data is read from @var{data} as
15849 a sequence of signed or unsigned bytes, shorts, or longs, or
15850 single-precision floating-point values, depending on @var{type}. These
15851 values are grouped into sets of one, two, three, or four values,
15852 depending on @var{format}, to form elements. If @var{type} is
15853 @code{GL_BITMAP}, the data is considered as a string of unsigned bytes
15854 (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is
15855 treated as eight 1-bit elements, with bit ordering determined by
15856 @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}).
15858 If a non-zero named buffer object is bound to the
15859 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
15860 texture image is specified, @var{data} is treated as a byte offset into
15861 the buffer object's data store.
15863 The first element corresponds to the left end of the texture array.
15864 Subsequent elements progress left-to-right through the remaining texels
15865 in the texture array. The final element corresponds to the right end of
15868 @var{format} determines the composition of each element in @var{data}.
15869 It can assume one of these symbolic values:
15872 @item @code{GL_COLOR_INDEX}
15873 Each element is a single value, a color index. The GL converts it to
15874 fixed point (with an unspecified number of zero bits to the right of the
15875 binary point), shifted left or right depending on the value and sign of
15876 @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see
15877 @code{glPixelTransfer}). The resulting index is converted to a set of
15878 color components using the @code{GL_PIXEL_MAP_I_TO_R},
15879 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
15880 @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1].
15882 @item @code{GL_RED}
15883 Each element is a single red component. The GL converts it to floating
15884 point and assembles it into an RGBA element by attaching 0 for green and
15885 blue, and 1 for alpha. Each component is then multiplied by the signed
15886 scale factor @code{GL_c_SCALE}, added to the signed bias
15887 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
15888 @code{glPixelTransfer}).
15890 @item @code{GL_GREEN}
15891 Each element is a single green component. The GL converts it to floating
15892 point and assembles it into an RGBA element by attaching 0 for red and
15893 blue, and 1 for alpha. Each component is then multiplied by the signed
15894 scale factor @code{GL_c_SCALE}, added to the signed bias
15895 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
15896 @code{glPixelTransfer}).
15898 @item @code{GL_BLUE}
15899 Each element is a single blue component. The GL converts it to floating
15900 point and assembles it into an RGBA element by attaching 0 for red and
15901 green, and 1 for alpha. Each component is then multiplied by the signed
15902 scale factor @code{GL_c_SCALE}, added to the signed bias
15903 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
15904 @code{glPixelTransfer}).
15906 @item @code{GL_ALPHA}
15907 Each element is a single alpha component. The GL converts it to floating
15908 point and assembles it into an RGBA element by attaching 0 for red,
15909 green, and blue. Each component is then multiplied by the signed scale
15910 factor @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
15911 clamped to the range [0,1] (see @code{glPixelTransfer}).
15913 @item @code{GL_INTENSITY}
15914 Each element is a single intensity value. The GL converts it to floating
15915 point, then assembles it into an RGBA element by replicating the
15916 intensity value three times for red, green, blue, and alpha. Each
15917 component is then multiplied by the signed scale factor
15918 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
15919 clamped to the range [0,1] (see @code{glPixelTransfer}).
15921 @item @code{GL_RGB}
15922 @item @code{GL_BGR}
15923 Each element is an RGB triple. The GL converts it to floating point and
15924 assembles it into an RGBA element by attaching 1 for alpha. Each
15925 component is then multiplied by the signed scale factor
15926 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
15927 clamped to the range [0,1] (see @code{glPixelTransfer}).
15929 @item @code{GL_RGBA}
15930 @item @code{GL_BGRA}
15931 Each element contains all four components. Each component is multiplied
15932 by the signed scale factor @code{GL_c_SCALE}, added to the signed bias
15933 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
15934 @code{glPixelTransfer}).
15936 @item @code{GL_LUMINANCE}
15937 Each element is a single luminance value. The GL converts it to floating
15938 point, then assembles it into an RGBA element by replicating the
15939 luminance value three times for red, green, and blue and attaching 1 for
15940 alpha. Each component is then multiplied by the signed scale factor
15941 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
15942 clamped to the range [0,1] (see @code{glPixelTransfer}).
15944 @item @code{GL_LUMINANCE_ALPHA}
15945 Each element is a luminance/alpha pair. The GL converts it to floating
15946 point, then assembles it into an RGBA element by replicating the
15947 luminance value three times for red, green, and blue. Each component is
15948 then multiplied by the signed scale factor @code{GL_c_SCALE}, added to
15949 the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see
15950 @code{glPixelTransfer}).
15952 @item @code{GL_DEPTH_COMPONENT}
15953 Each element is a single depth value. The GL converts it to floating
15954 point, multiplies by the signed scale factor @code{GL_DEPTH_SCALE}, adds
15955 the signed bias @code{GL_DEPTH_BIAS}, and clamps to the range [0,1] (see
15956 @code{glPixelTransfer}).
15960 Refer to the @code{glDrawPixels} reference page for a description of the
15961 acceptable values for the @var{type} parameter.
15963 If an application wants to store the texture at a certain resolution or
15964 in a certain format, it can request the resolution and format with
15965 @var{internalFormat}. The GL will choose an internal representation that
15966 closely approximates that requested by @var{internalFormat}, but it may
15967 not match exactly. (The representations specified by
15968 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and
15969 @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 may
15970 also be used to specify the above representations.)
15972 If the @var{internalFormat} parameter is one of the generic compressed
15973 formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
15974 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
15975 @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will
15976 replace the internal format with the symbolic constant for a specific
15977 internal format and compress the texture before storage. If no
15978 corresponding internal format is available, or the GL can not compress
15979 that image for any reason, the internal format is instead replaced with
15980 a corresponding base internal format.
15982 If the @var{internalFormat} parameter is @code{GL_SRGB},
15983 @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8},
15984 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
15985 or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red,
15986 green, blue, or luminance components are encoded in the sRGB color
15987 space. Any alpha component is left unchanged. The conversion from the
15988 sRGB encoded component @r{@var{c}_@var{s}} to a linear component
15989 @r{@var{c}_@var{l}} is:
15991 @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045),
15992 ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)}
15994 Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1].
15996 Use the @code{GL_PROXY_TEXTURE_1D} target to try out a resolution and
15997 format. The implementation will update and recompute its best match for
15998 the requested storage resolution and format. To then query this state,
15999 call @code{glGetTexLevelParameter}. If the texture cannot be
16000 accommodated, texture state is set to 0.
16002 A one-component texture image uses only the red component of the RGBA
16003 color from @var{data}. A two-component image uses the R and A values. A
16004 three-component image uses the R, G, and B values. A four-component
16005 image uses all of the RGBA components.
16007 Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA textures
16008 during texture filtering and application. Image-based shadowing can be
16009 enabled by comparing texture r coordinates to depth texture values to
16010 generate a boolean result. See @code{glTexParameter} for details on
16011 texture comparison.
16013 @code{GL_INVALID_ENUM} is generated if @var{target} is not
16014 @code{GL_TEXTURE_1D} or @code{GL_PROXY_TEXTURE_1D}.
16016 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
16017 format constant. Format constants other than @code{GL_STENCIL_INDEX} are
16020 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
16023 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
16024 and @var{format} is not @code{GL_COLOR_INDEX}.
16026 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
16028 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
16029 @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of
16030 @code{GL_MAX_TEXTURE_SIZE}.
16032 @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1,
16033 2, 3, 4, or one of the accepted resolution and format symbolic
16036 @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or
16037 greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
16039 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
16040 not supported and the @var{width} cannot be represented as
16041 @r{2^@var{n}+2(@var{border},)} for some integer value of @var{n}.
16043 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
16045 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
16046 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
16047 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
16048 and @var{format} is not @code{GL_RGB}.
16050 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
16051 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
16052 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
16053 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
16054 @code{GL_UNSIGNED_INT_10_10_10_2}, or
16055 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
16056 @code{GL_RGBA} nor @code{GL_BGRA}.
16058 @code{GL_INVALID_OPERATION} is generated if @var{format} is
16059 @code{GL_DEPTH_COMPONENT} and @var{internalFormat} is not
16060 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
16061 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}.
16063 @code{GL_INVALID_OPERATION} is generated if @var{internalFormat} is
16064 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
16065 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}, and
16066 @var{format} is not @code{GL_DEPTH_COMPONENT}.
16068 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
16069 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
16070 object's data store is currently mapped.
16072 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
16073 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
16074 would be unpacked from the buffer object such that the memory reads
16075 required would exceed the data store size.
16077 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
16078 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
16079 is not evenly divisible into the number of bytes needed to store in
16080 memory a datum indicated by @var{type}.
16082 @code{GL_INVALID_OPERATION} is generated if @code{glTexImage1D} is
16083 executed between the execution of @code{glBegin} and the corresponding
16084 execution of @code{glEnd}.
16088 @deftypefun void glTexImage2D target level internalFormat width height border format type data
16089 Specify a two-dimensional texture image.
16093 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
16094 @code{GL_PROXY_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
16095 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
16096 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
16097 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
16098 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z},
16099 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or
16100 @code{GL_PROXY_TEXTURE_CUBE_MAP}.
16103 Specifies the level-of-detail number. Level 0 is the base image level.
16104 Level @var{n} is the @var{n}th mipmap reduction image.
16106 @item @var{internalFormat}
16107 Specifies the number of color components in the texture. Must be 1, 2,
16108 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA},
16109 @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
16110 @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA},
16111 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
16112 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
16113 @code{GL_COMPRESSED_RGBA}, @code{GL_DEPTH_COMPONENT},
16114 @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24},
16115 @code{GL_DEPTH_COMPONENT32}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
16116 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
16117 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
16118 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
16119 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
16120 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY},
16121 @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12},
16122 @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
16123 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
16124 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
16125 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
16126 @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE},
16127 @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
16128 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
16129 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
16132 Specifies the width of the texture image including the border if any. If
16133 the GL version does not support non-power-of-two sizes, this value must
16134 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
16135 implementations support texture images that are at least 64 texels wide.
16138 Specifies the height of the texture image including the border if any.
16139 If the GL version does not support non-power-of-two sizes, this value
16140 must be @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}.
16141 All implementations support texture images that are at least 64 texels
16145 Specifies the width of the border. Must be either 0 or 1.
16148 Specifies the format of the pixel data. The following symbolic values
16149 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
16150 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
16151 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
16152 @code{GL_LUMINANCE_ALPHA}.
16155 Specifies the data type of the pixel data. The following symbolic values
16156 are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
16157 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
16158 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
16159 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
16160 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
16161 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
16162 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
16163 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
16164 and @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
16167 Specifies a pointer to the image data in memory.
16171 Texturing maps a portion of a specified texture image onto each
16172 graphical primitive for which texturing is enabled. To enable and
16173 disable two-dimensional texturing, call @code{glEnable} and
16174 @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and
16175 disable texturing using cube-mapped texture, call @code{glEnable} and
16176 @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}.
16178 To define texture images, call @code{glTexImage2D}. The arguments
16179 describe the parameters of the texture image, such as height, width,
16180 width of the border, level-of-detail number (see @code{glTexParameter}),
16181 and number of color components provided. The last three arguments
16182 describe how the image is represented in memory; they are identical to
16183 the pixel formats used for @code{glDrawPixels}.
16185 If @var{target} is @code{GL_PROXY_TEXTURE_2D} or
16186 @code{GL_PROXY_TEXTURE_CUBE_MAP}, no data is read from @var{data}, but
16187 all of the texture image state is recalculated, checked for consistency,
16188 and checked against the implementation's capabilities. If the
16189 implementation cannot handle a texture of the requested texture size, it
16190 sets all of the image state to 0, but does not generate an error (see
16191 @code{glGetError}). To query for an entire mipmap array, use an image
16192 array level greater than or equal to 1.
16194 If @var{target} is @code{GL_TEXTURE_2D}, or one of the
16195 @code{GL_TEXTURE_CUBE_MAP} targets, data is read from @var{data} as a
16196 sequence of signed or unsigned bytes, shorts, or longs, or
16197 single-precision floating-point values, depending on @var{type}. These
16198 values are grouped into sets of one, two, three, or four values,
16199 depending on @var{format}, to form elements. If @var{type} is
16200 @code{GL_BITMAP}, the data is considered as a string of unsigned bytes
16201 (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is
16202 treated as eight 1-bit elements, with bit ordering determined by
16203 @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}).
16205 If a non-zero named buffer object is bound to the
16206 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
16207 texture image is specified, @var{data} is treated as a byte offset into
16208 the buffer object's data store.
16210 The first element corresponds to the lower left corner of the texture
16211 image. Subsequent elements progress left-to-right through the remaining
16212 texels in the lowest row of the texture image, and then in successively
16213 higher rows of the texture image. The final element corresponds to the
16214 upper right corner of the texture image.
16216 @var{format} determines the composition of each element in @var{data}.
16217 It can assume one of these symbolic values:
16220 @item @code{GL_COLOR_INDEX}
16221 Each element is a single value, a color index. The GL converts it to
16222 fixed point (with an unspecified number of zero bits to the right of the
16223 binary point), shifted left or right depending on the value and sign of
16224 @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see
16225 @code{glPixelTransfer}). The resulting index is converted to a set of
16226 color components using the @code{GL_PIXEL_MAP_I_TO_R},
16227 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
16228 @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1].
16230 @item @code{GL_RED}
16231 Each element is a single red component. The GL converts it to floating
16232 point and assembles it into an RGBA element by attaching 0 for green and
16233 blue, and 1 for alpha. Each component is then multiplied by the signed
16234 scale factor @code{GL_c_SCALE}, added to the signed bias
16235 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
16236 @code{glPixelTransfer}).
16238 @item @code{GL_GREEN}
16239 Each element is a single green component. The GL converts it to floating
16240 point and assembles it into an RGBA element by attaching 0 for red and
16241 blue, and 1 for alpha. Each component is then multiplied by the signed
16242 scale factor @code{GL_c_SCALE}, added to the signed bias
16243 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
16244 @code{glPixelTransfer}).
16246 @item @code{GL_BLUE}
16247 Each element is a single blue component. The GL converts it to floating
16248 point and assembles it into an RGBA element by attaching 0 for red and
16249 green, and 1 for alpha. Each component is then multiplied by the signed
16250 scale factor @code{GL_c_SCALE}, added to the signed bias
16251 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
16252 @code{glPixelTransfer}).
16254 @item @code{GL_ALPHA}
16255 Each element is a single alpha component. The GL converts it to floating
16256 point and assembles it into an RGBA element by attaching 0 for red,
16257 green, and blue. Each component is then multiplied by the signed scale
16258 factor @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
16259 clamped to the range [0,1] (see @code{glPixelTransfer}).
16261 @item @code{GL_INTENSITY}
16262 Each element is a single intensity value. The GL converts it to floating
16263 point, then assembles it into an RGBA element by replicating the
16264 intensity value three times for red, green, blue, and alpha. Each
16265 component is then multiplied by the signed scale factor
16266 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
16267 clamped to the range [0,1] (see @code{glPixelTransfer}).
16269 @item @code{GL_RGB}
16270 @item @code{GL_BGR}
16271 Each element is an RGB triple. The GL converts it to floating point and
16272 assembles it into an RGBA element by attaching 1 for alpha. Each
16273 component is then multiplied by the signed scale factor
16274 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
16275 clamped to the range [0,1] (see @code{glPixelTransfer}).
16277 @item @code{GL_RGBA}
16278 @item @code{GL_BGRA}
16279 Each element contains all four components. Each component is multiplied
16280 by the signed scale factor @code{GL_c_SCALE}, added to the signed bias
16281 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
16282 @code{glPixelTransfer}).
16284 @item @code{GL_LUMINANCE}
16285 Each element is a single luminance value. The GL converts it to floating
16286 point, then assembles it into an RGBA element by replicating the
16287 luminance value three times for red, green, and blue and attaching 1 for
16288 alpha. Each component is then multiplied by the signed scale factor
16289 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
16290 clamped to the range [0,1] (see @code{glPixelTransfer}).
16292 @item @code{GL_LUMINANCE_ALPHA}
16293 Each element is a luminance/alpha pair. The GL converts it to floating
16294 point, then assembles it into an RGBA element by replicating the
16295 luminance value three times for red, green, and blue. Each component is
16296 then multiplied by the signed scale factor @code{GL_c_SCALE}, added to
16297 the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see
16298 @code{glPixelTransfer}).
16300 @item @code{GL_DEPTH_COMPONENT}
16301 Each element is a single depth value. The GL converts it to floating
16302 point, multiplies by the signed scale factor @code{GL_DEPTH_SCALE}, adds
16303 the signed bias @code{GL_DEPTH_BIAS}, and clamps to the range [0,1] (see
16304 @code{glPixelTransfer}).
16308 Refer to the @code{glDrawPixels} reference page for a description of the
16309 acceptable values for the @var{type} parameter.
16311 If an application wants to store the texture at a certain resolution or
16312 in a certain format, it can request the resolution and format with
16313 @var{internalFormat}. The GL will choose an internal representation that
16314 closely approximates that requested by @var{internalFormat}, but it may
16315 not match exactly. (The representations specified by
16316 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and
16317 @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 may
16318 also be used to specify the above representations.)
16320 If the @var{internalFormat} parameter is one of the generic compressed
16321 formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
16322 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
16323 @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will
16324 replace the internal format with the symbolic constant for a specific
16325 internal format and compress the texture before storage. If no
16326 corresponding internal format is available, or the GL can not compress
16327 that image for any reason, the internal format is instead replaced with
16328 a corresponding base internal format.
16330 If the @var{internalFormat} parameter is @code{GL_SRGB},
16331 @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8},
16332 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
16333 or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red,
16334 green, blue, or luminance components are encoded in the sRGB color
16335 space. Any alpha component is left unchanged. The conversion from the
16336 sRGB encoded component @r{@var{c}_@var{s}} to a linear component
16337 @r{@var{c}_@var{l}} is:
16339 @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045),
16340 ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)}
16342 Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1].
16344 Use the @code{GL_PROXY_TEXTURE_2D} or @code{GL_PROXY_TEXTURE_CUBE_MAP}
16345 target to try out a resolution and format. The implementation will
16346 update and recompute its best match for the requested storage resolution
16347 and format. To then query this state, call
16348 @code{glGetTexLevelParameter}. If the texture cannot be accommodated,
16349 texture state is set to 0.
16351 A one-component texture image uses only the red component of the RGBA
16352 color extracted from @var{data}. A two-component image uses the R and A
16353 values. A three-component image uses the R, G, and B values. A
16354 four-component image uses all of the RGBA components.
16356 Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA textures
16357 during texture filtering and application. Image-based shadowing can be
16358 enabled by comparing texture r coordinates to depth texture values to
16359 generate a boolean result. See @code{glTexParameter} for details on
16360 texture comparison.
16362 @code{GL_INVALID_ENUM} is generated if @var{target} is not
16363 @code{GL_TEXTURE_2D}, @code{GL_PROXY_TEXTURE_2D},
16364 @code{GL_PROXY_TEXTURE_CUBE_MAP}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
16365 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
16366 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
16367 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
16368 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
16369 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
16371 @code{GL_INVALID_ENUM} is generated if @var{target} is one of the six
16372 cube map 2D image targets and the width and height parameters are not
16375 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
16378 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
16379 and @var{format} is not @code{GL_COLOR_INDEX}.
16381 @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is
16382 less than 0 or greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
16384 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
16386 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
16387 @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of
16388 @code{GL_MAX_TEXTURE_SIZE}.
16390 @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1,
16391 2, 3, 4, or one of the accepted resolution and format symbolic
16394 @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is
16395 less than 0 or greater than 2 + @code{GL_MAX_TEXTURE_SIZE}.
16397 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
16398 not supported and the @var{width} or @var{height} cannot be represented
16399 as @r{2^@var{k}+2(@var{border},)} for some integer value of @var{k}.
16401 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
16403 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
16404 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
16405 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
16406 and @var{format} is not @code{GL_RGB}.
16408 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
16409 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
16410 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
16411 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
16412 @code{GL_UNSIGNED_INT_10_10_10_2}, or
16413 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
16414 @code{GL_RGBA} nor @code{GL_BGRA}.
16416 @code{GL_INVALID_OPERATION} is generated if @var{target} is not
16417 @code{GL_TEXTURE_2D} or @code{GL_PROXY_TEXTURE_2D} and
16418 @var{internalFormat} is @code{GL_DEPTH_COMPONENT},
16419 @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, or
16420 @code{GL_DEPTH_COMPONENT32}.
16422 @code{GL_INVALID_OPERATION} is generated if @var{format} is
16423 @code{GL_DEPTH_COMPONENT} and @var{internalFormat} is not
16424 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
16425 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}.
16427 @code{GL_INVALID_OPERATION} is generated if @var{internalFormat} is
16428 @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16},
16429 @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}, and
16430 @var{format} is not @code{GL_DEPTH_COMPONENT}.
16432 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
16433 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
16434 object's data store is currently mapped.
16436 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
16437 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
16438 would be unpacked from the buffer object such that the memory reads
16439 required would exceed the data store size.
16441 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
16442 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
16443 is not evenly divisible into the number of bytes needed to store in
16444 memory a datum indicated by @var{type}.
16446 @code{GL_INVALID_OPERATION} is generated if @code{glTexImage2D} is
16447 executed between the execution of @code{glBegin} and the corresponding
16448 execution of @code{glEnd}.
16452 @deftypefun void glTexImage3D target level internalFormat width height depth border format type data
16453 Specify a three-dimensional texture image.
16457 Specifies the target texture. Must be @code{GL_TEXTURE_3D} or
16458 @code{GL_PROXY_TEXTURE_3D}.
16461 Specifies the level-of-detail number. Level 0 is the base image level.
16462 Level @r{@var{n}} is the @r{@var{n}^@var{th}} mipmap reduction image.
16464 @item @var{internalFormat}
16465 Specifies the number of color components in the texture. Must be 1, 2,
16466 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA},
16467 @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12},
16468 @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA},
16469 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
16470 @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB},
16471 @code{GL_COMPRESSED_RGBA}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4},
16472 @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16},
16473 @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4},
16474 @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8},
16475 @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12},
16476 @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY},
16477 @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12},
16478 @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB},
16479 @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10},
16480 @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2},
16481 @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2},
16482 @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE},
16483 @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
16484 @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8},
16485 @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}.
16488 Specifies the width of the texture image including the border if any. If
16489 the GL version does not support non-power-of-two sizes, this value must
16490 be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All
16491 implementations support 3D texture images that are at least 16 texels
16495 Specifies the height of the texture image including the border if any.
16496 If the GL version does not support non-power-of-two sizes, this value
16497 must be @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}.
16498 All implementations support 3D texture images that are at least 16
16502 Specifies the depth of the texture image including the border if any. If
16503 the GL version does not support non-power-of-two sizes, this value must
16504 be @r{2^@var{k}+2(@var{border},)} for some integer @r{@var{k}}. All
16505 implementations support 3D texture images that are at least 16 texels
16509 Specifies the width of the border. Must be either 0 or 1.
16512 Specifies the format of the pixel data. The following symbolic values
16513 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
16514 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
16515 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
16516 @code{GL_LUMINANCE_ALPHA}.
16519 Specifies the data type of the pixel data. The following symbolic values
16520 are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
16521 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
16522 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
16523 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
16524 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
16525 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
16526 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
16527 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
16528 and @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
16531 Specifies a pointer to the image data in memory.
16535 Texturing maps a portion of a specified texture image onto each
16536 graphical primitive for which texturing is enabled. To enable and
16537 disable three-dimensional texturing, call @code{glEnable} and
16538 @code{glDisable} with argument @code{GL_TEXTURE_3D}.
16540 To define texture images, call @code{glTexImage3D}. The arguments
16541 describe the parameters of the texture image, such as height, width,
16542 depth, width of the border, level-of-detail number (see
16543 @code{glTexParameter}), and number of color components provided. The
16544 last three arguments describe how the image is represented in memory;
16545 they are identical to the pixel formats used for @code{glDrawPixels}.
16547 If @var{target} is @code{GL_PROXY_TEXTURE_3D}, no data is read from
16548 @var{data}, but all of the texture image state is recalculated, checked
16549 for consistency, and checked against the implementation's capabilities.
16550 If the implementation cannot handle a texture of the requested texture
16551 size, it sets all of the image state to 0, but does not generate an
16552 error (see @code{glGetError}). To query for an entire mipmap array, use
16553 an image array level greater than or equal to 1.
16555 If @var{target} is @code{GL_TEXTURE_3D}, data is read from @var{data} as
16556 a sequence of signed or unsigned bytes, shorts, or longs, or
16557 single-precision floating-point values, depending on @var{type}. These
16558 values are grouped into sets of one, two, three, or four values,
16559 depending on @var{format}, to form elements. If @var{type} is
16560 @code{GL_BITMAP}, the data is considered as a string of unsigned bytes
16561 (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is
16562 treated as eight 1-bit elements, with bit ordering determined by
16563 @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}).
16565 If a non-zero named buffer object is bound to the
16566 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
16567 texture image is specified, @var{data} is treated as a byte offset into
16568 the buffer object's data store.
16570 The first element corresponds to the lower left corner of the texture
16571 image. Subsequent elements progress left-to-right through the remaining
16572 texels in the lowest row of the texture image, and then in successively
16573 higher rows of the texture image. The final element corresponds to the
16574 upper right corner of the texture image.
16576 @var{format} determines the composition of each element in @var{data}.
16577 It can assume one of these symbolic values:
16580 @item @code{GL_COLOR_INDEX}
16581 Each element is a single value, a color index. The GL converts it to
16582 fixed point (with an unspecified number of zero bits to the right of the
16583 binary point), shifted left or right depending on the value and sign of
16584 @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see
16585 @code{glPixelTransfer}). The resulting index is converted to a set of
16586 color components using the @code{GL_PIXEL_MAP_I_TO_R},
16587 @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and
16588 @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1].
16590 @item @code{GL_RED}
16591 Each element is a single red component. The GL converts it to floating
16592 point and assembles it into an RGBA element by attaching 0 for green and
16593 blue, and 1 for alpha. Each component is then multiplied by the signed
16594 scale factor @code{GL_c_SCALE}, added to the signed bias
16595 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
16596 @code{glPixelTransfer}).
16598 @item @code{GL_GREEN}
16599 Each element is a single green component. The GL converts it to floating
16600 point and assembles it into an RGBA element by attaching 0 for red and
16601 blue, and 1 for alpha. Each component is then multiplied by the signed
16602 scale factor @code{GL_c_SCALE}, added to the signed bias
16603 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
16604 @code{glPixelTransfer}).
16606 @item @code{GL_BLUE}
16607 Each element is a single blue component. The GL converts it to floating
16608 point and assembles it into an RGBA element by attaching 0 for red and
16609 green, and 1 for alpha. Each component is then multiplied by the signed
16610 scale factor @code{GL_c_SCALE}, added to the signed bias
16611 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
16612 @code{glPixelTransfer}).
16614 @item @code{GL_ALPHA}
16615 Each element is a single alpha component. The GL converts it to floating
16616 point and assembles it into an RGBA element by attaching 0 for red,
16617 green, and blue. Each component is then multiplied by the signed scale
16618 factor @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
16619 clamped to the range [0,1] (see @code{glPixelTransfer}).
16621 @item @code{GL_INTENSITY}
16622 Each element is a single intensity value. The GL converts it to floating
16623 point, then assembles it into an RGBA element by replicating the
16624 intensity value three times for red, green, blue, and alpha. Each
16625 component is then multiplied by the signed scale factor
16626 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
16627 clamped to the range [0,1] (see @code{glPixelTransfer}).
16629 @item @code{GL_RGB}
16630 @item @code{GL_BGR}
16631 Each element is an RGB triple. The GL converts it to floating point and
16632 assembles it into an RGBA element by attaching 1 for alpha. Each
16633 component is then multiplied by the signed scale factor
16634 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
16635 clamped to the range [0,1] (see @code{glPixelTransfer}).
16637 @item @code{GL_RGBA}
16638 @item @code{GL_BGRA}
16639 Each element contains all four components. Each component is multiplied
16640 by the signed scale factor @code{GL_c_SCALE}, added to the signed bias
16641 @code{GL_c_BIAS}, and clamped to the range [0,1] (see
16642 @code{glPixelTransfer}).
16644 @item @code{GL_LUMINANCE}
16645 Each element is a single luminance value. The GL converts it to floating
16646 point, then assembles it into an RGBA element by replicating the
16647 luminance value three times for red, green, and blue and attaching 1 for
16648 alpha. Each component is then multiplied by the signed scale factor
16649 @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and
16650 clamped to the range [0,1] (see @code{glPixelTransfer}).
16652 @item @code{GL_LUMINANCE_ALPHA}
16653 Each element is a luminance/alpha pair. The GL converts it to floating
16654 point, then assembles it into an RGBA element by replicating the
16655 luminance value three times for red, green, and blue. Each component is
16656 then multiplied by the signed scale factor @code{GL_c_SCALE}, added to
16657 the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see
16658 @code{glPixelTransfer}).
16662 Refer to the @code{glDrawPixels} reference page for a description of the
16663 acceptable values for the @var{type} parameter.
16665 If an application wants to store the texture at a certain resolution or
16666 in a certain format, it can request the resolution and format with
16667 @var{internalFormat}. The GL will choose an internal representation that
16668 closely approximates that requested by @var{internalFormat}, but it may
16669 not match exactly. (The representations specified by
16670 @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and
16671 @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 may
16672 also be used to specify the above representations.)
16674 If the @var{internalFormat} parameter is one of the generic compressed
16675 formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY},
16676 @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA},
16677 @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will
16678 replace the internal format with the symbolic constant for a specific
16679 internal format and compress the texture before storage. If no
16680 corresponding internal format is available, or the GL can not compress
16681 that image for any reason, the internal format is instead replaced with
16682 a corresponding base internal format.
16684 If the @var{internalFormat} parameter is @code{GL_SRGB},
16685 @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8},
16686 @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA},
16687 or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red,
16688 green, blue, or luminance components are encoded in the sRGB color
16689 space. Any alpha component is left unchanged. The conversion from the
16690 sRGB encoded component @r{@var{c}_@var{s}} to a linear component
16691 @r{@var{c}_@var{l}} is:
16693 @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045),
16694 ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)}
16696 Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1].
16698 Use the @code{GL_PROXY_TEXTURE_3D} target to try out a resolution and
16699 format. The implementation will update and recompute its best match for
16700 the requested storage resolution and format. To then query this state,
16701 call @code{glGetTexLevelParameter}. If the texture cannot be
16702 accommodated, texture state is set to 0.
16704 A one-component texture image uses only the red component of the RGBA
16705 color extracted from @var{data}. A two-component image uses the R and A
16706 values. A three-component image uses the R, G, and B values. A
16707 four-component image uses all of the RGBA components.
16709 @code{GL_INVALID_ENUM} is generated if @var{target} is not
16710 @code{GL_TEXTURE_3D} or @code{GL_PROXY_TEXTURE_3D}.
16712 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
16713 format constant. Format constants other than @code{GL_STENCIL_INDEX} and
16714 @code{GL_DEPTH_COMPONENT} are accepted.
16716 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
16719 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
16720 and @var{format} is not @code{GL_COLOR_INDEX}.
16722 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
16724 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
16725 @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of
16726 @code{GL_MAX_TEXTURE_SIZE}.
16728 @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1,
16729 2, 3, 4, or one of the accepted resolution and format symbolic
16732 @code{GL_INVALID_VALUE} is generated if @var{width}, @var{height}, or
16733 @var{depth} is less than 0 or greater than 2 +
16734 @code{GL_MAX_TEXTURE_SIZE}.
16736 @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are
16737 not supported and the @var{width}, @var{height}, or @var{depth} cannot
16738 be represented as @r{2^@var{k}+2(@var{border},)} for some integer value
16741 @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1.
16743 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
16744 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
16745 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
16746 and @var{format} is not @code{GL_RGB}.
16748 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
16749 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
16750 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
16751 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
16752 @code{GL_UNSIGNED_INT_10_10_10_2}, or
16753 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
16754 @code{GL_RGBA} nor @code{GL_BGRA}.
16756 @code{GL_INVALID_OPERATION} is generated if @var{format} or
16757 @var{internalFormat} is @code{GL_DEPTH_COMPONENT},
16758 @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, or
16759 @code{GL_DEPTH_COMPONENT32}.
16761 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
16762 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
16763 object's data store is currently mapped.
16765 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
16766 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
16767 would be unpacked from the buffer object such that the memory reads
16768 required would exceed the data store size.
16770 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
16771 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
16772 is not evenly divisible into the number of bytes needed to store in
16773 memory a datum indicated by @var{type}.
16775 @code{GL_INVALID_OPERATION} is generated if @code{glTexImage3D} is
16776 executed between the execution of @code{glBegin} and the corresponding
16777 execution of @code{glEnd}.
16781 @deftypefun void glTexParameterf target pname param
16782 @deftypefunx void glTexParameteri target pname param
16783 Set texture parameters.
16787 Specifies the target texture, which must be either @code{GL_TEXTURE_1D},
16788 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, or
16789 @code{GL_TEXTURE_CUBE_MAP}.
16792 Specifies the symbolic name of a single-valued texture parameter.
16793 @var{pname} can be one of the following: @code{GL_TEXTURE_MIN_FILTER},
16794 @code{GL_TEXTURE_MAG_FILTER}, @code{GL_TEXTURE_MIN_LOD},
16795 @code{GL_TEXTURE_MAX_LOD}, @code{GL_TEXTURE_BASE_LEVEL},
16796 @code{GL_TEXTURE_MAX_LEVEL}, @code{GL_TEXTURE_WRAP_S},
16797 @code{GL_TEXTURE_WRAP_T}, @code{GL_TEXTURE_WRAP_R},
16798 @code{GL_TEXTURE_PRIORITY}, @code{GL_TEXTURE_COMPARE_MODE},
16799 @code{GL_TEXTURE_COMPARE_FUNC}, @code{GL_DEPTH_TEXTURE_MODE}, or
16800 @code{GL_GENERATE_MIPMAP}.
16803 Specifies the value of @var{pname}.
16807 Texture mapping is a technique that applies an image onto an object's
16808 surface as if the image were a decal or cellophane shrink-wrap. The
16809 image is created in texture space, with an (@r{@var{s}}, @r{@var{t}})
16810 coordinate system. A texture is a one- or two-dimensional image and a
16811 set of parameters that determine how samples are derived from the image.
16813 @code{glTexParameter} assigns the value or values in @var{params} to the
16814 texture parameter specified as @var{pname}. @var{target} defines the
16815 target texture, either @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, or
16816 @code{GL_TEXTURE_3D}. The following symbols are accepted in @var{pname}:
16819 @item @code{GL_TEXTURE_MIN_FILTER}
16820 The texture minifying function is used whenever the pixel being textured
16821 maps to an area greater than one texture element. There are six defined
16822 minifying functions. Two of them use the nearest one or nearest four
16823 texture elements to compute the texture value. The other four use
16826 A mipmap is an ordered set of arrays representing the same image at
16827 progressively lower resolutions. If the texture has dimensions
16828 @r{2^@var{n}×2^@var{m}}, there are @r{@var{max}(@var{n},@var{m})+1}
16829 mipmaps. The first mipmap is the original texture, with dimensions
16830 @r{2^@var{n}×2^@var{m}}. Each subsequent mipmap has dimensions
16831 @r{2^@var{k}-1,×2^@var{l}-1,}, where @r{2^@var{k}×2^@var{l}} are the
16832 dimensions of the previous mipmap, until either @r{@var{k}=0} or
16833 @r{@var{l}=0}. At that point, subsequent mipmaps have dimension
16834 @r{1×2^@var{l}-1,} or @r{2^@var{k}-1,×1} until the final mipmap, which
16835 has dimension @r{1×1}. To define the mipmaps, call @code{glTexImage1D},
16836 @code{glTexImage2D}, @code{glTexImage3D}, @code{glCopyTexImage1D}, or
16837 @code{glCopyTexImage2D} with the @var{level} argument indicating the
16838 order of the mipmaps. Level 0 is the original texture; level
16839 @r{@var{max}(@var{n},@var{m})} is the final @r{1×1} mipmap.
16841 @var{params} supplies a function for minifying the texture as one of the
16844 As more texture elements are sampled in the minification process, fewer
16845 aliasing artifacts will be apparent. While the @code{GL_NEAREST} and
16846 @code{GL_LINEAR} minification functions can be faster than the other
16847 four, they sample only one or four texture elements to determine the
16848 texture value of the pixel being rendered and can produce moire patterns
16849 or ragged transitions. The initial value of @code{GL_TEXTURE_MIN_FILTER}
16850 is @code{GL_NEAREST_MIPMAP_LINEAR}.
16852 @item @code{GL_TEXTURE_MAG_FILTER}
16853 The texture magnification function is used when the pixel being textured
16854 maps to an area less than or equal to one texture element. It sets the
16855 texture magnification function to either @code{GL_NEAREST} or
16856 @code{GL_LINEAR} (see below). @code{GL_NEAREST} is generally faster than
16857 @code{GL_LINEAR}, but it can produce textured images with sharper edges
16858 because the transition between texture elements is not as smooth. The
16859 initial value of @code{GL_TEXTURE_MAG_FILTER} is @code{GL_LINEAR}.
16864 @item @code{GL_NEAREST}
16865 Returns the value of the texture element that is nearest (in Manhattan
16866 distance) to the center of the pixel being textured.
16868 @item @code{GL_LINEAR}
16869 Returns the weighted average of the four texture elements that are
16870 closest to the center of the pixel being textured. These can include
16871 border texture elements, depending on the values of
16872 @code{GL_TEXTURE_WRAP_S} and @code{GL_TEXTURE_WRAP_T}, and on the exact
16875 @item @code{GL_NEAREST_MIPMAP_NEAREST}
16876 Chooses the mipmap that most closely matches the size of the pixel being
16877 textured and uses the @code{GL_NEAREST} criterion (the texture element
16878 nearest to the center of the pixel) to produce a texture value.
16880 @item @code{GL_LINEAR_MIPMAP_NEAREST}
16881 Chooses the mipmap that most closely matches the size of the pixel being
16882 textured and uses the @code{GL_LINEAR} criterion (a weighted average of
16883 the four texture elements that are closest to the center of the pixel)
16884 to produce a texture value.
16886 @item @code{GL_NEAREST_MIPMAP_LINEAR}
16887 Chooses the two mipmaps that most closely match the size of the pixel
16888 being textured and uses the @code{GL_NEAREST} criterion (the texture
16889 element nearest to the center of the pixel) to produce a texture value
16890 from each mipmap. The final texture value is a weighted average of those
16893 @item @code{GL_LINEAR_MIPMAP_LINEAR}
16894 Chooses the two mipmaps that most closely match the size of the pixel
16895 being textured and uses the @code{GL_LINEAR} criterion (a weighted
16896 average of the four texture elements that are closest to the center of
16897 the pixel) to produce a texture value from each mipmap. The final
16898 texture value is a weighted average of those two values.
16903 @item @code{GL_NEAREST}
16904 Returns the value of the texture element that is nearest (in Manhattan
16905 distance) to the center of the pixel being textured.
16907 @item @code{GL_LINEAR}
16908 Returns the weighted average of the four texture elements that are
16909 closest to the center of the pixel being textured. These can include
16910 border texture elements, depending on the values of
16911 @code{GL_TEXTURE_WRAP_S} and @code{GL_TEXTURE_WRAP_T}, and on the exact
16919 @item @code{GL_TEXTURE_MIN_LOD}
16920 Sets the minimum level-of-detail parameter. This floating-point value
16921 limits the selection of highest resolution mipmap (lowest mipmap level).
16922 The initial value is -1000.
16929 @item @code{GL_TEXTURE_MAX_LOD}
16930 Sets the maximum level-of-detail parameter. This floating-point value
16931 limits the selection of the lowest resolution mipmap (highest mipmap
16932 level). The initial value is 1000.
16939 @item @code{GL_TEXTURE_BASE_LEVEL}
16940 Specifies the index of the lowest defined mipmap level. This is an
16941 integer value. The initial value is 0.
16948 @item @code{GL_TEXTURE_MAX_LEVEL}
16949 Sets the index of the highest defined mipmap level. This is an integer
16950 value. The initial value is 1000.
16957 @item @code{GL_TEXTURE_WRAP_S}
16958 Sets the wrap parameter for texture coordinate @r{@var{s}} to either
16959 @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE},
16960 @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. @code{GL_CLAMP} causes
16961 @r{@var{s}} coordinates to be clamped to the range [0,1] and is useful
16962 for preventing wrapping artifacts when mapping a single image onto an
16963 object. @code{GL_CLAMP_TO_BORDER} causes the @r{@var{s}} coordinate to
16964 be clamped to the range @r{[-1/2@var{N},,1+1/2@var{N},]}, where
16965 @r{@var{N}} is the size of the texture in the direction of
16966 clamping.@code{GL_CLAMP_TO_EDGE} causes @r{@var{s}} coordinates to be
16967 clamped to the range @r{[1/2@var{N},,1-1/2@var{N},]}, where @r{@var{N}}
16968 is the size of the texture in the direction of clamping.
16969 @code{GL_REPEAT} causes the integer part of the @r{@var{s}} coordinate
16970 to be ignored; the GL uses only the fractional part, thereby creating a
16971 repeating pattern. @code{GL_MIRRORED_REPEAT} causes the @r{@var{s}}
16972 coordinate to be set to the fractional part of the texture coordinate if
16973 the integer part of @r{@var{s}} is even; if the integer part of
16974 @r{@var{s}} is odd, then the @r{@var{s}} texture coordinate is set to
16975 @r{1-@var{frac}(@var{s},)}, where @r{@var{frac}(@var{s},)} represents
16976 the fractional part of @r{@var{s}}. Border texture elements are accessed
16977 only if wrapping is set to @code{GL_CLAMP} or @code{GL_CLAMP_TO_BORDER}.
16978 Initially, @code{GL_TEXTURE_WRAP_S} is set to @code{GL_REPEAT}.
16985 @item @code{GL_TEXTURE_WRAP_T}
16986 Sets the wrap parameter for texture coordinate @r{@var{t}} to either
16987 @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE},
16988 @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. See the discussion under
16989 @code{GL_TEXTURE_WRAP_S}. Initially, @code{GL_TEXTURE_WRAP_T} is set to
16992 @item @code{GL_TEXTURE_WRAP_R}
16993 Sets the wrap parameter for texture coordinate @r{@var{r}} to either
16994 @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE},
16995 @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. See the discussion under
16996 @code{GL_TEXTURE_WRAP_S}. Initially, @code{GL_TEXTURE_WRAP_R} is set to
16999 @item @code{GL_TEXTURE_BORDER_COLOR}
17000 Sets a border color. @var{params} contains four values that comprise the
17001 RGBA color of the texture border. Integer color components are
17002 interpreted linearly such that the most positive integer maps to 1.0,
17003 and the most negative integer maps to -1.0. The values are clamped to
17004 the range [0,1] when they are specified. Initially, the border color is
17007 @item @code{GL_TEXTURE_PRIORITY}
17008 Specifies the texture residence priority of the currently bound texture.
17009 Permissible values are in the range @r{[0,1]}. See
17010 @code{glPrioritizeTextures} and @code{glBindTexture} for more
17013 @item @code{GL_TEXTURE_COMPARE_MODE}
17014 Specifies the texture comparison mode for currently bound depth
17015 textures. That is, a texture whose internal format is
17016 @code{GL_DEPTH_COMPONENT_*}; see @code{glTexImage2D}) Permissible values
17019 @item @code{GL_TEXTURE_COMPARE_FUNC}
17020 Specifies the comparison operator used when
17021 @code{GL_TEXTURE_COMPARE_MODE} is set to @code{GL_COMPARE_R_TO_TEXTURE}.
17022 Permissible values are: where @r{@var{r}} is the current interpolated
17023 texture coordinate, and @r{@var{D}_@var{t}} is the depth texture value
17024 sampled from the currently bound depth texture. @r{@var{result}} is
17025 assigned to the either the luminance, intensity, or alpha (as specified
17026 by @code{GL_DEPTH_TEXTURE_MODE}.)
17028 @item @code{GL_DEPTH_TEXTURE_MODE}
17029 Specifies a single symbolic constant indicating how depth values should
17030 be treated during filtering and texture application. Accepted values are
17031 @code{GL_LUMINANCE}, @code{GL_INTENSITY}, and @code{GL_ALPHA}. The
17032 initial value is @code{GL_LUMINANCE}.
17034 @item @code{GL_GENERATE_MIPMAP}
17035 Specifies a boolean value that indicates if all levels of a mipmap array
17036 should be automatically updated when any modification to the base level
17037 mipmap is done. The initial value is @code{GL_FALSE}.
17042 @item @code{GL_COMPARE_R_TO_TEXTURE}
17043 Specifies that the interpolated and clamped @r{@var{r}} texture
17044 coordinate should be compared to the value in the currently bound depth
17045 texture. See the discussion of @code{GL_TEXTURE_COMPARE_FUNC} for
17046 details of how the comparison is evaluated. The result of the comparison
17047 is assigned to luminance, intensity, or alpha (as specified by
17048 @code{GL_DEPTH_TEXTURE_MODE}).
17050 @item @code{GL_NONE}
17051 Specifies that the luminance, intensity, or alpha (as specified by
17052 @code{GL_DEPTH_TEXTURE_MODE}) should be assigned the appropriate value
17053 from the currently bound depth texture.
17058 @item @strong{Texture Comparison Function}
17059 @strong{Computed result}
17061 @item @code{GL_LEQUAL}
17062 @r{@var{result}=@{(1.0), (0.0) (@var{r}<=@var{D}_@var{t},),
17063 (@var{r}>@var{D}_@var{t},),}
17065 @item @code{GL_GEQUAL}
17066 @r{@var{result}=@{(1.0), (0.0) (@var{r}>=@var{D}_@var{t},),
17067 (@var{r}<@var{D}_@var{t},),}
17069 @item @code{GL_LESS}
17070 @r{@var{result}=@{(1.0), (0.0) (@var{r}<@var{D}_@var{t},),
17071 (@var{r}>=@var{D}_@var{t},),}
17073 @item @code{GL_GREATER}
17074 @r{@var{result}=@{(1.0), (0.0) (@var{r}>@var{D}_@var{t},),
17075 (@var{r}<=@var{D}_@var{t},),}
17077 @item @code{GL_EQUAL}
17078 @r{@var{result}=@{(1.0), (0.0) (@var{r}=@var{D}_@var{t},),
17079 (@var{r}≠@var{D}_@var{t},),}
17081 @item @code{GL_NOTEQUAL}
17082 @r{@var{result}=@{(1.0), (0.0) (@var{r}≠@var{D}_@var{t},),
17083 (@var{r}=@var{D}_@var{t},),}
17085 @item @code{GL_ALWAYS}
17086 @r{@var{result}=@code{1.0}}
17088 @item @code{GL_NEVER}
17089 @r{@var{result}=@code{0.0}}
17093 @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is
17094 not one of the accepted defined values.
17096 @code{GL_INVALID_ENUM} is generated if @var{params} should have a
17097 defined constant value (based on the value of @var{pname}) and does not.
17099 @code{GL_INVALID_OPERATION} is generated if @code{glTexParameter} is
17100 executed between the execution of @code{glBegin} and the corresponding
17101 execution of @code{glEnd}.
17105 @deftypefun void glTexSubImage1D target level xoffset width format type data
17106 Specify a one-dimensional texture subimage.
17110 Specifies the target texture. Must be @code{GL_TEXTURE_1D}.
17113 Specifies the level-of-detail number. Level 0 is the base image level.
17114 Level @var{n} is the @var{n}th mipmap reduction image.
17116 @item @var{xoffset}
17117 Specifies a texel offset in the x direction within the texture array.
17120 Specifies the width of the texture subimage.
17123 Specifies the format of the pixel data. The following symbolic values
17124 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
17125 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
17126 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
17127 @code{GL_LUMINANCE_ALPHA}.
17130 Specifies the data type of the pixel data. The following symbolic values
17131 are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
17132 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
17133 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
17134 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
17135 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
17136 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
17137 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
17138 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
17139 and @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
17142 Specifies a pointer to the image data in memory.
17146 Texturing maps a portion of a specified texture image onto each
17147 graphical primitive for which texturing is enabled. To enable or disable
17148 one-dimensional texturing, call @code{glEnable} and @code{glDisable}
17149 with argument @code{GL_TEXTURE_1D}.
17151 @code{glTexSubImage1D} redefines a contiguous subregion of an existing
17152 one-dimensional texture image. The texels referenced by @var{data}
17153 replace the portion of the existing texture array with x indices
17154 @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive. This
17155 region may not include any texels outside the range of the texture array
17156 as it was originally specified. It is not an error to specify a
17157 subtexture with width of 0, but such a specification has no effect.
17159 If a non-zero named buffer object is bound to the
17160 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
17161 texture image is specified, @var{data} is treated as a byte offset into
17162 the buffer object's data store.
17164 @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the
17167 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
17170 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
17173 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
17174 and @var{format} is not @code{GL_COLOR_INDEX}.
17176 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
17178 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
17179 @r{@var{log}_2}@var{max}, where @var{max} is the returned value of
17180 @code{GL_MAX_TEXTURE_SIZE}.
17182 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, or
17183 if @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, where
17184 @r{@var{w}} is the @code{GL_TEXTURE_WIDTH}, and @r{@var{b}} is the width
17185 of the @code{GL_TEXTURE_BORDER} of the texture image being modified.
17186 Note that @r{@var{w}} includes twice the border width.
17188 @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0.
17190 @code{GL_INVALID_OPERATION} is generated if the texture array has not
17191 been defined by a previous @code{glTexImage1D} operation.
17193 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
17194 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
17195 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
17196 and @var{format} is not @code{GL_RGB}.
17198 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
17199 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
17200 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
17201 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
17202 @code{GL_UNSIGNED_INT_10_10_10_2}, or
17203 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
17204 @code{GL_RGBA} nor @code{GL_BGRA}.
17206 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
17207 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
17208 object's data store is currently mapped.
17210 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
17211 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
17212 would be unpacked from the buffer object such that the memory reads
17213 required would exceed the data store size.
17215 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
17216 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
17217 is not evenly divisible into the number of bytes needed to store in
17218 memory a datum indicated by @var{type}.
17220 @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage1D} is
17221 executed between the execution of @code{glBegin} and the corresponding
17222 execution of @code{glEnd}.
17226 @deftypefun void glTexSubImage2D target level xoffset yoffset width height format type data
17227 Specify a two-dimensional texture subimage.
17231 Specifies the target texture. Must be @code{GL_TEXTURE_2D},
17232 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
17233 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
17234 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
17235 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
17236 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
17237 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
17240 Specifies the level-of-detail number. Level 0 is the base image level.
17241 Level @var{n} is the @var{n}th mipmap reduction image.
17243 @item @var{xoffset}
17244 Specifies a texel offset in the x direction within the texture array.
17246 @item @var{yoffset}
17247 Specifies a texel offset in the y direction within the texture array.
17250 Specifies the width of the texture subimage.
17253 Specifies the height of the texture subimage.
17256 Specifies the format of the pixel data. The following symbolic values
17257 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
17258 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
17259 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
17260 @code{GL_LUMINANCE_ALPHA}.
17263 Specifies the data type of the pixel data. The following symbolic values
17264 are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
17265 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
17266 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
17267 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
17268 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
17269 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
17270 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
17271 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
17272 and @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
17275 Specifies a pointer to the image data in memory.
17279 Texturing maps a portion of a specified texture image onto each
17280 graphical primitive for which texturing is enabled. To enable and
17281 disable two-dimensional texturing, call @code{glEnable} and
17282 @code{glDisable} with argument @code{GL_TEXTURE_2D}.
17284 @code{glTexSubImage2D} redefines a contiguous subregion of an existing
17285 two-dimensional texture image. The texels referenced by @var{data}
17286 replace the portion of the existing texture array with x indices
17287 @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive, and y
17288 indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive.
17289 This region may not include any texels outside the range of the texture
17290 array as it was originally specified. It is not an error to specify a
17291 subtexture with zero width or height, but such a specification has no
17294 If a non-zero named buffer object is bound to the
17295 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
17296 texture image is specified, @var{data} is treated as a byte offset into
17297 the buffer object's data store.
17299 @code{GL_INVALID_ENUM} is generated if @var{target} is not
17300 @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X},
17301 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X},
17302 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y},
17303 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y},
17304 @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or
17305 @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}.
17307 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
17310 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
17313 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
17314 and @var{format} is not @code{GL_COLOR_INDEX}.
17316 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
17318 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
17319 @r{@var{log}_2}@var{max}, where @var{max} is the returned value of
17320 @code{GL_MAX_TEXTURE_SIZE}.
17322 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}},
17323 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)},
17324 @r{@var{yoffset}<-@var{b}}, or
17325 @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, where @r{@var{w}}
17326 is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the
17327 @code{GL_TEXTURE_HEIGHT}, and @r{@var{b}} is the border width of the
17328 texture image being modified. Note that @r{@var{w}} and @r{@var{h}}
17329 include twice the border width.
17331 @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is
17334 @code{GL_INVALID_OPERATION} is generated if the texture array has not
17335 been defined by a previous @code{glTexImage2D} operation.
17337 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
17338 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
17339 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
17340 and @var{format} is not @code{GL_RGB}.
17342 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
17343 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
17344 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
17345 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
17346 @code{GL_UNSIGNED_INT_10_10_10_2}, or
17347 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
17348 @code{GL_RGBA} nor @code{GL_BGRA}.
17350 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
17351 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
17352 object's data store is currently mapped.
17354 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
17355 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
17356 would be unpacked from the buffer object such that the memory reads
17357 required would exceed the data store size.
17359 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
17360 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
17361 is not evenly divisible into the number of bytes needed to store in
17362 memory a datum indicated by @var{type}.
17364 @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage2D} is
17365 executed between the execution of @code{glBegin} and the corresponding
17366 execution of @code{glEnd}.
17370 @deftypefun void glTexSubImage3D target level xoffset yoffset zoffset width height depth format type data
17371 Specify a three-dimensional texture subimage.
17375 Specifies the target texture. Must be @code{GL_TEXTURE_3D}.
17378 Specifies the level-of-detail number. Level 0 is the base image level.
17379 Level @var{n} is the @var{n}th mipmap reduction image.
17381 @item @var{xoffset}
17382 Specifies a texel offset in the x direction within the texture array.
17384 @item @var{yoffset}
17385 Specifies a texel offset in the y direction within the texture array.
17387 @item @var{zoffset}
17388 Specifies a texel offset in the z direction within the texture array.
17391 Specifies the width of the texture subimage.
17394 Specifies the height of the texture subimage.
17397 Specifies the depth of the texture subimage.
17400 Specifies the format of the pixel data. The following symbolic values
17401 are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN},
17402 @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR},
17403 @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and
17404 @code{GL_LUMINANCE_ALPHA}.
17407 Specifies the data type of the pixel data. The following symbolic values
17408 are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP},
17409 @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT},
17410 @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2},
17411 @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5},
17412 @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4},
17413 @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1},
17414 @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8},
17415 @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2},
17416 and @code{GL_UNSIGNED_INT_2_10_10_10_REV}.
17419 Specifies a pointer to the image data in memory.
17423 Texturing maps a portion of a specified texture image onto each
17424 graphical primitive for which texturing is enabled. To enable and
17425 disable three-dimensional texturing, call @code{glEnable} and
17426 @code{glDisable} with argument @code{GL_TEXTURE_3D}.
17428 @code{glTexSubImage3D} redefines a contiguous subregion of an existing
17429 three-dimensional texture image. The texels referenced by @var{data}
17430 replace the portion of the existing texture array with x indices
17431 @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive, y indices
17432 @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive, and z
17433 indices @var{zoffset} and @r{@var{zoffset}+@var{depth}-1}, inclusive.
17434 This region may not include any texels outside the range of the texture
17435 array as it was originally specified. It is not an error to specify a
17436 subtexture with zero width, height, or depth but such a specification
17439 If a non-zero named buffer object is bound to the
17440 @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a
17441 texture image is specified, @var{data} is treated as a byte offset into
17442 the buffer object's data store.
17444 @code{GL_INVALID_ENUM} is generated if /@var{target} is not
17445 @code{GL_TEXTURE_3D}.
17447 @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted
17450 @code{GL_INVALID_ENUM} is generated if @var{type} is not a type
17453 @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP}
17454 and @var{format} is not @code{GL_COLOR_INDEX}.
17456 @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0.
17458 @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than
17459 @r{@var{log}_2}@var{max}, where @var{max} is the returned value of
17460 @code{GL_MAX_TEXTURE_SIZE}.
17462 @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}},
17463 @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)},
17464 @r{@var{yoffset}<-@var{b}}, or
17465 @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, or
17466 @r{@var{zoffset}<-@var{b}}, or
17467 @r{(@var{zoffset}+@var{depth},)>(@var{d}-@var{b},)}, where @r{@var{w}}
17468 is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the
17469 @code{GL_TEXTURE_HEIGHT}, @r{@var{d}} is the @code{GL_TEXTURE_DEPTH} and
17470 @r{@var{b}} is the border width of the texture image being modified.
17471 Note that @r{@var{w}}, @r{@var{h}}, and @r{@var{d}} include twice the
17474 @code{GL_INVALID_VALUE} is generated if @var{width}, @var{height}, or
17475 @var{depth} is less than 0.
17477 @code{GL_INVALID_OPERATION} is generated if the texture array has not
17478 been defined by a previous @code{glTexImage3D} operation.
17480 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
17481 @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV},
17482 @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV}
17483 and @var{format} is not @code{GL_RGB}.
17485 @code{GL_INVALID_OPERATION} is generated if @var{type} is one of
17486 @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV},
17487 @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV},
17488 @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV},
17489 @code{GL_UNSIGNED_INT_10_10_10_2}, or
17490 @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither
17491 @code{GL_RGBA} nor @code{GL_BGRA}.
17493 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
17494 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer
17495 object's data store is currently mapped.
17497 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
17498 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data
17499 would be unpacked from the buffer object such that the memory reads
17500 required would exceed the data store size.
17502 @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object
17503 name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data}
17504 is not evenly divisible into the number of bytes needed to store in
17505 memory a datum indicated by @var{type}.
17507 @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage3D} is
17508 executed between the execution of @code{glBegin} and the corresponding
17509 execution of @code{glEnd}.
17513 @deftypefun void glTranslatef x y z
17514 Multiply the current matrix by a translation matrix.
17520 Specify the @var{x}, @var{y}, and @var{z} coordinates of a translation
17525 @code{glTranslate} produces a translation by
17526 @r{(@var{x},@var{y}@var{z})}. The current matrix (see
17527 @code{glMatrixMode}) is multiplied by this translation matrix, with the
17528 product replacing the current matrix, as if @code{glMultMatrix} were
17529 called with the following matrix for its argument:
17531 @r{((1 0 0 @var{x}), (0 1 0 @var{y}), (0 0 1 @var{z}), (0 0 0 1),)}
17535 If the matrix mode is either @code{GL_MODELVIEW} or
17536 @code{GL_PROJECTION}, all objects drawn after a call to
17537 @code{glTranslate} are translated.
17539 Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the
17540 untranslated coordinate system.
17542 @code{GL_INVALID_OPERATION} is generated if @code{glTranslate} is
17543 executed between the execution of @code{glBegin} and the corresponding
17544 execution of @code{glEnd}.
17548 @deftypefun void glUniform1f location v0
17549 @deftypefunx void glUniform2f location v0 v1
17550 @deftypefunx void glUniform3f location v0 v1 v2
17551 @deftypefunx void glUniform4f location v0 v1 v2 v3
17552 @deftypefunx void glUniform1i location v0
17553 @deftypefunx void glUniform2i location v0 v1
17554 @deftypefunx void glUniform3i location v0 v1 v2
17555 @deftypefunx void glUniform4i location v0 v1 v2 v3
17556 Specify the value of a uniform variable for the current program object.
17559 @item @var{location}
17560 Specifies the location of the uniform variable to be modified.
17562 @item @var{v0}, @var{v1}, @var{v2}, @var{v3}
17563 Specifies the new values to be used for the specified uniform variable.
17567 @code{glUniform} modifies the value of a uniform variable or a uniform
17568 variable array. The location of the uniform variable to be modified is
17569 specified by @var{location}, which should be a value returned by
17570 @code{glGetUniformLocation}. @code{glUniform} operates on the program
17571 object that was made part of current state by calling
17572 @code{glUseProgram}.
17574 The commands @code{glUniform@{1|2|3|4@}@{f|i@}} are used to change the
17575 value of the uniform variable specified by @var{location} using the
17576 values passed as arguments. The number specified in the command should
17577 match the number of components in the data type of the specified uniform
17578 variable (e.g., @code{1} for float, int, bool; @code{2} for vec2, ivec2,
17579 bvec2, etc.). The suffix @code{f} indicates that floating-point values
17580 are being passed; the suffix @code{i} indicates that integer values are
17581 being passed, and this type should also match the data type of the
17582 specified uniform variable. The @code{i} variants of this function
17583 should be used to provide values for uniform variables defined as int,
17584 ivec2, ivec3, ivec4, or arrays of these. The @code{f} variants should be
17585 used to provide values for uniform variables of type float, vec2, vec3,
17586 vec4, or arrays of these. Either the @code{i} or the @code{f} variants
17587 may be used to provide values for uniform variables of type bool, bvec2,
17588 bvec3, bvec4, or arrays of these. The uniform variable will be set to
17589 false if the input value is 0 or 0.0f, and it will be set to true
17592 All active uniform variables defined in a program object are initialized
17593 to 0 when the program object is linked successfully. They retain the
17594 values assigned to them by a call to @code{glUniform } until the next
17595 successful link operation occurs on the program object, when they are
17596 once again initialized to 0.
17598 The commands @code{glUniform@{1|2|3|4@}@{f|i@}v} can be used to modify a
17599 single uniform variable or a uniform variable array. These commands pass
17600 a count and a pointer to the values to be loaded into a uniform variable
17601 or a uniform variable array. A count of 1 should be used if modifying
17602 the value of a single uniform variable, and a count of 1 or greater can
17603 be used to modify an entire array or part of an array. When loading
17604 @var{n} elements starting at an arbitrary position @var{m} in a uniform
17605 variable array, elements @var{m} + @var{n} - 1 in the array will be
17606 replaced with the new values. If @var{m} + @var{n} - 1 is larger than
17607 the size of the uniform variable array, values for all array elements
17608 beyond the end of the array will be ignored. The number specified in the
17609 name of the command indicates the number of components for each element
17610 in @var{value}, and it should match the number of components in the data
17611 type of the specified uniform variable (e.g., @code{1} for float, int,
17612 bool; @code{2} for vec2, ivec2, bvec2, etc.). The data type specified in
17613 the name of the command must match the data type for the specified
17614 uniform variable as described previously for
17615 @code{glUniform@{1|2|3|4@}@{f|i@}}.
17617 For uniform variable arrays, each element of the array is considered to
17618 be of the type indicated in the name of the command (e.g.,
17619 @code{glUniform3f} or @code{glUniform3fv} can be used to load a uniform
17620 variable array of type vec3). The number of elements of the uniform
17621 variable array to be modified is specified by @var{count}
17623 The commands @code{glUniformMatrix@{2|3|4|2x3|3x2|2x4|4x2|3x4|4x3@}fv}
17624 are used to modify a matrix or an array of matrices. The numbers in the
17625 command name are interpreted as the dimensionality of the matrix. The
17626 number @code{2} indicates a 2 × 2 matrix (i.e., 4 values), the number
17627 @code{3} indicates a 3 × 3 matrix (i.e., 9 values), and the number
17628 @code{4} indicates a 4 × 4 matrix (i.e., 16 values). Non-square matrix
17629 dimensionality is explicit, with the first number representing the
17630 number of columns and the second number representing the number of rows.
17631 For example, @code{2x4} indicates a 2 × 4 matrix with 2 columns and 4
17632 rows (i.e., 8 values). If @var{transpose} is @code{GL_FALSE}, each
17633 matrix is assumed to be supplied in column major order. If
17634 @var{transpose} is @code{GL_TRUE}, each matrix is assumed to be supplied
17635 in row major order. The @var{count} argument indicates the number of
17636 matrices to be passed. A count of 1 should be used if modifying the
17637 value of a single matrix, and a count greater than 1 can be used to
17638 modify an array of matrices.
17640 @code{GL_INVALID_OPERATION} is generated if there is no current program
17643 @code{GL_INVALID_OPERATION} is generated if the size of the uniform
17644 variable declared in the shader does not match the size indicated by the
17645 @code{glUniform} command.
17647 @code{GL_INVALID_OPERATION} is generated if one of the integer variants
17648 of this function is used to load a uniform variable of type float, vec2,
17649 vec3, vec4, or an array of these, or if one of the floating-point
17650 variants of this function is used to load a uniform variable of type
17651 int, ivec2, ivec3, or ivec4, or an array of these.
17653 @code{GL_INVALID_OPERATION} is generated if @var{location} is an invalid
17654 uniform location for the current program object and @var{location} is
17657 @code{GL_INVALID_VALUE} is generated if @var{count} is less than 0.
17659 @code{GL_INVALID_OPERATION} is generated if @var{count} is greater than
17660 1 and the indicated uniform variable is not an array variable.
17662 @code{GL_INVALID_OPERATION} is generated if a sampler is loaded using a
17663 command other than @code{glUniform1i} and @code{glUniform1iv}.
17665 @code{GL_INVALID_OPERATION} is generated if @code{glUniform} is executed
17666 between the execution of @code{glBegin} and the corresponding execution
17671 @deftypefun void glUseProgram program
17672 Installs a program object as part of current rendering state.
17675 @item @var{program}
17676 Specifies the handle of the program object whose executables are to be
17677 used as part of current rendering state.
17681 @code{glUseProgram} installs the program object specified by
17682 @var{program} as part of current rendering state. One or more
17683 executables are created in a program object by successfully attaching
17684 shader objects to it with @code{glAttachShader}, successfully compiling
17685 the shader objects with @code{glCompileShader}, and successfully linking
17686 the program object with @code{glLinkProgram}.
17688 A program object will contain an executable that will run on the vertex
17689 processor if it contains one or more shader objects of type
17690 @code{GL_VERTEX_SHADER} that have been successfully compiled and linked.
17691 Similarly, a program object will contain an executable that will run on
17692 the fragment processor if it contains one or more shader objects of type
17693 @code{GL_FRAGMENT_SHADER} that have been successfully compiled and
17696 Successfully installing an executable on a programmable processor will
17697 cause the corresponding fixed functionality of OpenGL to be disabled.
17698 Specifically, if an executable is installed on the vertex processor, the
17699 OpenGL fixed functionality will be disabled as follows.
17703 The modelview matrix is not applied to vertex coordinates.
17706 The projection matrix is not applied to vertex coordinates.
17709 The texture matrices are not applied to texture coordinates.
17712 Normals are not transformed to eye coordinates.
17715 Normals are not rescaled or normalized.
17718 Normalization of @code{GL_AUTO_NORMAL} evaluated normals is not
17722 Texture coordinates are not generated automatically.
17725 Per-vertex lighting is not performed.
17728 Color material computations are not performed.
17731 Color index lighting is not performed.
17734 This list also applies when setting the current raster position.
17738 The executable that is installed on the vertex processor is expected to
17739 implement any or all of the desired functionality from the preceding
17740 list. Similarly, if an executable is installed on the fragment
17741 processor, the OpenGL fixed functionality will be disabled as follows.
17745 Texture environment and texture functions are not applied.
17748 Texture application is not applied.
17751 Color sum is not applied.
17754 Fog is not applied.
17758 Again, the fragment shader that is installed is expected to implement
17759 any or all of the desired functionality from the preceding list.
17761 While a program object is in use, applications are free to modify
17762 attached shader objects, compile attached shader objects, attach
17763 additional shader objects, and detach or delete shader objects. None of
17764 these operations will affect the executables that are part of the
17765 current state. However, relinking the program object that is currently
17766 in use will install the program object as part of the current rendering
17767 state if the link operation was successful (see @code{glLinkProgram} ).
17768 If the program object currently in use is relinked unsuccessfully, its
17769 link status will be set to @code{GL_FALSE}, but the executables and
17770 associated state will remain part of the current state until a
17771 subsequent call to @code{glUseProgram} removes it from use. After it is
17772 removed from use, it cannot be made part of current state until it has
17773 been successfully relinked.
17775 If @var{program} contains shader objects of type @code{GL_VERTEX_SHADER}
17776 but it does not contain shader objects of type
17777 @code{GL_FRAGMENT_SHADER}, an executable will be installed on the vertex
17778 processor, but fixed functionality will be used for fragment processing.
17779 Similarly, if @var{program} contains shader objects of type
17780 @code{GL_FRAGMENT_SHADER} but it does not contain shader objects of type
17781 @code{GL_VERTEX_SHADER}, an executable will be installed on the fragment
17782 processor, but fixed functionality will be used for vertex processing.
17783 If @var{program} is 0, the programmable processors will be disabled, and
17784 fixed functionality will be used for both vertex and fragment
17787 @code{GL_INVALID_VALUE} is generated if @var{program} is neither 0 nor a
17788 value generated by OpenGL.
17790 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
17793 @code{GL_INVALID_OPERATION} is generated if @var{program} could not be
17794 made part of current state.
17796 @code{GL_INVALID_OPERATION} is generated if @code{glUseProgram} is
17797 executed between the execution of @code{glBegin} and the corresponding
17798 execution of @code{glEnd}.
17802 @deftypefun void glValidateProgram program
17803 Validates a program object.
17806 @item @var{program}
17807 Specifies the handle of the program object to be validated.
17811 @code{glValidateProgram} checks to see whether the executables contained
17812 in @var{program} can execute given the current OpenGL state. The
17813 information generated by the validation process will be stored in
17814 @var{program}'s information log. The validation information may consist
17815 of an empty string, or it may be a string containing information about
17816 how the current program object interacts with the rest of current OpenGL
17817 state. This provides a way for OpenGL implementers to convey more
17818 information about why the current program is inefficient, suboptimal,
17819 failing to execute, and so on.
17821 The status of the validation operation will be stored as part of the
17822 program object's state. This value will be set to @code{GL_TRUE} if the
17823 validation succeeded, and @code{GL_FALSE} otherwise. It can be queried
17824 by calling @code{glGetProgram} with arguments @var{program} and
17825 @code{GL_VALIDATE_STATUS}. If validation is successful, @var{program} is
17826 guaranteed to execute given the current state. Otherwise, @var{program}
17827 is guaranteed to not execute.
17829 This function is typically useful only during application development.
17830 The informational string stored in the information log is completely
17831 implementation dependent; therefore, an application should not expect
17832 different OpenGL implementations to produce identical information
17835 @code{GL_INVALID_VALUE} is generated if @var{program} is not a value
17836 generated by OpenGL.
17838 @code{GL_INVALID_OPERATION} is generated if @var{program} is not a
17841 @code{GL_INVALID_OPERATION} is generated if @code{glValidateProgram} is
17842 executed between the execution of @code{glBegin} and the corresponding
17843 execution of @code{glEnd}.
17847 @deftypefun void glVertexAttribPointer index size type normalized stride pointer
17848 Define an array of generic vertex attribute data.
17852 Specifies the index of the generic vertex attribute to be modified.
17855 Specifies the number of components per generic vertex attribute. Must be
17856 1, 2, 3, or 4. The initial value is 4.
17859 Specifies the data type of each component in the array. Symbolic
17860 constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT},
17861 @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT},
17862 @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is
17865 @item @var{normalized}
17866 Specifies whether fixed-point data values should be normalized
17867 (@code{GL_TRUE}) or converted directly as fixed-point values
17868 (@code{GL_FALSE}) when they are accessed.
17871 Specifies the byte offset between consecutive generic vertex attributes.
17872 If @var{stride} is 0, the generic vertex attributes are understood to be
17873 tightly packed in the array. The initial value is 0.
17875 @item @var{pointer}
17876 Specifies a pointer to the first component of the first generic vertex
17877 attribute in the array. The initial value is 0.
17881 @code{glVertexAttribPointer} specifies the location and data format of
17882 the array of generic vertex attributes at index @var{index} to use when
17883 rendering. @var{size} specifies the number of components per attribute
17884 and must be 1, 2, 3, or 4. @var{type} specifies the data type of each
17885 component, and @var{stride} specifies the byte stride from one attribute
17886 to the next, allowing vertices and attributes to be packed into a single
17887 array or stored in separate arrays. If set to @code{GL_TRUE},
17888 @var{normalized} indicates that values stored in an integer format are
17889 to be mapped to the range [-1,1] (for signed values) or [0,1] (for
17890 unsigned values) when they are accessed and converted to floating point.
17891 Otherwise, values will be converted to floats directly without
17894 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
17895 target (see @code{glBindBuffer}) while a generic vertex attribute array
17896 is specified, @var{pointer} is treated as a byte offset into the buffer
17897 object's data store. Also, the buffer object binding
17898 (@code{GL_ARRAY_BUFFER_BINDING}) is saved as generic vertex attribute
17899 array client-side state (@code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING})
17900 for index @var{index}.
17902 When a generic vertex attribute array is specified, @var{size},
17903 @var{type}, @var{normalized}, @var{stride}, and @var{pointer} are saved
17904 as client-side state, in addition to the current vertex array buffer
17907 To enable and disable a generic vertex attribute array, call
17908 @code{glEnableVertexAttribArray} and @code{glDisableVertexAttribArray}
17909 with @var{index}. If enabled, the generic vertex attribute array is used
17910 when @code{glArrayElement}, @code{glDrawArrays},
17911 @code{glMultiDrawArrays}, @code{glDrawElements},
17912 @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called.
17914 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
17915 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
17917 @code{GL_INVALID_VALUE} is generated if @var{size} is not 1, 2, 3, or 4.
17919 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
17922 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
17926 @deftypefun void glVertexAttrib1f index v0
17927 @deftypefunx void glVertexAttrib1s index v0
17928 @deftypefunx void glVertexAttrib2f index v0 v1
17929 @deftypefunx void glVertexAttrib2s index v0 v1
17930 @deftypefunx void glVertexAttrib3f index v0 v1 v2
17931 @deftypefunx void glVertexAttrib3s index v0 v1 v2
17932 @deftypefunx void glVertexAttrib4f index v0 v1 v2 v3
17933 @deftypefunx void glVertexAttrib4s index v0 v1 v2 v3
17934 @deftypefunx void glVertexAttrib4Nub index v0 v1 v2 v3
17935 Specifies the value of a generic vertex attribute.
17939 Specifies the index of the generic vertex attribute to be modified.
17941 @item @var{v0}, @var{v1}, @var{v2}, @var{v3}
17942 Specifies the new values to be used for the specified vertex attribute.
17946 OpenGL defines a number of standard vertex attributes that applications
17947 can modify with standard API entry points (color, normal, texture
17948 coordinates, etc.). The @code{glVertexAttrib} family of entry points
17949 allows an application to pass generic vertex attributes in numbered
17952 Generic attributes are defined as four-component values that are
17953 organized into an array. The first entry of this array is numbered 0,
17954 and the size of the array is specified by the implementation-dependent
17955 constant @code{GL_MAX_VERTEX_ATTRIBS}. Individual elements of this array
17956 can be modified with a @code{glVertexAttrib} call that specifies the
17957 index of the element to be modified and a value for that element.
17959 These commands can be used to specify one, two, three, or all four
17960 components of the generic vertex attribute specified by @var{index}. A
17961 @code{1} in the name of the command indicates that only one value is
17962 passed, and it will be used to modify the first component of the generic
17963 vertex attribute. The second and third components will be set to 0, and
17964 the fourth component will be set to 1. Similarly, a @code{2} in the name
17965 of the command indicates that values are provided for the first two
17966 components, the third component will be set to 0, and the fourth
17967 component will be set to 1. A @code{3} in the name of the command
17968 indicates that values are provided for the first three components and
17969 the fourth component will be set to 1, whereas a @code{4} in the name
17970 indicates that values are provided for all four components.
17972 The letters @code{s}, @code{f}, @code{i}, @code{d}, @code{ub},
17973 @code{us}, and @code{ui} indicate whether the arguments are of type
17974 short, float, int, double, unsigned byte, unsigned short, or unsigned
17975 int. When @code{v} is appended to the name, the commands can take a
17976 pointer to an array of such values. The commands containing @code{N}
17977 indicate that the arguments will be passed as fixed-point values that
17978 are scaled to a normalized range according to the component conversion
17979 rules defined by the OpenGL specification. Signed values are understood
17980 to represent fixed-point values in the range [-1,1], and unsigned values
17981 are understood to represent fixed-point values in the range [0,1].
17983 OpenGL Shading Language attribute variables are allowed to be of type
17984 mat2, mat3, or mat4. Attributes of these types may be loaded using the
17985 @code{glVertexAttrib} entry points. Matrices must be loaded into
17986 successive generic attribute slots in column major order, with one
17987 column of the matrix in each generic attribute slot.
17989 A user-defined attribute variable declared in a vertex shader can be
17990 bound to a generic attribute index by calling
17991 @code{glBindAttribLocation}. This allows an application to use more
17992 descriptive variable names in a vertex shader. A subsequent change to
17993 the specified generic vertex attribute will be immediately reflected as
17994 a change to the corresponding attribute variable in the vertex shader.
17996 The binding between a generic vertex attribute index and a user-defined
17997 attribute variable in a vertex shader is part of the state of a program
17998 object, but the current value of the generic vertex attribute is not.
17999 The value of each generic vertex attribute is part of current state,
18000 just like standard vertex attributes, and it is maintained even if a
18001 different program object is used.
18003 An application may freely modify generic vertex attributes that are not
18004 bound to a named vertex shader attribute variable. These values are
18005 simply maintained as part of current state and will not be accessed by
18006 the vertex shader. If a generic vertex attribute bound to an attribute
18007 variable in a vertex shader is not updated while the vertex shader is
18008 executing, the vertex shader will repeatedly use the current value for
18009 the generic vertex attribute.
18011 The generic vertex attribute with index 0 is the same as the vertex
18012 position attribute previously defined by OpenGL. A @code{glVertex2},
18013 @code{glVertex3}, or @code{glVertex4} command is completely equivalent
18014 to the corresponding @code{glVertexAttrib} command with an index
18015 argument of 0. A vertex shader can access generic vertex attribute 0 by
18016 using the built-in attribute variable @var{gl_Vertex}. There are no
18017 current values for generic vertex attribute 0. This is the only generic
18018 vertex attribute with this property; calls to set other standard vertex
18019 attributes can be freely mixed with calls to set any of the other
18020 generic vertex attributes.
18022 @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or
18023 equal to @code{GL_MAX_VERTEX_ATTRIBS}.
18027 @deftypefun void glVertexPointer size type stride pointer
18028 Define an array of vertex data.
18032 Specifies the number of coordinates per vertex. Must be 2, 3, or 4. The
18033 initial value is 4.
18036 Specifies the data type of each coordinate in the array. Symbolic
18037 constants @code{GL_SHORT}, @code{GL_INT}, @code{GL_FLOAT}, or
18038 @code{GL_DOUBLE} are accepted. The initial value is @code{GL_FLOAT}.
18041 Specifies the byte offset between consecutive vertices. If @var{stride}
18042 is 0, the vertices are understood to be tightly packed in the array. The
18043 initial value is 0.
18045 @item @var{pointer}
18046 Specifies a pointer to the first coordinate of the first vertex in the
18047 array. The initial value is 0.
18051 @code{glVertexPointer} specifies the location and data format of an
18052 array of vertex coordinates to use when rendering. @var{size} specifies
18053 the number of coordinates per vertex, and must be 2, 3, or 4. @var{type}
18054 specifies the data type of each coordinate, and @var{stride} specifies
18055 the byte stride from one vertex to the next, allowing vertices and
18056 attributes to be packed into a single array or stored in separate
18057 arrays. (Single-array storage may be more efficient on some
18058 implementations; see @code{glInterleavedArrays}.)
18060 If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER}
18061 target (see @code{glBindBuffer}) while a vertex array is specified,
18062 @var{pointer} is treated as a byte offset into the buffer object's data
18063 store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING})
18064 is saved as vertex array client-side state
18065 (@code{GL_VERTEX_ARRAY_BUFFER_BINDING}).
18067 When a vertex array is specified, @var{size}, @var{type}, @var{stride},
18068 and @var{pointer} are saved as client-side state, in addition to the
18069 current vertex array buffer object binding.
18071 To enable and disable the vertex array, call @code{glEnableClientState}
18072 and @code{glDisableClientState} with the argument
18073 @code{GL_VERTEX_ARRAY}. If enabled, the vertex array is used when
18074 @code{glArrayElement}, @code{glDrawArrays}, @code{glMultiDrawArrays},
18075 @code{glDrawElements}, @code{glMultiDrawElements}, or
18076 @code{glDrawRangeElements} is called.
18078 @code{GL_INVALID_VALUE} is generated if @var{size} is not 2, 3, or 4.
18080 @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted
18083 @code{GL_INVALID_VALUE} is generated if @var{stride} is negative.
18087 @deftypefun void glVertex2i x y
18088 @deftypefunx void glVertex2f x y
18089 @deftypefunx void glVertex3i x y z
18090 @deftypefunx void glVertex3f x y z
18091 @deftypefunx void glVertex4i x y z w
18092 @deftypefunx void glVertex4f x y z w
18100 Specify @var{x}, @var{y}, @var{z}, and @var{w} coordinates of a vertex.
18101 Not all parameters are present in all forms of the command.
18105 @code{glVertex} commands are used within @code{glBegin}/@code{glEnd}
18106 pairs to specify point, line, and polygon vertices. The current color,
18107 normal, texture coordinates, and fog coordinate are associated with the
18108 vertex when @code{glVertex} is called.
18110 When only @r{@var{x}} and @r{@var{y}} are specified, @r{@var{z}}
18111 defaults to 0 and @r{@var{w}} defaults to 1. When @r{@var{x}},
18112 @r{@var{y}}, and @r{@var{z}} are specified, @r{@var{w}} defaults to 1.
18116 @deftypefun void glViewport x y width height
18122 Specify the lower left corner of the viewport rectangle, in pixels. The
18123 initial value is (0,0).
18126 @itemx @var{height}
18127 Specify the width and height of the viewport. When a GL context is first
18128 attached to a window, @var{width} and @var{height} are set to the
18129 dimensions of that window.
18133 @code{glViewport} specifies the affine transformation of @r{@var{x}} and
18134 @r{@var{y}} from normalized device coordinates to window coordinates.
18135 Let @r{(@var{x}_@var{nd},@var{y}_@var{nd})} be normalized device
18136 coordinates. Then the window coordinates
18137 @r{(@var{x}_@var{w},@var{y}_@var{w})} are computed as follows:
18139 @r{@var{x}_@var{w}=(@var{x}_@var{nd}+1,)(@var{width}/2,)+@var{x}}
18141 @r{@var{y}_@var{w}=(@var{y}_@var{nd}+1,)(@var{height}/2,)+@var{y}}
18143 Viewport width and height are silently clamped to a range that depends
18144 on the implementation. To query this range, call @code{glGet} with
18145 argument @code{GL_MAX_VIEWPORT_DIMS}.
18147 @code{GL_INVALID_VALUE} is generated if either @var{width} or
18148 @var{height} is negative.
18150 @code{GL_INVALID_OPERATION} is generated if @code{glViewport} is
18151 executed between the execution of @code{glBegin} and the corresponding
18152 execution of @code{glEnd}.
18156 @deftypefun void glWindowPos2i x y
18157 @deftypefunx void glWindowPos2f x y
18158 @deftypefunx void glWindowPos3i x y z
18159 @deftypefunx void glWindowPos3f x y z
18160 Specify the raster position in window coordinates for pixel operations.
18166 Specify the @r{@var{x}}, @r{@var{y}}, @r{@var{z}} coordinates for the
18171 The GL maintains a 3D position in window coordinates. This position,
18172 called the raster position, is used to position pixel and bitmap write
18173 operations. It is maintained with subpixel accuracy. See
18174 @code{glBitmap}, @code{glDrawPixels}, and @code{glCopyPixels}.
18176 @code{glWindowPos2} specifies the @r{@var{x}} and @r{@var{y}}
18177 coordinates, while @r{@var{z}} is implicitly set to 0.
18178 @code{glWindowPos3} specifies all three coordinates. The @r{@var{w}}
18179 coordinate of the current raster position is always set to 1.0.
18181 @code{glWindowPos} directly updates the @r{@var{x}} and @r{@var{y}}
18182 coordinates of the current raster position with the values specified.
18183 That is, the values are neither transformed by the current modelview and
18184 projection matrices, nor by the viewport-to-window transform. The
18185 @r{@var{z}} coordinate of the current raster position is updated in the
18188 @r{@var{z}=@{(@var{n}), (@var{f}),
18189 (@var{n}+@var{z}×(@var{f}-@var{n},),)(@var{if}@var{z}<=0),
18190 (@var{if}@var{z}>=1), (@code{otherwise},),}
18194 where @r{@var{n}} is @code{GL_DEPTH_RANGE}'s near value, and @r{@var{f}}
18195 is @code{GL_DEPTH_RANGE}'s far value. See @code{glDepthRange}.
18197 The specified coordinates are not clip-tested, causing the raster
18198 position to always be valid.
18200 The current raster position also includes some associated color data and
18201 texture coordinates. If lighting is enabled, then
18202 @code{GL_CURRENT_RASTER_COLOR} (in RGBA mode) or
18203 @code{GL_CURRENT_RASTER_INDEX} (in color index mode) is set to the color
18204 produced by the lighting calculation (see @code{glLight},
18205 @code{glLightModel}, and @code{glShadeModel}). If lighting is disabled,
18206 current color (in RGBA mode, state variable @code{GL_CURRENT_COLOR}) or
18207 color index (in color index mode, state variable
18208 @code{GL_CURRENT_INDEX}) is used to update the current raster color.
18209 @code{GL_CURRENT_RASTER_SECONDARY_COLOR} (in RGBA mode) is likewise
18212 Likewise, @code{GL_CURRENT_RASTER_TEXTURE_COORDS} is updated as a
18213 function of @code{GL_CURRENT_TEXTURE_COORDS}, based on the texture
18214 matrix and the texture generation functions (see @code{glTexGen}). The
18215 @code{GL_CURRENT_RASTER_DISTANCE} is set to the
18216 @code{GL_CURRENT_FOG_COORD}.
18220 @code{GL_INVALID_OPERATION} is generated if @code{glWindowPos} is
18221 executed between the execution of @code{glBegin} and the corresponding
18222 execution of @code{glEnd}.
18227 @c %end of fragment