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 | |
7 | (use-modules (figl low-level gl)) | |
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 | |
bb894c9d | 2167 | @deftypefun void glColorTable target internalformat width format type data |
3c9b6116 AW |
2168 | Define a color lookup table. |
2169 | ||
8925f36f AW |
2170 | @table @asis |
2171 | @item @var{target} | |
2172 | Must be one of @code{GL_COLOR_TABLE}, | |
2173 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, | |
2174 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{GL_PROXY_COLOR_TABLE}, | |
2175 | @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or | |
2176 | @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}. | |
2177 | ||
2178 | @item @var{internalformat} | |
2179 | The internal format of the color table. The allowable values are | |
2180 | @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, | |
2181 | @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
2182 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
2183 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
2184 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
2185 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
2186 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY}, | |
2187 | @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12}, | |
2188 | @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
2189 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
2190 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
2191 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
2192 | @code{GL_RGBA12}, and @code{GL_RGBA16}. | |
2193 | ||
2194 | @item @var{width} | |
2195 | The number of entries in the color lookup table specified by @var{data}. | |
2196 | ||
2197 | @item @var{format} | |
2198 | The format of the pixel data in @var{data}. The allowable values are | |
2199 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, | |
2200 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, | |
2201 | @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}. | |
2202 | ||
2203 | @item @var{type} | |
2204 | The type of the pixel data in @var{data}. The allowable values are | |
2205 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT}, | |
2206 | @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT}, | |
2207 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
2208 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
2209 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
2210 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
2211 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
2212 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
2213 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
2214 | ||
2215 | @item @var{data} | |
2216 | Pointer to a one-dimensional array of pixel data that is processed to | |
2217 | build the color table. | |
2218 | ||
2219 | @end table | |
2220 | ||
8925f36f AW |
2221 | @code{glColorTable} may be used in two ways: to test the actual size and |
2222 | color resolution of a lookup table given a particular set of parameters, | |
2223 | or to load the contents of a color lookup table. Use the targets | |
2224 | @code{GL_PROXY_*} for the first case and the other targets for the | |
2225 | second case. | |
2226 | ||
2227 | If a non-zero named buffer object is bound to the | |
2228 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2229 | color table is specified, @var{data} is treated as a byte offset into | |
2230 | the buffer object's data store. | |
2231 | ||
2232 | If @var{target} is @code{GL_COLOR_TABLE}, | |
2233 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or | |
2234 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{glColorTable} builds a | |
2235 | color lookup table from an array of pixels. The pixel array specified by | |
2236 | @var{width}, @var{format}, @var{type}, and @var{data} is extracted from | |
2237 | memory and processed just as if @code{glDrawPixels} were called, but | |
2238 | processing stops after the final expansion to RGBA is completed. | |
2239 | ||
2240 | The four scale parameters and the four bias parameters that are defined | |
2241 | for the table are then used to scale and bias the R, G, B, and A | |
2242 | components of each pixel. (Use @code{glColorTableParameter} to set these | |
2243 | scale and bias parameters.) | |
2244 | ||
3c9b6116 AW |
2245 | Next, the R, G, B, and A values are clamped to the range @r{[0,1]}. Each |
2246 | pixel is then converted to the internal format specified by | |
8925f36f AW |
2247 | @var{internalformat}. This conversion simply maps the component values |
2248 | of the pixel (R, G, B, and A) to the values included in the internal | |
2249 | format (red, green, blue, alpha, luminance, and intensity). The mapping | |
2250 | is as follows: | |
2251 | ||
2252 | ||
2253 | ||
2254 | @table @asis | |
2255 | @item @strong{Internal Format} | |
2256 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
2257 | @strong{Luminance}, @strong{Intensity} | |
2258 | ||
2259 | @item @code{GL_ALPHA} | |
2260 | , , , A , , | |
2261 | ||
2262 | @item @code{GL_LUMINANCE} | |
2263 | , , , , R , | |
2264 | ||
2265 | @item @code{GL_LUMINANCE_ALPHA} | |
2266 | , , , A , R , | |
2267 | ||
2268 | @item @code{GL_INTENSITY} | |
2269 | , , , , , R | |
2270 | ||
2271 | @item @code{GL_RGB} | |
2272 | R , G , B , , , | |
2273 | ||
2274 | @item @code{GL_RGBA} | |
2275 | R , G , B , A , , | |
2276 | ||
2277 | @end table | |
2278 | ||
2279 | Finally, the red, green, blue, alpha, luminance, and/or intensity | |
2280 | components of the resulting pixels are stored in the color table. They | |
2281 | form a one-dimensional table with indices in the range | |
3c9b6116 | 2282 | @r{[0,@var{width}-1]}. |
8925f36f AW |
2283 | |
2284 | If @var{target} is @code{GL_PROXY_*}, @code{glColorTable} recomputes and | |
2285 | stores the values of the proxy color table's state variables | |
2286 | @code{GL_COLOR_TABLE_FORMAT}, @code{GL_COLOR_TABLE_WIDTH}, | |
2287 | @code{GL_COLOR_TABLE_RED_SIZE}, @code{GL_COLOR_TABLE_GREEN_SIZE}, | |
2288 | @code{GL_COLOR_TABLE_BLUE_SIZE}, @code{GL_COLOR_TABLE_ALPHA_SIZE}, | |
2289 | @code{GL_COLOR_TABLE_LUMINANCE_SIZE}, and | |
2290 | @code{GL_COLOR_TABLE_INTENSITY_SIZE}. There is no effect on the image or | |
2291 | state of any actual color table. If the specified color table is too | |
2292 | large to be supported, then all the proxy state variables listed above | |
2293 | are set to zero. Otherwise, the color table could be supported by | |
2294 | @code{glColorTable} using the corresponding non-proxy target, and the | |
2295 | proxy state variables are set as if that target were being defined. | |
2296 | ||
2297 | The proxy state variables can be retrieved by calling | |
2298 | @code{glGetColorTableParameter} with a target of @code{GL_PROXY_*}. This | |
2299 | allows the application to decide if a particular @code{glColorTable} | |
2300 | command would succeed, and to determine what the resulting color table | |
2301 | attributes would be. | |
2302 | ||
2303 | If a color table is enabled, and its width is non-zero, then its | |
2304 | contents are used to replace a subset of the components of each RGBA | |
2305 | pixel group, based on the internal format of the table. | |
2306 | ||
2307 | Each pixel group has color components (R, G, B, A) that are in the range | |
3c9b6116 | 2308 | @r{[0.0,1.0]}. The color components are rescaled to the size of the |
8925f36f AW |
2309 | color lookup table to form an index. Then a subset of the components |
2310 | based on the internal format of the table are replaced by the table | |
2311 | entry selected by that index. If the color components and contents of | |
2312 | the table are represented as follows: | |
2313 | ||
2314 | ||
2315 | ||
2316 | @table @asis | |
2317 | @item @strong{Representation} | |
2318 | @strong{Meaning} | |
2319 | ||
2320 | @item @code{r} | |
2321 | Table index computed from @code{R} | |
2322 | ||
2323 | @item @code{g} | |
2324 | Table index computed from @code{G} | |
2325 | ||
2326 | @item @code{b} | |
2327 | Table index computed from @code{B} | |
2328 | ||
2329 | @item @code{a} | |
2330 | Table index computed from @code{A} | |
2331 | ||
2332 | @item @code{L[i]} | |
2333 | Luminance value at table index @code{i} | |
2334 | ||
2335 | @item @code{I[i]} | |
2336 | Intensity value at table index @code{i} | |
2337 | ||
2338 | @item @code{R[i]} | |
2339 | Red value at table index @code{i} | |
2340 | ||
2341 | @item @code{G[i]} | |
2342 | Green value at table index @code{i} | |
2343 | ||
2344 | @item @code{B[i]} | |
2345 | Blue value at table index @code{i} | |
2346 | ||
2347 | @item @code{A[i]} | |
2348 | Alpha value at table index @code{i} | |
2349 | ||
2350 | @end table | |
2351 | ||
2352 | then the result of color table lookup is as follows: | |
2353 | ||
2354 | ||
2355 | ||
2356 | @table @asis | |
2357 | @item @strong{} | |
2358 | @strong{Resulting Texture Components} | |
2359 | ||
2360 | @item @strong{Table Internal Format} | |
2361 | @strong{R}, @strong{G}, @strong{B}, @strong{A} | |
2362 | ||
2363 | @item @code{GL_ALPHA} | |
2364 | @code{R}, @code{G}, @code{B}, @code{A[a]} | |
2365 | ||
2366 | @item @code{GL_LUMINANCE} | |
2367 | @code{L[r]}, @code{L[g]}, @code{L[b]}, @code{At} | |
2368 | ||
2369 | @item @code{GL_LUMINANCE_ALPHA} | |
2370 | @code{L[r]}, @code{L[g]}, @code{L[b]}, @code{A[a]} | |
2371 | ||
2372 | @item @code{GL_INTENSITY} | |
2373 | @code{I[r]}, @code{I[g]}, @code{I[b]}, @code{I[a]} | |
2374 | ||
2375 | @item @code{GL_RGB} | |
2376 | @code{R[r]}, @code{G[g]}, @code{B[b]}, @code{A} | |
2377 | ||
2378 | @item @code{GL_RGBA} | |
2379 | @code{R[r]}, @code{G[g]}, @code{B[b]}, @code{A[a]} | |
2380 | ||
2381 | @end table | |
2382 | ||
2383 | When @code{GL_COLOR_TABLE} is enabled, the colors resulting from the | |
2384 | pixel map operation (if it is enabled) are mapped by the color lookup | |
2385 | table before being passed to the convolution operation. The colors | |
2386 | resulting from the convolution operation are modified by the post | |
2387 | convolution color lookup table when | |
2388 | @code{GL_POST_CONVOLUTION_COLOR_TABLE} is enabled. These modified colors | |
2389 | are then sent to the color matrix operation. Finally, if | |
2390 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} is enabled, the colors resulting | |
2391 | from the color matrix operation are mapped by the post color matrix | |
2392 | color lookup table before being used by the histogram operation. | |
2393 | ||
2394 | ||
2395 | ||
8925f36f AW |
2396 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
2397 | allowable values. | |
2398 | ||
2399 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
2400 | of the allowable values. | |
2401 | ||
2402 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
2403 | allowable values. | |
2404 | ||
2405 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
2406 | allowable values. | |
2407 | ||
2408 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero. | |
2409 | ||
2410 | @code{GL_TABLE_TOO_LARGE} is generated if the requested color table is | |
2411 | too large to be supported by the implementation, and @var{target} is not | |
2412 | a @code{GL_PROXY_*} target. | |
2413 | ||
2414 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2415 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2416 | object's data store is currently mapped. | |
2417 | ||
2418 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2419 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2420 | would be unpacked from the buffer object such that the memory reads | |
2421 | required would exceed the data store size. | |
2422 | ||
2423 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2424 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
2425 | is not evenly divisible into the number of bytes needed to store in | |
2426 | memory a datum indicated by @var{type}. | |
2427 | ||
2428 | @code{GL_INVALID_OPERATION} is generated if @code{glColorTable} is | |
2429 | executed between the execution of @code{glBegin} and the corresponding | |
2430 | execution of @code{glEnd}. | |
2431 | ||
bb894c9d | 2432 | @end deftypefun |
8925f36f | 2433 | |
bb894c9d AW |
2434 | @deftypefun void glColor3i red green blue |
2435 | @deftypefunx void glColor3d red green blue | |
2436 | @deftypefunx void glColor3ui red green blue | |
2437 | @deftypefunx void glColor4i red green blue alpha | |
2438 | @deftypefunx void glColor4d red green blue alpha | |
2439 | @deftypefunx void glColor4ui red green blue alpha | |
3c9b6116 AW |
2440 | Set the current color. |
2441 | ||
8925f36f AW |
2442 | @table @asis |
2443 | @item @var{red} | |
2444 | @itemx @var{green} | |
2445 | @itemx @var{blue} | |
2446 | Specify new red, green, and blue values for the current color. | |
2447 | ||
2448 | @item @var{alpha} | |
2449 | Specifies a new alpha value for the current color. Included only in the | |
2450 | four-argument @code{glColor4} commands. | |
2451 | ||
2452 | @end table | |
2453 | ||
8925f36f AW |
2454 | The GL stores both a current single-valued color index and a current |
2455 | four-valued RGBA color. @code{glColor} sets a new four-valued RGBA | |
2456 | color. @code{glColor} has two major variants: @code{glColor3} and | |
2457 | @code{glColor4}. @code{glColor3} variants specify new red, green, and | |
2458 | blue values explicitly and set the current alpha value to 1.0 (full | |
2459 | intensity) implicitly. @code{glColor4} variants specify all four color | |
2460 | components explicitly. | |
2461 | ||
2462 | @code{glColor3b}, @code{glColor4b}, @code{glColor3s}, @code{glColor4s}, | |
2463 | @code{glColor3i}, and @code{glColor4i} take three or four signed byte, | |
2464 | short, or long integers as arguments. When @strong{v} is appended to the | |
2465 | name, the color commands can take a pointer to an array of such values. | |
2466 | ||
2467 | Current color values are stored in floating-point format, with | |
2468 | unspecified mantissa and exponent sizes. Unsigned integer color | |
2469 | components, when specified, are linearly mapped to floating-point values | |
2470 | such that the largest representable value maps to 1.0 (full intensity), | |
2471 | and 0 maps to 0.0 (zero intensity). Signed integer color components, | |
2472 | when specified, are linearly mapped to floating-point values such that | |
2473 | the most positive representable value maps to 1.0, and the most negative | |
3c9b6116 AW |
2474 | representable value maps to @r{-1.0}. (Note that this mapping does not |
2475 | convert 0 precisely to 0.0.) Floating-point values are mapped directly. | |
8925f36f AW |
2476 | |
2477 | Neither floating-point nor signed integer values are clamped to the | |
3c9b6116 | 2478 | range @r{[0,1]} before the current color is updated. However, color |
8925f36f AW |
2479 | components are clamped to this range before they are interpolated or |
2480 | written into a color buffer. | |
2481 | ||
bb894c9d | 2482 | @end deftypefun |
8925f36f | 2483 | |
bb894c9d | 2484 | @deftypefun void glCompileShader shader |
3c9b6116 AW |
2485 | Compiles a shader object. |
2486 | ||
8925f36f AW |
2487 | @table @asis |
2488 | @item @var{shader} | |
2489 | Specifies the shader object to be compiled. | |
2490 | ||
2491 | @end table | |
2492 | ||
8925f36f AW |
2493 | @code{glCompileShader} compiles the source code strings that have been |
2494 | stored in the shader object specified by @var{shader}. | |
2495 | ||
2496 | The compilation status will be stored as part of the shader object's | |
2497 | state. This value will be set to @code{GL_TRUE} if the shader was | |
2498 | compiled without errors and is ready for use, and @code{GL_FALSE} | |
2499 | otherwise. It can be queried by calling @code{glGetShader} with | |
2500 | arguments @var{shader} and @code{GL_COMPILE_STATUS}. | |
2501 | ||
2502 | Compilation of a shader can fail for a number of reasons as specified by | |
2503 | the OpenGL Shading Language Specification. Whether or not the | |
2504 | compilation was successful, information about the compilation can be | |
2505 | obtained from the shader object's information log by calling | |
2506 | @code{glGetShaderInfoLog}. | |
2507 | ||
8925f36f AW |
2508 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
2509 | generated by OpenGL. | |
2510 | ||
2511 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
2512 | object. | |
2513 | ||
2514 | @code{GL_INVALID_OPERATION} is generated if @code{glCompileShader} is | |
2515 | executed between the execution of @code{glBegin} and the corresponding | |
2516 | execution of @code{glEnd}. | |
2517 | ||
bb894c9d | 2518 | @end deftypefun |
8925f36f | 2519 | |
bb894c9d | 2520 | @deftypefun void glCompressedTexImage1D target level internalformat width border imageSize data |
3c9b6116 AW |
2521 | Specify a one-dimensional texture image in a compressed format. |
2522 | ||
8925f36f AW |
2523 | @table @asis |
2524 | @item @var{target} | |
2525 | Specifies the target texture. Must be @code{GL_TEXTURE_1D} or | |
2526 | @code{GL_PROXY_TEXTURE_1D}. | |
2527 | ||
2528 | @item @var{level} | |
2529 | Specifies the level-of-detail number. Level 0 is the base image level. | |
2530 | Level @var{n} is the @var{n}th mipmap reduction image. | |
2531 | ||
2532 | @item @var{internalformat} | |
2533 | Specifies the format of the compressed image data stored at address | |
2534 | @var{data}. | |
2535 | ||
2536 | @item @var{width} | |
2537 | Specifies the width of the texture image including the border if any. If | |
2538 | the GL version does not support non-power-of-two sizes, this value must | |
3c9b6116 AW |
2539 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
2540 | implementations support texture images that are at least 64 texels wide. | |
2541 | The height of the 1D texture image is 1. | |
8925f36f AW |
2542 | |
2543 | @item @var{border} | |
2544 | Specifies the width of the border. Must be either 0 or 1. | |
2545 | ||
2546 | @item @var{imageSize} | |
2547 | Specifies the number of unsigned bytes of image data starting at the | |
2548 | address specified by @var{data}. | |
2549 | ||
2550 | @item @var{data} | |
2551 | Specifies a pointer to the compressed image data in memory. | |
2552 | ||
2553 | @end table | |
2554 | ||
8925f36f AW |
2555 | Texturing maps a portion of a specified texture image onto each |
2556 | graphical primitive for which texturing is enabled. To enable and | |
2557 | disable one-dimensional texturing, call @code{glEnable} and | |
2558 | @code{glDisable} with argument @code{GL_TEXTURE_1D}. | |
2559 | ||
2560 | @code{glCompressedTexImage1D} loads a previously defined, and retrieved, | |
2561 | compressed one-dimensional texture image if @var{target} is | |
2562 | @code{GL_TEXTURE_1D} (see @code{glTexImage1D}). | |
2563 | ||
2564 | If @var{target} is @code{GL_PROXY_TEXTURE_1D}, no data is read from | |
2565 | @var{data}, but all of the texture image state is recalculated, checked | |
2566 | for consistency, and checked against the implementation's capabilities. | |
2567 | If the implementation cannot handle a texture of the requested texture | |
2568 | size, it sets all of the image state to 0, but does not generate an | |
2569 | error (see @code{glGetError}). To query for an entire mipmap array, use | |
2570 | an image array level greater than or equal to 1. | |
2571 | ||
2572 | @var{internalformat} must be extension-specified compressed-texture | |
2573 | format. When a texture is loaded with @code{glTexImage1D} using a | |
2574 | generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}) the | |
2575 | GL selects from one of its extensions supporting compressed textures. In | |
2576 | order to load the compressed texture image using | |
2577 | @code{glCompressedTexImage1D}, query the compressed texture image's size | |
2578 | and format using @code{glGetTexLevelParameter}. | |
2579 | ||
2580 | If a non-zero named buffer object is bound to the | |
2581 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2582 | texture image is specified, @var{data} is treated as a byte offset into | |
2583 | the buffer object's data store. | |
2584 | ||
8925f36f AW |
2585 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of |
2586 | the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
2587 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
2588 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or | |
2589 | @code{GL_COMPRESSED_RGBA}. | |
2590 | ||
2591 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
2592 | consistent with the format, dimensions, and contents of the specified | |
2593 | compressed image data. | |
2594 | ||
2595 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
2596 | not supported by the specific compressed internal format as specified in | |
2597 | the specific texture compression extension. | |
2598 | ||
2599 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2600 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2601 | object's data store is currently mapped. | |
2602 | ||
2603 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2604 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2605 | would be unpacked from the buffer object such that the memory reads | |
2606 | required would exceed the data store size. | |
2607 | ||
2608 | @code{GL_INVALID_OPERATION} is generated if | |
2609 | @code{glCompressedTexImage1D} is executed between the execution of | |
2610 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
2611 | ||
2612 | Undefined results, including abnormal program termination, are generated | |
2613 | if @var{data} is not encoded in a manner consistent with the extension | |
2614 | specification defining the internal compression format. | |
2615 | ||
bb894c9d | 2616 | @end deftypefun |
8925f36f | 2617 | |
bb894c9d | 2618 | @deftypefun void glCompressedTexImage2D target level internalformat width height border imageSize data |
3c9b6116 AW |
2619 | Specify a two-dimensional texture image in a compressed format. |
2620 | ||
8925f36f AW |
2621 | @table @asis |
2622 | @item @var{target} | |
2623 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, | |
2624 | @code{GL_PROXY_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
2625 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
2626 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
2627 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
2628 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, | |
2629 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or | |
2630 | @code{GL_PROXY_TEXTURE_CUBE_MAP}. | |
2631 | ||
2632 | @item @var{level} | |
2633 | Specifies the level-of-detail number. Level 0 is the base image level. | |
2634 | Level @var{n} is the @var{n}th mipmap reduction image. | |
2635 | ||
2636 | @item @var{internalformat} | |
2637 | Specifies the format of the compressed image data stored at address | |
2638 | @var{data}. | |
2639 | ||
2640 | @item @var{width} | |
2641 | Specifies the width of the texture image including the border if any. If | |
2642 | the GL version does not support non-power-of-two sizes, this value must | |
3c9b6116 AW |
2643 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
2644 | implementations support 2D texture images that are at least 64 texels | |
2645 | wide and cube-mapped texture images that are at least 16 texels wide. | |
8925f36f AW |
2646 | |
2647 | @item @var{height} | |
2648 | Specifies the height of the texture image including the border if any. | |
2649 | If the GL version does not support non-power-of-two sizes, this value | |
3c9b6116 AW |
2650 | must be Must be @r{2^@var{n}+2(@var{border},)} for some integer |
2651 | @r{@var{n}}. All implementations support 2D texture images that are at | |
2652 | least 64 texels high and cube-mapped texture images that are at least 16 | |
2653 | texels high. | |
8925f36f AW |
2654 | |
2655 | @item @var{border} | |
2656 | Specifies the width of the border. Must be either 0 or 1. | |
2657 | ||
2658 | @item @var{imageSize} | |
2659 | Specifies the number of unsigned bytes of image data starting at the | |
2660 | address specified by @var{data}. | |
2661 | ||
2662 | @item @var{data} | |
2663 | Specifies a pointer to the compressed image data in memory. | |
2664 | ||
2665 | @end table | |
2666 | ||
8925f36f AW |
2667 | Texturing maps a portion of a specified texture image onto each |
2668 | graphical primitive for which texturing is enabled. To enable and | |
2669 | disable two-dimensional texturing, call @code{glEnable} and | |
2670 | @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and | |
2671 | disable texturing using cube-mapped textures, call @code{glEnable} and | |
2672 | @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}. | |
2673 | ||
2674 | @code{glCompressedTexImage2D} loads a previously defined, and retrieved, | |
2675 | compressed two-dimensional texture image if @var{target} is | |
2676 | @code{GL_TEXTURE_2D} (see @code{glTexImage2D}). | |
2677 | ||
2678 | If @var{target} is @code{GL_PROXY_TEXTURE_2D}, no data is read from | |
2679 | @var{data}, but all of the texture image state is recalculated, checked | |
2680 | for consistency, and checked against the implementation's capabilities. | |
2681 | If the implementation cannot handle a texture of the requested texture | |
2682 | size, it sets all of the image state to 0, but does not generate an | |
2683 | error (see @code{glGetError}). To query for an entire mipmap array, use | |
2684 | an image array level greater than or equal to 1. | |
2685 | ||
2686 | @var{internalformat} must be an extension-specified compressed-texture | |
2687 | format. When a texture is loaded with @code{glTexImage2D} using a | |
2688 | generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}), the | |
2689 | GL selects from one of its extensions supporting compressed textures. In | |
2690 | order to load the compressed texture image using | |
2691 | @code{glCompressedTexImage2D}, query the compressed texture image's size | |
2692 | and format using @code{glGetTexLevelParameter}. | |
2693 | ||
2694 | If a non-zero named buffer object is bound to the | |
2695 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2696 | texture image is specified, @var{data} is treated as a byte offset into | |
2697 | the buffer object's data store. | |
2698 | ||
8925f36f AW |
2699 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of |
2700 | the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
2701 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
2702 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or | |
2703 | @code{GL_COMPRESSED_RGBA}. | |
2704 | ||
2705 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
2706 | consistent with the format, dimensions, and contents of the specified | |
2707 | compressed image data. | |
2708 | ||
2709 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
2710 | not supported by the specific compressed internal format as specified in | |
2711 | the specific texture compression extension. | |
2712 | ||
2713 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2714 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2715 | object's data store is currently mapped. | |
2716 | ||
2717 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2718 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2719 | would be unpacked from the buffer object such that the memory reads | |
2720 | required would exceed the data store size. | |
2721 | ||
2722 | @code{GL_INVALID_OPERATION} is generated if | |
2723 | @code{glCompressedTexImage2D} is executed between the execution of | |
2724 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
2725 | ||
2726 | Undefined results, including abnormal program termination, are generated | |
2727 | if @var{data} is not encoded in a manner consistent with the extension | |
2728 | specification defining the internal compression format. | |
2729 | ||
bb894c9d | 2730 | @end deftypefun |
8925f36f | 2731 | |
bb894c9d | 2732 | @deftypefun void glCompressedTexImage3D target level internalformat width height depth border imageSize data |
3c9b6116 AW |
2733 | Specify a three-dimensional texture image in a compressed format. |
2734 | ||
8925f36f AW |
2735 | @table @asis |
2736 | @item @var{target} | |
2737 | Specifies the target texture. Must be @code{GL_TEXTURE_3D} or | |
2738 | @code{GL_PROXY_TEXTURE_3D}. | |
2739 | ||
2740 | @item @var{level} | |
2741 | Specifies the level-of-detail number. Level 0 is the base image level. | |
2742 | Level @var{n} is the @var{n}th mipmap reduction image. | |
2743 | ||
2744 | @item @var{internalformat} | |
2745 | Specifies the format of the compressed image data stored at address | |
2746 | @var{data}. | |
2747 | ||
2748 | @item @var{width} | |
2749 | Specifies the width of the texture image including the border if any. If | |
2750 | the GL version does not support non-power-of-two sizes, this value must | |
3c9b6116 AW |
2751 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
2752 | implementations support 3D texture images that are at least 16 texels | |
2753 | wide. | |
8925f36f AW |
2754 | |
2755 | @item @var{height} | |
2756 | Specifies the height of the texture image including the border if any. | |
2757 | If the GL version does not support non-power-of-two sizes, this value | |
3c9b6116 AW |
2758 | must be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. |
2759 | All implementations support 3D texture images that are at least 16 | |
2760 | texels high. | |
8925f36f AW |
2761 | |
2762 | @item @var{depth} | |
2763 | Specifies the depth of the texture image including the border if any. If | |
2764 | the GL version does not support non-power-of-two sizes, this value must | |
3c9b6116 AW |
2765 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
2766 | implementations support 3D texture images that are at least 16 texels | |
2767 | deep. | |
8925f36f AW |
2768 | |
2769 | @item @var{border} | |
2770 | Specifies the width of the border. Must be either 0 or 1. | |
2771 | ||
2772 | @item @var{imageSize} | |
2773 | Specifies the number of unsigned bytes of image data starting at the | |
2774 | address specified by @var{data}. | |
2775 | ||
2776 | @item @var{data} | |
2777 | Specifies a pointer to the compressed image data in memory. | |
2778 | ||
2779 | @end table | |
2780 | ||
8925f36f AW |
2781 | Texturing maps a portion of a specified texture image onto each |
2782 | graphical primitive for which texturing is enabled. To enable and | |
2783 | disable three-dimensional texturing, call @code{glEnable} and | |
2784 | @code{glDisable} with argument @code{GL_TEXTURE_3D}. | |
2785 | ||
2786 | @code{glCompressedTexImage3D} loads a previously defined, and retrieved, | |
2787 | compressed three-dimensional texture image if @var{target} is | |
2788 | @code{GL_TEXTURE_3D} (see @code{glTexImage3D}). | |
2789 | ||
2790 | If @var{target} is @code{GL_PROXY_TEXTURE_3D}, no data is read from | |
2791 | @var{data}, but all of the texture image state is recalculated, checked | |
2792 | for consistency, and checked against the implementation's capabilities. | |
2793 | If the implementation cannot handle a texture of the requested texture | |
2794 | size, it sets all of the image state to 0, but does not generate an | |
2795 | error (see @code{glGetError}). To query for an entire mipmap array, use | |
2796 | an image array level greater than or equal to 1. | |
2797 | ||
2798 | @var{internalformat} must be an extension-specified compressed-texture | |
2799 | format. When a texture is loaded with @code{glTexImage2D} using a | |
2800 | generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}), the | |
2801 | GL selects from one of its extensions supporting compressed textures. In | |
2802 | order to load the compressed texture image using | |
2803 | @code{glCompressedTexImage3D}, query the compressed texture image's size | |
2804 | and format using @code{glGetTexLevelParameter}. | |
2805 | ||
2806 | If a non-zero named buffer object is bound to the | |
2807 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2808 | texture image is specified, @var{data} is treated as a byte offset into | |
2809 | the buffer object's data store. | |
2810 | ||
8925f36f AW |
2811 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of |
2812 | the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
2813 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
2814 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or | |
2815 | @code{GL_COMPRESSED_RGBA}. | |
2816 | ||
2817 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
2818 | consistent with the format, dimensions, and contents of the specified | |
2819 | compressed image data. | |
2820 | ||
2821 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
2822 | not supported by the specific compressed internal format as specified in | |
2823 | the specific texture compression extension. | |
2824 | ||
2825 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2826 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2827 | object's data store is currently mapped. | |
2828 | ||
2829 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2830 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2831 | would be unpacked from the buffer object such that the memory reads | |
2832 | required would exceed the data store size. | |
2833 | ||
2834 | @code{GL_INVALID_OPERATION} is generated if | |
2835 | @code{glCompressedTexImage3D} is executed between the execution of | |
2836 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
2837 | ||
2838 | Undefined results, including abnormal program termination, are generated | |
2839 | if @var{data} is not encoded in a manner consistent with the extension | |
2840 | specification defining the internal compression format. | |
2841 | ||
bb894c9d | 2842 | @end deftypefun |
8925f36f | 2843 | |
bb894c9d | 2844 | @deftypefun void glCompressedTexSubImage1D target level xoffset width format imageSize data |
3c9b6116 AW |
2845 | Specify a one-dimensional texture subimage in a compressed format. |
2846 | ||
8925f36f AW |
2847 | @table @asis |
2848 | @item @var{target} | |
2849 | Specifies the target texture. Must be @code{GL_TEXTURE_1D}. | |
2850 | ||
2851 | @item @var{level} | |
2852 | Specifies the level-of-detail number. Level 0 is the base image level. | |
2853 | Level @var{n} is the @var{n}th mipmap reduction image. | |
2854 | ||
2855 | @item @var{xoffset} | |
2856 | Specifies a texel offset in the x direction within the texture array. | |
2857 | ||
2858 | @item @var{width} | |
2859 | Specifies the width of the texture subimage. | |
2860 | ||
2861 | @item @var{format} | |
2862 | Specifies the format of the compressed image data stored at address | |
2863 | @var{data}. | |
2864 | ||
2865 | @item @var{imageSize} | |
2866 | Specifies the number of unsigned bytes of image data starting at the | |
2867 | address specified by @var{data}. | |
2868 | ||
2869 | @item @var{data} | |
2870 | Specifies a pointer to the compressed image data in memory. | |
2871 | ||
2872 | @end table | |
2873 | ||
8925f36f AW |
2874 | Texturing maps a portion of a specified texture image onto each |
2875 | graphical primitive for which texturing is enabled. To enable and | |
2876 | disable one-dimensional texturing, call @code{glEnable} and | |
2877 | @code{glDisable} with argument @code{GL_TEXTURE_1D}. | |
2878 | ||
2879 | @code{glCompressedTexSubImage1D} redefines a contiguous subregion of an | |
2880 | existing one-dimensional texture image. The texels referenced by | |
2881 | @var{data} replace the portion of the existing texture array with x | |
3c9b6116 | 2882 | indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive. |
8925f36f AW |
2883 | This region may not include any texels outside the range of the texture |
2884 | array as it was originally specified. It is not an error to specify a | |
2885 | subtexture with width of 0, but such a specification has no effect. | |
2886 | ||
2887 | @var{format} must be an extension-specified compressed-texture format. | |
2888 | The @var{format} of the compressed texture image is selected by the GL | |
2889 | implementation that compressed it (see @code{glTexImage1D}), and should | |
2890 | be queried at the time the texture was compressed with | |
2891 | @code{glGetTexLevelParameter}. | |
2892 | ||
2893 | If a non-zero named buffer object is bound to the | |
2894 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2895 | texture image is specified, @var{data} is treated as a byte offset into | |
2896 | the buffer object's data store. | |
2897 | ||
8925f36f AW |
2898 | @code{GL_INVALID_ENUM} is generated if @var{format} is one of these |
2899 | generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
2900 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
2901 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
2902 | @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE}, | |
2903 | @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB}, | |
2904 | @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}. | |
2905 | ||
2906 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
2907 | consistent with the format, dimensions, and contents of the specified | |
2908 | compressed image data. | |
2909 | ||
2910 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
2911 | not supported by the specific compressed internal format as specified in | |
2912 | the specific texture compression extension. | |
2913 | ||
2914 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2915 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2916 | object's data store is currently mapped. | |
2917 | ||
2918 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2919 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2920 | would be unpacked from the buffer object such that the memory reads | |
2921 | required would exceed the data store size. | |
2922 | ||
2923 | @code{GL_INVALID_OPERATION} is generated if | |
2924 | @code{glCompressedTexSubImage1D} is executed between the execution of | |
2925 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
2926 | ||
2927 | Undefined results, including abnormal program termination, are generated | |
2928 | if @var{data} is not encoded in a manner consistent with the extension | |
2929 | specification defining the internal compression format. | |
2930 | ||
bb894c9d | 2931 | @end deftypefun |
8925f36f | 2932 | |
bb894c9d | 2933 | @deftypefun void glCompressedTexSubImage2D target level xoffset yoffset width height format imageSize data |
3c9b6116 AW |
2934 | Specify a two-dimensional texture subimage in a compressed format. |
2935 | ||
8925f36f AW |
2936 | @table @asis |
2937 | @item @var{target} | |
2938 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, | |
2939 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
2940 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
2941 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
2942 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
2943 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
2944 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
2945 | ||
2946 | @item @var{level} | |
2947 | Specifies the level-of-detail number. Level 0 is the base image level. | |
2948 | Level @var{n} is the @var{n}th mipmap reduction image. | |
2949 | ||
2950 | @item @var{xoffset} | |
2951 | Specifies a texel offset in the x direction within the texture array. | |
2952 | ||
2953 | @item @var{yoffset} | |
2954 | Specifies a texel offset in the y direction within the texture array. | |
2955 | ||
2956 | @item @var{width} | |
2957 | Specifies the width of the texture subimage. | |
2958 | ||
2959 | @item @var{height} | |
2960 | Specifies the height of the texture subimage. | |
2961 | ||
2962 | @item @var{format} | |
2963 | Specifies the format of the compressed image data stored at address | |
2964 | @var{data}. | |
2965 | ||
2966 | @item @var{imageSize} | |
2967 | Specifies the number of unsigned bytes of image data starting at the | |
2968 | address specified by @var{data}. | |
2969 | ||
2970 | @item @var{data} | |
2971 | Specifies a pointer to the compressed image data in memory. | |
2972 | ||
2973 | @end table | |
2974 | ||
8925f36f AW |
2975 | Texturing maps a portion of a specified texture image onto each |
2976 | graphical primitive for which texturing is enabled. To enable and | |
2977 | disable two-dimensional texturing, call @code{glEnable} and | |
2978 | @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and | |
2979 | disable texturing using cube-mapped texture, call @code{glEnable} and | |
2980 | @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}. | |
2981 | ||
2982 | @code{glCompressedTexSubImage2D} redefines a contiguous subregion of an | |
2983 | existing two-dimensional texture image. The texels referenced by | |
2984 | @var{data} replace the portion of the existing texture array with x | |
3c9b6116 AW |
2985 | indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, and the y |
2986 | indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive. | |
2987 | This region may not include any texels outside the range of the texture | |
2988 | array as it was originally specified. It is not an error to specify a | |
2989 | subtexture with width of 0, but such a specification has no effect. | |
8925f36f AW |
2990 | |
2991 | @var{format} must be an extension-specified compressed-texture format. | |
2992 | The @var{format} of the compressed texture image is selected by the GL | |
2993 | implementation that compressed it (see @code{glTexImage2D}) and should | |
2994 | be queried at the time the texture was compressed with | |
2995 | @code{glGetTexLevelParameter}. | |
2996 | ||
2997 | If a non-zero named buffer object is bound to the | |
2998 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2999 | texture image is specified, @var{data} is treated as a byte offset into | |
3000 | the buffer object's data store. | |
3001 | ||
8925f36f AW |
3002 | @code{GL_INVALID_ENUM} is generated if @var{format} is one of these |
3003 | generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
3004 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
3005 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
3006 | @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE}, | |
3007 | @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB}, | |
3008 | @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}. | |
3009 | ||
3010 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
3011 | consistent with the format, dimensions, and contents of the specified | |
3012 | compressed image data. | |
3013 | ||
3014 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
3015 | not supported by the specific compressed internal format as specified in | |
3016 | the specific texture compression extension. | |
3017 | ||
3018 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3019 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
3020 | object's data store is currently mapped. | |
3021 | ||
3022 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3023 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
3024 | would be unpacked from the buffer object such that the memory reads | |
3025 | required would exceed the data store size. | |
3026 | ||
3027 | @code{GL_INVALID_OPERATION} is generated if | |
3028 | @code{glCompressedTexSubImage2D} is executed between the execution of | |
3029 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
3030 | ||
3031 | Undefined results, including abnormal program termination, are generated | |
3032 | if @var{data} is not encoded in a manner consistent with the extension | |
3033 | specification defining the internal compression format. | |
3034 | ||
bb894c9d | 3035 | @end deftypefun |
8925f36f | 3036 | |
bb894c9d | 3037 | @deftypefun void glCompressedTexSubImage3D target level xoffset yoffset zoffset width height depth format imageSize data |
3c9b6116 AW |
3038 | Specify a three-dimensional texture subimage in a compressed format. |
3039 | ||
8925f36f AW |
3040 | @table @asis |
3041 | @item @var{target} | |
3042 | Specifies the target texture. Must be @code{GL_TEXTURE_3D}. | |
3043 | ||
3044 | @item @var{level} | |
3045 | Specifies the level-of-detail number. Level 0 is the base image level. | |
3046 | Level @var{n} is the @var{n}th mipmap reduction image. | |
3047 | ||
3048 | @item @var{xoffset} | |
3049 | Specifies a texel offset in the x direction within the texture array. | |
3050 | ||
3051 | @item @var{yoffset} | |
3052 | Specifies a texel offset in the y direction within the texture array. | |
3053 | ||
3054 | @item @var{width} | |
3055 | Specifies the width of the texture subimage. | |
3056 | ||
3057 | @item @var{height} | |
3058 | Specifies the height of the texture subimage. | |
3059 | ||
3060 | @item @var{depth} | |
3061 | Specifies the depth of the texture subimage. | |
3062 | ||
3063 | @item @var{format} | |
3064 | Specifies the format of the compressed image data stored at address | |
3065 | @var{data}. | |
3066 | ||
3067 | @item @var{imageSize} | |
3068 | Specifies the number of unsigned bytes of image data starting at the | |
3069 | address specified by @var{data}. | |
3070 | ||
3071 | @item @var{data} | |
3072 | Specifies a pointer to the compressed image data in memory. | |
3073 | ||
3074 | @end table | |
3075 | ||
8925f36f AW |
3076 | Texturing maps a portion of a specified texture image onto each |
3077 | graphical primitive for which texturing is enabled. To enable and | |
3078 | disable three-dimensional texturing, call @code{glEnable} and | |
3079 | @code{glDisable} with argument @code{GL_TEXTURE_3D}. | |
3080 | ||
3081 | @code{glCompressedTexSubImage3D} redefines a contiguous subregion of an | |
3082 | existing three-dimensional texture image. The texels referenced by | |
3083 | @var{data} replace the portion of the existing texture array with x | |
3c9b6116 AW |
3084 | indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, and the y |
3085 | indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, and the z | |
3086 | indices @var{zoffset} and @r{@var{zoffset}+@var{depth}-1}, inclusive. | |
8925f36f AW |
3087 | This region may not include any texels outside the range of the texture |
3088 | array as it was originally specified. It is not an error to specify a | |
3089 | subtexture with width of 0, but such a specification has no effect. | |
3090 | ||
3091 | @var{format} must be an extension-specified compressed-texture format. | |
3092 | The @var{format} of the compressed texture image is selected by the GL | |
3093 | implementation that compressed it (see @code{glTexImage3D}) and should | |
3094 | be queried at the time the texture was compressed with | |
3095 | @code{glGetTexLevelParameter}. | |
3096 | ||
3097 | If a non-zero named buffer object is bound to the | |
3098 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
3099 | texture image is specified, @var{data} is treated as a byte offset into | |
3100 | the buffer object's data store. | |
3101 | ||
8925f36f AW |
3102 | @code{GL_INVALID_ENUM} is generated if @var{format} is one of these |
3103 | generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
3104 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
3105 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
3106 | @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE}, | |
3107 | @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB}, | |
3108 | @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}. | |
3109 | ||
3110 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
3111 | consistent with the format, dimensions, and contents of the specified | |
3112 | compressed image data. | |
3113 | ||
3114 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
3115 | not supported by the specific compressed internal format as specified in | |
3116 | the specific texture compression extension. | |
3117 | ||
3118 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3119 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
3120 | object's data store is currently mapped. | |
3121 | ||
3122 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3123 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
3124 | would be unpacked from the buffer object such that the memory reads | |
3125 | required would exceed the data store size. | |
3126 | ||
3127 | @code{GL_INVALID_OPERATION} is generated if | |
3128 | @code{glCompressedTexSubImage3D} is executed between the execution of | |
3129 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
3130 | ||
3131 | Undefined results, including abnormal program termination, are generated | |
3132 | if @var{data} is not encoded in a manner consistent with the extension | |
3133 | specification defining the internal compression format. | |
3134 | ||
bb894c9d | 3135 | @end deftypefun |
8925f36f | 3136 | |
bb894c9d | 3137 | @deftypefun void glConvolutionFilter1D target internalformat width format type data |
3c9b6116 AW |
3138 | Define a one-dimensional convolution filter. |
3139 | ||
8925f36f AW |
3140 | @table @asis |
3141 | @item @var{target} | |
3142 | Must be @code{GL_CONVOLUTION_1D}. | |
3143 | ||
3144 | @item @var{internalformat} | |
3145 | The internal format of the convolution filter kernel. The allowable | |
3146 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, | |
3147 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
3148 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
3149 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3150 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3151 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3152 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3153 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3154 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3155 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3156 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3157 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3158 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3159 | ||
3160 | @item @var{width} | |
3161 | The width of the pixel array referenced by @var{data}. | |
3162 | ||
3163 | @item @var{format} | |
3164 | The format of the pixel data in @var{data}. The allowable values are | |
3165 | @code{GL_ALPHA}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, | |
3166 | @code{GL_INTENSITY}, @code{GL_RGB}, and @code{GL_RGBA}. | |
3167 | ||
3168 | @item @var{type} | |
3169 | The type of the pixel data in @var{data}. Symbolic constants | |
3170 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
3171 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
3172 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
3173 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
3174 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
3175 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
3176 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
3177 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
3178 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
3179 | ||
3180 | @item @var{data} | |
3181 | Pointer to a one-dimensional array of pixel data that is processed to | |
3182 | build the convolution filter kernel. | |
3183 | ||
3184 | @end table | |
3185 | ||
8925f36f AW |
3186 | @code{glConvolutionFilter1D} builds a one-dimensional convolution filter |
3187 | kernel from an array of pixels. | |
3188 | ||
3189 | The pixel array specified by @var{width}, @var{format}, @var{type}, and | |
3190 | @var{data} is extracted from memory and processed just as if | |
3191 | @code{glDrawPixels} were called, but processing stops after the final | |
3192 | expansion to RGBA is completed. | |
3193 | ||
3194 | If a non-zero named buffer object is bound to the | |
3195 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
3196 | convolution filter is specified, @var{data} is treated as a byte offset | |
3197 | into the buffer object's data store. | |
3198 | ||
3199 | The R, G, B, and A components of each pixel are next scaled by the four | |
3200 | 1D @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four | |
3201 | 1D @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias | |
3202 | parameters are set by @code{glConvolutionParameter} using the | |
3203 | @code{GL_CONVOLUTION_1D} target and the names | |
3204 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
3205 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors | |
3206 | of four values that are applied to red, green, blue, and alpha, in that | |
3207 | order.) The R, G, B, and A values are not clamped to [0,1] at any time | |
3208 | during this process. | |
3209 | ||
3210 | Each pixel is then converted to the internal format specified by | |
3211 | @var{internalformat}. This conversion simply maps the component values | |
3212 | of the pixel (R, G, B, and A) to the values included in the internal | |
3213 | format (red, green, blue, alpha, luminance, and intensity). The mapping | |
3214 | is as follows: | |
3215 | ||
3216 | ||
3217 | ||
3218 | @table @asis | |
3219 | @item @strong{Internal Format} | |
3220 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
3221 | @strong{Luminance}, @strong{Intensity} | |
3222 | ||
3223 | @item @code{GL_ALPHA} | |
3224 | , , , A , , | |
3225 | ||
3226 | @item @code{GL_LUMINANCE} | |
3227 | , , , , R , | |
3228 | ||
3229 | @item @code{GL_LUMINANCE_ALPHA} | |
3230 | , , , A , R , | |
3231 | ||
3232 | @item @code{GL_INTENSITY} | |
3233 | , , , , , R | |
3234 | ||
3235 | @item @code{GL_RGB} | |
3236 | R , G , B , , , | |
3237 | ||
3238 | @item @code{GL_RGBA} | |
3239 | R , G , B , A , , | |
3240 | ||
3241 | @end table | |
3242 | ||
3243 | The red, green, blue, alpha, luminance, and/or intensity components of | |
3244 | the resulting pixels are stored in floating-point rather than integer | |
3245 | format. They form a one-dimensional filter kernel image indexed with | |
3246 | coordinate @var{i} such that @var{i} starts at 0 and increases from left | |
3247 | to right. Kernel location @var{i} is derived from the @var{i}th pixel, | |
3248 | counting from 0. | |
3249 | ||
3250 | Note that after a convolution is performed, the resulting color | |
3251 | components are also scaled by their corresponding | |
3252 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
3253 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
3254 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
3255 | and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}. | |
3256 | ||
8925f36f AW |
3257 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
3258 | @code{GL_CONVOLUTION_1D}. | |
3259 | ||
3260 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
3261 | of the allowable values. | |
3262 | ||
3263 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
3264 | allowable values. | |
3265 | ||
3266 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
3267 | allowable values. | |
3268 | ||
3269 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
3270 | greater than the maximum supported value. This value may be queried with | |
3271 | @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_1D} | |
3272 | and name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
3273 | ||
3274 | @code{GL_INVALID_OPERATION} is generated if @var{format} is one of | |
3275 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
3276 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
3277 | and @var{type} is not @code{GL_RGB}. | |
3278 | ||
3279 | @code{GL_INVALID_OPERATION} is generated if @var{format} is one of | |
3280 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
3281 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
3282 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
3283 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
3284 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{type} is neither | |
3285 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
3286 | ||
3287 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3288 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
3289 | object's data store is currently mapped. | |
3290 | ||
3291 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3292 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
3293 | would be unpacked from the buffer object such that the memory reads | |
3294 | required would exceed the data store size. | |
3295 | ||
3296 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3297 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
3298 | is not evenly divisible into the number of bytes needed to store in | |
3299 | memory a datum indicated by @var{type}. | |
3300 | ||
3301 | @code{GL_INVALID_OPERATION} is generated if @code{glConvolutionFilter1D} | |
3302 | is executed between the execution of @code{glBegin} and the | |
3303 | corresponding execution of @code{glEnd}. | |
3304 | ||
bb894c9d | 3305 | @end deftypefun |
8925f36f | 3306 | |
bb894c9d | 3307 | @deftypefun void glConvolutionFilter2D target internalformat width height format type data |
3c9b6116 AW |
3308 | Define a two-dimensional convolution filter. |
3309 | ||
8925f36f AW |
3310 | @table @asis |
3311 | @item @var{target} | |
3312 | Must be @code{GL_CONVOLUTION_2D}. | |
3313 | ||
3314 | @item @var{internalformat} | |
3315 | The internal format of the convolution filter kernel. The allowable | |
3316 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, | |
3317 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
3318 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
3319 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3320 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3321 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3322 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3323 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3324 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3325 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3326 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3327 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3328 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3329 | ||
3330 | @item @var{width} | |
3331 | The width of the pixel array referenced by @var{data}. | |
3332 | ||
3333 | @item @var{height} | |
3334 | The height of the pixel array referenced by @var{data}. | |
3335 | ||
3336 | @item @var{format} | |
3337 | The format of the pixel data in @var{data}. The allowable values are | |
3338 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, | |
3339 | @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, | |
3340 | @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA}. | |
3341 | ||
3342 | @item @var{type} | |
3343 | The type of the pixel data in @var{data}. Symbolic constants | |
3344 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
3345 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
3346 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
3347 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
3348 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
3349 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
3350 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
3351 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
3352 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
3353 | ||
3354 | @item @var{data} | |
3355 | Pointer to a two-dimensional array of pixel data that is processed to | |
3356 | build the convolution filter kernel. | |
3357 | ||
3358 | @end table | |
3359 | ||
8925f36f AW |
3360 | @code{glConvolutionFilter2D} builds a two-dimensional convolution filter |
3361 | kernel from an array of pixels. | |
3362 | ||
3363 | The pixel array specified by @var{width}, @var{height}, @var{format}, | |
3364 | @var{type}, and @var{data} is extracted from memory and processed just | |
3365 | as if @code{glDrawPixels} were called, but processing stops after the | |
3366 | final expansion to RGBA is completed. | |
3367 | ||
3368 | If a non-zero named buffer object is bound to the | |
3369 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
3370 | convolution filter is specified, @var{data} is treated as a byte offset | |
3371 | into the buffer object's data store. | |
3372 | ||
3373 | The R, G, B, and A components of each pixel are next scaled by the four | |
3374 | 2D @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four | |
3375 | 2D @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias | |
3376 | parameters are set by @code{glConvolutionParameter} using the | |
3377 | @code{GL_CONVOLUTION_2D} target and the names | |
3378 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
3379 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors | |
3380 | of four values that are applied to red, green, blue, and alpha, in that | |
3381 | order.) The R, G, B, and A values are not clamped to [0,1] at any time | |
3382 | during this process. | |
3383 | ||
3384 | Each pixel is then converted to the internal format specified by | |
3385 | @var{internalformat}. This conversion simply maps the component values | |
3386 | of the pixel (R, G, B, and A) to the values included in the internal | |
3387 | format (red, green, blue, alpha, luminance, and intensity). The mapping | |
3388 | is as follows: | |
3389 | ||
3390 | ||
3391 | ||
3392 | @table @asis | |
3393 | @item @strong{Internal Format} | |
3394 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
3395 | @strong{Luminance}, @strong{Intensity} | |
3396 | ||
3397 | @item @code{GL_ALPHA} | |
3398 | , , , A , , | |
3399 | ||
3400 | @item @code{GL_LUMINANCE} | |
3401 | , , , , R , | |
3402 | ||
3403 | @item @code{GL_LUMINANCE_ALPHA} | |
3404 | , , , A , R , | |
3405 | ||
3406 | @item @code{GL_INTENSITY} | |
3407 | , , , , , R | |
3408 | ||
3409 | @item @code{GL_RGB} | |
3410 | R , G , B , , , | |
3411 | ||
3412 | @item @code{GL_RGBA} | |
3413 | R , G , B , A , , | |
3414 | ||
3415 | @end table | |
3416 | ||
3417 | The red, green, blue, alpha, luminance, and/or intensity components of | |
3418 | the resulting pixels are stored in floating-point rather than integer | |
3419 | format. They form a two-dimensional filter kernel image indexed with | |
3420 | coordinates @var{i} and @var{j} such that @var{i} starts at zero and | |
3421 | increases from left to right, and @var{j} starts at zero and increases | |
3422 | from bottom to top. Kernel location @var{i,j} is derived from the | |
3423 | @var{N}th pixel, where @var{N} is @var{i}+@var{j}*@var{width}. | |
3424 | ||
3425 | Note that after a convolution is performed, the resulting color | |
3426 | components are also scaled by their corresponding | |
3427 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
3428 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
3429 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
3430 | and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}. | |
3431 | ||
8925f36f AW |
3432 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
3433 | @code{GL_CONVOLUTION_2D}. | |
3434 | ||
3435 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
3436 | of the allowable values. | |
3437 | ||
3438 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
3439 | allowable values. | |
3440 | ||
3441 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
3442 | allowable values. | |
3443 | ||
3444 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
3445 | greater than the maximum supported value. This value may be queried with | |
3446 | @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_2D} | |
3447 | and name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
3448 | ||
3449 | @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero | |
3450 | or greater than the maximum supported value. This value may be queried | |
3451 | with @code{glGetConvolutionParameter} using target | |
3452 | @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}. | |
3453 | ||
3454 | @code{GL_INVALID_OPERATION} is generated if @var{height} is one of | |
3455 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
3456 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
3457 | and @var{format} is not @code{GL_RGB}. | |
3458 | ||
3459 | @code{GL_INVALID_OPERATION} is generated if @var{height} is one of | |
3460 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
3461 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
3462 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
3463 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
3464 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
3465 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
3466 | ||
3467 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3468 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
3469 | object's data store is currently mapped. | |
3470 | ||
3471 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3472 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
3473 | would be unpacked from the buffer object such that the memory reads | |
3474 | required would exceed the data store size. | |
3475 | ||
3476 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3477 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
3478 | is not evenly divisible into the number of bytes needed to store in | |
3479 | memory a datum indicated by @var{type}. | |
3480 | ||
3481 | @code{GL_INVALID_OPERATION} is generated if @code{glConvolutionFilter2D} | |
3482 | is executed between the execution of @code{glBegin} and the | |
3483 | corresponding execution of @code{glEnd}. | |
3484 | ||
bb894c9d | 3485 | @end deftypefun |
8925f36f | 3486 | |
bb894c9d AW |
3487 | @deftypefun void glConvolutionParameterf target pname params |
3488 | @deftypefunx void glConvolutionParameteri target pname params | |
3c9b6116 AW |
3489 | Set convolution parameters. |
3490 | ||
8925f36f AW |
3491 | @table @asis |
3492 | @item @var{target} | |
3493 | The target for the convolution parameter. Must be one of | |
3494 | @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or | |
3495 | @code{GL_SEPARABLE_2D}. | |
3496 | ||
3497 | @item @var{pname} | |
3498 | The parameter to be set. Must be @code{GL_CONVOLUTION_BORDER_MODE}. | |
3499 | ||
3500 | @item @var{params} | |
3501 | The parameter value. Must be one of @code{GL_REDUCE}, | |
3502 | @code{GL_CONSTANT_BORDER}, @code{GL_REPLICATE_BORDER}. | |
3503 | ||
3504 | ||
3505 | ||
3506 | @end table | |
3507 | ||
8925f36f AW |
3508 | @code{glConvolutionParameter} sets the value of a convolution parameter. |
3509 | ||
3510 | @var{target} selects the convolution filter to be affected: | |
3511 | @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or | |
3512 | @code{GL_SEPARABLE_2D} for the 1D, 2D, or separable 2D filter, | |
3513 | respectively. | |
3514 | ||
3515 | @var{pname} selects the parameter to be changed. | |
3516 | @code{GL_CONVOLUTION_FILTER_SCALE} and @code{GL_CONVOLUTION_FILTER_BIAS} | |
3517 | affect the definition of the convolution filter kernel; see | |
3518 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and | |
3519 | @code{glSeparableFilter2D} for details. In these cases, @var{params}v is | |
3520 | an array of four values to be applied to red, green, blue, and alpha | |
3521 | values, respectively. The initial value for | |
3522 | @code{GL_CONVOLUTION_FILTER_SCALE} is (1, 1, 1, 1), and the initial | |
3523 | value for @code{GL_CONVOLUTION_FILTER_BIAS} is (0, 0, 0, 0). | |
3524 | ||
3525 | A @var{pname} value of @code{GL_CONVOLUTION_BORDER_MODE} controls the | |
3526 | convolution border mode. The accepted modes are: | |
3527 | ||
3528 | @table @asis | |
3529 | @item @code{GL_REDUCE} | |
3530 | The image resulting from convolution is smaller than the source image. | |
3c9b6116 AW |
3531 | If the filter width is @r{@var{Wf}} and height is @r{@var{Hf}}, and the |
3532 | source image width is @r{@var{Ws}} and height is @r{@var{Hs}}, then the | |
3533 | convolved image width will be @r{@var{Ws}-@var{Wf}+1} and height will be | |
3534 | @r{@var{Hs}-@var{Hf}+1}. (If this reduction would generate an image with | |
3535 | zero or negative width and/or height, the output is simply null, with no | |
3536 | error generated.) The coordinates of the image resulting from | |
3537 | convolution are zero through @r{@var{Ws}-@var{Wf}} in width and zero | |
3538 | through @r{@var{Hs}-@var{Hf}} in height. | |
8925f36f AW |
3539 | |
3540 | @item @code{GL_CONSTANT_BORDER} | |
3541 | The image resulting from convolution is the same size as the source | |
3542 | image, and processed as if the source image were surrounded by pixels | |
3543 | with their color specified by the @code{GL_CONVOLUTION_BORDER_COLOR}. | |
3544 | ||
3545 | @item @code{GL_REPLICATE_BORDER} | |
3546 | The image resulting from convolution is the same size as the source | |
3547 | image, and processed as if the outermost pixel on the border of the | |
3548 | source image were replicated. | |
3549 | ||
3550 | @end table | |
3551 | ||
8925f36f AW |
3552 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
3553 | allowable values. | |
3554 | ||
3555 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the | |
3556 | allowable values. | |
3557 | ||
3558 | @code{GL_INVALID_ENUM} is generated if @var{pname} is | |
3559 | @code{GL_CONVOLUTION_BORDER_MODE} and @var{params} is not one of | |
3560 | @code{GL_REDUCE}, @code{GL_CONSTANT_BORDER}, or | |
3561 | @code{GL_REPLICATE_BORDER}. | |
3562 | ||
3563 | @code{GL_INVALID_OPERATION} is generated if | |
3564 | @code{glConvolutionParameter} is executed between the execution of | |
3565 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
3566 | ||
bb894c9d | 3567 | @end deftypefun |
8925f36f | 3568 | |
bb894c9d | 3569 | @deftypefun void glCopyColorSubTable target start x y width |
3c9b6116 AW |
3570 | Respecify a portion of a color table. |
3571 | ||
8925f36f AW |
3572 | @table @asis |
3573 | @item @var{target} | |
3574 | Must be one of @code{GL_COLOR_TABLE}, | |
3575 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or | |
3576 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
3577 | ||
3578 | @item @var{start} | |
3579 | The starting index of the portion of the color table to be replaced. | |
3580 | ||
3581 | @item @var{x} | |
3582 | @itemx @var{y} | |
3583 | The window coordinates of the left corner of the row of pixels to be | |
3584 | copied. | |
3585 | ||
3586 | @item @var{width} | |
3587 | The number of table entries to replace. | |
3588 | ||
3589 | @end table | |
3590 | ||
8925f36f AW |
3591 | @code{glCopyColorSubTable} is used to respecify a contiguous portion of |
3592 | a color table previously defined using @code{glColorTable}. The pixels | |
3593 | copied from the framebuffer replace the portion of the existing table | |
3c9b6116 AW |
3594 | from indices @var{start} to @r{@var{start}+@var{x}-1}, inclusive. This |
3595 | region may not include any entries outside the range of the color table, | |
3596 | as was originally specified. It is not an error to specify a subtexture | |
3597 | with width of 0, but such a specification has no effect. | |
8925f36f | 3598 | |
8925f36f AW |
3599 | @code{GL_INVALID_VALUE} is generated if @var{target} is not a previously |
3600 | defined color table. | |
3601 | ||
3602 | @code{GL_INVALID_VALUE} is generated if @var{target} is not one of the | |
3603 | allowable values. | |
3604 | ||
3605 | @code{GL_INVALID_VALUE} is generated if | |
3c9b6116 | 3606 | @r{@var{start}+@var{x}>@var{width}}. |
8925f36f AW |
3607 | |
3608 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyColorSubTable} | |
3609 | is executed between the execution of @code{glBegin} and the | |
3610 | corresponding execution of @code{glEnd}. | |
3611 | ||
bb894c9d | 3612 | @end deftypefun |
8925f36f | 3613 | |
bb894c9d | 3614 | @deftypefun void glCopyColorTable target internalformat x y width |
3c9b6116 AW |
3615 | Copy pixels into a color table. |
3616 | ||
8925f36f AW |
3617 | @table @asis |
3618 | @item @var{target} | |
3619 | The color table target. Must be @code{GL_COLOR_TABLE}, | |
3620 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or | |
3621 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
3622 | ||
3623 | @item @var{internalformat} | |
3624 | The internal storage format of the texture image. Must be one of the | |
3625 | following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4}, | |
3626 | @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16}, | |
3627 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, | |
3628 | @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3629 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3630 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3631 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3632 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3633 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3634 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3635 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3636 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3637 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3638 | ||
3639 | @item @var{x} | |
3640 | The x coordinate of the lower-left corner of the pixel rectangle to be | |
3641 | transferred to the color table. | |
3642 | ||
3643 | @item @var{y} | |
3644 | The y coordinate of the lower-left corner of the pixel rectangle to be | |
3645 | transferred to the color table. | |
3646 | ||
3647 | @item @var{width} | |
3648 | The width of the pixel rectangle. | |
3649 | ||
3650 | @end table | |
3651 | ||
8925f36f AW |
3652 | @code{glCopyColorTable} loads a color table with pixels from the current |
3653 | @code{GL_READ_BUFFER} (rather than from main memory, as is the case for | |
3654 | @code{glColorTable}). | |
3655 | ||
3656 | The screen-aligned pixel rectangle with lower-left corner at (@var{x},\ | |
3657 | @var{y}) having width @var{width} and height 1 is loaded into the color | |
3658 | table. If any pixels within this region are outside the window that is | |
3659 | associated with the GL context, the values obtained for those pixels are | |
3660 | undefined. | |
3661 | ||
3662 | The pixels in the rectangle are processed just as if @code{glReadPixels} | |
3663 | were called, with @var{internalformat} set to RGBA, but processing stops | |
3664 | after the final conversion to RGBA. | |
3665 | ||
3666 | The four scale parameters and the four bias parameters that are defined | |
3667 | for the table are then used to scale and bias the R, G, B, and A | |
3668 | components of each pixel. The scale and bias parameters are set by | |
3669 | calling @code{glColorTableParameter}. | |
3670 | ||
3c9b6116 AW |
3671 | Next, the R, G, B, and A values are clamped to the range @r{[0,1]}. Each |
3672 | pixel is then converted to the internal format specified by | |
8925f36f AW |
3673 | @var{internalformat}. This conversion simply maps the component values |
3674 | of the pixel (R, G, B, and A) to the values included in the internal | |
3675 | format (red, green, blue, alpha, luminance, and intensity). The mapping | |
3676 | is as follows: | |
3677 | ||
3678 | ||
3679 | ||
3680 | @table @asis | |
3681 | @item @strong{Internal Format} | |
3682 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
3683 | @strong{Luminance}, @strong{Intensity} | |
3684 | ||
3685 | @item @code{GL_ALPHA} | |
3686 | , , , A , , | |
3687 | ||
3688 | @item @code{GL_LUMINANCE} | |
3689 | , , , , R , | |
3690 | ||
3691 | @item @code{GL_LUMINANCE_ALPHA} | |
3692 | , , , A , R , | |
3693 | ||
3694 | @item @code{GL_INTENSITY} | |
3695 | , , , , , R | |
3696 | ||
3697 | @item @code{GL_RGB} | |
3698 | R , G , B , , , | |
3699 | ||
3700 | @item @code{GL_RGBA} | |
3701 | R , G , B , A , , | |
3702 | ||
3703 | @end table | |
3704 | ||
3705 | Finally, the red, green, blue, alpha, luminance, and/or intensity | |
3706 | components of the resulting pixels are stored in the color table. They | |
3707 | form a one-dimensional table with indices in the range | |
3c9b6116 | 3708 | @r{[0,@var{width}-1]}. |
8925f36f AW |
3709 | |
3710 | ||
3711 | ||
8925f36f AW |
3712 | @code{GL_INVALID_ENUM} is generated when @var{target} is not one of the |
3713 | allowable values. | |
3714 | ||
3715 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero. | |
3716 | ||
3717 | @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not one | |
3718 | of the allowable values. | |
3719 | ||
3720 | @code{GL_TABLE_TOO_LARGE} is generated if the requested color table is | |
3721 | too large to be supported by the implementation. | |
3722 | ||
3723 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyColorTable} is | |
3724 | executed between the execution of @code{glBegin} and the corresponding | |
3725 | execution of @code{glEnd}. | |
3726 | ||
bb894c9d | 3727 | @end deftypefun |
8925f36f | 3728 | |
bb894c9d | 3729 | @deftypefun void glCopyConvolutionFilter1D target internalformat x y width |
3c9b6116 AW |
3730 | Copy pixels into a one-dimensional convolution filter. |
3731 | ||
8925f36f AW |
3732 | @table @asis |
3733 | @item @var{target} | |
3734 | Must be @code{GL_CONVOLUTION_1D}. | |
3735 | ||
3736 | @item @var{internalformat} | |
3737 | The internal format of the convolution filter kernel. The allowable | |
3738 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, | |
3739 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
3740 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
3741 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3742 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3743 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3744 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3745 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3746 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3747 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3748 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3749 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3750 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3751 | ||
3752 | @item @var{x} | |
3753 | @itemx @var{y} | |
3754 | The window space coordinates of the lower-left coordinate of the pixel | |
3755 | array to copy. | |
3756 | ||
3757 | @item @var{width} | |
3758 | The width of the pixel array to copy. | |
3759 | ||
3760 | @end table | |
3761 | ||
8925f36f AW |
3762 | @code{glCopyConvolutionFilter1D} defines a one-dimensional convolution |
3763 | filter kernel with pixels from the current @code{GL_READ_BUFFER} (rather | |
3764 | than from main memory, as is the case for @code{glConvolutionFilter1D}). | |
3765 | ||
3766 | The screen-aligned pixel rectangle with lower-left corner at (@var{x},\ | |
3767 | @var{y}), width @var{width} and height 1 is used to define the | |
3768 | convolution filter. If any pixels within this region are outside the | |
3769 | window that is associated with the GL context, the values obtained for | |
3770 | those pixels are undefined. | |
3771 | ||
3772 | The pixels in the rectangle are processed exactly as if | |
3773 | @code{glReadPixels} had been called with @var{format} set to RGBA, but | |
3774 | the process stops just before final conversion. The R, G, B, and A | |
3775 | components of each pixel are next scaled by the four 1D | |
3776 | @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four 1D | |
3777 | @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias | |
3778 | parameters are set by @code{glConvolutionParameter} using the | |
3779 | @code{GL_CONVOLUTION_1D} target and the names | |
3780 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
3781 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors | |
3782 | of four values that are applied to red, green, blue, and alpha, in that | |
3783 | order.) The R, G, B, and A values are not clamped to [0,1] at any time | |
3784 | during this process. | |
3785 | ||
3786 | Each pixel is then converted to the internal format specified by | |
3787 | @var{internalformat}. This conversion simply maps the component values | |
3788 | of the pixel (R, G, B, and A) to the values included in the internal | |
3789 | format (red, green, blue, alpha, luminance, and intensity). The mapping | |
3790 | is as follows: | |
3791 | ||
3792 | ||
3793 | ||
3794 | @table @asis | |
3795 | @item @strong{Internal Format} | |
3796 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
3797 | @strong{Luminance}, @strong{Intensity} | |
3798 | ||
3799 | @item @code{GL_ALPHA} | |
3800 | , , , A , , | |
3801 | ||
3802 | @item @code{GL_LUMINANCE} | |
3803 | , , , , R , | |
3804 | ||
3805 | @item @code{GL_LUMINANCE_ALPHA} | |
3806 | , , , A , R , | |
3807 | ||
3808 | @item @code{GL_INTENSITY} | |
3809 | , , , , , R | |
3810 | ||
3811 | @item @code{GL_RGB} | |
3812 | R , G , B , , , | |
3813 | ||
3814 | @item @code{GL_RGBA} | |
3815 | R , G , B , A , , | |
3816 | ||
3817 | @end table | |
3818 | ||
3819 | The red, green, blue, alpha, luminance, and/or intensity components of | |
3820 | the resulting pixels are stored in floating-point rather than integer | |
3821 | format. | |
3822 | ||
3823 | Pixel ordering is such that lower x screen coordinates correspond to | |
3824 | lower @var{i} filter image coordinates. | |
3825 | ||
3826 | Note that after a convolution is performed, the resulting color | |
3827 | components are also scaled by their corresponding | |
3828 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
3829 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
3830 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
3831 | and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}. | |
3832 | ||
8925f36f AW |
3833 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
3834 | @code{GL_CONVOLUTION_1D}. | |
3835 | ||
3836 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
3837 | of the allowable values. | |
3838 | ||
3839 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
3840 | greater than the maximum supported value. This value may be queried with | |
3841 | @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_1D} | |
3842 | and name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
3843 | ||
3844 | @code{GL_INVALID_OPERATION} is generated if | |
3845 | @code{glCopyConvolutionFilter1D} is executed between the execution of | |
3846 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
3847 | ||
bb894c9d | 3848 | @end deftypefun |
8925f36f | 3849 | |
bb894c9d | 3850 | @deftypefun void glCopyConvolutionFilter2D target internalformat x y width height |
3c9b6116 AW |
3851 | Copy pixels into a two-dimensional convolution filter. |
3852 | ||
8925f36f AW |
3853 | @table @asis |
3854 | @item @var{target} | |
3855 | Must be @code{GL_CONVOLUTION_2D}. | |
3856 | ||
3857 | @item @var{internalformat} | |
3858 | The internal format of the convolution filter kernel. The allowable | |
3859 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, | |
3860 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
3861 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
3862 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3863 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3864 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3865 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3866 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3867 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3868 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3869 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3870 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3871 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3872 | ||
3873 | @item @var{x} | |
3874 | @itemx @var{y} | |
3875 | The window space coordinates of the lower-left coordinate of the pixel | |
3876 | array to copy. | |
3877 | ||
3878 | @item @var{width} | |
3879 | The width of the pixel array to copy. | |
3880 | ||
3881 | @item @var{height} | |
3882 | The height of the pixel array to copy. | |
3883 | ||
3884 | @end table | |
3885 | ||
8925f36f AW |
3886 | @code{glCopyConvolutionFilter2D} defines a two-dimensional convolution |
3887 | filter kernel with pixels from the current @code{GL_READ_BUFFER} (rather | |
3888 | than from main memory, as is the case for @code{glConvolutionFilter2D}). | |
3889 | ||
3890 | The screen-aligned pixel rectangle with lower-left corner at (@var{x},\ | |
3891 | @var{y}), width @var{width} and height @var{height} is used to define | |
3892 | the convolution filter. If any pixels within this region are outside the | |
3893 | window that is associated with the GL context, the values obtained for | |
3894 | those pixels are undefined. | |
3895 | ||
3896 | The pixels in the rectangle are processed exactly as if | |
3897 | @code{glReadPixels} had been called with @var{format} set to RGBA, but | |
3898 | the process stops just before final conversion. The R, G, B, and A | |
3899 | components of each pixel are next scaled by the four 2D | |
3900 | @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four 2D | |
3901 | @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias | |
3902 | parameters are set by @code{glConvolutionParameter} using the | |
3903 | @code{GL_CONVOLUTION_2D} target and the names | |
3904 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
3905 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors | |
3906 | of four values that are applied to red, green, blue, and alpha, in that | |
3907 | order.) The R, G, B, and A values are not clamped to [0,1] at any time | |
3908 | during this process. | |
3909 | ||
3910 | Each pixel is then converted to the internal format specified by | |
3911 | @var{internalformat}. This conversion simply maps the component values | |
3912 | of the pixel (R, G, B, and A) to the values included in the internal | |
3913 | format (red, green, blue, alpha, luminance, and intensity). The mapping | |
3914 | is as follows: | |
3915 | ||
3916 | ||
3917 | ||
3918 | @table @asis | |
3919 | @item @strong{Internal Format} | |
3920 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
3921 | @strong{Luminance}, @strong{Intensity} | |
3922 | ||
3923 | @item @code{GL_ALPHA} | |
3924 | , , , A , , | |
3925 | ||
3926 | @item @code{GL_LUMINANCE} | |
3927 | , , , , R , | |
3928 | ||
3929 | @item @code{GL_LUMINANCE_ALPHA} | |
3930 | , , , A , R , | |
3931 | ||
3932 | @item @code{GL_INTENSITY} | |
3933 | , , , , , R | |
3934 | ||
3935 | @item @code{GL_RGB} | |
3936 | R , G , B , , , | |
3937 | ||
3938 | @item @code{GL_RGBA} | |
3939 | R , G , B , A , , | |
3940 | ||
3941 | @end table | |
3942 | ||
3943 | The red, green, blue, alpha, luminance, and/or intensity components of | |
3944 | the resulting pixels are stored in floating-point rather than integer | |
3945 | format. | |
3946 | ||
3947 | Pixel ordering is such that lower x screen coordinates correspond to | |
3948 | lower @var{i} filter image coordinates, and lower y screen coordinates | |
3949 | correspond to lower @var{j} filter image coordinates. | |
3950 | ||
3951 | Note that after a convolution is performed, the resulting color | |
3952 | components are also scaled by their corresponding | |
3953 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
3954 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
3955 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
3956 | and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}. | |
3957 | ||
8925f36f AW |
3958 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
3959 | @code{GL_CONVOLUTION_2D}. | |
3960 | ||
3961 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
3962 | of the allowable values. | |
3963 | ||
3964 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
3965 | greater than the maximum supported value. This value may be queried with | |
3966 | @code{glGetConvolutionParameter} using target @code{GL_CONVOLUTION_2D} | |
3967 | and name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
3968 | ||
3969 | @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero | |
3970 | or greater than the maximum supported value. This value may be queried | |
3971 | with @code{glGetConvolutionParameter} using target | |
3972 | @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}. | |
3973 | ||
3974 | @code{GL_INVALID_OPERATION} is generated if | |
3975 | @code{glCopyConvolutionFilter2D} is executed between the execution of | |
3976 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
3977 | ||
bb894c9d | 3978 | @end deftypefun |
8925f36f | 3979 | |
bb894c9d | 3980 | @deftypefun void glCopyPixels x y width height type |
3c9b6116 AW |
3981 | Copy pixels in the frame buffer. |
3982 | ||
8925f36f AW |
3983 | @table @asis |
3984 | @item @var{x} | |
3985 | @itemx @var{y} | |
3986 | Specify the window coordinates of the lower left corner of the | |
3987 | rectangular region of pixels to be copied. | |
3988 | ||
3989 | @item @var{width} | |
3990 | @itemx @var{height} | |
3991 | Specify the dimensions of the rectangular region of pixels to be copied. | |
3992 | Both must be nonnegative. | |
3993 | ||
3994 | @item @var{type} | |
3995 | Specifies whether color values, depth values, or stencil values are to | |
3996 | be copied. Symbolic constants @code{GL_COLOR}, @code{GL_DEPTH}, and | |
3997 | @code{GL_STENCIL} are accepted. | |
3998 | ||
3999 | @end table | |
4000 | ||
8925f36f AW |
4001 | @code{glCopyPixels} copies a screen-aligned rectangle of pixels from the |
4002 | specified frame buffer location to a region relative to the current | |
4003 | raster position. Its operation is well defined only if the entire pixel | |
4004 | source region is within the exposed portion of the window. Results of | |
4005 | copies from outside the window, or from regions of the window that are | |
4006 | not exposed, are hardware dependent and undefined. | |
4007 | ||
4008 | @var{x} and @var{y} specify the window coordinates of the lower left | |
4009 | corner of the rectangular region to be copied. @var{width} and | |
4010 | @var{height} specify the dimensions of the rectangular region to be | |
4011 | copied. Both @var{width} and @var{height} must not be negative. | |
4012 | ||
4013 | Several parameters control the processing of the pixel data while it is | |
4014 | being copied. These parameters are set with three commands: | |
4015 | @code{glPixelTransfer}, @code{glPixelMap}, and @code{glPixelZoom}. This | |
4016 | reference page describes the effects on @code{glCopyPixels} of most, but | |
4017 | not all, of the parameters specified by these three commands. | |
4018 | ||
4019 | @code{glCopyPixels} copies values from each pixel with the lower | |
3c9b6116 AW |
4020 | left-hand corner at @r{(@var{x}+@var{i},@var{y}+@var{j})} for |
4021 | @r{0<=@var{i}<@var{width}} and @r{0<=@var{j}<@var{height}}. This pixel | |
4022 | is said to be the @r{@var{i}}th pixel in the @r{@var{j}}th row. Pixels | |
4023 | are copied in row order from the lowest to the highest row, left to | |
4024 | right in each row. | |
8925f36f AW |
4025 | |
4026 | @var{type} specifies whether color, depth, or stencil data is to be | |
4027 | copied. The details of the transfer for each data type are as follows: | |
4028 | ||
4029 | @table @asis | |
4030 | @item @code{GL_COLOR} | |
4031 | Indices or RGBA colors are read from the buffer currently specified as | |
4032 | the read source buffer (see @code{glReadBuffer}). If the GL is in color | |
4033 | index mode, each index that is read from this buffer is converted to a | |
4034 | fixed-point format with an unspecified number of bits to the right of | |
4035 | the binary point. Each index is then shifted left by | |
4036 | @code{GL_INDEX_SHIFT} bits, and added to @code{GL_INDEX_OFFSET}. If | |
4037 | @code{GL_INDEX_SHIFT} is negative, the shift is to the right. In either | |
4038 | case, zero bits fill otherwise unspecified bit locations in the result. | |
4039 | If @code{GL_MAP_COLOR} is true, the index is replaced with the value | |
4040 | that it references in lookup table @code{GL_PIXEL_MAP_I_TO_I}. Whether | |
4041 | the lookup replacement of the index is done or not, the integer part of | |
3c9b6116 AW |
4042 | the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the |
4043 | number of bits in a color index buffer. | |
8925f36f AW |
4044 | |
4045 | If the GL is in RGBA mode, the red, green, blue, and alpha components of | |
4046 | each pixel that is read are converted to an internal floating-point | |
4047 | format with unspecified precision. The conversion maps the largest | |
4048 | representable component value to 1.0, and component value 0 to 0.0. The | |
4049 | resulting floating-point color values are then multiplied by | |
4050 | @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is RED, | |
4051 | GREEN, BLUE, and ALPHA for the respective color components. The results | |
4052 | are clamped to the range [0,1]. If @code{GL_MAP_COLOR} is true, each | |
4053 | color component is scaled by the size of lookup table | |
4054 | @code{GL_PIXEL_MAP_c_TO_c}, then replaced by the value that it | |
4055 | references in that table. @var{c} is R, G, B, or A. | |
4056 | ||
4057 | If the @code{ARB_imaging} extension is supported, the color values may | |
4058 | be additionally processed by color-table lookups, color-matrix | |
4059 | transformations, and convolution filters. | |
4060 | ||
4061 | The GL then converts the resulting indices or RGBA colors to fragments | |
4062 | by attaching the current raster position @var{z} coordinate and texture | |
4063 | coordinates to each pixel, then assigning window coordinates | |
3c9b6116 AW |
4064 | @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where |
4065 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position, | |
4066 | and the pixel was the @r{@var{i}}th pixel in the @r{@var{j}}th row. | |
4067 | These pixel fragments are then treated just like the fragments generated | |
4068 | by rasterizing points, lines, or polygons. Texture mapping, fog, and all | |
4069 | the fragment operations are applied before the fragments are written to | |
4070 | the frame buffer. | |
8925f36f AW |
4071 | |
4072 | @item @code{GL_DEPTH} | |
4073 | Depth values are read from the depth buffer and converted directly to an | |
4074 | internal floating-point format with unspecified precision. The resulting | |
4075 | floating-point depth value is then multiplied by @code{GL_DEPTH_SCALE} | |
4076 | and added to @code{GL_DEPTH_BIAS}. The result is clamped to the range | |
4077 | [0,1]. | |
4078 | ||
4079 | The GL then converts the resulting depth components to fragments by | |
4080 | attaching the current raster position color or color index and texture | |
4081 | coordinates to each pixel, then assigning window coordinates | |
3c9b6116 AW |
4082 | @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where |
4083 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position, | |
4084 | and the pixel was the @r{@var{i}}th pixel in the @r{@var{j}}th row. | |
4085 | These pixel fragments are then treated just like the fragments generated | |
4086 | by rasterizing points, lines, or polygons. Texture mapping, fog, and all | |
4087 | the fragment operations are applied before the fragments are written to | |
4088 | the frame buffer. | |
8925f36f AW |
4089 | |
4090 | @item @code{GL_STENCIL} | |
4091 | Stencil indices are read from the stencil buffer and converted to an | |
4092 | internal fixed-point format with an unspecified number of bits to the | |
4093 | right of the binary point. Each fixed-point index is then shifted left | |
4094 | by @code{GL_INDEX_SHIFT} bits, and added to @code{GL_INDEX_OFFSET}. If | |
4095 | @code{GL_INDEX_SHIFT} is negative, the shift is to the right. In either | |
4096 | case, zero bits fill otherwise unspecified bit locations in the result. | |
4097 | If @code{GL_MAP_STENCIL} is true, the index is replaced with the value | |
4098 | that it references in lookup table @code{GL_PIXEL_MAP_S_TO_S}. Whether | |
4099 | the lookup replacement of the index is done or not, the integer part of | |
3c9b6116 AW |
4100 | the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the |
4101 | number of bits in the stencil buffer. The resulting stencil indices are | |
4102 | then written to the stencil buffer such that the index read from the | |
4103 | @r{@var{i}}th location of the @r{@var{j}}th row is written to location | |
4104 | @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where | |
4105 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position. | |
8925f36f AW |
4106 | Only the pixel ownership test, the scissor test, and the stencil |
4107 | writemask affect these write operations. | |
4108 | ||
4109 | @end table | |
4110 | ||
4111 | The rasterization described thus far assumes pixel zoom factors of 1.0. | |
3c9b6116 AW |
4112 | If @code{glPixelZoom} is used to change the @r{@var{x}} and @r{@var{y}} |
4113 | pixel zoom factors, pixels are converted to fragments as follows. If | |
4114 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position, | |
4115 | and a given pixel is in the @r{@var{i}}th location in the @r{@var{j}}th | |
4116 | row of the source pixel rectangle, then fragments are generated for | |
4117 | pixels whose centers are in the rectangle with corners at | |
8925f36f | 4118 | |
3c9b6116 | 4119 | @r{(@var{x}_@var{r}+@var{zoom}_@var{x},@var{i},@var{y}_@var{r}+@var{zoom}_@var{y},@var{j})} |
8925f36f AW |
4120 | |
4121 | and | |
4122 | ||
3c9b6116 | 4123 | @r{(@var{x}_@var{r}+@var{zoom}_@var{x},(@var{i}+1,),@var{y}_@var{r}+@var{zoom}_@var{y},(@var{j}+1,))} |
8925f36f | 4124 | |
3c9b6116 AW |
4125 | where @r{@var{zoom}_@var{x}} is the value of @code{GL_ZOOM_X} and |
4126 | @r{@var{zoom}_@var{y}} is the value of @code{GL_ZOOM_Y}. | |
8925f36f | 4127 | |
8925f36f AW |
4128 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted |
4129 | value. | |
4130 | ||
4131 | @code{GL_INVALID_VALUE} is generated if either @var{width} or | |
4132 | @var{height} is negative. | |
4133 | ||
4134 | @code{GL_INVALID_OPERATION} is generated if @var{type} is | |
4135 | @code{GL_DEPTH} and there is no depth buffer. | |
4136 | ||
4137 | @code{GL_INVALID_OPERATION} is generated if @var{type} is | |
4138 | @code{GL_STENCIL} and there is no stencil buffer. | |
4139 | ||
4140 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyPixels} is | |
4141 | executed between the execution of @code{glBegin} and the corresponding | |
4142 | execution of @code{glEnd}. | |
4143 | ||
bb894c9d | 4144 | @end deftypefun |
8925f36f | 4145 | |
bb894c9d | 4146 | @deftypefun void glCopyTexImage1D target level internalformat x y width border |
3c9b6116 AW |
4147 | Copy pixels into a 1D texture image. |
4148 | ||
8925f36f AW |
4149 | @table @asis |
4150 | @item @var{target} | |
4151 | Specifies the target texture. Must be @code{GL_TEXTURE_1D}. | |
4152 | ||
4153 | @item @var{level} | |
4154 | Specifies the level-of-detail number. Level 0 is the base image level. | |
4155 | Level @var{n} is the @var{n}th mipmap reduction image. | |
4156 | ||
4157 | @item @var{internalformat} | |
4158 | Specifies the internal format of the texture. Must be one of the | |
4159 | following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4}, | |
4160 | @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16}, | |
4161 | @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_LUMINANCE}, | |
4162 | @code{GL_COMPRESSED_LUMINANCE_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
4163 | @code{GL_COMPRESSED_RGB}, @code{GL_COMPRESSED_RGBA}, | |
4164 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
4165 | @code{GL_DEPTH_COMPONENT24}, @code{GL_DEPTH_COMPONENT32}, | |
4166 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, | |
4167 | @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
4168 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
4169 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
4170 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
4171 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
4172 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_RGB}, | |
4173 | @code{GL_R3_G3_B2}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
4174 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
4175 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
4176 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, @code{GL_RGBA16}, | |
4177 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
4178 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
4179 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
4180 | ||
4181 | @item @var{x} | |
4182 | @itemx @var{y} | |
4183 | Specify the window coordinates of the left corner of the row of pixels | |
4184 | to be copied. | |
4185 | ||
4186 | @item @var{width} | |
4187 | Specifies the width of the texture image. Must be 0 or | |
3c9b6116 AW |
4188 | @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. The height |
4189 | of the texture image is 1. | |
8925f36f AW |
4190 | |
4191 | @item @var{border} | |
4192 | Specifies the width of the border. Must be either 0 or 1. | |
4193 | ||
4194 | @end table | |
4195 | ||
8925f36f AW |
4196 | @code{glCopyTexImage1D} defines a one-dimensional texture image with |
4197 | pixels from the current @code{GL_READ_BUFFER}. | |
4198 | ||
3c9b6116 AW |
4199 | The screen-aligned pixel row with left corner at @r{(@var{x},@var{y})} |
4200 | and with a length of @r{@var{width}+2(@var{border},)} defines the | |
4201 | texture array at the mipmap level specified by @var{level}. | |
4202 | @var{internalformat} specifies the internal format of the texture array. | |
8925f36f AW |
4203 | |
4204 | The pixels in the row are processed exactly as if @code{glCopyPixels} | |
4205 | had been called, but the process stops just before final conversion. At | |
3c9b6116 AW |
4206 | this point all pixel component values are clamped to the range @r{[0,1]} |
4207 | and then converted to the texture's internal format for storage in the | |
4208 | texel array. | |
8925f36f | 4209 | |
3c9b6116 | 4210 | Pixel ordering is such that lower @r{@var{x}} screen coordinates |
8925f36f AW |
4211 | correspond to lower texture coordinates. |
4212 | ||
4213 | If any of the pixels within the specified row of the current | |
4214 | @code{GL_READ_BUFFER} are outside the window associated with the current | |
4215 | rendering context, then the values obtained for those pixels are | |
4216 | undefined. | |
4217 | ||
4218 | @code{glCopyTexImage1D} defines a one-dimensional texture image with | |
4219 | pixels from the current @code{GL_READ_BUFFER}. | |
4220 | ||
4221 | When @var{internalformat} is one of the sRGB types, the GL does not | |
4222 | automatically convert the source pixels to the sRGB color space. In this | |
4223 | case, the @code{glPixelMap} function can be used to accomplish the | |
4224 | conversion. | |
4225 | ||
8925f36f AW |
4226 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
4227 | allowable values. | |
4228 | ||
4229 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4230 | ||
4231 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
4232 | @r{@var{log}_2@var{max}}, where @r{@var{max}} is the returned value of |
4233 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
4234 | |
4235 | @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not an | |
4236 | allowable value. | |
4237 | ||
4238 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or | |
4239 | greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
4240 | ||
4241 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
4242 | not supported and the @var{width} cannot be represented as | |
3c9b6116 | 4243 | @r{2^@var{n}+2(@var{border},)} for some integer value of @var{n}. |
8925f36f AW |
4244 | |
4245 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
4246 | ||
4247 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexImage1D} is | |
4248 | executed between the execution of @code{glBegin} and the corresponding | |
4249 | execution of @code{glEnd}. | |
4250 | ||
4251 | @code{GL_INVALID_OPERATION} is generated if @var{internalformat} is | |
4252 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
4253 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32} and there is | |
4254 | no depth buffer. | |
4255 | ||
bb894c9d | 4256 | @end deftypefun |
8925f36f | 4257 | |
bb894c9d | 4258 | @deftypefun void glCopyTexImage2D target level internalformat x y width height border |
3c9b6116 AW |
4259 | Copy pixels into a 2D texture image. |
4260 | ||
8925f36f AW |
4261 | @table @asis |
4262 | @item @var{target} | |
4263 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, | |
4264 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
4265 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
4266 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
4267 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
4268 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
4269 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
4270 | ||
4271 | @item @var{level} | |
4272 | Specifies the level-of-detail number. Level 0 is the base image level. | |
4273 | Level @var{n} is the @var{n}th mipmap reduction image. | |
4274 | ||
4275 | @item @var{internalformat} | |
4276 | Specifies the internal format of the texture. Must be one of the | |
4277 | following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4}, | |
4278 | @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16}, | |
4279 | @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_LUMINANCE}, | |
4280 | @code{GL_COMPRESSED_LUMINANCE_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
4281 | @code{GL_COMPRESSED_RGB}, @code{GL_COMPRESSED_RGBA}, | |
4282 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
4283 | @code{GL_DEPTH_COMPONENT24}, @code{GL_DEPTH_COMPONENT32}, | |
4284 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, | |
4285 | @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
4286 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
4287 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
4288 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
4289 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
4290 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_RGB}, | |
4291 | @code{GL_R3_G3_B2}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
4292 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
4293 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
4294 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, @code{GL_RGBA16}, | |
4295 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
4296 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
4297 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
4298 | ||
4299 | @item @var{x} | |
4300 | @itemx @var{y} | |
4301 | Specify the window coordinates of the lower left corner of the | |
4302 | rectangular region of pixels to be copied. | |
4303 | ||
4304 | @item @var{width} | |
4305 | Specifies the width of the texture image. Must be 0 or | |
3c9b6116 | 4306 | @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. |
8925f36f AW |
4307 | |
4308 | @item @var{height} | |
4309 | Specifies the height of the texture image. Must be 0 or | |
3c9b6116 | 4310 | @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}. |
8925f36f AW |
4311 | |
4312 | @item @var{border} | |
4313 | Specifies the width of the border. Must be either 0 or 1. | |
4314 | ||
4315 | @end table | |
4316 | ||
8925f36f AW |
4317 | @code{glCopyTexImage2D} defines a two-dimensional texture image, or |
4318 | cube-map texture image with pixels from the current | |
4319 | @code{GL_READ_BUFFER}. | |
4320 | ||
4321 | The screen-aligned pixel rectangle with lower left corner at (@var{x}, | |
3c9b6116 AW |
4322 | @var{y}) and with a width of @r{@var{width}+2(@var{border},)} and a |
4323 | height of @r{@var{height}+2(@var{border},)} defines the texture array | |
4324 | at the mipmap level specified by @var{level}. @var{internalformat} | |
8925f36f AW |
4325 | specifies the internal format of the texture array. |
4326 | ||
4327 | The pixels in the rectangle are processed exactly as if | |
4328 | @code{glCopyPixels} had been called, but the process stops just before | |
4329 | final conversion. At this point all pixel component values are clamped | |
3c9b6116 | 4330 | to the range @r{[0,1]} and then converted to the texture's internal |
8925f36f AW |
4331 | format for storage in the texel array. |
4332 | ||
3c9b6116 AW |
4333 | Pixel ordering is such that lower @r{@var{x}} and @r{@var{y}} screen |
4334 | coordinates correspond to lower @r{@var{s}} and @r{@var{t}} texture | |
4335 | coordinates. | |
8925f36f AW |
4336 | |
4337 | If any of the pixels within the specified rectangle of the current | |
4338 | @code{GL_READ_BUFFER} are outside the window associated with the current | |
4339 | rendering context, then the values obtained for those pixels are | |
4340 | undefined. | |
4341 | ||
4342 | When @var{internalformat} is one of the sRGB types, the GL does not | |
4343 | automatically convert the source pixels to the sRGB color space. In this | |
4344 | case, the @code{glPixelMap} function can be used to accomplish the | |
4345 | conversion. | |
4346 | ||
8925f36f AW |
4347 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
4348 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
4349 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
4350 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
4351 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
4352 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
4353 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
4354 | ||
4355 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4356 | ||
4357 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
4358 | @r{@var{log}_2@var{max}}, where @r{@var{max}} is the returned value of |
4359 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
4360 | |
4361 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or | |
4362 | greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
4363 | ||
4364 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
4365 | not supported and the @var{width} or @var{depth} cannot be represented | |
3c9b6116 | 4366 | as @r{2^@var{k}+2(@var{border},)} for some integer @r{@var{k}}. |
8925f36f AW |
4367 | |
4368 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
4369 | ||
4370 | @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not an | |
4371 | accepted format. | |
4372 | ||
4373 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexImage2D} is | |
4374 | executed between the execution of @code{glBegin} and the corresponding | |
4375 | execution of @code{glEnd}. | |
4376 | ||
4377 | @code{GL_INVALID_OPERATION} is generated if @var{internalformat} is | |
4378 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
4379 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32} and there is | |
4380 | no depth buffer. | |
4381 | ||
bb894c9d | 4382 | @end deftypefun |
8925f36f | 4383 | |
bb894c9d | 4384 | @deftypefun void glCopyTexSubImage1D target level xoffset x y width |
3c9b6116 AW |
4385 | Copy a one-dimensional texture subimage. |
4386 | ||
8925f36f AW |
4387 | @table @asis |
4388 | @item @var{target} | |
4389 | Specifies the target texture. Must be @code{GL_TEXTURE_1D}. | |
4390 | ||
4391 | @item @var{level} | |
4392 | Specifies the level-of-detail number. Level 0 is the base image level. | |
4393 | Level @var{n} is the @var{n}th mipmap reduction image. | |
4394 | ||
4395 | @item @var{xoffset} | |
4396 | Specifies the texel offset within the texture array. | |
4397 | ||
4398 | @item @var{x} | |
4399 | @itemx @var{y} | |
4400 | Specify the window coordinates of the left corner of the row of pixels | |
4401 | to be copied. | |
4402 | ||
4403 | @item @var{width} | |
4404 | Specifies the width of the texture subimage. | |
4405 | ||
4406 | @end table | |
4407 | ||
8925f36f AW |
4408 | @code{glCopyTexSubImage1D} replaces a portion of a one-dimensional |
4409 | texture image with pixels from the current @code{GL_READ_BUFFER} (rather | |
4410 | than from main memory, as is the case for @code{glTexSubImage1D}). | |
4411 | ||
4412 | The screen-aligned pixel row with left corner at (@var{x},\ @var{y}), | |
4413 | and with length @var{width} replaces the portion of the texture array | |
3c9b6116 | 4414 | with x indices @var{xoffset} through @r{@var{xoffset}+@var{width}-1}, |
8925f36f AW |
4415 | inclusive. The destination in the texture array may not include any |
4416 | texels outside the texture array as it was originally specified. | |
4417 | ||
4418 | The pixels in the row are processed exactly as if @code{glCopyPixels} | |
4419 | had been called, but the process stops just before final conversion. At | |
4420 | this point, all pixel component values are clamped to the range | |
3c9b6116 | 4421 | @r{[0,1]} and then converted to the texture's internal format for |
8925f36f AW |
4422 | storage in the texel array. |
4423 | ||
4424 | It is not an error to specify a subtexture with zero width, but such a | |
4425 | specification has no effect. If any of the pixels within the specified | |
4426 | row of the current @code{GL_READ_BUFFER} are outside the read window | |
4427 | associated with the current rendering context, then the values obtained | |
4428 | for those pixels are undefined. | |
4429 | ||
4430 | No change is made to the @var{internalformat}, @var{width}, or | |
4431 | @var{border} parameters of the specified texture array or to texel | |
4432 | values outside the specified subregion. | |
4433 | ||
8925f36f AW |
4434 | @code{GL_INVALID_ENUM} is generated if /@var{target} is not |
4435 | @code{GL_TEXTURE_1D}. | |
4436 | ||
4437 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
4438 | been defined by a previous @code{glTexImage1D} or | |
4439 | @code{glCopyTexImage1D} operation. | |
4440 | ||
4441 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4442 | ||
4443 | @code{GL_INVALID_VALUE} may be generated if | |
3c9b6116 | 4444 | @r{@var{level}>@var{log}_2(@var{max},)}, where @var{max} is the |
8925f36f AW |
4445 | returned value of @code{GL_MAX_TEXTURE_SIZE}. |
4446 | ||
3c9b6116 AW |
4447 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, or |
4448 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, where @r{@var{w}} | |
4449 | is the @code{GL_TEXTURE_WIDTH} and @r{@var{b}} is the | |
8925f36f | 4450 | @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that |
3c9b6116 | 4451 | @r{@var{w}} includes twice the border width. |
8925f36f AW |
4452 | |
4453 | ||
4454 | ||
bb894c9d | 4455 | @end deftypefun |
8925f36f | 4456 | |
bb894c9d | 4457 | @deftypefun void glCopyTexSubImage2D target level xoffset yoffset x y width height |
3c9b6116 AW |
4458 | Copy a two-dimensional texture subimage. |
4459 | ||
8925f36f AW |
4460 | @table @asis |
4461 | @item @var{target} | |
4462 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, | |
4463 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
4464 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
4465 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
4466 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
4467 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
4468 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
4469 | ||
4470 | @item @var{level} | |
4471 | Specifies the level-of-detail number. Level 0 is the base image level. | |
4472 | Level @var{n} is the @var{n}th mipmap reduction image. | |
4473 | ||
4474 | @item @var{xoffset} | |
4475 | Specifies a texel offset in the x direction within the texture array. | |
4476 | ||
4477 | @item @var{yoffset} | |
4478 | Specifies a texel offset in the y direction within the texture array. | |
4479 | ||
4480 | @item @var{x} | |
4481 | @itemx @var{y} | |
4482 | Specify the window coordinates of the lower left corner of the | |
4483 | rectangular region of pixels to be copied. | |
4484 | ||
4485 | @item @var{width} | |
4486 | Specifies the width of the texture subimage. | |
4487 | ||
4488 | @item @var{height} | |
4489 | Specifies the height of the texture subimage. | |
4490 | ||
4491 | @end table | |
4492 | ||
8925f36f AW |
4493 | @code{glCopyTexSubImage2D} replaces a rectangular portion of a |
4494 | two-dimensional texture image or cube-map texture image with pixels from | |
4495 | the current @code{GL_READ_BUFFER} (rather than from main memory, as is | |
4496 | the case for @code{glTexSubImage2D}). | |
4497 | ||
4498 | The screen-aligned pixel rectangle with lower left corner at | |
3c9b6116 AW |
4499 | @r{(@var{x},@var{y})} and with width @var{width} and height @var{height} |
4500 | replaces the portion of the texture array with x indices @var{xoffset} | |
4501 | through @r{@var{xoffset}+@var{width}-1}, inclusive, and y indices | |
4502 | @var{yoffset} through @r{@var{yoffset}+@var{height}-1}, inclusive, at | |
4503 | the mipmap level specified by @var{level}. | |
8925f36f AW |
4504 | |
4505 | The pixels in the rectangle are processed exactly as if | |
4506 | @code{glCopyPixels} had been called, but the process stops just before | |
4507 | final conversion. At this point, all pixel component values are clamped | |
3c9b6116 | 4508 | to the range @r{[0,1]} and then converted to the texture's internal |
8925f36f AW |
4509 | format for storage in the texel array. |
4510 | ||
4511 | The destination rectangle in the texture array may not include any | |
4512 | texels outside the texture array as it was originally specified. It is | |
4513 | not an error to specify a subtexture with zero width or height, but such | |
4514 | a specification has no effect. | |
4515 | ||
4516 | If any of the pixels within the specified rectangle of the current | |
4517 | @code{GL_READ_BUFFER} are outside the read window associated with the | |
4518 | current rendering context, then the values obtained for those pixels are | |
4519 | undefined. | |
4520 | ||
4521 | No change is made to the @var{internalformat}, @var{width}, | |
4522 | @var{height}, or @var{border} parameters of the specified texture array | |
4523 | or to texel values outside the specified subregion. | |
4524 | ||
8925f36f AW |
4525 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
4526 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
4527 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
4528 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
4529 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
4530 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
4531 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
4532 | ||
4533 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
4534 | been defined by a previous @code{glTexImage2D} or | |
4535 | @code{glCopyTexImage2D} operation. | |
4536 | ||
4537 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4538 | ||
4539 | @code{GL_INVALID_VALUE} may be generated if | |
3c9b6116 AW |
4540 | @r{@var{level}>@var{log}_2(@var{max},)}, where @r{@var{max}} is the |
4541 | returned value of @code{GL_MAX_TEXTURE_SIZE}. | |
4542 | ||
4543 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, | |
4544 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, | |
4545 | @r{@var{yoffset}<-@var{b}}, or | |
4546 | @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, where @r{@var{w}} | |
4547 | is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the | |
4548 | @code{GL_TEXTURE_HEIGHT}, and @r{@var{b}} is the | |
8925f36f | 4549 | @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that |
3c9b6116 | 4550 | @r{@var{w}} and @r{@var{h}} include twice the border width. |
8925f36f AW |
4551 | |
4552 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexSubImage2D} | |
4553 | is executed between the execution of @code{glBegin} and the | |
4554 | corresponding execution of @code{glEnd}. | |
4555 | ||
bb894c9d | 4556 | @end deftypefun |
8925f36f | 4557 | |
bb894c9d | 4558 | @deftypefun void glCopyTexSubImage3D target level xoffset yoffset zoffset x y width height |
3c9b6116 AW |
4559 | Copy a three-dimensional texture subimage. |
4560 | ||
8925f36f AW |
4561 | @table @asis |
4562 | @item @var{target} | |
4563 | Specifies the target texture. Must be @code{GL_TEXTURE_3D} | |
4564 | ||
4565 | @item @var{level} | |
4566 | Specifies the level-of-detail number. Level 0 is the base image level. | |
4567 | Level @var{n} is the @var{n}th mipmap reduction image. | |
4568 | ||
4569 | @item @var{xoffset} | |
4570 | Specifies a texel offset in the x direction within the texture array. | |
4571 | ||
4572 | @item @var{yoffset} | |
4573 | Specifies a texel offset in the y direction within the texture array. | |
4574 | ||
4575 | @item @var{zoffset} | |
4576 | Specifies a texel offset in the z direction within the texture array. | |
4577 | ||
4578 | @item @var{x} | |
4579 | @itemx @var{y} | |
4580 | Specify the window coordinates of the lower left corner of the | |
4581 | rectangular region of pixels to be copied. | |
4582 | ||
4583 | @item @var{width} | |
4584 | Specifies the width of the texture subimage. | |
4585 | ||
4586 | @item @var{height} | |
4587 | Specifies the height of the texture subimage. | |
4588 | ||
4589 | @end table | |
4590 | ||
8925f36f AW |
4591 | @code{glCopyTexSubImage3D} replaces a rectangular portion of a |
4592 | three-dimensional texture image with pixels from the current | |
4593 | @code{GL_READ_BUFFER} (rather than from main memory, as is the case for | |
4594 | @code{glTexSubImage3D}). | |
4595 | ||
4596 | The screen-aligned pixel rectangle with lower left corner at (@var{x},\ | |
4597 | @var{y}) and with width @var{width} and height @var{height} replaces the | |
4598 | portion of the texture array with x indices @var{xoffset} through | |
3c9b6116 AW |
4599 | @r{@var{xoffset}+@var{width}-1}, inclusive, and y indices @var{yoffset} |
4600 | through @r{@var{yoffset}+@var{height}-1}, inclusive, at z index | |
4601 | @var{zoffset} and at the mipmap level specified by @var{level}. | |
8925f36f AW |
4602 | |
4603 | The pixels in the rectangle are processed exactly as if | |
4604 | @code{glCopyPixels} had been called, but the process stops just before | |
4605 | final conversion. At this point, all pixel component values are clamped | |
3c9b6116 | 4606 | to the range @r{[0,1]} and then converted to the texture's internal |
8925f36f AW |
4607 | format for storage in the texel array. |
4608 | ||
4609 | The destination rectangle in the texture array may not include any | |
4610 | texels outside the texture array as it was originally specified. It is | |
4611 | not an error to specify a subtexture with zero width or height, but such | |
4612 | a specification has no effect. | |
4613 | ||
4614 | If any of the pixels within the specified rectangle of the current | |
4615 | @code{GL_READ_BUFFER} are outside the read window associated with the | |
4616 | current rendering context, then the values obtained for those pixels are | |
4617 | undefined. | |
4618 | ||
4619 | No change is made to the @var{internalformat}, @var{width}, | |
4620 | @var{height}, @var{depth}, or @var{border} parameters of the specified | |
4621 | texture array or to texel values outside the specified subregion. | |
4622 | ||
8925f36f AW |
4623 | @code{GL_INVALID_ENUM} is generated if /@var{target} is not |
4624 | @code{GL_TEXTURE_3D}. | |
4625 | ||
4626 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
4627 | been defined by a previous @code{glTexImage3D} operation. | |
4628 | ||
4629 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4630 | ||
4631 | @code{GL_INVALID_VALUE} may be generated if | |
3c9b6116 AW |
4632 | @r{@var{level}>@var{log}_2(@var{max},)}, where @r{@var{max}} is the |
4633 | returned value of @code{GL_MAX_3D_TEXTURE_SIZE}. | |
4634 | ||
4635 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, | |
4636 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, | |
4637 | @r{@var{yoffset}<-@var{b}}, | |
4638 | @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, | |
4639 | @r{@var{zoffset}<-@var{b}}, or | |
4640 | @r{(@var{zoffset}+1,)>(@var{d}-@var{b},)}, where @r{@var{w}} is the | |
4641 | @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the @code{GL_TEXTURE_HEIGHT}, | |
4642 | @r{@var{d}} is the @code{GL_TEXTURE_DEPTH}, and @r{@var{b}} is the | |
4643 | @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that | |
4644 | @r{@var{w}}, @r{@var{h}}, and @r{@var{d}} include twice the border | |
4645 | width. | |
8925f36f AW |
4646 | |
4647 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexSubImage3D} | |
4648 | is executed between the execution of @code{glBegin} and the | |
4649 | corresponding execution of @code{glEnd}. | |
4650 | ||
bb894c9d | 4651 | @end deftypefun |
8925f36f | 4652 | |
bb894c9d | 4653 | @deftypefun GLuint glCreateProgram |
3c9b6116 AW |
4654 | Creates a program object. |
4655 | ||
8925f36f AW |
4656 | @code{glCreateProgram} creates an empty program object and returns a |
4657 | non-zero value by which it can be referenced. A program object is an | |
4658 | object to which shader objects can be attached. This provides a | |
4659 | mechanism to specify the shader objects that will be linked to create a | |
4660 | program. It also provides a means for checking the compatibility of the | |
4661 | shaders that will be used to create a program (for instance, checking | |
4662 | the compatibility between a vertex shader and a fragment shader). When | |
4663 | no longer needed as part of a program object, shader objects can be | |
4664 | detached. | |
4665 | ||
4666 | One or more executables are created in a program object by successfully | |
4667 | attaching shader objects to it with @code{glAttachShader}, successfully | |
4668 | compiling the shader objects with @code{glCompileShader}, and | |
4669 | successfully linking the program object with @code{glLinkProgram}. These | |
4670 | executables are made part of current state when @code{glUseProgram} is | |
4671 | called. Program objects can be deleted by calling | |
4672 | @code{glDeleteProgram}. The memory associated with the program object | |
4673 | will be deleted when it is no longer part of current rendering state for | |
4674 | any context. | |
4675 | ||
8925f36f AW |
4676 | This function returns 0 if an error occurs creating the program object. |
4677 | ||
4678 | @code{GL_INVALID_OPERATION} is generated if @code{glCreateProgram} is | |
4679 | executed between the execution of @code{glBegin} and the corresponding | |
4680 | execution of @code{glEnd}. | |
4681 | ||
bb894c9d | 4682 | @end deftypefun |
8925f36f | 4683 | |
bb894c9d | 4684 | @deftypefun GLuint glCreateShader shaderType |
3c9b6116 AW |
4685 | Creates a shader object. |
4686 | ||
8925f36f AW |
4687 | @table @asis |
4688 | @item @var{shaderType} | |
4689 | Specifies the type of shader to be created. Must be either | |
4690 | @code{GL_VERTEX_SHADER} or @code{GL_FRAGMENT_SHADER}. | |
4691 | ||
4692 | @end table | |
4693 | ||
8925f36f AW |
4694 | @code{glCreateShader} creates an empty shader object and returns a |
4695 | non-zero value by which it can be referenced. A shader object is used to | |
4696 | maintain the source code strings that define a shader. @var{shaderType} | |
4697 | indicates the type of shader to be created. Two types of shaders are | |
4698 | supported. A shader of type @code{GL_VERTEX_SHADER} is a shader that is | |
4699 | intended to run on the programmable vertex processor and replace the | |
4700 | fixed functionality vertex processing in OpenGL. A shader of type | |
4701 | @code{GL_FRAGMENT_SHADER} is a shader that is intended to run on the | |
4702 | programmable fragment processor and replace the fixed functionality | |
4703 | fragment processing in OpenGL. | |
4704 | ||
4705 | When created, a shader object's @code{GL_SHADER_TYPE} parameter is set | |
4706 | to either @code{GL_VERTEX_SHADER} or @code{GL_FRAGMENT_SHADER}, | |
4707 | depending on the value of @var{shaderType}. | |
4708 | ||
8925f36f AW |
4709 | This function returns 0 if an error occurs creating the shader object. |
4710 | ||
4711 | @code{GL_INVALID_ENUM} is generated if @var{shaderType} is not an | |
4712 | accepted value. | |
4713 | ||
4714 | @code{GL_INVALID_OPERATION} is generated if @code{glCreateShader} is | |
4715 | executed between the execution of @code{glBegin} and the corresponding | |
4716 | execution of @code{glEnd}. | |
4717 | ||
bb894c9d | 4718 | @end deftypefun |
8925f36f | 4719 | |
bb894c9d | 4720 | @deftypefun void glCullFace mode |
3c9b6116 AW |
4721 | Specify whether front- or back-facing facets can be culled. |
4722 | ||
8925f36f AW |
4723 | @table @asis |
4724 | @item @var{mode} | |
4725 | Specifies whether front- or back-facing facets are candidates for | |
4726 | culling. Symbolic constants @code{GL_FRONT}, @code{GL_BACK}, and | |
4727 | @code{GL_FRONT_AND_BACK} are accepted. The initial value is | |
4728 | @code{GL_BACK}. | |
4729 | ||
4730 | @end table | |
4731 | ||
8925f36f AW |
4732 | @code{glCullFace} specifies whether front- or back-facing facets are |
4733 | culled (as specified by @var{mode}) when facet culling is enabled. Facet | |
4734 | culling is initially disabled. To enable and disable facet culling, call | |
4735 | the @code{glEnable} and @code{glDisable} commands with the argument | |
4736 | @code{GL_CULL_FACE}. Facets include triangles, quadrilaterals, polygons, | |
4737 | and rectangles. | |
4738 | ||
4739 | @code{glFrontFace} specifies which of the clockwise and counterclockwise | |
4740 | facets are front-facing and back-facing. See @code{glFrontFace}. | |
4741 | ||
8925f36f AW |
4742 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
4743 | value. | |
4744 | ||
4745 | @code{GL_INVALID_OPERATION} is generated if @code{glCullFace} is | |
4746 | executed between the execution of @code{glBegin} and the corresponding | |
4747 | execution of @code{glEnd}. | |
4748 | ||
bb894c9d | 4749 | @end deftypefun |
8925f36f | 4750 | |
bb894c9d | 4751 | @deftypefun void glDeleteBuffers n buffers |
3c9b6116 AW |
4752 | Delete named buffer objects. |
4753 | ||
8925f36f AW |
4754 | @table @asis |
4755 | @item @var{n} | |
4756 | Specifies the number of buffer objects to be deleted. | |
4757 | ||
4758 | @item @var{buffers} | |
4759 | Specifies an array of buffer objects to be deleted. | |
4760 | ||
4761 | @end table | |
4762 | ||
8925f36f AW |
4763 | @code{glDeleteBuffers} deletes @var{n} buffer objects named by the |
4764 | elements of the array @var{buffers}. After a buffer object is deleted, | |
4765 | it has no contents, and its name is free for reuse (for example by | |
4766 | @code{glGenBuffers}). If a buffer object that is currently bound is | |
4767 | deleted, the binding reverts to 0 (the absence of any buffer object, | |
4768 | which reverts to client memory usage). | |
4769 | ||
4770 | @code{glDeleteBuffers} silently ignores 0's and names that do not | |
4771 | correspond to existing buffer objects. | |
4772 | ||
8925f36f AW |
4773 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
4774 | ||
4775 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteBuffers} is | |
4776 | executed between the execution of @code{glBegin} and the corresponding | |
4777 | execution of @code{glEnd}. | |
4778 | ||
bb894c9d | 4779 | @end deftypefun |
8925f36f | 4780 | |
bb894c9d | 4781 | @deftypefun void glDeleteLists list range |
3c9b6116 AW |
4782 | Delete a contiguous group of display lists. |
4783 | ||
8925f36f AW |
4784 | @table @asis |
4785 | @item @var{list} | |
4786 | Specifies the integer name of the first display list to delete. | |
4787 | ||
4788 | @item @var{range} | |
4789 | Specifies the number of display lists to delete. | |
4790 | ||
4791 | @end table | |
4792 | ||
8925f36f AW |
4793 | @code{glDeleteLists} causes a contiguous group of display lists to be |
4794 | deleted. @var{list} is the name of the first display list to be deleted, | |
4795 | and @var{range} is the number of display lists to delete. All display | |
3c9b6116 AW |
4796 | lists @r{@var{d}} with @r{@var{list}<=@var{d}<=@var{list}+@var{range}-1} |
4797 | are deleted. | |
8925f36f AW |
4798 | |
4799 | All storage locations allocated to the specified display lists are | |
4800 | freed, and the names are available for reuse at a later time. Names | |
4801 | within the range that do not have an associated display list are | |
4802 | ignored. If @var{range} is 0, nothing happens. | |
4803 | ||
8925f36f AW |
4804 | @code{GL_INVALID_VALUE} is generated if @var{range} is negative. |
4805 | ||
4806 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteLists} is | |
4807 | executed between the execution of @code{glBegin} and the corresponding | |
4808 | execution of @code{glEnd}. | |
4809 | ||
bb894c9d | 4810 | @end deftypefun |
8925f36f | 4811 | |
bb894c9d | 4812 | @deftypefun void glDeleteProgram program |
3c9b6116 AW |
4813 | Deletes a program object. |
4814 | ||
8925f36f AW |
4815 | @table @asis |
4816 | @item @var{program} | |
4817 | Specifies the program object to be deleted. | |
4818 | ||
4819 | @end table | |
4820 | ||
8925f36f AW |
4821 | @code{glDeleteProgram} frees the memory and invalidates the name |
4822 | associated with the program object specified by @var{program.} This | |
4823 | command effectively undoes the effects of a call to | |
4824 | @code{glCreateProgram}. | |
4825 | ||
4826 | If a program object is in use as part of current rendering state, it | |
4827 | will be flagged for deletion, but it will not be deleted until it is no | |
4828 | longer part of current state for any rendering context. If a program | |
4829 | object to be deleted has shader objects attached to it, those shader | |
4830 | objects will be automatically detached but not deleted unless they have | |
4831 | already been flagged for deletion by a previous call to | |
4832 | @code{glDeleteShader}. A value of 0 for @var{program} will be silently | |
4833 | ignored. | |
4834 | ||
4835 | To determine whether a program object has been flagged for deletion, | |
4836 | call @code{glGetProgram} with arguments @var{program} and | |
4837 | @code{GL_DELETE_STATUS}. | |
4838 | ||
8925f36f AW |
4839 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
4840 | generated by OpenGL. | |
4841 | ||
4842 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteProgram} is | |
4843 | executed between the execution of @code{glBegin} and the corresponding | |
4844 | execution of @code{glEnd}. | |
4845 | ||
bb894c9d | 4846 | @end deftypefun |
8925f36f | 4847 | |
bb894c9d | 4848 | @deftypefun void glDeleteQueries n ids |
3c9b6116 AW |
4849 | Delete named query objects. |
4850 | ||
8925f36f AW |
4851 | @table @asis |
4852 | @item @var{n} | |
4853 | Specifies the number of query objects to be deleted. | |
4854 | ||
4855 | @item @var{ids} | |
4856 | Specifies an array of query objects to be deleted. | |
4857 | ||
4858 | @end table | |
4859 | ||
8925f36f AW |
4860 | @code{glDeleteQueries} deletes @var{n} query objects named by the |
4861 | elements of the array @var{ids}. After a query object is deleted, it has | |
4862 | no contents, and its name is free for reuse (for example by | |
4863 | @code{glGenQueries}). | |
4864 | ||
4865 | @code{glDeleteQueries} silently ignores 0's and names that do not | |
4866 | correspond to existing query objects. | |
4867 | ||
8925f36f AW |
4868 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
4869 | ||
4870 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteQueries} is | |
4871 | executed between the execution of @code{glBegin} and the corresponding | |
4872 | execution of @code{glEnd}. | |
4873 | ||
bb894c9d | 4874 | @end deftypefun |
8925f36f | 4875 | |
bb894c9d | 4876 | @deftypefun void glDeleteShader shader |
3c9b6116 AW |
4877 | Deletes a shader object. |
4878 | ||
8925f36f AW |
4879 | @table @asis |
4880 | @item @var{shader} | |
4881 | Specifies the shader object to be deleted. | |
4882 | ||
4883 | @end table | |
4884 | ||
8925f36f AW |
4885 | @code{glDeleteShader} frees the memory and invalidates the name |
4886 | associated with the shader object specified by @var{shader}. This | |
4887 | command effectively undoes the effects of a call to | |
4888 | @code{glCreateShader}. | |
4889 | ||
4890 | If a shader object to be deleted is attached to a program object, it | |
4891 | will be flagged for deletion, but it will not be deleted until it is no | |
4892 | longer attached to any program object, for any rendering context (i.e., | |
4893 | it must be detached from wherever it was attached before it will be | |
4894 | deleted). A value of 0 for @var{shader} will be silently ignored. | |
4895 | ||
4896 | To determine whether an object has been flagged for deletion, call | |
4897 | @code{glGetShader} with arguments @var{shader} and | |
4898 | @code{GL_DELETE_STATUS}. | |
4899 | ||
8925f36f AW |
4900 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
4901 | generated by OpenGL. | |
4902 | ||
4903 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteShader} is | |
4904 | executed between the execution of @code{glBegin} and the corresponding | |
4905 | execution of @code{glEnd}. | |
4906 | ||
bb894c9d | 4907 | @end deftypefun |
8925f36f | 4908 | |
bb894c9d | 4909 | @deftypefun void glDeleteTextures n textures |
3c9b6116 AW |
4910 | Delete named textures. |
4911 | ||
8925f36f AW |
4912 | @table @asis |
4913 | @item @var{n} | |
4914 | Specifies the number of textures to be deleted. | |
4915 | ||
4916 | @item @var{textures} | |
4917 | Specifies an array of textures to be deleted. | |
4918 | ||
4919 | @end table | |
4920 | ||
8925f36f AW |
4921 | @code{glDeleteTextures} deletes @var{n} textures named by the elements |
4922 | of the array @var{textures}. After a texture is deleted, it has no | |
4923 | contents or dimensionality, and its name is free for reuse (for example | |
4924 | by @code{glGenTextures}). If a texture that is currently bound is | |
4925 | deleted, the binding reverts to 0 (the default texture). | |
4926 | ||
4927 | @code{glDeleteTextures} silently ignores 0's and names that do not | |
4928 | correspond to existing textures. | |
4929 | ||
8925f36f AW |
4930 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
4931 | ||
4932 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteTextures} is | |
4933 | executed between the execution of @code{glBegin} and the corresponding | |
4934 | execution of @code{glEnd}. | |
4935 | ||
bb894c9d | 4936 | @end deftypefun |
8925f36f | 4937 | |
bb894c9d | 4938 | @deftypefun void glDepthFunc func |
3c9b6116 AW |
4939 | Specify the value used for depth buffer comparisons. |
4940 | ||
8925f36f AW |
4941 | @table @asis |
4942 | @item @var{func} | |
4943 | Specifies the depth comparison function. Symbolic constants | |
4944 | @code{GL_NEVER}, @code{GL_LESS}, @code{GL_EQUAL}, @code{GL_LEQUAL}, | |
4945 | @code{GL_GREATER}, @code{GL_NOTEQUAL}, @code{GL_GEQUAL}, and | |
4946 | @code{GL_ALWAYS} are accepted. The initial value is @code{GL_LESS}. | |
4947 | ||
4948 | @end table | |
4949 | ||
8925f36f AW |
4950 | @code{glDepthFunc} specifies the function used to compare each incoming |
4951 | pixel depth value with the depth value present in the depth buffer. The | |
4952 | comparison is performed only if depth testing is enabled. (See | |
4953 | @code{glEnable} and @code{glDisable} of @code{GL_DEPTH_TEST}.) | |
4954 | ||
4955 | @var{func} specifies the conditions under which the pixel will be drawn. | |
4956 | The comparison functions are as follows: | |
4957 | ||
4958 | @table @asis | |
4959 | @item @code{GL_NEVER} | |
4960 | Never passes. | |
4961 | ||
4962 | @item @code{GL_LESS} | |
4963 | Passes if the incoming depth value is less than the stored depth value. | |
4964 | ||
4965 | @item @code{GL_EQUAL} | |
4966 | Passes if the incoming depth value is equal to the stored depth value. | |
4967 | ||
4968 | @item @code{GL_LEQUAL} | |
4969 | Passes if the incoming depth value is less than or equal to the stored | |
4970 | depth value. | |
4971 | ||
4972 | @item @code{GL_GREATER} | |
4973 | Passes if the incoming depth value is greater than the stored depth | |
4974 | value. | |
4975 | ||
4976 | @item @code{GL_NOTEQUAL} | |
4977 | Passes if the incoming depth value is not equal to the stored depth | |
4978 | value. | |
4979 | ||
4980 | @item @code{GL_GEQUAL} | |
4981 | Passes if the incoming depth value is greater than or equal to the | |
4982 | stored depth value. | |
4983 | ||
4984 | @item @code{GL_ALWAYS} | |
4985 | Always passes. | |
4986 | ||
4987 | @end table | |
4988 | ||
4989 | The initial value of @var{func} is @code{GL_LESS}. Initially, depth | |
4990 | testing is disabled. If depth testing is disabled or if no depth buffer | |
4991 | exists, it is as if the depth test always passes. | |
4992 | ||
8925f36f AW |
4993 | @code{GL_INVALID_ENUM} is generated if @var{func} is not an accepted |
4994 | value. | |
4995 | ||
4996 | @code{GL_INVALID_OPERATION} is generated if @code{glDepthFunc} is | |
4997 | executed between the execution of @code{glBegin} and the corresponding | |
4998 | execution of @code{glEnd}. | |
4999 | ||
bb894c9d | 5000 | @end deftypefun |
8925f36f | 5001 | |
bb894c9d | 5002 | @deftypefun void glDepthMask flag |
3c9b6116 AW |
5003 | Enable or disable writing into the depth buffer. |
5004 | ||
8925f36f AW |
5005 | @table @asis |
5006 | @item @var{flag} | |
5007 | Specifies whether the depth buffer is enabled for writing. If @var{flag} | |
5008 | is @code{GL_FALSE}, depth buffer writing is disabled. Otherwise, it is | |
5009 | enabled. Initially, depth buffer writing is enabled. | |
5010 | ||
5011 | @end table | |
5012 | ||
8925f36f AW |
5013 | @code{glDepthMask} specifies whether the depth buffer is enabled for |
5014 | writing. If @var{flag} is @code{GL_FALSE}, depth buffer writing is | |
5015 | disabled. Otherwise, it is enabled. Initially, depth buffer writing is | |
5016 | enabled. | |
5017 | ||
8925f36f AW |
5018 | @code{GL_INVALID_OPERATION} is generated if @code{glDepthMask} is |
5019 | executed between the execution of @code{glBegin} and the corresponding | |
5020 | execution of @code{glEnd}. | |
5021 | ||
bb894c9d | 5022 | @end deftypefun |
8925f36f | 5023 | |
bb894c9d | 5024 | @deftypefun void glDepthRange nearVal farVal |
3c9b6116 AW |
5025 | Specify mapping of depth values from normalized device coordinates to |
5026 | window coordinates. | |
5027 | ||
8925f36f AW |
5028 | @table @asis |
5029 | @item @var{nearVal} | |
5030 | Specifies the mapping of the near clipping plane to window coordinates. | |
5031 | The initial value is 0. | |
5032 | ||
5033 | @item @var{farVal} | |
5034 | Specifies the mapping of the far clipping plane to window coordinates. | |
5035 | The initial value is 1. | |
5036 | ||
5037 | @end table | |
5038 | ||
8925f36f | 5039 | After clipping and division by @var{w}, depth coordinates range from |
3c9b6116 | 5040 | @r{-1} to 1, corresponding to the near and far clipping planes. |
8925f36f AW |
5041 | @code{glDepthRange} specifies a linear mapping of the normalized depth |
5042 | coordinates in this range to window depth coordinates. Regardless of the | |
5043 | actual depth buffer implementation, window coordinate depth values are | |
5044 | treated as though they range from 0 through 1 (like color components). | |
5045 | Thus, the values accepted by @code{glDepthRange} are both clamped to | |
5046 | this range before they are accepted. | |
5047 | ||
5048 | The setting of (0,1) maps the near plane to 0 and the far plane to 1. | |
5049 | With this mapping, the depth buffer range is fully utilized. | |
5050 | ||
8925f36f AW |
5051 | @code{GL_INVALID_OPERATION} is generated if @code{glDepthRange} is |
5052 | executed between the execution of @code{glBegin} and the corresponding | |
5053 | execution of @code{glEnd}. | |
5054 | ||
bb894c9d | 5055 | @end deftypefun |
8925f36f | 5056 | |
bb894c9d | 5057 | @deftypefun void glDetachShader program shader |
3c9b6116 AW |
5058 | Detaches a shader object from a program object to which it is attached. |
5059 | ||
8925f36f AW |
5060 | @table @asis |
5061 | @item @var{program} | |
5062 | Specifies the program object from which to detach the shader object. | |
5063 | ||
5064 | @item @var{shader} | |
5065 | Specifies the shader object to be detached. | |
5066 | ||
5067 | @end table | |
5068 | ||
8925f36f AW |
5069 | @code{glDetachShader} detaches the shader object specified by |
5070 | @var{shader} from the program object specified by @var{program}. This | |
5071 | command can be used to undo the effect of the command | |
5072 | @code{glAttachShader}. | |
5073 | ||
5074 | If @var{shader} has already been flagged for deletion by a call to | |
5075 | @code{glDeleteShader} and it is not attached to any other program | |
5076 | object, it will be deleted after it has been detached. | |
5077 | ||
8925f36f AW |
5078 | @code{GL_INVALID_VALUE} is generated if either @var{program} or |
5079 | @var{shader} is a value that was not generated by OpenGL. | |
5080 | ||
5081 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
5082 | program object. | |
5083 | ||
5084 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
5085 | object. | |
5086 | ||
5087 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not attached | |
5088 | to @var{program}. | |
5089 | ||
5090 | @code{GL_INVALID_OPERATION} is generated if @code{glDetachShader} is | |
5091 | executed between the execution of @code{glBegin} and the corresponding | |
5092 | execution of @code{glEnd}. | |
5093 | ||
bb894c9d | 5094 | @end deftypefun |
8925f36f | 5095 | |
bb894c9d | 5096 | @deftypefun void glDrawArrays mode first count |
3c9b6116 AW |
5097 | Render primitives from array data. |
5098 | ||
8925f36f AW |
5099 | @table @asis |
5100 | @item @var{mode} | |
5101 | Specifies what kind of primitives to render. Symbolic constants | |
5102 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, | |
5103 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
5104 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
5105 | @code{GL_POLYGON} are accepted. | |
5106 | ||
5107 | @item @var{first} | |
5108 | Specifies the starting index in the enabled arrays. | |
5109 | ||
5110 | @item @var{count} | |
5111 | Specifies the number of indices to be rendered. | |
5112 | ||
5113 | @end table | |
5114 | ||
8925f36f AW |
5115 | @code{glDrawArrays} specifies multiple geometric primitives with very |
5116 | few subroutine calls. Instead of calling a GL procedure to pass each | |
5117 | individual vertex, normal, texture coordinate, edge flag, or color, you | |
5118 | can prespecify separate arrays of vertices, normals, and colors and use | |
5119 | them to construct a sequence of primitives with a single call to | |
5120 | @code{glDrawArrays}. | |
5121 | ||
5122 | When @code{glDrawArrays} is called, it uses @var{count} sequential | |
5123 | elements from each enabled array to construct a sequence of geometric | |
5124 | primitives, beginning with element @var{first}. @var{mode} specifies | |
5125 | what kind of primitives are constructed and how the array elements | |
5126 | construct those primitives. If @code{GL_VERTEX_ARRAY} is not enabled, no | |
5127 | geometric primitives are generated. | |
5128 | ||
5129 | Vertex attributes that are modified by @code{glDrawArrays} have an | |
5130 | unspecified value after @code{glDrawArrays} returns. For example, if | |
5131 | @code{GL_COLOR_ARRAY} is enabled, the value of the current color is | |
5132 | undefined after @code{glDrawArrays} executes. Attributes that aren't | |
5133 | modified remain well defined. | |
5134 | ||
8925f36f AW |
5135 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
5136 | value. | |
5137 | ||
5138 | @code{GL_INVALID_VALUE} is generated if @var{count} is negative. | |
5139 | ||
5140 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5141 | name is bound to an enabled array and the buffer object's data store is | |
5142 | currently mapped. | |
5143 | ||
5144 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawArrays} is | |
5145 | executed between the execution of @code{glBegin} and the corresponding | |
5146 | @code{glEnd}. | |
5147 | ||
bb894c9d | 5148 | @end deftypefun |
8925f36f | 5149 | |
bb894c9d | 5150 | @deftypefun void glDrawBuffers n bufs |
3c9b6116 AW |
5151 | Specifies a list of color buffers to be drawn into. |
5152 | ||
8925f36f AW |
5153 | @table @asis |
5154 | @item @var{n} | |
5155 | Specifies the number of buffers in @var{bufs}. | |
5156 | ||
5157 | @item @var{bufs} | |
5158 | Points to an array of symbolic constants specifying the buffers into | |
5159 | which fragment colors or data values will be written. | |
5160 | ||
5161 | @end table | |
5162 | ||
8925f36f AW |
5163 | @code{glDrawBuffers} defines an array of buffers into which fragment |
5164 | color values or fragment data will be written. If no fragment shader is | |
5165 | active, rendering operations will generate only one fragment color per | |
5166 | fragment and it will be written into each of the buffers specified by | |
5167 | @var{bufs}. If a fragment shader is active and it writes a value to the | |
5168 | output variable @code{gl_FragColor}, then that value will be written | |
5169 | into each of the buffers specified by @var{bufs}. If a fragment shader | |
5170 | is active and it writes a value to one or more elements of the output | |
5171 | array variable @code{gl_FragData[]}, then the value of | |
5172 | @code{gl_FragData[0] } will be written into the first buffer specified | |
5173 | by @var{bufs}, the value of @code{gl_FragData[1] } will be written into | |
5174 | the second buffer specified by @var{bufs}, and so on up to | |
5175 | @code{gl_FragData[n-1]}. The draw buffer used for @code{gl_FragData[n]} | |
5176 | and beyond is implicitly set to be @code{GL_NONE}. | |
5177 | ||
5178 | The symbolic constants contained in @var{bufs} may be any of the | |
5179 | following: | |
5180 | ||
5181 | @table @asis | |
5182 | @item @code{GL_NONE} | |
5183 | The fragment color/data value is not written into any color buffer. | |
5184 | ||
5185 | @item @code{GL_FRONT_LEFT} | |
5186 | The fragment color/data value is written into the front left color | |
5187 | buffer. | |
5188 | ||
5189 | @item @code{GL_FRONT_RIGHT} | |
5190 | The fragment color/data value is written into the front right color | |
5191 | buffer. | |
5192 | ||
5193 | @item @code{GL_BACK_LEFT} | |
5194 | The fragment color/data value is written into the back left color | |
5195 | buffer. | |
5196 | ||
5197 | @item @code{GL_BACK_RIGHT} | |
5198 | The fragment color/data value is written into the back right color | |
5199 | buffer. | |
5200 | ||
5201 | @item @code{GL_AUXi} | |
5202 | The fragment color/data value is written into auxiliary buffer @code{i}. | |
5203 | ||
5204 | @end table | |
5205 | ||
5206 | Except for @code{GL_NONE}, the preceding symbolic constants may not | |
5207 | appear more than once in @var{bufs}. The maximum number of draw buffers | |
5208 | supported is implementation dependent and can be queried by calling | |
5209 | @code{glGet} with the argument @code{GL_MAX_DRAW_BUFFERS}. The number of | |
5210 | auxiliary buffers can be queried by calling @code{glGet} with the | |
5211 | argument @code{GL_AUX_BUFFERS}. | |
5212 | ||
8925f36f AW |
5213 | @code{GL_INVALID_ENUM} is generated if one of the values in @var{bufs} |
5214 | is not an accepted value. | |
5215 | ||
5216 | @code{GL_INVALID_ENUM} is generated if @var{n} is less than 0. | |
5217 | ||
5218 | @code{GL_INVALID_OPERATION} is generated if a symbolic constant other | |
5219 | than @code{GL_NONE} appears more than once in @var{bufs}. | |
5220 | ||
5221 | @code{GL_INVALID_OPERATION} is generated if any of the entries in | |
5222 | @var{bufs} (other than @code{GL_NONE} ) indicates a color buffer that | |
5223 | does not exist in the current GL context. | |
5224 | ||
5225 | @code{GL_INVALID_VALUE} is generated if @var{n} is greater than | |
5226 | @code{GL_MAX_DRAW_BUFFERS}. | |
5227 | ||
5228 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawBuffers} is | |
5229 | executed between the execution of @code{glBegin} and the corresponding | |
5230 | execution of @code{glEnd}. | |
5231 | ||
bb894c9d | 5232 | @end deftypefun |
8925f36f | 5233 | |
bb894c9d | 5234 | @deftypefun void glDrawBuffer mode |
3c9b6116 AW |
5235 | Specify which color buffers are to be drawn into. |
5236 | ||
8925f36f AW |
5237 | @table @asis |
5238 | @item @var{mode} | |
5239 | Specifies up to four color buffers to be drawn into. Symbolic constants | |
5240 | @code{GL_NONE}, @code{GL_FRONT_LEFT}, @code{GL_FRONT_RIGHT}, | |
5241 | @code{GL_BACK_LEFT}, @code{GL_BACK_RIGHT}, @code{GL_FRONT}, | |
5242 | @code{GL_BACK}, @code{GL_LEFT}, @code{GL_RIGHT}, | |
5243 | @code{GL_FRONT_AND_BACK}, and @code{GL_AUX}@var{i}, where @var{i} is | |
5244 | between 0 and the value of @code{GL_AUX_BUFFERS} minus 1, are accepted. | |
5245 | (@code{GL_AUX_BUFFERS} is not the upper limit; use @code{glGet} to query | |
5246 | the number of available aux buffers.) The initial value is | |
5247 | @code{GL_FRONT} for single-buffered contexts, and @code{GL_BACK} for | |
5248 | double-buffered contexts. | |
5249 | ||
5250 | @end table | |
5251 | ||
8925f36f AW |
5252 | When colors are written to the frame buffer, they are written into the |
5253 | color buffers specified by @code{glDrawBuffer}. The specifications are | |
5254 | as follows: | |
5255 | ||
5256 | @table @asis | |
5257 | @item @code{GL_NONE} | |
5258 | No color buffers are written. | |
5259 | ||
5260 | @item @code{GL_FRONT_LEFT} | |
5261 | Only the front left color buffer is written. | |
5262 | ||
5263 | @item @code{GL_FRONT_RIGHT} | |
5264 | Only the front right color buffer is written. | |
5265 | ||
5266 | @item @code{GL_BACK_LEFT} | |
5267 | Only the back left color buffer is written. | |
5268 | ||
5269 | @item @code{GL_BACK_RIGHT} | |
5270 | Only the back right color buffer is written. | |
5271 | ||
5272 | @item @code{GL_FRONT} | |
5273 | Only the front left and front right color buffers are written. If there | |
5274 | is no front right color buffer, only the front left color buffer is | |
5275 | written. | |
5276 | ||
5277 | @item @code{GL_BACK} | |
5278 | Only the back left and back right color buffers are written. If there is | |
5279 | no back right color buffer, only the back left color buffer is written. | |
5280 | ||
5281 | @item @code{GL_LEFT} | |
5282 | Only the front left and back left color buffers are written. If there is | |
5283 | no back left color buffer, only the front left color buffer is written. | |
5284 | ||
5285 | @item @code{GL_RIGHT} | |
5286 | Only the front right and back right color buffers are written. If there | |
5287 | is no back right color buffer, only the front right color buffer is | |
5288 | written. | |
5289 | ||
5290 | @item @code{GL_FRONT_AND_BACK} | |
5291 | All the front and back color buffers (front left, front right, back | |
5292 | left, back right) are written. If there are no back color buffers, only | |
5293 | the front left and front right color buffers are written. If there are | |
5294 | no right color buffers, only the front left and back left color buffers | |
5295 | are written. If there are no right or back color buffers, only the front | |
5296 | left color buffer is written. | |
5297 | ||
5298 | @item @code{GL_AUX}@var{i} | |
5299 | Only auxiliary color buffer @var{i} is written. | |
5300 | ||
5301 | @end table | |
5302 | ||
5303 | If more than one color buffer is selected for drawing, then blending or | |
5304 | logical operations are computed and applied independently for each color | |
5305 | buffer and can produce different results in each buffer. | |
5306 | ||
5307 | Monoscopic contexts include only @var{left} buffers, and stereoscopic | |
5308 | contexts include both @var{left} and @var{right} buffers. Likewise, | |
5309 | single-buffered contexts include only @var{front} buffers, and | |
5310 | double-buffered contexts include both @var{front} and @var{back} | |
5311 | buffers. The context is selected at GL initialization. | |
5312 | ||
8925f36f AW |
5313 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
5314 | value. | |
5315 | ||
5316 | @code{GL_INVALID_OPERATION} is generated if none of the buffers | |
5317 | indicated by @var{mode} exists. | |
5318 | ||
5319 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawBuffer} is | |
5320 | executed between the execution of @code{glBegin} and the corresponding | |
5321 | execution of @code{glEnd}. | |
5322 | ||
bb894c9d | 5323 | @end deftypefun |
8925f36f | 5324 | |
bb894c9d | 5325 | @deftypefun void glDrawElements mode count type indices |
3c9b6116 AW |
5326 | Render primitives from array data. |
5327 | ||
8925f36f AW |
5328 | @table @asis |
5329 | @item @var{mode} | |
5330 | Specifies what kind of primitives to render. Symbolic constants | |
5331 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, | |
5332 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
5333 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
5334 | @code{GL_POLYGON} are accepted. | |
5335 | ||
5336 | @item @var{count} | |
5337 | Specifies the number of elements to be rendered. | |
5338 | ||
5339 | @item @var{type} | |
5340 | Specifies the type of the values in @var{indices}. Must be one of | |
5341 | @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or | |
5342 | @code{GL_UNSIGNED_INT}. | |
5343 | ||
5344 | @item @var{indices} | |
5345 | Specifies a pointer to the location where the indices are stored. | |
5346 | ||
5347 | @end table | |
5348 | ||
8925f36f AW |
5349 | @code{glDrawElements} specifies multiple geometric primitives with very |
5350 | few subroutine calls. Instead of calling a GL function to pass each | |
5351 | individual vertex, normal, texture coordinate, edge flag, or color, you | |
5352 | can prespecify separate arrays of vertices, normals, and so on, and use | |
5353 | them to construct a sequence of primitives with a single call to | |
5354 | @code{glDrawElements}. | |
5355 | ||
5356 | When @code{glDrawElements} is called, it uses @var{count} sequential | |
5357 | elements from an enabled array, starting at @var{indices} to construct a | |
5358 | sequence of geometric primitives. @var{mode} specifies what kind of | |
5359 | primitives are constructed and how the array elements construct these | |
5360 | primitives. If more than one array is enabled, each is used. If | |
5361 | @code{GL_VERTEX_ARRAY} is not enabled, no geometric primitives are | |
5362 | constructed. | |
5363 | ||
5364 | Vertex attributes that are modified by @code{glDrawElements} have an | |
5365 | unspecified value after @code{glDrawElements} returns. For example, if | |
5366 | @code{GL_COLOR_ARRAY} is enabled, the value of the current color is | |
5367 | undefined after @code{glDrawElements} executes. Attributes that aren't | |
5368 | modified maintain their previous values. | |
5369 | ||
8925f36f AW |
5370 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
5371 | value. | |
5372 | ||
5373 | @code{GL_INVALID_VALUE} is generated if @var{count} is negative. | |
5374 | ||
5375 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5376 | name is bound to an enabled array or the element array and the buffer | |
5377 | object's data store is currently mapped. | |
5378 | ||
5379 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawElements} is | |
5380 | executed between the execution of @code{glBegin} and the corresponding | |
5381 | @code{glEnd}. | |
5382 | ||
bb894c9d | 5383 | @end deftypefun |
8925f36f | 5384 | |
bb894c9d | 5385 | @deftypefun void glDrawPixels width height format type data |
3c9b6116 AW |
5386 | Write a block of pixels to the frame buffer. |
5387 | ||
8925f36f AW |
5388 | @table @asis |
5389 | @item @var{width} | |
5390 | @itemx @var{height} | |
5391 | Specify the dimensions of the pixel rectangle to be written into the | |
5392 | frame buffer. | |
5393 | ||
5394 | @item @var{format} | |
5395 | Specifies the format of the pixel data. Symbolic constants | |
5396 | @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, | |
5397 | @code{GL_DEPTH_COMPONENT}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, | |
5398 | @code{GL_BGRA}, @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, | |
5399 | @code{GL_ALPHA}, @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA} are | |
5400 | accepted. | |
5401 | ||
5402 | @item @var{type} | |
5403 | Specifies the data type for @var{data}. Symbolic constants | |
5404 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
5405 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
5406 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
5407 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
5408 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
5409 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
5410 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
5411 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
5412 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
5413 | ||
5414 | @item @var{data} | |
5415 | Specifies a pointer to the pixel data. | |
5416 | ||
5417 | @end table | |
5418 | ||
8925f36f AW |
5419 | @code{glDrawPixels} reads pixel data from memory and writes it into the |
5420 | frame buffer relative to the current raster position, provided that the | |
5421 | raster position is valid. Use @code{glRasterPos} or @code{glWindowPos} | |
5422 | to set the current raster position; use @code{glGet} with argument | |
5423 | @code{GL_CURRENT_RASTER_POSITION_VALID} to determine if the specified | |
5424 | raster position is valid, and @code{glGet} with argument | |
5425 | @code{GL_CURRENT_RASTER_POSITION} to query the raster position. | |
5426 | ||
5427 | Several parameters define the encoding of pixel data in memory and | |
5428 | control the processing of the pixel data before it is placed in the | |
5429 | frame buffer. These parameters are set with four commands: | |
5430 | @code{glPixelStore}, @code{glPixelTransfer}, @code{glPixelMap}, and | |
5431 | @code{glPixelZoom}. This reference page describes the effects on | |
5432 | @code{glDrawPixels} of many, but not all, of the parameters specified by | |
5433 | these four commands. | |
5434 | ||
5435 | Data is read from @var{data} as a sequence of signed or unsigned bytes, | |
5436 | signed or unsigned shorts, signed or unsigned integers, or | |
5437 | single-precision floating-point values, depending on @var{type}. When | |
5438 | @var{type} is one of @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, | |
5439 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
5440 | @code{GL_INT}, or @code{GL_FLOAT} each of these bytes, shorts, integers, | |
5441 | or floating-point values is interpreted as one color or depth component, | |
5442 | or one index, depending on @var{format}. When @var{type} is one of | |
5443 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
5444 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
5445 | @code{GL_UNSIGNED_INT_8_8_8_8}, or @code{GL_UNSIGNED_INT_10_10_10_2}, | |
5446 | each unsigned value is interpreted as containing all the components for | |
5447 | a single pixel, with the color components arranged according to | |
5448 | @var{format}. When @var{type} is one of | |
5449 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
5450 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
5451 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
5452 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, or | |
5453 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}, each unsigned value is | |
5454 | interpreted as containing all color components, specified by | |
5455 | @var{format}, for a single pixel in a reversed order. Indices are always | |
5456 | treated individually. Color components are treated as groups of one, | |
5457 | two, three, or four values, again based on @var{format}. Both individual | |
5458 | indices and groups of components are referred to as pixels. If | |
5459 | @var{type} is @code{GL_BITMAP}, the data must be unsigned bytes, and | |
5460 | @var{format} must be either @code{GL_COLOR_INDEX} or | |
5461 | @code{GL_STENCIL_INDEX}. Each unsigned byte is treated as eight 1-bit | |
5462 | pixels, with bit ordering determined by @code{GL_UNPACK_LSB_FIRST} (see | |
5463 | @code{glPixelStore}). | |
5464 | ||
3c9b6116 | 5465 | @r{@var{width}×@var{height}} pixels are read from memory, starting at |
8925f36f AW |
5466 | location @var{data}. By default, these pixels are taken from adjacent |
5467 | memory locations, except that after all @var{width} pixels are read, the | |
5468 | read pointer is advanced to the next four-byte boundary. The four-byte | |
5469 | row alignment is specified by @code{glPixelStore} with argument | |
5470 | @code{GL_UNPACK_ALIGNMENT}, and it can be set to one, two, four, or | |
5471 | eight bytes. Other pixel store parameters specify different read pointer | |
5472 | advancements, both before the first pixel is read and after all | |
5473 | @var{width} pixels are read. See the @code{glPixelStore} reference page | |
5474 | for details on these options. | |
5475 | ||
5476 | If a non-zero named buffer object is bound to the | |
5477 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
5478 | block of pixels is specified, @var{data} is treated as a byte offset | |
5479 | into the buffer object's data store. | |
5480 | ||
3c9b6116 | 5481 | The @r{@var{width}×@var{height}} pixels that are read from memory are |
8925f36f AW |
5482 | each operated on in the same way, based on the values of several |
5483 | parameters specified by @code{glPixelTransfer} and @code{glPixelMap}. | |
5484 | The details of these operations, as well as the target buffer into which | |
5485 | the pixels are drawn, are specific to the format of the pixels, as | |
5486 | specified by @var{format}. @var{format} can assume one of 13 symbolic | |
5487 | values: | |
5488 | ||
5489 | @table @asis | |
5490 | @item @code{GL_COLOR_INDEX} | |
5491 | Each pixel is a single value, a color index. It is converted to | |
5492 | fixed-point format, with an unspecified number of bits to the right of | |
5493 | the binary point, regardless of the memory data type. Floating-point | |
5494 | values convert to true fixed-point values. Signed and unsigned integer | |
5495 | data is converted with all fraction bits set to 0. Bitmap data convert | |
5496 | to either 0 or 1. | |
5497 | ||
5498 | Each fixed-point index is then shifted left by @code{GL_INDEX_SHIFT} | |
5499 | bits and added to @code{GL_INDEX_OFFSET}. If @code{GL_INDEX_SHIFT} is | |
5500 | negative, the shift is to the right. In either case, zero bits fill | |
5501 | otherwise unspecified bit locations in the result. | |
5502 | ||
5503 | If the GL is in RGBA mode, the resulting index is converted to an RGBA | |
5504 | pixel with the help of the @code{GL_PIXEL_MAP_I_TO_R}, | |
5505 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
5506 | @code{GL_PIXEL_MAP_I_TO_A} tables. If the GL is in color index mode, and | |
5507 | if @code{GL_MAP_COLOR} is true, the index is replaced with the value | |
5508 | that it references in lookup table @code{GL_PIXEL_MAP_I_TO_I}. Whether | |
5509 | the lookup replacement of the index is done or not, the integer part of | |
3c9b6116 AW |
5510 | the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the |
5511 | number of bits in a color index buffer. | |
8925f36f AW |
5512 | |
5513 | The GL then converts the resulting indices or RGBA colors to fragments | |
5514 | by attaching the current raster position @var{z} coordinate and texture | |
3c9b6116 AW |
5515 | coordinates to each pixel, then assigning @r{@var{x}} and @r{@var{y}} |
5516 | window coordinates to the @r{@var{n}}th fragment such that | |
5517 | @r{@var{x}_@var{n}=@var{x}_@var{r}+@var{n}%@var{width}}@r{@var{y}_@var{n}=@var{y}_@var{r}+⌊@var{n}/@var{width},⌋} | |
8925f36f | 5518 | |
3c9b6116 | 5519 | where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster |
8925f36f AW |
5520 | position. These pixel fragments are then treated just like the fragments |
5521 | generated by rasterizing points, lines, or polygons. Texture mapping, | |
5522 | fog, and all the fragment operations are applied before the fragments | |
5523 | are written to the frame buffer. | |
5524 | ||
5525 | @item @code{GL_STENCIL_INDEX} | |
5526 | Each pixel is a single value, a stencil index. It is converted to | |
5527 | fixed-point format, with an unspecified number of bits to the right of | |
5528 | the binary point, regardless of the memory data type. Floating-point | |
5529 | values convert to true fixed-point values. Signed and unsigned integer | |
5530 | data is converted with all fraction bits set to 0. Bitmap data convert | |
5531 | to either 0 or 1. | |
5532 | ||
5533 | Each fixed-point index is then shifted left by @code{GL_INDEX_SHIFT} | |
5534 | bits, and added to @code{GL_INDEX_OFFSET}. If @code{GL_INDEX_SHIFT} is | |
5535 | negative, the shift is to the right. In either case, zero bits fill | |
5536 | otherwise unspecified bit locations in the result. If | |
5537 | @code{GL_MAP_STENCIL} is true, the index is replaced with the value that | |
5538 | it references in lookup table @code{GL_PIXEL_MAP_S_TO_S}. Whether the | |
5539 | lookup replacement of the index is done or not, the integer part of the | |
3c9b6116 | 5540 | index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the |
8925f36f | 5541 | number of bits in the stencil buffer. The resulting stencil indices are |
3c9b6116 AW |
5542 | then written to the stencil buffer such that the @r{@var{n}}th index is |
5543 | written to location | |
8925f36f | 5544 | |
3c9b6116 | 5545 | @r{@var{x}_@var{n}=@var{x}_@var{r}+@var{n}%@var{width}}@r{@var{y}_@var{n}=@var{y}_@var{r}+⌊@var{n}/@var{width},⌋} |
8925f36f | 5546 | |
3c9b6116 | 5547 | where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster |
8925f36f AW |
5548 | position. Only the pixel ownership test, the scissor test, and the |
5549 | stencil writemask affect these write operations. | |
5550 | ||
5551 | @item @code{GL_DEPTH_COMPONENT} | |
5552 | Each pixel is a single-depth component. Floating-point data is converted | |
5553 | directly to an internal floating-point format with unspecified | |
5554 | precision. Signed integer data is mapped linearly to the internal | |
5555 | floating-point format such that the most positive representable integer | |
5556 | value maps to 1.0, and the most negative representable value maps to | |
3c9b6116 AW |
5557 | @r{-1.0}. Unsigned integer data is mapped similarly: the largest integer |
5558 | value maps to 1.0, and 0 maps to 0.0. The resulting floating-point depth | |
5559 | value is then multiplied by @code{GL_DEPTH_SCALE} and added to | |
5560 | @code{GL_DEPTH_BIAS}. The result is clamped to the range @r{[0,1]}. | |
8925f36f AW |
5561 | |
5562 | The GL then converts the resulting depth components to fragments by | |
5563 | attaching the current raster position color or color index and texture | |
3c9b6116 AW |
5564 | coordinates to each pixel, then assigning @r{@var{x}} and @r{@var{y}} |
5565 | window coordinates to the @r{@var{n}}th fragment such that | |
8925f36f | 5566 | |
3c9b6116 | 5567 | @r{@var{x}_@var{n}=@var{x}_@var{r}+@var{n}%@var{width}}@r{@var{y}_@var{n}=@var{y}_@var{r}+⌊@var{n}/@var{width},⌋} |
8925f36f | 5568 | |
3c9b6116 | 5569 | where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster |
8925f36f AW |
5570 | position. These pixel fragments are then treated just like the fragments |
5571 | generated by rasterizing points, lines, or polygons. Texture mapping, | |
5572 | fog, and all the fragment operations are applied before the fragments | |
5573 | are written to the frame buffer. | |
5574 | ||
5575 | @item @code{GL_RGBA} | |
5576 | @item @code{GL_BGRA} | |
5577 | Each pixel is a four-component group: For @code{GL_RGBA}, the red | |
5578 | component is first, followed by green, followed by blue, followed by | |
5579 | alpha; for @code{GL_BGRA} the order is blue, green, red and then alpha. | |
5580 | Floating-point values are converted directly to an internal | |
5581 | floating-point format with unspecified precision. Signed integer values | |
5582 | are mapped linearly to the internal floating-point format such that the | |
5583 | most positive representable integer value maps to 1.0, and the most | |
3c9b6116 AW |
5584 | negative representable value maps to @r{-1.0}. (Note that this mapping |
5585 | does not convert 0 precisely to 0.0.) Unsigned integer data is mapped | |
5586 | similarly: The largest integer value maps to 1.0, and 0 maps to 0.0. The | |
5587 | resulting floating-point color values are then multiplied by | |
8925f36f AW |
5588 | @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is RED, |
5589 | GREEN, BLUE, and ALPHA for the respective color components. The results | |
3c9b6116 | 5590 | are clamped to the range @r{[0,1]}. |
8925f36f AW |
5591 | |
5592 | If @code{GL_MAP_COLOR} is true, each color component is scaled by the | |
5593 | size of lookup table @code{GL_PIXEL_MAP_c_TO_c}, then replaced by the | |
5594 | value that it references in that table. @var{c} is R, G, B, or A | |
5595 | respectively. | |
5596 | ||
5597 | The GL then converts the resulting RGBA colors to fragments by attaching | |
5598 | the current raster position @var{z} coordinate and texture coordinates | |
3c9b6116 AW |
5599 | to each pixel, then assigning @r{@var{x}} and @r{@var{y}} window |
5600 | coordinates to the @r{@var{n}}th fragment such that | |
8925f36f | 5601 | |
3c9b6116 | 5602 | @r{@var{x}_@var{n}=@var{x}_@var{r}+@var{n}%@var{width}}@r{@var{y}_@var{n}=@var{y}_@var{r}+⌊@var{n}/@var{width},⌋} |
8925f36f | 5603 | |
3c9b6116 | 5604 | where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster |
8925f36f AW |
5605 | position. These pixel fragments are then treated just like the fragments |
5606 | generated by rasterizing points, lines, or polygons. Texture mapping, | |
5607 | fog, and all the fragment operations are applied before the fragments | |
5608 | are written to the frame buffer. | |
5609 | ||
5610 | @item @code{GL_RED} | |
5611 | Each pixel is a single red component. This component is converted to the | |
5612 | internal floating-point format in the same way the red component of an | |
5613 | RGBA pixel is. It is then converted to an RGBA pixel with green and blue | |
5614 | set to 0, and alpha set to 1. After this conversion, the pixel is | |
5615 | treated as if it had been read as an RGBA pixel. | |
5616 | ||
5617 | @item @code{GL_GREEN} | |
5618 | Each pixel is a single green component. This component is converted to | |
5619 | the internal floating-point format in the same way the green component | |
5620 | of an RGBA pixel is. It is then converted to an RGBA pixel with red and | |
5621 | blue set to 0, and alpha set to 1. After this conversion, the pixel is | |
5622 | treated as if it had been read as an RGBA pixel. | |
5623 | ||
5624 | @item @code{GL_BLUE} | |
5625 | Each pixel is a single blue component. This component is converted to | |
5626 | the internal floating-point format in the same way the blue component of | |
5627 | an RGBA pixel is. It is then converted to an RGBA pixel with red and | |
5628 | green set to 0, and alpha set to 1. After this conversion, the pixel is | |
5629 | treated as if it had been read as an RGBA pixel. | |
5630 | ||
5631 | @item @code{GL_ALPHA} | |
5632 | Each pixel is a single alpha component. This component is converted to | |
5633 | the internal floating-point format in the same way the alpha component | |
5634 | of an RGBA pixel is. It is then converted to an RGBA pixel with red, | |
5635 | green, and blue set to 0. After this conversion, the pixel is treated as | |
5636 | if it had been read as an RGBA pixel. | |
5637 | ||
5638 | @item @code{GL_RGB} | |
5639 | @item @code{GL_BGR} | |
5640 | Each pixel is a three-component group: red first, followed by green, | |
5641 | followed by blue; for @code{GL_BGR}, the first component is blue, | |
5642 | followed by green and then red. Each component is converted to the | |
5643 | internal floating-point format in the same way the red, green, and blue | |
5644 | components of an RGBA pixel are. The color triple is converted to an | |
5645 | RGBA pixel with alpha set to 1. After this conversion, the pixel is | |
5646 | treated as if it had been read as an RGBA pixel. | |
5647 | ||
5648 | @item @code{GL_LUMINANCE} | |
5649 | Each pixel is a single luminance component. This component is converted | |
5650 | to the internal floating-point format in the same way the red component | |
5651 | of an RGBA pixel is. It is then converted to an RGBA pixel with red, | |
5652 | green, and blue set to the converted luminance value, and alpha set to | |
5653 | 1. After this conversion, the pixel is treated as if it had been read as | |
5654 | an RGBA pixel. | |
5655 | ||
5656 | @item @code{GL_LUMINANCE_ALPHA} | |
5657 | Each pixel is a two-component group: luminance first, followed by alpha. | |
5658 | The two components are converted to the internal floating-point format | |
5659 | in the same way the red component of an RGBA pixel is. They are then | |
5660 | converted to an RGBA pixel with red, green, and blue set to the | |
5661 | converted luminance value, and alpha set to the converted alpha value. | |
5662 | After this conversion, the pixel is treated as if it had been read as an | |
5663 | RGBA pixel. | |
5664 | ||
5665 | @end table | |
5666 | ||
5667 | The following table summarizes the meaning of the valid constants for | |
5668 | the @var{type} parameter: | |
5669 | ||
5670 | ||
5671 | ||
5672 | @table @asis | |
5673 | @item @strong{Type} | |
5674 | @strong{Corresponding Type} | |
5675 | ||
5676 | @item @code{GL_UNSIGNED_BYTE} | |
5677 | unsigned 8-bit integer | |
5678 | ||
5679 | @item @code{GL_BYTE} | |
5680 | signed 8-bit integer | |
5681 | ||
5682 | @item @code{GL_BITMAP} | |
5683 | single bits in unsigned 8-bit integers | |
5684 | ||
5685 | @item @code{GL_UNSIGNED_SHORT} | |
5686 | unsigned 16-bit integer | |
5687 | ||
5688 | @item @code{GL_SHORT} | |
5689 | signed 16-bit integer | |
5690 | ||
5691 | @item @code{GL_UNSIGNED_INT} | |
5692 | unsigned 32-bit integer | |
5693 | ||
5694 | @item @code{GL_INT} | |
5695 | 32-bit integer | |
5696 | ||
5697 | @item @code{GL_FLOAT} | |
5698 | single-precision floating-point | |
5699 | ||
5700 | @item @code{GL_UNSIGNED_BYTE_3_3_2} | |
5701 | unsigned 8-bit integer | |
5702 | ||
5703 | @item @code{GL_UNSIGNED_BYTE_2_3_3_REV} | |
5704 | unsigned 8-bit integer with reversed component ordering | |
5705 | ||
5706 | @item @code{GL_UNSIGNED_SHORT_5_6_5} | |
5707 | unsigned 16-bit integer | |
5708 | ||
5709 | @item @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
5710 | unsigned 16-bit integer with reversed component ordering | |
5711 | ||
5712 | @item @code{GL_UNSIGNED_SHORT_4_4_4_4} | |
5713 | unsigned 16-bit integer | |
5714 | ||
5715 | @item @code{GL_UNSIGNED_SHORT_4_4_4_4_REV} | |
5716 | unsigned 16-bit integer with reversed component ordering | |
5717 | ||
5718 | @item @code{GL_UNSIGNED_SHORT_5_5_5_1} | |
5719 | unsigned 16-bit integer | |
5720 | ||
5721 | @item @code{GL_UNSIGNED_SHORT_1_5_5_5_REV} | |
5722 | unsigned 16-bit integer with reversed component ordering | |
5723 | ||
5724 | @item @code{GL_UNSIGNED_INT_8_8_8_8} | |
5725 | unsigned 32-bit integer | |
5726 | ||
5727 | @item @code{GL_UNSIGNED_INT_8_8_8_8_REV} | |
5728 | unsigned 32-bit integer with reversed component ordering | |
5729 | ||
5730 | @item @code{GL_UNSIGNED_INT_10_10_10_2} | |
5731 | unsigned 32-bit integer | |
5732 | ||
5733 | @item @code{GL_UNSIGNED_INT_2_10_10_10_REV} | |
5734 | unsigned 32-bit integer with reversed component ordering | |
5735 | ||
5736 | @end table | |
5737 | ||
5738 | ||
5739 | ||
5740 | The rasterization described so far assumes pixel zoom factors of 1. If | |
3c9b6116 AW |
5741 | @code{glPixelZoom} is used to change the @r{@var{x}} and @r{@var{y}} |
5742 | pixel zoom factors, pixels are converted to fragments as follows. If | |
5743 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position, | |
5744 | and a given pixel is in the @r{@var{n}}th column and @r{@var{m}}th row | |
5745 | of the pixel rectangle, then fragments are generated for pixels whose | |
5746 | centers are in the rectangle with corners at | |
8925f36f | 5747 | |
3c9b6116 | 5748 | @r{(@var{x}_@var{r}+@var{zoom}_@var{x},@var{n},@var{y}_@var{r}+@var{zoom}_@var{y},@var{m})}@r{(@var{x}_@var{r}+@var{zoom}_@var{x},(@var{n}+1,),@var{y}_@var{r}+@var{zoom}_@var{y},(@var{m}+1,))} |
8925f36f | 5749 | |
3c9b6116 AW |
5750 | where @r{@var{zoom}_@var{x}} is the value of @code{GL_ZOOM_X} and |
5751 | @r{@var{zoom}_@var{y}} is the value of @code{GL_ZOOM_Y}. | |
8925f36f | 5752 | |
8925f36f AW |
5753 | @code{GL_INVALID_ENUM} is generated if @var{format} or @var{type} is not |
5754 | one of the accepted values. | |
5755 | ||
5756 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
5757 | and @var{format} is not either @code{GL_COLOR_INDEX} or | |
5758 | @code{GL_STENCIL_INDEX}. | |
5759 | ||
5760 | @code{GL_INVALID_VALUE} is generated if either @var{width} or | |
5761 | @var{height} is negative. | |
5762 | ||
5763 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
5764 | @code{GL_STENCIL_INDEX} and there is no stencil buffer. | |
5765 | ||
5766 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
5767 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, | |
5768 | @code{GL_RGB}, @code{GL_RGBA}, @code{GL_BGR}, @code{GL_BGRA}, | |
5769 | @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}, and the GL is in | |
5770 | color index mode. | |
5771 | ||
5772 | @code{GL_INVALID_OPERATION} is generated if @var{format} is one of | |
5773 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
5774 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
5775 | and @var{format} is not @code{GL_RGB}. | |
5776 | ||
5777 | @code{GL_INVALID_OPERATION} is generated if @var{format} is one of | |
5778 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
5779 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
5780 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
5781 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
5782 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
5783 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
5784 | ||
5785 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5786 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
5787 | object's data store is currently mapped. | |
5788 | ||
5789 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5790 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
5791 | would be unpacked from the buffer object such that the memory reads | |
5792 | required would exceed the data store size. | |
5793 | ||
5794 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5795 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
5796 | is not evenly divisible into the number of bytes needed to store in | |
5797 | memory a datum indicated by @var{type}. | |
5798 | ||
5799 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawPixels} is | |
5800 | executed between the execution of @code{glBegin} and the corresponding | |
5801 | execution of @code{glEnd}. | |
5802 | ||
bb894c9d | 5803 | @end deftypefun |
8925f36f | 5804 | |
bb894c9d | 5805 | @deftypefun void glDrawRangeElements mode start end count type indices |
3c9b6116 AW |
5806 | Render primitives from array data. |
5807 | ||
8925f36f AW |
5808 | @table @asis |
5809 | @item @var{mode} | |
5810 | Specifies what kind of primitives to render. Symbolic constants | |
5811 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, | |
5812 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
5813 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
5814 | @code{GL_POLYGON} are accepted. | |
5815 | ||
5816 | @item @var{start} | |
5817 | Specifies the minimum array index contained in @var{indices}. | |
5818 | ||
5819 | @item @var{end} | |
5820 | Specifies the maximum array index contained in @var{indices}. | |
5821 | ||
5822 | @item @var{count} | |
5823 | Specifies the number of elements to be rendered. | |
5824 | ||
5825 | @item @var{type} | |
5826 | Specifies the type of the values in @var{indices}. Must be one of | |
5827 | @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or | |
5828 | @code{GL_UNSIGNED_INT}. | |
5829 | ||
5830 | @item @var{indices} | |
5831 | Specifies a pointer to the location where the indices are stored. | |
5832 | ||
5833 | @end table | |
5834 | ||
8925f36f AW |
5835 | @code{glDrawRangeElements} is a restricted form of |
5836 | @code{glDrawElements}. @var{mode}, @var{start}, @var{end}, and | |
5837 | @var{count} match the corresponding arguments to @code{glDrawElements}, | |
5838 | with the additional constraint that all values in the arrays @var{count} | |
5839 | must lie between @var{start} and @var{end}, inclusive. | |
5840 | ||
5841 | Implementations denote recommended maximum amounts of vertex and index | |
5842 | data, which may be queried by calling @code{glGet} with argument | |
5843 | @code{GL_MAX_ELEMENTS_VERTICES} and @code{GL_MAX_ELEMENTS_INDICES}. If | |
3c9b6116 | 5844 | @r{@var{end}-@var{start}+1} is greater than the value of |
8925f36f AW |
5845 | @code{GL_MAX_ELEMENTS_VERTICES}, or if @var{count} is greater than the |
5846 | value of @code{GL_MAX_ELEMENTS_INDICES}, then the call may operate at | |
5847 | reduced performance. There is no requirement that all vertices in the | |
3c9b6116 | 5848 | range @r{[@var{start},@var{end}]} be referenced. However, the |
8925f36f AW |
5849 | implementation may partially process unused vertices, reducing |
5850 | performance from what could be achieved with an optimal index set. | |
5851 | ||
5852 | When @code{glDrawRangeElements} is called, it uses @var{count} | |
5853 | sequential elements from an enabled array, starting at @var{start} to | |
5854 | construct a sequence of geometric primitives. @var{mode} specifies what | |
5855 | kind of primitives are constructed, and how the array elements construct | |
5856 | these primitives. If more than one array is enabled, each is used. If | |
5857 | @code{GL_VERTEX_ARRAY} is not enabled, no geometric primitives are | |
5858 | constructed. | |
5859 | ||
5860 | Vertex attributes that are modified by @code{glDrawRangeElements} have | |
5861 | an unspecified value after @code{glDrawRangeElements} returns. For | |
5862 | example, if @code{GL_COLOR_ARRAY} is enabled, the value of the current | |
5863 | color is undefined after @code{glDrawRangeElements} executes. Attributes | |
5864 | that aren't modified maintain their previous values. | |
5865 | ||
8925f36f | 5866 | It is an error for indices to lie outside the range |
3c9b6116 AW |
5867 | @r{[@var{start},@var{end}]}, but implementations may not check for this |
5868 | situation. Such indices cause implementation-dependent behavior. | |
8925f36f AW |
5869 | |
5870 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted | |
5871 | value. | |
5872 | ||
5873 | @code{GL_INVALID_VALUE} is generated if @var{count} is negative. | |
5874 | ||
3c9b6116 | 5875 | @code{GL_INVALID_VALUE} is generated if @r{@var{end}<@var{start}}. |
8925f36f AW |
5876 | |
5877 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5878 | name is bound to an enabled array or the element array and the buffer | |
5879 | object's data store is currently mapped. | |
5880 | ||
5881 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawRangeElements} | |
5882 | is executed between the execution of @code{glBegin} and the | |
5883 | corresponding @code{glEnd}. | |
5884 | ||
bb894c9d | 5885 | @end deftypefun |
8925f36f | 5886 | |
bb894c9d | 5887 | @deftypefun void glEdgeFlagPointer stride pointer |
3c9b6116 AW |
5888 | Define an array of edge flags. |
5889 | ||
8925f36f AW |
5890 | @table @asis |
5891 | @item @var{stride} | |
5892 | Specifies the byte offset between consecutive edge flags. If | |
5893 | @var{stride} is 0, the edge flags are understood to be tightly packed in | |
5894 | the array. The initial value is 0. | |
5895 | ||
5896 | @item @var{pointer} | |
5897 | Specifies a pointer to the first edge flag in the array. The initial | |
5898 | value is 0. | |
5899 | ||
5900 | @end table | |
5901 | ||
8925f36f AW |
5902 | @code{glEdgeFlagPointer} specifies the location and data format of an |
5903 | array of boolean edge flags to use when rendering. @var{stride} | |
5904 | specifies the byte stride from one edge flag to the next, allowing | |
5905 | vertices and attributes to be packed into a single array or stored in | |
5906 | separate arrays. | |
5907 | ||
5908 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
5909 | target (see @code{glBindBuffer}) while an edge flag array is specified, | |
5910 | @var{pointer} is treated as a byte offset into the buffer object's data | |
5911 | store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING}) | |
5912 | is saved as edge flag vertex array client-side state | |
5913 | (@code{GL_EDGE_FLAG_ARRAY_BUFFER_BINDING}). | |
5914 | ||
5915 | When an edge flag array is specified, @var{stride} and @var{pointer} are | |
5916 | saved as client-side state, in addition to the current vertex array | |
5917 | buffer object binding. | |
5918 | ||
5919 | To enable and disable the edge flag array, call | |
5920 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
5921 | argument @code{GL_EDGE_FLAG_ARRAY}. If enabled, the edge flag array is | |
5922 | used when @code{glDrawArrays}, @code{glMultiDrawArrays}, | |
5923 | @code{glDrawElements}, @code{glMultiDrawElements}, | |
5924 | @code{glDrawRangeElements}, or @code{glArrayElement} is called. | |
5925 | ||
8925f36f AW |
5926 | @code{GL_INVALID_ENUM} is generated if @var{stride} is negative. |
5927 | ||
bb894c9d | 5928 | @end deftypefun |
8925f36f | 5929 | |
bb894c9d | 5930 | @deftypefun void glEdgeFlag flag |
3c9b6116 AW |
5931 | Flag edges as either boundary or nonboundary. |
5932 | ||
8925f36f AW |
5933 | @table @asis |
5934 | @item @var{flag} | |
5935 | Specifies the current edge flag value, either @code{GL_TRUE} or | |
5936 | @code{GL_FALSE}. The initial value is @code{GL_TRUE}. | |
5937 | ||
5938 | @end table | |
5939 | ||
8925f36f AW |
5940 | Each vertex of a polygon, separate triangle, or separate quadrilateral |
5941 | specified between a @code{glBegin}/@code{glEnd} pair is marked as the | |
5942 | start of either a boundary or nonboundary edge. If the current edge flag | |
5943 | is true when the vertex is specified, the vertex is marked as the start | |
5944 | of a boundary edge. Otherwise, the vertex is marked as the start of a | |
5945 | nonboundary edge. @code{glEdgeFlag} sets the edge flag bit to | |
5946 | @code{GL_TRUE} if @var{flag} is @code{GL_TRUE} and to @code{GL_FALSE} | |
5947 | otherwise. | |
5948 | ||
5949 | The vertices of connected triangles and connected quadrilaterals are | |
5950 | always marked as boundary, regardless of the value of the edge flag. | |
5951 | ||
5952 | Boundary and nonboundary edge flags on vertices are significant only if | |
5953 | @code{GL_POLYGON_MODE} is set to @code{GL_POINT} or @code{GL_LINE}. See | |
5954 | @code{glPolygonMode}. | |
5955 | ||
bb894c9d | 5956 | @end deftypefun |
8925f36f | 5957 | |
bb894c9d AW |
5958 | @deftypefun void glEnableClientState cap |
5959 | @deftypefunx void glDisableClientState cap | |
3c9b6116 AW |
5960 | Enable or disable client-side capability. |
5961 | ||
8925f36f AW |
5962 | @table @asis |
5963 | @item @var{cap} | |
5964 | Specifies the capability to enable. Symbolic constants | |
5965 | @code{GL_COLOR_ARRAY}, @code{GL_EDGE_FLAG_ARRAY}, | |
5966 | @code{GL_FOG_COORD_ARRAY}, @code{GL_INDEX_ARRAY}, | |
5967 | @code{GL_NORMAL_ARRAY}, @code{GL_SECONDARY_COLOR_ARRAY}, | |
5968 | @code{GL_TEXTURE_COORD_ARRAY}, and @code{GL_VERTEX_ARRAY} are accepted. | |
5969 | ||
5970 | @end table | |
5971 | ||
8925f36f AW |
5972 | @code{glEnableClientState} and @code{glDisableClientState} enable or |
5973 | disable individual client-side capabilities. By default, all client-side | |
5974 | capabilities are disabled. Both @code{glEnableClientState} and | |
5975 | @code{glDisableClientState} take a single argument, @var{cap}, which can | |
5976 | assume one of the following values: | |
5977 | ||
5978 | @table @asis | |
5979 | @item @code{GL_COLOR_ARRAY} | |
5980 | If enabled, the color array is enabled for writing and used during | |
5981 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
5982 | @code{glDrawElements}, | |
5983 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
5984 | @code{glMultiDrawElements} is called. See @code{glColorPointer}. | |
5985 | ||
5986 | @item @code{GL_EDGE_FLAG_ARRAY} | |
5987 | If enabled, the edge flag array is enabled for writing and used during | |
5988 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
5989 | @code{glDrawElements}, | |
5990 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
5991 | @code{glMultiDrawElements} is called. See @code{glEdgeFlagPointer}. | |
5992 | ||
5993 | @item @code{GL_FOG_COORD_ARRAY} | |
5994 | If enabled, the fog coordinate array is enabled for writing and used | |
5995 | during rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
5996 | @code{glDrawElements}, | |
5997 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
5998 | @code{glMultiDrawElements} is called. See @code{glFogCoordPointer}. | |
5999 | ||
6000 | @item @code{GL_INDEX_ARRAY} | |
6001 | If enabled, the index array is enabled for writing and used during | |
6002 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6003 | @code{glDrawElements}, | |
6004 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
6005 | @code{glMultiDrawElements} is called. See @code{glIndexPointer}. | |
6006 | ||
6007 | @item @code{GL_NORMAL_ARRAY} | |
6008 | If enabled, the normal array is enabled for writing and used during | |
6009 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6010 | @code{glDrawElements}, | |
6011 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
6012 | @code{glMultiDrawElements} is called. See @code{glNormalPointer}. | |
6013 | ||
6014 | @item @code{GL_SECONDARY_COLOR_ARRAY} | |
6015 | If enabled, the secondary color array is enabled for writing and used | |
6016 | during rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6017 | @code{glDrawElements}, | |
6018 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
6019 | @code{glMultiDrawElements} is called. See @code{glColorPointer}. | |
6020 | ||
6021 | @item @code{GL_TEXTURE_COORD_ARRAY} | |
6022 | If enabled, the texture coordinate array is enabled for writing and used | |
6023 | during rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6024 | @code{glDrawElements}, | |
6025 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
6026 | @code{glMultiDrawElements} is called. See @code{glTexCoordPointer}. | |
6027 | ||
6028 | @item @code{GL_VERTEX_ARRAY} | |
6029 | If enabled, the vertex array is enabled for writing and used during | |
6030 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6031 | @code{glDrawElements}, | |
6032 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
6033 | @code{glMultiDrawElements} is called. See @code{glVertexPointer}. | |
6034 | ||
6035 | @end table | |
6036 | ||
8925f36f AW |
6037 | @code{GL_INVALID_ENUM} is generated if @var{cap} is not an accepted |
6038 | value. | |
6039 | ||
6040 | @code{glEnableClientState} is not allowed between the execution of | |
6041 | @code{glBegin} and the corresponding @code{glEnd}, but an error may or | |
6042 | may not be generated. If no error is generated, the behavior is | |
6043 | undefined. | |
6044 | ||
bb894c9d | 6045 | @end deftypefun |
8925f36f | 6046 | |
bb894c9d AW |
6047 | @deftypefun void glEnableVertexAttribArray index |
6048 | @deftypefunx void glDisableVertexAttribArray index | |
3c9b6116 AW |
6049 | Enable or disable a generic vertex attribute array. |
6050 | ||
8925f36f AW |
6051 | @table @asis |
6052 | @item @var{index} | |
6053 | Specifies the index of the generic vertex attribute to be enabled or | |
6054 | disabled. | |
6055 | ||
6056 | @end table | |
6057 | ||
8925f36f AW |
6058 | @code{glEnableVertexAttribArray} enables the generic vertex attribute |
6059 | array specified by @var{index}. @code{glDisableVertexAttribArray} | |
6060 | disables the generic vertex attribute array specified by @var{index}. By | |
6061 | default, all client-side capabilities are disabled, including all | |
6062 | generic vertex attribute arrays. If enabled, the values in the generic | |
6063 | vertex attribute array will be accessed and used for rendering when | |
6064 | calls are made to vertex array commands such as @code{glDrawArrays}, | |
6065 | @code{glDrawElements}, @code{glDrawRangeElements}, | |
6066 | @code{glArrayElement}, @code{glMultiDrawElements}, or | |
6067 | @code{glMultiDrawArrays}. | |
6068 | ||
8925f36f AW |
6069 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or |
6070 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
6071 | ||
6072 | @code{GL_INVALID_OPERATION} is generated if either | |
6073 | @code{glEnableVertexAttribArray } or @code{glDisableVertexAttribArray } | |
6074 | is executed between the execution of @code{glBegin} and the | |
6075 | corresponding execution of @code{glEnd}. | |
6076 | ||
bb894c9d | 6077 | @end deftypefun |
8925f36f | 6078 | |
bb894c9d AW |
6079 | @deftypefun void glEnable cap |
6080 | @deftypefunx void glDisable cap | |
3c9b6116 AW |
6081 | Enable or disable server-side GL capabilities. |
6082 | ||
8925f36f AW |
6083 | @table @asis |
6084 | @item @var{cap} | |
6085 | Specifies a symbolic constant indicating a GL capability. | |
6086 | ||
6087 | @end table | |
6088 | ||
8925f36f AW |
6089 | @code{glEnable} and @code{glDisable} enable and disable various |
6090 | capabilities. Use @code{glIsEnabled} or @code{glGet} to determine the | |
6091 | current setting of any capability. The initial value for each capability | |
6092 | with the exception of @code{GL_DITHER} and @code{GL_MULTISAMPLE} is | |
6093 | @code{GL_FALSE}. The initial value for @code{GL_DITHER} and | |
6094 | @code{GL_MULTISAMPLE} is @code{GL_TRUE}. | |
6095 | ||
6096 | Both @code{glEnable} and @code{glDisable} take a single argument, | |
6097 | @var{cap}, which can assume one of the following values: | |
6098 | ||
6099 | @table @asis | |
6100 | @item @code{GL_ALPHA_TEST} | |
6101 | ||
6102 | ||
6103 | If enabled, do alpha testing. See @code{glAlphaFunc}. | |
6104 | ||
6105 | @item @code{GL_AUTO_NORMAL} | |
6106 | ||
6107 | ||
6108 | If enabled, generate normal vectors when either @code{GL_MAP2_VERTEX_3} | |
6109 | or @code{GL_MAP2_VERTEX_4} is used to generate vertices. See | |
6110 | @code{glMap2}. | |
6111 | ||
6112 | @item @code{GL_BLEND} | |
6113 | ||
6114 | ||
6115 | If enabled, blend the computed fragment color values with the values in | |
6116 | the color buffers. See @code{glBlendFunc}. | |
6117 | ||
6118 | @item @code{GL_CLIP_PLANE}@var{i} | |
6119 | ||
6120 | ||
6121 | If enabled, clip geometry against user-defined clipping plane @var{i}. | |
6122 | See @code{glClipPlane}. | |
6123 | ||
6124 | @item @code{GL_COLOR_LOGIC_OP} | |
6125 | ||
6126 | ||
6127 | If enabled, apply the currently selected logical operation to the | |
6128 | computed fragment color and color buffer values. See @code{glLogicOp}. | |
6129 | ||
6130 | @item @code{GL_COLOR_MATERIAL} | |
6131 | ||
6132 | ||
6133 | If enabled, have one or more material parameters track the current | |
6134 | color. See @code{glColorMaterial}. | |
6135 | ||
6136 | @item @code{GL_COLOR_SUM} | |
6137 | ||
6138 | ||
6139 | If enabled and no fragment shader is active, add the secondary color | |
6140 | value to the computed fragment color. See @code{glSecondaryColor}. | |
6141 | ||
6142 | @item @code{GL_COLOR_TABLE} | |
6143 | ||
6144 | ||
6145 | If enabled, perform a color table lookup on the incoming RGBA color | |
6146 | values. See @code{glColorTable}. | |
6147 | ||
6148 | @item @code{GL_CONVOLUTION_1D} | |
6149 | ||
6150 | ||
6151 | If enabled, perform a 1D convolution operation on incoming RGBA color | |
6152 | values. See @code{glConvolutionFilter1D}. | |
6153 | ||
6154 | @item @code{GL_CONVOLUTION_2D} | |
6155 | ||
6156 | ||
6157 | If enabled, perform a 2D convolution operation on incoming RGBA color | |
6158 | values. See @code{glConvolutionFilter2D}. | |
6159 | ||
6160 | @item @code{GL_CULL_FACE} | |
6161 | ||
6162 | ||
6163 | If enabled, cull polygons based on their winding in window coordinates. | |
6164 | See @code{glCullFace}. | |
6165 | ||
6166 | @item @code{GL_DEPTH_TEST} | |
6167 | ||
6168 | ||
6169 | If enabled, do depth comparisons and update the depth buffer. Note that | |
6170 | even if the depth buffer exists and the depth mask is non-zero, the | |
6171 | depth buffer is not updated if the depth test is disabled. See | |
6172 | @code{glDepthFunc} and @code{glDepthRange}. | |
6173 | ||
6174 | @item @code{GL_DITHER} | |
6175 | ||
6176 | ||
6177 | If enabled, dither color components or indices before they are written | |
6178 | to the color buffer. | |
6179 | ||
6180 | @item @code{GL_FOG} | |
6181 | ||
6182 | ||
6183 | If enabled and no fragment shader is active, blend a fog color into the | |
6184 | post-texturing color. See @code{glFog}. | |
6185 | ||
6186 | @item @code{GL_HISTOGRAM} | |
6187 | ||
6188 | ||
6189 | If enabled, histogram incoming RGBA color values. See | |
6190 | @code{glHistogram}. | |
6191 | ||
6192 | @item @code{GL_INDEX_LOGIC_OP} | |
6193 | ||
6194 | ||
6195 | If enabled, apply the currently selected logical operation to the | |
6196 | incoming index and color buffer indices. See @code{glLogicOp}. | |
6197 | ||
6198 | @item @code{GL_LIGHT}@var{i} | |
6199 | ||
6200 | ||
6201 | If enabled, include light @var{i} in the evaluation of the lighting | |
6202 | equation. See @code{glLightModel} and @code{glLight}. | |
6203 | ||
6204 | @item @code{GL_LIGHTING} | |
6205 | ||
6206 | ||
6207 | If enabled and no vertex shader is active, use the current lighting | |
6208 | parameters to compute the vertex color or index. Otherwise, simply | |
6209 | associate the current color or index with each vertex. See | |
6210 | @code{glMaterial}, @code{glLightModel}, and @code{glLight}. | |
6211 | ||
6212 | @item @code{GL_LINE_SMOOTH} | |
6213 | ||
6214 | ||
6215 | If enabled, draw lines with correct filtering. Otherwise, draw aliased | |
6216 | lines. See @code{glLineWidth}. | |
6217 | ||
6218 | @item @code{GL_LINE_STIPPLE} | |
6219 | ||
6220 | ||
6221 | If enabled, use the current line stipple pattern when drawing lines. See | |
6222 | @code{glLineStipple}. | |
6223 | ||
6224 | @item @code{GL_MAP1_COLOR_4} | |
6225 | ||
6226 | ||
6227 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6228 | @code{glEvalPoint1} generate RGBA values. See @code{glMap1}. | |
6229 | ||
6230 | @item @code{GL_MAP1_INDEX} | |
6231 | ||
6232 | ||
6233 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6234 | @code{glEvalPoint1} generate color indices. See @code{glMap1}. | |
6235 | ||
6236 | @item @code{GL_MAP1_NORMAL} | |
6237 | ||
6238 | ||
6239 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6240 | @code{glEvalPoint1} generate normals. See @code{glMap1}. | |
6241 | ||
6242 | @item @code{GL_MAP1_TEXTURE_COORD_1} | |
6243 | ||
6244 | ||
6245 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6246 | @code{glEvalPoint1} generate @var{s} texture coordinates. See | |
6247 | @code{glMap1}. | |
6248 | ||
6249 | @item @code{GL_MAP1_TEXTURE_COORD_2} | |
6250 | ||
6251 | ||
6252 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6253 | @code{glEvalPoint1} generate @var{s} and @var{t} texture coordinates. | |
6254 | See @code{glMap1}. | |
6255 | ||
6256 | @item @code{GL_MAP1_TEXTURE_COORD_3} | |
6257 | ||
6258 | ||
6259 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6260 | @code{glEvalPoint1} generate @var{s}, @var{t}, and @var{r} texture | |
6261 | coordinates. See @code{glMap1}. | |
6262 | ||
6263 | @item @code{GL_MAP1_TEXTURE_COORD_4} | |
6264 | ||
6265 | ||
6266 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6267 | @code{glEvalPoint1} generate @var{s}, @var{t}, @var{r}, and @var{q} | |
6268 | texture coordinates. See @code{glMap1}. | |
6269 | ||
6270 | @item @code{GL_MAP1_VERTEX_3} | |
6271 | ||
6272 | ||
6273 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6274 | @code{glEvalPoint1} generate @var{x}, @var{y}, and @var{z} vertex | |
6275 | coordinates. See @code{glMap1}. | |
6276 | ||
6277 | @item @code{GL_MAP1_VERTEX_4} | |
6278 | ||
6279 | ||
6280 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6281 | @code{glEvalPoint1} generate homogeneous @var{x}, @var{y}, @var{z}, and | |
6282 | @var{w} vertex coordinates. See @code{glMap1}. | |
6283 | ||
6284 | @item @code{GL_MAP2_COLOR_4} | |
6285 | ||
6286 | ||
6287 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6288 | @code{glEvalPoint2} generate RGBA values. See @code{glMap2}. | |
6289 | ||
6290 | @item @code{GL_MAP2_INDEX} | |
6291 | ||
6292 | ||
6293 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6294 | @code{glEvalPoint2} generate color indices. See @code{glMap2}. | |
6295 | ||
6296 | @item @code{GL_MAP2_NORMAL} | |
6297 | ||
6298 | ||
6299 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6300 | @code{glEvalPoint2} generate normals. See @code{glMap2}. | |
6301 | ||
6302 | @item @code{GL_MAP2_TEXTURE_COORD_1} | |
6303 | ||
6304 | ||
6305 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6306 | @code{glEvalPoint2} generate @var{s} texture coordinates. See | |
6307 | @code{glMap2}. | |
6308 | ||
6309 | @item @code{GL_MAP2_TEXTURE_COORD_2} | |
6310 | ||
6311 | ||
6312 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6313 | @code{glEvalPoint2} generate @var{s} and @var{t} texture coordinates. | |
6314 | See @code{glMap2}. | |
6315 | ||
6316 | @item @code{GL_MAP2_TEXTURE_COORD_3} | |
6317 | ||
6318 | ||
6319 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6320 | @code{glEvalPoint2} generate @var{s}, @var{t}, and @var{r} texture | |
6321 | coordinates. See @code{glMap2}. | |
6322 | ||
6323 | @item @code{GL_MAP2_TEXTURE_COORD_4} | |
6324 | ||
6325 | ||
6326 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6327 | @code{glEvalPoint2} generate @var{s}, @var{t}, @var{r}, and @var{q} | |
6328 | texture coordinates. See @code{glMap2}. | |
6329 | ||
6330 | @item @code{GL_MAP2_VERTEX_3} | |
6331 | ||
6332 | ||
6333 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6334 | @code{glEvalPoint2} generate @var{x}, @var{y}, and @var{z} vertex | |
6335 | coordinates. See @code{glMap2}. | |
6336 | ||
6337 | @item @code{GL_MAP2_VERTEX_4} | |
6338 | ||
6339 | ||
6340 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6341 | @code{glEvalPoint2} generate homogeneous @var{x}, @var{y}, @var{z}, and | |
6342 | @var{w} vertex coordinates. See @code{glMap2}. | |
6343 | ||
6344 | @item @code{GL_MINMAX} | |
6345 | ||
6346 | ||
6347 | If enabled, compute the minimum and maximum values of incoming RGBA | |
6348 | color values. See @code{glMinmax}. | |
6349 | ||
6350 | @item @code{GL_MULTISAMPLE} | |
6351 | ||
6352 | ||
6353 | If enabled, use multiple fragment samples in computing the final color | |
6354 | of a pixel. See @code{glSampleCoverage}. | |
6355 | ||
6356 | @item @code{GL_NORMALIZE} | |
6357 | ||
6358 | ||
6359 | If enabled and no vertex shader is active, normal vectors are normalized | |
6360 | to unit length after transformation and before lighting. This method is | |
6361 | generally less efficient than @code{GL_RESCALE_NORMAL}. See | |
6362 | @code{glNormal} and @code{glNormalPointer}. | |
6363 | ||
6364 | @item @code{GL_POINT_SMOOTH} | |
6365 | ||
6366 | ||
6367 | If enabled, draw points with proper filtering. Otherwise, draw aliased | |
6368 | points. See @code{glPointSize}. | |
6369 | ||
6370 | @item @code{GL_POINT_SPRITE} | |
6371 | ||
6372 | ||
6373 | If enabled, calculate texture coordinates for points based on texture | |
6374 | environment and point parameter settings. Otherwise texture coordinates | |
6375 | are constant across points. | |
6376 | ||
6377 | @item @code{GL_POLYGON_OFFSET_FILL} | |
6378 | ||
6379 | ||
6380 | If enabled, and if the polygon is rendered in @code{GL_FILL} mode, an | |
6381 | offset is added to depth values of a polygon's fragments before the | |
6382 | depth comparison is performed. See @code{glPolygonOffset}. | |
6383 | ||
6384 | @item @code{GL_POLYGON_OFFSET_LINE} | |
6385 | ||
6386 | ||
6387 | If enabled, and if the polygon is rendered in @code{GL_LINE} mode, an | |
6388 | offset is added to depth values of a polygon's fragments before the | |
6389 | depth comparison is performed. See @code{glPolygonOffset}. | |
6390 | ||
6391 | @item @code{GL_POLYGON_OFFSET_POINT} | |
6392 | ||
6393 | ||
6394 | If enabled, an offset is added to depth values of a polygon's fragments | |
6395 | before the depth comparison is performed, if the polygon is rendered in | |
6396 | @code{GL_POINT} mode. See @code{glPolygonOffset}. | |
6397 | ||
6398 | @item @code{GL_POLYGON_SMOOTH} | |
6399 | ||
6400 | ||
6401 | If enabled, draw polygons with proper filtering. Otherwise, draw aliased | |
6402 | polygons. For correct antialiased polygons, an alpha buffer is needed | |
6403 | and the polygons must be sorted front to back. | |
6404 | ||
6405 | @item @code{GL_POLYGON_STIPPLE} | |
6406 | ||
6407 | ||
6408 | If enabled, use the current polygon stipple pattern when rendering | |
6409 | polygons. See @code{glPolygonStipple}. | |
6410 | ||
6411 | @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} | |
6412 | ||
6413 | ||
6414 | If enabled, perform a color table lookup on RGBA color values after | |
6415 | color matrix transformation. See @code{glColorTable}. | |
6416 | ||
6417 | @item @code{GL_POST_CONVOLUTION_COLOR_TABLE} | |
6418 | ||
6419 | ||
6420 | If enabled, perform a color table lookup on RGBA color values after | |
6421 | convolution. See @code{glColorTable}. | |
6422 | ||
6423 | @item @code{GL_RESCALE_NORMAL} | |
6424 | ||
6425 | ||
6426 | If enabled and no vertex shader is active, normal vectors are scaled | |
6427 | after transformation and before lighting by a factor computed from the | |
6428 | modelview matrix. If the modelview matrix scales space uniformly, this | |
6429 | has the effect of restoring the transformed normal to unit length. This | |
6430 | method is generally more efficient than @code{GL_NORMALIZE}. See | |
6431 | @code{glNormal} and @code{glNormalPointer}. | |
6432 | ||
6433 | @item @code{GL_SAMPLE_ALPHA_TO_COVERAGE} | |
6434 | ||
6435 | ||
6436 | If enabled, compute a temporary coverage value where each bit is | |
6437 | determined by the alpha value at the corresponding sample location. The | |
6438 | temporary coverage value is then ANDed with the fragment coverage value. | |
6439 | ||
6440 | @item @code{GL_SAMPLE_ALPHA_TO_ONE} | |
6441 | ||
6442 | ||
6443 | If enabled, each sample alpha value is replaced by the maximum | |
6444 | representable alpha value. | |
6445 | ||
6446 | @item @code{GL_SAMPLE_COVERAGE} | |
6447 | ||
6448 | ||
6449 | If enabled, the fragment's coverage is ANDed with the temporary coverage | |
6450 | value. If @code{GL_SAMPLE_COVERAGE_INVERT} is set to @code{GL_TRUE}, | |
6451 | invert the coverage value. See @code{glSampleCoverage}. | |
6452 | ||
6453 | @item @code{GL_SEPARABLE_2D} | |
6454 | ||
6455 | ||
6456 | If enabled, perform a two-dimensional convolution operation using a | |
6457 | separable convolution filter on incoming RGBA color values. See | |
6458 | @code{glSeparableFilter2D}. | |
6459 | ||
6460 | @item @code{GL_SCISSOR_TEST} | |
6461 | ||
6462 | ||
6463 | If enabled, discard fragments that are outside the scissor rectangle. | |
6464 | See @code{glScissor}. | |
6465 | ||
6466 | @item @code{GL_STENCIL_TEST} | |
6467 | ||
6468 | ||
6469 | If enabled, do stencil testing and update the stencil buffer. See | |
6470 | @code{glStencilFunc} and @code{glStencilOp}. | |
6471 | ||
6472 | @item @code{GL_TEXTURE_1D} | |
6473 | ||
6474 | ||
6475 | If enabled and no fragment shader is active, one-dimensional texturing | |
6476 | is performed (unless two- or three-dimensional or cube-mapped texturing | |
6477 | is also enabled). See @code{glTexImage1D}. | |
6478 | ||
6479 | @item @code{GL_TEXTURE_2D} | |
6480 | ||
6481 | ||
6482 | If enabled and no fragment shader is active, two-dimensional texturing | |
6483 | is performed (unless three-dimensional or cube-mapped texturing is also | |
6484 | enabled). See @code{glTexImage2D}. | |
6485 | ||
6486 | @item @code{GL_TEXTURE_3D} | |
6487 | ||
6488 | ||
6489 | If enabled and no fragment shader is active, three-dimensional texturing | |
6490 | is performed (unless cube-mapped texturing is also enabled). See | |
6491 | @code{glTexImage3D}. | |
6492 | ||
6493 | @item @code{GL_TEXTURE_CUBE_MAP} | |
6494 | ||
6495 | ||
6496 | If enabled and no fragment shader is active, cube-mapped texturing is | |
6497 | performed. See @code{glTexImage2D}. | |
6498 | ||
6499 | @item @code{GL_TEXTURE_GEN_Q} | |
6500 | ||
6501 | ||
6502 | If enabled and no vertex shader is active, the @var{q} texture | |
6503 | coordinate is computed using the texture generation function defined | |
6504 | with @code{glTexGen}. Otherwise, the current @var{q} texture coordinate | |
6505 | is used. See @code{glTexGen}. | |
6506 | ||
6507 | @item @code{GL_TEXTURE_GEN_R} | |
6508 | ||
6509 | ||
6510 | If enabled and no vertex shader is active, the @var{r} texture | |
6511 | coordinate is computed using the texture generation function defined | |
6512 | with @code{glTexGen}. Otherwise, the current @var{r} texture coordinate | |
6513 | is used. See @code{glTexGen}. | |
6514 | ||
6515 | @item @code{GL_TEXTURE_GEN_S} | |
6516 | ||
6517 | ||
6518 | If enabled and no vertex shader is active, the @var{s} texture | |
6519 | coordinate is computed using the texture generation function defined | |
6520 | with @code{glTexGen}. Otherwise, the current @var{s} texture coordinate | |
6521 | is used. See @code{glTexGen}. | |
6522 | ||
6523 | @item @code{GL_TEXTURE_GEN_T} | |
6524 | ||
6525 | ||
6526 | If enabled and no vertex shader is active, the @var{t} texture | |
6527 | coordinate is computed using the texture generation function defined | |
6528 | with @code{glTexGen}. Otherwise, the current @var{t} texture coordinate | |
6529 | is used. See @code{glTexGen}. | |
6530 | ||
6531 | @item @code{GL_VERTEX_PROGRAM_POINT_SIZE} | |
6532 | ||
6533 | ||
6534 | If enabled and a vertex shader is active, then the derived point size is | |
6535 | taken from the (potentially clipped) shader builtin @code{gl_PointSize} | |
6536 | and clamped to the implementation-dependent point size range. | |
6537 | ||
6538 | @item @code{GL_VERTEX_PROGRAM_TWO_SIDE} | |
6539 | ||
6540 | ||
6541 | If enabled and a vertex shader is active, it specifies that the GL will | |
6542 | choose between front and back colors based on the polygon's face | |
6543 | direction of which the vertex being shaded is a part. It has no effect | |
6544 | on points or lines. | |
6545 | ||
6546 | @end table | |
6547 | ||
8925f36f AW |
6548 | @code{GL_INVALID_ENUM} is generated if @var{cap} is not one of the |
6549 | values listed previously. | |
6550 | ||
6551 | @code{GL_INVALID_OPERATION} is generated if @code{glEnable} or | |
6552 | @code{glDisable} is executed between the execution of @code{glBegin} and | |
6553 | the corresponding execution of @code{glEnd}. | |
6554 | ||
bb894c9d | 6555 | @end deftypefun |
8925f36f | 6556 | |
bb894c9d AW |
6557 | @deftypefun void glEvalCoord1d u |
6558 | @deftypefunx void glEvalCoord2d u v | |
3c9b6116 AW |
6559 | Evaluate enabled one- and two-dimensional maps. |
6560 | ||
8925f36f AW |
6561 | @table @asis |
6562 | @item @var{u} | |
3c9b6116 AW |
6563 | Specifies a value that is the domain coordinate @r{@var{u}} to the basis |
6564 | function defined in a previous @code{glMap1} or @code{glMap2} command. | |
8925f36f AW |
6565 | |
6566 | @item @var{v} | |
3c9b6116 AW |
6567 | Specifies a value that is the domain coordinate @r{@var{v}} to the basis |
6568 | function defined in a previous @code{glMap2} command. This argument is | |
6569 | not present in a @code{glEvalCoord1} command. | |
8925f36f AW |
6570 | |
6571 | @end table | |
6572 | ||
8925f36f AW |
6573 | @code{glEvalCoord1} evaluates enabled one-dimensional maps at argument |
6574 | @var{u}. @code{glEvalCoord2} does the same for two-dimensional maps | |
6575 | using two domain values, @var{u} and @var{v}. To define a map, call | |
6576 | @code{glMap1} and @code{glMap2}; to enable and disable it, call | |
6577 | @code{glEnable} and @code{glDisable}. | |
6578 | ||
6579 | When one of the @code{glEvalCoord} commands is issued, all currently | |
6580 | enabled maps of the indicated dimension are evaluated. Then, for each | |
6581 | enabled map, it is as if the corresponding GL command had been issued | |
6582 | with the computed value. That is, if @code{GL_MAP1_INDEX} or | |
6583 | @code{GL_MAP2_INDEX} is enabled, a @code{glIndex} command is simulated. | |
6584 | If @code{GL_MAP1_COLOR_4} or @code{GL_MAP2_COLOR_4} is enabled, a | |
6585 | @code{glColor} command is simulated. If @code{GL_MAP1_NORMAL} or | |
6586 | @code{GL_MAP2_NORMAL} is enabled, a normal vector is produced, and if | |
6587 | any of @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2}, | |
6588 | @code{GL_MAP1_TEXTURE_COORD_3}, @code{GL_MAP1_TEXTURE_COORD_4}, | |
6589 | @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2}, | |
6590 | @code{GL_MAP2_TEXTURE_COORD_3}, or @code{GL_MAP2_TEXTURE_COORD_4} is | |
6591 | enabled, then an appropriate @code{glTexCoord} command is simulated. | |
6592 | ||
6593 | For color, color index, normal, and texture coordinates the GL uses | |
6594 | evaluated values instead of current values for those evaluations that | |
6595 | are enabled, and current values otherwise, However, the evaluated values | |
6596 | do not update the current values. Thus, if @code{glVertex} commands are | |
6597 | interspersed with @code{glEvalCoord} commands, the color, normal, and | |
6598 | texture coordinates associated with the @code{glVertex} commands are not | |
6599 | affected by the values generated by the @code{glEvalCoord} commands, but | |
6600 | only by the most recent @code{glColor}, @code{glIndex}, @code{glNormal}, | |
6601 | and @code{glTexCoord} commands. | |
6602 | ||
6603 | No commands are issued for maps that are not enabled. If more than one | |
6604 | texture evaluation is enabled for a particular dimension (for example, | |
6605 | @code{GL_MAP2_TEXTURE_COORD_1} and @code{GL_MAP2_TEXTURE_COORD_2}), then | |
6606 | only the evaluation of the map that produces the larger number of | |
6607 | coordinates (in this case, @code{GL_MAP2_TEXTURE_COORD_2}) is carried | |
6608 | out. @code{GL_MAP1_VERTEX_4} overrides @code{GL_MAP1_VERTEX_3}, and | |
6609 | @code{GL_MAP2_VERTEX_4} overrides @code{GL_MAP2_VERTEX_3}, in the same | |
6610 | manner. If neither a three- nor a four-component vertex map is enabled | |
6611 | for the specified dimension, the @code{glEvalCoord} command is ignored. | |
6612 | ||
6613 | If you have enabled automatic normal generation, by calling | |
6614 | @code{glEnable} with argument @code{GL_AUTO_NORMAL}, @code{glEvalCoord2} | |
6615 | generates surface normals analytically, regardless of the contents or | |
6616 | enabling of the @code{GL_MAP2_NORMAL} map. Let | |
6617 | ||
3c9b6116 | 6618 | @r{@code{m}=∂@code{p},/∂@var{u},,×∂@code{p},/∂@var{v},,} |
8925f36f | 6619 | |
3c9b6116 AW |
6620 | Then the generated normal @r{@code{n}} is |
6621 | @r{@code{n}=@code{m}/∥@code{m},∥,} | |
8925f36f AW |
6622 | |
6623 | If automatic normal generation is disabled, the corresponding normal map | |
6624 | @code{GL_MAP2_NORMAL}, if enabled, is used to produce a normal. If | |
6625 | neither automatic normal generation nor a normal map is enabled, no | |
6626 | normal is generated for @code{glEvalCoord2} commands. | |
6627 | ||
bb894c9d | 6628 | @end deftypefun |
8925f36f | 6629 | |
bb894c9d AW |
6630 | @deftypefun void glEvalMesh1 mode i1 i2 |
6631 | @deftypefunx void glEvalMesh2 mode i1 i2 j1 j2 | |
3c9b6116 AW |
6632 | Compute a one- or two-dimensional grid of points or lines. |
6633 | ||
8925f36f AW |
6634 | @table @asis |
6635 | @item @var{mode} | |
6636 | In @code{glEvalMesh1}, specifies whether to compute a one-dimensional | |
6637 | mesh of points or lines. Symbolic constants @code{GL_POINT} and | |
6638 | @code{GL_LINE} are accepted. | |
6639 | ||
6640 | @item @var{i1} | |
6641 | @itemx @var{i2} | |
6642 | Specify the first and last integer values for grid domain variable | |
3c9b6116 | 6643 | @r{@var{i}}. |
8925f36f AW |
6644 | |
6645 | @end table | |
6646 | ||
8925f36f AW |
6647 | @code{glMapGrid} and @code{glEvalMesh} are used in tandem to efficiently |
6648 | generate and evaluate a series of evenly-spaced map domain values. | |
6649 | @code{glEvalMesh} steps through the integer domain of a one- or | |
6650 | two-dimensional grid, whose range is the domain of the evaluation maps | |
6651 | specified by @code{glMap1} and @code{glMap2}. @var{mode} determines | |
6652 | whether the resulting vertices are connected as points, lines, or filled | |
6653 | polygons. | |
6654 | ||
6655 | In the one-dimensional case, @code{glEvalMesh1}, the mesh is generated | |
6656 | as if the following code fragment were executed: | |
6657 | ||
6658 | where | |
6659 | ||
6660 | @example | |
6661 | ||
6662 | glBegin( @var{type} ); | |
6663 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) | |
3c9b6116 | 6664 | glEvalCoord1( @r{i·Δ@var{u}+@var{u}_1} ); |
8925f36f AW |
6665 | glEnd(); |
6666 | @end example | |
6667 | ||
3c9b6116 | 6668 | @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}} |
8925f36f | 6669 | |
3c9b6116 AW |
6670 | and @r{@var{n}}, @r{@var{u}_1}, and @r{@var{u}_2} are the arguments to |
6671 | the most recent @code{glMapGrid1} command. @var{type} is | |
8925f36f AW |
6672 | @code{GL_POINTS} if @var{mode} is @code{GL_POINT}, or @code{GL_LINES} if |
6673 | @var{mode} is @code{GL_LINE}. | |
6674 | ||
3c9b6116 AW |
6675 | The one absolute numeric requirement is that if @r{@var{i}=@var{n}}, |
6676 | then the value computed from @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly | |
6677 | @r{@var{u}_2}. | |
8925f36f AW |
6678 | |
6679 | In the two-dimensional case, @code{glEvalMesh2}, let .cp | |
3c9b6116 | 6680 | @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}} |
8925f36f | 6681 | |
3c9b6116 | 6682 | @r{Δ@var{v}=(@var{v}_2-@var{v}_1,)/@var{m}} |
8925f36f | 6683 | |
3c9b6116 AW |
6684 | where @r{@var{n}}, @r{@var{u}_1}, @r{@var{u}_2}, @r{@var{m}}, |
6685 | @r{@var{v}_1}, and @r{@var{v}_2} are the arguments to the most recent | |
6686 | @code{glMapGrid2} command. Then, if @var{mode} is @code{GL_FILL}, the | |
6687 | @code{glEvalMesh2} command is equivalent to: | |
8925f36f AW |
6688 | |
6689 | ||
6690 | ||
6691 | @example | |
6692 | ||
6693 | for ( j = @var{j1}; j < @var{j2}; j += 1 ) @{ | |
6694 | glBegin( GL_QUAD_STRIP ); | |
6695 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) @{ | |
3c9b6116 AW |
6696 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
6697 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,(j+1,)·Δ@var{v}+@var{v}_1} ); | |
8925f36f AW |
6698 | @} |
6699 | glEnd(); | |
6700 | @} | |
6701 | @end example | |
6702 | ||
6703 | If @var{mode} is @code{GL_LINE}, then a call to @code{glEvalMesh2} is | |
6704 | equivalent to: | |
6705 | ||
6706 | ||
6707 | ||
6708 | @example | |
6709 | ||
6710 | for ( j = @var{j1}; j <= @var{j2}; j += 1 ) @{ | |
6711 | glBegin( GL_LINE_STRIP ); | |
6712 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) | |
3c9b6116 | 6713 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
8925f36f AW |
6714 | glEnd(); |
6715 | @} | |
6716 | ||
6717 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) @{ | |
6718 | glBegin( GL_LINE_STRIP ); | |
6719 | for ( j = @var{j1}; j <= @var{j1}; j += 1 ) | |
3c9b6116 | 6720 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
8925f36f AW |
6721 | glEnd(); |
6722 | @} | |
6723 | @end example | |
6724 | ||
6725 | And finally, if @var{mode} is @code{GL_POINT}, then a call to | |
6726 | @code{glEvalMesh2} is equivalent to: | |
6727 | ||
6728 | ||
6729 | ||
6730 | @example | |
6731 | ||
6732 | glBegin( GL_POINTS ); | |
6733 | for ( j = @var{j1}; j <= @var{j2}; j += 1 ) | |
6734 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) | |
3c9b6116 | 6735 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
8925f36f AW |
6736 | glEnd(); |
6737 | @end example | |
6738 | ||
6739 | In all three cases, the only absolute numeric requirements are that if | |
3c9b6116 AW |
6740 | @r{@var{i}=@var{n}}, then the value computed from |
6741 | @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}, and if | |
6742 | @r{@var{j}=@var{m}}, then the value computed from | |
6743 | @r{@var{j}·Δ@var{v}+@var{v}_1} is exactly @r{@var{v}_2}. | |
8925f36f | 6744 | |
8925f36f AW |
6745 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
6746 | value. | |
6747 | ||
6748 | @code{GL_INVALID_OPERATION} is generated if @code{glEvalMesh} is | |
6749 | executed between the execution of @code{glBegin} and the corresponding | |
6750 | execution of @code{glEnd}. | |
6751 | ||
bb894c9d | 6752 | @end deftypefun |
8925f36f | 6753 | |
bb894c9d AW |
6754 | @deftypefun void glEvalPoint1 i |
6755 | @deftypefunx void glEvalPoint2 i j | |
3c9b6116 AW |
6756 | Generate and evaluate a single point in a mesh. |
6757 | ||
8925f36f AW |
6758 | @table @asis |
6759 | @item @var{i} | |
3c9b6116 | 6760 | Specifies the integer value for grid domain variable @r{@var{i}}. |
8925f36f AW |
6761 | |
6762 | @item @var{j} | |
3c9b6116 | 6763 | Specifies the integer value for grid domain variable @r{@var{j}} |
8925f36f AW |
6764 | (@code{glEvalPoint2} only). |
6765 | ||
6766 | @end table | |
6767 | ||
8925f36f AW |
6768 | @code{glMapGrid} and @code{glEvalMesh} are used in tandem to efficiently |
6769 | generate and evaluate a series of evenly spaced map domain values. | |
6770 | @code{glEvalPoint} can be used to evaluate a single grid point in the | |
6771 | same gridspace that is traversed by @code{glEvalMesh}. Calling | |
6772 | @code{glEvalPoint1} is equivalent to calling where | |
3c9b6116 | 6773 | @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}} |
8925f36f AW |
6774 | |
6775 | @example | |
6776 | ||
3c9b6116 | 6777 | glEvalCoord1( @r{i·Δ@var{u}+@var{u}_1} ); |
8925f36f AW |
6778 | @end example |
6779 | ||
3c9b6116 AW |
6780 | and @r{@var{n}}, @r{@var{u}_1}, and @r{@var{u}_2} are the arguments to |
6781 | the most recent @code{glMapGrid1} command. The one absolute numeric | |
6782 | requirement is that if @r{@var{i}=@var{n}}, then the value computed from | |
6783 | @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}. | |
8925f36f AW |
6784 | |
6785 | In the two-dimensional case, @code{glEvalPoint2}, let | |
6786 | ||
3c9b6116 | 6787 | @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}@r{Δ@var{v}=(@var{v}_2-@var{v}_1,)/@var{m}} |
8925f36f | 6788 | |
3c9b6116 AW |
6789 | where @r{@var{n}}, @r{@var{u}_1}, @r{@var{u}_2}, @r{@var{m}}, |
6790 | @r{@var{v}_1}, and @r{@var{v}_2} are the arguments to the most recent | |
6791 | @code{glMapGrid2} command. Then the @code{glEvalPoint2} command is | |
6792 | equivalent to calling The only absolute numeric requirements are that if | |
6793 | @r{@var{i}=@var{n}}, then the value computed from | |
6794 | @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}, and if | |
6795 | @r{@var{j}=@var{m}}, then the value computed from | |
6796 | @r{@var{j}·Δ@var{v}+@var{v}_1} is exactly @r{@var{v}_2}. | |
8925f36f AW |
6797 | |
6798 | @example | |
6799 | ||
3c9b6116 | 6800 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
8925f36f AW |
6801 | @end example |
6802 | ||
bb894c9d | 6803 | @end deftypefun |
8925f36f | 6804 | |
bb894c9d | 6805 | @deftypefun void glFeedbackBuffer size type buffer |
3c9b6116 AW |
6806 | Controls feedback mode. |
6807 | ||
8925f36f AW |
6808 | @table @asis |
6809 | @item @var{size} | |
6810 | Specifies the maximum number of values that can be written into | |
6811 | @var{buffer}. | |
6812 | ||
6813 | @item @var{type} | |
6814 | Specifies a symbolic constant that describes the information that will | |
6815 | be returned for each vertex. @code{GL_2D}, @code{GL_3D}, | |
6816 | @code{GL_3D_COLOR}, @code{GL_3D_COLOR_TEXTURE}, and | |
6817 | @code{GL_4D_COLOR_TEXTURE} are accepted. | |
6818 | ||
6819 | @item @var{buffer} | |
6820 | Returns the feedback data. | |
6821 | ||
6822 | @end table | |
6823 | ||
8925f36f AW |
6824 | The @code{glFeedbackBuffer} function controls feedback. Feedback, like |
6825 | selection, is a GL mode. The mode is selected by calling | |
6826 | @code{glRenderMode} with @code{GL_FEEDBACK}. When the GL is in feedback | |
6827 | mode, no pixels are produced by rasterization. Instead, information | |
6828 | about primitives that would have been rasterized is fed back to the | |
6829 | application using the GL. | |
6830 | ||
6831 | @code{glFeedbackBuffer} has three arguments: @var{buffer} is a pointer | |
6832 | to an array of floating-point values into which feedback information is | |
6833 | placed. @var{size} indicates the size of the array. @var{type} is a | |
6834 | symbolic constant describing the information that is fed back for each | |
6835 | vertex. @code{glFeedbackBuffer} must be issued before feedback mode is | |
6836 | enabled (by calling @code{glRenderMode} with argument | |
6837 | @code{GL_FEEDBACK}). Setting @code{GL_FEEDBACK} without establishing the | |
6838 | feedback buffer, or calling @code{glFeedbackBuffer} while the GL is in | |
6839 | feedback mode, is an error. | |
6840 | ||
6841 | When @code{glRenderMode} is called while in feedback mode, it returns | |
6842 | the number of entries placed in the feedback array and resets the | |
6843 | feedback array pointer to the base of the feedback buffer. The returned | |
6844 | value never exceeds @var{size}. If the feedback data required more room | |
6845 | than was available in @var{buffer}, @code{glRenderMode} returns a | |
6846 | negative value. To take the GL out of feedback mode, call | |
6847 | @code{glRenderMode} with a parameter value other than | |
6848 | @code{GL_FEEDBACK}. | |
6849 | ||
6850 | While in feedback mode, each primitive, bitmap, or pixel rectangle that | |
6851 | would be rasterized generates a block of values that are copied into the | |
6852 | feedback array. If doing so would cause the number of entries to exceed | |
6853 | the maximum, the block is partially written so as to fill the array (if | |
6854 | there is any room left at all), and an overflow flag is set. Each block | |
6855 | begins with a code indicating the primitive type, followed by values | |
6856 | that describe the primitive's vertices and associated data. Entries are | |
6857 | also written for bitmaps and pixel rectangles. Feedback occurs after | |
6858 | polygon culling and @code{glPolygonMode} interpretation of polygons has | |
6859 | taken place, so polygons that are culled are not returned in the | |
6860 | feedback buffer. It can also occur after polygons with more than three | |
6861 | edges are broken up into triangles, if the GL implementation renders | |
6862 | polygons by performing this decomposition. | |
6863 | ||
6864 | The @code{glPassThrough} command can be used to insert a marker into the | |
6865 | feedback buffer. See @code{glPassThrough}. | |
6866 | ||
6867 | Following is the grammar for the blocks of values written into the | |
6868 | feedback buffer. Each primitive is indicated with a unique identifying | |
6869 | value followed by some number of vertices. Polygon entries include an | |
6870 | integer value indicating how many vertices follow. A vertex is fed back | |
6871 | as some number of floating-point values, as determined by @var{type}. | |
6872 | Colors are fed back as four values in RGBA mode and one value in color | |
6873 | index mode. | |
6874 | ||
3c9b6116 AW |
6875 | feedbackList @r{←} feedbackItem feedbackList | feedbackItem feedbackItem |
6876 | @r{←} point | lineSegment | polygon | bitmap | pixelRectangle | passThru | |
6877 | point @r{←}@code{GL_POINT_TOKEN} vertex lineSegment | |
6878 | @r{←}@code{GL_LINE_TOKEN} vertex vertex | @code{GL_LINE_RESET_TOKEN} | |
6879 | vertex vertex polygon @r{←}@code{GL_POLYGON_TOKEN} n polySpec polySpec | |
6880 | @r{←} polySpec vertex | vertex vertex vertex bitmap | |
6881 | @r{←}@code{GL_BITMAP_TOKEN} vertex pixelRectangle | |
6882 | @r{←}@code{GL_DRAW_PIXEL_TOKEN} vertex | @code{GL_COPY_PIXEL_TOKEN} | |
6883 | vertex passThru @r{←}@code{GL_PASS_THROUGH_TOKEN} value vertex @r{←} 2d | |
6884 | | 3d | 3dColor | 3dColorTexture | 4dColorTexture 2d @r{←} value value 3d | |
6885 | @r{←} value value value 3dColor @r{←} value value value color | |
6886 | 3dColorTexture @r{←} value value value color tex 4dColorTexture @r{←} | |
6887 | value value value value color tex color @r{←} rgba | index rgba @r{←} | |
6888 | value value value value index @r{←} value tex @r{←} value value value | |
6889 | value | |
8925f36f AW |
6890 | |
6891 | @var{value} is a floating-point number, and @var{n} is a floating-point | |
6892 | integer giving the number of vertices in the polygon. | |
6893 | @code{GL_POINT_TOKEN}, @code{GL_LINE_TOKEN}, @code{GL_LINE_RESET_TOKEN}, | |
6894 | @code{GL_POLYGON_TOKEN}, @code{GL_BITMAP_TOKEN}, | |
6895 | @code{GL_DRAW_PIXEL_TOKEN}, @code{GL_COPY_PIXEL_TOKEN} and | |
6896 | @code{GL_PASS_THROUGH_TOKEN} are symbolic floating-point constants. | |
6897 | @code{GL_LINE_RESET_TOKEN} is returned whenever the line stipple pattern | |
6898 | is reset. The data returned as a vertex depends on the feedback | |
6899 | @var{type}. | |
6900 | ||
6901 | The following table gives the correspondence between @var{type} and the | |
6902 | number of values per vertex. @var{k} is 1 in color index mode and 4 in | |
6903 | RGBA mode. | |
6904 | ||
6905 | ||
6906 | ||
6907 | @table @asis | |
6908 | @item @strong{Type} | |
6909 | @strong{Coordinates}, @strong{Color}, @strong{Texture}, @strong{Total | |
6910 | Number of Values} | |
6911 | ||
6912 | @item @code{GL_2D} | |
6913 | @var{x}, @var{y}, , , 2 | |
6914 | ||
6915 | @item @code{GL_3D} | |
6916 | @var{x}, @var{y}, @var{z}, , , 3 | |
6917 | ||
6918 | @item @code{GL_3D_COLOR} | |
3c9b6116 | 6919 | @var{x}, @var{y}, @var{z}, @r{@var{k}}, , @r{3+@var{k}} |
8925f36f AW |
6920 | |
6921 | @item @code{GL_3D_COLOR_TEXTURE} | |
3c9b6116 | 6922 | @var{x}, @var{y}, @var{z}, @r{@var{k}}, 4 , @r{7+@var{k}} |
8925f36f AW |
6923 | |
6924 | @item @code{GL_4D_COLOR_TEXTURE} | |
3c9b6116 | 6925 | @var{x}, @var{y}, @var{z}, @var{w}, @r{@var{k}}, 4 , @r{8+@var{k}} |
8925f36f AW |
6926 | |
6927 | @end table | |
6928 | ||
6929 | Feedback vertex coordinates are in window coordinates, except @var{w}, | |
6930 | which is in clip coordinates. Feedback colors are lighted, if lighting | |
6931 | is enabled. Feedback texture coordinates are generated, if texture | |
6932 | coordinate generation is enabled. They are always transformed by the | |
6933 | texture matrix. | |
6934 | ||
8925f36f AW |
6935 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted |
6936 | value. | |
6937 | ||
6938 | @code{GL_INVALID_VALUE} is generated if @var{size} is negative. | |
6939 | ||
6940 | @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is | |
6941 | called while the render mode is @code{GL_FEEDBACK}, or if | |
6942 | @code{glRenderMode} is called with argument @code{GL_FEEDBACK} before | |
6943 | @code{glFeedbackBuffer} is called at least once. | |
6944 | ||
6945 | @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is | |
6946 | executed between the execution of @code{glBegin} and the corresponding | |
6947 | execution of @code{glEnd}. | |
6948 | ||
bb894c9d | 6949 | @end deftypefun |
8925f36f | 6950 | |
bb894c9d | 6951 | @deftypefun void glFinish |
3c9b6116 AW |
6952 | Block until all GL execution is complete. |
6953 | ||
8925f36f AW |
6954 | @code{glFinish} does not return until the effects of all previously |
6955 | called GL commands are complete. Such effects include all changes to GL | |
6956 | state, all changes to connection state, and all changes to the frame | |
6957 | buffer contents. | |
6958 | ||
8925f36f AW |
6959 | @code{GL_INVALID_OPERATION} is generated if @code{glFinish} is executed |
6960 | between the execution of @code{glBegin} and the corresponding execution | |
6961 | of @code{glEnd}. | |
6962 | ||
bb894c9d | 6963 | @end deftypefun |
8925f36f | 6964 | |
bb894c9d | 6965 | @deftypefun void glFlush |
3c9b6116 AW |
6966 | Force execution of GL commands in finite time. |
6967 | ||
8925f36f AW |
6968 | Different GL implementations buffer commands in several different |
6969 | locations, including network buffers and the graphics accelerator | |
6970 | itself. @code{glFlush} empties all of these buffers, causing all issued | |
6971 | commands to be executed as quickly as they are accepted by the actual | |
6972 | rendering engine. Though this execution may not be completed in any | |
6973 | particular time period, it does complete in finite time. | |
6974 | ||
6975 | Because any GL program might be executed over a network, or on an | |
6976 | accelerator that buffers commands, all programs should call | |
6977 | @code{glFlush} whenever they count on having all of their previously | |
6978 | issued commands completed. For example, call @code{glFlush} before | |
6979 | waiting for user input that depends on the generated image. | |
6980 | ||
8925f36f AW |
6981 | @code{GL_INVALID_OPERATION} is generated if @code{glFlush} is executed |
6982 | between the execution of @code{glBegin} and the corresponding execution | |
6983 | of @code{glEnd}. | |
6984 | ||
bb894c9d | 6985 | @end deftypefun |
8925f36f | 6986 | |
bb894c9d | 6987 | @deftypefun void glFogCoordPointer type stride pointer |
3c9b6116 AW |
6988 | Define an array of fog coordinates. |
6989 | ||
8925f36f AW |
6990 | @table @asis |
6991 | @item @var{type} | |
6992 | Specifies the data type of each fog coordinate. Symbolic constants | |
6993 | @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is | |
6994 | @code{GL_FLOAT}. | |
6995 | ||
6996 | @item @var{stride} | |
6997 | Specifies the byte offset between consecutive fog coordinates. If | |
6998 | @var{stride} is 0, the array elements are understood to be tightly | |
6999 | packed. The initial value is 0. | |
7000 | ||
7001 | @item @var{pointer} | |
7002 | Specifies a pointer to the first coordinate of the first fog coordinate | |
7003 | in the array. The initial value is 0. | |
7004 | ||
7005 | @end table | |
7006 | ||
8925f36f AW |
7007 | @code{glFogCoordPointer} specifies the location and data format of an |
7008 | array of fog coordinates to use when rendering. @var{type} specifies the | |
7009 | data type of each fog coordinate, and @var{stride} specifies the byte | |
7010 | stride from one fog coordinate to the next, allowing vertices and | |
7011 | attributes to be packed into a single array or stored in separate | |
7012 | arrays. | |
7013 | ||
7014 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
7015 | target (see @code{glBindBuffer}) while a fog coordinate array is | |
7016 | specified, @var{pointer} is treated as a byte offset into the buffer | |
7017 | object's data store. Also, the buffer object binding | |
7018 | (@code{GL_ARRAY_BUFFER_BINDING}) is saved as fog coordinate vertex array | |
7019 | client-side state (@code{GL_FOG_COORD_ARRAY_BUFFER_BINDING}). | |
7020 | ||
7021 | When a fog coordinate array is specified, @var{type}, @var{stride}, and | |
7022 | @var{pointer} are saved as client-side state, in addition to the current | |
7023 | vertex array buffer object binding. | |
7024 | ||
7025 | To enable and disable the fog coordinate array, call | |
7026 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
7027 | argument @code{GL_FOG_COORD_ARRAY}. If enabled, the fog coordinate array | |
7028 | is used when @code{glDrawArrays}, @code{glMultiDrawArrays}, | |
7029 | @code{glDrawElements}, @code{glMultiDrawElements}, | |
7030 | @code{glDrawRangeElements}, or @code{glArrayElement} is called. | |
7031 | ||
8925f36f AW |
7032 | @code{GL_INVALID_ENUM} is generated if @var{type} is not either |
7033 | @code{GL_FLOAT} or @code{GL_DOUBLE}. | |
7034 | ||
7035 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
7036 | ||
bb894c9d | 7037 | @end deftypefun |
8925f36f | 7038 | |
bb894c9d | 7039 | @deftypefun void glFogCoordd coord |
3c9b6116 AW |
7040 | Set the current fog coordinates. |
7041 | ||
8925f36f AW |
7042 | @table @asis |
7043 | @item @var{coord} | |
7044 | Specify the fog distance. | |
7045 | ||
7046 | @end table | |
7047 | ||
8925f36f AW |
7048 | @code{glFogCoord} specifies the fog coordinate that is associated with |
7049 | each vertex and the current raster position. The value specified is | |
7050 | interpolated and used in computing the fog color (see @code{glFog}). | |
7051 | ||
bb894c9d | 7052 | @end deftypefun |
8925f36f | 7053 | |
bb894c9d AW |
7054 | @deftypefun void glFogf pname param |
7055 | @deftypefunx void glFogi pname param | |
3c9b6116 AW |
7056 | Specify fog parameters. |
7057 | ||
8925f36f AW |
7058 | @table @asis |
7059 | @item @var{pname} | |
7060 | Specifies a single-valued fog parameter. @code{GL_FOG_MODE}, | |
7061 | @code{GL_FOG_DENSITY}, @code{GL_FOG_START}, @code{GL_FOG_END}, | |
7062 | @code{GL_FOG_INDEX}, and @code{GL_FOG_COORD_SRC} are accepted. | |
7063 | ||
7064 | @item @var{param} | |
7065 | Specifies the value that @var{pname} will be set to. | |
7066 | ||
7067 | @end table | |
7068 | ||
8925f36f AW |
7069 | Fog is initially disabled. While enabled, fog affects rasterized |
7070 | geometry, bitmaps, and pixel blocks, but not buffer clear operations. To | |
7071 | enable and disable fog, call @code{glEnable} and @code{glDisable} with | |
7072 | argument @code{GL_FOG}. | |
7073 | ||
7074 | @code{glFog} assigns the value or values in @var{params} to the fog | |
7075 | parameter specified by @var{pname}. The following values are accepted | |
7076 | for @var{pname}: | |
7077 | ||
7078 | @table @asis | |
7079 | @item @code{GL_FOG_MODE} | |
7080 | @var{params} is a single integer or floating-point value that specifies | |
3c9b6116 | 7081 | the equation to be used to compute the fog blend factor, @r{@var{f}}. |
8925f36f AW |
7082 | Three symbolic constants are accepted: @code{GL_LINEAR}, @code{GL_EXP}, |
7083 | and @code{GL_EXP2}. The equations corresponding to these symbolic | |
7084 | constants are defined below. The initial fog mode is @code{GL_EXP}. | |
7085 | ||
7086 | @item @code{GL_FOG_DENSITY} | |
7087 | @var{params} is a single integer or floating-point value that specifies | |
3c9b6116 | 7088 | @r{@var{density}}, the fog density used in both exponential fog |
8925f36f AW |
7089 | equations. Only nonnegative densities are accepted. The initial fog |
7090 | density is 1. | |
7091 | ||
7092 | @item @code{GL_FOG_START} | |
7093 | @var{params} is a single integer or floating-point value that specifies | |
3c9b6116 AW |
7094 | @r{@var{start}}, the near distance used in the linear fog equation. The |
7095 | initial near distance is 0. | |
8925f36f AW |
7096 | |
7097 | @item @code{GL_FOG_END} | |
7098 | @var{params} is a single integer or floating-point value that specifies | |
3c9b6116 | 7099 | @r{@var{end}}, the far distance used in the linear fog equation. The |
8925f36f AW |
7100 | initial far distance is 1. |
7101 | ||
7102 | @item @code{GL_FOG_INDEX} | |
7103 | @var{params} is a single integer or floating-point value that specifies | |
3c9b6116 | 7104 | @r{@var{i}_@var{f}}, the fog color index. The initial fog index is 0. |
8925f36f AW |
7105 | |
7106 | @item @code{GL_FOG_COLOR} | |
7107 | @var{params} contains four integer or floating-point values that specify | |
3c9b6116 AW |
7108 | @r{@var{C}_@var{f}}, the fog color. Integer values are mapped linearly |
7109 | such that the most positive representable value maps to 1.0, and the | |
7110 | most negative representable value maps to @r{-1.0}. Floating-point | |
7111 | values are mapped directly. After conversion, all color components are | |
7112 | clamped to the range @r{[0,1]}. The initial fog color is (0, 0, 0, 0). | |
8925f36f AW |
7113 | |
7114 | @item @code{GL_FOG_COORD_SRC} | |
7115 | @var{params} contains either of the following symbolic constants: | |
7116 | @code{GL_FOG_COORD} or @code{GL_FRAGMENT_DEPTH}. @code{GL_FOG_COORD} | |
7117 | specifies that the current fog coordinate should be used as distance | |
7118 | value in the fog color computation. @code{GL_FRAGMENT_DEPTH} specifies | |
7119 | that the current fragment depth should be used as distance value in the | |
7120 | fog computation. | |
7121 | ||
7122 | @end table | |
7123 | ||
7124 | Fog blends a fog color with each rasterized pixel fragment's | |
3c9b6116 AW |
7125 | post-texturing color using a blending factor @r{@var{f}}. Factor |
7126 | @r{@var{f}} is computed in one of three ways, depending on the fog mode. | |
7127 | Let @r{@var{c}} be either the distance in eye coordinate from the origin | |
7128 | (in the case that the @code{GL_FOG_COORD_SRC} is | |
8925f36f AW |
7129 | @code{GL_FRAGMENT_DEPTH}) or the current fog coordinate (in the case |
7130 | that @code{GL_FOG_COORD_SRC} is @code{GL_FOG_COORD}). The equation for | |
7131 | @code{GL_LINEAR} fog is | |
3c9b6116 | 7132 | @r{@var{f}=@var{end}-@var{c},/@var{end}-@var{start},} |
8925f36f AW |
7133 | |
7134 | The equation for @code{GL_EXP} fog is | |
3c9b6116 | 7135 | @r{@var{f}=@var{e}^-(@var{density}·@var{c},),} |
8925f36f AW |
7136 | |
7137 | The equation for @code{GL_EXP2} fog is | |
3c9b6116 | 7138 | @r{@var{f}=@var{e}^-(@var{density}·@var{c},),^2} |
8925f36f | 7139 | |
3c9b6116 AW |
7140 | Regardless of the fog mode, @r{@var{f}} is clamped to the range |
7141 | @r{[0,1]} after it is computed. Then, if the GL is in RGBA color mode, | |
7142 | the fragment's red, green, and blue colors, represented by | |
7143 | @r{@var{C}_@var{r}}, are replaced by | |
8925f36f | 7144 | |
3c9b6116 | 7145 | @r{@var{C}_@var{r},^″=@var{f}×@var{C}_@var{r}+(1-@var{f},)×@var{C}_@var{f}} |
8925f36f AW |
7146 | |
7147 | Fog does not affect a fragment's alpha component. | |
7148 | ||
3c9b6116 AW |
7149 | In color index mode, the fragment's color index @r{@var{i}_@var{r}} is |
7150 | replaced by | |
8925f36f | 7151 | |
3c9b6116 | 7152 | @r{@var{i}_@var{r},^″=@var{i}_@var{r}+(1-@var{f},)×@var{i}_@var{f}} |
8925f36f AW |
7153 | |
7154 | ||
7155 | ||
8925f36f AW |
7156 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted |
7157 | value, or if @var{pname} is @code{GL_FOG_MODE} and @var{params} is not | |
7158 | an accepted value. | |
7159 | ||
7160 | @code{GL_INVALID_VALUE} is generated if @var{pname} is | |
7161 | @code{GL_FOG_DENSITY} and @var{params} is negative. | |
7162 | ||
7163 | @code{GL_INVALID_OPERATION} is generated if @code{glFog} is executed | |
7164 | between the execution of @code{glBegin} and the corresponding execution | |
7165 | of @code{glEnd}. | |
7166 | ||
bb894c9d | 7167 | @end deftypefun |
8925f36f | 7168 | |
bb894c9d | 7169 | @deftypefun void glFrontFace mode |
3c9b6116 AW |
7170 | Define front- and back-facing polygons. |
7171 | ||
8925f36f AW |
7172 | @table @asis |
7173 | @item @var{mode} | |
7174 | Specifies the orientation of front-facing polygons. @code{GL_CW} and | |
7175 | @code{GL_CCW} are accepted. The initial value is @code{GL_CCW}. | |
7176 | ||
7177 | @end table | |
7178 | ||
8925f36f AW |
7179 | In a scene composed entirely of opaque closed surfaces, back-facing |
7180 | polygons are never visible. Eliminating these invisible polygons has the | |
7181 | obvious benefit of speeding up the rendering of the image. To enable and | |
7182 | disable elimination of back-facing polygons, call @code{glEnable} and | |
7183 | @code{glDisable} with argument @code{GL_CULL_FACE}. | |
7184 | ||
7185 | The projection of a polygon to window coordinates is said to have | |
7186 | clockwise winding if an imaginary object following the path from its | |
7187 | first vertex, its second vertex, and so on, to its last vertex, and | |
7188 | finally back to its first vertex, moves in a clockwise direction about | |
7189 | the interior of the polygon. The polygon's winding is said to be | |
7190 | counterclockwise if the imaginary object following the same path moves | |
7191 | in a counterclockwise direction about the interior of the polygon. | |
7192 | @code{glFrontFace} specifies whether polygons with clockwise winding in | |
7193 | window coordinates, or counterclockwise winding in window coordinates, | |
7194 | are taken to be front-facing. Passing @code{GL_CCW} to @var{mode} | |
7195 | selects counterclockwise polygons as front-facing; @code{GL_CW} selects | |
7196 | clockwise polygons as front-facing. By default, counterclockwise | |
7197 | polygons are taken to be front-facing. | |
7198 | ||
8925f36f AW |
7199 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
7200 | value. | |
7201 | ||
7202 | @code{GL_INVALID_OPERATION} is generated if @code{glFrontFace} is | |
7203 | executed between the execution of @code{glBegin} and the corresponding | |
7204 | execution of @code{glEnd}. | |
7205 | ||
bb894c9d | 7206 | @end deftypefun |
8925f36f | 7207 | |
bb894c9d | 7208 | @deftypefun void glFrustum left right bottom top nearVal farVal |
3c9b6116 AW |
7209 | Multiply the current matrix by a perspective matrix. |
7210 | ||
8925f36f AW |
7211 | @table @asis |
7212 | @item @var{left} | |
7213 | @itemx @var{right} | |
7214 | Specify the coordinates for the left and right vertical clipping planes. | |
7215 | ||
7216 | @item @var{bottom} | |
7217 | @itemx @var{top} | |
7218 | Specify the coordinates for the bottom and top horizontal clipping | |
7219 | planes. | |
7220 | ||
7221 | @item @var{nearVal} | |
7222 | @itemx @var{farVal} | |
7223 | Specify the distances to the near and far depth clipping planes. Both | |
7224 | distances must be positive. | |
7225 | ||
7226 | @end table | |
7227 | ||
8925f36f AW |
7228 | @code{glFrustum} describes a perspective matrix that produces a |
7229 | perspective projection. The current matrix (see @code{glMatrixMode}) is | |
7230 | multiplied by this matrix and the result replaces the current matrix, as | |
7231 | if @code{glMultMatrix} were called with the following matrix as its | |
7232 | argument: | |
7233 | ||
7234 | ||
7235 | ||
3c9b6116 | 7236 | @r{[(2@var{nearVal},/@var{right}-@var{left},, 0 @var{A} 0), (0 |
8925f36f AW |
7237 | 2@var{nearVal},/@var{top}-@var{bottom},, @var{B} 0), (0 0 @var{C} |
7238 | @var{D}), (0 0 -1 0),]} | |
7239 | ||
3c9b6116 | 7240 | @r{@var{A}=@var{right}+@var{left},/@var{right}-@var{left},} |
8925f36f | 7241 | |
3c9b6116 | 7242 | @r{@var{B}=@var{top}+@var{bottom},/@var{top}-@var{bottom},} |
8925f36f | 7243 | |
3c9b6116 | 7244 | @r{@var{C}=-@var{farVal}+@var{nearVal},/@var{farVal}-@var{nearVal},,} |
8925f36f | 7245 | |
3c9b6116 | 7246 | @r{@var{D}=-2@var{farVal}@var{nearVal},/@var{farVal}-@var{nearVal},,} |
8925f36f AW |
7247 | |
7248 | ||
7249 | ||
7250 | Typically, the matrix mode is @code{GL_PROJECTION}, and | |
3c9b6116 AW |
7251 | @r{(@var{left},@var{bottom}-@var{nearVal})} and |
7252 | @r{(@var{right},@var{top}-@var{nearVal})} specify the points on the near | |
7253 | clipping plane that are mapped to the lower left and upper right corners | |
7254 | of the window, assuming that the eye is located at (0, 0, 0). | |
7255 | @r{-@var{farVal}} specifies the location of the far clipping plane. Both | |
7256 | @var{nearVal} and @var{farVal} must be positive. | |
8925f36f AW |
7257 | |
7258 | Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the | |
7259 | current matrix stack. | |
7260 | ||
8925f36f AW |
7261 | @code{GL_INVALID_VALUE} is generated if @var{nearVal} or @var{farVal} is |
7262 | not positive, or if @var{left} = @var{right}, or @var{bottom} = | |
7263 | @var{top}, or @var{near} = @var{far}. | |
7264 | ||
7265 | @code{GL_INVALID_OPERATION} is generated if @code{glFrustum} is executed | |
7266 | between the execution of @code{glBegin} and the corresponding execution | |
7267 | of @code{glEnd}. | |
7268 | ||
bb894c9d | 7269 | @end deftypefun |
8925f36f | 7270 | |
bb894c9d | 7271 | @deftypefun void glGenBuffers n buffers |
3c9b6116 AW |
7272 | Generate buffer object names. |
7273 | ||
8925f36f AW |
7274 | @table @asis |
7275 | @item @var{n} | |
7276 | Specifies the number of buffer object names to be generated. | |
7277 | ||
7278 | @item @var{buffers} | |
7279 | Specifies an array in which the generated buffer object names are | |
7280 | stored. | |
7281 | ||
7282 | @end table | |
7283 | ||
8925f36f AW |
7284 | @code{glGenBuffers} returns @var{n} buffer object names in |
7285 | @var{buffers}. There is no guarantee that the names form a contiguous | |
7286 | set of integers; however, it is guaranteed that none of the returned | |
7287 | names was in use immediately before the call to @code{glGenBuffers}. | |
7288 | ||
7289 | Buffer object names returned by a call to @code{glGenBuffers} are not | |
7290 | returned by subsequent calls, unless they are first deleted with | |
7291 | @code{glDeleteBuffers}. | |
7292 | ||
7293 | No buffer objects are associated with the returned buffer object names | |
7294 | until they are first bound by calling @code{glBindBuffer}. | |
7295 | ||
8925f36f AW |
7296 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
7297 | ||
7298 | @code{GL_INVALID_OPERATION} is generated if @code{glGenBuffers} is | |
7299 | executed between the execution of @code{glBegin} and the corresponding | |
7300 | execution of @code{glEnd}. | |
7301 | ||
bb894c9d | 7302 | @end deftypefun |
8925f36f | 7303 | |
bb894c9d | 7304 | @deftypefun GLuint glGenLists range |
3c9b6116 AW |
7305 | Generate a contiguous set of empty display lists. |
7306 | ||
8925f36f AW |
7307 | @table @asis |
7308 | @item @var{range} | |
7309 | Specifies the number of contiguous empty display lists to be generated. | |
7310 | ||
7311 | @end table | |
7312 | ||
8925f36f AW |
7313 | @code{glGenLists} has one argument, @var{range}. It returns an integer |
7314 | @var{n} such that @var{range} contiguous empty display lists, named | |
3c9b6116 AW |
7315 | @r{@var{n}}, @r{@var{n}+1}, @r{@var{...}}, @r{@var{n}+@var{range}-1}, |
7316 | are created. If @var{range} is 0, if there is no group of @var{range} | |
7317 | contiguous names available, or if any error is generated, no display | |
7318 | lists are generated, and 0 is returned. | |
8925f36f | 7319 | |
8925f36f AW |
7320 | @code{GL_INVALID_VALUE} is generated if @var{range} is negative. |
7321 | ||
7322 | @code{GL_INVALID_OPERATION} is generated if @code{glGenLists} is | |
7323 | executed between the execution of @code{glBegin} and the corresponding | |
7324 | execution of @code{glEnd}. | |
7325 | ||
bb894c9d | 7326 | @end deftypefun |
8925f36f | 7327 | |
bb894c9d | 7328 | @deftypefun void glGenQueries n ids |
3c9b6116 AW |
7329 | Generate query object names. |
7330 | ||
8925f36f AW |
7331 | @table @asis |
7332 | @item @var{n} | |
7333 | Specifies the number of query object names to be generated. | |
7334 | ||
7335 | @item @var{ids} | |
7336 | Specifies an array in which the generated query object names are stored. | |
7337 | ||
7338 | @end table | |
7339 | ||
8925f36f AW |
7340 | @code{glGenQueries} returns @var{n} query object names in @var{ids}. |
7341 | There is no guarantee that the names form a contiguous set of integers; | |
7342 | however, it is guaranteed that none of the returned names was in use | |
7343 | immediately before the call to @code{glGenQueries}. | |
7344 | ||
7345 | Query object names returned by a call to @code{glGenQueries} are not | |
7346 | returned by subsequent calls, unless they are first deleted with | |
7347 | @code{glDeleteQueries}. | |
7348 | ||
7349 | No query objects are associated with the returned query object names | |
7350 | until they are first used by calling @code{glBeginQuery}. | |
7351 | ||
8925f36f AW |
7352 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
7353 | ||
7354 | @code{GL_INVALID_OPERATION} is generated if @code{glGenQueries} is | |
7355 | executed between the execution of @code{glBegin} and the corresponding | |
7356 | execution of @code{glEnd}. | |
7357 | ||
bb894c9d | 7358 | @end deftypefun |
8925f36f | 7359 | |
bb894c9d | 7360 | @deftypefun void glGenTextures n textures |
3c9b6116 AW |
7361 | Generate texture names. |
7362 | ||
8925f36f AW |
7363 | @table @asis |
7364 | @item @var{n} | |
7365 | Specifies the number of texture names to be generated. | |
7366 | ||
7367 | @item @var{textures} | |
7368 | Specifies an array in which the generated texture names are stored. | |
7369 | ||
7370 | @end table | |
7371 | ||
8925f36f AW |
7372 | @code{glGenTextures} returns @var{n} texture names in @var{textures}. |
7373 | There is no guarantee that the names form a contiguous set of integers; | |
7374 | however, it is guaranteed that none of the returned names was in use | |
7375 | immediately before the call to @code{glGenTextures}. | |
7376 | ||
7377 | The generated textures have no dimensionality; they assume the | |
7378 | dimensionality of the texture target to which they are first bound (see | |
7379 | @code{glBindTexture}). | |
7380 | ||
7381 | Texture names returned by a call to @code{glGenTextures} are not | |
7382 | returned by subsequent calls, unless they are first deleted with | |
7383 | @code{glDeleteTextures}. | |
7384 | ||
8925f36f AW |
7385 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
7386 | ||
7387 | @code{GL_INVALID_OPERATION} is generated if @code{glGenTextures} is | |
7388 | executed between the execution of @code{glBegin} and the corresponding | |
7389 | execution of @code{glEnd}. | |
7390 | ||
bb894c9d | 7391 | @end deftypefun |
8925f36f | 7392 | |
bb894c9d | 7393 | @deftypefun void glGetActiveAttrib program index bufSize length size type name |
3c9b6116 AW |
7394 | Returns information about an active attribute variable for the specified |
7395 | program object. | |
7396 | ||
8925f36f AW |
7397 | @table @asis |
7398 | @item @var{program} | |
7399 | Specifies the program object to be queried. | |
7400 | ||
7401 | @item @var{index} | |
7402 | Specifies the index of the attribute variable to be queried. | |
7403 | ||
7404 | @item @var{bufSize} | |
7405 | Specifies the maximum number of characters OpenGL is allowed to write in | |
7406 | the character buffer indicated by @var{name}. | |
7407 | ||
7408 | @item @var{length} | |
7409 | Returns the number of characters actually written by OpenGL in the | |
7410 | string indicated by @var{name} (excluding the null terminator) if a | |
7411 | value other than @code{NULL} is passed. | |
7412 | ||
7413 | @item @var{size} | |
7414 | Returns the size of the attribute variable. | |
7415 | ||
7416 | @item @var{type} | |
7417 | Returns the data type of the attribute variable. | |
7418 | ||
7419 | @item @var{name} | |
7420 | Returns a null terminated string containing the name of the attribute | |
7421 | variable. | |
7422 | ||
7423 | @end table | |
7424 | ||
8925f36f AW |
7425 | @code{glGetActiveAttrib} returns information about an active attribute |
7426 | variable in the program object specified by @var{program}. The number of | |
7427 | active attributes can be obtained by calling @code{glGetProgram} with | |
7428 | the value @code{GL_ACTIVE_ATTRIBUTES}. A value of 0 for @var{index} | |
7429 | selects the first active attribute variable. Permissible values for | |
7430 | @var{index} range from 0 to the number of active attribute variables | |
7431 | minus 1. | |
7432 | ||
7433 | A vertex shader may use either built-in attribute variables, | |
7434 | user-defined attribute variables, or both. Built-in attribute variables | |
7435 | have a prefix of "gl_" and reference conventional OpenGL vertex | |
7436 | attribtes (e.g., @var{gl_Vertex}, @var{gl_Normal}, etc., see the OpenGL | |
7437 | Shading Language specification for a complete list.) User-defined | |
7438 | attribute variables have arbitrary names and obtain their values through | |
7439 | numbered generic vertex attributes. An attribute variable (either | |
7440 | built-in or user-defined) is considered active if it is determined | |
7441 | during the link operation that it may be accessed during program | |
7442 | execution. Therefore, @var{program} should have previously been the | |
7443 | target of a call to @code{glLinkProgram}, but it is not necessary for it | |
7444 | to have been linked successfully. | |
7445 | ||
7446 | The size of the character buffer required to store the longest attribute | |
7447 | variable name in @var{program} can be obtained by calling | |
7448 | @code{glGetProgram} with the value | |
7449 | @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH}. This value should be used to | |
7450 | allocate a buffer of sufficient size to store the returned attribute | |
7451 | name. The size of this character buffer is passed in @var{bufSize}, and | |
7452 | a pointer to this character buffer is passed in @var{name}. | |
7453 | ||
7454 | @code{glGetActiveAttrib} returns the name of the attribute variable | |
7455 | indicated by @var{index}, storing it in the character buffer specified | |
7456 | by @var{name}. The string returned will be null terminated. The actual | |
7457 | number of characters written into this buffer is returned in | |
7458 | @var{length}, and this count does not include the null termination | |
7459 | character. If the length of the returned string is not required, a value | |
7460 | of @code{NULL} can be passed in the @var{length} argument. | |
7461 | ||
7462 | The @var{type} argument will return a pointer to the attribute | |
7463 | variable's data type. The symbolic constants @code{GL_FLOAT}, | |
7464 | @code{GL_FLOAT_VEC2}, @code{GL_FLOAT_VEC3}, @code{GL_FLOAT_VEC4}, | |
7465 | @code{GL_FLOAT_MAT2}, @code{GL_FLOAT_MAT3}, @code{GL_FLOAT_MAT4}, | |
7466 | @code{GL_FLOAT_MAT2x3}, @code{GL_FLOAT_MAT2x4}, @code{GL_FLOAT_MAT3x2}, | |
7467 | @code{GL_FLOAT_MAT3x4}, @code{GL_FLOAT_MAT4x2}, or | |
7468 | @code{GL_FLOAT_MAT4x3} may be returned. The @var{size} argument will | |
7469 | return the size of the attribute, in units of the type returned in | |
7470 | @var{type}. | |
7471 | ||
7472 | The list of active attribute variables may include both built-in | |
7473 | attribute variables (which begin with the prefix "gl_") as well as | |
7474 | user-defined attribute variable names. | |
7475 | ||
7476 | This function will return as much information as it can about the | |
7477 | specified active attribute variable. If no information is available, | |
7478 | @var{length} will be 0, and @var{name} will be an empty string. This | |
7479 | situation could occur if this function is called after a link operation | |
7480 | that failed. If an error occurs, the return values @var{length}, | |
7481 | @var{size}, @var{type}, and @var{name} will be unmodified. | |
7482 | ||
8925f36f AW |
7483 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
7484 | generated by OpenGL. | |
7485 | ||
7486 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
7487 | program object. | |
7488 | ||
7489 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or | |
7490 | equal to the number of active attribute variables in @var{program}. | |
7491 | ||
7492 | @code{GL_INVALID_OPERATION} is generated if @code{glGetActiveAttrib} is | |
7493 | executed between the execution of @code{glBegin} and the corresponding | |
7494 | execution of @code{glEnd}. | |
7495 | ||
7496 | @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0. | |
7497 | ||
bb894c9d | 7498 | @end deftypefun |
8925f36f | 7499 | |
bb894c9d | 7500 | @deftypefun void glGetActiveUniform program index bufSize length size type name |
3c9b6116 AW |
7501 | Returns information about an active uniform variable for the specified |
7502 | program object. | |
7503 | ||
8925f36f AW |
7504 | @table @asis |
7505 | @item @var{program} | |
7506 | Specifies the program object to be queried. | |
7507 | ||
7508 | @item @var{index} | |
7509 | Specifies the index of the uniform variable to be queried. | |
7510 | ||
7511 | @item @var{bufSize} | |
7512 | Specifies the maximum number of characters OpenGL is allowed to write in | |
7513 | the character buffer indicated by @var{name}. | |
7514 | ||
7515 | @item @var{length} | |
7516 | Returns the number of characters actually written by OpenGL in the | |
7517 | string indicated by @var{name} (excluding the null terminator) if a | |
7518 | value other than @code{NULL} is passed. | |
7519 | ||
7520 | @item @var{size} | |
7521 | Returns the size of the uniform variable. | |
7522 | ||
7523 | @item @var{type} | |
7524 | Returns the data type of the uniform variable. | |
7525 | ||
7526 | @item @var{name} | |
7527 | Returns a null terminated string containing the name of the uniform | |
7528 | variable. | |
7529 | ||
7530 | @end table | |
7531 | ||
8925f36f AW |
7532 | @code{glGetActiveUniform} returns information about an active uniform |
7533 | variable in the program object specified by @var{program}. The number of | |
7534 | active uniform variables can be obtained by calling @code{glGetProgram} | |
7535 | with the value @code{GL_ACTIVE_UNIFORMS}. A value of 0 for @var{index} | |
7536 | selects the first active uniform variable. Permissible values for | |
7537 | @var{index} range from 0 to the number of active uniform variables minus | |
7538 | 1. | |
7539 | ||
7540 | Shaders may use either built-in uniform variables, user-defined uniform | |
7541 | variables, or both. Built-in uniform variables have a prefix of "gl_" | |
7542 | and reference existing OpenGL state or values derived from such state | |
7543 | (e.g., @var{gl_Fog}, @var{gl_ModelViewMatrix}, etc., see the OpenGL | |
7544 | Shading Language specification for a complete list.) User-defined | |
7545 | uniform variables have arbitrary names and obtain their values from the | |
7546 | application through calls to @code{glUniform}. A uniform variable | |
7547 | (either built-in or user-defined) is considered active if it is | |
7548 | determined during the link operation that it may be accessed during | |
7549 | program execution. Therefore, @var{program} should have previously been | |
7550 | the target of a call to @code{glLinkProgram}, but it is not necessary | |
7551 | for it to have been linked successfully. | |
7552 | ||
7553 | The size of the character buffer required to store the longest uniform | |
7554 | variable name in @var{program} can be obtained by calling | |
7555 | @code{glGetProgram} with the value @code{GL_ACTIVE_UNIFORM_MAX_LENGTH}. | |
7556 | This value should be used to allocate a buffer of sufficient size to | |
7557 | store the returned uniform variable name. The size of this character | |
7558 | buffer is passed in @var{bufSize}, and a pointer to this character | |
7559 | buffer is passed in @var{name.} | |
7560 | ||
7561 | @code{glGetActiveUniform} returns the name of the uniform variable | |
7562 | indicated by @var{index}, storing it in the character buffer specified | |
7563 | by @var{name}. The string returned will be null terminated. The actual | |
7564 | number of characters written into this buffer is returned in | |
7565 | @var{length}, and this count does not include the null termination | |
7566 | character. If the length of the returned string is not required, a value | |
7567 | of @code{NULL} can be passed in the @var{length} argument. | |
7568 | ||
7569 | The @var{type} argument will return a pointer to the uniform variable's | |
7570 | data type. The symbolic constants @code{GL_FLOAT}, @code{GL_FLOAT_VEC2}, | |
7571 | @code{GL_FLOAT_VEC3}, @code{GL_FLOAT_VEC4}, @code{GL_INT}, | |
7572 | @code{GL_INT_VEC2}, @code{GL_INT_VEC3}, @code{GL_INT_VEC4}, | |
7573 | @code{GL_BOOL}, @code{GL_BOOL_VEC2}, @code{GL_BOOL_VEC3}, | |
7574 | @code{GL_BOOL_VEC4}, @code{GL_FLOAT_MAT2}, @code{GL_FLOAT_MAT3}, | |
7575 | @code{GL_FLOAT_MAT4}, @code{GL_FLOAT_MAT2x3}, @code{GL_FLOAT_MAT2x4}, | |
7576 | @code{GL_FLOAT_MAT3x2}, @code{GL_FLOAT_MAT3x4}, @code{GL_FLOAT_MAT4x2}, | |
7577 | @code{GL_FLOAT_MAT4x3}, @code{GL_SAMPLER_1D}, @code{GL_SAMPLER_2D}, | |
7578 | @code{GL_SAMPLER_3D}, @code{GL_SAMPLER_CUBE}, | |
7579 | @code{GL_SAMPLER_1D_SHADOW}, or @code{GL_SAMPLER_2D_SHADOW} may be | |
7580 | returned. | |
7581 | ||
7582 | If one or more elements of an array are active, the name of the array is | |
7583 | returned in @var{name}, the type is returned in @var{type}, and the | |
7584 | @var{size} parameter returns the highest array element index used, plus | |
7585 | one, as determined by the compiler and/or linker. Only one active | |
7586 | uniform variable will be reported for a uniform array. | |
7587 | ||
7588 | Uniform variables that are declared as structures or arrays of | |
7589 | structures will not be returned directly by this function. Instead, each | |
7590 | of these uniform variables will be reduced to its fundamental components | |
7591 | containing the "." and "[]" operators such that each of the names is | |
7592 | valid as an argument to @code{glGetUniformLocation}. Each of these | |
7593 | reduced uniform variables is counted as one active uniform variable and | |
7594 | is assigned an index. A valid name cannot be a structure, an array of | |
7595 | structures, or a subcomponent of a vector or matrix. | |
7596 | ||
7597 | The size of the uniform variable will be returned in @var{size}. Uniform | |
7598 | variables other than arrays will have a size of 1. Structures and arrays | |
7599 | of structures will be reduced as described earlier, such that each of | |
7600 | the names returned will be a data type in the earlier list. If this | |
7601 | reduction results in an array, the size returned will be as described | |
7602 | for uniform arrays; otherwise, the size returned will be 1. | |
7603 | ||
7604 | The list of active uniform variables may include both built-in uniform | |
7605 | variables (which begin with the prefix "gl_") as well as user-defined | |
7606 | uniform variable names. | |
7607 | ||
7608 | This function will return as much information as it can about the | |
7609 | specified active uniform variable. If no information is available, | |
7610 | @var{length} will be 0, and @var{name} will be an empty string. This | |
7611 | situation could occur if this function is called after a link operation | |
7612 | that failed. If an error occurs, the return values @var{length}, | |
7613 | @var{size}, @var{type}, and @var{name} will be unmodified. | |
7614 | ||
8925f36f AW |
7615 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
7616 | generated by OpenGL. | |
7617 | ||
7618 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
7619 | program object. | |
7620 | ||
7621 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or | |
7622 | equal to the number of active uniform variables in @var{program}. | |
7623 | ||
7624 | @code{GL_INVALID_OPERATION} is generated if @code{glGetActiveUniform} is | |
7625 | executed between the execution of @code{glBegin} and the corresponding | |
7626 | execution of @code{glEnd}. | |
7627 | ||
7628 | @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0. | |
7629 | ||
bb894c9d | 7630 | @end deftypefun |
8925f36f | 7631 | |
bb894c9d | 7632 | @deftypefun void glGetAttachedShaders program maxCount count shaders |
3c9b6116 AW |
7633 | Returns the handles of the shader objects attached to a program object. |
7634 | ||
8925f36f AW |
7635 | @table @asis |
7636 | @item @var{program} | |
7637 | Specifies the program object to be queried. | |
7638 | ||
7639 | @item @var{maxCount} | |
7640 | Specifies the size of the array for storing the returned object names. | |
7641 | ||
7642 | @item @var{count} | |
7643 | Returns the number of names actually returned in @var{objects}. | |
7644 | ||
7645 | @item @var{shaders} | |
7646 | Specifies an array that is used to return the names of attached shader | |
7647 | objects. | |
7648 | ||
7649 | @end table | |
7650 | ||
8925f36f AW |
7651 | @code{glGetAttachedShaders} returns the names of the shader objects |
7652 | attached to @var{program}. The names of shader objects that are attached | |
7653 | to @var{program} will be returned in @var{shaders.} The actual number of | |
7654 | shader names written into @var{shaders} is returned in @var{count.} If | |
7655 | no shader objects are attached to @var{program}, @var{count} is set to | |
7656 | 0. The maximum number of shader names that may be returned in | |
7657 | @var{shaders} is specified by @var{maxCount}. | |
7658 | ||
7659 | If the number of names actually returned is not required (for instance, | |
7660 | if it has just been obtained by calling @code{glGetProgram}), a value of | |
7661 | @code{NULL} may be passed for count. If no shader objects are attached | |
7662 | to @var{program}, a value of 0 will be returned in @var{count}. The | |
7663 | actual number of attached shaders can be obtained by calling | |
7664 | @code{glGetProgram} with the value @code{GL_ATTACHED_SHADERS}. | |
7665 | ||
8925f36f AW |
7666 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
7667 | generated by OpenGL. | |
7668 | ||
7669 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
7670 | program object. | |
7671 | ||
7672 | @code{GL_INVALID_VALUE} is generated if @var{maxCount} is less than 0. | |
7673 | ||
7674 | @code{GL_INVALID_OPERATION} is generated if @code{glGetAttachedShaders} | |
7675 | is executed between the execution of @code{glBegin} and the | |
7676 | corresponding execution of @code{glEnd}. | |
7677 | ||
bb894c9d | 7678 | @end deftypefun |
8925f36f | 7679 | |
bb894c9d | 7680 | @deftypefun GLint glGetAttribLocation program name |
3c9b6116 AW |
7681 | Returns the location of an attribute variable. |
7682 | ||
8925f36f AW |
7683 | @table @asis |
7684 | @item @var{program} | |
7685 | Specifies the program object to be queried. | |
7686 | ||
7687 | @item @var{name} | |
7688 | Points to a null terminated string containing the name of the attribute | |
7689 | variable whose location is to be queried. | |
7690 | ||
7691 | @end table | |
7692 | ||
8925f36f AW |
7693 | @code{glGetAttribLocation} queries the previously linked program object |
7694 | specified by @var{program} for the attribute variable specified by | |
7695 | @var{name} and returns the index of the generic vertex attribute that is | |
7696 | bound to that attribute variable. If @var{name} is a matrix attribute | |
7697 | variable, the index of the first column of the matrix is returned. If | |
7698 | the named attribute variable is not an active attribute in the specified | |
7699 | program object or if @var{name} starts with the reserved prefix "gl_", a | |
7700 | value of -1 is returned. | |
7701 | ||
7702 | The association between an attribute variable name and a generic | |
7703 | attribute index can be specified at any time by calling | |
7704 | @code{glBindAttribLocation}. Attribute bindings do not go into effect | |
7705 | until @code{glLinkProgram} is called. After a program object has been | |
7706 | linked successfully, the index values for attribute variables remain | |
7707 | fixed until the next link command occurs. The attribute values can only | |
7708 | be queried after a link if the link was successful. | |
7709 | @code{glGetAttribLocation} returns the binding that actually went into | |
7710 | effect the last time @code{glLinkProgram} was called for the specified | |
7711 | program object. Attribute bindings that have been specified since the | |
7712 | last link operation are not returned by @code{glGetAttribLocation}. | |
7713 | ||
8925f36f AW |
7714 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a value |
7715 | generated by OpenGL. | |
7716 | ||
7717 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
7718 | program object. | |
7719 | ||
7720 | @code{GL_INVALID_OPERATION} is generated if @var{program} has not been | |
7721 | successfully linked. | |
7722 | ||
7723 | @code{GL_INVALID_OPERATION} is generated if @code{glGetAttribLocation} | |
7724 | is executed between the execution of @code{glBegin} and the | |
7725 | corresponding execution of @code{glEnd}. | |
7726 | ||
bb894c9d | 7727 | @end deftypefun |
8925f36f | 7728 | |
bb894c9d | 7729 | @deftypefun void glGetBufferSubData target offset size data |
3c9b6116 AW |
7730 | Returns a subset of a buffer object's data store. |
7731 | ||
8925f36f AW |
7732 | @table @asis |
7733 | @item @var{target} | |
7734 | Specifies the target buffer object. The symbolic constant must be | |
7735 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
7736 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
7737 | ||
7738 | @item @var{offset} | |
7739 | Specifies the offset into the buffer object's data store from which data | |
7740 | will be returned, measured in bytes. | |
7741 | ||
7742 | @item @var{size} | |
7743 | Specifies the size in bytes of the data store region being returned. | |
7744 | ||
7745 | @item @var{data} | |
7746 | Specifies a pointer to the location where buffer object data is | |
7747 | returned. | |
7748 | ||
7749 | @end table | |
7750 | ||
8925f36f AW |
7751 | @code{glGetBufferSubData} returns some or all of the data from the |
7752 | buffer object currently bound to @var{target}. Data starting at byte | |
7753 | offset @var{offset} and extending for @var{size} bytes is copied from | |
7754 | the data store to the memory pointed to by @var{data}. An error is | |
7755 | thrown if the buffer object is currently mapped, or if @var{offset} and | |
7756 | @var{size} together define a range beyond the bounds of the buffer | |
7757 | object's data store. | |
7758 | ||
8925f36f AW |
7759 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
7760 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
7761 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
7762 | ||
7763 | @code{GL_INVALID_VALUE} is generated if @var{offset} or @var{size} is | |
7764 | negative, or if together they define a region of memory that extends | |
7765 | beyond the buffer object's allocated data store. | |
7766 | ||
7767 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
7768 | name 0 is bound to @var{target}. | |
7769 | ||
7770 | @code{GL_INVALID_OPERATION} is generated if the buffer object being | |
7771 | queried is mapped. | |
7772 | ||
7773 | @code{GL_INVALID_OPERATION} is generated if @code{glGetBufferSubData} is | |
7774 | executed between the execution of @code{glBegin} and the corresponding | |
7775 | execution of @code{glEnd}. | |
7776 | ||
bb894c9d | 7777 | @end deftypefun |
8925f36f | 7778 | |
bb894c9d | 7779 | @deftypefun void glGetClipPlane plane equation |
3c9b6116 AW |
7780 | Return the coefficients of the specified clipping plane. |
7781 | ||
8925f36f AW |
7782 | @table @asis |
7783 | @item @var{plane} | |
7784 | Specifies a clipping plane. The number of clipping planes depends on the | |
7785 | implementation, but at least six clipping planes are supported. They are | |
3c9b6116 AW |
7786 | identified by symbolic names of the form @code{GL_CLIP_PLANE}@r{@var{i}} |
7787 | where i ranges from 0 to the value of @code{GL_MAX_CLIP_PLANES} - 1. | |
8925f36f AW |
7788 | |
7789 | @item @var{equation} | |
7790 | Returns four double-precision values that are the coefficients of the | |
7791 | plane equation of @var{plane} in eye coordinates. The initial value is | |
7792 | (0, 0, 0, 0). | |
7793 | ||
7794 | @end table | |
7795 | ||
8925f36f AW |
7796 | @code{glGetClipPlane} returns in @var{equation} the four coefficients of |
7797 | the plane equation for @var{plane}. | |
7798 | ||
8925f36f AW |
7799 | @code{GL_INVALID_ENUM} is generated if @var{plane} is not an accepted |
7800 | value. | |
7801 | ||
7802 | @code{GL_INVALID_OPERATION} is generated if @code{glGetClipPlane} is | |
7803 | executed between the execution of @code{glBegin} and the corresponding | |
7804 | execution of @code{glEnd}. | |
7805 | ||
bb894c9d | 7806 | @end deftypefun |
8925f36f | 7807 | |
bb894c9d | 7808 | @deftypefun void glGetColorTable target format type table |
3c9b6116 AW |
7809 | Retrieve contents of a color lookup table. |
7810 | ||
8925f36f AW |
7811 | @table @asis |
7812 | @item @var{target} | |
7813 | Must be @code{GL_COLOR_TABLE}, @code{GL_POST_CONVOLUTION_COLOR_TABLE}, | |
7814 | or @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
7815 | ||
7816 | @item @var{format} | |
7817 | The format of the pixel data in @var{table}. The possible values are | |
7818 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, | |
7819 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, | |
7820 | @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}. | |
7821 | ||
7822 | @item @var{type} | |
7823 | The type of the pixel data in @var{table}. Symbolic constants | |
7824 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
7825 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
7826 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
7827 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
7828 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
7829 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
7830 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
7831 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
7832 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
7833 | ||
7834 | @item @var{table} | |
7835 | Pointer to a one-dimensional array of pixel data containing the contents | |
7836 | of the color table. | |
7837 | ||
7838 | @end table | |
7839 | ||
8925f36f AW |
7840 | @code{glGetColorTable} returns in @var{table} the contents of the color |
7841 | table specified by @var{target}. No pixel transfer operations are | |
7842 | performed, but pixel storage modes that are applicable to | |
7843 | @code{glReadPixels} are performed. | |
7844 | ||
7845 | If a non-zero named buffer object is bound to the | |
7846 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
7847 | histogram table is requested, @var{table} is treated as a byte offset | |
7848 | into the buffer object's data store. | |
7849 | ||
7850 | Color components that are requested in the specified @var{format}, but | |
7851 | which are not included in the internal format of the color lookup table, | |
7852 | are returned as zero. The assignments of internal color components to | |
7853 | the components requested by @var{format} are | |
7854 | ||
7855 | @table @asis | |
7856 | @item @strong{Internal Component} | |
7857 | @strong{Resulting Component} | |
7858 | ||
7859 | @item | |
7860 | Red | |
7861 | Red | |
7862 | ||
7863 | @item | |
7864 | Green | |
7865 | Green | |
7866 | ||
7867 | @item | |
7868 | Blue | |
7869 | Blue | |
7870 | ||
7871 | @item | |
7872 | Alpha | |
7873 | Alpha | |
7874 | ||
7875 | @item | |
7876 | Luminance | |
7877 | Red | |
7878 | ||
7879 | @item | |
7880 | Intensity | |
7881 | Red | |
7882 | ||
7883 | @end table | |
7884 | ||
7885 | ||
7886 | ||
8925f36f AW |
7887 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
7888 | allowable values. | |
7889 | ||
7890 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
7891 | allowable values. | |
7892 | ||
7893 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
7894 | allowable values. | |
7895 | ||
7896 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
7897 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
7898 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
7899 | and @var{format} is not @code{GL_RGB}. | |
7900 | ||
7901 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
7902 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
7903 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
7904 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
7905 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
7906 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
7907 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
7908 | ||
7909 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
7910 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
7911 | object's data store is currently mapped. | |
7912 | ||
7913 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
7914 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
7915 | would be packed to the buffer object such that the memory writes | |
7916 | required would exceed the data store size. | |
7917 | ||
7918 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
7919 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{table} | |
7920 | is not evenly divisible into the number of bytes needed to store in | |
7921 | memory a datum indicated by @var{type}. | |
7922 | ||
7923 | @code{GL_INVALID_OPERATION} is generated if @code{glGetColorTable} is | |
7924 | executed between the execution of @code{glBegin} and the corresponding | |
7925 | execution of @code{glEnd}. | |
7926 | ||
bb894c9d | 7927 | @end deftypefun |
8925f36f | 7928 | |
bb894c9d | 7929 | @deftypefun void glGetCompressedTexImage target lod img |
3c9b6116 AW |
7930 | Return a compressed texture image. |
7931 | ||
8925f36f AW |
7932 | @table @asis |
7933 | @item @var{target} | |
7934 | Specifies which texture is to be obtained. @code{GL_TEXTURE_1D}, | |
7935 | @code{GL_TEXTURE_2D}, and | |
7936 | @code{GL_TEXTURE_3D}@code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
7937 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
7938 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
7939 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
7940 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, and | |
7941 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z} are accepted. | |
7942 | ||
7943 | @item @var{lod} | |
7944 | Specifies the level-of-detail number of the desired image. Level 0 is | |
3c9b6116 AW |
7945 | the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap |
7946 | reduction image. | |
8925f36f AW |
7947 | |
7948 | @item @var{img} | |
7949 | Returns the compressed texture image. | |
7950 | ||
7951 | @end table | |
7952 | ||
8925f36f AW |
7953 | @code{glGetCompressedTexImage} returns the compressed texture image |
7954 | associated with @var{target} and @var{lod} into @var{img}. @var{img} | |
7955 | should be an array of @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} bytes. | |
7956 | @var{target} specifies whether the desired texture image was one | |
7957 | specified by @code{glTexImage1D} (@code{GL_TEXTURE_1D}), | |
7958 | @code{glTexImage2D} (@code{GL_TEXTURE_2D} or any of | |
7959 | @code{GL_TEXTURE_CUBE_MAP_*}), or @code{glTexImage3D} | |
7960 | (@code{GL_TEXTURE_3D}). @var{lod} specifies the level-of-detail number | |
7961 | of the desired image. | |
7962 | ||
7963 | If a non-zero named buffer object is bound to the | |
7964 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
7965 | texture image is requested, @var{img} is treated as a byte offset into | |
7966 | the buffer object's data store. | |
7967 | ||
7968 | To minimize errors, first verify that the texture is compressed by | |
7969 | calling @code{glGetTexLevelParameter} with argument | |
7970 | @code{GL_TEXTURE_COMPRESSED}. If the texture is compressed, then | |
7971 | determine the amount of memory required to store the compressed texture | |
7972 | by calling @code{glGetTexLevelParameter} with argument | |
7973 | @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE}. Finally, retrieve the internal | |
7974 | format of the texture by calling @code{glGetTexLevelParameter} with | |
7975 | argument @code{GL_TEXTURE_INTERNAL_FORMAT}. To store the texture for | |
7976 | later use, associate the internal format and size with the retrieved | |
7977 | texture image. These data can be used by the respective texture or | |
7978 | subtexture loading routine used for loading @var{target} textures. | |
7979 | ||
8925f36f AW |
7980 | @code{GL_INVALID_VALUE} is generated if @var{lod} is less than zero or |
7981 | greater than the maximum number of LODs permitted by the implementation. | |
7982 | ||
7983 | @code{GL_INVALID_OPERATION} is generated if | |
7984 | @code{glGetCompressedTexImage} is used to retrieve a texture that is in | |
7985 | an uncompressed internal format. | |
7986 | ||
7987 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
7988 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
7989 | object's data store is currently mapped. | |
7990 | ||
7991 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
7992 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
7993 | would be packed to the buffer object such that the memory writes | |
7994 | required would exceed the data store size. | |
7995 | ||
7996 | @code{GL_INVALID_OPERATION} is generated if | |
7997 | @code{glGetCompressedTexImage} is executed between the execution of | |
7998 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
7999 | ||
bb894c9d | 8000 | @end deftypefun |
8925f36f | 8001 | |
bb894c9d | 8002 | @deftypefun void glGetConvolutionFilter target format type image |
3c9b6116 AW |
8003 | Get current 1D or 2D convolution filter kernel. |
8004 | ||
8925f36f AW |
8005 | @table @asis |
8006 | @item @var{target} | |
8007 | The filter to be retrieved. Must be one of @code{GL_CONVOLUTION_1D} or | |
8008 | @code{GL_CONVOLUTION_2D}. | |
8009 | ||
8010 | @item @var{format} | |
8011 | Format of the output image. Must be one of @code{GL_RED}, | |
8012 | @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, | |
8013 | @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, or | |
8014 | @code{GL_LUMINANCE_ALPHA}. | |
8015 | ||
8016 | @item @var{type} | |
8017 | Data type of components in the output image. Symbolic constants | |
8018 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
8019 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
8020 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
8021 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
8022 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
8023 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
8024 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
8025 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
8026 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
8027 | ||
8028 | @item @var{image} | |
8029 | Pointer to storage for the output image. | |
8030 | ||
8031 | @end table | |
8032 | ||
8925f36f AW |
8033 | @code{glGetConvolutionFilter} returns the current 1D or 2D convolution |
8034 | filter kernel as an image. The one- or two-dimensional image is placed | |
8035 | in @var{image} according to the specifications in @var{format} and | |
8036 | @var{type}. No pixel transfer operations are performed on this image, | |
8037 | but the relevant pixel storage modes are applied. | |
8038 | ||
8039 | If a non-zero named buffer object is bound to the | |
8040 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
8041 | convolution filter is requested, @var{image} is treated as a byte offset | |
8042 | into the buffer object's data store. | |
8043 | ||
8044 | Color components that are present in @var{format} but not included in | |
8045 | the internal format of the filter are returned as zero. The assignments | |
8046 | of internal color components to the components of @var{format} are as | |
8047 | follows. | |
8048 | ||
8049 | @table @asis | |
8050 | @item @strong{Internal Component} | |
8051 | @strong{Resulting Component} | |
8052 | ||
8053 | @item | |
8054 | Red | |
8055 | Red | |
8056 | ||
8057 | @item | |
8058 | Green | |
8059 | Green | |
8060 | ||
8061 | @item | |
8062 | Blue | |
8063 | Blue | |
8064 | ||
8065 | @item | |
8066 | Alpha | |
8067 | Alpha | |
8068 | ||
8069 | @item | |
8070 | Luminance | |
8071 | Red | |
8072 | ||
8073 | @item | |
8074 | Intensity | |
8075 | Red | |
8076 | ||
8077 | @end table | |
8078 | ||
8079 | ||
8080 | ||
8925f36f AW |
8081 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
8082 | allowable values. | |
8083 | ||
8084 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
8085 | allowable values. | |
8086 | ||
8087 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
8088 | allowable values. | |
8089 | ||
8090 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8091 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
8092 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
8093 | and @var{format} is not @code{GL_RGB}. | |
8094 | ||
8095 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8096 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
8097 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
8098 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
8099 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
8100 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
8101 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
8102 | ||
8103 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8104 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
8105 | object's data store is currently mapped. | |
8106 | ||
8107 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8108 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
8109 | would be packed to the buffer object such that the memory writes | |
8110 | required would exceed the data store size. | |
8111 | ||
8112 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8113 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{image} | |
8114 | is not evenly divisible into the number of bytes needed to store in | |
8115 | memory a datum indicated by @var{type}. | |
8116 | ||
8117 | @code{GL_INVALID_OPERATION} is generated if | |
8118 | @code{glGetConvolutionFilter} is executed between the execution of | |
8119 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
8120 | ||
bb894c9d | 8121 | @end deftypefun |
8925f36f | 8122 | |
bb894c9d | 8123 | @deftypefun GLenum glGetError |
3c9b6116 AW |
8124 | Return error information. |
8125 | ||
8925f36f AW |
8126 | @code{glGetError} returns the value of the error flag. Each detectable |
8127 | error is assigned a numeric code and symbolic name. When an error | |
8128 | occurs, the error flag is set to the appropriate error code value. No | |
8129 | other errors are recorded until @code{glGetError} is called, the error | |
8130 | code is returned, and the flag is reset to @code{GL_NO_ERROR}. If a call | |
8131 | to @code{glGetError} returns @code{GL_NO_ERROR}, there has been no | |
8132 | detectable error since the last call to @code{glGetError}, or since the | |
8133 | GL was initialized. | |
8134 | ||
8135 | To allow for distributed implementations, there may be several error | |
8136 | flags. If any single error flag has recorded an error, the value of that | |
8137 | flag is returned and that flag is reset to @code{GL_NO_ERROR} when | |
8138 | @code{glGetError} is called. If more than one flag has recorded an | |
8139 | error, @code{glGetError} returns and clears an arbitrary error flag | |
8140 | value. Thus, @code{glGetError} should always be called in a loop, until | |
8141 | it returns @code{GL_NO_ERROR}, if all error flags are to be reset. | |
8142 | ||
8143 | Initially, all error flags are set to @code{GL_NO_ERROR}. | |
8144 | ||
8145 | The following errors are currently defined: | |
8146 | ||
8147 | @table @asis | |
8148 | @item @code{GL_NO_ERROR} | |
8149 | No error has been recorded. The value of this symbolic constant is | |
8150 | guaranteed to be 0. | |
8151 | ||
8152 | @item @code{GL_INVALID_ENUM} | |
8153 | An unacceptable value is specified for an enumerated argument. The | |
8154 | offending command is ignored and has no other side effect than to set | |
8155 | the error flag. | |
8156 | ||
8157 | @item @code{GL_INVALID_VALUE} | |
8158 | A numeric argument is out of range. The offending command is ignored and | |
8159 | has no other side effect than to set the error flag. | |
8160 | ||
8161 | @item @code{GL_INVALID_OPERATION} | |
8162 | The specified operation is not allowed in the current state. The | |
8163 | offending command is ignored and has no other side effect than to set | |
8164 | the error flag. | |
8165 | ||
8166 | @item @code{GL_STACK_OVERFLOW} | |
8167 | This command would cause a stack overflow. The offending command is | |
8168 | ignored and has no other side effect than to set the error flag. | |
8169 | ||
8170 | @item @code{GL_STACK_UNDERFLOW} | |
8171 | This command would cause a stack underflow. The offending command is | |
8172 | ignored and has no other side effect than to set the error flag. | |
8173 | ||
8174 | @item @code{GL_OUT_OF_MEMORY} | |
8175 | There is not enough memory left to execute the command. The state of the | |
8176 | GL is undefined, except for the state of the error flags, after this | |
8177 | error is recorded. | |
8178 | ||
8179 | @item @code{GL_TABLE_TOO_LARGE} | |
8180 | The specified table exceeds the implementation's maximum supported table | |
8181 | size. The offending command is ignored and has no other side effect than | |
8182 | to set the error flag. | |
8183 | ||
8184 | @end table | |
8185 | ||
8186 | When an error flag is set, results of a GL operation are undefined only | |
8187 | if @code{GL_OUT_OF_MEMORY} has occurred. In all other cases, the command | |
8188 | generating the error is ignored and has no effect on the GL state or | |
8189 | frame buffer contents. If the generating command returns a value, it | |
8190 | returns 0. If @code{glGetError} itself generates an error, it returns 0. | |
8191 | ||
8925f36f AW |
8192 | @code{GL_INVALID_OPERATION} is generated if @code{glGetError} is |
8193 | executed between the execution of @code{glBegin} and the corresponding | |
8194 | execution of @code{glEnd}. In this case, @code{glGetError} returns 0. | |
8195 | ||
bb894c9d | 8196 | @end deftypefun |
8925f36f | 8197 | |
bb894c9d | 8198 | @deftypefun void glGetHistogram target reset format type values |
3c9b6116 AW |
8199 | Get histogram table. |
8200 | ||
8925f36f AW |
8201 | @table @asis |
8202 | @item @var{target} | |
8203 | Must be @code{GL_HISTOGRAM}. | |
8204 | ||
8205 | @item @var{reset} | |
8206 | If @code{GL_TRUE}, each component counter that is actually returned is | |
8207 | reset to zero. (Other counters are unaffected.) If @code{GL_FALSE}, none | |
8208 | of the counters in the histogram table is modified. | |
8209 | ||
8210 | @item @var{format} | |
8211 | The format of values to be returned in @var{values}. Must be one of | |
8212 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, | |
8213 | @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, | |
8214 | @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}. | |
8215 | ||
8216 | @item @var{type} | |
8217 | The type of values to be returned in @var{values}. Symbolic constants | |
8218 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
8219 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
8220 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
8221 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
8222 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
8223 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
8224 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
8225 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
8226 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
8227 | ||
8228 | @item @var{values} | |
8229 | A pointer to storage for the returned histogram table. | |
8230 | ||
8231 | @end table | |
8232 | ||
8925f36f AW |
8233 | @code{glGetHistogram} returns the current histogram table as a |
8234 | one-dimensional image with the same width as the histogram. No pixel | |
8235 | transfer operations are performed on this image, but pixel storage modes | |
8236 | that are applicable to 1D images are honored. | |
8237 | ||
8238 | If a non-zero named buffer object is bound to the | |
8239 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
8240 | histogram table is requested, @var{values} is treated as a byte offset | |
8241 | into the buffer object's data store. | |
8242 | ||
8243 | Color components that are requested in the specified @var{format}, but | |
8244 | which are not included in the internal format of the histogram, are | |
8245 | returned as zero. The assignments of internal color components to the | |
8246 | components requested by @var{format} are: | |
8247 | ||
8248 | @table @asis | |
8249 | @item @strong{Internal Component} | |
8250 | @strong{Resulting Component} | |
8251 | ||
8252 | @item | |
8253 | Red | |
8254 | Red | |
8255 | ||
8256 | @item | |
8257 | Green | |
8258 | Green | |
8259 | ||
8260 | @item | |
8261 | Blue | |
8262 | Blue | |
8263 | ||
8264 | @item | |
8265 | Alpha | |
8266 | Alpha | |
8267 | ||
8268 | @item | |
8269 | Luminance | |
8270 | Red | |
8271 | ||
8272 | @end table | |
8273 | ||
8274 | ||
8275 | ||
8925f36f AW |
8276 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
8277 | @code{GL_HISTOGRAM}. | |
8278 | ||
8279 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
8280 | allowable values. | |
8281 | ||
8282 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
8283 | allowable values. | |
8284 | ||
8285 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8286 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
8287 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
8288 | and @var{format} is not @code{GL_RGB}. | |
8289 | ||
8290 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8291 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
8292 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
8293 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
8294 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
8295 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
8296 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
8297 | ||
8298 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8299 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
8300 | object's data store is currently mapped. | |
8301 | ||
8302 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8303 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
8304 | would be packed to the buffer object such that the memory writes | |
8305 | required would exceed the data store size. | |
8306 | ||
8307 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8308 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{values} | |
8309 | is not evenly divisible into the number of bytes needed to store in | |
8310 | memory a datum indicated by @var{type}. | |
8311 | ||
8312 | @code{GL_INVALID_OPERATION} is generated if @code{glGetHistogram} is | |
8313 | executed between the execution of @code{glBegin} and the corresponding | |
8314 | execution of @code{glEnd}. | |
8315 | ||
bb894c9d | 8316 | @end deftypefun |
8925f36f | 8317 | |
bb894c9d AW |
8318 | @deftypefun void glGetMinmax target reset format types values |
8319 | Get minimum and maximum pixel values. | |
3c9b6116 | 8320 | |
8925f36f | 8321 | @table @asis |
bb894c9d AW |
8322 | @item @var{target} |
8323 | Must be @code{GL_MINMAX}. | |
8925f36f | 8324 | |
bb894c9d AW |
8325 | @item @var{reset} |
8326 | If @code{GL_TRUE}, all entries in the minmax table that are actually | |
8327 | returned are reset to their initial values. (Other entries are | |
8328 | unaltered.) If @code{GL_FALSE}, the minmax table is unaltered. | |
8925f36f | 8329 | |
bb894c9d AW |
8330 | @item @var{format} |
8331 | The format of the data to be returned in @var{values}. Must be one of | |
8332 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, | |
8333 | @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, | |
8334 | @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}. | |
8925f36f | 8335 | |
bb894c9d AW |
8336 | @item @var{types} |
8337 | The type of the data to be returned in @var{values}. Symbolic constants | |
8338 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
8339 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
8340 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
8341 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
8342 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
8343 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
8344 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
8345 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
8346 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
8925f36f | 8347 | |
bb894c9d AW |
8348 | @item @var{values} |
8349 | A pointer to storage for the returned values. | |
8925f36f | 8350 | |
bb894c9d | 8351 | @end table |
8925f36f | 8352 | |
bb894c9d AW |
8353 | @code{glGetMinmax} returns the accumulated minimum and maximum pixel |
8354 | values (computed on a per-component basis) in a one-dimensional image of | |
8355 | width 2. The first set of return values are the minima, and the second | |
8356 | set of return values are the maxima. The format of the return values is | |
8357 | determined by @var{format}, and their type is determined by @var{types}. | |
8925f36f AW |
8358 | |
8359 | If a non-zero named buffer object is bound to the | |
8360 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while | |
8361 | minimum and maximum pixel values are requested, @var{values} is treated | |
8362 | as a byte offset into the buffer object's data store. | |
8363 | ||
8364 | No pixel transfer operations are performed on the return values, but | |
8365 | pixel storage modes that are applicable to one-dimensional images are | |
8366 | performed. Color components that are requested in the specified | |
8367 | @var{format}, but that are not included in the internal format of the | |
8368 | minmax table, are returned as zero. The assignment of internal color | |
8369 | components to the components requested by @var{format} are as follows: | |
8370 | ||
8371 | ||
8372 | ||
8373 | @table @asis | |
8374 | @item @strong{Internal Component} | |
8375 | @strong{Resulting Component} | |
8376 | ||
8377 | @item | |
8378 | Red | |
8379 | Red | |
8380 | ||
8381 | @item | |
8382 | Green | |
8383 | Green | |
8384 | ||
8385 | @item | |
8386 | Blue | |
8387 | Blue | |
8388 | ||
8389 | @item | |
8390 | Alpha | |
8391 | Alpha | |
8392 | ||
8393 | @item | |
8394 | Luminance | |
8395 | Red | |
8396 | ||
8397 | @end table | |
8398 | ||
8399 | If @var{reset} is @code{GL_TRUE}, the minmax table entries corresponding | |
8400 | to the return values are reset to their initial values. Minimum and | |
8401 | maximum values that are not returned are not modified, even if | |
8402 | @var{reset} is @code{GL_TRUE}. | |
8403 | ||
8925f36f AW |
8404 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
8405 | @code{GL_MINMAX}. | |
8406 | ||
8407 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
8408 | allowable values. | |
8409 | ||
8410 | @code{GL_INVALID_ENUM} is generated if @var{types} is not one of the | |
8411 | allowable values. | |
8412 | ||
8413 | @code{GL_INVALID_OPERATION} is generated if @var{types} is one of | |
8414 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
8415 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
8416 | and @var{format} is not @code{GL_RGB}. | |
8417 | ||
8418 | @code{GL_INVALID_OPERATION} is generated if @var{types} is one of | |
8419 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
8420 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
8421 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
8422 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
8423 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
8424 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
8425 | ||
8426 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8427 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
8428 | object's data store is currently mapped. | |
8429 | ||
8430 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8431 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
8432 | would be packed to the buffer object such that the memory writes | |
8433 | required would exceed the data store size. | |
8434 | ||
8435 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8436 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{values} | |
8437 | is not evenly divisible into the number of bytes needed to store in | |
8438 | memory a datum indicated by @var{type}. | |
8439 | ||
8440 | @code{GL_INVALID_OPERATION} is generated if @code{glGetMinmax} is | |
8441 | executed between the execution of @code{glBegin} and the corresponding | |
8442 | execution of @code{glEnd}. | |
8443 | ||
bb894c9d | 8444 | @end deftypefun |
8925f36f | 8445 | |
bb894c9d | 8446 | @deftypefun void glGetPolygonStipple pattern |
3c9b6116 AW |
8447 | Return the polygon stipple pattern. |
8448 | ||
8925f36f AW |
8449 | @table @asis |
8450 | @item @var{pattern} | |
8451 | Returns the stipple pattern. The initial value is all 1's. | |
8452 | ||
8453 | @end table | |
8454 | ||
3c9b6116 AW |
8455 | @code{glGetPolygonStipple} returns to @var{pattern} a @r{32×32} polygon |
8456 | stipple pattern. The pattern is packed into memory as if | |
8925f36f AW |
8457 | @code{glReadPixels} with both @var{height} and @var{width} of 32, |
8458 | @var{type} of @code{GL_BITMAP}, and @var{format} of | |
8459 | @code{GL_COLOR_INDEX} were called, and the stipple pattern were stored | |
3c9b6116 AW |
8460 | in an internal @r{32×32} color index buffer. Unlike @code{glReadPixels}, |
8461 | however, pixel transfer operations (shift, offset, pixel map) are not | |
8462 | applied to the returned stipple image. | |
8925f36f AW |
8463 | |
8464 | If a non-zero named buffer object is bound to the | |
8465 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
8466 | polygon stipple pattern is requested, @var{pattern} is treated as a byte | |
8467 | offset into the buffer object's data store. | |
8468 | ||
8925f36f AW |
8469 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object |
8470 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
8471 | object's data store is currently mapped. | |
8472 | ||
8473 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8474 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
8475 | would be packed to the buffer object such that the memory writes | |
8476 | required would exceed the data store size. | |
8477 | ||
8478 | @code{GL_INVALID_OPERATION} is generated if @code{glGetPolygonStipple} | |
8479 | is executed between the execution of @code{glBegin} and the | |
8480 | corresponding execution of @code{glEnd}. | |
8481 | ||
bb894c9d | 8482 | @end deftypefun |
8925f36f | 8483 | |
bb894c9d | 8484 | @deftypefun void glGetProgramInfoLog program maxLength length infoLog |
3c9b6116 AW |
8485 | Returns the information log for a program object. |
8486 | ||
8925f36f AW |
8487 | @table @asis |
8488 | @item @var{program} | |
8489 | Specifies the program object whose information log is to be queried. | |
8490 | ||
8491 | @item @var{maxLength} | |
8492 | Specifies the size of the character buffer for storing the returned | |
8493 | information log. | |
8494 | ||
8495 | @item @var{length} | |
8496 | Returns the length of the string returned in @var{infoLog} (excluding | |
8497 | the null terminator). | |
8498 | ||
8499 | @item @var{infoLog} | |
8500 | Specifies an array of characters that is used to return the information | |
8501 | log. | |
8502 | ||
8503 | @end table | |
8504 | ||
8925f36f AW |
8505 | @code{glGetProgramInfoLog} returns the information log for the specified |
8506 | program object. The information log for a program object is modified | |
8507 | when the program object is linked or validated. The string that is | |
8508 | returned will be null terminated. | |
8509 | ||
8510 | @code{glGetProgramInfoLog} returns in @var{infoLog} as much of the | |
8511 | information log as it can, up to a maximum of @var{maxLength} | |
8512 | characters. The number of characters actually returned, excluding the | |
8513 | null termination character, is specified by @var{length}. If the length | |
8514 | of the returned string is not required, a value of @code{NULL} can be | |
8515 | passed in the @var{length} argument. The size of the buffer required to | |
8516 | store the returned information log can be obtained by calling | |
8517 | @code{glGetProgram} with the value @code{GL_INFO_LOG_LENGTH}. | |
8518 | ||
8519 | The information log for a program object is either an empty string, or a | |
8520 | string containing information about the last link operation, or a string | |
8521 | containing information about the last validation operation. It may | |
8522 | contain diagnostic messages, warning messages, and other information. | |
8523 | When a program object is created, its information log will be a string | |
8524 | of length 0. | |
8525 | ||
8925f36f AW |
8526 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
8527 | generated by OpenGL. | |
8528 | ||
8529 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
8530 | program object. | |
8531 | ||
8532 | @code{GL_INVALID_VALUE} is generated if @var{maxLength} is less than 0. | |
8533 | ||
8534 | @code{GL_INVALID_OPERATION} is generated if @code{glGetProgramInfoLog} | |
8535 | is executed between the execution of @code{glBegin} and the | |
8536 | corresponding execution of @code{glEnd}. | |
8537 | ||
bb894c9d | 8538 | @end deftypefun |
8925f36f | 8539 | |
bb894c9d AW |
8540 | @deftypefun void glGetSeparableFilter target format type row column span |
8541 | Get separable convolution filter kernel images. | |
3c9b6116 | 8542 | |
8925f36f | 8543 | @table @asis |
bb894c9d AW |
8544 | @item @var{target} |
8545 | The separable filter to be retrieved. Must be @code{GL_SEPARABLE_2D}. | |
8925f36f | 8546 | |
bb894c9d AW |
8547 | @item @var{format} |
8548 | Format of the output images. Must be one of @code{GL_RED}, | |
8549 | @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, | |
8550 | @code{GL_BGR}@code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, or | |
8551 | @code{GL_LUMINANCE_ALPHA}. | |
8925f36f | 8552 | |
bb894c9d AW |
8553 | @item @var{type} |
8554 | Data type of components in the output images. Symbolic constants | |
8555 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
8556 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
8557 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
8558 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
8559 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
8560 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
8561 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
8562 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
8563 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
8925f36f | 8564 | |
bb894c9d AW |
8565 | @item @var{row} |
8566 | Pointer to storage for the row filter image. | |
8925f36f | 8567 | |
bb894c9d AW |
8568 | @item @var{column} |
8569 | Pointer to storage for the column filter image. | |
8925f36f | 8570 | |
bb894c9d AW |
8571 | @item @var{span} |
8572 | Pointer to storage for the span filter image (currently unused). | |
8925f36f | 8573 | |
bb894c9d | 8574 | @end table |
8925f36f | 8575 | |
bb894c9d AW |
8576 | @code{glGetSeparableFilter} returns the two one-dimensional filter |
8577 | kernel images for the current separable 2D convolution filter. The row | |
8578 | image is placed in @var{row} and the column image is placed in | |
8579 | @var{column} according to the specifications in @var{format} and | |
8580 | @var{type}. (In the current implementation, @var{span} is not affected | |
8581 | in any way.) No pixel transfer operations are performed on the images, | |
8582 | but the relevant pixel storage modes are applied. | |
8925f36f | 8583 | |
bb894c9d AW |
8584 | If a non-zero named buffer object is bound to the |
8585 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
8586 | separable convolution filter is requested, @var{row}, @var{column}, and | |
8587 | @var{span} are treated as a byte offset into the buffer object's data | |
8588 | store. | |
8925f36f | 8589 | |
bb894c9d AW |
8590 | Color components that are present in @var{format} but not included in |
8591 | the internal format of the filters are returned as zero. The assignments | |
8592 | of internal color components to the components of @var{format} are as | |
8593 | follows: | |
8925f36f | 8594 | |
8925f36f AW |
8595 | |
8596 | ||
bb894c9d AW |
8597 | @table @asis |
8598 | @item @strong{Internal Component} | |
8599 | @strong{Resulting Component} | |
8925f36f AW |
8600 | |
8601 | @item | |
8602 | Red | |
8603 | Red | |
8604 | ||
8605 | @item | |
8606 | Green | |
8607 | Green | |
8608 | ||
8609 | @item | |
8610 | Blue | |
8611 | Blue | |
8612 | ||
8613 | @item | |
8614 | Alpha | |
8615 | Alpha | |
8616 | ||
8617 | @item | |
8618 | Luminance | |
8619 | Red | |
8620 | ||
8621 | @item | |
8622 | Intensity | |
8623 | Red | |
8624 | ||
8625 | @end table | |
8626 | ||
8627 | ||
8628 | ||
8925f36f AW |
8629 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
8630 | @code{GL_SEPARABLE_2D}. | |
8631 | ||
8632 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
8633 | allowable values. | |
8634 | ||
8635 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
8636 | allowable values. | |
8637 | ||
8638 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8639 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
8640 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
8641 | and @var{format} is not @code{GL_RGB}. | |
8642 | ||
8643 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8644 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
8645 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
8646 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
8647 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
8648 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
8649 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
8650 | ||
8651 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8652 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
8653 | object's data store is currently mapped. | |
8654 | ||
8655 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8656 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
8657 | would be packed to the buffer object such that the memory writes | |
8658 | required would exceed the data store size. | |
8659 | ||
8660 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8661 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{row} or | |
8662 | @var{column} is not evenly divisible into the number of bytes needed to | |
8663 | store in memory a datum indicated by @var{type}. | |
8664 | ||
8665 | @code{GL_INVALID_OPERATION} is generated if @code{glGetSeparableFilter} | |
8666 | is executed between the execution of @code{glBegin} and the | |
8667 | corresponding execution of @code{glEnd}. | |
8668 | ||
bb894c9d | 8669 | @end deftypefun |
8925f36f | 8670 | |
bb894c9d | 8671 | @deftypefun void glGetShaderInfoLog shader maxLength length infoLog |
3c9b6116 AW |
8672 | Returns the information log for a shader object. |
8673 | ||
8925f36f AW |
8674 | @table @asis |
8675 | @item @var{shader} | |
8676 | Specifies the shader object whose information log is to be queried. | |
8677 | ||
8678 | @item @var{maxLength} | |
8679 | Specifies the size of the character buffer for storing the returned | |
8680 | information log. | |
8681 | ||
8682 | @item @var{length} | |
8683 | Returns the length of the string returned in @var{infoLog} (excluding | |
8684 | the null terminator). | |
8685 | ||
8686 | @item @var{infoLog} | |
8687 | Specifies an array of characters that is used to return the information | |
8688 | log. | |
8689 | ||
8690 | @end table | |
8691 | ||
8925f36f AW |
8692 | @code{glGetShaderInfoLog} returns the information log for the specified |
8693 | shader object. The information log for a shader object is modified when | |
8694 | the shader is compiled. The string that is returned will be null | |
8695 | terminated. | |
8696 | ||
8697 | @code{glGetShaderInfoLog} returns in @var{infoLog} as much of the | |
8698 | information log as it can, up to a maximum of @var{maxLength} | |
8699 | characters. The number of characters actually returned, excluding the | |
8700 | null termination character, is specified by @var{length}. If the length | |
8701 | of the returned string is not required, a value of @code{NULL} can be | |
8702 | passed in the @var{length} argument. The size of the buffer required to | |
8703 | store the returned information log can be obtained by calling | |
8704 | @code{glGetShader} with the value @code{GL_INFO_LOG_LENGTH}. | |
8705 | ||
8706 | The information log for a shader object is a string that may contain | |
8707 | diagnostic messages, warning messages, and other information about the | |
8708 | last compile operation. When a shader object is created, its information | |
8709 | log will be a string of length 0. | |
8710 | ||
8925f36f AW |
8711 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
8712 | generated by OpenGL. | |
8713 | ||
8714 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
8715 | object. | |
8716 | ||
8717 | @code{GL_INVALID_VALUE} is generated if @var{maxLength} is less than 0. | |
8718 | ||
8719 | @code{GL_INVALID_OPERATION} is generated if @code{glGetShaderInfoLog} is | |
8720 | executed between the execution of @code{glBegin} and the corresponding | |
8721 | execution of @code{glEnd}. | |
8722 | ||
bb894c9d | 8723 | @end deftypefun |
8925f36f | 8724 | |
bb894c9d | 8725 | @deftypefun void glGetShaderSource shader bufSize length source |
3c9b6116 AW |
8726 | Returns the source code string from a shader object. |
8727 | ||
8925f36f AW |
8728 | @table @asis |
8729 | @item @var{shader} | |
8730 | Specifies the shader object to be queried. | |
8731 | ||
8732 | @item @var{bufSize} | |
8733 | Specifies the size of the character buffer for storing the returned | |
8734 | source code string. | |
8735 | ||
8736 | @item @var{length} | |
8737 | Returns the length of the string returned in @var{source} (excluding the | |
8738 | null terminator). | |
8739 | ||
8740 | @item @var{source} | |
8741 | Specifies an array of characters that is used to return the source code | |
8742 | string. | |
8743 | ||
8744 | @end table | |
8745 | ||
8925f36f AW |
8746 | @code{glGetShaderSource} returns the concatenation of the source code |
8747 | strings from the shader object specified by @var{shader}. The source | |
8748 | code strings for a shader object are the result of a previous call to | |
8749 | @code{glShaderSource}. The string returned by the function will be null | |
8750 | terminated. | |
8751 | ||
8752 | @code{glGetShaderSource} returns in @var{source} as much of the source | |
8753 | code string as it can, up to a maximum of @var{bufSize} characters. The | |
8754 | number of characters actually returned, excluding the null termination | |
8755 | character, is specified by @var{length}. If the length of the returned | |
8756 | string is not required, a value of @code{NULL} can be passed in the | |
8757 | @var{length} argument. The size of the buffer required to store the | |
8758 | returned source code string can be obtained by calling | |
8759 | @code{glGetShader} with the value @code{GL_SHADER_SOURCE_LENGTH}. | |
8760 | ||
8925f36f AW |
8761 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
8762 | generated by OpenGL. | |
8763 | ||
8764 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
8765 | object. | |
8766 | ||
8767 | @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0. | |
8768 | ||
8769 | @code{GL_INVALID_OPERATION} is generated if @code{glGetShaderSource} is | |
8770 | executed between the execution of @code{glBegin} and the corresponding | |
8771 | execution of @code{glEnd}. | |
8772 | ||
bb894c9d | 8773 | @end deftypefun |
8925f36f | 8774 | |
bb894c9d | 8775 | @deftypefun * glGetString name |
3c9b6116 AW |
8776 | Return a string describing the current GL connection. |
8777 | ||
8925f36f AW |
8778 | @table @asis |
8779 | @item @var{name} | |
8780 | Specifies a symbolic constant, one of @code{GL_VENDOR}, | |
8781 | @code{GL_RENDERER}, @code{GL_VERSION}, | |
8782 | @code{GL_SHADING_LANGUAGE_VERSION}, or @code{GL_EXTENSIONS}. | |
8783 | ||
8784 | @end table | |
8785 | ||
8925f36f AW |
8786 | @code{glGetString} returns a pointer to a static string describing some |
8787 | aspect of the current GL connection. @var{name} can be one of the | |
8788 | following: | |
8789 | ||
8790 | @table @asis | |
8791 | @item @code{GL_VENDOR} | |
8792 | ||
8793 | ||
8794 | Returns the company responsible for this GL implementation. This name | |
8795 | does not change from release to release. | |
8796 | ||
8797 | @item @code{GL_RENDERER} | |
8798 | ||
8799 | ||
8800 | Returns the name of the renderer. This name is typically specific to a | |
8801 | particular configuration of a hardware platform. It does not change from | |
8802 | release to release. | |
8803 | ||
8804 | @item @code{GL_VERSION} | |
8805 | ||
8806 | ||
8807 | Returns a version or release number. | |
8808 | ||
8809 | @item @code{GL_SHADING_LANGUAGE_VERSION} | |
8810 | ||
8811 | ||
8812 | Returns a version or release number for the shading language. | |
8813 | ||
8814 | @item @code{GL_EXTENSIONS} | |
8815 | ||
8816 | ||
8817 | Returns a space-separated list of supported extensions to GL. | |
8818 | ||
8819 | @end table | |
8820 | ||
bb894c9d AW |
8821 | Because the GL does not include queries for the performance |
8822 | characteristics of an implementation, some applications are written to | |
8823 | recognize known platforms and modify their GL usage based on known | |
8824 | performance characteristics of these platforms. Strings @code{GL_VENDOR} | |
8825 | and @code{GL_RENDERER} together uniquely specify a platform. They do not | |
8826 | change from release to release and should be used by | |
8827 | platform-recognition algorithms. | |
8925f36f | 8828 | |
bb894c9d AW |
8829 | Some applications want to make use of features that are not part of the |
8830 | standard GL. These features may be implemented as extensions to the | |
8831 | standard GL. The @code{GL_EXTENSIONS} string is a space-separated list | |
8832 | of supported GL extensions. (Extension names never contain a space | |
8833 | character.) | |
8925f36f | 8834 | |
bb894c9d AW |
8835 | The @code{GL_VERSION} and @code{GL_SHADING_LANGUAGE_VERSION} strings |
8836 | begin with a version number. The version number uses one of these forms: | |
8925f36f | 8837 | |
bb894c9d | 8838 | @var{major_number.minor_number}@var{major_number.minor_number.release_number} |
8925f36f | 8839 | |
bb894c9d AW |
8840 | Vendor-specific information may follow the version number. Its format |
8841 | depends on the implementation, but a space always separates the version | |
8842 | number and the vendor-specific information. | |
8925f36f | 8843 | |
bb894c9d | 8844 | All strings are null-terminated. |
8925f36f | 8845 | |
bb894c9d AW |
8846 | @code{GL_INVALID_ENUM} is generated if @var{name} is not an accepted |
8847 | value. | |
8925f36f | 8848 | |
bb894c9d AW |
8849 | @code{GL_INVALID_OPERATION} is generated if @code{glGetString} is |
8850 | executed between the execution of @code{glBegin} and the corresponding | |
8851 | execution of @code{glEnd}. | |
8925f36f | 8852 | |
bb894c9d | 8853 | @end deftypefun |
8925f36f | 8854 | |
bb894c9d AW |
8855 | @deftypefun void glGetTexImage target level format type img |
8856 | Return a texture image. | |
8925f36f | 8857 | |
bb894c9d AW |
8858 | @table @asis |
8859 | @item @var{target} | |
8860 | Specifies which texture is to be obtained. @code{GL_TEXTURE_1D}, | |
8861 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, | |
8862 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
8863 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
8864 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
8865 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
8866 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, and | |
8867 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z} are accepted. | |
8925f36f | 8868 | |
bb894c9d AW |
8869 | @item @var{level} |
8870 | Specifies the level-of-detail number of the desired image. Level 0 is | |
8871 | the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap | |
8872 | reduction image. | |
8925f36f | 8873 | |
bb894c9d AW |
8874 | @item @var{format} |
8875 | Specifies a pixel format for the returned data. The supported formats | |
8876 | are @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, | |
8877 | @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, | |
8878 | @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA}. | |
8925f36f | 8879 | |
bb894c9d AW |
8880 | @item @var{type} |
8881 | Specifies a pixel type for the returned data. The supported types are | |
8882 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT}, | |
8883 | @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT}, | |
8884 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
8885 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
8886 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
8887 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
8888 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
8889 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
8890 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
8925f36f | 8891 | |
bb894c9d AW |
8892 | @item @var{img} |
8893 | Returns the texture image. Should be a pointer to an array of the type | |
8894 | specified by @var{type}. | |
8925f36f | 8895 | |
bb894c9d | 8896 | @end table |
8925f36f | 8897 | |
bb894c9d AW |
8898 | @code{glGetTexImage} returns a texture image into @var{img}. |
8899 | @var{target} specifies whether the desired texture image is one | |
8900 | specified by @code{glTexImage1D} (@code{GL_TEXTURE_1D}), | |
8901 | @code{glTexImage2D} (@code{GL_TEXTURE_2D} or any of | |
8902 | @code{GL_TEXTURE_CUBE_MAP_*}), or @code{glTexImage3D} | |
8903 | (@code{GL_TEXTURE_3D}). @var{level} specifies the level-of-detail number | |
8904 | of the desired image. @var{format} and @var{type} specify the format and | |
8905 | type of the desired image array. See the reference pages | |
8906 | @code{glTexImage1D} and @code{glDrawPixels} for a description of the | |
8907 | acceptable values for the @var{format} and @var{type} parameters, | |
8908 | respectively. | |
8925f36f | 8909 | |
bb894c9d AW |
8910 | If a non-zero named buffer object is bound to the |
8911 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
8912 | texture image is requested, @var{img} is treated as a byte offset into | |
8913 | the buffer object's data store. | |
8925f36f | 8914 | |
bb894c9d AW |
8915 | To understand the operation of @code{glGetTexImage}, consider the |
8916 | selected internal four-component texture image to be an RGBA color | |
8917 | buffer the size of the image. The semantics of @code{glGetTexImage} are | |
8918 | then identical to those of @code{glReadPixels}, with the exception that | |
8919 | no pixel transfer operations are performed, when called with the same | |
8920 | @var{format} and @var{type}, with @var{x} and @var{y} set to 0, | |
8921 | @var{width} set to the width of the texture image (including border if | |
8922 | one was specified), and @var{height} set to 1 for 1D images, or to the | |
8923 | height of the texture image (including border if one was specified) for | |
8924 | 2D images. Because the internal texture image is an RGBA image, pixel | |
8925 | formats @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, and | |
8926 | @code{GL_DEPTH_COMPONENT} are not accepted, and pixel type | |
8927 | @code{GL_BITMAP} is not accepted. | |
8925f36f | 8928 | |
bb894c9d AW |
8929 | If the selected texture image does not contain four components, the |
8930 | following mappings are applied. Single-component textures are treated as | |
8931 | RGBA buffers with red set to the single-component value, green set to 0, | |
8932 | blue set to 0, and alpha set to 1. Two-component textures are treated as | |
8933 | RGBA buffers with red set to the value of component zero, alpha set to | |
8934 | the value of component one, and green and blue set to 0. Finally, | |
8935 | three-component textures are treated as RGBA buffers with red set to | |
8936 | component zero, green set to component one, blue set to component two, | |
8937 | and alpha set to 1. | |
8925f36f | 8938 | |
bb894c9d AW |
8939 | To determine the required size of @var{img}, use |
8940 | @code{glGetTexLevelParameter} to determine the dimensions of the | |
8941 | internal texture image, then scale the required number of pixels by the | |
8942 | storage required for each pixel, based on @var{format} and @var{type}. | |
8943 | Be sure to take the pixel storage parameters into account, especially | |
8944 | @code{GL_PACK_ALIGNMENT}. | |
8925f36f | 8945 | |
bb894c9d AW |
8946 | @code{GL_INVALID_ENUM} is generated if @var{target}, @var{format}, or |
8947 | @var{type} is not an accepted value. | |
8925f36f | 8948 | |
bb894c9d | 8949 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. |
8925f36f | 8950 | |
bb894c9d AW |
8951 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than |
8952 | @r{@var{log}_2(@var{max},)}, where @r{@var{max}} is the returned value | |
8953 | of @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f | 8954 | |
bb894c9d AW |
8955 | @code{GL_INVALID_OPERATION} is returned if @var{type} is one of |
8956 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
8957 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
8958 | and @var{format} is not @code{GL_RGB}. | |
8925f36f | 8959 | |
bb894c9d AW |
8960 | @code{GL_INVALID_OPERATION} is returned if @var{type} is one of |
8961 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
8962 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
8963 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
8964 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
8965 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}, and @var{format} is neither | |
8966 | @code{GL_RGBA} or @code{GL_BGRA}. | |
8925f36f | 8967 | |
bb894c9d AW |
8968 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object |
8969 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
8970 | object's data store is currently mapped. | |
8925f36f | 8971 | |
bb894c9d AW |
8972 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object |
8973 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
8974 | would be packed to the buffer object such that the memory writes | |
8975 | required would exceed the data store size. | |
8925f36f | 8976 | |
bb894c9d AW |
8977 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object |
8978 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{img} is | |
8979 | not evenly divisible into the number of bytes needed to store in memory | |
8980 | a datum indicated by @var{type}. | |
8925f36f | 8981 | |
bb894c9d AW |
8982 | @code{GL_INVALID_OPERATION} is generated if @code{glGetTexImage} is |
8983 | executed between the execution of @code{glBegin} and the corresponding | |
8984 | execution of @code{glEnd}. | |
8925f36f | 8985 | |
bb894c9d | 8986 | @end deftypefun |
8925f36f | 8987 | |
bb894c9d AW |
8988 | @deftypefun GLint glGetUniformLocation program name |
8989 | Returns the location of a uniform variable. | |
8925f36f | 8990 | |
bb894c9d AW |
8991 | @table @asis |
8992 | @item @var{program} | |
8993 | Specifies the program object to be queried. | |
8925f36f | 8994 | |
bb894c9d AW |
8995 | @item @var{name} |
8996 | Points to a null terminated string containing the name of the uniform | |
8997 | variable whose location is to be queried. | |
8925f36f AW |
8998 | |
8999 | @end table | |
9000 | ||
bb894c9d AW |
9001 | @code{glGetUniformLocation } returns an integer that represents the |
9002 | location of a specific uniform variable within a program object. | |
9003 | @var{name} must be a null terminated string that contains no white | |
9004 | space. @var{name} must be an active uniform variable name in | |
9005 | @var{program} that is not a structure, an array of structures, or a | |
9006 | subcomponent of a vector or a matrix. This function returns -1 if | |
9007 | @var{name} does not correspond to an active uniform variable in | |
9008 | @var{program} or if @var{name} starts with the reserved prefix "gl_". | |
8925f36f | 9009 | |
bb894c9d AW |
9010 | Uniform variables that are structures or arrays of structures may be |
9011 | queried by calling @code{glGetUniformLocation} for each field within the | |
9012 | structure. The array element operator "[]" and the structure field | |
9013 | operator "." may be used in @var{name} in order to select elements | |
9014 | within an array or fields within a structure. The result of using these | |
9015 | operators is not allowed to be another structure, an array of | |
9016 | structures, or a subcomponent of a vector or a matrix. Except if the | |
9017 | last part of @var{name} indicates a uniform variable array, the location | |
9018 | of the first element of an array can be retrieved by using the name of | |
9019 | the array, or by using the name appended by "[0]". | |
8925f36f | 9020 | |
bb894c9d AW |
9021 | The actual locations assigned to uniform variables are not known until |
9022 | the program object is linked successfully. After linking has occurred, | |
9023 | the command @code{glGetUniformLocation} can be used to obtain the | |
9024 | location of a uniform variable. This location value can then be passed | |
9025 | to @code{glUniform} to set the value of the uniform variable or to | |
9026 | @code{glGetUniform} in order to query the current value of the uniform | |
9027 | variable. After a program object has been linked successfully, the index | |
9028 | values for uniform variables remain fixed until the next link command | |
9029 | occurs. Uniform variable locations and values can only be queried after | |
9030 | a link if the link was successful. | |
9031 | ||
9032 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value | |
9033 | generated by OpenGL. | |
8925f36f | 9034 | |
bb894c9d AW |
9035 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a |
9036 | program object. | |
9037 | ||
9038 | @code{GL_INVALID_OPERATION} is generated if @var{program} has not been | |
9039 | successfully linked. | |
8925f36f | 9040 | |
bb894c9d AW |
9041 | @code{GL_INVALID_OPERATION} is generated if @code{glGetUniformLocation} |
9042 | is executed between the execution of @code{glBegin} and the | |
9043 | corresponding execution of @code{glEnd}. | |
8925f36f | 9044 | |
bb894c9d | 9045 | @end deftypefun |
8925f36f | 9046 | |
bb894c9d | 9047 | @deftypefun void glHint target mode |
3c9b6116 AW |
9048 | Specify implementation-specific hints. |
9049 | ||
8925f36f AW |
9050 | @table @asis |
9051 | @item @var{target} | |
9052 | Specifies a symbolic constant indicating the behavior to be controlled. | |
9053 | @code{GL_FOG_HINT}, @code{GL_GENERATE_MIPMAP_HINT}, | |
9054 | @code{GL_LINE_SMOOTH_HINT}, @code{GL_PERSPECTIVE_CORRECTION_HINT}, | |
9055 | @code{GL_POINT_SMOOTH_HINT}, @code{GL_POLYGON_SMOOTH_HINT}, | |
9056 | @code{GL_TEXTURE_COMPRESSION_HINT}, and | |
9057 | @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT} are accepted. | |
9058 | ||
9059 | @item @var{mode} | |
9060 | Specifies a symbolic constant indicating the desired behavior. | |
9061 | @code{GL_FASTEST}, @code{GL_NICEST}, and @code{GL_DONT_CARE} are | |
9062 | accepted. | |
9063 | ||
9064 | @end table | |
9065 | ||
8925f36f AW |
9066 | Certain aspects of GL behavior, when there is room for interpretation, |
9067 | can be controlled with hints. A hint is specified with two arguments. | |
9068 | @var{target} is a symbolic constant indicating the behavior to be | |
9069 | controlled, and @var{mode} is another symbolic constant indicating the | |
9070 | desired behavior. The initial value for each @var{target} is | |
9071 | @code{GL_DONT_CARE}. @var{mode} can be one of the following: | |
9072 | ||
9073 | @table @asis | |
9074 | @item @code{GL_FASTEST} | |
9075 | ||
9076 | ||
9077 | The most efficient option should be chosen. | |
9078 | ||
9079 | @item @code{GL_NICEST} | |
9080 | ||
9081 | ||
9082 | The most correct, or highest quality, option should be chosen. | |
9083 | ||
9084 | @item @code{GL_DONT_CARE} | |
9085 | ||
9086 | ||
9087 | No preference. | |
9088 | ||
9089 | @end table | |
9090 | ||
9091 | Though the implementation aspects that can be hinted are well defined, | |
9092 | the interpretation of the hints depends on the implementation. The hint | |
9093 | aspects that can be specified with @var{target}, along with suggested | |
9094 | semantics, are as follows: | |
9095 | ||
9096 | @table @asis | |
9097 | @item @code{GL_FOG_HINT} | |
9098 | ||
9099 | ||
9100 | Indicates the accuracy of fog calculation. If per-pixel fog calculation | |
9101 | is not efficiently supported by the GL implementation, hinting | |
9102 | @code{GL_DONT_CARE} or @code{GL_FASTEST} can result in per-vertex | |
9103 | calculation of fog effects. | |
9104 | ||
9105 | @item @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT} | |
9106 | ||
9107 | ||
9108 | Indicates the accuracy of the derivative calculation for the GL shading | |
9109 | language fragment processing built-in functions: @code{dFdx}, | |
9110 | @code{dFdy}, and @code{fwidth}. | |
9111 | ||
9112 | @item @code{GL_GENERATE_MIPMAP_HINT} | |
9113 | ||
9114 | ||
9115 | Indicates the quality of filtering when generating mipmap images. | |
9116 | ||
9117 | @item @code{GL_LINE_SMOOTH_HINT} | |
9118 | ||
9119 | ||
9120 | Indicates the sampling quality of antialiased lines. If a larger filter | |
9121 | function is applied, hinting @code{GL_NICEST} can result in more pixel | |
9122 | fragments being generated during rasterization. | |
9123 | ||
9124 | @item @code{GL_PERSPECTIVE_CORRECTION_HINT} | |
9125 | ||
9126 | ||
9127 | Indicates the quality of color, texture coordinate, and fog coordinate | |
9128 | interpolation. If perspective-corrected parameter interpolation is not | |
9129 | efficiently supported by the GL implementation, hinting | |
9130 | @code{GL_DONT_CARE} or @code{GL_FASTEST} can result in simple linear | |
9131 | interpolation of colors and/or texture coordinates. | |
9132 | ||
9133 | @item @code{GL_POINT_SMOOTH_HINT} | |
9134 | ||
9135 | ||
9136 | Indicates the sampling quality of antialiased points. If a larger filter | |
9137 | function is applied, hinting @code{GL_NICEST} can result in more pixel | |
9138 | fragments being generated during rasterization. | |
9139 | ||
9140 | @item @code{GL_POLYGON_SMOOTH_HINT} | |
9141 | ||
9142 | ||
9143 | Indicates the sampling quality of antialiased polygons. Hinting | |
9144 | @code{GL_NICEST} can result in more pixel fragments being generated | |
9145 | during rasterization, if a larger filter function is applied. | |
9146 | ||
9147 | @item @code{GL_TEXTURE_COMPRESSION_HINT} | |
9148 | ||
9149 | ||
9150 | Indicates the quality and performance of the compressing texture images. | |
9151 | Hinting @code{GL_FASTEST} indicates that texture images should be | |
9152 | compressed as quickly as possible, while @code{GL_NICEST} indicates that | |
9153 | texture images should be compressed with as little image quality loss as | |
9154 | possible. @code{GL_NICEST} should be selected if the texture is to be | |
9155 | retrieved by @code{glGetCompressedTexImage} for reuse. | |
9156 | ||
9157 | @end table | |
9158 | ||
8925f36f AW |
9159 | @code{GL_INVALID_ENUM} is generated if either @var{target} or @var{mode} |
9160 | is not an accepted value. | |
9161 | ||
9162 | @code{GL_INVALID_OPERATION} is generated if @code{glHint} is executed | |
9163 | between the execution of @code{glBegin} and the corresponding execution | |
9164 | of @code{glEnd}. | |
9165 | ||
bb894c9d | 9166 | @end deftypefun |
8925f36f | 9167 | |
bb894c9d | 9168 | @deftypefun void glHistogram target width internalformat sink |
3c9b6116 AW |
9169 | Define histogram table. |
9170 | ||
8925f36f AW |
9171 | @table @asis |
9172 | @item @var{target} | |
9173 | The histogram whose parameters are to be set. Must be one of | |
9174 | @code{GL_HISTOGRAM} or @code{GL_PROXY_HISTOGRAM}. | |
9175 | ||
9176 | @item @var{width} | |
9177 | The number of entries in the histogram table. Must be a power of 2. | |
9178 | ||
9179 | @item @var{internalformat} | |
9180 | The format of entries in the histogram table. Must be one of | |
9181 | @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, | |
9182 | @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
9183 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
9184 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
9185 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
9186 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
9187 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
9188 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
9189 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
9190 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
9191 | @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
9192 | ||
9193 | @item @var{sink} | |
9194 | If @code{GL_TRUE}, pixels will be consumed by the histogramming process | |
9195 | and no drawing or texture loading will take place. If @code{GL_FALSE}, | |
9196 | pixels will proceed to the minmax process after histogramming. | |
9197 | ||
9198 | @end table | |
9199 | ||
8925f36f AW |
9200 | When @code{GL_HISTOGRAM} is enabled, RGBA color components are converted |
9201 | to histogram table indices by clamping to the range [0,1], multiplying | |
9202 | by the width of the histogram table, and rounding to the nearest | |
9203 | integer. The table entries selected by the RGBA indices are then | |
9204 | incremented. (If the internal format of the histogram table includes | |
9205 | luminance, then the index derived from the R color component determines | |
9206 | the luminance table entry to be incremented.) If a histogram table entry | |
9207 | is incremented beyond its maximum value, then its value becomes | |
9208 | undefined. (This is not an error.) | |
9209 | ||
9210 | Histogramming is performed only for RGBA pixels (though these may be | |
9211 | specified originally as color indices and converted to RGBA by index | |
9212 | table lookup). Histogramming is enabled with @code{glEnable} and | |
9213 | disabled with @code{glDisable}. | |
9214 | ||
9215 | When @var{target} is @code{GL_HISTOGRAM}, @code{glHistogram} redefines | |
9216 | the current histogram table to have @var{width} entries of the format | |
9217 | specified by @var{internalformat}. The entries are indexed 0 through | |
3c9b6116 AW |
9218 | @r{@var{width}-1}, and all entries are initialized to zero. The values |
9219 | in the previous histogram table, if any, are lost. If @var{sink} is | |
9220 | @code{GL_TRUE}, then pixels are discarded after histogramming; no | |
8925f36f AW |
9221 | further processing of the pixels takes place, and no drawing, texture |
9222 | loading, or pixel readback will result. | |
9223 | ||
9224 | When @var{target} is @code{GL_PROXY_HISTOGRAM}, @code{glHistogram} | |
9225 | computes all state information as if the histogram table were to be | |
9226 | redefined, but does not actually define the new table. If the requested | |
9227 | histogram table is too large to be supported, then the state information | |
9228 | will be set to zero. This provides a way to determine if a histogram | |
9229 | table with the given parameters can be supported. | |
9230 | ||
9231 | ||
9232 | ||
8925f36f AW |
9233 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
9234 | allowable values. | |
9235 | ||
9236 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
9237 | is not a power of 2. | |
9238 | ||
9239 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
9240 | of the allowable values. | |
9241 | ||
9242 | @code{GL_TABLE_TOO_LARGE} is generated if @var{target} is | |
9243 | @code{GL_HISTOGRAM} and the histogram table specified is too large for | |
9244 | the implementation. | |
9245 | ||
9246 | @code{GL_INVALID_OPERATION} is generated if @code{glHistogram} is | |
9247 | executed between the execution of @code{glBegin} and the corresponding | |
9248 | execution of @code{glEnd}. | |
9249 | ||
bb894c9d | 9250 | @end deftypefun |
8925f36f | 9251 | |
bb894c9d | 9252 | @deftypefun void glIndexMask mask |
3c9b6116 AW |
9253 | Control the writing of individual bits in the color index buffers. |
9254 | ||
8925f36f AW |
9255 | @table @asis |
9256 | @item @var{mask} | |
9257 | Specifies a bit mask to enable and disable the writing of individual | |
9258 | bits in the color index buffers. Initially, the mask is all 1's. | |
9259 | ||
9260 | @end table | |
9261 | ||
8925f36f | 9262 | @code{glIndexMask} controls the writing of individual bits in the color |
3c9b6116 AW |
9263 | index buffers. The least significant @r{@var{n}} bits of @var{mask}, |
9264 | where @r{@var{n}} is the number of bits in a color index buffer, specify | |
9265 | a mask. Where a 1 (one) appears in the mask, it's possible to write to | |
9266 | the corresponding bit in the color index buffer (or buffers). Where a 0 | |
9267 | (zero) appears, the corresponding bit is write-protected. | |
8925f36f AW |
9268 | |
9269 | This mask is used only in color index mode, and it affects only the | |
9270 | buffers currently selected for writing (see @code{glDrawBuffer}). | |
9271 | Initially, all bits are enabled for writing. | |
9272 | ||
8925f36f AW |
9273 | @code{GL_INVALID_OPERATION} is generated if @code{glIndexMask} is |
9274 | executed between the execution of @code{glBegin} and the corresponding | |
9275 | execution of @code{glEnd}. | |
9276 | ||
bb894c9d | 9277 | @end deftypefun |
8925f36f | 9278 | |
bb894c9d | 9279 | @deftypefun void glIndexPointer type stride pointer |
3c9b6116 AW |
9280 | Define an array of color indexes. |
9281 | ||
8925f36f AW |
9282 | @table @asis |
9283 | @item @var{type} | |
9284 | Specifies the data type of each color index in the array. Symbolic | |
9285 | constants @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, @code{GL_INT}, | |
9286 | @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value is | |
9287 | @code{GL_FLOAT}. | |
9288 | ||
9289 | @item @var{stride} | |
9290 | Specifies the byte offset between consecutive color indexes. If | |
9291 | @var{stride} is 0, the color indexes are understood to be tightly packed | |
9292 | in the array. The initial value is 0. | |
9293 | ||
9294 | @item @var{pointer} | |
9295 | Specifies a pointer to the first index in the array. The initial value | |
9296 | is 0. | |
9297 | ||
9298 | @end table | |
9299 | ||
8925f36f AW |
9300 | @code{glIndexPointer} specifies the location and data format of an array |
9301 | of color indexes to use when rendering. @var{type} specifies the data | |
9302 | type of each color index and @var{stride} specifies the byte stride from | |
9303 | one color index to the next, allowing vertices and attributes to be | |
9304 | packed into a single array or stored in separate arrays. | |
9305 | ||
9306 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
9307 | target (see @code{glBindBuffer}) while a color index array is specified, | |
9308 | @var{pointer} is treated as a byte offset into the buffer object's data | |
9309 | store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING}) | |
9310 | is saved as color index vertex array client-side state | |
9311 | (@code{GL_INDEX_ARRAY_BUFFER_BINDING}). | |
9312 | ||
9313 | When a color index array is specified, @var{type}, @var{stride}, and | |
9314 | @var{pointer} are saved as client-side state, in addition to the current | |
9315 | vertex array buffer object binding. | |
9316 | ||
9317 | To enable and disable the color index array, call | |
9318 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
9319 | argument @code{GL_INDEX_ARRAY}. If enabled, the color index array is | |
9320 | used when @code{glDrawArrays}, @code{glMultiDrawArrays}, | |
9321 | @code{glDrawElements}, @code{glMultiDrawElements}, | |
9322 | @code{glDrawRangeElements}, or @code{glArrayElement} is called. | |
9323 | ||
8925f36f AW |
9324 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted |
9325 | value. | |
9326 | ||
9327 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
9328 | ||
bb894c9d | 9329 | @end deftypefun |
8925f36f | 9330 | |
bb894c9d AW |
9331 | @deftypefun void glIndexi c |
9332 | @deftypefunx void glIndexd c | |
9333 | @deftypefunx void glIndexub c | |
3c9b6116 AW |
9334 | Set the current color index. |
9335 | ||
8925f36f AW |
9336 | @table @asis |
9337 | @item @var{c} | |
9338 | Specifies the new value for the current color index. | |
9339 | ||
9340 | ||
9341 | ||
9342 | @end table | |
9343 | ||
8925f36f AW |
9344 | @code{glIndex} updates the current (single-valued) color index. It takes |
9345 | one argument, the new value for the current color index. | |
9346 | ||
9347 | The current index is stored as a floating-point value. Integer values | |
9348 | are converted directly to floating-point values, with no special | |
9349 | mapping. The initial value is 1. | |
9350 | ||
9351 | Index values outside the representable range of the color index buffer | |
9352 | are not clamped. However, before an index is dithered (if enabled) and | |
9353 | written to the frame buffer, it is converted to fixed-point format. Any | |
9354 | bits in the integer portion of the resulting fixed-point value that do | |
9355 | not correspond to bits in the frame buffer are masked out. | |
9356 | ||
bb894c9d | 9357 | @end deftypefun |
8925f36f | 9358 | |
bb894c9d | 9359 | @deftypefun void glInitNames |
3c9b6116 AW |
9360 | Initialize the name stack. |
9361 | ||
8925f36f AW |
9362 | The name stack is used during selection mode to allow sets of rendering |
9363 | commands to be uniquely identified. It consists of an ordered set of | |
9364 | unsigned integers. @code{glInitNames} causes the name stack to be | |
9365 | initialized to its default empty state. | |
9366 | ||
9367 | The name stack is always empty while the render mode is not | |
9368 | @code{GL_SELECT}. Calls to @code{glInitNames} while the render mode is | |
9369 | not @code{GL_SELECT} are ignored. | |
9370 | ||
8925f36f AW |
9371 | @code{GL_INVALID_OPERATION} is generated if @code{glInitNames} is |
9372 | executed between the execution of @code{glBegin} and the corresponding | |
9373 | execution of @code{glEnd}. | |
9374 | ||
bb894c9d | 9375 | @end deftypefun |
8925f36f | 9376 | |
bb894c9d | 9377 | @deftypefun void glInterleavedArrays format stride pointer |
3c9b6116 AW |
9378 | Simultaneously specify and enable several interleaved arrays. |
9379 | ||
8925f36f AW |
9380 | @table @asis |
9381 | @item @var{format} | |
9382 | Specifies the type of array to enable. Symbolic constants @code{GL_V2F}, | |
9383 | @code{GL_V3F}, @code{GL_C4UB_V2F}, @code{GL_C4UB_V3F}, | |
9384 | @code{GL_C3F_V3F}, @code{GL_N3F_V3F}, @code{GL_C4F_N3F_V3F}, | |
9385 | @code{GL_T2F_V3F}, @code{GL_T4F_V4F}, @code{GL_T2F_C4UB_V3F}, | |
9386 | @code{GL_T2F_C3F_V3F}, @code{GL_T2F_N3F_V3F}, @code{GL_T2F_C4F_N3F_V3F}, | |
9387 | and @code{GL_T4F_C4F_N3F_V4F} are accepted. | |
9388 | ||
9389 | @item @var{stride} | |
9390 | Specifies the offset in bytes between each aggregate array element. | |
9391 | ||
9392 | @end table | |
9393 | ||
8925f36f AW |
9394 | @code{glInterleavedArrays} lets you specify and enable individual color, |
9395 | normal, texture and vertex arrays whose elements are part of a larger | |
9396 | aggregate array element. For some implementations, this is more | |
9397 | efficient than specifying the arrays separately. | |
9398 | ||
9399 | If @var{stride} is 0, the aggregate elements are stored consecutively. | |
9400 | Otherwise, @var{stride} bytes occur between the beginning of one | |
9401 | aggregate array element and the beginning of the next aggregate array | |
9402 | element. | |
9403 | ||
9404 | @var{format} serves as a ``key'' describing the extraction of individual | |
9405 | arrays from the aggregate array. If @var{format} contains a T, then | |
9406 | texture coordinates are extracted from the interleaved array. If C is | |
9407 | present, color values are extracted. If N is present, normal coordinates | |
9408 | are extracted. Vertex coordinates are always extracted. | |
9409 | ||
9410 | The digits 2, 3, and 4 denote how many values are extracted. F indicates | |
9411 | that values are extracted as floating-point values. Colors may also be | |
9412 | extracted as 4 unsigned bytes if 4UB follows the C. If a color is | |
9413 | extracted as 4 unsigned bytes, the vertex array element which follows is | |
9414 | located at the first possible floating-point aligned address. | |
9415 | ||
8925f36f AW |
9416 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted |
9417 | value. | |
9418 | ||
9419 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
9420 | ||
bb894c9d | 9421 | @end deftypefun |
8925f36f | 9422 | |
bb894c9d | 9423 | @deftypefun GLboolean glIsBuffer buffer |
3c9b6116 AW |
9424 | Determine if a name corresponds to a buffer object. |
9425 | ||
8925f36f AW |
9426 | @table @asis |
9427 | @item @var{buffer} | |
9428 | Specifies a value that may be the name of a buffer object. | |
9429 | ||
9430 | @end table | |
9431 | ||
8925f36f AW |
9432 | @code{glIsBuffer} returns @code{GL_TRUE} if @var{buffer} is currently |
9433 | the name of a buffer object. If @var{buffer} is zero, or is a non-zero | |
9434 | value that is not currently the name of a buffer object, or if an error | |
9435 | occurs, @code{glIsBuffer} returns @code{GL_FALSE}. | |
9436 | ||
9437 | A name returned by @code{glGenBuffers}, but not yet associated with a | |
9438 | buffer object by calling @code{glBindBuffer}, is not the name of a | |
9439 | buffer object. | |
9440 | ||
8925f36f AW |
9441 | @code{GL_INVALID_OPERATION} is generated if @code{glIsBuffer} is |
9442 | executed between the execution of @code{glBegin} and the corresponding | |
9443 | execution of @code{glEnd}. | |
9444 | ||
bb894c9d | 9445 | @end deftypefun |
8925f36f | 9446 | |
bb894c9d | 9447 | @deftypefun GLboolean glIsEnabled cap |
3c9b6116 AW |
9448 | Test whether a capability is enabled. |
9449 | ||
8925f36f AW |
9450 | @table @asis |
9451 | @item @var{cap} | |
9452 | Specifies a symbolic constant indicating a GL capability. | |
9453 | ||
9454 | @end table | |
9455 | ||
8925f36f AW |
9456 | @code{glIsEnabled} returns @code{GL_TRUE} if @var{cap} is an enabled |
9457 | capability and returns @code{GL_FALSE} otherwise. Initially all | |
9458 | capabilities except @code{GL_DITHER} are disabled; @code{GL_DITHER} is | |
9459 | initially enabled. | |
9460 | ||
9461 | The following capabilities are accepted for @var{cap}: | |
9462 | ||
9463 | ||
9464 | ||
9465 | @table @asis | |
9466 | @item @strong{Constant} | |
9467 | @strong{See} | |
9468 | ||
9469 | @item @code{GL_ALPHA_TEST} | |
9470 | @code{glAlphaFunc} | |
9471 | ||
9472 | @item @code{GL_AUTO_NORMAL} | |
9473 | @code{glEvalCoord} | |
9474 | ||
9475 | @item @code{GL_BLEND} | |
9476 | @code{glBlendFunc}, @code{glLogicOp} | |
9477 | ||
9478 | @item @code{GL_CLIP_PLANE}@var{i} | |
9479 | @code{glClipPlane} | |
9480 | ||
9481 | @item @code{GL_COLOR_ARRAY} | |
9482 | @code{glColorPointer} | |
9483 | ||
9484 | @item @code{GL_COLOR_LOGIC_OP} | |
9485 | @code{glLogicOp} | |
9486 | ||
9487 | @item @code{GL_COLOR_MATERIAL} | |
9488 | @code{glColorMaterial} | |
9489 | ||
9490 | @item @code{GL_COLOR_SUM} | |
9491 | @code{glSecondaryColor} | |
9492 | ||
9493 | @item @code{GL_COLOR_TABLE} | |
9494 | @code{glColorTable} | |
9495 | ||
9496 | @item @code{GL_CONVOLUTION_1D} | |
9497 | @code{glConvolutionFilter1D} | |
9498 | ||
9499 | @item @code{GL_CONVOLUTION_2D} | |
9500 | @code{glConvolutionFilter2D} | |
9501 | ||
9502 | @item @code{GL_CULL_FACE} | |
9503 | @code{glCullFace} | |
9504 | ||
9505 | @item @code{GL_DEPTH_TEST} | |
9506 | @code{glDepthFunc}, @code{glDepthRange} | |
9507 | ||
9508 | @item @code{GL_DITHER} | |
9509 | @code{glEnable} | |
9510 | ||
9511 | @item @code{GL_EDGE_FLAG_ARRAY} | |
9512 | @code{glEdgeFlagPointer} | |
9513 | ||
9514 | @item @code{GL_FOG} | |
9515 | @code{glFog} | |
9516 | ||
9517 | @item @code{GL_FOG_COORD_ARRAY} | |
9518 | @code{glFogCoordPointer} | |
9519 | ||
9520 | @item @code{GL_HISTOGRAM} | |
9521 | @code{glHistogram} | |
9522 | ||
9523 | @item @code{GL_INDEX_ARRAY} | |
9524 | @code{glIndexPointer} | |
9525 | ||
9526 | @item @code{GL_INDEX_LOGIC_OP} | |
9527 | @code{glLogicOp} | |
9528 | ||
9529 | @item @code{GL_LIGHT}@var{i} | |
9530 | @code{glLightModel}, @code{glLight} | |
9531 | ||
9532 | @item @code{GL_LIGHTING} | |
9533 | @code{glMaterial}, @code{glLightModel}, @code{glLight} | |
9534 | ||
9535 | @item @code{GL_LINE_SMOOTH} | |
9536 | @code{glLineWidth} | |
9537 | ||
9538 | @item @code{GL_LINE_STIPPLE} | |
9539 | @code{glLineStipple} | |
9540 | ||
9541 | @item @code{GL_MAP1_COLOR_4} | |
9542 | @code{glMap1} | |
9543 | ||
9544 | @item @code{GL_MAP1_INDEX} | |
9545 | @code{glMap1} | |
9546 | ||
9547 | @item @code{GL_MAP1_NORMAL} | |
9548 | @code{glMap1} | |
9549 | ||
9550 | @item @code{GL_MAP1_TEXTURE_COORD_1} | |
9551 | @code{glMap1} | |
9552 | ||
9553 | @item @code{GL_MAP1_TEXTURE_COORD_2} | |
9554 | @code{glMap1} | |
9555 | ||
9556 | @item @code{GL_MAP1_TEXTURE_COORD_3} | |
9557 | @code{glMap1} | |
9558 | ||
9559 | @item @code{GL_MAP1_TEXTURE_COORD_4} | |
9560 | @code{glMap1} | |
9561 | ||
9562 | @item @code{GL_MAP2_COLOR_4} | |
9563 | @code{glMap2} | |
9564 | ||
9565 | @item @code{GL_MAP2_INDEX} | |
9566 | @code{glMap2} | |
9567 | ||
9568 | @item @code{GL_MAP2_NORMAL} | |
9569 | @code{glMap2} | |
9570 | ||
9571 | @item @code{GL_MAP2_TEXTURE_COORD_1} | |
9572 | @code{glMap2} | |
9573 | ||
9574 | @item @code{GL_MAP2_TEXTURE_COORD_2} | |
9575 | @code{glMap2} | |
9576 | ||
9577 | @item @code{GL_MAP2_TEXTURE_COORD_3} | |
9578 | @code{glMap2} | |
9579 | ||
9580 | @item @code{GL_MAP2_TEXTURE_COORD_4} | |
9581 | @code{glMap2} | |
9582 | ||
9583 | @item @code{GL_MAP2_VERTEX_3} | |
9584 | @code{glMap2} | |
9585 | ||
9586 | @item @code{GL_MAP2_VERTEX_4} | |
9587 | @code{glMap2} | |
9588 | ||
9589 | @item @code{GL_MINMAX} | |
9590 | @code{glMinmax} | |
9591 | ||
9592 | @item @code{GL_MULTISAMPLE} | |
9593 | @code{glSampleCoverage} | |
9594 | ||
9595 | @item @code{GL_NORMAL_ARRAY} | |
9596 | @code{glNormalPointer} | |
9597 | ||
9598 | @item @code{GL_NORMALIZE} | |
9599 | @code{glNormal} | |
9600 | ||
9601 | @item @code{GL_POINT_SMOOTH} | |
9602 | @code{glPointSize} | |
9603 | ||
9604 | @item @code{GL_POINT_SPRITE} | |
9605 | @code{glEnable} | |
9606 | ||
9607 | @item @code{GL_POLYGON_SMOOTH} | |
9608 | @code{glPolygonMode} | |
9609 | ||
9610 | @item @code{GL_POLYGON_OFFSET_FILL} | |
9611 | @code{glPolygonOffset} | |
9612 | ||
9613 | @item @code{GL_POLYGON_OFFSET_LINE} | |
9614 | @code{glPolygonOffset} | |
9615 | ||
9616 | @item @code{GL_POLYGON_OFFSET_POINT} | |
9617 | @code{glPolygonOffset} | |
9618 | ||
9619 | @item @code{GL_POLYGON_STIPPLE} | |
9620 | @code{glPolygonStipple} | |
9621 | ||
9622 | @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} | |
9623 | @code{glColorTable} | |
9624 | ||
9625 | @item @code{GL_POST_CONVOLUTION_COLOR_TABLE} | |
9626 | @code{glColorTable} | |
9627 | ||
9628 | @item @code{GL_RESCALE_NORMAL} | |
9629 | @code{glNormal} | |
9630 | ||
9631 | @item @code{GL_SAMPLE_ALPHA_TO_COVERAGE} | |
9632 | @code{glSampleCoverage} | |
9633 | ||
9634 | @item @code{GL_SAMPLE_ALPHA_TO_ONE} | |
9635 | @code{glSampleCoverage} | |
9636 | ||
9637 | @item @code{GL_SAMPLE_COVERAGE} | |
9638 | @code{glSampleCoverage} | |
9639 | ||
9640 | @item @code{GL_SCISSOR_TEST} | |
9641 | @code{glScissor} | |
9642 | ||
9643 | @item @code{GL_SECONDARY_COLOR_ARRAY} | |
9644 | @code{glSecondaryColorPointer} | |
9645 | ||
9646 | @item @code{GL_SEPARABLE_2D} | |
9647 | @code{glSeparableFilter2D} | |
9648 | ||
9649 | @item @code{GL_STENCIL_TEST} | |
9650 | @code{glStencilFunc}, @code{glStencilOp} | |
9651 | ||
9652 | @item @code{GL_TEXTURE_1D} | |
9653 | @code{glTexImage1D} | |
9654 | ||
9655 | @item @code{GL_TEXTURE_2D} | |
9656 | @code{glTexImage2D} | |
9657 | ||
9658 | @item @code{GL_TEXTURE_3D} | |
9659 | @code{glTexImage3D} | |
9660 | ||
9661 | @item @code{GL_TEXTURE_COORD_ARRAY} | |
9662 | @code{glTexCoordPointer} | |
9663 | ||
9664 | @item @code{GL_TEXTURE_CUBE_MAP} | |
9665 | @code{glTexImage2D} | |
9666 | ||
9667 | @item @code{GL_TEXTURE_GEN_Q} | |
9668 | @code{glTexGen} | |
9669 | ||
9670 | @item @code{GL_TEXTURE_GEN_R} | |
9671 | @code{glTexGen} | |
9672 | ||
9673 | @item @code{GL_TEXTURE_GEN_S} | |
9674 | @code{glTexGen} | |
9675 | ||
9676 | @item @code{GL_TEXTURE_GEN_T} | |
9677 | @code{glTexGen} | |
9678 | ||
9679 | @item @code{GL_VERTEX_ARRAY} | |
9680 | @code{glVertexPointer} | |
9681 | ||
9682 | @item @code{GL_VERTEX_PROGRAM_POINT_SIZE} | |
9683 | @code{glEnable} | |
9684 | ||
9685 | @item @code{GL_VERTEX_PROGRAM_TWO_SIDE} | |
9686 | @code{glEnable} | |
9687 | ||
9688 | @end table | |
9689 | ||
9690 | ||
9691 | ||
8925f36f AW |
9692 | @code{GL_INVALID_ENUM} is generated if @var{cap} is not an accepted |
9693 | value. | |
9694 | ||
9695 | @code{GL_INVALID_OPERATION} is generated if @code{glIsEnabled} is | |
9696 | executed between the execution of @code{glBegin} and the corresponding | |
9697 | execution of @code{glEnd}. | |
9698 | ||
bb894c9d | 9699 | @end deftypefun |
8925f36f | 9700 | |
bb894c9d | 9701 | @deftypefun GLboolean glIsList list |
3c9b6116 AW |
9702 | Determine if a name corresponds to a display list. |
9703 | ||
8925f36f AW |
9704 | @table @asis |
9705 | @item @var{list} | |
9706 | Specifies a potential display list name. | |
9707 | ||
9708 | @end table | |
9709 | ||
8925f36f AW |
9710 | @code{glIsList} returns @code{GL_TRUE} if @var{list} is the name of a |
9711 | display list and returns @code{GL_FALSE} if it is not, or if an error | |
9712 | occurs. | |
9713 | ||
9714 | A name returned by @code{glGenLists}, but not yet associated with a | |
9715 | display list by calling @code{glNewList}, is not the name of a display | |
9716 | list. | |
9717 | ||
8925f36f AW |
9718 | @code{GL_INVALID_OPERATION} is generated if @code{glIsList} is executed |
9719 | between the execution of @code{glBegin} and the corresponding execution | |
9720 | of @code{glEnd}. | |
9721 | ||
bb894c9d | 9722 | @end deftypefun |
8925f36f | 9723 | |
bb894c9d | 9724 | @deftypefun GLboolean glIsProgram program |
3c9b6116 AW |
9725 | Determines if a name corresponds to a program object. |
9726 | ||
8925f36f AW |
9727 | @table @asis |
9728 | @item @var{program} | |
9729 | Specifies a potential program object. | |
9730 | ||
9731 | @end table | |
9732 | ||
8925f36f AW |
9733 | @code{glIsProgram} returns @code{GL_TRUE} if @var{program} is the name |
9734 | of a program object previously created with @code{glCreateProgram} and | |
9735 | not yet deleted with @code{glDeleteProgram}. If @var{program} is zero or | |
9736 | a non-zero value that is not the name of a program object, or if an | |
9737 | error occurs, @code{glIsProgram} returns @code{GL_FALSE}. | |
9738 | ||
8925f36f AW |
9739 | @code{GL_INVALID_OPERATION} is generated if @code{glIsProgram} is |
9740 | executed between the execution of @code{glBegin} and the corresponding | |
9741 | execution of @code{glEnd}. | |
9742 | ||
bb894c9d | 9743 | @end deftypefun |
8925f36f | 9744 | |
bb894c9d | 9745 | @deftypefun GLboolean glIsQuery id |
3c9b6116 AW |
9746 | Determine if a name corresponds to a query object. |
9747 | ||
8925f36f AW |
9748 | @table @asis |
9749 | @item @var{id} | |
9750 | Specifies a value that may be the name of a query object. | |
9751 | ||
9752 | @end table | |
9753 | ||
8925f36f AW |
9754 | @code{glIsQuery} returns @code{GL_TRUE} if @var{id} is currently the |
9755 | name of a query object. If @var{id} is zero, or is a non-zero value that | |
9756 | is not currently the name of a query object, or if an error occurs, | |
9757 | @code{glIsQuery} returns @code{GL_FALSE}. | |
9758 | ||
9759 | A name returned by @code{glGenQueries}, but not yet associated with a | |
9760 | query object by calling @code{glBeginQuery}, is not the name of a query | |
9761 | object. | |
9762 | ||
8925f36f AW |
9763 | @code{GL_INVALID_OPERATION} is generated if @code{glIsQuery} is executed |
9764 | between the execution of @code{glBegin} and the corresponding execution | |
9765 | of @code{glEnd}. | |
9766 | ||
bb894c9d | 9767 | @end deftypefun |
8925f36f | 9768 | |
bb894c9d | 9769 | @deftypefun GLboolean glIsShader shader |
3c9b6116 AW |
9770 | Determines if a name corresponds to a shader object. |
9771 | ||
8925f36f AW |
9772 | @table @asis |
9773 | @item @var{shader} | |
9774 | Specifies a potential shader object. | |
9775 | ||
9776 | @end table | |
9777 | ||
8925f36f AW |
9778 | @code{glIsShader} returns @code{GL_TRUE} if @var{shader} is the name of |
9779 | a shader object previously created with @code{glCreateShader} and not | |
9780 | yet deleted with @code{glDeleteShader}. If @var{shader} is zero or a | |
9781 | non-zero value that is not the name of a shader object, or if an error | |
9782 | occurs, @code{glIsShader } returns @code{GL_FALSE}. | |
9783 | ||
8925f36f AW |
9784 | @code{GL_INVALID_OPERATION} is generated if @code{glIsShader} is |
9785 | executed between the execution of @code{glBegin} and the corresponding | |
9786 | execution of @code{glEnd}. | |
9787 | ||
bb894c9d | 9788 | @end deftypefun |
8925f36f | 9789 | |
bb894c9d | 9790 | @deftypefun GLboolean glIsTexture texture |
3c9b6116 AW |
9791 | Determine if a name corresponds to a texture. |
9792 | ||
8925f36f AW |
9793 | @table @asis |
9794 | @item @var{texture} | |
9795 | Specifies a value that may be the name of a texture. | |
9796 | ||
9797 | @end table | |
9798 | ||
8925f36f AW |
9799 | @code{glIsTexture} returns @code{GL_TRUE} if @var{texture} is currently |
9800 | the name of a texture. If @var{texture} is zero, or is a non-zero value | |
9801 | that is not currently the name of a texture, or if an error occurs, | |
9802 | @code{glIsTexture} returns @code{GL_FALSE}. | |
9803 | ||
9804 | A name returned by @code{glGenTextures}, but not yet associated with a | |
9805 | texture by calling @code{glBindTexture}, is not the name of a texture. | |
9806 | ||
8925f36f AW |
9807 | @code{GL_INVALID_OPERATION} is generated if @code{glIsTexture} is |
9808 | executed between the execution of @code{glBegin} and the corresponding | |
9809 | execution of @code{glEnd}. | |
9810 | ||
bb894c9d | 9811 | @end deftypefun |
8925f36f | 9812 | |
bb894c9d AW |
9813 | @deftypefun void glLightModelf pname param |
9814 | @deftypefunx void glLightModeli pname param | |
3c9b6116 AW |
9815 | Set the lighting model parameters. |
9816 | ||
8925f36f AW |
9817 | @table @asis |
9818 | @item @var{pname} | |
9819 | Specifies a single-valued lighting model parameter. | |
9820 | @code{GL_LIGHT_MODEL_LOCAL_VIEWER}, @code{GL_LIGHT_MODEL_COLOR_CONTROL}, | |
9821 | and @code{GL_LIGHT_MODEL_TWO_SIDE} are accepted. | |
9822 | ||
9823 | @item @var{param} | |
9824 | Specifies the value that @var{param} will be set to. | |
9825 | ||
9826 | @end table | |
9827 | ||
8925f36f AW |
9828 | @code{glLightModel} sets the lighting model parameter. @var{pname} names |
9829 | a parameter and @var{params} gives the new value. There are three | |
9830 | lighting model parameters: | |
9831 | ||
9832 | @table @asis | |
9833 | @item @code{GL_LIGHT_MODEL_AMBIENT} | |
9834 | ||
9835 | ||
9836 | @var{params} contains four integer or floating-point values that specify | |
9837 | the ambient RGBA intensity of the entire scene. Integer values are | |
9838 | mapped linearly such that the most positive representable value maps to | |
3c9b6116 | 9839 | 1.0, and the most negative representable value maps to @r{-1.0}. |
8925f36f AW |
9840 | Floating-point values are mapped directly. Neither integer nor |
9841 | floating-point values are clamped. The initial ambient scene intensity | |
9842 | is (0.2, 0.2, 0.2, 1.0). | |
9843 | ||
9844 | @item @code{GL_LIGHT_MODEL_COLOR_CONTROL} | |
9845 | ||
9846 | ||
9847 | @var{params} must be either @code{GL_SEPARATE_SPECULAR_COLOR} or | |
9848 | @code{GL_SINGLE_COLOR}. @code{GL_SINGLE_COLOR} specifies that a single | |
9849 | color is generated from the lighting computation for a vertex. | |
9850 | @code{GL_SEPARATE_SPECULAR_COLOR} specifies that the specular color | |
9851 | computation of lighting be stored separately from the remainder of the | |
9852 | lighting computation. The specular color is summed into the generated | |
9853 | fragment's color after the application of texture mapping (if enabled). | |
9854 | The initial value is @code{GL_SINGLE_COLOR}. | |
9855 | ||
9856 | @item @code{GL_LIGHT_MODEL_LOCAL_VIEWER} | |
9857 | ||
9858 | ||
9859 | @var{params} is a single integer or floating-point value that specifies | |
9860 | how specular reflection angles are computed. If @var{params} is 0 (or | |
9861 | 0.0), specular reflection angles take the view direction to be parallel | |
9862 | to and in the direction of the -@var{z} axis, regardless of the location | |
9863 | of the vertex in eye coordinates. Otherwise, specular reflections are | |
9864 | computed from the origin of the eye coordinate system. The initial value | |
9865 | is 0. | |
9866 | ||
9867 | @item @code{GL_LIGHT_MODEL_TWO_SIDE} | |
9868 | ||
9869 | ||
9870 | @var{params} is a single integer or floating-point value that specifies | |
9871 | whether one- or two-sided lighting calculations are done for polygons. | |
9872 | It has no effect on the lighting calculations for points, lines, or | |
9873 | bitmaps. If @var{params} is 0 (or 0.0), one-sided lighting is specified, | |
9874 | and only the @var{front} material parameters are used in the lighting | |
9875 | equation. Otherwise, two-sided lighting is specified. In this case, | |
9876 | vertices of back-facing polygons are lighted using the @var{back} | |
9877 | material parameters and have their normals reversed before the lighting | |
9878 | equation is evaluated. Vertices of front-facing polygons are always | |
9879 | lighted using the @var{front} material parameters, with no change to | |
9880 | their normals. The initial value is 0. | |
9881 | ||
9882 | @end table | |
9883 | ||
9884 | In RGBA mode, the lighted color of a vertex is the sum of the material | |
9885 | emission intensity, the product of the material ambient reflectance and | |
9886 | the lighting model full-scene ambient intensity, and the contribution of | |
9887 | each enabled light source. Each light source contributes the sum of | |
9888 | three terms: ambient, diffuse, and specular. The ambient light source | |
9889 | contribution is the product of the material ambient reflectance and the | |
9890 | light's ambient intensity. The diffuse light source contribution is the | |
9891 | product of the material diffuse reflectance, the light's diffuse | |
9892 | intensity, and the dot product of the vertex's normal with the | |
9893 | normalized vector from the vertex to the light source. The specular | |
9894 | light source contribution is the product of the material specular | |
9895 | reflectance, the light's specular intensity, and the dot product of the | |
9896 | normalized vertex-to-eye and vertex-to-light vectors, raised to the | |
9897 | power of the shininess of the material. All three light source | |
9898 | contributions are attenuated equally based on the distance from the | |
9899 | vertex to the light source and on light source direction, spread | |
9900 | exponent, and spread cutoff angle. All dot products are replaced with 0 | |
9901 | if they evaluate to a negative value. | |
9902 | ||
9903 | The alpha component of the resulting lighted color is set to the alpha | |
9904 | value of the material diffuse reflectance. | |
9905 | ||
9906 | In color index mode, the value of the lighted index of a vertex ranges | |
9907 | from the ambient to the specular values passed to @code{glMaterial} | |
9908 | using @code{GL_COLOR_INDEXES}. Diffuse and specular coefficients, | |
9909 | computed with a (.30, .59, .11) weighting of the lights' colors, the | |
9910 | shininess of the material, and the same reflection and attenuation | |
9911 | equations as in the RGBA case, determine how much above ambient the | |
9912 | resulting index is. | |
9913 | ||
8925f36f AW |
9914 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted |
9915 | value. | |
9916 | ||
9917 | @code{GL_INVALID_ENUM} is generated if @var{pname} is | |
9918 | @code{GL_LIGHT_MODEL_COLOR_CONTROL} and @var{params} is not one of | |
9919 | @code{GL_SINGLE_COLOR} or @code{GL_SEPARATE_SPECULAR_COLOR}. | |
9920 | ||
9921 | @code{GL_INVALID_OPERATION} is generated if @code{glLightModel} is | |
9922 | executed between the execution of @code{glBegin} and the corresponding | |
9923 | execution of @code{glEnd}. | |
9924 | ||
bb894c9d | 9925 | @end deftypefun |
8925f36f | 9926 | |
bb894c9d AW |
9927 | @deftypefun void glLightf light pname param |
9928 | @deftypefunx void glLighti light pname param | |
3c9b6116 AW |
9929 | Set light source parameters. |
9930 | ||
8925f36f AW |
9931 | @table @asis |
9932 | @item @var{light} | |
9933 | Specifies a light. The number of lights depends on the implementation, | |
9934 | but at least eight lights are supported. They are identified by symbolic | |
3c9b6116 AW |
9935 | names of the form @code{GL_LIGHT}@r{@var{i}}, where i ranges from 0 to |
9936 | the value of @code{GL_MAX_LIGHTS} - 1. | |
8925f36f AW |
9937 | |
9938 | @item @var{pname} | |
9939 | Specifies a single-valued light source parameter for @var{light}. | |
9940 | @code{GL_SPOT_EXPONENT}, @code{GL_SPOT_CUTOFF}, | |
9941 | @code{GL_CONSTANT_ATTENUATION}, @code{GL_LINEAR_ATTENUATION}, and | |
9942 | @code{GL_QUADRATIC_ATTENUATION} are accepted. | |
9943 | ||
9944 | @item @var{param} | |
9945 | Specifies the value that parameter @var{pname} of light source | |
9946 | @var{light} will be set to. | |
9947 | ||
9948 | @end table | |
9949 | ||
8925f36f AW |
9950 | @code{glLight} sets the values of individual light source parameters. |
9951 | @var{light} names the light and is a symbolic name of the form | |
3c9b6116 | 9952 | @code{GL_LIGHT}@r{@var{i}}, where i ranges from 0 to the value of |
8925f36f AW |
9953 | @code{GL_MAX_LIGHTS} - 1. @var{pname} specifies one of ten light source |
9954 | parameters, again by symbolic name. @var{params} is either a single | |
9955 | value or a pointer to an array that contains the new values. | |
9956 | ||
9957 | To enable and disable lighting calculation, call @code{glEnable} and | |
9958 | @code{glDisable} with argument @code{GL_LIGHTING}. Lighting is initially | |
9959 | disabled. When it is enabled, light sources that are enabled contribute | |
3c9b6116 | 9960 | to the lighting calculation. Light source @r{@var{i}} is enabled and |
8925f36f | 9961 | disabled using @code{glEnable} and @code{glDisable} with argument |
3c9b6116 | 9962 | @code{GL_LIGHT}@r{@var{i}}. |
8925f36f AW |
9963 | |
9964 | The ten light parameters are as follows: | |
9965 | ||
9966 | @table @asis | |
9967 | @item @code{GL_AMBIENT} | |
9968 | @var{params} contains four integer or floating-point values that specify | |
9969 | the ambient RGBA intensity of the light. Integer values are mapped | |
9970 | linearly such that the most positive representable value maps to 1.0, | |
3c9b6116 | 9971 | and the most negative representable value maps to @r{-1.0}. |
8925f36f AW |
9972 | Floating-point values are mapped directly. Neither integer nor |
9973 | floating-point values are clamped. The initial ambient light intensity | |
9974 | is (0, 0, 0, 1). | |
9975 | ||
9976 | @item @code{GL_DIFFUSE} | |
9977 | @var{params} contains four integer or floating-point values that specify | |
9978 | the diffuse RGBA intensity of the light. Integer values are mapped | |
9979 | linearly such that the most positive representable value maps to 1.0, | |
3c9b6116 | 9980 | and the most negative representable value maps to @r{-1.0}. |
8925f36f AW |
9981 | Floating-point values are mapped directly. Neither integer nor |
9982 | floating-point values are clamped. The initial value for | |
9983 | @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial value is | |
9984 | (0, 0, 0, 1). | |
9985 | ||
9986 | @item @code{GL_SPECULAR} | |
9987 | @var{params} contains four integer or floating-point values that specify | |
9988 | the specular RGBA intensity of the light. Integer values are mapped | |
9989 | linearly such that the most positive representable value maps to 1.0, | |
3c9b6116 | 9990 | and the most negative representable value maps to @r{-1.0}. |
8925f36f AW |
9991 | Floating-point values are mapped directly. Neither integer nor |
9992 | floating-point values are clamped. The initial value for | |
9993 | @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial value is | |
9994 | (0, 0, 0, 1). | |
9995 | ||
9996 | @item @code{GL_POSITION} | |
9997 | @var{params} contains four integer or floating-point values that specify | |
9998 | the position of the light in homogeneous object coordinates. Both | |
9999 | integer and floating-point values are mapped directly. Neither integer | |
10000 | nor floating-point values are clamped. | |
10001 | ||
10002 | The position is transformed by the modelview matrix when @code{glLight} | |
10003 | is called (just as if it were a point), and it is stored in eye | |
3c9b6116 | 10004 | coordinates. If the @r{@var{w}} component of the position is 0, the |
8925f36f AW |
10005 | light is treated as a directional source. Diffuse and specular lighting |
10006 | calculations take the light's direction, but not its actual position, | |
10007 | into account, and attenuation is disabled. Otherwise, diffuse and | |
10008 | specular lighting calculations are based on the actual location of the | |
10009 | light in eye coordinates, and attenuation is enabled. The initial | |
10010 | position is (0, 0, 1, 0); thus, the initial light source is directional, | |
3c9b6116 | 10011 | parallel to, and in the direction of the @r{-@var{z}} axis. |
8925f36f AW |
10012 | |
10013 | @item @code{GL_SPOT_DIRECTION} | |
10014 | @var{params} contains three integer or floating-point values that | |
10015 | specify the direction of the light in homogeneous object coordinates. | |
10016 | Both integer and floating-point values are mapped directly. Neither | |
10017 | integer nor floating-point values are clamped. | |
10018 | ||
10019 | The spot direction is transformed by the upper 3x3 of the modelview | |
10020 | matrix when @code{glLight} is called, and it is stored in eye | |
10021 | coordinates. It is significant only when @code{GL_SPOT_CUTOFF} is not | |
3c9b6116 | 10022 | 180, which it is initially. The initial direction is @r{(0,0-1)}. |
8925f36f AW |
10023 | |
10024 | @item @code{GL_SPOT_EXPONENT} | |
10025 | @var{params} is a single integer or floating-point value that specifies | |
10026 | the intensity distribution of the light. Integer and floating-point | |
3c9b6116 | 10027 | values are mapped directly. Only values in the range @r{[0,128]} are |
8925f36f AW |
10028 | accepted. |
10029 | ||
10030 | Effective light intensity is attenuated by the cosine of the angle | |
10031 | between the direction of the light and the direction from the light to | |
10032 | the vertex being lighted, raised to the power of the spot exponent. | |
10033 | Thus, higher spot exponents result in a more focused light source, | |
10034 | regardless of the spot cutoff angle (see @code{GL_SPOT_CUTOFF}, next | |
10035 | paragraph). The initial spot exponent is 0, resulting in uniform light | |
10036 | distribution. | |
10037 | ||
10038 | @item @code{GL_SPOT_CUTOFF} | |
10039 | @var{params} is a single integer or floating-point value that specifies | |
10040 | the maximum spread angle of a light source. Integer and floating-point | |
3c9b6116 AW |
10041 | values are mapped directly. Only values in the range @r{[0,90]} and the |
10042 | special value 180 are accepted. If the angle between the direction of | |
10043 | the light and the direction from the light to the vertex being lighted | |
10044 | is greater than the spot cutoff angle, the light is completely masked. | |
10045 | Otherwise, its intensity is controlled by the spot exponent and the | |
10046 | attenuation factors. The initial spot cutoff is 180, resulting in | |
8925f36f AW |
10047 | uniform light distribution. |
10048 | ||
10049 | @item @code{GL_CONSTANT_ATTENUATION} | |
10050 | @item @code{GL_LINEAR_ATTENUATION} | |
10051 | @item @code{GL_QUADRATIC_ATTENUATION} | |
10052 | @var{params} is a single integer or floating-point value that specifies | |
10053 | one of the three light attenuation factors. Integer and floating-point | |
10054 | values are mapped directly. Only nonnegative values are accepted. If the | |
10055 | light is positional, rather than directional, its intensity is | |
10056 | attenuated by the reciprocal of the sum of the constant factor, the | |
10057 | linear factor times the distance between the light and the vertex being | |
10058 | lighted, and the quadratic factor times the square of the same distance. | |
10059 | The initial attenuation factors are (1, 0, 0), resulting in no | |
10060 | attenuation. | |
10061 | ||
10062 | @end table | |
10063 | ||
8925f36f AW |
10064 | @code{GL_INVALID_ENUM} is generated if either @var{light} or @var{pname} |
10065 | is not an accepted value. | |
10066 | ||
10067 | @code{GL_INVALID_VALUE} is generated if a spot exponent value is | |
3c9b6116 AW |
10068 | specified outside the range @r{[0,128]}, or if spot cutoff is specified |
10069 | outside the range @r{[0,90]} (except for the special value 180), or if a | |
10070 | negative attenuation factor is specified. | |
8925f36f AW |
10071 | |
10072 | @code{GL_INVALID_OPERATION} is generated if @code{glLight} is executed | |
10073 | between the execution of @code{glBegin} and the corresponding execution | |
10074 | of @code{glEnd}. | |
10075 | ||
bb894c9d | 10076 | @end deftypefun |
8925f36f | 10077 | |
bb894c9d | 10078 | @deftypefun void glLineStipple factor pattern |
3c9b6116 AW |
10079 | Specify the line stipple pattern. |
10080 | ||
8925f36f AW |
10081 | @table @asis |
10082 | @item @var{factor} | |
10083 | Specifies a multiplier for each bit in the line stipple pattern. If | |
10084 | @var{factor} is 3, for example, each bit in the pattern is used three | |
10085 | times before the next bit in the pattern is used. @var{factor} is | |
10086 | clamped to the range [1, 256] and defaults to 1. | |
10087 | ||
10088 | @item @var{pattern} | |
10089 | Specifies a 16-bit integer whose bit pattern determines which fragments | |
10090 | of a line will be drawn when the line is rasterized. Bit zero is used | |
10091 | first; the default pattern is all 1's. | |
10092 | ||
10093 | @end table | |
10094 | ||
8925f36f AW |
10095 | Line stippling masks out certain fragments produced by rasterization; |
10096 | those fragments will not be drawn. The masking is achieved by using | |
10097 | three parameters: the 16-bit line stipple pattern @var{pattern}, the | |
3c9b6116 | 10098 | repeat count @var{factor}, and an integer stipple counter @r{@var{s}}. |
8925f36f | 10099 | |
3c9b6116 AW |
10100 | Counter @r{@var{s}} is reset to 0 whenever @code{glBegin} is called and |
10101 | before each line segment of a | |
8925f36f AW |
10102 | @code{glBegin}(@code{GL_LINES})/@code{glEnd} sequence is generated. It |
10103 | is incremented after each fragment of a unit width aliased line segment | |
3c9b6116 AW |
10104 | is generated or after each @r{@var{i}} fragments of an @r{@var{i}} width |
10105 | line segment are generated. The @r{@var{i}} fragments associated with | |
10106 | count @r{@var{s}} are masked out if | |
8925f36f | 10107 | |
3c9b6116 | 10108 | @var{pattern} bit @r{(@var{s}/@var{factor},)%16} |
8925f36f AW |
10109 | |
10110 | is 0, otherwise these fragments are sent to the frame buffer. Bit zero | |
10111 | of @var{pattern} is the least significant bit. | |
10112 | ||
3c9b6116 AW |
10113 | Antialiased lines are treated as a sequence of @r{1×@var{width}} |
10114 | rectangles for purposes of stippling. Whether rectangle @r{@var{s}} is | |
10115 | rasterized or not depends on the fragment rule described for aliased | |
8925f36f AW |
10116 | lines, counting rectangles rather than groups of fragments. |
10117 | ||
10118 | To enable and disable line stippling, call @code{glEnable} and | |
10119 | @code{glDisable} with argument @code{GL_LINE_STIPPLE}. When enabled, the | |
10120 | line stipple pattern is applied as described above. When disabled, it is | |
10121 | as if the pattern were all 1's. Initially, line stippling is disabled. | |
10122 | ||
8925f36f AW |
10123 | @code{GL_INVALID_OPERATION} is generated if @code{glLineStipple} is |
10124 | executed between the execution of @code{glBegin} and the corresponding | |
10125 | execution of @code{glEnd}. | |
10126 | ||
bb894c9d | 10127 | @end deftypefun |
8925f36f | 10128 | |
bb894c9d | 10129 | @deftypefun void glLineWidth width |
3c9b6116 AW |
10130 | Specify the width of rasterized lines. |
10131 | ||
8925f36f AW |
10132 | @table @asis |
10133 | @item @var{width} | |
10134 | Specifies the width of rasterized lines. The initial value is 1. | |
10135 | ||
10136 | @end table | |
10137 | ||
8925f36f AW |
10138 | @code{glLineWidth} specifies the rasterized width of both aliased and |
10139 | antialiased lines. Using a line width other than 1 has different | |
10140 | effects, depending on whether line antialiasing is enabled. To enable | |
10141 | and disable line antialiasing, call @code{glEnable} and @code{glDisable} | |
10142 | with argument @code{GL_LINE_SMOOTH}. Line antialiasing is initially | |
10143 | disabled. | |
10144 | ||
10145 | If line antialiasing is disabled, the actual width is determined by | |
10146 | rounding the supplied width to the nearest integer. (If the rounding | |
10147 | results in the value 0, it is as if the line width were 1.) If | |
3c9b6116 AW |
10148 | @r{∣Δ@var{x},∣>=∣Δ@var{y},∣}, @var{i} pixels are filled in each column |
10149 | that is rasterized, where @var{i} is the rounded value of @var{width}. | |
10150 | Otherwise, @var{i} pixels are filled in each row that is rasterized. | |
8925f36f AW |
10151 | |
10152 | If antialiasing is enabled, line rasterization produces a fragment for | |
10153 | each pixel square that intersects the region lying within the rectangle | |
10154 | having width equal to the current line width, length equal to the actual | |
10155 | length of the line, and centered on the mathematical line segment. The | |
10156 | coverage value for each fragment is the window coordinate area of the | |
10157 | intersection of the rectangular region with the corresponding pixel | |
10158 | square. This value is saved and used in the final rasterization step. | |
10159 | ||
10160 | Not all widths can be supported when line antialiasing is enabled. If an | |
10161 | unsupported width is requested, the nearest supported width is used. | |
10162 | Only width 1 is guaranteed to be supported; others depend on the | |
10163 | implementation. Likewise, there is a range for aliased line widths as | |
10164 | well. To query the range of supported widths and the size difference | |
10165 | between supported widths within the range, call @code{glGet} with | |
10166 | arguments @code{GL_ALIASED_LINE_WIDTH_RANGE}, | |
10167 | @code{GL_SMOOTH_LINE_WIDTH_RANGE}, and | |
10168 | @code{GL_SMOOTH_LINE_WIDTH_GRANULARITY}. | |
10169 | ||
8925f36f AW |
10170 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than or |
10171 | equal to 0. | |
10172 | ||
10173 | @code{GL_INVALID_OPERATION} is generated if @code{glLineWidth} is | |
10174 | executed between the execution of @code{glBegin} and the corresponding | |
10175 | execution of @code{glEnd}. | |
10176 | ||
bb894c9d | 10177 | @end deftypefun |
8925f36f | 10178 | |
bb894c9d | 10179 | @deftypefun void glLinkProgram program |
3c9b6116 AW |
10180 | Links a program object. |
10181 | ||
8925f36f AW |
10182 | @table @asis |
10183 | @item @var{program} | |
10184 | Specifies the handle of the program object to be linked. | |
10185 | ||
10186 | @end table | |
10187 | ||
8925f36f AW |
10188 | @code{glLinkProgram} links the program object specified by |
10189 | @var{program}. If any shader objects of type @code{GL_VERTEX_SHADER} are | |
10190 | attached to @var{program}, they will be used to create an executable | |
10191 | that will run on the programmable vertex processor. If any shader | |
10192 | objects of type @code{GL_FRAGMENT_SHADER} are attached to @var{program}, | |
10193 | they will be used to create an executable that will run on the | |
10194 | programmable fragment processor. | |
10195 | ||
10196 | The status of the link operation will be stored as part of the program | |
10197 | object's state. This value will be set to @code{GL_TRUE} if the program | |
10198 | object was linked without errors and is ready for use, and | |
10199 | @code{GL_FALSE} otherwise. It can be queried by calling | |
10200 | @code{glGetProgram} with arguments @var{program} and | |
10201 | @code{GL_LINK_STATUS}. | |
10202 | ||
10203 | As a result of a successful link operation, all active user-defined | |
10204 | uniform variables belonging to @var{program} will be initialized to 0, | |
10205 | and each of the program object's active uniform variables will be | |
10206 | assigned a location that can be queried by calling | |
10207 | @code{glGetUniformLocation}. Also, any active user-defined attribute | |
10208 | variables that have not been bound to a generic vertex attribute index | |
10209 | will be bound to one at this time. | |
10210 | ||
10211 | Linking of a program object can fail for a number of reasons as | |
10212 | specified in the @var{OpenGL Shading Language Specification}. The | |
10213 | following lists some of the conditions that will cause a link error. | |
10214 | ||
10215 | @itemize | |
10216 | @item | |
10217 | The number of active attribute variables supported by the implementation | |
10218 | has been exceeded. | |
10219 | ||
10220 | @item | |
10221 | The storage limit for uniform variables has been exceeded. | |
10222 | ||
10223 | @item | |
10224 | The number of active uniform variables supported by the implementation | |
10225 | has been exceeded. | |
10226 | ||
10227 | @item | |
10228 | The @code{main} function is missing for the vertex shader or the | |
10229 | fragment shader. | |
10230 | ||
10231 | @item | |
10232 | A varying variable actually used in the fragment shader is not declared | |
10233 | in the same way (or is not declared at all) in the vertex shader. | |
10234 | ||
10235 | @item | |
10236 | A reference to a function or variable name is unresolved. | |
10237 | ||
10238 | @item | |
10239 | A shared global is declared with two different types or two different | |
10240 | initial values. | |
10241 | ||
10242 | @item | |
10243 | One or more of the attached shader objects has not been successfully | |
10244 | compiled. | |
10245 | ||
10246 | @item | |
10247 | Binding a generic attribute matrix caused some rows of the matrix to | |
10248 | fall outside the allowed maximum of @code{GL_MAX_VERTEX_ATTRIBS}. | |
10249 | ||
10250 | @item | |
10251 | Not enough contiguous vertex attribute slots could be found to bind | |
10252 | attribute matrices. | |
10253 | ||
10254 | @end itemize | |
10255 | ||
10256 | When a program object has been successfully linked, the program object | |
10257 | can be made part of current state by calling @code{glUseProgram}. | |
10258 | Whether or not the link operation was successful, the program object's | |
10259 | information log will be overwritten. The information log can be | |
10260 | retrieved by calling @code{glGetProgramInfoLog}. | |
10261 | ||
10262 | @code{glLinkProgram} will also install the generated executables as part | |
10263 | of the current rendering state if the link operation was successful and | |
10264 | the specified program object is already currently in use as a result of | |
10265 | a previous call to @code{glUseProgram}. If the program object currently | |
10266 | in use is relinked unsuccessfully, its link status will be set to | |
10267 | @code{GL_FALSE} , but the executables and associated state will remain | |
10268 | part of the current state until a subsequent call to @code{glUseProgram} | |
10269 | removes it from use. After it is removed from use, it cannot be made | |
10270 | part of current state until it has been successfully relinked. | |
10271 | ||
10272 | If @var{program} contains shader objects of type @code{GL_VERTEX_SHADER} | |
10273 | but does not contain shader objects of type @code{GL_FRAGMENT_SHADER}, | |
10274 | the vertex shader will be linked against the implicit interface for | |
10275 | fixed functionality fragment processing. Similarly, if @var{program} | |
10276 | contains shader objects of type @code{GL_FRAGMENT_SHADER} but it does | |
10277 | not contain shader objects of type @code{GL_VERTEX_SHADER}, the fragment | |
10278 | shader will be linked against the implicit interface for fixed | |
10279 | functionality vertex processing. | |
10280 | ||
10281 | The program object's information log is updated and the program is | |
10282 | generated at the time of the link operation. After the link operation, | |
10283 | applications are free to modify attached shader objects, compile | |
10284 | attached shader objects, detach shader objects, delete shader objects, | |
10285 | and attach additional shader objects. None of these operations affects | |
10286 | the information log or the program that is part of the program object. | |
10287 | ||
8925f36f AW |
10288 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
10289 | generated by OpenGL. | |
10290 | ||
10291 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
10292 | program object. | |
10293 | ||
10294 | @code{GL_INVALID_OPERATION} is generated if @code{glLinkProgram} is | |
10295 | executed between the execution of @code{glBegin} and the corresponding | |
10296 | execution of @code{glEnd}. | |
10297 | ||
bb894c9d | 10298 | @end deftypefun |
8925f36f | 10299 | |
bb894c9d | 10300 | @deftypefun void glListBase base |
3c9b6116 AW |
10301 | Set the display-list base for . |
10302 | ||
8925f36f AW |
10303 | @table @asis |
10304 | @item @var{base} | |
10305 | Specifies an integer offset that will be added to @code{glCallLists} | |
10306 | offsets to generate display-list names. The initial value is 0. | |
10307 | ||
10308 | @end table | |
10309 | ||
8925f36f AW |
10310 | @code{glCallLists} specifies an array of offsets. Display-list names are |
10311 | generated by adding @var{base} to each offset. Names that reference | |
10312 | valid display lists are executed; the others are ignored. | |
10313 | ||
8925f36f AW |
10314 | @code{GL_INVALID_OPERATION} is generated if @code{glListBase} is |
10315 | executed between the execution of @code{glBegin} and the corresponding | |
10316 | execution of @code{glEnd}. | |
10317 | ||
bb894c9d | 10318 | @end deftypefun |
8925f36f | 10319 | |
bb894c9d | 10320 | @deftypefun void glLoadIdentity |
3c9b6116 AW |
10321 | Replace the current matrix with the identity matrix. |
10322 | ||
8925f36f AW |
10323 | @code{glLoadIdentity} replaces the current matrix with the identity |
10324 | matrix. It is semantically equivalent to calling @code{glLoadMatrix} | |
10325 | with the identity matrix | |
10326 | ||
10327 | ||
10328 | ||
3c9b6116 | 10329 | @r{((1 0 0 0), (0 1 0 0), (0 0 1 0), (0 0 0 1),,)} |
8925f36f AW |
10330 | |
10331 | ||
10332 | ||
10333 | but in some cases it is more efficient. | |
10334 | ||
8925f36f AW |
10335 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadIdentity} is |
10336 | executed between the execution of @code{glBegin} and the corresponding | |
10337 | execution of @code{glEnd}. | |
10338 | ||
bb894c9d | 10339 | @end deftypefun |
8925f36f | 10340 | |
bb894c9d | 10341 | @deftypefun void glLoadMatrixd m |
3c9b6116 AW |
10342 | Replace the current matrix with the specified matrix. |
10343 | ||
8925f36f AW |
10344 | @table @asis |
10345 | @item @var{m} | |
10346 | Specifies a pointer to 16 consecutive values, which are used as the | |
3c9b6116 | 10347 | elements of a @r{4×4} column-major matrix. |
8925f36f AW |
10348 | |
10349 | @end table | |
10350 | ||
8925f36f AW |
10351 | @code{glLoadMatrix} replaces the current matrix with the one whose |
10352 | elements are specified by @var{m}. The current matrix is the projection | |
10353 | matrix, modelview matrix, or texture matrix, depending on the current | |
10354 | matrix mode (see @code{glMatrixMode}). | |
10355 | ||
10356 | The current matrix, M, defines a transformation of coordinates. For | |
10357 | instance, assume M refers to the modelview matrix. If | |
3c9b6116 AW |
10358 | @r{@var{v}=(@var{v}[0,],@var{v}[1,]@var{v}[2,]@var{v}[3,])} is the |
10359 | set of object coordinates of a vertex, and @var{m} points to an array of | |
10360 | @r{16} single- or double-precision floating-point values | |
10361 | @r{@var{m}=@{@var{m}[0,],@var{m}[1,]@var{...}@var{m}[15,]@}}, then | |
10362 | the modelview transformation @r{@var{M}(@var{v},)} does the following: | |
8925f36f | 10363 | |
3c9b6116 | 10364 | @r{@var{M}(@var{v},)=((@var{m}[0,] @var{m}[4,] @var{m}[8,] |
8925f36f AW |
10365 | @var{m}[12,]), (@var{m}[1,] @var{m}[5,] @var{m}[9,] @var{m}[13,]), |
10366 | (@var{m}[2,] @var{m}[6,] @var{m}[10,] @var{m}[14,]), (@var{m}[3,] | |
10367 | @var{m}[7,] @var{m}[11,] @var{m}[15,]),)×((@var{v}[0,]), | |
10368 | (@var{v}[1,]), (@var{v}[2,]), (@var{v}[3,]),)} | |
10369 | ||
10370 | ||
10371 | ||
10372 | Projection and texture transformations are similarly defined. | |
10373 | ||
8925f36f AW |
10374 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadMatrix} is |
10375 | executed between the execution of @code{glBegin} and the corresponding | |
10376 | execution of @code{glEnd}. | |
10377 | ||
bb894c9d | 10378 | @end deftypefun |
8925f36f | 10379 | |
bb894c9d | 10380 | @deftypefun void glLoadName name |
3c9b6116 AW |
10381 | Load a name onto the name stack. |
10382 | ||
8925f36f AW |
10383 | @table @asis |
10384 | @item @var{name} | |
10385 | Specifies a name that will replace the top value on the name stack. | |
10386 | ||
10387 | @end table | |
10388 | ||
8925f36f AW |
10389 | The name stack is used during selection mode to allow sets of rendering |
10390 | commands to be uniquely identified. It consists of an ordered set of | |
10391 | unsigned integers and is initially empty. | |
10392 | ||
10393 | @code{glLoadName} causes @var{name} to replace the value on the top of | |
10394 | the name stack. | |
10395 | ||
10396 | The name stack is always empty while the render mode is not | |
10397 | @code{GL_SELECT}. Calls to @code{glLoadName} while the render mode is | |
10398 | not @code{GL_SELECT} are ignored. | |
10399 | ||
8925f36f AW |
10400 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadName} is called |
10401 | while the name stack is empty. | |
10402 | ||
10403 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadName} is | |
10404 | executed between the execution of @code{glBegin} and the corresponding | |
10405 | execution of @code{glEnd}. | |
10406 | ||
bb894c9d | 10407 | @end deftypefun |
8925f36f | 10408 | |
bb894c9d | 10409 | @deftypefun void glLoadTransposeMatrixd m |
3c9b6116 AW |
10410 | Replace the current matrix with the specified row-major ordered matrix. |
10411 | ||
8925f36f AW |
10412 | @table @asis |
10413 | @item @var{m} | |
10414 | Specifies a pointer to 16 consecutive values, which are used as the | |
3c9b6116 | 10415 | elements of a @r{4×4} row-major matrix. |
8925f36f AW |
10416 | |
10417 | @end table | |
10418 | ||
8925f36f AW |
10419 | @code{glLoadTransposeMatrix} replaces the current matrix with the one |
10420 | whose elements are specified by @var{m}. The current matrix is the | |
10421 | projection matrix, modelview matrix, or texture matrix, depending on the | |
10422 | current matrix mode (see @code{glMatrixMode}). | |
10423 | ||
10424 | The current matrix, M, defines a transformation of coordinates. For | |
10425 | instance, assume M refers to the modelview matrix. If | |
3c9b6116 AW |
10426 | @r{@var{v}=(@var{v}[0,],@var{v}[1,]@var{v}[2,]@var{v}[3,])} is the |
10427 | set of object coordinates of a vertex, and @var{m} points to an array of | |
10428 | @r{16} single- or double-precision floating-point values | |
10429 | @r{@var{m}=@{@var{m}[0,],@var{m}[1,]@var{...}@var{m}[15,]@}}, then | |
10430 | the modelview transformation @r{@var{M}(@var{v},)} does the following: | |
8925f36f | 10431 | |
3c9b6116 | 10432 | @r{@var{M}(@var{v},)=((@var{m}[0,] @var{m}[1,] @var{m}[2,] |
8925f36f AW |
10433 | @var{m}[3,]), (@var{m}[4,] @var{m}[5,] @var{m}[6,] @var{m}[7,]), |
10434 | (@var{m}[8,] @var{m}[9,] @var{m}[10,] @var{m}[11,]), (@var{m}[12,] | |
10435 | @var{m}[13,] @var{m}[14,] @var{m}[15,]),)×((@var{v}[0,]), | |
10436 | (@var{v}[1,]), (@var{v}[2,]), (@var{v}[3,]),)} | |
10437 | ||
10438 | ||
10439 | ||
10440 | Projection and texture transformations are similarly defined. | |
10441 | ||
3c9b6116 AW |
10442 | Calling @code{glLoadTransposeMatrix} with matrix @r{@var{M}} is |
10443 | identical in operation to @code{glLoadMatrix} with @r{@var{M}^@var{T}}, | |
10444 | where @r{@var{T}} represents the transpose. | |
8925f36f | 10445 | |
8925f36f AW |
10446 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadTransposeMatrix} |
10447 | is executed between the execution of @code{glBegin} and the | |
10448 | corresponding execution of @code{glEnd}. | |
10449 | ||
bb894c9d | 10450 | @end deftypefun |
8925f36f | 10451 | |
bb894c9d | 10452 | @deftypefun void glLogicOp opcode |
3c9b6116 AW |
10453 | Specify a logical pixel operation for color index rendering. |
10454 | ||
8925f36f AW |
10455 | @table @asis |
10456 | @item @var{opcode} | |
10457 | Specifies a symbolic constant that selects a logical operation. The | |
10458 | following symbols are accepted: @code{GL_CLEAR}, @code{GL_SET}, | |
10459 | @code{GL_COPY}, @code{GL_COPY_INVERTED}, @code{GL_NOOP}, | |
10460 | @code{GL_INVERT}, @code{GL_AND}, @code{GL_NAND}, @code{GL_OR}, | |
10461 | @code{GL_NOR}, @code{GL_XOR}, @code{GL_EQUIV}, @code{GL_AND_REVERSE}, | |
10462 | @code{GL_AND_INVERTED}, @code{GL_OR_REVERSE}, and @code{GL_OR_INVERTED}. | |
10463 | The initial value is @code{GL_COPY}. | |
10464 | ||
10465 | @end table | |
10466 | ||
8925f36f AW |
10467 | @code{glLogicOp} specifies a logical operation that, when enabled, is |
10468 | applied between the incoming color index or RGBA color and the color | |
10469 | index or RGBA color at the corresponding location in the frame buffer. | |
10470 | To enable or disable the logical operation, call @code{glEnable} and | |
10471 | @code{glDisable} using the symbolic constant @code{GL_COLOR_LOGIC_OP} | |
10472 | for RGBA mode or @code{GL_INDEX_LOGIC_OP} for color index mode. The | |
10473 | initial value is disabled for both operations. | |
10474 | ||
10475 | ||
10476 | ||
10477 | @table @asis | |
10478 | @item @strong{Opcode} | |
10479 | @strong{Resulting Operation} | |
10480 | ||
10481 | @item @code{GL_CLEAR} | |
10482 | 0 | |
10483 | ||
10484 | @item @code{GL_SET} | |
10485 | 1 | |
10486 | ||
10487 | @item @code{GL_COPY} | |
10488 | s | |
10489 | ||
10490 | @item @code{GL_COPY_INVERTED} | |
10491 | ~s | |
10492 | ||
10493 | @item @code{GL_NOOP} | |
10494 | d | |
10495 | ||
10496 | @item @code{GL_INVERT} | |
10497 | ~d | |
10498 | ||
10499 | @item @code{GL_AND} | |
10500 | s & d | |
10501 | ||
10502 | @item @code{GL_NAND} | |
10503 | ~(s & d) | |
10504 | ||
10505 | @item @code{GL_OR} | |
10506 | s | d | |
10507 | ||
10508 | @item @code{GL_NOR} | |
10509 | ~(s | d) | |
10510 | ||
10511 | @item @code{GL_XOR} | |
10512 | s ^ d | |
10513 | ||
10514 | @item @code{GL_EQUIV} | |
10515 | ~(s ^ d) | |
10516 | ||
10517 | @item @code{GL_AND_REVERSE} | |
10518 | s & ~d | |
10519 | ||
10520 | @item @code{GL_AND_INVERTED} | |
10521 | ~s & d | |
10522 | ||
10523 | @item @code{GL_OR_REVERSE} | |
10524 | s | ~d | |
10525 | ||
10526 | @item @code{GL_OR_INVERTED} | |
10527 | ~s | d | |
10528 | ||
10529 | @end table | |
10530 | ||
10531 | @var{opcode} is a symbolic constant chosen from the list above. In the | |
10532 | explanation of the logical operations, @var{s} represents the incoming | |
10533 | color index and @var{d} represents the index in the frame buffer. | |
10534 | Standard C-language operators are used. As these bitwise operators | |
10535 | suggest, the logical operation is applied independently to each bit pair | |
10536 | of the source and destination indices or colors. | |
10537 | ||
8925f36f AW |
10538 | @code{GL_INVALID_ENUM} is generated if @var{opcode} is not an accepted |
10539 | value. | |
10540 | ||
10541 | @code{GL_INVALID_OPERATION} is generated if @code{glLogicOp} is executed | |
10542 | between the execution of @code{glBegin} and the corresponding execution | |
10543 | of @code{glEnd}. | |
10544 | ||
bb894c9d | 10545 | @end deftypefun |
8925f36f | 10546 | |
bb894c9d | 10547 | @deftypefun void glMap1d target u1 u2 stride order points |
3c9b6116 AW |
10548 | Define a one-dimensional evaluator. |
10549 | ||
8925f36f AW |
10550 | @table @asis |
10551 | @item @var{target} | |
10552 | Specifies the kind of values that are generated by the evaluator. | |
10553 | Symbolic constants @code{GL_MAP1_VERTEX_3}, @code{GL_MAP1_VERTEX_4}, | |
10554 | @code{GL_MAP1_INDEX}, @code{GL_MAP1_COLOR_4}, @code{GL_MAP1_NORMAL}, | |
10555 | @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2}, | |
10556 | @code{GL_MAP1_TEXTURE_COORD_3}, and @code{GL_MAP1_TEXTURE_COORD_4} are | |
10557 | accepted. | |
10558 | ||
10559 | @item @var{u1} | |
10560 | @itemx @var{u2} | |
3c9b6116 AW |
10561 | Specify a linear mapping of @r{@var{u}}, as presented to |
10562 | @code{glEvalCoord1}, to @r{@var{u}^}, the variable that is evaluated by | |
10563 | the equations specified by this command. | |
8925f36f AW |
10564 | |
10565 | @item @var{stride} | |
10566 | Specifies the number of floats or doubles between the beginning of one | |
10567 | control point and the beginning of the next one in the data structure | |
10568 | referenced in @var{points}. This allows control points to be embedded in | |
10569 | arbitrary data structures. The only constraint is that the values for a | |
10570 | particular control point must occupy contiguous memory locations. | |
10571 | ||
10572 | @item @var{order} | |
10573 | Specifies the number of control points. Must be positive. | |
10574 | ||
10575 | @item @var{points} | |
10576 | Specifies a pointer to the array of control points. | |
10577 | ||
10578 | @end table | |
10579 | ||
8925f36f AW |
10580 | Evaluators provide a way to use polynomial or rational polynomial |
10581 | mapping to produce vertices, normals, texture coordinates, and colors. | |
10582 | The values produced by an evaluator are sent to further stages of GL | |
10583 | processing just as if they had been presented using @code{glVertex}, | |
10584 | @code{glNormal}, @code{glTexCoord}, and @code{glColor} commands, except | |
10585 | that the generated values do not update the current normal, texture | |
10586 | coordinates, or color. | |
10587 | ||
10588 | All polynomial or rational polynomial splines of any degree (up to the | |
10589 | maximum degree supported by the GL implementation) can be described | |
10590 | using evaluators. These include almost all splines used in computer | |
10591 | graphics: B-splines, Bezier curves, Hermite splines, and so on. | |
10592 | ||
10593 | Evaluators define curves based on Bernstein polynomials. Define | |
3c9b6116 | 10594 | @r{@var{p}(@var{u}^,)} as |
8925f36f | 10595 | |
3c9b6116 | 10596 | @r{@var{p}(@var{u}^,)=Σ@var{i}=0@var{n}@var{B}_@var{i},^@var{n}(@var{u}^,)@var{R}_@var{i}} |
8925f36f AW |
10597 | |
10598 | ||
10599 | ||
3c9b6116 AW |
10600 | where @r{@var{R}_@var{i}} is a control point and |
10601 | @r{@var{B}_@var{i},^@var{n}(@var{u}^,)} is the @r{@var{i}}th Bernstein | |
10602 | polynomial of degree @r{@var{n}} (@var{order} = @r{@var{n}+1}): | |
8925f36f | 10603 | |
3c9b6116 | 10604 | @r{@var{B}_@var{i},^@var{n}(@var{u}^,)=((@var{n}), |
8925f36f AW |
10605 | (@var{i}),,)@var{u}^,^@var{i}(1-@var{u}^,)^@var{n}-@var{i},,} |
10606 | ||
10607 | Recall that | |
10608 | ||
3c9b6116 | 10609 | @r{0^0==1} and @r{((@var{n}), (0),,)==1} |
8925f36f AW |
10610 | |
10611 | @code{glMap1} is used to define the basis and to specify what kind of | |
10612 | values are produced. Once defined, a map can be enabled and disabled by | |
10613 | calling @code{glEnable} and @code{glDisable} with the map name, one of | |
10614 | the nine predefined values for @var{target} described below. | |
10615 | @code{glEvalCoord1} evaluates the one-dimensional maps that are enabled. | |
3c9b6116 AW |
10616 | When @code{glEvalCoord1} presents a value @r{@var{u}}, the Bernstein |
10617 | functions are evaluated using @r{@var{u}^}, where | |
10618 | @r{@var{u}^=@var{u}-@var{u1},/@var{u2}-@var{u1},} | |
8925f36f AW |
10619 | |
10620 | @var{target} is a symbolic constant that indicates what kind of control | |
10621 | points are provided in @var{points}, and what output is generated when | |
10622 | the map is evaluated. It can assume one of nine predefined values: | |
10623 | ||
10624 | @table @asis | |
10625 | @item @code{GL_MAP1_VERTEX_3} | |
10626 | Each control point is three floating-point values representing | |
3c9b6116 AW |
10627 | @r{@var{x}}, @r{@var{y}}, and @r{@var{z}}. Internal @code{glVertex3} |
10628 | commands are generated when the map is evaluated. | |
8925f36f AW |
10629 | |
10630 | @item @code{GL_MAP1_VERTEX_4} | |
10631 | Each control point is four floating-point values representing | |
3c9b6116 AW |
10632 | @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}. Internal |
10633 | @code{glVertex4} commands are generated when the map is evaluated. | |
8925f36f AW |
10634 | |
10635 | @item @code{GL_MAP1_INDEX} | |
10636 | Each control point is a single floating-point value representing a color | |
10637 | index. Internal @code{glIndex} commands are generated when the map is | |
10638 | evaluated but the current index is not updated with the value of these | |
10639 | @code{glIndex} commands. | |
10640 | ||
10641 | @item @code{GL_MAP1_COLOR_4} | |
10642 | Each control point is four floating-point values representing red, | |
10643 | green, blue, and alpha. Internal @code{glColor4} commands are generated | |
10644 | when the map is evaluated but the current color is not updated with the | |
10645 | value of these @code{glColor4} commands. | |
10646 | ||
10647 | @item @code{GL_MAP1_NORMAL} | |
10648 | Each control point is three floating-point values representing the | |
3c9b6116 AW |
10649 | @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} components of a normal vector. |
10650 | Internal @code{glNormal} commands are generated when the map is | |
10651 | evaluated but the current normal is not updated with the value of these | |
10652 | @code{glNormal} commands. | |
8925f36f AW |
10653 | |
10654 | @item @code{GL_MAP1_TEXTURE_COORD_1} | |
10655 | Each control point is a single floating-point value representing the | |
3c9b6116 AW |
10656 | @r{@var{s}} texture coordinate. Internal @code{glTexCoord1} commands are |
10657 | generated when the map is evaluated but the current texture coordinates | |
10658 | are not updated with the value of these @code{glTexCoord} commands. | |
8925f36f AW |
10659 | |
10660 | @item @code{GL_MAP1_TEXTURE_COORD_2} | |
10661 | Each control point is two floating-point values representing the | |
3c9b6116 | 10662 | @r{@var{s}} and @r{@var{t}} texture coordinates. Internal |
8925f36f AW |
10663 | @code{glTexCoord2} commands are generated when the map is evaluated but |
10664 | the current texture coordinates are not updated with the value of these | |
10665 | @code{glTexCoord} commands. | |
10666 | ||
10667 | @item @code{GL_MAP1_TEXTURE_COORD_3} | |
10668 | Each control point is three floating-point values representing the | |
3c9b6116 AW |
10669 | @r{@var{s}}, @r{@var{t}}, and @r{@var{r}} texture coordinates. Internal |
10670 | @code{glTexCoord3} commands are generated when the map is evaluated but | |
10671 | the current texture coordinates are not updated with the value of these | |
10672 | @code{glTexCoord} commands. | |
8925f36f AW |
10673 | |
10674 | @item @code{GL_MAP1_TEXTURE_COORD_4} | |
10675 | Each control point is four floating-point values representing the | |
3c9b6116 AW |
10676 | @r{@var{s}}, @r{@var{t}}, @r{@var{r}}, and @r{@var{q}} texture |
10677 | coordinates. Internal @code{glTexCoord4} commands are generated when the | |
10678 | map is evaluated but the current texture coordinates are not updated | |
10679 | with the value of these @code{glTexCoord} commands. | |
8925f36f AW |
10680 | |
10681 | @end table | |
10682 | ||
10683 | @var{stride}, @var{order}, and @var{points} define the array addressing | |
10684 | for accessing the control points. @var{points} is the location of the | |
10685 | first control point, which occupies one, two, three, or four contiguous | |
10686 | memory locations, depending on which map is being defined. @var{order} | |
10687 | is the number of control points in the array. @var{stride} specifies how | |
10688 | many float or double locations to advance the internal memory pointer to | |
10689 | reach the next control point. | |
10690 | ||
8925f36f AW |
10691 | @code{GL_INVALID_ENUM} is generated if @var{target} is not an accepted |
10692 | value. | |
10693 | ||
10694 | @code{GL_INVALID_VALUE} is generated if @var{u1} is equal to @var{u2}. | |
10695 | ||
10696 | @code{GL_INVALID_VALUE} is generated if @var{stride} is less than the | |
10697 | number of values in a control point. | |
10698 | ||
10699 | @code{GL_INVALID_VALUE} is generated if @var{order} is less than 1 or | |
10700 | greater than the return value of @code{GL_MAX_EVAL_ORDER}. | |
10701 | ||
10702 | @code{GL_INVALID_OPERATION} is generated if @code{glMap1} is executed | |
10703 | between the execution of @code{glBegin} and the corresponding execution | |
10704 | of @code{glEnd}. | |
10705 | ||
10706 | @code{GL_INVALID_OPERATION} is generated if @code{glMap1} is called and | |
10707 | the value of @code{GL_ACTIVE_TEXTURE} is not @code{GL_TEXTURE0}. | |
10708 | ||
bb894c9d | 10709 | @end deftypefun |
8925f36f | 10710 | |
bb894c9d | 10711 | @deftypefun void glMap2d target u1 u2 ustride uorder v1 v2 vstride vorder points |
3c9b6116 AW |
10712 | Define a two-dimensional evaluator. |
10713 | ||
8925f36f AW |
10714 | @table @asis |
10715 | @item @var{target} | |
10716 | Specifies the kind of values that are generated by the evaluator. | |
10717 | Symbolic constants @code{GL_MAP2_VERTEX_3}, @code{GL_MAP2_VERTEX_4}, | |
10718 | @code{GL_MAP2_INDEX}, @code{GL_MAP2_COLOR_4}, @code{GL_MAP2_NORMAL}, | |
10719 | @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2}, | |
10720 | @code{GL_MAP2_TEXTURE_COORD_3}, and @code{GL_MAP2_TEXTURE_COORD_4} are | |
10721 | accepted. | |
10722 | ||
10723 | @item @var{u1} | |
10724 | @itemx @var{u2} | |
3c9b6116 AW |
10725 | Specify a linear mapping of @r{@var{u}}, as presented to |
10726 | @code{glEvalCoord2}, to @r{@var{u}^}, one of the two variables that are | |
10727 | evaluated by the equations specified by this command. Initially, | |
8925f36f AW |
10728 | @var{u1} is 0 and @var{u2} is 1. |
10729 | ||
10730 | @item @var{ustride} | |
10731 | Specifies the number of floats or doubles between the beginning of | |
3c9b6116 AW |
10732 | control point @r{@var{R}_@var{ij}} and the beginning of control point |
10733 | @r{@var{R}_(@var{i}+1,)@var{j},}, where @r{@var{i}} and @r{@var{j}} are | |
10734 | the @r{@var{u}} and @r{@var{v}} control point indices, respectively. | |
10735 | This allows control points to be embedded in arbitrary data structures. | |
10736 | The only constraint is that the values for a particular control point | |
10737 | must occupy contiguous memory locations. The initial value of | |
10738 | @var{ustride} is 0. | |
8925f36f AW |
10739 | |
10740 | @item @var{uorder} | |
3c9b6116 | 10741 | Specifies the dimension of the control point array in the @r{@var{u}} |
8925f36f AW |
10742 | axis. Must be positive. The initial value is 1. |
10743 | ||
10744 | @item @var{v1} | |
10745 | @itemx @var{v2} | |
3c9b6116 AW |
10746 | Specify a linear mapping of @r{@var{v}}, as presented to |
10747 | @code{glEvalCoord2}, to @r{@var{v}^}, one of the two variables that are | |
10748 | evaluated by the equations specified by this command. Initially, | |
8925f36f AW |
10749 | @var{v1} is 0 and @var{v2} is 1. |
10750 | ||
10751 | @item @var{vstride} | |
10752 | Specifies the number of floats or doubles between the beginning of | |
3c9b6116 AW |
10753 | control point @r{@var{R}_@var{ij}} and the beginning of control point |
10754 | @r{@var{R}_@var{i}(@var{j}+1,),}, where @r{@var{i}} and @r{@var{j}} are | |
10755 | the @r{@var{u}} and @r{@var{v}} control point indices, respectively. | |
10756 | This allows control points to be embedded in arbitrary data structures. | |
10757 | The only constraint is that the values for a particular control point | |
10758 | must occupy contiguous memory locations. The initial value of | |
10759 | @var{vstride} is 0. | |
8925f36f AW |
10760 | |
10761 | @item @var{vorder} | |
3c9b6116 | 10762 | Specifies the dimension of the control point array in the @r{@var{v}} |
8925f36f AW |
10763 | axis. Must be positive. The initial value is 1. |
10764 | ||
10765 | @item @var{points} | |
10766 | Specifies a pointer to the array of control points. | |
10767 | ||
10768 | @end table | |
10769 | ||
8925f36f AW |
10770 | Evaluators provide a way to use polynomial or rational polynomial |
10771 | mapping to produce vertices, normals, texture coordinates, and colors. | |
10772 | The values produced by an evaluator are sent on to further stages of GL | |
10773 | processing just as if they had been presented using @code{glVertex}, | |
10774 | @code{glNormal}, @code{glTexCoord}, and @code{glColor} commands, except | |
10775 | that the generated values do not update the current normal, texture | |
10776 | coordinates, or color. | |
10777 | ||
10778 | All polynomial or rational polynomial splines of any degree (up to the | |
10779 | maximum degree supported by the GL implementation) can be described | |
10780 | using evaluators. These include almost all surfaces used in computer | |
10781 | graphics, including B-spline surfaces, NURBS surfaces, Bezier surfaces, | |
10782 | and so on. | |
10783 | ||
10784 | Evaluators define surfaces based on bivariate Bernstein polynomials. | |
3c9b6116 | 10785 | Define @r{@var{p}(@var{u}^,@var{v}^)} as |
8925f36f | 10786 | |
3c9b6116 | 10787 | @r{@var{p}(@var{u}^,@var{v}^)=Σ@var{i}=0@var{n}Σ@var{j}=0@var{m}@var{B}_@var{i},^@var{n}(@var{u}^,)@var{B}_@var{j},^@var{m}(@var{v}^,)@var{R}_@var{ij}} |
8925f36f AW |
10788 | |
10789 | ||
10790 | ||
3c9b6116 AW |
10791 | where @r{@var{R}_@var{ij}} is a control point, |
10792 | @r{@var{B}_@var{i},^@var{n}(@var{u}^,)} is the @r{@var{i}}th Bernstein | |
10793 | polynomial of degree @r{@var{n}} (@var{uorder} = @r{@var{n}+1}) | |
8925f36f | 10794 | |
3c9b6116 | 10795 | @r{@var{B}_@var{i},^@var{n}(@var{u}^,)=((@var{n}), |
8925f36f AW |
10796 | (@var{i}),,)@var{u}^,^@var{i}(1-@var{u}^,)^@var{n}-@var{i},,} |
10797 | ||
3c9b6116 AW |
10798 | and @r{@var{B}_@var{j},^@var{m}(@var{v}^,)} is the @r{@var{j}}th |
10799 | Bernstein polynomial of degree @r{@var{m}} (@var{vorder} = | |
10800 | @r{@var{m}+1}) | |
8925f36f | 10801 | |
3c9b6116 | 10802 | @r{@var{B}_@var{j},^@var{m}(@var{v}^,)=((@var{m}), |
8925f36f AW |
10803 | (@var{j}),,)@var{v}^,^@var{j}(1-@var{v}^,)^@var{m}-@var{j},,} |
10804 | ||
3c9b6116 | 10805 | Recall that @r{0^0==1} and @r{((@var{n}), (0),,)==1} |
8925f36f AW |
10806 | |
10807 | @code{glMap2} is used to define the basis and to specify what kind of | |
10808 | values are produced. Once defined, a map can be enabled and disabled by | |
10809 | calling @code{glEnable} and @code{glDisable} with the map name, one of | |
10810 | the nine predefined values for @var{target}, described below. When | |
3c9b6116 AW |
10811 | @code{glEvalCoord2} presents values @r{@var{u}} and @r{@var{v}}, the |
10812 | bivariate Bernstein polynomials are evaluated using @r{@var{u}^} and | |
10813 | @r{@var{v}^}, where | |
8925f36f | 10814 | |
3c9b6116 | 10815 | @r{@var{u}^=@var{u}-@var{u1},/@var{u2}-@var{u1},} |
8925f36f | 10816 | |
3c9b6116 | 10817 | @r{@var{v}^=@var{v}-@var{v1},/@var{v2}-@var{v1},} |
8925f36f AW |
10818 | |
10819 | @var{target} is a symbolic constant that indicates what kind of control | |
10820 | points are provided in @var{points}, and what output is generated when | |
10821 | the map is evaluated. It can assume one of nine predefined values: | |
10822 | ||
10823 | @table @asis | |
10824 | @item @code{GL_MAP2_VERTEX_3} | |
10825 | Each control point is three floating-point values representing | |
3c9b6116 AW |
10826 | @r{@var{x}}, @r{@var{y}}, and @r{@var{z}}. Internal @code{glVertex3} |
10827 | commands are generated when the map is evaluated. | |
8925f36f AW |
10828 | |
10829 | @item @code{GL_MAP2_VERTEX_4} | |
10830 | Each control point is four floating-point values representing | |
3c9b6116 AW |
10831 | @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}. Internal |
10832 | @code{glVertex4} commands are generated when the map is evaluated. | |
8925f36f AW |
10833 | |
10834 | @item @code{GL_MAP2_INDEX} | |
10835 | Each control point is a single floating-point value representing a color | |
10836 | index. Internal @code{glIndex} commands are generated when the map is | |
10837 | evaluated but the current index is not updated with the value of these | |
10838 | @code{glIndex} commands. | |
10839 | ||
10840 | @item @code{GL_MAP2_COLOR_4} | |
10841 | Each control point is four floating-point values representing red, | |
10842 | green, blue, and alpha. Internal @code{glColor4} commands are generated | |
10843 | when the map is evaluated but the current color is not updated with the | |
10844 | value of these @code{glColor4} commands. | |
10845 | ||
10846 | @item @code{GL_MAP2_NORMAL} | |
10847 | Each control point is three floating-point values representing the | |
3c9b6116 AW |
10848 | @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} components of a normal vector. |
10849 | Internal @code{glNormal} commands are generated when the map is | |
10850 | evaluated but the current normal is not updated with the value of these | |
10851 | @code{glNormal} commands. | |
8925f36f AW |
10852 | |
10853 | @item @code{GL_MAP2_TEXTURE_COORD_1} | |
10854 | Each control point is a single floating-point value representing the | |
3c9b6116 AW |
10855 | @r{@var{s}} texture coordinate. Internal @code{glTexCoord1} commands are |
10856 | generated when the map is evaluated but the current texture coordinates | |
10857 | are not updated with the value of these @code{glTexCoord} commands. | |
8925f36f AW |
10858 | |
10859 | @item @code{GL_MAP2_TEXTURE_COORD_2} | |
10860 | Each control point is two floating-point values representing the | |
3c9b6116 | 10861 | @r{@var{s}} and @r{@var{t}} texture coordinates. Internal |
8925f36f AW |
10862 | @code{glTexCoord2} commands are generated when the map is evaluated but |
10863 | the current texture coordinates are not updated with the value of these | |
10864 | @code{glTexCoord} commands. | |
10865 | ||
10866 | @item @code{GL_MAP2_TEXTURE_COORD_3} | |
10867 | Each control point is three floating-point values representing the | |
3c9b6116 AW |
10868 | @r{@var{s}}, @r{@var{t}}, and @r{@var{r}} texture coordinates. Internal |
10869 | @code{glTexCoord3} commands are generated when the map is evaluated but | |
10870 | the current texture coordinates are not updated with the value of these | |
10871 | @code{glTexCoord} commands. | |
8925f36f AW |
10872 | |
10873 | @item @code{GL_MAP2_TEXTURE_COORD_4} | |
10874 | Each control point is four floating-point values representing the | |
3c9b6116 AW |
10875 | @r{@var{s}}, @r{@var{t}}, @r{@var{r}}, and @r{@var{q}} texture |
10876 | coordinates. Internal @code{glTexCoord4} commands are generated when the | |
10877 | map is evaluated but the current texture coordinates are not updated | |
10878 | with the value of these @code{glTexCoord} commands. | |
8925f36f AW |
10879 | |
10880 | @end table | |
10881 | ||
10882 | @var{ustride}, @var{uorder}, @var{vstride}, @var{vorder}, and | |
10883 | @var{points} define the array addressing for accessing the control | |
10884 | points. @var{points} is the location of the first control point, which | |
10885 | occupies one, two, three, or four contiguous memory locations, depending | |
3c9b6116 AW |
10886 | on which map is being defined. There are @r{@var{uorder}×@var{vorder}} |
10887 | control points in the array. @var{ustride} specifies how many float or | |
10888 | double locations are skipped to advance the internal memory pointer from | |
10889 | control point @r{@var{R}_@var{i}@var{j},} to control point | |
10890 | @r{@var{R}_(@var{i}+1,)@var{j},}. @var{vstride} specifies how many | |
8925f36f | 10891 | float or double locations are skipped to advance the internal memory |
3c9b6116 AW |
10892 | pointer from control point @r{@var{R}_@var{i}@var{j},} to control point |
10893 | @r{@var{R}_@var{i}(@var{j}+1,),}. | |
8925f36f | 10894 | |
8925f36f AW |
10895 | @code{GL_INVALID_ENUM} is generated if @var{target} is not an accepted |
10896 | value. | |
10897 | ||
10898 | @code{GL_INVALID_VALUE} is generated if @var{u1} is equal to @var{u2}, | |
10899 | or if @var{v1} is equal to @var{v2}. | |
10900 | ||
10901 | @code{GL_INVALID_VALUE} is generated if either @var{ustride} or | |
10902 | @var{vstride} is less than the number of values in a control point. | |
10903 | ||
10904 | @code{GL_INVALID_VALUE} is generated if either @var{uorder} or | |
10905 | @var{vorder} is less than 1 or greater than the return value of | |
10906 | @code{GL_MAX_EVAL_ORDER}. | |
10907 | ||
10908 | @code{GL_INVALID_OPERATION} is generated if @code{glMap2} is executed | |
10909 | between the execution of @code{glBegin} and the corresponding execution | |
10910 | of @code{glEnd}. | |
10911 | ||
10912 | @code{GL_INVALID_OPERATION} is generated if @code{glMap2} is called and | |
10913 | the value of @code{GL_ACTIVE_TEXTURE} is not @code{GL_TEXTURE0}. | |
10914 | ||
bb894c9d | 10915 | @end deftypefun |
8925f36f | 10916 | |
bb894c9d AW |
10917 | @deftypefun * glMapBuffer target access |
10918 | @deftypefunx GLboolean glUnmapBuffer target | |
3c9b6116 AW |
10919 | Map a buffer object's data store. |
10920 | ||
8925f36f AW |
10921 | @table @asis |
10922 | @item @var{target} | |
10923 | Specifies the target buffer object being mapped. The symbolic constant | |
10924 | must be @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
10925 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
10926 | ||
10927 | @item @var{access} | |
10928 | Specifies the access policy, indicating whether it will be possible to | |
10929 | read from, write to, or both read from and write to the buffer object's | |
10930 | mapped data store. The symbolic constant must be @code{GL_READ_ONLY}, | |
10931 | @code{GL_WRITE_ONLY}, or @code{GL_READ_WRITE}. | |
10932 | ||
10933 | @end table | |
10934 | ||
8925f36f AW |
10935 | @code{glMapBuffer} maps to the client's address space the entire data |
10936 | store of the buffer object currently bound to @var{target}. The data can | |
10937 | then be directly read and/or written relative to the returned pointer, | |
10938 | depending on the specified @var{access} policy. If the GL is unable to | |
10939 | map the buffer object's data store, @code{glMapBuffer} generates an | |
10940 | error and returns @code{NULL}. This may occur for system-specific | |
10941 | reasons, such as low virtual memory availability. | |
10942 | ||
10943 | If a mapped data store is accessed in a way inconsistent with the | |
10944 | specified @var{access} policy, no error is generated, but performance | |
10945 | may be negatively impacted and system errors, including program | |
10946 | termination, may result. Unlike the @var{usage} parameter of | |
10947 | @code{glBufferData}, @var{access} is not a hint, and does in fact | |
10948 | constrain the usage of the mapped data store on some GL implementations. | |
10949 | In order to achieve the highest performance available, a buffer object's | |
10950 | data store should be used in ways consistent with both its specified | |
10951 | @var{usage} and @var{access} parameters. | |
10952 | ||
10953 | A mapped data store must be unmapped with @code{glUnmapBuffer} before | |
10954 | its buffer object is used. Otherwise an error will be generated by any | |
10955 | GL command that attempts to dereference the buffer object's data store. | |
10956 | When a data store is unmapped, the pointer to its data store becomes | |
10957 | invalid. @code{glUnmapBuffer} returns @code{GL_TRUE} unless the data | |
10958 | store contents have become corrupt during the time the data store was | |
10959 | mapped. This can occur for system-specific reasons that affect the | |
10960 | availability of graphics memory, such as screen mode changes. In such | |
10961 | situations, @code{GL_FALSE} is returned and the data store contents are | |
10962 | undefined. An application must detect this rare condition and | |
10963 | reinitialize the data store. | |
10964 | ||
10965 | A buffer object's mapped data store is automatically unmapped when the | |
10966 | buffer object is deleted or its data store is recreated with | |
10967 | @code{glBufferData}. | |
10968 | ||
8925f36f AW |
10969 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
10970 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
10971 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
10972 | ||
10973 | @code{GL_INVALID_ENUM} is generated if @var{access} is not | |
10974 | @code{GL_READ_ONLY}, @code{GL_WRITE_ONLY}, or @code{GL_READ_WRITE}. | |
10975 | ||
10976 | @code{GL_OUT_OF_MEMORY} is generated when @code{glMapBuffer} is executed | |
10977 | if the GL is unable to map the buffer object's data store. This may | |
10978 | occur for a variety of system-specific reasons, such as the absence of | |
10979 | sufficient remaining virtual memory. | |
10980 | ||
10981 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
10982 | name 0 is bound to @var{target}. | |
10983 | ||
10984 | @code{GL_INVALID_OPERATION} is generated if @code{glMapBuffer} is | |
10985 | executed for a buffer object whose data store is already mapped. | |
10986 | ||
10987 | @code{GL_INVALID_OPERATION} is generated if @code{glUnmapBuffer} is | |
10988 | executed for a buffer object whose data store is not currently mapped. | |
10989 | ||
10990 | @code{GL_INVALID_OPERATION} is generated if @code{glMapBuffer} or | |
10991 | @code{glUnmapBuffer} is executed between the execution of @code{glBegin} | |
10992 | and the corresponding execution of @code{glEnd}. | |
10993 | ||
bb894c9d | 10994 | @end deftypefun |
8925f36f | 10995 | |
bb894c9d AW |
10996 | @deftypefun void glMapGrid1d un u1 u2 |
10997 | @deftypefunx void glMapGrid2d un u1 u2 vn v1 v2 | |
3c9b6116 AW |
10998 | Define a one- or two-dimensional mesh. |
10999 | ||
8925f36f AW |
11000 | @table @asis |
11001 | @item @var{un} | |
11002 | Specifies the number of partitions in the grid range interval [@var{u1}, | |
11003 | @var{u2}]. Must be positive. | |
11004 | ||
11005 | @item @var{u1} | |
11006 | @itemx @var{u2} | |
3c9b6116 AW |
11007 | Specify the mappings for integer grid domain values @r{@var{i}=0} and |
11008 | @r{@var{i}=@var{un}}. | |
8925f36f AW |
11009 | |
11010 | @item @var{vn} | |
11011 | Specifies the number of partitions in the grid range interval [@var{v1}, | |
11012 | @var{v2}] (@code{glMapGrid2} only). | |
11013 | ||
11014 | @item @var{v1} | |
11015 | @itemx @var{v2} | |
3c9b6116 AW |
11016 | Specify the mappings for integer grid domain values @r{@var{j}=0} and |
11017 | @r{@var{j}=@var{vn}} (@code{glMapGrid2} only). | |
8925f36f AW |
11018 | |
11019 | @end table | |
11020 | ||
8925f36f AW |
11021 | @code{glMapGrid} and @code{glEvalMesh} are used together to efficiently |
11022 | generate and evaluate a series of evenly-spaced map domain values. | |
11023 | @code{glEvalMesh} steps through the integer domain of a one- or | |
11024 | two-dimensional grid, whose range is the domain of the evaluation maps | |
11025 | specified by @code{glMap1} and @code{glMap2}. | |
11026 | ||
11027 | @code{glMapGrid1} and @code{glMapGrid2} specify the linear grid mappings | |
3c9b6116 AW |
11028 | between the @r{@var{i}} (or @r{@var{i}} and @r{@var{j}}) integer grid |
11029 | coordinates, to the @r{@var{u}} (or @r{@var{u}} and @r{@var{v}}) | |
11030 | floating-point evaluation map coordinates. See @code{glMap1} and | |
11031 | @code{glMap2} for details of how @r{@var{u}} and @r{@var{v}} coordinates | |
11032 | are evaluated. | |
8925f36f AW |
11033 | |
11034 | @code{glMapGrid1} specifies a single linear mapping such that integer | |
11035 | grid coordinate 0 maps exactly to @var{u1}, and integer grid coordinate | |
11036 | @var{un} maps exactly to @var{u2}. All other integer grid coordinates | |
3c9b6116 | 11037 | @r{@var{i}} are mapped so that |
8925f36f | 11038 | |
3c9b6116 | 11039 | @r{@var{u}=@var{i}(@var{u2}-@var{u1},)/@var{un}+@var{u1}} |
8925f36f AW |
11040 | |
11041 | @code{glMapGrid2} specifies two such linear mappings. One maps integer | |
3c9b6116 AW |
11042 | grid coordinate @r{@var{i}=0} exactly to @var{u1}, and integer grid |
11043 | coordinate @r{@var{i}=@var{un}} exactly to @var{u2}. The other maps | |
11044 | integer grid coordinate @r{@var{j}=0} exactly to @var{v1}, and integer | |
11045 | grid coordinate @r{@var{j}=@var{vn}} exactly to @var{v2}. Other integer | |
11046 | grid coordinates @r{@var{i}} and @r{@var{j}} are mapped such that | |
8925f36f | 11047 | |
3c9b6116 | 11048 | @r{@var{u}=@var{i}(@var{u2}-@var{u1},)/@var{un}+@var{u1}} |
8925f36f | 11049 | |
3c9b6116 | 11050 | @r{@var{v}=@var{j}(@var{v2}-@var{v1},)/@var{vn}+@var{v1}} |
8925f36f AW |
11051 | |
11052 | The mappings specified by @code{glMapGrid} are used identically by | |
11053 | @code{glEvalMesh} and @code{glEvalPoint}. | |
11054 | ||
8925f36f AW |
11055 | @code{GL_INVALID_VALUE} is generated if either @var{un} or @var{vn} is |
11056 | not positive. | |
11057 | ||
11058 | @code{GL_INVALID_OPERATION} is generated if @code{glMapGrid} is executed | |
11059 | between the execution of @code{glBegin} and the corresponding execution | |
11060 | of @code{glEnd}. | |
11061 | ||
bb894c9d | 11062 | @end deftypefun |
8925f36f | 11063 | |
bb894c9d AW |
11064 | @deftypefun void glMaterialf face pname param |
11065 | @deftypefunx void glMateriali face pname param | |
3c9b6116 AW |
11066 | Specify material parameters for the lighting model. |
11067 | ||
8925f36f AW |
11068 | @table @asis |
11069 | @item @var{face} | |
11070 | Specifies which face or faces are being updated. Must be one of | |
11071 | @code{GL_FRONT}, @code{GL_BACK}, or @code{GL_FRONT_AND_BACK}. | |
11072 | ||
11073 | @item @var{pname} | |
11074 | Specifies the single-valued material parameter of the face or faces that | |
11075 | is being updated. Must be @code{GL_SHININESS}. | |
11076 | ||
11077 | @item @var{param} | |
11078 | Specifies the value that parameter @code{GL_SHININESS} will be set to. | |
11079 | ||
11080 | @end table | |
11081 | ||
8925f36f AW |
11082 | @code{glMaterial} assigns values to material parameters. There are two |
11083 | matched sets of material parameters. One, the @var{front-facing} set, is | |
11084 | used to shade points, lines, bitmaps, and all polygons (when two-sided | |
11085 | lighting is disabled), or just front-facing polygons (when two-sided | |
11086 | lighting is enabled). The other set, @var{back-facing}, is used to shade | |
11087 | back-facing polygons only when two-sided lighting is enabled. Refer to | |
11088 | the @code{glLightModel} reference page for details concerning one- and | |
11089 | two-sided lighting calculations. | |
11090 | ||
11091 | @code{glMaterial} takes three arguments. The first, @var{face}, | |
11092 | specifies whether the @code{GL_FRONT} materials, the @code{GL_BACK} | |
11093 | materials, or both @code{GL_FRONT_AND_BACK} materials will be modified. | |
11094 | The second, @var{pname}, specifies which of several parameters in one or | |
11095 | both sets will be modified. The third, @var{params}, specifies what | |
11096 | value or values will be assigned to the specified parameter. | |
11097 | ||
11098 | Material parameters are used in the lighting equation that is optionally | |
11099 | applied to each vertex. The equation is discussed in the | |
11100 | @code{glLightModel} reference page. The parameters that can be specified | |
11101 | using @code{glMaterial}, and their interpretations by the lighting | |
11102 | equation, are as follows: | |
11103 | ||
11104 | @table @asis | |
11105 | @item @code{GL_AMBIENT} | |
11106 | @var{params} contains four integer or floating-point values that specify | |
11107 | the ambient RGBA reflectance of the material. Integer values are mapped | |
11108 | linearly such that the most positive representable value maps to 1.0, | |
3c9b6116 | 11109 | and the most negative representable value maps to @r{-1.0}. |
8925f36f AW |
11110 | Floating-point values are mapped directly. Neither integer nor |
11111 | floating-point values are clamped. The initial ambient reflectance for | |
11112 | both front- and back-facing materials is (0.2, 0.2, 0.2, 1.0). | |
11113 | ||
11114 | @item @code{GL_DIFFUSE} | |
11115 | @var{params} contains four integer or floating-point values that specify | |
11116 | the diffuse RGBA reflectance of the material. Integer values are mapped | |
11117 | linearly such that the most positive representable value maps to 1.0, | |
3c9b6116 | 11118 | and the most negative representable value maps to @r{-1.0}. |
8925f36f AW |
11119 | Floating-point values are mapped directly. Neither integer nor |
11120 | floating-point values are clamped. The initial diffuse reflectance for | |
11121 | both front- and back-facing materials is (0.8, 0.8, 0.8, 1.0). | |
11122 | ||
11123 | @item @code{GL_SPECULAR} | |
11124 | @var{params} contains four integer or floating-point values that specify | |
11125 | the specular RGBA reflectance of the material. Integer values are mapped | |
11126 | linearly such that the most positive representable value maps to 1.0, | |
3c9b6116 | 11127 | and the most negative representable value maps to @r{-1.0}. |
8925f36f AW |
11128 | Floating-point values are mapped directly. Neither integer nor |
11129 | floating-point values are clamped. The initial specular reflectance for | |
11130 | both front- and back-facing materials is (0, 0, 0, 1). | |
11131 | ||
11132 | @item @code{GL_EMISSION} | |
11133 | @var{params} contains four integer or floating-point values that specify | |
11134 | the RGBA emitted light intensity of the material. Integer values are | |
11135 | mapped linearly such that the most positive representable value maps to | |
3c9b6116 | 11136 | 1.0, and the most negative representable value maps to @r{-1.0}. |
8925f36f AW |
11137 | Floating-point values are mapped directly. Neither integer nor |
11138 | floating-point values are clamped. The initial emission intensity for | |
11139 | both front- and back-facing materials is (0, 0, 0, 1). | |
11140 | ||
11141 | @item @code{GL_SHININESS} | |
11142 | @var{params} is a single integer or floating-point value that specifies | |
11143 | the RGBA specular exponent of the material. Integer and floating-point | |
3c9b6116 | 11144 | values are mapped directly. Only values in the range @r{[0,128]} are |
8925f36f AW |
11145 | accepted. The initial specular exponent for both front- and back-facing |
11146 | materials is 0. | |
11147 | ||
11148 | @item @code{GL_AMBIENT_AND_DIFFUSE} | |
11149 | Equivalent to calling @code{glMaterial} twice with the same parameter | |
11150 | values, once with @code{GL_AMBIENT} and once with @code{GL_DIFFUSE}. | |
11151 | ||
11152 | @item @code{GL_COLOR_INDEXES} | |
11153 | @var{params} contains three integer or floating-point values specifying | |
11154 | the color indices for ambient, diffuse, and specular lighting. These | |
11155 | three values, and @code{GL_SHININESS}, are the only material values used | |
11156 | by the color index mode lighting equation. Refer to the | |
11157 | @code{glLightModel} reference page for a discussion of color index | |
11158 | lighting. | |
11159 | ||
11160 | @end table | |
11161 | ||
8925f36f AW |
11162 | @code{GL_INVALID_ENUM} is generated if either @var{face} or @var{pname} |
11163 | is not an accepted value. | |
11164 | ||
11165 | @code{GL_INVALID_VALUE} is generated if a specular exponent outside the | |
3c9b6116 | 11166 | range @r{[0,128]} is specified. |
8925f36f | 11167 | |
bb894c9d | 11168 | @end deftypefun |
8925f36f | 11169 | |
bb894c9d | 11170 | @deftypefun void glMatrixMode mode |
3c9b6116 AW |
11171 | Specify which matrix is the current matrix. |
11172 | ||
8925f36f AW |
11173 | @table @asis |
11174 | @item @var{mode} | |
11175 | Specifies which matrix stack is the target for subsequent matrix | |
11176 | operations. Three values are accepted: @code{GL_MODELVIEW}, | |
11177 | @code{GL_PROJECTION}, and @code{GL_TEXTURE}. The initial value is | |
11178 | @code{GL_MODELVIEW}. Additionally, if the @code{ARB_imaging} extension | |
11179 | is supported, @code{GL_COLOR} is also accepted. | |
11180 | ||
11181 | @end table | |
11182 | ||
8925f36f AW |
11183 | @code{glMatrixMode} sets the current matrix mode. @var{mode} can assume |
11184 | one of four values: | |
11185 | ||
11186 | @table @asis | |
11187 | @item @code{GL_MODELVIEW} | |
11188 | Applies subsequent matrix operations to the modelview matrix stack. | |
11189 | ||
11190 | @item @code{GL_PROJECTION} | |
11191 | Applies subsequent matrix operations to the projection matrix stack. | |
11192 | ||
11193 | @item @code{GL_TEXTURE} | |
11194 | Applies subsequent matrix operations to the texture matrix stack. | |
11195 | ||
11196 | @item @code{GL_COLOR} | |
11197 | Applies subsequent matrix operations to the color matrix stack. | |
11198 | ||
11199 | @end table | |
11200 | ||
11201 | To find out which matrix stack is currently the target of all matrix | |
11202 | operations, call @code{glGet} with argument @code{GL_MATRIX_MODE}. The | |
11203 | initial value is @code{GL_MODELVIEW}. | |
11204 | ||
8925f36f AW |
11205 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
11206 | value. | |
11207 | ||
11208 | @code{GL_INVALID_OPERATION} is generated if @code{glMatrixMode} is | |
11209 | executed between the execution of @code{glBegin} and the corresponding | |
11210 | execution of @code{glEnd}. | |
11211 | ||
bb894c9d | 11212 | @end deftypefun |
8925f36f | 11213 | |
bb894c9d | 11214 | @deftypefun void glMinmax target internalformat sink |
3c9b6116 AW |
11215 | Define minmax table. |
11216 | ||
8925f36f AW |
11217 | @table @asis |
11218 | @item @var{target} | |
11219 | The minmax table whose parameters are to be set. Must be | |
11220 | @code{GL_MINMAX}. | |
11221 | ||
11222 | @item @var{internalformat} | |
11223 | The format of entries in the minmax table. Must be one of | |
11224 | @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, | |
11225 | @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
11226 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
11227 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
11228 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
11229 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
11230 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
11231 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
11232 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
11233 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
11234 | @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
11235 | ||
11236 | @item @var{sink} | |
11237 | If @code{GL_TRUE}, pixels will be consumed by the minmax process and no | |
11238 | drawing or texture loading will take place. If @code{GL_FALSE}, pixels | |
11239 | will proceed to the final conversion process after minmax. | |
11240 | ||
11241 | @end table | |
11242 | ||
8925f36f AW |
11243 | When @code{GL_MINMAX} is enabled, the RGBA components of incoming pixels |
11244 | are compared to the minimum and maximum values for each component, which | |
11245 | are stored in the two-element minmax table. (The first element stores | |
11246 | the minima, and the second element stores the maxima.) If a pixel | |
11247 | component is greater than the corresponding component in the maximum | |
11248 | element, then the maximum element is updated with the pixel component | |
11249 | value. If a pixel component is less than the corresponding component in | |
11250 | the minimum element, then the minimum element is updated with the pixel | |
11251 | component value. (In both cases, if the internal format of the minmax | |
11252 | table includes luminance, then the R color component of incoming pixels | |
11253 | is used for comparison.) The contents of the minmax table may be | |
11254 | retrieved at a later time by calling @code{glGetMinmax}. The minmax | |
11255 | operation is enabled or disabled by calling @code{glEnable} or | |
11256 | @code{glDisable}, respectively, with an argument of @code{GL_MINMAX}. | |
11257 | ||
11258 | @code{glMinmax} redefines the current minmax table to have entries of | |
11259 | the format specified by @var{internalformat}. The maximum element is | |
11260 | initialized with the smallest possible component values, and the minimum | |
11261 | element is initialized with the largest possible component values. The | |
11262 | values in the previous minmax table, if any, are lost. If @var{sink} is | |
11263 | @code{GL_TRUE}, then pixels are discarded after minmax; no further | |
11264 | processing of the pixels takes place, and no drawing, texture loading, | |
11265 | or pixel readback will result. | |
11266 | ||
11267 | ||
11268 | ||
8925f36f AW |
11269 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
11270 | allowable values. | |
11271 | ||
11272 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
11273 | of the allowable values. | |
11274 | ||
11275 | @code{GL_INVALID_OPERATION} is generated if @code{glMinmax} is executed | |
11276 | between the execution of @code{glBegin} and the corresponding execution | |
11277 | of @code{glEnd}. | |
11278 | ||
bb894c9d | 11279 | @end deftypefun |
8925f36f | 11280 | |
bb894c9d | 11281 | @deftypefun void glMultiDrawArrays mode first count primcount |
3c9b6116 AW |
11282 | Render multiple sets of primitives from array data. |
11283 | ||
8925f36f AW |
11284 | @table @asis |
11285 | @item @var{mode} | |
11286 | Specifies what kind of primitives to render. Symbolic constants | |
11287 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, | |
11288 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
11289 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
11290 | @code{GL_POLYGON} are accepted. | |
11291 | ||
11292 | @item @var{first} | |
11293 | Points to an array of starting indices in the enabled arrays. | |
11294 | ||
11295 | @item @var{count} | |
11296 | Points to an array of the number of indices to be rendered. | |
11297 | ||
11298 | @item @var{primcount} | |
11299 | Specifies the size of the first and count | |
11300 | ||
11301 | @end table | |
11302 | ||
8925f36f AW |
11303 | @code{glMultiDrawArrays} specifies multiple sets of geometric primitives |
11304 | with very few subroutine calls. Instead of calling a GL procedure to | |
11305 | pass each individual vertex, normal, texture coordinate, edge flag, or | |
11306 | color, you can prespecify separate arrays of vertices, normals, and | |
11307 | colors and use them to construct a sequence of primitives with a single | |
11308 | call to @code{glMultiDrawArrays}. | |
11309 | ||
11310 | @code{glMultiDrawArrays} behaves identically to @code{glDrawArrays} | |
11311 | except that @var{primcount} separate ranges of elements are specified | |
11312 | instead. | |
11313 | ||
11314 | When @code{glMultiDrawArrays} is called, it uses @var{count} sequential | |
11315 | elements from each enabled array to construct a sequence of geometric | |
11316 | primitives, beginning with element @var{first}. @var{mode} specifies | |
11317 | what kind of primitives are constructed, and how the array elements | |
11318 | construct those primitives. If @code{GL_VERTEX_ARRAY} is not enabled, no | |
11319 | geometric primitives are generated. | |
11320 | ||
11321 | Vertex attributes that are modified by @code{glMultiDrawArrays} have an | |
11322 | unspecified value after @code{glMultiDrawArrays} returns. For example, | |
11323 | if @code{GL_COLOR_ARRAY} is enabled, the value of the current color is | |
11324 | undefined after @code{glMultiDrawArrays} executes. Attributes that | |
11325 | aren't modified remain well defined. | |
11326 | ||
8925f36f AW |
11327 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
11328 | value. | |
11329 | ||
11330 | @code{GL_INVALID_VALUE} is generated if @var{primcount} is negative. | |
11331 | ||
11332 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
11333 | name is bound to an enabled array and the buffer object's data store is | |
11334 | currently mapped. | |
11335 | ||
11336 | @code{GL_INVALID_OPERATION} is generated if @code{glMultiDrawArrays} is | |
11337 | executed between the execution of @code{glBegin} and the corresponding | |
11338 | @code{glEnd}. | |
11339 | ||
bb894c9d | 11340 | @end deftypefun |
8925f36f | 11341 | |
bb894c9d | 11342 | @deftypefun void glMultiDrawElements mode count type indices primcount |
3c9b6116 AW |
11343 | Render multiple sets of primitives by specifying indices of array data |
11344 | elements. | |
11345 | ||
8925f36f AW |
11346 | @table @asis |
11347 | @item @var{mode} | |
11348 | Specifies what kind of primitives to render. Symbolic constants | |
11349 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, | |
11350 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
11351 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
11352 | @code{GL_POLYGON} are accepted. | |
11353 | ||
11354 | @item @var{count} | |
11355 | Points to an array of the elements counts. | |
11356 | ||
11357 | @item @var{type} | |
11358 | Specifies the type of the values in @var{indices}. Must be one of | |
11359 | @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or | |
11360 | @code{GL_UNSIGNED_INT}. | |
11361 | ||
11362 | @item @var{indices} | |
11363 | Specifies a pointer to the location where the indices are stored. | |
11364 | ||
11365 | @item @var{primcount} | |
11366 | Specifies the size of the @var{count} array. | |
11367 | ||
11368 | @end table | |
11369 | ||
8925f36f AW |
11370 | @code{glMultiDrawElements} specifies multiple sets of geometric |
11371 | primitives with very few subroutine calls. Instead of calling a GL | |
11372 | function to pass each individual vertex, normal, texture coordinate, | |
11373 | edge flag, or color, you can prespecify separate arrays of vertices, | |
11374 | normals, and so on, and use them to construct a sequence of primitives | |
11375 | with a single call to @code{glMultiDrawElements}. | |
11376 | ||
11377 | @code{glMultiDrawElements} is identical in operation to | |
11378 | @code{glDrawElements} except that @var{primcount} separate lists of | |
11379 | elements are specified. | |
11380 | ||
11381 | Vertex attributes that are modified by @code{glMultiDrawElements} have | |
11382 | an unspecified value after @code{glMultiDrawElements} returns. For | |
11383 | example, if @code{GL_COLOR_ARRAY} is enabled, the value of the current | |
11384 | color is undefined after @code{glMultiDrawElements} executes. Attributes | |
11385 | that aren't modified maintain their previous values. | |
11386 | ||
8925f36f AW |
11387 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
11388 | value. | |
11389 | ||
11390 | @code{GL_INVALID_VALUE} is generated if @var{primcount} is negative. | |
11391 | ||
11392 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
11393 | name is bound to an enabled array or the element array and the buffer | |
11394 | object's data store is currently mapped. | |
11395 | ||
11396 | @code{GL_INVALID_OPERATION} is generated if @code{glMultiDrawElements} | |
11397 | is executed between the execution of @code{glBegin} and the | |
11398 | corresponding @code{glEnd}. | |
11399 | ||
bb894c9d | 11400 | @end deftypefun |
8925f36f | 11401 | |
bb894c9d AW |
11402 | @deftypefun void glMultiTexCoord1i target s |
11403 | @deftypefunx void glMultiTexCoord1d target s | |
11404 | @deftypefunx void glMultiTexCoord2i target s t | |
11405 | @deftypefunx void glMultiTexCoord2d target s t | |
11406 | @deftypefunx void glMultiTexCoord3i target s t r | |
11407 | @deftypefunx void glMultiTexCoord3d target s t r | |
11408 | @deftypefunx void glMultiTexCoord4i target s t r q | |
11409 | @deftypefunx void glMultiTexCoord4d target s t r q | |
3c9b6116 AW |
11410 | Set the current texture coordinates. |
11411 | ||
8925f36f AW |
11412 | @table @asis |
11413 | @item @var{target} | |
11414 | Specifies the texture unit whose coordinates should be modified. The | |
11415 | number of texture units is implementation dependent, but must be at | |
11416 | least two. Symbolic constant must be one of | |
3c9b6116 | 11417 | @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to |
8925f36f AW |
11418 | @code{GL_MAX_TEXTURE_COORDS} - 1, which is an implementation-dependent |
11419 | value. | |
11420 | ||
11421 | @item @var{s} | |
11422 | @itemx @var{t} | |
11423 | @itemx @var{r} | |
11424 | @itemx @var{q} | |
11425 | Specify @var{s}, @var{t}, @var{r}, and @var{q} texture coordinates for | |
11426 | @var{target} texture unit. Not all parameters are present in all forms | |
11427 | of the command. | |
11428 | ||
11429 | @end table | |
11430 | ||
8925f36f AW |
11431 | @code{glMultiTexCoord} specifies texture coordinates in one, two, three, |
11432 | or four dimensions. @code{glMultiTexCoord1} sets the current texture | |
3c9b6116 AW |
11433 | coordinates to @r{(@var{s},001)}; a call to @code{glMultiTexCoord2} sets |
11434 | them to @r{(@var{s},@var{t}01)}. Similarly, @code{glMultiTexCoord3} | |
11435 | specifies the texture coordinates as @r{(@var{s},@var{t}@var{r}1)}, and | |
11436 | @code{glMultiTexCoord4} defines all four components explicitly as | |
11437 | @r{(@var{s},@var{t}@var{r}@var{q})}. | |
8925f36f AW |
11438 | |
11439 | The current texture coordinates are part of the data that is associated | |
11440 | with each vertex and with the current raster position. Initially, the | |
3c9b6116 | 11441 | values for @r{(@var{s},@var{t}@var{r}@var{q})} are @r{(0,001)}. |
8925f36f AW |
11442 | |
11443 | ||
11444 | ||
bb894c9d | 11445 | @end deftypefun |
8925f36f | 11446 | |
bb894c9d | 11447 | @deftypefun void glMultMatrixd m |
3c9b6116 AW |
11448 | Multiply the current matrix with the specified matrix. |
11449 | ||
8925f36f AW |
11450 | @table @asis |
11451 | @item @var{m} | |
11452 | Points to 16 consecutive values that are used as the elements of a | |
3c9b6116 | 11453 | @r{4×4} column-major matrix. |
8925f36f AW |
11454 | |
11455 | @end table | |
11456 | ||
8925f36f AW |
11457 | @code{glMultMatrix} multiplies the current matrix with the one specified |
11458 | using @var{m}, and replaces the current matrix with the product. | |
11459 | ||
11460 | The current matrix is determined by the current matrix mode (see | |
11461 | @code{glMatrixMode}). It is either the projection matrix, modelview | |
11462 | matrix, or the texture matrix. | |
11463 | ||
8925f36f AW |
11464 | @code{GL_INVALID_OPERATION} is generated if @code{glMultMatrix} is |
11465 | executed between the execution of @code{glBegin} and the corresponding | |
11466 | execution of @code{glEnd}. | |
11467 | ||
bb894c9d | 11468 | @end deftypefun |
8925f36f | 11469 | |
bb894c9d | 11470 | @deftypefun void glMultTransposeMatrixd m |
3c9b6116 AW |
11471 | Multiply the current matrix with the specified row-major ordered matrix. |
11472 | ||
8925f36f AW |
11473 | @table @asis |
11474 | @item @var{m} | |
11475 | Points to 16 consecutive values that are used as the elements of a | |
3c9b6116 | 11476 | @r{4×4} row-major matrix. |
8925f36f AW |
11477 | |
11478 | @end table | |
11479 | ||
8925f36f AW |
11480 | @code{glMultTransposeMatrix} multiplies the current matrix with the one |
11481 | specified using @var{m}, and replaces the current matrix with the | |
11482 | product. | |
11483 | ||
11484 | The current matrix is determined by the current matrix mode (see | |
11485 | @code{glMatrixMode}). It is either the projection matrix, modelview | |
11486 | matrix, or the texture matrix. | |
11487 | ||
8925f36f AW |
11488 | @code{GL_INVALID_OPERATION} is generated if @code{glMultTransposeMatrix} |
11489 | is executed between the execution of @code{glBegin} and the | |
11490 | corresponding execution of @code{glEnd}. | |
11491 | ||
bb894c9d | 11492 | @end deftypefun |
8925f36f | 11493 | |
bb894c9d AW |
11494 | @deftypefun void glNewList list mode |
11495 | @deftypefunx void glEndList | |
3c9b6116 AW |
11496 | Create or replace a display list. |
11497 | ||
8925f36f AW |
11498 | @table @asis |
11499 | @item @var{list} | |
11500 | Specifies the display-list name. | |
11501 | ||
11502 | @item @var{mode} | |
11503 | Specifies the compilation mode, which can be @code{GL_COMPILE} or | |
11504 | @code{GL_COMPILE_AND_EXECUTE}. | |
11505 | ||
11506 | @end table | |
11507 | ||
8925f36f AW |
11508 | Display lists are groups of GL commands that have been stored for |
11509 | subsequent execution. Display lists are created with @code{glNewList}. | |
11510 | All subsequent commands are placed in the display list, in the order | |
11511 | issued, until @code{glEndList} is called. | |
11512 | ||
11513 | @code{glNewList} has two arguments. The first argument, @var{list}, is a | |
11514 | positive integer that becomes the unique name for the display list. | |
11515 | Names can be created and reserved with @code{glGenLists} and tested for | |
11516 | uniqueness with @code{glIsList}. The second argument, @var{mode}, is a | |
11517 | symbolic constant that can assume one of two values: | |
11518 | ||
11519 | @table @asis | |
11520 | @item @code{GL_COMPILE} | |
11521 | Commands are merely compiled. | |
11522 | ||
11523 | @item @code{GL_COMPILE_AND_EXECUTE} | |
11524 | Commands are executed as they are compiled into the display list. | |
11525 | ||
11526 | @end table | |
11527 | ||
11528 | Certain commands are not compiled into the display list but are executed | |
11529 | immediately, regardless of the display-list mode. These commands are | |
11530 | @code{glAreTexturesResident}, @code{glColorPointer}, | |
11531 | @code{glDeleteLists}, @code{glDeleteTextures}, | |
11532 | @code{glDisableClientState}, @code{glEdgeFlagPointer}, | |
11533 | @code{glEnableClientState}, @code{glFeedbackBuffer}, @code{glFinish}, | |
11534 | @code{glFlush}, @code{glGenLists}, @code{glGenTextures}, | |
11535 | @code{glIndexPointer}, @code{glInterleavedArrays}, @code{glIsEnabled}, | |
11536 | @code{glIsList}, @code{glIsTexture}, @code{glNormalPointer}, | |
11537 | @code{glPopClientAttrib}, @code{glPixelStore}, | |
11538 | @code{glPushClientAttrib}, @code{glReadPixels}, @code{glRenderMode}, | |
11539 | @code{glSelectBuffer}, @code{glTexCoordPointer}, @code{glVertexPointer}, | |
11540 | and all of the @code{glGet} commands. | |
11541 | ||
11542 | Similarly, @code{glTexImage1D}, @code{glTexImage2D}, and | |
11543 | @code{glTexImage3D} are executed immediately and not compiled into the | |
11544 | display list when their first argument is @code{GL_PROXY_TEXTURE_1D}, | |
11545 | @code{GL_PROXY_TEXTURE_1D}, or @code{GL_PROXY_TEXTURE_3D}, respectively. | |
11546 | ||
11547 | When the @code{ARB_imaging} extension is supported, @code{glHistogram} | |
11548 | executes immediately when its argument is @code{GL_PROXY_HISTOGRAM}. | |
11549 | Similarly, @code{glColorTable} executes immediately when its first | |
11550 | argument is @code{GL_PROXY_COLOR_TABLE}, | |
11551 | @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or | |
11552 | @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}. | |
11553 | ||
11554 | For OpenGL versions 1.3 and greater, or when the @code{ARB_multitexture} | |
11555 | extension is supported, @code{glClientActiveTexture} is not compiled | |
11556 | into display lists, but executed immediately. | |
11557 | ||
11558 | When @code{glEndList} is encountered, the display-list definition is | |
11559 | completed by associating the list with the unique name @var{list} | |
11560 | (specified in the @code{glNewList} command). If a display list with name | |
11561 | @var{list} already exists, it is replaced only when @code{glEndList} is | |
11562 | called. | |
11563 | ||
8925f36f AW |
11564 | @code{GL_INVALID_VALUE} is generated if @var{list} is 0. |
11565 | ||
11566 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted | |
11567 | value. | |
11568 | ||
11569 | @code{GL_INVALID_OPERATION} is generated if @code{glEndList} is called | |
11570 | without a preceding @code{glNewList}, or if @code{glNewList} is called | |
11571 | while a display list is being defined. | |
11572 | ||
11573 | @code{GL_INVALID_OPERATION} is generated if @code{glNewList} or | |
11574 | @code{glEndList} is executed between the execution of @code{glBegin} and | |
11575 | the corresponding execution of @code{glEnd}. | |
11576 | ||
11577 | @code{GL_OUT_OF_MEMORY} is generated if there is insufficient memory to | |
11578 | compile the display list. If the GL version is 1.1 or greater, no change | |
11579 | is made to the previous contents of the display list, if any, and no | |
11580 | other change is made to the GL state. (It is as if no attempt had been | |
11581 | made to create the new display list.) | |
11582 | ||
bb894c9d | 11583 | @end deftypefun |
8925f36f | 11584 | |
bb894c9d | 11585 | @deftypefun void glNormalPointer type stride pointer |
3c9b6116 AW |
11586 | Define an array of normals. |
11587 | ||
8925f36f AW |
11588 | @table @asis |
11589 | @item @var{type} | |
11590 | Specifies the data type of each coordinate in the array. Symbolic | |
11591 | constants @code{GL_BYTE}, @code{GL_SHORT}, @code{GL_INT}, | |
11592 | @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value is | |
11593 | @code{GL_FLOAT}. | |
11594 | ||
11595 | @item @var{stride} | |
11596 | Specifies the byte offset between consecutive normals. If @var{stride} | |
11597 | is 0, the normals are understood to be tightly packed in the array. The | |
11598 | initial value is 0. | |
11599 | ||
11600 | @item @var{pointer} | |
11601 | Specifies a pointer to the first coordinate of the first normal in the | |
11602 | array. The initial value is 0. | |
11603 | ||
11604 | @end table | |
11605 | ||
8925f36f AW |
11606 | @code{glNormalPointer} specifies the location and data format of an |
11607 | array of normals to use when rendering. @var{type} specifies the data | |
11608 | type of each normal coordinate, and @var{stride} specifies the byte | |
11609 | stride from one normal to the next, allowing vertices and attributes to | |
11610 | be packed into a single array or stored in separate arrays. | |
11611 | (Single-array storage may be more efficient on some implementations; see | |
11612 | @code{glInterleavedArrays}.) | |
11613 | ||
11614 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
11615 | target (see @code{glBindBuffer}) while a normal array is specified, | |
11616 | @var{pointer} is treated as a byte offset into the buffer object's data | |
11617 | store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING}) | |
11618 | is saved as normal vertex array client-side state | |
11619 | (@code{GL_NORMAL_ARRAY_BUFFER_BINDING}). | |
11620 | ||
11621 | When a normal array is specified, @var{type}, @var{stride}, and | |
11622 | @var{pointer} are saved as client-side state, in addition to the current | |
11623 | vertex array buffer object binding. | |
11624 | ||
11625 | To enable and disable the normal array, call @code{glEnableClientState} | |
11626 | and @code{glDisableClientState} with the argument | |
11627 | @code{GL_NORMAL_ARRAY}. If enabled, the normal array is used when | |
11628 | @code{glDrawArrays}, @code{glMultiDrawArrays}, @code{glDrawElements}, | |
11629 | @code{glMultiDrawElements}, @code{glDrawRangeElements}, or | |
11630 | @code{glArrayElement} is called. | |
11631 | ||
8925f36f AW |
11632 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted |
11633 | value. | |
11634 | ||
11635 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
11636 | ||
bb894c9d | 11637 | @end deftypefun |
8925f36f | 11638 | |
bb894c9d AW |
11639 | @deftypefun void glNormal3d nx ny nz |
11640 | @deftypefunx void glNormal3i nx ny nz | |
3c9b6116 AW |
11641 | Set the current normal vector. |
11642 | ||
8925f36f AW |
11643 | @table @asis |
11644 | @item @var{nx} | |
11645 | @itemx @var{ny} | |
11646 | @itemx @var{nz} | |
3c9b6116 AW |
11647 | Specify the @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} coordinates of the |
11648 | new current normal. The initial value of the current normal is the unit | |
11649 | vector, (0, 0, 1). | |
8925f36f AW |
11650 | |
11651 | ||
11652 | ||
11653 | @end table | |
11654 | ||
8925f36f AW |
11655 | The current normal is set to the given coordinates whenever |
11656 | @code{glNormal} is issued. Byte, short, or integer arguments are | |
11657 | converted to floating-point format with a linear mapping that maps the | |
11658 | most positive representable integer value to 1.0 and the most negative | |
3c9b6116 | 11659 | representable integer value to @r{-1.0}. |
8925f36f AW |
11660 | |
11661 | Normals specified with @code{glNormal} need not have unit length. If | |
11662 | @code{GL_NORMALIZE} is enabled, then normals of any length specified | |
11663 | with @code{glNormal} are normalized after transformation. If | |
11664 | @code{GL_RESCALE_NORMAL} is enabled, normals are scaled by a scaling | |
11665 | factor derived from the modelview matrix. @code{GL_RESCALE_NORMAL} | |
11666 | requires that the originally specified normals were of unit length, and | |
11667 | that the modelview matrix contain only uniform scales for proper | |
11668 | results. To enable and disable normalization, call @code{glEnable} and | |
11669 | @code{glDisable} with either @code{GL_NORMALIZE} or | |
11670 | @code{GL_RESCALE_NORMAL}. Normalization is initially disabled. | |
11671 | ||
bb894c9d | 11672 | @end deftypefun |
8925f36f | 11673 | |
bb894c9d | 11674 | @deftypefun void glOrtho left right bottom top nearVal farVal |
3c9b6116 AW |
11675 | Multiply the current matrix with an orthographic matrix. |
11676 | ||
8925f36f AW |
11677 | @table @asis |
11678 | @item @var{left} | |
11679 | @itemx @var{right} | |
11680 | Specify the coordinates for the left and right vertical clipping planes. | |
11681 | ||
11682 | @item @var{bottom} | |
11683 | @itemx @var{top} | |
11684 | Specify the coordinates for the bottom and top horizontal clipping | |
11685 | planes. | |
11686 | ||
11687 | @item @var{nearVal} | |
11688 | @itemx @var{farVal} | |
11689 | Specify the distances to the nearer and farther depth clipping planes. | |
11690 | These values are negative if the plane is to be behind the viewer. | |
11691 | ||
11692 | @end table | |
11693 | ||
8925f36f AW |
11694 | @code{glOrtho} describes a transformation that produces a parallel |
11695 | projection. The current matrix (see @code{glMatrixMode}) is multiplied | |
11696 | by this matrix and the result replaces the current matrix, as if | |
11697 | @code{glMultMatrix} were called with the following matrix as its | |
11698 | argument: | |
11699 | ||
3c9b6116 | 11700 | @r{((2/@var{right}-@var{left},, 0 0 @var{t}_@var{x},), (0 |
8925f36f AW |
11701 | 2/@var{top}-@var{bottom},, 0 @var{t}_@var{y},), (0 0 |
11702 | -2/@var{farVal}-@var{nearVal},, @var{t}_@var{z},), (0 0 0 1),)} | |
11703 | ||
11704 | where | |
3c9b6116 | 11705 | @r{@var{t}_@var{x}=-@var{right}+@var{left},/@var{right}-@var{left},,}@r{@var{t}_@var{y}=-@var{top}+@var{bottom},/@var{top}-@var{bottom},,}@r{@var{t}_@var{z}=-@var{farVal}+@var{nearVal},/@var{farVal}-@var{nearVal},,} |
8925f36f AW |
11706 | |
11707 | Typically, the matrix mode is @code{GL_PROJECTION}, and | |
3c9b6116 AW |
11708 | @r{(@var{left},@var{bottom}-@var{nearVal})} and |
11709 | @r{(@var{right},@var{top}-@var{nearVal})} specify the points on the near | |
11710 | clipping plane that are mapped to the lower left and upper right corners | |
11711 | of the window, respectively, assuming that the eye is located at (0, 0, | |
11712 | 0). @r{-@var{farVal}} specifies the location of the far clipping plane. | |
11713 | Both @var{nearVal} and @var{farVal} can be either positive or negative. | |
8925f36f AW |
11714 | |
11715 | Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the | |
11716 | current matrix stack. | |
11717 | ||
8925f36f AW |
11718 | @code{GL_INVALID_VALUE} is generated if @var{left} = @var{right}, or |
11719 | @var{bottom} = @var{top}, or @var{near} = @var{far}. | |
11720 | ||
11721 | @code{GL_INVALID_OPERATION} is generated if @code{glOrtho} is executed | |
11722 | between the execution of @code{glBegin} and the corresponding execution | |
11723 | of @code{glEnd}. | |
11724 | ||
bb894c9d | 11725 | @end deftypefun |
8925f36f | 11726 | |
bb894c9d | 11727 | @deftypefun void glPassThrough token |
3c9b6116 AW |
11728 | Place a marker in the feedback buffer. |
11729 | ||
8925f36f AW |
11730 | @table @asis |
11731 | @item @var{token} | |
11732 | Specifies a marker value to be placed in the feedback buffer following a | |
11733 | @code{GL_PASS_THROUGH_TOKEN}. | |
11734 | ||
11735 | @end table | |
11736 | ||
8925f36f AW |
11737 | |
11738 | ||
11739 | Feedback is a GL render mode. The mode is selected by calling | |
11740 | @code{glRenderMode} with @code{GL_FEEDBACK}. When the GL is in feedback | |
11741 | mode, no pixels are produced by rasterization. Instead, information | |
11742 | about primitives that would have been rasterized is fed back to the | |
11743 | application using the GL. See the @code{glFeedbackBuffer} reference page | |
11744 | for a description of the feedback buffer and the values in it. | |
11745 | ||
11746 | @code{glPassThrough} inserts a user-defined marker in the feedback | |
11747 | buffer when it is executed in feedback mode. @var{token} is returned as | |
11748 | if it were a primitive; it is indicated with its own unique identifying | |
11749 | value: @code{GL_PASS_THROUGH_TOKEN}. The order of @code{glPassThrough} | |
11750 | commands with respect to the specification of graphics primitives is | |
11751 | maintained. | |
11752 | ||
8925f36f AW |
11753 | @code{GL_INVALID_OPERATION} is generated if @code{glPassThrough} is |
11754 | executed between the execution of @code{glBegin} and the corresponding | |
11755 | execution of @code{glEnd}. | |
11756 | ||
bb894c9d | 11757 | @end deftypefun |
8925f36f | 11758 | |
bb894c9d AW |
11759 | @deftypefun void glPixelStoref pname param |
11760 | @deftypefunx void glPixelStorei pname param | |
3c9b6116 AW |
11761 | Set pixel storage modes. |
11762 | ||
8925f36f AW |
11763 | @table @asis |
11764 | @item @var{pname} | |
11765 | Specifies the symbolic name of the parameter to be set. Six values | |
11766 | affect the packing of pixel data into memory: @code{GL_PACK_SWAP_BYTES}, | |
11767 | @code{GL_PACK_LSB_FIRST}, @code{GL_PACK_ROW_LENGTH}, | |
11768 | @code{GL_PACK_IMAGE_HEIGHT}, @code{GL_PACK_SKIP_PIXELS}, | |
11769 | @code{GL_PACK_SKIP_ROWS}, @code{GL_PACK_SKIP_IMAGES}, and | |
11770 | @code{GL_PACK_ALIGNMENT}. Six more affect the unpacking of pixel data | |
11771 | @var{from} memory: @code{GL_UNPACK_SWAP_BYTES}, | |
11772 | @code{GL_UNPACK_LSB_FIRST}, @code{GL_UNPACK_ROW_LENGTH}, | |
11773 | @code{GL_UNPACK_IMAGE_HEIGHT}, @code{GL_UNPACK_SKIP_PIXELS}, | |
11774 | @code{GL_UNPACK_SKIP_ROWS}, @code{GL_UNPACK_SKIP_IMAGES}, and | |
11775 | @code{GL_UNPACK_ALIGNMENT}. | |
11776 | ||
11777 | @item @var{param} | |
11778 | Specifies the value that @var{pname} is set to. | |
11779 | ||
11780 | @end table | |
11781 | ||
8925f36f AW |
11782 | @code{glPixelStore} sets pixel storage modes that affect the operation |
11783 | of subsequent @code{glDrawPixels} and @code{glReadPixels} as well as the | |
11784 | unpacking of polygon stipple patterns (see @code{glPolygonStipple}), | |
11785 | bitmaps (see @code{glBitmap}), texture patterns (see | |
11786 | @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D}, | |
11787 | @code{glTexSubImage1D}, @code{glTexSubImage2D}, @code{glTexSubImage3D}). | |
11788 | Additionally, if the @code{ARB_imaging} extension is supported, pixel | |
11789 | storage modes affect convolution filters (see | |
11790 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and | |
11791 | @code{glSeparableFilter2D}, color table (see @code{glColorTable}, and | |
11792 | @code{glColorSubTable}, and unpacking histogram (See | |
11793 | @code{glHistogram}), and minmax (See @code{glMinmax}) data. | |
11794 | ||
11795 | @var{pname} is a symbolic constant indicating the parameter to be set, | |
11796 | and @var{param} is the new value. Six of the twelve storage parameters | |
11797 | affect how pixel data is returned to client memory. They are as follows: | |
11798 | ||
11799 | @table @asis | |
11800 | @item @code{GL_PACK_SWAP_BYTES} | |
11801 | If true, byte ordering for multibyte color components, depth components, | |
11802 | color indices, or stencil indices is reversed. That is, if a four-byte | |
3c9b6116 AW |
11803 | component consists of bytes @r{@var{b}_0}, @r{@var{b}_1}, @r{@var{b}_2}, |
11804 | @r{@var{b}_3}, it is stored in memory as @r{@var{b}_3}, @r{@var{b}_2}, | |
11805 | @r{@var{b}_1}, @r{@var{b}_0} if @code{GL_PACK_SWAP_BYTES} is true. | |
11806 | @code{GL_PACK_SWAP_BYTES} has no effect on the memory order of | |
11807 | components within a pixel, only on the order of bytes within components | |
11808 | or indices. For example, the three components of a @code{GL_RGB} format | |
11809 | pixel are always stored with red first, green second, and blue third, | |
11810 | regardless of the value of @code{GL_PACK_SWAP_BYTES}. | |
8925f36f AW |
11811 | |
11812 | @item @code{GL_PACK_LSB_FIRST} | |
11813 | If true, bits are ordered within a byte from least significant to most | |
11814 | significant; otherwise, the first bit in each byte is the most | |
11815 | significant one. This parameter is significant for bitmap data only. | |
11816 | ||
11817 | @item @code{GL_PACK_ROW_LENGTH} | |
11818 | If greater than 0, @code{GL_PACK_ROW_LENGTH} defines the number of | |
11819 | pixels in a row. If the first pixel of a row is placed at location | |
3c9b6116 AW |
11820 | @r{@var{p}} in memory, then the location of the first pixel of the next |
11821 | row is obtained by skipping | |
8925f36f | 11822 | |
3c9b6116 | 11823 | @r{@var{k}=@{(@var{n}@var{l}), |
8925f36f AW |
11824 | (@var{a}/@var{s},⌈@var{s}@var{n}@var{l},/@var{a},⌉)(@var{s}>=@var{a}), |
11825 | (@var{s}<@var{a}),} | |
11826 | ||
3c9b6116 AW |
11827 | components or indices, where @r{@var{n}} is the number of components or |
11828 | indices in a pixel, @r{@var{l}} is the number of pixels in a row | |
11829 | (@code{GL_PACK_ROW_LENGTH} if it is greater than 0, the @r{@var{width}} | |
11830 | argument to the pixel routine otherwise), @r{@var{a}} is the value of | |
11831 | @code{GL_PACK_ALIGNMENT}, and @r{@var{s}} is the size, in bytes, of a | |
11832 | single component (if @r{@var{a}<@var{s}}, then it is as if | |
11833 | @r{@var{a}=@var{s}}). In the case of 1-bit values, the location of the | |
11834 | next row is obtained by skipping | |
8925f36f | 11835 | |
3c9b6116 | 11836 | @r{@var{k}=8@var{a}⌈@var{n}@var{l},/8@var{a},,⌉} |
8925f36f AW |
11837 | |
11838 | components or indices. | |
11839 | ||
11840 | The word @var{component} in this description refers to the nonindex | |
11841 | values red, green, blue, alpha, and depth. Storage format @code{GL_RGB}, | |
11842 | for example, has three components per pixel: first red, then green, and | |
11843 | finally blue. | |
11844 | ||
11845 | @item @code{GL_PACK_IMAGE_HEIGHT} | |
11846 | If greater than 0, @code{GL_PACK_IMAGE_HEIGHT} defines the number of | |
11847 | pixels in an image three-dimensional texture volume, where ``image'' is | |
11848 | defined by all pixels sharing the same third dimension index. If the | |
3c9b6116 AW |
11849 | first pixel of a row is placed at location @r{@var{p}} in memory, then |
11850 | the location of the first pixel of the next row is obtained by skipping | |
8925f36f | 11851 | |
3c9b6116 | 11852 | @r{@var{k}=@{(@var{n}@var{l}@var{h}), |
8925f36f AW |
11853 | (@var{a}/@var{s},⌈@var{s}@var{n}@var{l}@var{h},/@var{a},⌉)(@var{s}>=@var{a}), |
11854 | (@var{s}<@var{a}),} | |
11855 | ||
3c9b6116 AW |
11856 | components or indices, where @r{@var{n}} is the number of components or |
11857 | indices in a pixel, @r{@var{l}} is the number of pixels in a row | |
11858 | (@code{GL_PACK_ROW_LENGTH} if it is greater than 0, the @r{@var{width}} | |
11859 | argument to @code{glTexImage3D} otherwise), @r{@var{h}} is the number of | |
11860 | rows in a pixel image (@code{GL_PACK_IMAGE_HEIGHT} if it is greater than | |
11861 | 0, the @r{@var{height}} argument to the @code{glTexImage3D} routine | |
11862 | otherwise), @r{@var{a}} is the value of @code{GL_PACK_ALIGNMENT}, and | |
11863 | @r{@var{s}} is the size, in bytes, of a single component (if | |
11864 | @r{@var{a}<@var{s}}, then it is as if @r{@var{a}=@var{s}}). | |
8925f36f AW |
11865 | |
11866 | The word @var{component} in this description refers to the nonindex | |
11867 | values red, green, blue, alpha, and depth. Storage format @code{GL_RGB}, | |
11868 | for example, has three components per pixel: first red, then green, and | |
11869 | finally blue. | |
11870 | ||
11871 | @item @code{GL_PACK_SKIP_PIXELS}, @code{GL_PACK_SKIP_ROWS}, and @code{GL_PACK_SKIP_IMAGES} | |
11872 | These values are provided as a convenience to the programmer; they | |
11873 | provide no functionality that cannot be duplicated simply by | |
11874 | incrementing the pointer passed to @code{glReadPixels}. Setting | |
3c9b6116 AW |
11875 | @code{GL_PACK_SKIP_PIXELS} to @r{@var{i}} is equivalent to incrementing |
11876 | the pointer by @r{@var{i}@var{n}} components or indices, where | |
11877 | @r{@var{n}} is the number of components or indices in each pixel. | |
11878 | Setting @code{GL_PACK_SKIP_ROWS} to @r{@var{j}} is equivalent to | |
11879 | incrementing the pointer by @r{@var{j}@var{m}} components or indices, | |
11880 | where @r{@var{m}} is the number of components or indices per row, as | |
11881 | just computed in the @code{GL_PACK_ROW_LENGTH} section. Setting | |
11882 | @code{GL_PACK_SKIP_IMAGES} to @r{@var{k}} is equivalent to incrementing | |
11883 | the pointer by @r{@var{k}@var{p}}, where @r{@var{p}} is the number of | |
11884 | components or indices per image, as computed in the | |
11885 | @code{GL_PACK_IMAGE_HEIGHT} section. | |
8925f36f AW |
11886 | |
11887 | @item @code{GL_PACK_ALIGNMENT} | |
11888 | Specifies the alignment requirements for the start of each pixel row in | |
11889 | memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to | |
11890 | even-numbered bytes), 4 (word-alignment), and 8 (rows start on | |
11891 | double-word boundaries). | |
11892 | ||
11893 | @end table | |
11894 | ||
11895 | The other six of the twelve storage parameters affect how pixel data is | |
11896 | read from client memory. These values are significant for | |
11897 | @code{glDrawPixels}, @code{glTexImage1D}, @code{glTexImage2D}, | |
11898 | @code{glTexImage3D}, @code{glTexSubImage1D}, @code{glTexSubImage2D}, | |
11899 | @code{glTexSubImage3D}, @code{glBitmap}, and @code{glPolygonStipple}. | |
11900 | ||
11901 | Additionally, if the @code{ARB_imaging} extension is supported, | |
11902 | @code{glColorTable}, @code{glColorSubTable}, | |
11903 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and | |
11904 | @code{glSeparableFilter2D}. They are as follows: | |
11905 | ||
11906 | @table @asis | |
11907 | @item @code{GL_UNPACK_SWAP_BYTES} | |
11908 | If true, byte ordering for multibyte color components, depth components, | |
11909 | color indices, or stencil indices is reversed. That is, if a four-byte | |
3c9b6116 AW |
11910 | component consists of bytes @r{@var{b}_0}, @r{@var{b}_1}, @r{@var{b}_2}, |
11911 | @r{@var{b}_3}, it is taken from memory as @r{@var{b}_3}, @r{@var{b}_2}, | |
11912 | @r{@var{b}_1}, @r{@var{b}_0} if @code{GL_UNPACK_SWAP_BYTES} is true. | |
11913 | @code{GL_UNPACK_SWAP_BYTES} has no effect on the memory order of | |
11914 | components within a pixel, only on the order of bytes within components | |
11915 | or indices. For example, the three components of a @code{GL_RGB} format | |
11916 | pixel are always stored with red first, green second, and blue third, | |
11917 | regardless of the value of @code{GL_UNPACK_SWAP_BYTES}. | |
8925f36f AW |
11918 | |
11919 | @item @code{GL_UNPACK_LSB_FIRST} | |
11920 | If true, bits are ordered within a byte from least significant to most | |
11921 | significant; otherwise, the first bit in each byte is the most | |
11922 | significant one. This is relevant only for bitmap data. | |
11923 | ||
11924 | @item @code{GL_UNPACK_ROW_LENGTH} | |
11925 | If greater than 0, @code{GL_UNPACK_ROW_LENGTH} defines the number of | |
11926 | pixels in a row. If the first pixel of a row is placed at location | |
3c9b6116 AW |
11927 | @r{@var{p}} in memory, then the location of the first pixel of the next |
11928 | row is obtained by skipping | |
8925f36f | 11929 | |
3c9b6116 | 11930 | @r{@var{k}=@{(@var{n}@var{l}), |
8925f36f AW |
11931 | (@var{a}/@var{s},⌈@var{s}@var{n}@var{l},/@var{a},⌉)(@var{s}>=@var{a}), |
11932 | (@var{s}<@var{a}),} | |
11933 | ||
3c9b6116 AW |
11934 | components or indices, where @r{@var{n}} is the number of components or |
11935 | indices in a pixel, @r{@var{l}} is the number of pixels in a row | |
8925f36f | 11936 | (@code{GL_UNPACK_ROW_LENGTH} if it is greater than 0, the |
3c9b6116 AW |
11937 | @r{@var{width}} argument to the pixel routine otherwise), @r{@var{a}} is |
11938 | the value of @code{GL_UNPACK_ALIGNMENT}, and @r{@var{s}} is the size, in | |
11939 | bytes, of a single component (if @r{@var{a}<@var{s}}, then it is as if | |
11940 | @r{@var{a}=@var{s}}). In the case of 1-bit values, the location of the | |
11941 | next row is obtained by skipping | |
8925f36f | 11942 | |
3c9b6116 | 11943 | @r{@var{k}=8@var{a}⌈@var{n}@var{l},/8@var{a},,⌉} |
8925f36f AW |
11944 | |
11945 | components or indices. | |
11946 | ||
11947 | The word @var{component} in this description refers to the nonindex | |
11948 | values red, green, blue, alpha, and depth. Storage format @code{GL_RGB}, | |
11949 | for example, has three components per pixel: first red, then green, and | |
11950 | finally blue. | |
11951 | ||
11952 | @item @code{GL_UNPACK_IMAGE_HEIGHT} | |
11953 | If greater than 0, @code{GL_UNPACK_IMAGE_HEIGHT} defines the number of | |
11954 | pixels in an image of a three-dimensional texture volume. Where | |
11955 | ``image'' is defined by all pixel sharing the same third dimension | |
3c9b6116 AW |
11956 | index. If the first pixel of a row is placed at location @r{@var{p}} in |
11957 | memory, then the location of the first pixel of the next row is obtained | |
11958 | by skipping | |
8925f36f | 11959 | |
3c9b6116 | 11960 | @r{@var{k}=@{(@var{n}@var{l}@var{h}), |
8925f36f AW |
11961 | (@var{a}/@var{s},⌈@var{s}@var{n}@var{l}@var{h},/@var{a},⌉)(@var{s}>=@var{a}), |
11962 | (@var{s}<@var{a}),} | |
11963 | ||
3c9b6116 AW |
11964 | components or indices, where @r{@var{n}} is the number of components or |
11965 | indices in a pixel, @r{@var{l}} is the number of pixels in a row | |
8925f36f | 11966 | (@code{GL_UNPACK_ROW_LENGTH} if it is greater than 0, the |
3c9b6116 AW |
11967 | @r{@var{width}} argument to @code{glTexImage3D} otherwise), @r{@var{h}} |
11968 | is the number of rows in an image (@code{GL_UNPACK_IMAGE_HEIGHT} if it | |
11969 | is greater than 0, the @r{@var{height}} argument to @code{glTexImage3D} | |
11970 | otherwise), @r{@var{a}} is the value of @code{GL_UNPACK_ALIGNMENT}, and | |
11971 | @r{@var{s}} is the size, in bytes, of a single component (if | |
11972 | @r{@var{a}<@var{s}}, then it is as if @r{@var{a}=@var{s}}). | |
8925f36f AW |
11973 | |
11974 | The word @var{component} in this description refers to the nonindex | |
11975 | values red, green, blue, alpha, and depth. Storage format @code{GL_RGB}, | |
11976 | for example, has three components per pixel: first red, then green, and | |
11977 | finally blue. | |
11978 | ||
11979 | @item @code{GL_UNPACK_SKIP_PIXELS} and @code{GL_UNPACK_SKIP_ROWS} | |
11980 | These values are provided as a convenience to the programmer; they | |
11981 | provide no functionality that cannot be duplicated by incrementing the | |
11982 | pointer passed to @code{glDrawPixels}, @code{glTexImage1D}, | |
11983 | @code{glTexImage2D}, @code{glTexSubImage1D}, @code{glTexSubImage2D}, | |
11984 | @code{glBitmap}, or @code{glPolygonStipple}. Setting | |
3c9b6116 AW |
11985 | @code{GL_UNPACK_SKIP_PIXELS} to @r{@var{i}} is equivalent to |
11986 | incrementing the pointer by @r{@var{i}@var{n}} components or indices, | |
11987 | where @r{@var{n}} is the number of components or indices in each pixel. | |
11988 | Setting @code{GL_UNPACK_SKIP_ROWS} to @r{@var{j}} is equivalent to | |
11989 | incrementing the pointer by @r{@var{j}@var{k}} components or indices, | |
11990 | where @r{@var{k}} is the number of components or indices per row, as | |
11991 | just computed in the @code{GL_UNPACK_ROW_LENGTH} section. | |
8925f36f AW |
11992 | |
11993 | @item @code{GL_UNPACK_ALIGNMENT} | |
11994 | Specifies the alignment requirements for the start of each pixel row in | |
11995 | memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to | |
11996 | even-numbered bytes), 4 (word-alignment), and 8 (rows start on | |
11997 | double-word boundaries). | |
11998 | ||
11999 | @end table | |
12000 | ||
12001 | The following table gives the type, initial value, and range of valid | |
12002 | values for each storage parameter that can be set with | |
12003 | @code{glPixelStore}. | |
12004 | ||
12005 | ||
12006 | ||
12007 | @table @asis | |
12008 | @item @strong{@var{pname}} | |
12009 | @strong{Type}, @strong{Initial Value}, @strong{Valid Range} | |
12010 | ||
12011 | @item @code{GL_PACK_SWAP_BYTES} | |
12012 | boolean , false , true or false | |
12013 | ||
12014 | @item @code{GL_PACK_LSB_FIRST} | |
12015 | boolean , false , true or false | |
12016 | ||
12017 | @item @code{GL_PACK_ROW_LENGTH} | |
3c9b6116 | 12018 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
12019 | |
12020 | @item @code{GL_PACK_IMAGE_HEIGHT} | |
3c9b6116 | 12021 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
12022 | |
12023 | @item @code{GL_PACK_SKIP_ROWS} | |
3c9b6116 | 12024 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
12025 | |
12026 | @item @code{GL_PACK_SKIP_PIXELS} | |
3c9b6116 | 12027 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
12028 | |
12029 | @item @code{GL_PACK_SKIP_IMAGES} | |
3c9b6116 | 12030 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
12031 | |
12032 | @item @code{GL_PACK_ALIGNMENT} | |
12033 | integer , 4 , 1, 2, 4, or 8 | |
12034 | ||
12035 | @item @code{GL_UNPACK_SWAP_BYTES} | |
12036 | boolean , false , true or false | |
12037 | ||
12038 | @item @code{GL_UNPACK_LSB_FIRST} | |
12039 | boolean , false , true or false | |
12040 | ||
12041 | @item @code{GL_UNPACK_ROW_LENGTH} | |
3c9b6116 | 12042 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
12043 | |
12044 | @item @code{GL_UNPACK_IMAGE_HEIGHT} | |
3c9b6116 | 12045 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
12046 | |
12047 | @item @code{GL_UNPACK_SKIP_ROWS} | |
3c9b6116 | 12048 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
12049 | |
12050 | @item @code{GL_UNPACK_SKIP_PIXELS} | |
3c9b6116 | 12051 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
12052 | |
12053 | @item @code{GL_UNPACK_SKIP_IMAGES} | |
3c9b6116 | 12054 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
12055 | |
12056 | @item @code{GL_UNPACK_ALIGNMENT} | |
12057 | integer , 4 , 1, 2, 4, or 8 | |
12058 | ||
12059 | @end table | |
12060 | ||
12061 | @code{glPixelStoref} can be used to set any pixel store parameter. If | |
12062 | the parameter type is boolean, then if @var{param} is 0, the parameter | |
12063 | is false; otherwise it is set to true. If @var{pname} is a integer type | |
12064 | parameter, @var{param} is rounded to the nearest integer. | |
12065 | ||
12066 | Likewise, @code{glPixelStorei} can also be used to set any of the pixel | |
12067 | store parameters. Boolean parameters are set to false if @var{param} is | |
12068 | 0 and true otherwise. | |
12069 | ||
8925f36f AW |
12070 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted |
12071 | value. | |
12072 | ||
12073 | @code{GL_INVALID_VALUE} is generated if a negative row length, pixel | |
12074 | skip, or row skip value is specified, or if alignment is specified as | |
12075 | other than 1, 2, 4, or 8. | |
12076 | ||
12077 | @code{GL_INVALID_OPERATION} is generated if @code{glPixelStore} is | |
12078 | executed between the execution of @code{glBegin} and the corresponding | |
12079 | execution of @code{glEnd}. | |
12080 | ||
bb894c9d | 12081 | @end deftypefun |
8925f36f | 12082 | |
bb894c9d AW |
12083 | @deftypefun void glPixelTransferf pname param |
12084 | @deftypefunx void glPixelTransferi pname param | |
3c9b6116 AW |
12085 | Set pixel transfer modes. |
12086 | ||
8925f36f AW |
12087 | @table @asis |
12088 | @item @var{pname} | |
12089 | Specifies the symbolic name of the pixel transfer parameter to be set. | |
12090 | Must be one of the following: @code{GL_MAP_COLOR}, | |
12091 | @code{GL_MAP_STENCIL}, @code{GL_INDEX_SHIFT}, @code{GL_INDEX_OFFSET}, | |
12092 | @code{GL_RED_SCALE}, @code{GL_RED_BIAS}, @code{GL_GREEN_SCALE}, | |
12093 | @code{GL_GREEN_BIAS}, @code{GL_BLUE_SCALE}, @code{GL_BLUE_BIAS}, | |
12094 | @code{GL_ALPHA_SCALE}, @code{GL_ALPHA_BIAS}, @code{GL_DEPTH_SCALE}, or | |
12095 | @code{GL_DEPTH_BIAS}. | |
12096 | ||
12097 | Additionally, if the @code{ARB_imaging} extension is supported, the | |
12098 | following symbolic names are accepted: | |
12099 | @code{GL_POST_COLOR_MATRIX_RED_SCALE}, | |
12100 | @code{GL_POST_COLOR_MATRIX_GREEN_SCALE}, | |
12101 | @code{GL_POST_COLOR_MATRIX_BLUE_SCALE}, | |
12102 | @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE}, | |
12103 | @code{GL_POST_COLOR_MATRIX_RED_BIAS}, | |
12104 | @code{GL_POST_COLOR_MATRIX_GREEN_BIAS}, | |
12105 | @code{GL_POST_COLOR_MATRIX_BLUE_BIAS}, | |
12106 | @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS}, | |
12107 | @code{GL_POST_CONVOLUTION_RED_SCALE}, | |
12108 | @code{GL_POST_CONVOLUTION_GREEN_SCALE}, | |
12109 | @code{GL_POST_CONVOLUTION_BLUE_SCALE}, | |
12110 | @code{GL_POST_CONVOLUTION_ALPHA_SCALE}, | |
12111 | @code{GL_POST_CONVOLUTION_RED_BIAS}, | |
12112 | @code{GL_POST_CONVOLUTION_GREEN_BIAS}, | |
12113 | @code{GL_POST_CONVOLUTION_BLUE_BIAS}, and | |
12114 | @code{GL_POST_CONVOLUTION_ALPHA_BIAS}. | |
12115 | ||
12116 | @item @var{param} | |
12117 | Specifies the value that @var{pname} is set to. | |
12118 | ||
12119 | @end table | |
12120 | ||
8925f36f AW |
12121 | @code{glPixelTransfer} sets pixel transfer modes that affect the |
12122 | operation of subsequent @code{glCopyPixels}, @code{glCopyTexImage1D}, | |
12123 | @code{glCopyTexImage2D}, @code{glCopyTexSubImage1D}, | |
12124 | @code{glCopyTexSubImage2D}, @code{glCopyTexSubImage3D}, | |
12125 | @code{glDrawPixels}, @code{glReadPixels}, @code{glTexImage1D}, | |
12126 | @code{glTexImage2D}, @code{glTexImage3D}, @code{glTexSubImage1D}, | |
12127 | @code{glTexSubImage2D}, and @code{glTexSubImage3D} commands. | |
12128 | Additionally, if the @code{ARB_imaging} subset is supported, the | |
12129 | routines @code{glColorTable}, @code{glColorSubTable}, | |
12130 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, | |
12131 | @code{glHistogram}, @code{glMinmax}, and @code{glSeparableFilter2D} are | |
12132 | also affected. The algorithms that are specified by pixel transfer modes | |
12133 | operate on pixels after they are read from the frame buffer | |
12134 | (@code{glCopyPixels}@code{glCopyTexImage1D}, @code{glCopyTexImage2D}, | |
12135 | @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D}, | |
12136 | @code{glCopyTexSubImage3D}, and @code{glReadPixels}), or unpacked from | |
12137 | client memory (@code{glDrawPixels}, @code{glTexImage1D}, | |
12138 | @code{glTexImage2D}, @code{glTexImage3D}, @code{glTexSubImage1D}, | |
12139 | @code{glTexSubImage2D}, and @code{glTexSubImage3D}). Pixel transfer | |
12140 | operations happen in the same order, and in the same manner, regardless | |
12141 | of the command that resulted in the pixel operation. Pixel storage modes | |
12142 | (see @code{glPixelStore}) control the unpacking of pixels being read | |
12143 | from client memory and the packing of pixels being written back into | |
12144 | client memory. | |
12145 | ||
12146 | Pixel transfer operations handle four fundamental pixel types: | |
12147 | @var{color}, @var{color index}, @var{depth}, and @var{stencil}. | |
12148 | @var{Color} pixels consist of four floating-point values with | |
12149 | unspecified mantissa and exponent sizes, scaled such that 0 represents | |
12150 | zero intensity and 1 represents full intensity. @var{Color indices} | |
12151 | comprise a single fixed-point value, with unspecified precision to the | |
12152 | right of the binary point. @var{Depth} pixels comprise a single | |
12153 | floating-point value, with unspecified mantissa and exponent sizes, | |
12154 | scaled such that 0.0 represents the minimum depth buffer value, and 1.0 | |
12155 | represents the maximum depth buffer value. Finally, @var{stencil} pixels | |
12156 | comprise a single fixed-point value, with unspecified precision to the | |
12157 | right of the binary point. | |
12158 | ||
12159 | The pixel transfer operations performed on the four basic pixel types | |
12160 | are as follows: | |
12161 | ||
12162 | @table @asis | |
12163 | @item @var{Color} | |
12164 | Each of the four color components is multiplied by a scale factor, then | |
12165 | added to a bias factor. That is, the red component is multiplied by | |
12166 | @code{GL_RED_SCALE}, then added to @code{GL_RED_BIAS}; the green | |
12167 | component is multiplied by @code{GL_GREEN_SCALE}, then added to | |
12168 | @code{GL_GREEN_BIAS}; the blue component is multiplied by | |
12169 | @code{GL_BLUE_SCALE}, then added to @code{GL_BLUE_BIAS}; and the alpha | |
12170 | component is multiplied by @code{GL_ALPHA_SCALE}, then added to | |
12171 | @code{GL_ALPHA_BIAS}. After all four color components are scaled and | |
3c9b6116 | 12172 | biased, each is clamped to the range @r{[0,1]}. All color, scale, and |
8925f36f AW |
12173 | bias values are specified with @code{glPixelTransfer}. |
12174 | ||
12175 | If @code{GL_MAP_COLOR} is true, each color component is scaled by the | |
12176 | size of the corresponding color-to-color map, then replaced by the | |
12177 | contents of that map indexed by the scaled component. That is, the red | |
12178 | component is scaled by @code{GL_PIXEL_MAP_R_TO_R_SIZE}, then replaced by | |
12179 | the contents of @code{GL_PIXEL_MAP_R_TO_R} indexed by itself. The green | |
12180 | component is scaled by @code{GL_PIXEL_MAP_G_TO_G_SIZE}, then replaced by | |
12181 | the contents of @code{GL_PIXEL_MAP_G_TO_G} indexed by itself. The blue | |
12182 | component is scaled by @code{GL_PIXEL_MAP_B_TO_B_SIZE}, then replaced by | |
12183 | the contents of @code{GL_PIXEL_MAP_B_TO_B} indexed by itself. And the | |
12184 | alpha component is scaled by @code{GL_PIXEL_MAP_A_TO_A_SIZE}, then | |
12185 | replaced by the contents of @code{GL_PIXEL_MAP_A_TO_A} indexed by | |
12186 | itself. All components taken from the maps are then clamped to the range | |
3c9b6116 AW |
12187 | @r{[0,1]}. @code{GL_MAP_COLOR} is specified with @code{glPixelTransfer}. |
12188 | The contents of the various maps are specified with @code{glPixelMap}. | |
8925f36f AW |
12189 | |
12190 | If the @code{ARB_imaging} extension is supported, each of the four color | |
12191 | components may be scaled and biased after transformation by the color | |
12192 | matrix. That is, the red component is multiplied by | |
12193 | @code{GL_POST_COLOR_MATRIX_RED_SCALE}, then added to | |
12194 | @code{GL_POST_COLOR_MATRIX_RED_BIAS}; the green component is multiplied | |
12195 | by @code{GL_POST_COLOR_MATRIX_GREEN_SCALE}, then added to | |
12196 | @code{GL_POST_COLOR_MATRIX_GREEN_BIAS}; the blue component is multiplied | |
12197 | by @code{GL_POST_COLOR_MATRIX_BLUE_SCALE}, then added to | |
12198 | @code{GL_POST_COLOR_MATRIX_BLUE_BIAS}; and the alpha component is | |
12199 | multiplied by @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE}, then added to | |
12200 | @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS}. After all four color components | |
3c9b6116 | 12201 | are scaled and biased, each is clamped to the range @r{[0,1]}. |
8925f36f AW |
12202 | |
12203 | Similarly, if the @code{ARB_imaging} extension is supported, each of the | |
12204 | four color components may be scaled and biased after processing by the | |
12205 | enabled convolution filter. That is, the red component is multiplied by | |
12206 | @code{GL_POST_CONVOLUTION_RED_SCALE}, then added to | |
12207 | @code{GL_POST_CONVOLUTION_RED_BIAS}; the green component is multiplied | |
12208 | by @code{GL_POST_CONVOLUTION_GREEN_SCALE}, then added to | |
12209 | @code{GL_POST_CONVOLUTION_GREEN_BIAS}; the blue component is multiplied | |
12210 | by @code{GL_POST_CONVOLUTION_BLUE_SCALE}, then added to | |
12211 | @code{GL_POST_CONVOLUTION_BLUE_BIAS}; and the alpha component is | |
12212 | multiplied by @code{GL_POST_CONVOLUTION_ALPHA_SCALE}, then added to | |
12213 | @code{GL_POST_CONVOLUTION_ALPHA_BIAS}. After all four color components | |
3c9b6116 | 12214 | are scaled and biased, each is clamped to the range @r{[0,1]}. |
8925f36f AW |
12215 | |
12216 | @item @var{Color index} | |
12217 | Each color index is shifted left by @code{GL_INDEX_SHIFT} bits; any bits | |
12218 | beyond the number of fraction bits carried by the fixed-point index are | |
12219 | filled with zeros. If @code{GL_INDEX_SHIFT} is negative, the shift is to | |
12220 | the right, again zero filled. Then @code{GL_INDEX_OFFSET} is added to | |
12221 | the index. @code{GL_INDEX_SHIFT} and @code{GL_INDEX_OFFSET} are | |
12222 | specified with @code{glPixelTransfer}. | |
12223 | ||
12224 | From this point, operation diverges depending on the required format of | |
12225 | the resulting pixels. If the resulting pixels are to be written to a | |
12226 | color index buffer, or if they are being read back to client memory in | |
12227 | @code{GL_COLOR_INDEX} format, the pixels continue to be treated as | |
12228 | indices. If @code{GL_MAP_COLOR} is true, each index is masked by | |
3c9b6116 AW |
12229 | @r{2^@var{n}-1}, where @r{@var{n}} is @code{GL_PIXEL_MAP_I_TO_I_SIZE}, |
12230 | then replaced by the contents of @code{GL_PIXEL_MAP_I_TO_I} indexed by | |
12231 | the masked value. @code{GL_MAP_COLOR} is specified with | |
12232 | @code{glPixelTransfer}. The contents of the index map is specified with | |
12233 | @code{glPixelMap}. | |
8925f36f AW |
12234 | |
12235 | If the resulting pixels are to be written to an RGBA color buffer, or if | |
12236 | they are read back to client memory in a format other than | |
12237 | @code{GL_COLOR_INDEX}, the pixels are converted from indices to colors | |
12238 | by referencing the four maps @code{GL_PIXEL_MAP_I_TO_R}, | |
12239 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
12240 | @code{GL_PIXEL_MAP_I_TO_A}. Before being dereferenced, the index is | |
3c9b6116 | 12241 | masked by @r{2^@var{n}-1}, where @r{@var{n}} is |
8925f36f AW |
12242 | @code{GL_PIXEL_MAP_I_TO_R_SIZE} for the red map, |
12243 | @code{GL_PIXEL_MAP_I_TO_G_SIZE} for the green map, | |
12244 | @code{GL_PIXEL_MAP_I_TO_B_SIZE} for the blue map, and | |
12245 | @code{GL_PIXEL_MAP_I_TO_A_SIZE} for the alpha map. All components taken | |
3c9b6116 AW |
12246 | from the maps are then clamped to the range @r{[0,1]}. The contents of |
12247 | the four maps is specified with @code{glPixelMap}. | |
8925f36f AW |
12248 | |
12249 | @item @var{Depth} | |
12250 | Each depth value is multiplied by @code{GL_DEPTH_SCALE}, added to | |
3c9b6116 | 12251 | @code{GL_DEPTH_BIAS}, then clamped to the range @r{[0,1]}. |
8925f36f AW |
12252 | |
12253 | @item @var{Stencil} | |
12254 | Each index is shifted @code{GL_INDEX_SHIFT} bits just as a color index | |
12255 | is, then added to @code{GL_INDEX_OFFSET}. If @code{GL_MAP_STENCIL} is | |
3c9b6116 AW |
12256 | true, each index is masked by @r{2^@var{n}-1}, where @r{@var{n}} is |
12257 | @code{GL_PIXEL_MAP_S_TO_S_SIZE}, then replaced by the contents of | |
8925f36f AW |
12258 | @code{GL_PIXEL_MAP_S_TO_S} indexed by the masked value. |
12259 | ||
12260 | @end table | |
12261 | ||
12262 | The following table gives the type, initial value, and range of valid | |
12263 | values for each of the pixel transfer parameters that are set with | |
12264 | @code{glPixelTransfer}. | |
12265 | ||
12266 | ||
12267 | ||
12268 | @table @asis | |
12269 | @item @strong{@var{pname}} | |
12270 | @strong{Type}, @strong{Initial Value}, @strong{Valid Range} | |
12271 | ||
12272 | @item @code{GL_MAP_COLOR} | |
12273 | boolean , false , true/false | |
12274 | ||
12275 | @item @code{GL_MAP_STENCIL} | |
12276 | boolean , false , true/false | |
12277 | ||
12278 | @item @code{GL_INDEX_SHIFT} | |
3c9b6116 | 12279 | integer , 0 , @r{(-∞,∞)} |
8925f36f AW |
12280 | |
12281 | @item @code{GL_INDEX_OFFSET} | |
3c9b6116 | 12282 | integer , 0 , @r{(-∞,∞)} |
8925f36f AW |
12283 | |
12284 | @item @code{GL_RED_SCALE} | |
3c9b6116 | 12285 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
12286 | |
12287 | @item @code{GL_GREEN_SCALE} | |
3c9b6116 | 12288 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
12289 | |
12290 | @item @code{GL_BLUE_SCALE} | |
3c9b6116 | 12291 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
12292 | |
12293 | @item @code{GL_ALPHA_SCALE} | |
3c9b6116 | 12294 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
12295 | |
12296 | @item @code{GL_DEPTH_SCALE} | |
3c9b6116 | 12297 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
12298 | |
12299 | @item @code{GL_RED_BIAS} | |
3c9b6116 | 12300 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
12301 | |
12302 | @item @code{GL_GREEN_BIAS} | |
3c9b6116 | 12303 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
12304 | |
12305 | @item @code{GL_BLUE_BIAS} | |
3c9b6116 | 12306 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
12307 | |
12308 | @item @code{GL_ALPHA_BIAS} | |
3c9b6116 | 12309 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
12310 | |
12311 | @item @code{GL_DEPTH_BIAS} | |
3c9b6116 | 12312 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
12313 | |
12314 | @item @code{GL_POST_COLOR_MATRIX_RED_SCALE} | |
3c9b6116 | 12315 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
12316 | |
12317 | @item @code{GL_POST_COLOR_MATRIX_GREEN_SCALE} | |
3c9b6116 | 12318 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
12319 | |
12320 | @item @code{GL_POST_COLOR_MATRIX_BLUE_SCALE} | |
3c9b6116 | 12321 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
12322 | |
12323 | @item @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE} | |
3c9b6116 | 12324 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
12325 | |
12326 | @item @code{GL_POST_COLOR_MATRIX_RED_BIAS} | |
3c9b6116 | 12327 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
12328 | |
12329 | @item @code{GL_POST_COLOR_MATRIX_GREEN_BIAS} | |
3c9b6116 | 12330 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
12331 | |
12332 | @item @code{GL_POST_COLOR_MATRIX_BLUE_BIAS} | |
3c9b6116 | 12333 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
12334 | |
12335 | @item @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS} | |
3c9b6116 | 12336 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
12337 | |
12338 | @item @code{GL_POST_CONVOLUTION_RED_SCALE} | |
3c9b6116 | 12339 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
12340 | |
12341 | @item @code{GL_POST_CONVOLUTION_GREEN_SCALE} | |
3c9b6116 | 12342 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
12343 | |
12344 | @item @code{GL_POST_CONVOLUTION_BLUE_SCALE} | |
3c9b6116 | 12345 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
12346 | |
12347 | @item @code{GL_POST_CONVOLUTION_ALPHA_SCALE} | |
3c9b6116 | 12348 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
12349 | |
12350 | @item @code{GL_POST_CONVOLUTION_RED_BIAS} | |
3c9b6116 | 12351 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
12352 | |
12353 | @item @code{GL_POST_CONVOLUTION_GREEN_BIAS} | |
3c9b6116 | 12354 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
12355 | |
12356 | @item @code{GL_POST_CONVOLUTION_BLUE_BIAS} | |
3c9b6116 | 12357 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
12358 | |
12359 | @item @code{GL_POST_CONVOLUTION_ALPHA_BIAS} | |
3c9b6116 | 12360 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
12361 | |
12362 | @end table | |
12363 | ||
12364 | @code{glPixelTransferf} can be used to set any pixel transfer parameter. | |
12365 | If the parameter type is boolean, 0 implies false and any other value | |
12366 | implies true. If @var{pname} is an integer parameter, @var{param} is | |
12367 | rounded to the nearest integer. | |
12368 | ||
12369 | Likewise, @code{glPixelTransferi} can be used to set any of the pixel | |
12370 | transfer parameters. Boolean parameters are set to false if @var{param} | |
12371 | is 0 and to true otherwise. @var{param} is converted to floating point | |
12372 | before being assigned to real-valued parameters. | |
12373 | ||
8925f36f AW |
12374 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted |
12375 | value. | |
12376 | ||
12377 | @code{GL_INVALID_OPERATION} is generated if @code{glPixelTransfer} is | |
12378 | executed between the execution of @code{glBegin} and the corresponding | |
12379 | execution of @code{glEnd}. | |
12380 | ||
bb894c9d | 12381 | @end deftypefun |
8925f36f | 12382 | |
bb894c9d | 12383 | @deftypefun void glPixelZoom xfactor yfactor |
3c9b6116 AW |
12384 | Specify the pixel zoom factors. |
12385 | ||
8925f36f AW |
12386 | @table @asis |
12387 | @item @var{xfactor} | |
12388 | @itemx @var{yfactor} | |
3c9b6116 AW |
12389 | Specify the @r{@var{x}} and @r{@var{y}} zoom factors for pixel write |
12390 | operations. | |
8925f36f AW |
12391 | |
12392 | @end table | |
12393 | ||
3c9b6116 AW |
12394 | @code{glPixelZoom} specifies values for the @r{@var{x}} and @r{@var{y}} |
12395 | zoom factors. During the execution of @code{glDrawPixels} or | |
12396 | @code{glCopyPixels}, if (@r{@var{xr}}, @r{@var{yr}}) is the current | |
12397 | raster position, and a given element is in the @r{@var{m}}th row and | |
12398 | @r{@var{n}}th column of the pixel rectangle, then pixels whose centers | |
12399 | are in the rectangle with corners at | |
8925f36f | 12400 | |
3c9b6116 | 12401 | (@r{@var{xr}+@var{n}·@var{xfactor}}, @r{@var{yr}+@var{m}·@var{yfactor}}) |
8925f36f | 12402 | |
3c9b6116 AW |
12403 | (@r{@var{xr}+(@var{n}+1,)·@var{xfactor}}, |
12404 | @r{@var{yr}+(@var{m}+1,)·@var{yfactor}}) | |
8925f36f AW |
12405 | |
12406 | are candidates for replacement. Any pixel whose center lies on the | |
12407 | bottom or left edge of this rectangular region is also modified. | |
12408 | ||
12409 | Pixel zoom factors are not limited to positive values. Negative zoom | |
12410 | factors reflect the resulting image about the current raster position. | |
12411 | ||
8925f36f AW |
12412 | @code{GL_INVALID_OPERATION} is generated if @code{glPixelZoom} is |
12413 | executed between the execution of @code{glBegin} and the corresponding | |
12414 | execution of @code{glEnd}. | |
12415 | ||
bb894c9d | 12416 | @end deftypefun |
8925f36f | 12417 | |
bb894c9d AW |
12418 | @deftypefun void glPointParameterf pname param |
12419 | @deftypefunx void glPointParameteri pname param | |
3c9b6116 AW |
12420 | Specify point parameters. |
12421 | ||
8925f36f AW |
12422 | @table @asis |
12423 | @item @var{pname} | |
12424 | Specifies a single-valued point parameter. @code{GL_POINT_SIZE_MIN}, | |
12425 | @code{GL_POINT_SIZE_MAX}, @code{GL_POINT_FADE_THRESHOLD_SIZE}, and | |
12426 | @code{GL_POINT_SPRITE_COORD_ORIGIN} are accepted. | |
12427 | ||
12428 | @item @var{param} | |
12429 | Specifies the value that @var{pname} will be set to. | |
12430 | ||
12431 | @end table | |
12432 | ||
8925f36f AW |
12433 | The following values are accepted for @var{pname}: |
12434 | ||
12435 | @table @asis | |
12436 | @item @code{GL_POINT_SIZE_MIN} | |
12437 | ||
12438 | ||
12439 | @var{params} is a single floating-point value that specifies the minimum | |
12440 | point size. The default value is 0.0. | |
12441 | ||
12442 | @item @code{GL_POINT_SIZE_MAX} | |
12443 | ||
12444 | ||
12445 | @var{params} is a single floating-point value that specifies the maximum | |
12446 | point size. The default value is 1.0. | |
12447 | ||
12448 | @item @code{GL_POINT_FADE_THRESHOLD_SIZE} | |
12449 | ||
12450 | ||
12451 | @var{params} is a single floating-point value that specifies the | |
12452 | threshold value to which point sizes are clamped if they exceed the | |
12453 | specified value. The default value is 1.0. | |
12454 | ||
12455 | @item @code{GL_POINT_DISTANCE_ATTENUATION} | |
12456 | ||
12457 | ||
12458 | @var{params} is an array of three floating-point values that specify the | |
12459 | coefficients used for scaling the computed point size. The default | |
3c9b6116 | 12460 | values are @r{(1,00)}. |
8925f36f AW |
12461 | |
12462 | @item @code{GL_POINT_SPRITE_COORD_ORIGIN} | |
12463 | ||
12464 | ||
12465 | @var{params} is a single enum specifying the point sprite texture | |
12466 | coordinate origin, either @code{GL_LOWER_LEFT} or @code{GL_UPPER_LEFT}. | |
12467 | The default value is @code{GL_UPPER_LEFT}. | |
12468 | ||
12469 | @end table | |
12470 | ||
8925f36f AW |
12471 | @code{GL_INVALID_VALUE} is generated If the value specified for |
12472 | @code{GL_POINT_SIZE_MIN}, @code{GL_POINT_SIZE_MAX}, or | |
12473 | @code{GL_POINT_FADE_THRESHOLD_SIZE} is less than zero. | |
12474 | ||
12475 | @code{GL_INVALID_ENUM} is generated If the value specified for | |
12476 | @code{GL_POINT_SPRITE_COORD_ORIGIN} is not @code{GL_LOWER_LEFT} or | |
12477 | @code{GL_UPPER_LEFT}. | |
12478 | ||
12479 | If the value for @code{GL_POINT_SIZE_MIN} is greater than | |
12480 | @code{GL_POINT_SIZE_MAX}, the point size after clamping is undefined, | |
12481 | but no error is generated. | |
12482 | ||
12483 | ||
12484 | ||
bb894c9d | 12485 | @end deftypefun |
8925f36f | 12486 | |
bb894c9d | 12487 | @deftypefun void glPointSize size |
3c9b6116 AW |
12488 | Specify the diameter of rasterized points. |
12489 | ||
8925f36f AW |
12490 | @table @asis |
12491 | @item @var{size} | |
12492 | Specifies the diameter of rasterized points. The initial value is 1. | |
12493 | ||
12494 | @end table | |
12495 | ||
8925f36f AW |
12496 | @code{glPointSize} specifies the rasterized diameter of both aliased and |
12497 | antialiased points. Using a point size other than 1 has different | |
12498 | effects, depending on whether point antialiasing is enabled. To enable | |
12499 | and disable point antialiasing, call @code{glEnable} and | |
12500 | @code{glDisable} with argument @code{GL_POINT_SMOOTH}. Point | |
12501 | antialiasing is initially disabled. | |
12502 | ||
12503 | The specified point size is multiplied with a distance attenuation | |
12504 | factor and clamped to the specified point size range, and further | |
12505 | clamped to the implementation-dependent point size range to produce the | |
12506 | derived point size using | |
12507 | ||
3c9b6116 | 12508 | @r{@var{pointSize}=@var{clamp}(@var{size}×√(1/@var{a}+@var{b}×@var{d}+@var{c}×@var{d}^2,,,),,)} |
8925f36f | 12509 | |
3c9b6116 AW |
12510 | where @r{@var{d}} is the eye-coordinate distance from the eye to the |
12511 | vertex, and @r{@var{a}}, @r{@var{b}}, and @r{@var{c}} are the distance | |
12512 | attenuation coefficients (see @code{glPointParameter}). | |
8925f36f AW |
12513 | |
12514 | If multisampling is disabled, the computed point size is used as the | |
12515 | point's width. | |
12516 | ||
12517 | If multisampling is enabled, the point may be faded by modifying the | |
12518 | point alpha value (see @code{glSampleCoverage}) instead of allowing the | |
12519 | point width to go below a given threshold (see @code{glPointParameter}). | |
12520 | In this case, the width is further modified in the following manner: | |
12521 | ||
3c9b6116 | 12522 | @r{@var{pointWidth}=@{(@var{pointSize}), |
8925f36f AW |
12523 | (@var{threshold})(@var{pointSize}>=@var{threshold}), |
12524 | (@var{otherwise}),} | |
12525 | ||
12526 | The point alpha value is modified by computing: | |
12527 | ||
3c9b6116 | 12528 | @r{@var{pointAlpha}=@{(1), |
8925f36f AW |
12529 | ((@var{pointSize}/@var{threshold},)^2)(@var{pointSize}>=@var{threshold}), |
12530 | (@var{otherwise}),} | |
12531 | ||
12532 | If point antialiasing is disabled, the actual size is determined by | |
12533 | rounding the supplied size to the nearest integer. (If the rounding | |
12534 | results in the value 0, it is as if the point size were 1.) If the | |
3c9b6116 AW |
12535 | rounded size is odd, then the center point (@r{@var{x}}, @r{@var{y}}) of |
12536 | the pixel fragment that represents the point is computed as | |
8925f36f | 12537 | |
3c9b6116 | 12538 | @r{(⌊@var{x}_@var{w},⌋+.5,⌊@var{y}_@var{w},⌋+.5)} |
8925f36f | 12539 | |
3c9b6116 | 12540 | where @r{@var{w}} subscripts indicate window coordinates. All pixels |
8925f36f | 12541 | that lie within the square grid of the rounded size centered at |
3c9b6116 AW |
12542 | (@r{@var{x}}, @r{@var{y}}) make up the fragment. If the size is even, |
12543 | the center point is | |
8925f36f | 12544 | |
3c9b6116 | 12545 | @r{(⌊@var{x}_@var{w}+.5,⌋,⌊@var{y}_@var{w}+.5,⌋)} |
8925f36f AW |
12546 | |
12547 | and the rasterized fragment's centers are the half-integer window | |
12548 | coordinates within the square of the rounded size centered at | |
3c9b6116 | 12549 | @r{(@var{x},@var{y})}. All pixel fragments produced in rasterizing a |
8925f36f AW |
12550 | nonantialiased point are assigned the same associated data, that of the |
12551 | vertex corresponding to the point. | |
12552 | ||
12553 | If antialiasing is enabled, then point rasterization produces a fragment | |
12554 | for each pixel square that intersects the region lying within the circle | |
12555 | having diameter equal to the current point size and centered at the | |
3c9b6116 | 12556 | point's @r{(@var{x}_@var{w},@var{y}_@var{w})}. The coverage value for |
8925f36f AW |
12557 | each fragment is the window coordinate area of the intersection of the |
12558 | circular region with the corresponding pixel square. This value is saved | |
12559 | and used in the final rasterization step. The data associated with each | |
12560 | fragment is the data associated with the point being rasterized. | |
12561 | ||
12562 | Not all sizes are supported when point antialiasing is enabled. If an | |
12563 | unsupported size is requested, the nearest supported size is used. Only | |
12564 | size 1 is guaranteed to be supported; others depend on the | |
12565 | implementation. To query the range of supported sizes and the size | |
12566 | difference between supported sizes within the range, call @code{glGet} | |
12567 | with arguments @code{GL_SMOOTH_POINT_SIZE_RANGE} and | |
12568 | @code{GL_SMOOTH_POINT_SIZE_GRANULARITY}. For aliased points, query the | |
12569 | supported ranges and granularity with @code{glGet} with arguments | |
12570 | @code{GL_ALIASED_POINT_SIZE_RANGE}. | |
12571 | ||
8925f36f AW |
12572 | @code{GL_INVALID_VALUE} is generated if @var{size} is less than or equal |
12573 | to 0. | |
12574 | ||
12575 | @code{GL_INVALID_OPERATION} is generated if @code{glPointSize} is | |
12576 | executed between the execution of @code{glBegin} and the corresponding | |
12577 | execution of @code{glEnd}. | |
12578 | ||
bb894c9d | 12579 | @end deftypefun |
8925f36f | 12580 | |
bb894c9d | 12581 | @deftypefun void glPolygonMode face mode |
3c9b6116 AW |
12582 | Select a polygon rasterization mode. |
12583 | ||
8925f36f AW |
12584 | @table @asis |
12585 | @item @var{face} | |
12586 | Specifies the polygons that @var{mode} applies to. Must be | |
12587 | @code{GL_FRONT} for front-facing polygons, @code{GL_BACK} for | |
12588 | back-facing polygons, or @code{GL_FRONT_AND_BACK} for front- and | |
12589 | back-facing polygons. | |
12590 | ||
12591 | @item @var{mode} | |
12592 | Specifies how polygons will be rasterized. Accepted values are | |
12593 | @code{GL_POINT}, @code{GL_LINE}, and @code{GL_FILL}. The initial value | |
12594 | is @code{GL_FILL} for both front- and back-facing polygons. | |
12595 | ||
12596 | @end table | |
12597 | ||
8925f36f AW |
12598 | @code{glPolygonMode} controls the interpretation of polygons for |
12599 | rasterization. @var{face} describes which polygons @var{mode} applies | |
12600 | to: front-facing polygons (@code{GL_FRONT}), back-facing polygons | |
12601 | (@code{GL_BACK}), or both (@code{GL_FRONT_AND_BACK}). The polygon mode | |
12602 | affects only the final rasterization of polygons. In particular, a | |
12603 | polygon's vertices are lit and the polygon is clipped and possibly | |
12604 | culled before these modes are applied. | |
12605 | ||
12606 | Three modes are defined and can be specified in @var{mode}: | |
12607 | ||
12608 | @table @asis | |
12609 | @item @code{GL_POINT} | |
12610 | Polygon vertices that are marked as the start of a boundary edge are | |
12611 | drawn as points. Point attributes such as @code{GL_POINT_SIZE} and | |
12612 | @code{GL_POINT_SMOOTH} control the rasterization of the points. Polygon | |
12613 | rasterization attributes other than @code{GL_POLYGON_MODE} have no | |
12614 | effect. | |
12615 | ||
12616 | @item @code{GL_LINE} | |
12617 | Boundary edges of the polygon are drawn as line segments. They are | |
12618 | treated as connected line segments for line stippling; the line stipple | |
12619 | counter and pattern are not reset between segments (see | |
12620 | @code{glLineStipple}). Line attributes such as @code{GL_LINE_WIDTH} and | |
12621 | @code{GL_LINE_SMOOTH} control the rasterization of the lines. Polygon | |
12622 | rasterization attributes other than @code{GL_POLYGON_MODE} have no | |
12623 | effect. | |
12624 | ||
12625 | @item @code{GL_FILL} | |
12626 | The interior of the polygon is filled. Polygon attributes such as | |
12627 | @code{GL_POLYGON_STIPPLE} and @code{GL_POLYGON_SMOOTH} control the | |
12628 | rasterization of the polygon. | |
12629 | ||
12630 | @end table | |
12631 | ||
8925f36f AW |
12632 | @code{GL_INVALID_ENUM} is generated if either @var{face} or @var{mode} |
12633 | is not an accepted value. | |
12634 | ||
12635 | @code{GL_INVALID_OPERATION} is generated if @code{glPolygonMode} is | |
12636 | executed between the execution of @code{glBegin} and the corresponding | |
12637 | execution of @code{glEnd}. | |
12638 | ||
bb894c9d | 12639 | @end deftypefun |
8925f36f | 12640 | |
bb894c9d | 12641 | @deftypefun void glPolygonOffset factor units |
3c9b6116 AW |
12642 | Set the scale and units used to calculate depth values. |
12643 | ||
8925f36f AW |
12644 | @table @asis |
12645 | @item @var{factor} | |
12646 | Specifies a scale factor that is used to create a variable depth offset | |
12647 | for each polygon. The initial value is 0. | |
12648 | ||
12649 | @item @var{units} | |
12650 | Is multiplied by an implementation-specific value to create a constant | |
12651 | depth offset. The initial value is 0. | |
12652 | ||
12653 | @end table | |
12654 | ||
8925f36f AW |
12655 | When @code{GL_POLYGON_OFFSET_FILL}, @code{GL_POLYGON_OFFSET_LINE}, or |
12656 | @code{GL_POLYGON_OFFSET_POINT} is enabled, each fragment's @var{depth} | |
12657 | value will be offset after it is interpolated from the @var{depth} | |
12658 | values of the appropriate vertices. The value of the offset is | |
3c9b6116 AW |
12659 | @r{@var{factor}×@var{DZ}+@var{r}×@var{units}}, where @r{@var{DZ}} is a |
12660 | measurement of the change in depth relative to the screen area of the | |
12661 | polygon, and @r{@var{r}} is the smallest value that is guaranteed to | |
12662 | produce a resolvable offset for a given implementation. The offset is | |
8925f36f AW |
12663 | added before the depth test is performed and before the value is written |
12664 | into the depth buffer. | |
12665 | ||
12666 | @code{glPolygonOffset} is useful for rendering hidden-line images, for | |
12667 | applying decals to surfaces, and for rendering solids with highlighted | |
12668 | edges. | |
12669 | ||
8925f36f AW |
12670 | @code{GL_INVALID_OPERATION} is generated if @code{glPolygonOffset} is |
12671 | executed between the execution of @code{glBegin} and the corresponding | |
12672 | execution of @code{glEnd}. | |
12673 | ||
bb894c9d | 12674 | @end deftypefun |
8925f36f | 12675 | |
bb894c9d | 12676 | @deftypefun void glPolygonStipple pattern |
3c9b6116 AW |
12677 | Set the polygon stippling pattern. |
12678 | ||
8925f36f AW |
12679 | @table @asis |
12680 | @item @var{pattern} | |
3c9b6116 AW |
12681 | Specifies a pointer to a @r{32×32} stipple pattern that will be unpacked |
12682 | from memory in the same way that @code{glDrawPixels} unpacks pixels. | |
8925f36f AW |
12683 | |
12684 | @end table | |
12685 | ||
8925f36f AW |
12686 | Polygon stippling, like line stippling (see @code{glLineStipple}), masks |
12687 | out certain fragments produced by rasterization, creating a pattern. | |
12688 | Stippling is independent of polygon antialiasing. | |
12689 | ||
3c9b6116 AW |
12690 | @var{pattern} is a pointer to a @r{32×32} stipple pattern that is stored |
12691 | in memory just like the pixel data supplied to a @code{glDrawPixels} | |
12692 | call with height and @var{width} both equal to 32, a pixel format of | |
12693 | @code{GL_COLOR_INDEX}, and data type of @code{GL_BITMAP}. That is, the | |
12694 | stipple pattern is represented as a @r{32×32} array of 1-bit color | |
12695 | indices packed in unsigned bytes. @code{glPixelStore} parameters like | |
12696 | @code{GL_UNPACK_SWAP_BYTES} and @code{GL_UNPACK_LSB_FIRST} affect the | |
12697 | assembling of the bits into a stipple pattern. Pixel transfer operations | |
12698 | (shift, offset, pixel map) are not applied to the stipple image, | |
12699 | however. | |
8925f36f AW |
12700 | |
12701 | If a non-zero named buffer object is bound to the | |
12702 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
12703 | stipple pattern is specified, @var{pattern} is treated as a byte offset | |
12704 | into the buffer object's data store. | |
12705 | ||
12706 | To enable and disable polygon stippling, call @code{glEnable} and | |
12707 | @code{glDisable} with argument @code{GL_POLYGON_STIPPLE}. Polygon | |
12708 | stippling is initially disabled. If it's enabled, a rasterized polygon | |
3c9b6116 AW |
12709 | fragment with window coordinates @r{@var{x}_@var{w}} and |
12710 | @r{@var{y}_@var{w}} is sent to the next stage of the GL if and only if | |
12711 | the (@r{@var{x}_@var{w}%32})th bit in the (@r{@var{y}_@var{w}%32})th row | |
12712 | of the stipple pattern is 1 (one). When polygon stippling is disabled, | |
12713 | it is as if the stipple pattern consists of all 1's. | |
12714 | ||
8925f36f AW |
12715 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object |
12716 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
12717 | object's data store is currently mapped. | |
12718 | ||
12719 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
12720 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
12721 | would be unpacked from the buffer object such that the memory reads | |
12722 | required would exceed the data store size. | |
12723 | ||
12724 | @code{GL_INVALID_OPERATION} is generated if @code{glPolygonStipple} is | |
12725 | executed between the execution of @code{glBegin} and the corresponding | |
12726 | execution of @code{glEnd}. | |
12727 | ||
bb894c9d | 12728 | @end deftypefun |
8925f36f | 12729 | |
bb894c9d | 12730 | @deftypefun void glPrioritizeTextures n textures priorities |
3c9b6116 AW |
12731 | Set texture residence priority. |
12732 | ||
8925f36f AW |
12733 | @table @asis |
12734 | @item @var{n} | |
12735 | Specifies the number of textures to be prioritized. | |
12736 | ||
12737 | @item @var{textures} | |
12738 | Specifies an array containing the names of the textures to be | |
12739 | prioritized. | |
12740 | ||
12741 | @item @var{priorities} | |
12742 | Specifies an array containing the texture priorities. A priority given | |
12743 | in an element of @var{priorities} applies to the texture named by the | |
12744 | corresponding element of @var{textures}. | |
12745 | ||
12746 | @end table | |
12747 | ||
8925f36f AW |
12748 | @code{glPrioritizeTextures} assigns the @var{n} texture priorities given |
12749 | in @var{priorities} to the @var{n} textures named in @var{textures}. | |
12750 | ||
12751 | The GL establishes a ``working set'' of textures that are resident in | |
12752 | texture memory. These textures may be bound to a texture target much | |
12753 | more efficiently than textures that are not resident. By specifying a | |
12754 | priority for each texture, @code{glPrioritizeTextures} allows | |
12755 | applications to guide the GL implementation in determining which | |
12756 | textures should be resident. | |
12757 | ||
12758 | The priorities given in @var{priorities} are clamped to the range | |
3c9b6116 | 12759 | @r{[0,1]} before they are assigned. 0 indicates the lowest priority; |
8925f36f AW |
12760 | textures with priority 0 are least likely to be resident. 1 indicates |
12761 | the highest priority; textures with priority 1 are most likely to be | |
12762 | resident. However, textures are not guaranteed to be resident until they | |
12763 | are used. | |
12764 | ||
12765 | @code{glPrioritizeTextures} silently ignores attempts to prioritize | |
12766 | texture 0 or any texture name that does not correspond to an existing | |
12767 | texture. | |
12768 | ||
12769 | @code{glPrioritizeTextures} does not require that any of the textures | |
12770 | named by @var{textures} be bound to a texture target. | |
12771 | @code{glTexParameter} may also be used to set a texture's priority, but | |
12772 | only if the texture is currently bound. This is the only way to set the | |
12773 | priority of a default texture. | |
12774 | ||
8925f36f AW |
12775 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
12776 | ||
12777 | @code{GL_INVALID_OPERATION} is generated if @code{glPrioritizeTextures} | |
12778 | is executed between the execution of @code{glBegin} and the | |
12779 | corresponding execution of @code{glEnd}. | |
12780 | ||
bb894c9d | 12781 | @end deftypefun |
8925f36f | 12782 | |
bb894c9d AW |
12783 | @deftypefun void glPushAttrib mask |
12784 | @deftypefunx void glPopAttrib | |
3c9b6116 AW |
12785 | Push and pop the server attribute stack. |
12786 | ||
8925f36f AW |
12787 | @table @asis |
12788 | @item @var{mask} | |
12789 | Specifies a mask that indicates which attributes to save. Values for | |
12790 | @var{mask} are listed below. | |
12791 | ||
12792 | @end table | |
12793 | ||
8925f36f AW |
12794 | @code{glPushAttrib} takes one argument, a mask that indicates which |
12795 | groups of state variables to save on the attribute stack. Symbolic | |
12796 | constants are used to set bits in the mask. @var{mask} is typically | |
12797 | constructed by specifying the bitwise-or of several of these constants | |
12798 | together. The special mask @code{GL_ALL_ATTRIB_BITS} can be used to save | |
12799 | all stackable states. | |
12800 | ||
12801 | The symbolic mask constants and their associated GL state are as follows | |
12802 | (the second column lists which attributes are saved): | |
12803 | ||
12804 | ||
12805 | ||
12806 | @table @asis | |
12807 | @item @code{GL_ACCUM_BUFFER_BIT} | |
12808 | Accumulation buffer clear value | |
12809 | ||
12810 | @item @code{GL_COLOR_BUFFER_BIT} | |
12811 | @code{GL_ALPHA_TEST} enable bit | |
12812 | ||
12813 | @item | |
12814 | Alpha test function and reference value | |
12815 | ||
12816 | @item | |
12817 | @code{GL_BLEND} enable bit | |
12818 | ||
12819 | @item | |
12820 | Blending source and destination functions | |
12821 | ||
12822 | @item | |
12823 | Constant blend color | |
12824 | ||
12825 | @item | |
12826 | Blending equation | |
12827 | ||
12828 | @item | |
12829 | @code{GL_DITHER} enable bit | |
12830 | ||
12831 | @item | |
12832 | @code{GL_DRAW_BUFFER} setting | |
12833 | ||
12834 | @item | |
12835 | @code{GL_COLOR_LOGIC_OP} enable bit | |
12836 | ||
12837 | @item | |
12838 | @code{GL_INDEX_LOGIC_OP} enable bit | |
12839 | ||
12840 | @item | |
12841 | Logic op function | |
12842 | ||
12843 | @item | |
12844 | Color mode and index mode clear values | |
12845 | ||
12846 | @item | |
12847 | Color mode and index mode writemasks | |
12848 | ||
12849 | @item @code{GL_CURRENT_BIT} | |
12850 | Current RGBA color | |
12851 | ||
12852 | @item | |
12853 | Current color index | |
12854 | ||
12855 | @item | |
12856 | Current normal vector | |
12857 | ||
12858 | @item | |
12859 | Current texture coordinates | |
12860 | ||
12861 | @item | |
12862 | Current raster position | |
12863 | ||
12864 | @item | |
12865 | @code{GL_CURRENT_RASTER_POSITION_VALID} flag | |
12866 | ||
12867 | @item | |
12868 | RGBA color associated with current raster position | |
12869 | ||
12870 | @item | |
12871 | Color index associated with current raster position | |
12872 | ||
12873 | @item | |
12874 | Texture coordinates associated with current raster position | |
12875 | ||
12876 | @item | |
12877 | @code{GL_EDGE_FLAG} flag | |
12878 | ||
12879 | @item @code{GL_DEPTH_BUFFER_BIT} | |
12880 | @code{GL_DEPTH_TEST} enable bit | |
12881 | ||
12882 | @item | |
12883 | Depth buffer test function | |
12884 | ||
12885 | @item | |
12886 | Depth buffer clear value | |
12887 | ||
12888 | @item | |
12889 | @code{GL_DEPTH_WRITEMASK} enable bit | |
12890 | ||
12891 | @item @code{GL_ENABLE_BIT} | |
12892 | @code{GL_ALPHA_TEST} flag | |
12893 | ||
12894 | @item | |
12895 | @code{GL_AUTO_NORMAL} flag | |
12896 | ||
12897 | @item | |
12898 | @code{GL_BLEND} flag | |
12899 | ||
12900 | @item | |
12901 | Enable bits for the user-definable clipping planes | |
12902 | ||
12903 | @item | |
12904 | @code{GL_COLOR_MATERIAL} | |
12905 | ||
12906 | @item | |
12907 | @code{GL_CULL_FACE} flag | |
12908 | ||
12909 | @item | |
12910 | @code{GL_DEPTH_TEST} flag | |
12911 | ||
12912 | @item | |
12913 | @code{GL_DITHER} flag | |
12914 | ||
12915 | @item | |
12916 | @code{GL_FOG} flag | |
12917 | ||
12918 | @item | |
12919 | @code{GL_LIGHT}@var{i} where @code{0} <= @var{i} < @code{GL_MAX_LIGHTS} | |
12920 | ||
12921 | @item | |
12922 | @code{GL_LIGHTING} flag | |
12923 | ||
12924 | @item | |
12925 | @code{GL_LINE_SMOOTH} flag | |
12926 | ||
12927 | @item | |
12928 | @code{GL_LINE_STIPPLE} flag | |
12929 | ||
12930 | @item | |
12931 | @code{GL_COLOR_LOGIC_OP} flag | |
12932 | ||
12933 | @item | |
12934 | @code{GL_INDEX_LOGIC_OP} flag | |
12935 | ||
12936 | @item | |
12937 | @code{GL_MAP1_}@var{x} where @var{x} is a map type | |
12938 | ||
12939 | @item | |
12940 | @code{GL_MAP2_}@var{x} where @var{x} is a map type | |
12941 | ||
12942 | @item | |
12943 | @code{GL_MULTISAMPLE} flag | |
12944 | ||
12945 | @item | |
12946 | @code{GL_NORMALIZE} flag | |
12947 | ||
12948 | @item | |
12949 | @code{GL_POINT_SMOOTH} flag | |
12950 | ||
12951 | @item | |
12952 | @code{GL_POLYGON_OFFSET_LINE} flag | |
12953 | ||
12954 | @item | |
12955 | @code{GL_POLYGON_OFFSET_FILL} flag | |
12956 | ||
12957 | @item | |
12958 | @code{GL_POLYGON_OFFSET_POINT} flag | |
12959 | ||
12960 | @item | |
12961 | @code{GL_POLYGON_SMOOTH} flag | |
12962 | ||
12963 | @item | |
12964 | @code{GL_POLYGON_STIPPLE} flag | |
12965 | ||
12966 | @item | |
12967 | @code{GL_SAMPLE_ALPHA_TO_COVERAGE} flag | |
12968 | ||
12969 | @item | |
12970 | @code{GL_SAMPLE_ALPHA_TO_ONE} flag | |
12971 | ||
12972 | @item | |
12973 | @code{GL_SAMPLE_COVERAGE} flag | |
12974 | ||
12975 | @item | |
12976 | @code{GL_SCISSOR_TEST} flag | |
12977 | ||
12978 | @item | |
12979 | @code{GL_STENCIL_TEST} flag | |
12980 | ||
12981 | @item | |
12982 | @code{GL_TEXTURE_1D} flag | |
12983 | ||
12984 | @item | |
12985 | @code{GL_TEXTURE_2D} flag | |
12986 | ||
12987 | @item | |
12988 | @code{GL_TEXTURE_3D} flag | |
12989 | ||
12990 | @item | |
12991 | Flags @code{GL_TEXTURE_GEN_}@var{x} where @var{x} is S, T, R, or Q | |
12992 | ||
12993 | @item @code{GL_EVAL_BIT} | |
12994 | @code{GL_MAP1_}@var{x} enable bits, where @var{x} is a map type | |
12995 | ||
12996 | @item | |
12997 | @code{GL_MAP2_}@var{x} enable bits, where @var{x} is a map type | |
12998 | ||
12999 | @item | |
13000 | 1D grid endpoints and divisions | |
13001 | ||
13002 | @item | |
13003 | 2D grid endpoints and divisions | |
13004 | ||
13005 | @item | |
13006 | @code{GL_AUTO_NORMAL} enable bit | |
13007 | ||
13008 | @item @code{GL_FOG_BIT} | |
13009 | @code{GL_FOG} enable bit | |
13010 | ||
13011 | @item | |
13012 | Fog color | |
13013 | ||
13014 | @item | |
13015 | Fog density | |
13016 | ||
13017 | @item | |
13018 | Linear fog start | |
13019 | ||
13020 | @item | |
13021 | Linear fog end | |
13022 | ||
13023 | @item | |
13024 | Fog index | |
13025 | ||
13026 | @item | |
13027 | @code{GL_FOG_MODE} value | |
13028 | ||
13029 | @item @code{GL_HINT_BIT} | |
13030 | @code{GL_PERSPECTIVE_CORRECTION_HINT} setting | |
13031 | ||
13032 | @item | |
13033 | @code{GL_POINT_SMOOTH_HINT} setting | |
13034 | ||
13035 | @item | |
13036 | @code{GL_LINE_SMOOTH_HINT} setting | |
13037 | ||
13038 | @item | |
13039 | @code{GL_POLYGON_SMOOTH_HINT} setting | |
13040 | ||
13041 | @item | |
13042 | @code{GL_FOG_HINT} setting | |
13043 | ||
13044 | @item | |
13045 | @code{GL_GENERATE_MIPMAP_HINT} setting | |
13046 | ||
13047 | @item | |
13048 | @code{GL_TEXTURE_COMPRESSION_HINT} setting | |
13049 | ||
13050 | @item @code{GL_LIGHTING_BIT} | |
13051 | @code{GL_COLOR_MATERIAL} enable bit | |
13052 | ||
13053 | @item | |
13054 | @code{GL_COLOR_MATERIAL_FACE} value | |
13055 | ||
13056 | @item | |
13057 | Color material parameters that are tracking the current color | |
13058 | ||
13059 | @item | |
13060 | Ambient scene color | |
13061 | ||
13062 | @item | |
13063 | @code{GL_LIGHT_MODEL_LOCAL_VIEWER} value | |
13064 | ||
13065 | @item | |
13066 | @code{GL_LIGHT_MODEL_TWO_SIDE} setting | |
13067 | ||
13068 | @item | |
13069 | @code{GL_LIGHTING} enable bit | |
13070 | ||
13071 | @item | |
13072 | Enable bit for each light | |
13073 | ||
13074 | @item | |
13075 | Ambient, diffuse, and specular intensity for each light | |
13076 | ||
13077 | @item | |
13078 | Direction, position, exponent, and cutoff angle for each light | |
13079 | ||
13080 | @item | |
13081 | Constant, linear, and quadratic attenuation factors for each light | |
13082 | ||
13083 | @item | |
13084 | Ambient, diffuse, specular, and emissive color for each material | |
13085 | ||
13086 | @item | |
13087 | Ambient, diffuse, and specular color indices for each material | |
13088 | ||
13089 | @item | |
13090 | Specular exponent for each material | |
13091 | ||
13092 | @item | |
13093 | @code{GL_SHADE_MODEL} setting | |
13094 | ||
13095 | @item @code{GL_LINE_BIT} | |
13096 | @code{GL_LINE_SMOOTH} flag | |
13097 | ||
13098 | @item | |
13099 | @code{GL_LINE_STIPPLE} enable bit | |
13100 | ||
13101 | @item | |
13102 | Line stipple pattern and repeat counter | |
13103 | ||
13104 | @item | |
13105 | Line width | |
13106 | ||
13107 | @item @code{GL_LIST_BIT} | |
13108 | @code{GL_LIST_BASE} setting | |
13109 | ||
13110 | @item @code{GL_MULTISAMPLE_BIT} | |
13111 | @code{GL_MULTISAMPLE} flag | |
13112 | ||
13113 | @item | |
13114 | @code{GL_SAMPLE_ALPHA_TO_COVERAGE} flag | |
13115 | ||
13116 | @item | |
13117 | @code{GL_SAMPLE_ALPHA_TO_ONE} flag | |
13118 | ||
13119 | @item | |
13120 | @code{GL_SAMPLE_COVERAGE} flag | |
13121 | ||
13122 | @item | |
13123 | @code{GL_SAMPLE_COVERAGE_VALUE} value | |
13124 | ||
13125 | @item | |
13126 | @code{GL_SAMPLE_COVERAGE_INVERT} value | |
13127 | ||
13128 | @item @code{GL_PIXEL_MODE_BIT} | |
13129 | @code{GL_RED_BIAS} and @code{GL_RED_SCALE} settings | |
13130 | ||
13131 | @item | |
13132 | @code{GL_GREEN_BIAS} and @code{GL_GREEN_SCALE} values | |
13133 | ||
13134 | @item | |
13135 | @code{GL_BLUE_BIAS} and @code{GL_BLUE_SCALE} | |
13136 | ||
13137 | @item | |
13138 | @code{GL_ALPHA_BIAS} and @code{GL_ALPHA_SCALE} | |
13139 | ||
13140 | @item | |
13141 | @code{GL_DEPTH_BIAS} and @code{GL_DEPTH_SCALE} | |
13142 | ||
13143 | @item | |
13144 | @code{GL_INDEX_OFFSET} and @code{GL_INDEX_SHIFT} values | |
13145 | ||
13146 | @item | |
13147 | @code{GL_MAP_COLOR} and @code{GL_MAP_STENCIL} flags | |
13148 | ||
13149 | @item | |
13150 | @code{GL_ZOOM_X} and @code{GL_ZOOM_Y} factors | |
13151 | ||
13152 | @item | |
13153 | @code{GL_READ_BUFFER} setting | |
13154 | ||
13155 | @item @code{GL_POINT_BIT} | |
13156 | @code{GL_POINT_SMOOTH} flag | |
13157 | ||
13158 | @item | |
13159 | Point size | |
13160 | ||
13161 | @item @code{GL_POLYGON_BIT} | |
13162 | @code{GL_CULL_FACE} enable bit | |
13163 | ||
13164 | @item | |
13165 | @code{GL_CULL_FACE_MODE} value | |
13166 | ||
13167 | @item | |
13168 | @code{GL_FRONT_FACE} indicator | |
13169 | ||
13170 | @item | |
13171 | @code{GL_POLYGON_MODE} setting | |
13172 | ||
13173 | @item | |
13174 | @code{GL_POLYGON_SMOOTH} flag | |
13175 | ||
13176 | @item | |
13177 | @code{GL_POLYGON_STIPPLE} enable bit | |
13178 | ||
13179 | @item | |
13180 | @code{GL_POLYGON_OFFSET_FILL} flag | |
13181 | ||
13182 | @item | |
13183 | @code{GL_POLYGON_OFFSET_LINE} flag | |
13184 | ||
13185 | @item | |
13186 | @code{GL_POLYGON_OFFSET_POINT} flag | |
13187 | ||
13188 | @item | |
13189 | @code{GL_POLYGON_OFFSET_FACTOR} | |
13190 | ||
13191 | @item | |
13192 | @code{GL_POLYGON_OFFSET_UNITS} | |
13193 | ||
13194 | @item @code{GL_POLYGON_STIPPLE_BIT} | |
13195 | Polygon stipple image | |
13196 | ||
13197 | @item @code{GL_SCISSOR_BIT} | |
13198 | @code{GL_SCISSOR_TEST} flag | |
13199 | ||
13200 | @item | |
13201 | Scissor box | |
13202 | ||
13203 | @item @code{GL_STENCIL_BUFFER_BIT} | |
13204 | @code{GL_STENCIL_TEST} enable bit | |
13205 | ||
13206 | @item | |
13207 | Stencil function and reference value | |
13208 | ||
13209 | @item | |
13210 | Stencil value mask | |
13211 | ||
13212 | @item | |
13213 | Stencil fail, pass, and depth buffer pass actions | |
13214 | ||
13215 | @item | |
13216 | Stencil buffer clear value | |
13217 | ||
13218 | @item | |
13219 | Stencil buffer writemask | |
13220 | ||
13221 | @item @code{GL_TEXTURE_BIT} | |
13222 | Enable bits for the four texture coordinates | |
13223 | ||
13224 | @item | |
13225 | Border color for each texture image | |
13226 | ||
13227 | @item | |
13228 | Minification function for each texture image | |
13229 | ||
13230 | @item | |
13231 | Magnification function for each texture image | |
13232 | ||
13233 | @item | |
13234 | Texture coordinates and wrap mode for each texture image | |
13235 | ||
13236 | @item | |
13237 | Color and mode for each texture environment | |
13238 | ||
13239 | @item | |
13240 | Enable bits @code{GL_TEXTURE_GEN_}@var{x}, @var{x} is S, T, R, and Q | |
13241 | ||
13242 | @item | |
13243 | @code{GL_TEXTURE_GEN_MODE} setting for S, T, R, and Q | |
13244 | ||
13245 | @item | |
13246 | @code{glTexGen} plane equations for S, T, R, and Q | |
13247 | ||
13248 | @item | |
13249 | Current texture bindings (for example, @code{GL_TEXTURE_BINDING_2D}) | |
13250 | ||
13251 | @item @code{GL_TRANSFORM_BIT} | |
13252 | Coefficients of the six clipping planes | |
13253 | ||
13254 | @item | |
13255 | Enable bits for the user-definable clipping planes | |
13256 | ||
13257 | @item | |
13258 | @code{GL_MATRIX_MODE} value | |
13259 | ||
13260 | @item | |
13261 | @code{GL_NORMALIZE} flag | |
13262 | ||
13263 | @item | |
13264 | @code{GL_RESCALE_NORMAL} flag | |
13265 | ||
13266 | @item @code{GL_VIEWPORT_BIT} | |
13267 | Depth range (near and far) | |
13268 | ||
13269 | @item | |
13270 | Viewport origin and extent | |
13271 | ||
13272 | @end table | |
13273 | ||
13274 | @code{glPopAttrib} restores the values of the state variables saved with | |
13275 | the last @code{glPushAttrib} command. Those not saved are left | |
13276 | unchanged. | |
13277 | ||
13278 | It is an error to push attributes onto a full stack or to pop attributes | |
13279 | off an empty stack. In either case, the error flag is set and no other | |
13280 | change is made to GL state. | |
13281 | ||
13282 | Initially, the attribute stack is empty. | |
13283 | ||
8925f36f AW |
13284 | @code{GL_STACK_OVERFLOW} is generated if @code{glPushAttrib} is called |
13285 | while the attribute stack is full. | |
13286 | ||
13287 | @code{GL_STACK_UNDERFLOW} is generated if @code{glPopAttrib} is called | |
13288 | while the attribute stack is empty. | |
13289 | ||
13290 | @code{GL_INVALID_OPERATION} is generated if @code{glPushAttrib} or | |
13291 | @code{glPopAttrib} is executed between the execution of @code{glBegin} | |
13292 | and the corresponding execution of @code{glEnd}. | |
13293 | ||
bb894c9d | 13294 | @end deftypefun |
8925f36f | 13295 | |
bb894c9d AW |
13296 | @deftypefun void glPushClientAttrib mask |
13297 | @deftypefunx void glPopClientAttrib | |
3c9b6116 AW |
13298 | Push and pop the client attribute stack. |
13299 | ||
8925f36f AW |
13300 | @table @asis |
13301 | @item @var{mask} | |
13302 | Specifies a mask that indicates which attributes to save. Values for | |
13303 | @var{mask} are listed below. | |
13304 | ||
13305 | @end table | |
13306 | ||
8925f36f AW |
13307 | @code{glPushClientAttrib} takes one argument, a mask that indicates |
13308 | which groups of client-state variables to save on the client attribute | |
13309 | stack. Symbolic constants are used to set bits in the mask. @var{mask} | |
13310 | is typically constructed by specifying the bitwise-or of several of | |
13311 | these constants together. The special mask | |
13312 | @code{GL_CLIENT_ALL_ATTRIB_BITS} can be used to save all stackable | |
13313 | client state. | |
13314 | ||
13315 | The symbolic mask constants and their associated GL client state are as | |
13316 | follows (the second column lists which attributes are saved): | |
13317 | ||
13318 | @code{GL_CLIENT_PIXEL_STORE_BIT} Pixel storage modes | |
13319 | @code{GL_CLIENT_VERTEX_ARRAY_BIT} Vertex arrays (and enables) | |
13320 | ||
13321 | @code{glPopClientAttrib} restores the values of the client-state | |
13322 | variables saved with the last @code{glPushClientAttrib}. Those not saved | |
13323 | are left unchanged. | |
13324 | ||
13325 | It is an error to push attributes onto a full client attribute stack or | |
13326 | to pop attributes off an empty stack. In either case, the error flag is | |
13327 | set, and no other change is made to GL state. | |
13328 | ||
13329 | Initially, the client attribute stack is empty. | |
13330 | ||
8925f36f AW |
13331 | @code{GL_STACK_OVERFLOW} is generated if @code{glPushClientAttrib} is |
13332 | called while the attribute stack is full. | |
13333 | ||
13334 | @code{GL_STACK_UNDERFLOW} is generated if @code{glPopClientAttrib} is | |
13335 | called while the attribute stack is empty. | |
13336 | ||
bb894c9d | 13337 | @end deftypefun |
8925f36f | 13338 | |
bb894c9d AW |
13339 | @deftypefun void glPushMatrix |
13340 | @deftypefunx void glPopMatrix | |
3c9b6116 AW |
13341 | Push and pop the current matrix stack. |
13342 | ||
8925f36f AW |
13343 | There is a stack of matrices for each of the matrix modes. In |
13344 | @code{GL_MODELVIEW} mode, the stack depth is at least 32. In the other | |
13345 | modes, @code{GL_COLOR}, @code{GL_PROJECTION}, and @code{GL_TEXTURE}, the | |
13346 | depth is at least 2. The current matrix in any mode is the matrix on the | |
13347 | top of the stack for that mode. | |
13348 | ||
13349 | @code{glPushMatrix} pushes the current matrix stack down by one, | |
13350 | duplicating the current matrix. That is, after a @code{glPushMatrix} | |
13351 | call, the matrix on top of the stack is identical to the one below it. | |
13352 | ||
13353 | @code{glPopMatrix} pops the current matrix stack, replacing the current | |
13354 | matrix with the one below it on the stack. | |
13355 | ||
13356 | Initially, each of the stacks contains one matrix, an identity matrix. | |
13357 | ||
13358 | It is an error to push a full matrix stack or to pop a matrix stack that | |
13359 | contains only a single matrix. In either case, the error flag is set and | |
13360 | no other change is made to GL state. | |
13361 | ||
8925f36f AW |
13362 | @code{GL_STACK_OVERFLOW} is generated if @code{glPushMatrix} is called |
13363 | while the current matrix stack is full. | |
13364 | ||
13365 | @code{GL_STACK_UNDERFLOW} is generated if @code{glPopMatrix} is called | |
13366 | while the current matrix stack contains only a single matrix. | |
13367 | ||
13368 | @code{GL_INVALID_OPERATION} is generated if @code{glPushMatrix} or | |
13369 | @code{glPopMatrix} is executed between the execution of @code{glBegin} | |
13370 | and the corresponding execution of @code{glEnd}. | |
13371 | ||
bb894c9d | 13372 | @end deftypefun |
8925f36f | 13373 | |
bb894c9d AW |
13374 | @deftypefun void glPushName name |
13375 | @deftypefunx void glPopName | |
3c9b6116 AW |
13376 | Push and pop the name stack. |
13377 | ||
8925f36f AW |
13378 | @table @asis |
13379 | @item @var{name} | |
13380 | Specifies a name that will be pushed onto the name stack. | |
13381 | ||
13382 | @end table | |
13383 | ||
8925f36f AW |
13384 | The name stack is used during selection mode to allow sets of rendering |
13385 | commands to be uniquely identified. It consists of an ordered set of | |
13386 | unsigned integers and is initially empty. | |
13387 | ||
13388 | @code{glPushName} causes @var{name} to be pushed onto the name stack. | |
13389 | @code{glPopName} pops one name off the top of the stack. | |
13390 | ||
13391 | The maximum name stack depth is implementation-dependent; call | |
13392 | @code{GL_MAX_NAME_STACK_DEPTH} to find out the value for a particular | |
13393 | implementation. It is an error to push a name onto a full stack or to | |
13394 | pop a name off an empty stack. It is also an error to manipulate the | |
13395 | name stack between the execution of @code{glBegin} and the corresponding | |
13396 | execution of @code{glEnd}. In any of these cases, the error flag is set | |
13397 | and no other change is made to GL state. | |
13398 | ||
13399 | The name stack is always empty while the render mode is not | |
13400 | @code{GL_SELECT}. Calls to @code{glPushName} or @code{glPopName} while | |
13401 | the render mode is not @code{GL_SELECT} are ignored. | |
13402 | ||
8925f36f AW |
13403 | @code{GL_STACK_OVERFLOW} is generated if @code{glPushName} is called |
13404 | while the name stack is full. | |
13405 | ||
13406 | @code{GL_STACK_UNDERFLOW} is generated if @code{glPopName} is called | |
13407 | while the name stack is empty. | |
13408 | ||
13409 | @code{GL_INVALID_OPERATION} is generated if @code{glPushName} or | |
13410 | @code{glPopName} is executed between a call to @code{glBegin} and the | |
13411 | corresponding call to @code{glEnd}. | |
13412 | ||
bb894c9d | 13413 | @end deftypefun |
8925f36f | 13414 | |
bb894c9d AW |
13415 | @deftypefun void glRasterPos2i x y |
13416 | @deftypefunx void glRasterPos2d x y | |
13417 | @deftypefunx void glRasterPos3i x y z | |
13418 | @deftypefunx void glRasterPos3d x y z | |
13419 | @deftypefunx void glRasterPos4i x y z w | |
13420 | @deftypefunx void glRasterPos4d x y z w | |
3c9b6116 AW |
13421 | Specify the raster position for pixel operations. |
13422 | ||
8925f36f AW |
13423 | @table @asis |
13424 | @item @var{x} | |
13425 | @itemx @var{y} | |
13426 | @itemx @var{z} | |
13427 | @itemx @var{w} | |
3c9b6116 AW |
13428 | Specify the @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}} |
13429 | object coordinates (if present) for the raster position. | |
8925f36f AW |
13430 | |
13431 | @end table | |
13432 | ||
8925f36f AW |
13433 | The GL maintains a 3D position in window coordinates. This position, |
13434 | called the raster position, is used to position pixel and bitmap write | |
13435 | operations. It is maintained with subpixel accuracy. See | |
13436 | @code{glBitmap}, @code{glDrawPixels}, and @code{glCopyPixels}. | |
13437 | ||
13438 | The current raster position consists of three window coordinates | |
3c9b6116 AW |
13439 | (@r{@var{x}}, @r{@var{y}}, @r{@var{z}}), a clip coordinate value |
13440 | (@r{@var{w}}), an eye coordinate distance, a valid bit, and associated | |
13441 | color data and texture coordinates. The @r{@var{w}} coordinate is a clip | |
13442 | coordinate, because @r{@var{w}} is not projected to window coordinates. | |
13443 | @code{glRasterPos4} specifies object coordinates @r{@var{x}}, | |
13444 | @r{@var{y}}, @r{@var{z}}, and @r{@var{w}} explicitly. | |
13445 | @code{glRasterPos3} specifies object coordinate @r{@var{x}}, | |
13446 | @r{@var{y}}, and @r{@var{z}} explicitly, while @r{@var{w}} is implicitly | |
13447 | set to 1. @code{glRasterPos2} uses the argument values for @r{@var{x}} | |
13448 | and @r{@var{y}} while implicitly setting @r{@var{z}} and @r{@var{w}} to | |
13449 | 0 and 1. | |
8925f36f AW |
13450 | |
13451 | The object coordinates presented by @code{glRasterPos} are treated just | |
13452 | like those of a @code{glVertex} command: They are transformed by the | |
13453 | current modelview and projection matrices and passed to the clipping | |
13454 | stage. If the vertex is not culled, then it is projected and scaled to | |
13455 | window coordinates, which become the new current raster position, and | |
13456 | the @code{GL_CURRENT_RASTER_POSITION_VALID} flag is set. If the vertex | |
13457 | @var{is} culled, then the valid bit is cleared and the current raster | |
13458 | position and associated color and texture coordinates are undefined. | |
13459 | ||
13460 | The current raster position also includes some associated color data and | |
13461 | texture coordinates. If lighting is enabled, then | |
13462 | @code{GL_CURRENT_RASTER_COLOR} (in RGBA mode) or | |
13463 | @code{GL_CURRENT_RASTER_INDEX} (in color index mode) is set to the color | |
13464 | produced by the lighting calculation (see @code{glLight}, | |
13465 | @code{glLightModel}, and @code{glShadeModel}). If lighting is disabled, | |
13466 | current color (in RGBA mode, state variable @code{GL_CURRENT_COLOR}) or | |
13467 | color index (in color index mode, state variable | |
13468 | @code{GL_CURRENT_INDEX}) is used to update the current raster color. | |
13469 | @code{GL_CURRENT_RASTER_SECONDARY_COLOR} (in RGBA mode) is likewise | |
13470 | updated. | |
13471 | ||
13472 | Likewise, @code{GL_CURRENT_RASTER_TEXTURE_COORDS} is updated as a | |
13473 | function of @code{GL_CURRENT_TEXTURE_COORDS}, based on the texture | |
13474 | matrix and the texture generation functions (see @code{glTexGen}). | |
13475 | Finally, the distance from the origin of the eye coordinate system to | |
13476 | the vertex as transformed by only the modelview matrix replaces | |
13477 | @code{GL_CURRENT_RASTER_DISTANCE}. | |
13478 | ||
13479 | Initially, the current raster position is (0, 0, 0, 1), the current | |
13480 | raster distance is 0, the valid bit is set, the associated RGBA color is | |
13481 | (1, 1, 1, 1), the associated color index is 1, and the associated | |
13482 | texture coordinates are (0, 0, 0, 1). In RGBA mode, | |
13483 | @code{GL_CURRENT_RASTER_INDEX} is always 1; in color index mode, the | |
13484 | current raster RGBA color always maintains its initial value. | |
13485 | ||
8925f36f AW |
13486 | @code{GL_INVALID_OPERATION} is generated if @code{glRasterPos} is |
13487 | executed between the execution of @code{glBegin} and the corresponding | |
13488 | execution of @code{glEnd}. | |
13489 | ||
bb894c9d | 13490 | @end deftypefun |
8925f36f | 13491 | |
bb894c9d | 13492 | @deftypefun void glReadBuffer mode |
3c9b6116 AW |
13493 | Select a color buffer source for pixels. |
13494 | ||
8925f36f AW |
13495 | @table @asis |
13496 | @item @var{mode} | |
13497 | Specifies a color buffer. Accepted values are @code{GL_FRONT_LEFT}, | |
13498 | @code{GL_FRONT_RIGHT}, @code{GL_BACK_LEFT}, @code{GL_BACK_RIGHT}, | |
13499 | @code{GL_FRONT}, @code{GL_BACK}, @code{GL_LEFT}, @code{GL_RIGHT}, and | |
13500 | @code{GL_AUX}@var{i}, where @var{i} is between 0 and the value of | |
13501 | @code{GL_AUX_BUFFERS} minus 1. | |
13502 | ||
13503 | @end table | |
13504 | ||
8925f36f AW |
13505 | @code{glReadBuffer} specifies a color buffer as the source for |
13506 | subsequent @code{glReadPixels}, @code{glCopyTexImage1D}, | |
13507 | @code{glCopyTexImage2D}, @code{glCopyTexSubImage1D}, | |
13508 | @code{glCopyTexSubImage2D}, @code{glCopyTexSubImage3D}, and | |
13509 | @code{glCopyPixels} commands. @var{mode} accepts one of twelve or more | |
13510 | predefined values. (@code{GL_AUX0} through @code{GL_AUX3} are always | |
13511 | defined.) In a fully configured system, @code{GL_FRONT}, @code{GL_LEFT}, | |
13512 | and @code{GL_FRONT_LEFT} all name the front left buffer, | |
13513 | @code{GL_FRONT_RIGHT} and @code{GL_RIGHT} name the front right buffer, | |
13514 | and @code{GL_BACK_LEFT} and @code{GL_BACK} name the back left buffer. | |
13515 | ||
13516 | Nonstereo double-buffered configurations have only a front left and a | |
13517 | back left buffer. Single-buffered configurations have a front left and a | |
13518 | front right buffer if stereo, and only a front left buffer if nonstereo. | |
13519 | It is an error to specify a nonexistent buffer to @code{glReadBuffer}. | |
13520 | ||
13521 | @var{mode} is initially @code{GL_FRONT} in single-buffered | |
13522 | configurations and @code{GL_BACK} in double-buffered configurations. | |
13523 | ||
8925f36f AW |
13524 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of the |
13525 | twelve (or more) accepted values. | |
13526 | ||
13527 | @code{GL_INVALID_OPERATION} is generated if @var{mode} specifies a | |
13528 | buffer that does not exist. | |
13529 | ||
13530 | @code{GL_INVALID_OPERATION} is generated if @code{glReadBuffer} is | |
13531 | executed between the execution of @code{glBegin} and the corresponding | |
13532 | execution of @code{glEnd}. | |
13533 | ||
bb894c9d | 13534 | @end deftypefun |
8925f36f | 13535 | |
bb894c9d | 13536 | @deftypefun void glReadPixels x y width height format type data |
3c9b6116 AW |
13537 | Read a block of pixels from the frame buffer. |
13538 | ||
8925f36f AW |
13539 | @table @asis |
13540 | @item @var{x} | |
13541 | @itemx @var{y} | |
13542 | Specify the window coordinates of the first pixel that is read from the | |
13543 | frame buffer. This location is the lower left corner of a rectangular | |
13544 | block of pixels. | |
13545 | ||
13546 | @item @var{width} | |
13547 | @itemx @var{height} | |
13548 | Specify the dimensions of the pixel rectangle. @var{width} and | |
13549 | @var{height} of one correspond to a single pixel. | |
13550 | ||
13551 | @item @var{format} | |
13552 | Specifies the format of the pixel data. The following symbolic values | |
13553 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, | |
13554 | @code{GL_DEPTH_COMPONENT}, @code{GL_RED}, @code{GL_GREEN}, | |
13555 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
13556 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
13557 | @code{GL_LUMINANCE_ALPHA}. | |
13558 | ||
13559 | @item @var{type} | |
13560 | Specifies the data type of the pixel data. Must be one of | |
13561 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
13562 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
13563 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
13564 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
13565 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
13566 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
13567 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
13568 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
13569 | or @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
13570 | ||
13571 | @item @var{data} | |
13572 | Returns the pixel data. | |
13573 | ||
13574 | @end table | |
13575 | ||
8925f36f AW |
13576 | @code{glReadPixels} returns pixel data from the frame buffer, starting |
13577 | with the pixel whose lower left corner is at location (@var{x}, | |
13578 | @var{y}), into client memory starting at location @var{data}. Several | |
13579 | parameters control the processing of the pixel data before it is placed | |
13580 | into client memory. These parameters are set with three commands: | |
13581 | @code{glPixelStore}, @code{glPixelTransfer}, and @code{glPixelMap}. This | |
13582 | reference page describes the effects on @code{glReadPixels} of most, but | |
13583 | not all of the parameters specified by these three commands. | |
13584 | ||
13585 | If a non-zero named buffer object is bound to the | |
13586 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
13587 | block of pixels is requested, @var{data} is treated as a byte offset | |
13588 | into the buffer object's data store rather than a pointer to client | |
13589 | memory. | |
13590 | ||
13591 | When the @code{ARB_imaging} extension is supported, the pixel data may | |
13592 | be processed by additional operations including color table lookup, | |
13593 | color matrix transformations, convolutions, histograms, and minimum and | |
13594 | maximum pixel value computations. | |
13595 | ||
13596 | @code{glReadPixels} returns values from each pixel with lower left | |
3c9b6116 AW |
13597 | corner at @r{(@var{x}+@var{i},@var{y}+@var{j})} for |
13598 | @r{0<=@var{i}<@var{width}} and @r{0<=@var{j}<@var{height}}. This pixel | |
13599 | is said to be the @r{@var{i}}th pixel in the @r{@var{j}}th row. Pixels | |
13600 | are returned in row order from the lowest to the highest row, left to | |
13601 | right in each row. | |
8925f36f AW |
13602 | |
13603 | @var{format} specifies the format for the returned pixel values; | |
13604 | accepted values are: | |
13605 | ||
13606 | @table @asis | |
13607 | @item @code{GL_COLOR_INDEX} | |
13608 | Color indices are read from the color buffer selected by | |
13609 | @code{glReadBuffer}. Each index is converted to fixed point, shifted | |
13610 | left or right depending on the value and sign of @code{GL_INDEX_SHIFT}, | |
13611 | and added to @code{GL_INDEX_OFFSET}. If @code{GL_MAP_COLOR} is | |
13612 | @code{GL_TRUE}, indices are replaced by their mappings in the table | |
13613 | @code{GL_PIXEL_MAP_I_TO_I}. | |
13614 | ||
13615 | @item @code{GL_STENCIL_INDEX} | |
13616 | Stencil values are read from the stencil buffer. Each index is converted | |
13617 | to fixed point, shifted left or right depending on the value and sign of | |
13618 | @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET}. If | |
13619 | @code{GL_MAP_STENCIL} is @code{GL_TRUE}, indices are replaced by their | |
13620 | mappings in the table @code{GL_PIXEL_MAP_S_TO_S}. | |
13621 | ||
13622 | @item @code{GL_DEPTH_COMPONENT} | |
13623 | Depth values are read from the depth buffer. Each component is converted | |
13624 | to floating point such that the minimum depth value maps to 0 and the | |
13625 | maximum value maps to 1. Each component is then multiplied by | |
13626 | @code{GL_DEPTH_SCALE}, added to @code{GL_DEPTH_BIAS}, and finally | |
3c9b6116 | 13627 | clamped to the range @r{[0,1]}. |
8925f36f AW |
13628 | |
13629 | @item @code{GL_RED} | |
13630 | @item @code{GL_GREEN} | |
13631 | @item @code{GL_BLUE} | |
13632 | @item @code{GL_ALPHA} | |
13633 | @item @code{GL_RGB} | |
13634 | @item @code{GL_BGR} | |
13635 | @item @code{GL_RGBA} | |
13636 | @item @code{GL_BGRA} | |
13637 | @item @code{GL_LUMINANCE} | |
13638 | @item @code{GL_LUMINANCE_ALPHA} | |
13639 | Processing differs depending on whether color buffers store color | |
13640 | indices or RGBA color components. If color indices are stored, they are | |
13641 | read from the color buffer selected by @code{glReadBuffer}. Each index | |
13642 | is converted to fixed point, shifted left or right depending on the | |
13643 | value and sign of @code{GL_INDEX_SHIFT}, and added to | |
13644 | @code{GL_INDEX_OFFSET}. Indices are then replaced by the red, green, | |
13645 | blue, and alpha values obtained by indexing the tables | |
13646 | @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G}, | |
13647 | @code{GL_PIXEL_MAP_I_TO_B}, and @code{GL_PIXEL_MAP_I_TO_A}. Each table | |
3c9b6116 AW |
13648 | must be of size @r{2^@var{n}}, but @r{@var{n}} may be different for |
13649 | different tables. Before an index is used to look up a value in a table | |
13650 | of size @r{2^@var{n}}, it must be masked against @r{2^@var{n}-1}. | |
8925f36f AW |
13651 | |
13652 | If RGBA color components are stored in the color buffers, they are read | |
13653 | from the color buffer selected by @code{glReadBuffer}. Each color | |
13654 | component is converted to floating point such that zero intensity maps | |
13655 | to 0.0 and full intensity maps to 1.0. Each component is then multiplied | |
13656 | by @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is | |
13657 | RED, GREEN, BLUE, or ALPHA. Finally, if @code{GL_MAP_COLOR} is | |
3c9b6116 AW |
13658 | @code{GL_TRUE}, each component is clamped to the range @r{[0,1]}, scaled |
13659 | to the size of its corresponding table, and is then replaced by its | |
13660 | mapping in the table @code{GL_PIXEL_MAP_c_TO_c}, where @var{c} is R, G, | |
13661 | B, or A. | |
8925f36f AW |
13662 | |
13663 | Unneeded data is then discarded. For example, @code{GL_RED} discards the | |
13664 | green, blue, and alpha components, while @code{GL_RGB} discards only the | |
13665 | alpha component. @code{GL_LUMINANCE} computes a single-component value | |
13666 | as the sum of the red, green, and blue components, and | |
13667 | @code{GL_LUMINANCE_ALPHA} does the same, while keeping alpha as a second | |
3c9b6116 | 13668 | value. The final values are clamped to the range @r{[0,1]}. |
8925f36f AW |
13669 | |
13670 | @end table | |
13671 | ||
13672 | The shift, scale, bias, and lookup factors just described are all | |
13673 | specified by @code{glPixelTransfer}. The lookup table contents | |
13674 | themselves are specified by @code{glPixelMap}. | |
13675 | ||
13676 | Finally, the indices or components are converted to the proper format, | |
13677 | as specified by @var{type}. If @var{format} is @code{GL_COLOR_INDEX} or | |
13678 | @code{GL_STENCIL_INDEX} and @var{type} is not @code{GL_FLOAT}, each | |
13679 | index is masked with the mask value given in the following table. If | |
13680 | @var{type} is @code{GL_FLOAT}, then each integer index is converted to | |
13681 | single-precision floating-point format. | |
13682 | ||
13683 | If @var{format} is @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, | |
13684 | @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, | |
13685 | @code{GL_BGRA}, @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA} and | |
13686 | @var{type} is not @code{GL_FLOAT}, each component is multiplied by the | |
13687 | multiplier shown in the following table. If type is @code{GL_FLOAT}, | |
13688 | then each component is passed as is (or converted to the client's | |
13689 | single-precision floating-point format if it is different from the one | |
13690 | used by the GL). | |
13691 | ||
13692 | ||
13693 | ||
13694 | @table @asis | |
13695 | @item @var{type} | |
13696 | @strong{Index Mask}, @strong{Component Conversion} | |
13697 | ||
13698 | @item @code{GL_UNSIGNED_BYTE} | |
3c9b6116 | 13699 | @r{2^8-1}, @r{(2^8-1,)@var{c}} |
8925f36f AW |
13700 | |
13701 | @item @code{GL_BYTE} | |
3c9b6116 | 13702 | @r{2^7-1}, @r{(2^8-1,)@var{c}-1,/2} |
8925f36f AW |
13703 | |
13704 | @item @code{GL_BITMAP} | |
3c9b6116 | 13705 | @r{1}, @r{1} |
8925f36f AW |
13706 | |
13707 | @item @code{GL_UNSIGNED_SHORT} | |
3c9b6116 | 13708 | @r{2^16-1}, @r{(2^16-1,)@var{c}} |
8925f36f AW |
13709 | |
13710 | @item @code{GL_SHORT} | |
3c9b6116 | 13711 | @r{2^15-1}, @r{(2^16-1,)@var{c}-1,/2} |
8925f36f AW |
13712 | |
13713 | @item @code{GL_UNSIGNED_INT} | |
3c9b6116 | 13714 | @r{2^32-1}, @r{(2^32-1,)@var{c}} |
8925f36f AW |
13715 | |
13716 | @item @code{GL_INT} | |
3c9b6116 | 13717 | @r{2^31-1}, @r{(2^32-1,)@var{c}-1,/2} |
8925f36f AW |
13718 | |
13719 | @item @code{GL_FLOAT} | |
3c9b6116 | 13720 | none , @r{@var{c}} |
8925f36f AW |
13721 | |
13722 | @end table | |
13723 | ||
13724 | Return values are placed in memory as follows. If @var{format} is | |
13725 | @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, | |
13726 | @code{GL_DEPTH_COMPONENT}, @code{GL_RED}, @code{GL_GREEN}, | |
13727 | @code{GL_BLUE}, @code{GL_ALPHA}, or @code{GL_LUMINANCE}, a single value | |
3c9b6116 AW |
13728 | is returned and the data for the @r{@var{i}}th pixel in the |
13729 | @r{@var{j}}th row is placed in location | |
13730 | @r{(@var{j},)@var{width}+@var{i}}. @code{GL_RGB} and @code{GL_BGR} | |
8925f36f AW |
13731 | return three values, @code{GL_RGBA} and @code{GL_BGRA} return four |
13732 | values, and @code{GL_LUMINANCE_ALPHA} returns two values for each pixel, | |
13733 | with all values corresponding to a single pixel occupying contiguous | |
13734 | space in @var{data}. Storage parameters set by @code{glPixelStore}, such | |
13735 | as @code{GL_PACK_LSB_FIRST} and @code{GL_PACK_SWAP_BYTES}, affect the | |
13736 | way that data is written into memory. See @code{glPixelStore} for a | |
13737 | description. | |
13738 | ||
8925f36f AW |
13739 | @code{GL_INVALID_ENUM} is generated if @var{format} or @var{type} is not |
13740 | an accepted value. | |
13741 | ||
13742 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
13743 | and @var{format} is not @code{GL_COLOR_INDEX} or | |
13744 | @code{GL_STENCIL_INDEX}. | |
13745 | ||
13746 | @code{GL_INVALID_VALUE} is generated if either @var{width} or | |
13747 | @var{height} is negative. | |
13748 | ||
13749 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
13750 | @code{GL_COLOR_INDEX} and the color buffers store RGBA color components. | |
13751 | ||
13752 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
13753 | @code{GL_STENCIL_INDEX} and there is no stencil buffer. | |
13754 | ||
13755 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
13756 | @code{GL_DEPTH_COMPONENT} and there is no depth buffer. | |
13757 | ||
13758 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
13759 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
13760 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
13761 | and @var{format} is not @code{GL_RGB}. | |
13762 | ||
13763 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
13764 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
13765 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
13766 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
13767 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
13768 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
13769 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
13770 | ||
13771 | The formats @code{GL_BGR}, and @code{GL_BGRA} and types | |
13772 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
13773 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
13774 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
13775 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
13776 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
13777 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
13778 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} are available only if the GL | |
13779 | version is 1.2 or greater. | |
13780 | ||
13781 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
13782 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
13783 | object's data store is currently mapped. | |
13784 | ||
13785 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
13786 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
13787 | would be packed to the buffer object such that the memory writes | |
13788 | required would exceed the data store size. | |
13789 | ||
13790 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
13791 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{data} | |
13792 | is not evenly divisible into the number of bytes needed to store in | |
13793 | memory a datum indicated by @var{type}. | |
13794 | ||
13795 | @code{GL_INVALID_OPERATION} is generated if @code{glReadPixels} is | |
13796 | executed between the execution of @code{glBegin} and the corresponding | |
13797 | execution of @code{glEnd}. | |
13798 | ||
bb894c9d | 13799 | @end deftypefun |
8925f36f | 13800 | |
bb894c9d AW |
13801 | @deftypefun void glRectd x1 y1 x2 y2 |
13802 | @deftypefunx void glRecti x1 y1 x2 y2 | |
3c9b6116 AW |
13803 | Draw a rectangle. |
13804 | ||
8925f36f AW |
13805 | @table @asis |
13806 | @item @var{x1} | |
13807 | @itemx @var{y1} | |
13808 | Specify one vertex of a rectangle. | |
13809 | ||
13810 | @item @var{x2} | |
13811 | @itemx @var{y2} | |
13812 | Specify the opposite vertex of the rectangle. | |
13813 | ||
13814 | @end table | |
13815 | ||
8925f36f AW |
13816 | @code{glRect} supports efficient specification of rectangles as two |
13817 | corner points. Each rectangle command takes four arguments, organized | |
3c9b6116 AW |
13818 | either as two consecutive pairs of @r{(@var{x},@var{y})} coordinates or |
13819 | as two pointers to arrays, each containing an @r{(@var{x},@var{y})} | |
13820 | pair. The resulting rectangle is defined in the @r{@var{z}=0} plane. | |
8925f36f AW |
13821 | |
13822 | @code{glRect}(@var{x1}, @var{y1}, @var{x2}, @var{y2}) is exactly | |
13823 | equivalent to the following sequence: Note that if the second vertex is | |
13824 | above and to the right of the first vertex, the rectangle is constructed | |
13825 | with a counterclockwise winding. | |
13826 | ||
13827 | @example | |
13828 | ||
13829 | glBegin(@code{GL_POLYGON}); | |
13830 | glVertex2(@var{x1}, @var{y1}); | |
13831 | glVertex2(@var{x2}, @var{y1}); | |
13832 | glVertex2(@var{x2}, @var{y2}); | |
13833 | glVertex2(@var{x1}, @var{y2}); | |
13834 | glEnd(); | |
13835 | @end example | |
13836 | ||
8925f36f AW |
13837 | @code{GL_INVALID_OPERATION} is generated if @code{glRect} is executed |
13838 | between the execution of @code{glBegin} and the corresponding execution | |
13839 | of @code{glEnd}. | |
13840 | ||
bb894c9d | 13841 | @end deftypefun |
8925f36f | 13842 | |
bb894c9d | 13843 | @deftypefun GLint glRenderMode mode |
3c9b6116 AW |
13844 | Set rasterization mode. |
13845 | ||
8925f36f AW |
13846 | @table @asis |
13847 | @item @var{mode} | |
13848 | Specifies the rasterization mode. Three values are accepted: | |
13849 | @code{GL_RENDER}, @code{GL_SELECT}, and @code{GL_FEEDBACK}. The initial | |
13850 | value is @code{GL_RENDER}. | |
13851 | ||
13852 | @end table | |
13853 | ||
8925f36f AW |
13854 | @code{glRenderMode} sets the rasterization mode. It takes one argument, |
13855 | @var{mode}, which can assume one of three predefined values: | |
13856 | ||
13857 | @table @asis | |
13858 | @item @code{GL_RENDER} | |
13859 | Render mode. Primitives are rasterized, producing pixel fragments, which | |
13860 | are written into the frame buffer. This is the normal mode and also the | |
13861 | default mode. | |
13862 | ||
13863 | @item @code{GL_SELECT} | |
13864 | Selection mode. No pixel fragments are produced, and no change to the | |
13865 | frame buffer contents is made. Instead, a record of the names of | |
13866 | primitives that would have been drawn if the render mode had been | |
13867 | @code{GL_RENDER} is returned in a select buffer, which must be created | |
13868 | (see @code{glSelectBuffer}) before selection mode is entered. | |
13869 | ||
13870 | @item @code{GL_FEEDBACK} | |
13871 | Feedback mode. No pixel fragments are produced, and no change to the | |
13872 | frame buffer contents is made. Instead, the coordinates and attributes | |
13873 | of vertices that would have been drawn if the render mode had been | |
13874 | @code{GL_RENDER} is returned in a feedback buffer, which must be created | |
13875 | (see @code{glFeedbackBuffer}) before feedback mode is entered. | |
13876 | ||
13877 | @end table | |
13878 | ||
13879 | The return value of @code{glRenderMode} is determined by the render mode | |
13880 | at the time @code{glRenderMode} is called, rather than by @var{mode}. | |
13881 | The values returned for the three render modes are as follows: | |
13882 | ||
13883 | @table @asis | |
13884 | @item @code{GL_RENDER} | |
13885 | 0. | |
13886 | ||
13887 | @item @code{GL_SELECT} | |
13888 | The number of hit records transferred to the select buffer. | |
13889 | ||
13890 | @item @code{GL_FEEDBACK} | |
13891 | The number of values (not vertices) transferred to the feedback buffer. | |
13892 | ||
13893 | @end table | |
13894 | ||
13895 | See the @code{glSelectBuffer} and @code{glFeedbackBuffer} reference | |
13896 | pages for more details concerning selection and feedback operation. | |
13897 | ||
8925f36f AW |
13898 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of the |
13899 | three accepted values. | |
13900 | ||
13901 | @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is | |
13902 | called while the render mode is @code{GL_SELECT}, or if | |
13903 | @code{glRenderMode} is called with argument @code{GL_SELECT} before | |
13904 | @code{glSelectBuffer} is called at least once. | |
13905 | ||
13906 | @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is | |
13907 | called while the render mode is @code{GL_FEEDBACK}, or if | |
13908 | @code{glRenderMode} is called with argument @code{GL_FEEDBACK} before | |
13909 | @code{glFeedbackBuffer} is called at least once. | |
13910 | ||
13911 | @code{GL_INVALID_OPERATION} is generated if @code{glRenderMode} is | |
13912 | executed between the execution of @code{glBegin} and the corresponding | |
13913 | execution of @code{glEnd}. | |
13914 | ||
bb894c9d | 13915 | @end deftypefun |
8925f36f | 13916 | |
bb894c9d | 13917 | @deftypefun void glResetHistogram target |
3c9b6116 AW |
13918 | Reset histogram table entries to zero. |
13919 | ||
8925f36f AW |
13920 | @table @asis |
13921 | @item @var{target} | |
13922 | Must be @code{GL_HISTOGRAM}. | |
13923 | ||
13924 | @end table | |
13925 | ||
8925f36f AW |
13926 | @code{glResetHistogram} resets all the elements of the current histogram |
13927 | table to zero. | |
13928 | ||
8925f36f AW |
13929 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
13930 | @code{GL_HISTOGRAM}. | |
13931 | ||
13932 | @code{GL_INVALID_OPERATION} is generated if @code{glResetHistogram} is | |
13933 | executed between the execution of @code{glBegin} and the corresponding | |
13934 | execution of @code{glEnd}. | |
13935 | ||
bb894c9d | 13936 | @end deftypefun |
8925f36f | 13937 | |
bb894c9d | 13938 | @deftypefun void glResetMinmax target |
3c9b6116 AW |
13939 | Reset minmax table entries to initial values. |
13940 | ||
8925f36f AW |
13941 | @table @asis |
13942 | @item @var{target} | |
13943 | Must be @code{GL_MINMAX}. | |
13944 | ||
13945 | @end table | |
13946 | ||
8925f36f AW |
13947 | @code{glResetMinmax} resets the elements of the current minmax table to |
13948 | their initial values: the ``maximum'' element receives the minimum | |
13949 | possible component values, and the ``minimum'' element receives the | |
13950 | maximum possible component values. | |
13951 | ||
8925f36f AW |
13952 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
13953 | @code{GL_MINMAX}. | |
13954 | ||
13955 | @code{GL_INVALID_OPERATION} is generated if @code{glResetMinmax} is | |
13956 | executed between the execution of @code{glBegin} and the corresponding | |
13957 | execution of @code{glEnd}. | |
13958 | ||
bb894c9d | 13959 | @end deftypefun |
8925f36f | 13960 | |
bb894c9d | 13961 | @deftypefun void glRotated angle x y z |
3c9b6116 AW |
13962 | Multiply the current matrix by a rotation matrix. |
13963 | ||
8925f36f AW |
13964 | @table @asis |
13965 | @item @var{angle} | |
13966 | Specifies the angle of rotation, in degrees. | |
13967 | ||
13968 | @item @var{x} | |
13969 | @itemx @var{y} | |
13970 | @itemx @var{z} | |
13971 | Specify the @var{x}, @var{y}, and @var{z} coordinates of a vector, | |
13972 | respectively. | |
13973 | ||
13974 | @end table | |
13975 | ||
8925f36f | 13976 | @code{glRotate} produces a rotation of @var{angle} degrees around the |
3c9b6116 | 13977 | vector @r{(@var{x},@var{y}@var{z})}. The current matrix (see |
8925f36f AW |
13978 | @code{glMatrixMode}) is multiplied by a rotation matrix with the product |
13979 | replacing the current matrix, as if @code{glMultMatrix} were called with | |
13980 | the following matrix as its argument: | |
13981 | ||
3c9b6116 | 13982 | @r{((@var{x}^2(1-@var{c},)+@var{c} |
8925f36f AW |
13983 | @var{x}@var{y}(1-@var{c},)-@var{z}@var{s} |
13984 | @var{x}@var{z}(1-@var{c},)+@var{y}@var{s} 0), | |
13985 | (@var{y}@var{x}(1-@var{c},)+@var{z}@var{s} | |
13986 | @var{y}^2(1-@var{c},)+@var{c} | |
13987 | @var{y}@var{z}(1-@var{c},)-@var{x}@var{s} 0), | |
13988 | (@var{x}@var{z}(1-@var{c},)-@var{y}@var{s} | |
13989 | @var{y}@var{z}(1-@var{c},)+@var{x}@var{s} | |
13990 | @var{z}^2(1-@var{c},)+@var{c} 0), (0 0 0 1),)} | |
13991 | ||
13992 | ||
13993 | ||
3c9b6116 AW |
13994 | Where @r{@var{c}=@var{cos}(@var{angle},)}, |
13995 | @r{@var{s}=@var{sin}(@var{angle},)}, and | |
13996 | @r{∥(@var{x},@var{y}@var{z}),∥=1} (if not, the GL will normalize this | |
8925f36f AW |
13997 | vector). |
13998 | ||
13999 | ||
14000 | ||
14001 | ||
14002 | ||
14003 | If the matrix mode is either @code{GL_MODELVIEW} or | |
14004 | @code{GL_PROJECTION}, all objects drawn after @code{glRotate} is called | |
14005 | are rotated. Use @code{glPushMatrix} and @code{glPopMatrix} to save and | |
14006 | restore the unrotated coordinate system. | |
14007 | ||
8925f36f AW |
14008 | @code{GL_INVALID_OPERATION} is generated if @code{glRotate} is executed |
14009 | between the execution of @code{glBegin} and the corresponding execution | |
14010 | of @code{glEnd}. | |
14011 | ||
bb894c9d | 14012 | @end deftypefun |
8925f36f | 14013 | |
bb894c9d | 14014 | @deftypefun void glSampleCoverage value invert |
3c9b6116 AW |
14015 | Specify multisample coverage parameters. |
14016 | ||
8925f36f AW |
14017 | @table @asis |
14018 | @item @var{value} | |
14019 | Specify a single floating-point sample coverage value. The value is | |
3c9b6116 | 14020 | clamped to the range @r{[0,1]}. The initial value is 1.0. |
8925f36f AW |
14021 | |
14022 | @item @var{invert} | |
14023 | Specify a single boolean value representing if the coverage masks should | |
14024 | be inverted. @code{GL_TRUE} and @code{GL_FALSE} are accepted. The | |
14025 | initial value is @code{GL_FALSE}. | |
14026 | ||
14027 | @end table | |
14028 | ||
8925f36f AW |
14029 | Multisampling samples a pixel multiple times at various |
14030 | implementation-dependent subpixel locations to generate antialiasing | |
14031 | effects. Multisampling transparently antialiases points, lines, | |
14032 | polygons, bitmaps, and images if it is enabled. | |
14033 | ||
14034 | @var{value} is used in constructing a temporary mask used in determining | |
14035 | which samples will be used in resolving the final fragment color. This | |
14036 | mask is bitwise-anded with the coverage mask generated from the | |
14037 | multisampling computation. If the @var{invert} flag is set, the | |
14038 | temporary mask is inverted (all bits flipped) and then the bitwise-and | |
14039 | is computed. | |
14040 | ||
14041 | If an implementation does not have any multisample buffers available, or | |
14042 | multisampling is disabled, rasterization occurs with only a single | |
14043 | sample computing a pixel's final RGB color. | |
14044 | ||
14045 | Provided an implementation supports multisample buffers, and | |
14046 | multisampling is enabled, then a pixel's final color is generated by | |
14047 | combining several samples per pixel. Each sample contains color, depth, | |
14048 | and stencil information, allowing those operations to be performed on | |
14049 | each sample. | |
14050 | ||
8925f36f AW |
14051 | @code{GL_INVALID_OPERATION} is generated if @code{glSampleCoverage} is |
14052 | executed between the execution of @code{glBegin} and the corresponding | |
14053 | execution of @code{glEnd}. | |
14054 | ||
bb894c9d | 14055 | @end deftypefun |
8925f36f | 14056 | |
bb894c9d | 14057 | @deftypefun void glScaled x y z |
3c9b6116 AW |
14058 | Multiply the current matrix by a general scaling matrix. |
14059 | ||
8925f36f AW |
14060 | @table @asis |
14061 | @item @var{x} | |
14062 | @itemx @var{y} | |
14063 | @itemx @var{z} | |
14064 | Specify scale factors along the @var{x}, @var{y}, and @var{z} axes, | |
14065 | respectively. | |
14066 | ||
14067 | @end table | |
14068 | ||
8925f36f AW |
14069 | @code{glScale} produces a nonuniform scaling along the @var{x}, @var{y}, |
14070 | and @var{z} axes. The three parameters indicate the desired scale factor | |
14071 | along each of the three axes. | |
14072 | ||
14073 | The current matrix (see @code{glMatrixMode}) is multiplied by this scale | |
14074 | matrix, and the product replaces the current matrix as if | |
14075 | @code{glMultMatrix} were called with the following matrix as its | |
14076 | argument: | |
14077 | ||
3c9b6116 | 14078 | @r{((@var{x} 0 0 0), (0 @var{y} 0 0), (0 0 @var{z} 0), (0 0 0 1),)} |
8925f36f AW |
14079 | |
14080 | If the matrix mode is either @code{GL_MODELVIEW} or | |
14081 | @code{GL_PROJECTION}, all objects drawn after @code{glScale} is called | |
14082 | are scaled. | |
14083 | ||
14084 | Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the | |
14085 | unscaled coordinate system. | |
14086 | ||
8925f36f AW |
14087 | @code{GL_INVALID_OPERATION} is generated if @code{glScale} is executed |
14088 | between the execution of @code{glBegin} and the corresponding execution | |
14089 | of @code{glEnd}. | |
14090 | ||
bb894c9d | 14091 | @end deftypefun |
8925f36f | 14092 | |
bb894c9d | 14093 | @deftypefun void glScissor x y width height |
3c9b6116 AW |
14094 | Define the scissor box. |
14095 | ||
8925f36f AW |
14096 | @table @asis |
14097 | @item @var{x} | |
14098 | @itemx @var{y} | |
14099 | Specify the lower left corner of the scissor box. Initially (0, 0). | |
14100 | ||
14101 | @item @var{width} | |
14102 | @itemx @var{height} | |
14103 | Specify the width and height of the scissor box. When a GL context is | |
14104 | first attached to a window, @var{width} and @var{height} are set to the | |
14105 | dimensions of that window. | |
14106 | ||
14107 | @end table | |
14108 | ||
8925f36f AW |
14109 | @code{glScissor} defines a rectangle, called the scissor box, in window |
14110 | coordinates. The first two arguments, @var{x} and @var{y}, specify the | |
14111 | lower left corner of the box. @var{width} and @var{height} specify the | |
14112 | width and height of the box. | |
14113 | ||
14114 | To enable and disable the scissor test, call @code{glEnable} and | |
14115 | @code{glDisable} with argument @code{GL_SCISSOR_TEST}. The test is | |
14116 | initially disabled. While the test is enabled, only pixels that lie | |
14117 | within the scissor box can be modified by drawing commands. Window | |
14118 | coordinates have integer values at the shared corners of frame buffer | |
14119 | pixels. @code{glScissor(0,0,1,1)} allows modification of only the lower | |
14120 | left pixel in the window, and @code{glScissor(0,0,0,0)} doesn't allow | |
14121 | modification of any pixels in the window. | |
14122 | ||
14123 | When the scissor test is disabled, it is as though the scissor box | |
14124 | includes the entire window. | |
14125 | ||
8925f36f AW |
14126 | @code{GL_INVALID_VALUE} is generated if either @var{width} or |
14127 | @var{height} is negative. | |
14128 | ||
14129 | @code{GL_INVALID_OPERATION} is generated if @code{glScissor} is executed | |
14130 | between the execution of @code{glBegin} and the corresponding execution | |
14131 | of @code{glEnd}. | |
14132 | ||
bb894c9d | 14133 | @end deftypefun |
8925f36f | 14134 | |
bb894c9d | 14135 | @deftypefun void glSecondaryColorPointer size type stride pointer |
3c9b6116 AW |
14136 | Define an array of secondary colors. |
14137 | ||
8925f36f AW |
14138 | @table @asis |
14139 | @item @var{size} | |
14140 | Specifies the number of components per color. Must be 3. | |
14141 | ||
14142 | @item @var{type} | |
14143 | Specifies the data type of each color component in the array. Symbolic | |
14144 | constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, | |
14145 | @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT}, | |
14146 | @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is | |
14147 | @code{GL_FLOAT}. | |
14148 | ||
14149 | @item @var{stride} | |
14150 | Specifies the byte offset between consecutive colors. If @var{stride} is | |
14151 | 0, the colors are understood to be tightly packed in the array. The | |
14152 | initial value is 0. | |
14153 | ||
14154 | @item @var{pointer} | |
14155 | Specifies a pointer to the first component of the first color element in | |
14156 | the array. The initial value is 0. | |
14157 | ||
14158 | @end table | |
14159 | ||
8925f36f AW |
14160 | @code{glSecondaryColorPointer} specifies the location and data format of |
14161 | an array of color components to use when rendering. @var{size} specifies | |
14162 | the number of components per color, and must be 3. @var{type} specifies | |
14163 | the data type of each color component, and @var{stride} specifies the | |
14164 | byte stride from one color to the next, allowing vertices and attributes | |
14165 | to be packed into a single array or stored in separate arrays. | |
14166 | ||
14167 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
14168 | target (see @code{glBindBuffer}) while a secondary color array is | |
14169 | specified, @var{pointer} is treated as a byte offset into the buffer | |
14170 | object's data store. Also, the buffer object binding | |
14171 | (@code{GL_ARRAY_BUFFER_BINDING}) is saved as secondary color vertex | |
14172 | array client-side state | |
14173 | (@code{GL_SECONDARY_COLOR_ARRAY_BUFFER_BINDING}). | |
14174 | ||
14175 | When a secondary color array is specified, @var{size}, @var{type}, | |
14176 | @var{stride}, and @var{pointer} are saved as client-side state, in | |
14177 | addition to the current vertex array buffer object binding. | |
14178 | ||
14179 | To enable and disable the secondary color array, call | |
14180 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
14181 | argument @code{GL_SECONDARY_COLOR_ARRAY}. If enabled, the secondary | |
14182 | color array is used when @code{glArrayElement}, @code{glDrawArrays}, | |
14183 | @code{glMultiDrawArrays}, @code{glDrawElements}, | |
14184 | @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called. | |
14185 | ||
8925f36f AW |
14186 | @code{GL_INVALID_VALUE} is generated if @var{size} is not 3. |
14187 | ||
14188 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted | |
14189 | value. | |
14190 | ||
14191 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
14192 | ||
bb894c9d | 14193 | @end deftypefun |
8925f36f | 14194 | |
bb894c9d AW |
14195 | @deftypefun void glSecondaryColor3i red green blue |
14196 | @deftypefunx void glSecondaryColor3d red green blue | |
14197 | @deftypefunx void glSecondaryColor3ui red green blue | |
3c9b6116 AW |
14198 | Set the current secondary color. |
14199 | ||
8925f36f AW |
14200 | @table @asis |
14201 | @item @var{red} | |
14202 | @itemx @var{green} | |
14203 | @itemx @var{blue} | |
14204 | Specify new red, green, and blue values for the current secondary color. | |
14205 | ||
14206 | @end table | |
14207 | ||
8925f36f AW |
14208 | The GL stores both a primary four-valued RGBA color and a secondary |
14209 | four-valued RGBA color (where alpha is always set to 0.0) that is | |
14210 | associated with every vertex. | |
14211 | ||
14212 | The secondary color is interpolated and applied to each fragment during | |
14213 | rasterization when @code{GL_COLOR_SUM} is enabled. When lighting is | |
14214 | enabled, and @code{GL_SEPARATE_SPECULAR_COLOR} is specified, the value | |
14215 | of the secondary color is assigned the value computed from the specular | |
14216 | term of the lighting computation. Both the primary and secondary current | |
14217 | colors are applied to each fragment, regardless of the state of | |
14218 | @code{GL_COLOR_SUM}, under such conditions. When | |
14219 | @code{GL_SEPARATE_SPECULAR_COLOR} is specified, the value returned from | |
14220 | querying the current secondary color is undefined. | |
14221 | ||
14222 | @code{glSecondaryColor3b}, @code{glSecondaryColor3s}, and | |
14223 | @code{glSecondaryColor3i} take three signed byte, short, or long | |
14224 | integers as arguments. When @strong{v} is appended to the name, the | |
14225 | color commands can take a pointer to an array of such values. | |
14226 | ||
14227 | Color values are stored in floating-point format, with unspecified | |
14228 | mantissa and exponent sizes. Unsigned integer color components, when | |
14229 | specified, are linearly mapped to floating-point values such that the | |
14230 | largest representable value maps to 1.0 (full intensity), and 0 maps to | |
14231 | 0.0 (zero intensity). Signed integer color components, when specified, | |
14232 | are linearly mapped to floating-point values such that the most positive | |
14233 | representable value maps to 1.0, and the most negative representable | |
3c9b6116 | 14234 | value maps to @r{-1.0}. (Note that this mapping does not convert 0 |
8925f36f AW |
14235 | precisely to 0.0). Floating-point values are mapped directly. |
14236 | ||
14237 | Neither floating-point nor signed integer values are clamped to the | |
3c9b6116 | 14238 | range @r{[0,1]} before the current color is updated. However, color |
8925f36f AW |
14239 | components are clamped to this range before they are interpolated or |
14240 | written into a color buffer. | |
14241 | ||
bb894c9d | 14242 | @end deftypefun |
8925f36f | 14243 | |
bb894c9d | 14244 | @deftypefun void glSelectBuffer size buffer |
3c9b6116 AW |
14245 | Establish a buffer for selection mode values. |
14246 | ||
8925f36f AW |
14247 | @table @asis |
14248 | @item @var{size} | |
14249 | Specifies the size of @var{buffer}. | |
14250 | ||
14251 | @item @var{buffer} | |
14252 | Returns the selection data. | |
14253 | ||
14254 | @end table | |
14255 | ||
8925f36f AW |
14256 | @code{glSelectBuffer} has two arguments: @var{buffer} is a pointer to an |
14257 | array of unsigned integers, and @var{size} indicates the size of the | |
14258 | array. @var{buffer} returns values from the name stack (see | |
14259 | @code{glInitNames}, @code{glLoadName}, @code{glPushName}) when the | |
14260 | rendering mode is @code{GL_SELECT} (see @code{glRenderMode}). | |
14261 | @code{glSelectBuffer} must be issued before selection mode is enabled, | |
14262 | and it must not be issued while the rendering mode is @code{GL_SELECT}. | |
14263 | ||
14264 | A programmer can use selection to determine which primitives are drawn | |
14265 | into some region of a window. The region is defined by the current | |
14266 | modelview and perspective matrices. | |
14267 | ||
14268 | In selection mode, no pixel fragments are produced from rasterization. | |
14269 | Instead, if a primitive or a raster position intersects the clipping | |
14270 | volume defined by the viewing frustum and the user-defined clipping | |
14271 | planes, this primitive causes a selection hit. (With polygons, no hit | |
14272 | occurs if the polygon is culled.) When a change is made to the name | |
14273 | stack, or when @code{glRenderMode} is called, a hit record is copied to | |
14274 | @var{buffer} if any hits have occurred since the last such event (name | |
14275 | stack change or @code{glRenderMode} call). The hit record consists of | |
14276 | the number of names in the name stack at the time of the event, followed | |
14277 | by the minimum and maximum depth values of all vertices that hit since | |
14278 | the previous event, followed by the name stack contents, bottom name | |
14279 | first. | |
14280 | ||
14281 | Depth values (which are in the range [0,1]) are multiplied by | |
3c9b6116 | 14282 | @r{2^32-1}, before being placed in the hit record. |
8925f36f AW |
14283 | |
14284 | An internal index into @var{buffer} is reset to 0 whenever selection | |
14285 | mode is entered. Each time a hit record is copied into @var{buffer}, the | |
14286 | index is incremented to point to the cell just past the end of the block | |
14287 | of names\(emthat is, to the next available cell If the hit record is | |
14288 | larger than the number of remaining locations in @var{buffer}, as much | |
14289 | data as can fit is copied, and the overflow flag is set. If the name | |
14290 | stack is empty when a hit record is copied, that record consists of 0 | |
14291 | followed by the minimum and maximum depth values. | |
14292 | ||
14293 | To exit selection mode, call @code{glRenderMode} with an argument other | |
14294 | than @code{GL_SELECT}. Whenever @code{glRenderMode} is called while the | |
14295 | render mode is @code{GL_SELECT}, it returns the number of hit records | |
14296 | copied to @var{buffer}, resets the overflow flag and the selection | |
14297 | buffer pointer, and initializes the name stack to be empty. If the | |
14298 | overflow bit was set when @code{glRenderMode} was called, a negative hit | |
14299 | record count is returned. | |
14300 | ||
8925f36f AW |
14301 | @code{GL_INVALID_VALUE} is generated if @var{size} is negative. |
14302 | ||
14303 | @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is | |
14304 | called while the render mode is @code{GL_SELECT}, or if | |
14305 | @code{glRenderMode} is called with argument @code{GL_SELECT} before | |
14306 | @code{glSelectBuffer} is called at least once. | |
14307 | ||
14308 | @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is | |
14309 | executed between the execution of @code{glBegin} and the corresponding | |
14310 | execution of @code{glEnd}. | |
14311 | ||
bb894c9d | 14312 | @end deftypefun |
8925f36f | 14313 | |
bb894c9d | 14314 | @deftypefun void glSeparableFilter2D target internalformat width height format type row column |
3c9b6116 AW |
14315 | Define a separable two-dimensional convolution filter. |
14316 | ||
8925f36f AW |
14317 | @table @asis |
14318 | @item @var{target} | |
14319 | Must be @code{GL_SEPARABLE_2D}. | |
14320 | ||
14321 | @item @var{internalformat} | |
14322 | The internal format of the convolution filter kernel. The allowable | |
14323 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, | |
14324 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
14325 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
14326 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
14327 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
14328 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
14329 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
14330 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
14331 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
14332 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
14333 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
14334 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
14335 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
14336 | ||
14337 | @item @var{width} | |
14338 | The number of elements in the pixel array referenced by @var{row}. (This | |
14339 | is the width of the separable filter kernel.) | |
14340 | ||
14341 | @item @var{height} | |
14342 | The number of elements in the pixel array referenced by @var{column}. | |
14343 | (This is the height of the separable filter kernel.) | |
14344 | ||
14345 | @item @var{format} | |
14346 | The format of the pixel data in @var{row} and @var{column}. The | |
14347 | allowable values are @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, | |
14348 | @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, | |
14349 | @code{GL_BGRA}, @code{GL_INTENSITY}, @code{GL_LUMINANCE}, and | |
14350 | @code{GL_LUMINANCE_ALPHA}. | |
14351 | ||
14352 | @item @var{type} | |
14353 | The type of the pixel data in @var{row} and @var{column}. Symbolic | |
14354 | constants @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
14355 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
14356 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
14357 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
14358 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
14359 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
14360 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
14361 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
14362 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
14363 | ||
14364 | @item @var{row} | |
14365 | Pointer to a one-dimensional array of pixel data that is processed to | |
14366 | build the row filter kernel. | |
14367 | ||
14368 | @item @var{column} | |
14369 | Pointer to a one-dimensional array of pixel data that is processed to | |
14370 | build the column filter kernel. | |
14371 | ||
14372 | @end table | |
14373 | ||
8925f36f AW |
14374 | @code{glSeparableFilter2D} builds a two-dimensional separable |
14375 | convolution filter kernel from two arrays of pixels. | |
14376 | ||
14377 | The pixel arrays specified by (@var{width}, @var{format}, @var{type}, | |
14378 | @var{row}) and (@var{height}, @var{format}, @var{type}, @var{column}) | |
14379 | are processed just as if they had been passed to @code{glDrawPixels}, | |
14380 | but processing stops after the final expansion to RGBA is completed. | |
14381 | ||
14382 | If a non-zero named buffer object is bound to the | |
14383 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
14384 | convolution filter is specified, @var{row} and @var{column} are treated | |
14385 | as byte offsets into the buffer object's data store. | |
14386 | ||
14387 | Next, the R, G, B, and A components of all pixels in both arrays are | |
14388 | scaled by the four separable 2D @code{GL_CONVOLUTION_FILTER_SCALE} | |
14389 | parameters and biased by the four separable 2D | |
14390 | @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias | |
14391 | parameters are set by @code{glConvolutionParameter} using the | |
14392 | @code{GL_SEPARABLE_2D} target and the names | |
14393 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
14394 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are vectors | |
14395 | of four values that are applied to red, green, blue, and alpha, in that | |
14396 | order.) The R, G, B, and A values are not clamped to [0,1] at any time | |
14397 | during this process. | |
14398 | ||
14399 | Each pixel is then converted to the internal format specified by | |
14400 | @var{internalformat}. This conversion simply maps the component values | |
14401 | of the pixel (R, G, B, and A) to the values included in the internal | |
14402 | format (red, green, blue, alpha, luminance, and intensity). The mapping | |
14403 | is as follows: | |
14404 | ||
14405 | @table @asis | |
14406 | @item @strong{Internal Format} | |
14407 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
14408 | @strong{Luminance}, @strong{Intensity} | |
14409 | ||
14410 | @item @code{GL_LUMINANCE} | |
14411 | , , , , R , | |
14412 | ||
14413 | @item @code{GL_LUMINANCE_ALPHA} | |
14414 | , , , A , R , | |
14415 | ||
14416 | @item @code{GL_INTENSITY} | |
14417 | , , , , , R | |
14418 | ||
14419 | @item @code{GL_RGB} | |
14420 | R , G , B , , , | |
14421 | ||
14422 | @item @code{GL_RGBA} | |
14423 | R , G , B , A , , | |
14424 | ||
14425 | @end table | |
14426 | ||
14427 | The red, green, blue, alpha, luminance, and/or intensity components of | |
14428 | the resulting pixels are stored in floating-point rather than integer | |
14429 | format. They form two one-dimensional filter kernel images. The row | |
14430 | image is indexed by coordinate @var{i} starting at zero and increasing | |
14431 | from left to right. Each location in the row image is derived from | |
14432 | element @var{i} of @var{row}. The column image is indexed by coordinate | |
14433 | @var{j} starting at zero and increasing from bottom to top. Each | |
14434 | location in the column image is derived from element @var{j} of | |
14435 | @var{column}. | |
14436 | ||
14437 | Note that after a convolution is performed, the resulting color | |
14438 | components are also scaled by their corresponding | |
14439 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
14440 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
14441 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
14442 | and @strong{ALPHA}). These parameters are set by @code{glPixelTransfer}. | |
14443 | ||
8925f36f AW |
14444 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
14445 | @code{GL_SEPARABLE_2D}. | |
14446 | ||
14447 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
14448 | of the allowable values. | |
14449 | ||
14450 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
14451 | allowable values. | |
14452 | ||
14453 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
14454 | allowable values. | |
14455 | ||
14456 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
14457 | greater than the maximum supported value. This value may be queried with | |
14458 | @code{glGetConvolutionParameter} using target @code{GL_SEPARABLE_2D} and | |
14459 | name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
14460 | ||
14461 | @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero | |
14462 | or greater than the maximum supported value. This value may be queried | |
14463 | with @code{glGetConvolutionParameter} using target | |
14464 | @code{GL_SEPARABLE_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}. | |
14465 | ||
14466 | @code{GL_INVALID_OPERATION} is generated if @var{height} is one of | |
14467 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
14468 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
14469 | and @var{format} is not @code{GL_RGB}. | |
14470 | ||
14471 | @code{GL_INVALID_OPERATION} is generated if @var{height} is one of | |
14472 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
14473 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
14474 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
14475 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
14476 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
14477 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
14478 | ||
14479 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
14480 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
14481 | object's data store is currently mapped. | |
14482 | ||
14483 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
14484 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
14485 | would be unpacked from the buffer object such that the memory reads | |
14486 | required would exceed the data store size. | |
14487 | ||
14488 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
14489 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{row} | |
14490 | or @var{column} is not evenly divisible into the number of bytes needed | |
14491 | to store in memory a datum indicated by @var{type}. | |
14492 | ||
14493 | @code{GL_INVALID_OPERATION} is generated if @code{glSeparableFilter2D} | |
14494 | is executed between the execution of @code{glBegin} and the | |
14495 | corresponding execution of @code{glEnd}. | |
14496 | ||
bb894c9d | 14497 | @end deftypefun |
8925f36f | 14498 | |
bb894c9d | 14499 | @deftypefun void glShadeModel mode |
3c9b6116 AW |
14500 | Select flat or smooth shading. |
14501 | ||
8925f36f AW |
14502 | @table @asis |
14503 | @item @var{mode} | |
14504 | Specifies a symbolic value representing a shading technique. Accepted | |
14505 | values are @code{GL_FLAT} and @code{GL_SMOOTH}. The initial value is | |
14506 | @code{GL_SMOOTH}. | |
14507 | ||
14508 | @end table | |
14509 | ||
8925f36f AW |
14510 | GL primitives can have either flat or smooth shading. Smooth shading, |
14511 | the default, causes the computed colors of vertices to be interpolated | |
14512 | as the primitive is rasterized, typically assigning different colors to | |
14513 | each resulting pixel fragment. Flat shading selects the computed color | |
14514 | of just one vertex and assigns it to all the pixel fragments generated | |
14515 | by rasterizing a single primitive. In either case, the computed color of | |
14516 | a vertex is the result of lighting if lighting is enabled, or it is the | |
14517 | current color at the time the vertex was specified if lighting is | |
14518 | disabled. | |
14519 | ||
14520 | Flat and smooth shading are indistinguishable for points. Starting when | |
14521 | @code{glBegin} is issued and counting vertices and primitives from 1, | |
3c9b6116 AW |
14522 | the GL gives each flat-shaded line segment @r{@var{i}} the computed |
14523 | color of vertex @r{@var{i}+1}, its second vertex. Counting similarly | |
8925f36f AW |
14524 | from 1, the GL gives each flat-shaded polygon the computed color of the |
14525 | vertex listed in the following table. This is the last vertex to specify | |
14526 | the polygon in all cases except single polygons, where the first vertex | |
14527 | specifies the flat-shaded color. | |
14528 | ||
14529 | ||
14530 | ||
14531 | @table @asis | |
14532 | @item @strong{ | |
3c9b6116 | 14533 | Primitive Type of Polygon @r{@var{i}}} |
8925f36f AW |
14534 | @strong{Vertex} |
14535 | ||
14536 | @item | |
14537 | Single polygon | |
3c9b6116 | 14538 | (@r{@var{i}==1}) |
8925f36f AW |
14539 | 1 |
14540 | ||
14541 | @item | |
14542 | Triangle strip | |
3c9b6116 | 14543 | @r{@var{i}+2} |
8925f36f AW |
14544 | |
14545 | @item | |
14546 | Triangle fan | |
3c9b6116 | 14547 | @r{@var{i}+2} |
8925f36f AW |
14548 | |
14549 | @item | |
14550 | Independent triangle | |
3c9b6116 | 14551 | @r{3@var{i}} |
8925f36f AW |
14552 | |
14553 | @item | |
14554 | Quad strip | |
3c9b6116 | 14555 | @r{2@var{i}+2} |
8925f36f AW |
14556 | |
14557 | @item | |
14558 | Independent quad | |
3c9b6116 | 14559 | @r{4@var{i}} |
8925f36f AW |
14560 | |
14561 | @end table | |
14562 | ||
14563 | Flat and smooth shading are specified by @code{glShadeModel} with | |
14564 | @var{mode} set to @code{GL_FLAT} and @code{GL_SMOOTH}, respectively. | |
14565 | ||
8925f36f AW |
14566 | @code{GL_INVALID_ENUM} is generated if @var{mode} is any value other |
14567 | than @code{GL_FLAT} or @code{GL_SMOOTH}. | |
14568 | ||
14569 | @code{GL_INVALID_OPERATION} is generated if @code{glShadeModel} is | |
14570 | executed between the execution of @code{glBegin} and the corresponding | |
14571 | execution of @code{glEnd}. | |
14572 | ||
bb894c9d | 14573 | @end deftypefun |
8925f36f | 14574 | |
bb894c9d | 14575 | @deftypefun void glShaderSource shader count string length |
3c9b6116 AW |
14576 | Replaces the source code in a shader object. |
14577 | ||
8925f36f AW |
14578 | @table @asis |
14579 | @item @var{shader} | |
14580 | Specifies the handle of the shader object whose source code is to be | |
14581 | replaced. | |
14582 | ||
14583 | @item @var{count} | |
14584 | Specifies the number of elements in the @var{string} and @var{length} | |
14585 | arrays. | |
14586 | ||
14587 | @item @var{string} | |
14588 | Specifies an array of pointers to strings containing the source code to | |
14589 | be loaded into the shader. | |
14590 | ||
14591 | @item @var{length} | |
14592 | Specifies an array of string lengths. | |
14593 | ||
14594 | @end table | |
14595 | ||
8925f36f AW |
14596 | @code{glShaderSource} sets the source code in @var{shader} to the source |
14597 | code in the array of strings specified by @var{string}. Any source code | |
14598 | previously stored in the shader object is completely replaced. The | |
14599 | number of strings in the array is specified by @var{count}. If | |
14600 | @var{length} is @code{NULL}, each string is assumed to be null | |
14601 | terminated. If @var{length} is a value other than @code{NULL}, it points | |
14602 | to an array containing a string length for each of the corresponding | |
14603 | elements of @var{string}. Each element in the @var{length} array may | |
14604 | contain the length of the corresponding string (the null character is | |
14605 | not counted as part of the string length) or a value less than 0 to | |
14606 | indicate that the string is null terminated. The source code strings are | |
14607 | not scanned or parsed at this time; they are simply copied into the | |
14608 | specified shader object. | |
14609 | ||
8925f36f AW |
14610 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
14611 | generated by OpenGL. | |
14612 | ||
14613 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
14614 | object. | |
14615 | ||
14616 | @code{GL_INVALID_VALUE} is generated if @var{count} is less than 0. | |
14617 | ||
14618 | @code{GL_INVALID_OPERATION} is generated if @code{glShaderSource} is | |
14619 | executed between the execution of @code{glBegin} and the corresponding | |
14620 | execution of @code{glEnd}. | |
14621 | ||
bb894c9d | 14622 | @end deftypefun |
8925f36f | 14623 | |
bb894c9d | 14624 | @deftypefun void glStencilFuncSeparate face func ref mask |
3c9b6116 AW |
14625 | Set front and/or back function and reference value for stencil testing. |
14626 | ||
8925f36f AW |
14627 | @table @asis |
14628 | @item @var{face} | |
14629 | Specifies whether front and/or back stencil state is updated. Three | |
14630 | symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and | |
14631 | @code{GL_FRONT_AND_BACK}. | |
14632 | ||
14633 | @item @var{func} | |
14634 | Specifies the test function. Eight symbolic constants are valid: | |
14635 | @code{GL_NEVER}, @code{GL_LESS}, @code{GL_LEQUAL}, @code{GL_GREATER}, | |
14636 | @code{GL_GEQUAL}, @code{GL_EQUAL}, @code{GL_NOTEQUAL}, and | |
14637 | @code{GL_ALWAYS}. The initial value is @code{GL_ALWAYS}. | |
14638 | ||
14639 | @item @var{ref} | |
14640 | Specifies the reference value for the stencil test. @var{ref} is clamped | |
3c9b6116 AW |
14641 | to the range @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of |
14642 | bitplanes in the stencil buffer. The initial value is 0. | |
8925f36f AW |
14643 | |
14644 | @item @var{mask} | |
14645 | Specifies a mask that is ANDed with both the reference value and the | |
14646 | stored stencil value when the test is done. The initial value is all | |
14647 | 1's. | |
14648 | ||
14649 | @end table | |
14650 | ||
8925f36f AW |
14651 | Stenciling, like depth-buffering, enables and disables drawing on a |
14652 | per-pixel basis. You draw into the stencil planes using GL drawing | |
14653 | primitives, then render geometry and images, using the stencil planes to | |
14654 | mask out portions of the screen. Stenciling is typically used in | |
14655 | multipass rendering algorithms to achieve special effects, such as | |
14656 | decals, outlining, and constructive solid geometry rendering. | |
14657 | ||
14658 | The stencil test conditionally eliminates a pixel based on the outcome | |
14659 | of a comparison between the reference value and the value in the stencil | |
14660 | buffer. To enable and disable the test, call @code{glEnable} and | |
14661 | @code{glDisable} with argument @code{GL_STENCIL_TEST}. To specify | |
14662 | actions based on the outcome of the stencil test, call | |
14663 | @code{glStencilOp} or @code{glStencilOpSeparate}. | |
14664 | ||
14665 | There can be two separate sets of @var{func}, @var{ref}, and @var{mask} | |
14666 | parameters; one affects back-facing polygons, and the other affects | |
14667 | front-facing polygons as well as other non-polygon primitives. | |
14668 | @code{glStencilFunc} sets both front and back stencil state to the same | |
14669 | values, as if @code{glStencilFuncSeparate} were called with @var{face} | |
14670 | set to @code{GL_FRONT_AND_BACK}. | |
14671 | ||
14672 | @var{func} is a symbolic constant that determines the stencil comparison | |
14673 | function. It accepts one of eight values, shown in the following list. | |
14674 | @var{ref} is an integer reference value that is used in the stencil | |
3c9b6116 AW |
14675 | comparison. It is clamped to the range @r{[0,2^@var{n}-1]}, where |
14676 | @r{@var{n}} is the number of bitplanes in the stencil buffer. @var{mask} | |
14677 | is bitwise ANDed with both the reference value and the stored stencil | |
14678 | value, with the ANDed values participating in the comparison. | |
8925f36f AW |
14679 | |
14680 | If @var{stencil} represents the value stored in the corresponding | |
14681 | stencil buffer location, the following list shows the effect of each | |
14682 | comparison function that can be specified by @var{func}. Only if the | |
14683 | comparison succeeds is the pixel passed through to the next stage in the | |
14684 | rasterization process (see @code{glStencilOp}). All tests treat | |
14685 | @var{stencil} values as unsigned integers in the range | |
3c9b6116 AW |
14686 | @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of bitplanes in the |
14687 | stencil buffer. | |
8925f36f AW |
14688 | |
14689 | The following values are accepted by @var{func}: | |
14690 | ||
14691 | @table @asis | |
14692 | @item @code{GL_NEVER} | |
14693 | Always fails. | |
14694 | ||
14695 | @item @code{GL_LESS} | |
14696 | Passes if ( @var{ref} & @var{mask} ) < ( @var{stencil} & @var{mask} ). | |
14697 | ||
14698 | @item @code{GL_LEQUAL} | |
14699 | Passes if ( @var{ref} & @var{mask} ) <= ( @var{stencil} & @var{mask} ). | |
14700 | ||
14701 | @item @code{GL_GREATER} | |
14702 | Passes if ( @var{ref} & @var{mask} ) > ( @var{stencil} & @var{mask} ). | |
14703 | ||
14704 | @item @code{GL_GEQUAL} | |
14705 | Passes if ( @var{ref} & @var{mask} ) >= ( @var{stencil} & @var{mask} ). | |
14706 | ||
14707 | @item @code{GL_EQUAL} | |
14708 | Passes if ( @var{ref} & @var{mask} ) = ( @var{stencil} & @var{mask} ). | |
14709 | ||
14710 | @item @code{GL_NOTEQUAL} | |
14711 | Passes if ( @var{ref} & @var{mask} ) != ( @var{stencil} & @var{mask} ). | |
14712 | ||
14713 | @item @code{GL_ALWAYS} | |
14714 | Always passes. | |
14715 | ||
14716 | @end table | |
14717 | ||
8925f36f AW |
14718 | @code{GL_INVALID_ENUM} is generated if @var{func} is not one of the |
14719 | eight accepted values. | |
14720 | ||
14721 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilFuncSeparate} | |
14722 | is executed between the execution of @code{glBegin} and the | |
14723 | corresponding execution of @code{glEnd}. | |
14724 | ||
bb894c9d | 14725 | @end deftypefun |
8925f36f | 14726 | |
bb894c9d | 14727 | @deftypefun void glStencilFunc func ref mask |
3c9b6116 AW |
14728 | Set front and back function and reference value for stencil testing. |
14729 | ||
8925f36f AW |
14730 | @table @asis |
14731 | @item @var{func} | |
14732 | Specifies the test function. Eight symbolic constants are valid: | |
14733 | @code{GL_NEVER}, @code{GL_LESS}, @code{GL_LEQUAL}, @code{GL_GREATER}, | |
14734 | @code{GL_GEQUAL}, @code{GL_EQUAL}, @code{GL_NOTEQUAL}, and | |
14735 | @code{GL_ALWAYS}. The initial value is @code{GL_ALWAYS}. | |
14736 | ||
14737 | @item @var{ref} | |
14738 | Specifies the reference value for the stencil test. @var{ref} is clamped | |
3c9b6116 AW |
14739 | to the range @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of |
14740 | bitplanes in the stencil buffer. The initial value is 0. | |
8925f36f AW |
14741 | |
14742 | @item @var{mask} | |
14743 | Specifies a mask that is ANDed with both the reference value and the | |
14744 | stored stencil value when the test is done. The initial value is all | |
14745 | 1's. | |
14746 | ||
14747 | @end table | |
14748 | ||
8925f36f AW |
14749 | Stenciling, like depth-buffering, enables and disables drawing on a |
14750 | per-pixel basis. Stencil planes are first drawn into using GL drawing | |
14751 | primitives, then geometry and images are rendered using the stencil | |
14752 | planes to mask out portions of the screen. Stenciling is typically used | |
14753 | in multipass rendering algorithms to achieve special effects, such as | |
14754 | decals, outlining, and constructive solid geometry rendering. | |
14755 | ||
14756 | The stencil test conditionally eliminates a pixel based on the outcome | |
14757 | of a comparison between the reference value and the value in the stencil | |
14758 | buffer. To enable and disable the test, call @code{glEnable} and | |
14759 | @code{glDisable} with argument @code{GL_STENCIL_TEST}. To specify | |
14760 | actions based on the outcome of the stencil test, call | |
14761 | @code{glStencilOp} or @code{glStencilOpSeparate}. | |
14762 | ||
14763 | There can be two separate sets of @var{func}, @var{ref}, and @var{mask} | |
14764 | parameters; one affects back-facing polygons, and the other affects | |
14765 | front-facing polygons as well as other non-polygon primitives. | |
14766 | @code{glStencilFunc} sets both front and back stencil state to the same | |
14767 | values. Use @code{glStencilFuncSeparate} to set front and back stencil | |
14768 | state to different values. | |
14769 | ||
14770 | @var{func} is a symbolic constant that determines the stencil comparison | |
14771 | function. It accepts one of eight values, shown in the following list. | |
14772 | @var{ref} is an integer reference value that is used in the stencil | |
3c9b6116 AW |
14773 | comparison. It is clamped to the range @r{[0,2^@var{n}-1]}, where |
14774 | @r{@var{n}} is the number of bitplanes in the stencil buffer. @var{mask} | |
14775 | is bitwise ANDed with both the reference value and the stored stencil | |
14776 | value, with the ANDed values participating in the comparison. | |
8925f36f AW |
14777 | |
14778 | If @var{stencil} represents the value stored in the corresponding | |
14779 | stencil buffer location, the following list shows the effect of each | |
14780 | comparison function that can be specified by @var{func}. Only if the | |
14781 | comparison succeeds is the pixel passed through to the next stage in the | |
14782 | rasterization process (see @code{glStencilOp}). All tests treat | |
14783 | @var{stencil} values as unsigned integers in the range | |
3c9b6116 AW |
14784 | @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of bitplanes in the |
14785 | stencil buffer. | |
8925f36f AW |
14786 | |
14787 | The following values are accepted by @var{func}: | |
14788 | ||
14789 | @table @asis | |
14790 | @item @code{GL_NEVER} | |
14791 | Always fails. | |
14792 | ||
14793 | @item @code{GL_LESS} | |
14794 | Passes if ( @var{ref} & @var{mask} ) < ( @var{stencil} & @var{mask} ). | |
14795 | ||
14796 | @item @code{GL_LEQUAL} | |
14797 | Passes if ( @var{ref} & @var{mask} ) <= ( @var{stencil} & @var{mask} ). | |
14798 | ||
14799 | @item @code{GL_GREATER} | |
14800 | Passes if ( @var{ref} & @var{mask} ) > ( @var{stencil} & @var{mask} ). | |
14801 | ||
14802 | @item @code{GL_GEQUAL} | |
14803 | Passes if ( @var{ref} & @var{mask} ) >= ( @var{stencil} & @var{mask} ). | |
14804 | ||
14805 | @item @code{GL_EQUAL} | |
14806 | Passes if ( @var{ref} & @var{mask} ) = ( @var{stencil} & @var{mask} ). | |
14807 | ||
14808 | @item @code{GL_NOTEQUAL} | |
14809 | Passes if ( @var{ref} & @var{mask} ) != ( @var{stencil} & @var{mask} ). | |
14810 | ||
14811 | @item @code{GL_ALWAYS} | |
14812 | Always passes. | |
14813 | ||
14814 | @end table | |
14815 | ||
8925f36f AW |
14816 | @code{GL_INVALID_ENUM} is generated if @var{func} is not one of the |
14817 | eight accepted values. | |
14818 | ||
14819 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilFunc} is | |
14820 | executed between the execution of @code{glBegin} and the corresponding | |
14821 | execution of @code{glEnd}. | |
14822 | ||
bb894c9d | 14823 | @end deftypefun |
8925f36f | 14824 | |
bb894c9d | 14825 | @deftypefun void glStencilMaskSeparate face mask |
3c9b6116 AW |
14826 | Control the front and/or back writing of individual bits in the stencil |
14827 | planes. | |
14828 | ||
8925f36f AW |
14829 | @table @asis |
14830 | @item @var{face} | |
14831 | Specifies whether the front and/or back stencil writemask is updated. | |
14832 | Three symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and | |
14833 | @code{GL_FRONT_AND_BACK}. | |
14834 | ||
14835 | @item @var{mask} | |
14836 | Specifies a bit mask to enable and disable writing of individual bits in | |
14837 | the stencil planes. Initially, the mask is all 1's. | |
14838 | ||
14839 | @end table | |
14840 | ||
8925f36f | 14841 | @code{glStencilMaskSeparate} controls the writing of individual bits in |
3c9b6116 AW |
14842 | the stencil planes. The least significant @r{@var{n}} bits of |
14843 | @var{mask}, where @r{@var{n}} is the number of bits in the stencil | |
8925f36f AW |
14844 | buffer, specify a mask. Where a 1 appears in the mask, it's possible to |
14845 | write to the corresponding bit in the stencil buffer. Where a 0 appears, | |
14846 | the corresponding bit is write-protected. Initially, all bits are | |
14847 | enabled for writing. | |
14848 | ||
14849 | There can be two separate @var{mask} writemasks; one affects back-facing | |
14850 | polygons, and the other affects front-facing polygons as well as other | |
14851 | non-polygon primitives. @code{glStencilMask} sets both front and back | |
14852 | stencil writemasks to the same values, as if | |
14853 | @code{glStencilMaskSeparate} were called with @var{face} set to | |
14854 | @code{GL_FRONT_AND_BACK}. | |
14855 | ||
8925f36f AW |
14856 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilMaskSeparate} |
14857 | is executed between the execution of @code{glBegin} and the | |
14858 | corresponding execution of @code{glEnd}. | |
14859 | ||
bb894c9d | 14860 | @end deftypefun |
8925f36f | 14861 | |
bb894c9d | 14862 | @deftypefun void glStencilMask mask |
3c9b6116 AW |
14863 | Control the front and back writing of individual bits in the stencil |
14864 | planes. | |
14865 | ||
8925f36f AW |
14866 | @table @asis |
14867 | @item @var{mask} | |
14868 | Specifies a bit mask to enable and disable writing of individual bits in | |
14869 | the stencil planes. Initially, the mask is all 1's. | |
14870 | ||
14871 | @end table | |
14872 | ||
8925f36f | 14873 | @code{glStencilMask} controls the writing of individual bits in the |
3c9b6116 AW |
14874 | stencil planes. The least significant @r{@var{n}} bits of @var{mask}, |
14875 | where @r{@var{n}} is the number of bits in the stencil buffer, specify a | |
14876 | mask. Where a 1 appears in the mask, it's possible to write to the | |
14877 | corresponding bit in the stencil buffer. Where a 0 appears, the | |
8925f36f AW |
14878 | corresponding bit is write-protected. Initially, all bits are enabled |
14879 | for writing. | |
14880 | ||
14881 | There can be two separate @var{mask} writemasks; one affects back-facing | |
14882 | polygons, and the other affects front-facing polygons as well as other | |
14883 | non-polygon primitives. @code{glStencilMask} sets both front and back | |
14884 | stencil writemasks to the same values. Use @code{glStencilMaskSeparate} | |
14885 | to set front and back stencil writemasks to different values. | |
14886 | ||
8925f36f AW |
14887 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilMask} is |
14888 | executed between the execution of @code{glBegin} and the corresponding | |
14889 | execution of @code{glEnd}. | |
14890 | ||
bb894c9d | 14891 | @end deftypefun |
8925f36f | 14892 | |
bb894c9d | 14893 | @deftypefun void glStencilOpSeparate face sfail dpfail dppass |
3c9b6116 AW |
14894 | Set front and/or back stencil test actions. |
14895 | ||
8925f36f AW |
14896 | @table @asis |
14897 | @item @var{face} | |
14898 | Specifies whether front and/or back stencil state is updated. Three | |
14899 | symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and | |
14900 | @code{GL_FRONT_AND_BACK}. | |
14901 | ||
14902 | @item @var{sfail} | |
14903 | Specifies the action to take when the stencil test fails. Eight symbolic | |
14904 | constants are accepted: @code{GL_KEEP}, @code{GL_ZERO}, | |
14905 | @code{GL_REPLACE}, @code{GL_INCR}, @code{GL_INCR_WRAP}, @code{GL_DECR}, | |
14906 | @code{GL_DECR_WRAP}, and @code{GL_INVERT}. The initial value is | |
14907 | @code{GL_KEEP}. | |
14908 | ||
14909 | @item @var{dpfail} | |
14910 | Specifies the stencil action when the stencil test passes, but the depth | |
14911 | test fails. @var{dpfail} accepts the same symbolic constants as | |
14912 | @var{sfail}. The initial value is @code{GL_KEEP}. | |
14913 | ||
14914 | @item @var{dppass} | |
14915 | Specifies the stencil action when both the stencil test and the depth | |
14916 | test pass, or when the stencil test passes and either there is no depth | |
14917 | buffer or depth testing is not enabled. @var{dppass} accepts the same | |
14918 | symbolic constants as @var{sfail}. The initial value is @code{GL_KEEP}. | |
14919 | ||
14920 | @end table | |
14921 | ||
8925f36f AW |
14922 | Stenciling, like depth-buffering, enables and disables drawing on a |
14923 | per-pixel basis. You draw into the stencil planes using GL drawing | |
14924 | primitives, then render geometry and images, using the stencil planes to | |
14925 | mask out portions of the screen. Stenciling is typically used in | |
14926 | multipass rendering algorithms to achieve special effects, such as | |
14927 | decals, outlining, and constructive solid geometry rendering. | |
14928 | ||
14929 | The stencil test conditionally eliminates a pixel based on the outcome | |
14930 | of a comparison between the value in the stencil buffer and a reference | |
14931 | value. To enable and disable the test, call @code{glEnable} and | |
14932 | @code{glDisable} with argument @code{GL_STENCIL_TEST}; to control it, | |
14933 | call @code{glStencilFunc} or @code{glStencilFuncSeparate}. | |
14934 | ||
14935 | There can be two separate sets of @var{sfail}, @var{dpfail}, and | |
14936 | @var{dppass} parameters; one affects back-facing polygons, and the other | |
14937 | affects front-facing polygons as well as other non-polygon primitives. | |
14938 | @code{glStencilOp} sets both front and back stencil state to the same | |
14939 | values, as if @code{glStencilOpSeparate} were called with @var{face} set | |
14940 | to @code{GL_FRONT_AND_BACK}. | |
14941 | ||
14942 | @code{glStencilOpSeparate} takes three arguments that indicate what | |
14943 | happens to the stored stencil value while stenciling is enabled. If the | |
14944 | stencil test fails, no change is made to the pixel's color or depth | |
14945 | buffers, and @var{sfail} specifies what happens to the stencil buffer | |
14946 | contents. The following eight actions are possible. | |
14947 | ||
14948 | @table @asis | |
14949 | @item @code{GL_KEEP} | |
14950 | Keeps the current value. | |
14951 | ||
14952 | @item @code{GL_ZERO} | |
14953 | Sets the stencil buffer value to 0. | |
14954 | ||
14955 | @item @code{GL_REPLACE} | |
14956 | Sets the stencil buffer value to @var{ref}, as specified by | |
14957 | @code{glStencilFunc}. | |
14958 | ||
14959 | @item @code{GL_INCR} | |
14960 | Increments the current stencil buffer value. Clamps to the maximum | |
14961 | representable unsigned value. | |
14962 | ||
14963 | @item @code{GL_INCR_WRAP} | |
14964 | Increments the current stencil buffer value. Wraps stencil buffer value | |
14965 | to zero when incrementing the maximum representable unsigned value. | |
14966 | ||
14967 | @item @code{GL_DECR} | |
14968 | Decrements the current stencil buffer value. Clamps to 0. | |
14969 | ||
14970 | @item @code{GL_DECR_WRAP} | |
14971 | Decrements the current stencil buffer value. Wraps stencil buffer value | |
14972 | to the maximum representable unsigned value when decrementing a stencil | |
14973 | buffer value of zero. | |
14974 | ||
14975 | @item @code{GL_INVERT} | |
14976 | Bitwise inverts the current stencil buffer value. | |
14977 | ||
14978 | @end table | |
14979 | ||
14980 | Stencil buffer values are treated as unsigned integers. When incremented | |
3c9b6116 AW |
14981 | and decremented, values are clamped to 0 and @r{2^@var{n}-1}, where |
14982 | @r{@var{n}} is the value returned by querying @code{GL_STENCIL_BITS}. | |
8925f36f AW |
14983 | |
14984 | The other two arguments to @code{glStencilOpSeparate} specify stencil | |
14985 | buffer actions that depend on whether subsequent depth buffer tests | |
14986 | succeed (@var{dppass}) or fail (@var{dpfail}) (see @code{glDepthFunc}). | |
14987 | The actions are specified using the same eight symbolic constants as | |
14988 | @var{sfail}. Note that @var{dpfail} is ignored when there is no depth | |
14989 | buffer, or when the depth buffer is not enabled. In these cases, | |
14990 | @var{sfail} and @var{dppass} specify stencil action when the stencil | |
14991 | test fails and passes, respectively. | |
14992 | ||
8925f36f AW |
14993 | @code{GL_INVALID_ENUM} is generated if @var{face} is any value other |
14994 | than @code{GL_FRONT}, @code{GL_BACK}, or @code{GL_FRONT_AND_BACK}. | |
14995 | ||
14996 | @code{GL_INVALID_ENUM} is generated if @var{sfail}, @var{dpfail}, or | |
14997 | @var{dppass} is any value other than the eight defined constant values. | |
14998 | ||
14999 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilOpSeparate} | |
15000 | is executed between the execution of @code{glBegin} and the | |
15001 | corresponding execution of @code{glEnd}. | |
15002 | ||
bb894c9d | 15003 | @end deftypefun |
8925f36f | 15004 | |
bb894c9d | 15005 | @deftypefun void glStencilOp sfail dpfail dppass |
3c9b6116 AW |
15006 | Set front and back stencil test actions. |
15007 | ||
8925f36f AW |
15008 | @table @asis |
15009 | @item @var{sfail} | |
15010 | Specifies the action to take when the stencil test fails. Eight symbolic | |
15011 | constants are accepted: @code{GL_KEEP}, @code{GL_ZERO}, | |
15012 | @code{GL_REPLACE}, @code{GL_INCR}, @code{GL_INCR_WRAP}, @code{GL_DECR}, | |
15013 | @code{GL_DECR_WRAP}, and @code{GL_INVERT}. The initial value is | |
15014 | @code{GL_KEEP}. | |
15015 | ||
15016 | @item @var{dpfail} | |
15017 | Specifies the stencil action when the stencil test passes, but the depth | |
15018 | test fails. @var{dpfail} accepts the same symbolic constants as | |
15019 | @var{sfail}. The initial value is @code{GL_KEEP}. | |
15020 | ||
15021 | @item @var{dppass} | |
15022 | Specifies the stencil action when both the stencil test and the depth | |
15023 | test pass, or when the stencil test passes and either there is no depth | |
15024 | buffer or depth testing is not enabled. @var{dppass} accepts the same | |
15025 | symbolic constants as @var{sfail}. The initial value is @code{GL_KEEP}. | |
15026 | ||
15027 | @end table | |
15028 | ||
8925f36f AW |
15029 | Stenciling, like depth-buffering, enables and disables drawing on a |
15030 | per-pixel basis. You draw into the stencil planes using GL drawing | |
15031 | primitives, then render geometry and images, using the stencil planes to | |
15032 | mask out portions of the screen. Stenciling is typically used in | |
15033 | multipass rendering algorithms to achieve special effects, such as | |
15034 | decals, outlining, and constructive solid geometry rendering. | |
15035 | ||
15036 | The stencil test conditionally eliminates a pixel based on the outcome | |
15037 | of a comparison between the value in the stencil buffer and a reference | |
15038 | value. To enable and disable the test, call @code{glEnable} and | |
15039 | @code{glDisable} with argument @code{GL_STENCIL_TEST}; to control it, | |
15040 | call @code{glStencilFunc} or @code{glStencilFuncSeparate}. | |
15041 | ||
15042 | There can be two separate sets of @var{sfail}, @var{dpfail}, and | |
15043 | @var{dppass} parameters; one affects back-facing polygons, and the other | |
15044 | affects front-facing polygons as well as other non-polygon primitives. | |
15045 | @code{glStencilOp} sets both front and back stencil state to the same | |
15046 | values. Use @code{glStencilOpSeparate} to set front and back stencil | |
15047 | state to different values. | |
15048 | ||
15049 | @code{glStencilOp} takes three arguments that indicate what happens to | |
15050 | the stored stencil value while stenciling is enabled. If the stencil | |
15051 | test fails, no change is made to the pixel's color or depth buffers, and | |
15052 | @var{sfail} specifies what happens to the stencil buffer contents. The | |
15053 | following eight actions are possible. | |
15054 | ||
15055 | @table @asis | |
15056 | @item @code{GL_KEEP} | |
15057 | Keeps the current value. | |
15058 | ||
15059 | @item @code{GL_ZERO} | |
15060 | Sets the stencil buffer value to 0. | |
15061 | ||
15062 | @item @code{GL_REPLACE} | |
15063 | Sets the stencil buffer value to @var{ref}, as specified by | |
15064 | @code{glStencilFunc}. | |
15065 | ||
15066 | @item @code{GL_INCR} | |
15067 | Increments the current stencil buffer value. Clamps to the maximum | |
15068 | representable unsigned value. | |
15069 | ||
15070 | @item @code{GL_INCR_WRAP} | |
15071 | Increments the current stencil buffer value. Wraps stencil buffer value | |
15072 | to zero when incrementing the maximum representable unsigned value. | |
15073 | ||
15074 | @item @code{GL_DECR} | |
15075 | Decrements the current stencil buffer value. Clamps to 0. | |
15076 | ||
15077 | @item @code{GL_DECR_WRAP} | |
15078 | Decrements the current stencil buffer value. Wraps stencil buffer value | |
15079 | to the maximum representable unsigned value when decrementing a stencil | |
15080 | buffer value of zero. | |
15081 | ||
15082 | @item @code{GL_INVERT} | |
15083 | Bitwise inverts the current stencil buffer value. | |
15084 | ||
15085 | @end table | |
15086 | ||
15087 | Stencil buffer values are treated as unsigned integers. When incremented | |
3c9b6116 AW |
15088 | and decremented, values are clamped to 0 and @r{2^@var{n}-1}, where |
15089 | @r{@var{n}} is the value returned by querying @code{GL_STENCIL_BITS}. | |
8925f36f AW |
15090 | |
15091 | The other two arguments to @code{glStencilOp} specify stencil buffer | |
15092 | actions that depend on whether subsequent depth buffer tests succeed | |
15093 | (@var{dppass}) or fail (@var{dpfail}) (see @code{glDepthFunc}). The | |
15094 | actions are specified using the same eight symbolic constants as | |
15095 | @var{sfail}. Note that @var{dpfail} is ignored when there is no depth | |
15096 | buffer, or when the depth buffer is not enabled. In these cases, | |
15097 | @var{sfail} and @var{dppass} specify stencil action when the stencil | |
15098 | test fails and passes, respectively. | |
15099 | ||
8925f36f AW |
15100 | @code{GL_INVALID_ENUM} is generated if @var{sfail}, @var{dpfail}, or |
15101 | @var{dppass} is any value other than the eight defined constant values. | |
15102 | ||
15103 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilOp} is | |
15104 | executed between the execution of @code{glBegin} and the corresponding | |
15105 | execution of @code{glEnd}. | |
15106 | ||
bb894c9d | 15107 | @end deftypefun |
8925f36f | 15108 | |
bb894c9d | 15109 | @deftypefun void glTexCoordPointer size type stride pointer |
3c9b6116 AW |
15110 | Define an array of texture coordinates. |
15111 | ||
8925f36f AW |
15112 | @table @asis |
15113 | @item @var{size} | |
15114 | Specifies the number of coordinates per array element. Must be 1, 2, 3, | |
15115 | or 4. The initial value is 4. | |
15116 | ||
15117 | @item @var{type} | |
15118 | Specifies the data type of each texture coordinate. Symbolic constants | |
15119 | @code{GL_SHORT}, @code{GL_INT}, @code{GL_FLOAT}, or @code{GL_DOUBLE} are | |
15120 | accepted. The initial value is @code{GL_FLOAT}. | |
15121 | ||
15122 | @item @var{stride} | |
15123 | Specifies the byte offset between consecutive texture coordinate sets. | |
15124 | If @var{stride} is 0, the array elements are understood to be tightly | |
15125 | packed. The initial value is 0. | |
15126 | ||
15127 | @item @var{pointer} | |
15128 | Specifies a pointer to the first coordinate of the first texture | |
15129 | coordinate set in the array. The initial value is 0. | |
15130 | ||
15131 | @end table | |
15132 | ||
8925f36f AW |
15133 | @code{glTexCoordPointer} specifies the location and data format of an |
15134 | array of texture coordinates to use when rendering. @var{size} specifies | |
15135 | the number of coordinates per texture coordinate set, and must be 1, 2, | |
15136 | 3, or 4. @var{type} specifies the data type of each texture coordinate, | |
15137 | and @var{stride} specifies the byte stride from one texture coordinate | |
15138 | set to the next, allowing vertices and attributes to be packed into a | |
15139 | single array or stored in separate arrays. (Single-array storage may be | |
15140 | more efficient on some implementations; see @code{glInterleavedArrays}.) | |
15141 | ||
15142 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
15143 | target (see @code{glBindBuffer}) while a texture coordinate array is | |
15144 | specified, @var{pointer} is treated as a byte offset into the buffer | |
15145 | object's data store. Also, the buffer object binding | |
15146 | (@code{GL_ARRAY_BUFFER_BINDING}) is saved as texture coordinate vertex | |
15147 | array client-side state (@code{GL_TEXTURE_COORD_ARRAY_BUFFER_BINDING}). | |
15148 | ||
15149 | When a texture coordinate array is specified, @var{size}, @var{type}, | |
15150 | @var{stride}, and @var{pointer} are saved as client-side state, in | |
15151 | addition to the current vertex array buffer object binding. | |
15152 | ||
15153 | To enable and disable a texture coordinate array, call | |
15154 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
15155 | argument @code{GL_TEXTURE_COORD_ARRAY}. If enabled, the texture | |
15156 | coordinate array is used when @code{glArrayElement}, | |
15157 | @code{glDrawArrays}, @code{glMultiDrawArrays}, @code{glDrawElements}, | |
15158 | @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called. | |
15159 | ||
8925f36f AW |
15160 | @code{GL_INVALID_VALUE} is generated if @var{size} is not 1, 2, 3, or 4. |
15161 | ||
15162 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted | |
15163 | value. | |
15164 | ||
15165 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
15166 | ||
bb894c9d | 15167 | @end deftypefun |
8925f36f | 15168 | |
bb894c9d AW |
15169 | @deftypefun void glTexCoord1i s |
15170 | @deftypefunx void glTexCoord1d s | |
15171 | @deftypefunx void glTexCoord2i s t | |
15172 | @deftypefunx void glTexCoord2d s t | |
15173 | @deftypefunx void glTexCoord3i s t r | |
15174 | @deftypefunx void glTexCoord3d s t r | |
15175 | @deftypefunx void glTexCoord4i s t r q | |
15176 | @deftypefunx void glTexCoord4d s t r q | |
3c9b6116 AW |
15177 | Set the current texture coordinates. |
15178 | ||
8925f36f AW |
15179 | @table @asis |
15180 | @item @var{s} | |
15181 | @itemx @var{t} | |
15182 | @itemx @var{r} | |
15183 | @itemx @var{q} | |
15184 | Specify @var{s}, @var{t}, @var{r}, and @var{q} texture coordinates. Not | |
15185 | all parameters are present in all forms of the command. | |
15186 | ||
15187 | @end table | |
15188 | ||
8925f36f AW |
15189 | @code{glTexCoord} specifies texture coordinates in one, two, three, or |
15190 | four dimensions. @code{glTexCoord1} sets the current texture coordinates | |
3c9b6116 AW |
15191 | to @r{(@var{s},001)}; a call to @code{glTexCoord2} sets them to |
15192 | @r{(@var{s},@var{t}01)}. Similarly, @code{glTexCoord3} specifies the | |
15193 | texture coordinates as @r{(@var{s},@var{t}@var{r}1)}, and | |
8925f36f | 15194 | @code{glTexCoord4} defines all four components explicitly as |
3c9b6116 | 15195 | @r{(@var{s},@var{t}@var{r}@var{q})}. |
8925f36f AW |
15196 | |
15197 | The current texture coordinates are part of the data that is associated | |
15198 | with each vertex and with the current raster position. Initially, the | |
15199 | values for @var{s}, @var{t}, @var{r}, and @var{q} are (0, 0, 0, 1). | |
15200 | ||
15201 | ||
15202 | ||
bb894c9d | 15203 | @end deftypefun |
8925f36f | 15204 | |
bb894c9d AW |
15205 | @deftypefun void glTexEnvf target pname param |
15206 | @deftypefunx void glTexEnvi target pname param | |
3c9b6116 AW |
15207 | Set texture environment parameters. |
15208 | ||
8925f36f AW |
15209 | @table @asis |
15210 | @item @var{target} | |
15211 | Specifies a texture environment. May be @code{GL_TEXTURE_ENV}, | |
15212 | @code{GL_TEXTURE_FILTER_CONTROL} or @code{GL_POINT_SPRITE}. | |
15213 | ||
15214 | @item @var{pname} | |
15215 | Specifies the symbolic name of a single-valued texture environment | |
15216 | parameter. May be either @code{GL_TEXTURE_ENV_MODE}, | |
15217 | @code{GL_TEXTURE_LOD_BIAS}, @code{GL_COMBINE_RGB}, | |
15218 | @code{GL_COMBINE_ALPHA}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, | |
15219 | @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, | |
15220 | @code{GL_SRC2_ALPHA}, @code{GL_OPERAND0_RGB}, @code{GL_OPERAND1_RGB}, | |
15221 | @code{GL_OPERAND2_RGB}, @code{GL_OPERAND0_ALPHA}, | |
15222 | @code{GL_OPERAND1_ALPHA}, @code{GL_OPERAND2_ALPHA}, @code{GL_RGB_SCALE}, | |
15223 | @code{GL_ALPHA_SCALE}, or @code{GL_COORD_REPLACE}. | |
15224 | ||
15225 | @item @var{param} | |
15226 | Specifies a single symbolic constant, one of @code{GL_ADD}, | |
15227 | @code{GL_ADD_SIGNED}, @code{GL_INTERPOLATE}, @code{GL_MODULATE}, | |
15228 | @code{GL_DECAL}, @code{GL_BLEND}, @code{GL_REPLACE}, @code{GL_SUBTRACT}, | |
15229 | @code{GL_COMBINE}, @code{GL_TEXTURE}, @code{GL_CONSTANT}, | |
15230 | @code{GL_PRIMARY_COLOR}, @code{GL_PREVIOUS}, @code{GL_SRC_COLOR}, | |
15231 | @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_SRC_ALPHA}, | |
15232 | @code{GL_ONE_MINUS_SRC_ALPHA}, a single boolean value for the point | |
15233 | sprite texture coordinate replacement, a single floating-point value for | |
15234 | the texture level-of-detail bias, or 1.0, 2.0, or 4.0 when specifying | |
15235 | the @code{GL_RGB_SCALE} or @code{GL_ALPHA_SCALE}. | |
15236 | ||
15237 | @end table | |
15238 | ||
8925f36f AW |
15239 | A texture environment specifies how texture values are interpreted when |
15240 | a fragment is textured. When @var{target} is | |
15241 | @code{GL_TEXTURE_FILTER_CONTROL}, @var{pname} must be | |
15242 | @code{GL_TEXTURE_LOD_BIAS}. When @var{target} is @code{GL_TEXTURE_ENV}, | |
15243 | @var{pname} can be @code{GL_TEXTURE_ENV_MODE}, | |
15244 | @code{GL_TEXTURE_ENV_COLOR}, @code{GL_COMBINE_RGB}, | |
15245 | @code{GL_COMBINE_ALPHA}, @code{GL_RGB_SCALE}, @code{GL_ALPHA_SCALE}, | |
15246 | @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, @code{GL_SRC2_RGB}, | |
15247 | @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, or @code{GL_SRC2_ALPHA}. | |
15248 | ||
15249 | If @var{pname} is @code{GL_TEXTURE_ENV_MODE}, then @var{params} is (or | |
15250 | points to) the symbolic name of a texture function. Six texture | |
15251 | functions may be specified: @code{GL_ADD}, @code{GL_MODULATE}, | |
15252 | @code{GL_DECAL}, @code{GL_BLEND}, @code{GL_REPLACE}, or | |
15253 | @code{GL_COMBINE}. | |
15254 | ||
15255 | The following table shows the correspondence of filtered texture values | |
3c9b6116 AW |
15256 | @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}}, |
15257 | @r{@var{A}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{I}_@var{t}} to texture | |
15258 | source components. @r{@var{C}_@var{s}} and @r{@var{A}_@var{s}} are used | |
15259 | by the texture functions described below. | |
8925f36f AW |
15260 | |
15261 | ||
15262 | ||
15263 | @table @asis | |
15264 | @item | |
15265 | Texture Base Internal Format | |
3c9b6116 | 15266 | @r{@code{C}_@var{s}}, @r{@code{A}_@var{s}} |
8925f36f AW |
15267 | |
15268 | @item @code{GL_ALPHA} | |
3c9b6116 | 15269 | (0, 0, 0) , @r{@var{A}_@var{t}} |
8925f36f AW |
15270 | |
15271 | @item @code{GL_LUMINANCE} | |
3c9b6116 | 15272 | ( @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}} ) , 1 |
8925f36f AW |
15273 | |
15274 | @item @code{GL_LUMINANCE_ALPHA} | |
3c9b6116 AW |
15275 | ( @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}} ) , |
15276 | @r{@var{A}_@var{t}} | |
8925f36f AW |
15277 | |
15278 | @item @code{GL_INTENSITY} | |
3c9b6116 AW |
15279 | ( @r{@var{I}_@var{t}}, @r{@var{I}_@var{t}}, @r{@var{I}_@var{t}} ) , |
15280 | @r{@var{I}_@var{t}} | |
8925f36f AW |
15281 | |
15282 | @item @code{GL_RGB} | |
3c9b6116 | 15283 | ( @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}} ) , 1 |
8925f36f AW |
15284 | |
15285 | @item @code{GL_RGBA} | |
3c9b6116 AW |
15286 | ( @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}} ) , |
15287 | @r{@var{A}_@var{t}} | |
8925f36f AW |
15288 | |
15289 | @end table | |
15290 | ||
15291 | A texture function acts on the fragment to be textured using the texture | |
15292 | image value that applies to the fragment (see @code{glTexParameter}) and | |
15293 | produces an RGBA color for that fragment. The following table shows how | |
15294 | the RGBA color is produced for each of the first five texture functions | |
3c9b6116 AW |
15295 | that can be chosen. @r{@var{C}} is a triple of color values (RGB) and |
15296 | @r{@var{A}} is the associated alpha value. RGBA values extracted from a | |
15297 | texture image are in the range [0,1]. The subscript @r{@var{p}} refers | |
15298 | to the color computed from the previous texture stage (or the incoming | |
15299 | fragment if processing texture stage 0), the subscript @r{@var{s}} to | |
15300 | the texture source color, the subscript @r{@var{c}} to the texture | |
15301 | environment color, and the subscript @r{@var{v}} indicates a value | |
15302 | produced by the texture function. | |
8925f36f AW |
15303 | |
15304 | ||
15305 | ||
15306 | @table @asis | |
15307 | @item | |
15308 | Texture Base Internal Format | |
15309 | @code{Value}, @code{GL_REPLACE} Function , @code{GL_MODULATE} Function , | |
15310 | @code{GL_DECAL} Function , @code{GL_BLEND} Function , @code{GL_ADD} | |
15311 | Function | |
15312 | ||
15313 | @item @code{GL_ALPHA} | |
3c9b6116 AW |
15314 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{p}}, @r{@var{C}_@var{p}}, |
15315 | undefined , @r{@var{C}_@var{p}}, @r{@var{C}_@var{p}} | |
8925f36f AW |
15316 | |
15317 | @item | |
3c9b6116 AW |
15318 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}}, |
15319 | @r{@var{A}_@var{p}@var{A}_@var{s}}, , | |
15320 | @r{@var{A}_@var{v}=@var{A}_@var{p}@var{A}_@var{s}}, | |
15321 | @r{@var{A}_@var{p}@var{A}_@var{s}} | |
8925f36f AW |
15322 | |
15323 | @item @code{GL_LUMINANCE} | |
3c9b6116 AW |
15324 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
15325 | @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined , | |
15326 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
15327 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
15328 | |
15329 | @item | |
15330 | (or 1) | |
3c9b6116 AW |
15331 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, , |
15332 | @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}} | |
8925f36f AW |
15333 | |
15334 | @item @code{GL_LUMINANCE_ALPHA} | |
3c9b6116 AW |
15335 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
15336 | @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined , | |
15337 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
15338 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
15339 | |
15340 | @item | |
15341 | (or 2) | |
3c9b6116 AW |
15342 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}}, |
15343 | @r{@var{A}_@var{p}@var{A}_@var{s}}, , | |
15344 | @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}@var{A}_@var{s}} | |
8925f36f AW |
15345 | |
15346 | @item @code{GL_INTENSITY} | |
3c9b6116 AW |
15347 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
15348 | @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined , | |
15349 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
15350 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
15351 | |
15352 | @item | |
3c9b6116 AW |
15353 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}}, |
15354 | @r{@var{A}_@var{p}@var{A}_@var{s}}, , | |
15355 | @r{@var{A}_@var{p}(1-@var{A}_@var{s},)+@var{A}_@var{c}@var{A}_@var{s}}, | |
15356 | @r{@var{A}_@var{p}+@var{A}_@var{s}} | |
8925f36f AW |
15357 | |
15358 | @item @code{GL_RGB} | |
3c9b6116 AW |
15359 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
15360 | @r{@var{C}_@var{p}@var{C}_@var{s}}, @r{@var{C}_@var{s}}, | |
15361 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
15362 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
15363 | |
15364 | @item | |
15365 | (or 3) | |
3c9b6116 AW |
15366 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, |
15367 | @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}} | |
8925f36f AW |
15368 | |
15369 | @item @code{GL_RGBA} | |
3c9b6116 AW |
15370 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
15371 | @r{@var{C}_@var{p}@var{C}_@var{s}}, | |
15372 | @r{@var{C}_@var{p}(1-@var{A}_@var{s},)+@var{C}_@var{s}@var{A}_@var{s}}, | |
15373 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
15374 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
15375 | |
15376 | @item | |
15377 | (or 4) | |
3c9b6116 AW |
15378 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}}, |
15379 | @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}}, | |
15380 | @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}@var{A}_@var{s}} | |
8925f36f AW |
15381 | |
15382 | @end table | |
15383 | ||
15384 | If @var{pname} is @code{GL_TEXTURE_ENV_MODE}, and @var{params} is | |
15385 | @code{GL_COMBINE}, the form of the texture function depends on the | |
15386 | values of @code{GL_COMBINE_RGB} and @code{GL_COMBINE_ALPHA}. | |
15387 | ||
15388 | The following describes how the texture sources, as specified by | |
15389 | @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, @code{GL_SRC2_RGB}, | |
15390 | @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, and @code{GL_SRC2_ALPHA}, | |
15391 | are combined to produce a final texture color. In the following tables, | |
3c9b6116 AW |
15392 | @code{GL_SRC0_c} is represented by @r{@var{Arg0}}, @code{GL_SRC1_c} is |
15393 | represented by @r{@var{Arg1}}, and @code{GL_SRC2_c} is represented by | |
15394 | @r{@var{Arg2}}. | |
8925f36f AW |
15395 | |
15396 | @code{GL_COMBINE_RGB} accepts any of @code{GL_REPLACE}, | |
15397 | @code{GL_MODULATE}, @code{GL_ADD}, @code{GL_ADD_SIGNED}, | |
15398 | @code{GL_INTERPOLATE}, @code{GL_SUBTRACT}, @code{GL_DOT3_RGB}, or | |
15399 | @code{GL_DOT3_RGBA}. | |
15400 | ||
15401 | ||
15402 | ||
15403 | @table @asis | |
15404 | @item @strong{@code{GL_COMBINE_RGB}} | |
15405 | @strong{Texture Function} | |
15406 | ||
15407 | @item @code{GL_REPLACE} | |
3c9b6116 | 15408 | @r{@var{Arg0}} |
8925f36f AW |
15409 | |
15410 | @item @code{GL_MODULATE} | |
3c9b6116 | 15411 | @r{@var{Arg0}×@var{Arg1}} |
8925f36f AW |
15412 | |
15413 | @item @code{GL_ADD} | |
3c9b6116 | 15414 | @r{@var{Arg0}+@var{Arg1}} |
8925f36f AW |
15415 | |
15416 | @item @code{GL_ADD_SIGNED} | |
3c9b6116 | 15417 | @r{@var{Arg0}+@var{Arg1}-0.5} |
8925f36f AW |
15418 | |
15419 | @item @code{GL_INTERPOLATE} | |
3c9b6116 | 15420 | @r{@var{Arg0}×@var{Arg2}+@var{Arg1}×(1-@var{Arg2},)} |
8925f36f AW |
15421 | |
15422 | @item @code{GL_SUBTRACT} | |
3c9b6116 | 15423 | @r{@var{Arg0}-@var{Arg1}} |
8925f36f AW |
15424 | |
15425 | @item @code{GL_DOT3_RGB} | |
15426 | or @code{GL_DOT3_RGBA} | |
3c9b6116 | 15427 | @r{4×(((@var{Arg0}_@var{r},-0.5,)×(@var{Arg1}_@var{r},-0.5,),)+((@var{Arg0}_@var{g},-0.5,)×(@var{Arg1}_@var{g},-0.5,),)+((@var{Arg0}_@var{b},-0.5,)×(@var{Arg1}_@var{b},-0.5,),),)} |
8925f36f AW |
15428 | |
15429 | @end table | |
15430 | ||
15431 | The scalar results for @code{GL_DOT3_RGB} and @code{GL_DOT3_RGBA} are | |
15432 | placed into each of the 3 (RGB) or 4 (RGBA) components on output. | |
15433 | ||
15434 | Likewise, @code{GL_COMBINE_ALPHA} accepts any of @code{GL_REPLACE}, | |
15435 | @code{GL_MODULATE}, @code{GL_ADD}, @code{GL_ADD_SIGNED}, | |
15436 | @code{GL_INTERPOLATE}, or @code{GL_SUBTRACT}. The following table | |
15437 | describes how alpha values are combined: | |
15438 | ||
15439 | ||
15440 | ||
15441 | @table @asis | |
15442 | @item @strong{@code{GL_COMBINE_ALPHA}} | |
15443 | @strong{Texture Function} | |
15444 | ||
15445 | @item @code{GL_REPLACE} | |
3c9b6116 | 15446 | @r{@var{Arg0}} |
8925f36f AW |
15447 | |
15448 | @item @code{GL_MODULATE} | |
3c9b6116 | 15449 | @r{@var{Arg0}×@var{Arg1}} |
8925f36f AW |
15450 | |
15451 | @item @code{GL_ADD} | |
3c9b6116 | 15452 | @r{@var{Arg0}+@var{Arg1}} |
8925f36f AW |
15453 | |
15454 | @item @code{GL_ADD_SIGNED} | |
3c9b6116 | 15455 | @r{@var{Arg0}+@var{Arg1}-0.5} |
8925f36f AW |
15456 | |
15457 | @item @code{GL_INTERPOLATE} | |
3c9b6116 | 15458 | @r{@var{Arg0}×@var{Arg2}+@var{Arg1}×(1-@var{Arg2},)} |
8925f36f AW |
15459 | |
15460 | @item @code{GL_SUBTRACT} | |
3c9b6116 | 15461 | @r{@var{Arg0}-@var{Arg1}} |
8925f36f AW |
15462 | |
15463 | @end table | |
15464 | ||
3c9b6116 AW |
15465 | In the following tables, the value @r{@var{C}_@var{s}} represents the |
15466 | color sampled from the currently bound texture, @r{@var{C}_@var{c}} | |
15467 | represents the constant texture-environment color, @r{@var{C}_@var{f}} | |
15468 | represents the primary color of the incoming fragment, and | |
15469 | @r{@var{C}_@var{p}} represents the color computed from the previous | |
15470 | texture stage or @r{@var{C}_@var{f}} if processing texture stage 0. | |
15471 | Likewise, @r{@var{A}_@var{s}}, @r{@var{A}_@var{c}}, @r{@var{A}_@var{f}}, | |
15472 | and @r{@var{A}_@var{p}} represent the respective alpha values. | |
8925f36f | 15473 | |
3c9b6116 AW |
15474 | The following table describes the values assigned to @r{@var{Arg0}}, |
15475 | @r{@var{Arg1}}, and @r{@var{Arg2}} based upon the RGB sources and | |
8925f36f AW |
15476 | operands: |
15477 | ||
15478 | ||
15479 | ||
15480 | @table @asis | |
15481 | @item @strong{@code{GL_SRCn_RGB}} | |
15482 | @strong{@code{GL_OPERANDn_RGB}}, @strong{Argument Value} | |
15483 | ||
15484 | @item @code{GL_TEXTURE} | |
3c9b6116 | 15485 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{s},} |
8925f36f AW |
15486 | |
15487 | @item | |
3c9b6116 | 15488 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{s},} |
8925f36f AW |
15489 | |
15490 | @item | |
3c9b6116 | 15491 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},} |
8925f36f AW |
15492 | |
15493 | @item | |
3c9b6116 | 15494 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},} |
8925f36f AW |
15495 | |
15496 | @item @code{GL_TEXTUREn} | |
3c9b6116 | 15497 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{s},} |
8925f36f AW |
15498 | |
15499 | @item | |
3c9b6116 | 15500 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{s},} |
8925f36f AW |
15501 | |
15502 | @item | |
3c9b6116 | 15503 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},} |
8925f36f AW |
15504 | |
15505 | @item | |
3c9b6116 | 15506 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},} |
8925f36f AW |
15507 | |
15508 | @item @code{GL_CONSTANT} | |
3c9b6116 | 15509 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{c},} |
8925f36f AW |
15510 | |
15511 | @item | |
3c9b6116 | 15512 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{c},} |
8925f36f AW |
15513 | |
15514 | @item | |
3c9b6116 | 15515 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{c},} |
8925f36f AW |
15516 | |
15517 | @item | |
3c9b6116 | 15518 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{c},} |
8925f36f AW |
15519 | |
15520 | @item @code{GL_PRIMARY_COLOR} | |
3c9b6116 | 15521 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{f},} |
8925f36f AW |
15522 | |
15523 | @item | |
3c9b6116 | 15524 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{f},} |
8925f36f AW |
15525 | |
15526 | @item | |
3c9b6116 | 15527 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{f},} |
8925f36f AW |
15528 | |
15529 | @item | |
3c9b6116 | 15530 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{f},} |
8925f36f AW |
15531 | |
15532 | @item @code{GL_PREVIOUS} | |
3c9b6116 | 15533 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{p},} |
8925f36f AW |
15534 | |
15535 | @item | |
3c9b6116 | 15536 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{p},} |
8925f36f AW |
15537 | |
15538 | @item | |
3c9b6116 | 15539 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{p},} |
8925f36f AW |
15540 | |
15541 | @item | |
3c9b6116 | 15542 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{p},} |
8925f36f AW |
15543 | |
15544 | @end table | |
15545 | ||
3c9b6116 AW |
15546 | For @code{GL_TEXTUREn} sources, @r{@var{C}_@var{s}} and |
15547 | @r{@var{A}_@var{s}} represent the color and alpha, respectively, | |
15548 | produced from texture stage @r{@var{n}}. | |
8925f36f | 15549 | |
3c9b6116 AW |
15550 | The follow table describes the values assigned to @r{@var{Arg0}}, |
15551 | @r{@var{Arg1}}, and @r{@var{Arg2}} based upon the alpha sources and | |
15552 | operands: | |
8925f36f AW |
15553 | |
15554 | ||
15555 | ||
15556 | @table @asis | |
15557 | @item @strong{@code{GL_SRCn_ALPHA}} | |
15558 | @strong{@code{GL_OPERANDn_ALPHA}}, @strong{Argument Value} | |
15559 | ||
15560 | @item @code{GL_TEXTURE} | |
3c9b6116 | 15561 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},} |
8925f36f AW |
15562 | |
15563 | @item | |
3c9b6116 | 15564 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},} |
8925f36f AW |
15565 | |
15566 | @item @code{GL_TEXTUREn} | |
3c9b6116 | 15567 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},} |
8925f36f AW |
15568 | |
15569 | @item | |
3c9b6116 | 15570 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},} |
8925f36f AW |
15571 | |
15572 | @item @code{GL_CONSTANT} | |
3c9b6116 | 15573 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{c},} |
8925f36f AW |
15574 | |
15575 | @item | |
3c9b6116 | 15576 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{c},} |
8925f36f AW |
15577 | |
15578 | @item @code{GL_PRIMARY_COLOR} | |
3c9b6116 | 15579 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{f},} |
8925f36f AW |
15580 | |
15581 | @item | |
3c9b6116 | 15582 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{f},} |
8925f36f AW |
15583 | |
15584 | @item @code{GL_PREVIOUS} | |
3c9b6116 | 15585 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{p},} |
8925f36f AW |
15586 | |
15587 | @item | |
3c9b6116 | 15588 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{p},} |
8925f36f AW |
15589 | |
15590 | @end table | |
15591 | ||
15592 | The RGB and alpha results of the texture function are multipled by the | |
15593 | values of @code{GL_RGB_SCALE} and @code{GL_ALPHA_SCALE}, respectively, | |
3c9b6116 | 15594 | and clamped to the range @r{[0,1]}. |
8925f36f AW |
15595 | |
15596 | If @var{pname} is @code{GL_TEXTURE_ENV_COLOR}, @var{params} is a pointer | |
15597 | to an array that holds an RGBA color consisting of four values. Integer | |
15598 | color components are interpreted linearly such that the most positive | |
15599 | integer maps to 1.0, and the most negative integer maps to -1.0. The | |
15600 | values are clamped to the range [0,1] when they are specified. | |
3c9b6116 | 15601 | @r{@var{C}_@var{c}} takes these four values. |
8925f36f AW |
15602 | |
15603 | If @var{pname} is @code{GL_TEXTURE_LOD_BIAS}, the value specified is | |
15604 | added to the texture level-of-detail parameter, that selects which | |
15605 | mipmap, or mipmaps depending upon the selected | |
15606 | @code{GL_TEXTURE_MIN_FILTER}, will be sampled. | |
15607 | ||
15608 | @code{GL_TEXTURE_ENV_MODE} defaults to @code{GL_MODULATE} and | |
15609 | @code{GL_TEXTURE_ENV_COLOR} defaults to (0, 0, 0, 0). | |
15610 | ||
15611 | If @var{target} is @code{GL_POINT_SPRITE} and @var{pname} is | |
15612 | @code{GL_COORD_REPLACE}, the boolean value specified is used to either | |
15613 | enable or disable point sprite texture coordinate replacement. The | |
15614 | default value is @code{GL_FALSE}. | |
15615 | ||
8925f36f AW |
15616 | @code{GL_INVALID_ENUM} is generated when @var{target} or @var{pname} is |
15617 | not one of the accepted defined values, or when @var{params} should have | |
15618 | a defined constant value (based on the value of @var{pname}) and does | |
15619 | not. | |
15620 | ||
15621 | @code{GL_INVALID_VALUE} is generated if the @var{params} value for | |
15622 | @code{GL_RGB_SCALE} or @code{GL_ALPHA_SCALE} are not one of 1.0, 2.0, or | |
15623 | 4.0. | |
15624 | ||
15625 | @code{GL_INVALID_OPERATION} is generated if @code{glTexEnv} is executed | |
15626 | between the execution of @code{glBegin} and the corresponding execution | |
15627 | of @code{glEnd}. | |
15628 | ||
bb894c9d | 15629 | @end deftypefun |
8925f36f | 15630 | |
bb894c9d AW |
15631 | @deftypefun void glTexGeni coord pname param |
15632 | @deftypefunx void glTexGend coord pname param | |
3c9b6116 AW |
15633 | Control the generation of texture coordinates. |
15634 | ||
8925f36f AW |
15635 | @table @asis |
15636 | @item @var{coord} | |
15637 | Specifies a texture coordinate. Must be one of @code{GL_S}, @code{GL_T}, | |
15638 | @code{GL_R}, or @code{GL_Q}. | |
15639 | ||
15640 | @item @var{pname} | |
15641 | Specifies the symbolic name of the texture-coordinate generation | |
15642 | function. Must be @code{GL_TEXTURE_GEN_MODE}. | |
15643 | ||
15644 | @item @var{param} | |
15645 | Specifies a single-valued texture generation parameter, one of | |
15646 | @code{GL_OBJECT_LINEAR}, @code{GL_EYE_LINEAR}, @code{GL_SPHERE_MAP}, | |
15647 | @code{GL_NORMAL_MAP}, or @code{GL_REFLECTION_MAP}. | |
15648 | ||
15649 | @end table | |
15650 | ||
8925f36f AW |
15651 | @code{glTexGen} selects a texture-coordinate generation function or |
15652 | supplies coefficients for one of the functions. @var{coord} names one of | |
15653 | the (@var{s}, @var{t}, @var{r}, @var{q}) texture coordinates; it must be | |
15654 | one of the symbols @code{GL_S}, @code{GL_T}, @code{GL_R}, or | |
15655 | @code{GL_Q}. @var{pname} must be one of three symbolic constants: | |
15656 | @code{GL_TEXTURE_GEN_MODE}, @code{GL_OBJECT_PLANE}, or | |
15657 | @code{GL_EYE_PLANE}. If @var{pname} is @code{GL_TEXTURE_GEN_MODE}, then | |
15658 | @var{params} chooses a mode, one of @code{GL_OBJECT_LINEAR}, | |
15659 | @code{GL_EYE_LINEAR}, @code{GL_SPHERE_MAP}, @code{GL_NORMAL_MAP}, or | |
15660 | @code{GL_REFLECTION_MAP}. If @var{pname} is either | |
15661 | @code{GL_OBJECT_PLANE} or @code{GL_EYE_PLANE}, @var{params} contains | |
15662 | coefficients for the corresponding texture generation function. | |
15663 | ||
15664 | If the texture generation function is @code{GL_OBJECT_LINEAR}, the | |
15665 | function | |
15666 | ||
3c9b6116 AW |
15667 | @r{@var{g}=@var{p}_1×@var{x}_@var{o}+@var{p}_2×@var{y}_@var{o}+@var{p}_3×@var{z}_@var{o}+@var{p}_4×@var{w}_@var{o}} |
15668 | ||
15669 | is used, where @r{@var{g}} is the value computed for the coordinate | |
15670 | named in @var{coord}, @r{@var{p}_1}, @r{@var{p}_2}, @r{@var{p}_3}, and | |
15671 | @r{@var{p}_4} are the four values supplied in @var{params}, and | |
15672 | @r{@var{x}_@var{o}}, @r{@var{y}_@var{o}}, @r{@var{z}_@var{o}}, and | |
15673 | @r{@var{w}_@var{o}} are the object coordinates of the vertex. This | |
15674 | function can be used, for example, to texture-map terrain using sea | |
15675 | level as a reference plane (defined by @r{@var{p}_1}, @r{@var{p}_2}, | |
15676 | @r{@var{p}_3}, and @r{@var{p}_4}). The altitude of a terrain vertex is | |
15677 | computed by the @code{GL_OBJECT_LINEAR} coordinate generation function | |
15678 | as its distance from sea level; that altitude can then be used to index | |
15679 | the texture image to map white snow onto peaks and green grass onto | |
15680 | foothills. | |
8925f36f AW |
15681 | |
15682 | If the texture generation function is @code{GL_EYE_LINEAR}, the function | |
15683 | ||
3c9b6116 | 15684 | @r{@var{g}=@var{p}_1,^″×@var{x}_@var{e}+@var{p}_2,^″×@var{y}_@var{e}+@var{p}_3,^″×@var{z}_@var{e}+@var{p}_4,^″×@var{w}_@var{e}} |
8925f36f AW |
15685 | |
15686 | is used, where | |
15687 | ||
3c9b6116 | 15688 | @r{(@var{p}_1,^″@var{p}_2,^″@var{p}_3,^″@var{p}_4,^″,)=(@var{p}_1@var{p}_2@var{p}_3@var{p}_4,)@var{M}^-1} |
8925f36f | 15689 | |
3c9b6116 AW |
15690 | and @r{@var{x}_@var{e}}, @r{@var{y}_@var{e}}, @r{@var{z}_@var{e}}, and |
15691 | @r{@var{w}_@var{e}} are the eye coordinates of the vertex, | |
15692 | @r{@var{p}_1}, @r{@var{p}_2}, @r{@var{p}_3}, and @r{@var{p}_4} are the | |
15693 | values supplied in @var{params}, and @r{@var{M}} is the modelview matrix | |
15694 | when @code{glTexGen} is invoked. If @r{@var{M}} is poorly conditioned or | |
8925f36f AW |
15695 | singular, texture coordinates generated by the resulting function may be |
15696 | inaccurate or undefined. | |
15697 | ||
15698 | Note that the values in @var{params} define a reference plane in eye | |
15699 | coordinates. The modelview matrix that is applied to them may not be the | |
15700 | same one in effect when the polygon vertices are transformed. This | |
15701 | function establishes a field of texture coordinates that can produce | |
15702 | dynamic contour lines on moving objects. | |
15703 | ||
15704 | If the texture generation function is @code{GL_SPHERE_MAP} and | |
3c9b6116 AW |
15705 | @var{coord} is either @code{GL_S} or @code{GL_T}, @r{@var{s}} and |
15706 | @r{@var{t}} texture coordinates are generated as follows. Let @var{u} be | |
15707 | the unit vector pointing from the origin to the polygon vertex (in eye | |
15708 | coordinates). Let @var{n} sup prime be the current normal, after | |
8925f36f AW |
15709 | transformation to eye coordinates. Let |
15710 | ||
3c9b6116 | 15711 | @r{@var{f}=(@var{f}_@var{x}@var{f}_@var{y}@var{f}_@var{z},)^@var{T}} |
8925f36f AW |
15712 | be the reflection vector such that |
15713 | ||
3c9b6116 | 15714 | @r{@var{f}=@var{u}-2@var{n}^″@var{n}^″,^@var{T}@var{u}} |
8925f36f AW |
15715 | |
15716 | Finally, let | |
3c9b6116 AW |
15717 | @r{@var{m}=2√(@var{f}_@var{x},^2+@var{f}_@var{y},^2+(@var{f}_@var{z}+1,)^2,)}. |
15718 | Then the values assigned to the @r{@var{s}} and @r{@var{t}} texture | |
15719 | coordinates are | |
8925f36f | 15720 | |
3c9b6116 | 15721 | @r{@var{s}=@var{f}_@var{x}/@var{m}+1/2} |
8925f36f | 15722 | |
3c9b6116 | 15723 | @r{@var{t}=@var{f}_@var{y}/@var{m}+1/2} |
8925f36f AW |
15724 | |
15725 | To enable or disable a texture-coordinate generation function, call | |
15726 | @code{glEnable} or @code{glDisable} with one of the symbolic | |
15727 | texture-coordinate names (@code{GL_TEXTURE_GEN_S}, | |
15728 | @code{GL_TEXTURE_GEN_T}, @code{GL_TEXTURE_GEN_R}, or | |
15729 | @code{GL_TEXTURE_GEN_Q}) as the argument. When enabled, the specified | |
15730 | texture coordinate is computed according to the generating function | |
15731 | associated with that coordinate. When disabled, subsequent vertices take | |
15732 | the specified texture coordinate from the current set of texture | |
15733 | coordinates. Initially, all texture generation functions are set to | |
3c9b6116 AW |
15734 | @code{GL_EYE_LINEAR} and are disabled. Both @r{@var{s}} plane equations |
15735 | are (1, 0, 0, 0), both @r{@var{t}} plane equations are (0, 1, 0, 0), and | |
15736 | all @r{@var{r}} and @r{@var{q}} plane equations are (0, 0, 0, 0). | |
8925f36f AW |
15737 | |
15738 | When the @code{ARB_multitexture} extension is supported, @code{glTexGen} | |
15739 | sets the texture generation parameters for the currently active texture | |
15740 | unit, selected with @code{glActiveTexture}. | |
15741 | ||
8925f36f AW |
15742 | @code{GL_INVALID_ENUM} is generated when @var{coord} or @var{pname} is |
15743 | not an accepted defined value, or when @var{pname} is | |
15744 | @code{GL_TEXTURE_GEN_MODE} and @var{params} is not an accepted defined | |
15745 | value. | |
15746 | ||
15747 | @code{GL_INVALID_ENUM} is generated when @var{pname} is | |
15748 | @code{GL_TEXTURE_GEN_MODE}, @var{params} is @code{GL_SPHERE_MAP}, and | |
15749 | @var{coord} is either @code{GL_R} or @code{GL_Q}. | |
15750 | ||
15751 | @code{GL_INVALID_OPERATION} is generated if @code{glTexGen} is executed | |
15752 | between the execution of @code{glBegin} and the corresponding execution | |
15753 | of @code{glEnd}. | |
15754 | ||
bb894c9d | 15755 | @end deftypefun |
8925f36f | 15756 | |
bb894c9d | 15757 | @deftypefun void glTexImage1D target level internalFormat width border format type data |
3c9b6116 AW |
15758 | Specify a one-dimensional texture image. |
15759 | ||
8925f36f AW |
15760 | @table @asis |
15761 | @item @var{target} | |
15762 | Specifies the target texture. Must be @code{GL_TEXTURE_1D} or | |
15763 | @code{GL_PROXY_TEXTURE_1D}. | |
15764 | ||
15765 | @item @var{level} | |
15766 | Specifies the level-of-detail number. Level 0 is the base image level. | |
15767 | Level @var{n} is the @var{n}th mipmap reduction image. | |
15768 | ||
15769 | @item @var{internalFormat} | |
15770 | Specifies the number of color components in the texture. Must be 1, 2, | |
15771 | 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA}, | |
15772 | @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, | |
15773 | @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA}, | |
15774 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
15775 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
15776 | @code{GL_COMPRESSED_RGBA}, @code{GL_DEPTH_COMPONENT}, | |
15777 | @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, | |
15778 | @code{GL_DEPTH_COMPONENT32}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
15779 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
15780 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
15781 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
15782 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
15783 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY}, | |
15784 | @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12}, | |
15785 | @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
15786 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
15787 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
15788 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
15789 | @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE}, | |
15790 | @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
15791 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
15792 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
15793 | ||
15794 | @item @var{width} | |
15795 | Specifies the width of the texture image including the border if any. If | |
15796 | the GL version does not support non-power-of-two sizes, this value must | |
3c9b6116 AW |
15797 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
15798 | implementations support texture images that are at least 64 texels wide. | |
15799 | The height of the 1D texture image is 1. | |
8925f36f AW |
15800 | |
15801 | @item @var{border} | |
15802 | Specifies the width of the border. Must be either 0 or 1. | |
15803 | ||
15804 | @item @var{format} | |
15805 | Specifies the format of the pixel data. The following symbolic values | |
15806 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, | |
15807 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
15808 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
15809 | @code{GL_LUMINANCE_ALPHA}. | |
15810 | ||
15811 | @item @var{type} | |
15812 | Specifies the data type of the pixel data. The following symbolic values | |
15813 | are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
15814 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
15815 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
15816 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
15817 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
15818 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
15819 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
15820 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
15821 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
15822 | ||
15823 | @item @var{data} | |
15824 | Specifies a pointer to the image data in memory. | |
15825 | ||
15826 | @end table | |
15827 | ||
8925f36f AW |
15828 | Texturing maps a portion of a specified texture image onto each |
15829 | graphical primitive for which texturing is enabled. To enable and | |
15830 | disable one-dimensional texturing, call @code{glEnable} and | |
15831 | @code{glDisable} with argument @code{GL_TEXTURE_1D}. | |
15832 | ||
15833 | Texture images are defined with @code{glTexImage1D}. The arguments | |
15834 | describe the parameters of the texture image, such as width, width of | |
15835 | the border, level-of-detail number (see @code{glTexParameter}), and the | |
15836 | internal resolution and format used to store the image. The last three | |
15837 | arguments describe how the image is represented in memory; they are | |
15838 | identical to the pixel formats used for @code{glDrawPixels}. | |
15839 | ||
15840 | If @var{target} is @code{GL_PROXY_TEXTURE_1D}, no data is read from | |
15841 | @var{data}, but all of the texture image state is recalculated, checked | |
15842 | for consistency, and checked against the implementation's capabilities. | |
15843 | If the implementation cannot handle a texture of the requested texture | |
15844 | size, it sets all of the image state to 0, but does not generate an | |
15845 | error (see @code{glGetError}). To query for an entire mipmap array, use | |
15846 | an image array level greater than or equal to 1. | |
15847 | ||
15848 | If @var{target} is @code{GL_TEXTURE_1D}, data is read from @var{data} as | |
15849 | a sequence of signed or unsigned bytes, shorts, or longs, or | |
15850 | single-precision floating-point values, depending on @var{type}. These | |
15851 | values are grouped into sets of one, two, three, or four values, | |
15852 | depending on @var{format}, to form elements. If @var{type} is | |
15853 | @code{GL_BITMAP}, the data is considered as a string of unsigned bytes | |
15854 | (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is | |
15855 | treated as eight 1-bit elements, with bit ordering determined by | |
15856 | @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}). | |
15857 | ||
15858 | If a non-zero named buffer object is bound to the | |
15859 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
15860 | texture image is specified, @var{data} is treated as a byte offset into | |
15861 | the buffer object's data store. | |
15862 | ||
15863 | The first element corresponds to the left end of the texture array. | |
15864 | Subsequent elements progress left-to-right through the remaining texels | |
15865 | in the texture array. The final element corresponds to the right end of | |
15866 | the texture array. | |
15867 | ||
15868 | @var{format} determines the composition of each element in @var{data}. | |
15869 | It can assume one of these symbolic values: | |
15870 | ||
15871 | @table @asis | |
15872 | @item @code{GL_COLOR_INDEX} | |
15873 | Each element is a single value, a color index. The GL converts it to | |
15874 | fixed point (with an unspecified number of zero bits to the right of the | |
15875 | binary point), shifted left or right depending on the value and sign of | |
15876 | @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see | |
15877 | @code{glPixelTransfer}). The resulting index is converted to a set of | |
15878 | color components using the @code{GL_PIXEL_MAP_I_TO_R}, | |
15879 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
15880 | @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1]. | |
15881 | ||
15882 | @item @code{GL_RED} | |
15883 | Each element is a single red component. The GL converts it to floating | |
15884 | point and assembles it into an RGBA element by attaching 0 for green and | |
15885 | blue, and 1 for alpha. Each component is then multiplied by the signed | |
15886 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
15887 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
15888 | @code{glPixelTransfer}). | |
15889 | ||
15890 | @item @code{GL_GREEN} | |
15891 | Each element is a single green component. The GL converts it to floating | |
15892 | point and assembles it into an RGBA element by attaching 0 for red and | |
15893 | blue, and 1 for alpha. Each component is then multiplied by the signed | |
15894 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
15895 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
15896 | @code{glPixelTransfer}). | |
15897 | ||
15898 | @item @code{GL_BLUE} | |
15899 | Each element is a single blue component. The GL converts it to floating | |
15900 | point and assembles it into an RGBA element by attaching 0 for red and | |
15901 | green, and 1 for alpha. Each component is then multiplied by the signed | |
15902 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
15903 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
15904 | @code{glPixelTransfer}). | |
15905 | ||
15906 | @item @code{GL_ALPHA} | |
15907 | Each element is a single alpha component. The GL converts it to floating | |
15908 | point and assembles it into an RGBA element by attaching 0 for red, | |
15909 | green, and blue. Each component is then multiplied by the signed scale | |
15910 | factor @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
15911 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
15912 | ||
15913 | @item @code{GL_INTENSITY} | |
15914 | Each element is a single intensity value. The GL converts it to floating | |
15915 | point, then assembles it into an RGBA element by replicating the | |
15916 | intensity value three times for red, green, blue, and alpha. Each | |
15917 | component is then multiplied by the signed scale factor | |
15918 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
15919 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
15920 | ||
15921 | @item @code{GL_RGB} | |
15922 | @item @code{GL_BGR} | |
15923 | Each element is an RGB triple. The GL converts it to floating point and | |
15924 | assembles it into an RGBA element by attaching 1 for alpha. Each | |
15925 | component is then multiplied by the signed scale factor | |
15926 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
15927 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
15928 | ||
15929 | @item @code{GL_RGBA} | |
15930 | @item @code{GL_BGRA} | |
15931 | Each element contains all four components. Each component is multiplied | |
15932 | by the signed scale factor @code{GL_c_SCALE}, added to the signed bias | |
15933 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
15934 | @code{glPixelTransfer}). | |
15935 | ||
15936 | @item @code{GL_LUMINANCE} | |
15937 | Each element is a single luminance value. The GL converts it to floating | |
15938 | point, then assembles it into an RGBA element by replicating the | |
15939 | luminance value three times for red, green, and blue and attaching 1 for | |
15940 | alpha. Each component is then multiplied by the signed scale factor | |
15941 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
15942 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
15943 | ||
15944 | @item @code{GL_LUMINANCE_ALPHA} | |
15945 | Each element is a luminance/alpha pair. The GL converts it to floating | |
15946 | point, then assembles it into an RGBA element by replicating the | |
15947 | luminance value three times for red, green, and blue. Each component is | |
15948 | then multiplied by the signed scale factor @code{GL_c_SCALE}, added to | |
15949 | the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
15950 | @code{glPixelTransfer}). | |
15951 | ||
15952 | @item @code{GL_DEPTH_COMPONENT} | |
15953 | Each element is a single depth value. The GL converts it to floating | |
15954 | point, multiplies by the signed scale factor @code{GL_DEPTH_SCALE}, adds | |
15955 | the signed bias @code{GL_DEPTH_BIAS}, and clamps to the range [0,1] (see | |
15956 | @code{glPixelTransfer}). | |
15957 | ||
15958 | @end table | |
15959 | ||
15960 | Refer to the @code{glDrawPixels} reference page for a description of the | |
15961 | acceptable values for the @var{type} parameter. | |
15962 | ||
15963 | If an application wants to store the texture at a certain resolution or | |
15964 | in a certain format, it can request the resolution and format with | |
15965 | @var{internalFormat}. The GL will choose an internal representation that | |
15966 | closely approximates that requested by @var{internalFormat}, but it may | |
15967 | not match exactly. (The representations specified by | |
15968 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and | |
15969 | @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 may | |
15970 | also be used to specify the above representations.) | |
15971 | ||
15972 | If the @var{internalFormat} parameter is one of the generic compressed | |
15973 | formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
15974 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
15975 | @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will | |
15976 | replace the internal format with the symbolic constant for a specific | |
15977 | internal format and compress the texture before storage. If no | |
15978 | corresponding internal format is available, or the GL can not compress | |
15979 | that image for any reason, the internal format is instead replaced with | |
15980 | a corresponding base internal format. | |
15981 | ||
15982 | If the @var{internalFormat} parameter is @code{GL_SRGB}, | |
15983 | @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8}, | |
15984 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
15985 | or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red, | |
15986 | green, blue, or luminance components are encoded in the sRGB color | |
15987 | space. Any alpha component is left unchanged. The conversion from the | |
3c9b6116 AW |
15988 | sRGB encoded component @r{@var{c}_@var{s}} to a linear component |
15989 | @r{@var{c}_@var{l}} is: | |
8925f36f | 15990 | |
3c9b6116 AW |
15991 | @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045), |
15992 | ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)} | |
8925f36f | 15993 | |
3c9b6116 | 15994 | Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1]. |
8925f36f AW |
15995 | |
15996 | Use the @code{GL_PROXY_TEXTURE_1D} target to try out a resolution and | |
15997 | format. The implementation will update and recompute its best match for | |
15998 | the requested storage resolution and format. To then query this state, | |
15999 | call @code{glGetTexLevelParameter}. If the texture cannot be | |
16000 | accommodated, texture state is set to 0. | |
16001 | ||
16002 | A one-component texture image uses only the red component of the RGBA | |
16003 | color from @var{data}. A two-component image uses the R and A values. A | |
16004 | three-component image uses the R, G, and B values. A four-component | |
16005 | image uses all of the RGBA components. | |
16006 | ||
16007 | Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA textures | |
16008 | during texture filtering and application. Image-based shadowing can be | |
16009 | enabled by comparing texture r coordinates to depth texture values to | |
16010 | generate a boolean result. See @code{glTexParameter} for details on | |
16011 | texture comparison. | |
16012 | ||
8925f36f AW |
16013 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
16014 | @code{GL_TEXTURE_1D} or @code{GL_PROXY_TEXTURE_1D}. | |
16015 | ||
16016 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
16017 | format constant. Format constants other than @code{GL_STENCIL_INDEX} are | |
16018 | accepted. | |
16019 | ||
16020 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
16021 | constant. | |
16022 | ||
16023 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
16024 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
16025 | ||
16026 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
16027 | ||
16028 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
16029 | @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of |
16030 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
16031 | |
16032 | @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1, | |
16033 | 2, 3, 4, or one of the accepted resolution and format symbolic | |
16034 | constants. | |
16035 | ||
16036 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or | |
16037 | greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
16038 | ||
16039 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
16040 | not supported and the @var{width} cannot be represented as | |
3c9b6116 | 16041 | @r{2^@var{n}+2(@var{border},)} for some integer value of @var{n}. |
8925f36f AW |
16042 | |
16043 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
16044 | ||
16045 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
16046 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
16047 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
16048 | and @var{format} is not @code{GL_RGB}. | |
16049 | ||
16050 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
16051 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
16052 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
16053 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
16054 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
16055 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
16056 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
16057 | ||
16058 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
16059 | @code{GL_DEPTH_COMPONENT} and @var{internalFormat} is not | |
16060 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
16061 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}. | |
16062 | ||
16063 | @code{GL_INVALID_OPERATION} is generated if @var{internalFormat} is | |
16064 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
16065 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}, and | |
16066 | @var{format} is not @code{GL_DEPTH_COMPONENT}. | |
16067 | ||
16068 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
16069 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
16070 | object's data store is currently mapped. | |
16071 | ||
16072 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
16073 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
16074 | would be unpacked from the buffer object such that the memory reads | |
16075 | required would exceed the data store size. | |
16076 | ||
16077 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
16078 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
16079 | is not evenly divisible into the number of bytes needed to store in | |
16080 | memory a datum indicated by @var{type}. | |
16081 | ||
16082 | @code{GL_INVALID_OPERATION} is generated if @code{glTexImage1D} is | |
16083 | executed between the execution of @code{glBegin} and the corresponding | |
16084 | execution of @code{glEnd}. | |
16085 | ||
bb894c9d | 16086 | @end deftypefun |
8925f36f | 16087 | |
bb894c9d | 16088 | @deftypefun void glTexImage2D target level internalFormat width height border format type data |
3c9b6116 AW |
16089 | Specify a two-dimensional texture image. |
16090 | ||
8925f36f AW |
16091 | @table @asis |
16092 | @item @var{target} | |
16093 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, | |
16094 | @code{GL_PROXY_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
16095 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
16096 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
16097 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
16098 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, | |
16099 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or | |
16100 | @code{GL_PROXY_TEXTURE_CUBE_MAP}. | |
16101 | ||
16102 | @item @var{level} | |
16103 | Specifies the level-of-detail number. Level 0 is the base image level. | |
16104 | Level @var{n} is the @var{n}th mipmap reduction image. | |
16105 | ||
16106 | @item @var{internalFormat} | |
16107 | Specifies the number of color components in the texture. Must be 1, 2, | |
16108 | 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA}, | |
16109 | @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, | |
16110 | @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA}, | |
16111 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
16112 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
16113 | @code{GL_COMPRESSED_RGBA}, @code{GL_DEPTH_COMPONENT}, | |
16114 | @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, | |
16115 | @code{GL_DEPTH_COMPONENT32}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
16116 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
16117 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
16118 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
16119 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
16120 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY}, | |
16121 | @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12}, | |
16122 | @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
16123 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
16124 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
16125 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
16126 | @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE}, | |
16127 | @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
16128 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
16129 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
16130 | ||
16131 | @item @var{width} | |
16132 | Specifies the width of the texture image including the border if any. If | |
16133 | the GL version does not support non-power-of-two sizes, this value must | |
3c9b6116 AW |
16134 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
16135 | implementations support texture images that are at least 64 texels wide. | |
8925f36f AW |
16136 | |
16137 | @item @var{height} | |
16138 | Specifies the height of the texture image including the border if any. | |
16139 | If the GL version does not support non-power-of-two sizes, this value | |
3c9b6116 AW |
16140 | must be @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}. |
16141 | All implementations support texture images that are at least 64 texels | |
16142 | high. | |
8925f36f AW |
16143 | |
16144 | @item @var{border} | |
16145 | Specifies the width of the border. Must be either 0 or 1. | |
16146 | ||
16147 | @item @var{format} | |
16148 | Specifies the format of the pixel data. The following symbolic values | |
16149 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, | |
16150 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
16151 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
16152 | @code{GL_LUMINANCE_ALPHA}. | |
16153 | ||
16154 | @item @var{type} | |
16155 | Specifies the data type of the pixel data. The following symbolic values | |
16156 | are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
16157 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
16158 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
16159 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
16160 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
16161 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
16162 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
16163 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
16164 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
16165 | ||
16166 | @item @var{data} | |
16167 | Specifies a pointer to the image data in memory. | |
16168 | ||
16169 | @end table | |
16170 | ||
8925f36f AW |
16171 | Texturing maps a portion of a specified texture image onto each |
16172 | graphical primitive for which texturing is enabled. To enable and | |
16173 | disable two-dimensional texturing, call @code{glEnable} and | |
16174 | @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and | |
16175 | disable texturing using cube-mapped texture, call @code{glEnable} and | |
16176 | @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}. | |
16177 | ||
16178 | To define texture images, call @code{glTexImage2D}. The arguments | |
16179 | describe the parameters of the texture image, such as height, width, | |
16180 | width of the border, level-of-detail number (see @code{glTexParameter}), | |
16181 | and number of color components provided. The last three arguments | |
16182 | describe how the image is represented in memory; they are identical to | |
16183 | the pixel formats used for @code{glDrawPixels}. | |
16184 | ||
16185 | If @var{target} is @code{GL_PROXY_TEXTURE_2D} or | |
16186 | @code{GL_PROXY_TEXTURE_CUBE_MAP}, no data is read from @var{data}, but | |
16187 | all of the texture image state is recalculated, checked for consistency, | |
16188 | and checked against the implementation's capabilities. If the | |
16189 | implementation cannot handle a texture of the requested texture size, it | |
16190 | sets all of the image state to 0, but does not generate an error (see | |
16191 | @code{glGetError}). To query for an entire mipmap array, use an image | |
16192 | array level greater than or equal to 1. | |
16193 | ||
16194 | If @var{target} is @code{GL_TEXTURE_2D}, or one of the | |
16195 | @code{GL_TEXTURE_CUBE_MAP} targets, data is read from @var{data} as a | |
16196 | sequence of signed or unsigned bytes, shorts, or longs, or | |
16197 | single-precision floating-point values, depending on @var{type}. These | |
16198 | values are grouped into sets of one, two, three, or four values, | |
16199 | depending on @var{format}, to form elements. If @var{type} is | |
16200 | @code{GL_BITMAP}, the data is considered as a string of unsigned bytes | |
16201 | (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is | |
16202 | treated as eight 1-bit elements, with bit ordering determined by | |
16203 | @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}). | |
16204 | ||
16205 | If a non-zero named buffer object is bound to the | |
16206 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
16207 | texture image is specified, @var{data} is treated as a byte offset into | |
16208 | the buffer object's data store. | |
16209 | ||
16210 | The first element corresponds to the lower left corner of the texture | |
16211 | image. Subsequent elements progress left-to-right through the remaining | |
16212 | texels in the lowest row of the texture image, and then in successively | |
16213 | higher rows of the texture image. The final element corresponds to the | |
16214 | upper right corner of the texture image. | |
16215 | ||
16216 | @var{format} determines the composition of each element in @var{data}. | |
16217 | It can assume one of these symbolic values: | |
16218 | ||
16219 | @table @asis | |
16220 | @item @code{GL_COLOR_INDEX} | |
16221 | Each element is a single value, a color index. The GL converts it to | |
16222 | fixed point (with an unspecified number of zero bits to the right of the | |
16223 | binary point), shifted left or right depending on the value and sign of | |
16224 | @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see | |
16225 | @code{glPixelTransfer}). The resulting index is converted to a set of | |
16226 | color components using the @code{GL_PIXEL_MAP_I_TO_R}, | |
16227 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
16228 | @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1]. | |
16229 | ||
16230 | @item @code{GL_RED} | |
16231 | Each element is a single red component. The GL converts it to floating | |
16232 | point and assembles it into an RGBA element by attaching 0 for green and | |
16233 | blue, and 1 for alpha. Each component is then multiplied by the signed | |
16234 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
16235 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
16236 | @code{glPixelTransfer}). | |
16237 | ||
16238 | @item @code{GL_GREEN} | |
16239 | Each element is a single green component. The GL converts it to floating | |
16240 | point and assembles it into an RGBA element by attaching 0 for red and | |
16241 | blue, and 1 for alpha. Each component is then multiplied by the signed | |
16242 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
16243 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
16244 | @code{glPixelTransfer}). | |
16245 | ||
16246 | @item @code{GL_BLUE} | |
16247 | Each element is a single blue component. The GL converts it to floating | |
16248 | point and assembles it into an RGBA element by attaching 0 for red and | |
16249 | green, and 1 for alpha. Each component is then multiplied by the signed | |
16250 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
16251 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
16252 | @code{glPixelTransfer}). | |
16253 | ||
16254 | @item @code{GL_ALPHA} | |
16255 | Each element is a single alpha component. The GL converts it to floating | |
16256 | point and assembles it into an RGBA element by attaching 0 for red, | |
16257 | green, and blue. Each component is then multiplied by the signed scale | |
16258 | factor @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
16259 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
16260 | ||
16261 | @item @code{GL_INTENSITY} | |
16262 | Each element is a single intensity value. The GL converts it to floating | |
16263 | point, then assembles it into an RGBA element by replicating the | |
16264 | intensity value three times for red, green, blue, and alpha. Each | |
16265 | component is then multiplied by the signed scale factor | |
16266 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
16267 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
16268 | ||
16269 | @item @code{GL_RGB} | |
16270 | @item @code{GL_BGR} | |
16271 | Each element is an RGB triple. The GL converts it to floating point and | |
16272 | assembles it into an RGBA element by attaching 1 for alpha. Each | |
16273 | component is then multiplied by the signed scale factor | |
16274 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
16275 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
16276 | ||
16277 | @item @code{GL_RGBA} | |
16278 | @item @code{GL_BGRA} | |
16279 | Each element contains all four components. Each component is multiplied | |
16280 | by the signed scale factor @code{GL_c_SCALE}, added to the signed bias | |
16281 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
16282 | @code{glPixelTransfer}). | |
16283 | ||
16284 | @item @code{GL_LUMINANCE} | |
16285 | Each element is a single luminance value. The GL converts it to floating | |
16286 | point, then assembles it into an RGBA element by replicating the | |
16287 | luminance value three times for red, green, and blue and attaching 1 for | |
16288 | alpha. Each component is then multiplied by the signed scale factor | |
16289 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
16290 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
16291 | ||
16292 | @item @code{GL_LUMINANCE_ALPHA} | |
16293 | Each element is a luminance/alpha pair. The GL converts it to floating | |
16294 | point, then assembles it into an RGBA element by replicating the | |
16295 | luminance value three times for red, green, and blue. Each component is | |
16296 | then multiplied by the signed scale factor @code{GL_c_SCALE}, added to | |
16297 | the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
16298 | @code{glPixelTransfer}). | |
16299 | ||
16300 | @item @code{GL_DEPTH_COMPONENT} | |
16301 | Each element is a single depth value. The GL converts it to floating | |
16302 | point, multiplies by the signed scale factor @code{GL_DEPTH_SCALE}, adds | |
16303 | the signed bias @code{GL_DEPTH_BIAS}, and clamps to the range [0,1] (see | |
16304 | @code{glPixelTransfer}). | |
16305 | ||
16306 | @end table | |
16307 | ||
16308 | Refer to the @code{glDrawPixels} reference page for a description of the | |
16309 | acceptable values for the @var{type} parameter. | |
16310 | ||
16311 | If an application wants to store the texture at a certain resolution or | |
16312 | in a certain format, it can request the resolution and format with | |
16313 | @var{internalFormat}. The GL will choose an internal representation that | |
16314 | closely approximates that requested by @var{internalFormat}, but it may | |
16315 | not match exactly. (The representations specified by | |
16316 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and | |
16317 | @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 may | |
16318 | also be used to specify the above representations.) | |
16319 | ||
16320 | If the @var{internalFormat} parameter is one of the generic compressed | |
16321 | formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
16322 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
16323 | @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will | |
16324 | replace the internal format with the symbolic constant for a specific | |
16325 | internal format and compress the texture before storage. If no | |
16326 | corresponding internal format is available, or the GL can not compress | |
16327 | that image for any reason, the internal format is instead replaced with | |
16328 | a corresponding base internal format. | |
16329 | ||
16330 | If the @var{internalFormat} parameter is @code{GL_SRGB}, | |
16331 | @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8}, | |
16332 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
16333 | or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red, | |
16334 | green, blue, or luminance components are encoded in the sRGB color | |
16335 | space. Any alpha component is left unchanged. The conversion from the | |
3c9b6116 AW |
16336 | sRGB encoded component @r{@var{c}_@var{s}} to a linear component |
16337 | @r{@var{c}_@var{l}} is: | |
8925f36f | 16338 | |
3c9b6116 AW |
16339 | @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045), |
16340 | ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)} | |
8925f36f | 16341 | |
3c9b6116 | 16342 | Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1]. |
8925f36f AW |
16343 | |
16344 | Use the @code{GL_PROXY_TEXTURE_2D} or @code{GL_PROXY_TEXTURE_CUBE_MAP} | |
16345 | target to try out a resolution and format. The implementation will | |
16346 | update and recompute its best match for the requested storage resolution | |
16347 | and format. To then query this state, call | |
16348 | @code{glGetTexLevelParameter}. If the texture cannot be accommodated, | |
16349 | texture state is set to 0. | |
16350 | ||
16351 | A one-component texture image uses only the red component of the RGBA | |
16352 | color extracted from @var{data}. A two-component image uses the R and A | |
16353 | values. A three-component image uses the R, G, and B values. A | |
16354 | four-component image uses all of the RGBA components. | |
16355 | ||
16356 | Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA textures | |
16357 | during texture filtering and application. Image-based shadowing can be | |
16358 | enabled by comparing texture r coordinates to depth texture values to | |
16359 | generate a boolean result. See @code{glTexParameter} for details on | |
16360 | texture comparison. | |
16361 | ||
8925f36f AW |
16362 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
16363 | @code{GL_TEXTURE_2D}, @code{GL_PROXY_TEXTURE_2D}, | |
16364 | @code{GL_PROXY_TEXTURE_CUBE_MAP}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
16365 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
16366 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
16367 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
16368 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
16369 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
16370 | ||
16371 | @code{GL_INVALID_ENUM} is generated if @var{target} is one of the six | |
16372 | cube map 2D image targets and the width and height parameters are not | |
16373 | equal. | |
16374 | ||
16375 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
16376 | constant. | |
16377 | ||
16378 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
16379 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
16380 | ||
16381 | @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is | |
16382 | less than 0 or greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
16383 | ||
16384 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
16385 | ||
16386 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
16387 | @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of |
16388 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
16389 | |
16390 | @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1, | |
16391 | 2, 3, 4, or one of the accepted resolution and format symbolic | |
16392 | constants. | |
16393 | ||
16394 | @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is | |
16395 | less than 0 or greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
16396 | ||
16397 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
16398 | not supported and the @var{width} or @var{height} cannot be represented | |
3c9b6116 | 16399 | as @r{2^@var{k}+2(@var{border},)} for some integer value of @var{k}. |
8925f36f AW |
16400 | |
16401 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
16402 | ||
16403 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
16404 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
16405 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
16406 | and @var{format} is not @code{GL_RGB}. | |
16407 | ||
16408 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
16409 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
16410 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
16411 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
16412 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
16413 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
16414 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
16415 | ||
16416 | @code{GL_INVALID_OPERATION} is generated if @var{target} is not | |
16417 | @code{GL_TEXTURE_2D} or @code{GL_PROXY_TEXTURE_2D} and | |
16418 | @var{internalFormat} is @code{GL_DEPTH_COMPONENT}, | |
16419 | @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, or | |
16420 | @code{GL_DEPTH_COMPONENT32}. | |
16421 | ||
16422 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
16423 | @code{GL_DEPTH_COMPONENT} and @var{internalFormat} is not | |
16424 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
16425 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}. | |
16426 | ||
16427 | @code{GL_INVALID_OPERATION} is generated if @var{internalFormat} is | |
16428 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
16429 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}, and | |
16430 | @var{format} is not @code{GL_DEPTH_COMPONENT}. | |
16431 | ||
16432 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
16433 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
16434 | object's data store is currently mapped. | |
16435 | ||
16436 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
16437 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
16438 | would be unpacked from the buffer object such that the memory reads | |
16439 | required would exceed the data store size. | |
16440 | ||
16441 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
16442 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
16443 | is not evenly divisible into the number of bytes needed to store in | |
16444 | memory a datum indicated by @var{type}. | |
16445 | ||
16446 | @code{GL_INVALID_OPERATION} is generated if @code{glTexImage2D} is | |
16447 | executed between the execution of @code{glBegin} and the corresponding | |
16448 | execution of @code{glEnd}. | |
16449 | ||
bb894c9d | 16450 | @end deftypefun |
8925f36f | 16451 | |
bb894c9d | 16452 | @deftypefun void glTexImage3D target level internalFormat width height depth border format type data |
3c9b6116 AW |
16453 | Specify a three-dimensional texture image. |
16454 | ||
8925f36f AW |
16455 | @table @asis |
16456 | @item @var{target} | |
16457 | Specifies the target texture. Must be @code{GL_TEXTURE_3D} or | |
16458 | @code{GL_PROXY_TEXTURE_3D}. | |
16459 | ||
16460 | @item @var{level} | |
16461 | Specifies the level-of-detail number. Level 0 is the base image level. | |
3c9b6116 | 16462 | Level @r{@var{n}} is the @r{@var{n}^@var{th}} mipmap reduction image. |
8925f36f AW |
16463 | |
16464 | @item @var{internalFormat} | |
16465 | Specifies the number of color components in the texture. Must be 1, 2, | |
16466 | 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA}, | |
16467 | @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, | |
16468 | @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA}, | |
16469 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
16470 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
16471 | @code{GL_COMPRESSED_RGBA}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
16472 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
16473 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
16474 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
16475 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
16476 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY}, | |
16477 | @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12}, | |
16478 | @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
16479 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
16480 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
16481 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
16482 | @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE}, | |
16483 | @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
16484 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
16485 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
16486 | ||
16487 | @item @var{width} | |
16488 | Specifies the width of the texture image including the border if any. If | |
16489 | the GL version does not support non-power-of-two sizes, this value must | |
3c9b6116 AW |
16490 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
16491 | implementations support 3D texture images that are at least 16 texels | |
16492 | wide. | |
8925f36f AW |
16493 | |
16494 | @item @var{height} | |
16495 | Specifies the height of the texture image including the border if any. | |
16496 | If the GL version does not support non-power-of-two sizes, this value | |
3c9b6116 AW |
16497 | must be @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}. |
16498 | All implementations support 3D texture images that are at least 16 | |
16499 | texels high. | |
8925f36f AW |
16500 | |
16501 | @item @var{depth} | |
16502 | Specifies the depth of the texture image including the border if any. If | |
16503 | the GL version does not support non-power-of-two sizes, this value must | |
3c9b6116 AW |
16504 | be @r{2^@var{k}+2(@var{border},)} for some integer @r{@var{k}}. All |
16505 | implementations support 3D texture images that are at least 16 texels | |
16506 | deep. | |
8925f36f AW |
16507 | |
16508 | @item @var{border} | |
16509 | Specifies the width of the border. Must be either 0 or 1. | |
16510 | ||
16511 | @item @var{format} | |
16512 | Specifies the format of the pixel data. The following symbolic values | |
16513 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, | |
16514 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
16515 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
16516 | @code{GL_LUMINANCE_ALPHA}. | |
16517 | ||
16518 | @item @var{type} | |
16519 | Specifies the data type of the pixel data. The following symbolic values | |
16520 | are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
16521 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
16522 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
16523 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
16524 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
16525 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
16526 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
16527 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
16528 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
16529 | ||
16530 | @item @var{data} | |
16531 | Specifies a pointer to the image data in memory. | |
16532 | ||
16533 | @end table | |
16534 | ||
8925f36f AW |
16535 | Texturing maps a portion of a specified texture image onto each |
16536 | graphical primitive for which texturing is enabled. To enable and | |
16537 | disable three-dimensional texturing, call @code{glEnable} and | |
16538 | @code{glDisable} with argument @code{GL_TEXTURE_3D}. | |
16539 | ||
16540 | To define texture images, call @code{glTexImage3D}. The arguments | |
16541 | describe the parameters of the texture image, such as height, width, | |
16542 | depth, width of the border, level-of-detail number (see | |
16543 | @code{glTexParameter}), and number of color components provided. The | |
16544 | last three arguments describe how the image is represented in memory; | |
16545 | they are identical to the pixel formats used for @code{glDrawPixels}. | |
16546 | ||
16547 | If @var{target} is @code{GL_PROXY_TEXTURE_3D}, no data is read from | |
16548 | @var{data}, but all of the texture image state is recalculated, checked | |
16549 | for consistency, and checked against the implementation's capabilities. | |
16550 | If the implementation cannot handle a texture of the requested texture | |
16551 | size, it sets all of the image state to 0, but does not generate an | |
16552 | error (see @code{glGetError}). To query for an entire mipmap array, use | |
16553 | an image array level greater than or equal to 1. | |
16554 | ||
16555 | If @var{target} is @code{GL_TEXTURE_3D}, data is read from @var{data} as | |
16556 | a sequence of signed or unsigned bytes, shorts, or longs, or | |
16557 | single-precision floating-point values, depending on @var{type}. These | |
16558 | values are grouped into sets of one, two, three, or four values, | |
16559 | depending on @var{format}, to form elements. If @var{type} is | |
16560 | @code{GL_BITMAP}, the data is considered as a string of unsigned bytes | |
16561 | (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is | |
16562 | treated as eight 1-bit elements, with bit ordering determined by | |
16563 | @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}). | |
16564 | ||
16565 | If a non-zero named buffer object is bound to the | |
16566 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
16567 | texture image is specified, @var{data} is treated as a byte offset into | |
16568 | the buffer object's data store. | |
16569 | ||
16570 | The first element corresponds to the lower left corner of the texture | |
16571 | image. Subsequent elements progress left-to-right through the remaining | |
16572 | texels in the lowest row of the texture image, and then in successively | |
16573 | higher rows of the texture image. The final element corresponds to the | |
16574 | upper right corner of the texture image. | |
16575 | ||
16576 | @var{format} determines the composition of each element in @var{data}. | |
16577 | It can assume one of these symbolic values: | |
16578 | ||
16579 | @table @asis | |
16580 | @item @code{GL_COLOR_INDEX} | |
16581 | Each element is a single value, a color index. The GL converts it to | |
16582 | fixed point (with an unspecified number of zero bits to the right of the | |
16583 | binary point), shifted left or right depending on the value and sign of | |
16584 | @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see | |
16585 | @code{glPixelTransfer}). The resulting index is converted to a set of | |
16586 | color components using the @code{GL_PIXEL_MAP_I_TO_R}, | |
16587 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
16588 | @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1]. | |
16589 | ||
16590 | @item @code{GL_RED} | |
16591 | Each element is a single red component. The GL converts it to floating | |
16592 | point and assembles it into an RGBA element by attaching 0 for green and | |
16593 | blue, and 1 for alpha. Each component is then multiplied by the signed | |
16594 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
16595 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
16596 | @code{glPixelTransfer}). | |
16597 | ||
16598 | @item @code{GL_GREEN} | |
16599 | Each element is a single green component. The GL converts it to floating | |
16600 | point and assembles it into an RGBA element by attaching 0 for red and | |
16601 | blue, and 1 for alpha. Each component is then multiplied by the signed | |
16602 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
16603 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
16604 | @code{glPixelTransfer}). | |
16605 | ||
16606 | @item @code{GL_BLUE} | |
16607 | Each element is a single blue component. The GL converts it to floating | |
16608 | point and assembles it into an RGBA element by attaching 0 for red and | |
16609 | green, and 1 for alpha. Each component is then multiplied by the signed | |
16610 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
16611 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
16612 | @code{glPixelTransfer}). | |
16613 | ||
16614 | @item @code{GL_ALPHA} | |
16615 | Each element is a single alpha component. The GL converts it to floating | |
16616 | point and assembles it into an RGBA element by attaching 0 for red, | |
16617 | green, and blue. Each component is then multiplied by the signed scale | |
16618 | factor @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
16619 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
16620 | ||
16621 | @item @code{GL_INTENSITY} | |
16622 | Each element is a single intensity value. The GL converts it to floating | |
16623 | point, then assembles it into an RGBA element by replicating the | |
16624 | intensity value three times for red, green, blue, and alpha. Each | |
16625 | component is then multiplied by the signed scale factor | |
16626 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
16627 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
16628 | ||
16629 | @item @code{GL_RGB} | |
16630 | @item @code{GL_BGR} | |
16631 | Each element is an RGB triple. The GL converts it to floating point and | |
16632 | assembles it into an RGBA element by attaching 1 for alpha. Each | |
16633 | component is then multiplied by the signed scale factor | |
16634 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
16635 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
16636 | ||
16637 | @item @code{GL_RGBA} | |
16638 | @item @code{GL_BGRA} | |
16639 | Each element contains all four components. Each component is multiplied | |
16640 | by the signed scale factor @code{GL_c_SCALE}, added to the signed bias | |
16641 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
16642 | @code{glPixelTransfer}). | |
16643 | ||
16644 | @item @code{GL_LUMINANCE} | |
16645 | Each element is a single luminance value. The GL converts it to floating | |
16646 | point, then assembles it into an RGBA element by replicating the | |
16647 | luminance value three times for red, green, and blue and attaching 1 for | |
16648 | alpha. Each component is then multiplied by the signed scale factor | |
16649 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
16650 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
16651 | ||
16652 | @item @code{GL_LUMINANCE_ALPHA} | |
16653 | Each element is a luminance/alpha pair. The GL converts it to floating | |
16654 | point, then assembles it into an RGBA element by replicating the | |
16655 | luminance value three times for red, green, and blue. Each component is | |
16656 | then multiplied by the signed scale factor @code{GL_c_SCALE}, added to | |
16657 | the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
16658 | @code{glPixelTransfer}). | |
16659 | ||
16660 | @end table | |
16661 | ||
16662 | Refer to the @code{glDrawPixels} reference page for a description of the | |
16663 | acceptable values for the @var{type} parameter. | |
16664 | ||
16665 | If an application wants to store the texture at a certain resolution or | |
16666 | in a certain format, it can request the resolution and format with | |
16667 | @var{internalFormat}. The GL will choose an internal representation that | |
16668 | closely approximates that requested by @var{internalFormat}, but it may | |
16669 | not match exactly. (The representations specified by | |
16670 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and | |
16671 | @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 may | |
16672 | also be used to specify the above representations.) | |
16673 | ||
16674 | If the @var{internalFormat} parameter is one of the generic compressed | |
16675 | formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
16676 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
16677 | @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will | |
16678 | replace the internal format with the symbolic constant for a specific | |
16679 | internal format and compress the texture before storage. If no | |
16680 | corresponding internal format is available, or the GL can not compress | |
16681 | that image for any reason, the internal format is instead replaced with | |
16682 | a corresponding base internal format. | |
16683 | ||
16684 | If the @var{internalFormat} parameter is @code{GL_SRGB}, | |
16685 | @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8}, | |
16686 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
16687 | or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red, | |
16688 | green, blue, or luminance components are encoded in the sRGB color | |
16689 | space. Any alpha component is left unchanged. The conversion from the | |
3c9b6116 AW |
16690 | sRGB encoded component @r{@var{c}_@var{s}} to a linear component |
16691 | @r{@var{c}_@var{l}} is: | |
8925f36f | 16692 | |
3c9b6116 AW |
16693 | @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045), |
16694 | ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)} | |
8925f36f | 16695 | |
3c9b6116 | 16696 | Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1]. |
8925f36f AW |
16697 | |
16698 | Use the @code{GL_PROXY_TEXTURE_3D} target to try out a resolution and | |
16699 | format. The implementation will update and recompute its best match for | |
16700 | the requested storage resolution and format. To then query this state, | |
16701 | call @code{glGetTexLevelParameter}. If the texture cannot be | |
16702 | accommodated, texture state is set to 0. | |
16703 | ||
16704 | A one-component texture image uses only the red component of the RGBA | |
16705 | color extracted from @var{data}. A two-component image uses the R and A | |
16706 | values. A three-component image uses the R, G, and B values. A | |
16707 | four-component image uses all of the RGBA components. | |
16708 | ||
8925f36f AW |
16709 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
16710 | @code{GL_TEXTURE_3D} or @code{GL_PROXY_TEXTURE_3D}. | |
16711 | ||
16712 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
16713 | format constant. Format constants other than @code{GL_STENCIL_INDEX} and | |
16714 | @code{GL_DEPTH_COMPONENT} are accepted. | |
16715 | ||
16716 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
16717 | constant. | |
16718 | ||
16719 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
16720 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
16721 | ||
16722 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
16723 | ||
16724 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
16725 | @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of |
16726 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
16727 | |
16728 | @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1, | |
16729 | 2, 3, 4, or one of the accepted resolution and format symbolic | |
16730 | constants. | |
16731 | ||
16732 | @code{GL_INVALID_VALUE} is generated if @var{width}, @var{height}, or | |
16733 | @var{depth} is less than 0 or greater than 2 + | |
16734 | @code{GL_MAX_TEXTURE_SIZE}. | |
16735 | ||
16736 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
16737 | not supported and the @var{width}, @var{height}, or @var{depth} cannot | |
3c9b6116 AW |
16738 | be represented as @r{2^@var{k}+2(@var{border},)} for some integer value |
16739 | of @var{k}. | |
8925f36f AW |
16740 | |
16741 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
16742 | ||
16743 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
16744 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
16745 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
16746 | and @var{format} is not @code{GL_RGB}. | |
16747 | ||
16748 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
16749 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
16750 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
16751 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
16752 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
16753 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
16754 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
16755 | ||
16756 | @code{GL_INVALID_OPERATION} is generated if @var{format} or | |
16757 | @var{internalFormat} is @code{GL_DEPTH_COMPONENT}, | |
16758 | @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, or | |
16759 | @code{GL_DEPTH_COMPONENT32}. | |
16760 | ||
16761 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
16762 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
16763 | object's data store is currently mapped. | |
16764 | ||
16765 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
16766 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
16767 | would be unpacked from the buffer object such that the memory reads | |
16768 | required would exceed the data store size. | |
16769 | ||
16770 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
16771 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
16772 | is not evenly divisible into the number of bytes needed to store in | |
16773 | memory a datum indicated by @var{type}. | |
16774 | ||
16775 | @code{GL_INVALID_OPERATION} is generated if @code{glTexImage3D} is | |
16776 | executed between the execution of @code{glBegin} and the corresponding | |
16777 | execution of @code{glEnd}. | |
16778 | ||
bb894c9d | 16779 | @end deftypefun |
8925f36f | 16780 | |
bb894c9d AW |
16781 | @deftypefun void glTexParameterf target pname param |
16782 | @deftypefunx void glTexParameteri target pname param | |
3c9b6116 AW |
16783 | Set texture parameters. |
16784 | ||
8925f36f AW |
16785 | @table @asis |
16786 | @item @var{target} | |
16787 | Specifies the target texture, which must be either @code{GL_TEXTURE_1D}, | |
16788 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, or | |
16789 | @code{GL_TEXTURE_CUBE_MAP}. | |
16790 | ||
16791 | @item @var{pname} | |
16792 | Specifies the symbolic name of a single-valued texture parameter. | |
16793 | @var{pname} can be one of the following: @code{GL_TEXTURE_MIN_FILTER}, | |
16794 | @code{GL_TEXTURE_MAG_FILTER}, @code{GL_TEXTURE_MIN_LOD}, | |
16795 | @code{GL_TEXTURE_MAX_LOD}, @code{GL_TEXTURE_BASE_LEVEL}, | |
16796 | @code{GL_TEXTURE_MAX_LEVEL}, @code{GL_TEXTURE_WRAP_S}, | |
16797 | @code{GL_TEXTURE_WRAP_T}, @code{GL_TEXTURE_WRAP_R}, | |
16798 | @code{GL_TEXTURE_PRIORITY}, @code{GL_TEXTURE_COMPARE_MODE}, | |
16799 | @code{GL_TEXTURE_COMPARE_FUNC}, @code{GL_DEPTH_TEXTURE_MODE}, or | |
16800 | @code{GL_GENERATE_MIPMAP}. | |
16801 | ||
16802 | @item @var{param} | |
16803 | Specifies the value of @var{pname}. | |
16804 | ||
16805 | @end table | |
16806 | ||
8925f36f AW |
16807 | Texture mapping is a technique that applies an image onto an object's |
16808 | surface as if the image were a decal or cellophane shrink-wrap. The | |
3c9b6116 AW |
16809 | image is created in texture space, with an (@r{@var{s}}, @r{@var{t}}) |
16810 | coordinate system. A texture is a one- or two-dimensional image and a | |
16811 | set of parameters that determine how samples are derived from the image. | |
8925f36f AW |
16812 | |
16813 | @code{glTexParameter} assigns the value or values in @var{params} to the | |
16814 | texture parameter specified as @var{pname}. @var{target} defines the | |
16815 | target texture, either @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, or | |
16816 | @code{GL_TEXTURE_3D}. The following symbols are accepted in @var{pname}: | |
16817 | ||
16818 | @table @asis | |
16819 | @item @code{GL_TEXTURE_MIN_FILTER} | |
16820 | The texture minifying function is used whenever the pixel being textured | |
16821 | maps to an area greater than one texture element. There are six defined | |
16822 | minifying functions. Two of them use the nearest one or nearest four | |
16823 | texture elements to compute the texture value. The other four use | |
16824 | mipmaps. | |
16825 | ||
16826 | A mipmap is an ordered set of arrays representing the same image at | |
16827 | progressively lower resolutions. If the texture has dimensions | |
3c9b6116 AW |
16828 | @r{2^@var{n}×2^@var{m}}, there are @r{@var{max}(@var{n},@var{m})+1} |
16829 | mipmaps. The first mipmap is the original texture, with dimensions | |
16830 | @r{2^@var{n}×2^@var{m}}. Each subsequent mipmap has dimensions | |
16831 | @r{2^@var{k}-1,×2^@var{l}-1,}, where @r{2^@var{k}×2^@var{l}} are the | |
16832 | dimensions of the previous mipmap, until either @r{@var{k}=0} or | |
16833 | @r{@var{l}=0}. At that point, subsequent mipmaps have dimension | |
16834 | @r{1×2^@var{l}-1,} or @r{2^@var{k}-1,×1} until the final mipmap, which | |
16835 | has dimension @r{1×1}. To define the mipmaps, call @code{glTexImage1D}, | |
8925f36f AW |
16836 | @code{glTexImage2D}, @code{glTexImage3D}, @code{glCopyTexImage1D}, or |
16837 | @code{glCopyTexImage2D} with the @var{level} argument indicating the | |
16838 | order of the mipmaps. Level 0 is the original texture; level | |
3c9b6116 | 16839 | @r{@var{max}(@var{n},@var{m})} is the final @r{1×1} mipmap. |
8925f36f AW |
16840 | |
16841 | @var{params} supplies a function for minifying the texture as one of the | |
16842 | following: | |
16843 | ||
16844 | As more texture elements are sampled in the minification process, fewer | |
16845 | aliasing artifacts will be apparent. While the @code{GL_NEAREST} and | |
16846 | @code{GL_LINEAR} minification functions can be faster than the other | |
16847 | four, they sample only one or four texture elements to determine the | |
16848 | texture value of the pixel being rendered and can produce moire patterns | |
16849 | or ragged transitions. The initial value of @code{GL_TEXTURE_MIN_FILTER} | |
16850 | is @code{GL_NEAREST_MIPMAP_LINEAR}. | |
16851 | ||
16852 | @item @code{GL_TEXTURE_MAG_FILTER} | |
16853 | The texture magnification function is used when the pixel being textured | |
16854 | maps to an area less than or equal to one texture element. It sets the | |
16855 | texture magnification function to either @code{GL_NEAREST} or | |
16856 | @code{GL_LINEAR} (see below). @code{GL_NEAREST} is generally faster than | |
16857 | @code{GL_LINEAR}, but it can produce textured images with sharper edges | |
16858 | because the transition between texture elements is not as smooth. The | |
16859 | initial value of @code{GL_TEXTURE_MAG_FILTER} is @code{GL_LINEAR}. | |
16860 | ||
16861 | @end table | |
16862 | ||
16863 | @table @asis | |
16864 | @item @code{GL_NEAREST} | |
16865 | Returns the value of the texture element that is nearest (in Manhattan | |
16866 | distance) to the center of the pixel being textured. | |
16867 | ||
16868 | @item @code{GL_LINEAR} | |
16869 | Returns the weighted average of the four texture elements that are | |
16870 | closest to the center of the pixel being textured. These can include | |
16871 | border texture elements, depending on the values of | |
16872 | @code{GL_TEXTURE_WRAP_S} and @code{GL_TEXTURE_WRAP_T}, and on the exact | |
16873 | mapping. | |
16874 | ||
16875 | @item @code{GL_NEAREST_MIPMAP_NEAREST} | |
16876 | Chooses the mipmap that most closely matches the size of the pixel being | |
16877 | textured and uses the @code{GL_NEAREST} criterion (the texture element | |
16878 | nearest to the center of the pixel) to produce a texture value. | |
16879 | ||
16880 | @item @code{GL_LINEAR_MIPMAP_NEAREST} | |
16881 | Chooses the mipmap that most closely matches the size of the pixel being | |
16882 | textured and uses the @code{GL_LINEAR} criterion (a weighted average of | |
16883 | the four texture elements that are closest to the center of the pixel) | |
16884 | to produce a texture value. | |
16885 | ||
16886 | @item @code{GL_NEAREST_MIPMAP_LINEAR} | |
16887 | Chooses the two mipmaps that most closely match the size of the pixel | |
16888 | being textured and uses the @code{GL_NEAREST} criterion (the texture | |
16889 | element nearest to the center of the pixel) to produce a texture value | |
16890 | from each mipmap. The final texture value is a weighted average of those | |
16891 | two values. | |
16892 | ||
16893 | @item @code{GL_LINEAR_MIPMAP_LINEAR} | |
16894 | Chooses the two mipmaps that most closely match the size of the pixel | |
16895 | being textured and uses the @code{GL_LINEAR} criterion (a weighted | |
16896 | average of the four texture elements that are closest to the center of | |
16897 | the pixel) to produce a texture value from each mipmap. The final | |
16898 | texture value is a weighted average of those two values. | |
16899 | ||
16900 | @end table | |
16901 | ||
16902 | @table @asis | |
16903 | @item @code{GL_NEAREST} | |
16904 | Returns the value of the texture element that is nearest (in Manhattan | |
16905 | distance) to the center of the pixel being textured. | |
16906 | ||
16907 | @item @code{GL_LINEAR} | |
16908 | Returns the weighted average of the four texture elements that are | |
16909 | closest to the center of the pixel being textured. These can include | |
16910 | border texture elements, depending on the values of | |
16911 | @code{GL_TEXTURE_WRAP_S} and @code{GL_TEXTURE_WRAP_T}, and on the exact | |
16912 | mapping. | |
16913 | ||
16914 | @end table | |
16915 | ||
16916 | ||
16917 | ||
16918 | @table @asis | |
16919 | @item @code{GL_TEXTURE_MIN_LOD} | |
16920 | Sets the minimum level-of-detail parameter. This floating-point value | |
16921 | limits the selection of highest resolution mipmap (lowest mipmap level). | |
16922 | The initial value is -1000. | |
16923 | ||
16924 | @end table | |
16925 | ||
16926 | ||
16927 | ||
16928 | @table @asis | |
16929 | @item @code{GL_TEXTURE_MAX_LOD} | |
16930 | Sets the maximum level-of-detail parameter. This floating-point value | |
16931 | limits the selection of the lowest resolution mipmap (highest mipmap | |
16932 | level). The initial value is 1000. | |
16933 | ||
16934 | @end table | |
16935 | ||
16936 | ||
16937 | ||
16938 | @table @asis | |
16939 | @item @code{GL_TEXTURE_BASE_LEVEL} | |
16940 | Specifies the index of the lowest defined mipmap level. This is an | |
16941 | integer value. The initial value is 0. | |
16942 | ||
16943 | @end table | |
16944 | ||
16945 | ||
16946 | ||
16947 | @table @asis | |
16948 | @item @code{GL_TEXTURE_MAX_LEVEL} | |
16949 | Sets the index of the highest defined mipmap level. This is an integer | |
16950 | value. The initial value is 1000. | |
16951 | ||
16952 | @end table | |
16953 | ||
16954 | ||
16955 | ||
16956 | @table @asis | |
16957 | @item @code{GL_TEXTURE_WRAP_S} | |
3c9b6116 | 16958 | Sets the wrap parameter for texture coordinate @r{@var{s}} to either |
8925f36f AW |
16959 | @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE}, |
16960 | @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. @code{GL_CLAMP} causes | |
3c9b6116 AW |
16961 | @r{@var{s}} coordinates to be clamped to the range [0,1] and is useful |
16962 | for preventing wrapping artifacts when mapping a single image onto an | |
16963 | object. @code{GL_CLAMP_TO_BORDER} causes the @r{@var{s}} coordinate to | |
16964 | be clamped to the range @r{[-1/2@var{N},,1+1/2@var{N},]}, where | |
16965 | @r{@var{N}} is the size of the texture in the direction of | |
16966 | clamping.@code{GL_CLAMP_TO_EDGE} causes @r{@var{s}} coordinates to be | |
16967 | clamped to the range @r{[1/2@var{N},,1-1/2@var{N},]}, where @r{@var{N}} | |
16968 | is the size of the texture in the direction of clamping. | |
16969 | @code{GL_REPEAT} causes the integer part of the @r{@var{s}} coordinate | |
16970 | to be ignored; the GL uses only the fractional part, thereby creating a | |
16971 | repeating pattern. @code{GL_MIRRORED_REPEAT} causes the @r{@var{s}} | |
16972 | coordinate to be set to the fractional part of the texture coordinate if | |
16973 | the integer part of @r{@var{s}} is even; if the integer part of | |
16974 | @r{@var{s}} is odd, then the @r{@var{s}} texture coordinate is set to | |
16975 | @r{1-@var{frac}(@var{s},)}, where @r{@var{frac}(@var{s},)} represents | |
16976 | the fractional part of @r{@var{s}}. Border texture elements are accessed | |
16977 | only if wrapping is set to @code{GL_CLAMP} or @code{GL_CLAMP_TO_BORDER}. | |
16978 | Initially, @code{GL_TEXTURE_WRAP_S} is set to @code{GL_REPEAT}. | |
8925f36f AW |
16979 | |
16980 | @end table | |
16981 | ||
16982 | ||
16983 | ||
16984 | @table @asis | |
16985 | @item @code{GL_TEXTURE_WRAP_T} | |
3c9b6116 | 16986 | Sets the wrap parameter for texture coordinate @r{@var{t}} to either |
8925f36f AW |
16987 | @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE}, |
16988 | @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. See the discussion under | |
16989 | @code{GL_TEXTURE_WRAP_S}. Initially, @code{GL_TEXTURE_WRAP_T} is set to | |
16990 | @code{GL_REPEAT}. | |
16991 | ||
16992 | @item @code{GL_TEXTURE_WRAP_R} | |
3c9b6116 | 16993 | Sets the wrap parameter for texture coordinate @r{@var{r}} to either |
8925f36f AW |
16994 | @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE}, |
16995 | @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. See the discussion under | |
16996 | @code{GL_TEXTURE_WRAP_S}. Initially, @code{GL_TEXTURE_WRAP_R} is set to | |
16997 | @code{GL_REPEAT}. | |
16998 | ||
16999 | @item @code{GL_TEXTURE_BORDER_COLOR} | |
17000 | Sets a border color. @var{params} contains four values that comprise the | |
17001 | RGBA color of the texture border. Integer color components are | |
17002 | interpreted linearly such that the most positive integer maps to 1.0, | |
17003 | and the most negative integer maps to -1.0. The values are clamped to | |
17004 | the range [0,1] when they are specified. Initially, the border color is | |
17005 | (0, 0, 0, 0). | |
17006 | ||
17007 | @item @code{GL_TEXTURE_PRIORITY} | |
17008 | Specifies the texture residence priority of the currently bound texture. | |
3c9b6116 | 17009 | Permissible values are in the range @r{[0,1]}. See |
8925f36f AW |
17010 | @code{glPrioritizeTextures} and @code{glBindTexture} for more |
17011 | information. | |
17012 | ||
17013 | @item @code{GL_TEXTURE_COMPARE_MODE} | |
17014 | Specifies the texture comparison mode for currently bound depth | |
17015 | textures. That is, a texture whose internal format is | |
17016 | @code{GL_DEPTH_COMPONENT_*}; see @code{glTexImage2D}) Permissible values | |
17017 | are: | |
17018 | ||
17019 | @item @code{GL_TEXTURE_COMPARE_FUNC} | |
17020 | Specifies the comparison operator used when | |
17021 | @code{GL_TEXTURE_COMPARE_MODE} is set to @code{GL_COMPARE_R_TO_TEXTURE}. | |
3c9b6116 AW |
17022 | Permissible values are: where @r{@var{r}} is the current interpolated |
17023 | texture coordinate, and @r{@var{D}_@var{t}} is the depth texture value | |
17024 | sampled from the currently bound depth texture. @r{@var{result}} is | |
17025 | assigned to the either the luminance, intensity, or alpha (as specified | |
17026 | by @code{GL_DEPTH_TEXTURE_MODE}.) | |
8925f36f AW |
17027 | |
17028 | @item @code{GL_DEPTH_TEXTURE_MODE} | |
17029 | Specifies a single symbolic constant indicating how depth values should | |
17030 | be treated during filtering and texture application. Accepted values are | |
17031 | @code{GL_LUMINANCE}, @code{GL_INTENSITY}, and @code{GL_ALPHA}. The | |
17032 | initial value is @code{GL_LUMINANCE}. | |
17033 | ||
17034 | @item @code{GL_GENERATE_MIPMAP} | |
17035 | Specifies a boolean value that indicates if all levels of a mipmap array | |
17036 | should be automatically updated when any modification to the base level | |
17037 | mipmap is done. The initial value is @code{GL_FALSE}. | |
17038 | ||
17039 | @end table | |
17040 | ||
17041 | @table @asis | |
17042 | @item @code{GL_COMPARE_R_TO_TEXTURE} | |
3c9b6116 | 17043 | Specifies that the interpolated and clamped @r{@var{r}} texture |
8925f36f AW |
17044 | coordinate should be compared to the value in the currently bound depth |
17045 | texture. See the discussion of @code{GL_TEXTURE_COMPARE_FUNC} for | |
17046 | details of how the comparison is evaluated. The result of the comparison | |
17047 | is assigned to luminance, intensity, or alpha (as specified by | |
17048 | @code{GL_DEPTH_TEXTURE_MODE}). | |
17049 | ||
17050 | @item @code{GL_NONE} | |
17051 | Specifies that the luminance, intensity, or alpha (as specified by | |
17052 | @code{GL_DEPTH_TEXTURE_MODE}) should be assigned the appropriate value | |
17053 | from the currently bound depth texture. | |
17054 | ||
17055 | @end table | |
17056 | ||
17057 | @table @asis | |
17058 | @item @strong{Texture Comparison Function} | |
17059 | @strong{Computed result} | |
17060 | ||
17061 | @item @code{GL_LEQUAL} | |
3c9b6116 | 17062 | @r{@var{result}=@{(1.0), (0.0) (@var{r}<=@var{D}_@var{t},), |
8925f36f AW |
17063 | (@var{r}>@var{D}_@var{t},),} |
17064 | ||
17065 | @item @code{GL_GEQUAL} | |
3c9b6116 | 17066 | @r{@var{result}=@{(1.0), (0.0) (@var{r}>=@var{D}_@var{t},), |
8925f36f AW |
17067 | (@var{r}<@var{D}_@var{t},),} |
17068 | ||
17069 | @item @code{GL_LESS} | |
3c9b6116 | 17070 | @r{@var{result}=@{(1.0), (0.0) (@var{r}<@var{D}_@var{t},), |
8925f36f AW |
17071 | (@var{r}>=@var{D}_@var{t},),} |
17072 | ||
17073 | @item @code{GL_GREATER} | |
3c9b6116 | 17074 | @r{@var{result}=@{(1.0), (0.0) (@var{r}>@var{D}_@var{t},), |
8925f36f AW |
17075 | (@var{r}<=@var{D}_@var{t},),} |
17076 | ||
17077 | @item @code{GL_EQUAL} | |
3c9b6116 | 17078 | @r{@var{result}=@{(1.0), (0.0) (@var{r}=@var{D}_@var{t},), |
8925f36f AW |
17079 | (@var{r}≠@var{D}_@var{t},),} |
17080 | ||
17081 | @item @code{GL_NOTEQUAL} | |
3c9b6116 | 17082 | @r{@var{result}=@{(1.0), (0.0) (@var{r}≠@var{D}_@var{t},), |
8925f36f AW |
17083 | (@var{r}=@var{D}_@var{t},),} |
17084 | ||
17085 | @item @code{GL_ALWAYS} | |
3c9b6116 | 17086 | @r{@var{result}=@code{1.0}} |
8925f36f AW |
17087 | |
17088 | @item @code{GL_NEVER} | |
3c9b6116 | 17089 | @r{@var{result}=@code{0.0}} |
8925f36f AW |
17090 | |
17091 | @end table | |
17092 | ||
8925f36f AW |
17093 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is |
17094 | not one of the accepted defined values. | |
17095 | ||
17096 | @code{GL_INVALID_ENUM} is generated if @var{params} should have a | |
17097 | defined constant value (based on the value of @var{pname}) and does not. | |
17098 | ||
17099 | @code{GL_INVALID_OPERATION} is generated if @code{glTexParameter} is | |
17100 | executed between the execution of @code{glBegin} and the corresponding | |
17101 | execution of @code{glEnd}. | |
17102 | ||
bb894c9d | 17103 | @end deftypefun |
8925f36f | 17104 | |
bb894c9d | 17105 | @deftypefun void glTexSubImage1D target level xoffset width format type data |
3c9b6116 AW |
17106 | Specify a one-dimensional texture subimage. |
17107 | ||
8925f36f AW |
17108 | @table @asis |
17109 | @item @var{target} | |
17110 | Specifies the target texture. Must be @code{GL_TEXTURE_1D}. | |
17111 | ||
17112 | @item @var{level} | |
17113 | Specifies the level-of-detail number. Level 0 is the base image level. | |
17114 | Level @var{n} is the @var{n}th mipmap reduction image. | |
17115 | ||
17116 | @item @var{xoffset} | |
17117 | Specifies a texel offset in the x direction within the texture array. | |
17118 | ||
17119 | @item @var{width} | |
17120 | Specifies the width of the texture subimage. | |
17121 | ||
17122 | @item @var{format} | |
17123 | Specifies the format of the pixel data. The following symbolic values | |
17124 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, | |
17125 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
17126 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
17127 | @code{GL_LUMINANCE_ALPHA}. | |
17128 | ||
17129 | @item @var{type} | |
17130 | Specifies the data type of the pixel data. The following symbolic values | |
17131 | are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
17132 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
17133 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
17134 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
17135 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
17136 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
17137 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
17138 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
17139 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
17140 | ||
17141 | @item @var{data} | |
17142 | Specifies a pointer to the image data in memory. | |
17143 | ||
17144 | @end table | |
17145 | ||
8925f36f AW |
17146 | Texturing maps a portion of a specified texture image onto each |
17147 | graphical primitive for which texturing is enabled. To enable or disable | |
17148 | one-dimensional texturing, call @code{glEnable} and @code{glDisable} | |
17149 | with argument @code{GL_TEXTURE_1D}. | |
17150 | ||
17151 | @code{glTexSubImage1D} redefines a contiguous subregion of an existing | |
17152 | one-dimensional texture image. The texels referenced by @var{data} | |
17153 | replace the portion of the existing texture array with x indices | |
3c9b6116 | 17154 | @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive. This |
8925f36f AW |
17155 | region may not include any texels outside the range of the texture array |
17156 | as it was originally specified. It is not an error to specify a | |
17157 | subtexture with width of 0, but such a specification has no effect. | |
17158 | ||
17159 | If a non-zero named buffer object is bound to the | |
17160 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
17161 | texture image is specified, @var{data} is treated as a byte offset into | |
17162 | the buffer object's data store. | |
17163 | ||
8925f36f AW |
17164 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
17165 | allowable values. | |
17166 | ||
17167 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
17168 | format constant. | |
17169 | ||
17170 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
17171 | constant. | |
17172 | ||
17173 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
17174 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
17175 | ||
17176 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
17177 | ||
17178 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 | 17179 | @r{@var{log}_2}@var{max}, where @var{max} is the returned value of |
8925f36f AW |
17180 | @code{GL_MAX_TEXTURE_SIZE}. |
17181 | ||
3c9b6116 AW |
17182 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, or |
17183 | if @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, where | |
17184 | @r{@var{w}} is the @code{GL_TEXTURE_WIDTH}, and @r{@var{b}} is the width | |
17185 | of the @code{GL_TEXTURE_BORDER} of the texture image being modified. | |
17186 | Note that @r{@var{w}} includes twice the border width. | |
8925f36f AW |
17187 | |
17188 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0. | |
17189 | ||
17190 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
17191 | been defined by a previous @code{glTexImage1D} operation. | |
17192 | ||
17193 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
17194 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
17195 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
17196 | and @var{format} is not @code{GL_RGB}. | |
17197 | ||
17198 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
17199 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
17200 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
17201 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
17202 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
17203 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
17204 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
17205 | ||
17206 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
17207 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
17208 | object's data store is currently mapped. | |
17209 | ||
17210 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
17211 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
17212 | would be unpacked from the buffer object such that the memory reads | |
17213 | required would exceed the data store size. | |
17214 | ||
17215 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
17216 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
17217 | is not evenly divisible into the number of bytes needed to store in | |
17218 | memory a datum indicated by @var{type}. | |
17219 | ||
17220 | @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage1D} is | |
17221 | executed between the execution of @code{glBegin} and the corresponding | |
17222 | execution of @code{glEnd}. | |
17223 | ||
bb894c9d | 17224 | @end deftypefun |
8925f36f | 17225 | |
bb894c9d | 17226 | @deftypefun void glTexSubImage2D target level xoffset yoffset width height format type data |
3c9b6116 AW |
17227 | Specify a two-dimensional texture subimage. |
17228 | ||
8925f36f AW |
17229 | @table @asis |
17230 | @item @var{target} | |
17231 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, | |
17232 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
17233 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
17234 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
17235 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
17236 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
17237 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
17238 | ||
17239 | @item @var{level} | |
17240 | Specifies the level-of-detail number. Level 0 is the base image level. | |
17241 | Level @var{n} is the @var{n}th mipmap reduction image. | |
17242 | ||
17243 | @item @var{xoffset} | |
17244 | Specifies a texel offset in the x direction within the texture array. | |
17245 | ||
17246 | @item @var{yoffset} | |
17247 | Specifies a texel offset in the y direction within the texture array. | |
17248 | ||
17249 | @item @var{width} | |
17250 | Specifies the width of the texture subimage. | |
17251 | ||
17252 | @item @var{height} | |
17253 | Specifies the height of the texture subimage. | |
17254 | ||
17255 | @item @var{format} | |
17256 | Specifies the format of the pixel data. The following symbolic values | |
17257 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, | |
17258 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
17259 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
17260 | @code{GL_LUMINANCE_ALPHA}. | |
17261 | ||
17262 | @item @var{type} | |
17263 | Specifies the data type of the pixel data. The following symbolic values | |
17264 | are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
17265 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
17266 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
17267 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
17268 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
17269 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
17270 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
17271 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
17272 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
17273 | ||
17274 | @item @var{data} | |
17275 | Specifies a pointer to the image data in memory. | |
17276 | ||
17277 | @end table | |
17278 | ||
8925f36f AW |
17279 | Texturing maps a portion of a specified texture image onto each |
17280 | graphical primitive for which texturing is enabled. To enable and | |
17281 | disable two-dimensional texturing, call @code{glEnable} and | |
17282 | @code{glDisable} with argument @code{GL_TEXTURE_2D}. | |
17283 | ||
17284 | @code{glTexSubImage2D} redefines a contiguous subregion of an existing | |
17285 | two-dimensional texture image. The texels referenced by @var{data} | |
17286 | replace the portion of the existing texture array with x indices | |
3c9b6116 AW |
17287 | @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive, and y |
17288 | indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive. | |
17289 | This region may not include any texels outside the range of the texture | |
17290 | array as it was originally specified. It is not an error to specify a | |
17291 | subtexture with zero width or height, but such a specification has no | |
17292 | effect. | |
8925f36f AW |
17293 | |
17294 | If a non-zero named buffer object is bound to the | |
17295 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
17296 | texture image is specified, @var{data} is treated as a byte offset into | |
17297 | the buffer object's data store. | |
17298 | ||
8925f36f AW |
17299 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
17300 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
17301 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
17302 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
17303 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
17304 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
17305 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
17306 | ||
17307 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
17308 | format constant. | |
17309 | ||
17310 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
17311 | constant. | |
17312 | ||
17313 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
17314 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
17315 | ||
17316 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
17317 | ||
17318 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 | 17319 | @r{@var{log}_2}@var{max}, where @var{max} is the returned value of |
8925f36f AW |
17320 | @code{GL_MAX_TEXTURE_SIZE}. |
17321 | ||
3c9b6116 AW |
17322 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, |
17323 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, | |
17324 | @r{@var{yoffset}<-@var{b}}, or | |
17325 | @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, where @r{@var{w}} | |
17326 | is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the | |
17327 | @code{GL_TEXTURE_HEIGHT}, and @r{@var{b}} is the border width of the | |
17328 | texture image being modified. Note that @r{@var{w}} and @r{@var{h}} | |
17329 | include twice the border width. | |
8925f36f AW |
17330 | |
17331 | @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is | |
17332 | less than 0. | |
17333 | ||
17334 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
17335 | been defined by a previous @code{glTexImage2D} operation. | |
17336 | ||
17337 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
17338 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
17339 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
17340 | and @var{format} is not @code{GL_RGB}. | |
17341 | ||
17342 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
17343 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
17344 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
17345 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
17346 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
17347 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
17348 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
17349 | ||
17350 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
17351 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
17352 | object's data store is currently mapped. | |
17353 | ||
17354 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
17355 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
17356 | would be unpacked from the buffer object such that the memory reads | |
17357 | required would exceed the data store size. | |
17358 | ||
17359 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
17360 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
17361 | is not evenly divisible into the number of bytes needed to store in | |
17362 | memory a datum indicated by @var{type}. | |
17363 | ||
17364 | @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage2D} is | |
17365 | executed between the execution of @code{glBegin} and the corresponding | |
17366 | execution of @code{glEnd}. | |
17367 | ||
bb894c9d | 17368 | @end deftypefun |
8925f36f | 17369 | |
bb894c9d | 17370 | @deftypefun void glTexSubImage3D target level xoffset yoffset zoffset width height depth format type data |
3c9b6116 AW |
17371 | Specify a three-dimensional texture subimage. |
17372 | ||
8925f36f AW |
17373 | @table @asis |
17374 | @item @var{target} | |
17375 | Specifies the target texture. Must be @code{GL_TEXTURE_3D}. | |
17376 | ||
17377 | @item @var{level} | |
17378 | Specifies the level-of-detail number. Level 0 is the base image level. | |
17379 | Level @var{n} is the @var{n}th mipmap reduction image. | |
17380 | ||
17381 | @item @var{xoffset} | |
17382 | Specifies a texel offset in the x direction within the texture array. | |
17383 | ||
17384 | @item @var{yoffset} | |
17385 | Specifies a texel offset in the y direction within the texture array. | |
17386 | ||
17387 | @item @var{zoffset} | |
17388 | Specifies a texel offset in the z direction within the texture array. | |
17389 | ||
17390 | @item @var{width} | |
17391 | Specifies the width of the texture subimage. | |
17392 | ||
17393 | @item @var{height} | |
17394 | Specifies the height of the texture subimage. | |
17395 | ||
17396 | @item @var{depth} | |
17397 | Specifies the depth of the texture subimage. | |
17398 | ||
17399 | @item @var{format} | |
17400 | Specifies the format of the pixel data. The following symbolic values | |
17401 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, | |
17402 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
17403 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
17404 | @code{GL_LUMINANCE_ALPHA}. | |
17405 | ||
17406 | @item @var{type} | |
17407 | Specifies the data type of the pixel data. The following symbolic values | |
17408 | are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, | |
17409 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
17410 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
17411 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
17412 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
17413 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
17414 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
17415 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
17416 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
17417 | ||
17418 | @item @var{data} | |
17419 | Specifies a pointer to the image data in memory. | |
17420 | ||
17421 | @end table | |
17422 | ||
8925f36f AW |
17423 | Texturing maps a portion of a specified texture image onto each |
17424 | graphical primitive for which texturing is enabled. To enable and | |
17425 | disable three-dimensional texturing, call @code{glEnable} and | |
17426 | @code{glDisable} with argument @code{GL_TEXTURE_3D}. | |
17427 | ||
17428 | @code{glTexSubImage3D} redefines a contiguous subregion of an existing | |
17429 | three-dimensional texture image. The texels referenced by @var{data} | |
17430 | replace the portion of the existing texture array with x indices | |
3c9b6116 AW |
17431 | @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive, y indices |
17432 | @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive, and z | |
17433 | indices @var{zoffset} and @r{@var{zoffset}+@var{depth}-1}, inclusive. | |
17434 | This region may not include any texels outside the range of the texture | |
17435 | array as it was originally specified. It is not an error to specify a | |
17436 | subtexture with zero width, height, or depth but such a specification | |
17437 | has no effect. | |
8925f36f AW |
17438 | |
17439 | If a non-zero named buffer object is bound to the | |
17440 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
17441 | texture image is specified, @var{data} is treated as a byte offset into | |
17442 | the buffer object's data store. | |
17443 | ||
8925f36f AW |
17444 | @code{GL_INVALID_ENUM} is generated if /@var{target} is not |
17445 | @code{GL_TEXTURE_3D}. | |
17446 | ||
17447 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
17448 | format constant. | |
17449 | ||
17450 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
17451 | constant. | |
17452 | ||
17453 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
17454 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
17455 | ||
17456 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
17457 | ||
17458 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 | 17459 | @r{@var{log}_2}@var{max}, where @var{max} is the returned value of |
8925f36f AW |
17460 | @code{GL_MAX_TEXTURE_SIZE}. |
17461 | ||
3c9b6116 AW |
17462 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, |
17463 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, | |
17464 | @r{@var{yoffset}<-@var{b}}, or | |
17465 | @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, or | |
17466 | @r{@var{zoffset}<-@var{b}}, or | |
17467 | @r{(@var{zoffset}+@var{depth},)>(@var{d}-@var{b},)}, where @r{@var{w}} | |
17468 | is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the | |
17469 | @code{GL_TEXTURE_HEIGHT}, @r{@var{d}} is the @code{GL_TEXTURE_DEPTH} and | |
17470 | @r{@var{b}} is the border width of the texture image being modified. | |
17471 | Note that @r{@var{w}}, @r{@var{h}}, and @r{@var{d}} include twice the | |
17472 | border width. | |
8925f36f AW |
17473 | |
17474 | @code{GL_INVALID_VALUE} is generated if @var{width}, @var{height}, or | |
17475 | @var{depth} is less than 0. | |
17476 | ||
17477 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
17478 | been defined by a previous @code{glTexImage3D} operation. | |
17479 | ||
17480 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
17481 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
17482 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
17483 | and @var{format} is not @code{GL_RGB}. | |
17484 | ||
17485 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
17486 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
17487 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
17488 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
17489 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
17490 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
17491 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
17492 | ||
17493 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
17494 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
17495 | object's data store is currently mapped. | |
17496 | ||
17497 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
17498 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
17499 | would be unpacked from the buffer object such that the memory reads | |
17500 | required would exceed the data store size. | |
17501 | ||
17502 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
17503 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
17504 | is not evenly divisible into the number of bytes needed to store in | |
17505 | memory a datum indicated by @var{type}. | |
17506 | ||
17507 | @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage3D} is | |
17508 | executed between the execution of @code{glBegin} and the corresponding | |
17509 | execution of @code{glEnd}. | |
17510 | ||
bb894c9d | 17511 | @end deftypefun |
8925f36f | 17512 | |
bb894c9d | 17513 | @deftypefun void glTranslated x y z |
3c9b6116 AW |
17514 | Multiply the current matrix by a translation matrix. |
17515 | ||
8925f36f AW |
17516 | @table @asis |
17517 | @item @var{x} | |
17518 | @itemx @var{y} | |
17519 | @itemx @var{z} | |
17520 | Specify the @var{x}, @var{y}, and @var{z} coordinates of a translation | |
17521 | vector. | |
17522 | ||
17523 | @end table | |
17524 | ||
8925f36f | 17525 | @code{glTranslate} produces a translation by |
3c9b6116 | 17526 | @r{(@var{x},@var{y}@var{z})}. The current matrix (see |
8925f36f AW |
17527 | @code{glMatrixMode}) is multiplied by this translation matrix, with the |
17528 | product replacing the current matrix, as if @code{glMultMatrix} were | |
17529 | called with the following matrix for its argument: | |
17530 | ||
3c9b6116 | 17531 | @r{((1 0 0 @var{x}), (0 1 0 @var{y}), (0 0 1 @var{z}), (0 0 0 1),)} |
8925f36f AW |
17532 | |
17533 | ||
17534 | ||
17535 | If the matrix mode is either @code{GL_MODELVIEW} or | |
17536 | @code{GL_PROJECTION}, all objects drawn after a call to | |
17537 | @code{glTranslate} are translated. | |
17538 | ||
17539 | Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the | |
17540 | untranslated coordinate system. | |
17541 | ||
8925f36f AW |
17542 | @code{GL_INVALID_OPERATION} is generated if @code{glTranslate} is |
17543 | executed between the execution of @code{glBegin} and the corresponding | |
17544 | execution of @code{glEnd}. | |
17545 | ||
bb894c9d | 17546 | @end deftypefun |
8925f36f | 17547 | |
bb894c9d AW |
17548 | @deftypefun void glUniform1f location v0 |
17549 | @deftypefunx void glUniform2f location v0 v1 | |
17550 | @deftypefunx void glUniform3f location v0 v1 v2 | |
17551 | @deftypefunx void glUniform4f location v0 v1 v2 v3 | |
17552 | @deftypefunx void glUniform1i location v0 | |
17553 | @deftypefunx void glUniform2i location v0 v1 | |
17554 | @deftypefunx void glUniform3i location v0 v1 v2 | |
17555 | @deftypefunx void glUniform4i location v0 v1 v2 v3 | |
3c9b6116 AW |
17556 | Specify the value of a uniform variable for the current program object. |
17557 | ||
8925f36f AW |
17558 | @table @asis |
17559 | @item @var{location} | |
17560 | Specifies the location of the uniform variable to be modified. | |
17561 | ||
17562 | @item @var{v0}, @var{v1}, @var{v2}, @var{v3} | |
17563 | Specifies the new values to be used for the specified uniform variable. | |
17564 | ||
17565 | @end table | |
17566 | ||
8925f36f AW |
17567 | @code{glUniform} modifies the value of a uniform variable or a uniform |
17568 | variable array. The location of the uniform variable to be modified is | |
17569 | specified by @var{location}, which should be a value returned by | |
17570 | @code{glGetUniformLocation}. @code{glUniform} operates on the program | |
17571 | object that was made part of current state by calling | |
17572 | @code{glUseProgram}. | |
17573 | ||
17574 | The commands @code{glUniform@{1|2|3|4@}@{f|i@}} are used to change the | |
17575 | value of the uniform variable specified by @var{location} using the | |
17576 | values passed as arguments. The number specified in the command should | |
17577 | match the number of components in the data type of the specified uniform | |
17578 | variable (e.g., @code{1} for float, int, bool; @code{2} for vec2, ivec2, | |
17579 | bvec2, etc.). The suffix @code{f} indicates that floating-point values | |
17580 | are being passed; the suffix @code{i} indicates that integer values are | |
17581 | being passed, and this type should also match the data type of the | |
17582 | specified uniform variable. The @code{i} variants of this function | |
17583 | should be used to provide values for uniform variables defined as int, | |
17584 | ivec2, ivec3, ivec4, or arrays of these. The @code{f} variants should be | |
17585 | used to provide values for uniform variables of type float, vec2, vec3, | |
17586 | vec4, or arrays of these. Either the @code{i} or the @code{f} variants | |
17587 | may be used to provide values for uniform variables of type bool, bvec2, | |
17588 | bvec3, bvec4, or arrays of these. The uniform variable will be set to | |
17589 | false if the input value is 0 or 0.0f, and it will be set to true | |
17590 | otherwise. | |
17591 | ||
17592 | All active uniform variables defined in a program object are initialized | |
17593 | to 0 when the program object is linked successfully. They retain the | |
17594 | values assigned to them by a call to @code{glUniform } until the next | |
17595 | successful link operation occurs on the program object, when they are | |
17596 | once again initialized to 0. | |
17597 | ||
17598 | The commands @code{glUniform@{1|2|3|4@}@{f|i@}v} can be used to modify a | |
17599 | single uniform variable or a uniform variable array. These commands pass | |
17600 | a count and a pointer to the values to be loaded into a uniform variable | |
17601 | or a uniform variable array. A count of 1 should be used if modifying | |
17602 | the value of a single uniform variable, and a count of 1 or greater can | |
17603 | be used to modify an entire array or part of an array. When loading | |
17604 | @var{n} elements starting at an arbitrary position @var{m} in a uniform | |
17605 | variable array, elements @var{m} + @var{n} - 1 in the array will be | |
17606 | replaced with the new values. If @var{m} + @var{n} - 1 is larger than | |
17607 | the size of the uniform variable array, values for all array elements | |
17608 | beyond the end of the array will be ignored. The number specified in the | |
17609 | name of the command indicates the number of components for each element | |
17610 | in @var{value}, and it should match the number of components in the data | |
17611 | type of the specified uniform variable (e.g., @code{1} for float, int, | |
17612 | bool; @code{2} for vec2, ivec2, bvec2, etc.). The data type specified in | |
17613 | the name of the command must match the data type for the specified | |
17614 | uniform variable as described previously for | |
17615 | @code{glUniform@{1|2|3|4@}@{f|i@}}. | |
17616 | ||
17617 | For uniform variable arrays, each element of the array is considered to | |
17618 | be of the type indicated in the name of the command (e.g., | |
17619 | @code{glUniform3f} or @code{glUniform3fv} can be used to load a uniform | |
17620 | variable array of type vec3). The number of elements of the uniform | |
17621 | variable array to be modified is specified by @var{count} | |
17622 | ||
17623 | The commands @code{glUniformMatrix@{2|3|4|2x3|3x2|2x4|4x2|3x4|4x3@}fv} | |
17624 | are used to modify a matrix or an array of matrices. The numbers in the | |
17625 | command name are interpreted as the dimensionality of the matrix. The | |
17626 | number @code{2} indicates a 2 × 2 matrix (i.e., 4 values), the number | |
17627 | @code{3} indicates a 3 × 3 matrix (i.e., 9 values), and the number | |
17628 | @code{4} indicates a 4 × 4 matrix (i.e., 16 values). Non-square matrix | |
17629 | dimensionality is explicit, with the first number representing the | |
17630 | number of columns and the second number representing the number of rows. | |
17631 | For example, @code{2x4} indicates a 2 × 4 matrix with 2 columns and 4 | |
17632 | rows (i.e., 8 values). If @var{transpose} is @code{GL_FALSE}, each | |
17633 | matrix is assumed to be supplied in column major order. If | |
17634 | @var{transpose} is @code{GL_TRUE}, each matrix is assumed to be supplied | |
17635 | in row major order. The @var{count} argument indicates the number of | |
17636 | matrices to be passed. A count of 1 should be used if modifying the | |
17637 | value of a single matrix, and a count greater than 1 can be used to | |
17638 | modify an array of matrices. | |
17639 | ||
8925f36f AW |
17640 | @code{GL_INVALID_OPERATION} is generated if there is no current program |
17641 | object. | |
17642 | ||
17643 | @code{GL_INVALID_OPERATION} is generated if the size of the uniform | |
17644 | variable declared in the shader does not match the size indicated by the | |
17645 | @code{glUniform} command. | |
17646 | ||
17647 | @code{GL_INVALID_OPERATION} is generated if one of the integer variants | |
17648 | of this function is used to load a uniform variable of type float, vec2, | |
17649 | vec3, vec4, or an array of these, or if one of the floating-point | |
17650 | variants of this function is used to load a uniform variable of type | |
17651 | int, ivec2, ivec3, or ivec4, or an array of these. | |
17652 | ||
17653 | @code{GL_INVALID_OPERATION} is generated if @var{location} is an invalid | |
17654 | uniform location for the current program object and @var{location} is | |
17655 | not equal to -1. | |
17656 | ||
17657 | @code{GL_INVALID_VALUE} is generated if @var{count} is less than 0. | |
17658 | ||
17659 | @code{GL_INVALID_OPERATION} is generated if @var{count} is greater than | |
17660 | 1 and the indicated uniform variable is not an array variable. | |
17661 | ||
17662 | @code{GL_INVALID_OPERATION} is generated if a sampler is loaded using a | |
17663 | command other than @code{glUniform1i} and @code{glUniform1iv}. | |
17664 | ||
17665 | @code{GL_INVALID_OPERATION} is generated if @code{glUniform} is executed | |
17666 | between the execution of @code{glBegin} and the corresponding execution | |
17667 | of @code{glEnd}. | |
17668 | ||
bb894c9d | 17669 | @end deftypefun |
8925f36f | 17670 | |
bb894c9d | 17671 | @deftypefun void glUseProgram program |
3c9b6116 AW |
17672 | Installs a program object as part of current rendering state. |
17673 | ||
8925f36f AW |
17674 | @table @asis |
17675 | @item @var{program} | |
17676 | Specifies the handle of the program object whose executables are to be | |
17677 | used as part of current rendering state. | |
17678 | ||
17679 | @end table | |
17680 | ||
8925f36f AW |
17681 | @code{glUseProgram} installs the program object specified by |
17682 | @var{program} as part of current rendering state. One or more | |
17683 | executables are created in a program object by successfully attaching | |
17684 | shader objects to it with @code{glAttachShader}, successfully compiling | |
17685 | the shader objects with @code{glCompileShader}, and successfully linking | |
17686 | the program object with @code{glLinkProgram}. | |
17687 | ||
17688 | A program object will contain an executable that will run on the vertex | |
17689 | processor if it contains one or more shader objects of type | |
17690 | @code{GL_VERTEX_SHADER} that have been successfully compiled and linked. | |
17691 | Similarly, a program object will contain an executable that will run on | |
17692 | the fragment processor if it contains one or more shader objects of type | |
17693 | @code{GL_FRAGMENT_SHADER} that have been successfully compiled and | |
17694 | linked. | |
17695 | ||
17696 | Successfully installing an executable on a programmable processor will | |
17697 | cause the corresponding fixed functionality of OpenGL to be disabled. | |
17698 | Specifically, if an executable is installed on the vertex processor, the | |
17699 | OpenGL fixed functionality will be disabled as follows. | |
17700 | ||
17701 | @itemize | |
17702 | @item | |
17703 | The modelview matrix is not applied to vertex coordinates. | |
17704 | ||
17705 | @item | |
17706 | The projection matrix is not applied to vertex coordinates. | |
17707 | ||
17708 | @item | |
17709 | The texture matrices are not applied to texture coordinates. | |
17710 | ||
17711 | @item | |
17712 | Normals are not transformed to eye coordinates. | |
17713 | ||
17714 | @item | |
17715 | Normals are not rescaled or normalized. | |
17716 | ||
17717 | @item | |
17718 | Normalization of @code{GL_AUTO_NORMAL} evaluated normals is not | |
17719 | performed. | |
17720 | ||
17721 | @item | |
17722 | Texture coordinates are not generated automatically. | |
17723 | ||
17724 | @item | |
17725 | Per-vertex lighting is not performed. | |
17726 | ||
17727 | @item | |
17728 | Color material computations are not performed. | |
17729 | ||
17730 | @item | |
17731 | Color index lighting is not performed. | |
17732 | ||
17733 | @item | |
17734 | This list also applies when setting the current raster position. | |
17735 | ||
17736 | @end itemize | |
17737 | ||
17738 | The executable that is installed on the vertex processor is expected to | |
17739 | implement any or all of the desired functionality from the preceding | |
17740 | list. Similarly, if an executable is installed on the fragment | |
17741 | processor, the OpenGL fixed functionality will be disabled as follows. | |
17742 | ||
17743 | @itemize | |
17744 | @item | |
17745 | Texture environment and texture functions are not applied. | |
17746 | ||
17747 | @item | |
17748 | Texture application is not applied. | |
17749 | ||
17750 | @item | |
17751 | Color sum is not applied. | |
17752 | ||
17753 | @item | |
17754 | Fog is not applied. | |
17755 | ||
17756 | @end itemize | |
17757 | ||
17758 | Again, the fragment shader that is installed is expected to implement | |
17759 | any or all of the desired functionality from the preceding list. | |
17760 | ||
17761 | While a program object is in use, applications are free to modify | |
17762 | attached shader objects, compile attached shader objects, attach | |
17763 | additional shader objects, and detach or delete shader objects. None of | |
17764 | these operations will affect the executables that are part of the | |
17765 | current state. However, relinking the program object that is currently | |
17766 | in use will install the program object as part of the current rendering | |
17767 | state if the link operation was successful (see @code{glLinkProgram} ). | |
17768 | If the program object currently in use is relinked unsuccessfully, its | |
17769 | link status will be set to @code{GL_FALSE}, but the executables and | |
17770 | associated state will remain part of the current state until a | |
17771 | subsequent call to @code{glUseProgram} removes it from use. After it is | |
17772 | removed from use, it cannot be made part of current state until it has | |
17773 | been successfully relinked. | |
17774 | ||
17775 | If @var{program} contains shader objects of type @code{GL_VERTEX_SHADER} | |
17776 | but it does not contain shader objects of type | |
17777 | @code{GL_FRAGMENT_SHADER}, an executable will be installed on the vertex | |
17778 | processor, but fixed functionality will be used for fragment processing. | |
17779 | Similarly, if @var{program} contains shader objects of type | |
17780 | @code{GL_FRAGMENT_SHADER} but it does not contain shader objects of type | |
17781 | @code{GL_VERTEX_SHADER}, an executable will be installed on the fragment | |
17782 | processor, but fixed functionality will be used for vertex processing. | |
17783 | If @var{program} is 0, the programmable processors will be disabled, and | |
17784 | fixed functionality will be used for both vertex and fragment | |
17785 | processing. | |
17786 | ||
8925f36f AW |
17787 | @code{GL_INVALID_VALUE} is generated if @var{program} is neither 0 nor a |
17788 | value generated by OpenGL. | |
17789 | ||
17790 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
17791 | program object. | |
17792 | ||
17793 | @code{GL_INVALID_OPERATION} is generated if @var{program} could not be | |
17794 | made part of current state. | |
17795 | ||
17796 | @code{GL_INVALID_OPERATION} is generated if @code{glUseProgram} is | |
17797 | executed between the execution of @code{glBegin} and the corresponding | |
17798 | execution of @code{glEnd}. | |
17799 | ||
bb894c9d | 17800 | @end deftypefun |
8925f36f | 17801 | |
bb894c9d | 17802 | @deftypefun void glValidateProgram program |
3c9b6116 AW |
17803 | Validates a program object. |
17804 | ||
8925f36f AW |
17805 | @table @asis |
17806 | @item @var{program} | |
17807 | Specifies the handle of the program object to be validated. | |
17808 | ||
17809 | @end table | |
17810 | ||
8925f36f AW |
17811 | @code{glValidateProgram} checks to see whether the executables contained |
17812 | in @var{program} can execute given the current OpenGL state. The | |
17813 | information generated by the validation process will be stored in | |
17814 | @var{program}'s information log. The validation information may consist | |
17815 | of an empty string, or it may be a string containing information about | |
17816 | how the current program object interacts with the rest of current OpenGL | |
17817 | state. This provides a way for OpenGL implementers to convey more | |
17818 | information about why the current program is inefficient, suboptimal, | |
17819 | failing to execute, and so on. | |
17820 | ||
17821 | The status of the validation operation will be stored as part of the | |
17822 | program object's state. This value will be set to @code{GL_TRUE} if the | |
17823 | validation succeeded, and @code{GL_FALSE} otherwise. It can be queried | |
17824 | by calling @code{glGetProgram} with arguments @var{program} and | |
17825 | @code{GL_VALIDATE_STATUS}. If validation is successful, @var{program} is | |
17826 | guaranteed to execute given the current state. Otherwise, @var{program} | |
17827 | is guaranteed to not execute. | |
17828 | ||
17829 | This function is typically useful only during application development. | |
17830 | The informational string stored in the information log is completely | |
17831 | implementation dependent; therefore, an application should not expect | |
17832 | different OpenGL implementations to produce identical information | |
17833 | strings. | |
17834 | ||
8925f36f AW |
17835 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
17836 | generated by OpenGL. | |
17837 | ||
17838 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
17839 | program object. | |
17840 | ||
17841 | @code{GL_INVALID_OPERATION} is generated if @code{glValidateProgram} is | |
17842 | executed between the execution of @code{glBegin} and the corresponding | |
17843 | execution of @code{glEnd}. | |
17844 | ||
bb894c9d | 17845 | @end deftypefun |
8925f36f | 17846 | |
bb894c9d | 17847 | @deftypefun void glVertexAttribPointer index size type normalized stride pointer |
3c9b6116 AW |
17848 | Define an array of generic vertex attribute data. |
17849 | ||
8925f36f AW |
17850 | @table @asis |
17851 | @item @var{index} | |
17852 | Specifies the index of the generic vertex attribute to be modified. | |
17853 | ||
17854 | @item @var{size} | |
17855 | Specifies the number of components per generic vertex attribute. Must be | |
17856 | 1, 2, 3, or 4. The initial value is 4. | |
17857 | ||
17858 | @item @var{type} | |
17859 | Specifies the data type of each component in the array. Symbolic | |
17860 | constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, | |
17861 | @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT}, | |
17862 | @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is | |
17863 | @code{GL_FLOAT}. | |
17864 | ||
17865 | @item @var{normalized} | |
17866 | Specifies whether fixed-point data values should be normalized | |
17867 | (@code{GL_TRUE}) or converted directly as fixed-point values | |
17868 | (@code{GL_FALSE}) when they are accessed. | |
17869 | ||
17870 | @item @var{stride} | |
17871 | Specifies the byte offset between consecutive generic vertex attributes. | |
17872 | If @var{stride} is 0, the generic vertex attributes are understood to be | |
17873 | tightly packed in the array. The initial value is 0. | |
17874 | ||
17875 | @item @var{pointer} | |
17876 | Specifies a pointer to the first component of the first generic vertex | |
17877 | attribute in the array. The initial value is 0. | |
17878 | ||
17879 | @end table | |
17880 | ||
8925f36f AW |
17881 | @code{glVertexAttribPointer} specifies the location and data format of |
17882 | the array of generic vertex attributes at index @var{index} to use when | |
17883 | rendering. @var{size} specifies the number of components per attribute | |
17884 | and must be 1, 2, 3, or 4. @var{type} specifies the data type of each | |
17885 | component, and @var{stride} specifies the byte stride from one attribute | |
17886 | to the next, allowing vertices and attributes to be packed into a single | |
17887 | array or stored in separate arrays. If set to @code{GL_TRUE}, | |
17888 | @var{normalized} indicates that values stored in an integer format are | |
17889 | to be mapped to the range [-1,1] (for signed values) or [0,1] (for | |
17890 | unsigned values) when they are accessed and converted to floating point. | |
17891 | Otherwise, values will be converted to floats directly without | |
17892 | normalization. | |
17893 | ||
17894 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
17895 | target (see @code{glBindBuffer}) while a generic vertex attribute array | |
17896 | is specified, @var{pointer} is treated as a byte offset into the buffer | |
17897 | object's data store. Also, the buffer object binding | |
17898 | (@code{GL_ARRAY_BUFFER_BINDING}) is saved as generic vertex attribute | |
17899 | array client-side state (@code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING}) | |
17900 | for index @var{index}. | |
17901 | ||
17902 | When a generic vertex attribute array is specified, @var{size}, | |
17903 | @var{type}, @var{normalized}, @var{stride}, and @var{pointer} are saved | |
17904 | as client-side state, in addition to the current vertex array buffer | |
17905 | object binding. | |
17906 | ||
17907 | To enable and disable a generic vertex attribute array, call | |
17908 | @code{glEnableVertexAttribArray} and @code{glDisableVertexAttribArray} | |
17909 | with @var{index}. If enabled, the generic vertex attribute array is used | |
17910 | when @code{glArrayElement}, @code{glDrawArrays}, | |
17911 | @code{glMultiDrawArrays}, @code{glDrawElements}, | |
17912 | @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called. | |
17913 | ||
8925f36f AW |
17914 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or |
17915 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
17916 | ||
17917 | @code{GL_INVALID_VALUE} is generated if @var{size} is not 1, 2, 3, or 4. | |
17918 | ||
17919 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted | |
17920 | value. | |
17921 | ||
17922 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
17923 | ||
bb894c9d AW |
17924 | @end deftypefun |
17925 | ||
17926 | @deftypefun void glVertexAttrib1s index v0 | |
17927 | @deftypefunx void glVertexAttrib1d index v0 | |
17928 | @deftypefunx void glVertexAttrib2s index v0 v1 | |
17929 | @deftypefunx void glVertexAttrib2d index v0 v1 | |
17930 | @deftypefunx void glVertexAttrib3s index v0 v1 v2 | |
17931 | @deftypefunx void glVertexAttrib3d index v0 v1 v2 | |
17932 | @deftypefunx void glVertexAttrib4s index v0 v1 v2 v3 | |
17933 | @deftypefunx void glVertexAttrib4d index v0 v1 v2 v3 | |
17934 | @deftypefunx void glVertexAttrib4Nub index v0 v1 v2 v3 | |
3c9b6116 AW |
17935 | Specifies the value of a generic vertex attribute. |
17936 | ||
8925f36f AW |
17937 | @table @asis |
17938 | @item @var{index} | |
17939 | Specifies the index of the generic vertex attribute to be modified. | |
17940 | ||
17941 | @item @var{v0}, @var{v1}, @var{v2}, @var{v3} | |
17942 | Specifies the new values to be used for the specified vertex attribute. | |
17943 | ||
17944 | @end table | |
17945 | ||
8925f36f AW |
17946 | OpenGL defines a number of standard vertex attributes that applications |
17947 | can modify with standard API entry points (color, normal, texture | |
17948 | coordinates, etc.). The @code{glVertexAttrib} family of entry points | |
17949 | allows an application to pass generic vertex attributes in numbered | |
17950 | locations. | |
17951 | ||
17952 | Generic attributes are defined as four-component values that are | |
17953 | organized into an array. The first entry of this array is numbered 0, | |
17954 | and the size of the array is specified by the implementation-dependent | |
17955 | constant @code{GL_MAX_VERTEX_ATTRIBS}. Individual elements of this array | |
17956 | can be modified with a @code{glVertexAttrib} call that specifies the | |
17957 | index of the element to be modified and a value for that element. | |
17958 | ||
17959 | These commands can be used to specify one, two, three, or all four | |
17960 | components of the generic vertex attribute specified by @var{index}. A | |
17961 | @code{1} in the name of the command indicates that only one value is | |
17962 | passed, and it will be used to modify the first component of the generic | |
17963 | vertex attribute. The second and third components will be set to 0, and | |
17964 | the fourth component will be set to 1. Similarly, a @code{2} in the name | |
17965 | of the command indicates that values are provided for the first two | |
17966 | components, the third component will be set to 0, and the fourth | |
17967 | component will be set to 1. A @code{3} in the name of the command | |
17968 | indicates that values are provided for the first three components and | |
17969 | the fourth component will be set to 1, whereas a @code{4} in the name | |
17970 | indicates that values are provided for all four components. | |
17971 | ||
17972 | The letters @code{s}, @code{f}, @code{i}, @code{d}, @code{ub}, | |
17973 | @code{us}, and @code{ui} indicate whether the arguments are of type | |
17974 | short, float, int, double, unsigned byte, unsigned short, or unsigned | |
17975 | int. When @code{v} is appended to the name, the commands can take a | |
17976 | pointer to an array of such values. The commands containing @code{N} | |
17977 | indicate that the arguments will be passed as fixed-point values that | |
17978 | are scaled to a normalized range according to the component conversion | |
17979 | rules defined by the OpenGL specification. Signed values are understood | |
17980 | to represent fixed-point values in the range [-1,1], and unsigned values | |
17981 | are understood to represent fixed-point values in the range [0,1]. | |
17982 | ||
17983 | OpenGL Shading Language attribute variables are allowed to be of type | |
17984 | mat2, mat3, or mat4. Attributes of these types may be loaded using the | |
17985 | @code{glVertexAttrib} entry points. Matrices must be loaded into | |
17986 | successive generic attribute slots in column major order, with one | |
17987 | column of the matrix in each generic attribute slot. | |
17988 | ||
17989 | A user-defined attribute variable declared in a vertex shader can be | |
17990 | bound to a generic attribute index by calling | |
17991 | @code{glBindAttribLocation}. This allows an application to use more | |
17992 | descriptive variable names in a vertex shader. A subsequent change to | |
17993 | the specified generic vertex attribute will be immediately reflected as | |
17994 | a change to the corresponding attribute variable in the vertex shader. | |
17995 | ||
17996 | The binding between a generic vertex attribute index and a user-defined | |
17997 | attribute variable in a vertex shader is part of the state of a program | |
17998 | object, but the current value of the generic vertex attribute is not. | |
17999 | The value of each generic vertex attribute is part of current state, | |
18000 | just like standard vertex attributes, and it is maintained even if a | |
18001 | different program object is used. | |
18002 | ||
18003 | An application may freely modify generic vertex attributes that are not | |
18004 | bound to a named vertex shader attribute variable. These values are | |
18005 | simply maintained as part of current state and will not be accessed by | |
18006 | the vertex shader. If a generic vertex attribute bound to an attribute | |
18007 | variable in a vertex shader is not updated while the vertex shader is | |
18008 | executing, the vertex shader will repeatedly use the current value for | |
18009 | the generic vertex attribute. | |
18010 | ||
18011 | The generic vertex attribute with index 0 is the same as the vertex | |
18012 | position attribute previously defined by OpenGL. A @code{glVertex2}, | |
18013 | @code{glVertex3}, or @code{glVertex4} command is completely equivalent | |
18014 | to the corresponding @code{glVertexAttrib} command with an index | |
18015 | argument of 0. A vertex shader can access generic vertex attribute 0 by | |
18016 | using the built-in attribute variable @var{gl_Vertex}. There are no | |
18017 | current values for generic vertex attribute 0. This is the only generic | |
18018 | vertex attribute with this property; calls to set other standard vertex | |
18019 | attributes can be freely mixed with calls to set any of the other | |
18020 | generic vertex attributes. | |
18021 | ||
8925f36f AW |
18022 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or |
18023 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
18024 | ||
bb894c9d | 18025 | @end deftypefun |
8925f36f | 18026 | |
bb894c9d | 18027 | @deftypefun void glVertexPointer size type stride pointer |
3c9b6116 AW |
18028 | Define an array of vertex data. |
18029 | ||
8925f36f AW |
18030 | @table @asis |
18031 | @item @var{size} | |
18032 | Specifies the number of coordinates per vertex. Must be 2, 3, or 4. The | |
18033 | initial value is 4. | |
18034 | ||
18035 | @item @var{type} | |
18036 | Specifies the data type of each coordinate in the array. Symbolic | |
18037 | constants @code{GL_SHORT}, @code{GL_INT}, @code{GL_FLOAT}, or | |
18038 | @code{GL_DOUBLE} are accepted. The initial value is @code{GL_FLOAT}. | |
18039 | ||
18040 | @item @var{stride} | |
18041 | Specifies the byte offset between consecutive vertices. If @var{stride} | |
18042 | is 0, the vertices are understood to be tightly packed in the array. The | |
18043 | initial value is 0. | |
18044 | ||
18045 | @item @var{pointer} | |
18046 | Specifies a pointer to the first coordinate of the first vertex in the | |
18047 | array. The initial value is 0. | |
18048 | ||
18049 | @end table | |
18050 | ||
8925f36f AW |
18051 | @code{glVertexPointer} specifies the location and data format of an |
18052 | array of vertex coordinates to use when rendering. @var{size} specifies | |
18053 | the number of coordinates per vertex, and must be 2, 3, or 4. @var{type} | |
18054 | specifies the data type of each coordinate, and @var{stride} specifies | |
18055 | the byte stride from one vertex to the next, allowing vertices and | |
18056 | attributes to be packed into a single array or stored in separate | |
18057 | arrays. (Single-array storage may be more efficient on some | |
18058 | implementations; see @code{glInterleavedArrays}.) | |
18059 | ||
18060 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
18061 | target (see @code{glBindBuffer}) while a vertex array is specified, | |
18062 | @var{pointer} is treated as a byte offset into the buffer object's data | |
18063 | store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING}) | |
18064 | is saved as vertex array client-side state | |
18065 | (@code{GL_VERTEX_ARRAY_BUFFER_BINDING}). | |
18066 | ||
18067 | When a vertex array is specified, @var{size}, @var{type}, @var{stride}, | |
18068 | and @var{pointer} are saved as client-side state, in addition to the | |
18069 | current vertex array buffer object binding. | |
18070 | ||
18071 | To enable and disable the vertex array, call @code{glEnableClientState} | |
18072 | and @code{glDisableClientState} with the argument | |
18073 | @code{GL_VERTEX_ARRAY}. If enabled, the vertex array is used when | |
18074 | @code{glArrayElement}, @code{glDrawArrays}, @code{glMultiDrawArrays}, | |
18075 | @code{glDrawElements}, @code{glMultiDrawElements}, or | |
18076 | @code{glDrawRangeElements} is called. | |
18077 | ||
8925f36f AW |
18078 | @code{GL_INVALID_VALUE} is generated if @var{size} is not 2, 3, or 4. |
18079 | ||
18080 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted | |
18081 | value. | |
18082 | ||
18083 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
18084 | ||
bb894c9d | 18085 | @end deftypefun |
8925f36f | 18086 | |
bb894c9d AW |
18087 | @deftypefun void glVertex2i x y |
18088 | @deftypefunx void glVertex2d x y | |
18089 | @deftypefunx void glVertex3i x y z | |
18090 | @deftypefunx void glVertex3d x y z | |
18091 | @deftypefunx void glVertex4i x y z w | |
18092 | @deftypefunx void glVertex4d x y z w | |
3c9b6116 AW |
18093 | Specify a vertex. |
18094 | ||
8925f36f AW |
18095 | @table @asis |
18096 | @item @var{x} | |
18097 | @itemx @var{y} | |
18098 | @itemx @var{z} | |
18099 | @itemx @var{w} | |
18100 | Specify @var{x}, @var{y}, @var{z}, and @var{w} coordinates of a vertex. | |
18101 | Not all parameters are present in all forms of the command. | |
18102 | ||
18103 | @end table | |
18104 | ||
8925f36f AW |
18105 | @code{glVertex} commands are used within @code{glBegin}/@code{glEnd} |
18106 | pairs to specify point, line, and polygon vertices. The current color, | |
18107 | normal, texture coordinates, and fog coordinate are associated with the | |
18108 | vertex when @code{glVertex} is called. | |
18109 | ||
3c9b6116 AW |
18110 | When only @r{@var{x}} and @r{@var{y}} are specified, @r{@var{z}} |
18111 | defaults to 0 and @r{@var{w}} defaults to 1. When @r{@var{x}}, | |
18112 | @r{@var{y}}, and @r{@var{z}} are specified, @r{@var{w}} defaults to 1. | |
8925f36f | 18113 | |
bb894c9d | 18114 | @end deftypefun |
8925f36f | 18115 | |
bb894c9d | 18116 | @deftypefun void glViewport x y width height |
3c9b6116 AW |
18117 | Set the viewport. |
18118 | ||
8925f36f AW |
18119 | @table @asis |
18120 | @item @var{x} | |
18121 | @itemx @var{y} | |
18122 | Specify the lower left corner of the viewport rectangle, in pixels. The | |
18123 | initial value is (0,0). | |
18124 | ||
18125 | @item @var{width} | |
18126 | @itemx @var{height} | |
18127 | Specify the width and height of the viewport. When a GL context is first | |
18128 | attached to a window, @var{width} and @var{height} are set to the | |
18129 | dimensions of that window. | |
18130 | ||
18131 | @end table | |
18132 | ||
3c9b6116 AW |
18133 | @code{glViewport} specifies the affine transformation of @r{@var{x}} and |
18134 | @r{@var{y}} from normalized device coordinates to window coordinates. | |
18135 | Let @r{(@var{x}_@var{nd},@var{y}_@var{nd})} be normalized device | |
18136 | coordinates. Then the window coordinates | |
18137 | @r{(@var{x}_@var{w},@var{y}_@var{w})} are computed as follows: | |
8925f36f | 18138 | |
3c9b6116 | 18139 | @r{@var{x}_@var{w}=(@var{x}_@var{nd}+1,)(@var{width}/2,)+@var{x}} |
8925f36f | 18140 | |
3c9b6116 | 18141 | @r{@var{y}_@var{w}=(@var{y}_@var{nd}+1,)(@var{height}/2,)+@var{y}} |
8925f36f AW |
18142 | |
18143 | Viewport width and height are silently clamped to a range that depends | |
18144 | on the implementation. To query this range, call @code{glGet} with | |
18145 | argument @code{GL_MAX_VIEWPORT_DIMS}. | |
18146 | ||
8925f36f AW |
18147 | @code{GL_INVALID_VALUE} is generated if either @var{width} or |
18148 | @var{height} is negative. | |
18149 | ||
18150 | @code{GL_INVALID_OPERATION} is generated if @code{glViewport} is | |
18151 | executed between the execution of @code{glBegin} and the corresponding | |
18152 | execution of @code{glEnd}. | |
18153 | ||
bb894c9d | 18154 | @end deftypefun |
8925f36f | 18155 | |
bb894c9d AW |
18156 | @deftypefun void glWindowPos2i x y |
18157 | @deftypefunx void glWindowPos2d x y | |
18158 | @deftypefunx void glWindowPos3i x y z | |
18159 | @deftypefunx void glWindowPos3d x y z | |
3c9b6116 AW |
18160 | Specify the raster position in window coordinates for pixel operations. |
18161 | ||
8925f36f AW |
18162 | @table @asis |
18163 | @item @var{x} | |
18164 | @itemx @var{y} | |
18165 | @itemx @var{z} | |
3c9b6116 AW |
18166 | Specify the @r{@var{x}}, @r{@var{y}}, @r{@var{z}} coordinates for the |
18167 | raster position. | |
8925f36f AW |
18168 | |
18169 | @end table | |
18170 | ||
8925f36f AW |
18171 | The GL maintains a 3D position in window coordinates. This position, |
18172 | called the raster position, is used to position pixel and bitmap write | |
18173 | operations. It is maintained with subpixel accuracy. See | |
18174 | @code{glBitmap}, @code{glDrawPixels}, and @code{glCopyPixels}. | |
18175 | ||
3c9b6116 AW |
18176 | @code{glWindowPos2} specifies the @r{@var{x}} and @r{@var{y}} |
18177 | coordinates, while @r{@var{z}} is implicitly set to 0. | |
18178 | @code{glWindowPos3} specifies all three coordinates. The @r{@var{w}} | |
8925f36f AW |
18179 | coordinate of the current raster position is always set to 1.0. |
18180 | ||
3c9b6116 AW |
18181 | @code{glWindowPos} directly updates the @r{@var{x}} and @r{@var{y}} |
18182 | coordinates of the current raster position with the values specified. | |
18183 | That is, the values are neither transformed by the current modelview and | |
18184 | projection matrices, nor by the viewport-to-window transform. The | |
18185 | @r{@var{z}} coordinate of the current raster position is updated in the | |
18186 | following manner: | |
8925f36f | 18187 | |
3c9b6116 | 18188 | @r{@var{z}=@{(@var{n}), (@var{f}), |
8925f36f AW |
18189 | (@var{n}+@var{z}×(@var{f}-@var{n},),)(@var{if}@var{z}<=0), |
18190 | (@var{if}@var{z}>=1), (@code{otherwise},),} | |
18191 | ||
18192 | ||
18193 | ||
3c9b6116 AW |
18194 | where @r{@var{n}} is @code{GL_DEPTH_RANGE}'s near value, and @r{@var{f}} |
18195 | is @code{GL_DEPTH_RANGE}'s far value. See @code{glDepthRange}. | |
8925f36f AW |
18196 | |
18197 | The specified coordinates are not clip-tested, causing the raster | |
18198 | position to always be valid. | |
18199 | ||
18200 | The current raster position also includes some associated color data and | |
18201 | texture coordinates. If lighting is enabled, then | |
18202 | @code{GL_CURRENT_RASTER_COLOR} (in RGBA mode) or | |
18203 | @code{GL_CURRENT_RASTER_INDEX} (in color index mode) is set to the color | |
18204 | produced by the lighting calculation (see @code{glLight}, | |
18205 | @code{glLightModel}, and @code{glShadeModel}). If lighting is disabled, | |
18206 | current color (in RGBA mode, state variable @code{GL_CURRENT_COLOR}) or | |
18207 | color index (in color index mode, state variable | |
18208 | @code{GL_CURRENT_INDEX}) is used to update the current raster color. | |
18209 | @code{GL_CURRENT_RASTER_SECONDARY_COLOR} (in RGBA mode) is likewise | |
18210 | updated. | |
18211 | ||
18212 | Likewise, @code{GL_CURRENT_RASTER_TEXTURE_COORDS} is updated as a | |
18213 | function of @code{GL_CURRENT_TEXTURE_COORDS}, based on the texture | |
18214 | matrix and the texture generation functions (see @code{glTexGen}). The | |
18215 | @code{GL_CURRENT_RASTER_DISTANCE} is set to the | |
18216 | @code{GL_CURRENT_FOG_COORD}. | |
18217 | ||
18218 | ||
18219 | ||
8925f36f AW |
18220 | @code{GL_INVALID_OPERATION} is generated if @code{glWindowPos} is |
18221 | executed between the execution of @code{glBegin} and the corresponding | |
18222 | execution of @code{glEnd}. | |
18223 | ||
bb894c9d | 18224 | @end deftypefun |
8925f36f AW |
18225 | |
18226 | ||
18227 | @c %end of fragment |