Commit | Line | Data |
---|---|---|
8925f36f AW |
1 | |
2 | @c %start of fragment | |
3 | ||
3c9b6116 AW |
4 | The functions from this section may be had by loading the module: |
5 | ||
6 | @example | |
7ec693ed | 7 | (use-modules (figl gl low-level) |
3c9b6116 AW |
8 | @end example |
9 | ||
8925f36f AW |
10 | @copying |
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. | |
15 | ||
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/}. | |
19 | ||
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/}. | |
24 | ||
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/}. | |
29 | ||
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/}. | |
34 | ||
35 | @end copying | |
36 | ||
bb894c9d | 37 | @deftypefun void glAccum op value |
3c9b6116 AW |
38 | Operate on the accumulation buffer. |
39 | ||
8925f36f AW |
40 | @table @asis |
41 | @item @var{op} | |
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. | |
45 | ||
46 | @item @var{value} | |
47 | Specifies a floating-point value used in the accumulation buffer | |
48 | operation. @var{op} determines how @var{value} is used. | |
49 | ||
50 | @end table | |
51 | ||
8925f36f AW |
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. | |
58 | ||
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 | |
3c9b6116 | 66 | component is @r{[-1,1]}. The accumulation buffer pixels are mapped |
8925f36f AW |
67 | one-to-one with frame buffer pixels. |
68 | ||
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 | |
74 | @code{GL_RETURN}. | |
75 | ||
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 | |
3c9b6116 | 79 | a value outside the range @r{[-1,1]}, the contents of an accumulation |
8925f36f AW |
80 | buffer pixel component are undefined. |
81 | ||
82 | The operations are as follows: | |
83 | ||
84 | @table @asis | |
85 | @item @code{GL_ACCUM} | |
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 | |
3c9b6116 AW |
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 | |
8925f36f AW |
91 | @var{value} and added to the corresponding pixel component in the |
92 | accumulation buffer, thereby updating the accumulation buffer. | |
93 | ||
94 | @item @code{GL_LOAD} | |
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 | |
3c9b6116 | 98 | are divided by @r{2^@var{n}-1}, multiplied by @var{value}, and then |
8925f36f AW |
99 | stored in the corresponding accumulation buffer cell, overwriting the |
100 | current value. | |
101 | ||
102 | @item @code{GL_ADD} | |
103 | Adds @var{value} to each R, G, B, and A in the accumulation buffer. | |
104 | ||
105 | @item @code{GL_MULT} | |
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 | |
108 | buffer location. | |
109 | ||
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 | |
3c9b6116 AW |
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 | |
117 | writemasks. | |
8925f36f AW |
118 | |
119 | @end table | |
120 | ||
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. | |
124 | ||
8925f36f AW |
125 | @code{GL_INVALID_ENUM} is generated if @var{op} is not an accepted |
126 | value. | |
127 | ||
128 | @code{GL_INVALID_OPERATION} is generated if there is no accumulation | |
129 | buffer. | |
130 | ||
131 | @code{GL_INVALID_OPERATION} is generated if @code{glAccum} is executed | |
132 | between the execution of @code{glBegin} and the corresponding execution | |
133 | of @code{glEnd}. | |
134 | ||
bb894c9d | 135 | @end deftypefun |
8925f36f | 136 | |
bb894c9d | 137 | @deftypefun void glActiveTexture texture |
3c9b6116 AW |
138 | Select active texture unit. |
139 | ||
8925f36f AW |
140 | @table @asis |
141 | @item @var{texture} | |
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} | |
3c9b6116 | 144 | must be one of @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to |
8925f36f AW |
145 | the larger of (@code{GL_MAX_TEXTURE_COORDS} - 1) and |
146 | (@code{GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS} - 1). The initial value is | |
147 | @code{GL_TEXTURE0}. | |
148 | ||
149 | @end table | |
150 | ||
8925f36f AW |
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. | |
154 | ||
155 | Vertex arrays are client-side GL resources, which are selected by the | |
156 | @code{glClientActiveTexture} routine. | |
157 | ||
8925f36f | 158 | @code{GL_INVALID_ENUM} is generated if @var{texture} is not one of |
3c9b6116 | 159 | @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to the larger of |
8925f36f AW |
160 | (@code{GL_MAX_TEXTURE_COORDS} - 1) and |
161 | (@code{GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS} - 1). | |
162 | ||
bb894c9d | 163 | @end deftypefun |
8925f36f | 164 | |
bb894c9d | 165 | @deftypefun void glAlphaFunc func ref |
3c9b6116 AW |
166 | Specify the alpha test function. |
167 | ||
8925f36f AW |
168 | @table @asis |
169 | @item @var{func} | |
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}. | |
174 | ||
175 | @item @var{ref} | |
176 | Specifies the reference value that incoming alpha values are compared | |
3c9b6116 AW |
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 | |
8925f36f AW |
179 | initial reference value is 0. |
180 | ||
181 | @end table | |
182 | ||
8925f36f AW |
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}.) | |
189 | ||
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 | |
196 | as follows: | |
197 | ||
198 | @table @asis | |
199 | @item @code{GL_NEVER} | |
200 | Never passes. | |
201 | ||
202 | @item @code{GL_LESS} | |
203 | Passes if the incoming alpha value is less than the reference value. | |
204 | ||
205 | @item @code{GL_EQUAL} | |
206 | Passes if the incoming alpha value is equal to the reference value. | |
207 | ||
208 | @item @code{GL_LEQUAL} | |
209 | Passes if the incoming alpha value is less than or equal to the | |
210 | reference value. | |
211 | ||
212 | @item @code{GL_GREATER} | |
213 | Passes if the incoming alpha value is greater than the reference value. | |
214 | ||
215 | @item @code{GL_NOTEQUAL} | |
216 | Passes if the incoming alpha value is not equal to the reference value. | |
217 | ||
218 | @item @code{GL_GEQUAL} | |
219 | Passes if the incoming alpha value is greater than or equal to the | |
220 | reference value. | |
221 | ||
222 | @item @code{GL_ALWAYS} | |
223 | Always passes (initial value). | |
224 | ||
225 | @end table | |
226 | ||
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. | |
231 | ||
8925f36f AW |
232 | @code{GL_INVALID_ENUM} is generated if @var{func} is not an accepted |
233 | value. | |
234 | ||
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}. | |
238 | ||
bb894c9d | 239 | @end deftypefun |
8925f36f | 240 | |
bb894c9d | 241 | @deftypefun GLboolean glAreTexturesResident n textures residences |
3c9b6116 AW |
242 | Determine if textures are loaded in texture memory. |
243 | ||
8925f36f AW |
244 | @table @asis |
245 | @item @var{n} | |
246 | Specifies the number of textures to be queried. | |
247 | ||
248 | @item @var{textures} | |
249 | Specifies an array containing the names of the textures to be queried. | |
250 | ||
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}. | |
255 | ||
256 | @end table | |
257 | ||
8925f36f AW |
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. | |
261 | ||
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. | |
271 | ||
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. | |
277 | ||
8925f36f AW |
278 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
279 | ||
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. | |
283 | ||
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}. | |
287 | ||
bb894c9d | 288 | @end deftypefun |
8925f36f | 289 | |
bb894c9d | 290 | @deftypefun void glArrayElement i |
3c9b6116 AW |
291 | Render a vertex using the specified vertex array element. |
292 | ||
8925f36f AW |
293 | @table @asis |
294 | @item @var{i} | |
295 | Specifies an index into the enabled vertex data arrays. | |
296 | ||
297 | @end table | |
298 | ||
8925f36f AW |
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 | |
306 | modified. | |
307 | ||
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 | |
312 | for each triangle. | |
313 | ||
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. | |
321 | ||
8925f36f AW |
322 | @code{GL_INVALID_VALUE} may be generated if @var{i} is negative. |
323 | ||
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 | |
326 | currently mapped. | |
327 | ||
bb894c9d | 328 | @end deftypefun |
8925f36f | 329 | |
bb894c9d | 330 | @deftypefun void glAttachShader program shader |
3c9b6116 AW |
331 | Attaches a shader object to a program object. |
332 | ||
8925f36f AW |
333 | @table @asis |
334 | @item @var{program} | |
335 | Specifies the program object to which a shader object will be attached. | |
336 | ||
337 | @item @var{shader} | |
338 | Specifies the shader object that is to be attached. | |
339 | ||
340 | @end table | |
341 | ||
8925f36f AW |
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}. | |
350 | ||
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. | |
362 | ||
8925f36f AW |
363 | @code{GL_INVALID_VALUE} is generated if either @var{program} or |
364 | @var{shader} is not a value generated by OpenGL. | |
365 | ||
366 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
367 | program object. | |
368 | ||
369 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
370 | object. | |
371 | ||
372 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is already | |
373 | attached to @var{program}. | |
374 | ||
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}. | |
378 | ||
bb894c9d | 379 | @end deftypefun |
8925f36f | 380 | |
bb894c9d AW |
381 | @deftypefun void glBeginQuery target id |
382 | @deftypefunx void glEndQuery target | |
3c9b6116 AW |
383 | Delimit the boundaries of a query object. |
384 | ||
8925f36f AW |
385 | @table @asis |
386 | @item @var{target} | |
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}. | |
390 | ||
391 | @item @var{id} | |
392 | Specifies the name of a query object. | |
393 | ||
394 | @end table | |
395 | ||
8925f36f AW |
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 | |
398 | is created. | |
399 | ||
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}. | |
406 | ||
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 | |
411 | not yet complete. | |
412 | ||
8925f36f AW |
413 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
414 | @code{GL_SAMPLES_PASSED}. | |
415 | ||
416 | @code{GL_INVALID_OPERATION} is generated if @code{glBeginQuery} is | |
417 | executed while a query object of the same @var{target} is already | |
418 | active. | |
419 | ||
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. | |
422 | ||
423 | @code{GL_INVALID_OPERATION} is generated if @var{id} is 0. | |
424 | ||
425 | @code{GL_INVALID_OPERATION} is generated if @var{id} is the name of an | |
426 | already active query object. | |
427 | ||
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}. | |
431 | ||
bb894c9d | 432 | @end deftypefun |
8925f36f | 433 | |
bb894c9d AW |
434 | @deftypefun void glBegin mode |
435 | @deftypefunx void glEnd | |
3c9b6116 AW |
436 | Delimit the vertices of a primitive or a group of like primitives. |
437 | ||
8925f36f AW |
438 | @table @asis |
439 | @item @var{mode} | |
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}. | |
446 | ||
447 | @end table | |
448 | ||
8925f36f AW |
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 | |
3c9b6116 AW |
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 | |
8925f36f AW |
454 | interpretations are as follows: |
455 | ||
456 | @table @asis | |
457 | @item @code{GL_POINTS} | |
3c9b6116 AW |
458 | Treats each vertex as a single point. Vertex @r{@var{n}} defines point |
459 | @r{@var{n}}. @r{@var{N}} points are drawn. | |
8925f36f AW |
460 | |
461 | @item @code{GL_LINES} | |
462 | Treats each pair of vertices as an independent line segment. Vertices | |
3c9b6116 AW |
463 | @r{2@var{n}-1} and @r{2@var{n}} define line @r{@var{n}}. @r{@var{N}/2} |
464 | lines are drawn. | |
8925f36f AW |
465 | |
466 | @item @code{GL_LINE_STRIP} | |
467 | Draws a connected group of line segments from the first vertex to the | |
3c9b6116 AW |
468 | last. Vertices @r{@var{n}} and @r{@var{n}+1} define line @r{@var{n}}. |
469 | @r{@var{N}-1} lines are drawn. | |
8925f36f AW |
470 | |
471 | @item @code{GL_LINE_LOOP} | |
472 | Draws a connected group of line segments from the first vertex to the | |
3c9b6116 AW |
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. | |
8925f36f AW |
476 | |
477 | @item @code{GL_TRIANGLES} | |
478 | Treats each triplet of vertices as an independent triangle. Vertices | |
3c9b6116 AW |
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. | |
8925f36f AW |
481 | |
482 | @item @code{GL_TRIANGLE_STRIP} | |
483 | Draws a connected group of triangles. One triangle is defined for each | |
3c9b6116 AW |
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 | |
488 | are drawn. | |
8925f36f AW |
489 | |
490 | @item @code{GL_TRIANGLE_FAN} | |
491 | Draws a connected group of triangles. One triangle is defined for each | |
3c9b6116 AW |
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. | |
8925f36f AW |
495 | |
496 | @item @code{GL_QUADS} | |
497 | Treats each group of four vertices as an independent quadrilateral. | |
3c9b6116 AW |
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} | |
8925f36f AW |
500 | quadrilaterals are drawn. |
501 | ||
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 | |
3c9b6116 AW |
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 | |
509 | independent data. | |
8925f36f AW |
510 | |
511 | @item @code{GL_POLYGON} | |
3c9b6116 | 512 | Draws a single, convex polygon. Vertices @r{1} through @r{@var{N}} |
8925f36f AW |
513 | define this polygon. |
514 | ||
515 | @end table | |
516 | ||
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. | |
527 | ||
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. | |
535 | ||
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). | |
541 | ||
8925f36f AW |
542 | @code{GL_INVALID_ENUM} is generated if @var{mode} is set to an |
543 | unaccepted value. | |
544 | ||
545 | @code{GL_INVALID_OPERATION} is generated if @code{glBegin} is executed | |
546 | between a @code{glBegin} and the corresponding execution of | |
547 | @code{glEnd}. | |
548 | ||
549 | @code{GL_INVALID_OPERATION} is generated if @code{glEnd} is executed | |
550 | without being preceded by a @code{glBegin}. | |
551 | ||
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 | |
559 | @code{glEnd}. | |
560 | ||
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 | |
569 | not be generated. | |
570 | ||
bb894c9d | 571 | @end deftypefun |
8925f36f | 572 | |
bb894c9d | 573 | @deftypefun void glBindAttribLocation program index name |
3c9b6116 AW |
574 | Associates a generic vertex attribute index with a named attribute |
575 | variable. | |
576 | ||
8925f36f AW |
577 | @table @asis |
578 | @item @var{program} | |
579 | Specifies the handle of the program object in which the association is | |
580 | to be made. | |
581 | ||
582 | @item @var{index} | |
583 | Specifies the index of the generic vertex attribute to be bound. | |
584 | ||
585 | @item @var{name} | |
586 | Specifies a null terminated string containing the name of the vertex | |
587 | shader attribute variable to which @var{index} is to be bound. | |
588 | ||
589 | @end table | |
590 | ||
8925f36f AW |
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}. | |
599 | ||
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 | |
605 | mat4. | |
606 | ||
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}. | |
616 | ||
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 | |
623 | occurs. | |
624 | ||
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 | |
629 | is linked. | |
630 | ||
8925f36f AW |
631 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or |
632 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
633 | ||
634 | @code{GL_INVALID_OPERATION} is generated if @var{name} starts with the | |
635 | reserved prefix "gl_". | |
636 | ||
637 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value | |
638 | generated by OpenGL. | |
639 | ||
640 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
641 | program object. | |
642 | ||
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}. | |
646 | ||
bb894c9d | 647 | @end deftypefun |
8925f36f | 648 | |
bb894c9d | 649 | @deftypefun void glBindBuffer target buffer |
3c9b6116 AW |
650 | Bind a named buffer object. |
651 | ||
8925f36f AW |
652 | @table @asis |
653 | @item @var{target} | |
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}. | |
657 | ||
658 | @item @var{buffer} | |
659 | Specifies the name of a buffer object. | |
660 | ||
661 | @end table | |
662 | ||
8925f36f AW |
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. | |
670 | ||
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 | |
679 | display lists. | |
680 | ||
681 | You may use @code{glGenBuffers} to generate a set of new buffer object | |
682 | names. | |
683 | ||
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. | |
687 | ||
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. | |
694 | ||
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. | |
704 | ||
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. | |
711 | ||
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. | |
721 | ||
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. | |
736 | ||
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}. | |
740 | ||
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 | |
744 | binding target. | |
745 | ||
8925f36f AW |
746 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
747 | allowable values. | |
748 | ||
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}. | |
752 | ||
bb894c9d | 753 | @end deftypefun |
8925f36f | 754 | |
bb894c9d | 755 | @deftypefun void glBindTexture target texture |
3c9b6116 AW |
756 | Bind a named texture to a texturing target. |
757 | ||
8925f36f AW |
758 | @table @asis |
759 | @item @var{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}. | |
763 | ||
764 | @item @var{texture} | |
765 | Specifies the name of a texture. | |
766 | ||
767 | @end table | |
768 | ||
8925f36f AW |
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. | |
775 | ||
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 | |
781 | display lists. | |
782 | ||
783 | You may use @code{glGenTextures} to generate a set of new texture names. | |
784 | ||
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. | |
795 | ||
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. | |
803 | ||
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}. | |
807 | ||
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}. | |
814 | ||
815 | @code{glBindTexture} is included in display lists. | |
816 | ||
8925f36f AW |
817 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
818 | allowable values. | |
819 | ||
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}. | |
822 | ||
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}. | |
826 | ||
bb894c9d | 827 | @end deftypefun |
8925f36f | 828 | |
bb894c9d | 829 | @deftypefun void glBitmap width height xorig yorig xmove ymove bitmap |
3c9b6116 AW |
830 | Draw a bitmap. |
831 | ||
8925f36f AW |
832 | @table @asis |
833 | @item @var{width} | |
834 | @itemx @var{height} | |
835 | Specify the pixel width and height of the bitmap image. | |
836 | ||
837 | @item @var{xorig} | |
838 | @itemx @var{yorig} | |
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. | |
842 | ||
843 | @item @var{xmove} | |
844 | @itemx @var{ymove} | |
845 | Specify the @var{x} and @var{y} offsets to be added to the current | |
846 | raster position after the bitmap is drawn. | |
847 | ||
848 | @item @var{bitmap} | |
849 | Specifies the address of the bitmap image. | |
850 | ||
851 | @end table | |
852 | ||
8925f36f AW |
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 | |
857 | are not modified. | |
858 | ||
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. | |
865 | ||
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. | |
870 | ||
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. | |
878 | ||
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 | |
882 | ||
3c9b6116 | 883 | @r{@var{x}_@var{w}=⌊@var{x}_@var{r}-@var{x}_@var{o},⌋} |
8925f36f | 884 | |
3c9b6116 | 885 | @r{@var{y}_@var{w}=⌊@var{y}_@var{r}-@var{y}_@var{o},⌋} |
8925f36f | 886 | |
3c9b6116 AW |
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. | |
8925f36f AW |
895 | |
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. | |
900 | ||
8925f36f AW |
901 | @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is |
902 | negative. | |
903 | ||
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. | |
907 | ||
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. | |
912 | ||
913 | @code{GL_INVALID_OPERATION} is generated if @code{glBitmap} is executed | |
914 | between the execution of @code{glBegin} and the corresponding execution | |
915 | of @code{glEnd}. | |
916 | ||
bb894c9d | 917 | @end deftypefun |
8925f36f | 918 | |
bb894c9d | 919 | @deftypefun void glBlendColor red green blue alpha |
3c9b6116 AW |
920 | Set the blend color. |
921 | ||
8925f36f AW |
922 | @table @asis |
923 | @item @var{red} | |
924 | @itemx @var{green} | |
925 | @itemx @var{blue} | |
926 | @itemx @var{alpha} | |
927 | specify the components of @code{GL_BLEND_COLOR} | |
928 | ||
929 | @end table | |
930 | ||
8925f36f AW |
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 | |
3c9b6116 | 933 | range @r{[0,1]} before being stored. See @code{glBlendFunc} for a |
8925f36f AW |
934 | complete description of the blending operations. Initially the |
935 | @code{GL_BLEND_COLOR} is set to (0, 0, 0, 0). | |
936 | ||
8925f36f AW |
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}. | |
940 | ||
941 | ||
942 | ||
bb894c9d | 943 | @end deftypefun |
8925f36f | 944 | |
bb894c9d | 945 | @deftypefun void glBlendEquationSeparate modeRGB modeAlpha |
3c9b6116 AW |
946 | Set the RGB blend equation and the alpha blend equation separately. |
947 | ||
8925f36f AW |
948 | @table @asis |
949 | @item @var{modeRGB} | |
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}. | |
954 | ||
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}. | |
960 | ||
961 | @end table | |
962 | ||
8925f36f AW |
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. | |
967 | ||
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. | |
972 | ||
973 | In the equations that follow, source and destination color components | |
974 | are referred to as | |
3c9b6116 AW |
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})}, | |
8925f36f | 977 | respectively. The result color is referred to as |
3c9b6116 AW |
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})}, | |
8925f36f | 982 | respectively. For these equations all color components are understood to |
3c9b6116 | 983 | have values in the range @r{[0,1]}. |
8925f36f AW |
984 | |
985 | @table @asis | |
986 | @item @strong{Mode} | |
987 | @strong{RGB Components}, @strong{Alpha Component} | |
988 | ||
989 | @item @code{GL_FUNC_ADD} | |
3c9b6116 AW |
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}} | |
8925f36f AW |
992 | |
993 | @item @code{GL_FUNC_SUBTRACT} | |
3c9b6116 AW |
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}} | |
8925f36f AW |
996 | |
997 | @item @code{GL_FUNC_REVERSE_SUBTRACT} | |
3c9b6116 AW |
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}} | |
8925f36f AW |
1000 | |
1001 | @item @code{GL_MIN} | |
3c9b6116 AW |
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})} | |
8925f36f AW |
1004 | |
1005 | @item @code{GL_MAX} | |
3c9b6116 AW |
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})} | |
8925f36f AW |
1008 | |
1009 | @end table | |
1010 | ||
3c9b6116 | 1011 | The results of these equations are clamped to the range @r{[0,1]}. |
8925f36f AW |
1012 | |
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. | |
1017 | ||
1018 | Initially, both the RGB blend equation and the alpha blend equation are | |
1019 | set to @code{GL_FUNC_ADD}. | |
1020 | ||
1021 | ||
1022 | ||
8925f36f AW |
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}, | |
1026 | or @code{GL_MIN}. | |
1027 | ||
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}. | |
1031 | ||
bb894c9d | 1032 | @end deftypefun |
8925f36f | 1033 | |
bb894c9d | 1034 | @deftypefun void glBlendEquation mode |
3c9b6116 AW |
1035 | Specify the equation used for both the RGB blend equation and the Alpha |
1036 | blend equation. | |
1037 | ||
8925f36f AW |
1038 | @table @asis |
1039 | @item @var{mode} | |
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}. | |
1043 | ||
1044 | @end table | |
1045 | ||
8925f36f AW |
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. | |
1050 | ||
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. | |
1055 | ||
1056 | In the equations that follow, source and destination color components | |
1057 | are referred to as | |
3c9b6116 AW |
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})}, | |
8925f36f | 1060 | respectively. The result color is referred to as |
3c9b6116 AW |
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})}, | |
8925f36f | 1065 | respectively. For these equations all color components are understood to |
3c9b6116 | 1066 | have values in the range @r{[0,1]}. |
8925f36f AW |
1067 | |
1068 | @table @asis | |
1069 | @item @strong{Mode} | |
1070 | @strong{RGB Components}, @strong{Alpha Component} | |
1071 | ||
1072 | @item @code{GL_FUNC_ADD} | |
3c9b6116 AW |
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}} | |
8925f36f AW |
1075 | |
1076 | @item @code{GL_FUNC_SUBTRACT} | |
3c9b6116 AW |
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}} | |
8925f36f AW |
1079 | |
1080 | @item @code{GL_FUNC_REVERSE_SUBTRACT} | |
3c9b6116 AW |
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}} | |
8925f36f AW |
1083 | |
1084 | @item @code{GL_MIN} | |
3c9b6116 AW |
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})} | |
8925f36f AW |
1087 | |
1088 | @item @code{GL_MAX} | |
3c9b6116 AW |
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})} | |
8925f36f AW |
1091 | |
1092 | @end table | |
1093 | ||
3c9b6116 | 1094 | The results of these equations are clamped to the range @r{[0,1]}. |
8925f36f AW |
1095 | |
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. | |
1100 | ||
1101 | Initially, both the RGB blend equation and the alpha blend equation are | |
1102 | set to @code{GL_FUNC_ADD}. | |
1103 | ||
1104 | ||
1105 | ||
8925f36f AW |
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}. | |
1109 | ||
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}. | |
1113 | ||
bb894c9d | 1114 | @end deftypefun |
8925f36f | 1115 | |
bb894c9d | 1116 | @deftypefun void glBlendFuncSeparate srcRGB dstRGB srcAlpha dstAlpha |
3c9b6116 AW |
1117 | Specify pixel arithmetic for RGB and alpha components separately. |
1118 | ||
8925f36f AW |
1119 | @table @asis |
1120 | @item @var{srcRGB} | |
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}. | |
1130 | ||
1131 | @item @var{dstRGB} | |
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}. | |
1140 | ||
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 | |
1144 | is @code{GL_ONE}. | |
1145 | ||
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}. | |
1150 | ||
1151 | @end table | |
1152 | ||
8925f36f AW |
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. | |
1158 | ||
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. | |
1168 | ||
1169 | In the table and in subsequent equations, source and destination color | |
1170 | components are referred to as | |
3c9b6116 AW |
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})}. | |
8925f36f | 1175 | They are understood to have integer values between 0 and |
3c9b6116 | 1176 | @r{(@var{k}_@var{R},@var{k}_@var{G}@var{k}_@var{B}@var{k}_@var{A})}, |
8925f36f AW |
1177 | where |
1178 | ||
3c9b6116 | 1179 | @r{@var{k}_@var{c}=2^@var{m}_@var{c},-1} |
8925f36f | 1180 | |
3c9b6116 | 1181 | and @r{(@var{m}_@var{R},@var{m}_@var{G}@var{m}_@var{B}@var{m}_@var{A})} |
8925f36f AW |
1182 | is the number of red, green, blue, and alpha bitplanes. |
1183 | ||
1184 | Source and destination scale factors are referred to as | |
3c9b6116 AW |
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]}. | |
8925f36f AW |
1188 | |
1189 | ||
1190 | ||
1191 | @table @asis | |
1192 | @item @strong{Parameter} | |
1193 | @strong{RGB Factor}, @strong{Alpha Factor} | |
1194 | ||
1195 | @item @code{GL_ZERO} | |
3c9b6116 | 1196 | @r{(0,00)}, @r{0} |
8925f36f AW |
1197 | |
1198 | @item @code{GL_ONE} | |
3c9b6116 | 1199 | @r{(1,11)}, @r{1} |
8925f36f AW |
1200 | |
1201 | @item @code{GL_SRC_COLOR} | |
3c9b6116 AW |
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}} | |
8925f36f AW |
1204 | |
1205 | @item @code{GL_ONE_MINUS_SRC_COLOR} | |
3c9b6116 AW |
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}} | |
8925f36f AW |
1208 | |
1209 | @item @code{GL_DST_COLOR} | |
3c9b6116 AW |
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}} | |
8925f36f AW |
1212 | |
1213 | @item @code{GL_ONE_MINUS_DST_COLOR} | |
3c9b6116 AW |
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}} | |
8925f36f AW |
1216 | |
1217 | @item @code{GL_SRC_ALPHA} | |
3c9b6116 AW |
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}} | |
8925f36f AW |
1220 | |
1221 | @item @code{GL_ONE_MINUS_SRC_ALPHA} | |
3c9b6116 AW |
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}} | |
8925f36f AW |
1224 | |
1225 | @item @code{GL_DST_ALPHA} | |
3c9b6116 AW |
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}} | |
8925f36f AW |
1228 | |
1229 | @item @code{GL_ONE_MINUS_DST_ALPHA} | |
3c9b6116 AW |
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}} | |
8925f36f AW |
1232 | |
1233 | @item @code{GL_CONSTANT_COLOR} | |
3c9b6116 AW |
1234 | @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c})}, |
1235 | @r{@var{A}_@var{c}} | |
8925f36f AW |
1236 | |
1237 | @item @code{GL_ONE_MINUS_CONSTANT_COLOR} | |
3c9b6116 AW |
1238 | @r{(1,11)-(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c})}, |
1239 | @r{1-@var{A}_@var{c}} | |
8925f36f AW |
1240 | |
1241 | @item @code{GL_CONSTANT_ALPHA} | |
3c9b6116 AW |
1242 | @r{(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c})}, |
1243 | @r{@var{A}_@var{c}} | |
8925f36f AW |
1244 | |
1245 | @item @code{GL_ONE_MINUS_CONSTANT_ALPHA} | |
3c9b6116 AW |
1246 | @r{(1,11)-(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c})}, |
1247 | @r{1-@var{A}_@var{c}} | |
8925f36f AW |
1248 | |
1249 | @item @code{GL_SRC_ALPHA_SATURATE} | |
3c9b6116 | 1250 | @r{(@var{i},@var{i}@var{i})}, @r{1} |
8925f36f AW |
1251 | |
1252 | @end table | |
1253 | ||
1254 | In the table, | |
1255 | ||
3c9b6116 | 1256 | @r{@var{i}=@var{min}(@var{A}_@var{s},1-@var{A}_@var{d},)} |
8925f36f AW |
1257 | |
1258 | To determine the blended RGBA values of a pixel when drawing in RGBA | |
1259 | mode, the system uses the following equations: | |
1260 | ||
3c9b6116 | 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})} |
8925f36f AW |
1262 | |
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 | |
3c9b6116 AW |
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: | |
8925f36f | 1271 | |
3c9b6116 | 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}} |
8925f36f AW |
1273 | |
1274 | ||
1275 | ||
8925f36f AW |
1276 | @code{GL_INVALID_ENUM} is generated if either @var{srcRGB} or |
1277 | @var{dstRGB} is not an accepted value. | |
1278 | ||
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}. | |
1282 | ||
bb894c9d | 1283 | @end deftypefun |
8925f36f | 1284 | |
bb894c9d | 1285 | @deftypefun void glBlendFunc sfactor dfactor |
3c9b6116 AW |
1286 | Specify pixel arithmetic. |
1287 | ||
8925f36f AW |
1288 | @table @asis |
1289 | @item @var{sfactor} | |
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}. | |
1300 | ||
1301 | @item @var{dfactor} | |
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}. | |
1311 | ||
1312 | @end table | |
1313 | ||
8925f36f AW |
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. | |
1319 | ||
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 | |
3c9b6116 AW |
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})}. | |
8925f36f | 1331 | They are understood to have integer values between 0 and |
3c9b6116 | 1332 | @r{(@var{k}_@var{R},@var{k}_@var{G}@var{k}_@var{B}@var{k}_@var{A})}, |
8925f36f AW |
1333 | where |
1334 | ||
3c9b6116 | 1335 | @r{@var{k}_@var{c}=2^@var{m}_@var{c},-1} |
8925f36f | 1336 | |
3c9b6116 | 1337 | and @r{(@var{m}_@var{R},@var{m}_@var{G}@var{m}_@var{B}@var{m}_@var{A})} |
8925f36f AW |
1338 | is the number of red, green, blue, and alpha bitplanes. |
1339 | ||
1340 | Source and destination scale factors are referred to as | |
3c9b6116 AW |
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})}, | |
8925f36f | 1345 | represent either source or destination factors. All scale factors have |
3c9b6116 | 1346 | range @r{[0,1]}. |
8925f36f AW |
1347 | |
1348 | ||
1349 | ||
1350 | @table @asis | |
1351 | @item @strong{Parameter} | |
3c9b6116 | 1352 | @strong{@r{(@var{f}_@var{R},@var{f}_@var{G}@var{f}_@var{B}@var{f}_@var{A})}} |
8925f36f AW |
1353 | |
1354 | @item @code{GL_ZERO} | |
3c9b6116 | 1355 | @r{(0,000)} |
8925f36f AW |
1356 | |
1357 | @item @code{GL_ONE} | |
3c9b6116 | 1358 | @r{(1,111)} |
8925f36f AW |
1359 | |
1360 | @item @code{GL_SRC_COLOR} | |
3c9b6116 | 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})} |
8925f36f AW |
1362 | |
1363 | @item @code{GL_ONE_MINUS_SRC_COLOR} | |
3c9b6116 | 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})} |
8925f36f AW |
1365 | |
1366 | @item @code{GL_DST_COLOR} | |
3c9b6116 | 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})} |
8925f36f AW |
1368 | |
1369 | @item @code{GL_ONE_MINUS_DST_COLOR} | |
3c9b6116 | 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})} |
8925f36f AW |
1371 | |
1372 | @item @code{GL_SRC_ALPHA} | |
3c9b6116 | 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})} |
8925f36f AW |
1374 | |
1375 | @item @code{GL_ONE_MINUS_SRC_ALPHA} | |
3c9b6116 | 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})} |
8925f36f AW |
1377 | |
1378 | @item @code{GL_DST_ALPHA} | |
3c9b6116 | 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})} |
8925f36f AW |
1380 | |
1381 | @item @code{GL_ONE_MINUS_DST_ALPHA} | |
3c9b6116 | 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})} |
8925f36f AW |
1383 | |
1384 | @item @code{GL_CONSTANT_COLOR} | |
3c9b6116 | 1385 | @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})} |
8925f36f AW |
1386 | |
1387 | @item @code{GL_ONE_MINUS_CONSTANT_COLOR} | |
3c9b6116 | 1388 | @r{(1,111)-(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})} |
8925f36f AW |
1389 | |
1390 | @item @code{GL_CONSTANT_ALPHA} | |
3c9b6116 | 1391 | @r{(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c}@var{A}_@var{c})} |
8925f36f AW |
1392 | |
1393 | @item @code{GL_ONE_MINUS_CONSTANT_ALPHA} | |
3c9b6116 | 1394 | @r{(1,111)-(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c}@var{A}_@var{c})} |
8925f36f AW |
1395 | |
1396 | @item @code{GL_SRC_ALPHA_SATURATE} | |
3c9b6116 | 1397 | @r{(@var{i},@var{i}@var{i}1)} |
8925f36f AW |
1398 | |
1399 | @end table | |
1400 | ||
1401 | In the table, | |
1402 | ||
3c9b6116 | 1403 | @r{@var{i}=@var{min}(@var{A}_@var{s},@var{k}_@var{A}-@var{A}_@var{d})/@var{k}_@var{A}} |
8925f36f AW |
1404 | |
1405 | To determine the blended RGBA values of a pixel when drawing in RGBA | |
1406 | mode, the system uses the following equations: | |
1407 | ||
3c9b6116 | 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})} |
8925f36f AW |
1409 | |
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 | |
3c9b6116 AW |
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: | |
8925f36f | 1418 | |
3c9b6116 | 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}} |
8925f36f AW |
1420 | |
1421 | ||
1422 | ||
8925f36f AW |
1423 | @code{GL_INVALID_ENUM} is generated if either @var{sfactor} or |
1424 | @var{dfactor} is not an accepted value. | |
1425 | ||
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}. | |
1429 | ||
bb894c9d | 1430 | @end deftypefun |
8925f36f | 1431 | |
bb894c9d | 1432 | @deftypefun void glBufferData target size data usage |
3c9b6116 AW |
1433 | Creates and initializes a buffer object's data store. |
1434 | ||
8925f36f AW |
1435 | @table @asis |
1436 | @item @var{target} | |
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}. | |
1440 | ||
1441 | @item @var{size} | |
1442 | Specifies the size in bytes of the buffer object's new data store. | |
1443 | ||
1444 | @item @var{data} | |
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. | |
1447 | ||
1448 | @item @var{usage} | |
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}. | |
1454 | ||
1455 | @end table | |
1456 | ||
8925f36f AW |
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}. | |
1464 | ||
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: | |
1472 | ||
1473 | @table @asis | |
1474 | @item STREAM | |
1475 | The data store contents will be modified once and used at most a few | |
1476 | times. | |
1477 | ||
1478 | @item STATIC | |
1479 | The data store contents will be modified once and used many times. | |
1480 | ||
1481 | @item DYNAMIC | |
1482 | The data store contents will be modified repeatedly and used many times. | |
1483 | ||
1484 | @end table | |
1485 | ||
1486 | The nature of access may be one of these: | |
1487 | ||
1488 | @table @asis | |
1489 | @item DRAW | |
1490 | The data store contents are modified by the application, and used as the | |
1491 | source for GL drawing and image specification commands. | |
1492 | ||
1493 | @item READ | |
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. | |
1496 | ||
1497 | @item COPY | |
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. | |
1500 | ||
1501 | @end table | |
1502 | ||
8925f36f AW |
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}. | |
1506 | ||
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}. | |
1512 | ||
1513 | @code{GL_INVALID_VALUE} is generated if @var{size} is negative. | |
1514 | ||
1515 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
1516 | name 0 is bound to @var{target}. | |
1517 | ||
1518 | @code{GL_OUT_OF_MEMORY} is generated if the GL is unable to create a | |
1519 | data store with the specified @var{size}. | |
1520 | ||
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}. | |
1524 | ||
bb894c9d | 1525 | @end deftypefun |
8925f36f | 1526 | |
bb894c9d | 1527 | @deftypefun void glBufferSubData target offset size data |
3c9b6116 AW |
1528 | Updates a subset of a buffer object's data store. |
1529 | ||
8925f36f AW |
1530 | @table @asis |
1531 | @item @var{target} | |
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}. | |
1535 | ||
1536 | @item @var{offset} | |
1537 | Specifies the offset into the buffer object's data store where data | |
1538 | replacement will begin, measured in bytes. | |
1539 | ||
1540 | @item @var{size} | |
1541 | Specifies the size in bytes of the data store region being replaced. | |
1542 | ||
1543 | @item @var{data} | |
1544 | Specifies a pointer to the new data that will be copied into the data | |
1545 | store. | |
1546 | ||
1547 | @end table | |
1548 | ||
8925f36f AW |
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. | |
1555 | ||
8925f36f AW |
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}. | |
1559 | ||
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. | |
1563 | ||
1564 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
1565 | name 0 is bound to @var{target}. | |
1566 | ||
1567 | @code{GL_INVALID_OPERATION} is generated if the buffer object being | |
1568 | updated is mapped. | |
1569 | ||
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}. | |
1573 | ||
bb894c9d | 1574 | @end deftypefun |
8925f36f | 1575 | |
bb894c9d | 1576 | @deftypefun void glCallLists n type lists |
3c9b6116 AW |
1577 | Execute a list of display lists. |
1578 | ||
8925f36f AW |
1579 | @table @asis |
1580 | @item @var{n} | |
1581 | Specifies the number of display lists to be executed. | |
1582 | ||
1583 | @item @var{type} | |
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. | |
1589 | ||
1590 | @item @var{lists} | |
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}. | |
1594 | ||
1595 | @end table | |
1596 | ||
8925f36f AW |
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 | |
1601 | are ignored. | |
1602 | ||
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: | |
1606 | ||
1607 | @table @asis | |
1608 | @item @code{GL_BYTE} | |
1609 | @var{lists} is treated as an array of signed bytes, each in the range | |
3c9b6116 | 1610 | @r{-128} through 127. |
8925f36f AW |
1611 | |
1612 | @item @code{GL_UNSIGNED_BYTE} | |
1613 | @var{lists} is treated as an array of unsigned bytes, each in the range | |
1614 | 0 through 255. | |
1615 | ||
1616 | @item @code{GL_SHORT} | |
1617 | @var{lists} is treated as an array of signed two-byte integers, each in | |
3c9b6116 | 1618 | the range @r{-32768} through 32767. |
8925f36f AW |
1619 | |
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. | |
1623 | ||
1624 | @item @code{GL_INT} | |
1625 | @var{lists} is treated as an array of signed four-byte integers. | |
1626 | ||
1627 | @item @code{GL_UNSIGNED_INT} | |
1628 | @var{lists} is treated as an array of unsigned four-byte integers. | |
1629 | ||
1630 | @item @code{GL_FLOAT} | |
1631 | @var{lists} is treated as an array of four-byte floating-point values. | |
1632 | ||
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. | |
1638 | ||
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 | |
1644 | the third byte. | |
1645 | ||
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 | |
1652 | byte. | |
1653 | ||
1654 | @end table | |
1655 | ||
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}. | |
1658 | ||
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. | |
1663 | ||
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. | |
1669 | ||
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. | |
1675 | ||
8925f36f AW |
1676 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
1677 | ||
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}, | |
1682 | @code{GL_4_BYTES}. | |
1683 | ||
bb894c9d | 1684 | @end deftypefun |
8925f36f | 1685 | |
bb894c9d | 1686 | @deftypefun void glCallList list |
3c9b6116 AW |
1687 | Execute a display list. |
1688 | ||
8925f36f AW |
1689 | @table @asis |
1690 | @item @var{list} | |
1691 | Specifies the integer name of the display list to be executed. | |
1692 | ||
1693 | @end table | |
1694 | ||
8925f36f AW |
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. | |
1699 | ||
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. | |
1705 | ||
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. | |
1711 | ||
bb894c9d | 1712 | @end deftypefun |
8925f36f | 1713 | |
bb894c9d | 1714 | @deftypefun void glClearAccum red green blue alpha |
3c9b6116 AW |
1715 | Specify clear values for the accumulation buffer. |
1716 | ||
8925f36f AW |
1717 | @table @asis |
1718 | @item @var{red} | |
1719 | @itemx @var{green} | |
1720 | @itemx @var{blue} | |
1721 | @itemx @var{alpha} | |
1722 | Specify the red, green, blue, and alpha values used when the | |
1723 | accumulation buffer is cleared. The initial values are all 0. | |
1724 | ||
1725 | @end table | |
1726 | ||
8925f36f AW |
1727 | @code{glClearAccum} specifies the red, green, blue, and alpha values |
1728 | used by @code{glClear} to clear the accumulation buffer. | |
1729 | ||
1730 | Values specified by @code{glClearAccum} are clamped to the range | |
3c9b6116 | 1731 | @r{[-1,1]}. |
8925f36f | 1732 | |
8925f36f AW |
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}. | |
1736 | ||
bb894c9d | 1737 | @end deftypefun |
8925f36f | 1738 | |
bb894c9d | 1739 | @deftypefun void glClearColor red green blue alpha |
3c9b6116 AW |
1740 | Specify clear values for the color buffers. |
1741 | ||
8925f36f AW |
1742 | @table @asis |
1743 | @item @var{red} | |
1744 | @itemx @var{green} | |
1745 | @itemx @var{blue} | |
1746 | @itemx @var{alpha} | |
1747 | Specify the red, green, blue, and alpha values used when the color | |
1748 | buffers are cleared. The initial values are all 0. | |
1749 | ||
1750 | @end table | |
1751 | ||
8925f36f AW |
1752 | @code{glClearColor} specifies the red, green, blue, and alpha values |
1753 | used by @code{glClear} to clear the color buffers. Values specified by | |
3c9b6116 | 1754 | @code{glClearColor} are clamped to the range @r{[0,1]}. |
8925f36f | 1755 | |
8925f36f AW |
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}. | |
1759 | ||
bb894c9d | 1760 | @end deftypefun |
8925f36f | 1761 | |
bb894c9d | 1762 | @deftypefun void glClearDepth depth |
3c9b6116 AW |
1763 | Specify the clear value for the depth buffer. |
1764 | ||
8925f36f AW |
1765 | @table @asis |
1766 | @item @var{depth} | |
1767 | Specifies the depth value used when the depth buffer is cleared. The | |
1768 | initial value is 1. | |
1769 | ||
1770 | @end table | |
1771 | ||
8925f36f AW |
1772 | @code{glClearDepth} specifies the depth value used by @code{glClear} to |
1773 | clear the depth buffer. Values specified by @code{glClearDepth} are | |
3c9b6116 | 1774 | clamped to the range @r{[0,1]}. |
8925f36f | 1775 | |
8925f36f AW |
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}. | |
1779 | ||
bb894c9d | 1780 | @end deftypefun |
8925f36f | 1781 | |
bb894c9d | 1782 | @deftypefun void glClearIndex c |
3c9b6116 AW |
1783 | Specify the clear value for the color index buffers. |
1784 | ||
8925f36f AW |
1785 | @table @asis |
1786 | @item @var{c} | |
1787 | Specifies the index used when the color index buffers are cleared. The | |
1788 | initial value is 0. | |
1789 | ||
1790 | @end table | |
1791 | ||
8925f36f AW |
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 | |
3c9b6116 AW |
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. | |
8925f36f | 1798 | |
8925f36f AW |
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}. | |
1802 | ||
bb894c9d | 1803 | @end deftypefun |
8925f36f | 1804 | |
bb894c9d | 1805 | @deftypefun void glClearStencil s |
3c9b6116 AW |
1806 | Specify the clear value for the stencil buffer. |
1807 | ||
8925f36f AW |
1808 | @table @asis |
1809 | @item @var{s} | |
1810 | Specifies the index used when the stencil buffer is cleared. The initial | |
1811 | value is 0. | |
1812 | ||
1813 | @end table | |
1814 | ||
8925f36f | 1815 | @code{glClearStencil} specifies the index used by @code{glClear} to |
3c9b6116 AW |
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. | |
8925f36f | 1818 | |
8925f36f AW |
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}. | |
1822 | ||
bb894c9d | 1823 | @end deftypefun |
8925f36f | 1824 | |
bb894c9d | 1825 | @deftypefun void glClear mask |
3c9b6116 AW |
1826 | Clear buffers to preset values. |
1827 | ||
8925f36f AW |
1828 | @table @asis |
1829 | @item @var{mask} | |
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}. | |
1833 | ||
1834 | @end table | |
1835 | ||
8925f36f AW |
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}. | |
1841 | ||
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 | |
1846 | by @code{glClear}. | |
1847 | ||
1848 | @code{glClear} takes a single argument that is the bitwise OR of several | |
1849 | values indicating which buffer is to be cleared. | |
1850 | ||
1851 | The values are as follows: | |
1852 | ||
1853 | @table @asis | |
1854 | @item @code{GL_COLOR_BUFFER_BIT} | |
1855 | Indicates the buffers currently enabled for color writing. | |
1856 | ||
1857 | @item @code{GL_DEPTH_BUFFER_BIT} | |
1858 | Indicates the depth buffer. | |
1859 | ||
1860 | @item @code{GL_ACCUM_BUFFER_BIT} | |
1861 | Indicates the accumulation buffer. | |
1862 | ||
1863 | @item @code{GL_STENCIL_BUFFER_BIT} | |
1864 | Indicates the stencil buffer. | |
1865 | ||
1866 | @end table | |
1867 | ||
1868 | The value to which each buffer is cleared depends on the setting of the | |
1869 | clear value for that buffer. | |
1870 | ||
8925f36f AW |
1871 | @code{GL_INVALID_VALUE} is generated if any bit other than the four |
1872 | defined bits is set in @var{mask}. | |
1873 | ||
1874 | @code{GL_INVALID_OPERATION} is generated if @code{glClear} is executed | |
1875 | between the execution of @code{glBegin} and the corresponding execution | |
1876 | of @code{glEnd}. | |
1877 | ||
bb894c9d | 1878 | @end deftypefun |
8925f36f | 1879 | |
bb894c9d | 1880 | @deftypefun void glClientActiveTexture texture |
3c9b6116 AW |
1881 | Select active texture unit. |
1882 | ||
8925f36f AW |
1883 | @table @asis |
1884 | @item @var{texture} | |
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} | |
3c9b6116 | 1887 | must be one of @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to |
8925f36f AW |
1888 | the value of @code{GL_MAX_TEXTURE_COORDS} - 1, which is an |
1889 | implementation-dependent value. The initial value is @code{GL_TEXTURE0}. | |
1890 | ||
1891 | @end table | |
1892 | ||
8925f36f AW |
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}. | |
1898 | ||
8925f36f | 1899 | @code{GL_INVALID_ENUM} is generated if @var{texture} is not one of |
3c9b6116 | 1900 | @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to the value of |
8925f36f AW |
1901 | @code{GL_MAX_TEXTURE_COORDS} - 1. |
1902 | ||
bb894c9d | 1903 | @end deftypefun |
8925f36f | 1904 | |
bb894c9d | 1905 | @deftypefun void glClipPlane plane equation |
3c9b6116 AW |
1906 | Specify a plane against which all geometry is clipped. |
1907 | ||
8925f36f AW |
1908 | @table @asis |
1909 | @item @var{plane} | |
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 | |
3c9b6116 | 1912 | between 0 and @code{GL_MAX_CLIP_PLANES}@r{-1}, are accepted. |
8925f36f AW |
1913 | |
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. | |
1917 | ||
1918 | @end table | |
1919 | ||
8925f36f AW |
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. | |
1929 | ||
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}. | |
1938 | ||
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. | |
1942 | ||
1943 | All clipping planes are initially defined as (0, 0, 0, 0) in eye | |
1944 | coordinates and are disabled. | |
1945 | ||
8925f36f AW |
1946 | @code{GL_INVALID_ENUM} is generated if @var{plane} is not an accepted |
1947 | value. | |
1948 | ||
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}. | |
1952 | ||
bb894c9d | 1953 | @end deftypefun |
8925f36f | 1954 | |
bb894c9d | 1955 | @deftypefun void glColorMask red green blue alpha |
3c9b6116 AW |
1956 | Enable and disable writing of frame buffer color components. |
1957 | ||
8925f36f AW |
1958 | @table @asis |
1959 | @item @var{red} | |
1960 | @itemx @var{green} | |
1961 | @itemx @var{blue} | |
1962 | @itemx @var{alpha} | |
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. | |
1966 | ||
1967 | @end table | |
1968 | ||
8925f36f AW |
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. | |
1974 | ||
1975 | Changes to individual bits of components cannot be controlled. Rather, | |
1976 | changes are either enabled or disabled for entire color components. | |
1977 | ||
8925f36f AW |
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}. | |
1981 | ||
bb894c9d | 1982 | @end deftypefun |
8925f36f | 1983 | |
bb894c9d | 1984 | @deftypefun void glColorMaterial face mode |
3c9b6116 AW |
1985 | Cause a material color to track the current color. |
1986 | ||
8925f36f AW |
1987 | @table @asis |
1988 | @item @var{face} | |
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}. | |
1993 | ||
1994 | @item @var{mode} | |
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}. | |
2000 | ||
2001 | @end table | |
2002 | ||
8925f36f AW |
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. | |
2007 | ||
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. | |
2011 | ||
8925f36f AW |
2012 | @code{GL_INVALID_ENUM} is generated if @var{face} or @var{mode} is not |
2013 | an accepted value. | |
2014 | ||
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}. | |
2018 | ||
bb894c9d | 2019 | @end deftypefun |
8925f36f | 2020 | |
bb894c9d | 2021 | @deftypefun void glColorPointer size type stride pointer |
3c9b6116 AW |
2022 | Define an array of colors. |
2023 | ||
8925f36f AW |
2024 | @table @asis |
2025 | @item @var{size} | |
2026 | Specifies the number of components per color. Must be 3 or 4. The | |
2027 | initial value is 4. | |
2028 | ||
2029 | @item @var{type} | |
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 | |
2034 | @code{GL_FLOAT}. | |
2035 | ||
2036 | @item @var{stride} | |
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 | |
2039 | initial value is 0. | |
2040 | ||
2041 | @item @var{pointer} | |
2042 | Specifies a pointer to the first component of the first color element in | |
2043 | the array. The initial value is 0. | |
2044 | ||
2045 | @end table | |
2046 | ||
8925f36f AW |
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}.) | |
2055 | ||
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}). | |
2062 | ||
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. | |
2066 | ||
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. | |
2073 | ||
8925f36f AW |
2074 | @code{GL_INVALID_VALUE} is generated if @var{size} is not 3 or 4. |
2075 | ||
2076 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted | |
2077 | value. | |
2078 | ||
2079 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
2080 | ||
bb894c9d | 2081 | @end deftypefun |
8925f36f | 2082 | |
bb894c9d | 2083 | @deftypefun void glColorSubTable target start count format type data |
3c9b6116 AW |
2084 | Respecify a portion of a color table. |
2085 | ||
8925f36f AW |
2086 | @table @asis |
2087 | @item @var{target} | |
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}. | |
2091 | ||
2092 | @item @var{start} | |
2093 | The starting index of the portion of the color table to be replaced. | |
2094 | ||
2095 | @item @var{count} | |
2096 | The number of table entries to replace. | |
2097 | ||
2098 | @item @var{format} | |
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}. | |
2103 | ||
2104 | @item @var{type} | |
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}. | |
2115 | ||
2116 | @item @var{data} | |
2117 | Pointer to a one-dimensional array of pixel data that is processed to | |
2118 | replace the specified region of the color table. | |
2119 | ||
2120 | @end table | |
2121 | ||
8925f36f AW |
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 | |
3c9b6116 | 2125 | indices @var{start} to @r{@var{start}+@var{count}-1}, inclusive. This |
8925f36f AW |
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. | |
2129 | ||
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. | |
2134 | ||
8925f36f AW |
2135 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
2136 | allowable values. | |
2137 | ||
2138 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
2139 | allowable values. | |
2140 | ||
2141 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
2142 | allowable values. | |
2143 | ||
2144 | @code{GL_INVALID_VALUE} is generated if | |
3c9b6116 | 2145 | @r{@var{start}+@var{count}>@var{width}}. |
8925f36f AW |
2146 | |
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. | |
2150 | ||
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. | |
2155 | ||
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}. | |
2160 | ||
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}. | |
2164 | ||
bb894c9d | 2165 | @end deftypefun |
8925f36f | 2166 | |
b002944d AW |
2167 | @deftypefun void glColorTableParameterfv target pname params |
2168 | @deftypefunx void glColorTableParameteriv target pname params | |
2169 | Set color lookup table parameters. | |
2170 | ||
2171 | @table @asis | |
2172 | @item @var{target} | |
2173 | The target color table. Must be @code{GL_COLOR_TABLE}, | |
2174 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or | |
2175 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
2176 | ||
2177 | @item @var{pname} | |
2178 | The symbolic name of a texture color lookup table parameter. Must be one | |
2179 | of @code{GL_COLOR_TABLE_SCALE} or @code{GL_COLOR_TABLE_BIAS}. | |
2180 | ||
2181 | @item @var{params} | |
2182 | A pointer to an array where the values of the parameters are stored. | |
2183 | ||
2184 | @end table | |
2185 | ||
2186 | @code{glColorTableParameter} is used to specify the scale factors and | |
2187 | bias terms applied to color components when they are loaded into a color | |
2188 | table. @var{target} indicates which color table the scale and bias terms | |
2189 | apply to; it must be set to @code{GL_COLOR_TABLE}, | |
2190 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or | |
2191 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
2192 | ||
2193 | @var{pname} must be @code{GL_COLOR_TABLE_SCALE} to set the scale | |
2194 | factors. In this case, @var{params} points to an array of four values, | |
2195 | which are the scale factors for red, green, blue, and alpha, in that | |
2196 | order. | |
2197 | ||
2198 | @var{pname} must be @code{GL_COLOR_TABLE_BIAS} to set the bias terms. In | |
2199 | this case, @var{params} points to an array of four values, which are the | |
2200 | bias terms for red, green, blue, and alpha, in that order. | |
2201 | ||
2202 | The color tables themselves are specified by calling | |
2203 | @code{glColorTable}. | |
2204 | ||
2205 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
2206 | not an acceptable value. | |
2207 | ||
2208 | @code{GL_INVALID_OPERATION} is generated if @code{glColorTableParameter} | |
2209 | is executed between the execution of @code{glBegin} and the | |
2210 | corresponding execution of @code{glEnd}. | |
2211 | ||
2212 | @end deftypefun | |
2213 | ||
bb894c9d | 2214 | @deftypefun void glColorTable target internalformat width format type data |
3c9b6116 AW |
2215 | Define a color lookup table. |
2216 | ||
8925f36f AW |
2217 | @table @asis |
2218 | @item @var{target} | |
2219 | Must be one of @code{GL_COLOR_TABLE}, | |
2220 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, | |
2221 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{GL_PROXY_COLOR_TABLE}, | |
2222 | @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or | |
2223 | @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}. | |
2224 | ||
2225 | @item @var{internalformat} | |
2226 | The internal format of the color table. The allowable values are | |
2227 | @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, | |
2228 | @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
2229 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
2230 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
2231 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
2232 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
2233 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY}, | |
2234 | @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12}, | |
2235 | @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
2236 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
2237 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
2238 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
2239 | @code{GL_RGBA12}, and @code{GL_RGBA16}. | |
2240 | ||
2241 | @item @var{width} | |
2242 | The number of entries in the color lookup table specified by @var{data}. | |
2243 | ||
2244 | @item @var{format} | |
2245 | The format of the pixel data in @var{data}. The allowable values are | |
2246 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, | |
2247 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, | |
2248 | @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}. | |
2249 | ||
2250 | @item @var{type} | |
2251 | The type of the pixel data in @var{data}. The allowable values are | |
2252 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT}, | |
2253 | @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT}, | |
2254 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
2255 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
2256 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
2257 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
2258 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
2259 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
2260 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
2261 | ||
2262 | @item @var{data} | |
2263 | Pointer to a one-dimensional array of pixel data that is processed to | |
2264 | build the color table. | |
2265 | ||
2266 | @end table | |
2267 | ||
8925f36f AW |
2268 | @code{glColorTable} may be used in two ways: to test the actual size and |
2269 | color resolution of a lookup table given a particular set of parameters, | |
2270 | or to load the contents of a color lookup table. Use the targets | |
2271 | @code{GL_PROXY_*} for the first case and the other targets for the | |
2272 | second case. | |
2273 | ||
2274 | If a non-zero named buffer object is bound to the | |
2275 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2276 | color table is specified, @var{data} is treated as a byte offset into | |
2277 | the buffer object's data store. | |
2278 | ||
2279 | If @var{target} is @code{GL_COLOR_TABLE}, | |
2280 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or | |
2281 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{glColorTable} builds a | |
2282 | color lookup table from an array of pixels. The pixel array specified by | |
2283 | @var{width}, @var{format}, @var{type}, and @var{data} is extracted from | |
2284 | memory and processed just as if @code{glDrawPixels} were called, but | |
2285 | processing stops after the final expansion to RGBA is completed. | |
2286 | ||
2287 | The four scale parameters and the four bias parameters that are defined | |
2288 | for the table are then used to scale and bias the R, G, B, and A | |
2289 | components of each pixel. (Use @code{glColorTableParameter} to set these | |
2290 | scale and bias parameters.) | |
2291 | ||
3c9b6116 AW |
2292 | Next, the R, G, B, and A values are clamped to the range @r{[0,1]}. Each |
2293 | pixel is then converted to the internal format specified by | |
8925f36f AW |
2294 | @var{internalformat}. This conversion simply maps the component values |
2295 | of the pixel (R, G, B, and A) to the values included in the internal | |
2296 | format (red, green, blue, alpha, luminance, and intensity). The mapping | |
2297 | is as follows: | |
2298 | ||
2299 | ||
2300 | ||
2301 | @table @asis | |
2302 | @item @strong{Internal Format} | |
2303 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
2304 | @strong{Luminance}, @strong{Intensity} | |
2305 | ||
2306 | @item @code{GL_ALPHA} | |
2307 | , , , A , , | |
2308 | ||
2309 | @item @code{GL_LUMINANCE} | |
2310 | , , , , R , | |
2311 | ||
2312 | @item @code{GL_LUMINANCE_ALPHA} | |
2313 | , , , A , R , | |
2314 | ||
2315 | @item @code{GL_INTENSITY} | |
2316 | , , , , , R | |
2317 | ||
2318 | @item @code{GL_RGB} | |
2319 | R , G , B , , , | |
2320 | ||
2321 | @item @code{GL_RGBA} | |
2322 | R , G , B , A , , | |
2323 | ||
2324 | @end table | |
2325 | ||
2326 | Finally, the red, green, blue, alpha, luminance, and/or intensity | |
2327 | components of the resulting pixels are stored in the color table. They | |
2328 | form a one-dimensional table with indices in the range | |
3c9b6116 | 2329 | @r{[0,@var{width}-1]}. |
8925f36f AW |
2330 | |
2331 | If @var{target} is @code{GL_PROXY_*}, @code{glColorTable} recomputes and | |
2332 | stores the values of the proxy color table's state variables | |
2333 | @code{GL_COLOR_TABLE_FORMAT}, @code{GL_COLOR_TABLE_WIDTH}, | |
2334 | @code{GL_COLOR_TABLE_RED_SIZE}, @code{GL_COLOR_TABLE_GREEN_SIZE}, | |
2335 | @code{GL_COLOR_TABLE_BLUE_SIZE}, @code{GL_COLOR_TABLE_ALPHA_SIZE}, | |
2336 | @code{GL_COLOR_TABLE_LUMINANCE_SIZE}, and | |
2337 | @code{GL_COLOR_TABLE_INTENSITY_SIZE}. There is no effect on the image or | |
2338 | state of any actual color table. If the specified color table is too | |
2339 | large to be supported, then all the proxy state variables listed above | |
2340 | are set to zero. Otherwise, the color table could be supported by | |
2341 | @code{glColorTable} using the corresponding non-proxy target, and the | |
2342 | proxy state variables are set as if that target were being defined. | |
2343 | ||
2344 | The proxy state variables can be retrieved by calling | |
2345 | @code{glGetColorTableParameter} with a target of @code{GL_PROXY_*}. This | |
2346 | allows the application to decide if a particular @code{glColorTable} | |
2347 | command would succeed, and to determine what the resulting color table | |
2348 | attributes would be. | |
2349 | ||
2350 | If a color table is enabled, and its width is non-zero, then its | |
2351 | contents are used to replace a subset of the components of each RGBA | |
2352 | pixel group, based on the internal format of the table. | |
2353 | ||
2354 | Each pixel group has color components (R, G, B, A) that are in the range | |
3c9b6116 | 2355 | @r{[0.0,1.0]}. The color components are rescaled to the size of the |
8925f36f AW |
2356 | color lookup table to form an index. Then a subset of the components |
2357 | based on the internal format of the table are replaced by the table | |
2358 | entry selected by that index. If the color components and contents of | |
2359 | the table are represented as follows: | |
2360 | ||
2361 | ||
2362 | ||
2363 | @table @asis | |
2364 | @item @strong{Representation} | |
2365 | @strong{Meaning} | |
2366 | ||
2367 | @item @code{r} | |
2368 | Table index computed from @code{R} | |
2369 | ||
2370 | @item @code{g} | |
2371 | Table index computed from @code{G} | |
2372 | ||
2373 | @item @code{b} | |
2374 | Table index computed from @code{B} | |
2375 | ||
2376 | @item @code{a} | |
2377 | Table index computed from @code{A} | |
2378 | ||
2379 | @item @code{L[i]} | |
2380 | Luminance value at table index @code{i} | |
2381 | ||
2382 | @item @code{I[i]} | |
2383 | Intensity value at table index @code{i} | |
2384 | ||
2385 | @item @code{R[i]} | |
2386 | Red value at table index @code{i} | |
2387 | ||
2388 | @item @code{G[i]} | |
2389 | Green value at table index @code{i} | |
2390 | ||
2391 | @item @code{B[i]} | |
2392 | Blue value at table index @code{i} | |
2393 | ||
2394 | @item @code{A[i]} | |
2395 | Alpha value at table index @code{i} | |
2396 | ||
2397 | @end table | |
2398 | ||
2399 | then the result of color table lookup is as follows: | |
2400 | ||
2401 | ||
2402 | ||
2403 | @table @asis | |
2404 | @item @strong{} | |
2405 | @strong{Resulting Texture Components} | |
2406 | ||
2407 | @item @strong{Table Internal Format} | |
2408 | @strong{R}, @strong{G}, @strong{B}, @strong{A} | |
2409 | ||
2410 | @item @code{GL_ALPHA} | |
2411 | @code{R}, @code{G}, @code{B}, @code{A[a]} | |
2412 | ||
2413 | @item @code{GL_LUMINANCE} | |
2414 | @code{L[r]}, @code{L[g]}, @code{L[b]}, @code{At} | |
2415 | ||
2416 | @item @code{GL_LUMINANCE_ALPHA} | |
2417 | @code{L[r]}, @code{L[g]}, @code{L[b]}, @code{A[a]} | |
2418 | ||
2419 | @item @code{GL_INTENSITY} | |
2420 | @code{I[r]}, @code{I[g]}, @code{I[b]}, @code{I[a]} | |
2421 | ||
2422 | @item @code{GL_RGB} | |
2423 | @code{R[r]}, @code{G[g]}, @code{B[b]}, @code{A} | |
2424 | ||
2425 | @item @code{GL_RGBA} | |
2426 | @code{R[r]}, @code{G[g]}, @code{B[b]}, @code{A[a]} | |
2427 | ||
2428 | @end table | |
2429 | ||
2430 | When @code{GL_COLOR_TABLE} is enabled, the colors resulting from the | |
2431 | pixel map operation (if it is enabled) are mapped by the color lookup | |
2432 | table before being passed to the convolution operation. The colors | |
2433 | resulting from the convolution operation are modified by the post | |
2434 | convolution color lookup table when | |
2435 | @code{GL_POST_CONVOLUTION_COLOR_TABLE} is enabled. These modified colors | |
2436 | are then sent to the color matrix operation. Finally, if | |
2437 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} is enabled, the colors resulting | |
2438 | from the color matrix operation are mapped by the post color matrix | |
2439 | color lookup table before being used by the histogram operation. | |
2440 | ||
2441 | ||
2442 | ||
8925f36f AW |
2443 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
2444 | allowable values. | |
2445 | ||
2446 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
2447 | of the allowable values. | |
2448 | ||
2449 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
2450 | allowable values. | |
2451 | ||
2452 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
2453 | allowable values. | |
2454 | ||
2455 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero. | |
2456 | ||
2457 | @code{GL_TABLE_TOO_LARGE} is generated if the requested color table is | |
2458 | too large to be supported by the implementation, and @var{target} is not | |
2459 | a @code{GL_PROXY_*} target. | |
2460 | ||
2461 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2462 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2463 | object's data store is currently mapped. | |
2464 | ||
2465 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2466 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2467 | would be unpacked from the buffer object such that the memory reads | |
2468 | required would exceed the data store size. | |
2469 | ||
2470 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2471 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
2472 | is not evenly divisible into the number of bytes needed to store in | |
2473 | memory a datum indicated by @var{type}. | |
2474 | ||
2475 | @code{GL_INVALID_OPERATION} is generated if @code{glColorTable} is | |
2476 | executed between the execution of @code{glBegin} and the corresponding | |
2477 | execution of @code{glEnd}. | |
2478 | ||
bb894c9d | 2479 | @end deftypefun |
8925f36f | 2480 | |
bb894c9d | 2481 | @deftypefun void glColor3i red green blue |
ca09631c | 2482 | @deftypefunx void glColor3f red green blue |
bb894c9d AW |
2483 | @deftypefunx void glColor3ui red green blue |
2484 | @deftypefunx void glColor4i red green blue alpha | |
ca09631c | 2485 | @deftypefunx void glColor4f red green blue alpha |
bb894c9d | 2486 | @deftypefunx void glColor4ui red green blue alpha |
3c9b6116 AW |
2487 | Set the current color. |
2488 | ||
8925f36f AW |
2489 | @table @asis |
2490 | @item @var{red} | |
2491 | @itemx @var{green} | |
2492 | @itemx @var{blue} | |
2493 | Specify new red, green, and blue values for the current color. | |
2494 | ||
2495 | @item @var{alpha} | |
2496 | Specifies a new alpha value for the current color. Included only in the | |
2497 | four-argument @code{glColor4} commands. | |
2498 | ||
2499 | @end table | |
2500 | ||
8925f36f AW |
2501 | The GL stores both a current single-valued color index and a current |
2502 | four-valued RGBA color. @code{glColor} sets a new four-valued RGBA | |
2503 | color. @code{glColor} has two major variants: @code{glColor3} and | |
2504 | @code{glColor4}. @code{glColor3} variants specify new red, green, and | |
2505 | blue values explicitly and set the current alpha value to 1.0 (full | |
2506 | intensity) implicitly. @code{glColor4} variants specify all four color | |
2507 | components explicitly. | |
2508 | ||
2509 | @code{glColor3b}, @code{glColor4b}, @code{glColor3s}, @code{glColor4s}, | |
2510 | @code{glColor3i}, and @code{glColor4i} take three or four signed byte, | |
2511 | short, or long integers as arguments. When @strong{v} is appended to the | |
2512 | name, the color commands can take a pointer to an array of such values. | |
2513 | ||
2514 | Current color values are stored in floating-point format, with | |
2515 | unspecified mantissa and exponent sizes. Unsigned integer color | |
2516 | components, when specified, are linearly mapped to floating-point values | |
2517 | such that the largest representable value maps to 1.0 (full intensity), | |
2518 | and 0 maps to 0.0 (zero intensity). Signed integer color components, | |
2519 | when specified, are linearly mapped to floating-point values such that | |
2520 | the most positive representable value maps to 1.0, and the most negative | |
3c9b6116 AW |
2521 | representable value maps to @r{-1.0}. (Note that this mapping does not |
2522 | convert 0 precisely to 0.0.) Floating-point values are mapped directly. | |
8925f36f AW |
2523 | |
2524 | Neither floating-point nor signed integer values are clamped to the | |
3c9b6116 | 2525 | range @r{[0,1]} before the current color is updated. However, color |
8925f36f AW |
2526 | components are clamped to this range before they are interpolated or |
2527 | written into a color buffer. | |
2528 | ||
bb894c9d | 2529 | @end deftypefun |
8925f36f | 2530 | |
bb894c9d | 2531 | @deftypefun void glCompileShader shader |
3c9b6116 AW |
2532 | Compiles a shader object. |
2533 | ||
8925f36f AW |
2534 | @table @asis |
2535 | @item @var{shader} | |
2536 | Specifies the shader object to be compiled. | |
2537 | ||
2538 | @end table | |
2539 | ||
8925f36f AW |
2540 | @code{glCompileShader} compiles the source code strings that have been |
2541 | stored in the shader object specified by @var{shader}. | |
2542 | ||
2543 | The compilation status will be stored as part of the shader object's | |
2544 | state. This value will be set to @code{GL_TRUE} if the shader was | |
2545 | compiled without errors and is ready for use, and @code{GL_FALSE} | |
2546 | otherwise. It can be queried by calling @code{glGetShader} with | |
2547 | arguments @var{shader} and @code{GL_COMPILE_STATUS}. | |
2548 | ||
2549 | Compilation of a shader can fail for a number of reasons as specified by | |
2550 | the OpenGL Shading Language Specification. Whether or not the | |
2551 | compilation was successful, information about the compilation can be | |
2552 | obtained from the shader object's information log by calling | |
2553 | @code{glGetShaderInfoLog}. | |
2554 | ||
8925f36f AW |
2555 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
2556 | generated by OpenGL. | |
2557 | ||
2558 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
2559 | object. | |
2560 | ||
2561 | @code{GL_INVALID_OPERATION} is generated if @code{glCompileShader} is | |
2562 | executed between the execution of @code{glBegin} and the corresponding | |
2563 | execution of @code{glEnd}. | |
2564 | ||
bb894c9d | 2565 | @end deftypefun |
8925f36f | 2566 | |
bb894c9d | 2567 | @deftypefun void glCompressedTexImage1D target level internalformat width border imageSize data |
3c9b6116 AW |
2568 | Specify a one-dimensional texture image in a compressed format. |
2569 | ||
8925f36f AW |
2570 | @table @asis |
2571 | @item @var{target} | |
2572 | Specifies the target texture. Must be @code{GL_TEXTURE_1D} or | |
2573 | @code{GL_PROXY_TEXTURE_1D}. | |
2574 | ||
2575 | @item @var{level} | |
2576 | Specifies the level-of-detail number. Level 0 is the base image level. | |
2577 | Level @var{n} is the @var{n}th mipmap reduction image. | |
2578 | ||
2579 | @item @var{internalformat} | |
2580 | Specifies the format of the compressed image data stored at address | |
2581 | @var{data}. | |
2582 | ||
2583 | @item @var{width} | |
2584 | Specifies the width of the texture image including the border if any. If | |
2585 | the GL version does not support non-power-of-two sizes, this value must | |
3c9b6116 AW |
2586 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
2587 | implementations support texture images that are at least 64 texels wide. | |
2588 | The height of the 1D texture image is 1. | |
8925f36f AW |
2589 | |
2590 | @item @var{border} | |
2591 | Specifies the width of the border. Must be either 0 or 1. | |
2592 | ||
2593 | @item @var{imageSize} | |
2594 | Specifies the number of unsigned bytes of image data starting at the | |
2595 | address specified by @var{data}. | |
2596 | ||
2597 | @item @var{data} | |
2598 | Specifies a pointer to the compressed image data in memory. | |
2599 | ||
2600 | @end table | |
2601 | ||
8925f36f AW |
2602 | Texturing maps a portion of a specified texture image onto each |
2603 | graphical primitive for which texturing is enabled. To enable and | |
2604 | disable one-dimensional texturing, call @code{glEnable} and | |
2605 | @code{glDisable} with argument @code{GL_TEXTURE_1D}. | |
2606 | ||
2607 | @code{glCompressedTexImage1D} loads a previously defined, and retrieved, | |
2608 | compressed one-dimensional texture image if @var{target} is | |
2609 | @code{GL_TEXTURE_1D} (see @code{glTexImage1D}). | |
2610 | ||
2611 | If @var{target} is @code{GL_PROXY_TEXTURE_1D}, no data is read from | |
2612 | @var{data}, but all of the texture image state is recalculated, checked | |
2613 | for consistency, and checked against the implementation's capabilities. | |
2614 | If the implementation cannot handle a texture of the requested texture | |
2615 | size, it sets all of the image state to 0, but does not generate an | |
2616 | error (see @code{glGetError}). To query for an entire mipmap array, use | |
2617 | an image array level greater than or equal to 1. | |
2618 | ||
2619 | @var{internalformat} must be extension-specified compressed-texture | |
2620 | format. When a texture is loaded with @code{glTexImage1D} using a | |
2621 | generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}) the | |
2622 | GL selects from one of its extensions supporting compressed textures. In | |
2623 | order to load the compressed texture image using | |
2624 | @code{glCompressedTexImage1D}, query the compressed texture image's size | |
2625 | and format using @code{glGetTexLevelParameter}. | |
2626 | ||
2627 | If a non-zero named buffer object is bound to the | |
2628 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2629 | texture image is specified, @var{data} is treated as a byte offset into | |
2630 | the buffer object's data store. | |
2631 | ||
8925f36f AW |
2632 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of |
2633 | the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
2634 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
2635 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or | |
2636 | @code{GL_COMPRESSED_RGBA}. | |
2637 | ||
2638 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
2639 | consistent with the format, dimensions, and contents of the specified | |
2640 | compressed image data. | |
2641 | ||
2642 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
2643 | not supported by the specific compressed internal format as specified in | |
2644 | the specific texture compression extension. | |
2645 | ||
2646 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2647 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2648 | object's data store is currently mapped. | |
2649 | ||
2650 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2651 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2652 | would be unpacked from the buffer object such that the memory reads | |
2653 | required would exceed the data store size. | |
2654 | ||
2655 | @code{GL_INVALID_OPERATION} is generated if | |
2656 | @code{glCompressedTexImage1D} is executed between the execution of | |
2657 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
2658 | ||
2659 | Undefined results, including abnormal program termination, are generated | |
2660 | if @var{data} is not encoded in a manner consistent with the extension | |
2661 | specification defining the internal compression format. | |
2662 | ||
bb894c9d | 2663 | @end deftypefun |
8925f36f | 2664 | |
bb894c9d | 2665 | @deftypefun void glCompressedTexImage2D target level internalformat width height border imageSize data |
3c9b6116 AW |
2666 | Specify a two-dimensional texture image in a compressed format. |
2667 | ||
8925f36f AW |
2668 | @table @asis |
2669 | @item @var{target} | |
2670 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, | |
2671 | @code{GL_PROXY_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
2672 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
2673 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
2674 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
2675 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, | |
2676 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or | |
2677 | @code{GL_PROXY_TEXTURE_CUBE_MAP}. | |
2678 | ||
2679 | @item @var{level} | |
2680 | Specifies the level-of-detail number. Level 0 is the base image level. | |
2681 | Level @var{n} is the @var{n}th mipmap reduction image. | |
2682 | ||
2683 | @item @var{internalformat} | |
2684 | Specifies the format of the compressed image data stored at address | |
2685 | @var{data}. | |
2686 | ||
2687 | @item @var{width} | |
2688 | Specifies the width of the texture image including the border if any. If | |
2689 | the GL version does not support non-power-of-two sizes, this value must | |
3c9b6116 AW |
2690 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
2691 | implementations support 2D texture images that are at least 64 texels | |
2692 | wide and cube-mapped texture images that are at least 16 texels wide. | |
8925f36f AW |
2693 | |
2694 | @item @var{height} | |
2695 | Specifies the height of the texture image including the border if any. | |
2696 | If the GL version does not support non-power-of-two sizes, this value | |
3c9b6116 AW |
2697 | must be Must be @r{2^@var{n}+2(@var{border},)} for some integer |
2698 | @r{@var{n}}. All implementations support 2D texture images that are at | |
2699 | least 64 texels high and cube-mapped texture images that are at least 16 | |
2700 | texels high. | |
8925f36f AW |
2701 | |
2702 | @item @var{border} | |
2703 | Specifies the width of the border. Must be either 0 or 1. | |
2704 | ||
2705 | @item @var{imageSize} | |
2706 | Specifies the number of unsigned bytes of image data starting at the | |
2707 | address specified by @var{data}. | |
2708 | ||
2709 | @item @var{data} | |
2710 | Specifies a pointer to the compressed image data in memory. | |
2711 | ||
2712 | @end table | |
2713 | ||
8925f36f AW |
2714 | Texturing maps a portion of a specified texture image onto each |
2715 | graphical primitive for which texturing is enabled. To enable and | |
2716 | disable two-dimensional texturing, call @code{glEnable} and | |
2717 | @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and | |
2718 | disable texturing using cube-mapped textures, call @code{glEnable} and | |
2719 | @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}. | |
2720 | ||
2721 | @code{glCompressedTexImage2D} loads a previously defined, and retrieved, | |
2722 | compressed two-dimensional texture image if @var{target} is | |
2723 | @code{GL_TEXTURE_2D} (see @code{glTexImage2D}). | |
2724 | ||
2725 | If @var{target} is @code{GL_PROXY_TEXTURE_2D}, no data is read from | |
2726 | @var{data}, but all of the texture image state is recalculated, checked | |
2727 | for consistency, and checked against the implementation's capabilities. | |
2728 | If the implementation cannot handle a texture of the requested texture | |
2729 | size, it sets all of the image state to 0, but does not generate an | |
2730 | error (see @code{glGetError}). To query for an entire mipmap array, use | |
2731 | an image array level greater than or equal to 1. | |
2732 | ||
2733 | @var{internalformat} must be an extension-specified compressed-texture | |
2734 | format. When a texture is loaded with @code{glTexImage2D} using a | |
2735 | generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}), the | |
2736 | GL selects from one of its extensions supporting compressed textures. In | |
2737 | order to load the compressed texture image using | |
2738 | @code{glCompressedTexImage2D}, query the compressed texture image's size | |
2739 | and format using @code{glGetTexLevelParameter}. | |
2740 | ||
2741 | If a non-zero named buffer object is bound to the | |
2742 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2743 | texture image is specified, @var{data} is treated as a byte offset into | |
2744 | the buffer object's data store. | |
2745 | ||
8925f36f AW |
2746 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of |
2747 | the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
2748 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
2749 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or | |
2750 | @code{GL_COMPRESSED_RGBA}. | |
2751 | ||
2752 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
2753 | consistent with the format, dimensions, and contents of the specified | |
2754 | compressed image data. | |
2755 | ||
2756 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
2757 | not supported by the specific compressed internal format as specified in | |
2758 | the specific texture compression extension. | |
2759 | ||
2760 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2761 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2762 | object's data store is currently mapped. | |
2763 | ||
2764 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2765 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2766 | would be unpacked from the buffer object such that the memory reads | |
2767 | required would exceed the data store size. | |
2768 | ||
2769 | @code{GL_INVALID_OPERATION} is generated if | |
2770 | @code{glCompressedTexImage2D} is executed between the execution of | |
2771 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
2772 | ||
2773 | Undefined results, including abnormal program termination, are generated | |
2774 | if @var{data} is not encoded in a manner consistent with the extension | |
2775 | specification defining the internal compression format. | |
2776 | ||
bb894c9d | 2777 | @end deftypefun |
8925f36f | 2778 | |
bb894c9d | 2779 | @deftypefun void glCompressedTexImage3D target level internalformat width height depth border imageSize data |
3c9b6116 AW |
2780 | Specify a three-dimensional texture image in a compressed format. |
2781 | ||
8925f36f AW |
2782 | @table @asis |
2783 | @item @var{target} | |
2784 | Specifies the target texture. Must be @code{GL_TEXTURE_3D} or | |
2785 | @code{GL_PROXY_TEXTURE_3D}. | |
2786 | ||
2787 | @item @var{level} | |
2788 | Specifies the level-of-detail number. Level 0 is the base image level. | |
2789 | Level @var{n} is the @var{n}th mipmap reduction image. | |
2790 | ||
2791 | @item @var{internalformat} | |
2792 | Specifies the format of the compressed image data stored at address | |
2793 | @var{data}. | |
2794 | ||
2795 | @item @var{width} | |
2796 | Specifies the width of the texture image including the border if any. If | |
2797 | the GL version does not support non-power-of-two sizes, this value must | |
3c9b6116 AW |
2798 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
2799 | implementations support 3D texture images that are at least 16 texels | |
2800 | wide. | |
8925f36f AW |
2801 | |
2802 | @item @var{height} | |
2803 | Specifies the height of the texture image including the border if any. | |
2804 | If the GL version does not support non-power-of-two sizes, this value | |
3c9b6116 AW |
2805 | must be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. |
2806 | All implementations support 3D texture images that are at least 16 | |
2807 | texels high. | |
8925f36f AW |
2808 | |
2809 | @item @var{depth} | |
2810 | Specifies the depth of the texture image including the border if any. If | |
2811 | the GL version does not support non-power-of-two sizes, this value must | |
3c9b6116 AW |
2812 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
2813 | implementations support 3D texture images that are at least 16 texels | |
2814 | deep. | |
8925f36f AW |
2815 | |
2816 | @item @var{border} | |
2817 | Specifies the width of the border. Must be either 0 or 1. | |
2818 | ||
2819 | @item @var{imageSize} | |
2820 | Specifies the number of unsigned bytes of image data starting at the | |
2821 | address specified by @var{data}. | |
2822 | ||
2823 | @item @var{data} | |
2824 | Specifies a pointer to the compressed image data in memory. | |
2825 | ||
2826 | @end table | |
2827 | ||
8925f36f AW |
2828 | Texturing maps a portion of a specified texture image onto each |
2829 | graphical primitive for which texturing is enabled. To enable and | |
2830 | disable three-dimensional texturing, call @code{glEnable} and | |
2831 | @code{glDisable} with argument @code{GL_TEXTURE_3D}. | |
2832 | ||
2833 | @code{glCompressedTexImage3D} loads a previously defined, and retrieved, | |
2834 | compressed three-dimensional texture image if @var{target} is | |
2835 | @code{GL_TEXTURE_3D} (see @code{glTexImage3D}). | |
2836 | ||
2837 | If @var{target} is @code{GL_PROXY_TEXTURE_3D}, no data is read from | |
2838 | @var{data}, but all of the texture image state is recalculated, checked | |
2839 | for consistency, and checked against the implementation's capabilities. | |
2840 | If the implementation cannot handle a texture of the requested texture | |
2841 | size, it sets all of the image state to 0, but does not generate an | |
2842 | error (see @code{glGetError}). To query for an entire mipmap array, use | |
2843 | an image array level greater than or equal to 1. | |
2844 | ||
2845 | @var{internalformat} must be an extension-specified compressed-texture | |
2846 | format. When a texture is loaded with @code{glTexImage2D} using a | |
2847 | generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}), the | |
2848 | GL selects from one of its extensions supporting compressed textures. In | |
2849 | order to load the compressed texture image using | |
2850 | @code{glCompressedTexImage3D}, query the compressed texture image's size | |
2851 | and format using @code{glGetTexLevelParameter}. | |
2852 | ||
2853 | If a non-zero named buffer object is bound to the | |
2854 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2855 | texture image is specified, @var{data} is treated as a byte offset into | |
2856 | the buffer object's data store. | |
2857 | ||
8925f36f AW |
2858 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of |
2859 | the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
2860 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
2861 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or | |
2862 | @code{GL_COMPRESSED_RGBA}. | |
2863 | ||
2864 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
2865 | consistent with the format, dimensions, and contents of the specified | |
2866 | compressed image data. | |
2867 | ||
2868 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
2869 | not supported by the specific compressed internal format as specified in | |
2870 | the specific texture compression extension. | |
2871 | ||
2872 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2873 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2874 | object's data store is currently mapped. | |
2875 | ||
2876 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2877 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2878 | would be unpacked from the buffer object such that the memory reads | |
2879 | required would exceed the data store size. | |
2880 | ||
2881 | @code{GL_INVALID_OPERATION} is generated if | |
2882 | @code{glCompressedTexImage3D} is executed between the execution of | |
2883 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
2884 | ||
2885 | Undefined results, including abnormal program termination, are generated | |
2886 | if @var{data} is not encoded in a manner consistent with the extension | |
2887 | specification defining the internal compression format. | |
2888 | ||
bb894c9d | 2889 | @end deftypefun |
8925f36f | 2890 | |
bb894c9d | 2891 | @deftypefun void glCompressedTexSubImage1D target level xoffset width format imageSize data |
3c9b6116 AW |
2892 | Specify a one-dimensional texture subimage in a compressed format. |
2893 | ||
8925f36f AW |
2894 | @table @asis |
2895 | @item @var{target} | |
2896 | Specifies the target texture. Must be @code{GL_TEXTURE_1D}. | |
2897 | ||
2898 | @item @var{level} | |
2899 | Specifies the level-of-detail number. Level 0 is the base image level. | |
2900 | Level @var{n} is the @var{n}th mipmap reduction image. | |
2901 | ||
2902 | @item @var{xoffset} | |
2903 | Specifies a texel offset in the x direction within the texture array. | |
2904 | ||
2905 | @item @var{width} | |
2906 | Specifies the width of the texture subimage. | |
2907 | ||
2908 | @item @var{format} | |
2909 | Specifies the format of the compressed image data stored at address | |
2910 | @var{data}. | |
2911 | ||
2912 | @item @var{imageSize} | |
2913 | Specifies the number of unsigned bytes of image data starting at the | |
2914 | address specified by @var{data}. | |
2915 | ||
2916 | @item @var{data} | |
2917 | Specifies a pointer to the compressed image data in memory. | |
2918 | ||
2919 | @end table | |
2920 | ||
8925f36f AW |
2921 | Texturing maps a portion of a specified texture image onto each |
2922 | graphical primitive for which texturing is enabled. To enable and | |
2923 | disable one-dimensional texturing, call @code{glEnable} and | |
2924 | @code{glDisable} with argument @code{GL_TEXTURE_1D}. | |
2925 | ||
2926 | @code{glCompressedTexSubImage1D} redefines a contiguous subregion of an | |
2927 | existing one-dimensional texture image. The texels referenced by | |
2928 | @var{data} replace the portion of the existing texture array with x | |
3c9b6116 | 2929 | indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive. |
8925f36f AW |
2930 | This region may not include any texels outside the range of the texture |
2931 | array as it was originally specified. It is not an error to specify a | |
2932 | subtexture with width of 0, but such a specification has no effect. | |
2933 | ||
2934 | @var{format} must be an extension-specified compressed-texture format. | |
2935 | The @var{format} of the compressed texture image is selected by the GL | |
2936 | implementation that compressed it (see @code{glTexImage1D}), and should | |
2937 | be queried at the time the texture was compressed with | |
2938 | @code{glGetTexLevelParameter}. | |
2939 | ||
2940 | If a non-zero named buffer object is bound to the | |
2941 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2942 | texture image is specified, @var{data} is treated as a byte offset into | |
2943 | the buffer object's data store. | |
2944 | ||
8925f36f AW |
2945 | @code{GL_INVALID_ENUM} is generated if @var{format} is one of these |
2946 | generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
2947 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
2948 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
2949 | @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE}, | |
2950 | @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB}, | |
2951 | @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}. | |
2952 | ||
2953 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
2954 | consistent with the format, dimensions, and contents of the specified | |
2955 | compressed image data. | |
2956 | ||
2957 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
2958 | not supported by the specific compressed internal format as specified in | |
2959 | the specific texture compression extension. | |
2960 | ||
2961 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2962 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2963 | object's data store is currently mapped. | |
2964 | ||
2965 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2966 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2967 | would be unpacked from the buffer object such that the memory reads | |
2968 | required would exceed the data store size. | |
2969 | ||
2970 | @code{GL_INVALID_OPERATION} is generated if | |
2971 | @code{glCompressedTexSubImage1D} is executed between the execution of | |
2972 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
2973 | ||
2974 | Undefined results, including abnormal program termination, are generated | |
2975 | if @var{data} is not encoded in a manner consistent with the extension | |
2976 | specification defining the internal compression format. | |
2977 | ||
bb894c9d | 2978 | @end deftypefun |
8925f36f | 2979 | |
bb894c9d | 2980 | @deftypefun void glCompressedTexSubImage2D target level xoffset yoffset width height format imageSize data |
3c9b6116 AW |
2981 | Specify a two-dimensional texture subimage in a compressed format. |
2982 | ||
8925f36f AW |
2983 | @table @asis |
2984 | @item @var{target} | |
2985 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, | |
2986 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
2987 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
2988 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
2989 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
2990 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
2991 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
2992 | ||
2993 | @item @var{level} | |
2994 | Specifies the level-of-detail number. Level 0 is the base image level. | |
2995 | Level @var{n} is the @var{n}th mipmap reduction image. | |
2996 | ||
2997 | @item @var{xoffset} | |
2998 | Specifies a texel offset in the x direction within the texture array. | |
2999 | ||
3000 | @item @var{yoffset} | |
3001 | Specifies a texel offset in the y direction within the texture array. | |
3002 | ||
3003 | @item @var{width} | |
3004 | Specifies the width of the texture subimage. | |
3005 | ||
3006 | @item @var{height} | |
3007 | Specifies the height of the texture subimage. | |
3008 | ||
3009 | @item @var{format} | |
3010 | Specifies the format of the compressed image data stored at address | |
3011 | @var{data}. | |
3012 | ||
3013 | @item @var{imageSize} | |
3014 | Specifies the number of unsigned bytes of image data starting at the | |
3015 | address specified by @var{data}. | |
3016 | ||
3017 | @item @var{data} | |
3018 | Specifies a pointer to the compressed image data in memory. | |
3019 | ||
3020 | @end table | |
3021 | ||
8925f36f AW |
3022 | Texturing maps a portion of a specified texture image onto each |
3023 | graphical primitive for which texturing is enabled. To enable and | |
3024 | disable two-dimensional texturing, call @code{glEnable} and | |
3025 | @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and | |
3026 | disable texturing using cube-mapped texture, call @code{glEnable} and | |
3027 | @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}. | |
3028 | ||
3029 | @code{glCompressedTexSubImage2D} redefines a contiguous subregion of an | |
3030 | existing two-dimensional texture image. The texels referenced by | |
3031 | @var{data} replace the portion of the existing texture array with x | |
3c9b6116 AW |
3032 | indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, and the y |
3033 | indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive. | |
3034 | This region may not include any texels outside the range of the texture | |
3035 | array as it was originally specified. It is not an error to specify a | |
3036 | subtexture with width of 0, but such a specification has no effect. | |
8925f36f AW |
3037 | |
3038 | @var{format} must be an extension-specified compressed-texture format. | |
3039 | The @var{format} of the compressed texture image is selected by the GL | |
3040 | implementation that compressed it (see @code{glTexImage2D}) and should | |
3041 | be queried at the time the texture was compressed with | |
3042 | @code{glGetTexLevelParameter}. | |
3043 | ||
3044 | If a non-zero named buffer object is bound to the | |
3045 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
3046 | texture image is specified, @var{data} is treated as a byte offset into | |
3047 | the buffer object's data store. | |
3048 | ||
8925f36f AW |
3049 | @code{GL_INVALID_ENUM} is generated if @var{format} is one of these |
3050 | generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
3051 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
3052 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
3053 | @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE}, | |
3054 | @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB}, | |
3055 | @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}. | |
3056 | ||
3057 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
3058 | consistent with the format, dimensions, and contents of the specified | |
3059 | compressed image data. | |
3060 | ||
3061 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
3062 | not supported by the specific compressed internal format as specified in | |
3063 | the specific texture compression extension. | |
3064 | ||
3065 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3066 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
3067 | object's data store is currently mapped. | |
3068 | ||
3069 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3070 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
3071 | would be unpacked from the buffer object such that the memory reads | |
3072 | required would exceed the data store size. | |
3073 | ||
3074 | @code{GL_INVALID_OPERATION} is generated if | |
3075 | @code{glCompressedTexSubImage2D} is executed between the execution of | |
3076 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
3077 | ||
3078 | Undefined results, including abnormal program termination, are generated | |
3079 | if @var{data} is not encoded in a manner consistent with the extension | |
3080 | specification defining the internal compression format. | |
3081 | ||
bb894c9d | 3082 | @end deftypefun |
8925f36f | 3083 | |
bb894c9d | 3084 | @deftypefun void glCompressedTexSubImage3D target level xoffset yoffset zoffset width height depth format imageSize data |
3c9b6116 AW |
3085 | Specify a three-dimensional texture subimage in a compressed format. |
3086 | ||
8925f36f AW |
3087 | @table @asis |
3088 | @item @var{target} | |
3089 | Specifies the target texture. Must be @code{GL_TEXTURE_3D}. | |
3090 | ||
3091 | @item @var{level} | |
3092 | Specifies the level-of-detail number. Level 0 is the base image level. | |
3093 | Level @var{n} is the @var{n}th mipmap reduction image. | |
3094 | ||
3095 | @item @var{xoffset} | |
3096 | Specifies a texel offset in the x direction within the texture array. | |
3097 | ||
3098 | @item @var{yoffset} | |
3099 | Specifies a texel offset in the y direction within the texture array. | |
3100 | ||
3101 | @item @var{width} | |
3102 | Specifies the width of the texture subimage. | |
3103 | ||
3104 | @item @var{height} | |
3105 | Specifies the height of the texture subimage. | |
3106 | ||
3107 | @item @var{depth} | |
3108 | Specifies the depth of the texture subimage. | |
3109 | ||
3110 | @item @var{format} | |
3111 | Specifies the format of the compressed image data stored at address | |
3112 | @var{data}. | |
3113 | ||
3114 | @item @var{imageSize} | |
3115 | Specifies the number of unsigned bytes of image data starting at the | |
3116 | address specified by @var{data}. | |
3117 | ||
3118 | @item @var{data} | |
3119 | Specifies a pointer to the compressed image data in memory. | |
3120 | ||
3121 | @end table | |
3122 | ||
8925f36f AW |
3123 | Texturing maps a portion of a specified texture image onto each |
3124 | graphical primitive for which texturing is enabled. To enable and | |
3125 | disable three-dimensional texturing, call @code{glEnable} and | |
3126 | @code{glDisable} with argument @code{GL_TEXTURE_3D}. | |
3127 | ||
3128 | @code{glCompressedTexSubImage3D} redefines a contiguous subregion of an | |
3129 | existing three-dimensional texture image. The texels referenced by | |
3130 | @var{data} replace the portion of the existing texture array with x | |
3c9b6116 AW |
3131 | indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, and the y |
3132 | indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, and the z | |
3133 | indices @var{zoffset} and @r{@var{zoffset}+@var{depth}-1}, inclusive. | |
8925f36f AW |
3134 | This region may not include any texels outside the range of the texture |
3135 | array as it was originally specified. It is not an error to specify a | |
3136 | subtexture with width of 0, but such a specification has no effect. | |
3137 | ||
3138 | @var{format} must be an extension-specified compressed-texture format. | |
3139 | The @var{format} of the compressed texture image is selected by the GL | |
3140 | implementation that compressed it (see @code{glTexImage3D}) and should | |
3141 | be queried at the time the texture was compressed with | |
3142 | @code{glGetTexLevelParameter}. | |
3143 | ||
3144 | If a non-zero named buffer object is bound to the | |
3145 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
3146 | texture image is specified, @var{data} is treated as a byte offset into | |
3147 | the buffer object's data store. | |
3148 | ||
8925f36f AW |
3149 | @code{GL_INVALID_ENUM} is generated if @var{format} is one of these |
3150 | generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
3151 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
3152 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
3153 | @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE}, | |
3154 | @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB}, | |
3155 | @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}. | |
3156 | ||
3157 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
3158 | consistent with the format, dimensions, and contents of the specified | |
3159 | compressed image data. | |
3160 | ||
3161 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
3162 | not supported by the specific compressed internal format as specified in | |
3163 | the specific texture compression extension. | |
3164 | ||
3165 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3166 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
3167 | object's data store is currently mapped. | |
3168 | ||
3169 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3170 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
3171 | would be unpacked from the buffer object such that the memory reads | |
3172 | required would exceed the data store size. | |
3173 | ||
3174 | @code{GL_INVALID_OPERATION} is generated if | |
3175 | @code{glCompressedTexSubImage3D} is executed between the execution of | |
3176 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
3177 | ||
3178 | Undefined results, including abnormal program termination, are generated | |
3179 | if @var{data} is not encoded in a manner consistent with the extension | |
3180 | specification defining the internal compression format. | |
3181 | ||
bb894c9d | 3182 | @end deftypefun |
8925f36f | 3183 | |
bb894c9d | 3184 | @deftypefun void glConvolutionFilter1D target internalformat width format type data |
3c9b6116 AW |
3185 | Define a one-dimensional convolution filter. |
3186 | ||
8925f36f AW |
3187 | @table @asis |
3188 | @item @var{target} | |
3189 | Must be @code{GL_CONVOLUTION_1D}. | |
3190 | ||
3191 | @item @var{internalformat} | |
3192 | The internal format of the convolution filter kernel. The allowable | |
3193 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, | |
3194 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
3195 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
3196 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3197 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3198 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3199 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3200 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3201 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3202 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3203 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3204 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3205 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3206 | ||
3207 | @item @var{width} | |
3208 | The width of the pixel array referenced by @var{data}. | |
3209 | ||
3210 | @item @var{format} | |
3211 | The format of the pixel data in @var{data}. The allowable values are | |
3212 | @code{GL_ALPHA}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, | |
3213 | @code{GL_INTENSITY}, @code{GL_RGB}, and @code{GL_RGBA}. | |
3214 | ||
3215 | @item @var{type} | |
3216 | The type of the pixel data in @var{data}. Symbolic constants | |
3217 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
3218 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
3219 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
3220 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
3221 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
3222 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
3223 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
3224 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
3225 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
3226 | ||
3227 | @item @var{data} | |
3228 | Pointer to a one-dimensional array of pixel data that is processed to | |
3229 | build the convolution filter kernel. | |
3230 | ||
3231 | @end table | |
3232 | ||
8925f36f AW |
3233 | @code{glConvolutionFilter1D} builds a one-dimensional convolution filter |
3234 | kernel from an array of pixels. | |
3235 | ||
3236 | The pixel array specified by @var{width}, @var{format}, @var{type}, and | |
3237 | @var{data} is extracted from memory and processed just as if | |
3238 | @code{glDrawPixels} were called, but processing stops after the final | |
3239 | expansion to RGBA is completed. | |
3240 | ||
3241 | If a non-zero named buffer object is bound to the | |
3242 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
3243 | convolution filter is specified, @var{data} is treated as a byte offset | |
3244 | into the buffer object's data store. | |
3245 | ||
3246 | The R, G, B, and A components of each pixel are next scaled by the four | |
3247 | 1D @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four | |
3248 | 1D @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias | |
3249 | parameters are set by @code{glConvolutionParameter} using the | |
3250 | @code{GL_CONVOLUTION_1D} target and the names | |
3251 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
3252 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors | |
3253 | of four values that are applied to red, green, blue, and alpha, in that | |
3254 | order.) The R, G, B, and A values are not clamped to [0,1] at any time | |
3255 | during this process. | |
3256 | ||
3257 | Each pixel is then converted to the internal format specified by | |
3258 | @var{internalformat}. This conversion simply maps the component values | |
3259 | of the pixel (R, G, B, and A) to the values included in the internal | |
3260 | format (red, green, blue, alpha, luminance, and intensity). The mapping | |
3261 | is as follows: | |
3262 | ||
3263 | ||
3264 | ||
3265 | @table @asis | |
3266 | @item @strong{Internal Format} | |
3267 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
3268 | @strong{Luminance}, @strong{Intensity} | |
3269 | ||
3270 | @item @code{GL_ALPHA} | |
3271 | , , , A , , | |
3272 | ||
3273 | @item @code{GL_LUMINANCE} | |
3274 | , , , , R , | |
3275 | ||
3276 | @item @code{GL_LUMINANCE_ALPHA} | |
3277 | , , , A , R , | |
3278 | ||
3279 | @item @code{GL_INTENSITY} | |
3280 | , , , , , R | |
3281 | ||
3282 | @item @code{GL_RGB} | |
3283 | R , G , B , , , | |
3284 | ||
3285 | @item @code{GL_RGBA} | |
3286 | R , G , B , A , , | |
3287 | ||
3288 | @end table | |
3289 | ||
3290 | The red, green, blue, alpha, luminance, and/or intensity components of | |
3291 | the resulting pixels are stored in floating-point rather than integer | |
3292 | format. They form a one-dimensional filter kernel image indexed with | |
3293 | coordinate @var{i} such that @var{i} starts at 0 and increases from left | |
3294 | to right. Kernel location @var{i} is derived from the @var{i}th pixel, | |
3295 | counting from 0. | |
3296 | ||
3297 | Note that after a convolution is performed, the resulting color | |
3298 | components are also scaled by their corresponding | |
3299 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
3300 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
3301 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
3302 | and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}. | |
3303 | ||
8925f36f AW |
3304 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
3305 | @code{GL_CONVOLUTION_1D}. | |
3306 | ||
3307 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
3308 | of the allowable values. | |
3309 | ||
3310 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
3311 | allowable values. | |
3312 | ||
3313 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
3314 | allowable values. | |
3315 | ||
3316 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
3317 | greater than the maximum supported value. This value may be queried with | |
3318 | @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_1D} | |
3319 | and name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
3320 | ||
3321 | @code{GL_INVALID_OPERATION} is generated if @var{format} is one of | |
3322 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
3323 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
3324 | and @var{type} is not @code{GL_RGB}. | |
3325 | ||
3326 | @code{GL_INVALID_OPERATION} is generated if @var{format} is one of | |
3327 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
3328 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
3329 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
3330 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
3331 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{type} is neither | |
3332 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
3333 | ||
3334 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3335 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
3336 | object's data store is currently mapped. | |
3337 | ||
3338 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3339 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
3340 | would be unpacked from the buffer object such that the memory reads | |
3341 | required would exceed the data store size. | |
3342 | ||
3343 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3344 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
3345 | is not evenly divisible into the number of bytes needed to store in | |
3346 | memory a datum indicated by @var{type}. | |
3347 | ||
3348 | @code{GL_INVALID_OPERATION} is generated if @code{glConvolutionFilter1D} | |
3349 | is executed between the execution of @code{glBegin} and the | |
3350 | corresponding execution of @code{glEnd}. | |
3351 | ||
bb894c9d | 3352 | @end deftypefun |
8925f36f | 3353 | |
bb894c9d | 3354 | @deftypefun void glConvolutionFilter2D target internalformat width height format type data |
3c9b6116 AW |
3355 | Define a two-dimensional convolution filter. |
3356 | ||
8925f36f AW |
3357 | @table @asis |
3358 | @item @var{target} | |
3359 | Must be @code{GL_CONVOLUTION_2D}. | |
3360 | ||
3361 | @item @var{internalformat} | |
3362 | The internal format of the convolution filter kernel. The allowable | |
3363 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, | |
3364 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
3365 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
3366 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3367 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3368 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3369 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3370 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3371 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3372 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3373 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3374 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3375 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3376 | ||
3377 | @item @var{width} | |
3378 | The width of the pixel array referenced by @var{data}. | |
3379 | ||
3380 | @item @var{height} | |
3381 | The height of the pixel array referenced by @var{data}. | |
3382 | ||
3383 | @item @var{format} | |
3384 | The format of the pixel data in @var{data}. The allowable values are | |
3385 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, | |
3386 | @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, | |
3387 | @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA}. | |
3388 | ||
3389 | @item @var{type} | |
3390 | The type of the pixel data in @var{data}. Symbolic constants | |
3391 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
3392 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
3393 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
3394 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
3395 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
3396 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
3397 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
3398 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
3399 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
3400 | ||
3401 | @item @var{data} | |
3402 | Pointer to a two-dimensional array of pixel data that is processed to | |
3403 | build the convolution filter kernel. | |
3404 | ||
3405 | @end table | |
3406 | ||
8925f36f AW |
3407 | @code{glConvolutionFilter2D} builds a two-dimensional convolution filter |
3408 | kernel from an array of pixels. | |
3409 | ||
3410 | The pixel array specified by @var{width}, @var{height}, @var{format}, | |
3411 | @var{type}, and @var{data} is extracted from memory and processed just | |
3412 | as if @code{glDrawPixels} were called, but processing stops after the | |
3413 | final expansion to RGBA is completed. | |
3414 | ||
3415 | If a non-zero named buffer object is bound to the | |
3416 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
3417 | convolution filter is specified, @var{data} is treated as a byte offset | |
3418 | into the buffer object's data store. | |
3419 | ||
3420 | The R, G, B, and A components of each pixel are next scaled by the four | |
3421 | 2D @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four | |
3422 | 2D @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias | |
3423 | parameters are set by @code{glConvolutionParameter} using the | |
3424 | @code{GL_CONVOLUTION_2D} target and the names | |
3425 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
3426 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors | |
3427 | of four values that are applied to red, green, blue, and alpha, in that | |
3428 | order.) The R, G, B, and A values are not clamped to [0,1] at any time | |
3429 | during this process. | |
3430 | ||
3431 | Each pixel is then converted to the internal format specified by | |
3432 | @var{internalformat}. This conversion simply maps the component values | |
3433 | of the pixel (R, G, B, and A) to the values included in the internal | |
3434 | format (red, green, blue, alpha, luminance, and intensity). The mapping | |
3435 | is as follows: | |
3436 | ||
3437 | ||
3438 | ||
3439 | @table @asis | |
3440 | @item @strong{Internal Format} | |
3441 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
3442 | @strong{Luminance}, @strong{Intensity} | |
3443 | ||
3444 | @item @code{GL_ALPHA} | |
3445 | , , , A , , | |
3446 | ||
3447 | @item @code{GL_LUMINANCE} | |
3448 | , , , , R , | |
3449 | ||
3450 | @item @code{GL_LUMINANCE_ALPHA} | |
3451 | , , , A , R , | |
3452 | ||
3453 | @item @code{GL_INTENSITY} | |
3454 | , , , , , R | |
3455 | ||
3456 | @item @code{GL_RGB} | |
3457 | R , G , B , , , | |
3458 | ||
3459 | @item @code{GL_RGBA} | |
3460 | R , G , B , A , , | |
3461 | ||
3462 | @end table | |
3463 | ||
3464 | The red, green, blue, alpha, luminance, and/or intensity components of | |
3465 | the resulting pixels are stored in floating-point rather than integer | |
3466 | format. They form a two-dimensional filter kernel image indexed with | |
3467 | coordinates @var{i} and @var{j} such that @var{i} starts at zero and | |
3468 | increases from left to right, and @var{j} starts at zero and increases | |
3469 | from bottom to top. Kernel location @var{i,j} is derived from the | |
3470 | @var{N}th pixel, where @var{N} is @var{i}+@var{j}*@var{width}. | |
3471 | ||
3472 | Note that after a convolution is performed, the resulting color | |
3473 | components are also scaled by their corresponding | |
3474 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
3475 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
3476 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
3477 | and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}. | |
3478 | ||
8925f36f AW |
3479 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
3480 | @code{GL_CONVOLUTION_2D}. | |
3481 | ||
3482 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
3483 | of the allowable values. | |
3484 | ||
3485 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
3486 | allowable values. | |
3487 | ||
3488 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
3489 | allowable values. | |
3490 | ||
3491 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
3492 | greater than the maximum supported value. This value may be queried with | |
3493 | @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_2D} | |
3494 | and name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
3495 | ||
3496 | @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero | |
3497 | or greater than the maximum supported value. This value may be queried | |
3498 | with @code{glGetConvolutionParameter} using target | |
3499 | @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}. | |
3500 | ||
3501 | @code{GL_INVALID_OPERATION} is generated if @var{height} is one of | |
3502 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
3503 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
3504 | and @var{format} is not @code{GL_RGB}. | |
3505 | ||
3506 | @code{GL_INVALID_OPERATION} is generated if @var{height} is one of | |
3507 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
3508 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
3509 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
3510 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
3511 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
3512 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
3513 | ||
3514 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3515 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
3516 | object's data store is currently mapped. | |
3517 | ||
3518 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3519 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
3520 | would be unpacked from the buffer object such that the memory reads | |
3521 | required would exceed the data store size. | |
3522 | ||
3523 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3524 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
3525 | is not evenly divisible into the number of bytes needed to store in | |
3526 | memory a datum indicated by @var{type}. | |
3527 | ||
3528 | @code{GL_INVALID_OPERATION} is generated if @code{glConvolutionFilter2D} | |
3529 | is executed between the execution of @code{glBegin} and the | |
3530 | corresponding execution of @code{glEnd}. | |
3531 | ||
bb894c9d | 3532 | @end deftypefun |
8925f36f | 3533 | |
bb894c9d AW |
3534 | @deftypefun void glConvolutionParameterf target pname params |
3535 | @deftypefunx void glConvolutionParameteri target pname params | |
3c9b6116 AW |
3536 | Set convolution parameters. |
3537 | ||
8925f36f AW |
3538 | @table @asis |
3539 | @item @var{target} | |
3540 | The target for the convolution parameter. Must be one of | |
3541 | @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or | |
3542 | @code{GL_SEPARABLE_2D}. | |
3543 | ||
3544 | @item @var{pname} | |
3545 | The parameter to be set. Must be @code{GL_CONVOLUTION_BORDER_MODE}. | |
3546 | ||
3547 | @item @var{params} | |
3548 | The parameter value. Must be one of @code{GL_REDUCE}, | |
3549 | @code{GL_CONSTANT_BORDER}, @code{GL_REPLICATE_BORDER}. | |
3550 | ||
3551 | ||
3552 | ||
3553 | @end table | |
3554 | ||
8925f36f AW |
3555 | @code{glConvolutionParameter} sets the value of a convolution parameter. |
3556 | ||
3557 | @var{target} selects the convolution filter to be affected: | |
3558 | @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or | |
3559 | @code{GL_SEPARABLE_2D} for the 1D, 2D, or separable 2D filter, | |
3560 | respectively. | |
3561 | ||
3562 | @var{pname} selects the parameter to be changed. | |
3563 | @code{GL_CONVOLUTION_FILTER_SCALE} and @code{GL_CONVOLUTION_FILTER_BIAS} | |
3564 | affect the definition of the convolution filter kernel; see | |
3565 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and | |
3566 | @code{glSeparableFilter2D} for details. In these cases, @var{params}v is | |
3567 | an array of four values to be applied to red, green, blue, and alpha | |
3568 | values, respectively. The initial value for | |
3569 | @code{GL_CONVOLUTION_FILTER_SCALE} is (1, 1, 1, 1), and the initial | |
3570 | value for @code{GL_CONVOLUTION_FILTER_BIAS} is (0, 0, 0, 0). | |
3571 | ||
3572 | A @var{pname} value of @code{GL_CONVOLUTION_BORDER_MODE} controls the | |
3573 | convolution border mode. The accepted modes are: | |
3574 | ||
3575 | @table @asis | |
3576 | @item @code{GL_REDUCE} | |
3577 | The image resulting from convolution is smaller than the source image. | |
3c9b6116 AW |
3578 | If the filter width is @r{@var{Wf}} and height is @r{@var{Hf}}, and the |
3579 | source image width is @r{@var{Ws}} and height is @r{@var{Hs}}, then the | |
3580 | convolved image width will be @r{@var{Ws}-@var{Wf}+1} and height will be | |
3581 | @r{@var{Hs}-@var{Hf}+1}. (If this reduction would generate an image with | |
3582 | zero or negative width and/or height, the output is simply null, with no | |
3583 | error generated.) The coordinates of the image resulting from | |
3584 | convolution are zero through @r{@var{Ws}-@var{Wf}} in width and zero | |
3585 | through @r{@var{Hs}-@var{Hf}} in height. | |
8925f36f AW |
3586 | |
3587 | @item @code{GL_CONSTANT_BORDER} | |
3588 | The image resulting from convolution is the same size as the source | |
3589 | image, and processed as if the source image were surrounded by pixels | |
3590 | with their color specified by the @code{GL_CONVOLUTION_BORDER_COLOR}. | |
3591 | ||
3592 | @item @code{GL_REPLICATE_BORDER} | |
3593 | The image resulting from convolution is the same size as the source | |
3594 | image, and processed as if the outermost pixel on the border of the | |
3595 | source image were replicated. | |
3596 | ||
3597 | @end table | |
3598 | ||
8925f36f AW |
3599 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
3600 | allowable values. | |
3601 | ||
3602 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the | |
3603 | allowable values. | |
3604 | ||
3605 | @code{GL_INVALID_ENUM} is generated if @var{pname} is | |
3606 | @code{GL_CONVOLUTION_BORDER_MODE} and @var{params} is not one of | |
3607 | @code{GL_REDUCE}, @code{GL_CONSTANT_BORDER}, or | |
3608 | @code{GL_REPLICATE_BORDER}. | |
3609 | ||
3610 | @code{GL_INVALID_OPERATION} is generated if | |
3611 | @code{glConvolutionParameter} is executed between the execution of | |
3612 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
3613 | ||
bb894c9d | 3614 | @end deftypefun |
8925f36f | 3615 | |
bb894c9d | 3616 | @deftypefun void glCopyColorSubTable target start x y width |
3c9b6116 AW |
3617 | Respecify a portion of a color table. |
3618 | ||
8925f36f AW |
3619 | @table @asis |
3620 | @item @var{target} | |
3621 | Must be one of @code{GL_COLOR_TABLE}, | |
3622 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or | |
3623 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
3624 | ||
3625 | @item @var{start} | |
3626 | The starting index of the portion of the color table to be replaced. | |
3627 | ||
3628 | @item @var{x} | |
3629 | @itemx @var{y} | |
3630 | The window coordinates of the left corner of the row of pixels to be | |
3631 | copied. | |
3632 | ||
3633 | @item @var{width} | |
3634 | The number of table entries to replace. | |
3635 | ||
3636 | @end table | |
3637 | ||
8925f36f AW |
3638 | @code{glCopyColorSubTable} is used to respecify a contiguous portion of |
3639 | a color table previously defined using @code{glColorTable}. The pixels | |
3640 | copied from the framebuffer replace the portion of the existing table | |
3c9b6116 AW |
3641 | from indices @var{start} to @r{@var{start}+@var{x}-1}, inclusive. This |
3642 | region may not include any entries outside the range of the color table, | |
3643 | as was originally specified. It is not an error to specify a subtexture | |
3644 | with width of 0, but such a specification has no effect. | |
8925f36f | 3645 | |
8925f36f AW |
3646 | @code{GL_INVALID_VALUE} is generated if @var{target} is not a previously |
3647 | defined color table. | |
3648 | ||
3649 | @code{GL_INVALID_VALUE} is generated if @var{target} is not one of the | |
3650 | allowable values. | |
3651 | ||
3652 | @code{GL_INVALID_VALUE} is generated if | |
3c9b6116 | 3653 | @r{@var{start}+@var{x}>@var{width}}. |
8925f36f AW |
3654 | |
3655 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyColorSubTable} | |
3656 | is executed between the execution of @code{glBegin} and the | |
3657 | corresponding execution of @code{glEnd}. | |
3658 | ||
bb894c9d | 3659 | @end deftypefun |
8925f36f | 3660 | |
bb894c9d | 3661 | @deftypefun void glCopyColorTable target internalformat x y width |
3c9b6116 AW |
3662 | Copy pixels into a color table. |
3663 | ||
8925f36f AW |
3664 | @table @asis |
3665 | @item @var{target} | |
3666 | The color table target. Must be @code{GL_COLOR_TABLE}, | |
3667 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or | |
3668 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
3669 | ||
3670 | @item @var{internalformat} | |
3671 | The internal storage format of the texture image. Must be one of the | |
3672 | following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4}, | |
3673 | @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16}, | |
3674 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, | |
3675 | @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3676 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3677 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3678 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3679 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3680 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3681 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3682 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3683 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3684 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3685 | ||
3686 | @item @var{x} | |
3687 | The x coordinate of the lower-left corner of the pixel rectangle to be | |
3688 | transferred to the color table. | |
3689 | ||
3690 | @item @var{y} | |
3691 | The y coordinate of the lower-left corner of the pixel rectangle to be | |
3692 | transferred to the color table. | |
3693 | ||
3694 | @item @var{width} | |
3695 | The width of the pixel rectangle. | |
3696 | ||
3697 | @end table | |
3698 | ||
8925f36f AW |
3699 | @code{glCopyColorTable} loads a color table with pixels from the current |
3700 | @code{GL_READ_BUFFER} (rather than from main memory, as is the case for | |
3701 | @code{glColorTable}). | |
3702 | ||
3703 | The screen-aligned pixel rectangle with lower-left corner at (@var{x},\ | |
3704 | @var{y}) having width @var{width} and height 1 is loaded into the color | |
3705 | table. If any pixels within this region are outside the window that is | |
3706 | associated with the GL context, the values obtained for those pixels are | |
3707 | undefined. | |
3708 | ||
3709 | The pixels in the rectangle are processed just as if @code{glReadPixels} | |
3710 | were called, with @var{internalformat} set to RGBA, but processing stops | |
3711 | after the final conversion to RGBA. | |
3712 | ||
3713 | The four scale parameters and the four bias parameters that are defined | |
3714 | for the table are then used to scale and bias the R, G, B, and A | |
3715 | components of each pixel. The scale and bias parameters are set by | |
3716 | calling @code{glColorTableParameter}. | |
3717 | ||
3c9b6116 AW |
3718 | Next, the R, G, B, and A values are clamped to the range @r{[0,1]}. Each |
3719 | pixel is then converted to the internal format specified by | |
8925f36f AW |
3720 | @var{internalformat}. This conversion simply maps the component values |
3721 | of the pixel (R, G, B, and A) to the values included in the internal | |
3722 | format (red, green, blue, alpha, luminance, and intensity). The mapping | |
3723 | is as follows: | |
3724 | ||
3725 | ||
3726 | ||
3727 | @table @asis | |
3728 | @item @strong{Internal Format} | |
3729 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
3730 | @strong{Luminance}, @strong{Intensity} | |
3731 | ||
3732 | @item @code{GL_ALPHA} | |
3733 | , , , A , , | |
3734 | ||
3735 | @item @code{GL_LUMINANCE} | |
3736 | , , , , R , | |
3737 | ||
3738 | @item @code{GL_LUMINANCE_ALPHA} | |
3739 | , , , A , R , | |
3740 | ||
3741 | @item @code{GL_INTENSITY} | |
3742 | , , , , , R | |
3743 | ||
3744 | @item @code{GL_RGB} | |
3745 | R , G , B , , , | |
3746 | ||
3747 | @item @code{GL_RGBA} | |
3748 | R , G , B , A , , | |
3749 | ||
3750 | @end table | |
3751 | ||
3752 | Finally, the red, green, blue, alpha, luminance, and/or intensity | |
3753 | components of the resulting pixels are stored in the color table. They | |
3754 | form a one-dimensional table with indices in the range | |
3c9b6116 | 3755 | @r{[0,@var{width}-1]}. |
8925f36f AW |
3756 | |
3757 | ||
3758 | ||
8925f36f AW |
3759 | @code{GL_INVALID_ENUM} is generated when @var{target} is not one of the |
3760 | allowable values. | |
3761 | ||
3762 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero. | |
3763 | ||
3764 | @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not one | |
3765 | of the allowable values. | |
3766 | ||
3767 | @code{GL_TABLE_TOO_LARGE} is generated if the requested color table is | |
3768 | too large to be supported by the implementation. | |
3769 | ||
3770 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyColorTable} is | |
3771 | executed between the execution of @code{glBegin} and the corresponding | |
3772 | execution of @code{glEnd}. | |
3773 | ||
bb894c9d | 3774 | @end deftypefun |
8925f36f | 3775 | |
bb894c9d | 3776 | @deftypefun void glCopyConvolutionFilter1D target internalformat x y width |
3c9b6116 AW |
3777 | Copy pixels into a one-dimensional convolution filter. |
3778 | ||
8925f36f AW |
3779 | @table @asis |
3780 | @item @var{target} | |
3781 | Must be @code{GL_CONVOLUTION_1D}. | |
3782 | ||
3783 | @item @var{internalformat} | |
3784 | The internal format of the convolution filter kernel. The allowable | |
3785 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, | |
3786 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
3787 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
3788 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3789 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3790 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3791 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3792 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3793 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3794 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3795 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3796 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3797 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3798 | ||
3799 | @item @var{x} | |
3800 | @itemx @var{y} | |
3801 | The window space coordinates of the lower-left coordinate of the pixel | |
3802 | array to copy. | |
3803 | ||
3804 | @item @var{width} | |
3805 | The width of the pixel array to copy. | |
3806 | ||
3807 | @end table | |
3808 | ||
8925f36f AW |
3809 | @code{glCopyConvolutionFilter1D} defines a one-dimensional convolution |
3810 | filter kernel with pixels from the current @code{GL_READ_BUFFER} (rather | |
3811 | than from main memory, as is the case for @code{glConvolutionFilter1D}). | |
3812 | ||
3813 | The screen-aligned pixel rectangle with lower-left corner at (@var{x},\ | |
3814 | @var{y}), width @var{width} and height 1 is used to define the | |
3815 | convolution filter. If any pixels within this region are outside the | |
3816 | window that is associated with the GL context, the values obtained for | |
3817 | those pixels are undefined. | |
3818 | ||
3819 | The pixels in the rectangle are processed exactly as if | |
3820 | @code{glReadPixels} had been called with @var{format} set to RGBA, but | |
3821 | the process stops just before final conversion. The R, G, B, and A | |
3822 | components of each pixel are next scaled by the four 1D | |
3823 | @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four 1D | |
3824 | @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias | |
3825 | parameters are set by @code{glConvolutionParameter} using the | |
3826 | @code{GL_CONVOLUTION_1D} target and the names | |
3827 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
3828 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors | |
3829 | of four values that are applied to red, green, blue, and alpha, in that | |
3830 | order.) The R, G, B, and A values are not clamped to [0,1] at any time | |
3831 | during this process. | |
3832 | ||
3833 | Each pixel is then converted to the internal format specified by | |
3834 | @var{internalformat}. This conversion simply maps the component values | |
3835 | of the pixel (R, G, B, and A) to the values included in the internal | |
3836 | format (red, green, blue, alpha, luminance, and intensity). The mapping | |
3837 | is as follows: | |
3838 | ||
3839 | ||
3840 | ||
3841 | @table @asis | |
3842 | @item @strong{Internal Format} | |
3843 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
3844 | @strong{Luminance}, @strong{Intensity} | |
3845 | ||
3846 | @item @code{GL_ALPHA} | |
3847 | , , , A , , | |
3848 | ||
3849 | @item @code{GL_LUMINANCE} | |
3850 | , , , , R , | |
3851 | ||
3852 | @item @code{GL_LUMINANCE_ALPHA} | |
3853 | , , , A , R , | |
3854 | ||
3855 | @item @code{GL_INTENSITY} | |
3856 | , , , , , R | |
3857 | ||
3858 | @item @code{GL_RGB} | |
3859 | R , G , B , , , | |
3860 | ||
3861 | @item @code{GL_RGBA} | |
3862 | R , G , B , A , , | |
3863 | ||
3864 | @end table | |
3865 | ||
3866 | The red, green, blue, alpha, luminance, and/or intensity components of | |
3867 | the resulting pixels are stored in floating-point rather than integer | |
3868 | format. | |
3869 | ||
3870 | Pixel ordering is such that lower x screen coordinates correspond to | |
3871 | lower @var{i} filter image coordinates. | |
3872 | ||
3873 | Note that after a convolution is performed, the resulting color | |
3874 | components are also scaled by their corresponding | |
3875 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
3876 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
3877 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
3878 | and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}. | |
3879 | ||
8925f36f AW |
3880 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
3881 | @code{GL_CONVOLUTION_1D}. | |
3882 | ||
3883 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
3884 | of the allowable values. | |
3885 | ||
3886 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
3887 | greater than the maximum supported value. This value may be queried with | |
3888 | @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_1D} | |
3889 | and name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
3890 | ||
3891 | @code{GL_INVALID_OPERATION} is generated if | |
3892 | @code{glCopyConvolutionFilter1D} is executed between the execution of | |
3893 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
3894 | ||
bb894c9d | 3895 | @end deftypefun |
8925f36f | 3896 | |
bb894c9d | 3897 | @deftypefun void glCopyConvolutionFilter2D target internalformat x y width height |
3c9b6116 AW |
3898 | Copy pixels into a two-dimensional convolution filter. |
3899 | ||
8925f36f AW |
3900 | @table @asis |
3901 | @item @var{target} | |
3902 | Must be @code{GL_CONVOLUTION_2D}. | |
3903 | ||
3904 | @item @var{internalformat} | |
3905 | The internal format of the convolution filter kernel. The allowable | |
3906 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, | |
3907 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
3908 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
3909 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3910 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3911 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3912 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3913 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3914 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3915 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3916 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3917 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3918 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3919 | ||
3920 | @item @var{x} | |
3921 | @itemx @var{y} | |
3922 | The window space coordinates of the lower-left coordinate of the pixel | |
3923 | array to copy. | |
3924 | ||
3925 | @item @var{width} | |
3926 | The width of the pixel array to copy. | |
3927 | ||
3928 | @item @var{height} | |
3929 | The height of the pixel array to copy. | |
3930 | ||
3931 | @end table | |
3932 | ||
8925f36f AW |
3933 | @code{glCopyConvolutionFilter2D} defines a two-dimensional convolution |
3934 | filter kernel with pixels from the current @code{GL_READ_BUFFER} (rather | |
3935 | than from main memory, as is the case for @code{glConvolutionFilter2D}). | |
3936 | ||
3937 | The screen-aligned pixel rectangle with lower-left corner at (@var{x},\ | |
3938 | @var{y}), width @var{width} and height @var{height} is used to define | |
3939 | the convolution filter. If any pixels within this region are outside the | |
3940 | window that is associated with the GL context, the values obtained for | |
3941 | those pixels are undefined. | |
3942 | ||
3943 | The pixels in the rectangle are processed exactly as if | |
3944 | @code{glReadPixels} had been called with @var{format} set to RGBA, but | |
3945 | the process stops just before final conversion. The R, G, B, and A | |
3946 | components of each pixel are next scaled by the four 2D | |
3947 | @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four 2D | |
3948 | @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias | |
3949 | parameters are set by @code{glConvolutionParameter} using the | |
3950 | @code{GL_CONVOLUTION_2D} target and the names | |
3951 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
3952 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors | |
3953 | of four values that are applied to red, green, blue, and alpha, in that | |
3954 | order.) The R, G, B, and A values are not clamped to [0,1] at any time | |
3955 | during this process. | |
3956 | ||
3957 | Each pixel is then converted to the internal format specified by | |
3958 | @var{internalformat}. This conversion simply maps the component values | |
3959 | of the pixel (R, G, B, and A) to the values included in the internal | |
3960 | format (red, green, blue, alpha, luminance, and intensity). The mapping | |
3961 | is as follows: | |
3962 | ||
3963 | ||
3964 | ||
3965 | @table @asis | |
3966 | @item @strong{Internal Format} | |
3967 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
3968 | @strong{Luminance}, @strong{Intensity} | |
3969 | ||
3970 | @item @code{GL_ALPHA} | |
3971 | , , , A , , | |
3972 | ||
3973 | @item @code{GL_LUMINANCE} | |
3974 | , , , , R , | |
3975 | ||
3976 | @item @code{GL_LUMINANCE_ALPHA} | |
3977 | , , , A , R , | |
3978 | ||
3979 | @item @code{GL_INTENSITY} | |
3980 | , , , , , R | |
3981 | ||
3982 | @item @code{GL_RGB} | |
3983 | R , G , B , , , | |
3984 | ||
3985 | @item @code{GL_RGBA} | |
3986 | R , G , B , A , , | |
3987 | ||
3988 | @end table | |
3989 | ||
3990 | The red, green, blue, alpha, luminance, and/or intensity components of | |
3991 | the resulting pixels are stored in floating-point rather than integer | |
3992 | format. | |
3993 | ||
3994 | Pixel ordering is such that lower x screen coordinates correspond to | |
3995 | lower @var{i} filter image coordinates, and lower y screen coordinates | |
3996 | correspond to lower @var{j} filter image coordinates. | |
3997 | ||
3998 | Note that after a convolution is performed, the resulting color | |
3999 | components are also scaled by their corresponding | |
4000 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
4001 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
4002 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
4003 | and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}. | |
4004 | ||
8925f36f AW |
4005 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
4006 | @code{GL_CONVOLUTION_2D}. | |
4007 | ||
4008 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
4009 | of the allowable values. | |
4010 | ||
4011 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
4012 | greater than the maximum supported value. This value may be queried with | |
4013 | @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_2D} | |
4014 | and name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
4015 | ||
4016 | @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero | |
4017 | or greater than the maximum supported value. This value may be queried | |
4018 | with @code{glGetConvolutionParameter} using target | |
4019 | @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}. | |
4020 | ||
4021 | @code{GL_INVALID_OPERATION} is generated if | |
4022 | @code{glCopyConvolutionFilter2D} is executed between the execution of | |
4023 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
4024 | ||
bb894c9d | 4025 | @end deftypefun |
8925f36f | 4026 | |
bb894c9d | 4027 | @deftypefun void glCopyPixels x y width height type |
3c9b6116 AW |
4028 | Copy pixels in the frame buffer. |
4029 | ||
8925f36f AW |
4030 | @table @asis |
4031 | @item @var{x} | |
4032 | @itemx @var{y} | |
4033 | Specify the window coordinates of the lower left corner of the | |
4034 | rectangular region of pixels to be copied. | |
4035 | ||
4036 | @item @var{width} | |
4037 | @itemx @var{height} | |
4038 | Specify the dimensions of the rectangular region of pixels to be copied. | |
4039 | Both must be nonnegative. | |
4040 | ||
4041 | @item @var{type} | |
4042 | Specifies whether color values, depth values, or stencil values are to | |
4043 | be copied. Symbolic constants @code{GL_COLOR}, @code{GL_DEPTH}, and | |
4044 | @code{GL_STENCIL} are accepted. | |
4045 | ||
4046 | @end table | |
4047 | ||
8925f36f AW |
4048 | @code{glCopyPixels} copies a screen-aligned rectangle of pixels from the |
4049 | specified frame buffer location to a region relative to the current | |
4050 | raster position. Its operation is well defined only if the entire pixel | |
4051 | source region is within the exposed portion of the window. Results of | |
4052 | copies from outside the window, or from regions of the window that are | |
4053 | not exposed, are hardware dependent and undefined. | |
4054 | ||
4055 | @var{x} and @var{y} specify the window coordinates of the lower left | |
4056 | corner of the rectangular region to be copied. @var{width} and | |
4057 | @var{height} specify the dimensions of the rectangular region to be | |
4058 | copied. Both @var{width} and @var{height} must not be negative. | |
4059 | ||
4060 | Several parameters control the processing of the pixel data while it is | |
4061 | being copied. These parameters are set with three commands: | |
4062 | @code{glPixelTransfer}, @code{glPixelMap}, and @code{glPixelZoom}. This | |
4063 | reference page describes the effects on @code{glCopyPixels} of most, but | |
4064 | not all, of the parameters specified by these three commands. | |
4065 | ||
4066 | @code{glCopyPixels} copies values from each pixel with the lower | |
3c9b6116 AW |
4067 | left-hand corner at @r{(@var{x}+@var{i},@var{y}+@var{j})} for |
4068 | @r{0<=@var{i}<@var{width}} and @r{0<=@var{j}<@var{height}}. This pixel | |
4069 | is said to be the @r{@var{i}}th pixel in the @r{@var{j}}th row. Pixels | |
4070 | are copied in row order from the lowest to the highest row, left to | |
4071 | right in each row. | |
8925f36f AW |
4072 | |
4073 | @var{type} specifies whether color, depth, or stencil data is to be | |
4074 | copied. The details of the transfer for each data type are as follows: | |
4075 | ||
4076 | @table @asis | |
4077 | @item @code{GL_COLOR} | |
4078 | Indices or RGBA colors are read from the buffer currently specified as | |
4079 | the read source buffer (see @code{glReadBuffer}). If the GL is in color | |
4080 | index mode, each index that is read from this buffer is converted to a | |
4081 | fixed-point format with an unspecified number of bits to the right of | |
4082 | the binary point. Each index is then shifted left by | |
4083 | @code{GL_INDEX_SHIFT} bits, and added to @code{GL_INDEX_OFFSET}. If | |
4084 | @code{GL_INDEX_SHIFT} is negative, the shift is to the right. In either | |
4085 | case, zero bits fill otherwise unspecified bit locations in the result. | |
4086 | If @code{GL_MAP_COLOR} is true, the index is replaced with the value | |
4087 | that it references in lookup table @code{GL_PIXEL_MAP_I_TO_I}. Whether | |
4088 | the lookup replacement of the index is done or not, the integer part of | |
3c9b6116 AW |
4089 | the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the |
4090 | number of bits in a color index buffer. | |
8925f36f AW |
4091 | |
4092 | If the GL is in RGBA mode, the red, green, blue, and alpha components of | |
4093 | each pixel that is read are converted to an internal floating-point | |
4094 | format with unspecified precision. The conversion maps the largest | |
4095 | representable component value to 1.0, and component value 0 to 0.0. The | |
4096 | resulting floating-point color values are then multiplied by | |
4097 | @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is RED, | |
4098 | GREEN, BLUE, and ALPHA for the respective color components. The results | |
4099 | are clamped to the range [0,1]. If @code{GL_MAP_COLOR} is true, each | |
4100 | color component is scaled by the size of lookup table | |
4101 | @code{GL_PIXEL_MAP_c_TO_c}, then replaced by the value that it | |
4102 | references in that table. @var{c} is R, G, B, or A. | |
4103 | ||
4104 | If the @code{ARB_imaging} extension is supported, the color values may | |
4105 | be additionally processed by color-table lookups, color-matrix | |
4106 | transformations, and convolution filters. | |
4107 | ||
4108 | The GL then converts the resulting indices or RGBA colors to fragments | |
4109 | by attaching the current raster position @var{z} coordinate and texture | |
4110 | coordinates to each pixel, then assigning window coordinates | |
3c9b6116 AW |
4111 | @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where |
4112 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position, | |
4113 | and the pixel was the @r{@var{i}}th pixel in the @r{@var{j}}th row. | |
4114 | These pixel fragments are then treated just like the fragments generated | |
4115 | by rasterizing points, lines, or polygons. Texture mapping, fog, and all | |
4116 | the fragment operations are applied before the fragments are written to | |
4117 | the frame buffer. | |
8925f36f AW |
4118 | |
4119 | @item @code{GL_DEPTH} | |
4120 | Depth values are read from the depth buffer and converted directly to an | |
4121 | internal floating-point format with unspecified precision. The resulting | |
4122 | floating-point depth value is then multiplied by @code{GL_DEPTH_SCALE} | |
4123 | and added to @code{GL_DEPTH_BIAS}. The result is clamped to the range | |
4124 | [0,1]. | |
4125 | ||
4126 | The GL then converts the resulting depth components to fragments by | |
4127 | attaching the current raster position color or color index and texture | |
4128 | coordinates to each pixel, then assigning window coordinates | |
3c9b6116 AW |
4129 | @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where |
4130 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position, | |
4131 | and the pixel was the @r{@var{i}}th pixel in the @r{@var{j}}th row. | |
4132 | These pixel fragments are then treated just like the fragments generated | |
4133 | by rasterizing points, lines, or polygons. Texture mapping, fog, and all | |
4134 | the fragment operations are applied before the fragments are written to | |
4135 | the frame buffer. | |
8925f36f AW |
4136 | |
4137 | @item @code{GL_STENCIL} | |
4138 | Stencil indices are read from the stencil buffer and converted to an | |
4139 | internal fixed-point format with an unspecified number of bits to the | |
4140 | right of the binary point. Each fixed-point index is then shifted left | |
4141 | by @code{GL_INDEX_SHIFT} bits, and added to @code{GL_INDEX_OFFSET}. If | |
4142 | @code{GL_INDEX_SHIFT} is negative, the shift is to the right. In either | |
4143 | case, zero bits fill otherwise unspecified bit locations in the result. | |
4144 | If @code{GL_MAP_STENCIL} is true, the index is replaced with the value | |
4145 | that it references in lookup table @code{GL_PIXEL_MAP_S_TO_S}. Whether | |
4146 | the lookup replacement of the index is done or not, the integer part of | |
3c9b6116 AW |
4147 | the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the |
4148 | number of bits in the stencil buffer. The resulting stencil indices are | |
4149 | then written to the stencil buffer such that the index read from the | |
4150 | @r{@var{i}}th location of the @r{@var{j}}th row is written to location | |
4151 | @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where | |
4152 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position. | |
8925f36f AW |
4153 | Only the pixel ownership test, the scissor test, and the stencil |
4154 | writemask affect these write operations. | |
4155 | ||
4156 | @end table | |
4157 | ||
4158 | The rasterization described thus far assumes pixel zoom factors of 1.0. | |
3c9b6116 AW |
4159 | If @code{glPixelZoom} is used to change the @r{@var{x}} and @r{@var{y}} |
4160 | pixel zoom factors, pixels are converted to fragments as follows. If | |
4161 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position, | |
4162 | and a given pixel is in the @r{@var{i}}th location in the @r{@var{j}}th | |
4163 | row of the source pixel rectangle, then fragments are generated for | |
4164 | pixels whose centers are in the rectangle with corners at | |
8925f36f | 4165 | |
3c9b6116 | 4166 | @r{(@var{x}_@var{r}+@var{zoom}_@var{x},@var{i},@var{y}_@var{r}+@var{zoom}_@var{y},@var{j})} |
8925f36f AW |
4167 | |
4168 | and | |
4169 | ||
3c9b6116 | 4170 | @r{(@var{x}_@var{r}+@var{zoom}_@var{x},(@var{i}+1,),@var{y}_@var{r}+@var{zoom}_@var{y},(@var{j}+1,))} |
8925f36f | 4171 | |
3c9b6116 AW |
4172 | where @r{@var{zoom}_@var{x}} is the value of @code{GL_ZOOM_X} and |
4173 | @r{@var{zoom}_@var{y}} is the value of @code{GL_ZOOM_Y}. | |
8925f36f | 4174 | |
8925f36f AW |
4175 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted |
4176 | value. | |
4177 | ||
4178 | @code{GL_INVALID_VALUE} is generated if either @var{width} or | |
4179 | @var{height} is negative. | |
4180 | ||
4181 | @code{GL_INVALID_OPERATION} is generated if @var{type} is | |
4182 | @code{GL_DEPTH} and there is no depth buffer. | |
4183 | ||
4184 | @code{GL_INVALID_OPERATION} is generated if @var{type} is | |
4185 | @code{GL_STENCIL} and there is no stencil buffer. | |
4186 | ||
4187 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyPixels} is | |
4188 | executed between the execution of @code{glBegin} and the corresponding | |
4189 | execution of @code{glEnd}. | |
4190 | ||
bb894c9d | 4191 | @end deftypefun |
8925f36f | 4192 | |
bb894c9d | 4193 | @deftypefun void glCopyTexImage1D target level internalformat x y width border |
3c9b6116 AW |
4194 | Copy pixels into a 1D texture image. |
4195 | ||
8925f36f AW |
4196 | @table @asis |
4197 | @item @var{target} | |
4198 | Specifies the target texture. Must be @code{GL_TEXTURE_1D}. | |
4199 | ||
4200 | @item @var{level} | |
4201 | Specifies the level-of-detail number. Level 0 is the base image level. | |
4202 | Level @var{n} is the @var{n}th mipmap reduction image. | |
4203 | ||
4204 | @item @var{internalformat} | |
4205 | Specifies the internal format of the texture. Must be one of the | |
4206 | following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4}, | |
4207 | @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16}, | |
4208 | @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_LUMINANCE}, | |
4209 | @code{GL_COMPRESSED_LUMINANCE_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
4210 | @code{GL_COMPRESSED_RGB}, @code{GL_COMPRESSED_RGBA}, | |
4211 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
4212 | @code{GL_DEPTH_COMPONENT24}, @code{GL_DEPTH_COMPONENT32}, | |
4213 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, | |
4214 | @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
4215 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
4216 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
4217 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
4218 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
4219 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_RGB}, | |
4220 | @code{GL_R3_G3_B2}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
4221 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
4222 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
4223 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, @code{GL_RGBA16}, | |
4224 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
4225 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
4226 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
4227 | ||
4228 | @item @var{x} | |
4229 | @itemx @var{y} | |
4230 | Specify the window coordinates of the left corner of the row of pixels | |
4231 | to be copied. | |
4232 | ||
4233 | @item @var{width} | |
4234 | Specifies the width of the texture image. Must be 0 or | |
3c9b6116 AW |
4235 | @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. The height |
4236 | of the texture image is 1. | |
8925f36f AW |
4237 | |
4238 | @item @var{border} | |
4239 | Specifies the width of the border. Must be either 0 or 1. | |
4240 | ||
4241 | @end table | |
4242 | ||
8925f36f AW |
4243 | @code{glCopyTexImage1D} defines a one-dimensional texture image with |
4244 | pixels from the current @code{GL_READ_BUFFER}. | |
4245 | ||
3c9b6116 AW |
4246 | The screen-aligned pixel row with left corner at @r{(@var{x},@var{y})} |
4247 | and with a length of @r{@var{width}+2(@var{border},)} defines the | |
4248 | texture array at the mipmap level specified by @var{level}. | |
4249 | @var{internalformat} specifies the internal format of the texture array. | |
8925f36f AW |
4250 | |
4251 | The pixels in the row are processed exactly as if @code{glCopyPixels} | |
4252 | had been called, but the process stops just before final conversion. At | |
3c9b6116 AW |
4253 | this point all pixel component values are clamped to the range @r{[0,1]} |
4254 | and then converted to the texture's internal format for storage in the | |
4255 | texel array. | |
8925f36f | 4256 | |
3c9b6116 | 4257 | Pixel ordering is such that lower @r{@var{x}} screen coordinates |
8925f36f AW |
4258 | correspond to lower texture coordinates. |
4259 | ||
4260 | If any of the pixels within the specified row of the current | |
4261 | @code{GL_READ_BUFFER} are outside the window associated with the current | |
4262 | rendering context, then the values obtained for those pixels are | |
4263 | undefined. | |
4264 | ||
4265 | @code{glCopyTexImage1D} defines a one-dimensional texture image with | |
4266 | pixels from the current @code{GL_READ_BUFFER}. | |
4267 | ||
4268 | When @var{internalformat} is one of the sRGB types, the GL does not | |
4269 | automatically convert the source pixels to the sRGB color space. In this | |
4270 | case, the @code{glPixelMap} function can be used to accomplish the | |
4271 | conversion. | |
4272 | ||
8925f36f AW |
4273 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
4274 | allowable values. | |
4275 | ||
4276 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4277 | ||
4278 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
4279 | @r{@var{log}_2@var{max}}, where @r{@var{max}} is the returned value of |
4280 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
4281 | |
4282 | @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not an | |
4283 | allowable value. | |
4284 | ||
4285 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or | |
4286 | greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
4287 | ||
4288 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
4289 | not supported and the @var{width} cannot be represented as | |
3c9b6116 | 4290 | @r{2^@var{n}+2(@var{border},)} for some integer value of @var{n}. |
8925f36f AW |
4291 | |
4292 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
4293 | ||
4294 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexImage1D} is | |
4295 | executed between the execution of @code{glBegin} and the corresponding | |
4296 | execution of @code{glEnd}. | |
4297 | ||
4298 | @code{GL_INVALID_OPERATION} is generated if @var{internalformat} is | |
4299 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
4300 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32} and there is | |
4301 | no depth buffer. | |
4302 | ||
bb894c9d | 4303 | @end deftypefun |
8925f36f | 4304 | |
bb894c9d | 4305 | @deftypefun void glCopyTexImage2D target level internalformat x y width height border |
3c9b6116 AW |
4306 | Copy pixels into a 2D texture image. |
4307 | ||
8925f36f AW |
4308 | @table @asis |
4309 | @item @var{target} | |
4310 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, | |
4311 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
4312 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
4313 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
4314 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
4315 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
4316 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
4317 | ||
4318 | @item @var{level} | |
4319 | Specifies the level-of-detail number. Level 0 is the base image level. | |
4320 | Level @var{n} is the @var{n}th mipmap reduction image. | |
4321 | ||
4322 | @item @var{internalformat} | |
4323 | Specifies the internal format of the texture. Must be one of the | |
4324 | following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4}, | |
4325 | @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16}, | |
4326 | @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_LUMINANCE}, | |
4327 | @code{GL_COMPRESSED_LUMINANCE_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
4328 | @code{GL_COMPRESSED_RGB}, @code{GL_COMPRESSED_RGBA}, | |
4329 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
4330 | @code{GL_DEPTH_COMPONENT24}, @code{GL_DEPTH_COMPONENT32}, | |
4331 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, | |
4332 | @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
4333 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
4334 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
4335 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
4336 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
4337 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_RGB}, | |
4338 | @code{GL_R3_G3_B2}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
4339 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
4340 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
4341 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, @code{GL_RGBA16}, | |
4342 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
4343 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
4344 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
4345 | ||
4346 | @item @var{x} | |
4347 | @itemx @var{y} | |
4348 | Specify the window coordinates of the lower left corner of the | |
4349 | rectangular region of pixels to be copied. | |
4350 | ||
4351 | @item @var{width} | |
4352 | Specifies the width of the texture image. Must be 0 or | |
3c9b6116 | 4353 | @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. |
8925f36f AW |
4354 | |
4355 | @item @var{height} | |
4356 | Specifies the height of the texture image. Must be 0 or | |
3c9b6116 | 4357 | @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}. |
8925f36f AW |
4358 | |
4359 | @item @var{border} | |
4360 | Specifies the width of the border. Must be either 0 or 1. | |
4361 | ||
4362 | @end table | |
4363 | ||
8925f36f AW |
4364 | @code{glCopyTexImage2D} defines a two-dimensional texture image, or |
4365 | cube-map texture image with pixels from the current | |
4366 | @code{GL_READ_BUFFER}. | |
4367 | ||
4368 | The screen-aligned pixel rectangle with lower left corner at (@var{x}, | |
3c9b6116 AW |
4369 | @var{y}) and with a width of @r{@var{width}+2(@var{border},)} and a |
4370 | height of @r{@var{height}+2(@var{border},)} defines the texture array | |
4371 | at the mipmap level specified by @var{level}. @var{internalformat} | |
8925f36f AW |
4372 | specifies the internal format of the texture array. |
4373 | ||
4374 | The pixels in the rectangle are processed exactly as if | |
4375 | @code{glCopyPixels} had been called, but the process stops just before | |
4376 | final conversion. At this point all pixel component values are clamped | |
3c9b6116 | 4377 | to the range @r{[0,1]} and then converted to the texture's internal |
8925f36f AW |
4378 | format for storage in the texel array. |
4379 | ||
3c9b6116 AW |
4380 | Pixel ordering is such that lower @r{@var{x}} and @r{@var{y}} screen |
4381 | coordinates correspond to lower @r{@var{s}} and @r{@var{t}} texture | |
4382 | coordinates. | |
8925f36f AW |
4383 | |
4384 | If any of the pixels within the specified rectangle of the current | |
4385 | @code{GL_READ_BUFFER} are outside the window associated with the current | |
4386 | rendering context, then the values obtained for those pixels are | |
4387 | undefined. | |
4388 | ||
4389 | When @var{internalformat} is one of the sRGB types, the GL does not | |
4390 | automatically convert the source pixels to the sRGB color space. In this | |
4391 | case, the @code{glPixelMap} function can be used to accomplish the | |
4392 | conversion. | |
4393 | ||
8925f36f AW |
4394 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
4395 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
4396 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
4397 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
4398 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
4399 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
4400 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
4401 | ||
4402 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4403 | ||
4404 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
4405 | @r{@var{log}_2@var{max}}, where @r{@var{max}} is the returned value of |
4406 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
4407 | |
4408 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or | |
4409 | greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
4410 | ||
4411 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
4412 | not supported and the @var{width} or @var{depth} cannot be represented | |
3c9b6116 | 4413 | as @r{2^@var{k}+2(@var{border},)} for some integer @r{@var{k}}. |
8925f36f AW |
4414 | |
4415 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
4416 | ||
4417 | @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not an | |
4418 | accepted format. | |
4419 | ||
4420 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexImage2D} is | |
4421 | executed between the execution of @code{glBegin} and the corresponding | |
4422 | execution of @code{glEnd}. | |
4423 | ||
4424 | @code{GL_INVALID_OPERATION} is generated if @var{internalformat} is | |
4425 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
4426 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32} and there is | |
4427 | no depth buffer. | |
4428 | ||
bb894c9d | 4429 | @end deftypefun |
8925f36f | 4430 | |
bb894c9d | 4431 | @deftypefun void glCopyTexSubImage1D target level xoffset x y width |
3c9b6116 AW |
4432 | Copy a one-dimensional texture subimage. |
4433 | ||
8925f36f AW |
4434 | @table @asis |
4435 | @item @var{target} | |
4436 | Specifies the target texture. Must be @code{GL_TEXTURE_1D}. | |
4437 | ||
4438 | @item @var{level} | |
4439 | Specifies the level-of-detail number. Level 0 is the base image level. | |
4440 | Level @var{n} is the @var{n}th mipmap reduction image. | |
4441 | ||
4442 | @item @var{xoffset} | |
4443 | Specifies the texel offset within the texture array. | |
4444 | ||
4445 | @item @var{x} | |
4446 | @itemx @var{y} | |
4447 | Specify the window coordinates of the left corner of the row of pixels | |
4448 | to be copied. | |
4449 | ||
4450 | @item @var{width} | |
4451 | Specifies the width of the texture subimage. | |
4452 | ||
4453 | @end table | |
4454 | ||
8925f36f AW |
4455 | @code{glCopyTexSubImage1D} replaces a portion of a one-dimensional |
4456 | texture image with pixels from the current @code{GL_READ_BUFFER} (rather | |
4457 | than from main memory, as is the case for @code{glTexSubImage1D}). | |
4458 | ||
4459 | The screen-aligned pixel row with left corner at (@var{x},\ @var{y}), | |
4460 | and with length @var{width} replaces the portion of the texture array | |
3c9b6116 | 4461 | with x indices @var{xoffset} through @r{@var{xoffset}+@var{width}-1}, |
8925f36f AW |
4462 | inclusive. The destination in the texture array may not include any |
4463 | texels outside the texture array as it was originally specified. | |
4464 | ||
4465 | The pixels in the row are processed exactly as if @code{glCopyPixels} | |
4466 | had been called, but the process stops just before final conversion. At | |
4467 | this point, all pixel component values are clamped to the range | |
3c9b6116 | 4468 | @r{[0,1]} and then converted to the texture's internal format for |
8925f36f AW |
4469 | storage in the texel array. |
4470 | ||
4471 | It is not an error to specify a subtexture with zero width, but such a | |
4472 | specification has no effect. If any of the pixels within the specified | |
4473 | row of the current @code{GL_READ_BUFFER} are outside the read window | |
4474 | associated with the current rendering context, then the values obtained | |
4475 | for those pixels are undefined. | |
4476 | ||
4477 | No change is made to the @var{internalformat}, @var{width}, or | |
4478 | @var{border} parameters of the specified texture array or to texel | |
4479 | values outside the specified subregion. | |
4480 | ||
8925f36f AW |
4481 | @code{GL_INVALID_ENUM} is generated if /@var{target} is not |
4482 | @code{GL_TEXTURE_1D}. | |
4483 | ||
4484 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
4485 | been defined by a previous @code{glTexImage1D} or | |
4486 | @code{glCopyTexImage1D} operation. | |
4487 | ||
4488 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4489 | ||
4490 | @code{GL_INVALID_VALUE} may be generated if | |
3c9b6116 | 4491 | @r{@var{level}>@var{log}_2(@var{max},)}, where @var{max} is the |
8925f36f AW |
4492 | returned value of @code{GL_MAX_TEXTURE_SIZE}. |
4493 | ||
3c9b6116 AW |
4494 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, or |
4495 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, where @r{@var{w}} | |
4496 | is the @code{GL_TEXTURE_WIDTH} and @r{@var{b}} is the | |
8925f36f | 4497 | @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that |
3c9b6116 | 4498 | @r{@var{w}} includes twice the border width. |
8925f36f AW |
4499 | |
4500 | ||
4501 | ||
bb894c9d | 4502 | @end deftypefun |
8925f36f | 4503 | |
bb894c9d | 4504 | @deftypefun void glCopyTexSubImage2D target level xoffset yoffset x y width height |
3c9b6116 AW |
4505 | Copy a two-dimensional texture subimage. |
4506 | ||
8925f36f AW |
4507 | @table @asis |
4508 | @item @var{target} | |
4509 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, | |
4510 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
4511 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
4512 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
4513 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
4514 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
4515 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
4516 | ||
4517 | @item @var{level} | |
4518 | Specifies the level-of-detail number. Level 0 is the base image level. | |
4519 | Level @var{n} is the @var{n}th mipmap reduction image. | |
4520 | ||
4521 | @item @var{xoffset} | |
4522 | Specifies a texel offset in the x direction within the texture array. | |
4523 | ||
4524 | @item @var{yoffset} | |
4525 | Specifies a texel offset in the y direction within the texture array. | |
4526 | ||
4527 | @item @var{x} | |
4528 | @itemx @var{y} | |
4529 | Specify the window coordinates of the lower left corner of the | |
4530 | rectangular region of pixels to be copied. | |
4531 | ||
4532 | @item @var{width} | |
4533 | Specifies the width of the texture subimage. | |
4534 | ||
4535 | @item @var{height} | |
4536 | Specifies the height of the texture subimage. | |
4537 | ||
4538 | @end table | |
4539 | ||
8925f36f AW |
4540 | @code{glCopyTexSubImage2D} replaces a rectangular portion of a |
4541 | two-dimensional texture image or cube-map texture image with pixels from | |
4542 | the current @code{GL_READ_BUFFER} (rather than from main memory, as is | |
4543 | the case for @code{glTexSubImage2D}). | |
4544 | ||
4545 | The screen-aligned pixel rectangle with lower left corner at | |
3c9b6116 AW |
4546 | @r{(@var{x},@var{y})} and with width @var{width} and height @var{height} |
4547 | replaces the portion of the texture array with x indices @var{xoffset} | |
4548 | through @r{@var{xoffset}+@var{width}-1}, inclusive, and y indices | |
4549 | @var{yoffset} through @r{@var{yoffset}+@var{height}-1}, inclusive, at | |
4550 | the mipmap level specified by @var{level}. | |
8925f36f AW |
4551 | |
4552 | The pixels in the rectangle are processed exactly as if | |
4553 | @code{glCopyPixels} had been called, but the process stops just before | |
4554 | final conversion. At this point, all pixel component values are clamped | |
3c9b6116 | 4555 | to the range @r{[0,1]} and then converted to the texture's internal |
8925f36f AW |
4556 | format for storage in the texel array. |
4557 | ||
4558 | The destination rectangle in the texture array may not include any | |
4559 | texels outside the texture array as it was originally specified. It is | |
4560 | not an error to specify a subtexture with zero width or height, but such | |
4561 | a specification has no effect. | |
4562 | ||
4563 | If any of the pixels within the specified rectangle of the current | |
4564 | @code{GL_READ_BUFFER} are outside the read window associated with the | |
4565 | current rendering context, then the values obtained for those pixels are | |
4566 | undefined. | |
4567 | ||
4568 | No change is made to the @var{internalformat}, @var{width}, | |
4569 | @var{height}, or @var{border} parameters of the specified texture array | |
4570 | or to texel values outside the specified subregion. | |
4571 | ||
8925f36f AW |
4572 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
4573 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
4574 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
4575 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
4576 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
4577 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
4578 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
4579 | ||
4580 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
4581 | been defined by a previous @code{glTexImage2D} or | |
4582 | @code{glCopyTexImage2D} operation. | |
4583 | ||
4584 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4585 | ||
4586 | @code{GL_INVALID_VALUE} may be generated if | |
3c9b6116 AW |
4587 | @r{@var{level}>@var{log}_2(@var{max},)}, where @r{@var{max}} is the |
4588 | returned value of @code{GL_MAX_TEXTURE_SIZE}. | |
4589 | ||
4590 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, | |
4591 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, | |
4592 | @r{@var{yoffset}<-@var{b}}, or | |
4593 | @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, where @r{@var{w}} | |
4594 | is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the | |
4595 | @code{GL_TEXTURE_HEIGHT}, and @r{@var{b}} is the | |
8925f36f | 4596 | @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that |
3c9b6116 | 4597 | @r{@var{w}} and @r{@var{h}} include twice the border width. |
8925f36f AW |
4598 | |
4599 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexSubImage2D} | |
4600 | is executed between the execution of @code{glBegin} and the | |
4601 | corresponding execution of @code{glEnd}. | |
4602 | ||
bb894c9d | 4603 | @end deftypefun |
8925f36f | 4604 | |
bb894c9d | 4605 | @deftypefun void glCopyTexSubImage3D target level xoffset yoffset zoffset x y width height |
3c9b6116 AW |
4606 | Copy a three-dimensional texture subimage. |
4607 | ||
8925f36f AW |
4608 | @table @asis |
4609 | @item @var{target} | |
4610 | Specifies the target texture. Must be @code{GL_TEXTURE_3D} | |
4611 | ||
4612 | @item @var{level} | |
4613 | Specifies the level-of-detail number. Level 0 is the base image level. | |
4614 | Level @var{n} is the @var{n}th mipmap reduction image. | |
4615 | ||
4616 | @item @var{xoffset} | |
4617 | Specifies a texel offset in the x direction within the texture array. | |
4618 | ||
4619 | @item @var{yoffset} | |
4620 | Specifies a texel offset in the y direction within the texture array. | |
4621 | ||
4622 | @item @var{zoffset} | |
4623 | Specifies a texel offset in the z direction within the texture array. | |
4624 | ||
4625 | @item @var{x} | |
4626 | @itemx @var{y} | |
4627 | Specify the window coordinates of the lower left corner of the | |
4628 | rectangular region of pixels to be copied. | |
4629 | ||
4630 | @item @var{width} | |
4631 | Specifies the width of the texture subimage. | |
4632 | ||
4633 | @item @var{height} | |
4634 | Specifies the height of the texture subimage. | |
4635 | ||
4636 | @end table | |
4637 | ||
8925f36f AW |
4638 | @code{glCopyTexSubImage3D} replaces a rectangular portion of a |
4639 | three-dimensional texture image with pixels from the current | |
4640 | @code{GL_READ_BUFFER} (rather than from main memory, as is the case for | |
4641 | @code{glTexSubImage3D}). | |
4642 | ||
4643 | The screen-aligned pixel rectangle with lower left corner at (@var{x},\ | |
4644 | @var{y}) and with width @var{width} and height @var{height} replaces the | |
4645 | portion of the texture array with x indices @var{xoffset} through | |
3c9b6116 AW |
4646 | @r{@var{xoffset}+@var{width}-1}, inclusive, and y indices @var{yoffset} |
4647 | through @r{@var{yoffset}+@var{height}-1}, inclusive, at z index | |
4648 | @var{zoffset} and at the mipmap level specified by @var{level}. | |
8925f36f AW |
4649 | |
4650 | The pixels in the rectangle are processed exactly as if | |
4651 | @code{glCopyPixels} had been called, but the process stops just before | |
4652 | final conversion. At this point, all pixel component values are clamped | |
3c9b6116 | 4653 | to the range @r{[0,1]} and then converted to the texture's internal |
8925f36f AW |
4654 | format for storage in the texel array. |
4655 | ||
4656 | The destination rectangle in the texture array may not include any | |
4657 | texels outside the texture array as it was originally specified. It is | |
4658 | not an error to specify a subtexture with zero width or height, but such | |
4659 | a specification has no effect. | |
4660 | ||
4661 | If any of the pixels within the specified rectangle of the current | |
4662 | @code{GL_READ_BUFFER} are outside the read window associated with the | |
4663 | current rendering context, then the values obtained for those pixels are | |
4664 | undefined. | |
4665 | ||
4666 | No change is made to the @var{internalformat}, @var{width}, | |
4667 | @var{height}, @var{depth}, or @var{border} parameters of the specified | |
4668 | texture array or to texel values outside the specified subregion. | |
4669 | ||
8925f36f AW |
4670 | @code{GL_INVALID_ENUM} is generated if /@var{target} is not |
4671 | @code{GL_TEXTURE_3D}. | |
4672 | ||
4673 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
4674 | been defined by a previous @code{glTexImage3D} operation. | |
4675 | ||
4676 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4677 | ||
4678 | @code{GL_INVALID_VALUE} may be generated if | |
3c9b6116 AW |
4679 | @r{@var{level}>@var{log}_2(@var{max},)}, where @r{@var{max}} is the |
4680 | returned value of @code{GL_MAX_3D_TEXTURE_SIZE}. | |
4681 | ||
4682 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, | |
4683 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, | |
4684 | @r{@var{yoffset}<-@var{b}}, | |
4685 | @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, | |
4686 | @r{@var{zoffset}<-@var{b}}, or | |
4687 | @r{(@var{zoffset}+1,)>(@var{d}-@var{b},)}, where @r{@var{w}} is the | |
4688 | @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the @code{GL_TEXTURE_HEIGHT}, | |
4689 | @r{@var{d}} is the @code{GL_TEXTURE_DEPTH}, and @r{@var{b}} is the | |
4690 | @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that | |
4691 | @r{@var{w}}, @r{@var{h}}, and @r{@var{d}} include twice the border | |
4692 | width. | |
8925f36f AW |
4693 | |
4694 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexSubImage3D} | |
4695 | is executed between the execution of @code{glBegin} and the | |
4696 | corresponding execution of @code{glEnd}. | |
4697 | ||
bb894c9d | 4698 | @end deftypefun |
8925f36f | 4699 | |
bb894c9d | 4700 | @deftypefun GLuint glCreateProgram |
3c9b6116 AW |
4701 | Creates a program object. |
4702 | ||
8925f36f AW |
4703 | @code{glCreateProgram} creates an empty program object and returns a |
4704 | non-zero value by which it can be referenced. A program object is an | |
4705 | object to which shader objects can be attached. This provides a | |
4706 | mechanism to specify the shader objects that will be linked to create a | |
4707 | program. It also provides a means for checking the compatibility of the | |
4708 | shaders that will be used to create a program (for instance, checking | |
4709 | the compatibility between a vertex shader and a fragment shader). When | |
4710 | no longer needed as part of a program object, shader objects can be | |
4711 | detached. | |
4712 | ||
4713 | One or more executables are created in a program object by successfully | |
4714 | attaching shader objects to it with @code{glAttachShader}, successfully | |
4715 | compiling the shader objects with @code{glCompileShader}, and | |
4716 | successfully linking the program object with @code{glLinkProgram}. These | |
4717 | executables are made part of current state when @code{glUseProgram} is | |
4718 | called. Program objects can be deleted by calling | |
4719 | @code{glDeleteProgram}. The memory associated with the program object | |
4720 | will be deleted when it is no longer part of current rendering state for | |
4721 | any context. | |
4722 | ||
8925f36f AW |
4723 | This function returns 0 if an error occurs creating the program object. |
4724 | ||
4725 | @code{GL_INVALID_OPERATION} is generated if @code{glCreateProgram} is | |
4726 | executed between the execution of @code{glBegin} and the corresponding | |
4727 | execution of @code{glEnd}. | |
4728 | ||
bb894c9d | 4729 | @end deftypefun |
8925f36f | 4730 | |
bb894c9d | 4731 | @deftypefun GLuint glCreateShader shaderType |
3c9b6116 AW |
4732 | Creates a shader object. |
4733 | ||
8925f36f AW |
4734 | @table @asis |
4735 | @item @var{shaderType} | |
4736 | Specifies the type of shader to be created. Must be either | |
4737 | @code{GL_VERTEX_SHADER} or @code{GL_FRAGMENT_SHADER}. | |
4738 | ||
4739 | @end table | |
4740 | ||
8925f36f AW |
4741 | @code{glCreateShader} creates an empty shader object and returns a |
4742 | non-zero value by which it can be referenced. A shader object is used to | |
4743 | maintain the source code strings that define a shader. @var{shaderType} | |
4744 | indicates the type of shader to be created. Two types of shaders are | |
4745 | supported. A shader of type @code{GL_VERTEX_SHADER} is a shader that is | |
4746 | intended to run on the programmable vertex processor and replace the | |
4747 | fixed functionality vertex processing in OpenGL. A shader of type | |
4748 | @code{GL_FRAGMENT_SHADER} is a shader that is intended to run on the | |
4749 | programmable fragment processor and replace the fixed functionality | |
4750 | fragment processing in OpenGL. | |
4751 | ||
4752 | When created, a shader object's @code{GL_SHADER_TYPE} parameter is set | |
4753 | to either @code{GL_VERTEX_SHADER} or @code{GL_FRAGMENT_SHADER}, | |
4754 | depending on the value of @var{shaderType}. | |
4755 | ||
8925f36f AW |
4756 | This function returns 0 if an error occurs creating the shader object. |
4757 | ||
4758 | @code{GL_INVALID_ENUM} is generated if @var{shaderType} is not an | |
4759 | accepted value. | |
4760 | ||
4761 | @code{GL_INVALID_OPERATION} is generated if @code{glCreateShader} is | |
4762 | executed between the execution of @code{glBegin} and the corresponding | |
4763 | execution of @code{glEnd}. | |
4764 | ||
bb894c9d | 4765 | @end deftypefun |
8925f36f | 4766 | |
bb894c9d | 4767 | @deftypefun void glCullFace mode |
3c9b6116 AW |
4768 | Specify whether front- or back-facing facets can be culled. |
4769 | ||
8925f36f AW |
4770 | @table @asis |
4771 | @item @var{mode} | |
4772 | Specifies whether front- or back-facing facets are candidates for | |
4773 | culling. Symbolic constants @code{GL_FRONT}, @code{GL_BACK}, and | |
4774 | @code{GL_FRONT_AND_BACK} are accepted. The initial value is | |
4775 | @code{GL_BACK}. | |
4776 | ||
4777 | @end table | |
4778 | ||
8925f36f AW |
4779 | @code{glCullFace} specifies whether front- or back-facing facets are |
4780 | culled (as specified by @var{mode}) when facet culling is enabled. Facet | |
4781 | culling is initially disabled. To enable and disable facet culling, call | |
4782 | the @code{glEnable} and @code{glDisable} commands with the argument | |
4783 | @code{GL_CULL_FACE}. Facets include triangles, quadrilaterals, polygons, | |
4784 | and rectangles. | |
4785 | ||
4786 | @code{glFrontFace} specifies which of the clockwise and counterclockwise | |
4787 | facets are front-facing and back-facing. See @code{glFrontFace}. | |
4788 | ||
8925f36f AW |
4789 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
4790 | value. | |
4791 | ||
4792 | @code{GL_INVALID_OPERATION} is generated if @code{glCullFace} is | |
4793 | executed between the execution of @code{glBegin} and the corresponding | |
4794 | execution of @code{glEnd}. | |
4795 | ||
bb894c9d | 4796 | @end deftypefun |
8925f36f | 4797 | |
bb894c9d | 4798 | @deftypefun void glDeleteBuffers n buffers |
3c9b6116 AW |
4799 | Delete named buffer objects. |
4800 | ||
8925f36f AW |
4801 | @table @asis |
4802 | @item @var{n} | |
4803 | Specifies the number of buffer objects to be deleted. | |
4804 | ||
4805 | @item @var{buffers} | |
4806 | Specifies an array of buffer objects to be deleted. | |
4807 | ||
4808 | @end table | |
4809 | ||
8925f36f AW |
4810 | @code{glDeleteBuffers} deletes @var{n} buffer objects named by the |
4811 | elements of the array @var{buffers}. After a buffer object is deleted, | |
4812 | it has no contents, and its name is free for reuse (for example by | |
4813 | @code{glGenBuffers}). If a buffer object that is currently bound is | |
4814 | deleted, the binding reverts to 0 (the absence of any buffer object, | |
4815 | which reverts to client memory usage). | |
4816 | ||
4817 | @code{glDeleteBuffers} silently ignores 0's and names that do not | |
4818 | correspond to existing buffer objects. | |
4819 | ||
8925f36f AW |
4820 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
4821 | ||
4822 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteBuffers} is | |
4823 | executed between the execution of @code{glBegin} and the corresponding | |
4824 | execution of @code{glEnd}. | |
4825 | ||
bb894c9d | 4826 | @end deftypefun |
8925f36f | 4827 | |
bb894c9d | 4828 | @deftypefun void glDeleteLists list range |
3c9b6116 AW |
4829 | Delete a contiguous group of display lists. |
4830 | ||
8925f36f AW |
4831 | @table @asis |
4832 | @item @var{list} | |
4833 | Specifies the integer name of the first display list to delete. | |
4834 | ||
4835 | @item @var{range} | |
4836 | Specifies the number of display lists to delete. | |
4837 | ||
4838 | @end table | |
4839 | ||
8925f36f AW |
4840 | @code{glDeleteLists} causes a contiguous group of display lists to be |
4841 | deleted. @var{list} is the name of the first display list to be deleted, | |
4842 | and @var{range} is the number of display lists to delete. All display | |
3c9b6116 AW |
4843 | lists @r{@var{d}} with @r{@var{list}<=@var{d}<=@var{list}+@var{range}-1} |
4844 | are deleted. | |
8925f36f AW |
4845 | |
4846 | All storage locations allocated to the specified display lists are | |
4847 | freed, and the names are available for reuse at a later time. Names | |
4848 | within the range that do not have an associated display list are | |
4849 | ignored. If @var{range} is 0, nothing happens. | |
4850 | ||
8925f36f AW |
4851 | @code{GL_INVALID_VALUE} is generated if @var{range} is negative. |
4852 | ||
4853 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteLists} is | |
4854 | executed between the execution of @code{glBegin} and the corresponding | |
4855 | execution of @code{glEnd}. | |
4856 | ||
bb894c9d | 4857 | @end deftypefun |
8925f36f | 4858 | |
bb894c9d | 4859 | @deftypefun void glDeleteProgram program |
3c9b6116 AW |
4860 | Deletes a program object. |
4861 | ||
8925f36f AW |
4862 | @table @asis |
4863 | @item @var{program} | |
4864 | Specifies the program object to be deleted. | |
4865 | ||
4866 | @end table | |
4867 | ||
8925f36f AW |
4868 | @code{glDeleteProgram} frees the memory and invalidates the name |
4869 | associated with the program object specified by @var{program.} This | |
4870 | command effectively undoes the effects of a call to | |
4871 | @code{glCreateProgram}. | |
4872 | ||
4873 | If a program object is in use as part of current rendering state, it | |
4874 | will be flagged for deletion, but it will not be deleted until it is no | |
4875 | longer part of current state for any rendering context. If a program | |
4876 | object to be deleted has shader objects attached to it, those shader | |
4877 | objects will be automatically detached but not deleted unless they have | |
4878 | already been flagged for deletion by a previous call to | |
4879 | @code{glDeleteShader}. A value of 0 for @var{program} will be silently | |
4880 | ignored. | |
4881 | ||
4882 | To determine whether a program object has been flagged for deletion, | |
4883 | call @code{glGetProgram} with arguments @var{program} and | |
4884 | @code{GL_DELETE_STATUS}. | |
4885 | ||
8925f36f AW |
4886 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
4887 | generated by OpenGL. | |
4888 | ||
4889 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteProgram} is | |
4890 | executed between the execution of @code{glBegin} and the corresponding | |
4891 | execution of @code{glEnd}. | |
4892 | ||
bb894c9d | 4893 | @end deftypefun |
8925f36f | 4894 | |
bb894c9d | 4895 | @deftypefun void glDeleteQueries n ids |
3c9b6116 AW |
4896 | Delete named query objects. |
4897 | ||
8925f36f AW |
4898 | @table @asis |
4899 | @item @var{n} | |
4900 | Specifies the number of query objects to be deleted. | |
4901 | ||
4902 | @item @var{ids} | |
4903 | Specifies an array of query objects to be deleted. | |
4904 | ||
4905 | @end table | |
4906 | ||
8925f36f AW |
4907 | @code{glDeleteQueries} deletes @var{n} query objects named by the |
4908 | elements of the array @var{ids}. After a query object is deleted, it has | |
4909 | no contents, and its name is free for reuse (for example by | |
4910 | @code{glGenQueries}). | |
4911 | ||
4912 | @code{glDeleteQueries} silently ignores 0's and names that do not | |
4913 | correspond to existing query objects. | |
4914 | ||
8925f36f AW |
4915 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
4916 | ||
4917 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteQueries} is | |
4918 | executed between the execution of @code{glBegin} and the corresponding | |
4919 | execution of @code{glEnd}. | |
4920 | ||
bb894c9d | 4921 | @end deftypefun |
8925f36f | 4922 | |
bb894c9d | 4923 | @deftypefun void glDeleteShader shader |
3c9b6116 AW |
4924 | Deletes a shader object. |
4925 | ||
8925f36f AW |
4926 | @table @asis |
4927 | @item @var{shader} | |
4928 | Specifies the shader object to be deleted. | |
4929 | ||
4930 | @end table | |
4931 | ||
8925f36f AW |
4932 | @code{glDeleteShader} frees the memory and invalidates the name |
4933 | associated with the shader object specified by @var{shader}. This | |
4934 | command effectively undoes the effects of a call to | |
4935 | @code{glCreateShader}. | |
4936 | ||
4937 | If a shader object to be deleted is attached to a program object, it | |
4938 | will be flagged for deletion, but it will not be deleted until it is no | |
4939 | longer attached to any program object, for any rendering context (i.e., | |
4940 | it must be detached from wherever it was attached before it will be | |
4941 | deleted). A value of 0 for @var{shader} will be silently ignored. | |
4942 | ||
4943 | To determine whether an object has been flagged for deletion, call | |
4944 | @code{glGetShader} with arguments @var{shader} and | |
4945 | @code{GL_DELETE_STATUS}. | |
4946 | ||
8925f36f AW |
4947 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
4948 | generated by OpenGL. | |
4949 | ||
4950 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteShader} is | |
4951 | executed between the execution of @code{glBegin} and the corresponding | |
4952 | execution of @code{glEnd}. | |
4953 | ||
bb894c9d | 4954 | @end deftypefun |
8925f36f | 4955 | |
bb894c9d | 4956 | @deftypefun void glDeleteTextures n textures |
3c9b6116 AW |
4957 | Delete named textures. |
4958 | ||
8925f36f AW |
4959 | @table @asis |
4960 | @item @var{n} | |
4961 | Specifies the number of textures to be deleted. | |
4962 | ||
4963 | @item @var{textures} | |
4964 | Specifies an array of textures to be deleted. | |
4965 | ||
4966 | @end table | |
4967 | ||
8925f36f AW |
4968 | @code{glDeleteTextures} deletes @var{n} textures named by the elements |
4969 | of the array @var{textures}. After a texture is deleted, it has no | |
4970 | contents or dimensionality, and its name is free for reuse (for example | |
4971 | by @code{glGenTextures}). If a texture that is currently bound is | |
4972 | deleted, the binding reverts to 0 (the default texture). | |
4973 | ||
4974 | @code{glDeleteTextures} silently ignores 0's and names that do not | |
4975 | correspond to existing textures. | |
4976 | ||
8925f36f AW |
4977 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
4978 | ||
4979 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteTextures} is | |
4980 | executed between the execution of @code{glBegin} and the corresponding | |
4981 | execution of @code{glEnd}. | |
4982 | ||
bb894c9d | 4983 | @end deftypefun |
8925f36f | 4984 | |
bb894c9d | 4985 | @deftypefun void glDepthFunc func |
3c9b6116 AW |
4986 | Specify the value used for depth buffer comparisons. |
4987 | ||
8925f36f AW |
4988 | @table @asis |
4989 | @item @var{func} | |
4990 | Specifies the depth comparison function. Symbolic constants | |
4991 | @code{GL_NEVER}, @code{GL_LESS}, @code{GL_EQUAL}, @code{GL_LEQUAL}, | |
4992 | @code{GL_GREATER}, @code{GL_NOTEQUAL}, @code{GL_GEQUAL}, and | |
4993 | @code{GL_ALWAYS} are accepted. The initial value is @code{GL_LESS}. | |
4994 | ||
4995 | @end table | |
4996 | ||
8925f36f AW |
4997 | @code{glDepthFunc} specifies the function used to compare each incoming |
4998 | pixel depth value with the depth value present in the depth buffer. The | |
4999 | comparison is performed only if depth testing is enabled. (See | |
5000 | @code{glEnable} and @code{glDisable} of @code{GL_DEPTH_TEST}.) | |
5001 | ||
5002 | @var{func} specifies the conditions under which the pixel will be drawn. | |
5003 | The comparison functions are as follows: | |
5004 | ||
5005 | @table @asis | |
5006 | @item @code{GL_NEVER} | |
5007 | Never passes. | |
5008 | ||
5009 | @item @code{GL_LESS} | |
5010 | Passes if the incoming depth value is less than the stored depth value. | |
5011 | ||
5012 | @item @code{GL_EQUAL} | |
5013 | Passes if the incoming depth value is equal to the stored depth value. | |
5014 | ||
5015 | @item @code{GL_LEQUAL} | |
5016 | Passes if the incoming depth value is less than or equal to the stored | |
5017 | depth value. | |
5018 | ||
5019 | @item @code{GL_GREATER} | |
5020 | Passes if the incoming depth value is greater than the stored depth | |
5021 | value. | |
5022 | ||
5023 | @item @code{GL_NOTEQUAL} | |
5024 | Passes if the incoming depth value is not equal to the stored depth | |
5025 | value. | |
5026 | ||
5027 | @item @code{GL_GEQUAL} | |
5028 | Passes if the incoming depth value is greater than or equal to the | |
5029 | stored depth value. | |
5030 | ||
5031 | @item @code{GL_ALWAYS} | |
5032 | Always passes. | |
5033 | ||
5034 | @end table | |
5035 | ||
5036 | The initial value of @var{func} is @code{GL_LESS}. Initially, depth | |
5037 | testing is disabled. If depth testing is disabled or if no depth buffer | |
5038 | exists, it is as if the depth test always passes. | |
5039 | ||
8925f36f AW |
5040 | @code{GL_INVALID_ENUM} is generated if @var{func} is not an accepted |
5041 | value. | |
5042 | ||
5043 | @code{GL_INVALID_OPERATION} is generated if @code{glDepthFunc} is | |
5044 | executed between the execution of @code{glBegin} and the corresponding | |
5045 | execution of @code{glEnd}. | |
5046 | ||
bb894c9d | 5047 | @end deftypefun |
8925f36f | 5048 | |
bb894c9d | 5049 | @deftypefun void glDepthMask flag |
3c9b6116 AW |
5050 | Enable or disable writing into the depth buffer. |
5051 | ||
8925f36f AW |
5052 | @table @asis |
5053 | @item @var{flag} | |
5054 | Specifies whether the depth buffer is enabled for writing. If @var{flag} | |
5055 | is @code{GL_FALSE}, depth buffer writing is disabled. Otherwise, it is | |
5056 | enabled. Initially, depth buffer writing is enabled. | |
5057 | ||
5058 | @end table | |
5059 | ||
8925f36f AW |
5060 | @code{glDepthMask} specifies whether the depth buffer is enabled for |
5061 | writing. If @var{flag} is @code{GL_FALSE}, depth buffer writing is | |
5062 | disabled. Otherwise, it is enabled. Initially, depth buffer writing is | |
5063 | enabled. | |
5064 | ||
8925f36f AW |
5065 | @code{GL_INVALID_OPERATION} is generated if @code{glDepthMask} is |
5066 | executed between the execution of @code{glBegin} and the corresponding | |
5067 | execution of @code{glEnd}. | |
5068 | ||
bb894c9d | 5069 | @end deftypefun |
8925f36f | 5070 | |
bb894c9d | 5071 | @deftypefun void glDepthRange nearVal farVal |
3c9b6116 AW |
5072 | Specify mapping of depth values from normalized device coordinates to |
5073 | window coordinates. | |
5074 | ||
8925f36f AW |
5075 | @table @asis |
5076 | @item @var{nearVal} | |
5077 | Specifies the mapping of the near clipping plane to window coordinates. | |
5078 | The initial value is 0. | |
5079 | ||
5080 | @item @var{farVal} | |
5081 | Specifies the mapping of the far clipping plane to window coordinates. | |
5082 | The initial value is 1. | |
5083 | ||
5084 | @end table | |
5085 | ||
8925f36f | 5086 | After clipping and division by @var{w}, depth coordinates range from |
3c9b6116 | 5087 | @r{-1} to 1, corresponding to the near and far clipping planes. |
8925f36f AW |
5088 | @code{glDepthRange} specifies a linear mapping of the normalized depth |
5089 | coordinates in this range to window depth coordinates. Regardless of the | |
5090 | actual depth buffer implementation, window coordinate depth values are | |
5091 | treated as though they range from 0 through 1 (like color components). | |
5092 | Thus, the values accepted by @code{glDepthRange} are both clamped to | |
5093 | this range before they are accepted. | |
5094 | ||
5095 | The setting of (0,1) maps the near plane to 0 and the far plane to 1. | |
5096 | With this mapping, the depth buffer range is fully utilized. | |
5097 | ||
8925f36f AW |
5098 | @code{GL_INVALID_OPERATION} is generated if @code{glDepthRange} is |
5099 | executed between the execution of @code{glBegin} and the corresponding | |
5100 | execution of @code{glEnd}. | |
5101 | ||
bb894c9d | 5102 | @end deftypefun |
8925f36f | 5103 | |
bb894c9d | 5104 | @deftypefun void glDetachShader program shader |
3c9b6116 AW |
5105 | Detaches a shader object from a program object to which it is attached. |
5106 | ||
8925f36f AW |
5107 | @table @asis |
5108 | @item @var{program} | |
5109 | Specifies the program object from which to detach the shader object. | |
5110 | ||
5111 | @item @var{shader} | |
5112 | Specifies the shader object to be detached. | |
5113 | ||
5114 | @end table | |
5115 | ||
8925f36f AW |
5116 | @code{glDetachShader} detaches the shader object specified by |
5117 | @var{shader} from the program object specified by @var{program}. This | |
5118 | command can be used to undo the effect of the command | |
5119 | @code{glAttachShader}. | |
5120 | ||
5121 | If @var{shader} has already been flagged for deletion by a call to | |
5122 | @code{glDeleteShader} and it is not attached to any other program | |
5123 | object, it will be deleted after it has been detached. | |
5124 | ||
8925f36f AW |
5125 | @code{GL_INVALID_VALUE} is generated if either @var{program} or |
5126 | @var{shader} is a value that was not generated by OpenGL. | |
5127 | ||
5128 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
5129 | program object. | |
5130 | ||
5131 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
5132 | object. | |
5133 | ||
5134 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not attached | |
5135 | to @var{program}. | |
5136 | ||
5137 | @code{GL_INVALID_OPERATION} is generated if @code{glDetachShader} is | |
5138 | executed between the execution of @code{glBegin} and the corresponding | |
5139 | execution of @code{glEnd}. | |
5140 | ||
bb894c9d | 5141 | @end deftypefun |
8925f36f | 5142 | |
bb894c9d | 5143 | @deftypefun void glDrawArrays mode first count |
3c9b6116 AW |
5144 | Render primitives from array data. |
5145 | ||
8925f36f AW |
5146 | @table @asis |
5147 | @item @var{mode} | |
5148 | Specifies what kind of primitives to render. Symbolic constants | |
5149 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, | |
5150 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
5151 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
5152 | @code{GL_POLYGON} are accepted. | |
5153 | ||
5154 | @item @var{first} | |
5155 | Specifies the starting index in the enabled arrays. | |
5156 | ||
5157 | @item @var{count} | |
5158 | Specifies the number of indices to be rendered. | |
5159 | ||
5160 | @end table | |
5161 | ||
8925f36f AW |
5162 | @code{glDrawArrays} specifies multiple geometric primitives with very |
5163 | few subroutine calls. Instead of calling a GL procedure to pass each | |
5164 | individual vertex, normal, texture coordinate, edge flag, or color, you | |
5165 | can prespecify separate arrays of vertices, normals, and colors and use | |
5166 | them to construct a sequence of primitives with a single call to | |
5167 | @code{glDrawArrays}. | |
5168 | ||
5169 | When @code{glDrawArrays} is called, it uses @var{count} sequential | |
5170 | elements from each enabled array to construct a sequence of geometric | |
5171 | primitives, beginning with element @var{first}. @var{mode} specifies | |
5172 | what kind of primitives are constructed and how the array elements | |
5173 | construct those primitives. If @code{GL_VERTEX_ARRAY} is not enabled, no | |
5174 | geometric primitives are generated. | |
5175 | ||
5176 | Vertex attributes that are modified by @code{glDrawArrays} have an | |
5177 | unspecified value after @code{glDrawArrays} returns. For example, if | |
5178 | @code{GL_COLOR_ARRAY} is enabled, the value of the current color is | |
5179 | undefined after @code{glDrawArrays} executes. Attributes that aren't | |
5180 | modified remain well defined. | |
5181 | ||
8925f36f AW |
5182 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
5183 | value. | |
5184 | ||
5185 | @code{GL_INVALID_VALUE} is generated if @var{count} is negative. | |
5186 | ||
5187 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5188 | name is bound to an enabled array and the buffer object's data store is | |
5189 | currently mapped. | |
5190 | ||
5191 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawArrays} is | |
5192 | executed between the execution of @code{glBegin} and the corresponding | |
5193 | @code{glEnd}. | |
5194 | ||
bb894c9d | 5195 | @end deftypefun |
8925f36f | 5196 | |
bb894c9d | 5197 | @deftypefun void glDrawBuffers n bufs |
3c9b6116 AW |
5198 | Specifies a list of color buffers to be drawn into. |
5199 | ||
8925f36f AW |
5200 | @table @asis |
5201 | @item @var{n} | |
5202 | Specifies the number of buffers in @var{bufs}. | |
5203 | ||
5204 | @item @var{bufs} | |
5205 | Points to an array of symbolic constants specifying the buffers into | |
5206 | which fragment colors or data values will be written. | |
5207 | ||
5208 | @end table | |
5209 | ||
8925f36f AW |
5210 | @code{glDrawBuffers} defines an array of buffers into which fragment |
5211 | color values or fragment data will be written. If no fragment shader is | |
5212 | active, rendering operations will generate only one fragment color per | |
5213 | fragment and it will be written into each of the buffers specified by | |
5214 | @var{bufs}. If a fragment shader is active and it writes a value to the | |
5215 | output variable @code{gl_FragColor}, then that value will be written | |
5216 | into each of the buffers specified by @var{bufs}. If a fragment shader | |
5217 | is active and it writes a value to one or more elements of the output | |
5218 | array variable @code{gl_FragData[]}, then the value of | |
5219 | @code{gl_FragData[0] } will be written into the first buffer specified | |
5220 | by @var{bufs}, the value of @code{gl_FragData[1] } will be written into | |
5221 | the second buffer specified by @var{bufs}, and so on up to | |
5222 | @code{gl_FragData[n-1]}. The draw buffer used for @code{gl_FragData[n]} | |
5223 | and beyond is implicitly set to be @code{GL_NONE}. | |
5224 | ||
5225 | The symbolic constants contained in @var{bufs} may be any of the | |
5226 | following: | |
5227 | ||
5228 | @table @asis | |
5229 | @item @code{GL_NONE} | |
5230 | The fragment color/data value is not written into any color buffer. | |
5231 | ||
5232 | @item @code{GL_FRONT_LEFT} | |
5233 | The fragment color/data value is written into the front left color | |
5234 | buffer. | |
5235 | ||
5236 | @item @code{GL_FRONT_RIGHT} | |
5237 | The fragment color/data value is written into the front right color | |
5238 | buffer. | |
5239 | ||
5240 | @item @code{GL_BACK_LEFT} | |
5241 | The fragment color/data value is written into the back left color | |
5242 | buffer. | |
5243 | ||
5244 | @item @code{GL_BACK_RIGHT} | |
5245 | The fragment color/data value is written into the back right color | |
5246 | buffer. | |
5247 | ||
5248 | @item @code{GL_AUXi} | |
5249 | The fragment color/data value is written into auxiliary buffer @code{i}. | |
5250 | ||
5251 | @end table | |
5252 | ||
5253 | Except for @code{GL_NONE}, the preceding symbolic constants may not | |
5254 | appear more than once in @var{bufs}. The maximum number of draw buffers | |
5255 | supported is implementation dependent and can be queried by calling | |
5256 | @code{glGet} with the argument @code{GL_MAX_DRAW_BUFFERS}. The number of | |
5257 | auxiliary buffers can be queried by calling @code{glGet} with the | |
5258 | argument @code{GL_AUX_BUFFERS}. | |
5259 | ||
8925f36f AW |
5260 | @code{GL_INVALID_ENUM} is generated if one of the values in @var{bufs} |
5261 | is not an accepted value. | |
5262 | ||
5263 | @code{GL_INVALID_ENUM} is generated if @var{n} is less than 0. | |
5264 | ||
5265 | @code{GL_INVALID_OPERATION} is generated if a symbolic constant other | |
5266 | than @code{GL_NONE} appears more than once in @var{bufs}. | |
5267 | ||
5268 | @code{GL_INVALID_OPERATION} is generated if any of the entries in | |
5269 | @var{bufs} (other than @code{GL_NONE} ) indicates a color buffer that | |
5270 | does not exist in the current GL context. | |
5271 | ||
5272 | @code{GL_INVALID_VALUE} is generated if @var{n} is greater than | |
5273 | @code{GL_MAX_DRAW_BUFFERS}. | |
5274 | ||
5275 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawBuffers} is | |
5276 | executed between the execution of @code{glBegin} and the corresponding | |
5277 | execution of @code{glEnd}. | |
5278 | ||
bb894c9d | 5279 | @end deftypefun |
8925f36f | 5280 | |
bb894c9d | 5281 | @deftypefun void glDrawBuffer mode |
3c9b6116 AW |
5282 | Specify which color buffers are to be drawn into. |
5283 | ||
8925f36f AW |
5284 | @table @asis |
5285 | @item @var{mode} | |
5286 | Specifies up to four color buffers to be drawn into. Symbolic constants | |
5287 | @code{GL_NONE}, @code{GL_FRONT_LEFT}, @code{GL_FRONT_RIGHT}, | |
5288 | @code{GL_BACK_LEFT}, @code{GL_BACK_RIGHT}, @code{GL_FRONT}, | |
5289 | @code{GL_BACK}, @code{GL_LEFT}, @code{GL_RIGHT}, | |
5290 | @code{GL_FRONT_AND_BACK}, and @code{GL_AUX}@var{i}, where @var{i} is | |
5291 | between 0 and the value of @code{GL_AUX_BUFFERS} minus 1, are accepted. | |
5292 | (@code{GL_AUX_BUFFERS} is not the upper limit; use @code{glGet} to query | |
5293 | the number of available aux buffers.) The initial value is | |
5294 | @code{GL_FRONT} for single-buffered contexts, and @code{GL_BACK} for | |
5295 | double-buffered contexts. | |
5296 | ||
5297 | @end table | |
5298 | ||
8925f36f AW |
5299 | When colors are written to the frame buffer, they are written into the |
5300 | color buffers specified by @code{glDrawBuffer}. The specifications are | |
5301 | as follows: | |
5302 | ||
5303 | @table @asis | |
5304 | @item @code{GL_NONE} | |
5305 | No color buffers are written. | |
5306 | ||
5307 | @item @code{GL_FRONT_LEFT} | |
5308 | Only the front left color buffer is written. | |
5309 | ||
5310 | @item @code{GL_FRONT_RIGHT} | |
5311 | Only the front right color buffer is written. | |
5312 | ||
5313 | @item @code{GL_BACK_LEFT} | |
5314 | Only the back left color buffer is written. | |
5315 | ||
5316 | @item @code{GL_BACK_RIGHT} | |
5317 | Only the back right color buffer is written. | |
5318 | ||
5319 | @item @code{GL_FRONT} | |
5320 | Only the front left and front right color buffers are written. If there | |
5321 | is no front right color buffer, only the front left color buffer is | |
5322 | written. | |
5323 | ||
5324 | @item @code{GL_BACK} | |
5325 | Only the back left and back right color buffers are written. If there is | |
5326 | no back right color buffer, only the back left color buffer is written. | |
5327 | ||
5328 | @item @code{GL_LEFT} | |
5329 | Only the front left and back left color buffers are written. If there is | |
5330 | no back left color buffer, only the front left color buffer is written. | |
5331 | ||
5332 | @item @code{GL_RIGHT} | |
5333 | Only the front right and back right color buffers are written. If there | |
5334 | is no back right color buffer, only the front right color buffer is | |
5335 | written. | |
5336 | ||
5337 | @item @code{GL_FRONT_AND_BACK} | |
5338 | All the front and back color buffers (front left, front right, back | |
5339 | left, back right) are written. If there are no back color buffers, only | |
5340 | the front left and front right color buffers are written. If there are | |
5341 | no right color buffers, only the front left and back left color buffers | |
5342 | are written. If there are no right or back color buffers, only the front | |
5343 | left color buffer is written. | |
5344 | ||
5345 | @item @code{GL_AUX}@var{i} | |
5346 | Only auxiliary color buffer @var{i} is written. | |
5347 | ||
5348 | @end table | |
5349 | ||
5350 | If more than one color buffer is selected for drawing, then blending or | |
5351 | logical operations are computed and applied independently for each color | |
5352 | buffer and can produce different results in each buffer. | |
5353 | ||
5354 | Monoscopic contexts include only @var{left} buffers, and stereoscopic | |
5355 | contexts include both @var{left} and @var{right} buffers. Likewise, | |
5356 | single-buffered contexts include only @var{front} buffers, and | |
5357 | double-buffered contexts include both @var{front} and @var{back} | |
5358 | buffers. The context is selected at GL initialization. | |
5359 | ||
8925f36f AW |
5360 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
5361 | value. | |
5362 | ||
5363 | @code{GL_INVALID_OPERATION} is generated if none of the buffers | |
5364 | indicated by @var{mode} exists. | |
5365 | ||
5366 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawBuffer} is | |
5367 | executed between the execution of @code{glBegin} and the corresponding | |
5368 | execution of @code{glEnd}. | |
5369 | ||
bb894c9d | 5370 | @end deftypefun |
8925f36f | 5371 | |
bb894c9d | 5372 | @deftypefun void glDrawElements mode count type indices |
3c9b6116 AW |
5373 | Render primitives from array data. |
5374 | ||
8925f36f AW |
5375 | @table @asis |
5376 | @item @var{mode} | |
5377 | Specifies what kind of primitives to render. Symbolic constants | |
5378 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, | |
5379 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
5380 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
5381 | @code{GL_POLYGON} are accepted. | |
5382 | ||
5383 | @item @var{count} | |
5384 | Specifies the number of elements to be rendered. | |
5385 | ||
5386 | @item @var{type} | |
5387 | Specifies the type of the values in @var{indices}. Must be one of | |
5388 | @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or | |
5389 | @code{GL_UNSIGNED_INT}. | |
5390 | ||
5391 | @item @var{indices} | |
5392 | Specifies a pointer to the location where the indices are stored. | |
5393 | ||
5394 | @end table | |
5395 | ||
8925f36f AW |
5396 | @code{glDrawElements} specifies multiple geometric primitives with very |
5397 | few subroutine calls. Instead of calling a GL function to pass each | |
5398 | individual vertex, normal, texture coordinate, edge flag, or color, you | |
5399 | can prespecify separate arrays of vertices, normals, and so on, and use | |
5400 | them to construct a sequence of primitives with a single call to | |
5401 | @code{glDrawElements}. | |
5402 | ||
5403 | When @code{glDrawElements} is called, it uses @var{count} sequential | |
5404 | elements from an enabled array, starting at @var{indices} to construct a | |
5405 | sequence of geometric primitives. @var{mode} specifies what kind of | |
5406 | primitives are constructed and how the array elements construct these | |
5407 | primitives. If more than one array is enabled, each is used. If | |
5408 | @code{GL_VERTEX_ARRAY} is not enabled, no geometric primitives are | |
5409 | constructed. | |
5410 | ||
5411 | Vertex attributes that are modified by @code{glDrawElements} have an | |
5412 | unspecified value after @code{glDrawElements} returns. For example, if | |
5413 | @code{GL_COLOR_ARRAY} is enabled, the value of the current color is | |
5414 | undefined after @code{glDrawElements} executes. Attributes that aren't | |
5415 | modified maintain their previous values. | |
5416 | ||
8925f36f AW |
5417 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
5418 | value. | |
5419 | ||
5420 | @code{GL_INVALID_VALUE} is generated if @var{count} is negative. | |
5421 | ||
5422 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5423 | name is bound to an enabled array or the element array and the buffer | |
5424 | object's data store is currently mapped. | |
5425 | ||
5426 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawElements} is | |
5427 | executed between the execution of @code{glBegin} and the corresponding | |
5428 | @code{glEnd}. | |
5429 | ||
bb894c9d | 5430 | @end deftypefun |
8925f36f | 5431 | |
bb894c9d | 5432 | @deftypefun void glDrawPixels width height format type data |
3c9b6116 AW |
5433 | Write a block of pixels to the frame buffer. |
5434 | ||
8925f36f AW |
5435 | @table @asis |
5436 | @item @var{width} | |
5437 | @itemx @var{height} | |
5438 | Specify the dimensions of the pixel rectangle to be written into the | |
5439 | frame buffer. | |
5440 | ||
5441 | @item @var{format} | |
5442 | Specifies the format of the pixel data. Symbolic constants | |
5443 | @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, | |
5444 | @code{GL_DEPTH_COMPONENT}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, | |
5445 | @code{GL_BGRA}, @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, | |
5446 | @code{GL_ALPHA}, @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA} are | |
5447 | accepted. | |
5448 | ||
5449 | @item @var{type} | |
5450 | Specifies the data type for @var{data}. Symbolic constants | |
5451 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
5452 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
5453 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
5454 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
5455 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
5456 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
5457 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
5458 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
5459 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
5460 | ||
5461 | @item @var{data} | |
5462 | Specifies a pointer to the pixel data. | |
5463 | ||
5464 | @end table | |
5465 | ||
8925f36f AW |
5466 | @code{glDrawPixels} reads pixel data from memory and writes it into the |
5467 | frame buffer relative to the current raster position, provided that the | |
5468 | raster position is valid. Use @code{glRasterPos} or @code{glWindowPos} | |
5469 | to set the current raster position; use @code{glGet} with argument | |
5470 | @code{GL_CURRENT_RASTER_POSITION_VALID} to determine if the specified | |
5471 | raster position is valid, and @code{glGet} with argument | |
5472 | @code{GL_CURRENT_RASTER_POSITION} to query the raster position. | |
5473 | ||
5474 | Several parameters define the encoding of pixel data in memory and | |
5475 | control the processing of the pixel data before it is placed in the | |
5476 | frame buffer. These parameters are set with four commands: | |
5477 | @code{glPixelStore}, @code{glPixelTransfer}, @code{glPixelMap}, and | |
5478 | @code{glPixelZoom}. This reference page describes the effects on | |
5479 | @code{glDrawPixels} of many, but not all, of the parameters specified by | |
5480 | these four commands. | |
5481 | ||
5482 | Data is read from @var{data} as a sequence of signed or unsigned bytes, | |
5483 | signed or unsigned shorts, signed or unsigned integers, or | |
5484 | single-precision floating-point values, depending on @var{type}. When | |
5485 | @var{type} is one of @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, | |
5486 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
5487 | @code{GL_INT}, or @code{GL_FLOAT} each of these bytes, shorts, integers, | |
5488 | or floating-point values is interpreted as one color or depth component, | |
5489 | or one index, depending on @var{format}. When @var{type} is one of | |
5490 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
5491 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
5492 | @code{GL_UNSIGNED_INT_8_8_8_8}, or @code{GL_UNSIGNED_INT_10_10_10_2}, | |
5493 | each unsigned value is interpreted as containing all the components for | |
5494 | a single pixel, with the color components arranged according to | |
5495 | @var{format}. When @var{type} is one of | |
5496 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
5497 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
5498 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
5499 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, or | |
5500 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}, each unsigned value is | |
5501 | interpreted as containing all color components, specified by | |
5502 | @var{format}, for a single pixel in a reversed order. Indices are always | |
5503 | treated individually. Color components are treated as groups of one, | |
5504 | two, three, or four values, again based on @var{format}. Both individual | |
5505 | indices and groups of components are referred to as pixels. If | |
5506 | @var{type} is @code{GL_BITMAP}, the data must be unsigned bytes, and | |
5507 | @var{format} must be either @code{GL_COLOR_INDEX} or | |
5508 | @code{GL_STENCIL_INDEX}. Each unsigned byte is treated as eight 1-bit | |
5509 | pixels, with bit ordering determined by @code{GL_UNPACK_LSB_FIRST} (see | |
5510 | @code{glPixelStore}). | |
5511 | ||
3c9b6116 | 5512 | @r{@var{width}×@var{height}} pixels are read from memory, starting at |
8925f36f AW |
5513 | location @var{data}. By default, these pixels are taken from adjacent |
5514 | memory locations, except that after all @var{width} pixels are read, the | |
5515 | read pointer is advanced to the next four-byte boundary. The four-byte | |
5516 | row alignment is specified by @code{glPixelStore} with argument | |
5517 | @code{GL_UNPACK_ALIGNMENT}, and it can be set to one, two, four, or | |
5518 | eight bytes. Other pixel store parameters specify different read pointer | |
5519 | advancements, both before the first pixel is read and after all | |
5520 | @var{width} pixels are read. See the @code{glPixelStore} reference page | |
5521 | for details on these options. | |
5522 | ||
5523 | If a non-zero named buffer object is bound to the | |
5524 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
5525 | block of pixels is specified, @var{data} is treated as a byte offset | |
5526 | into the buffer object's data store. | |
5527 | ||
3c9b6116 | 5528 | The @r{@var{width}×@var{height}} pixels that are read from memory are |
8925f36f AW |
5529 | each operated on in the same way, based on the values of several |
5530 | parameters specified by @code{glPixelTransfer} and @code{glPixelMap}. | |
5531 | The details of these operations, as well as the target buffer into which | |
5532 | the pixels are drawn, are specific to the format of the pixels, as | |
5533 | specified by @var{format}. @var{format} can assume one of 13 symbolic | |
5534 | values: | |
5535 | ||
5536 | @table @asis | |
5537 | @item @code{GL_COLOR_INDEX} | |
5538 | Each pixel is a single value, a color index. It is converted to | |
5539 | fixed-point format, with an unspecified number of bits to the right of | |
5540 | the binary point, regardless of the memory data type. Floating-point | |
5541 | values convert to true fixed-point values. Signed and unsigned integer | |
5542 | data is converted with all fraction bits set to 0. Bitmap data convert | |
5543 | to either 0 or 1. | |
5544 | ||
5545 | Each fixed-point index is then shifted left by @code{GL_INDEX_SHIFT} | |
5546 | bits and added to @code{GL_INDEX_OFFSET}. If @code{GL_INDEX_SHIFT} is | |
5547 | negative, the shift is to the right. In either case, zero bits fill | |
5548 | otherwise unspecified bit locations in the result. | |
5549 | ||
5550 | If the GL is in RGBA mode, the resulting index is converted to an RGBA | |
5551 | pixel with the help of the @code{GL_PIXEL_MAP_I_TO_R}, | |
5552 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
5553 | @code{GL_PIXEL_MAP_I_TO_A} tables. If the GL is in color index mode, and | |
5554 | if @code{GL_MAP_COLOR} is true, the index is replaced with the value | |
5555 | that it references in lookup table @code{GL_PIXEL_MAP_I_TO_I}. Whether | |
5556 | the lookup replacement of the index is done or not, the integer part of | |
3c9b6116 AW |
5557 | the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the |
5558 | number of bits in a color index buffer. | |
8925f36f AW |
5559 | |
5560 | The GL then converts the resulting indices or RGBA colors to fragments | |
5561 | by attaching the current raster position @var{z} coordinate and texture | |
3c9b6116 AW |
5562 | coordinates to each pixel, then assigning @r{@var{x}} and @r{@var{y}} |
5563 | window coordinates to the @r{@var{n}}th fragment such that | |
5564 | @r{@var{x}_@var{n}=@var{x}_@var{r}+@var{n}%@var{width}}@r{@var{y}_@var{n}=@var{y}_@var{r}+⌊@var{n}/@var{width},⌋} | |
8925f36f | 5565 | |
3c9b6116 | 5566 | where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster |
8925f36f AW |
5567 | position. These pixel fragments are then treated just like the fragments |
5568 | generated by rasterizing points, lines, or polygons. Texture mapping, | |
5569 | fog, and all the fragment operations are applied before the fragments | |
5570 | are written to the frame buffer. | |
5571 | ||
5572 | @item @code{GL_STENCIL_INDEX} | |
5573 | Each pixel is a single value, a stencil index. It is converted to | |
5574 | fixed-point format, with an unspecified number of bits to the right of | |
5575 | the binary point, regardless of the memory data type. Floating-point | |
5576 | values convert to true fixed-point values. Signed and unsigned integer | |
5577 | data is converted with all fraction bits set to 0. Bitmap data convert | |
5578 | to either 0 or 1. | |
5579 | ||
5580 | Each fixed-point index is then shifted left by @code{GL_INDEX_SHIFT} | |
5581 | bits, and added to @code{GL_INDEX_OFFSET}. If @code{GL_INDEX_SHIFT} is | |
5582 | negative, the shift is to the right. In either case, zero bits fill | |
5583 | otherwise unspecified bit locations in the result. If | |
5584 | @code{GL_MAP_STENCIL} is true, the index is replaced with the value that | |
5585 | it references in lookup table @code{GL_PIXEL_MAP_S_TO_S}. Whether the | |
5586 | lookup replacement of the index is done or not, the integer part of the | |
3c9b6116 | 5587 | index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the |
8925f36f | 5588 | number of bits in the stencil buffer. The resulting stencil indices are |
3c9b6116 AW |
5589 | then written to the stencil buffer such that the @r{@var{n}}th index is |
5590 | written to location | |
8925f36f | 5591 | |
3c9b6116 | 5592 | @r{@var{x}_@var{n}=@var{x}_@var{r}+@var{n}%@var{width}}@r{@var{y}_@var{n}=@var{y}_@var{r}+⌊@var{n}/@var{width},⌋} |
8925f36f | 5593 | |
3c9b6116 | 5594 | where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster |
8925f36f AW |
5595 | position. Only the pixel ownership test, the scissor test, and the |
5596 | stencil writemask affect these write operations. | |
5597 | ||
5598 | @item @code{GL_DEPTH_COMPONENT} | |
5599 | Each pixel is a single-depth component. Floating-point data is converted | |
5600 | directly to an internal floating-point format with unspecified | |
5601 | precision. Signed integer data is mapped linearly to the internal | |
5602 | floating-point format such that the most positive representable integer | |
5603 | value maps to 1.0, and the most negative representable value maps to | |
3c9b6116 AW |
5604 | @r{-1.0}. Unsigned integer data is mapped similarly: the largest integer |
5605 | value maps to 1.0, and 0 maps to 0.0. The resulting floating-point depth | |
5606 | value is then multiplied by @code{GL_DEPTH_SCALE} and added to | |
5607 | @code{GL_DEPTH_BIAS}. The result is clamped to the range @r{[0,1]}. | |
8925f36f AW |
5608 | |
5609 | The GL then converts the resulting depth components to fragments by | |
5610 | attaching the current raster position color or color index and texture | |
3c9b6116 AW |
5611 | coordinates to each pixel, then assigning @r{@var{x}} and @r{@var{y}} |
5612 | window coordinates to the @r{@var{n}}th fragment such that | |
8925f36f | 5613 | |
3c9b6116 | 5614 | @r{@var{x}_@var{n}=@var{x}_@var{r}+@var{n}%@var{width}}@r{@var{y}_@var{n}=@var{y}_@var{r}+⌊@var{n}/@var{width},⌋} |
8925f36f | 5615 | |
3c9b6116 | 5616 | where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster |
8925f36f AW |
5617 | position. These pixel fragments are then treated just like the fragments |
5618 | generated by rasterizing points, lines, or polygons. Texture mapping, | |
5619 | fog, and all the fragment operations are applied before the fragments | |
5620 | are written to the frame buffer. | |
5621 | ||
5622 | @item @code{GL_RGBA} | |
5623 | @item @code{GL_BGRA} | |
5624 | Each pixel is a four-component group: For @code{GL_RGBA}, the red | |
5625 | component is first, followed by green, followed by blue, followed by | |
5626 | alpha; for @code{GL_BGRA} the order is blue, green, red and then alpha. | |
5627 | Floating-point values are converted directly to an internal | |
5628 | floating-point format with unspecified precision. Signed integer values | |
5629 | are mapped linearly to the internal floating-point format such that the | |
5630 | most positive representable integer value maps to 1.0, and the most | |
3c9b6116 AW |
5631 | negative representable value maps to @r{-1.0}. (Note that this mapping |
5632 | does not convert 0 precisely to 0.0.) Unsigned integer data is mapped | |
5633 | similarly: The largest integer value maps to 1.0, and 0 maps to 0.0. The | |
5634 | resulting floating-point color values are then multiplied by | |
8925f36f AW |
5635 | @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is RED, |
5636 | GREEN, BLUE, and ALPHA for the respective color components. The results | |
3c9b6116 | 5637 | are clamped to the range @r{[0,1]}. |
8925f36f AW |
5638 | |
5639 | If @code{GL_MAP_COLOR} is true, each color component is scaled by the | |
5640 | size of lookup table @code{GL_PIXEL_MAP_c_TO_c}, then replaced by the | |
5641 | value that it references in that table. @var{c} is R, G, B, or A | |
5642 | respectively. | |
5643 | ||
5644 | The GL then converts the resulting RGBA colors to fragments by attaching | |
5645 | the current raster position @var{z} coordinate and texture coordinates | |
3c9b6116 AW |
5646 | to each pixel, then assigning @r{@var{x}} and @r{@var{y}} window |
5647 | coordinates to the @r{@var{n}}th fragment such that | |
8925f36f | 5648 | |
3c9b6116 | 5649 | @r{@var{x}_@var{n}=@var{x}_@var{r}+@var{n}%@var{width}}@r{@var{y}_@var{n}=@var{y}_@var{r}+⌊@var{n}/@var{width},⌋} |
8925f36f | 5650 | |
3c9b6116 | 5651 | where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster |
8925f36f AW |
5652 | position. These pixel fragments are then treated just like the fragments |
5653 | generated by rasterizing points, lines, or polygons. Texture mapping, | |
5654 | fog, and all the fragment operations are applied before the fragments | |
5655 | are written to the frame buffer. | |
5656 | ||
5657 | @item @code{GL_RED} | |
5658 | Each pixel is a single red component. This component is converted to the | |
5659 | internal floating-point format in the same way the red component of an | |
5660 | RGBA pixel is. It is then converted to an RGBA pixel with green and blue | |
5661 | set to 0, and alpha set to 1. After this conversion, the pixel is | |
5662 | treated as if it had been read as an RGBA pixel. | |
5663 | ||
5664 | @item @code{GL_GREEN} | |
5665 | Each pixel is a single green component. This component is converted to | |
5666 | the internal floating-point format in the same way the green component | |
5667 | of an RGBA pixel is. It is then converted to an RGBA pixel with red and | |
5668 | blue set to 0, and alpha set to 1. After this conversion, the pixel is | |
5669 | treated as if it had been read as an RGBA pixel. | |
5670 | ||
5671 | @item @code{GL_BLUE} | |
5672 | Each pixel is a single blue component. This component is converted to | |
5673 | the internal floating-point format in the same way the blue component of | |
5674 | an RGBA pixel is. It is then converted to an RGBA pixel with red and | |
5675 | green set to 0, and alpha set to 1. After this conversion, the pixel is | |
5676 | treated as if it had been read as an RGBA pixel. | |
5677 | ||
5678 | @item @code{GL_ALPHA} | |
5679 | Each pixel is a single alpha component. This component is converted to | |
5680 | the internal floating-point format in the same way the alpha component | |
5681 | of an RGBA pixel is. It is then converted to an RGBA pixel with red, | |
5682 | green, and blue set to 0. After this conversion, the pixel is treated as | |
5683 | if it had been read as an RGBA pixel. | |
5684 | ||
5685 | @item @code{GL_RGB} | |
5686 | @item @code{GL_BGR} | |
5687 | Each pixel is a three-component group: red first, followed by green, | |
5688 | followed by blue; for @code{GL_BGR}, the first component is blue, | |
5689 | followed by green and then red. Each component is converted to the | |
5690 | internal floating-point format in the same way the red, green, and blue | |
5691 | components of an RGBA pixel are. The color triple is converted to an | |
5692 | RGBA pixel with alpha set to 1. After this conversion, the pixel is | |
5693 | treated as if it had been read as an RGBA pixel. | |
5694 | ||
5695 | @item @code{GL_LUMINANCE} | |
5696 | Each pixel is a single luminance component. This component is converted | |
5697 | to the internal floating-point format in the same way the red component | |
5698 | of an RGBA pixel is. It is then converted to an RGBA pixel with red, | |
5699 | green, and blue set to the converted luminance value, and alpha set to | |
5700 | 1. After this conversion, the pixel is treated as if it had been read as | |
5701 | an RGBA pixel. | |
5702 | ||
5703 | @item @code{GL_LUMINANCE_ALPHA} | |
5704 | Each pixel is a two-component group: luminance first, followed by alpha. | |
5705 | The two components are converted to the internal floating-point format | |
5706 | in the same way the red component of an RGBA pixel is. They are then | |
5707 | converted to an RGBA pixel with red, green, and blue set to the | |
5708 | converted luminance value, and alpha set to the converted alpha value. | |
5709 | After this conversion, the pixel is treated as if it had been read as an | |
5710 | RGBA pixel. | |
5711 | ||
5712 | @end table | |
5713 | ||
5714 | The following table summarizes the meaning of the valid constants for | |
5715 | the @var{type} parameter: | |
5716 | ||
5717 | ||
5718 | ||
5719 | @table @asis | |
5720 | @item @strong{Type} | |
5721 | @strong{Corresponding Type} | |
5722 | ||
5723 | @item @code{GL_UNSIGNED_BYTE} | |
5724 | unsigned 8-bit integer | |
5725 | ||
5726 | @item @code{GL_BYTE} | |
5727 | signed 8-bit integer | |
5728 | ||
5729 | @item @code{GL_BITMAP} | |
5730 | single bits in unsigned 8-bit integers | |
5731 | ||
5732 | @item @code{GL_UNSIGNED_SHORT} | |
5733 | unsigned 16-bit integer | |
5734 | ||
5735 | @item @code{GL_SHORT} | |
5736 | signed 16-bit integer | |
5737 | ||
5738 | @item @code{GL_UNSIGNED_INT} | |
5739 | unsigned 32-bit integer | |
5740 | ||
5741 | @item @code{GL_INT} | |
5742 | 32-bit integer | |
5743 | ||
5744 | @item @code{GL_FLOAT} | |
5745 | single-precision floating-point | |
5746 | ||
5747 | @item @code{GL_UNSIGNED_BYTE_3_3_2} | |
5748 | unsigned 8-bit integer | |
5749 | ||
5750 | @item @code{GL_UNSIGNED_BYTE_2_3_3_REV} | |
5751 | unsigned 8-bit integer with reversed component ordering | |
5752 | ||
5753 | @item @code{GL_UNSIGNED_SHORT_5_6_5} | |
5754 | unsigned 16-bit integer | |
5755 | ||
5756 | @item @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
5757 | unsigned 16-bit integer with reversed component ordering | |
5758 | ||
5759 | @item @code{GL_UNSIGNED_SHORT_4_4_4_4} | |
5760 | unsigned 16-bit integer | |
5761 | ||
5762 | @item @code{GL_UNSIGNED_SHORT_4_4_4_4_REV} | |
5763 | unsigned 16-bit integer with reversed component ordering | |
5764 | ||
5765 | @item @code{GL_UNSIGNED_SHORT_5_5_5_1} | |
5766 | unsigned 16-bit integer | |
5767 | ||
5768 | @item @code{GL_UNSIGNED_SHORT_1_5_5_5_REV} | |
5769 | unsigned 16-bit integer with reversed component ordering | |
5770 | ||
5771 | @item @code{GL_UNSIGNED_INT_8_8_8_8} | |
5772 | unsigned 32-bit integer | |
5773 | ||
5774 | @item @code{GL_UNSIGNED_INT_8_8_8_8_REV} | |
5775 | unsigned 32-bit integer with reversed component ordering | |
5776 | ||
5777 | @item @code{GL_UNSIGNED_INT_10_10_10_2} | |
5778 | unsigned 32-bit integer | |
5779 | ||
5780 | @item @code{GL_UNSIGNED_INT_2_10_10_10_REV} | |
5781 | unsigned 32-bit integer with reversed component ordering | |
5782 | ||
5783 | @end table | |
5784 | ||
5785 | ||
5786 | ||
5787 | The rasterization described so far assumes pixel zoom factors of 1. If | |
3c9b6116 AW |
5788 | @code{glPixelZoom} is used to change the @r{@var{x}} and @r{@var{y}} |
5789 | pixel zoom factors, pixels are converted to fragments as follows. If | |
5790 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position, | |
5791 | and a given pixel is in the @r{@var{n}}th column and @r{@var{m}}th row | |
5792 | of the pixel rectangle, then fragments are generated for pixels whose | |
5793 | centers are in the rectangle with corners at | |
8925f36f | 5794 | |
3c9b6116 | 5795 | @r{(@var{x}_@var{r}+@var{zoom}_@var{x},@var{n},@var{y}_@var{r}+@var{zoom}_@var{y},@var{m})}@r{(@var{x}_@var{r}+@var{zoom}_@var{x},(@var{n}+1,),@var{y}_@var{r}+@var{zoom}_@var{y},(@var{m}+1,))} |
8925f36f | 5796 | |
3c9b6116 AW |
5797 | where @r{@var{zoom}_@var{x}} is the value of @code{GL_ZOOM_X} and |
5798 | @r{@var{zoom}_@var{y}} is the value of @code{GL_ZOOM_Y}. | |
8925f36f | 5799 | |
8925f36f AW |
5800 | @code{GL_INVALID_ENUM} is generated if @var{format} or @var{type} is not |
5801 | one of the accepted values. | |
5802 | ||
5803 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
5804 | and @var{format} is not either @code{GL_COLOR_INDEX} or | |
5805 | @code{GL_STENCIL_INDEX}. | |
5806 | ||
5807 | @code{GL_INVALID_VALUE} is generated if either @var{width} or | |
5808 | @var{height} is negative. | |
5809 | ||
5810 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
5811 | @code{GL_STENCIL_INDEX} and there is no stencil buffer. | |
5812 | ||
5813 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
5814 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, | |
5815 | @code{GL_RGB}, @code{GL_RGBA}, @code{GL_BGR}, @code{GL_BGRA}, | |
5816 | @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}, and the GL is in | |
5817 | color index mode. | |
5818 | ||
5819 | @code{GL_INVALID_OPERATION} is generated if @var{format} is one of | |
5820 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
5821 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
5822 | and @var{format} is not @code{GL_RGB}. | |
5823 | ||
5824 | @code{GL_INVALID_OPERATION} is generated if @var{format} is one of | |
5825 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
5826 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
5827 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
5828 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
5829 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
5830 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
5831 | ||
5832 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5833 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
5834 | object's data store is currently mapped. | |
5835 | ||
5836 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5837 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
5838 | would be unpacked from the buffer object such that the memory reads | |
5839 | required would exceed the data store size. | |
5840 | ||
5841 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5842 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
5843 | is not evenly divisible into the number of bytes needed to store in | |
5844 | memory a datum indicated by @var{type}. | |
5845 | ||
5846 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawPixels} is | |
5847 | executed between the execution of @code{glBegin} and the corresponding | |
5848 | execution of @code{glEnd}. | |
5849 | ||
bb894c9d | 5850 | @end deftypefun |
8925f36f | 5851 | |
bb894c9d | 5852 | @deftypefun void glDrawRangeElements mode start end count type indices |
3c9b6116 AW |
5853 | Render primitives from array data. |
5854 | ||
8925f36f AW |
5855 | @table @asis |
5856 | @item @var{mode} | |
5857 | Specifies what kind of primitives to render. Symbolic constants | |
5858 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, | |
5859 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
5860 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
5861 | @code{GL_POLYGON} are accepted. | |
5862 | ||
5863 | @item @var{start} | |
5864 | Specifies the minimum array index contained in @var{indices}. | |
5865 | ||
5866 | @item @var{end} | |
5867 | Specifies the maximum array index contained in @var{indices}. | |
5868 | ||
5869 | @item @var{count} | |
5870 | Specifies the number of elements to be rendered. | |
5871 | ||
5872 | @item @var{type} | |
5873 | Specifies the type of the values in @var{indices}. Must be one of | |
5874 | @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or | |
5875 | @code{GL_UNSIGNED_INT}. | |
5876 | ||
5877 | @item @var{indices} | |
5878 | Specifies a pointer to the location where the indices are stored. | |
5879 | ||
5880 | @end table | |
5881 | ||
8925f36f AW |
5882 | @code{glDrawRangeElements} is a restricted form of |
5883 | @code{glDrawElements}. @var{mode}, @var{start}, @var{end}, and | |
5884 | @var{count} match the corresponding arguments to @code{glDrawElements}, | |
5885 | with the additional constraint that all values in the arrays @var{count} | |
5886 | must lie between @var{start} and @var{end}, inclusive. | |
5887 | ||
5888 | Implementations denote recommended maximum amounts of vertex and index | |
5889 | data, which may be queried by calling @code{glGet} with argument | |
5890 | @code{GL_MAX_ELEMENTS_VERTICES} and @code{GL_MAX_ELEMENTS_INDICES}. If | |
3c9b6116 | 5891 | @r{@var{end}-@var{start}+1} is greater than the value of |
8925f36f AW |
5892 | @code{GL_MAX_ELEMENTS_VERTICES}, or if @var{count} is greater than the |
5893 | value of @code{GL_MAX_ELEMENTS_INDICES}, then the call may operate at | |
5894 | reduced performance. There is no requirement that all vertices in the | |
3c9b6116 | 5895 | range @r{[@var{start},@var{end}]} be referenced. However, the |
8925f36f AW |
5896 | implementation may partially process unused vertices, reducing |
5897 | performance from what could be achieved with an optimal index set. | |
5898 | ||
5899 | When @code{glDrawRangeElements} is called, it uses @var{count} | |
5900 | sequential elements from an enabled array, starting at @var{start} to | |
5901 | construct a sequence of geometric primitives. @var{mode} specifies what | |
5902 | kind of primitives are constructed, and how the array elements construct | |
5903 | these primitives. If more than one array is enabled, each is used. If | |
5904 | @code{GL_VERTEX_ARRAY} is not enabled, no geometric primitives are | |
5905 | constructed. | |
5906 | ||
5907 | Vertex attributes that are modified by @code{glDrawRangeElements} have | |
5908 | an unspecified value after @code{glDrawRangeElements} returns. For | |
5909 | example, if @code{GL_COLOR_ARRAY} is enabled, the value of the current | |
5910 | color is undefined after @code{glDrawRangeElements} executes. Attributes | |
5911 | that aren't modified maintain their previous values. | |
5912 | ||
8925f36f | 5913 | It is an error for indices to lie outside the range |
3c9b6116 AW |
5914 | @r{[@var{start},@var{end}]}, but implementations may not check for this |
5915 | situation. Such indices cause implementation-dependent behavior. | |
8925f36f AW |
5916 | |
5917 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted | |
5918 | value. | |
5919 | ||
5920 | @code{GL_INVALID_VALUE} is generated if @var{count} is negative. | |
5921 | ||
3c9b6116 | 5922 | @code{GL_INVALID_VALUE} is generated if @r{@var{end}<@var{start}}. |
8925f36f AW |
5923 | |
5924 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5925 | name is bound to an enabled array or the element array and the buffer | |
5926 | object's data store is currently mapped. | |
5927 | ||
5928 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawRangeElements} | |
5929 | is executed between the execution of @code{glBegin} and the | |
5930 | corresponding @code{glEnd}. | |
5931 | ||
bb894c9d | 5932 | @end deftypefun |
8925f36f | 5933 | |
bb894c9d | 5934 | @deftypefun void glEdgeFlagPointer stride pointer |
3c9b6116 AW |
5935 | Define an array of edge flags. |
5936 | ||
8925f36f AW |
5937 | @table @asis |
5938 | @item @var{stride} | |
5939 | Specifies the byte offset between consecutive edge flags. If | |
5940 | @var{stride} is 0, the edge flags are understood to be tightly packed in | |
5941 | the array. The initial value is 0. | |
5942 | ||
5943 | @item @var{pointer} | |
5944 | Specifies a pointer to the first edge flag in the array. The initial | |
5945 | value is 0. | |
5946 | ||
5947 | @end table | |
5948 | ||
8925f36f AW |
5949 | @code{glEdgeFlagPointer} specifies the location and data format of an |
5950 | array of boolean edge flags to use when rendering. @var{stride} | |
5951 | specifies the byte stride from one edge flag to the next, allowing | |
5952 | vertices and attributes to be packed into a single array or stored in | |
5953 | separate arrays. | |
5954 | ||
5955 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
5956 | target (see @code{glBindBuffer}) while an edge flag array is specified, | |
5957 | @var{pointer} is treated as a byte offset into the buffer object's data | |
5958 | store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING}) | |
5959 | is saved as edge flag vertex array client-side state | |
5960 | (@code{GL_EDGE_FLAG_ARRAY_BUFFER_BINDING}). | |
5961 | ||
5962 | When an edge flag array is specified, @var{stride} and @var{pointer} are | |
5963 | saved as client-side state, in addition to the current vertex array | |
5964 | buffer object binding. | |
5965 | ||
5966 | To enable and disable the edge flag array, call | |
5967 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
5968 | argument @code{GL_EDGE_FLAG_ARRAY}. If enabled, the edge flag array is | |
5969 | used when @code{glDrawArrays}, @code{glMultiDrawArrays}, | |
5970 | @code{glDrawElements}, @code{glMultiDrawElements}, | |
5971 | @code{glDrawRangeElements}, or @code{glArrayElement} is called. | |
5972 | ||
8925f36f AW |
5973 | @code{GL_INVALID_ENUM} is generated if @var{stride} is negative. |
5974 | ||
bb894c9d | 5975 | @end deftypefun |
8925f36f | 5976 | |
bb894c9d | 5977 | @deftypefun void glEdgeFlag flag |
3c9b6116 AW |
5978 | Flag edges as either boundary or nonboundary. |
5979 | ||
8925f36f AW |
5980 | @table @asis |
5981 | @item @var{flag} | |
5982 | Specifies the current edge flag value, either @code{GL_TRUE} or | |
5983 | @code{GL_FALSE}. The initial value is @code{GL_TRUE}. | |
5984 | ||
5985 | @end table | |
5986 | ||
8925f36f AW |
5987 | Each vertex of a polygon, separate triangle, or separate quadrilateral |
5988 | specified between a @code{glBegin}/@code{glEnd} pair is marked as the | |
5989 | start of either a boundary or nonboundary edge. If the current edge flag | |
5990 | is true when the vertex is specified, the vertex is marked as the start | |
5991 | of a boundary edge. Otherwise, the vertex is marked as the start of a | |
5992 | nonboundary edge. @code{glEdgeFlag} sets the edge flag bit to | |
5993 | @code{GL_TRUE} if @var{flag} is @code{GL_TRUE} and to @code{GL_FALSE} | |
5994 | otherwise. | |
5995 | ||
5996 | The vertices of connected triangles and connected quadrilaterals are | |
5997 | always marked as boundary, regardless of the value of the edge flag. | |
5998 | ||
5999 | Boundary and nonboundary edge flags on vertices are significant only if | |
6000 | @code{GL_POLYGON_MODE} is set to @code{GL_POINT} or @code{GL_LINE}. See | |
6001 | @code{glPolygonMode}. | |
6002 | ||
bb894c9d | 6003 | @end deftypefun |
8925f36f | 6004 | |
bb894c9d AW |
6005 | @deftypefun void glEnableClientState cap |
6006 | @deftypefunx void glDisableClientState cap | |
3c9b6116 AW |
6007 | Enable or disable client-side capability. |
6008 | ||
8925f36f AW |
6009 | @table @asis |
6010 | @item @var{cap} | |
6011 | Specifies the capability to enable. Symbolic constants | |
6012 | @code{GL_COLOR_ARRAY}, @code{GL_EDGE_FLAG_ARRAY}, | |
6013 | @code{GL_FOG_COORD_ARRAY}, @code{GL_INDEX_ARRAY}, | |
6014 | @code{GL_NORMAL_ARRAY}, @code{GL_SECONDARY_COLOR_ARRAY}, | |
6015 | @code{GL_TEXTURE_COORD_ARRAY}, and @code{GL_VERTEX_ARRAY} are accepted. | |
6016 | ||
6017 | @end table | |
6018 | ||
8925f36f AW |
6019 | @code{glEnableClientState} and @code{glDisableClientState} enable or |
6020 | disable individual client-side capabilities. By default, all client-side | |
6021 | capabilities are disabled. Both @code{glEnableClientState} and | |
6022 | @code{glDisableClientState} take a single argument, @var{cap}, which can | |
6023 | assume one of the following values: | |
6024 | ||
6025 | @table @asis | |
6026 | @item @code{GL_COLOR_ARRAY} | |
6027 | If enabled, the color array is enabled for writing and used during | |
6028 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6029 | @code{glDrawElements}, | |
6030 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
6031 | @code{glMultiDrawElements} is called. See @code{glColorPointer}. | |
6032 | ||
6033 | @item @code{GL_EDGE_FLAG_ARRAY} | |
6034 | If enabled, the edge flag array is enabled for writing and used during | |
6035 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6036 | @code{glDrawElements}, | |
6037 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
6038 | @code{glMultiDrawElements} is called. See @code{glEdgeFlagPointer}. | |
6039 | ||
6040 | @item @code{GL_FOG_COORD_ARRAY} | |
6041 | If enabled, the fog coordinate array is enabled for writing and used | |
6042 | during rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6043 | @code{glDrawElements}, | |
6044 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
6045 | @code{glMultiDrawElements} is called. See @code{glFogCoordPointer}. | |
6046 | ||
6047 | @item @code{GL_INDEX_ARRAY} | |
6048 | If enabled, the index array is enabled for writing and used during | |
6049 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6050 | @code{glDrawElements}, | |
6051 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
6052 | @code{glMultiDrawElements} is called. See @code{glIndexPointer}. | |
6053 | ||
6054 | @item @code{GL_NORMAL_ARRAY} | |
6055 | If enabled, the normal array is enabled for writing and used during | |
6056 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6057 | @code{glDrawElements}, | |
6058 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
6059 | @code{glMultiDrawElements} is called. See @code{glNormalPointer}. | |
6060 | ||
6061 | @item @code{GL_SECONDARY_COLOR_ARRAY} | |
6062 | If enabled, the secondary color array is enabled for writing and used | |
6063 | during rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6064 | @code{glDrawElements}, | |
6065 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
6066 | @code{glMultiDrawElements} is called. See @code{glColorPointer}. | |
6067 | ||
6068 | @item @code{GL_TEXTURE_COORD_ARRAY} | |
6069 | If enabled, the texture coordinate array is enabled for writing and used | |
6070 | during rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6071 | @code{glDrawElements}, | |
6072 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
6073 | @code{glMultiDrawElements} is called. See @code{glTexCoordPointer}. | |
6074 | ||
6075 | @item @code{GL_VERTEX_ARRAY} | |
6076 | If enabled, the vertex array is enabled for writing and used during | |
6077 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6078 | @code{glDrawElements}, | |
6079 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
6080 | @code{glMultiDrawElements} is called. See @code{glVertexPointer}. | |
6081 | ||
6082 | @end table | |
6083 | ||
8925f36f AW |
6084 | @code{GL_INVALID_ENUM} is generated if @var{cap} is not an accepted |
6085 | value. | |
6086 | ||
6087 | @code{glEnableClientState} is not allowed between the execution of | |
6088 | @code{glBegin} and the corresponding @code{glEnd}, but an error may or | |
6089 | may not be generated. If no error is generated, the behavior is | |
6090 | undefined. | |
6091 | ||
bb894c9d | 6092 | @end deftypefun |
8925f36f | 6093 | |
bb894c9d AW |
6094 | @deftypefun void glEnableVertexAttribArray index |
6095 | @deftypefunx void glDisableVertexAttribArray index | |
3c9b6116 AW |
6096 | Enable or disable a generic vertex attribute array. |
6097 | ||
8925f36f AW |
6098 | @table @asis |
6099 | @item @var{index} | |
6100 | Specifies the index of the generic vertex attribute to be enabled or | |
6101 | disabled. | |
6102 | ||
6103 | @end table | |
6104 | ||
8925f36f AW |
6105 | @code{glEnableVertexAttribArray} enables the generic vertex attribute |
6106 | array specified by @var{index}. @code{glDisableVertexAttribArray} | |
6107 | disables the generic vertex attribute array specified by @var{index}. By | |
6108 | default, all client-side capabilities are disabled, including all | |
6109 | generic vertex attribute arrays. If enabled, the values in the generic | |
6110 | vertex attribute array will be accessed and used for rendering when | |
6111 | calls are made to vertex array commands such as @code{glDrawArrays}, | |
6112 | @code{glDrawElements}, @code{glDrawRangeElements}, | |
6113 | @code{glArrayElement}, @code{glMultiDrawElements}, or | |
6114 | @code{glMultiDrawArrays}. | |
6115 | ||
8925f36f AW |
6116 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or |
6117 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
6118 | ||
6119 | @code{GL_INVALID_OPERATION} is generated if either | |
6120 | @code{glEnableVertexAttribArray } or @code{glDisableVertexAttribArray } | |
6121 | is executed between the execution of @code{glBegin} and the | |
6122 | corresponding execution of @code{glEnd}. | |
6123 | ||
bb894c9d | 6124 | @end deftypefun |
8925f36f | 6125 | |
bb894c9d AW |
6126 | @deftypefun void glEnable cap |
6127 | @deftypefunx void glDisable cap | |
3c9b6116 AW |
6128 | Enable or disable server-side GL capabilities. |
6129 | ||
8925f36f AW |
6130 | @table @asis |
6131 | @item @var{cap} | |
6132 | Specifies a symbolic constant indicating a GL capability. | |
6133 | ||
6134 | @end table | |
6135 | ||
8925f36f AW |
6136 | @code{glEnable} and @code{glDisable} enable and disable various |
6137 | capabilities. Use @code{glIsEnabled} or @code{glGet} to determine the | |
6138 | current setting of any capability. The initial value for each capability | |
6139 | with the exception of @code{GL_DITHER} and @code{GL_MULTISAMPLE} is | |
6140 | @code{GL_FALSE}. The initial value for @code{GL_DITHER} and | |
6141 | @code{GL_MULTISAMPLE} is @code{GL_TRUE}. | |
6142 | ||
6143 | Both @code{glEnable} and @code{glDisable} take a single argument, | |
6144 | @var{cap}, which can assume one of the following values: | |
6145 | ||
6146 | @table @asis | |
6147 | @item @code{GL_ALPHA_TEST} | |
6148 | ||
6149 | ||
6150 | If enabled, do alpha testing. See @code{glAlphaFunc}. | |
6151 | ||
6152 | @item @code{GL_AUTO_NORMAL} | |
6153 | ||
6154 | ||
6155 | If enabled, generate normal vectors when either @code{GL_MAP2_VERTEX_3} | |
6156 | or @code{GL_MAP2_VERTEX_4} is used to generate vertices. See | |
6157 | @code{glMap2}. | |
6158 | ||
6159 | @item @code{GL_BLEND} | |
6160 | ||
6161 | ||
6162 | If enabled, blend the computed fragment color values with the values in | |
6163 | the color buffers. See @code{glBlendFunc}. | |
6164 | ||
6165 | @item @code{GL_CLIP_PLANE}@var{i} | |
6166 | ||
6167 | ||
6168 | If enabled, clip geometry against user-defined clipping plane @var{i}. | |
6169 | See @code{glClipPlane}. | |
6170 | ||
6171 | @item @code{GL_COLOR_LOGIC_OP} | |
6172 | ||
6173 | ||
6174 | If enabled, apply the currently selected logical operation to the | |
6175 | computed fragment color and color buffer values. See @code{glLogicOp}. | |
6176 | ||
6177 | @item @code{GL_COLOR_MATERIAL} | |
6178 | ||
6179 | ||
6180 | If enabled, have one or more material parameters track the current | |
6181 | color. See @code{glColorMaterial}. | |
6182 | ||
6183 | @item @code{GL_COLOR_SUM} | |
6184 | ||
6185 | ||
6186 | If enabled and no fragment shader is active, add the secondary color | |
6187 | value to the computed fragment color. See @code{glSecondaryColor}. | |
6188 | ||
6189 | @item @code{GL_COLOR_TABLE} | |
6190 | ||
6191 | ||
6192 | If enabled, perform a color table lookup on the incoming RGBA color | |
6193 | values. See @code{glColorTable}. | |
6194 | ||
6195 | @item @code{GL_CONVOLUTION_1D} | |
6196 | ||
6197 | ||
6198 | If enabled, perform a 1D convolution operation on incoming RGBA color | |
6199 | values. See @code{glConvolutionFilter1D}. | |
6200 | ||
6201 | @item @code{GL_CONVOLUTION_2D} | |
6202 | ||
6203 | ||
6204 | If enabled, perform a 2D convolution operation on incoming RGBA color | |
6205 | values. See @code{glConvolutionFilter2D}. | |
6206 | ||
6207 | @item @code{GL_CULL_FACE} | |
6208 | ||
6209 | ||
6210 | If enabled, cull polygons based on their winding in window coordinates. | |
6211 | See @code{glCullFace}. | |
6212 | ||
6213 | @item @code{GL_DEPTH_TEST} | |
6214 | ||
6215 | ||
6216 | If enabled, do depth comparisons and update the depth buffer. Note that | |
6217 | even if the depth buffer exists and the depth mask is non-zero, the | |
6218 | depth buffer is not updated if the depth test is disabled. See | |
6219 | @code{glDepthFunc} and @code{glDepthRange}. | |
6220 | ||
6221 | @item @code{GL_DITHER} | |
6222 | ||
6223 | ||
6224 | If enabled, dither color components or indices before they are written | |
6225 | to the color buffer. | |
6226 | ||
6227 | @item @code{GL_FOG} | |
6228 | ||
6229 | ||
6230 | If enabled and no fragment shader is active, blend a fog color into the | |
6231 | post-texturing color. See @code{glFog}. | |
6232 | ||
6233 | @item @code{GL_HISTOGRAM} | |
6234 | ||
6235 | ||
6236 | If enabled, histogram incoming RGBA color values. See | |
6237 | @code{glHistogram}. | |
6238 | ||
6239 | @item @code{GL_INDEX_LOGIC_OP} | |
6240 | ||
6241 | ||
6242 | If enabled, apply the currently selected logical operation to the | |
6243 | incoming index and color buffer indices. See @code{glLogicOp}. | |
6244 | ||
6245 | @item @code{GL_LIGHT}@var{i} | |
6246 | ||
6247 | ||
6248 | If enabled, include light @var{i} in the evaluation of the lighting | |
6249 | equation. See @code{glLightModel} and @code{glLight}. | |
6250 | ||
6251 | @item @code{GL_LIGHTING} | |
6252 | ||
6253 | ||
6254 | If enabled and no vertex shader is active, use the current lighting | |
6255 | parameters to compute the vertex color or index. Otherwise, simply | |
6256 | associate the current color or index with each vertex. See | |
6257 | @code{glMaterial}, @code{glLightModel}, and @code{glLight}. | |
6258 | ||
6259 | @item @code{GL_LINE_SMOOTH} | |
6260 | ||
6261 | ||
6262 | If enabled, draw lines with correct filtering. Otherwise, draw aliased | |
6263 | lines. See @code{glLineWidth}. | |
6264 | ||
6265 | @item @code{GL_LINE_STIPPLE} | |
6266 | ||
6267 | ||
6268 | If enabled, use the current line stipple pattern when drawing lines. See | |
6269 | @code{glLineStipple}. | |
6270 | ||
6271 | @item @code{GL_MAP1_COLOR_4} | |
6272 | ||
6273 | ||
6274 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6275 | @code{glEvalPoint1} generate RGBA values. See @code{glMap1}. | |
6276 | ||
6277 | @item @code{GL_MAP1_INDEX} | |
6278 | ||
6279 | ||
6280 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6281 | @code{glEvalPoint1} generate color indices. See @code{glMap1}. | |
6282 | ||
6283 | @item @code{GL_MAP1_NORMAL} | |
6284 | ||
6285 | ||
6286 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6287 | @code{glEvalPoint1} generate normals. See @code{glMap1}. | |
6288 | ||
6289 | @item @code{GL_MAP1_TEXTURE_COORD_1} | |
6290 | ||
6291 | ||
6292 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6293 | @code{glEvalPoint1} generate @var{s} texture coordinates. See | |
6294 | @code{glMap1}. | |
6295 | ||
6296 | @item @code{GL_MAP1_TEXTURE_COORD_2} | |
6297 | ||
6298 | ||
6299 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6300 | @code{glEvalPoint1} generate @var{s} and @var{t} texture coordinates. | |
6301 | See @code{glMap1}. | |
6302 | ||
6303 | @item @code{GL_MAP1_TEXTURE_COORD_3} | |
6304 | ||
6305 | ||
6306 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6307 | @code{glEvalPoint1} generate @var{s}, @var{t}, and @var{r} texture | |
6308 | coordinates. See @code{glMap1}. | |
6309 | ||
6310 | @item @code{GL_MAP1_TEXTURE_COORD_4} | |
6311 | ||
6312 | ||
6313 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6314 | @code{glEvalPoint1} generate @var{s}, @var{t}, @var{r}, and @var{q} | |
6315 | texture coordinates. See @code{glMap1}. | |
6316 | ||
6317 | @item @code{GL_MAP1_VERTEX_3} | |
6318 | ||
6319 | ||
6320 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6321 | @code{glEvalPoint1} generate @var{x}, @var{y}, and @var{z} vertex | |
6322 | coordinates. See @code{glMap1}. | |
6323 | ||
6324 | @item @code{GL_MAP1_VERTEX_4} | |
6325 | ||
6326 | ||
6327 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6328 | @code{glEvalPoint1} generate homogeneous @var{x}, @var{y}, @var{z}, and | |
6329 | @var{w} vertex coordinates. See @code{glMap1}. | |
6330 | ||
6331 | @item @code{GL_MAP2_COLOR_4} | |
6332 | ||
6333 | ||
6334 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6335 | @code{glEvalPoint2} generate RGBA values. See @code{glMap2}. | |
6336 | ||
6337 | @item @code{GL_MAP2_INDEX} | |
6338 | ||
6339 | ||
6340 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6341 | @code{glEvalPoint2} generate color indices. See @code{glMap2}. | |
6342 | ||
6343 | @item @code{GL_MAP2_NORMAL} | |
6344 | ||
6345 | ||
6346 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6347 | @code{glEvalPoint2} generate normals. See @code{glMap2}. | |
6348 | ||
6349 | @item @code{GL_MAP2_TEXTURE_COORD_1} | |
6350 | ||
6351 | ||
6352 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6353 | @code{glEvalPoint2} generate @var{s} texture coordinates. See | |
6354 | @code{glMap2}. | |
6355 | ||
6356 | @item @code{GL_MAP2_TEXTURE_COORD_2} | |
6357 | ||
6358 | ||
6359 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6360 | @code{glEvalPoint2} generate @var{s} and @var{t} texture coordinates. | |
6361 | See @code{glMap2}. | |
6362 | ||
6363 | @item @code{GL_MAP2_TEXTURE_COORD_3} | |
6364 | ||
6365 | ||
6366 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6367 | @code{glEvalPoint2} generate @var{s}, @var{t}, and @var{r} texture | |
6368 | coordinates. See @code{glMap2}. | |
6369 | ||
6370 | @item @code{GL_MAP2_TEXTURE_COORD_4} | |
6371 | ||
6372 | ||
6373 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6374 | @code{glEvalPoint2} generate @var{s}, @var{t}, @var{r}, and @var{q} | |
6375 | texture coordinates. See @code{glMap2}. | |
6376 | ||
6377 | @item @code{GL_MAP2_VERTEX_3} | |
6378 | ||
6379 | ||
6380 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6381 | @code{glEvalPoint2} generate @var{x}, @var{y}, and @var{z} vertex | |
6382 | coordinates. See @code{glMap2}. | |
6383 | ||
6384 | @item @code{GL_MAP2_VERTEX_4} | |
6385 | ||
6386 | ||
6387 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6388 | @code{glEvalPoint2} generate homogeneous @var{x}, @var{y}, @var{z}, and | |
6389 | @var{w} vertex coordinates. See @code{glMap2}. | |
6390 | ||
6391 | @item @code{GL_MINMAX} | |
6392 | ||
6393 | ||
6394 | If enabled, compute the minimum and maximum values of incoming RGBA | |
6395 | color values. See @code{glMinmax}. | |
6396 | ||
6397 | @item @code{GL_MULTISAMPLE} | |
6398 | ||
6399 | ||
6400 | If enabled, use multiple fragment samples in computing the final color | |
6401 | of a pixel. See @code{glSampleCoverage}. | |
6402 | ||
6403 | @item @code{GL_NORMALIZE} | |
6404 | ||
6405 | ||
6406 | If enabled and no vertex shader is active, normal vectors are normalized | |
6407 | to unit length after transformation and before lighting. This method is | |
6408 | generally less efficient than @code{GL_RESCALE_NORMAL}. See | |
6409 | @code{glNormal} and @code{glNormalPointer}. | |
6410 | ||
6411 | @item @code{GL_POINT_SMOOTH} | |
6412 | ||
6413 | ||
6414 | If enabled, draw points with proper filtering. Otherwise, draw aliased | |
6415 | points. See @code{glPointSize}. | |
6416 | ||
6417 | @item @code{GL_POINT_SPRITE} | |
6418 | ||
6419 | ||
6420 | If enabled, calculate texture coordinates for points based on texture | |
6421 | environment and point parameter settings. Otherwise texture coordinates | |
6422 | are constant across points. | |
6423 | ||
6424 | @item @code{GL_POLYGON_OFFSET_FILL} | |
6425 | ||
6426 | ||
6427 | If enabled, and if the polygon is rendered in @code{GL_FILL} mode, an | |
6428 | offset is added to depth values of a polygon's fragments before the | |
6429 | depth comparison is performed. See @code{glPolygonOffset}. | |
6430 | ||
6431 | @item @code{GL_POLYGON_OFFSET_LINE} | |
6432 | ||
6433 | ||
6434 | If enabled, and if the polygon is rendered in @code{GL_LINE} mode, an | |
6435 | offset is added to depth values of a polygon's fragments before the | |
6436 | depth comparison is performed. See @code{glPolygonOffset}. | |
6437 | ||
6438 | @item @code{GL_POLYGON_OFFSET_POINT} | |
6439 | ||
6440 | ||
6441 | If enabled, an offset is added to depth values of a polygon's fragments | |
6442 | before the depth comparison is performed, if the polygon is rendered in | |
6443 | @code{GL_POINT} mode. See @code{glPolygonOffset}. | |
6444 | ||
6445 | @item @code{GL_POLYGON_SMOOTH} | |
6446 | ||
6447 | ||
6448 | If enabled, draw polygons with proper filtering. Otherwise, draw aliased | |
6449 | polygons. For correct antialiased polygons, an alpha buffer is needed | |
6450 | and the polygons must be sorted front to back. | |
6451 | ||
6452 | @item @code{GL_POLYGON_STIPPLE} | |
6453 | ||
6454 | ||
6455 | If enabled, use the current polygon stipple pattern when rendering | |
6456 | polygons. See @code{glPolygonStipple}. | |
6457 | ||
6458 | @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} | |
6459 | ||
6460 | ||
6461 | If enabled, perform a color table lookup on RGBA color values after | |
6462 | color matrix transformation. See @code{glColorTable}. | |
6463 | ||
6464 | @item @code{GL_POST_CONVOLUTION_COLOR_TABLE} | |
6465 | ||
6466 | ||
6467 | If enabled, perform a color table lookup on RGBA color values after | |
6468 | convolution. See @code{glColorTable}. | |
6469 | ||
6470 | @item @code{GL_RESCALE_NORMAL} | |
6471 | ||
6472 | ||
6473 | If enabled and no vertex shader is active, normal vectors are scaled | |
6474 | after transformation and before lighting by a factor computed from the | |
6475 | modelview matrix. If the modelview matrix scales space uniformly, this | |
6476 | has the effect of restoring the transformed normal to unit length. This | |
6477 | method is generally more efficient than @code{GL_NORMALIZE}. See | |
6478 | @code{glNormal} and @code{glNormalPointer}. | |
6479 | ||
6480 | @item @code{GL_SAMPLE_ALPHA_TO_COVERAGE} | |
6481 | ||
6482 | ||
6483 | If enabled, compute a temporary coverage value where each bit is | |
6484 | determined by the alpha value at the corresponding sample location. The | |
6485 | temporary coverage value is then ANDed with the fragment coverage value. | |
6486 | ||
6487 | @item @code{GL_SAMPLE_ALPHA_TO_ONE} | |
6488 | ||
6489 | ||
6490 | If enabled, each sample alpha value is replaced by the maximum | |
6491 | representable alpha value. | |
6492 | ||
6493 | @item @code{GL_SAMPLE_COVERAGE} | |
6494 | ||
6495 | ||
6496 | If enabled, the fragment's coverage is ANDed with the temporary coverage | |
6497 | value. If @code{GL_SAMPLE_COVERAGE_INVERT} is set to @code{GL_TRUE}, | |
6498 | invert the coverage value. See @code{glSampleCoverage}. | |
6499 | ||
6500 | @item @code{GL_SEPARABLE_2D} | |
6501 | ||
6502 | ||
6503 | If enabled, perform a two-dimensional convolution operation using a | |
6504 | separable convolution filter on incoming RGBA color values. See | |
6505 | @code{glSeparableFilter2D}. | |
6506 | ||
6507 | @item @code{GL_SCISSOR_TEST} | |
6508 | ||
6509 | ||
6510 | If enabled, discard fragments that are outside the scissor rectangle. | |
6511 | See @code{glScissor}. | |
6512 | ||
6513 | @item @code{GL_STENCIL_TEST} | |
6514 | ||
6515 | ||
6516 | If enabled, do stencil testing and update the stencil buffer. See | |
6517 | @code{glStencilFunc} and @code{glStencilOp}. | |
6518 | ||
6519 | @item @code{GL_TEXTURE_1D} | |
6520 | ||
6521 | ||
6522 | If enabled and no fragment shader is active, one-dimensional texturing | |
6523 | is performed (unless two- or three-dimensional or cube-mapped texturing | |
6524 | is also enabled). See @code{glTexImage1D}. | |
6525 | ||
6526 | @item @code{GL_TEXTURE_2D} | |
6527 | ||
6528 | ||
6529 | If enabled and no fragment shader is active, two-dimensional texturing | |
6530 | is performed (unless three-dimensional or cube-mapped texturing is also | |
6531 | enabled). See @code{glTexImage2D}. | |
6532 | ||
6533 | @item @code{GL_TEXTURE_3D} | |
6534 | ||
6535 | ||
6536 | If enabled and no fragment shader is active, three-dimensional texturing | |
6537 | is performed (unless cube-mapped texturing is also enabled). See | |
6538 | @code{glTexImage3D}. | |
6539 | ||
6540 | @item @code{GL_TEXTURE_CUBE_MAP} | |
6541 | ||
6542 | ||
6543 | If enabled and no fragment shader is active, cube-mapped texturing is | |
6544 | performed. See @code{glTexImage2D}. | |
6545 | ||
6546 | @item @code{GL_TEXTURE_GEN_Q} | |
6547 | ||
6548 | ||
6549 | If enabled and no vertex shader is active, the @var{q} texture | |
6550 | coordinate is computed using the texture generation function defined | |
6551 | with @code{glTexGen}. Otherwise, the current @var{q} texture coordinate | |
6552 | is used. See @code{glTexGen}. | |
6553 | ||
6554 | @item @code{GL_TEXTURE_GEN_R} | |
6555 | ||
6556 | ||
6557 | If enabled and no vertex shader is active, the @var{r} texture | |
6558 | coordinate is computed using the texture generation function defined | |
6559 | with @code{glTexGen}. Otherwise, the current @var{r} texture coordinate | |
6560 | is used. See @code{glTexGen}. | |
6561 | ||
6562 | @item @code{GL_TEXTURE_GEN_S} | |
6563 | ||
6564 | ||
6565 | If enabled and no vertex shader is active, the @var{s} texture | |
6566 | coordinate is computed using the texture generation function defined | |
6567 | with @code{glTexGen}. Otherwise, the current @var{s} texture coordinate | |
6568 | is used. See @code{glTexGen}. | |
6569 | ||
6570 | @item @code{GL_TEXTURE_GEN_T} | |
6571 | ||
6572 | ||
6573 | If enabled and no vertex shader is active, the @var{t} texture | |
6574 | coordinate is computed using the texture generation function defined | |
6575 | with @code{glTexGen}. Otherwise, the current @var{t} texture coordinate | |
6576 | is used. See @code{glTexGen}. | |
6577 | ||
6578 | @item @code{GL_VERTEX_PROGRAM_POINT_SIZE} | |
6579 | ||
6580 | ||
6581 | If enabled and a vertex shader is active, then the derived point size is | |
6582 | taken from the (potentially clipped) shader builtin @code{gl_PointSize} | |
6583 | and clamped to the implementation-dependent point size range. | |
6584 | ||
6585 | @item @code{GL_VERTEX_PROGRAM_TWO_SIDE} | |
6586 | ||
6587 | ||
6588 | If enabled and a vertex shader is active, it specifies that the GL will | |
6589 | choose between front and back colors based on the polygon's face | |
6590 | direction of which the vertex being shaded is a part. It has no effect | |
6591 | on points or lines. | |
6592 | ||
6593 | @end table | |
6594 | ||
8925f36f AW |
6595 | @code{GL_INVALID_ENUM} is generated if @var{cap} is not one of the |
6596 | values listed previously. | |
6597 | ||
6598 | @code{GL_INVALID_OPERATION} is generated if @code{glEnable} or | |
6599 | @code{glDisable} is executed between the execution of @code{glBegin} and | |
6600 | the corresponding execution of @code{glEnd}. | |
6601 | ||
bb894c9d | 6602 | @end deftypefun |
8925f36f | 6603 | |
ca09631c AW |
6604 | @deftypefun void glEvalCoord1f u |
6605 | @deftypefunx void glEvalCoord2f u v | |
3c9b6116 AW |
6606 | Evaluate enabled one- and two-dimensional maps. |
6607 | ||
8925f36f AW |
6608 | @table @asis |
6609 | @item @var{u} | |
3c9b6116 AW |
6610 | Specifies a value that is the domain coordinate @r{@var{u}} to the basis |
6611 | function defined in a previous @code{glMap1} or @code{glMap2} command. | |
8925f36f AW |
6612 | |
6613 | @item @var{v} | |
3c9b6116 AW |
6614 | Specifies a value that is the domain coordinate @r{@var{v}} to the basis |
6615 | function defined in a previous @code{glMap2} command. This argument is | |
6616 | not present in a @code{glEvalCoord1} command. | |
8925f36f AW |
6617 | |
6618 | @end table | |
6619 | ||
8925f36f AW |
6620 | @code{glEvalCoord1} evaluates enabled one-dimensional maps at argument |
6621 | @var{u}. @code{glEvalCoord2} does the same for two-dimensional maps | |
6622 | using two domain values, @var{u} and @var{v}. To define a map, call | |
6623 | @code{glMap1} and @code{glMap2}; to enable and disable it, call | |
6624 | @code{glEnable} and @code{glDisable}. | |
6625 | ||
6626 | When one of the @code{glEvalCoord} commands is issued, all currently | |
6627 | enabled maps of the indicated dimension are evaluated. Then, for each | |
6628 | enabled map, it is as if the corresponding GL command had been issued | |
6629 | with the computed value. That is, if @code{GL_MAP1_INDEX} or | |
6630 | @code{GL_MAP2_INDEX} is enabled, a @code{glIndex} command is simulated. | |
6631 | If @code{GL_MAP1_COLOR_4} or @code{GL_MAP2_COLOR_4} is enabled, a | |
6632 | @code{glColor} command is simulated. If @code{GL_MAP1_NORMAL} or | |
6633 | @code{GL_MAP2_NORMAL} is enabled, a normal vector is produced, and if | |
6634 | any of @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2}, | |
6635 | @code{GL_MAP1_TEXTURE_COORD_3}, @code{GL_MAP1_TEXTURE_COORD_4}, | |
6636 | @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2}, | |
6637 | @code{GL_MAP2_TEXTURE_COORD_3}, or @code{GL_MAP2_TEXTURE_COORD_4} is | |
6638 | enabled, then an appropriate @code{glTexCoord} command is simulated. | |
6639 | ||
6640 | For color, color index, normal, and texture coordinates the GL uses | |
6641 | evaluated values instead of current values for those evaluations that | |
6642 | are enabled, and current values otherwise, However, the evaluated values | |
6643 | do not update the current values. Thus, if @code{glVertex} commands are | |
6644 | interspersed with @code{glEvalCoord} commands, the color, normal, and | |
6645 | texture coordinates associated with the @code{glVertex} commands are not | |
6646 | affected by the values generated by the @code{glEvalCoord} commands, but | |
6647 | only by the most recent @code{glColor}, @code{glIndex}, @code{glNormal}, | |
6648 | and @code{glTexCoord} commands. | |
6649 | ||
6650 | No commands are issued for maps that are not enabled. If more than one | |
6651 | texture evaluation is enabled for a particular dimension (for example, | |
6652 | @code{GL_MAP2_TEXTURE_COORD_1} and @code{GL_MAP2_TEXTURE_COORD_2}), then | |
6653 | only the evaluation of the map that produces the larger number of | |
6654 | coordinates (in this case, @code{GL_MAP2_TEXTURE_COORD_2}) is carried | |
6655 | out. @code{GL_MAP1_VERTEX_4} overrides @code{GL_MAP1_VERTEX_3}, and | |
6656 | @code{GL_MAP2_VERTEX_4} overrides @code{GL_MAP2_VERTEX_3}, in the same | |
6657 | manner. If neither a three- nor a four-component vertex map is enabled | |
6658 | for the specified dimension, the @code{glEvalCoord} command is ignored. | |
6659 | ||
6660 | If you have enabled automatic normal generation, by calling | |
6661 | @code{glEnable} with argument @code{GL_AUTO_NORMAL}, @code{glEvalCoord2} | |
6662 | generates surface normals analytically, regardless of the contents or | |
6663 | enabling of the @code{GL_MAP2_NORMAL} map. Let | |
6664 | ||
3c9b6116 | 6665 | @r{@code{m}=∂@code{p},/∂@var{u},,×∂@code{p},/∂@var{v},,} |
8925f36f | 6666 | |
3c9b6116 AW |
6667 | Then the generated normal @r{@code{n}} is |
6668 | @r{@code{n}=@code{m}/∥@code{m},∥,} | |
8925f36f AW |
6669 | |
6670 | If automatic normal generation is disabled, the corresponding normal map | |
6671 | @code{GL_MAP2_NORMAL}, if enabled, is used to produce a normal. If | |
6672 | neither automatic normal generation nor a normal map is enabled, no | |
6673 | normal is generated for @code{glEvalCoord2} commands. | |
6674 | ||
bb894c9d | 6675 | @end deftypefun |
8925f36f | 6676 | |
bb894c9d AW |
6677 | @deftypefun void glEvalMesh1 mode i1 i2 |
6678 | @deftypefunx void glEvalMesh2 mode i1 i2 j1 j2 | |
3c9b6116 AW |
6679 | Compute a one- or two-dimensional grid of points or lines. |
6680 | ||
8925f36f AW |
6681 | @table @asis |
6682 | @item @var{mode} | |
6683 | In @code{glEvalMesh1}, specifies whether to compute a one-dimensional | |
6684 | mesh of points or lines. Symbolic constants @code{GL_POINT} and | |
6685 | @code{GL_LINE} are accepted. | |
6686 | ||
6687 | @item @var{i1} | |
6688 | @itemx @var{i2} | |
6689 | Specify the first and last integer values for grid domain variable | |
3c9b6116 | 6690 | @r{@var{i}}. |
8925f36f AW |
6691 | |
6692 | @end table | |
6693 | ||
8925f36f AW |
6694 | @code{glMapGrid} and @code{glEvalMesh} are used in tandem to efficiently |
6695 | generate and evaluate a series of evenly-spaced map domain values. | |
6696 | @code{glEvalMesh} steps through the integer domain of a one- or | |
6697 | two-dimensional grid, whose range is the domain of the evaluation maps | |
6698 | specified by @code{glMap1} and @code{glMap2}. @var{mode} determines | |
6699 | whether the resulting vertices are connected as points, lines, or filled | |
6700 | polygons. | |
6701 | ||
6702 | In the one-dimensional case, @code{glEvalMesh1}, the mesh is generated | |
6703 | as if the following code fragment were executed: | |
6704 | ||
6705 | where | |
6706 | ||
6707 | @example | |
6708 | ||
6709 | glBegin( @var{type} ); | |
6710 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) | |
3c9b6116 | 6711 | glEvalCoord1( @r{i·Δ@var{u}+@var{u}_1} ); |
8925f36f AW |
6712 | glEnd(); |
6713 | @end example | |
6714 | ||
3c9b6116 | 6715 | @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}} |
8925f36f | 6716 | |
3c9b6116 AW |
6717 | and @r{@var{n}}, @r{@var{u}_1}, and @r{@var{u}_2} are the arguments to |
6718 | the most recent @code{glMapGrid1} command. @var{type} is | |
8925f36f AW |
6719 | @code{GL_POINTS} if @var{mode} is @code{GL_POINT}, or @code{GL_LINES} if |
6720 | @var{mode} is @code{GL_LINE}. | |
6721 | ||
3c9b6116 AW |
6722 | The one absolute numeric requirement is that if @r{@var{i}=@var{n}}, |
6723 | then the value computed from @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly | |
6724 | @r{@var{u}_2}. | |
8925f36f AW |
6725 | |
6726 | In the two-dimensional case, @code{glEvalMesh2}, let .cp | |
3c9b6116 | 6727 | @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}} |
8925f36f | 6728 | |
3c9b6116 | 6729 | @r{Δ@var{v}=(@var{v}_2-@var{v}_1,)/@var{m}} |
8925f36f | 6730 | |
3c9b6116 AW |
6731 | where @r{@var{n}}, @r{@var{u}_1}, @r{@var{u}_2}, @r{@var{m}}, |
6732 | @r{@var{v}_1}, and @r{@var{v}_2} are the arguments to the most recent | |
6733 | @code{glMapGrid2} command. Then, if @var{mode} is @code{GL_FILL}, the | |
6734 | @code{glEvalMesh2} command is equivalent to: | |
8925f36f AW |
6735 | |
6736 | ||
6737 | ||
6738 | @example | |
6739 | ||
6740 | for ( j = @var{j1}; j < @var{j2}; j += 1 ) @{ | |
6741 | glBegin( GL_QUAD_STRIP ); | |
6742 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) @{ | |
3c9b6116 AW |
6743 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
6744 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,(j+1,)·Δ@var{v}+@var{v}_1} ); | |
8925f36f AW |
6745 | @} |
6746 | glEnd(); | |
6747 | @} | |
6748 | @end example | |
6749 | ||
6750 | If @var{mode} is @code{GL_LINE}, then a call to @code{glEvalMesh2} is | |
6751 | equivalent to: | |
6752 | ||
6753 | ||
6754 | ||
6755 | @example | |
6756 | ||
6757 | for ( j = @var{j1}; j <= @var{j2}; j += 1 ) @{ | |
6758 | glBegin( GL_LINE_STRIP ); | |
6759 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) | |
3c9b6116 | 6760 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
8925f36f AW |
6761 | glEnd(); |
6762 | @} | |
6763 | ||
6764 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) @{ | |
6765 | glBegin( GL_LINE_STRIP ); | |
6766 | for ( j = @var{j1}; j <= @var{j1}; j += 1 ) | |
3c9b6116 | 6767 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
8925f36f AW |
6768 | glEnd(); |
6769 | @} | |
6770 | @end example | |
6771 | ||
6772 | And finally, if @var{mode} is @code{GL_POINT}, then a call to | |
6773 | @code{glEvalMesh2} is equivalent to: | |
6774 | ||
6775 | ||
6776 | ||
6777 | @example | |
6778 | ||
6779 | glBegin( GL_POINTS ); | |
6780 | for ( j = @var{j1}; j <= @var{j2}; j += 1 ) | |
6781 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) | |
3c9b6116 | 6782 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
8925f36f AW |
6783 | glEnd(); |
6784 | @end example | |
6785 | ||
6786 | In all three cases, the only absolute numeric requirements are that if | |
3c9b6116 AW |
6787 | @r{@var{i}=@var{n}}, then the value computed from |
6788 | @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}, and if | |
6789 | @r{@var{j}=@var{m}}, then the value computed from | |
6790 | @r{@var{j}·Δ@var{v}+@var{v}_1} is exactly @r{@var{v}_2}. | |
8925f36f | 6791 | |
8925f36f AW |
6792 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
6793 | value. | |
6794 | ||
6795 | @code{GL_INVALID_OPERATION} is generated if @code{glEvalMesh} is | |
6796 | executed between the execution of @code{glBegin} and the corresponding | |
6797 | execution of @code{glEnd}. | |
6798 | ||
bb894c9d | 6799 | @end deftypefun |
8925f36f | 6800 | |
bb894c9d AW |
6801 | @deftypefun void glEvalPoint1 i |
6802 | @deftypefunx void glEvalPoint2 i j | |
3c9b6116 AW |
6803 | Generate and evaluate a single point in a mesh. |
6804 | ||
8925f36f AW |
6805 | @table @asis |
6806 | @item @var{i} | |
3c9b6116 | 6807 | Specifies the integer value for grid domain variable @r{@var{i}}. |
8925f36f AW |
6808 | |
6809 | @item @var{j} | |
3c9b6116 | 6810 | Specifies the integer value for grid domain variable @r{@var{j}} |
8925f36f AW |
6811 | (@code{glEvalPoint2} only). |
6812 | ||
6813 | @end table | |
6814 | ||
8925f36f AW |
6815 | @code{glMapGrid} and @code{glEvalMesh} are used in tandem to efficiently |
6816 | generate and evaluate a series of evenly spaced map domain values. | |
6817 | @code{glEvalPoint} can be used to evaluate a single grid point in the | |
6818 | same gridspace that is traversed by @code{glEvalMesh}. Calling | |
6819 | @code{glEvalPoint1} is equivalent to calling where | |
3c9b6116 | 6820 | @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}} |
8925f36f AW |
6821 | |
6822 | @example | |
6823 | ||
3c9b6116 | 6824 | glEvalCoord1( @r{i·Δ@var{u}+@var{u}_1} ); |
8925f36f AW |
6825 | @end example |
6826 | ||
3c9b6116 AW |
6827 | and @r{@var{n}}, @r{@var{u}_1}, and @r{@var{u}_2} are the arguments to |
6828 | the most recent @code{glMapGrid1} command. The one absolute numeric | |
6829 | requirement is that if @r{@var{i}=@var{n}}, then the value computed from | |
6830 | @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}. | |
8925f36f AW |
6831 | |
6832 | In the two-dimensional case, @code{glEvalPoint2}, let | |
6833 | ||
3c9b6116 | 6834 | @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}@r{Δ@var{v}=(@var{v}_2-@var{v}_1,)/@var{m}} |
8925f36f | 6835 | |
3c9b6116 AW |
6836 | where @r{@var{n}}, @r{@var{u}_1}, @r{@var{u}_2}, @r{@var{m}}, |
6837 | @r{@var{v}_1}, and @r{@var{v}_2} are the arguments to the most recent | |
6838 | @code{glMapGrid2} command. Then the @code{glEvalPoint2} command is | |
6839 | equivalent to calling The only absolute numeric requirements are that if | |
6840 | @r{@var{i}=@var{n}}, then the value computed from | |
6841 | @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}, and if | |
6842 | @r{@var{j}=@var{m}}, then the value computed from | |
6843 | @r{@var{j}·Δ@var{v}+@var{v}_1} is exactly @r{@var{v}_2}. | |
8925f36f AW |
6844 | |
6845 | @example | |
6846 | ||
3c9b6116 | 6847 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
8925f36f AW |
6848 | @end example |
6849 | ||
bb894c9d | 6850 | @end deftypefun |
8925f36f | 6851 | |
bb894c9d | 6852 | @deftypefun void glFeedbackBuffer size type buffer |
3c9b6116 AW |
6853 | Controls feedback mode. |
6854 | ||
8925f36f AW |
6855 | @table @asis |
6856 | @item @var{size} | |
6857 | Specifies the maximum number of values that can be written into | |
6858 | @var{buffer}. | |
6859 | ||
6860 | @item @var{type} | |
6861 | Specifies a symbolic constant that describes the information that will | |
6862 | be returned for each vertex. @code{GL_2D}, @code{GL_3D}, | |
6863 | @code{GL_3D_COLOR}, @code{GL_3D_COLOR_TEXTURE}, and | |
6864 | @code{GL_4D_COLOR_TEXTURE} are accepted. | |
6865 | ||
6866 | @item @var{buffer} | |
6867 | Returns the feedback data. | |
6868 | ||
6869 | @end table | |
6870 | ||
8925f36f AW |
6871 | The @code{glFeedbackBuffer} function controls feedback. Feedback, like |
6872 | selection, is a GL mode. The mode is selected by calling | |
6873 | @code{glRenderMode} with @code{GL_FEEDBACK}. When the GL is in feedback | |
6874 | mode, no pixels are produced by rasterization. Instead, information | |
6875 | about primitives that would have been rasterized is fed back to the | |
6876 | application using the GL. | |
6877 | ||
6878 | @code{glFeedbackBuffer} has three arguments: @var{buffer} is a pointer | |
6879 | to an array of floating-point values into which feedback information is | |
6880 | placed. @var{size} indicates the size of the array. @var{type} is a | |
6881 | symbolic constant describing the information that is fed back for each | |
6882 | vertex. @code{glFeedbackBuffer} must be issued before feedback mode is | |
6883 | enabled (by calling @code{glRenderMode} with argument | |
6884 | @code{GL_FEEDBACK}). Setting @code{GL_FEEDBACK} without establishing the | |
6885 | feedback buffer, or calling @code{glFeedbackBuffer} while the GL is in | |
6886 | feedback mode, is an error. | |
6887 | ||
6888 | When @code{glRenderMode} is called while in feedback mode, it returns | |
6889 | the number of entries placed in the feedback array and resets the | |
6890 | feedback array pointer to the base of the feedback buffer. The returned | |
6891 | value never exceeds @var{size}. If the feedback data required more room | |
6892 | than was available in @var{buffer}, @code{glRenderMode} returns a | |
6893 | negative value. To take the GL out of feedback mode, call | |
6894 | @code{glRenderMode} with a parameter value other than | |
6895 | @code{GL_FEEDBACK}. | |
6896 | ||
6897 | While in feedback mode, each primitive, bitmap, or pixel rectangle that | |
6898 | would be rasterized generates a block of values that are copied into the | |
6899 | feedback array. If doing so would cause the number of entries to exceed | |
6900 | the maximum, the block is partially written so as to fill the array (if | |
6901 | there is any room left at all), and an overflow flag is set. Each block | |
6902 | begins with a code indicating the primitive type, followed by values | |
6903 | that describe the primitive's vertices and associated data. Entries are | |
6904 | also written for bitmaps and pixel rectangles. Feedback occurs after | |
6905 | polygon culling and @code{glPolygonMode} interpretation of polygons has | |
6906 | taken place, so polygons that are culled are not returned in the | |
6907 | feedback buffer. It can also occur after polygons with more than three | |
6908 | edges are broken up into triangles, if the GL implementation renders | |
6909 | polygons by performing this decomposition. | |
6910 | ||
6911 | The @code{glPassThrough} command can be used to insert a marker into the | |
6912 | feedback buffer. See @code{glPassThrough}. | |
6913 | ||
6914 | Following is the grammar for the blocks of values written into the | |
6915 | feedback buffer. Each primitive is indicated with a unique identifying | |
6916 | value followed by some number of vertices. Polygon entries include an | |
6917 | integer value indicating how many vertices follow. A vertex is fed back | |
6918 | as some number of floating-point values, as determined by @var{type}. | |
6919 | Colors are fed back as four values in RGBA mode and one value in color | |
6920 | index mode. | |
6921 | ||
3c9b6116 AW |
6922 | feedbackList @r{←} feedbackItem feedbackList | feedbackItem feedbackItem |
6923 | @r{←} point | lineSegment | polygon | bitmap | pixelRectangle | passThru | |
6924 | point @r{←}@code{GL_POINT_TOKEN} vertex lineSegment | |
6925 | @r{←}@code{GL_LINE_TOKEN} vertex vertex | @code{GL_LINE_RESET_TOKEN} | |
6926 | vertex vertex polygon @r{←}@code{GL_POLYGON_TOKEN} n polySpec polySpec | |
6927 | @r{←} polySpec vertex | vertex vertex vertex bitmap | |
6928 | @r{←}@code{GL_BITMAP_TOKEN} vertex pixelRectangle | |
6929 | @r{←}@code{GL_DRAW_PIXEL_TOKEN} vertex | @code{GL_COPY_PIXEL_TOKEN} | |
6930 | vertex passThru @r{←}@code{GL_PASS_THROUGH_TOKEN} value vertex @r{←} 2d | |
6931 | | 3d | 3dColor | 3dColorTexture | 4dColorTexture 2d @r{←} value value 3d | |
6932 | @r{←} value value value 3dColor @r{←} value value value color | |
6933 | 3dColorTexture @r{←} value value value color tex 4dColorTexture @r{←} | |
6934 | value value value value color tex color @r{←} rgba | index rgba @r{←} | |
6935 | value value value value index @r{←} value tex @r{←} value value value | |
6936 | value | |
8925f36f AW |
6937 | |
6938 | @var{value} is a floating-point number, and @var{n} is a floating-point | |
6939 | integer giving the number of vertices in the polygon. | |
6940 | @code{GL_POINT_TOKEN}, @code{GL_LINE_TOKEN}, @code{GL_LINE_RESET_TOKEN}, | |
6941 | @code{GL_POLYGON_TOKEN}, @code{GL_BITMAP_TOKEN}, | |
6942 | @code{GL_DRAW_PIXEL_TOKEN}, @code{GL_COPY_PIXEL_TOKEN} and | |
6943 | @code{GL_PASS_THROUGH_TOKEN} are symbolic floating-point constants. | |
6944 | @code{GL_LINE_RESET_TOKEN} is returned whenever the line stipple pattern | |
6945 | is reset. The data returned as a vertex depends on the feedback | |
6946 | @var{type}. | |
6947 | ||
6948 | The following table gives the correspondence between @var{type} and the | |
6949 | number of values per vertex. @var{k} is 1 in color index mode and 4 in | |
6950 | RGBA mode. | |
6951 | ||
6952 | ||
6953 | ||
6954 | @table @asis | |
6955 | @item @strong{Type} | |
6956 | @strong{Coordinates}, @strong{Color}, @strong{Texture}, @strong{Total | |
6957 | Number of Values} | |
6958 | ||
6959 | @item @code{GL_2D} | |
6960 | @var{x}, @var{y}, , , 2 | |
6961 | ||
6962 | @item @code{GL_3D} | |
6963 | @var{x}, @var{y}, @var{z}, , , 3 | |
6964 | ||
6965 | @item @code{GL_3D_COLOR} | |
3c9b6116 | 6966 | @var{x}, @var{y}, @var{z}, @r{@var{k}}, , @r{3+@var{k}} |
8925f36f AW |
6967 | |
6968 | @item @code{GL_3D_COLOR_TEXTURE} | |
3c9b6116 | 6969 | @var{x}, @var{y}, @var{z}, @r{@var{k}}, 4 , @r{7+@var{k}} |
8925f36f AW |
6970 | |
6971 | @item @code{GL_4D_COLOR_TEXTURE} | |
3c9b6116 | 6972 | @var{x}, @var{y}, @var{z}, @var{w}, @r{@var{k}}, 4 , @r{8+@var{k}} |
8925f36f AW |
6973 | |
6974 | @end table | |
6975 | ||
6976 | Feedback vertex coordinates are in window coordinates, except @var{w}, | |
6977 | which is in clip coordinates. Feedback colors are lighted, if lighting | |
6978 | is enabled. Feedback texture coordinates are generated, if texture | |
6979 | coordinate generation is enabled. They are always transformed by the | |
6980 | texture matrix. | |
6981 | ||
8925f36f AW |
6982 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted |
6983 | value. | |
6984 | ||
6985 | @code{GL_INVALID_VALUE} is generated if @var{size} is negative. | |
6986 | ||
6987 | @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is | |
6988 | called while the render mode is @code{GL_FEEDBACK}, or if | |
6989 | @code{glRenderMode} is called with argument @code{GL_FEEDBACK} before | |
6990 | @code{glFeedbackBuffer} is called at least once. | |
6991 | ||
6992 | @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is | |
6993 | executed between the execution of @code{glBegin} and the corresponding | |
6994 | execution of @code{glEnd}. | |
6995 | ||
bb894c9d | 6996 | @end deftypefun |
8925f36f | 6997 | |
bb894c9d | 6998 | @deftypefun void glFinish |
3c9b6116 AW |
6999 | Block until all GL execution is complete. |
7000 | ||
8925f36f AW |
7001 | @code{glFinish} does not return until the effects of all previously |
7002 | called GL commands are complete. Such effects include all changes to GL | |
7003 | state, all changes to connection state, and all changes to the frame | |
7004 | buffer contents. | |
7005 | ||
8925f36f AW |
7006 | @code{GL_INVALID_OPERATION} is generated if @code{glFinish} is executed |
7007 | between the execution of @code{glBegin} and the corresponding execution | |
7008 | of @code{glEnd}. | |
7009 | ||
bb894c9d | 7010 | @end deftypefun |
8925f36f | 7011 | |
bb894c9d | 7012 | @deftypefun void glFlush |
3c9b6116 AW |
7013 | Force execution of GL commands in finite time. |
7014 | ||
8925f36f AW |
7015 | Different GL implementations buffer commands in several different |
7016 | locations, including network buffers and the graphics accelerator | |
7017 | itself. @code{glFlush} empties all of these buffers, causing all issued | |
7018 | commands to be executed as quickly as they are accepted by the actual | |
7019 | rendering engine. Though this execution may not be completed in any | |
7020 | particular time period, it does complete in finite time. | |
7021 | ||
7022 | Because any GL program might be executed over a network, or on an | |
7023 | accelerator that buffers commands, all programs should call | |
7024 | @code{glFlush} whenever they count on having all of their previously | |
7025 | issued commands completed. For example, call @code{glFlush} before | |
7026 | waiting for user input that depends on the generated image. | |
7027 | ||
8925f36f AW |
7028 | @code{GL_INVALID_OPERATION} is generated if @code{glFlush} is executed |
7029 | between the execution of @code{glBegin} and the corresponding execution | |
7030 | of @code{glEnd}. | |
7031 | ||
bb894c9d | 7032 | @end deftypefun |
8925f36f | 7033 | |
bb894c9d | 7034 | @deftypefun void glFogCoordPointer type stride pointer |
3c9b6116 AW |
7035 | Define an array of fog coordinates. |
7036 | ||
8925f36f AW |
7037 | @table @asis |
7038 | @item @var{type} | |
7039 | Specifies the data type of each fog coordinate. Symbolic constants | |
7040 | @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is | |
7041 | @code{GL_FLOAT}. | |
7042 | ||
7043 | @item @var{stride} | |
7044 | Specifies the byte offset between consecutive fog coordinates. If | |
7045 | @var{stride} is 0, the array elements are understood to be tightly | |
7046 | packed. The initial value is 0. | |
7047 | ||
7048 | @item @var{pointer} | |
7049 | Specifies a pointer to the first coordinate of the first fog coordinate | |
7050 | in the array. The initial value is 0. | |
7051 | ||
7052 | @end table | |
7053 | ||
8925f36f AW |
7054 | @code{glFogCoordPointer} specifies the location and data format of an |
7055 | array of fog coordinates to use when rendering. @var{type} specifies the | |
7056 | data type of each fog coordinate, and @var{stride} specifies the byte | |
7057 | stride from one fog coordinate to the next, allowing vertices and | |
7058 | attributes to be packed into a single array or stored in separate | |
7059 | arrays. | |
7060 | ||
7061 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
7062 | target (see @code{glBindBuffer}) while a fog coordinate array is | |
7063 | specified, @var{pointer} is treated as a byte offset into the buffer | |
7064 | object's data store. Also, the buffer object binding | |
7065 | (@code{GL_ARRAY_BUFFER_BINDING}) is saved as fog coordinate vertex array | |
7066 | client-side state (@code{GL_FOG_COORD_ARRAY_BUFFER_BINDING}). | |
7067 | ||
7068 | When a fog coordinate array is specified, @var{type}, @var{stride}, and | |
7069 | @var{pointer} are saved as client-side state, in addition to the current | |
7070 | vertex array buffer object binding. | |
7071 | ||
7072 | To enable and disable the fog coordinate array, call | |
7073 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
7074 | argument @code{GL_FOG_COORD_ARRAY}. If enabled, the fog coordinate array | |
7075 | is used when @code{glDrawArrays}, @code{glMultiDrawArrays}, | |
7076 | @code{glDrawElements}, @code{glMultiDrawElements}, | |
7077 | @code{glDrawRangeElements}, or @code{glArrayElement} is called. | |
7078 | ||
8925f36f AW |
7079 | @code{GL_INVALID_ENUM} is generated if @var{type} is not either |
7080 | @code{GL_FLOAT} or @code{GL_DOUBLE}. | |
7081 | ||
7082 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
7083 | ||
bb894c9d | 7084 | @end deftypefun |
8925f36f | 7085 | |
ca09631c | 7086 | @deftypefun void glFogCoordf coord |
3c9b6116 AW |
7087 | Set the current fog coordinates. |
7088 | ||
8925f36f AW |
7089 | @table @asis |
7090 | @item @var{coord} | |
7091 | Specify the fog distance. | |
7092 | ||
7093 | @end table | |
7094 | ||
8925f36f AW |
7095 | @code{glFogCoord} specifies the fog coordinate that is associated with |
7096 | each vertex and the current raster position. The value specified is | |
7097 | interpolated and used in computing the fog color (see @code{glFog}). | |
7098 | ||
bb894c9d | 7099 | @end deftypefun |
8925f36f | 7100 | |
bb894c9d AW |
7101 | @deftypefun void glFogf pname param |
7102 | @deftypefunx void glFogi pname param | |
3c9b6116 AW |
7103 | Specify fog parameters. |
7104 | ||
8925f36f AW |
7105 | @table @asis |
7106 | @item @var{pname} | |
7107 | Specifies a single-valued fog parameter. @code{GL_FOG_MODE}, | |
7108 | @code{GL_FOG_DENSITY}, @code{GL_FOG_START}, @code{GL_FOG_END}, | |
7109 | @code{GL_FOG_INDEX}, and @code{GL_FOG_COORD_SRC} are accepted. | |
7110 | ||
7111 | @item @var{param} | |
7112 | Specifies the value that @var{pname} will be set to. | |
7113 | ||
7114 | @end table | |
7115 | ||
8925f36f AW |
7116 | Fog is initially disabled. While enabled, fog affects rasterized |
7117 | geometry, bitmaps, and pixel blocks, but not buffer clear operations. To | |
7118 | enable and disable fog, call @code{glEnable} and @code{glDisable} with | |
7119 | argument @code{GL_FOG}. | |
7120 | ||
7121 | @code{glFog} assigns the value or values in @var{params} to the fog | |
7122 | parameter specified by @var{pname}. The following values are accepted | |
7123 | for @var{pname}: | |
7124 | ||
7125 | @table @asis | |
7126 | @item @code{GL_FOG_MODE} | |
7127 | @var{params} is a single integer or floating-point value that specifies | |
3c9b6116 | 7128 | the equation to be used to compute the fog blend factor, @r{@var{f}}. |
8925f36f AW |
7129 | Three symbolic constants are accepted: @code{GL_LINEAR}, @code{GL_EXP}, |
7130 | and @code{GL_EXP2}. The equations corresponding to these symbolic | |
7131 | constants are defined below. The initial fog mode is @code{GL_EXP}. | |
7132 | ||
7133 | @item @code{GL_FOG_DENSITY} | |
7134 | @var{params} is a single integer or floating-point value that specifies | |
3c9b6116 | 7135 | @r{@var{density}}, the fog density used in both exponential fog |
8925f36f AW |
7136 | equations. Only nonnegative densities are accepted. The initial fog |
7137 | density is 1. | |
7138 | ||
7139 | @item @code{GL_FOG_START} | |
7140 | @var{params} is a single integer or floating-point value that specifies | |
3c9b6116 AW |
7141 | @r{@var{start}}, the near distance used in the linear fog equation. The |
7142 | initial near distance is 0. | |
8925f36f AW |
7143 | |
7144 | @item @code{GL_FOG_END} | |
7145 | @var{params} is a single integer or floating-point value that specifies | |
3c9b6116 | 7146 | @r{@var{end}}, the far distance used in the linear fog equation. The |
8925f36f AW |
7147 | initial far distance is 1. |
7148 | ||
7149 | @item @code{GL_FOG_INDEX} | |
7150 | @var{params} is a single integer or floating-point value that specifies | |
3c9b6116 | 7151 | @r{@var{i}_@var{f}}, the fog color index. The initial fog index is 0. |
8925f36f AW |
7152 | |
7153 | @item @code{GL_FOG_COLOR} | |
7154 | @var{params} contains four integer or floating-point values that specify | |
3c9b6116 AW |
7155 | @r{@var{C}_@var{f}}, the fog color. Integer values are mapped linearly |
7156 | such that the most positive representable value maps to 1.0, and the | |
7157 | most negative representable value maps to @r{-1.0}. Floating-point | |
7158 | values are mapped directly. After conversion, all color components are | |
7159 | clamped to the range @r{[0,1]}. The initial fog color is (0, 0, 0, 0). | |
8925f36f AW |
7160 | |
7161 | @item @code{GL_FOG_COORD_SRC} | |
7162 | @var{params} contains either of the following symbolic constants: | |
7163 | @code{GL_FOG_COORD} or @code{GL_FRAGMENT_DEPTH}. @code{GL_FOG_COORD} | |
7164 | specifies that the current fog coordinate should be used as distance | |
7165 | value in the fog color computation. @code{GL_FRAGMENT_DEPTH} specifies | |
7166 | that the current fragment depth should be used as distance value in the | |
7167 | fog computation. | |
7168 | ||
7169 | @end table | |
7170 | ||
7171 | Fog blends a fog color with each rasterized pixel fragment's | |
3c9b6116 AW |
7172 | post-texturing color using a blending factor @r{@var{f}}. Factor |
7173 | @r{@var{f}} is computed in one of three ways, depending on the fog mode. | |
7174 | Let @r{@var{c}} be either the distance in eye coordinate from the origin | |
7175 | (in the case that the @code{GL_FOG_COORD_SRC} is | |
8925f36f AW |
7176 | @code{GL_FRAGMENT_DEPTH}) or the current fog coordinate (in the case |
7177 | that @code{GL_FOG_COORD_SRC} is @code{GL_FOG_COORD}). The equation for | |
7178 | @code{GL_LINEAR} fog is | |
3c9b6116 | 7179 | @r{@var{f}=@var{end}-@var{c},/@var{end}-@var{start},} |
8925f36f AW |
7180 | |
7181 | The equation for @code{GL_EXP} fog is | |
3c9b6116 | 7182 | @r{@var{f}=@var{e}^-(@var{density}·@var{c},),} |
8925f36f AW |
7183 | |
7184 | The equation for @code{GL_EXP2} fog is | |
3c9b6116 | 7185 | @r{@var{f}=@var{e}^-(@var{density}·@var{c},),^2} |
8925f36f | 7186 | |
3c9b6116 AW |
7187 | Regardless of the fog mode, @r{@var{f}} is clamped to the range |
7188 | @r{[0,1]} after it is computed. Then, if the GL is in RGBA color mode, | |
7189 | the fragment's red, green, and blue colors, represented by | |
7190 | @r{@var{C}_@var{r}}, are replaced by | |
8925f36f | 7191 | |
3c9b6116 | 7192 | @r{@var{C}_@var{r},^″=@var{f}×@var{C}_@var{r}+(1-@var{f},)×@var{C}_@var{f}} |
8925f36f AW |
7193 | |
7194 | Fog does not affect a fragment's alpha component. | |
7195 | ||
3c9b6116 AW |
7196 | In color index mode, the fragment's color index @r{@var{i}_@var{r}} is |
7197 | replaced by | |
8925f36f | 7198 | |
3c9b6116 | 7199 | @r{@var{i}_@var{r},^″=@var{i}_@var{r}+(1-@var{f},)×@var{i}_@var{f}} |
8925f36f AW |
7200 | |
7201 | ||
7202 | ||
8925f36f AW |
7203 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted |
7204 | value, or if @var{pname} is @code{GL_FOG_MODE} and @var{params} is not | |
7205 | an accepted value. | |
7206 | ||
7207 | @code{GL_INVALID_VALUE} is generated if @var{pname} is | |
7208 | @code{GL_FOG_DENSITY} and @var{params} is negative. | |
7209 | ||
7210 | @code{GL_INVALID_OPERATION} is generated if @code{glFog} is executed | |
7211 | between the execution of @code{glBegin} and the corresponding execution | |
7212 | of @code{glEnd}. | |
7213 | ||
bb894c9d | 7214 | @end deftypefun |
8925f36f | 7215 | |
bb894c9d | 7216 | @deftypefun void glFrontFace mode |
3c9b6116 AW |
7217 | Define front- and back-facing polygons. |
7218 | ||
8925f36f AW |
7219 | @table @asis |
7220 | @item @var{mode} | |
7221 | Specifies the orientation of front-facing polygons. @code{GL_CW} and | |
7222 | @code{GL_CCW} are accepted. The initial value is @code{GL_CCW}. | |
7223 | ||
7224 | @end table | |
7225 | ||
8925f36f AW |
7226 | In a scene composed entirely of opaque closed surfaces, back-facing |
7227 | polygons are never visible. Eliminating these invisible polygons has the | |
7228 | obvious benefit of speeding up the rendering of the image. To enable and | |
7229 | disable elimination of back-facing polygons, call @code{glEnable} and | |
7230 | @code{glDisable} with argument @code{GL_CULL_FACE}. | |
7231 | ||
7232 | The projection of a polygon to window coordinates is said to have | |
7233 | clockwise winding if an imaginary object following the path from its | |
7234 | first vertex, its second vertex, and so on, to its last vertex, and | |
7235 | finally back to its first vertex, moves in a clockwise direction about | |
7236 | the interior of the polygon. The polygon's winding is said to be | |
7237 | counterclockwise if the imaginary object following the same path moves | |
7238 | in a counterclockwise direction about the interior of the polygon. | |
7239 | @code{glFrontFace} specifies whether polygons with clockwise winding in | |
7240 | window coordinates, or counterclockwise winding in window coordinates, | |
7241 | are taken to be front-facing. Passing @code{GL_CCW} to @var{mode} | |
7242 | selects counterclockwise polygons as front-facing; @code{GL_CW} selects | |
7243 | clockwise polygons as front-facing. By default, counterclockwise | |
7244 | polygons are taken to be front-facing. | |
7245 | ||
8925f36f AW |
7246 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
7247 | value. | |
7248 | ||
7249 | @code{GL_INVALID_OPERATION} is generated if @code{glFrontFace} is | |
7250 | executed between the execution of @code{glBegin} and the corresponding | |
7251 | execution of @code{glEnd}. | |
7252 | ||
bb894c9d | 7253 | @end deftypefun |
8925f36f | 7254 | |
bb894c9d | 7255 | @deftypefun void glFrustum left right bottom top nearVal farVal |
3c9b6116 AW |
7256 | Multiply the current matrix by a perspective matrix. |
7257 | ||
8925f36f AW |
7258 | @table @asis |
7259 | @item @var{left} | |
7260 | @itemx @var{right} | |
7261 | Specify the coordinates for the left and right vertical clipping planes. | |
7262 | ||
7263 | @item @var{bottom} | |
7264 | @itemx @var{top} | |
7265 | Specify the coordinates for the bottom and top horizontal clipping | |
7266 | planes. | |
7267 | ||
7268 | @item @var{nearVal} | |
7269 | @itemx @var{farVal} | |
7270 | Specify the distances to the near and far depth clipping planes. Both | |
7271 | distances must be positive. | |
7272 | ||
7273 | @end table | |
7274 | ||
8925f36f AW |
7275 | @code{glFrustum} describes a perspective matrix that produces a |
7276 | perspective projection. The current matrix (see @code{glMatrixMode}) is | |
7277 | multiplied by this matrix and the result replaces the current matrix, as | |
7278 | if @code{glMultMatrix} were called with the following matrix as its | |
7279 | argument: | |
7280 | ||
7281 | ||
7282 | ||
3c9b6116 | 7283 | @r{[(2@var{nearVal},/@var{right}-@var{left},, 0 @var{A} 0), (0 |
8925f36f AW |
7284 | 2@var{nearVal},/@var{top}-@var{bottom},, @var{B} 0), (0 0 @var{C} |
7285 | @var{D}), (0 0 -1 0),]} | |
7286 | ||
3c9b6116 | 7287 | @r{@var{A}=@var{right}+@var{left},/@var{right}-@var{left},} |
8925f36f | 7288 | |
3c9b6116 | 7289 | @r{@var{B}=@var{top}+@var{bottom},/@var{top}-@var{bottom},} |
8925f36f | 7290 | |
3c9b6116 | 7291 | @r{@var{C}=-@var{farVal}+@var{nearVal},/@var{farVal}-@var{nearVal},,} |
8925f36f | 7292 | |
3c9b6116 | 7293 | @r{@var{D}=-2@var{farVal}@var{nearVal},/@var{farVal}-@var{nearVal},,} |
8925f36f AW |
7294 | |
7295 | ||
7296 | ||
7297 | Typically, the matrix mode is @code{GL_PROJECTION}, and | |
3c9b6116 AW |
7298 | @r{(@var{left},@var{bottom}-@var{nearVal})} and |
7299 | @r{(@var{right},@var{top}-@var{nearVal})} specify the points on the near | |
7300 | clipping plane that are mapped to the lower left and upper right corners | |
7301 | of the window, assuming that the eye is located at (0, 0, 0). | |
7302 | @r{-@var{farVal}} specifies the location of the far clipping plane. Both | |
7303 | @var{nearVal} and @var{farVal} must be positive. | |
8925f36f AW |
7304 | |
7305 | Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the | |
7306 | current matrix stack. | |
7307 | ||
8925f36f AW |
7308 | @code{GL_INVALID_VALUE} is generated if @var{nearVal} or @var{farVal} is |
7309 | not positive, or if @var{left} = @var{right}, or @var{bottom} = | |
7310 | @var{top}, or @var{near} = @var{far}. | |
7311 | ||
7312 | @code{GL_INVALID_OPERATION} is generated if @code{glFrustum} is executed | |
7313 | between the execution of @code{glBegin} and the corresponding execution | |
7314 | of @code{glEnd}. | |
7315 | ||
bb894c9d | 7316 | @end deftypefun |
8925f36f | 7317 | |
bb894c9d | 7318 | @deftypefun void glGenBuffers n buffers |
3c9b6116 AW |
7319 | Generate buffer object names. |
7320 | ||
8925f36f AW |
7321 | @table @asis |
7322 | @item @var{n} | |
7323 | Specifies the number of buffer object names to be generated. | |
7324 | ||
7325 | @item @var{buffers} | |
7326 | Specifies an array in which the generated buffer object names are | |
7327 | stored. | |
7328 | ||
7329 | @end table | |
7330 | ||
8925f36f AW |
7331 | @code{glGenBuffers} returns @var{n} buffer object names in |
7332 | @var{buffers}. There is no guarantee that the names form a contiguous | |
7333 | set of integers; however, it is guaranteed that none of the returned | |
7334 | names was in use immediately before the call to @code{glGenBuffers}. | |
7335 | ||
7336 | Buffer object names returned by a call to @code{glGenBuffers} are not | |
7337 | returned by subsequent calls, unless they are first deleted with | |
7338 | @code{glDeleteBuffers}. | |
7339 | ||
7340 | No buffer objects are associated with the returned buffer object names | |
7341 | until they are first bound by calling @code{glBindBuffer}. | |
7342 | ||
8925f36f AW |
7343 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
7344 | ||
7345 | @code{GL_INVALID_OPERATION} is generated if @code{glGenBuffers} is | |
7346 | executed between the execution of @code{glBegin} and the corresponding | |
7347 | execution of @code{glEnd}. | |
7348 | ||
bb894c9d | 7349 | @end deftypefun |
8925f36f | 7350 | |
bb894c9d | 7351 | @deftypefun GLuint glGenLists range |
3c9b6116 AW |
7352 | Generate a contiguous set of empty display lists. |
7353 | ||
8925f36f AW |
7354 | @table @asis |
7355 | @item @var{range} | |
7356 | Specifies the number of contiguous empty display lists to be generated. | |
7357 | ||
7358 | @end table | |
7359 | ||
8925f36f AW |
7360 | @code{glGenLists} has one argument, @var{range}. It returns an integer |
7361 | @var{n} such that @var{range} contiguous empty display lists, named | |
3c9b6116 AW |
7362 | @r{@var{n}}, @r{@var{n}+1}, @r{@var{...}}, @r{@var{n}+@var{range}-1}, |
7363 | are created. If @var{range} is 0, if there is no group of @var{range} | |
7364 | contiguous names available, or if any error is generated, no display | |
7365 | lists are generated, and 0 is returned. | |
8925f36f | 7366 | |
8925f36f AW |
7367 | @code{GL_INVALID_VALUE} is generated if @var{range} is negative. |
7368 | ||
7369 | @code{GL_INVALID_OPERATION} is generated if @code{glGenLists} is | |
7370 | executed between the execution of @code{glBegin} and the corresponding | |
7371 | execution of @code{glEnd}. | |
7372 | ||
bb894c9d | 7373 | @end deftypefun |
8925f36f | 7374 | |
bb894c9d | 7375 | @deftypefun void glGenQueries n ids |
3c9b6116 AW |
7376 | Generate query object names. |
7377 | ||
8925f36f AW |
7378 | @table @asis |
7379 | @item @var{n} | |
7380 | Specifies the number of query object names to be generated. | |
7381 | ||
7382 | @item @var{ids} | |
7383 | Specifies an array in which the generated query object names are stored. | |
7384 | ||
7385 | @end table | |
7386 | ||
8925f36f AW |
7387 | @code{glGenQueries} returns @var{n} query object names in @var{ids}. |
7388 | There is no guarantee that the names form a contiguous set of integers; | |
7389 | however, it is guaranteed that none of the returned names was in use | |
7390 | immediately before the call to @code{glGenQueries}. | |
7391 | ||
7392 | Query object names returned by a call to @code{glGenQueries} are not | |
7393 | returned by subsequent calls, unless they are first deleted with | |
7394 | @code{glDeleteQueries}. | |
7395 | ||
7396 | No query objects are associated with the returned query object names | |
7397 | until they are first used by calling @code{glBeginQuery}. | |
7398 | ||
8925f36f AW |
7399 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
7400 | ||
7401 | @code{GL_INVALID_OPERATION} is generated if @code{glGenQueries} is | |
7402 | executed between the execution of @code{glBegin} and the corresponding | |
7403 | execution of @code{glEnd}. | |
7404 | ||
bb894c9d | 7405 | @end deftypefun |
8925f36f | 7406 | |
bb894c9d | 7407 | @deftypefun void glGenTextures n textures |
3c9b6116 AW |
7408 | Generate texture names. |
7409 | ||
8925f36f AW |
7410 | @table @asis |
7411 | @item @var{n} | |
7412 | Specifies the number of texture names to be generated. | |
7413 | ||
7414 | @item @var{textures} | |
7415 | Specifies an array in which the generated texture names are stored. | |
7416 | ||
7417 | @end table | |
7418 | ||
8925f36f AW |
7419 | @code{glGenTextures} returns @var{n} texture names in @var{textures}. |
7420 | There is no guarantee that the names form a contiguous set of integers; | |
7421 | however, it is guaranteed that none of the returned names was in use | |
7422 | immediately before the call to @code{glGenTextures}. | |
7423 | ||
7424 | The generated textures have no dimensionality; they assume the | |
7425 | dimensionality of the texture target to which they are first bound (see | |
7426 | @code{glBindTexture}). | |
7427 | ||
7428 | Texture names returned by a call to @code{glGenTextures} are not | |
7429 | returned by subsequent calls, unless they are first deleted with | |
7430 | @code{glDeleteTextures}. | |
7431 | ||
8925f36f AW |
7432 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
7433 | ||
7434 | @code{GL_INVALID_OPERATION} is generated if @code{glGenTextures} is | |
7435 | executed between the execution of @code{glBegin} and the corresponding | |
7436 | execution of @code{glEnd}. | |
7437 | ||
bb894c9d | 7438 | @end deftypefun |
8925f36f | 7439 | |
bb894c9d | 7440 | @deftypefun void glGetActiveAttrib program index bufSize length size type name |
3c9b6116 AW |
7441 | Returns information about an active attribute variable for the specified |
7442 | program object. | |
7443 | ||
8925f36f AW |
7444 | @table @asis |
7445 | @item @var{program} | |
7446 | Specifies the program object to be queried. | |
7447 | ||
7448 | @item @var{index} | |
7449 | Specifies the index of the attribute variable to be queried. | |
7450 | ||
7451 | @item @var{bufSize} | |
7452 | Specifies the maximum number of characters OpenGL is allowed to write in | |
7453 | the character buffer indicated by @var{name}. | |
7454 | ||
7455 | @item @var{length} | |
7456 | Returns the number of characters actually written by OpenGL in the | |
7457 | string indicated by @var{name} (excluding the null terminator) if a | |
7458 | value other than @code{NULL} is passed. | |
7459 | ||
7460 | @item @var{size} | |
7461 | Returns the size of the attribute variable. | |
7462 | ||
7463 | @item @var{type} | |
7464 | Returns the data type of the attribute variable. | |
7465 | ||
7466 | @item @var{name} | |
7467 | Returns a null terminated string containing the name of the attribute | |
7468 | variable. | |
7469 | ||
7470 | @end table | |
7471 | ||
8925f36f AW |
7472 | @code{glGetActiveAttrib} returns information about an active attribute |
7473 | variable in the program object specified by @var{program}. The number of | |
7474 | active attributes can be obtained by calling @code{glGetProgram} with | |
7475 | the value @code{GL_ACTIVE_ATTRIBUTES}. A value of 0 for @var{index} | |
7476 | selects the first active attribute variable. Permissible values for | |
7477 | @var{index} range from 0 to the number of active attribute variables | |
7478 | minus 1. | |
7479 | ||
7480 | A vertex shader may use either built-in attribute variables, | |
7481 | user-defined attribute variables, or both. Built-in attribute variables | |
7482 | have a prefix of "gl_" and reference conventional OpenGL vertex | |
7483 | attribtes (e.g., @var{gl_Vertex}, @var{gl_Normal}, etc., see the OpenGL | |
7484 | Shading Language specification for a complete list.) User-defined | |
7485 | attribute variables have arbitrary names and obtain their values through | |
7486 | numbered generic vertex attributes. An attribute variable (either | |
7487 | built-in or user-defined) is considered active if it is determined | |
7488 | during the link operation that it may be accessed during program | |
7489 | execution. Therefore, @var{program} should have previously been the | |
7490 | target of a call to @code{glLinkProgram}, but it is not necessary for it | |
7491 | to have been linked successfully. | |
7492 | ||
7493 | The size of the character buffer required to store the longest attribute | |
7494 | variable name in @var{program} can be obtained by calling | |
7495 | @code{glGetProgram} with the value | |
7496 | @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH}. This value should be used to | |
7497 | allocate a buffer of sufficient size to store the returned attribute | |
7498 | name. The size of this character buffer is passed in @var{bufSize}, and | |
7499 | a pointer to this character buffer is passed in @var{name}. | |
7500 | ||
7501 | @code{glGetActiveAttrib} returns the name of the attribute variable | |
7502 | indicated by @var{index}, storing it in the character buffer specified | |
7503 | by @var{name}. The string returned will be null terminated. The actual | |
7504 | number of characters written into this buffer is returned in | |
7505 | @var{length}, and this count does not include the null termination | |
7506 | character. If the length of the returned string is not required, a value | |
7507 | of @code{NULL} can be passed in the @var{length} argument. | |
7508 | ||
7509 | The @var{type} argument will return a pointer to the attribute | |
7510 | variable's data type. The symbolic constants @code{GL_FLOAT}, | |
7511 | @code{GL_FLOAT_VEC2}, @code{GL_FLOAT_VEC3}, @code{GL_FLOAT_VEC4}, | |
7512 | @code{GL_FLOAT_MAT2}, @code{GL_FLOAT_MAT3}, @code{GL_FLOAT_MAT4}, | |
7513 | @code{GL_FLOAT_MAT2x3}, @code{GL_FLOAT_MAT2x4}, @code{GL_FLOAT_MAT3x2}, | |
7514 | @code{GL_FLOAT_MAT3x4}, @code{GL_FLOAT_MAT4x2}, or | |
7515 | @code{GL_FLOAT_MAT4x3} may be returned. The @var{size} argument will | |
7516 | return the size of the attribute, in units of the type returned in | |
7517 | @var{type}. | |
7518 | ||
7519 | The list of active attribute variables may include both built-in | |
7520 | attribute variables (which begin with the prefix "gl_") as well as | |
7521 | user-defined attribute variable names. | |
7522 | ||
7523 | This function will return as much information as it can about the | |
7524 | specified active attribute variable. If no information is available, | |
7525 | @var{length} will be 0, and @var{name} will be an empty string. This | |
7526 | situation could occur if this function is called after a link operation | |
7527 | that failed. If an error occurs, the return values @var{length}, | |
7528 | @var{size}, @var{type}, and @var{name} will be unmodified. | |
7529 | ||
8925f36f AW |
7530 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
7531 | generated by OpenGL. | |
7532 | ||
7533 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
7534 | program object. | |
7535 | ||
7536 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or | |
7537 | equal to the number of active attribute variables in @var{program}. | |
7538 | ||
7539 | @code{GL_INVALID_OPERATION} is generated if @code{glGetActiveAttrib} is | |
7540 | executed between the execution of @code{glBegin} and the corresponding | |
7541 | execution of @code{glEnd}. | |
7542 | ||
7543 | @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0. | |
7544 | ||
bb894c9d | 7545 | @end deftypefun |
8925f36f | 7546 | |
bb894c9d | 7547 | @deftypefun void glGetActiveUniform program index bufSize length size type name |
3c9b6116 AW |
7548 | Returns information about an active uniform variable for the specified |
7549 | program object. | |
7550 | ||
8925f36f AW |
7551 | @table @asis |
7552 | @item @var{program} | |
7553 | Specifies the program object to be queried. | |
7554 | ||
7555 | @item @var{index} | |
7556 | Specifies the index of the uniform variable to be queried. | |
7557 | ||
7558 | @item @var{bufSize} | |
7559 | Specifies the maximum number of characters OpenGL is allowed to write in | |
7560 | the character buffer indicated by @var{name}. | |
7561 | ||
7562 | @item @var{length} | |
7563 | Returns the number of characters actually written by OpenGL in the | |
7564 | string indicated by @var{name} (excluding the null terminator) if a | |
7565 | value other than @code{NULL} is passed. | |
7566 | ||
7567 | @item @var{size} | |
7568 | Returns the size of the uniform variable. | |
7569 | ||
7570 | @item @var{type} | |
7571 | Returns the data type of the uniform variable. | |
7572 | ||
7573 | @item @var{name} | |
7574 | Returns a null terminated string containing the name of the uniform | |
7575 | variable. | |
7576 | ||
7577 | @end table | |
7578 | ||
8925f36f AW |
7579 | @code{glGetActiveUniform} returns information about an active uniform |
7580 | variable in the program object specified by @var{program}. The number of | |
7581 | active uniform variables can be obtained by calling @code{glGetProgram} | |
7582 | with the value @code{GL_ACTIVE_UNIFORMS}. A value of 0 for @var{index} | |
7583 | selects the first active uniform variable. Permissible values for | |
7584 | @var{index} range from 0 to the number of active uniform variables minus | |
7585 | 1. | |
7586 | ||
7587 | Shaders may use either built-in uniform variables, user-defined uniform | |
7588 | variables, or both. Built-in uniform variables have a prefix of "gl_" | |
7589 | and reference existing OpenGL state or values derived from such state | |
7590 | (e.g., @var{gl_Fog}, @var{gl_ModelViewMatrix}, etc., see the OpenGL | |
7591 | Shading Language specification for a complete list.) User-defined | |
7592 | uniform variables have arbitrary names and obtain their values from the | |
7593 | application through calls to @code{glUniform}. A uniform variable | |
7594 | (either built-in or user-defined) is considered active if it is | |
7595 | determined during the link operation that it may be accessed during | |
7596 | program execution. Therefore, @var{program} should have previously been | |
7597 | the target of a call to @code{glLinkProgram}, but it is not necessary | |
7598 | for it to have been linked successfully. | |
7599 | ||
7600 | The size of the character buffer required to store the longest uniform | |
7601 | variable name in @var{program} can be obtained by calling | |
7602 | @code{glGetProgram} with the value @code{GL_ACTIVE_UNIFORM_MAX_LENGTH}. | |
7603 | This value should be used to allocate a buffer of sufficient size to | |
7604 | store the returned uniform variable name. The size of this character | |
7605 | buffer is passed in @var{bufSize}, and a pointer to this character | |
7606 | buffer is passed in @var{name.} | |
7607 | ||
7608 | @code{glGetActiveUniform} returns the name of the uniform variable | |
7609 | indicated by @var{index}, storing it in the character buffer specified | |
7610 | by @var{name}. The string returned will be null terminated. The actual | |
7611 | number of characters written into this buffer is returned in | |
7612 | @var{length}, and this count does not include the null termination | |
7613 | character. If the length of the returned string is not required, a value | |
7614 | of @code{NULL} can be passed in the @var{length} argument. | |
7615 | ||
7616 | The @var{type} argument will return a pointer to the uniform variable's | |
7617 | data type. The symbolic constants @code{GL_FLOAT}, @code{GL_FLOAT_VEC2}, | |
7618 | @code{GL_FLOAT_VEC3}, @code{GL_FLOAT_VEC4}, @code{GL_INT}, | |
7619 | @code{GL_INT_VEC2}, @code{GL_INT_VEC3}, @code{GL_INT_VEC4}, | |
7620 | @code{GL_BOOL}, @code{GL_BOOL_VEC2}, @code{GL_BOOL_VEC3}, | |
7621 | @code{GL_BOOL_VEC4}, @code{GL_FLOAT_MAT2}, @code{GL_FLOAT_MAT3}, | |
7622 | @code{GL_FLOAT_MAT4}, @code{GL_FLOAT_MAT2x3}, @code{GL_FLOAT_MAT2x4}, | |
7623 | @code{GL_FLOAT_MAT3x2}, @code{GL_FLOAT_MAT3x4}, @code{GL_FLOAT_MAT4x2}, | |
7624 | @code{GL_FLOAT_MAT4x3}, @code{GL_SAMPLER_1D}, @code{GL_SAMPLER_2D}, | |
7625 | @code{GL_SAMPLER_3D}, @code{GL_SAMPLER_CUBE}, | |
7626 | @code{GL_SAMPLER_1D_SHADOW}, or @code{GL_SAMPLER_2D_SHADOW} may be | |
7627 | returned. | |
7628 | ||
7629 | If one or more elements of an array are active, the name of the array is | |
7630 | returned in @var{name}, the type is returned in @var{type}, and the | |
7631 | @var{size} parameter returns the highest array element index used, plus | |
7632 | one, as determined by the compiler and/or linker. Only one active | |
7633 | uniform variable will be reported for a uniform array. | |
7634 | ||
7635 | Uniform variables that are declared as structures or arrays of | |
7636 | structures will not be returned directly by this function. Instead, each | |
7637 | of these uniform variables will be reduced to its fundamental components | |
7638 | containing the "." and "[]" operators such that each of the names is | |
7639 | valid as an argument to @code{glGetUniformLocation}. Each of these | |
7640 | reduced uniform variables is counted as one active uniform variable and | |
7641 | is assigned an index. A valid name cannot be a structure, an array of | |
7642 | structures, or a subcomponent of a vector or matrix. | |
7643 | ||
7644 | The size of the uniform variable will be returned in @var{size}. Uniform | |
7645 | variables other than arrays will have a size of 1. Structures and arrays | |
7646 | of structures will be reduced as described earlier, such that each of | |
7647 | the names returned will be a data type in the earlier list. If this | |
7648 | reduction results in an array, the size returned will be as described | |
7649 | for uniform arrays; otherwise, the size returned will be 1. | |
7650 | ||
7651 | The list of active uniform variables may include both built-in uniform | |
7652 | variables (which begin with the prefix "gl_") as well as user-defined | |
7653 | uniform variable names. | |
7654 | ||
7655 | This function will return as much information as it can about the | |
7656 | specified active uniform variable. If no information is available, | |
7657 | @var{length} will be 0, and @var{name} will be an empty string. This | |
7658 | situation could occur if this function is called after a link operation | |
7659 | that failed. If an error occurs, the return values @var{length}, | |
7660 | @var{size}, @var{type}, and @var{name} will be unmodified. | |
7661 | ||
8925f36f AW |
7662 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
7663 | generated by OpenGL. | |
7664 | ||
7665 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
7666 | program object. | |
7667 | ||
7668 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or | |
7669 | equal to the number of active uniform variables in @var{program}. | |
7670 | ||
7671 | @code{GL_INVALID_OPERATION} is generated if @code{glGetActiveUniform} is | |
7672 | executed between the execution of @code{glBegin} and the corresponding | |
7673 | execution of @code{glEnd}. | |
7674 | ||
7675 | @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0. | |
7676 | ||
bb894c9d | 7677 | @end deftypefun |
8925f36f | 7678 | |
bb894c9d | 7679 | @deftypefun void glGetAttachedShaders program maxCount count shaders |
3c9b6116 AW |
7680 | Returns the handles of the shader objects attached to a program object. |
7681 | ||
8925f36f AW |
7682 | @table @asis |
7683 | @item @var{program} | |
7684 | Specifies the program object to be queried. | |
7685 | ||
7686 | @item @var{maxCount} | |
7687 | Specifies the size of the array for storing the returned object names. | |
7688 | ||
7689 | @item @var{count} | |
7690 | Returns the number of names actually returned in @var{objects}. | |
7691 | ||
7692 | @item @var{shaders} | |
7693 | Specifies an array that is used to return the names of attached shader | |
7694 | objects. | |
7695 | ||
7696 | @end table | |
7697 | ||
8925f36f AW |
7698 | @code{glGetAttachedShaders} returns the names of the shader objects |
7699 | attached to @var{program}. The names of shader objects that are attached | |
7700 | to @var{program} will be returned in @var{shaders.} The actual number of | |
7701 | shader names written into @var{shaders} is returned in @var{count.} If | |
7702 | no shader objects are attached to @var{program}, @var{count} is set to | |
7703 | 0. The maximum number of shader names that may be returned in | |
7704 | @var{shaders} is specified by @var{maxCount}. | |
7705 | ||
7706 | If the number of names actually returned is not required (for instance, | |
7707 | if it has just been obtained by calling @code{glGetProgram}), a value of | |
7708 | @code{NULL} may be passed for count. If no shader objects are attached | |
7709 | to @var{program}, a value of 0 will be returned in @var{count}. The | |
7710 | actual number of attached shaders can be obtained by calling | |
7711 | @code{glGetProgram} with the value @code{GL_ATTACHED_SHADERS}. | |
7712 | ||
8925f36f AW |
7713 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
7714 | generated by OpenGL. | |
7715 | ||
7716 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
7717 | program object. | |
7718 | ||
7719 | @code{GL_INVALID_VALUE} is generated if @var{maxCount} is less than 0. | |
7720 | ||
7721 | @code{GL_INVALID_OPERATION} is generated if @code{glGetAttachedShaders} | |
7722 | is executed between the execution of @code{glBegin} and the | |
7723 | corresponding execution of @code{glEnd}. | |
7724 | ||
bb894c9d | 7725 | @end deftypefun |
8925f36f | 7726 | |
bb894c9d | 7727 | @deftypefun GLint glGetAttribLocation program name |
3c9b6116 AW |
7728 | Returns the location of an attribute variable. |
7729 | ||
8925f36f AW |
7730 | @table @asis |
7731 | @item @var{program} | |
7732 | Specifies the program object to be queried. | |
7733 | ||
7734 | @item @var{name} | |
7735 | Points to a null terminated string containing the name of the attribute | |
7736 | variable whose location is to be queried. | |
7737 | ||
7738 | @end table | |
7739 | ||
8925f36f AW |
7740 | @code{glGetAttribLocation} queries the previously linked program object |
7741 | specified by @var{program} for the attribute variable specified by | |
7742 | @var{name} and returns the index of the generic vertex attribute that is | |
7743 | bound to that attribute variable. If @var{name} is a matrix attribute | |
7744 | variable, the index of the first column of the matrix is returned. If | |
7745 | the named attribute variable is not an active attribute in the specified | |
7746 | program object or if @var{name} starts with the reserved prefix "gl_", a | |
7747 | value of -1 is returned. | |
7748 | ||
7749 | The association between an attribute variable name and a generic | |
7750 | attribute index can be specified at any time by calling | |
7751 | @code{glBindAttribLocation}. Attribute bindings do not go into effect | |
7752 | until @code{glLinkProgram} is called. After a program object has been | |
7753 | linked successfully, the index values for attribute variables remain | |
7754 | fixed until the next link command occurs. The attribute values can only | |
7755 | be queried after a link if the link was successful. | |
7756 | @code{glGetAttribLocation} returns the binding that actually went into | |
7757 | effect the last time @code{glLinkProgram} was called for the specified | |
7758 | program object. Attribute bindings that have been specified since the | |
7759 | last link operation are not returned by @code{glGetAttribLocation}. | |
7760 | ||
8925f36f AW |
7761 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a value |
7762 | generated by OpenGL. | |
7763 | ||
7764 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
7765 | program object. | |
7766 | ||
7767 | @code{GL_INVALID_OPERATION} is generated if @var{program} has not been | |
7768 | successfully linked. | |
7769 | ||
7770 | @code{GL_INVALID_OPERATION} is generated if @code{glGetAttribLocation} | |
7771 | is executed between the execution of @code{glBegin} and the | |
7772 | corresponding execution of @code{glEnd}. | |
7773 | ||
bb894c9d | 7774 | @end deftypefun |
8925f36f | 7775 | |
b002944d AW |
7776 | @deftypefun void glGetBufferParameteriv target value data |
7777 | Return parameters of a buffer object. | |
7778 | ||
7779 | @table @asis | |
7780 | @item @var{target} | |
7781 | Specifies the target buffer object. The symbolic constant must be | |
7782 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
7783 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
7784 | ||
7785 | @item @var{value} | |
7786 | Specifies the symbolic name of a buffer object parameter. Accepted | |
7787 | values are @code{GL_BUFFER_ACCESS}, @code{GL_BUFFER_MAPPED}, | |
7788 | @code{GL_BUFFER_SIZE}, or @code{GL_BUFFER_USAGE}. | |
7789 | ||
7790 | @item @var{data} | |
7791 | Returns the requested parameter. | |
7792 | ||
7793 | @end table | |
7794 | ||
7795 | @code{glGetBufferParameteriv} returns in @var{data} a selected parameter | |
7796 | of the buffer object specified by @var{target}. | |
7797 | ||
7798 | @var{value} names a specific buffer object parameter, as follows: | |
7799 | ||
7800 | @table @asis | |
7801 | @item @code{GL_BUFFER_ACCESS} | |
7802 | @var{params} returns the access policy set while mapping the buffer | |
7803 | object. The initial value is @code{GL_READ_WRITE}. | |
7804 | ||
7805 | @item @code{GL_BUFFER_MAPPED} | |
7806 | @var{params} returns a flag indicating whether the buffer object is | |
7807 | currently mapped. The initial value is @code{GL_FALSE}. | |
7808 | ||
7809 | @item @code{GL_BUFFER_SIZE} | |
7810 | @var{params} returns the size of the buffer object, measured in bytes. | |
7811 | The initial value is 0. | |
7812 | ||
7813 | @item @code{GL_BUFFER_USAGE} | |
7814 | @var{params} returns the buffer object's usage pattern. The initial | |
7815 | value is @code{GL_STATIC_DRAW}. | |
7816 | ||
7817 | @end table | |
7818 | ||
7819 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{value} is | |
7820 | not an accepted value. | |
7821 | ||
7822 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
7823 | name 0 is bound to @var{target}. | |
7824 | ||
7825 | @code{GL_INVALID_OPERATION} is generated if | |
7826 | @code{glGetBufferParameteriv} is executed between the execution of | |
7827 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
7828 | ||
7829 | @end deftypefun | |
7830 | ||
7831 | @deftypefun void glGetBufferPointerv target pname params | |
7832 | Return the pointer to a mapped buffer object's data store. | |
7833 | ||
7834 | @table @asis | |
7835 | @item @var{target} | |
7836 | Specifies the target buffer object. The symbolic constant must be | |
7837 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
7838 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
7839 | ||
7840 | @item @var{pname} | |
7841 | Specifies the pointer to be returned. The symbolic constant must be | |
7842 | @code{GL_BUFFER_MAP_POINTER}. | |
7843 | ||
7844 | @item @var{params} | |
7845 | Returns the pointer value specified by @var{pname}. | |
7846 | ||
7847 | @end table | |
7848 | ||
7849 | @code{glGetBufferPointerv} returns pointer information. @var{pname} is a | |
7850 | symbolic constant indicating the pointer to be returned, which must be | |
7851 | @code{GL_BUFFER_MAP_POINTER}, the pointer to which the buffer object's | |
7852 | data store is mapped. If the data store is not currently mapped, | |
7853 | @code{NULL} is returned. @var{params} is a pointer to a location in | |
7854 | which to place the returned pointer value. | |
7855 | ||
7856 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
7857 | not an accepted value. | |
7858 | ||
7859 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
7860 | name 0 is bound to @var{target}. | |
7861 | ||
7862 | @code{GL_INVALID_OPERATION} is generated if @code{glGetBufferPointerv} | |
7863 | is executed between the execution of @code{glBegin} and the | |
7864 | corresponding execution of @code{glEnd}. | |
7865 | ||
7866 | @end deftypefun | |
7867 | ||
bb894c9d | 7868 | @deftypefun void glGetBufferSubData target offset size data |
3c9b6116 AW |
7869 | Returns a subset of a buffer object's data store. |
7870 | ||
8925f36f AW |
7871 | @table @asis |
7872 | @item @var{target} | |
7873 | Specifies the target buffer object. The symbolic constant must be | |
7874 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
7875 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
7876 | ||
7877 | @item @var{offset} | |
7878 | Specifies the offset into the buffer object's data store from which data | |
7879 | will be returned, measured in bytes. | |
7880 | ||
7881 | @item @var{size} | |
7882 | Specifies the size in bytes of the data store region being returned. | |
7883 | ||
7884 | @item @var{data} | |
7885 | Specifies a pointer to the location where buffer object data is | |
7886 | returned. | |
7887 | ||
7888 | @end table | |
7889 | ||
8925f36f AW |
7890 | @code{glGetBufferSubData} returns some or all of the data from the |
7891 | buffer object currently bound to @var{target}. Data starting at byte | |
7892 | offset @var{offset} and extending for @var{size} bytes is copied from | |
7893 | the data store to the memory pointed to by @var{data}. An error is | |
7894 | thrown if the buffer object is currently mapped, or if @var{offset} and | |
7895 | @var{size} together define a range beyond the bounds of the buffer | |
7896 | object's data store. | |
7897 | ||
8925f36f AW |
7898 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
7899 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
7900 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
7901 | ||
7902 | @code{GL_INVALID_VALUE} is generated if @var{offset} or @var{size} is | |
7903 | negative, or if together they define a region of memory that extends | |
7904 | beyond the buffer object's allocated data store. | |
7905 | ||
7906 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
7907 | name 0 is bound to @var{target}. | |
7908 | ||
7909 | @code{GL_INVALID_OPERATION} is generated if the buffer object being | |
7910 | queried is mapped. | |
7911 | ||
7912 | @code{GL_INVALID_OPERATION} is generated if @code{glGetBufferSubData} is | |
7913 | executed between the execution of @code{glBegin} and the corresponding | |
7914 | execution of @code{glEnd}. | |
7915 | ||
bb894c9d | 7916 | @end deftypefun |
8925f36f | 7917 | |
bb894c9d | 7918 | @deftypefun void glGetClipPlane plane equation |
3c9b6116 AW |
7919 | Return the coefficients of the specified clipping plane. |
7920 | ||
8925f36f AW |
7921 | @table @asis |
7922 | @item @var{plane} | |
7923 | Specifies a clipping plane. The number of clipping planes depends on the | |
7924 | implementation, but at least six clipping planes are supported. They are | |
3c9b6116 AW |
7925 | identified by symbolic names of the form @code{GL_CLIP_PLANE}@r{@var{i}} |
7926 | where i ranges from 0 to the value of @code{GL_MAX_CLIP_PLANES} - 1. | |
8925f36f AW |
7927 | |
7928 | @item @var{equation} | |
7929 | Returns four double-precision values that are the coefficients of the | |
7930 | plane equation of @var{plane} in eye coordinates. The initial value is | |
7931 | (0, 0, 0, 0). | |
7932 | ||
7933 | @end table | |
7934 | ||
8925f36f AW |
7935 | @code{glGetClipPlane} returns in @var{equation} the four coefficients of |
7936 | the plane equation for @var{plane}. | |
7937 | ||
8925f36f AW |
7938 | @code{GL_INVALID_ENUM} is generated if @var{plane} is not an accepted |
7939 | value. | |
7940 | ||
7941 | @code{GL_INVALID_OPERATION} is generated if @code{glGetClipPlane} is | |
7942 | executed between the execution of @code{glBegin} and the corresponding | |
7943 | execution of @code{glEnd}. | |
7944 | ||
bb894c9d | 7945 | @end deftypefun |
8925f36f | 7946 | |
b002944d AW |
7947 | @deftypefun void glGetColorTableParameterfv target pname params |
7948 | @deftypefunx void glGetColorTableParameteriv target pname params | |
7949 | Get color lookup table parameters. | |
7950 | ||
7951 | @table @asis | |
7952 | @item @var{target} | |
7953 | The target color table. Must be @code{GL_COLOR_TABLE}, | |
7954 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, | |
7955 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{GL_PROXY_COLOR_TABLE}, | |
7956 | @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or | |
7957 | @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}. | |
7958 | ||
7959 | @item @var{pname} | |
7960 | The symbolic name of a color lookup table parameter. Must be one of | |
7961 | @code{GL_COLOR_TABLE_BIAS}, @code{GL_COLOR_TABLE_SCALE}, | |
7962 | @code{GL_COLOR_TABLE_FORMAT}, @code{GL_COLOR_TABLE_WIDTH}, | |
7963 | @code{GL_COLOR_TABLE_RED_SIZE}, @code{GL_COLOR_TABLE_GREEN_SIZE}, | |
7964 | @code{GL_COLOR_TABLE_BLUE_SIZE}, @code{GL_COLOR_TABLE_ALPHA_SIZE}, | |
7965 | @code{GL_COLOR_TABLE_LUMINANCE_SIZE}, or | |
7966 | @code{GL_COLOR_TABLE_INTENSITY_SIZE}. | |
7967 | ||
7968 | @item @var{params} | |
7969 | A pointer to an array where the values of the parameter will be stored. | |
7970 | ||
7971 | @end table | |
7972 | ||
7973 | Returns parameters specific to color table @var{target}. | |
7974 | ||
7975 | When @var{pname} is set to @code{GL_COLOR_TABLE_SCALE} or | |
7976 | @code{GL_COLOR_TABLE_BIAS}, @code{glGetColorTableParameter} returns the | |
7977 | color table scale or bias parameters for the table specified by | |
7978 | @var{target}. For these queries, @var{target} must be set to | |
7979 | @code{GL_COLOR_TABLE}, @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or | |
7980 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} and @var{params} points to an | |
7981 | array of four elements, which receive the scale or bias factors for red, | |
7982 | green, blue, and alpha, in that order. | |
7983 | ||
7984 | @code{glGetColorTableParameter} can also be used to retrieve the format | |
7985 | and size parameters for a color table. For these queries, set | |
7986 | @var{target} to either the color table target or the proxy color table | |
7987 | target. The format and size parameters are set by @code{glColorTable}. | |
7988 | ||
7989 | The following table lists the format and size parameters that may be | |
7990 | queried. For each symbolic constant listed below for @var{pname}, | |
7991 | @var{params} must point to an array of the given length and receive the | |
7992 | values indicated. | |
7993 | ||
7994 | ||
7995 | ||
7996 | @table @asis | |
7997 | @item @strong{Parameter} | |
7998 | @strong{N}, @strong{Meaning} | |
7999 | ||
8000 | @item @code{GL_COLOR_TABLE_FORMAT} | |
8001 | 1 , Internal format (e.g., @code{GL_RGBA}) | |
8002 | ||
8003 | @item @code{GL_COLOR_TABLE_WIDTH} | |
8004 | 1 , Number of elements in table | |
8005 | ||
8006 | @item @code{GL_COLOR_TABLE_RED_SIZE} | |
8007 | 1 , Size of red component, in bits | |
8008 | ||
8009 | @item @code{GL_COLOR_TABLE_GREEN_SIZE} | |
8010 | 1 , Size of green component | |
8011 | ||
8012 | @item @code{GL_COLOR_TABLE_BLUE_SIZE} | |
8013 | 1 , Size of blue component | |
8014 | ||
8015 | @item @code{GL_COLOR_TABLE_ALPHA_SIZE} | |
8016 | 1 , Size of alpha component | |
8017 | ||
8018 | @item @code{GL_COLOR_TABLE_LUMINANCE_SIZE} | |
8019 | 1 , Size of luminance component | |
8020 | ||
8021 | @item @code{GL_COLOR_TABLE_INTENSITY_SIZE} | |
8022 | 1 , Size of intensity component | |
8023 | ||
8024 | @end table | |
8025 | ||
8026 | ||
8027 | ||
8028 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
8029 | not an acceptable value. | |
8030 | ||
8031 | @code{GL_INVALID_OPERATION} is generated if | |
8032 | @code{glGetColorTableParameter} is executed between the execution of | |
8033 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
8034 | ||
8035 | @end deftypefun | |
8036 | ||
bb894c9d | 8037 | @deftypefun void glGetColorTable target format type table |
3c9b6116 AW |
8038 | Retrieve contents of a color lookup table. |
8039 | ||
8925f36f AW |
8040 | @table @asis |
8041 | @item @var{target} | |
8042 | Must be @code{GL_COLOR_TABLE}, @code{GL_POST_CONVOLUTION_COLOR_TABLE}, | |
8043 | or @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
8044 | ||
8045 | @item @var{format} | |
8046 | The format of the pixel data in @var{table}. The possible values are | |
8047 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, | |
8048 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, | |
8049 | @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}. | |
8050 | ||
8051 | @item @var{type} | |
8052 | The type of the pixel data in @var{table}. Symbolic constants | |
8053 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
8054 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
8055 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
8056 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
8057 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
8058 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
8059 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
8060 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
8061 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
8062 | ||
8063 | @item @var{table} | |
8064 | Pointer to a one-dimensional array of pixel data containing the contents | |
8065 | of the color table. | |
8066 | ||
8067 | @end table | |
8068 | ||
8925f36f AW |
8069 | @code{glGetColorTable} returns in @var{table} the contents of the color |
8070 | table specified by @var{target}. No pixel transfer operations are | |
8071 | performed, but pixel storage modes that are applicable to | |
8072 | @code{glReadPixels} are performed. | |
8073 | ||
8074 | If a non-zero named buffer object is bound to the | |
8075 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
8076 | histogram table is requested, @var{table} is treated as a byte offset | |
8077 | into the buffer object's data store. | |
8078 | ||
8079 | Color components that are requested in the specified @var{format}, but | |
8080 | which are not included in the internal format of the color lookup table, | |
8081 | are returned as zero. The assignments of internal color components to | |
8082 | the components requested by @var{format} are | |
8083 | ||
8084 | @table @asis | |
8085 | @item @strong{Internal Component} | |
8086 | @strong{Resulting Component} | |
8087 | ||
8088 | @item | |
8089 | Red | |
8090 | Red | |
8091 | ||
8092 | @item | |
8093 | Green | |
8094 | Green | |
8095 | ||
8096 | @item | |
8097 | Blue | |
8098 | Blue | |
8099 | ||
8100 | @item | |
8101 | Alpha | |
8102 | Alpha | |
8103 | ||
8104 | @item | |
8105 | Luminance | |
8106 | Red | |
8107 | ||
8108 | @item | |
8109 | Intensity | |
8110 | Red | |
8111 | ||
8112 | @end table | |
8113 | ||
8114 | ||
8115 | ||
8925f36f AW |
8116 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
8117 | allowable values. | |
8118 | ||
8119 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
8120 | allowable values. | |
8121 | ||
8122 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
8123 | allowable values. | |
8124 | ||
8125 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8126 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
8127 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
8128 | and @var{format} is not @code{GL_RGB}. | |
8129 | ||
8130 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8131 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
8132 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
8133 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
8134 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
8135 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
8136 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
8137 | ||
8138 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8139 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
8140 | object's data store is currently mapped. | |
8141 | ||
8142 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8143 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
8144 | would be packed to the buffer object such that the memory writes | |
8145 | required would exceed the data store size. | |
8146 | ||
8147 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8148 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{table} | |
8149 | is not evenly divisible into the number of bytes needed to store in | |
8150 | memory a datum indicated by @var{type}. | |
8151 | ||
8152 | @code{GL_INVALID_OPERATION} is generated if @code{glGetColorTable} is | |
8153 | executed between the execution of @code{glBegin} and the corresponding | |
8154 | execution of @code{glEnd}. | |
8155 | ||
bb894c9d | 8156 | @end deftypefun |
8925f36f | 8157 | |
bb894c9d | 8158 | @deftypefun void glGetCompressedTexImage target lod img |
3c9b6116 AW |
8159 | Return a compressed texture image. |
8160 | ||
8925f36f AW |
8161 | @table @asis |
8162 | @item @var{target} | |
8163 | Specifies which texture is to be obtained. @code{GL_TEXTURE_1D}, | |
8164 | @code{GL_TEXTURE_2D}, and | |
8165 | @code{GL_TEXTURE_3D}@code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
8166 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
8167 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
8168 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
8169 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, and | |
8170 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z} are accepted. | |
8171 | ||
8172 | @item @var{lod} | |
8173 | Specifies the level-of-detail number of the desired image. Level 0 is | |
3c9b6116 AW |
8174 | the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap |
8175 | reduction image. | |
8925f36f AW |
8176 | |
8177 | @item @var{img} | |
8178 | Returns the compressed texture image. | |
8179 | ||
8180 | @end table | |
8181 | ||
8925f36f AW |
8182 | @code{glGetCompressedTexImage} returns the compressed texture image |
8183 | associated with @var{target} and @var{lod} into @var{img}. @var{img} | |
8184 | should be an array of @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} bytes. | |
8185 | @var{target} specifies whether the desired texture image was one | |
8186 | specified by @code{glTexImage1D} (@code{GL_TEXTURE_1D}), | |
8187 | @code{glTexImage2D} (@code{GL_TEXTURE_2D} or any of | |
8188 | @code{GL_TEXTURE_CUBE_MAP_*}), or @code{glTexImage3D} | |
8189 | (@code{GL_TEXTURE_3D}). @var{lod} specifies the level-of-detail number | |
8190 | of the desired image. | |
8191 | ||
8192 | If a non-zero named buffer object is bound to the | |
8193 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
8194 | texture image is requested, @var{img} is treated as a byte offset into | |
8195 | the buffer object's data store. | |
8196 | ||
8197 | To minimize errors, first verify that the texture is compressed by | |
8198 | calling @code{glGetTexLevelParameter} with argument | |
8199 | @code{GL_TEXTURE_COMPRESSED}. If the texture is compressed, then | |
8200 | determine the amount of memory required to store the compressed texture | |
8201 | by calling @code{glGetTexLevelParameter} with argument | |
8202 | @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE}. Finally, retrieve the internal | |
8203 | format of the texture by calling @code{glGetTexLevelParameter} with | |
8204 | argument @code{GL_TEXTURE_INTERNAL_FORMAT}. To store the texture for | |
8205 | later use, associate the internal format and size with the retrieved | |
8206 | texture image. These data can be used by the respective texture or | |
8207 | subtexture loading routine used for loading @var{target} textures. | |
8208 | ||
8925f36f AW |
8209 | @code{GL_INVALID_VALUE} is generated if @var{lod} is less than zero or |
8210 | greater than the maximum number of LODs permitted by the implementation. | |
8211 | ||
8212 | @code{GL_INVALID_OPERATION} is generated if | |
8213 | @code{glGetCompressedTexImage} is used to retrieve a texture that is in | |
8214 | an uncompressed internal format. | |
8215 | ||
8216 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8217 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
8218 | object's data store is currently mapped. | |
8219 | ||
8220 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8221 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
8222 | would be packed to the buffer object such that the memory writes | |
8223 | required would exceed the data store size. | |
8224 | ||
8225 | @code{GL_INVALID_OPERATION} is generated if | |
8226 | @code{glGetCompressedTexImage} is executed between the execution of | |
8227 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
8228 | ||
bb894c9d | 8229 | @end deftypefun |
8925f36f | 8230 | |
bb894c9d | 8231 | @deftypefun void glGetConvolutionFilter target format type image |
3c9b6116 AW |
8232 | Get current 1D or 2D convolution filter kernel. |
8233 | ||
8925f36f AW |
8234 | @table @asis |
8235 | @item @var{target} | |
8236 | The filter to be retrieved. Must be one of @code{GL_CONVOLUTION_1D} or | |
8237 | @code{GL_CONVOLUTION_2D}. | |
8238 | ||
8239 | @item @var{format} | |
8240 | Format of the output image. Must be one of @code{GL_RED}, | |
8241 | @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, | |
8242 | @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, or | |
8243 | @code{GL_LUMINANCE_ALPHA}. | |
8244 | ||
8245 | @item @var{type} | |
8246 | Data type of components in the output image. Symbolic constants | |
8247 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
8248 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
8249 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
8250 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
8251 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
8252 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
8253 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
8254 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
8255 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
8256 | ||
8257 | @item @var{image} | |
8258 | Pointer to storage for the output image. | |
8259 | ||
8260 | @end table | |
8261 | ||
8925f36f AW |
8262 | @code{glGetConvolutionFilter} returns the current 1D or 2D convolution |
8263 | filter kernel as an image. The one- or two-dimensional image is placed | |
8264 | in @var{image} according to the specifications in @var{format} and | |
8265 | @var{type}. No pixel transfer operations are performed on this image, | |
8266 | but the relevant pixel storage modes are applied. | |
8267 | ||
8268 | If a non-zero named buffer object is bound to the | |
8269 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
8270 | convolution filter is requested, @var{image} is treated as a byte offset | |
8271 | into the buffer object's data store. | |
8272 | ||
8273 | Color components that are present in @var{format} but not included in | |
8274 | the internal format of the filter are returned as zero. The assignments | |
8275 | of internal color components to the components of @var{format} are as | |
8276 | follows. | |
8277 | ||
8278 | @table @asis | |
8279 | @item @strong{Internal Component} | |
8280 | @strong{Resulting Component} | |
8281 | ||
8282 | @item | |
8283 | Red | |
8284 | Red | |
8285 | ||
8286 | @item | |
8287 | Green | |
8288 | Green | |
8289 | ||
8290 | @item | |
8291 | Blue | |
8292 | Blue | |
8293 | ||
8294 | @item | |
8295 | Alpha | |
8296 | Alpha | |
8297 | ||
8298 | @item | |
8299 | Luminance | |
8300 | Red | |
8301 | ||
8302 | @item | |
8303 | Intensity | |
8304 | Red | |
8305 | ||
8306 | @end table | |
8307 | ||
8308 | ||
8309 | ||
8925f36f AW |
8310 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
8311 | allowable values. | |
8312 | ||
8313 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
8314 | allowable values. | |
8315 | ||
8316 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
8317 | allowable values. | |
8318 | ||
8319 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8320 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
8321 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
8322 | and @var{format} is not @code{GL_RGB}. | |
8323 | ||
8324 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8325 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
8326 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
8327 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
8328 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
8329 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
8330 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
8331 | ||
8332 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8333 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
8334 | object's data store is currently mapped. | |
8335 | ||
8336 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8337 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
8338 | would be packed to the buffer object such that the memory writes | |
8339 | required would exceed the data store size. | |
8340 | ||
8341 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8342 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{image} | |
8343 | is not evenly divisible into the number of bytes needed to store in | |
8344 | memory a datum indicated by @var{type}. | |
8345 | ||
8346 | @code{GL_INVALID_OPERATION} is generated if | |
8347 | @code{glGetConvolutionFilter} is executed between the execution of | |
8348 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
8349 | ||
bb894c9d | 8350 | @end deftypefun |
8925f36f | 8351 | |
b002944d AW |
8352 | @deftypefun void glGetConvolutionParameterfv target pname params |
8353 | @deftypefunx void glGetConvolutionParameteriv target pname params | |
8354 | Get convolution parameters. | |
8355 | ||
8356 | @table @asis | |
8357 | @item @var{target} | |
8358 | The filter whose parameters are to be retrieved. Must be one of | |
8359 | @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or | |
8360 | @code{GL_SEPARABLE_2D}. | |
8361 | ||
8362 | @item @var{pname} | |
8363 | The parameter to be retrieved. Must be one of | |
8364 | @code{GL_CONVOLUTION_BORDER_MODE}, @code{GL_CONVOLUTION_BORDER_COLOR}, | |
8365 | @code{GL_CONVOLUTION_FILTER_SCALE}, @code{GL_CONVOLUTION_FILTER_BIAS}, | |
8366 | @code{GL_CONVOLUTION_FORMAT}, @code{GL_CONVOLUTION_WIDTH}, | |
8367 | @code{GL_CONVOLUTION_HEIGHT}, @code{GL_MAX_CONVOLUTION_WIDTH}, or | |
8368 | @code{GL_MAX_CONVOLUTION_HEIGHT}. | |
8369 | ||
8370 | @item @var{params} | |
8371 | Pointer to storage for the parameters to be retrieved. | |
8372 | ||
8373 | @end table | |
8374 | ||
8375 | @code{glGetConvolutionParameter} retrieves convolution parameters. | |
8376 | @var{target} determines which convolution filter is queried. @var{pname} | |
8377 | determines which parameter is returned: | |
8378 | ||
8379 | @table @asis | |
8380 | @item @code{GL_CONVOLUTION_BORDER_MODE} | |
8381 | ||
8382 | ||
8383 | The convolution border mode. See @code{glConvolutionParameter} for a | |
8384 | list of border modes. | |
8385 | ||
8386 | @item @code{GL_CONVOLUTION_BORDER_COLOR} | |
8387 | ||
8388 | ||
8389 | The current convolution border color. @var{params} must be a pointer to | |
8390 | an array of four elements, which will receive the red, green, blue, and | |
8391 | alpha border colors. | |
8392 | ||
8393 | @item @code{GL_CONVOLUTION_FILTER_SCALE} | |
8394 | ||
8395 | ||
8396 | The current filter scale factors. @var{params} must be a pointer to an | |
8397 | array of four elements, which will receive the red, green, blue, and | |
8398 | alpha filter scale factors in that order. | |
8399 | ||
8400 | @item @code{GL_CONVOLUTION_FILTER_BIAS} | |
8401 | ||
8402 | ||
8403 | The current filter bias factors. @var{params} must be a pointer to an | |
8404 | array of four elements, which will receive the red, green, blue, and | |
8405 | alpha filter bias terms in that order. | |
8406 | ||
8407 | @item @code{GL_CONVOLUTION_FORMAT} | |
8408 | ||
8409 | ||
8410 | The current internal format. See @code{glConvolutionFilter1D}, | |
8411 | @code{glConvolutionFilter2D}, and @code{glSeparableFilter2D} for lists | |
8412 | of allowable formats. | |
8413 | ||
8414 | @item @code{GL_CONVOLUTION_WIDTH} | |
8415 | ||
8416 | ||
8417 | The current filter image width. | |
8418 | ||
8419 | @item @code{GL_CONVOLUTION_HEIGHT} | |
8420 | ||
8421 | ||
8422 | The current filter image height. | |
8423 | ||
8424 | @item @code{GL_MAX_CONVOLUTION_WIDTH} | |
8425 | ||
8426 | ||
8427 | The maximum acceptable filter image width. | |
8428 | ||
8429 | @item @code{GL_MAX_CONVOLUTION_HEIGHT} | |
8430 | ||
8431 | ||
8432 | The maximum acceptable filter image height. | |
8433 | ||
8434 | @end table | |
8435 | ||
8436 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the | |
8437 | allowable values. | |
8438 | ||
8439 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the | |
8440 | allowable values. | |
8441 | ||
8442 | @code{GL_INVALID_ENUM} is generated if @var{target} is | |
8443 | @code{GL_CONVOLUTION_1D} and @var{pname} is @code{GL_CONVOLUTION_HEIGHT} | |
8444 | or @code{GL_MAX_CONVOLUTION_HEIGHT}. | |
8445 | ||
8446 | @code{GL_INVALID_OPERATION} is generated if | |
8447 | @code{glGetConvolutionParameter} is executed between the execution of | |
8448 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
8449 | ||
8450 | @end deftypefun | |
8451 | ||
bb894c9d | 8452 | @deftypefun GLenum glGetError |
3c9b6116 AW |
8453 | Return error information. |
8454 | ||
8925f36f AW |
8455 | @code{glGetError} returns the value of the error flag. Each detectable |
8456 | error is assigned a numeric code and symbolic name. When an error | |
8457 | occurs, the error flag is set to the appropriate error code value. No | |
8458 | other errors are recorded until @code{glGetError} is called, the error | |
8459 | code is returned, and the flag is reset to @code{GL_NO_ERROR}. If a call | |
8460 | to @code{glGetError} returns @code{GL_NO_ERROR}, there has been no | |
8461 | detectable error since the last call to @code{glGetError}, or since the | |
8462 | GL was initialized. | |
8463 | ||
8464 | To allow for distributed implementations, there may be several error | |
8465 | flags. If any single error flag has recorded an error, the value of that | |
8466 | flag is returned and that flag is reset to @code{GL_NO_ERROR} when | |
8467 | @code{glGetError} is called. If more than one flag has recorded an | |
8468 | error, @code{glGetError} returns and clears an arbitrary error flag | |
8469 | value. Thus, @code{glGetError} should always be called in a loop, until | |
8470 | it returns @code{GL_NO_ERROR}, if all error flags are to be reset. | |
8471 | ||
8472 | Initially, all error flags are set to @code{GL_NO_ERROR}. | |
8473 | ||
8474 | The following errors are currently defined: | |
8475 | ||
8476 | @table @asis | |
8477 | @item @code{GL_NO_ERROR} | |
8478 | No error has been recorded. The value of this symbolic constant is | |
8479 | guaranteed to be 0. | |
8480 | ||
8481 | @item @code{GL_INVALID_ENUM} | |
8482 | An unacceptable value is specified for an enumerated argument. The | |
8483 | offending command is ignored and has no other side effect than to set | |
8484 | the error flag. | |
8485 | ||
8486 | @item @code{GL_INVALID_VALUE} | |
8487 | A numeric argument is out of range. The offending command is ignored and | |
8488 | has no other side effect than to set the error flag. | |
8489 | ||
8490 | @item @code{GL_INVALID_OPERATION} | |
8491 | The specified operation is not allowed in the current state. The | |
8492 | offending command is ignored and has no other side effect than to set | |
8493 | the error flag. | |
8494 | ||
8495 | @item @code{GL_STACK_OVERFLOW} | |
8496 | This command would cause a stack overflow. The offending command is | |
8497 | ignored and has no other side effect than to set the error flag. | |
8498 | ||
8499 | @item @code{GL_STACK_UNDERFLOW} | |
8500 | This command would cause a stack underflow. The offending command is | |
8501 | ignored and has no other side effect than to set the error flag. | |
8502 | ||
8503 | @item @code{GL_OUT_OF_MEMORY} | |
8504 | There is not enough memory left to execute the command. The state of the | |
8505 | GL is undefined, except for the state of the error flags, after this | |
8506 | error is recorded. | |
8507 | ||
8508 | @item @code{GL_TABLE_TOO_LARGE} | |
8509 | The specified table exceeds the implementation's maximum supported table | |
8510 | size. The offending command is ignored and has no other side effect than | |
8511 | to set the error flag. | |
8512 | ||
8513 | @end table | |
8514 | ||
8515 | When an error flag is set, results of a GL operation are undefined only | |
8516 | if @code{GL_OUT_OF_MEMORY} has occurred. In all other cases, the command | |
8517 | generating the error is ignored and has no effect on the GL state or | |
8518 | frame buffer contents. If the generating command returns a value, it | |
8519 | returns 0. If @code{glGetError} itself generates an error, it returns 0. | |
8520 | ||
8925f36f AW |
8521 | @code{GL_INVALID_OPERATION} is generated if @code{glGetError} is |
8522 | executed between the execution of @code{glBegin} and the corresponding | |
8523 | execution of @code{glEnd}. In this case, @code{glGetError} returns 0. | |
8524 | ||
bb894c9d | 8525 | @end deftypefun |
8925f36f | 8526 | |
b002944d AW |
8527 | @deftypefun void glGetHistogramParameterfv target pname params |
8528 | @deftypefunx void glGetHistogramParameteriv target pname params | |
8529 | Get histogram parameters. | |
8530 | ||
8531 | @table @asis | |
8532 | @item @var{target} | |
8533 | Must be one of @code{GL_HISTOGRAM} or @code{GL_PROXY_HISTOGRAM}. | |
8534 | ||
8535 | @item @var{pname} | |
8536 | The name of the parameter to be retrieved. Must be one of | |
8537 | @code{GL_HISTOGRAM_WIDTH}, @code{GL_HISTOGRAM_FORMAT}, | |
8538 | @code{GL_HISTOGRAM_RED_SIZE}, @code{GL_HISTOGRAM_GREEN_SIZE}, | |
8539 | @code{GL_HISTOGRAM_BLUE_SIZE}, @code{GL_HISTOGRAM_ALPHA_SIZE}, | |
8540 | @code{GL_HISTOGRAM_LUMINANCE_SIZE}, or @code{GL_HISTOGRAM_SINK}. | |
8541 | ||
8542 | @item @var{params} | |
8543 | Pointer to storage for the returned values. | |
8544 | ||
8545 | @end table | |
8546 | ||
8547 | @code{glGetHistogramParameter} is used to query parameter values for the | |
8548 | current histogram or for a proxy. The histogram state information may be | |
8549 | queried by calling @code{glGetHistogramParameter} with a @var{target} of | |
8550 | @code{GL_HISTOGRAM} (to obtain information for the current histogram | |
8551 | table) or @code{GL_PROXY_HISTOGRAM} (to obtain information from the most | |
8552 | recent proxy request) and one of the following values for the | |
8553 | @var{pname} argument: | |
8554 | ||
8555 | ||
8556 | ||
8557 | @table @asis | |
8558 | @item @strong{Parameter} | |
8559 | @strong{Description} | |
8560 | ||
8561 | @item @code{GL_HISTOGRAM_WIDTH} | |
8562 | Histogram table width | |
8563 | ||
8564 | @item @code{GL_HISTOGRAM_FORMAT} | |
8565 | Internal format | |
8566 | ||
8567 | @item @code{GL_HISTOGRAM_RED_SIZE} | |
8568 | Red component counter size, in bits | |
8569 | ||
8570 | @item @code{GL_HISTOGRAM_GREEN_SIZE} | |
8571 | Green component counter size, in bits | |
8572 | ||
8573 | @item @code{GL_HISTOGRAM_BLUE_SIZE} | |
8574 | Blue component counter size, in bits | |
8575 | ||
8576 | @item @code{GL_HISTOGRAM_ALPHA_SIZE} | |
8577 | Alpha component counter size, in bits | |
8578 | ||
8579 | @item @code{GL_HISTOGRAM_LUMINANCE_SIZE} | |
8580 | Luminance component counter size, in bits | |
8581 | ||
8582 | @item @code{GL_HISTOGRAM_SINK} | |
8583 | Value of the @var{sink} parameter | |
8584 | ||
8585 | @end table | |
8586 | ||
8587 | ||
8588 | ||
8589 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the | |
8590 | allowable values. | |
8591 | ||
8592 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the | |
8593 | allowable values. | |
8594 | ||
8595 | @code{GL_INVALID_OPERATION} is generated if | |
8596 | @code{glGetHistogramParameter} is executed between the execution of | |
8597 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
8598 | ||
8599 | @end deftypefun | |
8600 | ||
bb894c9d | 8601 | @deftypefun void glGetHistogram target reset format type values |
3c9b6116 AW |
8602 | Get histogram table. |
8603 | ||
8925f36f AW |
8604 | @table @asis |
8605 | @item @var{target} | |
8606 | Must be @code{GL_HISTOGRAM}. | |
8607 | ||
8608 | @item @var{reset} | |
8609 | If @code{GL_TRUE}, each component counter that is actually returned is | |
8610 | reset to zero. (Other counters are unaffected.) If @code{GL_FALSE}, none | |
8611 | of the counters in the histogram table is modified. | |
8612 | ||
8613 | @item @var{format} | |
8614 | The format of values to be returned in @var{values}. Must be one of | |
8615 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, | |
8616 | @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, | |
8617 | @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}. | |
8618 | ||
8619 | @item @var{type} | |
8620 | The type of values to be returned in @var{values}. Symbolic constants | |
8621 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
8622 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
8623 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
8624 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
8625 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
8626 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
8627 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
8628 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
8629 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
8630 | ||
8631 | @item @var{values} | |
8632 | A pointer to storage for the returned histogram table. | |
8633 | ||
8634 | @end table | |
8635 | ||
8925f36f AW |
8636 | @code{glGetHistogram} returns the current histogram table as a |
8637 | one-dimensional image with the same width as the histogram. No pixel | |
8638 | transfer operations are performed on this image, but pixel storage modes | |
8639 | that are applicable to 1D images are honored. | |
8640 | ||
8641 | If a non-zero named buffer object is bound to the | |
8642 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
8643 | histogram table is requested, @var{values} is treated as a byte offset | |
8644 | into the buffer object's data store. | |
8645 | ||
8646 | Color components that are requested in the specified @var{format}, but | |
8647 | which are not included in the internal format of the histogram, are | |
8648 | returned as zero. The assignments of internal color components to the | |
8649 | components requested by @var{format} are: | |
8650 | ||
8651 | @table @asis | |
8652 | @item @strong{Internal Component} | |
8653 | @strong{Resulting Component} | |
8654 | ||
8655 | @item | |
8656 | Red | |
8657 | Red | |
8658 | ||
8659 | @item | |
8660 | Green | |
8661 | Green | |
8662 | ||
8663 | @item | |
8664 | Blue | |
8665 | Blue | |
8666 | ||
8667 | @item | |
8668 | Alpha | |
8669 | Alpha | |
8670 | ||
8671 | @item | |
8672 | Luminance | |
8673 | Red | |
8674 | ||
8675 | @end table | |
8676 | ||
8677 | ||
8678 | ||
8925f36f AW |
8679 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
8680 | @code{GL_HISTOGRAM}. | |
8681 | ||
8682 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
8683 | allowable values. | |
8684 | ||
8685 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
8686 | allowable values. | |
8687 | ||
8688 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8689 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
8690 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
8691 | and @var{format} is not @code{GL_RGB}. | |
8692 | ||
8693 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8694 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
8695 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
8696 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
8697 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
8698 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
8699 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
8700 | ||
8701 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8702 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
8703 | object's data store is currently mapped. | |
8704 | ||
8705 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8706 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
8707 | would be packed to the buffer object such that the memory writes | |
8708 | required would exceed the data store size. | |
8709 | ||
8710 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8711 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{values} | |
8712 | is not evenly divisible into the number of bytes needed to store in | |
8713 | memory a datum indicated by @var{type}. | |
8714 | ||
8715 | @code{GL_INVALID_OPERATION} is generated if @code{glGetHistogram} is | |
8716 | executed between the execution of @code{glBegin} and the corresponding | |
8717 | execution of @code{glEnd}. | |
8718 | ||
bb894c9d | 8719 | @end deftypefun |
8925f36f | 8720 | |
b002944d AW |
8721 | @deftypefun void glGetLightfv light pname params |
8722 | @deftypefunx void glGetLightiv light pname params | |
8723 | Return light source parameter values. | |
3c9b6116 | 8724 | |
8925f36f | 8725 | @table @asis |
b002944d AW |
8726 | @item @var{light} |
8727 | Specifies a light source. The number of possible lights depends on the | |
8728 | implementation, but at least eight lights are supported. They are | |
8729 | identified by symbolic names of the form @code{GL_LIGHT}@r{@var{i}} | |
8730 | where @r{@var{i}} ranges from 0 to the value of @code{GL_MAX_LIGHTS} - | |
8731 | 1. | |
8925f36f | 8732 | |
b002944d AW |
8733 | @item @var{pname} |
8734 | Specifies a light source parameter for @var{light}. Accepted symbolic | |
8735 | names are @code{GL_AMBIENT}, @code{GL_DIFFUSE}, @code{GL_SPECULAR}, | |
8736 | @code{GL_POSITION}, @code{GL_SPOT_DIRECTION}, @code{GL_SPOT_EXPONENT}, | |
8737 | @code{GL_SPOT_CUTOFF}, @code{GL_CONSTANT_ATTENUATION}, | |
8738 | @code{GL_LINEAR_ATTENUATION}, and @code{GL_QUADRATIC_ATTENUATION}. | |
8925f36f | 8739 | |
b002944d AW |
8740 | @item @var{params} |
8741 | Returns the requested data. | |
8925f36f | 8742 | |
b002944d | 8743 | @end table |
8925f36f | 8744 | |
b002944d AW |
8745 | @code{glGetLight} returns in @var{params} the value or values of a light |
8746 | source parameter. @var{light} names the light and is a symbolic name of | |
8747 | the form @code{GL_LIGHT}@r{@var{i}} where i ranges from 0 to the value | |
8748 | of @code{GL_MAX_LIGHTS} - 1. @code{GL_MAX_LIGHTS} is an implementation | |
8749 | dependent constant that is greater than or equal to eight. @var{pname} | |
8750 | specifies one of ten light source parameters, again by symbolic name. | |
8925f36f | 8751 | |
b002944d | 8752 | The following parameters are defined: |
8925f36f | 8753 | |
b002944d AW |
8754 | @table @asis |
8755 | @item @code{GL_AMBIENT} | |
8756 | @var{params} returns four integer or floating-point values representing | |
8757 | the ambient intensity of the light source. Integer values, when | |
8758 | requested, are linearly mapped from the internal floating-point | |
8759 | representation such that 1.0 maps to the most positive representable | |
8760 | integer value, and @r{-1.0} maps to the most negative representable | |
8761 | integer value. If the internal value is outside the range @r{[-1,1]}, | |
8762 | the corresponding integer return value is undefined. The initial value | |
8763 | is (0, 0, 0, 1). | |
8764 | ||
8765 | @item @code{GL_DIFFUSE} | |
8766 | @var{params} returns four integer or floating-point values representing | |
8767 | the diffuse intensity of the light source. Integer values, when | |
8768 | requested, are linearly mapped from the internal floating-point | |
8769 | representation such that 1.0 maps to the most positive representable | |
8770 | integer value, and @r{-1.0} maps to the most negative representable | |
8771 | integer value. If the internal value is outside the range @r{[-1,1]}, | |
8772 | the corresponding integer return value is undefined. The initial value | |
8773 | for @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial | |
8774 | value is (0, 0, 0, 0). | |
8775 | ||
8776 | @item @code{GL_SPECULAR} | |
8777 | @var{params} returns four integer or floating-point values representing | |
8778 | the specular intensity of the light source. Integer values, when | |
8779 | requested, are linearly mapped from the internal floating-point | |
8780 | representation such that 1.0 maps to the most positive representable | |
8781 | integer value, and @r{-1.0} maps to the most negative representable | |
8782 | integer value. If the internal value is outside the range @r{[-1,1]}, | |
8783 | the corresponding integer return value is undefined. The initial value | |
8784 | for @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial | |
8785 | value is (0, 0, 0, 0). | |
8786 | ||
8787 | @item @code{GL_POSITION} | |
8788 | @var{params} returns four integer or floating-point values representing | |
8789 | the position of the light source. Integer values, when requested, are | |
8790 | computed by rounding the internal floating-point values to the nearest | |
8791 | integer value. The returned values are those maintained in eye | |
8792 | coordinates. They will not be equal to the values specified using | |
8793 | @code{glLight}, unless the modelview matrix was identity at the time | |
8794 | @code{glLight} was called. The initial value is (0, 0, 1, 0). | |
8795 | ||
8796 | @item @code{GL_SPOT_DIRECTION} | |
8797 | @var{params} returns three integer or floating-point values representing | |
8798 | the direction of the light source. Integer values, when requested, are | |
8799 | computed by rounding the internal floating-point values to the nearest | |
8800 | integer value. The returned values are those maintained in eye | |
8801 | coordinates. They will not be equal to the values specified using | |
8802 | @code{glLight}, unless the modelview matrix was identity at the time | |
8803 | @code{glLight} was called. Although spot direction is normalized before | |
8804 | being used in the lighting equation, the returned values are the | |
8805 | transformed versions of the specified values prior to normalization. The | |
8806 | initial value is @r{(0,0-1)}. | |
8807 | ||
8808 | @item @code{GL_SPOT_EXPONENT} | |
8809 | @var{params} returns a single integer or floating-point value | |
8810 | representing the spot exponent of the light. An integer value, when | |
8811 | requested, is computed by rounding the internal floating-point | |
8812 | representation to the nearest integer. The initial value is 0. | |
8813 | ||
8814 | @item @code{GL_SPOT_CUTOFF} | |
8815 | @var{params} returns a single integer or floating-point value | |
8816 | representing the spot cutoff angle of the light. An integer value, when | |
8817 | requested, is computed by rounding the internal floating-point | |
8818 | representation to the nearest integer. The initial value is 180. | |
8819 | ||
8820 | @item @code{GL_CONSTANT_ATTENUATION} | |
8821 | @var{params} returns a single integer or floating-point value | |
8822 | representing the constant (not distance-related) attenuation of the | |
8823 | light. An integer value, when requested, is computed by rounding the | |
8824 | internal floating-point representation to the nearest integer. The | |
8825 | initial value is 1. | |
8826 | ||
8827 | @item @code{GL_LINEAR_ATTENUATION} | |
8828 | @var{params} returns a single integer or floating-point value | |
8829 | representing the linear attenuation of the light. An integer value, when | |
8830 | requested, is computed by rounding the internal floating-point | |
8831 | representation to the nearest integer. The initial value is 0. | |
8832 | ||
8833 | @item @code{GL_QUADRATIC_ATTENUATION} | |
8834 | @var{params} returns a single integer or floating-point value | |
8835 | representing the quadratic attenuation of the light. An integer value, | |
8836 | when requested, is computed by rounding the internal floating-point | |
8837 | representation to the nearest integer. The initial value is 0. | |
8838 | ||
8839 | @end table | |
8840 | ||
8841 | @code{GL_INVALID_ENUM} is generated if @var{light} or @var{pname} is not | |
8842 | an accepted value. | |
8843 | ||
8844 | @code{GL_INVALID_OPERATION} is generated if @code{glGetLight} is | |
8845 | executed between the execution of @code{glBegin} and the corresponding | |
8846 | execution of @code{glEnd}. | |
8847 | ||
8848 | @end deftypefun | |
8849 | ||
8850 | @deftypefun void glGetMapfv target query v | |
8851 | @deftypefunx void glGetMapiv target query v | |
8852 | Return evaluator parameters. | |
8853 | ||
8854 | @table @asis | |
8855 | @item @var{target} | |
8856 | Specifies the symbolic name of a map. Accepted values are | |
8857 | @code{GL_MAP1_COLOR_4}, @code{GL_MAP1_INDEX}, @code{GL_MAP1_NORMAL}, | |
8858 | @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2}, | |
8859 | @code{GL_MAP1_TEXTURE_COORD_3}, @code{GL_MAP1_TEXTURE_COORD_4}, | |
8860 | @code{GL_MAP1_VERTEX_3}, @code{GL_MAP1_VERTEX_4}, | |
8861 | @code{GL_MAP2_COLOR_4}, @code{GL_MAP2_INDEX}, @code{GL_MAP2_NORMAL}, | |
8862 | @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2}, | |
8863 | @code{GL_MAP2_TEXTURE_COORD_3}, @code{GL_MAP2_TEXTURE_COORD_4}, | |
8864 | @code{GL_MAP2_VERTEX_3}, and @code{GL_MAP2_VERTEX_4}. | |
8865 | ||
8866 | @item @var{query} | |
8867 | Specifies which parameter to return. Symbolic names @code{GL_COEFF}, | |
8868 | @code{GL_ORDER}, and @code{GL_DOMAIN} are accepted. | |
8869 | ||
8870 | @item @var{v} | |
8871 | Returns the requested data. | |
8872 | ||
8873 | @end table | |
8874 | ||
8875 | @code{glMap1} and @code{glMap2} define evaluators. @code{glGetMap} | |
8876 | returns evaluator parameters. @var{target} chooses a map, @var{query} | |
8877 | selects a specific parameter, and @var{v} points to storage where the | |
8878 | values will be returned. | |
8879 | ||
8880 | The acceptable values for the @var{target} parameter are described in | |
8881 | the @code{glMap1} and @code{glMap2} reference pages. | |
8882 | ||
8883 | @var{query} can assume the following values: | |
8884 | ||
8885 | @table @asis | |
8886 | @item @code{GL_COEFF} | |
8887 | @var{v} returns the control points for the evaluator function. | |
8888 | One-dimensional evaluators return @r{@var{order}} control points, and | |
8889 | two-dimensional evaluators return @r{@var{uorder}×@var{vorder}} control | |
8890 | points. Each control point consists of one, two, three, or four integer, | |
8891 | single-precision floating-point, or double-precision floating-point | |
8892 | values, depending on the type of the evaluator. The GL returns | |
8893 | two-dimensional control points in row-major order, incrementing the | |
8894 | @r{@var{uorder}} index quickly and the @r{@var{vorder}} index after each | |
8895 | row. Integer values, when requested, are computed by rounding the | |
8896 | internal floating-point values to the nearest integer values. | |
8897 | ||
8898 | @item @code{GL_ORDER} | |
8899 | @var{v} returns the order of the evaluator function. One-dimensional | |
8900 | evaluators return a single value, @r{@var{order}}. The initial value is | |
8901 | 1. Two-dimensional evaluators return two values, @r{@var{uorder}} and | |
8902 | @r{@var{vorder}}. The initial value is 1,1. | |
8903 | ||
8904 | @item @code{GL_DOMAIN} | |
8905 | @var{v} returns the linear @r{@var{u}} and @r{@var{v}} mapping | |
8906 | parameters. One-dimensional evaluators return two values, @r{@var{u1}} | |
8907 | and @r{@var{u2}}, as specified by @code{glMap1}. Two-dimensional | |
8908 | evaluators return four values (@r{@var{u1}}, @r{@var{u2}}, @r{@var{v1}}, | |
8909 | and @r{@var{v2}}) as specified by @code{glMap2}. Integer values, when | |
8910 | requested, are computed by rounding the internal floating-point values | |
8911 | to the nearest integer values. | |
8912 | ||
8913 | @end table | |
8914 | ||
8915 | @code{GL_INVALID_ENUM} is generated if either @var{target} or | |
8916 | @var{query} is not an accepted value. | |
8917 | ||
8918 | @code{GL_INVALID_OPERATION} is generated if @code{glGetMap} is executed | |
8919 | between the execution of @code{glBegin} and the corresponding execution | |
8920 | of @code{glEnd}. | |
8921 | ||
8922 | @end deftypefun | |
8923 | ||
8924 | @deftypefun void glGetMaterialfv face pname params | |
8925 | @deftypefunx void glGetMaterialiv face pname params | |
8926 | Return material parameters. | |
8927 | ||
8928 | @table @asis | |
8929 | @item @var{face} | |
8930 | Specifies which of the two materials is being queried. @code{GL_FRONT} | |
8931 | or @code{GL_BACK} are accepted, representing the front and back | |
8932 | materials, respectively. | |
8933 | ||
8934 | @item @var{pname} | |
8935 | Specifies the material parameter to return. @code{GL_AMBIENT}, | |
8936 | @code{GL_DIFFUSE}, @code{GL_SPECULAR}, @code{GL_EMISSION}, | |
8937 | @code{GL_SHININESS}, and @code{GL_COLOR_INDEXES} are accepted. | |
8938 | ||
8939 | @item @var{params} | |
8940 | Returns the requested data. | |
8941 | ||
8942 | @end table | |
8943 | ||
8944 | @code{glGetMaterial} returns in @var{params} the value or values of | |
8945 | parameter @var{pname} of material @var{face}. Six parameters are | |
8946 | defined: | |
8947 | ||
8948 | @table @asis | |
8949 | @item @code{GL_AMBIENT} | |
8950 | @var{params} returns four integer or floating-point values representing | |
8951 | the ambient reflectance of the material. Integer values, when requested, | |
8952 | are linearly mapped from the internal floating-point representation such | |
8953 | that 1.0 maps to the most positive representable integer value, and | |
8954 | @r{-1.0} maps to the most negative representable integer value. If the | |
8955 | internal value is outside the range @r{[-1,1]}, the corresponding | |
8956 | integer return value is undefined. The initial value is (0.2, 0.2, 0.2, | |
8957 | 1.0) | |
8958 | ||
8959 | @item @code{GL_DIFFUSE} | |
8960 | @var{params} returns four integer or floating-point values representing | |
8961 | the diffuse reflectance of the material. Integer values, when requested, | |
8962 | are linearly mapped from the internal floating-point representation such | |
8963 | that 1.0 maps to the most positive representable integer value, and | |
8964 | @r{-1.0} maps to the most negative representable integer value. If the | |
8965 | internal value is outside the range @r{[-1,1]}, the corresponding | |
8966 | integer return value is undefined. The initial value is (0.8, 0.8, 0.8, | |
8967 | 1.0). | |
8968 | ||
8969 | @item @code{GL_SPECULAR} | |
8970 | @var{params} returns four integer or floating-point values representing | |
8971 | the specular reflectance of the material. Integer values, when | |
8972 | requested, are linearly mapped from the internal floating-point | |
8973 | representation such that 1.0 maps to the most positive representable | |
8974 | integer value, and @r{-1.0} maps to the most negative representable | |
8975 | integer value. If the internal value is outside the range @r{[-1,1]}, | |
8976 | the corresponding integer return value is undefined. The initial value | |
8977 | is (0, 0, 0, 1). | |
8978 | ||
8979 | @item @code{GL_EMISSION} | |
8980 | @var{params} returns four integer or floating-point values representing | |
8981 | the emitted light intensity of the material. Integer values, when | |
8982 | requested, are linearly mapped from the internal floating-point | |
8983 | representation such that 1.0 maps to the most positive representable | |
8984 | integer value, and @r{-1.0} maps to the most negative representable | |
8985 | integer value. If the internal value is outside the range @r{[-1,1]}, | |
8986 | the corresponding integer return value is undefined. The initial value | |
8987 | is (0, 0, 0, 1). | |
8988 | ||
8989 | @item @code{GL_SHININESS} | |
8990 | @var{params} returns one integer or floating-point value representing | |
8991 | the specular exponent of the material. Integer values, when requested, | |
8992 | are computed by rounding the internal floating-point value to the | |
8993 | nearest integer value. The initial value is 0. | |
8994 | ||
8995 | @item @code{GL_COLOR_INDEXES} | |
8996 | @var{params} returns three integer or floating-point values representing | |
8997 | the ambient, diffuse, and specular indices of the material. These | |
8998 | indices are used only for color index lighting. (All the other | |
8999 | parameters are used only for RGBA lighting.) Integer values, when | |
9000 | requested, are computed by rounding the internal floating-point values | |
9001 | to the nearest integer values. | |
9002 | ||
9003 | @end table | |
9004 | ||
9005 | @code{GL_INVALID_ENUM} is generated if @var{face} or @var{pname} is not | |
9006 | an accepted value. | |
9007 | ||
9008 | @code{GL_INVALID_OPERATION} is generated if @code{glGetMaterial} is | |
9009 | executed between the execution of @code{glBegin} and the corresponding | |
9010 | execution of @code{glEnd}. | |
9011 | ||
9012 | @end deftypefun | |
9013 | ||
9014 | @deftypefun void glGetMinmaxParameterfv target pname params | |
9015 | @deftypefunx void glGetMinmaxParameteriv target pname params | |
9016 | Get minmax parameters. | |
9017 | ||
9018 | @table @asis | |
9019 | @item @var{target} | |
9020 | Must be @code{GL_MINMAX}. | |
9021 | ||
9022 | @item @var{pname} | |
9023 | The parameter to be retrieved. Must be one of @code{GL_MINMAX_FORMAT} or | |
9024 | @code{GL_MINMAX_SINK}. | |
9025 | ||
9026 | @item @var{params} | |
9027 | A pointer to storage for the retrieved parameters. | |
9028 | ||
9029 | @end table | |
9030 | ||
9031 | @code{glGetMinmaxParameter} retrieves parameters for the current minmax | |
9032 | table by setting @var{pname} to one of the following values: | |
9033 | ||
9034 | ||
9035 | ||
9036 | @table @asis | |
9037 | @item @strong{Parameter} | |
9038 | @strong{Description} | |
9039 | ||
9040 | @item @code{GL_MINMAX_FORMAT} | |
9041 | Internal format of minmax table | |
9042 | ||
9043 | @item @code{GL_MINMAX_SINK} | |
9044 | Value of the @var{sink} parameter | |
9045 | ||
9046 | @end table | |
9047 | ||
9048 | ||
9049 | ||
9050 | @code{GL_INVALID_ENUM} is generated if @var{target} is not | |
9051 | @code{GL_MINMAX}. | |
9052 | ||
9053 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the | |
9054 | allowable values. | |
9055 | ||
9056 | @code{GL_INVALID_OPERATION} is generated if @code{glGetMinmaxParameter} | |
9057 | is executed between the execution of @code{glBegin} and the | |
9058 | corresponding execution of @code{glEnd}. | |
9059 | ||
9060 | @end deftypefun | |
9061 | ||
9062 | @deftypefun void glGetMinmax target reset format types values | |
9063 | Get minimum and maximum pixel values. | |
9064 | ||
9065 | @table @asis | |
9066 | @item @var{target} | |
9067 | Must be @code{GL_MINMAX}. | |
9068 | ||
9069 | @item @var{reset} | |
9070 | If @code{GL_TRUE}, all entries in the minmax table that are actually | |
9071 | returned are reset to their initial values. (Other entries are | |
9072 | unaltered.) If @code{GL_FALSE}, the minmax table is unaltered. | |
9073 | ||
9074 | @item @var{format} | |
9075 | The format of the data to be returned in @var{values}. Must be one of | |
9076 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, | |
9077 | @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, | |
9078 | @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}. | |
9079 | ||
9080 | @item @var{types} | |
9081 | The type of the data to be returned in @var{values}. Symbolic constants | |
9082 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
9083 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
9084 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
9085 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
9086 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
9087 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
9088 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
9089 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
9090 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
9091 | ||
9092 | @item @var{values} | |
9093 | A pointer to storage for the returned values. | |
9094 | ||
9095 | @end table | |
9096 | ||
9097 | @code{glGetMinmax} returns the accumulated minimum and maximum pixel | |
9098 | values (computed on a per-component basis) in a one-dimensional image of | |
9099 | width 2. The first set of return values are the minima, and the second | |
9100 | set of return values are the maxima. The format of the return values is | |
bb894c9d | 9101 | determined by @var{format}, and their type is determined by @var{types}. |
8925f36f AW |
9102 | |
9103 | If a non-zero named buffer object is bound to the | |
9104 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while | |
9105 | minimum and maximum pixel values are requested, @var{values} is treated | |
9106 | as a byte offset into the buffer object's data store. | |
9107 | ||
9108 | No pixel transfer operations are performed on the return values, but | |
9109 | pixel storage modes that are applicable to one-dimensional images are | |
9110 | performed. Color components that are requested in the specified | |
9111 | @var{format}, but that are not included in the internal format of the | |
9112 | minmax table, are returned as zero. The assignment of internal color | |
9113 | components to the components requested by @var{format} are as follows: | |
9114 | ||
9115 | ||
9116 | ||
9117 | @table @asis | |
9118 | @item @strong{Internal Component} | |
9119 | @strong{Resulting Component} | |
9120 | ||
9121 | @item | |
9122 | Red | |
9123 | Red | |
9124 | ||
9125 | @item | |
9126 | Green | |
9127 | Green | |
9128 | ||
9129 | @item | |
9130 | Blue | |
9131 | Blue | |
9132 | ||
9133 | @item | |
9134 | Alpha | |
9135 | Alpha | |
9136 | ||
9137 | @item | |
9138 | Luminance | |
9139 | Red | |
9140 | ||
9141 | @end table | |
9142 | ||
9143 | If @var{reset} is @code{GL_TRUE}, the minmax table entries corresponding | |
9144 | to the return values are reset to their initial values. Minimum and | |
9145 | maximum values that are not returned are not modified, even if | |
9146 | @var{reset} is @code{GL_TRUE}. | |
9147 | ||
8925f36f AW |
9148 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
9149 | @code{GL_MINMAX}. | |
9150 | ||
9151 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
9152 | allowable values. | |
9153 | ||
9154 | @code{GL_INVALID_ENUM} is generated if @var{types} is not one of the | |
9155 | allowable values. | |
9156 | ||
9157 | @code{GL_INVALID_OPERATION} is generated if @var{types} is one of | |
9158 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
9159 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
9160 | and @var{format} is not @code{GL_RGB}. | |
9161 | ||
9162 | @code{GL_INVALID_OPERATION} is generated if @var{types} is one of | |
9163 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
9164 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
9165 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
9166 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
9167 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
9168 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
9169 | ||
9170 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9171 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
9172 | object's data store is currently mapped. | |
9173 | ||
9174 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9175 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
9176 | would be packed to the buffer object such that the memory writes | |
9177 | required would exceed the data store size. | |
9178 | ||
9179 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9180 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{values} | |
9181 | is not evenly divisible into the number of bytes needed to store in | |
9182 | memory a datum indicated by @var{type}. | |
9183 | ||
9184 | @code{GL_INVALID_OPERATION} is generated if @code{glGetMinmax} is | |
9185 | executed between the execution of @code{glBegin} and the corresponding | |
9186 | execution of @code{glEnd}. | |
9187 | ||
bb894c9d | 9188 | @end deftypefun |
8925f36f | 9189 | |
b002944d AW |
9190 | @deftypefun void glGetPixelMapfv map data |
9191 | @deftypefunx void glGetPixelMapuiv map data | |
9192 | Return the specified pixel map. | |
9193 | ||
9194 | @table @asis | |
9195 | @item @var{map} | |
9196 | Specifies the name of the pixel map to return. Accepted values are | |
9197 | @code{GL_PIXEL_MAP_I_TO_I}, @code{GL_PIXEL_MAP_S_TO_S}, | |
9198 | @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G}, | |
9199 | @code{GL_PIXEL_MAP_I_TO_B}, @code{GL_PIXEL_MAP_I_TO_A}, | |
9200 | @code{GL_PIXEL_MAP_R_TO_R}, @code{GL_PIXEL_MAP_G_TO_G}, | |
9201 | @code{GL_PIXEL_MAP_B_TO_B}, and @code{GL_PIXEL_MAP_A_TO_A}. | |
9202 | ||
9203 | @item @var{data} | |
9204 | Returns the pixel map contents. | |
9205 | ||
9206 | @end table | |
9207 | ||
9208 | See the @code{glPixelMap} reference page for a description of the | |
9209 | acceptable values for the @var{map} parameter. @code{glGetPixelMap} | |
9210 | returns in @var{data} the contents of the pixel map specified in | |
9211 | @var{map}. Pixel maps are used during the execution of | |
9212 | @code{glReadPixels}, @code{glDrawPixels}, @code{glCopyPixels}, | |
9213 | @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D}, | |
9214 | @code{glTexSubImage1D}, @code{glTexSubImage2D}, @code{glTexSubImage3D}, | |
9215 | @code{glCopyTexImage1D}, @code{glCopyTexImage2D}, | |
9216 | @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D}, and | |
9217 | @code{glCopyTexSubImage3D}. to map color indices, stencil indices, color | |
9218 | components, and depth components to other values. | |
9219 | ||
9220 | If a non-zero named buffer object is bound to the | |
9221 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
9222 | pixel map is requested, @var{data} is treated as a byte offset into the | |
9223 | buffer object's data store. | |
9224 | ||
9225 | Unsigned integer values, if requested, are linearly mapped from the | |
9226 | internal fixed or floating-point representation such that 1.0 maps to | |
9227 | the largest representable integer value, and 0.0 maps to 0. Return | |
9228 | unsigned integer values are undefined if the map value was not in the | |
9229 | range [0,1]. | |
9230 | ||
9231 | To determine the required size of @var{map}, call @code{glGet} with the | |
9232 | appropriate symbolic constant. | |
9233 | ||
9234 | @code{GL_INVALID_ENUM} is generated if @var{map} is not an accepted | |
9235 | value. | |
9236 | ||
9237 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9238 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
9239 | object's data store is currently mapped. | |
9240 | ||
9241 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9242 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
9243 | would be packed to the buffer object such that the memory writes | |
9244 | required would exceed the data store size. | |
9245 | ||
9246 | @code{GL_INVALID_OPERATION} is generated by @code{glGetPixelMapfv} if a | |
9247 | non-zero buffer object name is bound to the @code{GL_PIXEL_PACK_BUFFER} | |
9248 | target and @var{data} is not evenly divisible into the number of bytes | |
9249 | needed to store in memory a GLfloat datum. | |
9250 | ||
9251 | @code{GL_INVALID_OPERATION} is generated by @code{glGetPixelMapuiv} if a | |
9252 | non-zero buffer object name is bound to the @code{GL_PIXEL_PACK_BUFFER} | |
9253 | target and @var{data} is not evenly divisible into the number of bytes | |
9254 | needed to store in memory a GLuint datum. | |
9255 | ||
9256 | @code{GL_INVALID_OPERATION} is generated by @code{glGetPixelMapusv} if a | |
9257 | non-zero buffer object name is bound to the @code{GL_PIXEL_PACK_BUFFER} | |
9258 | target and @var{data} is not evenly divisible into the number of bytes | |
9259 | needed to store in memory a GLushort datum. | |
9260 | ||
9261 | @code{GL_INVALID_OPERATION} is generated if @code{glGetPixelMap} is | |
9262 | executed between the execution of @code{glBegin} and the corresponding | |
9263 | execution of @code{glEnd}. | |
9264 | ||
9265 | @end deftypefun | |
9266 | ||
9267 | @deftypefun void glGetPointerv pname params | |
9268 | Return the address of the specified pointer. | |
9269 | ||
9270 | @table @asis | |
9271 | @item @var{pname} | |
9272 | Specifies the array or buffer pointer to be returned. Symbolic constants | |
9273 | @code{GL_COLOR_ARRAY_POINTER}, @code{GL_EDGE_FLAG_ARRAY_POINTER}, | |
9274 | @code{GL_FOG_COORD_ARRAY_POINTER}, @code{GL_FEEDBACK_BUFFER_POINTER}, | |
9275 | @code{GL_INDEX_ARRAY_POINTER}, @code{GL_NORMAL_ARRAY_POINTER}, | |
9276 | @code{GL_SECONDARY_COLOR_ARRAY_POINTER}, | |
9277 | @code{GL_SELECTION_BUFFER_POINTER}, | |
9278 | @code{GL_TEXTURE_COORD_ARRAY_POINTER}, or @code{GL_VERTEX_ARRAY_POINTER} | |
9279 | are accepted. | |
9280 | ||
9281 | @item @var{params} | |
9282 | Returns the pointer value specified by @var{pname}. | |
9283 | ||
9284 | @end table | |
9285 | ||
9286 | @code{glGetPointerv} returns pointer information. @var{pname} is a | |
9287 | symbolic constant indicating the pointer to be returned, and | |
9288 | @var{params} is a pointer to a location in which to place the returned | |
9289 | data. | |
9290 | ||
9291 | For all @var{pname} arguments except @code{GL_FEEDBACK_BUFFER_POINTER} | |
9292 | and @code{GL_SELECTION_BUFFER_POINTER}, if a non-zero named buffer | |
9293 | object was bound to the @code{GL_ARRAY_BUFFER} target (see | |
9294 | @code{glBindBuffer}) when the desired pointer was previously specified, | |
9295 | the pointer returned is a byte offset into the buffer object's data | |
9296 | store. Buffer objects are only available in OpenGL versions 1.5 and | |
9297 | greater. | |
9298 | ||
9299 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted | |
9300 | value. | |
9301 | ||
9302 | @end deftypefun | |
9303 | ||
bb894c9d | 9304 | @deftypefun void glGetPolygonStipple pattern |
3c9b6116 AW |
9305 | Return the polygon stipple pattern. |
9306 | ||
8925f36f AW |
9307 | @table @asis |
9308 | @item @var{pattern} | |
9309 | Returns the stipple pattern. The initial value is all 1's. | |
9310 | ||
9311 | @end table | |
9312 | ||
3c9b6116 AW |
9313 | @code{glGetPolygonStipple} returns to @var{pattern} a @r{32×32} polygon |
9314 | stipple pattern. The pattern is packed into memory as if | |
8925f36f AW |
9315 | @code{glReadPixels} with both @var{height} and @var{width} of 32, |
9316 | @var{type} of @code{GL_BITMAP}, and @var{format} of | |
9317 | @code{GL_COLOR_INDEX} were called, and the stipple pattern were stored | |
3c9b6116 AW |
9318 | in an internal @r{32×32} color index buffer. Unlike @code{glReadPixels}, |
9319 | however, pixel transfer operations (shift, offset, pixel map) are not | |
9320 | applied to the returned stipple image. | |
8925f36f AW |
9321 | |
9322 | If a non-zero named buffer object is bound to the | |
9323 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
9324 | polygon stipple pattern is requested, @var{pattern} is treated as a byte | |
9325 | offset into the buffer object's data store. | |
9326 | ||
8925f36f AW |
9327 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object |
9328 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
9329 | object's data store is currently mapped. | |
9330 | ||
9331 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9332 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
9333 | would be packed to the buffer object such that the memory writes | |
9334 | required would exceed the data store size. | |
9335 | ||
9336 | @code{GL_INVALID_OPERATION} is generated if @code{glGetPolygonStipple} | |
9337 | is executed between the execution of @code{glBegin} and the | |
9338 | corresponding execution of @code{glEnd}. | |
9339 | ||
bb894c9d | 9340 | @end deftypefun |
8925f36f | 9341 | |
bb894c9d | 9342 | @deftypefun void glGetProgramInfoLog program maxLength length infoLog |
3c9b6116 AW |
9343 | Returns the information log for a program object. |
9344 | ||
8925f36f AW |
9345 | @table @asis |
9346 | @item @var{program} | |
9347 | Specifies the program object whose information log is to be queried. | |
9348 | ||
9349 | @item @var{maxLength} | |
9350 | Specifies the size of the character buffer for storing the returned | |
9351 | information log. | |
9352 | ||
9353 | @item @var{length} | |
9354 | Returns the length of the string returned in @var{infoLog} (excluding | |
9355 | the null terminator). | |
9356 | ||
9357 | @item @var{infoLog} | |
9358 | Specifies an array of characters that is used to return the information | |
9359 | log. | |
9360 | ||
9361 | @end table | |
9362 | ||
8925f36f AW |
9363 | @code{glGetProgramInfoLog} returns the information log for the specified |
9364 | program object. The information log for a program object is modified | |
9365 | when the program object is linked or validated. The string that is | |
9366 | returned will be null terminated. | |
9367 | ||
9368 | @code{glGetProgramInfoLog} returns in @var{infoLog} as much of the | |
9369 | information log as it can, up to a maximum of @var{maxLength} | |
9370 | characters. The number of characters actually returned, excluding the | |
9371 | null termination character, is specified by @var{length}. If the length | |
9372 | of the returned string is not required, a value of @code{NULL} can be | |
9373 | passed in the @var{length} argument. The size of the buffer required to | |
9374 | store the returned information log can be obtained by calling | |
9375 | @code{glGetProgram} with the value @code{GL_INFO_LOG_LENGTH}. | |
9376 | ||
9377 | The information log for a program object is either an empty string, or a | |
9378 | string containing information about the last link operation, or a string | |
9379 | containing information about the last validation operation. It may | |
9380 | contain diagnostic messages, warning messages, and other information. | |
9381 | When a program object is created, its information log will be a string | |
9382 | of length 0. | |
9383 | ||
8925f36f AW |
9384 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
9385 | generated by OpenGL. | |
9386 | ||
9387 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
9388 | program object. | |
9389 | ||
9390 | @code{GL_INVALID_VALUE} is generated if @var{maxLength} is less than 0. | |
9391 | ||
9392 | @code{GL_INVALID_OPERATION} is generated if @code{glGetProgramInfoLog} | |
9393 | is executed between the execution of @code{glBegin} and the | |
9394 | corresponding execution of @code{glEnd}. | |
9395 | ||
bb894c9d | 9396 | @end deftypefun |
8925f36f | 9397 | |
b002944d AW |
9398 | @deftypefun void glGetProgramiv program pname params |
9399 | Returns a parameter from a program object. | |
3c9b6116 | 9400 | |
8925f36f | 9401 | @table @asis |
b002944d AW |
9402 | @item @var{program} |
9403 | Specifies the program object to be queried. | |
8925f36f | 9404 | |
b002944d AW |
9405 | @item @var{pname} |
9406 | Specifies the object parameter. Accepted symbolic names are | |
9407 | @code{GL_DELETE_STATUS}, @code{GL_LINK_STATUS}, | |
9408 | @code{GL_VALIDATE_STATUS}, @code{GL_INFO_LOG_LENGTH}, | |
9409 | @code{GL_ATTACHED_SHADERS}, @code{GL_ACTIVE_ATTRIBUTES}, | |
9410 | @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH}, @code{GL_ACTIVE_UNIFORMS}, | |
9411 | @code{GL_ACTIVE_UNIFORM_MAX_LENGTH}. | |
8925f36f | 9412 | |
b002944d AW |
9413 | @item @var{params} |
9414 | Returns the requested object parameter. | |
8925f36f | 9415 | |
b002944d | 9416 | @end table |
8925f36f | 9417 | |
b002944d AW |
9418 | @code{glGetProgram} returns in @var{params} the value of a parameter for |
9419 | a specific program object. The following parameters are defined: | |
8925f36f | 9420 | |
b002944d AW |
9421 | @table @asis |
9422 | @item @code{GL_DELETE_STATUS} | |
8925f36f | 9423 | |
8925f36f | 9424 | |
b002944d AW |
9425 | @var{params} returns @code{GL_TRUE} if @var{program} is currently |
9426 | flagged for deletion, and @code{GL_FALSE} otherwise. | |
9427 | ||
9428 | @item @code{GL_LINK_STATUS} | |
9429 | ||
9430 | ||
9431 | @var{params} returns @code{GL_TRUE} if the last link operation on | |
9432 | @var{program} was successful, and @code{GL_FALSE} otherwise. | |
9433 | ||
9434 | @item @code{GL_VALIDATE_STATUS} | |
9435 | ||
9436 | ||
9437 | @var{params} returns @code{GL_TRUE} or if the last validation operation | |
9438 | on @var{program} was successful, and @code{GL_FALSE} otherwise. | |
9439 | ||
9440 | @item @code{GL_INFO_LOG_LENGTH} | |
9441 | ||
9442 | ||
9443 | @var{params} returns the number of characters in the information log for | |
9444 | @var{program} including the null termination character (i.e., the size | |
9445 | of the character buffer required to store the information log). If | |
9446 | @var{program} has no information log, a value of 0 is returned. | |
9447 | ||
9448 | @item @code{GL_ATTACHED_SHADERS} | |
9449 | ||
9450 | ||
9451 | @var{params} returns the number of shader objects attached to | |
9452 | @var{program}. | |
9453 | ||
9454 | @item @code{GL_ACTIVE_ATTRIBUTES} | |
9455 | ||
9456 | ||
9457 | @var{params} returns the number of active attribute variables for | |
9458 | @var{program}. | |
9459 | ||
9460 | @item @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH} | |
9461 | ||
9462 | ||
9463 | @var{params} returns the length of the longest active attribute name for | |
9464 | @var{program}, including the null termination character (i.e., the size | |
9465 | of the character buffer required to store the longest attribute name). | |
9466 | If no active attributes exist, 0 is returned. | |
9467 | ||
9468 | @item @code{GL_ACTIVE_UNIFORMS} | |
9469 | ||
9470 | ||
9471 | @var{params} returns the number of active uniform variables for | |
9472 | @var{program}. | |
9473 | ||
9474 | @item @code{GL_ACTIVE_UNIFORM_MAX_LENGTH} | |
9475 | ||
9476 | ||
9477 | @var{params} returns the length of the longest active uniform variable | |
9478 | name for @var{program}, including the null termination character (i.e., | |
9479 | the size of the character buffer required to store the longest uniform | |
9480 | variable name). If no active uniform variables exist, 0 is returned. | |
9481 | ||
9482 | @end table | |
9483 | ||
9484 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value | |
9485 | generated by OpenGL. | |
9486 | ||
9487 | @code{GL_INVALID_OPERATION} is generated if @var{program} does not refer | |
9488 | to a program object. | |
9489 | ||
9490 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted | |
9491 | value. | |
9492 | ||
9493 | @code{GL_INVALID_OPERATION} is generated if @code{glGetProgram} is | |
9494 | executed between the execution of @code{glBegin} and the corresponding | |
9495 | execution of @code{glEnd}. | |
9496 | ||
9497 | @end deftypefun | |
9498 | ||
9499 | @deftypefun void glGetQueryiv target pname params | |
9500 | Return parameters of a query object target. | |
9501 | ||
9502 | @table @asis | |
9503 | @item @var{target} | |
9504 | Specifies a query object target. Must be @code{GL_SAMPLES_PASSED}. | |
9505 | ||
9506 | @item @var{pname} | |
9507 | Specifies the symbolic name of a query object target parameter. Accepted | |
9508 | values are @code{GL_CURRENT_QUERY} or @code{GL_QUERY_COUNTER_BITS}. | |
9509 | ||
9510 | @item @var{params} | |
9511 | Returns the requested data. | |
9512 | ||
9513 | @end table | |
9514 | ||
9515 | @code{glGetQueryiv} returns in @var{params} a selected parameter of the | |
9516 | query object target specified by @var{target}. | |
9517 | ||
9518 | @var{pname} names a specific query object target parameter. When | |
9519 | @var{target} is @code{GL_SAMPLES_PASSED}, @var{pname} can be as follows: | |
9520 | ||
9521 | @table @asis | |
9522 | @item @code{GL_CURRENT_QUERY} | |
9523 | @var{params} returns the name of the currently active occlusion query | |
9524 | object. If no occlusion query is active, 0 is returned. The initial | |
9525 | value is 0. | |
9526 | ||
9527 | @item @code{GL_QUERY_COUNTER_BITS} | |
9528 | @var{params} returns the number of bits in the query counter used to | |
9529 | accumulate passing samples. If the number of bits returned is 0, the | |
9530 | implementation does not support a query counter, and the results | |
9531 | obtained from @code{glGetQueryObject} are useless. | |
9532 | ||
9533 | @end table | |
9534 | ||
9535 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
9536 | not an accepted value. | |
9537 | ||
9538 | @code{GL_INVALID_OPERATION} is generated if @code{glGetQueryiv} is | |
9539 | executed between the execution of @code{glBegin} and the corresponding | |
9540 | execution of @code{glEnd}. | |
9541 | ||
9542 | @end deftypefun | |
9543 | ||
9544 | @deftypefun void glGetQueryObjectiv id pname params | |
9545 | @deftypefunx void glGetQueryObjectuiv id pname params | |
9546 | Return parameters of a query object. | |
9547 | ||
9548 | @table @asis | |
9549 | @item @var{id} | |
9550 | Specifies the name of a query object. | |
9551 | ||
9552 | @item @var{pname} | |
9553 | Specifies the symbolic name of a query object parameter. Accepted values | |
9554 | are @code{GL_QUERY_RESULT} or @code{GL_QUERY_RESULT_AVAILABLE}. | |
9555 | ||
9556 | @item @var{params} | |
9557 | Returns the requested data. | |
9558 | ||
9559 | @end table | |
9560 | ||
9561 | @code{glGetQueryObject} returns in @var{params} a selected parameter of | |
9562 | the query object specified by @var{id}. | |
9563 | ||
9564 | @var{pname} names a specific query object parameter. @var{pname} can be | |
9565 | as follows: | |
9566 | ||
9567 | @table @asis | |
9568 | @item @code{GL_QUERY_RESULT} | |
9569 | @var{params} returns the value of the query object's passed samples | |
9570 | counter. The initial value is 0. | |
9571 | ||
9572 | @item @code{GL_QUERY_RESULT_AVAILABLE} | |
9573 | @var{params} returns whether the passed samples counter is immediately | |
9574 | available. If a delay would occur waiting for the query result, | |
9575 | @code{GL_FALSE} is returned. Otherwise, @code{GL_TRUE} is returned, | |
9576 | which also indicates that the results of all previous queries are | |
9577 | available as well. | |
9578 | ||
9579 | @end table | |
9580 | ||
9581 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted | |
9582 | value. | |
9583 | ||
9584 | @code{GL_INVALID_OPERATION} is generated if @var{id} is not the name of | |
9585 | a query object. | |
9586 | ||
9587 | @code{GL_INVALID_OPERATION} is generated if @var{id} is the name of a | |
9588 | currently active query object. | |
9589 | ||
9590 | @code{GL_INVALID_OPERATION} is generated if @code{glGetQueryObject} is | |
9591 | executed between the execution of @code{glBegin} and the corresponding | |
9592 | execution of @code{glEnd}. | |
9593 | ||
9594 | @end deftypefun | |
9595 | ||
9596 | @deftypefun void glGetSeparableFilter target format type row column span | |
9597 | Get separable convolution filter kernel images. | |
9598 | ||
9599 | @table @asis | |
9600 | @item @var{target} | |
9601 | The separable filter to be retrieved. Must be @code{GL_SEPARABLE_2D}. | |
9602 | ||
9603 | @item @var{format} | |
9604 | Format of the output images. Must be one of @code{GL_RED}, | |
9605 | @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, | |
9606 | @code{GL_BGR}@code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, or | |
9607 | @code{GL_LUMINANCE_ALPHA}. | |
9608 | ||
9609 | @item @var{type} | |
9610 | Data type of components in the output images. Symbolic constants | |
9611 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
9612 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
9613 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
9614 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
9615 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
9616 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
9617 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
9618 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
9619 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
9620 | ||
9621 | @item @var{row} | |
9622 | Pointer to storage for the row filter image. | |
9623 | ||
9624 | @item @var{column} | |
9625 | Pointer to storage for the column filter image. | |
9626 | ||
9627 | @item @var{span} | |
9628 | Pointer to storage for the span filter image (currently unused). | |
9629 | ||
9630 | @end table | |
9631 | ||
9632 | @code{glGetSeparableFilter} returns the two one-dimensional filter | |
9633 | kernel images for the current separable 2D convolution filter. The row | |
9634 | image is placed in @var{row} and the column image is placed in | |
9635 | @var{column} according to the specifications in @var{format} and | |
9636 | @var{type}. (In the current implementation, @var{span} is not affected | |
9637 | in any way.) No pixel transfer operations are performed on the images, | |
9638 | but the relevant pixel storage modes are applied. | |
8925f36f | 9639 | |
bb894c9d AW |
9640 | If a non-zero named buffer object is bound to the |
9641 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
9642 | separable convolution filter is requested, @var{row}, @var{column}, and | |
9643 | @var{span} are treated as a byte offset into the buffer object's data | |
9644 | store. | |
8925f36f | 9645 | |
bb894c9d AW |
9646 | Color components that are present in @var{format} but not included in |
9647 | the internal format of the filters are returned as zero. The assignments | |
9648 | of internal color components to the components of @var{format} are as | |
9649 | follows: | |
8925f36f | 9650 | |
8925f36f AW |
9651 | |
9652 | ||
bb894c9d AW |
9653 | @table @asis |
9654 | @item @strong{Internal Component} | |
9655 | @strong{Resulting Component} | |
8925f36f AW |
9656 | |
9657 | @item | |
9658 | Red | |
9659 | Red | |
9660 | ||
9661 | @item | |
9662 | Green | |
9663 | Green | |
9664 | ||
9665 | @item | |
9666 | Blue | |
9667 | Blue | |
9668 | ||
9669 | @item | |
9670 | Alpha | |
9671 | Alpha | |
9672 | ||
9673 | @item | |
9674 | Luminance | |
9675 | Red | |
9676 | ||
9677 | @item | |
9678 | Intensity | |
9679 | Red | |
9680 | ||
9681 | @end table | |
9682 | ||
9683 | ||
9684 | ||
8925f36f AW |
9685 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
9686 | @code{GL_SEPARABLE_2D}. | |
9687 | ||
9688 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
9689 | allowable values. | |
9690 | ||
9691 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
9692 | allowable values. | |
9693 | ||
9694 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
9695 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
9696 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
9697 | and @var{format} is not @code{GL_RGB}. | |
9698 | ||
9699 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
9700 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
9701 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
9702 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
9703 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
9704 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
9705 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
9706 | ||
9707 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9708 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
9709 | object's data store is currently mapped. | |
9710 | ||
9711 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9712 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
9713 | would be packed to the buffer object such that the memory writes | |
9714 | required would exceed the data store size. | |
9715 | ||
9716 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9717 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{row} or | |
9718 | @var{column} is not evenly divisible into the number of bytes needed to | |
9719 | store in memory a datum indicated by @var{type}. | |
9720 | ||
9721 | @code{GL_INVALID_OPERATION} is generated if @code{glGetSeparableFilter} | |
9722 | is executed between the execution of @code{glBegin} and the | |
9723 | corresponding execution of @code{glEnd}. | |
9724 | ||
bb894c9d | 9725 | @end deftypefun |
8925f36f | 9726 | |
bb894c9d | 9727 | @deftypefun void glGetShaderInfoLog shader maxLength length infoLog |
3c9b6116 AW |
9728 | Returns the information log for a shader object. |
9729 | ||
8925f36f AW |
9730 | @table @asis |
9731 | @item @var{shader} | |
9732 | Specifies the shader object whose information log is to be queried. | |
9733 | ||
9734 | @item @var{maxLength} | |
9735 | Specifies the size of the character buffer for storing the returned | |
9736 | information log. | |
9737 | ||
9738 | @item @var{length} | |
9739 | Returns the length of the string returned in @var{infoLog} (excluding | |
9740 | the null terminator). | |
9741 | ||
9742 | @item @var{infoLog} | |
9743 | Specifies an array of characters that is used to return the information | |
9744 | log. | |
9745 | ||
9746 | @end table | |
9747 | ||
8925f36f AW |
9748 | @code{glGetShaderInfoLog} returns the information log for the specified |
9749 | shader object. The information log for a shader object is modified when | |
9750 | the shader is compiled. The string that is returned will be null | |
9751 | terminated. | |
9752 | ||
9753 | @code{glGetShaderInfoLog} returns in @var{infoLog} as much of the | |
9754 | information log as it can, up to a maximum of @var{maxLength} | |
9755 | characters. The number of characters actually returned, excluding the | |
9756 | null termination character, is specified by @var{length}. If the length | |
9757 | of the returned string is not required, a value of @code{NULL} can be | |
9758 | passed in the @var{length} argument. The size of the buffer required to | |
9759 | store the returned information log can be obtained by calling | |
9760 | @code{glGetShader} with the value @code{GL_INFO_LOG_LENGTH}. | |
9761 | ||
9762 | The information log for a shader object is a string that may contain | |
9763 | diagnostic messages, warning messages, and other information about the | |
9764 | last compile operation. When a shader object is created, its information | |
9765 | log will be a string of length 0. | |
9766 | ||
8925f36f AW |
9767 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
9768 | generated by OpenGL. | |
9769 | ||
9770 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
9771 | object. | |
9772 | ||
9773 | @code{GL_INVALID_VALUE} is generated if @var{maxLength} is less than 0. | |
9774 | ||
9775 | @code{GL_INVALID_OPERATION} is generated if @code{glGetShaderInfoLog} is | |
9776 | executed between the execution of @code{glBegin} and the corresponding | |
9777 | execution of @code{glEnd}. | |
9778 | ||
bb894c9d | 9779 | @end deftypefun |
8925f36f | 9780 | |
bb894c9d | 9781 | @deftypefun void glGetShaderSource shader bufSize length source |
3c9b6116 AW |
9782 | Returns the source code string from a shader object. |
9783 | ||
8925f36f AW |
9784 | @table @asis |
9785 | @item @var{shader} | |
9786 | Specifies the shader object to be queried. | |
9787 | ||
9788 | @item @var{bufSize} | |
9789 | Specifies the size of the character buffer for storing the returned | |
9790 | source code string. | |
9791 | ||
9792 | @item @var{length} | |
9793 | Returns the length of the string returned in @var{source} (excluding the | |
9794 | null terminator). | |
9795 | ||
9796 | @item @var{source} | |
9797 | Specifies an array of characters that is used to return the source code | |
9798 | string. | |
9799 | ||
9800 | @end table | |
9801 | ||
8925f36f AW |
9802 | @code{glGetShaderSource} returns the concatenation of the source code |
9803 | strings from the shader object specified by @var{shader}. The source | |
9804 | code strings for a shader object are the result of a previous call to | |
9805 | @code{glShaderSource}. The string returned by the function will be null | |
9806 | terminated. | |
9807 | ||
9808 | @code{glGetShaderSource} returns in @var{source} as much of the source | |
9809 | code string as it can, up to a maximum of @var{bufSize} characters. The | |
9810 | number of characters actually returned, excluding the null termination | |
9811 | character, is specified by @var{length}. If the length of the returned | |
9812 | string is not required, a value of @code{NULL} can be passed in the | |
9813 | @var{length} argument. The size of the buffer required to store the | |
9814 | returned source code string can be obtained by calling | |
9815 | @code{glGetShader} with the value @code{GL_SHADER_SOURCE_LENGTH}. | |
9816 | ||
8925f36f AW |
9817 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
9818 | generated by OpenGL. | |
9819 | ||
9820 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
9821 | object. | |
9822 | ||
9823 | @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0. | |
9824 | ||
9825 | @code{GL_INVALID_OPERATION} is generated if @code{glGetShaderSource} is | |
9826 | executed between the execution of @code{glBegin} and the corresponding | |
9827 | execution of @code{glEnd}. | |
9828 | ||
bb894c9d | 9829 | @end deftypefun |
8925f36f | 9830 | |
b002944d AW |
9831 | @deftypefun void glGetShaderiv shader pname params |
9832 | Returns a parameter from a shader object. | |
9833 | ||
9834 | @table @asis | |
9835 | @item @var{shader} | |
9836 | Specifies the shader object to be queried. | |
9837 | ||
9838 | @item @var{pname} | |
9839 | Specifies the object parameter. Accepted symbolic names are | |
9840 | @code{GL_SHADER_TYPE}, @code{GL_DELETE_STATUS}, | |
9841 | @code{GL_COMPILE_STATUS}, @code{GL_INFO_LOG_LENGTH}, | |
9842 | @code{GL_SHADER_SOURCE_LENGTH}. | |
9843 | ||
9844 | @item @var{params} | |
9845 | Returns the requested object parameter. | |
9846 | ||
9847 | @end table | |
9848 | ||
9849 | @code{glGetShader} returns in @var{params} the value of a parameter for | |
9850 | a specific shader object. The following parameters are defined: | |
9851 | ||
9852 | @table @asis | |
9853 | @item @code{GL_SHADER_TYPE} | |
9854 | @var{params} returns @code{GL_VERTEX_SHADER} if @var{shader} is a vertex | |
9855 | shader object, and @code{GL_FRAGMENT_SHADER} if @var{shader} is a | |
9856 | fragment shader object. | |
9857 | ||
9858 | @item @code{GL_DELETE_STATUS} | |
9859 | @var{params} returns @code{GL_TRUE} if @var{shader} is currently flagged | |
9860 | for deletion, and @code{GL_FALSE} otherwise. | |
9861 | ||
9862 | @item @code{GL_COMPILE_STATUS} | |
9863 | @var{params} returns @code{GL_TRUE} if the last compile operation on | |
9864 | @var{shader} was successful, and @code{GL_FALSE} otherwise. | |
9865 | ||
9866 | @item @code{GL_INFO_LOG_LENGTH} | |
9867 | @var{params} returns the number of characters in the information log for | |
9868 | @var{shader} including the null termination character (i.e., the size of | |
9869 | the character buffer required to store the information log). If | |
9870 | @var{shader} has no information log, a value of 0 is returned. | |
9871 | ||
9872 | @item @code{GL_SHADER_SOURCE_LENGTH} | |
9873 | @var{params} returns the length of the concatenation of the source | |
9874 | strings that make up the shader source for the @var{shader}, including | |
9875 | the null termination character. (i.e., the size of the character buffer | |
9876 | required to store the shader source). If no source code exists, 0 is | |
9877 | returned. | |
9878 | ||
9879 | @end table | |
9880 | ||
9881 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value | |
9882 | generated by OpenGL. | |
9883 | ||
9884 | @code{GL_INVALID_OPERATION} is generated if @var{shader} does not refer | |
9885 | to a shader object. | |
9886 | ||
9887 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted | |
9888 | value. | |
9889 | ||
9890 | @code{GL_INVALID_OPERATION} is generated if @code{glGetShader} is | |
9891 | executed between the execution of @code{glBegin} and the corresponding | |
9892 | execution of @code{glEnd}. | |
9893 | ||
9894 | @end deftypefun | |
9895 | ||
00239761 | 9896 | @deftypefun const-GLubyte* glGetString name |
3c9b6116 AW |
9897 | Return a string describing the current GL connection. |
9898 | ||
8925f36f AW |
9899 | @table @asis |
9900 | @item @var{name} | |
9901 | Specifies a symbolic constant, one of @code{GL_VENDOR}, | |
9902 | @code{GL_RENDERER}, @code{GL_VERSION}, | |
9903 | @code{GL_SHADING_LANGUAGE_VERSION}, or @code{GL_EXTENSIONS}. | |
9904 | ||
9905 | @end table | |
9906 | ||
8925f36f AW |
9907 | @code{glGetString} returns a pointer to a static string describing some |
9908 | aspect of the current GL connection. @var{name} can be one of the | |
9909 | following: | |
9910 | ||
9911 | @table @asis | |
9912 | @item @code{GL_VENDOR} | |
9913 | ||
9914 | ||
9915 | Returns the company responsible for this GL implementation. This name | |
9916 | does not change from release to release. | |
9917 | ||
9918 | @item @code{GL_RENDERER} | |
9919 | ||
9920 | ||
9921 | Returns the name of the renderer. This name is typically specific to a | |
9922 | particular configuration of a hardware platform. It does not change from | |
9923 | release to release. | |
9924 | ||
9925 | @item @code{GL_VERSION} | |
9926 | ||
9927 | ||
9928 | Returns a version or release number. | |
9929 | ||
9930 | @item @code{GL_SHADING_LANGUAGE_VERSION} | |
9931 | ||
9932 | ||
9933 | Returns a version or release number for the shading language. | |
9934 | ||
9935 | @item @code{GL_EXTENSIONS} | |
9936 | ||
9937 | ||
9938 | Returns a space-separated list of supported extensions to GL. | |
9939 | ||
9940 | @end table | |
9941 | ||
bb894c9d AW |
9942 | Because the GL does not include queries for the performance |
9943 | characteristics of an implementation, some applications are written to | |
9944 | recognize known platforms and modify their GL usage based on known | |
9945 | performance characteristics of these platforms. Strings @code{GL_VENDOR} | |
9946 | and @code{GL_RENDERER} together uniquely specify a platform. They do not | |
9947 | change from release to release and should be used by | |
9948 | platform-recognition algorithms. | |
8925f36f | 9949 | |
b002944d AW |
9950 | Some applications want to make use of features that are not part of the |
9951 | standard GL. These features may be implemented as extensions to the | |
9952 | standard GL. The @code{GL_EXTENSIONS} string is a space-separated list | |
9953 | of supported GL extensions. (Extension names never contain a space | |
9954 | character.) | |
9955 | ||
9956 | The @code{GL_VERSION} and @code{GL_SHADING_LANGUAGE_VERSION} strings | |
9957 | begin with a version number. The version number uses one of these forms: | |
9958 | ||
9959 | @var{major_number.minor_number}@var{major_number.minor_number.release_number} | |
9960 | ||
9961 | Vendor-specific information may follow the version number. Its format | |
9962 | depends on the implementation, but a space always separates the version | |
9963 | number and the vendor-specific information. | |
9964 | ||
9965 | All strings are null-terminated. | |
9966 | ||
9967 | @code{GL_INVALID_ENUM} is generated if @var{name} is not an accepted | |
9968 | value. | |
9969 | ||
9970 | @code{GL_INVALID_OPERATION} is generated if @code{glGetString} is | |
9971 | executed between the execution of @code{glBegin} and the corresponding | |
9972 | execution of @code{glEnd}. | |
9973 | ||
9974 | @end deftypefun | |
9975 | ||
9976 | @deftypefun void glGetTexEnvfv target pname params | |
9977 | @deftypefunx void glGetTexEnviv target pname params | |
9978 | Return texture environment parameters. | |
9979 | ||
9980 | @table @asis | |
9981 | @item @var{target} | |
9982 | Specifies a texture environment. May be @code{GL_TEXTURE_ENV}, | |
9983 | @code{GL_TEXTURE_FILTER_CONTROL}, or @code{GL_POINT_SPRITE}. | |
9984 | ||
9985 | @item @var{pname} | |
9986 | Specifies the symbolic name of a texture environment parameter. Accepted | |
9987 | values are @code{GL_TEXTURE_ENV_MODE}, @code{GL_TEXTURE_ENV_COLOR}, | |
9988 | @code{GL_TEXTURE_LOD_BIAS}, @code{GL_COMBINE_RGB}, | |
9989 | @code{GL_COMBINE_ALPHA}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, | |
9990 | @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, | |
9991 | @code{GL_SRC2_ALPHA}, @code{GL_OPERAND0_RGB}, @code{GL_OPERAND1_RGB}, | |
9992 | @code{GL_OPERAND2_RGB}, @code{GL_OPERAND0_ALPHA}, | |
9993 | @code{GL_OPERAND1_ALPHA}, @code{GL_OPERAND2_ALPHA}, @code{GL_RGB_SCALE}, | |
9994 | @code{GL_ALPHA_SCALE}, or @code{GL_COORD_REPLACE}. | |
9995 | ||
9996 | @item @var{params} | |
9997 | Returns the requested data. | |
9998 | ||
9999 | @end table | |
10000 | ||
10001 | @code{glGetTexEnv} returns in @var{params} selected values of a texture | |
10002 | environment that was specified with @code{glTexEnv}. @var{target} | |
10003 | specifies a texture environment. | |
10004 | ||
10005 | When @var{target} is @code{GL_TEXTURE_FILTER_CONTROL}, @var{pname} must | |
10006 | be @code{GL_TEXTURE_LOD_BIAS}. When @var{target} is | |
10007 | @code{GL_POINT_SPRITE}, @var{pname} must be @code{GL_COORD_REPLACE}. | |
10008 | When @var{target} is @code{GL_TEXTURE_ENV}, @var{pname} can be | |
10009 | @code{GL_TEXTURE_ENV_MODE}, @code{GL_TEXTURE_ENV_COLOR}, | |
10010 | @code{GL_COMBINE_RGB}, @code{GL_COMBINE_ALPHA}, @code{GL_RGB_SCALE}, | |
10011 | @code{GL_ALPHA_SCALE}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, | |
10012 | @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, or | |
10013 | @code{GL_SRC2_ALPHA}. | |
10014 | ||
10015 | @var{pname} names a specific texture environment parameter, as follows: | |
10016 | ||
10017 | @table @asis | |
10018 | @item @code{GL_TEXTURE_ENV_MODE} | |
10019 | @var{params} returns the single-valued texture environment mode, a | |
10020 | symbolic constant. The initial value is @code{GL_MODULATE}. | |
10021 | ||
10022 | @item @code{GL_TEXTURE_ENV_COLOR} | |
10023 | @var{params} returns four integer or floating-point values that are the | |
10024 | texture environment color. Integer values, when requested, are linearly | |
10025 | mapped from the internal floating-point representation such that 1.0 | |
10026 | maps to the most positive representable integer, and @r{-1.0} maps to | |
10027 | the most negative representable integer. The initial value is (0, 0, 0, | |
10028 | 0). | |
10029 | ||
10030 | @item @code{GL_TEXTURE_LOD_BIAS} | |
10031 | @var{params} returns a single floating-point value that is the texture | |
10032 | level-of-detail bias. The initial value is 0. | |
10033 | ||
10034 | @item @code{GL_COMBINE_RGB} | |
10035 | @var{params} returns a single symbolic constant value representing the | |
10036 | current RGB combine mode. The initial value is @code{GL_MODULATE}. | |
10037 | ||
10038 | @item @code{GL_COMBINE_ALPHA} | |
10039 | @var{params} returns a single symbolic constant value representing the | |
10040 | current alpha combine mode. The initial value is @code{GL_MODULATE}. | |
10041 | ||
10042 | @item @code{GL_SRC0_RGB} | |
10043 | @var{params} returns a single symbolic constant value representing the | |
10044 | texture combiner zero's RGB source. The initial value is | |
10045 | @code{GL_TEXTURE}. | |
10046 | ||
10047 | @item @code{GL_SRC1_RGB} | |
10048 | @var{params} returns a single symbolic constant value representing the | |
10049 | texture combiner one's RGB source. The initial value is | |
10050 | @code{GL_PREVIOUS}. | |
10051 | ||
10052 | @item @code{GL_SRC2_RGB} | |
10053 | @var{params} returns a single symbolic constant value representing the | |
10054 | texture combiner two's RGB source. The initial value is | |
10055 | @code{GL_CONSTANT}. | |
10056 | ||
10057 | @item @code{GL_SRC0_ALPHA} | |
10058 | @var{params} returns a single symbolic constant value representing the | |
10059 | texture combiner zero's alpha source. The initial value is | |
10060 | @code{GL_TEXTURE}. | |
10061 | ||
10062 | @item @code{GL_SRC1_ALPHA} | |
10063 | @var{params} returns a single symbolic constant value representing the | |
10064 | texture combiner one's alpha source. The initial value is | |
10065 | @code{GL_PREVIOUS}. | |
10066 | ||
10067 | @item @code{GL_SRC2_ALPHA} | |
10068 | @var{params} returns a single symbolic constant value representing the | |
10069 | texture combiner two's alpha source. The initial value is | |
10070 | @code{GL_CONSTANT}. | |
10071 | ||
10072 | @item @code{GL_OPERAND0_RGB} | |
10073 | @var{params} returns a single symbolic constant value representing the | |
10074 | texture combiner zero's RGB operand. The initial value is | |
10075 | @code{GL_SRC_COLOR}. | |
10076 | ||
10077 | @item @code{GL_OPERAND1_RGB} | |
10078 | @var{params} returns a single symbolic constant value representing the | |
10079 | texture combiner one's RGB operand. The initial value is | |
10080 | @code{GL_SRC_COLOR}. | |
10081 | ||
10082 | @item @code{GL_OPERAND2_RGB} | |
10083 | @var{params} returns a single symbolic constant value representing the | |
10084 | texture combiner two's RGB operand. The initial value is | |
10085 | @code{GL_SRC_ALPHA}. | |
10086 | ||
10087 | @item @code{GL_OPERAND0_ALPHA} | |
10088 | @var{params} returns a single symbolic constant value representing the | |
10089 | texture combiner zero's alpha operand. The initial value is | |
10090 | @code{GL_SRC_ALPHA}. | |
10091 | ||
10092 | @item @code{GL_OPERAND1_ALPHA} | |
10093 | @var{params} returns a single symbolic constant value representing the | |
10094 | texture combiner one's alpha operand. The initial value is | |
10095 | @code{GL_SRC_ALPHA}. | |
10096 | ||
10097 | @item @code{GL_OPERAND2_ALPHA} | |
10098 | @var{params} returns a single symbolic constant value representing the | |
10099 | texture combiner two's alpha operand. The initial value is | |
10100 | @code{GL_SRC_ALPHA}. | |
10101 | ||
10102 | @item @code{GL_RGB_SCALE} | |
10103 | @var{params} returns a single floating-point value representing the | |
10104 | current RGB texture combiner scaling factor. The initial value is 1.0. | |
10105 | ||
10106 | @item @code{GL_ALPHA_SCALE} | |
10107 | @var{params} returns a single floating-point value representing the | |
10108 | current alpha texture combiner scaling factor. The initial value is 1.0. | |
10109 | ||
10110 | @item @code{GL_COORD_REPLACE} | |
10111 | @var{params} returns a single boolean value representing the current | |
10112 | point sprite texture coordinate replacement enable state. The initial | |
10113 | value is @code{GL_FALSE}. | |
10114 | ||
10115 | @end table | |
10116 | ||
10117 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
10118 | not an accepted value. | |
10119 | ||
10120 | @code{GL_INVALID_OPERATION} is generated if @code{glGetTexEnv} is | |
10121 | executed between the execution of @code{glBegin} and the corresponding | |
10122 | execution of @code{glEnd}. | |
10123 | ||
10124 | @end deftypefun | |
10125 | ||
10126 | @deftypefun void glGetTexGenfv coord pname params | |
10127 | @deftypefunx void glGetTexGeniv coord pname params | |
10128 | Return texture coordinate generation parameters. | |
10129 | ||
10130 | @table @asis | |
10131 | @item @var{coord} | |
10132 | Specifies a texture coordinate. Must be @code{GL_S}, @code{GL_T}, | |
10133 | @code{GL_R}, or @code{GL_Q}. | |
10134 | ||
10135 | @item @var{pname} | |
10136 | Specifies the symbolic name of the value(s) to be returned. Must be | |
10137 | either @code{GL_TEXTURE_GEN_MODE} or the name of one of the texture | |
10138 | generation plane equations: @code{GL_OBJECT_PLANE} or | |
10139 | @code{GL_EYE_PLANE}. | |
10140 | ||
10141 | @item @var{params} | |
10142 | Returns the requested data. | |
10143 | ||
10144 | @end table | |
10145 | ||
10146 | @code{glGetTexGen} returns in @var{params} selected parameters of a | |
10147 | texture coordinate generation function that was specified using | |
10148 | @code{glTexGen}. @var{coord} names one of the (@var{s}, @var{t}, | |
10149 | @var{r}, @var{q}) texture coordinates, using the symbolic constant | |
10150 | @code{GL_S}, @code{GL_T}, @code{GL_R}, or @code{GL_Q}. | |
10151 | ||
10152 | @var{pname} specifies one of three symbolic names: | |
10153 | ||
10154 | @table @asis | |
10155 | @item @code{GL_TEXTURE_GEN_MODE} | |
10156 | @var{params} returns the single-valued texture generation function, a | |
10157 | symbolic constant. The initial value is @code{GL_EYE_LINEAR}. | |
10158 | ||
10159 | @item @code{GL_OBJECT_PLANE} | |
10160 | @var{params} returns the four plane equation coefficients that specify | |
10161 | object linear-coordinate generation. Integer values, when requested, are | |
10162 | mapped directly from the internal floating-point representation. | |
10163 | ||
10164 | @item @code{GL_EYE_PLANE} | |
10165 | @var{params} returns the four plane equation coefficients that specify | |
10166 | eye linear-coordinate generation. Integer values, when requested, are | |
10167 | mapped directly from the internal floating-point representation. The | |
10168 | returned values are those maintained in eye coordinates. They are not | |
10169 | equal to the values specified using @code{glTexGen}, unless the | |
10170 | modelview matrix was identity when @code{glTexGen} was called. | |
10171 | ||
10172 | @end table | |
10173 | ||
10174 | @code{GL_INVALID_ENUM} is generated if @var{coord} or @var{pname} is not | |
10175 | an accepted value. | |
10176 | ||
10177 | @code{GL_INVALID_OPERATION} is generated if @code{glGetTexGen} is | |
10178 | executed between the execution of @code{glBegin} and the corresponding | |
10179 | execution of @code{glEnd}. | |
10180 | ||
10181 | @end deftypefun | |
10182 | ||
10183 | @deftypefun void glGetTexImage target level format type img | |
10184 | Return a texture image. | |
10185 | ||
10186 | @table @asis | |
10187 | @item @var{target} | |
10188 | Specifies which texture is to be obtained. @code{GL_TEXTURE_1D}, | |
10189 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, | |
10190 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
10191 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
10192 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
10193 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
10194 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, and | |
10195 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z} are accepted. | |
10196 | ||
10197 | @item @var{level} | |
10198 | Specifies the level-of-detail number of the desired image. Level 0 is | |
10199 | the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap | |
10200 | reduction image. | |
10201 | ||
10202 | @item @var{format} | |
10203 | Specifies a pixel format for the returned data. The supported formats | |
10204 | are @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, | |
10205 | @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, | |
10206 | @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA}. | |
10207 | ||
10208 | @item @var{type} | |
10209 | Specifies a pixel type for the returned data. The supported types are | |
10210 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT}, | |
10211 | @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT}, | |
10212 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
10213 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
10214 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
10215 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
10216 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
10217 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
10218 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
10219 | ||
10220 | @item @var{img} | |
10221 | Returns the texture image. Should be a pointer to an array of the type | |
10222 | specified by @var{type}. | |
10223 | ||
10224 | @end table | |
10225 | ||
10226 | @code{glGetTexImage} returns a texture image into @var{img}. | |
10227 | @var{target} specifies whether the desired texture image is one | |
10228 | specified by @code{glTexImage1D} (@code{GL_TEXTURE_1D}), | |
10229 | @code{glTexImage2D} (@code{GL_TEXTURE_2D} or any of | |
10230 | @code{GL_TEXTURE_CUBE_MAP_*}), or @code{glTexImage3D} | |
10231 | (@code{GL_TEXTURE_3D}). @var{level} specifies the level-of-detail number | |
10232 | of the desired image. @var{format} and @var{type} specify the format and | |
10233 | type of the desired image array. See the reference pages | |
10234 | @code{glTexImage1D} and @code{glDrawPixels} for a description of the | |
10235 | acceptable values for the @var{format} and @var{type} parameters, | |
10236 | respectively. | |
10237 | ||
10238 | If a non-zero named buffer object is bound to the | |
10239 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
10240 | texture image is requested, @var{img} is treated as a byte offset into | |
10241 | the buffer object's data store. | |
10242 | ||
10243 | To understand the operation of @code{glGetTexImage}, consider the | |
10244 | selected internal four-component texture image to be an RGBA color | |
10245 | buffer the size of the image. The semantics of @code{glGetTexImage} are | |
10246 | then identical to those of @code{glReadPixels}, with the exception that | |
10247 | no pixel transfer operations are performed, when called with the same | |
10248 | @var{format} and @var{type}, with @var{x} and @var{y} set to 0, | |
10249 | @var{width} set to the width of the texture image (including border if | |
10250 | one was specified), and @var{height} set to 1 for 1D images, or to the | |
10251 | height of the texture image (including border if one was specified) for | |
10252 | 2D images. Because the internal texture image is an RGBA image, pixel | |
10253 | formats @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, and | |
10254 | @code{GL_DEPTH_COMPONENT} are not accepted, and pixel type | |
10255 | @code{GL_BITMAP} is not accepted. | |
10256 | ||
10257 | If the selected texture image does not contain four components, the | |
10258 | following mappings are applied. Single-component textures are treated as | |
10259 | RGBA buffers with red set to the single-component value, green set to 0, | |
10260 | blue set to 0, and alpha set to 1. Two-component textures are treated as | |
10261 | RGBA buffers with red set to the value of component zero, alpha set to | |
10262 | the value of component one, and green and blue set to 0. Finally, | |
10263 | three-component textures are treated as RGBA buffers with red set to | |
10264 | component zero, green set to component one, blue set to component two, | |
10265 | and alpha set to 1. | |
10266 | ||
10267 | To determine the required size of @var{img}, use | |
10268 | @code{glGetTexLevelParameter} to determine the dimensions of the | |
10269 | internal texture image, then scale the required number of pixels by the | |
10270 | storage required for each pixel, based on @var{format} and @var{type}. | |
10271 | Be sure to take the pixel storage parameters into account, especially | |
10272 | @code{GL_PACK_ALIGNMENT}. | |
10273 | ||
10274 | @code{GL_INVALID_ENUM} is generated if @var{target}, @var{format}, or | |
10275 | @var{type} is not an accepted value. | |
10276 | ||
10277 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
10278 | ||
10279 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
10280 | @r{@var{log}_2(@var{max},)}, where @r{@var{max}} is the returned value | |
10281 | of @code{GL_MAX_TEXTURE_SIZE}. | |
10282 | ||
10283 | @code{GL_INVALID_OPERATION} is returned if @var{type} is one of | |
10284 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
10285 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
10286 | and @var{format} is not @code{GL_RGB}. | |
10287 | ||
10288 | @code{GL_INVALID_OPERATION} is returned if @var{type} is one of | |
10289 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
10290 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
10291 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
10292 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
10293 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}, and @var{format} is neither | |
10294 | @code{GL_RGBA} or @code{GL_BGRA}. | |
10295 | ||
10296 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
10297 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
10298 | object's data store is currently mapped. | |
10299 | ||
10300 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
10301 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
10302 | would be packed to the buffer object such that the memory writes | |
10303 | required would exceed the data store size. | |
10304 | ||
10305 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
10306 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{img} is | |
10307 | not evenly divisible into the number of bytes needed to store in memory | |
10308 | a datum indicated by @var{type}. | |
10309 | ||
10310 | @code{GL_INVALID_OPERATION} is generated if @code{glGetTexImage} is | |
10311 | executed between the execution of @code{glBegin} and the corresponding | |
10312 | execution of @code{glEnd}. | |
10313 | ||
10314 | @end deftypefun | |
10315 | ||
10316 | @deftypefun void glGetTexLevelParameterfv target level pname params | |
10317 | @deftypefunx void glGetTexLevelParameteriv target level pname params | |
10318 | Return texture parameter values for a specific level of detail. | |
10319 | ||
10320 | @table @asis | |
10321 | @item @var{target} | |
10322 | Specifies the symbolic name of the target texture, either | |
10323 | @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, | |
10324 | @code{GL_PROXY_TEXTURE_1D}, @code{GL_PROXY_TEXTURE_2D}, | |
10325 | @code{GL_PROXY_TEXTURE_3D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
10326 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
10327 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
10328 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
10329 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, | |
10330 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or | |
10331 | @code{GL_PROXY_TEXTURE_CUBE_MAP}. | |
10332 | ||
10333 | @item @var{level} | |
10334 | Specifies the level-of-detail number of the desired image. Level 0 is | |
10335 | the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap | |
10336 | reduction image. | |
10337 | ||
10338 | @item @var{pname} | |
10339 | Specifies the symbolic name of a texture parameter. | |
10340 | @code{GL_TEXTURE_WIDTH}, @code{GL_TEXTURE_HEIGHT}, | |
10341 | @code{GL_TEXTURE_DEPTH}, @code{GL_TEXTURE_INTERNAL_FORMAT}, | |
10342 | @code{GL_TEXTURE_BORDER}, @code{GL_TEXTURE_RED_SIZE}, | |
10343 | @code{GL_TEXTURE_GREEN_SIZE}, @code{GL_TEXTURE_BLUE_SIZE}, | |
10344 | @code{GL_TEXTURE_ALPHA_SIZE}, @code{GL_TEXTURE_LUMINANCE_SIZE}, | |
10345 | @code{GL_TEXTURE_INTENSITY_SIZE}, @code{GL_TEXTURE_DEPTH_SIZE}, | |
10346 | @code{GL_TEXTURE_COMPRESSED}, and | |
10347 | @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} are accepted. | |
10348 | ||
10349 | @item @var{params} | |
10350 | Returns the requested data. | |
10351 | ||
10352 | @end table | |
10353 | ||
10354 | @code{glGetTexLevelParameter} returns in @var{params} texture parameter | |
10355 | values for a specific level-of-detail value, specified as @var{level}. | |
10356 | @var{target} defines the target texture, either @code{GL_TEXTURE_1D}, | |
10357 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, @code{GL_PROXY_TEXTURE_1D}, | |
10358 | @code{GL_PROXY_TEXTURE_2D}, @code{GL_PROXY_TEXTURE_3D}, | |
10359 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
10360 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
10361 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
10362 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
10363 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, | |
10364 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or | |
10365 | @code{GL_PROXY_TEXTURE_CUBE_MAP}. | |
10366 | ||
10367 | @code{GL_MAX_TEXTURE_SIZE}, and @code{GL_MAX_3D_TEXTURE_SIZE} are not | |
10368 | really descriptive enough. It has to report the largest square texture | |
10369 | image that can be accommodated with mipmaps and borders, but a long | |
10370 | skinny texture, or a texture without mipmaps and borders, may easily fit | |
10371 | in texture memory. The proxy targets allow the user to more accurately | |
10372 | query whether the GL can accommodate a texture of a given configuration. | |
10373 | If the texture cannot be accommodated, the texture state variables, | |
10374 | which may be queried with @code{glGetTexLevelParameter}, are set to 0. | |
10375 | If the texture can be accommodated, the texture state values will be set | |
10376 | as they would be set for a non-proxy target. | |
10377 | ||
10378 | @var{pname} specifies the texture parameter whose value or values will | |
10379 | be returned. | |
10380 | ||
10381 | The accepted parameter names are as follows: | |
10382 | ||
10383 | @table @asis | |
10384 | @item @code{GL_TEXTURE_WIDTH} | |
10385 | ||
10386 | ||
10387 | @var{params} returns a single value, the width of the texture image. | |
10388 | This value includes the border of the texture image. The initial value | |
10389 | is 0. | |
10390 | ||
10391 | @item @code{GL_TEXTURE_HEIGHT} | |
10392 | ||
10393 | ||
10394 | @var{params} returns a single value, the height of the texture image. | |
10395 | This value includes the border of the texture image. The initial value | |
10396 | is 0. | |
10397 | ||
10398 | @item @code{GL_TEXTURE_DEPTH} | |
10399 | ||
10400 | ||
10401 | @var{params} returns a single value, the depth of the texture image. | |
10402 | This value includes the border of the texture image. The initial value | |
10403 | is 0. | |
10404 | ||
10405 | @item @code{GL_TEXTURE_INTERNAL_FORMAT} | |
10406 | ||
10407 | ||
10408 | @var{params} returns a single value, the internal format of the texture | |
10409 | image. | |
10410 | ||
10411 | @item @code{GL_TEXTURE_BORDER} | |
10412 | ||
10413 | ||
10414 | @var{params} returns a single value, the width in pixels of the border | |
10415 | of the texture image. The initial value is 0. | |
10416 | ||
10417 | @item @code{GL_TEXTURE_RED_SIZE}, | |
10418 | @item @code{GL_TEXTURE_GREEN_SIZE}, | |
10419 | @item @code{GL_TEXTURE_BLUE_SIZE}, | |
10420 | @item @code{GL_TEXTURE_ALPHA_SIZE}, | |
10421 | @item @code{GL_TEXTURE_LUMINANCE_SIZE}, | |
10422 | @item @code{GL_TEXTURE_INTENSITY_SIZE}, | |
10423 | @item @code{GL_TEXTURE_DEPTH_SIZE} | |
10424 | ||
10425 | ||
10426 | The internal storage resolution of an individual component. The | |
10427 | resolution chosen by the GL will be a close match for the resolution | |
10428 | requested by the user with the component argument of | |
10429 | @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D}, | |
10430 | @code{glCopyTexImage1D}, and @code{glCopyTexImage2D}. The initial value | |
10431 | is 0. | |
10432 | ||
10433 | @item @code{GL_TEXTURE_COMPRESSED} | |
10434 | ||
10435 | ||
10436 | @var{params} returns a single boolean value indicating if the texture | |
10437 | image is stored in a compressed internal format. The initiali value is | |
10438 | @code{GL_FALSE}. | |
10439 | ||
10440 | @item @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} | |
10441 | ||
10442 | ||
10443 | @var{params} returns a single integer value, the number of unsigned | |
10444 | bytes of the compressed texture image that would be returned from | |
10445 | @code{glGetCompressedTexImage}. | |
10446 | ||
10447 | @end table | |
10448 | ||
10449 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
10450 | not an accepted value. | |
10451 | ||
10452 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
10453 | ||
10454 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
10455 | @r{@var{log}_2}@var{max}, where @var{max} is the returned value of | |
10456 | @code{GL_MAX_TEXTURE_SIZE}. | |
10457 | ||
10458 | @code{GL_INVALID_OPERATION} is generated if | |
10459 | @code{glGetTexLevelParameter} is executed between the execution of | |
10460 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
10461 | ||
10462 | @code{GL_INVALID_OPERATION} is generated if | |
10463 | @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} is queried on texture images | |
10464 | with an uncompressed internal format or on proxy targets. | |
10465 | ||
10466 | @end deftypefun | |
10467 | ||
10468 | @deftypefun void glGetTexParameterfv target pname params | |
10469 | @deftypefunx void glGetTexParameteriv target pname params | |
10470 | Return texture parameter values. | |
10471 | ||
10472 | @table @asis | |
10473 | @item @var{target} | |
10474 | Specifies the symbolic name of the target texture. @code{GL_TEXTURE_1D}, | |
10475 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, and | |
10476 | @code{GL_TEXTURE_CUBE_MAP} are accepted. | |
10477 | ||
10478 | @item @var{pname} | |
10479 | Specifies the symbolic name of a texture parameter. | |
10480 | @code{GL_TEXTURE_MAG_FILTER}, @code{GL_TEXTURE_MIN_FILTER}, | |
10481 | @code{GL_TEXTURE_MIN_LOD}, @code{GL_TEXTURE_MAX_LOD}, | |
10482 | @code{GL_TEXTURE_BASE_LEVEL}, @code{GL_TEXTURE_MAX_LEVEL}, | |
10483 | @code{GL_TEXTURE_WRAP_S}, @code{GL_TEXTURE_WRAP_T}, | |
10484 | @code{GL_TEXTURE_WRAP_R}, @code{GL_TEXTURE_BORDER_COLOR}, | |
10485 | @code{GL_TEXTURE_PRIORITY}, @code{GL_TEXTURE_RESIDENT}, | |
10486 | @code{GL_TEXTURE_COMPARE_MODE}, @code{GL_TEXTURE_COMPARE_FUNC}, | |
10487 | @code{GL_DEPTH_TEXTURE_MODE}, and @code{GL_GENERATE_MIPMAP} are | |
10488 | accepted. | |
10489 | ||
10490 | @item @var{params} | |
10491 | Returns the texture parameters. | |
10492 | ||
10493 | @end table | |
10494 | ||
10495 | @code{glGetTexParameter} returns in @var{params} the value or values of | |
10496 | the texture parameter specified as @var{pname}. @var{target} defines the | |
10497 | target texture, either @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, | |
10498 | @code{GL_TEXTURE_3D}, or @code{GL_TEXTURE_CUBE_MAP}, to specify one-, | |
10499 | two-, or three-dimensional or cube-mapped texturing. @var{pname} accepts | |
10500 | the same symbols as @code{glTexParameter}, with the same | |
10501 | interpretations: | |
10502 | ||
10503 | @table @asis | |
10504 | @item @code{GL_TEXTURE_MAG_FILTER} | |
10505 | Returns the single-valued texture magnification filter, a symbolic | |
10506 | constant. The initial value is @code{GL_LINEAR}. | |
10507 | ||
10508 | @item @code{GL_TEXTURE_MIN_FILTER} | |
10509 | Returns the single-valued texture minification filter, a symbolic | |
10510 | constant. The initial value is @code{GL_NEAREST_MIPMAP_LINEAR}. | |
10511 | ||
10512 | @item @code{GL_TEXTURE_MIN_LOD} | |
10513 | Returns the single-valued texture minimum level-of-detail value. The | |
10514 | initial value is @r{-1000}. | |
10515 | ||
10516 | @item @code{GL_TEXTURE_MAX_LOD} | |
10517 | Returns the single-valued texture maximum level-of-detail value. The | |
10518 | initial value is 1000. | |
10519 | ||
10520 | @item @code{GL_TEXTURE_BASE_LEVEL} | |
10521 | Returns the single-valued base texture mipmap level. The initial value | |
10522 | is 0. | |
10523 | ||
10524 | @item @code{GL_TEXTURE_MAX_LEVEL} | |
10525 | Returns the single-valued maximum texture mipmap array level. The | |
10526 | initial value is 1000. | |
10527 | ||
10528 | @item @code{GL_TEXTURE_WRAP_S} | |
10529 | Returns the single-valued wrapping function for texture coordinate | |
10530 | @r{@var{s}}, a symbolic constant. The initial value is @code{GL_REPEAT}. | |
10531 | ||
10532 | @item @code{GL_TEXTURE_WRAP_T} | |
10533 | Returns the single-valued wrapping function for texture coordinate | |
10534 | @r{@var{t}}, a symbolic constant. The initial value is @code{GL_REPEAT}. | |
10535 | ||
10536 | @item @code{GL_TEXTURE_WRAP_R} | |
10537 | Returns the single-valued wrapping function for texture coordinate | |
10538 | @r{@var{r}}, a symbolic constant. The initial value is @code{GL_REPEAT}. | |
10539 | ||
10540 | @item @code{GL_TEXTURE_BORDER_COLOR} | |
10541 | Returns four integer or floating-point numbers that comprise the RGBA | |
10542 | color of the texture border. Floating-point values are returned in the | |
10543 | range @r{[0,1]}. Integer values are returned as a linear mapping of the | |
10544 | internal floating-point representation such that 1.0 maps to the most | |
10545 | positive representable integer and @r{-1.0} maps to the most negative | |
10546 | representable integer. The initial value is (0, 0, 0, 0). | |
10547 | ||
10548 | @item @code{GL_TEXTURE_PRIORITY} | |
10549 | Returns the residence priority of the target texture (or the named | |
10550 | texture bound to it). The initial value is 1. See | |
10551 | @code{glPrioritizeTextures}. | |
10552 | ||
10553 | @item @code{GL_TEXTURE_RESIDENT} | |
10554 | Returns the residence status of the target texture. If the value | |
10555 | returned in @var{params} is @code{GL_TRUE}, the texture is resident in | |
10556 | texture memory. See @code{glAreTexturesResident}. | |
10557 | ||
10558 | @item @code{GL_TEXTURE_COMPARE_MODE} | |
10559 | Returns a single-valued texture comparison mode, a symbolic constant. | |
10560 | The initial value is @code{GL_NONE}. See @code{glTexParameter}. | |
10561 | ||
10562 | @item @code{GL_TEXTURE_COMPARE_FUNC} | |
10563 | Returns a single-valued texture comparison function, a symbolic | |
10564 | constant. The initial value is @code{GL_LEQUAL}. See | |
10565 | @code{glTexParameter}. | |
10566 | ||
10567 | @item @code{GL_DEPTH_TEXTURE_MODE} | |
10568 | Returns a single-valued texture format indicating how the depth values | |
10569 | should be converted into color components. The initial value is | |
10570 | @code{GL_LUMINANCE}. See @code{glTexParameter}. | |
10571 | ||
10572 | @item @code{GL_GENERATE_MIPMAP} | |
10573 | Returns a single boolean value indicating if automatic mipmap level | |
10574 | updates are enabled. See @code{glTexParameter}. | |
10575 | ||
10576 | @end table | |
10577 | ||
10578 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
10579 | not an accepted value. | |
10580 | ||
10581 | @code{GL_INVALID_OPERATION} is generated if @code{glGetTexParameter} is | |
10582 | executed between the execution of @code{glBegin} and the corresponding | |
10583 | execution of @code{glEnd}. | |
10584 | ||
10585 | @end deftypefun | |
10586 | ||
10587 | @deftypefun GLint glGetUniformLocation program name | |
10588 | Returns the location of a uniform variable. | |
10589 | ||
10590 | @table @asis | |
10591 | @item @var{program} | |
10592 | Specifies the program object to be queried. | |
10593 | ||
10594 | @item @var{name} | |
10595 | Points to a null terminated string containing the name of the uniform | |
10596 | variable whose location is to be queried. | |
10597 | ||
10598 | @end table | |
10599 | ||
10600 | @code{glGetUniformLocation } returns an integer that represents the | |
10601 | location of a specific uniform variable within a program object. | |
10602 | @var{name} must be a null terminated string that contains no white | |
10603 | space. @var{name} must be an active uniform variable name in | |
10604 | @var{program} that is not a structure, an array of structures, or a | |
10605 | subcomponent of a vector or a matrix. This function returns -1 if | |
10606 | @var{name} does not correspond to an active uniform variable in | |
10607 | @var{program} or if @var{name} starts with the reserved prefix "gl_". | |
10608 | ||
10609 | Uniform variables that are structures or arrays of structures may be | |
10610 | queried by calling @code{glGetUniformLocation} for each field within the | |
10611 | structure. The array element operator "[]" and the structure field | |
10612 | operator "." may be used in @var{name} in order to select elements | |
10613 | within an array or fields within a structure. The result of using these | |
10614 | operators is not allowed to be another structure, an array of | |
10615 | structures, or a subcomponent of a vector or a matrix. Except if the | |
10616 | last part of @var{name} indicates a uniform variable array, the location | |
10617 | of the first element of an array can be retrieved by using the name of | |
10618 | the array, or by using the name appended by "[0]". | |
10619 | ||
10620 | The actual locations assigned to uniform variables are not known until | |
10621 | the program object is linked successfully. After linking has occurred, | |
10622 | the command @code{glGetUniformLocation} can be used to obtain the | |
10623 | location of a uniform variable. This location value can then be passed | |
10624 | to @code{glUniform} to set the value of the uniform variable or to | |
10625 | @code{glGetUniform} in order to query the current value of the uniform | |
10626 | variable. After a program object has been linked successfully, the index | |
10627 | values for uniform variables remain fixed until the next link command | |
10628 | occurs. Uniform variable locations and values can only be queried after | |
10629 | a link if the link was successful. | |
10630 | ||
10631 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value | |
10632 | generated by OpenGL. | |
10633 | ||
10634 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
10635 | program object. | |
10636 | ||
10637 | @code{GL_INVALID_OPERATION} is generated if @var{program} has not been | |
10638 | successfully linked. | |
10639 | ||
10640 | @code{GL_INVALID_OPERATION} is generated if @code{glGetUniformLocation} | |
10641 | is executed between the execution of @code{glBegin} and the | |
10642 | corresponding execution of @code{glEnd}. | |
10643 | ||
10644 | @end deftypefun | |
10645 | ||
10646 | @deftypefun void glGetUniformfv program location params | |
10647 | @deftypefunx void glGetUniformiv program location params | |
10648 | Returns the value of a uniform variable. | |
10649 | ||
10650 | @table @asis | |
10651 | @item @var{program} | |
10652 | Specifies the program object to be queried. | |
10653 | ||
10654 | @item @var{location} | |
10655 | Specifies the location of the uniform variable to be queried. | |
10656 | ||
10657 | @item @var{params} | |
10658 | Returns the value of the specified uniform variable. | |
10659 | ||
10660 | @end table | |
10661 | ||
10662 | @code{glGetUniform} returns in @var{params} the value(s) of the | |
10663 | specified uniform variable. The type of the uniform variable specified | |
10664 | by @var{location} determines the number of values returned. If the | |
10665 | uniform variable is defined in the shader as a boolean, int, or float, a | |
10666 | single value will be returned. If it is defined as a vec2, ivec2, or | |
10667 | bvec2, two values will be returned. If it is defined as a vec3, ivec3, | |
10668 | or bvec3, three values will be returned, and so on. To query values | |
10669 | stored in uniform variables declared as arrays, call @code{glGetUniform} | |
10670 | for each element of the array. To query values stored in uniform | |
10671 | variables declared as structures, call @code{glGetUniform} for each | |
10672 | field in the structure. The values for uniform variables declared as a | |
10673 | matrix will be returned in column major order. | |
10674 | ||
10675 | The locations assigned to uniform variables are not known until the | |
10676 | program object is linked. After linking has occurred, the command | |
10677 | @code{glGetUniformLocation} can be used to obtain the location of a | |
10678 | uniform variable. This location value can then be passed to | |
10679 | @code{glGetUniform} in order to query the current value of the uniform | |
10680 | variable. After a program object has been linked successfully, the index | |
10681 | values for uniform variables remain fixed until the next link command | |
10682 | occurs. The uniform variable values can only be queried after a link if | |
10683 | the link was successful. | |
10684 | ||
10685 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value | |
10686 | generated by OpenGL. | |
10687 | ||
10688 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
10689 | program object. | |
10690 | ||
10691 | @code{GL_INVALID_OPERATION} is generated if @var{program} has not been | |
10692 | successfully linked. | |
10693 | ||
10694 | @code{GL_INVALID_OPERATION} is generated if @var{location} does not | |
10695 | correspond to a valid uniform variable location for the specified | |
10696 | program object. | |
10697 | ||
10698 | @code{GL_INVALID_OPERATION} is generated if @code{glGetUniform} is | |
10699 | executed between the execution of @code{glBegin} and the corresponding | |
10700 | execution of @code{glEnd}. | |
10701 | ||
10702 | @end deftypefun | |
10703 | ||
10704 | @deftypefun void glGetVertexAttribPointerv index pname pointer | |
10705 | Return the address of the specified generic vertex attribute pointer. | |
10706 | ||
10707 | @table @asis | |
10708 | @item @var{index} | |
10709 | Specifies the generic vertex attribute parameter to be returned. | |
10710 | ||
10711 | @item @var{pname} | |
10712 | Specifies the symbolic name of the generic vertex attribute parameter to | |
10713 | be returned. Must be @code{GL_VERTEX_ATTRIB_ARRAY_POINTER}. | |
10714 | ||
10715 | @item @var{pointer} | |
10716 | Returns the pointer value. | |
10717 | ||
10718 | @end table | |
10719 | ||
10720 | @code{glGetVertexAttribPointerv} returns pointer information. | |
10721 | @var{index} is the generic vertex attribute to be queried, @var{pname} | |
10722 | is a symbolic constant indicating the pointer to be returned, and | |
10723 | @var{params} is a pointer to a location in which to place the returned | |
10724 | data. | |
10725 | ||
10726 | If a non-zero named buffer object was bound to the | |
10727 | @code{GL_ARRAY_BUFFER} target (see @code{glBindBuffer}) when the desired | |
10728 | pointer was previously specified, the @var{pointer} returned is a byte | |
10729 | offset into the buffer object's data store. | |
10730 | ||
10731 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or | |
10732 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
10733 | ||
10734 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted | |
10735 | value. | |
10736 | ||
10737 | @end deftypefun | |
10738 | ||
10739 | @deftypefun void glGetVertexAttribfv index pname params | |
10740 | @deftypefunx void glGetVertexAttribiv index pname params | |
10741 | Return a generic vertex attribute parameter. | |
10742 | ||
10743 | @table @asis | |
10744 | @item @var{index} | |
10745 | Specifies the generic vertex attribute parameter to be queried. | |
10746 | ||
10747 | @item @var{pname} | |
10748 | Specifies the symbolic name of the vertex attribute parameter to be | |
10749 | queried. Accepted values are | |
10750 | @code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING}, | |
10751 | @code{GL_VERTEX_ATTRIB_ARRAY_ENABLED}, | |
10752 | @code{GL_VERTEX_ATTRIB_ARRAY_SIZE}, | |
10753 | @code{GL_VERTEX_ATTRIB_ARRAY_STRIDE}, | |
10754 | @code{GL_VERTEX_ATTRIB_ARRAY_TYPE}, | |
10755 | @code{GL_VERTEX_ATTRIB_ARRAY_NORMALIZED}, or | |
10756 | @code{GL_CURRENT_VERTEX_ATTRIB}. | |
10757 | ||
10758 | @item @var{params} | |
10759 | Returns the requested data. | |
10760 | ||
10761 | @end table | |
10762 | ||
10763 | @code{glGetVertexAttrib} returns in @var{params} the value of a generic | |
10764 | vertex attribute parameter. The generic vertex attribute to be queried | |
10765 | is specified by @var{index}, and the parameter to be queried is | |
10766 | specified by @var{pname}. | |
10767 | ||
10768 | The accepted parameter names are as follows: | |
10769 | ||
10770 | @table @asis | |
10771 | @item @code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING} | |
10772 | ||
10773 | ||
10774 | @var{params} returns a single value, the name of the buffer object | |
10775 | currently bound to the binding point corresponding to generic vertex | |
10776 | attribute array @var{index}. If no buffer object is bound, 0 is | |
10777 | returned. The initial value is 0. | |
10778 | ||
10779 | @item @code{GL_VERTEX_ATTRIB_ARRAY_ENABLED} | |
10780 | ||
10781 | ||
10782 | @var{params} returns a single value that is non-zero (true) if the | |
10783 | vertex attribute array for @var{index} is enabled and 0 (false) if it is | |
10784 | disabled. The initial value is @code{GL_FALSE}. | |
10785 | ||
10786 | @item @code{GL_VERTEX_ATTRIB_ARRAY_SIZE} | |
10787 | ||
10788 | ||
10789 | @var{params} returns a single value, the size of the vertex attribute | |
10790 | array for @var{index}. The size is the number of values for each element | |
10791 | of the vertex attribute array, and it will be 1, 2, 3, or 4. The initial | |
10792 | value is 4. | |
10793 | ||
10794 | @item @code{GL_VERTEX_ATTRIB_ARRAY_STRIDE} | |
10795 | ||
10796 | ||
10797 | @var{params} returns a single value, the array stride for (number of | |
10798 | bytes between successive elements in) the vertex attribute array for | |
10799 | @var{index}. A value of 0 indicates that the array elements are stored | |
10800 | sequentially in memory. The initial value is 0. | |
10801 | ||
10802 | @item @code{GL_VERTEX_ATTRIB_ARRAY_TYPE} | |
10803 | ||
10804 | ||
10805 | @var{params} returns a single value, a symbolic constant indicating the | |
10806 | array type for the vertex attribute array for @var{index}. Possible | |
10807 | values are @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, | |
10808 | @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT}, | |
10809 | @code{GL_FLOAT}, and @code{GL_DOUBLE}. The initial value is | |
10810 | @code{GL_FLOAT}. | |
10811 | ||
10812 | @item @code{GL_VERTEX_ATTRIB_ARRAY_NORMALIZED} | |
10813 | ||
10814 | ||
10815 | @var{params} returns a single value that is non-zero (true) if | |
10816 | fixed-point data types for the vertex attribute array indicated by | |
10817 | @var{index} are normalized when they are converted to floating point, | |
10818 | and 0 (false) otherwise. The initial value is @code{GL_FALSE}. | |
10819 | ||
10820 | @item @code{GL_CURRENT_VERTEX_ATTRIB} | |
10821 | ||
10822 | ||
10823 | @var{params} returns four values that represent the current value for | |
10824 | the generic vertex attribute specified by index. Generic vertex | |
10825 | attribute 0 is unique in that it has no current state, so an error will | |
10826 | be generated if @var{index} is 0. The initial value for all other | |
10827 | generic vertex attributes is (0,0,0,1). | |
10828 | ||
10829 | @end table | |
10830 | ||
10831 | All of the parameters except @code{GL_CURRENT_VERTEX_ATTRIB} represent | |
10832 | client-side state. | |
10833 | ||
10834 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or | |
10835 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
10836 | ||
10837 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted | |
10838 | value. | |
10839 | ||
10840 | @code{GL_INVALID_OPERATION} is generated if @var{index} is 0 and | |
10841 | @var{pname} is @code{GL_CURRENT_VERTEX_ATTRIB}. | |
10842 | ||
10843 | @end deftypefun | |
10844 | ||
10845 | @deftypefun void glGetBooleanv pname params | |
10846 | @deftypefunx void glGetDoublev pname params | |
10847 | @deftypefunx void glGetFloatv pname params | |
10848 | @deftypefunx void glGetIntegerv pname params | |
10849 | Return the value or values of a selected parameter. | |
10850 | ||
10851 | @table @asis | |
10852 | @item @var{pname} | |
10853 | Specifies the parameter value to be returned. The symbolic constants in | |
10854 | the list below are accepted. | |
10855 | ||
10856 | @item @var{params} | |
10857 | Returns the value or values of the specified parameter. | |
10858 | ||
10859 | @end table | |
10860 | ||
10861 | These four commands return values for simple state variables in GL. | |
10862 | @var{pname} is a symbolic constant indicating the state variable to be | |
10863 | returned, and @var{params} is a pointer to an array of the indicated | |
10864 | type in which to place the returned data. | |
10865 | ||
10866 | Type conversion is performed if @var{params} has a different type than | |
10867 | the state variable value being requested. If @code{glGetBooleanv} is | |
10868 | called, a floating-point (or integer) value is converted to | |
10869 | @code{GL_FALSE} if and only if it is 0.0 (or 0). Otherwise, it is | |
10870 | converted to @code{GL_TRUE}. If @code{glGetIntegerv} is called, boolean | |
10871 | values are returned as @code{GL_TRUE} or @code{GL_FALSE}, and most | |
10872 | floating-point values are rounded to the nearest integer value. | |
10873 | Floating-point colors and normals, however, are returned with a linear | |
10874 | mapping that maps 1.0 to the most positive representable integer value | |
10875 | and @r{-1.0} to the most negative representable integer value. If | |
10876 | @code{glGetFloatv} or @code{glGetDoublev} is called, boolean values are | |
10877 | returned as @code{GL_TRUE} or @code{GL_FALSE}, and integer values are | |
10878 | converted to floating-point values. | |
10879 | ||
10880 | The following symbolic constants are accepted by @var{pname}: | |
10881 | ||
10882 | @table @asis | |
10883 | @item @code{GL_ACCUM_ALPHA_BITS} | |
10884 | ||
10885 | ||
10886 | @var{params} returns one value, the number of alpha bitplanes in the | |
10887 | accumulation buffer. | |
10888 | ||
10889 | @item @code{GL_ACCUM_BLUE_BITS} | |
10890 | ||
10891 | ||
10892 | @var{params} returns one value, the number of blue bitplanes in the | |
10893 | accumulation buffer. | |
10894 | ||
10895 | @item @code{GL_ACCUM_CLEAR_VALUE} | |
10896 | ||
10897 | ||
10898 | @var{params} returns four values: the red, green, blue, and alpha values | |
10899 | used to clear the accumulation buffer. Integer values, if requested, are | |
10900 | linearly mapped from the internal floating-point representation such | |
10901 | that 1.0 returns the most positive representable integer value, and | |
10902 | @r{-1.0} returns the most negative representable integer value. The | |
10903 | initial value is (0, 0, 0, 0). See @code{glClearAccum}. | |
10904 | ||
10905 | @item @code{GL_ACCUM_GREEN_BITS} | |
10906 | ||
10907 | ||
10908 | @var{params} returns one value, the number of green bitplanes in the | |
10909 | accumulation buffer. | |
10910 | ||
10911 | @item @code{GL_ACCUM_RED_BITS} | |
10912 | ||
10913 | ||
10914 | @var{params} returns one value, the number of red bitplanes in the | |
10915 | accumulation buffer. | |
10916 | ||
10917 | @item @code{GL_ACTIVE_TEXTURE} | |
10918 | ||
10919 | ||
10920 | @var{params} returns a single value indicating the active multitexture | |
10921 | unit. The initial value is @code{GL_TEXTURE0}. See | |
10922 | @code{glActiveTexture}. | |
10923 | ||
10924 | @item @code{GL_ALIASED_POINT_SIZE_RANGE} | |
10925 | ||
10926 | ||
10927 | @var{params} returns two values, the smallest and largest supported | |
10928 | sizes for aliased points. | |
10929 | ||
10930 | @item @code{GL_ALIASED_LINE_WIDTH_RANGE} | |
10931 | ||
10932 | ||
10933 | @var{params} returns two values, the smallest and largest supported | |
10934 | widths for aliased lines. | |
10935 | ||
10936 | @item @code{GL_ALPHA_BIAS} | |
10937 | ||
10938 | ||
10939 | @var{params} returns one value, the alpha bias factor used during pixel | |
10940 | transfers. The initial value is 0. See @code{glPixelTransfer}. | |
10941 | ||
10942 | @item @code{GL_ALPHA_BITS} | |
10943 | ||
10944 | ||
10945 | @var{params} returns one value, the number of alpha bitplanes in each | |
10946 | color buffer. | |
10947 | ||
10948 | @item @code{GL_ALPHA_SCALE} | |
10949 | ||
10950 | ||
10951 | @var{params} returns one value, the alpha scale factor used during pixel | |
10952 | transfers. The initial value is 1. See @code{glPixelTransfer}. | |
10953 | ||
10954 | @item @code{GL_ALPHA_TEST} | |
10955 | ||
10956 | ||
10957 | @var{params} returns a single boolean value indicating whether alpha | |
10958 | testing of fragments is enabled. The initial value is @code{GL_FALSE}. | |
10959 | See @code{glAlphaFunc}. | |
10960 | ||
10961 | @item @code{GL_ALPHA_TEST_FUNC}@var{params} returns one value, | |
10962 | ||
10963 | ||
10964 | the symbolic name of the alpha test function. The initial value is | |
10965 | @code{GL_ALWAYS}. See @code{glAlphaFunc}. | |
10966 | ||
10967 | @item @code{GL_ALPHA_TEST_REF} | |
10968 | ||
10969 | ||
10970 | @var{params} returns one value, the reference value for the alpha test. | |
10971 | The initial value is 0. See @code{glAlphaFunc}. An integer value, if | |
10972 | requested, is linearly mapped from the internal floating-point | |
10973 | representation such that 1.0 returns the most positive representable | |
10974 | integer value, and @r{-1.0} returns the most negative representable | |
10975 | integer value. | |
10976 | ||
10977 | @item @code{GL_ARRAY_BUFFER_BINDING} | |
10978 | ||
10979 | ||
10980 | @var{params} returns a single value, the name of the buffer object | |
10981 | currently bound to the target @code{GL_ARRAY_BUFFER}. If no buffer | |
10982 | object is bound to this target, 0 is returned. The initial value is 0. | |
10983 | See @code{glBindBuffer}. | |
10984 | ||
10985 | @item @code{GL_ATTRIB_STACK_DEPTH} | |
10986 | ||
10987 | ||
10988 | @var{params} returns one value, the depth of the attribute stack. If the | |
10989 | stack is empty, 0 is returned. The initial value is 0. See | |
10990 | @code{glPushAttrib}. | |
10991 | ||
10992 | @item @code{GL_AUTO_NORMAL} | |
10993 | ||
10994 | ||
10995 | @var{params} returns a single boolean value indicating whether 2D map | |
10996 | evaluation automatically generates surface normals. The initial value is | |
10997 | @code{GL_FALSE}. See @code{glMap2}. | |
10998 | ||
10999 | @item @code{GL_AUX_BUFFERS} | |
11000 | ||
11001 | ||
11002 | @var{params} returns one value, the number of auxiliary color buffers | |
11003 | available. | |
11004 | ||
11005 | @item @code{GL_BLEND} | |
11006 | ||
11007 | ||
11008 | @var{params} returns a single boolean value indicating whether blending | |
11009 | is enabled. The initial value is @code{GL_FALSE}. See | |
11010 | @code{glBlendFunc}. | |
11011 | ||
11012 | @item @code{GL_BLEND_COLOR} | |
11013 | ||
11014 | ||
11015 | @var{params} returns four values, the red, green, blue, and alpha values | |
11016 | which are the components of the blend color. See @code{glBlendColor}. | |
11017 | ||
11018 | @item @code{GL_BLEND_DST_ALPHA} | |
11019 | ||
11020 | ||
11021 | @var{params} returns one value, the symbolic constant identifying the | |
11022 | alpha destination blend function. The initial value is @code{GL_ZERO}. | |
11023 | See @code{glBlendFunc} and @code{glBlendFuncSeparate}. | |
11024 | ||
11025 | @item @code{GL_BLEND_DST_RGB} | |
11026 | ||
11027 | ||
11028 | @var{params} returns one value, the symbolic constant identifying the | |
11029 | RGB destination blend function. The initial value is @code{GL_ZERO}. See | |
11030 | @code{glBlendFunc} and @code{glBlendFuncSeparate}. | |
11031 | ||
11032 | @item @code{GL_BLEND_EQUATION_RGB} | |
11033 | ||
11034 | ||
11035 | @var{params} returns one value, a symbolic constant indicating whether | |
11036 | the RGB blend equation is @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT}, | |
11037 | @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN} or @code{GL_MAX}. See | |
11038 | @code{glBlendEquationSeparate}. | |
11039 | ||
11040 | @item @code{GL_BLEND_EQUATION_ALPHA} | |
11041 | ||
11042 | ||
11043 | @var{params} returns one value, a symbolic constant indicating whether | |
11044 | the Alpha blend equation is @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT}, | |
11045 | @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN} or @code{GL_MAX}. See | |
11046 | @code{glBlendEquationSeparate}. | |
11047 | ||
11048 | @item @code{GL_BLEND_SRC_ALPHA} | |
11049 | ||
11050 | ||
11051 | @var{params} returns one value, the symbolic constant identifying the | |
11052 | alpha source blend function. The initial value is @code{GL_ONE}. See | |
11053 | @code{glBlendFunc} and @code{glBlendFuncSeparate}. | |
11054 | ||
11055 | @item @code{GL_BLEND_SRC_RGB} | |
11056 | ||
11057 | ||
11058 | @var{params} returns one value, the symbolic constant identifying the | |
11059 | RGB source blend function. The initial value is @code{GL_ONE}. See | |
11060 | @code{glBlendFunc} and @code{glBlendFuncSeparate}. | |
11061 | ||
11062 | @item @code{GL_BLUE_BIAS} | |
11063 | ||
11064 | ||
11065 | @var{params} returns one value, the blue bias factor used during pixel | |
11066 | transfers. The initial value is 0. See @code{glPixelTransfer}. | |
11067 | ||
11068 | @item @code{GL_BLUE_BITS} | |
11069 | ||
11070 | ||
11071 | @var{params} returns one value, the number of blue bitplanes in each | |
11072 | color buffer. | |
11073 | ||
11074 | @item @code{GL_BLUE_SCALE} | |
11075 | ||
11076 | ||
11077 | @var{params} returns one value, the blue scale factor used during pixel | |
11078 | transfers. The initial value is 1. See @code{glPixelTransfer}. | |
11079 | ||
11080 | @item @code{GL_CLIENT_ACTIVE_TEXTURE} | |
11081 | ||
11082 | ||
11083 | @var{params} returns a single integer value indicating the current | |
11084 | client active multitexture unit. The initial value is | |
11085 | @code{GL_TEXTURE0}. See @code{glClientActiveTexture}. | |
11086 | ||
11087 | @item @code{GL_CLIENT_ATTRIB_STACK_DEPTH} | |
11088 | ||
11089 | ||
11090 | @var{params} returns one value indicating the depth of the attribute | |
11091 | stack. The initial value is 0. See @code{glPushClientAttrib}. | |
11092 | ||
11093 | @item @code{GL_CLIP_PLANE}@var{i} | |
11094 | ||
11095 | ||
11096 | @var{params} returns a single boolean value indicating whether the | |
11097 | specified clipping plane is enabled. The initial value is | |
11098 | @code{GL_FALSE}. See @code{glClipPlane}. | |
11099 | ||
11100 | @item @code{GL_COLOR_ARRAY} | |
11101 | ||
11102 | ||
11103 | @var{params} returns a single boolean value indicating whether the color | |
11104 | array is enabled. The initial value is @code{GL_FALSE}. See | |
11105 | @code{glColorPointer}. | |
11106 | ||
11107 | @item @code{GL_COLOR_ARRAY_BUFFER_BINDING} | |
11108 | ||
11109 | ||
11110 | @var{params} returns a single value, the name of the buffer object | |
11111 | associated with the color array. This buffer object would have been | |
11112 | bound to the target @code{GL_ARRAY_BUFFER} at the time of the most | |
11113 | recent call to @code{glColorPointer}. If no buffer object was bound to | |
11114 | this target, 0 is returned. The initial value is 0. See | |
11115 | @code{glBindBuffer}. | |
11116 | ||
11117 | @item @code{GL_COLOR_ARRAY_SIZE} | |
11118 | ||
11119 | ||
11120 | @var{params} returns one value, the number of components per color in | |
11121 | the color array. The initial value is 4. See @code{glColorPointer}. | |
11122 | ||
11123 | @item @code{GL_COLOR_ARRAY_STRIDE} | |
11124 | ||
11125 | ||
11126 | @var{params} returns one value, the byte offset between consecutive | |
11127 | colors in the color array. The initial value is 0. See | |
11128 | @code{glColorPointer}. | |
11129 | ||
11130 | @item @code{GL_COLOR_ARRAY_TYPE} | |
11131 | ||
11132 | ||
11133 | @var{params} returns one value, the data type of each component in the | |
11134 | color array. The initial value is @code{GL_FLOAT}. See | |
11135 | @code{glColorPointer}. | |
11136 | ||
11137 | @item @code{GL_COLOR_CLEAR_VALUE} | |
11138 | ||
11139 | ||
11140 | @var{params} returns four values: the red, green, blue, and alpha values | |
11141 | used to clear the color buffers. Integer values, if requested, are | |
11142 | linearly mapped from the internal floating-point representation such | |
11143 | that 1.0 returns the most positive representable integer value, and | |
11144 | @r{-1.0} returns the most negative representable integer value. The | |
11145 | initial value is (0, 0, 0, 0). See @code{glClearColor}. | |
11146 | ||
11147 | @item @code{GL_COLOR_LOGIC_OP} | |
11148 | ||
11149 | ||
11150 | @var{params} returns a single boolean value indicating whether a | |
11151 | fragment's RGBA color values are merged into the framebuffer using a | |
11152 | logical operation. The initial value is @code{GL_FALSE}. See | |
11153 | @code{glLogicOp}. | |
11154 | ||
11155 | @item @code{GL_COLOR_MATERIAL} | |
11156 | ||
11157 | ||
11158 | @var{params} returns a single boolean value indicating whether one or | |
11159 | more material parameters are tracking the current color. The initial | |
11160 | value is @code{GL_FALSE}. See @code{glColorMaterial}. | |
11161 | ||
11162 | @item @code{GL_COLOR_MATERIAL_FACE} | |
11163 | ||
11164 | ||
11165 | @var{params} returns one value, a symbolic constant indicating which | |
11166 | materials have a parameter that is tracking the current color. The | |
11167 | initial value is @code{GL_FRONT_AND_BACK}. See @code{glColorMaterial}. | |
11168 | ||
11169 | @item @code{GL_COLOR_MATERIAL_PARAMETER} | |
11170 | ||
11171 | ||
11172 | @var{params} returns one value, a symbolic constant indicating which | |
11173 | material parameters are tracking the current color. The initial value is | |
11174 | @code{GL_AMBIENT_AND_DIFFUSE}. See @code{glColorMaterial}. | |
11175 | ||
11176 | @item @code{GL_COLOR_MATRIX} | |
11177 | ||
11178 | ||
11179 | @var{params} returns sixteen values: the color matrix on the top of the | |
11180 | color matrix stack. Initially this matrix is the identity matrix. See | |
11181 | @code{glPushMatrix}. | |
11182 | ||
11183 | @item @code{GL_COLOR_MATRIX_STACK_DEPTH} | |
11184 | ||
11185 | ||
11186 | @var{params} returns one value, the maximum supported depth of the | |
11187 | projection matrix stack. The value must be at least 2. See | |
11188 | @code{glPushMatrix}. | |
11189 | ||
11190 | @item @code{GL_COLOR_SUM} | |
11191 | ||
11192 | ||
11193 | @var{params} returns a single boolean value indicating whether primary | |
11194 | and secondary color sum is enabled. See @code{glSecondaryColor}. | |
11195 | ||
11196 | @item @code{GL_COLOR_TABLE} | |
11197 | ||
11198 | ||
11199 | @var{params} returns a single boolean value indicating whether the color | |
11200 | table lookup is enabled. See @code{glColorTable}. | |
11201 | ||
11202 | @item @code{GL_COLOR_WRITEMASK} | |
11203 | ||
11204 | ||
11205 | @var{params} returns four boolean values: the red, green, blue, and | |
11206 | alpha write enables for the color buffers. The initial value is | |
11207 | (@code{GL_TRUE}, @code{GL_TRUE}, @code{GL_TRUE}, @code{GL_TRUE}). See | |
11208 | @code{glColorMask}. | |
11209 | ||
11210 | @item @code{GL_COMPRESSED_TEXTURE_FORMATS} | |
11211 | ||
11212 | ||
11213 | @var{params} returns a list of symbolic constants of length | |
11214 | @code{GL_NUM_COMPRESSED_TEXTURE_FORMATS} indicating which compressed | |
11215 | texture formats are available. See @code{glCompressedTexImage2D}. | |
11216 | ||
11217 | @item @code{GL_CONVOLUTION_1D} | |
11218 | ||
11219 | ||
11220 | @var{params} returns a single boolean value indicating whether 1D | |
11221 | convolution is enabled. The initial value is @code{GL_FALSE}. See | |
11222 | @code{glConvolutionFilter1D}. | |
11223 | ||
11224 | @item @code{GL_CONVOLUTION_2D} | |
11225 | ||
11226 | ||
11227 | @var{params} returns a single boolean value indicating whether 2D | |
11228 | convolution is enabled. The initial value is @code{GL_FALSE}. See | |
11229 | @code{glConvolutionFilter2D}. | |
11230 | ||
11231 | @item @code{GL_CULL_FACE} | |
11232 | ||
11233 | ||
11234 | @var{params} returns a single boolean value indicating whether polygon | |
11235 | culling is enabled. The initial value is @code{GL_FALSE}. See | |
11236 | @code{glCullFace}. | |
11237 | ||
11238 | @item @code{GL_CULL_FACE_MODE} | |
11239 | ||
11240 | ||
11241 | @var{params} returns one value, a symbolic constant indicating which | |
11242 | polygon faces are to be culled. The initial value is @code{GL_BACK}. See | |
11243 | @code{glCullFace}. | |
11244 | ||
11245 | @item @code{GL_CURRENT_COLOR} | |
11246 | ||
11247 | ||
11248 | @var{params} returns four values: the red, green, blue, and alpha values | |
11249 | of the current color. Integer values, if requested, are linearly mapped | |
11250 | from the internal floating-point representation such that 1.0 returns | |
11251 | the most positive representable integer value, and @r{-1.0} returns the | |
11252 | most negative representable integer value. The initial value is (1, 1, | |
11253 | 1, 1). See @code{glColor}. | |
11254 | ||
11255 | @item @code{GL_CURRENT_FOG_COORD} | |
11256 | ||
11257 | ||
11258 | @var{params} returns one value, the current fog coordinate. The initial | |
11259 | value is 0. See @code{glFogCoord}. | |
11260 | ||
11261 | @item @code{GL_CURRENT_INDEX} | |
11262 | ||
11263 | ||
11264 | @var{params} returns one value, the current color index. The initial | |
11265 | value is 1. See @code{glIndex}. | |
11266 | ||
11267 | @item @code{GL_CURRENT_NORMAL} | |
11268 | ||
11269 | ||
11270 | @var{params} returns three values: the @var{x}, @var{y}, and @var{z} | |
11271 | values of the current normal. Integer values, if requested, are linearly | |
11272 | mapped from the internal floating-point representation such that 1.0 | |
11273 | returns the most positive representable integer value, and @r{-1.0} | |
11274 | returns the most negative representable integer value. The initial value | |
11275 | is (0, 0, 1). See @code{glNormal}. | |
11276 | ||
11277 | @item @code{GL_CURRENT_PROGRAM} | |
11278 | ||
11279 | ||
11280 | @var{params} returns one value, the name of the program object that is | |
11281 | currently active, or 0 if no program object is active. See | |
11282 | @code{glUseProgram}. | |
11283 | ||
11284 | @item @code{GL_CURRENT_RASTER_COLOR} | |
11285 | ||
11286 | ||
11287 | @var{params} returns four values: the red, green, blue, and alpha color | |
11288 | values of the current raster position. Integer values, if requested, are | |
11289 | linearly mapped from the internal floating-point representation such | |
11290 | that 1.0 returns the most positive representable integer value, and | |
11291 | @r{-1.0} returns the most negative representable integer value. The | |
11292 | initial value is (1, 1, 1, 1). See @code{glRasterPos}. | |
11293 | ||
11294 | @item @code{GL_CURRENT_RASTER_DISTANCE} | |
11295 | ||
11296 | ||
11297 | @var{params} returns one value, the distance from the eye to the current | |
11298 | raster position. The initial value is 0. See @code{glRasterPos}. | |
11299 | ||
11300 | @item @code{GL_CURRENT_RASTER_INDEX} | |
11301 | ||
11302 | ||
11303 | @var{params} returns one value, the color index of the current raster | |
11304 | position. The initial value is 1. See @code{glRasterPos}. | |
11305 | ||
11306 | @item @code{GL_CURRENT_RASTER_POSITION} | |
11307 | ||
11308 | ||
11309 | @var{params} returns four values: the @var{x}, @var{y}, @var{z}, and | |
11310 | @var{w} components of the current raster position. @var{x}, @var{y}, and | |
11311 | @var{z} are in window coordinates, and @var{w} is in clip coordinates. | |
11312 | The initial value is (0, 0, 0, 1). See @code{glRasterPos}. | |
11313 | ||
11314 | @item @code{GL_CURRENT_RASTER_POSITION_VALID} | |
11315 | ||
11316 | ||
11317 | @var{params} returns a single boolean value indicating whether the | |
11318 | current raster position is valid. The initial value is @code{GL_TRUE}. | |
11319 | See @code{glRasterPos}. | |
11320 | ||
11321 | @item @code{GL_CURRENT_RASTER_SECONDARY_COLOR} | |
11322 | ||
11323 | ||
11324 | @var{params} returns four values: the red, green, blue, and alpha | |
11325 | secondary color values of the current raster position. Integer values, | |
11326 | if requested, are linearly mapped from the internal floating-point | |
11327 | representation such that 1.0 returns the most positive representable | |
11328 | integer value, and @r{-1.0} returns the most negative representable | |
11329 | integer value. The initial value is (1, 1, 1, 1). See | |
11330 | @code{glRasterPos}. | |
11331 | ||
11332 | @item @code{GL_CURRENT_RASTER_TEXTURE_COORDS} | |
11333 | ||
11334 | ||
11335 | @var{params} returns four values: the @var{s}, @var{t}, @var{r}, and | |
11336 | @var{q} texture coordinates of the current raster position. The initial | |
11337 | value is (0, 0, 0, 1). See @code{glRasterPos} and | |
11338 | @code{glMultiTexCoord}. | |
11339 | ||
11340 | @item @code{GL_CURRENT_SECONDARY_COLOR} | |
11341 | ||
11342 | ||
11343 | @var{params} returns four values: the red, green, blue, and alpha values | |
11344 | of the current secondary color. Integer values, if requested, are | |
11345 | linearly mapped from the internal floating-point representation such | |
11346 | that 1.0 returns the most positive representable integer value, and | |
11347 | @r{-1.0} returns the most negative representable integer value. The | |
11348 | initial value is (0, 0, 0, 0). See @code{glSecondaryColor}. | |
11349 | ||
11350 | @item @code{GL_CURRENT_TEXTURE_COORDS} | |
11351 | ||
11352 | ||
11353 | @var{params} returns four values: the @var{s}, @var{t}, @var{r}, and | |
11354 | @var{q} current texture coordinates. The initial value is (0, 0, 0, 1). | |
11355 | See @code{glMultiTexCoord}. | |
11356 | ||
11357 | @item @code{GL_DEPTH_BIAS} | |
11358 | ||
11359 | ||
11360 | @var{params} returns one value, the depth bias factor used during pixel | |
11361 | transfers. The initial value is 0. See @code{glPixelTransfer}. | |
11362 | ||
11363 | @item @code{GL_DEPTH_BITS} | |
11364 | ||
11365 | ||
11366 | @var{params} returns one value, the number of bitplanes in the depth | |
11367 | buffer. | |
11368 | ||
11369 | @item @code{GL_DEPTH_CLEAR_VALUE} | |
11370 | ||
11371 | ||
11372 | @var{params} returns one value, the value that is used to clear the | |
11373 | depth buffer. Integer values, if requested, are linearly mapped from the | |
11374 | internal floating-point representation such that 1.0 returns the most | |
11375 | positive representable integer value, and @r{-1.0} returns the most | |
11376 | negative representable integer value. The initial value is 1. See | |
11377 | @code{glClearDepth}. | |
11378 | ||
11379 | @item @code{GL_DEPTH_FUNC} | |
11380 | ||
11381 | ||
11382 | @var{params} returns one value, the symbolic constant that indicates the | |
11383 | depth comparison function. The initial value is @code{GL_LESS}. See | |
11384 | @code{glDepthFunc}. | |
11385 | ||
11386 | @item @code{GL_DEPTH_RANGE} | |
11387 | ||
11388 | ||
11389 | @var{params} returns two values: the near and far mapping limits for the | |
11390 | depth buffer. Integer values, if requested, are linearly mapped from the | |
11391 | internal floating-point representation such that 1.0 returns the most | |
11392 | positive representable integer value, and @r{-1.0} returns the most | |
11393 | negative representable integer value. The initial value is (0, 1). See | |
11394 | @code{glDepthRange}. | |
11395 | ||
11396 | @item @code{GL_DEPTH_SCALE} | |
11397 | ||
11398 | ||
11399 | @var{params} returns one value, the depth scale factor used during pixel | |
11400 | transfers. The initial value is 1. See @code{glPixelTransfer}. | |
11401 | ||
11402 | @item @code{GL_DEPTH_TEST} | |
11403 | ||
11404 | ||
11405 | @var{params} returns a single boolean value indicating whether depth | |
11406 | testing of fragments is enabled. The initial value is @code{GL_FALSE}. | |
11407 | See @code{glDepthFunc} and @code{glDepthRange}. | |
11408 | ||
11409 | @item @code{GL_DEPTH_WRITEMASK} | |
11410 | ||
11411 | ||
11412 | @var{params} returns a single boolean value indicating if the depth | |
11413 | buffer is enabled for writing. The initial value is @code{GL_TRUE}. See | |
11414 | @code{glDepthMask}. | |
11415 | ||
11416 | @item @code{GL_DITHER} | |
11417 | ||
11418 | ||
11419 | @var{params} returns a single boolean value indicating whether dithering | |
11420 | of fragment colors and indices is enabled. The initial value is | |
11421 | @code{GL_TRUE}. | |
11422 | ||
11423 | @item @code{GL_DOUBLEBUFFER} | |
11424 | ||
11425 | ||
11426 | @var{params} returns a single boolean value indicating whether double | |
11427 | buffering is supported. | |
11428 | ||
11429 | @item @code{GL_DRAW_BUFFER} | |
11430 | ||
11431 | ||
11432 | @var{params} returns one value, a symbolic constant indicating which | |
11433 | buffers are being drawn to. See @code{glDrawBuffer}. The initial value | |
11434 | is @code{GL_BACK} if there are back buffers, otherwise it is | |
11435 | @code{GL_FRONT}. | |
11436 | ||
11437 | @item @code{GL_DRAW_BUFFER}@var{i} | |
11438 | ||
11439 | ||
11440 | @var{params} returns one value, a symbolic constant indicating which | |
11441 | buffers are being drawn to by the corresponding output color. See | |
11442 | @code{glDrawBuffers}. The initial value of @code{GL_DRAW_BUFFER0} is | |
11443 | @code{GL_BACK} if there are back buffers, otherwise it is | |
11444 | @code{GL_FRONT}. The initial values of draw buffers for all other output | |
11445 | colors is @code{GL_NONE}. | |
11446 | ||
11447 | @item @code{GL_EDGE_FLAG} | |
11448 | ||
11449 | ||
11450 | @var{params} returns a single boolean value indicating whether the | |
11451 | current edge flag is @code{GL_TRUE} or @code{GL_FALSE}. The initial | |
11452 | value is @code{GL_TRUE}. See @code{glEdgeFlag}. | |
11453 | ||
11454 | @item @code{GL_EDGE_FLAG_ARRAY} | |
11455 | ||
11456 | ||
11457 | @var{params} returns a single boolean value indicating whether the edge | |
11458 | flag array is enabled. The initial value is @code{GL_FALSE}. See | |
11459 | @code{glEdgeFlagPointer}. | |
11460 | ||
11461 | @item @code{GL_EDGE_FLAG_ARRAY_BUFFER_BINDING} | |
11462 | ||
11463 | ||
11464 | @var{params} returns a single value, the name of the buffer object | |
11465 | associated with the edge flag array. This buffer object would have been | |
11466 | bound to the target @code{GL_ARRAY_BUFFER} at the time of the most | |
11467 | recent call to @code{glEdgeFlagPointer}. If no buffer object was bound | |
11468 | to this target, 0 is returned. The initial value is 0. See | |
11469 | @code{glBindBuffer}. | |
11470 | ||
11471 | @item @code{GL_EDGE_FLAG_ARRAY_STRIDE} | |
11472 | ||
11473 | ||
11474 | @var{params} returns one value, the byte offset between consecutive edge | |
11475 | flags in the edge flag array. The initial value is 0. See | |
11476 | @code{glEdgeFlagPointer}. | |
11477 | ||
11478 | @item @code{GL_ELEMENT_ARRAY_BUFFER_BINDING} | |
11479 | ||
11480 | ||
11481 | @var{params} returns a single value, the name of the buffer object | |
11482 | currently bound to the target @code{GL_ELEMENT_ARRAY_BUFFER}. If no | |
11483 | buffer object is bound to this target, 0 is returned. The initial value | |
11484 | is 0. See @code{glBindBuffer}. | |
11485 | ||
11486 | @item @code{GL_FEEDBACK_BUFFER_SIZE} | |
11487 | ||
11488 | ||
11489 | @var{params} returns one value, the size of the feedback buffer. See | |
11490 | @code{glFeedbackBuffer}. | |
11491 | ||
11492 | @item @code{GL_FEEDBACK_BUFFER_TYPE} | |
11493 | ||
11494 | ||
11495 | @var{params} returns one value, the type of the feedback buffer. See | |
11496 | @code{glFeedbackBuffer}. | |
11497 | ||
11498 | @item @code{GL_FOG} | |
11499 | ||
11500 | ||
11501 | @var{params} returns a single boolean value indicating whether fogging | |
11502 | is enabled. The initial value is @code{GL_FALSE}. See @code{glFog}. | |
11503 | ||
11504 | @item @code{GL_FOG_COORD_ARRAY} | |
11505 | ||
11506 | ||
11507 | @var{params} returns a single boolean value indicating whether the fog | |
11508 | coordinate array is enabled. The initial value is @code{GL_FALSE}. See | |
11509 | @code{glFogCoordPointer}. | |
11510 | ||
11511 | @item @code{GL_FOG_COORD_ARRAY_BUFFER_BINDING} | |
11512 | ||
11513 | ||
11514 | @var{params} returns a single value, the name of the buffer object | |
11515 | associated with the fog coordinate array. This buffer object would have | |
11516 | been bound to the target @code{GL_ARRAY_BUFFER} at the time of the most | |
11517 | recent call to @code{glFogCoordPointer}. If no buffer object was bound | |
11518 | to this target, 0 is returned. The initial value is 0. See | |
11519 | @code{glBindBuffer}. | |
11520 | ||
11521 | @item @code{GL_FOG_COORD_ARRAY_STRIDE} | |
11522 | ||
11523 | ||
11524 | @var{params} returns one value, the byte offset between consecutive fog | |
11525 | coordinates in the fog coordinate array. The initial value is 0. See | |
11526 | @code{glFogCoordPointer}. | |
11527 | ||
11528 | @item @code{GL_FOG_COORD_ARRAY_TYPE} | |
11529 | ||
11530 | ||
11531 | @var{params} returns one value, the type of the fog coordinate array. | |
11532 | The initial value is @code{GL_FLOAT}. See @code{glFogCoordPointer}. | |
11533 | ||
11534 | @item @code{GL_FOG_COORD_SRC} | |
11535 | ||
11536 | ||
11537 | @var{params} returns one value, a symbolic constant indicating the | |
11538 | source of the fog coordinate. The initial value is | |
11539 | @code{GL_FRAGMENT_DEPTH}. See @code{glFog}. | |
11540 | ||
11541 | @item @code{GL_FOG_COLOR} | |
11542 | ||
11543 | ||
11544 | @var{params} returns four values: the red, green, blue, and alpha | |
11545 | components of the fog color. Integer values, if requested, are linearly | |
11546 | mapped from the internal floating-point representation such that 1.0 | |
11547 | returns the most positive representable integer value, and @r{-1.0} | |
11548 | returns the most negative representable integer value. The initial value | |
11549 | is (0, 0, 0, 0). See @code{glFog}. | |
11550 | ||
11551 | @item @code{GL_FOG_DENSITY} | |
11552 | ||
11553 | ||
11554 | @var{params} returns one value, the fog density parameter. The initial | |
11555 | value is 1. See @code{glFog}. | |
11556 | ||
11557 | @item @code{GL_FOG_END} | |
11558 | ||
11559 | ||
11560 | @var{params} returns one value, the end factor for the linear fog | |
11561 | equation. The initial value is 1. See @code{glFog}. | |
11562 | ||
11563 | @item @code{GL_FOG_HINT} | |
11564 | ||
11565 | ||
11566 | @var{params} returns one value, a symbolic constant indicating the mode | |
11567 | of the fog hint. The initial value is @code{GL_DONT_CARE}. See | |
11568 | @code{glHint}. | |
11569 | ||
11570 | @item @code{GL_FOG_INDEX} | |
11571 | ||
11572 | ||
11573 | @var{params} returns one value, the fog color index. The initial value | |
11574 | is 0. See @code{glFog}. | |
11575 | ||
11576 | @item @code{GL_FOG_MODE} | |
11577 | ||
11578 | ||
11579 | @var{params} returns one value, a symbolic constant indicating which fog | |
11580 | equation is selected. The initial value is @code{GL_EXP}. See | |
11581 | @code{glFog}. | |
11582 | ||
11583 | @item @code{GL_FOG_START} | |
11584 | ||
11585 | ||
11586 | @var{params} returns one value, the start factor for the linear fog | |
11587 | equation. The initial value is 0. See @code{glFog}. | |
11588 | ||
11589 | @item @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT} | |
11590 | ||
11591 | ||
11592 | @var{params} returns one value, a symbolic constant indicating the mode | |
11593 | of the derivative accuracy hint for fragment shaders. The initial value | |
11594 | is @code{GL_DONT_CARE}. See @code{glHint}. | |
11595 | ||
11596 | @item @code{GL_FRONT_FACE} | |
11597 | ||
11598 | ||
11599 | @var{params} returns one value, a symbolic constant indicating whether | |
11600 | clockwise or counterclockwise polygon winding is treated as | |
11601 | front-facing. The initial value is @code{GL_CCW}. See | |
11602 | @code{glFrontFace}. | |
11603 | ||
11604 | @item @code{GL_GENERATE_MIPMAP_HINT} | |
11605 | ||
11606 | ||
11607 | @var{params} returns one value, a symbolic constant indicating the mode | |
11608 | of the mipmap generation filtering hint. The initial value is | |
11609 | @code{GL_DONT_CARE}. See @code{glHint}. | |
11610 | ||
11611 | @item @code{GL_GREEN_BIAS} | |
11612 | ||
11613 | ||
11614 | @var{params} returns one value, the green bias factor used during pixel | |
11615 | transfers. The initial value is 0. | |
11616 | ||
11617 | @item @code{GL_GREEN_BITS} | |
11618 | ||
11619 | ||
11620 | @var{params} returns one value, the number of green bitplanes in each | |
11621 | color buffer. | |
11622 | ||
11623 | @item @code{GL_GREEN_SCALE} | |
11624 | ||
11625 | ||
11626 | @var{params} returns one value, the green scale factor used during pixel | |
11627 | transfers. The initial value is 1. See @code{glPixelTransfer}. | |
11628 | ||
11629 | @item @code{GL_HISTOGRAM} | |
11630 | ||
11631 | ||
11632 | @var{params} returns a single boolean value indicating whether histogram | |
11633 | is enabled. The initial value is @code{GL_FALSE}. See | |
11634 | @code{glHistogram}. | |
11635 | ||
11636 | @item @code{GL_INDEX_ARRAY} | |
11637 | ||
11638 | ||
11639 | @var{params} returns a single boolean value indicating whether the color | |
11640 | index array is enabled. The initial value is @code{GL_FALSE}. See | |
11641 | @code{glIndexPointer}. | |
11642 | ||
11643 | @item @code{GL_INDEX_ARRAY_BUFFER_BINDING} | |
11644 | ||
11645 | ||
11646 | @var{params} returns a single value, the name of the buffer object | |
11647 | associated with the color index array. This buffer object would have | |
11648 | been bound to the target @code{GL_ARRAY_BUFFER} at the time of the most | |
11649 | recent call to @code{glIndexPointer}. If no buffer object was bound to | |
11650 | this target, 0 is returned. The initial value is 0. See | |
11651 | @code{glBindBuffer}. | |
11652 | ||
11653 | @item @code{GL_INDEX_ARRAY_STRIDE} | |
11654 | ||
11655 | ||
11656 | @var{params} returns one value, the byte offset between consecutive | |
11657 | color indexes in the color index array. The initial value is 0. See | |
11658 | @code{glIndexPointer}. | |
11659 | ||
11660 | @item @code{GL_INDEX_ARRAY_TYPE} | |
11661 | ||
11662 | ||
11663 | @var{params} returns one value, the data type of indexes in the color | |
11664 | index array. The initial value is @code{GL_FLOAT}. See | |
11665 | @code{glIndexPointer}. | |
11666 | ||
11667 | @item @code{GL_INDEX_BITS} | |
11668 | ||
11669 | ||
11670 | @var{params} returns one value, the number of bitplanes in each color | |
11671 | index buffer. | |
11672 | ||
11673 | @item @code{GL_INDEX_CLEAR_VALUE} | |
11674 | ||
11675 | ||
11676 | @var{params} returns one value, the color index used to clear the color | |
11677 | index buffers. The initial value is 0. See @code{glClearIndex}. | |
11678 | ||
11679 | @item @code{GL_INDEX_LOGIC_OP} | |
11680 | ||
11681 | ||
11682 | @var{params} returns a single boolean value indicating whether a | |
11683 | fragment's index values are merged into the framebuffer using a logical | |
11684 | operation. The initial value is @code{GL_FALSE}. See @code{glLogicOp}. | |
11685 | ||
11686 | @item @code{GL_INDEX_MODE} | |
11687 | ||
11688 | ||
11689 | @var{params} returns a single boolean value indicating whether the GL is | |
11690 | in color index mode (@code{GL_TRUE}) or RGBA mode (@code{GL_FALSE}). | |
11691 | ||
11692 | @item @code{GL_INDEX_OFFSET} | |
11693 | ||
11694 | ||
11695 | @var{params} returns one value, the offset added to color and stencil | |
11696 | indices during pixel transfers. The initial value is 0. See | |
11697 | @code{glPixelTransfer}. | |
11698 | ||
11699 | @item @code{GL_INDEX_SHIFT} | |
11700 | ||
11701 | ||
11702 | @var{params} returns one value, the amount that color and stencil | |
11703 | indices are shifted during pixel transfers. The initial value is 0. See | |
11704 | @code{glPixelTransfer}. | |
11705 | ||
11706 | @item @code{GL_INDEX_WRITEMASK} | |
11707 | ||
11708 | ||
11709 | @var{params} returns one value, a mask indicating which bitplanes of | |
11710 | each color index buffer can be written. The initial value is all 1's. | |
11711 | See @code{glIndexMask}. | |
11712 | ||
11713 | @item @code{GL_LIGHT}@var{i} | |
11714 | ||
11715 | ||
11716 | @var{params} returns a single boolean value indicating whether the | |
11717 | specified light is enabled. The initial value is @code{GL_FALSE}. See | |
11718 | @code{glLight} and @code{glLightModel}. | |
11719 | ||
11720 | @item @code{GL_LIGHTING} | |
11721 | ||
11722 | ||
11723 | @var{params} returns a single boolean value indicating whether lighting | |
11724 | is enabled. The initial value is @code{GL_FALSE}. See | |
11725 | @code{glLightModel}. | |
11726 | ||
11727 | @item @code{GL_LIGHT_MODEL_AMBIENT} | |
11728 | ||
11729 | ||
11730 | @var{params} returns four values: the red, green, blue, and alpha | |
11731 | components of the ambient intensity of the entire scene. Integer values, | |
11732 | if requested, are linearly mapped from the internal floating-point | |
11733 | representation such that 1.0 returns the most positive representable | |
11734 | integer value, and @r{-1.0} returns the most negative representable | |
11735 | integer value. The initial value is (0.2, 0.2, 0.2, 1.0). See | |
11736 | @code{glLightModel}. | |
11737 | ||
11738 | @item @code{GL_LIGHT_MODEL_COLOR_CONTROL} | |
11739 | ||
11740 | ||
11741 | @var{params} returns single enumerated value indicating whether specular | |
11742 | reflection calculations are separated from normal lighting computations. | |
11743 | The initial value is @code{GL_SINGLE_COLOR}. | |
11744 | ||
11745 | @item @code{GL_LIGHT_MODEL_LOCAL_VIEWER} | |
11746 | ||
11747 | ||
11748 | @var{params} returns a single boolean value indicating whether specular | |
11749 | reflection calculations treat the viewer as being local to the scene. | |
11750 | The initial value is @code{GL_FALSE}. See @code{glLightModel}. | |
11751 | ||
11752 | @item @code{GL_LIGHT_MODEL_TWO_SIDE} | |
11753 | ||
11754 | ||
11755 | @var{params} returns a single boolean value indicating whether separate | |
11756 | materials are used to compute lighting for front- and back-facing | |
11757 | polygons. The initial value is @code{GL_FALSE}. See @code{glLightModel}. | |
11758 | ||
11759 | @item @code{GL_LINE_SMOOTH} | |
11760 | ||
11761 | ||
11762 | @var{params} returns a single boolean value indicating whether | |
11763 | antialiasing of lines is enabled. The initial value is @code{GL_FALSE}. | |
11764 | See @code{glLineWidth}. | |
11765 | ||
11766 | @item @code{GL_LINE_SMOOTH_HINT} | |
11767 | ||
11768 | ||
11769 | @var{params} returns one value, a symbolic constant indicating the mode | |
11770 | of the line antialiasing hint. The initial value is @code{GL_DONT_CARE}. | |
11771 | See @code{glHint}. | |
11772 | ||
11773 | @item @code{GL_LINE_STIPPLE} | |
11774 | ||
11775 | ||
11776 | @var{params} returns a single boolean value indicating whether stippling | |
11777 | of lines is enabled. The initial value is @code{GL_FALSE}. See | |
11778 | @code{glLineStipple}. | |
11779 | ||
11780 | @item @code{GL_LINE_STIPPLE_PATTERN} | |
11781 | ||
11782 | ||
11783 | @var{params} returns one value, the 16-bit line stipple pattern. The | |
11784 | initial value is all 1's. See @code{glLineStipple}. | |
11785 | ||
11786 | @item @code{GL_LINE_STIPPLE_REPEAT} | |
11787 | ||
11788 | ||
11789 | @var{params} returns one value, the line stipple repeat factor. The | |
11790 | initial value is 1. See @code{glLineStipple}. | |
11791 | ||
11792 | @item @code{GL_LINE_WIDTH} | |
11793 | ||
11794 | ||
11795 | @var{params} returns one value, the line width as specified with | |
11796 | @code{glLineWidth}. The initial value is 1. | |
11797 | ||
11798 | @item @code{GL_LINE_WIDTH_GRANULARITY} | |
11799 | ||
11800 | ||
11801 | @var{params} returns one value, the width difference between adjacent | |
11802 | supported widths for antialiased lines. See @code{glLineWidth}. | |
11803 | ||
11804 | @item @code{GL_LINE_WIDTH_RANGE} | |
11805 | ||
11806 | ||
11807 | @var{params} returns two values: the smallest and largest supported | |
11808 | widths for antialiased lines. See @code{glLineWidth}. | |
11809 | ||
11810 | @item @code{GL_LIST_BASE} | |
11811 | ||
11812 | ||
11813 | @var{params} returns one value, the base offset added to all names in | |
11814 | arrays presented to @code{glCallLists}. The initial value is 0. See | |
11815 | @code{glListBase}. | |
11816 | ||
11817 | @item @code{GL_LIST_INDEX} | |
11818 | ||
11819 | ||
11820 | @var{params} returns one value, the name of the display list currently | |
11821 | under construction. 0 is returned if no display list is currently under | |
11822 | construction. The initial value is 0. See @code{glNewList}. | |
11823 | ||
11824 | @item @code{GL_LIST_MODE} | |
11825 | ||
11826 | ||
11827 | @var{params} returns one value, a symbolic constant indicating the | |
11828 | construction mode of the display list currently under construction. The | |
11829 | initial value is 0. See @code{glNewList}. | |
11830 | ||
11831 | @item @code{GL_LOGIC_OP_MODE} | |
11832 | ||
11833 | ||
11834 | @var{params} returns one value, a symbolic constant indicating the | |
11835 | selected logic operation mode. The initial value is @code{GL_COPY}. See | |
11836 | @code{glLogicOp}. | |
11837 | ||
11838 | @item @code{GL_MAP1_COLOR_4} | |
11839 | ||
11840 | ||
11841 | @var{params} returns a single boolean value indicating whether 1D | |
11842 | evaluation generates colors. The initial value is @code{GL_FALSE}. See | |
11843 | @code{glMap1}. | |
11844 | ||
11845 | @item @code{GL_MAP1_GRID_DOMAIN} | |
11846 | ||
11847 | ||
11848 | @var{params} returns two values: the endpoints of the 1D map's grid | |
11849 | domain. The initial value is (0, 1). See @code{glMapGrid}. | |
11850 | ||
11851 | @item @code{GL_MAP1_GRID_SEGMENTS} | |
11852 | ||
11853 | ||
11854 | @var{params} returns one value, the number of partitions in the 1D map's | |
11855 | grid domain. The initial value is 1. See @code{glMapGrid}. | |
11856 | ||
11857 | @item @code{GL_MAP1_INDEX} | |
11858 | ||
11859 | ||
11860 | @var{params} returns a single boolean value indicating whether 1D | |
11861 | evaluation generates color indices. The initial value is | |
11862 | @code{GL_FALSE}. See @code{glMap1}. | |
11863 | ||
11864 | @item @code{GL_MAP1_NORMAL} | |
11865 | ||
11866 | ||
11867 | @var{params} returns a single boolean value indicating whether 1D | |
11868 | evaluation generates normals. The initial value is @code{GL_FALSE}. See | |
11869 | @code{glMap1}. | |
11870 | ||
11871 | @item @code{GL_MAP1_TEXTURE_COORD_1} | |
11872 | ||
11873 | ||
11874 | @var{params} returns a single boolean value indicating whether 1D | |
11875 | evaluation generates 1D texture coordinates. The initial value is | |
11876 | @code{GL_FALSE}. See @code{glMap1}. | |
11877 | ||
11878 | @item @code{GL_MAP1_TEXTURE_COORD_2} | |
11879 | ||
11880 | ||
11881 | @var{params} returns a single boolean value indicating whether 1D | |
11882 | evaluation generates 2D texture coordinates. The initial value is | |
11883 | @code{GL_FALSE}. See @code{glMap1}. | |
11884 | ||
11885 | @item @code{GL_MAP1_TEXTURE_COORD_3} | |
11886 | ||
11887 | ||
11888 | @var{params} returns a single boolean value indicating whether 1D | |
11889 | evaluation generates 3D texture coordinates. The initial value is | |
11890 | @code{GL_FALSE}. See @code{glMap1}. | |
11891 | ||
11892 | @item @code{GL_MAP1_TEXTURE_COORD_4} | |
11893 | ||
11894 | ||
11895 | @var{params} returns a single boolean value indicating whether 1D | |
11896 | evaluation generates 4D texture coordinates. The initial value is | |
11897 | @code{GL_FALSE}. See @code{glMap1}. | |
11898 | ||
11899 | @item @code{GL_MAP1_VERTEX_3} | |
11900 | ||
11901 | ||
11902 | @var{params} returns a single boolean value indicating whether 1D | |
11903 | evaluation generates 3D vertex coordinates. The initial value is | |
11904 | @code{GL_FALSE}. See @code{glMap1}. | |
11905 | ||
11906 | @item @code{GL_MAP1_VERTEX_4} | |
11907 | ||
11908 | ||
11909 | @var{params} returns a single boolean value indicating whether 1D | |
11910 | evaluation generates 4D vertex coordinates. The initial value is | |
11911 | @code{GL_FALSE}. See @code{glMap1}. | |
11912 | ||
11913 | @item @code{GL_MAP2_COLOR_4} | |
11914 | ||
11915 | ||
11916 | @var{params} returns a single boolean value indicating whether 2D | |
11917 | evaluation generates colors. The initial value is @code{GL_FALSE}. See | |
11918 | @code{glMap2}. | |
11919 | ||
11920 | @item @code{GL_MAP2_GRID_DOMAIN} | |
11921 | ||
11922 | ||
11923 | @var{params} returns four values: the endpoints of the 2D map's | |
11924 | @r{@var{i}} and @r{@var{j}} grid domains. The initial value is (0,1; | |
11925 | 0,1). See @code{glMapGrid}. | |
11926 | ||
11927 | @item @code{GL_MAP2_GRID_SEGMENTS} | |
11928 | ||
11929 | ||
11930 | @var{params} returns two values: the number of partitions in the 2D | |
11931 | map's @r{@var{i}} and @r{@var{j}} grid domains. The initial value is | |
11932 | (1,1). See @code{glMapGrid}. | |
11933 | ||
11934 | @item @code{GL_MAP2_INDEX} | |
11935 | ||
11936 | ||
11937 | @var{params} returns a single boolean value indicating whether 2D | |
11938 | evaluation generates color indices. The initial value is | |
11939 | @code{GL_FALSE}. See @code{glMap2}. | |
11940 | ||
11941 | @item @code{GL_MAP2_NORMAL} | |
11942 | ||
11943 | ||
11944 | @var{params} returns a single boolean value indicating whether 2D | |
11945 | evaluation generates normals. The initial value is @code{GL_FALSE}. See | |
11946 | @code{glMap2}. | |
11947 | ||
11948 | @item @code{GL_MAP2_TEXTURE_COORD_1} | |
11949 | ||
11950 | ||
11951 | @var{params} returns a single boolean value indicating whether 2D | |
11952 | evaluation generates 1D texture coordinates. The initial value is | |
11953 | @code{GL_FALSE}. See @code{glMap2}. | |
11954 | ||
11955 | @item @code{GL_MAP2_TEXTURE_COORD_2} | |
11956 | ||
11957 | ||
11958 | @var{params} returns a single boolean value indicating whether 2D | |
11959 | evaluation generates 2D texture coordinates. The initial value is | |
11960 | @code{GL_FALSE}. See @code{glMap2}. | |
11961 | ||
11962 | @item @code{GL_MAP2_TEXTURE_COORD_3} | |
11963 | ||
11964 | ||
11965 | @var{params} returns a single boolean value indicating whether 2D | |
11966 | evaluation generates 3D texture coordinates. The initial value is | |
11967 | @code{GL_FALSE}. See @code{glMap2}. | |
11968 | ||
11969 | @item @code{GL_MAP2_TEXTURE_COORD_4} | |
11970 | ||
11971 | ||
11972 | @var{params} returns a single boolean value indicating whether 2D | |
11973 | evaluation generates 4D texture coordinates. The initial value is | |
11974 | @code{GL_FALSE}. See @code{glMap2}. | |
11975 | ||
11976 | @item @code{GL_MAP2_VERTEX_3} | |
11977 | ||
11978 | ||
11979 | @var{params} returns a single boolean value indicating whether 2D | |
11980 | evaluation generates 3D vertex coordinates. The initial value is | |
11981 | @code{GL_FALSE}. See @code{glMap2}. | |
11982 | ||
11983 | @item @code{GL_MAP2_VERTEX_4} | |
11984 | ||
11985 | ||
11986 | @var{params} returns a single boolean value indicating whether 2D | |
11987 | evaluation generates 4D vertex coordinates. The initial value is | |
11988 | @code{GL_FALSE}. See @code{glMap2}. | |
11989 | ||
11990 | @item @code{GL_MAP_COLOR} | |
11991 | ||
11992 | ||
11993 | @var{params} returns a single boolean value indicating if colors and | |
11994 | color indices are to be replaced by table lookup during pixel transfers. | |
11995 | The initial value is @code{GL_FALSE}. See @code{glPixelTransfer}. | |
11996 | ||
11997 | @item @code{GL_MAP_STENCIL} | |
11998 | ||
11999 | ||
12000 | @var{params} returns a single boolean value indicating if stencil | |
12001 | indices are to be replaced by table lookup during pixel transfers. The | |
12002 | initial value is @code{GL_FALSE}. See @code{glPixelTransfer}. | |
12003 | ||
12004 | @item @code{GL_MATRIX_MODE} | |
12005 | ||
12006 | ||
12007 | @var{params} returns one value, a symbolic constant indicating which | |
12008 | matrix stack is currently the target of all matrix operations. The | |
12009 | initial value is @code{GL_MODELVIEW}. See @code{glMatrixMode}. | |
12010 | ||
12011 | @item @code{GL_MAX_3D_TEXTURE_SIZE} | |
12012 | ||
12013 | ||
12014 | @var{params} returns one value, a rough estimate of the largest 3D | |
12015 | texture that the GL can handle. The value must be at least 16. If the GL | |
12016 | version is 1.2 or greater, use @code{GL_PROXY_TEXTURE_3D} to determine | |
12017 | if a texture is too large. See @code{glTexImage3D}. | |
12018 | ||
12019 | @item @code{GL_MAX_CLIENT_ATTRIB_STACK_DEPTH} | |
12020 | ||
12021 | ||
12022 | @var{params} returns one value indicating the maximum supported depth of | |
12023 | the client attribute stack. See @code{glPushClientAttrib}. | |
12024 | ||
12025 | @item @code{GL_MAX_ATTRIB_STACK_DEPTH} | |
12026 | ||
12027 | ||
12028 | @var{params} returns one value, the maximum supported depth of the | |
12029 | attribute stack. The value must be at least 16. See @code{glPushAttrib}. | |
12030 | ||
12031 | @item @code{GL_MAX_CLIP_PLANES} | |
12032 | ||
12033 | ||
12034 | @var{params} returns one value, the maximum number of | |
12035 | application-defined clipping planes. The value must be at least 6. See | |
12036 | @code{glClipPlane}. | |
12037 | ||
12038 | @item @code{GL_MAX_COLOR_MATRIX_STACK_DEPTH} | |
12039 | ||
12040 | ||
12041 | @var{params} returns one value, the maximum supported depth of the color | |
12042 | matrix stack. The value must be at least 2. See @code{glPushMatrix}. | |
12043 | ||
12044 | @item @code{GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS} | |
12045 | ||
12046 | ||
12047 | @var{params} returns one value, the maximum supported texture image | |
12048 | units that can be used to access texture maps from the vertex shader and | |
12049 | the fragment processor combined. If both the vertex shader and the | |
12050 | fragment processing stage access the same texture image unit, then that | |
12051 | counts as using two texture image units against this limit. The value | |
12052 | must be at least 2. See @code{glActiveTexture}. | |
12053 | ||
12054 | @item @code{GL_MAX_CUBE_MAP_TEXTURE_SIZE} | |
12055 | ||
12056 | ||
12057 | @var{params} returns one value. The value gives a rough estimate of the | |
12058 | largest cube-map texture that the GL can handle. The value must be at | |
12059 | least 16. If the GL version is 1.3 or greater, use | |
12060 | @code{GL_PROXY_TEXTURE_CUBE_MAP} to determine if a texture is too large. | |
12061 | See @code{glTexImage2D}. | |
12062 | ||
12063 | @item @code{GL_MAX_DRAW_BUFFERS} | |
12064 | ||
12065 | ||
12066 | @var{params} returns one value, the maximum number of simultaneous | |
12067 | output colors allowed from a fragment shader using the | |
12068 | @code{gl_FragData} built-in array. The value must be at least 1. See | |
12069 | @code{glDrawBuffers}. | |
12070 | ||
12071 | @item @code{GL_MAX_ELEMENTS_INDICES} | |
12072 | ||
12073 | ||
12074 | @var{params} returns one value, the recommended maximum number of vertex | |
12075 | array indices. See @code{glDrawRangeElements}. | |
12076 | ||
12077 | @item @code{GL_MAX_ELEMENTS_VERTICES} | |
12078 | ||
12079 | ||
12080 | @var{params} returns one value, the recommended maximum number of vertex | |
12081 | array vertices. See @code{glDrawRangeElements}. | |
12082 | ||
12083 | @item @code{GL_MAX_EVAL_ORDER} | |
12084 | ||
12085 | ||
12086 | @var{params} returns one value, the maximum equation order supported by | |
12087 | 1D and 2D evaluators. The value must be at least 8. See @code{glMap1} | |
12088 | and @code{glMap2}. | |
12089 | ||
12090 | @item @code{GL_MAX_FRAGMENT_UNIFORM_COMPONENTS} | |
12091 | ||
12092 | ||
12093 | @var{params} returns one value, the maximum number of individual | |
12094 | floating-point, integer, or boolean values that can be held in uniform | |
12095 | variable storage for a fragment shader. The value must be at least 64. | |
12096 | See @code{glUniform}. | |
12097 | ||
12098 | @item @code{GL_MAX_LIGHTS} | |
12099 | ||
12100 | ||
12101 | @var{params} returns one value, the maximum number of lights. The value | |
12102 | must be at least 8. See @code{glLight}. | |
12103 | ||
12104 | @item @code{GL_MAX_LIST_NESTING} | |
12105 | ||
12106 | ||
12107 | @var{params} returns one value, the maximum recursion depth allowed | |
12108 | during display-list traversal. The value must be at least 64. See | |
12109 | @code{glCallList}. | |
12110 | ||
12111 | @item @code{GL_MAX_MODELVIEW_STACK_DEPTH} | |
12112 | ||
12113 | ||
12114 | @var{params} returns one value, the maximum supported depth of the | |
12115 | modelview matrix stack. The value must be at least 32. See | |
12116 | @code{glPushMatrix}. | |
12117 | ||
12118 | @item @code{GL_MAX_NAME_STACK_DEPTH} | |
12119 | ||
12120 | ||
12121 | @var{params} returns one value, the maximum supported depth of the | |
12122 | selection name stack. The value must be at least 64. See | |
12123 | @code{glPushName}. | |
12124 | ||
12125 | @item @code{GL_MAX_PIXEL_MAP_TABLE} | |
12126 | ||
12127 | ||
12128 | @var{params} returns one value, the maximum supported size of a | |
12129 | @code{glPixelMap} lookup table. The value must be at least 32. See | |
12130 | @code{glPixelMap}. | |
12131 | ||
12132 | @item @code{GL_MAX_PROJECTION_STACK_DEPTH} | |
12133 | ||
12134 | ||
12135 | @var{params} returns one value, the maximum supported depth of the | |
12136 | projection matrix stack. The value must be at least 2. See | |
12137 | @code{glPushMatrix}. | |
12138 | ||
12139 | @item @code{GL_MAX_TEXTURE_COORDS} | |
12140 | ||
12141 | ||
12142 | @var{params} returns one value, the maximum number of texture coordinate | |
12143 | sets available to vertex and fragment shaders. The value must be at | |
12144 | least 2. See @code{glActiveTexture} and @code{glClientActiveTexture}. | |
12145 | ||
12146 | @item @code{GL_MAX_TEXTURE_IMAGE_UNITS} | |
12147 | ||
12148 | ||
12149 | @var{params} returns one value, the maximum supported texture image | |
12150 | units that can be used to access texture maps from the fragment shader. | |
12151 | The value must be at least 2. See @code{glActiveTexture}. | |
12152 | ||
12153 | @item @code{GL_MAX_TEXTURE_LOD_BIAS} | |
12154 | ||
12155 | ||
12156 | @var{params} returns one value, the maximum, absolute value of the | |
12157 | texture level-of-detail bias. The value must be at least 4. | |
12158 | ||
12159 | @item @code{GL_MAX_TEXTURE_SIZE} | |
12160 | ||
12161 | ||
12162 | @var{params} returns one value. The value gives a rough estimate of the | |
12163 | largest texture that the GL can handle. The value must be at least 64. | |
12164 | If the GL version is 1.1 or greater, use @code{GL_PROXY_TEXTURE_1D} or | |
12165 | @code{GL_PROXY_TEXTURE_2D} to determine if a texture is too large. See | |
12166 | @code{glTexImage1D} and @code{glTexImage2D}. | |
12167 | ||
12168 | @item @code{GL_MAX_TEXTURE_STACK_DEPTH} | |
12169 | ||
12170 | ||
12171 | @var{params} returns one value, the maximum supported depth of the | |
12172 | texture matrix stack. The value must be at least 2. See | |
12173 | @code{glPushMatrix}. | |
12174 | ||
12175 | @item @code{GL_MAX_TEXTURE_UNITS} | |
12176 | ||
12177 | ||
12178 | @var{params} returns a single value indicating the number of | |
12179 | conventional texture units supported. Each conventional texture unit | |
12180 | includes both a texture coordinate set and a texture image unit. | |
12181 | Conventional texture units may be used for fixed-function (non-shader) | |
12182 | rendering. The value must be at least 2. Additional texture coordinate | |
12183 | sets and texture image units may be accessed from vertex and fragment | |
12184 | shaders. See @code{glActiveTexture} and @code{glClientActiveTexture}. | |
12185 | ||
12186 | @item @code{GL_MAX_VARYING_FLOATS} | |
12187 | ||
12188 | ||
12189 | @var{params} returns one value, the maximum number of interpolators | |
12190 | available for processing varying variables used by vertex and fragment | |
12191 | shaders. This value represents the number of individual floating-point | |
12192 | values that can be interpolated; varying variables declared as vectors, | |
12193 | matrices, and arrays will all consume multiple interpolators. The value | |
12194 | must be at least 32. | |
12195 | ||
12196 | @item @code{GL_MAX_VERTEX_ATTRIBS} | |
12197 | ||
12198 | ||
12199 | @var{params} returns one value, the maximum number of 4-component | |
12200 | generic vertex attributes accessible to a vertex shader. The value must | |
12201 | be at least 16. See @code{glVertexAttrib}. | |
12202 | ||
12203 | @item @code{GL_MAX_VERTEX_TEXTURE_IMAGE_UNITS} | |
12204 | ||
12205 | ||
12206 | @var{params} returns one value, the maximum supported texture image | |
12207 | units that can be used to access texture maps from the vertex shader. | |
12208 | The value may be 0. See @code{glActiveTexture}. | |
12209 | ||
12210 | @item @code{GL_MAX_VERTEX_UNIFORM_COMPONENTS} | |
12211 | ||
12212 | ||
12213 | @var{params} returns one value, the maximum number of individual | |
12214 | floating-point, integer, or boolean values that can be held in uniform | |
12215 | variable storage for a vertex shader. The value must be at least 512. | |
12216 | See @code{glUniform}. | |
12217 | ||
12218 | @item @code{GL_MAX_VIEWPORT_DIMS} | |
12219 | ||
12220 | ||
12221 | @var{params} returns two values: the maximum supported width and height | |
12222 | of the viewport. These must be at least as large as the visible | |
12223 | dimensions of the display being rendered to. See @code{glViewport}. | |
12224 | ||
12225 | @item @code{GL_MINMAX} | |
12226 | ||
12227 | ||
12228 | @var{params} returns a single boolean value indicating whether pixel | |
12229 | minmax values are computed. The initial value is @code{GL_FALSE}. See | |
12230 | @code{glMinmax}. | |
12231 | ||
12232 | @item @code{GL_MODELVIEW_MATRIX} | |
12233 | ||
12234 | ||
12235 | @var{params} returns sixteen values: the modelview matrix on the top of | |
12236 | the modelview matrix stack. Initially this matrix is the identity | |
12237 | matrix. See @code{glPushMatrix}. | |
12238 | ||
12239 | @item @code{GL_MODELVIEW_STACK_DEPTH} | |
12240 | ||
12241 | ||
12242 | @var{params} returns one value, the number of matrices on the modelview | |
12243 | matrix stack. The initial value is 1. See @code{glPushMatrix}. | |
12244 | ||
12245 | @item @code{GL_NAME_STACK_DEPTH} | |
12246 | ||
12247 | ||
12248 | @var{params} returns one value, the number of names on the selection | |
12249 | name stack. The initial value is 0. See @code{glPushName}. | |
12250 | ||
12251 | @item @code{GL_NORMAL_ARRAY} | |
12252 | ||
12253 | ||
12254 | @var{params} returns a single boolean value, indicating whether the | |
12255 | normal array is enabled. The initial value is @code{GL_FALSE}. See | |
12256 | @code{glNormalPointer}. | |
12257 | ||
12258 | @item @code{GL_NORMAL_ARRAY_BUFFER_BINDING} | |
12259 | ||
12260 | ||
12261 | @var{params} returns a single value, the name of the buffer object | |
12262 | associated with the normal array. This buffer object would have been | |
12263 | bound to the target @code{GL_ARRAY_BUFFER} at the time of the most | |
12264 | recent call to @code{glNormalPointer}. If no buffer object was bound to | |
12265 | this target, 0 is returned. The initial value is 0. See | |
12266 | @code{glBindBuffer}. | |
12267 | ||
12268 | @item @code{GL_NORMAL_ARRAY_STRIDE} | |
12269 | ||
12270 | ||
12271 | @var{params} returns one value, the byte offset between consecutive | |
12272 | normals in the normal array. The initial value is 0. See | |
12273 | @code{glNormalPointer}. | |
12274 | ||
12275 | @item @code{GL_NORMAL_ARRAY_TYPE} | |
12276 | ||
12277 | ||
12278 | @var{params} returns one value, the data type of each coordinate in the | |
12279 | normal array. The initial value is @code{GL_FLOAT}. See | |
12280 | @code{glNormalPointer}. | |
12281 | ||
12282 | @item @code{GL_NORMALIZE} | |
12283 | ||
12284 | ||
12285 | @var{params} returns a single boolean value indicating whether normals | |
12286 | are automatically scaled to unit length after they have been transformed | |
12287 | to eye coordinates. The initial value is @code{GL_FALSE}. See | |
12288 | @code{glNormal}. | |
12289 | ||
12290 | @item @code{GL_NUM_COMPRESSED_TEXTURE_FORMATS} | |
12291 | ||
12292 | ||
12293 | @var{params} returns a single integer value indicating the number of | |
12294 | available compressed texture formats. The minimum value is 0. See | |
12295 | @code{glCompressedTexImage2D}. | |
12296 | ||
12297 | @item @code{GL_PACK_ALIGNMENT} | |
12298 | ||
12299 | ||
12300 | @var{params} returns one value, the byte alignment used for writing | |
12301 | pixel data to memory. The initial value is 4. See @code{glPixelStore}. | |
12302 | ||
12303 | @item @code{GL_PACK_IMAGE_HEIGHT} | |
12304 | ||
12305 | ||
12306 | @var{params} returns one value, the image height used for writing pixel | |
12307 | data to memory. The initial value is 0. See @code{glPixelStore}. | |
12308 | ||
12309 | @item @code{GL_PACK_LSB_FIRST} | |
12310 | ||
12311 | ||
12312 | @var{params} returns a single boolean value indicating whether | |
12313 | single-bit pixels being written to memory are written first to the least | |
12314 | significant bit of each unsigned byte. The initial value is | |
12315 | @code{GL_FALSE}. See @code{glPixelStore}. | |
12316 | ||
12317 | @item @code{GL_PACK_ROW_LENGTH} | |
12318 | ||
12319 | ||
12320 | @var{params} returns one value, the row length used for writing pixel | |
12321 | data to memory. The initial value is 0. See @code{glPixelStore}. | |
12322 | ||
12323 | @item @code{GL_PACK_SKIP_IMAGES} | |
12324 | ||
12325 | ||
12326 | @var{params} returns one value, the number of pixel images skipped | |
12327 | before the first pixel is written into memory. The initial value is 0. | |
12328 | See @code{glPixelStore}. | |
12329 | ||
12330 | @item @code{GL_PACK_SKIP_PIXELS} | |
12331 | ||
12332 | ||
12333 | @var{params} returns one value, the number of pixel locations skipped | |
12334 | before the first pixel is written into memory. The initial value is 0. | |
12335 | See @code{glPixelStore}. | |
12336 | ||
12337 | @item @code{GL_PACK_SKIP_ROWS} | |
12338 | ||
12339 | ||
12340 | @var{params} returns one value, the number of rows of pixel locations | |
12341 | skipped before the first pixel is written into memory. The initial value | |
12342 | is 0. See @code{glPixelStore}. | |
12343 | ||
12344 | @item @code{GL_PACK_SWAP_BYTES} | |
12345 | ||
12346 | ||
12347 | @var{params} returns a single boolean value indicating whether the bytes | |
12348 | of two-byte and four-byte pixel indices and components are swapped | |
12349 | before being written to memory. The initial value is @code{GL_FALSE}. | |
12350 | See @code{glPixelStore}. | |
12351 | ||
12352 | @item @code{GL_PERSPECTIVE_CORRECTION_HINT} | |
12353 | ||
12354 | ||
12355 | @var{params} returns one value, a symbolic constant indicating the mode | |
12356 | of the perspective correction hint. The initial value is | |
12357 | @code{GL_DONT_CARE}. See @code{glHint}. | |
12358 | ||
12359 | @item @code{GL_PIXEL_MAP_A_TO_A_SIZE} | |
12360 | ||
12361 | ||
12362 | @var{params} returns one value, the size of the alpha-to-alpha pixel | |
12363 | translation table. The initial value is 1. See @code{glPixelMap}. | |
12364 | ||
12365 | @item @code{GL_PIXEL_MAP_B_TO_B_SIZE} | |
12366 | ||
12367 | ||
12368 | @var{params} returns one value, the size of the blue-to-blue pixel | |
12369 | translation table. The initial value is 1. See @code{glPixelMap}. | |
12370 | ||
12371 | @item @code{GL_PIXEL_MAP_G_TO_G_SIZE} | |
12372 | ||
12373 | ||
12374 | @var{params} returns one value, the size of the green-to-green pixel | |
12375 | translation table. The initial value is 1. See @code{glPixelMap}. | |
12376 | ||
12377 | @item @code{GL_PIXEL_MAP_I_TO_A_SIZE} | |
12378 | ||
12379 | ||
12380 | @var{params} returns one value, the size of the index-to-alpha pixel | |
12381 | translation table. The initial value is 1. See @code{glPixelMap}. | |
12382 | ||
12383 | @item @code{GL_PIXEL_MAP_I_TO_B_SIZE} | |
12384 | ||
12385 | ||
12386 | @var{params} returns one value, the size of the index-to-blue pixel | |
12387 | translation table. The initial value is 1. See @code{glPixelMap}. | |
12388 | ||
12389 | @item @code{GL_PIXEL_MAP_I_TO_G_SIZE} | |
12390 | ||
12391 | ||
12392 | @var{params} returns one value, the size of the index-to-green pixel | |
12393 | translation table. The initial value is 1. See @code{glPixelMap}. | |
12394 | ||
12395 | @item @code{GL_PIXEL_MAP_I_TO_I_SIZE} | |
12396 | ||
12397 | ||
12398 | @var{params} returns one value, the size of the index-to-index pixel | |
12399 | translation table. The initial value is 1. See @code{glPixelMap}. | |
12400 | ||
12401 | @item @code{GL_PIXEL_MAP_I_TO_R_SIZE} | |
12402 | ||
12403 | ||
12404 | @var{params} returns one value, the size of the index-to-red pixel | |
12405 | translation table. The initial value is 1. See @code{glPixelMap}. | |
12406 | ||
12407 | @item @code{GL_PIXEL_MAP_R_TO_R_SIZE} | |
12408 | ||
12409 | ||
12410 | @var{params} returns one value, the size of the red-to-red pixel | |
12411 | translation table. The initial value is 1. See @code{glPixelMap}. | |
12412 | ||
12413 | @item @code{GL_PIXEL_MAP_S_TO_S_SIZE} | |
12414 | ||
12415 | ||
12416 | @var{params} returns one value, the size of the stencil-to-stencil pixel | |
12417 | translation table. The initial value is 1. See @code{glPixelMap}. | |
12418 | ||
12419 | @item @code{GL_PIXEL_PACK_BUFFER_BINDING} | |
12420 | ||
12421 | ||
12422 | @var{params} returns a single value, the name of the buffer object | |
12423 | currently bound to the target @code{GL_PIXEL_PACK_BUFFER}. If no buffer | |
12424 | object is bound to this target, 0 is returned. The initial value is 0. | |
12425 | See @code{glBindBuffer}. | |
12426 | ||
12427 | @item @code{GL_PIXEL_UNPACK_BUFFER_BINDING} | |
12428 | ||
12429 | ||
12430 | @var{params} returns a single value, the name of the buffer object | |
12431 | currently bound to the target @code{GL_PIXEL_UNPACK_BUFFER}. If no | |
12432 | buffer object is bound to this target, 0 is returned. The initial value | |
12433 | is 0. See @code{glBindBuffer}. | |
12434 | ||
12435 | @item @code{GL_POINT_DISTANCE_ATTENUATION} | |
12436 | ||
12437 | ||
12438 | @var{params} returns three values, the coefficients for computing the | |
12439 | attenuation value for points. See @code{glPointParameter}. | |
12440 | ||
12441 | @item @code{GL_POINT_FADE_THRESHOLD_SIZE} | |
12442 | ||
12443 | ||
12444 | @var{params} returns one value, the point size threshold for determining | |
12445 | the point size. See @code{glPointParameter}. | |
12446 | ||
12447 | @item @code{GL_POINT_SIZE} | |
12448 | ||
12449 | ||
12450 | @var{params} returns one value, the point size as specified by | |
12451 | @code{glPointSize}. The initial value is 1. | |
12452 | ||
12453 | @item @code{GL_POINT_SIZE_GRANULARITY} | |
12454 | ||
12455 | ||
12456 | @var{params} returns one value, the size difference between adjacent | |
12457 | supported sizes for antialiased points. See @code{glPointSize}. | |
12458 | ||
12459 | @item @code{GL_POINT_SIZE_MAX} | |
12460 | ||
12461 | ||
12462 | @var{params} returns one value, the upper bound for the attenuated point | |
12463 | sizes. The initial value is 0.0. See @code{glPointParameter}. | |
12464 | ||
12465 | @item @code{GL_POINT_SIZE_MIN} | |
12466 | ||
12467 | ||
12468 | @var{params} returns one value, the lower bound for the attenuated point | |
12469 | sizes. The initial value is 1.0. See @code{glPointParameter}. | |
12470 | ||
12471 | @item @code{GL_POINT_SIZE_RANGE} | |
12472 | ||
12473 | ||
12474 | @var{params} returns two values: the smallest and largest supported | |
12475 | sizes for antialiased points. The smallest size must be at most 1, and | |
12476 | the largest size must be at least 1. See @code{glPointSize}. | |
12477 | ||
12478 | @item @code{GL_POINT_SMOOTH} | |
12479 | ||
12480 | ||
12481 | @var{params} returns a single boolean value indicating whether | |
12482 | antialiasing of points is enabled. The initial value is @code{GL_FALSE}. | |
12483 | See @code{glPointSize}. | |
12484 | ||
12485 | @item @code{GL_POINT_SMOOTH_HINT} | |
12486 | ||
12487 | ||
12488 | @var{params} returns one value, a symbolic constant indicating the mode | |
12489 | of the point antialiasing hint. The initial value is | |
12490 | @code{GL_DONT_CARE}. See @code{glHint}. | |
12491 | ||
12492 | @item @code{GL_POINT_SPRITE} | |
12493 | ||
12494 | ||
12495 | @var{params} returns a single boolean value indicating whether point | |
12496 | sprite is enabled. The initial value is @code{GL_FALSE}. | |
12497 | ||
12498 | @item @code{GL_POLYGON_MODE} | |
12499 | ||
12500 | ||
12501 | @var{params} returns two values: symbolic constants indicating whether | |
12502 | front-facing and back-facing polygons are rasterized as points, lines, | |
12503 | or filled polygons. The initial value is @code{GL_FILL}. See | |
12504 | @code{glPolygonMode}. | |
12505 | ||
12506 | @item @code{GL_POLYGON_OFFSET_FACTOR} | |
12507 | ||
12508 | ||
12509 | @var{params} returns one value, the scaling factor used to determine the | |
12510 | variable offset that is added to the depth value of each fragment | |
12511 | generated when a polygon is rasterized. The initial value is 0. See | |
12512 | @code{glPolygonOffset}. | |
12513 | ||
12514 | @item @code{GL_POLYGON_OFFSET_UNITS} | |
12515 | ||
12516 | ||
12517 | @var{params} returns one value. This value is multiplied by an | |
12518 | implementation-specific value and then added to the depth value of each | |
12519 | fragment generated when a polygon is rasterized. The initial value is 0. | |
12520 | See @code{glPolygonOffset}. | |
12521 | ||
12522 | @item @code{GL_POLYGON_OFFSET_FILL} | |
12523 | ||
12524 | ||
12525 | @var{params} returns a single boolean value indicating whether polygon | |
12526 | offset is enabled for polygons in fill mode. The initial value is | |
12527 | @code{GL_FALSE}. See @code{glPolygonOffset}. | |
12528 | ||
12529 | @item @code{GL_POLYGON_OFFSET_LINE} | |
12530 | ||
12531 | ||
12532 | @var{params} returns a single boolean value indicating whether polygon | |
12533 | offset is enabled for polygons in line mode. The initial value is | |
12534 | @code{GL_FALSE}. See @code{glPolygonOffset}. | |
12535 | ||
12536 | @item @code{GL_POLYGON_OFFSET_POINT} | |
12537 | ||
12538 | ||
12539 | @var{params} returns a single boolean value indicating whether polygon | |
12540 | offset is enabled for polygons in point mode. The initial value is | |
12541 | @code{GL_FALSE}. See @code{glPolygonOffset}. | |
12542 | ||
12543 | @item @code{GL_POLYGON_SMOOTH} | |
12544 | ||
12545 | ||
12546 | @var{params} returns a single boolean value indicating whether | |
12547 | antialiasing of polygons is enabled. The initial value is | |
12548 | @code{GL_FALSE}. See @code{glPolygonMode}. | |
12549 | ||
12550 | @item @code{GL_POLYGON_SMOOTH_HINT} | |
12551 | ||
12552 | ||
12553 | @var{params} returns one value, a symbolic constant indicating the mode | |
12554 | of the polygon antialiasing hint. The initial value is | |
12555 | @code{GL_DONT_CARE}. See @code{glHint}. | |
12556 | ||
12557 | @item @code{GL_POLYGON_STIPPLE} | |
12558 | ||
12559 | ||
12560 | @var{params} returns a single boolean value indicating whether polygon | |
12561 | stippling is enabled. The initial value is @code{GL_FALSE}. See | |
12562 | @code{glPolygonStipple}. | |
12563 | ||
12564 | @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} | |
12565 | ||
12566 | ||
12567 | @var{params} returns a single boolean value indicating whether post | |
12568 | color matrix transformation lookup is enabled. The initial value is | |
12569 | @code{GL_FALSE}. See @code{glColorTable}. | |
12570 | ||
12571 | @item @code{GL_POST_COLOR_MATRIX_RED_BIAS} | |
12572 | ||
12573 | ||
12574 | @var{params} returns one value, the red bias factor applied to RGBA | |
12575 | fragments after color matrix transformations. The initial value is 0. | |
12576 | See @code{glPixelTransfer}. | |
12577 | ||
12578 | @item @code{GL_POST_COLOR_MATRIX_GREEN_BIAS} | |
12579 | ||
12580 | ||
12581 | @var{params} returns one value, the green bias factor applied to RGBA | |
12582 | fragments after color matrix transformations. The initial value is 0. | |
12583 | See @code{glPixelTransfer} | |
12584 | ||
12585 | @item @code{GL_POST_COLOR_MATRIX_BLUE_BIAS} | |
12586 | ||
12587 | ||
12588 | @var{params} returns one value, the blue bias factor applied to RGBA | |
12589 | fragments after color matrix transformations. The initial value is 0. | |
12590 | See @code{glPixelTransfer}. | |
12591 | ||
12592 | @item @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS} | |
12593 | ||
12594 | ||
12595 | @var{params} returns one value, the alpha bias factor applied to RGBA | |
12596 | fragments after color matrix transformations. The initial value is 0. | |
12597 | See @code{glPixelTransfer}. | |
12598 | ||
12599 | @item @code{GL_POST_COLOR_MATRIX_RED_SCALE} | |
12600 | ||
12601 | ||
12602 | @var{params} returns one value, the red scale factor applied to RGBA | |
12603 | fragments after color matrix transformations. The initial value is 1. | |
12604 | See @code{glPixelTransfer}. | |
12605 | ||
12606 | @item @code{GL_POST_COLOR_MATRIX_GREEN_SCALE} | |
12607 | ||
12608 | ||
12609 | @var{params} returns one value, the green scale factor applied to RGBA | |
12610 | fragments after color matrix transformations. The initial value is 1. | |
12611 | See @code{glPixelTransfer}. | |
12612 | ||
12613 | @item @code{GL_POST_COLOR_MATRIX_BLUE_SCALE} | |
12614 | ||
12615 | ||
12616 | @var{params} returns one value, the blue scale factor applied to RGBA | |
12617 | fragments after color matrix transformations. The initial value is 1. | |
12618 | See @code{glPixelTransfer}. | |
12619 | ||
12620 | @item @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE} | |
12621 | ||
12622 | ||
12623 | @var{params} returns one value, the alpha scale factor applied to RGBA | |
12624 | fragments after color matrix transformations. The initial value is 1. | |
12625 | See @code{glPixelTransfer}. | |
12626 | ||
12627 | @item @code{GL_POST_CONVOLUTION_COLOR_TABLE} | |
12628 | ||
12629 | ||
12630 | @var{params} returns a single boolean value indicating whether post | |
12631 | convolution lookup is enabled. The initial value is @code{GL_FALSE}. See | |
12632 | @code{glColorTable}. | |
12633 | ||
12634 | @item @code{GL_POST_CONVOLUTION_RED_BIAS} | |
12635 | ||
12636 | ||
12637 | @var{params} returns one value, the red bias factor applied to RGBA | |
12638 | fragments after convolution. The initial value is 0. See | |
12639 | @code{glPixelTransfer}. | |
12640 | ||
12641 | @item @code{GL_POST_CONVOLUTION_GREEN_BIAS} | |
12642 | ||
12643 | ||
12644 | @var{params} returns one value, the green bias factor applied to RGBA | |
12645 | fragments after convolution. The initial value is 0. See | |
12646 | @code{glPixelTransfer}. | |
12647 | ||
12648 | @item @code{GL_POST_CONVOLUTION_BLUE_BIAS} | |
12649 | ||
12650 | ||
12651 | @var{params} returns one value, the blue bias factor applied to RGBA | |
12652 | fragments after convolution. The initial value is 0. See | |
12653 | @code{glPixelTransfer}. | |
12654 | ||
12655 | @item @code{GL_POST_CONVOLUTION_ALPHA_BIAS} | |
12656 | ||
12657 | ||
12658 | @var{params} returns one value, the alpha bias factor applied to RGBA | |
12659 | fragments after convolution. The initial value is 0. See | |
12660 | @code{glPixelTransfer}. | |
12661 | ||
12662 | @item @code{GL_POST_CONVOLUTION_RED_SCALE} | |
12663 | ||
12664 | ||
12665 | @var{params} returns one value, the red scale factor applied to RGBA | |
12666 | fragments after convolution. The initial value is 1. See | |
12667 | @code{glPixelTransfer}. | |
12668 | ||
12669 | @item @code{GL_POST_CONVOLUTION_GREEN_SCALE} | |
12670 | ||
12671 | ||
12672 | @var{params} returns one value, the green scale factor applied to RGBA | |
12673 | fragments after convolution. The initial value is 1. See | |
12674 | @code{glPixelTransfer}. | |
12675 | ||
12676 | @item @code{GL_POST_CONVOLUTION_BLUE_SCALE} | |
12677 | ||
12678 | ||
12679 | @var{params} returns one value, the blue scale factor applied to RGBA | |
12680 | fragments after convolution. The initial value is 1. See | |
12681 | @code{glPixelTransfer}. | |
12682 | ||
12683 | @item @code{GL_POST_CONVOLUTION_ALPHA_SCALE} | |
12684 | ||
12685 | ||
12686 | @var{params} returns one value, the alpha scale factor applied to RGBA | |
12687 | fragments after convolution. The initial value is 1. See | |
12688 | @code{glPixelTransfer}. | |
12689 | ||
12690 | @item @code{GL_PROJECTION_MATRIX} | |
12691 | ||
12692 | ||
12693 | @var{params} returns sixteen values: the projection matrix on the top of | |
12694 | the projection matrix stack. Initially this matrix is the identity | |
12695 | matrix. See @code{glPushMatrix}. | |
12696 | ||
12697 | @item @code{GL_PROJECTION_STACK_DEPTH} | |
12698 | ||
12699 | ||
12700 | @var{params} returns one value, the number of matrices on the projection | |
12701 | matrix stack. The initial value is 1. See @code{glPushMatrix}. | |
12702 | ||
12703 | @item @code{GL_READ_BUFFER} | |
12704 | ||
12705 | ||
12706 | @var{params} returns one value, a symbolic constant indicating which | |
12707 | color buffer is selected for reading. The initial value is | |
12708 | @code{GL_BACK} if there is a back buffer, otherwise it is | |
12709 | @code{GL_FRONT}. See @code{glReadPixels} and @code{glAccum}. | |
12710 | ||
12711 | @item @code{GL_RED_BIAS} | |
12712 | ||
12713 | ||
12714 | @var{params} returns one value, the red bias factor used during pixel | |
12715 | transfers. The initial value is 0. | |
12716 | ||
12717 | @item @code{GL_RED_BITS} | |
12718 | ||
12719 | ||
12720 | @var{params} returns one value, the number of red bitplanes in each | |
12721 | color buffer. | |
12722 | ||
12723 | @item @code{GL_RED_SCALE} | |
12724 | ||
12725 | ||
12726 | @var{params} returns one value, the red scale factor used during pixel | |
12727 | transfers. The initial value is 1. See @code{glPixelTransfer}. | |
12728 | ||
12729 | @item @code{GL_RENDER_MODE} | |
12730 | ||
12731 | ||
12732 | @var{params} returns one value, a symbolic constant indicating whether | |
12733 | the GL is in render, select, or feedback mode. The initial value is | |
12734 | @code{GL_RENDER}. See @code{glRenderMode}. | |
12735 | ||
12736 | @item @code{GL_RESCALE_NORMAL} | |
12737 | ||
12738 | ||
12739 | @var{params} returns single boolean value indicating whether normal | |
12740 | rescaling is enabled. See @code{glEnable}. | |
12741 | ||
12742 | @item @code{GL_RGBA_MODE} | |
12743 | ||
12744 | ||
12745 | @var{params} returns a single boolean value indicating whether the GL is | |
12746 | in RGBA mode (true) or color index mode (false). See @code{glColor}. | |
12747 | ||
12748 | @item @code{GL_SAMPLE_BUFFERS} | |
12749 | ||
12750 | ||
12751 | @var{params} returns a single integer value indicating the number of | |
12752 | sample buffers associated with the framebuffer. See | |
12753 | @code{glSampleCoverage}. | |
12754 | ||
12755 | @item @code{GL_SAMPLE_COVERAGE_VALUE} | |
12756 | ||
12757 | ||
12758 | @var{params} returns a single positive floating-point value indicating | |
12759 | the current sample coverage value. See @code{glSampleCoverage}. | |
12760 | ||
12761 | @item @code{GL_SAMPLE_COVERAGE_INVERT} | |
12762 | ||
12763 | ||
12764 | @var{params} returns a single boolean value indicating if the temporary | |
12765 | coverage value should be inverted. See @code{glSampleCoverage}. | |
12766 | ||
12767 | @item @code{GL_SAMPLES} | |
12768 | ||
12769 | ||
12770 | @var{params} returns a single integer value indicating the coverage mask | |
12771 | size. See @code{glSampleCoverage}. | |
12772 | ||
12773 | @item @code{GL_SCISSOR_BOX} | |
12774 | ||
12775 | ||
12776 | @var{params} returns four values: the @r{@var{x}} and @r{@var{y}} window | |
12777 | coordinates of the scissor box, followed by its width and height. | |
12778 | Initially the @r{@var{x}} and @r{@var{y}} window coordinates are both 0 | |
12779 | and the width and height are set to the size of the window. See | |
12780 | @code{glScissor}. | |
12781 | ||
12782 | @item @code{GL_SCISSOR_TEST} | |
12783 | ||
12784 | ||
12785 | @var{params} returns a single boolean value indicating whether | |
12786 | scissoring is enabled. The initial value is @code{GL_FALSE}. See | |
12787 | @code{glScissor}. | |
12788 | ||
12789 | @item @code{GL_SECONDARY_COLOR_ARRAY} | |
12790 | ||
12791 | ||
12792 | @var{params} returns a single boolean value indicating whether the | |
12793 | secondary color array is enabled. The initial value is @code{GL_FALSE}. | |
12794 | See @code{glSecondaryColorPointer}. | |
12795 | ||
12796 | @item @code{GL_SECONDARY_COLOR_ARRAY_BUFFER_BINDING} | |
12797 | ||
12798 | ||
12799 | @var{params} returns a single value, the name of the buffer object | |
12800 | associated with the secondary color array. This buffer object would have | |
12801 | been bound to the target @code{GL_ARRAY_BUFFER} at the time of the most | |
12802 | recent call to @code{glSecondaryColorPointer}. If no buffer object was | |
12803 | bound to this target, 0 is returned. The initial value is 0. See | |
12804 | @code{glBindBuffer}. | |
12805 | ||
12806 | @item @code{GL_SECONDARY_COLOR_ARRAY_SIZE} | |
12807 | ||
12808 | ||
12809 | @var{params} returns one value, the number of components per color in | |
12810 | the secondary color array. The initial value is 3. See | |
12811 | @code{glSecondaryColorPointer}. | |
12812 | ||
12813 | @item @code{GL_SECONDARY_COLOR_ARRAY_STRIDE} | |
12814 | ||
12815 | ||
12816 | @var{params} returns one value, the byte offset between consecutive | |
12817 | colors in the secondary color array. The initial value is 0. See | |
12818 | @code{glSecondaryColorPointer}. | |
12819 | ||
12820 | @item @code{GL_SECONDARY_COLOR_ARRAY_TYPE} | |
12821 | ||
12822 | ||
12823 | @var{params} returns one value, the data type of each component in the | |
12824 | secondary color array. The initial value is @code{GL_FLOAT}. See | |
12825 | @code{glSecondaryColorPointer}. | |
12826 | ||
12827 | @item @code{GL_SELECTION_BUFFER_SIZE} | |
12828 | ||
12829 | ||
12830 | @var{params} return one value, the size of the selection buffer. See | |
12831 | @code{glSelectBuffer}. | |
12832 | ||
12833 | @item @code{GL_SEPARABLE_2D} | |
12834 | ||
12835 | ||
12836 | @var{params} returns a single boolean value indicating whether 2D | |
12837 | separable convolution is enabled. The initial value is @code{GL_FALSE}. | |
12838 | See @code{glSeparableFilter2D}. | |
12839 | ||
12840 | @item @code{GL_SHADE_MODEL} | |
12841 | ||
12842 | ||
12843 | @var{params} returns one value, a symbolic constant indicating whether | |
12844 | the shading mode is flat or smooth. The initial value is | |
12845 | @code{GL_SMOOTH}. See @code{glShadeModel}. | |
12846 | ||
12847 | @item @code{GL_SMOOTH_LINE_WIDTH_RANGE} | |
12848 | ||
12849 | ||
12850 | @var{params} returns two values, the smallest and largest supported | |
12851 | widths for antialiased lines. See @code{glLineWidth}. | |
12852 | ||
12853 | @item @code{GL_SMOOTH_LINE_WIDTH_GRANULARITY} | |
12854 | ||
12855 | ||
12856 | @var{params} returns one value, the granularity of widths for | |
12857 | antialiased lines. See @code{glLineWidth}. | |
12858 | ||
12859 | @item @code{GL_SMOOTH_POINT_SIZE_RANGE} | |
12860 | ||
12861 | ||
12862 | @var{params} returns two values, the smallest and largest supported | |
12863 | widths for antialiased points. See @code{glPointSize}. | |
12864 | ||
12865 | @item @code{GL_SMOOTH_POINT_SIZE_GRANULARITY} | |
12866 | ||
12867 | ||
12868 | @var{params} returns one value, the granularity of sizes for antialiased | |
12869 | points. See @code{glPointSize}. | |
12870 | ||
12871 | @item @code{GL_STENCIL_BACK_FAIL} | |
12872 | ||
12873 | ||
12874 | @var{params} returns one value, a symbolic constant indicating what | |
12875 | action is taken for back-facing polygons when the stencil test fails. | |
12876 | The initial value is @code{GL_KEEP}. See @code{glStencilOpSeparate}. | |
12877 | ||
12878 | @item @code{GL_STENCIL_BACK_FUNC} | |
12879 | ||
12880 | ||
12881 | @var{params} returns one value, a symbolic constant indicating what | |
12882 | function is used for back-facing polygons to compare the stencil | |
12883 | reference value with the stencil buffer value. The initial value is | |
12884 | @code{GL_ALWAYS}. See @code{glStencilFuncSeparate}. | |
12885 | ||
12886 | @item @code{GL_STENCIL_BACK_PASS_DEPTH_FAIL} | |
12887 | ||
12888 | ||
12889 | @var{params} returns one value, a symbolic constant indicating what | |
12890 | action is taken for back-facing polygons when the stencil test passes, | |
12891 | but the depth test fails. The initial value is @code{GL_KEEP}. See | |
12892 | @code{glStencilOpSeparate}. | |
12893 | ||
12894 | @item @code{GL_STENCIL_BACK_PASS_DEPTH_PASS} | |
12895 | ||
12896 | ||
12897 | @var{params} returns one value, a symbolic constant indicating what | |
12898 | action is taken for back-facing polygons when the stencil test passes | |
12899 | and the depth test passes. The initial value is @code{GL_KEEP}. See | |
12900 | @code{glStencilOpSeparate}. | |
12901 | ||
12902 | @item @code{GL_STENCIL_BACK_REF} | |
12903 | ||
12904 | ||
12905 | @var{params} returns one value, the reference value that is compared | |
12906 | with the contents of the stencil buffer for back-facing polygons. The | |
12907 | initial value is 0. See @code{glStencilFuncSeparate}. | |
12908 | ||
12909 | @item @code{GL_STENCIL_BACK_VALUE_MASK} | |
12910 | ||
12911 | ||
12912 | @var{params} returns one value, the mask that is used for back-facing | |
12913 | polygons to mask both the stencil reference value and the stencil buffer | |
12914 | value before they are compared. The initial value is all 1's. See | |
12915 | @code{glStencilFuncSeparate}. | |
12916 | ||
12917 | @item @code{GL_STENCIL_BACK_WRITEMASK} | |
12918 | ||
12919 | ||
12920 | @var{params} returns one value, the mask that controls writing of the | |
12921 | stencil bitplanes for back-facing polygons. The initial value is all | |
12922 | 1's. See @code{glStencilMaskSeparate}. | |
12923 | ||
12924 | @item @code{GL_STENCIL_BITS} | |
12925 | ||
12926 | ||
12927 | @var{params} returns one value, the number of bitplanes in the stencil | |
12928 | buffer. | |
12929 | ||
12930 | @item @code{GL_STENCIL_CLEAR_VALUE} | |
12931 | ||
12932 | ||
12933 | @var{params} returns one value, the index to which the stencil bitplanes | |
12934 | are cleared. The initial value is 0. See @code{glClearStencil}. | |
12935 | ||
12936 | @item @code{GL_STENCIL_FAIL} | |
12937 | ||
12938 | ||
12939 | @var{params} returns one value, a symbolic constant indicating what | |
12940 | action is taken when the stencil test fails. The initial value is | |
12941 | @code{GL_KEEP}. See @code{glStencilOp}. If the GL version is 2.0 or | |
12942 | greater, this stencil state only affects non-polygons and front-facing | |
12943 | polygons. Back-facing polygons use separate stencil state. See | |
12944 | @code{glStencilOpSeparate}. | |
12945 | ||
12946 | @item @code{GL_STENCIL_FUNC} | |
12947 | ||
12948 | ||
12949 | @var{params} returns one value, a symbolic constant indicating what | |
12950 | function is used to compare the stencil reference value with the stencil | |
12951 | buffer value. The initial value is @code{GL_ALWAYS}. See | |
12952 | @code{glStencilFunc}. If the GL version is 2.0 or greater, this stencil | |
12953 | state only affects non-polygons and front-facing polygons. Back-facing | |
12954 | polygons use separate stencil state. See @code{glStencilFuncSeparate}. | |
12955 | ||
12956 | @item @code{GL_STENCIL_PASS_DEPTH_FAIL} | |
12957 | ||
12958 | ||
12959 | @var{params} returns one value, a symbolic constant indicating what | |
12960 | action is taken when the stencil test passes, but the depth test fails. | |
12961 | The initial value is @code{GL_KEEP}. See @code{glStencilOp}. If the GL | |
12962 | version is 2.0 or greater, this stencil state only affects non-polygons | |
12963 | and front-facing polygons. Back-facing polygons use separate stencil | |
12964 | state. See @code{glStencilOpSeparate}. | |
12965 | ||
12966 | @item @code{GL_STENCIL_PASS_DEPTH_PASS} | |
12967 | ||
12968 | ||
12969 | @var{params} returns one value, a symbolic constant indicating what | |
12970 | action is taken when the stencil test passes and the depth test passes. | |
12971 | The initial value is @code{GL_KEEP}. See @code{glStencilOp}. If the GL | |
12972 | version is 2.0 or greater, this stencil state only affects non-polygons | |
12973 | and front-facing polygons. Back-facing polygons use separate stencil | |
12974 | state. See @code{glStencilOpSeparate}. | |
12975 | ||
12976 | @item @code{GL_STENCIL_REF} | |
12977 | ||
12978 | ||
12979 | @var{params} returns one value, the reference value that is compared | |
12980 | with the contents of the stencil buffer. The initial value is 0. See | |
12981 | @code{glStencilFunc}. If the GL version is 2.0 or greater, this stencil | |
12982 | state only affects non-polygons and front-facing polygons. Back-facing | |
12983 | polygons use separate stencil state. See @code{glStencilFuncSeparate}. | |
12984 | ||
12985 | @item @code{GL_STENCIL_TEST} | |
12986 | ||
12987 | ||
12988 | @var{params} returns a single boolean value indicating whether stencil | |
12989 | testing of fragments is enabled. The initial value is @code{GL_FALSE}. | |
12990 | See @code{glStencilFunc} and @code{glStencilOp}. | |
12991 | ||
12992 | @item @code{GL_STENCIL_VALUE_MASK} | |
12993 | ||
12994 | ||
12995 | @var{params} returns one value, the mask that is used to mask both the | |
12996 | stencil reference value and the stencil buffer value before they are | |
12997 | compared. The initial value is all 1's. See @code{glStencilFunc}. If the | |
12998 | GL version is 2.0 or greater, this stencil state only affects | |
12999 | non-polygons and front-facing polygons. Back-facing polygons use | |
13000 | separate stencil state. See @code{glStencilFuncSeparate}. | |
13001 | ||
13002 | @item @code{GL_STENCIL_WRITEMASK} | |
13003 | ||
13004 | ||
13005 | @var{params} returns one value, the mask that controls writing of the | |
13006 | stencil bitplanes. The initial value is all 1's. See | |
13007 | @code{glStencilMask}. If the GL version is 2.0 or greater, this stencil | |
13008 | state only affects non-polygons and front-facing polygons. Back-facing | |
13009 | polygons use separate stencil state. See @code{glStencilMaskSeparate}. | |
13010 | ||
13011 | @item @code{GL_STEREO} | |
13012 | ||
13013 | ||
13014 | @var{params} returns a single boolean value indicating whether stereo | |
13015 | buffers (left and right) are supported. | |
13016 | ||
13017 | @item @code{GL_SUBPIXEL_BITS} | |
13018 | ||
13019 | ||
13020 | @var{params} returns one value, an estimate of the number of bits of | |
13021 | subpixel resolution that are used to position rasterized geometry in | |
13022 | window coordinates. The value must be at least 4. | |
13023 | ||
13024 | @item @code{GL_TEXTURE_1D} | |
13025 | ||
13026 | ||
13027 | @var{params} returns a single boolean value indicating whether 1D | |
13028 | texture mapping is enabled. The initial value is @code{GL_FALSE}. See | |
13029 | @code{glTexImage1D}. | |
13030 | ||
13031 | @item @code{GL_TEXTURE_BINDING_1D} | |
13032 | ||
13033 | ||
13034 | @var{params} returns a single value, the name of the texture currently | |
13035 | bound to the target @code{GL_TEXTURE_1D}. The initial value is 0. See | |
13036 | @code{glBindTexture}. | |
13037 | ||
13038 | @item @code{GL_TEXTURE_2D} | |
13039 | ||
13040 | ||
13041 | @var{params} returns a single boolean value indicating whether 2D | |
13042 | texture mapping is enabled. The initial value is @code{GL_FALSE}. See | |
13043 | @code{glTexImage2D}. | |
13044 | ||
13045 | @item @code{GL_TEXTURE_BINDING_2D} | |
13046 | ||
13047 | ||
13048 | @var{params} returns a single value, the name of the texture currently | |
13049 | bound to the target @code{GL_TEXTURE_2D}. The initial value is 0. See | |
13050 | @code{glBindTexture}. | |
13051 | ||
13052 | @item @code{GL_TEXTURE_3D} | |
13053 | ||
13054 | ||
13055 | @var{params} returns a single boolean value indicating whether 3D | |
13056 | texture mapping is enabled. The initial value is @code{GL_FALSE}. See | |
13057 | @code{glTexImage3D}. | |
13058 | ||
13059 | @item @code{GL_TEXTURE_BINDING_3D} | |
13060 | ||
13061 | ||
13062 | @var{params} returns a single value, the name of the texture currently | |
13063 | bound to the target @code{GL_TEXTURE_3D}. The initial value is 0. See | |
13064 | @code{glBindTexture}. | |
13065 | ||
13066 | @item @code{GL_TEXTURE_BINDING_CUBE_MAP} | |
13067 | ||
13068 | ||
13069 | @var{params} returns a single value, the name of the texture currently | |
13070 | bound to the target @code{GL_TEXTURE_CUBE_MAP}. The initial value is 0. | |
13071 | See @code{glBindTexture}. | |
13072 | ||
13073 | @item @code{GL_TEXTURE_COMPRESSION_HINT} | |
13074 | ||
13075 | ||
13076 | @var{params} returns a single value indicating the mode of the texture | |
13077 | compression hint. The initial value is @code{GL_DONT_CARE}. | |
13078 | ||
13079 | @item @code{GL_TEXTURE_COORD_ARRAY} | |
13080 | ||
13081 | ||
13082 | @var{params} returns a single boolean value indicating whether the | |
13083 | texture coordinate array is enabled. The initial value is | |
13084 | @code{GL_FALSE}. See @code{glTexCoordPointer}. | |
13085 | ||
13086 | @item @code{GL_TEXTURE_COORD_ARRAY_BUFFER_BINDING} | |
13087 | ||
13088 | ||
13089 | @var{params} returns a single value, the name of the buffer object | |
13090 | associated with the texture coordinate array. This buffer object would | |
13091 | have been bound to the target @code{GL_ARRAY_BUFFER} at the time of the | |
13092 | most recent call to @code{glTexCoordPointer}. If no buffer object was | |
13093 | bound to this target, 0 is returned. The initial value is 0. See | |
13094 | @code{glBindBuffer}. | |
13095 | ||
13096 | @item @code{GL_TEXTURE_COORD_ARRAY_SIZE} | |
13097 | ||
13098 | ||
13099 | @var{params} returns one value, the number of coordinates per element in | |
13100 | the texture coordinate array. The initial value is 4. See | |
13101 | @code{glTexCoordPointer}. | |
13102 | ||
13103 | @item @code{GL_TEXTURE_COORD_ARRAY_STRIDE} | |
13104 | ||
13105 | ||
13106 | @var{params} returns one value, the byte offset between consecutive | |
13107 | elements in the texture coordinate array. The initial value is 0. See | |
13108 | @code{glTexCoordPointer}. | |
13109 | ||
13110 | @item @code{GL_TEXTURE_COORD_ARRAY_TYPE} | |
13111 | ||
13112 | ||
13113 | @var{params} returns one value, the data type of the coordinates in the | |
13114 | texture coordinate array. The initial value is @code{GL_FLOAT}. See | |
13115 | @code{glTexCoordPointer}. | |
13116 | ||
13117 | @item @code{GL_TEXTURE_CUBE_MAP} | |
13118 | ||
13119 | ||
13120 | @var{params} returns a single boolean value indicating whether | |
13121 | cube-mapped texture mapping is enabled. The initial value is | |
13122 | @code{GL_FALSE}. See @code{glTexImage2D}. | |
13123 | ||
13124 | @item @code{GL_TEXTURE_GEN_Q} | |
13125 | ||
13126 | ||
13127 | @var{params} returns a single boolean value indicating whether automatic | |
13128 | generation of the @var{q} texture coordinate is enabled. The initial | |
13129 | value is @code{GL_FALSE}. See @code{glTexGen}. | |
13130 | ||
13131 | @item @code{GL_TEXTURE_GEN_R} | |
13132 | ||
13133 | ||
13134 | @var{params} returns a single boolean value indicating whether automatic | |
13135 | generation of the @var{r} texture coordinate is enabled. The initial | |
13136 | value is @code{GL_FALSE}. See @code{glTexGen}. | |
13137 | ||
13138 | @item @code{GL_TEXTURE_GEN_S} | |
13139 | ||
13140 | ||
13141 | @var{params} returns a single boolean value indicating whether automatic | |
13142 | generation of the @var{S} texture coordinate is enabled. The initial | |
13143 | value is @code{GL_FALSE}. See @code{glTexGen}. | |
13144 | ||
13145 | @item @code{GL_TEXTURE_GEN_T} | |
13146 | ||
13147 | ||
13148 | @var{params} returns a single boolean value indicating whether automatic | |
13149 | generation of the T texture coordinate is enabled. The initial value is | |
13150 | @code{GL_FALSE}. See @code{glTexGen}. | |
13151 | ||
13152 | @item @code{GL_TEXTURE_MATRIX} | |
13153 | ||
13154 | ||
13155 | @var{params} returns sixteen values: the texture matrix on the top of | |
13156 | the texture matrix stack. Initially this matrix is the identity matrix. | |
13157 | See @code{glPushMatrix}. | |
13158 | ||
13159 | @item @code{GL_TEXTURE_STACK_DEPTH} | |
13160 | ||
13161 | ||
13162 | @var{params} returns one value, the number of matrices on the texture | |
13163 | matrix stack. The initial value is 1. See @code{glPushMatrix}. | |
13164 | ||
13165 | @item @code{GL_TRANSPOSE_COLOR_MATRIX} | |
13166 | ||
13167 | ||
13168 | @var{params} returns 16 values, the elements of the color matrix in | |
13169 | row-major order. See @code{glLoadTransposeMatrix}. | |
13170 | ||
13171 | @item @code{GL_TRANSPOSE_MODELVIEW_MATRIX} | |
13172 | ||
13173 | ||
13174 | @var{params} returns 16 values, the elements of the modelview matrix in | |
13175 | row-major order. See @code{glLoadTransposeMatrix}. | |
13176 | ||
13177 | @item @code{GL_TRANSPOSE_PROJECTION_MATRIX} | |
13178 | ||
13179 | ||
13180 | @var{params} returns 16 values, the elements of the projection matrix in | |
13181 | row-major order. See @code{glLoadTransposeMatrix}. | |
13182 | ||
13183 | @item @code{GL_TRANSPOSE_TEXTURE_MATRIX} | |
13184 | ||
13185 | ||
13186 | @var{params} returns 16 values, the elements of the texture matrix in | |
13187 | row-major order. See @code{glLoadTransposeMatrix}. | |
13188 | ||
13189 | @item @code{GL_UNPACK_ALIGNMENT} | |
13190 | ||
13191 | ||
13192 | @var{params} returns one value, the byte alignment used for reading | |
13193 | pixel data from memory. The initial value is 4. See @code{glPixelStore}. | |
13194 | ||
13195 | @item @code{GL_UNPACK_IMAGE_HEIGHT} | |
13196 | ||
13197 | ||
13198 | @var{params} returns one value, the image height used for reading pixel | |
13199 | data from memory. The initial is 0. See @code{glPixelStore}. | |
13200 | ||
13201 | @item @code{GL_UNPACK_LSB_FIRST} | |
13202 | ||
13203 | ||
13204 | @var{params} returns a single boolean value indicating whether | |
13205 | single-bit pixels being read from memory are read first from the least | |
13206 | significant bit of each unsigned byte. The initial value is | |
13207 | @code{GL_FALSE}. See @code{glPixelStore}. | |
13208 | ||
13209 | @item @code{GL_UNPACK_ROW_LENGTH} | |
13210 | ||
13211 | ||
13212 | @var{params} returns one value, the row length used for reading pixel | |
13213 | data from memory. The initial value is 0. See @code{glPixelStore}. | |
13214 | ||
13215 | @item @code{GL_UNPACK_SKIP_IMAGES} | |
13216 | ||
13217 | ||
13218 | @var{params} returns one value, the number of pixel images skipped | |
13219 | before the first pixel is read from memory. The initial value is 0. See | |
13220 | @code{glPixelStore}. | |
13221 | ||
13222 | @item @code{GL_UNPACK_SKIP_PIXELS} | |
13223 | ||
13224 | ||
13225 | @var{params} returns one value, the number of pixel locations skipped | |
13226 | before the first pixel is read from memory. The initial value is 0. See | |
13227 | @code{glPixelStore}. | |
13228 | ||
13229 | @item @code{GL_UNPACK_SKIP_ROWS} | |
8925f36f AW |
13230 | |
13231 | ||
b002944d AW |
13232 | @var{params} returns one value, the number of rows of pixel locations |
13233 | skipped before the first pixel is read from memory. The initial value is | |
13234 | 0. See @code{glPixelStore}. | |
8925f36f | 13235 | |
b002944d | 13236 | @item @code{GL_UNPACK_SWAP_BYTES} |
8925f36f AW |
13237 | |
13238 | ||
b002944d AW |
13239 | @var{params} returns a single boolean value indicating whether the bytes |
13240 | of two-byte and four-byte pixel indices and components are swapped after | |
13241 | being read from memory. The initial value is @code{GL_FALSE}. See | |
13242 | @code{glPixelStore}. | |
8925f36f | 13243 | |
b002944d | 13244 | @item @code{GL_VERTEX_ARRAY} |
8925f36f AW |
13245 | |
13246 | ||
b002944d AW |
13247 | @var{params} returns a single boolean value indicating whether the |
13248 | vertex array is enabled. The initial value is @code{GL_FALSE}. See | |
13249 | @code{glVertexPointer}. | |
8925f36f | 13250 | |
b002944d | 13251 | @item @code{GL_VERTEX_ARRAY_BUFFER_BINDING} |
8925f36f AW |
13252 | |
13253 | ||
b002944d AW |
13254 | @var{params} returns a single value, the name of the buffer object |
13255 | associated with the vertex array. This buffer object would have been | |
13256 | bound to the target @code{GL_ARRAY_BUFFER} at the time of the most | |
13257 | recent call to @code{glVertexPointer}. If no buffer object was bound to | |
13258 | this target, 0 is returned. The initial value is 0. See | |
13259 | @code{glBindBuffer}. | |
8925f36f | 13260 | |
b002944d | 13261 | @item @code{GL_VERTEX_ARRAY_SIZE} |
8925f36f AW |
13262 | |
13263 | ||
b002944d AW |
13264 | @var{params} returns one value, the number of coordinates per vertex in |
13265 | the vertex array. The initial value is 4. See @code{glVertexPointer}. | |
8925f36f | 13266 | |
b002944d | 13267 | @item @code{GL_VERTEX_ARRAY_STRIDE} |
8925f36f AW |
13268 | |
13269 | ||
b002944d AW |
13270 | @var{params} returns one value, the byte offset between consecutive |
13271 | vertices in the vertex array. The initial value is 0. See | |
13272 | @code{glVertexPointer}. | |
8925f36f | 13273 | |
b002944d | 13274 | @item @code{GL_VERTEX_ARRAY_TYPE} |
8925f36f AW |
13275 | |
13276 | ||
b002944d AW |
13277 | @var{params} returns one value, the data type of each coordinate in the |
13278 | vertex array. The initial value is @code{GL_FLOAT}. See | |
13279 | @code{glVertexPointer}. | |
8925f36f | 13280 | |
b002944d | 13281 | @item @code{GL_VERTEX_PROGRAM_POINT_SIZE} |
8925f36f AW |
13282 | |
13283 | ||
b002944d AW |
13284 | @var{params} returns a single boolean value indicating whether vertex |
13285 | program point size mode is enabled. If enabled, and a vertex shader is | |
13286 | active, then the point size is taken from the shader built-in | |
13287 | @code{gl_PointSize}. If disabled, and a vertex shader is active, then | |
13288 | the point size is taken from the point state as specified by | |
13289 | @code{glPointSize}. The initial value is @code{GL_FALSE}. | |
8925f36f | 13290 | |
b002944d | 13291 | @item @code{GL_VERTEX_PROGRAM_TWO_SIDE} |
8925f36f AW |
13292 | |
13293 | ||
b002944d AW |
13294 | @var{params} returns a single boolean value indicating whether vertex |
13295 | program two-sided color mode is enabled. If enabled, and a vertex shader | |
13296 | is active, then the GL chooses the back color output for back-facing | |
13297 | polygons, and the front color output for non-polygons and front-facing | |
13298 | polygons. If disabled, and a vertex shader is active, then the front | |
13299 | color output is always selected. The initial value is @code{GL_FALSE}. | |
8925f36f | 13300 | |
b002944d | 13301 | @item @code{GL_VIEWPORT} |
8925f36f AW |
13302 | |
13303 | ||
b002944d AW |
13304 | @var{params} returns four values: the @r{@var{x}} and @r{@var{y}} window |
13305 | coordinates of the viewport, followed by its width and height. Initially | |
13306 | the @r{@var{x}} and @r{@var{y}} window coordinates are both set to 0, | |
13307 | and the width and height are set to the width and height of the window | |
13308 | into which the GL will do its rendering. See @code{glViewport}. | |
8925f36f | 13309 | |
b002944d | 13310 | @item @code{GL_ZOOM_X} |
8925f36f AW |
13311 | |
13312 | ||
b002944d AW |
13313 | @var{params} returns one value, the @r{@var{x}} pixel zoom factor. The |
13314 | initial value is 1. See @code{glPixelZoom}. | |
8925f36f | 13315 | |
b002944d | 13316 | @item @code{GL_ZOOM_Y} |
8925f36f | 13317 | |
8925f36f | 13318 | |
b002944d AW |
13319 | @var{params} returns one value, the @r{@var{y}} pixel zoom factor. The |
13320 | initial value is 1. See @code{glPixelZoom}. | |
8925f36f | 13321 | |
b002944d | 13322 | @end table |
bb894c9d | 13323 | |
b002944d AW |
13324 | Many of the boolean parameters can also be queried more easily using |
13325 | @code{glIsEnabled}. | |
8925f36f | 13326 | |
b002944d AW |
13327 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted |
13328 | value. | |
13329 | ||
13330 | @code{GL_INVALID_OPERATION} is generated if @code{glGet} is executed | |
13331 | between the execution of @code{glBegin} and the corresponding execution | |
13332 | of @code{glEnd}. | |
bb894c9d | 13333 | |
8925f36f AW |
13334 | |
13335 | ||
bb894c9d | 13336 | @end deftypefun |
8925f36f | 13337 | |
bb894c9d | 13338 | @deftypefun void glHint target mode |
3c9b6116 AW |
13339 | Specify implementation-specific hints. |
13340 | ||
8925f36f AW |
13341 | @table @asis |
13342 | @item @var{target} | |
13343 | Specifies a symbolic constant indicating the behavior to be controlled. | |
13344 | @code{GL_FOG_HINT}, @code{GL_GENERATE_MIPMAP_HINT}, | |
13345 | @code{GL_LINE_SMOOTH_HINT}, @code{GL_PERSPECTIVE_CORRECTION_HINT}, | |
13346 | @code{GL_POINT_SMOOTH_HINT}, @code{GL_POLYGON_SMOOTH_HINT}, | |
13347 | @code{GL_TEXTURE_COMPRESSION_HINT}, and | |
13348 | @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT} are accepted. | |
13349 | ||
13350 | @item @var{mode} | |
13351 | Specifies a symbolic constant indicating the desired behavior. | |
13352 | @code{GL_FASTEST}, @code{GL_NICEST}, and @code{GL_DONT_CARE} are | |
13353 | accepted. | |
13354 | ||
13355 | @end table | |
13356 | ||
8925f36f AW |
13357 | Certain aspects of GL behavior, when there is room for interpretation, |
13358 | can be controlled with hints. A hint is specified with two arguments. | |
13359 | @var{target} is a symbolic constant indicating the behavior to be | |
13360 | controlled, and @var{mode} is another symbolic constant indicating the | |
13361 | desired behavior. The initial value for each @var{target} is | |
13362 | @code{GL_DONT_CARE}. @var{mode} can be one of the following: | |
13363 | ||
13364 | @table @asis | |
13365 | @item @code{GL_FASTEST} | |
13366 | ||
13367 | ||
13368 | The most efficient option should be chosen. | |
13369 | ||
13370 | @item @code{GL_NICEST} | |
13371 | ||
13372 | ||
13373 | The most correct, or highest quality, option should be chosen. | |
13374 | ||
13375 | @item @code{GL_DONT_CARE} | |
13376 | ||
13377 | ||
13378 | No preference. | |
13379 | ||
13380 | @end table | |
13381 | ||
13382 | Though the implementation aspects that can be hinted are well defined, | |
13383 | the interpretation of the hints depends on the implementation. The hint | |
13384 | aspects that can be specified with @var{target}, along with suggested | |
13385 | semantics, are as follows: | |
13386 | ||
13387 | @table @asis | |
13388 | @item @code{GL_FOG_HINT} | |
13389 | ||
13390 | ||
13391 | Indicates the accuracy of fog calculation. If per-pixel fog calculation | |
13392 | is not efficiently supported by the GL implementation, hinting | |
13393 | @code{GL_DONT_CARE} or @code{GL_FASTEST} can result in per-vertex | |
13394 | calculation of fog effects. | |
13395 | ||
13396 | @item @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT} | |
13397 | ||
13398 | ||
13399 | Indicates the accuracy of the derivative calculation for the GL shading | |
13400 | language fragment processing built-in functions: @code{dFdx}, | |
13401 | @code{dFdy}, and @code{fwidth}. | |
13402 | ||
13403 | @item @code{GL_GENERATE_MIPMAP_HINT} | |
13404 | ||
13405 | ||
13406 | Indicates the quality of filtering when generating mipmap images. | |
13407 | ||
13408 | @item @code{GL_LINE_SMOOTH_HINT} | |
13409 | ||
13410 | ||
13411 | Indicates the sampling quality of antialiased lines. If a larger filter | |
13412 | function is applied, hinting @code{GL_NICEST} can result in more pixel | |
13413 | fragments being generated during rasterization. | |
13414 | ||
13415 | @item @code{GL_PERSPECTIVE_CORRECTION_HINT} | |
13416 | ||
13417 | ||
13418 | Indicates the quality of color, texture coordinate, and fog coordinate | |
13419 | interpolation. If perspective-corrected parameter interpolation is not | |
13420 | efficiently supported by the GL implementation, hinting | |
13421 | @code{GL_DONT_CARE} or @code{GL_FASTEST} can result in simple linear | |
13422 | interpolation of colors and/or texture coordinates. | |
13423 | ||
13424 | @item @code{GL_POINT_SMOOTH_HINT} | |
13425 | ||
13426 | ||
13427 | Indicates the sampling quality of antialiased points. If a larger filter | |
13428 | function is applied, hinting @code{GL_NICEST} can result in more pixel | |
13429 | fragments being generated during rasterization. | |
13430 | ||
13431 | @item @code{GL_POLYGON_SMOOTH_HINT} | |
13432 | ||
13433 | ||
13434 | Indicates the sampling quality of antialiased polygons. Hinting | |
13435 | @code{GL_NICEST} can result in more pixel fragments being generated | |
13436 | during rasterization, if a larger filter function is applied. | |
13437 | ||
13438 | @item @code{GL_TEXTURE_COMPRESSION_HINT} | |
13439 | ||
13440 | ||
13441 | Indicates the quality and performance of the compressing texture images. | |
13442 | Hinting @code{GL_FASTEST} indicates that texture images should be | |
13443 | compressed as quickly as possible, while @code{GL_NICEST} indicates that | |
13444 | texture images should be compressed with as little image quality loss as | |
13445 | possible. @code{GL_NICEST} should be selected if the texture is to be | |
13446 | retrieved by @code{glGetCompressedTexImage} for reuse. | |
13447 | ||
13448 | @end table | |
13449 | ||
8925f36f AW |
13450 | @code{GL_INVALID_ENUM} is generated if either @var{target} or @var{mode} |
13451 | is not an accepted value. | |
13452 | ||
13453 | @code{GL_INVALID_OPERATION} is generated if @code{glHint} is executed | |
13454 | between the execution of @code{glBegin} and the corresponding execution | |
13455 | of @code{glEnd}. | |
13456 | ||
bb894c9d | 13457 | @end deftypefun |
8925f36f | 13458 | |
bb894c9d | 13459 | @deftypefun void glHistogram target width internalformat sink |
3c9b6116 AW |
13460 | Define histogram table. |
13461 | ||
8925f36f AW |
13462 | @table @asis |
13463 | @item @var{target} | |
13464 | The histogram whose parameters are to be set. Must be one of | |
13465 | @code{GL_HISTOGRAM} or @code{GL_PROXY_HISTOGRAM}. | |
13466 | ||
13467 | @item @var{width} | |
13468 | The number of entries in the histogram table. Must be a power of 2. | |
13469 | ||
13470 | @item @var{internalformat} | |
13471 | The format of entries in the histogram table. Must be one of | |
13472 | @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, | |
13473 | @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
13474 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
13475 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
13476 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
13477 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
13478 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
13479 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
13480 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
13481 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
13482 | @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
13483 | ||
13484 | @item @var{sink} | |
13485 | If @code{GL_TRUE}, pixels will be consumed by the histogramming process | |
13486 | and no drawing or texture loading will take place. If @code{GL_FALSE}, | |
13487 | pixels will proceed to the minmax process after histogramming. | |
13488 | ||
13489 | @end table | |
13490 | ||
8925f36f AW |
13491 | When @code{GL_HISTOGRAM} is enabled, RGBA color components are converted |
13492 | to histogram table indices by clamping to the range [0,1], multiplying | |
13493 | by the width of the histogram table, and rounding to the nearest | |
13494 | integer. The table entries selected by the RGBA indices are then | |
13495 | incremented. (If the internal format of the histogram table includes | |
13496 | luminance, then the index derived from the R color component determines | |
13497 | the luminance table entry to be incremented.) If a histogram table entry | |
13498 | is incremented beyond its maximum value, then its value becomes | |
13499 | undefined. (This is not an error.) | |
13500 | ||
13501 | Histogramming is performed only for RGBA pixels (though these may be | |
13502 | specified originally as color indices and converted to RGBA by index | |
13503 | table lookup). Histogramming is enabled with @code{glEnable} and | |
13504 | disabled with @code{glDisable}. | |
13505 | ||
13506 | When @var{target} is @code{GL_HISTOGRAM}, @code{glHistogram} redefines | |
13507 | the current histogram table to have @var{width} entries of the format | |
13508 | specified by @var{internalformat}. The entries are indexed 0 through | |
3c9b6116 AW |
13509 | @r{@var{width}-1}, and all entries are initialized to zero. The values |
13510 | in the previous histogram table, if any, are lost. If @var{sink} is | |
13511 | @code{GL_TRUE}, then pixels are discarded after histogramming; no | |
8925f36f AW |
13512 | further processing of the pixels takes place, and no drawing, texture |
13513 | loading, or pixel readback will result. | |
13514 | ||
13515 | When @var{target} is @code{GL_PROXY_HISTOGRAM}, @code{glHistogram} | |
13516 | computes all state information as if the histogram table were to be | |
13517 | redefined, but does not actually define the new table. If the requested | |
13518 | histogram table is too large to be supported, then the state information | |
13519 | will be set to zero. This provides a way to determine if a histogram | |
13520 | table with the given parameters can be supported. | |
13521 | ||
13522 | ||
13523 | ||
8925f36f AW |
13524 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
13525 | allowable values. | |
13526 | ||
13527 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
13528 | is not a power of 2. | |
13529 | ||
13530 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
13531 | of the allowable values. | |
13532 | ||
13533 | @code{GL_TABLE_TOO_LARGE} is generated if @var{target} is | |
13534 | @code{GL_HISTOGRAM} and the histogram table specified is too large for | |
13535 | the implementation. | |
13536 | ||
13537 | @code{GL_INVALID_OPERATION} is generated if @code{glHistogram} is | |
13538 | executed between the execution of @code{glBegin} and the corresponding | |
13539 | execution of @code{glEnd}. | |
13540 | ||
bb894c9d | 13541 | @end deftypefun |
8925f36f | 13542 | |
bb894c9d | 13543 | @deftypefun void glIndexMask mask |
3c9b6116 AW |
13544 | Control the writing of individual bits in the color index buffers. |
13545 | ||
8925f36f AW |
13546 | @table @asis |
13547 | @item @var{mask} | |
13548 | Specifies a bit mask to enable and disable the writing of individual | |
13549 | bits in the color index buffers. Initially, the mask is all 1's. | |
13550 | ||
13551 | @end table | |
13552 | ||
8925f36f | 13553 | @code{glIndexMask} controls the writing of individual bits in the color |
3c9b6116 AW |
13554 | index buffers. The least significant @r{@var{n}} bits of @var{mask}, |
13555 | where @r{@var{n}} is the number of bits in a color index buffer, specify | |
13556 | a mask. Where a 1 (one) appears in the mask, it's possible to write to | |
13557 | the corresponding bit in the color index buffer (or buffers). Where a 0 | |
13558 | (zero) appears, the corresponding bit is write-protected. | |
8925f36f AW |
13559 | |
13560 | This mask is used only in color index mode, and it affects only the | |
13561 | buffers currently selected for writing (see @code{glDrawBuffer}). | |
13562 | Initially, all bits are enabled for writing. | |
13563 | ||
8925f36f AW |
13564 | @code{GL_INVALID_OPERATION} is generated if @code{glIndexMask} is |
13565 | executed between the execution of @code{glBegin} and the corresponding | |
13566 | execution of @code{glEnd}. | |
13567 | ||
bb894c9d | 13568 | @end deftypefun |
8925f36f | 13569 | |
bb894c9d | 13570 | @deftypefun void glIndexPointer type stride pointer |
3c9b6116 AW |
13571 | Define an array of color indexes. |
13572 | ||
8925f36f AW |
13573 | @table @asis |
13574 | @item @var{type} | |
13575 | Specifies the data type of each color index in the array. Symbolic | |
13576 | constants @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, @code{GL_INT}, | |
13577 | @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value is | |
13578 | @code{GL_FLOAT}. | |
13579 | ||
13580 | @item @var{stride} | |
13581 | Specifies the byte offset between consecutive color indexes. If | |
13582 | @var{stride} is 0, the color indexes are understood to be tightly packed | |
13583 | in the array. The initial value is 0. | |
13584 | ||
13585 | @item @var{pointer} | |
13586 | Specifies a pointer to the first index in the array. The initial value | |
13587 | is 0. | |
13588 | ||
13589 | @end table | |
13590 | ||
8925f36f AW |
13591 | @code{glIndexPointer} specifies the location and data format of an array |
13592 | of color indexes to use when rendering. @var{type} specifies the data | |
13593 | type of each color index and @var{stride} specifies the byte stride from | |
13594 | one color index to the next, allowing vertices and attributes to be | |
13595 | packed into a single array or stored in separate arrays. | |
13596 | ||
13597 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
13598 | target (see @code{glBindBuffer}) while a color index array is specified, | |
13599 | @var{pointer} is treated as a byte offset into the buffer object's data | |
13600 | store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING}) | |
13601 | is saved as color index vertex array client-side state | |
13602 | (@code{GL_INDEX_ARRAY_BUFFER_BINDING}). | |
13603 | ||
13604 | When a color index array is specified, @var{type}, @var{stride}, and | |
13605 | @var{pointer} are saved as client-side state, in addition to the current | |
13606 | vertex array buffer object binding. | |
13607 | ||
13608 | To enable and disable the color index array, call | |
13609 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
13610 | argument @code{GL_INDEX_ARRAY}. If enabled, the color index array is | |
13611 | used when @code{glDrawArrays}, @code{glMultiDrawArrays}, | |
13612 | @code{glDrawElements}, @code{glMultiDrawElements}, | |
13613 | @code{glDrawRangeElements}, or @code{glArrayElement} is called. | |
13614 | ||
8925f36f AW |
13615 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted |
13616 | value. | |
13617 | ||
13618 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
13619 | ||
bb894c9d | 13620 | @end deftypefun |
8925f36f | 13621 | |
bb894c9d | 13622 | @deftypefun void glIndexi c |
ca09631c | 13623 | @deftypefunx void glIndexf c |
bb894c9d | 13624 | @deftypefunx void glIndexub c |
3c9b6116 AW |
13625 | Set the current color index. |
13626 | ||
8925f36f AW |
13627 | @table @asis |
13628 | @item @var{c} | |
13629 | Specifies the new value for the current color index. | |
13630 | ||
13631 | ||
13632 | ||
13633 | @end table | |
13634 | ||
8925f36f AW |
13635 | @code{glIndex} updates the current (single-valued) color index. It takes |
13636 | one argument, the new value for the current color index. | |
13637 | ||
13638 | The current index is stored as a floating-point value. Integer values | |
13639 | are converted directly to floating-point values, with no special | |
13640 | mapping. The initial value is 1. | |
13641 | ||
13642 | Index values outside the representable range of the color index buffer | |
13643 | are not clamped. However, before an index is dithered (if enabled) and | |
13644 | written to the frame buffer, it is converted to fixed-point format. Any | |
13645 | bits in the integer portion of the resulting fixed-point value that do | |
13646 | not correspond to bits in the frame buffer are masked out. | |
13647 | ||
bb894c9d | 13648 | @end deftypefun |
8925f36f | 13649 | |
bb894c9d | 13650 | @deftypefun void glInitNames |
3c9b6116 AW |
13651 | Initialize the name stack. |
13652 | ||
8925f36f AW |
13653 | The name stack is used during selection mode to allow sets of rendering |
13654 | commands to be uniquely identified. It consists of an ordered set of | |
13655 | unsigned integers. @code{glInitNames} causes the name stack to be | |
13656 | initialized to its default empty state. | |
13657 | ||
13658 | The name stack is always empty while the render mode is not | |
13659 | @code{GL_SELECT}. Calls to @code{glInitNames} while the render mode is | |
13660 | not @code{GL_SELECT} are ignored. | |
13661 | ||
8925f36f AW |
13662 | @code{GL_INVALID_OPERATION} is generated if @code{glInitNames} is |
13663 | executed between the execution of @code{glBegin} and the corresponding | |
13664 | execution of @code{glEnd}. | |
13665 | ||
bb894c9d | 13666 | @end deftypefun |
8925f36f | 13667 | |
bb894c9d | 13668 | @deftypefun void glInterleavedArrays format stride pointer |
3c9b6116 AW |
13669 | Simultaneously specify and enable several interleaved arrays. |
13670 | ||
8925f36f AW |
13671 | @table @asis |
13672 | @item @var{format} | |
13673 | Specifies the type of array to enable. Symbolic constants @code{GL_V2F}, | |
13674 | @code{GL_V3F}, @code{GL_C4UB_V2F}, @code{GL_C4UB_V3F}, | |
13675 | @code{GL_C3F_V3F}, @code{GL_N3F_V3F}, @code{GL_C4F_N3F_V3F}, | |
13676 | @code{GL_T2F_V3F}, @code{GL_T4F_V4F}, @code{GL_T2F_C4UB_V3F}, | |
13677 | @code{GL_T2F_C3F_V3F}, @code{GL_T2F_N3F_V3F}, @code{GL_T2F_C4F_N3F_V3F}, | |
13678 | and @code{GL_T4F_C4F_N3F_V4F} are accepted. | |
13679 | ||
13680 | @item @var{stride} | |
13681 | Specifies the offset in bytes between each aggregate array element. | |
13682 | ||
13683 | @end table | |
13684 | ||
8925f36f AW |
13685 | @code{glInterleavedArrays} lets you specify and enable individual color, |
13686 | normal, texture and vertex arrays whose elements are part of a larger | |
13687 | aggregate array element. For some implementations, this is more | |
13688 | efficient than specifying the arrays separately. | |
13689 | ||
13690 | If @var{stride} is 0, the aggregate elements are stored consecutively. | |
13691 | Otherwise, @var{stride} bytes occur between the beginning of one | |
13692 | aggregate array element and the beginning of the next aggregate array | |
13693 | element. | |
13694 | ||
13695 | @var{format} serves as a ``key'' describing the extraction of individual | |
13696 | arrays from the aggregate array. If @var{format} contains a T, then | |
13697 | texture coordinates are extracted from the interleaved array. If C is | |
13698 | present, color values are extracted. If N is present, normal coordinates | |
13699 | are extracted. Vertex coordinates are always extracted. | |
13700 | ||
13701 | The digits 2, 3, and 4 denote how many values are extracted. F indicates | |
13702 | that values are extracted as floating-point values. Colors may also be | |
13703 | extracted as 4 unsigned bytes if 4UB follows the C. If a color is | |
13704 | extracted as 4 unsigned bytes, the vertex array element which follows is | |
13705 | located at the first possible floating-point aligned address. | |
13706 | ||
8925f36f AW |
13707 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted |
13708 | value. | |
13709 | ||
13710 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
13711 | ||
bb894c9d | 13712 | @end deftypefun |
8925f36f | 13713 | |
bb894c9d | 13714 | @deftypefun GLboolean glIsBuffer buffer |
3c9b6116 AW |
13715 | Determine if a name corresponds to a buffer object. |
13716 | ||
8925f36f AW |
13717 | @table @asis |
13718 | @item @var{buffer} | |
13719 | Specifies a value that may be the name of a buffer object. | |
13720 | ||
13721 | @end table | |
13722 | ||
8925f36f AW |
13723 | @code{glIsBuffer} returns @code{GL_TRUE} if @var{buffer} is currently |
13724 | the name of a buffer object. If @var{buffer} is zero, or is a non-zero | |
13725 | value that is not currently the name of a buffer object, or if an error | |
13726 | occurs, @code{glIsBuffer} returns @code{GL_FALSE}. | |
13727 | ||
13728 | A name returned by @code{glGenBuffers}, but not yet associated with a | |
13729 | buffer object by calling @code{glBindBuffer}, is not the name of a | |
13730 | buffer object. | |
13731 | ||
8925f36f AW |
13732 | @code{GL_INVALID_OPERATION} is generated if @code{glIsBuffer} is |
13733 | executed between the execution of @code{glBegin} and the corresponding | |
13734 | execution of @code{glEnd}. | |
13735 | ||
bb894c9d | 13736 | @end deftypefun |
8925f36f | 13737 | |
bb894c9d | 13738 | @deftypefun GLboolean glIsEnabled cap |
3c9b6116 AW |
13739 | Test whether a capability is enabled. |
13740 | ||
8925f36f AW |
13741 | @table @asis |
13742 | @item @var{cap} | |
13743 | Specifies a symbolic constant indicating a GL capability. | |
13744 | ||
13745 | @end table | |
13746 | ||
8925f36f AW |
13747 | @code{glIsEnabled} returns @code{GL_TRUE} if @var{cap} is an enabled |
13748 | capability and returns @code{GL_FALSE} otherwise. Initially all | |
13749 | capabilities except @code{GL_DITHER} are disabled; @code{GL_DITHER} is | |
13750 | initially enabled. | |
13751 | ||
13752 | The following capabilities are accepted for @var{cap}: | |
13753 | ||
13754 | ||
13755 | ||
13756 | @table @asis | |
13757 | @item @strong{Constant} | |
13758 | @strong{See} | |
13759 | ||
13760 | @item @code{GL_ALPHA_TEST} | |
13761 | @code{glAlphaFunc} | |
13762 | ||
13763 | @item @code{GL_AUTO_NORMAL} | |
13764 | @code{glEvalCoord} | |
13765 | ||
13766 | @item @code{GL_BLEND} | |
13767 | @code{glBlendFunc}, @code{glLogicOp} | |
13768 | ||
13769 | @item @code{GL_CLIP_PLANE}@var{i} | |
13770 | @code{glClipPlane} | |
13771 | ||
13772 | @item @code{GL_COLOR_ARRAY} | |
13773 | @code{glColorPointer} | |
13774 | ||
13775 | @item @code{GL_COLOR_LOGIC_OP} | |
13776 | @code{glLogicOp} | |
13777 | ||
13778 | @item @code{GL_COLOR_MATERIAL} | |
13779 | @code{glColorMaterial} | |
13780 | ||
13781 | @item @code{GL_COLOR_SUM} | |
13782 | @code{glSecondaryColor} | |
13783 | ||
13784 | @item @code{GL_COLOR_TABLE} | |
13785 | @code{glColorTable} | |
13786 | ||
13787 | @item @code{GL_CONVOLUTION_1D} | |
13788 | @code{glConvolutionFilter1D} | |
13789 | ||
13790 | @item @code{GL_CONVOLUTION_2D} | |
13791 | @code{glConvolutionFilter2D} | |
13792 | ||
13793 | @item @code{GL_CULL_FACE} | |
13794 | @code{glCullFace} | |
13795 | ||
13796 | @item @code{GL_DEPTH_TEST} | |
13797 | @code{glDepthFunc}, @code{glDepthRange} | |
13798 | ||
13799 | @item @code{GL_DITHER} | |
13800 | @code{glEnable} | |
13801 | ||
13802 | @item @code{GL_EDGE_FLAG_ARRAY} | |
13803 | @code{glEdgeFlagPointer} | |
13804 | ||
13805 | @item @code{GL_FOG} | |
13806 | @code{glFog} | |
13807 | ||
13808 | @item @code{GL_FOG_COORD_ARRAY} | |
13809 | @code{glFogCoordPointer} | |
13810 | ||
13811 | @item @code{GL_HISTOGRAM} | |
13812 | @code{glHistogram} | |
13813 | ||
13814 | @item @code{GL_INDEX_ARRAY} | |
13815 | @code{glIndexPointer} | |
13816 | ||
13817 | @item @code{GL_INDEX_LOGIC_OP} | |
13818 | @code{glLogicOp} | |
13819 | ||
13820 | @item @code{GL_LIGHT}@var{i} | |
13821 | @code{glLightModel}, @code{glLight} | |
13822 | ||
13823 | @item @code{GL_LIGHTING} | |
13824 | @code{glMaterial}, @code{glLightModel}, @code{glLight} | |
13825 | ||
13826 | @item @code{GL_LINE_SMOOTH} | |
13827 | @code{glLineWidth} | |
13828 | ||
13829 | @item @code{GL_LINE_STIPPLE} | |
13830 | @code{glLineStipple} | |
13831 | ||
13832 | @item @code{GL_MAP1_COLOR_4} | |
13833 | @code{glMap1} | |
13834 | ||
13835 | @item @code{GL_MAP1_INDEX} | |
13836 | @code{glMap1} | |
13837 | ||
13838 | @item @code{GL_MAP1_NORMAL} | |
13839 | @code{glMap1} | |
13840 | ||
13841 | @item @code{GL_MAP1_TEXTURE_COORD_1} | |
13842 | @code{glMap1} | |
13843 | ||
13844 | @item @code{GL_MAP1_TEXTURE_COORD_2} | |
13845 | @code{glMap1} | |
13846 | ||
13847 | @item @code{GL_MAP1_TEXTURE_COORD_3} | |
13848 | @code{glMap1} | |
13849 | ||
13850 | @item @code{GL_MAP1_TEXTURE_COORD_4} | |
13851 | @code{glMap1} | |
13852 | ||
13853 | @item @code{GL_MAP2_COLOR_4} | |
13854 | @code{glMap2} | |
13855 | ||
13856 | @item @code{GL_MAP2_INDEX} | |
13857 | @code{glMap2} | |
13858 | ||
13859 | @item @code{GL_MAP2_NORMAL} | |
13860 | @code{glMap2} | |
13861 | ||
13862 | @item @code{GL_MAP2_TEXTURE_COORD_1} | |
13863 | @code{glMap2} | |
13864 | ||
13865 | @item @code{GL_MAP2_TEXTURE_COORD_2} | |
13866 | @code{glMap2} | |
13867 | ||
13868 | @item @code{GL_MAP2_TEXTURE_COORD_3} | |
13869 | @code{glMap2} | |
13870 | ||
13871 | @item @code{GL_MAP2_TEXTURE_COORD_4} | |
13872 | @code{glMap2} | |
13873 | ||
13874 | @item @code{GL_MAP2_VERTEX_3} | |
13875 | @code{glMap2} | |
13876 | ||
13877 | @item @code{GL_MAP2_VERTEX_4} | |
13878 | @code{glMap2} | |
13879 | ||
13880 | @item @code{GL_MINMAX} | |
13881 | @code{glMinmax} | |
13882 | ||
13883 | @item @code{GL_MULTISAMPLE} | |
13884 | @code{glSampleCoverage} | |
13885 | ||
13886 | @item @code{GL_NORMAL_ARRAY} | |
13887 | @code{glNormalPointer} | |
13888 | ||
13889 | @item @code{GL_NORMALIZE} | |
13890 | @code{glNormal} | |
13891 | ||
13892 | @item @code{GL_POINT_SMOOTH} | |
13893 | @code{glPointSize} | |
13894 | ||
13895 | @item @code{GL_POINT_SPRITE} | |
13896 | @code{glEnable} | |
13897 | ||
13898 | @item @code{GL_POLYGON_SMOOTH} | |
13899 | @code{glPolygonMode} | |
13900 | ||
13901 | @item @code{GL_POLYGON_OFFSET_FILL} | |
13902 | @code{glPolygonOffset} | |
13903 | ||
13904 | @item @code{GL_POLYGON_OFFSET_LINE} | |
13905 | @code{glPolygonOffset} | |
13906 | ||
13907 | @item @code{GL_POLYGON_OFFSET_POINT} | |
13908 | @code{glPolygonOffset} | |
13909 | ||
13910 | @item @code{GL_POLYGON_STIPPLE} | |
13911 | @code{glPolygonStipple} | |
13912 | ||
13913 | @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} | |
13914 | @code{glColorTable} | |
13915 | ||
13916 | @item @code{GL_POST_CONVOLUTION_COLOR_TABLE} | |
13917 | @code{glColorTable} | |
13918 | ||
13919 | @item @code{GL_RESCALE_NORMAL} | |
13920 | @code{glNormal} | |
13921 | ||
13922 | @item @code{GL_SAMPLE_ALPHA_TO_COVERAGE} | |
13923 | @code{glSampleCoverage} | |
13924 | ||
13925 | @item @code{GL_SAMPLE_ALPHA_TO_ONE} | |
13926 | @code{glSampleCoverage} | |
13927 | ||
13928 | @item @code{GL_SAMPLE_COVERAGE} | |
13929 | @code{glSampleCoverage} | |
13930 | ||
13931 | @item @code{GL_SCISSOR_TEST} | |
13932 | @code{glScissor} | |
13933 | ||
13934 | @item @code{GL_SECONDARY_COLOR_ARRAY} | |
13935 | @code{glSecondaryColorPointer} | |
13936 | ||
13937 | @item @code{GL_SEPARABLE_2D} | |
13938 | @code{glSeparableFilter2D} | |
13939 | ||
13940 | @item @code{GL_STENCIL_TEST} | |
13941 | @code{glStencilFunc}, @code{glStencilOp} | |
13942 | ||
13943 | @item @code{GL_TEXTURE_1D} | |
13944 | @code{glTexImage1D} | |
13945 | ||
13946 | @item @code{GL_TEXTURE_2D} | |
13947 | @code{glTexImage2D} | |
13948 | ||
13949 | @item @code{GL_TEXTURE_3D} | |
13950 | @code{glTexImage3D} | |
13951 | ||
13952 | @item @code{GL_TEXTURE_COORD_ARRAY} | |
13953 | @code{glTexCoordPointer} | |
13954 | ||
13955 | @item @code{GL_TEXTURE_CUBE_MAP} | |
13956 | @code{glTexImage2D} | |
13957 | ||
13958 | @item @code{GL_TEXTURE_GEN_Q} | |
13959 | @code{glTexGen} | |
13960 | ||
13961 | @item @code{GL_TEXTURE_GEN_R} | |
13962 | @code{glTexGen} | |
13963 | ||
13964 | @item @code{GL_TEXTURE_GEN_S} | |
13965 | @code{glTexGen} | |
13966 | ||
13967 | @item @code{GL_TEXTURE_GEN_T} | |
13968 | @code{glTexGen} | |
13969 | ||
13970 | @item @code{GL_VERTEX_ARRAY} | |
13971 | @code{glVertexPointer} | |
13972 | ||
13973 | @item @code{GL_VERTEX_PROGRAM_POINT_SIZE} | |
13974 | @code{glEnable} | |
13975 | ||
13976 | @item @code{GL_VERTEX_PROGRAM_TWO_SIDE} | |
13977 | @code{glEnable} | |
13978 | ||
13979 | @end table | |
13980 | ||
13981 | ||
13982 | ||
8925f36f AW |
13983 | @code{GL_INVALID_ENUM} is generated if @var{cap} is not an accepted |
13984 | value. | |
13985 | ||
13986 | @code{GL_INVALID_OPERATION} is generated if @code{glIsEnabled} is | |
13987 | executed between the execution of @code{glBegin} and the corresponding | |
13988 | execution of @code{glEnd}. | |
13989 | ||
bb894c9d | 13990 | @end deftypefun |
8925f36f | 13991 | |
bb894c9d | 13992 | @deftypefun GLboolean glIsList list |
3c9b6116 AW |
13993 | Determine if a name corresponds to a display list. |
13994 | ||
8925f36f AW |
13995 | @table @asis |
13996 | @item @var{list} | |
13997 | Specifies a potential display list name. | |
13998 | ||
13999 | @end table | |
14000 | ||
8925f36f AW |
14001 | @code{glIsList} returns @code{GL_TRUE} if @var{list} is the name of a |
14002 | display list and returns @code{GL_FALSE} if it is not, or if an error | |
14003 | occurs. | |
14004 | ||
14005 | A name returned by @code{glGenLists}, but not yet associated with a | |
14006 | display list by calling @code{glNewList}, is not the name of a display | |
14007 | list. | |
14008 | ||
8925f36f AW |
14009 | @code{GL_INVALID_OPERATION} is generated if @code{glIsList} is executed |
14010 | between the execution of @code{glBegin} and the corresponding execution | |
14011 | of @code{glEnd}. | |
14012 | ||
bb894c9d | 14013 | @end deftypefun |
8925f36f | 14014 | |
bb894c9d | 14015 | @deftypefun GLboolean glIsProgram program |
3c9b6116 AW |
14016 | Determines if a name corresponds to a program object. |
14017 | ||
8925f36f AW |
14018 | @table @asis |
14019 | @item @var{program} | |
14020 | Specifies a potential program object. | |
14021 | ||
14022 | @end table | |
14023 | ||
8925f36f AW |
14024 | @code{glIsProgram} returns @code{GL_TRUE} if @var{program} is the name |
14025 | of a program object previously created with @code{glCreateProgram} and | |
14026 | not yet deleted with @code{glDeleteProgram}. If @var{program} is zero or | |
14027 | a non-zero value that is not the name of a program object, or if an | |
14028 | error occurs, @code{glIsProgram} returns @code{GL_FALSE}. | |
14029 | ||
8925f36f AW |
14030 | @code{GL_INVALID_OPERATION} is generated if @code{glIsProgram} is |
14031 | executed between the execution of @code{glBegin} and the corresponding | |
14032 | execution of @code{glEnd}. | |
14033 | ||
bb894c9d | 14034 | @end deftypefun |
8925f36f | 14035 | |
bb894c9d | 14036 | @deftypefun GLboolean glIsQuery id |
3c9b6116 AW |
14037 | Determine if a name corresponds to a query object. |
14038 | ||
8925f36f AW |
14039 | @table @asis |
14040 | @item @var{id} | |
14041 | Specifies a value that may be the name of a query object. | |
14042 | ||
14043 | @end table | |
14044 | ||
8925f36f AW |
14045 | @code{glIsQuery} returns @code{GL_TRUE} if @var{id} is currently the |
14046 | name of a query object. If @var{id} is zero, or is a non-zero value that | |
14047 | is not currently the name of a query object, or if an error occurs, | |
14048 | @code{glIsQuery} returns @code{GL_FALSE}. | |
14049 | ||
14050 | A name returned by @code{glGenQueries}, but not yet associated with a | |
14051 | query object by calling @code{glBeginQuery}, is not the name of a query | |
14052 | object. | |
14053 | ||
8925f36f AW |
14054 | @code{GL_INVALID_OPERATION} is generated if @code{glIsQuery} is executed |
14055 | between the execution of @code{glBegin} and the corresponding execution | |
14056 | of @code{glEnd}. | |
14057 | ||
bb894c9d | 14058 | @end deftypefun |
8925f36f | 14059 | |
bb894c9d | 14060 | @deftypefun GLboolean glIsShader shader |
3c9b6116 AW |
14061 | Determines if a name corresponds to a shader object. |
14062 | ||
8925f36f AW |
14063 | @table @asis |
14064 | @item @var{shader} | |
14065 | Specifies a potential shader object. | |
14066 | ||
14067 | @end table | |
14068 | ||
8925f36f AW |
14069 | @code{glIsShader} returns @code{GL_TRUE} if @var{shader} is the name of |
14070 | a shader object previously created with @code{glCreateShader} and not | |
14071 | yet deleted with @code{glDeleteShader}. If @var{shader} is zero or a | |
14072 | non-zero value that is not the name of a shader object, or if an error | |
14073 | occurs, @code{glIsShader } returns @code{GL_FALSE}. | |
14074 | ||
8925f36f AW |
14075 | @code{GL_INVALID_OPERATION} is generated if @code{glIsShader} is |
14076 | executed between the execution of @code{glBegin} and the corresponding | |
14077 | execution of @code{glEnd}. | |
14078 | ||
bb894c9d | 14079 | @end deftypefun |
8925f36f | 14080 | |
bb894c9d | 14081 | @deftypefun GLboolean glIsTexture texture |
3c9b6116 AW |
14082 | Determine if a name corresponds to a texture. |
14083 | ||
8925f36f AW |
14084 | @table @asis |
14085 | @item @var{texture} | |
14086 | Specifies a value that may be the name of a texture. | |
14087 | ||
14088 | @end table | |
14089 | ||
8925f36f AW |
14090 | @code{glIsTexture} returns @code{GL_TRUE} if @var{texture} is currently |
14091 | the name of a texture. If @var{texture} is zero, or is a non-zero value | |
14092 | that is not currently the name of a texture, or if an error occurs, | |
14093 | @code{glIsTexture} returns @code{GL_FALSE}. | |
14094 | ||
14095 | A name returned by @code{glGenTextures}, but not yet associated with a | |
14096 | texture by calling @code{glBindTexture}, is not the name of a texture. | |
14097 | ||
8925f36f AW |
14098 | @code{GL_INVALID_OPERATION} is generated if @code{glIsTexture} is |
14099 | executed between the execution of @code{glBegin} and the corresponding | |
14100 | execution of @code{glEnd}. | |
14101 | ||
bb894c9d | 14102 | @end deftypefun |
8925f36f | 14103 | |
bb894c9d AW |
14104 | @deftypefun void glLightModelf pname param |
14105 | @deftypefunx void glLightModeli pname param | |
3c9b6116 AW |
14106 | Set the lighting model parameters. |
14107 | ||
8925f36f AW |
14108 | @table @asis |
14109 | @item @var{pname} | |
14110 | Specifies a single-valued lighting model parameter. | |
14111 | @code{GL_LIGHT_MODEL_LOCAL_VIEWER}, @code{GL_LIGHT_MODEL_COLOR_CONTROL}, | |
14112 | and @code{GL_LIGHT_MODEL_TWO_SIDE} are accepted. | |
14113 | ||
14114 | @item @var{param} | |
14115 | Specifies the value that @var{param} will be set to. | |
14116 | ||
14117 | @end table | |
14118 | ||
8925f36f AW |
14119 | @code{glLightModel} sets the lighting model parameter. @var{pname} names |
14120 | a parameter and @var{params} gives the new value. There are three | |
14121 | lighting model parameters: | |
14122 | ||
14123 | @table @asis | |
14124 | @item @code{GL_LIGHT_MODEL_AMBIENT} | |
14125 | ||
14126 | ||
14127 | @var{params} contains four integer or floating-point values that specify | |
14128 | the ambient RGBA intensity of the entire scene. Integer values are | |
14129 | mapped linearly such that the most positive representable value maps to | |
3c9b6116 | 14130 | 1.0, and the most negative representable value maps to @r{-1.0}. |
8925f36f AW |
14131 | Floating-point values are mapped directly. Neither integer nor |
14132 | floating-point values are clamped. The initial ambient scene intensity | |
14133 | is (0.2, 0.2, 0.2, 1.0). | |
14134 | ||
14135 | @item @code{GL_LIGHT_MODEL_COLOR_CONTROL} | |
14136 | ||
14137 | ||
14138 | @var{params} must be either @code{GL_SEPARATE_SPECULAR_COLOR} or | |
14139 | @code{GL_SINGLE_COLOR}. @code{GL_SINGLE_COLOR} specifies that a single | |
14140 | color is generated from the lighting computation for a vertex. | |
14141 | @code{GL_SEPARATE_SPECULAR_COLOR} specifies that the specular color | |
14142 | computation of lighting be stored separately from the remainder of the | |
14143 | lighting computation. The specular color is summed into the generated | |
14144 | fragment's color after the application of texture mapping (if enabled). | |
14145 | The initial value is @code{GL_SINGLE_COLOR}. | |
14146 | ||
14147 | @item @code{GL_LIGHT_MODEL_LOCAL_VIEWER} | |
14148 | ||
14149 | ||
14150 | @var{params} is a single integer or floating-point value that specifies | |
14151 | how specular reflection angles are computed. If @var{params} is 0 (or | |
14152 | 0.0), specular reflection angles take the view direction to be parallel | |
14153 | to and in the direction of the -@var{z} axis, regardless of the location | |
14154 | of the vertex in eye coordinates. Otherwise, specular reflections are | |
14155 | computed from the origin of the eye coordinate system. The initial value | |
14156 | is 0. | |
14157 | ||
14158 | @item @code{GL_LIGHT_MODEL_TWO_SIDE} | |
14159 | ||
14160 | ||
14161 | @var{params} is a single integer or floating-point value that specifies | |
14162 | whether one- or two-sided lighting calculations are done for polygons. | |
14163 | It has no effect on the lighting calculations for points, lines, or | |
14164 | bitmaps. If @var{params} is 0 (or 0.0), one-sided lighting is specified, | |
14165 | and only the @var{front} material parameters are used in the lighting | |
14166 | equation. Otherwise, two-sided lighting is specified. In this case, | |
14167 | vertices of back-facing polygons are lighted using the @var{back} | |
14168 | material parameters and have their normals reversed before the lighting | |
14169 | equation is evaluated. Vertices of front-facing polygons are always | |
14170 | lighted using the @var{front} material parameters, with no change to | |
14171 | their normals. The initial value is 0. | |
14172 | ||
14173 | @end table | |
14174 | ||
14175 | In RGBA mode, the lighted color of a vertex is the sum of the material | |
14176 | emission intensity, the product of the material ambient reflectance and | |
14177 | the lighting model full-scene ambient intensity, and the contribution of | |
14178 | each enabled light source. Each light source contributes the sum of | |
14179 | three terms: ambient, diffuse, and specular. The ambient light source | |
14180 | contribution is the product of the material ambient reflectance and the | |
14181 | light's ambient intensity. The diffuse light source contribution is the | |
14182 | product of the material diffuse reflectance, the light's diffuse | |
14183 | intensity, and the dot product of the vertex's normal with the | |
14184 | normalized vector from the vertex to the light source. The specular | |
14185 | light source contribution is the product of the material specular | |
14186 | reflectance, the light's specular intensity, and the dot product of the | |
14187 | normalized vertex-to-eye and vertex-to-light vectors, raised to the | |
14188 | power of the shininess of the material. All three light source | |
14189 | contributions are attenuated equally based on the distance from the | |
14190 | vertex to the light source and on light source direction, spread | |
14191 | exponent, and spread cutoff angle. All dot products are replaced with 0 | |
14192 | if they evaluate to a negative value. | |
14193 | ||
14194 | The alpha component of the resulting lighted color is set to the alpha | |
14195 | value of the material diffuse reflectance. | |
14196 | ||
14197 | In color index mode, the value of the lighted index of a vertex ranges | |
14198 | from the ambient to the specular values passed to @code{glMaterial} | |
14199 | using @code{GL_COLOR_INDEXES}. Diffuse and specular coefficients, | |
14200 | computed with a (.30, .59, .11) weighting of the lights' colors, the | |
14201 | shininess of the material, and the same reflection and attenuation | |
14202 | equations as in the RGBA case, determine how much above ambient the | |
14203 | resulting index is. | |
14204 | ||
8925f36f AW |
14205 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted |
14206 | value. | |
14207 | ||
14208 | @code{GL_INVALID_ENUM} is generated if @var{pname} is | |
14209 | @code{GL_LIGHT_MODEL_COLOR_CONTROL} and @var{params} is not one of | |
14210 | @code{GL_SINGLE_COLOR} or @code{GL_SEPARATE_SPECULAR_COLOR}. | |
14211 | ||
14212 | @code{GL_INVALID_OPERATION} is generated if @code{glLightModel} is | |
14213 | executed between the execution of @code{glBegin} and the corresponding | |
14214 | execution of @code{glEnd}. | |
14215 | ||
bb894c9d | 14216 | @end deftypefun |
8925f36f | 14217 | |
bb894c9d AW |
14218 | @deftypefun void glLightf light pname param |
14219 | @deftypefunx void glLighti light pname param | |
3c9b6116 AW |
14220 | Set light source parameters. |
14221 | ||
8925f36f AW |
14222 | @table @asis |
14223 | @item @var{light} | |
14224 | Specifies a light. The number of lights depends on the implementation, | |
14225 | but at least eight lights are supported. They are identified by symbolic | |
3c9b6116 AW |
14226 | names of the form @code{GL_LIGHT}@r{@var{i}}, where i ranges from 0 to |
14227 | the value of @code{GL_MAX_LIGHTS} - 1. | |
8925f36f AW |
14228 | |
14229 | @item @var{pname} | |
14230 | Specifies a single-valued light source parameter for @var{light}. | |
14231 | @code{GL_SPOT_EXPONENT}, @code{GL_SPOT_CUTOFF}, | |
14232 | @code{GL_CONSTANT_ATTENUATION}, @code{GL_LINEAR_ATTENUATION}, and | |
14233 | @code{GL_QUADRATIC_ATTENUATION} are accepted. | |
14234 | ||
14235 | @item @var{param} | |
14236 | Specifies the value that parameter @var{pname} of light source | |
14237 | @var{light} will be set to. | |
14238 | ||
14239 | @end table | |
14240 | ||
8925f36f AW |
14241 | @code{glLight} sets the values of individual light source parameters. |
14242 | @var{light} names the light and is a symbolic name of the form | |
3c9b6116 | 14243 | @code{GL_LIGHT}@r{@var{i}}, where i ranges from 0 to the value of |
8925f36f AW |
14244 | @code{GL_MAX_LIGHTS} - 1. @var{pname} specifies one of ten light source |
14245 | parameters, again by symbolic name. @var{params} is either a single | |
14246 | value or a pointer to an array that contains the new values. | |
14247 | ||
14248 | To enable and disable lighting calculation, call @code{glEnable} and | |
14249 | @code{glDisable} with argument @code{GL_LIGHTING}. Lighting is initially | |
14250 | disabled. When it is enabled, light sources that are enabled contribute | |
3c9b6116 | 14251 | to the lighting calculation. Light source @r{@var{i}} is enabled and |
8925f36f | 14252 | disabled using @code{glEnable} and @code{glDisable} with argument |
3c9b6116 | 14253 | @code{GL_LIGHT}@r{@var{i}}. |
8925f36f AW |
14254 | |
14255 | The ten light parameters are as follows: | |
14256 | ||
14257 | @table @asis | |
14258 | @item @code{GL_AMBIENT} | |
14259 | @var{params} contains four integer or floating-point values that specify | |
14260 | the ambient RGBA intensity of the light. Integer values are mapped | |
14261 | linearly such that the most positive representable value maps to 1.0, | |
3c9b6116 | 14262 | and the most negative representable value maps to @r{-1.0}. |
8925f36f AW |
14263 | Floating-point values are mapped directly. Neither integer nor |
14264 | floating-point values are clamped. The initial ambient light intensity | |
14265 | is (0, 0, 0, 1). | |
14266 | ||
14267 | @item @code{GL_DIFFUSE} | |
14268 | @var{params} contains four integer or floating-point values that specify | |
14269 | the diffuse RGBA intensity of the light. Integer values are mapped | |
14270 | linearly such that the most positive representable value maps to 1.0, | |
3c9b6116 | 14271 | and the most negative representable value maps to @r{-1.0}. |
8925f36f AW |
14272 | Floating-point values are mapped directly. Neither integer nor |
14273 | floating-point values are clamped. The initial value for | |
14274 | @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial value is | |
14275 | (0, 0, 0, 1). | |
14276 | ||
14277 | @item @code{GL_SPECULAR} | |
14278 | @var{params} contains four integer or floating-point values that specify | |
14279 | the specular RGBA intensity of the light. Integer values are mapped | |
14280 | linearly such that the most positive representable value maps to 1.0, | |
3c9b6116 | 14281 | and the most negative representable value maps to @r{-1.0}. |
8925f36f AW |
14282 | Floating-point values are mapped directly. Neither integer nor |
14283 | floating-point values are clamped. The initial value for | |
14284 | @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial value is | |
14285 | (0, 0, 0, 1). | |
14286 | ||
14287 | @item @code{GL_POSITION} | |
14288 | @var{params} contains four integer or floating-point values that specify | |
14289 | the position of the light in homogeneous object coordinates. Both | |
14290 | integer and floating-point values are mapped directly. Neither integer | |
14291 | nor floating-point values are clamped. | |
14292 | ||
14293 | The position is transformed by the modelview matrix when @code{glLight} | |
14294 | is called (just as if it were a point), and it is stored in eye | |
3c9b6116 | 14295 | coordinates. If the @r{@var{w}} component of the position is 0, the |
8925f36f AW |
14296 | light is treated as a directional source. Diffuse and specular lighting |
14297 | calculations take the light's direction, but not its actual position, | |
14298 | into account, and attenuation is disabled. Otherwise, diffuse and | |
14299 | specular lighting calculations are based on the actual location of the | |
14300 | light in eye coordinates, and attenuation is enabled. The initial | |
14301 | position is (0, 0, 1, 0); thus, the initial light source is directional, | |
3c9b6116 | 14302 | parallel to, and in the direction of the @r{-@var{z}} axis. |
8925f36f AW |
14303 | |
14304 | @item @code{GL_SPOT_DIRECTION} | |
14305 | @var{params} contains three integer or floating-point values that | |
14306 | specify the direction of the light in homogeneous object coordinates. | |
14307 | Both integer and floating-point values are mapped directly. Neither | |
14308 | integer nor floating-point values are clamped. | |
14309 | ||
14310 | The spot direction is transformed by the upper 3x3 of the modelview | |
14311 | matrix when @code{glLight} is called, and it is stored in eye | |
14312 | coordinates. It is significant only when @code{GL_SPOT_CUTOFF} is not | |
3c9b6116 | 14313 | 180, which it is initially. The initial direction is @r{(0,0-1)}. |
8925f36f AW |
14314 | |
14315 | @item @code{GL_SPOT_EXPONENT} | |
14316 | @var{params} is a single integer or floating-point value that specifies | |
14317 | the intensity distribution of the light. Integer and floating-point | |
3c9b6116 | 14318 | values are mapped directly. Only values in the range @r{[0,128]} are |
8925f36f AW |
14319 | accepted. |
14320 | ||
14321 | Effective light intensity is attenuated by the cosine of the angle | |
14322 | between the direction of the light and the direction from the light to | |
14323 | the vertex being lighted, raised to the power of the spot exponent. | |
14324 | Thus, higher spot exponents result in a more focused light source, | |
14325 | regardless of the spot cutoff angle (see @code{GL_SPOT_CUTOFF}, next | |
14326 | paragraph). The initial spot exponent is 0, resulting in uniform light | |
14327 | distribution. | |
14328 | ||
14329 | @item @code{GL_SPOT_CUTOFF} | |
14330 | @var{params} is a single integer or floating-point value that specifies | |
14331 | the maximum spread angle of a light source. Integer and floating-point | |
3c9b6116 AW |
14332 | values are mapped directly. Only values in the range @r{[0,90]} and the |
14333 | special value 180 are accepted. If the angle between the direction of | |
14334 | the light and the direction from the light to the vertex being lighted | |
14335 | is greater than the spot cutoff angle, the light is completely masked. | |
14336 | Otherwise, its intensity is controlled by the spot exponent and the | |
14337 | attenuation factors. The initial spot cutoff is 180, resulting in | |
8925f36f AW |
14338 | uniform light distribution. |
14339 | ||
14340 | @item @code{GL_CONSTANT_ATTENUATION} | |
14341 | @item @code{GL_LINEAR_ATTENUATION} | |
14342 | @item @code{GL_QUADRATIC_ATTENUATION} | |
14343 | @var{params} is a single integer or floating-point value that specifies | |
14344 | one of the three light attenuation factors. Integer and floating-point | |
14345 | values are mapped directly. Only nonnegative values are accepted. If the | |
14346 | light is positional, rather than directional, its intensity is | |
14347 | attenuated by the reciprocal of the sum of the constant factor, the | |
14348 | linear factor times the distance between the light and the vertex being | |
14349 | lighted, and the quadratic factor times the square of the same distance. | |
14350 | The initial attenuation factors are (1, 0, 0), resulting in no | |
14351 | attenuation. | |
14352 | ||
14353 | @end table | |
14354 | ||
8925f36f AW |
14355 | @code{GL_INVALID_ENUM} is generated if either @var{light} or @var{pname} |
14356 | is not an accepted value. | |
14357 | ||
14358 | @code{GL_INVALID_VALUE} is generated if a spot exponent value is | |
3c9b6116 AW |
14359 | specified outside the range @r{[0,128]}, or if spot cutoff is specified |
14360 | outside the range @r{[0,90]} (except for the special value 180), or if a | |
14361 | negative attenuation factor is specified. | |
8925f36f AW |
14362 | |
14363 | @code{GL_INVALID_OPERATION} is generated if @code{glLight} is executed | |
14364 | between the execution of @code{glBegin} and the corresponding execution | |
14365 | of @code{glEnd}. | |
14366 | ||
bb894c9d | 14367 | @end deftypefun |
8925f36f | 14368 | |
bb894c9d | 14369 | @deftypefun void glLineStipple factor pattern |
3c9b6116 AW |
14370 | Specify the line stipple pattern. |
14371 | ||
8925f36f AW |
14372 | @table @asis |
14373 | @item @var{factor} | |
14374 | Specifies a multiplier for each bit in the line stipple pattern. If | |
14375 | @var{factor} is 3, for example, each bit in the pattern is used three | |
14376 | times before the next bit in the pattern is used. @var{factor} is | |
14377 | clamped to the range [1, 256] and defaults to 1. | |
14378 | ||
14379 | @item @var{pattern} | |
14380 | Specifies a 16-bit integer whose bit pattern determines which fragments | |
14381 | of a line will be drawn when the line is rasterized. Bit zero is used | |
14382 | first; the default pattern is all 1's. | |
14383 | ||
14384 | @end table | |
14385 | ||
8925f36f AW |
14386 | Line stippling masks out certain fragments produced by rasterization; |
14387 | those fragments will not be drawn. The masking is achieved by using | |
14388 | three parameters: the 16-bit line stipple pattern @var{pattern}, the | |
3c9b6116 | 14389 | repeat count @var{factor}, and an integer stipple counter @r{@var{s}}. |
8925f36f | 14390 | |
3c9b6116 AW |
14391 | Counter @r{@var{s}} is reset to 0 whenever @code{glBegin} is called and |
14392 | before each line segment of a | |
8925f36f AW |
14393 | @code{glBegin}(@code{GL_LINES})/@code{glEnd} sequence is generated. It |
14394 | is incremented after each fragment of a unit width aliased line segment | |
3c9b6116 AW |
14395 | is generated or after each @r{@var{i}} fragments of an @r{@var{i}} width |
14396 | line segment are generated. The @r{@var{i}} fragments associated with | |
14397 | count @r{@var{s}} are masked out if | |
8925f36f | 14398 | |
3c9b6116 | 14399 | @var{pattern} bit @r{(@var{s}/@var{factor},)%16} |
8925f36f AW |
14400 | |
14401 | is 0, otherwise these fragments are sent to the frame buffer. Bit zero | |
14402 | of @var{pattern} is the least significant bit. | |
14403 | ||
3c9b6116 AW |
14404 | Antialiased lines are treated as a sequence of @r{1×@var{width}} |
14405 | rectangles for purposes of stippling. Whether rectangle @r{@var{s}} is | |
14406 | rasterized or not depends on the fragment rule described for aliased | |
8925f36f AW |
14407 | lines, counting rectangles rather than groups of fragments. |
14408 | ||
14409 | To enable and disable line stippling, call @code{glEnable} and | |
14410 | @code{glDisable} with argument @code{GL_LINE_STIPPLE}. When enabled, the | |
14411 | line stipple pattern is applied as described above. When disabled, it is | |
14412 | as if the pattern were all 1's. Initially, line stippling is disabled. | |
14413 | ||
8925f36f AW |
14414 | @code{GL_INVALID_OPERATION} is generated if @code{glLineStipple} is |
14415 | executed between the execution of @code{glBegin} and the corresponding | |
14416 | execution of @code{glEnd}. | |
14417 | ||
bb894c9d | 14418 | @end deftypefun |
8925f36f | 14419 | |
bb894c9d | 14420 | @deftypefun void glLineWidth width |
3c9b6116 AW |
14421 | Specify the width of rasterized lines. |
14422 | ||
8925f36f AW |
14423 | @table @asis |
14424 | @item @var{width} | |
14425 | Specifies the width of rasterized lines. The initial value is 1. | |
14426 | ||
14427 | @end table | |
14428 | ||
8925f36f AW |
14429 | @code{glLineWidth} specifies the rasterized width of both aliased and |
14430 | antialiased lines. Using a line width other than 1 has different | |
14431 | effects, depending on whether line antialiasing is enabled. To enable | |
14432 | and disable line antialiasing, call @code{glEnable} and @code{glDisable} | |
14433 | with argument @code{GL_LINE_SMOOTH}. Line antialiasing is initially | |
14434 | disabled. | |
14435 | ||
14436 | If line antialiasing is disabled, the actual width is determined by | |
14437 | rounding the supplied width to the nearest integer. (If the rounding | |
14438 | results in the value 0, it is as if the line width were 1.) If | |
3c9b6116 AW |
14439 | @r{∣Δ@var{x},∣>=∣Δ@var{y},∣}, @var{i} pixels are filled in each column |
14440 | that is rasterized, where @var{i} is the rounded value of @var{width}. | |
14441 | Otherwise, @var{i} pixels are filled in each row that is rasterized. | |
8925f36f AW |
14442 | |
14443 | If antialiasing is enabled, line rasterization produces a fragment for | |
14444 | each pixel square that intersects the region lying within the rectangle | |
14445 | having width equal to the current line width, length equal to the actual | |
14446 | length of the line, and centered on the mathematical line segment. The | |
14447 | coverage value for each fragment is the window coordinate area of the | |
14448 | intersection of the rectangular region with the corresponding pixel | |
14449 | square. This value is saved and used in the final rasterization step. | |
14450 | ||
14451 | Not all widths can be supported when line antialiasing is enabled. If an | |
14452 | unsupported width is requested, the nearest supported width is used. | |
14453 | Only width 1 is guaranteed to be supported; others depend on the | |
14454 | implementation. Likewise, there is a range for aliased line widths as | |
14455 | well. To query the range of supported widths and the size difference | |
14456 | between supported widths within the range, call @code{glGet} with | |
14457 | arguments @code{GL_ALIASED_LINE_WIDTH_RANGE}, | |
14458 | @code{GL_SMOOTH_LINE_WIDTH_RANGE}, and | |
14459 | @code{GL_SMOOTH_LINE_WIDTH_GRANULARITY}. | |
14460 | ||
8925f36f AW |
14461 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than or |
14462 | equal to 0. | |
14463 | ||
14464 | @code{GL_INVALID_OPERATION} is generated if @code{glLineWidth} is | |
14465 | executed between the execution of @code{glBegin} and the corresponding | |
14466 | execution of @code{glEnd}. | |
14467 | ||
bb894c9d | 14468 | @end deftypefun |
8925f36f | 14469 | |
bb894c9d | 14470 | @deftypefun void glLinkProgram program |
3c9b6116 AW |
14471 | Links a program object. |
14472 | ||
8925f36f AW |
14473 | @table @asis |
14474 | @item @var{program} | |
14475 | Specifies the handle of the program object to be linked. | |
14476 | ||
14477 | @end table | |
14478 | ||
8925f36f AW |
14479 | @code{glLinkProgram} links the program object specified by |
14480 | @var{program}. If any shader objects of type @code{GL_VERTEX_SHADER} are | |
14481 | attached to @var{program}, they will be used to create an executable | |
14482 | that will run on the programmable vertex processor. If any shader | |
14483 | objects of type @code{GL_FRAGMENT_SHADER} are attached to @var{program}, | |
14484 | they will be used to create an executable that will run on the | |
14485 | programmable fragment processor. | |
14486 | ||
14487 | The status of the link operation will be stored as part of the program | |
14488 | object's state. This value will be set to @code{GL_TRUE} if the program | |
14489 | object was linked without errors and is ready for use, and | |
14490 | @code{GL_FALSE} otherwise. It can be queried by calling | |
14491 | @code{glGetProgram} with arguments @var{program} and | |
14492 | @code{GL_LINK_STATUS}. | |
14493 | ||
14494 | As a result of a successful link operation, all active user-defined | |
14495 | uniform variables belonging to @var{program} will be initialized to 0, | |
14496 | and each of the program object's active uniform variables will be | |
14497 | assigned a location that can be queried by calling | |
14498 | @code{glGetUniformLocation}. Also, any active user-defined attribute | |
14499 | variables that have not been bound to a generic vertex attribute index | |
14500 | will be bound to one at this time. | |
14501 | ||
14502 | Linking of a program object can fail for a number of reasons as | |
14503 | specified in the @var{OpenGL Shading Language Specification}. The | |
14504 | following lists some of the conditions that will cause a link error. | |
14505 | ||
14506 | @itemize | |
14507 | @item | |
14508 | The number of active attribute variables supported by the implementation | |
14509 | has been exceeded. | |
14510 | ||
14511 | @item | |
14512 | The storage limit for uniform variables has been exceeded. | |
14513 | ||
14514 | @item | |
14515 | The number of active uniform variables supported by the implementation | |
14516 | has been exceeded. | |
14517 | ||
14518 | @item | |
14519 | The @code{main} function is missing for the vertex shader or the | |
14520 | fragment shader. | |
14521 | ||
14522 | @item | |
14523 | A varying variable actually used in the fragment shader is not declared | |
14524 | in the same way (or is not declared at all) in the vertex shader. | |
14525 | ||
14526 | @item | |
14527 | A reference to a function or variable name is unresolved. | |
14528 | ||
14529 | @item | |
14530 | A shared global is declared with two different types or two different | |
14531 | initial values. | |
14532 | ||
14533 | @item | |
14534 | One or more of the attached shader objects has not been successfully | |
14535 | compiled. | |
14536 | ||
14537 | @item | |
14538 | Binding a generic attribute matrix caused some rows of the matrix to | |
14539 | fall outside the allowed maximum of @code{GL_MAX_VERTEX_ATTRIBS}. | |
14540 | ||
14541 | @item | |
14542 | Not enough contiguous vertex attribute slots could be found to bind | |
14543 | attribute matrices. | |
14544 | ||
14545 | @end itemize | |
14546 | ||
14547 | When a program object has been successfully linked, the program object | |
14548 | can be made part of current state by calling @code{glUseProgram}. | |
14549 | Whether or not the link operation was successful, the program object's | |
14550 | information log will be overwritten. The information log can be | |
14551 | retrieved by calling @code{glGetProgramInfoLog}. | |
14552 | ||
14553 | @code{glLinkProgram} will also install the generated executables as part | |
14554 | of the current rendering state if the link operation was successful and | |
14555 | the specified program object is already currently in use as a result of | |
14556 | a previous call to @code{glUseProgram}. If the program object currently | |
14557 | in use is relinked unsuccessfully, its link status will be set to | |
14558 | @code{GL_FALSE} , but the executables and associated state will remain | |
14559 | part of the current state until a subsequent call to @code{glUseProgram} | |
14560 | removes it from use. After it is removed from use, it cannot be made | |
14561 | part of current state until it has been successfully relinked. | |
14562 | ||
14563 | If @var{program} contains shader objects of type @code{GL_VERTEX_SHADER} | |
14564 | but does not contain shader objects of type @code{GL_FRAGMENT_SHADER}, | |
14565 | the vertex shader will be linked against the implicit interface for | |
14566 | fixed functionality fragment processing. Similarly, if @var{program} | |
14567 | contains shader objects of type @code{GL_FRAGMENT_SHADER} but it does | |
14568 | not contain shader objects of type @code{GL_VERTEX_SHADER}, the fragment | |
14569 | shader will be linked against the implicit interface for fixed | |
14570 | functionality vertex processing. | |
14571 | ||
14572 | The program object's information log is updated and the program is | |
14573 | generated at the time of the link operation. After the link operation, | |
14574 | applications are free to modify attached shader objects, compile | |
14575 | attached shader objects, detach shader objects, delete shader objects, | |
14576 | and attach additional shader objects. None of these operations affects | |
14577 | the information log or the program that is part of the program object. | |
14578 | ||
8925f36f AW |
14579 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
14580 | generated by OpenGL. | |
14581 | ||
14582 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
14583 | program object. | |
14584 | ||
14585 | @code{GL_INVALID_OPERATION} is generated if @code{glLinkProgram} is | |
14586 | executed between the execution of @code{glBegin} and the corresponding | |
14587 | execution of @code{glEnd}. | |
14588 | ||
bb894c9d | 14589 | @end deftypefun |
8925f36f | 14590 | |
bb894c9d | 14591 | @deftypefun void glListBase base |
3c9b6116 AW |
14592 | Set the display-list base for . |
14593 | ||
8925f36f AW |
14594 | @table @asis |
14595 | @item @var{base} | |
14596 | Specifies an integer offset that will be added to @code{glCallLists} | |
14597 | offsets to generate display-list names. The initial value is 0. | |
14598 | ||
14599 | @end table | |
14600 | ||
8925f36f AW |
14601 | @code{glCallLists} specifies an array of offsets. Display-list names are |
14602 | generated by adding @var{base} to each offset. Names that reference | |
14603 | valid display lists are executed; the others are ignored. | |
14604 | ||
8925f36f AW |
14605 | @code{GL_INVALID_OPERATION} is generated if @code{glListBase} is |
14606 | executed between the execution of @code{glBegin} and the corresponding | |
14607 | execution of @code{glEnd}. | |
14608 | ||
bb894c9d | 14609 | @end deftypefun |
8925f36f | 14610 | |
bb894c9d | 14611 | @deftypefun void glLoadIdentity |
3c9b6116 AW |
14612 | Replace the current matrix with the identity matrix. |
14613 | ||
8925f36f AW |
14614 | @code{glLoadIdentity} replaces the current matrix with the identity |
14615 | matrix. It is semantically equivalent to calling @code{glLoadMatrix} | |
14616 | with the identity matrix | |
14617 | ||
14618 | ||
14619 | ||
3c9b6116 | 14620 | @r{((1 0 0 0), (0 1 0 0), (0 0 1 0), (0 0 0 1),,)} |
8925f36f AW |
14621 | |
14622 | ||
14623 | ||
14624 | but in some cases it is more efficient. | |
14625 | ||
8925f36f AW |
14626 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadIdentity} is |
14627 | executed between the execution of @code{glBegin} and the corresponding | |
14628 | execution of @code{glEnd}. | |
14629 | ||
bb894c9d | 14630 | @end deftypefun |
8925f36f | 14631 | |
ca09631c | 14632 | @deftypefun void glLoadMatrixf m |
3c9b6116 AW |
14633 | Replace the current matrix with the specified matrix. |
14634 | ||
8925f36f AW |
14635 | @table @asis |
14636 | @item @var{m} | |
14637 | Specifies a pointer to 16 consecutive values, which are used as the | |
3c9b6116 | 14638 | elements of a @r{4×4} column-major matrix. |
8925f36f AW |
14639 | |
14640 | @end table | |
14641 | ||
8925f36f AW |
14642 | @code{glLoadMatrix} replaces the current matrix with the one whose |
14643 | elements are specified by @var{m}. The current matrix is the projection | |
14644 | matrix, modelview matrix, or texture matrix, depending on the current | |
14645 | matrix mode (see @code{glMatrixMode}). | |
14646 | ||
14647 | The current matrix, M, defines a transformation of coordinates. For | |
14648 | instance, assume M refers to the modelview matrix. If | |
3c9b6116 AW |
14649 | @r{@var{v}=(@var{v}[0,],@var{v}[1,]@var{v}[2,]@var{v}[3,])} is the |
14650 | set of object coordinates of a vertex, and @var{m} points to an array of | |
14651 | @r{16} single- or double-precision floating-point values | |
14652 | @r{@var{m}=@{@var{m}[0,],@var{m}[1,]@var{...}@var{m}[15,]@}}, then | |
14653 | the modelview transformation @r{@var{M}(@var{v},)} does the following: | |
8925f36f | 14654 | |
3c9b6116 | 14655 | @r{@var{M}(@var{v},)=((@var{m}[0,] @var{m}[4,] @var{m}[8,] |
8925f36f AW |
14656 | @var{m}[12,]), (@var{m}[1,] @var{m}[5,] @var{m}[9,] @var{m}[13,]), |
14657 | (@var{m}[2,] @var{m}[6,] @var{m}[10,] @var{m}[14,]), (@var{m}[3,] | |
14658 | @var{m}[7,] @var{m}[11,] @var{m}[15,]),)×((@var{v}[0,]), | |
14659 | (@var{v}[1,]), (@var{v}[2,]), (@var{v}[3,]),)} | |
14660 | ||
14661 | ||
14662 | ||
14663 | Projection and texture transformations are similarly defined. | |
14664 | ||
8925f36f AW |
14665 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadMatrix} is |
14666 | executed between the execution of @code{glBegin} and the corresponding | |
14667 | execution of @code{glEnd}. | |
14668 | ||
bb894c9d | 14669 | @end deftypefun |
8925f36f | 14670 | |
bb894c9d | 14671 | @deftypefun void glLoadName name |
3c9b6116 AW |
14672 | Load a name onto the name stack. |
14673 | ||
8925f36f AW |
14674 | @table @asis |
14675 | @item @var{name} | |
14676 | Specifies a name that will replace the top value on the name stack. | |
14677 | ||
14678 | @end table | |
14679 | ||
8925f36f AW |
14680 | The name stack is used during selection mode to allow sets of rendering |
14681 | commands to be uniquely identified. It consists of an ordered set of | |
14682 | unsigned integers and is initially empty. | |
14683 | ||
14684 | @code{glLoadName} causes @var{name} to replace the value on the top of | |
14685 | the name stack. | |
14686 | ||
14687 | The name stack is always empty while the render mode is not | |
14688 | @code{GL_SELECT}. Calls to @code{glLoadName} while the render mode is | |
14689 | not @code{GL_SELECT} are ignored. | |
14690 | ||
8925f36f AW |
14691 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadName} is called |
14692 | while the name stack is empty. | |
14693 | ||
14694 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadName} is | |
14695 | executed between the execution of @code{glBegin} and the corresponding | |
14696 | execution of @code{glEnd}. | |
14697 | ||
bb894c9d | 14698 | @end deftypefun |
8925f36f | 14699 | |
ca09631c | 14700 | @deftypefun void glLoadTransposeMatrixf m |
3c9b6116 AW |
14701 | Replace the current matrix with the specified row-major ordered matrix. |
14702 | ||
8925f36f AW |
14703 | @table @asis |
14704 | @item @var{m} | |
14705 | Specifies a pointer to 16 consecutive values, which are used as the | |
3c9b6116 | 14706 | elements of a @r{4×4} row-major matrix. |
8925f36f AW |
14707 | |
14708 | @end table | |
14709 | ||
8925f36f AW |
14710 | @code{glLoadTransposeMatrix} replaces the current matrix with the one |
14711 | whose elements are specified by @var{m}. The current matrix is the | |
14712 | projection matrix, modelview matrix, or texture matrix, depending on the | |
14713 | current matrix mode (see @code{glMatrixMode}). | |
14714 | ||
14715 | The current matrix, M, defines a transformation of coordinates. For | |
14716 | instance, assume M refers to the modelview matrix. If | |
3c9b6116 AW |
14717 | @r{@var{v}=(@var{v}[0,],@var{v}[1,]@var{v}[2,]@var{v}[3,])} is the |
14718 | set of object coordinates of a vertex, and @var{m} points to an array of | |
14719 | @r{16} single- or double-precision floating-point values | |
14720 | @r{@var{m}=@{@var{m}[0,],@var{m}[1,]@var{...}@var{m}[15,]@}}, then | |
14721 | the modelview transformation @r{@var{M}(@var{v},)} does the following: | |
8925f36f | 14722 | |
3c9b6116 | 14723 | @r{@var{M}(@var{v},)=((@var{m}[0,] @var{m}[1,] @var{m}[2,] |
8925f36f AW |
14724 | @var{m}[3,]), (@var{m}[4,] @var{m}[5,] @var{m}[6,] @var{m}[7,]), |
14725 | (@var{m}[8,] @var{m}[9,] @var{m}[10,] @var{m}[11,]), (@var{m}[12,] | |
14726 | @var{m}[13,] @var{m}[14,] @var{m}[15,]),)×((@var{v}[0,]), | |
14727 | (@var{v}[1,]), (@var{v}[2,]), (@var{v}[3,]),)} | |
14728 | ||
14729 | ||
14730 | ||
14731 | Projection and texture transformations are similarly defined. | |
14732 | ||
3c9b6116 AW |
14733 | Calling @code{glLoadTransposeMatrix} with matrix @r{@var{M}} is |
14734 | identical in operation to @code{glLoadMatrix} with @r{@var{M}^@var{T}}, | |
14735 | where @r{@var{T}} represents the transpose. | |
8925f36f | 14736 | |
8925f36f AW |
14737 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadTransposeMatrix} |
14738 | is executed between the execution of @code{glBegin} and the | |
14739 | corresponding execution of @code{glEnd}. | |
14740 | ||
bb894c9d | 14741 | @end deftypefun |
8925f36f | 14742 | |
bb894c9d | 14743 | @deftypefun void glLogicOp opcode |
3c9b6116 AW |
14744 | Specify a logical pixel operation for color index rendering. |
14745 | ||
8925f36f AW |
14746 | @table @asis |
14747 | @item @var{opcode} | |
14748 | Specifies a symbolic constant that selects a logical operation. The | |
14749 | following symbols are accepted: @code{GL_CLEAR}, @code{GL_SET}, | |
14750 | @code{GL_COPY}, @code{GL_COPY_INVERTED}, @code{GL_NOOP}, | |
14751 | @code{GL_INVERT}, @code{GL_AND}, @code{GL_NAND}, @code{GL_OR}, | |
14752 | @code{GL_NOR}, @code{GL_XOR}, @code{GL_EQUIV}, @code{GL_AND_REVERSE}, | |
14753 | @code{GL_AND_INVERTED}, @code{GL_OR_REVERSE}, and @code{GL_OR_INVERTED}. | |
14754 | The initial value is @code{GL_COPY}. | |
14755 | ||
14756 | @end table | |
14757 | ||
8925f36f AW |
14758 | @code{glLogicOp} specifies a logical operation that, when enabled, is |
14759 | applied between the incoming color index or RGBA color and the color | |
14760 | index or RGBA color at the corresponding location in the frame buffer. | |
14761 | To enable or disable the logical operation, call @code{glEnable} and | |
14762 | @code{glDisable} using the symbolic constant @code{GL_COLOR_LOGIC_OP} | |
14763 | for RGBA mode or @code{GL_INDEX_LOGIC_OP} for color index mode. The | |
14764 | initial value is disabled for both operations. | |
14765 | ||
14766 | ||
14767 | ||
14768 | @table @asis | |
14769 | @item @strong{Opcode} | |
14770 | @strong{Resulting Operation} | |
14771 | ||
14772 | @item @code{GL_CLEAR} | |
14773 | 0 | |
14774 | ||
14775 | @item @code{GL_SET} | |
14776 | 1 | |
14777 | ||
14778 | @item @code{GL_COPY} | |
14779 | s | |
14780 | ||
14781 | @item @code{GL_COPY_INVERTED} | |
14782 | ~s | |
14783 | ||
14784 | @item @code{GL_NOOP} | |
14785 | d | |
14786 | ||
14787 | @item @code{GL_INVERT} | |
14788 | ~d | |
14789 | ||
14790 | @item @code{GL_AND} | |
14791 | s & d | |
14792 | ||
14793 | @item @code{GL_NAND} | |
14794 | ~(s & d) | |
14795 | ||
14796 | @item @code{GL_OR} | |
14797 | s | d | |
14798 | ||
14799 | @item @code{GL_NOR} | |
14800 | ~(s | d) | |
14801 | ||
14802 | @item @code{GL_XOR} | |
14803 | s ^ d | |
14804 | ||
14805 | @item @code{GL_EQUIV} | |
14806 | ~(s ^ d) | |
14807 | ||
14808 | @item @code{GL_AND_REVERSE} | |
14809 | s & ~d | |
14810 | ||
14811 | @item @code{GL_AND_INVERTED} | |
14812 | ~s & d | |
14813 | ||
14814 | @item @code{GL_OR_REVERSE} | |
14815 | s | ~d | |
14816 | ||
14817 | @item @code{GL_OR_INVERTED} | |
14818 | ~s | d | |
14819 | ||
14820 | @end table | |
14821 | ||
14822 | @var{opcode} is a symbolic constant chosen from the list above. In the | |
14823 | explanation of the logical operations, @var{s} represents the incoming | |
14824 | color index and @var{d} represents the index in the frame buffer. | |
14825 | Standard C-language operators are used. As these bitwise operators | |
14826 | suggest, the logical operation is applied independently to each bit pair | |
14827 | of the source and destination indices or colors. | |
14828 | ||
8925f36f AW |
14829 | @code{GL_INVALID_ENUM} is generated if @var{opcode} is not an accepted |
14830 | value. | |
14831 | ||
14832 | @code{GL_INVALID_OPERATION} is generated if @code{glLogicOp} is executed | |
14833 | between the execution of @code{glBegin} and the corresponding execution | |
14834 | of @code{glEnd}. | |
14835 | ||
bb894c9d | 14836 | @end deftypefun |
8925f36f | 14837 | |
ca09631c | 14838 | @deftypefun void glMap1f target u1 u2 stride order points |
3c9b6116 AW |
14839 | Define a one-dimensional evaluator. |
14840 | ||
8925f36f AW |
14841 | @table @asis |
14842 | @item @var{target} | |
14843 | Specifies the kind of values that are generated by the evaluator. | |
14844 | Symbolic constants @code{GL_MAP1_VERTEX_3}, @code{GL_MAP1_VERTEX_4}, | |
14845 | @code{GL_MAP1_INDEX}, @code{GL_MAP1_COLOR_4}, @code{GL_MAP1_NORMAL}, | |
14846 | @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2}, | |
14847 | @code{GL_MAP1_TEXTURE_COORD_3}, and @code{GL_MAP1_TEXTURE_COORD_4} are | |
14848 | accepted. | |
14849 | ||
14850 | @item @var{u1} | |
14851 | @itemx @var{u2} | |
3c9b6116 AW |
14852 | Specify a linear mapping of @r{@var{u}}, as presented to |
14853 | @code{glEvalCoord1}, to @r{@var{u}^}, the variable that is evaluated by | |
14854 | the equations specified by this command. | |
8925f36f AW |
14855 | |
14856 | @item @var{stride} | |
14857 | Specifies the number of floats or doubles between the beginning of one | |
14858 | control point and the beginning of the next one in the data structure | |
14859 | referenced in @var{points}. This allows control points to be embedded in | |
14860 | arbitrary data structures. The only constraint is that the values for a | |
14861 | particular control point must occupy contiguous memory locations. | |
14862 | ||
14863 | @item @var{order} | |
14864 | Specifies the number of control points. Must be positive. | |
14865 | ||
14866 | @item @var{points} | |
14867 | Specifies a pointer to the array of control points. | |
14868 | ||
14869 | @end table | |
14870 | ||
8925f36f AW |
14871 | Evaluators provide a way to use polynomial or rational polynomial |
14872 | mapping to produce vertices, normals, texture coordinates, and colors. | |
14873 | The values produced by an evaluator are sent to further stages of GL | |
14874 | processing just as if they had been presented using @code{glVertex}, | |
14875 | @code{glNormal}, @code{glTexCoord}, and @code{glColor} commands, except | |
14876 | that the generated values do not update the current normal, texture | |
14877 | coordinates, or color. | |
14878 | ||
14879 | All polynomial or rational polynomial splines of any degree (up to the | |
14880 | maximum degree supported by the GL implementation) can be described | |
14881 | using evaluators. These include almost all splines used in computer | |
14882 | graphics: B-splines, Bezier curves, Hermite splines, and so on. | |
14883 | ||
14884 | Evaluators define curves based on Bernstein polynomials. Define | |
3c9b6116 | 14885 | @r{@var{p}(@var{u}^,)} as |
8925f36f | 14886 | |
3c9b6116 | 14887 | @r{@var{p}(@var{u}^,)=Σ@var{i}=0@var{n}@var{B}_@var{i},^@var{n}(@var{u}^,)@var{R}_@var{i}} |
8925f36f AW |
14888 | |
14889 | ||
14890 | ||
3c9b6116 AW |
14891 | where @r{@var{R}_@var{i}} is a control point and |
14892 | @r{@var{B}_@var{i},^@var{n}(@var{u}^,)} is the @r{@var{i}}th Bernstein | |
14893 | polynomial of degree @r{@var{n}} (@var{order} = @r{@var{n}+1}): | |
8925f36f | 14894 | |
3c9b6116 | 14895 | @r{@var{B}_@var{i},^@var{n}(@var{u}^,)=((@var{n}), |
8925f36f AW |
14896 | (@var{i}),,)@var{u}^,^@var{i}(1-@var{u}^,)^@var{n}-@var{i},,} |
14897 | ||
14898 | Recall that | |
14899 | ||
3c9b6116 | 14900 | @r{0^0==1} and @r{((@var{n}), (0),,)==1} |
8925f36f AW |
14901 | |
14902 | @code{glMap1} is used to define the basis and to specify what kind of | |
14903 | values are produced. Once defined, a map can be enabled and disabled by | |
14904 | calling @code{glEnable} and @code{glDisable} with the map name, one of | |
14905 | the nine predefined values for @var{target} described below. | |
14906 | @code{glEvalCoord1} evaluates the one-dimensional maps that are enabled. | |
3c9b6116 AW |
14907 | When @code{glEvalCoord1} presents a value @r{@var{u}}, the Bernstein |
14908 | functions are evaluated using @r{@var{u}^}, where | |
14909 | @r{@var{u}^=@var{u}-@var{u1},/@var{u2}-@var{u1},} | |
8925f36f AW |
14910 | |
14911 | @var{target} is a symbolic constant that indicates what kind of control | |
14912 | points are provided in @var{points}, and what output is generated when | |
14913 | the map is evaluated. It can assume one of nine predefined values: | |
14914 | ||
14915 | @table @asis | |
14916 | @item @code{GL_MAP1_VERTEX_3} | |
14917 | Each control point is three floating-point values representing | |
3c9b6116 AW |
14918 | @r{@var{x}}, @r{@var{y}}, and @r{@var{z}}. Internal @code{glVertex3} |
14919 | commands are generated when the map is evaluated. | |
8925f36f AW |
14920 | |
14921 | @item @code{GL_MAP1_VERTEX_4} | |
14922 | Each control point is four floating-point values representing | |
3c9b6116 AW |
14923 | @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}. Internal |
14924 | @code{glVertex4} commands are generated when the map is evaluated. | |
8925f36f AW |
14925 | |
14926 | @item @code{GL_MAP1_INDEX} | |
14927 | Each control point is a single floating-point value representing a color | |
14928 | index. Internal @code{glIndex} commands are generated when the map is | |
14929 | evaluated but the current index is not updated with the value of these | |
14930 | @code{glIndex} commands. | |
14931 | ||
14932 | @item @code{GL_MAP1_COLOR_4} | |
14933 | Each control point is four floating-point values representing red, | |
14934 | green, blue, and alpha. Internal @code{glColor4} commands are generated | |
14935 | when the map is evaluated but the current color is not updated with the | |
14936 | value of these @code{glColor4} commands. | |
14937 | ||
14938 | @item @code{GL_MAP1_NORMAL} | |
14939 | Each control point is three floating-point values representing the | |
3c9b6116 AW |
14940 | @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} components of a normal vector. |
14941 | Internal @code{glNormal} commands are generated when the map is | |
14942 | evaluated but the current normal is not updated with the value of these | |
14943 | @code{glNormal} commands. | |
8925f36f AW |
14944 | |
14945 | @item @code{GL_MAP1_TEXTURE_COORD_1} | |
14946 | Each control point is a single floating-point value representing the | |
3c9b6116 AW |
14947 | @r{@var{s}} texture coordinate. Internal @code{glTexCoord1} commands are |
14948 | generated when the map is evaluated but the current texture coordinates | |
14949 | are not updated with the value of these @code{glTexCoord} commands. | |
8925f36f AW |
14950 | |
14951 | @item @code{GL_MAP1_TEXTURE_COORD_2} | |
14952 | Each control point is two floating-point values representing the | |
3c9b6116 | 14953 | @r{@var{s}} and @r{@var{t}} texture coordinates. Internal |
8925f36f AW |
14954 | @code{glTexCoord2} commands are generated when the map is evaluated but |
14955 | the current texture coordinates are not updated with the value of these | |
14956 | @code{glTexCoord} commands. | |
14957 | ||
14958 | @item @code{GL_MAP1_TEXTURE_COORD_3} | |
14959 | Each control point is three floating-point values representing the | |
3c9b6116 AW |
14960 | @r{@var{s}}, @r{@var{t}}, and @r{@var{r}} texture coordinates. Internal |
14961 | @code{glTexCoord3} commands are generated when the map is evaluated but | |
14962 | the current texture coordinates are not updated with the value of these | |
14963 | @code{glTexCoord} commands. | |
8925f36f AW |
14964 | |
14965 | @item @code{GL_MAP1_TEXTURE_COORD_4} | |
14966 | Each control point is four floating-point values representing the | |
3c9b6116 AW |
14967 | @r{@var{s}}, @r{@var{t}}, @r{@var{r}}, and @r{@var{q}} texture |
14968 | coordinates. Internal @code{glTexCoord4} commands are generated when the | |
14969 | map is evaluated but the current texture coordinates are not updated | |
14970 | with the value of these @code{glTexCoord} commands. | |
8925f36f AW |
14971 | |
14972 | @end table | |
14973 | ||
14974 | @var{stride}, @var{order}, and @var{points} define the array addressing | |
14975 | for accessing the control points. @var{points} is the location of the | |
14976 | first control point, which occupies one, two, three, or four contiguous | |
14977 | memory locations, depending on which map is being defined. @var{order} | |
14978 | is the number of control points in the array. @var{stride} specifies how | |
14979 | many float or double locations to advance the internal memory pointer to | |
14980 | reach the next control point. | |
14981 | ||
8925f36f AW |
14982 | @code{GL_INVALID_ENUM} is generated if @var{target} is not an accepted |
14983 | value. | |
14984 | ||
14985 | @code{GL_INVALID_VALUE} is generated if @var{u1} is equal to @var{u2}. | |
14986 | ||
14987 | @code{GL_INVALID_VALUE} is generated if @var{stride} is less than the | |
14988 | number of values in a control point. | |
14989 | ||
14990 | @code{GL_INVALID_VALUE} is generated if @var{order} is less than 1 or | |
14991 | greater than the return value of @code{GL_MAX_EVAL_ORDER}. | |
14992 | ||
14993 | @code{GL_INVALID_OPERATION} is generated if @code{glMap1} is executed | |
14994 | between the execution of @code{glBegin} and the corresponding execution | |
14995 | of @code{glEnd}. | |
14996 | ||
14997 | @code{GL_INVALID_OPERATION} is generated if @code{glMap1} is called and | |
14998 | the value of @code{GL_ACTIVE_TEXTURE} is not @code{GL_TEXTURE0}. | |
14999 | ||
bb894c9d | 15000 | @end deftypefun |
8925f36f | 15001 | |
ca09631c | 15002 | @deftypefun void glMap2f target u1 u2 ustride uorder v1 v2 vstride vorder points |
3c9b6116 AW |
15003 | Define a two-dimensional evaluator. |
15004 | ||
8925f36f AW |
15005 | @table @asis |
15006 | @item @var{target} | |
15007 | Specifies the kind of values that are generated by the evaluator. | |
15008 | Symbolic constants @code{GL_MAP2_VERTEX_3}, @code{GL_MAP2_VERTEX_4}, | |
15009 | @code{GL_MAP2_INDEX}, @code{GL_MAP2_COLOR_4}, @code{GL_MAP2_NORMAL}, | |
15010 | @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2}, | |
15011 | @code{GL_MAP2_TEXTURE_COORD_3}, and @code{GL_MAP2_TEXTURE_COORD_4} are | |
15012 | accepted. | |
15013 | ||
15014 | @item @var{u1} | |
15015 | @itemx @var{u2} | |
3c9b6116 AW |
15016 | Specify a linear mapping of @r{@var{u}}, as presented to |
15017 | @code{glEvalCoord2}, to @r{@var{u}^}, one of the two variables that are | |
15018 | evaluated by the equations specified by this command. Initially, | |
8925f36f AW |
15019 | @var{u1} is 0 and @var{u2} is 1. |
15020 | ||
15021 | @item @var{ustride} | |
15022 | Specifies the number of floats or doubles between the beginning of | |
3c9b6116 AW |
15023 | control point @r{@var{R}_@var{ij}} and the beginning of control point |
15024 | @r{@var{R}_(@var{i}+1,)@var{j},}, where @r{@var{i}} and @r{@var{j}} are | |
15025 | the @r{@var{u}} and @r{@var{v}} control point indices, respectively. | |
15026 | This allows control points to be embedded in arbitrary data structures. | |
15027 | The only constraint is that the values for a particular control point | |
15028 | must occupy contiguous memory locations. The initial value of | |
15029 | @var{ustride} is 0. | |
8925f36f AW |
15030 | |
15031 | @item @var{uorder} | |
3c9b6116 | 15032 | Specifies the dimension of the control point array in the @r{@var{u}} |
8925f36f AW |
15033 | axis. Must be positive. The initial value is 1. |
15034 | ||
15035 | @item @var{v1} | |
15036 | @itemx @var{v2} | |
3c9b6116 AW |
15037 | Specify a linear mapping of @r{@var{v}}, as presented to |
15038 | @code{glEvalCoord2}, to @r{@var{v}^}, one of the two variables that are | |
15039 | evaluated by the equations specified by this command. Initially, | |
8925f36f AW |
15040 | @var{v1} is 0 and @var{v2} is 1. |
15041 | ||
15042 | @item @var{vstride} | |
15043 | Specifies the number of floats or doubles between the beginning of | |
3c9b6116 AW |
15044 | control point @r{@var{R}_@var{ij}} and the beginning of control point |
15045 | @r{@var{R}_@var{i}(@var{j}+1,),}, where @r{@var{i}} and @r{@var{j}} are | |
15046 | the @r{@var{u}} and @r{@var{v}} control point indices, respectively. | |
15047 | This allows control points to be embedded in arbitrary data structures. | |
15048 | The only constraint is that the values for a particular control point | |
15049 | must occupy contiguous memory locations. The initial value of | |
15050 | @var{vstride} is 0. | |
8925f36f AW |
15051 | |
15052 | @item @var{vorder} | |
3c9b6116 | 15053 | Specifies the dimension of the control point array in the @r{@var{v}} |
8925f36f AW |
15054 | axis. Must be positive. The initial value is 1. |
15055 | ||
15056 | @item @var{points} | |
15057 | Specifies a pointer to the array of control points. | |
15058 | ||
15059 | @end table | |
15060 | ||
8925f36f AW |
15061 | Evaluators provide a way to use polynomial or rational polynomial |
15062 | mapping to produce vertices, normals, texture coordinates, and colors. | |
15063 | The values produced by an evaluator are sent on to further stages of GL | |
15064 | processing just as if they had been presented using @code{glVertex}, | |
15065 | @code{glNormal}, @code{glTexCoord}, and @code{glColor} commands, except | |
15066 | that the generated values do not update the current normal, texture | |
15067 | coordinates, or color. | |
15068 | ||
15069 | All polynomial or rational polynomial splines of any degree (up to the | |
15070 | maximum degree supported by the GL implementation) can be described | |
15071 | using evaluators. These include almost all surfaces used in computer | |
15072 | graphics, including B-spline surfaces, NURBS surfaces, Bezier surfaces, | |
15073 | and so on. | |
15074 | ||
15075 | Evaluators define surfaces based on bivariate Bernstein polynomials. | |
3c9b6116 | 15076 | Define @r{@var{p}(@var{u}^,@var{v}^)} as |
8925f36f | 15077 | |
3c9b6116 | 15078 | @r{@var{p}(@var{u}^,@var{v}^)=Σ@var{i}=0@var{n}Σ@var{j}=0@var{m}@var{B}_@var{i},^@var{n}(@var{u}^,)@var{B}_@var{j},^@var{m}(@var{v}^,)@var{R}_@var{ij}} |
8925f36f AW |
15079 | |
15080 | ||
15081 | ||
3c9b6116 AW |
15082 | where @r{@var{R}_@var{ij}} is a control point, |
15083 | @r{@var{B}_@var{i},^@var{n}(@var{u}^,)} is the @r{@var{i}}th Bernstein | |
15084 | polynomial of degree @r{@var{n}} (@var{uorder} = @r{@var{n}+1}) | |
8925f36f | 15085 | |
3c9b6116 | 15086 | @r{@var{B}_@var{i},^@var{n}(@var{u}^,)=((@var{n}), |
8925f36f AW |
15087 | (@var{i}),,)@var{u}^,^@var{i}(1-@var{u}^,)^@var{n}-@var{i},,} |
15088 | ||
3c9b6116 AW |
15089 | and @r{@var{B}_@var{j},^@var{m}(@var{v}^,)} is the @r{@var{j}}th |
15090 | Bernstein polynomial of degree @r{@var{m}} (@var{vorder} = | |
15091 | @r{@var{m}+1}) | |
8925f36f | 15092 | |
3c9b6116 | 15093 | @r{@var{B}_@var{j},^@var{m}(@var{v}^,)=((@var{m}), |
8925f36f AW |
15094 | (@var{j}),,)@var{v}^,^@var{j}(1-@var{v}^,)^@var{m}-@var{j},,} |
15095 | ||
3c9b6116 | 15096 | Recall that @r{0^0==1} and @r{((@var{n}), (0),,)==1} |
8925f36f AW |
15097 | |
15098 | @code{glMap2} is used to define the basis and to specify what kind of | |
15099 | values are produced. Once defined, a map can be enabled and disabled by | |
15100 | calling @code{glEnable} and @code{glDisable} with the map name, one of | |
15101 | the nine predefined values for @var{target}, described below. When | |
3c9b6116 AW |
15102 | @code{glEvalCoord2} presents values @r{@var{u}} and @r{@var{v}}, the |
15103 | bivariate Bernstein polynomials are evaluated using @r{@var{u}^} and | |
15104 | @r{@var{v}^}, where | |
8925f36f | 15105 | |
3c9b6116 | 15106 | @r{@var{u}^=@var{u}-@var{u1},/@var{u2}-@var{u1},} |
8925f36f | 15107 | |
3c9b6116 | 15108 | @r{@var{v}^=@var{v}-@var{v1},/@var{v2}-@var{v1},} |
8925f36f AW |
15109 | |
15110 | @var{target} is a symbolic constant that indicates what kind of control | |
15111 | points are provided in @var{points}, and what output is generated when | |
15112 | the map is evaluated. It can assume one of nine predefined values: | |
15113 | ||
15114 | @table @asis | |
15115 | @item @code{GL_MAP2_VERTEX_3} | |
15116 | Each control point is three floating-point values representing | |
3c9b6116 AW |
15117 | @r{@var{x}}, @r{@var{y}}, and @r{@var{z}}. Internal @code{glVertex3} |
15118 | commands are generated when the map is evaluated. | |
8925f36f AW |
15119 | |
15120 | @item @code{GL_MAP2_VERTEX_4} | |
15121 | Each control point is four floating-point values representing | |
3c9b6116 AW |
15122 | @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}. Internal |
15123 | @code{glVertex4} commands are generated when the map is evaluated. | |
8925f36f AW |
15124 | |
15125 | @item @code{GL_MAP2_INDEX} | |
15126 | Each control point is a single floating-point value representing a color | |
15127 | index. Internal @code{glIndex} commands are generated when the map is | |
15128 | evaluated but the current index is not updated with the value of these | |
15129 | @code{glIndex} commands. | |
15130 | ||
15131 | @item @code{GL_MAP2_COLOR_4} | |
15132 | Each control point is four floating-point values representing red, | |
15133 | green, blue, and alpha. Internal @code{glColor4} commands are generated | |
15134 | when the map is evaluated but the current color is not updated with the | |
15135 | value of these @code{glColor4} commands. | |
15136 | ||
15137 | @item @code{GL_MAP2_NORMAL} | |
15138 | Each control point is three floating-point values representing the | |
3c9b6116 AW |
15139 | @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} components of a normal vector. |
15140 | Internal @code{glNormal} commands are generated when the map is | |
15141 | evaluated but the current normal is not updated with the value of these | |
15142 | @code{glNormal} commands. | |
8925f36f AW |
15143 | |
15144 | @item @code{GL_MAP2_TEXTURE_COORD_1} | |
15145 | Each control point is a single floating-point value representing the | |
3c9b6116 AW |
15146 | @r{@var{s}} texture coordinate. Internal @code{glTexCoord1} commands are |
15147 | generated when the map is evaluated but the current texture coordinates | |
15148 | are not updated with the value of these @code{glTexCoord} commands. | |
8925f36f AW |
15149 | |
15150 | @item @code{GL_MAP2_TEXTURE_COORD_2} | |
15151 | Each control point is two floating-point values representing the | |
3c9b6116 | 15152 | @r{@var{s}} and @r{@var{t}} texture coordinates. Internal |
8925f36f AW |
15153 | @code{glTexCoord2} commands are generated when the map is evaluated but |
15154 | the current texture coordinates are not updated with the value of these | |
15155 | @code{glTexCoord} commands. | |
15156 | ||
15157 | @item @code{GL_MAP2_TEXTURE_COORD_3} | |
15158 | Each control point is three floating-point values representing the | |
3c9b6116 AW |
15159 | @r{@var{s}}, @r{@var{t}}, and @r{@var{r}} texture coordinates. Internal |
15160 | @code{glTexCoord3} commands are generated when the map is evaluated but | |
15161 | the current texture coordinates are not updated with the value of these | |
15162 | @code{glTexCoord} commands. | |
8925f36f AW |
15163 | |
15164 | @item @code{GL_MAP2_TEXTURE_COORD_4} | |
15165 | Each control point is four floating-point values representing the | |
3c9b6116 AW |
15166 | @r{@var{s}}, @r{@var{t}}, @r{@var{r}}, and @r{@var{q}} texture |
15167 | coordinates. Internal @code{glTexCoord4} commands are generated when the | |
15168 | map is evaluated but the current texture coordinates are not updated | |
15169 | with the value of these @code{glTexCoord} commands. | |
8925f36f AW |
15170 | |
15171 | @end table | |
15172 | ||
15173 | @var{ustride}, @var{uorder}, @var{vstride}, @var{vorder}, and | |
15174 | @var{points} define the array addressing for accessing the control | |
15175 | points. @var{points} is the location of the first control point, which | |
15176 | occupies one, two, three, or four contiguous memory locations, depending | |
3c9b6116 AW |
15177 | on which map is being defined. There are @r{@var{uorder}×@var{vorder}} |
15178 | control points in the array. @var{ustride} specifies how many float or | |
15179 | double locations are skipped to advance the internal memory pointer from | |
15180 | control point @r{@var{R}_@var{i}@var{j},} to control point | |
15181 | @r{@var{R}_(@var{i}+1,)@var{j},}. @var{vstride} specifies how many | |
8925f36f | 15182 | float or double locations are skipped to advance the internal memory |
3c9b6116 AW |
15183 | pointer from control point @r{@var{R}_@var{i}@var{j},} to control point |
15184 | @r{@var{R}_@var{i}(@var{j}+1,),}. | |
8925f36f | 15185 | |
8925f36f AW |
15186 | @code{GL_INVALID_ENUM} is generated if @var{target} is not an accepted |
15187 | value. | |
15188 | ||
15189 | @code{GL_INVALID_VALUE} is generated if @var{u1} is equal to @var{u2}, | |
15190 | or if @var{v1} is equal to @var{v2}. | |
15191 | ||
15192 | @code{GL_INVALID_VALUE} is generated if either @var{ustride} or | |
15193 | @var{vstride} is less than the number of values in a control point. | |
15194 | ||
15195 | @code{GL_INVALID_VALUE} is generated if either @var{uorder} or | |
15196 | @var{vorder} is less than 1 or greater than the return value of | |
15197 | @code{GL_MAX_EVAL_ORDER}. | |
15198 | ||
15199 | @code{GL_INVALID_OPERATION} is generated if @code{glMap2} is executed | |
15200 | between the execution of @code{glBegin} and the corresponding execution | |
15201 | of @code{glEnd}. | |
15202 | ||
15203 | @code{GL_INVALID_OPERATION} is generated if @code{glMap2} is called and | |
15204 | the value of @code{GL_ACTIVE_TEXTURE} is not @code{GL_TEXTURE0}. | |
15205 | ||
bb894c9d | 15206 | @end deftypefun |
8925f36f | 15207 | |
00239761 | 15208 | @deftypefun void-* glMapBuffer target access |
bb894c9d | 15209 | @deftypefunx GLboolean glUnmapBuffer target |
3c9b6116 AW |
15210 | Map a buffer object's data store. |
15211 | ||
8925f36f AW |
15212 | @table @asis |
15213 | @item @var{target} | |
15214 | Specifies the target buffer object being mapped. The symbolic constant | |
15215 | must be @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
15216 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
15217 | ||
15218 | @item @var{access} | |
15219 | Specifies the access policy, indicating whether it will be possible to | |
15220 | read from, write to, or both read from and write to the buffer object's | |
15221 | mapped data store. The symbolic constant must be @code{GL_READ_ONLY}, | |
15222 | @code{GL_WRITE_ONLY}, or @code{GL_READ_WRITE}. | |
15223 | ||
15224 | @end table | |
15225 | ||
8925f36f AW |
15226 | @code{glMapBuffer} maps to the client's address space the entire data |
15227 | store of the buffer object currently bound to @var{target}. The data can | |
15228 | then be directly read and/or written relative to the returned pointer, | |
15229 | depending on the specified @var{access} policy. If the GL is unable to | |
15230 | map the buffer object's data store, @code{glMapBuffer} generates an | |
15231 | error and returns @code{NULL}. This may occur for system-specific | |
15232 | reasons, such as low virtual memory availability. | |
15233 | ||
15234 | If a mapped data store is accessed in a way inconsistent with the | |
15235 | specified @var{access} policy, no error is generated, but performance | |
15236 | may be negatively impacted and system errors, including program | |
15237 | termination, may result. Unlike the @var{usage} parameter of | |
15238 | @code{glBufferData}, @var{access} is not a hint, and does in fact | |
15239 | constrain the usage of the mapped data store on some GL implementations. | |
15240 | In order to achieve the highest performance available, a buffer object's | |
15241 | data store should be used in ways consistent with both its specified | |
15242 | @var{usage} and @var{access} parameters. | |
15243 | ||
15244 | A mapped data store must be unmapped with @code{glUnmapBuffer} before | |
15245 | its buffer object is used. Otherwise an error will be generated by any | |
15246 | GL command that attempts to dereference the buffer object's data store. | |
15247 | When a data store is unmapped, the pointer to its data store becomes | |
15248 | invalid. @code{glUnmapBuffer} returns @code{GL_TRUE} unless the data | |
15249 | store contents have become corrupt during the time the data store was | |
15250 | mapped. This can occur for system-specific reasons that affect the | |
15251 | availability of graphics memory, such as screen mode changes. In such | |
15252 | situations, @code{GL_FALSE} is returned and the data store contents are | |
15253 | undefined. An application must detect this rare condition and | |
15254 | reinitialize the data store. | |
15255 | ||
15256 | A buffer object's mapped data store is automatically unmapped when the | |
15257 | buffer object is deleted or its data store is recreated with | |
15258 | @code{glBufferData}. | |
15259 | ||
8925f36f AW |
15260 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
15261 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
15262 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
15263 | ||
15264 | @code{GL_INVALID_ENUM} is generated if @var{access} is not | |
15265 | @code{GL_READ_ONLY}, @code{GL_WRITE_ONLY}, or @code{GL_READ_WRITE}. | |
15266 | ||
15267 | @code{GL_OUT_OF_MEMORY} is generated when @code{glMapBuffer} is executed | |
15268 | if the GL is unable to map the buffer object's data store. This may | |
15269 | occur for a variety of system-specific reasons, such as the absence of | |
15270 | sufficient remaining virtual memory. | |
15271 | ||
15272 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
15273 | name 0 is bound to @var{target}. | |
15274 | ||
15275 | @code{GL_INVALID_OPERATION} is generated if @code{glMapBuffer} is | |
15276 | executed for a buffer object whose data store is already mapped. | |
15277 | ||
15278 | @code{GL_INVALID_OPERATION} is generated if @code{glUnmapBuffer} is | |
15279 | executed for a buffer object whose data store is not currently mapped. | |
15280 | ||
15281 | @code{GL_INVALID_OPERATION} is generated if @code{glMapBuffer} or | |
15282 | @code{glUnmapBuffer} is executed between the execution of @code{glBegin} | |
15283 | and the corresponding execution of @code{glEnd}. | |
15284 | ||
bb894c9d | 15285 | @end deftypefun |
8925f36f | 15286 | |
ca09631c AW |
15287 | @deftypefun void glMapGrid1f un u1 u2 |
15288 | @deftypefunx void glMapGrid2f un u1 u2 vn v1 v2 | |
3c9b6116 AW |
15289 | Define a one- or two-dimensional mesh. |
15290 | ||
8925f36f AW |
15291 | @table @asis |
15292 | @item @var{un} | |
15293 | Specifies the number of partitions in the grid range interval [@var{u1}, | |
15294 | @var{u2}]. Must be positive. | |
15295 | ||
15296 | @item @var{u1} | |
15297 | @itemx @var{u2} | |
3c9b6116 AW |
15298 | Specify the mappings for integer grid domain values @r{@var{i}=0} and |
15299 | @r{@var{i}=@var{un}}. | |
8925f36f AW |
15300 | |
15301 | @item @var{vn} | |
15302 | Specifies the number of partitions in the grid range interval [@var{v1}, | |
15303 | @var{v2}] (@code{glMapGrid2} only). | |
15304 | ||
15305 | @item @var{v1} | |
15306 | @itemx @var{v2} | |
3c9b6116 AW |
15307 | Specify the mappings for integer grid domain values @r{@var{j}=0} and |
15308 | @r{@var{j}=@var{vn}} (@code{glMapGrid2} only). | |
8925f36f AW |
15309 | |
15310 | @end table | |
15311 | ||
8925f36f AW |
15312 | @code{glMapGrid} and @code{glEvalMesh} are used together to efficiently |
15313 | generate and evaluate a series of evenly-spaced map domain values. | |
15314 | @code{glEvalMesh} steps through the integer domain of a one- or | |
15315 | two-dimensional grid, whose range is the domain of the evaluation maps | |
15316 | specified by @code{glMap1} and @code{glMap2}. | |
15317 | ||
15318 | @code{glMapGrid1} and @code{glMapGrid2} specify the linear grid mappings | |
3c9b6116 AW |
15319 | between the @r{@var{i}} (or @r{@var{i}} and @r{@var{j}}) integer grid |
15320 | coordinates, to the @r{@var{u}} (or @r{@var{u}} and @r{@var{v}}) | |
15321 | floating-point evaluation map coordinates. See @code{glMap1} and | |
15322 | @code{glMap2} for details of how @r{@var{u}} and @r{@var{v}} coordinates | |
15323 | are evaluated. | |
8925f36f AW |
15324 | |
15325 | @code{glMapGrid1} specifies a single linear mapping such that integer | |
15326 | grid coordinate 0 maps exactly to @var{u1}, and integer grid coordinate | |
15327 | @var{un} maps exactly to @var{u2}. All other integer grid coordinates | |
3c9b6116 | 15328 | @r{@var{i}} are mapped so that |
8925f36f | 15329 | |
3c9b6116 | 15330 | @r{@var{u}=@var{i}(@var{u2}-@var{u1},)/@var{un}+@var{u1}} |
8925f36f AW |
15331 | |
15332 | @code{glMapGrid2} specifies two such linear mappings. One maps integer | |
3c9b6116 AW |
15333 | grid coordinate @r{@var{i}=0} exactly to @var{u1}, and integer grid |
15334 | coordinate @r{@var{i}=@var{un}} exactly to @var{u2}. The other maps | |
15335 | integer grid coordinate @r{@var{j}=0} exactly to @var{v1}, and integer | |
15336 | grid coordinate @r{@var{j}=@var{vn}} exactly to @var{v2}. Other integer | |
15337 | grid coordinates @r{@var{i}} and @r{@var{j}} are mapped such that | |
8925f36f | 15338 | |
3c9b6116 | 15339 | @r{@var{u}=@var{i}(@var{u2}-@var{u1},)/@var{un}+@var{u1}} |
8925f36f | 15340 | |
3c9b6116 | 15341 | @r{@var{v}=@var{j}(@var{v2}-@var{v1},)/@var{vn}+@var{v1}} |
8925f36f AW |
15342 | |
15343 | The mappings specified by @code{glMapGrid} are used identically by | |
15344 | @code{glEvalMesh} and @code{glEvalPoint}. | |
15345 | ||
8925f36f AW |
15346 | @code{GL_INVALID_VALUE} is generated if either @var{un} or @var{vn} is |
15347 | not positive. | |
15348 | ||
15349 | @code{GL_INVALID_OPERATION} is generated if @code{glMapGrid} is executed | |
15350 | between the execution of @code{glBegin} and the corresponding execution | |
15351 | of @code{glEnd}. | |
15352 | ||
bb894c9d | 15353 | @end deftypefun |
8925f36f | 15354 | |
bb894c9d AW |
15355 | @deftypefun void glMaterialf face pname param |
15356 | @deftypefunx void glMateriali face pname param | |
3c9b6116 AW |
15357 | Specify material parameters for the lighting model. |
15358 | ||
8925f36f AW |
15359 | @table @asis |
15360 | @item @var{face} | |
15361 | Specifies which face or faces are being updated. Must be one of | |
15362 | @code{GL_FRONT}, @code{GL_BACK}, or @code{GL_FRONT_AND_BACK}. | |
15363 | ||
15364 | @item @var{pname} | |
15365 | Specifies the single-valued material parameter of the face or faces that | |
15366 | is being updated. Must be @code{GL_SHININESS}. | |
15367 | ||
15368 | @item @var{param} | |
15369 | Specifies the value that parameter @code{GL_SHININESS} will be set to. | |
15370 | ||
15371 | @end table | |
15372 | ||
8925f36f AW |
15373 | @code{glMaterial} assigns values to material parameters. There are two |
15374 | matched sets of material parameters. One, the @var{front-facing} set, is | |
15375 | used to shade points, lines, bitmaps, and all polygons (when two-sided | |
15376 | lighting is disabled), or just front-facing polygons (when two-sided | |
15377 | lighting is enabled). The other set, @var{back-facing}, is used to shade | |
15378 | back-facing polygons only when two-sided lighting is enabled. Refer to | |
15379 | the @code{glLightModel} reference page for details concerning one- and | |
15380 | two-sided lighting calculations. | |
15381 | ||
15382 | @code{glMaterial} takes three arguments. The first, @var{face}, | |
15383 | specifies whether the @code{GL_FRONT} materials, the @code{GL_BACK} | |
15384 | materials, or both @code{GL_FRONT_AND_BACK} materials will be modified. | |
15385 | The second, @var{pname}, specifies which of several parameters in one or | |
15386 | both sets will be modified. The third, @var{params}, specifies what | |
15387 | value or values will be assigned to the specified parameter. | |
15388 | ||
15389 | Material parameters are used in the lighting equation that is optionally | |
15390 | applied to each vertex. The equation is discussed in the | |
15391 | @code{glLightModel} reference page. The parameters that can be specified | |
15392 | using @code{glMaterial}, and their interpretations by the lighting | |
15393 | equation, are as follows: | |
15394 | ||
15395 | @table @asis | |
15396 | @item @code{GL_AMBIENT} | |
15397 | @var{params} contains four integer or floating-point values that specify | |
15398 | the ambient RGBA reflectance of the material. Integer values are mapped | |
15399 | linearly such that the most positive representable value maps to 1.0, | |
3c9b6116 | 15400 | and the most negative representable value maps to @r{-1.0}. |
8925f36f AW |
15401 | Floating-point values are mapped directly. Neither integer nor |
15402 | floating-point values are clamped. The initial ambient reflectance for | |
15403 | both front- and back-facing materials is (0.2, 0.2, 0.2, 1.0). | |
15404 | ||
15405 | @item @code{GL_DIFFUSE} | |
15406 | @var{params} contains four integer or floating-point values that specify | |
15407 | the diffuse RGBA reflectance of the material. Integer values are mapped | |
15408 | linearly such that the most positive representable value maps to 1.0, | |
3c9b6116 | 15409 | and the most negative representable value maps to @r{-1.0}. |
8925f36f AW |
15410 | Floating-point values are mapped directly. Neither integer nor |
15411 | floating-point values are clamped. The initial diffuse reflectance for | |
15412 | both front- and back-facing materials is (0.8, 0.8, 0.8, 1.0). | |
15413 | ||
15414 | @item @code{GL_SPECULAR} | |
15415 | @var{params} contains four integer or floating-point values that specify | |
15416 | the specular RGBA reflectance of the material. Integer values are mapped | |
15417 | linearly such that the most positive representable value maps to 1.0, | |
3c9b6116 | 15418 | and the most negative representable value maps to @r{-1.0}. |
8925f36f AW |
15419 | Floating-point values are mapped directly. Neither integer nor |
15420 | floating-point values are clamped. The initial specular reflectance for | |
15421 | both front- and back-facing materials is (0, 0, 0, 1). | |
15422 | ||
15423 | @item @code{GL_EMISSION} | |
15424 | @var{params} contains four integer or floating-point values that specify | |
15425 | the RGBA emitted light intensity of the material. Integer values are | |
15426 | mapped linearly such that the most positive representable value maps to | |
3c9b6116 | 15427 | 1.0, and the most negative representable value maps to @r{-1.0}. |
8925f36f AW |
15428 | Floating-point values are mapped directly. Neither integer nor |
15429 | floating-point values are clamped. The initial emission intensity for | |
15430 | both front- and back-facing materials is (0, 0, 0, 1). | |
15431 | ||
15432 | @item @code{GL_SHININESS} | |
15433 | @var{params} is a single integer or floating-point value that specifies | |
15434 | the RGBA specular exponent of the material. Integer and floating-point | |
3c9b6116 | 15435 | values are mapped directly. Only values in the range @r{[0,128]} are |
8925f36f AW |
15436 | accepted. The initial specular exponent for both front- and back-facing |
15437 | materials is 0. | |
15438 | ||
15439 | @item @code{GL_AMBIENT_AND_DIFFUSE} | |
15440 | Equivalent to calling @code{glMaterial} twice with the same parameter | |
15441 | values, once with @code{GL_AMBIENT} and once with @code{GL_DIFFUSE}. | |
15442 | ||
15443 | @item @code{GL_COLOR_INDEXES} | |
15444 | @var{params} contains three integer or floating-point values specifying | |
15445 | the color indices for ambient, diffuse, and specular lighting. These | |
15446 | three values, and @code{GL_SHININESS}, are the only material values used | |
15447 | by the color index mode lighting equation. Refer to the | |
15448 | @code{glLightModel} reference page for a discussion of color index | |
15449 | lighting. | |
15450 | ||
15451 | @end table | |
15452 | ||
8925f36f AW |
15453 | @code{GL_INVALID_ENUM} is generated if either @var{face} or @var{pname} |
15454 | is not an accepted value. | |
15455 | ||
15456 | @code{GL_INVALID_VALUE} is generated if a specular exponent outside the | |
3c9b6116 | 15457 | range @r{[0,128]} is specified. |
8925f36f | 15458 | |
bb894c9d | 15459 | @end deftypefun |
8925f36f | 15460 | |
bb894c9d | 15461 | @deftypefun void glMatrixMode mode |
3c9b6116 AW |
15462 | Specify which matrix is the current matrix. |
15463 | ||
8925f36f AW |
15464 | @table @asis |
15465 | @item @var{mode} | |
15466 | Specifies which matrix stack is the target for subsequent matrix | |
15467 | operations. Three values are accepted: @code{GL_MODELVIEW}, | |
15468 | @code{GL_PROJECTION}, and @code{GL_TEXTURE}. The initial value is | |
15469 | @code{GL_MODELVIEW}. Additionally, if the @code{ARB_imaging} extension | |
15470 | is supported, @code{GL_COLOR} is also accepted. | |
15471 | ||
15472 | @end table | |
15473 | ||
8925f36f AW |
15474 | @code{glMatrixMode} sets the current matrix mode. @var{mode} can assume |
15475 | one of four values: | |
15476 | ||
15477 | @table @asis | |
15478 | @item @code{GL_MODELVIEW} | |
15479 | Applies subsequent matrix operations to the modelview matrix stack. | |
15480 | ||
15481 | @item @code{GL_PROJECTION} | |
15482 | Applies subsequent matrix operations to the projection matrix stack. | |
15483 | ||
15484 | @item @code{GL_TEXTURE} | |
15485 | Applies subsequent matrix operations to the texture matrix stack. | |
15486 | ||
15487 | @item @code{GL_COLOR} | |
15488 | Applies subsequent matrix operations to the color matrix stack. | |
15489 | ||
15490 | @end table | |
15491 | ||
15492 | To find out which matrix stack is currently the target of all matrix | |
15493 | operations, call @code{glGet} with argument @code{GL_MATRIX_MODE}. The | |
15494 | initial value is @code{GL_MODELVIEW}. | |
15495 | ||
8925f36f AW |
15496 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
15497 | value. | |
15498 | ||
15499 | @code{GL_INVALID_OPERATION} is generated if @code{glMatrixMode} is | |
15500 | executed between the execution of @code{glBegin} and the corresponding | |
15501 | execution of @code{glEnd}. | |
15502 | ||
bb894c9d | 15503 | @end deftypefun |
8925f36f | 15504 | |
bb894c9d | 15505 | @deftypefun void glMinmax target internalformat sink |
3c9b6116 AW |
15506 | Define minmax table. |
15507 | ||
8925f36f AW |
15508 | @table @asis |
15509 | @item @var{target} | |
15510 | The minmax table whose parameters are to be set. Must be | |
15511 | @code{GL_MINMAX}. | |
15512 | ||
15513 | @item @var{internalformat} | |
15514 | The format of entries in the minmax table. Must be one of | |
15515 | @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, | |
15516 | @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
15517 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
15518 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
15519 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
15520 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
15521 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
15522 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
15523 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
15524 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
15525 | @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
15526 | ||
15527 | @item @var{sink} | |
15528 | If @code{GL_TRUE}, pixels will be consumed by the minmax process and no | |
15529 | drawing or texture loading will take place. If @code{GL_FALSE}, pixels | |
15530 | will proceed to the final conversion process after minmax. | |
15531 | ||
15532 | @end table | |
15533 | ||
8925f36f AW |
15534 | When @code{GL_MINMAX} is enabled, the RGBA components of incoming pixels |
15535 | are compared to the minimum and maximum values for each component, which | |
15536 | are stored in the two-element minmax table. (The first element stores | |
15537 | the minima, and the second element stores the maxima.) If a pixel | |
15538 | component is greater than the corresponding component in the maximum | |
15539 | element, then the maximum element is updated with the pixel component | |
15540 | value. If a pixel component is less than the corresponding component in | |
15541 | the minimum element, then the minimum element is updated with the pixel | |
15542 | component value. (In both cases, if the internal format of the minmax | |
15543 | table includes luminance, then the R color component of incoming pixels | |
15544 | is used for comparison.) The contents of the minmax table may be | |
15545 | retrieved at a later time by calling @code{glGetMinmax}. The minmax | |
15546 | operation is enabled or disabled by calling @code{glEnable} or | |
15547 | @code{glDisable}, respectively, with an argument of @code{GL_MINMAX}. | |
15548 | ||
15549 | @code{glMinmax} redefines the current minmax table to have entries of | |
15550 | the format specified by @var{internalformat}. The maximum element is | |
15551 | initialized with the smallest possible component values, and the minimum | |
15552 | element is initialized with the largest possible component values. The | |
15553 | values in the previous minmax table, if any, are lost. If @var{sink} is | |
15554 | @code{GL_TRUE}, then pixels are discarded after minmax; no further | |
15555 | processing of the pixels takes place, and no drawing, texture loading, | |
15556 | or pixel readback will result. | |
15557 | ||
15558 | ||
15559 | ||
8925f36f AW |
15560 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
15561 | allowable values. | |
15562 | ||
15563 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
15564 | of the allowable values. | |
15565 | ||
15566 | @code{GL_INVALID_OPERATION} is generated if @code{glMinmax} is executed | |
15567 | between the execution of @code{glBegin} and the corresponding execution | |
15568 | of @code{glEnd}. | |
15569 | ||
bb894c9d | 15570 | @end deftypefun |
8925f36f | 15571 | |
bb894c9d | 15572 | @deftypefun void glMultiDrawArrays mode first count primcount |
3c9b6116 AW |
15573 | Render multiple sets of primitives from array data. |
15574 | ||
8925f36f AW |
15575 | @table @asis |
15576 | @item @var{mode} | |
15577 | Specifies what kind of primitives to render. Symbolic constants | |
15578 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, | |
15579 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
15580 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
15581 | @code{GL_POLYGON} are accepted. | |
15582 | ||
15583 | @item @var{first} | |
15584 | Points to an array of starting indices in the enabled arrays. | |
15585 | ||
15586 | @item @var{count} | |
15587 | Points to an array of the number of indices to be rendered. | |
15588 | ||
15589 | @item @var{primcount} | |
15590 | Specifies the size of the first and count | |
15591 | ||
15592 | @end table | |
15593 | ||
8925f36f AW |
15594 | @code{glMultiDrawArrays} specifies multiple sets of geometric primitives |
15595 | with very few subroutine calls. Instead of calling a GL procedure to | |
15596 | pass each individual vertex, normal, texture coordinate, edge flag, or | |
15597 | color, you can prespecify separate arrays of vertices, normals, and | |
15598 | colors and use them to construct a sequence of primitives with a single | |
15599 | call to @code{glMultiDrawArrays}. | |
15600 | ||
15601 | @code{glMultiDrawArrays} behaves identically to @code{glDrawArrays} | |
15602 | except that @var{primcount} separate ranges of elements are specified | |
15603 | instead. | |
15604 | ||
15605 | When @code{glMultiDrawArrays} is called, it uses @var{count} sequential | |
15606 | elements from each enabled array to construct a sequence of geometric | |
15607 | primitives, beginning with element @var{first}. @var{mode} specifies | |
15608 | what kind of primitives are constructed, and how the array elements | |
15609 | construct those primitives. If @code{GL_VERTEX_ARRAY} is not enabled, no | |
15610 | geometric primitives are generated. | |
15611 | ||
15612 | Vertex attributes that are modified by @code{glMultiDrawArrays} have an | |
15613 | unspecified value after @code{glMultiDrawArrays} returns. For example, | |
15614 | if @code{GL_COLOR_ARRAY} is enabled, the value of the current color is | |
15615 | undefined after @code{glMultiDrawArrays} executes. Attributes that | |
15616 | aren't modified remain well defined. | |
15617 | ||
8925f36f AW |
15618 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
15619 | value. | |
15620 | ||
15621 | @code{GL_INVALID_VALUE} is generated if @var{primcount} is negative. | |
15622 | ||
15623 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
15624 | name is bound to an enabled array and the buffer object's data store is | |
15625 | currently mapped. | |
15626 | ||
15627 | @code{GL_INVALID_OPERATION} is generated if @code{glMultiDrawArrays} is | |
15628 | executed between the execution of @code{glBegin} and the corresponding | |
15629 | @code{glEnd}. | |
15630 | ||
bb894c9d | 15631 | @end deftypefun |
8925f36f | 15632 | |
bb894c9d | 15633 | @deftypefun void glMultiDrawElements mode count type indices primcount |
3c9b6116 AW |
15634 | Render multiple sets of primitives by specifying indices of array data |
15635 | elements. | |
15636 | ||
8925f36f AW |
15637 | @table @asis |
15638 | @item @var{mode} | |
15639 | Specifies what kind of primitives to render. Symbolic constants | |
15640 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, | |
15641 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
15642 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
15643 | @code{GL_POLYGON} are accepted. | |
15644 | ||
15645 | @item @var{count} | |
15646 | Points to an array of the elements counts. | |
15647 | ||
15648 | @item @var{type} | |
15649 | Specifies the type of the values in @var{indices}. Must be one of | |
15650 | @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or | |
15651 | @code{GL_UNSIGNED_INT}. | |
15652 | ||
15653 | @item @var{indices} | |
15654 | Specifies a pointer to the location where the indices are stored. | |
15655 | ||
15656 | @item @var{primcount} | |
15657 | Specifies the size of the @var{count} array. | |
15658 | ||
15659 | @end table | |
15660 | ||
8925f36f AW |
15661 | @code{glMultiDrawElements} specifies multiple sets of geometric |
15662 | primitives with very few subroutine calls. Instead of calling a GL | |
15663 | function to pass each individual vertex, normal, texture coordinate, | |
15664 | edge flag, or color, you can prespecify separate arrays of vertices, | |
15665 | normals, and so on, and use them to construct a sequence of primitives | |
15666 | with a single call to @code{glMultiDrawElements}. | |
15667 | ||
15668 | @code{glMultiDrawElements} is identical in operation to | |
15669 | @code{glDrawElements} except that @var{primcount} separate lists of | |
15670 | elements are specified. | |
15671 | ||
15672 | Vertex attributes that are modified by @code{glMultiDrawElements} have | |
15673 | an unspecified value after @code{glMultiDrawElements} returns. For | |
15674 | example, if @code{GL_COLOR_ARRAY} is enabled, the value of the current | |
15675 | color is undefined after @code{glMultiDrawElements} executes. Attributes | |
15676 | that aren't modified maintain their previous values. | |
15677 | ||
8925f36f AW |
15678 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
15679 | value. | |
15680 | ||
15681 | @code{GL_INVALID_VALUE} is generated if @var{primcount} is negative. | |
15682 | ||
15683 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
15684 | name is bound to an enabled array or the element array and the buffer | |
15685 | object's data store is currently mapped. | |
15686 | ||
15687 | @code{GL_INVALID_OPERATION} is generated if @code{glMultiDrawElements} | |
15688 | is executed between the execution of @code{glBegin} and the | |
15689 | corresponding @code{glEnd}. | |
15690 | ||
bb894c9d | 15691 | @end deftypefun |
8925f36f | 15692 | |
bb894c9d | 15693 | @deftypefun void glMultiTexCoord1i target s |
ca09631c | 15694 | @deftypefunx void glMultiTexCoord1f target s |
bb894c9d | 15695 | @deftypefunx void glMultiTexCoord2i target s t |
ca09631c | 15696 | @deftypefunx void glMultiTexCoord2f target s t |
bb894c9d | 15697 | @deftypefunx void glMultiTexCoord3i target s t r |
ca09631c | 15698 | @deftypefunx void glMultiTexCoord3f target s t r |
bb894c9d | 15699 | @deftypefunx void glMultiTexCoord4i target s t r q |
ca09631c | 15700 | @deftypefunx void glMultiTexCoord4f target s t r q |
3c9b6116 AW |
15701 | Set the current texture coordinates. |
15702 | ||
8925f36f AW |
15703 | @table @asis |
15704 | @item @var{target} | |
15705 | Specifies the texture unit whose coordinates should be modified. The | |
15706 | number of texture units is implementation dependent, but must be at | |
15707 | least two. Symbolic constant must be one of | |
3c9b6116 | 15708 | @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to |
8925f36f AW |
15709 | @code{GL_MAX_TEXTURE_COORDS} - 1, which is an implementation-dependent |
15710 | value. | |
15711 | ||
15712 | @item @var{s} | |
15713 | @itemx @var{t} | |
15714 | @itemx @var{r} | |
15715 | @itemx @var{q} | |
15716 | Specify @var{s}, @var{t}, @var{r}, and @var{q} texture coordinates for | |
15717 | @var{target} texture unit. Not all parameters are present in all forms | |
15718 | of the command. | |
15719 | ||
15720 | @end table | |
15721 | ||
8925f36f AW |
15722 | @code{glMultiTexCoord} specifies texture coordinates in one, two, three, |
15723 | or four dimensions. @code{glMultiTexCoord1} sets the current texture | |
3c9b6116 AW |
15724 | coordinates to @r{(@var{s},001)}; a call to @code{glMultiTexCoord2} sets |
15725 | them to @r{(@var{s},@var{t}01)}. Similarly, @code{glMultiTexCoord3} | |
15726 | specifies the texture coordinates as @r{(@var{s},@var{t}@var{r}1)}, and | |
15727 | @code{glMultiTexCoord4} defines all four components explicitly as | |
15728 | @r{(@var{s},@var{t}@var{r}@var{q})}. | |
8925f36f AW |
15729 | |
15730 | The current texture coordinates are part of the data that is associated | |
15731 | with each vertex and with the current raster position. Initially, the | |
3c9b6116 | 15732 | values for @r{(@var{s},@var{t}@var{r}@var{q})} are @r{(0,001)}. |
8925f36f AW |
15733 | |
15734 | ||
15735 | ||
bb894c9d | 15736 | @end deftypefun |
8925f36f | 15737 | |
ca09631c | 15738 | @deftypefun void glMultMatrixf m |
3c9b6116 AW |
15739 | Multiply the current matrix with the specified matrix. |
15740 | ||
8925f36f AW |
15741 | @table @asis |
15742 | @item @var{m} | |
15743 | Points to 16 consecutive values that are used as the elements of a | |
3c9b6116 | 15744 | @r{4×4} column-major matrix. |
8925f36f AW |
15745 | |
15746 | @end table | |
15747 | ||
8925f36f AW |
15748 | @code{glMultMatrix} multiplies the current matrix with the one specified |
15749 | using @var{m}, and replaces the current matrix with the product. | |
15750 | ||
15751 | The current matrix is determined by the current matrix mode (see | |
15752 | @code{glMatrixMode}). It is either the projection matrix, modelview | |
15753 | matrix, or the texture matrix. | |
15754 | ||
8925f36f AW |
15755 | @code{GL_INVALID_OPERATION} is generated if @code{glMultMatrix} is |
15756 | executed between the execution of @code{glBegin} and the corresponding | |
15757 | execution of @code{glEnd}. | |
15758 | ||
bb894c9d | 15759 | @end deftypefun |
8925f36f | 15760 | |
ca09631c | 15761 | @deftypefun void glMultTransposeMatrixf m |
3c9b6116 AW |
15762 | Multiply the current matrix with the specified row-major ordered matrix. |
15763 | ||
8925f36f AW |
15764 | @table @asis |
15765 | @item @var{m} | |
15766 | Points to 16 consecutive values that are used as the elements of a | |
3c9b6116 | 15767 | @r{4×4} row-major matrix. |
8925f36f AW |
15768 | |
15769 | @end table | |
15770 | ||
8925f36f AW |
15771 | @code{glMultTransposeMatrix} multiplies the current matrix with the one |
15772 | specified using @var{m}, and replaces the current matrix with the | |
15773 | product. | |
15774 | ||
15775 | The current matrix is determined by the current matrix mode (see | |
15776 | @code{glMatrixMode}). It is either the projection matrix, modelview | |
15777 | matrix, or the texture matrix. | |
15778 | ||
8925f36f AW |
15779 | @code{GL_INVALID_OPERATION} is generated if @code{glMultTransposeMatrix} |
15780 | is executed between the execution of @code{glBegin} and the | |
15781 | corresponding execution of @code{glEnd}. | |
15782 | ||
bb894c9d | 15783 | @end deftypefun |
8925f36f | 15784 | |
bb894c9d AW |
15785 | @deftypefun void glNewList list mode |
15786 | @deftypefunx void glEndList | |
3c9b6116 AW |
15787 | Create or replace a display list. |
15788 | ||
8925f36f AW |
15789 | @table @asis |
15790 | @item @var{list} | |
15791 | Specifies the display-list name. | |
15792 | ||
15793 | @item @var{mode} | |
15794 | Specifies the compilation mode, which can be @code{GL_COMPILE} or | |
15795 | @code{GL_COMPILE_AND_EXECUTE}. | |
15796 | ||
15797 | @end table | |
15798 | ||
8925f36f AW |
15799 | Display lists are groups of GL commands that have been stored for |
15800 | subsequent execution. Display lists are created with @code{glNewList}. | |
15801 | All subsequent commands are placed in the display list, in the order | |
15802 | issued, until @code{glEndList} is called. | |
15803 | ||
15804 | @code{glNewList} has two arguments. The first argument, @var{list}, is a | |
15805 | positive integer that becomes the unique name for the display list. | |
15806 | Names can be created and reserved with @code{glGenLists} and tested for | |
15807 | uniqueness with @code{glIsList}. The second argument, @var{mode}, is a | |
15808 | symbolic constant that can assume one of two values: | |
15809 | ||
15810 | @table @asis | |
15811 | @item @code{GL_COMPILE} | |
15812 | Commands are merely compiled. | |
15813 | ||
15814 | @item @code{GL_COMPILE_AND_EXECUTE} | |
15815 | Commands are executed as they are compiled into the display list. | |
15816 | ||
15817 | @end table | |
15818 | ||
15819 | Certain commands are not compiled into the display list but are executed | |
15820 | immediately, regardless of the display-list mode. These commands are | |
15821 | @code{glAreTexturesResident}, @code{glColorPointer}, | |
15822 | @code{glDeleteLists}, @code{glDeleteTextures}, | |
15823 | @code{glDisableClientState}, @code{glEdgeFlagPointer}, | |
15824 | @code{glEnableClientState}, @code{glFeedbackBuffer}, @code{glFinish}, | |
15825 | @code{glFlush}, @code{glGenLists}, @code{glGenTextures}, | |
15826 | @code{glIndexPointer}, @code{glInterleavedArrays}, @code{glIsEnabled}, | |
15827 | @code{glIsList}, @code{glIsTexture}, @code{glNormalPointer}, | |
15828 | @code{glPopClientAttrib}, @code{glPixelStore}, | |
15829 | @code{glPushClientAttrib}, @code{glReadPixels}, @code{glRenderMode}, | |
15830 | @code{glSelectBuffer}, @code{glTexCoordPointer}, @code{glVertexPointer}, | |
15831 | and all of the @code{glGet} commands. | |
15832 | ||
15833 | Similarly, @code{glTexImage1D}, @code{glTexImage2D}, and | |
15834 | @code{glTexImage3D} are executed immediately and not compiled into the | |
15835 | display list when their first argument is @code{GL_PROXY_TEXTURE_1D}, | |
15836 | @code{GL_PROXY_TEXTURE_1D}, or @code{GL_PROXY_TEXTURE_3D}, respectively. | |
15837 | ||
15838 | When the @code{ARB_imaging} extension is supported, @code{glHistogram} | |
15839 | executes immediately when its argument is @code{GL_PROXY_HISTOGRAM}. | |
15840 | Similarly, @code{glColorTable} executes immediately when its first | |
15841 | argument is @code{GL_PROXY_COLOR_TABLE}, | |
15842 | @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or | |
15843 | @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}. | |
15844 | ||
15845 | For OpenGL versions 1.3 and greater, or when the @code{ARB_multitexture} | |
15846 | extension is supported, @code{glClientActiveTexture} is not compiled | |
15847 | into display lists, but executed immediately. | |
15848 | ||
15849 | When @code{glEndList} is encountered, the display-list definition is | |
15850 | completed by associating the list with the unique name @var{list} | |
15851 | (specified in the @code{glNewList} command). If a display list with name | |
15852 | @var{list} already exists, it is replaced only when @code{glEndList} is | |
15853 | called. | |
15854 | ||
8925f36f AW |
15855 | @code{GL_INVALID_VALUE} is generated if @var{list} is 0. |
15856 | ||
15857 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted | |
15858 | value. | |
15859 | ||
15860 | @code{GL_INVALID_OPERATION} is generated if @code{glEndList} is called | |
15861 | without a preceding @code{glNewList}, or if @code{glNewList} is called | |
15862 | while a display list is being defined. | |
15863 | ||
15864 | @code{GL_INVALID_OPERATION} is generated if @code{glNewList} or | |
15865 | @code{glEndList} is executed between the execution of @code{glBegin} and | |
15866 | the corresponding execution of @code{glEnd}. | |
15867 | ||
15868 | @code{GL_OUT_OF_MEMORY} is generated if there is insufficient memory to | |
15869 | compile the display list. If the GL version is 1.1 or greater, no change | |
15870 | is made to the previous contents of the display list, if any, and no | |
15871 | other change is made to the GL state. (It is as if no attempt had been | |
15872 | made to create the new display list.) | |
15873 | ||
bb894c9d | 15874 | @end deftypefun |
8925f36f | 15875 | |
bb894c9d | 15876 | @deftypefun void glNormalPointer type stride pointer |
3c9b6116 AW |
15877 | Define an array of normals. |
15878 | ||
8925f36f AW |
15879 | @table @asis |
15880 | @item @var{type} | |
15881 | Specifies the data type of each coordinate in the array. Symbolic | |
15882 | constants @code{GL_BYTE}, @code{GL_SHORT}, @code{GL_INT}, | |
15883 | @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value is | |
15884 | @code{GL_FLOAT}. | |
15885 | ||
15886 | @item @var{stride} | |
15887 | Specifies the byte offset between consecutive normals. If @var{stride} | |
15888 | is 0, the normals are understood to be tightly packed in the array. The | |
15889 | initial value is 0. | |
15890 | ||
15891 | @item @var{pointer} | |
15892 | Specifies a pointer to the first coordinate of the first normal in the | |
15893 | array. The initial value is 0. | |
15894 | ||
15895 | @end table | |
15896 | ||
8925f36f AW |
15897 | @code{glNormalPointer} specifies the location and data format of an |
15898 | array of normals to use when rendering. @var{type} specifies the data | |
15899 | type of each normal coordinate, and @var{stride} specifies the byte | |
15900 | stride from one normal to the next, allowing vertices and attributes to | |
15901 | be packed into a single array or stored in separate arrays. | |
15902 | (Single-array storage may be more efficient on some implementations; see | |
15903 | @code{glInterleavedArrays}.) | |
15904 | ||
15905 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
15906 | target (see @code{glBindBuffer}) while a normal array is specified, | |
15907 | @var{pointer} is treated as a byte offset into the buffer object's data | |
15908 | store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING}) | |
15909 | is saved as normal vertex array client-side state | |
15910 | (@code{GL_NORMAL_ARRAY_BUFFER_BINDING}). | |
15911 | ||
15912 | When a normal array is specified, @var{type}, @var{stride}, and | |
15913 | @var{pointer} are saved as client-side state, in addition to the current | |
15914 | vertex array buffer object binding. | |
15915 | ||
15916 | To enable and disable the normal array, call @code{glEnableClientState} | |
15917 | and @code{glDisableClientState} with the argument | |
15918 | @code{GL_NORMAL_ARRAY}. If enabled, the normal array is used when | |
15919 | @code{glDrawArrays}, @code{glMultiDrawArrays}, @code{glDrawElements}, | |
15920 | @code{glMultiDrawElements}, @code{glDrawRangeElements}, or | |
15921 | @code{glArrayElement} is called. | |
15922 | ||
8925f36f AW |
15923 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted |
15924 | value. | |
15925 | ||
15926 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
15927 | ||
bb894c9d | 15928 | @end deftypefun |
8925f36f | 15929 | |
ca09631c | 15930 | @deftypefun void glNormal3f nx ny nz |
bb894c9d | 15931 | @deftypefunx void glNormal3i nx ny nz |
3c9b6116 AW |
15932 | Set the current normal vector. |
15933 | ||
8925f36f AW |
15934 | @table @asis |
15935 | @item @var{nx} | |
15936 | @itemx @var{ny} | |
15937 | @itemx @var{nz} | |
3c9b6116 AW |
15938 | Specify the @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} coordinates of the |
15939 | new current normal. The initial value of the current normal is the unit | |
15940 | vector, (0, 0, 1). | |
8925f36f AW |
15941 | |
15942 | ||
15943 | ||
15944 | @end table | |
15945 | ||
8925f36f AW |
15946 | The current normal is set to the given coordinates whenever |
15947 | @code{glNormal} is issued. Byte, short, or integer arguments are | |
15948 | converted to floating-point format with a linear mapping that maps the | |
15949 | most positive representable integer value to 1.0 and the most negative | |
3c9b6116 | 15950 | representable integer value to @r{-1.0}. |
8925f36f AW |
15951 | |
15952 | Normals specified with @code{glNormal} need not have unit length. If | |
15953 | @code{GL_NORMALIZE} is enabled, then normals of any length specified | |
15954 | with @code{glNormal} are normalized after transformation. If | |
15955 | @code{GL_RESCALE_NORMAL} is enabled, normals are scaled by a scaling | |
15956 | factor derived from the modelview matrix. @code{GL_RESCALE_NORMAL} | |
15957 | requires that the originally specified normals were of unit length, and | |
15958 | that the modelview matrix contain only uniform scales for proper | |
15959 | results. To enable and disable normalization, call @code{glEnable} and | |
15960 | @code{glDisable} with either @code{GL_NORMALIZE} or | |
15961 | @code{GL_RESCALE_NORMAL}. Normalization is initially disabled. | |
15962 | ||
bb894c9d | 15963 | @end deftypefun |
8925f36f | 15964 | |
bb894c9d | 15965 | @deftypefun void glOrtho left right bottom top nearVal farVal |
3c9b6116 AW |
15966 | Multiply the current matrix with an orthographic matrix. |
15967 | ||
8925f36f AW |
15968 | @table @asis |
15969 | @item @var{left} | |
15970 | @itemx @var{right} | |
15971 | Specify the coordinates for the left and right vertical clipping planes. | |
15972 | ||
15973 | @item @var{bottom} | |
15974 | @itemx @var{top} | |
15975 | Specify the coordinates for the bottom and top horizontal clipping | |
15976 | planes. | |
15977 | ||
15978 | @item @var{nearVal} | |
15979 | @itemx @var{farVal} | |
15980 | Specify the distances to the nearer and farther depth clipping planes. | |
15981 | These values are negative if the plane is to be behind the viewer. | |
15982 | ||
15983 | @end table | |
15984 | ||
8925f36f AW |
15985 | @code{glOrtho} describes a transformation that produces a parallel |
15986 | projection. The current matrix (see @code{glMatrixMode}) is multiplied | |
15987 | by this matrix and the result replaces the current matrix, as if | |
15988 | @code{glMultMatrix} were called with the following matrix as its | |
15989 | argument: | |
15990 | ||
3c9b6116 | 15991 | @r{((2/@var{right}-@var{left},, 0 0 @var{t}_@var{x},), (0 |
8925f36f AW |
15992 | 2/@var{top}-@var{bottom},, 0 @var{t}_@var{y},), (0 0 |
15993 | -2/@var{farVal}-@var{nearVal},, @var{t}_@var{z},), (0 0 0 1),)} | |
15994 | ||
15995 | where | |
3c9b6116 | 15996 | @r{@var{t}_@var{x}=-@var{right}+@var{left},/@var{right}-@var{left},,}@r{@var{t}_@var{y}=-@var{top}+@var{bottom},/@var{top}-@var{bottom},,}@r{@var{t}_@var{z}=-@var{farVal}+@var{nearVal},/@var{farVal}-@var{nearVal},,} |
8925f36f AW |
15997 | |
15998 | Typically, the matrix mode is @code{GL_PROJECTION}, and | |
3c9b6116 AW |
15999 | @r{(@var{left},@var{bottom}-@var{nearVal})} and |
16000 | @r{(@var{right},@var{top}-@var{nearVal})} specify the points on the near | |
16001 | clipping plane that are mapped to the lower left and upper right corners | |
16002 | of the window, respectively, assuming that the eye is located at (0, 0, | |
16003 | 0). @r{-@var{farVal}} specifies the location of the far clipping plane. | |
16004 | Both @var{nearVal} and @var{farVal} can be either positive or negative. | |
8925f36f AW |
16005 | |
16006 | Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the | |
16007 | current matrix stack. | |
16008 | ||
8925f36f AW |
16009 | @code{GL_INVALID_VALUE} is generated if @var{left} = @var{right}, or |
16010 | @var{bottom} = @var{top}, or @var{near} = @var{far}. | |
16011 | ||
16012 | @code{GL_INVALID_OPERATION} is generated if @code{glOrtho} is executed | |
16013 | between the execution of @code{glBegin} and the corresponding execution | |
16014 | of @code{glEnd}. | |
16015 | ||
bb894c9d | 16016 | @end deftypefun |
8925f36f | 16017 | |
bb894c9d | 16018 | @deftypefun void glPassThrough token |
3c9b6116 AW |
16019 | Place a marker in the feedback buffer. |
16020 | ||
8925f36f AW |
16021 | @table @asis |
16022 | @item @var{token} | |
16023 | Specifies a marker value to be placed in the feedback buffer following a | |
16024 | @code{GL_PASS_THROUGH_TOKEN}. | |
16025 | ||
16026 | @end table | |
16027 | ||
8925f36f AW |
16028 | |
16029 | ||
16030 | Feedback is a GL render mode. The mode is selected by calling | |
16031 | @code{glRenderMode} with @code{GL_FEEDBACK}. When the GL is in feedback | |
16032 | mode, no pixels are produced by rasterization. Instead, information | |
16033 | about primitives that would have been rasterized is fed back to the | |
16034 | application using the GL. See the @code{glFeedbackBuffer} reference page | |
16035 | for a description of the feedback buffer and the values in it. | |
16036 | ||
16037 | @code{glPassThrough} inserts a user-defined marker in the feedback | |
16038 | buffer when it is executed in feedback mode. @var{token} is returned as | |
16039 | if it were a primitive; it is indicated with its own unique identifying | |
16040 | value: @code{GL_PASS_THROUGH_TOKEN}. The order of @code{glPassThrough} | |
16041 | commands with respect to the specification of graphics primitives is | |
16042 | maintained. | |
16043 | ||
8925f36f AW |
16044 | @code{GL_INVALID_OPERATION} is generated if @code{glPassThrough} is |
16045 | executed between the execution of @code{glBegin} and the corresponding | |
16046 | execution of @code{glEnd}. | |
16047 | ||
bb894c9d | 16048 | @end deftypefun |
8925f36f | 16049 | |
b002944d AW |
16050 | @deftypefun void glPixelMapfv map mapsize values |
16051 | @deftypefunx void glPixelMapuiv map mapsize values | |
16052 | Set up pixel transfer maps. | |
16053 | ||
16054 | @table @asis | |
16055 | @item @var{map} | |
16056 | Specifies a symbolic map name. Must be one of the following: | |
16057 | @code{GL_PIXEL_MAP_I_TO_I}, @code{GL_PIXEL_MAP_S_TO_S}, | |
16058 | @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G}, | |
16059 | @code{GL_PIXEL_MAP_I_TO_B}, @code{GL_PIXEL_MAP_I_TO_A}, | |
16060 | @code{GL_PIXEL_MAP_R_TO_R}, @code{GL_PIXEL_MAP_G_TO_G}, | |
16061 | @code{GL_PIXEL_MAP_B_TO_B}, or @code{GL_PIXEL_MAP_A_TO_A}. | |
16062 | ||
16063 | @item @var{mapsize} | |
16064 | Specifies the size of the map being defined. | |
16065 | ||
16066 | @item @var{values} | |
16067 | Specifies an array of @var{mapsize} values. | |
16068 | ||
16069 | @end table | |
16070 | ||
16071 | @code{glPixelMap} sets up translation tables, or @var{maps}, used by | |
16072 | @code{glCopyPixels}, @code{glCopyTexImage1D}, @code{glCopyTexImage2D}, | |
16073 | @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D}, | |
16074 | @code{glCopyTexSubImage3D}, @code{glDrawPixels}, @code{glReadPixels}, | |
16075 | @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D}, | |
16076 | @code{glTexSubImage1D}, @code{glTexSubImage2D}, and | |
16077 | @code{glTexSubImage3D}. Additionally, if the @code{ARB_imaging} subset | |
16078 | is supported, the routines @code{glColorTable}, @code{glColorSubTable}, | |
16079 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, | |
16080 | @code{glHistogram}, @code{glMinmax}, and @code{glSeparableFilter2D}. Use | |
16081 | of these maps is described completely in the @code{glPixelTransfer} | |
16082 | reference page, and partly in the reference pages for the pixel and | |
16083 | texture image commands. Only the specification of the maps is described | |
16084 | in this reference page. | |
16085 | ||
16086 | @var{map} is a symbolic map name, indicating one of ten maps to set. | |
16087 | @var{mapsize} specifies the number of entries in the map, and | |
16088 | @var{values} is a pointer to an array of @var{mapsize} map values. | |
16089 | ||
16090 | If a non-zero named buffer object is bound to the | |
16091 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
16092 | pixel transfer map is specified, @var{values} is treated as a byte | |
16093 | offset into the buffer object's data store. | |
16094 | ||
16095 | The ten maps are as follows: | |
16096 | ||
16097 | @table @asis | |
16098 | @item @code{GL_PIXEL_MAP_I_TO_I} | |
16099 | Maps color indices to color indices. | |
16100 | ||
16101 | @item @code{GL_PIXEL_MAP_S_TO_S} | |
16102 | Maps stencil indices to stencil indices. | |
16103 | ||
16104 | @item @code{GL_PIXEL_MAP_I_TO_R} | |
16105 | Maps color indices to red components. | |
16106 | ||
16107 | @item @code{GL_PIXEL_MAP_I_TO_G} | |
16108 | Maps color indices to green components. | |
16109 | ||
16110 | @item @code{GL_PIXEL_MAP_I_TO_B} | |
16111 | Maps color indices to blue components. | |
16112 | ||
16113 | @item @code{GL_PIXEL_MAP_I_TO_A} | |
16114 | Maps color indices to alpha components. | |
16115 | ||
16116 | @item @code{GL_PIXEL_MAP_R_TO_R} | |
16117 | Maps red components to red components. | |
16118 | ||
16119 | @item @code{GL_PIXEL_MAP_G_TO_G} | |
16120 | Maps green components to green components. | |
16121 | ||
16122 | @item @code{GL_PIXEL_MAP_B_TO_B} | |
16123 | Maps blue components to blue components. | |
16124 | ||
16125 | @item @code{GL_PIXEL_MAP_A_TO_A} | |
16126 | Maps alpha components to alpha components. | |
16127 | ||
16128 | @end table | |
16129 | ||
16130 | The entries in a map can be specified as single-precision floating-point | |
16131 | numbers, unsigned short integers, or unsigned int integers. Maps that | |
16132 | store color component values (all but @code{GL_PIXEL_MAP_I_TO_I} and | |
16133 | @code{GL_PIXEL_MAP_S_TO_S}) retain their values in floating-point | |
16134 | format, with unspecified mantissa and exponent sizes. Floating-point | |
16135 | values specified by @code{glPixelMapfv} are converted directly to the | |
16136 | internal floating-point format of these maps, then clamped to the range | |
16137 | [0,1]. Unsigned integer values specified by @code{glPixelMapusv} and | |
16138 | @code{glPixelMapuiv} are converted linearly such that the largest | |
16139 | representable integer maps to 1.0, and 0 maps to 0.0. | |
16140 | ||
16141 | Maps that store indices, @code{GL_PIXEL_MAP_I_TO_I} and | |
16142 | @code{GL_PIXEL_MAP_S_TO_S}, retain their values in fixed-point format, | |
16143 | with an unspecified number of bits to the right of the binary point. | |
16144 | Floating-point values specified by @code{glPixelMapfv} are converted | |
16145 | directly to the internal fixed-point format of these maps. Unsigned | |
16146 | integer values specified by @code{glPixelMapusv} and | |
16147 | @code{glPixelMapuiv} specify integer values, with all 0's to the right | |
16148 | of the binary point. | |
16149 | ||
16150 | The following table shows the initial sizes and values for each of the | |
16151 | maps. Maps that are indexed by either color or stencil indices must have | |
16152 | @var{mapsize} = @r{2^@var{n}} for some @r{@var{n}} or the results are | |
16153 | undefined. The maximum allowable size for each map depends on the | |
16154 | implementation and can be determined by calling @code{glGet} with | |
16155 | argument @code{GL_MAX_PIXEL_MAP_TABLE}. The single maximum applies to | |
16156 | all maps; it is at least 32. | |
16157 | ||
16158 | @table @asis | |
16159 | @item @strong{@var{map}} | |
16160 | @strong{Lookup Index}, @strong{Lookup Value}, @strong{Initial Size}, | |
16161 | @strong{Initial Value} | |
16162 | ||
16163 | @item @code{GL_PIXEL_MAP_I_TO_I} | |
16164 | color index , color index , 1 , 0 | |
16165 | ||
16166 | @item @code{GL_PIXEL_MAP_S_TO_S} | |
16167 | stencil index , stencil index , 1 , 0 | |
16168 | ||
16169 | @item @code{GL_PIXEL_MAP_I_TO_R} | |
16170 | color index , R , 1 , 0 | |
16171 | ||
16172 | @item @code{GL_PIXEL_MAP_I_TO_G} | |
16173 | color index , G , 1 , 0 | |
16174 | ||
16175 | @item @code{GL_PIXEL_MAP_I_TO_B} | |
16176 | color index , B , 1 , 0 | |
16177 | ||
16178 | @item @code{GL_PIXEL_MAP_I_TO_A} | |
16179 | color index , A , 1 , 0 | |
16180 | ||
16181 | @item @code{GL_PIXEL_MAP_R_TO_R} | |
16182 | R , R , 1 , 0 | |
16183 | ||
16184 | @item @code{GL_PIXEL_MAP_G_TO_G} | |
16185 | G , G , 1 , 0 | |
16186 | ||
16187 | @item @code{GL_PIXEL_MAP_B_TO_B} | |
16188 | B , B , 1 , 0 | |
16189 | ||
16190 | @item @code{GL_PIXEL_MAP_A_TO_A} | |
16191 | A , A , 1 , 0 | |
16192 | ||
16193 | @end table | |
16194 | ||
16195 | @code{GL_INVALID_ENUM} is generated if @var{map} is not an accepted | |
16196 | value. | |
16197 | ||
16198 | @code{GL_INVALID_VALUE} is generated if @var{mapsize} is less than one | |
16199 | or larger than @code{GL_MAX_PIXEL_MAP_TABLE}. | |
16200 | ||
16201 | @code{GL_INVALID_VALUE} is generated if @var{map} is | |
16202 | @code{GL_PIXEL_MAP_I_TO_I}, @code{GL_PIXEL_MAP_S_TO_S}, | |
16203 | @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G}, | |
16204 | @code{GL_PIXEL_MAP_I_TO_B}, or @code{GL_PIXEL_MAP_I_TO_A}, and | |
16205 | @var{mapsize} is not a power of two. | |
16206 | ||
16207 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
16208 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
16209 | object's data store is currently mapped. | |
16210 | ||
16211 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
16212 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
16213 | would be unpacked from the buffer object such that the memory reads | |
16214 | required would exceed the data store size. | |
16215 | ||
16216 | @code{GL_INVALID_OPERATION} is generated by @code{glPixelMapfv} if a | |
16217 | non-zero buffer object name is bound to the | |
16218 | @code{GL_PIXEL_UNPACK_BUFFER} target and @var{values} is not evenly | |
16219 | divisible into the number of bytes needed to store in memory a GLfloat | |
16220 | datum. | |
16221 | ||
16222 | @code{GL_INVALID_OPERATION} is generated by @code{glPixelMapuiv} if a | |
16223 | non-zero buffer object name is bound to the | |
16224 | @code{GL_PIXEL_UNPACK_BUFFER} target and @var{values} is not evenly | |
16225 | divisible into the number of bytes needed to store in memory a GLuint | |
16226 | datum. | |
16227 | ||
16228 | @code{GL_INVALID_OPERATION} is generated by @code{glPixelMapusv} if a | |
16229 | non-zero buffer object name is bound to the | |
16230 | @code{GL_PIXEL_UNPACK_BUFFER} target and @var{values} is not evenly | |
16231 | divisible into the number of bytes needed to store in memory a GLushort | |
16232 | datum. | |
16233 | ||
16234 | @code{GL_INVALID_OPERATION} is generated if @code{glPixelMap} is | |
16235 | executed between the execution of @code{glBegin} and the corresponding | |
16236 | execution of @code{glEnd}. | |
16237 | ||
16238 | @end deftypefun | |
16239 | ||
bb894c9d AW |
16240 | @deftypefun void glPixelStoref pname param |
16241 | @deftypefunx void glPixelStorei pname param | |
3c9b6116 AW |
16242 | Set pixel storage modes. |
16243 | ||
8925f36f AW |
16244 | @table @asis |
16245 | @item @var{pname} | |
16246 | Specifies the symbolic name of the parameter to be set. Six values | |
16247 | affect the packing of pixel data into memory: @code{GL_PACK_SWAP_BYTES}, | |
16248 | @code{GL_PACK_LSB_FIRST}, @code{GL_PACK_ROW_LENGTH}, | |
16249 | @code{GL_PACK_IMAGE_HEIGHT}, @code{GL_PACK_SKIP_PIXELS}, | |
16250 | @code{GL_PACK_SKIP_ROWS}, @code{GL_PACK_SKIP_IMAGES}, and | |
16251 | @code{GL_PACK_ALIGNMENT}. Six more affect the unpacking of pixel data | |
16252 | @var{from} memory: @code{GL_UNPACK_SWAP_BYTES}, | |
16253 | @code{GL_UNPACK_LSB_FIRST}, @code{GL_UNPACK_ROW_LENGTH}, | |
16254 | @code{GL_UNPACK_IMAGE_HEIGHT}, @code{GL_UNPACK_SKIP_PIXELS}, | |
16255 | @code{GL_UNPACK_SKIP_ROWS}, @code{GL_UNPACK_SKIP_IMAGES}, and | |
16256 | @code{GL_UNPACK_ALIGNMENT}. | |
16257 | ||
16258 | @item @var{param} | |
16259 | Specifies the value that @var{pname} is set to. | |
16260 | ||
16261 | @end table | |
16262 | ||
8925f36f AW |
16263 | @code{glPixelStore} sets pixel storage modes that affect the operation |
16264 | of subsequent @code{glDrawPixels} and @code{glReadPixels} as well as the | |
16265 | unpacking of polygon stipple patterns (see @code{glPolygonStipple}), | |
16266 | bitmaps (see @code{glBitmap}), texture patterns (see | |
16267 | @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D}, | |
16268 | @code{glTexSubImage1D}, @code{glTexSubImage2D}, @code{glTexSubImage3D}). | |
16269 | Additionally, if the @code{ARB_imaging} extension is supported, pixel | |
16270 | storage modes affect convolution filters (see | |
16271 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and | |
16272 | @code{glSeparableFilter2D}, color table (see @code{glColorTable}, and | |
16273 | @code{glColorSubTable}, and unpacking histogram (See | |
16274 | @code{glHistogram}), and minmax (See @code{glMinmax}) data. | |
16275 | ||
16276 | @var{pname} is a symbolic constant indicating the parameter to be set, | |
16277 | and @var{param} is the new value. Six of the twelve storage parameters | |
16278 | affect how pixel data is returned to client memory. They are as follows: | |
16279 | ||
16280 | @table @asis | |
16281 | @item @code{GL_PACK_SWAP_BYTES} | |
16282 | If true, byte ordering for multibyte color components, depth components, | |
16283 | color indices, or stencil indices is reversed. That is, if a four-byte | |
3c9b6116 AW |
16284 | component consists of bytes @r{@var{b}_0}, @r{@var{b}_1}, @r{@var{b}_2}, |
16285 | @r{@var{b}_3}, it is stored in memory as @r{@var{b}_3}, @r{@var{b}_2}, | |
16286 | @r{@var{b}_1}, @r{@var{b}_0} if @code{GL_PACK_SWAP_BYTES} is true. | |
16287 | @code{GL_PACK_SWAP_BYTES} has no effect on the memory order of | |
16288 | components within a pixel, only on the order of bytes within components | |
16289 | or indices. For example, the three components of a @code{GL_RGB} format | |
16290 | pixel are always stored with red first, green second, and blue third, | |
16291 | regardless of the value of @code{GL_PACK_SWAP_BYTES}. | |
8925f36f AW |
16292 | |
16293 | @item @code{GL_PACK_LSB_FIRST} | |
16294 | If true, bits are ordered within a byte from least significant to most | |
16295 | significant; otherwise, the first bit in each byte is the most | |
16296 | significant one. This parameter is significant for bitmap data only. | |
16297 | ||
16298 | @item @code{GL_PACK_ROW_LENGTH} | |
16299 | If greater than 0, @code{GL_PACK_ROW_LENGTH} defines the number of | |
16300 | pixels in a row. If the first pixel of a row is placed at location | |
3c9b6116 AW |
16301 | @r{@var{p}} in memory, then the location of the first pixel of the next |
16302 | row is obtained by skipping | |
8925f36f | 16303 | |
3c9b6116 | 16304 | @r{@var{k}=@{(@var{n}@var{l}), |
8925f36f AW |
16305 | (@var{a}/@var{s},⌈@var{s}@var{n}@var{l},/@var{a},⌉)(@var{s}>=@var{a}), |
16306 | (@var{s}<@var{a}),} | |
16307 | ||
3c9b6116 AW |
16308 | components or indices, where @r{@var{n}} is the number of components or |
16309 | indices in a pixel, @r{@var{l}} is the number of pixels in a row | |
16310 | (@code{GL_PACK_ROW_LENGTH} if it is greater than 0, the @r{@var{width}} | |
16311 | argument to the pixel routine otherwise), @r{@var{a}} is the value of | |
16312 | @code{GL_PACK_ALIGNMENT}, and @r{@var{s}} is the size, in bytes, of a | |
16313 | single component (if @r{@var{a}<@var{s}}, then it is as if | |
16314 | @r{@var{a}=@var{s}}). In the case of 1-bit values, the location of the | |
16315 | next row is obtained by skipping | |
8925f36f | 16316 | |
3c9b6116 | 16317 | @r{@var{k}=8@var{a}⌈@var{n}@var{l},/8@var{a},,⌉} |
8925f36f AW |
16318 | |
16319 | components or indices. | |
16320 | ||
16321 | The word @var{component} in this description refers to the nonindex | |
16322 | values red, green, blue, alpha, and depth. Storage format @code{GL_RGB}, | |
16323 | for example, has three components per pixel: first red, then green, and | |
16324 | finally blue. | |
16325 | ||
16326 | @item @code{GL_PACK_IMAGE_HEIGHT} | |
16327 | If greater than 0, @code{GL_PACK_IMAGE_HEIGHT} defines the number of | |
16328 | pixels in an image three-dimensional texture volume, where ``image'' is | |
16329 | defined by all pixels sharing the same third dimension index. If the | |
3c9b6116 AW |
16330 | first pixel of a row is placed at location @r{@var{p}} in memory, then |
16331 | the location of the first pixel of the next row is obtained by skipping | |
8925f36f | 16332 | |
3c9b6116 | 16333 | @r{@var{k}=@{(@var{n}@var{l}@var{h}), |
8925f36f AW |
16334 | (@var{a}/@var{s},⌈@var{s}@var{n}@var{l}@var{h},/@var{a},⌉)(@var{s}>=@var{a}), |
16335 | (@var{s}<@var{a}),} | |
16336 | ||
3c9b6116 AW |
16337 | components or indices, where @r{@var{n}} is the number of components or |
16338 | indices in a pixel, @r{@var{l}} is the number of pixels in a row | |
16339 | (@code{GL_PACK_ROW_LENGTH} if it is greater than 0, the @r{@var{width}} | |
16340 | argument to @code{glTexImage3D} otherwise), @r{@var{h}} is the number of | |
16341 | rows in a pixel image (@code{GL_PACK_IMAGE_HEIGHT} if it is greater than | |
16342 | 0, the @r{@var{height}} argument to the @code{glTexImage3D} routine | |
16343 | otherwise), @r{@var{a}} is the value of @code{GL_PACK_ALIGNMENT}, and | |
16344 | @r{@var{s}} is the size, in bytes, of a single component (if | |
16345 | @r{@var{a}<@var{s}}, then it is as if @r{@var{a}=@var{s}}). | |
8925f36f AW |
16346 | |
16347 | The word @var{component} in this description refers to the nonindex | |
16348 | values red, green, blue, alpha, and depth. Storage format @code{GL_RGB}, | |
16349 | for example, has three components per pixel: first red, then green, and | |
16350 | finally blue. | |
16351 | ||
16352 | @item @code{GL_PACK_SKIP_PIXELS}, @code{GL_PACK_SKIP_ROWS}, and @code{GL_PACK_SKIP_IMAGES} | |
16353 | These values are provided as a convenience to the programmer; they | |
16354 | provide no functionality that cannot be duplicated simply by | |
16355 | incrementing the pointer passed to @code{glReadPixels}. Setting | |
3c9b6116 AW |
16356 | @code{GL_PACK_SKIP_PIXELS} to @r{@var{i}} is equivalent to incrementing |
16357 | the pointer by @r{@var{i}@var{n}} components or indices, where | |
16358 | @r{@var{n}} is the number of components or indices in each pixel. | |
16359 | Setting @code{GL_PACK_SKIP_ROWS} to @r{@var{j}} is equivalent to | |
16360 | incrementing the pointer by @r{@var{j}@var{m}} components or indices, | |
16361 | where @r{@var{m}} is the number of components or indices per row, as | |
16362 | just computed in the @code{GL_PACK_ROW_LENGTH} section. Setting | |
16363 | @code{GL_PACK_SKIP_IMAGES} to @r{@var{k}} is equivalent to incrementing | |
16364 | the pointer by @r{@var{k}@var{p}}, where @r{@var{p}} is the number of | |
16365 | components or indices per image, as computed in the | |
16366 | @code{GL_PACK_IMAGE_HEIGHT} section. | |
8925f36f AW |
16367 | |
16368 | @item @code{GL_PACK_ALIGNMENT} | |
16369 | Specifies the alignment requirements for the start of each pixel row in | |
16370 | memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to | |
16371 | even-numbered bytes), 4 (word-alignment), and 8 (rows start on | |
16372 | double-word boundaries). | |
16373 | ||
16374 | @end table | |
16375 | ||
16376 | The other six of the twelve storage parameters affect how pixel data is | |
16377 | read from client memory. These values are significant for | |
16378 | @code{glDrawPixels}, @code{glTexImage1D}, @code{glTexImage2D}, | |
16379 | @code{glTexImage3D}, @code{glTexSubImage1D}, @code{glTexSubImage2D}, | |
16380 | @code{glTexSubImage3D}, @code{glBitmap}, and @code{glPolygonStipple}. | |
16381 | ||
16382 | Additionally, if the @code{ARB_imaging} extension is supported, | |
16383 | @code{glColorTable}, @code{glColorSubTable}, | |
16384 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and | |
16385 | @code{glSeparableFilter2D}. They are as follows: | |
16386 | ||
16387 | @table @asis | |
16388 | @item @code{GL_UNPACK_SWAP_BYTES} | |
16389 | If true, byte ordering for multibyte color components, depth components, | |
16390 | color indices, or stencil indices is reversed. That is, if a four-byte | |
3c9b6116 AW |
16391 | component consists of bytes @r{@var{b}_0}, @r{@var{b}_1}, @r{@var{b}_2}, |
16392 | @r{@var{b}_3}, it is taken from memory as @r{@var{b}_3}, @r{@var{b}_2}, | |
16393 | @r{@var{b}_1}, @r{@var{b}_0} if @code{GL_UNPACK_SWAP_BYTES} is true. | |
16394 | @code{GL_UNPACK_SWAP_BYTES} has no effect on the memory order of | |
16395 | components within a pixel, only on the order of bytes within components | |
16396 | or indices. For example, the three components of a @code{GL_RGB} format | |
16397 | pixel are always stored with red first, green second, and blue third, | |
16398 | regardless of the value of @code{GL_UNPACK_SWAP_BYTES}. | |
8925f36f AW |
16399 | |
16400 | @item @code{GL_UNPACK_LSB_FIRST} | |
16401 | If true, bits are ordered within a byte from least significant to most | |
16402 | significant; otherwise, the first bit in each byte is the most | |
16403 | significant one. This is relevant only for bitmap data. | |
16404 | ||
16405 | @item @code{GL_UNPACK_ROW_LENGTH} | |
16406 | If greater than 0, @code{GL_UNPACK_ROW_LENGTH} defines the number of | |
16407 | pixels in a row. If the first pixel of a row is placed at location | |
3c9b6116 AW |
16408 | @r{@var{p}} in memory, then the location of the first pixel of the next |
16409 | row is obtained by skipping | |
8925f36f | 16410 | |
3c9b6116 | 16411 | @r{@var{k}=@{(@var{n}@var{l}), |
8925f36f AW |
16412 | (@var{a}/@var{s},⌈@var{s}@var{n}@var{l},/@var{a},⌉)(@var{s}>=@var{a}), |
16413 | (@var{s}<@var{a}),} | |
16414 | ||
3c9b6116 AW |
16415 | components or indices, where @r{@var{n}} is the number of components or |
16416 | indices in a pixel, @r{@var{l}} is the number of pixels in a row | |
8925f36f | 16417 | (@code{GL_UNPACK_ROW_LENGTH} if it is greater than 0, the |
3c9b6116 AW |
16418 | @r{@var{width}} argument to the pixel routine otherwise), @r{@var{a}} is |
16419 | the value of @code{GL_UNPACK_ALIGNMENT}, and @r{@var{s}} is the size, in | |
16420 | bytes, of a single component (if @r{@var{a}<@var{s}}, then it is as if | |
16421 | @r{@var{a}=@var{s}}). In the case of 1-bit values, the location of the | |
16422 | next row is obtained by skipping | |
8925f36f | 16423 | |
3c9b6116 | 16424 | @r{@var{k}=8@var{a}⌈@var{n}@var{l},/8@var{a},,⌉} |
8925f36f AW |
16425 | |
16426 | components or indices. | |
16427 | ||
16428 | The word @var{component} in this description refers to the nonindex | |
16429 | values red, green, blue, alpha, and depth. Storage format @code{GL_RGB}, | |
16430 | for example, has three components per pixel: first red, then green, and | |
16431 | finally blue. | |
16432 | ||
16433 | @item @code{GL_UNPACK_IMAGE_HEIGHT} | |
16434 | If greater than 0, @code{GL_UNPACK_IMAGE_HEIGHT} defines the number of | |
16435 | pixels in an image of a three-dimensional texture volume. Where | |
16436 | ``image'' is defined by all pixel sharing the same third dimension | |
3c9b6116 AW |
16437 | index. If the first pixel of a row is placed at location @r{@var{p}} in |
16438 | memory, then the location of the first pixel of the next row is obtained | |
16439 | by skipping | |
8925f36f | 16440 | |
3c9b6116 | 16441 | @r{@var{k}=@{(@var{n}@var{l}@var{h}), |
8925f36f AW |
16442 | (@var{a}/@var{s},⌈@var{s}@var{n}@var{l}@var{h},/@var{a},⌉)(@var{s}>=@var{a}), |
16443 | (@var{s}<@var{a}),} | |
16444 | ||
3c9b6116 AW |
16445 | components or indices, where @r{@var{n}} is the number of components or |
16446 | indices in a pixel, @r{@var{l}} is the number of pixels in a row | |
8925f36f | 16447 | (@code{GL_UNPACK_ROW_LENGTH} if it is greater than 0, the |
3c9b6116 AW |
16448 | @r{@var{width}} argument to @code{glTexImage3D} otherwise), @r{@var{h}} |
16449 | is the number of rows in an image (@code{GL_UNPACK_IMAGE_HEIGHT} if it | |
16450 | is greater than 0, the @r{@var{height}} argument to @code{glTexImage3D} | |
16451 | otherwise), @r{@var{a}} is the value of @code{GL_UNPACK_ALIGNMENT}, and | |
16452 | @r{@var{s}} is the size, in bytes, of a single component (if | |
16453 | @r{@var{a}<@var{s}}, then it is as if @r{@var{a}=@var{s}}). | |
8925f36f AW |
16454 | |
16455 | The word @var{component} in this description refers to the nonindex | |
16456 | values red, green, blue, alpha, and depth. Storage format @code{GL_RGB}, | |
16457 | for example, has three components per pixel: first red, then green, and | |
16458 | finally blue. | |
16459 | ||
16460 | @item @code{GL_UNPACK_SKIP_PIXELS} and @code{GL_UNPACK_SKIP_ROWS} | |
16461 | These values are provided as a convenience to the programmer; they | |
16462 | provide no functionality that cannot be duplicated by incrementing the | |
16463 | pointer passed to @code{glDrawPixels}, @code{glTexImage1D}, | |
16464 | @code{glTexImage2D}, @code{glTexSubImage1D}, @code{glTexSubImage2D}, | |
16465 | @code{glBitmap}, or @code{glPolygonStipple}. Setting | |
3c9b6116 AW |
16466 | @code{GL_UNPACK_SKIP_PIXELS} to @r{@var{i}} is equivalent to |
16467 | incrementing the pointer by @r{@var{i}@var{n}} components or indices, | |
16468 | where @r{@var{n}} is the number of components or indices in each pixel. | |
16469 | Setting @code{GL_UNPACK_SKIP_ROWS} to @r{@var{j}} is equivalent to | |
16470 | incrementing the pointer by @r{@var{j}@var{k}} components or indices, | |
16471 | where @r{@var{k}} is the number of components or indices per row, as | |
16472 | just computed in the @code{GL_UNPACK_ROW_LENGTH} section. | |
8925f36f AW |
16473 | |
16474 | @item @code{GL_UNPACK_ALIGNMENT} | |
16475 | Specifies the alignment requirements for the start of each pixel row in | |
16476 | memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to | |
16477 | even-numbered bytes), 4 (word-alignment), and 8 (rows start on | |
16478 | double-word boundaries). | |
16479 | ||
16480 | @end table | |
16481 | ||
16482 | The following table gives the type, initial value, and range of valid | |
16483 | values for each storage parameter that can be set with | |
16484 | @code{glPixelStore}. | |
16485 | ||
16486 | ||
16487 | ||
16488 | @table @asis | |
16489 | @item @strong{@var{pname}} | |
16490 | @strong{Type}, @strong{Initial Value}, @strong{Valid Range} | |
16491 | ||
16492 | @item @code{GL_PACK_SWAP_BYTES} | |
16493 | boolean , false , true or false | |
16494 | ||
16495 | @item @code{GL_PACK_LSB_FIRST} | |
16496 | boolean , false , true or false | |
16497 | ||
16498 | @item @code{GL_PACK_ROW_LENGTH} | |
3c9b6116 | 16499 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16500 | |
16501 | @item @code{GL_PACK_IMAGE_HEIGHT} | |
3c9b6116 | 16502 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16503 | |
16504 | @item @code{GL_PACK_SKIP_ROWS} | |
3c9b6116 | 16505 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16506 | |
16507 | @item @code{GL_PACK_SKIP_PIXELS} | |
3c9b6116 | 16508 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16509 | |
16510 | @item @code{GL_PACK_SKIP_IMAGES} | |
3c9b6116 | 16511 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16512 | |
16513 | @item @code{GL_PACK_ALIGNMENT} | |
16514 | integer , 4 , 1, 2, 4, or 8 | |
16515 | ||
16516 | @item @code{GL_UNPACK_SWAP_BYTES} | |
16517 | boolean , false , true or false | |
16518 | ||
16519 | @item @code{GL_UNPACK_LSB_FIRST} | |
16520 | boolean , false , true or false | |
16521 | ||
16522 | @item @code{GL_UNPACK_ROW_LENGTH} | |
3c9b6116 | 16523 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16524 | |
16525 | @item @code{GL_UNPACK_IMAGE_HEIGHT} | |
3c9b6116 | 16526 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16527 | |
16528 | @item @code{GL_UNPACK_SKIP_ROWS} | |
3c9b6116 | 16529 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16530 | |
16531 | @item @code{GL_UNPACK_SKIP_PIXELS} | |
3c9b6116 | 16532 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16533 | |
16534 | @item @code{GL_UNPACK_SKIP_IMAGES} | |
3c9b6116 | 16535 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16536 | |
16537 | @item @code{GL_UNPACK_ALIGNMENT} | |
16538 | integer , 4 , 1, 2, 4, or 8 | |
16539 | ||
16540 | @end table | |
16541 | ||
16542 | @code{glPixelStoref} can be used to set any pixel store parameter. If | |
16543 | the parameter type is boolean, then if @var{param} is 0, the parameter | |
16544 | is false; otherwise it is set to true. If @var{pname} is a integer type | |
16545 | parameter, @var{param} is rounded to the nearest integer. | |
16546 | ||
16547 | Likewise, @code{glPixelStorei} can also be used to set any of the pixel | |
16548 | store parameters. Boolean parameters are set to false if @var{param} is | |
16549 | 0 and true otherwise. | |
16550 | ||
8925f36f AW |
16551 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted |
16552 | value. | |
16553 | ||
16554 | @code{GL_INVALID_VALUE} is generated if a negative row length, pixel | |
16555 | skip, or row skip value is specified, or if alignment is specified as | |
16556 | other than 1, 2, 4, or 8. | |
16557 | ||
16558 | @code{GL_INVALID_OPERATION} is generated if @code{glPixelStore} is | |
16559 | executed between the execution of @code{glBegin} and the corresponding | |
16560 | execution of @code{glEnd}. | |
16561 | ||
bb894c9d | 16562 | @end deftypefun |
8925f36f | 16563 | |
bb894c9d AW |
16564 | @deftypefun void glPixelTransferf pname param |
16565 | @deftypefunx void glPixelTransferi pname param | |
3c9b6116 AW |
16566 | Set pixel transfer modes. |
16567 | ||
8925f36f AW |
16568 | @table @asis |
16569 | @item @var{pname} | |
16570 | Specifies the symbolic name of the pixel transfer parameter to be set. | |
16571 | Must be one of the following: @code{GL_MAP_COLOR}, | |
16572 | @code{GL_MAP_STENCIL}, @code{GL_INDEX_SHIFT}, @code{GL_INDEX_OFFSET}, | |
16573 | @code{GL_RED_SCALE}, @code{GL_RED_BIAS}, @code{GL_GREEN_SCALE}, | |
16574 | @code{GL_GREEN_BIAS}, @code{GL_BLUE_SCALE}, @code{GL_BLUE_BIAS}, | |
16575 | @code{GL_ALPHA_SCALE}, @code{GL_ALPHA_BIAS}, @code{GL_DEPTH_SCALE}, or | |
16576 | @code{GL_DEPTH_BIAS}. | |
16577 | ||
16578 | Additionally, if the @code{ARB_imaging} extension is supported, the | |
16579 | following symbolic names are accepted: | |
16580 | @code{GL_POST_COLOR_MATRIX_RED_SCALE}, | |
16581 | @code{GL_POST_COLOR_MATRIX_GREEN_SCALE}, | |
16582 | @code{GL_POST_COLOR_MATRIX_BLUE_SCALE}, | |
16583 | @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE}, | |
16584 | @code{GL_POST_COLOR_MATRIX_RED_BIAS}, | |
16585 | @code{GL_POST_COLOR_MATRIX_GREEN_BIAS}, | |
16586 | @code{GL_POST_COLOR_MATRIX_BLUE_BIAS}, | |
16587 | @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS}, | |
16588 | @code{GL_POST_CONVOLUTION_RED_SCALE}, | |
16589 | @code{GL_POST_CONVOLUTION_GREEN_SCALE}, | |
16590 | @code{GL_POST_CONVOLUTION_BLUE_SCALE}, | |
16591 | @code{GL_POST_CONVOLUTION_ALPHA_SCALE}, | |
16592 | @code{GL_POST_CONVOLUTION_RED_BIAS}, | |
16593 | @code{GL_POST_CONVOLUTION_GREEN_BIAS}, | |
16594 | @code{GL_POST_CONVOLUTION_BLUE_BIAS}, and | |
16595 | @code{GL_POST_CONVOLUTION_ALPHA_BIAS}. | |
16596 | ||
16597 | @item @var{param} | |
16598 | Specifies the value that @var{pname} is set to. | |
16599 | ||
16600 | @end table | |
16601 | ||
8925f36f AW |
16602 | @code{glPixelTransfer} sets pixel transfer modes that affect the |
16603 | operation of subsequent @code{glCopyPixels}, @code{glCopyTexImage1D}, | |
16604 | @code{glCopyTexImage2D}, @code{glCopyTexSubImage1D}, | |
16605 | @code{glCopyTexSubImage2D}, @code{glCopyTexSubImage3D}, | |
16606 | @code{glDrawPixels}, @code{glReadPixels}, @code{glTexImage1D}, | |
16607 | @code{glTexImage2D}, @code{glTexImage3D}, @code{glTexSubImage1D}, | |
16608 | @code{glTexSubImage2D}, and @code{glTexSubImage3D} commands. | |
16609 | Additionally, if the @code{ARB_imaging} subset is supported, the | |
16610 | routines @code{glColorTable}, @code{glColorSubTable}, | |
16611 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, | |
16612 | @code{glHistogram}, @code{glMinmax}, and @code{glSeparableFilter2D} are | |
16613 | also affected. The algorithms that are specified by pixel transfer modes | |
16614 | operate on pixels after they are read from the frame buffer | |
16615 | (@code{glCopyPixels}@code{glCopyTexImage1D}, @code{glCopyTexImage2D}, | |
16616 | @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D}, | |
16617 | @code{glCopyTexSubImage3D}, and @code{glReadPixels}), or unpacked from | |
16618 | client memory (@code{glDrawPixels}, @code{glTexImage1D}, | |
16619 | @code{glTexImage2D}, @code{glTexImage3D}, @code{glTexSubImage1D}, | |
16620 | @code{glTexSubImage2D}, and @code{glTexSubImage3D}). Pixel transfer | |
16621 | operations happen in the same order, and in the same manner, regardless | |
16622 | of the command that resulted in the pixel operation. Pixel storage modes | |
16623 | (see @code{glPixelStore}) control the unpacking of pixels being read | |
16624 | from client memory and the packing of pixels being written back into | |
16625 | client memory. | |
16626 | ||
16627 | Pixel transfer operations handle four fundamental pixel types: | |
16628 | @var{color}, @var{color index}, @var{depth}, and @var{stencil}. | |
16629 | @var{Color} pixels consist of four floating-point values with | |
16630 | unspecified mantissa and exponent sizes, scaled such that 0 represents | |
16631 | zero intensity and 1 represents full intensity. @var{Color indices} | |
16632 | comprise a single fixed-point value, with unspecified precision to the | |
16633 | right of the binary point. @var{Depth} pixels comprise a single | |
16634 | floating-point value, with unspecified mantissa and exponent sizes, | |
16635 | scaled such that 0.0 represents the minimum depth buffer value, and 1.0 | |
16636 | represents the maximum depth buffer value. Finally, @var{stencil} pixels | |
16637 | comprise a single fixed-point value, with unspecified precision to the | |
16638 | right of the binary point. | |
16639 | ||
16640 | The pixel transfer operations performed on the four basic pixel types | |
16641 | are as follows: | |
16642 | ||
16643 | @table @asis | |
16644 | @item @var{Color} | |
16645 | Each of the four color components is multiplied by a scale factor, then | |
16646 | added to a bias factor. That is, the red component is multiplied by | |
16647 | @code{GL_RED_SCALE}, then added to @code{GL_RED_BIAS}; the green | |
16648 | component is multiplied by @code{GL_GREEN_SCALE}, then added to | |
16649 | @code{GL_GREEN_BIAS}; the blue component is multiplied by | |
16650 | @code{GL_BLUE_SCALE}, then added to @code{GL_BLUE_BIAS}; and the alpha | |
16651 | component is multiplied by @code{GL_ALPHA_SCALE}, then added to | |
16652 | @code{GL_ALPHA_BIAS}. After all four color components are scaled and | |
3c9b6116 | 16653 | biased, each is clamped to the range @r{[0,1]}. All color, scale, and |
8925f36f AW |
16654 | bias values are specified with @code{glPixelTransfer}. |
16655 | ||
16656 | If @code{GL_MAP_COLOR} is true, each color component is scaled by the | |
16657 | size of the corresponding color-to-color map, then replaced by the | |
16658 | contents of that map indexed by the scaled component. That is, the red | |
16659 | component is scaled by @code{GL_PIXEL_MAP_R_TO_R_SIZE}, then replaced by | |
16660 | the contents of @code{GL_PIXEL_MAP_R_TO_R} indexed by itself. The green | |
16661 | component is scaled by @code{GL_PIXEL_MAP_G_TO_G_SIZE}, then replaced by | |
16662 | the contents of @code{GL_PIXEL_MAP_G_TO_G} indexed by itself. The blue | |
16663 | component is scaled by @code{GL_PIXEL_MAP_B_TO_B_SIZE}, then replaced by | |
16664 | the contents of @code{GL_PIXEL_MAP_B_TO_B} indexed by itself. And the | |
16665 | alpha component is scaled by @code{GL_PIXEL_MAP_A_TO_A_SIZE}, then | |
16666 | replaced by the contents of @code{GL_PIXEL_MAP_A_TO_A} indexed by | |
16667 | itself. All components taken from the maps are then clamped to the range | |
3c9b6116 AW |
16668 | @r{[0,1]}. @code{GL_MAP_COLOR} is specified with @code{glPixelTransfer}. |
16669 | The contents of the various maps are specified with @code{glPixelMap}. | |
8925f36f AW |
16670 | |
16671 | If the @code{ARB_imaging} extension is supported, each of the four color | |
16672 | components may be scaled and biased after transformation by the color | |
16673 | matrix. That is, the red component is multiplied by | |
16674 | @code{GL_POST_COLOR_MATRIX_RED_SCALE}, then added to | |
16675 | @code{GL_POST_COLOR_MATRIX_RED_BIAS}; the green component is multiplied | |
16676 | by @code{GL_POST_COLOR_MATRIX_GREEN_SCALE}, then added to | |
16677 | @code{GL_POST_COLOR_MATRIX_GREEN_BIAS}; the blue component is multiplied | |
16678 | by @code{GL_POST_COLOR_MATRIX_BLUE_SCALE}, then added to | |
16679 | @code{GL_POST_COLOR_MATRIX_BLUE_BIAS}; and the alpha component is | |
16680 | multiplied by @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE}, then added to | |
16681 | @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS}. After all four color components | |
3c9b6116 | 16682 | are scaled and biased, each is clamped to the range @r{[0,1]}. |
8925f36f AW |
16683 | |
16684 | Similarly, if the @code{ARB_imaging} extension is supported, each of the | |
16685 | four color components may be scaled and biased after processing by the | |
16686 | enabled convolution filter. That is, the red component is multiplied by | |
16687 | @code{GL_POST_CONVOLUTION_RED_SCALE}, then added to | |
16688 | @code{GL_POST_CONVOLUTION_RED_BIAS}; the green component is multiplied | |
16689 | by @code{GL_POST_CONVOLUTION_GREEN_SCALE}, then added to | |
16690 | @code{GL_POST_CONVOLUTION_GREEN_BIAS}; the blue component is multiplied | |
16691 | by @code{GL_POST_CONVOLUTION_BLUE_SCALE}, then added to | |
16692 | @code{GL_POST_CONVOLUTION_BLUE_BIAS}; and the alpha component is | |
16693 | multiplied by @code{GL_POST_CONVOLUTION_ALPHA_SCALE}, then added to | |
16694 | @code{GL_POST_CONVOLUTION_ALPHA_BIAS}. After all four color components | |
3c9b6116 | 16695 | are scaled and biased, each is clamped to the range @r{[0,1]}. |
8925f36f AW |
16696 | |
16697 | @item @var{Color index} | |
16698 | Each color index is shifted left by @code{GL_INDEX_SHIFT} bits; any bits | |
16699 | beyond the number of fraction bits carried by the fixed-point index are | |
16700 | filled with zeros. If @code{GL_INDEX_SHIFT} is negative, the shift is to | |
16701 | the right, again zero filled. Then @code{GL_INDEX_OFFSET} is added to | |
16702 | the index. @code{GL_INDEX_SHIFT} and @code{GL_INDEX_OFFSET} are | |
16703 | specified with @code{glPixelTransfer}. | |
16704 | ||
16705 | From this point, operation diverges depending on the required format of | |
16706 | the resulting pixels. If the resulting pixels are to be written to a | |
16707 | color index buffer, or if they are being read back to client memory in | |
16708 | @code{GL_COLOR_INDEX} format, the pixels continue to be treated as | |
16709 | indices. If @code{GL_MAP_COLOR} is true, each index is masked by | |
3c9b6116 AW |
16710 | @r{2^@var{n}-1}, where @r{@var{n}} is @code{GL_PIXEL_MAP_I_TO_I_SIZE}, |
16711 | then replaced by the contents of @code{GL_PIXEL_MAP_I_TO_I} indexed by | |
16712 | the masked value. @code{GL_MAP_COLOR} is specified with | |
16713 | @code{glPixelTransfer}. The contents of the index map is specified with | |
16714 | @code{glPixelMap}. | |
8925f36f AW |
16715 | |
16716 | If the resulting pixels are to be written to an RGBA color buffer, or if | |
16717 | they are read back to client memory in a format other than | |
16718 | @code{GL_COLOR_INDEX}, the pixels are converted from indices to colors | |
16719 | by referencing the four maps @code{GL_PIXEL_MAP_I_TO_R}, | |
16720 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
16721 | @code{GL_PIXEL_MAP_I_TO_A}. Before being dereferenced, the index is | |
3c9b6116 | 16722 | masked by @r{2^@var{n}-1}, where @r{@var{n}} is |
8925f36f AW |
16723 | @code{GL_PIXEL_MAP_I_TO_R_SIZE} for the red map, |
16724 | @code{GL_PIXEL_MAP_I_TO_G_SIZE} for the green map, | |
16725 | @code{GL_PIXEL_MAP_I_TO_B_SIZE} for the blue map, and | |
16726 | @code{GL_PIXEL_MAP_I_TO_A_SIZE} for the alpha map. All components taken | |
3c9b6116 AW |
16727 | from the maps are then clamped to the range @r{[0,1]}. The contents of |
16728 | the four maps is specified with @code{glPixelMap}. | |
8925f36f AW |
16729 | |
16730 | @item @var{Depth} | |
16731 | Each depth value is multiplied by @code{GL_DEPTH_SCALE}, added to | |
3c9b6116 | 16732 | @code{GL_DEPTH_BIAS}, then clamped to the range @r{[0,1]}. |
8925f36f AW |
16733 | |
16734 | @item @var{Stencil} | |
16735 | Each index is shifted @code{GL_INDEX_SHIFT} bits just as a color index | |
16736 | is, then added to @code{GL_INDEX_OFFSET}. If @code{GL_MAP_STENCIL} is | |
3c9b6116 AW |
16737 | true, each index is masked by @r{2^@var{n}-1}, where @r{@var{n}} is |
16738 | @code{GL_PIXEL_MAP_S_TO_S_SIZE}, then replaced by the contents of | |
8925f36f AW |
16739 | @code{GL_PIXEL_MAP_S_TO_S} indexed by the masked value. |
16740 | ||
16741 | @end table | |
16742 | ||
16743 | The following table gives the type, initial value, and range of valid | |
16744 | values for each of the pixel transfer parameters that are set with | |
16745 | @code{glPixelTransfer}. | |
16746 | ||
16747 | ||
16748 | ||
16749 | @table @asis | |
16750 | @item @strong{@var{pname}} | |
16751 | @strong{Type}, @strong{Initial Value}, @strong{Valid Range} | |
16752 | ||
16753 | @item @code{GL_MAP_COLOR} | |
16754 | boolean , false , true/false | |
16755 | ||
16756 | @item @code{GL_MAP_STENCIL} | |
16757 | boolean , false , true/false | |
16758 | ||
16759 | @item @code{GL_INDEX_SHIFT} | |
3c9b6116 | 16760 | integer , 0 , @r{(-∞,∞)} |
8925f36f AW |
16761 | |
16762 | @item @code{GL_INDEX_OFFSET} | |
3c9b6116 | 16763 | integer , 0 , @r{(-∞,∞)} |
8925f36f AW |
16764 | |
16765 | @item @code{GL_RED_SCALE} | |
3c9b6116 | 16766 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16767 | |
16768 | @item @code{GL_GREEN_SCALE} | |
3c9b6116 | 16769 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16770 | |
16771 | @item @code{GL_BLUE_SCALE} | |
3c9b6116 | 16772 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16773 | |
16774 | @item @code{GL_ALPHA_SCALE} | |
3c9b6116 | 16775 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16776 | |
16777 | @item @code{GL_DEPTH_SCALE} | |
3c9b6116 | 16778 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16779 | |
16780 | @item @code{GL_RED_BIAS} | |
3c9b6116 | 16781 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16782 | |
16783 | @item @code{GL_GREEN_BIAS} | |
3c9b6116 | 16784 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16785 | |
16786 | @item @code{GL_BLUE_BIAS} | |
3c9b6116 | 16787 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16788 | |
16789 | @item @code{GL_ALPHA_BIAS} | |
3c9b6116 | 16790 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16791 | |
16792 | @item @code{GL_DEPTH_BIAS} | |
3c9b6116 | 16793 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16794 | |
16795 | @item @code{GL_POST_COLOR_MATRIX_RED_SCALE} | |
3c9b6116 | 16796 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16797 | |
16798 | @item @code{GL_POST_COLOR_MATRIX_GREEN_SCALE} | |
3c9b6116 | 16799 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16800 | |
16801 | @item @code{GL_POST_COLOR_MATRIX_BLUE_SCALE} | |
3c9b6116 | 16802 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16803 | |
16804 | @item @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE} | |
3c9b6116 | 16805 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16806 | |
16807 | @item @code{GL_POST_COLOR_MATRIX_RED_BIAS} | |
3c9b6116 | 16808 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16809 | |
16810 | @item @code{GL_POST_COLOR_MATRIX_GREEN_BIAS} | |
3c9b6116 | 16811 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16812 | |
16813 | @item @code{GL_POST_COLOR_MATRIX_BLUE_BIAS} | |
3c9b6116 | 16814 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16815 | |
16816 | @item @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS} | |
3c9b6116 | 16817 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16818 | |
16819 | @item @code{GL_POST_CONVOLUTION_RED_SCALE} | |
3c9b6116 | 16820 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16821 | |
16822 | @item @code{GL_POST_CONVOLUTION_GREEN_SCALE} | |
3c9b6116 | 16823 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16824 | |
16825 | @item @code{GL_POST_CONVOLUTION_BLUE_SCALE} | |
3c9b6116 | 16826 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16827 | |
16828 | @item @code{GL_POST_CONVOLUTION_ALPHA_SCALE} | |
3c9b6116 | 16829 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16830 | |
16831 | @item @code{GL_POST_CONVOLUTION_RED_BIAS} | |
3c9b6116 | 16832 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16833 | |
16834 | @item @code{GL_POST_CONVOLUTION_GREEN_BIAS} | |
3c9b6116 | 16835 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16836 | |
16837 | @item @code{GL_POST_CONVOLUTION_BLUE_BIAS} | |
3c9b6116 | 16838 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16839 | |
16840 | @item @code{GL_POST_CONVOLUTION_ALPHA_BIAS} | |
3c9b6116 | 16841 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16842 | |
16843 | @end table | |
16844 | ||
16845 | @code{glPixelTransferf} can be used to set any pixel transfer parameter. | |
16846 | If the parameter type is boolean, 0 implies false and any other value | |
16847 | implies true. If @var{pname} is an integer parameter, @var{param} is | |
16848 | rounded to the nearest integer. | |
16849 | ||
16850 | Likewise, @code{glPixelTransferi} can be used to set any of the pixel | |
16851 | transfer parameters. Boolean parameters are set to false if @var{param} | |
16852 | is 0 and to true otherwise. @var{param} is converted to floating point | |
16853 | before being assigned to real-valued parameters. | |
16854 | ||
8925f36f AW |
16855 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted |
16856 | value. | |
16857 | ||
16858 | @code{GL_INVALID_OPERATION} is generated if @code{glPixelTransfer} is | |
16859 | executed between the execution of @code{glBegin} and the corresponding | |
16860 | execution of @code{glEnd}. | |
16861 | ||
bb894c9d | 16862 | @end deftypefun |
8925f36f | 16863 | |
bb894c9d | 16864 | @deftypefun void glPixelZoom xfactor yfactor |
3c9b6116 AW |
16865 | Specify the pixel zoom factors. |
16866 | ||
8925f36f AW |
16867 | @table @asis |
16868 | @item @var{xfactor} | |
16869 | @itemx @var{yfactor} | |
3c9b6116 AW |
16870 | Specify the @r{@var{x}} and @r{@var{y}} zoom factors for pixel write |
16871 | operations. | |
8925f36f AW |
16872 | |
16873 | @end table | |
16874 | ||
3c9b6116 AW |
16875 | @code{glPixelZoom} specifies values for the @r{@var{x}} and @r{@var{y}} |
16876 | zoom factors. During the execution of @code{glDrawPixels} or | |
16877 | @code{glCopyPixels}, if (@r{@var{xr}}, @r{@var{yr}}) is the current | |
16878 | raster position, and a given element is in the @r{@var{m}}th row and | |
16879 | @r{@var{n}}th column of the pixel rectangle, then pixels whose centers | |
16880 | are in the rectangle with corners at | |
8925f36f | 16881 | |
3c9b6116 | 16882 | (@r{@var{xr}+@var{n}·@var{xfactor}}, @r{@var{yr}+@var{m}·@var{yfactor}}) |
8925f36f | 16883 | |
3c9b6116 AW |
16884 | (@r{@var{xr}+(@var{n}+1,)·@var{xfactor}}, |
16885 | @r{@var{yr}+(@var{m}+1,)·@var{yfactor}}) | |
8925f36f AW |
16886 | |
16887 | are candidates for replacement. Any pixel whose center lies on the | |
16888 | bottom or left edge of this rectangular region is also modified. | |
16889 | ||
16890 | Pixel zoom factors are not limited to positive values. Negative zoom | |
16891 | factors reflect the resulting image about the current raster position. | |
16892 | ||
8925f36f AW |
16893 | @code{GL_INVALID_OPERATION} is generated if @code{glPixelZoom} is |
16894 | executed between the execution of @code{glBegin} and the corresponding | |
16895 | execution of @code{glEnd}. | |
16896 | ||
bb894c9d | 16897 | @end deftypefun |
8925f36f | 16898 | |
bb894c9d AW |
16899 | @deftypefun void glPointParameterf pname param |
16900 | @deftypefunx void glPointParameteri pname param | |
3c9b6116 AW |
16901 | Specify point parameters. |
16902 | ||
8925f36f AW |
16903 | @table @asis |
16904 | @item @var{pname} | |
16905 | Specifies a single-valued point parameter. @code{GL_POINT_SIZE_MIN}, | |
16906 | @code{GL_POINT_SIZE_MAX}, @code{GL_POINT_FADE_THRESHOLD_SIZE}, and | |
16907 | @code{GL_POINT_SPRITE_COORD_ORIGIN} are accepted. | |
16908 | ||
16909 | @item @var{param} | |
16910 | Specifies the value that @var{pname} will be set to. | |
16911 | ||
16912 | @end table | |
16913 | ||
8925f36f AW |
16914 | The following values are accepted for @var{pname}: |
16915 | ||
16916 | @table @asis | |
16917 | @item @code{GL_POINT_SIZE_MIN} | |
16918 | ||
16919 | ||
16920 | @var{params} is a single floating-point value that specifies the minimum | |
16921 | point size. The default value is 0.0. | |
16922 | ||
16923 | @item @code{GL_POINT_SIZE_MAX} | |
16924 | ||
16925 | ||
16926 | @var{params} is a single floating-point value that specifies the maximum | |
16927 | point size. The default value is 1.0. | |
16928 | ||
16929 | @item @code{GL_POINT_FADE_THRESHOLD_SIZE} | |
16930 | ||
16931 | ||
16932 | @var{params} is a single floating-point value that specifies the | |
16933 | threshold value to which point sizes are clamped if they exceed the | |
16934 | specified value. The default value is 1.0. | |
16935 | ||
16936 | @item @code{GL_POINT_DISTANCE_ATTENUATION} | |
16937 | ||
16938 | ||
16939 | @var{params} is an array of three floating-point values that specify the | |
16940 | coefficients used for scaling the computed point size. The default | |
3c9b6116 | 16941 | values are @r{(1,00)}. |
8925f36f AW |
16942 | |
16943 | @item @code{GL_POINT_SPRITE_COORD_ORIGIN} | |
16944 | ||
16945 | ||
16946 | @var{params} is a single enum specifying the point sprite texture | |
16947 | coordinate origin, either @code{GL_LOWER_LEFT} or @code{GL_UPPER_LEFT}. | |
16948 | The default value is @code{GL_UPPER_LEFT}. | |
16949 | ||
16950 | @end table | |
16951 | ||
8925f36f AW |
16952 | @code{GL_INVALID_VALUE} is generated If the value specified for |
16953 | @code{GL_POINT_SIZE_MIN}, @code{GL_POINT_SIZE_MAX}, or | |
16954 | @code{GL_POINT_FADE_THRESHOLD_SIZE} is less than zero. | |
16955 | ||
16956 | @code{GL_INVALID_ENUM} is generated If the value specified for | |
16957 | @code{GL_POINT_SPRITE_COORD_ORIGIN} is not @code{GL_LOWER_LEFT} or | |
16958 | @code{GL_UPPER_LEFT}. | |
16959 | ||
16960 | If the value for @code{GL_POINT_SIZE_MIN} is greater than | |
16961 | @code{GL_POINT_SIZE_MAX}, the point size after clamping is undefined, | |
16962 | but no error is generated. | |
16963 | ||
16964 | ||
16965 | ||
bb894c9d | 16966 | @end deftypefun |
8925f36f | 16967 | |
bb894c9d | 16968 | @deftypefun void glPointSize size |
3c9b6116 AW |
16969 | Specify the diameter of rasterized points. |
16970 | ||
8925f36f AW |
16971 | @table @asis |
16972 | @item @var{size} | |
16973 | Specifies the diameter of rasterized points. The initial value is 1. | |
16974 | ||
16975 | @end table | |
16976 | ||
8925f36f AW |
16977 | @code{glPointSize} specifies the rasterized diameter of both aliased and |
16978 | antialiased points. Using a point size other than 1 has different | |
16979 | effects, depending on whether point antialiasing is enabled. To enable | |
16980 | and disable point antialiasing, call @code{glEnable} and | |
16981 | @code{glDisable} with argument @code{GL_POINT_SMOOTH}. Point | |
16982 | antialiasing is initially disabled. | |
16983 | ||
16984 | The specified point size is multiplied with a distance attenuation | |
16985 | factor and clamped to the specified point size range, and further | |
16986 | clamped to the implementation-dependent point size range to produce the | |
16987 | derived point size using | |
16988 | ||
3c9b6116 | 16989 | @r{@var{pointSize}=@var{clamp}(@var{size}×√(1/@var{a}+@var{b}×@var{d}+@var{c}×@var{d}^2,,,),,)} |
8925f36f | 16990 | |
3c9b6116 AW |
16991 | where @r{@var{d}} is the eye-coordinate distance from the eye to the |
16992 | vertex, and @r{@var{a}}, @r{@var{b}}, and @r{@var{c}} are the distance | |
16993 | attenuation coefficients (see @code{glPointParameter}). | |
8925f36f AW |
16994 | |
16995 | If multisampling is disabled, the computed point size is used as the | |
16996 | point's width. | |
16997 | ||
16998 | If multisampling is enabled, the point may be faded by modifying the | |
16999 | point alpha value (see @code{glSampleCoverage}) instead of allowing the | |
17000 | point width to go below a given threshold (see @code{glPointParameter}). | |
17001 | In this case, the width is further modified in the following manner: | |
17002 | ||
3c9b6116 | 17003 | @r{@var{pointWidth}=@{(@var{pointSize}), |
8925f36f AW |
17004 | (@var{threshold})(@var{pointSize}>=@var{threshold}), |
17005 | (@var{otherwise}),} | |
17006 | ||
17007 | The point alpha value is modified by computing: | |
17008 | ||
3c9b6116 | 17009 | @r{@var{pointAlpha}=@{(1), |
8925f36f AW |
17010 | ((@var{pointSize}/@var{threshold},)^2)(@var{pointSize}>=@var{threshold}), |
17011 | (@var{otherwise}),} | |
17012 | ||
17013 | If point antialiasing is disabled, the actual size is determined by | |
17014 | rounding the supplied size to the nearest integer. (If the rounding | |
17015 | results in the value 0, it is as if the point size were 1.) If the | |
3c9b6116 AW |
17016 | rounded size is odd, then the center point (@r{@var{x}}, @r{@var{y}}) of |
17017 | the pixel fragment that represents the point is computed as | |
8925f36f | 17018 | |
3c9b6116 | 17019 | @r{(⌊@var{x}_@var{w},⌋+.5,⌊@var{y}_@var{w},⌋+.5)} |
8925f36f | 17020 | |
3c9b6116 | 17021 | where @r{@var{w}} subscripts indicate window coordinates. All pixels |
8925f36f | 17022 | that lie within the square grid of the rounded size centered at |
3c9b6116 AW |
17023 | (@r{@var{x}}, @r{@var{y}}) make up the fragment. If the size is even, |
17024 | the center point is | |
8925f36f | 17025 | |
3c9b6116 | 17026 | @r{(⌊@var{x}_@var{w}+.5,⌋,⌊@var{y}_@var{w}+.5,⌋)} |
8925f36f AW |
17027 | |
17028 | and the rasterized fragment's centers are the half-integer window | |
17029 | coordinates within the square of the rounded size centered at | |
3c9b6116 | 17030 | @r{(@var{x},@var{y})}. All pixel fragments produced in rasterizing a |
8925f36f AW |
17031 | nonantialiased point are assigned the same associated data, that of the |
17032 | vertex corresponding to the point. | |
17033 | ||
17034 | If antialiasing is enabled, then point rasterization produces a fragment | |
17035 | for each pixel square that intersects the region lying within the circle | |
17036 | having diameter equal to the current point size and centered at the | |
3c9b6116 | 17037 | point's @r{(@var{x}_@var{w},@var{y}_@var{w})}. The coverage value for |
8925f36f AW |
17038 | each fragment is the window coordinate area of the intersection of the |
17039 | circular region with the corresponding pixel square. This value is saved | |
17040 | and used in the final rasterization step. The data associated with each | |
17041 | fragment is the data associated with the point being rasterized. | |
17042 | ||
17043 | Not all sizes are supported when point antialiasing is enabled. If an | |
17044 | unsupported size is requested, the nearest supported size is used. Only | |
17045 | size 1 is guaranteed to be supported; others depend on the | |
17046 | implementation. To query the range of supported sizes and the size | |
17047 | difference between supported sizes within the range, call @code{glGet} | |
17048 | with arguments @code{GL_SMOOTH_POINT_SIZE_RANGE} and | |
17049 | @code{GL_SMOOTH_POINT_SIZE_GRANULARITY}. For aliased points, query the | |
17050 | supported ranges and granularity with @code{glGet} with arguments | |
17051 | @code{GL_ALIASED_POINT_SIZE_RANGE}. | |
17052 | ||
8925f36f AW |
17053 | @code{GL_INVALID_VALUE} is generated if @var{size} is less than or equal |
17054 | to 0. | |
17055 | ||
17056 | @code{GL_INVALID_OPERATION} is generated if @code{glPointSize} is | |
17057 | executed between the execution of @code{glBegin} and the corresponding | |
17058 | execution of @code{glEnd}. | |
17059 | ||
bb894c9d | 17060 | @end deftypefun |
8925f36f | 17061 | |
bb894c9d | 17062 | @deftypefun void glPolygonMode face mode |
3c9b6116 AW |
17063 | Select a polygon rasterization mode. |
17064 | ||
8925f36f AW |
17065 | @table @asis |
17066 | @item @var{face} | |
17067 | Specifies the polygons that @var{mode} applies to. Must be | |
17068 | @code{GL_FRONT} for front-facing polygons, @code{GL_BACK} for | |
17069 | back-facing polygons, or @code{GL_FRONT_AND_BACK} for front- and | |
17070 | back-facing polygons. | |
17071 | ||
17072 | @item @var{mode} | |
17073 | Specifies how polygons will be rasterized. Accepted values are | |
17074 | @code{GL_POINT}, @code{GL_LINE}, and @code{GL_FILL}. The initial value | |
17075 | is @code{GL_FILL} for both front- and back-facing polygons. | |
17076 | ||
17077 | @end table | |
17078 | ||
8925f36f AW |
17079 | @code{glPolygonMode} controls the interpretation of polygons for |
17080 | rasterization. @var{face} describes which polygons @var{mode} applies | |
17081 | to: front-facing polygons (@code{GL_FRONT}), back-facing polygons | |
17082 | (@code{GL_BACK}), or both (@code{GL_FRONT_AND_BACK}). The polygon mode | |
17083 | affects only the final rasterization of polygons. In particular, a | |
17084 | polygon's vertices are lit and the polygon is clipped and possibly | |
17085 | culled before these modes are applied. | |
17086 | ||
17087 | Three modes are defined and can be specified in @var{mode}: | |
17088 | ||
17089 | @table @asis | |
17090 | @item @code{GL_POINT} | |
17091 | Polygon vertices that are marked as the start of a boundary edge are | |
17092 | drawn as points. Point attributes such as @code{GL_POINT_SIZE} and | |
17093 | @code{GL_POINT_SMOOTH} control the rasterization of the points. Polygon | |
17094 | rasterization attributes other than @code{GL_POLYGON_MODE} have no | |
17095 | effect. | |
17096 | ||
17097 | @item @code{GL_LINE} | |
17098 | Boundary edges of the polygon are drawn as line segments. They are | |
17099 | treated as connected line segments for line stippling; the line stipple | |
17100 | counter and pattern are not reset between segments (see | |
17101 | @code{glLineStipple}). Line attributes such as @code{GL_LINE_WIDTH} and | |
17102 | @code{GL_LINE_SMOOTH} control the rasterization of the lines. Polygon | |
17103 | rasterization attributes other than @code{GL_POLYGON_MODE} have no | |
17104 | effect. | |
17105 | ||
17106 | @item @code{GL_FILL} | |
17107 | The interior of the polygon is filled. Polygon attributes such as | |
17108 | @code{GL_POLYGON_STIPPLE} and @code{GL_POLYGON_SMOOTH} control the | |
17109 | rasterization of the polygon. | |
17110 | ||
17111 | @end table | |
17112 | ||
8925f36f AW |
17113 | @code{GL_INVALID_ENUM} is generated if either @var{face} or @var{mode} |
17114 | is not an accepted value. | |
17115 | ||
17116 | @code{GL_INVALID_OPERATION} is generated if @code{glPolygonMode} is | |
17117 | executed between the execution of @code{glBegin} and the corresponding | |
17118 | execution of @code{glEnd}. | |
17119 | ||
bb894c9d | 17120 | @end deftypefun |
8925f36f | 17121 | |
bb894c9d | 17122 | @deftypefun void glPolygonOffset factor units |
3c9b6116 AW |
17123 | Set the scale and units used to calculate depth values. |
17124 | ||
8925f36f AW |
17125 | @table @asis |
17126 | @item @var{factor} | |
17127 | Specifies a scale factor that is used to create a variable depth offset | |
17128 | for each polygon. The initial value is 0. | |
17129 | ||
17130 | @item @var{units} | |
17131 | Is multiplied by an implementation-specific value to create a constant | |
17132 | depth offset. The initial value is 0. | |
17133 | ||
17134 | @end table | |
17135 | ||
8925f36f AW |
17136 | When @code{GL_POLYGON_OFFSET_FILL}, @code{GL_POLYGON_OFFSET_LINE}, or |
17137 | @code{GL_POLYGON_OFFSET_POINT} is enabled, each fragment's @var{depth} | |
17138 | value will be offset after it is interpolated from the @var{depth} | |
17139 | values of the appropriate vertices. The value of the offset is | |
3c9b6116 AW |
17140 | @r{@var{factor}×@var{DZ}+@var{r}×@var{units}}, where @r{@var{DZ}} is a |
17141 | measurement of the change in depth relative to the screen area of the | |
17142 | polygon, and @r{@var{r}} is the smallest value that is guaranteed to | |
17143 | produce a resolvable offset for a given implementation. The offset is | |
8925f36f AW |
17144 | added before the depth test is performed and before the value is written |
17145 | into the depth buffer. | |
17146 | ||
17147 | @code{glPolygonOffset} is useful for rendering hidden-line images, for | |
17148 | applying decals to surfaces, and for rendering solids with highlighted | |
17149 | edges. | |
17150 | ||
8925f36f AW |
17151 | @code{GL_INVALID_OPERATION} is generated if @code{glPolygonOffset} is |
17152 | executed between the execution of @code{glBegin} and the corresponding | |
17153 | execution of @code{glEnd}. | |
17154 | ||
bb894c9d | 17155 | @end deftypefun |
8925f36f | 17156 | |
bb894c9d | 17157 | @deftypefun void glPolygonStipple pattern |
3c9b6116 AW |
17158 | Set the polygon stippling pattern. |
17159 | ||
8925f36f AW |
17160 | @table @asis |
17161 | @item @var{pattern} | |
3c9b6116 AW |
17162 | Specifies a pointer to a @r{32×32} stipple pattern that will be unpacked |
17163 | from memory in the same way that @code{glDrawPixels} unpacks pixels. | |
8925f36f AW |
17164 | |
17165 | @end table | |
17166 | ||
8925f36f AW |
17167 | Polygon stippling, like line stippling (see @code{glLineStipple}), masks |
17168 | out certain fragments produced by rasterization, creating a pattern. | |
17169 | Stippling is independent of polygon antialiasing. | |
17170 | ||
3c9b6116 AW |
17171 | @var{pattern} is a pointer to a @r{32×32} stipple pattern that is stored |
17172 | in memory just like the pixel data supplied to a @code{glDrawPixels} | |
17173 | call with height and @var{width} both equal to 32, a pixel format of | |
17174 | @code{GL_COLOR_INDEX}, and data type of @code{GL_BITMAP}. That is, the | |
17175 | stipple pattern is represented as a @r{32×32} array of 1-bit color | |
17176 | indices packed in unsigned bytes. @code{glPixelStore} parameters like | |
17177 | @code{GL_UNPACK_SWAP_BYTES} and @code{GL_UNPACK_LSB_FIRST} affect the | |
17178 | assembling of the bits into a stipple pattern. Pixel transfer operations | |
17179 | (shift, offset, pixel map) are not applied to the stipple image, | |
17180 | however. | |
8925f36f AW |
17181 | |
17182 | If a non-zero named buffer object is bound to the | |
17183 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
17184 | stipple pattern is specified, @var{pattern} is treated as a byte offset | |
17185 | into the buffer object's data store. | |
17186 | ||
17187 | To enable and disable polygon stippling, call @code{glEnable} and | |
17188 | @code{glDisable} with argument @code{GL_POLYGON_STIPPLE}. Polygon | |
17189 | stippling is initially disabled. If it's enabled, a rasterized polygon | |
3c9b6116 AW |
17190 | fragment with window coordinates @r{@var{x}_@var{w}} and |
17191 | @r{@var{y}_@var{w}} is sent to the next stage of the GL if and only if | |
17192 | the (@r{@var{x}_@var{w}%32})th bit in the (@r{@var{y}_@var{w}%32})th row | |
17193 | of the stipple pattern is 1 (one). When polygon stippling is disabled, | |
17194 | it is as if the stipple pattern consists of all 1's. | |
17195 | ||
8925f36f AW |
17196 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object |
17197 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
17198 | object's data store is currently mapped. | |
17199 | ||
17200 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
17201 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
17202 | would be unpacked from the buffer object such that the memory reads | |
17203 | required would exceed the data store size. | |
17204 | ||
17205 | @code{GL_INVALID_OPERATION} is generated if @code{glPolygonStipple} is | |
17206 | executed between the execution of @code{glBegin} and the corresponding | |
17207 | execution of @code{glEnd}. | |
17208 | ||
bb894c9d | 17209 | @end deftypefun |
8925f36f | 17210 | |
bb894c9d | 17211 | @deftypefun void glPrioritizeTextures n textures priorities |
3c9b6116 AW |
17212 | Set texture residence priority. |
17213 | ||
8925f36f AW |
17214 | @table @asis |
17215 | @item @var{n} | |
17216 | Specifies the number of textures to be prioritized. | |
17217 | ||
17218 | @item @var{textures} | |
17219 | Specifies an array containing the names of the textures to be | |
17220 | prioritized. | |
17221 | ||
17222 | @item @var{priorities} | |
17223 | Specifies an array containing the texture priorities. A priority given | |
17224 | in an element of @var{priorities} applies to the texture named by the | |
17225 | corresponding element of @var{textures}. | |
17226 | ||
17227 | @end table | |
17228 | ||
8925f36f AW |
17229 | @code{glPrioritizeTextures} assigns the @var{n} texture priorities given |
17230 | in @var{priorities} to the @var{n} textures named in @var{textures}. | |
17231 | ||
17232 | The GL establishes a ``working set'' of textures that are resident in | |
17233 | texture memory. These textures may be bound to a texture target much | |
17234 | more efficiently than textures that are not resident. By specifying a | |
17235 | priority for each texture, @code{glPrioritizeTextures} allows | |
17236 | applications to guide the GL implementation in determining which | |
17237 | textures should be resident. | |
17238 | ||
17239 | The priorities given in @var{priorities} are clamped to the range | |
3c9b6116 | 17240 | @r{[0,1]} before they are assigned. 0 indicates the lowest priority; |
8925f36f AW |
17241 | textures with priority 0 are least likely to be resident. 1 indicates |
17242 | the highest priority; textures with priority 1 are most likely to be | |
17243 | resident. However, textures are not guaranteed to be resident until they | |
17244 | are used. | |
17245 | ||
17246 | @code{glPrioritizeTextures} silently ignores attempts to prioritize | |
17247 | texture 0 or any texture name that does not correspond to an existing | |
17248 | texture. | |
17249 | ||
17250 | @code{glPrioritizeTextures} does not require that any of the textures | |
17251 | named by @var{textures} be bound to a texture target. | |
17252 | @code{glTexParameter} may also be used to set a texture's priority, but | |
17253 | only if the texture is currently bound. This is the only way to set the | |
17254 | priority of a default texture. | |
17255 | ||
8925f36f AW |
17256 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
17257 | ||
17258 | @code{GL_INVALID_OPERATION} is generated if @code{glPrioritizeTextures} | |
17259 | is executed between the execution of @code{glBegin} and the | |
17260 | corresponding execution of @code{glEnd}. | |
17261 | ||
bb894c9d | 17262 | @end deftypefun |
8925f36f | 17263 | |
bb894c9d AW |
17264 | @deftypefun void glPushAttrib mask |
17265 | @deftypefunx void glPopAttrib | |
3c9b6116 AW |
17266 | Push and pop the server attribute stack. |
17267 | ||
8925f36f AW |
17268 | @table @asis |
17269 | @item @var{mask} | |
17270 | Specifies a mask that indicates which attributes to save. Values for | |
17271 | @var{mask} are listed below. | |
17272 | ||
17273 | @end table | |
17274 | ||
8925f36f AW |
17275 | @code{glPushAttrib} takes one argument, a mask that indicates which |
17276 | groups of state variables to save on the attribute stack. Symbolic | |
17277 | constants are used to set bits in the mask. @var{mask} is typically | |
17278 | constructed by specifying the bitwise-or of several of these constants | |
17279 | together. The special mask @code{GL_ALL_ATTRIB_BITS} can be used to save | |
17280 | all stackable states. | |
17281 | ||
17282 | The symbolic mask constants and their associated GL state are as follows | |
17283 | (the second column lists which attributes are saved): | |
17284 | ||
17285 | ||
17286 | ||
17287 | @table @asis | |
17288 | @item @code{GL_ACCUM_BUFFER_BIT} | |
17289 | Accumulation buffer clear value | |
17290 | ||
17291 | @item @code{GL_COLOR_BUFFER_BIT} | |
17292 | @code{GL_ALPHA_TEST} enable bit | |
17293 | ||
17294 | @item | |
17295 | Alpha test function and reference value | |
17296 | ||
17297 | @item | |
17298 | @code{GL_BLEND} enable bit | |
17299 | ||
17300 | @item | |
17301 | Blending source and destination functions | |
17302 | ||
17303 | @item | |
17304 | Constant blend color | |
17305 | ||
17306 | @item | |
17307 | Blending equation | |
17308 | ||
17309 | @item | |
17310 | @code{GL_DITHER} enable bit | |
17311 | ||
17312 | @item | |
17313 | @code{GL_DRAW_BUFFER} setting | |
17314 | ||
17315 | @item | |
17316 | @code{GL_COLOR_LOGIC_OP} enable bit | |
17317 | ||
17318 | @item | |
17319 | @code{GL_INDEX_LOGIC_OP} enable bit | |
17320 | ||
17321 | @item | |
17322 | Logic op function | |
17323 | ||
17324 | @item | |
17325 | Color mode and index mode clear values | |
17326 | ||
17327 | @item | |
17328 | Color mode and index mode writemasks | |
17329 | ||
17330 | @item @code{GL_CURRENT_BIT} | |
17331 | Current RGBA color | |
17332 | ||
17333 | @item | |
17334 | Current color index | |
17335 | ||
17336 | @item | |
17337 | Current normal vector | |
17338 | ||
17339 | @item | |
17340 | Current texture coordinates | |
17341 | ||
17342 | @item | |
17343 | Current raster position | |
17344 | ||
17345 | @item | |
17346 | @code{GL_CURRENT_RASTER_POSITION_VALID} flag | |
17347 | ||
17348 | @item | |
17349 | RGBA color associated with current raster position | |
17350 | ||
17351 | @item | |
17352 | Color index associated with current raster position | |
17353 | ||
17354 | @item | |
17355 | Texture coordinates associated with current raster position | |
17356 | ||
17357 | @item | |
17358 | @code{GL_EDGE_FLAG} flag | |
17359 | ||
17360 | @item @code{GL_DEPTH_BUFFER_BIT} | |
17361 | @code{GL_DEPTH_TEST} enable bit | |
17362 | ||
17363 | @item | |
17364 | Depth buffer test function | |
17365 | ||
17366 | @item | |
17367 | Depth buffer clear value | |
17368 | ||
17369 | @item | |
17370 | @code{GL_DEPTH_WRITEMASK} enable bit | |
17371 | ||
17372 | @item @code{GL_ENABLE_BIT} | |
17373 | @code{GL_ALPHA_TEST} flag | |
17374 | ||
17375 | @item | |
17376 | @code{GL_AUTO_NORMAL} flag | |
17377 | ||
17378 | @item | |
17379 | @code{GL_BLEND} flag | |
17380 | ||
17381 | @item | |
17382 | Enable bits for the user-definable clipping planes | |
17383 | ||
17384 | @item | |
17385 | @code{GL_COLOR_MATERIAL} | |
17386 | ||
17387 | @item | |
17388 | @code{GL_CULL_FACE} flag | |
17389 | ||
17390 | @item | |
17391 | @code{GL_DEPTH_TEST} flag | |
17392 | ||
17393 | @item | |
17394 | @code{GL_DITHER} flag | |
17395 | ||
17396 | @item | |
17397 | @code{GL_FOG} flag | |
17398 | ||
17399 | @item | |
17400 | @code{GL_LIGHT}@var{i} where @code{0} <= @var{i} < @code{GL_MAX_LIGHTS} | |
17401 | ||
17402 | @item | |
17403 | @code{GL_LIGHTING} flag | |
17404 | ||
17405 | @item | |
17406 | @code{GL_LINE_SMOOTH} flag | |
17407 | ||
17408 | @item | |
17409 | @code{GL_LINE_STIPPLE} flag | |
17410 | ||
17411 | @item | |
17412 | @code{GL_COLOR_LOGIC_OP} flag | |
17413 | ||
17414 | @item | |
17415 | @code{GL_INDEX_LOGIC_OP} flag | |
17416 | ||
17417 | @item | |
17418 | @code{GL_MAP1_}@var{x} where @var{x} is a map type | |
17419 | ||
17420 | @item | |
17421 | @code{GL_MAP2_}@var{x} where @var{x} is a map type | |
17422 | ||
17423 | @item | |
17424 | @code{GL_MULTISAMPLE} flag | |
17425 | ||
17426 | @item | |
17427 | @code{GL_NORMALIZE} flag | |
17428 | ||
17429 | @item | |
17430 | @code{GL_POINT_SMOOTH} flag | |
17431 | ||
17432 | @item | |
17433 | @code{GL_POLYGON_OFFSET_LINE} flag | |
17434 | ||
17435 | @item | |
17436 | @code{GL_POLYGON_OFFSET_FILL} flag | |
17437 | ||
17438 | @item | |
17439 | @code{GL_POLYGON_OFFSET_POINT} flag | |
17440 | ||
17441 | @item | |
17442 | @code{GL_POLYGON_SMOOTH} flag | |
17443 | ||
17444 | @item | |
17445 | @code{GL_POLYGON_STIPPLE} flag | |
17446 | ||
17447 | @item | |
17448 | @code{GL_SAMPLE_ALPHA_TO_COVERAGE} flag | |
17449 | ||
17450 | @item | |
17451 | @code{GL_SAMPLE_ALPHA_TO_ONE} flag | |
17452 | ||
17453 | @item | |
17454 | @code{GL_SAMPLE_COVERAGE} flag | |
17455 | ||
17456 | @item | |
17457 | @code{GL_SCISSOR_TEST} flag | |
17458 | ||
17459 | @item | |
17460 | @code{GL_STENCIL_TEST} flag | |
17461 | ||
17462 | @item | |
17463 | @code{GL_TEXTURE_1D} flag | |
17464 | ||
17465 | @item | |
17466 | @code{GL_TEXTURE_2D} flag | |
17467 | ||
17468 | @item | |
17469 | @code{GL_TEXTURE_3D} flag | |
17470 | ||
17471 | @item | |
17472 | Flags @code{GL_TEXTURE_GEN_}@var{x} where @var{x} is S, T, R, or Q | |
17473 | ||
17474 | @item @code{GL_EVAL_BIT} | |
17475 | @code{GL_MAP1_}@var{x} enable bits, where @var{x} is a map type | |
17476 | ||
17477 | @item | |
17478 | @code{GL_MAP2_}@var{x} enable bits, where @var{x} is a map type | |
17479 | ||
17480 | @item | |
17481 | 1D grid endpoints and divisions | |
17482 | ||
17483 | @item | |
17484 | 2D grid endpoints and divisions | |
17485 | ||
17486 | @item | |
17487 | @code{GL_AUTO_NORMAL} enable bit | |
17488 | ||
17489 | @item @code{GL_FOG_BIT} | |
17490 | @code{GL_FOG} enable bit | |
17491 | ||
17492 | @item | |
17493 | Fog color | |
17494 | ||
17495 | @item | |
17496 | Fog density | |
17497 | ||
17498 | @item | |
17499 | Linear fog start | |
17500 | ||
17501 | @item | |
17502 | Linear fog end | |
17503 | ||
17504 | @item | |
17505 | Fog index | |
17506 | ||
17507 | @item | |
17508 | @code{GL_FOG_MODE} value | |
17509 | ||
17510 | @item @code{GL_HINT_BIT} | |
17511 | @code{GL_PERSPECTIVE_CORRECTION_HINT} setting | |
17512 | ||
17513 | @item | |
17514 | @code{GL_POINT_SMOOTH_HINT} setting | |
17515 | ||
17516 | @item | |
17517 | @code{GL_LINE_SMOOTH_HINT} setting | |
17518 | ||
17519 | @item | |
17520 | @code{GL_POLYGON_SMOOTH_HINT} setting | |
17521 | ||
17522 | @item | |
17523 | @code{GL_FOG_HINT} setting | |
17524 | ||
17525 | @item | |
17526 | @code{GL_GENERATE_MIPMAP_HINT} setting | |
17527 | ||
17528 | @item | |
17529 | @code{GL_TEXTURE_COMPRESSION_HINT} setting | |
17530 | ||
17531 | @item @code{GL_LIGHTING_BIT} | |
17532 | @code{GL_COLOR_MATERIAL} enable bit | |
17533 | ||
17534 | @item | |
17535 | @code{GL_COLOR_MATERIAL_FACE} value | |
17536 | ||
17537 | @item | |
17538 | Color material parameters that are tracking the current color | |
17539 | ||
17540 | @item | |
17541 | Ambient scene color | |
17542 | ||
17543 | @item | |
17544 | @code{GL_LIGHT_MODEL_LOCAL_VIEWER} value | |
17545 | ||
17546 | @item | |
17547 | @code{GL_LIGHT_MODEL_TWO_SIDE} setting | |
17548 | ||
17549 | @item | |
17550 | @code{GL_LIGHTING} enable bit | |
17551 | ||
17552 | @item | |
17553 | Enable bit for each light | |
17554 | ||
17555 | @item | |
17556 | Ambient, diffuse, and specular intensity for each light | |
17557 | ||
17558 | @item | |
17559 | Direction, position, exponent, and cutoff angle for each light | |
17560 | ||
17561 | @item | |
17562 | Constant, linear, and quadratic attenuation factors for each light | |
17563 | ||
17564 | @item | |
17565 | Ambient, diffuse, specular, and emissive color for each material | |
17566 | ||
17567 | @item | |
17568 | Ambient, diffuse, and specular color indices for each material | |
17569 | ||
17570 | @item | |
17571 | Specular exponent for each material | |
17572 | ||
17573 | @item | |
17574 | @code{GL_SHADE_MODEL} setting | |
17575 | ||
17576 | @item @code{GL_LINE_BIT} | |
17577 | @code{GL_LINE_SMOOTH} flag | |
17578 | ||
17579 | @item | |
17580 | @code{GL_LINE_STIPPLE} enable bit | |
17581 | ||
17582 | @item | |
17583 | Line stipple pattern and repeat counter | |
17584 | ||
17585 | @item | |
17586 | Line width | |
17587 | ||
17588 | @item @code{GL_LIST_BIT} | |
17589 | @code{GL_LIST_BASE} setting | |
17590 | ||
17591 | @item @code{GL_MULTISAMPLE_BIT} | |
17592 | @code{GL_MULTISAMPLE} flag | |
17593 | ||
17594 | @item | |
17595 | @code{GL_SAMPLE_ALPHA_TO_COVERAGE} flag | |
17596 | ||
17597 | @item | |
17598 | @code{GL_SAMPLE_ALPHA_TO_ONE} flag | |
17599 | ||
17600 | @item | |
17601 | @code{GL_SAMPLE_COVERAGE} flag | |
17602 | ||
17603 | @item | |
17604 | @code{GL_SAMPLE_COVERAGE_VALUE} value | |
17605 | ||
17606 | @item | |
17607 | @code{GL_SAMPLE_COVERAGE_INVERT} value | |
17608 | ||
17609 | @item @code{GL_PIXEL_MODE_BIT} | |
17610 | @code{GL_RED_BIAS} and @code{GL_RED_SCALE} settings | |
17611 | ||
17612 | @item | |
17613 | @code{GL_GREEN_BIAS} and @code{GL_GREEN_SCALE} values | |
17614 | ||
17615 | @item | |
17616 | @code{GL_BLUE_BIAS} and @code{GL_BLUE_SCALE} | |
17617 | ||
17618 | @item | |
17619 | @code{GL_ALPHA_BIAS} and @code{GL_ALPHA_SCALE} | |
17620 | ||
17621 | @item | |
17622 | @code{GL_DEPTH_BIAS} and @code{GL_DEPTH_SCALE} | |
17623 | ||
17624 | @item | |
17625 | @code{GL_INDEX_OFFSET} and @code{GL_INDEX_SHIFT} values | |
17626 | ||
17627 | @item | |
17628 | @code{GL_MAP_COLOR} and @code{GL_MAP_STENCIL} flags | |
17629 | ||
17630 | @item | |
17631 | @code{GL_ZOOM_X} and @code{GL_ZOOM_Y} factors | |
17632 | ||
17633 | @item | |
17634 | @code{GL_READ_BUFFER} setting | |
17635 | ||
17636 | @item @code{GL_POINT_BIT} | |
17637 | @code{GL_POINT_SMOOTH} flag | |
17638 | ||
17639 | @item | |
17640 | Point size | |
17641 | ||
17642 | @item @code{GL_POLYGON_BIT} | |
17643 | @code{GL_CULL_FACE} enable bit | |
17644 | ||
17645 | @item | |
17646 | @code{GL_CULL_FACE_MODE} value | |
17647 | ||
17648 | @item | |
17649 | @code{GL_FRONT_FACE} indicator | |
17650 | ||
17651 | @item | |
17652 | @code{GL_POLYGON_MODE} setting | |
17653 | ||
17654 | @item | |
17655 | @code{GL_POLYGON_SMOOTH} flag | |
17656 | ||
17657 | @item | |
17658 | @code{GL_POLYGON_STIPPLE} enable bit | |
17659 | ||
17660 | @item | |
17661 | @code{GL_POLYGON_OFFSET_FILL} flag | |
17662 | ||
17663 | @item | |
17664 | @code{GL_POLYGON_OFFSET_LINE} flag | |
17665 | ||
17666 | @item | |
17667 | @code{GL_POLYGON_OFFSET_POINT} flag | |
17668 | ||
17669 | @item | |
17670 | @code{GL_POLYGON_OFFSET_FACTOR} | |
17671 | ||
17672 | @item | |
17673 | @code{GL_POLYGON_OFFSET_UNITS} | |
17674 | ||
17675 | @item @code{GL_POLYGON_STIPPLE_BIT} | |
17676 | Polygon stipple image | |
17677 | ||
17678 | @item @code{GL_SCISSOR_BIT} | |
17679 | @code{GL_SCISSOR_TEST} flag | |
17680 | ||
17681 | @item | |
17682 | Scissor box | |
17683 | ||
17684 | @item @code{GL_STENCIL_BUFFER_BIT} | |
17685 | @code{GL_STENCIL_TEST} enable bit | |
17686 | ||
17687 | @item | |
17688 | Stencil function and reference value | |
17689 | ||
17690 | @item | |
17691 | Stencil value mask | |
17692 | ||
17693 | @item | |
17694 | Stencil fail, pass, and depth buffer pass actions | |
17695 | ||
17696 | @item | |
17697 | Stencil buffer clear value | |
17698 | ||
17699 | @item | |
17700 | Stencil buffer writemask | |
17701 | ||
17702 | @item @code{GL_TEXTURE_BIT} | |
17703 | Enable bits for the four texture coordinates | |
17704 | ||
17705 | @item | |
17706 | Border color for each texture image | |
17707 | ||
17708 | @item | |
17709 | Minification function for each texture image | |
17710 | ||
17711 | @item | |
17712 | Magnification function for each texture image | |
17713 | ||
17714 | @item | |
17715 | Texture coordinates and wrap mode for each texture image | |
17716 | ||
17717 | @item | |
17718 | Color and mode for each texture environment | |
17719 | ||
17720 | @item | |
17721 | Enable bits @code{GL_TEXTURE_GEN_}@var{x}, @var{x} is S, T, R, and Q | |
17722 | ||
17723 | @item | |
17724 | @code{GL_TEXTURE_GEN_MODE} setting for S, T, R, and Q | |
17725 | ||
17726 | @item | |
17727 | @code{glTexGen} plane equations for S, T, R, and Q | |
17728 | ||
17729 | @item | |
17730 | Current texture bindings (for example, @code{GL_TEXTURE_BINDING_2D}) | |
17731 | ||
17732 | @item @code{GL_TRANSFORM_BIT} | |
17733 | Coefficients of the six clipping planes | |
17734 | ||
17735 | @item | |
17736 | Enable bits for the user-definable clipping planes | |
17737 | ||
17738 | @item | |
17739 | @code{GL_MATRIX_MODE} value | |
17740 | ||
17741 | @item | |
17742 | @code{GL_NORMALIZE} flag | |
17743 | ||
17744 | @item | |
17745 | @code{GL_RESCALE_NORMAL} flag | |
17746 | ||
17747 | @item @code{GL_VIEWPORT_BIT} | |
17748 | Depth range (near and far) | |
17749 | ||
17750 | @item | |
17751 | Viewport origin and extent | |
17752 | ||
17753 | @end table | |
17754 | ||
17755 | @code{glPopAttrib} restores the values of the state variables saved with | |
17756 | the last @code{glPushAttrib} command. Those not saved are left | |
17757 | unchanged. | |
17758 | ||
17759 | It is an error to push attributes onto a full stack or to pop attributes | |
17760 | off an empty stack. In either case, the error flag is set and no other | |
17761 | change is made to GL state. | |
17762 | ||
17763 | Initially, the attribute stack is empty. | |
17764 | ||
8925f36f AW |
17765 | @code{GL_STACK_OVERFLOW} is generated if @code{glPushAttrib} is called |
17766 | while the attribute stack is full. | |
17767 | ||
17768 | @code{GL_STACK_UNDERFLOW} is generated if @code{glPopAttrib} is called | |
17769 | while the attribute stack is empty. | |
17770 | ||
17771 | @code{GL_INVALID_OPERATION} is generated if @code{glPushAttrib} or | |
17772 | @code{glPopAttrib} is executed between the execution of @code{glBegin} | |
17773 | and the corresponding execution of @code{glEnd}. | |
17774 | ||
bb894c9d | 17775 | @end deftypefun |
8925f36f | 17776 | |
bb894c9d AW |
17777 | @deftypefun void glPushClientAttrib mask |
17778 | @deftypefunx void glPopClientAttrib | |
3c9b6116 AW |
17779 | Push and pop the client attribute stack. |
17780 | ||
8925f36f AW |
17781 | @table @asis |
17782 | @item @var{mask} | |
17783 | Specifies a mask that indicates which attributes to save. Values for | |
17784 | @var{mask} are listed below. | |
17785 | ||
17786 | @end table | |
17787 | ||
8925f36f AW |
17788 | @code{glPushClientAttrib} takes one argument, a mask that indicates |
17789 | which groups of client-state variables to save on the client attribute | |
17790 | stack. Symbolic constants are used to set bits in the mask. @var{mask} | |
17791 | is typically constructed by specifying the bitwise-or of several of | |
17792 | these constants together. The special mask | |
17793 | @code{GL_CLIENT_ALL_ATTRIB_BITS} can be used to save all stackable | |
17794 | client state. | |
17795 | ||
17796 | The symbolic mask constants and their associated GL client state are as | |
17797 | follows (the second column lists which attributes are saved): | |
17798 | ||
17799 | @code{GL_CLIENT_PIXEL_STORE_BIT} Pixel storage modes | |
17800 | @code{GL_CLIENT_VERTEX_ARRAY_BIT} Vertex arrays (and enables) | |
17801 | ||
17802 | @code{glPopClientAttrib} restores the values of the client-state | |
17803 | variables saved with the last @code{glPushClientAttrib}. Those not saved | |
17804 | are left unchanged. | |
17805 | ||
17806 | It is an error to push attributes onto a full client attribute stack or | |
17807 | to pop attributes off an empty stack. In either case, the error flag is | |
17808 | set, and no other change is made to GL state. | |
17809 | ||
17810 | Initially, the client attribute stack is empty. | |
17811 | ||
8925f36f AW |
17812 | @code{GL_STACK_OVERFLOW} is generated if @code{glPushClientAttrib} is |
17813 | called while the attribute stack is full. | |
17814 | ||
17815 | @code{GL_STACK_UNDERFLOW} is generated if @code{glPopClientAttrib} is | |
17816 | called while the attribute stack is empty. | |
17817 | ||
bb894c9d | 17818 | @end deftypefun |
8925f36f | 17819 | |
bb894c9d AW |
17820 | @deftypefun void glPushMatrix |
17821 | @deftypefunx void glPopMatrix | |
3c9b6116 AW |
17822 | Push and pop the current matrix stack. |
17823 | ||
8925f36f AW |
17824 | There is a stack of matrices for each of the matrix modes. In |
17825 | @code{GL_MODELVIEW} mode, the stack depth is at least 32. In the other | |
17826 | modes, @code{GL_COLOR}, @code{GL_PROJECTION}, and @code{GL_TEXTURE}, the | |
17827 | depth is at least 2. The current matrix in any mode is the matrix on the | |
17828 | top of the stack for that mode. | |
17829 | ||
17830 | @code{glPushMatrix} pushes the current matrix stack down by one, | |
17831 | duplicating the current matrix. That is, after a @code{glPushMatrix} | |
17832 | call, the matrix on top of the stack is identical to the one below it. | |
17833 | ||
17834 | @code{glPopMatrix} pops the current matrix stack, replacing the current | |
17835 | matrix with the one below it on the stack. | |
17836 | ||
17837 | Initially, each of the stacks contains one matrix, an identity matrix. | |
17838 | ||
17839 | It is an error to push a full matrix stack or to pop a matrix stack that | |
17840 | contains only a single matrix. In either case, the error flag is set and | |
17841 | no other change is made to GL state. | |
17842 | ||
8925f36f AW |
17843 | @code{GL_STACK_OVERFLOW} is generated if @code{glPushMatrix} is called |
17844 | while the current matrix stack is full. | |
17845 | ||
17846 | @code{GL_STACK_UNDERFLOW} is generated if @code{glPopMatrix} is called | |
17847 | while the current matrix stack contains only a single matrix. | |
17848 | ||
17849 | @code{GL_INVALID_OPERATION} is generated if @code{glPushMatrix} or | |
17850 | @code{glPopMatrix} is executed between the execution of @code{glBegin} | |
17851 | and the corresponding execution of @code{glEnd}. | |
17852 | ||
bb894c9d | 17853 | @end deftypefun |
8925f36f | 17854 | |
bb894c9d AW |
17855 | @deftypefun void glPushName name |
17856 | @deftypefunx void glPopName | |
3c9b6116 AW |
17857 | Push and pop the name stack. |
17858 | ||
8925f36f AW |
17859 | @table @asis |
17860 | @item @var{name} | |
17861 | Specifies a name that will be pushed onto the name stack. | |
17862 | ||
17863 | @end table | |
17864 | ||
8925f36f AW |
17865 | The name stack is used during selection mode to allow sets of rendering |
17866 | commands to be uniquely identified. It consists of an ordered set of | |
17867 | unsigned integers and is initially empty. | |
17868 | ||
17869 | @code{glPushName} causes @var{name} to be pushed onto the name stack. | |
17870 | @code{glPopName} pops one name off the top of the stack. | |
17871 | ||
17872 | The maximum name stack depth is implementation-dependent; call | |
17873 | @code{GL_MAX_NAME_STACK_DEPTH} to find out the value for a particular | |
17874 | implementation. It is an error to push a name onto a full stack or to | |
17875 | pop a name off an empty stack. It is also an error to manipulate the | |
17876 | name stack between the execution of @code{glBegin} and the corresponding | |
17877 | execution of @code{glEnd}. In any of these cases, the error flag is set | |
17878 | and no other change is made to GL state. | |
17879 | ||
17880 | The name stack is always empty while the render mode is not | |
17881 | @code{GL_SELECT}. Calls to @code{glPushName} or @code{glPopName} while | |
17882 | the render mode is not @code{GL_SELECT} are ignored. | |
17883 | ||
8925f36f AW |
17884 | @code{GL_STACK_OVERFLOW} is generated if @code{glPushName} is called |
17885 | while the name stack is full. | |
17886 | ||
17887 | @code{GL_STACK_UNDERFLOW} is generated if @code{glPopName} is called | |
17888 | while the name stack is empty. | |
17889 | ||
17890 | @code{GL_INVALID_OPERATION} is generated if @code{glPushName} or | |
17891 | @code{glPopName} is executed between a call to @code{glBegin} and the | |
17892 | corresponding call to @code{glEnd}. | |
17893 | ||
bb894c9d | 17894 | @end deftypefun |
8925f36f | 17895 | |
bb894c9d | 17896 | @deftypefun void glRasterPos2i x y |
ca09631c | 17897 | @deftypefunx void glRasterPos2f x y |
bb894c9d | 17898 | @deftypefunx void glRasterPos3i x y z |
ca09631c | 17899 | @deftypefunx void glRasterPos3f x y z |
bb894c9d | 17900 | @deftypefunx void glRasterPos4i x y z w |
ca09631c | 17901 | @deftypefunx void glRasterPos4f x y z w |
3c9b6116 AW |
17902 | Specify the raster position for pixel operations. |
17903 | ||
8925f36f AW |
17904 | @table @asis |
17905 | @item @var{x} | |
17906 | @itemx @var{y} | |
17907 | @itemx @var{z} | |
17908 | @itemx @var{w} | |
3c9b6116 AW |
17909 | Specify the @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}} |
17910 | object coordinates (if present) for the raster position. | |
8925f36f AW |
17911 | |
17912 | @end table | |
17913 | ||
8925f36f AW |
17914 | The GL maintains a 3D position in window coordinates. This position, |
17915 | called the raster position, is used to position pixel and bitmap write | |
17916 | operations. It is maintained with subpixel accuracy. See | |
17917 | @code{glBitmap}, @code{glDrawPixels}, and @code{glCopyPixels}. | |
17918 | ||
17919 | The current raster position consists of three window coordinates | |
3c9b6116 AW |
17920 | (@r{@var{x}}, @r{@var{y}}, @r{@var{z}}), a clip coordinate value |
17921 | (@r{@var{w}}), an eye coordinate distance, a valid bit, and associated | |
17922 | color data and texture coordinates. The @r{@var{w}} coordinate is a clip | |
17923 | coordinate, because @r{@var{w}} is not projected to window coordinates. | |
17924 | @code{glRasterPos4} specifies object coordinates @r{@var{x}}, | |
17925 | @r{@var{y}}, @r{@var{z}}, and @r{@var{w}} explicitly. | |
17926 | @code{glRasterPos3} specifies object coordinate @r{@var{x}}, | |
17927 | @r{@var{y}}, and @r{@var{z}} explicitly, while @r{@var{w}} is implicitly | |
17928 | set to 1. @code{glRasterPos2} uses the argument values for @r{@var{x}} | |
17929 | and @r{@var{y}} while implicitly setting @r{@var{z}} and @r{@var{w}} to | |
17930 | 0 and 1. | |
8925f36f AW |
17931 | |
17932 | The object coordinates presented by @code{glRasterPos} are treated just | |
17933 | like those of a @code{glVertex} command: They are transformed by the | |
17934 | current modelview and projection matrices and passed to the clipping | |
17935 | stage. If the vertex is not culled, then it is projected and scaled to | |
17936 | window coordinates, which become the new current raster position, and | |
17937 | the @code{GL_CURRENT_RASTER_POSITION_VALID} flag is set. If the vertex | |
17938 | @var{is} culled, then the valid bit is cleared and the current raster | |
17939 | position and associated color and texture coordinates are undefined. | |
17940 | ||
17941 | The current raster position also includes some associated color data and | |
17942 | texture coordinates. If lighting is enabled, then | |
17943 | @code{GL_CURRENT_RASTER_COLOR} (in RGBA mode) or | |
17944 | @code{GL_CURRENT_RASTER_INDEX} (in color index mode) is set to the color | |
17945 | produced by the lighting calculation (see @code{glLight}, | |
17946 | @code{glLightModel}, and @code{glShadeModel}). If lighting is disabled, | |
17947 | current color (in RGBA mode, state variable @code{GL_CURRENT_COLOR}) or | |
17948 | color index (in color index mode, state variable | |
17949 | @code{GL_CURRENT_INDEX}) is used to update the current raster color. | |
17950 | @code{GL_CURRENT_RASTER_SECONDARY_COLOR} (in RGBA mode) is likewise | |
17951 | updated. | |
17952 | ||
17953 | Likewise, @code{GL_CURRENT_RASTER_TEXTURE_COORDS} is updated as a | |
17954 | function of @code{GL_CURRENT_TEXTURE_COORDS}, based on the texture | |
17955 | matrix and the texture generation functions (see @code{glTexGen}). | |
17956 | Finally, the distance from the origin of the eye coordinate system to | |
17957 | the vertex as transformed by only the modelview matrix replaces | |
17958 | @code{GL_CURRENT_RASTER_DISTANCE}. | |
17959 | ||
17960 | Initially, the current raster position is (0, 0, 0, 1), the current | |
17961 | raster distance is 0, the valid bit is set, the associated RGBA color is | |
17962 | (1, 1, 1, 1), the associated color index is 1, and the associated | |
17963 | texture coordinates are (0, 0, 0, 1). In RGBA mode, | |
17964 | @code{GL_CURRENT_RASTER_INDEX} is always 1; in color index mode, the | |
17965 | current raster RGBA color always maintains its initial value. | |
17966 | ||
8925f36f AW |
17967 | @code{GL_INVALID_OPERATION} is generated if @code{glRasterPos} is |
17968 | executed between the execution of @code{glBegin} and the corresponding | |
17969 | execution of @code{glEnd}. | |
17970 | ||
bb894c9d | 17971 | @end deftypefun |
8925f36f | 17972 | |
bb894c9d | 17973 | @deftypefun void glReadBuffer mode |
3c9b6116 AW |
17974 | Select a color buffer source for pixels. |
17975 | ||
8925f36f AW |
17976 | @table @asis |
17977 | @item @var{mode} | |
17978 | Specifies a color buffer. Accepted values are @code{GL_FRONT_LEFT}, | |
17979 | @code{GL_FRONT_RIGHT}, @code{GL_BACK_LEFT}, @code{GL_BACK_RIGHT}, | |
17980 | @code{GL_FRONT}, @code{GL_BACK}, @code{GL_LEFT}, @code{GL_RIGHT}, and | |
17981 | @code{GL_AUX}@var{i}, where @var{i} is between 0 and the value of | |
17982 | @code{GL_AUX_BUFFERS} minus 1. | |
17983 | ||
17984 | @end table | |
17985 | ||
8925f36f AW |
17986 | @code{glReadBuffer} specifies a color buffer as the source for |
17987 | subsequent @code{glReadPixels}, @code{glCopyTexImage1D}, | |
17988 | @code{glCopyTexImage2D}, @code{glCopyTexSubImage1D}, | |
17989 | @code{glCopyTexSubImage2D}, @code{glCopyTexSubImage3D}, and | |
17990 | @code{glCopyPixels} commands. @var{mode} accepts one of twelve or more | |
17991 | predefined values. (@code{GL_AUX0} through @code{GL_AUX3} are always | |
17992 | defined.) In a fully configured system, @code{GL_FRONT}, @code{GL_LEFT}, | |
17993 | and @code{GL_FRONT_LEFT} all name the front left buffer, | |
17994 | @code{GL_FRONT_RIGHT} and @code{GL_RIGHT} name the front right buffer, | |
17995 | and @code{GL_BACK_LEFT} and @code{GL_BACK} name the back left buffer. | |
17996 | ||
17997 | Nonstereo double-buffered configurations have only a front left and a | |
17998 | back left buffer. Single-buffered configurations have a front left and a | |
17999 | front right buffer if stereo, and only a front left buffer if nonstereo. | |
18000 | It is an error to specify a nonexistent buffer to @code{glReadBuffer}. | |
18001 | ||
18002 | @var{mode} is initially @code{GL_FRONT} in single-buffered | |
18003 | configurations and @code{GL_BACK} in double-buffered configurations. | |
18004 | ||
8925f36f AW |
18005 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of the |
18006 | twelve (or more) accepted values. | |
18007 | ||
18008 | @code{GL_INVALID_OPERATION} is generated if @var{mode} specifies a | |
18009 | buffer that does not exist. | |
18010 | ||
18011 | @code{GL_INVALID_OPERATION} is generated if @code{glReadBuffer} is | |
18012 | executed between the execution of @code{glBegin} and the corresponding | |
18013 | execution of @code{glEnd}. | |
18014 | ||
bb894c9d | 18015 | @end deftypefun |
8925f36f | 18016 | |
bb894c9d | 18017 | @deftypefun void glReadPixels x y width height format type data |
3c9b6116 AW |
18018 | Read a block of pixels from the frame buffer. |
18019 | ||
8925f36f AW |
18020 | @table @asis |
18021 | @item @var{x} | |
18022 | @itemx @var{y} | |
18023 | Specify the window coordinates of the first pixel that is read from the | |
18024 | frame buffer. This location is the lower left corner of a rectangular | |
18025 | block of pixels. | |
18026 | ||
18027 | @item @var{width} | |
18028 | @itemx @var{height} | |
18029 | Specify the dimensions of the pixel rectangle. @var{width} and | |
18030 | @var{height} of one correspond to a single pixel. | |
18031 | ||
18032 | @item @var{format} | |
18033 | Specifies the format of the pixel data. The following symbolic values | |
18034 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, | |
18035 | @code{GL_DEPTH_COMPONENT}, @code{GL_RED}, @code{GL_GREEN}, | |
18036 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
18037 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
18038 | @code{GL_LUMINANCE_ALPHA}. | |
18039 | ||
18040 | @item @var{type} | |
18041 | Specifies the data type of the pixel data. Must be one of | |
18042 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
18043 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
18044 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
18045 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
18046 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
18047 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
18048 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
18049 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
18050 | or @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
18051 | ||
18052 | @item @var{data} | |
18053 | Returns the pixel data. | |
18054 | ||
18055 | @end table | |
18056 | ||
8925f36f AW |
18057 | @code{glReadPixels} returns pixel data from the frame buffer, starting |
18058 | with the pixel whose lower left corner is at location (@var{x}, | |
18059 | @var{y}), into client memory starting at location @var{data}. Several | |
18060 | parameters control the processing of the pixel data before it is placed | |
18061 | into client memory. These parameters are set with three commands: | |
18062 | @code{glPixelStore}, @code{glPixelTransfer}, and @code{glPixelMap}. This | |
18063 | reference page describes the effects on @code{glReadPixels} of most, but | |
18064 | not all of the parameters specified by these three commands. | |
18065 | ||
18066 | If a non-zero named buffer object is bound to the | |
18067 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
18068 | block of pixels is requested, @var{data} is treated as a byte offset | |
18069 | into the buffer object's data store rather than a pointer to client | |
18070 | memory. | |
18071 | ||
18072 | When the @code{ARB_imaging} extension is supported, the pixel data may | |
18073 | be processed by additional operations including color table lookup, | |
18074 | color matrix transformations, convolutions, histograms, and minimum and | |
18075 | maximum pixel value computations. | |
18076 | ||
18077 | @code{glReadPixels} returns values from each pixel with lower left | |
3c9b6116 AW |
18078 | corner at @r{(@var{x}+@var{i},@var{y}+@var{j})} for |
18079 | @r{0<=@var{i}<@var{width}} and @r{0<=@var{j}<@var{height}}. This pixel | |
18080 | is said to be the @r{@var{i}}th pixel in the @r{@var{j}}th row. Pixels | |
18081 | are returned in row order from the lowest to the highest row, left to | |
18082 | right in each row. | |
8925f36f AW |
18083 | |
18084 | @var{format} specifies the format for the returned pixel values; | |
18085 | accepted values are: | |
18086 | ||
18087 | @table @asis | |
18088 | @item @code{GL_COLOR_INDEX} | |
18089 | Color indices are read from the color buffer selected by | |
18090 | @code{glReadBuffer}. Each index is converted to fixed point, shifted | |
18091 | left or right depending on the value and sign of @code{GL_INDEX_SHIFT}, | |
18092 | and added to @code{GL_INDEX_OFFSET}. If @code{GL_MAP_COLOR} is | |
18093 | @code{GL_TRUE}, indices are replaced by their mappings in the table | |
18094 | @code{GL_PIXEL_MAP_I_TO_I}. | |
18095 | ||
18096 | @item @code{GL_STENCIL_INDEX} | |
18097 | Stencil values are read from the stencil buffer. Each index is converted | |
18098 | to fixed point, shifted left or right depending on the value and sign of | |
18099 | @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET}. If | |
18100 | @code{GL_MAP_STENCIL} is @code{GL_TRUE}, indices are replaced by their | |
18101 | mappings in the table @code{GL_PIXEL_MAP_S_TO_S}. | |
18102 | ||
18103 | @item @code{GL_DEPTH_COMPONENT} | |
18104 | Depth values are read from the depth buffer. Each component is converted | |
18105 | to floating point such that the minimum depth value maps to 0 and the | |
18106 | maximum value maps to 1. Each component is then multiplied by | |
18107 | @code{GL_DEPTH_SCALE}, added to @code{GL_DEPTH_BIAS}, and finally | |
3c9b6116 | 18108 | clamped to the range @r{[0,1]}. |
8925f36f AW |
18109 | |
18110 | @item @code{GL_RED} | |
18111 | @item @code{GL_GREEN} | |
18112 | @item @code{GL_BLUE} | |
18113 | @item @code{GL_ALPHA} | |
18114 | @item @code{GL_RGB} | |
18115 | @item @code{GL_BGR} | |
18116 | @item @code{GL_RGBA} | |
18117 | @item @code{GL_BGRA} | |
18118 | @item @code{GL_LUMINANCE} | |
18119 | @item @code{GL_LUMINANCE_ALPHA} | |
18120 | Processing differs depending on whether color buffers store color | |
18121 | indices or RGBA color components. If color indices are stored, they are | |
18122 | read from the color buffer selected by @code{glReadBuffer}. Each index | |
18123 | is converted to fixed point, shifted left or right depending on the | |
18124 | value and sign of @code{GL_INDEX_SHIFT}, and added to | |
18125 | @code{GL_INDEX_OFFSET}. Indices are then replaced by the red, green, | |
18126 | blue, and alpha values obtained by indexing the tables | |
18127 | @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G}, | |
18128 | @code{GL_PIXEL_MAP_I_TO_B}, and @code{GL_PIXEL_MAP_I_TO_A}. Each table | |
3c9b6116 AW |
18129 | must be of size @r{2^@var{n}}, but @r{@var{n}} may be different for |
18130 | different tables. Before an index is used to look up a value in a table | |
18131 | of size @r{2^@var{n}}, it must be masked against @r{2^@var{n}-1}. | |
8925f36f AW |
18132 | |
18133 | If RGBA color components are stored in the color buffers, they are read | |
18134 | from the color buffer selected by @code{glReadBuffer}. Each color | |
18135 | component is converted to floating point such that zero intensity maps | |
18136 | to 0.0 and full intensity maps to 1.0. Each component is then multiplied | |
18137 | by @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is | |
18138 | RED, GREEN, BLUE, or ALPHA. Finally, if @code{GL_MAP_COLOR} is | |
3c9b6116 AW |
18139 | @code{GL_TRUE}, each component is clamped to the range @r{[0,1]}, scaled |
18140 | to the size of its corresponding table, and is then replaced by its | |
18141 | mapping in the table @code{GL_PIXEL_MAP_c_TO_c}, where @var{c} is R, G, | |
18142 | B, or A. | |
8925f36f AW |
18143 | |
18144 | Unneeded data is then discarded. For example, @code{GL_RED} discards the | |
18145 | green, blue, and alpha components, while @code{GL_RGB} discards only the | |
18146 | alpha component. @code{GL_LUMINANCE} computes a single-component value | |
18147 | as the sum of the red, green, and blue components, and | |
18148 | @code{GL_LUMINANCE_ALPHA} does the same, while keeping alpha as a second | |
3c9b6116 | 18149 | value. The final values are clamped to the range @r{[0,1]}. |
8925f36f AW |
18150 | |
18151 | @end table | |
18152 | ||
18153 | The shift, scale, bias, and lookup factors just described are all | |
18154 | specified by @code{glPixelTransfer}. The lookup table contents | |
18155 | themselves are specified by @code{glPixelMap}. | |
18156 | ||
18157 | Finally, the indices or components are converted to the proper format, | |
18158 | as specified by @var{type}. If @var{format} is @code{GL_COLOR_INDEX} or | |
18159 | @code{GL_STENCIL_INDEX} and @var{type} is not @code{GL_FLOAT}, each | |
18160 | index is masked with the mask value given in the following table. If | |
18161 | @var{type} is @code{GL_FLOAT}, then each integer index is converted to | |
18162 | single-precision floating-point format. | |
18163 | ||
18164 | If @var{format} is @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, | |
18165 | @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, | |
18166 | @code{GL_BGRA}, @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA} and | |
18167 | @var{type} is not @code{GL_FLOAT}, each component is multiplied by the | |
18168 | multiplier shown in the following table. If type is @code{GL_FLOAT}, | |
18169 | then each component is passed as is (or converted to the client's | |
18170 | single-precision floating-point format if it is different from the one | |
18171 | used by the GL). | |
18172 | ||
18173 | ||
18174 | ||
18175 | @table @asis | |
18176 | @item @var{type} | |
18177 | @strong{Index Mask}, @strong{Component Conversion} | |
18178 | ||
18179 | @item @code{GL_UNSIGNED_BYTE} | |
3c9b6116 | 18180 | @r{2^8-1}, @r{(2^8-1,)@var{c}} |
8925f36f AW |
18181 | |
18182 | @item @code{GL_BYTE} | |
3c9b6116 | 18183 | @r{2^7-1}, @r{(2^8-1,)@var{c}-1,/2} |
8925f36f AW |
18184 | |
18185 | @item @code{GL_BITMAP} | |
3c9b6116 | 18186 | @r{1}, @r{1} |
8925f36f AW |
18187 | |
18188 | @item @code{GL_UNSIGNED_SHORT} | |
3c9b6116 | 18189 | @r{2^16-1}, @r{(2^16-1,)@var{c}} |
8925f36f AW |
18190 | |
18191 | @item @code{GL_SHORT} | |
3c9b6116 | 18192 | @r{2^15-1}, @r{(2^16-1,)@var{c}-1,/2} |
8925f36f AW |
18193 | |
18194 | @item @code{GL_UNSIGNED_INT} | |
3c9b6116 | 18195 | @r{2^32-1}, @r{(2^32-1,)@var{c}} |
8925f36f AW |
18196 | |
18197 | @item @code{GL_INT} | |
3c9b6116 | 18198 | @r{2^31-1}, @r{(2^32-1,)@var{c}-1,/2} |
8925f36f AW |
18199 | |
18200 | @item @code{GL_FLOAT} | |
3c9b6116 | 18201 | none , @r{@var{c}} |
8925f36f AW |
18202 | |
18203 | @end table | |
18204 | ||
18205 | Return values are placed in memory as follows. If @var{format} is | |
18206 | @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, | |
18207 | @code{GL_DEPTH_COMPONENT}, @code{GL_RED}, @code{GL_GREEN}, | |
18208 | @code{GL_BLUE}, @code{GL_ALPHA}, or @code{GL_LUMINANCE}, a single value | |
3c9b6116 AW |
18209 | is returned and the data for the @r{@var{i}}th pixel in the |
18210 | @r{@var{j}}th row is placed in location | |
18211 | @r{(@var{j},)@var{width}+@var{i}}. @code{GL_RGB} and @code{GL_BGR} | |
8925f36f AW |
18212 | return three values, @code{GL_RGBA} and @code{GL_BGRA} return four |
18213 | values, and @code{GL_LUMINANCE_ALPHA} returns two values for each pixel, | |
18214 | with all values corresponding to a single pixel occupying contiguous | |
18215 | space in @var{data}. Storage parameters set by @code{glPixelStore}, such | |
18216 | as @code{GL_PACK_LSB_FIRST} and @code{GL_PACK_SWAP_BYTES}, affect the | |
18217 | way that data is written into memory. See @code{glPixelStore} for a | |
18218 | description. | |
18219 | ||
8925f36f AW |
18220 | @code{GL_INVALID_ENUM} is generated if @var{format} or @var{type} is not |
18221 | an accepted value. | |
18222 | ||
18223 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
18224 | and @var{format} is not @code{GL_COLOR_INDEX} or | |
18225 | @code{GL_STENCIL_INDEX}. | |
18226 | ||
18227 | @code{GL_INVALID_VALUE} is generated if either @var{width} or | |
18228 | @var{height} is negative. | |
18229 | ||
18230 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
18231 | @code{GL_COLOR_INDEX} and the color buffers store RGBA color components. | |
18232 | ||
18233 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
18234 | @code{GL_STENCIL_INDEX} and there is no stencil buffer. | |
18235 | ||
18236 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
18237 | @code{GL_DEPTH_COMPONENT} and there is no depth buffer. | |
18238 | ||
18239 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
18240 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
18241 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
18242 | and @var{format} is not @code{GL_RGB}. | |
18243 | ||
18244 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
18245 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
18246 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
18247 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
18248 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
18249 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
18250 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
18251 | ||
18252 | The formats @code{GL_BGR}, and @code{GL_BGRA} and types | |
18253 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
18254 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
18255 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
18256 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
18257 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
18258 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
18259 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} are available only if the GL | |
18260 | version is 1.2 or greater. | |
18261 | ||
18262 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
18263 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
18264 | object's data store is currently mapped. | |
18265 | ||
18266 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
18267 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
18268 | would be packed to the buffer object such that the memory writes | |
18269 | required would exceed the data store size. | |
18270 | ||
18271 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
18272 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{data} | |
18273 | is not evenly divisible into the number of bytes needed to store in | |
18274 | memory a datum indicated by @var{type}. | |
18275 | ||
18276 | @code{GL_INVALID_OPERATION} is generated if @code{glReadPixels} is | |
18277 | executed between the execution of @code{glBegin} and the corresponding | |
18278 | execution of @code{glEnd}. | |
18279 | ||
bb894c9d | 18280 | @end deftypefun |
8925f36f | 18281 | |
ca09631c | 18282 | @deftypefun void glRectf x1 y1 x2 y2 |
bb894c9d | 18283 | @deftypefunx void glRecti x1 y1 x2 y2 |
3c9b6116 AW |
18284 | Draw a rectangle. |
18285 | ||
8925f36f AW |
18286 | @table @asis |
18287 | @item @var{x1} | |
18288 | @itemx @var{y1} | |
18289 | Specify one vertex of a rectangle. | |
18290 | ||
18291 | @item @var{x2} | |
18292 | @itemx @var{y2} | |
18293 | Specify the opposite vertex of the rectangle. | |
18294 | ||
18295 | @end table | |
18296 | ||
8925f36f AW |
18297 | @code{glRect} supports efficient specification of rectangles as two |
18298 | corner points. Each rectangle command takes four arguments, organized | |
3c9b6116 AW |
18299 | either as two consecutive pairs of @r{(@var{x},@var{y})} coordinates or |
18300 | as two pointers to arrays, each containing an @r{(@var{x},@var{y})} | |
18301 | pair. The resulting rectangle is defined in the @r{@var{z}=0} plane. | |
8925f36f AW |
18302 | |
18303 | @code{glRect}(@var{x1}, @var{y1}, @var{x2}, @var{y2}) is exactly | |
18304 | equivalent to the following sequence: Note that if the second vertex is | |
18305 | above and to the right of the first vertex, the rectangle is constructed | |
18306 | with a counterclockwise winding. | |
18307 | ||
18308 | @example | |
18309 | ||
18310 | glBegin(@code{GL_POLYGON}); | |
18311 | glVertex2(@var{x1}, @var{y1}); | |
18312 | glVertex2(@var{x2}, @var{y1}); | |
18313 | glVertex2(@var{x2}, @var{y2}); | |
18314 | glVertex2(@var{x1}, @var{y2}); | |
18315 | glEnd(); | |
18316 | @end example | |
18317 | ||
8925f36f AW |
18318 | @code{GL_INVALID_OPERATION} is generated if @code{glRect} is executed |
18319 | between the execution of @code{glBegin} and the corresponding execution | |
18320 | of @code{glEnd}. | |
18321 | ||
bb894c9d | 18322 | @end deftypefun |
8925f36f | 18323 | |
bb894c9d | 18324 | @deftypefun GLint glRenderMode mode |
3c9b6116 AW |
18325 | Set rasterization mode. |
18326 | ||
8925f36f AW |
18327 | @table @asis |
18328 | @item @var{mode} | |
18329 | Specifies the rasterization mode. Three values are accepted: | |
18330 | @code{GL_RENDER}, @code{GL_SELECT}, and @code{GL_FEEDBACK}. The initial | |
18331 | value is @code{GL_RENDER}. | |
18332 | ||
18333 | @end table | |
18334 | ||
8925f36f AW |
18335 | @code{glRenderMode} sets the rasterization mode. It takes one argument, |
18336 | @var{mode}, which can assume one of three predefined values: | |
18337 | ||
18338 | @table @asis | |
18339 | @item @code{GL_RENDER} | |
18340 | Render mode. Primitives are rasterized, producing pixel fragments, which | |
18341 | are written into the frame buffer. This is the normal mode and also the | |
18342 | default mode. | |
18343 | ||
18344 | @item @code{GL_SELECT} | |
18345 | Selection mode. No pixel fragments are produced, and no change to the | |
18346 | frame buffer contents is made. Instead, a record of the names of | |
18347 | primitives that would have been drawn if the render mode had been | |
18348 | @code{GL_RENDER} is returned in a select buffer, which must be created | |
18349 | (see @code{glSelectBuffer}) before selection mode is entered. | |
18350 | ||
18351 | @item @code{GL_FEEDBACK} | |
18352 | Feedback mode. No pixel fragments are produced, and no change to the | |
18353 | frame buffer contents is made. Instead, the coordinates and attributes | |
18354 | of vertices that would have been drawn if the render mode had been | |
18355 | @code{GL_RENDER} is returned in a feedback buffer, which must be created | |
18356 | (see @code{glFeedbackBuffer}) before feedback mode is entered. | |
18357 | ||
18358 | @end table | |
18359 | ||
18360 | The return value of @code{glRenderMode} is determined by the render mode | |
18361 | at the time @code{glRenderMode} is called, rather than by @var{mode}. | |
18362 | The values returned for the three render modes are as follows: | |
18363 | ||
18364 | @table @asis | |
18365 | @item @code{GL_RENDER} | |
18366 | 0. | |
18367 | ||
18368 | @item @code{GL_SELECT} | |
18369 | The number of hit records transferred to the select buffer. | |
18370 | ||
18371 | @item @code{GL_FEEDBACK} | |
18372 | The number of values (not vertices) transferred to the feedback buffer. | |
18373 | ||
18374 | @end table | |
18375 | ||
18376 | See the @code{glSelectBuffer} and @code{glFeedbackBuffer} reference | |
18377 | pages for more details concerning selection and feedback operation. | |
18378 | ||
8925f36f AW |
18379 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of the |
18380 | three accepted values. | |
18381 | ||
18382 | @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is | |
18383 | called while the render mode is @code{GL_SELECT}, or if | |
18384 | @code{glRenderMode} is called with argument @code{GL_SELECT} before | |
18385 | @code{glSelectBuffer} is called at least once. | |
18386 | ||
18387 | @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is | |
18388 | called while the render mode is @code{GL_FEEDBACK}, or if | |
18389 | @code{glRenderMode} is called with argument @code{GL_FEEDBACK} before | |
18390 | @code{glFeedbackBuffer} is called at least once. | |
18391 | ||
18392 | @code{GL_INVALID_OPERATION} is generated if @code{glRenderMode} is | |
18393 | executed between the execution of @code{glBegin} and the corresponding | |
18394 | execution of @code{glEnd}. | |
18395 | ||
bb894c9d | 18396 | @end deftypefun |
8925f36f | 18397 | |
bb894c9d | 18398 | @deftypefun void glResetHistogram target |
3c9b6116 AW |
18399 | Reset histogram table entries to zero. |
18400 | ||
8925f36f AW |
18401 | @table @asis |
18402 | @item @var{target} | |
18403 | Must be @code{GL_HISTOGRAM}. | |
18404 | ||
18405 | @end table | |
18406 | ||
8925f36f AW |
18407 | @code{glResetHistogram} resets all the elements of the current histogram |
18408 | table to zero. | |
18409 | ||
8925f36f AW |
18410 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
18411 | @code{GL_HISTOGRAM}. | |
18412 | ||
18413 | @code{GL_INVALID_OPERATION} is generated if @code{glResetHistogram} is | |
18414 | executed between the execution of @code{glBegin} and the corresponding | |
18415 | execution of @code{glEnd}. | |
18416 | ||
bb894c9d | 18417 | @end deftypefun |
8925f36f | 18418 | |
bb894c9d | 18419 | @deftypefun void glResetMinmax target |
3c9b6116 AW |
18420 | Reset minmax table entries to initial values. |
18421 | ||
8925f36f AW |
18422 | @table @asis |
18423 | @item @var{target} | |
18424 | Must be @code{GL_MINMAX}. | |
18425 | ||
18426 | @end table | |
18427 | ||
8925f36f AW |
18428 | @code{glResetMinmax} resets the elements of the current minmax table to |
18429 | their initial values: the ``maximum'' element receives the minimum | |
18430 | possible component values, and the ``minimum'' element receives the | |
18431 | maximum possible component values. | |
18432 | ||
8925f36f AW |
18433 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
18434 | @code{GL_MINMAX}. | |
18435 | ||
18436 | @code{GL_INVALID_OPERATION} is generated if @code{glResetMinmax} is | |
18437 | executed between the execution of @code{glBegin} and the corresponding | |
18438 | execution of @code{glEnd}. | |
18439 | ||
bb894c9d | 18440 | @end deftypefun |
8925f36f | 18441 | |
ca09631c | 18442 | @deftypefun void glRotatef angle x y z |
3c9b6116 AW |
18443 | Multiply the current matrix by a rotation matrix. |
18444 | ||
8925f36f AW |
18445 | @table @asis |
18446 | @item @var{angle} | |
18447 | Specifies the angle of rotation, in degrees. | |
18448 | ||
18449 | @item @var{x} | |
18450 | @itemx @var{y} | |
18451 | @itemx @var{z} | |
18452 | Specify the @var{x}, @var{y}, and @var{z} coordinates of a vector, | |
18453 | respectively. | |
18454 | ||
18455 | @end table | |
18456 | ||
8925f36f | 18457 | @code{glRotate} produces a rotation of @var{angle} degrees around the |
3c9b6116 | 18458 | vector @r{(@var{x},@var{y}@var{z})}. The current matrix (see |
8925f36f AW |
18459 | @code{glMatrixMode}) is multiplied by a rotation matrix with the product |
18460 | replacing the current matrix, as if @code{glMultMatrix} were called with | |
18461 | the following matrix as its argument: | |
18462 | ||
3c9b6116 | 18463 | @r{((@var{x}^2(1-@var{c},)+@var{c} |
8925f36f AW |
18464 | @var{x}@var{y}(1-@var{c},)-@var{z}@var{s} |
18465 | @var{x}@var{z}(1-@var{c},)+@var{y}@var{s} 0), | |
18466 | (@var{y}@var{x}(1-@var{c},)+@var{z}@var{s} | |
18467 | @var{y}^2(1-@var{c},)+@var{c} | |
18468 | @var{y}@var{z}(1-@var{c},)-@var{x}@var{s} 0), | |
18469 | (@var{x}@var{z}(1-@var{c},)-@var{y}@var{s} | |
18470 | @var{y}@var{z}(1-@var{c},)+@var{x}@var{s} | |
18471 | @var{z}^2(1-@var{c},)+@var{c} 0), (0 0 0 1),)} | |
18472 | ||
18473 | ||
18474 | ||
3c9b6116 AW |
18475 | Where @r{@var{c}=@var{cos}(@var{angle},)}, |
18476 | @r{@var{s}=@var{sin}(@var{angle},)}, and | |
18477 | @r{∥(@var{x},@var{y}@var{z}),∥=1} (if not, the GL will normalize this | |
8925f36f AW |
18478 | vector). |
18479 | ||
18480 | ||
18481 | ||
18482 | ||
18483 | ||
18484 | If the matrix mode is either @code{GL_MODELVIEW} or | |
18485 | @code{GL_PROJECTION}, all objects drawn after @code{glRotate} is called | |
18486 | are rotated. Use @code{glPushMatrix} and @code{glPopMatrix} to save and | |
18487 | restore the unrotated coordinate system. | |
18488 | ||
8925f36f AW |
18489 | @code{GL_INVALID_OPERATION} is generated if @code{glRotate} is executed |
18490 | between the execution of @code{glBegin} and the corresponding execution | |
18491 | of @code{glEnd}. | |
18492 | ||
bb894c9d | 18493 | @end deftypefun |
8925f36f | 18494 | |
bb894c9d | 18495 | @deftypefun void glSampleCoverage value invert |
3c9b6116 AW |
18496 | Specify multisample coverage parameters. |
18497 | ||
8925f36f AW |
18498 | @table @asis |
18499 | @item @var{value} | |
18500 | Specify a single floating-point sample coverage value. The value is | |
3c9b6116 | 18501 | clamped to the range @r{[0,1]}. The initial value is 1.0. |
8925f36f AW |
18502 | |
18503 | @item @var{invert} | |
18504 | Specify a single boolean value representing if the coverage masks should | |
18505 | be inverted. @code{GL_TRUE} and @code{GL_FALSE} are accepted. The | |
18506 | initial value is @code{GL_FALSE}. | |
18507 | ||
18508 | @end table | |
18509 | ||
8925f36f AW |
18510 | Multisampling samples a pixel multiple times at various |
18511 | implementation-dependent subpixel locations to generate antialiasing | |
18512 | effects. Multisampling transparently antialiases points, lines, | |
18513 | polygons, bitmaps, and images if it is enabled. | |
18514 | ||
18515 | @var{value} is used in constructing a temporary mask used in determining | |
18516 | which samples will be used in resolving the final fragment color. This | |
18517 | mask is bitwise-anded with the coverage mask generated from the | |
18518 | multisampling computation. If the @var{invert} flag is set, the | |
18519 | temporary mask is inverted (all bits flipped) and then the bitwise-and | |
18520 | is computed. | |
18521 | ||
18522 | If an implementation does not have any multisample buffers available, or | |
18523 | multisampling is disabled, rasterization occurs with only a single | |
18524 | sample computing a pixel's final RGB color. | |
18525 | ||
18526 | Provided an implementation supports multisample buffers, and | |
18527 | multisampling is enabled, then a pixel's final color is generated by | |
18528 | combining several samples per pixel. Each sample contains color, depth, | |
18529 | and stencil information, allowing those operations to be performed on | |
18530 | each sample. | |
18531 | ||
8925f36f AW |
18532 | @code{GL_INVALID_OPERATION} is generated if @code{glSampleCoverage} is |
18533 | executed between the execution of @code{glBegin} and the corresponding | |
18534 | execution of @code{glEnd}. | |
18535 | ||
bb894c9d | 18536 | @end deftypefun |
8925f36f | 18537 | |
ca09631c | 18538 | @deftypefun void glScalef x y z |
3c9b6116 AW |
18539 | Multiply the current matrix by a general scaling matrix. |
18540 | ||
8925f36f AW |
18541 | @table @asis |
18542 | @item @var{x} | |
18543 | @itemx @var{y} | |
18544 | @itemx @var{z} | |
18545 | Specify scale factors along the @var{x}, @var{y}, and @var{z} axes, | |
18546 | respectively. | |
18547 | ||
18548 | @end table | |
18549 | ||
8925f36f AW |
18550 | @code{glScale} produces a nonuniform scaling along the @var{x}, @var{y}, |
18551 | and @var{z} axes. The three parameters indicate the desired scale factor | |
18552 | along each of the three axes. | |
18553 | ||
18554 | The current matrix (see @code{glMatrixMode}) is multiplied by this scale | |
18555 | matrix, and the product replaces the current matrix as if | |
18556 | @code{glMultMatrix} were called with the following matrix as its | |
18557 | argument: | |
18558 | ||
3c9b6116 | 18559 | @r{((@var{x} 0 0 0), (0 @var{y} 0 0), (0 0 @var{z} 0), (0 0 0 1),)} |
8925f36f AW |
18560 | |
18561 | If the matrix mode is either @code{GL_MODELVIEW} or | |
18562 | @code{GL_PROJECTION}, all objects drawn after @code{glScale} is called | |
18563 | are scaled. | |
18564 | ||
18565 | Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the | |
18566 | unscaled coordinate system. | |
18567 | ||
8925f36f AW |
18568 | @code{GL_INVALID_OPERATION} is generated if @code{glScale} is executed |
18569 | between the execution of @code{glBegin} and the corresponding execution | |
18570 | of @code{glEnd}. | |
18571 | ||
bb894c9d | 18572 | @end deftypefun |
8925f36f | 18573 | |
bb894c9d | 18574 | @deftypefun void glScissor x y width height |
3c9b6116 AW |
18575 | Define the scissor box. |
18576 | ||
8925f36f AW |
18577 | @table @asis |
18578 | @item @var{x} | |
18579 | @itemx @var{y} | |
18580 | Specify the lower left corner of the scissor box. Initially (0, 0). | |
18581 | ||
18582 | @item @var{width} | |
18583 | @itemx @var{height} | |
18584 | Specify the width and height of the scissor box. When a GL context is | |
18585 | first attached to a window, @var{width} and @var{height} are set to the | |
18586 | dimensions of that window. | |
18587 | ||
18588 | @end table | |
18589 | ||
8925f36f AW |
18590 | @code{glScissor} defines a rectangle, called the scissor box, in window |
18591 | coordinates. The first two arguments, @var{x} and @var{y}, specify the | |
18592 | lower left corner of the box. @var{width} and @var{height} specify the | |
18593 | width and height of the box. | |
18594 | ||
18595 | To enable and disable the scissor test, call @code{glEnable} and | |
18596 | @code{glDisable} with argument @code{GL_SCISSOR_TEST}. The test is | |
18597 | initially disabled. While the test is enabled, only pixels that lie | |
18598 | within the scissor box can be modified by drawing commands. Window | |
18599 | coordinates have integer values at the shared corners of frame buffer | |
18600 | pixels. @code{glScissor(0,0,1,1)} allows modification of only the lower | |
18601 | left pixel in the window, and @code{glScissor(0,0,0,0)} doesn't allow | |
18602 | modification of any pixels in the window. | |
18603 | ||
18604 | When the scissor test is disabled, it is as though the scissor box | |
18605 | includes the entire window. | |
18606 | ||
8925f36f AW |
18607 | @code{GL_INVALID_VALUE} is generated if either @var{width} or |
18608 | @var{height} is negative. | |
18609 | ||
18610 | @code{GL_INVALID_OPERATION} is generated if @code{glScissor} is executed | |
18611 | between the execution of @code{glBegin} and the corresponding execution | |
18612 | of @code{glEnd}. | |
18613 | ||
bb894c9d | 18614 | @end deftypefun |
8925f36f | 18615 | |
bb894c9d | 18616 | @deftypefun void glSecondaryColorPointer size type stride pointer |
3c9b6116 AW |
18617 | Define an array of secondary colors. |
18618 | ||
8925f36f AW |
18619 | @table @asis |
18620 | @item @var{size} | |
18621 | Specifies the number of components per color. Must be 3. | |
18622 | ||
18623 | @item @var{type} | |
18624 | Specifies the data type of each color component in the array. Symbolic | |
18625 | constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, | |
18626 | @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT}, | |
18627 | @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is | |
18628 | @code{GL_FLOAT}. | |
18629 | ||
18630 | @item @var{stride} | |
18631 | Specifies the byte offset between consecutive colors. If @var{stride} is | |
18632 | 0, the colors are understood to be tightly packed in the array. The | |
18633 | initial value is 0. | |
18634 | ||
18635 | @item @var{pointer} | |
18636 | Specifies a pointer to the first component of the first color element in | |
18637 | the array. The initial value is 0. | |
18638 | ||
18639 | @end table | |
18640 | ||
8925f36f AW |
18641 | @code{glSecondaryColorPointer} specifies the location and data format of |
18642 | an array of color components to use when rendering. @var{size} specifies | |
18643 | the number of components per color, and must be 3. @var{type} specifies | |
18644 | the data type of each color component, and @var{stride} specifies the | |
18645 | byte stride from one color to the next, allowing vertices and attributes | |
18646 | to be packed into a single array or stored in separate arrays. | |
18647 | ||
18648 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
18649 | target (see @code{glBindBuffer}) while a secondary color array is | |
18650 | specified, @var{pointer} is treated as a byte offset into the buffer | |
18651 | object's data store. Also, the buffer object binding | |
18652 | (@code{GL_ARRAY_BUFFER_BINDING}) is saved as secondary color vertex | |
18653 | array client-side state | |
18654 | (@code{GL_SECONDARY_COLOR_ARRAY_BUFFER_BINDING}). | |
18655 | ||
18656 | When a secondary color array is specified, @var{size}, @var{type}, | |
18657 | @var{stride}, and @var{pointer} are saved as client-side state, in | |
18658 | addition to the current vertex array buffer object binding. | |
18659 | ||
18660 | To enable and disable the secondary color array, call | |
18661 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
18662 | argument @code{GL_SECONDARY_COLOR_ARRAY}. If enabled, the secondary | |
18663 | color array is used when @code{glArrayElement}, @code{glDrawArrays}, | |
18664 | @code{glMultiDrawArrays}, @code{glDrawElements}, | |
18665 | @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called. | |
18666 | ||
8925f36f AW |
18667 | @code{GL_INVALID_VALUE} is generated if @var{size} is not 3. |
18668 | ||
18669 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted | |
18670 | value. | |
18671 | ||
18672 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
18673 | ||
bb894c9d | 18674 | @end deftypefun |
8925f36f | 18675 | |
bb894c9d | 18676 | @deftypefun void glSecondaryColor3i red green blue |
ca09631c | 18677 | @deftypefunx void glSecondaryColor3f red green blue |
bb894c9d | 18678 | @deftypefunx void glSecondaryColor3ui red green blue |
3c9b6116 AW |
18679 | Set the current secondary color. |
18680 | ||
8925f36f AW |
18681 | @table @asis |
18682 | @item @var{red} | |
18683 | @itemx @var{green} | |
18684 | @itemx @var{blue} | |
18685 | Specify new red, green, and blue values for the current secondary color. | |
18686 | ||
18687 | @end table | |
18688 | ||
8925f36f AW |
18689 | The GL stores both a primary four-valued RGBA color and a secondary |
18690 | four-valued RGBA color (where alpha is always set to 0.0) that is | |
18691 | associated with every vertex. | |
18692 | ||
18693 | The secondary color is interpolated and applied to each fragment during | |
18694 | rasterization when @code{GL_COLOR_SUM} is enabled. When lighting is | |
18695 | enabled, and @code{GL_SEPARATE_SPECULAR_COLOR} is specified, the value | |
18696 | of the secondary color is assigned the value computed from the specular | |
18697 | term of the lighting computation. Both the primary and secondary current | |
18698 | colors are applied to each fragment, regardless of the state of | |
18699 | @code{GL_COLOR_SUM}, under such conditions. When | |
18700 | @code{GL_SEPARATE_SPECULAR_COLOR} is specified, the value returned from | |
18701 | querying the current secondary color is undefined. | |
18702 | ||
18703 | @code{glSecondaryColor3b}, @code{glSecondaryColor3s}, and | |
18704 | @code{glSecondaryColor3i} take three signed byte, short, or long | |
18705 | integers as arguments. When @strong{v} is appended to the name, the | |
18706 | color commands can take a pointer to an array of such values. | |
18707 | ||
18708 | Color values are stored in floating-point format, with unspecified | |
18709 | mantissa and exponent sizes. Unsigned integer color components, when | |
18710 | specified, are linearly mapped to floating-point values such that the | |
18711 | largest representable value maps to 1.0 (full intensity), and 0 maps to | |
18712 | 0.0 (zero intensity). Signed integer color components, when specified, | |
18713 | are linearly mapped to floating-point values such that the most positive | |
18714 | representable value maps to 1.0, and the most negative representable | |
3c9b6116 | 18715 | value maps to @r{-1.0}. (Note that this mapping does not convert 0 |
8925f36f AW |
18716 | precisely to 0.0). Floating-point values are mapped directly. |
18717 | ||
18718 | Neither floating-point nor signed integer values are clamped to the | |
3c9b6116 | 18719 | range @r{[0,1]} before the current color is updated. However, color |
8925f36f AW |
18720 | components are clamped to this range before they are interpolated or |
18721 | written into a color buffer. | |
18722 | ||
bb894c9d | 18723 | @end deftypefun |
8925f36f | 18724 | |
bb894c9d | 18725 | @deftypefun void glSelectBuffer size buffer |
3c9b6116 AW |
18726 | Establish a buffer for selection mode values. |
18727 | ||
8925f36f AW |
18728 | @table @asis |
18729 | @item @var{size} | |
18730 | Specifies the size of @var{buffer}. | |
18731 | ||
18732 | @item @var{buffer} | |
18733 | Returns the selection data. | |
18734 | ||
18735 | @end table | |
18736 | ||
8925f36f AW |
18737 | @code{glSelectBuffer} has two arguments: @var{buffer} is a pointer to an |
18738 | array of unsigned integers, and @var{size} indicates the size of the | |
18739 | array. @var{buffer} returns values from the name stack (see | |
18740 | @code{glInitNames}, @code{glLoadName}, @code{glPushName}) when the | |
18741 | rendering mode is @code{GL_SELECT} (see @code{glRenderMode}). | |
18742 | @code{glSelectBuffer} must be issued before selection mode is enabled, | |
18743 | and it must not be issued while the rendering mode is @code{GL_SELECT}. | |
18744 | ||
18745 | A programmer can use selection to determine which primitives are drawn | |
18746 | into some region of a window. The region is defined by the current | |
18747 | modelview and perspective matrices. | |
18748 | ||
18749 | In selection mode, no pixel fragments are produced from rasterization. | |
18750 | Instead, if a primitive or a raster position intersects the clipping | |
18751 | volume defined by the viewing frustum and the user-defined clipping | |
18752 | planes, this primitive causes a selection hit. (With polygons, no hit | |
18753 | occurs if the polygon is culled.) When a change is made to the name | |
18754 | stack, or when @code{glRenderMode} is called, a hit record is copied to | |
18755 | @var{buffer} if any hits have occurred since the last such event (name | |
18756 | stack change or @code{glRenderMode} call). The hit record consists of | |
18757 | the number of names in the name stack at the time of the event, followed | |
18758 | by the minimum and maximum depth values of all vertices that hit since | |
18759 | the previous event, followed by the name stack contents, bottom name | |
18760 | first. | |
18761 | ||
18762 | Depth values (which are in the range [0,1]) are multiplied by | |
3c9b6116 | 18763 | @r{2^32-1}, before being placed in the hit record. |
8925f36f AW |
18764 | |
18765 | An internal index into @var{buffer} is reset to 0 whenever selection | |
18766 | mode is entered. Each time a hit record is copied into @var{buffer}, the | |
18767 | index is incremented to point to the cell just past the end of the block | |
18768 | of names\(emthat is, to the next available cell If the hit record is | |
18769 | larger than the number of remaining locations in @var{buffer}, as much | |
18770 | data as can fit is copied, and the overflow flag is set. If the name | |
18771 | stack is empty when a hit record is copied, that record consists of 0 | |
18772 | followed by the minimum and maximum depth values. | |
18773 | ||
18774 | To exit selection mode, call @code{glRenderMode} with an argument other | |
18775 | than @code{GL_SELECT}. Whenever @code{glRenderMode} is called while the | |
18776 | render mode is @code{GL_SELECT}, it returns the number of hit records | |
18777 | copied to @var{buffer}, resets the overflow flag and the selection | |
18778 | buffer pointer, and initializes the name stack to be empty. If the | |
18779 | overflow bit was set when @code{glRenderMode} was called, a negative hit | |
18780 | record count is returned. | |
18781 | ||
8925f36f AW |
18782 | @code{GL_INVALID_VALUE} is generated if @var{size} is negative. |
18783 | ||
18784 | @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is | |
18785 | called while the render mode is @code{GL_SELECT}, or if | |
18786 | @code{glRenderMode} is called with argument @code{GL_SELECT} before | |
18787 | @code{glSelectBuffer} is called at least once. | |
18788 | ||
18789 | @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is | |
18790 | executed between the execution of @code{glBegin} and the corresponding | |
18791 | execution of @code{glEnd}. | |
18792 | ||
bb894c9d | 18793 | @end deftypefun |
8925f36f | 18794 | |
bb894c9d | 18795 | @deftypefun void glSeparableFilter2D target internalformat width height format type row column |
3c9b6116 AW |
18796 | Define a separable two-dimensional convolution filter. |
18797 | ||
8925f36f AW |
18798 | @table @asis |
18799 | @item @var{target} | |
18800 | Must be @code{GL_SEPARABLE_2D}. | |
18801 | ||
18802 | @item @var{internalformat} | |
18803 | The internal format of the convolution filter kernel. The allowable | |
18804 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, | |
18805 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
18806 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
18807 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
18808 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
18809 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
18810 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
18811 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
18812 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
18813 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
18814 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
18815 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
18816 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
18817 | ||
18818 | @item @var{width} | |
18819 | The number of elements in the pixel array referenced by @var{row}. (This | |
18820 | is the width of the separable filter kernel.) | |
18821 | ||
18822 | @item @var{height} | |
18823 | The number of elements in the pixel array referenced by @var{column}. | |
18824 | (This is the height of the separable filter kernel.) | |
18825 | ||
18826 | @item @var{format} | |
18827 | The format of the pixel data in @var{row} and @var{column}. The | |
18828 | allowable values are @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, | |
18829 | @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, | |
18830 | @code{GL_BGRA}, @code{GL_INTENSITY}, @code{GL_LUMINANCE}, and | |
18831 | @code{GL_LUMINANCE_ALPHA}. | |
18832 | ||
18833 | @item @var{type} | |
18834 | The type of the pixel data in @var{row} and @var{column}. Symbolic | |
18835 | constants @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
18836 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
18837 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
18838 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
18839 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
18840 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
18841 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
18842 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
18843 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
18844 | ||
18845 | @item @var{row} | |
18846 | Pointer to a one-dimensional array of pixel data that is processed to | |
18847 | build the row filter kernel. | |
18848 | ||
18849 | @item @var{column} | |
18850 | Pointer to a one-dimensional array of pixel data that is processed to | |
18851 | build the column filter kernel. | |
18852 | ||
18853 | @end table | |
18854 | ||
8925f36f AW |
18855 | @code{glSeparableFilter2D} builds a two-dimensional separable |
18856 | convolution filter kernel from two arrays of pixels. | |
18857 | ||
18858 | The pixel arrays specified by (@var{width}, @var{format}, @var{type}, | |
18859 | @var{row}) and (@var{height}, @var{format}, @var{type}, @var{column}) | |
18860 | are processed just as if they had been passed to @code{glDrawPixels}, | |
18861 | but processing stops after the final expansion to RGBA is completed. | |
18862 | ||
18863 | If a non-zero named buffer object is bound to the | |
18864 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
18865 | convolution filter is specified, @var{row} and @var{column} are treated | |
18866 | as byte offsets into the buffer object's data store. | |
18867 | ||
18868 | Next, the R, G, B, and A components of all pixels in both arrays are | |
18869 | scaled by the four separable 2D @code{GL_CONVOLUTION_FILTER_SCALE} | |
18870 | parameters and biased by the four separable 2D | |
18871 | @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias | |
18872 | parameters are set by @code{glConvolutionParameter} using the | |
18873 | @code{GL_SEPARABLE_2D} target and the names | |
18874 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
18875 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors | |
18876 | of four values that are applied to red, green, blue, and alpha, in that | |
18877 | order.) The R, G, B, and A values are not clamped to [0,1] at any time | |
18878 | during this process. | |
18879 | ||
18880 | Each pixel is then converted to the internal format specified by | |
18881 | @var{internalformat}. This conversion simply maps the component values | |
18882 | of the pixel (R, G, B, and A) to the values included in the internal | |
18883 | format (red, green, blue, alpha, luminance, and intensity). The mapping | |
18884 | is as follows: | |
18885 | ||
18886 | @table @asis | |
18887 | @item @strong{Internal Format} | |
18888 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
18889 | @strong{Luminance}, @strong{Intensity} | |
18890 | ||
18891 | @item @code{GL_LUMINANCE} | |
18892 | , , , , R , | |
18893 | ||
18894 | @item @code{GL_LUMINANCE_ALPHA} | |
18895 | , , , A , R , | |
18896 | ||
18897 | @item @code{GL_INTENSITY} | |
18898 | , , , , , R | |
18899 | ||
18900 | @item @code{GL_RGB} | |
18901 | R , G , B , , , | |
18902 | ||
18903 | @item @code{GL_RGBA} | |
18904 | R , G , B , A , , | |
18905 | ||
18906 | @end table | |
18907 | ||
18908 | The red, green, blue, alpha, luminance, and/or intensity components of | |
18909 | the resulting pixels are stored in floating-point rather than integer | |
18910 | format. They form two one-dimensional filter kernel images. The row | |
18911 | image is indexed by coordinate @var{i} starting at zero and increasing | |
18912 | from left to right. Each location in the row image is derived from | |
18913 | element @var{i} of @var{row}. The column image is indexed by coordinate | |
18914 | @var{j} starting at zero and increasing from bottom to top. Each | |
18915 | location in the column image is derived from element @var{j} of | |
18916 | @var{column}. | |
18917 | ||
18918 | Note that after a convolution is performed, the resulting color | |
18919 | components are also scaled by their corresponding | |
18920 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
18921 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
18922 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
18923 | and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}. | |
18924 | ||
8925f36f AW |
18925 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
18926 | @code{GL_SEPARABLE_2D}. | |
18927 | ||
18928 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
18929 | of the allowable values. | |
18930 | ||
18931 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
18932 | allowable values. | |
18933 | ||
18934 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
18935 | allowable values. | |
18936 | ||
18937 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
18938 | greater than the maximum supported value. This value may be queried with | |
18939 | @code{glGetConvolutionParameter} using target @code{GL_SEPARABLE_2D} and | |
18940 | name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
18941 | ||
18942 | @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero | |
18943 | or greater than the maximum supported value. This value may be queried | |
18944 | with @code{glGetConvolutionParameter} using target | |
18945 | @code{GL_SEPARABLE_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}. | |
18946 | ||
18947 | @code{GL_INVALID_OPERATION} is generated if @var{height} is one of | |
18948 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
18949 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
18950 | and @var{format} is not @code{GL_RGB}. | |
18951 | ||
18952 | @code{GL_INVALID_OPERATION} is generated if @var{height} is one of | |
18953 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
18954 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
18955 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
18956 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
18957 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
18958 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
18959 | ||
18960 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
18961 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
18962 | object's data store is currently mapped. | |
18963 | ||
18964 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
18965 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
18966 | would be unpacked from the buffer object such that the memory reads | |
18967 | required would exceed the data store size. | |
18968 | ||
18969 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
18970 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{row} | |
18971 | or @var{column} is not evenly divisible into the number of bytes needed | |
18972 | to store in memory a datum indicated by @var{type}. | |
18973 | ||
18974 | @code{GL_INVALID_OPERATION} is generated if @code{glSeparableFilter2D} | |
18975 | is executed between the execution of @code{glBegin} and the | |
18976 | corresponding execution of @code{glEnd}. | |
18977 | ||
bb894c9d | 18978 | @end deftypefun |
8925f36f | 18979 | |
bb894c9d | 18980 | @deftypefun void glShadeModel mode |
3c9b6116 AW |
18981 | Select flat or smooth shading. |
18982 | ||
8925f36f AW |
18983 | @table @asis |
18984 | @item @var{mode} | |
18985 | Specifies a symbolic value representing a shading technique. Accepted | |
18986 | values are @code{GL_FLAT} and @code{GL_SMOOTH}. The initial value is | |
18987 | @code{GL_SMOOTH}. | |
18988 | ||
18989 | @end table | |
18990 | ||
8925f36f AW |
18991 | GL primitives can have either flat or smooth shading. Smooth shading, |
18992 | the default, causes the computed colors of vertices to be interpolated | |
18993 | as the primitive is rasterized, typically assigning different colors to | |
18994 | each resulting pixel fragment. Flat shading selects the computed color | |
18995 | of just one vertex and assigns it to all the pixel fragments generated | |
18996 | by rasterizing a single primitive. In either case, the computed color of | |
18997 | a vertex is the result of lighting if lighting is enabled, or it is the | |
18998 | current color at the time the vertex was specified if lighting is | |
18999 | disabled. | |
19000 | ||
19001 | Flat and smooth shading are indistinguishable for points. Starting when | |
19002 | @code{glBegin} is issued and counting vertices and primitives from 1, | |
3c9b6116 AW |
19003 | the GL gives each flat-shaded line segment @r{@var{i}} the computed |
19004 | color of vertex @r{@var{i}+1}, its second vertex. Counting similarly | |
8925f36f AW |
19005 | from 1, the GL gives each flat-shaded polygon the computed color of the |
19006 | vertex listed in the following table. This is the last vertex to specify | |
19007 | the polygon in all cases except single polygons, where the first vertex | |
19008 | specifies the flat-shaded color. | |
19009 | ||
19010 | ||
19011 | ||
19012 | @table @asis | |
19013 | @item @strong{ | |
3c9b6116 | 19014 | Primitive Type of Polygon @r{@var{i}}} |
8925f36f AW |
19015 | @strong{Vertex} |
19016 | ||
19017 | @item | |
19018 | Single polygon | |
3c9b6116 | 19019 | (@r{@var{i}==1}) |
8925f36f AW |
19020 | 1 |
19021 | ||
19022 | @item | |
19023 | Triangle strip | |
3c9b6116 | 19024 | @r{@var{i}+2} |
8925f36f AW |
19025 | |
19026 | @item | |
19027 | Triangle fan | |
3c9b6116 | 19028 | @r{@var{i}+2} |
8925f36f AW |
19029 | |
19030 | @item | |
19031 | Independent triangle | |
3c9b6116 | 19032 | @r{3@var{i}} |
8925f36f AW |
19033 | |
19034 | @item | |
19035 | Quad strip | |
3c9b6116 | 19036 | @r{2@var{i}+2} |
8925f36f AW |
19037 | |
19038 | @item | |
19039 | Independent quad | |
3c9b6116 | 19040 | @r{4@var{i}} |
8925f36f AW |
19041 | |
19042 | @end table | |
19043 | ||
19044 | Flat and smooth shading are specified by @code{glShadeModel} with | |
19045 | @var{mode} set to @code{GL_FLAT} and @code{GL_SMOOTH}, respectively. | |
19046 | ||
8925f36f AW |
19047 | @code{GL_INVALID_ENUM} is generated if @var{mode} is any value other |
19048 | than @code{GL_FLAT} or @code{GL_SMOOTH}. | |
19049 | ||
19050 | @code{GL_INVALID_OPERATION} is generated if @code{glShadeModel} is | |
19051 | executed between the execution of @code{glBegin} and the corresponding | |
19052 | execution of @code{glEnd}. | |
19053 | ||
bb894c9d | 19054 | @end deftypefun |
8925f36f | 19055 | |
bb894c9d | 19056 | @deftypefun void glShaderSource shader count string length |
3c9b6116 AW |
19057 | Replaces the source code in a shader object. |
19058 | ||
8925f36f AW |
19059 | @table @asis |
19060 | @item @var{shader} | |
19061 | Specifies the handle of the shader object whose source code is to be | |
19062 | replaced. | |
19063 | ||
19064 | @item @var{count} | |
19065 | Specifies the number of elements in the @var{string} and @var{length} | |
19066 | arrays. | |
19067 | ||
19068 | @item @var{string} | |
19069 | Specifies an array of pointers to strings containing the source code to | |
19070 | be loaded into the shader. | |
19071 | ||
19072 | @item @var{length} | |
19073 | Specifies an array of string lengths. | |
19074 | ||
19075 | @end table | |
19076 | ||
8925f36f AW |
19077 | @code{glShaderSource} sets the source code in @var{shader} to the source |
19078 | code in the array of strings specified by @var{string}. Any source code | |
19079 | previously stored in the shader object is completely replaced. The | |
19080 | number of strings in the array is specified by @var{count}. If | |
19081 | @var{length} is @code{NULL}, each string is assumed to be null | |
19082 | terminated. If @var{length} is a value other than @code{NULL}, it points | |
19083 | to an array containing a string length for each of the corresponding | |
19084 | elements of @var{string}. Each element in the @var{length} array may | |
19085 | contain the length of the corresponding string (the null character is | |
19086 | not counted as part of the string length) or a value less than 0 to | |
19087 | indicate that the string is null terminated. The source code strings are | |
19088 | not scanned or parsed at this time; they are simply copied into the | |
19089 | specified shader object. | |
19090 | ||
8925f36f AW |
19091 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
19092 | generated by OpenGL. | |
19093 | ||
19094 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
19095 | object. | |
19096 | ||
19097 | @code{GL_INVALID_VALUE} is generated if @var{count} is less than 0. | |
19098 | ||
19099 | @code{GL_INVALID_OPERATION} is generated if @code{glShaderSource} is | |
19100 | executed between the execution of @code{glBegin} and the corresponding | |
19101 | execution of @code{glEnd}. | |
19102 | ||
bb894c9d | 19103 | @end deftypefun |
8925f36f | 19104 | |
bb894c9d | 19105 | @deftypefun void glStencilFuncSeparate face func ref mask |
3c9b6116 AW |
19106 | Set front and/or back function and reference value for stencil testing. |
19107 | ||
8925f36f AW |
19108 | @table @asis |
19109 | @item @var{face} | |
19110 | Specifies whether front and/or back stencil state is updated. Three | |
19111 | symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and | |
19112 | @code{GL_FRONT_AND_BACK}. | |
19113 | ||
19114 | @item @var{func} | |
19115 | Specifies the test function. Eight symbolic constants are valid: | |
19116 | @code{GL_NEVER}, @code{GL_LESS}, @code{GL_LEQUAL}, @code{GL_GREATER}, | |
19117 | @code{GL_GEQUAL}, @code{GL_EQUAL}, @code{GL_NOTEQUAL}, and | |
19118 | @code{GL_ALWAYS}. The initial value is @code{GL_ALWAYS}. | |
19119 | ||
19120 | @item @var{ref} | |
19121 | Specifies the reference value for the stencil test. @var{ref} is clamped | |
3c9b6116 AW |
19122 | to the range @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of |
19123 | bitplanes in the stencil buffer. The initial value is 0. | |
8925f36f AW |
19124 | |
19125 | @item @var{mask} | |
19126 | Specifies a mask that is ANDed with both the reference value and the | |
19127 | stored stencil value when the test is done. The initial value is all | |
19128 | 1's. | |
19129 | ||
19130 | @end table | |
19131 | ||
8925f36f AW |
19132 | Stenciling, like depth-buffering, enables and disables drawing on a |
19133 | per-pixel basis. You draw into the stencil planes using GL drawing | |
19134 | primitives, then render geometry and images, using the stencil planes to | |
19135 | mask out portions of the screen. Stenciling is typically used in | |
19136 | multipass rendering algorithms to achieve special effects, such as | |
19137 | decals, outlining, and constructive solid geometry rendering. | |
19138 | ||
19139 | The stencil test conditionally eliminates a pixel based on the outcome | |
19140 | of a comparison between the reference value and the value in the stencil | |
19141 | buffer. To enable and disable the test, call @code{glEnable} and | |
19142 | @code{glDisable} with argument @code{GL_STENCIL_TEST}. To specify | |
19143 | actions based on the outcome of the stencil test, call | |
19144 | @code{glStencilOp} or @code{glStencilOpSeparate}. | |
19145 | ||
19146 | There can be two separate sets of @var{func}, @var{ref}, and @var{mask} | |
19147 | parameters; one affects back-facing polygons, and the other affects | |
19148 | front-facing polygons as well as other non-polygon primitives. | |
19149 | @code{glStencilFunc} sets both front and back stencil state to the same | |
19150 | values, as if @code{glStencilFuncSeparate} were called with @var{face} | |
19151 | set to @code{GL_FRONT_AND_BACK}. | |
19152 | ||
19153 | @var{func} is a symbolic constant that determines the stencil comparison | |
19154 | function. It accepts one of eight values, shown in the following list. | |
19155 | @var{ref} is an integer reference value that is used in the stencil | |
3c9b6116 AW |
19156 | comparison. It is clamped to the range @r{[0,2^@var{n}-1]}, where |
19157 | @r{@var{n}} is the number of bitplanes in the stencil buffer. @var{mask} | |
19158 | is bitwise ANDed with both the reference value and the stored stencil | |
19159 | value, with the ANDed values participating in the comparison. | |
8925f36f AW |
19160 | |
19161 | If @var{stencil} represents the value stored in the corresponding | |
19162 | stencil buffer location, the following list shows the effect of each | |
19163 | comparison function that can be specified by @var{func}. Only if the | |
19164 | comparison succeeds is the pixel passed through to the next stage in the | |
19165 | rasterization process (see @code{glStencilOp}). All tests treat | |
19166 | @var{stencil} values as unsigned integers in the range | |
3c9b6116 AW |
19167 | @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of bitplanes in the |
19168 | stencil buffer. | |
8925f36f AW |
19169 | |
19170 | The following values are accepted by @var{func}: | |
19171 | ||
19172 | @table @asis | |
19173 | @item @code{GL_NEVER} | |
19174 | Always fails. | |
19175 | ||
19176 | @item @code{GL_LESS} | |
19177 | Passes if ( @var{ref} & @var{mask} ) < ( @var{stencil} & @var{mask} ). | |
19178 | ||
19179 | @item @code{GL_LEQUAL} | |
19180 | Passes if ( @var{ref} & @var{mask} ) <= ( @var{stencil} & @var{mask} ). | |
19181 | ||
19182 | @item @code{GL_GREATER} | |
19183 | Passes if ( @var{ref} & @var{mask} ) > ( @var{stencil} & @var{mask} ). | |
19184 | ||
19185 | @item @code{GL_GEQUAL} | |
19186 | Passes if ( @var{ref} & @var{mask} ) >= ( @var{stencil} & @var{mask} ). | |
19187 | ||
19188 | @item @code{GL_EQUAL} | |
19189 | Passes if ( @var{ref} & @var{mask} ) = ( @var{stencil} & @var{mask} ). | |
19190 | ||
19191 | @item @code{GL_NOTEQUAL} | |
19192 | Passes if ( @var{ref} & @var{mask} ) != ( @var{stencil} & @var{mask} ). | |
19193 | ||
19194 | @item @code{GL_ALWAYS} | |
19195 | Always passes. | |
19196 | ||
19197 | @end table | |
19198 | ||
8925f36f AW |
19199 | @code{GL_INVALID_ENUM} is generated if @var{func} is not one of the |
19200 | eight accepted values. | |
19201 | ||
19202 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilFuncSeparate} | |
19203 | is executed between the execution of @code{glBegin} and the | |
19204 | corresponding execution of @code{glEnd}. | |
19205 | ||
bb894c9d | 19206 | @end deftypefun |
8925f36f | 19207 | |
bb894c9d | 19208 | @deftypefun void glStencilFunc func ref mask |
3c9b6116 AW |
19209 | Set front and back function and reference value for stencil testing. |
19210 | ||
8925f36f AW |
19211 | @table @asis |
19212 | @item @var{func} | |
19213 | Specifies the test function. Eight symbolic constants are valid: | |
19214 | @code{GL_NEVER}, @code{GL_LESS}, @code{GL_LEQUAL}, @code{GL_GREATER}, | |
19215 | @code{GL_GEQUAL}, @code{GL_EQUAL}, @code{GL_NOTEQUAL}, and | |
19216 | @code{GL_ALWAYS}. The initial value is @code{GL_ALWAYS}. | |
19217 | ||
19218 | @item @var{ref} | |
19219 | Specifies the reference value for the stencil test. @var{ref} is clamped | |
3c9b6116 AW |
19220 | to the range @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of |
19221 | bitplanes in the stencil buffer. The initial value is 0. | |
8925f36f AW |
19222 | |
19223 | @item @var{mask} | |
19224 | Specifies a mask that is ANDed with both the reference value and the | |
19225 | stored stencil value when the test is done. The initial value is all | |
19226 | 1's. | |
19227 | ||
19228 | @end table | |
19229 | ||
8925f36f AW |
19230 | Stenciling, like depth-buffering, enables and disables drawing on a |
19231 | per-pixel basis. Stencil planes are first drawn into using GL drawing | |
19232 | primitives, then geometry and images are rendered using the stencil | |
19233 | planes to mask out portions of the screen. Stenciling is typically used | |
19234 | in multipass rendering algorithms to achieve special effects, such as | |
19235 | decals, outlining, and constructive solid geometry rendering. | |
19236 | ||
19237 | The stencil test conditionally eliminates a pixel based on the outcome | |
19238 | of a comparison between the reference value and the value in the stencil | |
19239 | buffer. To enable and disable the test, call @code{glEnable} and | |
19240 | @code{glDisable} with argument @code{GL_STENCIL_TEST}. To specify | |
19241 | actions based on the outcome of the stencil test, call | |
19242 | @code{glStencilOp} or @code{glStencilOpSeparate}. | |
19243 | ||
19244 | There can be two separate sets of @var{func}, @var{ref}, and @var{mask} | |
19245 | parameters; one affects back-facing polygons, and the other affects | |
19246 | front-facing polygons as well as other non-polygon primitives. | |
19247 | @code{glStencilFunc} sets both front and back stencil state to the same | |
19248 | values. Use @code{glStencilFuncSeparate} to set front and back stencil | |
19249 | state to different values. | |
19250 | ||
19251 | @var{func} is a symbolic constant that determines the stencil comparison | |
19252 | function. It accepts one of eight values, shown in the following list. | |
19253 | @var{ref} is an integer reference value that is used in the stencil | |
3c9b6116 AW |
19254 | comparison. It is clamped to the range @r{[0,2^@var{n}-1]}, where |
19255 | @r{@var{n}} is the number of bitplanes in the stencil buffer. @var{mask} | |
19256 | is bitwise ANDed with both the reference value and the stored stencil | |
19257 | value, with the ANDed values participating in the comparison. | |
8925f36f AW |
19258 | |
19259 | If @var{stencil} represents the value stored in the corresponding | |
19260 | stencil buffer location, the following list shows the effect of each | |
19261 | comparison function that can be specified by @var{func}. Only if the | |
19262 | comparison succeeds is the pixel passed through to the next stage in the | |
19263 | rasterization process (see @code{glStencilOp}). All tests treat | |
19264 | @var{stencil} values as unsigned integers in the range | |
3c9b6116 AW |
19265 | @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of bitplanes in the |
19266 | stencil buffer. | |
8925f36f AW |
19267 | |
19268 | The following values are accepted by @var{func}: | |
19269 | ||
19270 | @table @asis | |
19271 | @item @code{GL_NEVER} | |
19272 | Always fails. | |
19273 | ||
19274 | @item @code{GL_LESS} | |
19275 | Passes if ( @var{ref} & @var{mask} ) < ( @var{stencil} & @var{mask} ). | |
19276 | ||
19277 | @item @code{GL_LEQUAL} | |
19278 | Passes if ( @var{ref} & @var{mask} ) <= ( @var{stencil} & @var{mask} ). | |
19279 | ||
19280 | @item @code{GL_GREATER} | |
19281 | Passes if ( @var{ref} & @var{mask} ) > ( @var{stencil} & @var{mask} ). | |
19282 | ||
19283 | @item @code{GL_GEQUAL} | |
19284 | Passes if ( @var{ref} & @var{mask} ) >= ( @var{stencil} & @var{mask} ). | |
19285 | ||
19286 | @item @code{GL_EQUAL} | |
19287 | Passes if ( @var{ref} & @var{mask} ) = ( @var{stencil} & @var{mask} ). | |
19288 | ||
19289 | @item @code{GL_NOTEQUAL} | |
19290 | Passes if ( @var{ref} & @var{mask} ) != ( @var{stencil} & @var{mask} ). | |
19291 | ||
19292 | @item @code{GL_ALWAYS} | |
19293 | Always passes. | |
19294 | ||
19295 | @end table | |
19296 | ||
8925f36f AW |
19297 | @code{GL_INVALID_ENUM} is generated if @var{func} is not one of the |
19298 | eight accepted values. | |
19299 | ||
19300 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilFunc} is | |
19301 | executed between the execution of @code{glBegin} and the corresponding | |
19302 | execution of @code{glEnd}. | |
19303 | ||
bb894c9d | 19304 | @end deftypefun |
8925f36f | 19305 | |
bb894c9d | 19306 | @deftypefun void glStencilMaskSeparate face mask |
3c9b6116 AW |
19307 | Control the front and/or back writing of individual bits in the stencil |
19308 | planes. | |
19309 | ||
8925f36f AW |
19310 | @table @asis |
19311 | @item @var{face} | |
19312 | Specifies whether the front and/or back stencil writemask is updated. | |
19313 | Three symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and | |
19314 | @code{GL_FRONT_AND_BACK}. | |
19315 | ||
19316 | @item @var{mask} | |
19317 | Specifies a bit mask to enable and disable writing of individual bits in | |
19318 | the stencil planes. Initially, the mask is all 1's. | |
19319 | ||
19320 | @end table | |
19321 | ||
8925f36f | 19322 | @code{glStencilMaskSeparate} controls the writing of individual bits in |
3c9b6116 AW |
19323 | the stencil planes. The least significant @r{@var{n}} bits of |
19324 | @var{mask}, where @r{@var{n}} is the number of bits in the stencil | |
8925f36f AW |
19325 | buffer, specify a mask. Where a 1 appears in the mask, it's possible to |
19326 | write to the corresponding bit in the stencil buffer. Where a 0 appears, | |
19327 | the corresponding bit is write-protected. Initially, all bits are | |
19328 | enabled for writing. | |
19329 | ||
19330 | There can be two separate @var{mask} writemasks; one affects back-facing | |
19331 | polygons, and the other affects front-facing polygons as well as other | |
19332 | non-polygon primitives. @code{glStencilMask} sets both front and back | |
19333 | stencil writemasks to the same values, as if | |
19334 | @code{glStencilMaskSeparate} were called with @var{face} set to | |
19335 | @code{GL_FRONT_AND_BACK}. | |
19336 | ||
8925f36f AW |
19337 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilMaskSeparate} |
19338 | is executed between the execution of @code{glBegin} and the | |
19339 | corresponding execution of @code{glEnd}. | |
19340 | ||
bb894c9d | 19341 | @end deftypefun |
8925f36f | 19342 | |
bb894c9d | 19343 | @deftypefun void glStencilMask mask |
3c9b6116 AW |
19344 | Control the front and back writing of individual bits in the stencil |
19345 | planes. | |
19346 | ||
8925f36f AW |
19347 | @table @asis |
19348 | @item @var{mask} | |
19349 | Specifies a bit mask to enable and disable writing of individual bits in | |
19350 | the stencil planes. Initially, the mask is all 1's. | |
19351 | ||
19352 | @end table | |
19353 | ||
8925f36f | 19354 | @code{glStencilMask} controls the writing of individual bits in the |
3c9b6116 AW |
19355 | stencil planes. The least significant @r{@var{n}} bits of @var{mask}, |
19356 | where @r{@var{n}} is the number of bits in the stencil buffer, specify a | |
19357 | mask. Where a 1 appears in the mask, it's possible to write to the | |
19358 | corresponding bit in the stencil buffer. Where a 0 appears, the | |
8925f36f AW |
19359 | corresponding bit is write-protected. Initially, all bits are enabled |
19360 | for writing. | |
19361 | ||
19362 | There can be two separate @var{mask} writemasks; one affects back-facing | |
19363 | polygons, and the other affects front-facing polygons as well as other | |
19364 | non-polygon primitives. @code{glStencilMask} sets both front and back | |
19365 | stencil writemasks to the same values. Use @code{glStencilMaskSeparate} | |
19366 | to set front and back stencil writemasks to different values. | |
19367 | ||
8925f36f AW |
19368 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilMask} is |
19369 | executed between the execution of @code{glBegin} and the corresponding | |
19370 | execution of @code{glEnd}. | |
19371 | ||
bb894c9d | 19372 | @end deftypefun |
8925f36f | 19373 | |
bb894c9d | 19374 | @deftypefun void glStencilOpSeparate face sfail dpfail dppass |
3c9b6116 AW |
19375 | Set front and/or back stencil test actions. |
19376 | ||
8925f36f AW |
19377 | @table @asis |
19378 | @item @var{face} | |
19379 | Specifies whether front and/or back stencil state is updated. Three | |
19380 | symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and | |
19381 | @code{GL_FRONT_AND_BACK}. | |
19382 | ||
19383 | @item @var{sfail} | |
19384 | Specifies the action to take when the stencil test fails. Eight symbolic | |
19385 | constants are accepted: @code{GL_KEEP}, @code{GL_ZERO}, | |
19386 | @code{GL_REPLACE}, @code{GL_INCR}, @code{GL_INCR_WRAP}, @code{GL_DECR}, | |
19387 | @code{GL_DECR_WRAP}, and @code{GL_INVERT}. The initial value is | |
19388 | @code{GL_KEEP}. | |
19389 | ||
19390 | @item @var{dpfail} | |
19391 | Specifies the stencil action when the stencil test passes, but the depth | |
19392 | test fails. @var{dpfail} accepts the same symbolic constants as | |
19393 | @var{sfail}. The initial value is @code{GL_KEEP}. | |
19394 | ||
19395 | @item @var{dppass} | |
19396 | Specifies the stencil action when both the stencil test and the depth | |
19397 | test pass, or when the stencil test passes and either there is no depth | |
19398 | buffer or depth testing is not enabled. @var{dppass} accepts the same | |
19399 | symbolic constants as @var{sfail}. The initial value is @code{GL_KEEP}. | |
19400 | ||
19401 | @end table | |
19402 | ||
8925f36f AW |
19403 | Stenciling, like depth-buffering, enables and disables drawing on a |
19404 | per-pixel basis. You draw into the stencil planes using GL drawing | |
19405 | primitives, then render geometry and images, using the stencil planes to | |
19406 | mask out portions of the screen. Stenciling is typically used in | |
19407 | multipass rendering algorithms to achieve special effects, such as | |
19408 | decals, outlining, and constructive solid geometry rendering. | |
19409 | ||
19410 | The stencil test conditionally eliminates a pixel based on the outcome | |
19411 | of a comparison between the value in the stencil buffer and a reference | |
19412 | value. To enable and disable the test, call @code{glEnable} and | |
19413 | @code{glDisable} with argument @code{GL_STENCIL_TEST}; to control it, | |
19414 | call @code{glStencilFunc} or @code{glStencilFuncSeparate}. | |
19415 | ||
19416 | There can be two separate sets of @var{sfail}, @var{dpfail}, and | |
19417 | @var{dppass} parameters; one affects back-facing polygons, and the other | |
19418 | affects front-facing polygons as well as other non-polygon primitives. | |
19419 | @code{glStencilOp} sets both front and back stencil state to the same | |
19420 | values, as if @code{glStencilOpSeparate} were called with @var{face} set | |
19421 | to @code{GL_FRONT_AND_BACK}. | |
19422 | ||
19423 | @code{glStencilOpSeparate} takes three arguments that indicate what | |
19424 | happens to the stored stencil value while stenciling is enabled. If the | |
19425 | stencil test fails, no change is made to the pixel's color or depth | |
19426 | buffers, and @var{sfail} specifies what happens to the stencil buffer | |
19427 | contents. The following eight actions are possible. | |
19428 | ||
19429 | @table @asis | |
19430 | @item @code{GL_KEEP} | |
19431 | Keeps the current value. | |
19432 | ||
19433 | @item @code{GL_ZERO} | |
19434 | Sets the stencil buffer value to 0. | |
19435 | ||
19436 | @item @code{GL_REPLACE} | |
19437 | Sets the stencil buffer value to @var{ref}, as specified by | |
19438 | @code{glStencilFunc}. | |
19439 | ||
19440 | @item @code{GL_INCR} | |
19441 | Increments the current stencil buffer value. Clamps to the maximum | |
19442 | representable unsigned value. | |
19443 | ||
19444 | @item @code{GL_INCR_WRAP} | |
19445 | Increments the current stencil buffer value. Wraps stencil buffer value | |
19446 | to zero when incrementing the maximum representable unsigned value. | |
19447 | ||
19448 | @item @code{GL_DECR} | |
19449 | Decrements the current stencil buffer value. Clamps to 0. | |
19450 | ||
19451 | @item @code{GL_DECR_WRAP} | |
19452 | Decrements the current stencil buffer value. Wraps stencil buffer value | |
19453 | to the maximum representable unsigned value when decrementing a stencil | |
19454 | buffer value of zero. | |
19455 | ||
19456 | @item @code{GL_INVERT} | |
19457 | Bitwise inverts the current stencil buffer value. | |
19458 | ||
19459 | @end table | |
19460 | ||
19461 | Stencil buffer values are treated as unsigned integers. When incremented | |
3c9b6116 AW |
19462 | and decremented, values are clamped to 0 and @r{2^@var{n}-1}, where |
19463 | @r{@var{n}} is the value returned by querying @code{GL_STENCIL_BITS}. | |
8925f36f AW |
19464 | |
19465 | The other two arguments to @code{glStencilOpSeparate} specify stencil | |
19466 | buffer actions that depend on whether subsequent depth buffer tests | |
19467 | succeed (@var{dppass}) or fail (@var{dpfail}) (see @code{glDepthFunc}). | |
19468 | The actions are specified using the same eight symbolic constants as | |
19469 | @var{sfail}. Note that @var{dpfail} is ignored when there is no depth | |
19470 | buffer, or when the depth buffer is not enabled. In these cases, | |
19471 | @var{sfail} and @var{dppass} specify stencil action when the stencil | |
19472 | test fails and passes, respectively. | |
19473 | ||
8925f36f AW |
19474 | @code{GL_INVALID_ENUM} is generated if @var{face} is any value other |
19475 | than @code{GL_FRONT}, @code{GL_BACK}, or @code{GL_FRONT_AND_BACK}. | |
19476 | ||
19477 | @code{GL_INVALID_ENUM} is generated if @var{sfail}, @var{dpfail}, or | |
19478 | @var{dppass} is any value other than the eight defined constant values. | |
19479 | ||
19480 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilOpSeparate} | |
19481 | is executed between the execution of @code{glBegin} and the | |
19482 | corresponding execution of @code{glEnd}. | |
19483 | ||
bb894c9d | 19484 | @end deftypefun |
8925f36f | 19485 | |
bb894c9d | 19486 | @deftypefun void glStencilOp sfail dpfail dppass |
3c9b6116 AW |
19487 | Set front and back stencil test actions. |
19488 | ||
8925f36f AW |
19489 | @table @asis |
19490 | @item @var{sfail} | |
19491 | Specifies the action to take when the stencil test fails. Eight symbolic | |
19492 | constants are accepted: @code{GL_KEEP}, @code{GL_ZERO}, | |
19493 | @code{GL_REPLACE}, @code{GL_INCR}, @code{GL_INCR_WRAP}, @code{GL_DECR}, | |
19494 | @code{GL_DECR_WRAP}, and @code{GL_INVERT}. The initial value is | |
19495 | @code{GL_KEEP}. | |
19496 | ||
19497 | @item @var{dpfail} | |
19498 | Specifies the stencil action when the stencil test passes, but the depth | |
19499 | test fails. @var{dpfail} accepts the same symbolic constants as | |
19500 | @var{sfail}. The initial value is @code{GL_KEEP}. | |
19501 | ||
19502 | @item @var{dppass} | |
19503 | Specifies the stencil action when both the stencil test and the depth | |
19504 | test pass, or when the stencil test passes and either there is no depth | |
19505 | buffer or depth testing is not enabled. @var{dppass} accepts the same | |
19506 | symbolic constants as @var{sfail}. The initial value is @code{GL_KEEP}. | |
19507 | ||
19508 | @end table | |
19509 | ||
8925f36f AW |
19510 | Stenciling, like depth-buffering, enables and disables drawing on a |
19511 | per-pixel basis. You draw into the stencil planes using GL drawing | |
19512 | primitives, then render geometry and images, using the stencil planes to | |
19513 | mask out portions of the screen. Stenciling is typically used in | |
19514 | multipass rendering algorithms to achieve special effects, such as | |
19515 | decals, outlining, and constructive solid geometry rendering. | |
19516 | ||
19517 | The stencil test conditionally eliminates a pixel based on the outcome | |
19518 | of a comparison between the value in the stencil buffer and a reference | |
19519 | value. To enable and disable the test, call @code{glEnable} and | |
19520 | @code{glDisable} with argument @code{GL_STENCIL_TEST}; to control it, | |
19521 | call @code{glStencilFunc} or @code{glStencilFuncSeparate}. | |
19522 | ||
19523 | There can be two separate sets of @var{sfail}, @var{dpfail}, and | |
19524 | @var{dppass} parameters; one affects back-facing polygons, and the other | |
19525 | affects front-facing polygons as well as other non-polygon primitives. | |
19526 | @code{glStencilOp} sets both front and back stencil state to the same | |
19527 | values. Use @code{glStencilOpSeparate} to set front and back stencil | |
19528 | state to different values. | |
19529 | ||
19530 | @code{glStencilOp} takes three arguments that indicate what happens to | |
19531 | the stored stencil value while stenciling is enabled. If the stencil | |
19532 | test fails, no change is made to the pixel's color or depth buffers, and | |
19533 | @var{sfail} specifies what happens to the stencil buffer contents. The | |
19534 | following eight actions are possible. | |
19535 | ||
19536 | @table @asis | |
19537 | @item @code{GL_KEEP} | |
19538 | Keeps the current value. | |
19539 | ||
19540 | @item @code{GL_ZERO} | |
19541 | Sets the stencil buffer value to 0. | |
19542 | ||
19543 | @item @code{GL_REPLACE} | |
19544 | Sets the stencil buffer value to @var{ref}, as specified by | |
19545 | @code{glStencilFunc}. | |
19546 | ||
19547 | @item @code{GL_INCR} | |
19548 | Increments the current stencil buffer value. Clamps to the maximum | |
19549 | representable unsigned value. | |
19550 | ||
19551 | @item @code{GL_INCR_WRAP} | |
19552 | Increments the current stencil buffer value. Wraps stencil buffer value | |
19553 | to zero when incrementing the maximum representable unsigned value. | |
19554 | ||
19555 | @item @code{GL_DECR} | |
19556 | Decrements the current stencil buffer value. Clamps to 0. | |
19557 | ||
19558 | @item @code{GL_DECR_WRAP} | |
19559 | Decrements the current stencil buffer value. Wraps stencil buffer value | |
19560 | to the maximum representable unsigned value when decrementing a stencil | |
19561 | buffer value of zero. | |
19562 | ||
19563 | @item @code{GL_INVERT} | |
19564 | Bitwise inverts the current stencil buffer value. | |
19565 | ||
19566 | @end table | |
19567 | ||
19568 | Stencil buffer values are treated as unsigned integers. When incremented | |
3c9b6116 AW |
19569 | and decremented, values are clamped to 0 and @r{2^@var{n}-1}, where |
19570 | @r{@var{n}} is the value returned by querying @code{GL_STENCIL_BITS}. | |
8925f36f AW |
19571 | |
19572 | The other two arguments to @code{glStencilOp} specify stencil buffer | |
19573 | actions that depend on whether subsequent depth buffer tests succeed | |
19574 | (@var{dppass}) or fail (@var{dpfail}) (see @code{glDepthFunc}). The | |
19575 | actions are specified using the same eight symbolic constants as | |
19576 | @var{sfail}. Note that @var{dpfail} is ignored when there is no depth | |
19577 | buffer, or when the depth buffer is not enabled. In these cases, | |
19578 | @var{sfail} and @var{dppass} specify stencil action when the stencil | |
19579 | test fails and passes, respectively. | |
19580 | ||
8925f36f AW |
19581 | @code{GL_INVALID_ENUM} is generated if @var{sfail}, @var{dpfail}, or |
19582 | @var{dppass} is any value other than the eight defined constant values. | |
19583 | ||
19584 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilOp} is | |
19585 | executed between the execution of @code{glBegin} and the corresponding | |
19586 | execution of @code{glEnd}. | |
19587 | ||
bb894c9d | 19588 | @end deftypefun |
8925f36f | 19589 | |
bb894c9d | 19590 | @deftypefun void glTexCoordPointer size type stride pointer |
3c9b6116 AW |
19591 | Define an array of texture coordinates. |
19592 | ||
8925f36f AW |
19593 | @table @asis |
19594 | @item @var{size} | |
19595 | Specifies the number of coordinates per array element. Must be 1, 2, 3, | |
19596 | or 4. The initial value is 4. | |
19597 | ||
19598 | @item @var{type} | |
19599 | Specifies the data type of each texture coordinate. Symbolic constants | |
19600 | @code{GL_SHORT}, @code{GL_INT}, @code{GL_FLOAT}, or @code{GL_DOUBLE} are | |
19601 | accepted. The initial value is @code{GL_FLOAT}. | |
19602 | ||
19603 | @item @var{stride} | |
19604 | Specifies the byte offset between consecutive texture coordinate sets. | |
19605 | If @var{stride} is 0, the array elements are understood to be tightly | |
19606 | packed. The initial value is 0. | |
19607 | ||
19608 | @item @var{pointer} | |
19609 | Specifies a pointer to the first coordinate of the first texture | |
19610 | coordinate set in the array. The initial value is 0. | |
19611 | ||
19612 | @end table | |
19613 | ||
8925f36f AW |
19614 | @code{glTexCoordPointer} specifies the location and data format of an |
19615 | array of texture coordinates to use when rendering. @var{size} specifies | |
19616 | the number of coordinates per texture coordinate set, and must be 1, 2, | |
19617 | 3, or 4. @var{type} specifies the data type of each texture coordinate, | |
19618 | and @var{stride} specifies the byte stride from one texture coordinate | |
19619 | set to the next, allowing vertices and attributes to be packed into a | |
19620 | single array or stored in separate arrays. (Single-array storage may be | |
19621 | more efficient on some implementations; see @code{glInterleavedArrays}.) | |
19622 | ||
19623 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
19624 | target (see @code{glBindBuffer}) while a texture coordinate array is | |
19625 | specified, @var{pointer} is treated as a byte offset into the buffer | |
19626 | object's data store. Also, the buffer object binding | |
19627 | (@code{GL_ARRAY_BUFFER_BINDING}) is saved as texture coordinate vertex | |
19628 | array client-side state (@code{GL_TEXTURE_COORD_ARRAY_BUFFER_BINDING}). | |
19629 | ||
19630 | When a texture coordinate array is specified, @var{size}, @var{type}, | |
19631 | @var{stride}, and @var{pointer} are saved as client-side state, in | |
19632 | addition to the current vertex array buffer object binding. | |
19633 | ||
19634 | To enable and disable a texture coordinate array, call | |
19635 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
19636 | argument @code{GL_TEXTURE_COORD_ARRAY}. If enabled, the texture | |
19637 | coordinate array is used when @code{glArrayElement}, | |
19638 | @code{glDrawArrays}, @code{glMultiDrawArrays}, @code{glDrawElements}, | |
19639 | @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called. | |
19640 | ||
8925f36f AW |
19641 | @code{GL_INVALID_VALUE} is generated if @var{size} is not 1, 2, 3, or 4. |
19642 | ||
19643 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted | |
19644 | value. | |
19645 | ||
19646 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
19647 | ||
bb894c9d | 19648 | @end deftypefun |
8925f36f | 19649 | |
bb894c9d | 19650 | @deftypefun void glTexCoord1i s |
ca09631c | 19651 | @deftypefunx void glTexCoord1f s |
bb894c9d | 19652 | @deftypefunx void glTexCoord2i s t |
ca09631c | 19653 | @deftypefunx void glTexCoord2f s t |
bb894c9d | 19654 | @deftypefunx void glTexCoord3i s t r |
ca09631c | 19655 | @deftypefunx void glTexCoord3f s t r |
bb894c9d | 19656 | @deftypefunx void glTexCoord4i s t r q |
ca09631c | 19657 | @deftypefunx void glTexCoord4f s t r q |
3c9b6116 AW |
19658 | Set the current texture coordinates. |
19659 | ||
8925f36f AW |
19660 | @table @asis |
19661 | @item @var{s} | |
19662 | @itemx @var{t} | |
19663 | @itemx @var{r} | |
19664 | @itemx @var{q} | |
19665 | Specify @var{s}, @var{t}, @var{r}, and @var{q} texture coordinates. Not | |
19666 | all parameters are present in all forms of the command. | |
19667 | ||
19668 | @end table | |
19669 | ||
8925f36f AW |
19670 | @code{glTexCoord} specifies texture coordinates in one, two, three, or |
19671 | four dimensions. @code{glTexCoord1} sets the current texture coordinates | |
3c9b6116 AW |
19672 | to @r{(@var{s},001)}; a call to @code{glTexCoord2} sets them to |
19673 | @r{(@var{s},@var{t}01)}. Similarly, @code{glTexCoord3} specifies the | |
19674 | texture coordinates as @r{(@var{s},@var{t}@var{r}1)}, and | |
8925f36f | 19675 | @code{glTexCoord4} defines all four components explicitly as |
3c9b6116 | 19676 | @r{(@var{s},@var{t}@var{r}@var{q})}. |
8925f36f AW |
19677 | |
19678 | The current texture coordinates are part of the data that is associated | |
19679 | with each vertex and with the current raster position. Initially, the | |
19680 | values for @var{s}, @var{t}, @var{r}, and @var{q} are (0, 0, 0, 1). | |
19681 | ||
19682 | ||
19683 | ||
bb894c9d | 19684 | @end deftypefun |
8925f36f | 19685 | |
bb894c9d AW |
19686 | @deftypefun void glTexEnvf target pname param |
19687 | @deftypefunx void glTexEnvi target pname param | |
3c9b6116 AW |
19688 | Set texture environment parameters. |
19689 | ||
8925f36f AW |
19690 | @table @asis |
19691 | @item @var{target} | |
19692 | Specifies a texture environment. May be @code{GL_TEXTURE_ENV}, | |
19693 | @code{GL_TEXTURE_FILTER_CONTROL} or @code{GL_POINT_SPRITE}. | |
19694 | ||
19695 | @item @var{pname} | |
19696 | Specifies the symbolic name of a single-valued texture environment | |
19697 | parameter. May be either @code{GL_TEXTURE_ENV_MODE}, | |
19698 | @code{GL_TEXTURE_LOD_BIAS}, @code{GL_COMBINE_RGB}, | |
19699 | @code{GL_COMBINE_ALPHA}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, | |
19700 | @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, | |
19701 | @code{GL_SRC2_ALPHA}, @code{GL_OPERAND0_RGB}, @code{GL_OPERAND1_RGB}, | |
19702 | @code{GL_OPERAND2_RGB}, @code{GL_OPERAND0_ALPHA}, | |
19703 | @code{GL_OPERAND1_ALPHA}, @code{GL_OPERAND2_ALPHA}, @code{GL_RGB_SCALE}, | |
19704 | @code{GL_ALPHA_SCALE}, or @code{GL_COORD_REPLACE}. | |
19705 | ||
19706 | @item @var{param} | |
19707 | Specifies a single symbolic constant, one of @code{GL_ADD}, | |
19708 | @code{GL_ADD_SIGNED}, @code{GL_INTERPOLATE}, @code{GL_MODULATE}, | |
19709 | @code{GL_DECAL}, @code{GL_BLEND}, @code{GL_REPLACE}, @code{GL_SUBTRACT}, | |
19710 | @code{GL_COMBINE}, @code{GL_TEXTURE}, @code{GL_CONSTANT}, | |
19711 | @code{GL_PRIMARY_COLOR}, @code{GL_PREVIOUS}, @code{GL_SRC_COLOR}, | |
19712 | @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_SRC_ALPHA}, | |
19713 | @code{GL_ONE_MINUS_SRC_ALPHA}, a single boolean value for the point | |
19714 | sprite texture coordinate replacement, a single floating-point value for | |
19715 | the texture level-of-detail bias, or 1.0, 2.0, or 4.0 when specifying | |
19716 | the @code{GL_RGB_SCALE} or @code{GL_ALPHA_SCALE}. | |
19717 | ||
19718 | @end table | |
19719 | ||
8925f36f AW |
19720 | A texture environment specifies how texture values are interpreted when |
19721 | a fragment is textured. When @var{target} is | |
19722 | @code{GL_TEXTURE_FILTER_CONTROL}, @var{pname} must be | |
19723 | @code{GL_TEXTURE_LOD_BIAS}. When @var{target} is @code{GL_TEXTURE_ENV}, | |
19724 | @var{pname} can be @code{GL_TEXTURE_ENV_MODE}, | |
19725 | @code{GL_TEXTURE_ENV_COLOR}, @code{GL_COMBINE_RGB}, | |
19726 | @code{GL_COMBINE_ALPHA}, @code{GL_RGB_SCALE}, @code{GL_ALPHA_SCALE}, | |
19727 | @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, @code{GL_SRC2_RGB}, | |
19728 | @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, or @code{GL_SRC2_ALPHA}. | |
19729 | ||
19730 | If @var{pname} is @code{GL_TEXTURE_ENV_MODE}, then @var{params} is (or | |
19731 | points to) the symbolic name of a texture function. Six texture | |
19732 | functions may be specified: @code{GL_ADD}, @code{GL_MODULATE}, | |
19733 | @code{GL_DECAL}, @code{GL_BLEND}, @code{GL_REPLACE}, or | |
19734 | @code{GL_COMBINE}. | |
19735 | ||
19736 | The following table shows the correspondence of filtered texture values | |
3c9b6116 AW |
19737 | @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}}, |
19738 | @r{@var{A}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{I}_@var{t}} to texture | |
19739 | source components. @r{@var{C}_@var{s}} and @r{@var{A}_@var{s}} are used | |
19740 | by the texture functions described below. | |
8925f36f AW |
19741 | |
19742 | ||
19743 | ||
19744 | @table @asis | |
19745 | @item | |
19746 | Texture Base Internal Format | |
3c9b6116 | 19747 | @r{@code{C}_@var{s}}, @r{@code{A}_@var{s}} |
8925f36f AW |
19748 | |
19749 | @item @code{GL_ALPHA} | |
3c9b6116 | 19750 | (0, 0, 0) , @r{@var{A}_@var{t}} |
8925f36f AW |
19751 | |
19752 | @item @code{GL_LUMINANCE} | |
3c9b6116 | 19753 | ( @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}} ) , 1 |
8925f36f AW |
19754 | |
19755 | @item @code{GL_LUMINANCE_ALPHA} | |
3c9b6116 AW |
19756 | ( @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}} ) , |
19757 | @r{@var{A}_@var{t}} | |
8925f36f AW |
19758 | |
19759 | @item @code{GL_INTENSITY} | |
3c9b6116 AW |
19760 | ( @r{@var{I}_@var{t}}, @r{@var{I}_@var{t}}, @r{@var{I}_@var{t}} ) , |
19761 | @r{@var{I}_@var{t}} | |
8925f36f AW |
19762 | |
19763 | @item @code{GL_RGB} | |
3c9b6116 | 19764 | ( @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}} ) , 1 |
8925f36f AW |
19765 | |
19766 | @item @code{GL_RGBA} | |
3c9b6116 AW |
19767 | ( @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}} ) , |
19768 | @r{@var{A}_@var{t}} | |
8925f36f AW |
19769 | |
19770 | @end table | |
19771 | ||
19772 | A texture function acts on the fragment to be textured using the texture | |
19773 | image value that applies to the fragment (see @code{glTexParameter}) and | |
19774 | produces an RGBA color for that fragment. The following table shows how | |
19775 | the RGBA color is produced for each of the first five texture functions | |
3c9b6116 AW |
19776 | that can be chosen. @r{@var{C}} is a triple of color values (RGB) and |
19777 | @r{@var{A}} is the associated alpha value. RGBA values extracted from a | |
19778 | texture image are in the range [0,1]. The subscript @r{@var{p}} refers | |
19779 | to the color computed from the previous texture stage (or the incoming | |
19780 | fragment if processing texture stage 0), the subscript @r{@var{s}} to | |
19781 | the texture source color, the subscript @r{@var{c}} to the texture | |
19782 | environment color, and the subscript @r{@var{v}} indicates a value | |
19783 | produced by the texture function. | |
8925f36f AW |
19784 | |
19785 | ||
19786 | ||
19787 | @table @asis | |
19788 | @item | |
19789 | Texture Base Internal Format | |
19790 | @code{Value}, @code{GL_REPLACE} Function , @code{GL_MODULATE} Function , | |
19791 | @code{GL_DECAL} Function , @code{GL_BLEND} Function , @code{GL_ADD} | |
19792 | Function | |
19793 | ||
19794 | @item @code{GL_ALPHA} | |
3c9b6116 AW |
19795 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{p}}, @r{@var{C}_@var{p}}, |
19796 | undefined , @r{@var{C}_@var{p}}, @r{@var{C}_@var{p}} | |
8925f36f AW |
19797 | |
19798 | @item | |
3c9b6116 AW |
19799 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}}, |
19800 | @r{@var{A}_@var{p}@var{A}_@var{s}}, , | |
19801 | @r{@var{A}_@var{v}=@var{A}_@var{p}@var{A}_@var{s}}, | |
19802 | @r{@var{A}_@var{p}@var{A}_@var{s}} | |
8925f36f AW |
19803 | |
19804 | @item @code{GL_LUMINANCE} | |
3c9b6116 AW |
19805 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
19806 | @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined , | |
19807 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
19808 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
19809 | |
19810 | @item | |
19811 | (or 1) | |
3c9b6116 AW |
19812 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, , |
19813 | @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}} | |
8925f36f AW |
19814 | |
19815 | @item @code{GL_LUMINANCE_ALPHA} | |
3c9b6116 AW |
19816 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
19817 | @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined , | |
19818 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
19819 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
19820 | |
19821 | @item | |
19822 | (or 2) | |
3c9b6116 AW |
19823 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}}, |
19824 | @r{@var{A}_@var{p}@var{A}_@var{s}}, , | |
19825 | @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}@var{A}_@var{s}} | |
8925f36f AW |
19826 | |
19827 | @item @code{GL_INTENSITY} | |
3c9b6116 AW |
19828 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
19829 | @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined , | |
19830 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
19831 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
19832 | |
19833 | @item | |
3c9b6116 AW |
19834 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}}, |
19835 | @r{@var{A}_@var{p}@var{A}_@var{s}}, , | |
19836 | @r{@var{A}_@var{p}(1-@var{A}_@var{s},)+@var{A}_@var{c}@var{A}_@var{s}}, | |
19837 | @r{@var{A}_@var{p}+@var{A}_@var{s}} | |
8925f36f AW |
19838 | |
19839 | @item @code{GL_RGB} | |
3c9b6116 AW |
19840 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
19841 | @r{@var{C}_@var{p}@var{C}_@var{s}}, @r{@var{C}_@var{s}}, | |
19842 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
19843 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
19844 | |
19845 | @item | |
19846 | (or 3) | |
3c9b6116 AW |
19847 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, |
19848 | @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}} | |
8925f36f AW |
19849 | |
19850 | @item @code{GL_RGBA} | |
3c9b6116 AW |
19851 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
19852 | @r{@var{C}_@var{p}@var{C}_@var{s}}, | |
19853 | @r{@var{C}_@var{p}(1-@var{A}_@var{s},)+@var{C}_@var{s}@var{A}_@var{s}}, | |
19854 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
19855 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
19856 | |
19857 | @item | |
19858 | (or 4) | |
3c9b6116 AW |
19859 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}}, |
19860 | @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}}, | |
19861 | @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}@var{A}_@var{s}} | |
8925f36f AW |
19862 | |
19863 | @end table | |
19864 | ||
19865 | If @var{pname} is @code{GL_TEXTURE_ENV_MODE}, and @var{params} is | |
19866 | @code{GL_COMBINE}, the form of the texture function depends on the | |
19867 | values of @code{GL_COMBINE_RGB} and @code{GL_COMBINE_ALPHA}. | |
19868 | ||
19869 | The following describes how the texture sources, as specified by | |
19870 | @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, @code{GL_SRC2_RGB}, | |
19871 | @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, and @code{GL_SRC2_ALPHA}, | |
19872 | are combined to produce a final texture color. In the following tables, | |
3c9b6116 AW |
19873 | @code{GL_SRC0_c} is represented by @r{@var{Arg0}}, @code{GL_SRC1_c} is |
19874 | represented by @r{@var{Arg1}}, and @code{GL_SRC2_c} is represented by | |
19875 | @r{@var{Arg2}}. | |
8925f36f AW |
19876 | |
19877 | @code{GL_COMBINE_RGB} accepts any of @code{GL_REPLACE}, | |
19878 | @code{GL_MODULATE}, @code{GL_ADD}, @code{GL_ADD_SIGNED}, | |
19879 | @code{GL_INTERPOLATE}, @code{GL_SUBTRACT}, @code{GL_DOT3_RGB}, or | |
19880 | @code{GL_DOT3_RGBA}. | |
19881 | ||
19882 | ||
19883 | ||
19884 | @table @asis | |
19885 | @item @strong{@code{GL_COMBINE_RGB}} | |
19886 | @strong{Texture Function} | |
19887 | ||
19888 | @item @code{GL_REPLACE} | |
3c9b6116 | 19889 | @r{@var{Arg0}} |
8925f36f AW |
19890 | |
19891 | @item @code{GL_MODULATE} | |
3c9b6116 | 19892 | @r{@var{Arg0}×@var{Arg1}} |
8925f36f AW |
19893 | |
19894 | @item @code{GL_ADD} | |
3c9b6116 | 19895 | @r{@var{Arg0}+@var{Arg1}} |
8925f36f AW |
19896 | |
19897 | @item @code{GL_ADD_SIGNED} | |
3c9b6116 | 19898 | @r{@var{Arg0}+@var{Arg1}-0.5} |
8925f36f AW |
19899 | |
19900 | @item @code{GL_INTERPOLATE} | |
3c9b6116 | 19901 | @r{@var{Arg0}×@var{Arg2}+@var{Arg1}×(1-@var{Arg2},)} |
8925f36f AW |
19902 | |
19903 | @item @code{GL_SUBTRACT} | |
3c9b6116 | 19904 | @r{@var{Arg0}-@var{Arg1}} |
8925f36f AW |
19905 | |
19906 | @item @code{GL_DOT3_RGB} | |
19907 | or @code{GL_DOT3_RGBA} | |
3c9b6116 | 19908 | @r{4×(((@var{Arg0}_@var{r},-0.5,)×(@var{Arg1}_@var{r},-0.5,),)+((@var{Arg0}_@var{g},-0.5,)×(@var{Arg1}_@var{g},-0.5,),)+((@var{Arg0}_@var{b},-0.5,)×(@var{Arg1}_@var{b},-0.5,),),)} |
8925f36f AW |
19909 | |
19910 | @end table | |
19911 | ||
19912 | The scalar results for @code{GL_DOT3_RGB} and @code{GL_DOT3_RGBA} are | |
19913 | placed into each of the 3 (RGB) or 4 (RGBA) components on output. | |
19914 | ||
19915 | Likewise, @code{GL_COMBINE_ALPHA} accepts any of @code{GL_REPLACE}, | |
19916 | @code{GL_MODULATE}, @code{GL_ADD}, @code{GL_ADD_SIGNED}, | |
19917 | @code{GL_INTERPOLATE}, or @code{GL_SUBTRACT}. The following table | |
19918 | describes how alpha values are combined: | |
19919 | ||
19920 | ||
19921 | ||
19922 | @table @asis | |
19923 | @item @strong{@code{GL_COMBINE_ALPHA}} | |
19924 | @strong{Texture Function} | |
19925 | ||
19926 | @item @code{GL_REPLACE} | |
3c9b6116 | 19927 | @r{@var{Arg0}} |
8925f36f AW |
19928 | |
19929 | @item @code{GL_MODULATE} | |
3c9b6116 | 19930 | @r{@var{Arg0}×@var{Arg1}} |
8925f36f AW |
19931 | |
19932 | @item @code{GL_ADD} | |
3c9b6116 | 19933 | @r{@var{Arg0}+@var{Arg1}} |
8925f36f AW |
19934 | |
19935 | @item @code{GL_ADD_SIGNED} | |
3c9b6116 | 19936 | @r{@var{Arg0}+@var{Arg1}-0.5} |
8925f36f AW |
19937 | |
19938 | @item @code{GL_INTERPOLATE} | |
3c9b6116 | 19939 | @r{@var{Arg0}×@var{Arg2}+@var{Arg1}×(1-@var{Arg2},)} |
8925f36f AW |
19940 | |
19941 | @item @code{GL_SUBTRACT} | |
3c9b6116 | 19942 | @r{@var{Arg0}-@var{Arg1}} |
8925f36f AW |
19943 | |
19944 | @end table | |
19945 | ||
3c9b6116 AW |
19946 | In the following tables, the value @r{@var{C}_@var{s}} represents the |
19947 | color sampled from the currently bound texture, @r{@var{C}_@var{c}} | |
19948 | represents the constant texture-environment color, @r{@var{C}_@var{f}} | |
19949 | represents the primary color of the incoming fragment, and | |
19950 | @r{@var{C}_@var{p}} represents the color computed from the previous | |
19951 | texture stage or @r{@var{C}_@var{f}} if processing texture stage 0. | |
19952 | Likewise, @r{@var{A}_@var{s}}, @r{@var{A}_@var{c}}, @r{@var{A}_@var{f}}, | |
19953 | and @r{@var{A}_@var{p}} represent the respective alpha values. | |
8925f36f | 19954 | |
3c9b6116 AW |
19955 | The following table describes the values assigned to @r{@var{Arg0}}, |
19956 | @r{@var{Arg1}}, and @r{@var{Arg2}} based upon the RGB sources and | |
8925f36f AW |
19957 | operands: |
19958 | ||
19959 | ||
19960 | ||
19961 | @table @asis | |
19962 | @item @strong{@code{GL_SRCn_RGB}} | |
19963 | @strong{@code{GL_OPERANDn_RGB}}, @strong{Argument Value} | |
19964 | ||
19965 | @item @code{GL_TEXTURE} | |
3c9b6116 | 19966 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{s},} |
8925f36f AW |
19967 | |
19968 | @item | |
3c9b6116 | 19969 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{s},} |
8925f36f AW |
19970 | |
19971 | @item | |
3c9b6116 | 19972 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},} |
8925f36f AW |
19973 | |
19974 | @item | |
3c9b6116 | 19975 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},} |
8925f36f AW |
19976 | |
19977 | @item @code{GL_TEXTUREn} | |
3c9b6116 | 19978 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{s},} |
8925f36f AW |
19979 | |
19980 | @item | |
3c9b6116 | 19981 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{s},} |
8925f36f AW |
19982 | |
19983 | @item | |
3c9b6116 | 19984 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},} |
8925f36f AW |
19985 | |
19986 | @item | |
3c9b6116 | 19987 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},} |
8925f36f AW |
19988 | |
19989 | @item @code{GL_CONSTANT} | |
3c9b6116 | 19990 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{c},} |
8925f36f AW |
19991 | |
19992 | @item | |
3c9b6116 | 19993 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{c},} |
8925f36f AW |
19994 | |
19995 | @item | |
3c9b6116 | 19996 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{c},} |
8925f36f AW |
19997 | |
19998 | @item | |
3c9b6116 | 19999 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{c},} |
8925f36f AW |
20000 | |
20001 | @item @code{GL_PRIMARY_COLOR} | |
3c9b6116 | 20002 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{f},} |
8925f36f AW |
20003 | |
20004 | @item | |
3c9b6116 | 20005 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{f},} |
8925f36f AW |
20006 | |
20007 | @item | |
3c9b6116 | 20008 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{f},} |
8925f36f AW |
20009 | |
20010 | @item | |
3c9b6116 | 20011 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{f},} |
8925f36f AW |
20012 | |
20013 | @item @code{GL_PREVIOUS} | |
3c9b6116 | 20014 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{p},} |
8925f36f AW |
20015 | |
20016 | @item | |
3c9b6116 | 20017 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{p},} |
8925f36f AW |
20018 | |
20019 | @item | |
3c9b6116 | 20020 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{p},} |
8925f36f AW |
20021 | |
20022 | @item | |
3c9b6116 | 20023 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{p},} |
8925f36f AW |
20024 | |
20025 | @end table | |
20026 | ||
3c9b6116 AW |
20027 | For @code{GL_TEXTUREn} sources, @r{@var{C}_@var{s}} and |
20028 | @r{@var{A}_@var{s}} represent the color and alpha, respectively, | |
20029 | produced from texture stage @r{@var{n}}. | |
8925f36f | 20030 | |
3c9b6116 AW |
20031 | The follow table describes the values assigned to @r{@var{Arg0}}, |
20032 | @r{@var{Arg1}}, and @r{@var{Arg2}} based upon the alpha sources and | |
20033 | operands: | |
8925f36f AW |
20034 | |
20035 | ||
20036 | ||
20037 | @table @asis | |
20038 | @item @strong{@code{GL_SRCn_ALPHA}} | |
20039 | @strong{@code{GL_OPERANDn_ALPHA}}, @strong{Argument Value} | |
20040 | ||
20041 | @item @code{GL_TEXTURE} | |
3c9b6116 | 20042 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},} |
8925f36f AW |
20043 | |
20044 | @item | |
3c9b6116 | 20045 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},} |
8925f36f AW |
20046 | |
20047 | @item @code{GL_TEXTUREn} | |
3c9b6116 | 20048 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},} |
8925f36f AW |
20049 | |
20050 | @item | |
3c9b6116 | 20051 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},} |
8925f36f AW |
20052 | |
20053 | @item @code{GL_CONSTANT} | |
3c9b6116 | 20054 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{c},} |
8925f36f AW |
20055 | |
20056 | @item | |
3c9b6116 | 20057 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{c},} |
8925f36f AW |
20058 | |
20059 | @item @code{GL_PRIMARY_COLOR} | |
3c9b6116 | 20060 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{f},} |
8925f36f AW |
20061 | |
20062 | @item | |
3c9b6116 | 20063 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{f},} |
8925f36f AW |
20064 | |
20065 | @item @code{GL_PREVIOUS} | |
3c9b6116 | 20066 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{p},} |
8925f36f AW |
20067 | |
20068 | @item | |
3c9b6116 | 20069 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{p},} |
8925f36f AW |
20070 | |
20071 | @end table | |
20072 | ||
20073 | The RGB and alpha results of the texture function are multipled by the | |
20074 | values of @code{GL_RGB_SCALE} and @code{GL_ALPHA_SCALE}, respectively, | |
3c9b6116 | 20075 | and clamped to the range @r{[0,1]}. |
8925f36f AW |
20076 | |
20077 | If @var{pname} is @code{GL_TEXTURE_ENV_COLOR}, @var{params} is a pointer | |
20078 | to an array that holds an RGBA color consisting of four values. Integer | |
20079 | color components are interpreted linearly such that the most positive | |
20080 | integer maps to 1.0, and the most negative integer maps to -1.0. The | |
20081 | values are clamped to the range [0,1] when they are specified. | |
3c9b6116 | 20082 | @r{@var{C}_@var{c}} takes these four values. |
8925f36f AW |
20083 | |
20084 | If @var{pname} is @code{GL_TEXTURE_LOD_BIAS}, the value specified is | |
20085 | added to the texture level-of-detail parameter, that selects which | |
20086 | mipmap, or mipmaps depending upon the selected | |
20087 | @code{GL_TEXTURE_MIN_FILTER}, will be sampled. | |
20088 | ||
20089 | @code{GL_TEXTURE_ENV_MODE} defaults to @code{GL_MODULATE} and | |
20090 | @code{GL_TEXTURE_ENV_COLOR} defaults to (0, 0, 0, 0). | |
20091 | ||
20092 | If @var{target} is @code{GL_POINT_SPRITE} and @var{pname} is | |
20093 | @code{GL_COORD_REPLACE}, the boolean value specified is used to either | |
20094 | enable or disable point sprite texture coordinate replacement. The | |
20095 | default value is @code{GL_FALSE}. | |
20096 | ||
8925f36f AW |
20097 | @code{GL_INVALID_ENUM} is generated when @var{target} or @var{pname} is |
20098 | not one of the accepted defined values, or when @var{params} should have | |
20099 | a defined constant value (based on the value of @var{pname}) and does | |
20100 | not. | |
20101 | ||
20102 | @code{GL_INVALID_VALUE} is generated if the @var{params} value for | |
20103 | @code{GL_RGB_SCALE} or @code{GL_ALPHA_SCALE} are not one of 1.0, 2.0, or | |
20104 | 4.0. | |
20105 | ||
20106 | @code{GL_INVALID_OPERATION} is generated if @code{glTexEnv} is executed | |
20107 | between the execution of @code{glBegin} and the corresponding execution | |
20108 | of @code{glEnd}. | |
20109 | ||
bb894c9d | 20110 | @end deftypefun |
8925f36f | 20111 | |
bb894c9d | 20112 | @deftypefun void glTexGeni coord pname param |
ca09631c | 20113 | @deftypefunx void glTexGenf coord pname param |
3c9b6116 AW |
20114 | Control the generation of texture coordinates. |
20115 | ||
8925f36f AW |
20116 | @table @asis |
20117 | @item @var{coord} | |
20118 | Specifies a texture coordinate. Must be one of @code{GL_S}, @code{GL_T}, | |
20119 | @code{GL_R}, or @code{GL_Q}. | |
20120 | ||
20121 | @item @var{pname} | |
20122 | Specifies the symbolic name of the texture-coordinate generation | |
20123 | function. Must be @code{GL_TEXTURE_GEN_MODE}. | |
20124 | ||
20125 | @item @var{param} | |
20126 | Specifies a single-valued texture generation parameter, one of | |
20127 | @code{GL_OBJECT_LINEAR}, @code{GL_EYE_LINEAR}, @code{GL_SPHERE_MAP}, | |
20128 | @code{GL_NORMAL_MAP}, or @code{GL_REFLECTION_MAP}. | |
20129 | ||
20130 | @end table | |
20131 | ||
8925f36f AW |
20132 | @code{glTexGen} selects a texture-coordinate generation function or |
20133 | supplies coefficients for one of the functions. @var{coord} names one of | |
20134 | the (@var{s}, @var{t}, @var{r}, @var{q}) texture coordinates; it must be | |
20135 | one of the symbols @code{GL_S}, @code{GL_T}, @code{GL_R}, or | |
20136 | @code{GL_Q}. @var{pname} must be one of three symbolic constants: | |
20137 | @code{GL_TEXTURE_GEN_MODE}, @code{GL_OBJECT_PLANE}, or | |
20138 | @code{GL_EYE_PLANE}. If @var{pname} is @code{GL_TEXTURE_GEN_MODE}, then | |
20139 | @var{params} chooses a mode, one of @code{GL_OBJECT_LINEAR}, | |
20140 | @code{GL_EYE_LINEAR}, @code{GL_SPHERE_MAP}, @code{GL_NORMAL_MAP}, or | |
20141 | @code{GL_REFLECTION_MAP}. If @var{pname} is either | |
20142 | @code{GL_OBJECT_PLANE} or @code{GL_EYE_PLANE}, @var{params} contains | |
20143 | coefficients for the corresponding texture generation function. | |
20144 | ||
20145 | If the texture generation function is @code{GL_OBJECT_LINEAR}, the | |
20146 | function | |
20147 | ||
3c9b6116 AW |
20148 | @r{@var{g}=@var{p}_1×@var{x}_@var{o}+@var{p}_2×@var{y}_@var{o}+@var{p}_3×@var{z}_@var{o}+@var{p}_4×@var{w}_@var{o}} |
20149 | ||
20150 | is used, where @r{@var{g}} is the value computed for the coordinate | |
20151 | named in @var{coord}, @r{@var{p}_1}, @r{@var{p}_2}, @r{@var{p}_3}, and | |
20152 | @r{@var{p}_4} are the four values supplied in @var{params}, and | |
20153 | @r{@var{x}_@var{o}}, @r{@var{y}_@var{o}}, @r{@var{z}_@var{o}}, and | |
20154 | @r{@var{w}_@var{o}} are the object coordinates of the vertex. This | |
20155 | function can be used, for example, to texture-map terrain using sea | |
20156 | level as a reference plane (defined by @r{@var{p}_1}, @r{@var{p}_2}, | |
20157 | @r{@var{p}_3}, and @r{@var{p}_4}). The altitude of a terrain vertex is | |
20158 | computed by the @code{GL_OBJECT_LINEAR} coordinate generation function | |
20159 | as its distance from sea level; that altitude can then be used to index | |
20160 | the texture image to map white snow onto peaks and green grass onto | |
20161 | foothills. | |
8925f36f AW |
20162 | |
20163 | If the texture generation function is @code{GL_EYE_LINEAR}, the function | |
20164 | ||
3c9b6116 | 20165 | @r{@var{g}=@var{p}_1,^″×@var{x}_@var{e}+@var{p}_2,^″×@var{y}_@var{e}+@var{p}_3,^″×@var{z}_@var{e}+@var{p}_4,^″×@var{w}_@var{e}} |
8925f36f AW |
20166 | |
20167 | is used, where | |
20168 | ||
3c9b6116 | 20169 | @r{(@var{p}_1,^″@var{p}_2,^″@var{p}_3,^″@var{p}_4,^″,)=(@var{p}_1@var{p}_2@var{p}_3@var{p}_4,)@var{M}^-1} |
8925f36f | 20170 | |
3c9b6116 AW |
20171 | and @r{@var{x}_@var{e}}, @r{@var{y}_@var{e}}, @r{@var{z}_@var{e}}, and |
20172 | @r{@var{w}_@var{e}} are the eye coordinates of the vertex, | |
20173 | @r{@var{p}_1}, @r{@var{p}_2}, @r{@var{p}_3}, and @r{@var{p}_4} are the | |
20174 | values supplied in @var{params}, and @r{@var{M}} is the modelview matrix | |
20175 | when @code{glTexGen} is invoked. If @r{@var{M}} is poorly conditioned or | |
8925f36f AW |
20176 | singular, texture coordinates generated by the resulting function may be |
20177 | inaccurate or undefined. | |
20178 | ||
20179 | Note that the values in @var{params} define a reference plane in eye | |
20180 | coordinates. The modelview matrix that is applied to them may not be the | |
20181 | same one in effect when the polygon vertices are transformed. This | |
20182 | function establishes a field of texture coordinates that can produce | |
20183 | dynamic contour lines on moving objects. | |
20184 | ||
20185 | If the texture generation function is @code{GL_SPHERE_MAP} and | |
3c9b6116 AW |
20186 | @var{coord} is either @code{GL_S} or @code{GL_T}, @r{@var{s}} and |
20187 | @r{@var{t}} texture coordinates are generated as follows. Let @var{u} be | |
20188 | the unit vector pointing from the origin to the polygon vertex (in eye | |
20189 | coordinates). Let @var{n} sup prime be the current normal, after | |
8925f36f AW |
20190 | transformation to eye coordinates. Let |
20191 | ||
3c9b6116 | 20192 | @r{@var{f}=(@var{f}_@var{x}@var{f}_@var{y}@var{f}_@var{z},)^@var{T}} |
8925f36f AW |
20193 | be the reflection vector such that |
20194 | ||
3c9b6116 | 20195 | @r{@var{f}=@var{u}-2@var{n}^″@var{n}^″,^@var{T}@var{u}} |
8925f36f AW |
20196 | |
20197 | Finally, let | |
3c9b6116 AW |
20198 | @r{@var{m}=2√(@var{f}_@var{x},^2+@var{f}_@var{y},^2+(@var{f}_@var{z}+1,)^2,)}. |
20199 | Then the values assigned to the @r{@var{s}} and @r{@var{t}} texture | |
20200 | coordinates are | |
8925f36f | 20201 | |
3c9b6116 | 20202 | @r{@var{s}=@var{f}_@var{x}/@var{m}+1/2} |
8925f36f | 20203 | |
3c9b6116 | 20204 | @r{@var{t}=@var{f}_@var{y}/@var{m}+1/2} |
8925f36f AW |
20205 | |
20206 | To enable or disable a texture-coordinate generation function, call | |
20207 | @code{glEnable} or @code{glDisable} with one of the symbolic | |
20208 | texture-coordinate names (@code{GL_TEXTURE_GEN_S}, | |
20209 | @code{GL_TEXTURE_GEN_T}, @code{GL_TEXTURE_GEN_R}, or | |
20210 | @code{GL_TEXTURE_GEN_Q}) as the argument. When enabled, the specified | |
20211 | texture coordinate is computed according to the generating function | |
20212 | associated with that coordinate. When disabled, subsequent vertices take | |
20213 | the specified texture coordinate from the current set of texture | |
20214 | coordinates. Initially, all texture generation functions are set to | |
3c9b6116 AW |
20215 | @code{GL_EYE_LINEAR} and are disabled. Both @r{@var{s}} plane equations |
20216 | are (1, 0, 0, 0), both @r{@var{t}} plane equations are (0, 1, 0, 0), and | |
20217 | all @r{@var{r}} and @r{@var{q}} plane equations are (0, 0, 0, 0). | |
8925f36f AW |
20218 | |
20219 | When the @code{ARB_multitexture} extension is supported, @code{glTexGen} | |
20220 | sets the texture generation parameters for the currently active texture | |
20221 | unit, selected with @code{glActiveTexture}. | |
20222 | ||
8925f36f AW |
20223 | @code{GL_INVALID_ENUM} is generated when @var{coord} or @var{pname} is |
20224 | not an accepted defined value, or when @var{pname} is | |
20225 | @code{GL_TEXTURE_GEN_MODE} and @var{params} is not an accepted defined | |
20226 | value. | |
20227 | ||
20228 | @code{GL_INVALID_ENUM} is generated when @var{pname} is | |
20229 | @code{GL_TEXTURE_GEN_MODE}, @var{params} is @code{GL_SPHERE_MAP}, and | |
20230 | @var{coord} is either @code{GL_R} or @code{GL_Q}. | |
20231 | ||
20232 | @code{GL_INVALID_OPERATION} is generated if @code{glTexGen} is executed | |
20233 | between the execution of @code{glBegin} and the corresponding execution | |
20234 | of @code{glEnd}. | |
20235 | ||
bb894c9d | 20236 | @end deftypefun |
8925f36f | 20237 | |
bb894c9d | 20238 | @deftypefun void glTexImage1D target level internalFormat width border format type data |
3c9b6116 AW |
20239 | Specify a one-dimensional texture image. |
20240 | ||
8925f36f AW |
20241 | @table @asis |
20242 | @item @var{target} | |
20243 | Specifies the target texture. Must be @code{GL_TEXTURE_1D} or | |
20244 | @code{GL_PROXY_TEXTURE_1D}. | |
20245 | ||
20246 | @item @var{level} | |
20247 | Specifies the level-of-detail number. Level 0 is the base image level. | |
20248 | Level @var{n} is the @var{n}th mipmap reduction image. | |
20249 | ||
20250 | @item @var{internalFormat} | |
20251 | Specifies the number of color components in the texture. Must be 1, 2, | |
20252 | 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA}, | |
20253 | @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, | |
20254 | @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA}, | |
20255 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
20256 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
20257 | @code{GL_COMPRESSED_RGBA}, @code{GL_DEPTH_COMPONENT}, | |
20258 | @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, | |
20259 | @code{GL_DEPTH_COMPONENT32}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
20260 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
20261 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
20262 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
20263 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
20264 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY}, | |
20265 | @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12}, | |
20266 | @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
20267 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
20268 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
20269 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
20270 | @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE}, | |
20271 | @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
20272 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
20273 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
20274 | ||
20275 | @item @var{width} | |
20276 | Specifies the width of the texture image including the border if any. If | |
20277 | the GL version does not support non-power-of-two sizes, this value must | |
3c9b6116 AW |
20278 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
20279 | implementations support texture images that are at least 64 texels wide. | |
20280 | The height of the 1D texture image is 1. | |
8925f36f AW |
20281 | |
20282 | @item @var{border} | |
20283 | Specifies the width of the border. Must be either 0 or 1. | |
20284 | ||
20285 | @item @var{format} | |
20286 | Specifies the format of the pixel data. The following symbolic values | |
20287 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, | |
20288 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
20289 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
20290 | @code{GL_LUMINANCE_ALPHA}. | |
20291 | ||
20292 | @item @var{type} | |
20293 | Specifies the data type of the pixel data. The following symbolic values | |
20294 | are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
20295 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
20296 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
20297 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
20298 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
20299 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
20300 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
20301 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
20302 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
20303 | ||
20304 | @item @var{data} | |
20305 | Specifies a pointer to the image data in memory. | |
20306 | ||
20307 | @end table | |
20308 | ||
8925f36f AW |
20309 | Texturing maps a portion of a specified texture image onto each |
20310 | graphical primitive for which texturing is enabled. To enable and | |
20311 | disable one-dimensional texturing, call @code{glEnable} and | |
20312 | @code{glDisable} with argument @code{GL_TEXTURE_1D}. | |
20313 | ||
20314 | Texture images are defined with @code{glTexImage1D}. The arguments | |
20315 | describe the parameters of the texture image, such as width, width of | |
20316 | the border, level-of-detail number (see @code{glTexParameter}), and the | |
20317 | internal resolution and format used to store the image. The last three | |
20318 | arguments describe how the image is represented in memory; they are | |
20319 | identical to the pixel formats used for @code{glDrawPixels}. | |
20320 | ||
20321 | If @var{target} is @code{GL_PROXY_TEXTURE_1D}, no data is read from | |
20322 | @var{data}, but all of the texture image state is recalculated, checked | |
20323 | for consistency, and checked against the implementation's capabilities. | |
20324 | If the implementation cannot handle a texture of the requested texture | |
20325 | size, it sets all of the image state to 0, but does not generate an | |
20326 | error (see @code{glGetError}). To query for an entire mipmap array, use | |
20327 | an image array level greater than or equal to 1. | |
20328 | ||
20329 | If @var{target} is @code{GL_TEXTURE_1D}, data is read from @var{data} as | |
20330 | a sequence of signed or unsigned bytes, shorts, or longs, or | |
20331 | single-precision floating-point values, depending on @var{type}. These | |
20332 | values are grouped into sets of one, two, three, or four values, | |
20333 | depending on @var{format}, to form elements. If @var{type} is | |
20334 | @code{GL_BITMAP}, the data is considered as a string of unsigned bytes | |
20335 | (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is | |
20336 | treated as eight 1-bit elements, with bit ordering determined by | |
20337 | @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}). | |
20338 | ||
20339 | If a non-zero named buffer object is bound to the | |
20340 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
20341 | texture image is specified, @var{data} is treated as a byte offset into | |
20342 | the buffer object's data store. | |
20343 | ||
20344 | The first element corresponds to the left end of the texture array. | |
20345 | Subsequent elements progress left-to-right through the remaining texels | |
20346 | in the texture array. The final element corresponds to the right end of | |
20347 | the texture array. | |
20348 | ||
20349 | @var{format} determines the composition of each element in @var{data}. | |
20350 | It can assume one of these symbolic values: | |
20351 | ||
20352 | @table @asis | |
20353 | @item @code{GL_COLOR_INDEX} | |
20354 | Each element is a single value, a color index. The GL converts it to | |
20355 | fixed point (with an unspecified number of zero bits to the right of the | |
20356 | binary point), shifted left or right depending on the value and sign of | |
20357 | @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see | |
20358 | @code{glPixelTransfer}). The resulting index is converted to a set of | |
20359 | color components using the @code{GL_PIXEL_MAP_I_TO_R}, | |
20360 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
20361 | @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1]. | |
20362 | ||
20363 | @item @code{GL_RED} | |
20364 | Each element is a single red component. The GL converts it to floating | |
20365 | point and assembles it into an RGBA element by attaching 0 for green and | |
20366 | blue, and 1 for alpha. Each component is then multiplied by the signed | |
20367 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
20368 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20369 | @code{glPixelTransfer}). | |
20370 | ||
20371 | @item @code{GL_GREEN} | |
20372 | Each element is a single green component. The GL converts it to floating | |
20373 | point and assembles it into an RGBA element by attaching 0 for red and | |
20374 | blue, and 1 for alpha. Each component is then multiplied by the signed | |
20375 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
20376 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20377 | @code{glPixelTransfer}). | |
20378 | ||
20379 | @item @code{GL_BLUE} | |
20380 | Each element is a single blue component. The GL converts it to floating | |
20381 | point and assembles it into an RGBA element by attaching 0 for red and | |
20382 | green, and 1 for alpha. Each component is then multiplied by the signed | |
20383 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
20384 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20385 | @code{glPixelTransfer}). | |
20386 | ||
20387 | @item @code{GL_ALPHA} | |
20388 | Each element is a single alpha component. The GL converts it to floating | |
20389 | point and assembles it into an RGBA element by attaching 0 for red, | |
20390 | green, and blue. Each component is then multiplied by the signed scale | |
20391 | factor @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
20392 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20393 | ||
20394 | @item @code{GL_INTENSITY} | |
20395 | Each element is a single intensity value. The GL converts it to floating | |
20396 | point, then assembles it into an RGBA element by replicating the | |
20397 | intensity value three times for red, green, blue, and alpha. Each | |
20398 | component is then multiplied by the signed scale factor | |
20399 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
20400 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20401 | ||
20402 | @item @code{GL_RGB} | |
20403 | @item @code{GL_BGR} | |
20404 | Each element is an RGB triple. The GL converts it to floating point and | |
20405 | assembles it into an RGBA element by attaching 1 for alpha. Each | |
20406 | component is then multiplied by the signed scale factor | |
20407 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
20408 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20409 | ||
20410 | @item @code{GL_RGBA} | |
20411 | @item @code{GL_BGRA} | |
20412 | Each element contains all four components. Each component is multiplied | |
20413 | by the signed scale factor @code{GL_c_SCALE}, added to the signed bias | |
20414 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20415 | @code{glPixelTransfer}). | |
20416 | ||
20417 | @item @code{GL_LUMINANCE} | |
20418 | Each element is a single luminance value. The GL converts it to floating | |
20419 | point, then assembles it into an RGBA element by replicating the | |
20420 | luminance value three times for red, green, and blue and attaching 1 for | |
20421 | alpha. Each component is then multiplied by the signed scale factor | |
20422 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
20423 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20424 | ||
20425 | @item @code{GL_LUMINANCE_ALPHA} | |
20426 | Each element is a luminance/alpha pair. The GL converts it to floating | |
20427 | point, then assembles it into an RGBA element by replicating the | |
20428 | luminance value three times for red, green, and blue. Each component is | |
20429 | then multiplied by the signed scale factor @code{GL_c_SCALE}, added to | |
20430 | the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20431 | @code{glPixelTransfer}). | |
20432 | ||
20433 | @item @code{GL_DEPTH_COMPONENT} | |
20434 | Each element is a single depth value. The GL converts it to floating | |
20435 | point, multiplies by the signed scale factor @code{GL_DEPTH_SCALE}, adds | |
20436 | the signed bias @code{GL_DEPTH_BIAS}, and clamps to the range [0,1] (see | |
20437 | @code{glPixelTransfer}). | |
20438 | ||
20439 | @end table | |
20440 | ||
20441 | Refer to the @code{glDrawPixels} reference page for a description of the | |
20442 | acceptable values for the @var{type} parameter. | |
20443 | ||
20444 | If an application wants to store the texture at a certain resolution or | |
20445 | in a certain format, it can request the resolution and format with | |
20446 | @var{internalFormat}. The GL will choose an internal representation that | |
20447 | closely approximates that requested by @var{internalFormat}, but it may | |
20448 | not match exactly. (The representations specified by | |
20449 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and | |
20450 | @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 may | |
20451 | also be used to specify the above representations.) | |
20452 | ||
20453 | If the @var{internalFormat} parameter is one of the generic compressed | |
20454 | formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
20455 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
20456 | @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will | |
20457 | replace the internal format with the symbolic constant for a specific | |
20458 | internal format and compress the texture before storage. If no | |
20459 | corresponding internal format is available, or the GL can not compress | |
20460 | that image for any reason, the internal format is instead replaced with | |
20461 | a corresponding base internal format. | |
20462 | ||
20463 | If the @var{internalFormat} parameter is @code{GL_SRGB}, | |
20464 | @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8}, | |
20465 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
20466 | or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red, | |
20467 | green, blue, or luminance components are encoded in the sRGB color | |
20468 | space. Any alpha component is left unchanged. The conversion from the | |
3c9b6116 AW |
20469 | sRGB encoded component @r{@var{c}_@var{s}} to a linear component |
20470 | @r{@var{c}_@var{l}} is: | |
8925f36f | 20471 | |
3c9b6116 AW |
20472 | @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045), |
20473 | ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)} | |
8925f36f | 20474 | |
3c9b6116 | 20475 | Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1]. |
8925f36f AW |
20476 | |
20477 | Use the @code{GL_PROXY_TEXTURE_1D} target to try out a resolution and | |
20478 | format. The implementation will update and recompute its best match for | |
20479 | the requested storage resolution and format. To then query this state, | |
20480 | call @code{glGetTexLevelParameter}. If the texture cannot be | |
20481 | accommodated, texture state is set to 0. | |
20482 | ||
20483 | A one-component texture image uses only the red component of the RGBA | |
20484 | color from @var{data}. A two-component image uses the R and A values. A | |
20485 | three-component image uses the R, G, and B values. A four-component | |
20486 | image uses all of the RGBA components. | |
20487 | ||
20488 | Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA textures | |
20489 | during texture filtering and application. Image-based shadowing can be | |
20490 | enabled by comparing texture r coordinates to depth texture values to | |
20491 | generate a boolean result. See @code{glTexParameter} for details on | |
20492 | texture comparison. | |
20493 | ||
8925f36f AW |
20494 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
20495 | @code{GL_TEXTURE_1D} or @code{GL_PROXY_TEXTURE_1D}. | |
20496 | ||
20497 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
20498 | format constant. Format constants other than @code{GL_STENCIL_INDEX} are | |
20499 | accepted. | |
20500 | ||
20501 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
20502 | constant. | |
20503 | ||
20504 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
20505 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
20506 | ||
20507 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
20508 | ||
20509 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
20510 | @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of |
20511 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
20512 | |
20513 | @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1, | |
20514 | 2, 3, 4, or one of the accepted resolution and format symbolic | |
20515 | constants. | |
20516 | ||
20517 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or | |
20518 | greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
20519 | ||
20520 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
20521 | not supported and the @var{width} cannot be represented as | |
3c9b6116 | 20522 | @r{2^@var{n}+2(@var{border},)} for some integer value of @var{n}. |
8925f36f AW |
20523 | |
20524 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
20525 | ||
20526 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
20527 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
20528 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
20529 | and @var{format} is not @code{GL_RGB}. | |
20530 | ||
20531 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
20532 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
20533 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
20534 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
20535 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
20536 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
20537 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
20538 | ||
20539 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
20540 | @code{GL_DEPTH_COMPONENT} and @var{internalFormat} is not | |
20541 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
20542 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}. | |
20543 | ||
20544 | @code{GL_INVALID_OPERATION} is generated if @var{internalFormat} is | |
20545 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
20546 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}, and | |
20547 | @var{format} is not @code{GL_DEPTH_COMPONENT}. | |
20548 | ||
20549 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
20550 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
20551 | object's data store is currently mapped. | |
20552 | ||
20553 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
20554 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
20555 | would be unpacked from the buffer object such that the memory reads | |
20556 | required would exceed the data store size. | |
20557 | ||
20558 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
20559 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
20560 | is not evenly divisible into the number of bytes needed to store in | |
20561 | memory a datum indicated by @var{type}. | |
20562 | ||
20563 | @code{GL_INVALID_OPERATION} is generated if @code{glTexImage1D} is | |
20564 | executed between the execution of @code{glBegin} and the corresponding | |
20565 | execution of @code{glEnd}. | |
20566 | ||
bb894c9d | 20567 | @end deftypefun |
8925f36f | 20568 | |
bb894c9d | 20569 | @deftypefun void glTexImage2D target level internalFormat width height border format type data |
3c9b6116 AW |
20570 | Specify a two-dimensional texture image. |
20571 | ||
8925f36f AW |
20572 | @table @asis |
20573 | @item @var{target} | |
20574 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, | |
20575 | @code{GL_PROXY_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
20576 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
20577 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
20578 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
20579 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, | |
20580 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or | |
20581 | @code{GL_PROXY_TEXTURE_CUBE_MAP}. | |
20582 | ||
20583 | @item @var{level} | |
20584 | Specifies the level-of-detail number. Level 0 is the base image level. | |
20585 | Level @var{n} is the @var{n}th mipmap reduction image. | |
20586 | ||
20587 | @item @var{internalFormat} | |
20588 | Specifies the number of color components in the texture. Must be 1, 2, | |
20589 | 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA}, | |
20590 | @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, | |
20591 | @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA}, | |
20592 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
20593 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
20594 | @code{GL_COMPRESSED_RGBA}, @code{GL_DEPTH_COMPONENT}, | |
20595 | @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, | |
20596 | @code{GL_DEPTH_COMPONENT32}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
20597 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
20598 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
20599 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
20600 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
20601 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY}, | |
20602 | @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12}, | |
20603 | @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
20604 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
20605 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
20606 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
20607 | @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE}, | |
20608 | @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
20609 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
20610 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
20611 | ||
20612 | @item @var{width} | |
20613 | Specifies the width of the texture image including the border if any. If | |
20614 | the GL version does not support non-power-of-two sizes, this value must | |
3c9b6116 AW |
20615 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
20616 | implementations support texture images that are at least 64 texels wide. | |
8925f36f AW |
20617 | |
20618 | @item @var{height} | |
20619 | Specifies the height of the texture image including the border if any. | |
20620 | If the GL version does not support non-power-of-two sizes, this value | |
3c9b6116 AW |
20621 | must be @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}. |
20622 | All implementations support texture images that are at least 64 texels | |
20623 | high. | |
8925f36f AW |
20624 | |
20625 | @item @var{border} | |
20626 | Specifies the width of the border. Must be either 0 or 1. | |
20627 | ||
20628 | @item @var{format} | |
20629 | Specifies the format of the pixel data. The following symbolic values | |
20630 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, | |
20631 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
20632 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
20633 | @code{GL_LUMINANCE_ALPHA}. | |
20634 | ||
20635 | @item @var{type} | |
20636 | Specifies the data type of the pixel data. The following symbolic values | |
20637 | are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
20638 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
20639 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
20640 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
20641 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
20642 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
20643 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
20644 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
20645 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
20646 | ||
20647 | @item @var{data} | |
20648 | Specifies a pointer to the image data in memory. | |
20649 | ||
20650 | @end table | |
20651 | ||
8925f36f AW |
20652 | Texturing maps a portion of a specified texture image onto each |
20653 | graphical primitive for which texturing is enabled. To enable and | |
20654 | disable two-dimensional texturing, call @code{glEnable} and | |
20655 | @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and | |
20656 | disable texturing using cube-mapped texture, call @code{glEnable} and | |
20657 | @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}. | |
20658 | ||
20659 | To define texture images, call @code{glTexImage2D}. The arguments | |
20660 | describe the parameters of the texture image, such as height, width, | |
20661 | width of the border, level-of-detail number (see @code{glTexParameter}), | |
20662 | and number of color components provided. The last three arguments | |
20663 | describe how the image is represented in memory; they are identical to | |
20664 | the pixel formats used for @code{glDrawPixels}. | |
20665 | ||
20666 | If @var{target} is @code{GL_PROXY_TEXTURE_2D} or | |
20667 | @code{GL_PROXY_TEXTURE_CUBE_MAP}, no data is read from @var{data}, but | |
20668 | all of the texture image state is recalculated, checked for consistency, | |
20669 | and checked against the implementation's capabilities. If the | |
20670 | implementation cannot handle a texture of the requested texture size, it | |
20671 | sets all of the image state to 0, but does not generate an error (see | |
20672 | @code{glGetError}). To query for an entire mipmap array, use an image | |
20673 | array level greater than or equal to 1. | |
20674 | ||
20675 | If @var{target} is @code{GL_TEXTURE_2D}, or one of the | |
20676 | @code{GL_TEXTURE_CUBE_MAP} targets, data is read from @var{data} as a | |
20677 | sequence of signed or unsigned bytes, shorts, or longs, or | |
20678 | single-precision floating-point values, depending on @var{type}. These | |
20679 | values are grouped into sets of one, two, three, or four values, | |
20680 | depending on @var{format}, to form elements. If @var{type} is | |
20681 | @code{GL_BITMAP}, the data is considered as a string of unsigned bytes | |
20682 | (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is | |
20683 | treated as eight 1-bit elements, with bit ordering determined by | |
20684 | @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}). | |
20685 | ||
20686 | If a non-zero named buffer object is bound to the | |
20687 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
20688 | texture image is specified, @var{data} is treated as a byte offset into | |
20689 | the buffer object's data store. | |
20690 | ||
20691 | The first element corresponds to the lower left corner of the texture | |
20692 | image. Subsequent elements progress left-to-right through the remaining | |
20693 | texels in the lowest row of the texture image, and then in successively | |
20694 | higher rows of the texture image. The final element corresponds to the | |
20695 | upper right corner of the texture image. | |
20696 | ||
20697 | @var{format} determines the composition of each element in @var{data}. | |
20698 | It can assume one of these symbolic values: | |
20699 | ||
20700 | @table @asis | |
20701 | @item @code{GL_COLOR_INDEX} | |
20702 | Each element is a single value, a color index. The GL converts it to | |
20703 | fixed point (with an unspecified number of zero bits to the right of the | |
20704 | binary point), shifted left or right depending on the value and sign of | |
20705 | @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see | |
20706 | @code{glPixelTransfer}). The resulting index is converted to a set of | |
20707 | color components using the @code{GL_PIXEL_MAP_I_TO_R}, | |
20708 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
20709 | @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1]. | |
20710 | ||
20711 | @item @code{GL_RED} | |
20712 | Each element is a single red component. The GL converts it to floating | |
20713 | point and assembles it into an RGBA element by attaching 0 for green and | |
20714 | blue, and 1 for alpha. Each component is then multiplied by the signed | |
20715 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
20716 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20717 | @code{glPixelTransfer}). | |
20718 | ||
20719 | @item @code{GL_GREEN} | |
20720 | Each element is a single green component. The GL converts it to floating | |
20721 | point and assembles it into an RGBA element by attaching 0 for red and | |
20722 | blue, and 1 for alpha. Each component is then multiplied by the signed | |
20723 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
20724 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20725 | @code{glPixelTransfer}). | |
20726 | ||
20727 | @item @code{GL_BLUE} | |
20728 | Each element is a single blue component. The GL converts it to floating | |
20729 | point and assembles it into an RGBA element by attaching 0 for red and | |
20730 | green, and 1 for alpha. Each component is then multiplied by the signed | |
20731 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
20732 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20733 | @code{glPixelTransfer}). | |
20734 | ||
20735 | @item @code{GL_ALPHA} | |
20736 | Each element is a single alpha component. The GL converts it to floating | |
20737 | point and assembles it into an RGBA element by attaching 0 for red, | |
20738 | green, and blue. Each component is then multiplied by the signed scale | |
20739 | factor @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
20740 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20741 | ||
20742 | @item @code{GL_INTENSITY} | |
20743 | Each element is a single intensity value. The GL converts it to floating | |
20744 | point, then assembles it into an RGBA element by replicating the | |
20745 | intensity value three times for red, green, blue, and alpha. Each | |
20746 | component is then multiplied by the signed scale factor | |
20747 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
20748 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20749 | ||
20750 | @item @code{GL_RGB} | |
20751 | @item @code{GL_BGR} | |
20752 | Each element is an RGB triple. The GL converts it to floating point and | |
20753 | assembles it into an RGBA element by attaching 1 for alpha. Each | |
20754 | component is then multiplied by the signed scale factor | |
20755 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
20756 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20757 | ||
20758 | @item @code{GL_RGBA} | |
20759 | @item @code{GL_BGRA} | |
20760 | Each element contains all four components. Each component is multiplied | |
20761 | by the signed scale factor @code{GL_c_SCALE}, added to the signed bias | |
20762 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20763 | @code{glPixelTransfer}). | |
20764 | ||
20765 | @item @code{GL_LUMINANCE} | |
20766 | Each element is a single luminance value. The GL converts it to floating | |
20767 | point, then assembles it into an RGBA element by replicating the | |
20768 | luminance value three times for red, green, and blue and attaching 1 for | |
20769 | alpha. Each component is then multiplied by the signed scale factor | |
20770 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
20771 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20772 | ||
20773 | @item @code{GL_LUMINANCE_ALPHA} | |
20774 | Each element is a luminance/alpha pair. The GL converts it to floating | |
20775 | point, then assembles it into an RGBA element by replicating the | |
20776 | luminance value three times for red, green, and blue. Each component is | |
20777 | then multiplied by the signed scale factor @code{GL_c_SCALE}, added to | |
20778 | the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20779 | @code{glPixelTransfer}). | |
20780 | ||
20781 | @item @code{GL_DEPTH_COMPONENT} | |
20782 | Each element is a single depth value. The GL converts it to floating | |
20783 | point, multiplies by the signed scale factor @code{GL_DEPTH_SCALE}, adds | |
20784 | the signed bias @code{GL_DEPTH_BIAS}, and clamps to the range [0,1] (see | |
20785 | @code{glPixelTransfer}). | |
20786 | ||
20787 | @end table | |
20788 | ||
20789 | Refer to the @code{glDrawPixels} reference page for a description of the | |
20790 | acceptable values for the @var{type} parameter. | |
20791 | ||
20792 | If an application wants to store the texture at a certain resolution or | |
20793 | in a certain format, it can request the resolution and format with | |
20794 | @var{internalFormat}. The GL will choose an internal representation that | |
20795 | closely approximates that requested by @var{internalFormat}, but it may | |
20796 | not match exactly. (The representations specified by | |
20797 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and | |
20798 | @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 may | |
20799 | also be used to specify the above representations.) | |
20800 | ||
20801 | If the @var{internalFormat} parameter is one of the generic compressed | |
20802 | formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
20803 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
20804 | @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will | |
20805 | replace the internal format with the symbolic constant for a specific | |
20806 | internal format and compress the texture before storage. If no | |
20807 | corresponding internal format is available, or the GL can not compress | |
20808 | that image for any reason, the internal format is instead replaced with | |
20809 | a corresponding base internal format. | |
20810 | ||
20811 | If the @var{internalFormat} parameter is @code{GL_SRGB}, | |
20812 | @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8}, | |
20813 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
20814 | or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red, | |
20815 | green, blue, or luminance components are encoded in the sRGB color | |
20816 | space. Any alpha component is left unchanged. The conversion from the | |
3c9b6116 AW |
20817 | sRGB encoded component @r{@var{c}_@var{s}} to a linear component |
20818 | @r{@var{c}_@var{l}} is: | |
8925f36f | 20819 | |
3c9b6116 AW |
20820 | @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045), |
20821 | ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)} | |
8925f36f | 20822 | |
3c9b6116 | 20823 | Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1]. |
8925f36f AW |
20824 | |
20825 | Use the @code{GL_PROXY_TEXTURE_2D} or @code{GL_PROXY_TEXTURE_CUBE_MAP} | |
20826 | target to try out a resolution and format. The implementation will | |
20827 | update and recompute its best match for the requested storage resolution | |
20828 | and format. To then query this state, call | |
20829 | @code{glGetTexLevelParameter}. If the texture cannot be accommodated, | |
20830 | texture state is set to 0. | |
20831 | ||
20832 | A one-component texture image uses only the red component of the RGBA | |
20833 | color extracted from @var{data}. A two-component image uses the R and A | |
20834 | values. A three-component image uses the R, G, and B values. A | |
20835 | four-component image uses all of the RGBA components. | |
20836 | ||
20837 | Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA textures | |
20838 | during texture filtering and application. Image-based shadowing can be | |
20839 | enabled by comparing texture r coordinates to depth texture values to | |
20840 | generate a boolean result. See @code{glTexParameter} for details on | |
20841 | texture comparison. | |
20842 | ||
8925f36f AW |
20843 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
20844 | @code{GL_TEXTURE_2D}, @code{GL_PROXY_TEXTURE_2D}, | |
20845 | @code{GL_PROXY_TEXTURE_CUBE_MAP}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
20846 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
20847 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
20848 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
20849 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
20850 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
20851 | ||
20852 | @code{GL_INVALID_ENUM} is generated if @var{target} is one of the six | |
20853 | cube map 2D image targets and the width and height parameters are not | |
20854 | equal. | |
20855 | ||
20856 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
20857 | constant. | |
20858 | ||
20859 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
20860 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
20861 | ||
20862 | @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is | |
20863 | less than 0 or greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
20864 | ||
20865 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
20866 | ||
20867 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
20868 | @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of |
20869 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
20870 | |
20871 | @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1, | |
20872 | 2, 3, 4, or one of the accepted resolution and format symbolic | |
20873 | constants. | |
20874 | ||
20875 | @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is | |
20876 | less than 0 or greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
20877 | ||
20878 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
20879 | not supported and the @var{width} or @var{height} cannot be represented | |
3c9b6116 | 20880 | as @r{2^@var{k}+2(@var{border},)} for some integer value of @var{k}. |
8925f36f AW |
20881 | |
20882 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
20883 | ||
20884 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
20885 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
20886 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
20887 | and @var{format} is not @code{GL_RGB}. | |
20888 | ||
20889 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
20890 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
20891 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
20892 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
20893 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
20894 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
20895 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
20896 | ||
20897 | @code{GL_INVALID_OPERATION} is generated if @var{target} is not | |
20898 | @code{GL_TEXTURE_2D} or @code{GL_PROXY_TEXTURE_2D} and | |
20899 | @var{internalFormat} is @code{GL_DEPTH_COMPONENT}, | |
20900 | @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, or | |
20901 | @code{GL_DEPTH_COMPONENT32}. | |
20902 | ||
20903 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
20904 | @code{GL_DEPTH_COMPONENT} and @var{internalFormat} is not | |
20905 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
20906 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}. | |
20907 | ||
20908 | @code{GL_INVALID_OPERATION} is generated if @var{internalFormat} is | |
20909 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
20910 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}, and | |
20911 | @var{format} is not @code{GL_DEPTH_COMPONENT}. | |
20912 | ||
20913 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
20914 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
20915 | object's data store is currently mapped. | |
20916 | ||
20917 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
20918 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
20919 | would be unpacked from the buffer object such that the memory reads | |
20920 | required would exceed the data store size. | |
20921 | ||
20922 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
20923 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
20924 | is not evenly divisible into the number of bytes needed to store in | |
20925 | memory a datum indicated by @var{type}. | |
20926 | ||
20927 | @code{GL_INVALID_OPERATION} is generated if @code{glTexImage2D} is | |
20928 | executed between the execution of @code{glBegin} and the corresponding | |
20929 | execution of @code{glEnd}. | |
20930 | ||
bb894c9d | 20931 | @end deftypefun |
8925f36f | 20932 | |
bb894c9d | 20933 | @deftypefun void glTexImage3D target level internalFormat width height depth border format type data |
3c9b6116 AW |
20934 | Specify a three-dimensional texture image. |
20935 | ||
8925f36f AW |
20936 | @table @asis |
20937 | @item @var{target} | |
20938 | Specifies the target texture. Must be @code{GL_TEXTURE_3D} or | |
20939 | @code{GL_PROXY_TEXTURE_3D}. | |
20940 | ||
20941 | @item @var{level} | |
20942 | Specifies the level-of-detail number. Level 0 is the base image level. | |
3c9b6116 | 20943 | Level @r{@var{n}} is the @r{@var{n}^@var{th}} mipmap reduction image. |
8925f36f AW |
20944 | |
20945 | @item @var{internalFormat} | |
20946 | Specifies the number of color components in the texture. Must be 1, 2, | |
20947 | 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA}, | |
20948 | @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, | |
20949 | @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA}, | |
20950 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
20951 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
20952 | @code{GL_COMPRESSED_RGBA}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
20953 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
20954 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
20955 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
20956 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
20957 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY}, | |
20958 | @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12}, | |
20959 | @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
20960 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
20961 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
20962 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
20963 | @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE}, | |
20964 | @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
20965 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
20966 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
20967 | ||
20968 | @item @var{width} | |
20969 | Specifies the width of the texture image including the border if any. If | |
20970 | the GL version does not support non-power-of-two sizes, this value must | |
3c9b6116 AW |
20971 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
20972 | implementations support 3D texture images that are at least 16 texels | |
20973 | wide. | |
8925f36f AW |
20974 | |
20975 | @item @var{height} | |
20976 | Specifies the height of the texture image including the border if any. | |
20977 | If the GL version does not support non-power-of-two sizes, this value | |
3c9b6116 AW |
20978 | must be @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}. |
20979 | All implementations support 3D texture images that are at least 16 | |
20980 | texels high. | |
8925f36f AW |
20981 | |
20982 | @item @var{depth} | |
20983 | Specifies the depth of the texture image including the border if any. If | |
20984 | the GL version does not support non-power-of-two sizes, this value must | |
3c9b6116 AW |
20985 | be @r{2^@var{k}+2(@var{border},)} for some integer @r{@var{k}}. All |
20986 | implementations support 3D texture images that are at least 16 texels | |
20987 | deep. | |
8925f36f AW |
20988 | |
20989 | @item @var{border} | |
20990 | Specifies the width of the border. Must be either 0 or 1. | |
20991 | ||
20992 | @item @var{format} | |
20993 | Specifies the format of the pixel data. The following symbolic values | |
20994 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, | |
20995 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
20996 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
20997 | @code{GL_LUMINANCE_ALPHA}. | |
20998 | ||
20999 | @item @var{type} | |
21000 | Specifies the data type of the pixel data. The following symbolic values | |
21001 | are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
21002 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
21003 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
21004 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
21005 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
21006 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
21007 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
21008 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
21009 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
21010 | ||
21011 | @item @var{data} | |
21012 | Specifies a pointer to the image data in memory. | |
21013 | ||
21014 | @end table | |
21015 | ||
8925f36f AW |
21016 | Texturing maps a portion of a specified texture image onto each |
21017 | graphical primitive for which texturing is enabled. To enable and | |
21018 | disable three-dimensional texturing, call @code{glEnable} and | |
21019 | @code{glDisable} with argument @code{GL_TEXTURE_3D}. | |
21020 | ||
21021 | To define texture images, call @code{glTexImage3D}. The arguments | |
21022 | describe the parameters of the texture image, such as height, width, | |
21023 | depth, width of the border, level-of-detail number (see | |
21024 | @code{glTexParameter}), and number of color components provided. The | |
21025 | last three arguments describe how the image is represented in memory; | |
21026 | they are identical to the pixel formats used for @code{glDrawPixels}. | |
21027 | ||
21028 | If @var{target} is @code{GL_PROXY_TEXTURE_3D}, no data is read from | |
21029 | @var{data}, but all of the texture image state is recalculated, checked | |
21030 | for consistency, and checked against the implementation's capabilities. | |
21031 | If the implementation cannot handle a texture of the requested texture | |
21032 | size, it sets all of the image state to 0, but does not generate an | |
21033 | error (see @code{glGetError}). To query for an entire mipmap array, use | |
21034 | an image array level greater than or equal to 1. | |
21035 | ||
21036 | If @var{target} is @code{GL_TEXTURE_3D}, data is read from @var{data} as | |
21037 | a sequence of signed or unsigned bytes, shorts, or longs, or | |
21038 | single-precision floating-point values, depending on @var{type}. These | |
21039 | values are grouped into sets of one, two, three, or four values, | |
21040 | depending on @var{format}, to form elements. If @var{type} is | |
21041 | @code{GL_BITMAP}, the data is considered as a string of unsigned bytes | |
21042 | (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is | |
21043 | treated as eight 1-bit elements, with bit ordering determined by | |
21044 | @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}). | |
21045 | ||
21046 | If a non-zero named buffer object is bound to the | |
21047 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
21048 | texture image is specified, @var{data} is treated as a byte offset into | |
21049 | the buffer object's data store. | |
21050 | ||
21051 | The first element corresponds to the lower left corner of the texture | |
21052 | image. Subsequent elements progress left-to-right through the remaining | |
21053 | texels in the lowest row of the texture image, and then in successively | |
21054 | higher rows of the texture image. The final element corresponds to the | |
21055 | upper right corner of the texture image. | |
21056 | ||
21057 | @var{format} determines the composition of each element in @var{data}. | |
21058 | It can assume one of these symbolic values: | |
21059 | ||
21060 | @table @asis | |
21061 | @item @code{GL_COLOR_INDEX} | |
21062 | Each element is a single value, a color index. The GL converts it to | |
21063 | fixed point (with an unspecified number of zero bits to the right of the | |
21064 | binary point), shifted left or right depending on the value and sign of | |
21065 | @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see | |
21066 | @code{glPixelTransfer}). The resulting index is converted to a set of | |
21067 | color components using the @code{GL_PIXEL_MAP_I_TO_R}, | |
21068 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
21069 | @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1]. | |
21070 | ||
21071 | @item @code{GL_RED} | |
21072 | Each element is a single red component. The GL converts it to floating | |
21073 | point and assembles it into an RGBA element by attaching 0 for green and | |
21074 | blue, and 1 for alpha. Each component is then multiplied by the signed | |
21075 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
21076 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
21077 | @code{glPixelTransfer}). | |
21078 | ||
21079 | @item @code{GL_GREEN} | |
21080 | Each element is a single green component. The GL converts it to floating | |
21081 | point and assembles it into an RGBA element by attaching 0 for red and | |
21082 | blue, and 1 for alpha. Each component is then multiplied by the signed | |
21083 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
21084 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
21085 | @code{glPixelTransfer}). | |
21086 | ||
21087 | @item @code{GL_BLUE} | |
21088 | Each element is a single blue component. The GL converts it to floating | |
21089 | point and assembles it into an RGBA element by attaching 0 for red and | |
21090 | green, and 1 for alpha. Each component is then multiplied by the signed | |
21091 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
21092 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
21093 | @code{glPixelTransfer}). | |
21094 | ||
21095 | @item @code{GL_ALPHA} | |
21096 | Each element is a single alpha component. The GL converts it to floating | |
21097 | point and assembles it into an RGBA element by attaching 0 for red, | |
21098 | green, and blue. Each component is then multiplied by the signed scale | |
21099 | factor @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
21100 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
21101 | ||
21102 | @item @code{GL_INTENSITY} | |
21103 | Each element is a single intensity value. The GL converts it to floating | |
21104 | point, then assembles it into an RGBA element by replicating the | |
21105 | intensity value three times for red, green, blue, and alpha. Each | |
21106 | component is then multiplied by the signed scale factor | |
21107 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
21108 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
21109 | ||
21110 | @item @code{GL_RGB} | |
21111 | @item @code{GL_BGR} | |
21112 | Each element is an RGB triple. The GL converts it to floating point and | |
21113 | assembles it into an RGBA element by attaching 1 for alpha. Each | |
21114 | component is then multiplied by the signed scale factor | |
21115 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
21116 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
21117 | ||
21118 | @item @code{GL_RGBA} | |
21119 | @item @code{GL_BGRA} | |
21120 | Each element contains all four components. Each component is multiplied | |
21121 | by the signed scale factor @code{GL_c_SCALE}, added to the signed bias | |
21122 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
21123 | @code{glPixelTransfer}). | |
21124 | ||
21125 | @item @code{GL_LUMINANCE} | |
21126 | Each element is a single luminance value. The GL converts it to floating | |
21127 | point, then assembles it into an RGBA element by replicating the | |
21128 | luminance value three times for red, green, and blue and attaching 1 for | |
21129 | alpha. Each component is then multiplied by the signed scale factor | |
21130 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
21131 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
21132 | ||
21133 | @item @code{GL_LUMINANCE_ALPHA} | |
21134 | Each element is a luminance/alpha pair. The GL converts it to floating | |
21135 | point, then assembles it into an RGBA element by replicating the | |
21136 | luminance value three times for red, green, and blue. Each component is | |
21137 | then multiplied by the signed scale factor @code{GL_c_SCALE}, added to | |
21138 | the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
21139 | @code{glPixelTransfer}). | |
21140 | ||
21141 | @end table | |
21142 | ||
21143 | Refer to the @code{glDrawPixels} reference page for a description of the | |
21144 | acceptable values for the @var{type} parameter. | |
21145 | ||
21146 | If an application wants to store the texture at a certain resolution or | |
21147 | in a certain format, it can request the resolution and format with | |
21148 | @var{internalFormat}. The GL will choose an internal representation that | |
21149 | closely approximates that requested by @var{internalFormat}, but it may | |
21150 | not match exactly. (The representations specified by | |
21151 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and | |
21152 | @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 may | |
21153 | also be used to specify the above representations.) | |
21154 | ||
21155 | If the @var{internalFormat} parameter is one of the generic compressed | |
21156 | formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
21157 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
21158 | @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will | |
21159 | replace the internal format with the symbolic constant for a specific | |
21160 | internal format and compress the texture before storage. If no | |
21161 | corresponding internal format is available, or the GL can not compress | |
21162 | that image for any reason, the internal format is instead replaced with | |
21163 | a corresponding base internal format. | |
21164 | ||
21165 | If the @var{internalFormat} parameter is @code{GL_SRGB}, | |
21166 | @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8}, | |
21167 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
21168 | or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red, | |
21169 | green, blue, or luminance components are encoded in the sRGB color | |
21170 | space. Any alpha component is left unchanged. The conversion from the | |
3c9b6116 AW |
21171 | sRGB encoded component @r{@var{c}_@var{s}} to a linear component |
21172 | @r{@var{c}_@var{l}} is: | |
8925f36f | 21173 | |
3c9b6116 AW |
21174 | @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045), |
21175 | ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)} | |
8925f36f | 21176 | |
3c9b6116 | 21177 | Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1]. |
8925f36f AW |
21178 | |
21179 | Use the @code{GL_PROXY_TEXTURE_3D} target to try out a resolution and | |
21180 | format. The implementation will update and recompute its best match for | |
21181 | the requested storage resolution and format. To then query this state, | |
21182 | call @code{glGetTexLevelParameter}. If the texture cannot be | |
21183 | accommodated, texture state is set to 0. | |
21184 | ||
21185 | A one-component texture image uses only the red component of the RGBA | |
21186 | color extracted from @var{data}. A two-component image uses the R and A | |
21187 | values. A three-component image uses the R, G, and B values. A | |
21188 | four-component image uses all of the RGBA components. | |
21189 | ||
8925f36f AW |
21190 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
21191 | @code{GL_TEXTURE_3D} or @code{GL_PROXY_TEXTURE_3D}. | |
21192 | ||
21193 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
21194 | format constant. Format constants other than @code{GL_STENCIL_INDEX} and | |
21195 | @code{GL_DEPTH_COMPONENT} are accepted. | |
21196 | ||
21197 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
21198 | constant. | |
21199 | ||
21200 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
21201 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
21202 | ||
21203 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
21204 | ||
21205 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
21206 | @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of |
21207 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
21208 | |
21209 | @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1, | |
21210 | 2, 3, 4, or one of the accepted resolution and format symbolic | |
21211 | constants. | |
21212 | ||
21213 | @code{GL_INVALID_VALUE} is generated if @var{width}, @var{height}, or | |
21214 | @var{depth} is less than 0 or greater than 2 + | |
21215 | @code{GL_MAX_TEXTURE_SIZE}. | |
21216 | ||
21217 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
21218 | not supported and the @var{width}, @var{height}, or @var{depth} cannot | |
3c9b6116 AW |
21219 | be represented as @r{2^@var{k}+2(@var{border},)} for some integer value |
21220 | of @var{k}. | |
8925f36f AW |
21221 | |
21222 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
21223 | ||
21224 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21225 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
21226 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
21227 | and @var{format} is not @code{GL_RGB}. | |
21228 | ||
21229 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21230 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
21231 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
21232 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
21233 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
21234 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
21235 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
21236 | ||
21237 | @code{GL_INVALID_OPERATION} is generated if @var{format} or | |
21238 | @var{internalFormat} is @code{GL_DEPTH_COMPONENT}, | |
21239 | @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, or | |
21240 | @code{GL_DEPTH_COMPONENT32}. | |
21241 | ||
21242 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21243 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
21244 | object's data store is currently mapped. | |
21245 | ||
21246 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21247 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
21248 | would be unpacked from the buffer object such that the memory reads | |
21249 | required would exceed the data store size. | |
21250 | ||
21251 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21252 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
21253 | is not evenly divisible into the number of bytes needed to store in | |
21254 | memory a datum indicated by @var{type}. | |
21255 | ||
21256 | @code{GL_INVALID_OPERATION} is generated if @code{glTexImage3D} is | |
21257 | executed between the execution of @code{glBegin} and the corresponding | |
21258 | execution of @code{glEnd}. | |
21259 | ||
bb894c9d | 21260 | @end deftypefun |
8925f36f | 21261 | |
bb894c9d AW |
21262 | @deftypefun void glTexParameterf target pname param |
21263 | @deftypefunx void glTexParameteri target pname param | |
3c9b6116 AW |
21264 | Set texture parameters. |
21265 | ||
8925f36f AW |
21266 | @table @asis |
21267 | @item @var{target} | |
21268 | Specifies the target texture, which must be either @code{GL_TEXTURE_1D}, | |
21269 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, or | |
21270 | @code{GL_TEXTURE_CUBE_MAP}. | |
21271 | ||
21272 | @item @var{pname} | |
21273 | Specifies the symbolic name of a single-valued texture parameter. | |
21274 | @var{pname} can be one of the following: @code{GL_TEXTURE_MIN_FILTER}, | |
21275 | @code{GL_TEXTURE_MAG_FILTER}, @code{GL_TEXTURE_MIN_LOD}, | |
21276 | @code{GL_TEXTURE_MAX_LOD}, @code{GL_TEXTURE_BASE_LEVEL}, | |
21277 | @code{GL_TEXTURE_MAX_LEVEL}, @code{GL_TEXTURE_WRAP_S}, | |
21278 | @code{GL_TEXTURE_WRAP_T}, @code{GL_TEXTURE_WRAP_R}, | |
21279 | @code{GL_TEXTURE_PRIORITY}, @code{GL_TEXTURE_COMPARE_MODE}, | |
21280 | @code{GL_TEXTURE_COMPARE_FUNC}, @code{GL_DEPTH_TEXTURE_MODE}, or | |
21281 | @code{GL_GENERATE_MIPMAP}. | |
21282 | ||
21283 | @item @var{param} | |
21284 | Specifies the value of @var{pname}. | |
21285 | ||
21286 | @end table | |
21287 | ||
8925f36f AW |
21288 | Texture mapping is a technique that applies an image onto an object's |
21289 | surface as if the image were a decal or cellophane shrink-wrap. The | |
3c9b6116 AW |
21290 | image is created in texture space, with an (@r{@var{s}}, @r{@var{t}}) |
21291 | coordinate system. A texture is a one- or two-dimensional image and a | |
21292 | set of parameters that determine how samples are derived from the image. | |
8925f36f AW |
21293 | |
21294 | @code{glTexParameter} assigns the value or values in @var{params} to the | |
21295 | texture parameter specified as @var{pname}. @var{target} defines the | |
21296 | target texture, either @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, or | |
21297 | @code{GL_TEXTURE_3D}. The following symbols are accepted in @var{pname}: | |
21298 | ||
21299 | @table @asis | |
21300 | @item @code{GL_TEXTURE_MIN_FILTER} | |
21301 | The texture minifying function is used whenever the pixel being textured | |
21302 | maps to an area greater than one texture element. There are six defined | |
21303 | minifying functions. Two of them use the nearest one or nearest four | |
21304 | texture elements to compute the texture value. The other four use | |
21305 | mipmaps. | |
21306 | ||
21307 | A mipmap is an ordered set of arrays representing the same image at | |
21308 | progressively lower resolutions. If the texture has dimensions | |
3c9b6116 AW |
21309 | @r{2^@var{n}×2^@var{m}}, there are @r{@var{max}(@var{n},@var{m})+1} |
21310 | mipmaps. The first mipmap is the original texture, with dimensions | |
21311 | @r{2^@var{n}×2^@var{m}}. Each subsequent mipmap has dimensions | |
21312 | @r{2^@var{k}-1,×2^@var{l}-1,}, where @r{2^@var{k}×2^@var{l}} are the | |
21313 | dimensions of the previous mipmap, until either @r{@var{k}=0} or | |
21314 | @r{@var{l}=0}. At that point, subsequent mipmaps have dimension | |
21315 | @r{1×2^@var{l}-1,} or @r{2^@var{k}-1,×1} until the final mipmap, which | |
21316 | has dimension @r{1×1}. To define the mipmaps, call @code{glTexImage1D}, | |
8925f36f AW |
21317 | @code{glTexImage2D}, @code{glTexImage3D}, @code{glCopyTexImage1D}, or |
21318 | @code{glCopyTexImage2D} with the @var{level} argument indicating the | |
21319 | order of the mipmaps. Level 0 is the original texture; level | |
3c9b6116 | 21320 | @r{@var{max}(@var{n},@var{m})} is the final @r{1×1} mipmap. |
8925f36f AW |
21321 | |
21322 | @var{params} supplies a function for minifying the texture as one of the | |
21323 | following: | |
21324 | ||
21325 | As more texture elements are sampled in the minification process, fewer | |
21326 | aliasing artifacts will be apparent. While the @code{GL_NEAREST} and | |
21327 | @code{GL_LINEAR} minification functions can be faster than the other | |
21328 | four, they sample only one or four texture elements to determine the | |
21329 | texture value of the pixel being rendered and can produce moire patterns | |
21330 | or ragged transitions. The initial value of @code{GL_TEXTURE_MIN_FILTER} | |
21331 | is @code{GL_NEAREST_MIPMAP_LINEAR}. | |
21332 | ||
21333 | @item @code{GL_TEXTURE_MAG_FILTER} | |
21334 | The texture magnification function is used when the pixel being textured | |
21335 | maps to an area less than or equal to one texture element. It sets the | |
21336 | texture magnification function to either @code{GL_NEAREST} or | |
21337 | @code{GL_LINEAR} (see below). @code{GL_NEAREST} is generally faster than | |
21338 | @code{GL_LINEAR}, but it can produce textured images with sharper edges | |
21339 | because the transition between texture elements is not as smooth. The | |
21340 | initial value of @code{GL_TEXTURE_MAG_FILTER} is @code{GL_LINEAR}. | |
21341 | ||
21342 | @end table | |
21343 | ||
21344 | @table @asis | |
21345 | @item @code{GL_NEAREST} | |
21346 | Returns the value of the texture element that is nearest (in Manhattan | |
21347 | distance) to the center of the pixel being textured. | |
21348 | ||
21349 | @item @code{GL_LINEAR} | |
21350 | Returns the weighted average of the four texture elements that are | |
21351 | closest to the center of the pixel being textured. These can include | |
21352 | border texture elements, depending on the values of | |
21353 | @code{GL_TEXTURE_WRAP_S} and @code{GL_TEXTURE_WRAP_T}, and on the exact | |
21354 | mapping. | |
21355 | ||
21356 | @item @code{GL_NEAREST_MIPMAP_NEAREST} | |
21357 | Chooses the mipmap that most closely matches the size of the pixel being | |
21358 | textured and uses the @code{GL_NEAREST} criterion (the texture element | |
21359 | nearest to the center of the pixel) to produce a texture value. | |
21360 | ||
21361 | @item @code{GL_LINEAR_MIPMAP_NEAREST} | |
21362 | Chooses the mipmap that most closely matches the size of the pixel being | |
21363 | textured and uses the @code{GL_LINEAR} criterion (a weighted average of | |
21364 | the four texture elements that are closest to the center of the pixel) | |
21365 | to produce a texture value. | |
21366 | ||
21367 | @item @code{GL_NEAREST_MIPMAP_LINEAR} | |
21368 | Chooses the two mipmaps that most closely match the size of the pixel | |
21369 | being textured and uses the @code{GL_NEAREST} criterion (the texture | |
21370 | element nearest to the center of the pixel) to produce a texture value | |
21371 | from each mipmap. The final texture value is a weighted average of those | |
21372 | two values. | |
21373 | ||
21374 | @item @code{GL_LINEAR_MIPMAP_LINEAR} | |
21375 | Chooses the two mipmaps that most closely match the size of the pixel | |
21376 | being textured and uses the @code{GL_LINEAR} criterion (a weighted | |
21377 | average of the four texture elements that are closest to the center of | |
21378 | the pixel) to produce a texture value from each mipmap. The final | |
21379 | texture value is a weighted average of those two values. | |
21380 | ||
21381 | @end table | |
21382 | ||
21383 | @table @asis | |
21384 | @item @code{GL_NEAREST} | |
21385 | Returns the value of the texture element that is nearest (in Manhattan | |
21386 | distance) to the center of the pixel being textured. | |
21387 | ||
21388 | @item @code{GL_LINEAR} | |
21389 | Returns the weighted average of the four texture elements that are | |
21390 | closest to the center of the pixel being textured. These can include | |
21391 | border texture elements, depending on the values of | |
21392 | @code{GL_TEXTURE_WRAP_S} and @code{GL_TEXTURE_WRAP_T}, and on the exact | |
21393 | mapping. | |
21394 | ||
21395 | @end table | |
21396 | ||
21397 | ||
21398 | ||
21399 | @table @asis | |
21400 | @item @code{GL_TEXTURE_MIN_LOD} | |
21401 | Sets the minimum level-of-detail parameter. This floating-point value | |
21402 | limits the selection of highest resolution mipmap (lowest mipmap level). | |
21403 | The initial value is -1000. | |
21404 | ||
21405 | @end table | |
21406 | ||
21407 | ||
21408 | ||
21409 | @table @asis | |
21410 | @item @code{GL_TEXTURE_MAX_LOD} | |
21411 | Sets the maximum level-of-detail parameter. This floating-point value | |
21412 | limits the selection of the lowest resolution mipmap (highest mipmap | |
21413 | level). The initial value is 1000. | |
21414 | ||
21415 | @end table | |
21416 | ||
21417 | ||
21418 | ||
21419 | @table @asis | |
21420 | @item @code{GL_TEXTURE_BASE_LEVEL} | |
21421 | Specifies the index of the lowest defined mipmap level. This is an | |
21422 | integer value. The initial value is 0. | |
21423 | ||
21424 | @end table | |
21425 | ||
21426 | ||
21427 | ||
21428 | @table @asis | |
21429 | @item @code{GL_TEXTURE_MAX_LEVEL} | |
21430 | Sets the index of the highest defined mipmap level. This is an integer | |
21431 | value. The initial value is 1000. | |
21432 | ||
21433 | @end table | |
21434 | ||
21435 | ||
21436 | ||
21437 | @table @asis | |
21438 | @item @code{GL_TEXTURE_WRAP_S} | |
3c9b6116 | 21439 | Sets the wrap parameter for texture coordinate @r{@var{s}} to either |
8925f36f AW |
21440 | @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE}, |
21441 | @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. @code{GL_CLAMP} causes | |
3c9b6116 AW |
21442 | @r{@var{s}} coordinates to be clamped to the range [0,1] and is useful |
21443 | for preventing wrapping artifacts when mapping a single image onto an | |
21444 | object. @code{GL_CLAMP_TO_BORDER} causes the @r{@var{s}} coordinate to | |
21445 | be clamped to the range @r{[-1/2@var{N},,1+1/2@var{N},]}, where | |
21446 | @r{@var{N}} is the size of the texture in the direction of | |
21447 | clamping.@code{GL_CLAMP_TO_EDGE} causes @r{@var{s}} coordinates to be | |
21448 | clamped to the range @r{[1/2@var{N},,1-1/2@var{N},]}, where @r{@var{N}} | |
21449 | is the size of the texture in the direction of clamping. | |
21450 | @code{GL_REPEAT} causes the integer part of the @r{@var{s}} coordinate | |
21451 | to be ignored; the GL uses only the fractional part, thereby creating a | |
21452 | repeating pattern. @code{GL_MIRRORED_REPEAT} causes the @r{@var{s}} | |
21453 | coordinate to be set to the fractional part of the texture coordinate if | |
21454 | the integer part of @r{@var{s}} is even; if the integer part of | |
21455 | @r{@var{s}} is odd, then the @r{@var{s}} texture coordinate is set to | |
21456 | @r{1-@var{frac}(@var{s},)}, where @r{@var{frac}(@var{s},)} represents | |
21457 | the fractional part of @r{@var{s}}. Border texture elements are accessed | |
21458 | only if wrapping is set to @code{GL_CLAMP} or @code{GL_CLAMP_TO_BORDER}. | |
21459 | Initially, @code{GL_TEXTURE_WRAP_S} is set to @code{GL_REPEAT}. | |
8925f36f AW |
21460 | |
21461 | @end table | |
21462 | ||
21463 | ||
21464 | ||
21465 | @table @asis | |
21466 | @item @code{GL_TEXTURE_WRAP_T} | |
3c9b6116 | 21467 | Sets the wrap parameter for texture coordinate @r{@var{t}} to either |
8925f36f AW |
21468 | @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE}, |
21469 | @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. See the discussion under | |
21470 | @code{GL_TEXTURE_WRAP_S}. Initially, @code{GL_TEXTURE_WRAP_T} is set to | |
21471 | @code{GL_REPEAT}. | |
21472 | ||
21473 | @item @code{GL_TEXTURE_WRAP_R} | |
3c9b6116 | 21474 | Sets the wrap parameter for texture coordinate @r{@var{r}} to either |
8925f36f AW |
21475 | @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE}, |
21476 | @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. See the discussion under | |
21477 | @code{GL_TEXTURE_WRAP_S}. Initially, @code{GL_TEXTURE_WRAP_R} is set to | |
21478 | @code{GL_REPEAT}. | |
21479 | ||
21480 | @item @code{GL_TEXTURE_BORDER_COLOR} | |
21481 | Sets a border color. @var{params} contains four values that comprise the | |
21482 | RGBA color of the texture border. Integer color components are | |
21483 | interpreted linearly such that the most positive integer maps to 1.0, | |
21484 | and the most negative integer maps to -1.0. The values are clamped to | |
21485 | the range [0,1] when they are specified. Initially, the border color is | |
21486 | (0, 0, 0, 0). | |
21487 | ||
21488 | @item @code{GL_TEXTURE_PRIORITY} | |
21489 | Specifies the texture residence priority of the currently bound texture. | |
3c9b6116 | 21490 | Permissible values are in the range @r{[0,1]}. See |
8925f36f AW |
21491 | @code{glPrioritizeTextures} and @code{glBindTexture} for more |
21492 | information. | |
21493 | ||
21494 | @item @code{GL_TEXTURE_COMPARE_MODE} | |
21495 | Specifies the texture comparison mode for currently bound depth | |
21496 | textures. That is, a texture whose internal format is | |
21497 | @code{GL_DEPTH_COMPONENT_*}; see @code{glTexImage2D}) Permissible values | |
21498 | are: | |
21499 | ||
21500 | @item @code{GL_TEXTURE_COMPARE_FUNC} | |
21501 | Specifies the comparison operator used when | |
21502 | @code{GL_TEXTURE_COMPARE_MODE} is set to @code{GL_COMPARE_R_TO_TEXTURE}. | |
3c9b6116 AW |
21503 | Permissible values are: where @r{@var{r}} is the current interpolated |
21504 | texture coordinate, and @r{@var{D}_@var{t}} is the depth texture value | |
21505 | sampled from the currently bound depth texture. @r{@var{result}} is | |
21506 | assigned to the either the luminance, intensity, or alpha (as specified | |
21507 | by @code{GL_DEPTH_TEXTURE_MODE}.) | |
8925f36f AW |
21508 | |
21509 | @item @code{GL_DEPTH_TEXTURE_MODE} | |
21510 | Specifies a single symbolic constant indicating how depth values should | |
21511 | be treated during filtering and texture application. Accepted values are | |
21512 | @code{GL_LUMINANCE}, @code{GL_INTENSITY}, and @code{GL_ALPHA}. The | |
21513 | initial value is @code{GL_LUMINANCE}. | |
21514 | ||
21515 | @item @code{GL_GENERATE_MIPMAP} | |
21516 | Specifies a boolean value that indicates if all levels of a mipmap array | |
21517 | should be automatically updated when any modification to the base level | |
21518 | mipmap is done. The initial value is @code{GL_FALSE}. | |
21519 | ||
21520 | @end table | |
21521 | ||
21522 | @table @asis | |
21523 | @item @code{GL_COMPARE_R_TO_TEXTURE} | |
3c9b6116 | 21524 | Specifies that the interpolated and clamped @r{@var{r}} texture |
8925f36f AW |
21525 | coordinate should be compared to the value in the currently bound depth |
21526 | texture. See the discussion of @code{GL_TEXTURE_COMPARE_FUNC} for | |
21527 | details of how the comparison is evaluated. The result of the comparison | |
21528 | is assigned to luminance, intensity, or alpha (as specified by | |
21529 | @code{GL_DEPTH_TEXTURE_MODE}). | |
21530 | ||
21531 | @item @code{GL_NONE} | |
21532 | Specifies that the luminance, intensity, or alpha (as specified by | |
21533 | @code{GL_DEPTH_TEXTURE_MODE}) should be assigned the appropriate value | |
21534 | from the currently bound depth texture. | |
21535 | ||
21536 | @end table | |
21537 | ||
21538 | @table @asis | |
21539 | @item @strong{Texture Comparison Function} | |
21540 | @strong{Computed result} | |
21541 | ||
21542 | @item @code{GL_LEQUAL} | |
3c9b6116 | 21543 | @r{@var{result}=@{(1.0), (0.0) (@var{r}<=@var{D}_@var{t},), |
8925f36f AW |
21544 | (@var{r}>@var{D}_@var{t},),} |
21545 | ||
21546 | @item @code{GL_GEQUAL} | |
3c9b6116 | 21547 | @r{@var{result}=@{(1.0), (0.0) (@var{r}>=@var{D}_@var{t},), |
8925f36f AW |
21548 | (@var{r}<@var{D}_@var{t},),} |
21549 | ||
21550 | @item @code{GL_LESS} | |
3c9b6116 | 21551 | @r{@var{result}=@{(1.0), (0.0) (@var{r}<@var{D}_@var{t},), |
8925f36f AW |
21552 | (@var{r}>=@var{D}_@var{t},),} |
21553 | ||
21554 | @item @code{GL_GREATER} | |
3c9b6116 | 21555 | @r{@var{result}=@{(1.0), (0.0) (@var{r}>@var{D}_@var{t},), |
8925f36f AW |
21556 | (@var{r}<=@var{D}_@var{t},),} |
21557 | ||
21558 | @item @code{GL_EQUAL} | |
3c9b6116 | 21559 | @r{@var{result}=@{(1.0), (0.0) (@var{r}=@var{D}_@var{t},), |
8925f36f AW |
21560 | (@var{r}≠@var{D}_@var{t},),} |
21561 | ||
21562 | @item @code{GL_NOTEQUAL} | |
3c9b6116 | 21563 | @r{@var{result}=@{(1.0), (0.0) (@var{r}≠@var{D}_@var{t},), |
8925f36f AW |
21564 | (@var{r}=@var{D}_@var{t},),} |
21565 | ||
21566 | @item @code{GL_ALWAYS} | |
3c9b6116 | 21567 | @r{@var{result}=@code{1.0}} |
8925f36f AW |
21568 | |
21569 | @item @code{GL_NEVER} | |
3c9b6116 | 21570 | @r{@var{result}=@code{0.0}} |
8925f36f AW |
21571 | |
21572 | @end table | |
21573 | ||
8925f36f AW |
21574 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is |
21575 | not one of the accepted defined values. | |
21576 | ||
21577 | @code{GL_INVALID_ENUM} is generated if @var{params} should have a | |
21578 | defined constant value (based on the value of @var{pname}) and does not. | |
21579 | ||
21580 | @code{GL_INVALID_OPERATION} is generated if @code{glTexParameter} is | |
21581 | executed between the execution of @code{glBegin} and the corresponding | |
21582 | execution of @code{glEnd}. | |
21583 | ||
bb894c9d | 21584 | @end deftypefun |
8925f36f | 21585 | |
bb894c9d | 21586 | @deftypefun void glTexSubImage1D target level xoffset width format type data |
3c9b6116 AW |
21587 | Specify a one-dimensional texture subimage. |
21588 | ||
8925f36f AW |
21589 | @table @asis |
21590 | @item @var{target} | |
21591 | Specifies the target texture. Must be @code{GL_TEXTURE_1D}. | |
21592 | ||
21593 | @item @var{level} | |
21594 | Specifies the level-of-detail number. Level 0 is the base image level. | |
21595 | Level @var{n} is the @var{n}th mipmap reduction image. | |
21596 | ||
21597 | @item @var{xoffset} | |
21598 | Specifies a texel offset in the x direction within the texture array. | |
21599 | ||
21600 | @item @var{width} | |
21601 | Specifies the width of the texture subimage. | |
21602 | ||
21603 | @item @var{format} | |
21604 | Specifies the format of the pixel data. The following symbolic values | |
21605 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, | |
21606 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
21607 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
21608 | @code{GL_LUMINANCE_ALPHA}. | |
21609 | ||
21610 | @item @var{type} | |
21611 | Specifies the data type of the pixel data. The following symbolic values | |
21612 | are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
21613 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
21614 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
21615 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
21616 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
21617 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
21618 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
21619 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
21620 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
21621 | ||
21622 | @item @var{data} | |
21623 | Specifies a pointer to the image data in memory. | |
21624 | ||
21625 | @end table | |
21626 | ||
8925f36f AW |
21627 | Texturing maps a portion of a specified texture image onto each |
21628 | graphical primitive for which texturing is enabled. To enable or disable | |
21629 | one-dimensional texturing, call @code{glEnable} and @code{glDisable} | |
21630 | with argument @code{GL_TEXTURE_1D}. | |
21631 | ||
21632 | @code{glTexSubImage1D} redefines a contiguous subregion of an existing | |
21633 | one-dimensional texture image. The texels referenced by @var{data} | |
21634 | replace the portion of the existing texture array with x indices | |
3c9b6116 | 21635 | @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive. This |
8925f36f AW |
21636 | region may not include any texels outside the range of the texture array |
21637 | as it was originally specified. It is not an error to specify a | |
21638 | subtexture with width of 0, but such a specification has no effect. | |
21639 | ||
21640 | If a non-zero named buffer object is bound to the | |
21641 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
21642 | texture image is specified, @var{data} is treated as a byte offset into | |
21643 | the buffer object's data store. | |
21644 | ||
8925f36f AW |
21645 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
21646 | allowable values. | |
21647 | ||
21648 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
21649 | format constant. | |
21650 | ||
21651 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
21652 | constant. | |
21653 | ||
21654 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
21655 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
21656 | ||
21657 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
21658 | ||
21659 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 | 21660 | @r{@var{log}_2}@var{max}, where @var{max} is the returned value of |
8925f36f AW |
21661 | @code{GL_MAX_TEXTURE_SIZE}. |
21662 | ||
3c9b6116 AW |
21663 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, or |
21664 | if @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, where | |
21665 | @r{@var{w}} is the @code{GL_TEXTURE_WIDTH}, and @r{@var{b}} is the width | |
21666 | of the @code{GL_TEXTURE_BORDER} of the texture image being modified. | |
21667 | Note that @r{@var{w}} includes twice the border width. | |
8925f36f AW |
21668 | |
21669 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0. | |
21670 | ||
21671 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
21672 | been defined by a previous @code{glTexImage1D} operation. | |
21673 | ||
21674 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21675 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
21676 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
21677 | and @var{format} is not @code{GL_RGB}. | |
21678 | ||
21679 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21680 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
21681 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
21682 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
21683 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
21684 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
21685 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
21686 | ||
21687 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21688 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
21689 | object's data store is currently mapped. | |
21690 | ||
21691 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21692 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
21693 | would be unpacked from the buffer object such that the memory reads | |
21694 | required would exceed the data store size. | |
21695 | ||
21696 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21697 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
21698 | is not evenly divisible into the number of bytes needed to store in | |
21699 | memory a datum indicated by @var{type}. | |
21700 | ||
21701 | @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage1D} is | |
21702 | executed between the execution of @code{glBegin} and the corresponding | |
21703 | execution of @code{glEnd}. | |
21704 | ||
bb894c9d | 21705 | @end deftypefun |
8925f36f | 21706 | |
bb894c9d | 21707 | @deftypefun void glTexSubImage2D target level xoffset yoffset width height format type data |
3c9b6116 AW |
21708 | Specify a two-dimensional texture subimage. |
21709 | ||
8925f36f AW |
21710 | @table @asis |
21711 | @item @var{target} | |
21712 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, | |
21713 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
21714 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
21715 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
21716 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
21717 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
21718 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
21719 | ||
21720 | @item @var{level} | |
21721 | Specifies the level-of-detail number. Level 0 is the base image level. | |
21722 | Level @var{n} is the @var{n}th mipmap reduction image. | |
21723 | ||
21724 | @item @var{xoffset} | |
21725 | Specifies a texel offset in the x direction within the texture array. | |
21726 | ||
21727 | @item @var{yoffset} | |
21728 | Specifies a texel offset in the y direction within the texture array. | |
21729 | ||
21730 | @item @var{width} | |
21731 | Specifies the width of the texture subimage. | |
21732 | ||
21733 | @item @var{height} | |
21734 | Specifies the height of the texture subimage. | |
21735 | ||
21736 | @item @var{format} | |
21737 | Specifies the format of the pixel data. The following symbolic values | |
21738 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, | |
21739 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
21740 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
21741 | @code{GL_LUMINANCE_ALPHA}. | |
21742 | ||
21743 | @item @var{type} | |
21744 | Specifies the data type of the pixel data. The following symbolic values | |
21745 | are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
21746 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
21747 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
21748 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
21749 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
21750 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
21751 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
21752 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
21753 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
21754 | ||
21755 | @item @var{data} | |
21756 | Specifies a pointer to the image data in memory. | |
21757 | ||
21758 | @end table | |
21759 | ||
8925f36f AW |
21760 | Texturing maps a portion of a specified texture image onto each |
21761 | graphical primitive for which texturing is enabled. To enable and | |
21762 | disable two-dimensional texturing, call @code{glEnable} and | |
21763 | @code{glDisable} with argument @code{GL_TEXTURE_2D}. | |
21764 | ||
21765 | @code{glTexSubImage2D} redefines a contiguous subregion of an existing | |
21766 | two-dimensional texture image. The texels referenced by @var{data} | |
21767 | replace the portion of the existing texture array with x indices | |
3c9b6116 AW |
21768 | @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive, and y |
21769 | indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive. | |
21770 | This region may not include any texels outside the range of the texture | |
21771 | array as it was originally specified. It is not an error to specify a | |
21772 | subtexture with zero width or height, but such a specification has no | |
21773 | effect. | |
8925f36f AW |
21774 | |
21775 | If a non-zero named buffer object is bound to the | |
21776 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
21777 | texture image is specified, @var{data} is treated as a byte offset into | |
21778 | the buffer object's data store. | |
21779 | ||
8925f36f AW |
21780 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
21781 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
21782 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
21783 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
21784 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
21785 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
21786 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
21787 | ||
21788 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
21789 | format constant. | |
21790 | ||
21791 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
21792 | constant. | |
21793 | ||
21794 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
21795 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
21796 | ||
21797 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
21798 | ||
21799 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 | 21800 | @r{@var{log}_2}@var{max}, where @var{max} is the returned value of |
8925f36f AW |
21801 | @code{GL_MAX_TEXTURE_SIZE}. |
21802 | ||
3c9b6116 AW |
21803 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, |
21804 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, | |
21805 | @r{@var{yoffset}<-@var{b}}, or | |
21806 | @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, where @r{@var{w}} | |
21807 | is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the | |
21808 | @code{GL_TEXTURE_HEIGHT}, and @r{@var{b}} is the border width of the | |
21809 | texture image being modified. Note that @r{@var{w}} and @r{@var{h}} | |
21810 | include twice the border width. | |
8925f36f AW |
21811 | |
21812 | @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is | |
21813 | less than 0. | |
21814 | ||
21815 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
21816 | been defined by a previous @code{glTexImage2D} operation. | |
21817 | ||
21818 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21819 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
21820 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
21821 | and @var{format} is not @code{GL_RGB}. | |
21822 | ||
21823 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21824 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
21825 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
21826 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
21827 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
21828 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
21829 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
21830 | ||
21831 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21832 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
21833 | object's data store is currently mapped. | |
21834 | ||
21835 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21836 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
21837 | would be unpacked from the buffer object such that the memory reads | |
21838 | required would exceed the data store size. | |
21839 | ||
21840 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21841 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
21842 | is not evenly divisible into the number of bytes needed to store in | |
21843 | memory a datum indicated by @var{type}. | |
21844 | ||
21845 | @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage2D} is | |
21846 | executed between the execution of @code{glBegin} and the corresponding | |
21847 | execution of @code{glEnd}. | |
21848 | ||
bb894c9d | 21849 | @end deftypefun |
8925f36f | 21850 | |
bb894c9d | 21851 | @deftypefun void glTexSubImage3D target level xoffset yoffset zoffset width height depth format type data |
3c9b6116 AW |
21852 | Specify a three-dimensional texture subimage. |
21853 | ||
8925f36f AW |
21854 | @table @asis |
21855 | @item @var{target} | |
21856 | Specifies the target texture. Must be @code{GL_TEXTURE_3D}. | |
21857 | ||
21858 | @item @var{level} | |
21859 | Specifies the level-of-detail number. Level 0 is the base image level. | |
21860 | Level @var{n} is the @var{n}th mipmap reduction image. | |
21861 | ||
21862 | @item @var{xoffset} | |
21863 | Specifies a texel offset in the x direction within the texture array. | |
21864 | ||
21865 | @item @var{yoffset} | |
21866 | Specifies a texel offset in the y direction within the texture array. | |
21867 | ||
21868 | @item @var{zoffset} | |
21869 | Specifies a texel offset in the z direction within the texture array. | |
21870 | ||
21871 | @item @var{width} | |
21872 | Specifies the width of the texture subimage. | |
21873 | ||
21874 | @item @var{height} | |
21875 | Specifies the height of the texture subimage. | |
21876 | ||
21877 | @item @var{depth} | |
21878 | Specifies the depth of the texture subimage. | |
21879 | ||
21880 | @item @var{format} | |
21881 | Specifies the format of the pixel data. The following symbolic values | |
21882 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, | |
21883 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
21884 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
21885 | @code{GL_LUMINANCE_ALPHA}. | |
21886 | ||
21887 | @item @var{type} | |
21888 | Specifies the data type of the pixel data. The following symbolic values | |
21889 | are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
21890 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
21891 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
21892 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
21893 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
21894 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
21895 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
21896 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
21897 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
21898 | ||
21899 | @item @var{data} | |
21900 | Specifies a pointer to the image data in memory. | |
21901 | ||
21902 | @end table | |
21903 | ||
8925f36f AW |
21904 | Texturing maps a portion of a specified texture image onto each |
21905 | graphical primitive for which texturing is enabled. To enable and | |
21906 | disable three-dimensional texturing, call @code{glEnable} and | |
21907 | @code{glDisable} with argument @code{GL_TEXTURE_3D}. | |
21908 | ||
21909 | @code{glTexSubImage3D} redefines a contiguous subregion of an existing | |
21910 | three-dimensional texture image. The texels referenced by @var{data} | |
21911 | replace the portion of the existing texture array with x indices | |
3c9b6116 AW |
21912 | @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive, y indices |
21913 | @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive, and z | |
21914 | indices @var{zoffset} and @r{@var{zoffset}+@var{depth}-1}, inclusive. | |
21915 | This region may not include any texels outside the range of the texture | |
21916 | array as it was originally specified. It is not an error to specify a | |
21917 | subtexture with zero width, height, or depth but such a specification | |
21918 | has no effect. | |
8925f36f AW |
21919 | |
21920 | If a non-zero named buffer object is bound to the | |
21921 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
21922 | texture image is specified, @var{data} is treated as a byte offset into | |
21923 | the buffer object's data store. | |
21924 | ||
8925f36f AW |
21925 | @code{GL_INVALID_ENUM} is generated if /@var{target} is not |
21926 | @code{GL_TEXTURE_3D}. | |
21927 | ||
21928 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
21929 | format constant. | |
21930 | ||
21931 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
21932 | constant. | |
21933 | ||
21934 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
21935 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
21936 | ||
21937 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
21938 | ||
21939 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 | 21940 | @r{@var{log}_2}@var{max}, where @var{max} is the returned value of |
8925f36f AW |
21941 | @code{GL_MAX_TEXTURE_SIZE}. |
21942 | ||
3c9b6116 AW |
21943 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, |
21944 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, | |
21945 | @r{@var{yoffset}<-@var{b}}, or | |
21946 | @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, or | |
21947 | @r{@var{zoffset}<-@var{b}}, or | |
21948 | @r{(@var{zoffset}+@var{depth},)>(@var{d}-@var{b},)}, where @r{@var{w}} | |
21949 | is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the | |
21950 | @code{GL_TEXTURE_HEIGHT}, @r{@var{d}} is the @code{GL_TEXTURE_DEPTH} and | |
21951 | @r{@var{b}} is the border width of the texture image being modified. | |
21952 | Note that @r{@var{w}}, @r{@var{h}}, and @r{@var{d}} include twice the | |
21953 | border width. | |
8925f36f AW |
21954 | |
21955 | @code{GL_INVALID_VALUE} is generated if @var{width}, @var{height}, or | |
21956 | @var{depth} is less than 0. | |
21957 | ||
21958 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
21959 | been defined by a previous @code{glTexImage3D} operation. | |
21960 | ||
21961 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21962 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
21963 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
21964 | and @var{format} is not @code{GL_RGB}. | |
21965 | ||
21966 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21967 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
21968 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
21969 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
21970 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
21971 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
21972 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
21973 | ||
21974 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21975 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
21976 | object's data store is currently mapped. | |
21977 | ||
21978 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21979 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
21980 | would be unpacked from the buffer object such that the memory reads | |
21981 | required would exceed the data store size. | |
21982 | ||
21983 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21984 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
21985 | is not evenly divisible into the number of bytes needed to store in | |
21986 | memory a datum indicated by @var{type}. | |
21987 | ||
21988 | @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage3D} is | |
21989 | executed between the execution of @code{glBegin} and the corresponding | |
21990 | execution of @code{glEnd}. | |
21991 | ||
bb894c9d | 21992 | @end deftypefun |
8925f36f | 21993 | |
ca09631c | 21994 | @deftypefun void glTranslatef x y z |
3c9b6116 AW |
21995 | Multiply the current matrix by a translation matrix. |
21996 | ||
8925f36f AW |
21997 | @table @asis |
21998 | @item @var{x} | |
21999 | @itemx @var{y} | |
22000 | @itemx @var{z} | |
22001 | Specify the @var{x}, @var{y}, and @var{z} coordinates of a translation | |
22002 | vector. | |
22003 | ||
22004 | @end table | |
22005 | ||
8925f36f | 22006 | @code{glTranslate} produces a translation by |
3c9b6116 | 22007 | @r{(@var{x},@var{y}@var{z})}. The current matrix (see |
8925f36f AW |
22008 | @code{glMatrixMode}) is multiplied by this translation matrix, with the |
22009 | product replacing the current matrix, as if @code{glMultMatrix} were | |
22010 | called with the following matrix for its argument: | |
22011 | ||
3c9b6116 | 22012 | @r{((1 0 0 @var{x}), (0 1 0 @var{y}), (0 0 1 @var{z}), (0 0 0 1),)} |
8925f36f AW |
22013 | |
22014 | ||
22015 | ||
22016 | If the matrix mode is either @code{GL_MODELVIEW} or | |
22017 | @code{GL_PROJECTION}, all objects drawn after a call to | |
22018 | @code{glTranslate} are translated. | |
22019 | ||
22020 | Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the | |
22021 | untranslated coordinate system. | |
22022 | ||
8925f36f AW |
22023 | @code{GL_INVALID_OPERATION} is generated if @code{glTranslate} is |
22024 | executed between the execution of @code{glBegin} and the corresponding | |
22025 | execution of @code{glEnd}. | |
22026 | ||
bb894c9d | 22027 | @end deftypefun |
8925f36f | 22028 | |
bb894c9d AW |
22029 | @deftypefun void glUniform1f location v0 |
22030 | @deftypefunx void glUniform2f location v0 v1 | |
22031 | @deftypefunx void glUniform3f location v0 v1 v2 | |
22032 | @deftypefunx void glUniform4f location v0 v1 v2 v3 | |
22033 | @deftypefunx void glUniform1i location v0 | |
22034 | @deftypefunx void glUniform2i location v0 v1 | |
22035 | @deftypefunx void glUniform3i location v0 v1 v2 | |
22036 | @deftypefunx void glUniform4i location v0 v1 v2 v3 | |
b002944d AW |
22037 | @deftypefunx void glUniformMatrix2fv location count transpose value |
22038 | @deftypefunx void glUniformMatrix3fv location count transpose value | |
22039 | @deftypefunx void glUniformMatrix4fv location count transpose value | |
22040 | @deftypefunx void glUniformMatrix2x3fv location count transpose value | |
22041 | @deftypefunx void glUniformMatrix3x2fv location count transpose value | |
22042 | @deftypefunx void glUniformMatrix2x4fv location count transpose value | |
22043 | @deftypefunx void glUniformMatrix4x2fv location count transpose value | |
22044 | @deftypefunx void glUniformMatrix3x4fv location count transpose value | |
22045 | @deftypefunx void glUniformMatrix4x3fv location count transpose value | |
3c9b6116 AW |
22046 | Specify the value of a uniform variable for the current program object. |
22047 | ||
8925f36f AW |
22048 | @table @asis |
22049 | @item @var{location} | |
22050 | Specifies the location of the uniform variable to be modified. | |
22051 | ||
22052 | @item @var{v0}, @var{v1}, @var{v2}, @var{v3} | |
22053 | Specifies the new values to be used for the specified uniform variable. | |
22054 | ||
22055 | @end table | |
22056 | ||
8925f36f AW |
22057 | @code{glUniform} modifies the value of a uniform variable or a uniform |
22058 | variable array. The location of the uniform variable to be modified is | |
22059 | specified by @var{location}, which should be a value returned by | |
22060 | @code{glGetUniformLocation}. @code{glUniform} operates on the program | |
22061 | object that was made part of current state by calling | |
22062 | @code{glUseProgram}. | |
22063 | ||
22064 | The commands @code{glUniform@{1|2|3|4@}@{f|i@}} are used to change the | |
22065 | value of the uniform variable specified by @var{location} using the | |
22066 | values passed as arguments. The number specified in the command should | |
22067 | match the number of components in the data type of the specified uniform | |
22068 | variable (e.g., @code{1} for float, int, bool; @code{2} for vec2, ivec2, | |
22069 | bvec2, etc.). The suffix @code{f} indicates that floating-point values | |
22070 | are being passed; the suffix @code{i} indicates that integer values are | |
22071 | being passed, and this type should also match the data type of the | |
22072 | specified uniform variable. The @code{i} variants of this function | |
22073 | should be used to provide values for uniform variables defined as int, | |
22074 | ivec2, ivec3, ivec4, or arrays of these. The @code{f} variants should be | |
22075 | used to provide values for uniform variables of type float, vec2, vec3, | |
22076 | vec4, or arrays of these. Either the @code{i} or the @code{f} variants | |
22077 | may be used to provide values for uniform variables of type bool, bvec2, | |
22078 | bvec3, bvec4, or arrays of these. The uniform variable will be set to | |
22079 | false if the input value is 0 or 0.0f, and it will be set to true | |
22080 | otherwise. | |
22081 | ||
22082 | All active uniform variables defined in a program object are initialized | |
22083 | to 0 when the program object is linked successfully. They retain the | |
22084 | values assigned to them by a call to @code{glUniform } until the next | |
22085 | successful link operation occurs on the program object, when they are | |
22086 | once again initialized to 0. | |
22087 | ||
22088 | The commands @code{glUniform@{1|2|3|4@}@{f|i@}v} can be used to modify a | |
22089 | single uniform variable or a uniform variable array. These commands pass | |
22090 | a count and a pointer to the values to be loaded into a uniform variable | |
22091 | or a uniform variable array. A count of 1 should be used if modifying | |
22092 | the value of a single uniform variable, and a count of 1 or greater can | |
22093 | be used to modify an entire array or part of an array. When loading | |
22094 | @var{n} elements starting at an arbitrary position @var{m} in a uniform | |
22095 | variable array, elements @var{m} + @var{n} - 1 in the array will be | |
22096 | replaced with the new values. If @var{m} + @var{n} - 1 is larger than | |
22097 | the size of the uniform variable array, values for all array elements | |
22098 | beyond the end of the array will be ignored. The number specified in the | |
22099 | name of the command indicates the number of components for each element | |
22100 | in @var{value}, and it should match the number of components in the data | |
22101 | type of the specified uniform variable (e.g., @code{1} for float, int, | |
22102 | bool; @code{2} for vec2, ivec2, bvec2, etc.). The data type specified in | |
22103 | the name of the command must match the data type for the specified | |
22104 | uniform variable as described previously for | |
22105 | @code{glUniform@{1|2|3|4@}@{f|i@}}. | |
22106 | ||
22107 | For uniform variable arrays, each element of the array is considered to | |
22108 | be of the type indicated in the name of the command (e.g., | |
22109 | @code{glUniform3f} or @code{glUniform3fv} can be used to load a uniform | |
22110 | variable array of type vec3). The number of elements of the uniform | |
22111 | variable array to be modified is specified by @var{count} | |
22112 | ||
22113 | The commands @code{glUniformMatrix@{2|3|4|2x3|3x2|2x4|4x2|3x4|4x3@}fv} | |
22114 | are used to modify a matrix or an array of matrices. The numbers in the | |
22115 | command name are interpreted as the dimensionality of the matrix. The | |
22116 | number @code{2} indicates a 2 × 2 matrix (i.e., 4 values), the number | |
22117 | @code{3} indicates a 3 × 3 matrix (i.e., 9 values), and the number | |
22118 | @code{4} indicates a 4 × 4 matrix (i.e., 16 values). Non-square matrix | |
22119 | dimensionality is explicit, with the first number representing the | |
22120 | number of columns and the second number representing the number of rows. | |
22121 | For example, @code{2x4} indicates a 2 × 4 matrix with 2 columns and 4 | |
22122 | rows (i.e., 8 values). If @var{transpose} is @code{GL_FALSE}, each | |
22123 | matrix is assumed to be supplied in column major order. If | |
22124 | @var{transpose} is @code{GL_TRUE}, each matrix is assumed to be supplied | |
22125 | in row major order. The @var{count} argument indicates the number of | |
22126 | matrices to be passed. A count of 1 should be used if modifying the | |
22127 | value of a single matrix, and a count greater than 1 can be used to | |
22128 | modify an array of matrices. | |
22129 | ||
8925f36f AW |
22130 | @code{GL_INVALID_OPERATION} is generated if there is no current program |
22131 | object. | |
22132 | ||
22133 | @code{GL_INVALID_OPERATION} is generated if the size of the uniform | |
22134 | variable declared in the shader does not match the size indicated by the | |
22135 | @code{glUniform} command. | |
22136 | ||
22137 | @code{GL_INVALID_OPERATION} is generated if one of the integer variants | |
22138 | of this function is used to load a uniform variable of type float, vec2, | |
22139 | vec3, vec4, or an array of these, or if one of the floating-point | |
22140 | variants of this function is used to load a uniform variable of type | |
22141 | int, ivec2, ivec3, or ivec4, or an array of these. | |
22142 | ||
22143 | @code{GL_INVALID_OPERATION} is generated if @var{location} is an invalid | |
22144 | uniform location for the current program object and @var{location} is | |
22145 | not equal to -1. | |
22146 | ||
22147 | @code{GL_INVALID_VALUE} is generated if @var{count} is less than 0. | |
22148 | ||
22149 | @code{GL_INVALID_OPERATION} is generated if @var{count} is greater than | |
22150 | 1 and the indicated uniform variable is not an array variable. | |
22151 | ||
22152 | @code{GL_INVALID_OPERATION} is generated if a sampler is loaded using a | |
22153 | command other than @code{glUniform1i} and @code{glUniform1iv}. | |
22154 | ||
22155 | @code{GL_INVALID_OPERATION} is generated if @code{glUniform} is executed | |
22156 | between the execution of @code{glBegin} and the corresponding execution | |
22157 | of @code{glEnd}. | |
22158 | ||
bb894c9d | 22159 | @end deftypefun |
8925f36f | 22160 | |
bb894c9d | 22161 | @deftypefun void glUseProgram program |
3c9b6116 AW |
22162 | Installs a program object as part of current rendering state. |
22163 | ||
8925f36f AW |
22164 | @table @asis |
22165 | @item @var{program} | |
22166 | Specifies the handle of the program object whose executables are to be | |
22167 | used as part of current rendering state. | |
22168 | ||
22169 | @end table | |
22170 | ||
8925f36f AW |
22171 | @code{glUseProgram} installs the program object specified by |
22172 | @var{program} as part of current rendering state. One or more | |
22173 | executables are created in a program object by successfully attaching | |
22174 | shader objects to it with @code{glAttachShader}, successfully compiling | |
22175 | the shader objects with @code{glCompileShader}, and successfully linking | |
22176 | the program object with @code{glLinkProgram}. | |
22177 | ||
22178 | A program object will contain an executable that will run on the vertex | |
22179 | processor if it contains one or more shader objects of type | |
22180 | @code{GL_VERTEX_SHADER} that have been successfully compiled and linked. | |
22181 | Similarly, a program object will contain an executable that will run on | |
22182 | the fragment processor if it contains one or more shader objects of type | |
22183 | @code{GL_FRAGMENT_SHADER} that have been successfully compiled and | |
22184 | linked. | |
22185 | ||
22186 | Successfully installing an executable on a programmable processor will | |
22187 | cause the corresponding fixed functionality of OpenGL to be disabled. | |
22188 | Specifically, if an executable is installed on the vertex processor, the | |
22189 | OpenGL fixed functionality will be disabled as follows. | |
22190 | ||
22191 | @itemize | |
22192 | @item | |
22193 | The modelview matrix is not applied to vertex coordinates. | |
22194 | ||
22195 | @item | |
22196 | The projection matrix is not applied to vertex coordinates. | |
22197 | ||
22198 | @item | |
22199 | The texture matrices are not applied to texture coordinates. | |
22200 | ||
22201 | @item | |
22202 | Normals are not transformed to eye coordinates. | |
22203 | ||
22204 | @item | |
22205 | Normals are not rescaled or normalized. | |
22206 | ||
22207 | @item | |
22208 | Normalization of @code{GL_AUTO_NORMAL} evaluated normals is not | |
22209 | performed. | |
22210 | ||
22211 | @item | |
22212 | Texture coordinates are not generated automatically. | |
22213 | ||
22214 | @item | |
22215 | Per-vertex lighting is not performed. | |
22216 | ||
22217 | @item | |
22218 | Color material computations are not performed. | |
22219 | ||
22220 | @item | |
22221 | Color index lighting is not performed. | |
22222 | ||
22223 | @item | |
22224 | This list also applies when setting the current raster position. | |
22225 | ||
22226 | @end itemize | |
22227 | ||
22228 | The executable that is installed on the vertex processor is expected to | |
22229 | implement any or all of the desired functionality from the preceding | |
22230 | list. Similarly, if an executable is installed on the fragment | |
22231 | processor, the OpenGL fixed functionality will be disabled as follows. | |
22232 | ||
22233 | @itemize | |
22234 | @item | |
22235 | Texture environment and texture functions are not applied. | |
22236 | ||
22237 | @item | |
22238 | Texture application is not applied. | |
22239 | ||
22240 | @item | |
22241 | Color sum is not applied. | |
22242 | ||
22243 | @item | |
22244 | Fog is not applied. | |
22245 | ||
22246 | @end itemize | |
22247 | ||
22248 | Again, the fragment shader that is installed is expected to implement | |
22249 | any or all of the desired functionality from the preceding list. | |
22250 | ||
22251 | While a program object is in use, applications are free to modify | |
22252 | attached shader objects, compile attached shader objects, attach | |
22253 | additional shader objects, and detach or delete shader objects. None of | |
22254 | these operations will affect the executables that are part of the | |
22255 | current state. However, relinking the program object that is currently | |
22256 | in use will install the program object as part of the current rendering | |
22257 | state if the link operation was successful (see @code{glLinkProgram} ). | |
22258 | If the program object currently in use is relinked unsuccessfully, its | |
22259 | link status will be set to @code{GL_FALSE}, but the executables and | |
22260 | associated state will remain part of the current state until a | |
22261 | subsequent call to @code{glUseProgram} removes it from use. After it is | |
22262 | removed from use, it cannot be made part of current state until it has | |
22263 | been successfully relinked. | |
22264 | ||
22265 | If @var{program} contains shader objects of type @code{GL_VERTEX_SHADER} | |
22266 | but it does not contain shader objects of type | |
22267 | @code{GL_FRAGMENT_SHADER}, an executable will be installed on the vertex | |
22268 | processor, but fixed functionality will be used for fragment processing. | |
22269 | Similarly, if @var{program} contains shader objects of type | |
22270 | @code{GL_FRAGMENT_SHADER} but it does not contain shader objects of type | |
22271 | @code{GL_VERTEX_SHADER}, an executable will be installed on the fragment | |
22272 | processor, but fixed functionality will be used for vertex processing. | |
22273 | If @var{program} is 0, the programmable processors will be disabled, and | |
22274 | fixed functionality will be used for both vertex and fragment | |
22275 | processing. | |
22276 | ||
8925f36f AW |
22277 | @code{GL_INVALID_VALUE} is generated if @var{program} is neither 0 nor a |
22278 | value generated by OpenGL. | |
22279 | ||
22280 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
22281 | program object. | |
22282 | ||
22283 | @code{GL_INVALID_OPERATION} is generated if @var{program} could not be | |
22284 | made part of current state. | |
22285 | ||
22286 | @code{GL_INVALID_OPERATION} is generated if @code{glUseProgram} is | |
22287 | executed between the execution of @code{glBegin} and the corresponding | |
22288 | execution of @code{glEnd}. | |
22289 | ||
bb894c9d | 22290 | @end deftypefun |
8925f36f | 22291 | |
bb894c9d | 22292 | @deftypefun void glValidateProgram program |
3c9b6116 AW |
22293 | Validates a program object. |
22294 | ||
8925f36f AW |
22295 | @table @asis |
22296 | @item @var{program} | |
22297 | Specifies the handle of the program object to be validated. | |
22298 | ||
22299 | @end table | |
22300 | ||
8925f36f AW |
22301 | @code{glValidateProgram} checks to see whether the executables contained |
22302 | in @var{program} can execute given the current OpenGL state. The | |
22303 | information generated by the validation process will be stored in | |
22304 | @var{program}'s information log. The validation information may consist | |
22305 | of an empty string, or it may be a string containing information about | |
22306 | how the current program object interacts with the rest of current OpenGL | |
22307 | state. This provides a way for OpenGL implementers to convey more | |
22308 | information about why the current program is inefficient, suboptimal, | |
22309 | failing to execute, and so on. | |
22310 | ||
22311 | The status of the validation operation will be stored as part of the | |
22312 | program object's state. This value will be set to @code{GL_TRUE} if the | |
22313 | validation succeeded, and @code{GL_FALSE} otherwise. It can be queried | |
22314 | by calling @code{glGetProgram} with arguments @var{program} and | |
22315 | @code{GL_VALIDATE_STATUS}. If validation is successful, @var{program} is | |
22316 | guaranteed to execute given the current state. Otherwise, @var{program} | |
22317 | is guaranteed to not execute. | |
22318 | ||
22319 | This function is typically useful only during application development. | |
22320 | The informational string stored in the information log is completely | |
22321 | implementation dependent; therefore, an application should not expect | |
22322 | different OpenGL implementations to produce identical information | |
22323 | strings. | |
22324 | ||
8925f36f AW |
22325 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
22326 | generated by OpenGL. | |
22327 | ||
22328 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
22329 | program object. | |
22330 | ||
22331 | @code{GL_INVALID_OPERATION} is generated if @code{glValidateProgram} is | |
22332 | executed between the execution of @code{glBegin} and the corresponding | |
22333 | execution of @code{glEnd}. | |
22334 | ||
bb894c9d | 22335 | @end deftypefun |
8925f36f | 22336 | |
bb894c9d | 22337 | @deftypefun void glVertexAttribPointer index size type normalized stride pointer |
3c9b6116 AW |
22338 | Define an array of generic vertex attribute data. |
22339 | ||
8925f36f AW |
22340 | @table @asis |
22341 | @item @var{index} | |
22342 | Specifies the index of the generic vertex attribute to be modified. | |
22343 | ||
22344 | @item @var{size} | |
22345 | Specifies the number of components per generic vertex attribute. Must be | |
22346 | 1, 2, 3, or 4. The initial value is 4. | |
22347 | ||
22348 | @item @var{type} | |
22349 | Specifies the data type of each component in the array. Symbolic | |
22350 | constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, | |
22351 | @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT}, | |
22352 | @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is | |
22353 | @code{GL_FLOAT}. | |
22354 | ||
22355 | @item @var{normalized} | |
22356 | Specifies whether fixed-point data values should be normalized | |
22357 | (@code{GL_TRUE}) or converted directly as fixed-point values | |
22358 | (@code{GL_FALSE}) when they are accessed. | |
22359 | ||
22360 | @item @var{stride} | |
22361 | Specifies the byte offset between consecutive generic vertex attributes. | |
22362 | If @var{stride} is 0, the generic vertex attributes are understood to be | |
22363 | tightly packed in the array. The initial value is 0. | |
22364 | ||
22365 | @item @var{pointer} | |
22366 | Specifies a pointer to the first component of the first generic vertex | |
22367 | attribute in the array. The initial value is 0. | |
22368 | ||
22369 | @end table | |
22370 | ||
8925f36f AW |
22371 | @code{glVertexAttribPointer} specifies the location and data format of |
22372 | the array of generic vertex attributes at index @var{index} to use when | |
22373 | rendering. @var{size} specifies the number of components per attribute | |
22374 | and must be 1, 2, 3, or 4. @var{type} specifies the data type of each | |
22375 | component, and @var{stride} specifies the byte stride from one attribute | |
22376 | to the next, allowing vertices and attributes to be packed into a single | |
22377 | array or stored in separate arrays. If set to @code{GL_TRUE}, | |
22378 | @var{normalized} indicates that values stored in an integer format are | |
22379 | to be mapped to the range [-1,1] (for signed values) or [0,1] (for | |
22380 | unsigned values) when they are accessed and converted to floating point. | |
22381 | Otherwise, values will be converted to floats directly without | |
22382 | normalization. | |
22383 | ||
22384 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
22385 | target (see @code{glBindBuffer}) while a generic vertex attribute array | |
22386 | is specified, @var{pointer} is treated as a byte offset into the buffer | |
22387 | object's data store. Also, the buffer object binding | |
22388 | (@code{GL_ARRAY_BUFFER_BINDING}) is saved as generic vertex attribute | |
22389 | array client-side state (@code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING}) | |
22390 | for index @var{index}. | |
22391 | ||
22392 | When a generic vertex attribute array is specified, @var{size}, | |
22393 | @var{type}, @var{normalized}, @var{stride}, and @var{pointer} are saved | |
22394 | as client-side state, in addition to the current vertex array buffer | |
22395 | object binding. | |
22396 | ||
22397 | To enable and disable a generic vertex attribute array, call | |
22398 | @code{glEnableVertexAttribArray} and @code{glDisableVertexAttribArray} | |
22399 | with @var{index}. If enabled, the generic vertex attribute array is used | |
22400 | when @code{glArrayElement}, @code{glDrawArrays}, | |
22401 | @code{glMultiDrawArrays}, @code{glDrawElements}, | |
22402 | @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called. | |
22403 | ||
8925f36f AW |
22404 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or |
22405 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
22406 | ||
22407 | @code{GL_INVALID_VALUE} is generated if @var{size} is not 1, 2, 3, or 4. | |
22408 | ||
22409 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted | |
22410 | value. | |
22411 | ||
22412 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
22413 | ||
bb894c9d AW |
22414 | @end deftypefun |
22415 | ||
ca09631c AW |
22416 | @deftypefun void glVertexAttrib1f index v0 |
22417 | @deftypefunx void glVertexAttrib1s index v0 | |
22418 | @deftypefunx void glVertexAttrib2f index v0 v1 | |
bb894c9d | 22419 | @deftypefunx void glVertexAttrib2s index v0 v1 |
ca09631c | 22420 | @deftypefunx void glVertexAttrib3f index v0 v1 v2 |
bb894c9d | 22421 | @deftypefunx void glVertexAttrib3s index v0 v1 v2 |
ca09631c | 22422 | @deftypefunx void glVertexAttrib4f index v0 v1 v2 v3 |
bb894c9d | 22423 | @deftypefunx void glVertexAttrib4s index v0 v1 v2 v3 |
bb894c9d | 22424 | @deftypefunx void glVertexAttrib4Nub index v0 v1 v2 v3 |
b002944d AW |
22425 | @deftypefunx void glVertexAttrib4iv index v |
22426 | @deftypefunx void glVertexAttrib4uiv index v | |
22427 | @deftypefunx void glVertexAttrib4Niv index v | |
22428 | @deftypefunx void glVertexAttrib4Nuiv index v | |
3c9b6116 AW |
22429 | Specifies the value of a generic vertex attribute. |
22430 | ||
8925f36f AW |
22431 | @table @asis |
22432 | @item @var{index} | |
22433 | Specifies the index of the generic vertex attribute to be modified. | |
22434 | ||
22435 | @item @var{v0}, @var{v1}, @var{v2}, @var{v3} | |
22436 | Specifies the new values to be used for the specified vertex attribute. | |
22437 | ||
22438 | @end table | |
22439 | ||
8925f36f AW |
22440 | OpenGL defines a number of standard vertex attributes that applications |
22441 | can modify with standard API entry points (color, normal, texture | |
22442 | coordinates, etc.). The @code{glVertexAttrib} family of entry points | |
22443 | allows an application to pass generic vertex attributes in numbered | |
22444 | locations. | |
22445 | ||
22446 | Generic attributes are defined as four-component values that are | |
22447 | organized into an array. The first entry of this array is numbered 0, | |
22448 | and the size of the array is specified by the implementation-dependent | |
22449 | constant @code{GL_MAX_VERTEX_ATTRIBS}. Individual elements of this array | |
22450 | can be modified with a @code{glVertexAttrib} call that specifies the | |
22451 | index of the element to be modified and a value for that element. | |
22452 | ||
22453 | These commands can be used to specify one, two, three, or all four | |
22454 | components of the generic vertex attribute specified by @var{index}. A | |
22455 | @code{1} in the name of the command indicates that only one value is | |
22456 | passed, and it will be used to modify the first component of the generic | |
22457 | vertex attribute. The second and third components will be set to 0, and | |
22458 | the fourth component will be set to 1. Similarly, a @code{2} in the name | |
22459 | of the command indicates that values are provided for the first two | |
22460 | components, the third component will be set to 0, and the fourth | |
22461 | component will be set to 1. A @code{3} in the name of the command | |
22462 | indicates that values are provided for the first three components and | |
22463 | the fourth component will be set to 1, whereas a @code{4} in the name | |
22464 | indicates that values are provided for all four components. | |
22465 | ||
22466 | The letters @code{s}, @code{f}, @code{i}, @code{d}, @code{ub}, | |
22467 | @code{us}, and @code{ui} indicate whether the arguments are of type | |
22468 | short, float, int, double, unsigned byte, unsigned short, or unsigned | |
22469 | int. When @code{v} is appended to the name, the commands can take a | |
22470 | pointer to an array of such values. The commands containing @code{N} | |
22471 | indicate that the arguments will be passed as fixed-point values that | |
22472 | are scaled to a normalized range according to the component conversion | |
22473 | rules defined by the OpenGL specification. Signed values are understood | |
22474 | to represent fixed-point values in the range [-1,1], and unsigned values | |
22475 | are understood to represent fixed-point values in the range [0,1]. | |
22476 | ||
22477 | OpenGL Shading Language attribute variables are allowed to be of type | |
22478 | mat2, mat3, or mat4. Attributes of these types may be loaded using the | |
22479 | @code{glVertexAttrib} entry points. Matrices must be loaded into | |
22480 | successive generic attribute slots in column major order, with one | |
22481 | column of the matrix in each generic attribute slot. | |
22482 | ||
22483 | A user-defined attribute variable declared in a vertex shader can be | |
22484 | bound to a generic attribute index by calling | |
22485 | @code{glBindAttribLocation}. This allows an application to use more | |
22486 | descriptive variable names in a vertex shader. A subsequent change to | |
22487 | the specified generic vertex attribute will be immediately reflected as | |
22488 | a change to the corresponding attribute variable in the vertex shader. | |
22489 | ||
22490 | The binding between a generic vertex attribute index and a user-defined | |
22491 | attribute variable in a vertex shader is part of the state of a program | |
22492 | object, but the current value of the generic vertex attribute is not. | |
22493 | The value of each generic vertex attribute is part of current state, | |
22494 | just like standard vertex attributes, and it is maintained even if a | |
22495 | different program object is used. | |
22496 | ||
22497 | An application may freely modify generic vertex attributes that are not | |
22498 | bound to a named vertex shader attribute variable. These values are | |
22499 | simply maintained as part of current state and will not be accessed by | |
22500 | the vertex shader. If a generic vertex attribute bound to an attribute | |
22501 | variable in a vertex shader is not updated while the vertex shader is | |
22502 | executing, the vertex shader will repeatedly use the current value for | |
22503 | the generic vertex attribute. | |
22504 | ||
22505 | The generic vertex attribute with index 0 is the same as the vertex | |
22506 | position attribute previously defined by OpenGL. A @code{glVertex2}, | |
22507 | @code{glVertex3}, or @code{glVertex4} command is completely equivalent | |
22508 | to the corresponding @code{glVertexAttrib} command with an index | |
22509 | argument of 0. A vertex shader can access generic vertex attribute 0 by | |
22510 | using the built-in attribute variable @var{gl_Vertex}. There are no | |
22511 | current values for generic vertex attribute 0. This is the only generic | |
22512 | vertex attribute with this property; calls to set other standard vertex | |
22513 | attributes can be freely mixed with calls to set any of the other | |
22514 | generic vertex attributes. | |
22515 | ||
8925f36f AW |
22516 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or |
22517 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
22518 | ||
bb894c9d | 22519 | @end deftypefun |
8925f36f | 22520 | |
bb894c9d | 22521 | @deftypefun void glVertexPointer size type stride pointer |
3c9b6116 AW |
22522 | Define an array of vertex data. |
22523 | ||
8925f36f AW |
22524 | @table @asis |
22525 | @item @var{size} | |
22526 | Specifies the number of coordinates per vertex. Must be 2, 3, or 4. The | |
22527 | initial value is 4. | |
22528 | ||
22529 | @item @var{type} | |
22530 | Specifies the data type of each coordinate in the array. Symbolic | |
22531 | constants @code{GL_SHORT}, @code{GL_INT}, @code{GL_FLOAT}, or | |
22532 | @code{GL_DOUBLE} are accepted. The initial value is @code{GL_FLOAT}. | |
22533 | ||
22534 | @item @var{stride} | |
22535 | Specifies the byte offset between consecutive vertices. If @var{stride} | |
22536 | is 0, the vertices are understood to be tightly packed in the array. The | |
22537 | initial value is 0. | |
22538 | ||
22539 | @item @var{pointer} | |
22540 | Specifies a pointer to the first coordinate of the first vertex in the | |
22541 | array. The initial value is 0. | |
22542 | ||
22543 | @end table | |
22544 | ||
8925f36f AW |
22545 | @code{glVertexPointer} specifies the location and data format of an |
22546 | array of vertex coordinates to use when rendering. @var{size} specifies | |
22547 | the number of coordinates per vertex, and must be 2, 3, or 4. @var{type} | |
22548 | specifies the data type of each coordinate, and @var{stride} specifies | |
22549 | the byte stride from one vertex to the next, allowing vertices and | |
22550 | attributes to be packed into a single array or stored in separate | |
22551 | arrays. (Single-array storage may be more efficient on some | |
22552 | implementations; see @code{glInterleavedArrays}.) | |
22553 | ||
22554 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
22555 | target (see @code{glBindBuffer}) while a vertex array is specified, | |
22556 | @var{pointer} is treated as a byte offset into the buffer object's data | |
22557 | store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING}) | |
22558 | is saved as vertex array client-side state | |
22559 | (@code{GL_VERTEX_ARRAY_BUFFER_BINDING}). | |
22560 | ||
22561 | When a vertex array is specified, @var{size}, @var{type}, @var{stride}, | |
22562 | and @var{pointer} are saved as client-side state, in addition to the | |
22563 | current vertex array buffer object binding. | |
22564 | ||
22565 | To enable and disable the vertex array, call @code{glEnableClientState} | |
22566 | and @code{glDisableClientState} with the argument | |
22567 | @code{GL_VERTEX_ARRAY}. If enabled, the vertex array is used when | |
22568 | @code{glArrayElement}, @code{glDrawArrays}, @code{glMultiDrawArrays}, | |
22569 | @code{glDrawElements}, @code{glMultiDrawElements}, or | |
22570 | @code{glDrawRangeElements} is called. | |
22571 | ||
8925f36f AW |
22572 | @code{GL_INVALID_VALUE} is generated if @var{size} is not 2, 3, or 4. |
22573 | ||
22574 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted | |
22575 | value. | |
22576 | ||
22577 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
22578 | ||
bb894c9d | 22579 | @end deftypefun |
8925f36f | 22580 | |
bb894c9d | 22581 | @deftypefun void glVertex2i x y |
ca09631c | 22582 | @deftypefunx void glVertex2f x y |
bb894c9d | 22583 | @deftypefunx void glVertex3i x y z |
ca09631c | 22584 | @deftypefunx void glVertex3f x y z |
bb894c9d | 22585 | @deftypefunx void glVertex4i x y z w |
ca09631c | 22586 | @deftypefunx void glVertex4f x y z w |
3c9b6116 AW |
22587 | Specify a vertex. |
22588 | ||
8925f36f AW |
22589 | @table @asis |
22590 | @item @var{x} | |
22591 | @itemx @var{y} | |
22592 | @itemx @var{z} | |
22593 | @itemx @var{w} | |
22594 | Specify @var{x}, @var{y}, @var{z}, and @var{w} coordinates of a vertex. | |
22595 | Not all parameters are present in all forms of the command. | |
22596 | ||
22597 | @end table | |
22598 | ||
8925f36f AW |
22599 | @code{glVertex} commands are used within @code{glBegin}/@code{glEnd} |
22600 | pairs to specify point, line, and polygon vertices. The current color, | |
22601 | normal, texture coordinates, and fog coordinate are associated with the | |
22602 | vertex when @code{glVertex} is called. | |
22603 | ||
3c9b6116 AW |
22604 | When only @r{@var{x}} and @r{@var{y}} are specified, @r{@var{z}} |
22605 | defaults to 0 and @r{@var{w}} defaults to 1. When @r{@var{x}}, | |
22606 | @r{@var{y}}, and @r{@var{z}} are specified, @r{@var{w}} defaults to 1. | |
8925f36f | 22607 | |
bb894c9d | 22608 | @end deftypefun |
8925f36f | 22609 | |
bb894c9d | 22610 | @deftypefun void glViewport x y width height |
3c9b6116 AW |
22611 | Set the viewport. |
22612 | ||
8925f36f AW |
22613 | @table @asis |
22614 | @item @var{x} | |
22615 | @itemx @var{y} | |
22616 | Specify the lower left corner of the viewport rectangle, in pixels. The | |
22617 | initial value is (0,0). | |
22618 | ||
22619 | @item @var{width} | |
22620 | @itemx @var{height} | |
22621 | Specify the width and height of the viewport. When a GL context is first | |
22622 | attached to a window, @var{width} and @var{height} are set to the | |
22623 | dimensions of that window. | |
22624 | ||
22625 | @end table | |
22626 | ||
3c9b6116 AW |
22627 | @code{glViewport} specifies the affine transformation of @r{@var{x}} and |
22628 | @r{@var{y}} from normalized device coordinates to window coordinates. | |
22629 | Let @r{(@var{x}_@var{nd},@var{y}_@var{nd})} be normalized device | |
22630 | coordinates. Then the window coordinates | |
22631 | @r{(@var{x}_@var{w},@var{y}_@var{w})} are computed as follows: | |
8925f36f | 22632 | |
3c9b6116 | 22633 | @r{@var{x}_@var{w}=(@var{x}_@var{nd}+1,)(@var{width}/2,)+@var{x}} |
8925f36f | 22634 | |
3c9b6116 | 22635 | @r{@var{y}_@var{w}=(@var{y}_@var{nd}+1,)(@var{height}/2,)+@var{y}} |
8925f36f AW |
22636 | |
22637 | Viewport width and height are silently clamped to a range that depends | |
22638 | on the implementation. To query this range, call @code{glGet} with | |
22639 | argument @code{GL_MAX_VIEWPORT_DIMS}. | |
22640 | ||
8925f36f AW |
22641 | @code{GL_INVALID_VALUE} is generated if either @var{width} or |
22642 | @var{height} is negative. | |
22643 | ||
22644 | @code{GL_INVALID_OPERATION} is generated if @code{glViewport} is | |
22645 | executed between the execution of @code{glBegin} and the corresponding | |
22646 | execution of @code{glEnd}. | |
22647 | ||
bb894c9d | 22648 | @end deftypefun |
8925f36f | 22649 | |
bb894c9d | 22650 | @deftypefun void glWindowPos2i x y |
ca09631c | 22651 | @deftypefunx void glWindowPos2f x y |
bb894c9d | 22652 | @deftypefunx void glWindowPos3i x y z |
ca09631c | 22653 | @deftypefunx void glWindowPos3f x y z |
3c9b6116 AW |
22654 | Specify the raster position in window coordinates for pixel operations. |
22655 | ||
8925f36f AW |
22656 | @table @asis |
22657 | @item @var{x} | |
22658 | @itemx @var{y} | |
22659 | @itemx @var{z} | |
3c9b6116 AW |
22660 | Specify the @r{@var{x}}, @r{@var{y}}, @r{@var{z}} coordinates for the |
22661 | raster position. | |
8925f36f AW |
22662 | |
22663 | @end table | |
22664 | ||
8925f36f AW |
22665 | The GL maintains a 3D position in window coordinates. This position, |
22666 | called the raster position, is used to position pixel and bitmap write | |
22667 | operations. It is maintained with subpixel accuracy. See | |
22668 | @code{glBitmap}, @code{glDrawPixels}, and @code{glCopyPixels}. | |
22669 | ||
3c9b6116 AW |
22670 | @code{glWindowPos2} specifies the @r{@var{x}} and @r{@var{y}} |
22671 | coordinates, while @r{@var{z}} is implicitly set to 0. | |
22672 | @code{glWindowPos3} specifies all three coordinates. The @r{@var{w}} | |
8925f36f AW |
22673 | coordinate of the current raster position is always set to 1.0. |
22674 | ||
3c9b6116 AW |
22675 | @code{glWindowPos} directly updates the @r{@var{x}} and @r{@var{y}} |
22676 | coordinates of the current raster position with the values specified. | |
22677 | That is, the values are neither transformed by the current modelview and | |
22678 | projection matrices, nor by the viewport-to-window transform. The | |
22679 | @r{@var{z}} coordinate of the current raster position is updated in the | |
22680 | following manner: | |
8925f36f | 22681 | |
3c9b6116 | 22682 | @r{@var{z}=@{(@var{n}), (@var{f}), |
8925f36f AW |
22683 | (@var{n}+@var{z}×(@var{f}-@var{n},),)(@var{if}@var{z}<=0), |
22684 | (@var{if}@var{z}>=1), (@code{otherwise},),} | |
22685 | ||
22686 | ||
22687 | ||
3c9b6116 AW |
22688 | where @r{@var{n}} is @code{GL_DEPTH_RANGE}'s near value, and @r{@var{f}} |
22689 | is @code{GL_DEPTH_RANGE}'s far value. See @code{glDepthRange}. | |
8925f36f AW |
22690 | |
22691 | The specified coordinates are not clip-tested, causing the raster | |
22692 | position to always be valid. | |
22693 | ||
22694 | The current raster position also includes some associated color data and | |
22695 | texture coordinates. If lighting is enabled, then | |
22696 | @code{GL_CURRENT_RASTER_COLOR} (in RGBA mode) or | |
22697 | @code{GL_CURRENT_RASTER_INDEX} (in color index mode) is set to the color | |
22698 | produced by the lighting calculation (see @code{glLight}, | |
22699 | @code{glLightModel}, and @code{glShadeModel}). If lighting is disabled, | |
22700 | current color (in RGBA mode, state variable @code{GL_CURRENT_COLOR}) or | |
22701 | color index (in color index mode, state variable | |
22702 | @code{GL_CURRENT_INDEX}) is used to update the current raster color. | |
22703 | @code{GL_CURRENT_RASTER_SECONDARY_COLOR} (in RGBA mode) is likewise | |
22704 | updated. | |
22705 | ||
22706 | Likewise, @code{GL_CURRENT_RASTER_TEXTURE_COORDS} is updated as a | |
22707 | function of @code{GL_CURRENT_TEXTURE_COORDS}, based on the texture | |
22708 | matrix and the texture generation functions (see @code{glTexGen}). The | |
22709 | @code{GL_CURRENT_RASTER_DISTANCE} is set to the | |
22710 | @code{GL_CURRENT_FOG_COORD}. | |
22711 | ||
22712 | ||
22713 | ||
8925f36f AW |
22714 | @code{GL_INVALID_OPERATION} is generated if @code{glWindowPos} is |
22715 | executed between the execution of @code{glBegin} and the corresponding | |
22716 | execution of @code{glEnd}. | |
22717 | ||
bb894c9d | 22718 | @end deftypefun |
8925f36f AW |
22719 | |
22720 | ||
22721 | @c %end of fragment |