Commit | Line | Data |
---|---|---|
8925f36f AW |
1 | |
2 | @c %start of fragment | |
3 | ||
3c9b6116 AW |
4 | The functions from this section may be had by loading the module: |
5 | ||
6 | @example | |
7ec693ed | 7 | (use-modules (figl gl low-level) |
3c9b6116 AW |
8 | @end example |
9 | ||
8925f36f AW |
10 | @copying |
11 | This section of the manual was derived from the upstream OpenGL | |
c7b31271 DH |
12 | documentation. Each function's documentation has its own copyright |
13 | statement; for full details, see the upstream documentation. The | |
8925f36f AW |
14 | copyright notices and licenses present in this section are as follows. |
15 | ||
c7b31271 DH |
16 | Copyright @copyright{} 1991-2006 Silicon Graphics, Inc. This document |
17 | is licensed under the SGI Free Software B License. For details, see | |
8925f36f AW |
18 | @uref{http://oss.sgi.com/projects/FreeB/,http://oss.sgi.com/projects/FreeB/}. |
19 | ||
c7b31271 | 20 | Copyright @copyright{} 2003-2005 3Dlabs Inc. Ltd. This material may be |
8925f36f AW |
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 | ||
c7b31271 | 25 | Copyright @copyright{} 2005 Addison-Wesley. This material may be |
8925f36f AW |
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 | ||
c7b31271 | 30 | Copyright @copyright{} 2006 Khronos Group. This material may be |
8925f36f AW |
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} | |
c7b31271 | 42 | Specifies the accumulation buffer operation. Symbolic constants |
8925f36f AW |
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 | |
c7b31271 | 48 | operation. @var{op} determines how @var{value} is used. |
8925f36f AW |
49 | |
50 | @end table | |
51 | ||
c7b31271 DH |
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 | |
8925f36f | 54 | buffers are added to the contents of the accumulation buffer after |
c7b31271 | 55 | rendering. Effects such as antialiasing (of points, lines, and |
8925f36f AW |
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 | |
c7b31271 DH |
60 | alpha values. The number of bits per component in the accumulation |
61 | buffer depends on the implementation. You can examine this number by | |
8925f36f AW |
62 | calling @code{glGetIntegerv} four times, with arguments |
63 | @code{GL_ACCUM_RED_BITS}, @code{GL_ACCUM_GREEN_BITS}, | |
c7b31271 DH |
64 | @code{GL_ACCUM_BLUE_BITS}, and @code{GL_ACCUM_ALPHA_BITS}. Regardless |
65 | of the number of bits per component, the range of values stored by each | |
66 | component is @r{[-1,1]}. The accumulation buffer pixels are mapped | |
8925f36f AW |
67 | one-to-one with frame buffer pixels. |
68 | ||
c7b31271 | 69 | @code{glAccum} operates on the accumulation buffer. The first argument, |
8925f36f | 70 | @var{op}, is a symbolic constant that selects an accumulation buffer |
c7b31271 DH |
71 | operation. The second argument, @var{value}, is a floating-point value |
72 | to be used in that operation. Five operations are specified: | |
8925f36f AW |
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 | |
c7b31271 DH |
78 | alpha components of each pixel. If a @code{glAccum} operation results |
79 | in a value outside the range @r{[-1,1]}, the contents of an accumulation | |
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 | |
c7b31271 | 87 | reading (see @code{glReadBuffer}). Each component value is divided by |
3c9b6116 | 88 | @r{2^@var{n}-1}, where @r{@var{n}} is the number of bits allocated to |
c7b31271 | 89 | each color component in the currently selected buffer. The result is a |
3c9b6116 | 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 | |
c7b31271 | 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 | |
c7b31271 | 115 | display buffer cell. The only fragment operations that are applied to |
3c9b6116 AW |
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} | |
c7b31271 DH |
142 | Specifies which texture unit to make active. The number of texture |
143 | units is implementation dependent, but must be at least two. | |
144 | @var{texture} must be one of @code{GL_TEXTURE}@r{@var{i}}, where i | |
145 | ranges from 0 to the larger of (@code{GL_MAX_TEXTURE_COORDS} - 1) and | |
146 | (@code{GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS} - 1). The initial value is | |
8925f36f AW |
147 | @code{GL_TEXTURE0}. |
148 | ||
149 | @end table | |
150 | ||
8925f36f | 151 | @code{glActiveTexture} selects which texture unit subsequent texture |
c7b31271 | 152 | state calls will affect. The number of texture units an implementation |
8925f36f AW |
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} | |
c7b31271 | 170 | Specifies the alpha comparison function. Symbolic constants |
8925f36f AW |
171 | @code{GL_NEVER}, @code{GL_LESS}, @code{GL_EQUAL}, @code{GL_LEQUAL}, |
172 | @code{GL_GREATER}, @code{GL_NOTEQUAL}, @code{GL_GEQUAL}, and | |
c7b31271 | 173 | @code{GL_ALWAYS} are accepted. The initial value is @code{GL_ALWAYS}. |
8925f36f AW |
174 | |
175 | @item @var{ref} | |
176 | Specifies the reference value that incoming alpha values are compared | |
c7b31271 DH |
177 | to. This value is clamped to the range @r{[0,1]}, where 0 represents |
178 | the lowest possible alpha value and 1 the highest possible value. The | |
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 | |
c7b31271 DH |
185 | reference value. @code{glAlphaFunc} specifies the reference value and |
186 | the comparison function. The comparison is performed only if alpha | |
187 | testing is enabled. By default, it is not enabled. (See | |
188 | @code{glEnable} and @code{glDisable} of @code{GL_ALPHA_TEST}.) | |
8925f36f AW |
189 | |
190 | @var{func} and @var{ref} specify the conditions under which the pixel is | |
c7b31271 DH |
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, | |
8925f36f | 193 | the incoming fragment is drawn if it also passes subsequent stencil and |
c7b31271 DH |
194 | depth buffer tests. If the value fails the comparison, no change is |
195 | made to the frame buffer at that pixel location. The comparison | |
196 | functions are as follows: | |
8925f36f AW |
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 | |
c7b31271 | 229 | bitmaps, and from pixel draw and copy operations. @code{glAlphaFunc} |
8925f36f AW |
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 | 258 | GL establishes a ``working set'' of textures that are resident in |
c7b31271 | 259 | texture memory. These textures can be bound to a texture target much |
8925f36f AW |
260 | more efficiently than textures that are not resident. |
261 | ||
262 | @code{glAreTexturesResident} queries the texture residence status of the | |
c7b31271 | 263 | @var{n} textures named by the elements of @var{textures}. If all the |
8925f36f | 264 | named textures are resident, @code{glAreTexturesResident} returns |
c7b31271 | 265 | @code{GL_TRUE}, and the contents of @var{residences} are undisturbed. If |
8925f36f AW |
266 | not all the named textures are resident, @code{glAreTexturesResident} |
267 | returns @code{GL_FALSE}, and detailed status is returned in the @var{n} | |
c7b31271 | 268 | elements of @var{residences}. If an element of @var{residences} is |
8925f36f AW |
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 | |
c7b31271 | 275 | set to @code{GL_TEXTURE_RESIDENT}. This is the only way that the |
8925f36f AW |
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 | |
c7b31271 | 281 | 0 or does not name a texture. In that case, the function returns |
8925f36f AW |
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 | |
c7b31271 | 301 | for point, line, and polygon primitives. If @code{GL_VERTEX_ARRAY} is |
8925f36f AW |
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 | |
c7b31271 | 304 | enabled arrays. If @code{GL_VERTEX_ARRAY} is not enabled, no drawing |
8925f36f AW |
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 | |
c7b31271 | 310 | order. Because each call specifies only a single vertex, it is possible |
8925f36f AW |
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 | |
c7b31271 | 317 | @code{glBegin}/@code{glEnd} period in nonsequential ways. That is, a |
8925f36f AW |
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 | 342 | In order to create an executable, there must be a way to specify the |
c7b31271 DH |
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 | |
8925f36f AW |
345 | object must first be attached to that program object. |
346 | @code{glAttachShader} attaches the shader object specified by | |
c7b31271 | 347 | @var{shader} to the program object specified by @var{program}. This |
8925f36f AW |
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 | |
c7b31271 | 352 | whether or not the shader object is attached to a program object. It is |
8925f36f AW |
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 | |
c7b31271 | 355 | has been compiled. It is permissible to attach multiple shader objects |
8925f36f | 356 | of the same type because each may contain a portion of the complete |
c7b31271 DH |
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 | |
8925f36f AW |
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 | |
c7b31271 | 388 | @code{glBeginQuery} and the subsequent @code{glEndQuery}. The symbolic |
8925f36f AW |
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 | 396 | @code{glBeginQuery} and @code{glEndQuery} delimit the boundaries of a |
c7b31271 DH |
397 | query object. If a query object with name @var{id} does not yet exist |
398 | it is created. | |
8925f36f AW |
399 | |
400 | When @code{glBeginQuery} is executed, the query object's samples-passed | |
c7b31271 DH |
401 | counter is reset to 0. Subsequent rendering will increment the counter |
402 | once for every sample that passes the depth test. When | |
403 | @code{glEndQuery} is executed, the samples-passed counter is assigned to | |
404 | the query object's result value. This value can be queried by calling | |
8925f36f AW |
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 | |
c7b31271 | 409 | result is available. @code{GL_QUERY_RESULT_AVAILABLE} can be queried to |
8925f36f AW |
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 | |
c7b31271 | 441 | presented between @code{glBegin} and the subsequent @code{glEnd}. Ten |
8925f36f AW |
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 | 449 | @code{glBegin} and @code{glEnd} delimit the vertices that define a |
c7b31271 DH |
450 | primitive or a group of like primitives. @code{glBegin} accepts a |
451 | single argument that specifies in which of ten ways the vertices are | |
452 | interpreted. Taking @r{@var{n}} as an integer count starting at one, | |
453 | and @r{@var{N}} as the total number of vertices specified, the | |
8925f36f AW |
454 | interpretations are as follows: |
455 | ||
456 | @table @asis | |
457 | @item @code{GL_POINTS} | |
c7b31271 DH |
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} | |
c7b31271 DH |
462 | Treats each pair of vertices as an independent line segment. Vertices |
463 | @r{2@var{n}-1} and @r{2@var{n}} define line @r{@var{n}}. @r{@var{N}/2} | |
3c9b6116 | 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 | |
c7b31271 | 468 | last. Vertices @r{@var{n}} and @r{@var{n}+1} define line @r{@var{n}}. |
3c9b6116 | 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 | |
c7b31271 DH |
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} | |
c7b31271 | 478 | Treats each triplet of vertices as an independent triangle. Vertices |
3c9b6116 | 479 | @r{3@var{n}-2}, @r{3@var{n}-1}, and @r{3@var{n}} define triangle |
c7b31271 | 480 | @r{@var{n}}. @r{@var{N}/3} triangles are drawn. |
8925f36f AW |
481 | |
482 | @item @code{GL_TRIANGLE_STRIP} | |
c7b31271 DH |
483 | Draws a connected group of triangles. One triangle is defined for each |
484 | vertex presented after the first two vertices. For odd @r{@var{n}}, | |
3c9b6116 | 485 | vertices @r{@var{n}}, @r{@var{n}+1}, and @r{@var{n}+2} define triangle |
c7b31271 DH |
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 | |
3c9b6116 | 488 | are drawn. |
8925f36f AW |
489 | |
490 | @item @code{GL_TRIANGLE_FAN} | |
c7b31271 DH |
491 | Draws a connected group of triangles. One triangle is defined for each |
492 | vertex presented after the first two vertices. Vertices @r{1}, | |
3c9b6116 AW |
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 | 498 | Vertices @r{4@var{n}-3}, @r{4@var{n}-2}, @r{4@var{n}-1}, and |
c7b31271 | 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} | |
c7b31271 DH |
503 | Draws a connected group of quadrilaterals. One quadrilateral is defined |
504 | for each pair of vertices presented after the first pair. Vertices | |
3c9b6116 | 505 | @r{2@var{n}-1}, @r{2@var{n}}, @r{2@var{n}+2}, and @r{2@var{n}+1} |
c7b31271 DH |
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 | |
3c9b6116 AW |
508 | quadrilateral from strip data is different from that used with |
509 | independent data. | |
8925f36f AW |
510 | |
511 | @item @code{GL_POLYGON} | |
c7b31271 | 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 | |
c7b31271 | 518 | @code{glEnd}. The commands are @code{glVertex}, @code{glColor}, |
8925f36f AW |
519 | @code{glSecondaryColor}, @code{glIndex}, @code{glNormal}, |
520 | @code{glFogCoord}, @code{glTexCoord}, @code{glMultiTexCoord}, | |
521 | @code{glVertexAttrib}, @code{glEvalCoord}, @code{glEvalPoint}, | |
c7b31271 | 522 | @code{glArrayElement}, @code{glMaterial}, and @code{glEdgeFlag}. Also, |
8925f36f | 523 | it is acceptable to use @code{glCallList} or @code{glCallLists} to |
c7b31271 | 524 | execute display lists that include only the preceding commands. If any |
8925f36f AW |
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 | |
c7b31271 DH |
530 | @code{glEnd}. Lines, triangles, quadrilaterals, and polygons that are |
531 | incompletely specified are not drawn. Incomplete specification results | |
8925f36f | 532 | when either too few vertices are provided to specify even a single |
c7b31271 | 533 | primitive or when an incorrect multiple of vertices is specified. The |
8925f36f AW |
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, | |
c7b31271 | 538 | and 3 for a polygon. Modes that require a certain multiple of vertices |
8925f36f AW |
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 | |
c7b31271 DH |
593 | a generic vertex attribute index. The name of the user-defined |
594 | attribute variable is passed as a null terminated string in @var{name}. | |
595 | The generic vertex attribute index to be bound to this variable is | |
596 | specified by @var{index}. When @var{program} is made part of current | |
597 | state, values provided via the generic vertex attribute @var{index} will | |
598 | modify the value of the user-defined attribute variable specified by | |
599 | @var{name}. | |
8925f36f AW |
600 | |
601 | If @var{name} refers to a matrix attribute variable, @var{index} refers | |
c7b31271 | 602 | to the first column of the matrix. Other matrix columns are then |
8925f36f AW |
603 | automatically bound to locations @var{index+1} for a matrix of type |
604 | mat2; @var{index+1} and @var{index+2} for a matrix of type mat3; and | |
605 | @var{index+1}, @var{index+2}, and @var{index+3} for a matrix of type | |
606 | mat4. | |
607 | ||
608 | This command makes it possible for vertex shaders to use descriptive | |
609 | names for attribute variables rather than generic variables that are | |
c7b31271 | 610 | numbered from 0 to @code{GL_MAX_VERTEX_ATTRIBS} -1. The values sent to |
8925f36f AW |
611 | each generic attribute index are part of current state, just like |
612 | standard vertex attributes such as color, normal, and vertex position. | |
613 | If a different program object is made current by calling | |
614 | @code{glUseProgram}, the generic vertex attributes are tracked in such a | |
615 | way that the same values will be observed by attributes in the new | |
616 | program object that are also bound to @var{index}. | |
617 | ||
618 | Attribute variable name-to-generic attribute index bindings for a | |
619 | program object can be explicitly assigned at any time by calling | |
c7b31271 DH |
620 | @code{glBindAttribLocation}. Attribute bindings do not go into effect |
621 | until @code{glLinkProgram} is called. After a program object has been | |
8925f36f AW |
622 | linked successfully, the index values for generic attributes remain |
623 | fixed (and their values can be queried) until the next link command | |
624 | occurs. | |
625 | ||
626 | Applications are not allowed to bind any of the standard OpenGL vertex | |
627 | attributes using this command, as they are bound automatically when | |
c7b31271 | 628 | needed. Any attribute binding that occurs after the program object has |
8925f36f AW |
629 | been linked will not take effect until the next time the program object |
630 | is linked. | |
631 | ||
8925f36f AW |
632 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or |
633 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
634 | ||
635 | @code{GL_INVALID_OPERATION} is generated if @var{name} starts with the | |
636 | reserved prefix "gl_". | |
637 | ||
638 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value | |
639 | generated by OpenGL. | |
640 | ||
641 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
642 | program object. | |
643 | ||
644 | @code{GL_INVALID_OPERATION} is generated if @code{glBindAttribLocation} | |
645 | is executed between the execution of @code{glBegin} and the | |
646 | corresponding execution of @code{glEnd}. | |
647 | ||
bb894c9d | 648 | @end deftypefun |
8925f36f | 649 | |
bb894c9d | 650 | @deftypefun void glBindBuffer target buffer |
3c9b6116 AW |
651 | Bind a named buffer object. |
652 | ||
8925f36f AW |
653 | @table @asis |
654 | @item @var{target} | |
c7b31271 | 655 | Specifies the target to which the buffer object is bound. The symbolic |
8925f36f AW |
656 | constant must be @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, |
657 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
658 | ||
659 | @item @var{buffer} | |
660 | Specifies the name of a buffer object. | |
661 | ||
662 | @end table | |
663 | ||
8925f36f AW |
664 | @code{glBindBuffer} lets you create or use a named buffer object. |
665 | Calling @code{glBindBuffer} with @var{target} set to | |
666 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
667 | @code{GL_PIXEL_PACK_BUFFER} or @code{GL_PIXEL_UNPACK_BUFFER} and | |
668 | @var{buffer} set to the name of the new buffer object binds the buffer | |
c7b31271 | 669 | object name to the target. When a buffer object is bound to a target, |
8925f36f AW |
670 | the previous binding for that target is automatically broken. |
671 | ||
c7b31271 | 672 | Buffer object names are unsigned integers. The value zero is reserved, |
8925f36f AW |
673 | but there is no default buffer object for each buffer object target. |
674 | Instead, @var{buffer} set to zero effectively unbinds any buffer object | |
675 | previously bound, and restores client memory usage for that buffer | |
c7b31271 | 676 | object target. Buffer object names and the corresponding buffer object |
8925f36f AW |
677 | contents are local to the shared display-list space (see |
678 | @code{glXCreateContext}) of the current GL rendering context; two | |
679 | rendering contexts share buffer object names only if they also share | |
680 | display lists. | |
681 | ||
682 | You may use @code{glGenBuffers} to generate a set of new buffer object | |
683 | names. | |
684 | ||
685 | The state of a buffer object immediately after it is first bound is an | |
686 | unmapped zero-sized memory buffer with @code{GL_READ_WRITE} access and | |
687 | @code{GL_STATIC_DRAW} usage. | |
688 | ||
689 | While a non-zero buffer object name is bound, GL operations on the | |
690 | target to which it is bound affect the bound buffer object, and queries | |
691 | of the target to which it is bound return state from the bound buffer | |
c7b31271 DH |
692 | object. While buffer object name zero is bound, as in the initial |
693 | state, attempts to modify or query state on the target to which it is | |
694 | bound generates an @code{GL_INVALID_OPERATION} error. | |
8925f36f AW |
695 | |
696 | When vertex array pointer state is changed, for example by a call to | |
697 | @code{glNormalPointer}, the current buffer object binding | |
698 | (@code{GL_ARRAY_BUFFER_BINDING}) is copied into the corresponding client | |
699 | state for the vertex array type being changed, for example | |
c7b31271 DH |
700 | @code{GL_NORMAL_ARRAY_BUFFER_BINDING}. While a non-zero buffer object |
701 | is bound to the @code{GL_ARRAY_BUFFER} target, the vertex array pointer | |
8925f36f AW |
702 | parameter that is traditionally interpreted as a pointer to client-side |
703 | memory is instead interpreted as an offset within the buffer object | |
704 | measured in basic machine units. | |
705 | ||
706 | While a non-zero buffer object is bound to the | |
707 | @code{GL_ELEMENT_ARRAY_BUFFER} target, the indices parameter of | |
708 | @code{glDrawElements}, @code{glDrawRangeElements}, or | |
709 | @code{glMultiDrawElements} that is traditionally interpreted as a | |
710 | pointer to client-side memory is instead interpreted as an offset within | |
711 | the buffer object measured in basic machine units. | |
712 | ||
713 | While a non-zero buffer object is bound to the | |
714 | @code{GL_PIXEL_PACK_BUFFER} target, the following commands are affected: | |
715 | @code{glGetCompressedTexImage}, @code{glGetConvolutionFilter}, | |
716 | @code{glGetHistogram}, @code{glGetMinmax}, @code{glGetPixelMap}, | |
717 | @code{glGetPolygonStipple}, @code{glGetSeparableFilter}, | |
c7b31271 | 718 | @code{glGetTexImage}, and @code{glReadPixels}. The pointer parameter |
8925f36f AW |
719 | that is traditionally interpreted as a pointer to client-side memory |
720 | where the pixels are to be packed is instead interpreted as an offset | |
721 | within the buffer object measured in basic machine units. | |
722 | ||
723 | While a non-zero buffer object is bound to the | |
724 | @code{GL_PIXEL_UNPACK_BUFFER} target, the following commands are | |
725 | affected: @code{glBitmap}, @code{glColorSubTable}, @code{glColorTable}, | |
726 | @code{glCompressedTexImage1D}, @code{glCompressedTexImage2D}, | |
727 | @code{glCompressedTexImage3D}, @code{glCompressedTexSubImage1D}, | |
728 | @code{glCompressedTexSubImage2D}, @code{glCompressedTexSubImage3D}, | |
729 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, | |
730 | @code{glDrawPixels}, @code{glPixelMap}, @code{glPolygonStipple}, | |
731 | @code{glSeparableFilter2D}, @code{glTexImage1D}, @code{glTexImage2D}, | |
732 | @code{glTexImage3D}, @code{glTexSubImage1D}, @code{glTexSubImage2D}, and | |
c7b31271 | 733 | @code{glTexSubImage3D}. The pointer parameter that is traditionally |
8925f36f AW |
734 | interpreted as a pointer to client-side memory from which the pixels are |
735 | to be unpacked is instead interpreted as an offset within the buffer | |
736 | object measured in basic machine units. | |
737 | ||
738 | A buffer object binding created with @code{glBindBuffer} remains active | |
739 | until a different buffer object name is bound to the same target, or | |
740 | until the bound buffer object is deleted with @code{glDeleteBuffers}. | |
741 | ||
742 | Once created, a named buffer object may be re-bound to any target as | |
c7b31271 | 743 | often as needed. However, the GL implementation may make choices about |
8925f36f AW |
744 | how to optimize the storage of a buffer object based on its initial |
745 | binding target. | |
746 | ||
8925f36f AW |
747 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
748 | allowable values. | |
749 | ||
750 | @code{GL_INVALID_OPERATION} is generated if @code{glBindBuffer} is | |
751 | executed between the execution of @code{glBegin} and the corresponding | |
752 | execution of @code{glEnd}. | |
753 | ||
bb894c9d | 754 | @end deftypefun |
8925f36f | 755 | |
bb894c9d | 756 | @deftypefun void glBindTexture target texture |
3c9b6116 AW |
757 | Bind a named texture to a texturing target. |
758 | ||
8925f36f AW |
759 | @table @asis |
760 | @item @var{target} | |
c7b31271 | 761 | Specifies the target to which the texture is bound. Must be either |
8925f36f AW |
762 | @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, or |
763 | @code{GL_TEXTURE_CUBE_MAP}. | |
764 | ||
765 | @item @var{texture} | |
766 | Specifies the name of a texture. | |
767 | ||
768 | @end table | |
769 | ||
c7b31271 | 770 | @code{glBindTexture} lets you create or use a named texture. Calling |
8925f36f AW |
771 | @code{glBindTexture} with @var{target} set to @code{GL_TEXTURE_1D}, |
772 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D} or @code{GL_TEXTURE_CUBE_MAP} | |
773 | and @var{texture} set to the name of the new texture binds the texture | |
c7b31271 | 774 | name to the target. When a texture is bound to a target, the previous |
8925f36f AW |
775 | binding for that target is automatically broken. |
776 | ||
c7b31271 DH |
777 | Texture names are unsigned integers. The value zero is reserved to |
778 | represent the default texture for each texture target. Texture names | |
779 | and the corresponding texture contents are local to the shared | |
780 | display-list space (see @code{glXCreateContext}) of the current GL | |
781 | rendering context; two rendering contexts share texture names only if | |
782 | they also share display lists. | |
8925f36f AW |
783 | |
784 | You may use @code{glGenTextures} to generate a set of new texture names. | |
785 | ||
786 | When a texture is first bound, it assumes the specified target: A | |
787 | texture first bound to @code{GL_TEXTURE_1D} becomes one-dimensional | |
788 | texture, a texture first bound to @code{GL_TEXTURE_2D} becomes | |
789 | two-dimensional texture, a texture first bound to @code{GL_TEXTURE_3D} | |
790 | becomes three-dimensional texture, and a texture first bound to | |
c7b31271 DH |
791 | @code{GL_TEXTURE_CUBE_MAP} becomes a cube-mapped texture. The state of |
792 | a one-dimensional texture immediately after it is first bound is | |
8925f36f AW |
793 | equivalent to the state of the default @code{GL_TEXTURE_1D} at GL |
794 | initialization, and similarly for two- and three-dimensional textures | |
795 | and cube-mapped textures. | |
796 | ||
797 | While a texture is bound, GL operations on the target to which it is | |
798 | bound affect the bound texture, and queries of the target to which it is | |
c7b31271 DH |
799 | bound return state from the bound texture. If texture mapping is active |
800 | on the target to which a texture is bound, the bound texture is used. In | |
8925f36f AW |
801 | effect, the texture targets become aliases for the textures currently |
802 | bound to them, and the texture name zero refers to the default textures | |
803 | that were bound to them at initialization. | |
804 | ||
805 | A texture binding created with @code{glBindTexture} remains active until | |
806 | a different texture is bound to the same target, or until the bound | |
807 | texture is deleted with @code{glDeleteTextures}. | |
808 | ||
809 | Once created, a named texture may be re-bound to its same original | |
c7b31271 | 810 | target as often as needed. It is usually much faster to use |
8925f36f AW |
811 | @code{glBindTexture} to bind an existing named texture to one of the |
812 | texture targets than it is to reload the texture image using | |
c7b31271 | 813 | @code{glTexImage1D}, @code{glTexImage2D}, or @code{glTexImage3D}. For |
8925f36f AW |
814 | additional control over performance, use @code{glPrioritizeTextures}. |
815 | ||
816 | @code{glBindTexture} is included in display lists. | |
817 | ||
8925f36f AW |
818 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
819 | allowable values. | |
820 | ||
821 | @code{GL_INVALID_OPERATION} is generated if @var{texture} was previously | |
822 | created with a target that doesn't match that of @var{target}. | |
823 | ||
824 | @code{GL_INVALID_OPERATION} is generated if @code{glBindTexture} is | |
825 | executed between the execution of @code{glBegin} and the corresponding | |
826 | execution of @code{glEnd}. | |
827 | ||
bb894c9d | 828 | @end deftypefun |
8925f36f | 829 | |
bb894c9d | 830 | @deftypefun void glBitmap width height xorig yorig xmove ymove bitmap |
3c9b6116 AW |
831 | Draw a bitmap. |
832 | ||
8925f36f AW |
833 | @table @asis |
834 | @item @var{width} | |
835 | @itemx @var{height} | |
836 | Specify the pixel width and height of the bitmap image. | |
837 | ||
838 | @item @var{xorig} | |
839 | @itemx @var{yorig} | |
c7b31271 | 840 | Specify the location of the origin in the bitmap image. The origin is |
8925f36f AW |
841 | measured from the lower left corner of the bitmap, with right and up |
842 | being the positive axes. | |
843 | ||
844 | @item @var{xmove} | |
845 | @itemx @var{ymove} | |
846 | Specify the @var{x} and @var{y} offsets to be added to the current | |
847 | raster position after the bitmap is drawn. | |
848 | ||
849 | @item @var{bitmap} | |
850 | Specifies the address of the bitmap image. | |
851 | ||
852 | @end table | |
853 | ||
c7b31271 | 854 | A bitmap is a binary image. When drawn, the bitmap is positioned |
8925f36f AW |
855 | relative to the current raster position, and frame buffer pixels |
856 | corresponding to 1's in the bitmap are written using the current raster | |
c7b31271 | 857 | color or index. Frame buffer pixels corresponding to 0's in the bitmap |
8925f36f AW |
858 | are not modified. |
859 | ||
c7b31271 DH |
860 | @code{glBitmap} takes seven arguments. The first pair specifies the |
861 | width and height of the bitmap image. The second pair specifies the | |
8925f36f | 862 | location of the bitmap origin relative to the lower left corner of the |
c7b31271 | 863 | bitmap image. The third pair of arguments specifies @var{x} and @var{y} |
8925f36f | 864 | offsets to be added to the current raster position after the bitmap has |
c7b31271 | 865 | been drawn. The final argument is a pointer to the bitmap image itself. |
8925f36f AW |
866 | |
867 | If a non-zero named buffer object is bound to the | |
868 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
869 | bitmap image is specified, @var{bitmap} is treated as a byte offset into | |
870 | the buffer object's data store. | |
871 | ||
872 | The bitmap image is interpreted like image data for the | |
873 | @code{glDrawPixels} command, with @var{width} and @var{height} | |
874 | corresponding to the width and height arguments of that command, and | |
875 | with @var{type} set to @code{GL_BITMAP} and @var{format} set to | |
c7b31271 | 876 | @code{GL_COLOR_INDEX}. Modes specified using @code{glPixelStore} affect |
8925f36f AW |
877 | the interpretation of bitmap image data; modes specified using |
878 | @code{glPixelTransfer} do not. | |
879 | ||
880 | If the current raster position is invalid, @code{glBitmap} is ignored. | |
881 | Otherwise, the lower left corner of the bitmap image is positioned at | |
882 | the window coordinates | |
883 | ||
3c9b6116 | 884 | @r{@var{x}_@var{w}=⌊@var{x}_@var{r}-@var{x}_@var{o},⌋} |
8925f36f | 885 | |
3c9b6116 | 886 | @r{@var{y}_@var{w}=⌊@var{y}_@var{r}-@var{y}_@var{o},⌋} |
8925f36f | 887 | |
3c9b6116 | 888 | where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the raster position and |
c7b31271 | 889 | @r{(@var{x}_@var{o},@var{y}_@var{o})} is the bitmap origin. Fragments |
3c9b6116 | 890 | are then generated for each pixel corresponding to a 1 (one) in the |
c7b31271 | 891 | bitmap image. These fragments are generated using the current raster |
3c9b6116 | 892 | @var{z} coordinate, color or color index, and current raster texture |
c7b31271 DH |
893 | coordinates. They are then treated just as if they had been generated |
894 | by a point, line, or polygon, including texture mapping, fogging, and | |
895 | all per-fragment operations such as alpha and depth testing. | |
8925f36f AW |
896 | |
897 | After the bitmap has been drawn, the @var{x} and @var{y} coordinates of | |
898 | the current raster position are offset by @var{xmove} and @var{ymove}. | |
899 | No change is made to the @var{z} coordinate of the current raster | |
900 | position, or to the current raster color, texture coordinates, or index. | |
901 | ||
8925f36f AW |
902 | @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is |
903 | negative. | |
904 | ||
905 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
906 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
907 | object's data store is currently mapped. | |
908 | ||
909 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
910 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
911 | would be unpacked from the buffer object such that the memory reads | |
912 | required would exceed the data store size. | |
913 | ||
914 | @code{GL_INVALID_OPERATION} is generated if @code{glBitmap} is executed | |
915 | between the execution of @code{glBegin} and the corresponding execution | |
916 | of @code{glEnd}. | |
917 | ||
bb894c9d | 918 | @end deftypefun |
8925f36f | 919 | |
bb894c9d | 920 | @deftypefun void glBlendColor red green blue alpha |
3c9b6116 AW |
921 | Set the blend color. |
922 | ||
8925f36f AW |
923 | @table @asis |
924 | @item @var{red} | |
925 | @itemx @var{green} | |
926 | @itemx @var{blue} | |
927 | @itemx @var{alpha} | |
928 | specify the components of @code{GL_BLEND_COLOR} | |
929 | ||
930 | @end table | |
931 | ||
8925f36f | 932 | The @code{GL_BLEND_COLOR} may be used to calculate the source and |
c7b31271 DH |
933 | destination blending factors. The color components are clamped to the |
934 | range @r{[0,1]} before being stored. See @code{glBlendFunc} for a | |
935 | complete description of the blending operations. Initially the | |
8925f36f AW |
936 | @code{GL_BLEND_COLOR} is set to (0, 0, 0, 0). |
937 | ||
8925f36f AW |
938 | @code{GL_INVALID_OPERATION} is generated if @code{glBlendColor} is |
939 | executed between the execution of @code{glBegin} and the corresponding | |
940 | execution of @code{glEnd}. | |
941 | ||
942 | ||
943 | ||
bb894c9d | 944 | @end deftypefun |
8925f36f | 945 | |
bb894c9d | 946 | @deftypefun void glBlendEquationSeparate modeRGB modeAlpha |
3c9b6116 AW |
947 | Set the RGB blend equation and the alpha blend equation separately. |
948 | ||
8925f36f AW |
949 | @table @asis |
950 | @item @var{modeRGB} | |
951 | specifies the RGB blend equation, how the red, green, and blue | |
c7b31271 DH |
952 | components of the source and destination colors are combined. It must |
953 | be @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT}, | |
8925f36f AW |
954 | @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN}, @code{GL_MAX}. |
955 | ||
956 | @item @var{modeAlpha} | |
957 | specifies the alpha blend equation, how the alpha component of the | |
c7b31271 | 958 | source and destination colors are combined. It must be |
8925f36f AW |
959 | @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT}, |
960 | @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN}, @code{GL_MAX}. | |
961 | ||
962 | @end table | |
963 | ||
8925f36f AW |
964 | The blend equations determines how a new pixel (the ''source'' color) is |
965 | combined with a pixel already in the framebuffer (the ''destination'' | |
c7b31271 | 966 | color). This function specifies one blend equation for the RGB-color |
8925f36f AW |
967 | components and one blend equation for the alpha component. |
968 | ||
969 | The blend equations use the source and destination blend factors | |
970 | specified by either @code{glBlendFunc} or @code{glBlendFuncSeparate}. | |
971 | See @code{glBlendFunc} or @code{glBlendFuncSeparate} for a description | |
972 | of the various blend factors. | |
973 | ||
974 | In the equations that follow, source and destination color components | |
975 | are referred to as | |
3c9b6116 AW |
976 | @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and |
977 | @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})}, | |
c7b31271 DH |
978 | respectively. The result color is referred to as |
979 | @r{(@var{R}_@var{r},@var{G}_@var{r}@var{B}_@var{r}@var{A}_@var{r})}. The | |
3c9b6116 AW |
980 | source and destination blend factors are denoted |
981 | @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and | |
982 | @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})}, | |
c7b31271 DH |
983 | respectively. For these equations all color components are understood |
984 | to have values in the range @r{[0,1]}. | |
8925f36f AW |
985 | |
986 | @table @asis | |
987 | @item @strong{Mode} | |
988 | @strong{RGB Components}, @strong{Alpha Component} | |
989 | ||
990 | @item @code{GL_FUNC_ADD} | |
3c9b6116 AW |
991 | @r{@var{Rr}=@var{R}_@var{s}@var{s}_@var{R}+@var{R}_@var{d}@var{d}_@var{R}}@r{@var{Gr}=@var{G}_@var{s}@var{s}_@var{G}+@var{G}_@var{d}@var{d}_@var{G}}@r{@var{Br}=@var{B}_@var{s}@var{s}_@var{B}+@var{B}_@var{d}@var{d}_@var{B}}, |
992 | @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}+@var{A}_@var{d}@var{d}_@var{A}} | |
8925f36f AW |
993 | |
994 | @item @code{GL_FUNC_SUBTRACT} | |
3c9b6116 AW |
995 | @r{@var{Rr}=@var{R}_@var{s}@var{s}_@var{R}-@var{R}_@var{d}@var{d}_@var{R}}@r{@var{Gr}=@var{G}_@var{s}@var{s}_@var{G}-@var{G}_@var{d}@var{d}_@var{G}}@r{@var{Br}=@var{B}_@var{s}@var{s}_@var{B}-@var{B}_@var{d}@var{d}_@var{B}}, |
996 | @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}-@var{A}_@var{d}@var{d}_@var{A}} | |
8925f36f AW |
997 | |
998 | @item @code{GL_FUNC_REVERSE_SUBTRACT} | |
3c9b6116 AW |
999 | @r{@var{Rr}=@var{R}_@var{d}@var{d}_@var{R}-@var{R}_@var{s}@var{s}_@var{R}}@r{@var{Gr}=@var{G}_@var{d}@var{d}_@var{G}-@var{G}_@var{s}@var{s}_@var{G}}@r{@var{Br}=@var{B}_@var{d}@var{d}_@var{B}-@var{B}_@var{s}@var{s}_@var{B}}, |
1000 | @r{@var{Ar}=@var{A}_@var{d}@var{d}_@var{A}-@var{A}_@var{s}@var{s}_@var{A}} | |
8925f36f AW |
1001 | |
1002 | @item @code{GL_MIN} | |
3c9b6116 AW |
1003 | @r{@var{Rr}=@var{min}(@var{R}_@var{s},@var{R}_@var{d})}@r{@var{Gr}=@var{min}(@var{G}_@var{s},@var{G}_@var{d})}@r{@var{Br}=@var{min}(@var{B}_@var{s},@var{B}_@var{d})}, |
1004 | @r{@var{Ar}=@var{min}(@var{A}_@var{s},@var{A}_@var{d})} | |
8925f36f AW |
1005 | |
1006 | @item @code{GL_MAX} | |
3c9b6116 AW |
1007 | @r{@var{Rr}=@var{max}(@var{R}_@var{s},@var{R}_@var{d})}@r{@var{Gr}=@var{max}(@var{G}_@var{s},@var{G}_@var{d})}@r{@var{Br}=@var{max}(@var{B}_@var{s},@var{B}_@var{d})}, |
1008 | @r{@var{Ar}=@var{max}(@var{A}_@var{s},@var{A}_@var{d})} | |
8925f36f AW |
1009 | |
1010 | @end table | |
1011 | ||
3c9b6116 | 1012 | The results of these equations are clamped to the range @r{[0,1]}. |
8925f36f AW |
1013 | |
1014 | The @code{GL_MIN} and @code{GL_MAX} equations are useful for | |
1015 | applications that analyze image data (image thresholding against a | |
c7b31271 | 1016 | constant color, for example). The @code{GL_FUNC_ADD} equation is useful |
8925f36f AW |
1017 | for antialiasing and transparency, among other things. |
1018 | ||
1019 | Initially, both the RGB blend equation and the alpha blend equation are | |
1020 | set to @code{GL_FUNC_ADD}. | |
1021 | ||
1022 | ||
1023 | ||
8925f36f AW |
1024 | @code{GL_INVALID_ENUM} is generated if either @var{modeRGB} or |
1025 | @var{modeAlpha} is not one of @code{GL_FUNC_ADD}, | |
1026 | @code{GL_FUNC_SUBTRACT}, @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MAX}, | |
1027 | or @code{GL_MIN}. | |
1028 | ||
1029 | @code{GL_INVALID_OPERATION} is generated if | |
1030 | @code{glBlendEquationSeparate} is executed between the execution of | |
1031 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
1032 | ||
bb894c9d | 1033 | @end deftypefun |
8925f36f | 1034 | |
bb894c9d | 1035 | @deftypefun void glBlendEquation mode |
3c9b6116 AW |
1036 | Specify the equation used for both the RGB blend equation and the Alpha |
1037 | blend equation. | |
1038 | ||
8925f36f AW |
1039 | @table @asis |
1040 | @item @var{mode} | |
c7b31271 | 1041 | specifies how source and destination colors are combined. It must be |
8925f36f AW |
1042 | @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT}, |
1043 | @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN}, @code{GL_MAX}. | |
1044 | ||
1045 | @end table | |
1046 | ||
8925f36f AW |
1047 | The blend equations determine how a new pixel (the ''source'' color) is |
1048 | combined with a pixel already in the framebuffer (the ''destination'' | |
c7b31271 | 1049 | color). This function sets both the RGB blend equation and the alpha |
8925f36f AW |
1050 | blend equation to a single equation. |
1051 | ||
1052 | These equations use the source and destination blend factors specified | |
c7b31271 | 1053 | by either @code{glBlendFunc} or @code{glBlendFuncSeparate}. See |
8925f36f AW |
1054 | @code{glBlendFunc} or @code{glBlendFuncSeparate} for a description of |
1055 | the various blend factors. | |
1056 | ||
1057 | In the equations that follow, source and destination color components | |
1058 | are referred to as | |
3c9b6116 AW |
1059 | @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and |
1060 | @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})}, | |
c7b31271 DH |
1061 | respectively. The result color is referred to as |
1062 | @r{(@var{R}_@var{r},@var{G}_@var{r}@var{B}_@var{r}@var{A}_@var{r})}. The | |
3c9b6116 AW |
1063 | source and destination blend factors are denoted |
1064 | @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and | |
1065 | @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})}, | |
c7b31271 DH |
1066 | respectively. For these equations all color components are understood |
1067 | to have values in the range @r{[0,1]}. | |
8925f36f AW |
1068 | |
1069 | @table @asis | |
1070 | @item @strong{Mode} | |
1071 | @strong{RGB Components}, @strong{Alpha Component} | |
1072 | ||
1073 | @item @code{GL_FUNC_ADD} | |
3c9b6116 AW |
1074 | @r{@var{Rr}=@var{R}_@var{s}@var{s}_@var{R}+@var{R}_@var{d}@var{d}_@var{R}}@r{@var{Gr}=@var{G}_@var{s}@var{s}_@var{G}+@var{G}_@var{d}@var{d}_@var{G}}@r{@var{Br}=@var{B}_@var{s}@var{s}_@var{B}+@var{B}_@var{d}@var{d}_@var{B}}, |
1075 | @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}+@var{A}_@var{d}@var{d}_@var{A}} | |
8925f36f AW |
1076 | |
1077 | @item @code{GL_FUNC_SUBTRACT} | |
3c9b6116 AW |
1078 | @r{@var{Rr}=@var{R}_@var{s}@var{s}_@var{R}-@var{R}_@var{d}@var{d}_@var{R}}@r{@var{Gr}=@var{G}_@var{s}@var{s}_@var{G}-@var{G}_@var{d}@var{d}_@var{G}}@r{@var{Br}=@var{B}_@var{s}@var{s}_@var{B}-@var{B}_@var{d}@var{d}_@var{B}}, |
1079 | @r{@var{Ar}=@var{A}_@var{s}@var{s}_@var{A}-@var{A}_@var{d}@var{d}_@var{A}} | |
8925f36f AW |
1080 | |
1081 | @item @code{GL_FUNC_REVERSE_SUBTRACT} | |
3c9b6116 AW |
1082 | @r{@var{Rr}=@var{R}_@var{d}@var{d}_@var{R}-@var{R}_@var{s}@var{s}_@var{R}}@r{@var{Gr}=@var{G}_@var{d}@var{d}_@var{G}-@var{G}_@var{s}@var{s}_@var{G}}@r{@var{Br}=@var{B}_@var{d}@var{d}_@var{B}-@var{B}_@var{s}@var{s}_@var{B}}, |
1083 | @r{@var{Ar}=@var{A}_@var{d}@var{d}_@var{A}-@var{A}_@var{s}@var{s}_@var{A}} | |
8925f36f AW |
1084 | |
1085 | @item @code{GL_MIN} | |
3c9b6116 AW |
1086 | @r{@var{Rr}=@var{min}(@var{R}_@var{s},@var{R}_@var{d})}@r{@var{Gr}=@var{min}(@var{G}_@var{s},@var{G}_@var{d})}@r{@var{Br}=@var{min}(@var{B}_@var{s},@var{B}_@var{d})}, |
1087 | @r{@var{Ar}=@var{min}(@var{A}_@var{s},@var{A}_@var{d})} | |
8925f36f AW |
1088 | |
1089 | @item @code{GL_MAX} | |
3c9b6116 AW |
1090 | @r{@var{Rr}=@var{max}(@var{R}_@var{s},@var{R}_@var{d})}@r{@var{Gr}=@var{max}(@var{G}_@var{s},@var{G}_@var{d})}@r{@var{Br}=@var{max}(@var{B}_@var{s},@var{B}_@var{d})}, |
1091 | @r{@var{Ar}=@var{max}(@var{A}_@var{s},@var{A}_@var{d})} | |
8925f36f AW |
1092 | |
1093 | @end table | |
1094 | ||
3c9b6116 | 1095 | The results of these equations are clamped to the range @r{[0,1]}. |
8925f36f AW |
1096 | |
1097 | The @code{GL_MIN} and @code{GL_MAX} equations are useful for | |
1098 | applications that analyze image data (image thresholding against a | |
c7b31271 | 1099 | constant color, for example). The @code{GL_FUNC_ADD} equation is useful |
8925f36f AW |
1100 | for antialiasing and transparency, among other things. |
1101 | ||
1102 | Initially, both the RGB blend equation and the alpha blend equation are | |
1103 | set to @code{GL_FUNC_ADD}. | |
1104 | ||
1105 | ||
1106 | ||
8925f36f AW |
1107 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of |
1108 | @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT}, | |
1109 | @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MAX}, or @code{GL_MIN}. | |
1110 | ||
1111 | @code{GL_INVALID_OPERATION} is generated if @code{glBlendEquation} is | |
1112 | executed between the execution of @code{glBegin} and the corresponding | |
1113 | execution of @code{glEnd}. | |
1114 | ||
bb894c9d | 1115 | @end deftypefun |
8925f36f | 1116 | |
bb894c9d | 1117 | @deftypefun void glBlendFuncSeparate srcRGB dstRGB srcAlpha dstAlpha |
3c9b6116 AW |
1118 | Specify pixel arithmetic for RGB and alpha components separately. |
1119 | ||
8925f36f AW |
1120 | @table @asis |
1121 | @item @var{srcRGB} | |
1122 | Specifies how the red, green, and blue blending factors are computed. | |
1123 | The following symbolic constants are accepted: @code{GL_ZERO}, | |
1124 | @code{GL_ONE}, @code{GL_SRC_COLOR}, @code{GL_ONE_MINUS_SRC_COLOR}, | |
1125 | @code{GL_DST_COLOR}, @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA}, | |
1126 | @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA}, | |
1127 | @code{GL_ONE_MINUS_DST_ALPHA}, @code{GL_CONSTANT_COLOR}, | |
1128 | @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA}, | |
1129 | @code{GL_ONE_MINUS_CONSTANT_ALPHA}, and @code{GL_SRC_ALPHA_SATURATE}. | |
1130 | The initial value is @code{GL_ONE}. | |
1131 | ||
1132 | @item @var{dstRGB} | |
1133 | Specifies how the red, green, and blue destination blending factors are | |
c7b31271 DH |
1134 | computed. The following symbolic constants are accepted: |
1135 | @code{GL_ZERO}, @code{GL_ONE}, @code{GL_SRC_COLOR}, | |
1136 | @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_DST_COLOR}, | |
1137 | @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA}, | |
8925f36f | 1138 | @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA}, |
c7b31271 | 1139 | @code{GL_ONE_MINUS_DST_ALPHA}. @code{GL_CONSTANT_COLOR}, |
8925f36f | 1140 | @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA}, and |
c7b31271 DH |
1141 | @code{GL_ONE_MINUS_CONSTANT_ALPHA}. The initial value is |
1142 | @code{GL_ZERO}. | |
8925f36f AW |
1143 | |
1144 | @item @var{srcAlpha} | |
c7b31271 DH |
1145 | Specified how the alpha source blending factor is computed. The same |
1146 | symbolic constants are accepted as for @var{srcRGB}. The initial value | |
8925f36f AW |
1147 | is @code{GL_ONE}. |
1148 | ||
1149 | @item @var{dstAlpha} | |
c7b31271 DH |
1150 | Specified how the alpha destination blending factor is computed. The |
1151 | same symbolic constants are accepted as for @var{dstRGB}. The initial | |
8925f36f AW |
1152 | value is @code{GL_ZERO}. |
1153 | ||
1154 | @end table | |
1155 | ||
8925f36f AW |
1156 | In RGBA mode, pixels can be drawn using a function that blends the |
1157 | incoming (source) RGBA values with the RGBA values that are already in | |
c7b31271 DH |
1158 | the frame buffer (the destination values). Blending is initially |
1159 | disabled. Use @code{glEnable} and @code{glDisable} with argument | |
8925f36f AW |
1160 | @code{GL_BLEND} to enable and disable blending. |
1161 | ||
1162 | @code{glBlendFuncSeparate} defines the operation of blending when it is | |
c7b31271 DH |
1163 | enabled. @var{srcRGB} specifies which method is used to scale the |
1164 | source RGB-color components. @var{dstRGB} specifies which method is | |
1165 | used to scale the destination RGB-color components. Likewise, | |
1166 | @var{srcAlpha} specifies which method is used to scale the source alpha | |
1167 | color component, and @var{dstAlpha} specifies which method is used to | |
1168 | scale the destination alpha component. The possible methods are | |
1169 | described in the following table. Each method defines four scale | |
1170 | factors, one each for red, green, blue, and alpha. | |
8925f36f AW |
1171 | |
1172 | In the table and in subsequent equations, source and destination color | |
1173 | components are referred to as | |
3c9b6116 | 1174 | @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and |
c7b31271 | 1175 | @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})}. The |
3c9b6116 AW |
1176 | color specified by @code{glBlendColor} is referred to as |
1177 | @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})}. | |
8925f36f | 1178 | They are understood to have integer values between 0 and |
3c9b6116 | 1179 | @r{(@var{k}_@var{R},@var{k}_@var{G}@var{k}_@var{B}@var{k}_@var{A})}, |
8925f36f AW |
1180 | where |
1181 | ||
3c9b6116 | 1182 | @r{@var{k}_@var{c}=2^@var{m}_@var{c},-1} |
8925f36f | 1183 | |
3c9b6116 | 1184 | and @r{(@var{m}_@var{R},@var{m}_@var{G}@var{m}_@var{B}@var{m}_@var{A})} |
8925f36f AW |
1185 | is the number of red, green, blue, and alpha bitplanes. |
1186 | ||
1187 | Source and destination scale factors are referred to as | |
3c9b6116 | 1188 | @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and |
c7b31271 | 1189 | @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})}. All |
3c9b6116 | 1190 | scale factors have range @r{[0,1]}. |
8925f36f AW |
1191 | |
1192 | ||
1193 | ||
1194 | @table @asis | |
1195 | @item @strong{Parameter} | |
1196 | @strong{RGB Factor}, @strong{Alpha Factor} | |
1197 | ||
1198 | @item @code{GL_ZERO} | |
3c9b6116 | 1199 | @r{(0,00)}, @r{0} |
8925f36f AW |
1200 | |
1201 | @item @code{GL_ONE} | |
3c9b6116 | 1202 | @r{(1,11)}, @r{1} |
8925f36f AW |
1203 | |
1204 | @item @code{GL_SRC_COLOR} | |
3c9b6116 AW |
1205 | @r{(@var{R}_@var{s}/@var{k}_@var{R},@var{G}_@var{s}/@var{k}_@var{G}@var{B}_@var{s}/@var{k}_@var{B})}, |
1206 | @r{@var{A}_@var{s}/@var{k}_@var{A}} | |
8925f36f AW |
1207 | |
1208 | @item @code{GL_ONE_MINUS_SRC_COLOR} | |
3c9b6116 AW |
1209 | @r{(1,111)-(@var{R}_@var{s}/@var{k}_@var{R},@var{G}_@var{s}/@var{k}_@var{G}@var{B}_@var{s}/@var{k}_@var{B})}, |
1210 | @r{1-@var{A}_@var{s}/@var{k}_@var{A}} | |
8925f36f AW |
1211 | |
1212 | @item @code{GL_DST_COLOR} | |
3c9b6116 AW |
1213 | @r{(@var{R}_@var{d}/@var{k}_@var{R},@var{G}_@var{d}/@var{k}_@var{G}@var{B}_@var{d}/@var{k}_@var{B})}, |
1214 | @r{@var{A}_@var{d}/@var{k}_@var{A}} | |
8925f36f AW |
1215 | |
1216 | @item @code{GL_ONE_MINUS_DST_COLOR} | |
3c9b6116 AW |
1217 | @r{(1,11)-(@var{R}_@var{d}/@var{k}_@var{R},@var{G}_@var{d}/@var{k}_@var{G}@var{B}_@var{d}/@var{k}_@var{B})}, |
1218 | @r{1-@var{A}_@var{d}/@var{k}_@var{A}} | |
8925f36f AW |
1219 | |
1220 | @item @code{GL_SRC_ALPHA} | |
3c9b6116 AW |
1221 | @r{(@var{A}_@var{s}/@var{k}_@var{A},@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A})}, |
1222 | @r{@var{A}_@var{s}/@var{k}_@var{A}} | |
8925f36f AW |
1223 | |
1224 | @item @code{GL_ONE_MINUS_SRC_ALPHA} | |
3c9b6116 AW |
1225 | @r{(1,11)-(@var{A}_@var{s}/@var{k}_@var{A},@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A})}, |
1226 | @r{1-@var{A}_@var{s}/@var{k}_@var{A}} | |
8925f36f AW |
1227 | |
1228 | @item @code{GL_DST_ALPHA} | |
3c9b6116 AW |
1229 | @r{(@var{A}_@var{d}/@var{k}_@var{A},@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A})}, |
1230 | @r{@var{A}_@var{d}/@var{k}_@var{A}} | |
8925f36f AW |
1231 | |
1232 | @item @code{GL_ONE_MINUS_DST_ALPHA} | |
3c9b6116 AW |
1233 | @r{(1,11)-(@var{A}_@var{d}/@var{k}_@var{A},@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A})}, |
1234 | @r{1-@var{A}_@var{d}/@var{k}_@var{A}} | |
8925f36f AW |
1235 | |
1236 | @item @code{GL_CONSTANT_COLOR} | |
3c9b6116 AW |
1237 | @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c})}, |
1238 | @r{@var{A}_@var{c}} | |
8925f36f AW |
1239 | |
1240 | @item @code{GL_ONE_MINUS_CONSTANT_COLOR} | |
3c9b6116 AW |
1241 | @r{(1,11)-(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c})}, |
1242 | @r{1-@var{A}_@var{c}} | |
8925f36f AW |
1243 | |
1244 | @item @code{GL_CONSTANT_ALPHA} | |
3c9b6116 AW |
1245 | @r{(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c})}, |
1246 | @r{@var{A}_@var{c}} | |
8925f36f AW |
1247 | |
1248 | @item @code{GL_ONE_MINUS_CONSTANT_ALPHA} | |
3c9b6116 AW |
1249 | @r{(1,11)-(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c})}, |
1250 | @r{1-@var{A}_@var{c}} | |
8925f36f AW |
1251 | |
1252 | @item @code{GL_SRC_ALPHA_SATURATE} | |
3c9b6116 | 1253 | @r{(@var{i},@var{i}@var{i})}, @r{1} |
8925f36f AW |
1254 | |
1255 | @end table | |
1256 | ||
1257 | In the table, | |
1258 | ||
3c9b6116 | 1259 | @r{@var{i}=@var{min}(@var{A}_@var{s},1-@var{A}_@var{d},)} |
8925f36f AW |
1260 | |
1261 | To determine the blended RGBA values of a pixel when drawing in RGBA | |
1262 | mode, the system uses the following equations: | |
1263 | ||
3c9b6116 | 1264 | @r{@var{R}_@var{d}=@var{min}(@var{k}_@var{R},@var{R}_@var{s}@var{s}_@var{R}+@var{R}_@var{d}@var{d}_@var{R})}@r{@var{G}_@var{d}=@var{min}(@var{k}_@var{G},@var{G}_@var{s}@var{s}_@var{G}+@var{G}_@var{d}@var{d}_@var{G})}@r{@var{B}_@var{d}=@var{min}(@var{k}_@var{B},@var{B}_@var{s}@var{s}_@var{B}+@var{B}_@var{d}@var{d}_@var{B})}@r{@var{A}_@var{d}=@var{min}(@var{k}_@var{A},@var{A}_@var{s}@var{s}_@var{A}+@var{A}_@var{d}@var{d}_@var{A})} |
8925f36f AW |
1265 | |
1266 | Despite the apparent precision of the above equations, blending | |
1267 | arithmetic is not exactly specified, because blending operates with | |
c7b31271 | 1268 | imprecise integer color values. However, a blend factor that should be |
8925f36f | 1269 | equal to 1 is guaranteed not to modify its multiplicand, and a blend |
c7b31271 | 1270 | factor equal to 0 reduces its multiplicand to 0. For example, when |
8925f36f | 1271 | @var{srcRGB} is @code{GL_SRC_ALPHA}, @var{dstRGB} is |
3c9b6116 AW |
1272 | @code{GL_ONE_MINUS_SRC_ALPHA}, and @r{@var{A}_@var{s}} is equal to |
1273 | @r{@var{k}_@var{A}}, the equations reduce to simple replacement: | |
8925f36f | 1274 | |
3c9b6116 | 1275 | @r{@var{R}_@var{d}=@var{R}_@var{s}}@r{@var{G}_@var{d}=@var{G}_@var{s}}@r{@var{B}_@var{d}=@var{B}_@var{s}}@r{@var{A}_@var{d}=@var{A}_@var{s}} |
8925f36f AW |
1276 | |
1277 | ||
1278 | ||
8925f36f AW |
1279 | @code{GL_INVALID_ENUM} is generated if either @var{srcRGB} or |
1280 | @var{dstRGB} is not an accepted value. | |
1281 | ||
1282 | @code{GL_INVALID_OPERATION} is generated if @code{glBlendFuncSeparate} | |
1283 | is executed between the execution of @code{glBegin} and the | |
1284 | corresponding execution of @code{glEnd}. | |
1285 | ||
bb894c9d | 1286 | @end deftypefun |
8925f36f | 1287 | |
bb894c9d | 1288 | @deftypefun void glBlendFunc sfactor dfactor |
3c9b6116 AW |
1289 | Specify pixel arithmetic. |
1290 | ||
8925f36f AW |
1291 | @table @asis |
1292 | @item @var{sfactor} | |
1293 | Specifies how the red, green, blue, and alpha source blending factors | |
c7b31271 | 1294 | are computed. The following symbolic constants are accepted: |
8925f36f AW |
1295 | @code{GL_ZERO}, @code{GL_ONE}, @code{GL_SRC_COLOR}, |
1296 | @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_DST_COLOR}, | |
1297 | @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA}, | |
1298 | @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA}, | |
1299 | @code{GL_ONE_MINUS_DST_ALPHA}, @code{GL_CONSTANT_COLOR}, | |
1300 | @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA}, | |
1301 | @code{GL_ONE_MINUS_CONSTANT_ALPHA}, and @code{GL_SRC_ALPHA_SATURATE}. | |
1302 | The initial value is @code{GL_ONE}. | |
1303 | ||
1304 | @item @var{dfactor} | |
1305 | Specifies how the red, green, blue, and alpha destination blending | |
c7b31271 | 1306 | factors are computed. The following symbolic constants are accepted: |
8925f36f AW |
1307 | @code{GL_ZERO}, @code{GL_ONE}, @code{GL_SRC_COLOR}, |
1308 | @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_DST_COLOR}, | |
1309 | @code{GL_ONE_MINUS_DST_COLOR}, @code{GL_SRC_ALPHA}, | |
1310 | @code{GL_ONE_MINUS_SRC_ALPHA}, @code{GL_DST_ALPHA}, | |
c7b31271 | 1311 | @code{GL_ONE_MINUS_DST_ALPHA}. @code{GL_CONSTANT_COLOR}, |
8925f36f | 1312 | @code{GL_ONE_MINUS_CONSTANT_COLOR}, @code{GL_CONSTANT_ALPHA}, and |
c7b31271 DH |
1313 | @code{GL_ONE_MINUS_CONSTANT_ALPHA}. The initial value is |
1314 | @code{GL_ZERO}. | |
8925f36f AW |
1315 | |
1316 | @end table | |
1317 | ||
8925f36f AW |
1318 | In RGBA mode, pixels can be drawn using a function that blends the |
1319 | incoming (source) RGBA values with the RGBA values that are already in | |
c7b31271 DH |
1320 | the frame buffer (the destination values). Blending is initially |
1321 | disabled. Use @code{glEnable} and @code{glDisable} with argument | |
8925f36f AW |
1322 | @code{GL_BLEND} to enable and disable blending. |
1323 | ||
1324 | @code{glBlendFunc} defines the operation of blending when it is enabled. | |
1325 | @var{sfactor} specifies which method is used to scale the source color | |
c7b31271 DH |
1326 | components. @var{dfactor} specifies which method is used to scale the |
1327 | destination color components. The possible methods are described in the | |
1328 | following table. Each method defines four scale factors, one each for | |
1329 | red, green, blue, and alpha. In the table and in subsequent equations, | |
8925f36f | 1330 | source and destination color components are referred to as |
3c9b6116 | 1331 | @r{(@var{R}_@var{s},@var{G}_@var{s}@var{B}_@var{s}@var{A}_@var{s})} and |
c7b31271 | 1332 | @r{(@var{R}_@var{d},@var{G}_@var{d}@var{B}_@var{d}@var{A}_@var{d})}. The |
3c9b6116 AW |
1333 | color specified by @code{glBlendColor} is referred to as |
1334 | @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})}. | |
8925f36f | 1335 | They are understood to have integer values between 0 and |
3c9b6116 | 1336 | @r{(@var{k}_@var{R},@var{k}_@var{G}@var{k}_@var{B}@var{k}_@var{A})}, |
8925f36f AW |
1337 | where |
1338 | ||
3c9b6116 | 1339 | @r{@var{k}_@var{c}=2^@var{m}_@var{c},-1} |
8925f36f | 1340 | |
3c9b6116 | 1341 | and @r{(@var{m}_@var{R},@var{m}_@var{G}@var{m}_@var{B}@var{m}_@var{A})} |
8925f36f AW |
1342 | is the number of red, green, blue, and alpha bitplanes. |
1343 | ||
1344 | Source and destination scale factors are referred to as | |
3c9b6116 | 1345 | @r{(@var{s}_@var{R},@var{s}_@var{G}@var{s}_@var{B}@var{s}_@var{A})} and |
c7b31271 | 1346 | @r{(@var{d}_@var{R},@var{d}_@var{G}@var{d}_@var{B}@var{d}_@var{A})}. The |
3c9b6116 AW |
1347 | scale factors described in the table, denoted |
1348 | @r{(@var{f}_@var{R},@var{f}_@var{G}@var{f}_@var{B}@var{f}_@var{A})}, | |
c7b31271 | 1349 | represent either source or destination factors. All scale factors have |
3c9b6116 | 1350 | range @r{[0,1]}. |
8925f36f AW |
1351 | |
1352 | ||
1353 | ||
1354 | @table @asis | |
1355 | @item @strong{Parameter} | |
3c9b6116 | 1356 | @strong{@r{(@var{f}_@var{R},@var{f}_@var{G}@var{f}_@var{B}@var{f}_@var{A})}} |
8925f36f AW |
1357 | |
1358 | @item @code{GL_ZERO} | |
3c9b6116 | 1359 | @r{(0,000)} |
8925f36f AW |
1360 | |
1361 | @item @code{GL_ONE} | |
3c9b6116 | 1362 | @r{(1,111)} |
8925f36f AW |
1363 | |
1364 | @item @code{GL_SRC_COLOR} | |
3c9b6116 | 1365 | @r{(@var{R}_@var{s}/@var{k}_@var{R},@var{G}_@var{s}/@var{k}_@var{G}@var{B}_@var{s}/@var{k}_@var{B}@var{A}_@var{s}/@var{k}_@var{A})} |
8925f36f AW |
1366 | |
1367 | @item @code{GL_ONE_MINUS_SRC_COLOR} | |
3c9b6116 | 1368 | @r{(1,111)-(@var{R}_@var{s}/@var{k}_@var{R},@var{G}_@var{s}/@var{k}_@var{G}@var{B}_@var{s}/@var{k}_@var{B}@var{A}_@var{s}/@var{k}_@var{A})} |
8925f36f AW |
1369 | |
1370 | @item @code{GL_DST_COLOR} | |
3c9b6116 | 1371 | @r{(@var{R}_@var{d}/@var{k}_@var{R},@var{G}_@var{d}/@var{k}_@var{G}@var{B}_@var{d}/@var{k}_@var{B}@var{A}_@var{d}/@var{k}_@var{A})} |
8925f36f AW |
1372 | |
1373 | @item @code{GL_ONE_MINUS_DST_COLOR} | |
3c9b6116 | 1374 | @r{(1,111)-(@var{R}_@var{d}/@var{k}_@var{R},@var{G}_@var{d}/@var{k}_@var{G}@var{B}_@var{d}/@var{k}_@var{B}@var{A}_@var{d}/@var{k}_@var{A})} |
8925f36f AW |
1375 | |
1376 | @item @code{GL_SRC_ALPHA} | |
3c9b6116 | 1377 | @r{(@var{A}_@var{s}/@var{k}_@var{A},@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A})} |
8925f36f AW |
1378 | |
1379 | @item @code{GL_ONE_MINUS_SRC_ALPHA} | |
3c9b6116 | 1380 | @r{(1,111)-(@var{A}_@var{s}/@var{k}_@var{A},@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A}@var{A}_@var{s}/@var{k}_@var{A})} |
8925f36f AW |
1381 | |
1382 | @item @code{GL_DST_ALPHA} | |
3c9b6116 | 1383 | @r{(@var{A}_@var{d}/@var{k}_@var{A},@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A})} |
8925f36f AW |
1384 | |
1385 | @item @code{GL_ONE_MINUS_DST_ALPHA} | |
3c9b6116 | 1386 | @r{(1,111)-(@var{A}_@var{d}/@var{k}_@var{A},@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A}@var{A}_@var{d}/@var{k}_@var{A})} |
8925f36f AW |
1387 | |
1388 | @item @code{GL_CONSTANT_COLOR} | |
3c9b6116 | 1389 | @r{(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})} |
8925f36f AW |
1390 | |
1391 | @item @code{GL_ONE_MINUS_CONSTANT_COLOR} | |
3c9b6116 | 1392 | @r{(1,111)-(@var{R}_@var{c},@var{G}_@var{c}@var{B}_@var{c}@var{A}_@var{c})} |
8925f36f AW |
1393 | |
1394 | @item @code{GL_CONSTANT_ALPHA} | |
3c9b6116 | 1395 | @r{(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c}@var{A}_@var{c})} |
8925f36f AW |
1396 | |
1397 | @item @code{GL_ONE_MINUS_CONSTANT_ALPHA} | |
3c9b6116 | 1398 | @r{(1,111)-(@var{A}_@var{c},@var{A}_@var{c}@var{A}_@var{c}@var{A}_@var{c})} |
8925f36f AW |
1399 | |
1400 | @item @code{GL_SRC_ALPHA_SATURATE} | |
3c9b6116 | 1401 | @r{(@var{i},@var{i}@var{i}1)} |
8925f36f AW |
1402 | |
1403 | @end table | |
1404 | ||
1405 | In the table, | |
1406 | ||
3c9b6116 | 1407 | @r{@var{i}=@var{min}(@var{A}_@var{s},@var{k}_@var{A}-@var{A}_@var{d})/@var{k}_@var{A}} |
8925f36f AW |
1408 | |
1409 | To determine the blended RGBA values of a pixel when drawing in RGBA | |
1410 | mode, the system uses the following equations: | |
1411 | ||
3c9b6116 | 1412 | @r{@var{R}_@var{d}=@var{min}(@var{k}_@var{R},@var{R}_@var{s}@var{s}_@var{R}+@var{R}_@var{d}@var{d}_@var{R})}@r{@var{G}_@var{d}=@var{min}(@var{k}_@var{G},@var{G}_@var{s}@var{s}_@var{G}+@var{G}_@var{d}@var{d}_@var{G})}@r{@var{B}_@var{d}=@var{min}(@var{k}_@var{B},@var{B}_@var{s}@var{s}_@var{B}+@var{B}_@var{d}@var{d}_@var{B})}@r{@var{A}_@var{d}=@var{min}(@var{k}_@var{A},@var{A}_@var{s}@var{s}_@var{A}+@var{A}_@var{d}@var{d}_@var{A})} |
8925f36f AW |
1413 | |
1414 | Despite the apparent precision of the above equations, blending | |
1415 | arithmetic is not exactly specified, because blending operates with | |
c7b31271 | 1416 | imprecise integer color values. However, a blend factor that should be |
8925f36f | 1417 | equal to 1 is guaranteed not to modify its multiplicand, and a blend |
c7b31271 | 1418 | factor equal to 0 reduces its multiplicand to 0. For example, when |
8925f36f | 1419 | @var{sfactor} is @code{GL_SRC_ALPHA}, @var{dfactor} is |
3c9b6116 AW |
1420 | @code{GL_ONE_MINUS_SRC_ALPHA}, and @r{@var{A}_@var{s}} is equal to |
1421 | @r{@var{k}_@var{A}}, the equations reduce to simple replacement: | |
8925f36f | 1422 | |
3c9b6116 | 1423 | @r{@var{R}_@var{d}=@var{R}_@var{s}}@r{@var{G}_@var{d}=@var{G}_@var{s}}@r{@var{B}_@var{d}=@var{B}_@var{s}}@r{@var{A}_@var{d}=@var{A}_@var{s}} |
8925f36f AW |
1424 | |
1425 | ||
1426 | ||
8925f36f AW |
1427 | @code{GL_INVALID_ENUM} is generated if either @var{sfactor} or |
1428 | @var{dfactor} is not an accepted value. | |
1429 | ||
1430 | @code{GL_INVALID_OPERATION} is generated if @code{glBlendFunc} is | |
1431 | executed between the execution of @code{glBegin} and the corresponding | |
1432 | execution of @code{glEnd}. | |
1433 | ||
bb894c9d | 1434 | @end deftypefun |
8925f36f | 1435 | |
bb894c9d | 1436 | @deftypefun void glBufferData target size data usage |
3c9b6116 AW |
1437 | Creates and initializes a buffer object's data store. |
1438 | ||
8925f36f AW |
1439 | @table @asis |
1440 | @item @var{target} | |
c7b31271 | 1441 | Specifies the target buffer object. The symbolic constant must be |
8925f36f AW |
1442 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, |
1443 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
1444 | ||
1445 | @item @var{size} | |
1446 | Specifies the size in bytes of the buffer object's new data store. | |
1447 | ||
1448 | @item @var{data} | |
1449 | Specifies a pointer to data that will be copied into the data store for | |
1450 | initialization, or @code{NULL} if no data is to be copied. | |
1451 | ||
1452 | @item @var{usage} | |
c7b31271 | 1453 | Specifies the expected usage pattern of the data store. The symbolic |
8925f36f AW |
1454 | constant must be @code{GL_STREAM_DRAW}, @code{GL_STREAM_READ}, |
1455 | @code{GL_STREAM_COPY}, @code{GL_STATIC_DRAW}, @code{GL_STATIC_READ}, | |
1456 | @code{GL_STATIC_COPY}, @code{GL_DYNAMIC_DRAW}, @code{GL_DYNAMIC_READ}, | |
1457 | or @code{GL_DYNAMIC_COPY}. | |
1458 | ||
1459 | @end table | |
1460 | ||
8925f36f | 1461 | @code{glBufferData} creates a new data store for the buffer object |
c7b31271 DH |
1462 | currently bound to @var{target}. Any pre-existing data store is |
1463 | deleted. The new data store is created with the specified @var{size} in | |
1464 | bytes and @var{usage}. If @var{data} is not @code{NULL}, the data store | |
1465 | is initialized with data from this pointer. In its initial state, the | |
1466 | new data store is not mapped, it has a @code{NULL} mapped pointer, and | |
1467 | its mapped access is @code{GL_READ_WRITE}. | |
8925f36f AW |
1468 | |
1469 | @var{usage} is a hint to the GL implementation as to how a buffer | |
c7b31271 DH |
1470 | object's data store will be accessed. This enables the GL |
1471 | implementation to make more intelligent decisions that may significantly | |
1472 | impact buffer object performance. It does not, however, constrain the | |
1473 | actual usage of the data store. @var{usage} can be broken down into two | |
1474 | parts: first, the frequency of access (modification and usage), and | |
1475 | second, the nature of that access. The frequency of access may be one | |
1476 | of these: | |
8925f36f AW |
1477 | |
1478 | @table @asis | |
1479 | @item STREAM | |
1480 | The data store contents will be modified once and used at most a few | |
1481 | times. | |
1482 | ||
1483 | @item STATIC | |
1484 | The data store contents will be modified once and used many times. | |
1485 | ||
1486 | @item DYNAMIC | |
1487 | The data store contents will be modified repeatedly and used many times. | |
1488 | ||
1489 | @end table | |
1490 | ||
1491 | The nature of access may be one of these: | |
1492 | ||
1493 | @table @asis | |
1494 | @item DRAW | |
1495 | The data store contents are modified by the application, and used as the | |
1496 | source for GL drawing and image specification commands. | |
1497 | ||
1498 | @item READ | |
1499 | The data store contents are modified by reading data from the GL, and | |
1500 | used to return that data when queried by the application. | |
1501 | ||
1502 | @item COPY | |
1503 | The data store contents are modified by reading data from the GL, and | |
1504 | used as the source for GL drawing and image specification commands. | |
1505 | ||
1506 | @end table | |
1507 | ||
8925f36f AW |
1508 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
1509 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
1510 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
1511 | ||
1512 | @code{GL_INVALID_ENUM} is generated if @var{usage} is not | |
1513 | @code{GL_STREAM_DRAW}, @code{GL_STREAM_READ}, @code{GL_STREAM_COPY}, | |
1514 | @code{GL_STATIC_DRAW}, @code{GL_STATIC_READ}, @code{GL_STATIC_COPY}, | |
1515 | @code{GL_DYNAMIC_DRAW}, @code{GL_DYNAMIC_READ}, or | |
1516 | @code{GL_DYNAMIC_COPY}. | |
1517 | ||
1518 | @code{GL_INVALID_VALUE} is generated if @var{size} is negative. | |
1519 | ||
1520 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
1521 | name 0 is bound to @var{target}. | |
1522 | ||
1523 | @code{GL_OUT_OF_MEMORY} is generated if the GL is unable to create a | |
1524 | data store with the specified @var{size}. | |
1525 | ||
1526 | @code{GL_INVALID_OPERATION} is generated if @code{glBufferData} is | |
1527 | executed between the execution of @code{glBegin} and the corresponding | |
1528 | execution of @code{glEnd}. | |
1529 | ||
bb894c9d | 1530 | @end deftypefun |
8925f36f | 1531 | |
bb894c9d | 1532 | @deftypefun void glBufferSubData target offset size data |
3c9b6116 AW |
1533 | Updates a subset of a buffer object's data store. |
1534 | ||
8925f36f AW |
1535 | @table @asis |
1536 | @item @var{target} | |
c7b31271 | 1537 | Specifies the target buffer object. The symbolic constant must be |
8925f36f AW |
1538 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, |
1539 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
1540 | ||
1541 | @item @var{offset} | |
1542 | Specifies the offset into the buffer object's data store where data | |
1543 | replacement will begin, measured in bytes. | |
1544 | ||
1545 | @item @var{size} | |
1546 | Specifies the size in bytes of the data store region being replaced. | |
1547 | ||
1548 | @item @var{data} | |
1549 | Specifies a pointer to the new data that will be copied into the data | |
1550 | store. | |
1551 | ||
1552 | @end table | |
1553 | ||
8925f36f | 1554 | @code{glBufferSubData} redefines some or all of the data store for the |
c7b31271 | 1555 | buffer object currently bound to @var{target}. Data starting at byte |
8925f36f | 1556 | offset @var{offset} and extending for @var{size} bytes is copied to the |
c7b31271 | 1557 | data store from the memory pointed to by @var{data}. An error is thrown |
8925f36f AW |
1558 | if @var{offset} and @var{size} together define a range beyond the bounds |
1559 | of the buffer object's data store. | |
1560 | ||
8925f36f AW |
1561 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
1562 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
1563 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
1564 | ||
1565 | @code{GL_INVALID_VALUE} is generated if @var{offset} or @var{size} is | |
1566 | negative, or if together they define a region of memory that extends | |
1567 | beyond the buffer object's allocated data store. | |
1568 | ||
1569 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
1570 | name 0 is bound to @var{target}. | |
1571 | ||
1572 | @code{GL_INVALID_OPERATION} is generated if the buffer object being | |
1573 | updated is mapped. | |
1574 | ||
1575 | @code{GL_INVALID_OPERATION} is generated if @code{glBufferSubData} is | |
1576 | executed between the execution of @code{glBegin} and the corresponding | |
1577 | execution of @code{glEnd}. | |
1578 | ||
bb894c9d | 1579 | @end deftypefun |
8925f36f | 1580 | |
bb894c9d | 1581 | @deftypefun void glCallLists n type lists |
3c9b6116 AW |
1582 | Execute a list of display lists. |
1583 | ||
8925f36f AW |
1584 | @table @asis |
1585 | @item @var{n} | |
1586 | Specifies the number of display lists to be executed. | |
1587 | ||
1588 | @item @var{type} | |
c7b31271 | 1589 | Specifies the type of values in @var{lists}. Symbolic constants |
8925f36f AW |
1590 | @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, |
1591 | @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT}, | |
1592 | @code{GL_FLOAT}, @code{GL_2_BYTES}, @code{GL_3_BYTES}, and | |
1593 | @code{GL_4_BYTES} are accepted. | |
1594 | ||
1595 | @item @var{lists} | |
1596 | Specifies the address of an array of name offsets in the display list. | |
1597 | The pointer type is void because the offsets can be bytes, shorts, ints, | |
1598 | or floats, depending on the value of @var{type}. | |
1599 | ||
1600 | @end table | |
1601 | ||
8925f36f | 1602 | @code{glCallLists} causes each display list in the list of names passed |
c7b31271 | 1603 | as @var{lists} to be executed. As a result, the commands saved in each |
8925f36f | 1604 | display list are executed in order, just as if they were called without |
c7b31271 | 1605 | using a display list. Names of display lists that have not been defined |
8925f36f AW |
1606 | are ignored. |
1607 | ||
1608 | @code{glCallLists} provides an efficient means for executing more than | |
c7b31271 DH |
1609 | one display list. @var{type} allows lists with various name formats to |
1610 | be accepted. The formats are as follows: | |
8925f36f AW |
1611 | |
1612 | @table @asis | |
1613 | @item @code{GL_BYTE} | |
1614 | @var{lists} is treated as an array of signed bytes, each in the range | |
3c9b6116 | 1615 | @r{-128} through 127. |
8925f36f AW |
1616 | |
1617 | @item @code{GL_UNSIGNED_BYTE} | |
1618 | @var{lists} is treated as an array of unsigned bytes, each in the range | |
1619 | 0 through 255. | |
1620 | ||
1621 | @item @code{GL_SHORT} | |
1622 | @var{lists} is treated as an array of signed two-byte integers, each in | |
3c9b6116 | 1623 | the range @r{-32768} through 32767. |
8925f36f AW |
1624 | |
1625 | @item @code{GL_UNSIGNED_SHORT} | |
1626 | @var{lists} is treated as an array of unsigned two-byte integers, each | |
1627 | in the range 0 through 65535. | |
1628 | ||
1629 | @item @code{GL_INT} | |
1630 | @var{lists} is treated as an array of signed four-byte integers. | |
1631 | ||
1632 | @item @code{GL_UNSIGNED_INT} | |
1633 | @var{lists} is treated as an array of unsigned four-byte integers. | |
1634 | ||
1635 | @item @code{GL_FLOAT} | |
1636 | @var{lists} is treated as an array of four-byte floating-point values. | |
1637 | ||
1638 | @item @code{GL_2_BYTES} | |
c7b31271 DH |
1639 | @var{lists} is treated as an array of unsigned bytes. Each pair of |
1640 | bytes specifies a single display-list name. The value of the pair is | |
1641 | computed as 256 times the unsigned value of the first byte plus the | |
1642 | unsigned value of the second byte. | |
8925f36f AW |
1643 | |
1644 | @item @code{GL_3_BYTES} | |
c7b31271 DH |
1645 | @var{lists} is treated as an array of unsigned bytes. Each triplet of |
1646 | bytes specifies a single display-list name. The value of the triplet is | |
8925f36f AW |
1647 | computed as 65536 times the unsigned value of the first byte, plus 256 |
1648 | times the unsigned value of the second byte, plus the unsigned value of | |
1649 | the third byte. | |
1650 | ||
1651 | @item @code{GL_4_BYTES} | |
c7b31271 DH |
1652 | @var{lists} is treated as an array of unsigned bytes. Each quadruplet |
1653 | of bytes specifies a single display-list name. The value of the | |
1654 | quadruplet is computed as 16777216 times the unsigned value of the first | |
1655 | byte, plus 65536 times the unsigned value of the second byte, plus 256 | |
1656 | times the unsigned value of the third byte, plus the unsigned value of | |
1657 | the fourth byte. | |
8925f36f AW |
1658 | |
1659 | @end table | |
1660 | ||
c7b31271 | 1661 | The list of display-list names is not null-terminated. Rather, @var{n} |
8925f36f AW |
1662 | specifies how many names are to be taken from @var{lists}. |
1663 | ||
1664 | An additional level of indirection is made available with the | |
1665 | @code{glListBase} command, which specifies an unsigned offset that is | |
1666 | added to each display-list name specified in @var{lists} before that | |
1667 | display list is executed. | |
1668 | ||
c7b31271 | 1669 | @code{glCallLists} can appear inside a display list. To avoid the |
8925f36f AW |
1670 | possibility of infinite recursion resulting from display lists calling |
1671 | one another, a limit is placed on the nesting level of display lists | |
c7b31271 | 1672 | during display-list execution. This limit must be at least 64, and it |
8925f36f AW |
1673 | depends on the implementation. |
1674 | ||
1675 | GL state is not saved and restored across a call to @code{glCallLists}. | |
1676 | Thus, changes made to GL state during the execution of the display lists | |
c7b31271 | 1677 | remain after execution is completed. Use @code{glPushAttrib}, |
8925f36f AW |
1678 | @code{glPopAttrib}, @code{glPushMatrix}, and @code{glPopMatrix} to |
1679 | preserve GL state across @code{glCallLists} calls. | |
1680 | ||
8925f36f AW |
1681 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
1682 | ||
1683 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of | |
1684 | @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, | |
1685 | @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT}, | |
1686 | @code{GL_FLOAT}, @code{GL_2_BYTES}, @code{GL_3_BYTES}, | |
1687 | @code{GL_4_BYTES}. | |
1688 | ||
bb894c9d | 1689 | @end deftypefun |
8925f36f | 1690 | |
bb894c9d | 1691 | @deftypefun void glCallList list |
3c9b6116 AW |
1692 | Execute a display list. |
1693 | ||
8925f36f AW |
1694 | @table @asis |
1695 | @item @var{list} | |
1696 | Specifies the integer name of the display list to be executed. | |
1697 | ||
1698 | @end table | |
1699 | ||
c7b31271 | 1700 | @code{glCallList} causes the named display list to be executed. The |
8925f36f | 1701 | commands saved in the display list are executed in order, just as if |
c7b31271 | 1702 | they were called without using a display list. If @var{list} has not |
8925f36f AW |
1703 | been defined as a display list, @code{glCallList} is ignored. |
1704 | ||
c7b31271 | 1705 | @code{glCallList} can appear inside a display list. To avoid the |
8925f36f AW |
1706 | possibility of infinite recursion resulting from display lists calling |
1707 | one another, a limit is placed on the nesting level of display lists | |
c7b31271 DH |
1708 | during display-list execution. This limit is at least 64, and it |
1709 | depends on the implementation. | |
8925f36f AW |
1710 | |
1711 | GL state is not saved and restored across a call to @code{glCallList}. | |
1712 | Thus, changes made to GL state during the execution of a display list | |
c7b31271 | 1713 | remain after execution of the display list is completed. Use |
8925f36f AW |
1714 | @code{glPushAttrib}, @code{glPopAttrib}, @code{glPushMatrix}, and |
1715 | @code{glPopMatrix} to preserve GL state across @code{glCallList} calls. | |
1716 | ||
bb894c9d | 1717 | @end deftypefun |
8925f36f | 1718 | |
bb894c9d | 1719 | @deftypefun void glClearAccum red green blue alpha |
3c9b6116 AW |
1720 | Specify clear values for the accumulation buffer. |
1721 | ||
8925f36f AW |
1722 | @table @asis |
1723 | @item @var{red} | |
1724 | @itemx @var{green} | |
1725 | @itemx @var{blue} | |
1726 | @itemx @var{alpha} | |
1727 | Specify the red, green, blue, and alpha values used when the | |
c7b31271 | 1728 | accumulation buffer is cleared. The initial values are all 0. |
8925f36f AW |
1729 | |
1730 | @end table | |
1731 | ||
8925f36f AW |
1732 | @code{glClearAccum} specifies the red, green, blue, and alpha values |
1733 | used by @code{glClear} to clear the accumulation buffer. | |
1734 | ||
1735 | Values specified by @code{glClearAccum} are clamped to the range | |
3c9b6116 | 1736 | @r{[-1,1]}. |
8925f36f | 1737 | |
8925f36f AW |
1738 | @code{GL_INVALID_OPERATION} is generated if @code{glClearAccum} is |
1739 | executed between the execution of @code{glBegin} and the corresponding | |
1740 | execution of @code{glEnd}. | |
1741 | ||
bb894c9d | 1742 | @end deftypefun |
8925f36f | 1743 | |
bb894c9d | 1744 | @deftypefun void glClearColor red green blue alpha |
3c9b6116 AW |
1745 | Specify clear values for the color buffers. |
1746 | ||
8925f36f AW |
1747 | @table @asis |
1748 | @item @var{red} | |
1749 | @itemx @var{green} | |
1750 | @itemx @var{blue} | |
1751 | @itemx @var{alpha} | |
1752 | Specify the red, green, blue, and alpha values used when the color | |
c7b31271 | 1753 | buffers are cleared. The initial values are all 0. |
8925f36f AW |
1754 | |
1755 | @end table | |
1756 | ||
8925f36f | 1757 | @code{glClearColor} specifies the red, green, blue, and alpha values |
c7b31271 | 1758 | used by @code{glClear} to clear the color buffers. Values specified by |
3c9b6116 | 1759 | @code{glClearColor} are clamped to the range @r{[0,1]}. |
8925f36f | 1760 | |
8925f36f AW |
1761 | @code{GL_INVALID_OPERATION} is generated if @code{glClearColor} is |
1762 | executed between the execution of @code{glBegin} and the corresponding | |
1763 | execution of @code{glEnd}. | |
1764 | ||
bb894c9d | 1765 | @end deftypefun |
8925f36f | 1766 | |
bb894c9d | 1767 | @deftypefun void glClearDepth depth |
3c9b6116 AW |
1768 | Specify the clear value for the depth buffer. |
1769 | ||
8925f36f AW |
1770 | @table @asis |
1771 | @item @var{depth} | |
c7b31271 | 1772 | Specifies the depth value used when the depth buffer is cleared. The |
8925f36f AW |
1773 | initial value is 1. |
1774 | ||
1775 | @end table | |
1776 | ||
8925f36f | 1777 | @code{glClearDepth} specifies the depth value used by @code{glClear} to |
c7b31271 | 1778 | clear the depth buffer. Values specified by @code{glClearDepth} are |
3c9b6116 | 1779 | clamped to the range @r{[0,1]}. |
8925f36f | 1780 | |
8925f36f AW |
1781 | @code{GL_INVALID_OPERATION} is generated if @code{glClearDepth} is |
1782 | executed between the execution of @code{glBegin} and the corresponding | |
1783 | execution of @code{glEnd}. | |
1784 | ||
bb894c9d | 1785 | @end deftypefun |
8925f36f | 1786 | |
bb894c9d | 1787 | @deftypefun void glClearIndex c |
3c9b6116 AW |
1788 | Specify the clear value for the color index buffers. |
1789 | ||
8925f36f AW |
1790 | @table @asis |
1791 | @item @var{c} | |
c7b31271 | 1792 | Specifies the index used when the color index buffers are cleared. The |
8925f36f AW |
1793 | initial value is 0. |
1794 | ||
1795 | @end table | |
1796 | ||
8925f36f | 1797 | @code{glClearIndex} specifies the index used by @code{glClear} to clear |
c7b31271 | 1798 | the color index buffers. @var{c} is not clamped. Rather, @var{c} is |
8925f36f | 1799 | converted to a fixed-point value with unspecified precision to the right |
c7b31271 | 1800 | of the binary point. The integer part of this value is then masked with |
3c9b6116 AW |
1801 | @r{2^@var{m}-1}, where @r{@var{m}} is the number of bits in a color |
1802 | index stored in the frame buffer. | |
8925f36f | 1803 | |
8925f36f AW |
1804 | @code{GL_INVALID_OPERATION} is generated if @code{glClearIndex} is |
1805 | executed between the execution of @code{glBegin} and the corresponding | |
1806 | execution of @code{glEnd}. | |
1807 | ||
bb894c9d | 1808 | @end deftypefun |
8925f36f | 1809 | |
bb894c9d | 1810 | @deftypefun void glClearStencil s |
3c9b6116 AW |
1811 | Specify the clear value for the stencil buffer. |
1812 | ||
8925f36f AW |
1813 | @table @asis |
1814 | @item @var{s} | |
c7b31271 DH |
1815 | Specifies the index used when the stencil buffer is cleared. The |
1816 | initial value is 0. | |
8925f36f AW |
1817 | |
1818 | @end table | |
1819 | ||
8925f36f | 1820 | @code{glClearStencil} specifies the index used by @code{glClear} to |
c7b31271 | 1821 | clear the stencil buffer. @var{s} is masked with @r{2^@var{m}-1}, where |
3c9b6116 | 1822 | @r{@var{m}} is the number of bits in the stencil buffer. |
8925f36f | 1823 | |
8925f36f AW |
1824 | @code{GL_INVALID_OPERATION} is generated if @code{glClearStencil} is |
1825 | executed between the execution of @code{glBegin} and the corresponding | |
1826 | execution of @code{glEnd}. | |
1827 | ||
bb894c9d | 1828 | @end deftypefun |
8925f36f | 1829 | |
bb894c9d | 1830 | @deftypefun void glClear mask |
3c9b6116 AW |
1831 | Clear buffers to preset values. |
1832 | ||
8925f36f AW |
1833 | @table @asis |
1834 | @item @var{mask} | |
c7b31271 | 1835 | Bitwise OR of masks that indicate the buffers to be cleared. The four |
8925f36f AW |
1836 | masks are @code{GL_COLOR_BUFFER_BIT}, @code{GL_DEPTH_BUFFER_BIT}, |
1837 | @code{GL_ACCUM_BUFFER_BIT}, and @code{GL_STENCIL_BUFFER_BIT}. | |
1838 | ||
1839 | @end table | |
1840 | ||
8925f36f AW |
1841 | @code{glClear} sets the bitplane area of the window to values previously |
1842 | selected by @code{glClearColor}, @code{glClearIndex}, | |
1843 | @code{glClearDepth}, @code{glClearStencil}, and @code{glClearAccum}. | |
1844 | Multiple color buffers can be cleared simultaneously by selecting more | |
1845 | than one buffer at a time using @code{glDrawBuffer}. | |
1846 | ||
1847 | The pixel ownership test, the scissor test, dithering, and the buffer | |
c7b31271 DH |
1848 | writemasks affect the operation of @code{glClear}. The scissor box |
1849 | bounds the cleared region. Alpha function, blend function, logical | |
8925f36f AW |
1850 | operation, stenciling, texture mapping, and depth-buffering are ignored |
1851 | by @code{glClear}. | |
1852 | ||
1853 | @code{glClear} takes a single argument that is the bitwise OR of several | |
1854 | values indicating which buffer is to be cleared. | |
1855 | ||
1856 | The values are as follows: | |
1857 | ||
1858 | @table @asis | |
1859 | @item @code{GL_COLOR_BUFFER_BIT} | |
1860 | Indicates the buffers currently enabled for color writing. | |
1861 | ||
1862 | @item @code{GL_DEPTH_BUFFER_BIT} | |
1863 | Indicates the depth buffer. | |
1864 | ||
1865 | @item @code{GL_ACCUM_BUFFER_BIT} | |
1866 | Indicates the accumulation buffer. | |
1867 | ||
1868 | @item @code{GL_STENCIL_BUFFER_BIT} | |
1869 | Indicates the stencil buffer. | |
1870 | ||
1871 | @end table | |
1872 | ||
1873 | The value to which each buffer is cleared depends on the setting of the | |
1874 | clear value for that buffer. | |
1875 | ||
8925f36f AW |
1876 | @code{GL_INVALID_VALUE} is generated if any bit other than the four |
1877 | defined bits is set in @var{mask}. | |
1878 | ||
1879 | @code{GL_INVALID_OPERATION} is generated if @code{glClear} is executed | |
1880 | between the execution of @code{glBegin} and the corresponding execution | |
1881 | of @code{glEnd}. | |
1882 | ||
bb894c9d | 1883 | @end deftypefun |
8925f36f | 1884 | |
bb894c9d | 1885 | @deftypefun void glClientActiveTexture texture |
3c9b6116 AW |
1886 | Select active texture unit. |
1887 | ||
8925f36f AW |
1888 | @table @asis |
1889 | @item @var{texture} | |
c7b31271 DH |
1890 | Specifies which texture unit to make active. The number of texture |
1891 | units is implementation dependent, but must be at least two. | |
1892 | @var{texture} must be one of @code{GL_TEXTURE}@r{@var{i}}, where i | |
1893 | ranges from 0 to the value of @code{GL_MAX_TEXTURE_COORDS} - 1, which is | |
1894 | an implementation-dependent value. The initial value is | |
1895 | @code{GL_TEXTURE0}. | |
8925f36f AW |
1896 | |
1897 | @end table | |
1898 | ||
8925f36f AW |
1899 | @code{glClientActiveTexture} selects the vertex array client state |
1900 | parameters to be modified by @code{glTexCoordPointer}, and enabled or | |
1901 | disabled with @code{glEnableClientState} or @code{glDisableClientState}, | |
1902 | respectively, when called with a parameter of | |
1903 | @code{GL_TEXTURE_COORD_ARRAY}. | |
1904 | ||
8925f36f | 1905 | @code{GL_INVALID_ENUM} is generated if @var{texture} is not one of |
3c9b6116 | 1906 | @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to the value of |
8925f36f AW |
1907 | @code{GL_MAX_TEXTURE_COORDS} - 1. |
1908 | ||
bb894c9d | 1909 | @end deftypefun |
8925f36f | 1910 | |
bb894c9d | 1911 | @deftypefun void glClipPlane plane equation |
3c9b6116 AW |
1912 | Specify a plane against which all geometry is clipped. |
1913 | ||
8925f36f AW |
1914 | @table @asis |
1915 | @item @var{plane} | |
c7b31271 | 1916 | Specifies which clipping plane is being positioned. Symbolic names of |
8925f36f | 1917 | the form @code{GL_CLIP_PLANE}@var{i}, where @var{i} is an integer |
3c9b6116 | 1918 | between 0 and @code{GL_MAX_CLIP_PLANES}@r{-1}, are accepted. |
8925f36f AW |
1919 | |
1920 | @item @var{equation} | |
1921 | Specifies the address of an array of four double-precision | |
c7b31271 DH |
1922 | floating-point values. These values are interpreted as a plane |
1923 | equation. | |
8925f36f AW |
1924 | |
1925 | @end table | |
1926 | ||
8925f36f | 1927 | Geometry is always clipped against the boundaries of a six-plane frustum |
c7b31271 | 1928 | in @var{x}, @var{y}, and @var{z}. @code{glClipPlane} allows the |
8925f36f AW |
1929 | specification of additional planes, not necessarily perpendicular to the |
1930 | @var{x}, @var{y}, or @var{z} axis, against which all geometry is | |
c7b31271 DH |
1931 | clipped. To determine the maximum number of additional clipping planes, |
1932 | call @code{glGetIntegerv} with argument @code{GL_MAX_CLIP_PLANES}. All | |
1933 | implementations support at least six such clipping planes. Because the | |
8925f36f AW |
1934 | resulting clipping region is the intersection of the defined |
1935 | half-spaces, it is always convex. | |
1936 | ||
1937 | @code{glClipPlane} specifies a half-space using a four-component plane | |
c7b31271 | 1938 | equation. When @code{glClipPlane} is called, @var{equation} is |
8925f36f | 1939 | transformed by the inverse of the modelview matrix and stored in the |
c7b31271 DH |
1940 | resulting eye coordinates. Subsequent changes to the modelview matrix |
1941 | have no effect on the stored plane-equation components. If the dot | |
8925f36f AW |
1942 | product of the eye coordinates of a vertex with the stored plane |
1943 | equation components is positive or zero, the vertex is @var{in} with | |
c7b31271 | 1944 | respect to that clipping plane. Otherwise, it is @var{out}. |
8925f36f AW |
1945 | |
1946 | To enable and disable clipping planes, call @code{glEnable} and | |
1947 | @code{glDisable} with the argument @code{GL_CLIP_PLANE}@var{i}, where | |
1948 | @var{i} is the plane number. | |
1949 | ||
1950 | All clipping planes are initially defined as (0, 0, 0, 0) in eye | |
1951 | coordinates and are disabled. | |
1952 | ||
8925f36f AW |
1953 | @code{GL_INVALID_ENUM} is generated if @var{plane} is not an accepted |
1954 | value. | |
1955 | ||
1956 | @code{GL_INVALID_OPERATION} is generated if @code{glClipPlane} is | |
1957 | executed between the execution of @code{glBegin} and the corresponding | |
1958 | execution of @code{glEnd}. | |
1959 | ||
bb894c9d | 1960 | @end deftypefun |
8925f36f | 1961 | |
bb894c9d | 1962 | @deftypefun void glColorMask red green blue alpha |
3c9b6116 AW |
1963 | Enable and disable writing of frame buffer color components. |
1964 | ||
8925f36f AW |
1965 | @table @asis |
1966 | @item @var{red} | |
1967 | @itemx @var{green} | |
1968 | @itemx @var{blue} | |
1969 | @itemx @var{alpha} | |
1970 | Specify whether red, green, blue, and alpha can or cannot be written | |
c7b31271 | 1971 | into the frame buffer. The initial values are all @code{GL_TRUE}, |
8925f36f AW |
1972 | indicating that the color components can be written. |
1973 | ||
1974 | @end table | |
1975 | ||
8925f36f | 1976 | @code{glColorMask} specifies whether the individual color components in |
c7b31271 | 1977 | the frame buffer can or cannot be written. If @var{red} is |
8925f36f AW |
1978 | @code{GL_FALSE}, for example, no change is made to the red component of |
1979 | any pixel in any of the color buffers, regardless of the drawing | |
1980 | operation attempted. | |
1981 | ||
c7b31271 | 1982 | Changes to individual bits of components cannot be controlled. Rather, |
8925f36f AW |
1983 | changes are either enabled or disabled for entire color components. |
1984 | ||
8925f36f AW |
1985 | @code{GL_INVALID_OPERATION} is generated if @code{glColorMask} is |
1986 | executed between the execution of @code{glBegin} and the corresponding | |
1987 | execution of @code{glEnd}. | |
1988 | ||
bb894c9d | 1989 | @end deftypefun |
8925f36f | 1990 | |
bb894c9d | 1991 | @deftypefun void glColorMaterial face mode |
3c9b6116 AW |
1992 | Cause a material color to track the current color. |
1993 | ||
8925f36f AW |
1994 | @table @asis |
1995 | @item @var{face} | |
1996 | Specifies whether front, back, or both front and back material | |
c7b31271 DH |
1997 | parameters should track the current color. Accepted values are |
1998 | @code{GL_FRONT}, @code{GL_BACK}, and @code{GL_FRONT_AND_BACK}. The | |
8925f36f AW |
1999 | initial value is @code{GL_FRONT_AND_BACK}. |
2000 | ||
2001 | @item @var{mode} | |
2002 | Specifies which of several material parameters track the current color. | |
2003 | Accepted values are @code{GL_EMISSION}, @code{GL_AMBIENT}, | |
2004 | @code{GL_DIFFUSE}, @code{GL_SPECULAR}, and | |
c7b31271 | 2005 | @code{GL_AMBIENT_AND_DIFFUSE}. The initial value is |
8925f36f AW |
2006 | @code{GL_AMBIENT_AND_DIFFUSE}. |
2007 | ||
2008 | @end table | |
2009 | ||
8925f36f | 2010 | @code{glColorMaterial} specifies which material parameters track the |
c7b31271 | 2011 | current color. When @code{GL_COLOR_MATERIAL} is enabled, the material |
8925f36f AW |
2012 | parameter or parameters specified by @var{mode}, of the material or |
2013 | materials specified by @var{face}, track the current color at all times. | |
2014 | ||
2015 | To enable and disable @code{GL_COLOR_MATERIAL}, call @code{glEnable} and | |
2016 | @code{glDisable} with argument @code{GL_COLOR_MATERIAL}. | |
2017 | @code{GL_COLOR_MATERIAL} is initially disabled. | |
2018 | ||
8925f36f AW |
2019 | @code{GL_INVALID_ENUM} is generated if @var{face} or @var{mode} is not |
2020 | an accepted value. | |
2021 | ||
2022 | @code{GL_INVALID_OPERATION} is generated if @code{glColorMaterial} is | |
2023 | executed between the execution of @code{glBegin} and the corresponding | |
2024 | execution of @code{glEnd}. | |
2025 | ||
bb894c9d | 2026 | @end deftypefun |
8925f36f | 2027 | |
bb894c9d | 2028 | @deftypefun void glColorPointer size type stride pointer |
3c9b6116 AW |
2029 | Define an array of colors. |
2030 | ||
8925f36f AW |
2031 | @table @asis |
2032 | @item @var{size} | |
c7b31271 | 2033 | Specifies the number of components per color. Must be 3 or 4. The |
8925f36f AW |
2034 | initial value is 4. |
2035 | ||
2036 | @item @var{type} | |
c7b31271 | 2037 | Specifies the data type of each color component in the array. Symbolic |
8925f36f AW |
2038 | constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, |
2039 | @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT}, | |
c7b31271 DH |
2040 | @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value |
2041 | is @code{GL_FLOAT}. | |
8925f36f AW |
2042 | |
2043 | @item @var{stride} | |
c7b31271 DH |
2044 | Specifies the byte offset between consecutive colors. If @var{stride} |
2045 | is 0, the colors are understood to be tightly packed in the array. The | |
8925f36f AW |
2046 | initial value is 0. |
2047 | ||
2048 | @item @var{pointer} | |
2049 | Specifies a pointer to the first component of the first color element in | |
c7b31271 | 2050 | the array. The initial value is 0. |
8925f36f AW |
2051 | |
2052 | @end table | |
2053 | ||
8925f36f | 2054 | @code{glColorPointer} specifies the location and data format of an array |
c7b31271 DH |
2055 | of color components to use when rendering. @var{size} specifies the |
2056 | number of components per color, and must be 3 or 4. @var{type} | |
2057 | specifies the data type of each color component, and @var{stride} | |
2058 | specifies the byte stride from one color to the next, allowing vertices | |
2059 | and attributes to be packed into a single array or stored in separate | |
2060 | arrays. (Single-array storage may be more efficient on some | |
2061 | implementations; see @code{glInterleavedArrays}.) | |
8925f36f AW |
2062 | |
2063 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
2064 | target (see @code{glBindBuffer}) while a color array is specified, | |
2065 | @var{pointer} is treated as a byte offset into the buffer object's data | |
c7b31271 | 2066 | store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING}) |
8925f36f AW |
2067 | is saved as color vertex array client-side state |
2068 | (@code{GL_COLOR_ARRAY_BUFFER_BINDING}). | |
2069 | ||
2070 | When a color array is specified, @var{size}, @var{type}, @var{stride}, | |
2071 | and @var{pointer} are saved as client-side state, in addition to the | |
2072 | current vertex array buffer object binding. | |
2073 | ||
2074 | To enable and disable the color array, call @code{glEnableClientState} | |
2075 | and @code{glDisableClientState} with the argument @code{GL_COLOR_ARRAY}. | |
2076 | If enabled, the color array is used when @code{glDrawArrays}, | |
2077 | @code{glMultiDrawArrays}, @code{glDrawElements}, | |
2078 | @code{glMultiDrawElements}, @code{glDrawRangeElements}, or | |
2079 | @code{glArrayElement} is called. | |
2080 | ||
8925f36f AW |
2081 | @code{GL_INVALID_VALUE} is generated if @var{size} is not 3 or 4. |
2082 | ||
2083 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted | |
2084 | value. | |
2085 | ||
2086 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
2087 | ||
bb894c9d | 2088 | @end deftypefun |
8925f36f | 2089 | |
bb894c9d | 2090 | @deftypefun void glColorSubTable target start count format type data |
3c9b6116 AW |
2091 | Respecify a portion of a color table. |
2092 | ||
8925f36f AW |
2093 | @table @asis |
2094 | @item @var{target} | |
2095 | Must be one of @code{GL_COLOR_TABLE}, | |
2096 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or | |
2097 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
2098 | ||
2099 | @item @var{start} | |
2100 | The starting index of the portion of the color table to be replaced. | |
2101 | ||
2102 | @item @var{count} | |
2103 | The number of table entries to replace. | |
2104 | ||
2105 | @item @var{format} | |
c7b31271 | 2106 | The format of the pixel data in @var{data}. The allowable values are |
8925f36f AW |
2107 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, |
2108 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, | |
2109 | @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}. | |
2110 | ||
2111 | @item @var{type} | |
c7b31271 | 2112 | The type of the pixel data in @var{data}. The allowable values are |
8925f36f AW |
2113 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT}, |
2114 | @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT}, | |
2115 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
2116 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
2117 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
2118 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
2119 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
2120 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
2121 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
2122 | ||
2123 | @item @var{data} | |
2124 | Pointer to a one-dimensional array of pixel data that is processed to | |
2125 | replace the specified region of the color table. | |
2126 | ||
2127 | @end table | |
2128 | ||
8925f36f | 2129 | @code{glColorSubTable} is used to respecify a contiguous portion of a |
c7b31271 | 2130 | color table previously defined using @code{glColorTable}. The pixels |
8925f36f | 2131 | referenced by @var{data} replace the portion of the existing table from |
c7b31271 | 2132 | indices @var{start} to @r{@var{start}+@var{count}-1}, inclusive. This |
8925f36f | 2133 | region may not include any entries outside the range of the color table |
c7b31271 | 2134 | as it was originally specified. It is not an error to specify a |
8925f36f AW |
2135 | subtexture with width of 0, but such a specification has no effect. |
2136 | ||
2137 | If a non-zero named buffer object is bound to the | |
2138 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2139 | portion of a color table is respecified, @var{data} is treated as a byte | |
2140 | offset into the buffer object's data store. | |
2141 | ||
8925f36f AW |
2142 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
2143 | allowable values. | |
2144 | ||
2145 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
2146 | allowable values. | |
2147 | ||
2148 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
2149 | allowable values. | |
2150 | ||
2151 | @code{GL_INVALID_VALUE} is generated if | |
3c9b6116 | 2152 | @r{@var{start}+@var{count}>@var{width}}. |
8925f36f AW |
2153 | |
2154 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2155 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2156 | object's data store is currently mapped. | |
2157 | ||
2158 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2159 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2160 | would be unpacked from the buffer object such that the memory reads | |
2161 | required would exceed the data store size. | |
2162 | ||
2163 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2164 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
2165 | is not evenly divisible into the number of bytes needed to store in | |
2166 | memory a datum indicated by @var{type}. | |
2167 | ||
2168 | @code{GL_INVALID_OPERATION} is generated if @code{glColorSubTable} is | |
2169 | executed between the execution of @code{glBegin} and the corresponding | |
2170 | execution of @code{glEnd}. | |
2171 | ||
bb894c9d | 2172 | @end deftypefun |
8925f36f | 2173 | |
b002944d AW |
2174 | @deftypefun void glColorTableParameterfv target pname params |
2175 | @deftypefunx void glColorTableParameteriv target pname params | |
2176 | Set color lookup table parameters. | |
2177 | ||
2178 | @table @asis | |
2179 | @item @var{target} | |
c7b31271 | 2180 | The target color table. Must be @code{GL_COLOR_TABLE}, |
b002944d AW |
2181 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or |
2182 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
2183 | ||
2184 | @item @var{pname} | |
c7b31271 DH |
2185 | The symbolic name of a texture color lookup table parameter. Must be |
2186 | one of @code{GL_COLOR_TABLE_SCALE} or @code{GL_COLOR_TABLE_BIAS}. | |
b002944d AW |
2187 | |
2188 | @item @var{params} | |
2189 | A pointer to an array where the values of the parameters are stored. | |
2190 | ||
2191 | @end table | |
2192 | ||
2193 | @code{glColorTableParameter} is used to specify the scale factors and | |
2194 | bias terms applied to color components when they are loaded into a color | |
c7b31271 DH |
2195 | table. @var{target} indicates which color table the scale and bias |
2196 | terms apply to; it must be set to @code{GL_COLOR_TABLE}, | |
b002944d AW |
2197 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or |
2198 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
2199 | ||
2200 | @var{pname} must be @code{GL_COLOR_TABLE_SCALE} to set the scale | |
c7b31271 | 2201 | factors. In this case, @var{params} points to an array of four values, |
b002944d AW |
2202 | which are the scale factors for red, green, blue, and alpha, in that |
2203 | order. | |
2204 | ||
c7b31271 | 2205 | @var{pname} must be @code{GL_COLOR_TABLE_BIAS} to set the bias terms. In |
b002944d AW |
2206 | this case, @var{params} points to an array of four values, which are the |
2207 | bias terms for red, green, blue, and alpha, in that order. | |
2208 | ||
2209 | The color tables themselves are specified by calling | |
2210 | @code{glColorTable}. | |
2211 | ||
2212 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
2213 | not an acceptable value. | |
2214 | ||
2215 | @code{GL_INVALID_OPERATION} is generated if @code{glColorTableParameter} | |
2216 | is executed between the execution of @code{glBegin} and the | |
2217 | corresponding execution of @code{glEnd}. | |
2218 | ||
2219 | @end deftypefun | |
2220 | ||
bb894c9d | 2221 | @deftypefun void glColorTable target internalformat width format type data |
3c9b6116 AW |
2222 | Define a color lookup table. |
2223 | ||
8925f36f AW |
2224 | @table @asis |
2225 | @item @var{target} | |
2226 | Must be one of @code{GL_COLOR_TABLE}, | |
2227 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, | |
2228 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{GL_PROXY_COLOR_TABLE}, | |
2229 | @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or | |
2230 | @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}. | |
2231 | ||
2232 | @item @var{internalformat} | |
c7b31271 | 2233 | The internal format of the color table. The allowable values are |
8925f36f AW |
2234 | @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, |
2235 | @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
2236 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
2237 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
2238 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
2239 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
2240 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY}, | |
2241 | @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12}, | |
2242 | @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
2243 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
2244 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
2245 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
2246 | @code{GL_RGBA12}, and @code{GL_RGBA16}. | |
2247 | ||
2248 | @item @var{width} | |
2249 | The number of entries in the color lookup table specified by @var{data}. | |
2250 | ||
2251 | @item @var{format} | |
c7b31271 | 2252 | The format of the pixel data in @var{data}. The allowable values are |
8925f36f AW |
2253 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, |
2254 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, | |
2255 | @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}. | |
2256 | ||
2257 | @item @var{type} | |
c7b31271 | 2258 | The type of the pixel data in @var{data}. The allowable values are |
8925f36f AW |
2259 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT}, |
2260 | @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT}, | |
2261 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
2262 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
2263 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
2264 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
2265 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
2266 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
2267 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
2268 | ||
2269 | @item @var{data} | |
2270 | Pointer to a one-dimensional array of pixel data that is processed to | |
2271 | build the color table. | |
2272 | ||
2273 | @end table | |
2274 | ||
8925f36f AW |
2275 | @code{glColorTable} may be used in two ways: to test the actual size and |
2276 | color resolution of a lookup table given a particular set of parameters, | |
c7b31271 | 2277 | or to load the contents of a color lookup table. Use the targets |
8925f36f AW |
2278 | @code{GL_PROXY_*} for the first case and the other targets for the |
2279 | second case. | |
2280 | ||
2281 | If a non-zero named buffer object is bound to the | |
2282 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2283 | color table is specified, @var{data} is treated as a byte offset into | |
2284 | the buffer object's data store. | |
2285 | ||
2286 | If @var{target} is @code{GL_COLOR_TABLE}, | |
2287 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or | |
2288 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{glColorTable} builds a | |
c7b31271 DH |
2289 | color lookup table from an array of pixels. The pixel array specified |
2290 | by @var{width}, @var{format}, @var{type}, and @var{data} is extracted | |
2291 | from memory and processed just as if @code{glDrawPixels} were called, | |
2292 | but processing stops after the final expansion to RGBA is completed. | |
8925f36f AW |
2293 | |
2294 | The four scale parameters and the four bias parameters that are defined | |
2295 | for the table are then used to scale and bias the R, G, B, and A | |
c7b31271 DH |
2296 | components of each pixel. (Use @code{glColorTableParameter} to set |
2297 | these scale and bias parameters.) | |
8925f36f | 2298 | |
c7b31271 | 2299 | Next, the R, G, B, and A values are clamped to the range @r{[0,1]}. Each |
3c9b6116 | 2300 | pixel is then converted to the internal format specified by |
c7b31271 | 2301 | @var{internalformat}. This conversion simply maps the component values |
8925f36f | 2302 | of the pixel (R, G, B, and A) to the values included in the internal |
c7b31271 | 2303 | format (red, green, blue, alpha, luminance, and intensity). The mapping |
8925f36f AW |
2304 | is as follows: |
2305 | ||
2306 | ||
2307 | ||
2308 | @table @asis | |
2309 | @item @strong{Internal Format} | |
2310 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
2311 | @strong{Luminance}, @strong{Intensity} | |
2312 | ||
2313 | @item @code{GL_ALPHA} | |
2314 | , , , A , , | |
2315 | ||
2316 | @item @code{GL_LUMINANCE} | |
2317 | , , , , R , | |
2318 | ||
2319 | @item @code{GL_LUMINANCE_ALPHA} | |
2320 | , , , A , R , | |
2321 | ||
2322 | @item @code{GL_INTENSITY} | |
2323 | , , , , , R | |
2324 | ||
2325 | @item @code{GL_RGB} | |
2326 | R , G , B , , , | |
2327 | ||
2328 | @item @code{GL_RGBA} | |
2329 | R , G , B , A , , | |
2330 | ||
2331 | @end table | |
2332 | ||
2333 | Finally, the red, green, blue, alpha, luminance, and/or intensity | |
c7b31271 | 2334 | components of the resulting pixels are stored in the color table. They |
8925f36f | 2335 | form a one-dimensional table with indices in the range |
3c9b6116 | 2336 | @r{[0,@var{width}-1]}. |
8925f36f AW |
2337 | |
2338 | If @var{target} is @code{GL_PROXY_*}, @code{glColorTable} recomputes and | |
2339 | stores the values of the proxy color table's state variables | |
2340 | @code{GL_COLOR_TABLE_FORMAT}, @code{GL_COLOR_TABLE_WIDTH}, | |
2341 | @code{GL_COLOR_TABLE_RED_SIZE}, @code{GL_COLOR_TABLE_GREEN_SIZE}, | |
2342 | @code{GL_COLOR_TABLE_BLUE_SIZE}, @code{GL_COLOR_TABLE_ALPHA_SIZE}, | |
2343 | @code{GL_COLOR_TABLE_LUMINANCE_SIZE}, and | |
c7b31271 DH |
2344 | @code{GL_COLOR_TABLE_INTENSITY_SIZE}. There is no effect on the image |
2345 | or state of any actual color table. If the specified color table is too | |
8925f36f | 2346 | large to be supported, then all the proxy state variables listed above |
c7b31271 | 2347 | are set to zero. Otherwise, the color table could be supported by |
8925f36f AW |
2348 | @code{glColorTable} using the corresponding non-proxy target, and the |
2349 | proxy state variables are set as if that target were being defined. | |
2350 | ||
2351 | The proxy state variables can be retrieved by calling | |
c7b31271 | 2352 | @code{glGetColorTableParameter} with a target of @code{GL_PROXY_*}. This |
8925f36f AW |
2353 | allows the application to decide if a particular @code{glColorTable} |
2354 | command would succeed, and to determine what the resulting color table | |
2355 | attributes would be. | |
2356 | ||
2357 | If a color table is enabled, and its width is non-zero, then its | |
2358 | contents are used to replace a subset of the components of each RGBA | |
2359 | pixel group, based on the internal format of the table. | |
2360 | ||
2361 | Each pixel group has color components (R, G, B, A) that are in the range | |
c7b31271 DH |
2362 | @r{[0.0,1.0]}. The color components are rescaled to the size of the |
2363 | color lookup table to form an index. Then a subset of the components | |
8925f36f | 2364 | based on the internal format of the table are replaced by the table |
c7b31271 | 2365 | entry selected by that index. If the color components and contents of |
8925f36f AW |
2366 | the table are represented as follows: |
2367 | ||
2368 | ||
2369 | ||
2370 | @table @asis | |
2371 | @item @strong{Representation} | |
2372 | @strong{Meaning} | |
2373 | ||
2374 | @item @code{r} | |
2375 | Table index computed from @code{R} | |
2376 | ||
2377 | @item @code{g} | |
2378 | Table index computed from @code{G} | |
2379 | ||
2380 | @item @code{b} | |
2381 | Table index computed from @code{B} | |
2382 | ||
2383 | @item @code{a} | |
2384 | Table index computed from @code{A} | |
2385 | ||
2386 | @item @code{L[i]} | |
2387 | Luminance value at table index @code{i} | |
2388 | ||
2389 | @item @code{I[i]} | |
2390 | Intensity value at table index @code{i} | |
2391 | ||
2392 | @item @code{R[i]} | |
2393 | Red value at table index @code{i} | |
2394 | ||
2395 | @item @code{G[i]} | |
2396 | Green value at table index @code{i} | |
2397 | ||
2398 | @item @code{B[i]} | |
2399 | Blue value at table index @code{i} | |
2400 | ||
2401 | @item @code{A[i]} | |
2402 | Alpha value at table index @code{i} | |
2403 | ||
2404 | @end table | |
2405 | ||
2406 | then the result of color table lookup is as follows: | |
2407 | ||
2408 | ||
2409 | ||
2410 | @table @asis | |
2411 | @item @strong{} | |
2412 | @strong{Resulting Texture Components} | |
2413 | ||
2414 | @item @strong{Table Internal Format} | |
2415 | @strong{R}, @strong{G}, @strong{B}, @strong{A} | |
2416 | ||
2417 | @item @code{GL_ALPHA} | |
2418 | @code{R}, @code{G}, @code{B}, @code{A[a]} | |
2419 | ||
2420 | @item @code{GL_LUMINANCE} | |
2421 | @code{L[r]}, @code{L[g]}, @code{L[b]}, @code{At} | |
2422 | ||
2423 | @item @code{GL_LUMINANCE_ALPHA} | |
2424 | @code{L[r]}, @code{L[g]}, @code{L[b]}, @code{A[a]} | |
2425 | ||
2426 | @item @code{GL_INTENSITY} | |
2427 | @code{I[r]}, @code{I[g]}, @code{I[b]}, @code{I[a]} | |
2428 | ||
2429 | @item @code{GL_RGB} | |
2430 | @code{R[r]}, @code{G[g]}, @code{B[b]}, @code{A} | |
2431 | ||
2432 | @item @code{GL_RGBA} | |
2433 | @code{R[r]}, @code{G[g]}, @code{B[b]}, @code{A[a]} | |
2434 | ||
2435 | @end table | |
2436 | ||
2437 | When @code{GL_COLOR_TABLE} is enabled, the colors resulting from the | |
2438 | pixel map operation (if it is enabled) are mapped by the color lookup | |
c7b31271 | 2439 | table before being passed to the convolution operation. The colors |
8925f36f AW |
2440 | resulting from the convolution operation are modified by the post |
2441 | convolution color lookup table when | |
c7b31271 DH |
2442 | @code{GL_POST_CONVOLUTION_COLOR_TABLE} is enabled. These modified |
2443 | colors are then sent to the color matrix operation. Finally, if | |
8925f36f AW |
2444 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} is enabled, the colors resulting |
2445 | from the color matrix operation are mapped by the post color matrix | |
2446 | color lookup table before being used by the histogram operation. | |
2447 | ||
2448 | ||
2449 | ||
8925f36f AW |
2450 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
2451 | allowable values. | |
2452 | ||
2453 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
2454 | of the allowable values. | |
2455 | ||
2456 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
2457 | allowable values. | |
2458 | ||
2459 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
2460 | allowable values. | |
2461 | ||
2462 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero. | |
2463 | ||
2464 | @code{GL_TABLE_TOO_LARGE} is generated if the requested color table is | |
2465 | too large to be supported by the implementation, and @var{target} is not | |
2466 | a @code{GL_PROXY_*} target. | |
2467 | ||
2468 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2469 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2470 | object's data store is currently mapped. | |
2471 | ||
2472 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2473 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2474 | would be unpacked from the buffer object such that the memory reads | |
2475 | required would exceed the data store size. | |
2476 | ||
2477 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2478 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
2479 | is not evenly divisible into the number of bytes needed to store in | |
2480 | memory a datum indicated by @var{type}. | |
2481 | ||
2482 | @code{GL_INVALID_OPERATION} is generated if @code{glColorTable} is | |
2483 | executed between the execution of @code{glBegin} and the corresponding | |
2484 | execution of @code{glEnd}. | |
2485 | ||
bb894c9d | 2486 | @end deftypefun |
8925f36f | 2487 | |
d172eed9 AW |
2488 | @deftypefun void glColor3b red green blue |
2489 | @deftypefunx void glColor3s red green blue | |
2490 | @deftypefunx void glColor3i red green blue | |
ca09631c | 2491 | @deftypefunx void glColor3f red green blue |
d172eed9 AW |
2492 | @deftypefunx void glColor3d red green blue |
2493 | @deftypefunx void glColor3ub red green blue | |
2494 | @deftypefunx void glColor3us red green blue | |
bb894c9d | 2495 | @deftypefunx void glColor3ui red green blue |
d172eed9 AW |
2496 | @deftypefunx void glColor4b red green blue alpha |
2497 | @deftypefunx void glColor4s red green blue alpha | |
bb894c9d | 2498 | @deftypefunx void glColor4i red green blue alpha |
ca09631c | 2499 | @deftypefunx void glColor4f red green blue alpha |
d172eed9 AW |
2500 | @deftypefunx void glColor4d red green blue alpha |
2501 | @deftypefunx void glColor4ub red green blue alpha | |
2502 | @deftypefunx void glColor4us red green blue alpha | |
bb894c9d | 2503 | @deftypefunx void glColor4ui red green blue alpha |
d172eed9 AW |
2504 | @deftypefunx void glColor3bv v |
2505 | @deftypefunx void glColor3sv v | |
2506 | @deftypefunx void glColor3iv v | |
2507 | @deftypefunx void glColor3fv v | |
2508 | @deftypefunx void glColor3dv v | |
2509 | @deftypefunx void glColor3ubv v | |
2510 | @deftypefunx void glColor3usv v | |
2511 | @deftypefunx void glColor3uiv v | |
2512 | @deftypefunx void glColor4bv v | |
2513 | @deftypefunx void glColor4sv v | |
2514 | @deftypefunx void glColor4iv v | |
2515 | @deftypefunx void glColor4fv v | |
2516 | @deftypefunx void glColor4dv v | |
2517 | @deftypefunx void glColor4ubv v | |
2518 | @deftypefunx void glColor4usv v | |
2519 | @deftypefunx void glColor4uiv v | |
3c9b6116 AW |
2520 | Set the current color. |
2521 | ||
8925f36f AW |
2522 | @table @asis |
2523 | @item @var{red} | |
2524 | @itemx @var{green} | |
2525 | @itemx @var{blue} | |
2526 | Specify new red, green, and blue values for the current color. | |
2527 | ||
2528 | @item @var{alpha} | |
c7b31271 | 2529 | Specifies a new alpha value for the current color. Included only in the |
8925f36f AW |
2530 | four-argument @code{glColor4} commands. |
2531 | ||
2532 | @end table | |
2533 | ||
8925f36f | 2534 | The GL stores both a current single-valued color index and a current |
c7b31271 DH |
2535 | four-valued RGBA color. @code{glColor} sets a new four-valued RGBA |
2536 | color. @code{glColor} has two major variants: @code{glColor3} and | |
2537 | @code{glColor4}. @code{glColor3} variants specify new red, green, and | |
8925f36f | 2538 | blue values explicitly and set the current alpha value to 1.0 (full |
c7b31271 | 2539 | intensity) implicitly. @code{glColor4} variants specify all four color |
8925f36f AW |
2540 | components explicitly. |
2541 | ||
2542 | @code{glColor3b}, @code{glColor4b}, @code{glColor3s}, @code{glColor4s}, | |
2543 | @code{glColor3i}, and @code{glColor4i} take three or four signed byte, | |
c7b31271 DH |
2544 | short, or long integers as arguments. When @strong{v} is appended to |
2545 | the name, the color commands can take a pointer to an array of such | |
2546 | values. | |
8925f36f AW |
2547 | |
2548 | Current color values are stored in floating-point format, with | |
c7b31271 | 2549 | unspecified mantissa and exponent sizes. Unsigned integer color |
8925f36f AW |
2550 | components, when specified, are linearly mapped to floating-point values |
2551 | such that the largest representable value maps to 1.0 (full intensity), | |
c7b31271 | 2552 | and 0 maps to 0.0 (zero intensity). Signed integer color components, |
8925f36f AW |
2553 | when specified, are linearly mapped to floating-point values such that |
2554 | the most positive representable value maps to 1.0, and the most negative | |
c7b31271 | 2555 | representable value maps to @r{-1.0}. (Note that this mapping does not |
3c9b6116 | 2556 | convert 0 precisely to 0.0.) Floating-point values are mapped directly. |
8925f36f AW |
2557 | |
2558 | Neither floating-point nor signed integer values are clamped to the | |
c7b31271 | 2559 | range @r{[0,1]} before the current color is updated. However, color |
8925f36f AW |
2560 | components are clamped to this range before they are interpolated or |
2561 | written into a color buffer. | |
2562 | ||
bb894c9d | 2563 | @end deftypefun |
8925f36f | 2564 | |
bb894c9d | 2565 | @deftypefun void glCompileShader shader |
3c9b6116 AW |
2566 | Compiles a shader object. |
2567 | ||
8925f36f AW |
2568 | @table @asis |
2569 | @item @var{shader} | |
2570 | Specifies the shader object to be compiled. | |
2571 | ||
2572 | @end table | |
2573 | ||
8925f36f AW |
2574 | @code{glCompileShader} compiles the source code strings that have been |
2575 | stored in the shader object specified by @var{shader}. | |
2576 | ||
2577 | The compilation status will be stored as part of the shader object's | |
c7b31271 | 2578 | state. This value will be set to @code{GL_TRUE} if the shader was |
8925f36f | 2579 | compiled without errors and is ready for use, and @code{GL_FALSE} |
c7b31271 | 2580 | otherwise. It can be queried by calling @code{glGetShader} with |
8925f36f AW |
2581 | arguments @var{shader} and @code{GL_COMPILE_STATUS}. |
2582 | ||
2583 | Compilation of a shader can fail for a number of reasons as specified by | |
c7b31271 | 2584 | the OpenGL Shading Language Specification. Whether or not the |
8925f36f AW |
2585 | compilation was successful, information about the compilation can be |
2586 | obtained from the shader object's information log by calling | |
2587 | @code{glGetShaderInfoLog}. | |
2588 | ||
8925f36f AW |
2589 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
2590 | generated by OpenGL. | |
2591 | ||
2592 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
2593 | object. | |
2594 | ||
2595 | @code{GL_INVALID_OPERATION} is generated if @code{glCompileShader} is | |
2596 | executed between the execution of @code{glBegin} and the corresponding | |
2597 | execution of @code{glEnd}. | |
2598 | ||
bb894c9d | 2599 | @end deftypefun |
8925f36f | 2600 | |
bb894c9d | 2601 | @deftypefun void glCompressedTexImage1D target level internalformat width border imageSize data |
3c9b6116 AW |
2602 | Specify a one-dimensional texture image in a compressed format. |
2603 | ||
8925f36f AW |
2604 | @table @asis |
2605 | @item @var{target} | |
c7b31271 | 2606 | Specifies the target texture. Must be @code{GL_TEXTURE_1D} or |
8925f36f AW |
2607 | @code{GL_PROXY_TEXTURE_1D}. |
2608 | ||
2609 | @item @var{level} | |
c7b31271 | 2610 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
2611 | Level @var{n} is the @var{n}th mipmap reduction image. |
2612 | ||
2613 | @item @var{internalformat} | |
2614 | Specifies the format of the compressed image data stored at address | |
2615 | @var{data}. | |
2616 | ||
2617 | @item @var{width} | |
c7b31271 | 2618 | Specifies the width of the texture image including the border if any. If |
8925f36f | 2619 | the GL version does not support non-power-of-two sizes, this value must |
c7b31271 | 2620 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
3c9b6116 AW |
2621 | implementations support texture images that are at least 64 texels wide. |
2622 | The height of the 1D texture image is 1. | |
8925f36f AW |
2623 | |
2624 | @item @var{border} | |
c7b31271 | 2625 | Specifies the width of the border. Must be either 0 or 1. |
8925f36f AW |
2626 | |
2627 | @item @var{imageSize} | |
2628 | Specifies the number of unsigned bytes of image data starting at the | |
2629 | address specified by @var{data}. | |
2630 | ||
2631 | @item @var{data} | |
2632 | Specifies a pointer to the compressed image data in memory. | |
2633 | ||
2634 | @end table | |
2635 | ||
8925f36f | 2636 | Texturing maps a portion of a specified texture image onto each |
c7b31271 | 2637 | graphical primitive for which texturing is enabled. To enable and |
8925f36f AW |
2638 | disable one-dimensional texturing, call @code{glEnable} and |
2639 | @code{glDisable} with argument @code{GL_TEXTURE_1D}. | |
2640 | ||
2641 | @code{glCompressedTexImage1D} loads a previously defined, and retrieved, | |
2642 | compressed one-dimensional texture image if @var{target} is | |
2643 | @code{GL_TEXTURE_1D} (see @code{glTexImage1D}). | |
2644 | ||
2645 | If @var{target} is @code{GL_PROXY_TEXTURE_1D}, no data is read from | |
2646 | @var{data}, but all of the texture image state is recalculated, checked | |
2647 | for consistency, and checked against the implementation's capabilities. | |
2648 | If the implementation cannot handle a texture of the requested texture | |
2649 | size, it sets all of the image state to 0, but does not generate an | |
c7b31271 | 2650 | error (see @code{glGetError}). To query for an entire mipmap array, use |
8925f36f AW |
2651 | an image array level greater than or equal to 1. |
2652 | ||
2653 | @var{internalformat} must be extension-specified compressed-texture | |
c7b31271 | 2654 | format. When a texture is loaded with @code{glTexImage1D} using a |
8925f36f | 2655 | generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}) the |
c7b31271 | 2656 | GL selects from one of its extensions supporting compressed textures. In |
8925f36f AW |
2657 | order to load the compressed texture image using |
2658 | @code{glCompressedTexImage1D}, query the compressed texture image's size | |
2659 | and format using @code{glGetTexLevelParameter}. | |
2660 | ||
2661 | If a non-zero named buffer object is bound to the | |
2662 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2663 | texture image is specified, @var{data} is treated as a byte offset into | |
2664 | the buffer object's data store. | |
2665 | ||
8925f36f AW |
2666 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of |
2667 | the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
2668 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
2669 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or | |
2670 | @code{GL_COMPRESSED_RGBA}. | |
2671 | ||
2672 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
2673 | consistent with the format, dimensions, and contents of the specified | |
2674 | compressed image data. | |
2675 | ||
2676 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
2677 | not supported by the specific compressed internal format as specified in | |
2678 | the specific texture compression extension. | |
2679 | ||
2680 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2681 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2682 | object's data store is currently mapped. | |
2683 | ||
2684 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2685 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2686 | would be unpacked from the buffer object such that the memory reads | |
2687 | required would exceed the data store size. | |
2688 | ||
2689 | @code{GL_INVALID_OPERATION} is generated if | |
2690 | @code{glCompressedTexImage1D} is executed between the execution of | |
2691 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
2692 | ||
2693 | Undefined results, including abnormal program termination, are generated | |
2694 | if @var{data} is not encoded in a manner consistent with the extension | |
2695 | specification defining the internal compression format. | |
2696 | ||
bb894c9d | 2697 | @end deftypefun |
8925f36f | 2698 | |
bb894c9d | 2699 | @deftypefun void glCompressedTexImage2D target level internalformat width height border imageSize data |
3c9b6116 AW |
2700 | Specify a two-dimensional texture image in a compressed format. |
2701 | ||
8925f36f AW |
2702 | @table @asis |
2703 | @item @var{target} | |
c7b31271 | 2704 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, |
8925f36f AW |
2705 | @code{GL_PROXY_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, |
2706 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
2707 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
2708 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
2709 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, | |
2710 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or | |
2711 | @code{GL_PROXY_TEXTURE_CUBE_MAP}. | |
2712 | ||
2713 | @item @var{level} | |
c7b31271 | 2714 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
2715 | Level @var{n} is the @var{n}th mipmap reduction image. |
2716 | ||
2717 | @item @var{internalformat} | |
2718 | Specifies the format of the compressed image data stored at address | |
2719 | @var{data}. | |
2720 | ||
2721 | @item @var{width} | |
c7b31271 | 2722 | Specifies the width of the texture image including the border if any. If |
8925f36f | 2723 | the GL version does not support non-power-of-two sizes, this value must |
c7b31271 | 2724 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
3c9b6116 AW |
2725 | implementations support 2D texture images that are at least 64 texels |
2726 | wide and cube-mapped texture images that are at least 16 texels wide. | |
8925f36f AW |
2727 | |
2728 | @item @var{height} | |
2729 | Specifies the height of the texture image including the border if any. | |
2730 | If the GL version does not support non-power-of-two sizes, this value | |
3c9b6116 | 2731 | must be Must be @r{2^@var{n}+2(@var{border},)} for some integer |
c7b31271 | 2732 | @r{@var{n}}. All implementations support 2D texture images that are at |
3c9b6116 AW |
2733 | least 64 texels high and cube-mapped texture images that are at least 16 |
2734 | texels high. | |
8925f36f AW |
2735 | |
2736 | @item @var{border} | |
c7b31271 | 2737 | Specifies the width of the border. Must be either 0 or 1. |
8925f36f AW |
2738 | |
2739 | @item @var{imageSize} | |
2740 | Specifies the number of unsigned bytes of image data starting at the | |
2741 | address specified by @var{data}. | |
2742 | ||
2743 | @item @var{data} | |
2744 | Specifies a pointer to the compressed image data in memory. | |
2745 | ||
2746 | @end table | |
2747 | ||
8925f36f | 2748 | Texturing maps a portion of a specified texture image onto each |
c7b31271 | 2749 | graphical primitive for which texturing is enabled. To enable and |
8925f36f | 2750 | disable two-dimensional texturing, call @code{glEnable} and |
c7b31271 | 2751 | @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and |
8925f36f AW |
2752 | disable texturing using cube-mapped textures, call @code{glEnable} and |
2753 | @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}. | |
2754 | ||
2755 | @code{glCompressedTexImage2D} loads a previously defined, and retrieved, | |
2756 | compressed two-dimensional texture image if @var{target} is | |
2757 | @code{GL_TEXTURE_2D} (see @code{glTexImage2D}). | |
2758 | ||
2759 | If @var{target} is @code{GL_PROXY_TEXTURE_2D}, no data is read from | |
2760 | @var{data}, but all of the texture image state is recalculated, checked | |
2761 | for consistency, and checked against the implementation's capabilities. | |
2762 | If the implementation cannot handle a texture of the requested texture | |
2763 | size, it sets all of the image state to 0, but does not generate an | |
c7b31271 | 2764 | error (see @code{glGetError}). To query for an entire mipmap array, use |
8925f36f AW |
2765 | an image array level greater than or equal to 1. |
2766 | ||
2767 | @var{internalformat} must be an extension-specified compressed-texture | |
c7b31271 | 2768 | format. When a texture is loaded with @code{glTexImage2D} using a |
8925f36f | 2769 | generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}), the |
c7b31271 | 2770 | GL selects from one of its extensions supporting compressed textures. In |
8925f36f AW |
2771 | order to load the compressed texture image using |
2772 | @code{glCompressedTexImage2D}, query the compressed texture image's size | |
2773 | and format using @code{glGetTexLevelParameter}. | |
2774 | ||
2775 | If a non-zero named buffer object is bound to the | |
2776 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2777 | texture image is specified, @var{data} is treated as a byte offset into | |
2778 | the buffer object's data store. | |
2779 | ||
8925f36f AW |
2780 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of |
2781 | the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
2782 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
2783 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or | |
2784 | @code{GL_COMPRESSED_RGBA}. | |
2785 | ||
2786 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
2787 | consistent with the format, dimensions, and contents of the specified | |
2788 | compressed image data. | |
2789 | ||
2790 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
2791 | not supported by the specific compressed internal format as specified in | |
2792 | the specific texture compression extension. | |
2793 | ||
2794 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2795 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2796 | object's data store is currently mapped. | |
2797 | ||
2798 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2799 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2800 | would be unpacked from the buffer object such that the memory reads | |
2801 | required would exceed the data store size. | |
2802 | ||
2803 | @code{GL_INVALID_OPERATION} is generated if | |
2804 | @code{glCompressedTexImage2D} is executed between the execution of | |
2805 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
2806 | ||
2807 | Undefined results, including abnormal program termination, are generated | |
2808 | if @var{data} is not encoded in a manner consistent with the extension | |
2809 | specification defining the internal compression format. | |
2810 | ||
bb894c9d | 2811 | @end deftypefun |
8925f36f | 2812 | |
bb894c9d | 2813 | @deftypefun void glCompressedTexImage3D target level internalformat width height depth border imageSize data |
3c9b6116 AW |
2814 | Specify a three-dimensional texture image in a compressed format. |
2815 | ||
8925f36f AW |
2816 | @table @asis |
2817 | @item @var{target} | |
c7b31271 | 2818 | Specifies the target texture. Must be @code{GL_TEXTURE_3D} or |
8925f36f AW |
2819 | @code{GL_PROXY_TEXTURE_3D}. |
2820 | ||
2821 | @item @var{level} | |
c7b31271 | 2822 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
2823 | Level @var{n} is the @var{n}th mipmap reduction image. |
2824 | ||
2825 | @item @var{internalformat} | |
2826 | Specifies the format of the compressed image data stored at address | |
2827 | @var{data}. | |
2828 | ||
2829 | @item @var{width} | |
c7b31271 | 2830 | Specifies the width of the texture image including the border if any. If |
8925f36f | 2831 | the GL version does not support non-power-of-two sizes, this value must |
c7b31271 | 2832 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
3c9b6116 AW |
2833 | implementations support 3D texture images that are at least 16 texels |
2834 | wide. | |
8925f36f AW |
2835 | |
2836 | @item @var{height} | |
2837 | Specifies the height of the texture image including the border if any. | |
2838 | If the GL version does not support non-power-of-two sizes, this value | |
3c9b6116 AW |
2839 | must be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. |
2840 | All implementations support 3D texture images that are at least 16 | |
2841 | texels high. | |
8925f36f AW |
2842 | |
2843 | @item @var{depth} | |
c7b31271 | 2844 | Specifies the depth of the texture image including the border if any. If |
8925f36f | 2845 | the GL version does not support non-power-of-two sizes, this value must |
c7b31271 | 2846 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
3c9b6116 AW |
2847 | implementations support 3D texture images that are at least 16 texels |
2848 | deep. | |
8925f36f AW |
2849 | |
2850 | @item @var{border} | |
c7b31271 | 2851 | Specifies the width of the border. Must be either 0 or 1. |
8925f36f AW |
2852 | |
2853 | @item @var{imageSize} | |
2854 | Specifies the number of unsigned bytes of image data starting at the | |
2855 | address specified by @var{data}. | |
2856 | ||
2857 | @item @var{data} | |
2858 | Specifies a pointer to the compressed image data in memory. | |
2859 | ||
2860 | @end table | |
2861 | ||
8925f36f | 2862 | Texturing maps a portion of a specified texture image onto each |
c7b31271 | 2863 | graphical primitive for which texturing is enabled. To enable and |
8925f36f AW |
2864 | disable three-dimensional texturing, call @code{glEnable} and |
2865 | @code{glDisable} with argument @code{GL_TEXTURE_3D}. | |
2866 | ||
2867 | @code{glCompressedTexImage3D} loads a previously defined, and retrieved, | |
2868 | compressed three-dimensional texture image if @var{target} is | |
2869 | @code{GL_TEXTURE_3D} (see @code{glTexImage3D}). | |
2870 | ||
2871 | If @var{target} is @code{GL_PROXY_TEXTURE_3D}, no data is read from | |
2872 | @var{data}, but all of the texture image state is recalculated, checked | |
2873 | for consistency, and checked against the implementation's capabilities. | |
2874 | If the implementation cannot handle a texture of the requested texture | |
2875 | size, it sets all of the image state to 0, but does not generate an | |
c7b31271 | 2876 | error (see @code{glGetError}). To query for an entire mipmap array, use |
8925f36f AW |
2877 | an image array level greater than or equal to 1. |
2878 | ||
2879 | @var{internalformat} must be an extension-specified compressed-texture | |
c7b31271 | 2880 | format. When a texture is loaded with @code{glTexImage2D} using a |
8925f36f | 2881 | generic compressed texture format (e.g., @code{GL_COMPRESSED_RGB}), the |
c7b31271 | 2882 | GL selects from one of its extensions supporting compressed textures. In |
8925f36f AW |
2883 | order to load the compressed texture image using |
2884 | @code{glCompressedTexImage3D}, query the compressed texture image's size | |
2885 | and format using @code{glGetTexLevelParameter}. | |
2886 | ||
2887 | If a non-zero named buffer object is bound to the | |
2888 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2889 | texture image is specified, @var{data} is treated as a byte offset into | |
2890 | the buffer object's data store. | |
2891 | ||
8925f36f AW |
2892 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is one of |
2893 | the generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
2894 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
2895 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, or | |
2896 | @code{GL_COMPRESSED_RGBA}. | |
2897 | ||
2898 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
2899 | consistent with the format, dimensions, and contents of the specified | |
2900 | compressed image data. | |
2901 | ||
2902 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
2903 | not supported by the specific compressed internal format as specified in | |
2904 | the specific texture compression extension. | |
2905 | ||
2906 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2907 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2908 | object's data store is currently mapped. | |
2909 | ||
2910 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2911 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
2912 | would be unpacked from the buffer object such that the memory reads | |
2913 | required would exceed the data store size. | |
2914 | ||
2915 | @code{GL_INVALID_OPERATION} is generated if | |
2916 | @code{glCompressedTexImage3D} is executed between the execution of | |
2917 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
2918 | ||
2919 | Undefined results, including abnormal program termination, are generated | |
2920 | if @var{data} is not encoded in a manner consistent with the extension | |
2921 | specification defining the internal compression format. | |
2922 | ||
bb894c9d | 2923 | @end deftypefun |
8925f36f | 2924 | |
bb894c9d | 2925 | @deftypefun void glCompressedTexSubImage1D target level xoffset width format imageSize data |
3c9b6116 AW |
2926 | Specify a one-dimensional texture subimage in a compressed format. |
2927 | ||
8925f36f AW |
2928 | @table @asis |
2929 | @item @var{target} | |
c7b31271 | 2930 | Specifies the target texture. Must be @code{GL_TEXTURE_1D}. |
8925f36f AW |
2931 | |
2932 | @item @var{level} | |
c7b31271 | 2933 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
2934 | Level @var{n} is the @var{n}th mipmap reduction image. |
2935 | ||
2936 | @item @var{xoffset} | |
2937 | Specifies a texel offset in the x direction within the texture array. | |
2938 | ||
2939 | @item @var{width} | |
2940 | Specifies the width of the texture subimage. | |
2941 | ||
2942 | @item @var{format} | |
2943 | Specifies the format of the compressed image data stored at address | |
2944 | @var{data}. | |
2945 | ||
2946 | @item @var{imageSize} | |
2947 | Specifies the number of unsigned bytes of image data starting at the | |
2948 | address specified by @var{data}. | |
2949 | ||
2950 | @item @var{data} | |
2951 | Specifies a pointer to the compressed image data in memory. | |
2952 | ||
2953 | @end table | |
2954 | ||
8925f36f | 2955 | Texturing maps a portion of a specified texture image onto each |
c7b31271 | 2956 | graphical primitive for which texturing is enabled. To enable and |
8925f36f AW |
2957 | disable one-dimensional texturing, call @code{glEnable} and |
2958 | @code{glDisable} with argument @code{GL_TEXTURE_1D}. | |
2959 | ||
2960 | @code{glCompressedTexSubImage1D} redefines a contiguous subregion of an | |
c7b31271 | 2961 | existing one-dimensional texture image. The texels referenced by |
8925f36f | 2962 | @var{data} replace the portion of the existing texture array with x |
3c9b6116 | 2963 | indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive. |
8925f36f | 2964 | This region may not include any texels outside the range of the texture |
c7b31271 | 2965 | array as it was originally specified. It is not an error to specify a |
8925f36f AW |
2966 | subtexture with width of 0, but such a specification has no effect. |
2967 | ||
2968 | @var{format} must be an extension-specified compressed-texture format. | |
2969 | The @var{format} of the compressed texture image is selected by the GL | |
2970 | implementation that compressed it (see @code{glTexImage1D}), and should | |
2971 | be queried at the time the texture was compressed with | |
2972 | @code{glGetTexLevelParameter}. | |
2973 | ||
2974 | If a non-zero named buffer object is bound to the | |
2975 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
2976 | texture image is specified, @var{data} is treated as a byte offset into | |
2977 | the buffer object's data store. | |
2978 | ||
8925f36f AW |
2979 | @code{GL_INVALID_ENUM} is generated if @var{format} is one of these |
2980 | generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
2981 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
2982 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
2983 | @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE}, | |
2984 | @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB}, | |
2985 | @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}. | |
2986 | ||
2987 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
2988 | consistent with the format, dimensions, and contents of the specified | |
2989 | compressed image data. | |
2990 | ||
2991 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
2992 | not supported by the specific compressed internal format as specified in | |
2993 | the specific texture compression extension. | |
2994 | ||
2995 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
2996 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
2997 | object's data store is currently mapped. | |
2998 | ||
2999 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3000 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
3001 | would be unpacked from the buffer object such that the memory reads | |
3002 | required would exceed the data store size. | |
3003 | ||
3004 | @code{GL_INVALID_OPERATION} is generated if | |
3005 | @code{glCompressedTexSubImage1D} is executed between the execution of | |
3006 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
3007 | ||
3008 | Undefined results, including abnormal program termination, are generated | |
3009 | if @var{data} is not encoded in a manner consistent with the extension | |
3010 | specification defining the internal compression format. | |
3011 | ||
bb894c9d | 3012 | @end deftypefun |
8925f36f | 3013 | |
bb894c9d | 3014 | @deftypefun void glCompressedTexSubImage2D target level xoffset yoffset width height format imageSize data |
3c9b6116 AW |
3015 | Specify a two-dimensional texture subimage in a compressed format. |
3016 | ||
8925f36f AW |
3017 | @table @asis |
3018 | @item @var{target} | |
c7b31271 | 3019 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, |
8925f36f AW |
3020 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, |
3021 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
3022 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
3023 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
3024 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
3025 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
3026 | ||
3027 | @item @var{level} | |
c7b31271 | 3028 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
3029 | Level @var{n} is the @var{n}th mipmap reduction image. |
3030 | ||
3031 | @item @var{xoffset} | |
3032 | Specifies a texel offset in the x direction within the texture array. | |
3033 | ||
3034 | @item @var{yoffset} | |
3035 | Specifies a texel offset in the y direction within the texture array. | |
3036 | ||
3037 | @item @var{width} | |
3038 | Specifies the width of the texture subimage. | |
3039 | ||
3040 | @item @var{height} | |
3041 | Specifies the height of the texture subimage. | |
3042 | ||
3043 | @item @var{format} | |
3044 | Specifies the format of the compressed image data stored at address | |
3045 | @var{data}. | |
3046 | ||
3047 | @item @var{imageSize} | |
3048 | Specifies the number of unsigned bytes of image data starting at the | |
3049 | address specified by @var{data}. | |
3050 | ||
3051 | @item @var{data} | |
3052 | Specifies a pointer to the compressed image data in memory. | |
3053 | ||
3054 | @end table | |
3055 | ||
8925f36f | 3056 | Texturing maps a portion of a specified texture image onto each |
c7b31271 | 3057 | graphical primitive for which texturing is enabled. To enable and |
8925f36f | 3058 | disable two-dimensional texturing, call @code{glEnable} and |
c7b31271 | 3059 | @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and |
8925f36f AW |
3060 | disable texturing using cube-mapped texture, call @code{glEnable} and |
3061 | @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}. | |
3062 | ||
3063 | @code{glCompressedTexSubImage2D} redefines a contiguous subregion of an | |
c7b31271 | 3064 | existing two-dimensional texture image. The texels referenced by |
8925f36f | 3065 | @var{data} replace the portion of the existing texture array with x |
3c9b6116 AW |
3066 | indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, and the y |
3067 | indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive. | |
3068 | This region may not include any texels outside the range of the texture | |
c7b31271 | 3069 | array as it was originally specified. It is not an error to specify a |
3c9b6116 | 3070 | subtexture with width of 0, but such a specification has no effect. |
8925f36f AW |
3071 | |
3072 | @var{format} must be an extension-specified compressed-texture format. | |
3073 | The @var{format} of the compressed texture image is selected by the GL | |
3074 | implementation that compressed it (see @code{glTexImage2D}) and should | |
3075 | be queried at the time the texture was compressed with | |
3076 | @code{glGetTexLevelParameter}. | |
3077 | ||
3078 | If a non-zero named buffer object is bound to the | |
3079 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
3080 | texture image is specified, @var{data} is treated as a byte offset into | |
3081 | the buffer object's data store. | |
3082 | ||
8925f36f AW |
3083 | @code{GL_INVALID_ENUM} is generated if @var{format} is one of these |
3084 | generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
3085 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
3086 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
3087 | @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE}, | |
3088 | @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB}, | |
3089 | @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}. | |
3090 | ||
3091 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
3092 | consistent with the format, dimensions, and contents of the specified | |
3093 | compressed image data. | |
3094 | ||
3095 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
3096 | not supported by the specific compressed internal format as specified in | |
3097 | the specific texture compression extension. | |
3098 | ||
3099 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3100 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
3101 | object's data store is currently mapped. | |
3102 | ||
3103 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3104 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
3105 | would be unpacked from the buffer object such that the memory reads | |
3106 | required would exceed the data store size. | |
3107 | ||
3108 | @code{GL_INVALID_OPERATION} is generated if | |
3109 | @code{glCompressedTexSubImage2D} is executed between the execution of | |
3110 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
3111 | ||
3112 | Undefined results, including abnormal program termination, are generated | |
3113 | if @var{data} is not encoded in a manner consistent with the extension | |
3114 | specification defining the internal compression format. | |
3115 | ||
bb894c9d | 3116 | @end deftypefun |
8925f36f | 3117 | |
bb894c9d | 3118 | @deftypefun void glCompressedTexSubImage3D target level xoffset yoffset zoffset width height depth format imageSize data |
3c9b6116 AW |
3119 | Specify a three-dimensional texture subimage in a compressed format. |
3120 | ||
8925f36f AW |
3121 | @table @asis |
3122 | @item @var{target} | |
c7b31271 | 3123 | Specifies the target texture. Must be @code{GL_TEXTURE_3D}. |
8925f36f AW |
3124 | |
3125 | @item @var{level} | |
c7b31271 | 3126 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
3127 | Level @var{n} is the @var{n}th mipmap reduction image. |
3128 | ||
3129 | @item @var{xoffset} | |
3130 | Specifies a texel offset in the x direction within the texture array. | |
3131 | ||
3132 | @item @var{yoffset} | |
3133 | Specifies a texel offset in the y direction within the texture array. | |
3134 | ||
3135 | @item @var{width} | |
3136 | Specifies the width of the texture subimage. | |
3137 | ||
3138 | @item @var{height} | |
3139 | Specifies the height of the texture subimage. | |
3140 | ||
3141 | @item @var{depth} | |
3142 | Specifies the depth of the texture subimage. | |
3143 | ||
3144 | @item @var{format} | |
3145 | Specifies the format of the compressed image data stored at address | |
3146 | @var{data}. | |
3147 | ||
3148 | @item @var{imageSize} | |
3149 | Specifies the number of unsigned bytes of image data starting at the | |
3150 | address specified by @var{data}. | |
3151 | ||
3152 | @item @var{data} | |
3153 | Specifies a pointer to the compressed image data in memory. | |
3154 | ||
3155 | @end table | |
3156 | ||
8925f36f | 3157 | Texturing maps a portion of a specified texture image onto each |
c7b31271 | 3158 | graphical primitive for which texturing is enabled. To enable and |
8925f36f AW |
3159 | disable three-dimensional texturing, call @code{glEnable} and |
3160 | @code{glDisable} with argument @code{GL_TEXTURE_3D}. | |
3161 | ||
3162 | @code{glCompressedTexSubImage3D} redefines a contiguous subregion of an | |
c7b31271 | 3163 | existing three-dimensional texture image. The texels referenced by |
8925f36f | 3164 | @var{data} replace the portion of the existing texture array with x |
3c9b6116 AW |
3165 | indices @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, and the y |
3166 | indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, and the z | |
3167 | indices @var{zoffset} and @r{@var{zoffset}+@var{depth}-1}, inclusive. | |
8925f36f | 3168 | This region may not include any texels outside the range of the texture |
c7b31271 | 3169 | array as it was originally specified. It is not an error to specify a |
8925f36f AW |
3170 | subtexture with width of 0, but such a specification has no effect. |
3171 | ||
3172 | @var{format} must be an extension-specified compressed-texture format. | |
3173 | The @var{format} of the compressed texture image is selected by the GL | |
3174 | implementation that compressed it (see @code{glTexImage3D}) and should | |
3175 | be queried at the time the texture was compressed with | |
3176 | @code{glGetTexLevelParameter}. | |
3177 | ||
3178 | If a non-zero named buffer object is bound to the | |
3179 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
3180 | texture image is specified, @var{data} is treated as a byte offset into | |
3181 | the buffer object's data store. | |
3182 | ||
8925f36f AW |
3183 | @code{GL_INVALID_ENUM} is generated if @var{format} is one of these |
3184 | generic compressed internal formats: @code{GL_COMPRESSED_ALPHA}, | |
3185 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
3186 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
3187 | @code{GL_COMPRESSED_RGBA}, @code{GL_COMPRESSED_SLUMINANCE}, | |
3188 | @code{GL_COMPRESSED_SLUMINANCE_ALPHA}, @code{GL_COMPRESSED_SRGB}, | |
3189 | @code{GL_COMPRESSED_SRGBA}, or @code{GL_COMPRESSED_SRGB_ALPHA}. | |
3190 | ||
3191 | @code{GL_INVALID_VALUE} is generated if @var{imageSize} is not | |
3192 | consistent with the format, dimensions, and contents of the specified | |
3193 | compressed image data. | |
3194 | ||
3195 | @code{GL_INVALID_OPERATION} is generated if parameter combinations are | |
3196 | not supported by the specific compressed internal format as specified in | |
3197 | the specific texture compression extension. | |
3198 | ||
3199 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3200 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
3201 | object's data store is currently mapped. | |
3202 | ||
3203 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3204 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
3205 | would be unpacked from the buffer object such that the memory reads | |
3206 | required would exceed the data store size. | |
3207 | ||
3208 | @code{GL_INVALID_OPERATION} is generated if | |
3209 | @code{glCompressedTexSubImage3D} is executed between the execution of | |
3210 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
3211 | ||
3212 | Undefined results, including abnormal program termination, are generated | |
3213 | if @var{data} is not encoded in a manner consistent with the extension | |
3214 | specification defining the internal compression format. | |
3215 | ||
bb894c9d | 3216 | @end deftypefun |
8925f36f | 3217 | |
bb894c9d | 3218 | @deftypefun void glConvolutionFilter1D target internalformat width format type data |
3c9b6116 AW |
3219 | Define a one-dimensional convolution filter. |
3220 | ||
8925f36f AW |
3221 | @table @asis |
3222 | @item @var{target} | |
3223 | Must be @code{GL_CONVOLUTION_1D}. | |
3224 | ||
3225 | @item @var{internalformat} | |
c7b31271 | 3226 | The internal format of the convolution filter kernel. The allowable |
8925f36f AW |
3227 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, |
3228 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
3229 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
3230 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3231 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3232 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3233 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3234 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3235 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3236 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3237 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3238 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3239 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3240 | ||
3241 | @item @var{width} | |
3242 | The width of the pixel array referenced by @var{data}. | |
3243 | ||
3244 | @item @var{format} | |
c7b31271 | 3245 | The format of the pixel data in @var{data}. The allowable values are |
8925f36f AW |
3246 | @code{GL_ALPHA}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, |
3247 | @code{GL_INTENSITY}, @code{GL_RGB}, and @code{GL_RGBA}. | |
3248 | ||
3249 | @item @var{type} | |
c7b31271 | 3250 | The type of the pixel data in @var{data}. Symbolic constants |
8925f36f AW |
3251 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
3252 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
3253 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
3254 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
3255 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
3256 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
3257 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
3258 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
3259 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
3260 | ||
3261 | @item @var{data} | |
3262 | Pointer to a one-dimensional array of pixel data that is processed to | |
3263 | build the convolution filter kernel. | |
3264 | ||
3265 | @end table | |
3266 | ||
8925f36f AW |
3267 | @code{glConvolutionFilter1D} builds a one-dimensional convolution filter |
3268 | kernel from an array of pixels. | |
3269 | ||
3270 | The pixel array specified by @var{width}, @var{format}, @var{type}, and | |
3271 | @var{data} is extracted from memory and processed just as if | |
3272 | @code{glDrawPixels} were called, but processing stops after the final | |
3273 | expansion to RGBA is completed. | |
3274 | ||
3275 | If a non-zero named buffer object is bound to the | |
3276 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
3277 | convolution filter is specified, @var{data} is treated as a byte offset | |
3278 | into the buffer object's data store. | |
3279 | ||
3280 | The R, G, B, and A components of each pixel are next scaled by the four | |
3281 | 1D @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four | |
c7b31271 | 3282 | 1D @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias |
8925f36f AW |
3283 | parameters are set by @code{glConvolutionParameter} using the |
3284 | @code{GL_CONVOLUTION_1D} target and the names | |
3285 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
c7b31271 DH |
3286 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are |
3287 | vectors of four values that are applied to red, green, blue, and alpha, | |
3288 | in that order.) The R, G, B, and A values are not clamped to [0,1] at | |
3289 | any time during this process. | |
8925f36f AW |
3290 | |
3291 | Each pixel is then converted to the internal format specified by | |
c7b31271 | 3292 | @var{internalformat}. This conversion simply maps the component values |
8925f36f | 3293 | of the pixel (R, G, B, and A) to the values included in the internal |
c7b31271 | 3294 | format (red, green, blue, alpha, luminance, and intensity). The mapping |
8925f36f AW |
3295 | is as follows: |
3296 | ||
3297 | ||
3298 | ||
3299 | @table @asis | |
3300 | @item @strong{Internal Format} | |
3301 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
3302 | @strong{Luminance}, @strong{Intensity} | |
3303 | ||
3304 | @item @code{GL_ALPHA} | |
3305 | , , , A , , | |
3306 | ||
3307 | @item @code{GL_LUMINANCE} | |
3308 | , , , , R , | |
3309 | ||
3310 | @item @code{GL_LUMINANCE_ALPHA} | |
3311 | , , , A , R , | |
3312 | ||
3313 | @item @code{GL_INTENSITY} | |
3314 | , , , , , R | |
3315 | ||
3316 | @item @code{GL_RGB} | |
3317 | R , G , B , , , | |
3318 | ||
3319 | @item @code{GL_RGBA} | |
3320 | R , G , B , A , , | |
3321 | ||
3322 | @end table | |
3323 | ||
3324 | The red, green, blue, alpha, luminance, and/or intensity components of | |
3325 | the resulting pixels are stored in floating-point rather than integer | |
c7b31271 | 3326 | format. They form a one-dimensional filter kernel image indexed with |
8925f36f | 3327 | coordinate @var{i} such that @var{i} starts at 0 and increases from left |
c7b31271 | 3328 | to right. Kernel location @var{i} is derived from the @var{i}th pixel, |
8925f36f AW |
3329 | counting from 0. |
3330 | ||
3331 | Note that after a convolution is performed, the resulting color | |
3332 | components are also scaled by their corresponding | |
3333 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
3334 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
3335 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
c7b31271 DH |
3336 | and @strong{ALPHA}). These parameters are set by |
3337 | @code{glPixelTransfer}. | |
8925f36f | 3338 | |
8925f36f AW |
3339 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
3340 | @code{GL_CONVOLUTION_1D}. | |
3341 | ||
3342 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
3343 | of the allowable values. | |
3344 | ||
3345 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
3346 | allowable values. | |
3347 | ||
3348 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
3349 | allowable values. | |
3350 | ||
3351 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
c7b31271 DH |
3352 | greater than the maximum supported value. This value may be queried |
3353 | with @code{glGetConvolutionParameter} using target | |
3354 | @code{GL_CONVOLUTION_1D} and name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
8925f36f AW |
3355 | |
3356 | @code{GL_INVALID_OPERATION} is generated if @var{format} is one of | |
3357 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
3358 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
3359 | and @var{type} is not @code{GL_RGB}. | |
3360 | ||
3361 | @code{GL_INVALID_OPERATION} is generated if @var{format} is one of | |
3362 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
3363 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
3364 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
3365 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
3366 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{type} is neither | |
3367 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
3368 | ||
3369 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3370 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
3371 | object's data store is currently mapped. | |
3372 | ||
3373 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3374 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
3375 | would be unpacked from the buffer object such that the memory reads | |
3376 | required would exceed the data store size. | |
3377 | ||
3378 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3379 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
3380 | is not evenly divisible into the number of bytes needed to store in | |
3381 | memory a datum indicated by @var{type}. | |
3382 | ||
3383 | @code{GL_INVALID_OPERATION} is generated if @code{glConvolutionFilter1D} | |
3384 | is executed between the execution of @code{glBegin} and the | |
3385 | corresponding execution of @code{glEnd}. | |
3386 | ||
bb894c9d | 3387 | @end deftypefun |
8925f36f | 3388 | |
bb894c9d | 3389 | @deftypefun void glConvolutionFilter2D target internalformat width height format type data |
3c9b6116 AW |
3390 | Define a two-dimensional convolution filter. |
3391 | ||
8925f36f AW |
3392 | @table @asis |
3393 | @item @var{target} | |
3394 | Must be @code{GL_CONVOLUTION_2D}. | |
3395 | ||
3396 | @item @var{internalformat} | |
c7b31271 | 3397 | The internal format of the convolution filter kernel. The allowable |
8925f36f AW |
3398 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, |
3399 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
3400 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
3401 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3402 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3403 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3404 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3405 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3406 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3407 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3408 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3409 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3410 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3411 | ||
3412 | @item @var{width} | |
3413 | The width of the pixel array referenced by @var{data}. | |
3414 | ||
3415 | @item @var{height} | |
3416 | The height of the pixel array referenced by @var{data}. | |
3417 | ||
3418 | @item @var{format} | |
c7b31271 | 3419 | The format of the pixel data in @var{data}. The allowable values are |
8925f36f AW |
3420 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, |
3421 | @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, | |
3422 | @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA}. | |
3423 | ||
3424 | @item @var{type} | |
c7b31271 | 3425 | The type of the pixel data in @var{data}. Symbolic constants |
8925f36f AW |
3426 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
3427 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
3428 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
3429 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
3430 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
3431 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
3432 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
3433 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
3434 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
3435 | ||
3436 | @item @var{data} | |
3437 | Pointer to a two-dimensional array of pixel data that is processed to | |
3438 | build the convolution filter kernel. | |
3439 | ||
3440 | @end table | |
3441 | ||
8925f36f AW |
3442 | @code{glConvolutionFilter2D} builds a two-dimensional convolution filter |
3443 | kernel from an array of pixels. | |
3444 | ||
3445 | The pixel array specified by @var{width}, @var{height}, @var{format}, | |
3446 | @var{type}, and @var{data} is extracted from memory and processed just | |
3447 | as if @code{glDrawPixels} were called, but processing stops after the | |
3448 | final expansion to RGBA is completed. | |
3449 | ||
3450 | If a non-zero named buffer object is bound to the | |
3451 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
3452 | convolution filter is specified, @var{data} is treated as a byte offset | |
3453 | into the buffer object's data store. | |
3454 | ||
3455 | The R, G, B, and A components of each pixel are next scaled by the four | |
3456 | 2D @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four | |
c7b31271 | 3457 | 2D @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias |
8925f36f AW |
3458 | parameters are set by @code{glConvolutionParameter} using the |
3459 | @code{GL_CONVOLUTION_2D} target and the names | |
3460 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
c7b31271 DH |
3461 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are |
3462 | vectors of four values that are applied to red, green, blue, and alpha, | |
3463 | in that order.) The R, G, B, and A values are not clamped to [0,1] at | |
3464 | any time during this process. | |
8925f36f AW |
3465 | |
3466 | Each pixel is then converted to the internal format specified by | |
c7b31271 | 3467 | @var{internalformat}. This conversion simply maps the component values |
8925f36f | 3468 | of the pixel (R, G, B, and A) to the values included in the internal |
c7b31271 | 3469 | format (red, green, blue, alpha, luminance, and intensity). The mapping |
8925f36f AW |
3470 | is as follows: |
3471 | ||
3472 | ||
3473 | ||
3474 | @table @asis | |
3475 | @item @strong{Internal Format} | |
3476 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
3477 | @strong{Luminance}, @strong{Intensity} | |
3478 | ||
3479 | @item @code{GL_ALPHA} | |
3480 | , , , A , , | |
3481 | ||
3482 | @item @code{GL_LUMINANCE} | |
3483 | , , , , R , | |
3484 | ||
3485 | @item @code{GL_LUMINANCE_ALPHA} | |
3486 | , , , A , R , | |
3487 | ||
3488 | @item @code{GL_INTENSITY} | |
3489 | , , , , , R | |
3490 | ||
3491 | @item @code{GL_RGB} | |
3492 | R , G , B , , , | |
3493 | ||
3494 | @item @code{GL_RGBA} | |
3495 | R , G , B , A , , | |
3496 | ||
3497 | @end table | |
3498 | ||
3499 | The red, green, blue, alpha, luminance, and/or intensity components of | |
3500 | the resulting pixels are stored in floating-point rather than integer | |
c7b31271 | 3501 | format. They form a two-dimensional filter kernel image indexed with |
8925f36f AW |
3502 | coordinates @var{i} and @var{j} such that @var{i} starts at zero and |
3503 | increases from left to right, and @var{j} starts at zero and increases | |
c7b31271 | 3504 | from bottom to top. Kernel location @var{i,j} is derived from the |
8925f36f AW |
3505 | @var{N}th pixel, where @var{N} is @var{i}+@var{j}*@var{width}. |
3506 | ||
3507 | Note that after a convolution is performed, the resulting color | |
3508 | components are also scaled by their corresponding | |
3509 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
3510 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
3511 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
c7b31271 DH |
3512 | and @strong{ALPHA}). These parameters are set by |
3513 | @code{glPixelTransfer}. | |
8925f36f | 3514 | |
8925f36f AW |
3515 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
3516 | @code{GL_CONVOLUTION_2D}. | |
3517 | ||
3518 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
3519 | of the allowable values. | |
3520 | ||
3521 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
3522 | allowable values. | |
3523 | ||
3524 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
3525 | allowable values. | |
3526 | ||
3527 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
c7b31271 DH |
3528 | greater than the maximum supported value. This value may be queried |
3529 | with @code{glGetConvolutionParameter} using target | |
3530 | @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
8925f36f AW |
3531 | |
3532 | @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero | |
c7b31271 | 3533 | or greater than the maximum supported value. This value may be queried |
8925f36f AW |
3534 | with @code{glGetConvolutionParameter} using target |
3535 | @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}. | |
3536 | ||
3537 | @code{GL_INVALID_OPERATION} is generated if @var{height} is one of | |
3538 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
3539 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
3540 | and @var{format} is not @code{GL_RGB}. | |
3541 | ||
3542 | @code{GL_INVALID_OPERATION} is generated if @var{height} is one of | |
3543 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
3544 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
3545 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
3546 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
3547 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
3548 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
3549 | ||
3550 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3551 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
3552 | object's data store is currently mapped. | |
3553 | ||
3554 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3555 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
3556 | would be unpacked from the buffer object such that the memory reads | |
3557 | required would exceed the data store size. | |
3558 | ||
3559 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
3560 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
3561 | is not evenly divisible into the number of bytes needed to store in | |
3562 | memory a datum indicated by @var{type}. | |
3563 | ||
3564 | @code{GL_INVALID_OPERATION} is generated if @code{glConvolutionFilter2D} | |
3565 | is executed between the execution of @code{glBegin} and the | |
3566 | corresponding execution of @code{glEnd}. | |
3567 | ||
bb894c9d | 3568 | @end deftypefun |
8925f36f | 3569 | |
bb894c9d AW |
3570 | @deftypefun void glConvolutionParameterf target pname params |
3571 | @deftypefunx void glConvolutionParameteri target pname params | |
d172eed9 AW |
3572 | @deftypefunx void glConvolutionParameterfv target pname params |
3573 | @deftypefunx void glConvolutionParameteriv target pname params | |
3c9b6116 AW |
3574 | Set convolution parameters. |
3575 | ||
8925f36f AW |
3576 | @table @asis |
3577 | @item @var{target} | |
c7b31271 | 3578 | The target for the convolution parameter. Must be one of |
8925f36f AW |
3579 | @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or |
3580 | @code{GL_SEPARABLE_2D}. | |
3581 | ||
3582 | @item @var{pname} | |
c7b31271 | 3583 | The parameter to be set. Must be @code{GL_CONVOLUTION_BORDER_MODE}. |
8925f36f AW |
3584 | |
3585 | @item @var{params} | |
c7b31271 | 3586 | The parameter value. Must be one of @code{GL_REDUCE}, |
8925f36f AW |
3587 | @code{GL_CONSTANT_BORDER}, @code{GL_REPLICATE_BORDER}. |
3588 | ||
3589 | ||
3590 | ||
3591 | @end table | |
3592 | ||
8925f36f AW |
3593 | @code{glConvolutionParameter} sets the value of a convolution parameter. |
3594 | ||
3595 | @var{target} selects the convolution filter to be affected: | |
3596 | @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or | |
3597 | @code{GL_SEPARABLE_2D} for the 1D, 2D, or separable 2D filter, | |
3598 | respectively. | |
3599 | ||
3600 | @var{pname} selects the parameter to be changed. | |
3601 | @code{GL_CONVOLUTION_FILTER_SCALE} and @code{GL_CONVOLUTION_FILTER_BIAS} | |
3602 | affect the definition of the convolution filter kernel; see | |
3603 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and | |
c7b31271 DH |
3604 | @code{glSeparableFilter2D} for details. In these cases, @var{params}v |
3605 | is an array of four values to be applied to red, green, blue, and alpha | |
3606 | values, respectively. The initial value for | |
8925f36f AW |
3607 | @code{GL_CONVOLUTION_FILTER_SCALE} is (1, 1, 1, 1), and the initial |
3608 | value for @code{GL_CONVOLUTION_FILTER_BIAS} is (0, 0, 0, 0). | |
3609 | ||
3610 | A @var{pname} value of @code{GL_CONVOLUTION_BORDER_MODE} controls the | |
c7b31271 | 3611 | convolution border mode. The accepted modes are: |
8925f36f AW |
3612 | |
3613 | @table @asis | |
3614 | @item @code{GL_REDUCE} | |
3615 | The image resulting from convolution is smaller than the source image. | |
3c9b6116 AW |
3616 | If the filter width is @r{@var{Wf}} and height is @r{@var{Hf}}, and the |
3617 | source image width is @r{@var{Ws}} and height is @r{@var{Hs}}, then the | |
3618 | convolved image width will be @r{@var{Ws}-@var{Wf}+1} and height will be | |
c7b31271 DH |
3619 | @r{@var{Hs}-@var{Hf}+1}. (If this reduction would generate an image |
3620 | with zero or negative width and/or height, the output is simply null, | |
3621 | with no error generated.) The coordinates of the image resulting from | |
3c9b6116 AW |
3622 | convolution are zero through @r{@var{Ws}-@var{Wf}} in width and zero |
3623 | through @r{@var{Hs}-@var{Hf}} in height. | |
8925f36f AW |
3624 | |
3625 | @item @code{GL_CONSTANT_BORDER} | |
3626 | The image resulting from convolution is the same size as the source | |
3627 | image, and processed as if the source image were surrounded by pixels | |
3628 | with their color specified by the @code{GL_CONVOLUTION_BORDER_COLOR}. | |
3629 | ||
3630 | @item @code{GL_REPLICATE_BORDER} | |
3631 | The image resulting from convolution is the same size as the source | |
3632 | image, and processed as if the outermost pixel on the border of the | |
3633 | source image were replicated. | |
3634 | ||
3635 | @end table | |
3636 | ||
8925f36f AW |
3637 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
3638 | allowable values. | |
3639 | ||
3640 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the | |
3641 | allowable values. | |
3642 | ||
3643 | @code{GL_INVALID_ENUM} is generated if @var{pname} is | |
3644 | @code{GL_CONVOLUTION_BORDER_MODE} and @var{params} is not one of | |
3645 | @code{GL_REDUCE}, @code{GL_CONSTANT_BORDER}, or | |
3646 | @code{GL_REPLICATE_BORDER}. | |
3647 | ||
3648 | @code{GL_INVALID_OPERATION} is generated if | |
3649 | @code{glConvolutionParameter} is executed between the execution of | |
3650 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
3651 | ||
bb894c9d | 3652 | @end deftypefun |
8925f36f | 3653 | |
bb894c9d | 3654 | @deftypefun void glCopyColorSubTable target start x y width |
3c9b6116 AW |
3655 | Respecify a portion of a color table. |
3656 | ||
8925f36f AW |
3657 | @table @asis |
3658 | @item @var{target} | |
3659 | Must be one of @code{GL_COLOR_TABLE}, | |
3660 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or | |
3661 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
3662 | ||
3663 | @item @var{start} | |
3664 | The starting index of the portion of the color table to be replaced. | |
3665 | ||
3666 | @item @var{x} | |
3667 | @itemx @var{y} | |
3668 | The window coordinates of the left corner of the row of pixels to be | |
3669 | copied. | |
3670 | ||
3671 | @item @var{width} | |
3672 | The number of table entries to replace. | |
3673 | ||
3674 | @end table | |
3675 | ||
8925f36f | 3676 | @code{glCopyColorSubTable} is used to respecify a contiguous portion of |
c7b31271 | 3677 | a color table previously defined using @code{glColorTable}. The pixels |
8925f36f | 3678 | copied from the framebuffer replace the portion of the existing table |
c7b31271 | 3679 | from indices @var{start} to @r{@var{start}+@var{x}-1}, inclusive. This |
3c9b6116 | 3680 | region may not include any entries outside the range of the color table, |
c7b31271 | 3681 | as was originally specified. It is not an error to specify a subtexture |
3c9b6116 | 3682 | with width of 0, but such a specification has no effect. |
8925f36f | 3683 | |
8925f36f AW |
3684 | @code{GL_INVALID_VALUE} is generated if @var{target} is not a previously |
3685 | defined color table. | |
3686 | ||
3687 | @code{GL_INVALID_VALUE} is generated if @var{target} is not one of the | |
3688 | allowable values. | |
3689 | ||
3690 | @code{GL_INVALID_VALUE} is generated if | |
3c9b6116 | 3691 | @r{@var{start}+@var{x}>@var{width}}. |
8925f36f AW |
3692 | |
3693 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyColorSubTable} | |
3694 | is executed between the execution of @code{glBegin} and the | |
3695 | corresponding execution of @code{glEnd}. | |
3696 | ||
bb894c9d | 3697 | @end deftypefun |
8925f36f | 3698 | |
bb894c9d | 3699 | @deftypefun void glCopyColorTable target internalformat x y width |
3c9b6116 AW |
3700 | Copy pixels into a color table. |
3701 | ||
8925f36f AW |
3702 | @table @asis |
3703 | @item @var{target} | |
c7b31271 | 3704 | The color table target. Must be @code{GL_COLOR_TABLE}, |
8925f36f AW |
3705 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or |
3706 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
3707 | ||
3708 | @item @var{internalformat} | |
c7b31271 | 3709 | The internal storage format of the texture image. Must be one of the |
8925f36f AW |
3710 | following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4}, |
3711 | @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16}, | |
3712 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, | |
3713 | @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3714 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3715 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3716 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3717 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3718 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3719 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3720 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3721 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3722 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3723 | ||
3724 | @item @var{x} | |
3725 | The x coordinate of the lower-left corner of the pixel rectangle to be | |
3726 | transferred to the color table. | |
3727 | ||
3728 | @item @var{y} | |
3729 | The y coordinate of the lower-left corner of the pixel rectangle to be | |
3730 | transferred to the color table. | |
3731 | ||
3732 | @item @var{width} | |
3733 | The width of the pixel rectangle. | |
3734 | ||
3735 | @end table | |
3736 | ||
8925f36f AW |
3737 | @code{glCopyColorTable} loads a color table with pixels from the current |
3738 | @code{GL_READ_BUFFER} (rather than from main memory, as is the case for | |
3739 | @code{glColorTable}). | |
3740 | ||
3741 | The screen-aligned pixel rectangle with lower-left corner at (@var{x},\ | |
3742 | @var{y}) having width @var{width} and height 1 is loaded into the color | |
c7b31271 | 3743 | table. If any pixels within this region are outside the window that is |
8925f36f AW |
3744 | associated with the GL context, the values obtained for those pixels are |
3745 | undefined. | |
3746 | ||
3747 | The pixels in the rectangle are processed just as if @code{glReadPixels} | |
3748 | were called, with @var{internalformat} set to RGBA, but processing stops | |
3749 | after the final conversion to RGBA. | |
3750 | ||
3751 | The four scale parameters and the four bias parameters that are defined | |
3752 | for the table are then used to scale and bias the R, G, B, and A | |
c7b31271 | 3753 | components of each pixel. The scale and bias parameters are set by |
8925f36f AW |
3754 | calling @code{glColorTableParameter}. |
3755 | ||
c7b31271 | 3756 | Next, the R, G, B, and A values are clamped to the range @r{[0,1]}. Each |
3c9b6116 | 3757 | pixel is then converted to the internal format specified by |
c7b31271 | 3758 | @var{internalformat}. This conversion simply maps the component values |
8925f36f | 3759 | of the pixel (R, G, B, and A) to the values included in the internal |
c7b31271 | 3760 | format (red, green, blue, alpha, luminance, and intensity). The mapping |
8925f36f AW |
3761 | is as follows: |
3762 | ||
3763 | ||
3764 | ||
3765 | @table @asis | |
3766 | @item @strong{Internal Format} | |
3767 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
3768 | @strong{Luminance}, @strong{Intensity} | |
3769 | ||
3770 | @item @code{GL_ALPHA} | |
3771 | , , , A , , | |
3772 | ||
3773 | @item @code{GL_LUMINANCE} | |
3774 | , , , , R , | |
3775 | ||
3776 | @item @code{GL_LUMINANCE_ALPHA} | |
3777 | , , , A , R , | |
3778 | ||
3779 | @item @code{GL_INTENSITY} | |
3780 | , , , , , R | |
3781 | ||
3782 | @item @code{GL_RGB} | |
3783 | R , G , B , , , | |
3784 | ||
3785 | @item @code{GL_RGBA} | |
3786 | R , G , B , A , , | |
3787 | ||
3788 | @end table | |
3789 | ||
3790 | Finally, the red, green, blue, alpha, luminance, and/or intensity | |
c7b31271 | 3791 | components of the resulting pixels are stored in the color table. They |
8925f36f | 3792 | form a one-dimensional table with indices in the range |
3c9b6116 | 3793 | @r{[0,@var{width}-1]}. |
8925f36f AW |
3794 | |
3795 | ||
3796 | ||
8925f36f AW |
3797 | @code{GL_INVALID_ENUM} is generated when @var{target} is not one of the |
3798 | allowable values. | |
3799 | ||
3800 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero. | |
3801 | ||
3802 | @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not one | |
3803 | of the allowable values. | |
3804 | ||
3805 | @code{GL_TABLE_TOO_LARGE} is generated if the requested color table is | |
3806 | too large to be supported by the implementation. | |
3807 | ||
3808 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyColorTable} is | |
3809 | executed between the execution of @code{glBegin} and the corresponding | |
3810 | execution of @code{glEnd}. | |
3811 | ||
bb894c9d | 3812 | @end deftypefun |
8925f36f | 3813 | |
bb894c9d | 3814 | @deftypefun void glCopyConvolutionFilter1D target internalformat x y width |
3c9b6116 AW |
3815 | Copy pixels into a one-dimensional convolution filter. |
3816 | ||
8925f36f AW |
3817 | @table @asis |
3818 | @item @var{target} | |
3819 | Must be @code{GL_CONVOLUTION_1D}. | |
3820 | ||
3821 | @item @var{internalformat} | |
c7b31271 | 3822 | The internal format of the convolution filter kernel. The allowable |
8925f36f AW |
3823 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, |
3824 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
3825 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
3826 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3827 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3828 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3829 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3830 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3831 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3832 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3833 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3834 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3835 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3836 | ||
3837 | @item @var{x} | |
3838 | @itemx @var{y} | |
3839 | The window space coordinates of the lower-left coordinate of the pixel | |
3840 | array to copy. | |
3841 | ||
3842 | @item @var{width} | |
3843 | The width of the pixel array to copy. | |
3844 | ||
3845 | @end table | |
3846 | ||
8925f36f AW |
3847 | @code{glCopyConvolutionFilter1D} defines a one-dimensional convolution |
3848 | filter kernel with pixels from the current @code{GL_READ_BUFFER} (rather | |
3849 | than from main memory, as is the case for @code{glConvolutionFilter1D}). | |
3850 | ||
3851 | The screen-aligned pixel rectangle with lower-left corner at (@var{x},\ | |
3852 | @var{y}), width @var{width} and height 1 is used to define the | |
c7b31271 | 3853 | convolution filter. If any pixels within this region are outside the |
8925f36f AW |
3854 | window that is associated with the GL context, the values obtained for |
3855 | those pixels are undefined. | |
3856 | ||
3857 | The pixels in the rectangle are processed exactly as if | |
3858 | @code{glReadPixels} had been called with @var{format} set to RGBA, but | |
c7b31271 | 3859 | the process stops just before final conversion. The R, G, B, and A |
8925f36f AW |
3860 | components of each pixel are next scaled by the four 1D |
3861 | @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four 1D | |
c7b31271 | 3862 | @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias |
8925f36f AW |
3863 | parameters are set by @code{glConvolutionParameter} using the |
3864 | @code{GL_CONVOLUTION_1D} target and the names | |
3865 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
c7b31271 DH |
3866 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are |
3867 | vectors of four values that are applied to red, green, blue, and alpha, | |
3868 | in that order.) The R, G, B, and A values are not clamped to [0,1] at | |
3869 | any time during this process. | |
8925f36f AW |
3870 | |
3871 | Each pixel is then converted to the internal format specified by | |
c7b31271 | 3872 | @var{internalformat}. This conversion simply maps the component values |
8925f36f | 3873 | of the pixel (R, G, B, and A) to the values included in the internal |
c7b31271 | 3874 | format (red, green, blue, alpha, luminance, and intensity). The mapping |
8925f36f AW |
3875 | is as follows: |
3876 | ||
3877 | ||
3878 | ||
3879 | @table @asis | |
3880 | @item @strong{Internal Format} | |
3881 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
3882 | @strong{Luminance}, @strong{Intensity} | |
3883 | ||
3884 | @item @code{GL_ALPHA} | |
3885 | , , , A , , | |
3886 | ||
3887 | @item @code{GL_LUMINANCE} | |
3888 | , , , , R , | |
3889 | ||
3890 | @item @code{GL_LUMINANCE_ALPHA} | |
3891 | , , , A , R , | |
3892 | ||
3893 | @item @code{GL_INTENSITY} | |
3894 | , , , , , R | |
3895 | ||
3896 | @item @code{GL_RGB} | |
3897 | R , G , B , , , | |
3898 | ||
3899 | @item @code{GL_RGBA} | |
3900 | R , G , B , A , , | |
3901 | ||
3902 | @end table | |
3903 | ||
3904 | The red, green, blue, alpha, luminance, and/or intensity components of | |
3905 | the resulting pixels are stored in floating-point rather than integer | |
3906 | format. | |
3907 | ||
3908 | Pixel ordering is such that lower x screen coordinates correspond to | |
3909 | lower @var{i} filter image coordinates. | |
3910 | ||
3911 | Note that after a convolution is performed, the resulting color | |
3912 | components are also scaled by their corresponding | |
3913 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
3914 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
3915 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
c7b31271 DH |
3916 | and @strong{ALPHA}). These parameters are set by |
3917 | @code{glPixelTransfer}. | |
8925f36f | 3918 | |
8925f36f AW |
3919 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
3920 | @code{GL_CONVOLUTION_1D}. | |
3921 | ||
3922 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
3923 | of the allowable values. | |
3924 | ||
3925 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
c7b31271 DH |
3926 | greater than the maximum supported value. This value may be queried |
3927 | with @code{glGetConvolutionParameter} using target | |
3928 | @code{GL_CONVOLUTION_1D} and name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
8925f36f AW |
3929 | |
3930 | @code{GL_INVALID_OPERATION} is generated if | |
3931 | @code{glCopyConvolutionFilter1D} is executed between the execution of | |
3932 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
3933 | ||
bb894c9d | 3934 | @end deftypefun |
8925f36f | 3935 | |
bb894c9d | 3936 | @deftypefun void glCopyConvolutionFilter2D target internalformat x y width height |
3c9b6116 AW |
3937 | Copy pixels into a two-dimensional convolution filter. |
3938 | ||
8925f36f AW |
3939 | @table @asis |
3940 | @item @var{target} | |
3941 | Must be @code{GL_CONVOLUTION_2D}. | |
3942 | ||
3943 | @item @var{internalformat} | |
c7b31271 | 3944 | The internal format of the convolution filter kernel. The allowable |
8925f36f AW |
3945 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, |
3946 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
3947 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
3948 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
3949 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
3950 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
3951 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
3952 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
3953 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
3954 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
3955 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
3956 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
3957 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
3958 | ||
3959 | @item @var{x} | |
3960 | @itemx @var{y} | |
3961 | The window space coordinates of the lower-left coordinate of the pixel | |
3962 | array to copy. | |
3963 | ||
3964 | @item @var{width} | |
3965 | The width of the pixel array to copy. | |
3966 | ||
3967 | @item @var{height} | |
3968 | The height of the pixel array to copy. | |
3969 | ||
3970 | @end table | |
3971 | ||
8925f36f AW |
3972 | @code{glCopyConvolutionFilter2D} defines a two-dimensional convolution |
3973 | filter kernel with pixels from the current @code{GL_READ_BUFFER} (rather | |
3974 | than from main memory, as is the case for @code{glConvolutionFilter2D}). | |
3975 | ||
3976 | The screen-aligned pixel rectangle with lower-left corner at (@var{x},\ | |
3977 | @var{y}), width @var{width} and height @var{height} is used to define | |
c7b31271 DH |
3978 | the convolution filter. If any pixels within this region are outside |
3979 | the window that is associated with the GL context, the values obtained | |
3980 | for those pixels are undefined. | |
8925f36f AW |
3981 | |
3982 | The pixels in the rectangle are processed exactly as if | |
3983 | @code{glReadPixels} had been called with @var{format} set to RGBA, but | |
c7b31271 | 3984 | the process stops just before final conversion. The R, G, B, and A |
8925f36f AW |
3985 | components of each pixel are next scaled by the four 2D |
3986 | @code{GL_CONVOLUTION_FILTER_SCALE} parameters and biased by the four 2D | |
c7b31271 | 3987 | @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias |
8925f36f AW |
3988 | parameters are set by @code{glConvolutionParameter} using the |
3989 | @code{GL_CONVOLUTION_2D} target and the names | |
3990 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
c7b31271 DH |
3991 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are |
3992 | vectors of four values that are applied to red, green, blue, and alpha, | |
3993 | in that order.) The R, G, B, and A values are not clamped to [0,1] at | |
3994 | any time during this process. | |
8925f36f AW |
3995 | |
3996 | Each pixel is then converted to the internal format specified by | |
c7b31271 | 3997 | @var{internalformat}. This conversion simply maps the component values |
8925f36f | 3998 | of the pixel (R, G, B, and A) to the values included in the internal |
c7b31271 | 3999 | format (red, green, blue, alpha, luminance, and intensity). The mapping |
8925f36f AW |
4000 | is as follows: |
4001 | ||
4002 | ||
4003 | ||
4004 | @table @asis | |
4005 | @item @strong{Internal Format} | |
4006 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
4007 | @strong{Luminance}, @strong{Intensity} | |
4008 | ||
4009 | @item @code{GL_ALPHA} | |
4010 | , , , A , , | |
4011 | ||
4012 | @item @code{GL_LUMINANCE} | |
4013 | , , , , R , | |
4014 | ||
4015 | @item @code{GL_LUMINANCE_ALPHA} | |
4016 | , , , A , R , | |
4017 | ||
4018 | @item @code{GL_INTENSITY} | |
4019 | , , , , , R | |
4020 | ||
4021 | @item @code{GL_RGB} | |
4022 | R , G , B , , , | |
4023 | ||
4024 | @item @code{GL_RGBA} | |
4025 | R , G , B , A , , | |
4026 | ||
4027 | @end table | |
4028 | ||
4029 | The red, green, blue, alpha, luminance, and/or intensity components of | |
4030 | the resulting pixels are stored in floating-point rather than integer | |
4031 | format. | |
4032 | ||
4033 | Pixel ordering is such that lower x screen coordinates correspond to | |
4034 | lower @var{i} filter image coordinates, and lower y screen coordinates | |
4035 | correspond to lower @var{j} filter image coordinates. | |
4036 | ||
4037 | Note that after a convolution is performed, the resulting color | |
4038 | components are also scaled by their corresponding | |
4039 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
4040 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
4041 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
c7b31271 DH |
4042 | and @strong{ALPHA}). These parameters are set by |
4043 | @code{glPixelTransfer}. | |
8925f36f | 4044 | |
8925f36f AW |
4045 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
4046 | @code{GL_CONVOLUTION_2D}. | |
4047 | ||
4048 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
4049 | of the allowable values. | |
4050 | ||
4051 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
c7b31271 DH |
4052 | greater than the maximum supported value. This value may be queried |
4053 | with @code{glGetConvolutionParameter} using target | |
4054 | @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
8925f36f AW |
4055 | |
4056 | @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero | |
c7b31271 | 4057 | or greater than the maximum supported value. This value may be queried |
8925f36f AW |
4058 | with @code{glGetConvolutionParameter} using target |
4059 | @code{GL_CONVOLUTION_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}. | |
4060 | ||
4061 | @code{GL_INVALID_OPERATION} is generated if | |
4062 | @code{glCopyConvolutionFilter2D} is executed between the execution of | |
4063 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
4064 | ||
bb894c9d | 4065 | @end deftypefun |
8925f36f | 4066 | |
bb894c9d | 4067 | @deftypefun void glCopyPixels x y width height type |
3c9b6116 AW |
4068 | Copy pixels in the frame buffer. |
4069 | ||
8925f36f AW |
4070 | @table @asis |
4071 | @item @var{x} | |
4072 | @itemx @var{y} | |
4073 | Specify the window coordinates of the lower left corner of the | |
4074 | rectangular region of pixels to be copied. | |
4075 | ||
4076 | @item @var{width} | |
4077 | @itemx @var{height} | |
4078 | Specify the dimensions of the rectangular region of pixels to be copied. | |
4079 | Both must be nonnegative. | |
4080 | ||
4081 | @item @var{type} | |
4082 | Specifies whether color values, depth values, or stencil values are to | |
c7b31271 | 4083 | be copied. Symbolic constants @code{GL_COLOR}, @code{GL_DEPTH}, and |
8925f36f AW |
4084 | @code{GL_STENCIL} are accepted. |
4085 | ||
4086 | @end table | |
4087 | ||
8925f36f AW |
4088 | @code{glCopyPixels} copies a screen-aligned rectangle of pixels from the |
4089 | specified frame buffer location to a region relative to the current | |
c7b31271 DH |
4090 | raster position. Its operation is well defined only if the entire pixel |
4091 | source region is within the exposed portion of the window. Results of | |
8925f36f AW |
4092 | copies from outside the window, or from regions of the window that are |
4093 | not exposed, are hardware dependent and undefined. | |
4094 | ||
4095 | @var{x} and @var{y} specify the window coordinates of the lower left | |
c7b31271 | 4096 | corner of the rectangular region to be copied. @var{width} and |
8925f36f | 4097 | @var{height} specify the dimensions of the rectangular region to be |
c7b31271 | 4098 | copied. Both @var{width} and @var{height} must not be negative. |
8925f36f AW |
4099 | |
4100 | Several parameters control the processing of the pixel data while it is | |
c7b31271 DH |
4101 | being copied. These parameters are set with three commands: |
4102 | @code{glPixelTransfer}, @code{glPixelMap}, and @code{glPixelZoom}. This | |
8925f36f AW |
4103 | reference page describes the effects on @code{glCopyPixels} of most, but |
4104 | not all, of the parameters specified by these three commands. | |
4105 | ||
4106 | @code{glCopyPixels} copies values from each pixel with the lower | |
3c9b6116 | 4107 | left-hand corner at @r{(@var{x}+@var{i},@var{y}+@var{j})} for |
c7b31271 DH |
4108 | @r{0<=@var{i}<@var{width}} and @r{0<=@var{j}<@var{height}}. This pixel |
4109 | is said to be the @r{@var{i}}th pixel in the @r{@var{j}}th row. Pixels | |
3c9b6116 AW |
4110 | are copied in row order from the lowest to the highest row, left to |
4111 | right in each row. | |
8925f36f AW |
4112 | |
4113 | @var{type} specifies whether color, depth, or stencil data is to be | |
c7b31271 | 4114 | copied. The details of the transfer for each data type are as follows: |
8925f36f AW |
4115 | |
4116 | @table @asis | |
4117 | @item @code{GL_COLOR} | |
4118 | Indices or RGBA colors are read from the buffer currently specified as | |
c7b31271 | 4119 | the read source buffer (see @code{glReadBuffer}). If the GL is in color |
8925f36f AW |
4120 | index mode, each index that is read from this buffer is converted to a |
4121 | fixed-point format with an unspecified number of bits to the right of | |
c7b31271 DH |
4122 | the binary point. Each index is then shifted left by |
4123 | @code{GL_INDEX_SHIFT} bits, and added to @code{GL_INDEX_OFFSET}. If | |
4124 | @code{GL_INDEX_SHIFT} is negative, the shift is to the right. In either | |
8925f36f AW |
4125 | case, zero bits fill otherwise unspecified bit locations in the result. |
4126 | If @code{GL_MAP_COLOR} is true, the index is replaced with the value | |
c7b31271 | 4127 | that it references in lookup table @code{GL_PIXEL_MAP_I_TO_I}. Whether |
8925f36f | 4128 | the lookup replacement of the index is done or not, the integer part of |
3c9b6116 AW |
4129 | the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the |
4130 | number of bits in a color index buffer. | |
8925f36f AW |
4131 | |
4132 | If the GL is in RGBA mode, the red, green, blue, and alpha components of | |
4133 | each pixel that is read are converted to an internal floating-point | |
c7b31271 DH |
4134 | format with unspecified precision. The conversion maps the largest |
4135 | representable component value to 1.0, and component value 0 to 0.0. The | |
8925f36f AW |
4136 | resulting floating-point color values are then multiplied by |
4137 | @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is RED, | |
c7b31271 DH |
4138 | GREEN, BLUE, and ALPHA for the respective color components. The results |
4139 | are clamped to the range [0,1]. If @code{GL_MAP_COLOR} is true, each | |
8925f36f AW |
4140 | color component is scaled by the size of lookup table |
4141 | @code{GL_PIXEL_MAP_c_TO_c}, then replaced by the value that it | |
c7b31271 | 4142 | references in that table. @var{c} is R, G, B, or A. |
8925f36f AW |
4143 | |
4144 | If the @code{ARB_imaging} extension is supported, the color values may | |
4145 | be additionally processed by color-table lookups, color-matrix | |
4146 | transformations, and convolution filters. | |
4147 | ||
4148 | The GL then converts the resulting indices or RGBA colors to fragments | |
4149 | by attaching the current raster position @var{z} coordinate and texture | |
4150 | coordinates to each pixel, then assigning window coordinates | |
3c9b6116 AW |
4151 | @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where |
4152 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position, | |
4153 | and the pixel was the @r{@var{i}}th pixel in the @r{@var{j}}th row. | |
4154 | These pixel fragments are then treated just like the fragments generated | |
c7b31271 DH |
4155 | by rasterizing points, lines, or polygons. Texture mapping, fog, and |
4156 | all the fragment operations are applied before the fragments are written | |
4157 | to the frame buffer. | |
8925f36f AW |
4158 | |
4159 | @item @code{GL_DEPTH} | |
4160 | Depth values are read from the depth buffer and converted directly to an | |
c7b31271 DH |
4161 | internal floating-point format with unspecified precision. The |
4162 | resulting floating-point depth value is then multiplied by | |
4163 | @code{GL_DEPTH_SCALE} and added to @code{GL_DEPTH_BIAS}. The result is | |
4164 | clamped to the range [0,1]. | |
8925f36f AW |
4165 | |
4166 | The GL then converts the resulting depth components to fragments by | |
4167 | attaching the current raster position color or color index and texture | |
4168 | coordinates to each pixel, then assigning window coordinates | |
3c9b6116 AW |
4169 | @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where |
4170 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position, | |
4171 | and the pixel was the @r{@var{i}}th pixel in the @r{@var{j}}th row. | |
4172 | These pixel fragments are then treated just like the fragments generated | |
c7b31271 DH |
4173 | by rasterizing points, lines, or polygons. Texture mapping, fog, and |
4174 | all the fragment operations are applied before the fragments are written | |
4175 | to the frame buffer. | |
8925f36f AW |
4176 | |
4177 | @item @code{GL_STENCIL} | |
4178 | Stencil indices are read from the stencil buffer and converted to an | |
4179 | internal fixed-point format with an unspecified number of bits to the | |
c7b31271 DH |
4180 | right of the binary point. Each fixed-point index is then shifted left |
4181 | by @code{GL_INDEX_SHIFT} bits, and added to @code{GL_INDEX_OFFSET}. If | |
4182 | @code{GL_INDEX_SHIFT} is negative, the shift is to the right. In either | |
8925f36f AW |
4183 | case, zero bits fill otherwise unspecified bit locations in the result. |
4184 | If @code{GL_MAP_STENCIL} is true, the index is replaced with the value | |
c7b31271 | 4185 | that it references in lookup table @code{GL_PIXEL_MAP_S_TO_S}. Whether |
8925f36f | 4186 | the lookup replacement of the index is done or not, the integer part of |
3c9b6116 | 4187 | the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the |
c7b31271 | 4188 | number of bits in the stencil buffer. The resulting stencil indices are |
3c9b6116 AW |
4189 | then written to the stencil buffer such that the index read from the |
4190 | @r{@var{i}}th location of the @r{@var{j}}th row is written to location | |
4191 | @r{(@var{x}_@var{r}+@var{i},@var{y}_@var{r}+@var{j})}, where | |
4192 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position. | |
8925f36f AW |
4193 | Only the pixel ownership test, the scissor test, and the stencil |
4194 | writemask affect these write operations. | |
4195 | ||
4196 | @end table | |
4197 | ||
4198 | The rasterization described thus far assumes pixel zoom factors of 1.0. | |
3c9b6116 | 4199 | If @code{glPixelZoom} is used to change the @r{@var{x}} and @r{@var{y}} |
c7b31271 | 4200 | pixel zoom factors, pixels are converted to fragments as follows. If |
3c9b6116 AW |
4201 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position, |
4202 | and a given pixel is in the @r{@var{i}}th location in the @r{@var{j}}th | |
4203 | row of the source pixel rectangle, then fragments are generated for | |
4204 | pixels whose centers are in the rectangle with corners at | |
8925f36f | 4205 | |
3c9b6116 | 4206 | @r{(@var{x}_@var{r}+@var{zoom}_@var{x},@var{i},@var{y}_@var{r}+@var{zoom}_@var{y},@var{j})} |
8925f36f AW |
4207 | |
4208 | and | |
4209 | ||
3c9b6116 | 4210 | @r{(@var{x}_@var{r}+@var{zoom}_@var{x},(@var{i}+1,),@var{y}_@var{r}+@var{zoom}_@var{y},(@var{j}+1,))} |
8925f36f | 4211 | |
3c9b6116 AW |
4212 | where @r{@var{zoom}_@var{x}} is the value of @code{GL_ZOOM_X} and |
4213 | @r{@var{zoom}_@var{y}} is the value of @code{GL_ZOOM_Y}. | |
8925f36f | 4214 | |
8925f36f AW |
4215 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted |
4216 | value. | |
4217 | ||
4218 | @code{GL_INVALID_VALUE} is generated if either @var{width} or | |
4219 | @var{height} is negative. | |
4220 | ||
4221 | @code{GL_INVALID_OPERATION} is generated if @var{type} is | |
4222 | @code{GL_DEPTH} and there is no depth buffer. | |
4223 | ||
4224 | @code{GL_INVALID_OPERATION} is generated if @var{type} is | |
4225 | @code{GL_STENCIL} and there is no stencil buffer. | |
4226 | ||
4227 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyPixels} is | |
4228 | executed between the execution of @code{glBegin} and the corresponding | |
4229 | execution of @code{glEnd}. | |
4230 | ||
bb894c9d | 4231 | @end deftypefun |
8925f36f | 4232 | |
bb894c9d | 4233 | @deftypefun void glCopyTexImage1D target level internalformat x y width border |
3c9b6116 AW |
4234 | Copy pixels into a 1D texture image. |
4235 | ||
8925f36f AW |
4236 | @table @asis |
4237 | @item @var{target} | |
c7b31271 | 4238 | Specifies the target texture. Must be @code{GL_TEXTURE_1D}. |
8925f36f AW |
4239 | |
4240 | @item @var{level} | |
c7b31271 | 4241 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
4242 | Level @var{n} is the @var{n}th mipmap reduction image. |
4243 | ||
4244 | @item @var{internalformat} | |
c7b31271 | 4245 | Specifies the internal format of the texture. Must be one of the |
8925f36f AW |
4246 | following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4}, |
4247 | @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16}, | |
4248 | @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_LUMINANCE}, | |
4249 | @code{GL_COMPRESSED_LUMINANCE_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
4250 | @code{GL_COMPRESSED_RGB}, @code{GL_COMPRESSED_RGBA}, | |
4251 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
4252 | @code{GL_DEPTH_COMPONENT24}, @code{GL_DEPTH_COMPONENT32}, | |
4253 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, | |
4254 | @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
4255 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
4256 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
4257 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
4258 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
4259 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_RGB}, | |
4260 | @code{GL_R3_G3_B2}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
4261 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
4262 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
4263 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, @code{GL_RGBA16}, | |
4264 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
4265 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
4266 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
4267 | ||
4268 | @item @var{x} | |
4269 | @itemx @var{y} | |
4270 | Specify the window coordinates of the left corner of the row of pixels | |
4271 | to be copied. | |
4272 | ||
4273 | @item @var{width} | |
c7b31271 DH |
4274 | Specifies the width of the texture image. Must be 0 or |
4275 | @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. The | |
4276 | height of the texture image is 1. | |
8925f36f AW |
4277 | |
4278 | @item @var{border} | |
c7b31271 | 4279 | Specifies the width of the border. Must be either 0 or 1. |
8925f36f AW |
4280 | |
4281 | @end table | |
4282 | ||
8925f36f AW |
4283 | @code{glCopyTexImage1D} defines a one-dimensional texture image with |
4284 | pixels from the current @code{GL_READ_BUFFER}. | |
4285 | ||
3c9b6116 AW |
4286 | The screen-aligned pixel row with left corner at @r{(@var{x},@var{y})} |
4287 | and with a length of @r{@var{width}+2(@var{border},)} defines the | |
4288 | texture array at the mipmap level specified by @var{level}. | |
4289 | @var{internalformat} specifies the internal format of the texture array. | |
8925f36f AW |
4290 | |
4291 | The pixels in the row are processed exactly as if @code{glCopyPixels} | |
c7b31271 | 4292 | had been called, but the process stops just before final conversion. At |
3c9b6116 AW |
4293 | this point all pixel component values are clamped to the range @r{[0,1]} |
4294 | and then converted to the texture's internal format for storage in the | |
4295 | texel array. | |
8925f36f | 4296 | |
3c9b6116 | 4297 | Pixel ordering is such that lower @r{@var{x}} screen coordinates |
8925f36f AW |
4298 | correspond to lower texture coordinates. |
4299 | ||
4300 | If any of the pixels within the specified row of the current | |
4301 | @code{GL_READ_BUFFER} are outside the window associated with the current | |
4302 | rendering context, then the values obtained for those pixels are | |
4303 | undefined. | |
4304 | ||
4305 | @code{glCopyTexImage1D} defines a one-dimensional texture image with | |
4306 | pixels from the current @code{GL_READ_BUFFER}. | |
4307 | ||
4308 | When @var{internalformat} is one of the sRGB types, the GL does not | |
c7b31271 DH |
4309 | automatically convert the source pixels to the sRGB color space. In |
4310 | this case, the @code{glPixelMap} function can be used to accomplish the | |
8925f36f AW |
4311 | conversion. |
4312 | ||
8925f36f AW |
4313 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
4314 | allowable values. | |
4315 | ||
4316 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4317 | ||
4318 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
4319 | @r{@var{log}_2@var{max}}, where @r{@var{max}} is the returned value of |
4320 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
4321 | |
4322 | @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not an | |
4323 | allowable value. | |
4324 | ||
4325 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or | |
4326 | greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
4327 | ||
4328 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
4329 | not supported and the @var{width} cannot be represented as | |
3c9b6116 | 4330 | @r{2^@var{n}+2(@var{border},)} for some integer value of @var{n}. |
8925f36f AW |
4331 | |
4332 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
4333 | ||
4334 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexImage1D} is | |
4335 | executed between the execution of @code{glBegin} and the corresponding | |
4336 | execution of @code{glEnd}. | |
4337 | ||
4338 | @code{GL_INVALID_OPERATION} is generated if @var{internalformat} is | |
4339 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
4340 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32} and there is | |
4341 | no depth buffer. | |
4342 | ||
bb894c9d | 4343 | @end deftypefun |
8925f36f | 4344 | |
bb894c9d | 4345 | @deftypefun void glCopyTexImage2D target level internalformat x y width height border |
3c9b6116 AW |
4346 | Copy pixels into a 2D texture image. |
4347 | ||
8925f36f AW |
4348 | @table @asis |
4349 | @item @var{target} | |
c7b31271 | 4350 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, |
8925f36f AW |
4351 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, |
4352 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
4353 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
4354 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
4355 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
4356 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
4357 | ||
4358 | @item @var{level} | |
c7b31271 | 4359 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
4360 | Level @var{n} is the @var{n}th mipmap reduction image. |
4361 | ||
4362 | @item @var{internalformat} | |
c7b31271 | 4363 | Specifies the internal format of the texture. Must be one of the |
8925f36f AW |
4364 | following symbolic constants: @code{GL_ALPHA}, @code{GL_ALPHA4}, |
4365 | @code{GL_ALPHA8}, @code{GL_ALPHA12}, @code{GL_ALPHA16}, | |
4366 | @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_LUMINANCE}, | |
4367 | @code{GL_COMPRESSED_LUMINANCE_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
4368 | @code{GL_COMPRESSED_RGB}, @code{GL_COMPRESSED_RGBA}, | |
4369 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
4370 | @code{GL_DEPTH_COMPONENT24}, @code{GL_DEPTH_COMPONENT32}, | |
4371 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, | |
4372 | @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
4373 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
4374 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
4375 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
4376 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
4377 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_RGB}, | |
4378 | @code{GL_R3_G3_B2}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
4379 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
4380 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
4381 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, @code{GL_RGBA16}, | |
4382 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
4383 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
4384 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
4385 | ||
4386 | @item @var{x} | |
4387 | @itemx @var{y} | |
4388 | Specify the window coordinates of the lower left corner of the | |
4389 | rectangular region of pixels to be copied. | |
4390 | ||
4391 | @item @var{width} | |
c7b31271 | 4392 | Specifies the width of the texture image. Must be 0 or |
3c9b6116 | 4393 | @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. |
8925f36f AW |
4394 | |
4395 | @item @var{height} | |
c7b31271 | 4396 | Specifies the height of the texture image. Must be 0 or |
3c9b6116 | 4397 | @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}. |
8925f36f AW |
4398 | |
4399 | @item @var{border} | |
c7b31271 | 4400 | Specifies the width of the border. Must be either 0 or 1. |
8925f36f AW |
4401 | |
4402 | @end table | |
4403 | ||
8925f36f AW |
4404 | @code{glCopyTexImage2D} defines a two-dimensional texture image, or |
4405 | cube-map texture image with pixels from the current | |
4406 | @code{GL_READ_BUFFER}. | |
4407 | ||
4408 | The screen-aligned pixel rectangle with lower left corner at (@var{x}, | |
3c9b6116 AW |
4409 | @var{y}) and with a width of @r{@var{width}+2(@var{border},)} and a |
4410 | height of @r{@var{height}+2(@var{border},)} defines the texture array | |
c7b31271 | 4411 | at the mipmap level specified by @var{level}. @var{internalformat} |
8925f36f AW |
4412 | specifies the internal format of the texture array. |
4413 | ||
4414 | The pixels in the rectangle are processed exactly as if | |
4415 | @code{glCopyPixels} had been called, but the process stops just before | |
c7b31271 | 4416 | final conversion. At this point all pixel component values are clamped |
3c9b6116 | 4417 | to the range @r{[0,1]} and then converted to the texture's internal |
8925f36f AW |
4418 | format for storage in the texel array. |
4419 | ||
3c9b6116 AW |
4420 | Pixel ordering is such that lower @r{@var{x}} and @r{@var{y}} screen |
4421 | coordinates correspond to lower @r{@var{s}} and @r{@var{t}} texture | |
4422 | coordinates. | |
8925f36f AW |
4423 | |
4424 | If any of the pixels within the specified rectangle of the current | |
4425 | @code{GL_READ_BUFFER} are outside the window associated with the current | |
4426 | rendering context, then the values obtained for those pixels are | |
4427 | undefined. | |
4428 | ||
4429 | When @var{internalformat} is one of the sRGB types, the GL does not | |
c7b31271 DH |
4430 | automatically convert the source pixels to the sRGB color space. In |
4431 | this case, the @code{glPixelMap} function can be used to accomplish the | |
8925f36f AW |
4432 | conversion. |
4433 | ||
8925f36f AW |
4434 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
4435 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
4436 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
4437 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
4438 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
4439 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
4440 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
4441 | ||
4442 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4443 | ||
4444 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
4445 | @r{@var{log}_2@var{max}}, where @r{@var{max}} is the returned value of |
4446 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
4447 | |
4448 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or | |
4449 | greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
4450 | ||
4451 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
4452 | not supported and the @var{width} or @var{depth} cannot be represented | |
3c9b6116 | 4453 | as @r{2^@var{k}+2(@var{border},)} for some integer @r{@var{k}}. |
8925f36f AW |
4454 | |
4455 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
4456 | ||
4457 | @code{GL_INVALID_VALUE} is generated if @var{internalformat} is not an | |
4458 | accepted format. | |
4459 | ||
4460 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexImage2D} is | |
4461 | executed between the execution of @code{glBegin} and the corresponding | |
4462 | execution of @code{glEnd}. | |
4463 | ||
4464 | @code{GL_INVALID_OPERATION} is generated if @var{internalformat} is | |
4465 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
4466 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32} and there is | |
4467 | no depth buffer. | |
4468 | ||
bb894c9d | 4469 | @end deftypefun |
8925f36f | 4470 | |
bb894c9d | 4471 | @deftypefun void glCopyTexSubImage1D target level xoffset x y width |
3c9b6116 AW |
4472 | Copy a one-dimensional texture subimage. |
4473 | ||
8925f36f AW |
4474 | @table @asis |
4475 | @item @var{target} | |
c7b31271 | 4476 | Specifies the target texture. Must be @code{GL_TEXTURE_1D}. |
8925f36f AW |
4477 | |
4478 | @item @var{level} | |
c7b31271 | 4479 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
4480 | Level @var{n} is the @var{n}th mipmap reduction image. |
4481 | ||
4482 | @item @var{xoffset} | |
4483 | Specifies the texel offset within the texture array. | |
4484 | ||
4485 | @item @var{x} | |
4486 | @itemx @var{y} | |
4487 | Specify the window coordinates of the left corner of the row of pixels | |
4488 | to be copied. | |
4489 | ||
4490 | @item @var{width} | |
4491 | Specifies the width of the texture subimage. | |
4492 | ||
4493 | @end table | |
4494 | ||
8925f36f AW |
4495 | @code{glCopyTexSubImage1D} replaces a portion of a one-dimensional |
4496 | texture image with pixels from the current @code{GL_READ_BUFFER} (rather | |
4497 | than from main memory, as is the case for @code{glTexSubImage1D}). | |
4498 | ||
4499 | The screen-aligned pixel row with left corner at (@var{x},\ @var{y}), | |
4500 | and with length @var{width} replaces the portion of the texture array | |
3c9b6116 | 4501 | with x indices @var{xoffset} through @r{@var{xoffset}+@var{width}-1}, |
c7b31271 | 4502 | inclusive. The destination in the texture array may not include any |
8925f36f AW |
4503 | texels outside the texture array as it was originally specified. |
4504 | ||
4505 | The pixels in the row are processed exactly as if @code{glCopyPixels} | |
c7b31271 | 4506 | had been called, but the process stops just before final conversion. At |
8925f36f | 4507 | this point, all pixel component values are clamped to the range |
3c9b6116 | 4508 | @r{[0,1]} and then converted to the texture's internal format for |
8925f36f AW |
4509 | storage in the texel array. |
4510 | ||
4511 | It is not an error to specify a subtexture with zero width, but such a | |
c7b31271 | 4512 | specification has no effect. If any of the pixels within the specified |
8925f36f AW |
4513 | row of the current @code{GL_READ_BUFFER} are outside the read window |
4514 | associated with the current rendering context, then the values obtained | |
4515 | for those pixels are undefined. | |
4516 | ||
4517 | No change is made to the @var{internalformat}, @var{width}, or | |
4518 | @var{border} parameters of the specified texture array or to texel | |
4519 | values outside the specified subregion. | |
4520 | ||
8925f36f AW |
4521 | @code{GL_INVALID_ENUM} is generated if /@var{target} is not |
4522 | @code{GL_TEXTURE_1D}. | |
4523 | ||
4524 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
4525 | been defined by a previous @code{glTexImage1D} or | |
4526 | @code{glCopyTexImage1D} operation. | |
4527 | ||
4528 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4529 | ||
4530 | @code{GL_INVALID_VALUE} may be generated if | |
3c9b6116 | 4531 | @r{@var{level}>@var{log}_2(@var{max},)}, where @var{max} is the |
8925f36f AW |
4532 | returned value of @code{GL_MAX_TEXTURE_SIZE}. |
4533 | ||
3c9b6116 AW |
4534 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, or |
4535 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, where @r{@var{w}} | |
4536 | is the @code{GL_TEXTURE_WIDTH} and @r{@var{b}} is the | |
c7b31271 | 4537 | @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that |
3c9b6116 | 4538 | @r{@var{w}} includes twice the border width. |
8925f36f AW |
4539 | |
4540 | ||
4541 | ||
bb894c9d | 4542 | @end deftypefun |
8925f36f | 4543 | |
bb894c9d | 4544 | @deftypefun void glCopyTexSubImage2D target level xoffset yoffset x y width height |
3c9b6116 AW |
4545 | Copy a two-dimensional texture subimage. |
4546 | ||
8925f36f AW |
4547 | @table @asis |
4548 | @item @var{target} | |
c7b31271 | 4549 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, |
8925f36f AW |
4550 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, |
4551 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
4552 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
4553 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
4554 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
4555 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
4556 | ||
4557 | @item @var{level} | |
c7b31271 | 4558 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
4559 | Level @var{n} is the @var{n}th mipmap reduction image. |
4560 | ||
4561 | @item @var{xoffset} | |
4562 | Specifies a texel offset in the x direction within the texture array. | |
4563 | ||
4564 | @item @var{yoffset} | |
4565 | Specifies a texel offset in the y direction within the texture array. | |
4566 | ||
4567 | @item @var{x} | |
4568 | @itemx @var{y} | |
4569 | Specify the window coordinates of the lower left corner of the | |
4570 | rectangular region of pixels to be copied. | |
4571 | ||
4572 | @item @var{width} | |
4573 | Specifies the width of the texture subimage. | |
4574 | ||
4575 | @item @var{height} | |
4576 | Specifies the height of the texture subimage. | |
4577 | ||
4578 | @end table | |
4579 | ||
8925f36f AW |
4580 | @code{glCopyTexSubImage2D} replaces a rectangular portion of a |
4581 | two-dimensional texture image or cube-map texture image with pixels from | |
4582 | the current @code{GL_READ_BUFFER} (rather than from main memory, as is | |
4583 | the case for @code{glTexSubImage2D}). | |
4584 | ||
4585 | The screen-aligned pixel rectangle with lower left corner at | |
3c9b6116 AW |
4586 | @r{(@var{x},@var{y})} and with width @var{width} and height @var{height} |
4587 | replaces the portion of the texture array with x indices @var{xoffset} | |
4588 | through @r{@var{xoffset}+@var{width}-1}, inclusive, and y indices | |
4589 | @var{yoffset} through @r{@var{yoffset}+@var{height}-1}, inclusive, at | |
4590 | the mipmap level specified by @var{level}. | |
8925f36f AW |
4591 | |
4592 | The pixels in the rectangle are processed exactly as if | |
4593 | @code{glCopyPixels} had been called, but the process stops just before | |
c7b31271 | 4594 | final conversion. At this point, all pixel component values are clamped |
3c9b6116 | 4595 | to the range @r{[0,1]} and then converted to the texture's internal |
8925f36f AW |
4596 | format for storage in the texel array. |
4597 | ||
4598 | The destination rectangle in the texture array may not include any | |
c7b31271 | 4599 | texels outside the texture array as it was originally specified. It is |
8925f36f AW |
4600 | not an error to specify a subtexture with zero width or height, but such |
4601 | a specification has no effect. | |
4602 | ||
4603 | If any of the pixels within the specified rectangle of the current | |
4604 | @code{GL_READ_BUFFER} are outside the read window associated with the | |
4605 | current rendering context, then the values obtained for those pixels are | |
4606 | undefined. | |
4607 | ||
4608 | No change is made to the @var{internalformat}, @var{width}, | |
4609 | @var{height}, or @var{border} parameters of the specified texture array | |
4610 | or to texel values outside the specified subregion. | |
4611 | ||
8925f36f AW |
4612 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
4613 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
4614 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
4615 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
4616 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
4617 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
4618 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
4619 | ||
4620 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
4621 | been defined by a previous @code{glTexImage2D} or | |
4622 | @code{glCopyTexImage2D} operation. | |
4623 | ||
4624 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4625 | ||
4626 | @code{GL_INVALID_VALUE} may be generated if | |
3c9b6116 AW |
4627 | @r{@var{level}>@var{log}_2(@var{max},)}, where @r{@var{max}} is the |
4628 | returned value of @code{GL_MAX_TEXTURE_SIZE}. | |
4629 | ||
4630 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, | |
4631 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, | |
4632 | @r{@var{yoffset}<-@var{b}}, or | |
4633 | @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, where @r{@var{w}} | |
4634 | is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the | |
4635 | @code{GL_TEXTURE_HEIGHT}, and @r{@var{b}} is the | |
c7b31271 | 4636 | @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that |
3c9b6116 | 4637 | @r{@var{w}} and @r{@var{h}} include twice the border width. |
8925f36f AW |
4638 | |
4639 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexSubImage2D} | |
4640 | is executed between the execution of @code{glBegin} and the | |
4641 | corresponding execution of @code{glEnd}. | |
4642 | ||
bb894c9d | 4643 | @end deftypefun |
8925f36f | 4644 | |
bb894c9d | 4645 | @deftypefun void glCopyTexSubImage3D target level xoffset yoffset zoffset x y width height |
3c9b6116 AW |
4646 | Copy a three-dimensional texture subimage. |
4647 | ||
8925f36f AW |
4648 | @table @asis |
4649 | @item @var{target} | |
c7b31271 | 4650 | Specifies the target texture. Must be @code{GL_TEXTURE_3D} |
8925f36f AW |
4651 | |
4652 | @item @var{level} | |
c7b31271 | 4653 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
4654 | Level @var{n} is the @var{n}th mipmap reduction image. |
4655 | ||
4656 | @item @var{xoffset} | |
4657 | Specifies a texel offset in the x direction within the texture array. | |
4658 | ||
4659 | @item @var{yoffset} | |
4660 | Specifies a texel offset in the y direction within the texture array. | |
4661 | ||
4662 | @item @var{zoffset} | |
4663 | Specifies a texel offset in the z direction within the texture array. | |
4664 | ||
4665 | @item @var{x} | |
4666 | @itemx @var{y} | |
4667 | Specify the window coordinates of the lower left corner of the | |
4668 | rectangular region of pixels to be copied. | |
4669 | ||
4670 | @item @var{width} | |
4671 | Specifies the width of the texture subimage. | |
4672 | ||
4673 | @item @var{height} | |
4674 | Specifies the height of the texture subimage. | |
4675 | ||
4676 | @end table | |
4677 | ||
8925f36f AW |
4678 | @code{glCopyTexSubImage3D} replaces a rectangular portion of a |
4679 | three-dimensional texture image with pixels from the current | |
4680 | @code{GL_READ_BUFFER} (rather than from main memory, as is the case for | |
4681 | @code{glTexSubImage3D}). | |
4682 | ||
4683 | The screen-aligned pixel rectangle with lower left corner at (@var{x},\ | |
4684 | @var{y}) and with width @var{width} and height @var{height} replaces the | |
4685 | portion of the texture array with x indices @var{xoffset} through | |
3c9b6116 AW |
4686 | @r{@var{xoffset}+@var{width}-1}, inclusive, and y indices @var{yoffset} |
4687 | through @r{@var{yoffset}+@var{height}-1}, inclusive, at z index | |
4688 | @var{zoffset} and at the mipmap level specified by @var{level}. | |
8925f36f AW |
4689 | |
4690 | The pixels in the rectangle are processed exactly as if | |
4691 | @code{glCopyPixels} had been called, but the process stops just before | |
c7b31271 | 4692 | final conversion. At this point, all pixel component values are clamped |
3c9b6116 | 4693 | to the range @r{[0,1]} and then converted to the texture's internal |
8925f36f AW |
4694 | format for storage in the texel array. |
4695 | ||
4696 | The destination rectangle in the texture array may not include any | |
c7b31271 | 4697 | texels outside the texture array as it was originally specified. It is |
8925f36f AW |
4698 | not an error to specify a subtexture with zero width or height, but such |
4699 | a specification has no effect. | |
4700 | ||
4701 | If any of the pixels within the specified rectangle of the current | |
4702 | @code{GL_READ_BUFFER} are outside the read window associated with the | |
4703 | current rendering context, then the values obtained for those pixels are | |
4704 | undefined. | |
4705 | ||
4706 | No change is made to the @var{internalformat}, @var{width}, | |
4707 | @var{height}, @var{depth}, or @var{border} parameters of the specified | |
4708 | texture array or to texel values outside the specified subregion. | |
4709 | ||
8925f36f AW |
4710 | @code{GL_INVALID_ENUM} is generated if /@var{target} is not |
4711 | @code{GL_TEXTURE_3D}. | |
4712 | ||
4713 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
4714 | been defined by a previous @code{glTexImage3D} operation. | |
4715 | ||
4716 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
4717 | ||
4718 | @code{GL_INVALID_VALUE} may be generated if | |
3c9b6116 AW |
4719 | @r{@var{level}>@var{log}_2(@var{max},)}, where @r{@var{max}} is the |
4720 | returned value of @code{GL_MAX_3D_TEXTURE_SIZE}. | |
4721 | ||
4722 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, | |
4723 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, | |
4724 | @r{@var{yoffset}<-@var{b}}, | |
4725 | @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, | |
4726 | @r{@var{zoffset}<-@var{b}}, or | |
4727 | @r{(@var{zoffset}+1,)>(@var{d}-@var{b},)}, where @r{@var{w}} is the | |
4728 | @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the @code{GL_TEXTURE_HEIGHT}, | |
4729 | @r{@var{d}} is the @code{GL_TEXTURE_DEPTH}, and @r{@var{b}} is the | |
c7b31271 | 4730 | @code{GL_TEXTURE_BORDER} of the texture image being modified. Note that |
3c9b6116 AW |
4731 | @r{@var{w}}, @r{@var{h}}, and @r{@var{d}} include twice the border |
4732 | width. | |
8925f36f AW |
4733 | |
4734 | @code{GL_INVALID_OPERATION} is generated if @code{glCopyTexSubImage3D} | |
4735 | is executed between the execution of @code{glBegin} and the | |
4736 | corresponding execution of @code{glEnd}. | |
4737 | ||
bb894c9d | 4738 | @end deftypefun |
8925f36f | 4739 | |
bb894c9d | 4740 | @deftypefun GLuint glCreateProgram |
3c9b6116 AW |
4741 | Creates a program object. |
4742 | ||
8925f36f | 4743 | @code{glCreateProgram} creates an empty program object and returns a |
c7b31271 DH |
4744 | non-zero value by which it can be referenced. A program object is an |
4745 | object to which shader objects can be attached. This provides a | |
8925f36f | 4746 | mechanism to specify the shader objects that will be linked to create a |
c7b31271 | 4747 | program. It also provides a means for checking the compatibility of the |
8925f36f | 4748 | shaders that will be used to create a program (for instance, checking |
c7b31271 | 4749 | the compatibility between a vertex shader and a fragment shader). When |
8925f36f AW |
4750 | no longer needed as part of a program object, shader objects can be |
4751 | detached. | |
4752 | ||
4753 | One or more executables are created in a program object by successfully | |
4754 | attaching shader objects to it with @code{glAttachShader}, successfully | |
4755 | compiling the shader objects with @code{glCompileShader}, and | |
c7b31271 | 4756 | successfully linking the program object with @code{glLinkProgram}. These |
8925f36f | 4757 | executables are made part of current state when @code{glUseProgram} is |
c7b31271 DH |
4758 | called. Program objects can be deleted by calling |
4759 | @code{glDeleteProgram}. The memory associated with the program object | |
8925f36f AW |
4760 | will be deleted when it is no longer part of current rendering state for |
4761 | any context. | |
4762 | ||
8925f36f AW |
4763 | This function returns 0 if an error occurs creating the program object. |
4764 | ||
4765 | @code{GL_INVALID_OPERATION} is generated if @code{glCreateProgram} is | |
4766 | executed between the execution of @code{glBegin} and the corresponding | |
4767 | execution of @code{glEnd}. | |
4768 | ||
bb894c9d | 4769 | @end deftypefun |
8925f36f | 4770 | |
bb894c9d | 4771 | @deftypefun GLuint glCreateShader shaderType |
3c9b6116 AW |
4772 | Creates a shader object. |
4773 | ||
8925f36f AW |
4774 | @table @asis |
4775 | @item @var{shaderType} | |
c7b31271 | 4776 | Specifies the type of shader to be created. Must be either |
8925f36f AW |
4777 | @code{GL_VERTEX_SHADER} or @code{GL_FRAGMENT_SHADER}. |
4778 | ||
4779 | @end table | |
4780 | ||
8925f36f | 4781 | @code{glCreateShader} creates an empty shader object and returns a |
c7b31271 DH |
4782 | non-zero value by which it can be referenced. A shader object is used |
4783 | to maintain the source code strings that define a shader. | |
4784 | @var{shaderType} indicates the type of shader to be created. Two types | |
4785 | of shaders are supported. A shader of type @code{GL_VERTEX_SHADER} is a | |
4786 | shader that is intended to run on the programmable vertex processor and | |
4787 | replace the fixed functionality vertex processing in OpenGL. A shader | |
4788 | of type @code{GL_FRAGMENT_SHADER} is a shader that is intended to run on | |
4789 | the programmable fragment processor and replace the fixed functionality | |
8925f36f AW |
4790 | fragment processing in OpenGL. |
4791 | ||
4792 | When created, a shader object's @code{GL_SHADER_TYPE} parameter is set | |
4793 | to either @code{GL_VERTEX_SHADER} or @code{GL_FRAGMENT_SHADER}, | |
4794 | depending on the value of @var{shaderType}. | |
4795 | ||
8925f36f AW |
4796 | This function returns 0 if an error occurs creating the shader object. |
4797 | ||
4798 | @code{GL_INVALID_ENUM} is generated if @var{shaderType} is not an | |
4799 | accepted value. | |
4800 | ||
4801 | @code{GL_INVALID_OPERATION} is generated if @code{glCreateShader} is | |
4802 | executed between the execution of @code{glBegin} and the corresponding | |
4803 | execution of @code{glEnd}. | |
4804 | ||
bb894c9d | 4805 | @end deftypefun |
8925f36f | 4806 | |
bb894c9d | 4807 | @deftypefun void glCullFace mode |
3c9b6116 AW |
4808 | Specify whether front- or back-facing facets can be culled. |
4809 | ||
8925f36f AW |
4810 | @table @asis |
4811 | @item @var{mode} | |
4812 | Specifies whether front- or back-facing facets are candidates for | |
c7b31271 DH |
4813 | culling. Symbolic constants @code{GL_FRONT}, @code{GL_BACK}, and |
4814 | @code{GL_FRONT_AND_BACK} are accepted. The initial value is | |
8925f36f AW |
4815 | @code{GL_BACK}. |
4816 | ||
4817 | @end table | |
4818 | ||
8925f36f | 4819 | @code{glCullFace} specifies whether front- or back-facing facets are |
c7b31271 DH |
4820 | culled (as specified by @var{mode}) when facet culling is enabled. Facet |
4821 | culling is initially disabled. To enable and disable facet culling, | |
4822 | call the @code{glEnable} and @code{glDisable} commands with the argument | |
4823 | @code{GL_CULL_FACE}. Facets include triangles, quadrilaterals, | |
4824 | polygons, and rectangles. | |
8925f36f AW |
4825 | |
4826 | @code{glFrontFace} specifies which of the clockwise and counterclockwise | |
c7b31271 | 4827 | facets are front-facing and back-facing. See @code{glFrontFace}. |
8925f36f | 4828 | |
8925f36f AW |
4829 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
4830 | value. | |
4831 | ||
4832 | @code{GL_INVALID_OPERATION} is generated if @code{glCullFace} is | |
4833 | executed between the execution of @code{glBegin} and the corresponding | |
4834 | execution of @code{glEnd}. | |
4835 | ||
bb894c9d | 4836 | @end deftypefun |
8925f36f | 4837 | |
bb894c9d | 4838 | @deftypefun void glDeleteBuffers n buffers |
3c9b6116 AW |
4839 | Delete named buffer objects. |
4840 | ||
8925f36f AW |
4841 | @table @asis |
4842 | @item @var{n} | |
4843 | Specifies the number of buffer objects to be deleted. | |
4844 | ||
4845 | @item @var{buffers} | |
4846 | Specifies an array of buffer objects to be deleted. | |
4847 | ||
4848 | @end table | |
4849 | ||
8925f36f | 4850 | @code{glDeleteBuffers} deletes @var{n} buffer objects named by the |
c7b31271 | 4851 | elements of the array @var{buffers}. After a buffer object is deleted, |
8925f36f | 4852 | it has no contents, and its name is free for reuse (for example by |
c7b31271 | 4853 | @code{glGenBuffers}). If a buffer object that is currently bound is |
8925f36f AW |
4854 | deleted, the binding reverts to 0 (the absence of any buffer object, |
4855 | which reverts to client memory usage). | |
4856 | ||
4857 | @code{glDeleteBuffers} silently ignores 0's and names that do not | |
4858 | correspond to existing buffer objects. | |
4859 | ||
8925f36f AW |
4860 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
4861 | ||
4862 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteBuffers} is | |
4863 | executed between the execution of @code{glBegin} and the corresponding | |
4864 | execution of @code{glEnd}. | |
4865 | ||
bb894c9d | 4866 | @end deftypefun |
8925f36f | 4867 | |
bb894c9d | 4868 | @deftypefun void glDeleteLists list range |
3c9b6116 AW |
4869 | Delete a contiguous group of display lists. |
4870 | ||
8925f36f AW |
4871 | @table @asis |
4872 | @item @var{list} | |
4873 | Specifies the integer name of the first display list to delete. | |
4874 | ||
4875 | @item @var{range} | |
4876 | Specifies the number of display lists to delete. | |
4877 | ||
4878 | @end table | |
4879 | ||
8925f36f | 4880 | @code{glDeleteLists} causes a contiguous group of display lists to be |
c7b31271 DH |
4881 | deleted. @var{list} is the name of the first display list to be |
4882 | deleted, and @var{range} is the number of display lists to delete. All | |
4883 | display lists @r{@var{d}} with | |
4884 | @r{@var{list}<=@var{d}<=@var{list}+@var{range}-1} are deleted. | |
8925f36f AW |
4885 | |
4886 | All storage locations allocated to the specified display lists are | |
c7b31271 | 4887 | freed, and the names are available for reuse at a later time. Names |
8925f36f | 4888 | within the range that do not have an associated display list are |
c7b31271 | 4889 | ignored. If @var{range} is 0, nothing happens. |
8925f36f | 4890 | |
8925f36f AW |
4891 | @code{GL_INVALID_VALUE} is generated if @var{range} is negative. |
4892 | ||
4893 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteLists} is | |
4894 | executed between the execution of @code{glBegin} and the corresponding | |
4895 | execution of @code{glEnd}. | |
4896 | ||
bb894c9d | 4897 | @end deftypefun |
8925f36f | 4898 | |
bb894c9d | 4899 | @deftypefun void glDeleteProgram program |
3c9b6116 AW |
4900 | Deletes a program object. |
4901 | ||
8925f36f AW |
4902 | @table @asis |
4903 | @item @var{program} | |
4904 | Specifies the program object to be deleted. | |
4905 | ||
4906 | @end table | |
4907 | ||
8925f36f AW |
4908 | @code{glDeleteProgram} frees the memory and invalidates the name |
4909 | associated with the program object specified by @var{program.} This | |
4910 | command effectively undoes the effects of a call to | |
4911 | @code{glCreateProgram}. | |
4912 | ||
4913 | If a program object is in use as part of current rendering state, it | |
4914 | will be flagged for deletion, but it will not be deleted until it is no | |
c7b31271 | 4915 | longer part of current state for any rendering context. If a program |
8925f36f AW |
4916 | object to be deleted has shader objects attached to it, those shader |
4917 | objects will be automatically detached but not deleted unless they have | |
4918 | already been flagged for deletion by a previous call to | |
c7b31271 | 4919 | @code{glDeleteShader}. A value of 0 for @var{program} will be silently |
8925f36f AW |
4920 | ignored. |
4921 | ||
4922 | To determine whether a program object has been flagged for deletion, | |
4923 | call @code{glGetProgram} with arguments @var{program} and | |
4924 | @code{GL_DELETE_STATUS}. | |
4925 | ||
8925f36f AW |
4926 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
4927 | generated by OpenGL. | |
4928 | ||
4929 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteProgram} is | |
4930 | executed between the execution of @code{glBegin} and the corresponding | |
4931 | execution of @code{glEnd}. | |
4932 | ||
bb894c9d | 4933 | @end deftypefun |
8925f36f | 4934 | |
bb894c9d | 4935 | @deftypefun void glDeleteQueries n ids |
3c9b6116 AW |
4936 | Delete named query objects. |
4937 | ||
8925f36f AW |
4938 | @table @asis |
4939 | @item @var{n} | |
4940 | Specifies the number of query objects to be deleted. | |
4941 | ||
4942 | @item @var{ids} | |
4943 | Specifies an array of query objects to be deleted. | |
4944 | ||
4945 | @end table | |
4946 | ||
8925f36f | 4947 | @code{glDeleteQueries} deletes @var{n} query objects named by the |
c7b31271 DH |
4948 | elements of the array @var{ids}. After a query object is deleted, it |
4949 | has no contents, and its name is free for reuse (for example by | |
8925f36f AW |
4950 | @code{glGenQueries}). |
4951 | ||
4952 | @code{glDeleteQueries} silently ignores 0's and names that do not | |
4953 | correspond to existing query objects. | |
4954 | ||
8925f36f AW |
4955 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
4956 | ||
4957 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteQueries} is | |
4958 | executed between the execution of @code{glBegin} and the corresponding | |
4959 | execution of @code{glEnd}. | |
4960 | ||
bb894c9d | 4961 | @end deftypefun |
8925f36f | 4962 | |
bb894c9d | 4963 | @deftypefun void glDeleteShader shader |
3c9b6116 AW |
4964 | Deletes a shader object. |
4965 | ||
8925f36f AW |
4966 | @table @asis |
4967 | @item @var{shader} | |
4968 | Specifies the shader object to be deleted. | |
4969 | ||
4970 | @end table | |
4971 | ||
8925f36f | 4972 | @code{glDeleteShader} frees the memory and invalidates the name |
c7b31271 | 4973 | associated with the shader object specified by @var{shader}. This |
8925f36f AW |
4974 | command effectively undoes the effects of a call to |
4975 | @code{glCreateShader}. | |
4976 | ||
4977 | If a shader object to be deleted is attached to a program object, it | |
4978 | will be flagged for deletion, but it will not be deleted until it is no | |
4979 | longer attached to any program object, for any rendering context (i.e., | |
4980 | it must be detached from wherever it was attached before it will be | |
c7b31271 | 4981 | deleted). A value of 0 for @var{shader} will be silently ignored. |
8925f36f AW |
4982 | |
4983 | To determine whether an object has been flagged for deletion, call | |
4984 | @code{glGetShader} with arguments @var{shader} and | |
4985 | @code{GL_DELETE_STATUS}. | |
4986 | ||
8925f36f AW |
4987 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
4988 | generated by OpenGL. | |
4989 | ||
4990 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteShader} is | |
4991 | executed between the execution of @code{glBegin} and the corresponding | |
4992 | execution of @code{glEnd}. | |
4993 | ||
bb894c9d | 4994 | @end deftypefun |
8925f36f | 4995 | |
bb894c9d | 4996 | @deftypefun void glDeleteTextures n textures |
3c9b6116 AW |
4997 | Delete named textures. |
4998 | ||
8925f36f AW |
4999 | @table @asis |
5000 | @item @var{n} | |
5001 | Specifies the number of textures to be deleted. | |
5002 | ||
5003 | @item @var{textures} | |
5004 | Specifies an array of textures to be deleted. | |
5005 | ||
5006 | @end table | |
5007 | ||
8925f36f | 5008 | @code{glDeleteTextures} deletes @var{n} textures named by the elements |
c7b31271 | 5009 | of the array @var{textures}. After a texture is deleted, it has no |
8925f36f | 5010 | contents or dimensionality, and its name is free for reuse (for example |
c7b31271 | 5011 | by @code{glGenTextures}). If a texture that is currently bound is |
8925f36f AW |
5012 | deleted, the binding reverts to 0 (the default texture). |
5013 | ||
5014 | @code{glDeleteTextures} silently ignores 0's and names that do not | |
5015 | correspond to existing textures. | |
5016 | ||
8925f36f AW |
5017 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
5018 | ||
5019 | @code{GL_INVALID_OPERATION} is generated if @code{glDeleteTextures} is | |
5020 | executed between the execution of @code{glBegin} and the corresponding | |
5021 | execution of @code{glEnd}. | |
5022 | ||
bb894c9d | 5023 | @end deftypefun |
8925f36f | 5024 | |
bb894c9d | 5025 | @deftypefun void glDepthFunc func |
3c9b6116 AW |
5026 | Specify the value used for depth buffer comparisons. |
5027 | ||
8925f36f AW |
5028 | @table @asis |
5029 | @item @var{func} | |
c7b31271 | 5030 | Specifies the depth comparison function. Symbolic constants |
8925f36f AW |
5031 | @code{GL_NEVER}, @code{GL_LESS}, @code{GL_EQUAL}, @code{GL_LEQUAL}, |
5032 | @code{GL_GREATER}, @code{GL_NOTEQUAL}, @code{GL_GEQUAL}, and | |
c7b31271 | 5033 | @code{GL_ALWAYS} are accepted. The initial value is @code{GL_LESS}. |
8925f36f AW |
5034 | |
5035 | @end table | |
5036 | ||
8925f36f | 5037 | @code{glDepthFunc} specifies the function used to compare each incoming |
c7b31271 DH |
5038 | pixel depth value with the depth value present in the depth buffer. The |
5039 | comparison is performed only if depth testing is enabled. (See | |
8925f36f AW |
5040 | @code{glEnable} and @code{glDisable} of @code{GL_DEPTH_TEST}.) |
5041 | ||
5042 | @var{func} specifies the conditions under which the pixel will be drawn. | |
5043 | The comparison functions are as follows: | |
5044 | ||
5045 | @table @asis | |
5046 | @item @code{GL_NEVER} | |
5047 | Never passes. | |
5048 | ||
5049 | @item @code{GL_LESS} | |
5050 | Passes if the incoming depth value is less than the stored depth value. | |
5051 | ||
5052 | @item @code{GL_EQUAL} | |
5053 | Passes if the incoming depth value is equal to the stored depth value. | |
5054 | ||
5055 | @item @code{GL_LEQUAL} | |
5056 | Passes if the incoming depth value is less than or equal to the stored | |
5057 | depth value. | |
5058 | ||
5059 | @item @code{GL_GREATER} | |
5060 | Passes if the incoming depth value is greater than the stored depth | |
5061 | value. | |
5062 | ||
5063 | @item @code{GL_NOTEQUAL} | |
5064 | Passes if the incoming depth value is not equal to the stored depth | |
5065 | value. | |
5066 | ||
5067 | @item @code{GL_GEQUAL} | |
5068 | Passes if the incoming depth value is greater than or equal to the | |
5069 | stored depth value. | |
5070 | ||
5071 | @item @code{GL_ALWAYS} | |
5072 | Always passes. | |
5073 | ||
5074 | @end table | |
5075 | ||
c7b31271 DH |
5076 | The initial value of @var{func} is @code{GL_LESS}. Initially, depth |
5077 | testing is disabled. If depth testing is disabled or if no depth buffer | |
8925f36f AW |
5078 | exists, it is as if the depth test always passes. |
5079 | ||
8925f36f AW |
5080 | @code{GL_INVALID_ENUM} is generated if @var{func} is not an accepted |
5081 | value. | |
5082 | ||
5083 | @code{GL_INVALID_OPERATION} is generated if @code{glDepthFunc} is | |
5084 | executed between the execution of @code{glBegin} and the corresponding | |
5085 | execution of @code{glEnd}. | |
5086 | ||
bb894c9d | 5087 | @end deftypefun |
8925f36f | 5088 | |
bb894c9d | 5089 | @deftypefun void glDepthMask flag |
3c9b6116 AW |
5090 | Enable or disable writing into the depth buffer. |
5091 | ||
8925f36f AW |
5092 | @table @asis |
5093 | @item @var{flag} | |
c7b31271 DH |
5094 | Specifies whether the depth buffer is enabled for writing. If |
5095 | @var{flag} is @code{GL_FALSE}, depth buffer writing is disabled. | |
5096 | Otherwise, it is enabled. Initially, depth buffer writing is enabled. | |
8925f36f AW |
5097 | |
5098 | @end table | |
5099 | ||
8925f36f | 5100 | @code{glDepthMask} specifies whether the depth buffer is enabled for |
c7b31271 DH |
5101 | writing. If @var{flag} is @code{GL_FALSE}, depth buffer writing is |
5102 | disabled. Otherwise, it is enabled. Initially, depth buffer writing is | |
8925f36f AW |
5103 | enabled. |
5104 | ||
8925f36f AW |
5105 | @code{GL_INVALID_OPERATION} is generated if @code{glDepthMask} is |
5106 | executed between the execution of @code{glBegin} and the corresponding | |
5107 | execution of @code{glEnd}. | |
5108 | ||
bb894c9d | 5109 | @end deftypefun |
8925f36f | 5110 | |
bb894c9d | 5111 | @deftypefun void glDepthRange nearVal farVal |
3c9b6116 AW |
5112 | Specify mapping of depth values from normalized device coordinates to |
5113 | window coordinates. | |
5114 | ||
8925f36f AW |
5115 | @table @asis |
5116 | @item @var{nearVal} | |
5117 | Specifies the mapping of the near clipping plane to window coordinates. | |
5118 | The initial value is 0. | |
5119 | ||
5120 | @item @var{farVal} | |
5121 | Specifies the mapping of the far clipping plane to window coordinates. | |
5122 | The initial value is 1. | |
5123 | ||
5124 | @end table | |
5125 | ||
8925f36f | 5126 | After clipping and division by @var{w}, depth coordinates range from |
3c9b6116 | 5127 | @r{-1} to 1, corresponding to the near and far clipping planes. |
8925f36f | 5128 | @code{glDepthRange} specifies a linear mapping of the normalized depth |
c7b31271 DH |
5129 | coordinates in this range to window depth coordinates. Regardless of |
5130 | the actual depth buffer implementation, window coordinate depth values | |
5131 | are treated as though they range from 0 through 1 (like color | |
5132 | components). Thus, the values accepted by @code{glDepthRange} are both | |
5133 | clamped to this range before they are accepted. | |
8925f36f AW |
5134 | |
5135 | The setting of (0,1) maps the near plane to 0 and the far plane to 1. | |
5136 | With this mapping, the depth buffer range is fully utilized. | |
5137 | ||
8925f36f AW |
5138 | @code{GL_INVALID_OPERATION} is generated if @code{glDepthRange} is |
5139 | executed between the execution of @code{glBegin} and the corresponding | |
5140 | execution of @code{glEnd}. | |
5141 | ||
bb894c9d | 5142 | @end deftypefun |
8925f36f | 5143 | |
bb894c9d | 5144 | @deftypefun void glDetachShader program shader |
3c9b6116 AW |
5145 | Detaches a shader object from a program object to which it is attached. |
5146 | ||
8925f36f AW |
5147 | @table @asis |
5148 | @item @var{program} | |
5149 | Specifies the program object from which to detach the shader object. | |
5150 | ||
5151 | @item @var{shader} | |
5152 | Specifies the shader object to be detached. | |
5153 | ||
5154 | @end table | |
5155 | ||
8925f36f | 5156 | @code{glDetachShader} detaches the shader object specified by |
c7b31271 | 5157 | @var{shader} from the program object specified by @var{program}. This |
8925f36f AW |
5158 | command can be used to undo the effect of the command |
5159 | @code{glAttachShader}. | |
5160 | ||
5161 | If @var{shader} has already been flagged for deletion by a call to | |
5162 | @code{glDeleteShader} and it is not attached to any other program | |
5163 | object, it will be deleted after it has been detached. | |
5164 | ||
8925f36f AW |
5165 | @code{GL_INVALID_VALUE} is generated if either @var{program} or |
5166 | @var{shader} is a value that was not generated by OpenGL. | |
5167 | ||
5168 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
5169 | program object. | |
5170 | ||
5171 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
5172 | object. | |
5173 | ||
5174 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not attached | |
5175 | to @var{program}. | |
5176 | ||
5177 | @code{GL_INVALID_OPERATION} is generated if @code{glDetachShader} is | |
5178 | executed between the execution of @code{glBegin} and the corresponding | |
5179 | execution of @code{glEnd}. | |
5180 | ||
bb894c9d | 5181 | @end deftypefun |
8925f36f | 5182 | |
bb894c9d | 5183 | @deftypefun void glDrawArrays mode first count |
3c9b6116 AW |
5184 | Render primitives from array data. |
5185 | ||
8925f36f AW |
5186 | @table @asis |
5187 | @item @var{mode} | |
c7b31271 | 5188 | Specifies what kind of primitives to render. Symbolic constants |
8925f36f AW |
5189 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, |
5190 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
5191 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
5192 | @code{GL_POLYGON} are accepted. | |
5193 | ||
5194 | @item @var{first} | |
5195 | Specifies the starting index in the enabled arrays. | |
5196 | ||
5197 | @item @var{count} | |
5198 | Specifies the number of indices to be rendered. | |
5199 | ||
5200 | @end table | |
5201 | ||
8925f36f | 5202 | @code{glDrawArrays} specifies multiple geometric primitives with very |
c7b31271 | 5203 | few subroutine calls. Instead of calling a GL procedure to pass each |
8925f36f AW |
5204 | individual vertex, normal, texture coordinate, edge flag, or color, you |
5205 | can prespecify separate arrays of vertices, normals, and colors and use | |
5206 | them to construct a sequence of primitives with a single call to | |
5207 | @code{glDrawArrays}. | |
5208 | ||
5209 | When @code{glDrawArrays} is called, it uses @var{count} sequential | |
5210 | elements from each enabled array to construct a sequence of geometric | |
c7b31271 | 5211 | primitives, beginning with element @var{first}. @var{mode} specifies |
8925f36f | 5212 | what kind of primitives are constructed and how the array elements |
c7b31271 DH |
5213 | construct those primitives. If @code{GL_VERTEX_ARRAY} is not enabled, |
5214 | no geometric primitives are generated. | |
8925f36f AW |
5215 | |
5216 | Vertex attributes that are modified by @code{glDrawArrays} have an | |
c7b31271 | 5217 | unspecified value after @code{glDrawArrays} returns. For example, if |
8925f36f | 5218 | @code{GL_COLOR_ARRAY} is enabled, the value of the current color is |
c7b31271 | 5219 | undefined after @code{glDrawArrays} executes. Attributes that aren't |
8925f36f AW |
5220 | modified remain well defined. |
5221 | ||
8925f36f AW |
5222 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
5223 | value. | |
5224 | ||
5225 | @code{GL_INVALID_VALUE} is generated if @var{count} is negative. | |
5226 | ||
5227 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5228 | name is bound to an enabled array and the buffer object's data store is | |
5229 | currently mapped. | |
5230 | ||
5231 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawArrays} is | |
5232 | executed between the execution of @code{glBegin} and the corresponding | |
5233 | @code{glEnd}. | |
5234 | ||
bb894c9d | 5235 | @end deftypefun |
8925f36f | 5236 | |
bb894c9d | 5237 | @deftypefun void glDrawBuffers n bufs |
3c9b6116 AW |
5238 | Specifies a list of color buffers to be drawn into. |
5239 | ||
8925f36f AW |
5240 | @table @asis |
5241 | @item @var{n} | |
5242 | Specifies the number of buffers in @var{bufs}. | |
5243 | ||
5244 | @item @var{bufs} | |
5245 | Points to an array of symbolic constants specifying the buffers into | |
5246 | which fragment colors or data values will be written. | |
5247 | ||
5248 | @end table | |
5249 | ||
8925f36f | 5250 | @code{glDrawBuffers} defines an array of buffers into which fragment |
c7b31271 | 5251 | color values or fragment data will be written. If no fragment shader is |
8925f36f AW |
5252 | active, rendering operations will generate only one fragment color per |
5253 | fragment and it will be written into each of the buffers specified by | |
c7b31271 | 5254 | @var{bufs}. If a fragment shader is active and it writes a value to the |
8925f36f | 5255 | output variable @code{gl_FragColor}, then that value will be written |
c7b31271 | 5256 | into each of the buffers specified by @var{bufs}. If a fragment shader |
8925f36f AW |
5257 | is active and it writes a value to one or more elements of the output |
5258 | array variable @code{gl_FragData[]}, then the value of | |
5259 | @code{gl_FragData[0] } will be written into the first buffer specified | |
5260 | by @var{bufs}, the value of @code{gl_FragData[1] } will be written into | |
5261 | the second buffer specified by @var{bufs}, and so on up to | |
c7b31271 | 5262 | @code{gl_FragData[n-1]}. The draw buffer used for @code{gl_FragData[n]} |
8925f36f AW |
5263 | and beyond is implicitly set to be @code{GL_NONE}. |
5264 | ||
5265 | The symbolic constants contained in @var{bufs} may be any of the | |
5266 | following: | |
5267 | ||
5268 | @table @asis | |
5269 | @item @code{GL_NONE} | |
5270 | The fragment color/data value is not written into any color buffer. | |
5271 | ||
5272 | @item @code{GL_FRONT_LEFT} | |
5273 | The fragment color/data value is written into the front left color | |
5274 | buffer. | |
5275 | ||
5276 | @item @code{GL_FRONT_RIGHT} | |
5277 | The fragment color/data value is written into the front right color | |
5278 | buffer. | |
5279 | ||
5280 | @item @code{GL_BACK_LEFT} | |
5281 | The fragment color/data value is written into the back left color | |
5282 | buffer. | |
5283 | ||
5284 | @item @code{GL_BACK_RIGHT} | |
5285 | The fragment color/data value is written into the back right color | |
5286 | buffer. | |
5287 | ||
5288 | @item @code{GL_AUXi} | |
5289 | The fragment color/data value is written into auxiliary buffer @code{i}. | |
5290 | ||
5291 | @end table | |
5292 | ||
5293 | Except for @code{GL_NONE}, the preceding symbolic constants may not | |
c7b31271 | 5294 | appear more than once in @var{bufs}. The maximum number of draw buffers |
8925f36f | 5295 | supported is implementation dependent and can be queried by calling |
c7b31271 DH |
5296 | @code{glGet} with the argument @code{GL_MAX_DRAW_BUFFERS}. The number |
5297 | of auxiliary buffers can be queried by calling @code{glGet} with the | |
8925f36f AW |
5298 | argument @code{GL_AUX_BUFFERS}. |
5299 | ||
8925f36f AW |
5300 | @code{GL_INVALID_ENUM} is generated if one of the values in @var{bufs} |
5301 | is not an accepted value. | |
5302 | ||
5303 | @code{GL_INVALID_ENUM} is generated if @var{n} is less than 0. | |
5304 | ||
5305 | @code{GL_INVALID_OPERATION} is generated if a symbolic constant other | |
5306 | than @code{GL_NONE} appears more than once in @var{bufs}. | |
5307 | ||
5308 | @code{GL_INVALID_OPERATION} is generated if any of the entries in | |
5309 | @var{bufs} (other than @code{GL_NONE} ) indicates a color buffer that | |
5310 | does not exist in the current GL context. | |
5311 | ||
5312 | @code{GL_INVALID_VALUE} is generated if @var{n} is greater than | |
5313 | @code{GL_MAX_DRAW_BUFFERS}. | |
5314 | ||
5315 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawBuffers} is | |
5316 | executed between the execution of @code{glBegin} and the corresponding | |
5317 | execution of @code{glEnd}. | |
5318 | ||
bb894c9d | 5319 | @end deftypefun |
8925f36f | 5320 | |
bb894c9d | 5321 | @deftypefun void glDrawBuffer mode |
3c9b6116 AW |
5322 | Specify which color buffers are to be drawn into. |
5323 | ||
8925f36f AW |
5324 | @table @asis |
5325 | @item @var{mode} | |
c7b31271 | 5326 | Specifies up to four color buffers to be drawn into. Symbolic constants |
8925f36f AW |
5327 | @code{GL_NONE}, @code{GL_FRONT_LEFT}, @code{GL_FRONT_RIGHT}, |
5328 | @code{GL_BACK_LEFT}, @code{GL_BACK_RIGHT}, @code{GL_FRONT}, | |
5329 | @code{GL_BACK}, @code{GL_LEFT}, @code{GL_RIGHT}, | |
5330 | @code{GL_FRONT_AND_BACK}, and @code{GL_AUX}@var{i}, where @var{i} is | |
5331 | between 0 and the value of @code{GL_AUX_BUFFERS} minus 1, are accepted. | |
5332 | (@code{GL_AUX_BUFFERS} is not the upper limit; use @code{glGet} to query | |
5333 | the number of available aux buffers.) The initial value is | |
5334 | @code{GL_FRONT} for single-buffered contexts, and @code{GL_BACK} for | |
5335 | double-buffered contexts. | |
5336 | ||
5337 | @end table | |
5338 | ||
8925f36f | 5339 | When colors are written to the frame buffer, they are written into the |
c7b31271 | 5340 | color buffers specified by @code{glDrawBuffer}. The specifications are |
8925f36f AW |
5341 | as follows: |
5342 | ||
5343 | @table @asis | |
5344 | @item @code{GL_NONE} | |
5345 | No color buffers are written. | |
5346 | ||
5347 | @item @code{GL_FRONT_LEFT} | |
5348 | Only the front left color buffer is written. | |
5349 | ||
5350 | @item @code{GL_FRONT_RIGHT} | |
5351 | Only the front right color buffer is written. | |
5352 | ||
5353 | @item @code{GL_BACK_LEFT} | |
5354 | Only the back left color buffer is written. | |
5355 | ||
5356 | @item @code{GL_BACK_RIGHT} | |
5357 | Only the back right color buffer is written. | |
5358 | ||
5359 | @item @code{GL_FRONT} | |
c7b31271 | 5360 | Only the front left and front right color buffers are written. If there |
8925f36f AW |
5361 | is no front right color buffer, only the front left color buffer is |
5362 | written. | |
5363 | ||
5364 | @item @code{GL_BACK} | |
c7b31271 DH |
5365 | Only the back left and back right color buffers are written. If there |
5366 | is no back right color buffer, only the back left color buffer is | |
5367 | written. | |
8925f36f AW |
5368 | |
5369 | @item @code{GL_LEFT} | |
c7b31271 DH |
5370 | Only the front left and back left color buffers are written. If there |
5371 | is no back left color buffer, only the front left color buffer is | |
5372 | written. | |
8925f36f AW |
5373 | |
5374 | @item @code{GL_RIGHT} | |
c7b31271 | 5375 | Only the front right and back right color buffers are written. If there |
8925f36f AW |
5376 | is no back right color buffer, only the front right color buffer is |
5377 | written. | |
5378 | ||
5379 | @item @code{GL_FRONT_AND_BACK} | |
5380 | All the front and back color buffers (front left, front right, back | |
c7b31271 DH |
5381 | left, back right) are written. If there are no back color buffers, only |
5382 | the front left and front right color buffers are written. If there are | |
8925f36f | 5383 | no right color buffers, only the front left and back left color buffers |
c7b31271 DH |
5384 | are written. If there are no right or back color buffers, only the |
5385 | front left color buffer is written. | |
8925f36f AW |
5386 | |
5387 | @item @code{GL_AUX}@var{i} | |
5388 | Only auxiliary color buffer @var{i} is written. | |
5389 | ||
5390 | @end table | |
5391 | ||
5392 | If more than one color buffer is selected for drawing, then blending or | |
5393 | logical operations are computed and applied independently for each color | |
5394 | buffer and can produce different results in each buffer. | |
5395 | ||
5396 | Monoscopic contexts include only @var{left} buffers, and stereoscopic | |
c7b31271 | 5397 | contexts include both @var{left} and @var{right} buffers. Likewise, |
8925f36f AW |
5398 | single-buffered contexts include only @var{front} buffers, and |
5399 | double-buffered contexts include both @var{front} and @var{back} | |
c7b31271 | 5400 | buffers. The context is selected at GL initialization. |
8925f36f | 5401 | |
8925f36f AW |
5402 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
5403 | value. | |
5404 | ||
5405 | @code{GL_INVALID_OPERATION} is generated if none of the buffers | |
5406 | indicated by @var{mode} exists. | |
5407 | ||
5408 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawBuffer} is | |
5409 | executed between the execution of @code{glBegin} and the corresponding | |
5410 | execution of @code{glEnd}. | |
5411 | ||
bb894c9d | 5412 | @end deftypefun |
8925f36f | 5413 | |
bb894c9d | 5414 | @deftypefun void glDrawElements mode count type indices |
3c9b6116 AW |
5415 | Render primitives from array data. |
5416 | ||
8925f36f AW |
5417 | @table @asis |
5418 | @item @var{mode} | |
c7b31271 | 5419 | Specifies what kind of primitives to render. Symbolic constants |
8925f36f AW |
5420 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, |
5421 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
5422 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
5423 | @code{GL_POLYGON} are accepted. | |
5424 | ||
5425 | @item @var{count} | |
5426 | Specifies the number of elements to be rendered. | |
5427 | ||
5428 | @item @var{type} | |
c7b31271 | 5429 | Specifies the type of the values in @var{indices}. Must be one of |
8925f36f AW |
5430 | @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or |
5431 | @code{GL_UNSIGNED_INT}. | |
5432 | ||
5433 | @item @var{indices} | |
5434 | Specifies a pointer to the location where the indices are stored. | |
5435 | ||
5436 | @end table | |
5437 | ||
8925f36f | 5438 | @code{glDrawElements} specifies multiple geometric primitives with very |
c7b31271 | 5439 | few subroutine calls. Instead of calling a GL function to pass each |
8925f36f AW |
5440 | individual vertex, normal, texture coordinate, edge flag, or color, you |
5441 | can prespecify separate arrays of vertices, normals, and so on, and use | |
5442 | them to construct a sequence of primitives with a single call to | |
5443 | @code{glDrawElements}. | |
5444 | ||
5445 | When @code{glDrawElements} is called, it uses @var{count} sequential | |
5446 | elements from an enabled array, starting at @var{indices} to construct a | |
c7b31271 | 5447 | sequence of geometric primitives. @var{mode} specifies what kind of |
8925f36f | 5448 | primitives are constructed and how the array elements construct these |
c7b31271 | 5449 | primitives. If more than one array is enabled, each is used. If |
8925f36f AW |
5450 | @code{GL_VERTEX_ARRAY} is not enabled, no geometric primitives are |
5451 | constructed. | |
5452 | ||
5453 | Vertex attributes that are modified by @code{glDrawElements} have an | |
c7b31271 | 5454 | unspecified value after @code{glDrawElements} returns. For example, if |
8925f36f | 5455 | @code{GL_COLOR_ARRAY} is enabled, the value of the current color is |
c7b31271 | 5456 | undefined after @code{glDrawElements} executes. Attributes that aren't |
8925f36f AW |
5457 | modified maintain their previous values. |
5458 | ||
8925f36f AW |
5459 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
5460 | value. | |
5461 | ||
5462 | @code{GL_INVALID_VALUE} is generated if @var{count} is negative. | |
5463 | ||
5464 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5465 | name is bound to an enabled array or the element array and the buffer | |
5466 | object's data store is currently mapped. | |
5467 | ||
5468 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawElements} is | |
5469 | executed between the execution of @code{glBegin} and the corresponding | |
5470 | @code{glEnd}. | |
5471 | ||
bb894c9d | 5472 | @end deftypefun |
8925f36f | 5473 | |
bb894c9d | 5474 | @deftypefun void glDrawPixels width height format type data |
3c9b6116 AW |
5475 | Write a block of pixels to the frame buffer. |
5476 | ||
8925f36f AW |
5477 | @table @asis |
5478 | @item @var{width} | |
5479 | @itemx @var{height} | |
5480 | Specify the dimensions of the pixel rectangle to be written into the | |
5481 | frame buffer. | |
5482 | ||
5483 | @item @var{format} | |
c7b31271 | 5484 | Specifies the format of the pixel data. Symbolic constants |
8925f36f AW |
5485 | @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, |
5486 | @code{GL_DEPTH_COMPONENT}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, | |
5487 | @code{GL_BGRA}, @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, | |
5488 | @code{GL_ALPHA}, @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA} are | |
5489 | accepted. | |
5490 | ||
5491 | @item @var{type} | |
c7b31271 | 5492 | Specifies the data type for @var{data}. Symbolic constants |
8925f36f AW |
5493 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
5494 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
5495 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
5496 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
5497 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
5498 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
5499 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
5500 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
5501 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
5502 | ||
5503 | @item @var{data} | |
5504 | Specifies a pointer to the pixel data. | |
5505 | ||
5506 | @end table | |
5507 | ||
8925f36f AW |
5508 | @code{glDrawPixels} reads pixel data from memory and writes it into the |
5509 | frame buffer relative to the current raster position, provided that the | |
c7b31271 | 5510 | raster position is valid. Use @code{glRasterPos} or @code{glWindowPos} |
8925f36f AW |
5511 | to set the current raster position; use @code{glGet} with argument |
5512 | @code{GL_CURRENT_RASTER_POSITION_VALID} to determine if the specified | |
5513 | raster position is valid, and @code{glGet} with argument | |
5514 | @code{GL_CURRENT_RASTER_POSITION} to query the raster position. | |
5515 | ||
5516 | Several parameters define the encoding of pixel data in memory and | |
5517 | control the processing of the pixel data before it is placed in the | |
c7b31271 | 5518 | frame buffer. These parameters are set with four commands: |
8925f36f | 5519 | @code{glPixelStore}, @code{glPixelTransfer}, @code{glPixelMap}, and |
c7b31271 | 5520 | @code{glPixelZoom}. This reference page describes the effects on |
8925f36f AW |
5521 | @code{glDrawPixels} of many, but not all, of the parameters specified by |
5522 | these four commands. | |
5523 | ||
5524 | Data is read from @var{data} as a sequence of signed or unsigned bytes, | |
5525 | signed or unsigned shorts, signed or unsigned integers, or | |
c7b31271 | 5526 | single-precision floating-point values, depending on @var{type}. When |
8925f36f AW |
5527 | @var{type} is one of @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, |
5528 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
5529 | @code{GL_INT}, or @code{GL_FLOAT} each of these bytes, shorts, integers, | |
5530 | or floating-point values is interpreted as one color or depth component, | |
c7b31271 | 5531 | or one index, depending on @var{format}. When @var{type} is one of |
8925f36f AW |
5532 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_SHORT_5_6_5}, |
5533 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
5534 | @code{GL_UNSIGNED_INT_8_8_8_8}, or @code{GL_UNSIGNED_INT_10_10_10_2}, | |
5535 | each unsigned value is interpreted as containing all the components for | |
5536 | a single pixel, with the color components arranged according to | |
c7b31271 | 5537 | @var{format}. When @var{type} is one of |
8925f36f AW |
5538 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, |
5539 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
5540 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
5541 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, or | |
5542 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}, each unsigned value is | |
5543 | interpreted as containing all color components, specified by | |
c7b31271 DH |
5544 | @var{format}, for a single pixel in a reversed order. Indices are |
5545 | always treated individually. Color components are treated as groups of | |
5546 | one, two, three, or four values, again based on @var{format}. Both | |
5547 | individual indices and groups of components are referred to as pixels. | |
5548 | If @var{type} is @code{GL_BITMAP}, the data must be unsigned bytes, and | |
8925f36f | 5549 | @var{format} must be either @code{GL_COLOR_INDEX} or |
c7b31271 | 5550 | @code{GL_STENCIL_INDEX}. Each unsigned byte is treated as eight 1-bit |
8925f36f AW |
5551 | pixels, with bit ordering determined by @code{GL_UNPACK_LSB_FIRST} (see |
5552 | @code{glPixelStore}). | |
5553 | ||
3c9b6116 | 5554 | @r{@var{width}×@var{height}} pixels are read from memory, starting at |
c7b31271 | 5555 | location @var{data}. By default, these pixels are taken from adjacent |
8925f36f | 5556 | memory locations, except that after all @var{width} pixels are read, the |
c7b31271 | 5557 | read pointer is advanced to the next four-byte boundary. The four-byte |
8925f36f AW |
5558 | row alignment is specified by @code{glPixelStore} with argument |
5559 | @code{GL_UNPACK_ALIGNMENT}, and it can be set to one, two, four, or | |
c7b31271 DH |
5560 | eight bytes. Other pixel store parameters specify different read |
5561 | pointer advancements, both before the first pixel is read and after all | |
5562 | @var{width} pixels are read. See the @code{glPixelStore} reference page | |
8925f36f AW |
5563 | for details on these options. |
5564 | ||
5565 | If a non-zero named buffer object is bound to the | |
5566 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
5567 | block of pixels is specified, @var{data} is treated as a byte offset | |
5568 | into the buffer object's data store. | |
5569 | ||
3c9b6116 | 5570 | The @r{@var{width}×@var{height}} pixels that are read from memory are |
8925f36f AW |
5571 | each operated on in the same way, based on the values of several |
5572 | parameters specified by @code{glPixelTransfer} and @code{glPixelMap}. | |
5573 | The details of these operations, as well as the target buffer into which | |
5574 | the pixels are drawn, are specific to the format of the pixels, as | |
c7b31271 | 5575 | specified by @var{format}. @var{format} can assume one of 13 symbolic |
8925f36f AW |
5576 | values: |
5577 | ||
5578 | @table @asis | |
5579 | @item @code{GL_COLOR_INDEX} | |
c7b31271 | 5580 | Each pixel is a single value, a color index. It is converted to |
8925f36f | 5581 | fixed-point format, with an unspecified number of bits to the right of |
c7b31271 DH |
5582 | the binary point, regardless of the memory data type. Floating-point |
5583 | values convert to true fixed-point values. Signed and unsigned integer | |
5584 | data is converted with all fraction bits set to 0. Bitmap data convert | |
8925f36f AW |
5585 | to either 0 or 1. |
5586 | ||
5587 | Each fixed-point index is then shifted left by @code{GL_INDEX_SHIFT} | |
c7b31271 DH |
5588 | bits and added to @code{GL_INDEX_OFFSET}. If @code{GL_INDEX_SHIFT} is |
5589 | negative, the shift is to the right. In either case, zero bits fill | |
8925f36f AW |
5590 | otherwise unspecified bit locations in the result. |
5591 | ||
5592 | If the GL is in RGBA mode, the resulting index is converted to an RGBA | |
5593 | pixel with the help of the @code{GL_PIXEL_MAP_I_TO_R}, | |
5594 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
c7b31271 DH |
5595 | @code{GL_PIXEL_MAP_I_TO_A} tables. If the GL is in color index mode, |
5596 | and if @code{GL_MAP_COLOR} is true, the index is replaced with the value | |
5597 | that it references in lookup table @code{GL_PIXEL_MAP_I_TO_I}. Whether | |
8925f36f | 5598 | the lookup replacement of the index is done or not, the integer part of |
3c9b6116 AW |
5599 | the index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the |
5600 | number of bits in a color index buffer. | |
8925f36f AW |
5601 | |
5602 | The GL then converts the resulting indices or RGBA colors to fragments | |
5603 | by attaching the current raster position @var{z} coordinate and texture | |
3c9b6116 AW |
5604 | coordinates to each pixel, then assigning @r{@var{x}} and @r{@var{y}} |
5605 | window coordinates to the @r{@var{n}}th fragment such that | |
5606 | @r{@var{x}_@var{n}=@var{x}_@var{r}+@var{n}%@var{width}}@r{@var{y}_@var{n}=@var{y}_@var{r}+⌊@var{n}/@var{width},⌋} | |
8925f36f | 5607 | |
3c9b6116 | 5608 | where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster |
c7b31271 DH |
5609 | position. These pixel fragments are then treated just like the |
5610 | fragments generated by rasterizing points, lines, or polygons. Texture | |
5611 | mapping, fog, and all the fragment operations are applied before the | |
5612 | fragments are written to the frame buffer. | |
8925f36f AW |
5613 | |
5614 | @item @code{GL_STENCIL_INDEX} | |
c7b31271 | 5615 | Each pixel is a single value, a stencil index. It is converted to |
8925f36f | 5616 | fixed-point format, with an unspecified number of bits to the right of |
c7b31271 DH |
5617 | the binary point, regardless of the memory data type. Floating-point |
5618 | values convert to true fixed-point values. Signed and unsigned integer | |
5619 | data is converted with all fraction bits set to 0. Bitmap data convert | |
8925f36f AW |
5620 | to either 0 or 1. |
5621 | ||
5622 | Each fixed-point index is then shifted left by @code{GL_INDEX_SHIFT} | |
c7b31271 DH |
5623 | bits, and added to @code{GL_INDEX_OFFSET}. If @code{GL_INDEX_SHIFT} is |
5624 | negative, the shift is to the right. In either case, zero bits fill | |
5625 | otherwise unspecified bit locations in the result. If | |
8925f36f | 5626 | @code{GL_MAP_STENCIL} is true, the index is replaced with the value that |
c7b31271 | 5627 | it references in lookup table @code{GL_PIXEL_MAP_S_TO_S}. Whether the |
8925f36f | 5628 | lookup replacement of the index is done or not, the integer part of the |
3c9b6116 | 5629 | index is then ANDed with @r{2^@var{b}-1}, where @r{@var{b}} is the |
c7b31271 | 5630 | number of bits in the stencil buffer. The resulting stencil indices are |
3c9b6116 AW |
5631 | then written to the stencil buffer such that the @r{@var{n}}th index is |
5632 | written to location | |
8925f36f | 5633 | |
3c9b6116 | 5634 | @r{@var{x}_@var{n}=@var{x}_@var{r}+@var{n}%@var{width}}@r{@var{y}_@var{n}=@var{y}_@var{r}+⌊@var{n}/@var{width},⌋} |
8925f36f | 5635 | |
3c9b6116 | 5636 | where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster |
c7b31271 | 5637 | position. Only the pixel ownership test, the scissor test, and the |
8925f36f AW |
5638 | stencil writemask affect these write operations. |
5639 | ||
5640 | @item @code{GL_DEPTH_COMPONENT} | |
c7b31271 DH |
5641 | Each pixel is a single-depth component. Floating-point data is |
5642 | converted directly to an internal floating-point format with unspecified | |
5643 | precision. Signed integer data is mapped linearly to the internal | |
8925f36f AW |
5644 | floating-point format such that the most positive representable integer |
5645 | value maps to 1.0, and the most negative representable value maps to | |
c7b31271 DH |
5646 | @r{-1.0}. Unsigned integer data is mapped similarly: the largest |
5647 | integer value maps to 1.0, and 0 maps to 0.0. The resulting | |
5648 | floating-point depth value is then multiplied by @code{GL_DEPTH_SCALE} | |
5649 | and added to @code{GL_DEPTH_BIAS}. The result is clamped to the range | |
5650 | @r{[0,1]}. | |
8925f36f AW |
5651 | |
5652 | The GL then converts the resulting depth components to fragments by | |
5653 | attaching the current raster position color or color index and texture | |
3c9b6116 AW |
5654 | coordinates to each pixel, then assigning @r{@var{x}} and @r{@var{y}} |
5655 | window coordinates to the @r{@var{n}}th fragment such that | |
8925f36f | 5656 | |
3c9b6116 | 5657 | @r{@var{x}_@var{n}=@var{x}_@var{r}+@var{n}%@var{width}}@r{@var{y}_@var{n}=@var{y}_@var{r}+⌊@var{n}/@var{width},⌋} |
8925f36f | 5658 | |
3c9b6116 | 5659 | where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster |
c7b31271 DH |
5660 | position. These pixel fragments are then treated just like the |
5661 | fragments generated by rasterizing points, lines, or polygons. Texture | |
5662 | mapping, fog, and all the fragment operations are applied before the | |
5663 | fragments are written to the frame buffer. | |
8925f36f AW |
5664 | |
5665 | @item @code{GL_RGBA} | |
5666 | @item @code{GL_BGRA} | |
5667 | Each pixel is a four-component group: For @code{GL_RGBA}, the red | |
5668 | component is first, followed by green, followed by blue, followed by | |
5669 | alpha; for @code{GL_BGRA} the order is blue, green, red and then alpha. | |
5670 | Floating-point values are converted directly to an internal | |
c7b31271 | 5671 | floating-point format with unspecified precision. Signed integer values |
8925f36f AW |
5672 | are mapped linearly to the internal floating-point format such that the |
5673 | most positive representable integer value maps to 1.0, and the most | |
c7b31271 | 5674 | negative representable value maps to @r{-1.0}. (Note that this mapping |
3c9b6116 | 5675 | does not convert 0 precisely to 0.0.) Unsigned integer data is mapped |
c7b31271 | 5676 | similarly: The largest integer value maps to 1.0, and 0 maps to 0.0. The |
3c9b6116 | 5677 | resulting floating-point color values are then multiplied by |
8925f36f | 5678 | @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where @var{c} is RED, |
c7b31271 | 5679 | GREEN, BLUE, and ALPHA for the respective color components. The results |
3c9b6116 | 5680 | are clamped to the range @r{[0,1]}. |
8925f36f AW |
5681 | |
5682 | If @code{GL_MAP_COLOR} is true, each color component is scaled by the | |
5683 | size of lookup table @code{GL_PIXEL_MAP_c_TO_c}, then replaced by the | |
c7b31271 | 5684 | value that it references in that table. @var{c} is R, G, B, or A |
8925f36f AW |
5685 | respectively. |
5686 | ||
5687 | The GL then converts the resulting RGBA colors to fragments by attaching | |
5688 | the current raster position @var{z} coordinate and texture coordinates | |
3c9b6116 AW |
5689 | to each pixel, then assigning @r{@var{x}} and @r{@var{y}} window |
5690 | coordinates to the @r{@var{n}}th fragment such that | |
8925f36f | 5691 | |
3c9b6116 | 5692 | @r{@var{x}_@var{n}=@var{x}_@var{r}+@var{n}%@var{width}}@r{@var{y}_@var{n}=@var{y}_@var{r}+⌊@var{n}/@var{width},⌋} |
8925f36f | 5693 | |
3c9b6116 | 5694 | where @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster |
c7b31271 DH |
5695 | position. These pixel fragments are then treated just like the |
5696 | fragments generated by rasterizing points, lines, or polygons. Texture | |
5697 | mapping, fog, and all the fragment operations are applied before the | |
5698 | fragments are written to the frame buffer. | |
8925f36f AW |
5699 | |
5700 | @item @code{GL_RED} | |
c7b31271 DH |
5701 | Each pixel is a single red component. This component is converted to |
5702 | the internal floating-point format in the same way the red component of | |
5703 | an RGBA pixel is. It is then converted to an RGBA pixel with green and | |
5704 | blue set to 0, and alpha set to 1. After this conversion, the pixel is | |
8925f36f AW |
5705 | treated as if it had been read as an RGBA pixel. |
5706 | ||
5707 | @item @code{GL_GREEN} | |
c7b31271 | 5708 | Each pixel is a single green component. This component is converted to |
8925f36f | 5709 | the internal floating-point format in the same way the green component |
c7b31271 DH |
5710 | of an RGBA pixel is. It is then converted to an RGBA pixel with red and |
5711 | blue set to 0, and alpha set to 1. After this conversion, the pixel is | |
8925f36f AW |
5712 | treated as if it had been read as an RGBA pixel. |
5713 | ||
5714 | @item @code{GL_BLUE} | |
c7b31271 | 5715 | Each pixel is a single blue component. This component is converted to |
8925f36f | 5716 | the internal floating-point format in the same way the blue component of |
c7b31271 DH |
5717 | an RGBA pixel is. It is then converted to an RGBA pixel with red and |
5718 | green set to 0, and alpha set to 1. After this conversion, the pixel is | |
8925f36f AW |
5719 | treated as if it had been read as an RGBA pixel. |
5720 | ||
5721 | @item @code{GL_ALPHA} | |
c7b31271 | 5722 | Each pixel is a single alpha component. This component is converted to |
8925f36f | 5723 | the internal floating-point format in the same way the alpha component |
c7b31271 DH |
5724 | of an RGBA pixel is. It is then converted to an RGBA pixel with red, |
5725 | green, and blue set to 0. After this conversion, the pixel is treated | |
5726 | as if it had been read as an RGBA pixel. | |
8925f36f AW |
5727 | |
5728 | @item @code{GL_RGB} | |
5729 | @item @code{GL_BGR} | |
5730 | Each pixel is a three-component group: red first, followed by green, | |
5731 | followed by blue; for @code{GL_BGR}, the first component is blue, | |
c7b31271 | 5732 | followed by green and then red. Each component is converted to the |
8925f36f | 5733 | internal floating-point format in the same way the red, green, and blue |
c7b31271 DH |
5734 | components of an RGBA pixel are. The color triple is converted to an |
5735 | RGBA pixel with alpha set to 1. After this conversion, the pixel is | |
8925f36f AW |
5736 | treated as if it had been read as an RGBA pixel. |
5737 | ||
5738 | @item @code{GL_LUMINANCE} | |
c7b31271 | 5739 | Each pixel is a single luminance component. This component is converted |
8925f36f | 5740 | to the internal floating-point format in the same way the red component |
c7b31271 | 5741 | of an RGBA pixel is. It is then converted to an RGBA pixel with red, |
8925f36f | 5742 | green, and blue set to the converted luminance value, and alpha set to |
c7b31271 DH |
5743 | 1. After this conversion, the pixel is treated as if it had been read |
5744 | as an RGBA pixel. | |
8925f36f AW |
5745 | |
5746 | @item @code{GL_LUMINANCE_ALPHA} | |
5747 | Each pixel is a two-component group: luminance first, followed by alpha. | |
5748 | The two components are converted to the internal floating-point format | |
c7b31271 | 5749 | in the same way the red component of an RGBA pixel is. They are then |
8925f36f AW |
5750 | converted to an RGBA pixel with red, green, and blue set to the |
5751 | converted luminance value, and alpha set to the converted alpha value. | |
5752 | After this conversion, the pixel is treated as if it had been read as an | |
5753 | RGBA pixel. | |
5754 | ||
5755 | @end table | |
5756 | ||
5757 | The following table summarizes the meaning of the valid constants for | |
5758 | the @var{type} parameter: | |
5759 | ||
5760 | ||
5761 | ||
5762 | @table @asis | |
5763 | @item @strong{Type} | |
5764 | @strong{Corresponding Type} | |
5765 | ||
5766 | @item @code{GL_UNSIGNED_BYTE} | |
5767 | unsigned 8-bit integer | |
5768 | ||
5769 | @item @code{GL_BYTE} | |
5770 | signed 8-bit integer | |
5771 | ||
5772 | @item @code{GL_BITMAP} | |
5773 | single bits in unsigned 8-bit integers | |
5774 | ||
5775 | @item @code{GL_UNSIGNED_SHORT} | |
5776 | unsigned 16-bit integer | |
5777 | ||
5778 | @item @code{GL_SHORT} | |
5779 | signed 16-bit integer | |
5780 | ||
5781 | @item @code{GL_UNSIGNED_INT} | |
5782 | unsigned 32-bit integer | |
5783 | ||
5784 | @item @code{GL_INT} | |
5785 | 32-bit integer | |
5786 | ||
5787 | @item @code{GL_FLOAT} | |
5788 | single-precision floating-point | |
5789 | ||
5790 | @item @code{GL_UNSIGNED_BYTE_3_3_2} | |
5791 | unsigned 8-bit integer | |
5792 | ||
5793 | @item @code{GL_UNSIGNED_BYTE_2_3_3_REV} | |
5794 | unsigned 8-bit integer with reversed component ordering | |
5795 | ||
5796 | @item @code{GL_UNSIGNED_SHORT_5_6_5} | |
5797 | unsigned 16-bit integer | |
5798 | ||
5799 | @item @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
5800 | unsigned 16-bit integer with reversed component ordering | |
5801 | ||
5802 | @item @code{GL_UNSIGNED_SHORT_4_4_4_4} | |
5803 | unsigned 16-bit integer | |
5804 | ||
5805 | @item @code{GL_UNSIGNED_SHORT_4_4_4_4_REV} | |
5806 | unsigned 16-bit integer with reversed component ordering | |
5807 | ||
5808 | @item @code{GL_UNSIGNED_SHORT_5_5_5_1} | |
5809 | unsigned 16-bit integer | |
5810 | ||
5811 | @item @code{GL_UNSIGNED_SHORT_1_5_5_5_REV} | |
5812 | unsigned 16-bit integer with reversed component ordering | |
5813 | ||
5814 | @item @code{GL_UNSIGNED_INT_8_8_8_8} | |
5815 | unsigned 32-bit integer | |
5816 | ||
5817 | @item @code{GL_UNSIGNED_INT_8_8_8_8_REV} | |
5818 | unsigned 32-bit integer with reversed component ordering | |
5819 | ||
5820 | @item @code{GL_UNSIGNED_INT_10_10_10_2} | |
5821 | unsigned 32-bit integer | |
5822 | ||
5823 | @item @code{GL_UNSIGNED_INT_2_10_10_10_REV} | |
5824 | unsigned 32-bit integer with reversed component ordering | |
5825 | ||
5826 | @end table | |
5827 | ||
5828 | ||
5829 | ||
c7b31271 | 5830 | The rasterization described so far assumes pixel zoom factors of 1. If |
3c9b6116 | 5831 | @code{glPixelZoom} is used to change the @r{@var{x}} and @r{@var{y}} |
c7b31271 | 5832 | pixel zoom factors, pixels are converted to fragments as follows. If |
3c9b6116 AW |
5833 | @r{(@var{x}_@var{r},@var{y}_@var{r})} is the current raster position, |
5834 | and a given pixel is in the @r{@var{n}}th column and @r{@var{m}}th row | |
5835 | of the pixel rectangle, then fragments are generated for pixels whose | |
5836 | centers are in the rectangle with corners at | |
8925f36f | 5837 | |
3c9b6116 | 5838 | @r{(@var{x}_@var{r}+@var{zoom}_@var{x},@var{n},@var{y}_@var{r}+@var{zoom}_@var{y},@var{m})}@r{(@var{x}_@var{r}+@var{zoom}_@var{x},(@var{n}+1,),@var{y}_@var{r}+@var{zoom}_@var{y},(@var{m}+1,))} |
8925f36f | 5839 | |
3c9b6116 AW |
5840 | where @r{@var{zoom}_@var{x}} is the value of @code{GL_ZOOM_X} and |
5841 | @r{@var{zoom}_@var{y}} is the value of @code{GL_ZOOM_Y}. | |
8925f36f | 5842 | |
8925f36f AW |
5843 | @code{GL_INVALID_ENUM} is generated if @var{format} or @var{type} is not |
5844 | one of the accepted values. | |
5845 | ||
5846 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
5847 | and @var{format} is not either @code{GL_COLOR_INDEX} or | |
5848 | @code{GL_STENCIL_INDEX}. | |
5849 | ||
5850 | @code{GL_INVALID_VALUE} is generated if either @var{width} or | |
5851 | @var{height} is negative. | |
5852 | ||
5853 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
5854 | @code{GL_STENCIL_INDEX} and there is no stencil buffer. | |
5855 | ||
5856 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
5857 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, | |
5858 | @code{GL_RGB}, @code{GL_RGBA}, @code{GL_BGR}, @code{GL_BGRA}, | |
5859 | @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}, and the GL is in | |
5860 | color index mode. | |
5861 | ||
5862 | @code{GL_INVALID_OPERATION} is generated if @var{format} is one of | |
5863 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
5864 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
5865 | and @var{format} is not @code{GL_RGB}. | |
5866 | ||
5867 | @code{GL_INVALID_OPERATION} is generated if @var{format} is one of | |
5868 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
5869 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
5870 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
5871 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
5872 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
5873 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
5874 | ||
5875 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5876 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
5877 | object's data store is currently mapped. | |
5878 | ||
5879 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5880 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
5881 | would be unpacked from the buffer object such that the memory reads | |
5882 | required would exceed the data store size. | |
5883 | ||
5884 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5885 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
5886 | is not evenly divisible into the number of bytes needed to store in | |
5887 | memory a datum indicated by @var{type}. | |
5888 | ||
5889 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawPixels} is | |
5890 | executed between the execution of @code{glBegin} and the corresponding | |
5891 | execution of @code{glEnd}. | |
5892 | ||
bb894c9d | 5893 | @end deftypefun |
8925f36f | 5894 | |
bb894c9d | 5895 | @deftypefun void glDrawRangeElements mode start end count type indices |
3c9b6116 AW |
5896 | Render primitives from array data. |
5897 | ||
8925f36f AW |
5898 | @table @asis |
5899 | @item @var{mode} | |
c7b31271 | 5900 | Specifies what kind of primitives to render. Symbolic constants |
8925f36f AW |
5901 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, |
5902 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
5903 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
5904 | @code{GL_POLYGON} are accepted. | |
5905 | ||
5906 | @item @var{start} | |
5907 | Specifies the minimum array index contained in @var{indices}. | |
5908 | ||
5909 | @item @var{end} | |
5910 | Specifies the maximum array index contained in @var{indices}. | |
5911 | ||
5912 | @item @var{count} | |
5913 | Specifies the number of elements to be rendered. | |
5914 | ||
5915 | @item @var{type} | |
c7b31271 | 5916 | Specifies the type of the values in @var{indices}. Must be one of |
8925f36f AW |
5917 | @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or |
5918 | @code{GL_UNSIGNED_INT}. | |
5919 | ||
5920 | @item @var{indices} | |
5921 | Specifies a pointer to the location where the indices are stored. | |
5922 | ||
5923 | @end table | |
5924 | ||
8925f36f | 5925 | @code{glDrawRangeElements} is a restricted form of |
c7b31271 | 5926 | @code{glDrawElements}. @var{mode}, @var{start}, @var{end}, and |
8925f36f AW |
5927 | @var{count} match the corresponding arguments to @code{glDrawElements}, |
5928 | with the additional constraint that all values in the arrays @var{count} | |
5929 | must lie between @var{start} and @var{end}, inclusive. | |
5930 | ||
5931 | Implementations denote recommended maximum amounts of vertex and index | |
5932 | data, which may be queried by calling @code{glGet} with argument | |
c7b31271 | 5933 | @code{GL_MAX_ELEMENTS_VERTICES} and @code{GL_MAX_ELEMENTS_INDICES}. If |
3c9b6116 | 5934 | @r{@var{end}-@var{start}+1} is greater than the value of |
8925f36f AW |
5935 | @code{GL_MAX_ELEMENTS_VERTICES}, or if @var{count} is greater than the |
5936 | value of @code{GL_MAX_ELEMENTS_INDICES}, then the call may operate at | |
c7b31271 DH |
5937 | reduced performance. There is no requirement that all vertices in the |
5938 | range @r{[@var{start},@var{end}]} be referenced. However, the | |
8925f36f AW |
5939 | implementation may partially process unused vertices, reducing |
5940 | performance from what could be achieved with an optimal index set. | |
5941 | ||
5942 | When @code{glDrawRangeElements} is called, it uses @var{count} | |
5943 | sequential elements from an enabled array, starting at @var{start} to | |
c7b31271 | 5944 | construct a sequence of geometric primitives. @var{mode} specifies what |
8925f36f | 5945 | kind of primitives are constructed, and how the array elements construct |
c7b31271 | 5946 | these primitives. If more than one array is enabled, each is used. If |
8925f36f AW |
5947 | @code{GL_VERTEX_ARRAY} is not enabled, no geometric primitives are |
5948 | constructed. | |
5949 | ||
5950 | Vertex attributes that are modified by @code{glDrawRangeElements} have | |
c7b31271 | 5951 | an unspecified value after @code{glDrawRangeElements} returns. For |
8925f36f | 5952 | example, if @code{GL_COLOR_ARRAY} is enabled, the value of the current |
c7b31271 | 5953 | color is undefined after @code{glDrawRangeElements} executes. Attributes |
8925f36f AW |
5954 | that aren't modified maintain their previous values. |
5955 | ||
8925f36f | 5956 | It is an error for indices to lie outside the range |
3c9b6116 | 5957 | @r{[@var{start},@var{end}]}, but implementations may not check for this |
c7b31271 | 5958 | situation. Such indices cause implementation-dependent behavior. |
8925f36f AW |
5959 | |
5960 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted | |
5961 | value. | |
5962 | ||
5963 | @code{GL_INVALID_VALUE} is generated if @var{count} is negative. | |
5964 | ||
3c9b6116 | 5965 | @code{GL_INVALID_VALUE} is generated if @r{@var{end}<@var{start}}. |
8925f36f AW |
5966 | |
5967 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
5968 | name is bound to an enabled array or the element array and the buffer | |
5969 | object's data store is currently mapped. | |
5970 | ||
5971 | @code{GL_INVALID_OPERATION} is generated if @code{glDrawRangeElements} | |
5972 | is executed between the execution of @code{glBegin} and the | |
5973 | corresponding @code{glEnd}. | |
5974 | ||
bb894c9d | 5975 | @end deftypefun |
8925f36f | 5976 | |
bb894c9d | 5977 | @deftypefun void glEdgeFlagPointer stride pointer |
3c9b6116 AW |
5978 | Define an array of edge flags. |
5979 | ||
8925f36f AW |
5980 | @table @asis |
5981 | @item @var{stride} | |
c7b31271 | 5982 | Specifies the byte offset between consecutive edge flags. If |
8925f36f | 5983 | @var{stride} is 0, the edge flags are understood to be tightly packed in |
c7b31271 | 5984 | the array. The initial value is 0. |
8925f36f AW |
5985 | |
5986 | @item @var{pointer} | |
c7b31271 | 5987 | Specifies a pointer to the first edge flag in the array. The initial |
8925f36f AW |
5988 | value is 0. |
5989 | ||
5990 | @end table | |
5991 | ||
8925f36f | 5992 | @code{glEdgeFlagPointer} specifies the location and data format of an |
c7b31271 | 5993 | array of boolean edge flags to use when rendering. @var{stride} |
8925f36f AW |
5994 | specifies the byte stride from one edge flag to the next, allowing |
5995 | vertices and attributes to be packed into a single array or stored in | |
5996 | separate arrays. | |
5997 | ||
5998 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
5999 | target (see @code{glBindBuffer}) while an edge flag array is specified, | |
6000 | @var{pointer} is treated as a byte offset into the buffer object's data | |
c7b31271 | 6001 | store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING}) |
8925f36f AW |
6002 | is saved as edge flag vertex array client-side state |
6003 | (@code{GL_EDGE_FLAG_ARRAY_BUFFER_BINDING}). | |
6004 | ||
6005 | When an edge flag array is specified, @var{stride} and @var{pointer} are | |
6006 | saved as client-side state, in addition to the current vertex array | |
6007 | buffer object binding. | |
6008 | ||
6009 | To enable and disable the edge flag array, call | |
6010 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
c7b31271 | 6011 | argument @code{GL_EDGE_FLAG_ARRAY}. If enabled, the edge flag array is |
8925f36f AW |
6012 | used when @code{glDrawArrays}, @code{glMultiDrawArrays}, |
6013 | @code{glDrawElements}, @code{glMultiDrawElements}, | |
6014 | @code{glDrawRangeElements}, or @code{glArrayElement} is called. | |
6015 | ||
8925f36f AW |
6016 | @code{GL_INVALID_ENUM} is generated if @var{stride} is negative. |
6017 | ||
bb894c9d | 6018 | @end deftypefun |
8925f36f | 6019 | |
bb894c9d | 6020 | @deftypefun void glEdgeFlag flag |
d172eed9 | 6021 | @deftypefunx void glEdgeFlagv flag |
3c9b6116 AW |
6022 | Flag edges as either boundary or nonboundary. |
6023 | ||
8925f36f AW |
6024 | @table @asis |
6025 | @item @var{flag} | |
6026 | Specifies the current edge flag value, either @code{GL_TRUE} or | |
c7b31271 | 6027 | @code{GL_FALSE}. The initial value is @code{GL_TRUE}. |
8925f36f AW |
6028 | |
6029 | @end table | |
6030 | ||
8925f36f AW |
6031 | Each vertex of a polygon, separate triangle, or separate quadrilateral |
6032 | specified between a @code{glBegin}/@code{glEnd} pair is marked as the | |
c7b31271 DH |
6033 | start of either a boundary or nonboundary edge. If the current edge |
6034 | flag is true when the vertex is specified, the vertex is marked as the | |
6035 | start of a boundary edge. Otherwise, the vertex is marked as the start | |
6036 | of a nonboundary edge. @code{glEdgeFlag} sets the edge flag bit to | |
8925f36f AW |
6037 | @code{GL_TRUE} if @var{flag} is @code{GL_TRUE} and to @code{GL_FALSE} |
6038 | otherwise. | |
6039 | ||
6040 | The vertices of connected triangles and connected quadrilaterals are | |
6041 | always marked as boundary, regardless of the value of the edge flag. | |
6042 | ||
6043 | Boundary and nonboundary edge flags on vertices are significant only if | |
c7b31271 | 6044 | @code{GL_POLYGON_MODE} is set to @code{GL_POINT} or @code{GL_LINE}. See |
8925f36f AW |
6045 | @code{glPolygonMode}. |
6046 | ||
bb894c9d | 6047 | @end deftypefun |
8925f36f | 6048 | |
bb894c9d AW |
6049 | @deftypefun void glEnableClientState cap |
6050 | @deftypefunx void glDisableClientState cap | |
3c9b6116 AW |
6051 | Enable or disable client-side capability. |
6052 | ||
8925f36f AW |
6053 | @table @asis |
6054 | @item @var{cap} | |
c7b31271 | 6055 | Specifies the capability to enable. Symbolic constants |
8925f36f AW |
6056 | @code{GL_COLOR_ARRAY}, @code{GL_EDGE_FLAG_ARRAY}, |
6057 | @code{GL_FOG_COORD_ARRAY}, @code{GL_INDEX_ARRAY}, | |
6058 | @code{GL_NORMAL_ARRAY}, @code{GL_SECONDARY_COLOR_ARRAY}, | |
6059 | @code{GL_TEXTURE_COORD_ARRAY}, and @code{GL_VERTEX_ARRAY} are accepted. | |
6060 | ||
6061 | @end table | |
6062 | ||
8925f36f | 6063 | @code{glEnableClientState} and @code{glDisableClientState} enable or |
c7b31271 DH |
6064 | disable individual client-side capabilities. By default, all |
6065 | client-side capabilities are disabled. Both @code{glEnableClientState} | |
6066 | and @code{glDisableClientState} take a single argument, @var{cap}, which | |
6067 | can assume one of the following values: | |
8925f36f AW |
6068 | |
6069 | @table @asis | |
6070 | @item @code{GL_COLOR_ARRAY} | |
6071 | If enabled, the color array is enabled for writing and used during | |
6072 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6073 | @code{glDrawElements}, | |
6074 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
c7b31271 | 6075 | @code{glMultiDrawElements} is called. See @code{glColorPointer}. |
8925f36f AW |
6076 | |
6077 | @item @code{GL_EDGE_FLAG_ARRAY} | |
6078 | If enabled, the edge flag array is enabled for writing and used during | |
6079 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6080 | @code{glDrawElements}, | |
6081 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
c7b31271 | 6082 | @code{glMultiDrawElements} is called. See @code{glEdgeFlagPointer}. |
8925f36f AW |
6083 | |
6084 | @item @code{GL_FOG_COORD_ARRAY} | |
6085 | If enabled, the fog coordinate array is enabled for writing and used | |
6086 | during rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6087 | @code{glDrawElements}, | |
6088 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
c7b31271 | 6089 | @code{glMultiDrawElements} is called. See @code{glFogCoordPointer}. |
8925f36f AW |
6090 | |
6091 | @item @code{GL_INDEX_ARRAY} | |
6092 | If enabled, the index array is enabled for writing and used during | |
6093 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6094 | @code{glDrawElements}, | |
6095 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
c7b31271 | 6096 | @code{glMultiDrawElements} is called. See @code{glIndexPointer}. |
8925f36f AW |
6097 | |
6098 | @item @code{GL_NORMAL_ARRAY} | |
6099 | If enabled, the normal array is enabled for writing and used during | |
6100 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6101 | @code{glDrawElements}, | |
6102 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
c7b31271 | 6103 | @code{glMultiDrawElements} is called. See @code{glNormalPointer}. |
8925f36f AW |
6104 | |
6105 | @item @code{GL_SECONDARY_COLOR_ARRAY} | |
6106 | If enabled, the secondary color array is enabled for writing and used | |
6107 | during rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6108 | @code{glDrawElements}, | |
6109 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
c7b31271 | 6110 | @code{glMultiDrawElements} is called. See @code{glColorPointer}. |
8925f36f AW |
6111 | |
6112 | @item @code{GL_TEXTURE_COORD_ARRAY} | |
6113 | If enabled, the texture coordinate array is enabled for writing and used | |
6114 | during rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6115 | @code{glDrawElements}, | |
6116 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
c7b31271 | 6117 | @code{glMultiDrawElements} is called. See @code{glTexCoordPointer}. |
8925f36f AW |
6118 | |
6119 | @item @code{GL_VERTEX_ARRAY} | |
6120 | If enabled, the vertex array is enabled for writing and used during | |
6121 | rendering when @code{glArrayElement}, @code{glDrawArrays}, | |
6122 | @code{glDrawElements}, | |
6123 | @code{glDrawRangeElements}@code{glMultiDrawArrays}, or | |
c7b31271 | 6124 | @code{glMultiDrawElements} is called. See @code{glVertexPointer}. |
8925f36f AW |
6125 | |
6126 | @end table | |
6127 | ||
8925f36f AW |
6128 | @code{GL_INVALID_ENUM} is generated if @var{cap} is not an accepted |
6129 | value. | |
6130 | ||
6131 | @code{glEnableClientState} is not allowed between the execution of | |
6132 | @code{glBegin} and the corresponding @code{glEnd}, but an error may or | |
c7b31271 | 6133 | may not be generated. If no error is generated, the behavior is |
8925f36f AW |
6134 | undefined. |
6135 | ||
bb894c9d | 6136 | @end deftypefun |
8925f36f | 6137 | |
bb894c9d AW |
6138 | @deftypefun void glEnableVertexAttribArray index |
6139 | @deftypefunx void glDisableVertexAttribArray index | |
3c9b6116 AW |
6140 | Enable or disable a generic vertex attribute array. |
6141 | ||
8925f36f AW |
6142 | @table @asis |
6143 | @item @var{index} | |
6144 | Specifies the index of the generic vertex attribute to be enabled or | |
6145 | disabled. | |
6146 | ||
6147 | @end table | |
6148 | ||
8925f36f | 6149 | @code{glEnableVertexAttribArray} enables the generic vertex attribute |
c7b31271 DH |
6150 | array specified by @var{index}. @code{glDisableVertexAttribArray} |
6151 | disables the generic vertex attribute array specified by @var{index}. By | |
8925f36f | 6152 | default, all client-side capabilities are disabled, including all |
c7b31271 | 6153 | generic vertex attribute arrays. If enabled, the values in the generic |
8925f36f AW |
6154 | vertex attribute array will be accessed and used for rendering when |
6155 | calls are made to vertex array commands such as @code{glDrawArrays}, | |
6156 | @code{glDrawElements}, @code{glDrawRangeElements}, | |
6157 | @code{glArrayElement}, @code{glMultiDrawElements}, or | |
6158 | @code{glMultiDrawArrays}. | |
6159 | ||
8925f36f AW |
6160 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or |
6161 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
6162 | ||
6163 | @code{GL_INVALID_OPERATION} is generated if either | |
6164 | @code{glEnableVertexAttribArray } or @code{glDisableVertexAttribArray } | |
6165 | is executed between the execution of @code{glBegin} and the | |
6166 | corresponding execution of @code{glEnd}. | |
6167 | ||
bb894c9d | 6168 | @end deftypefun |
8925f36f | 6169 | |
bb894c9d AW |
6170 | @deftypefun void glEnable cap |
6171 | @deftypefunx void glDisable cap | |
3c9b6116 AW |
6172 | Enable or disable server-side GL capabilities. |
6173 | ||
8925f36f AW |
6174 | @table @asis |
6175 | @item @var{cap} | |
6176 | Specifies a symbolic constant indicating a GL capability. | |
6177 | ||
6178 | @end table | |
6179 | ||
8925f36f | 6180 | @code{glEnable} and @code{glDisable} enable and disable various |
c7b31271 DH |
6181 | capabilities. Use @code{glIsEnabled} or @code{glGet} to determine the |
6182 | current setting of any capability. The initial value for each | |
6183 | capability with the exception of @code{GL_DITHER} and | |
6184 | @code{GL_MULTISAMPLE} is @code{GL_FALSE}. The initial value for | |
6185 | @code{GL_DITHER} and @code{GL_MULTISAMPLE} is @code{GL_TRUE}. | |
8925f36f AW |
6186 | |
6187 | Both @code{glEnable} and @code{glDisable} take a single argument, | |
6188 | @var{cap}, which can assume one of the following values: | |
6189 | ||
6190 | @table @asis | |
6191 | @item @code{GL_ALPHA_TEST} | |
6192 | ||
6193 | ||
c7b31271 | 6194 | If enabled, do alpha testing. See @code{glAlphaFunc}. |
8925f36f AW |
6195 | |
6196 | @item @code{GL_AUTO_NORMAL} | |
6197 | ||
6198 | ||
6199 | If enabled, generate normal vectors when either @code{GL_MAP2_VERTEX_3} | |
c7b31271 | 6200 | or @code{GL_MAP2_VERTEX_4} is used to generate vertices. See |
8925f36f AW |
6201 | @code{glMap2}. |
6202 | ||
6203 | @item @code{GL_BLEND} | |
6204 | ||
6205 | ||
6206 | If enabled, blend the computed fragment color values with the values in | |
c7b31271 | 6207 | the color buffers. See @code{glBlendFunc}. |
8925f36f AW |
6208 | |
6209 | @item @code{GL_CLIP_PLANE}@var{i} | |
6210 | ||
6211 | ||
6212 | If enabled, clip geometry against user-defined clipping plane @var{i}. | |
6213 | See @code{glClipPlane}. | |
6214 | ||
6215 | @item @code{GL_COLOR_LOGIC_OP} | |
6216 | ||
6217 | ||
6218 | If enabled, apply the currently selected logical operation to the | |
c7b31271 | 6219 | computed fragment color and color buffer values. See @code{glLogicOp}. |
8925f36f AW |
6220 | |
6221 | @item @code{GL_COLOR_MATERIAL} | |
6222 | ||
6223 | ||
6224 | If enabled, have one or more material parameters track the current | |
c7b31271 | 6225 | color. See @code{glColorMaterial}. |
8925f36f AW |
6226 | |
6227 | @item @code{GL_COLOR_SUM} | |
6228 | ||
6229 | ||
6230 | If enabled and no fragment shader is active, add the secondary color | |
c7b31271 | 6231 | value to the computed fragment color. See @code{glSecondaryColor}. |
8925f36f AW |
6232 | |
6233 | @item @code{GL_COLOR_TABLE} | |
6234 | ||
6235 | ||
6236 | If enabled, perform a color table lookup on the incoming RGBA color | |
c7b31271 | 6237 | values. See @code{glColorTable}. |
8925f36f AW |
6238 | |
6239 | @item @code{GL_CONVOLUTION_1D} | |
6240 | ||
6241 | ||
6242 | If enabled, perform a 1D convolution operation on incoming RGBA color | |
c7b31271 | 6243 | values. See @code{glConvolutionFilter1D}. |
8925f36f AW |
6244 | |
6245 | @item @code{GL_CONVOLUTION_2D} | |
6246 | ||
6247 | ||
6248 | If enabled, perform a 2D convolution operation on incoming RGBA color | |
c7b31271 | 6249 | values. See @code{glConvolutionFilter2D}. |
8925f36f AW |
6250 | |
6251 | @item @code{GL_CULL_FACE} | |
6252 | ||
6253 | ||
6254 | If enabled, cull polygons based on their winding in window coordinates. | |
6255 | See @code{glCullFace}. | |
6256 | ||
6257 | @item @code{GL_DEPTH_TEST} | |
6258 | ||
6259 | ||
c7b31271 | 6260 | If enabled, do depth comparisons and update the depth buffer. Note that |
8925f36f | 6261 | even if the depth buffer exists and the depth mask is non-zero, the |
c7b31271 | 6262 | depth buffer is not updated if the depth test is disabled. See |
8925f36f AW |
6263 | @code{glDepthFunc} and @code{glDepthRange}. |
6264 | ||
6265 | @item @code{GL_DITHER} | |
6266 | ||
6267 | ||
6268 | If enabled, dither color components or indices before they are written | |
6269 | to the color buffer. | |
6270 | ||
6271 | @item @code{GL_FOG} | |
6272 | ||
6273 | ||
6274 | If enabled and no fragment shader is active, blend a fog color into the | |
c7b31271 | 6275 | post-texturing color. See @code{glFog}. |
8925f36f AW |
6276 | |
6277 | @item @code{GL_HISTOGRAM} | |
6278 | ||
6279 | ||
c7b31271 | 6280 | If enabled, histogram incoming RGBA color values. See |
8925f36f AW |
6281 | @code{glHistogram}. |
6282 | ||
6283 | @item @code{GL_INDEX_LOGIC_OP} | |
6284 | ||
6285 | ||
6286 | If enabled, apply the currently selected logical operation to the | |
c7b31271 | 6287 | incoming index and color buffer indices. See @code{glLogicOp}. |
8925f36f AW |
6288 | |
6289 | @item @code{GL_LIGHT}@var{i} | |
6290 | ||
6291 | ||
6292 | If enabled, include light @var{i} in the evaluation of the lighting | |
c7b31271 | 6293 | equation. See @code{glLightModel} and @code{glLight}. |
8925f36f AW |
6294 | |
6295 | @item @code{GL_LIGHTING} | |
6296 | ||
6297 | ||
6298 | If enabled and no vertex shader is active, use the current lighting | |
c7b31271 DH |
6299 | parameters to compute the vertex color or index. Otherwise, simply |
6300 | associate the current color or index with each vertex. See | |
8925f36f AW |
6301 | @code{glMaterial}, @code{glLightModel}, and @code{glLight}. |
6302 | ||
6303 | @item @code{GL_LINE_SMOOTH} | |
6304 | ||
6305 | ||
c7b31271 DH |
6306 | If enabled, draw lines with correct filtering. Otherwise, draw aliased |
6307 | lines. See @code{glLineWidth}. | |
8925f36f AW |
6308 | |
6309 | @item @code{GL_LINE_STIPPLE} | |
6310 | ||
6311 | ||
c7b31271 | 6312 | If enabled, use the current line stipple pattern when drawing lines. See |
8925f36f AW |
6313 | @code{glLineStipple}. |
6314 | ||
6315 | @item @code{GL_MAP1_COLOR_4} | |
6316 | ||
6317 | ||
6318 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
c7b31271 | 6319 | @code{glEvalPoint1} generate RGBA values. See @code{glMap1}. |
8925f36f AW |
6320 | |
6321 | @item @code{GL_MAP1_INDEX} | |
6322 | ||
6323 | ||
6324 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
c7b31271 | 6325 | @code{glEvalPoint1} generate color indices. See @code{glMap1}. |
8925f36f AW |
6326 | |
6327 | @item @code{GL_MAP1_NORMAL} | |
6328 | ||
6329 | ||
6330 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
c7b31271 | 6331 | @code{glEvalPoint1} generate normals. See @code{glMap1}. |
8925f36f AW |
6332 | |
6333 | @item @code{GL_MAP1_TEXTURE_COORD_1} | |
6334 | ||
6335 | ||
6336 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
c7b31271 | 6337 | @code{glEvalPoint1} generate @var{s} texture coordinates. See |
8925f36f AW |
6338 | @code{glMap1}. |
6339 | ||
6340 | @item @code{GL_MAP1_TEXTURE_COORD_2} | |
6341 | ||
6342 | ||
6343 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6344 | @code{glEvalPoint1} generate @var{s} and @var{t} texture coordinates. | |
6345 | See @code{glMap1}. | |
6346 | ||
6347 | @item @code{GL_MAP1_TEXTURE_COORD_3} | |
6348 | ||
6349 | ||
6350 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6351 | @code{glEvalPoint1} generate @var{s}, @var{t}, and @var{r} texture | |
c7b31271 | 6352 | coordinates. See @code{glMap1}. |
8925f36f AW |
6353 | |
6354 | @item @code{GL_MAP1_TEXTURE_COORD_4} | |
6355 | ||
6356 | ||
6357 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6358 | @code{glEvalPoint1} generate @var{s}, @var{t}, @var{r}, and @var{q} | |
c7b31271 | 6359 | texture coordinates. See @code{glMap1}. |
8925f36f AW |
6360 | |
6361 | @item @code{GL_MAP1_VERTEX_3} | |
6362 | ||
6363 | ||
6364 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6365 | @code{glEvalPoint1} generate @var{x}, @var{y}, and @var{z} vertex | |
c7b31271 | 6366 | coordinates. See @code{glMap1}. |
8925f36f AW |
6367 | |
6368 | @item @code{GL_MAP1_VERTEX_4} | |
6369 | ||
6370 | ||
6371 | If enabled, calls to @code{glEvalCoord1}, @code{glEvalMesh1}, and | |
6372 | @code{glEvalPoint1} generate homogeneous @var{x}, @var{y}, @var{z}, and | |
c7b31271 | 6373 | @var{w} vertex coordinates. See @code{glMap1}. |
8925f36f AW |
6374 | |
6375 | @item @code{GL_MAP2_COLOR_4} | |
6376 | ||
6377 | ||
6378 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
c7b31271 | 6379 | @code{glEvalPoint2} generate RGBA values. See @code{glMap2}. |
8925f36f AW |
6380 | |
6381 | @item @code{GL_MAP2_INDEX} | |
6382 | ||
6383 | ||
6384 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
c7b31271 | 6385 | @code{glEvalPoint2} generate color indices. See @code{glMap2}. |
8925f36f AW |
6386 | |
6387 | @item @code{GL_MAP2_NORMAL} | |
6388 | ||
6389 | ||
6390 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
c7b31271 | 6391 | @code{glEvalPoint2} generate normals. See @code{glMap2}. |
8925f36f AW |
6392 | |
6393 | @item @code{GL_MAP2_TEXTURE_COORD_1} | |
6394 | ||
6395 | ||
6396 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
c7b31271 | 6397 | @code{glEvalPoint2} generate @var{s} texture coordinates. See |
8925f36f AW |
6398 | @code{glMap2}. |
6399 | ||
6400 | @item @code{GL_MAP2_TEXTURE_COORD_2} | |
6401 | ||
6402 | ||
6403 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6404 | @code{glEvalPoint2} generate @var{s} and @var{t} texture coordinates. | |
6405 | See @code{glMap2}. | |
6406 | ||
6407 | @item @code{GL_MAP2_TEXTURE_COORD_3} | |
6408 | ||
6409 | ||
6410 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6411 | @code{glEvalPoint2} generate @var{s}, @var{t}, and @var{r} texture | |
c7b31271 | 6412 | coordinates. See @code{glMap2}. |
8925f36f AW |
6413 | |
6414 | @item @code{GL_MAP2_TEXTURE_COORD_4} | |
6415 | ||
6416 | ||
6417 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6418 | @code{glEvalPoint2} generate @var{s}, @var{t}, @var{r}, and @var{q} | |
c7b31271 | 6419 | texture coordinates. See @code{glMap2}. |
8925f36f AW |
6420 | |
6421 | @item @code{GL_MAP2_VERTEX_3} | |
6422 | ||
6423 | ||
6424 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6425 | @code{glEvalPoint2} generate @var{x}, @var{y}, and @var{z} vertex | |
c7b31271 | 6426 | coordinates. See @code{glMap2}. |
8925f36f AW |
6427 | |
6428 | @item @code{GL_MAP2_VERTEX_4} | |
6429 | ||
6430 | ||
6431 | If enabled, calls to @code{glEvalCoord2}, @code{glEvalMesh2}, and | |
6432 | @code{glEvalPoint2} generate homogeneous @var{x}, @var{y}, @var{z}, and | |
c7b31271 | 6433 | @var{w} vertex coordinates. See @code{glMap2}. |
8925f36f AW |
6434 | |
6435 | @item @code{GL_MINMAX} | |
6436 | ||
6437 | ||
6438 | If enabled, compute the minimum and maximum values of incoming RGBA | |
c7b31271 | 6439 | color values. See @code{glMinmax}. |
8925f36f AW |
6440 | |
6441 | @item @code{GL_MULTISAMPLE} | |
6442 | ||
6443 | ||
6444 | If enabled, use multiple fragment samples in computing the final color | |
c7b31271 | 6445 | of a pixel. See @code{glSampleCoverage}. |
8925f36f AW |
6446 | |
6447 | @item @code{GL_NORMALIZE} | |
6448 | ||
6449 | ||
6450 | If enabled and no vertex shader is active, normal vectors are normalized | |
c7b31271 DH |
6451 | to unit length after transformation and before lighting. This method is |
6452 | generally less efficient than @code{GL_RESCALE_NORMAL}. See | |
8925f36f AW |
6453 | @code{glNormal} and @code{glNormalPointer}. |
6454 | ||
6455 | @item @code{GL_POINT_SMOOTH} | |
6456 | ||
6457 | ||
c7b31271 DH |
6458 | If enabled, draw points with proper filtering. Otherwise, draw aliased |
6459 | points. See @code{glPointSize}. | |
8925f36f AW |
6460 | |
6461 | @item @code{GL_POINT_SPRITE} | |
6462 | ||
6463 | ||
6464 | If enabled, calculate texture coordinates for points based on texture | |
c7b31271 | 6465 | environment and point parameter settings. Otherwise texture coordinates |
8925f36f AW |
6466 | are constant across points. |
6467 | ||
6468 | @item @code{GL_POLYGON_OFFSET_FILL} | |
6469 | ||
6470 | ||
6471 | If enabled, and if the polygon is rendered in @code{GL_FILL} mode, an | |
6472 | offset is added to depth values of a polygon's fragments before the | |
c7b31271 | 6473 | depth comparison is performed. See @code{glPolygonOffset}. |
8925f36f AW |
6474 | |
6475 | @item @code{GL_POLYGON_OFFSET_LINE} | |
6476 | ||
6477 | ||
6478 | If enabled, and if the polygon is rendered in @code{GL_LINE} mode, an | |
6479 | offset is added to depth values of a polygon's fragments before the | |
c7b31271 | 6480 | depth comparison is performed. See @code{glPolygonOffset}. |
8925f36f AW |
6481 | |
6482 | @item @code{GL_POLYGON_OFFSET_POINT} | |
6483 | ||
6484 | ||
6485 | If enabled, an offset is added to depth values of a polygon's fragments | |
6486 | before the depth comparison is performed, if the polygon is rendered in | |
c7b31271 | 6487 | @code{GL_POINT} mode. See @code{glPolygonOffset}. |
8925f36f AW |
6488 | |
6489 | @item @code{GL_POLYGON_SMOOTH} | |
6490 | ||
6491 | ||
c7b31271 DH |
6492 | If enabled, draw polygons with proper filtering. Otherwise, draw |
6493 | aliased polygons. For correct antialiased polygons, an alpha buffer is | |
6494 | needed and the polygons must be sorted front to back. | |
8925f36f AW |
6495 | |
6496 | @item @code{GL_POLYGON_STIPPLE} | |
6497 | ||
6498 | ||
6499 | If enabled, use the current polygon stipple pattern when rendering | |
c7b31271 | 6500 | polygons. See @code{glPolygonStipple}. |
8925f36f AW |
6501 | |
6502 | @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} | |
6503 | ||
6504 | ||
6505 | If enabled, perform a color table lookup on RGBA color values after | |
c7b31271 | 6506 | color matrix transformation. See @code{glColorTable}. |
8925f36f AW |
6507 | |
6508 | @item @code{GL_POST_CONVOLUTION_COLOR_TABLE} | |
6509 | ||
6510 | ||
6511 | If enabled, perform a color table lookup on RGBA color values after | |
c7b31271 | 6512 | convolution. See @code{glColorTable}. |
8925f36f AW |
6513 | |
6514 | @item @code{GL_RESCALE_NORMAL} | |
6515 | ||
6516 | ||
6517 | If enabled and no vertex shader is active, normal vectors are scaled | |
6518 | after transformation and before lighting by a factor computed from the | |
c7b31271 DH |
6519 | modelview matrix. If the modelview matrix scales space uniformly, this |
6520 | has the effect of restoring the transformed normal to unit length. This | |
6521 | method is generally more efficient than @code{GL_NORMALIZE}. See | |
8925f36f AW |
6522 | @code{glNormal} and @code{glNormalPointer}. |
6523 | ||
6524 | @item @code{GL_SAMPLE_ALPHA_TO_COVERAGE} | |
6525 | ||
6526 | ||
6527 | If enabled, compute a temporary coverage value where each bit is | |
c7b31271 | 6528 | determined by the alpha value at the corresponding sample location. The |
8925f36f AW |
6529 | temporary coverage value is then ANDed with the fragment coverage value. |
6530 | ||
6531 | @item @code{GL_SAMPLE_ALPHA_TO_ONE} | |
6532 | ||
6533 | ||
6534 | If enabled, each sample alpha value is replaced by the maximum | |
6535 | representable alpha value. | |
6536 | ||
6537 | @item @code{GL_SAMPLE_COVERAGE} | |
6538 | ||
6539 | ||
6540 | If enabled, the fragment's coverage is ANDed with the temporary coverage | |
c7b31271 DH |
6541 | value. If @code{GL_SAMPLE_COVERAGE_INVERT} is set to @code{GL_TRUE}, |
6542 | invert the coverage value. See @code{glSampleCoverage}. | |
8925f36f AW |
6543 | |
6544 | @item @code{GL_SEPARABLE_2D} | |
6545 | ||
6546 | ||
6547 | If enabled, perform a two-dimensional convolution operation using a | |
c7b31271 | 6548 | separable convolution filter on incoming RGBA color values. See |
8925f36f AW |
6549 | @code{glSeparableFilter2D}. |
6550 | ||
6551 | @item @code{GL_SCISSOR_TEST} | |
6552 | ||
6553 | ||
6554 | If enabled, discard fragments that are outside the scissor rectangle. | |
6555 | See @code{glScissor}. | |
6556 | ||
6557 | @item @code{GL_STENCIL_TEST} | |
6558 | ||
6559 | ||
c7b31271 | 6560 | If enabled, do stencil testing and update the stencil buffer. See |
8925f36f AW |
6561 | @code{glStencilFunc} and @code{glStencilOp}. |
6562 | ||
6563 | @item @code{GL_TEXTURE_1D} | |
6564 | ||
6565 | ||
6566 | If enabled and no fragment shader is active, one-dimensional texturing | |
6567 | is performed (unless two- or three-dimensional or cube-mapped texturing | |
c7b31271 | 6568 | is also enabled). See @code{glTexImage1D}. |
8925f36f AW |
6569 | |
6570 | @item @code{GL_TEXTURE_2D} | |
6571 | ||
6572 | ||
6573 | If enabled and no fragment shader is active, two-dimensional texturing | |
6574 | is performed (unless three-dimensional or cube-mapped texturing is also | |
c7b31271 | 6575 | enabled). See @code{glTexImage2D}. |
8925f36f AW |
6576 | |
6577 | @item @code{GL_TEXTURE_3D} | |
6578 | ||
6579 | ||
6580 | If enabled and no fragment shader is active, three-dimensional texturing | |
c7b31271 | 6581 | is performed (unless cube-mapped texturing is also enabled). See |
8925f36f AW |
6582 | @code{glTexImage3D}. |
6583 | ||
6584 | @item @code{GL_TEXTURE_CUBE_MAP} | |
6585 | ||
6586 | ||
6587 | If enabled and no fragment shader is active, cube-mapped texturing is | |
c7b31271 | 6588 | performed. See @code{glTexImage2D}. |
8925f36f AW |
6589 | |
6590 | @item @code{GL_TEXTURE_GEN_Q} | |
6591 | ||
6592 | ||
6593 | If enabled and no vertex shader is active, the @var{q} texture | |
6594 | coordinate is computed using the texture generation function defined | |
c7b31271 DH |
6595 | with @code{glTexGen}. Otherwise, the current @var{q} texture coordinate |
6596 | is used. See @code{glTexGen}. | |
8925f36f AW |
6597 | |
6598 | @item @code{GL_TEXTURE_GEN_R} | |
6599 | ||
6600 | ||
6601 | If enabled and no vertex shader is active, the @var{r} texture | |
6602 | coordinate is computed using the texture generation function defined | |
c7b31271 DH |
6603 | with @code{glTexGen}. Otherwise, the current @var{r} texture coordinate |
6604 | is used. See @code{glTexGen}. | |
8925f36f AW |
6605 | |
6606 | @item @code{GL_TEXTURE_GEN_S} | |
6607 | ||
6608 | ||
6609 | If enabled and no vertex shader is active, the @var{s} texture | |
6610 | coordinate is computed using the texture generation function defined | |
c7b31271 DH |
6611 | with @code{glTexGen}. Otherwise, the current @var{s} texture coordinate |
6612 | is used. See @code{glTexGen}. | |
8925f36f AW |
6613 | |
6614 | @item @code{GL_TEXTURE_GEN_T} | |
6615 | ||
6616 | ||
6617 | If enabled and no vertex shader is active, the @var{t} texture | |
6618 | coordinate is computed using the texture generation function defined | |
c7b31271 DH |
6619 | with @code{glTexGen}. Otherwise, the current @var{t} texture coordinate |
6620 | is used. See @code{glTexGen}. | |
8925f36f AW |
6621 | |
6622 | @item @code{GL_VERTEX_PROGRAM_POINT_SIZE} | |
6623 | ||
6624 | ||
6625 | If enabled and a vertex shader is active, then the derived point size is | |
6626 | taken from the (potentially clipped) shader builtin @code{gl_PointSize} | |
6627 | and clamped to the implementation-dependent point size range. | |
6628 | ||
6629 | @item @code{GL_VERTEX_PROGRAM_TWO_SIDE} | |
6630 | ||
6631 | ||
6632 | If enabled and a vertex shader is active, it specifies that the GL will | |
6633 | choose between front and back colors based on the polygon's face | |
c7b31271 | 6634 | direction of which the vertex being shaded is a part. It has no effect |
8925f36f AW |
6635 | on points or lines. |
6636 | ||
6637 | @end table | |
6638 | ||
8925f36f AW |
6639 | @code{GL_INVALID_ENUM} is generated if @var{cap} is not one of the |
6640 | values listed previously. | |
6641 | ||
6642 | @code{GL_INVALID_OPERATION} is generated if @code{glEnable} or | |
6643 | @code{glDisable} is executed between the execution of @code{glBegin} and | |
6644 | the corresponding execution of @code{glEnd}. | |
6645 | ||
bb894c9d | 6646 | @end deftypefun |
8925f36f | 6647 | |
ca09631c | 6648 | @deftypefun void glEvalCoord1f u |
d172eed9 | 6649 | @deftypefunx void glEvalCoord1d u |
ca09631c | 6650 | @deftypefunx void glEvalCoord2f u v |
d172eed9 AW |
6651 | @deftypefunx void glEvalCoord2d u v |
6652 | @deftypefunx void glEvalCoord1fv u | |
6653 | @deftypefunx void glEvalCoord1dv u | |
6654 | @deftypefunx void glEvalCoord2fv u | |
6655 | @deftypefunx void glEvalCoord2dv u | |
3c9b6116 AW |
6656 | Evaluate enabled one- and two-dimensional maps. |
6657 | ||
8925f36f AW |
6658 | @table @asis |
6659 | @item @var{u} | |
3c9b6116 AW |
6660 | Specifies a value that is the domain coordinate @r{@var{u}} to the basis |
6661 | function defined in a previous @code{glMap1} or @code{glMap2} command. | |
8925f36f AW |
6662 | |
6663 | @item @var{v} | |
3c9b6116 | 6664 | Specifies a value that is the domain coordinate @r{@var{v}} to the basis |
c7b31271 | 6665 | function defined in a previous @code{glMap2} command. This argument is |
3c9b6116 | 6666 | not present in a @code{glEvalCoord1} command. |
8925f36f AW |
6667 | |
6668 | @end table | |
6669 | ||
8925f36f | 6670 | @code{glEvalCoord1} evaluates enabled one-dimensional maps at argument |
c7b31271 DH |
6671 | @var{u}. @code{glEvalCoord2} does the same for two-dimensional maps |
6672 | using two domain values, @var{u} and @var{v}. To define a map, call | |
8925f36f AW |
6673 | @code{glMap1} and @code{glMap2}; to enable and disable it, call |
6674 | @code{glEnable} and @code{glDisable}. | |
6675 | ||
6676 | When one of the @code{glEvalCoord} commands is issued, all currently | |
c7b31271 | 6677 | enabled maps of the indicated dimension are evaluated. Then, for each |
8925f36f | 6678 | enabled map, it is as if the corresponding GL command had been issued |
c7b31271 | 6679 | with the computed value. That is, if @code{GL_MAP1_INDEX} or |
8925f36f AW |
6680 | @code{GL_MAP2_INDEX} is enabled, a @code{glIndex} command is simulated. |
6681 | If @code{GL_MAP1_COLOR_4} or @code{GL_MAP2_COLOR_4} is enabled, a | |
c7b31271 | 6682 | @code{glColor} command is simulated. If @code{GL_MAP1_NORMAL} or |
8925f36f AW |
6683 | @code{GL_MAP2_NORMAL} is enabled, a normal vector is produced, and if |
6684 | any of @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2}, | |
6685 | @code{GL_MAP1_TEXTURE_COORD_3}, @code{GL_MAP1_TEXTURE_COORD_4}, | |
6686 | @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2}, | |
6687 | @code{GL_MAP2_TEXTURE_COORD_3}, or @code{GL_MAP2_TEXTURE_COORD_4} is | |
6688 | enabled, then an appropriate @code{glTexCoord} command is simulated. | |
6689 | ||
6690 | For color, color index, normal, and texture coordinates the GL uses | |
6691 | evaluated values instead of current values for those evaluations that | |
6692 | are enabled, and current values otherwise, However, the evaluated values | |
c7b31271 | 6693 | do not update the current values. Thus, if @code{glVertex} commands are |
8925f36f AW |
6694 | interspersed with @code{glEvalCoord} commands, the color, normal, and |
6695 | texture coordinates associated with the @code{glVertex} commands are not | |
6696 | affected by the values generated by the @code{glEvalCoord} commands, but | |
6697 | only by the most recent @code{glColor}, @code{glIndex}, @code{glNormal}, | |
6698 | and @code{glTexCoord} commands. | |
6699 | ||
c7b31271 | 6700 | No commands are issued for maps that are not enabled. If more than one |
8925f36f AW |
6701 | texture evaluation is enabled for a particular dimension (for example, |
6702 | @code{GL_MAP2_TEXTURE_COORD_1} and @code{GL_MAP2_TEXTURE_COORD_2}), then | |
6703 | only the evaluation of the map that produces the larger number of | |
6704 | coordinates (in this case, @code{GL_MAP2_TEXTURE_COORD_2}) is carried | |
c7b31271 | 6705 | out. @code{GL_MAP1_VERTEX_4} overrides @code{GL_MAP1_VERTEX_3}, and |
8925f36f | 6706 | @code{GL_MAP2_VERTEX_4} overrides @code{GL_MAP2_VERTEX_3}, in the same |
c7b31271 | 6707 | manner. If neither a three- nor a four-component vertex map is enabled |
8925f36f AW |
6708 | for the specified dimension, the @code{glEvalCoord} command is ignored. |
6709 | ||
6710 | If you have enabled automatic normal generation, by calling | |
6711 | @code{glEnable} with argument @code{GL_AUTO_NORMAL}, @code{glEvalCoord2} | |
6712 | generates surface normals analytically, regardless of the contents or | |
c7b31271 | 6713 | enabling of the @code{GL_MAP2_NORMAL} map. Let |
8925f36f | 6714 | |
3c9b6116 | 6715 | @r{@code{m}=∂@code{p},/∂@var{u},,×∂@code{p},/∂@var{v},,} |
8925f36f | 6716 | |
3c9b6116 AW |
6717 | Then the generated normal @r{@code{n}} is |
6718 | @r{@code{n}=@code{m}/∥@code{m},∥,} | |
8925f36f AW |
6719 | |
6720 | If automatic normal generation is disabled, the corresponding normal map | |
c7b31271 | 6721 | @code{GL_MAP2_NORMAL}, if enabled, is used to produce a normal. If |
8925f36f AW |
6722 | neither automatic normal generation nor a normal map is enabled, no |
6723 | normal is generated for @code{glEvalCoord2} commands. | |
6724 | ||
bb894c9d | 6725 | @end deftypefun |
8925f36f | 6726 | |
bb894c9d AW |
6727 | @deftypefun void glEvalMesh1 mode i1 i2 |
6728 | @deftypefunx void glEvalMesh2 mode i1 i2 j1 j2 | |
3c9b6116 AW |
6729 | Compute a one- or two-dimensional grid of points or lines. |
6730 | ||
8925f36f AW |
6731 | @table @asis |
6732 | @item @var{mode} | |
6733 | In @code{glEvalMesh1}, specifies whether to compute a one-dimensional | |
c7b31271 | 6734 | mesh of points or lines. Symbolic constants @code{GL_POINT} and |
8925f36f AW |
6735 | @code{GL_LINE} are accepted. |
6736 | ||
6737 | @item @var{i1} | |
6738 | @itemx @var{i2} | |
6739 | Specify the first and last integer values for grid domain variable | |
3c9b6116 | 6740 | @r{@var{i}}. |
8925f36f AW |
6741 | |
6742 | @end table | |
6743 | ||
8925f36f AW |
6744 | @code{glMapGrid} and @code{glEvalMesh} are used in tandem to efficiently |
6745 | generate and evaluate a series of evenly-spaced map domain values. | |
6746 | @code{glEvalMesh} steps through the integer domain of a one- or | |
6747 | two-dimensional grid, whose range is the domain of the evaluation maps | |
c7b31271 | 6748 | specified by @code{glMap1} and @code{glMap2}. @var{mode} determines |
8925f36f AW |
6749 | whether the resulting vertices are connected as points, lines, or filled |
6750 | polygons. | |
6751 | ||
6752 | In the one-dimensional case, @code{glEvalMesh1}, the mesh is generated | |
6753 | as if the following code fragment were executed: | |
6754 | ||
6755 | where | |
6756 | ||
6757 | @example | |
6758 | ||
6759 | glBegin( @var{type} ); | |
6760 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) | |
3c9b6116 | 6761 | glEvalCoord1( @r{i·Δ@var{u}+@var{u}_1} ); |
8925f36f AW |
6762 | glEnd(); |
6763 | @end example | |
6764 | ||
3c9b6116 | 6765 | @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}} |
8925f36f | 6766 | |
3c9b6116 | 6767 | and @r{@var{n}}, @r{@var{u}_1}, and @r{@var{u}_2} are the arguments to |
c7b31271 | 6768 | the most recent @code{glMapGrid1} command. @var{type} is |
8925f36f AW |
6769 | @code{GL_POINTS} if @var{mode} is @code{GL_POINT}, or @code{GL_LINES} if |
6770 | @var{mode} is @code{GL_LINE}. | |
6771 | ||
3c9b6116 AW |
6772 | The one absolute numeric requirement is that if @r{@var{i}=@var{n}}, |
6773 | then the value computed from @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly | |
6774 | @r{@var{u}_2}. | |
8925f36f AW |
6775 | |
6776 | In the two-dimensional case, @code{glEvalMesh2}, let .cp | |
3c9b6116 | 6777 | @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}} |
8925f36f | 6778 | |
3c9b6116 | 6779 | @r{Δ@var{v}=(@var{v}_2-@var{v}_1,)/@var{m}} |
8925f36f | 6780 | |
3c9b6116 AW |
6781 | where @r{@var{n}}, @r{@var{u}_1}, @r{@var{u}_2}, @r{@var{m}}, |
6782 | @r{@var{v}_1}, and @r{@var{v}_2} are the arguments to the most recent | |
c7b31271 | 6783 | @code{glMapGrid2} command. Then, if @var{mode} is @code{GL_FILL}, the |
3c9b6116 | 6784 | @code{glEvalMesh2} command is equivalent to: |
8925f36f AW |
6785 | |
6786 | ||
6787 | ||
6788 | @example | |
6789 | ||
6790 | for ( j = @var{j1}; j < @var{j2}; j += 1 ) @{ | |
6791 | glBegin( GL_QUAD_STRIP ); | |
6792 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) @{ | |
3c9b6116 AW |
6793 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
6794 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,(j+1,)·Δ@var{v}+@var{v}_1} ); | |
8925f36f AW |
6795 | @} |
6796 | glEnd(); | |
6797 | @} | |
6798 | @end example | |
6799 | ||
6800 | If @var{mode} is @code{GL_LINE}, then a call to @code{glEvalMesh2} is | |
6801 | equivalent to: | |
6802 | ||
6803 | ||
6804 | ||
6805 | @example | |
6806 | ||
6807 | for ( j = @var{j1}; j <= @var{j2}; j += 1 ) @{ | |
6808 | glBegin( GL_LINE_STRIP ); | |
6809 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) | |
3c9b6116 | 6810 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
8925f36f AW |
6811 | glEnd(); |
6812 | @} | |
6813 | ||
6814 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) @{ | |
6815 | glBegin( GL_LINE_STRIP ); | |
6816 | for ( j = @var{j1}; j <= @var{j1}; j += 1 ) | |
3c9b6116 | 6817 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
8925f36f AW |
6818 | glEnd(); |
6819 | @} | |
6820 | @end example | |
6821 | ||
6822 | And finally, if @var{mode} is @code{GL_POINT}, then a call to | |
6823 | @code{glEvalMesh2} is equivalent to: | |
6824 | ||
6825 | ||
6826 | ||
6827 | @example | |
6828 | ||
6829 | glBegin( GL_POINTS ); | |
6830 | for ( j = @var{j1}; j <= @var{j2}; j += 1 ) | |
6831 | for ( i = @var{i1}; i <= @var{i2}; i += 1 ) | |
3c9b6116 | 6832 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
8925f36f AW |
6833 | glEnd(); |
6834 | @end example | |
6835 | ||
6836 | In all three cases, the only absolute numeric requirements are that if | |
3c9b6116 AW |
6837 | @r{@var{i}=@var{n}}, then the value computed from |
6838 | @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}, and if | |
6839 | @r{@var{j}=@var{m}}, then the value computed from | |
6840 | @r{@var{j}·Δ@var{v}+@var{v}_1} is exactly @r{@var{v}_2}. | |
8925f36f | 6841 | |
8925f36f AW |
6842 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
6843 | value. | |
6844 | ||
6845 | @code{GL_INVALID_OPERATION} is generated if @code{glEvalMesh} is | |
6846 | executed between the execution of @code{glBegin} and the corresponding | |
6847 | execution of @code{glEnd}. | |
6848 | ||
bb894c9d | 6849 | @end deftypefun |
8925f36f | 6850 | |
bb894c9d AW |
6851 | @deftypefun void glEvalPoint1 i |
6852 | @deftypefunx void glEvalPoint2 i j | |
3c9b6116 AW |
6853 | Generate and evaluate a single point in a mesh. |
6854 | ||
8925f36f AW |
6855 | @table @asis |
6856 | @item @var{i} | |
3c9b6116 | 6857 | Specifies the integer value for grid domain variable @r{@var{i}}. |
8925f36f AW |
6858 | |
6859 | @item @var{j} | |
3c9b6116 | 6860 | Specifies the integer value for grid domain variable @r{@var{j}} |
8925f36f AW |
6861 | (@code{glEvalPoint2} only). |
6862 | ||
6863 | @end table | |
6864 | ||
8925f36f AW |
6865 | @code{glMapGrid} and @code{glEvalMesh} are used in tandem to efficiently |
6866 | generate and evaluate a series of evenly spaced map domain values. | |
6867 | @code{glEvalPoint} can be used to evaluate a single grid point in the | |
c7b31271 | 6868 | same gridspace that is traversed by @code{glEvalMesh}. Calling |
8925f36f | 6869 | @code{glEvalPoint1} is equivalent to calling where |
3c9b6116 | 6870 | @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}} |
8925f36f AW |
6871 | |
6872 | @example | |
6873 | ||
3c9b6116 | 6874 | glEvalCoord1( @r{i·Δ@var{u}+@var{u}_1} ); |
8925f36f AW |
6875 | @end example |
6876 | ||
3c9b6116 | 6877 | and @r{@var{n}}, @r{@var{u}_1}, and @r{@var{u}_2} are the arguments to |
c7b31271 | 6878 | the most recent @code{glMapGrid1} command. The one absolute numeric |
3c9b6116 AW |
6879 | requirement is that if @r{@var{i}=@var{n}}, then the value computed from |
6880 | @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}. | |
8925f36f AW |
6881 | |
6882 | In the two-dimensional case, @code{glEvalPoint2}, let | |
6883 | ||
3c9b6116 | 6884 | @r{Δ@var{u}=(@var{u}_2-@var{u}_1,)/@var{n}}@r{Δ@var{v}=(@var{v}_2-@var{v}_1,)/@var{m}} |
8925f36f | 6885 | |
3c9b6116 AW |
6886 | where @r{@var{n}}, @r{@var{u}_1}, @r{@var{u}_2}, @r{@var{m}}, |
6887 | @r{@var{v}_1}, and @r{@var{v}_2} are the arguments to the most recent | |
c7b31271 | 6888 | @code{glMapGrid2} command. Then the @code{glEvalPoint2} command is |
3c9b6116 AW |
6889 | equivalent to calling The only absolute numeric requirements are that if |
6890 | @r{@var{i}=@var{n}}, then the value computed from | |
6891 | @r{@var{i}·Δ@var{u}+@var{u}_1} is exactly @r{@var{u}_2}, and if | |
6892 | @r{@var{j}=@var{m}}, then the value computed from | |
6893 | @r{@var{j}·Δ@var{v}+@var{v}_1} is exactly @r{@var{v}_2}. | |
8925f36f AW |
6894 | |
6895 | @example | |
6896 | ||
3c9b6116 | 6897 | glEvalCoord2( @r{i·Δ@var{u}+@var{u}_1,j·Δ@var{v}+@var{v}_1} ); |
8925f36f AW |
6898 | @end example |
6899 | ||
bb894c9d | 6900 | @end deftypefun |
8925f36f | 6901 | |
bb894c9d | 6902 | @deftypefun void glFeedbackBuffer size type buffer |
3c9b6116 AW |
6903 | Controls feedback mode. |
6904 | ||
8925f36f AW |
6905 | @table @asis |
6906 | @item @var{size} | |
6907 | Specifies the maximum number of values that can be written into | |
6908 | @var{buffer}. | |
6909 | ||
6910 | @item @var{type} | |
6911 | Specifies a symbolic constant that describes the information that will | |
c7b31271 | 6912 | be returned for each vertex. @code{GL_2D}, @code{GL_3D}, |
8925f36f AW |
6913 | @code{GL_3D_COLOR}, @code{GL_3D_COLOR_TEXTURE}, and |
6914 | @code{GL_4D_COLOR_TEXTURE} are accepted. | |
6915 | ||
6916 | @item @var{buffer} | |
6917 | Returns the feedback data. | |
6918 | ||
6919 | @end table | |
6920 | ||
c7b31271 DH |
6921 | The @code{glFeedbackBuffer} function controls feedback. Feedback, like |
6922 | selection, is a GL mode. The mode is selected by calling | |
6923 | @code{glRenderMode} with @code{GL_FEEDBACK}. When the GL is in feedback | |
6924 | mode, no pixels are produced by rasterization. Instead, information | |
8925f36f AW |
6925 | about primitives that would have been rasterized is fed back to the |
6926 | application using the GL. | |
6927 | ||
6928 | @code{glFeedbackBuffer} has three arguments: @var{buffer} is a pointer | |
6929 | to an array of floating-point values into which feedback information is | |
c7b31271 | 6930 | placed. @var{size} indicates the size of the array. @var{type} is a |
8925f36f | 6931 | symbolic constant describing the information that is fed back for each |
c7b31271 | 6932 | vertex. @code{glFeedbackBuffer} must be issued before feedback mode is |
8925f36f | 6933 | enabled (by calling @code{glRenderMode} with argument |
c7b31271 DH |
6934 | @code{GL_FEEDBACK}). Setting @code{GL_FEEDBACK} without establishing |
6935 | the feedback buffer, or calling @code{glFeedbackBuffer} while the GL is | |
6936 | in feedback mode, is an error. | |
8925f36f AW |
6937 | |
6938 | When @code{glRenderMode} is called while in feedback mode, it returns | |
6939 | the number of entries placed in the feedback array and resets the | |
c7b31271 DH |
6940 | feedback array pointer to the base of the feedback buffer. The returned |
6941 | value never exceeds @var{size}. If the feedback data required more room | |
8925f36f | 6942 | than was available in @var{buffer}, @code{glRenderMode} returns a |
c7b31271 | 6943 | negative value. To take the GL out of feedback mode, call |
8925f36f AW |
6944 | @code{glRenderMode} with a parameter value other than |
6945 | @code{GL_FEEDBACK}. | |
6946 | ||
6947 | While in feedback mode, each primitive, bitmap, or pixel rectangle that | |
6948 | would be rasterized generates a block of values that are copied into the | |
c7b31271 | 6949 | feedback array. If doing so would cause the number of entries to exceed |
8925f36f | 6950 | the maximum, the block is partially written so as to fill the array (if |
c7b31271 | 6951 | there is any room left at all), and an overflow flag is set. Each block |
8925f36f | 6952 | begins with a code indicating the primitive type, followed by values |
c7b31271 DH |
6953 | that describe the primitive's vertices and associated data. Entries are |
6954 | also written for bitmaps and pixel rectangles. Feedback occurs after | |
8925f36f AW |
6955 | polygon culling and @code{glPolygonMode} interpretation of polygons has |
6956 | taken place, so polygons that are culled are not returned in the | |
c7b31271 | 6957 | feedback buffer. It can also occur after polygons with more than three |
8925f36f AW |
6958 | edges are broken up into triangles, if the GL implementation renders |
6959 | polygons by performing this decomposition. | |
6960 | ||
6961 | The @code{glPassThrough} command can be used to insert a marker into the | |
c7b31271 | 6962 | feedback buffer. See @code{glPassThrough}. |
8925f36f AW |
6963 | |
6964 | Following is the grammar for the blocks of values written into the | |
c7b31271 DH |
6965 | feedback buffer. Each primitive is indicated with a unique identifying |
6966 | value followed by some number of vertices. Polygon entries include an | |
6967 | integer value indicating how many vertices follow. A vertex is fed back | |
8925f36f AW |
6968 | as some number of floating-point values, as determined by @var{type}. |
6969 | Colors are fed back as four values in RGBA mode and one value in color | |
6970 | index mode. | |
6971 | ||
3c9b6116 AW |
6972 | feedbackList @r{←} feedbackItem feedbackList | feedbackItem feedbackItem |
6973 | @r{←} point | lineSegment | polygon | bitmap | pixelRectangle | passThru | |
6974 | point @r{←}@code{GL_POINT_TOKEN} vertex lineSegment | |
6975 | @r{←}@code{GL_LINE_TOKEN} vertex vertex | @code{GL_LINE_RESET_TOKEN} | |
6976 | vertex vertex polygon @r{←}@code{GL_POLYGON_TOKEN} n polySpec polySpec | |
6977 | @r{←} polySpec vertex | vertex vertex vertex bitmap | |
6978 | @r{←}@code{GL_BITMAP_TOKEN} vertex pixelRectangle | |
6979 | @r{←}@code{GL_DRAW_PIXEL_TOKEN} vertex | @code{GL_COPY_PIXEL_TOKEN} | |
6980 | vertex passThru @r{←}@code{GL_PASS_THROUGH_TOKEN} value vertex @r{←} 2d | |
6981 | | 3d | 3dColor | 3dColorTexture | 4dColorTexture 2d @r{←} value value 3d | |
6982 | @r{←} value value value 3dColor @r{←} value value value color | |
6983 | 3dColorTexture @r{←} value value value color tex 4dColorTexture @r{←} | |
6984 | value value value value color tex color @r{←} rgba | index rgba @r{←} | |
6985 | value value value value index @r{←} value tex @r{←} value value value | |
6986 | value | |
8925f36f AW |
6987 | |
6988 | @var{value} is a floating-point number, and @var{n} is a floating-point | |
6989 | integer giving the number of vertices in the polygon. | |
6990 | @code{GL_POINT_TOKEN}, @code{GL_LINE_TOKEN}, @code{GL_LINE_RESET_TOKEN}, | |
6991 | @code{GL_POLYGON_TOKEN}, @code{GL_BITMAP_TOKEN}, | |
6992 | @code{GL_DRAW_PIXEL_TOKEN}, @code{GL_COPY_PIXEL_TOKEN} and | |
6993 | @code{GL_PASS_THROUGH_TOKEN} are symbolic floating-point constants. | |
6994 | @code{GL_LINE_RESET_TOKEN} is returned whenever the line stipple pattern | |
c7b31271 | 6995 | is reset. The data returned as a vertex depends on the feedback |
8925f36f AW |
6996 | @var{type}. |
6997 | ||
6998 | The following table gives the correspondence between @var{type} and the | |
c7b31271 | 6999 | number of values per vertex. @var{k} is 1 in color index mode and 4 in |
8925f36f AW |
7000 | RGBA mode. |
7001 | ||
7002 | ||
7003 | ||
7004 | @table @asis | |
7005 | @item @strong{Type} | |
7006 | @strong{Coordinates}, @strong{Color}, @strong{Texture}, @strong{Total | |
7007 | Number of Values} | |
7008 | ||
7009 | @item @code{GL_2D} | |
7010 | @var{x}, @var{y}, , , 2 | |
7011 | ||
7012 | @item @code{GL_3D} | |
7013 | @var{x}, @var{y}, @var{z}, , , 3 | |
7014 | ||
7015 | @item @code{GL_3D_COLOR} | |
3c9b6116 | 7016 | @var{x}, @var{y}, @var{z}, @r{@var{k}}, , @r{3+@var{k}} |
8925f36f AW |
7017 | |
7018 | @item @code{GL_3D_COLOR_TEXTURE} | |
3c9b6116 | 7019 | @var{x}, @var{y}, @var{z}, @r{@var{k}}, 4 , @r{7+@var{k}} |
8925f36f AW |
7020 | |
7021 | @item @code{GL_4D_COLOR_TEXTURE} | |
3c9b6116 | 7022 | @var{x}, @var{y}, @var{z}, @var{w}, @r{@var{k}}, 4 , @r{8+@var{k}} |
8925f36f AW |
7023 | |
7024 | @end table | |
7025 | ||
7026 | Feedback vertex coordinates are in window coordinates, except @var{w}, | |
c7b31271 DH |
7027 | which is in clip coordinates. Feedback colors are lighted, if lighting |
7028 | is enabled. Feedback texture coordinates are generated, if texture | |
7029 | coordinate generation is enabled. They are always transformed by the | |
8925f36f AW |
7030 | texture matrix. |
7031 | ||
8925f36f AW |
7032 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted |
7033 | value. | |
7034 | ||
7035 | @code{GL_INVALID_VALUE} is generated if @var{size} is negative. | |
7036 | ||
7037 | @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is | |
7038 | called while the render mode is @code{GL_FEEDBACK}, or if | |
7039 | @code{glRenderMode} is called with argument @code{GL_FEEDBACK} before | |
7040 | @code{glFeedbackBuffer} is called at least once. | |
7041 | ||
7042 | @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is | |
7043 | executed between the execution of @code{glBegin} and the corresponding | |
7044 | execution of @code{glEnd}. | |
7045 | ||
bb894c9d | 7046 | @end deftypefun |
8925f36f | 7047 | |
bb894c9d | 7048 | @deftypefun void glFinish |
3c9b6116 AW |
7049 | Block until all GL execution is complete. |
7050 | ||
8925f36f | 7051 | @code{glFinish} does not return until the effects of all previously |
c7b31271 | 7052 | called GL commands are complete. Such effects include all changes to GL |
8925f36f AW |
7053 | state, all changes to connection state, and all changes to the frame |
7054 | buffer contents. | |
7055 | ||
8925f36f AW |
7056 | @code{GL_INVALID_OPERATION} is generated if @code{glFinish} is executed |
7057 | between the execution of @code{glBegin} and the corresponding execution | |
7058 | of @code{glEnd}. | |
7059 | ||
bb894c9d | 7060 | @end deftypefun |
8925f36f | 7061 | |
bb894c9d | 7062 | @deftypefun void glFlush |
3c9b6116 AW |
7063 | Force execution of GL commands in finite time. |
7064 | ||
8925f36f AW |
7065 | Different GL implementations buffer commands in several different |
7066 | locations, including network buffers and the graphics accelerator | |
c7b31271 | 7067 | itself. @code{glFlush} empties all of these buffers, causing all issued |
8925f36f | 7068 | commands to be executed as quickly as they are accepted by the actual |
c7b31271 | 7069 | rendering engine. Though this execution may not be completed in any |
8925f36f AW |
7070 | particular time period, it does complete in finite time. |
7071 | ||
7072 | Because any GL program might be executed over a network, or on an | |
7073 | accelerator that buffers commands, all programs should call | |
7074 | @code{glFlush} whenever they count on having all of their previously | |
c7b31271 | 7075 | issued commands completed. For example, call @code{glFlush} before |
8925f36f AW |
7076 | waiting for user input that depends on the generated image. |
7077 | ||
8925f36f AW |
7078 | @code{GL_INVALID_OPERATION} is generated if @code{glFlush} is executed |
7079 | between the execution of @code{glBegin} and the corresponding execution | |
7080 | of @code{glEnd}. | |
7081 | ||
bb894c9d | 7082 | @end deftypefun |
8925f36f | 7083 | |
bb894c9d | 7084 | @deftypefun void glFogCoordPointer type stride pointer |
3c9b6116 AW |
7085 | Define an array of fog coordinates. |
7086 | ||
8925f36f AW |
7087 | @table @asis |
7088 | @item @var{type} | |
c7b31271 DH |
7089 | Specifies the data type of each fog coordinate. Symbolic constants |
7090 | @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is | |
8925f36f AW |
7091 | @code{GL_FLOAT}. |
7092 | ||
7093 | @item @var{stride} | |
c7b31271 | 7094 | Specifies the byte offset between consecutive fog coordinates. If |
8925f36f | 7095 | @var{stride} is 0, the array elements are understood to be tightly |
c7b31271 | 7096 | packed. The initial value is 0. |
8925f36f AW |
7097 | |
7098 | @item @var{pointer} | |
7099 | Specifies a pointer to the first coordinate of the first fog coordinate | |
c7b31271 | 7100 | in the array. The initial value is 0. |
8925f36f AW |
7101 | |
7102 | @end table | |
7103 | ||
8925f36f | 7104 | @code{glFogCoordPointer} specifies the location and data format of an |
c7b31271 DH |
7105 | array of fog coordinates to use when rendering. @var{type} specifies |
7106 | the data type of each fog coordinate, and @var{stride} specifies the | |
7107 | byte stride from one fog coordinate to the next, allowing vertices and | |
8925f36f AW |
7108 | attributes to be packed into a single array or stored in separate |
7109 | arrays. | |
7110 | ||
7111 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
7112 | target (see @code{glBindBuffer}) while a fog coordinate array is | |
7113 | specified, @var{pointer} is treated as a byte offset into the buffer | |
c7b31271 | 7114 | object's data store. Also, the buffer object binding |
8925f36f AW |
7115 | (@code{GL_ARRAY_BUFFER_BINDING}) is saved as fog coordinate vertex array |
7116 | client-side state (@code{GL_FOG_COORD_ARRAY_BUFFER_BINDING}). | |
7117 | ||
7118 | When a fog coordinate array is specified, @var{type}, @var{stride}, and | |
7119 | @var{pointer} are saved as client-side state, in addition to the current | |
7120 | vertex array buffer object binding. | |
7121 | ||
7122 | To enable and disable the fog coordinate array, call | |
7123 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
c7b31271 DH |
7124 | argument @code{GL_FOG_COORD_ARRAY}. If enabled, the fog coordinate |
7125 | array is used when @code{glDrawArrays}, @code{glMultiDrawArrays}, | |
8925f36f AW |
7126 | @code{glDrawElements}, @code{glMultiDrawElements}, |
7127 | @code{glDrawRangeElements}, or @code{glArrayElement} is called. | |
7128 | ||
8925f36f AW |
7129 | @code{GL_INVALID_ENUM} is generated if @var{type} is not either |
7130 | @code{GL_FLOAT} or @code{GL_DOUBLE}. | |
7131 | ||
7132 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
7133 | ||
bb894c9d | 7134 | @end deftypefun |
8925f36f | 7135 | |
d172eed9 AW |
7136 | @deftypefun void glFogCoordd coord |
7137 | @deftypefunx void glFogCoordf coord | |
7138 | @deftypefunx void glFogCoorddv coord | |
7139 | @deftypefunx void glFogCoordfv coord | |
3c9b6116 AW |
7140 | Set the current fog coordinates. |
7141 | ||
8925f36f AW |
7142 | @table @asis |
7143 | @item @var{coord} | |
7144 | Specify the fog distance. | |
7145 | ||
7146 | @end table | |
7147 | ||
8925f36f | 7148 | @code{glFogCoord} specifies the fog coordinate that is associated with |
c7b31271 | 7149 | each vertex and the current raster position. The value specified is |
8925f36f AW |
7150 | interpolated and used in computing the fog color (see @code{glFog}). |
7151 | ||
bb894c9d | 7152 | @end deftypefun |
8925f36f | 7153 | |
bb894c9d AW |
7154 | @deftypefun void glFogf pname param |
7155 | @deftypefunx void glFogi pname param | |
d172eed9 AW |
7156 | @deftypefunx void glFogfv pname params |
7157 | @deftypefunx void glFogiv pname params | |
3c9b6116 AW |
7158 | Specify fog parameters. |
7159 | ||
8925f36f AW |
7160 | @table @asis |
7161 | @item @var{pname} | |
c7b31271 | 7162 | Specifies a single-valued fog parameter. @code{GL_FOG_MODE}, |
8925f36f AW |
7163 | @code{GL_FOG_DENSITY}, @code{GL_FOG_START}, @code{GL_FOG_END}, |
7164 | @code{GL_FOG_INDEX}, and @code{GL_FOG_COORD_SRC} are accepted. | |
7165 | ||
7166 | @item @var{param} | |
7167 | Specifies the value that @var{pname} will be set to. | |
7168 | ||
7169 | @end table | |
7170 | ||
c7b31271 DH |
7171 | Fog is initially disabled. While enabled, fog affects rasterized |
7172 | geometry, bitmaps, and pixel blocks, but not buffer clear operations. To | |
8925f36f AW |
7173 | enable and disable fog, call @code{glEnable} and @code{glDisable} with |
7174 | argument @code{GL_FOG}. | |
7175 | ||
7176 | @code{glFog} assigns the value or values in @var{params} to the fog | |
c7b31271 | 7177 | parameter specified by @var{pname}. The following values are accepted |
8925f36f AW |
7178 | for @var{pname}: |
7179 | ||
7180 | @table @asis | |
7181 | @item @code{GL_FOG_MODE} | |
7182 | @var{params} is a single integer or floating-point value that specifies | |
3c9b6116 | 7183 | the equation to be used to compute the fog blend factor, @r{@var{f}}. |
8925f36f | 7184 | Three symbolic constants are accepted: @code{GL_LINEAR}, @code{GL_EXP}, |
c7b31271 DH |
7185 | and @code{GL_EXP2}. The equations corresponding to these symbolic |
7186 | constants are defined below. The initial fog mode is @code{GL_EXP}. | |
8925f36f AW |
7187 | |
7188 | @item @code{GL_FOG_DENSITY} | |
7189 | @var{params} is a single integer or floating-point value that specifies | |
3c9b6116 | 7190 | @r{@var{density}}, the fog density used in both exponential fog |
c7b31271 | 7191 | equations. Only nonnegative densities are accepted. The initial fog |
8925f36f AW |
7192 | density is 1. |
7193 | ||
7194 | @item @code{GL_FOG_START} | |
7195 | @var{params} is a single integer or floating-point value that specifies | |
c7b31271 | 7196 | @r{@var{start}}, the near distance used in the linear fog equation. The |
3c9b6116 | 7197 | initial near distance is 0. |
8925f36f AW |
7198 | |
7199 | @item @code{GL_FOG_END} | |
7200 | @var{params} is a single integer or floating-point value that specifies | |
c7b31271 | 7201 | @r{@var{end}}, the far distance used in the linear fog equation. The |
8925f36f AW |
7202 | initial far distance is 1. |
7203 | ||
7204 | @item @code{GL_FOG_INDEX} | |
7205 | @var{params} is a single integer or floating-point value that specifies | |
c7b31271 | 7206 | @r{@var{i}_@var{f}}, the fog color index. The initial fog index is 0. |
8925f36f AW |
7207 | |
7208 | @item @code{GL_FOG_COLOR} | |
7209 | @var{params} contains four integer or floating-point values that specify | |
c7b31271 | 7210 | @r{@var{C}_@var{f}}, the fog color. Integer values are mapped linearly |
3c9b6116 | 7211 | such that the most positive representable value maps to 1.0, and the |
c7b31271 DH |
7212 | most negative representable value maps to @r{-1.0}. Floating-point |
7213 | values are mapped directly. After conversion, all color components are | |
7214 | clamped to the range @r{[0,1]}. The initial fog color is (0, 0, 0, 0). | |
8925f36f AW |
7215 | |
7216 | @item @code{GL_FOG_COORD_SRC} | |
7217 | @var{params} contains either of the following symbolic constants: | |
c7b31271 | 7218 | @code{GL_FOG_COORD} or @code{GL_FRAGMENT_DEPTH}. @code{GL_FOG_COORD} |
8925f36f | 7219 | specifies that the current fog coordinate should be used as distance |
c7b31271 | 7220 | value in the fog color computation. @code{GL_FRAGMENT_DEPTH} specifies |
8925f36f AW |
7221 | that the current fragment depth should be used as distance value in the |
7222 | fog computation. | |
7223 | ||
7224 | @end table | |
7225 | ||
7226 | Fog blends a fog color with each rasterized pixel fragment's | |
c7b31271 | 7227 | post-texturing color using a blending factor @r{@var{f}}. Factor |
3c9b6116 AW |
7228 | @r{@var{f}} is computed in one of three ways, depending on the fog mode. |
7229 | Let @r{@var{c}} be either the distance in eye coordinate from the origin | |
7230 | (in the case that the @code{GL_FOG_COORD_SRC} is | |
8925f36f | 7231 | @code{GL_FRAGMENT_DEPTH}) or the current fog coordinate (in the case |
c7b31271 | 7232 | that @code{GL_FOG_COORD_SRC} is @code{GL_FOG_COORD}). The equation for |
8925f36f | 7233 | @code{GL_LINEAR} fog is |
3c9b6116 | 7234 | @r{@var{f}=@var{end}-@var{c},/@var{end}-@var{start},} |
8925f36f AW |
7235 | |
7236 | The equation for @code{GL_EXP} fog is | |
3c9b6116 | 7237 | @r{@var{f}=@var{e}^-(@var{density}·@var{c},),} |
8925f36f AW |
7238 | |
7239 | The equation for @code{GL_EXP2} fog is | |
3c9b6116 | 7240 | @r{@var{f}=@var{e}^-(@var{density}·@var{c},),^2} |
8925f36f | 7241 | |
3c9b6116 | 7242 | Regardless of the fog mode, @r{@var{f}} is clamped to the range |
c7b31271 | 7243 | @r{[0,1]} after it is computed. Then, if the GL is in RGBA color mode, |
3c9b6116 AW |
7244 | the fragment's red, green, and blue colors, represented by |
7245 | @r{@var{C}_@var{r}}, are replaced by | |
8925f36f | 7246 | |
3c9b6116 | 7247 | @r{@var{C}_@var{r},^″=@var{f}×@var{C}_@var{r}+(1-@var{f},)×@var{C}_@var{f}} |
8925f36f AW |
7248 | |
7249 | Fog does not affect a fragment's alpha component. | |
7250 | ||
3c9b6116 AW |
7251 | In color index mode, the fragment's color index @r{@var{i}_@var{r}} is |
7252 | replaced by | |
8925f36f | 7253 | |
3c9b6116 | 7254 | @r{@var{i}_@var{r},^″=@var{i}_@var{r}+(1-@var{f},)×@var{i}_@var{f}} |
8925f36f AW |
7255 | |
7256 | ||
7257 | ||
8925f36f AW |
7258 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted |
7259 | value, or if @var{pname} is @code{GL_FOG_MODE} and @var{params} is not | |
7260 | an accepted value. | |
7261 | ||
7262 | @code{GL_INVALID_VALUE} is generated if @var{pname} is | |
7263 | @code{GL_FOG_DENSITY} and @var{params} is negative. | |
7264 | ||
7265 | @code{GL_INVALID_OPERATION} is generated if @code{glFog} 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 glFrontFace mode |
3c9b6116 AW |
7272 | Define front- and back-facing polygons. |
7273 | ||
8925f36f AW |
7274 | @table @asis |
7275 | @item @var{mode} | |
c7b31271 DH |
7276 | Specifies the orientation of front-facing polygons. @code{GL_CW} and |
7277 | @code{GL_CCW} are accepted. The initial value is @code{GL_CCW}. | |
8925f36f AW |
7278 | |
7279 | @end table | |
7280 | ||
8925f36f | 7281 | In a scene composed entirely of opaque closed surfaces, back-facing |
c7b31271 DH |
7282 | polygons are never visible. Eliminating these invisible polygons has |
7283 | the obvious benefit of speeding up the rendering of the image. To | |
7284 | enable and disable elimination of back-facing polygons, call | |
7285 | @code{glEnable} and @code{glDisable} with argument @code{GL_CULL_FACE}. | |
8925f36f AW |
7286 | |
7287 | The projection of a polygon to window coordinates is said to have | |
7288 | clockwise winding if an imaginary object following the path from its | |
7289 | first vertex, its second vertex, and so on, to its last vertex, and | |
7290 | finally back to its first vertex, moves in a clockwise direction about | |
c7b31271 | 7291 | the interior of the polygon. The polygon's winding is said to be |
8925f36f AW |
7292 | counterclockwise if the imaginary object following the same path moves |
7293 | in a counterclockwise direction about the interior of the polygon. | |
7294 | @code{glFrontFace} specifies whether polygons with clockwise winding in | |
7295 | window coordinates, or counterclockwise winding in window coordinates, | |
c7b31271 | 7296 | are taken to be front-facing. Passing @code{GL_CCW} to @var{mode} |
8925f36f | 7297 | selects counterclockwise polygons as front-facing; @code{GL_CW} selects |
c7b31271 | 7298 | clockwise polygons as front-facing. By default, counterclockwise |
8925f36f AW |
7299 | polygons are taken to be front-facing. |
7300 | ||
8925f36f AW |
7301 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
7302 | value. | |
7303 | ||
7304 | @code{GL_INVALID_OPERATION} is generated if @code{glFrontFace} is | |
7305 | executed between the execution of @code{glBegin} and the corresponding | |
7306 | execution of @code{glEnd}. | |
7307 | ||
bb894c9d | 7308 | @end deftypefun |
8925f36f | 7309 | |
bb894c9d | 7310 | @deftypefun void glFrustum left right bottom top nearVal farVal |
3c9b6116 AW |
7311 | Multiply the current matrix by a perspective matrix. |
7312 | ||
8925f36f AW |
7313 | @table @asis |
7314 | @item @var{left} | |
7315 | @itemx @var{right} | |
7316 | Specify the coordinates for the left and right vertical clipping planes. | |
7317 | ||
7318 | @item @var{bottom} | |
7319 | @itemx @var{top} | |
7320 | Specify the coordinates for the bottom and top horizontal clipping | |
7321 | planes. | |
7322 | ||
7323 | @item @var{nearVal} | |
7324 | @itemx @var{farVal} | |
c7b31271 | 7325 | Specify the distances to the near and far depth clipping planes. Both |
8925f36f AW |
7326 | distances must be positive. |
7327 | ||
7328 | @end table | |
7329 | ||
8925f36f | 7330 | @code{glFrustum} describes a perspective matrix that produces a |
c7b31271 | 7331 | perspective projection. The current matrix (see @code{glMatrixMode}) is |
8925f36f AW |
7332 | multiplied by this matrix and the result replaces the current matrix, as |
7333 | if @code{glMultMatrix} were called with the following matrix as its | |
7334 | argument: | |
7335 | ||
7336 | ||
7337 | ||
3c9b6116 | 7338 | @r{[(2@var{nearVal},/@var{right}-@var{left},, 0 @var{A} 0), (0 |
8925f36f AW |
7339 | 2@var{nearVal},/@var{top}-@var{bottom},, @var{B} 0), (0 0 @var{C} |
7340 | @var{D}), (0 0 -1 0),]} | |
7341 | ||
3c9b6116 | 7342 | @r{@var{A}=@var{right}+@var{left},/@var{right}-@var{left},} |
8925f36f | 7343 | |
3c9b6116 | 7344 | @r{@var{B}=@var{top}+@var{bottom},/@var{top}-@var{bottom},} |
8925f36f | 7345 | |
3c9b6116 | 7346 | @r{@var{C}=-@var{farVal}+@var{nearVal},/@var{farVal}-@var{nearVal},,} |
8925f36f | 7347 | |
3c9b6116 | 7348 | @r{@var{D}=-2@var{farVal}@var{nearVal},/@var{farVal}-@var{nearVal},,} |
8925f36f AW |
7349 | |
7350 | ||
7351 | ||
7352 | Typically, the matrix mode is @code{GL_PROJECTION}, and | |
3c9b6116 AW |
7353 | @r{(@var{left},@var{bottom}-@var{nearVal})} and |
7354 | @r{(@var{right},@var{top}-@var{nearVal})} specify the points on the near | |
7355 | clipping plane that are mapped to the lower left and upper right corners | |
7356 | of the window, assuming that the eye is located at (0, 0, 0). | |
c7b31271 | 7357 | @r{-@var{farVal}} specifies the location of the far clipping plane. Both |
3c9b6116 | 7358 | @var{nearVal} and @var{farVal} must be positive. |
8925f36f AW |
7359 | |
7360 | Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the | |
7361 | current matrix stack. | |
7362 | ||
8925f36f AW |
7363 | @code{GL_INVALID_VALUE} is generated if @var{nearVal} or @var{farVal} is |
7364 | not positive, or if @var{left} = @var{right}, or @var{bottom} = | |
7365 | @var{top}, or @var{near} = @var{far}. | |
7366 | ||
7367 | @code{GL_INVALID_OPERATION} is generated if @code{glFrustum} is executed | |
7368 | between the execution of @code{glBegin} and the corresponding execution | |
7369 | of @code{glEnd}. | |
7370 | ||
bb894c9d | 7371 | @end deftypefun |
8925f36f | 7372 | |
bb894c9d | 7373 | @deftypefun void glGenBuffers n buffers |
3c9b6116 AW |
7374 | Generate buffer object names. |
7375 | ||
8925f36f AW |
7376 | @table @asis |
7377 | @item @var{n} | |
7378 | Specifies the number of buffer object names to be generated. | |
7379 | ||
7380 | @item @var{buffers} | |
7381 | Specifies an array in which the generated buffer object names are | |
7382 | stored. | |
7383 | ||
7384 | @end table | |
7385 | ||
8925f36f | 7386 | @code{glGenBuffers} returns @var{n} buffer object names in |
c7b31271 | 7387 | @var{buffers}. There is no guarantee that the names form a contiguous |
8925f36f AW |
7388 | set of integers; however, it is guaranteed that none of the returned |
7389 | names was in use immediately before the call to @code{glGenBuffers}. | |
7390 | ||
7391 | Buffer object names returned by a call to @code{glGenBuffers} are not | |
7392 | returned by subsequent calls, unless they are first deleted with | |
7393 | @code{glDeleteBuffers}. | |
7394 | ||
7395 | No buffer objects are associated with the returned buffer object names | |
7396 | until they are first bound by calling @code{glBindBuffer}. | |
7397 | ||
8925f36f AW |
7398 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
7399 | ||
7400 | @code{GL_INVALID_OPERATION} is generated if @code{glGenBuffers} is | |
7401 | executed between the execution of @code{glBegin} and the corresponding | |
7402 | execution of @code{glEnd}. | |
7403 | ||
bb894c9d | 7404 | @end deftypefun |
8925f36f | 7405 | |
bb894c9d | 7406 | @deftypefun GLuint glGenLists range |
3c9b6116 AW |
7407 | Generate a contiguous set of empty display lists. |
7408 | ||
8925f36f AW |
7409 | @table @asis |
7410 | @item @var{range} | |
7411 | Specifies the number of contiguous empty display lists to be generated. | |
7412 | ||
7413 | @end table | |
7414 | ||
c7b31271 | 7415 | @code{glGenLists} has one argument, @var{range}. It returns an integer |
8925f36f | 7416 | @var{n} such that @var{range} contiguous empty display lists, named |
3c9b6116 | 7417 | @r{@var{n}}, @r{@var{n}+1}, @r{@var{...}}, @r{@var{n}+@var{range}-1}, |
c7b31271 | 7418 | are created. If @var{range} is 0, if there is no group of @var{range} |
3c9b6116 AW |
7419 | contiguous names available, or if any error is generated, no display |
7420 | lists are generated, and 0 is returned. | |
8925f36f | 7421 | |
8925f36f AW |
7422 | @code{GL_INVALID_VALUE} is generated if @var{range} is negative. |
7423 | ||
7424 | @code{GL_INVALID_OPERATION} is generated if @code{glGenLists} is | |
7425 | executed between the execution of @code{glBegin} and the corresponding | |
7426 | execution of @code{glEnd}. | |
7427 | ||
bb894c9d | 7428 | @end deftypefun |
8925f36f | 7429 | |
bb894c9d | 7430 | @deftypefun void glGenQueries n ids |
3c9b6116 AW |
7431 | Generate query object names. |
7432 | ||
8925f36f AW |
7433 | @table @asis |
7434 | @item @var{n} | |
7435 | Specifies the number of query object names to be generated. | |
7436 | ||
7437 | @item @var{ids} | |
7438 | Specifies an array in which the generated query object names are stored. | |
7439 | ||
7440 | @end table | |
7441 | ||
8925f36f AW |
7442 | @code{glGenQueries} returns @var{n} query object names in @var{ids}. |
7443 | There is no guarantee that the names form a contiguous set of integers; | |
7444 | however, it is guaranteed that none of the returned names was in use | |
7445 | immediately before the call to @code{glGenQueries}. | |
7446 | ||
7447 | Query object names returned by a call to @code{glGenQueries} are not | |
7448 | returned by subsequent calls, unless they are first deleted with | |
7449 | @code{glDeleteQueries}. | |
7450 | ||
7451 | No query objects are associated with the returned query object names | |
7452 | until they are first used by calling @code{glBeginQuery}. | |
7453 | ||
8925f36f AW |
7454 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
7455 | ||
7456 | @code{GL_INVALID_OPERATION} is generated if @code{glGenQueries} is | |
7457 | executed between the execution of @code{glBegin} and the corresponding | |
7458 | execution of @code{glEnd}. | |
7459 | ||
bb894c9d | 7460 | @end deftypefun |
8925f36f | 7461 | |
bb894c9d | 7462 | @deftypefun void glGenTextures n textures |
3c9b6116 AW |
7463 | Generate texture names. |
7464 | ||
8925f36f AW |
7465 | @table @asis |
7466 | @item @var{n} | |
7467 | Specifies the number of texture names to be generated. | |
7468 | ||
7469 | @item @var{textures} | |
7470 | Specifies an array in which the generated texture names are stored. | |
7471 | ||
7472 | @end table | |
7473 | ||
8925f36f AW |
7474 | @code{glGenTextures} returns @var{n} texture names in @var{textures}. |
7475 | There is no guarantee that the names form a contiguous set of integers; | |
7476 | however, it is guaranteed that none of the returned names was in use | |
7477 | immediately before the call to @code{glGenTextures}. | |
7478 | ||
7479 | The generated textures have no dimensionality; they assume the | |
7480 | dimensionality of the texture target to which they are first bound (see | |
7481 | @code{glBindTexture}). | |
7482 | ||
7483 | Texture names returned by a call to @code{glGenTextures} are not | |
7484 | returned by subsequent calls, unless they are first deleted with | |
7485 | @code{glDeleteTextures}. | |
7486 | ||
8925f36f AW |
7487 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
7488 | ||
7489 | @code{GL_INVALID_OPERATION} is generated if @code{glGenTextures} is | |
7490 | executed between the execution of @code{glBegin} and the corresponding | |
7491 | execution of @code{glEnd}. | |
7492 | ||
bb894c9d | 7493 | @end deftypefun |
8925f36f | 7494 | |
bb894c9d | 7495 | @deftypefun void glGetActiveAttrib program index bufSize length size type name |
3c9b6116 AW |
7496 | Returns information about an active attribute variable for the specified |
7497 | program object. | |
7498 | ||
8925f36f AW |
7499 | @table @asis |
7500 | @item @var{program} | |
7501 | Specifies the program object to be queried. | |
7502 | ||
7503 | @item @var{index} | |
7504 | Specifies the index of the attribute variable to be queried. | |
7505 | ||
7506 | @item @var{bufSize} | |
7507 | Specifies the maximum number of characters OpenGL is allowed to write in | |
7508 | the character buffer indicated by @var{name}. | |
7509 | ||
7510 | @item @var{length} | |
7511 | Returns the number of characters actually written by OpenGL in the | |
7512 | string indicated by @var{name} (excluding the null terminator) if a | |
7513 | value other than @code{NULL} is passed. | |
7514 | ||
7515 | @item @var{size} | |
7516 | Returns the size of the attribute variable. | |
7517 | ||
7518 | @item @var{type} | |
7519 | Returns the data type of the attribute variable. | |
7520 | ||
7521 | @item @var{name} | |
7522 | Returns a null terminated string containing the name of the attribute | |
7523 | variable. | |
7524 | ||
7525 | @end table | |
7526 | ||
8925f36f | 7527 | @code{glGetActiveAttrib} returns information about an active attribute |
c7b31271 DH |
7528 | variable in the program object specified by @var{program}. The number |
7529 | of active attributes can be obtained by calling @code{glGetProgram} with | |
7530 | the value @code{GL_ACTIVE_ATTRIBUTES}. A value of 0 for @var{index} | |
7531 | selects the first active attribute variable. Permissible values for | |
8925f36f AW |
7532 | @var{index} range from 0 to the number of active attribute variables |
7533 | minus 1. | |
7534 | ||
7535 | A vertex shader may use either built-in attribute variables, | |
c7b31271 | 7536 | user-defined attribute variables, or both. Built-in attribute variables |
8925f36f AW |
7537 | have a prefix of "gl_" and reference conventional OpenGL vertex |
7538 | attribtes (e.g., @var{gl_Vertex}, @var{gl_Normal}, etc., see the OpenGL | |
7539 | Shading Language specification for a complete list.) User-defined | |
7540 | attribute variables have arbitrary names and obtain their values through | |
c7b31271 | 7541 | numbered generic vertex attributes. An attribute variable (either |
8925f36f AW |
7542 | built-in or user-defined) is considered active if it is determined |
7543 | during the link operation that it may be accessed during program | |
c7b31271 | 7544 | execution. Therefore, @var{program} should have previously been the |
8925f36f AW |
7545 | target of a call to @code{glLinkProgram}, but it is not necessary for it |
7546 | to have been linked successfully. | |
7547 | ||
7548 | The size of the character buffer required to store the longest attribute | |
7549 | variable name in @var{program} can be obtained by calling | |
7550 | @code{glGetProgram} with the value | |
c7b31271 | 7551 | @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH}. This value should be used to |
8925f36f | 7552 | allocate a buffer of sufficient size to store the returned attribute |
c7b31271 | 7553 | name. The size of this character buffer is passed in @var{bufSize}, and |
8925f36f AW |
7554 | a pointer to this character buffer is passed in @var{name}. |
7555 | ||
7556 | @code{glGetActiveAttrib} returns the name of the attribute variable | |
7557 | indicated by @var{index}, storing it in the character buffer specified | |
c7b31271 | 7558 | by @var{name}. The string returned will be null terminated. The actual |
8925f36f AW |
7559 | number of characters written into this buffer is returned in |
7560 | @var{length}, and this count does not include the null termination | |
c7b31271 DH |
7561 | character. If the length of the returned string is not required, a |
7562 | value of @code{NULL} can be passed in the @var{length} argument. | |
8925f36f AW |
7563 | |
7564 | The @var{type} argument will return a pointer to the attribute | |
c7b31271 | 7565 | variable's data type. The symbolic constants @code{GL_FLOAT}, |
8925f36f AW |
7566 | @code{GL_FLOAT_VEC2}, @code{GL_FLOAT_VEC3}, @code{GL_FLOAT_VEC4}, |
7567 | @code{GL_FLOAT_MAT2}, @code{GL_FLOAT_MAT3}, @code{GL_FLOAT_MAT4}, | |
7568 | @code{GL_FLOAT_MAT2x3}, @code{GL_FLOAT_MAT2x4}, @code{GL_FLOAT_MAT3x2}, | |
7569 | @code{GL_FLOAT_MAT3x4}, @code{GL_FLOAT_MAT4x2}, or | |
c7b31271 | 7570 | @code{GL_FLOAT_MAT4x3} may be returned. The @var{size} argument will |
8925f36f AW |
7571 | return the size of the attribute, in units of the type returned in |
7572 | @var{type}. | |
7573 | ||
7574 | The list of active attribute variables may include both built-in | |
7575 | attribute variables (which begin with the prefix "gl_") as well as | |
7576 | user-defined attribute variable names. | |
7577 | ||
7578 | This function will return as much information as it can about the | |
c7b31271 DH |
7579 | specified active attribute variable. If no information is available, |
7580 | @var{length} will be 0, and @var{name} will be an empty string. This | |
8925f36f | 7581 | situation could occur if this function is called after a link operation |
c7b31271 | 7582 | that failed. If an error occurs, the return values @var{length}, |
8925f36f AW |
7583 | @var{size}, @var{type}, and @var{name} will be unmodified. |
7584 | ||
8925f36f AW |
7585 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
7586 | generated by OpenGL. | |
7587 | ||
7588 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
7589 | program object. | |
7590 | ||
7591 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or | |
7592 | equal to the number of active attribute variables in @var{program}. | |
7593 | ||
7594 | @code{GL_INVALID_OPERATION} is generated if @code{glGetActiveAttrib} is | |
7595 | executed between the execution of @code{glBegin} and the corresponding | |
7596 | execution of @code{glEnd}. | |
7597 | ||
7598 | @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0. | |
7599 | ||
bb894c9d | 7600 | @end deftypefun |
8925f36f | 7601 | |
bb894c9d | 7602 | @deftypefun void glGetActiveUniform program index bufSize length size type name |
3c9b6116 AW |
7603 | Returns information about an active uniform variable for the specified |
7604 | program object. | |
7605 | ||
8925f36f AW |
7606 | @table @asis |
7607 | @item @var{program} | |
7608 | Specifies the program object to be queried. | |
7609 | ||
7610 | @item @var{index} | |
7611 | Specifies the index of the uniform variable to be queried. | |
7612 | ||
7613 | @item @var{bufSize} | |
7614 | Specifies the maximum number of characters OpenGL is allowed to write in | |
7615 | the character buffer indicated by @var{name}. | |
7616 | ||
7617 | @item @var{length} | |
7618 | Returns the number of characters actually written by OpenGL in the | |
7619 | string indicated by @var{name} (excluding the null terminator) if a | |
7620 | value other than @code{NULL} is passed. | |
7621 | ||
7622 | @item @var{size} | |
7623 | Returns the size of the uniform variable. | |
7624 | ||
7625 | @item @var{type} | |
7626 | Returns the data type of the uniform variable. | |
7627 | ||
7628 | @item @var{name} | |
7629 | Returns a null terminated string containing the name of the uniform | |
7630 | variable. | |
7631 | ||
7632 | @end table | |
7633 | ||
8925f36f | 7634 | @code{glGetActiveUniform} returns information about an active uniform |
c7b31271 DH |
7635 | variable in the program object specified by @var{program}. The number |
7636 | of active uniform variables can be obtained by calling | |
7637 | @code{glGetProgram} with the value @code{GL_ACTIVE_UNIFORMS}. A value | |
7638 | of 0 for @var{index} selects the first active uniform variable. | |
7639 | Permissible values for @var{index} range from 0 to the number of active | |
7640 | uniform variables minus 1. | |
8925f36f AW |
7641 | |
7642 | Shaders may use either built-in uniform variables, user-defined uniform | |
c7b31271 | 7643 | variables, or both. Built-in uniform variables have a prefix of "gl_" |
8925f36f AW |
7644 | and reference existing OpenGL state or values derived from such state |
7645 | (e.g., @var{gl_Fog}, @var{gl_ModelViewMatrix}, etc., see the OpenGL | |
7646 | Shading Language specification for a complete list.) User-defined | |
7647 | uniform variables have arbitrary names and obtain their values from the | |
c7b31271 | 7648 | application through calls to @code{glUniform}. A uniform variable |
8925f36f AW |
7649 | (either built-in or user-defined) is considered active if it is |
7650 | determined during the link operation that it may be accessed during | |
c7b31271 | 7651 | program execution. Therefore, @var{program} should have previously been |
8925f36f AW |
7652 | the target of a call to @code{glLinkProgram}, but it is not necessary |
7653 | for it to have been linked successfully. | |
7654 | ||
7655 | The size of the character buffer required to store the longest uniform | |
7656 | variable name in @var{program} can be obtained by calling | |
7657 | @code{glGetProgram} with the value @code{GL_ACTIVE_UNIFORM_MAX_LENGTH}. | |
7658 | This value should be used to allocate a buffer of sufficient size to | |
c7b31271 | 7659 | store the returned uniform variable name. The size of this character |
8925f36f AW |
7660 | buffer is passed in @var{bufSize}, and a pointer to this character |
7661 | buffer is passed in @var{name.} | |
7662 | ||
7663 | @code{glGetActiveUniform} returns the name of the uniform variable | |
7664 | indicated by @var{index}, storing it in the character buffer specified | |
c7b31271 | 7665 | by @var{name}. The string returned will be null terminated. The actual |
8925f36f AW |
7666 | number of characters written into this buffer is returned in |
7667 | @var{length}, and this count does not include the null termination | |
c7b31271 DH |
7668 | character. If the length of the returned string is not required, a |
7669 | value of @code{NULL} can be passed in the @var{length} argument. | |
8925f36f AW |
7670 | |
7671 | The @var{type} argument will return a pointer to the uniform variable's | |
c7b31271 DH |
7672 | data type. The symbolic constants @code{GL_FLOAT}, |
7673 | @code{GL_FLOAT_VEC2}, @code{GL_FLOAT_VEC3}, @code{GL_FLOAT_VEC4}, | |
7674 | @code{GL_INT}, @code{GL_INT_VEC2}, @code{GL_INT_VEC3}, | |
7675 | @code{GL_INT_VEC4}, @code{GL_BOOL}, @code{GL_BOOL_VEC2}, | |
7676 | @code{GL_BOOL_VEC3}, @code{GL_BOOL_VEC4}, @code{GL_FLOAT_MAT2}, | |
7677 | @code{GL_FLOAT_MAT3}, @code{GL_FLOAT_MAT4}, @code{GL_FLOAT_MAT2x3}, | |
7678 | @code{GL_FLOAT_MAT2x4}, @code{GL_FLOAT_MAT3x2}, @code{GL_FLOAT_MAT3x4}, | |
7679 | @code{GL_FLOAT_MAT4x2}, @code{GL_FLOAT_MAT4x3}, @code{GL_SAMPLER_1D}, | |
7680 | @code{GL_SAMPLER_2D}, @code{GL_SAMPLER_3D}, @code{GL_SAMPLER_CUBE}, | |
8925f36f AW |
7681 | @code{GL_SAMPLER_1D_SHADOW}, or @code{GL_SAMPLER_2D_SHADOW} may be |
7682 | returned. | |
7683 | ||
7684 | If one or more elements of an array are active, the name of the array is | |
7685 | returned in @var{name}, the type is returned in @var{type}, and the | |
7686 | @var{size} parameter returns the highest array element index used, plus | |
c7b31271 | 7687 | one, as determined by the compiler and/or linker. Only one active |
8925f36f AW |
7688 | uniform variable will be reported for a uniform array. |
7689 | ||
7690 | Uniform variables that are declared as structures or arrays of | |
c7b31271 DH |
7691 | structures will not be returned directly by this function. Instead, |
7692 | each of these uniform variables will be reduced to its fundamental | |
7693 | components containing the "." and "[]" operators such that each of the | |
7694 | names is valid as an argument to @code{glGetUniformLocation}. Each of | |
7695 | these reduced uniform variables is counted as one active uniform | |
7696 | variable and is assigned an index. A valid name cannot be a structure, | |
7697 | an array of structures, or a subcomponent of a vector or matrix. | |
7698 | ||
7699 | The size of the uniform variable will be returned in @var{size}. Uniform | |
7700 | variables other than arrays will have a size of 1. Structures and | |
7701 | arrays of structures will be reduced as described earlier, such that | |
7702 | each of the names returned will be a data type in the earlier list. If | |
7703 | this reduction results in an array, the size returned will be as | |
7704 | described for uniform arrays; otherwise, the size returned will be 1. | |
8925f36f AW |
7705 | |
7706 | The list of active uniform variables may include both built-in uniform | |
7707 | variables (which begin with the prefix "gl_") as well as user-defined | |
7708 | uniform variable names. | |
7709 | ||
7710 | This function will return as much information as it can about the | |
c7b31271 DH |
7711 | specified active uniform variable. If no information is available, |
7712 | @var{length} will be 0, and @var{name} will be an empty string. This | |
8925f36f | 7713 | situation could occur if this function is called after a link operation |
c7b31271 | 7714 | that failed. If an error occurs, the return values @var{length}, |
8925f36f AW |
7715 | @var{size}, @var{type}, and @var{name} will be unmodified. |
7716 | ||
8925f36f AW |
7717 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
7718 | generated by OpenGL. | |
7719 | ||
7720 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
7721 | program object. | |
7722 | ||
7723 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or | |
7724 | equal to the number of active uniform variables in @var{program}. | |
7725 | ||
7726 | @code{GL_INVALID_OPERATION} is generated if @code{glGetActiveUniform} is | |
7727 | executed between the execution of @code{glBegin} and the corresponding | |
7728 | execution of @code{glEnd}. | |
7729 | ||
7730 | @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0. | |
7731 | ||
bb894c9d | 7732 | @end deftypefun |
8925f36f | 7733 | |
bb894c9d | 7734 | @deftypefun void glGetAttachedShaders program maxCount count shaders |
3c9b6116 AW |
7735 | Returns the handles of the shader objects attached to a program object. |
7736 | ||
8925f36f AW |
7737 | @table @asis |
7738 | @item @var{program} | |
7739 | Specifies the program object to be queried. | |
7740 | ||
7741 | @item @var{maxCount} | |
7742 | Specifies the size of the array for storing the returned object names. | |
7743 | ||
7744 | @item @var{count} | |
7745 | Returns the number of names actually returned in @var{objects}. | |
7746 | ||
7747 | @item @var{shaders} | |
7748 | Specifies an array that is used to return the names of attached shader | |
7749 | objects. | |
7750 | ||
7751 | @end table | |
7752 | ||
8925f36f | 7753 | @code{glGetAttachedShaders} returns the names of the shader objects |
c7b31271 DH |
7754 | attached to @var{program}. The names of shader objects that are |
7755 | attached to @var{program} will be returned in @var{shaders.} The actual | |
7756 | number of shader names written into @var{shaders} is returned in | |
7757 | @var{count.} If no shader objects are attached to @var{program}, | |
7758 | @var{count} is set to 0. The maximum number of shader names that may be | |
7759 | returned in @var{shaders} is specified by @var{maxCount}. | |
8925f36f AW |
7760 | |
7761 | If the number of names actually returned is not required (for instance, | |
7762 | if it has just been obtained by calling @code{glGetProgram}), a value of | |
c7b31271 DH |
7763 | @code{NULL} may be passed for count. If no shader objects are attached |
7764 | to @var{program}, a value of 0 will be returned in @var{count}. The | |
8925f36f AW |
7765 | actual number of attached shaders can be obtained by calling |
7766 | @code{glGetProgram} with the value @code{GL_ATTACHED_SHADERS}. | |
7767 | ||
8925f36f AW |
7768 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
7769 | generated by OpenGL. | |
7770 | ||
7771 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
7772 | program object. | |
7773 | ||
7774 | @code{GL_INVALID_VALUE} is generated if @var{maxCount} is less than 0. | |
7775 | ||
7776 | @code{GL_INVALID_OPERATION} is generated if @code{glGetAttachedShaders} | |
7777 | is executed between the execution of @code{glBegin} and the | |
7778 | corresponding execution of @code{glEnd}. | |
7779 | ||
bb894c9d | 7780 | @end deftypefun |
8925f36f | 7781 | |
bb894c9d | 7782 | @deftypefun GLint glGetAttribLocation program name |
3c9b6116 AW |
7783 | Returns the location of an attribute variable. |
7784 | ||
8925f36f AW |
7785 | @table @asis |
7786 | @item @var{program} | |
7787 | Specifies the program object to be queried. | |
7788 | ||
7789 | @item @var{name} | |
7790 | Points to a null terminated string containing the name of the attribute | |
7791 | variable whose location is to be queried. | |
7792 | ||
7793 | @end table | |
7794 | ||
8925f36f AW |
7795 | @code{glGetAttribLocation} queries the previously linked program object |
7796 | specified by @var{program} for the attribute variable specified by | |
7797 | @var{name} and returns the index of the generic vertex attribute that is | |
c7b31271 DH |
7798 | bound to that attribute variable. If @var{name} is a matrix attribute |
7799 | variable, the index of the first column of the matrix is returned. If | |
8925f36f AW |
7800 | the named attribute variable is not an active attribute in the specified |
7801 | program object or if @var{name} starts with the reserved prefix "gl_", a | |
7802 | value of -1 is returned. | |
7803 | ||
7804 | The association between an attribute variable name and a generic | |
7805 | attribute index can be specified at any time by calling | |
c7b31271 DH |
7806 | @code{glBindAttribLocation}. Attribute bindings do not go into effect |
7807 | until @code{glLinkProgram} is called. After a program object has been | |
8925f36f | 7808 | linked successfully, the index values for attribute variables remain |
c7b31271 | 7809 | fixed until the next link command occurs. The attribute values can only |
8925f36f AW |
7810 | be queried after a link if the link was successful. |
7811 | @code{glGetAttribLocation} returns the binding that actually went into | |
7812 | effect the last time @code{glLinkProgram} was called for the specified | |
c7b31271 | 7813 | program object. Attribute bindings that have been specified since the |
8925f36f AW |
7814 | last link operation are not returned by @code{glGetAttribLocation}. |
7815 | ||
8925f36f AW |
7816 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a value |
7817 | generated by OpenGL. | |
7818 | ||
7819 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
7820 | program object. | |
7821 | ||
7822 | @code{GL_INVALID_OPERATION} is generated if @var{program} has not been | |
7823 | successfully linked. | |
7824 | ||
7825 | @code{GL_INVALID_OPERATION} is generated if @code{glGetAttribLocation} | |
7826 | is executed between the execution of @code{glBegin} and the | |
7827 | corresponding execution of @code{glEnd}. | |
7828 | ||
bb894c9d | 7829 | @end deftypefun |
8925f36f | 7830 | |
b002944d AW |
7831 | @deftypefun void glGetBufferParameteriv target value data |
7832 | Return parameters of a buffer object. | |
7833 | ||
7834 | @table @asis | |
7835 | @item @var{target} | |
c7b31271 | 7836 | Specifies the target buffer object. The symbolic constant must be |
b002944d AW |
7837 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, |
7838 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
7839 | ||
7840 | @item @var{value} | |
c7b31271 | 7841 | Specifies the symbolic name of a buffer object parameter. Accepted |
b002944d AW |
7842 | values are @code{GL_BUFFER_ACCESS}, @code{GL_BUFFER_MAPPED}, |
7843 | @code{GL_BUFFER_SIZE}, or @code{GL_BUFFER_USAGE}. | |
7844 | ||
7845 | @item @var{data} | |
7846 | Returns the requested parameter. | |
7847 | ||
7848 | @end table | |
7849 | ||
7850 | @code{glGetBufferParameteriv} returns in @var{data} a selected parameter | |
7851 | of the buffer object specified by @var{target}. | |
7852 | ||
7853 | @var{value} names a specific buffer object parameter, as follows: | |
7854 | ||
7855 | @table @asis | |
7856 | @item @code{GL_BUFFER_ACCESS} | |
7857 | @var{params} returns the access policy set while mapping the buffer | |
c7b31271 | 7858 | object. The initial value is @code{GL_READ_WRITE}. |
b002944d AW |
7859 | |
7860 | @item @code{GL_BUFFER_MAPPED} | |
7861 | @var{params} returns a flag indicating whether the buffer object is | |
c7b31271 | 7862 | currently mapped. The initial value is @code{GL_FALSE}. |
b002944d AW |
7863 | |
7864 | @item @code{GL_BUFFER_SIZE} | |
7865 | @var{params} returns the size of the buffer object, measured in bytes. | |
7866 | The initial value is 0. | |
7867 | ||
7868 | @item @code{GL_BUFFER_USAGE} | |
c7b31271 | 7869 | @var{params} returns the buffer object's usage pattern. The initial |
b002944d AW |
7870 | value is @code{GL_STATIC_DRAW}. |
7871 | ||
7872 | @end table | |
7873 | ||
7874 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{value} is | |
7875 | not an accepted value. | |
7876 | ||
7877 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
7878 | name 0 is bound to @var{target}. | |
7879 | ||
7880 | @code{GL_INVALID_OPERATION} is generated if | |
7881 | @code{glGetBufferParameteriv} is executed between the execution of | |
7882 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
7883 | ||
7884 | @end deftypefun | |
7885 | ||
7886 | @deftypefun void glGetBufferPointerv target pname params | |
7887 | Return the pointer to a mapped buffer object's data store. | |
7888 | ||
7889 | @table @asis | |
7890 | @item @var{target} | |
c7b31271 | 7891 | Specifies the target buffer object. The symbolic constant must be |
b002944d AW |
7892 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, |
7893 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
7894 | ||
7895 | @item @var{pname} | |
c7b31271 | 7896 | Specifies the pointer to be returned. The symbolic constant must be |
b002944d AW |
7897 | @code{GL_BUFFER_MAP_POINTER}. |
7898 | ||
7899 | @item @var{params} | |
7900 | Returns the pointer value specified by @var{pname}. | |
7901 | ||
7902 | @end table | |
7903 | ||
c7b31271 DH |
7904 | @code{glGetBufferPointerv} returns pointer information. @var{pname} is |
7905 | a symbolic constant indicating the pointer to be returned, which must be | |
b002944d | 7906 | @code{GL_BUFFER_MAP_POINTER}, the pointer to which the buffer object's |
c7b31271 DH |
7907 | data store is mapped. If the data store is not currently mapped, |
7908 | @code{NULL} is returned. @var{params} is a pointer to a location in | |
b002944d AW |
7909 | which to place the returned pointer value. |
7910 | ||
7911 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
7912 | not an accepted value. | |
7913 | ||
7914 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
7915 | name 0 is bound to @var{target}. | |
7916 | ||
7917 | @code{GL_INVALID_OPERATION} is generated if @code{glGetBufferPointerv} | |
7918 | is executed between the execution of @code{glBegin} and the | |
7919 | corresponding execution of @code{glEnd}. | |
7920 | ||
7921 | @end deftypefun | |
7922 | ||
bb894c9d | 7923 | @deftypefun void glGetBufferSubData target offset size data |
3c9b6116 AW |
7924 | Returns a subset of a buffer object's data store. |
7925 | ||
8925f36f AW |
7926 | @table @asis |
7927 | @item @var{target} | |
c7b31271 | 7928 | Specifies the target buffer object. The symbolic constant must be |
8925f36f AW |
7929 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, |
7930 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
7931 | ||
7932 | @item @var{offset} | |
7933 | Specifies the offset into the buffer object's data store from which data | |
7934 | will be returned, measured in bytes. | |
7935 | ||
7936 | @item @var{size} | |
7937 | Specifies the size in bytes of the data store region being returned. | |
7938 | ||
7939 | @item @var{data} | |
7940 | Specifies a pointer to the location where buffer object data is | |
7941 | returned. | |
7942 | ||
7943 | @end table | |
7944 | ||
8925f36f | 7945 | @code{glGetBufferSubData} returns some or all of the data from the |
c7b31271 | 7946 | buffer object currently bound to @var{target}. Data starting at byte |
8925f36f | 7947 | offset @var{offset} and extending for @var{size} bytes is copied from |
c7b31271 | 7948 | the data store to the memory pointed to by @var{data}. An error is |
8925f36f AW |
7949 | thrown if the buffer object is currently mapped, or if @var{offset} and |
7950 | @var{size} together define a range beyond the bounds of the buffer | |
7951 | object's data store. | |
7952 | ||
8925f36f AW |
7953 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
7954 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
7955 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
7956 | ||
7957 | @code{GL_INVALID_VALUE} is generated if @var{offset} or @var{size} is | |
7958 | negative, or if together they define a region of memory that extends | |
7959 | beyond the buffer object's allocated data store. | |
7960 | ||
7961 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
7962 | name 0 is bound to @var{target}. | |
7963 | ||
7964 | @code{GL_INVALID_OPERATION} is generated if the buffer object being | |
7965 | queried is mapped. | |
7966 | ||
7967 | @code{GL_INVALID_OPERATION} is generated if @code{glGetBufferSubData} is | |
7968 | executed between the execution of @code{glBegin} and the corresponding | |
7969 | execution of @code{glEnd}. | |
7970 | ||
bb894c9d | 7971 | @end deftypefun |
8925f36f | 7972 | |
bb894c9d | 7973 | @deftypefun void glGetClipPlane plane equation |
3c9b6116 AW |
7974 | Return the coefficients of the specified clipping plane. |
7975 | ||
8925f36f AW |
7976 | @table @asis |
7977 | @item @var{plane} | |
c7b31271 DH |
7978 | Specifies a clipping plane. The number of clipping planes depends on |
7979 | the implementation, but at least six clipping planes are supported. They | |
7980 | are identified by symbolic names of the form | |
7981 | @code{GL_CLIP_PLANE}@r{@var{i}} where i ranges from 0 to the value of | |
7982 | @code{GL_MAX_CLIP_PLANES} - 1. | |
8925f36f AW |
7983 | |
7984 | @item @var{equation} | |
7985 | Returns four double-precision values that are the coefficients of the | |
c7b31271 | 7986 | plane equation of @var{plane} in eye coordinates. The initial value is |
8925f36f AW |
7987 | (0, 0, 0, 0). |
7988 | ||
7989 | @end table | |
7990 | ||
8925f36f AW |
7991 | @code{glGetClipPlane} returns in @var{equation} the four coefficients of |
7992 | the plane equation for @var{plane}. | |
7993 | ||
8925f36f AW |
7994 | @code{GL_INVALID_ENUM} is generated if @var{plane} is not an accepted |
7995 | value. | |
7996 | ||
7997 | @code{GL_INVALID_OPERATION} is generated if @code{glGetClipPlane} is | |
7998 | executed between the execution of @code{glBegin} and the corresponding | |
7999 | execution of @code{glEnd}. | |
8000 | ||
bb894c9d | 8001 | @end deftypefun |
8925f36f | 8002 | |
b002944d AW |
8003 | @deftypefun void glGetColorTableParameterfv target pname params |
8004 | @deftypefunx void glGetColorTableParameteriv target pname params | |
8005 | Get color lookup table parameters. | |
8006 | ||
8007 | @table @asis | |
8008 | @item @var{target} | |
c7b31271 | 8009 | The target color table. Must be @code{GL_COLOR_TABLE}, |
b002944d AW |
8010 | @code{GL_POST_CONVOLUTION_COLOR_TABLE}, |
8011 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}, @code{GL_PROXY_COLOR_TABLE}, | |
8012 | @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or | |
8013 | @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}. | |
8014 | ||
8015 | @item @var{pname} | |
c7b31271 | 8016 | The symbolic name of a color lookup table parameter. Must be one of |
b002944d AW |
8017 | @code{GL_COLOR_TABLE_BIAS}, @code{GL_COLOR_TABLE_SCALE}, |
8018 | @code{GL_COLOR_TABLE_FORMAT}, @code{GL_COLOR_TABLE_WIDTH}, | |
8019 | @code{GL_COLOR_TABLE_RED_SIZE}, @code{GL_COLOR_TABLE_GREEN_SIZE}, | |
8020 | @code{GL_COLOR_TABLE_BLUE_SIZE}, @code{GL_COLOR_TABLE_ALPHA_SIZE}, | |
8021 | @code{GL_COLOR_TABLE_LUMINANCE_SIZE}, or | |
8022 | @code{GL_COLOR_TABLE_INTENSITY_SIZE}. | |
8023 | ||
8024 | @item @var{params} | |
8025 | A pointer to an array where the values of the parameter will be stored. | |
8026 | ||
8027 | @end table | |
8028 | ||
8029 | Returns parameters specific to color table @var{target}. | |
8030 | ||
8031 | When @var{pname} is set to @code{GL_COLOR_TABLE_SCALE} or | |
8032 | @code{GL_COLOR_TABLE_BIAS}, @code{glGetColorTableParameter} returns the | |
8033 | color table scale or bias parameters for the table specified by | |
c7b31271 | 8034 | @var{target}. For these queries, @var{target} must be set to |
b002944d AW |
8035 | @code{GL_COLOR_TABLE}, @code{GL_POST_CONVOLUTION_COLOR_TABLE}, or |
8036 | @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} and @var{params} points to an | |
8037 | array of four elements, which receive the scale or bias factors for red, | |
8038 | green, blue, and alpha, in that order. | |
8039 | ||
8040 | @code{glGetColorTableParameter} can also be used to retrieve the format | |
c7b31271 | 8041 | and size parameters for a color table. For these queries, set |
b002944d | 8042 | @var{target} to either the color table target or the proxy color table |
c7b31271 | 8043 | target. The format and size parameters are set by @code{glColorTable}. |
b002944d AW |
8044 | |
8045 | The following table lists the format and size parameters that may be | |
c7b31271 | 8046 | queried. For each symbolic constant listed below for @var{pname}, |
b002944d AW |
8047 | @var{params} must point to an array of the given length and receive the |
8048 | values indicated. | |
8049 | ||
8050 | ||
8051 | ||
8052 | @table @asis | |
8053 | @item @strong{Parameter} | |
8054 | @strong{N}, @strong{Meaning} | |
8055 | ||
8056 | @item @code{GL_COLOR_TABLE_FORMAT} | |
8057 | 1 , Internal format (e.g., @code{GL_RGBA}) | |
8058 | ||
8059 | @item @code{GL_COLOR_TABLE_WIDTH} | |
8060 | 1 , Number of elements in table | |
8061 | ||
8062 | @item @code{GL_COLOR_TABLE_RED_SIZE} | |
8063 | 1 , Size of red component, in bits | |
8064 | ||
8065 | @item @code{GL_COLOR_TABLE_GREEN_SIZE} | |
8066 | 1 , Size of green component | |
8067 | ||
8068 | @item @code{GL_COLOR_TABLE_BLUE_SIZE} | |
8069 | 1 , Size of blue component | |
8070 | ||
8071 | @item @code{GL_COLOR_TABLE_ALPHA_SIZE} | |
8072 | 1 , Size of alpha component | |
8073 | ||
8074 | @item @code{GL_COLOR_TABLE_LUMINANCE_SIZE} | |
8075 | 1 , Size of luminance component | |
8076 | ||
8077 | @item @code{GL_COLOR_TABLE_INTENSITY_SIZE} | |
8078 | 1 , Size of intensity component | |
8079 | ||
8080 | @end table | |
8081 | ||
8082 | ||
8083 | ||
8084 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
8085 | not an acceptable value. | |
8086 | ||
8087 | @code{GL_INVALID_OPERATION} is generated if | |
8088 | @code{glGetColorTableParameter} is executed between the execution of | |
8089 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
8090 | ||
8091 | @end deftypefun | |
8092 | ||
bb894c9d | 8093 | @deftypefun void glGetColorTable target format type table |
3c9b6116 AW |
8094 | Retrieve contents of a color lookup table. |
8095 | ||
8925f36f AW |
8096 | @table @asis |
8097 | @item @var{target} | |
8098 | Must be @code{GL_COLOR_TABLE}, @code{GL_POST_CONVOLUTION_COLOR_TABLE}, | |
8099 | or @code{GL_POST_COLOR_MATRIX_COLOR_TABLE}. | |
8100 | ||
8101 | @item @var{format} | |
c7b31271 | 8102 | The format of the pixel data in @var{table}. The possible values are |
8925f36f AW |
8103 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, |
8104 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, | |
8105 | @code{GL_BGR}, @code{GL_RGBA}, and @code{GL_BGRA}. | |
8106 | ||
8107 | @item @var{type} | |
c7b31271 | 8108 | The type of the pixel data in @var{table}. Symbolic constants |
8925f36f AW |
8109 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
8110 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
8111 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
8112 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
8113 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
8114 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
8115 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
8116 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
8117 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
8118 | ||
8119 | @item @var{table} | |
8120 | Pointer to a one-dimensional array of pixel data containing the contents | |
8121 | of the color table. | |
8122 | ||
8123 | @end table | |
8124 | ||
8925f36f | 8125 | @code{glGetColorTable} returns in @var{table} the contents of the color |
c7b31271 | 8126 | table specified by @var{target}. No pixel transfer operations are |
8925f36f AW |
8127 | performed, but pixel storage modes that are applicable to |
8128 | @code{glReadPixels} are performed. | |
8129 | ||
8130 | If a non-zero named buffer object is bound to the | |
8131 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
8132 | histogram table is requested, @var{table} is treated as a byte offset | |
8133 | into the buffer object's data store. | |
8134 | ||
8135 | Color components that are requested in the specified @var{format}, but | |
8136 | which are not included in the internal format of the color lookup table, | |
c7b31271 | 8137 | are returned as zero. The assignments of internal color components to |
8925f36f AW |
8138 | the components requested by @var{format} are |
8139 | ||
8140 | @table @asis | |
8141 | @item @strong{Internal Component} | |
8142 | @strong{Resulting Component} | |
8143 | ||
8144 | @item | |
8145 | Red | |
8146 | Red | |
8147 | ||
8148 | @item | |
8149 | Green | |
8150 | Green | |
8151 | ||
8152 | @item | |
8153 | Blue | |
8154 | Blue | |
8155 | ||
8156 | @item | |
8157 | Alpha | |
8158 | Alpha | |
8159 | ||
8160 | @item | |
8161 | Luminance | |
8162 | Red | |
8163 | ||
8164 | @item | |
8165 | Intensity | |
8166 | Red | |
8167 | ||
8168 | @end table | |
8169 | ||
8170 | ||
8171 | ||
8925f36f AW |
8172 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
8173 | allowable values. | |
8174 | ||
8175 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
8176 | allowable values. | |
8177 | ||
8178 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
8179 | allowable values. | |
8180 | ||
8181 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8182 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
8183 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
8184 | and @var{format} is not @code{GL_RGB}. | |
8185 | ||
8186 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8187 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
8188 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
8189 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
8190 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
8191 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
8192 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
8193 | ||
8194 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8195 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
8196 | object's data store is currently mapped. | |
8197 | ||
8198 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8199 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
8200 | would be packed to the buffer object such that the memory writes | |
8201 | required would exceed the data store size. | |
8202 | ||
8203 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8204 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{table} | |
8205 | is not evenly divisible into the number of bytes needed to store in | |
8206 | memory a datum indicated by @var{type}. | |
8207 | ||
8208 | @code{GL_INVALID_OPERATION} is generated if @code{glGetColorTable} is | |
8209 | executed between the execution of @code{glBegin} and the corresponding | |
8210 | execution of @code{glEnd}. | |
8211 | ||
bb894c9d | 8212 | @end deftypefun |
8925f36f | 8213 | |
bb894c9d | 8214 | @deftypefun void glGetCompressedTexImage target lod img |
3c9b6116 AW |
8215 | Return a compressed texture image. |
8216 | ||
8925f36f AW |
8217 | @table @asis |
8218 | @item @var{target} | |
c7b31271 | 8219 | Specifies which texture is to be obtained. @code{GL_TEXTURE_1D}, |
8925f36f AW |
8220 | @code{GL_TEXTURE_2D}, and |
8221 | @code{GL_TEXTURE_3D}@code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
8222 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
8223 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
8224 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
8225 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, and | |
8226 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z} are accepted. | |
8227 | ||
8228 | @item @var{lod} | |
c7b31271 DH |
8229 | Specifies the level-of-detail number of the desired image. Level 0 is |
8230 | the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap | |
3c9b6116 | 8231 | reduction image. |
8925f36f AW |
8232 | |
8233 | @item @var{img} | |
8234 | Returns the compressed texture image. | |
8235 | ||
8236 | @end table | |
8237 | ||
8925f36f | 8238 | @code{glGetCompressedTexImage} returns the compressed texture image |
c7b31271 | 8239 | associated with @var{target} and @var{lod} into @var{img}. @var{img} |
8925f36f AW |
8240 | should be an array of @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} bytes. |
8241 | @var{target} specifies whether the desired texture image was one | |
8242 | specified by @code{glTexImage1D} (@code{GL_TEXTURE_1D}), | |
8243 | @code{glTexImage2D} (@code{GL_TEXTURE_2D} or any of | |
8244 | @code{GL_TEXTURE_CUBE_MAP_*}), or @code{glTexImage3D} | |
c7b31271 | 8245 | (@code{GL_TEXTURE_3D}). @var{lod} specifies the level-of-detail number |
8925f36f AW |
8246 | of the desired image. |
8247 | ||
8248 | If a non-zero named buffer object is bound to the | |
8249 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
8250 | texture image is requested, @var{img} is treated as a byte offset into | |
8251 | the buffer object's data store. | |
8252 | ||
8253 | To minimize errors, first verify that the texture is compressed by | |
8254 | calling @code{glGetTexLevelParameter} with argument | |
c7b31271 | 8255 | @code{GL_TEXTURE_COMPRESSED}. If the texture is compressed, then |
8925f36f AW |
8256 | determine the amount of memory required to store the compressed texture |
8257 | by calling @code{glGetTexLevelParameter} with argument | |
c7b31271 | 8258 | @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE}. Finally, retrieve the internal |
8925f36f | 8259 | format of the texture by calling @code{glGetTexLevelParameter} with |
c7b31271 | 8260 | argument @code{GL_TEXTURE_INTERNAL_FORMAT}. To store the texture for |
8925f36f | 8261 | later use, associate the internal format and size with the retrieved |
c7b31271 | 8262 | texture image. These data can be used by the respective texture or |
8925f36f AW |
8263 | subtexture loading routine used for loading @var{target} textures. |
8264 | ||
8925f36f AW |
8265 | @code{GL_INVALID_VALUE} is generated if @var{lod} is less than zero or |
8266 | greater than the maximum number of LODs permitted by the implementation. | |
8267 | ||
8268 | @code{GL_INVALID_OPERATION} is generated if | |
8269 | @code{glGetCompressedTexImage} is used to retrieve a texture that is in | |
8270 | an uncompressed internal format. | |
8271 | ||
8272 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8273 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
8274 | object's data store is currently mapped. | |
8275 | ||
8276 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8277 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
8278 | would be packed to the buffer object such that the memory writes | |
8279 | required would exceed the data store size. | |
8280 | ||
8281 | @code{GL_INVALID_OPERATION} is generated if | |
8282 | @code{glGetCompressedTexImage} is executed between the execution of | |
8283 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
8284 | ||
bb894c9d | 8285 | @end deftypefun |
8925f36f | 8286 | |
bb894c9d | 8287 | @deftypefun void glGetConvolutionFilter target format type image |
3c9b6116 AW |
8288 | Get current 1D or 2D convolution filter kernel. |
8289 | ||
8925f36f AW |
8290 | @table @asis |
8291 | @item @var{target} | |
c7b31271 | 8292 | The filter to be retrieved. Must be one of @code{GL_CONVOLUTION_1D} or |
8925f36f AW |
8293 | @code{GL_CONVOLUTION_2D}. |
8294 | ||
8295 | @item @var{format} | |
c7b31271 | 8296 | Format of the output image. Must be one of @code{GL_RED}, |
8925f36f AW |
8297 | @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, |
8298 | @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, or | |
8299 | @code{GL_LUMINANCE_ALPHA}. | |
8300 | ||
8301 | @item @var{type} | |
c7b31271 | 8302 | Data type of components in the output image. Symbolic constants |
8925f36f AW |
8303 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
8304 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
8305 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
8306 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
8307 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
8308 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
8309 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
8310 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
8311 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
8312 | ||
8313 | @item @var{image} | |
8314 | Pointer to storage for the output image. | |
8315 | ||
8316 | @end table | |
8317 | ||
8925f36f | 8318 | @code{glGetConvolutionFilter} returns the current 1D or 2D convolution |
c7b31271 | 8319 | filter kernel as an image. The one- or two-dimensional image is placed |
8925f36f | 8320 | in @var{image} according to the specifications in @var{format} and |
c7b31271 | 8321 | @var{type}. No pixel transfer operations are performed on this image, |
8925f36f AW |
8322 | but the relevant pixel storage modes are applied. |
8323 | ||
8324 | If a non-zero named buffer object is bound to the | |
8325 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
8326 | convolution filter is requested, @var{image} is treated as a byte offset | |
8327 | into the buffer object's data store. | |
8328 | ||
8329 | Color components that are present in @var{format} but not included in | |
c7b31271 | 8330 | the internal format of the filter are returned as zero. The assignments |
8925f36f AW |
8331 | of internal color components to the components of @var{format} are as |
8332 | follows. | |
8333 | ||
8334 | @table @asis | |
8335 | @item @strong{Internal Component} | |
8336 | @strong{Resulting Component} | |
8337 | ||
8338 | @item | |
8339 | Red | |
8340 | Red | |
8341 | ||
8342 | @item | |
8343 | Green | |
8344 | Green | |
8345 | ||
8346 | @item | |
8347 | Blue | |
8348 | Blue | |
8349 | ||
8350 | @item | |
8351 | Alpha | |
8352 | Alpha | |
8353 | ||
8354 | @item | |
8355 | Luminance | |
8356 | Red | |
8357 | ||
8358 | @item | |
8359 | Intensity | |
8360 | Red | |
8361 | ||
8362 | @end table | |
8363 | ||
8364 | ||
8365 | ||
8925f36f AW |
8366 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
8367 | allowable values. | |
8368 | ||
8369 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
8370 | allowable values. | |
8371 | ||
8372 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
8373 | allowable values. | |
8374 | ||
8375 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8376 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
8377 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
8378 | and @var{format} is not @code{GL_RGB}. | |
8379 | ||
8380 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8381 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
8382 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
8383 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
8384 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
8385 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
8386 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
8387 | ||
8388 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8389 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
8390 | object's data store is currently mapped. | |
8391 | ||
8392 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8393 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
8394 | would be packed to the buffer object such that the memory writes | |
8395 | required would exceed the data store size. | |
8396 | ||
8397 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8398 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{image} | |
8399 | is not evenly divisible into the number of bytes needed to store in | |
8400 | memory a datum indicated by @var{type}. | |
8401 | ||
8402 | @code{GL_INVALID_OPERATION} is generated if | |
8403 | @code{glGetConvolutionFilter} is executed between the execution of | |
8404 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
8405 | ||
bb894c9d | 8406 | @end deftypefun |
8925f36f | 8407 | |
b002944d AW |
8408 | @deftypefun void glGetConvolutionParameterfv target pname params |
8409 | @deftypefunx void glGetConvolutionParameteriv target pname params | |
8410 | Get convolution parameters. | |
8411 | ||
8412 | @table @asis | |
8413 | @item @var{target} | |
c7b31271 | 8414 | The filter whose parameters are to be retrieved. Must be one of |
b002944d AW |
8415 | @code{GL_CONVOLUTION_1D}, @code{GL_CONVOLUTION_2D}, or |
8416 | @code{GL_SEPARABLE_2D}. | |
8417 | ||
8418 | @item @var{pname} | |
c7b31271 | 8419 | The parameter to be retrieved. Must be one of |
b002944d AW |
8420 | @code{GL_CONVOLUTION_BORDER_MODE}, @code{GL_CONVOLUTION_BORDER_COLOR}, |
8421 | @code{GL_CONVOLUTION_FILTER_SCALE}, @code{GL_CONVOLUTION_FILTER_BIAS}, | |
8422 | @code{GL_CONVOLUTION_FORMAT}, @code{GL_CONVOLUTION_WIDTH}, | |
8423 | @code{GL_CONVOLUTION_HEIGHT}, @code{GL_MAX_CONVOLUTION_WIDTH}, or | |
8424 | @code{GL_MAX_CONVOLUTION_HEIGHT}. | |
8425 | ||
8426 | @item @var{params} | |
8427 | Pointer to storage for the parameters to be retrieved. | |
8428 | ||
8429 | @end table | |
8430 | ||
8431 | @code{glGetConvolutionParameter} retrieves convolution parameters. | |
c7b31271 | 8432 | @var{target} determines which convolution filter is queried. @var{pname} |
b002944d AW |
8433 | determines which parameter is returned: |
8434 | ||
8435 | @table @asis | |
8436 | @item @code{GL_CONVOLUTION_BORDER_MODE} | |
8437 | ||
8438 | ||
c7b31271 | 8439 | The convolution border mode. See @code{glConvolutionParameter} for a |
b002944d AW |
8440 | list of border modes. |
8441 | ||
8442 | @item @code{GL_CONVOLUTION_BORDER_COLOR} | |
8443 | ||
8444 | ||
c7b31271 | 8445 | The current convolution border color. @var{params} must be a pointer to |
b002944d AW |
8446 | an array of four elements, which will receive the red, green, blue, and |
8447 | alpha border colors. | |
8448 | ||
8449 | @item @code{GL_CONVOLUTION_FILTER_SCALE} | |
8450 | ||
8451 | ||
c7b31271 | 8452 | The current filter scale factors. @var{params} must be a pointer to an |
b002944d AW |
8453 | array of four elements, which will receive the red, green, blue, and |
8454 | alpha filter scale factors in that order. | |
8455 | ||
8456 | @item @code{GL_CONVOLUTION_FILTER_BIAS} | |
8457 | ||
8458 | ||
c7b31271 | 8459 | The current filter bias factors. @var{params} must be a pointer to an |
b002944d AW |
8460 | array of four elements, which will receive the red, green, blue, and |
8461 | alpha filter bias terms in that order. | |
8462 | ||
8463 | @item @code{GL_CONVOLUTION_FORMAT} | |
8464 | ||
8465 | ||
c7b31271 | 8466 | The current internal format. See @code{glConvolutionFilter1D}, |
b002944d AW |
8467 | @code{glConvolutionFilter2D}, and @code{glSeparableFilter2D} for lists |
8468 | of allowable formats. | |
8469 | ||
8470 | @item @code{GL_CONVOLUTION_WIDTH} | |
8471 | ||
8472 | ||
8473 | The current filter image width. | |
8474 | ||
8475 | @item @code{GL_CONVOLUTION_HEIGHT} | |
8476 | ||
8477 | ||
8478 | The current filter image height. | |
8479 | ||
8480 | @item @code{GL_MAX_CONVOLUTION_WIDTH} | |
8481 | ||
8482 | ||
8483 | The maximum acceptable filter image width. | |
8484 | ||
8485 | @item @code{GL_MAX_CONVOLUTION_HEIGHT} | |
8486 | ||
8487 | ||
8488 | The maximum acceptable filter image height. | |
8489 | ||
8490 | @end table | |
8491 | ||
8492 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the | |
8493 | allowable values. | |
8494 | ||
8495 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the | |
8496 | allowable values. | |
8497 | ||
8498 | @code{GL_INVALID_ENUM} is generated if @var{target} is | |
8499 | @code{GL_CONVOLUTION_1D} and @var{pname} is @code{GL_CONVOLUTION_HEIGHT} | |
8500 | or @code{GL_MAX_CONVOLUTION_HEIGHT}. | |
8501 | ||
8502 | @code{GL_INVALID_OPERATION} is generated if | |
8503 | @code{glGetConvolutionParameter} is executed between the execution of | |
8504 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
8505 | ||
8506 | @end deftypefun | |
8507 | ||
bb894c9d | 8508 | @deftypefun GLenum glGetError |
3c9b6116 AW |
8509 | Return error information. |
8510 | ||
c7b31271 DH |
8511 | @code{glGetError} returns the value of the error flag. Each detectable |
8512 | error is assigned a numeric code and symbolic name. When an error | |
8513 | occurs, the error flag is set to the appropriate error code value. No | |
8925f36f | 8514 | other errors are recorded until @code{glGetError} is called, the error |
c7b31271 DH |
8515 | code is returned, and the flag is reset to @code{GL_NO_ERROR}. If a |
8516 | call to @code{glGetError} returns @code{GL_NO_ERROR}, there has been no | |
8925f36f AW |
8517 | detectable error since the last call to @code{glGetError}, or since the |
8518 | GL was initialized. | |
8519 | ||
8520 | To allow for distributed implementations, there may be several error | |
c7b31271 DH |
8521 | flags. If any single error flag has recorded an error, the value of |
8522 | that flag is returned and that flag is reset to @code{GL_NO_ERROR} when | |
8523 | @code{glGetError} is called. If more than one flag has recorded an | |
8925f36f | 8524 | error, @code{glGetError} returns and clears an arbitrary error flag |
c7b31271 | 8525 | value. Thus, @code{glGetError} should always be called in a loop, until |
8925f36f AW |
8526 | it returns @code{GL_NO_ERROR}, if all error flags are to be reset. |
8527 | ||
8528 | Initially, all error flags are set to @code{GL_NO_ERROR}. | |
8529 | ||
8530 | The following errors are currently defined: | |
8531 | ||
8532 | @table @asis | |
8533 | @item @code{GL_NO_ERROR} | |
c7b31271 | 8534 | No error has been recorded. The value of this symbolic constant is |
8925f36f AW |
8535 | guaranteed to be 0. |
8536 | ||
8537 | @item @code{GL_INVALID_ENUM} | |
c7b31271 | 8538 | An unacceptable value is specified for an enumerated argument. The |
8925f36f AW |
8539 | offending command is ignored and has no other side effect than to set |
8540 | the error flag. | |
8541 | ||
8542 | @item @code{GL_INVALID_VALUE} | |
c7b31271 DH |
8543 | A numeric argument is out of range. The offending command is ignored |
8544 | and has no other side effect than to set the error flag. | |
8925f36f AW |
8545 | |
8546 | @item @code{GL_INVALID_OPERATION} | |
c7b31271 | 8547 | The specified operation is not allowed in the current state. The |
8925f36f AW |
8548 | offending command is ignored and has no other side effect than to set |
8549 | the error flag. | |
8550 | ||
8551 | @item @code{GL_STACK_OVERFLOW} | |
c7b31271 | 8552 | This command would cause a stack overflow. The offending command is |
8925f36f AW |
8553 | ignored and has no other side effect than to set the error flag. |
8554 | ||
8555 | @item @code{GL_STACK_UNDERFLOW} | |
c7b31271 | 8556 | This command would cause a stack underflow. The offending command is |
8925f36f AW |
8557 | ignored and has no other side effect than to set the error flag. |
8558 | ||
8559 | @item @code{GL_OUT_OF_MEMORY} | |
c7b31271 DH |
8560 | There is not enough memory left to execute the command. The state of |
8561 | the GL is undefined, except for the state of the error flags, after this | |
8925f36f AW |
8562 | error is recorded. |
8563 | ||
8564 | @item @code{GL_TABLE_TOO_LARGE} | |
8565 | The specified table exceeds the implementation's maximum supported table | |
c7b31271 DH |
8566 | size. The offending command is ignored and has no other side effect |
8567 | than to set the error flag. | |
8925f36f AW |
8568 | |
8569 | @end table | |
8570 | ||
8571 | When an error flag is set, results of a GL operation are undefined only | |
c7b31271 DH |
8572 | if @code{GL_OUT_OF_MEMORY} has occurred. In all other cases, the |
8573 | command generating the error is ignored and has no effect on the GL | |
8574 | state or frame buffer contents. If the generating command returns a | |
8575 | value, it returns 0. If @code{glGetError} itself generates an error, it | |
8576 | returns 0. | |
8925f36f | 8577 | |
8925f36f AW |
8578 | @code{GL_INVALID_OPERATION} is generated if @code{glGetError} is |
8579 | executed between the execution of @code{glBegin} and the corresponding | |
c7b31271 | 8580 | execution of @code{glEnd}. In this case, @code{glGetError} returns 0. |
8925f36f | 8581 | |
bb894c9d | 8582 | @end deftypefun |
8925f36f | 8583 | |
b002944d AW |
8584 | @deftypefun void glGetHistogramParameterfv target pname params |
8585 | @deftypefunx void glGetHistogramParameteriv target pname params | |
8586 | Get histogram parameters. | |
8587 | ||
8588 | @table @asis | |
8589 | @item @var{target} | |
8590 | Must be one of @code{GL_HISTOGRAM} or @code{GL_PROXY_HISTOGRAM}. | |
8591 | ||
8592 | @item @var{pname} | |
c7b31271 | 8593 | The name of the parameter to be retrieved. Must be one of |
b002944d AW |
8594 | @code{GL_HISTOGRAM_WIDTH}, @code{GL_HISTOGRAM_FORMAT}, |
8595 | @code{GL_HISTOGRAM_RED_SIZE}, @code{GL_HISTOGRAM_GREEN_SIZE}, | |
8596 | @code{GL_HISTOGRAM_BLUE_SIZE}, @code{GL_HISTOGRAM_ALPHA_SIZE}, | |
8597 | @code{GL_HISTOGRAM_LUMINANCE_SIZE}, or @code{GL_HISTOGRAM_SINK}. | |
8598 | ||
8599 | @item @var{params} | |
8600 | Pointer to storage for the returned values. | |
8601 | ||
8602 | @end table | |
8603 | ||
8604 | @code{glGetHistogramParameter} is used to query parameter values for the | |
c7b31271 DH |
8605 | current histogram or for a proxy. The histogram state information may |
8606 | be queried by calling @code{glGetHistogramParameter} with a @var{target} | |
8607 | of @code{GL_HISTOGRAM} (to obtain information for the current histogram | |
b002944d AW |
8608 | table) or @code{GL_PROXY_HISTOGRAM} (to obtain information from the most |
8609 | recent proxy request) and one of the following values for the | |
8610 | @var{pname} argument: | |
8611 | ||
8612 | ||
8613 | ||
8614 | @table @asis | |
8615 | @item @strong{Parameter} | |
8616 | @strong{Description} | |
8617 | ||
8618 | @item @code{GL_HISTOGRAM_WIDTH} | |
8619 | Histogram table width | |
8620 | ||
8621 | @item @code{GL_HISTOGRAM_FORMAT} | |
8622 | Internal format | |
8623 | ||
8624 | @item @code{GL_HISTOGRAM_RED_SIZE} | |
8625 | Red component counter size, in bits | |
8626 | ||
8627 | @item @code{GL_HISTOGRAM_GREEN_SIZE} | |
8628 | Green component counter size, in bits | |
8629 | ||
8630 | @item @code{GL_HISTOGRAM_BLUE_SIZE} | |
8631 | Blue component counter size, in bits | |
8632 | ||
8633 | @item @code{GL_HISTOGRAM_ALPHA_SIZE} | |
8634 | Alpha component counter size, in bits | |
8635 | ||
8636 | @item @code{GL_HISTOGRAM_LUMINANCE_SIZE} | |
8637 | Luminance component counter size, in bits | |
8638 | ||
8639 | @item @code{GL_HISTOGRAM_SINK} | |
8640 | Value of the @var{sink} parameter | |
8641 | ||
8642 | @end table | |
8643 | ||
8644 | ||
8645 | ||
8646 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the | |
8647 | allowable values. | |
8648 | ||
8649 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the | |
8650 | allowable values. | |
8651 | ||
8652 | @code{GL_INVALID_OPERATION} is generated if | |
8653 | @code{glGetHistogramParameter} is executed between the execution of | |
8654 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
8655 | ||
8656 | @end deftypefun | |
8657 | ||
bb894c9d | 8658 | @deftypefun void glGetHistogram target reset format type values |
3c9b6116 AW |
8659 | Get histogram table. |
8660 | ||
8925f36f AW |
8661 | @table @asis |
8662 | @item @var{target} | |
8663 | Must be @code{GL_HISTOGRAM}. | |
8664 | ||
8665 | @item @var{reset} | |
8666 | If @code{GL_TRUE}, each component counter that is actually returned is | |
c7b31271 DH |
8667 | reset to zero. (Other counters are unaffected.) If @code{GL_FALSE}, |
8668 | none of the counters in the histogram table is modified. | |
8925f36f AW |
8669 | |
8670 | @item @var{format} | |
c7b31271 | 8671 | The format of values to be returned in @var{values}. Must be one of |
8925f36f AW |
8672 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, |
8673 | @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, | |
8674 | @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}. | |
8675 | ||
8676 | @item @var{type} | |
c7b31271 | 8677 | The type of values to be returned in @var{values}. Symbolic constants |
8925f36f AW |
8678 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
8679 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
8680 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
8681 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
8682 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
8683 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
8684 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
8685 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
8686 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
8687 | ||
8688 | @item @var{values} | |
8689 | A pointer to storage for the returned histogram table. | |
8690 | ||
8691 | @end table | |
8692 | ||
8925f36f | 8693 | @code{glGetHistogram} returns the current histogram table as a |
c7b31271 | 8694 | one-dimensional image with the same width as the histogram. No pixel |
8925f36f AW |
8695 | transfer operations are performed on this image, but pixel storage modes |
8696 | that are applicable to 1D images are honored. | |
8697 | ||
8698 | If a non-zero named buffer object is bound to the | |
8699 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
8700 | histogram table is requested, @var{values} is treated as a byte offset | |
8701 | into the buffer object's data store. | |
8702 | ||
8703 | Color components that are requested in the specified @var{format}, but | |
8704 | which are not included in the internal format of the histogram, are | |
c7b31271 | 8705 | returned as zero. The assignments of internal color components to the |
8925f36f AW |
8706 | components requested by @var{format} are: |
8707 | ||
8708 | @table @asis | |
8709 | @item @strong{Internal Component} | |
8710 | @strong{Resulting Component} | |
8711 | ||
8712 | @item | |
8713 | Red | |
8714 | Red | |
8715 | ||
8716 | @item | |
8717 | Green | |
8718 | Green | |
8719 | ||
8720 | @item | |
8721 | Blue | |
8722 | Blue | |
8723 | ||
8724 | @item | |
8725 | Alpha | |
8726 | Alpha | |
8727 | ||
8728 | @item | |
8729 | Luminance | |
8730 | Red | |
8731 | ||
8732 | @end table | |
8733 | ||
8734 | ||
8735 | ||
8925f36f AW |
8736 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
8737 | @code{GL_HISTOGRAM}. | |
8738 | ||
8739 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
8740 | allowable values. | |
8741 | ||
8742 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
8743 | allowable values. | |
8744 | ||
8745 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8746 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
8747 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
8748 | and @var{format} is not @code{GL_RGB}. | |
8749 | ||
8750 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
8751 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
8752 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
8753 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
8754 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
8755 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
8756 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
8757 | ||
8758 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8759 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
8760 | object's data store is currently mapped. | |
8761 | ||
8762 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8763 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
8764 | would be packed to the buffer object such that the memory writes | |
8765 | required would exceed the data store size. | |
8766 | ||
8767 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
8768 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{values} | |
8769 | is not evenly divisible into the number of bytes needed to store in | |
8770 | memory a datum indicated by @var{type}. | |
8771 | ||
8772 | @code{GL_INVALID_OPERATION} is generated if @code{glGetHistogram} is | |
8773 | executed between the execution of @code{glBegin} and the corresponding | |
8774 | execution of @code{glEnd}. | |
8775 | ||
bb894c9d | 8776 | @end deftypefun |
8925f36f | 8777 | |
b002944d AW |
8778 | @deftypefun void glGetLightfv light pname params |
8779 | @deftypefunx void glGetLightiv light pname params | |
8780 | Return light source parameter values. | |
3c9b6116 | 8781 | |
8925f36f | 8782 | @table @asis |
b002944d | 8783 | @item @var{light} |
c7b31271 DH |
8784 | Specifies a light source. The number of possible lights depends on the |
8785 | implementation, but at least eight lights are supported. They are | |
b002944d AW |
8786 | identified by symbolic names of the form @code{GL_LIGHT}@r{@var{i}} |
8787 | where @r{@var{i}} ranges from 0 to the value of @code{GL_MAX_LIGHTS} - | |
8788 | 1. | |
8925f36f | 8789 | |
b002944d | 8790 | @item @var{pname} |
c7b31271 | 8791 | Specifies a light source parameter for @var{light}. Accepted symbolic |
b002944d AW |
8792 | names are @code{GL_AMBIENT}, @code{GL_DIFFUSE}, @code{GL_SPECULAR}, |
8793 | @code{GL_POSITION}, @code{GL_SPOT_DIRECTION}, @code{GL_SPOT_EXPONENT}, | |
8794 | @code{GL_SPOT_CUTOFF}, @code{GL_CONSTANT_ATTENUATION}, | |
8795 | @code{GL_LINEAR_ATTENUATION}, and @code{GL_QUADRATIC_ATTENUATION}. | |
8925f36f | 8796 | |
b002944d AW |
8797 | @item @var{params} |
8798 | Returns the requested data. | |
8925f36f | 8799 | |
b002944d | 8800 | @end table |
8925f36f | 8801 | |
b002944d | 8802 | @code{glGetLight} returns in @var{params} the value or values of a light |
c7b31271 | 8803 | source parameter. @var{light} names the light and is a symbolic name of |
b002944d | 8804 | the form @code{GL_LIGHT}@r{@var{i}} where i ranges from 0 to the value |
c7b31271 DH |
8805 | of @code{GL_MAX_LIGHTS} - 1. @code{GL_MAX_LIGHTS} is an implementation |
8806 | dependent constant that is greater than or equal to eight. @var{pname} | |
b002944d | 8807 | specifies one of ten light source parameters, again by symbolic name. |
8925f36f | 8808 | |
b002944d | 8809 | The following parameters are defined: |
8925f36f | 8810 | |
b002944d AW |
8811 | @table @asis |
8812 | @item @code{GL_AMBIENT} | |
8813 | @var{params} returns four integer or floating-point values representing | |
c7b31271 | 8814 | the ambient intensity of the light source. Integer values, when |
b002944d AW |
8815 | requested, are linearly mapped from the internal floating-point |
8816 | representation such that 1.0 maps to the most positive representable | |
8817 | integer value, and @r{-1.0} maps to the most negative representable | |
c7b31271 DH |
8818 | integer value. If the internal value is outside the range @r{[-1,1]}, |
8819 | the corresponding integer return value is undefined. The initial value | |
b002944d AW |
8820 | is (0, 0, 0, 1). |
8821 | ||
8822 | @item @code{GL_DIFFUSE} | |
8823 | @var{params} returns four integer or floating-point values representing | |
c7b31271 | 8824 | the diffuse intensity of the light source. Integer values, when |
b002944d AW |
8825 | requested, are linearly mapped from the internal floating-point |
8826 | representation such that 1.0 maps to the most positive representable | |
8827 | integer value, and @r{-1.0} maps to the most negative representable | |
c7b31271 DH |
8828 | integer value. If the internal value is outside the range @r{[-1,1]}, |
8829 | the corresponding integer return value is undefined. The initial value | |
b002944d AW |
8830 | for @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial |
8831 | value is (0, 0, 0, 0). | |
8832 | ||
8833 | @item @code{GL_SPECULAR} | |
8834 | @var{params} returns four integer or floating-point values representing | |
c7b31271 | 8835 | the specular intensity of the light source. Integer values, when |
b002944d AW |
8836 | requested, are linearly mapped from the internal floating-point |
8837 | representation such that 1.0 maps to the most positive representable | |
8838 | integer value, and @r{-1.0} maps to the most negative representable | |
c7b31271 DH |
8839 | integer value. If the internal value is outside the range @r{[-1,1]}, |
8840 | the corresponding integer return value is undefined. The initial value | |
b002944d AW |
8841 | for @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial |
8842 | value is (0, 0, 0, 0). | |
8843 | ||
8844 | @item @code{GL_POSITION} | |
8845 | @var{params} returns four integer or floating-point values representing | |
c7b31271 | 8846 | the position of the light source. Integer values, when requested, are |
b002944d | 8847 | computed by rounding the internal floating-point values to the nearest |
c7b31271 DH |
8848 | integer value. The returned values are those maintained in eye |
8849 | coordinates. They will not be equal to the values specified using | |
b002944d | 8850 | @code{glLight}, unless the modelview matrix was identity at the time |
c7b31271 | 8851 | @code{glLight} was called. The initial value is (0, 0, 1, 0). |
b002944d AW |
8852 | |
8853 | @item @code{GL_SPOT_DIRECTION} | |
8854 | @var{params} returns three integer or floating-point values representing | |
c7b31271 | 8855 | the direction of the light source. Integer values, when requested, are |
b002944d | 8856 | computed by rounding the internal floating-point values to the nearest |
c7b31271 DH |
8857 | integer value. The returned values are those maintained in eye |
8858 | coordinates. They will not be equal to the values specified using | |
b002944d | 8859 | @code{glLight}, unless the modelview matrix was identity at the time |
c7b31271 | 8860 | @code{glLight} was called. Although spot direction is normalized before |
b002944d | 8861 | being used in the lighting equation, the returned values are the |
c7b31271 | 8862 | transformed versions of the specified values prior to normalization. The |
b002944d AW |
8863 | initial value is @r{(0,0-1)}. |
8864 | ||
8865 | @item @code{GL_SPOT_EXPONENT} | |
8866 | @var{params} returns a single integer or floating-point value | |
c7b31271 | 8867 | representing the spot exponent of the light. An integer value, when |
b002944d | 8868 | requested, is computed by rounding the internal floating-point |
c7b31271 | 8869 | representation to the nearest integer. The initial value is 0. |
b002944d AW |
8870 | |
8871 | @item @code{GL_SPOT_CUTOFF} | |
8872 | @var{params} returns a single integer or floating-point value | |
c7b31271 | 8873 | representing the spot cutoff angle of the light. An integer value, when |
b002944d | 8874 | requested, is computed by rounding the internal floating-point |
c7b31271 | 8875 | representation to the nearest integer. The initial value is 180. |
b002944d AW |
8876 | |
8877 | @item @code{GL_CONSTANT_ATTENUATION} | |
8878 | @var{params} returns a single integer or floating-point value | |
8879 | representing the constant (not distance-related) attenuation of the | |
c7b31271 DH |
8880 | light. An integer value, when requested, is computed by rounding the |
8881 | internal floating-point representation to the nearest integer. The | |
b002944d AW |
8882 | initial value is 1. |
8883 | ||
8884 | @item @code{GL_LINEAR_ATTENUATION} | |
8885 | @var{params} returns a single integer or floating-point value | |
c7b31271 DH |
8886 | representing the linear attenuation of the light. An integer value, |
8887 | when requested, is computed by rounding the internal floating-point | |
8888 | representation to the nearest integer. The initial value is 0. | |
b002944d AW |
8889 | |
8890 | @item @code{GL_QUADRATIC_ATTENUATION} | |
8891 | @var{params} returns a single integer or floating-point value | |
c7b31271 | 8892 | representing the quadratic attenuation of the light. An integer value, |
b002944d | 8893 | when requested, is computed by rounding the internal floating-point |
c7b31271 | 8894 | representation to the nearest integer. The initial value is 0. |
b002944d AW |
8895 | |
8896 | @end table | |
8897 | ||
8898 | @code{GL_INVALID_ENUM} is generated if @var{light} or @var{pname} is not | |
8899 | an accepted value. | |
8900 | ||
8901 | @code{GL_INVALID_OPERATION} is generated if @code{glGetLight} is | |
8902 | executed between the execution of @code{glBegin} and the corresponding | |
8903 | execution of @code{glEnd}. | |
8904 | ||
8905 | @end deftypefun | |
8906 | ||
d172eed9 AW |
8907 | @deftypefun void glGetMapdv target query v |
8908 | @deftypefunx void glGetMapfv target query v | |
b002944d AW |
8909 | @deftypefunx void glGetMapiv target query v |
8910 | Return evaluator parameters. | |
8911 | ||
8912 | @table @asis | |
8913 | @item @var{target} | |
c7b31271 | 8914 | Specifies the symbolic name of a map. Accepted values are |
b002944d AW |
8915 | @code{GL_MAP1_COLOR_4}, @code{GL_MAP1_INDEX}, @code{GL_MAP1_NORMAL}, |
8916 | @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2}, | |
8917 | @code{GL_MAP1_TEXTURE_COORD_3}, @code{GL_MAP1_TEXTURE_COORD_4}, | |
8918 | @code{GL_MAP1_VERTEX_3}, @code{GL_MAP1_VERTEX_4}, | |
8919 | @code{GL_MAP2_COLOR_4}, @code{GL_MAP2_INDEX}, @code{GL_MAP2_NORMAL}, | |
8920 | @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2}, | |
8921 | @code{GL_MAP2_TEXTURE_COORD_3}, @code{GL_MAP2_TEXTURE_COORD_4}, | |
8922 | @code{GL_MAP2_VERTEX_3}, and @code{GL_MAP2_VERTEX_4}. | |
8923 | ||
8924 | @item @var{query} | |
c7b31271 | 8925 | Specifies which parameter to return. Symbolic names @code{GL_COEFF}, |
b002944d AW |
8926 | @code{GL_ORDER}, and @code{GL_DOMAIN} are accepted. |
8927 | ||
8928 | @item @var{v} | |
8929 | Returns the requested data. | |
8930 | ||
8931 | @end table | |
8932 | ||
c7b31271 DH |
8933 | @code{glMap1} and @code{glMap2} define evaluators. @code{glGetMap} |
8934 | returns evaluator parameters. @var{target} chooses a map, @var{query} | |
b002944d AW |
8935 | selects a specific parameter, and @var{v} points to storage where the |
8936 | values will be returned. | |
8937 | ||
8938 | The acceptable values for the @var{target} parameter are described in | |
8939 | the @code{glMap1} and @code{glMap2} reference pages. | |
8940 | ||
8941 | @var{query} can assume the following values: | |
8942 | ||
8943 | @table @asis | |
8944 | @item @code{GL_COEFF} | |
8945 | @var{v} returns the control points for the evaluator function. | |
8946 | One-dimensional evaluators return @r{@var{order}} control points, and | |
8947 | two-dimensional evaluators return @r{@var{uorder}×@var{vorder}} control | |
c7b31271 DH |
8948 | points. Each control point consists of one, two, three, or four |
8949 | integer, single-precision floating-point, or double-precision | |
8950 | floating-point values, depending on the type of the evaluator. The GL | |
8951 | returns two-dimensional control points in row-major order, incrementing | |
8952 | the @r{@var{uorder}} index quickly and the @r{@var{vorder}} index after | |
8953 | each row. Integer values, when requested, are computed by rounding the | |
b002944d AW |
8954 | internal floating-point values to the nearest integer values. |
8955 | ||
8956 | @item @code{GL_ORDER} | |
c7b31271 DH |
8957 | @var{v} returns the order of the evaluator function. One-dimensional |
8958 | evaluators return a single value, @r{@var{order}}. The initial value is | |
8959 | 1. Two-dimensional evaluators return two values, @r{@var{uorder}} and | |
8960 | @r{@var{vorder}}. The initial value is 1,1. | |
b002944d AW |
8961 | |
8962 | @item @code{GL_DOMAIN} | |
8963 | @var{v} returns the linear @r{@var{u}} and @r{@var{v}} mapping | |
c7b31271 DH |
8964 | parameters. One-dimensional evaluators return two values, @r{@var{u1}} |
8965 | and @r{@var{u2}}, as specified by @code{glMap1}. Two-dimensional | |
b002944d | 8966 | evaluators return four values (@r{@var{u1}}, @r{@var{u2}}, @r{@var{v1}}, |
c7b31271 | 8967 | and @r{@var{v2}}) as specified by @code{glMap2}. Integer values, when |
b002944d AW |
8968 | requested, are computed by rounding the internal floating-point values |
8969 | to the nearest integer values. | |
8970 | ||
8971 | @end table | |
8972 | ||
8973 | @code{GL_INVALID_ENUM} is generated if either @var{target} or | |
8974 | @var{query} is not an accepted value. | |
8975 | ||
8976 | @code{GL_INVALID_OPERATION} is generated if @code{glGetMap} is executed | |
8977 | between the execution of @code{glBegin} and the corresponding execution | |
8978 | of @code{glEnd}. | |
8979 | ||
8980 | @end deftypefun | |
8981 | ||
8982 | @deftypefun void glGetMaterialfv face pname params | |
8983 | @deftypefunx void glGetMaterialiv face pname params | |
8984 | Return material parameters. | |
8985 | ||
8986 | @table @asis | |
8987 | @item @var{face} | |
c7b31271 | 8988 | Specifies which of the two materials is being queried. @code{GL_FRONT} |
b002944d AW |
8989 | or @code{GL_BACK} are accepted, representing the front and back |
8990 | materials, respectively. | |
8991 | ||
8992 | @item @var{pname} | |
c7b31271 | 8993 | Specifies the material parameter to return. @code{GL_AMBIENT}, |
b002944d AW |
8994 | @code{GL_DIFFUSE}, @code{GL_SPECULAR}, @code{GL_EMISSION}, |
8995 | @code{GL_SHININESS}, and @code{GL_COLOR_INDEXES} are accepted. | |
8996 | ||
8997 | @item @var{params} | |
8998 | Returns the requested data. | |
8999 | ||
9000 | @end table | |
9001 | ||
9002 | @code{glGetMaterial} returns in @var{params} the value or values of | |
c7b31271 | 9003 | parameter @var{pname} of material @var{face}. Six parameters are |
b002944d AW |
9004 | defined: |
9005 | ||
9006 | @table @asis | |
9007 | @item @code{GL_AMBIENT} | |
9008 | @var{params} returns four integer or floating-point values representing | |
c7b31271 DH |
9009 | the ambient reflectance of the material. Integer values, when |
9010 | requested, are linearly mapped from the internal floating-point | |
9011 | representation such that 1.0 maps to the most positive representable | |
9012 | integer value, and @r{-1.0} maps to the most negative representable | |
9013 | integer value. If the internal value is outside the range @r{[-1,1]}, | |
9014 | the corresponding integer return value is undefined. The initial value | |
9015 | is (0.2, 0.2, 0.2, 1.0) | |
b002944d AW |
9016 | |
9017 | @item @code{GL_DIFFUSE} | |
9018 | @var{params} returns four integer or floating-point values representing | |
c7b31271 DH |
9019 | the diffuse reflectance of the material. Integer values, when |
9020 | requested, are linearly mapped from the internal floating-point | |
9021 | representation such that 1.0 maps to the most positive representable | |
9022 | integer value, and @r{-1.0} maps to the most negative representable | |
9023 | integer value. If the internal value is outside the range @r{[-1,1]}, | |
9024 | the corresponding integer return value is undefined. The initial value | |
9025 | is (0.8, 0.8, 0.8, 1.0). | |
b002944d AW |
9026 | |
9027 | @item @code{GL_SPECULAR} | |
9028 | @var{params} returns four integer or floating-point values representing | |
c7b31271 | 9029 | the specular reflectance of the material. Integer values, when |
b002944d AW |
9030 | requested, are linearly mapped from the internal floating-point |
9031 | representation such that 1.0 maps to the most positive representable | |
9032 | integer value, and @r{-1.0} maps to the most negative representable | |
c7b31271 DH |
9033 | integer value. If the internal value is outside the range @r{[-1,1]}, |
9034 | the corresponding integer return value is undefined. The initial value | |
b002944d AW |
9035 | is (0, 0, 0, 1). |
9036 | ||
9037 | @item @code{GL_EMISSION} | |
9038 | @var{params} returns four integer or floating-point values representing | |
c7b31271 | 9039 | the emitted light intensity of the material. Integer values, when |
b002944d AW |
9040 | requested, are linearly mapped from the internal floating-point |
9041 | representation such that 1.0 maps to the most positive representable | |
9042 | integer value, and @r{-1.0} maps to the most negative representable | |
c7b31271 DH |
9043 | integer value. If the internal value is outside the range @r{[-1,1]}, |
9044 | the corresponding integer return value is undefined. The initial value | |
b002944d AW |
9045 | is (0, 0, 0, 1). |
9046 | ||
9047 | @item @code{GL_SHININESS} | |
9048 | @var{params} returns one integer or floating-point value representing | |
c7b31271 | 9049 | the specular exponent of the material. Integer values, when requested, |
b002944d | 9050 | are computed by rounding the internal floating-point value to the |
c7b31271 | 9051 | nearest integer value. The initial value is 0. |
b002944d AW |
9052 | |
9053 | @item @code{GL_COLOR_INDEXES} | |
9054 | @var{params} returns three integer or floating-point values representing | |
c7b31271 DH |
9055 | the ambient, diffuse, and specular indices of the material. These |
9056 | indices are used only for color index lighting. (All the other | |
b002944d AW |
9057 | parameters are used only for RGBA lighting.) Integer values, when |
9058 | requested, are computed by rounding the internal floating-point values | |
9059 | to the nearest integer values. | |
9060 | ||
9061 | @end table | |
9062 | ||
9063 | @code{GL_INVALID_ENUM} is generated if @var{face} or @var{pname} is not | |
9064 | an accepted value. | |
9065 | ||
9066 | @code{GL_INVALID_OPERATION} is generated if @code{glGetMaterial} is | |
9067 | executed between the execution of @code{glBegin} and the corresponding | |
9068 | execution of @code{glEnd}. | |
9069 | ||
9070 | @end deftypefun | |
9071 | ||
9072 | @deftypefun void glGetMinmaxParameterfv target pname params | |
9073 | @deftypefunx void glGetMinmaxParameteriv target pname params | |
9074 | Get minmax parameters. | |
9075 | ||
9076 | @table @asis | |
9077 | @item @var{target} | |
9078 | Must be @code{GL_MINMAX}. | |
9079 | ||
9080 | @item @var{pname} | |
c7b31271 DH |
9081 | The parameter to be retrieved. Must be one of @code{GL_MINMAX_FORMAT} |
9082 | or @code{GL_MINMAX_SINK}. | |
b002944d AW |
9083 | |
9084 | @item @var{params} | |
9085 | A pointer to storage for the retrieved parameters. | |
9086 | ||
9087 | @end table | |
9088 | ||
9089 | @code{glGetMinmaxParameter} retrieves parameters for the current minmax | |
9090 | table by setting @var{pname} to one of the following values: | |
9091 | ||
9092 | ||
9093 | ||
9094 | @table @asis | |
9095 | @item @strong{Parameter} | |
9096 | @strong{Description} | |
9097 | ||
9098 | @item @code{GL_MINMAX_FORMAT} | |
9099 | Internal format of minmax table | |
9100 | ||
9101 | @item @code{GL_MINMAX_SINK} | |
9102 | Value of the @var{sink} parameter | |
9103 | ||
9104 | @end table | |
9105 | ||
9106 | ||
9107 | ||
9108 | @code{GL_INVALID_ENUM} is generated if @var{target} is not | |
9109 | @code{GL_MINMAX}. | |
9110 | ||
9111 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not one of the | |
9112 | allowable values. | |
9113 | ||
9114 | @code{GL_INVALID_OPERATION} is generated if @code{glGetMinmaxParameter} | |
9115 | is executed between the execution of @code{glBegin} and the | |
9116 | corresponding execution of @code{glEnd}. | |
9117 | ||
9118 | @end deftypefun | |
9119 | ||
9120 | @deftypefun void glGetMinmax target reset format types values | |
9121 | Get minimum and maximum pixel values. | |
9122 | ||
9123 | @table @asis | |
9124 | @item @var{target} | |
9125 | Must be @code{GL_MINMAX}. | |
9126 | ||
9127 | @item @var{reset} | |
9128 | If @code{GL_TRUE}, all entries in the minmax table that are actually | |
c7b31271 | 9129 | returned are reset to their initial values. (Other entries are |
b002944d AW |
9130 | unaltered.) If @code{GL_FALSE}, the minmax table is unaltered. |
9131 | ||
9132 | @item @var{format} | |
c7b31271 | 9133 | The format of the data to be returned in @var{values}. Must be one of |
b002944d AW |
9134 | @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, |
9135 | @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, | |
9136 | @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA}. | |
9137 | ||
9138 | @item @var{types} | |
c7b31271 | 9139 | The type of the data to be returned in @var{values}. Symbolic constants |
b002944d AW |
9140 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
9141 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
9142 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
9143 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
9144 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
9145 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
9146 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
9147 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
9148 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
9149 | ||
9150 | @item @var{values} | |
9151 | A pointer to storage for the returned values. | |
9152 | ||
9153 | @end table | |
9154 | ||
9155 | @code{glGetMinmax} returns the accumulated minimum and maximum pixel | |
9156 | values (computed on a per-component basis) in a one-dimensional image of | |
c7b31271 DH |
9157 | width 2. The first set of return values are the minima, and the second |
9158 | set of return values are the maxima. The format of the return values is | |
bb894c9d | 9159 | determined by @var{format}, and their type is determined by @var{types}. |
8925f36f AW |
9160 | |
9161 | If a non-zero named buffer object is bound to the | |
9162 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while | |
9163 | minimum and maximum pixel values are requested, @var{values} is treated | |
9164 | as a byte offset into the buffer object's data store. | |
9165 | ||
9166 | No pixel transfer operations are performed on the return values, but | |
9167 | pixel storage modes that are applicable to one-dimensional images are | |
c7b31271 | 9168 | performed. Color components that are requested in the specified |
8925f36f | 9169 | @var{format}, but that are not included in the internal format of the |
c7b31271 | 9170 | minmax table, are returned as zero. The assignment of internal color |
8925f36f AW |
9171 | components to the components requested by @var{format} are as follows: |
9172 | ||
9173 | ||
9174 | ||
9175 | @table @asis | |
9176 | @item @strong{Internal Component} | |
9177 | @strong{Resulting Component} | |
9178 | ||
9179 | @item | |
9180 | Red | |
9181 | Red | |
9182 | ||
9183 | @item | |
9184 | Green | |
9185 | Green | |
9186 | ||
9187 | @item | |
9188 | Blue | |
9189 | Blue | |
9190 | ||
9191 | @item | |
9192 | Alpha | |
9193 | Alpha | |
9194 | ||
9195 | @item | |
9196 | Luminance | |
9197 | Red | |
9198 | ||
9199 | @end table | |
9200 | ||
9201 | If @var{reset} is @code{GL_TRUE}, the minmax table entries corresponding | |
c7b31271 | 9202 | to the return values are reset to their initial values. Minimum and |
8925f36f AW |
9203 | maximum values that are not returned are not modified, even if |
9204 | @var{reset} is @code{GL_TRUE}. | |
9205 | ||
8925f36f AW |
9206 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
9207 | @code{GL_MINMAX}. | |
9208 | ||
9209 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
9210 | allowable values. | |
9211 | ||
9212 | @code{GL_INVALID_ENUM} is generated if @var{types} is not one of the | |
9213 | allowable values. | |
9214 | ||
9215 | @code{GL_INVALID_OPERATION} is generated if @var{types} is one of | |
9216 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
9217 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
9218 | and @var{format} is not @code{GL_RGB}. | |
9219 | ||
9220 | @code{GL_INVALID_OPERATION} is generated if @var{types} is one of | |
9221 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
9222 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
9223 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
9224 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
9225 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
9226 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
9227 | ||
9228 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9229 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
9230 | object's data store is currently mapped. | |
9231 | ||
9232 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9233 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
9234 | would be packed to the buffer object such that the memory writes | |
9235 | required would exceed the data store size. | |
9236 | ||
9237 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9238 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{values} | |
9239 | is not evenly divisible into the number of bytes needed to store in | |
9240 | memory a datum indicated by @var{type}. | |
9241 | ||
9242 | @code{GL_INVALID_OPERATION} is generated if @code{glGetMinmax} is | |
9243 | executed between the execution of @code{glBegin} and the corresponding | |
9244 | execution of @code{glEnd}. | |
9245 | ||
bb894c9d | 9246 | @end deftypefun |
8925f36f | 9247 | |
b002944d AW |
9248 | @deftypefun void glGetPixelMapfv map data |
9249 | @deftypefunx void glGetPixelMapuiv map data | |
d172eed9 | 9250 | @deftypefunx void glGetPixelMapusv map data |
b002944d AW |
9251 | Return the specified pixel map. |
9252 | ||
9253 | @table @asis | |
9254 | @item @var{map} | |
c7b31271 | 9255 | Specifies the name of the pixel map to return. Accepted values are |
b002944d AW |
9256 | @code{GL_PIXEL_MAP_I_TO_I}, @code{GL_PIXEL_MAP_S_TO_S}, |
9257 | @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G}, | |
9258 | @code{GL_PIXEL_MAP_I_TO_B}, @code{GL_PIXEL_MAP_I_TO_A}, | |
9259 | @code{GL_PIXEL_MAP_R_TO_R}, @code{GL_PIXEL_MAP_G_TO_G}, | |
9260 | @code{GL_PIXEL_MAP_B_TO_B}, and @code{GL_PIXEL_MAP_A_TO_A}. | |
9261 | ||
9262 | @item @var{data} | |
9263 | Returns the pixel map contents. | |
9264 | ||
9265 | @end table | |
9266 | ||
9267 | See the @code{glPixelMap} reference page for a description of the | |
c7b31271 | 9268 | acceptable values for the @var{map} parameter. @code{glGetPixelMap} |
b002944d | 9269 | returns in @var{data} the contents of the pixel map specified in |
c7b31271 | 9270 | @var{map}. Pixel maps are used during the execution of |
b002944d AW |
9271 | @code{glReadPixels}, @code{glDrawPixels}, @code{glCopyPixels}, |
9272 | @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D}, | |
9273 | @code{glTexSubImage1D}, @code{glTexSubImage2D}, @code{glTexSubImage3D}, | |
9274 | @code{glCopyTexImage1D}, @code{glCopyTexImage2D}, | |
9275 | @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D}, and | |
c7b31271 DH |
9276 | @code{glCopyTexSubImage3D}. to map color indices, stencil indices, |
9277 | color components, and depth components to other values. | |
b002944d AW |
9278 | |
9279 | If a non-zero named buffer object is bound to the | |
9280 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
9281 | pixel map is requested, @var{data} is treated as a byte offset into the | |
9282 | buffer object's data store. | |
9283 | ||
9284 | Unsigned integer values, if requested, are linearly mapped from the | |
9285 | internal fixed or floating-point representation such that 1.0 maps to | |
c7b31271 | 9286 | the largest representable integer value, and 0.0 maps to 0. Return |
b002944d AW |
9287 | unsigned integer values are undefined if the map value was not in the |
9288 | range [0,1]. | |
9289 | ||
9290 | To determine the required size of @var{map}, call @code{glGet} with the | |
9291 | appropriate symbolic constant. | |
9292 | ||
9293 | @code{GL_INVALID_ENUM} is generated if @var{map} is not an accepted | |
9294 | value. | |
9295 | ||
9296 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9297 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
9298 | object's data store is currently mapped. | |
9299 | ||
9300 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9301 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
9302 | would be packed to the buffer object such that the memory writes | |
9303 | required would exceed the data store size. | |
9304 | ||
9305 | @code{GL_INVALID_OPERATION} is generated by @code{glGetPixelMapfv} if a | |
9306 | non-zero buffer object name is bound to the @code{GL_PIXEL_PACK_BUFFER} | |
9307 | target and @var{data} is not evenly divisible into the number of bytes | |
9308 | needed to store in memory a GLfloat datum. | |
9309 | ||
9310 | @code{GL_INVALID_OPERATION} is generated by @code{glGetPixelMapuiv} if a | |
9311 | non-zero buffer object name is bound to the @code{GL_PIXEL_PACK_BUFFER} | |
9312 | target and @var{data} is not evenly divisible into the number of bytes | |
9313 | needed to store in memory a GLuint datum. | |
9314 | ||
9315 | @code{GL_INVALID_OPERATION} is generated by @code{glGetPixelMapusv} if a | |
9316 | non-zero buffer object name is bound to the @code{GL_PIXEL_PACK_BUFFER} | |
9317 | target and @var{data} is not evenly divisible into the number of bytes | |
9318 | needed to store in memory a GLushort datum. | |
9319 | ||
9320 | @code{GL_INVALID_OPERATION} is generated if @code{glGetPixelMap} is | |
9321 | executed between the execution of @code{glBegin} and the corresponding | |
9322 | execution of @code{glEnd}. | |
9323 | ||
9324 | @end deftypefun | |
9325 | ||
9326 | @deftypefun void glGetPointerv pname params | |
9327 | Return the address of the specified pointer. | |
9328 | ||
9329 | @table @asis | |
9330 | @item @var{pname} | |
c7b31271 DH |
9331 | Specifies the array or buffer pointer to be returned. Symbolic |
9332 | constants @code{GL_COLOR_ARRAY_POINTER}, | |
9333 | @code{GL_EDGE_FLAG_ARRAY_POINTER}, @code{GL_FOG_COORD_ARRAY_POINTER}, | |
9334 | @code{GL_FEEDBACK_BUFFER_POINTER}, @code{GL_INDEX_ARRAY_POINTER}, | |
9335 | @code{GL_NORMAL_ARRAY_POINTER}, @code{GL_SECONDARY_COLOR_ARRAY_POINTER}, | |
b002944d AW |
9336 | @code{GL_SELECTION_BUFFER_POINTER}, |
9337 | @code{GL_TEXTURE_COORD_ARRAY_POINTER}, or @code{GL_VERTEX_ARRAY_POINTER} | |
9338 | are accepted. | |
9339 | ||
9340 | @item @var{params} | |
9341 | Returns the pointer value specified by @var{pname}. | |
9342 | ||
9343 | @end table | |
9344 | ||
c7b31271 | 9345 | @code{glGetPointerv} returns pointer information. @var{pname} is a |
b002944d AW |
9346 | symbolic constant indicating the pointer to be returned, and |
9347 | @var{params} is a pointer to a location in which to place the returned | |
9348 | data. | |
9349 | ||
9350 | For all @var{pname} arguments except @code{GL_FEEDBACK_BUFFER_POINTER} | |
9351 | and @code{GL_SELECTION_BUFFER_POINTER}, if a non-zero named buffer | |
9352 | object was bound to the @code{GL_ARRAY_BUFFER} target (see | |
9353 | @code{glBindBuffer}) when the desired pointer was previously specified, | |
9354 | the pointer returned is a byte offset into the buffer object's data | |
c7b31271 | 9355 | store. Buffer objects are only available in OpenGL versions 1.5 and |
b002944d AW |
9356 | greater. |
9357 | ||
9358 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted | |
9359 | value. | |
9360 | ||
9361 | @end deftypefun | |
9362 | ||
bb894c9d | 9363 | @deftypefun void glGetPolygonStipple pattern |
3c9b6116 AW |
9364 | Return the polygon stipple pattern. |
9365 | ||
8925f36f AW |
9366 | @table @asis |
9367 | @item @var{pattern} | |
c7b31271 | 9368 | Returns the stipple pattern. The initial value is all 1's. |
8925f36f AW |
9369 | |
9370 | @end table | |
9371 | ||
3c9b6116 | 9372 | @code{glGetPolygonStipple} returns to @var{pattern} a @r{32×32} polygon |
c7b31271 | 9373 | stipple pattern. The pattern is packed into memory as if |
8925f36f AW |
9374 | @code{glReadPixels} with both @var{height} and @var{width} of 32, |
9375 | @var{type} of @code{GL_BITMAP}, and @var{format} of | |
9376 | @code{GL_COLOR_INDEX} were called, and the stipple pattern were stored | |
c7b31271 DH |
9377 | in an internal @r{32×32} color index buffer. Unlike |
9378 | @code{glReadPixels}, however, pixel transfer operations (shift, offset, | |
9379 | pixel map) are not applied to the returned stipple image. | |
8925f36f AW |
9380 | |
9381 | If a non-zero named buffer object is bound to the | |
9382 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
9383 | polygon stipple pattern is requested, @var{pattern} is treated as a byte | |
9384 | offset into the buffer object's data store. | |
9385 | ||
8925f36f AW |
9386 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object |
9387 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
9388 | object's data store is currently mapped. | |
9389 | ||
9390 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9391 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
9392 | would be packed to the buffer object such that the memory writes | |
9393 | required would exceed the data store size. | |
9394 | ||
9395 | @code{GL_INVALID_OPERATION} is generated if @code{glGetPolygonStipple} | |
9396 | is executed between the execution of @code{glBegin} and the | |
9397 | corresponding execution of @code{glEnd}. | |
9398 | ||
bb894c9d | 9399 | @end deftypefun |
8925f36f | 9400 | |
bb894c9d | 9401 | @deftypefun void glGetProgramInfoLog program maxLength length infoLog |
3c9b6116 AW |
9402 | Returns the information log for a program object. |
9403 | ||
8925f36f AW |
9404 | @table @asis |
9405 | @item @var{program} | |
9406 | Specifies the program object whose information log is to be queried. | |
9407 | ||
9408 | @item @var{maxLength} | |
9409 | Specifies the size of the character buffer for storing the returned | |
9410 | information log. | |
9411 | ||
9412 | @item @var{length} | |
9413 | Returns the length of the string returned in @var{infoLog} (excluding | |
9414 | the null terminator). | |
9415 | ||
9416 | @item @var{infoLog} | |
9417 | Specifies an array of characters that is used to return the information | |
9418 | log. | |
9419 | ||
9420 | @end table | |
9421 | ||
8925f36f | 9422 | @code{glGetProgramInfoLog} returns the information log for the specified |
c7b31271 DH |
9423 | program object. The information log for a program object is modified |
9424 | when the program object is linked or validated. The string that is | |
8925f36f AW |
9425 | returned will be null terminated. |
9426 | ||
9427 | @code{glGetProgramInfoLog} returns in @var{infoLog} as much of the | |
9428 | information log as it can, up to a maximum of @var{maxLength} | |
c7b31271 DH |
9429 | characters. The number of characters actually returned, excluding the |
9430 | null termination character, is specified by @var{length}. If the length | |
8925f36f | 9431 | of the returned string is not required, a value of @code{NULL} can be |
c7b31271 | 9432 | passed in the @var{length} argument. The size of the buffer required to |
8925f36f AW |
9433 | store the returned information log can be obtained by calling |
9434 | @code{glGetProgram} with the value @code{GL_INFO_LOG_LENGTH}. | |
9435 | ||
9436 | The information log for a program object is either an empty string, or a | |
9437 | string containing information about the last link operation, or a string | |
c7b31271 | 9438 | containing information about the last validation operation. It may |
8925f36f AW |
9439 | contain diagnostic messages, warning messages, and other information. |
9440 | When a program object is created, its information log will be a string | |
9441 | of length 0. | |
9442 | ||
8925f36f AW |
9443 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
9444 | generated by OpenGL. | |
9445 | ||
9446 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
9447 | program object. | |
9448 | ||
9449 | @code{GL_INVALID_VALUE} is generated if @var{maxLength} is less than 0. | |
9450 | ||
9451 | @code{GL_INVALID_OPERATION} is generated if @code{glGetProgramInfoLog} | |
9452 | is executed between the execution of @code{glBegin} and the | |
9453 | corresponding execution of @code{glEnd}. | |
9454 | ||
bb894c9d | 9455 | @end deftypefun |
8925f36f | 9456 | |
b002944d AW |
9457 | @deftypefun void glGetProgramiv program pname params |
9458 | Returns a parameter from a program object. | |
3c9b6116 | 9459 | |
8925f36f | 9460 | @table @asis |
b002944d AW |
9461 | @item @var{program} |
9462 | Specifies the program object to be queried. | |
8925f36f | 9463 | |
b002944d | 9464 | @item @var{pname} |
c7b31271 | 9465 | Specifies the object parameter. Accepted symbolic names are |
b002944d AW |
9466 | @code{GL_DELETE_STATUS}, @code{GL_LINK_STATUS}, |
9467 | @code{GL_VALIDATE_STATUS}, @code{GL_INFO_LOG_LENGTH}, | |
9468 | @code{GL_ATTACHED_SHADERS}, @code{GL_ACTIVE_ATTRIBUTES}, | |
9469 | @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH}, @code{GL_ACTIVE_UNIFORMS}, | |
9470 | @code{GL_ACTIVE_UNIFORM_MAX_LENGTH}. | |
8925f36f | 9471 | |
b002944d AW |
9472 | @item @var{params} |
9473 | Returns the requested object parameter. | |
8925f36f | 9474 | |
b002944d | 9475 | @end table |
8925f36f | 9476 | |
b002944d | 9477 | @code{glGetProgram} returns in @var{params} the value of a parameter for |
c7b31271 | 9478 | a specific program object. The following parameters are defined: |
8925f36f | 9479 | |
b002944d AW |
9480 | @table @asis |
9481 | @item @code{GL_DELETE_STATUS} | |
8925f36f | 9482 | |
8925f36f | 9483 | |
b002944d AW |
9484 | @var{params} returns @code{GL_TRUE} if @var{program} is currently |
9485 | flagged for deletion, and @code{GL_FALSE} otherwise. | |
9486 | ||
9487 | @item @code{GL_LINK_STATUS} | |
9488 | ||
9489 | ||
9490 | @var{params} returns @code{GL_TRUE} if the last link operation on | |
9491 | @var{program} was successful, and @code{GL_FALSE} otherwise. | |
9492 | ||
9493 | @item @code{GL_VALIDATE_STATUS} | |
9494 | ||
9495 | ||
9496 | @var{params} returns @code{GL_TRUE} or if the last validation operation | |
9497 | on @var{program} was successful, and @code{GL_FALSE} otherwise. | |
9498 | ||
9499 | @item @code{GL_INFO_LOG_LENGTH} | |
9500 | ||
9501 | ||
9502 | @var{params} returns the number of characters in the information log for | |
9503 | @var{program} including the null termination character (i.e., the size | |
c7b31271 | 9504 | of the character buffer required to store the information log). If |
b002944d AW |
9505 | @var{program} has no information log, a value of 0 is returned. |
9506 | ||
9507 | @item @code{GL_ATTACHED_SHADERS} | |
9508 | ||
9509 | ||
9510 | @var{params} returns the number of shader objects attached to | |
9511 | @var{program}. | |
9512 | ||
9513 | @item @code{GL_ACTIVE_ATTRIBUTES} | |
9514 | ||
9515 | ||
9516 | @var{params} returns the number of active attribute variables for | |
9517 | @var{program}. | |
9518 | ||
9519 | @item @code{GL_ACTIVE_ATTRIBUTE_MAX_LENGTH} | |
9520 | ||
9521 | ||
9522 | @var{params} returns the length of the longest active attribute name for | |
9523 | @var{program}, including the null termination character (i.e., the size | |
9524 | of the character buffer required to store the longest attribute name). | |
9525 | If no active attributes exist, 0 is returned. | |
9526 | ||
9527 | @item @code{GL_ACTIVE_UNIFORMS} | |
9528 | ||
9529 | ||
9530 | @var{params} returns the number of active uniform variables for | |
9531 | @var{program}. | |
9532 | ||
9533 | @item @code{GL_ACTIVE_UNIFORM_MAX_LENGTH} | |
9534 | ||
9535 | ||
9536 | @var{params} returns the length of the longest active uniform variable | |
9537 | name for @var{program}, including the null termination character (i.e., | |
9538 | the size of the character buffer required to store the longest uniform | |
c7b31271 | 9539 | variable name). If no active uniform variables exist, 0 is returned. |
b002944d AW |
9540 | |
9541 | @end table | |
9542 | ||
9543 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value | |
9544 | generated by OpenGL. | |
9545 | ||
9546 | @code{GL_INVALID_OPERATION} is generated if @var{program} does not refer | |
9547 | to a program object. | |
9548 | ||
9549 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted | |
9550 | value. | |
9551 | ||
9552 | @code{GL_INVALID_OPERATION} is generated if @code{glGetProgram} is | |
9553 | executed between the execution of @code{glBegin} and the corresponding | |
9554 | execution of @code{glEnd}. | |
9555 | ||
9556 | @end deftypefun | |
9557 | ||
9558 | @deftypefun void glGetQueryiv target pname params | |
9559 | Return parameters of a query object target. | |
9560 | ||
9561 | @table @asis | |
9562 | @item @var{target} | |
c7b31271 | 9563 | Specifies a query object target. Must be @code{GL_SAMPLES_PASSED}. |
b002944d AW |
9564 | |
9565 | @item @var{pname} | |
c7b31271 | 9566 | Specifies the symbolic name of a query object target parameter. Accepted |
b002944d AW |
9567 | values are @code{GL_CURRENT_QUERY} or @code{GL_QUERY_COUNTER_BITS}. |
9568 | ||
9569 | @item @var{params} | |
9570 | Returns the requested data. | |
9571 | ||
9572 | @end table | |
9573 | ||
9574 | @code{glGetQueryiv} returns in @var{params} a selected parameter of the | |
9575 | query object target specified by @var{target}. | |
9576 | ||
c7b31271 | 9577 | @var{pname} names a specific query object target parameter. When |
b002944d AW |
9578 | @var{target} is @code{GL_SAMPLES_PASSED}, @var{pname} can be as follows: |
9579 | ||
9580 | @table @asis | |
9581 | @item @code{GL_CURRENT_QUERY} | |
9582 | @var{params} returns the name of the currently active occlusion query | |
c7b31271 | 9583 | object. If no occlusion query is active, 0 is returned. The initial |
b002944d AW |
9584 | value is 0. |
9585 | ||
9586 | @item @code{GL_QUERY_COUNTER_BITS} | |
9587 | @var{params} returns the number of bits in the query counter used to | |
c7b31271 | 9588 | accumulate passing samples. If the number of bits returned is 0, the |
b002944d AW |
9589 | implementation does not support a query counter, and the results |
9590 | obtained from @code{glGetQueryObject} are useless. | |
9591 | ||
9592 | @end table | |
9593 | ||
9594 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
9595 | not an accepted value. | |
9596 | ||
9597 | @code{GL_INVALID_OPERATION} is generated if @code{glGetQueryiv} is | |
9598 | executed between the execution of @code{glBegin} and the corresponding | |
9599 | execution of @code{glEnd}. | |
9600 | ||
9601 | @end deftypefun | |
9602 | ||
9603 | @deftypefun void glGetQueryObjectiv id pname params | |
9604 | @deftypefunx void glGetQueryObjectuiv id pname params | |
9605 | Return parameters of a query object. | |
9606 | ||
9607 | @table @asis | |
9608 | @item @var{id} | |
9609 | Specifies the name of a query object. | |
9610 | ||
9611 | @item @var{pname} | |
c7b31271 DH |
9612 | Specifies the symbolic name of a query object parameter. Accepted |
9613 | values are @code{GL_QUERY_RESULT} or @code{GL_QUERY_RESULT_AVAILABLE}. | |
b002944d AW |
9614 | |
9615 | @item @var{params} | |
9616 | Returns the requested data. | |
9617 | ||
9618 | @end table | |
9619 | ||
9620 | @code{glGetQueryObject} returns in @var{params} a selected parameter of | |
9621 | the query object specified by @var{id}. | |
9622 | ||
c7b31271 | 9623 | @var{pname} names a specific query object parameter. @var{pname} can be |
b002944d AW |
9624 | as follows: |
9625 | ||
9626 | @table @asis | |
9627 | @item @code{GL_QUERY_RESULT} | |
9628 | @var{params} returns the value of the query object's passed samples | |
c7b31271 | 9629 | counter. The initial value is 0. |
b002944d AW |
9630 | |
9631 | @item @code{GL_QUERY_RESULT_AVAILABLE} | |
9632 | @var{params} returns whether the passed samples counter is immediately | |
c7b31271 DH |
9633 | available. If a delay would occur waiting for the query result, |
9634 | @code{GL_FALSE} is returned. Otherwise, @code{GL_TRUE} is returned, | |
b002944d AW |
9635 | which also indicates that the results of all previous queries are |
9636 | available as well. | |
9637 | ||
9638 | @end table | |
9639 | ||
9640 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted | |
9641 | value. | |
9642 | ||
9643 | @code{GL_INVALID_OPERATION} is generated if @var{id} is not the name of | |
9644 | a query object. | |
9645 | ||
9646 | @code{GL_INVALID_OPERATION} is generated if @var{id} is the name of a | |
9647 | currently active query object. | |
9648 | ||
9649 | @code{GL_INVALID_OPERATION} is generated if @code{glGetQueryObject} is | |
9650 | executed between the execution of @code{glBegin} and the corresponding | |
9651 | execution of @code{glEnd}. | |
9652 | ||
9653 | @end deftypefun | |
9654 | ||
9655 | @deftypefun void glGetSeparableFilter target format type row column span | |
9656 | Get separable convolution filter kernel images. | |
9657 | ||
9658 | @table @asis | |
9659 | @item @var{target} | |
c7b31271 | 9660 | The separable filter to be retrieved. Must be @code{GL_SEPARABLE_2D}. |
b002944d AW |
9661 | |
9662 | @item @var{format} | |
c7b31271 | 9663 | Format of the output images. Must be one of @code{GL_RED}, |
b002944d AW |
9664 | @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, |
9665 | @code{GL_BGR}@code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, or | |
9666 | @code{GL_LUMINANCE_ALPHA}. | |
9667 | ||
9668 | @item @var{type} | |
c7b31271 | 9669 | Data type of components in the output images. Symbolic constants |
b002944d AW |
9670 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
9671 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
9672 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
9673 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
9674 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
9675 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
9676 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
9677 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
9678 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
9679 | ||
9680 | @item @var{row} | |
9681 | Pointer to storage for the row filter image. | |
9682 | ||
9683 | @item @var{column} | |
9684 | Pointer to storage for the column filter image. | |
9685 | ||
9686 | @item @var{span} | |
9687 | Pointer to storage for the span filter image (currently unused). | |
9688 | ||
9689 | @end table | |
9690 | ||
9691 | @code{glGetSeparableFilter} returns the two one-dimensional filter | |
c7b31271 | 9692 | kernel images for the current separable 2D convolution filter. The row |
b002944d AW |
9693 | image is placed in @var{row} and the column image is placed in |
9694 | @var{column} according to the specifications in @var{format} and | |
c7b31271 | 9695 | @var{type}. (In the current implementation, @var{span} is not affected |
b002944d AW |
9696 | in any way.) No pixel transfer operations are performed on the images, |
9697 | but the relevant pixel storage modes are applied. | |
8925f36f | 9698 | |
bb894c9d AW |
9699 | If a non-zero named buffer object is bound to the |
9700 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
9701 | separable convolution filter is requested, @var{row}, @var{column}, and | |
9702 | @var{span} are treated as a byte offset into the buffer object's data | |
9703 | store. | |
8925f36f | 9704 | |
bb894c9d | 9705 | Color components that are present in @var{format} but not included in |
c7b31271 DH |
9706 | the internal format of the filters are returned as zero. The |
9707 | assignments of internal color components to the components of | |
9708 | @var{format} are as follows: | |
8925f36f | 9709 | |
8925f36f AW |
9710 | |
9711 | ||
bb894c9d AW |
9712 | @table @asis |
9713 | @item @strong{Internal Component} | |
9714 | @strong{Resulting Component} | |
8925f36f AW |
9715 | |
9716 | @item | |
9717 | Red | |
9718 | Red | |
9719 | ||
9720 | @item | |
9721 | Green | |
9722 | Green | |
9723 | ||
9724 | @item | |
9725 | Blue | |
9726 | Blue | |
9727 | ||
9728 | @item | |
9729 | Alpha | |
9730 | Alpha | |
9731 | ||
9732 | @item | |
9733 | Luminance | |
9734 | Red | |
9735 | ||
9736 | @item | |
9737 | Intensity | |
9738 | Red | |
9739 | ||
9740 | @end table | |
9741 | ||
9742 | ||
9743 | ||
8925f36f AW |
9744 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
9745 | @code{GL_SEPARABLE_2D}. | |
9746 | ||
9747 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
9748 | allowable values. | |
9749 | ||
9750 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
9751 | allowable values. | |
9752 | ||
9753 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
9754 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
9755 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
9756 | and @var{format} is not @code{GL_RGB}. | |
9757 | ||
9758 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
9759 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
9760 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
9761 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
9762 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
9763 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
9764 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
9765 | ||
9766 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9767 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
9768 | object's data store is currently mapped. | |
9769 | ||
9770 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9771 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
9772 | would be packed to the buffer object such that the memory writes | |
9773 | required would exceed the data store size. | |
9774 | ||
9775 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
9776 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{row} or | |
9777 | @var{column} is not evenly divisible into the number of bytes needed to | |
9778 | store in memory a datum indicated by @var{type}. | |
9779 | ||
9780 | @code{GL_INVALID_OPERATION} is generated if @code{glGetSeparableFilter} | |
9781 | is executed between the execution of @code{glBegin} and the | |
9782 | corresponding execution of @code{glEnd}. | |
9783 | ||
bb894c9d | 9784 | @end deftypefun |
8925f36f | 9785 | |
bb894c9d | 9786 | @deftypefun void glGetShaderInfoLog shader maxLength length infoLog |
3c9b6116 AW |
9787 | Returns the information log for a shader object. |
9788 | ||
8925f36f AW |
9789 | @table @asis |
9790 | @item @var{shader} | |
9791 | Specifies the shader object whose information log is to be queried. | |
9792 | ||
9793 | @item @var{maxLength} | |
9794 | Specifies the size of the character buffer for storing the returned | |
9795 | information log. | |
9796 | ||
9797 | @item @var{length} | |
9798 | Returns the length of the string returned in @var{infoLog} (excluding | |
9799 | the null terminator). | |
9800 | ||
9801 | @item @var{infoLog} | |
9802 | Specifies an array of characters that is used to return the information | |
9803 | log. | |
9804 | ||
9805 | @end table | |
9806 | ||
8925f36f | 9807 | @code{glGetShaderInfoLog} returns the information log for the specified |
c7b31271 DH |
9808 | shader object. The information log for a shader object is modified when |
9809 | the shader is compiled. The string that is returned will be null | |
8925f36f AW |
9810 | terminated. |
9811 | ||
9812 | @code{glGetShaderInfoLog} returns in @var{infoLog} as much of the | |
9813 | information log as it can, up to a maximum of @var{maxLength} | |
c7b31271 DH |
9814 | characters. The number of characters actually returned, excluding the |
9815 | null termination character, is specified by @var{length}. If the length | |
8925f36f | 9816 | of the returned string is not required, a value of @code{NULL} can be |
c7b31271 | 9817 | passed in the @var{length} argument. The size of the buffer required to |
8925f36f AW |
9818 | store the returned information log can be obtained by calling |
9819 | @code{glGetShader} with the value @code{GL_INFO_LOG_LENGTH}. | |
9820 | ||
9821 | The information log for a shader object is a string that may contain | |
9822 | diagnostic messages, warning messages, and other information about the | |
c7b31271 DH |
9823 | last compile operation. When a shader object is created, its |
9824 | information log will be a string of length 0. | |
8925f36f | 9825 | |
8925f36f AW |
9826 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
9827 | generated by OpenGL. | |
9828 | ||
9829 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
9830 | object. | |
9831 | ||
9832 | @code{GL_INVALID_VALUE} is generated if @var{maxLength} is less than 0. | |
9833 | ||
9834 | @code{GL_INVALID_OPERATION} is generated if @code{glGetShaderInfoLog} is | |
9835 | executed between the execution of @code{glBegin} and the corresponding | |
9836 | execution of @code{glEnd}. | |
9837 | ||
bb894c9d | 9838 | @end deftypefun |
8925f36f | 9839 | |
bb894c9d | 9840 | @deftypefun void glGetShaderSource shader bufSize length source |
3c9b6116 AW |
9841 | Returns the source code string from a shader object. |
9842 | ||
8925f36f AW |
9843 | @table @asis |
9844 | @item @var{shader} | |
9845 | Specifies the shader object to be queried. | |
9846 | ||
9847 | @item @var{bufSize} | |
9848 | Specifies the size of the character buffer for storing the returned | |
9849 | source code string. | |
9850 | ||
9851 | @item @var{length} | |
9852 | Returns the length of the string returned in @var{source} (excluding the | |
9853 | null terminator). | |
9854 | ||
9855 | @item @var{source} | |
9856 | Specifies an array of characters that is used to return the source code | |
9857 | string. | |
9858 | ||
9859 | @end table | |
9860 | ||
8925f36f | 9861 | @code{glGetShaderSource} returns the concatenation of the source code |
c7b31271 | 9862 | strings from the shader object specified by @var{shader}. The source |
8925f36f | 9863 | code strings for a shader object are the result of a previous call to |
c7b31271 | 9864 | @code{glShaderSource}. The string returned by the function will be null |
8925f36f AW |
9865 | terminated. |
9866 | ||
9867 | @code{glGetShaderSource} returns in @var{source} as much of the source | |
c7b31271 | 9868 | code string as it can, up to a maximum of @var{bufSize} characters. The |
8925f36f | 9869 | number of characters actually returned, excluding the null termination |
c7b31271 | 9870 | character, is specified by @var{length}. If the length of the returned |
8925f36f | 9871 | string is not required, a value of @code{NULL} can be passed in the |
c7b31271 | 9872 | @var{length} argument. The size of the buffer required to store the |
8925f36f AW |
9873 | returned source code string can be obtained by calling |
9874 | @code{glGetShader} with the value @code{GL_SHADER_SOURCE_LENGTH}. | |
9875 | ||
8925f36f AW |
9876 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
9877 | generated by OpenGL. | |
9878 | ||
9879 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
9880 | object. | |
9881 | ||
9882 | @code{GL_INVALID_VALUE} is generated if @var{bufSize} is less than 0. | |
9883 | ||
9884 | @code{GL_INVALID_OPERATION} is generated if @code{glGetShaderSource} is | |
9885 | executed between the execution of @code{glBegin} and the corresponding | |
9886 | execution of @code{glEnd}. | |
9887 | ||
bb894c9d | 9888 | @end deftypefun |
8925f36f | 9889 | |
b002944d AW |
9890 | @deftypefun void glGetShaderiv shader pname params |
9891 | Returns a parameter from a shader object. | |
9892 | ||
9893 | @table @asis | |
9894 | @item @var{shader} | |
9895 | Specifies the shader object to be queried. | |
9896 | ||
9897 | @item @var{pname} | |
c7b31271 | 9898 | Specifies the object parameter. Accepted symbolic names are |
b002944d AW |
9899 | @code{GL_SHADER_TYPE}, @code{GL_DELETE_STATUS}, |
9900 | @code{GL_COMPILE_STATUS}, @code{GL_INFO_LOG_LENGTH}, | |
9901 | @code{GL_SHADER_SOURCE_LENGTH}. | |
9902 | ||
9903 | @item @var{params} | |
9904 | Returns the requested object parameter. | |
9905 | ||
9906 | @end table | |
9907 | ||
9908 | @code{glGetShader} returns in @var{params} the value of a parameter for | |
c7b31271 | 9909 | a specific shader object. The following parameters are defined: |
b002944d AW |
9910 | |
9911 | @table @asis | |
9912 | @item @code{GL_SHADER_TYPE} | |
9913 | @var{params} returns @code{GL_VERTEX_SHADER} if @var{shader} is a vertex | |
9914 | shader object, and @code{GL_FRAGMENT_SHADER} if @var{shader} is a | |
9915 | fragment shader object. | |
9916 | ||
9917 | @item @code{GL_DELETE_STATUS} | |
9918 | @var{params} returns @code{GL_TRUE} if @var{shader} is currently flagged | |
9919 | for deletion, and @code{GL_FALSE} otherwise. | |
9920 | ||
9921 | @item @code{GL_COMPILE_STATUS} | |
9922 | @var{params} returns @code{GL_TRUE} if the last compile operation on | |
9923 | @var{shader} was successful, and @code{GL_FALSE} otherwise. | |
9924 | ||
9925 | @item @code{GL_INFO_LOG_LENGTH} | |
9926 | @var{params} returns the number of characters in the information log for | |
9927 | @var{shader} including the null termination character (i.e., the size of | |
c7b31271 | 9928 | the character buffer required to store the information log). If |
b002944d AW |
9929 | @var{shader} has no information log, a value of 0 is returned. |
9930 | ||
9931 | @item @code{GL_SHADER_SOURCE_LENGTH} | |
9932 | @var{params} returns the length of the concatenation of the source | |
9933 | strings that make up the shader source for the @var{shader}, including | |
c7b31271 DH |
9934 | the null termination character. (i.e., the size of the character buffer |
9935 | required to store the shader source). If no source code exists, 0 is | |
b002944d AW |
9936 | returned. |
9937 | ||
9938 | @end table | |
9939 | ||
9940 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value | |
9941 | generated by OpenGL. | |
9942 | ||
9943 | @code{GL_INVALID_OPERATION} is generated if @var{shader} does not refer | |
9944 | to a shader object. | |
9945 | ||
9946 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted | |
9947 | value. | |
9948 | ||
9949 | @code{GL_INVALID_OPERATION} is generated if @code{glGetShader} is | |
9950 | executed between the execution of @code{glBegin} and the corresponding | |
9951 | execution of @code{glEnd}. | |
9952 | ||
9953 | @end deftypefun | |
9954 | ||
00239761 | 9955 | @deftypefun const-GLubyte* glGetString name |
3c9b6116 AW |
9956 | Return a string describing the current GL connection. |
9957 | ||
8925f36f AW |
9958 | @table @asis |
9959 | @item @var{name} | |
9960 | Specifies a symbolic constant, one of @code{GL_VENDOR}, | |
9961 | @code{GL_RENDERER}, @code{GL_VERSION}, | |
9962 | @code{GL_SHADING_LANGUAGE_VERSION}, or @code{GL_EXTENSIONS}. | |
9963 | ||
9964 | @end table | |
9965 | ||
8925f36f | 9966 | @code{glGetString} returns a pointer to a static string describing some |
c7b31271 | 9967 | aspect of the current GL connection. @var{name} can be one of the |
8925f36f AW |
9968 | following: |
9969 | ||
9970 | @table @asis | |
9971 | @item @code{GL_VENDOR} | |
9972 | ||
9973 | ||
c7b31271 | 9974 | Returns the company responsible for this GL implementation. This name |
8925f36f AW |
9975 | does not change from release to release. |
9976 | ||
9977 | @item @code{GL_RENDERER} | |
9978 | ||
9979 | ||
c7b31271 DH |
9980 | Returns the name of the renderer. This name is typically specific to a |
9981 | particular configuration of a hardware platform. It does not change | |
9982 | from release to release. | |
8925f36f AW |
9983 | |
9984 | @item @code{GL_VERSION} | |
9985 | ||
9986 | ||
9987 | Returns a version or release number. | |
9988 | ||
9989 | @item @code{GL_SHADING_LANGUAGE_VERSION} | |
9990 | ||
9991 | ||
9992 | Returns a version or release number for the shading language. | |
9993 | ||
9994 | @item @code{GL_EXTENSIONS} | |
9995 | ||
9996 | ||
9997 | Returns a space-separated list of supported extensions to GL. | |
9998 | ||
9999 | @end table | |
10000 | ||
bb894c9d AW |
10001 | Because the GL does not include queries for the performance |
10002 | characteristics of an implementation, some applications are written to | |
10003 | recognize known platforms and modify their GL usage based on known | |
c7b31271 DH |
10004 | performance characteristics of these platforms. Strings |
10005 | @code{GL_VENDOR} and @code{GL_RENDERER} together uniquely specify a | |
10006 | platform. They do not change from release to release and should be used | |
10007 | by platform-recognition algorithms. | |
8925f36f | 10008 | |
b002944d | 10009 | Some applications want to make use of features that are not part of the |
c7b31271 DH |
10010 | standard GL. These features may be implemented as extensions to the |
10011 | standard GL. The @code{GL_EXTENSIONS} string is a space-separated list | |
10012 | of supported GL extensions. (Extension names never contain a space | |
b002944d AW |
10013 | character.) |
10014 | ||
10015 | The @code{GL_VERSION} and @code{GL_SHADING_LANGUAGE_VERSION} strings | |
c7b31271 DH |
10016 | begin with a version number. The version number uses one of these |
10017 | forms: | |
b002944d AW |
10018 | |
10019 | @var{major_number.minor_number}@var{major_number.minor_number.release_number} | |
10020 | ||
c7b31271 | 10021 | Vendor-specific information may follow the version number. Its format |
b002944d AW |
10022 | depends on the implementation, but a space always separates the version |
10023 | number and the vendor-specific information. | |
10024 | ||
10025 | All strings are null-terminated. | |
10026 | ||
10027 | @code{GL_INVALID_ENUM} is generated if @var{name} is not an accepted | |
10028 | value. | |
10029 | ||
10030 | @code{GL_INVALID_OPERATION} is generated if @code{glGetString} is | |
10031 | executed between the execution of @code{glBegin} and the corresponding | |
10032 | execution of @code{glEnd}. | |
10033 | ||
10034 | @end deftypefun | |
10035 | ||
10036 | @deftypefun void glGetTexEnvfv target pname params | |
10037 | @deftypefunx void glGetTexEnviv target pname params | |
10038 | Return texture environment parameters. | |
10039 | ||
10040 | @table @asis | |
10041 | @item @var{target} | |
c7b31271 | 10042 | Specifies a texture environment. May be @code{GL_TEXTURE_ENV}, |
b002944d AW |
10043 | @code{GL_TEXTURE_FILTER_CONTROL}, or @code{GL_POINT_SPRITE}. |
10044 | ||
10045 | @item @var{pname} | |
c7b31271 | 10046 | Specifies the symbolic name of a texture environment parameter. Accepted |
b002944d AW |
10047 | values are @code{GL_TEXTURE_ENV_MODE}, @code{GL_TEXTURE_ENV_COLOR}, |
10048 | @code{GL_TEXTURE_LOD_BIAS}, @code{GL_COMBINE_RGB}, | |
10049 | @code{GL_COMBINE_ALPHA}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, | |
10050 | @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, | |
10051 | @code{GL_SRC2_ALPHA}, @code{GL_OPERAND0_RGB}, @code{GL_OPERAND1_RGB}, | |
10052 | @code{GL_OPERAND2_RGB}, @code{GL_OPERAND0_ALPHA}, | |
10053 | @code{GL_OPERAND1_ALPHA}, @code{GL_OPERAND2_ALPHA}, @code{GL_RGB_SCALE}, | |
10054 | @code{GL_ALPHA_SCALE}, or @code{GL_COORD_REPLACE}. | |
10055 | ||
10056 | @item @var{params} | |
10057 | Returns the requested data. | |
10058 | ||
10059 | @end table | |
10060 | ||
10061 | @code{glGetTexEnv} returns in @var{params} selected values of a texture | |
c7b31271 | 10062 | environment that was specified with @code{glTexEnv}. @var{target} |
b002944d AW |
10063 | specifies a texture environment. |
10064 | ||
10065 | When @var{target} is @code{GL_TEXTURE_FILTER_CONTROL}, @var{pname} must | |
c7b31271 | 10066 | be @code{GL_TEXTURE_LOD_BIAS}. When @var{target} is |
b002944d AW |
10067 | @code{GL_POINT_SPRITE}, @var{pname} must be @code{GL_COORD_REPLACE}. |
10068 | When @var{target} is @code{GL_TEXTURE_ENV}, @var{pname} can be | |
10069 | @code{GL_TEXTURE_ENV_MODE}, @code{GL_TEXTURE_ENV_COLOR}, | |
10070 | @code{GL_COMBINE_RGB}, @code{GL_COMBINE_ALPHA}, @code{GL_RGB_SCALE}, | |
10071 | @code{GL_ALPHA_SCALE}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, | |
10072 | @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, or | |
10073 | @code{GL_SRC2_ALPHA}. | |
10074 | ||
10075 | @var{pname} names a specific texture environment parameter, as follows: | |
10076 | ||
10077 | @table @asis | |
10078 | @item @code{GL_TEXTURE_ENV_MODE} | |
10079 | @var{params} returns the single-valued texture environment mode, a | |
c7b31271 | 10080 | symbolic constant. The initial value is @code{GL_MODULATE}. |
b002944d AW |
10081 | |
10082 | @item @code{GL_TEXTURE_ENV_COLOR} | |
10083 | @var{params} returns four integer or floating-point values that are the | |
c7b31271 | 10084 | texture environment color. Integer values, when requested, are linearly |
b002944d AW |
10085 | mapped from the internal floating-point representation such that 1.0 |
10086 | maps to the most positive representable integer, and @r{-1.0} maps to | |
c7b31271 | 10087 | the most negative representable integer. The initial value is (0, 0, 0, |
b002944d AW |
10088 | 0). |
10089 | ||
10090 | @item @code{GL_TEXTURE_LOD_BIAS} | |
10091 | @var{params} returns a single floating-point value that is the texture | |
c7b31271 | 10092 | level-of-detail bias. The initial value is 0. |
b002944d AW |
10093 | |
10094 | @item @code{GL_COMBINE_RGB} | |
10095 | @var{params} returns a single symbolic constant value representing the | |
c7b31271 | 10096 | current RGB combine mode. The initial value is @code{GL_MODULATE}. |
b002944d AW |
10097 | |
10098 | @item @code{GL_COMBINE_ALPHA} | |
10099 | @var{params} returns a single symbolic constant value representing the | |
c7b31271 | 10100 | current alpha combine mode. The initial value is @code{GL_MODULATE}. |
b002944d AW |
10101 | |
10102 | @item @code{GL_SRC0_RGB} | |
10103 | @var{params} returns a single symbolic constant value representing the | |
c7b31271 | 10104 | texture combiner zero's RGB source. The initial value is |
b002944d AW |
10105 | @code{GL_TEXTURE}. |
10106 | ||
10107 | @item @code{GL_SRC1_RGB} | |
10108 | @var{params} returns a single symbolic constant value representing the | |
c7b31271 | 10109 | texture combiner one's RGB source. The initial value is |
b002944d AW |
10110 | @code{GL_PREVIOUS}. |
10111 | ||
10112 | @item @code{GL_SRC2_RGB} | |
10113 | @var{params} returns a single symbolic constant value representing the | |
c7b31271 | 10114 | texture combiner two's RGB source. The initial value is |
b002944d AW |
10115 | @code{GL_CONSTANT}. |
10116 | ||
10117 | @item @code{GL_SRC0_ALPHA} | |
10118 | @var{params} returns a single symbolic constant value representing the | |
c7b31271 | 10119 | texture combiner zero's alpha source. The initial value is |
b002944d AW |
10120 | @code{GL_TEXTURE}. |
10121 | ||
10122 | @item @code{GL_SRC1_ALPHA} | |
10123 | @var{params} returns a single symbolic constant value representing the | |
c7b31271 | 10124 | texture combiner one's alpha source. The initial value is |
b002944d AW |
10125 | @code{GL_PREVIOUS}. |
10126 | ||
10127 | @item @code{GL_SRC2_ALPHA} | |
10128 | @var{params} returns a single symbolic constant value representing the | |
c7b31271 | 10129 | texture combiner two's alpha source. The initial value is |
b002944d AW |
10130 | @code{GL_CONSTANT}. |
10131 | ||
10132 | @item @code{GL_OPERAND0_RGB} | |
10133 | @var{params} returns a single symbolic constant value representing the | |
c7b31271 | 10134 | texture combiner zero's RGB operand. The initial value is |
b002944d AW |
10135 | @code{GL_SRC_COLOR}. |
10136 | ||
10137 | @item @code{GL_OPERAND1_RGB} | |
10138 | @var{params} returns a single symbolic constant value representing the | |
c7b31271 | 10139 | texture combiner one's RGB operand. The initial value is |
b002944d AW |
10140 | @code{GL_SRC_COLOR}. |
10141 | ||
10142 | @item @code{GL_OPERAND2_RGB} | |
10143 | @var{params} returns a single symbolic constant value representing the | |
c7b31271 | 10144 | texture combiner two's RGB operand. The initial value is |
b002944d AW |
10145 | @code{GL_SRC_ALPHA}. |
10146 | ||
10147 | @item @code{GL_OPERAND0_ALPHA} | |
10148 | @var{params} returns a single symbolic constant value representing the | |
c7b31271 | 10149 | texture combiner zero's alpha operand. The initial value is |
b002944d AW |
10150 | @code{GL_SRC_ALPHA}. |
10151 | ||
10152 | @item @code{GL_OPERAND1_ALPHA} | |
10153 | @var{params} returns a single symbolic constant value representing the | |
c7b31271 | 10154 | texture combiner one's alpha operand. The initial value is |
b002944d AW |
10155 | @code{GL_SRC_ALPHA}. |
10156 | ||
10157 | @item @code{GL_OPERAND2_ALPHA} | |
10158 | @var{params} returns a single symbolic constant value representing the | |
c7b31271 | 10159 | texture combiner two's alpha operand. The initial value is |
b002944d AW |
10160 | @code{GL_SRC_ALPHA}. |
10161 | ||
10162 | @item @code{GL_RGB_SCALE} | |
10163 | @var{params} returns a single floating-point value representing the | |
c7b31271 | 10164 | current RGB texture combiner scaling factor. The initial value is 1.0. |
b002944d AW |
10165 | |
10166 | @item @code{GL_ALPHA_SCALE} | |
10167 | @var{params} returns a single floating-point value representing the | |
c7b31271 DH |
10168 | current alpha texture combiner scaling factor. The initial value is |
10169 | 1.0. | |
b002944d AW |
10170 | |
10171 | @item @code{GL_COORD_REPLACE} | |
10172 | @var{params} returns a single boolean value representing the current | |
c7b31271 | 10173 | point sprite texture coordinate replacement enable state. The initial |
b002944d AW |
10174 | value is @code{GL_FALSE}. |
10175 | ||
10176 | @end table | |
10177 | ||
10178 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
10179 | not an accepted value. | |
10180 | ||
10181 | @code{GL_INVALID_OPERATION} is generated if @code{glGetTexEnv} is | |
10182 | executed between the execution of @code{glBegin} and the corresponding | |
10183 | execution of @code{glEnd}. | |
10184 | ||
10185 | @end deftypefun | |
10186 | ||
d172eed9 AW |
10187 | @deftypefun void glGetTexGendv coord pname params |
10188 | @deftypefunx void glGetTexGenfv coord pname params | |
b002944d AW |
10189 | @deftypefunx void glGetTexGeniv coord pname params |
10190 | Return texture coordinate generation parameters. | |
10191 | ||
10192 | @table @asis | |
10193 | @item @var{coord} | |
c7b31271 | 10194 | Specifies a texture coordinate. Must be @code{GL_S}, @code{GL_T}, |
b002944d AW |
10195 | @code{GL_R}, or @code{GL_Q}. |
10196 | ||
10197 | @item @var{pname} | |
c7b31271 | 10198 | Specifies the symbolic name of the value(s) to be returned. Must be |
b002944d AW |
10199 | either @code{GL_TEXTURE_GEN_MODE} or the name of one of the texture |
10200 | generation plane equations: @code{GL_OBJECT_PLANE} or | |
10201 | @code{GL_EYE_PLANE}. | |
10202 | ||
10203 | @item @var{params} | |
10204 | Returns the requested data. | |
10205 | ||
10206 | @end table | |
10207 | ||
10208 | @code{glGetTexGen} returns in @var{params} selected parameters of a | |
10209 | texture coordinate generation function that was specified using | |
c7b31271 | 10210 | @code{glTexGen}. @var{coord} names one of the (@var{s}, @var{t}, |
b002944d AW |
10211 | @var{r}, @var{q}) texture coordinates, using the symbolic constant |
10212 | @code{GL_S}, @code{GL_T}, @code{GL_R}, or @code{GL_Q}. | |
10213 | ||
10214 | @var{pname} specifies one of three symbolic names: | |
10215 | ||
10216 | @table @asis | |
10217 | @item @code{GL_TEXTURE_GEN_MODE} | |
10218 | @var{params} returns the single-valued texture generation function, a | |
c7b31271 | 10219 | symbolic constant. The initial value is @code{GL_EYE_LINEAR}. |
b002944d AW |
10220 | |
10221 | @item @code{GL_OBJECT_PLANE} | |
10222 | @var{params} returns the four plane equation coefficients that specify | |
c7b31271 DH |
10223 | object linear-coordinate generation. Integer values, when requested, |
10224 | are mapped directly from the internal floating-point representation. | |
b002944d AW |
10225 | |
10226 | @item @code{GL_EYE_PLANE} | |
10227 | @var{params} returns the four plane equation coefficients that specify | |
c7b31271 DH |
10228 | eye linear-coordinate generation. Integer values, when requested, are |
10229 | mapped directly from the internal floating-point representation. The | |
10230 | returned values are those maintained in eye coordinates. They are not | |
b002944d AW |
10231 | equal to the values specified using @code{glTexGen}, unless the |
10232 | modelview matrix was identity when @code{glTexGen} was called. | |
10233 | ||
10234 | @end table | |
10235 | ||
10236 | @code{GL_INVALID_ENUM} is generated if @var{coord} or @var{pname} is not | |
10237 | an accepted value. | |
10238 | ||
10239 | @code{GL_INVALID_OPERATION} is generated if @code{glGetTexGen} is | |
10240 | executed between the execution of @code{glBegin} and the corresponding | |
10241 | execution of @code{glEnd}. | |
10242 | ||
10243 | @end deftypefun | |
10244 | ||
10245 | @deftypefun void glGetTexImage target level format type img | |
10246 | Return a texture image. | |
10247 | ||
10248 | @table @asis | |
10249 | @item @var{target} | |
c7b31271 | 10250 | Specifies which texture is to be obtained. @code{GL_TEXTURE_1D}, |
b002944d AW |
10251 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, |
10252 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
10253 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
10254 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
10255 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
10256 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, and | |
10257 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z} are accepted. | |
10258 | ||
10259 | @item @var{level} | |
c7b31271 DH |
10260 | Specifies the level-of-detail number of the desired image. Level 0 is |
10261 | the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap | |
b002944d AW |
10262 | reduction image. |
10263 | ||
10264 | @item @var{format} | |
c7b31271 | 10265 | Specifies a pixel format for the returned data. The supported formats |
b002944d AW |
10266 | are @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, @code{GL_ALPHA}, |
10267 | @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, @code{GL_BGRA}, | |
10268 | @code{GL_LUMINANCE}, and @code{GL_LUMINANCE_ALPHA}. | |
10269 | ||
10270 | @item @var{type} | |
c7b31271 | 10271 | Specifies a pixel type for the returned data. The supported types are |
b002944d AW |
10272 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_UNSIGNED_SHORT}, |
10273 | @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT}, | |
10274 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
10275 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
10276 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
10277 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
10278 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
10279 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
10280 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
10281 | ||
10282 | @item @var{img} | |
c7b31271 | 10283 | Returns the texture image. Should be a pointer to an array of the type |
b002944d AW |
10284 | specified by @var{type}. |
10285 | ||
10286 | @end table | |
10287 | ||
10288 | @code{glGetTexImage} returns a texture image into @var{img}. | |
10289 | @var{target} specifies whether the desired texture image is one | |
10290 | specified by @code{glTexImage1D} (@code{GL_TEXTURE_1D}), | |
10291 | @code{glTexImage2D} (@code{GL_TEXTURE_2D} or any of | |
10292 | @code{GL_TEXTURE_CUBE_MAP_*}), or @code{glTexImage3D} | |
c7b31271 DH |
10293 | (@code{GL_TEXTURE_3D}). @var{level} specifies the level-of-detail |
10294 | number of the desired image. @var{format} and @var{type} specify the | |
10295 | format and type of the desired image array. See the reference pages | |
b002944d AW |
10296 | @code{glTexImage1D} and @code{glDrawPixels} for a description of the |
10297 | acceptable values for the @var{format} and @var{type} parameters, | |
10298 | respectively. | |
10299 | ||
10300 | If a non-zero named buffer object is bound to the | |
10301 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
10302 | texture image is requested, @var{img} is treated as a byte offset into | |
10303 | the buffer object's data store. | |
10304 | ||
10305 | To understand the operation of @code{glGetTexImage}, consider the | |
10306 | selected internal four-component texture image to be an RGBA color | |
c7b31271 | 10307 | buffer the size of the image. The semantics of @code{glGetTexImage} are |
b002944d AW |
10308 | then identical to those of @code{glReadPixels}, with the exception that |
10309 | no pixel transfer operations are performed, when called with the same | |
10310 | @var{format} and @var{type}, with @var{x} and @var{y} set to 0, | |
10311 | @var{width} set to the width of the texture image (including border if | |
10312 | one was specified), and @var{height} set to 1 for 1D images, or to the | |
10313 | height of the texture image (including border if one was specified) for | |
c7b31271 | 10314 | 2D images. Because the internal texture image is an RGBA image, pixel |
b002944d AW |
10315 | formats @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, and |
10316 | @code{GL_DEPTH_COMPONENT} are not accepted, and pixel type | |
10317 | @code{GL_BITMAP} is not accepted. | |
10318 | ||
10319 | If the selected texture image does not contain four components, the | |
c7b31271 DH |
10320 | following mappings are applied. Single-component textures are treated |
10321 | as RGBA buffers with red set to the single-component value, green set to | |
10322 | 0, blue set to 0, and alpha set to 1. Two-component textures are | |
10323 | treated as RGBA buffers with red set to the value of component zero, | |
10324 | alpha set to the value of component one, and green and blue set to 0. | |
10325 | Finally, three-component textures are treated as RGBA buffers with red | |
10326 | set to component zero, green set to component one, blue set to component | |
10327 | two, and alpha set to 1. | |
b002944d AW |
10328 | |
10329 | To determine the required size of @var{img}, use | |
10330 | @code{glGetTexLevelParameter} to determine the dimensions of the | |
10331 | internal texture image, then scale the required number of pixels by the | |
10332 | storage required for each pixel, based on @var{format} and @var{type}. | |
10333 | Be sure to take the pixel storage parameters into account, especially | |
10334 | @code{GL_PACK_ALIGNMENT}. | |
10335 | ||
10336 | @code{GL_INVALID_ENUM} is generated if @var{target}, @var{format}, or | |
10337 | @var{type} is not an accepted value. | |
10338 | ||
10339 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
10340 | ||
10341 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
10342 | @r{@var{log}_2(@var{max},)}, where @r{@var{max}} is the returned value | |
10343 | of @code{GL_MAX_TEXTURE_SIZE}. | |
10344 | ||
10345 | @code{GL_INVALID_OPERATION} is returned if @var{type} is one of | |
10346 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
10347 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
10348 | and @var{format} is not @code{GL_RGB}. | |
10349 | ||
10350 | @code{GL_INVALID_OPERATION} is returned if @var{type} is one of | |
10351 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
10352 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
10353 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
10354 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
10355 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}, and @var{format} is neither | |
10356 | @code{GL_RGBA} or @code{GL_BGRA}. | |
10357 | ||
10358 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
10359 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
10360 | object's data store is currently mapped. | |
10361 | ||
10362 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
10363 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
10364 | would be packed to the buffer object such that the memory writes | |
10365 | required would exceed the data store size. | |
10366 | ||
10367 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
10368 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{img} is | |
10369 | not evenly divisible into the number of bytes needed to store in memory | |
10370 | a datum indicated by @var{type}. | |
10371 | ||
10372 | @code{GL_INVALID_OPERATION} is generated if @code{glGetTexImage} is | |
10373 | executed between the execution of @code{glBegin} and the corresponding | |
10374 | execution of @code{glEnd}. | |
10375 | ||
10376 | @end deftypefun | |
10377 | ||
10378 | @deftypefun void glGetTexLevelParameterfv target level pname params | |
10379 | @deftypefunx void glGetTexLevelParameteriv target level pname params | |
10380 | Return texture parameter values for a specific level of detail. | |
10381 | ||
10382 | @table @asis | |
10383 | @item @var{target} | |
10384 | Specifies the symbolic name of the target texture, either | |
10385 | @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, | |
10386 | @code{GL_PROXY_TEXTURE_1D}, @code{GL_PROXY_TEXTURE_2D}, | |
10387 | @code{GL_PROXY_TEXTURE_3D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
10388 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
10389 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
10390 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
10391 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, | |
10392 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or | |
10393 | @code{GL_PROXY_TEXTURE_CUBE_MAP}. | |
10394 | ||
10395 | @item @var{level} | |
c7b31271 DH |
10396 | Specifies the level-of-detail number of the desired image. Level 0 is |
10397 | the base image level. Level @r{@var{n}} is the @r{@var{n}}th mipmap | |
b002944d AW |
10398 | reduction image. |
10399 | ||
10400 | @item @var{pname} | |
10401 | Specifies the symbolic name of a texture parameter. | |
10402 | @code{GL_TEXTURE_WIDTH}, @code{GL_TEXTURE_HEIGHT}, | |
10403 | @code{GL_TEXTURE_DEPTH}, @code{GL_TEXTURE_INTERNAL_FORMAT}, | |
10404 | @code{GL_TEXTURE_BORDER}, @code{GL_TEXTURE_RED_SIZE}, | |
10405 | @code{GL_TEXTURE_GREEN_SIZE}, @code{GL_TEXTURE_BLUE_SIZE}, | |
10406 | @code{GL_TEXTURE_ALPHA_SIZE}, @code{GL_TEXTURE_LUMINANCE_SIZE}, | |
10407 | @code{GL_TEXTURE_INTENSITY_SIZE}, @code{GL_TEXTURE_DEPTH_SIZE}, | |
10408 | @code{GL_TEXTURE_COMPRESSED}, and | |
10409 | @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} are accepted. | |
10410 | ||
10411 | @item @var{params} | |
10412 | Returns the requested data. | |
10413 | ||
10414 | @end table | |
10415 | ||
10416 | @code{glGetTexLevelParameter} returns in @var{params} texture parameter | |
10417 | values for a specific level-of-detail value, specified as @var{level}. | |
10418 | @var{target} defines the target texture, either @code{GL_TEXTURE_1D}, | |
10419 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, @code{GL_PROXY_TEXTURE_1D}, | |
10420 | @code{GL_PROXY_TEXTURE_2D}, @code{GL_PROXY_TEXTURE_3D}, | |
10421 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
10422 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
10423 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
10424 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
10425 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, | |
10426 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or | |
10427 | @code{GL_PROXY_TEXTURE_CUBE_MAP}. | |
10428 | ||
10429 | @code{GL_MAX_TEXTURE_SIZE}, and @code{GL_MAX_3D_TEXTURE_SIZE} are not | |
c7b31271 | 10430 | really descriptive enough. It has to report the largest square texture |
b002944d AW |
10431 | image that can be accommodated with mipmaps and borders, but a long |
10432 | skinny texture, or a texture without mipmaps and borders, may easily fit | |
c7b31271 | 10433 | in texture memory. The proxy targets allow the user to more accurately |
b002944d AW |
10434 | query whether the GL can accommodate a texture of a given configuration. |
10435 | If the texture cannot be accommodated, the texture state variables, | |
10436 | which may be queried with @code{glGetTexLevelParameter}, are set to 0. | |
10437 | If the texture can be accommodated, the texture state values will be set | |
10438 | as they would be set for a non-proxy target. | |
10439 | ||
10440 | @var{pname} specifies the texture parameter whose value or values will | |
10441 | be returned. | |
10442 | ||
10443 | The accepted parameter names are as follows: | |
10444 | ||
10445 | @table @asis | |
10446 | @item @code{GL_TEXTURE_WIDTH} | |
10447 | ||
10448 | ||
10449 | @var{params} returns a single value, the width of the texture image. | |
c7b31271 | 10450 | This value includes the border of the texture image. The initial value |
b002944d AW |
10451 | is 0. |
10452 | ||
10453 | @item @code{GL_TEXTURE_HEIGHT} | |
10454 | ||
10455 | ||
10456 | @var{params} returns a single value, the height of the texture image. | |
c7b31271 | 10457 | This value includes the border of the texture image. The initial value |
b002944d AW |
10458 | is 0. |
10459 | ||
10460 | @item @code{GL_TEXTURE_DEPTH} | |
10461 | ||
10462 | ||
10463 | @var{params} returns a single value, the depth of the texture image. | |
c7b31271 | 10464 | This value includes the border of the texture image. The initial value |
b002944d AW |
10465 | is 0. |
10466 | ||
10467 | @item @code{GL_TEXTURE_INTERNAL_FORMAT} | |
10468 | ||
10469 | ||
10470 | @var{params} returns a single value, the internal format of the texture | |
10471 | image. | |
10472 | ||
10473 | @item @code{GL_TEXTURE_BORDER} | |
10474 | ||
10475 | ||
10476 | @var{params} returns a single value, the width in pixels of the border | |
c7b31271 | 10477 | of the texture image. The initial value is 0. |
b002944d AW |
10478 | |
10479 | @item @code{GL_TEXTURE_RED_SIZE}, | |
10480 | @item @code{GL_TEXTURE_GREEN_SIZE}, | |
10481 | @item @code{GL_TEXTURE_BLUE_SIZE}, | |
10482 | @item @code{GL_TEXTURE_ALPHA_SIZE}, | |
10483 | @item @code{GL_TEXTURE_LUMINANCE_SIZE}, | |
10484 | @item @code{GL_TEXTURE_INTENSITY_SIZE}, | |
10485 | @item @code{GL_TEXTURE_DEPTH_SIZE} | |
10486 | ||
10487 | ||
c7b31271 | 10488 | The internal storage resolution of an individual component. The |
b002944d AW |
10489 | resolution chosen by the GL will be a close match for the resolution |
10490 | requested by the user with the component argument of | |
10491 | @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D}, | |
c7b31271 | 10492 | @code{glCopyTexImage1D}, and @code{glCopyTexImage2D}. The initial value |
b002944d AW |
10493 | is 0. |
10494 | ||
10495 | @item @code{GL_TEXTURE_COMPRESSED} | |
10496 | ||
10497 | ||
10498 | @var{params} returns a single boolean value indicating if the texture | |
c7b31271 | 10499 | image is stored in a compressed internal format. The initiali value is |
b002944d AW |
10500 | @code{GL_FALSE}. |
10501 | ||
10502 | @item @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} | |
10503 | ||
10504 | ||
10505 | @var{params} returns a single integer value, the number of unsigned | |
10506 | bytes of the compressed texture image that would be returned from | |
10507 | @code{glGetCompressedTexImage}. | |
10508 | ||
10509 | @end table | |
10510 | ||
10511 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
10512 | not an accepted value. | |
10513 | ||
10514 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
10515 | ||
10516 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
10517 | @r{@var{log}_2}@var{max}, where @var{max} is the returned value of | |
10518 | @code{GL_MAX_TEXTURE_SIZE}. | |
10519 | ||
10520 | @code{GL_INVALID_OPERATION} is generated if | |
10521 | @code{glGetTexLevelParameter} is executed between the execution of | |
10522 | @code{glBegin} and the corresponding execution of @code{glEnd}. | |
10523 | ||
10524 | @code{GL_INVALID_OPERATION} is generated if | |
10525 | @code{GL_TEXTURE_COMPRESSED_IMAGE_SIZE} is queried on texture images | |
10526 | with an uncompressed internal format or on proxy targets. | |
10527 | ||
10528 | @end deftypefun | |
10529 | ||
10530 | @deftypefun void glGetTexParameterfv target pname params | |
10531 | @deftypefunx void glGetTexParameteriv target pname params | |
10532 | Return texture parameter values. | |
10533 | ||
10534 | @table @asis | |
10535 | @item @var{target} | |
c7b31271 | 10536 | Specifies the symbolic name of the target texture. @code{GL_TEXTURE_1D}, |
b002944d AW |
10537 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, and |
10538 | @code{GL_TEXTURE_CUBE_MAP} are accepted. | |
10539 | ||
10540 | @item @var{pname} | |
10541 | Specifies the symbolic name of a texture parameter. | |
10542 | @code{GL_TEXTURE_MAG_FILTER}, @code{GL_TEXTURE_MIN_FILTER}, | |
10543 | @code{GL_TEXTURE_MIN_LOD}, @code{GL_TEXTURE_MAX_LOD}, | |
10544 | @code{GL_TEXTURE_BASE_LEVEL}, @code{GL_TEXTURE_MAX_LEVEL}, | |
10545 | @code{GL_TEXTURE_WRAP_S}, @code{GL_TEXTURE_WRAP_T}, | |
10546 | @code{GL_TEXTURE_WRAP_R}, @code{GL_TEXTURE_BORDER_COLOR}, | |
10547 | @code{GL_TEXTURE_PRIORITY}, @code{GL_TEXTURE_RESIDENT}, | |
10548 | @code{GL_TEXTURE_COMPARE_MODE}, @code{GL_TEXTURE_COMPARE_FUNC}, | |
10549 | @code{GL_DEPTH_TEXTURE_MODE}, and @code{GL_GENERATE_MIPMAP} are | |
10550 | accepted. | |
10551 | ||
10552 | @item @var{params} | |
10553 | Returns the texture parameters. | |
10554 | ||
10555 | @end table | |
10556 | ||
10557 | @code{glGetTexParameter} returns in @var{params} the value or values of | |
c7b31271 DH |
10558 | the texture parameter specified as @var{pname}. @var{target} defines |
10559 | the target texture, either @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, | |
b002944d | 10560 | @code{GL_TEXTURE_3D}, or @code{GL_TEXTURE_CUBE_MAP}, to specify one-, |
c7b31271 DH |
10561 | two-, or three-dimensional or cube-mapped texturing. @var{pname} |
10562 | accepts the same symbols as @code{glTexParameter}, with the same | |
b002944d AW |
10563 | interpretations: |
10564 | ||
10565 | @table @asis | |
10566 | @item @code{GL_TEXTURE_MAG_FILTER} | |
10567 | Returns the single-valued texture magnification filter, a symbolic | |
c7b31271 | 10568 | constant. The initial value is @code{GL_LINEAR}. |
b002944d AW |
10569 | |
10570 | @item @code{GL_TEXTURE_MIN_FILTER} | |
10571 | Returns the single-valued texture minification filter, a symbolic | |
c7b31271 | 10572 | constant. The initial value is @code{GL_NEAREST_MIPMAP_LINEAR}. |
b002944d AW |
10573 | |
10574 | @item @code{GL_TEXTURE_MIN_LOD} | |
c7b31271 | 10575 | Returns the single-valued texture minimum level-of-detail value. The |
b002944d AW |
10576 | initial value is @r{-1000}. |
10577 | ||
10578 | @item @code{GL_TEXTURE_MAX_LOD} | |
c7b31271 | 10579 | Returns the single-valued texture maximum level-of-detail value. The |
b002944d AW |
10580 | initial value is 1000. |
10581 | ||
10582 | @item @code{GL_TEXTURE_BASE_LEVEL} | |
c7b31271 | 10583 | Returns the single-valued base texture mipmap level. The initial value |
b002944d AW |
10584 | is 0. |
10585 | ||
10586 | @item @code{GL_TEXTURE_MAX_LEVEL} | |
c7b31271 | 10587 | Returns the single-valued maximum texture mipmap array level. The |
b002944d AW |
10588 | initial value is 1000. |
10589 | ||
10590 | @item @code{GL_TEXTURE_WRAP_S} | |
10591 | Returns the single-valued wrapping function for texture coordinate | |
c7b31271 DH |
10592 | @r{@var{s}}, a symbolic constant. The initial value is |
10593 | @code{GL_REPEAT}. | |
b002944d AW |
10594 | |
10595 | @item @code{GL_TEXTURE_WRAP_T} | |
10596 | Returns the single-valued wrapping function for texture coordinate | |
c7b31271 DH |
10597 | @r{@var{t}}, a symbolic constant. The initial value is |
10598 | @code{GL_REPEAT}. | |
b002944d AW |
10599 | |
10600 | @item @code{GL_TEXTURE_WRAP_R} | |
10601 | Returns the single-valued wrapping function for texture coordinate | |
c7b31271 DH |
10602 | @r{@var{r}}, a symbolic constant. The initial value is |
10603 | @code{GL_REPEAT}. | |
b002944d AW |
10604 | |
10605 | @item @code{GL_TEXTURE_BORDER_COLOR} | |
10606 | Returns four integer or floating-point numbers that comprise the RGBA | |
c7b31271 DH |
10607 | color of the texture border. Floating-point values are returned in the |
10608 | range @r{[0,1]}. Integer values are returned as a linear mapping of the | |
b002944d AW |
10609 | internal floating-point representation such that 1.0 maps to the most |
10610 | positive representable integer and @r{-1.0} maps to the most negative | |
c7b31271 | 10611 | representable integer. The initial value is (0, 0, 0, 0). |
b002944d AW |
10612 | |
10613 | @item @code{GL_TEXTURE_PRIORITY} | |
10614 | Returns the residence priority of the target texture (or the named | |
c7b31271 | 10615 | texture bound to it). The initial value is 1. See |
b002944d AW |
10616 | @code{glPrioritizeTextures}. |
10617 | ||
10618 | @item @code{GL_TEXTURE_RESIDENT} | |
c7b31271 | 10619 | Returns the residence status of the target texture. If the value |
b002944d | 10620 | returned in @var{params} is @code{GL_TRUE}, the texture is resident in |
c7b31271 | 10621 | texture memory. See @code{glAreTexturesResident}. |
b002944d AW |
10622 | |
10623 | @item @code{GL_TEXTURE_COMPARE_MODE} | |
10624 | Returns a single-valued texture comparison mode, a symbolic constant. | |
c7b31271 | 10625 | The initial value is @code{GL_NONE}. See @code{glTexParameter}. |
b002944d AW |
10626 | |
10627 | @item @code{GL_TEXTURE_COMPARE_FUNC} | |
10628 | Returns a single-valued texture comparison function, a symbolic | |
c7b31271 | 10629 | constant. The initial value is @code{GL_LEQUAL}. See |
b002944d AW |
10630 | @code{glTexParameter}. |
10631 | ||
10632 | @item @code{GL_DEPTH_TEXTURE_MODE} | |
10633 | Returns a single-valued texture format indicating how the depth values | |
c7b31271 DH |
10634 | should be converted into color components. The initial value is |
10635 | @code{GL_LUMINANCE}. See @code{glTexParameter}. | |
b002944d AW |
10636 | |
10637 | @item @code{GL_GENERATE_MIPMAP} | |
10638 | Returns a single boolean value indicating if automatic mipmap level | |
c7b31271 | 10639 | updates are enabled. See @code{glTexParameter}. |
b002944d AW |
10640 | |
10641 | @end table | |
10642 | ||
10643 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is | |
10644 | not an accepted value. | |
10645 | ||
10646 | @code{GL_INVALID_OPERATION} is generated if @code{glGetTexParameter} is | |
10647 | executed between the execution of @code{glBegin} and the corresponding | |
10648 | execution of @code{glEnd}. | |
10649 | ||
10650 | @end deftypefun | |
10651 | ||
10652 | @deftypefun GLint glGetUniformLocation program name | |
10653 | Returns the location of a uniform variable. | |
10654 | ||
10655 | @table @asis | |
10656 | @item @var{program} | |
10657 | Specifies the program object to be queried. | |
10658 | ||
10659 | @item @var{name} | |
10660 | Points to a null terminated string containing the name of the uniform | |
10661 | variable whose location is to be queried. | |
10662 | ||
10663 | @end table | |
10664 | ||
10665 | @code{glGetUniformLocation } returns an integer that represents the | |
10666 | location of a specific uniform variable within a program object. | |
10667 | @var{name} must be a null terminated string that contains no white | |
c7b31271 | 10668 | space. @var{name} must be an active uniform variable name in |
b002944d | 10669 | @var{program} that is not a structure, an array of structures, or a |
c7b31271 | 10670 | subcomponent of a vector or a matrix. This function returns -1 if |
b002944d AW |
10671 | @var{name} does not correspond to an active uniform variable in |
10672 | @var{program} or if @var{name} starts with the reserved prefix "gl_". | |
10673 | ||
10674 | Uniform variables that are structures or arrays of structures may be | |
10675 | queried by calling @code{glGetUniformLocation} for each field within the | |
c7b31271 | 10676 | structure. The array element operator "[]" and the structure field |
b002944d | 10677 | operator "." may be used in @var{name} in order to select elements |
c7b31271 | 10678 | within an array or fields within a structure. The result of using these |
b002944d | 10679 | operators is not allowed to be another structure, an array of |
c7b31271 | 10680 | structures, or a subcomponent of a vector or a matrix. Except if the |
b002944d AW |
10681 | last part of @var{name} indicates a uniform variable array, the location |
10682 | of the first element of an array can be retrieved by using the name of | |
10683 | the array, or by using the name appended by "[0]". | |
10684 | ||
10685 | The actual locations assigned to uniform variables are not known until | |
c7b31271 | 10686 | the program object is linked successfully. After linking has occurred, |
b002944d | 10687 | the command @code{glGetUniformLocation} can be used to obtain the |
c7b31271 | 10688 | location of a uniform variable. This location value can then be passed |
b002944d AW |
10689 | to @code{glUniform} to set the value of the uniform variable or to |
10690 | @code{glGetUniform} in order to query the current value of the uniform | |
c7b31271 DH |
10691 | variable. After a program object has been linked successfully, the |
10692 | index values for uniform variables remain fixed until the next link | |
10693 | command occurs. Uniform variable locations and values can only be | |
10694 | queried after a link if the link was successful. | |
b002944d AW |
10695 | |
10696 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value | |
10697 | generated by OpenGL. | |
10698 | ||
10699 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
10700 | program object. | |
10701 | ||
10702 | @code{GL_INVALID_OPERATION} is generated if @var{program} has not been | |
10703 | successfully linked. | |
10704 | ||
10705 | @code{GL_INVALID_OPERATION} is generated if @code{glGetUniformLocation} | |
10706 | is executed between the execution of @code{glBegin} and the | |
10707 | corresponding execution of @code{glEnd}. | |
10708 | ||
10709 | @end deftypefun | |
10710 | ||
10711 | @deftypefun void glGetUniformfv program location params | |
10712 | @deftypefunx void glGetUniformiv program location params | |
10713 | Returns the value of a uniform variable. | |
10714 | ||
10715 | @table @asis | |
10716 | @item @var{program} | |
10717 | Specifies the program object to be queried. | |
10718 | ||
10719 | @item @var{location} | |
10720 | Specifies the location of the uniform variable to be queried. | |
10721 | ||
10722 | @item @var{params} | |
10723 | Returns the value of the specified uniform variable. | |
10724 | ||
10725 | @end table | |
10726 | ||
10727 | @code{glGetUniform} returns in @var{params} the value(s) of the | |
c7b31271 DH |
10728 | specified uniform variable. The type of the uniform variable specified |
10729 | by @var{location} determines the number of values returned. If the | |
b002944d | 10730 | uniform variable is defined in the shader as a boolean, int, or float, a |
c7b31271 DH |
10731 | single value will be returned. If it is defined as a vec2, ivec2, or |
10732 | bvec2, two values will be returned. If it is defined as a vec3, ivec3, | |
10733 | or bvec3, three values will be returned, and so on. To query values | |
b002944d | 10734 | stored in uniform variables declared as arrays, call @code{glGetUniform} |
c7b31271 | 10735 | for each element of the array. To query values stored in uniform |
b002944d | 10736 | variables declared as structures, call @code{glGetUniform} for each |
c7b31271 | 10737 | field in the structure. The values for uniform variables declared as a |
b002944d AW |
10738 | matrix will be returned in column major order. |
10739 | ||
10740 | The locations assigned to uniform variables are not known until the | |
c7b31271 | 10741 | program object is linked. After linking has occurred, the command |
b002944d | 10742 | @code{glGetUniformLocation} can be used to obtain the location of a |
c7b31271 | 10743 | uniform variable. This location value can then be passed to |
b002944d | 10744 | @code{glGetUniform} in order to query the current value of the uniform |
c7b31271 DH |
10745 | variable. After a program object has been linked successfully, the |
10746 | index values for uniform variables remain fixed until the next link | |
10747 | command occurs. The uniform variable values can only be queried after a | |
10748 | link if the link was successful. | |
b002944d AW |
10749 | |
10750 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value | |
10751 | generated by OpenGL. | |
10752 | ||
10753 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
10754 | program object. | |
10755 | ||
10756 | @code{GL_INVALID_OPERATION} is generated if @var{program} has not been | |
10757 | successfully linked. | |
10758 | ||
10759 | @code{GL_INVALID_OPERATION} is generated if @var{location} does not | |
10760 | correspond to a valid uniform variable location for the specified | |
10761 | program object. | |
10762 | ||
10763 | @code{GL_INVALID_OPERATION} is generated if @code{glGetUniform} is | |
10764 | executed between the execution of @code{glBegin} and the corresponding | |
10765 | execution of @code{glEnd}. | |
10766 | ||
10767 | @end deftypefun | |
10768 | ||
10769 | @deftypefun void glGetVertexAttribPointerv index pname pointer | |
10770 | Return the address of the specified generic vertex attribute pointer. | |
10771 | ||
10772 | @table @asis | |
10773 | @item @var{index} | |
10774 | Specifies the generic vertex attribute parameter to be returned. | |
10775 | ||
10776 | @item @var{pname} | |
10777 | Specifies the symbolic name of the generic vertex attribute parameter to | |
c7b31271 | 10778 | be returned. Must be @code{GL_VERTEX_ATTRIB_ARRAY_POINTER}. |
b002944d AW |
10779 | |
10780 | @item @var{pointer} | |
10781 | Returns the pointer value. | |
10782 | ||
10783 | @end table | |
10784 | ||
10785 | @code{glGetVertexAttribPointerv} returns pointer information. | |
10786 | @var{index} is the generic vertex attribute to be queried, @var{pname} | |
10787 | is a symbolic constant indicating the pointer to be returned, and | |
10788 | @var{params} is a pointer to a location in which to place the returned | |
10789 | data. | |
10790 | ||
10791 | If a non-zero named buffer object was bound to the | |
10792 | @code{GL_ARRAY_BUFFER} target (see @code{glBindBuffer}) when the desired | |
10793 | pointer was previously specified, the @var{pointer} returned is a byte | |
10794 | offset into the buffer object's data store. | |
10795 | ||
10796 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or | |
10797 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
10798 | ||
10799 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted | |
10800 | value. | |
10801 | ||
10802 | @end deftypefun | |
10803 | ||
d172eed9 AW |
10804 | @deftypefun void glGetVertexAttribdv index pname params |
10805 | @deftypefunx void glGetVertexAttribfv index pname params | |
b002944d AW |
10806 | @deftypefunx void glGetVertexAttribiv index pname params |
10807 | Return a generic vertex attribute parameter. | |
10808 | ||
10809 | @table @asis | |
10810 | @item @var{index} | |
10811 | Specifies the generic vertex attribute parameter to be queried. | |
10812 | ||
10813 | @item @var{pname} | |
10814 | Specifies the symbolic name of the vertex attribute parameter to be | |
c7b31271 | 10815 | queried. Accepted values are |
b002944d AW |
10816 | @code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING}, |
10817 | @code{GL_VERTEX_ATTRIB_ARRAY_ENABLED}, | |
10818 | @code{GL_VERTEX_ATTRIB_ARRAY_SIZE}, | |
10819 | @code{GL_VERTEX_ATTRIB_ARRAY_STRIDE}, | |
10820 | @code{GL_VERTEX_ATTRIB_ARRAY_TYPE}, | |
10821 | @code{GL_VERTEX_ATTRIB_ARRAY_NORMALIZED}, or | |
10822 | @code{GL_CURRENT_VERTEX_ATTRIB}. | |
10823 | ||
10824 | @item @var{params} | |
10825 | Returns the requested data. | |
10826 | ||
10827 | @end table | |
10828 | ||
10829 | @code{glGetVertexAttrib} returns in @var{params} the value of a generic | |
c7b31271 | 10830 | vertex attribute parameter. The generic vertex attribute to be queried |
b002944d AW |
10831 | is specified by @var{index}, and the parameter to be queried is |
10832 | specified by @var{pname}. | |
10833 | ||
10834 | The accepted parameter names are as follows: | |
10835 | ||
10836 | @table @asis | |
10837 | @item @code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING} | |
10838 | ||
10839 | ||
10840 | @var{params} returns a single value, the name of the buffer object | |
10841 | currently bound to the binding point corresponding to generic vertex | |
c7b31271 DH |
10842 | attribute array @var{index}. If no buffer object is bound, 0 is |
10843 | returned. The initial value is 0. | |
b002944d AW |
10844 | |
10845 | @item @code{GL_VERTEX_ATTRIB_ARRAY_ENABLED} | |
10846 | ||
10847 | ||
10848 | @var{params} returns a single value that is non-zero (true) if the | |
10849 | vertex attribute array for @var{index} is enabled and 0 (false) if it is | |
c7b31271 | 10850 | disabled. The initial value is @code{GL_FALSE}. |
b002944d AW |
10851 | |
10852 | @item @code{GL_VERTEX_ATTRIB_ARRAY_SIZE} | |
10853 | ||
10854 | ||
10855 | @var{params} returns a single value, the size of the vertex attribute | |
c7b31271 DH |
10856 | array for @var{index}. The size is the number of values for each |
10857 | element of the vertex attribute array, and it will be 1, 2, 3, or 4. The | |
10858 | initial value is 4. | |
b002944d AW |
10859 | |
10860 | @item @code{GL_VERTEX_ATTRIB_ARRAY_STRIDE} | |
10861 | ||
10862 | ||
10863 | @var{params} returns a single value, the array stride for (number of | |
10864 | bytes between successive elements in) the vertex attribute array for | |
c7b31271 DH |
10865 | @var{index}. A value of 0 indicates that the array elements are stored |
10866 | sequentially in memory. The initial value is 0. | |
b002944d AW |
10867 | |
10868 | @item @code{GL_VERTEX_ATTRIB_ARRAY_TYPE} | |
10869 | ||
10870 | ||
10871 | @var{params} returns a single value, a symbolic constant indicating the | |
c7b31271 | 10872 | array type for the vertex attribute array for @var{index}. Possible |
b002944d AW |
10873 | values are @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, |
10874 | @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT}, | |
c7b31271 | 10875 | @code{GL_FLOAT}, and @code{GL_DOUBLE}. The initial value is |
b002944d AW |
10876 | @code{GL_FLOAT}. |
10877 | ||
10878 | @item @code{GL_VERTEX_ATTRIB_ARRAY_NORMALIZED} | |
10879 | ||
10880 | ||
10881 | @var{params} returns a single value that is non-zero (true) if | |
10882 | fixed-point data types for the vertex attribute array indicated by | |
10883 | @var{index} are normalized when they are converted to floating point, | |
c7b31271 | 10884 | and 0 (false) otherwise. The initial value is @code{GL_FALSE}. |
b002944d AW |
10885 | |
10886 | @item @code{GL_CURRENT_VERTEX_ATTRIB} | |
10887 | ||
10888 | ||
10889 | @var{params} returns four values that represent the current value for | |
c7b31271 | 10890 | the generic vertex attribute specified by index. Generic vertex |
b002944d | 10891 | attribute 0 is unique in that it has no current state, so an error will |
c7b31271 | 10892 | be generated if @var{index} is 0. The initial value for all other |
b002944d AW |
10893 | generic vertex attributes is (0,0,0,1). |
10894 | ||
10895 | @end table | |
10896 | ||
10897 | All of the parameters except @code{GL_CURRENT_VERTEX_ATTRIB} represent | |
10898 | client-side state. | |
10899 | ||
10900 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or | |
10901 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
10902 | ||
10903 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted | |
10904 | value. | |
10905 | ||
10906 | @code{GL_INVALID_OPERATION} is generated if @var{index} is 0 and | |
10907 | @var{pname} is @code{GL_CURRENT_VERTEX_ATTRIB}. | |
10908 | ||
10909 | @end deftypefun | |
10910 | ||
10911 | @deftypefun void glGetBooleanv pname params | |
10912 | @deftypefunx void glGetDoublev pname params | |
10913 | @deftypefunx void glGetFloatv pname params | |
10914 | @deftypefunx void glGetIntegerv pname params | |
10915 | Return the value or values of a selected parameter. | |
10916 | ||
10917 | @table @asis | |
10918 | @item @var{pname} | |
c7b31271 | 10919 | Specifies the parameter value to be returned. The symbolic constants in |
b002944d AW |
10920 | the list below are accepted. |
10921 | ||
10922 | @item @var{params} | |
10923 | Returns the value or values of the specified parameter. | |
10924 | ||
10925 | @end table | |
10926 | ||
10927 | These four commands return values for simple state variables in GL. | |
10928 | @var{pname} is a symbolic constant indicating the state variable to be | |
10929 | returned, and @var{params} is a pointer to an array of the indicated | |
10930 | type in which to place the returned data. | |
10931 | ||
10932 | Type conversion is performed if @var{params} has a different type than | |
c7b31271 | 10933 | the state variable value being requested. If @code{glGetBooleanv} is |
b002944d | 10934 | called, a floating-point (or integer) value is converted to |
c7b31271 DH |
10935 | @code{GL_FALSE} if and only if it is 0.0 (or 0). Otherwise, it is |
10936 | converted to @code{GL_TRUE}. If @code{glGetIntegerv} is called, boolean | |
b002944d AW |
10937 | values are returned as @code{GL_TRUE} or @code{GL_FALSE}, and most |
10938 | floating-point values are rounded to the nearest integer value. | |
10939 | Floating-point colors and normals, however, are returned with a linear | |
10940 | mapping that maps 1.0 to the most positive representable integer value | |
c7b31271 | 10941 | and @r{-1.0} to the most negative representable integer value. If |
b002944d AW |
10942 | @code{glGetFloatv} or @code{glGetDoublev} is called, boolean values are |
10943 | returned as @code{GL_TRUE} or @code{GL_FALSE}, and integer values are | |
10944 | converted to floating-point values. | |
10945 | ||
10946 | The following symbolic constants are accepted by @var{pname}: | |
10947 | ||
10948 | @table @asis | |
10949 | @item @code{GL_ACCUM_ALPHA_BITS} | |
10950 | ||
10951 | ||
10952 | @var{params} returns one value, the number of alpha bitplanes in the | |
10953 | accumulation buffer. | |
10954 | ||
10955 | @item @code{GL_ACCUM_BLUE_BITS} | |
10956 | ||
10957 | ||
10958 | @var{params} returns one value, the number of blue bitplanes in the | |
10959 | accumulation buffer. | |
10960 | ||
10961 | @item @code{GL_ACCUM_CLEAR_VALUE} | |
10962 | ||
10963 | ||
10964 | @var{params} returns four values: the red, green, blue, and alpha values | |
c7b31271 DH |
10965 | used to clear the accumulation buffer. Integer values, if requested, |
10966 | are linearly mapped from the internal floating-point representation such | |
b002944d | 10967 | that 1.0 returns the most positive representable integer value, and |
c7b31271 DH |
10968 | @r{-1.0} returns the most negative representable integer value. The |
10969 | initial value is (0, 0, 0, 0). See @code{glClearAccum}. | |
b002944d AW |
10970 | |
10971 | @item @code{GL_ACCUM_GREEN_BITS} | |
10972 | ||
10973 | ||
10974 | @var{params} returns one value, the number of green bitplanes in the | |
10975 | accumulation buffer. | |
10976 | ||
10977 | @item @code{GL_ACCUM_RED_BITS} | |
10978 | ||
10979 | ||
10980 | @var{params} returns one value, the number of red bitplanes in the | |
10981 | accumulation buffer. | |
10982 | ||
10983 | @item @code{GL_ACTIVE_TEXTURE} | |
10984 | ||
10985 | ||
10986 | @var{params} returns a single value indicating the active multitexture | |
c7b31271 | 10987 | unit. The initial value is @code{GL_TEXTURE0}. See |
b002944d AW |
10988 | @code{glActiveTexture}. |
10989 | ||
10990 | @item @code{GL_ALIASED_POINT_SIZE_RANGE} | |
10991 | ||
10992 | ||
10993 | @var{params} returns two values, the smallest and largest supported | |
10994 | sizes for aliased points. | |
10995 | ||
10996 | @item @code{GL_ALIASED_LINE_WIDTH_RANGE} | |
10997 | ||
10998 | ||
10999 | @var{params} returns two values, the smallest and largest supported | |
11000 | widths for aliased lines. | |
11001 | ||
11002 | @item @code{GL_ALPHA_BIAS} | |
11003 | ||
11004 | ||
11005 | @var{params} returns one value, the alpha bias factor used during pixel | |
c7b31271 | 11006 | transfers. The initial value is 0. See @code{glPixelTransfer}. |
b002944d AW |
11007 | |
11008 | @item @code{GL_ALPHA_BITS} | |
11009 | ||
11010 | ||
11011 | @var{params} returns one value, the number of alpha bitplanes in each | |
11012 | color buffer. | |
11013 | ||
11014 | @item @code{GL_ALPHA_SCALE} | |
11015 | ||
11016 | ||
11017 | @var{params} returns one value, the alpha scale factor used during pixel | |
c7b31271 | 11018 | transfers. The initial value is 1. See @code{glPixelTransfer}. |
b002944d AW |
11019 | |
11020 | @item @code{GL_ALPHA_TEST} | |
11021 | ||
11022 | ||
11023 | @var{params} returns a single boolean value indicating whether alpha | |
c7b31271 | 11024 | testing of fragments is enabled. The initial value is @code{GL_FALSE}. |
b002944d AW |
11025 | See @code{glAlphaFunc}. |
11026 | ||
11027 | @item @code{GL_ALPHA_TEST_FUNC}@var{params} returns one value, | |
11028 | ||
11029 | ||
c7b31271 DH |
11030 | the symbolic name of the alpha test function. The initial value is |
11031 | @code{GL_ALWAYS}. See @code{glAlphaFunc}. | |
b002944d AW |
11032 | |
11033 | @item @code{GL_ALPHA_TEST_REF} | |
11034 | ||
11035 | ||
11036 | @var{params} returns one value, the reference value for the alpha test. | |
c7b31271 | 11037 | The initial value is 0. See @code{glAlphaFunc}. An integer value, if |
b002944d AW |
11038 | requested, is linearly mapped from the internal floating-point |
11039 | representation such that 1.0 returns the most positive representable | |
11040 | integer value, and @r{-1.0} returns the most negative representable | |
11041 | integer value. | |
11042 | ||
11043 | @item @code{GL_ARRAY_BUFFER_BINDING} | |
11044 | ||
11045 | ||
11046 | @var{params} returns a single value, the name of the buffer object | |
c7b31271 DH |
11047 | currently bound to the target @code{GL_ARRAY_BUFFER}. If no buffer |
11048 | object is bound to this target, 0 is returned. The initial value is 0. | |
b002944d AW |
11049 | See @code{glBindBuffer}. |
11050 | ||
11051 | @item @code{GL_ATTRIB_STACK_DEPTH} | |
11052 | ||
11053 | ||
c7b31271 DH |
11054 | @var{params} returns one value, the depth of the attribute stack. If |
11055 | the stack is empty, 0 is returned. The initial value is 0. See | |
b002944d AW |
11056 | @code{glPushAttrib}. |
11057 | ||
11058 | @item @code{GL_AUTO_NORMAL} | |
11059 | ||
11060 | ||
11061 | @var{params} returns a single boolean value indicating whether 2D map | |
c7b31271 DH |
11062 | evaluation automatically generates surface normals. The initial value |
11063 | is @code{GL_FALSE}. See @code{glMap2}. | |
b002944d AW |
11064 | |
11065 | @item @code{GL_AUX_BUFFERS} | |
11066 | ||
11067 | ||
11068 | @var{params} returns one value, the number of auxiliary color buffers | |
11069 | available. | |
11070 | ||
11071 | @item @code{GL_BLEND} | |
11072 | ||
11073 | ||
11074 | @var{params} returns a single boolean value indicating whether blending | |
c7b31271 | 11075 | is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11076 | @code{glBlendFunc}. |
11077 | ||
11078 | @item @code{GL_BLEND_COLOR} | |
11079 | ||
11080 | ||
11081 | @var{params} returns four values, the red, green, blue, and alpha values | |
c7b31271 | 11082 | which are the components of the blend color. See @code{glBlendColor}. |
b002944d AW |
11083 | |
11084 | @item @code{GL_BLEND_DST_ALPHA} | |
11085 | ||
11086 | ||
11087 | @var{params} returns one value, the symbolic constant identifying the | |
c7b31271 | 11088 | alpha destination blend function. The initial value is @code{GL_ZERO}. |
b002944d AW |
11089 | See @code{glBlendFunc} and @code{glBlendFuncSeparate}. |
11090 | ||
11091 | @item @code{GL_BLEND_DST_RGB} | |
11092 | ||
11093 | ||
11094 | @var{params} returns one value, the symbolic constant identifying the | |
c7b31271 DH |
11095 | RGB destination blend function. The initial value is @code{GL_ZERO}. |
11096 | See @code{glBlendFunc} and @code{glBlendFuncSeparate}. | |
b002944d AW |
11097 | |
11098 | @item @code{GL_BLEND_EQUATION_RGB} | |
11099 | ||
11100 | ||
11101 | @var{params} returns one value, a symbolic constant indicating whether | |
11102 | the RGB blend equation is @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT}, | |
c7b31271 | 11103 | @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN} or @code{GL_MAX}. See |
b002944d AW |
11104 | @code{glBlendEquationSeparate}. |
11105 | ||
11106 | @item @code{GL_BLEND_EQUATION_ALPHA} | |
11107 | ||
11108 | ||
11109 | @var{params} returns one value, a symbolic constant indicating whether | |
11110 | the Alpha blend equation is @code{GL_FUNC_ADD}, @code{GL_FUNC_SUBTRACT}, | |
c7b31271 | 11111 | @code{GL_FUNC_REVERSE_SUBTRACT}, @code{GL_MIN} or @code{GL_MAX}. See |
b002944d AW |
11112 | @code{glBlendEquationSeparate}. |
11113 | ||
11114 | @item @code{GL_BLEND_SRC_ALPHA} | |
11115 | ||
11116 | ||
11117 | @var{params} returns one value, the symbolic constant identifying the | |
c7b31271 | 11118 | alpha source blend function. The initial value is @code{GL_ONE}. See |
b002944d AW |
11119 | @code{glBlendFunc} and @code{glBlendFuncSeparate}. |
11120 | ||
11121 | @item @code{GL_BLEND_SRC_RGB} | |
11122 | ||
11123 | ||
11124 | @var{params} returns one value, the symbolic constant identifying the | |
c7b31271 | 11125 | RGB source blend function. The initial value is @code{GL_ONE}. See |
b002944d AW |
11126 | @code{glBlendFunc} and @code{glBlendFuncSeparate}. |
11127 | ||
11128 | @item @code{GL_BLUE_BIAS} | |
11129 | ||
11130 | ||
11131 | @var{params} returns one value, the blue bias factor used during pixel | |
c7b31271 | 11132 | transfers. The initial value is 0. See @code{glPixelTransfer}. |
b002944d AW |
11133 | |
11134 | @item @code{GL_BLUE_BITS} | |
11135 | ||
11136 | ||
11137 | @var{params} returns one value, the number of blue bitplanes in each | |
11138 | color buffer. | |
11139 | ||
11140 | @item @code{GL_BLUE_SCALE} | |
11141 | ||
11142 | ||
11143 | @var{params} returns one value, the blue scale factor used during pixel | |
c7b31271 | 11144 | transfers. The initial value is 1. See @code{glPixelTransfer}. |
b002944d AW |
11145 | |
11146 | @item @code{GL_CLIENT_ACTIVE_TEXTURE} | |
11147 | ||
11148 | ||
11149 | @var{params} returns a single integer value indicating the current | |
c7b31271 DH |
11150 | client active multitexture unit. The initial value is |
11151 | @code{GL_TEXTURE0}. See @code{glClientActiveTexture}. | |
b002944d AW |
11152 | |
11153 | @item @code{GL_CLIENT_ATTRIB_STACK_DEPTH} | |
11154 | ||
11155 | ||
11156 | @var{params} returns one value indicating the depth of the attribute | |
c7b31271 | 11157 | stack. The initial value is 0. See @code{glPushClientAttrib}. |
b002944d AW |
11158 | |
11159 | @item @code{GL_CLIP_PLANE}@var{i} | |
11160 | ||
11161 | ||
11162 | @var{params} returns a single boolean value indicating whether the | |
c7b31271 DH |
11163 | specified clipping plane is enabled. The initial value is |
11164 | @code{GL_FALSE}. See @code{glClipPlane}. | |
b002944d AW |
11165 | |
11166 | @item @code{GL_COLOR_ARRAY} | |
11167 | ||
11168 | ||
11169 | @var{params} returns a single boolean value indicating whether the color | |
c7b31271 | 11170 | array is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11171 | @code{glColorPointer}. |
11172 | ||
11173 | @item @code{GL_COLOR_ARRAY_BUFFER_BINDING} | |
11174 | ||
11175 | ||
11176 | @var{params} returns a single value, the name of the buffer object | |
c7b31271 | 11177 | associated with the color array. This buffer object would have been |
b002944d | 11178 | bound to the target @code{GL_ARRAY_BUFFER} at the time of the most |
c7b31271 DH |
11179 | recent call to @code{glColorPointer}. If no buffer object was bound to |
11180 | this target, 0 is returned. The initial value is 0. See | |
b002944d AW |
11181 | @code{glBindBuffer}. |
11182 | ||
11183 | @item @code{GL_COLOR_ARRAY_SIZE} | |
11184 | ||
11185 | ||
11186 | @var{params} returns one value, the number of components per color in | |
c7b31271 | 11187 | the color array. The initial value is 4. See @code{glColorPointer}. |
b002944d AW |
11188 | |
11189 | @item @code{GL_COLOR_ARRAY_STRIDE} | |
11190 | ||
11191 | ||
11192 | @var{params} returns one value, the byte offset between consecutive | |
c7b31271 | 11193 | colors in the color array. The initial value is 0. See |
b002944d AW |
11194 | @code{glColorPointer}. |
11195 | ||
11196 | @item @code{GL_COLOR_ARRAY_TYPE} | |
11197 | ||
11198 | ||
11199 | @var{params} returns one value, the data type of each component in the | |
c7b31271 | 11200 | color array. The initial value is @code{GL_FLOAT}. See |
b002944d AW |
11201 | @code{glColorPointer}. |
11202 | ||
11203 | @item @code{GL_COLOR_CLEAR_VALUE} | |
11204 | ||
11205 | ||
11206 | @var{params} returns four values: the red, green, blue, and alpha values | |
c7b31271 | 11207 | used to clear the color buffers. Integer values, if requested, are |
b002944d AW |
11208 | linearly mapped from the internal floating-point representation such |
11209 | that 1.0 returns the most positive representable integer value, and | |
c7b31271 DH |
11210 | @r{-1.0} returns the most negative representable integer value. The |
11211 | initial value is (0, 0, 0, 0). See @code{glClearColor}. | |
b002944d AW |
11212 | |
11213 | @item @code{GL_COLOR_LOGIC_OP} | |
11214 | ||
11215 | ||
11216 | @var{params} returns a single boolean value indicating whether a | |
11217 | fragment's RGBA color values are merged into the framebuffer using a | |
c7b31271 | 11218 | logical operation. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11219 | @code{glLogicOp}. |
11220 | ||
11221 | @item @code{GL_COLOR_MATERIAL} | |
11222 | ||
11223 | ||
11224 | @var{params} returns a single boolean value indicating whether one or | |
c7b31271 DH |
11225 | more material parameters are tracking the current color. The initial |
11226 | value is @code{GL_FALSE}. See @code{glColorMaterial}. | |
b002944d AW |
11227 | |
11228 | @item @code{GL_COLOR_MATERIAL_FACE} | |
11229 | ||
11230 | ||
11231 | @var{params} returns one value, a symbolic constant indicating which | |
c7b31271 DH |
11232 | materials have a parameter that is tracking the current color. The |
11233 | initial value is @code{GL_FRONT_AND_BACK}. See @code{glColorMaterial}. | |
b002944d AW |
11234 | |
11235 | @item @code{GL_COLOR_MATERIAL_PARAMETER} | |
11236 | ||
11237 | ||
11238 | @var{params} returns one value, a symbolic constant indicating which | |
c7b31271 DH |
11239 | material parameters are tracking the current color. The initial value |
11240 | is @code{GL_AMBIENT_AND_DIFFUSE}. See @code{glColorMaterial}. | |
b002944d AW |
11241 | |
11242 | @item @code{GL_COLOR_MATRIX} | |
11243 | ||
11244 | ||
11245 | @var{params} returns sixteen values: the color matrix on the top of the | |
c7b31271 | 11246 | color matrix stack. Initially this matrix is the identity matrix. See |
b002944d AW |
11247 | @code{glPushMatrix}. |
11248 | ||
11249 | @item @code{GL_COLOR_MATRIX_STACK_DEPTH} | |
11250 | ||
11251 | ||
11252 | @var{params} returns one value, the maximum supported depth of the | |
c7b31271 | 11253 | projection matrix stack. The value must be at least 2. See |
b002944d AW |
11254 | @code{glPushMatrix}. |
11255 | ||
11256 | @item @code{GL_COLOR_SUM} | |
11257 | ||
11258 | ||
11259 | @var{params} returns a single boolean value indicating whether primary | |
c7b31271 | 11260 | and secondary color sum is enabled. See @code{glSecondaryColor}. |
b002944d AW |
11261 | |
11262 | @item @code{GL_COLOR_TABLE} | |
11263 | ||
11264 | ||
11265 | @var{params} returns a single boolean value indicating whether the color | |
c7b31271 | 11266 | table lookup is enabled. See @code{glColorTable}. |
b002944d AW |
11267 | |
11268 | @item @code{GL_COLOR_WRITEMASK} | |
11269 | ||
11270 | ||
11271 | @var{params} returns four boolean values: the red, green, blue, and | |
c7b31271 DH |
11272 | alpha write enables for the color buffers. The initial value is |
11273 | (@code{GL_TRUE}, @code{GL_TRUE}, @code{GL_TRUE}, @code{GL_TRUE}). See | |
b002944d AW |
11274 | @code{glColorMask}. |
11275 | ||
11276 | @item @code{GL_COMPRESSED_TEXTURE_FORMATS} | |
11277 | ||
11278 | ||
11279 | @var{params} returns a list of symbolic constants of length | |
11280 | @code{GL_NUM_COMPRESSED_TEXTURE_FORMATS} indicating which compressed | |
c7b31271 | 11281 | texture formats are available. See @code{glCompressedTexImage2D}. |
b002944d AW |
11282 | |
11283 | @item @code{GL_CONVOLUTION_1D} | |
11284 | ||
11285 | ||
11286 | @var{params} returns a single boolean value indicating whether 1D | |
c7b31271 | 11287 | convolution is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11288 | @code{glConvolutionFilter1D}. |
11289 | ||
11290 | @item @code{GL_CONVOLUTION_2D} | |
11291 | ||
11292 | ||
11293 | @var{params} returns a single boolean value indicating whether 2D | |
c7b31271 | 11294 | convolution is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11295 | @code{glConvolutionFilter2D}. |
11296 | ||
11297 | @item @code{GL_CULL_FACE} | |
11298 | ||
11299 | ||
11300 | @var{params} returns a single boolean value indicating whether polygon | |
c7b31271 | 11301 | culling is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11302 | @code{glCullFace}. |
11303 | ||
11304 | @item @code{GL_CULL_FACE_MODE} | |
11305 | ||
11306 | ||
11307 | @var{params} returns one value, a symbolic constant indicating which | |
c7b31271 DH |
11308 | polygon faces are to be culled. The initial value is @code{GL_BACK}. |
11309 | See @code{glCullFace}. | |
b002944d AW |
11310 | |
11311 | @item @code{GL_CURRENT_COLOR} | |
11312 | ||
11313 | ||
11314 | @var{params} returns four values: the red, green, blue, and alpha values | |
c7b31271 | 11315 | of the current color. Integer values, if requested, are linearly mapped |
b002944d AW |
11316 | from the internal floating-point representation such that 1.0 returns |
11317 | the most positive representable integer value, and @r{-1.0} returns the | |
c7b31271 DH |
11318 | most negative representable integer value. The initial value is (1, 1, |
11319 | 1, 1). See @code{glColor}. | |
b002944d AW |
11320 | |
11321 | @item @code{GL_CURRENT_FOG_COORD} | |
11322 | ||
11323 | ||
c7b31271 DH |
11324 | @var{params} returns one value, the current fog coordinate. The initial |
11325 | value is 0. See @code{glFogCoord}. | |
b002944d AW |
11326 | |
11327 | @item @code{GL_CURRENT_INDEX} | |
11328 | ||
11329 | ||
c7b31271 DH |
11330 | @var{params} returns one value, the current color index. The initial |
11331 | value is 1. See @code{glIndex}. | |
b002944d AW |
11332 | |
11333 | @item @code{GL_CURRENT_NORMAL} | |
11334 | ||
11335 | ||
11336 | @var{params} returns three values: the @var{x}, @var{y}, and @var{z} | |
c7b31271 DH |
11337 | values of the current normal. Integer values, if requested, are |
11338 | linearly mapped from the internal floating-point representation such | |
11339 | that 1.0 returns the most positive representable integer value, and | |
11340 | @r{-1.0} returns the most negative representable integer value. The | |
11341 | initial value is (0, 0, 1). See @code{glNormal}. | |
b002944d AW |
11342 | |
11343 | @item @code{GL_CURRENT_PROGRAM} | |
11344 | ||
11345 | ||
11346 | @var{params} returns one value, the name of the program object that is | |
c7b31271 | 11347 | currently active, or 0 if no program object is active. See |
b002944d AW |
11348 | @code{glUseProgram}. |
11349 | ||
11350 | @item @code{GL_CURRENT_RASTER_COLOR} | |
11351 | ||
11352 | ||
11353 | @var{params} returns four values: the red, green, blue, and alpha color | |
c7b31271 DH |
11354 | values of the current raster position. Integer values, if requested, |
11355 | are linearly mapped from the internal floating-point representation such | |
b002944d | 11356 | that 1.0 returns the most positive representable integer value, and |
c7b31271 DH |
11357 | @r{-1.0} returns the most negative representable integer value. The |
11358 | initial value is (1, 1, 1, 1). See @code{glRasterPos}. | |
b002944d AW |
11359 | |
11360 | @item @code{GL_CURRENT_RASTER_DISTANCE} | |
11361 | ||
11362 | ||
11363 | @var{params} returns one value, the distance from the eye to the current | |
c7b31271 | 11364 | raster position. The initial value is 0. See @code{glRasterPos}. |
b002944d AW |
11365 | |
11366 | @item @code{GL_CURRENT_RASTER_INDEX} | |
11367 | ||
11368 | ||
11369 | @var{params} returns one value, the color index of the current raster | |
c7b31271 | 11370 | position. The initial value is 1. See @code{glRasterPos}. |
b002944d AW |
11371 | |
11372 | @item @code{GL_CURRENT_RASTER_POSITION} | |
11373 | ||
11374 | ||
11375 | @var{params} returns four values: the @var{x}, @var{y}, @var{z}, and | |
c7b31271 DH |
11376 | @var{w} components of the current raster position. @var{x}, @var{y}, |
11377 | and @var{z} are in window coordinates, and @var{w} is in clip | |
11378 | coordinates. The initial value is (0, 0, 0, 1). See | |
11379 | @code{glRasterPos}. | |
b002944d AW |
11380 | |
11381 | @item @code{GL_CURRENT_RASTER_POSITION_VALID} | |
11382 | ||
11383 | ||
11384 | @var{params} returns a single boolean value indicating whether the | |
c7b31271 | 11385 | current raster position is valid. The initial value is @code{GL_TRUE}. |
b002944d AW |
11386 | See @code{glRasterPos}. |
11387 | ||
11388 | @item @code{GL_CURRENT_RASTER_SECONDARY_COLOR} | |
11389 | ||
11390 | ||
11391 | @var{params} returns four values: the red, green, blue, and alpha | |
c7b31271 | 11392 | secondary color values of the current raster position. Integer values, |
b002944d AW |
11393 | if requested, are linearly mapped from the internal floating-point |
11394 | representation such that 1.0 returns the most positive representable | |
11395 | integer value, and @r{-1.0} returns the most negative representable | |
c7b31271 | 11396 | integer value. The initial value is (1, 1, 1, 1). See |
b002944d AW |
11397 | @code{glRasterPos}. |
11398 | ||
11399 | @item @code{GL_CURRENT_RASTER_TEXTURE_COORDS} | |
11400 | ||
11401 | ||
11402 | @var{params} returns four values: the @var{s}, @var{t}, @var{r}, and | |
c7b31271 DH |
11403 | @var{q} texture coordinates of the current raster position. The initial |
11404 | value is (0, 0, 0, 1). See @code{glRasterPos} and | |
b002944d AW |
11405 | @code{glMultiTexCoord}. |
11406 | ||
11407 | @item @code{GL_CURRENT_SECONDARY_COLOR} | |
11408 | ||
11409 | ||
11410 | @var{params} returns four values: the red, green, blue, and alpha values | |
c7b31271 | 11411 | of the current secondary color. Integer values, if requested, are |
b002944d AW |
11412 | linearly mapped from the internal floating-point representation such |
11413 | that 1.0 returns the most positive representable integer value, and | |
c7b31271 DH |
11414 | @r{-1.0} returns the most negative representable integer value. The |
11415 | initial value is (0, 0, 0, 0). See @code{glSecondaryColor}. | |
b002944d AW |
11416 | |
11417 | @item @code{GL_CURRENT_TEXTURE_COORDS} | |
11418 | ||
11419 | ||
11420 | @var{params} returns four values: the @var{s}, @var{t}, @var{r}, and | |
c7b31271 | 11421 | @var{q} current texture coordinates. The initial value is (0, 0, 0, 1). |
b002944d AW |
11422 | See @code{glMultiTexCoord}. |
11423 | ||
11424 | @item @code{GL_DEPTH_BIAS} | |
11425 | ||
11426 | ||
11427 | @var{params} returns one value, the depth bias factor used during pixel | |
c7b31271 | 11428 | transfers. The initial value is 0. See @code{glPixelTransfer}. |
b002944d AW |
11429 | |
11430 | @item @code{GL_DEPTH_BITS} | |
11431 | ||
11432 | ||
11433 | @var{params} returns one value, the number of bitplanes in the depth | |
11434 | buffer. | |
11435 | ||
11436 | @item @code{GL_DEPTH_CLEAR_VALUE} | |
11437 | ||
11438 | ||
11439 | @var{params} returns one value, the value that is used to clear the | |
c7b31271 DH |
11440 | depth buffer. Integer values, if requested, are linearly mapped from |
11441 | the internal floating-point representation such that 1.0 returns the | |
11442 | most positive representable integer value, and @r{-1.0} returns the most | |
11443 | negative representable integer value. The initial value is 1. See | |
b002944d AW |
11444 | @code{glClearDepth}. |
11445 | ||
11446 | @item @code{GL_DEPTH_FUNC} | |
11447 | ||
11448 | ||
11449 | @var{params} returns one value, the symbolic constant that indicates the | |
c7b31271 | 11450 | depth comparison function. The initial value is @code{GL_LESS}. See |
b002944d AW |
11451 | @code{glDepthFunc}. |
11452 | ||
11453 | @item @code{GL_DEPTH_RANGE} | |
11454 | ||
11455 | ||
11456 | @var{params} returns two values: the near and far mapping limits for the | |
c7b31271 DH |
11457 | depth buffer. Integer values, if requested, are linearly mapped from |
11458 | the internal floating-point representation such that 1.0 returns the | |
11459 | most positive representable integer value, and @r{-1.0} returns the most | |
11460 | negative representable integer value. The initial value is (0, 1). See | |
b002944d AW |
11461 | @code{glDepthRange}. |
11462 | ||
11463 | @item @code{GL_DEPTH_SCALE} | |
11464 | ||
11465 | ||
11466 | @var{params} returns one value, the depth scale factor used during pixel | |
c7b31271 | 11467 | transfers. The initial value is 1. See @code{glPixelTransfer}. |
b002944d AW |
11468 | |
11469 | @item @code{GL_DEPTH_TEST} | |
11470 | ||
11471 | ||
11472 | @var{params} returns a single boolean value indicating whether depth | |
c7b31271 | 11473 | testing of fragments is enabled. The initial value is @code{GL_FALSE}. |
b002944d AW |
11474 | See @code{glDepthFunc} and @code{glDepthRange}. |
11475 | ||
11476 | @item @code{GL_DEPTH_WRITEMASK} | |
11477 | ||
11478 | ||
11479 | @var{params} returns a single boolean value indicating if the depth | |
c7b31271 | 11480 | buffer is enabled for writing. The initial value is @code{GL_TRUE}. See |
b002944d AW |
11481 | @code{glDepthMask}. |
11482 | ||
11483 | @item @code{GL_DITHER} | |
11484 | ||
11485 | ||
11486 | @var{params} returns a single boolean value indicating whether dithering | |
c7b31271 | 11487 | of fragment colors and indices is enabled. The initial value is |
b002944d AW |
11488 | @code{GL_TRUE}. |
11489 | ||
11490 | @item @code{GL_DOUBLEBUFFER} | |
11491 | ||
11492 | ||
11493 | @var{params} returns a single boolean value indicating whether double | |
11494 | buffering is supported. | |
11495 | ||
11496 | @item @code{GL_DRAW_BUFFER} | |
11497 | ||
11498 | ||
11499 | @var{params} returns one value, a symbolic constant indicating which | |
c7b31271 | 11500 | buffers are being drawn to. See @code{glDrawBuffer}. The initial value |
b002944d AW |
11501 | is @code{GL_BACK} if there are back buffers, otherwise it is |
11502 | @code{GL_FRONT}. | |
11503 | ||
11504 | @item @code{GL_DRAW_BUFFER}@var{i} | |
11505 | ||
11506 | ||
11507 | @var{params} returns one value, a symbolic constant indicating which | |
c7b31271 DH |
11508 | buffers are being drawn to by the corresponding output color. See |
11509 | @code{glDrawBuffers}. The initial value of @code{GL_DRAW_BUFFER0} is | |
b002944d | 11510 | @code{GL_BACK} if there are back buffers, otherwise it is |
c7b31271 DH |
11511 | @code{GL_FRONT}. The initial values of draw buffers for all other |
11512 | output colors is @code{GL_NONE}. | |
b002944d AW |
11513 | |
11514 | @item @code{GL_EDGE_FLAG} | |
11515 | ||
11516 | ||
11517 | @var{params} returns a single boolean value indicating whether the | |
c7b31271 DH |
11518 | current edge flag is @code{GL_TRUE} or @code{GL_FALSE}. The initial |
11519 | value is @code{GL_TRUE}. See @code{glEdgeFlag}. | |
b002944d AW |
11520 | |
11521 | @item @code{GL_EDGE_FLAG_ARRAY} | |
11522 | ||
11523 | ||
11524 | @var{params} returns a single boolean value indicating whether the edge | |
c7b31271 | 11525 | flag array is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11526 | @code{glEdgeFlagPointer}. |
11527 | ||
11528 | @item @code{GL_EDGE_FLAG_ARRAY_BUFFER_BINDING} | |
11529 | ||
11530 | ||
11531 | @var{params} returns a single value, the name of the buffer object | |
c7b31271 | 11532 | associated with the edge flag array. This buffer object would have been |
b002944d | 11533 | bound to the target @code{GL_ARRAY_BUFFER} at the time of the most |
c7b31271 DH |
11534 | recent call to @code{glEdgeFlagPointer}. If no buffer object was bound |
11535 | to this target, 0 is returned. The initial value is 0. See | |
b002944d AW |
11536 | @code{glBindBuffer}. |
11537 | ||
11538 | @item @code{GL_EDGE_FLAG_ARRAY_STRIDE} | |
11539 | ||
11540 | ||
11541 | @var{params} returns one value, the byte offset between consecutive edge | |
c7b31271 | 11542 | flags in the edge flag array. The initial value is 0. See |
b002944d AW |
11543 | @code{glEdgeFlagPointer}. |
11544 | ||
11545 | @item @code{GL_ELEMENT_ARRAY_BUFFER_BINDING} | |
11546 | ||
11547 | ||
11548 | @var{params} returns a single value, the name of the buffer object | |
c7b31271 DH |
11549 | currently bound to the target @code{GL_ELEMENT_ARRAY_BUFFER}. If no |
11550 | buffer object is bound to this target, 0 is returned. The initial value | |
11551 | is 0. See @code{glBindBuffer}. | |
b002944d AW |
11552 | |
11553 | @item @code{GL_FEEDBACK_BUFFER_SIZE} | |
11554 | ||
11555 | ||
c7b31271 | 11556 | @var{params} returns one value, the size of the feedback buffer. See |
b002944d AW |
11557 | @code{glFeedbackBuffer}. |
11558 | ||
11559 | @item @code{GL_FEEDBACK_BUFFER_TYPE} | |
11560 | ||
11561 | ||
c7b31271 | 11562 | @var{params} returns one value, the type of the feedback buffer. See |
b002944d AW |
11563 | @code{glFeedbackBuffer}. |
11564 | ||
11565 | @item @code{GL_FOG} | |
11566 | ||
11567 | ||
11568 | @var{params} returns a single boolean value indicating whether fogging | |
c7b31271 | 11569 | is enabled. The initial value is @code{GL_FALSE}. See @code{glFog}. |
b002944d AW |
11570 | |
11571 | @item @code{GL_FOG_COORD_ARRAY} | |
11572 | ||
11573 | ||
11574 | @var{params} returns a single boolean value indicating whether the fog | |
c7b31271 | 11575 | coordinate array is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11576 | @code{glFogCoordPointer}. |
11577 | ||
11578 | @item @code{GL_FOG_COORD_ARRAY_BUFFER_BINDING} | |
11579 | ||
11580 | ||
11581 | @var{params} returns a single value, the name of the buffer object | |
c7b31271 | 11582 | associated with the fog coordinate array. This buffer object would have |
b002944d | 11583 | been bound to the target @code{GL_ARRAY_BUFFER} at the time of the most |
c7b31271 DH |
11584 | recent call to @code{glFogCoordPointer}. If no buffer object was bound |
11585 | to this target, 0 is returned. The initial value is 0. See | |
b002944d AW |
11586 | @code{glBindBuffer}. |
11587 | ||
11588 | @item @code{GL_FOG_COORD_ARRAY_STRIDE} | |
11589 | ||
11590 | ||
11591 | @var{params} returns one value, the byte offset between consecutive fog | |
c7b31271 | 11592 | coordinates in the fog coordinate array. The initial value is 0. See |
b002944d AW |
11593 | @code{glFogCoordPointer}. |
11594 | ||
11595 | @item @code{GL_FOG_COORD_ARRAY_TYPE} | |
11596 | ||
11597 | ||
11598 | @var{params} returns one value, the type of the fog coordinate array. | |
c7b31271 | 11599 | The initial value is @code{GL_FLOAT}. See @code{glFogCoordPointer}. |
b002944d AW |
11600 | |
11601 | @item @code{GL_FOG_COORD_SRC} | |
11602 | ||
11603 | ||
11604 | @var{params} returns one value, a symbolic constant indicating the | |
c7b31271 DH |
11605 | source of the fog coordinate. The initial value is |
11606 | @code{GL_FRAGMENT_DEPTH}. See @code{glFog}. | |
b002944d AW |
11607 | |
11608 | @item @code{GL_FOG_COLOR} | |
11609 | ||
11610 | ||
11611 | @var{params} returns four values: the red, green, blue, and alpha | |
c7b31271 | 11612 | components of the fog color. Integer values, if requested, are linearly |
b002944d AW |
11613 | mapped from the internal floating-point representation such that 1.0 |
11614 | returns the most positive representable integer value, and @r{-1.0} | |
c7b31271 DH |
11615 | returns the most negative representable integer value. The initial |
11616 | value is (0, 0, 0, 0). See @code{glFog}. | |
b002944d AW |
11617 | |
11618 | @item @code{GL_FOG_DENSITY} | |
11619 | ||
11620 | ||
c7b31271 DH |
11621 | @var{params} returns one value, the fog density parameter. The initial |
11622 | value is 1. See @code{glFog}. | |
b002944d AW |
11623 | |
11624 | @item @code{GL_FOG_END} | |
11625 | ||
11626 | ||
11627 | @var{params} returns one value, the end factor for the linear fog | |
c7b31271 | 11628 | equation. The initial value is 1. See @code{glFog}. |
b002944d AW |
11629 | |
11630 | @item @code{GL_FOG_HINT} | |
11631 | ||
11632 | ||
11633 | @var{params} returns one value, a symbolic constant indicating the mode | |
c7b31271 | 11634 | of the fog hint. The initial value is @code{GL_DONT_CARE}. See |
b002944d AW |
11635 | @code{glHint}. |
11636 | ||
11637 | @item @code{GL_FOG_INDEX} | |
11638 | ||
11639 | ||
c7b31271 DH |
11640 | @var{params} returns one value, the fog color index. The initial value |
11641 | is 0. See @code{glFog}. | |
b002944d AW |
11642 | |
11643 | @item @code{GL_FOG_MODE} | |
11644 | ||
11645 | ||
11646 | @var{params} returns one value, a symbolic constant indicating which fog | |
c7b31271 | 11647 | equation is selected. The initial value is @code{GL_EXP}. See |
b002944d AW |
11648 | @code{glFog}. |
11649 | ||
11650 | @item @code{GL_FOG_START} | |
11651 | ||
11652 | ||
11653 | @var{params} returns one value, the start factor for the linear fog | |
c7b31271 | 11654 | equation. The initial value is 0. See @code{glFog}. |
b002944d AW |
11655 | |
11656 | @item @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT} | |
11657 | ||
11658 | ||
11659 | @var{params} returns one value, a symbolic constant indicating the mode | |
c7b31271 DH |
11660 | of the derivative accuracy hint for fragment shaders. The initial value |
11661 | is @code{GL_DONT_CARE}. See @code{glHint}. | |
b002944d AW |
11662 | |
11663 | @item @code{GL_FRONT_FACE} | |
11664 | ||
11665 | ||
11666 | @var{params} returns one value, a symbolic constant indicating whether | |
11667 | clockwise or counterclockwise polygon winding is treated as | |
c7b31271 | 11668 | front-facing. The initial value is @code{GL_CCW}. See |
b002944d AW |
11669 | @code{glFrontFace}. |
11670 | ||
11671 | @item @code{GL_GENERATE_MIPMAP_HINT} | |
11672 | ||
11673 | ||
11674 | @var{params} returns one value, a symbolic constant indicating the mode | |
c7b31271 DH |
11675 | of the mipmap generation filtering hint. The initial value is |
11676 | @code{GL_DONT_CARE}. See @code{glHint}. | |
b002944d AW |
11677 | |
11678 | @item @code{GL_GREEN_BIAS} | |
11679 | ||
11680 | ||
11681 | @var{params} returns one value, the green bias factor used during pixel | |
c7b31271 | 11682 | transfers. The initial value is 0. |
b002944d AW |
11683 | |
11684 | @item @code{GL_GREEN_BITS} | |
11685 | ||
11686 | ||
11687 | @var{params} returns one value, the number of green bitplanes in each | |
11688 | color buffer. | |
11689 | ||
11690 | @item @code{GL_GREEN_SCALE} | |
11691 | ||
11692 | ||
11693 | @var{params} returns one value, the green scale factor used during pixel | |
c7b31271 | 11694 | transfers. The initial value is 1. See @code{glPixelTransfer}. |
b002944d AW |
11695 | |
11696 | @item @code{GL_HISTOGRAM} | |
11697 | ||
11698 | ||
11699 | @var{params} returns a single boolean value indicating whether histogram | |
c7b31271 | 11700 | is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11701 | @code{glHistogram}. |
11702 | ||
11703 | @item @code{GL_INDEX_ARRAY} | |
11704 | ||
11705 | ||
11706 | @var{params} returns a single boolean value indicating whether the color | |
c7b31271 | 11707 | index array is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11708 | @code{glIndexPointer}. |
11709 | ||
11710 | @item @code{GL_INDEX_ARRAY_BUFFER_BINDING} | |
11711 | ||
11712 | ||
11713 | @var{params} returns a single value, the name of the buffer object | |
c7b31271 | 11714 | associated with the color index array. This buffer object would have |
b002944d | 11715 | been bound to the target @code{GL_ARRAY_BUFFER} at the time of the most |
c7b31271 DH |
11716 | recent call to @code{glIndexPointer}. If no buffer object was bound to |
11717 | this target, 0 is returned. The initial value is 0. See | |
b002944d AW |
11718 | @code{glBindBuffer}. |
11719 | ||
11720 | @item @code{GL_INDEX_ARRAY_STRIDE} | |
11721 | ||
11722 | ||
11723 | @var{params} returns one value, the byte offset between consecutive | |
c7b31271 | 11724 | color indexes in the color index array. The initial value is 0. See |
b002944d AW |
11725 | @code{glIndexPointer}. |
11726 | ||
11727 | @item @code{GL_INDEX_ARRAY_TYPE} | |
11728 | ||
11729 | ||
11730 | @var{params} returns one value, the data type of indexes in the color | |
c7b31271 | 11731 | index array. The initial value is @code{GL_FLOAT}. See |
b002944d AW |
11732 | @code{glIndexPointer}. |
11733 | ||
11734 | @item @code{GL_INDEX_BITS} | |
11735 | ||
11736 | ||
11737 | @var{params} returns one value, the number of bitplanes in each color | |
11738 | index buffer. | |
11739 | ||
11740 | @item @code{GL_INDEX_CLEAR_VALUE} | |
11741 | ||
11742 | ||
11743 | @var{params} returns one value, the color index used to clear the color | |
c7b31271 | 11744 | index buffers. The initial value is 0. See @code{glClearIndex}. |
b002944d AW |
11745 | |
11746 | @item @code{GL_INDEX_LOGIC_OP} | |
11747 | ||
11748 | ||
11749 | @var{params} returns a single boolean value indicating whether a | |
11750 | fragment's index values are merged into the framebuffer using a logical | |
c7b31271 | 11751 | operation. The initial value is @code{GL_FALSE}. See @code{glLogicOp}. |
b002944d AW |
11752 | |
11753 | @item @code{GL_INDEX_MODE} | |
11754 | ||
11755 | ||
11756 | @var{params} returns a single boolean value indicating whether the GL is | |
11757 | in color index mode (@code{GL_TRUE}) or RGBA mode (@code{GL_FALSE}). | |
11758 | ||
11759 | @item @code{GL_INDEX_OFFSET} | |
11760 | ||
11761 | ||
11762 | @var{params} returns one value, the offset added to color and stencil | |
c7b31271 | 11763 | indices during pixel transfers. The initial value is 0. See |
b002944d AW |
11764 | @code{glPixelTransfer}. |
11765 | ||
11766 | @item @code{GL_INDEX_SHIFT} | |
11767 | ||
11768 | ||
11769 | @var{params} returns one value, the amount that color and stencil | |
c7b31271 | 11770 | indices are shifted during pixel transfers. The initial value is 0. See |
b002944d AW |
11771 | @code{glPixelTransfer}. |
11772 | ||
11773 | @item @code{GL_INDEX_WRITEMASK} | |
11774 | ||
11775 | ||
11776 | @var{params} returns one value, a mask indicating which bitplanes of | |
c7b31271 | 11777 | each color index buffer can be written. The initial value is all 1's. |
b002944d AW |
11778 | See @code{glIndexMask}. |
11779 | ||
11780 | @item @code{GL_LIGHT}@var{i} | |
11781 | ||
11782 | ||
11783 | @var{params} returns a single boolean value indicating whether the | |
c7b31271 | 11784 | specified light is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11785 | @code{glLight} and @code{glLightModel}. |
11786 | ||
11787 | @item @code{GL_LIGHTING} | |
11788 | ||
11789 | ||
11790 | @var{params} returns a single boolean value indicating whether lighting | |
c7b31271 | 11791 | is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11792 | @code{glLightModel}. |
11793 | ||
11794 | @item @code{GL_LIGHT_MODEL_AMBIENT} | |
11795 | ||
11796 | ||
11797 | @var{params} returns four values: the red, green, blue, and alpha | |
c7b31271 DH |
11798 | components of the ambient intensity of the entire scene. Integer |
11799 | values, if requested, are linearly mapped from the internal | |
11800 | floating-point representation such that 1.0 returns the most positive | |
11801 | representable integer value, and @r{-1.0} returns the most negative | |
11802 | representable integer value. The initial value is (0.2, 0.2, 0.2, 1.0). | |
11803 | See @code{glLightModel}. | |
b002944d AW |
11804 | |
11805 | @item @code{GL_LIGHT_MODEL_COLOR_CONTROL} | |
11806 | ||
11807 | ||
11808 | @var{params} returns single enumerated value indicating whether specular | |
11809 | reflection calculations are separated from normal lighting computations. | |
11810 | The initial value is @code{GL_SINGLE_COLOR}. | |
11811 | ||
11812 | @item @code{GL_LIGHT_MODEL_LOCAL_VIEWER} | |
11813 | ||
11814 | ||
11815 | @var{params} returns a single boolean value indicating whether specular | |
11816 | reflection calculations treat the viewer as being local to the scene. | |
c7b31271 | 11817 | The initial value is @code{GL_FALSE}. See @code{glLightModel}. |
b002944d AW |
11818 | |
11819 | @item @code{GL_LIGHT_MODEL_TWO_SIDE} | |
11820 | ||
11821 | ||
11822 | @var{params} returns a single boolean value indicating whether separate | |
11823 | materials are used to compute lighting for front- and back-facing | |
c7b31271 DH |
11824 | polygons. The initial value is @code{GL_FALSE}. See |
11825 | @code{glLightModel}. | |
b002944d AW |
11826 | |
11827 | @item @code{GL_LINE_SMOOTH} | |
11828 | ||
11829 | ||
11830 | @var{params} returns a single boolean value indicating whether | |
c7b31271 | 11831 | antialiasing of lines is enabled. The initial value is @code{GL_FALSE}. |
b002944d AW |
11832 | See @code{glLineWidth}. |
11833 | ||
11834 | @item @code{GL_LINE_SMOOTH_HINT} | |
11835 | ||
11836 | ||
11837 | @var{params} returns one value, a symbolic constant indicating the mode | |
c7b31271 DH |
11838 | of the line antialiasing hint. The initial value is |
11839 | @code{GL_DONT_CARE}. See @code{glHint}. | |
b002944d AW |
11840 | |
11841 | @item @code{GL_LINE_STIPPLE} | |
11842 | ||
11843 | ||
11844 | @var{params} returns a single boolean value indicating whether stippling | |
c7b31271 | 11845 | of lines is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11846 | @code{glLineStipple}. |
11847 | ||
11848 | @item @code{GL_LINE_STIPPLE_PATTERN} | |
11849 | ||
11850 | ||
c7b31271 DH |
11851 | @var{params} returns one value, the 16-bit line stipple pattern. The |
11852 | initial value is all 1's. See @code{glLineStipple}. | |
b002944d AW |
11853 | |
11854 | @item @code{GL_LINE_STIPPLE_REPEAT} | |
11855 | ||
11856 | ||
c7b31271 DH |
11857 | @var{params} returns one value, the line stipple repeat factor. The |
11858 | initial value is 1. See @code{glLineStipple}. | |
b002944d AW |
11859 | |
11860 | @item @code{GL_LINE_WIDTH} | |
11861 | ||
11862 | ||
11863 | @var{params} returns one value, the line width as specified with | |
c7b31271 | 11864 | @code{glLineWidth}. The initial value is 1. |
b002944d AW |
11865 | |
11866 | @item @code{GL_LINE_WIDTH_GRANULARITY} | |
11867 | ||
11868 | ||
11869 | @var{params} returns one value, the width difference between adjacent | |
c7b31271 | 11870 | supported widths for antialiased lines. See @code{glLineWidth}. |
b002944d AW |
11871 | |
11872 | @item @code{GL_LINE_WIDTH_RANGE} | |
11873 | ||
11874 | ||
11875 | @var{params} returns two values: the smallest and largest supported | |
c7b31271 | 11876 | widths for antialiased lines. See @code{glLineWidth}. |
b002944d AW |
11877 | |
11878 | @item @code{GL_LIST_BASE} | |
11879 | ||
11880 | ||
11881 | @var{params} returns one value, the base offset added to all names in | |
c7b31271 | 11882 | arrays presented to @code{glCallLists}. The initial value is 0. See |
b002944d AW |
11883 | @code{glListBase}. |
11884 | ||
11885 | @item @code{GL_LIST_INDEX} | |
11886 | ||
11887 | ||
11888 | @var{params} returns one value, the name of the display list currently | |
c7b31271 DH |
11889 | under construction. 0 is returned if no display list is currently under |
11890 | construction. The initial value is 0. See @code{glNewList}. | |
b002944d AW |
11891 | |
11892 | @item @code{GL_LIST_MODE} | |
11893 | ||
11894 | ||
11895 | @var{params} returns one value, a symbolic constant indicating the | |
c7b31271 DH |
11896 | construction mode of the display list currently under construction. The |
11897 | initial value is 0. See @code{glNewList}. | |
b002944d AW |
11898 | |
11899 | @item @code{GL_LOGIC_OP_MODE} | |
11900 | ||
11901 | ||
11902 | @var{params} returns one value, a symbolic constant indicating the | |
c7b31271 | 11903 | selected logic operation mode. The initial value is @code{GL_COPY}. See |
b002944d AW |
11904 | @code{glLogicOp}. |
11905 | ||
11906 | @item @code{GL_MAP1_COLOR_4} | |
11907 | ||
11908 | ||
11909 | @var{params} returns a single boolean value indicating whether 1D | |
c7b31271 | 11910 | evaluation generates colors. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11911 | @code{glMap1}. |
11912 | ||
11913 | @item @code{GL_MAP1_GRID_DOMAIN} | |
11914 | ||
11915 | ||
11916 | @var{params} returns two values: the endpoints of the 1D map's grid | |
c7b31271 | 11917 | domain. The initial value is (0, 1). See @code{glMapGrid}. |
b002944d AW |
11918 | |
11919 | @item @code{GL_MAP1_GRID_SEGMENTS} | |
11920 | ||
11921 | ||
11922 | @var{params} returns one value, the number of partitions in the 1D map's | |
c7b31271 | 11923 | grid domain. The initial value is 1. See @code{glMapGrid}. |
b002944d AW |
11924 | |
11925 | @item @code{GL_MAP1_INDEX} | |
11926 | ||
11927 | ||
11928 | @var{params} returns a single boolean value indicating whether 1D | |
c7b31271 DH |
11929 | evaluation generates color indices. The initial value is |
11930 | @code{GL_FALSE}. See @code{glMap1}. | |
b002944d AW |
11931 | |
11932 | @item @code{GL_MAP1_NORMAL} | |
11933 | ||
11934 | ||
11935 | @var{params} returns a single boolean value indicating whether 1D | |
c7b31271 | 11936 | evaluation generates normals. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11937 | @code{glMap1}. |
11938 | ||
11939 | @item @code{GL_MAP1_TEXTURE_COORD_1} | |
11940 | ||
11941 | ||
11942 | @var{params} returns a single boolean value indicating whether 1D | |
c7b31271 DH |
11943 | evaluation generates 1D texture coordinates. The initial value is |
11944 | @code{GL_FALSE}. See @code{glMap1}. | |
b002944d AW |
11945 | |
11946 | @item @code{GL_MAP1_TEXTURE_COORD_2} | |
11947 | ||
11948 | ||
11949 | @var{params} returns a single boolean value indicating whether 1D | |
c7b31271 DH |
11950 | evaluation generates 2D texture coordinates. The initial value is |
11951 | @code{GL_FALSE}. See @code{glMap1}. | |
b002944d AW |
11952 | |
11953 | @item @code{GL_MAP1_TEXTURE_COORD_3} | |
11954 | ||
11955 | ||
11956 | @var{params} returns a single boolean value indicating whether 1D | |
c7b31271 DH |
11957 | evaluation generates 3D texture coordinates. The initial value is |
11958 | @code{GL_FALSE}. See @code{glMap1}. | |
b002944d AW |
11959 | |
11960 | @item @code{GL_MAP1_TEXTURE_COORD_4} | |
11961 | ||
11962 | ||
11963 | @var{params} returns a single boolean value indicating whether 1D | |
c7b31271 DH |
11964 | evaluation generates 4D texture coordinates. The initial value is |
11965 | @code{GL_FALSE}. See @code{glMap1}. | |
b002944d AW |
11966 | |
11967 | @item @code{GL_MAP1_VERTEX_3} | |
11968 | ||
11969 | ||
11970 | @var{params} returns a single boolean value indicating whether 1D | |
c7b31271 DH |
11971 | evaluation generates 3D vertex coordinates. The initial value is |
11972 | @code{GL_FALSE}. See @code{glMap1}. | |
b002944d AW |
11973 | |
11974 | @item @code{GL_MAP1_VERTEX_4} | |
11975 | ||
11976 | ||
11977 | @var{params} returns a single boolean value indicating whether 1D | |
c7b31271 DH |
11978 | evaluation generates 4D vertex coordinates. The initial value is |
11979 | @code{GL_FALSE}. See @code{glMap1}. | |
b002944d AW |
11980 | |
11981 | @item @code{GL_MAP2_COLOR_4} | |
11982 | ||
11983 | ||
11984 | @var{params} returns a single boolean value indicating whether 2D | |
c7b31271 | 11985 | evaluation generates colors. The initial value is @code{GL_FALSE}. See |
b002944d AW |
11986 | @code{glMap2}. |
11987 | ||
11988 | @item @code{GL_MAP2_GRID_DOMAIN} | |
11989 | ||
11990 | ||
11991 | @var{params} returns four values: the endpoints of the 2D map's | |
c7b31271 DH |
11992 | @r{@var{i}} and @r{@var{j}} grid domains. The initial value is (0,1; |
11993 | 0,1). See @code{glMapGrid}. | |
b002944d AW |
11994 | |
11995 | @item @code{GL_MAP2_GRID_SEGMENTS} | |
11996 | ||
11997 | ||
11998 | @var{params} returns two values: the number of partitions in the 2D | |
c7b31271 DH |
11999 | map's @r{@var{i}} and @r{@var{j}} grid domains. The initial value is |
12000 | (1,1). See @code{glMapGrid}. | |
b002944d AW |
12001 | |
12002 | @item @code{GL_MAP2_INDEX} | |
12003 | ||
12004 | ||
12005 | @var{params} returns a single boolean value indicating whether 2D | |
c7b31271 DH |
12006 | evaluation generates color indices. The initial value is |
12007 | @code{GL_FALSE}. See @code{glMap2}. | |
b002944d AW |
12008 | |
12009 | @item @code{GL_MAP2_NORMAL} | |
12010 | ||
12011 | ||
12012 | @var{params} returns a single boolean value indicating whether 2D | |
c7b31271 | 12013 | evaluation generates normals. The initial value is @code{GL_FALSE}. See |
b002944d AW |
12014 | @code{glMap2}. |
12015 | ||
12016 | @item @code{GL_MAP2_TEXTURE_COORD_1} | |
12017 | ||
12018 | ||
12019 | @var{params} returns a single boolean value indicating whether 2D | |
c7b31271 DH |
12020 | evaluation generates 1D texture coordinates. The initial value is |
12021 | @code{GL_FALSE}. See @code{glMap2}. | |
b002944d AW |
12022 | |
12023 | @item @code{GL_MAP2_TEXTURE_COORD_2} | |
12024 | ||
12025 | ||
12026 | @var{params} returns a single boolean value indicating whether 2D | |
c7b31271 DH |
12027 | evaluation generates 2D texture coordinates. The initial value is |
12028 | @code{GL_FALSE}. See @code{glMap2}. | |
b002944d AW |
12029 | |
12030 | @item @code{GL_MAP2_TEXTURE_COORD_3} | |
12031 | ||
12032 | ||
12033 | @var{params} returns a single boolean value indicating whether 2D | |
c7b31271 DH |
12034 | evaluation generates 3D texture coordinates. The initial value is |
12035 | @code{GL_FALSE}. See @code{glMap2}. | |
b002944d AW |
12036 | |
12037 | @item @code{GL_MAP2_TEXTURE_COORD_4} | |
12038 | ||
12039 | ||
12040 | @var{params} returns a single boolean value indicating whether 2D | |
c7b31271 DH |
12041 | evaluation generates 4D texture coordinates. The initial value is |
12042 | @code{GL_FALSE}. See @code{glMap2}. | |
b002944d AW |
12043 | |
12044 | @item @code{GL_MAP2_VERTEX_3} | |
12045 | ||
12046 | ||
12047 | @var{params} returns a single boolean value indicating whether 2D | |
c7b31271 DH |
12048 | evaluation generates 3D vertex coordinates. The initial value is |
12049 | @code{GL_FALSE}. See @code{glMap2}. | |
b002944d AW |
12050 | |
12051 | @item @code{GL_MAP2_VERTEX_4} | |
12052 | ||
12053 | ||
12054 | @var{params} returns a single boolean value indicating whether 2D | |
c7b31271 DH |
12055 | evaluation generates 4D vertex coordinates. The initial value is |
12056 | @code{GL_FALSE}. See @code{glMap2}. | |
b002944d AW |
12057 | |
12058 | @item @code{GL_MAP_COLOR} | |
12059 | ||
12060 | ||
12061 | @var{params} returns a single boolean value indicating if colors and | |
12062 | color indices are to be replaced by table lookup during pixel transfers. | |
c7b31271 | 12063 | The initial value is @code{GL_FALSE}. See @code{glPixelTransfer}. |
b002944d AW |
12064 | |
12065 | @item @code{GL_MAP_STENCIL} | |
12066 | ||
12067 | ||
12068 | @var{params} returns a single boolean value indicating if stencil | |
c7b31271 DH |
12069 | indices are to be replaced by table lookup during pixel transfers. The |
12070 | initial value is @code{GL_FALSE}. See @code{glPixelTransfer}. | |
b002944d AW |
12071 | |
12072 | @item @code{GL_MATRIX_MODE} | |
12073 | ||
12074 | ||
12075 | @var{params} returns one value, a symbolic constant indicating which | |
c7b31271 DH |
12076 | matrix stack is currently the target of all matrix operations. The |
12077 | initial value is @code{GL_MODELVIEW}. See @code{glMatrixMode}. | |
b002944d AW |
12078 | |
12079 | @item @code{GL_MAX_3D_TEXTURE_SIZE} | |
12080 | ||
12081 | ||
12082 | @var{params} returns one value, a rough estimate of the largest 3D | |
c7b31271 DH |
12083 | texture that the GL can handle. The value must be at least 16. If the |
12084 | GL version is 1.2 or greater, use @code{GL_PROXY_TEXTURE_3D} to | |
12085 | determine if a texture is too large. See @code{glTexImage3D}. | |
b002944d AW |
12086 | |
12087 | @item @code{GL_MAX_CLIENT_ATTRIB_STACK_DEPTH} | |
12088 | ||
12089 | ||
12090 | @var{params} returns one value indicating the maximum supported depth of | |
c7b31271 | 12091 | the client attribute stack. See @code{glPushClientAttrib}. |
b002944d AW |
12092 | |
12093 | @item @code{GL_MAX_ATTRIB_STACK_DEPTH} | |
12094 | ||
12095 | ||
12096 | @var{params} returns one value, the maximum supported depth of the | |
c7b31271 DH |
12097 | attribute stack. The value must be at least 16. See |
12098 | @code{glPushAttrib}. | |
b002944d AW |
12099 | |
12100 | @item @code{GL_MAX_CLIP_PLANES} | |
12101 | ||
12102 | ||
12103 | @var{params} returns one value, the maximum number of | |
c7b31271 | 12104 | application-defined clipping planes. The value must be at least 6. See |
b002944d AW |
12105 | @code{glClipPlane}. |
12106 | ||
12107 | @item @code{GL_MAX_COLOR_MATRIX_STACK_DEPTH} | |
12108 | ||
12109 | ||
12110 | @var{params} returns one value, the maximum supported depth of the color | |
c7b31271 | 12111 | matrix stack. The value must be at least 2. See @code{glPushMatrix}. |
b002944d AW |
12112 | |
12113 | @item @code{GL_MAX_COMBINED_TEXTURE_IMAGE_UNITS} | |
12114 | ||
12115 | ||
12116 | @var{params} returns one value, the maximum supported texture image | |
12117 | units that can be used to access texture maps from the vertex shader and | |
c7b31271 | 12118 | the fragment processor combined. If both the vertex shader and the |
b002944d | 12119 | fragment processing stage access the same texture image unit, then that |
c7b31271 DH |
12120 | counts as using two texture image units against this limit. The value |
12121 | must be at least 2. See @code{glActiveTexture}. | |
b002944d AW |
12122 | |
12123 | @item @code{GL_MAX_CUBE_MAP_TEXTURE_SIZE} | |
12124 | ||
12125 | ||
c7b31271 DH |
12126 | @var{params} returns one value. The value gives a rough estimate of the |
12127 | largest cube-map texture that the GL can handle. The value must be at | |
12128 | least 16. If the GL version is 1.3 or greater, use | |
b002944d AW |
12129 | @code{GL_PROXY_TEXTURE_CUBE_MAP} to determine if a texture is too large. |
12130 | See @code{glTexImage2D}. | |
12131 | ||
12132 | @item @code{GL_MAX_DRAW_BUFFERS} | |
12133 | ||
12134 | ||
12135 | @var{params} returns one value, the maximum number of simultaneous | |
12136 | output colors allowed from a fragment shader using the | |
c7b31271 | 12137 | @code{gl_FragData} built-in array. The value must be at least 1. See |
b002944d AW |
12138 | @code{glDrawBuffers}. |
12139 | ||
12140 | @item @code{GL_MAX_ELEMENTS_INDICES} | |
12141 | ||
12142 | ||
12143 | @var{params} returns one value, the recommended maximum number of vertex | |
c7b31271 | 12144 | array indices. See @code{glDrawRangeElements}. |
b002944d AW |
12145 | |
12146 | @item @code{GL_MAX_ELEMENTS_VERTICES} | |
12147 | ||
12148 | ||
12149 | @var{params} returns one value, the recommended maximum number of vertex | |
c7b31271 | 12150 | array vertices. See @code{glDrawRangeElements}. |
b002944d AW |
12151 | |
12152 | @item @code{GL_MAX_EVAL_ORDER} | |
12153 | ||
12154 | ||
12155 | @var{params} returns one value, the maximum equation order supported by | |
c7b31271 | 12156 | 1D and 2D evaluators. The value must be at least 8. See @code{glMap1} |
b002944d AW |
12157 | and @code{glMap2}. |
12158 | ||
12159 | @item @code{GL_MAX_FRAGMENT_UNIFORM_COMPONENTS} | |
12160 | ||
12161 | ||
12162 | @var{params} returns one value, the maximum number of individual | |
12163 | floating-point, integer, or boolean values that can be held in uniform | |
c7b31271 | 12164 | variable storage for a fragment shader. The value must be at least 64. |
b002944d AW |
12165 | See @code{glUniform}. |
12166 | ||
12167 | @item @code{GL_MAX_LIGHTS} | |
12168 | ||
12169 | ||
c7b31271 DH |
12170 | @var{params} returns one value, the maximum number of lights. The value |
12171 | must be at least 8. See @code{glLight}. | |
b002944d AW |
12172 | |
12173 | @item @code{GL_MAX_LIST_NESTING} | |
12174 | ||
12175 | ||
12176 | @var{params} returns one value, the maximum recursion depth allowed | |
c7b31271 | 12177 | during display-list traversal. The value must be at least 64. See |
b002944d AW |
12178 | @code{glCallList}. |
12179 | ||
12180 | @item @code{GL_MAX_MODELVIEW_STACK_DEPTH} | |
12181 | ||
12182 | ||
12183 | @var{params} returns one value, the maximum supported depth of the | |
c7b31271 | 12184 | modelview matrix stack. The value must be at least 32. See |
b002944d AW |
12185 | @code{glPushMatrix}. |
12186 | ||
12187 | @item @code{GL_MAX_NAME_STACK_DEPTH} | |
12188 | ||
12189 | ||
12190 | @var{params} returns one value, the maximum supported depth of the | |
c7b31271 | 12191 | selection name stack. The value must be at least 64. See |
b002944d AW |
12192 | @code{glPushName}. |
12193 | ||
12194 | @item @code{GL_MAX_PIXEL_MAP_TABLE} | |
12195 | ||
12196 | ||
12197 | @var{params} returns one value, the maximum supported size of a | |
c7b31271 | 12198 | @code{glPixelMap} lookup table. The value must be at least 32. See |
b002944d AW |
12199 | @code{glPixelMap}. |
12200 | ||
12201 | @item @code{GL_MAX_PROJECTION_STACK_DEPTH} | |
12202 | ||
12203 | ||
12204 | @var{params} returns one value, the maximum supported depth of the | |
c7b31271 | 12205 | projection matrix stack. The value must be at least 2. See |
b002944d AW |
12206 | @code{glPushMatrix}. |
12207 | ||
12208 | @item @code{GL_MAX_TEXTURE_COORDS} | |
12209 | ||
12210 | ||
12211 | @var{params} returns one value, the maximum number of texture coordinate | |
c7b31271 DH |
12212 | sets available to vertex and fragment shaders. The value must be at |
12213 | least 2. See @code{glActiveTexture} and @code{glClientActiveTexture}. | |
b002944d AW |
12214 | |
12215 | @item @code{GL_MAX_TEXTURE_IMAGE_UNITS} | |
12216 | ||
12217 | ||
12218 | @var{params} returns one value, the maximum supported texture image | |
12219 | units that can be used to access texture maps from the fragment shader. | |
c7b31271 | 12220 | The value must be at least 2. See @code{glActiveTexture}. |
b002944d AW |
12221 | |
12222 | @item @code{GL_MAX_TEXTURE_LOD_BIAS} | |
12223 | ||
12224 | ||
12225 | @var{params} returns one value, the maximum, absolute value of the | |
c7b31271 | 12226 | texture level-of-detail bias. The value must be at least 4. |
b002944d AW |
12227 | |
12228 | @item @code{GL_MAX_TEXTURE_SIZE} | |
12229 | ||
12230 | ||
c7b31271 DH |
12231 | @var{params} returns one value. The value gives a rough estimate of the |
12232 | largest texture that the GL can handle. The value must be at least 64. | |
b002944d | 12233 | If the GL version is 1.1 or greater, use @code{GL_PROXY_TEXTURE_1D} or |
c7b31271 | 12234 | @code{GL_PROXY_TEXTURE_2D} to determine if a texture is too large. See |
b002944d AW |
12235 | @code{glTexImage1D} and @code{glTexImage2D}. |
12236 | ||
12237 | @item @code{GL_MAX_TEXTURE_STACK_DEPTH} | |
12238 | ||
12239 | ||
12240 | @var{params} returns one value, the maximum supported depth of the | |
c7b31271 | 12241 | texture matrix stack. The value must be at least 2. See |
b002944d AW |
12242 | @code{glPushMatrix}. |
12243 | ||
12244 | @item @code{GL_MAX_TEXTURE_UNITS} | |
12245 | ||
12246 | ||
12247 | @var{params} returns a single value indicating the number of | |
c7b31271 | 12248 | conventional texture units supported. Each conventional texture unit |
b002944d AW |
12249 | includes both a texture coordinate set and a texture image unit. |
12250 | Conventional texture units may be used for fixed-function (non-shader) | |
c7b31271 | 12251 | rendering. The value must be at least 2. Additional texture coordinate |
b002944d | 12252 | sets and texture image units may be accessed from vertex and fragment |
c7b31271 | 12253 | shaders. See @code{glActiveTexture} and @code{glClientActiveTexture}. |
b002944d AW |
12254 | |
12255 | @item @code{GL_MAX_VARYING_FLOATS} | |
12256 | ||
12257 | ||
12258 | @var{params} returns one value, the maximum number of interpolators | |
12259 | available for processing varying variables used by vertex and fragment | |
c7b31271 | 12260 | shaders. This value represents the number of individual floating-point |
b002944d | 12261 | values that can be interpolated; varying variables declared as vectors, |
c7b31271 | 12262 | matrices, and arrays will all consume multiple interpolators. The value |
b002944d AW |
12263 | must be at least 32. |
12264 | ||
12265 | @item @code{GL_MAX_VERTEX_ATTRIBS} | |
12266 | ||
12267 | ||
12268 | @var{params} returns one value, the maximum number of 4-component | |
c7b31271 DH |
12269 | generic vertex attributes accessible to a vertex shader. The value must |
12270 | be at least 16. See @code{glVertexAttrib}. | |
b002944d AW |
12271 | |
12272 | @item @code{GL_MAX_VERTEX_TEXTURE_IMAGE_UNITS} | |
12273 | ||
12274 | ||
12275 | @var{params} returns one value, the maximum supported texture image | |
12276 | units that can be used to access texture maps from the vertex shader. | |
c7b31271 | 12277 | The value may be 0. See @code{glActiveTexture}. |
b002944d AW |
12278 | |
12279 | @item @code{GL_MAX_VERTEX_UNIFORM_COMPONENTS} | |
12280 | ||
12281 | ||
12282 | @var{params} returns one value, the maximum number of individual | |
12283 | floating-point, integer, or boolean values that can be held in uniform | |
c7b31271 | 12284 | variable storage for a vertex shader. The value must be at least 512. |
b002944d AW |
12285 | See @code{glUniform}. |
12286 | ||
12287 | @item @code{GL_MAX_VIEWPORT_DIMS} | |
12288 | ||
12289 | ||
12290 | @var{params} returns two values: the maximum supported width and height | |
c7b31271 DH |
12291 | of the viewport. These must be at least as large as the visible |
12292 | dimensions of the display being rendered to. See @code{glViewport}. | |
b002944d AW |
12293 | |
12294 | @item @code{GL_MINMAX} | |
12295 | ||
12296 | ||
12297 | @var{params} returns a single boolean value indicating whether pixel | |
c7b31271 | 12298 | minmax values are computed. The initial value is @code{GL_FALSE}. See |
b002944d AW |
12299 | @code{glMinmax}. |
12300 | ||
12301 | @item @code{GL_MODELVIEW_MATRIX} | |
12302 | ||
12303 | ||
12304 | @var{params} returns sixteen values: the modelview matrix on the top of | |
c7b31271 DH |
12305 | the modelview matrix stack. Initially this matrix is the identity |
12306 | matrix. See @code{glPushMatrix}. | |
b002944d AW |
12307 | |
12308 | @item @code{GL_MODELVIEW_STACK_DEPTH} | |
12309 | ||
12310 | ||
12311 | @var{params} returns one value, the number of matrices on the modelview | |
c7b31271 | 12312 | matrix stack. The initial value is 1. See @code{glPushMatrix}. |
b002944d AW |
12313 | |
12314 | @item @code{GL_NAME_STACK_DEPTH} | |
12315 | ||
12316 | ||
12317 | @var{params} returns one value, the number of names on the selection | |
c7b31271 | 12318 | name stack. The initial value is 0. See @code{glPushName}. |
b002944d AW |
12319 | |
12320 | @item @code{GL_NORMAL_ARRAY} | |
12321 | ||
12322 | ||
12323 | @var{params} returns a single boolean value, indicating whether the | |
c7b31271 | 12324 | normal array is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
12325 | @code{glNormalPointer}. |
12326 | ||
12327 | @item @code{GL_NORMAL_ARRAY_BUFFER_BINDING} | |
12328 | ||
12329 | ||
12330 | @var{params} returns a single value, the name of the buffer object | |
c7b31271 | 12331 | associated with the normal array. This buffer object would have been |
b002944d | 12332 | bound to the target @code{GL_ARRAY_BUFFER} at the time of the most |
c7b31271 DH |
12333 | recent call to @code{glNormalPointer}. If no buffer object was bound to |
12334 | this target, 0 is returned. The initial value is 0. See | |
b002944d AW |
12335 | @code{glBindBuffer}. |
12336 | ||
12337 | @item @code{GL_NORMAL_ARRAY_STRIDE} | |
12338 | ||
12339 | ||
12340 | @var{params} returns one value, the byte offset between consecutive | |
c7b31271 | 12341 | normals in the normal array. The initial value is 0. See |
b002944d AW |
12342 | @code{glNormalPointer}. |
12343 | ||
12344 | @item @code{GL_NORMAL_ARRAY_TYPE} | |
12345 | ||
12346 | ||
12347 | @var{params} returns one value, the data type of each coordinate in the | |
c7b31271 | 12348 | normal array. The initial value is @code{GL_FLOAT}. See |
b002944d AW |
12349 | @code{glNormalPointer}. |
12350 | ||
12351 | @item @code{GL_NORMALIZE} | |
12352 | ||
12353 | ||
12354 | @var{params} returns a single boolean value indicating whether normals | |
12355 | are automatically scaled to unit length after they have been transformed | |
c7b31271 | 12356 | to eye coordinates. The initial value is @code{GL_FALSE}. See |
b002944d AW |
12357 | @code{glNormal}. |
12358 | ||
12359 | @item @code{GL_NUM_COMPRESSED_TEXTURE_FORMATS} | |
12360 | ||
12361 | ||
12362 | @var{params} returns a single integer value indicating the number of | |
c7b31271 | 12363 | available compressed texture formats. The minimum value is 0. See |
b002944d AW |
12364 | @code{glCompressedTexImage2D}. |
12365 | ||
12366 | @item @code{GL_PACK_ALIGNMENT} | |
12367 | ||
12368 | ||
12369 | @var{params} returns one value, the byte alignment used for writing | |
c7b31271 | 12370 | pixel data to memory. The initial value is 4. See @code{glPixelStore}. |
b002944d AW |
12371 | |
12372 | @item @code{GL_PACK_IMAGE_HEIGHT} | |
12373 | ||
12374 | ||
12375 | @var{params} returns one value, the image height used for writing pixel | |
c7b31271 | 12376 | data to memory. The initial value is 0. See @code{glPixelStore}. |
b002944d AW |
12377 | |
12378 | @item @code{GL_PACK_LSB_FIRST} | |
12379 | ||
12380 | ||
12381 | @var{params} returns a single boolean value indicating whether | |
12382 | single-bit pixels being written to memory are written first to the least | |
c7b31271 DH |
12383 | significant bit of each unsigned byte. The initial value is |
12384 | @code{GL_FALSE}. See @code{glPixelStore}. | |
b002944d AW |
12385 | |
12386 | @item @code{GL_PACK_ROW_LENGTH} | |
12387 | ||
12388 | ||
12389 | @var{params} returns one value, the row length used for writing pixel | |
c7b31271 | 12390 | data to memory. The initial value is 0. See @code{glPixelStore}. |
b002944d AW |
12391 | |
12392 | @item @code{GL_PACK_SKIP_IMAGES} | |
12393 | ||
12394 | ||
12395 | @var{params} returns one value, the number of pixel images skipped | |
c7b31271 | 12396 | before the first pixel is written into memory. The initial value is 0. |
b002944d AW |
12397 | See @code{glPixelStore}. |
12398 | ||
12399 | @item @code{GL_PACK_SKIP_PIXELS} | |
12400 | ||
12401 | ||
12402 | @var{params} returns one value, the number of pixel locations skipped | |
c7b31271 | 12403 | before the first pixel is written into memory. The initial value is 0. |
b002944d AW |
12404 | See @code{glPixelStore}. |
12405 | ||
12406 | @item @code{GL_PACK_SKIP_ROWS} | |
12407 | ||
12408 | ||
12409 | @var{params} returns one value, the number of rows of pixel locations | |
c7b31271 DH |
12410 | skipped before the first pixel is written into memory. The initial |
12411 | value is 0. See @code{glPixelStore}. | |
b002944d AW |
12412 | |
12413 | @item @code{GL_PACK_SWAP_BYTES} | |
12414 | ||
12415 | ||
12416 | @var{params} returns a single boolean value indicating whether the bytes | |
12417 | of two-byte and four-byte pixel indices and components are swapped | |
c7b31271 | 12418 | before being written to memory. The initial value is @code{GL_FALSE}. |
b002944d AW |
12419 | See @code{glPixelStore}. |
12420 | ||
12421 | @item @code{GL_PERSPECTIVE_CORRECTION_HINT} | |
12422 | ||
12423 | ||
12424 | @var{params} returns one value, a symbolic constant indicating the mode | |
c7b31271 DH |
12425 | of the perspective correction hint. The initial value is |
12426 | @code{GL_DONT_CARE}. See @code{glHint}. | |
b002944d AW |
12427 | |
12428 | @item @code{GL_PIXEL_MAP_A_TO_A_SIZE} | |
12429 | ||
12430 | ||
12431 | @var{params} returns one value, the size of the alpha-to-alpha pixel | |
c7b31271 | 12432 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12433 | |
12434 | @item @code{GL_PIXEL_MAP_B_TO_B_SIZE} | |
12435 | ||
12436 | ||
12437 | @var{params} returns one value, the size of the blue-to-blue pixel | |
c7b31271 | 12438 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12439 | |
12440 | @item @code{GL_PIXEL_MAP_G_TO_G_SIZE} | |
12441 | ||
12442 | ||
12443 | @var{params} returns one value, the size of the green-to-green pixel | |
c7b31271 | 12444 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12445 | |
12446 | @item @code{GL_PIXEL_MAP_I_TO_A_SIZE} | |
12447 | ||
12448 | ||
12449 | @var{params} returns one value, the size of the index-to-alpha pixel | |
c7b31271 | 12450 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12451 | |
12452 | @item @code{GL_PIXEL_MAP_I_TO_B_SIZE} | |
12453 | ||
12454 | ||
12455 | @var{params} returns one value, the size of the index-to-blue pixel | |
c7b31271 | 12456 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12457 | |
12458 | @item @code{GL_PIXEL_MAP_I_TO_G_SIZE} | |
12459 | ||
12460 | ||
12461 | @var{params} returns one value, the size of the index-to-green pixel | |
c7b31271 | 12462 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12463 | |
12464 | @item @code{GL_PIXEL_MAP_I_TO_I_SIZE} | |
12465 | ||
12466 | ||
12467 | @var{params} returns one value, the size of the index-to-index pixel | |
c7b31271 | 12468 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12469 | |
12470 | @item @code{GL_PIXEL_MAP_I_TO_R_SIZE} | |
12471 | ||
12472 | ||
12473 | @var{params} returns one value, the size of the index-to-red pixel | |
c7b31271 | 12474 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12475 | |
12476 | @item @code{GL_PIXEL_MAP_R_TO_R_SIZE} | |
12477 | ||
12478 | ||
12479 | @var{params} returns one value, the size of the red-to-red pixel | |
c7b31271 | 12480 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12481 | |
12482 | @item @code{GL_PIXEL_MAP_S_TO_S_SIZE} | |
12483 | ||
12484 | ||
12485 | @var{params} returns one value, the size of the stencil-to-stencil pixel | |
c7b31271 | 12486 | translation table. The initial value is 1. See @code{glPixelMap}. |
b002944d AW |
12487 | |
12488 | @item @code{GL_PIXEL_PACK_BUFFER_BINDING} | |
12489 | ||
12490 | ||
12491 | @var{params} returns a single value, the name of the buffer object | |
c7b31271 DH |
12492 | currently bound to the target @code{GL_PIXEL_PACK_BUFFER}. If no buffer |
12493 | object is bound to this target, 0 is returned. The initial value is 0. | |
b002944d AW |
12494 | See @code{glBindBuffer}. |
12495 | ||
12496 | @item @code{GL_PIXEL_UNPACK_BUFFER_BINDING} | |
12497 | ||
12498 | ||
12499 | @var{params} returns a single value, the name of the buffer object | |
c7b31271 DH |
12500 | currently bound to the target @code{GL_PIXEL_UNPACK_BUFFER}. If no |
12501 | buffer object is bound to this target, 0 is returned. The initial value | |
12502 | is 0. See @code{glBindBuffer}. | |
b002944d AW |
12503 | |
12504 | @item @code{GL_POINT_DISTANCE_ATTENUATION} | |
12505 | ||
12506 | ||
12507 | @var{params} returns three values, the coefficients for computing the | |
c7b31271 | 12508 | attenuation value for points. See @code{glPointParameter}. |
b002944d AW |
12509 | |
12510 | @item @code{GL_POINT_FADE_THRESHOLD_SIZE} | |
12511 | ||
12512 | ||
12513 | @var{params} returns one value, the point size threshold for determining | |
c7b31271 | 12514 | the point size. See @code{glPointParameter}. |
b002944d AW |
12515 | |
12516 | @item @code{GL_POINT_SIZE} | |
12517 | ||
12518 | ||
12519 | @var{params} returns one value, the point size as specified by | |
c7b31271 | 12520 | @code{glPointSize}. The initial value is 1. |
b002944d AW |
12521 | |
12522 | @item @code{GL_POINT_SIZE_GRANULARITY} | |
12523 | ||
12524 | ||
12525 | @var{params} returns one value, the size difference between adjacent | |
c7b31271 | 12526 | supported sizes for antialiased points. See @code{glPointSize}. |
b002944d AW |
12527 | |
12528 | @item @code{GL_POINT_SIZE_MAX} | |
12529 | ||
12530 | ||
12531 | @var{params} returns one value, the upper bound for the attenuated point | |
c7b31271 | 12532 | sizes. The initial value is 0.0. See @code{glPointParameter}. |
b002944d AW |
12533 | |
12534 | @item @code{GL_POINT_SIZE_MIN} | |
12535 | ||
12536 | ||
12537 | @var{params} returns one value, the lower bound for the attenuated point | |
c7b31271 | 12538 | sizes. The initial value is 1.0. See @code{glPointParameter}. |
b002944d AW |
12539 | |
12540 | @item @code{GL_POINT_SIZE_RANGE} | |
12541 | ||
12542 | ||
12543 | @var{params} returns two values: the smallest and largest supported | |
c7b31271 DH |
12544 | sizes for antialiased points. The smallest size must be at most 1, and |
12545 | the largest size must be at least 1. See @code{glPointSize}. | |
b002944d AW |
12546 | |
12547 | @item @code{GL_POINT_SMOOTH} | |
12548 | ||
12549 | ||
12550 | @var{params} returns a single boolean value indicating whether | |
c7b31271 DH |
12551 | antialiasing of points is enabled. The initial value is |
12552 | @code{GL_FALSE}. See @code{glPointSize}. | |
b002944d AW |
12553 | |
12554 | @item @code{GL_POINT_SMOOTH_HINT} | |
12555 | ||
12556 | ||
12557 | @var{params} returns one value, a symbolic constant indicating the mode | |
c7b31271 DH |
12558 | of the point antialiasing hint. The initial value is |
12559 | @code{GL_DONT_CARE}. See @code{glHint}. | |
b002944d AW |
12560 | |
12561 | @item @code{GL_POINT_SPRITE} | |
12562 | ||
12563 | ||
12564 | @var{params} returns a single boolean value indicating whether point | |
c7b31271 | 12565 | sprite is enabled. The initial value is @code{GL_FALSE}. |
b002944d AW |
12566 | |
12567 | @item @code{GL_POLYGON_MODE} | |
12568 | ||
12569 | ||
12570 | @var{params} returns two values: symbolic constants indicating whether | |
12571 | front-facing and back-facing polygons are rasterized as points, lines, | |
c7b31271 | 12572 | or filled polygons. The initial value is @code{GL_FILL}. See |
b002944d AW |
12573 | @code{glPolygonMode}. |
12574 | ||
12575 | @item @code{GL_POLYGON_OFFSET_FACTOR} | |
12576 | ||
12577 | ||
12578 | @var{params} returns one value, the scaling factor used to determine the | |
12579 | variable offset that is added to the depth value of each fragment | |
c7b31271 | 12580 | generated when a polygon is rasterized. The initial value is 0. See |
b002944d AW |
12581 | @code{glPolygonOffset}. |
12582 | ||
12583 | @item @code{GL_POLYGON_OFFSET_UNITS} | |
12584 | ||
12585 | ||
c7b31271 | 12586 | @var{params} returns one value. This value is multiplied by an |
b002944d | 12587 | implementation-specific value and then added to the depth value of each |
c7b31271 DH |
12588 | fragment generated when a polygon is rasterized. The initial value is |
12589 | 0. See @code{glPolygonOffset}. | |
b002944d AW |
12590 | |
12591 | @item @code{GL_POLYGON_OFFSET_FILL} | |
12592 | ||
12593 | ||
12594 | @var{params} returns a single boolean value indicating whether polygon | |
c7b31271 DH |
12595 | offset is enabled for polygons in fill mode. The initial value is |
12596 | @code{GL_FALSE}. See @code{glPolygonOffset}. | |
b002944d AW |
12597 | |
12598 | @item @code{GL_POLYGON_OFFSET_LINE} | |
12599 | ||
12600 | ||
12601 | @var{params} returns a single boolean value indicating whether polygon | |
c7b31271 DH |
12602 | offset is enabled for polygons in line mode. The initial value is |
12603 | @code{GL_FALSE}. See @code{glPolygonOffset}. | |
b002944d AW |
12604 | |
12605 | @item @code{GL_POLYGON_OFFSET_POINT} | |
12606 | ||
12607 | ||
12608 | @var{params} returns a single boolean value indicating whether polygon | |
c7b31271 DH |
12609 | offset is enabled for polygons in point mode. The initial value is |
12610 | @code{GL_FALSE}. See @code{glPolygonOffset}. | |
b002944d AW |
12611 | |
12612 | @item @code{GL_POLYGON_SMOOTH} | |
12613 | ||
12614 | ||
12615 | @var{params} returns a single boolean value indicating whether | |
c7b31271 DH |
12616 | antialiasing of polygons is enabled. The initial value is |
12617 | @code{GL_FALSE}. See @code{glPolygonMode}. | |
b002944d AW |
12618 | |
12619 | @item @code{GL_POLYGON_SMOOTH_HINT} | |
12620 | ||
12621 | ||
12622 | @var{params} returns one value, a symbolic constant indicating the mode | |
c7b31271 DH |
12623 | of the polygon antialiasing hint. The initial value is |
12624 | @code{GL_DONT_CARE}. See @code{glHint}. | |
b002944d AW |
12625 | |
12626 | @item @code{GL_POLYGON_STIPPLE} | |
12627 | ||
12628 | ||
12629 | @var{params} returns a single boolean value indicating whether polygon | |
c7b31271 | 12630 | stippling is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
12631 | @code{glPolygonStipple}. |
12632 | ||
12633 | @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} | |
12634 | ||
12635 | ||
12636 | @var{params} returns a single boolean value indicating whether post | |
c7b31271 DH |
12637 | color matrix transformation lookup is enabled. The initial value is |
12638 | @code{GL_FALSE}. See @code{glColorTable}. | |
b002944d AW |
12639 | |
12640 | @item @code{GL_POST_COLOR_MATRIX_RED_BIAS} | |
12641 | ||
12642 | ||
12643 | @var{params} returns one value, the red bias factor applied to RGBA | |
c7b31271 | 12644 | fragments after color matrix transformations. The initial value is 0. |
b002944d AW |
12645 | See @code{glPixelTransfer}. |
12646 | ||
12647 | @item @code{GL_POST_COLOR_MATRIX_GREEN_BIAS} | |
12648 | ||
12649 | ||
12650 | @var{params} returns one value, the green bias factor applied to RGBA | |
c7b31271 | 12651 | fragments after color matrix transformations. The initial value is 0. |
b002944d AW |
12652 | See @code{glPixelTransfer} |
12653 | ||
12654 | @item @code{GL_POST_COLOR_MATRIX_BLUE_BIAS} | |
12655 | ||
12656 | ||
12657 | @var{params} returns one value, the blue bias factor applied to RGBA | |
c7b31271 | 12658 | fragments after color matrix transformations. The initial value is 0. |
b002944d AW |
12659 | See @code{glPixelTransfer}. |
12660 | ||
12661 | @item @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS} | |
12662 | ||
12663 | ||
12664 | @var{params} returns one value, the alpha bias factor applied to RGBA | |
c7b31271 | 12665 | fragments after color matrix transformations. The initial value is 0. |
b002944d AW |
12666 | See @code{glPixelTransfer}. |
12667 | ||
12668 | @item @code{GL_POST_COLOR_MATRIX_RED_SCALE} | |
12669 | ||
12670 | ||
12671 | @var{params} returns one value, the red scale factor applied to RGBA | |
c7b31271 | 12672 | fragments after color matrix transformations. The initial value is 1. |
b002944d AW |
12673 | See @code{glPixelTransfer}. |
12674 | ||
12675 | @item @code{GL_POST_COLOR_MATRIX_GREEN_SCALE} | |
12676 | ||
12677 | ||
12678 | @var{params} returns one value, the green scale factor applied to RGBA | |
c7b31271 | 12679 | fragments after color matrix transformations. The initial value is 1. |
b002944d AW |
12680 | See @code{glPixelTransfer}. |
12681 | ||
12682 | @item @code{GL_POST_COLOR_MATRIX_BLUE_SCALE} | |
12683 | ||
12684 | ||
12685 | @var{params} returns one value, the blue scale factor applied to RGBA | |
c7b31271 | 12686 | fragments after color matrix transformations. The initial value is 1. |
b002944d AW |
12687 | See @code{glPixelTransfer}. |
12688 | ||
12689 | @item @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE} | |
12690 | ||
12691 | ||
12692 | @var{params} returns one value, the alpha scale factor applied to RGBA | |
c7b31271 | 12693 | fragments after color matrix transformations. The initial value is 1. |
b002944d AW |
12694 | See @code{glPixelTransfer}. |
12695 | ||
12696 | @item @code{GL_POST_CONVOLUTION_COLOR_TABLE} | |
12697 | ||
12698 | ||
12699 | @var{params} returns a single boolean value indicating whether post | |
c7b31271 DH |
12700 | convolution lookup is enabled. The initial value is @code{GL_FALSE}. |
12701 | See @code{glColorTable}. | |
b002944d AW |
12702 | |
12703 | @item @code{GL_POST_CONVOLUTION_RED_BIAS} | |
12704 | ||
12705 | ||
12706 | @var{params} returns one value, the red bias factor applied to RGBA | |
c7b31271 | 12707 | fragments after convolution. The initial value is 0. See |
b002944d AW |
12708 | @code{glPixelTransfer}. |
12709 | ||
12710 | @item @code{GL_POST_CONVOLUTION_GREEN_BIAS} | |
12711 | ||
12712 | ||
12713 | @var{params} returns one value, the green bias factor applied to RGBA | |
c7b31271 | 12714 | fragments after convolution. The initial value is 0. See |
b002944d AW |
12715 | @code{glPixelTransfer}. |
12716 | ||
12717 | @item @code{GL_POST_CONVOLUTION_BLUE_BIAS} | |
12718 | ||
12719 | ||
12720 | @var{params} returns one value, the blue bias factor applied to RGBA | |
c7b31271 | 12721 | fragments after convolution. The initial value is 0. See |
b002944d AW |
12722 | @code{glPixelTransfer}. |
12723 | ||
12724 | @item @code{GL_POST_CONVOLUTION_ALPHA_BIAS} | |
12725 | ||
12726 | ||
12727 | @var{params} returns one value, the alpha bias factor applied to RGBA | |
c7b31271 | 12728 | fragments after convolution. The initial value is 0. See |
b002944d AW |
12729 | @code{glPixelTransfer}. |
12730 | ||
12731 | @item @code{GL_POST_CONVOLUTION_RED_SCALE} | |
12732 | ||
12733 | ||
12734 | @var{params} returns one value, the red scale factor applied to RGBA | |
c7b31271 | 12735 | fragments after convolution. The initial value is 1. See |
b002944d AW |
12736 | @code{glPixelTransfer}. |
12737 | ||
12738 | @item @code{GL_POST_CONVOLUTION_GREEN_SCALE} | |
12739 | ||
12740 | ||
12741 | @var{params} returns one value, the green scale factor applied to RGBA | |
c7b31271 | 12742 | fragments after convolution. The initial value is 1. See |
b002944d AW |
12743 | @code{glPixelTransfer}. |
12744 | ||
12745 | @item @code{GL_POST_CONVOLUTION_BLUE_SCALE} | |
12746 | ||
12747 | ||
12748 | @var{params} returns one value, the blue scale factor applied to RGBA | |
c7b31271 | 12749 | fragments after convolution. The initial value is 1. See |
b002944d AW |
12750 | @code{glPixelTransfer}. |
12751 | ||
12752 | @item @code{GL_POST_CONVOLUTION_ALPHA_SCALE} | |
12753 | ||
12754 | ||
12755 | @var{params} returns one value, the alpha scale factor applied to RGBA | |
c7b31271 | 12756 | fragments after convolution. The initial value is 1. See |
b002944d AW |
12757 | @code{glPixelTransfer}. |
12758 | ||
12759 | @item @code{GL_PROJECTION_MATRIX} | |
12760 | ||
12761 | ||
12762 | @var{params} returns sixteen values: the projection matrix on the top of | |
c7b31271 DH |
12763 | the projection matrix stack. Initially this matrix is the identity |
12764 | matrix. See @code{glPushMatrix}. | |
b002944d AW |
12765 | |
12766 | @item @code{GL_PROJECTION_STACK_DEPTH} | |
12767 | ||
12768 | ||
12769 | @var{params} returns one value, the number of matrices on the projection | |
c7b31271 | 12770 | matrix stack. The initial value is 1. See @code{glPushMatrix}. |
b002944d AW |
12771 | |
12772 | @item @code{GL_READ_BUFFER} | |
12773 | ||
12774 | ||
12775 | @var{params} returns one value, a symbolic constant indicating which | |
c7b31271 | 12776 | color buffer is selected for reading. The initial value is |
b002944d | 12777 | @code{GL_BACK} if there is a back buffer, otherwise it is |
c7b31271 | 12778 | @code{GL_FRONT}. See @code{glReadPixels} and @code{glAccum}. |
b002944d AW |
12779 | |
12780 | @item @code{GL_RED_BIAS} | |
12781 | ||
12782 | ||
12783 | @var{params} returns one value, the red bias factor used during pixel | |
c7b31271 | 12784 | transfers. The initial value is 0. |
b002944d AW |
12785 | |
12786 | @item @code{GL_RED_BITS} | |
12787 | ||
12788 | ||
12789 | @var{params} returns one value, the number of red bitplanes in each | |
12790 | color buffer. | |
12791 | ||
12792 | @item @code{GL_RED_SCALE} | |
12793 | ||
12794 | ||
12795 | @var{params} returns one value, the red scale factor used during pixel | |
c7b31271 | 12796 | transfers. The initial value is 1. See @code{glPixelTransfer}. |
b002944d AW |
12797 | |
12798 | @item @code{GL_RENDER_MODE} | |
12799 | ||
12800 | ||
12801 | @var{params} returns one value, a symbolic constant indicating whether | |
c7b31271 DH |
12802 | the GL is in render, select, or feedback mode. The initial value is |
12803 | @code{GL_RENDER}. See @code{glRenderMode}. | |
b002944d AW |
12804 | |
12805 | @item @code{GL_RESCALE_NORMAL} | |
12806 | ||
12807 | ||
12808 | @var{params} returns single boolean value indicating whether normal | |
c7b31271 | 12809 | rescaling is enabled. See @code{glEnable}. |
b002944d AW |
12810 | |
12811 | @item @code{GL_RGBA_MODE} | |
12812 | ||
12813 | ||
12814 | @var{params} returns a single boolean value indicating whether the GL is | |
c7b31271 | 12815 | in RGBA mode (true) or color index mode (false). See @code{glColor}. |
b002944d AW |
12816 | |
12817 | @item @code{GL_SAMPLE_BUFFERS} | |
12818 | ||
12819 | ||
12820 | @var{params} returns a single integer value indicating the number of | |
c7b31271 | 12821 | sample buffers associated with the framebuffer. See |
b002944d AW |
12822 | @code{glSampleCoverage}. |
12823 | ||
12824 | @item @code{GL_SAMPLE_COVERAGE_VALUE} | |
12825 | ||
12826 | ||
12827 | @var{params} returns a single positive floating-point value indicating | |
c7b31271 | 12828 | the current sample coverage value. See @code{glSampleCoverage}. |
b002944d AW |
12829 | |
12830 | @item @code{GL_SAMPLE_COVERAGE_INVERT} | |
12831 | ||
12832 | ||
12833 | @var{params} returns a single boolean value indicating if the temporary | |
c7b31271 | 12834 | coverage value should be inverted. See @code{glSampleCoverage}. |
b002944d AW |
12835 | |
12836 | @item @code{GL_SAMPLES} | |
12837 | ||
12838 | ||
12839 | @var{params} returns a single integer value indicating the coverage mask | |
c7b31271 | 12840 | size. See @code{glSampleCoverage}. |
b002944d AW |
12841 | |
12842 | @item @code{GL_SCISSOR_BOX} | |
12843 | ||
12844 | ||
12845 | @var{params} returns four values: the @r{@var{x}} and @r{@var{y}} window | |
12846 | coordinates of the scissor box, followed by its width and height. | |
12847 | Initially the @r{@var{x}} and @r{@var{y}} window coordinates are both 0 | |
c7b31271 | 12848 | and the width and height are set to the size of the window. See |
b002944d AW |
12849 | @code{glScissor}. |
12850 | ||
12851 | @item @code{GL_SCISSOR_TEST} | |
12852 | ||
12853 | ||
12854 | @var{params} returns a single boolean value indicating whether | |
c7b31271 | 12855 | scissoring is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
12856 | @code{glScissor}. |
12857 | ||
12858 | @item @code{GL_SECONDARY_COLOR_ARRAY} | |
12859 | ||
12860 | ||
12861 | @var{params} returns a single boolean value indicating whether the | |
c7b31271 | 12862 | secondary color array is enabled. The initial value is @code{GL_FALSE}. |
b002944d AW |
12863 | See @code{glSecondaryColorPointer}. |
12864 | ||
12865 | @item @code{GL_SECONDARY_COLOR_ARRAY_BUFFER_BINDING} | |
12866 | ||
12867 | ||
12868 | @var{params} returns a single value, the name of the buffer object | |
c7b31271 DH |
12869 | associated with the secondary color array. This buffer object would |
12870 | have been bound to the target @code{GL_ARRAY_BUFFER} at the time of the | |
12871 | most recent call to @code{glSecondaryColorPointer}. If no buffer object | |
12872 | was bound to this target, 0 is returned. The initial value is 0. See | |
b002944d AW |
12873 | @code{glBindBuffer}. |
12874 | ||
12875 | @item @code{GL_SECONDARY_COLOR_ARRAY_SIZE} | |
12876 | ||
12877 | ||
12878 | @var{params} returns one value, the number of components per color in | |
c7b31271 | 12879 | the secondary color array. The initial value is 3. See |
b002944d AW |
12880 | @code{glSecondaryColorPointer}. |
12881 | ||
12882 | @item @code{GL_SECONDARY_COLOR_ARRAY_STRIDE} | |
12883 | ||
12884 | ||
12885 | @var{params} returns one value, the byte offset between consecutive | |
c7b31271 | 12886 | colors in the secondary color array. The initial value is 0. See |
b002944d AW |
12887 | @code{glSecondaryColorPointer}. |
12888 | ||
12889 | @item @code{GL_SECONDARY_COLOR_ARRAY_TYPE} | |
12890 | ||
12891 | ||
12892 | @var{params} returns one value, the data type of each component in the | |
c7b31271 | 12893 | secondary color array. The initial value is @code{GL_FLOAT}. See |
b002944d AW |
12894 | @code{glSecondaryColorPointer}. |
12895 | ||
12896 | @item @code{GL_SELECTION_BUFFER_SIZE} | |
12897 | ||
12898 | ||
c7b31271 | 12899 | @var{params} return one value, the size of the selection buffer. See |
b002944d AW |
12900 | @code{glSelectBuffer}. |
12901 | ||
12902 | @item @code{GL_SEPARABLE_2D} | |
12903 | ||
12904 | ||
12905 | @var{params} returns a single boolean value indicating whether 2D | |
c7b31271 | 12906 | separable convolution is enabled. The initial value is @code{GL_FALSE}. |
b002944d AW |
12907 | See @code{glSeparableFilter2D}. |
12908 | ||
12909 | @item @code{GL_SHADE_MODEL} | |
12910 | ||
12911 | ||
12912 | @var{params} returns one value, a symbolic constant indicating whether | |
c7b31271 DH |
12913 | the shading mode is flat or smooth. The initial value is |
12914 | @code{GL_SMOOTH}. See @code{glShadeModel}. | |
b002944d AW |
12915 | |
12916 | @item @code{GL_SMOOTH_LINE_WIDTH_RANGE} | |
12917 | ||
12918 | ||
12919 | @var{params} returns two values, the smallest and largest supported | |
c7b31271 | 12920 | widths for antialiased lines. See @code{glLineWidth}. |
b002944d AW |
12921 | |
12922 | @item @code{GL_SMOOTH_LINE_WIDTH_GRANULARITY} | |
12923 | ||
12924 | ||
12925 | @var{params} returns one value, the granularity of widths for | |
c7b31271 | 12926 | antialiased lines. See @code{glLineWidth}. |
b002944d AW |
12927 | |
12928 | @item @code{GL_SMOOTH_POINT_SIZE_RANGE} | |
12929 | ||
12930 | ||
12931 | @var{params} returns two values, the smallest and largest supported | |
c7b31271 | 12932 | widths for antialiased points. See @code{glPointSize}. |
b002944d AW |
12933 | |
12934 | @item @code{GL_SMOOTH_POINT_SIZE_GRANULARITY} | |
12935 | ||
12936 | ||
12937 | @var{params} returns one value, the granularity of sizes for antialiased | |
c7b31271 | 12938 | points. See @code{glPointSize}. |
b002944d AW |
12939 | |
12940 | @item @code{GL_STENCIL_BACK_FAIL} | |
12941 | ||
12942 | ||
12943 | @var{params} returns one value, a symbolic constant indicating what | |
12944 | action is taken for back-facing polygons when the stencil test fails. | |
c7b31271 | 12945 | The initial value is @code{GL_KEEP}. See @code{glStencilOpSeparate}. |
b002944d AW |
12946 | |
12947 | @item @code{GL_STENCIL_BACK_FUNC} | |
12948 | ||
12949 | ||
12950 | @var{params} returns one value, a symbolic constant indicating what | |
12951 | function is used for back-facing polygons to compare the stencil | |
c7b31271 DH |
12952 | reference value with the stencil buffer value. The initial value is |
12953 | @code{GL_ALWAYS}. See @code{glStencilFuncSeparate}. | |
b002944d AW |
12954 | |
12955 | @item @code{GL_STENCIL_BACK_PASS_DEPTH_FAIL} | |
12956 | ||
12957 | ||
12958 | @var{params} returns one value, a symbolic constant indicating what | |
12959 | action is taken for back-facing polygons when the stencil test passes, | |
c7b31271 | 12960 | but the depth test fails. The initial value is @code{GL_KEEP}. See |
b002944d AW |
12961 | @code{glStencilOpSeparate}. |
12962 | ||
12963 | @item @code{GL_STENCIL_BACK_PASS_DEPTH_PASS} | |
12964 | ||
12965 | ||
12966 | @var{params} returns one value, a symbolic constant indicating what | |
12967 | action is taken for back-facing polygons when the stencil test passes | |
c7b31271 | 12968 | and the depth test passes. The initial value is @code{GL_KEEP}. See |
b002944d AW |
12969 | @code{glStencilOpSeparate}. |
12970 | ||
12971 | @item @code{GL_STENCIL_BACK_REF} | |
12972 | ||
12973 | ||
12974 | @var{params} returns one value, the reference value that is compared | |
c7b31271 DH |
12975 | with the contents of the stencil buffer for back-facing polygons. The |
12976 | initial value is 0. See @code{glStencilFuncSeparate}. | |
b002944d AW |
12977 | |
12978 | @item @code{GL_STENCIL_BACK_VALUE_MASK} | |
12979 | ||
12980 | ||
12981 | @var{params} returns one value, the mask that is used for back-facing | |
12982 | polygons to mask both the stencil reference value and the stencil buffer | |
c7b31271 | 12983 | value before they are compared. The initial value is all 1's. See |
b002944d AW |
12984 | @code{glStencilFuncSeparate}. |
12985 | ||
12986 | @item @code{GL_STENCIL_BACK_WRITEMASK} | |
12987 | ||
12988 | ||
12989 | @var{params} returns one value, the mask that controls writing of the | |
c7b31271 DH |
12990 | stencil bitplanes for back-facing polygons. The initial value is all |
12991 | 1's. See @code{glStencilMaskSeparate}. | |
b002944d AW |
12992 | |
12993 | @item @code{GL_STENCIL_BITS} | |
12994 | ||
12995 | ||
12996 | @var{params} returns one value, the number of bitplanes in the stencil | |
12997 | buffer. | |
12998 | ||
12999 | @item @code{GL_STENCIL_CLEAR_VALUE} | |
13000 | ||
13001 | ||
13002 | @var{params} returns one value, the index to which the stencil bitplanes | |
c7b31271 | 13003 | are cleared. The initial value is 0. See @code{glClearStencil}. |
b002944d AW |
13004 | |
13005 | @item @code{GL_STENCIL_FAIL} | |
13006 | ||
13007 | ||
13008 | @var{params} returns one value, a symbolic constant indicating what | |
c7b31271 DH |
13009 | action is taken when the stencil test fails. The initial value is |
13010 | @code{GL_KEEP}. See @code{glStencilOp}. If the GL version is 2.0 or | |
b002944d | 13011 | greater, this stencil state only affects non-polygons and front-facing |
c7b31271 | 13012 | polygons. Back-facing polygons use separate stencil state. See |
b002944d AW |
13013 | @code{glStencilOpSeparate}. |
13014 | ||
13015 | @item @code{GL_STENCIL_FUNC} | |
13016 | ||
13017 | ||
13018 | @var{params} returns one value, a symbolic constant indicating what | |
13019 | function is used to compare the stencil reference value with the stencil | |
c7b31271 DH |
13020 | buffer value. The initial value is @code{GL_ALWAYS}. See |
13021 | @code{glStencilFunc}. If the GL version is 2.0 or greater, this stencil | |
13022 | state only affects non-polygons and front-facing polygons. Back-facing | |
13023 | polygons use separate stencil state. See @code{glStencilFuncSeparate}. | |
b002944d AW |
13024 | |
13025 | @item @code{GL_STENCIL_PASS_DEPTH_FAIL} | |
13026 | ||
13027 | ||
13028 | @var{params} returns one value, a symbolic constant indicating what | |
13029 | action is taken when the stencil test passes, but the depth test fails. | |
c7b31271 | 13030 | The initial value is @code{GL_KEEP}. See @code{glStencilOp}. If the GL |
b002944d | 13031 | version is 2.0 or greater, this stencil state only affects non-polygons |
c7b31271 DH |
13032 | and front-facing polygons. Back-facing polygons use separate stencil |
13033 | state. See @code{glStencilOpSeparate}. | |
b002944d AW |
13034 | |
13035 | @item @code{GL_STENCIL_PASS_DEPTH_PASS} | |
13036 | ||
13037 | ||
13038 | @var{params} returns one value, a symbolic constant indicating what | |
13039 | action is taken when the stencil test passes and the depth test passes. | |
c7b31271 | 13040 | The initial value is @code{GL_KEEP}. See @code{glStencilOp}. If the GL |
b002944d | 13041 | version is 2.0 or greater, this stencil state only affects non-polygons |
c7b31271 DH |
13042 | and front-facing polygons. Back-facing polygons use separate stencil |
13043 | state. See @code{glStencilOpSeparate}. | |
b002944d AW |
13044 | |
13045 | @item @code{GL_STENCIL_REF} | |
13046 | ||
13047 | ||
13048 | @var{params} returns one value, the reference value that is compared | |
c7b31271 DH |
13049 | with the contents of the stencil buffer. The initial value is 0. See |
13050 | @code{glStencilFunc}. If the GL version is 2.0 or greater, this stencil | |
13051 | state only affects non-polygons and front-facing polygons. Back-facing | |
13052 | polygons use separate stencil state. See @code{glStencilFuncSeparate}. | |
b002944d AW |
13053 | |
13054 | @item @code{GL_STENCIL_TEST} | |
13055 | ||
13056 | ||
13057 | @var{params} returns a single boolean value indicating whether stencil | |
c7b31271 | 13058 | testing of fragments is enabled. The initial value is @code{GL_FALSE}. |
b002944d AW |
13059 | See @code{glStencilFunc} and @code{glStencilOp}. |
13060 | ||
13061 | @item @code{GL_STENCIL_VALUE_MASK} | |
13062 | ||
13063 | ||
13064 | @var{params} returns one value, the mask that is used to mask both the | |
13065 | stencil reference value and the stencil buffer value before they are | |
c7b31271 DH |
13066 | compared. The initial value is all 1's. See @code{glStencilFunc}. If |
13067 | the GL version is 2.0 or greater, this stencil state only affects | |
13068 | non-polygons and front-facing polygons. Back-facing polygons use | |
13069 | separate stencil state. See @code{glStencilFuncSeparate}. | |
b002944d AW |
13070 | |
13071 | @item @code{GL_STENCIL_WRITEMASK} | |
13072 | ||
13073 | ||
13074 | @var{params} returns one value, the mask that controls writing of the | |
c7b31271 DH |
13075 | stencil bitplanes. The initial value is all 1's. See |
13076 | @code{glStencilMask}. If the GL version is 2.0 or greater, this stencil | |
13077 | state only affects non-polygons and front-facing polygons. Back-facing | |
13078 | polygons use separate stencil state. See @code{glStencilMaskSeparate}. | |
b002944d AW |
13079 | |
13080 | @item @code{GL_STEREO} | |
13081 | ||
13082 | ||
13083 | @var{params} returns a single boolean value indicating whether stereo | |
13084 | buffers (left and right) are supported. | |
13085 | ||
13086 | @item @code{GL_SUBPIXEL_BITS} | |
13087 | ||
13088 | ||
13089 | @var{params} returns one value, an estimate of the number of bits of | |
13090 | subpixel resolution that are used to position rasterized geometry in | |
c7b31271 | 13091 | window coordinates. The value must be at least 4. |
b002944d AW |
13092 | |
13093 | @item @code{GL_TEXTURE_1D} | |
13094 | ||
13095 | ||
13096 | @var{params} returns a single boolean value indicating whether 1D | |
c7b31271 | 13097 | texture mapping is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
13098 | @code{glTexImage1D}. |
13099 | ||
13100 | @item @code{GL_TEXTURE_BINDING_1D} | |
13101 | ||
13102 | ||
13103 | @var{params} returns a single value, the name of the texture currently | |
c7b31271 | 13104 | bound to the target @code{GL_TEXTURE_1D}. The initial value is 0. See |
b002944d AW |
13105 | @code{glBindTexture}. |
13106 | ||
13107 | @item @code{GL_TEXTURE_2D} | |
13108 | ||
13109 | ||
13110 | @var{params} returns a single boolean value indicating whether 2D | |
c7b31271 | 13111 | texture mapping is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
13112 | @code{glTexImage2D}. |
13113 | ||
13114 | @item @code{GL_TEXTURE_BINDING_2D} | |
13115 | ||
13116 | ||
13117 | @var{params} returns a single value, the name of the texture currently | |
c7b31271 | 13118 | bound to the target @code{GL_TEXTURE_2D}. The initial value is 0. See |
b002944d AW |
13119 | @code{glBindTexture}. |
13120 | ||
13121 | @item @code{GL_TEXTURE_3D} | |
13122 | ||
13123 | ||
13124 | @var{params} returns a single boolean value indicating whether 3D | |
c7b31271 | 13125 | texture mapping is enabled. The initial value is @code{GL_FALSE}. See |
b002944d AW |
13126 | @code{glTexImage3D}. |
13127 | ||
13128 | @item @code{GL_TEXTURE_BINDING_3D} | |
13129 | ||
13130 | ||
13131 | @var{params} returns a single value, the name of the texture currently | |
c7b31271 | 13132 | bound to the target @code{GL_TEXTURE_3D}. The initial value is 0. See |
b002944d AW |
13133 | @code{glBindTexture}. |
13134 | ||
13135 | @item @code{GL_TEXTURE_BINDING_CUBE_MAP} | |
13136 | ||
13137 | ||
13138 | @var{params} returns a single value, the name of the texture currently | |
c7b31271 | 13139 | bound to the target @code{GL_TEXTURE_CUBE_MAP}. The initial value is 0. |
b002944d AW |
13140 | See @code{glBindTexture}. |
13141 | ||
13142 | @item @code{GL_TEXTURE_COMPRESSION_HINT} | |
13143 | ||
13144 | ||
13145 | @var{params} returns a single value indicating the mode of the texture | |
c7b31271 | 13146 | compression hint. The initial value is @code{GL_DONT_CARE}. |
b002944d AW |
13147 | |
13148 | @item @code{GL_TEXTURE_COORD_ARRAY} | |
13149 | ||
13150 | ||
13151 | @var{params} returns a single boolean value indicating whether the | |
c7b31271 DH |
13152 | texture coordinate array is enabled. The initial value is |
13153 | @code{GL_FALSE}. See @code{glTexCoordPointer}. | |
b002944d AW |
13154 | |
13155 | @item @code{GL_TEXTURE_COORD_ARRAY_BUFFER_BINDING} | |
13156 | ||
13157 | ||
13158 | @var{params} returns a single value, the name of the buffer object | |
c7b31271 | 13159 | associated with the texture coordinate array. This buffer object would |
b002944d | 13160 | have been bound to the target @code{GL_ARRAY_BUFFER} at the time of the |
c7b31271 DH |
13161 | most recent call to @code{glTexCoordPointer}. If no buffer object was |
13162 | bound to this target, 0 is returned. The initial value is 0. See | |
b002944d AW |
13163 | @code{glBindBuffer}. |
13164 | ||
13165 | @item @code{GL_TEXTURE_COORD_ARRAY_SIZE} | |
13166 | ||
13167 | ||
13168 | @var{params} returns one value, the number of coordinates per element in | |
c7b31271 | 13169 | the texture coordinate array. The initial value is 4. See |
b002944d AW |
13170 | @code{glTexCoordPointer}. |
13171 | ||
13172 | @item @code{GL_TEXTURE_COORD_ARRAY_STRIDE} | |
13173 | ||
13174 | ||
13175 | @var{params} returns one value, the byte offset between consecutive | |
c7b31271 | 13176 | elements in the texture coordinate array. The initial value is 0. See |
b002944d AW |
13177 | @code{glTexCoordPointer}. |
13178 | ||
13179 | @item @code{GL_TEXTURE_COORD_ARRAY_TYPE} | |
13180 | ||
13181 | ||
13182 | @var{params} returns one value, the data type of the coordinates in the | |
c7b31271 | 13183 | texture coordinate array. The initial value is @code{GL_FLOAT}. See |
b002944d AW |
13184 | @code{glTexCoordPointer}. |
13185 | ||
13186 | @item @code{GL_TEXTURE_CUBE_MAP} | |
13187 | ||
13188 | ||
13189 | @var{params} returns a single boolean value indicating whether | |
c7b31271 DH |
13190 | cube-mapped texture mapping is enabled. The initial value is |
13191 | @code{GL_FALSE}. See @code{glTexImage2D}. | |
b002944d AW |
13192 | |
13193 | @item @code{GL_TEXTURE_GEN_Q} | |
13194 | ||
13195 | ||
13196 | @var{params} returns a single boolean value indicating whether automatic | |
c7b31271 DH |
13197 | generation of the @var{q} texture coordinate is enabled. The initial |
13198 | value is @code{GL_FALSE}. See @code{glTexGen}. | |
b002944d AW |
13199 | |
13200 | @item @code{GL_TEXTURE_GEN_R} | |
13201 | ||
13202 | ||
13203 | @var{params} returns a single boolean value indicating whether automatic | |
c7b31271 DH |
13204 | generation of the @var{r} texture coordinate is enabled. The initial |
13205 | value is @code{GL_FALSE}. See @code{glTexGen}. | |
b002944d AW |
13206 | |
13207 | @item @code{GL_TEXTURE_GEN_S} | |
13208 | ||
13209 | ||
13210 | @var{params} returns a single boolean value indicating whether automatic | |
c7b31271 DH |
13211 | generation of the @var{S} texture coordinate is enabled. The initial |
13212 | value is @code{GL_FALSE}. See @code{glTexGen}. | |
b002944d AW |
13213 | |
13214 | @item @code{GL_TEXTURE_GEN_T} | |
13215 | ||
13216 | ||
13217 | @var{params} returns a single boolean value indicating whether automatic | |
c7b31271 DH |
13218 | generation of the T texture coordinate is enabled. The initial value is |
13219 | @code{GL_FALSE}. See @code{glTexGen}. | |
b002944d AW |
13220 | |
13221 | @item @code{GL_TEXTURE_MATRIX} | |
13222 | ||
13223 | ||
13224 | @var{params} returns sixteen values: the texture matrix on the top of | |
c7b31271 | 13225 | the texture matrix stack. Initially this matrix is the identity matrix. |
b002944d AW |
13226 | See @code{glPushMatrix}. |
13227 | ||
13228 | @item @code{GL_TEXTURE_STACK_DEPTH} | |
13229 | ||
13230 | ||
13231 | @var{params} returns one value, the number of matrices on the texture | |
c7b31271 | 13232 | matrix stack. The initial value is 1. See @code{glPushMatrix}. |
b002944d AW |
13233 | |
13234 | @item @code{GL_TRANSPOSE_COLOR_MATRIX} | |
13235 | ||
13236 | ||
13237 | @var{params} returns 16 values, the elements of the color matrix in | |
c7b31271 | 13238 | row-major order. See @code{glLoadTransposeMatrix}. |
b002944d AW |
13239 | |
13240 | @item @code{GL_TRANSPOSE_MODELVIEW_MATRIX} | |
13241 | ||
13242 | ||
13243 | @var{params} returns 16 values, the elements of the modelview matrix in | |
c7b31271 | 13244 | row-major order. See @code{glLoadTransposeMatrix}. |
b002944d AW |
13245 | |
13246 | @item @code{GL_TRANSPOSE_PROJECTION_MATRIX} | |
13247 | ||
13248 | ||
13249 | @var{params} returns 16 values, the elements of the projection matrix in | |
c7b31271 | 13250 | row-major order. See @code{glLoadTransposeMatrix}. |
b002944d AW |
13251 | |
13252 | @item @code{GL_TRANSPOSE_TEXTURE_MATRIX} | |
13253 | ||
13254 | ||
13255 | @var{params} returns 16 values, the elements of the texture matrix in | |
c7b31271 | 13256 | row-major order. See @code{glLoadTransposeMatrix}. |
b002944d AW |
13257 | |
13258 | @item @code{GL_UNPACK_ALIGNMENT} | |
13259 | ||
13260 | ||
13261 | @var{params} returns one value, the byte alignment used for reading | |
c7b31271 DH |
13262 | pixel data from memory. The initial value is 4. See |
13263 | @code{glPixelStore}. | |
b002944d AW |
13264 | |
13265 | @item @code{GL_UNPACK_IMAGE_HEIGHT} | |
13266 | ||
13267 | ||
13268 | @var{params} returns one value, the image height used for reading pixel | |
c7b31271 | 13269 | data from memory. The initial is 0. See @code{glPixelStore}. |
b002944d AW |
13270 | |
13271 | @item @code{GL_UNPACK_LSB_FIRST} | |
13272 | ||
13273 | ||
13274 | @var{params} returns a single boolean value indicating whether | |
13275 | single-bit pixels being read from memory are read first from the least | |
c7b31271 DH |
13276 | significant bit of each unsigned byte. The initial value is |
13277 | @code{GL_FALSE}. See @code{glPixelStore}. | |
b002944d AW |
13278 | |
13279 | @item @code{GL_UNPACK_ROW_LENGTH} | |
13280 | ||
13281 | ||
13282 | @var{params} returns one value, the row length used for reading pixel | |
c7b31271 | 13283 | data from memory. The initial value is 0. See @code{glPixelStore}. |
b002944d AW |
13284 | |
13285 | @item @code{GL_UNPACK_SKIP_IMAGES} | |
13286 | ||
13287 | ||
13288 | @var{params} returns one value, the number of pixel images skipped | |
c7b31271 | 13289 | before the first pixel is read from memory. The initial value is 0. See |
b002944d AW |
13290 | @code{glPixelStore}. |
13291 | ||
13292 | @item @code{GL_UNPACK_SKIP_PIXELS} | |
13293 | ||
13294 | ||
13295 | @var{params} returns one value, the number of pixel locations skipped | |
c7b31271 | 13296 | before the first pixel is read from memory. The initial value is 0. See |
b002944d AW |
13297 | @code{glPixelStore}. |
13298 | ||
13299 | @item @code{GL_UNPACK_SKIP_ROWS} | |
8925f36f AW |
13300 | |
13301 | ||
b002944d | 13302 | @var{params} returns one value, the number of rows of pixel locations |
c7b31271 DH |
13303 | skipped before the first pixel is read from memory. The initial value |
13304 | is 0. See @code{glPixelStore}. | |
8925f36f | 13305 | |
b002944d | 13306 | @item @code{GL_UNPACK_SWAP_BYTES} |
8925f36f AW |
13307 | |
13308 | ||
b002944d AW |
13309 | @var{params} returns a single boolean value indicating whether the bytes |
13310 | of two-byte and four-byte pixel indices and components are swapped after | |
c7b31271 | 13311 | being read from memory. The initial value is @code{GL_FALSE}. See |
b002944d | 13312 | @code{glPixelStore}. |
8925f36f | 13313 | |
b002944d | 13314 | @item @code{GL_VERTEX_ARRAY} |
8925f36f AW |
13315 | |
13316 | ||
b002944d | 13317 | @var{params} returns a single boolean value indicating whether the |
c7b31271 | 13318 | vertex array is enabled. The initial value is @code{GL_FALSE}. See |
b002944d | 13319 | @code{glVertexPointer}. |
8925f36f | 13320 | |
b002944d | 13321 | @item @code{GL_VERTEX_ARRAY_BUFFER_BINDING} |
8925f36f AW |
13322 | |
13323 | ||
b002944d | 13324 | @var{params} returns a single value, the name of the buffer object |
c7b31271 | 13325 | associated with the vertex array. This buffer object would have been |
b002944d | 13326 | bound to the target @code{GL_ARRAY_BUFFER} at the time of the most |
c7b31271 DH |
13327 | recent call to @code{glVertexPointer}. If no buffer object was bound to |
13328 | this target, 0 is returned. The initial value is 0. See | |
b002944d | 13329 | @code{glBindBuffer}. |
8925f36f | 13330 | |
b002944d | 13331 | @item @code{GL_VERTEX_ARRAY_SIZE} |
8925f36f AW |
13332 | |
13333 | ||
b002944d | 13334 | @var{params} returns one value, the number of coordinates per vertex in |
c7b31271 | 13335 | the vertex array. The initial value is 4. See @code{glVertexPointer}. |
8925f36f | 13336 | |
b002944d | 13337 | @item @code{GL_VERTEX_ARRAY_STRIDE} |
8925f36f AW |
13338 | |
13339 | ||
b002944d | 13340 | @var{params} returns one value, the byte offset between consecutive |
c7b31271 | 13341 | vertices in the vertex array. The initial value is 0. See |
b002944d | 13342 | @code{glVertexPointer}. |
8925f36f | 13343 | |
b002944d | 13344 | @item @code{GL_VERTEX_ARRAY_TYPE} |
8925f36f AW |
13345 | |
13346 | ||
b002944d | 13347 | @var{params} returns one value, the data type of each coordinate in the |
c7b31271 | 13348 | vertex array. The initial value is @code{GL_FLOAT}. See |
b002944d | 13349 | @code{glVertexPointer}. |
8925f36f | 13350 | |
b002944d | 13351 | @item @code{GL_VERTEX_PROGRAM_POINT_SIZE} |
8925f36f AW |
13352 | |
13353 | ||
b002944d | 13354 | @var{params} returns a single boolean value indicating whether vertex |
c7b31271 | 13355 | program point size mode is enabled. If enabled, and a vertex shader is |
b002944d | 13356 | active, then the point size is taken from the shader built-in |
c7b31271 | 13357 | @code{gl_PointSize}. If disabled, and a vertex shader is active, then |
b002944d | 13358 | the point size is taken from the point state as specified by |
c7b31271 | 13359 | @code{glPointSize}. The initial value is @code{GL_FALSE}. |
8925f36f | 13360 | |
b002944d | 13361 | @item @code{GL_VERTEX_PROGRAM_TWO_SIDE} |
8925f36f AW |
13362 | |
13363 | ||
b002944d | 13364 | @var{params} returns a single boolean value indicating whether vertex |
c7b31271 DH |
13365 | program two-sided color mode is enabled. If enabled, and a vertex |
13366 | shader is active, then the GL chooses the back color output for | |
13367 | back-facing polygons, and the front color output for non-polygons and | |
13368 | front-facing polygons. If disabled, and a vertex shader is active, then | |
13369 | the front color output is always selected. The initial value is | |
13370 | @code{GL_FALSE}. | |
8925f36f | 13371 | |
b002944d | 13372 | @item @code{GL_VIEWPORT} |
8925f36f AW |
13373 | |
13374 | ||
b002944d | 13375 | @var{params} returns four values: the @r{@var{x}} and @r{@var{y}} window |
c7b31271 | 13376 | coordinates of the viewport, followed by its width and height. Initially |
b002944d AW |
13377 | the @r{@var{x}} and @r{@var{y}} window coordinates are both set to 0, |
13378 | and the width and height are set to the width and height of the window | |
c7b31271 | 13379 | into which the GL will do its rendering. See @code{glViewport}. |
8925f36f | 13380 | |
b002944d | 13381 | @item @code{GL_ZOOM_X} |
8925f36f AW |
13382 | |
13383 | ||
c7b31271 DH |
13384 | @var{params} returns one value, the @r{@var{x}} pixel zoom factor. The |
13385 | initial value is 1. See @code{glPixelZoom}. | |
8925f36f | 13386 | |
b002944d | 13387 | @item @code{GL_ZOOM_Y} |
8925f36f | 13388 | |
8925f36f | 13389 | |
c7b31271 DH |
13390 | @var{params} returns one value, the @r{@var{y}} pixel zoom factor. The |
13391 | initial value is 1. See @code{glPixelZoom}. | |
8925f36f | 13392 | |
b002944d | 13393 | @end table |
bb894c9d | 13394 | |
b002944d AW |
13395 | Many of the boolean parameters can also be queried more easily using |
13396 | @code{glIsEnabled}. | |
8925f36f | 13397 | |
b002944d AW |
13398 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted |
13399 | value. | |
13400 | ||
13401 | @code{GL_INVALID_OPERATION} is generated if @code{glGet} is executed | |
13402 | between the execution of @code{glBegin} and the corresponding execution | |
13403 | of @code{glEnd}. | |
bb894c9d | 13404 | |
8925f36f AW |
13405 | |
13406 | ||
bb894c9d | 13407 | @end deftypefun |
8925f36f | 13408 | |
bb894c9d | 13409 | @deftypefun void glHint target mode |
3c9b6116 AW |
13410 | Specify implementation-specific hints. |
13411 | ||
8925f36f AW |
13412 | @table @asis |
13413 | @item @var{target} | |
13414 | Specifies a symbolic constant indicating the behavior to be controlled. | |
13415 | @code{GL_FOG_HINT}, @code{GL_GENERATE_MIPMAP_HINT}, | |
13416 | @code{GL_LINE_SMOOTH_HINT}, @code{GL_PERSPECTIVE_CORRECTION_HINT}, | |
13417 | @code{GL_POINT_SMOOTH_HINT}, @code{GL_POLYGON_SMOOTH_HINT}, | |
13418 | @code{GL_TEXTURE_COMPRESSION_HINT}, and | |
13419 | @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT} are accepted. | |
13420 | ||
13421 | @item @var{mode} | |
13422 | Specifies a symbolic constant indicating the desired behavior. | |
13423 | @code{GL_FASTEST}, @code{GL_NICEST}, and @code{GL_DONT_CARE} are | |
13424 | accepted. | |
13425 | ||
13426 | @end table | |
13427 | ||
8925f36f | 13428 | Certain aspects of GL behavior, when there is room for interpretation, |
c7b31271 | 13429 | can be controlled with hints. A hint is specified with two arguments. |
8925f36f AW |
13430 | @var{target} is a symbolic constant indicating the behavior to be |
13431 | controlled, and @var{mode} is another symbolic constant indicating the | |
c7b31271 DH |
13432 | desired behavior. The initial value for each @var{target} is |
13433 | @code{GL_DONT_CARE}. @var{mode} can be one of the following: | |
8925f36f AW |
13434 | |
13435 | @table @asis | |
13436 | @item @code{GL_FASTEST} | |
13437 | ||
13438 | ||
13439 | The most efficient option should be chosen. | |
13440 | ||
13441 | @item @code{GL_NICEST} | |
13442 | ||
13443 | ||
13444 | The most correct, or highest quality, option should be chosen. | |
13445 | ||
13446 | @item @code{GL_DONT_CARE} | |
13447 | ||
13448 | ||
13449 | No preference. | |
13450 | ||
13451 | @end table | |
13452 | ||
13453 | Though the implementation aspects that can be hinted are well defined, | |
c7b31271 | 13454 | the interpretation of the hints depends on the implementation. The hint |
8925f36f AW |
13455 | aspects that can be specified with @var{target}, along with suggested |
13456 | semantics, are as follows: | |
13457 | ||
13458 | @table @asis | |
13459 | @item @code{GL_FOG_HINT} | |
13460 | ||
13461 | ||
c7b31271 | 13462 | Indicates the accuracy of fog calculation. If per-pixel fog calculation |
8925f36f AW |
13463 | is not efficiently supported by the GL implementation, hinting |
13464 | @code{GL_DONT_CARE} or @code{GL_FASTEST} can result in per-vertex | |
13465 | calculation of fog effects. | |
13466 | ||
13467 | @item @code{GL_FRAGMENT_SHADER_DERIVATIVE_HINT} | |
13468 | ||
13469 | ||
13470 | Indicates the accuracy of the derivative calculation for the GL shading | |
13471 | language fragment processing built-in functions: @code{dFdx}, | |
13472 | @code{dFdy}, and @code{fwidth}. | |
13473 | ||
13474 | @item @code{GL_GENERATE_MIPMAP_HINT} | |
13475 | ||
13476 | ||
13477 | Indicates the quality of filtering when generating mipmap images. | |
13478 | ||
13479 | @item @code{GL_LINE_SMOOTH_HINT} | |
13480 | ||
13481 | ||
c7b31271 | 13482 | Indicates the sampling quality of antialiased lines. If a larger filter |
8925f36f AW |
13483 | function is applied, hinting @code{GL_NICEST} can result in more pixel |
13484 | fragments being generated during rasterization. | |
13485 | ||
13486 | @item @code{GL_PERSPECTIVE_CORRECTION_HINT} | |
13487 | ||
13488 | ||
13489 | Indicates the quality of color, texture coordinate, and fog coordinate | |
c7b31271 | 13490 | interpolation. If perspective-corrected parameter interpolation is not |
8925f36f AW |
13491 | efficiently supported by the GL implementation, hinting |
13492 | @code{GL_DONT_CARE} or @code{GL_FASTEST} can result in simple linear | |
13493 | interpolation of colors and/or texture coordinates. | |
13494 | ||
13495 | @item @code{GL_POINT_SMOOTH_HINT} | |
13496 | ||
13497 | ||
c7b31271 DH |
13498 | Indicates the sampling quality of antialiased points. If a larger |
13499 | filter function is applied, hinting @code{GL_NICEST} can result in more | |
13500 | pixel fragments being generated during rasterization. | |
8925f36f AW |
13501 | |
13502 | @item @code{GL_POLYGON_SMOOTH_HINT} | |
13503 | ||
13504 | ||
c7b31271 | 13505 | Indicates the sampling quality of antialiased polygons. Hinting |
8925f36f AW |
13506 | @code{GL_NICEST} can result in more pixel fragments being generated |
13507 | during rasterization, if a larger filter function is applied. | |
13508 | ||
13509 | @item @code{GL_TEXTURE_COMPRESSION_HINT} | |
13510 | ||
13511 | ||
13512 | Indicates the quality and performance of the compressing texture images. | |
13513 | Hinting @code{GL_FASTEST} indicates that texture images should be | |
13514 | compressed as quickly as possible, while @code{GL_NICEST} indicates that | |
13515 | texture images should be compressed with as little image quality loss as | |
c7b31271 | 13516 | possible. @code{GL_NICEST} should be selected if the texture is to be |
8925f36f AW |
13517 | retrieved by @code{glGetCompressedTexImage} for reuse. |
13518 | ||
13519 | @end table | |
13520 | ||
8925f36f AW |
13521 | @code{GL_INVALID_ENUM} is generated if either @var{target} or @var{mode} |
13522 | is not an accepted value. | |
13523 | ||
13524 | @code{GL_INVALID_OPERATION} is generated if @code{glHint} is executed | |
13525 | between the execution of @code{glBegin} and the corresponding execution | |
13526 | of @code{glEnd}. | |
13527 | ||
bb894c9d | 13528 | @end deftypefun |
8925f36f | 13529 | |
bb894c9d | 13530 | @deftypefun void glHistogram target width internalformat sink |
3c9b6116 AW |
13531 | Define histogram table. |
13532 | ||
8925f36f AW |
13533 | @table @asis |
13534 | @item @var{target} | |
c7b31271 | 13535 | The histogram whose parameters are to be set. Must be one of |
8925f36f AW |
13536 | @code{GL_HISTOGRAM} or @code{GL_PROXY_HISTOGRAM}. |
13537 | ||
13538 | @item @var{width} | |
c7b31271 | 13539 | The number of entries in the histogram table. Must be a power of 2. |
8925f36f AW |
13540 | |
13541 | @item @var{internalformat} | |
c7b31271 | 13542 | The format of entries in the histogram table. Must be one of |
8925f36f AW |
13543 | @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, |
13544 | @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
13545 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
13546 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
13547 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
13548 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
13549 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
13550 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
13551 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
13552 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
13553 | @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
13554 | ||
13555 | @item @var{sink} | |
13556 | If @code{GL_TRUE}, pixels will be consumed by the histogramming process | |
c7b31271 | 13557 | and no drawing or texture loading will take place. If @code{GL_FALSE}, |
8925f36f AW |
13558 | pixels will proceed to the minmax process after histogramming. |
13559 | ||
13560 | @end table | |
13561 | ||
8925f36f AW |
13562 | When @code{GL_HISTOGRAM} is enabled, RGBA color components are converted |
13563 | to histogram table indices by clamping to the range [0,1], multiplying | |
13564 | by the width of the histogram table, and rounding to the nearest | |
c7b31271 DH |
13565 | integer. The table entries selected by the RGBA indices are then |
13566 | incremented. (If the internal format of the histogram table includes | |
8925f36f AW |
13567 | luminance, then the index derived from the R color component determines |
13568 | the luminance table entry to be incremented.) If a histogram table entry | |
13569 | is incremented beyond its maximum value, then its value becomes | |
c7b31271 | 13570 | undefined. (This is not an error.) |
8925f36f AW |
13571 | |
13572 | Histogramming is performed only for RGBA pixels (though these may be | |
13573 | specified originally as color indices and converted to RGBA by index | |
c7b31271 | 13574 | table lookup). Histogramming is enabled with @code{glEnable} and |
8925f36f AW |
13575 | disabled with @code{glDisable}. |
13576 | ||
13577 | When @var{target} is @code{GL_HISTOGRAM}, @code{glHistogram} redefines | |
13578 | the current histogram table to have @var{width} entries of the format | |
c7b31271 DH |
13579 | specified by @var{internalformat}. The entries are indexed 0 through |
13580 | @r{@var{width}-1}, and all entries are initialized to zero. The values | |
13581 | in the previous histogram table, if any, are lost. If @var{sink} is | |
3c9b6116 | 13582 | @code{GL_TRUE}, then pixels are discarded after histogramming; no |
8925f36f AW |
13583 | further processing of the pixels takes place, and no drawing, texture |
13584 | loading, or pixel readback will result. | |
13585 | ||
13586 | When @var{target} is @code{GL_PROXY_HISTOGRAM}, @code{glHistogram} | |
13587 | computes all state information as if the histogram table were to be | |
c7b31271 | 13588 | redefined, but does not actually define the new table. If the requested |
8925f36f | 13589 | histogram table is too large to be supported, then the state information |
c7b31271 | 13590 | will be set to zero. This provides a way to determine if a histogram |
8925f36f AW |
13591 | table with the given parameters can be supported. |
13592 | ||
13593 | ||
13594 | ||
8925f36f AW |
13595 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
13596 | allowable values. | |
13597 | ||
13598 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
13599 | is not a power of 2. | |
13600 | ||
13601 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
13602 | of the allowable values. | |
13603 | ||
13604 | @code{GL_TABLE_TOO_LARGE} is generated if @var{target} is | |
13605 | @code{GL_HISTOGRAM} and the histogram table specified is too large for | |
13606 | the implementation. | |
13607 | ||
13608 | @code{GL_INVALID_OPERATION} is generated if @code{glHistogram} is | |
13609 | executed between the execution of @code{glBegin} and the corresponding | |
13610 | execution of @code{glEnd}. | |
13611 | ||
bb894c9d | 13612 | @end deftypefun |
8925f36f | 13613 | |
bb894c9d | 13614 | @deftypefun void glIndexMask mask |
3c9b6116 AW |
13615 | Control the writing of individual bits in the color index buffers. |
13616 | ||
8925f36f AW |
13617 | @table @asis |
13618 | @item @var{mask} | |
13619 | Specifies a bit mask to enable and disable the writing of individual | |
c7b31271 | 13620 | bits in the color index buffers. Initially, the mask is all 1's. |
8925f36f AW |
13621 | |
13622 | @end table | |
13623 | ||
8925f36f | 13624 | @code{glIndexMask} controls the writing of individual bits in the color |
c7b31271 | 13625 | index buffers. The least significant @r{@var{n}} bits of @var{mask}, |
3c9b6116 | 13626 | where @r{@var{n}} is the number of bits in a color index buffer, specify |
c7b31271 DH |
13627 | a mask. Where a 1 (one) appears in the mask, it's possible to write to |
13628 | the corresponding bit in the color index buffer (or buffers). Where a 0 | |
3c9b6116 | 13629 | (zero) appears, the corresponding bit is write-protected. |
8925f36f AW |
13630 | |
13631 | This mask is used only in color index mode, and it affects only the | |
13632 | buffers currently selected for writing (see @code{glDrawBuffer}). | |
13633 | Initially, all bits are enabled for writing. | |
13634 | ||
8925f36f AW |
13635 | @code{GL_INVALID_OPERATION} is generated if @code{glIndexMask} is |
13636 | executed between the execution of @code{glBegin} and the corresponding | |
13637 | execution of @code{glEnd}. | |
13638 | ||
bb894c9d | 13639 | @end deftypefun |
8925f36f | 13640 | |
bb894c9d | 13641 | @deftypefun void glIndexPointer type stride pointer |
3c9b6116 AW |
13642 | Define an array of color indexes. |
13643 | ||
8925f36f AW |
13644 | @table @asis |
13645 | @item @var{type} | |
c7b31271 | 13646 | Specifies the data type of each color index in the array. Symbolic |
8925f36f | 13647 | constants @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, @code{GL_INT}, |
c7b31271 DH |
13648 | @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value |
13649 | is @code{GL_FLOAT}. | |
8925f36f AW |
13650 | |
13651 | @item @var{stride} | |
c7b31271 | 13652 | Specifies the byte offset between consecutive color indexes. If |
8925f36f | 13653 | @var{stride} is 0, the color indexes are understood to be tightly packed |
c7b31271 | 13654 | in the array. The initial value is 0. |
8925f36f AW |
13655 | |
13656 | @item @var{pointer} | |
c7b31271 | 13657 | Specifies a pointer to the first index in the array. The initial value |
8925f36f AW |
13658 | is 0. |
13659 | ||
13660 | @end table | |
13661 | ||
8925f36f | 13662 | @code{glIndexPointer} specifies the location and data format of an array |
c7b31271 | 13663 | of color indexes to use when rendering. @var{type} specifies the data |
8925f36f AW |
13664 | type of each color index and @var{stride} specifies the byte stride from |
13665 | one color index to the next, allowing vertices and attributes to be | |
13666 | packed into a single array or stored in separate arrays. | |
13667 | ||
13668 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
13669 | target (see @code{glBindBuffer}) while a color index array is specified, | |
13670 | @var{pointer} is treated as a byte offset into the buffer object's data | |
c7b31271 | 13671 | store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING}) |
8925f36f AW |
13672 | is saved as color index vertex array client-side state |
13673 | (@code{GL_INDEX_ARRAY_BUFFER_BINDING}). | |
13674 | ||
13675 | When a color index array is specified, @var{type}, @var{stride}, and | |
13676 | @var{pointer} are saved as client-side state, in addition to the current | |
13677 | vertex array buffer object binding. | |
13678 | ||
13679 | To enable and disable the color index array, call | |
13680 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
c7b31271 | 13681 | argument @code{GL_INDEX_ARRAY}. If enabled, the color index array is |
8925f36f AW |
13682 | used when @code{glDrawArrays}, @code{glMultiDrawArrays}, |
13683 | @code{glDrawElements}, @code{glMultiDrawElements}, | |
13684 | @code{glDrawRangeElements}, or @code{glArrayElement} is called. | |
13685 | ||
8925f36f AW |
13686 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted |
13687 | value. | |
13688 | ||
13689 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
13690 | ||
bb894c9d | 13691 | @end deftypefun |
8925f36f | 13692 | |
d172eed9 AW |
13693 | @deftypefun void glIndexs c |
13694 | @deftypefunx void glIndexi c | |
ca09631c | 13695 | @deftypefunx void glIndexf c |
d172eed9 | 13696 | @deftypefunx void glIndexd c |
bb894c9d | 13697 | @deftypefunx void glIndexub c |
d172eed9 AW |
13698 | @deftypefunx void glIndexsv c |
13699 | @deftypefunx void glIndexiv c | |
13700 | @deftypefunx void glIndexfv c | |
13701 | @deftypefunx void glIndexdv c | |
13702 | @deftypefunx void glIndexubv c | |
3c9b6116 AW |
13703 | Set the current color index. |
13704 | ||
8925f36f AW |
13705 | @table @asis |
13706 | @item @var{c} | |
13707 | Specifies the new value for the current color index. | |
13708 | ||
13709 | ||
13710 | ||
13711 | @end table | |
13712 | ||
c7b31271 DH |
13713 | @code{glIndex} updates the current (single-valued) color index. It |
13714 | takes one argument, the new value for the current color index. | |
8925f36f | 13715 | |
c7b31271 | 13716 | The current index is stored as a floating-point value. Integer values |
8925f36f | 13717 | are converted directly to floating-point values, with no special |
c7b31271 | 13718 | mapping. The initial value is 1. |
8925f36f AW |
13719 | |
13720 | Index values outside the representable range of the color index buffer | |
c7b31271 DH |
13721 | are not clamped. However, before an index is dithered (if enabled) and |
13722 | written to the frame buffer, it is converted to fixed-point format. Any | |
8925f36f AW |
13723 | bits in the integer portion of the resulting fixed-point value that do |
13724 | not correspond to bits in the frame buffer are masked out. | |
13725 | ||
bb894c9d | 13726 | @end deftypefun |
8925f36f | 13727 | |
bb894c9d | 13728 | @deftypefun void glInitNames |
3c9b6116 AW |
13729 | Initialize the name stack. |
13730 | ||
8925f36f | 13731 | The name stack is used during selection mode to allow sets of rendering |
c7b31271 DH |
13732 | commands to be uniquely identified. It consists of an ordered set of |
13733 | unsigned integers. @code{glInitNames} causes the name stack to be | |
8925f36f AW |
13734 | initialized to its default empty state. |
13735 | ||
13736 | The name stack is always empty while the render mode is not | |
c7b31271 | 13737 | @code{GL_SELECT}. Calls to @code{glInitNames} while the render mode is |
8925f36f AW |
13738 | not @code{GL_SELECT} are ignored. |
13739 | ||
8925f36f AW |
13740 | @code{GL_INVALID_OPERATION} is generated if @code{glInitNames} is |
13741 | executed between the execution of @code{glBegin} and the corresponding | |
13742 | execution of @code{glEnd}. | |
13743 | ||
bb894c9d | 13744 | @end deftypefun |
8925f36f | 13745 | |
bb894c9d | 13746 | @deftypefun void glInterleavedArrays format stride pointer |
3c9b6116 AW |
13747 | Simultaneously specify and enable several interleaved arrays. |
13748 | ||
8925f36f AW |
13749 | @table @asis |
13750 | @item @var{format} | |
c7b31271 DH |
13751 | Specifies the type of array to enable. Symbolic constants |
13752 | @code{GL_V2F}, @code{GL_V3F}, @code{GL_C4UB_V2F}, @code{GL_C4UB_V3F}, | |
8925f36f AW |
13753 | @code{GL_C3F_V3F}, @code{GL_N3F_V3F}, @code{GL_C4F_N3F_V3F}, |
13754 | @code{GL_T2F_V3F}, @code{GL_T4F_V4F}, @code{GL_T2F_C4UB_V3F}, | |
13755 | @code{GL_T2F_C3F_V3F}, @code{GL_T2F_N3F_V3F}, @code{GL_T2F_C4F_N3F_V3F}, | |
13756 | and @code{GL_T4F_C4F_N3F_V4F} are accepted. | |
13757 | ||
13758 | @item @var{stride} | |
13759 | Specifies the offset in bytes between each aggregate array element. | |
13760 | ||
13761 | @end table | |
13762 | ||
8925f36f AW |
13763 | @code{glInterleavedArrays} lets you specify and enable individual color, |
13764 | normal, texture and vertex arrays whose elements are part of a larger | |
c7b31271 | 13765 | aggregate array element. For some implementations, this is more |
8925f36f AW |
13766 | efficient than specifying the arrays separately. |
13767 | ||
13768 | If @var{stride} is 0, the aggregate elements are stored consecutively. | |
13769 | Otherwise, @var{stride} bytes occur between the beginning of one | |
13770 | aggregate array element and the beginning of the next aggregate array | |
13771 | element. | |
13772 | ||
13773 | @var{format} serves as a ``key'' describing the extraction of individual | |
c7b31271 DH |
13774 | arrays from the aggregate array. If @var{format} contains a T, then |
13775 | texture coordinates are extracted from the interleaved array. If C is | |
13776 | present, color values are extracted. If N is present, normal | |
13777 | coordinates are extracted. Vertex coordinates are always extracted. | |
8925f36f | 13778 | |
c7b31271 DH |
13779 | The digits 2, 3, and 4 denote how many values are extracted. F |
13780 | indicates that values are extracted as floating-point values. Colors | |
13781 | may also be extracted as 4 unsigned bytes if 4UB follows the C. If a | |
13782 | color is extracted as 4 unsigned bytes, the vertex array element which | |
13783 | follows is located at the first possible floating-point aligned address. | |
8925f36f | 13784 | |
8925f36f AW |
13785 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted |
13786 | value. | |
13787 | ||
13788 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
13789 | ||
bb894c9d | 13790 | @end deftypefun |
8925f36f | 13791 | |
bb894c9d | 13792 | @deftypefun GLboolean glIsBuffer buffer |
3c9b6116 AW |
13793 | Determine if a name corresponds to a buffer object. |
13794 | ||
8925f36f AW |
13795 | @table @asis |
13796 | @item @var{buffer} | |
13797 | Specifies a value that may be the name of a buffer object. | |
13798 | ||
13799 | @end table | |
13800 | ||
8925f36f | 13801 | @code{glIsBuffer} returns @code{GL_TRUE} if @var{buffer} is currently |
c7b31271 | 13802 | the name of a buffer object. If @var{buffer} is zero, or is a non-zero |
8925f36f AW |
13803 | value that is not currently the name of a buffer object, or if an error |
13804 | occurs, @code{glIsBuffer} returns @code{GL_FALSE}. | |
13805 | ||
13806 | A name returned by @code{glGenBuffers}, but not yet associated with a | |
13807 | buffer object by calling @code{glBindBuffer}, is not the name of a | |
13808 | buffer object. | |
13809 | ||
8925f36f AW |
13810 | @code{GL_INVALID_OPERATION} is generated if @code{glIsBuffer} is |
13811 | executed between the execution of @code{glBegin} and the corresponding | |
13812 | execution of @code{glEnd}. | |
13813 | ||
bb894c9d | 13814 | @end deftypefun |
8925f36f | 13815 | |
bb894c9d | 13816 | @deftypefun GLboolean glIsEnabled cap |
3c9b6116 AW |
13817 | Test whether a capability is enabled. |
13818 | ||
8925f36f AW |
13819 | @table @asis |
13820 | @item @var{cap} | |
13821 | Specifies a symbolic constant indicating a GL capability. | |
13822 | ||
13823 | @end table | |
13824 | ||
8925f36f | 13825 | @code{glIsEnabled} returns @code{GL_TRUE} if @var{cap} is an enabled |
c7b31271 | 13826 | capability and returns @code{GL_FALSE} otherwise. Initially all |
8925f36f AW |
13827 | capabilities except @code{GL_DITHER} are disabled; @code{GL_DITHER} is |
13828 | initially enabled. | |
13829 | ||
13830 | The following capabilities are accepted for @var{cap}: | |
13831 | ||
13832 | ||
13833 | ||
13834 | @table @asis | |
13835 | @item @strong{Constant} | |
13836 | @strong{See} | |
13837 | ||
13838 | @item @code{GL_ALPHA_TEST} | |
13839 | @code{glAlphaFunc} | |
13840 | ||
13841 | @item @code{GL_AUTO_NORMAL} | |
13842 | @code{glEvalCoord} | |
13843 | ||
13844 | @item @code{GL_BLEND} | |
13845 | @code{glBlendFunc}, @code{glLogicOp} | |
13846 | ||
13847 | @item @code{GL_CLIP_PLANE}@var{i} | |
13848 | @code{glClipPlane} | |
13849 | ||
13850 | @item @code{GL_COLOR_ARRAY} | |
13851 | @code{glColorPointer} | |
13852 | ||
13853 | @item @code{GL_COLOR_LOGIC_OP} | |
13854 | @code{glLogicOp} | |
13855 | ||
13856 | @item @code{GL_COLOR_MATERIAL} | |
13857 | @code{glColorMaterial} | |
13858 | ||
13859 | @item @code{GL_COLOR_SUM} | |
13860 | @code{glSecondaryColor} | |
13861 | ||
13862 | @item @code{GL_COLOR_TABLE} | |
13863 | @code{glColorTable} | |
13864 | ||
13865 | @item @code{GL_CONVOLUTION_1D} | |
13866 | @code{glConvolutionFilter1D} | |
13867 | ||
13868 | @item @code{GL_CONVOLUTION_2D} | |
13869 | @code{glConvolutionFilter2D} | |
13870 | ||
13871 | @item @code{GL_CULL_FACE} | |
13872 | @code{glCullFace} | |
13873 | ||
13874 | @item @code{GL_DEPTH_TEST} | |
13875 | @code{glDepthFunc}, @code{glDepthRange} | |
13876 | ||
13877 | @item @code{GL_DITHER} | |
13878 | @code{glEnable} | |
13879 | ||
13880 | @item @code{GL_EDGE_FLAG_ARRAY} | |
13881 | @code{glEdgeFlagPointer} | |
13882 | ||
13883 | @item @code{GL_FOG} | |
13884 | @code{glFog} | |
13885 | ||
13886 | @item @code{GL_FOG_COORD_ARRAY} | |
13887 | @code{glFogCoordPointer} | |
13888 | ||
13889 | @item @code{GL_HISTOGRAM} | |
13890 | @code{glHistogram} | |
13891 | ||
13892 | @item @code{GL_INDEX_ARRAY} | |
13893 | @code{glIndexPointer} | |
13894 | ||
13895 | @item @code{GL_INDEX_LOGIC_OP} | |
13896 | @code{glLogicOp} | |
13897 | ||
13898 | @item @code{GL_LIGHT}@var{i} | |
13899 | @code{glLightModel}, @code{glLight} | |
13900 | ||
13901 | @item @code{GL_LIGHTING} | |
13902 | @code{glMaterial}, @code{glLightModel}, @code{glLight} | |
13903 | ||
13904 | @item @code{GL_LINE_SMOOTH} | |
13905 | @code{glLineWidth} | |
13906 | ||
13907 | @item @code{GL_LINE_STIPPLE} | |
13908 | @code{glLineStipple} | |
13909 | ||
13910 | @item @code{GL_MAP1_COLOR_4} | |
13911 | @code{glMap1} | |
13912 | ||
13913 | @item @code{GL_MAP1_INDEX} | |
13914 | @code{glMap1} | |
13915 | ||
13916 | @item @code{GL_MAP1_NORMAL} | |
13917 | @code{glMap1} | |
13918 | ||
13919 | @item @code{GL_MAP1_TEXTURE_COORD_1} | |
13920 | @code{glMap1} | |
13921 | ||
13922 | @item @code{GL_MAP1_TEXTURE_COORD_2} | |
13923 | @code{glMap1} | |
13924 | ||
13925 | @item @code{GL_MAP1_TEXTURE_COORD_3} | |
13926 | @code{glMap1} | |
13927 | ||
13928 | @item @code{GL_MAP1_TEXTURE_COORD_4} | |
13929 | @code{glMap1} | |
13930 | ||
13931 | @item @code{GL_MAP2_COLOR_4} | |
13932 | @code{glMap2} | |
13933 | ||
13934 | @item @code{GL_MAP2_INDEX} | |
13935 | @code{glMap2} | |
13936 | ||
13937 | @item @code{GL_MAP2_NORMAL} | |
13938 | @code{glMap2} | |
13939 | ||
13940 | @item @code{GL_MAP2_TEXTURE_COORD_1} | |
13941 | @code{glMap2} | |
13942 | ||
13943 | @item @code{GL_MAP2_TEXTURE_COORD_2} | |
13944 | @code{glMap2} | |
13945 | ||
13946 | @item @code{GL_MAP2_TEXTURE_COORD_3} | |
13947 | @code{glMap2} | |
13948 | ||
13949 | @item @code{GL_MAP2_TEXTURE_COORD_4} | |
13950 | @code{glMap2} | |
13951 | ||
13952 | @item @code{GL_MAP2_VERTEX_3} | |
13953 | @code{glMap2} | |
13954 | ||
13955 | @item @code{GL_MAP2_VERTEX_4} | |
13956 | @code{glMap2} | |
13957 | ||
13958 | @item @code{GL_MINMAX} | |
13959 | @code{glMinmax} | |
13960 | ||
13961 | @item @code{GL_MULTISAMPLE} | |
13962 | @code{glSampleCoverage} | |
13963 | ||
13964 | @item @code{GL_NORMAL_ARRAY} | |
13965 | @code{glNormalPointer} | |
13966 | ||
13967 | @item @code{GL_NORMALIZE} | |
13968 | @code{glNormal} | |
13969 | ||
13970 | @item @code{GL_POINT_SMOOTH} | |
13971 | @code{glPointSize} | |
13972 | ||
13973 | @item @code{GL_POINT_SPRITE} | |
13974 | @code{glEnable} | |
13975 | ||
13976 | @item @code{GL_POLYGON_SMOOTH} | |
13977 | @code{glPolygonMode} | |
13978 | ||
13979 | @item @code{GL_POLYGON_OFFSET_FILL} | |
13980 | @code{glPolygonOffset} | |
13981 | ||
13982 | @item @code{GL_POLYGON_OFFSET_LINE} | |
13983 | @code{glPolygonOffset} | |
13984 | ||
13985 | @item @code{GL_POLYGON_OFFSET_POINT} | |
13986 | @code{glPolygonOffset} | |
13987 | ||
13988 | @item @code{GL_POLYGON_STIPPLE} | |
13989 | @code{glPolygonStipple} | |
13990 | ||
13991 | @item @code{GL_POST_COLOR_MATRIX_COLOR_TABLE} | |
13992 | @code{glColorTable} | |
13993 | ||
13994 | @item @code{GL_POST_CONVOLUTION_COLOR_TABLE} | |
13995 | @code{glColorTable} | |
13996 | ||
13997 | @item @code{GL_RESCALE_NORMAL} | |
13998 | @code{glNormal} | |
13999 | ||
14000 | @item @code{GL_SAMPLE_ALPHA_TO_COVERAGE} | |
14001 | @code{glSampleCoverage} | |
14002 | ||
14003 | @item @code{GL_SAMPLE_ALPHA_TO_ONE} | |
14004 | @code{glSampleCoverage} | |
14005 | ||
14006 | @item @code{GL_SAMPLE_COVERAGE} | |
14007 | @code{glSampleCoverage} | |
14008 | ||
14009 | @item @code{GL_SCISSOR_TEST} | |
14010 | @code{glScissor} | |
14011 | ||
14012 | @item @code{GL_SECONDARY_COLOR_ARRAY} | |
14013 | @code{glSecondaryColorPointer} | |
14014 | ||
14015 | @item @code{GL_SEPARABLE_2D} | |
14016 | @code{glSeparableFilter2D} | |
14017 | ||
14018 | @item @code{GL_STENCIL_TEST} | |
14019 | @code{glStencilFunc}, @code{glStencilOp} | |
14020 | ||
14021 | @item @code{GL_TEXTURE_1D} | |
14022 | @code{glTexImage1D} | |
14023 | ||
14024 | @item @code{GL_TEXTURE_2D} | |
14025 | @code{glTexImage2D} | |
14026 | ||
14027 | @item @code{GL_TEXTURE_3D} | |
14028 | @code{glTexImage3D} | |
14029 | ||
14030 | @item @code{GL_TEXTURE_COORD_ARRAY} | |
14031 | @code{glTexCoordPointer} | |
14032 | ||
14033 | @item @code{GL_TEXTURE_CUBE_MAP} | |
14034 | @code{glTexImage2D} | |
14035 | ||
14036 | @item @code{GL_TEXTURE_GEN_Q} | |
14037 | @code{glTexGen} | |
14038 | ||
14039 | @item @code{GL_TEXTURE_GEN_R} | |
14040 | @code{glTexGen} | |
14041 | ||
14042 | @item @code{GL_TEXTURE_GEN_S} | |
14043 | @code{glTexGen} | |
14044 | ||
14045 | @item @code{GL_TEXTURE_GEN_T} | |
14046 | @code{glTexGen} | |
14047 | ||
14048 | @item @code{GL_VERTEX_ARRAY} | |
14049 | @code{glVertexPointer} | |
14050 | ||
14051 | @item @code{GL_VERTEX_PROGRAM_POINT_SIZE} | |
14052 | @code{glEnable} | |
14053 | ||
14054 | @item @code{GL_VERTEX_PROGRAM_TWO_SIDE} | |
14055 | @code{glEnable} | |
14056 | ||
14057 | @end table | |
14058 | ||
14059 | ||
14060 | ||
8925f36f AW |
14061 | @code{GL_INVALID_ENUM} is generated if @var{cap} is not an accepted |
14062 | value. | |
14063 | ||
14064 | @code{GL_INVALID_OPERATION} is generated if @code{glIsEnabled} is | |
14065 | executed between the execution of @code{glBegin} and the corresponding | |
14066 | execution of @code{glEnd}. | |
14067 | ||
bb894c9d | 14068 | @end deftypefun |
8925f36f | 14069 | |
bb894c9d | 14070 | @deftypefun GLboolean glIsList list |
3c9b6116 AW |
14071 | Determine if a name corresponds to a display list. |
14072 | ||
8925f36f AW |
14073 | @table @asis |
14074 | @item @var{list} | |
14075 | Specifies a potential display list name. | |
14076 | ||
14077 | @end table | |
14078 | ||
8925f36f AW |
14079 | @code{glIsList} returns @code{GL_TRUE} if @var{list} is the name of a |
14080 | display list and returns @code{GL_FALSE} if it is not, or if an error | |
14081 | occurs. | |
14082 | ||
14083 | A name returned by @code{glGenLists}, but not yet associated with a | |
14084 | display list by calling @code{glNewList}, is not the name of a display | |
14085 | list. | |
14086 | ||
8925f36f AW |
14087 | @code{GL_INVALID_OPERATION} is generated if @code{glIsList} 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 GLboolean glIsProgram program |
3c9b6116 AW |
14094 | Determines if a name corresponds to a program object. |
14095 | ||
8925f36f AW |
14096 | @table @asis |
14097 | @item @var{program} | |
14098 | Specifies a potential program object. | |
14099 | ||
14100 | @end table | |
14101 | ||
8925f36f AW |
14102 | @code{glIsProgram} returns @code{GL_TRUE} if @var{program} is the name |
14103 | of a program object previously created with @code{glCreateProgram} and | |
c7b31271 DH |
14104 | not yet deleted with @code{glDeleteProgram}. If @var{program} is zero |
14105 | or a non-zero value that is not the name of a program object, or if an | |
8925f36f AW |
14106 | error occurs, @code{glIsProgram} returns @code{GL_FALSE}. |
14107 | ||
8925f36f AW |
14108 | @code{GL_INVALID_OPERATION} is generated if @code{glIsProgram} is |
14109 | executed between the execution of @code{glBegin} and the corresponding | |
14110 | execution of @code{glEnd}. | |
14111 | ||
bb894c9d | 14112 | @end deftypefun |
8925f36f | 14113 | |
bb894c9d | 14114 | @deftypefun GLboolean glIsQuery id |
3c9b6116 AW |
14115 | Determine if a name corresponds to a query object. |
14116 | ||
8925f36f AW |
14117 | @table @asis |
14118 | @item @var{id} | |
14119 | Specifies a value that may be the name of a query object. | |
14120 | ||
14121 | @end table | |
14122 | ||
8925f36f | 14123 | @code{glIsQuery} returns @code{GL_TRUE} if @var{id} is currently the |
c7b31271 DH |
14124 | name of a query object. If @var{id} is zero, or is a non-zero value |
14125 | that is not currently the name of a query object, or if an error occurs, | |
8925f36f AW |
14126 | @code{glIsQuery} returns @code{GL_FALSE}. |
14127 | ||
14128 | A name returned by @code{glGenQueries}, but not yet associated with a | |
14129 | query object by calling @code{glBeginQuery}, is not the name of a query | |
14130 | object. | |
14131 | ||
8925f36f AW |
14132 | @code{GL_INVALID_OPERATION} is generated if @code{glIsQuery} is executed |
14133 | between the execution of @code{glBegin} and the corresponding execution | |
14134 | of @code{glEnd}. | |
14135 | ||
bb894c9d | 14136 | @end deftypefun |
8925f36f | 14137 | |
bb894c9d | 14138 | @deftypefun GLboolean glIsShader shader |
3c9b6116 AW |
14139 | Determines if a name corresponds to a shader object. |
14140 | ||
8925f36f AW |
14141 | @table @asis |
14142 | @item @var{shader} | |
14143 | Specifies a potential shader object. | |
14144 | ||
14145 | @end table | |
14146 | ||
8925f36f AW |
14147 | @code{glIsShader} returns @code{GL_TRUE} if @var{shader} is the name of |
14148 | a shader object previously created with @code{glCreateShader} and not | |
c7b31271 | 14149 | yet deleted with @code{glDeleteShader}. If @var{shader} is zero or a |
8925f36f AW |
14150 | non-zero value that is not the name of a shader object, or if an error |
14151 | occurs, @code{glIsShader } returns @code{GL_FALSE}. | |
14152 | ||
8925f36f AW |
14153 | @code{GL_INVALID_OPERATION} is generated if @code{glIsShader} is |
14154 | executed between the execution of @code{glBegin} and the corresponding | |
14155 | execution of @code{glEnd}. | |
14156 | ||
bb894c9d | 14157 | @end deftypefun |
8925f36f | 14158 | |
bb894c9d | 14159 | @deftypefun GLboolean glIsTexture texture |
3c9b6116 AW |
14160 | Determine if a name corresponds to a texture. |
14161 | ||
8925f36f AW |
14162 | @table @asis |
14163 | @item @var{texture} | |
14164 | Specifies a value that may be the name of a texture. | |
14165 | ||
14166 | @end table | |
14167 | ||
8925f36f | 14168 | @code{glIsTexture} returns @code{GL_TRUE} if @var{texture} is currently |
c7b31271 | 14169 | the name of a texture. If @var{texture} is zero, or is a non-zero value |
8925f36f AW |
14170 | that is not currently the name of a texture, or if an error occurs, |
14171 | @code{glIsTexture} returns @code{GL_FALSE}. | |
14172 | ||
14173 | A name returned by @code{glGenTextures}, but not yet associated with a | |
14174 | texture by calling @code{glBindTexture}, is not the name of a texture. | |
14175 | ||
8925f36f AW |
14176 | @code{GL_INVALID_OPERATION} is generated if @code{glIsTexture} is |
14177 | executed between the execution of @code{glBegin} and the corresponding | |
14178 | execution of @code{glEnd}. | |
14179 | ||
bb894c9d | 14180 | @end deftypefun |
8925f36f | 14181 | |
bb894c9d AW |
14182 | @deftypefun void glLightModelf pname param |
14183 | @deftypefunx void glLightModeli pname param | |
d172eed9 AW |
14184 | @deftypefunx void glLightModelfv pname params |
14185 | @deftypefunx void glLightModeliv pname params | |
3c9b6116 AW |
14186 | Set the lighting model parameters. |
14187 | ||
8925f36f AW |
14188 | @table @asis |
14189 | @item @var{pname} | |
14190 | Specifies a single-valued lighting model parameter. | |
14191 | @code{GL_LIGHT_MODEL_LOCAL_VIEWER}, @code{GL_LIGHT_MODEL_COLOR_CONTROL}, | |
14192 | and @code{GL_LIGHT_MODEL_TWO_SIDE} are accepted. | |
14193 | ||
14194 | @item @var{param} | |
14195 | Specifies the value that @var{param} will be set to. | |
14196 | ||
14197 | @end table | |
14198 | ||
c7b31271 DH |
14199 | @code{glLightModel} sets the lighting model parameter. @var{pname} |
14200 | names a parameter and @var{params} gives the new value. There are three | |
8925f36f AW |
14201 | lighting model parameters: |
14202 | ||
14203 | @table @asis | |
14204 | @item @code{GL_LIGHT_MODEL_AMBIENT} | |
14205 | ||
14206 | ||
14207 | @var{params} contains four integer or floating-point values that specify | |
c7b31271 | 14208 | the ambient RGBA intensity of the entire scene. Integer values are |
8925f36f | 14209 | mapped linearly such that the most positive representable value maps to |
3c9b6116 | 14210 | 1.0, and the most negative representable value maps to @r{-1.0}. |
c7b31271 DH |
14211 | Floating-point values are mapped directly. Neither integer nor |
14212 | floating-point values are clamped. The initial ambient scene intensity | |
8925f36f AW |
14213 | is (0.2, 0.2, 0.2, 1.0). |
14214 | ||
14215 | @item @code{GL_LIGHT_MODEL_COLOR_CONTROL} | |
14216 | ||
14217 | ||
14218 | @var{params} must be either @code{GL_SEPARATE_SPECULAR_COLOR} or | |
c7b31271 | 14219 | @code{GL_SINGLE_COLOR}. @code{GL_SINGLE_COLOR} specifies that a single |
8925f36f AW |
14220 | color is generated from the lighting computation for a vertex. |
14221 | @code{GL_SEPARATE_SPECULAR_COLOR} specifies that the specular color | |
14222 | computation of lighting be stored separately from the remainder of the | |
c7b31271 | 14223 | lighting computation. The specular color is summed into the generated |
8925f36f AW |
14224 | fragment's color after the application of texture mapping (if enabled). |
14225 | The initial value is @code{GL_SINGLE_COLOR}. | |
14226 | ||
14227 | @item @code{GL_LIGHT_MODEL_LOCAL_VIEWER} | |
14228 | ||
14229 | ||
14230 | @var{params} is a single integer or floating-point value that specifies | |
c7b31271 | 14231 | how specular reflection angles are computed. If @var{params} is 0 (or |
8925f36f AW |
14232 | 0.0), specular reflection angles take the view direction to be parallel |
14233 | to and in the direction of the -@var{z} axis, regardless of the location | |
c7b31271 DH |
14234 | of the vertex in eye coordinates. Otherwise, specular reflections are |
14235 | computed from the origin of the eye coordinate system. The initial | |
14236 | value is 0. | |
8925f36f AW |
14237 | |
14238 | @item @code{GL_LIGHT_MODEL_TWO_SIDE} | |
14239 | ||
14240 | ||
14241 | @var{params} is a single integer or floating-point value that specifies | |
14242 | whether one- or two-sided lighting calculations are done for polygons. | |
14243 | It has no effect on the lighting calculations for points, lines, or | |
c7b31271 DH |
14244 | bitmaps. If @var{params} is 0 (or 0.0), one-sided lighting is |
14245 | specified, and only the @var{front} material parameters are used in the | |
14246 | lighting equation. Otherwise, two-sided lighting is specified. In this | |
14247 | case, vertices of back-facing polygons are lighted using the @var{back} | |
8925f36f | 14248 | material parameters and have their normals reversed before the lighting |
c7b31271 | 14249 | equation is evaluated. Vertices of front-facing polygons are always |
8925f36f | 14250 | lighted using the @var{front} material parameters, with no change to |
c7b31271 | 14251 | their normals. The initial value is 0. |
8925f36f AW |
14252 | |
14253 | @end table | |
14254 | ||
14255 | In RGBA mode, the lighted color of a vertex is the sum of the material | |
14256 | emission intensity, the product of the material ambient reflectance and | |
14257 | the lighting model full-scene ambient intensity, and the contribution of | |
c7b31271 DH |
14258 | each enabled light source. Each light source contributes the sum of |
14259 | three terms: ambient, diffuse, and specular. The ambient light source | |
8925f36f | 14260 | contribution is the product of the material ambient reflectance and the |
c7b31271 | 14261 | light's ambient intensity. The diffuse light source contribution is the |
8925f36f AW |
14262 | product of the material diffuse reflectance, the light's diffuse |
14263 | intensity, and the dot product of the vertex's normal with the | |
c7b31271 | 14264 | normalized vector from the vertex to the light source. The specular |
8925f36f AW |
14265 | light source contribution is the product of the material specular |
14266 | reflectance, the light's specular intensity, and the dot product of the | |
14267 | normalized vertex-to-eye and vertex-to-light vectors, raised to the | |
c7b31271 | 14268 | power of the shininess of the material. All three light source |
8925f36f AW |
14269 | contributions are attenuated equally based on the distance from the |
14270 | vertex to the light source and on light source direction, spread | |
c7b31271 | 14271 | exponent, and spread cutoff angle. All dot products are replaced with 0 |
8925f36f AW |
14272 | if they evaluate to a negative value. |
14273 | ||
14274 | The alpha component of the resulting lighted color is set to the alpha | |
14275 | value of the material diffuse reflectance. | |
14276 | ||
14277 | In color index mode, the value of the lighted index of a vertex ranges | |
14278 | from the ambient to the specular values passed to @code{glMaterial} | |
c7b31271 | 14279 | using @code{GL_COLOR_INDEXES}. Diffuse and specular coefficients, |
8925f36f AW |
14280 | computed with a (.30, .59, .11) weighting of the lights' colors, the |
14281 | shininess of the material, and the same reflection and attenuation | |
14282 | equations as in the RGBA case, determine how much above ambient the | |
14283 | resulting index is. | |
14284 | ||
8925f36f AW |
14285 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted |
14286 | value. | |
14287 | ||
14288 | @code{GL_INVALID_ENUM} is generated if @var{pname} is | |
14289 | @code{GL_LIGHT_MODEL_COLOR_CONTROL} and @var{params} is not one of | |
14290 | @code{GL_SINGLE_COLOR} or @code{GL_SEPARATE_SPECULAR_COLOR}. | |
14291 | ||
14292 | @code{GL_INVALID_OPERATION} is generated if @code{glLightModel} is | |
14293 | executed between the execution of @code{glBegin} and the corresponding | |
14294 | execution of @code{glEnd}. | |
14295 | ||
bb894c9d | 14296 | @end deftypefun |
8925f36f | 14297 | |
bb894c9d AW |
14298 | @deftypefun void glLightf light pname param |
14299 | @deftypefunx void glLighti light pname param | |
d172eed9 AW |
14300 | @deftypefunx void glLightfv light pname params |
14301 | @deftypefunx void glLightiv light pname params | |
3c9b6116 AW |
14302 | Set light source parameters. |
14303 | ||
8925f36f AW |
14304 | @table @asis |
14305 | @item @var{light} | |
c7b31271 DH |
14306 | Specifies a light. The number of lights depends on the implementation, |
14307 | but at least eight lights are supported. They are identified by | |
14308 | symbolic names of the form @code{GL_LIGHT}@r{@var{i}}, where i ranges | |
14309 | from 0 to the value of @code{GL_MAX_LIGHTS} - 1. | |
8925f36f AW |
14310 | |
14311 | @item @var{pname} | |
14312 | Specifies a single-valued light source parameter for @var{light}. | |
14313 | @code{GL_SPOT_EXPONENT}, @code{GL_SPOT_CUTOFF}, | |
14314 | @code{GL_CONSTANT_ATTENUATION}, @code{GL_LINEAR_ATTENUATION}, and | |
14315 | @code{GL_QUADRATIC_ATTENUATION} are accepted. | |
14316 | ||
14317 | @item @var{param} | |
14318 | Specifies the value that parameter @var{pname} of light source | |
14319 | @var{light} will be set to. | |
14320 | ||
14321 | @end table | |
14322 | ||
8925f36f AW |
14323 | @code{glLight} sets the values of individual light source parameters. |
14324 | @var{light} names the light and is a symbolic name of the form | |
3c9b6116 | 14325 | @code{GL_LIGHT}@r{@var{i}}, where i ranges from 0 to the value of |
c7b31271 DH |
14326 | @code{GL_MAX_LIGHTS} - 1. @var{pname} specifies one of ten light source |
14327 | parameters, again by symbolic name. @var{params} is either a single | |
8925f36f AW |
14328 | value or a pointer to an array that contains the new values. |
14329 | ||
14330 | To enable and disable lighting calculation, call @code{glEnable} and | |
c7b31271 DH |
14331 | @code{glDisable} with argument @code{GL_LIGHTING}. Lighting is |
14332 | initially disabled. When it is enabled, light sources that are enabled | |
14333 | contribute to the lighting calculation. Light source @r{@var{i}} is | |
14334 | enabled and disabled using @code{glEnable} and @code{glDisable} with | |
14335 | argument @code{GL_LIGHT}@r{@var{i}}. | |
8925f36f AW |
14336 | |
14337 | The ten light parameters are as follows: | |
14338 | ||
14339 | @table @asis | |
14340 | @item @code{GL_AMBIENT} | |
14341 | @var{params} contains four integer or floating-point values that specify | |
c7b31271 | 14342 | the ambient RGBA intensity of the light. Integer values are mapped |
8925f36f | 14343 | linearly such that the most positive representable value maps to 1.0, |
3c9b6116 | 14344 | and the most negative representable value maps to @r{-1.0}. |
c7b31271 DH |
14345 | Floating-point values are mapped directly. Neither integer nor |
14346 | floating-point values are clamped. The initial ambient light intensity | |
8925f36f AW |
14347 | is (0, 0, 0, 1). |
14348 | ||
14349 | @item @code{GL_DIFFUSE} | |
14350 | @var{params} contains four integer or floating-point values that specify | |
c7b31271 | 14351 | the diffuse RGBA intensity of the light. Integer values are mapped |
8925f36f | 14352 | linearly such that the most positive representable value maps to 1.0, |
3c9b6116 | 14353 | and the most negative representable value maps to @r{-1.0}. |
c7b31271 DH |
14354 | Floating-point values are mapped directly. Neither integer nor |
14355 | floating-point values are clamped. The initial value for | |
8925f36f AW |
14356 | @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial value is |
14357 | (0, 0, 0, 1). | |
14358 | ||
14359 | @item @code{GL_SPECULAR} | |
14360 | @var{params} contains four integer or floating-point values that specify | |
c7b31271 | 14361 | the specular RGBA intensity of the light. Integer values are mapped |
8925f36f | 14362 | linearly such that the most positive representable value maps to 1.0, |
3c9b6116 | 14363 | and the most negative representable value maps to @r{-1.0}. |
c7b31271 DH |
14364 | Floating-point values are mapped directly. Neither integer nor |
14365 | floating-point values are clamped. The initial value for | |
8925f36f AW |
14366 | @code{GL_LIGHT0} is (1, 1, 1, 1); for other lights, the initial value is |
14367 | (0, 0, 0, 1). | |
14368 | ||
14369 | @item @code{GL_POSITION} | |
14370 | @var{params} contains four integer or floating-point values that specify | |
c7b31271 DH |
14371 | the position of the light in homogeneous object coordinates. Both |
14372 | integer and floating-point values are mapped directly. Neither integer | |
8925f36f AW |
14373 | nor floating-point values are clamped. |
14374 | ||
14375 | The position is transformed by the modelview matrix when @code{glLight} | |
14376 | is called (just as if it were a point), and it is stored in eye | |
c7b31271 DH |
14377 | coordinates. If the @r{@var{w}} component of the position is 0, the |
14378 | light is treated as a directional source. Diffuse and specular lighting | |
8925f36f | 14379 | calculations take the light's direction, but not its actual position, |
c7b31271 | 14380 | into account, and attenuation is disabled. Otherwise, diffuse and |
8925f36f | 14381 | specular lighting calculations are based on the actual location of the |
c7b31271 | 14382 | light in eye coordinates, and attenuation is enabled. The initial |
8925f36f | 14383 | position is (0, 0, 1, 0); thus, the initial light source is directional, |
3c9b6116 | 14384 | parallel to, and in the direction of the @r{-@var{z}} axis. |
8925f36f AW |
14385 | |
14386 | @item @code{GL_SPOT_DIRECTION} | |
14387 | @var{params} contains three integer or floating-point values that | |
14388 | specify the direction of the light in homogeneous object coordinates. | |
c7b31271 | 14389 | Both integer and floating-point values are mapped directly. Neither |
8925f36f AW |
14390 | integer nor floating-point values are clamped. |
14391 | ||
14392 | The spot direction is transformed by the upper 3x3 of the modelview | |
14393 | matrix when @code{glLight} is called, and it is stored in eye | |
c7b31271 DH |
14394 | coordinates. It is significant only when @code{GL_SPOT_CUTOFF} is not |
14395 | 180, which it is initially. The initial direction is @r{(0,0-1)}. | |
8925f36f AW |
14396 | |
14397 | @item @code{GL_SPOT_EXPONENT} | |
14398 | @var{params} is a single integer or floating-point value that specifies | |
c7b31271 DH |
14399 | the intensity distribution of the light. Integer and floating-point |
14400 | values are mapped directly. Only values in the range @r{[0,128]} are | |
8925f36f AW |
14401 | accepted. |
14402 | ||
14403 | Effective light intensity is attenuated by the cosine of the angle | |
14404 | between the direction of the light and the direction from the light to | |
14405 | the vertex being lighted, raised to the power of the spot exponent. | |
14406 | Thus, higher spot exponents result in a more focused light source, | |
14407 | regardless of the spot cutoff angle (see @code{GL_SPOT_CUTOFF}, next | |
c7b31271 | 14408 | paragraph). The initial spot exponent is 0, resulting in uniform light |
8925f36f AW |
14409 | distribution. |
14410 | ||
14411 | @item @code{GL_SPOT_CUTOFF} | |
14412 | @var{params} is a single integer or floating-point value that specifies | |
c7b31271 DH |
14413 | the maximum spread angle of a light source. Integer and floating-point |
14414 | values are mapped directly. Only values in the range @r{[0,90]} and the | |
14415 | special value 180 are accepted. If the angle between the direction of | |
3c9b6116 AW |
14416 | the light and the direction from the light to the vertex being lighted |
14417 | is greater than the spot cutoff angle, the light is completely masked. | |
14418 | Otherwise, its intensity is controlled by the spot exponent and the | |
c7b31271 | 14419 | attenuation factors. The initial spot cutoff is 180, resulting in |
8925f36f AW |
14420 | uniform light distribution. |
14421 | ||
14422 | @item @code{GL_CONSTANT_ATTENUATION} | |
14423 | @item @code{GL_LINEAR_ATTENUATION} | |
14424 | @item @code{GL_QUADRATIC_ATTENUATION} | |
14425 | @var{params} is a single integer or floating-point value that specifies | |
c7b31271 DH |
14426 | one of the three light attenuation factors. Integer and floating-point |
14427 | values are mapped directly. Only nonnegative values are accepted. If | |
14428 | the light is positional, rather than directional, its intensity is | |
8925f36f AW |
14429 | attenuated by the reciprocal of the sum of the constant factor, the |
14430 | linear factor times the distance between the light and the vertex being | |
14431 | lighted, and the quadratic factor times the square of the same distance. | |
14432 | The initial attenuation factors are (1, 0, 0), resulting in no | |
14433 | attenuation. | |
14434 | ||
14435 | @end table | |
14436 | ||
8925f36f AW |
14437 | @code{GL_INVALID_ENUM} is generated if either @var{light} or @var{pname} |
14438 | is not an accepted value. | |
14439 | ||
14440 | @code{GL_INVALID_VALUE} is generated if a spot exponent value is | |
3c9b6116 AW |
14441 | specified outside the range @r{[0,128]}, or if spot cutoff is specified |
14442 | outside the range @r{[0,90]} (except for the special value 180), or if a | |
14443 | negative attenuation factor is specified. | |
8925f36f AW |
14444 | |
14445 | @code{GL_INVALID_OPERATION} is generated if @code{glLight} is executed | |
14446 | between the execution of @code{glBegin} and the corresponding execution | |
14447 | of @code{glEnd}. | |
14448 | ||
bb894c9d | 14449 | @end deftypefun |
8925f36f | 14450 | |
bb894c9d | 14451 | @deftypefun void glLineStipple factor pattern |
3c9b6116 AW |
14452 | Specify the line stipple pattern. |
14453 | ||
8925f36f AW |
14454 | @table @asis |
14455 | @item @var{factor} | |
c7b31271 | 14456 | Specifies a multiplier for each bit in the line stipple pattern. If |
8925f36f | 14457 | @var{factor} is 3, for example, each bit in the pattern is used three |
c7b31271 | 14458 | times before the next bit in the pattern is used. @var{factor} is |
8925f36f AW |
14459 | clamped to the range [1, 256] and defaults to 1. |
14460 | ||
14461 | @item @var{pattern} | |
14462 | Specifies a 16-bit integer whose bit pattern determines which fragments | |
c7b31271 | 14463 | of a line will be drawn when the line is rasterized. Bit zero is used |
8925f36f AW |
14464 | first; the default pattern is all 1's. |
14465 | ||
14466 | @end table | |
14467 | ||
8925f36f | 14468 | Line stippling masks out certain fragments produced by rasterization; |
c7b31271 | 14469 | those fragments will not be drawn. The masking is achieved by using |
8925f36f | 14470 | three parameters: the 16-bit line stipple pattern @var{pattern}, the |
3c9b6116 | 14471 | repeat count @var{factor}, and an integer stipple counter @r{@var{s}}. |
8925f36f | 14472 | |
3c9b6116 AW |
14473 | Counter @r{@var{s}} is reset to 0 whenever @code{glBegin} is called and |
14474 | before each line segment of a | |
c7b31271 | 14475 | @code{glBegin}(@code{GL_LINES})/@code{glEnd} sequence is generated. It |
8925f36f | 14476 | is incremented after each fragment of a unit width aliased line segment |
3c9b6116 | 14477 | is generated or after each @r{@var{i}} fragments of an @r{@var{i}} width |
c7b31271 | 14478 | line segment are generated. The @r{@var{i}} fragments associated with |
3c9b6116 | 14479 | count @r{@var{s}} are masked out if |
8925f36f | 14480 | |
3c9b6116 | 14481 | @var{pattern} bit @r{(@var{s}/@var{factor},)%16} |
8925f36f | 14482 | |
c7b31271 | 14483 | is 0, otherwise these fragments are sent to the frame buffer. Bit zero |
8925f36f AW |
14484 | of @var{pattern} is the least significant bit. |
14485 | ||
3c9b6116 | 14486 | Antialiased lines are treated as a sequence of @r{1×@var{width}} |
c7b31271 | 14487 | rectangles for purposes of stippling. Whether rectangle @r{@var{s}} is |
3c9b6116 | 14488 | rasterized or not depends on the fragment rule described for aliased |
8925f36f AW |
14489 | lines, counting rectangles rather than groups of fragments. |
14490 | ||
14491 | To enable and disable line stippling, call @code{glEnable} and | |
c7b31271 DH |
14492 | @code{glDisable} with argument @code{GL_LINE_STIPPLE}. When enabled, |
14493 | the line stipple pattern is applied as described above. When disabled, | |
14494 | it is as if the pattern were all 1's. Initially, line stippling is | |
14495 | disabled. | |
8925f36f | 14496 | |
8925f36f AW |
14497 | @code{GL_INVALID_OPERATION} is generated if @code{glLineStipple} is |
14498 | executed between the execution of @code{glBegin} and the corresponding | |
14499 | execution of @code{glEnd}. | |
14500 | ||
bb894c9d | 14501 | @end deftypefun |
8925f36f | 14502 | |
bb894c9d | 14503 | @deftypefun void glLineWidth width |
3c9b6116 AW |
14504 | Specify the width of rasterized lines. |
14505 | ||
8925f36f AW |
14506 | @table @asis |
14507 | @item @var{width} | |
c7b31271 | 14508 | Specifies the width of rasterized lines. The initial value is 1. |
8925f36f AW |
14509 | |
14510 | @end table | |
14511 | ||
8925f36f | 14512 | @code{glLineWidth} specifies the rasterized width of both aliased and |
c7b31271 DH |
14513 | antialiased lines. Using a line width other than 1 has different |
14514 | effects, depending on whether line antialiasing is enabled. To enable | |
8925f36f | 14515 | and disable line antialiasing, call @code{glEnable} and @code{glDisable} |
c7b31271 | 14516 | with argument @code{GL_LINE_SMOOTH}. Line antialiasing is initially |
8925f36f AW |
14517 | disabled. |
14518 | ||
14519 | If line antialiasing is disabled, the actual width is determined by | |
c7b31271 | 14520 | rounding the supplied width to the nearest integer. (If the rounding |
8925f36f | 14521 | results in the value 0, it is as if the line width were 1.) If |
3c9b6116 AW |
14522 | @r{∣Δ@var{x},∣>=∣Δ@var{y},∣}, @var{i} pixels are filled in each column |
14523 | that is rasterized, where @var{i} is the rounded value of @var{width}. | |
14524 | Otherwise, @var{i} pixels are filled in each row that is rasterized. | |
8925f36f AW |
14525 | |
14526 | If antialiasing is enabled, line rasterization produces a fragment for | |
14527 | each pixel square that intersects the region lying within the rectangle | |
14528 | having width equal to the current line width, length equal to the actual | |
c7b31271 | 14529 | length of the line, and centered on the mathematical line segment. The |
8925f36f AW |
14530 | coverage value for each fragment is the window coordinate area of the |
14531 | intersection of the rectangular region with the corresponding pixel | |
c7b31271 | 14532 | square. This value is saved and used in the final rasterization step. |
8925f36f | 14533 | |
c7b31271 DH |
14534 | Not all widths can be supported when line antialiasing is enabled. If |
14535 | an unsupported width is requested, the nearest supported width is used. | |
8925f36f | 14536 | Only width 1 is guaranteed to be supported; others depend on the |
c7b31271 DH |
14537 | implementation. Likewise, there is a range for aliased line widths as |
14538 | well. To query the range of supported widths and the size difference | |
8925f36f AW |
14539 | between supported widths within the range, call @code{glGet} with |
14540 | arguments @code{GL_ALIASED_LINE_WIDTH_RANGE}, | |
14541 | @code{GL_SMOOTH_LINE_WIDTH_RANGE}, and | |
14542 | @code{GL_SMOOTH_LINE_WIDTH_GRANULARITY}. | |
14543 | ||
8925f36f AW |
14544 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than or |
14545 | equal to 0. | |
14546 | ||
14547 | @code{GL_INVALID_OPERATION} is generated if @code{glLineWidth} is | |
14548 | executed between the execution of @code{glBegin} and the corresponding | |
14549 | execution of @code{glEnd}. | |
14550 | ||
bb894c9d | 14551 | @end deftypefun |
8925f36f | 14552 | |
bb894c9d | 14553 | @deftypefun void glLinkProgram program |
3c9b6116 AW |
14554 | Links a program object. |
14555 | ||
8925f36f AW |
14556 | @table @asis |
14557 | @item @var{program} | |
14558 | Specifies the handle of the program object to be linked. | |
14559 | ||
14560 | @end table | |
14561 | ||
8925f36f | 14562 | @code{glLinkProgram} links the program object specified by |
c7b31271 DH |
14563 | @var{program}. If any shader objects of type @code{GL_VERTEX_SHADER} |
14564 | are attached to @var{program}, they will be used to create an executable | |
14565 | that will run on the programmable vertex processor. If any shader | |
8925f36f AW |
14566 | objects of type @code{GL_FRAGMENT_SHADER} are attached to @var{program}, |
14567 | they will be used to create an executable that will run on the | |
14568 | programmable fragment processor. | |
14569 | ||
14570 | The status of the link operation will be stored as part of the program | |
c7b31271 | 14571 | object's state. This value will be set to @code{GL_TRUE} if the program |
8925f36f | 14572 | object was linked without errors and is ready for use, and |
c7b31271 | 14573 | @code{GL_FALSE} otherwise. It can be queried by calling |
8925f36f AW |
14574 | @code{glGetProgram} with arguments @var{program} and |
14575 | @code{GL_LINK_STATUS}. | |
14576 | ||
14577 | As a result of a successful link operation, all active user-defined | |
14578 | uniform variables belonging to @var{program} will be initialized to 0, | |
14579 | and each of the program object's active uniform variables will be | |
14580 | assigned a location that can be queried by calling | |
c7b31271 | 14581 | @code{glGetUniformLocation}. Also, any active user-defined attribute |
8925f36f AW |
14582 | variables that have not been bound to a generic vertex attribute index |
14583 | will be bound to one at this time. | |
14584 | ||
14585 | Linking of a program object can fail for a number of reasons as | |
c7b31271 | 14586 | specified in the @var{OpenGL Shading Language Specification}. The |
8925f36f AW |
14587 | following lists some of the conditions that will cause a link error. |
14588 | ||
14589 | @itemize | |
14590 | @item | |
14591 | The number of active attribute variables supported by the implementation | |
14592 | has been exceeded. | |
14593 | ||
14594 | @item | |
14595 | The storage limit for uniform variables has been exceeded. | |
14596 | ||
14597 | @item | |
14598 | The number of active uniform variables supported by the implementation | |
14599 | has been exceeded. | |
14600 | ||
14601 | @item | |
14602 | The @code{main} function is missing for the vertex shader or the | |
14603 | fragment shader. | |
14604 | ||
14605 | @item | |
14606 | A varying variable actually used in the fragment shader is not declared | |
14607 | in the same way (or is not declared at all) in the vertex shader. | |
14608 | ||
14609 | @item | |
14610 | A reference to a function or variable name is unresolved. | |
14611 | ||
14612 | @item | |
14613 | A shared global is declared with two different types or two different | |
14614 | initial values. | |
14615 | ||
14616 | @item | |
14617 | One or more of the attached shader objects has not been successfully | |
14618 | compiled. | |
14619 | ||
14620 | @item | |
14621 | Binding a generic attribute matrix caused some rows of the matrix to | |
14622 | fall outside the allowed maximum of @code{GL_MAX_VERTEX_ATTRIBS}. | |
14623 | ||
14624 | @item | |
14625 | Not enough contiguous vertex attribute slots could be found to bind | |
14626 | attribute matrices. | |
14627 | ||
14628 | @end itemize | |
14629 | ||
14630 | When a program object has been successfully linked, the program object | |
14631 | can be made part of current state by calling @code{glUseProgram}. | |
14632 | Whether or not the link operation was successful, the program object's | |
c7b31271 | 14633 | information log will be overwritten. The information log can be |
8925f36f AW |
14634 | retrieved by calling @code{glGetProgramInfoLog}. |
14635 | ||
14636 | @code{glLinkProgram} will also install the generated executables as part | |
14637 | of the current rendering state if the link operation was successful and | |
14638 | the specified program object is already currently in use as a result of | |
c7b31271 | 14639 | a previous call to @code{glUseProgram}. If the program object currently |
8925f36f AW |
14640 | in use is relinked unsuccessfully, its link status will be set to |
14641 | @code{GL_FALSE} , but the executables and associated state will remain | |
14642 | part of the current state until a subsequent call to @code{glUseProgram} | |
c7b31271 | 14643 | removes it from use. After it is removed from use, it cannot be made |
8925f36f AW |
14644 | part of current state until it has been successfully relinked. |
14645 | ||
14646 | If @var{program} contains shader objects of type @code{GL_VERTEX_SHADER} | |
14647 | but does not contain shader objects of type @code{GL_FRAGMENT_SHADER}, | |
14648 | the vertex shader will be linked against the implicit interface for | |
c7b31271 | 14649 | fixed functionality fragment processing. Similarly, if @var{program} |
8925f36f AW |
14650 | contains shader objects of type @code{GL_FRAGMENT_SHADER} but it does |
14651 | not contain shader objects of type @code{GL_VERTEX_SHADER}, the fragment | |
14652 | shader will be linked against the implicit interface for fixed | |
14653 | functionality vertex processing. | |
14654 | ||
14655 | The program object's information log is updated and the program is | |
c7b31271 | 14656 | generated at the time of the link operation. After the link operation, |
8925f36f AW |
14657 | applications are free to modify attached shader objects, compile |
14658 | attached shader objects, detach shader objects, delete shader objects, | |
c7b31271 | 14659 | and attach additional shader objects. None of these operations affects |
8925f36f AW |
14660 | the information log or the program that is part of the program object. |
14661 | ||
8925f36f AW |
14662 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
14663 | generated by OpenGL. | |
14664 | ||
14665 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
14666 | program object. | |
14667 | ||
14668 | @code{GL_INVALID_OPERATION} is generated if @code{glLinkProgram} is | |
14669 | executed between the execution of @code{glBegin} and the corresponding | |
14670 | execution of @code{glEnd}. | |
14671 | ||
bb894c9d | 14672 | @end deftypefun |
8925f36f | 14673 | |
bb894c9d | 14674 | @deftypefun void glListBase base |
3c9b6116 AW |
14675 | Set the display-list base for . |
14676 | ||
8925f36f AW |
14677 | @table @asis |
14678 | @item @var{base} | |
14679 | Specifies an integer offset that will be added to @code{glCallLists} | |
c7b31271 | 14680 | offsets to generate display-list names. The initial value is 0. |
8925f36f AW |
14681 | |
14682 | @end table | |
14683 | ||
c7b31271 DH |
14684 | @code{glCallLists} specifies an array of offsets. Display-list names |
14685 | are generated by adding @var{base} to each offset. Names that reference | |
8925f36f AW |
14686 | valid display lists are executed; the others are ignored. |
14687 | ||
8925f36f AW |
14688 | @code{GL_INVALID_OPERATION} is generated if @code{glListBase} is |
14689 | executed between the execution of @code{glBegin} and the corresponding | |
14690 | execution of @code{glEnd}. | |
14691 | ||
bb894c9d | 14692 | @end deftypefun |
8925f36f | 14693 | |
bb894c9d | 14694 | @deftypefun void glLoadIdentity |
3c9b6116 AW |
14695 | Replace the current matrix with the identity matrix. |
14696 | ||
8925f36f | 14697 | @code{glLoadIdentity} replaces the current matrix with the identity |
c7b31271 | 14698 | matrix. It is semantically equivalent to calling @code{glLoadMatrix} |
8925f36f AW |
14699 | with the identity matrix |
14700 | ||
14701 | ||
14702 | ||
3c9b6116 | 14703 | @r{((1 0 0 0), (0 1 0 0), (0 0 1 0), (0 0 0 1),,)} |
8925f36f AW |
14704 | |
14705 | ||
14706 | ||
14707 | but in some cases it is more efficient. | |
14708 | ||
8925f36f AW |
14709 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadIdentity} is |
14710 | executed between the execution of @code{glBegin} and the corresponding | |
14711 | execution of @code{glEnd}. | |
14712 | ||
bb894c9d | 14713 | @end deftypefun |
8925f36f | 14714 | |
d172eed9 AW |
14715 | @deftypefun void glLoadMatrixd m |
14716 | @deftypefunx void glLoadMatrixf m | |
3c9b6116 AW |
14717 | Replace the current matrix with the specified matrix. |
14718 | ||
8925f36f AW |
14719 | @table @asis |
14720 | @item @var{m} | |
14721 | Specifies a pointer to 16 consecutive values, which are used as the | |
3c9b6116 | 14722 | elements of a @r{4×4} column-major matrix. |
8925f36f AW |
14723 | |
14724 | @end table | |
14725 | ||
8925f36f | 14726 | @code{glLoadMatrix} replaces the current matrix with the one whose |
c7b31271 | 14727 | elements are specified by @var{m}. The current matrix is the projection |
8925f36f AW |
14728 | matrix, modelview matrix, or texture matrix, depending on the current |
14729 | matrix mode (see @code{glMatrixMode}). | |
14730 | ||
c7b31271 DH |
14731 | The current matrix, M, defines a transformation of coordinates. For |
14732 | instance, assume M refers to the modelview matrix. If | |
3c9b6116 AW |
14733 | @r{@var{v}=(@var{v}[0,],@var{v}[1,]@var{v}[2,]@var{v}[3,])} is the |
14734 | set of object coordinates of a vertex, and @var{m} points to an array of | |
14735 | @r{16} single- or double-precision floating-point values | |
14736 | @r{@var{m}=@{@var{m}[0,],@var{m}[1,]@var{...}@var{m}[15,]@}}, then | |
14737 | the modelview transformation @r{@var{M}(@var{v},)} does the following: | |
8925f36f | 14738 | |
3c9b6116 | 14739 | @r{@var{M}(@var{v},)=((@var{m}[0,] @var{m}[4,] @var{m}[8,] |
8925f36f AW |
14740 | @var{m}[12,]), (@var{m}[1,] @var{m}[5,] @var{m}[9,] @var{m}[13,]), |
14741 | (@var{m}[2,] @var{m}[6,] @var{m}[10,] @var{m}[14,]), (@var{m}[3,] | |
14742 | @var{m}[7,] @var{m}[11,] @var{m}[15,]),)×((@var{v}[0,]), | |
14743 | (@var{v}[1,]), (@var{v}[2,]), (@var{v}[3,]),)} | |
14744 | ||
14745 | ||
14746 | ||
14747 | Projection and texture transformations are similarly defined. | |
14748 | ||
8925f36f AW |
14749 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadMatrix} is |
14750 | executed between the execution of @code{glBegin} and the corresponding | |
14751 | execution of @code{glEnd}. | |
14752 | ||
bb894c9d | 14753 | @end deftypefun |
8925f36f | 14754 | |
bb894c9d | 14755 | @deftypefun void glLoadName name |
3c9b6116 AW |
14756 | Load a name onto the name stack. |
14757 | ||
8925f36f AW |
14758 | @table @asis |
14759 | @item @var{name} | |
14760 | Specifies a name that will replace the top value on the name stack. | |
14761 | ||
14762 | @end table | |
14763 | ||
8925f36f | 14764 | The name stack is used during selection mode to allow sets of rendering |
c7b31271 | 14765 | commands to be uniquely identified. It consists of an ordered set of |
8925f36f AW |
14766 | unsigned integers and is initially empty. |
14767 | ||
14768 | @code{glLoadName} causes @var{name} to replace the value on the top of | |
14769 | the name stack. | |
14770 | ||
14771 | The name stack is always empty while the render mode is not | |
c7b31271 | 14772 | @code{GL_SELECT}. Calls to @code{glLoadName} while the render mode is |
8925f36f AW |
14773 | not @code{GL_SELECT} are ignored. |
14774 | ||
8925f36f AW |
14775 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadName} is called |
14776 | while the name stack is empty. | |
14777 | ||
14778 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadName} is | |
14779 | executed between the execution of @code{glBegin} and the corresponding | |
14780 | execution of @code{glEnd}. | |
14781 | ||
bb894c9d | 14782 | @end deftypefun |
8925f36f | 14783 | |
d172eed9 AW |
14784 | @deftypefun void glLoadTransposeMatrixd m |
14785 | @deftypefunx void glLoadTransposeMatrixf m | |
3c9b6116 AW |
14786 | Replace the current matrix with the specified row-major ordered matrix. |
14787 | ||
8925f36f AW |
14788 | @table @asis |
14789 | @item @var{m} | |
14790 | Specifies a pointer to 16 consecutive values, which are used as the | |
3c9b6116 | 14791 | elements of a @r{4×4} row-major matrix. |
8925f36f AW |
14792 | |
14793 | @end table | |
14794 | ||
8925f36f | 14795 | @code{glLoadTransposeMatrix} replaces the current matrix with the one |
c7b31271 | 14796 | whose elements are specified by @var{m}. The current matrix is the |
8925f36f AW |
14797 | projection matrix, modelview matrix, or texture matrix, depending on the |
14798 | current matrix mode (see @code{glMatrixMode}). | |
14799 | ||
c7b31271 DH |
14800 | The current matrix, M, defines a transformation of coordinates. For |
14801 | instance, assume M refers to the modelview matrix. If | |
3c9b6116 AW |
14802 | @r{@var{v}=(@var{v}[0,],@var{v}[1,]@var{v}[2,]@var{v}[3,])} is the |
14803 | set of object coordinates of a vertex, and @var{m} points to an array of | |
14804 | @r{16} single- or double-precision floating-point values | |
14805 | @r{@var{m}=@{@var{m}[0,],@var{m}[1,]@var{...}@var{m}[15,]@}}, then | |
14806 | the modelview transformation @r{@var{M}(@var{v},)} does the following: | |
8925f36f | 14807 | |
3c9b6116 | 14808 | @r{@var{M}(@var{v},)=((@var{m}[0,] @var{m}[1,] @var{m}[2,] |
8925f36f AW |
14809 | @var{m}[3,]), (@var{m}[4,] @var{m}[5,] @var{m}[6,] @var{m}[7,]), |
14810 | (@var{m}[8,] @var{m}[9,] @var{m}[10,] @var{m}[11,]), (@var{m}[12,] | |
14811 | @var{m}[13,] @var{m}[14,] @var{m}[15,]),)×((@var{v}[0,]), | |
14812 | (@var{v}[1,]), (@var{v}[2,]), (@var{v}[3,]),)} | |
14813 | ||
14814 | ||
14815 | ||
14816 | Projection and texture transformations are similarly defined. | |
14817 | ||
3c9b6116 AW |
14818 | Calling @code{glLoadTransposeMatrix} with matrix @r{@var{M}} is |
14819 | identical in operation to @code{glLoadMatrix} with @r{@var{M}^@var{T}}, | |
14820 | where @r{@var{T}} represents the transpose. | |
8925f36f | 14821 | |
8925f36f AW |
14822 | @code{GL_INVALID_OPERATION} is generated if @code{glLoadTransposeMatrix} |
14823 | is executed between the execution of @code{glBegin} and the | |
14824 | corresponding execution of @code{glEnd}. | |
14825 | ||
bb894c9d | 14826 | @end deftypefun |
8925f36f | 14827 | |
bb894c9d | 14828 | @deftypefun void glLogicOp opcode |
3c9b6116 AW |
14829 | Specify a logical pixel operation for color index rendering. |
14830 | ||
8925f36f AW |
14831 | @table @asis |
14832 | @item @var{opcode} | |
c7b31271 | 14833 | Specifies a symbolic constant that selects a logical operation. The |
8925f36f AW |
14834 | following symbols are accepted: @code{GL_CLEAR}, @code{GL_SET}, |
14835 | @code{GL_COPY}, @code{GL_COPY_INVERTED}, @code{GL_NOOP}, | |
14836 | @code{GL_INVERT}, @code{GL_AND}, @code{GL_NAND}, @code{GL_OR}, | |
14837 | @code{GL_NOR}, @code{GL_XOR}, @code{GL_EQUIV}, @code{GL_AND_REVERSE}, | |
14838 | @code{GL_AND_INVERTED}, @code{GL_OR_REVERSE}, and @code{GL_OR_INVERTED}. | |
14839 | The initial value is @code{GL_COPY}. | |
14840 | ||
14841 | @end table | |
14842 | ||
8925f36f AW |
14843 | @code{glLogicOp} specifies a logical operation that, when enabled, is |
14844 | applied between the incoming color index or RGBA color and the color | |
14845 | index or RGBA color at the corresponding location in the frame buffer. | |
14846 | To enable or disable the logical operation, call @code{glEnable} and | |
14847 | @code{glDisable} using the symbolic constant @code{GL_COLOR_LOGIC_OP} | |
c7b31271 | 14848 | for RGBA mode or @code{GL_INDEX_LOGIC_OP} for color index mode. The |
8925f36f AW |
14849 | initial value is disabled for both operations. |
14850 | ||
14851 | ||
14852 | ||
14853 | @table @asis | |
14854 | @item @strong{Opcode} | |
14855 | @strong{Resulting Operation} | |
14856 | ||
14857 | @item @code{GL_CLEAR} | |
14858 | 0 | |
14859 | ||
14860 | @item @code{GL_SET} | |
14861 | 1 | |
14862 | ||
14863 | @item @code{GL_COPY} | |
14864 | s | |
14865 | ||
14866 | @item @code{GL_COPY_INVERTED} | |
14867 | ~s | |
14868 | ||
14869 | @item @code{GL_NOOP} | |
14870 | d | |
14871 | ||
14872 | @item @code{GL_INVERT} | |
14873 | ~d | |
14874 | ||
14875 | @item @code{GL_AND} | |
14876 | s & d | |
14877 | ||
14878 | @item @code{GL_NAND} | |
14879 | ~(s & d) | |
14880 | ||
14881 | @item @code{GL_OR} | |
14882 | s | d | |
14883 | ||
14884 | @item @code{GL_NOR} | |
14885 | ~(s | d) | |
14886 | ||
14887 | @item @code{GL_XOR} | |
14888 | s ^ d | |
14889 | ||
14890 | @item @code{GL_EQUIV} | |
14891 | ~(s ^ d) | |
14892 | ||
14893 | @item @code{GL_AND_REVERSE} | |
14894 | s & ~d | |
14895 | ||
14896 | @item @code{GL_AND_INVERTED} | |
14897 | ~s & d | |
14898 | ||
14899 | @item @code{GL_OR_REVERSE} | |
14900 | s | ~d | |
14901 | ||
14902 | @item @code{GL_OR_INVERTED} | |
14903 | ~s | d | |
14904 | ||
14905 | @end table | |
14906 | ||
c7b31271 | 14907 | @var{opcode} is a symbolic constant chosen from the list above. In the |
8925f36f AW |
14908 | explanation of the logical operations, @var{s} represents the incoming |
14909 | color index and @var{d} represents the index in the frame buffer. | |
c7b31271 | 14910 | Standard C-language operators are used. As these bitwise operators |
8925f36f AW |
14911 | suggest, the logical operation is applied independently to each bit pair |
14912 | of the source and destination indices or colors. | |
14913 | ||
8925f36f AW |
14914 | @code{GL_INVALID_ENUM} is generated if @var{opcode} is not an accepted |
14915 | value. | |
14916 | ||
14917 | @code{GL_INVALID_OPERATION} is generated if @code{glLogicOp} is executed | |
14918 | between the execution of @code{glBegin} and the corresponding execution | |
14919 | of @code{glEnd}. | |
14920 | ||
bb894c9d | 14921 | @end deftypefun |
8925f36f | 14922 | |
ca09631c | 14923 | @deftypefun void glMap1f target u1 u2 stride order points |
d172eed9 | 14924 | @deftypefunx void glMap1d target u1 u2 stride order points |
3c9b6116 AW |
14925 | Define a one-dimensional evaluator. |
14926 | ||
8925f36f AW |
14927 | @table @asis |
14928 | @item @var{target} | |
14929 | Specifies the kind of values that are generated by the evaluator. | |
14930 | Symbolic constants @code{GL_MAP1_VERTEX_3}, @code{GL_MAP1_VERTEX_4}, | |
14931 | @code{GL_MAP1_INDEX}, @code{GL_MAP1_COLOR_4}, @code{GL_MAP1_NORMAL}, | |
14932 | @code{GL_MAP1_TEXTURE_COORD_1}, @code{GL_MAP1_TEXTURE_COORD_2}, | |
14933 | @code{GL_MAP1_TEXTURE_COORD_3}, and @code{GL_MAP1_TEXTURE_COORD_4} are | |
14934 | accepted. | |
14935 | ||
14936 | @item @var{u1} | |
14937 | @itemx @var{u2} | |
3c9b6116 AW |
14938 | Specify a linear mapping of @r{@var{u}}, as presented to |
14939 | @code{glEvalCoord1}, to @r{@var{u}^}, the variable that is evaluated by | |
14940 | the equations specified by this command. | |
8925f36f AW |
14941 | |
14942 | @item @var{stride} | |
14943 | Specifies the number of floats or doubles between the beginning of one | |
14944 | control point and the beginning of the next one in the data structure | |
c7b31271 DH |
14945 | referenced in @var{points}. This allows control points to be embedded |
14946 | in arbitrary data structures. The only constraint is that the values | |
14947 | for a particular control point must occupy contiguous memory locations. | |
8925f36f AW |
14948 | |
14949 | @item @var{order} | |
c7b31271 | 14950 | Specifies the number of control points. Must be positive. |
8925f36f AW |
14951 | |
14952 | @item @var{points} | |
14953 | Specifies a pointer to the array of control points. | |
14954 | ||
14955 | @end table | |
14956 | ||
8925f36f AW |
14957 | Evaluators provide a way to use polynomial or rational polynomial |
14958 | mapping to produce vertices, normals, texture coordinates, and colors. | |
14959 | The values produced by an evaluator are sent to further stages of GL | |
14960 | processing just as if they had been presented using @code{glVertex}, | |
14961 | @code{glNormal}, @code{glTexCoord}, and @code{glColor} commands, except | |
14962 | that the generated values do not update the current normal, texture | |
14963 | coordinates, or color. | |
14964 | ||
14965 | All polynomial or rational polynomial splines of any degree (up to the | |
14966 | maximum degree supported by the GL implementation) can be described | |
c7b31271 | 14967 | using evaluators. These include almost all splines used in computer |
8925f36f AW |
14968 | graphics: B-splines, Bezier curves, Hermite splines, and so on. |
14969 | ||
c7b31271 | 14970 | Evaluators define curves based on Bernstein polynomials. Define |
3c9b6116 | 14971 | @r{@var{p}(@var{u}^,)} as |
8925f36f | 14972 | |
3c9b6116 | 14973 | @r{@var{p}(@var{u}^,)=Σ@var{i}=0@var{n}@var{B}_@var{i},^@var{n}(@var{u}^,)@var{R}_@var{i}} |
8925f36f AW |
14974 | |
14975 | ||
14976 | ||
3c9b6116 AW |
14977 | where @r{@var{R}_@var{i}} is a control point and |
14978 | @r{@var{B}_@var{i},^@var{n}(@var{u}^,)} is the @r{@var{i}}th Bernstein | |
14979 | polynomial of degree @r{@var{n}} (@var{order} = @r{@var{n}+1}): | |
8925f36f | 14980 | |
3c9b6116 | 14981 | @r{@var{B}_@var{i},^@var{n}(@var{u}^,)=((@var{n}), |
8925f36f AW |
14982 | (@var{i}),,)@var{u}^,^@var{i}(1-@var{u}^,)^@var{n}-@var{i},,} |
14983 | ||
14984 | Recall that | |
14985 | ||
3c9b6116 | 14986 | @r{0^0==1} and @r{((@var{n}), (0),,)==1} |
8925f36f AW |
14987 | |
14988 | @code{glMap1} is used to define the basis and to specify what kind of | |
c7b31271 | 14989 | values are produced. Once defined, a map can be enabled and disabled by |
8925f36f AW |
14990 | calling @code{glEnable} and @code{glDisable} with the map name, one of |
14991 | the nine predefined values for @var{target} described below. | |
14992 | @code{glEvalCoord1} evaluates the one-dimensional maps that are enabled. | |
3c9b6116 AW |
14993 | When @code{glEvalCoord1} presents a value @r{@var{u}}, the Bernstein |
14994 | functions are evaluated using @r{@var{u}^}, where | |
14995 | @r{@var{u}^=@var{u}-@var{u1},/@var{u2}-@var{u1},} | |
8925f36f AW |
14996 | |
14997 | @var{target} is a symbolic constant that indicates what kind of control | |
14998 | points are provided in @var{points}, and what output is generated when | |
c7b31271 | 14999 | the map is evaluated. It can assume one of nine predefined values: |
8925f36f AW |
15000 | |
15001 | @table @asis | |
15002 | @item @code{GL_MAP1_VERTEX_3} | |
15003 | Each control point is three floating-point values representing | |
c7b31271 | 15004 | @r{@var{x}}, @r{@var{y}}, and @r{@var{z}}. Internal @code{glVertex3} |
3c9b6116 | 15005 | commands are generated when the map is evaluated. |
8925f36f AW |
15006 | |
15007 | @item @code{GL_MAP1_VERTEX_4} | |
15008 | Each control point is four floating-point values representing | |
c7b31271 | 15009 | @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}. Internal |
3c9b6116 | 15010 | @code{glVertex4} commands are generated when the map is evaluated. |
8925f36f AW |
15011 | |
15012 | @item @code{GL_MAP1_INDEX} | |
15013 | Each control point is a single floating-point value representing a color | |
c7b31271 | 15014 | index. Internal @code{glIndex} commands are generated when the map is |
8925f36f AW |
15015 | evaluated but the current index is not updated with the value of these |
15016 | @code{glIndex} commands. | |
15017 | ||
15018 | @item @code{GL_MAP1_COLOR_4} | |
15019 | Each control point is four floating-point values representing red, | |
c7b31271 | 15020 | green, blue, and alpha. Internal @code{glColor4} commands are generated |
8925f36f AW |
15021 | when the map is evaluated but the current color is not updated with the |
15022 | value of these @code{glColor4} commands. | |
15023 | ||
15024 | @item @code{GL_MAP1_NORMAL} | |
15025 | Each control point is three floating-point values representing the | |
3c9b6116 AW |
15026 | @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} components of a normal vector. |
15027 | Internal @code{glNormal} commands are generated when the map is | |
15028 | evaluated but the current normal is not updated with the value of these | |
15029 | @code{glNormal} commands. | |
8925f36f AW |
15030 | |
15031 | @item @code{GL_MAP1_TEXTURE_COORD_1} | |
15032 | Each control point is a single floating-point value representing the | |
c7b31271 DH |
15033 | @r{@var{s}} texture coordinate. Internal @code{glTexCoord1} commands |
15034 | are generated when the map is evaluated but the current texture | |
15035 | coordinates are not updated with the value of these @code{glTexCoord} | |
15036 | commands. | |
8925f36f AW |
15037 | |
15038 | @item @code{GL_MAP1_TEXTURE_COORD_2} | |
15039 | Each control point is two floating-point values representing the | |
c7b31271 | 15040 | @r{@var{s}} and @r{@var{t}} texture coordinates. Internal |
8925f36f AW |
15041 | @code{glTexCoord2} commands are generated when the map is evaluated but |
15042 | the current texture coordinates are not updated with the value of these | |
15043 | @code{glTexCoord} commands. | |
15044 | ||
15045 | @item @code{GL_MAP1_TEXTURE_COORD_3} | |
15046 | Each control point is three floating-point values representing the | |
c7b31271 | 15047 | @r{@var{s}}, @r{@var{t}}, and @r{@var{r}} texture coordinates. Internal |
3c9b6116 AW |
15048 | @code{glTexCoord3} commands are generated when the map is evaluated but |
15049 | the current texture coordinates are not updated with the value of these | |
15050 | @code{glTexCoord} commands. | |
8925f36f AW |
15051 | |
15052 | @item @code{GL_MAP1_TEXTURE_COORD_4} | |
15053 | Each control point is four floating-point values representing the | |
3c9b6116 | 15054 | @r{@var{s}}, @r{@var{t}}, @r{@var{r}}, and @r{@var{q}} texture |
c7b31271 DH |
15055 | coordinates. Internal @code{glTexCoord4} commands are generated when |
15056 | the map is evaluated but the current texture coordinates are not updated | |
3c9b6116 | 15057 | with the value of these @code{glTexCoord} commands. |
8925f36f AW |
15058 | |
15059 | @end table | |
15060 | ||
15061 | @var{stride}, @var{order}, and @var{points} define the array addressing | |
c7b31271 | 15062 | for accessing the control points. @var{points} is the location of the |
8925f36f | 15063 | first control point, which occupies one, two, three, or four contiguous |
c7b31271 DH |
15064 | memory locations, depending on which map is being defined. @var{order} |
15065 | is the number of control points in the array. @var{stride} specifies | |
15066 | how many float or double locations to advance the internal memory | |
15067 | pointer to reach the next control point. | |
8925f36f | 15068 | |
8925f36f AW |
15069 | @code{GL_INVALID_ENUM} is generated if @var{target} is not an accepted |
15070 | value. | |
15071 | ||
15072 | @code{GL_INVALID_VALUE} is generated if @var{u1} is equal to @var{u2}. | |
15073 | ||
15074 | @code{GL_INVALID_VALUE} is generated if @var{stride} is less than the | |
15075 | number of values in a control point. | |
15076 | ||
15077 | @code{GL_INVALID_VALUE} is generated if @var{order} is less than 1 or | |
15078 | greater than the return value of @code{GL_MAX_EVAL_ORDER}. | |
15079 | ||
15080 | @code{GL_INVALID_OPERATION} is generated if @code{glMap1} is executed | |
15081 | between the execution of @code{glBegin} and the corresponding execution | |
15082 | of @code{glEnd}. | |
15083 | ||
15084 | @code{GL_INVALID_OPERATION} is generated if @code{glMap1} is called and | |
15085 | the value of @code{GL_ACTIVE_TEXTURE} is not @code{GL_TEXTURE0}. | |
15086 | ||
bb894c9d | 15087 | @end deftypefun |
8925f36f | 15088 | |
ca09631c | 15089 | @deftypefun void glMap2f target u1 u2 ustride uorder v1 v2 vstride vorder points |
d172eed9 | 15090 | @deftypefunx void glMap2d target u1 u2 ustride uorder v1 v2 vstride vorder points |
3c9b6116 AW |
15091 | Define a two-dimensional evaluator. |
15092 | ||
8925f36f AW |
15093 | @table @asis |
15094 | @item @var{target} | |
15095 | Specifies the kind of values that are generated by the evaluator. | |
15096 | Symbolic constants @code{GL_MAP2_VERTEX_3}, @code{GL_MAP2_VERTEX_4}, | |
15097 | @code{GL_MAP2_INDEX}, @code{GL_MAP2_COLOR_4}, @code{GL_MAP2_NORMAL}, | |
15098 | @code{GL_MAP2_TEXTURE_COORD_1}, @code{GL_MAP2_TEXTURE_COORD_2}, | |
15099 | @code{GL_MAP2_TEXTURE_COORD_3}, and @code{GL_MAP2_TEXTURE_COORD_4} are | |
15100 | accepted. | |
15101 | ||
15102 | @item @var{u1} | |
15103 | @itemx @var{u2} | |
3c9b6116 AW |
15104 | Specify a linear mapping of @r{@var{u}}, as presented to |
15105 | @code{glEvalCoord2}, to @r{@var{u}^}, one of the two variables that are | |
c7b31271 | 15106 | evaluated by the equations specified by this command. Initially, |
8925f36f AW |
15107 | @var{u1} is 0 and @var{u2} is 1. |
15108 | ||
15109 | @item @var{ustride} | |
15110 | Specifies the number of floats or doubles between the beginning of | |
3c9b6116 AW |
15111 | control point @r{@var{R}_@var{ij}} and the beginning of control point |
15112 | @r{@var{R}_(@var{i}+1,)@var{j},}, where @r{@var{i}} and @r{@var{j}} are | |
15113 | the @r{@var{u}} and @r{@var{v}} control point indices, respectively. | |
15114 | This allows control points to be embedded in arbitrary data structures. | |
15115 | The only constraint is that the values for a particular control point | |
c7b31271 | 15116 | must occupy contiguous memory locations. The initial value of |
3c9b6116 | 15117 | @var{ustride} is 0. |
8925f36f AW |
15118 | |
15119 | @item @var{uorder} | |
3c9b6116 | 15120 | Specifies the dimension of the control point array in the @r{@var{u}} |
c7b31271 | 15121 | axis. Must be positive. The initial value is 1. |
8925f36f AW |
15122 | |
15123 | @item @var{v1} | |
15124 | @itemx @var{v2} | |
3c9b6116 AW |
15125 | Specify a linear mapping of @r{@var{v}}, as presented to |
15126 | @code{glEvalCoord2}, to @r{@var{v}^}, one of the two variables that are | |
c7b31271 | 15127 | evaluated by the equations specified by this command. Initially, |
8925f36f AW |
15128 | @var{v1} is 0 and @var{v2} is 1. |
15129 | ||
15130 | @item @var{vstride} | |
15131 | Specifies the number of floats or doubles between the beginning of | |
3c9b6116 AW |
15132 | control point @r{@var{R}_@var{ij}} and the beginning of control point |
15133 | @r{@var{R}_@var{i}(@var{j}+1,),}, where @r{@var{i}} and @r{@var{j}} are | |
15134 | the @r{@var{u}} and @r{@var{v}} control point indices, respectively. | |
15135 | This allows control points to be embedded in arbitrary data structures. | |
15136 | The only constraint is that the values for a particular control point | |
c7b31271 | 15137 | must occupy contiguous memory locations. The initial value of |
3c9b6116 | 15138 | @var{vstride} is 0. |
8925f36f AW |
15139 | |
15140 | @item @var{vorder} | |
3c9b6116 | 15141 | Specifies the dimension of the control point array in the @r{@var{v}} |
c7b31271 | 15142 | axis. Must be positive. The initial value is 1. |
8925f36f AW |
15143 | |
15144 | @item @var{points} | |
15145 | Specifies a pointer to the array of control points. | |
15146 | ||
15147 | @end table | |
15148 | ||
8925f36f AW |
15149 | Evaluators provide a way to use polynomial or rational polynomial |
15150 | mapping to produce vertices, normals, texture coordinates, and colors. | |
15151 | The values produced by an evaluator are sent on to further stages of GL | |
15152 | processing just as if they had been presented using @code{glVertex}, | |
15153 | @code{glNormal}, @code{glTexCoord}, and @code{glColor} commands, except | |
15154 | that the generated values do not update the current normal, texture | |
15155 | coordinates, or color. | |
15156 | ||
15157 | All polynomial or rational polynomial splines of any degree (up to the | |
15158 | maximum degree supported by the GL implementation) can be described | |
c7b31271 | 15159 | using evaluators. These include almost all surfaces used in computer |
8925f36f AW |
15160 | graphics, including B-spline surfaces, NURBS surfaces, Bezier surfaces, |
15161 | and so on. | |
15162 | ||
15163 | Evaluators define surfaces based on bivariate Bernstein polynomials. | |
3c9b6116 | 15164 | Define @r{@var{p}(@var{u}^,@var{v}^)} as |
8925f36f | 15165 | |
3c9b6116 | 15166 | @r{@var{p}(@var{u}^,@var{v}^)=Σ@var{i}=0@var{n}Σ@var{j}=0@var{m}@var{B}_@var{i},^@var{n}(@var{u}^,)@var{B}_@var{j},^@var{m}(@var{v}^,)@var{R}_@var{ij}} |
8925f36f AW |
15167 | |
15168 | ||
15169 | ||
3c9b6116 AW |
15170 | where @r{@var{R}_@var{ij}} is a control point, |
15171 | @r{@var{B}_@var{i},^@var{n}(@var{u}^,)} is the @r{@var{i}}th Bernstein | |
15172 | polynomial of degree @r{@var{n}} (@var{uorder} = @r{@var{n}+1}) | |
8925f36f | 15173 | |
3c9b6116 | 15174 | @r{@var{B}_@var{i},^@var{n}(@var{u}^,)=((@var{n}), |
8925f36f AW |
15175 | (@var{i}),,)@var{u}^,^@var{i}(1-@var{u}^,)^@var{n}-@var{i},,} |
15176 | ||
3c9b6116 AW |
15177 | and @r{@var{B}_@var{j},^@var{m}(@var{v}^,)} is the @r{@var{j}}th |
15178 | Bernstein polynomial of degree @r{@var{m}} (@var{vorder} = | |
15179 | @r{@var{m}+1}) | |
8925f36f | 15180 | |
3c9b6116 | 15181 | @r{@var{B}_@var{j},^@var{m}(@var{v}^,)=((@var{m}), |
8925f36f AW |
15182 | (@var{j}),,)@var{v}^,^@var{j}(1-@var{v}^,)^@var{m}-@var{j},,} |
15183 | ||
3c9b6116 | 15184 | Recall that @r{0^0==1} and @r{((@var{n}), (0),,)==1} |
8925f36f AW |
15185 | |
15186 | @code{glMap2} is used to define the basis and to specify what kind of | |
c7b31271 | 15187 | values are produced. Once defined, a map can be enabled and disabled by |
8925f36f | 15188 | calling @code{glEnable} and @code{glDisable} with the map name, one of |
c7b31271 | 15189 | the nine predefined values for @var{target}, described below. When |
3c9b6116 AW |
15190 | @code{glEvalCoord2} presents values @r{@var{u}} and @r{@var{v}}, the |
15191 | bivariate Bernstein polynomials are evaluated using @r{@var{u}^} and | |
15192 | @r{@var{v}^}, where | |
8925f36f | 15193 | |
3c9b6116 | 15194 | @r{@var{u}^=@var{u}-@var{u1},/@var{u2}-@var{u1},} |
8925f36f | 15195 | |
3c9b6116 | 15196 | @r{@var{v}^=@var{v}-@var{v1},/@var{v2}-@var{v1},} |
8925f36f AW |
15197 | |
15198 | @var{target} is a symbolic constant that indicates what kind of control | |
15199 | points are provided in @var{points}, and what output is generated when | |
c7b31271 | 15200 | the map is evaluated. It can assume one of nine predefined values: |
8925f36f AW |
15201 | |
15202 | @table @asis | |
15203 | @item @code{GL_MAP2_VERTEX_3} | |
15204 | Each control point is three floating-point values representing | |
c7b31271 | 15205 | @r{@var{x}}, @r{@var{y}}, and @r{@var{z}}. Internal @code{glVertex3} |
3c9b6116 | 15206 | commands are generated when the map is evaluated. |
8925f36f AW |
15207 | |
15208 | @item @code{GL_MAP2_VERTEX_4} | |
15209 | Each control point is four floating-point values representing | |
c7b31271 | 15210 | @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}}. Internal |
3c9b6116 | 15211 | @code{glVertex4} commands are generated when the map is evaluated. |
8925f36f AW |
15212 | |
15213 | @item @code{GL_MAP2_INDEX} | |
15214 | Each control point is a single floating-point value representing a color | |
c7b31271 | 15215 | index. Internal @code{glIndex} commands are generated when the map is |
8925f36f AW |
15216 | evaluated but the current index is not updated with the value of these |
15217 | @code{glIndex} commands. | |
15218 | ||
15219 | @item @code{GL_MAP2_COLOR_4} | |
15220 | Each control point is four floating-point values representing red, | |
c7b31271 | 15221 | green, blue, and alpha. Internal @code{glColor4} commands are generated |
8925f36f AW |
15222 | when the map is evaluated but the current color is not updated with the |
15223 | value of these @code{glColor4} commands. | |
15224 | ||
15225 | @item @code{GL_MAP2_NORMAL} | |
15226 | Each control point is three floating-point values representing the | |
3c9b6116 AW |
15227 | @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} components of a normal vector. |
15228 | Internal @code{glNormal} commands are generated when the map is | |
15229 | evaluated but the current normal is not updated with the value of these | |
15230 | @code{glNormal} commands. | |
8925f36f AW |
15231 | |
15232 | @item @code{GL_MAP2_TEXTURE_COORD_1} | |
15233 | Each control point is a single floating-point value representing the | |
c7b31271 DH |
15234 | @r{@var{s}} texture coordinate. Internal @code{glTexCoord1} commands |
15235 | are generated when the map is evaluated but the current texture | |
15236 | coordinates are not updated with the value of these @code{glTexCoord} | |
15237 | commands. | |
8925f36f AW |
15238 | |
15239 | @item @code{GL_MAP2_TEXTURE_COORD_2} | |
15240 | Each control point is two floating-point values representing the | |
c7b31271 | 15241 | @r{@var{s}} and @r{@var{t}} texture coordinates. Internal |
8925f36f AW |
15242 | @code{glTexCoord2} commands are generated when the map is evaluated but |
15243 | the current texture coordinates are not updated with the value of these | |
15244 | @code{glTexCoord} commands. | |
15245 | ||
15246 | @item @code{GL_MAP2_TEXTURE_COORD_3} | |
15247 | Each control point is three floating-point values representing the | |
c7b31271 | 15248 | @r{@var{s}}, @r{@var{t}}, and @r{@var{r}} texture coordinates. Internal |
3c9b6116 AW |
15249 | @code{glTexCoord3} commands are generated when the map is evaluated but |
15250 | the current texture coordinates are not updated with the value of these | |
15251 | @code{glTexCoord} commands. | |
8925f36f AW |
15252 | |
15253 | @item @code{GL_MAP2_TEXTURE_COORD_4} | |
15254 | Each control point is four floating-point values representing the | |
3c9b6116 | 15255 | @r{@var{s}}, @r{@var{t}}, @r{@var{r}}, and @r{@var{q}} texture |
c7b31271 DH |
15256 | coordinates. Internal @code{glTexCoord4} commands are generated when |
15257 | the map is evaluated but the current texture coordinates are not updated | |
3c9b6116 | 15258 | with the value of these @code{glTexCoord} commands. |
8925f36f AW |
15259 | |
15260 | @end table | |
15261 | ||
15262 | @var{ustride}, @var{uorder}, @var{vstride}, @var{vorder}, and | |
15263 | @var{points} define the array addressing for accessing the control | |
c7b31271 | 15264 | points. @var{points} is the location of the first control point, which |
8925f36f | 15265 | occupies one, two, three, or four contiguous memory locations, depending |
c7b31271 DH |
15266 | on which map is being defined. There are @r{@var{uorder}×@var{vorder}} |
15267 | control points in the array. @var{ustride} specifies how many float or | |
3c9b6116 AW |
15268 | double locations are skipped to advance the internal memory pointer from |
15269 | control point @r{@var{R}_@var{i}@var{j},} to control point | |
c7b31271 | 15270 | @r{@var{R}_(@var{i}+1,)@var{j},}. @var{vstride} specifies how many |
8925f36f | 15271 | float or double locations are skipped to advance the internal memory |
3c9b6116 AW |
15272 | pointer from control point @r{@var{R}_@var{i}@var{j},} to control point |
15273 | @r{@var{R}_@var{i}(@var{j}+1,),}. | |
8925f36f | 15274 | |
8925f36f AW |
15275 | @code{GL_INVALID_ENUM} is generated if @var{target} is not an accepted |
15276 | value. | |
15277 | ||
15278 | @code{GL_INVALID_VALUE} is generated if @var{u1} is equal to @var{u2}, | |
15279 | or if @var{v1} is equal to @var{v2}. | |
15280 | ||
15281 | @code{GL_INVALID_VALUE} is generated if either @var{ustride} or | |
15282 | @var{vstride} is less than the number of values in a control point. | |
15283 | ||
15284 | @code{GL_INVALID_VALUE} is generated if either @var{uorder} or | |
15285 | @var{vorder} is less than 1 or greater than the return value of | |
15286 | @code{GL_MAX_EVAL_ORDER}. | |
15287 | ||
15288 | @code{GL_INVALID_OPERATION} is generated if @code{glMap2} is executed | |
15289 | between the execution of @code{glBegin} and the corresponding execution | |
15290 | of @code{glEnd}. | |
15291 | ||
15292 | @code{GL_INVALID_OPERATION} is generated if @code{glMap2} is called and | |
15293 | the value of @code{GL_ACTIVE_TEXTURE} is not @code{GL_TEXTURE0}. | |
15294 | ||
bb894c9d | 15295 | @end deftypefun |
8925f36f | 15296 | |
00239761 | 15297 | @deftypefun void-* glMapBuffer target access |
bb894c9d | 15298 | @deftypefunx GLboolean glUnmapBuffer target |
3c9b6116 AW |
15299 | Map a buffer object's data store. |
15300 | ||
8925f36f AW |
15301 | @table @asis |
15302 | @item @var{target} | |
c7b31271 | 15303 | Specifies the target buffer object being mapped. The symbolic constant |
8925f36f AW |
15304 | must be @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, |
15305 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
15306 | ||
15307 | @item @var{access} | |
15308 | Specifies the access policy, indicating whether it will be possible to | |
15309 | read from, write to, or both read from and write to the buffer object's | |
c7b31271 | 15310 | mapped data store. The symbolic constant must be @code{GL_READ_ONLY}, |
8925f36f AW |
15311 | @code{GL_WRITE_ONLY}, or @code{GL_READ_WRITE}. |
15312 | ||
15313 | @end table | |
15314 | ||
8925f36f | 15315 | @code{glMapBuffer} maps to the client's address space the entire data |
c7b31271 DH |
15316 | store of the buffer object currently bound to @var{target}. The data |
15317 | can then be directly read and/or written relative to the returned | |
15318 | pointer, depending on the specified @var{access} policy. If the GL is | |
15319 | unable to map the buffer object's data store, @code{glMapBuffer} | |
15320 | generates an error and returns @code{NULL}. This may occur for | |
15321 | system-specific reasons, such as low virtual memory availability. | |
8925f36f AW |
15322 | |
15323 | If a mapped data store is accessed in a way inconsistent with the | |
15324 | specified @var{access} policy, no error is generated, but performance | |
15325 | may be negatively impacted and system errors, including program | |
c7b31271 | 15326 | termination, may result. Unlike the @var{usage} parameter of |
8925f36f AW |
15327 | @code{glBufferData}, @var{access} is not a hint, and does in fact |
15328 | constrain the usage of the mapped data store on some GL implementations. | |
15329 | In order to achieve the highest performance available, a buffer object's | |
15330 | data store should be used in ways consistent with both its specified | |
15331 | @var{usage} and @var{access} parameters. | |
15332 | ||
15333 | A mapped data store must be unmapped with @code{glUnmapBuffer} before | |
c7b31271 | 15334 | its buffer object is used. Otherwise an error will be generated by any |
8925f36f AW |
15335 | GL command that attempts to dereference the buffer object's data store. |
15336 | When a data store is unmapped, the pointer to its data store becomes | |
c7b31271 | 15337 | invalid. @code{glUnmapBuffer} returns @code{GL_TRUE} unless the data |
8925f36f | 15338 | store contents have become corrupt during the time the data store was |
c7b31271 DH |
15339 | mapped. This can occur for system-specific reasons that affect the |
15340 | availability of graphics memory, such as screen mode changes. In such | |
8925f36f | 15341 | situations, @code{GL_FALSE} is returned and the data store contents are |
c7b31271 | 15342 | undefined. An application must detect this rare condition and |
8925f36f AW |
15343 | reinitialize the data store. |
15344 | ||
15345 | A buffer object's mapped data store is automatically unmapped when the | |
15346 | buffer object is deleted or its data store is recreated with | |
15347 | @code{glBufferData}. | |
15348 | ||
8925f36f AW |
15349 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
15350 | @code{GL_ARRAY_BUFFER}, @code{GL_ELEMENT_ARRAY_BUFFER}, | |
15351 | @code{GL_PIXEL_PACK_BUFFER}, or @code{GL_PIXEL_UNPACK_BUFFER}. | |
15352 | ||
15353 | @code{GL_INVALID_ENUM} is generated if @var{access} is not | |
15354 | @code{GL_READ_ONLY}, @code{GL_WRITE_ONLY}, or @code{GL_READ_WRITE}. | |
15355 | ||
15356 | @code{GL_OUT_OF_MEMORY} is generated when @code{glMapBuffer} is executed | |
c7b31271 | 15357 | if the GL is unable to map the buffer object's data store. This may |
8925f36f AW |
15358 | occur for a variety of system-specific reasons, such as the absence of |
15359 | sufficient remaining virtual memory. | |
15360 | ||
15361 | @code{GL_INVALID_OPERATION} is generated if the reserved buffer object | |
15362 | name 0 is bound to @var{target}. | |
15363 | ||
15364 | @code{GL_INVALID_OPERATION} is generated if @code{glMapBuffer} is | |
15365 | executed for a buffer object whose data store is already mapped. | |
15366 | ||
15367 | @code{GL_INVALID_OPERATION} is generated if @code{glUnmapBuffer} is | |
15368 | executed for a buffer object whose data store is not currently mapped. | |
15369 | ||
15370 | @code{GL_INVALID_OPERATION} is generated if @code{glMapBuffer} or | |
15371 | @code{glUnmapBuffer} is executed between the execution of @code{glBegin} | |
15372 | and the corresponding execution of @code{glEnd}. | |
15373 | ||
bb894c9d | 15374 | @end deftypefun |
8925f36f | 15375 | |
d172eed9 AW |
15376 | @deftypefun void glMapGrid1d un u1 u2 |
15377 | @deftypefunx void glMapGrid1f un u1 u2 | |
15378 | @deftypefunx void glMapGrid2d un u1 u2 vn v1 v2 | |
ca09631c | 15379 | @deftypefunx void glMapGrid2f un u1 u2 vn v1 v2 |
3c9b6116 AW |
15380 | Define a one- or two-dimensional mesh. |
15381 | ||
8925f36f AW |
15382 | @table @asis |
15383 | @item @var{un} | |
15384 | Specifies the number of partitions in the grid range interval [@var{u1}, | |
c7b31271 | 15385 | @var{u2}]. Must be positive. |
8925f36f AW |
15386 | |
15387 | @item @var{u1} | |
15388 | @itemx @var{u2} | |
3c9b6116 AW |
15389 | Specify the mappings for integer grid domain values @r{@var{i}=0} and |
15390 | @r{@var{i}=@var{un}}. | |
8925f36f AW |
15391 | |
15392 | @item @var{vn} | |
15393 | Specifies the number of partitions in the grid range interval [@var{v1}, | |
15394 | @var{v2}] (@code{glMapGrid2} only). | |
15395 | ||
15396 | @item @var{v1} | |
15397 | @itemx @var{v2} | |
3c9b6116 AW |
15398 | Specify the mappings for integer grid domain values @r{@var{j}=0} and |
15399 | @r{@var{j}=@var{vn}} (@code{glMapGrid2} only). | |
8925f36f AW |
15400 | |
15401 | @end table | |
15402 | ||
8925f36f AW |
15403 | @code{glMapGrid} and @code{glEvalMesh} are used together to efficiently |
15404 | generate and evaluate a series of evenly-spaced map domain values. | |
15405 | @code{glEvalMesh} steps through the integer domain of a one- or | |
15406 | two-dimensional grid, whose range is the domain of the evaluation maps | |
15407 | specified by @code{glMap1} and @code{glMap2}. | |
15408 | ||
15409 | @code{glMapGrid1} and @code{glMapGrid2} specify the linear grid mappings | |
3c9b6116 AW |
15410 | between the @r{@var{i}} (or @r{@var{i}} and @r{@var{j}}) integer grid |
15411 | coordinates, to the @r{@var{u}} (or @r{@var{u}} and @r{@var{v}}) | |
c7b31271 | 15412 | floating-point evaluation map coordinates. See @code{glMap1} and |
3c9b6116 AW |
15413 | @code{glMap2} for details of how @r{@var{u}} and @r{@var{v}} coordinates |
15414 | are evaluated. | |
8925f36f AW |
15415 | |
15416 | @code{glMapGrid1} specifies a single linear mapping such that integer | |
15417 | grid coordinate 0 maps exactly to @var{u1}, and integer grid coordinate | |
c7b31271 | 15418 | @var{un} maps exactly to @var{u2}. All other integer grid coordinates |
3c9b6116 | 15419 | @r{@var{i}} are mapped so that |
8925f36f | 15420 | |
3c9b6116 | 15421 | @r{@var{u}=@var{i}(@var{u2}-@var{u1},)/@var{un}+@var{u1}} |
8925f36f | 15422 | |
c7b31271 | 15423 | @code{glMapGrid2} specifies two such linear mappings. One maps integer |
3c9b6116 | 15424 | grid coordinate @r{@var{i}=0} exactly to @var{u1}, and integer grid |
c7b31271 | 15425 | coordinate @r{@var{i}=@var{un}} exactly to @var{u2}. The other maps |
3c9b6116 | 15426 | integer grid coordinate @r{@var{j}=0} exactly to @var{v1}, and integer |
c7b31271 | 15427 | grid coordinate @r{@var{j}=@var{vn}} exactly to @var{v2}. Other integer |
3c9b6116 | 15428 | grid coordinates @r{@var{i}} and @r{@var{j}} are mapped such that |
8925f36f | 15429 | |
3c9b6116 | 15430 | @r{@var{u}=@var{i}(@var{u2}-@var{u1},)/@var{un}+@var{u1}} |
8925f36f | 15431 | |
3c9b6116 | 15432 | @r{@var{v}=@var{j}(@var{v2}-@var{v1},)/@var{vn}+@var{v1}} |
8925f36f AW |
15433 | |
15434 | The mappings specified by @code{glMapGrid} are used identically by | |
15435 | @code{glEvalMesh} and @code{glEvalPoint}. | |
15436 | ||
8925f36f AW |
15437 | @code{GL_INVALID_VALUE} is generated if either @var{un} or @var{vn} is |
15438 | not positive. | |
15439 | ||
15440 | @code{GL_INVALID_OPERATION} is generated if @code{glMapGrid} is executed | |
15441 | between the execution of @code{glBegin} and the corresponding execution | |
15442 | of @code{glEnd}. | |
15443 | ||
bb894c9d | 15444 | @end deftypefun |
8925f36f | 15445 | |
bb894c9d AW |
15446 | @deftypefun void glMaterialf face pname param |
15447 | @deftypefunx void glMateriali face pname param | |
d172eed9 AW |
15448 | @deftypefunx void glMaterialfv face pname params |
15449 | @deftypefunx void glMaterialiv face pname params | |
3c9b6116 AW |
15450 | Specify material parameters for the lighting model. |
15451 | ||
8925f36f AW |
15452 | @table @asis |
15453 | @item @var{face} | |
c7b31271 | 15454 | Specifies which face or faces are being updated. Must be one of |
8925f36f AW |
15455 | @code{GL_FRONT}, @code{GL_BACK}, or @code{GL_FRONT_AND_BACK}. |
15456 | ||
15457 | @item @var{pname} | |
15458 | Specifies the single-valued material parameter of the face or faces that | |
c7b31271 | 15459 | is being updated. Must be @code{GL_SHININESS}. |
8925f36f AW |
15460 | |
15461 | @item @var{param} | |
15462 | Specifies the value that parameter @code{GL_SHININESS} will be set to. | |
15463 | ||
15464 | @end table | |
15465 | ||
c7b31271 DH |
15466 | @code{glMaterial} assigns values to material parameters. There are two |
15467 | matched sets of material parameters. One, the @var{front-facing} set, | |
15468 | is used to shade points, lines, bitmaps, and all polygons (when | |
15469 | two-sided lighting is disabled), or just front-facing polygons (when | |
15470 | two-sided lighting is enabled). The other set, @var{back-facing}, is | |
15471 | used to shade back-facing polygons only when two-sided lighting is | |
15472 | enabled. Refer to the @code{glLightModel} reference page for details | |
15473 | concerning one- and two-sided lighting calculations. | |
8925f36f | 15474 | |
c7b31271 | 15475 | @code{glMaterial} takes three arguments. The first, @var{face}, |
8925f36f AW |
15476 | specifies whether the @code{GL_FRONT} materials, the @code{GL_BACK} |
15477 | materials, or both @code{GL_FRONT_AND_BACK} materials will be modified. | |
15478 | The second, @var{pname}, specifies which of several parameters in one or | |
c7b31271 | 15479 | both sets will be modified. The third, @var{params}, specifies what |
8925f36f AW |
15480 | value or values will be assigned to the specified parameter. |
15481 | ||
15482 | Material parameters are used in the lighting equation that is optionally | |
c7b31271 DH |
15483 | applied to each vertex. The equation is discussed in the |
15484 | @code{glLightModel} reference page. The parameters that can be | |
15485 | specified using @code{glMaterial}, and their interpretations by the | |
15486 | lighting equation, are as follows: | |
8925f36f AW |
15487 | |
15488 | @table @asis | |
15489 | @item @code{GL_AMBIENT} | |
15490 | @var{params} contains four integer or floating-point values that specify | |
c7b31271 | 15491 | the ambient RGBA reflectance of the material. Integer values are mapped |
8925f36f | 15492 | linearly such that the most positive representable value maps to 1.0, |
3c9b6116 | 15493 | and the most negative representable value maps to @r{-1.0}. |
c7b31271 DH |
15494 | Floating-point values are mapped directly. Neither integer nor |
15495 | floating-point values are clamped. The initial ambient reflectance for | |
8925f36f AW |
15496 | both front- and back-facing materials is (0.2, 0.2, 0.2, 1.0). |
15497 | ||
15498 | @item @code{GL_DIFFUSE} | |
15499 | @var{params} contains four integer or floating-point values that specify | |
c7b31271 | 15500 | the diffuse RGBA reflectance of the material. Integer values are mapped |
8925f36f | 15501 | linearly such that the most positive representable value maps to 1.0, |
3c9b6116 | 15502 | and the most negative representable value maps to @r{-1.0}. |
c7b31271 DH |
15503 | Floating-point values are mapped directly. Neither integer nor |
15504 | floating-point values are clamped. The initial diffuse reflectance for | |
8925f36f AW |
15505 | both front- and back-facing materials is (0.8, 0.8, 0.8, 1.0). |
15506 | ||
15507 | @item @code{GL_SPECULAR} | |
15508 | @var{params} contains four integer or floating-point values that specify | |
c7b31271 DH |
15509 | the specular RGBA reflectance of the material. Integer values are |
15510 | mapped linearly such that the most positive representable value maps to | |
15511 | 1.0, and the most negative representable value maps to @r{-1.0}. | |
15512 | Floating-point values are mapped directly. Neither integer nor | |
15513 | floating-point values are clamped. The initial specular reflectance for | |
8925f36f AW |
15514 | both front- and back-facing materials is (0, 0, 0, 1). |
15515 | ||
15516 | @item @code{GL_EMISSION} | |
15517 | @var{params} contains four integer or floating-point values that specify | |
c7b31271 | 15518 | the RGBA emitted light intensity of the material. Integer values are |
8925f36f | 15519 | mapped linearly such that the most positive representable value maps to |
3c9b6116 | 15520 | 1.0, and the most negative representable value maps to @r{-1.0}. |
c7b31271 DH |
15521 | Floating-point values are mapped directly. Neither integer nor |
15522 | floating-point values are clamped. The initial emission intensity for | |
8925f36f AW |
15523 | both front- and back-facing materials is (0, 0, 0, 1). |
15524 | ||
15525 | @item @code{GL_SHININESS} | |
15526 | @var{params} is a single integer or floating-point value that specifies | |
c7b31271 DH |
15527 | the RGBA specular exponent of the material. Integer and floating-point |
15528 | values are mapped directly. Only values in the range @r{[0,128]} are | |
15529 | accepted. The initial specular exponent for both front- and back-facing | |
8925f36f AW |
15530 | materials is 0. |
15531 | ||
15532 | @item @code{GL_AMBIENT_AND_DIFFUSE} | |
15533 | Equivalent to calling @code{glMaterial} twice with the same parameter | |
15534 | values, once with @code{GL_AMBIENT} and once with @code{GL_DIFFUSE}. | |
15535 | ||
15536 | @item @code{GL_COLOR_INDEXES} | |
15537 | @var{params} contains three integer or floating-point values specifying | |
c7b31271 | 15538 | the color indices for ambient, diffuse, and specular lighting. These |
8925f36f | 15539 | three values, and @code{GL_SHININESS}, are the only material values used |
c7b31271 | 15540 | by the color index mode lighting equation. Refer to the |
8925f36f AW |
15541 | @code{glLightModel} reference page for a discussion of color index |
15542 | lighting. | |
15543 | ||
15544 | @end table | |
15545 | ||
8925f36f AW |
15546 | @code{GL_INVALID_ENUM} is generated if either @var{face} or @var{pname} |
15547 | is not an accepted value. | |
15548 | ||
15549 | @code{GL_INVALID_VALUE} is generated if a specular exponent outside the | |
3c9b6116 | 15550 | range @r{[0,128]} is specified. |
8925f36f | 15551 | |
bb894c9d | 15552 | @end deftypefun |
8925f36f | 15553 | |
bb894c9d | 15554 | @deftypefun void glMatrixMode mode |
3c9b6116 AW |
15555 | Specify which matrix is the current matrix. |
15556 | ||
8925f36f AW |
15557 | @table @asis |
15558 | @item @var{mode} | |
15559 | Specifies which matrix stack is the target for subsequent matrix | |
c7b31271 DH |
15560 | operations. Three values are accepted: @code{GL_MODELVIEW}, |
15561 | @code{GL_PROJECTION}, and @code{GL_TEXTURE}. The initial value is | |
15562 | @code{GL_MODELVIEW}. Additionally, if the @code{ARB_imaging} extension | |
8925f36f AW |
15563 | is supported, @code{GL_COLOR} is also accepted. |
15564 | ||
15565 | @end table | |
15566 | ||
c7b31271 | 15567 | @code{glMatrixMode} sets the current matrix mode. @var{mode} can assume |
8925f36f AW |
15568 | one of four values: |
15569 | ||
15570 | @table @asis | |
15571 | @item @code{GL_MODELVIEW} | |
15572 | Applies subsequent matrix operations to the modelview matrix stack. | |
15573 | ||
15574 | @item @code{GL_PROJECTION} | |
15575 | Applies subsequent matrix operations to the projection matrix stack. | |
15576 | ||
15577 | @item @code{GL_TEXTURE} | |
15578 | Applies subsequent matrix operations to the texture matrix stack. | |
15579 | ||
15580 | @item @code{GL_COLOR} | |
15581 | Applies subsequent matrix operations to the color matrix stack. | |
15582 | ||
15583 | @end table | |
15584 | ||
15585 | To find out which matrix stack is currently the target of all matrix | |
c7b31271 | 15586 | operations, call @code{glGet} with argument @code{GL_MATRIX_MODE}. The |
8925f36f AW |
15587 | initial value is @code{GL_MODELVIEW}. |
15588 | ||
8925f36f AW |
15589 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
15590 | value. | |
15591 | ||
15592 | @code{GL_INVALID_OPERATION} is generated if @code{glMatrixMode} is | |
15593 | executed between the execution of @code{glBegin} and the corresponding | |
15594 | execution of @code{glEnd}. | |
15595 | ||
bb894c9d | 15596 | @end deftypefun |
8925f36f | 15597 | |
bb894c9d | 15598 | @deftypefun void glMinmax target internalformat sink |
3c9b6116 AW |
15599 | Define minmax table. |
15600 | ||
8925f36f AW |
15601 | @table @asis |
15602 | @item @var{target} | |
c7b31271 | 15603 | The minmax table whose parameters are to be set. Must be |
8925f36f AW |
15604 | @code{GL_MINMAX}. |
15605 | ||
15606 | @item @var{internalformat} | |
c7b31271 | 15607 | The format of entries in the minmax table. Must be one of |
8925f36f AW |
15608 | @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, |
15609 | @code{GL_ALPHA16}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
15610 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
15611 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
15612 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
15613 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
15614 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
15615 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
15616 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
15617 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
15618 | @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
15619 | ||
15620 | @item @var{sink} | |
15621 | If @code{GL_TRUE}, pixels will be consumed by the minmax process and no | |
c7b31271 | 15622 | drawing or texture loading will take place. If @code{GL_FALSE}, pixels |
8925f36f AW |
15623 | will proceed to the final conversion process after minmax. |
15624 | ||
15625 | @end table | |
15626 | ||
8925f36f AW |
15627 | When @code{GL_MINMAX} is enabled, the RGBA components of incoming pixels |
15628 | are compared to the minimum and maximum values for each component, which | |
c7b31271 | 15629 | are stored in the two-element minmax table. (The first element stores |
8925f36f AW |
15630 | the minima, and the second element stores the maxima.) If a pixel |
15631 | component is greater than the corresponding component in the maximum | |
15632 | element, then the maximum element is updated with the pixel component | |
c7b31271 | 15633 | value. If a pixel component is less than the corresponding component in |
8925f36f | 15634 | the minimum element, then the minimum element is updated with the pixel |
c7b31271 | 15635 | component value. (In both cases, if the internal format of the minmax |
8925f36f AW |
15636 | table includes luminance, then the R color component of incoming pixels |
15637 | is used for comparison.) The contents of the minmax table may be | |
c7b31271 | 15638 | retrieved at a later time by calling @code{glGetMinmax}. The minmax |
8925f36f AW |
15639 | operation is enabled or disabled by calling @code{glEnable} or |
15640 | @code{glDisable}, respectively, with an argument of @code{GL_MINMAX}. | |
15641 | ||
15642 | @code{glMinmax} redefines the current minmax table to have entries of | |
c7b31271 | 15643 | the format specified by @var{internalformat}. The maximum element is |
8925f36f | 15644 | initialized with the smallest possible component values, and the minimum |
c7b31271 DH |
15645 | element is initialized with the largest possible component values. The |
15646 | values in the previous minmax table, if any, are lost. If @var{sink} is | |
8925f36f AW |
15647 | @code{GL_TRUE}, then pixels are discarded after minmax; no further |
15648 | processing of the pixels takes place, and no drawing, texture loading, | |
15649 | or pixel readback will result. | |
15650 | ||
15651 | ||
15652 | ||
8925f36f AW |
15653 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
15654 | allowable values. | |
15655 | ||
15656 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
15657 | of the allowable values. | |
15658 | ||
15659 | @code{GL_INVALID_OPERATION} is generated if @code{glMinmax} is executed | |
15660 | between the execution of @code{glBegin} and the corresponding execution | |
15661 | of @code{glEnd}. | |
15662 | ||
bb894c9d | 15663 | @end deftypefun |
8925f36f | 15664 | |
bb894c9d | 15665 | @deftypefun void glMultiDrawArrays mode first count primcount |
3c9b6116 AW |
15666 | Render multiple sets of primitives from array data. |
15667 | ||
8925f36f AW |
15668 | @table @asis |
15669 | @item @var{mode} | |
c7b31271 | 15670 | Specifies what kind of primitives to render. Symbolic constants |
8925f36f AW |
15671 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, |
15672 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
15673 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
15674 | @code{GL_POLYGON} are accepted. | |
15675 | ||
15676 | @item @var{first} | |
15677 | Points to an array of starting indices in the enabled arrays. | |
15678 | ||
15679 | @item @var{count} | |
15680 | Points to an array of the number of indices to be rendered. | |
15681 | ||
15682 | @item @var{primcount} | |
15683 | Specifies the size of the first and count | |
15684 | ||
15685 | @end table | |
15686 | ||
8925f36f | 15687 | @code{glMultiDrawArrays} specifies multiple sets of geometric primitives |
c7b31271 | 15688 | with very few subroutine calls. Instead of calling a GL procedure to |
8925f36f AW |
15689 | pass each individual vertex, normal, texture coordinate, edge flag, or |
15690 | color, you can prespecify separate arrays of vertices, normals, and | |
15691 | colors and use them to construct a sequence of primitives with a single | |
15692 | call to @code{glMultiDrawArrays}. | |
15693 | ||
15694 | @code{glMultiDrawArrays} behaves identically to @code{glDrawArrays} | |
15695 | except that @var{primcount} separate ranges of elements are specified | |
15696 | instead. | |
15697 | ||
15698 | When @code{glMultiDrawArrays} is called, it uses @var{count} sequential | |
15699 | elements from each enabled array to construct a sequence of geometric | |
c7b31271 | 15700 | primitives, beginning with element @var{first}. @var{mode} specifies |
8925f36f | 15701 | what kind of primitives are constructed, and how the array elements |
c7b31271 DH |
15702 | construct those primitives. If @code{GL_VERTEX_ARRAY} is not enabled, |
15703 | no geometric primitives are generated. | |
8925f36f AW |
15704 | |
15705 | Vertex attributes that are modified by @code{glMultiDrawArrays} have an | |
c7b31271 | 15706 | unspecified value after @code{glMultiDrawArrays} returns. For example, |
8925f36f | 15707 | if @code{GL_COLOR_ARRAY} is enabled, the value of the current color is |
c7b31271 | 15708 | undefined after @code{glMultiDrawArrays} executes. Attributes that |
8925f36f AW |
15709 | aren't modified remain well defined. |
15710 | ||
8925f36f AW |
15711 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
15712 | value. | |
15713 | ||
15714 | @code{GL_INVALID_VALUE} is generated if @var{primcount} is negative. | |
15715 | ||
15716 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
15717 | name is bound to an enabled array and the buffer object's data store is | |
15718 | currently mapped. | |
15719 | ||
15720 | @code{GL_INVALID_OPERATION} is generated if @code{glMultiDrawArrays} is | |
15721 | executed between the execution of @code{glBegin} and the corresponding | |
15722 | @code{glEnd}. | |
15723 | ||
bb894c9d | 15724 | @end deftypefun |
8925f36f | 15725 | |
bb894c9d | 15726 | @deftypefun void glMultiDrawElements mode count type indices primcount |
3c9b6116 AW |
15727 | Render multiple sets of primitives by specifying indices of array data |
15728 | elements. | |
15729 | ||
8925f36f AW |
15730 | @table @asis |
15731 | @item @var{mode} | |
c7b31271 | 15732 | Specifies what kind of primitives to render. Symbolic constants |
8925f36f AW |
15733 | @code{GL_POINTS}, @code{GL_LINE_STRIP}, @code{GL_LINE_LOOP}, |
15734 | @code{GL_LINES}, @code{GL_TRIANGLE_STRIP}, @code{GL_TRIANGLE_FAN}, | |
15735 | @code{GL_TRIANGLES}, @code{GL_QUAD_STRIP}, @code{GL_QUADS}, and | |
15736 | @code{GL_POLYGON} are accepted. | |
15737 | ||
15738 | @item @var{count} | |
15739 | Points to an array of the elements counts. | |
15740 | ||
15741 | @item @var{type} | |
c7b31271 | 15742 | Specifies the type of the values in @var{indices}. Must be one of |
8925f36f AW |
15743 | @code{GL_UNSIGNED_BYTE}, @code{GL_UNSIGNED_SHORT}, or |
15744 | @code{GL_UNSIGNED_INT}. | |
15745 | ||
15746 | @item @var{indices} | |
15747 | Specifies a pointer to the location where the indices are stored. | |
15748 | ||
15749 | @item @var{primcount} | |
15750 | Specifies the size of the @var{count} array. | |
15751 | ||
15752 | @end table | |
15753 | ||
8925f36f | 15754 | @code{glMultiDrawElements} specifies multiple sets of geometric |
c7b31271 | 15755 | primitives with very few subroutine calls. Instead of calling a GL |
8925f36f AW |
15756 | function to pass each individual vertex, normal, texture coordinate, |
15757 | edge flag, or color, you can prespecify separate arrays of vertices, | |
15758 | normals, and so on, and use them to construct a sequence of primitives | |
15759 | with a single call to @code{glMultiDrawElements}. | |
15760 | ||
15761 | @code{glMultiDrawElements} is identical in operation to | |
15762 | @code{glDrawElements} except that @var{primcount} separate lists of | |
15763 | elements are specified. | |
15764 | ||
15765 | Vertex attributes that are modified by @code{glMultiDrawElements} have | |
c7b31271 | 15766 | an unspecified value after @code{glMultiDrawElements} returns. For |
8925f36f | 15767 | example, if @code{GL_COLOR_ARRAY} is enabled, the value of the current |
c7b31271 | 15768 | color is undefined after @code{glMultiDrawElements} executes. Attributes |
8925f36f AW |
15769 | that aren't modified maintain their previous values. |
15770 | ||
8925f36f AW |
15771 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted |
15772 | value. | |
15773 | ||
15774 | @code{GL_INVALID_VALUE} is generated if @var{primcount} is negative. | |
15775 | ||
15776 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
15777 | name is bound to an enabled array or the element array and the buffer | |
15778 | object's data store is currently mapped. | |
15779 | ||
15780 | @code{GL_INVALID_OPERATION} is generated if @code{glMultiDrawElements} | |
15781 | is executed between the execution of @code{glBegin} and the | |
15782 | corresponding @code{glEnd}. | |
15783 | ||
bb894c9d | 15784 | @end deftypefun |
8925f36f | 15785 | |
d172eed9 AW |
15786 | @deftypefun void glMultiTexCoord1s target s |
15787 | @deftypefunx void glMultiTexCoord1i target s | |
ca09631c | 15788 | @deftypefunx void glMultiTexCoord1f target s |
d172eed9 AW |
15789 | @deftypefunx void glMultiTexCoord1d target s |
15790 | @deftypefunx void glMultiTexCoord2s target s t | |
bb894c9d | 15791 | @deftypefunx void glMultiTexCoord2i target s t |
ca09631c | 15792 | @deftypefunx void glMultiTexCoord2f target s t |
d172eed9 AW |
15793 | @deftypefunx void glMultiTexCoord2d target s t |
15794 | @deftypefunx void glMultiTexCoord3s target s t r | |
bb894c9d | 15795 | @deftypefunx void glMultiTexCoord3i target s t r |
ca09631c | 15796 | @deftypefunx void glMultiTexCoord3f target s t r |
d172eed9 AW |
15797 | @deftypefunx void glMultiTexCoord3d target s t r |
15798 | @deftypefunx void glMultiTexCoord4s target s t r q | |
bb894c9d | 15799 | @deftypefunx void glMultiTexCoord4i target s t r q |
ca09631c | 15800 | @deftypefunx void glMultiTexCoord4f target s t r q |
d172eed9 AW |
15801 | @deftypefunx void glMultiTexCoord4d target s t r q |
15802 | @deftypefunx void glMultiTexCoord1sv target v | |
15803 | @deftypefunx void glMultiTexCoord1iv target v | |
15804 | @deftypefunx void glMultiTexCoord1fv target v | |
15805 | @deftypefunx void glMultiTexCoord1dv target v | |
15806 | @deftypefunx void glMultiTexCoord2sv target v | |
15807 | @deftypefunx void glMultiTexCoord2iv target v | |
15808 | @deftypefunx void glMultiTexCoord2fv target v | |
15809 | @deftypefunx void glMultiTexCoord2dv target v | |
15810 | @deftypefunx void glMultiTexCoord3sv target v | |
15811 | @deftypefunx void glMultiTexCoord3iv target v | |
15812 | @deftypefunx void glMultiTexCoord3fv target v | |
15813 | @deftypefunx void glMultiTexCoord3dv target v | |
15814 | @deftypefunx void glMultiTexCoord4sv target v | |
15815 | @deftypefunx void glMultiTexCoord4iv target v | |
15816 | @deftypefunx void glMultiTexCoord4fv target v | |
15817 | @deftypefunx void glMultiTexCoord4dv target v | |
3c9b6116 AW |
15818 | Set the current texture coordinates. |
15819 | ||
8925f36f AW |
15820 | @table @asis |
15821 | @item @var{target} | |
c7b31271 | 15822 | Specifies the texture unit whose coordinates should be modified. The |
8925f36f | 15823 | number of texture units is implementation dependent, but must be at |
c7b31271 | 15824 | least two. Symbolic constant must be one of |
3c9b6116 | 15825 | @code{GL_TEXTURE}@r{@var{i}}, where i ranges from 0 to |
8925f36f AW |
15826 | @code{GL_MAX_TEXTURE_COORDS} - 1, which is an implementation-dependent |
15827 | value. | |
15828 | ||
15829 | @item @var{s} | |
15830 | @itemx @var{t} | |
15831 | @itemx @var{r} | |
15832 | @itemx @var{q} | |
15833 | Specify @var{s}, @var{t}, @var{r}, and @var{q} texture coordinates for | |
c7b31271 | 15834 | @var{target} texture unit. Not all parameters are present in all forms |
8925f36f AW |
15835 | of the command. |
15836 | ||
15837 | @end table | |
15838 | ||
8925f36f | 15839 | @code{glMultiTexCoord} specifies texture coordinates in one, two, three, |
c7b31271 | 15840 | or four dimensions. @code{glMultiTexCoord1} sets the current texture |
3c9b6116 | 15841 | coordinates to @r{(@var{s},001)}; a call to @code{glMultiTexCoord2} sets |
c7b31271 | 15842 | them to @r{(@var{s},@var{t}01)}. Similarly, @code{glMultiTexCoord3} |
3c9b6116 AW |
15843 | specifies the texture coordinates as @r{(@var{s},@var{t}@var{r}1)}, and |
15844 | @code{glMultiTexCoord4} defines all four components explicitly as | |
15845 | @r{(@var{s},@var{t}@var{r}@var{q})}. | |
8925f36f AW |
15846 | |
15847 | The current texture coordinates are part of the data that is associated | |
c7b31271 | 15848 | with each vertex and with the current raster position. Initially, the |
3c9b6116 | 15849 | values for @r{(@var{s},@var{t}@var{r}@var{q})} are @r{(0,001)}. |
8925f36f AW |
15850 | |
15851 | ||
15852 | ||
bb894c9d | 15853 | @end deftypefun |
8925f36f | 15854 | |
d172eed9 AW |
15855 | @deftypefun void glMultMatrixd m |
15856 | @deftypefunx void glMultMatrixf m | |
3c9b6116 AW |
15857 | Multiply the current matrix with the specified matrix. |
15858 | ||
8925f36f AW |
15859 | @table @asis |
15860 | @item @var{m} | |
15861 | Points to 16 consecutive values that are used as the elements of a | |
3c9b6116 | 15862 | @r{4×4} column-major matrix. |
8925f36f AW |
15863 | |
15864 | @end table | |
15865 | ||
8925f36f AW |
15866 | @code{glMultMatrix} multiplies the current matrix with the one specified |
15867 | using @var{m}, and replaces the current matrix with the product. | |
15868 | ||
15869 | The current matrix is determined by the current matrix mode (see | |
c7b31271 | 15870 | @code{glMatrixMode}). It is either the projection matrix, modelview |
8925f36f AW |
15871 | matrix, or the texture matrix. |
15872 | ||
8925f36f AW |
15873 | @code{GL_INVALID_OPERATION} is generated if @code{glMultMatrix} is |
15874 | executed between the execution of @code{glBegin} and the corresponding | |
15875 | execution of @code{glEnd}. | |
15876 | ||
bb894c9d | 15877 | @end deftypefun |
8925f36f | 15878 | |
d172eed9 AW |
15879 | @deftypefun void glMultTransposeMatrixd m |
15880 | @deftypefunx void glMultTransposeMatrixf m | |
3c9b6116 AW |
15881 | Multiply the current matrix with the specified row-major ordered matrix. |
15882 | ||
8925f36f AW |
15883 | @table @asis |
15884 | @item @var{m} | |
15885 | Points to 16 consecutive values that are used as the elements of a | |
3c9b6116 | 15886 | @r{4×4} row-major matrix. |
8925f36f AW |
15887 | |
15888 | @end table | |
15889 | ||
8925f36f AW |
15890 | @code{glMultTransposeMatrix} multiplies the current matrix with the one |
15891 | specified using @var{m}, and replaces the current matrix with the | |
15892 | product. | |
15893 | ||
15894 | The current matrix is determined by the current matrix mode (see | |
c7b31271 | 15895 | @code{glMatrixMode}). It is either the projection matrix, modelview |
8925f36f AW |
15896 | matrix, or the texture matrix. |
15897 | ||
8925f36f AW |
15898 | @code{GL_INVALID_OPERATION} is generated if @code{glMultTransposeMatrix} |
15899 | is executed between the execution of @code{glBegin} and the | |
15900 | corresponding execution of @code{glEnd}. | |
15901 | ||
bb894c9d | 15902 | @end deftypefun |
8925f36f | 15903 | |
bb894c9d AW |
15904 | @deftypefun void glNewList list mode |
15905 | @deftypefunx void glEndList | |
3c9b6116 AW |
15906 | Create or replace a display list. |
15907 | ||
8925f36f AW |
15908 | @table @asis |
15909 | @item @var{list} | |
15910 | Specifies the display-list name. | |
15911 | ||
15912 | @item @var{mode} | |
15913 | Specifies the compilation mode, which can be @code{GL_COMPILE} or | |
15914 | @code{GL_COMPILE_AND_EXECUTE}. | |
15915 | ||
15916 | @end table | |
15917 | ||
8925f36f | 15918 | Display lists are groups of GL commands that have been stored for |
c7b31271 | 15919 | subsequent execution. Display lists are created with @code{glNewList}. |
8925f36f AW |
15920 | All subsequent commands are placed in the display list, in the order |
15921 | issued, until @code{glEndList} is called. | |
15922 | ||
c7b31271 DH |
15923 | @code{glNewList} has two arguments. The first argument, @var{list}, is |
15924 | a positive integer that becomes the unique name for the display list. | |
8925f36f | 15925 | Names can be created and reserved with @code{glGenLists} and tested for |
c7b31271 | 15926 | uniqueness with @code{glIsList}. The second argument, @var{mode}, is a |
8925f36f AW |
15927 | symbolic constant that can assume one of two values: |
15928 | ||
15929 | @table @asis | |
15930 | @item @code{GL_COMPILE} | |
15931 | Commands are merely compiled. | |
15932 | ||
15933 | @item @code{GL_COMPILE_AND_EXECUTE} | |
15934 | Commands are executed as they are compiled into the display list. | |
15935 | ||
15936 | @end table | |
15937 | ||
15938 | Certain commands are not compiled into the display list but are executed | |
c7b31271 | 15939 | immediately, regardless of the display-list mode. These commands are |
8925f36f AW |
15940 | @code{glAreTexturesResident}, @code{glColorPointer}, |
15941 | @code{glDeleteLists}, @code{glDeleteTextures}, | |
15942 | @code{glDisableClientState}, @code{glEdgeFlagPointer}, | |
15943 | @code{glEnableClientState}, @code{glFeedbackBuffer}, @code{glFinish}, | |
15944 | @code{glFlush}, @code{glGenLists}, @code{glGenTextures}, | |
15945 | @code{glIndexPointer}, @code{glInterleavedArrays}, @code{glIsEnabled}, | |
15946 | @code{glIsList}, @code{glIsTexture}, @code{glNormalPointer}, | |
15947 | @code{glPopClientAttrib}, @code{glPixelStore}, | |
15948 | @code{glPushClientAttrib}, @code{glReadPixels}, @code{glRenderMode}, | |
15949 | @code{glSelectBuffer}, @code{glTexCoordPointer}, @code{glVertexPointer}, | |
15950 | and all of the @code{glGet} commands. | |
15951 | ||
15952 | Similarly, @code{glTexImage1D}, @code{glTexImage2D}, and | |
15953 | @code{glTexImage3D} are executed immediately and not compiled into the | |
15954 | display list when their first argument is @code{GL_PROXY_TEXTURE_1D}, | |
15955 | @code{GL_PROXY_TEXTURE_1D}, or @code{GL_PROXY_TEXTURE_3D}, respectively. | |
15956 | ||
15957 | When the @code{ARB_imaging} extension is supported, @code{glHistogram} | |
15958 | executes immediately when its argument is @code{GL_PROXY_HISTOGRAM}. | |
15959 | Similarly, @code{glColorTable} executes immediately when its first | |
15960 | argument is @code{GL_PROXY_COLOR_TABLE}, | |
15961 | @code{GL_PROXY_POST_CONVOLUTION_COLOR_TABLE}, or | |
15962 | @code{GL_PROXY_POST_COLOR_MATRIX_COLOR_TABLE}. | |
15963 | ||
15964 | For OpenGL versions 1.3 and greater, or when the @code{ARB_multitexture} | |
15965 | extension is supported, @code{glClientActiveTexture} is not compiled | |
15966 | into display lists, but executed immediately. | |
15967 | ||
15968 | When @code{glEndList} is encountered, the display-list definition is | |
15969 | completed by associating the list with the unique name @var{list} | |
c7b31271 DH |
15970 | (specified in the @code{glNewList} command). If a display list with |
15971 | name @var{list} already exists, it is replaced only when | |
15972 | @code{glEndList} is called. | |
8925f36f | 15973 | |
8925f36f AW |
15974 | @code{GL_INVALID_VALUE} is generated if @var{list} is 0. |
15975 | ||
15976 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not an accepted | |
15977 | value. | |
15978 | ||
15979 | @code{GL_INVALID_OPERATION} is generated if @code{glEndList} is called | |
15980 | without a preceding @code{glNewList}, or if @code{glNewList} is called | |
15981 | while a display list is being defined. | |
15982 | ||
15983 | @code{GL_INVALID_OPERATION} is generated if @code{glNewList} or | |
15984 | @code{glEndList} is executed between the execution of @code{glBegin} and | |
15985 | the corresponding execution of @code{glEnd}. | |
15986 | ||
15987 | @code{GL_OUT_OF_MEMORY} is generated if there is insufficient memory to | |
c7b31271 DH |
15988 | compile the display list. If the GL version is 1.1 or greater, no |
15989 | change is made to the previous contents of the display list, if any, and | |
15990 | no other change is made to the GL state. (It is as if no attempt had | |
15991 | been made to create the new display list.) | |
8925f36f | 15992 | |
bb894c9d | 15993 | @end deftypefun |
8925f36f | 15994 | |
bb894c9d | 15995 | @deftypefun void glNormalPointer type stride pointer |
3c9b6116 AW |
15996 | Define an array of normals. |
15997 | ||
8925f36f AW |
15998 | @table @asis |
15999 | @item @var{type} | |
c7b31271 | 16000 | Specifies the data type of each coordinate in the array. Symbolic |
8925f36f | 16001 | constants @code{GL_BYTE}, @code{GL_SHORT}, @code{GL_INT}, |
c7b31271 DH |
16002 | @code{GL_FLOAT}, and @code{GL_DOUBLE} are accepted. The initial value |
16003 | is @code{GL_FLOAT}. | |
8925f36f AW |
16004 | |
16005 | @item @var{stride} | |
c7b31271 DH |
16006 | Specifies the byte offset between consecutive normals. If @var{stride} |
16007 | is 0, the normals are understood to be tightly packed in the array. The | |
8925f36f AW |
16008 | initial value is 0. |
16009 | ||
16010 | @item @var{pointer} | |
16011 | Specifies a pointer to the first coordinate of the first normal in the | |
c7b31271 | 16012 | array. The initial value is 0. |
8925f36f AW |
16013 | |
16014 | @end table | |
16015 | ||
8925f36f | 16016 | @code{glNormalPointer} specifies the location and data format of an |
c7b31271 | 16017 | array of normals to use when rendering. @var{type} specifies the data |
8925f36f AW |
16018 | type of each normal coordinate, and @var{stride} specifies the byte |
16019 | stride from one normal to the next, allowing vertices and attributes to | |
16020 | be packed into a single array or stored in separate arrays. | |
16021 | (Single-array storage may be more efficient on some implementations; see | |
16022 | @code{glInterleavedArrays}.) | |
16023 | ||
16024 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
16025 | target (see @code{glBindBuffer}) while a normal array is specified, | |
16026 | @var{pointer} is treated as a byte offset into the buffer object's data | |
c7b31271 | 16027 | store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING}) |
8925f36f AW |
16028 | is saved as normal vertex array client-side state |
16029 | (@code{GL_NORMAL_ARRAY_BUFFER_BINDING}). | |
16030 | ||
16031 | When a normal array is specified, @var{type}, @var{stride}, and | |
16032 | @var{pointer} are saved as client-side state, in addition to the current | |
16033 | vertex array buffer object binding. | |
16034 | ||
16035 | To enable and disable the normal array, call @code{glEnableClientState} | |
16036 | and @code{glDisableClientState} with the argument | |
c7b31271 | 16037 | @code{GL_NORMAL_ARRAY}. If enabled, the normal array is used when |
8925f36f AW |
16038 | @code{glDrawArrays}, @code{glMultiDrawArrays}, @code{glDrawElements}, |
16039 | @code{glMultiDrawElements}, @code{glDrawRangeElements}, or | |
16040 | @code{glArrayElement} is called. | |
16041 | ||
8925f36f AW |
16042 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted |
16043 | value. | |
16044 | ||
16045 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
16046 | ||
bb894c9d | 16047 | @end deftypefun |
8925f36f | 16048 | |
d172eed9 AW |
16049 | @deftypefun void glNormal3b nx ny nz |
16050 | @deftypefunx void glNormal3d nx ny nz | |
16051 | @deftypefunx void glNormal3f nx ny nz | |
bb894c9d | 16052 | @deftypefunx void glNormal3i nx ny nz |
d172eed9 AW |
16053 | @deftypefunx void glNormal3s nx ny nz |
16054 | @deftypefunx void glNormal3bv v | |
16055 | @deftypefunx void glNormal3dv v | |
16056 | @deftypefunx void glNormal3fv v | |
16057 | @deftypefunx void glNormal3iv v | |
16058 | @deftypefunx void glNormal3sv v | |
3c9b6116 AW |
16059 | Set the current normal vector. |
16060 | ||
8925f36f AW |
16061 | @table @asis |
16062 | @item @var{nx} | |
16063 | @itemx @var{ny} | |
16064 | @itemx @var{nz} | |
3c9b6116 | 16065 | Specify the @r{@var{x}}, @r{@var{y}}, and @r{@var{z}} coordinates of the |
c7b31271 | 16066 | new current normal. The initial value of the current normal is the unit |
3c9b6116 | 16067 | vector, (0, 0, 1). |
8925f36f AW |
16068 | |
16069 | ||
16070 | ||
16071 | @end table | |
16072 | ||
8925f36f | 16073 | The current normal is set to the given coordinates whenever |
c7b31271 | 16074 | @code{glNormal} is issued. Byte, short, or integer arguments are |
8925f36f AW |
16075 | converted to floating-point format with a linear mapping that maps the |
16076 | most positive representable integer value to 1.0 and the most negative | |
3c9b6116 | 16077 | representable integer value to @r{-1.0}. |
8925f36f | 16078 | |
c7b31271 | 16079 | Normals specified with @code{glNormal} need not have unit length. If |
8925f36f | 16080 | @code{GL_NORMALIZE} is enabled, then normals of any length specified |
c7b31271 | 16081 | with @code{glNormal} are normalized after transformation. If |
8925f36f | 16082 | @code{GL_RESCALE_NORMAL} is enabled, normals are scaled by a scaling |
c7b31271 | 16083 | factor derived from the modelview matrix. @code{GL_RESCALE_NORMAL} |
8925f36f AW |
16084 | requires that the originally specified normals were of unit length, and |
16085 | that the modelview matrix contain only uniform scales for proper | |
c7b31271 | 16086 | results. To enable and disable normalization, call @code{glEnable} and |
8925f36f | 16087 | @code{glDisable} with either @code{GL_NORMALIZE} or |
c7b31271 | 16088 | @code{GL_RESCALE_NORMAL}. Normalization is initially disabled. |
8925f36f | 16089 | |
bb894c9d | 16090 | @end deftypefun |
8925f36f | 16091 | |
bb894c9d | 16092 | @deftypefun void glOrtho left right bottom top nearVal farVal |
3c9b6116 AW |
16093 | Multiply the current matrix with an orthographic matrix. |
16094 | ||
8925f36f AW |
16095 | @table @asis |
16096 | @item @var{left} | |
16097 | @itemx @var{right} | |
16098 | Specify the coordinates for the left and right vertical clipping planes. | |
16099 | ||
16100 | @item @var{bottom} | |
16101 | @itemx @var{top} | |
16102 | Specify the coordinates for the bottom and top horizontal clipping | |
16103 | planes. | |
16104 | ||
16105 | @item @var{nearVal} | |
16106 | @itemx @var{farVal} | |
16107 | Specify the distances to the nearer and farther depth clipping planes. | |
16108 | These values are negative if the plane is to be behind the viewer. | |
16109 | ||
16110 | @end table | |
16111 | ||
8925f36f | 16112 | @code{glOrtho} describes a transformation that produces a parallel |
c7b31271 | 16113 | projection. The current matrix (see @code{glMatrixMode}) is multiplied |
8925f36f AW |
16114 | by this matrix and the result replaces the current matrix, as if |
16115 | @code{glMultMatrix} were called with the following matrix as its | |
16116 | argument: | |
16117 | ||
3c9b6116 | 16118 | @r{((2/@var{right}-@var{left},, 0 0 @var{t}_@var{x},), (0 |
8925f36f AW |
16119 | 2/@var{top}-@var{bottom},, 0 @var{t}_@var{y},), (0 0 |
16120 | -2/@var{farVal}-@var{nearVal},, @var{t}_@var{z},), (0 0 0 1),)} | |
16121 | ||
16122 | where | |
3c9b6116 | 16123 | @r{@var{t}_@var{x}=-@var{right}+@var{left},/@var{right}-@var{left},,}@r{@var{t}_@var{y}=-@var{top}+@var{bottom},/@var{top}-@var{bottom},,}@r{@var{t}_@var{z}=-@var{farVal}+@var{nearVal},/@var{farVal}-@var{nearVal},,} |
8925f36f AW |
16124 | |
16125 | Typically, the matrix mode is @code{GL_PROJECTION}, and | |
3c9b6116 AW |
16126 | @r{(@var{left},@var{bottom}-@var{nearVal})} and |
16127 | @r{(@var{right},@var{top}-@var{nearVal})} specify the points on the near | |
16128 | clipping plane that are mapped to the lower left and upper right corners | |
16129 | of the window, respectively, assuming that the eye is located at (0, 0, | |
c7b31271 | 16130 | 0). @r{-@var{farVal}} specifies the location of the far clipping plane. |
3c9b6116 | 16131 | Both @var{nearVal} and @var{farVal} can be either positive or negative. |
8925f36f AW |
16132 | |
16133 | Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the | |
16134 | current matrix stack. | |
16135 | ||
8925f36f AW |
16136 | @code{GL_INVALID_VALUE} is generated if @var{left} = @var{right}, or |
16137 | @var{bottom} = @var{top}, or @var{near} = @var{far}. | |
16138 | ||
16139 | @code{GL_INVALID_OPERATION} is generated if @code{glOrtho} is executed | |
16140 | between the execution of @code{glBegin} and the corresponding execution | |
16141 | of @code{glEnd}. | |
16142 | ||
bb894c9d | 16143 | @end deftypefun |
8925f36f | 16144 | |
bb894c9d | 16145 | @deftypefun void glPassThrough token |
3c9b6116 AW |
16146 | Place a marker in the feedback buffer. |
16147 | ||
8925f36f AW |
16148 | @table @asis |
16149 | @item @var{token} | |
16150 | Specifies a marker value to be placed in the feedback buffer following a | |
16151 | @code{GL_PASS_THROUGH_TOKEN}. | |
16152 | ||
16153 | @end table | |
16154 | ||
8925f36f AW |
16155 | |
16156 | ||
c7b31271 DH |
16157 | Feedback is a GL render mode. The mode is selected by calling |
16158 | @code{glRenderMode} with @code{GL_FEEDBACK}. When the GL is in feedback | |
16159 | mode, no pixels are produced by rasterization. Instead, information | |
8925f36f | 16160 | about primitives that would have been rasterized is fed back to the |
c7b31271 DH |
16161 | application using the GL. See the @code{glFeedbackBuffer} reference |
16162 | page for a description of the feedback buffer and the values in it. | |
8925f36f AW |
16163 | |
16164 | @code{glPassThrough} inserts a user-defined marker in the feedback | |
c7b31271 | 16165 | buffer when it is executed in feedback mode. @var{token} is returned as |
8925f36f | 16166 | if it were a primitive; it is indicated with its own unique identifying |
c7b31271 | 16167 | value: @code{GL_PASS_THROUGH_TOKEN}. The order of @code{glPassThrough} |
8925f36f AW |
16168 | commands with respect to the specification of graphics primitives is |
16169 | maintained. | |
16170 | ||
8925f36f AW |
16171 | @code{GL_INVALID_OPERATION} is generated if @code{glPassThrough} is |
16172 | executed between the execution of @code{glBegin} and the corresponding | |
16173 | execution of @code{glEnd}. | |
16174 | ||
bb894c9d | 16175 | @end deftypefun |
8925f36f | 16176 | |
b002944d AW |
16177 | @deftypefun void glPixelMapfv map mapsize values |
16178 | @deftypefunx void glPixelMapuiv map mapsize values | |
d172eed9 | 16179 | @deftypefunx void glPixelMapusv map mapsize values |
b002944d AW |
16180 | Set up pixel transfer maps. |
16181 | ||
16182 | @table @asis | |
16183 | @item @var{map} | |
c7b31271 | 16184 | Specifies a symbolic map name. Must be one of the following: |
b002944d AW |
16185 | @code{GL_PIXEL_MAP_I_TO_I}, @code{GL_PIXEL_MAP_S_TO_S}, |
16186 | @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G}, | |
16187 | @code{GL_PIXEL_MAP_I_TO_B}, @code{GL_PIXEL_MAP_I_TO_A}, | |
16188 | @code{GL_PIXEL_MAP_R_TO_R}, @code{GL_PIXEL_MAP_G_TO_G}, | |
16189 | @code{GL_PIXEL_MAP_B_TO_B}, or @code{GL_PIXEL_MAP_A_TO_A}. | |
16190 | ||
16191 | @item @var{mapsize} | |
16192 | Specifies the size of the map being defined. | |
16193 | ||
16194 | @item @var{values} | |
16195 | Specifies an array of @var{mapsize} values. | |
16196 | ||
16197 | @end table | |
16198 | ||
16199 | @code{glPixelMap} sets up translation tables, or @var{maps}, used by | |
16200 | @code{glCopyPixels}, @code{glCopyTexImage1D}, @code{glCopyTexImage2D}, | |
16201 | @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D}, | |
16202 | @code{glCopyTexSubImage3D}, @code{glDrawPixels}, @code{glReadPixels}, | |
16203 | @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D}, | |
16204 | @code{glTexSubImage1D}, @code{glTexSubImage2D}, and | |
c7b31271 | 16205 | @code{glTexSubImage3D}. Additionally, if the @code{ARB_imaging} subset |
b002944d AW |
16206 | is supported, the routines @code{glColorTable}, @code{glColorSubTable}, |
16207 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, | |
c7b31271 | 16208 | @code{glHistogram}, @code{glMinmax}, and @code{glSeparableFilter2D}. Use |
b002944d AW |
16209 | of these maps is described completely in the @code{glPixelTransfer} |
16210 | reference page, and partly in the reference pages for the pixel and | |
c7b31271 | 16211 | texture image commands. Only the specification of the maps is described |
b002944d AW |
16212 | in this reference page. |
16213 | ||
16214 | @var{map} is a symbolic map name, indicating one of ten maps to set. | |
16215 | @var{mapsize} specifies the number of entries in the map, and | |
16216 | @var{values} is a pointer to an array of @var{mapsize} map values. | |
16217 | ||
16218 | If a non-zero named buffer object is bound to the | |
16219 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
16220 | pixel transfer map is specified, @var{values} is treated as a byte | |
16221 | offset into the buffer object's data store. | |
16222 | ||
16223 | The ten maps are as follows: | |
16224 | ||
16225 | @table @asis | |
16226 | @item @code{GL_PIXEL_MAP_I_TO_I} | |
16227 | Maps color indices to color indices. | |
16228 | ||
16229 | @item @code{GL_PIXEL_MAP_S_TO_S} | |
16230 | Maps stencil indices to stencil indices. | |
16231 | ||
16232 | @item @code{GL_PIXEL_MAP_I_TO_R} | |
16233 | Maps color indices to red components. | |
16234 | ||
16235 | @item @code{GL_PIXEL_MAP_I_TO_G} | |
16236 | Maps color indices to green components. | |
16237 | ||
16238 | @item @code{GL_PIXEL_MAP_I_TO_B} | |
16239 | Maps color indices to blue components. | |
16240 | ||
16241 | @item @code{GL_PIXEL_MAP_I_TO_A} | |
16242 | Maps color indices to alpha components. | |
16243 | ||
16244 | @item @code{GL_PIXEL_MAP_R_TO_R} | |
16245 | Maps red components to red components. | |
16246 | ||
16247 | @item @code{GL_PIXEL_MAP_G_TO_G} | |
16248 | Maps green components to green components. | |
16249 | ||
16250 | @item @code{GL_PIXEL_MAP_B_TO_B} | |
16251 | Maps blue components to blue components. | |
16252 | ||
16253 | @item @code{GL_PIXEL_MAP_A_TO_A} | |
16254 | Maps alpha components to alpha components. | |
16255 | ||
16256 | @end table | |
16257 | ||
16258 | The entries in a map can be specified as single-precision floating-point | |
c7b31271 | 16259 | numbers, unsigned short integers, or unsigned int integers. Maps that |
b002944d AW |
16260 | store color component values (all but @code{GL_PIXEL_MAP_I_TO_I} and |
16261 | @code{GL_PIXEL_MAP_S_TO_S}) retain their values in floating-point | |
c7b31271 | 16262 | format, with unspecified mantissa and exponent sizes. Floating-point |
b002944d AW |
16263 | values specified by @code{glPixelMapfv} are converted directly to the |
16264 | internal floating-point format of these maps, then clamped to the range | |
c7b31271 | 16265 | [0,1]. Unsigned integer values specified by @code{glPixelMapusv} and |
b002944d AW |
16266 | @code{glPixelMapuiv} are converted linearly such that the largest |
16267 | representable integer maps to 1.0, and 0 maps to 0.0. | |
16268 | ||
16269 | Maps that store indices, @code{GL_PIXEL_MAP_I_TO_I} and | |
16270 | @code{GL_PIXEL_MAP_S_TO_S}, retain their values in fixed-point format, | |
16271 | with an unspecified number of bits to the right of the binary point. | |
16272 | Floating-point values specified by @code{glPixelMapfv} are converted | |
c7b31271 | 16273 | directly to the internal fixed-point format of these maps. Unsigned |
b002944d AW |
16274 | integer values specified by @code{glPixelMapusv} and |
16275 | @code{glPixelMapuiv} specify integer values, with all 0's to the right | |
16276 | of the binary point. | |
16277 | ||
16278 | The following table shows the initial sizes and values for each of the | |
c7b31271 DH |
16279 | maps. Maps that are indexed by either color or stencil indices must |
16280 | have @var{mapsize} = @r{2^@var{n}} for some @r{@var{n}} or the results | |
16281 | are undefined. The maximum allowable size for each map depends on the | |
b002944d | 16282 | implementation and can be determined by calling @code{glGet} with |
c7b31271 | 16283 | argument @code{GL_MAX_PIXEL_MAP_TABLE}. The single maximum applies to |
b002944d AW |
16284 | all maps; it is at least 32. |
16285 | ||
16286 | @table @asis | |
16287 | @item @strong{@var{map}} | |
16288 | @strong{Lookup Index}, @strong{Lookup Value}, @strong{Initial Size}, | |
16289 | @strong{Initial Value} | |
16290 | ||
16291 | @item @code{GL_PIXEL_MAP_I_TO_I} | |
16292 | color index , color index , 1 , 0 | |
16293 | ||
16294 | @item @code{GL_PIXEL_MAP_S_TO_S} | |
16295 | stencil index , stencil index , 1 , 0 | |
16296 | ||
16297 | @item @code{GL_PIXEL_MAP_I_TO_R} | |
16298 | color index , R , 1 , 0 | |
16299 | ||
16300 | @item @code{GL_PIXEL_MAP_I_TO_G} | |
16301 | color index , G , 1 , 0 | |
16302 | ||
16303 | @item @code{GL_PIXEL_MAP_I_TO_B} | |
16304 | color index , B , 1 , 0 | |
16305 | ||
16306 | @item @code{GL_PIXEL_MAP_I_TO_A} | |
16307 | color index , A , 1 , 0 | |
16308 | ||
16309 | @item @code{GL_PIXEL_MAP_R_TO_R} | |
16310 | R , R , 1 , 0 | |
16311 | ||
16312 | @item @code{GL_PIXEL_MAP_G_TO_G} | |
16313 | G , G , 1 , 0 | |
16314 | ||
16315 | @item @code{GL_PIXEL_MAP_B_TO_B} | |
16316 | B , B , 1 , 0 | |
16317 | ||
16318 | @item @code{GL_PIXEL_MAP_A_TO_A} | |
16319 | A , A , 1 , 0 | |
16320 | ||
16321 | @end table | |
16322 | ||
16323 | @code{GL_INVALID_ENUM} is generated if @var{map} is not an accepted | |
16324 | value. | |
16325 | ||
16326 | @code{GL_INVALID_VALUE} is generated if @var{mapsize} is less than one | |
16327 | or larger than @code{GL_MAX_PIXEL_MAP_TABLE}. | |
16328 | ||
16329 | @code{GL_INVALID_VALUE} is generated if @var{map} is | |
16330 | @code{GL_PIXEL_MAP_I_TO_I}, @code{GL_PIXEL_MAP_S_TO_S}, | |
16331 | @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G}, | |
16332 | @code{GL_PIXEL_MAP_I_TO_B}, or @code{GL_PIXEL_MAP_I_TO_A}, and | |
16333 | @var{mapsize} is not a power of two. | |
16334 | ||
16335 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
16336 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
16337 | object's data store is currently mapped. | |
16338 | ||
16339 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
16340 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
16341 | would be unpacked from the buffer object such that the memory reads | |
16342 | required would exceed the data store size. | |
16343 | ||
16344 | @code{GL_INVALID_OPERATION} is generated by @code{glPixelMapfv} if a | |
16345 | non-zero buffer object name is bound to the | |
16346 | @code{GL_PIXEL_UNPACK_BUFFER} target and @var{values} is not evenly | |
16347 | divisible into the number of bytes needed to store in memory a GLfloat | |
16348 | datum. | |
16349 | ||
16350 | @code{GL_INVALID_OPERATION} is generated by @code{glPixelMapuiv} if a | |
16351 | non-zero buffer object name is bound to the | |
16352 | @code{GL_PIXEL_UNPACK_BUFFER} target and @var{values} is not evenly | |
16353 | divisible into the number of bytes needed to store in memory a GLuint | |
16354 | datum. | |
16355 | ||
16356 | @code{GL_INVALID_OPERATION} is generated by @code{glPixelMapusv} if a | |
16357 | non-zero buffer object name is bound to the | |
16358 | @code{GL_PIXEL_UNPACK_BUFFER} target and @var{values} is not evenly | |
16359 | divisible into the number of bytes needed to store in memory a GLushort | |
16360 | datum. | |
16361 | ||
16362 | @code{GL_INVALID_OPERATION} is generated if @code{glPixelMap} is | |
16363 | executed between the execution of @code{glBegin} and the corresponding | |
16364 | execution of @code{glEnd}. | |
16365 | ||
16366 | @end deftypefun | |
16367 | ||
bb894c9d AW |
16368 | @deftypefun void glPixelStoref pname param |
16369 | @deftypefunx void glPixelStorei pname param | |
3c9b6116 AW |
16370 | Set pixel storage modes. |
16371 | ||
8925f36f AW |
16372 | @table @asis |
16373 | @item @var{pname} | |
c7b31271 | 16374 | Specifies the symbolic name of the parameter to be set. Six values |
8925f36f AW |
16375 | affect the packing of pixel data into memory: @code{GL_PACK_SWAP_BYTES}, |
16376 | @code{GL_PACK_LSB_FIRST}, @code{GL_PACK_ROW_LENGTH}, | |
16377 | @code{GL_PACK_IMAGE_HEIGHT}, @code{GL_PACK_SKIP_PIXELS}, | |
16378 | @code{GL_PACK_SKIP_ROWS}, @code{GL_PACK_SKIP_IMAGES}, and | |
c7b31271 | 16379 | @code{GL_PACK_ALIGNMENT}. Six more affect the unpacking of pixel data |
8925f36f AW |
16380 | @var{from} memory: @code{GL_UNPACK_SWAP_BYTES}, |
16381 | @code{GL_UNPACK_LSB_FIRST}, @code{GL_UNPACK_ROW_LENGTH}, | |
16382 | @code{GL_UNPACK_IMAGE_HEIGHT}, @code{GL_UNPACK_SKIP_PIXELS}, | |
16383 | @code{GL_UNPACK_SKIP_ROWS}, @code{GL_UNPACK_SKIP_IMAGES}, and | |
16384 | @code{GL_UNPACK_ALIGNMENT}. | |
16385 | ||
16386 | @item @var{param} | |
16387 | Specifies the value that @var{pname} is set to. | |
16388 | ||
16389 | @end table | |
16390 | ||
8925f36f AW |
16391 | @code{glPixelStore} sets pixel storage modes that affect the operation |
16392 | of subsequent @code{glDrawPixels} and @code{glReadPixels} as well as the | |
16393 | unpacking of polygon stipple patterns (see @code{glPolygonStipple}), | |
16394 | bitmaps (see @code{glBitmap}), texture patterns (see | |
16395 | @code{glTexImage1D}, @code{glTexImage2D}, @code{glTexImage3D}, | |
16396 | @code{glTexSubImage1D}, @code{glTexSubImage2D}, @code{glTexSubImage3D}). | |
16397 | Additionally, if the @code{ARB_imaging} extension is supported, pixel | |
16398 | storage modes affect convolution filters (see | |
16399 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and | |
16400 | @code{glSeparableFilter2D}, color table (see @code{glColorTable}, and | |
16401 | @code{glColorSubTable}, and unpacking histogram (See | |
16402 | @code{glHistogram}), and minmax (See @code{glMinmax}) data. | |
16403 | ||
16404 | @var{pname} is a symbolic constant indicating the parameter to be set, | |
c7b31271 DH |
16405 | and @var{param} is the new value. Six of the twelve storage parameters |
16406 | affect how pixel data is returned to client memory. They are as | |
16407 | follows: | |
8925f36f AW |
16408 | |
16409 | @table @asis | |
16410 | @item @code{GL_PACK_SWAP_BYTES} | |
16411 | If true, byte ordering for multibyte color components, depth components, | |
c7b31271 | 16412 | color indices, or stencil indices is reversed. That is, if a four-byte |
3c9b6116 AW |
16413 | component consists of bytes @r{@var{b}_0}, @r{@var{b}_1}, @r{@var{b}_2}, |
16414 | @r{@var{b}_3}, it is stored in memory as @r{@var{b}_3}, @r{@var{b}_2}, | |
16415 | @r{@var{b}_1}, @r{@var{b}_0} if @code{GL_PACK_SWAP_BYTES} is true. | |
16416 | @code{GL_PACK_SWAP_BYTES} has no effect on the memory order of | |
16417 | components within a pixel, only on the order of bytes within components | |
c7b31271 | 16418 | or indices. For example, the three components of a @code{GL_RGB} format |
3c9b6116 AW |
16419 | pixel are always stored with red first, green second, and blue third, |
16420 | regardless of the value of @code{GL_PACK_SWAP_BYTES}. | |
8925f36f AW |
16421 | |
16422 | @item @code{GL_PACK_LSB_FIRST} | |
16423 | If true, bits are ordered within a byte from least significant to most | |
16424 | significant; otherwise, the first bit in each byte is the most | |
c7b31271 | 16425 | significant one. This parameter is significant for bitmap data only. |
8925f36f AW |
16426 | |
16427 | @item @code{GL_PACK_ROW_LENGTH} | |
16428 | If greater than 0, @code{GL_PACK_ROW_LENGTH} defines the number of | |
c7b31271 | 16429 | pixels in a row. If the first pixel of a row is placed at location |
3c9b6116 AW |
16430 | @r{@var{p}} in memory, then the location of the first pixel of the next |
16431 | row is obtained by skipping | |
8925f36f | 16432 | |
3c9b6116 | 16433 | @r{@var{k}=@{(@var{n}@var{l}), |
8925f36f AW |
16434 | (@var{a}/@var{s},⌈@var{s}@var{n}@var{l},/@var{a},⌉)(@var{s}>=@var{a}), |
16435 | (@var{s}<@var{a}),} | |
16436 | ||
3c9b6116 AW |
16437 | components or indices, where @r{@var{n}} is the number of components or |
16438 | indices in a pixel, @r{@var{l}} is the number of pixels in a row | |
16439 | (@code{GL_PACK_ROW_LENGTH} if it is greater than 0, the @r{@var{width}} | |
16440 | argument to the pixel routine otherwise), @r{@var{a}} is the value of | |
16441 | @code{GL_PACK_ALIGNMENT}, and @r{@var{s}} is the size, in bytes, of a | |
16442 | single component (if @r{@var{a}<@var{s}}, then it is as if | |
c7b31271 | 16443 | @r{@var{a}=@var{s}}). In the case of 1-bit values, the location of the |
3c9b6116 | 16444 | next row is obtained by skipping |
8925f36f | 16445 | |
3c9b6116 | 16446 | @r{@var{k}=8@var{a}⌈@var{n}@var{l},/8@var{a},,⌉} |
8925f36f AW |
16447 | |
16448 | components or indices. | |
16449 | ||
16450 | The word @var{component} in this description refers to the nonindex | |
c7b31271 DH |
16451 | values red, green, blue, alpha, and depth. Storage format |
16452 | @code{GL_RGB}, for example, has three components per pixel: first red, | |
16453 | then green, and finally blue. | |
8925f36f AW |
16454 | |
16455 | @item @code{GL_PACK_IMAGE_HEIGHT} | |
16456 | If greater than 0, @code{GL_PACK_IMAGE_HEIGHT} defines the number of | |
16457 | pixels in an image three-dimensional texture volume, where ``image'' is | |
c7b31271 | 16458 | defined by all pixels sharing the same third dimension index. If the |
3c9b6116 AW |
16459 | first pixel of a row is placed at location @r{@var{p}} in memory, then |
16460 | the location of the first pixel of the next row is obtained by skipping | |
8925f36f | 16461 | |
3c9b6116 | 16462 | @r{@var{k}=@{(@var{n}@var{l}@var{h}), |
8925f36f AW |
16463 | (@var{a}/@var{s},⌈@var{s}@var{n}@var{l}@var{h},/@var{a},⌉)(@var{s}>=@var{a}), |
16464 | (@var{s}<@var{a}),} | |
16465 | ||
3c9b6116 AW |
16466 | components or indices, where @r{@var{n}} is the number of components or |
16467 | indices in a pixel, @r{@var{l}} is the number of pixels in a row | |
16468 | (@code{GL_PACK_ROW_LENGTH} if it is greater than 0, the @r{@var{width}} | |
16469 | argument to @code{glTexImage3D} otherwise), @r{@var{h}} is the number of | |
16470 | rows in a pixel image (@code{GL_PACK_IMAGE_HEIGHT} if it is greater than | |
16471 | 0, the @r{@var{height}} argument to the @code{glTexImage3D} routine | |
16472 | otherwise), @r{@var{a}} is the value of @code{GL_PACK_ALIGNMENT}, and | |
16473 | @r{@var{s}} is the size, in bytes, of a single component (if | |
16474 | @r{@var{a}<@var{s}}, then it is as if @r{@var{a}=@var{s}}). | |
8925f36f AW |
16475 | |
16476 | The word @var{component} in this description refers to the nonindex | |
c7b31271 DH |
16477 | values red, green, blue, alpha, and depth. Storage format |
16478 | @code{GL_RGB}, for example, has three components per pixel: first red, | |
16479 | then green, and finally blue. | |
8925f36f AW |
16480 | |
16481 | @item @code{GL_PACK_SKIP_PIXELS}, @code{GL_PACK_SKIP_ROWS}, and @code{GL_PACK_SKIP_IMAGES} | |
16482 | These values are provided as a convenience to the programmer; they | |
16483 | provide no functionality that cannot be duplicated simply by | |
c7b31271 | 16484 | incrementing the pointer passed to @code{glReadPixels}. Setting |
3c9b6116 AW |
16485 | @code{GL_PACK_SKIP_PIXELS} to @r{@var{i}} is equivalent to incrementing |
16486 | the pointer by @r{@var{i}@var{n}} components or indices, where | |
16487 | @r{@var{n}} is the number of components or indices in each pixel. | |
16488 | Setting @code{GL_PACK_SKIP_ROWS} to @r{@var{j}} is equivalent to | |
16489 | incrementing the pointer by @r{@var{j}@var{m}} components or indices, | |
16490 | where @r{@var{m}} is the number of components or indices per row, as | |
c7b31271 | 16491 | just computed in the @code{GL_PACK_ROW_LENGTH} section. Setting |
3c9b6116 AW |
16492 | @code{GL_PACK_SKIP_IMAGES} to @r{@var{k}} is equivalent to incrementing |
16493 | the pointer by @r{@var{k}@var{p}}, where @r{@var{p}} is the number of | |
16494 | components or indices per image, as computed in the | |
16495 | @code{GL_PACK_IMAGE_HEIGHT} section. | |
8925f36f AW |
16496 | |
16497 | @item @code{GL_PACK_ALIGNMENT} | |
16498 | Specifies the alignment requirements for the start of each pixel row in | |
c7b31271 | 16499 | memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to |
8925f36f AW |
16500 | even-numbered bytes), 4 (word-alignment), and 8 (rows start on |
16501 | double-word boundaries). | |
16502 | ||
16503 | @end table | |
16504 | ||
16505 | The other six of the twelve storage parameters affect how pixel data is | |
c7b31271 | 16506 | read from client memory. These values are significant for |
8925f36f AW |
16507 | @code{glDrawPixels}, @code{glTexImage1D}, @code{glTexImage2D}, |
16508 | @code{glTexImage3D}, @code{glTexSubImage1D}, @code{glTexSubImage2D}, | |
16509 | @code{glTexSubImage3D}, @code{glBitmap}, and @code{glPolygonStipple}. | |
16510 | ||
16511 | Additionally, if the @code{ARB_imaging} extension is supported, | |
16512 | @code{glColorTable}, @code{glColorSubTable}, | |
16513 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, and | |
c7b31271 | 16514 | @code{glSeparableFilter2D}. They are as follows: |
8925f36f AW |
16515 | |
16516 | @table @asis | |
16517 | @item @code{GL_UNPACK_SWAP_BYTES} | |
16518 | If true, byte ordering for multibyte color components, depth components, | |
c7b31271 | 16519 | color indices, or stencil indices is reversed. That is, if a four-byte |
3c9b6116 AW |
16520 | component consists of bytes @r{@var{b}_0}, @r{@var{b}_1}, @r{@var{b}_2}, |
16521 | @r{@var{b}_3}, it is taken from memory as @r{@var{b}_3}, @r{@var{b}_2}, | |
16522 | @r{@var{b}_1}, @r{@var{b}_0} if @code{GL_UNPACK_SWAP_BYTES} is true. | |
16523 | @code{GL_UNPACK_SWAP_BYTES} has no effect on the memory order of | |
16524 | components within a pixel, only on the order of bytes within components | |
c7b31271 | 16525 | or indices. For example, the three components of a @code{GL_RGB} format |
3c9b6116 AW |
16526 | pixel are always stored with red first, green second, and blue third, |
16527 | regardless of the value of @code{GL_UNPACK_SWAP_BYTES}. | |
8925f36f AW |
16528 | |
16529 | @item @code{GL_UNPACK_LSB_FIRST} | |
16530 | If true, bits are ordered within a byte from least significant to most | |
16531 | significant; otherwise, the first bit in each byte is the most | |
c7b31271 | 16532 | significant one. This is relevant only for bitmap data. |
8925f36f AW |
16533 | |
16534 | @item @code{GL_UNPACK_ROW_LENGTH} | |
16535 | If greater than 0, @code{GL_UNPACK_ROW_LENGTH} defines the number of | |
c7b31271 | 16536 | pixels in a row. If the first pixel of a row is placed at location |
3c9b6116 AW |
16537 | @r{@var{p}} in memory, then the location of the first pixel of the next |
16538 | row is obtained by skipping | |
8925f36f | 16539 | |
3c9b6116 | 16540 | @r{@var{k}=@{(@var{n}@var{l}), |
8925f36f AW |
16541 | (@var{a}/@var{s},⌈@var{s}@var{n}@var{l},/@var{a},⌉)(@var{s}>=@var{a}), |
16542 | (@var{s}<@var{a}),} | |
16543 | ||
3c9b6116 AW |
16544 | components or indices, where @r{@var{n}} is the number of components or |
16545 | indices in a pixel, @r{@var{l}} is the number of pixels in a row | |
8925f36f | 16546 | (@code{GL_UNPACK_ROW_LENGTH} if it is greater than 0, the |
3c9b6116 AW |
16547 | @r{@var{width}} argument to the pixel routine otherwise), @r{@var{a}} is |
16548 | the value of @code{GL_UNPACK_ALIGNMENT}, and @r{@var{s}} is the size, in | |
16549 | bytes, of a single component (if @r{@var{a}<@var{s}}, then it is as if | |
c7b31271 | 16550 | @r{@var{a}=@var{s}}). In the case of 1-bit values, the location of the |
3c9b6116 | 16551 | next row is obtained by skipping |
8925f36f | 16552 | |
3c9b6116 | 16553 | @r{@var{k}=8@var{a}⌈@var{n}@var{l},/8@var{a},,⌉} |
8925f36f AW |
16554 | |
16555 | components or indices. | |
16556 | ||
16557 | The word @var{component} in this description refers to the nonindex | |
c7b31271 DH |
16558 | values red, green, blue, alpha, and depth. Storage format |
16559 | @code{GL_RGB}, for example, has three components per pixel: first red, | |
16560 | then green, and finally blue. | |
8925f36f AW |
16561 | |
16562 | @item @code{GL_UNPACK_IMAGE_HEIGHT} | |
16563 | If greater than 0, @code{GL_UNPACK_IMAGE_HEIGHT} defines the number of | |
c7b31271 | 16564 | pixels in an image of a three-dimensional texture volume. Where |
8925f36f | 16565 | ``image'' is defined by all pixel sharing the same third dimension |
c7b31271 | 16566 | index. If the first pixel of a row is placed at location @r{@var{p}} in |
3c9b6116 AW |
16567 | memory, then the location of the first pixel of the next row is obtained |
16568 | by skipping | |
8925f36f | 16569 | |
3c9b6116 | 16570 | @r{@var{k}=@{(@var{n}@var{l}@var{h}), |
8925f36f AW |
16571 | (@var{a}/@var{s},⌈@var{s}@var{n}@var{l}@var{h},/@var{a},⌉)(@var{s}>=@var{a}), |
16572 | (@var{s}<@var{a}),} | |
16573 | ||
3c9b6116 AW |
16574 | components or indices, where @r{@var{n}} is the number of components or |
16575 | indices in a pixel, @r{@var{l}} is the number of pixels in a row | |
8925f36f | 16576 | (@code{GL_UNPACK_ROW_LENGTH} if it is greater than 0, the |
3c9b6116 AW |
16577 | @r{@var{width}} argument to @code{glTexImage3D} otherwise), @r{@var{h}} |
16578 | is the number of rows in an image (@code{GL_UNPACK_IMAGE_HEIGHT} if it | |
16579 | is greater than 0, the @r{@var{height}} argument to @code{glTexImage3D} | |
16580 | otherwise), @r{@var{a}} is the value of @code{GL_UNPACK_ALIGNMENT}, and | |
16581 | @r{@var{s}} is the size, in bytes, of a single component (if | |
16582 | @r{@var{a}<@var{s}}, then it is as if @r{@var{a}=@var{s}}). | |
8925f36f AW |
16583 | |
16584 | The word @var{component} in this description refers to the nonindex | |
c7b31271 DH |
16585 | values red, green, blue, alpha, and depth. Storage format |
16586 | @code{GL_RGB}, for example, has three components per pixel: first red, | |
16587 | then green, and finally blue. | |
8925f36f AW |
16588 | |
16589 | @item @code{GL_UNPACK_SKIP_PIXELS} and @code{GL_UNPACK_SKIP_ROWS} | |
16590 | These values are provided as a convenience to the programmer; they | |
16591 | provide no functionality that cannot be duplicated by incrementing the | |
16592 | pointer passed to @code{glDrawPixels}, @code{glTexImage1D}, | |
16593 | @code{glTexImage2D}, @code{glTexSubImage1D}, @code{glTexSubImage2D}, | |
c7b31271 | 16594 | @code{glBitmap}, or @code{glPolygonStipple}. Setting |
3c9b6116 AW |
16595 | @code{GL_UNPACK_SKIP_PIXELS} to @r{@var{i}} is equivalent to |
16596 | incrementing the pointer by @r{@var{i}@var{n}} components or indices, | |
16597 | where @r{@var{n}} is the number of components or indices in each pixel. | |
16598 | Setting @code{GL_UNPACK_SKIP_ROWS} to @r{@var{j}} is equivalent to | |
16599 | incrementing the pointer by @r{@var{j}@var{k}} components or indices, | |
16600 | where @r{@var{k}} is the number of components or indices per row, as | |
16601 | just computed in the @code{GL_UNPACK_ROW_LENGTH} section. | |
8925f36f AW |
16602 | |
16603 | @item @code{GL_UNPACK_ALIGNMENT} | |
16604 | Specifies the alignment requirements for the start of each pixel row in | |
c7b31271 | 16605 | memory. The allowable values are 1 (byte-alignment), 2 (rows aligned to |
8925f36f AW |
16606 | even-numbered bytes), 4 (word-alignment), and 8 (rows start on |
16607 | double-word boundaries). | |
16608 | ||
16609 | @end table | |
16610 | ||
16611 | The following table gives the type, initial value, and range of valid | |
16612 | values for each storage parameter that can be set with | |
16613 | @code{glPixelStore}. | |
16614 | ||
16615 | ||
16616 | ||
16617 | @table @asis | |
16618 | @item @strong{@var{pname}} | |
16619 | @strong{Type}, @strong{Initial Value}, @strong{Valid Range} | |
16620 | ||
16621 | @item @code{GL_PACK_SWAP_BYTES} | |
16622 | boolean , false , true or false | |
16623 | ||
16624 | @item @code{GL_PACK_LSB_FIRST} | |
16625 | boolean , false , true or false | |
16626 | ||
16627 | @item @code{GL_PACK_ROW_LENGTH} | |
3c9b6116 | 16628 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16629 | |
16630 | @item @code{GL_PACK_IMAGE_HEIGHT} | |
3c9b6116 | 16631 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16632 | |
16633 | @item @code{GL_PACK_SKIP_ROWS} | |
3c9b6116 | 16634 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16635 | |
16636 | @item @code{GL_PACK_SKIP_PIXELS} | |
3c9b6116 | 16637 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16638 | |
16639 | @item @code{GL_PACK_SKIP_IMAGES} | |
3c9b6116 | 16640 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16641 | |
16642 | @item @code{GL_PACK_ALIGNMENT} | |
16643 | integer , 4 , 1, 2, 4, or 8 | |
16644 | ||
16645 | @item @code{GL_UNPACK_SWAP_BYTES} | |
16646 | boolean , false , true or false | |
16647 | ||
16648 | @item @code{GL_UNPACK_LSB_FIRST} | |
16649 | boolean , false , true or false | |
16650 | ||
16651 | @item @code{GL_UNPACK_ROW_LENGTH} | |
3c9b6116 | 16652 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16653 | |
16654 | @item @code{GL_UNPACK_IMAGE_HEIGHT} | |
3c9b6116 | 16655 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16656 | |
16657 | @item @code{GL_UNPACK_SKIP_ROWS} | |
3c9b6116 | 16658 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16659 | |
16660 | @item @code{GL_UNPACK_SKIP_PIXELS} | |
3c9b6116 | 16661 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16662 | |
16663 | @item @code{GL_UNPACK_SKIP_IMAGES} | |
3c9b6116 | 16664 | integer , 0 , @r{[0,∞)} |
8925f36f AW |
16665 | |
16666 | @item @code{GL_UNPACK_ALIGNMENT} | |
16667 | integer , 4 , 1, 2, 4, or 8 | |
16668 | ||
16669 | @end table | |
16670 | ||
c7b31271 | 16671 | @code{glPixelStoref} can be used to set any pixel store parameter. If |
8925f36f | 16672 | the parameter type is boolean, then if @var{param} is 0, the parameter |
c7b31271 | 16673 | is false; otherwise it is set to true. If @var{pname} is a integer type |
8925f36f AW |
16674 | parameter, @var{param} is rounded to the nearest integer. |
16675 | ||
16676 | Likewise, @code{glPixelStorei} can also be used to set any of the pixel | |
c7b31271 | 16677 | store parameters. Boolean parameters are set to false if @var{param} is |
8925f36f AW |
16678 | 0 and true otherwise. |
16679 | ||
8925f36f AW |
16680 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted |
16681 | value. | |
16682 | ||
16683 | @code{GL_INVALID_VALUE} is generated if a negative row length, pixel | |
16684 | skip, or row skip value is specified, or if alignment is specified as | |
16685 | other than 1, 2, 4, or 8. | |
16686 | ||
16687 | @code{GL_INVALID_OPERATION} is generated if @code{glPixelStore} is | |
16688 | executed between the execution of @code{glBegin} and the corresponding | |
16689 | execution of @code{glEnd}. | |
16690 | ||
bb894c9d | 16691 | @end deftypefun |
8925f36f | 16692 | |
bb894c9d AW |
16693 | @deftypefun void glPixelTransferf pname param |
16694 | @deftypefunx void glPixelTransferi pname param | |
3c9b6116 AW |
16695 | Set pixel transfer modes. |
16696 | ||
8925f36f AW |
16697 | @table @asis |
16698 | @item @var{pname} | |
16699 | Specifies the symbolic name of the pixel transfer parameter to be set. | |
16700 | Must be one of the following: @code{GL_MAP_COLOR}, | |
16701 | @code{GL_MAP_STENCIL}, @code{GL_INDEX_SHIFT}, @code{GL_INDEX_OFFSET}, | |
16702 | @code{GL_RED_SCALE}, @code{GL_RED_BIAS}, @code{GL_GREEN_SCALE}, | |
16703 | @code{GL_GREEN_BIAS}, @code{GL_BLUE_SCALE}, @code{GL_BLUE_BIAS}, | |
16704 | @code{GL_ALPHA_SCALE}, @code{GL_ALPHA_BIAS}, @code{GL_DEPTH_SCALE}, or | |
16705 | @code{GL_DEPTH_BIAS}. | |
16706 | ||
16707 | Additionally, if the @code{ARB_imaging} extension is supported, the | |
16708 | following symbolic names are accepted: | |
16709 | @code{GL_POST_COLOR_MATRIX_RED_SCALE}, | |
16710 | @code{GL_POST_COLOR_MATRIX_GREEN_SCALE}, | |
16711 | @code{GL_POST_COLOR_MATRIX_BLUE_SCALE}, | |
16712 | @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE}, | |
16713 | @code{GL_POST_COLOR_MATRIX_RED_BIAS}, | |
16714 | @code{GL_POST_COLOR_MATRIX_GREEN_BIAS}, | |
16715 | @code{GL_POST_COLOR_MATRIX_BLUE_BIAS}, | |
16716 | @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS}, | |
16717 | @code{GL_POST_CONVOLUTION_RED_SCALE}, | |
16718 | @code{GL_POST_CONVOLUTION_GREEN_SCALE}, | |
16719 | @code{GL_POST_CONVOLUTION_BLUE_SCALE}, | |
16720 | @code{GL_POST_CONVOLUTION_ALPHA_SCALE}, | |
16721 | @code{GL_POST_CONVOLUTION_RED_BIAS}, | |
16722 | @code{GL_POST_CONVOLUTION_GREEN_BIAS}, | |
16723 | @code{GL_POST_CONVOLUTION_BLUE_BIAS}, and | |
16724 | @code{GL_POST_CONVOLUTION_ALPHA_BIAS}. | |
16725 | ||
16726 | @item @var{param} | |
16727 | Specifies the value that @var{pname} is set to. | |
16728 | ||
16729 | @end table | |
16730 | ||
8925f36f AW |
16731 | @code{glPixelTransfer} sets pixel transfer modes that affect the |
16732 | operation of subsequent @code{glCopyPixels}, @code{glCopyTexImage1D}, | |
16733 | @code{glCopyTexImage2D}, @code{glCopyTexSubImage1D}, | |
16734 | @code{glCopyTexSubImage2D}, @code{glCopyTexSubImage3D}, | |
16735 | @code{glDrawPixels}, @code{glReadPixels}, @code{glTexImage1D}, | |
16736 | @code{glTexImage2D}, @code{glTexImage3D}, @code{glTexSubImage1D}, | |
16737 | @code{glTexSubImage2D}, and @code{glTexSubImage3D} commands. | |
16738 | Additionally, if the @code{ARB_imaging} subset is supported, the | |
16739 | routines @code{glColorTable}, @code{glColorSubTable}, | |
16740 | @code{glConvolutionFilter1D}, @code{glConvolutionFilter2D}, | |
16741 | @code{glHistogram}, @code{glMinmax}, and @code{glSeparableFilter2D} are | |
c7b31271 DH |
16742 | also affected. The algorithms that are specified by pixel transfer |
16743 | modes operate on pixels after they are read from the frame buffer | |
8925f36f AW |
16744 | (@code{glCopyPixels}@code{glCopyTexImage1D}, @code{glCopyTexImage2D}, |
16745 | @code{glCopyTexSubImage1D}, @code{glCopyTexSubImage2D}, | |
16746 | @code{glCopyTexSubImage3D}, and @code{glReadPixels}), or unpacked from | |
16747 | client memory (@code{glDrawPixels}, @code{glTexImage1D}, | |
16748 | @code{glTexImage2D}, @code{glTexImage3D}, @code{glTexSubImage1D}, | |
c7b31271 | 16749 | @code{glTexSubImage2D}, and @code{glTexSubImage3D}). Pixel transfer |
8925f36f | 16750 | operations happen in the same order, and in the same manner, regardless |
c7b31271 DH |
16751 | of the command that resulted in the pixel operation. Pixel storage |
16752 | modes (see @code{glPixelStore}) control the unpacking of pixels being | |
16753 | read from client memory and the packing of pixels being written back | |
16754 | into client memory. | |
8925f36f AW |
16755 | |
16756 | Pixel transfer operations handle four fundamental pixel types: | |
16757 | @var{color}, @var{color index}, @var{depth}, and @var{stencil}. | |
16758 | @var{Color} pixels consist of four floating-point values with | |
16759 | unspecified mantissa and exponent sizes, scaled such that 0 represents | |
c7b31271 | 16760 | zero intensity and 1 represents full intensity. @var{Color indices} |
8925f36f | 16761 | comprise a single fixed-point value, with unspecified precision to the |
c7b31271 | 16762 | right of the binary point. @var{Depth} pixels comprise a single |
8925f36f AW |
16763 | floating-point value, with unspecified mantissa and exponent sizes, |
16764 | scaled such that 0.0 represents the minimum depth buffer value, and 1.0 | |
c7b31271 DH |
16765 | represents the maximum depth buffer value. Finally, @var{stencil} |
16766 | pixels comprise a single fixed-point value, with unspecified precision | |
16767 | to the right of the binary point. | |
8925f36f AW |
16768 | |
16769 | The pixel transfer operations performed on the four basic pixel types | |
16770 | are as follows: | |
16771 | ||
16772 | @table @asis | |
16773 | @item @var{Color} | |
16774 | Each of the four color components is multiplied by a scale factor, then | |
c7b31271 | 16775 | added to a bias factor. That is, the red component is multiplied by |
8925f36f AW |
16776 | @code{GL_RED_SCALE}, then added to @code{GL_RED_BIAS}; the green |
16777 | component is multiplied by @code{GL_GREEN_SCALE}, then added to | |
16778 | @code{GL_GREEN_BIAS}; the blue component is multiplied by | |
16779 | @code{GL_BLUE_SCALE}, then added to @code{GL_BLUE_BIAS}; and the alpha | |
16780 | component is multiplied by @code{GL_ALPHA_SCALE}, then added to | |
c7b31271 DH |
16781 | @code{GL_ALPHA_BIAS}. After all four color components are scaled and |
16782 | biased, each is clamped to the range @r{[0,1]}. All color, scale, and | |
8925f36f AW |
16783 | bias values are specified with @code{glPixelTransfer}. |
16784 | ||
16785 | If @code{GL_MAP_COLOR} is true, each color component is scaled by the | |
16786 | size of the corresponding color-to-color map, then replaced by the | |
c7b31271 | 16787 | contents of that map indexed by the scaled component. That is, the red |
8925f36f | 16788 | component is scaled by @code{GL_PIXEL_MAP_R_TO_R_SIZE}, then replaced by |
c7b31271 | 16789 | the contents of @code{GL_PIXEL_MAP_R_TO_R} indexed by itself. The green |
8925f36f | 16790 | component is scaled by @code{GL_PIXEL_MAP_G_TO_G_SIZE}, then replaced by |
c7b31271 | 16791 | the contents of @code{GL_PIXEL_MAP_G_TO_G} indexed by itself. The blue |
8925f36f | 16792 | component is scaled by @code{GL_PIXEL_MAP_B_TO_B_SIZE}, then replaced by |
c7b31271 | 16793 | the contents of @code{GL_PIXEL_MAP_B_TO_B} indexed by itself. And the |
8925f36f AW |
16794 | alpha component is scaled by @code{GL_PIXEL_MAP_A_TO_A_SIZE}, then |
16795 | replaced by the contents of @code{GL_PIXEL_MAP_A_TO_A} indexed by | |
c7b31271 DH |
16796 | itself. All components taken from the maps are then clamped to the |
16797 | range @r{[0,1]}. @code{GL_MAP_COLOR} is specified with | |
16798 | @code{glPixelTransfer}. The contents of the various maps are specified | |
16799 | with @code{glPixelMap}. | |
8925f36f AW |
16800 | |
16801 | If the @code{ARB_imaging} extension is supported, each of the four color | |
16802 | components may be scaled and biased after transformation by the color | |
c7b31271 | 16803 | matrix. That is, the red component is multiplied by |
8925f36f AW |
16804 | @code{GL_POST_COLOR_MATRIX_RED_SCALE}, then added to |
16805 | @code{GL_POST_COLOR_MATRIX_RED_BIAS}; the green component is multiplied | |
16806 | by @code{GL_POST_COLOR_MATRIX_GREEN_SCALE}, then added to | |
16807 | @code{GL_POST_COLOR_MATRIX_GREEN_BIAS}; the blue component is multiplied | |
16808 | by @code{GL_POST_COLOR_MATRIX_BLUE_SCALE}, then added to | |
16809 | @code{GL_POST_COLOR_MATRIX_BLUE_BIAS}; and the alpha component is | |
16810 | multiplied by @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE}, then added to | |
c7b31271 | 16811 | @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS}. After all four color components |
3c9b6116 | 16812 | are scaled and biased, each is clamped to the range @r{[0,1]}. |
8925f36f AW |
16813 | |
16814 | Similarly, if the @code{ARB_imaging} extension is supported, each of the | |
16815 | four color components may be scaled and biased after processing by the | |
c7b31271 | 16816 | enabled convolution filter. That is, the red component is multiplied by |
8925f36f AW |
16817 | @code{GL_POST_CONVOLUTION_RED_SCALE}, then added to |
16818 | @code{GL_POST_CONVOLUTION_RED_BIAS}; the green component is multiplied | |
16819 | by @code{GL_POST_CONVOLUTION_GREEN_SCALE}, then added to | |
16820 | @code{GL_POST_CONVOLUTION_GREEN_BIAS}; the blue component is multiplied | |
16821 | by @code{GL_POST_CONVOLUTION_BLUE_SCALE}, then added to | |
16822 | @code{GL_POST_CONVOLUTION_BLUE_BIAS}; and the alpha component is | |
16823 | multiplied by @code{GL_POST_CONVOLUTION_ALPHA_SCALE}, then added to | |
c7b31271 | 16824 | @code{GL_POST_CONVOLUTION_ALPHA_BIAS}. After all four color components |
3c9b6116 | 16825 | are scaled and biased, each is clamped to the range @r{[0,1]}. |
8925f36f AW |
16826 | |
16827 | @item @var{Color index} | |
16828 | Each color index is shifted left by @code{GL_INDEX_SHIFT} bits; any bits | |
16829 | beyond the number of fraction bits carried by the fixed-point index are | |
c7b31271 DH |
16830 | filled with zeros. If @code{GL_INDEX_SHIFT} is negative, the shift is |
16831 | to the right, again zero filled. Then @code{GL_INDEX_OFFSET} is added | |
16832 | to the index. @code{GL_INDEX_SHIFT} and @code{GL_INDEX_OFFSET} are | |
8925f36f AW |
16833 | specified with @code{glPixelTransfer}. |
16834 | ||
16835 | From this point, operation diverges depending on the required format of | |
c7b31271 | 16836 | the resulting pixels. If the resulting pixels are to be written to a |
8925f36f AW |
16837 | color index buffer, or if they are being read back to client memory in |
16838 | @code{GL_COLOR_INDEX} format, the pixels continue to be treated as | |
c7b31271 | 16839 | indices. If @code{GL_MAP_COLOR} is true, each index is masked by |
3c9b6116 AW |
16840 | @r{2^@var{n}-1}, where @r{@var{n}} is @code{GL_PIXEL_MAP_I_TO_I_SIZE}, |
16841 | then replaced by the contents of @code{GL_PIXEL_MAP_I_TO_I} indexed by | |
c7b31271 DH |
16842 | the masked value. @code{GL_MAP_COLOR} is specified with |
16843 | @code{glPixelTransfer}. The contents of the index map is specified with | |
3c9b6116 | 16844 | @code{glPixelMap}. |
8925f36f AW |
16845 | |
16846 | If the resulting pixels are to be written to an RGBA color buffer, or if | |
16847 | they are read back to client memory in a format other than | |
16848 | @code{GL_COLOR_INDEX}, the pixels are converted from indices to colors | |
16849 | by referencing the four maps @code{GL_PIXEL_MAP_I_TO_R}, | |
16850 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
c7b31271 | 16851 | @code{GL_PIXEL_MAP_I_TO_A}. Before being dereferenced, the index is |
3c9b6116 | 16852 | masked by @r{2^@var{n}-1}, where @r{@var{n}} is |
8925f36f AW |
16853 | @code{GL_PIXEL_MAP_I_TO_R_SIZE} for the red map, |
16854 | @code{GL_PIXEL_MAP_I_TO_G_SIZE} for the green map, | |
16855 | @code{GL_PIXEL_MAP_I_TO_B_SIZE} for the blue map, and | |
c7b31271 DH |
16856 | @code{GL_PIXEL_MAP_I_TO_A_SIZE} for the alpha map. All components taken |
16857 | from the maps are then clamped to the range @r{[0,1]}. The contents of | |
3c9b6116 | 16858 | the four maps is specified with @code{glPixelMap}. |
8925f36f AW |
16859 | |
16860 | @item @var{Depth} | |
16861 | Each depth value is multiplied by @code{GL_DEPTH_SCALE}, added to | |
3c9b6116 | 16862 | @code{GL_DEPTH_BIAS}, then clamped to the range @r{[0,1]}. |
8925f36f AW |
16863 | |
16864 | @item @var{Stencil} | |
16865 | Each index is shifted @code{GL_INDEX_SHIFT} bits just as a color index | |
c7b31271 | 16866 | is, then added to @code{GL_INDEX_OFFSET}. If @code{GL_MAP_STENCIL} is |
3c9b6116 AW |
16867 | true, each index is masked by @r{2^@var{n}-1}, where @r{@var{n}} is |
16868 | @code{GL_PIXEL_MAP_S_TO_S_SIZE}, then replaced by the contents of | |
8925f36f AW |
16869 | @code{GL_PIXEL_MAP_S_TO_S} indexed by the masked value. |
16870 | ||
16871 | @end table | |
16872 | ||
16873 | The following table gives the type, initial value, and range of valid | |
16874 | values for each of the pixel transfer parameters that are set with | |
16875 | @code{glPixelTransfer}. | |
16876 | ||
16877 | ||
16878 | ||
16879 | @table @asis | |
16880 | @item @strong{@var{pname}} | |
16881 | @strong{Type}, @strong{Initial Value}, @strong{Valid Range} | |
16882 | ||
16883 | @item @code{GL_MAP_COLOR} | |
16884 | boolean , false , true/false | |
16885 | ||
16886 | @item @code{GL_MAP_STENCIL} | |
16887 | boolean , false , true/false | |
16888 | ||
16889 | @item @code{GL_INDEX_SHIFT} | |
3c9b6116 | 16890 | integer , 0 , @r{(-∞,∞)} |
8925f36f AW |
16891 | |
16892 | @item @code{GL_INDEX_OFFSET} | |
3c9b6116 | 16893 | integer , 0 , @r{(-∞,∞)} |
8925f36f AW |
16894 | |
16895 | @item @code{GL_RED_SCALE} | |
3c9b6116 | 16896 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16897 | |
16898 | @item @code{GL_GREEN_SCALE} | |
3c9b6116 | 16899 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16900 | |
16901 | @item @code{GL_BLUE_SCALE} | |
3c9b6116 | 16902 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16903 | |
16904 | @item @code{GL_ALPHA_SCALE} | |
3c9b6116 | 16905 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16906 | |
16907 | @item @code{GL_DEPTH_SCALE} | |
3c9b6116 | 16908 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16909 | |
16910 | @item @code{GL_RED_BIAS} | |
3c9b6116 | 16911 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16912 | |
16913 | @item @code{GL_GREEN_BIAS} | |
3c9b6116 | 16914 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16915 | |
16916 | @item @code{GL_BLUE_BIAS} | |
3c9b6116 | 16917 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16918 | |
16919 | @item @code{GL_ALPHA_BIAS} | |
3c9b6116 | 16920 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16921 | |
16922 | @item @code{GL_DEPTH_BIAS} | |
3c9b6116 | 16923 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16924 | |
16925 | @item @code{GL_POST_COLOR_MATRIX_RED_SCALE} | |
3c9b6116 | 16926 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16927 | |
16928 | @item @code{GL_POST_COLOR_MATRIX_GREEN_SCALE} | |
3c9b6116 | 16929 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16930 | |
16931 | @item @code{GL_POST_COLOR_MATRIX_BLUE_SCALE} | |
3c9b6116 | 16932 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16933 | |
16934 | @item @code{GL_POST_COLOR_MATRIX_ALPHA_SCALE} | |
3c9b6116 | 16935 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16936 | |
16937 | @item @code{GL_POST_COLOR_MATRIX_RED_BIAS} | |
3c9b6116 | 16938 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16939 | |
16940 | @item @code{GL_POST_COLOR_MATRIX_GREEN_BIAS} | |
3c9b6116 | 16941 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16942 | |
16943 | @item @code{GL_POST_COLOR_MATRIX_BLUE_BIAS} | |
3c9b6116 | 16944 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16945 | |
16946 | @item @code{GL_POST_COLOR_MATRIX_ALPHA_BIAS} | |
3c9b6116 | 16947 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16948 | |
16949 | @item @code{GL_POST_CONVOLUTION_RED_SCALE} | |
3c9b6116 | 16950 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16951 | |
16952 | @item @code{GL_POST_CONVOLUTION_GREEN_SCALE} | |
3c9b6116 | 16953 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16954 | |
16955 | @item @code{GL_POST_CONVOLUTION_BLUE_SCALE} | |
3c9b6116 | 16956 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16957 | |
16958 | @item @code{GL_POST_CONVOLUTION_ALPHA_SCALE} | |
3c9b6116 | 16959 | float , 1 , @r{(-∞,∞)} |
8925f36f AW |
16960 | |
16961 | @item @code{GL_POST_CONVOLUTION_RED_BIAS} | |
3c9b6116 | 16962 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16963 | |
16964 | @item @code{GL_POST_CONVOLUTION_GREEN_BIAS} | |
3c9b6116 | 16965 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16966 | |
16967 | @item @code{GL_POST_CONVOLUTION_BLUE_BIAS} | |
3c9b6116 | 16968 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16969 | |
16970 | @item @code{GL_POST_CONVOLUTION_ALPHA_BIAS} | |
3c9b6116 | 16971 | float , 0 , @r{(-∞,∞)} |
8925f36f AW |
16972 | |
16973 | @end table | |
16974 | ||
16975 | @code{glPixelTransferf} can be used to set any pixel transfer parameter. | |
16976 | If the parameter type is boolean, 0 implies false and any other value | |
c7b31271 | 16977 | implies true. If @var{pname} is an integer parameter, @var{param} is |
8925f36f AW |
16978 | rounded to the nearest integer. |
16979 | ||
16980 | Likewise, @code{glPixelTransferi} can be used to set any of the pixel | |
c7b31271 DH |
16981 | transfer parameters. Boolean parameters are set to false if @var{param} |
16982 | is 0 and to true otherwise. @var{param} is converted to floating point | |
8925f36f AW |
16983 | before being assigned to real-valued parameters. |
16984 | ||
8925f36f AW |
16985 | @code{GL_INVALID_ENUM} is generated if @var{pname} is not an accepted |
16986 | value. | |
16987 | ||
16988 | @code{GL_INVALID_OPERATION} is generated if @code{glPixelTransfer} is | |
16989 | executed between the execution of @code{glBegin} and the corresponding | |
16990 | execution of @code{glEnd}. | |
16991 | ||
bb894c9d | 16992 | @end deftypefun |
8925f36f | 16993 | |
bb894c9d | 16994 | @deftypefun void glPixelZoom xfactor yfactor |
3c9b6116 AW |
16995 | Specify the pixel zoom factors. |
16996 | ||
8925f36f AW |
16997 | @table @asis |
16998 | @item @var{xfactor} | |
16999 | @itemx @var{yfactor} | |
3c9b6116 AW |
17000 | Specify the @r{@var{x}} and @r{@var{y}} zoom factors for pixel write |
17001 | operations. | |
8925f36f AW |
17002 | |
17003 | @end table | |
17004 | ||
3c9b6116 | 17005 | @code{glPixelZoom} specifies values for the @r{@var{x}} and @r{@var{y}} |
c7b31271 | 17006 | zoom factors. During the execution of @code{glDrawPixels} or |
3c9b6116 AW |
17007 | @code{glCopyPixels}, if (@r{@var{xr}}, @r{@var{yr}}) is the current |
17008 | raster position, and a given element is in the @r{@var{m}}th row and | |
17009 | @r{@var{n}}th column of the pixel rectangle, then pixels whose centers | |
17010 | are in the rectangle with corners at | |
8925f36f | 17011 | |
3c9b6116 | 17012 | (@r{@var{xr}+@var{n}·@var{xfactor}}, @r{@var{yr}+@var{m}·@var{yfactor}}) |
8925f36f | 17013 | |
3c9b6116 AW |
17014 | (@r{@var{xr}+(@var{n}+1,)·@var{xfactor}}, |
17015 | @r{@var{yr}+(@var{m}+1,)·@var{yfactor}}) | |
8925f36f | 17016 | |
c7b31271 | 17017 | are candidates for replacement. Any pixel whose center lies on the |
8925f36f AW |
17018 | bottom or left edge of this rectangular region is also modified. |
17019 | ||
c7b31271 | 17020 | Pixel zoom factors are not limited to positive values. Negative zoom |
8925f36f AW |
17021 | factors reflect the resulting image about the current raster position. |
17022 | ||
8925f36f AW |
17023 | @code{GL_INVALID_OPERATION} is generated if @code{glPixelZoom} is |
17024 | executed between the execution of @code{glBegin} and the corresponding | |
17025 | execution of @code{glEnd}. | |
17026 | ||
bb894c9d | 17027 | @end deftypefun |
8925f36f | 17028 | |
bb894c9d AW |
17029 | @deftypefun void glPointParameterf pname param |
17030 | @deftypefunx void glPointParameteri pname param | |
d172eed9 AW |
17031 | @deftypefunx void glPointParameterfv pname params |
17032 | @deftypefunx void glPointParameteriv pname params | |
3c9b6116 AW |
17033 | Specify point parameters. |
17034 | ||
8925f36f AW |
17035 | @table @asis |
17036 | @item @var{pname} | |
c7b31271 | 17037 | Specifies a single-valued point parameter. @code{GL_POINT_SIZE_MIN}, |
8925f36f AW |
17038 | @code{GL_POINT_SIZE_MAX}, @code{GL_POINT_FADE_THRESHOLD_SIZE}, and |
17039 | @code{GL_POINT_SPRITE_COORD_ORIGIN} are accepted. | |
17040 | ||
17041 | @item @var{param} | |
17042 | Specifies the value that @var{pname} will be set to. | |
17043 | ||
17044 | @end table | |
17045 | ||
8925f36f AW |
17046 | The following values are accepted for @var{pname}: |
17047 | ||
17048 | @table @asis | |
17049 | @item @code{GL_POINT_SIZE_MIN} | |
17050 | ||
17051 | ||
17052 | @var{params} is a single floating-point value that specifies the minimum | |
c7b31271 | 17053 | point size. The default value is 0.0. |
8925f36f AW |
17054 | |
17055 | @item @code{GL_POINT_SIZE_MAX} | |
17056 | ||
17057 | ||
17058 | @var{params} is a single floating-point value that specifies the maximum | |
c7b31271 | 17059 | point size. The default value is 1.0. |
8925f36f AW |
17060 | |
17061 | @item @code{GL_POINT_FADE_THRESHOLD_SIZE} | |
17062 | ||
17063 | ||
17064 | @var{params} is a single floating-point value that specifies the | |
17065 | threshold value to which point sizes are clamped if they exceed the | |
c7b31271 | 17066 | specified value. The default value is 1.0. |
8925f36f AW |
17067 | |
17068 | @item @code{GL_POINT_DISTANCE_ATTENUATION} | |
17069 | ||
17070 | ||
17071 | @var{params} is an array of three floating-point values that specify the | |
c7b31271 | 17072 | coefficients used for scaling the computed point size. The default |
3c9b6116 | 17073 | values are @r{(1,00)}. |
8925f36f AW |
17074 | |
17075 | @item @code{GL_POINT_SPRITE_COORD_ORIGIN} | |
17076 | ||
17077 | ||
17078 | @var{params} is a single enum specifying the point sprite texture | |
17079 | coordinate origin, either @code{GL_LOWER_LEFT} or @code{GL_UPPER_LEFT}. | |
17080 | The default value is @code{GL_UPPER_LEFT}. | |
17081 | ||
17082 | @end table | |
17083 | ||
8925f36f AW |
17084 | @code{GL_INVALID_VALUE} is generated If the value specified for |
17085 | @code{GL_POINT_SIZE_MIN}, @code{GL_POINT_SIZE_MAX}, or | |
17086 | @code{GL_POINT_FADE_THRESHOLD_SIZE} is less than zero. | |
17087 | ||
17088 | @code{GL_INVALID_ENUM} is generated If the value specified for | |
17089 | @code{GL_POINT_SPRITE_COORD_ORIGIN} is not @code{GL_LOWER_LEFT} or | |
17090 | @code{GL_UPPER_LEFT}. | |
17091 | ||
17092 | If the value for @code{GL_POINT_SIZE_MIN} is greater than | |
17093 | @code{GL_POINT_SIZE_MAX}, the point size after clamping is undefined, | |
17094 | but no error is generated. | |
17095 | ||
17096 | ||
17097 | ||
bb894c9d | 17098 | @end deftypefun |
8925f36f | 17099 | |
bb894c9d | 17100 | @deftypefun void glPointSize size |
3c9b6116 AW |
17101 | Specify the diameter of rasterized points. |
17102 | ||
8925f36f AW |
17103 | @table @asis |
17104 | @item @var{size} | |
c7b31271 | 17105 | Specifies the diameter of rasterized points. The initial value is 1. |
8925f36f AW |
17106 | |
17107 | @end table | |
17108 | ||
8925f36f | 17109 | @code{glPointSize} specifies the rasterized diameter of both aliased and |
c7b31271 DH |
17110 | antialiased points. Using a point size other than 1 has different |
17111 | effects, depending on whether point antialiasing is enabled. To enable | |
8925f36f | 17112 | and disable point antialiasing, call @code{glEnable} and |
c7b31271 | 17113 | @code{glDisable} with argument @code{GL_POINT_SMOOTH}. Point |
8925f36f AW |
17114 | antialiasing is initially disabled. |
17115 | ||
17116 | The specified point size is multiplied with a distance attenuation | |
17117 | factor and clamped to the specified point size range, and further | |
17118 | clamped to the implementation-dependent point size range to produce the | |
17119 | derived point size using | |
17120 | ||
3c9b6116 | 17121 | @r{@var{pointSize}=@var{clamp}(@var{size}×√(1/@var{a}+@var{b}×@var{d}+@var{c}×@var{d}^2,,,),,)} |
8925f36f | 17122 | |
3c9b6116 AW |
17123 | where @r{@var{d}} is the eye-coordinate distance from the eye to the |
17124 | vertex, and @r{@var{a}}, @r{@var{b}}, and @r{@var{c}} are the distance | |
17125 | attenuation coefficients (see @code{glPointParameter}). | |
8925f36f AW |
17126 | |
17127 | If multisampling is disabled, the computed point size is used as the | |
17128 | point's width. | |
17129 | ||
17130 | If multisampling is enabled, the point may be faded by modifying the | |
17131 | point alpha value (see @code{glSampleCoverage}) instead of allowing the | |
17132 | point width to go below a given threshold (see @code{glPointParameter}). | |
17133 | In this case, the width is further modified in the following manner: | |
17134 | ||
3c9b6116 | 17135 | @r{@var{pointWidth}=@{(@var{pointSize}), |
8925f36f AW |
17136 | (@var{threshold})(@var{pointSize}>=@var{threshold}), |
17137 | (@var{otherwise}),} | |
17138 | ||
17139 | The point alpha value is modified by computing: | |
17140 | ||
3c9b6116 | 17141 | @r{@var{pointAlpha}=@{(1), |
8925f36f AW |
17142 | ((@var{pointSize}/@var{threshold},)^2)(@var{pointSize}>=@var{threshold}), |
17143 | (@var{otherwise}),} | |
17144 | ||
17145 | If point antialiasing is disabled, the actual size is determined by | |
c7b31271 | 17146 | rounding the supplied size to the nearest integer. (If the rounding |
8925f36f | 17147 | results in the value 0, it is as if the point size were 1.) If the |
3c9b6116 AW |
17148 | rounded size is odd, then the center point (@r{@var{x}}, @r{@var{y}}) of |
17149 | the pixel fragment that represents the point is computed as | |
8925f36f | 17150 | |
3c9b6116 | 17151 | @r{(⌊@var{x}_@var{w},⌋+.5,⌊@var{y}_@var{w},⌋+.5)} |
8925f36f | 17152 | |
c7b31271 | 17153 | where @r{@var{w}} subscripts indicate window coordinates. All pixels |
8925f36f | 17154 | that lie within the square grid of the rounded size centered at |
c7b31271 | 17155 | (@r{@var{x}}, @r{@var{y}}) make up the fragment. If the size is even, |
3c9b6116 | 17156 | the center point is |
8925f36f | 17157 | |
3c9b6116 | 17158 | @r{(⌊@var{x}_@var{w}+.5,⌋,⌊@var{y}_@var{w}+.5,⌋)} |
8925f36f AW |
17159 | |
17160 | and the rasterized fragment's centers are the half-integer window | |
17161 | coordinates within the square of the rounded size centered at | |
c7b31271 | 17162 | @r{(@var{x},@var{y})}. All pixel fragments produced in rasterizing a |
8925f36f AW |
17163 | nonantialiased point are assigned the same associated data, that of the |
17164 | vertex corresponding to the point. | |
17165 | ||
17166 | If antialiasing is enabled, then point rasterization produces a fragment | |
17167 | for each pixel square that intersects the region lying within the circle | |
17168 | having diameter equal to the current point size and centered at the | |
c7b31271 | 17169 | point's @r{(@var{x}_@var{w},@var{y}_@var{w})}. The coverage value for |
8925f36f | 17170 | each fragment is the window coordinate area of the intersection of the |
c7b31271 DH |
17171 | circular region with the corresponding pixel square. This value is |
17172 | saved and used in the final rasterization step. The data associated | |
17173 | with each fragment is the data associated with the point being | |
17174 | rasterized. | |
8925f36f | 17175 | |
c7b31271 DH |
17176 | Not all sizes are supported when point antialiasing is enabled. If an |
17177 | unsupported size is requested, the nearest supported size is used. Only | |
8925f36f | 17178 | size 1 is guaranteed to be supported; others depend on the |
c7b31271 | 17179 | implementation. To query the range of supported sizes and the size |
8925f36f AW |
17180 | difference between supported sizes within the range, call @code{glGet} |
17181 | with arguments @code{GL_SMOOTH_POINT_SIZE_RANGE} and | |
c7b31271 | 17182 | @code{GL_SMOOTH_POINT_SIZE_GRANULARITY}. For aliased points, query the |
8925f36f AW |
17183 | supported ranges and granularity with @code{glGet} with arguments |
17184 | @code{GL_ALIASED_POINT_SIZE_RANGE}. | |
17185 | ||
8925f36f AW |
17186 | @code{GL_INVALID_VALUE} is generated if @var{size} is less than or equal |
17187 | to 0. | |
17188 | ||
17189 | @code{GL_INVALID_OPERATION} is generated if @code{glPointSize} is | |
17190 | executed between the execution of @code{glBegin} and the corresponding | |
17191 | execution of @code{glEnd}. | |
17192 | ||
bb894c9d | 17193 | @end deftypefun |
8925f36f | 17194 | |
bb894c9d | 17195 | @deftypefun void glPolygonMode face mode |
3c9b6116 AW |
17196 | Select a polygon rasterization mode. |
17197 | ||
8925f36f AW |
17198 | @table @asis |
17199 | @item @var{face} | |
c7b31271 | 17200 | Specifies the polygons that @var{mode} applies to. Must be |
8925f36f AW |
17201 | @code{GL_FRONT} for front-facing polygons, @code{GL_BACK} for |
17202 | back-facing polygons, or @code{GL_FRONT_AND_BACK} for front- and | |
17203 | back-facing polygons. | |
17204 | ||
17205 | @item @var{mode} | |
c7b31271 DH |
17206 | Specifies how polygons will be rasterized. Accepted values are |
17207 | @code{GL_POINT}, @code{GL_LINE}, and @code{GL_FILL}. The initial value | |
8925f36f AW |
17208 | is @code{GL_FILL} for both front- and back-facing polygons. |
17209 | ||
17210 | @end table | |
17211 | ||
8925f36f | 17212 | @code{glPolygonMode} controls the interpretation of polygons for |
c7b31271 | 17213 | rasterization. @var{face} describes which polygons @var{mode} applies |
8925f36f | 17214 | to: front-facing polygons (@code{GL_FRONT}), back-facing polygons |
c7b31271 DH |
17215 | (@code{GL_BACK}), or both (@code{GL_FRONT_AND_BACK}). The polygon mode |
17216 | affects only the final rasterization of polygons. In particular, a | |
8925f36f AW |
17217 | polygon's vertices are lit and the polygon is clipped and possibly |
17218 | culled before these modes are applied. | |
17219 | ||
17220 | Three modes are defined and can be specified in @var{mode}: | |
17221 | ||
17222 | @table @asis | |
17223 | @item @code{GL_POINT} | |
17224 | Polygon vertices that are marked as the start of a boundary edge are | |
c7b31271 DH |
17225 | drawn as points. Point attributes such as @code{GL_POINT_SIZE} and |
17226 | @code{GL_POINT_SMOOTH} control the rasterization of the points. Polygon | |
8925f36f AW |
17227 | rasterization attributes other than @code{GL_POLYGON_MODE} have no |
17228 | effect. | |
17229 | ||
17230 | @item @code{GL_LINE} | |
c7b31271 | 17231 | Boundary edges of the polygon are drawn as line segments. They are |
8925f36f AW |
17232 | treated as connected line segments for line stippling; the line stipple |
17233 | counter and pattern are not reset between segments (see | |
c7b31271 DH |
17234 | @code{glLineStipple}). Line attributes such as @code{GL_LINE_WIDTH} and |
17235 | @code{GL_LINE_SMOOTH} control the rasterization of the lines. Polygon | |
8925f36f AW |
17236 | rasterization attributes other than @code{GL_POLYGON_MODE} have no |
17237 | effect. | |
17238 | ||
17239 | @item @code{GL_FILL} | |
c7b31271 | 17240 | The interior of the polygon is filled. Polygon attributes such as |
8925f36f AW |
17241 | @code{GL_POLYGON_STIPPLE} and @code{GL_POLYGON_SMOOTH} control the |
17242 | rasterization of the polygon. | |
17243 | ||
17244 | @end table | |
17245 | ||
8925f36f AW |
17246 | @code{GL_INVALID_ENUM} is generated if either @var{face} or @var{mode} |
17247 | is not an accepted value. | |
17248 | ||
17249 | @code{GL_INVALID_OPERATION} is generated if @code{glPolygonMode} is | |
17250 | executed between the execution of @code{glBegin} and the corresponding | |
17251 | execution of @code{glEnd}. | |
17252 | ||
bb894c9d | 17253 | @end deftypefun |
8925f36f | 17254 | |
bb894c9d | 17255 | @deftypefun void glPolygonOffset factor units |
3c9b6116 AW |
17256 | Set the scale and units used to calculate depth values. |
17257 | ||
8925f36f AW |
17258 | @table @asis |
17259 | @item @var{factor} | |
17260 | Specifies a scale factor that is used to create a variable depth offset | |
c7b31271 | 17261 | for each polygon. The initial value is 0. |
8925f36f AW |
17262 | |
17263 | @item @var{units} | |
17264 | Is multiplied by an implementation-specific value to create a constant | |
c7b31271 | 17265 | depth offset. The initial value is 0. |
8925f36f AW |
17266 | |
17267 | @end table | |
17268 | ||
8925f36f AW |
17269 | When @code{GL_POLYGON_OFFSET_FILL}, @code{GL_POLYGON_OFFSET_LINE}, or |
17270 | @code{GL_POLYGON_OFFSET_POINT} is enabled, each fragment's @var{depth} | |
17271 | value will be offset after it is interpolated from the @var{depth} | |
c7b31271 | 17272 | values of the appropriate vertices. The value of the offset is |
3c9b6116 AW |
17273 | @r{@var{factor}×@var{DZ}+@var{r}×@var{units}}, where @r{@var{DZ}} is a |
17274 | measurement of the change in depth relative to the screen area of the | |
17275 | polygon, and @r{@var{r}} is the smallest value that is guaranteed to | |
c7b31271 | 17276 | produce a resolvable offset for a given implementation. The offset is |
8925f36f AW |
17277 | added before the depth test is performed and before the value is written |
17278 | into the depth buffer. | |
17279 | ||
17280 | @code{glPolygonOffset} is useful for rendering hidden-line images, for | |
17281 | applying decals to surfaces, and for rendering solids with highlighted | |
17282 | edges. | |
17283 | ||
8925f36f AW |
17284 | @code{GL_INVALID_OPERATION} is generated if @code{glPolygonOffset} is |
17285 | executed between the execution of @code{glBegin} and the corresponding | |
17286 | execution of @code{glEnd}. | |
17287 | ||
bb894c9d | 17288 | @end deftypefun |
8925f36f | 17289 | |
bb894c9d | 17290 | @deftypefun void glPolygonStipple pattern |
3c9b6116 AW |
17291 | Set the polygon stippling pattern. |
17292 | ||
8925f36f AW |
17293 | @table @asis |
17294 | @item @var{pattern} | |
3c9b6116 AW |
17295 | Specifies a pointer to a @r{32×32} stipple pattern that will be unpacked |
17296 | from memory in the same way that @code{glDrawPixels} unpacks pixels. | |
8925f36f AW |
17297 | |
17298 | @end table | |
17299 | ||
8925f36f AW |
17300 | Polygon stippling, like line stippling (see @code{glLineStipple}), masks |
17301 | out certain fragments produced by rasterization, creating a pattern. | |
17302 | Stippling is independent of polygon antialiasing. | |
17303 | ||
3c9b6116 AW |
17304 | @var{pattern} is a pointer to a @r{32×32} stipple pattern that is stored |
17305 | in memory just like the pixel data supplied to a @code{glDrawPixels} | |
17306 | call with height and @var{width} both equal to 32, a pixel format of | |
c7b31271 | 17307 | @code{GL_COLOR_INDEX}, and data type of @code{GL_BITMAP}. That is, the |
3c9b6116 | 17308 | stipple pattern is represented as a @r{32×32} array of 1-bit color |
c7b31271 | 17309 | indices packed in unsigned bytes. @code{glPixelStore} parameters like |
3c9b6116 | 17310 | @code{GL_UNPACK_SWAP_BYTES} and @code{GL_UNPACK_LSB_FIRST} affect the |
c7b31271 DH |
17311 | assembling of the bits into a stipple pattern. Pixel transfer |
17312 | operations (shift, offset, pixel map) are not applied to the stipple | |
17313 | image, however. | |
8925f36f AW |
17314 | |
17315 | If a non-zero named buffer object is bound to the | |
17316 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
17317 | stipple pattern is specified, @var{pattern} is treated as a byte offset | |
17318 | into the buffer object's data store. | |
17319 | ||
17320 | To enable and disable polygon stippling, call @code{glEnable} and | |
c7b31271 DH |
17321 | @code{glDisable} with argument @code{GL_POLYGON_STIPPLE}. Polygon |
17322 | stippling is initially disabled. If it's enabled, a rasterized polygon | |
3c9b6116 AW |
17323 | fragment with window coordinates @r{@var{x}_@var{w}} and |
17324 | @r{@var{y}_@var{w}} is sent to the next stage of the GL if and only if | |
17325 | the (@r{@var{x}_@var{w}%32})th bit in the (@r{@var{y}_@var{w}%32})th row | |
c7b31271 | 17326 | of the stipple pattern is 1 (one). When polygon stippling is disabled, |
3c9b6116 AW |
17327 | it is as if the stipple pattern consists of all 1's. |
17328 | ||
8925f36f AW |
17329 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object |
17330 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
17331 | object's data store is currently mapped. | |
17332 | ||
17333 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
17334 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
17335 | would be unpacked from the buffer object such that the memory reads | |
17336 | required would exceed the data store size. | |
17337 | ||
17338 | @code{GL_INVALID_OPERATION} is generated if @code{glPolygonStipple} is | |
17339 | executed between the execution of @code{glBegin} and the corresponding | |
17340 | execution of @code{glEnd}. | |
17341 | ||
bb894c9d | 17342 | @end deftypefun |
8925f36f | 17343 | |
bb894c9d | 17344 | @deftypefun void glPrioritizeTextures n textures priorities |
3c9b6116 AW |
17345 | Set texture residence priority. |
17346 | ||
8925f36f AW |
17347 | @table @asis |
17348 | @item @var{n} | |
17349 | Specifies the number of textures to be prioritized. | |
17350 | ||
17351 | @item @var{textures} | |
17352 | Specifies an array containing the names of the textures to be | |
17353 | prioritized. | |
17354 | ||
17355 | @item @var{priorities} | |
c7b31271 | 17356 | Specifies an array containing the texture priorities. A priority given |
8925f36f AW |
17357 | in an element of @var{priorities} applies to the texture named by the |
17358 | corresponding element of @var{textures}. | |
17359 | ||
17360 | @end table | |
17361 | ||
8925f36f AW |
17362 | @code{glPrioritizeTextures} assigns the @var{n} texture priorities given |
17363 | in @var{priorities} to the @var{n} textures named in @var{textures}. | |
17364 | ||
17365 | The GL establishes a ``working set'' of textures that are resident in | |
c7b31271 DH |
17366 | texture memory. These textures may be bound to a texture target much |
17367 | more efficiently than textures that are not resident. By specifying a | |
8925f36f AW |
17368 | priority for each texture, @code{glPrioritizeTextures} allows |
17369 | applications to guide the GL implementation in determining which | |
17370 | textures should be resident. | |
17371 | ||
17372 | The priorities given in @var{priorities} are clamped to the range | |
c7b31271 DH |
17373 | @r{[0,1]} before they are assigned. 0 indicates the lowest priority; |
17374 | textures with priority 0 are least likely to be resident. 1 indicates | |
8925f36f | 17375 | the highest priority; textures with priority 1 are most likely to be |
c7b31271 DH |
17376 | resident. However, textures are not guaranteed to be resident until |
17377 | they are used. | |
8925f36f AW |
17378 | |
17379 | @code{glPrioritizeTextures} silently ignores attempts to prioritize | |
17380 | texture 0 or any texture name that does not correspond to an existing | |
17381 | texture. | |
17382 | ||
17383 | @code{glPrioritizeTextures} does not require that any of the textures | |
17384 | named by @var{textures} be bound to a texture target. | |
17385 | @code{glTexParameter} may also be used to set a texture's priority, but | |
c7b31271 | 17386 | only if the texture is currently bound. This is the only way to set the |
8925f36f AW |
17387 | priority of a default texture. |
17388 | ||
8925f36f AW |
17389 | @code{GL_INVALID_VALUE} is generated if @var{n} is negative. |
17390 | ||
17391 | @code{GL_INVALID_OPERATION} is generated if @code{glPrioritizeTextures} | |
17392 | is executed between the execution of @code{glBegin} and the | |
17393 | corresponding execution of @code{glEnd}. | |
17394 | ||
bb894c9d | 17395 | @end deftypefun |
8925f36f | 17396 | |
bb894c9d AW |
17397 | @deftypefun void glPushAttrib mask |
17398 | @deftypefunx void glPopAttrib | |
3c9b6116 AW |
17399 | Push and pop the server attribute stack. |
17400 | ||
8925f36f AW |
17401 | @table @asis |
17402 | @item @var{mask} | |
c7b31271 | 17403 | Specifies a mask that indicates which attributes to save. Values for |
8925f36f AW |
17404 | @var{mask} are listed below. |
17405 | ||
17406 | @end table | |
17407 | ||
8925f36f | 17408 | @code{glPushAttrib} takes one argument, a mask that indicates which |
c7b31271 DH |
17409 | groups of state variables to save on the attribute stack. Symbolic |
17410 | constants are used to set bits in the mask. @var{mask} is typically | |
8925f36f | 17411 | constructed by specifying the bitwise-or of several of these constants |
c7b31271 DH |
17412 | together. The special mask @code{GL_ALL_ATTRIB_BITS} can be used to |
17413 | save all stackable states. | |
8925f36f AW |
17414 | |
17415 | The symbolic mask constants and their associated GL state are as follows | |
17416 | (the second column lists which attributes are saved): | |
17417 | ||
17418 | ||
17419 | ||
17420 | @table @asis | |
17421 | @item @code{GL_ACCUM_BUFFER_BIT} | |
17422 | Accumulation buffer clear value | |
17423 | ||
17424 | @item @code{GL_COLOR_BUFFER_BIT} | |
17425 | @code{GL_ALPHA_TEST} enable bit | |
17426 | ||
17427 | @item | |
17428 | Alpha test function and reference value | |
17429 | ||
17430 | @item | |
17431 | @code{GL_BLEND} enable bit | |
17432 | ||
17433 | @item | |
17434 | Blending source and destination functions | |
17435 | ||
17436 | @item | |
17437 | Constant blend color | |
17438 | ||
17439 | @item | |
17440 | Blending equation | |
17441 | ||
17442 | @item | |
17443 | @code{GL_DITHER} enable bit | |
17444 | ||
17445 | @item | |
17446 | @code{GL_DRAW_BUFFER} setting | |
17447 | ||
17448 | @item | |
17449 | @code{GL_COLOR_LOGIC_OP} enable bit | |
17450 | ||
17451 | @item | |
17452 | @code{GL_INDEX_LOGIC_OP} enable bit | |
17453 | ||
17454 | @item | |
17455 | Logic op function | |
17456 | ||
17457 | @item | |
17458 | Color mode and index mode clear values | |
17459 | ||
17460 | @item | |
17461 | Color mode and index mode writemasks | |
17462 | ||
17463 | @item @code{GL_CURRENT_BIT} | |
17464 | Current RGBA color | |
17465 | ||
17466 | @item | |
17467 | Current color index | |
17468 | ||
17469 | @item | |
17470 | Current normal vector | |
17471 | ||
17472 | @item | |
17473 | Current texture coordinates | |
17474 | ||
17475 | @item | |
17476 | Current raster position | |
17477 | ||
17478 | @item | |
17479 | @code{GL_CURRENT_RASTER_POSITION_VALID} flag | |
17480 | ||
17481 | @item | |
17482 | RGBA color associated with current raster position | |
17483 | ||
17484 | @item | |
17485 | Color index associated with current raster position | |
17486 | ||
17487 | @item | |
17488 | Texture coordinates associated with current raster position | |
17489 | ||
17490 | @item | |
17491 | @code{GL_EDGE_FLAG} flag | |
17492 | ||
17493 | @item @code{GL_DEPTH_BUFFER_BIT} | |
17494 | @code{GL_DEPTH_TEST} enable bit | |
17495 | ||
17496 | @item | |
17497 | Depth buffer test function | |
17498 | ||
17499 | @item | |
17500 | Depth buffer clear value | |
17501 | ||
17502 | @item | |
17503 | @code{GL_DEPTH_WRITEMASK} enable bit | |
17504 | ||
17505 | @item @code{GL_ENABLE_BIT} | |
17506 | @code{GL_ALPHA_TEST} flag | |
17507 | ||
17508 | @item | |
17509 | @code{GL_AUTO_NORMAL} flag | |
17510 | ||
17511 | @item | |
17512 | @code{GL_BLEND} flag | |
17513 | ||
17514 | @item | |
17515 | Enable bits for the user-definable clipping planes | |
17516 | ||
17517 | @item | |
17518 | @code{GL_COLOR_MATERIAL} | |
17519 | ||
17520 | @item | |
17521 | @code{GL_CULL_FACE} flag | |
17522 | ||
17523 | @item | |
17524 | @code{GL_DEPTH_TEST} flag | |
17525 | ||
17526 | @item | |
17527 | @code{GL_DITHER} flag | |
17528 | ||
17529 | @item | |
17530 | @code{GL_FOG} flag | |
17531 | ||
17532 | @item | |
17533 | @code{GL_LIGHT}@var{i} where @code{0} <= @var{i} < @code{GL_MAX_LIGHTS} | |
17534 | ||
17535 | @item | |
17536 | @code{GL_LIGHTING} flag | |
17537 | ||
17538 | @item | |
17539 | @code{GL_LINE_SMOOTH} flag | |
17540 | ||
17541 | @item | |
17542 | @code{GL_LINE_STIPPLE} flag | |
17543 | ||
17544 | @item | |
17545 | @code{GL_COLOR_LOGIC_OP} flag | |
17546 | ||
17547 | @item | |
17548 | @code{GL_INDEX_LOGIC_OP} flag | |
17549 | ||
17550 | @item | |
17551 | @code{GL_MAP1_}@var{x} where @var{x} is a map type | |
17552 | ||
17553 | @item | |
17554 | @code{GL_MAP2_}@var{x} where @var{x} is a map type | |
17555 | ||
17556 | @item | |
17557 | @code{GL_MULTISAMPLE} flag | |
17558 | ||
17559 | @item | |
17560 | @code{GL_NORMALIZE} flag | |
17561 | ||
17562 | @item | |
17563 | @code{GL_POINT_SMOOTH} flag | |
17564 | ||
17565 | @item | |
17566 | @code{GL_POLYGON_OFFSET_LINE} flag | |
17567 | ||
17568 | @item | |
17569 | @code{GL_POLYGON_OFFSET_FILL} flag | |
17570 | ||
17571 | @item | |
17572 | @code{GL_POLYGON_OFFSET_POINT} flag | |
17573 | ||
17574 | @item | |
17575 | @code{GL_POLYGON_SMOOTH} flag | |
17576 | ||
17577 | @item | |
17578 | @code{GL_POLYGON_STIPPLE} flag | |
17579 | ||
17580 | @item | |
17581 | @code{GL_SAMPLE_ALPHA_TO_COVERAGE} flag | |
17582 | ||
17583 | @item | |
17584 | @code{GL_SAMPLE_ALPHA_TO_ONE} flag | |
17585 | ||
17586 | @item | |
17587 | @code{GL_SAMPLE_COVERAGE} flag | |
17588 | ||
17589 | @item | |
17590 | @code{GL_SCISSOR_TEST} flag | |
17591 | ||
17592 | @item | |
17593 | @code{GL_STENCIL_TEST} flag | |
17594 | ||
17595 | @item | |
17596 | @code{GL_TEXTURE_1D} flag | |
17597 | ||
17598 | @item | |
17599 | @code{GL_TEXTURE_2D} flag | |
17600 | ||
17601 | @item | |
17602 | @code{GL_TEXTURE_3D} flag | |
17603 | ||
17604 | @item | |
17605 | Flags @code{GL_TEXTURE_GEN_}@var{x} where @var{x} is S, T, R, or Q | |
17606 | ||
17607 | @item @code{GL_EVAL_BIT} | |
17608 | @code{GL_MAP1_}@var{x} enable bits, where @var{x} is a map type | |
17609 | ||
17610 | @item | |
17611 | @code{GL_MAP2_}@var{x} enable bits, where @var{x} is a map type | |
17612 | ||
17613 | @item | |
17614 | 1D grid endpoints and divisions | |
17615 | ||
17616 | @item | |
17617 | 2D grid endpoints and divisions | |
17618 | ||
17619 | @item | |
17620 | @code{GL_AUTO_NORMAL} enable bit | |
17621 | ||
17622 | @item @code{GL_FOG_BIT} | |
17623 | @code{GL_FOG} enable bit | |
17624 | ||
17625 | @item | |
17626 | Fog color | |
17627 | ||
17628 | @item | |
17629 | Fog density | |
17630 | ||
17631 | @item | |
17632 | Linear fog start | |
17633 | ||
17634 | @item | |
17635 | Linear fog end | |
17636 | ||
17637 | @item | |
17638 | Fog index | |
17639 | ||
17640 | @item | |
17641 | @code{GL_FOG_MODE} value | |
17642 | ||
17643 | @item @code{GL_HINT_BIT} | |
17644 | @code{GL_PERSPECTIVE_CORRECTION_HINT} setting | |
17645 | ||
17646 | @item | |
17647 | @code{GL_POINT_SMOOTH_HINT} setting | |
17648 | ||
17649 | @item | |
17650 | @code{GL_LINE_SMOOTH_HINT} setting | |
17651 | ||
17652 | @item | |
17653 | @code{GL_POLYGON_SMOOTH_HINT} setting | |
17654 | ||
17655 | @item | |
17656 | @code{GL_FOG_HINT} setting | |
17657 | ||
17658 | @item | |
17659 | @code{GL_GENERATE_MIPMAP_HINT} setting | |
17660 | ||
17661 | @item | |
17662 | @code{GL_TEXTURE_COMPRESSION_HINT} setting | |
17663 | ||
17664 | @item @code{GL_LIGHTING_BIT} | |
17665 | @code{GL_COLOR_MATERIAL} enable bit | |
17666 | ||
17667 | @item | |
17668 | @code{GL_COLOR_MATERIAL_FACE} value | |
17669 | ||
17670 | @item | |
17671 | Color material parameters that are tracking the current color | |
17672 | ||
17673 | @item | |
17674 | Ambient scene color | |
17675 | ||
17676 | @item | |
17677 | @code{GL_LIGHT_MODEL_LOCAL_VIEWER} value | |
17678 | ||
17679 | @item | |
17680 | @code{GL_LIGHT_MODEL_TWO_SIDE} setting | |
17681 | ||
17682 | @item | |
17683 | @code{GL_LIGHTING} enable bit | |
17684 | ||
17685 | @item | |
17686 | Enable bit for each light | |
17687 | ||
17688 | @item | |
17689 | Ambient, diffuse, and specular intensity for each light | |
17690 | ||
17691 | @item | |
17692 | Direction, position, exponent, and cutoff angle for each light | |
17693 | ||
17694 | @item | |
17695 | Constant, linear, and quadratic attenuation factors for each light | |
17696 | ||
17697 | @item | |
17698 | Ambient, diffuse, specular, and emissive color for each material | |
17699 | ||
17700 | @item | |
17701 | Ambient, diffuse, and specular color indices for each material | |
17702 | ||
17703 | @item | |
17704 | Specular exponent for each material | |
17705 | ||
17706 | @item | |
17707 | @code{GL_SHADE_MODEL} setting | |
17708 | ||
17709 | @item @code{GL_LINE_BIT} | |
17710 | @code{GL_LINE_SMOOTH} flag | |
17711 | ||
17712 | @item | |
17713 | @code{GL_LINE_STIPPLE} enable bit | |
17714 | ||
17715 | @item | |
17716 | Line stipple pattern and repeat counter | |
17717 | ||
17718 | @item | |
17719 | Line width | |
17720 | ||
17721 | @item @code{GL_LIST_BIT} | |
17722 | @code{GL_LIST_BASE} setting | |
17723 | ||
17724 | @item @code{GL_MULTISAMPLE_BIT} | |
17725 | @code{GL_MULTISAMPLE} flag | |
17726 | ||
17727 | @item | |
17728 | @code{GL_SAMPLE_ALPHA_TO_COVERAGE} flag | |
17729 | ||
17730 | @item | |
17731 | @code{GL_SAMPLE_ALPHA_TO_ONE} flag | |
17732 | ||
17733 | @item | |
17734 | @code{GL_SAMPLE_COVERAGE} flag | |
17735 | ||
17736 | @item | |
17737 | @code{GL_SAMPLE_COVERAGE_VALUE} value | |
17738 | ||
17739 | @item | |
17740 | @code{GL_SAMPLE_COVERAGE_INVERT} value | |
17741 | ||
17742 | @item @code{GL_PIXEL_MODE_BIT} | |
17743 | @code{GL_RED_BIAS} and @code{GL_RED_SCALE} settings | |
17744 | ||
17745 | @item | |
17746 | @code{GL_GREEN_BIAS} and @code{GL_GREEN_SCALE} values | |
17747 | ||
17748 | @item | |
17749 | @code{GL_BLUE_BIAS} and @code{GL_BLUE_SCALE} | |
17750 | ||
17751 | @item | |
17752 | @code{GL_ALPHA_BIAS} and @code{GL_ALPHA_SCALE} | |
17753 | ||
17754 | @item | |
17755 | @code{GL_DEPTH_BIAS} and @code{GL_DEPTH_SCALE} | |
17756 | ||
17757 | @item | |
17758 | @code{GL_INDEX_OFFSET} and @code{GL_INDEX_SHIFT} values | |
17759 | ||
17760 | @item | |
17761 | @code{GL_MAP_COLOR} and @code{GL_MAP_STENCIL} flags | |
17762 | ||
17763 | @item | |
17764 | @code{GL_ZOOM_X} and @code{GL_ZOOM_Y} factors | |
17765 | ||
17766 | @item | |
17767 | @code{GL_READ_BUFFER} setting | |
17768 | ||
17769 | @item @code{GL_POINT_BIT} | |
17770 | @code{GL_POINT_SMOOTH} flag | |
17771 | ||
17772 | @item | |
17773 | Point size | |
17774 | ||
17775 | @item @code{GL_POLYGON_BIT} | |
17776 | @code{GL_CULL_FACE} enable bit | |
17777 | ||
17778 | @item | |
17779 | @code{GL_CULL_FACE_MODE} value | |
17780 | ||
17781 | @item | |
17782 | @code{GL_FRONT_FACE} indicator | |
17783 | ||
17784 | @item | |
17785 | @code{GL_POLYGON_MODE} setting | |
17786 | ||
17787 | @item | |
17788 | @code{GL_POLYGON_SMOOTH} flag | |
17789 | ||
17790 | @item | |
17791 | @code{GL_POLYGON_STIPPLE} enable bit | |
17792 | ||
17793 | @item | |
17794 | @code{GL_POLYGON_OFFSET_FILL} flag | |
17795 | ||
17796 | @item | |
17797 | @code{GL_POLYGON_OFFSET_LINE} flag | |
17798 | ||
17799 | @item | |
17800 | @code{GL_POLYGON_OFFSET_POINT} flag | |
17801 | ||
17802 | @item | |
17803 | @code{GL_POLYGON_OFFSET_FACTOR} | |
17804 | ||
17805 | @item | |
17806 | @code{GL_POLYGON_OFFSET_UNITS} | |
17807 | ||
17808 | @item @code{GL_POLYGON_STIPPLE_BIT} | |
17809 | Polygon stipple image | |
17810 | ||
17811 | @item @code{GL_SCISSOR_BIT} | |
17812 | @code{GL_SCISSOR_TEST} flag | |
17813 | ||
17814 | @item | |
17815 | Scissor box | |
17816 | ||
17817 | @item @code{GL_STENCIL_BUFFER_BIT} | |
17818 | @code{GL_STENCIL_TEST} enable bit | |
17819 | ||
17820 | @item | |
17821 | Stencil function and reference value | |
17822 | ||
17823 | @item | |
17824 | Stencil value mask | |
17825 | ||
17826 | @item | |
17827 | Stencil fail, pass, and depth buffer pass actions | |
17828 | ||
17829 | @item | |
17830 | Stencil buffer clear value | |
17831 | ||
17832 | @item | |
17833 | Stencil buffer writemask | |
17834 | ||
17835 | @item @code{GL_TEXTURE_BIT} | |
17836 | Enable bits for the four texture coordinates | |
17837 | ||
17838 | @item | |
17839 | Border color for each texture image | |
17840 | ||
17841 | @item | |
17842 | Minification function for each texture image | |
17843 | ||
17844 | @item | |
17845 | Magnification function for each texture image | |
17846 | ||
17847 | @item | |
17848 | Texture coordinates and wrap mode for each texture image | |
17849 | ||
17850 | @item | |
17851 | Color and mode for each texture environment | |
17852 | ||
17853 | @item | |
17854 | Enable bits @code{GL_TEXTURE_GEN_}@var{x}, @var{x} is S, T, R, and Q | |
17855 | ||
17856 | @item | |
17857 | @code{GL_TEXTURE_GEN_MODE} setting for S, T, R, and Q | |
17858 | ||
17859 | @item | |
17860 | @code{glTexGen} plane equations for S, T, R, and Q | |
17861 | ||
17862 | @item | |
17863 | Current texture bindings (for example, @code{GL_TEXTURE_BINDING_2D}) | |
17864 | ||
17865 | @item @code{GL_TRANSFORM_BIT} | |
17866 | Coefficients of the six clipping planes | |
17867 | ||
17868 | @item | |
17869 | Enable bits for the user-definable clipping planes | |
17870 | ||
17871 | @item | |
17872 | @code{GL_MATRIX_MODE} value | |
17873 | ||
17874 | @item | |
17875 | @code{GL_NORMALIZE} flag | |
17876 | ||
17877 | @item | |
17878 | @code{GL_RESCALE_NORMAL} flag | |
17879 | ||
17880 | @item @code{GL_VIEWPORT_BIT} | |
17881 | Depth range (near and far) | |
17882 | ||
17883 | @item | |
17884 | Viewport origin and extent | |
17885 | ||
17886 | @end table | |
17887 | ||
17888 | @code{glPopAttrib} restores the values of the state variables saved with | |
c7b31271 | 17889 | the last @code{glPushAttrib} command. Those not saved are left |
8925f36f AW |
17890 | unchanged. |
17891 | ||
17892 | It is an error to push attributes onto a full stack or to pop attributes | |
c7b31271 | 17893 | off an empty stack. In either case, the error flag is set and no other |
8925f36f AW |
17894 | change is made to GL state. |
17895 | ||
17896 | Initially, the attribute stack is empty. | |
17897 | ||
8925f36f AW |
17898 | @code{GL_STACK_OVERFLOW} is generated if @code{glPushAttrib} is called |
17899 | while the attribute stack is full. | |
17900 | ||
17901 | @code{GL_STACK_UNDERFLOW} is generated if @code{glPopAttrib} is called | |
17902 | while the attribute stack is empty. | |
17903 | ||
17904 | @code{GL_INVALID_OPERATION} is generated if @code{glPushAttrib} or | |
17905 | @code{glPopAttrib} is executed between the execution of @code{glBegin} | |
17906 | and the corresponding execution of @code{glEnd}. | |
17907 | ||
bb894c9d | 17908 | @end deftypefun |
8925f36f | 17909 | |
bb894c9d AW |
17910 | @deftypefun void glPushClientAttrib mask |
17911 | @deftypefunx void glPopClientAttrib | |
3c9b6116 AW |
17912 | Push and pop the client attribute stack. |
17913 | ||
8925f36f AW |
17914 | @table @asis |
17915 | @item @var{mask} | |
c7b31271 | 17916 | Specifies a mask that indicates which attributes to save. Values for |
8925f36f AW |
17917 | @var{mask} are listed below. |
17918 | ||
17919 | @end table | |
17920 | ||
8925f36f AW |
17921 | @code{glPushClientAttrib} takes one argument, a mask that indicates |
17922 | which groups of client-state variables to save on the client attribute | |
c7b31271 | 17923 | stack. Symbolic constants are used to set bits in the mask. @var{mask} |
8925f36f | 17924 | is typically constructed by specifying the bitwise-or of several of |
c7b31271 | 17925 | these constants together. The special mask |
8925f36f AW |
17926 | @code{GL_CLIENT_ALL_ATTRIB_BITS} can be used to save all stackable |
17927 | client state. | |
17928 | ||
17929 | The symbolic mask constants and their associated GL client state are as | |
17930 | follows (the second column lists which attributes are saved): | |
17931 | ||
17932 | @code{GL_CLIENT_PIXEL_STORE_BIT} Pixel storage modes | |
17933 | @code{GL_CLIENT_VERTEX_ARRAY_BIT} Vertex arrays (and enables) | |
17934 | ||
17935 | @code{glPopClientAttrib} restores the values of the client-state | |
c7b31271 DH |
17936 | variables saved with the last @code{glPushClientAttrib}. Those not |
17937 | saved are left unchanged. | |
8925f36f AW |
17938 | |
17939 | It is an error to push attributes onto a full client attribute stack or | |
c7b31271 | 17940 | to pop attributes off an empty stack. In either case, the error flag is |
8925f36f AW |
17941 | set, and no other change is made to GL state. |
17942 | ||
17943 | Initially, the client attribute stack is empty. | |
17944 | ||
8925f36f AW |
17945 | @code{GL_STACK_OVERFLOW} is generated if @code{glPushClientAttrib} is |
17946 | called while the attribute stack is full. | |
17947 | ||
17948 | @code{GL_STACK_UNDERFLOW} is generated if @code{glPopClientAttrib} is | |
17949 | called while the attribute stack is empty. | |
17950 | ||
bb894c9d | 17951 | @end deftypefun |
8925f36f | 17952 | |
bb894c9d AW |
17953 | @deftypefun void glPushMatrix |
17954 | @deftypefunx void glPopMatrix | |
3c9b6116 AW |
17955 | Push and pop the current matrix stack. |
17956 | ||
c7b31271 DH |
17957 | There is a stack of matrices for each of the matrix modes. In |
17958 | @code{GL_MODELVIEW} mode, the stack depth is at least 32. In the other | |
8925f36f | 17959 | modes, @code{GL_COLOR}, @code{GL_PROJECTION}, and @code{GL_TEXTURE}, the |
c7b31271 DH |
17960 | depth is at least 2. The current matrix in any mode is the matrix on |
17961 | the top of the stack for that mode. | |
8925f36f AW |
17962 | |
17963 | @code{glPushMatrix} pushes the current matrix stack down by one, | |
c7b31271 | 17964 | duplicating the current matrix. That is, after a @code{glPushMatrix} |
8925f36f AW |
17965 | call, the matrix on top of the stack is identical to the one below it. |
17966 | ||
17967 | @code{glPopMatrix} pops the current matrix stack, replacing the current | |
17968 | matrix with the one below it on the stack. | |
17969 | ||
17970 | Initially, each of the stacks contains one matrix, an identity matrix. | |
17971 | ||
17972 | It is an error to push a full matrix stack or to pop a matrix stack that | |
c7b31271 DH |
17973 | contains only a single matrix. In either case, the error flag is set |
17974 | and no other change is made to GL state. | |
8925f36f | 17975 | |
8925f36f AW |
17976 | @code{GL_STACK_OVERFLOW} is generated if @code{glPushMatrix} is called |
17977 | while the current matrix stack is full. | |
17978 | ||
17979 | @code{GL_STACK_UNDERFLOW} is generated if @code{glPopMatrix} is called | |
17980 | while the current matrix stack contains only a single matrix. | |
17981 | ||
17982 | @code{GL_INVALID_OPERATION} is generated if @code{glPushMatrix} or | |
17983 | @code{glPopMatrix} is executed between the execution of @code{glBegin} | |
17984 | and the corresponding execution of @code{glEnd}. | |
17985 | ||
bb894c9d | 17986 | @end deftypefun |
8925f36f | 17987 | |
bb894c9d AW |
17988 | @deftypefun void glPushName name |
17989 | @deftypefunx void glPopName | |
3c9b6116 AW |
17990 | Push and pop the name stack. |
17991 | ||
8925f36f AW |
17992 | @table @asis |
17993 | @item @var{name} | |
17994 | Specifies a name that will be pushed onto the name stack. | |
17995 | ||
17996 | @end table | |
17997 | ||
8925f36f | 17998 | The name stack is used during selection mode to allow sets of rendering |
c7b31271 | 17999 | commands to be uniquely identified. It consists of an ordered set of |
8925f36f AW |
18000 | unsigned integers and is initially empty. |
18001 | ||
18002 | @code{glPushName} causes @var{name} to be pushed onto the name stack. | |
18003 | @code{glPopName} pops one name off the top of the stack. | |
18004 | ||
18005 | The maximum name stack depth is implementation-dependent; call | |
18006 | @code{GL_MAX_NAME_STACK_DEPTH} to find out the value for a particular | |
c7b31271 DH |
18007 | implementation. It is an error to push a name onto a full stack or to |
18008 | pop a name off an empty stack. It is also an error to manipulate the | |
8925f36f | 18009 | name stack between the execution of @code{glBegin} and the corresponding |
c7b31271 | 18010 | execution of @code{glEnd}. In any of these cases, the error flag is set |
8925f36f AW |
18011 | and no other change is made to GL state. |
18012 | ||
18013 | The name stack is always empty while the render mode is not | |
c7b31271 | 18014 | @code{GL_SELECT}. Calls to @code{glPushName} or @code{glPopName} while |
8925f36f AW |
18015 | the render mode is not @code{GL_SELECT} are ignored. |
18016 | ||
8925f36f AW |
18017 | @code{GL_STACK_OVERFLOW} is generated if @code{glPushName} is called |
18018 | while the name stack is full. | |
18019 | ||
18020 | @code{GL_STACK_UNDERFLOW} is generated if @code{glPopName} is called | |
18021 | while the name stack is empty. | |
18022 | ||
18023 | @code{GL_INVALID_OPERATION} is generated if @code{glPushName} or | |
18024 | @code{glPopName} is executed between a call to @code{glBegin} and the | |
18025 | corresponding call to @code{glEnd}. | |
18026 | ||
bb894c9d | 18027 | @end deftypefun |
8925f36f | 18028 | |
d172eed9 AW |
18029 | @deftypefun void glRasterPos2s x y |
18030 | @deftypefunx void glRasterPos2i x y | |
ca09631c | 18031 | @deftypefunx void glRasterPos2f x y |
d172eed9 AW |
18032 | @deftypefunx void glRasterPos2d x y |
18033 | @deftypefunx void glRasterPos3s x y z | |
bb894c9d | 18034 | @deftypefunx void glRasterPos3i x y z |
ca09631c | 18035 | @deftypefunx void glRasterPos3f x y z |
d172eed9 AW |
18036 | @deftypefunx void glRasterPos3d x y z |
18037 | @deftypefunx void glRasterPos4s x y z w | |
bb894c9d | 18038 | @deftypefunx void glRasterPos4i x y z w |
ca09631c | 18039 | @deftypefunx void glRasterPos4f x y z w |
d172eed9 AW |
18040 | @deftypefunx void glRasterPos4d x y z w |
18041 | @deftypefunx void glRasterPos2sv v | |
18042 | @deftypefunx void glRasterPos2iv v | |
18043 | @deftypefunx void glRasterPos2fv v | |
18044 | @deftypefunx void glRasterPos2dv v | |
18045 | @deftypefunx void glRasterPos3sv v | |
18046 | @deftypefunx void glRasterPos3iv v | |
18047 | @deftypefunx void glRasterPos3fv v | |
18048 | @deftypefunx void glRasterPos3dv v | |
18049 | @deftypefunx void glRasterPos4sv v | |
18050 | @deftypefunx void glRasterPos4iv v | |
18051 | @deftypefunx void glRasterPos4fv v | |
18052 | @deftypefunx void glRasterPos4dv v | |
3c9b6116 AW |
18053 | Specify the raster position for pixel operations. |
18054 | ||
8925f36f AW |
18055 | @table @asis |
18056 | @item @var{x} | |
18057 | @itemx @var{y} | |
18058 | @itemx @var{z} | |
18059 | @itemx @var{w} | |
3c9b6116 AW |
18060 | Specify the @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}} |
18061 | object coordinates (if present) for the raster position. | |
8925f36f AW |
18062 | |
18063 | @end table | |
18064 | ||
c7b31271 | 18065 | The GL maintains a 3D position in window coordinates. This position, |
8925f36f | 18066 | called the raster position, is used to position pixel and bitmap write |
c7b31271 | 18067 | operations. It is maintained with subpixel accuracy. See |
8925f36f AW |
18068 | @code{glBitmap}, @code{glDrawPixels}, and @code{glCopyPixels}. |
18069 | ||
18070 | The current raster position consists of three window coordinates | |
3c9b6116 AW |
18071 | (@r{@var{x}}, @r{@var{y}}, @r{@var{z}}), a clip coordinate value |
18072 | (@r{@var{w}}), an eye coordinate distance, a valid bit, and associated | |
c7b31271 DH |
18073 | color data and texture coordinates. The @r{@var{w}} coordinate is a |
18074 | clip coordinate, because @r{@var{w}} is not projected to window | |
18075 | coordinates. @code{glRasterPos4} specifies object coordinates | |
18076 | @r{@var{x}}, @r{@var{y}}, @r{@var{z}}, and @r{@var{w}} explicitly. | |
3c9b6116 AW |
18077 | @code{glRasterPos3} specifies object coordinate @r{@var{x}}, |
18078 | @r{@var{y}}, and @r{@var{z}} explicitly, while @r{@var{w}} is implicitly | |
c7b31271 | 18079 | set to 1. @code{glRasterPos2} uses the argument values for @r{@var{x}} |
3c9b6116 AW |
18080 | and @r{@var{y}} while implicitly setting @r{@var{z}} and @r{@var{w}} to |
18081 | 0 and 1. | |
8925f36f AW |
18082 | |
18083 | The object coordinates presented by @code{glRasterPos} are treated just | |
18084 | like those of a @code{glVertex} command: They are transformed by the | |
18085 | current modelview and projection matrices and passed to the clipping | |
c7b31271 | 18086 | stage. If the vertex is not culled, then it is projected and scaled to |
8925f36f | 18087 | window coordinates, which become the new current raster position, and |
c7b31271 | 18088 | the @code{GL_CURRENT_RASTER_POSITION_VALID} flag is set. If the vertex |
8925f36f AW |
18089 | @var{is} culled, then the valid bit is cleared and the current raster |
18090 | position and associated color and texture coordinates are undefined. | |
18091 | ||
18092 | The current raster position also includes some associated color data and | |
c7b31271 | 18093 | texture coordinates. If lighting is enabled, then |
8925f36f AW |
18094 | @code{GL_CURRENT_RASTER_COLOR} (in RGBA mode) or |
18095 | @code{GL_CURRENT_RASTER_INDEX} (in color index mode) is set to the color | |
18096 | produced by the lighting calculation (see @code{glLight}, | |
c7b31271 | 18097 | @code{glLightModel}, and @code{glShadeModel}). If lighting is disabled, |
8925f36f AW |
18098 | current color (in RGBA mode, state variable @code{GL_CURRENT_COLOR}) or |
18099 | color index (in color index mode, state variable | |
18100 | @code{GL_CURRENT_INDEX}) is used to update the current raster color. | |
18101 | @code{GL_CURRENT_RASTER_SECONDARY_COLOR} (in RGBA mode) is likewise | |
18102 | updated. | |
18103 | ||
18104 | Likewise, @code{GL_CURRENT_RASTER_TEXTURE_COORDS} is updated as a | |
18105 | function of @code{GL_CURRENT_TEXTURE_COORDS}, based on the texture | |
18106 | matrix and the texture generation functions (see @code{glTexGen}). | |
18107 | Finally, the distance from the origin of the eye coordinate system to | |
18108 | the vertex as transformed by only the modelview matrix replaces | |
18109 | @code{GL_CURRENT_RASTER_DISTANCE}. | |
18110 | ||
18111 | Initially, the current raster position is (0, 0, 0, 1), the current | |
18112 | raster distance is 0, the valid bit is set, the associated RGBA color is | |
18113 | (1, 1, 1, 1), the associated color index is 1, and the associated | |
c7b31271 | 18114 | texture coordinates are (0, 0, 0, 1). In RGBA mode, |
8925f36f AW |
18115 | @code{GL_CURRENT_RASTER_INDEX} is always 1; in color index mode, the |
18116 | current raster RGBA color always maintains its initial value. | |
18117 | ||
8925f36f AW |
18118 | @code{GL_INVALID_OPERATION} is generated if @code{glRasterPos} is |
18119 | executed between the execution of @code{glBegin} and the corresponding | |
18120 | execution of @code{glEnd}. | |
18121 | ||
bb894c9d | 18122 | @end deftypefun |
8925f36f | 18123 | |
bb894c9d | 18124 | @deftypefun void glReadBuffer mode |
3c9b6116 AW |
18125 | Select a color buffer source for pixels. |
18126 | ||
8925f36f AW |
18127 | @table @asis |
18128 | @item @var{mode} | |
c7b31271 | 18129 | Specifies a color buffer. Accepted values are @code{GL_FRONT_LEFT}, |
8925f36f AW |
18130 | @code{GL_FRONT_RIGHT}, @code{GL_BACK_LEFT}, @code{GL_BACK_RIGHT}, |
18131 | @code{GL_FRONT}, @code{GL_BACK}, @code{GL_LEFT}, @code{GL_RIGHT}, and | |
18132 | @code{GL_AUX}@var{i}, where @var{i} is between 0 and the value of | |
18133 | @code{GL_AUX_BUFFERS} minus 1. | |
18134 | ||
18135 | @end table | |
18136 | ||
8925f36f AW |
18137 | @code{glReadBuffer} specifies a color buffer as the source for |
18138 | subsequent @code{glReadPixels}, @code{glCopyTexImage1D}, | |
18139 | @code{glCopyTexImage2D}, @code{glCopyTexSubImage1D}, | |
18140 | @code{glCopyTexSubImage2D}, @code{glCopyTexSubImage3D}, and | |
c7b31271 DH |
18141 | @code{glCopyPixels} commands. @var{mode} accepts one of twelve or more |
18142 | predefined values. (@code{GL_AUX0} through @code{GL_AUX3} are always | |
8925f36f AW |
18143 | defined.) In a fully configured system, @code{GL_FRONT}, @code{GL_LEFT}, |
18144 | and @code{GL_FRONT_LEFT} all name the front left buffer, | |
18145 | @code{GL_FRONT_RIGHT} and @code{GL_RIGHT} name the front right buffer, | |
18146 | and @code{GL_BACK_LEFT} and @code{GL_BACK} name the back left buffer. | |
18147 | ||
18148 | Nonstereo double-buffered configurations have only a front left and a | |
c7b31271 DH |
18149 | back left buffer. Single-buffered configurations have a front left and |
18150 | a front right buffer if stereo, and only a front left buffer if | |
18151 | nonstereo. It is an error to specify a nonexistent buffer to | |
18152 | @code{glReadBuffer}. | |
8925f36f AW |
18153 | |
18154 | @var{mode} is initially @code{GL_FRONT} in single-buffered | |
18155 | configurations and @code{GL_BACK} in double-buffered configurations. | |
18156 | ||
8925f36f AW |
18157 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of the |
18158 | twelve (or more) accepted values. | |
18159 | ||
18160 | @code{GL_INVALID_OPERATION} is generated if @var{mode} specifies a | |
18161 | buffer that does not exist. | |
18162 | ||
18163 | @code{GL_INVALID_OPERATION} is generated if @code{glReadBuffer} is | |
18164 | executed between the execution of @code{glBegin} and the corresponding | |
18165 | execution of @code{glEnd}. | |
18166 | ||
bb894c9d | 18167 | @end deftypefun |
8925f36f | 18168 | |
bb894c9d | 18169 | @deftypefun void glReadPixels x y width height format type data |
3c9b6116 AW |
18170 | Read a block of pixels from the frame buffer. |
18171 | ||
8925f36f AW |
18172 | @table @asis |
18173 | @item @var{x} | |
18174 | @itemx @var{y} | |
18175 | Specify the window coordinates of the first pixel that is read from the | |
c7b31271 | 18176 | frame buffer. This location is the lower left corner of a rectangular |
8925f36f AW |
18177 | block of pixels. |
18178 | ||
18179 | @item @var{width} | |
18180 | @itemx @var{height} | |
c7b31271 | 18181 | Specify the dimensions of the pixel rectangle. @var{width} and |
8925f36f AW |
18182 | @var{height} of one correspond to a single pixel. |
18183 | ||
18184 | @item @var{format} | |
c7b31271 | 18185 | Specifies the format of the pixel data. The following symbolic values |
8925f36f AW |
18186 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, |
18187 | @code{GL_DEPTH_COMPONENT}, @code{GL_RED}, @code{GL_GREEN}, | |
18188 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
18189 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
18190 | @code{GL_LUMINANCE_ALPHA}. | |
18191 | ||
18192 | @item @var{type} | |
c7b31271 | 18193 | Specifies the data type of the pixel data. Must be one of |
8925f36f AW |
18194 | @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
18195 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
18196 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
18197 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
18198 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
18199 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
18200 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
18201 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
18202 | or @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
18203 | ||
18204 | @item @var{data} | |
18205 | Returns the pixel data. | |
18206 | ||
18207 | @end table | |
18208 | ||
8925f36f AW |
18209 | @code{glReadPixels} returns pixel data from the frame buffer, starting |
18210 | with the pixel whose lower left corner is at location (@var{x}, | |
c7b31271 | 18211 | @var{y}), into client memory starting at location @var{data}. Several |
8925f36f | 18212 | parameters control the processing of the pixel data before it is placed |
c7b31271 DH |
18213 | into client memory. These parameters are set with three commands: |
18214 | @code{glPixelStore}, @code{glPixelTransfer}, and @code{glPixelMap}. This | |
8925f36f AW |
18215 | reference page describes the effects on @code{glReadPixels} of most, but |
18216 | not all of the parameters specified by these three commands. | |
18217 | ||
18218 | If a non-zero named buffer object is bound to the | |
18219 | @code{GL_PIXEL_PACK_BUFFER} target (see @code{glBindBuffer}) while a | |
18220 | block of pixels is requested, @var{data} is treated as a byte offset | |
18221 | into the buffer object's data store rather than a pointer to client | |
18222 | memory. | |
18223 | ||
18224 | When the @code{ARB_imaging} extension is supported, the pixel data may | |
18225 | be processed by additional operations including color table lookup, | |
18226 | color matrix transformations, convolutions, histograms, and minimum and | |
18227 | maximum pixel value computations. | |
18228 | ||
18229 | @code{glReadPixels} returns values from each pixel with lower left | |
3c9b6116 | 18230 | corner at @r{(@var{x}+@var{i},@var{y}+@var{j})} for |
c7b31271 DH |
18231 | @r{0<=@var{i}<@var{width}} and @r{0<=@var{j}<@var{height}}. This pixel |
18232 | is said to be the @r{@var{i}}th pixel in the @r{@var{j}}th row. Pixels | |
3c9b6116 AW |
18233 | are returned in row order from the lowest to the highest row, left to |
18234 | right in each row. | |
8925f36f AW |
18235 | |
18236 | @var{format} specifies the format for the returned pixel values; | |
18237 | accepted values are: | |
18238 | ||
18239 | @table @asis | |
18240 | @item @code{GL_COLOR_INDEX} | |
18241 | Color indices are read from the color buffer selected by | |
c7b31271 | 18242 | @code{glReadBuffer}. Each index is converted to fixed point, shifted |
8925f36f | 18243 | left or right depending on the value and sign of @code{GL_INDEX_SHIFT}, |
c7b31271 | 18244 | and added to @code{GL_INDEX_OFFSET}. If @code{GL_MAP_COLOR} is |
8925f36f AW |
18245 | @code{GL_TRUE}, indices are replaced by their mappings in the table |
18246 | @code{GL_PIXEL_MAP_I_TO_I}. | |
18247 | ||
18248 | @item @code{GL_STENCIL_INDEX} | |
c7b31271 DH |
18249 | Stencil values are read from the stencil buffer. Each index is |
18250 | converted to fixed point, shifted left or right depending on the value | |
18251 | and sign of @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET}. | |
18252 | If @code{GL_MAP_STENCIL} is @code{GL_TRUE}, indices are replaced by | |
18253 | their mappings in the table @code{GL_PIXEL_MAP_S_TO_S}. | |
8925f36f AW |
18254 | |
18255 | @item @code{GL_DEPTH_COMPONENT} | |
c7b31271 DH |
18256 | Depth values are read from the depth buffer. Each component is |
18257 | converted to floating point such that the minimum depth value maps to 0 | |
18258 | and the maximum value maps to 1. Each component is then multiplied by | |
8925f36f | 18259 | @code{GL_DEPTH_SCALE}, added to @code{GL_DEPTH_BIAS}, and finally |
3c9b6116 | 18260 | clamped to the range @r{[0,1]}. |
8925f36f AW |
18261 | |
18262 | @item @code{GL_RED} | |
18263 | @item @code{GL_GREEN} | |
18264 | @item @code{GL_BLUE} | |
18265 | @item @code{GL_ALPHA} | |
18266 | @item @code{GL_RGB} | |
18267 | @item @code{GL_BGR} | |
18268 | @item @code{GL_RGBA} | |
18269 | @item @code{GL_BGRA} | |
18270 | @item @code{GL_LUMINANCE} | |
18271 | @item @code{GL_LUMINANCE_ALPHA} | |
18272 | Processing differs depending on whether color buffers store color | |
c7b31271 DH |
18273 | indices or RGBA color components. If color indices are stored, they are |
18274 | read from the color buffer selected by @code{glReadBuffer}. Each index | |
8925f36f AW |
18275 | is converted to fixed point, shifted left or right depending on the |
18276 | value and sign of @code{GL_INDEX_SHIFT}, and added to | |
c7b31271 | 18277 | @code{GL_INDEX_OFFSET}. Indices are then replaced by the red, green, |
8925f36f AW |
18278 | blue, and alpha values obtained by indexing the tables |
18279 | @code{GL_PIXEL_MAP_I_TO_R}, @code{GL_PIXEL_MAP_I_TO_G}, | |
c7b31271 | 18280 | @code{GL_PIXEL_MAP_I_TO_B}, and @code{GL_PIXEL_MAP_I_TO_A}. Each table |
3c9b6116 | 18281 | must be of size @r{2^@var{n}}, but @r{@var{n}} may be different for |
c7b31271 | 18282 | different tables. Before an index is used to look up a value in a table |
3c9b6116 | 18283 | of size @r{2^@var{n}}, it must be masked against @r{2^@var{n}-1}. |
8925f36f AW |
18284 | |
18285 | If RGBA color components are stored in the color buffers, they are read | |
c7b31271 | 18286 | from the color buffer selected by @code{glReadBuffer}. Each color |
8925f36f | 18287 | component is converted to floating point such that zero intensity maps |
c7b31271 DH |
18288 | to 0.0 and full intensity maps to 1.0. Each component is then |
18289 | multiplied by @code{GL_c_SCALE} and added to @code{GL_c_BIAS}, where | |
18290 | @var{c} is RED, GREEN, BLUE, or ALPHA. Finally, if @code{GL_MAP_COLOR} | |
18291 | is @code{GL_TRUE}, each component is clamped to the range @r{[0,1]}, | |
18292 | scaled to the size of its corresponding table, and is then replaced by | |
18293 | its mapping in the table @code{GL_PIXEL_MAP_c_TO_c}, where @var{c} is R, | |
18294 | G, B, or A. | |
18295 | ||
18296 | Unneeded data is then discarded. For example, @code{GL_RED} discards | |
18297 | the green, blue, and alpha components, while @code{GL_RGB} discards only | |
18298 | the alpha component. @code{GL_LUMINANCE} computes a single-component | |
18299 | value as the sum of the red, green, and blue components, and | |
8925f36f | 18300 | @code{GL_LUMINANCE_ALPHA} does the same, while keeping alpha as a second |
c7b31271 | 18301 | value. The final values are clamped to the range @r{[0,1]}. |
8925f36f AW |
18302 | |
18303 | @end table | |
18304 | ||
18305 | The shift, scale, bias, and lookup factors just described are all | |
c7b31271 | 18306 | specified by @code{glPixelTransfer}. The lookup table contents |
8925f36f AW |
18307 | themselves are specified by @code{glPixelMap}. |
18308 | ||
18309 | Finally, the indices or components are converted to the proper format, | |
c7b31271 | 18310 | as specified by @var{type}. If @var{format} is @code{GL_COLOR_INDEX} or |
8925f36f | 18311 | @code{GL_STENCIL_INDEX} and @var{type} is not @code{GL_FLOAT}, each |
c7b31271 | 18312 | index is masked with the mask value given in the following table. If |
8925f36f AW |
18313 | @var{type} is @code{GL_FLOAT}, then each integer index is converted to |
18314 | single-precision floating-point format. | |
18315 | ||
18316 | If @var{format} is @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, | |
18317 | @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, | |
18318 | @code{GL_BGRA}, @code{GL_LUMINANCE}, or @code{GL_LUMINANCE_ALPHA} and | |
18319 | @var{type} is not @code{GL_FLOAT}, each component is multiplied by the | |
c7b31271 | 18320 | multiplier shown in the following table. If type is @code{GL_FLOAT}, |
8925f36f AW |
18321 | then each component is passed as is (or converted to the client's |
18322 | single-precision floating-point format if it is different from the one | |
18323 | used by the GL). | |
18324 | ||
18325 | ||
18326 | ||
18327 | @table @asis | |
18328 | @item @var{type} | |
18329 | @strong{Index Mask}, @strong{Component Conversion} | |
18330 | ||
18331 | @item @code{GL_UNSIGNED_BYTE} | |
3c9b6116 | 18332 | @r{2^8-1}, @r{(2^8-1,)@var{c}} |
8925f36f AW |
18333 | |
18334 | @item @code{GL_BYTE} | |
3c9b6116 | 18335 | @r{2^7-1}, @r{(2^8-1,)@var{c}-1,/2} |
8925f36f AW |
18336 | |
18337 | @item @code{GL_BITMAP} | |
3c9b6116 | 18338 | @r{1}, @r{1} |
8925f36f AW |
18339 | |
18340 | @item @code{GL_UNSIGNED_SHORT} | |
3c9b6116 | 18341 | @r{2^16-1}, @r{(2^16-1,)@var{c}} |
8925f36f AW |
18342 | |
18343 | @item @code{GL_SHORT} | |
3c9b6116 | 18344 | @r{2^15-1}, @r{(2^16-1,)@var{c}-1,/2} |
8925f36f AW |
18345 | |
18346 | @item @code{GL_UNSIGNED_INT} | |
3c9b6116 | 18347 | @r{2^32-1}, @r{(2^32-1,)@var{c}} |
8925f36f AW |
18348 | |
18349 | @item @code{GL_INT} | |
3c9b6116 | 18350 | @r{2^31-1}, @r{(2^32-1,)@var{c}-1,/2} |
8925f36f AW |
18351 | |
18352 | @item @code{GL_FLOAT} | |
3c9b6116 | 18353 | none , @r{@var{c}} |
8925f36f AW |
18354 | |
18355 | @end table | |
18356 | ||
c7b31271 | 18357 | Return values are placed in memory as follows. If @var{format} is |
8925f36f AW |
18358 | @code{GL_COLOR_INDEX}, @code{GL_STENCIL_INDEX}, |
18359 | @code{GL_DEPTH_COMPONENT}, @code{GL_RED}, @code{GL_GREEN}, | |
18360 | @code{GL_BLUE}, @code{GL_ALPHA}, or @code{GL_LUMINANCE}, a single value | |
3c9b6116 AW |
18361 | is returned and the data for the @r{@var{i}}th pixel in the |
18362 | @r{@var{j}}th row is placed in location | |
c7b31271 | 18363 | @r{(@var{j},)@var{width}+@var{i}}. @code{GL_RGB} and @code{GL_BGR} |
8925f36f AW |
18364 | return three values, @code{GL_RGBA} and @code{GL_BGRA} return four |
18365 | values, and @code{GL_LUMINANCE_ALPHA} returns two values for each pixel, | |
18366 | with all values corresponding to a single pixel occupying contiguous | |
c7b31271 DH |
18367 | space in @var{data}. Storage parameters set by @code{glPixelStore}, |
18368 | such as @code{GL_PACK_LSB_FIRST} and @code{GL_PACK_SWAP_BYTES}, affect | |
18369 | the way that data is written into memory. See @code{glPixelStore} for a | |
8925f36f AW |
18370 | description. |
18371 | ||
8925f36f AW |
18372 | @code{GL_INVALID_ENUM} is generated if @var{format} or @var{type} is not |
18373 | an accepted value. | |
18374 | ||
18375 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
18376 | and @var{format} is not @code{GL_COLOR_INDEX} or | |
18377 | @code{GL_STENCIL_INDEX}. | |
18378 | ||
18379 | @code{GL_INVALID_VALUE} is generated if either @var{width} or | |
18380 | @var{height} is negative. | |
18381 | ||
18382 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
18383 | @code{GL_COLOR_INDEX} and the color buffers store RGBA color components. | |
18384 | ||
18385 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
18386 | @code{GL_STENCIL_INDEX} and there is no stencil buffer. | |
18387 | ||
18388 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
18389 | @code{GL_DEPTH_COMPONENT} and there is no depth buffer. | |
18390 | ||
18391 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
18392 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
18393 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
18394 | and @var{format} is not @code{GL_RGB}. | |
18395 | ||
18396 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
18397 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
18398 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
18399 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
18400 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
18401 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
18402 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
18403 | ||
18404 | The formats @code{GL_BGR}, and @code{GL_BGRA} and types | |
18405 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
18406 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
18407 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
18408 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
18409 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
18410 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
18411 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} are available only if the GL | |
18412 | version is 1.2 or greater. | |
18413 | ||
18414 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
18415 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the buffer | |
18416 | object's data store is currently mapped. | |
18417 | ||
18418 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
18419 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and the data | |
18420 | would be packed to the buffer object such that the memory writes | |
18421 | required would exceed the data store size. | |
18422 | ||
18423 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
18424 | name is bound to the @code{GL_PIXEL_PACK_BUFFER} target and @var{data} | |
18425 | is not evenly divisible into the number of bytes needed to store in | |
18426 | memory a datum indicated by @var{type}. | |
18427 | ||
18428 | @code{GL_INVALID_OPERATION} is generated if @code{glReadPixels} is | |
18429 | executed between the execution of @code{glBegin} and the corresponding | |
18430 | execution of @code{glEnd}. | |
18431 | ||
bb894c9d | 18432 | @end deftypefun |
8925f36f | 18433 | |
d172eed9 AW |
18434 | @deftypefun void glRectd x1 y1 x2 y2 |
18435 | @deftypefunx void glRectf x1 y1 x2 y2 | |
bb894c9d | 18436 | @deftypefunx void glRecti x1 y1 x2 y2 |
d172eed9 AW |
18437 | @deftypefunx void glRects x1 y1 x2 y2 |
18438 | @deftypefunx void glRectdv v1 v2 | |
18439 | @deftypefunx void glRectfv v1 v2 | |
18440 | @deftypefunx void glRectiv v1 v2 | |
18441 | @deftypefunx void glRectsv v1 v2 | |
3c9b6116 AW |
18442 | Draw a rectangle. |
18443 | ||
8925f36f AW |
18444 | @table @asis |
18445 | @item @var{x1} | |
18446 | @itemx @var{y1} | |
18447 | Specify one vertex of a rectangle. | |
18448 | ||
18449 | @item @var{x2} | |
18450 | @itemx @var{y2} | |
18451 | Specify the opposite vertex of the rectangle. | |
18452 | ||
18453 | @end table | |
18454 | ||
8925f36f | 18455 | @code{glRect} supports efficient specification of rectangles as two |
c7b31271 | 18456 | corner points. Each rectangle command takes four arguments, organized |
3c9b6116 AW |
18457 | either as two consecutive pairs of @r{(@var{x},@var{y})} coordinates or |
18458 | as two pointers to arrays, each containing an @r{(@var{x},@var{y})} | |
c7b31271 | 18459 | pair. The resulting rectangle is defined in the @r{@var{z}=0} plane. |
8925f36f AW |
18460 | |
18461 | @code{glRect}(@var{x1}, @var{y1}, @var{x2}, @var{y2}) is exactly | |
18462 | equivalent to the following sequence: Note that if the second vertex is | |
18463 | above and to the right of the first vertex, the rectangle is constructed | |
18464 | with a counterclockwise winding. | |
18465 | ||
18466 | @example | |
18467 | ||
18468 | glBegin(@code{GL_POLYGON}); | |
18469 | glVertex2(@var{x1}, @var{y1}); | |
18470 | glVertex2(@var{x2}, @var{y1}); | |
18471 | glVertex2(@var{x2}, @var{y2}); | |
18472 | glVertex2(@var{x1}, @var{y2}); | |
18473 | glEnd(); | |
18474 | @end example | |
18475 | ||
8925f36f AW |
18476 | @code{GL_INVALID_OPERATION} is generated if @code{glRect} is executed |
18477 | between the execution of @code{glBegin} and the corresponding execution | |
18478 | of @code{glEnd}. | |
18479 | ||
bb894c9d | 18480 | @end deftypefun |
8925f36f | 18481 | |
bb894c9d | 18482 | @deftypefun GLint glRenderMode mode |
3c9b6116 AW |
18483 | Set rasterization mode. |
18484 | ||
8925f36f AW |
18485 | @table @asis |
18486 | @item @var{mode} | |
c7b31271 DH |
18487 | Specifies the rasterization mode. Three values are accepted: |
18488 | @code{GL_RENDER}, @code{GL_SELECT}, and @code{GL_FEEDBACK}. The initial | |
8925f36f AW |
18489 | value is @code{GL_RENDER}. |
18490 | ||
18491 | @end table | |
18492 | ||
c7b31271 | 18493 | @code{glRenderMode} sets the rasterization mode. It takes one argument, |
8925f36f AW |
18494 | @var{mode}, which can assume one of three predefined values: |
18495 | ||
18496 | @table @asis | |
18497 | @item @code{GL_RENDER} | |
c7b31271 DH |
18498 | Render mode. Primitives are rasterized, producing pixel fragments, |
18499 | which are written into the frame buffer. This is the normal mode and | |
18500 | also the default mode. | |
8925f36f AW |
18501 | |
18502 | @item @code{GL_SELECT} | |
c7b31271 DH |
18503 | Selection mode. No pixel fragments are produced, and no change to the |
18504 | frame buffer contents is made. Instead, a record of the names of | |
8925f36f AW |
18505 | primitives that would have been drawn if the render mode had been |
18506 | @code{GL_RENDER} is returned in a select buffer, which must be created | |
18507 | (see @code{glSelectBuffer}) before selection mode is entered. | |
18508 | ||
18509 | @item @code{GL_FEEDBACK} | |
c7b31271 DH |
18510 | Feedback mode. No pixel fragments are produced, and no change to the |
18511 | frame buffer contents is made. Instead, the coordinates and attributes | |
8925f36f AW |
18512 | of vertices that would have been drawn if the render mode had been |
18513 | @code{GL_RENDER} is returned in a feedback buffer, which must be created | |
18514 | (see @code{glFeedbackBuffer}) before feedback mode is entered. | |
18515 | ||
18516 | @end table | |
18517 | ||
18518 | The return value of @code{glRenderMode} is determined by the render mode | |
18519 | at the time @code{glRenderMode} is called, rather than by @var{mode}. | |
18520 | The values returned for the three render modes are as follows: | |
18521 | ||
18522 | @table @asis | |
18523 | @item @code{GL_RENDER} | |
18524 | 0. | |
18525 | ||
18526 | @item @code{GL_SELECT} | |
18527 | The number of hit records transferred to the select buffer. | |
18528 | ||
18529 | @item @code{GL_FEEDBACK} | |
18530 | The number of values (not vertices) transferred to the feedback buffer. | |
18531 | ||
18532 | @end table | |
18533 | ||
18534 | See the @code{glSelectBuffer} and @code{glFeedbackBuffer} reference | |
18535 | pages for more details concerning selection and feedback operation. | |
18536 | ||
8925f36f AW |
18537 | @code{GL_INVALID_ENUM} is generated if @var{mode} is not one of the |
18538 | three accepted values. | |
18539 | ||
18540 | @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is | |
18541 | called while the render mode is @code{GL_SELECT}, or if | |
18542 | @code{glRenderMode} is called with argument @code{GL_SELECT} before | |
18543 | @code{glSelectBuffer} is called at least once. | |
18544 | ||
18545 | @code{GL_INVALID_OPERATION} is generated if @code{glFeedbackBuffer} is | |
18546 | called while the render mode is @code{GL_FEEDBACK}, or if | |
18547 | @code{glRenderMode} is called with argument @code{GL_FEEDBACK} before | |
18548 | @code{glFeedbackBuffer} is called at least once. | |
18549 | ||
18550 | @code{GL_INVALID_OPERATION} is generated if @code{glRenderMode} is | |
18551 | executed between the execution of @code{glBegin} and the corresponding | |
18552 | execution of @code{glEnd}. | |
18553 | ||
bb894c9d | 18554 | @end deftypefun |
8925f36f | 18555 | |
bb894c9d | 18556 | @deftypefun void glResetHistogram target |
3c9b6116 AW |
18557 | Reset histogram table entries to zero. |
18558 | ||
8925f36f AW |
18559 | @table @asis |
18560 | @item @var{target} | |
18561 | Must be @code{GL_HISTOGRAM}. | |
18562 | ||
18563 | @end table | |
18564 | ||
8925f36f AW |
18565 | @code{glResetHistogram} resets all the elements of the current histogram |
18566 | table to zero. | |
18567 | ||
8925f36f AW |
18568 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
18569 | @code{GL_HISTOGRAM}. | |
18570 | ||
18571 | @code{GL_INVALID_OPERATION} is generated if @code{glResetHistogram} is | |
18572 | executed between the execution of @code{glBegin} and the corresponding | |
18573 | execution of @code{glEnd}. | |
18574 | ||
bb894c9d | 18575 | @end deftypefun |
8925f36f | 18576 | |
bb894c9d | 18577 | @deftypefun void glResetMinmax target |
3c9b6116 AW |
18578 | Reset minmax table entries to initial values. |
18579 | ||
8925f36f AW |
18580 | @table @asis |
18581 | @item @var{target} | |
18582 | Must be @code{GL_MINMAX}. | |
18583 | ||
18584 | @end table | |
18585 | ||
8925f36f AW |
18586 | @code{glResetMinmax} resets the elements of the current minmax table to |
18587 | their initial values: the ``maximum'' element receives the minimum | |
18588 | possible component values, and the ``minimum'' element receives the | |
18589 | maximum possible component values. | |
18590 | ||
8925f36f AW |
18591 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
18592 | @code{GL_MINMAX}. | |
18593 | ||
18594 | @code{GL_INVALID_OPERATION} is generated if @code{glResetMinmax} is | |
18595 | executed between the execution of @code{glBegin} and the corresponding | |
18596 | execution of @code{glEnd}. | |
18597 | ||
bb894c9d | 18598 | @end deftypefun |
8925f36f | 18599 | |
d172eed9 AW |
18600 | @deftypefun void glRotated angle x y z |
18601 | @deftypefunx void glRotatef angle x y z | |
3c9b6116 AW |
18602 | Multiply the current matrix by a rotation matrix. |
18603 | ||
8925f36f AW |
18604 | @table @asis |
18605 | @item @var{angle} | |
18606 | Specifies the angle of rotation, in degrees. | |
18607 | ||
18608 | @item @var{x} | |
18609 | @itemx @var{y} | |
18610 | @itemx @var{z} | |
18611 | Specify the @var{x}, @var{y}, and @var{z} coordinates of a vector, | |
18612 | respectively. | |
18613 | ||
18614 | @end table | |
18615 | ||
8925f36f | 18616 | @code{glRotate} produces a rotation of @var{angle} degrees around the |
c7b31271 | 18617 | vector @r{(@var{x},@var{y}@var{z})}. The current matrix (see |
8925f36f AW |
18618 | @code{glMatrixMode}) is multiplied by a rotation matrix with the product |
18619 | replacing the current matrix, as if @code{glMultMatrix} were called with | |
18620 | the following matrix as its argument: | |
18621 | ||
3c9b6116 | 18622 | @r{((@var{x}^2(1-@var{c},)+@var{c} |
8925f36f AW |
18623 | @var{x}@var{y}(1-@var{c},)-@var{z}@var{s} |
18624 | @var{x}@var{z}(1-@var{c},)+@var{y}@var{s} 0), | |
18625 | (@var{y}@var{x}(1-@var{c},)+@var{z}@var{s} | |
18626 | @var{y}^2(1-@var{c},)+@var{c} | |
18627 | @var{y}@var{z}(1-@var{c},)-@var{x}@var{s} 0), | |
18628 | (@var{x}@var{z}(1-@var{c},)-@var{y}@var{s} | |
18629 | @var{y}@var{z}(1-@var{c},)+@var{x}@var{s} | |
18630 | @var{z}^2(1-@var{c},)+@var{c} 0), (0 0 0 1),)} | |
18631 | ||
18632 | ||
18633 | ||
3c9b6116 AW |
18634 | Where @r{@var{c}=@var{cos}(@var{angle},)}, |
18635 | @r{@var{s}=@var{sin}(@var{angle},)}, and | |
18636 | @r{∥(@var{x},@var{y}@var{z}),∥=1} (if not, the GL will normalize this | |
8925f36f AW |
18637 | vector). |
18638 | ||
18639 | ||
18640 | ||
18641 | ||
18642 | ||
18643 | If the matrix mode is either @code{GL_MODELVIEW} or | |
18644 | @code{GL_PROJECTION}, all objects drawn after @code{glRotate} is called | |
c7b31271 | 18645 | are rotated. Use @code{glPushMatrix} and @code{glPopMatrix} to save and |
8925f36f AW |
18646 | restore the unrotated coordinate system. |
18647 | ||
8925f36f AW |
18648 | @code{GL_INVALID_OPERATION} is generated if @code{glRotate} is executed |
18649 | between the execution of @code{glBegin} and the corresponding execution | |
18650 | of @code{glEnd}. | |
18651 | ||
bb894c9d | 18652 | @end deftypefun |
8925f36f | 18653 | |
bb894c9d | 18654 | @deftypefun void glSampleCoverage value invert |
3c9b6116 AW |
18655 | Specify multisample coverage parameters. |
18656 | ||
8925f36f AW |
18657 | @table @asis |
18658 | @item @var{value} | |
c7b31271 DH |
18659 | Specify a single floating-point sample coverage value. The value is |
18660 | clamped to the range @r{[0,1]}. The initial value is 1.0. | |
8925f36f AW |
18661 | |
18662 | @item @var{invert} | |
18663 | Specify a single boolean value representing if the coverage masks should | |
c7b31271 | 18664 | be inverted. @code{GL_TRUE} and @code{GL_FALSE} are accepted. The |
8925f36f AW |
18665 | initial value is @code{GL_FALSE}. |
18666 | ||
18667 | @end table | |
18668 | ||
8925f36f AW |
18669 | Multisampling samples a pixel multiple times at various |
18670 | implementation-dependent subpixel locations to generate antialiasing | |
c7b31271 | 18671 | effects. Multisampling transparently antialiases points, lines, |
8925f36f AW |
18672 | polygons, bitmaps, and images if it is enabled. |
18673 | ||
18674 | @var{value} is used in constructing a temporary mask used in determining | |
c7b31271 | 18675 | which samples will be used in resolving the final fragment color. This |
8925f36f | 18676 | mask is bitwise-anded with the coverage mask generated from the |
c7b31271 | 18677 | multisampling computation. If the @var{invert} flag is set, the |
8925f36f AW |
18678 | temporary mask is inverted (all bits flipped) and then the bitwise-and |
18679 | is computed. | |
18680 | ||
18681 | If an implementation does not have any multisample buffers available, or | |
18682 | multisampling is disabled, rasterization occurs with only a single | |
18683 | sample computing a pixel's final RGB color. | |
18684 | ||
18685 | Provided an implementation supports multisample buffers, and | |
18686 | multisampling is enabled, then a pixel's final color is generated by | |
c7b31271 | 18687 | combining several samples per pixel. Each sample contains color, depth, |
8925f36f AW |
18688 | and stencil information, allowing those operations to be performed on |
18689 | each sample. | |
18690 | ||
8925f36f AW |
18691 | @code{GL_INVALID_OPERATION} is generated if @code{glSampleCoverage} is |
18692 | executed between the execution of @code{glBegin} and the corresponding | |
18693 | execution of @code{glEnd}. | |
18694 | ||
bb894c9d | 18695 | @end deftypefun |
8925f36f | 18696 | |
d172eed9 AW |
18697 | @deftypefun void glScaled x y z |
18698 | @deftypefunx void glScalef x y z | |
3c9b6116 AW |
18699 | Multiply the current matrix by a general scaling matrix. |
18700 | ||
8925f36f AW |
18701 | @table @asis |
18702 | @item @var{x} | |
18703 | @itemx @var{y} | |
18704 | @itemx @var{z} | |
18705 | Specify scale factors along the @var{x}, @var{y}, and @var{z} axes, | |
18706 | respectively. | |
18707 | ||
18708 | @end table | |
18709 | ||
8925f36f | 18710 | @code{glScale} produces a nonuniform scaling along the @var{x}, @var{y}, |
c7b31271 DH |
18711 | and @var{z} axes. The three parameters indicate the desired scale |
18712 | factor along each of the three axes. | |
8925f36f AW |
18713 | |
18714 | The current matrix (see @code{glMatrixMode}) is multiplied by this scale | |
18715 | matrix, and the product replaces the current matrix as if | |
18716 | @code{glMultMatrix} were called with the following matrix as its | |
18717 | argument: | |
18718 | ||
3c9b6116 | 18719 | @r{((@var{x} 0 0 0), (0 @var{y} 0 0), (0 0 @var{z} 0), (0 0 0 1),)} |
8925f36f AW |
18720 | |
18721 | If the matrix mode is either @code{GL_MODELVIEW} or | |
18722 | @code{GL_PROJECTION}, all objects drawn after @code{glScale} is called | |
18723 | are scaled. | |
18724 | ||
18725 | Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the | |
18726 | unscaled coordinate system. | |
18727 | ||
8925f36f AW |
18728 | @code{GL_INVALID_OPERATION} is generated if @code{glScale} is executed |
18729 | between the execution of @code{glBegin} and the corresponding execution | |
18730 | of @code{glEnd}. | |
18731 | ||
bb894c9d | 18732 | @end deftypefun |
8925f36f | 18733 | |
bb894c9d | 18734 | @deftypefun void glScissor x y width height |
3c9b6116 AW |
18735 | Define the scissor box. |
18736 | ||
8925f36f AW |
18737 | @table @asis |
18738 | @item @var{x} | |
18739 | @itemx @var{y} | |
c7b31271 | 18740 | Specify the lower left corner of the scissor box. Initially (0, 0). |
8925f36f AW |
18741 | |
18742 | @item @var{width} | |
18743 | @itemx @var{height} | |
c7b31271 | 18744 | Specify the width and height of the scissor box. When a GL context is |
8925f36f AW |
18745 | first attached to a window, @var{width} and @var{height} are set to the |
18746 | dimensions of that window. | |
18747 | ||
18748 | @end table | |
18749 | ||
8925f36f | 18750 | @code{glScissor} defines a rectangle, called the scissor box, in window |
c7b31271 DH |
18751 | coordinates. The first two arguments, @var{x} and @var{y}, specify the |
18752 | lower left corner of the box. @var{width} and @var{height} specify the | |
8925f36f AW |
18753 | width and height of the box. |
18754 | ||
18755 | To enable and disable the scissor test, call @code{glEnable} and | |
c7b31271 DH |
18756 | @code{glDisable} with argument @code{GL_SCISSOR_TEST}. The test is |
18757 | initially disabled. While the test is enabled, only pixels that lie | |
18758 | within the scissor box can be modified by drawing commands. Window | |
8925f36f | 18759 | coordinates have integer values at the shared corners of frame buffer |
c7b31271 | 18760 | pixels. @code{glScissor(0,0,1,1)} allows modification of only the lower |
8925f36f AW |
18761 | left pixel in the window, and @code{glScissor(0,0,0,0)} doesn't allow |
18762 | modification of any pixels in the window. | |
18763 | ||
18764 | When the scissor test is disabled, it is as though the scissor box | |
18765 | includes the entire window. | |
18766 | ||
8925f36f AW |
18767 | @code{GL_INVALID_VALUE} is generated if either @var{width} or |
18768 | @var{height} is negative. | |
18769 | ||
18770 | @code{GL_INVALID_OPERATION} is generated if @code{glScissor} is executed | |
18771 | between the execution of @code{glBegin} and the corresponding execution | |
18772 | of @code{glEnd}. | |
18773 | ||
bb894c9d | 18774 | @end deftypefun |
8925f36f | 18775 | |
bb894c9d | 18776 | @deftypefun void glSecondaryColorPointer size type stride pointer |
3c9b6116 AW |
18777 | Define an array of secondary colors. |
18778 | ||
8925f36f AW |
18779 | @table @asis |
18780 | @item @var{size} | |
c7b31271 | 18781 | Specifies the number of components per color. Must be 3. |
8925f36f AW |
18782 | |
18783 | @item @var{type} | |
c7b31271 | 18784 | Specifies the data type of each color component in the array. Symbolic |
8925f36f AW |
18785 | constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, |
18786 | @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT}, | |
c7b31271 | 18787 | @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is |
8925f36f AW |
18788 | @code{GL_FLOAT}. |
18789 | ||
18790 | @item @var{stride} | |
c7b31271 DH |
18791 | Specifies the byte offset between consecutive colors. If @var{stride} |
18792 | is 0, the colors are understood to be tightly packed in the array. The | |
8925f36f AW |
18793 | initial value is 0. |
18794 | ||
18795 | @item @var{pointer} | |
18796 | Specifies a pointer to the first component of the first color element in | |
c7b31271 | 18797 | the array. The initial value is 0. |
8925f36f AW |
18798 | |
18799 | @end table | |
18800 | ||
8925f36f | 18801 | @code{glSecondaryColorPointer} specifies the location and data format of |
c7b31271 DH |
18802 | an array of color components to use when rendering. @var{size} |
18803 | specifies the number of components per color, and must be 3. @var{type} | |
18804 | specifies the data type of each color component, and @var{stride} | |
18805 | specifies the byte stride from one color to the next, allowing vertices | |
18806 | and attributes to be packed into a single array or stored in separate | |
18807 | arrays. | |
8925f36f AW |
18808 | |
18809 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
18810 | target (see @code{glBindBuffer}) while a secondary color array is | |
18811 | specified, @var{pointer} is treated as a byte offset into the buffer | |
c7b31271 | 18812 | object's data store. Also, the buffer object binding |
8925f36f AW |
18813 | (@code{GL_ARRAY_BUFFER_BINDING}) is saved as secondary color vertex |
18814 | array client-side state | |
18815 | (@code{GL_SECONDARY_COLOR_ARRAY_BUFFER_BINDING}). | |
18816 | ||
18817 | When a secondary color array is specified, @var{size}, @var{type}, | |
18818 | @var{stride}, and @var{pointer} are saved as client-side state, in | |
18819 | addition to the current vertex array buffer object binding. | |
18820 | ||
18821 | To enable and disable the secondary color array, call | |
18822 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
c7b31271 | 18823 | argument @code{GL_SECONDARY_COLOR_ARRAY}. If enabled, the secondary |
8925f36f AW |
18824 | color array is used when @code{glArrayElement}, @code{glDrawArrays}, |
18825 | @code{glMultiDrawArrays}, @code{glDrawElements}, | |
18826 | @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called. | |
18827 | ||
8925f36f AW |
18828 | @code{GL_INVALID_VALUE} is generated if @var{size} is not 3. |
18829 | ||
18830 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted | |
18831 | value. | |
18832 | ||
18833 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
18834 | ||
bb894c9d | 18835 | @end deftypefun |
8925f36f | 18836 | |
d172eed9 AW |
18837 | @deftypefun void glSecondaryColor3b red green blue |
18838 | @deftypefunx void glSecondaryColor3s red green blue | |
18839 | @deftypefunx void glSecondaryColor3i red green blue | |
ca09631c | 18840 | @deftypefunx void glSecondaryColor3f red green blue |
d172eed9 AW |
18841 | @deftypefunx void glSecondaryColor3d red green blue |
18842 | @deftypefunx void glSecondaryColor3ub red green blue | |
18843 | @deftypefunx void glSecondaryColor3us red green blue | |
bb894c9d | 18844 | @deftypefunx void glSecondaryColor3ui red green blue |
d172eed9 AW |
18845 | @deftypefunx void glSecondaryColor3bv v |
18846 | @deftypefunx void glSecondaryColor3sv v | |
18847 | @deftypefunx void glSecondaryColor3iv v | |
18848 | @deftypefunx void glSecondaryColor3fv v | |
18849 | @deftypefunx void glSecondaryColor3dv v | |
18850 | @deftypefunx void glSecondaryColor3ubv v | |
18851 | @deftypefunx void glSecondaryColor3usv v | |
18852 | @deftypefunx void glSecondaryColor3uiv v | |
3c9b6116 AW |
18853 | Set the current secondary color. |
18854 | ||
8925f36f AW |
18855 | @table @asis |
18856 | @item @var{red} | |
18857 | @itemx @var{green} | |
18858 | @itemx @var{blue} | |
18859 | Specify new red, green, and blue values for the current secondary color. | |
18860 | ||
18861 | @end table | |
18862 | ||
8925f36f AW |
18863 | The GL stores both a primary four-valued RGBA color and a secondary |
18864 | four-valued RGBA color (where alpha is always set to 0.0) that is | |
18865 | associated with every vertex. | |
18866 | ||
18867 | The secondary color is interpolated and applied to each fragment during | |
c7b31271 | 18868 | rasterization when @code{GL_COLOR_SUM} is enabled. When lighting is |
8925f36f AW |
18869 | enabled, and @code{GL_SEPARATE_SPECULAR_COLOR} is specified, the value |
18870 | of the secondary color is assigned the value computed from the specular | |
c7b31271 DH |
18871 | term of the lighting computation. Both the primary and secondary |
18872 | current colors are applied to each fragment, regardless of the state of | |
18873 | @code{GL_COLOR_SUM}, under such conditions. When | |
8925f36f AW |
18874 | @code{GL_SEPARATE_SPECULAR_COLOR} is specified, the value returned from |
18875 | querying the current secondary color is undefined. | |
18876 | ||
18877 | @code{glSecondaryColor3b}, @code{glSecondaryColor3s}, and | |
18878 | @code{glSecondaryColor3i} take three signed byte, short, or long | |
c7b31271 | 18879 | integers as arguments. When @strong{v} is appended to the name, the |
8925f36f AW |
18880 | color commands can take a pointer to an array of such values. |
18881 | ||
18882 | Color values are stored in floating-point format, with unspecified | |
c7b31271 | 18883 | mantissa and exponent sizes. Unsigned integer color components, when |
8925f36f AW |
18884 | specified, are linearly mapped to floating-point values such that the |
18885 | largest representable value maps to 1.0 (full intensity), and 0 maps to | |
c7b31271 | 18886 | 0.0 (zero intensity). Signed integer color components, when specified, |
8925f36f AW |
18887 | are linearly mapped to floating-point values such that the most positive |
18888 | representable value maps to 1.0, and the most negative representable | |
c7b31271 DH |
18889 | value maps to @r{-1.0}. (Note that this mapping does not convert 0 |
18890 | precisely to 0.0). Floating-point values are mapped directly. | |
8925f36f AW |
18891 | |
18892 | Neither floating-point nor signed integer values are clamped to the | |
c7b31271 | 18893 | range @r{[0,1]} before the current color is updated. However, color |
8925f36f AW |
18894 | components are clamped to this range before they are interpolated or |
18895 | written into a color buffer. | |
18896 | ||
bb894c9d | 18897 | @end deftypefun |
8925f36f | 18898 | |
bb894c9d | 18899 | @deftypefun void glSelectBuffer size buffer |
3c9b6116 AW |
18900 | Establish a buffer for selection mode values. |
18901 | ||
8925f36f AW |
18902 | @table @asis |
18903 | @item @var{size} | |
18904 | Specifies the size of @var{buffer}. | |
18905 | ||
18906 | @item @var{buffer} | |
18907 | Returns the selection data. | |
18908 | ||
18909 | @end table | |
18910 | ||
8925f36f AW |
18911 | @code{glSelectBuffer} has two arguments: @var{buffer} is a pointer to an |
18912 | array of unsigned integers, and @var{size} indicates the size of the | |
c7b31271 | 18913 | array. @var{buffer} returns values from the name stack (see |
8925f36f AW |
18914 | @code{glInitNames}, @code{glLoadName}, @code{glPushName}) when the |
18915 | rendering mode is @code{GL_SELECT} (see @code{glRenderMode}). | |
18916 | @code{glSelectBuffer} must be issued before selection mode is enabled, | |
18917 | and it must not be issued while the rendering mode is @code{GL_SELECT}. | |
18918 | ||
18919 | A programmer can use selection to determine which primitives are drawn | |
c7b31271 | 18920 | into some region of a window. The region is defined by the current |
8925f36f AW |
18921 | modelview and perspective matrices. |
18922 | ||
18923 | In selection mode, no pixel fragments are produced from rasterization. | |
18924 | Instead, if a primitive or a raster position intersects the clipping | |
18925 | volume defined by the viewing frustum and the user-defined clipping | |
c7b31271 | 18926 | planes, this primitive causes a selection hit. (With polygons, no hit |
8925f36f AW |
18927 | occurs if the polygon is culled.) When a change is made to the name |
18928 | stack, or when @code{glRenderMode} is called, a hit record is copied to | |
18929 | @var{buffer} if any hits have occurred since the last such event (name | |
c7b31271 | 18930 | stack change or @code{glRenderMode} call). The hit record consists of |
8925f36f AW |
18931 | the number of names in the name stack at the time of the event, followed |
18932 | by the minimum and maximum depth values of all vertices that hit since | |
18933 | the previous event, followed by the name stack contents, bottom name | |
18934 | first. | |
18935 | ||
18936 | Depth values (which are in the range [0,1]) are multiplied by | |
3c9b6116 | 18937 | @r{2^32-1}, before being placed in the hit record. |
8925f36f AW |
18938 | |
18939 | An internal index into @var{buffer} is reset to 0 whenever selection | |
c7b31271 DH |
18940 | mode is entered. Each time a hit record is copied into @var{buffer}, |
18941 | the index is incremented to point to the cell just past the end of the | |
18942 | block of names\(emthat is, to the next available cell If the hit record | |
18943 | is larger than the number of remaining locations in @var{buffer}, as | |
18944 | much data as can fit is copied, and the overflow flag is set. If the | |
18945 | name stack is empty when a hit record is copied, that record consists of | |
18946 | 0 followed by the minimum and maximum depth values. | |
8925f36f AW |
18947 | |
18948 | To exit selection mode, call @code{glRenderMode} with an argument other | |
c7b31271 | 18949 | than @code{GL_SELECT}. Whenever @code{glRenderMode} is called while the |
8925f36f AW |
18950 | render mode is @code{GL_SELECT}, it returns the number of hit records |
18951 | copied to @var{buffer}, resets the overflow flag and the selection | |
c7b31271 | 18952 | buffer pointer, and initializes the name stack to be empty. If the |
8925f36f AW |
18953 | overflow bit was set when @code{glRenderMode} was called, a negative hit |
18954 | record count is returned. | |
18955 | ||
8925f36f AW |
18956 | @code{GL_INVALID_VALUE} is generated if @var{size} is negative. |
18957 | ||
18958 | @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is | |
18959 | called while the render mode is @code{GL_SELECT}, or if | |
18960 | @code{glRenderMode} is called with argument @code{GL_SELECT} before | |
18961 | @code{glSelectBuffer} is called at least once. | |
18962 | ||
18963 | @code{GL_INVALID_OPERATION} is generated if @code{glSelectBuffer} is | |
18964 | executed between the execution of @code{glBegin} and the corresponding | |
18965 | execution of @code{glEnd}. | |
18966 | ||
bb894c9d | 18967 | @end deftypefun |
8925f36f | 18968 | |
bb894c9d | 18969 | @deftypefun void glSeparableFilter2D target internalformat width height format type row column |
3c9b6116 AW |
18970 | Define a separable two-dimensional convolution filter. |
18971 | ||
8925f36f AW |
18972 | @table @asis |
18973 | @item @var{target} | |
18974 | Must be @code{GL_SEPARABLE_2D}. | |
18975 | ||
18976 | @item @var{internalformat} | |
c7b31271 | 18977 | The internal format of the convolution filter kernel. The allowable |
8925f36f AW |
18978 | values are @code{GL_ALPHA}, @code{GL_ALPHA4}, @code{GL_ALPHA8}, |
18979 | @code{GL_ALPHA12}, @code{GL_ALPHA16}, @code{GL_LUMINANCE}, | |
18980 | @code{GL_LUMINANCE4}, @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, | |
18981 | @code{GL_LUMINANCE16}, @code{GL_LUMINANCE_ALPHA}, | |
18982 | @code{GL_LUMINANCE4_ALPHA4}, @code{GL_LUMINANCE6_ALPHA2}, | |
18983 | @code{GL_LUMINANCE8_ALPHA8}, @code{GL_LUMINANCE12_ALPHA4}, | |
18984 | @code{GL_LUMINANCE12_ALPHA12}, @code{GL_LUMINANCE16_ALPHA16}, | |
18985 | @code{GL_INTENSITY}, @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, | |
18986 | @code{GL_INTENSITY12}, @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, | |
18987 | @code{GL_RGB}, @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, | |
18988 | @code{GL_RGB10}, @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, | |
18989 | @code{GL_RGBA2}, @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, | |
18990 | @code{GL_RGB10_A2}, @code{GL_RGBA12}, or @code{GL_RGBA16}. | |
18991 | ||
18992 | @item @var{width} | |
c7b31271 | 18993 | The number of elements in the pixel array referenced by @var{row}. (This |
8925f36f AW |
18994 | is the width of the separable filter kernel.) |
18995 | ||
18996 | @item @var{height} | |
18997 | The number of elements in the pixel array referenced by @var{column}. | |
18998 | (This is the height of the separable filter kernel.) | |
18999 | ||
19000 | @item @var{format} | |
c7b31271 | 19001 | The format of the pixel data in @var{row} and @var{column}. The |
8925f36f AW |
19002 | allowable values are @code{GL_RED}, @code{GL_GREEN}, @code{GL_BLUE}, |
19003 | @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, @code{GL_RGBA}, | |
19004 | @code{GL_BGRA}, @code{GL_INTENSITY}, @code{GL_LUMINANCE}, and | |
19005 | @code{GL_LUMINANCE_ALPHA}. | |
19006 | ||
19007 | @item @var{type} | |
c7b31271 | 19008 | The type of the pixel data in @var{row} and @var{column}. Symbolic |
8925f36f AW |
19009 | constants @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, @code{GL_BITMAP}, |
19010 | @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, @code{GL_UNSIGNED_INT}, | |
19011 | @code{GL_INT}, @code{GL_FLOAT}, @code{GL_UNSIGNED_BYTE_3_3_2}, | |
19012 | @code{GL_UNSIGNED_BYTE_2_3_3_REV}, @code{GL_UNSIGNED_SHORT_5_6_5}, | |
19013 | @code{GL_UNSIGNED_SHORT_5_6_5_REV}, @code{GL_UNSIGNED_SHORT_4_4_4_4}, | |
19014 | @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, @code{GL_UNSIGNED_SHORT_5_5_5_1}, | |
19015 | @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, @code{GL_UNSIGNED_INT_8_8_8_8}, | |
19016 | @code{GL_UNSIGNED_INT_8_8_8_8_REV}, @code{GL_UNSIGNED_INT_10_10_10_2}, | |
19017 | and @code{GL_UNSIGNED_INT_2_10_10_10_REV} are accepted. | |
19018 | ||
19019 | @item @var{row} | |
19020 | Pointer to a one-dimensional array of pixel data that is processed to | |
19021 | build the row filter kernel. | |
19022 | ||
19023 | @item @var{column} | |
19024 | Pointer to a one-dimensional array of pixel data that is processed to | |
19025 | build the column filter kernel. | |
19026 | ||
19027 | @end table | |
19028 | ||
8925f36f AW |
19029 | @code{glSeparableFilter2D} builds a two-dimensional separable |
19030 | convolution filter kernel from two arrays of pixels. | |
19031 | ||
19032 | The pixel arrays specified by (@var{width}, @var{format}, @var{type}, | |
19033 | @var{row}) and (@var{height}, @var{format}, @var{type}, @var{column}) | |
19034 | are processed just as if they had been passed to @code{glDrawPixels}, | |
19035 | but processing stops after the final expansion to RGBA is completed. | |
19036 | ||
19037 | If a non-zero named buffer object is bound to the | |
19038 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
19039 | convolution filter is specified, @var{row} and @var{column} are treated | |
19040 | as byte offsets into the buffer object's data store. | |
19041 | ||
19042 | Next, the R, G, B, and A components of all pixels in both arrays are | |
19043 | scaled by the four separable 2D @code{GL_CONVOLUTION_FILTER_SCALE} | |
19044 | parameters and biased by the four separable 2D | |
c7b31271 | 19045 | @code{GL_CONVOLUTION_FILTER_BIAS} parameters. (The scale and bias |
8925f36f AW |
19046 | parameters are set by @code{glConvolutionParameter} using the |
19047 | @code{GL_SEPARABLE_2D} target and the names | |
19048 | @code{GL_CONVOLUTION_FILTER_SCALE} and | |
c7b31271 DH |
19049 | @code{GL_CONVOLUTION_FILTER_BIAS}. The parameters themselves are |
19050 | vectors of four values that are applied to red, green, blue, and alpha, | |
19051 | in that order.) The R, G, B, and A values are not clamped to [0,1] at | |
19052 | any time during this process. | |
8925f36f AW |
19053 | |
19054 | Each pixel is then converted to the internal format specified by | |
c7b31271 | 19055 | @var{internalformat}. This conversion simply maps the component values |
8925f36f | 19056 | of the pixel (R, G, B, and A) to the values included in the internal |
c7b31271 | 19057 | format (red, green, blue, alpha, luminance, and intensity). The mapping |
8925f36f AW |
19058 | is as follows: |
19059 | ||
19060 | @table @asis | |
19061 | @item @strong{Internal Format} | |
19062 | @strong{Red}, @strong{Green}, @strong{Blue}, @strong{Alpha}, | |
19063 | @strong{Luminance}, @strong{Intensity} | |
19064 | ||
19065 | @item @code{GL_LUMINANCE} | |
19066 | , , , , R , | |
19067 | ||
19068 | @item @code{GL_LUMINANCE_ALPHA} | |
19069 | , , , A , R , | |
19070 | ||
19071 | @item @code{GL_INTENSITY} | |
19072 | , , , , , R | |
19073 | ||
19074 | @item @code{GL_RGB} | |
19075 | R , G , B , , , | |
19076 | ||
19077 | @item @code{GL_RGBA} | |
19078 | R , G , B , A , , | |
19079 | ||
19080 | @end table | |
19081 | ||
19082 | The red, green, blue, alpha, luminance, and/or intensity components of | |
19083 | the resulting pixels are stored in floating-point rather than integer | |
c7b31271 | 19084 | format. They form two one-dimensional filter kernel images. The row |
8925f36f | 19085 | image is indexed by coordinate @var{i} starting at zero and increasing |
c7b31271 DH |
19086 | from left to right. Each location in the row image is derived from |
19087 | element @var{i} of @var{row}. The column image is indexed by coordinate | |
19088 | @var{j} starting at zero and increasing from bottom to top. Each | |
8925f36f AW |
19089 | location in the column image is derived from element @var{j} of |
19090 | @var{column}. | |
19091 | ||
19092 | Note that after a convolution is performed, the resulting color | |
19093 | components are also scaled by their corresponding | |
19094 | @code{GL_POST_CONVOLUTION_c_SCALE} parameters and biased by their | |
19095 | corresponding @code{GL_POST_CONVOLUTION_c_BIAS} parameters (where | |
19096 | @var{c} takes on the values @strong{RED}, @strong{GREEN}, @strong{BLUE}, | |
c7b31271 DH |
19097 | and @strong{ALPHA}). These parameters are set by |
19098 | @code{glPixelTransfer}. | |
8925f36f | 19099 | |
8925f36f AW |
19100 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
19101 | @code{GL_SEPARABLE_2D}. | |
19102 | ||
19103 | @code{GL_INVALID_ENUM} is generated if @var{internalformat} is not one | |
19104 | of the allowable values. | |
19105 | ||
19106 | @code{GL_INVALID_ENUM} is generated if @var{format} is not one of the | |
19107 | allowable values. | |
19108 | ||
19109 | @code{GL_INVALID_ENUM} is generated if @var{type} is not one of the | |
19110 | allowable values. | |
19111 | ||
19112 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than zero or | |
c7b31271 DH |
19113 | greater than the maximum supported value. This value may be queried |
19114 | with @code{glGetConvolutionParameter} using target | |
19115 | @code{GL_SEPARABLE_2D} and name @code{GL_MAX_CONVOLUTION_WIDTH}. | |
8925f36f AW |
19116 | |
19117 | @code{GL_INVALID_VALUE} is generated if @var{height} is less than zero | |
c7b31271 | 19118 | or greater than the maximum supported value. This value may be queried |
8925f36f AW |
19119 | with @code{glGetConvolutionParameter} using target |
19120 | @code{GL_SEPARABLE_2D} and name @code{GL_MAX_CONVOLUTION_HEIGHT}. | |
19121 | ||
19122 | @code{GL_INVALID_OPERATION} is generated if @var{height} is one of | |
19123 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
19124 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
19125 | and @var{format} is not @code{GL_RGB}. | |
19126 | ||
19127 | @code{GL_INVALID_OPERATION} is generated if @var{height} is one of | |
19128 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
19129 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
19130 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
19131 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
19132 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
19133 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
19134 | ||
19135 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
19136 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
19137 | object's data store is currently mapped. | |
19138 | ||
19139 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
19140 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
19141 | would be unpacked from the buffer object such that the memory reads | |
19142 | required would exceed the data store size. | |
19143 | ||
19144 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
19145 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{row} | |
19146 | or @var{column} is not evenly divisible into the number of bytes needed | |
19147 | to store in memory a datum indicated by @var{type}. | |
19148 | ||
19149 | @code{GL_INVALID_OPERATION} is generated if @code{glSeparableFilter2D} | |
19150 | is executed between the execution of @code{glBegin} and the | |
19151 | corresponding execution of @code{glEnd}. | |
19152 | ||
bb894c9d | 19153 | @end deftypefun |
8925f36f | 19154 | |
bb894c9d | 19155 | @deftypefun void glShadeModel mode |
3c9b6116 AW |
19156 | Select flat or smooth shading. |
19157 | ||
8925f36f AW |
19158 | @table @asis |
19159 | @item @var{mode} | |
c7b31271 DH |
19160 | Specifies a symbolic value representing a shading technique. Accepted |
19161 | values are @code{GL_FLAT} and @code{GL_SMOOTH}. The initial value is | |
8925f36f AW |
19162 | @code{GL_SMOOTH}. |
19163 | ||
19164 | @end table | |
19165 | ||
c7b31271 | 19166 | GL primitives can have either flat or smooth shading. Smooth shading, |
8925f36f AW |
19167 | the default, causes the computed colors of vertices to be interpolated |
19168 | as the primitive is rasterized, typically assigning different colors to | |
c7b31271 | 19169 | each resulting pixel fragment. Flat shading selects the computed color |
8925f36f | 19170 | of just one vertex and assigns it to all the pixel fragments generated |
c7b31271 DH |
19171 | by rasterizing a single primitive. In either case, the computed color |
19172 | of a vertex is the result of lighting if lighting is enabled, or it is | |
19173 | the current color at the time the vertex was specified if lighting is | |
8925f36f AW |
19174 | disabled. |
19175 | ||
c7b31271 | 19176 | Flat and smooth shading are indistinguishable for points. Starting when |
8925f36f | 19177 | @code{glBegin} is issued and counting vertices and primitives from 1, |
3c9b6116 | 19178 | the GL gives each flat-shaded line segment @r{@var{i}} the computed |
c7b31271 | 19179 | color of vertex @r{@var{i}+1}, its second vertex. Counting similarly |
8925f36f | 19180 | from 1, the GL gives each flat-shaded polygon the computed color of the |
c7b31271 DH |
19181 | vertex listed in the following table. This is the last vertex to |
19182 | specify the polygon in all cases except single polygons, where the first | |
19183 | vertex specifies the flat-shaded color. | |
8925f36f AW |
19184 | |
19185 | ||
19186 | ||
19187 | @table @asis | |
19188 | @item @strong{ | |
3c9b6116 | 19189 | Primitive Type of Polygon @r{@var{i}}} |
8925f36f AW |
19190 | @strong{Vertex} |
19191 | ||
19192 | @item | |
19193 | Single polygon | |
3c9b6116 | 19194 | (@r{@var{i}==1}) |
8925f36f AW |
19195 | 1 |
19196 | ||
19197 | @item | |
19198 | Triangle strip | |
3c9b6116 | 19199 | @r{@var{i}+2} |
8925f36f AW |
19200 | |
19201 | @item | |
19202 | Triangle fan | |
3c9b6116 | 19203 | @r{@var{i}+2} |
8925f36f AW |
19204 | |
19205 | @item | |
19206 | Independent triangle | |
3c9b6116 | 19207 | @r{3@var{i}} |
8925f36f AW |
19208 | |
19209 | @item | |
19210 | Quad strip | |
3c9b6116 | 19211 | @r{2@var{i}+2} |
8925f36f AW |
19212 | |
19213 | @item | |
19214 | Independent quad | |
3c9b6116 | 19215 | @r{4@var{i}} |
8925f36f AW |
19216 | |
19217 | @end table | |
19218 | ||
19219 | Flat and smooth shading are specified by @code{glShadeModel} with | |
19220 | @var{mode} set to @code{GL_FLAT} and @code{GL_SMOOTH}, respectively. | |
19221 | ||
8925f36f AW |
19222 | @code{GL_INVALID_ENUM} is generated if @var{mode} is any value other |
19223 | than @code{GL_FLAT} or @code{GL_SMOOTH}. | |
19224 | ||
19225 | @code{GL_INVALID_OPERATION} is generated if @code{glShadeModel} is | |
19226 | executed between the execution of @code{glBegin} and the corresponding | |
19227 | execution of @code{glEnd}. | |
19228 | ||
bb894c9d | 19229 | @end deftypefun |
8925f36f | 19230 | |
bb894c9d | 19231 | @deftypefun void glShaderSource shader count string length |
3c9b6116 AW |
19232 | Replaces the source code in a shader object. |
19233 | ||
8925f36f AW |
19234 | @table @asis |
19235 | @item @var{shader} | |
19236 | Specifies the handle of the shader object whose source code is to be | |
19237 | replaced. | |
19238 | ||
19239 | @item @var{count} | |
19240 | Specifies the number of elements in the @var{string} and @var{length} | |
19241 | arrays. | |
19242 | ||
19243 | @item @var{string} | |
19244 | Specifies an array of pointers to strings containing the source code to | |
19245 | be loaded into the shader. | |
19246 | ||
19247 | @item @var{length} | |
19248 | Specifies an array of string lengths. | |
19249 | ||
19250 | @end table | |
19251 | ||
8925f36f | 19252 | @code{glShaderSource} sets the source code in @var{shader} to the source |
c7b31271 DH |
19253 | code in the array of strings specified by @var{string}. Any source code |
19254 | previously stored in the shader object is completely replaced. The | |
19255 | number of strings in the array is specified by @var{count}. If | |
8925f36f | 19256 | @var{length} is @code{NULL}, each string is assumed to be null |
c7b31271 DH |
19257 | terminated. If @var{length} is a value other than @code{NULL}, it |
19258 | points to an array containing a string length for each of the | |
19259 | corresponding elements of @var{string}. Each element in the | |
19260 | @var{length} array may contain the length of the corresponding string | |
19261 | (the null character is not counted as part of the string length) or a | |
19262 | value less than 0 to indicate that the string is null terminated. The | |
19263 | source code strings are not scanned or parsed at this time; they are | |
19264 | simply copied into the specified shader object. | |
8925f36f | 19265 | |
8925f36f AW |
19266 | @code{GL_INVALID_VALUE} is generated if @var{shader} is not a value |
19267 | generated by OpenGL. | |
19268 | ||
19269 | @code{GL_INVALID_OPERATION} is generated if @var{shader} is not a shader | |
19270 | object. | |
19271 | ||
19272 | @code{GL_INVALID_VALUE} is generated if @var{count} is less than 0. | |
19273 | ||
19274 | @code{GL_INVALID_OPERATION} is generated if @code{glShaderSource} is | |
19275 | executed between the execution of @code{glBegin} and the corresponding | |
19276 | execution of @code{glEnd}. | |
19277 | ||
bb894c9d | 19278 | @end deftypefun |
8925f36f | 19279 | |
bb894c9d | 19280 | @deftypefun void glStencilFuncSeparate face func ref mask |
3c9b6116 AW |
19281 | Set front and/or back function and reference value for stencil testing. |
19282 | ||
8925f36f AW |
19283 | @table @asis |
19284 | @item @var{face} | |
c7b31271 | 19285 | Specifies whether front and/or back stencil state is updated. Three |
8925f36f AW |
19286 | symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and |
19287 | @code{GL_FRONT_AND_BACK}. | |
19288 | ||
19289 | @item @var{func} | |
c7b31271 | 19290 | Specifies the test function. Eight symbolic constants are valid: |
8925f36f AW |
19291 | @code{GL_NEVER}, @code{GL_LESS}, @code{GL_LEQUAL}, @code{GL_GREATER}, |
19292 | @code{GL_GEQUAL}, @code{GL_EQUAL}, @code{GL_NOTEQUAL}, and | |
c7b31271 | 19293 | @code{GL_ALWAYS}. The initial value is @code{GL_ALWAYS}. |
8925f36f AW |
19294 | |
19295 | @item @var{ref} | |
c7b31271 DH |
19296 | Specifies the reference value for the stencil test. @var{ref} is |
19297 | clamped to the range @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the | |
19298 | number of bitplanes in the stencil buffer. The initial value is 0. | |
8925f36f AW |
19299 | |
19300 | @item @var{mask} | |
19301 | Specifies a mask that is ANDed with both the reference value and the | |
c7b31271 | 19302 | stored stencil value when the test is done. The initial value is all |
8925f36f AW |
19303 | 1's. |
19304 | ||
19305 | @end table | |
19306 | ||
8925f36f | 19307 | Stenciling, like depth-buffering, enables and disables drawing on a |
c7b31271 | 19308 | per-pixel basis. You draw into the stencil planes using GL drawing |
8925f36f | 19309 | primitives, then render geometry and images, using the stencil planes to |
c7b31271 | 19310 | mask out portions of the screen. Stenciling is typically used in |
8925f36f AW |
19311 | multipass rendering algorithms to achieve special effects, such as |
19312 | decals, outlining, and constructive solid geometry rendering. | |
19313 | ||
19314 | The stencil test conditionally eliminates a pixel based on the outcome | |
19315 | of a comparison between the reference value and the value in the stencil | |
c7b31271 DH |
19316 | buffer. To enable and disable the test, call @code{glEnable} and |
19317 | @code{glDisable} with argument @code{GL_STENCIL_TEST}. To specify | |
8925f36f AW |
19318 | actions based on the outcome of the stencil test, call |
19319 | @code{glStencilOp} or @code{glStencilOpSeparate}. | |
19320 | ||
19321 | There can be two separate sets of @var{func}, @var{ref}, and @var{mask} | |
19322 | parameters; one affects back-facing polygons, and the other affects | |
19323 | front-facing polygons as well as other non-polygon primitives. | |
19324 | @code{glStencilFunc} sets both front and back stencil state to the same | |
19325 | values, as if @code{glStencilFuncSeparate} were called with @var{face} | |
19326 | set to @code{GL_FRONT_AND_BACK}. | |
19327 | ||
19328 | @var{func} is a symbolic constant that determines the stencil comparison | |
c7b31271 | 19329 | function. It accepts one of eight values, shown in the following list. |
8925f36f | 19330 | @var{ref} is an integer reference value that is used in the stencil |
c7b31271 DH |
19331 | comparison. It is clamped to the range @r{[0,2^@var{n}-1]}, where |
19332 | @r{@var{n}} is the number of bitplanes in the stencil buffer. @var{mask} | |
3c9b6116 AW |
19333 | is bitwise ANDed with both the reference value and the stored stencil |
19334 | value, with the ANDed values participating in the comparison. | |
8925f36f AW |
19335 | |
19336 | If @var{stencil} represents the value stored in the corresponding | |
19337 | stencil buffer location, the following list shows the effect of each | |
c7b31271 | 19338 | comparison function that can be specified by @var{func}. Only if the |
8925f36f | 19339 | comparison succeeds is the pixel passed through to the next stage in the |
c7b31271 | 19340 | rasterization process (see @code{glStencilOp}). All tests treat |
8925f36f | 19341 | @var{stencil} values as unsigned integers in the range |
3c9b6116 AW |
19342 | @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of bitplanes in the |
19343 | stencil buffer. | |
8925f36f AW |
19344 | |
19345 | The following values are accepted by @var{func}: | |
19346 | ||
19347 | @table @asis | |
19348 | @item @code{GL_NEVER} | |
19349 | Always fails. | |
19350 | ||
19351 | @item @code{GL_LESS} | |
19352 | Passes if ( @var{ref} & @var{mask} ) < ( @var{stencil} & @var{mask} ). | |
19353 | ||
19354 | @item @code{GL_LEQUAL} | |
19355 | Passes if ( @var{ref} & @var{mask} ) <= ( @var{stencil} & @var{mask} ). | |
19356 | ||
19357 | @item @code{GL_GREATER} | |
19358 | Passes if ( @var{ref} & @var{mask} ) > ( @var{stencil} & @var{mask} ). | |
19359 | ||
19360 | @item @code{GL_GEQUAL} | |
19361 | Passes if ( @var{ref} & @var{mask} ) >= ( @var{stencil} & @var{mask} ). | |
19362 | ||
19363 | @item @code{GL_EQUAL} | |
19364 | Passes if ( @var{ref} & @var{mask} ) = ( @var{stencil} & @var{mask} ). | |
19365 | ||
19366 | @item @code{GL_NOTEQUAL} | |
19367 | Passes if ( @var{ref} & @var{mask} ) != ( @var{stencil} & @var{mask} ). | |
19368 | ||
19369 | @item @code{GL_ALWAYS} | |
19370 | Always passes. | |
19371 | ||
19372 | @end table | |
19373 | ||
8925f36f AW |
19374 | @code{GL_INVALID_ENUM} is generated if @var{func} is not one of the |
19375 | eight accepted values. | |
19376 | ||
19377 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilFuncSeparate} | |
19378 | is executed between the execution of @code{glBegin} and the | |
19379 | corresponding execution of @code{glEnd}. | |
19380 | ||
bb894c9d | 19381 | @end deftypefun |
8925f36f | 19382 | |
bb894c9d | 19383 | @deftypefun void glStencilFunc func ref mask |
3c9b6116 AW |
19384 | Set front and back function and reference value for stencil testing. |
19385 | ||
8925f36f AW |
19386 | @table @asis |
19387 | @item @var{func} | |
c7b31271 | 19388 | Specifies the test function. Eight symbolic constants are valid: |
8925f36f AW |
19389 | @code{GL_NEVER}, @code{GL_LESS}, @code{GL_LEQUAL}, @code{GL_GREATER}, |
19390 | @code{GL_GEQUAL}, @code{GL_EQUAL}, @code{GL_NOTEQUAL}, and | |
c7b31271 | 19391 | @code{GL_ALWAYS}. The initial value is @code{GL_ALWAYS}. |
8925f36f AW |
19392 | |
19393 | @item @var{ref} | |
c7b31271 DH |
19394 | Specifies the reference value for the stencil test. @var{ref} is |
19395 | clamped to the range @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the | |
19396 | number of bitplanes in the stencil buffer. The initial value is 0. | |
8925f36f AW |
19397 | |
19398 | @item @var{mask} | |
19399 | Specifies a mask that is ANDed with both the reference value and the | |
c7b31271 | 19400 | stored stencil value when the test is done. The initial value is all |
8925f36f AW |
19401 | 1's. |
19402 | ||
19403 | @end table | |
19404 | ||
8925f36f | 19405 | Stenciling, like depth-buffering, enables and disables drawing on a |
c7b31271 | 19406 | per-pixel basis. Stencil planes are first drawn into using GL drawing |
8925f36f | 19407 | primitives, then geometry and images are rendered using the stencil |
c7b31271 | 19408 | planes to mask out portions of the screen. Stenciling is typically used |
8925f36f AW |
19409 | in multipass rendering algorithms to achieve special effects, such as |
19410 | decals, outlining, and constructive solid geometry rendering. | |
19411 | ||
19412 | The stencil test conditionally eliminates a pixel based on the outcome | |
19413 | of a comparison between the reference value and the value in the stencil | |
c7b31271 DH |
19414 | buffer. To enable and disable the test, call @code{glEnable} and |
19415 | @code{glDisable} with argument @code{GL_STENCIL_TEST}. To specify | |
8925f36f AW |
19416 | actions based on the outcome of the stencil test, call |
19417 | @code{glStencilOp} or @code{glStencilOpSeparate}. | |
19418 | ||
19419 | There can be two separate sets of @var{func}, @var{ref}, and @var{mask} | |
19420 | parameters; one affects back-facing polygons, and the other affects | |
19421 | front-facing polygons as well as other non-polygon primitives. | |
19422 | @code{glStencilFunc} sets both front and back stencil state to the same | |
c7b31271 | 19423 | values. Use @code{glStencilFuncSeparate} to set front and back stencil |
8925f36f AW |
19424 | state to different values. |
19425 | ||
19426 | @var{func} is a symbolic constant that determines the stencil comparison | |
c7b31271 | 19427 | function. It accepts one of eight values, shown in the following list. |
8925f36f | 19428 | @var{ref} is an integer reference value that is used in the stencil |
c7b31271 DH |
19429 | comparison. It is clamped to the range @r{[0,2^@var{n}-1]}, where |
19430 | @r{@var{n}} is the number of bitplanes in the stencil buffer. @var{mask} | |
3c9b6116 AW |
19431 | is bitwise ANDed with both the reference value and the stored stencil |
19432 | value, with the ANDed values participating in the comparison. | |
8925f36f AW |
19433 | |
19434 | If @var{stencil} represents the value stored in the corresponding | |
19435 | stencil buffer location, the following list shows the effect of each | |
c7b31271 | 19436 | comparison function that can be specified by @var{func}. Only if the |
8925f36f | 19437 | comparison succeeds is the pixel passed through to the next stage in the |
c7b31271 | 19438 | rasterization process (see @code{glStencilOp}). All tests treat |
8925f36f | 19439 | @var{stencil} values as unsigned integers in the range |
3c9b6116 AW |
19440 | @r{[0,2^@var{n}-1]}, where @r{@var{n}} is the number of bitplanes in the |
19441 | stencil buffer. | |
8925f36f AW |
19442 | |
19443 | The following values are accepted by @var{func}: | |
19444 | ||
19445 | @table @asis | |
19446 | @item @code{GL_NEVER} | |
19447 | Always fails. | |
19448 | ||
19449 | @item @code{GL_LESS} | |
19450 | Passes if ( @var{ref} & @var{mask} ) < ( @var{stencil} & @var{mask} ). | |
19451 | ||
19452 | @item @code{GL_LEQUAL} | |
19453 | Passes if ( @var{ref} & @var{mask} ) <= ( @var{stencil} & @var{mask} ). | |
19454 | ||
19455 | @item @code{GL_GREATER} | |
19456 | Passes if ( @var{ref} & @var{mask} ) > ( @var{stencil} & @var{mask} ). | |
19457 | ||
19458 | @item @code{GL_GEQUAL} | |
19459 | Passes if ( @var{ref} & @var{mask} ) >= ( @var{stencil} & @var{mask} ). | |
19460 | ||
19461 | @item @code{GL_EQUAL} | |
19462 | Passes if ( @var{ref} & @var{mask} ) = ( @var{stencil} & @var{mask} ). | |
19463 | ||
19464 | @item @code{GL_NOTEQUAL} | |
19465 | Passes if ( @var{ref} & @var{mask} ) != ( @var{stencil} & @var{mask} ). | |
19466 | ||
19467 | @item @code{GL_ALWAYS} | |
19468 | Always passes. | |
19469 | ||
19470 | @end table | |
19471 | ||
8925f36f AW |
19472 | @code{GL_INVALID_ENUM} is generated if @var{func} is not one of the |
19473 | eight accepted values. | |
19474 | ||
19475 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilFunc} is | |
19476 | executed between the execution of @code{glBegin} and the corresponding | |
19477 | execution of @code{glEnd}. | |
19478 | ||
bb894c9d | 19479 | @end deftypefun |
8925f36f | 19480 | |
bb894c9d | 19481 | @deftypefun void glStencilMaskSeparate face mask |
3c9b6116 AW |
19482 | Control the front and/or back writing of individual bits in the stencil |
19483 | planes. | |
19484 | ||
8925f36f AW |
19485 | @table @asis |
19486 | @item @var{face} | |
19487 | Specifies whether the front and/or back stencil writemask is updated. | |
19488 | Three symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and | |
19489 | @code{GL_FRONT_AND_BACK}. | |
19490 | ||
19491 | @item @var{mask} | |
19492 | Specifies a bit mask to enable and disable writing of individual bits in | |
c7b31271 | 19493 | the stencil planes. Initially, the mask is all 1's. |
8925f36f AW |
19494 | |
19495 | @end table | |
19496 | ||
8925f36f | 19497 | @code{glStencilMaskSeparate} controls the writing of individual bits in |
c7b31271 | 19498 | the stencil planes. The least significant @r{@var{n}} bits of |
3c9b6116 | 19499 | @var{mask}, where @r{@var{n}} is the number of bits in the stencil |
c7b31271 DH |
19500 | buffer, specify a mask. Where a 1 appears in the mask, it's possible to |
19501 | write to the corresponding bit in the stencil buffer. Where a 0 | |
19502 | appears, the corresponding bit is write-protected. Initially, all bits | |
19503 | are enabled for writing. | |
8925f36f AW |
19504 | |
19505 | There can be two separate @var{mask} writemasks; one affects back-facing | |
19506 | polygons, and the other affects front-facing polygons as well as other | |
c7b31271 | 19507 | non-polygon primitives. @code{glStencilMask} sets both front and back |
8925f36f AW |
19508 | stencil writemasks to the same values, as if |
19509 | @code{glStencilMaskSeparate} were called with @var{face} set to | |
19510 | @code{GL_FRONT_AND_BACK}. | |
19511 | ||
8925f36f AW |
19512 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilMaskSeparate} |
19513 | is executed between the execution of @code{glBegin} and the | |
19514 | corresponding execution of @code{glEnd}. | |
19515 | ||
bb894c9d | 19516 | @end deftypefun |
8925f36f | 19517 | |
bb894c9d | 19518 | @deftypefun void glStencilMask mask |
3c9b6116 AW |
19519 | Control the front and back writing of individual bits in the stencil |
19520 | planes. | |
19521 | ||
8925f36f AW |
19522 | @table @asis |
19523 | @item @var{mask} | |
19524 | Specifies a bit mask to enable and disable writing of individual bits in | |
c7b31271 | 19525 | the stencil planes. Initially, the mask is all 1's. |
8925f36f AW |
19526 | |
19527 | @end table | |
19528 | ||
8925f36f | 19529 | @code{glStencilMask} controls the writing of individual bits in the |
c7b31271 | 19530 | stencil planes. The least significant @r{@var{n}} bits of @var{mask}, |
3c9b6116 | 19531 | where @r{@var{n}} is the number of bits in the stencil buffer, specify a |
c7b31271 DH |
19532 | mask. Where a 1 appears in the mask, it's possible to write to the |
19533 | corresponding bit in the stencil buffer. Where a 0 appears, the | |
19534 | corresponding bit is write-protected. Initially, all bits are enabled | |
8925f36f AW |
19535 | for writing. |
19536 | ||
19537 | There can be two separate @var{mask} writemasks; one affects back-facing | |
19538 | polygons, and the other affects front-facing polygons as well as other | |
c7b31271 DH |
19539 | non-polygon primitives. @code{glStencilMask} sets both front and back |
19540 | stencil writemasks to the same values. Use @code{glStencilMaskSeparate} | |
8925f36f AW |
19541 | to set front and back stencil writemasks to different values. |
19542 | ||
8925f36f AW |
19543 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilMask} is |
19544 | executed between the execution of @code{glBegin} and the corresponding | |
19545 | execution of @code{glEnd}. | |
19546 | ||
bb894c9d | 19547 | @end deftypefun |
8925f36f | 19548 | |
bb894c9d | 19549 | @deftypefun void glStencilOpSeparate face sfail dpfail dppass |
3c9b6116 AW |
19550 | Set front and/or back stencil test actions. |
19551 | ||
8925f36f AW |
19552 | @table @asis |
19553 | @item @var{face} | |
c7b31271 | 19554 | Specifies whether front and/or back stencil state is updated. Three |
8925f36f AW |
19555 | symbolic constants are valid: @code{GL_FRONT}, @code{GL_BACK}, and |
19556 | @code{GL_FRONT_AND_BACK}. | |
19557 | ||
19558 | @item @var{sfail} | |
c7b31271 DH |
19559 | Specifies the action to take when the stencil test fails. Eight |
19560 | symbolic constants are accepted: @code{GL_KEEP}, @code{GL_ZERO}, | |
8925f36f | 19561 | @code{GL_REPLACE}, @code{GL_INCR}, @code{GL_INCR_WRAP}, @code{GL_DECR}, |
c7b31271 | 19562 | @code{GL_DECR_WRAP}, and @code{GL_INVERT}. The initial value is |
8925f36f AW |
19563 | @code{GL_KEEP}. |
19564 | ||
19565 | @item @var{dpfail} | |
19566 | Specifies the stencil action when the stencil test passes, but the depth | |
c7b31271 DH |
19567 | test fails. @var{dpfail} accepts the same symbolic constants as |
19568 | @var{sfail}. The initial value is @code{GL_KEEP}. | |
8925f36f AW |
19569 | |
19570 | @item @var{dppass} | |
19571 | Specifies the stencil action when both the stencil test and the depth | |
19572 | test pass, or when the stencil test passes and either there is no depth | |
c7b31271 DH |
19573 | buffer or depth testing is not enabled. @var{dppass} accepts the same |
19574 | symbolic constants as @var{sfail}. The initial value is @code{GL_KEEP}. | |
8925f36f AW |
19575 | |
19576 | @end table | |
19577 | ||
8925f36f | 19578 | Stenciling, like depth-buffering, enables and disables drawing on a |
c7b31271 | 19579 | per-pixel basis. You draw into the stencil planes using GL drawing |
8925f36f | 19580 | primitives, then render geometry and images, using the stencil planes to |
c7b31271 | 19581 | mask out portions of the screen. Stenciling is typically used in |
8925f36f AW |
19582 | multipass rendering algorithms to achieve special effects, such as |
19583 | decals, outlining, and constructive solid geometry rendering. | |
19584 | ||
19585 | The stencil test conditionally eliminates a pixel based on the outcome | |
19586 | of a comparison between the value in the stencil buffer and a reference | |
c7b31271 | 19587 | value. To enable and disable the test, call @code{glEnable} and |
8925f36f AW |
19588 | @code{glDisable} with argument @code{GL_STENCIL_TEST}; to control it, |
19589 | call @code{glStencilFunc} or @code{glStencilFuncSeparate}. | |
19590 | ||
19591 | There can be two separate sets of @var{sfail}, @var{dpfail}, and | |
19592 | @var{dppass} parameters; one affects back-facing polygons, and the other | |
19593 | affects front-facing polygons as well as other non-polygon primitives. | |
19594 | @code{glStencilOp} sets both front and back stencil state to the same | |
19595 | values, as if @code{glStencilOpSeparate} were called with @var{face} set | |
19596 | to @code{GL_FRONT_AND_BACK}. | |
19597 | ||
19598 | @code{glStencilOpSeparate} takes three arguments that indicate what | |
c7b31271 | 19599 | happens to the stored stencil value while stenciling is enabled. If the |
8925f36f AW |
19600 | stencil test fails, no change is made to the pixel's color or depth |
19601 | buffers, and @var{sfail} specifies what happens to the stencil buffer | |
c7b31271 | 19602 | contents. The following eight actions are possible. |
8925f36f AW |
19603 | |
19604 | @table @asis | |
19605 | @item @code{GL_KEEP} | |
19606 | Keeps the current value. | |
19607 | ||
19608 | @item @code{GL_ZERO} | |
19609 | Sets the stencil buffer value to 0. | |
19610 | ||
19611 | @item @code{GL_REPLACE} | |
19612 | Sets the stencil buffer value to @var{ref}, as specified by | |
19613 | @code{glStencilFunc}. | |
19614 | ||
19615 | @item @code{GL_INCR} | |
c7b31271 | 19616 | Increments the current stencil buffer value. Clamps to the maximum |
8925f36f AW |
19617 | representable unsigned value. |
19618 | ||
19619 | @item @code{GL_INCR_WRAP} | |
c7b31271 | 19620 | Increments the current stencil buffer value. Wraps stencil buffer value |
8925f36f AW |
19621 | to zero when incrementing the maximum representable unsigned value. |
19622 | ||
19623 | @item @code{GL_DECR} | |
c7b31271 | 19624 | Decrements the current stencil buffer value. Clamps to 0. |
8925f36f AW |
19625 | |
19626 | @item @code{GL_DECR_WRAP} | |
c7b31271 | 19627 | Decrements the current stencil buffer value. Wraps stencil buffer value |
8925f36f AW |
19628 | to the maximum representable unsigned value when decrementing a stencil |
19629 | buffer value of zero. | |
19630 | ||
19631 | @item @code{GL_INVERT} | |
19632 | Bitwise inverts the current stencil buffer value. | |
19633 | ||
19634 | @end table | |
19635 | ||
c7b31271 DH |
19636 | Stencil buffer values are treated as unsigned integers. When |
19637 | incremented and decremented, values are clamped to 0 and | |
19638 | @r{2^@var{n}-1}, where @r{@var{n}} is the value returned by querying | |
19639 | @code{GL_STENCIL_BITS}. | |
8925f36f AW |
19640 | |
19641 | The other two arguments to @code{glStencilOpSeparate} specify stencil | |
19642 | buffer actions that depend on whether subsequent depth buffer tests | |
19643 | succeed (@var{dppass}) or fail (@var{dpfail}) (see @code{glDepthFunc}). | |
19644 | The actions are specified using the same eight symbolic constants as | |
c7b31271 DH |
19645 | @var{sfail}. Note that @var{dpfail} is ignored when there is no depth |
19646 | buffer, or when the depth buffer is not enabled. In these cases, | |
8925f36f AW |
19647 | @var{sfail} and @var{dppass} specify stencil action when the stencil |
19648 | test fails and passes, respectively. | |
19649 | ||
8925f36f AW |
19650 | @code{GL_INVALID_ENUM} is generated if @var{face} is any value other |
19651 | than @code{GL_FRONT}, @code{GL_BACK}, or @code{GL_FRONT_AND_BACK}. | |
19652 | ||
19653 | @code{GL_INVALID_ENUM} is generated if @var{sfail}, @var{dpfail}, or | |
19654 | @var{dppass} is any value other than the eight defined constant values. | |
19655 | ||
19656 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilOpSeparate} | |
19657 | is executed between the execution of @code{glBegin} and the | |
19658 | corresponding execution of @code{glEnd}. | |
19659 | ||
bb894c9d | 19660 | @end deftypefun |
8925f36f | 19661 | |
bb894c9d | 19662 | @deftypefun void glStencilOp sfail dpfail dppass |
3c9b6116 AW |
19663 | Set front and back stencil test actions. |
19664 | ||
8925f36f AW |
19665 | @table @asis |
19666 | @item @var{sfail} | |
c7b31271 DH |
19667 | Specifies the action to take when the stencil test fails. Eight |
19668 | symbolic constants are accepted: @code{GL_KEEP}, @code{GL_ZERO}, | |
8925f36f | 19669 | @code{GL_REPLACE}, @code{GL_INCR}, @code{GL_INCR_WRAP}, @code{GL_DECR}, |
c7b31271 | 19670 | @code{GL_DECR_WRAP}, and @code{GL_INVERT}. The initial value is |
8925f36f AW |
19671 | @code{GL_KEEP}. |
19672 | ||
19673 | @item @var{dpfail} | |
19674 | Specifies the stencil action when the stencil test passes, but the depth | |
c7b31271 DH |
19675 | test fails. @var{dpfail} accepts the same symbolic constants as |
19676 | @var{sfail}. The initial value is @code{GL_KEEP}. | |
8925f36f AW |
19677 | |
19678 | @item @var{dppass} | |
19679 | Specifies the stencil action when both the stencil test and the depth | |
19680 | test pass, or when the stencil test passes and either there is no depth | |
c7b31271 DH |
19681 | buffer or depth testing is not enabled. @var{dppass} accepts the same |
19682 | symbolic constants as @var{sfail}. The initial value is @code{GL_KEEP}. | |
8925f36f AW |
19683 | |
19684 | @end table | |
19685 | ||
8925f36f | 19686 | Stenciling, like depth-buffering, enables and disables drawing on a |
c7b31271 | 19687 | per-pixel basis. You draw into the stencil planes using GL drawing |
8925f36f | 19688 | primitives, then render geometry and images, using the stencil planes to |
c7b31271 | 19689 | mask out portions of the screen. Stenciling is typically used in |
8925f36f AW |
19690 | multipass rendering algorithms to achieve special effects, such as |
19691 | decals, outlining, and constructive solid geometry rendering. | |
19692 | ||
19693 | The stencil test conditionally eliminates a pixel based on the outcome | |
19694 | of a comparison between the value in the stencil buffer and a reference | |
c7b31271 | 19695 | value. To enable and disable the test, call @code{glEnable} and |
8925f36f AW |
19696 | @code{glDisable} with argument @code{GL_STENCIL_TEST}; to control it, |
19697 | call @code{glStencilFunc} or @code{glStencilFuncSeparate}. | |
19698 | ||
19699 | There can be two separate sets of @var{sfail}, @var{dpfail}, and | |
19700 | @var{dppass} parameters; one affects back-facing polygons, and the other | |
19701 | affects front-facing polygons as well as other non-polygon primitives. | |
19702 | @code{glStencilOp} sets both front and back stencil state to the same | |
c7b31271 | 19703 | values. Use @code{glStencilOpSeparate} to set front and back stencil |
8925f36f AW |
19704 | state to different values. |
19705 | ||
19706 | @code{glStencilOp} takes three arguments that indicate what happens to | |
c7b31271 | 19707 | the stored stencil value while stenciling is enabled. If the stencil |
8925f36f | 19708 | test fails, no change is made to the pixel's color or depth buffers, and |
c7b31271 | 19709 | @var{sfail} specifies what happens to the stencil buffer contents. The |
8925f36f AW |
19710 | following eight actions are possible. |
19711 | ||
19712 | @table @asis | |
19713 | @item @code{GL_KEEP} | |
19714 | Keeps the current value. | |
19715 | ||
19716 | @item @code{GL_ZERO} | |
19717 | Sets the stencil buffer value to 0. | |
19718 | ||
19719 | @item @code{GL_REPLACE} | |
19720 | Sets the stencil buffer value to @var{ref}, as specified by | |
19721 | @code{glStencilFunc}. | |
19722 | ||
19723 | @item @code{GL_INCR} | |
c7b31271 | 19724 | Increments the current stencil buffer value. Clamps to the maximum |
8925f36f AW |
19725 | representable unsigned value. |
19726 | ||
19727 | @item @code{GL_INCR_WRAP} | |
c7b31271 | 19728 | Increments the current stencil buffer value. Wraps stencil buffer value |
8925f36f AW |
19729 | to zero when incrementing the maximum representable unsigned value. |
19730 | ||
19731 | @item @code{GL_DECR} | |
c7b31271 | 19732 | Decrements the current stencil buffer value. Clamps to 0. |
8925f36f AW |
19733 | |
19734 | @item @code{GL_DECR_WRAP} | |
c7b31271 | 19735 | Decrements the current stencil buffer value. Wraps stencil buffer value |
8925f36f AW |
19736 | to the maximum representable unsigned value when decrementing a stencil |
19737 | buffer value of zero. | |
19738 | ||
19739 | @item @code{GL_INVERT} | |
19740 | Bitwise inverts the current stencil buffer value. | |
19741 | ||
19742 | @end table | |
19743 | ||
c7b31271 DH |
19744 | Stencil buffer values are treated as unsigned integers. When |
19745 | incremented and decremented, values are clamped to 0 and | |
19746 | @r{2^@var{n}-1}, where @r{@var{n}} is the value returned by querying | |
19747 | @code{GL_STENCIL_BITS}. | |
8925f36f AW |
19748 | |
19749 | The other two arguments to @code{glStencilOp} specify stencil buffer | |
19750 | actions that depend on whether subsequent depth buffer tests succeed | |
c7b31271 | 19751 | (@var{dppass}) or fail (@var{dpfail}) (see @code{glDepthFunc}). The |
8925f36f | 19752 | actions are specified using the same eight symbolic constants as |
c7b31271 DH |
19753 | @var{sfail}. Note that @var{dpfail} is ignored when there is no depth |
19754 | buffer, or when the depth buffer is not enabled. In these cases, | |
8925f36f AW |
19755 | @var{sfail} and @var{dppass} specify stencil action when the stencil |
19756 | test fails and passes, respectively. | |
19757 | ||
8925f36f AW |
19758 | @code{GL_INVALID_ENUM} is generated if @var{sfail}, @var{dpfail}, or |
19759 | @var{dppass} is any value other than the eight defined constant values. | |
19760 | ||
19761 | @code{GL_INVALID_OPERATION} is generated if @code{glStencilOp} is | |
19762 | executed between the execution of @code{glBegin} and the corresponding | |
19763 | execution of @code{glEnd}. | |
19764 | ||
bb894c9d | 19765 | @end deftypefun |
8925f36f | 19766 | |
bb894c9d | 19767 | @deftypefun void glTexCoordPointer size type stride pointer |
3c9b6116 AW |
19768 | Define an array of texture coordinates. |
19769 | ||
8925f36f AW |
19770 | @table @asis |
19771 | @item @var{size} | |
c7b31271 DH |
19772 | Specifies the number of coordinates per array element. Must be 1, 2, 3, |
19773 | or 4. The initial value is 4. | |
8925f36f AW |
19774 | |
19775 | @item @var{type} | |
c7b31271 | 19776 | Specifies the data type of each texture coordinate. Symbolic constants |
8925f36f | 19777 | @code{GL_SHORT}, @code{GL_INT}, @code{GL_FLOAT}, or @code{GL_DOUBLE} are |
c7b31271 | 19778 | accepted. The initial value is @code{GL_FLOAT}. |
8925f36f AW |
19779 | |
19780 | @item @var{stride} | |
19781 | Specifies the byte offset between consecutive texture coordinate sets. | |
19782 | If @var{stride} is 0, the array elements are understood to be tightly | |
c7b31271 | 19783 | packed. The initial value is 0. |
8925f36f AW |
19784 | |
19785 | @item @var{pointer} | |
19786 | Specifies a pointer to the first coordinate of the first texture | |
c7b31271 | 19787 | coordinate set in the array. The initial value is 0. |
8925f36f AW |
19788 | |
19789 | @end table | |
19790 | ||
8925f36f | 19791 | @code{glTexCoordPointer} specifies the location and data format of an |
c7b31271 DH |
19792 | array of texture coordinates to use when rendering. @var{size} |
19793 | specifies the number of coordinates per texture coordinate set, and must | |
19794 | be 1, 2, 3, or 4. @var{type} specifies the data type of each texture | |
19795 | coordinate, and @var{stride} specifies the byte stride from one texture | |
19796 | coordinate set to the next, allowing vertices and attributes to be | |
19797 | packed into a single array or stored in separate arrays. (Single-array | |
19798 | storage may be more efficient on some implementations; see | |
19799 | @code{glInterleavedArrays}.) | |
8925f36f AW |
19800 | |
19801 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
19802 | target (see @code{glBindBuffer}) while a texture coordinate array is | |
19803 | specified, @var{pointer} is treated as a byte offset into the buffer | |
c7b31271 | 19804 | object's data store. Also, the buffer object binding |
8925f36f AW |
19805 | (@code{GL_ARRAY_BUFFER_BINDING}) is saved as texture coordinate vertex |
19806 | array client-side state (@code{GL_TEXTURE_COORD_ARRAY_BUFFER_BINDING}). | |
19807 | ||
19808 | When a texture coordinate array is specified, @var{size}, @var{type}, | |
19809 | @var{stride}, and @var{pointer} are saved as client-side state, in | |
19810 | addition to the current vertex array buffer object binding. | |
19811 | ||
19812 | To enable and disable a texture coordinate array, call | |
19813 | @code{glEnableClientState} and @code{glDisableClientState} with the | |
c7b31271 | 19814 | argument @code{GL_TEXTURE_COORD_ARRAY}. If enabled, the texture |
8925f36f AW |
19815 | coordinate array is used when @code{glArrayElement}, |
19816 | @code{glDrawArrays}, @code{glMultiDrawArrays}, @code{glDrawElements}, | |
19817 | @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called. | |
19818 | ||
8925f36f AW |
19819 | @code{GL_INVALID_VALUE} is generated if @var{size} is not 1, 2, 3, or 4. |
19820 | ||
19821 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted | |
19822 | value. | |
19823 | ||
19824 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
19825 | ||
bb894c9d | 19826 | @end deftypefun |
8925f36f | 19827 | |
d172eed9 AW |
19828 | @deftypefun void glTexCoord1s s |
19829 | @deftypefunx void glTexCoord1i s | |
ca09631c | 19830 | @deftypefunx void glTexCoord1f s |
d172eed9 AW |
19831 | @deftypefunx void glTexCoord1d s |
19832 | @deftypefunx void glTexCoord2s s t | |
bb894c9d | 19833 | @deftypefunx void glTexCoord2i s t |
ca09631c | 19834 | @deftypefunx void glTexCoord2f s t |
d172eed9 AW |
19835 | @deftypefunx void glTexCoord2d s t |
19836 | @deftypefunx void glTexCoord3s s t r | |
bb894c9d | 19837 | @deftypefunx void glTexCoord3i s t r |
ca09631c | 19838 | @deftypefunx void glTexCoord3f s t r |
d172eed9 AW |
19839 | @deftypefunx void glTexCoord3d s t r |
19840 | @deftypefunx void glTexCoord4s s t r q | |
bb894c9d | 19841 | @deftypefunx void glTexCoord4i s t r q |
ca09631c | 19842 | @deftypefunx void glTexCoord4f s t r q |
d172eed9 AW |
19843 | @deftypefunx void glTexCoord4d s t r q |
19844 | @deftypefunx void glTexCoord1sv v | |
19845 | @deftypefunx void glTexCoord1iv v | |
19846 | @deftypefunx void glTexCoord1fv v | |
19847 | @deftypefunx void glTexCoord1dv v | |
19848 | @deftypefunx void glTexCoord2sv v | |
19849 | @deftypefunx void glTexCoord2iv v | |
19850 | @deftypefunx void glTexCoord2fv v | |
19851 | @deftypefunx void glTexCoord2dv v | |
19852 | @deftypefunx void glTexCoord3sv v | |
19853 | @deftypefunx void glTexCoord3iv v | |
19854 | @deftypefunx void glTexCoord3fv v | |
19855 | @deftypefunx void glTexCoord3dv v | |
19856 | @deftypefunx void glTexCoord4sv v | |
19857 | @deftypefunx void glTexCoord4iv v | |
19858 | @deftypefunx void glTexCoord4fv v | |
19859 | @deftypefunx void glTexCoord4dv v | |
3c9b6116 AW |
19860 | Set the current texture coordinates. |
19861 | ||
8925f36f AW |
19862 | @table @asis |
19863 | @item @var{s} | |
19864 | @itemx @var{t} | |
19865 | @itemx @var{r} | |
19866 | @itemx @var{q} | |
c7b31271 | 19867 | Specify @var{s}, @var{t}, @var{r}, and @var{q} texture coordinates. Not |
8925f36f AW |
19868 | all parameters are present in all forms of the command. |
19869 | ||
19870 | @end table | |
19871 | ||
8925f36f | 19872 | @code{glTexCoord} specifies texture coordinates in one, two, three, or |
c7b31271 DH |
19873 | four dimensions. @code{glTexCoord1} sets the current texture |
19874 | coordinates to @r{(@var{s},001)}; a call to @code{glTexCoord2} sets them | |
19875 | to @r{(@var{s},@var{t}01)}. Similarly, @code{glTexCoord3} specifies the | |
3c9b6116 | 19876 | texture coordinates as @r{(@var{s},@var{t}@var{r}1)}, and |
8925f36f | 19877 | @code{glTexCoord4} defines all four components explicitly as |
3c9b6116 | 19878 | @r{(@var{s},@var{t}@var{r}@var{q})}. |
8925f36f AW |
19879 | |
19880 | The current texture coordinates are part of the data that is associated | |
c7b31271 | 19881 | with each vertex and with the current raster position. Initially, the |
8925f36f AW |
19882 | values for @var{s}, @var{t}, @var{r}, and @var{q} are (0, 0, 0, 1). |
19883 | ||
19884 | ||
19885 | ||
bb894c9d | 19886 | @end deftypefun |
8925f36f | 19887 | |
bb894c9d AW |
19888 | @deftypefun void glTexEnvf target pname param |
19889 | @deftypefunx void glTexEnvi target pname param | |
d172eed9 AW |
19890 | @deftypefunx void glTexEnvfv target pname params |
19891 | @deftypefunx void glTexEnviv target pname params | |
3c9b6116 AW |
19892 | Set texture environment parameters. |
19893 | ||
8925f36f AW |
19894 | @table @asis |
19895 | @item @var{target} | |
c7b31271 | 19896 | Specifies a texture environment. May be @code{GL_TEXTURE_ENV}, |
8925f36f AW |
19897 | @code{GL_TEXTURE_FILTER_CONTROL} or @code{GL_POINT_SPRITE}. |
19898 | ||
19899 | @item @var{pname} | |
19900 | Specifies the symbolic name of a single-valued texture environment | |
c7b31271 | 19901 | parameter. May be either @code{GL_TEXTURE_ENV_MODE}, |
8925f36f AW |
19902 | @code{GL_TEXTURE_LOD_BIAS}, @code{GL_COMBINE_RGB}, |
19903 | @code{GL_COMBINE_ALPHA}, @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, | |
19904 | @code{GL_SRC2_RGB}, @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, | |
19905 | @code{GL_SRC2_ALPHA}, @code{GL_OPERAND0_RGB}, @code{GL_OPERAND1_RGB}, | |
19906 | @code{GL_OPERAND2_RGB}, @code{GL_OPERAND0_ALPHA}, | |
19907 | @code{GL_OPERAND1_ALPHA}, @code{GL_OPERAND2_ALPHA}, @code{GL_RGB_SCALE}, | |
19908 | @code{GL_ALPHA_SCALE}, or @code{GL_COORD_REPLACE}. | |
19909 | ||
19910 | @item @var{param} | |
19911 | Specifies a single symbolic constant, one of @code{GL_ADD}, | |
19912 | @code{GL_ADD_SIGNED}, @code{GL_INTERPOLATE}, @code{GL_MODULATE}, | |
19913 | @code{GL_DECAL}, @code{GL_BLEND}, @code{GL_REPLACE}, @code{GL_SUBTRACT}, | |
19914 | @code{GL_COMBINE}, @code{GL_TEXTURE}, @code{GL_CONSTANT}, | |
19915 | @code{GL_PRIMARY_COLOR}, @code{GL_PREVIOUS}, @code{GL_SRC_COLOR}, | |
19916 | @code{GL_ONE_MINUS_SRC_COLOR}, @code{GL_SRC_ALPHA}, | |
19917 | @code{GL_ONE_MINUS_SRC_ALPHA}, a single boolean value for the point | |
19918 | sprite texture coordinate replacement, a single floating-point value for | |
19919 | the texture level-of-detail bias, or 1.0, 2.0, or 4.0 when specifying | |
19920 | the @code{GL_RGB_SCALE} or @code{GL_ALPHA_SCALE}. | |
19921 | ||
19922 | @end table | |
19923 | ||
8925f36f | 19924 | A texture environment specifies how texture values are interpreted when |
c7b31271 | 19925 | a fragment is textured. When @var{target} is |
8925f36f | 19926 | @code{GL_TEXTURE_FILTER_CONTROL}, @var{pname} must be |
c7b31271 | 19927 | @code{GL_TEXTURE_LOD_BIAS}. When @var{target} is @code{GL_TEXTURE_ENV}, |
8925f36f AW |
19928 | @var{pname} can be @code{GL_TEXTURE_ENV_MODE}, |
19929 | @code{GL_TEXTURE_ENV_COLOR}, @code{GL_COMBINE_RGB}, | |
19930 | @code{GL_COMBINE_ALPHA}, @code{GL_RGB_SCALE}, @code{GL_ALPHA_SCALE}, | |
19931 | @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, @code{GL_SRC2_RGB}, | |
19932 | @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, or @code{GL_SRC2_ALPHA}. | |
19933 | ||
19934 | If @var{pname} is @code{GL_TEXTURE_ENV_MODE}, then @var{params} is (or | |
c7b31271 | 19935 | points to) the symbolic name of a texture function. Six texture |
8925f36f AW |
19936 | functions may be specified: @code{GL_ADD}, @code{GL_MODULATE}, |
19937 | @code{GL_DECAL}, @code{GL_BLEND}, @code{GL_REPLACE}, or | |
19938 | @code{GL_COMBINE}. | |
19939 | ||
19940 | The following table shows the correspondence of filtered texture values | |
3c9b6116 AW |
19941 | @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}}, |
19942 | @r{@var{A}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{I}_@var{t}} to texture | |
c7b31271 | 19943 | source components. @r{@var{C}_@var{s}} and @r{@var{A}_@var{s}} are used |
3c9b6116 | 19944 | by the texture functions described below. |
8925f36f AW |
19945 | |
19946 | ||
19947 | ||
19948 | @table @asis | |
19949 | @item | |
19950 | Texture Base Internal Format | |
3c9b6116 | 19951 | @r{@code{C}_@var{s}}, @r{@code{A}_@var{s}} |
8925f36f AW |
19952 | |
19953 | @item @code{GL_ALPHA} | |
3c9b6116 | 19954 | (0, 0, 0) , @r{@var{A}_@var{t}} |
8925f36f AW |
19955 | |
19956 | @item @code{GL_LUMINANCE} | |
3c9b6116 | 19957 | ( @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}} ) , 1 |
8925f36f AW |
19958 | |
19959 | @item @code{GL_LUMINANCE_ALPHA} | |
3c9b6116 AW |
19960 | ( @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}}, @r{@var{L}_@var{t}} ) , |
19961 | @r{@var{A}_@var{t}} | |
8925f36f AW |
19962 | |
19963 | @item @code{GL_INTENSITY} | |
3c9b6116 AW |
19964 | ( @r{@var{I}_@var{t}}, @r{@var{I}_@var{t}}, @r{@var{I}_@var{t}} ) , |
19965 | @r{@var{I}_@var{t}} | |
8925f36f AW |
19966 | |
19967 | @item @code{GL_RGB} | |
3c9b6116 | 19968 | ( @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}} ) , 1 |
8925f36f AW |
19969 | |
19970 | @item @code{GL_RGBA} | |
3c9b6116 AW |
19971 | ( @r{@var{R}_@var{t}}, @r{@var{G}_@var{t}}, @r{@var{B}_@var{t}} ) , |
19972 | @r{@var{A}_@var{t}} | |
8925f36f AW |
19973 | |
19974 | @end table | |
19975 | ||
19976 | A texture function acts on the fragment to be textured using the texture | |
19977 | image value that applies to the fragment (see @code{glTexParameter}) and | |
c7b31271 | 19978 | produces an RGBA color for that fragment. The following table shows how |
8925f36f | 19979 | the RGBA color is produced for each of the first five texture functions |
c7b31271 DH |
19980 | that can be chosen. @r{@var{C}} is a triple of color values (RGB) and |
19981 | @r{@var{A}} is the associated alpha value. RGBA values extracted from a | |
19982 | texture image are in the range [0,1]. The subscript @r{@var{p}} refers | |
3c9b6116 AW |
19983 | to the color computed from the previous texture stage (or the incoming |
19984 | fragment if processing texture stage 0), the subscript @r{@var{s}} to | |
19985 | the texture source color, the subscript @r{@var{c}} to the texture | |
19986 | environment color, and the subscript @r{@var{v}} indicates a value | |
19987 | produced by the texture function. | |
8925f36f AW |
19988 | |
19989 | ||
19990 | ||
19991 | @table @asis | |
19992 | @item | |
19993 | Texture Base Internal Format | |
19994 | @code{Value}, @code{GL_REPLACE} Function , @code{GL_MODULATE} Function , | |
19995 | @code{GL_DECAL} Function , @code{GL_BLEND} Function , @code{GL_ADD} | |
19996 | Function | |
19997 | ||
19998 | @item @code{GL_ALPHA} | |
3c9b6116 AW |
19999 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{p}}, @r{@var{C}_@var{p}}, |
20000 | undefined , @r{@var{C}_@var{p}}, @r{@var{C}_@var{p}} | |
8925f36f AW |
20001 | |
20002 | @item | |
3c9b6116 AW |
20003 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}}, |
20004 | @r{@var{A}_@var{p}@var{A}_@var{s}}, , | |
20005 | @r{@var{A}_@var{v}=@var{A}_@var{p}@var{A}_@var{s}}, | |
20006 | @r{@var{A}_@var{p}@var{A}_@var{s}} | |
8925f36f AW |
20007 | |
20008 | @item @code{GL_LUMINANCE} | |
3c9b6116 AW |
20009 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
20010 | @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined , | |
20011 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
20012 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
20013 | |
20014 | @item | |
20015 | (or 1) | |
3c9b6116 AW |
20016 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, , |
20017 | @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}} | |
8925f36f AW |
20018 | |
20019 | @item @code{GL_LUMINANCE_ALPHA} | |
3c9b6116 AW |
20020 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
20021 | @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined , | |
20022 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
20023 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
20024 | |
20025 | @item | |
20026 | (or 2) | |
3c9b6116 AW |
20027 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}}, |
20028 | @r{@var{A}_@var{p}@var{A}_@var{s}}, , | |
20029 | @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}@var{A}_@var{s}} | |
8925f36f AW |
20030 | |
20031 | @item @code{GL_INTENSITY} | |
3c9b6116 AW |
20032 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
20033 | @r{@var{C}_@var{p}@var{C}_@var{s}}, undefined , | |
20034 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
20035 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
20036 | |
20037 | @item | |
3c9b6116 AW |
20038 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}}, |
20039 | @r{@var{A}_@var{p}@var{A}_@var{s}}, , | |
20040 | @r{@var{A}_@var{p}(1-@var{A}_@var{s},)+@var{A}_@var{c}@var{A}_@var{s}}, | |
20041 | @r{@var{A}_@var{p}+@var{A}_@var{s}} | |
8925f36f AW |
20042 | |
20043 | @item @code{GL_RGB} | |
3c9b6116 AW |
20044 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
20045 | @r{@var{C}_@var{p}@var{C}_@var{s}}, @r{@var{C}_@var{s}}, | |
20046 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
20047 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
20048 | |
20049 | @item | |
20050 | (or 3) | |
3c9b6116 AW |
20051 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, |
20052 | @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}}, @r{@var{A}_@var{p}} | |
8925f36f AW |
20053 | |
20054 | @item @code{GL_RGBA} | |
3c9b6116 AW |
20055 | @r{@var{C}_@var{v}=}, @r{@var{C}_@var{s}}, |
20056 | @r{@var{C}_@var{p}@var{C}_@var{s}}, | |
20057 | @r{@var{C}_@var{p}(1-@var{A}_@var{s},)+@var{C}_@var{s}@var{A}_@var{s}}, | |
20058 | @r{@var{C}_@var{p}(1-@var{C}_@var{s},)+@var{C}_@var{c}@var{C}_@var{s}}, | |
20059 | @r{@var{C}_@var{p}+@var{C}_@var{s}} | |
8925f36f AW |
20060 | |
20061 | @item | |
20062 | (or 4) | |
3c9b6116 AW |
20063 | @r{@var{A}_@var{v}=}, @r{@var{A}_@var{s}}, |
20064 | @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}}, | |
20065 | @r{@var{A}_@var{p}@var{A}_@var{s}}, @r{@var{A}_@var{p}@var{A}_@var{s}} | |
8925f36f AW |
20066 | |
20067 | @end table | |
20068 | ||
20069 | If @var{pname} is @code{GL_TEXTURE_ENV_MODE}, and @var{params} is | |
20070 | @code{GL_COMBINE}, the form of the texture function depends on the | |
20071 | values of @code{GL_COMBINE_RGB} and @code{GL_COMBINE_ALPHA}. | |
20072 | ||
20073 | The following describes how the texture sources, as specified by | |
20074 | @code{GL_SRC0_RGB}, @code{GL_SRC1_RGB}, @code{GL_SRC2_RGB}, | |
20075 | @code{GL_SRC0_ALPHA}, @code{GL_SRC1_ALPHA}, and @code{GL_SRC2_ALPHA}, | |
c7b31271 | 20076 | are combined to produce a final texture color. In the following tables, |
3c9b6116 AW |
20077 | @code{GL_SRC0_c} is represented by @r{@var{Arg0}}, @code{GL_SRC1_c} is |
20078 | represented by @r{@var{Arg1}}, and @code{GL_SRC2_c} is represented by | |
20079 | @r{@var{Arg2}}. | |
8925f36f AW |
20080 | |
20081 | @code{GL_COMBINE_RGB} accepts any of @code{GL_REPLACE}, | |
20082 | @code{GL_MODULATE}, @code{GL_ADD}, @code{GL_ADD_SIGNED}, | |
20083 | @code{GL_INTERPOLATE}, @code{GL_SUBTRACT}, @code{GL_DOT3_RGB}, or | |
20084 | @code{GL_DOT3_RGBA}. | |
20085 | ||
20086 | ||
20087 | ||
20088 | @table @asis | |
20089 | @item @strong{@code{GL_COMBINE_RGB}} | |
20090 | @strong{Texture Function} | |
20091 | ||
20092 | @item @code{GL_REPLACE} | |
3c9b6116 | 20093 | @r{@var{Arg0}} |
8925f36f AW |
20094 | |
20095 | @item @code{GL_MODULATE} | |
3c9b6116 | 20096 | @r{@var{Arg0}×@var{Arg1}} |
8925f36f AW |
20097 | |
20098 | @item @code{GL_ADD} | |
3c9b6116 | 20099 | @r{@var{Arg0}+@var{Arg1}} |
8925f36f AW |
20100 | |
20101 | @item @code{GL_ADD_SIGNED} | |
3c9b6116 | 20102 | @r{@var{Arg0}+@var{Arg1}-0.5} |
8925f36f AW |
20103 | |
20104 | @item @code{GL_INTERPOLATE} | |
3c9b6116 | 20105 | @r{@var{Arg0}×@var{Arg2}+@var{Arg1}×(1-@var{Arg2},)} |
8925f36f AW |
20106 | |
20107 | @item @code{GL_SUBTRACT} | |
3c9b6116 | 20108 | @r{@var{Arg0}-@var{Arg1}} |
8925f36f AW |
20109 | |
20110 | @item @code{GL_DOT3_RGB} | |
20111 | or @code{GL_DOT3_RGBA} | |
3c9b6116 | 20112 | @r{4×(((@var{Arg0}_@var{r},-0.5,)×(@var{Arg1}_@var{r},-0.5,),)+((@var{Arg0}_@var{g},-0.5,)×(@var{Arg1}_@var{g},-0.5,),)+((@var{Arg0}_@var{b},-0.5,)×(@var{Arg1}_@var{b},-0.5,),),)} |
8925f36f AW |
20113 | |
20114 | @end table | |
20115 | ||
20116 | The scalar results for @code{GL_DOT3_RGB} and @code{GL_DOT3_RGBA} are | |
20117 | placed into each of the 3 (RGB) or 4 (RGBA) components on output. | |
20118 | ||
20119 | Likewise, @code{GL_COMBINE_ALPHA} accepts any of @code{GL_REPLACE}, | |
20120 | @code{GL_MODULATE}, @code{GL_ADD}, @code{GL_ADD_SIGNED}, | |
c7b31271 | 20121 | @code{GL_INTERPOLATE}, or @code{GL_SUBTRACT}. The following table |
8925f36f AW |
20122 | describes how alpha values are combined: |
20123 | ||
20124 | ||
20125 | ||
20126 | @table @asis | |
20127 | @item @strong{@code{GL_COMBINE_ALPHA}} | |
20128 | @strong{Texture Function} | |
20129 | ||
20130 | @item @code{GL_REPLACE} | |
3c9b6116 | 20131 | @r{@var{Arg0}} |
8925f36f AW |
20132 | |
20133 | @item @code{GL_MODULATE} | |
3c9b6116 | 20134 | @r{@var{Arg0}×@var{Arg1}} |
8925f36f AW |
20135 | |
20136 | @item @code{GL_ADD} | |
3c9b6116 | 20137 | @r{@var{Arg0}+@var{Arg1}} |
8925f36f AW |
20138 | |
20139 | @item @code{GL_ADD_SIGNED} | |
3c9b6116 | 20140 | @r{@var{Arg0}+@var{Arg1}-0.5} |
8925f36f AW |
20141 | |
20142 | @item @code{GL_INTERPOLATE} | |
3c9b6116 | 20143 | @r{@var{Arg0}×@var{Arg2}+@var{Arg1}×(1-@var{Arg2},)} |
8925f36f AW |
20144 | |
20145 | @item @code{GL_SUBTRACT} | |
3c9b6116 | 20146 | @r{@var{Arg0}-@var{Arg1}} |
8925f36f AW |
20147 | |
20148 | @end table | |
20149 | ||
3c9b6116 AW |
20150 | In the following tables, the value @r{@var{C}_@var{s}} represents the |
20151 | color sampled from the currently bound texture, @r{@var{C}_@var{c}} | |
20152 | represents the constant texture-environment color, @r{@var{C}_@var{f}} | |
20153 | represents the primary color of the incoming fragment, and | |
20154 | @r{@var{C}_@var{p}} represents the color computed from the previous | |
20155 | texture stage or @r{@var{C}_@var{f}} if processing texture stage 0. | |
20156 | Likewise, @r{@var{A}_@var{s}}, @r{@var{A}_@var{c}}, @r{@var{A}_@var{f}}, | |
20157 | and @r{@var{A}_@var{p}} represent the respective alpha values. | |
8925f36f | 20158 | |
3c9b6116 AW |
20159 | The following table describes the values assigned to @r{@var{Arg0}}, |
20160 | @r{@var{Arg1}}, and @r{@var{Arg2}} based upon the RGB sources and | |
8925f36f AW |
20161 | operands: |
20162 | ||
20163 | ||
20164 | ||
20165 | @table @asis | |
20166 | @item @strong{@code{GL_SRCn_RGB}} | |
20167 | @strong{@code{GL_OPERANDn_RGB}}, @strong{Argument Value} | |
20168 | ||
20169 | @item @code{GL_TEXTURE} | |
3c9b6116 | 20170 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{s},} |
8925f36f AW |
20171 | |
20172 | @item | |
3c9b6116 | 20173 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{s},} |
8925f36f AW |
20174 | |
20175 | @item | |
3c9b6116 | 20176 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},} |
8925f36f AW |
20177 | |
20178 | @item | |
3c9b6116 | 20179 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},} |
8925f36f AW |
20180 | |
20181 | @item @code{GL_TEXTUREn} | |
3c9b6116 | 20182 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{s},} |
8925f36f AW |
20183 | |
20184 | @item | |
3c9b6116 | 20185 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{s},} |
8925f36f AW |
20186 | |
20187 | @item | |
3c9b6116 | 20188 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},} |
8925f36f AW |
20189 | |
20190 | @item | |
3c9b6116 | 20191 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},} |
8925f36f AW |
20192 | |
20193 | @item @code{GL_CONSTANT} | |
3c9b6116 | 20194 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{c},} |
8925f36f AW |
20195 | |
20196 | @item | |
3c9b6116 | 20197 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{c},} |
8925f36f AW |
20198 | |
20199 | @item | |
3c9b6116 | 20200 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{c},} |
8925f36f AW |
20201 | |
20202 | @item | |
3c9b6116 | 20203 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{c},} |
8925f36f AW |
20204 | |
20205 | @item @code{GL_PRIMARY_COLOR} | |
3c9b6116 | 20206 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{f},} |
8925f36f AW |
20207 | |
20208 | @item | |
3c9b6116 | 20209 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{f},} |
8925f36f AW |
20210 | |
20211 | @item | |
3c9b6116 | 20212 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{f},} |
8925f36f AW |
20213 | |
20214 | @item | |
3c9b6116 | 20215 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{f},} |
8925f36f AW |
20216 | |
20217 | @item @code{GL_PREVIOUS} | |
3c9b6116 | 20218 | @code{GL_SRC_COLOR}, @r{@var{C}_@var{p},} |
8925f36f AW |
20219 | |
20220 | @item | |
3c9b6116 | 20221 | @code{GL_ONE_MINUS_SRC_COLOR}, @r{1-@var{C}_@var{p},} |
8925f36f AW |
20222 | |
20223 | @item | |
3c9b6116 | 20224 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{p},} |
8925f36f AW |
20225 | |
20226 | @item | |
3c9b6116 | 20227 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{p},} |
8925f36f AW |
20228 | |
20229 | @end table | |
20230 | ||
3c9b6116 AW |
20231 | For @code{GL_TEXTUREn} sources, @r{@var{C}_@var{s}} and |
20232 | @r{@var{A}_@var{s}} represent the color and alpha, respectively, | |
20233 | produced from texture stage @r{@var{n}}. | |
8925f36f | 20234 | |
3c9b6116 AW |
20235 | The follow table describes the values assigned to @r{@var{Arg0}}, |
20236 | @r{@var{Arg1}}, and @r{@var{Arg2}} based upon the alpha sources and | |
20237 | operands: | |
8925f36f AW |
20238 | |
20239 | ||
20240 | ||
20241 | @table @asis | |
20242 | @item @strong{@code{GL_SRCn_ALPHA}} | |
20243 | @strong{@code{GL_OPERANDn_ALPHA}}, @strong{Argument Value} | |
20244 | ||
20245 | @item @code{GL_TEXTURE} | |
3c9b6116 | 20246 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},} |
8925f36f AW |
20247 | |
20248 | @item | |
3c9b6116 | 20249 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},} |
8925f36f AW |
20250 | |
20251 | @item @code{GL_TEXTUREn} | |
3c9b6116 | 20252 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{s},} |
8925f36f AW |
20253 | |
20254 | @item | |
3c9b6116 | 20255 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{s},} |
8925f36f AW |
20256 | |
20257 | @item @code{GL_CONSTANT} | |
3c9b6116 | 20258 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{c},} |
8925f36f AW |
20259 | |
20260 | @item | |
3c9b6116 | 20261 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{c},} |
8925f36f AW |
20262 | |
20263 | @item @code{GL_PRIMARY_COLOR} | |
3c9b6116 | 20264 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{f},} |
8925f36f AW |
20265 | |
20266 | @item | |
3c9b6116 | 20267 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{f},} |
8925f36f AW |
20268 | |
20269 | @item @code{GL_PREVIOUS} | |
3c9b6116 | 20270 | @code{GL_SRC_ALPHA}, @r{@var{A}_@var{p},} |
8925f36f AW |
20271 | |
20272 | @item | |
3c9b6116 | 20273 | @code{GL_ONE_MINUS_SRC_ALPHA}, @r{1-@var{A}_@var{p},} |
8925f36f AW |
20274 | |
20275 | @end table | |
20276 | ||
20277 | The RGB and alpha results of the texture function are multipled by the | |
20278 | values of @code{GL_RGB_SCALE} and @code{GL_ALPHA_SCALE}, respectively, | |
3c9b6116 | 20279 | and clamped to the range @r{[0,1]}. |
8925f36f AW |
20280 | |
20281 | If @var{pname} is @code{GL_TEXTURE_ENV_COLOR}, @var{params} is a pointer | |
c7b31271 | 20282 | to an array that holds an RGBA color consisting of four values. Integer |
8925f36f | 20283 | color components are interpreted linearly such that the most positive |
c7b31271 | 20284 | integer maps to 1.0, and the most negative integer maps to -1.0. The |
8925f36f | 20285 | values are clamped to the range [0,1] when they are specified. |
3c9b6116 | 20286 | @r{@var{C}_@var{c}} takes these four values. |
8925f36f AW |
20287 | |
20288 | If @var{pname} is @code{GL_TEXTURE_LOD_BIAS}, the value specified is | |
20289 | added to the texture level-of-detail parameter, that selects which | |
20290 | mipmap, or mipmaps depending upon the selected | |
20291 | @code{GL_TEXTURE_MIN_FILTER}, will be sampled. | |
20292 | ||
20293 | @code{GL_TEXTURE_ENV_MODE} defaults to @code{GL_MODULATE} and | |
20294 | @code{GL_TEXTURE_ENV_COLOR} defaults to (0, 0, 0, 0). | |
20295 | ||
20296 | If @var{target} is @code{GL_POINT_SPRITE} and @var{pname} is | |
20297 | @code{GL_COORD_REPLACE}, the boolean value specified is used to either | |
c7b31271 | 20298 | enable or disable point sprite texture coordinate replacement. The |
8925f36f AW |
20299 | default value is @code{GL_FALSE}. |
20300 | ||
8925f36f AW |
20301 | @code{GL_INVALID_ENUM} is generated when @var{target} or @var{pname} is |
20302 | not one of the accepted defined values, or when @var{params} should have | |
20303 | a defined constant value (based on the value of @var{pname}) and does | |
20304 | not. | |
20305 | ||
20306 | @code{GL_INVALID_VALUE} is generated if the @var{params} value for | |
20307 | @code{GL_RGB_SCALE} or @code{GL_ALPHA_SCALE} are not one of 1.0, 2.0, or | |
20308 | 4.0. | |
20309 | ||
20310 | @code{GL_INVALID_OPERATION} is generated if @code{glTexEnv} is executed | |
20311 | between the execution of @code{glBegin} and the corresponding execution | |
20312 | of @code{glEnd}. | |
20313 | ||
bb894c9d | 20314 | @end deftypefun |
8925f36f | 20315 | |
bb894c9d | 20316 | @deftypefun void glTexGeni coord pname param |
ca09631c | 20317 | @deftypefunx void glTexGenf coord pname param |
d172eed9 AW |
20318 | @deftypefunx void glTexGend coord pname param |
20319 | @deftypefunx void glTexGeniv coord pname params | |
20320 | @deftypefunx void glTexGenfv coord pname params | |
20321 | @deftypefunx void glTexGendv coord pname params | |
3c9b6116 AW |
20322 | Control the generation of texture coordinates. |
20323 | ||
8925f36f AW |
20324 | @table @asis |
20325 | @item @var{coord} | |
c7b31271 DH |
20326 | Specifies a texture coordinate. Must be one of @code{GL_S}, |
20327 | @code{GL_T}, @code{GL_R}, or @code{GL_Q}. | |
8925f36f AW |
20328 | |
20329 | @item @var{pname} | |
20330 | Specifies the symbolic name of the texture-coordinate generation | |
c7b31271 | 20331 | function. Must be @code{GL_TEXTURE_GEN_MODE}. |
8925f36f AW |
20332 | |
20333 | @item @var{param} | |
20334 | Specifies a single-valued texture generation parameter, one of | |
20335 | @code{GL_OBJECT_LINEAR}, @code{GL_EYE_LINEAR}, @code{GL_SPHERE_MAP}, | |
20336 | @code{GL_NORMAL_MAP}, or @code{GL_REFLECTION_MAP}. | |
20337 | ||
20338 | @end table | |
20339 | ||
8925f36f | 20340 | @code{glTexGen} selects a texture-coordinate generation function or |
c7b31271 DH |
20341 | supplies coefficients for one of the functions. @var{coord} names one |
20342 | of the (@var{s}, @var{t}, @var{r}, @var{q}) texture coordinates; it must | |
20343 | be one of the symbols @code{GL_S}, @code{GL_T}, @code{GL_R}, or | |
20344 | @code{GL_Q}. @var{pname} must be one of three symbolic constants: | |
8925f36f | 20345 | @code{GL_TEXTURE_GEN_MODE}, @code{GL_OBJECT_PLANE}, or |
c7b31271 | 20346 | @code{GL_EYE_PLANE}. If @var{pname} is @code{GL_TEXTURE_GEN_MODE}, then |
8925f36f AW |
20347 | @var{params} chooses a mode, one of @code{GL_OBJECT_LINEAR}, |
20348 | @code{GL_EYE_LINEAR}, @code{GL_SPHERE_MAP}, @code{GL_NORMAL_MAP}, or | |
c7b31271 | 20349 | @code{GL_REFLECTION_MAP}. If @var{pname} is either |
8925f36f AW |
20350 | @code{GL_OBJECT_PLANE} or @code{GL_EYE_PLANE}, @var{params} contains |
20351 | coefficients for the corresponding texture generation function. | |
20352 | ||
20353 | If the texture generation function is @code{GL_OBJECT_LINEAR}, the | |
20354 | function | |
20355 | ||
3c9b6116 AW |
20356 | @r{@var{g}=@var{p}_1×@var{x}_@var{o}+@var{p}_2×@var{y}_@var{o}+@var{p}_3×@var{z}_@var{o}+@var{p}_4×@var{w}_@var{o}} |
20357 | ||
20358 | is used, where @r{@var{g}} is the value computed for the coordinate | |
20359 | named in @var{coord}, @r{@var{p}_1}, @r{@var{p}_2}, @r{@var{p}_3}, and | |
20360 | @r{@var{p}_4} are the four values supplied in @var{params}, and | |
20361 | @r{@var{x}_@var{o}}, @r{@var{y}_@var{o}}, @r{@var{z}_@var{o}}, and | |
c7b31271 | 20362 | @r{@var{w}_@var{o}} are the object coordinates of the vertex. This |
3c9b6116 AW |
20363 | function can be used, for example, to texture-map terrain using sea |
20364 | level as a reference plane (defined by @r{@var{p}_1}, @r{@var{p}_2}, | |
c7b31271 | 20365 | @r{@var{p}_3}, and @r{@var{p}_4}). The altitude of a terrain vertex is |
3c9b6116 AW |
20366 | computed by the @code{GL_OBJECT_LINEAR} coordinate generation function |
20367 | as its distance from sea level; that altitude can then be used to index | |
20368 | the texture image to map white snow onto peaks and green grass onto | |
20369 | foothills. | |
8925f36f AW |
20370 | |
20371 | If the texture generation function is @code{GL_EYE_LINEAR}, the function | |
20372 | ||
3c9b6116 | 20373 | @r{@var{g}=@var{p}_1,^″×@var{x}_@var{e}+@var{p}_2,^″×@var{y}_@var{e}+@var{p}_3,^″×@var{z}_@var{e}+@var{p}_4,^″×@var{w}_@var{e}} |
8925f36f AW |
20374 | |
20375 | is used, where | |
20376 | ||
3c9b6116 | 20377 | @r{(@var{p}_1,^″@var{p}_2,^″@var{p}_3,^″@var{p}_4,^″,)=(@var{p}_1@var{p}_2@var{p}_3@var{p}_4,)@var{M}^-1} |
8925f36f | 20378 | |
3c9b6116 AW |
20379 | and @r{@var{x}_@var{e}}, @r{@var{y}_@var{e}}, @r{@var{z}_@var{e}}, and |
20380 | @r{@var{w}_@var{e}} are the eye coordinates of the vertex, | |
20381 | @r{@var{p}_1}, @r{@var{p}_2}, @r{@var{p}_3}, and @r{@var{p}_4} are the | |
20382 | values supplied in @var{params}, and @r{@var{M}} is the modelview matrix | |
c7b31271 DH |
20383 | when @code{glTexGen} is invoked. If @r{@var{M}} is poorly conditioned |
20384 | or singular, texture coordinates generated by the resulting function may | |
20385 | be inaccurate or undefined. | |
8925f36f AW |
20386 | |
20387 | Note that the values in @var{params} define a reference plane in eye | |
c7b31271 DH |
20388 | coordinates. The modelview matrix that is applied to them may not be |
20389 | the same one in effect when the polygon vertices are transformed. This | |
8925f36f AW |
20390 | function establishes a field of texture coordinates that can produce |
20391 | dynamic contour lines on moving objects. | |
20392 | ||
20393 | If the texture generation function is @code{GL_SPHERE_MAP} and | |
3c9b6116 | 20394 | @var{coord} is either @code{GL_S} or @code{GL_T}, @r{@var{s}} and |
c7b31271 DH |
20395 | @r{@var{t}} texture coordinates are generated as follows. Let @var{u} |
20396 | be the unit vector pointing from the origin to the polygon vertex (in | |
20397 | eye coordinates). Let @var{n} sup prime be the current normal, after | |
20398 | transformation to eye coordinates. Let | |
8925f36f | 20399 | |
3c9b6116 | 20400 | @r{@var{f}=(@var{f}_@var{x}@var{f}_@var{y}@var{f}_@var{z},)^@var{T}} |
8925f36f AW |
20401 | be the reflection vector such that |
20402 | ||
3c9b6116 | 20403 | @r{@var{f}=@var{u}-2@var{n}^″@var{n}^″,^@var{T}@var{u}} |
8925f36f AW |
20404 | |
20405 | Finally, let | |
3c9b6116 AW |
20406 | @r{@var{m}=2√(@var{f}_@var{x},^2+@var{f}_@var{y},^2+(@var{f}_@var{z}+1,)^2,)}. |
20407 | Then the values assigned to the @r{@var{s}} and @r{@var{t}} texture | |
20408 | coordinates are | |
8925f36f | 20409 | |
3c9b6116 | 20410 | @r{@var{s}=@var{f}_@var{x}/@var{m}+1/2} |
8925f36f | 20411 | |
3c9b6116 | 20412 | @r{@var{t}=@var{f}_@var{y}/@var{m}+1/2} |
8925f36f AW |
20413 | |
20414 | To enable or disable a texture-coordinate generation function, call | |
20415 | @code{glEnable} or @code{glDisable} with one of the symbolic | |
20416 | texture-coordinate names (@code{GL_TEXTURE_GEN_S}, | |
20417 | @code{GL_TEXTURE_GEN_T}, @code{GL_TEXTURE_GEN_R}, or | |
c7b31271 | 20418 | @code{GL_TEXTURE_GEN_Q}) as the argument. When enabled, the specified |
8925f36f | 20419 | texture coordinate is computed according to the generating function |
c7b31271 DH |
20420 | associated with that coordinate. When disabled, subsequent vertices |
20421 | take the specified texture coordinate from the current set of texture | |
20422 | coordinates. Initially, all texture generation functions are set to | |
20423 | @code{GL_EYE_LINEAR} and are disabled. Both @r{@var{s}} plane equations | |
3c9b6116 AW |
20424 | are (1, 0, 0, 0), both @r{@var{t}} plane equations are (0, 1, 0, 0), and |
20425 | all @r{@var{r}} and @r{@var{q}} plane equations are (0, 0, 0, 0). | |
8925f36f AW |
20426 | |
20427 | When the @code{ARB_multitexture} extension is supported, @code{glTexGen} | |
20428 | sets the texture generation parameters for the currently active texture | |
20429 | unit, selected with @code{glActiveTexture}. | |
20430 | ||
8925f36f AW |
20431 | @code{GL_INVALID_ENUM} is generated when @var{coord} or @var{pname} is |
20432 | not an accepted defined value, or when @var{pname} is | |
20433 | @code{GL_TEXTURE_GEN_MODE} and @var{params} is not an accepted defined | |
20434 | value. | |
20435 | ||
20436 | @code{GL_INVALID_ENUM} is generated when @var{pname} is | |
20437 | @code{GL_TEXTURE_GEN_MODE}, @var{params} is @code{GL_SPHERE_MAP}, and | |
20438 | @var{coord} is either @code{GL_R} or @code{GL_Q}. | |
20439 | ||
20440 | @code{GL_INVALID_OPERATION} is generated if @code{glTexGen} is executed | |
20441 | between the execution of @code{glBegin} and the corresponding execution | |
20442 | of @code{glEnd}. | |
20443 | ||
bb894c9d | 20444 | @end deftypefun |
8925f36f | 20445 | |
bb894c9d | 20446 | @deftypefun void glTexImage1D target level internalFormat width border format type data |
3c9b6116 AW |
20447 | Specify a one-dimensional texture image. |
20448 | ||
8925f36f AW |
20449 | @table @asis |
20450 | @item @var{target} | |
c7b31271 | 20451 | Specifies the target texture. Must be @code{GL_TEXTURE_1D} or |
8925f36f AW |
20452 | @code{GL_PROXY_TEXTURE_1D}. |
20453 | ||
20454 | @item @var{level} | |
c7b31271 | 20455 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
20456 | Level @var{n} is the @var{n}th mipmap reduction image. |
20457 | ||
20458 | @item @var{internalFormat} | |
c7b31271 | 20459 | Specifies the number of color components in the texture. Must be 1, 2, |
8925f36f AW |
20460 | 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA}, |
20461 | @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, | |
20462 | @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA}, | |
20463 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
20464 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
20465 | @code{GL_COMPRESSED_RGBA}, @code{GL_DEPTH_COMPONENT}, | |
20466 | @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, | |
20467 | @code{GL_DEPTH_COMPONENT32}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
20468 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
20469 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
20470 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
20471 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
20472 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY}, | |
20473 | @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12}, | |
20474 | @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
20475 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
20476 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
20477 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
20478 | @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE}, | |
20479 | @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
20480 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
20481 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
20482 | ||
20483 | @item @var{width} | |
c7b31271 | 20484 | Specifies the width of the texture image including the border if any. If |
8925f36f | 20485 | the GL version does not support non-power-of-two sizes, this value must |
c7b31271 | 20486 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
3c9b6116 AW |
20487 | implementations support texture images that are at least 64 texels wide. |
20488 | The height of the 1D texture image is 1. | |
8925f36f AW |
20489 | |
20490 | @item @var{border} | |
c7b31271 | 20491 | Specifies the width of the border. Must be either 0 or 1. |
8925f36f AW |
20492 | |
20493 | @item @var{format} | |
c7b31271 | 20494 | Specifies the format of the pixel data. The following symbolic values |
8925f36f AW |
20495 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, |
20496 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
20497 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
20498 | @code{GL_LUMINANCE_ALPHA}. | |
20499 | ||
20500 | @item @var{type} | |
c7b31271 DH |
20501 | Specifies the data type of the pixel data. The following symbolic |
20502 | values are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, | |
20503 | @code{GL_BITMAP}, @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, | |
20504 | @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT}, | |
20505 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
20506 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
20507 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
20508 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
20509 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
20510 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
20511 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
8925f36f AW |
20512 | |
20513 | @item @var{data} | |
20514 | Specifies a pointer to the image data in memory. | |
20515 | ||
20516 | @end table | |
20517 | ||
8925f36f | 20518 | Texturing maps a portion of a specified texture image onto each |
c7b31271 | 20519 | graphical primitive for which texturing is enabled. To enable and |
8925f36f AW |
20520 | disable one-dimensional texturing, call @code{glEnable} and |
20521 | @code{glDisable} with argument @code{GL_TEXTURE_1D}. | |
20522 | ||
c7b31271 | 20523 | Texture images are defined with @code{glTexImage1D}. The arguments |
8925f36f AW |
20524 | describe the parameters of the texture image, such as width, width of |
20525 | the border, level-of-detail number (see @code{glTexParameter}), and the | |
c7b31271 | 20526 | internal resolution and format used to store the image. The last three |
8925f36f AW |
20527 | arguments describe how the image is represented in memory; they are |
20528 | identical to the pixel formats used for @code{glDrawPixels}. | |
20529 | ||
20530 | If @var{target} is @code{GL_PROXY_TEXTURE_1D}, no data is read from | |
20531 | @var{data}, but all of the texture image state is recalculated, checked | |
20532 | for consistency, and checked against the implementation's capabilities. | |
20533 | If the implementation cannot handle a texture of the requested texture | |
20534 | size, it sets all of the image state to 0, but does not generate an | |
c7b31271 | 20535 | error (see @code{glGetError}). To query for an entire mipmap array, use |
8925f36f AW |
20536 | an image array level greater than or equal to 1. |
20537 | ||
20538 | If @var{target} is @code{GL_TEXTURE_1D}, data is read from @var{data} as | |
20539 | a sequence of signed or unsigned bytes, shorts, or longs, or | |
c7b31271 | 20540 | single-precision floating-point values, depending on @var{type}. These |
8925f36f | 20541 | values are grouped into sets of one, two, three, or four values, |
c7b31271 | 20542 | depending on @var{format}, to form elements. If @var{type} is |
8925f36f | 20543 | @code{GL_BITMAP}, the data is considered as a string of unsigned bytes |
c7b31271 | 20544 | (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is |
8925f36f AW |
20545 | treated as eight 1-bit elements, with bit ordering determined by |
20546 | @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}). | |
20547 | ||
20548 | If a non-zero named buffer object is bound to the | |
20549 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
20550 | texture image is specified, @var{data} is treated as a byte offset into | |
20551 | the buffer object's data store. | |
20552 | ||
20553 | The first element corresponds to the left end of the texture array. | |
20554 | Subsequent elements progress left-to-right through the remaining texels | |
c7b31271 | 20555 | in the texture array. The final element corresponds to the right end of |
8925f36f AW |
20556 | the texture array. |
20557 | ||
20558 | @var{format} determines the composition of each element in @var{data}. | |
20559 | It can assume one of these symbolic values: | |
20560 | ||
20561 | @table @asis | |
20562 | @item @code{GL_COLOR_INDEX} | |
c7b31271 | 20563 | Each element is a single value, a color index. The GL converts it to |
8925f36f AW |
20564 | fixed point (with an unspecified number of zero bits to the right of the |
20565 | binary point), shifted left or right depending on the value and sign of | |
20566 | @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see | |
c7b31271 | 20567 | @code{glPixelTransfer}). The resulting index is converted to a set of |
8925f36f AW |
20568 | color components using the @code{GL_PIXEL_MAP_I_TO_R}, |
20569 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
20570 | @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1]. | |
20571 | ||
20572 | @item @code{GL_RED} | |
c7b31271 | 20573 | Each element is a single red component. The GL converts it to floating |
8925f36f | 20574 | point and assembles it into an RGBA element by attaching 0 for green and |
c7b31271 | 20575 | blue, and 1 for alpha. Each component is then multiplied by the signed |
8925f36f AW |
20576 | scale factor @code{GL_c_SCALE}, added to the signed bias |
20577 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20578 | @code{glPixelTransfer}). | |
20579 | ||
20580 | @item @code{GL_GREEN} | |
c7b31271 DH |
20581 | Each element is a single green component. The GL converts it to |
20582 | floating point and assembles it into an RGBA element by attaching 0 for | |
20583 | red and blue, and 1 for alpha. Each component is then multiplied by the | |
20584 | signed scale factor @code{GL_c_SCALE}, added to the signed bias | |
8925f36f AW |
20585 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see |
20586 | @code{glPixelTransfer}). | |
20587 | ||
20588 | @item @code{GL_BLUE} | |
c7b31271 | 20589 | Each element is a single blue component. The GL converts it to floating |
8925f36f | 20590 | point and assembles it into an RGBA element by attaching 0 for red and |
c7b31271 | 20591 | green, and 1 for alpha. Each component is then multiplied by the signed |
8925f36f AW |
20592 | scale factor @code{GL_c_SCALE}, added to the signed bias |
20593 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20594 | @code{glPixelTransfer}). | |
20595 | ||
20596 | @item @code{GL_ALPHA} | |
c7b31271 DH |
20597 | Each element is a single alpha component. The GL converts it to |
20598 | floating point and assembles it into an RGBA element by attaching 0 for | |
20599 | red, green, and blue. Each component is then multiplied by the signed | |
20600 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
20601 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20602 | @code{glPixelTransfer}). | |
8925f36f AW |
20603 | |
20604 | @item @code{GL_INTENSITY} | |
c7b31271 DH |
20605 | Each element is a single intensity value. The GL converts it to |
20606 | floating point, then assembles it into an RGBA element by replicating | |
20607 | the intensity value three times for red, green, blue, and alpha. Each | |
8925f36f AW |
20608 | component is then multiplied by the signed scale factor |
20609 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
20610 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20611 | ||
20612 | @item @code{GL_RGB} | |
20613 | @item @code{GL_BGR} | |
c7b31271 DH |
20614 | Each element is an RGB triple. The GL converts it to floating point and |
20615 | assembles it into an RGBA element by attaching 1 for alpha. Each | |
8925f36f AW |
20616 | component is then multiplied by the signed scale factor |
20617 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
20618 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20619 | ||
20620 | @item @code{GL_RGBA} | |
20621 | @item @code{GL_BGRA} | |
c7b31271 | 20622 | Each element contains all four components. Each component is multiplied |
8925f36f AW |
20623 | by the signed scale factor @code{GL_c_SCALE}, added to the signed bias |
20624 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20625 | @code{glPixelTransfer}). | |
20626 | ||
20627 | @item @code{GL_LUMINANCE} | |
c7b31271 DH |
20628 | Each element is a single luminance value. The GL converts it to |
20629 | floating point, then assembles it into an RGBA element by replicating | |
20630 | the luminance value three times for red, green, and blue and attaching 1 | |
20631 | for alpha. Each component is then multiplied by the signed scale factor | |
8925f36f AW |
20632 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and |
20633 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20634 | ||
20635 | @item @code{GL_LUMINANCE_ALPHA} | |
c7b31271 | 20636 | Each element is a luminance/alpha pair. The GL converts it to floating |
8925f36f | 20637 | point, then assembles it into an RGBA element by replicating the |
c7b31271 | 20638 | luminance value three times for red, green, and blue. Each component is |
8925f36f AW |
20639 | then multiplied by the signed scale factor @code{GL_c_SCALE}, added to |
20640 | the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20641 | @code{glPixelTransfer}). | |
20642 | ||
20643 | @item @code{GL_DEPTH_COMPONENT} | |
c7b31271 | 20644 | Each element is a single depth value. The GL converts it to floating |
8925f36f AW |
20645 | point, multiplies by the signed scale factor @code{GL_DEPTH_SCALE}, adds |
20646 | the signed bias @code{GL_DEPTH_BIAS}, and clamps to the range [0,1] (see | |
20647 | @code{glPixelTransfer}). | |
20648 | ||
20649 | @end table | |
20650 | ||
20651 | Refer to the @code{glDrawPixels} reference page for a description of the | |
20652 | acceptable values for the @var{type} parameter. | |
20653 | ||
20654 | If an application wants to store the texture at a certain resolution or | |
20655 | in a certain format, it can request the resolution and format with | |
c7b31271 DH |
20656 | @var{internalFormat}. The GL will choose an internal representation |
20657 | that closely approximates that requested by @var{internalFormat}, but it | |
20658 | may not match exactly. (The representations specified by | |
8925f36f | 20659 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and |
c7b31271 DH |
20660 | @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 |
20661 | may also be used to specify the above representations.) | |
8925f36f AW |
20662 | |
20663 | If the @var{internalFormat} parameter is one of the generic compressed | |
20664 | formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
20665 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
20666 | @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will | |
20667 | replace the internal format with the symbolic constant for a specific | |
c7b31271 | 20668 | internal format and compress the texture before storage. If no |
8925f36f AW |
20669 | corresponding internal format is available, or the GL can not compress |
20670 | that image for any reason, the internal format is instead replaced with | |
20671 | a corresponding base internal format. | |
20672 | ||
20673 | If the @var{internalFormat} parameter is @code{GL_SRGB}, | |
20674 | @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8}, | |
20675 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
20676 | or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red, | |
20677 | green, blue, or luminance components are encoded in the sRGB color | |
c7b31271 | 20678 | space. Any alpha component is left unchanged. The conversion from the |
3c9b6116 AW |
20679 | sRGB encoded component @r{@var{c}_@var{s}} to a linear component |
20680 | @r{@var{c}_@var{l}} is: | |
8925f36f | 20681 | |
3c9b6116 AW |
20682 | @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045), |
20683 | ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)} | |
8925f36f | 20684 | |
3c9b6116 | 20685 | Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1]. |
8925f36f AW |
20686 | |
20687 | Use the @code{GL_PROXY_TEXTURE_1D} target to try out a resolution and | |
c7b31271 DH |
20688 | format. The implementation will update and recompute its best match for |
20689 | the requested storage resolution and format. To then query this state, | |
20690 | call @code{glGetTexLevelParameter}. If the texture cannot be | |
8925f36f AW |
20691 | accommodated, texture state is set to 0. |
20692 | ||
20693 | A one-component texture image uses only the red component of the RGBA | |
c7b31271 DH |
20694 | color from @var{data}. A two-component image uses the R and A values. A |
20695 | three-component image uses the R, G, and B values. A four-component | |
8925f36f AW |
20696 | image uses all of the RGBA components. |
20697 | ||
20698 | Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA textures | |
c7b31271 | 20699 | during texture filtering and application. Image-based shadowing can be |
8925f36f | 20700 | enabled by comparing texture r coordinates to depth texture values to |
c7b31271 | 20701 | generate a boolean result. See @code{glTexParameter} for details on |
8925f36f AW |
20702 | texture comparison. |
20703 | ||
8925f36f AW |
20704 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
20705 | @code{GL_TEXTURE_1D} or @code{GL_PROXY_TEXTURE_1D}. | |
20706 | ||
20707 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
c7b31271 DH |
20708 | format constant. Format constants other than @code{GL_STENCIL_INDEX} |
20709 | are accepted. | |
8925f36f AW |
20710 | |
20711 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
20712 | constant. | |
20713 | ||
20714 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
20715 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
20716 | ||
20717 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
20718 | ||
20719 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
20720 | @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of |
20721 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
20722 | |
20723 | @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1, | |
20724 | 2, 3, 4, or one of the accepted resolution and format symbolic | |
20725 | constants. | |
20726 | ||
20727 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0 or | |
20728 | greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
20729 | ||
20730 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
20731 | not supported and the @var{width} cannot be represented as | |
3c9b6116 | 20732 | @r{2^@var{n}+2(@var{border},)} for some integer value of @var{n}. |
8925f36f AW |
20733 | |
20734 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
20735 | ||
20736 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
20737 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
20738 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
20739 | and @var{format} is not @code{GL_RGB}. | |
20740 | ||
20741 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
20742 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
20743 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
20744 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
20745 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
20746 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
20747 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
20748 | ||
20749 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
20750 | @code{GL_DEPTH_COMPONENT} and @var{internalFormat} is not | |
20751 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
20752 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}. | |
20753 | ||
20754 | @code{GL_INVALID_OPERATION} is generated if @var{internalFormat} is | |
20755 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
20756 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}, and | |
20757 | @var{format} is not @code{GL_DEPTH_COMPONENT}. | |
20758 | ||
20759 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
20760 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
20761 | object's data store is currently mapped. | |
20762 | ||
20763 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
20764 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
20765 | would be unpacked from the buffer object such that the memory reads | |
20766 | required would exceed the data store size. | |
20767 | ||
20768 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
20769 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
20770 | is not evenly divisible into the number of bytes needed to store in | |
20771 | memory a datum indicated by @var{type}. | |
20772 | ||
20773 | @code{GL_INVALID_OPERATION} is generated if @code{glTexImage1D} is | |
20774 | executed between the execution of @code{glBegin} and the corresponding | |
20775 | execution of @code{glEnd}. | |
20776 | ||
bb894c9d | 20777 | @end deftypefun |
8925f36f | 20778 | |
bb894c9d | 20779 | @deftypefun void glTexImage2D target level internalFormat width height border format type data |
3c9b6116 AW |
20780 | Specify a two-dimensional texture image. |
20781 | ||
8925f36f AW |
20782 | @table @asis |
20783 | @item @var{target} | |
c7b31271 | 20784 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, |
8925f36f AW |
20785 | @code{GL_PROXY_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, |
20786 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
20787 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
20788 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
20789 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, | |
20790 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}, or | |
20791 | @code{GL_PROXY_TEXTURE_CUBE_MAP}. | |
20792 | ||
20793 | @item @var{level} | |
c7b31271 | 20794 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
20795 | Level @var{n} is the @var{n}th mipmap reduction image. |
20796 | ||
20797 | @item @var{internalFormat} | |
c7b31271 | 20798 | Specifies the number of color components in the texture. Must be 1, 2, |
8925f36f AW |
20799 | 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA}, |
20800 | @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, | |
20801 | @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA}, | |
20802 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
20803 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
20804 | @code{GL_COMPRESSED_RGBA}, @code{GL_DEPTH_COMPONENT}, | |
20805 | @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, | |
20806 | @code{GL_DEPTH_COMPONENT32}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
20807 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
20808 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
20809 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
20810 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
20811 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY}, | |
20812 | @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12}, | |
20813 | @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
20814 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
20815 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
20816 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
20817 | @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE}, | |
20818 | @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
20819 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
20820 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
20821 | ||
20822 | @item @var{width} | |
c7b31271 | 20823 | Specifies the width of the texture image including the border if any. If |
8925f36f | 20824 | the GL version does not support non-power-of-two sizes, this value must |
c7b31271 | 20825 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
3c9b6116 | 20826 | implementations support texture images that are at least 64 texels wide. |
8925f36f AW |
20827 | |
20828 | @item @var{height} | |
20829 | Specifies the height of the texture image including the border if any. | |
20830 | If the GL version does not support non-power-of-two sizes, this value | |
3c9b6116 AW |
20831 | must be @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}. |
20832 | All implementations support texture images that are at least 64 texels | |
20833 | high. | |
8925f36f AW |
20834 | |
20835 | @item @var{border} | |
c7b31271 | 20836 | Specifies the width of the border. Must be either 0 or 1. |
8925f36f AW |
20837 | |
20838 | @item @var{format} | |
c7b31271 | 20839 | Specifies the format of the pixel data. The following symbolic values |
8925f36f AW |
20840 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, |
20841 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
20842 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
20843 | @code{GL_LUMINANCE_ALPHA}. | |
20844 | ||
20845 | @item @var{type} | |
c7b31271 DH |
20846 | Specifies the data type of the pixel data. The following symbolic |
20847 | values are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, | |
20848 | @code{GL_BITMAP}, @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, | |
20849 | @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT}, | |
20850 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
20851 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
20852 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
20853 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
20854 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
20855 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
20856 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
8925f36f AW |
20857 | |
20858 | @item @var{data} | |
20859 | Specifies a pointer to the image data in memory. | |
20860 | ||
20861 | @end table | |
20862 | ||
8925f36f | 20863 | Texturing maps a portion of a specified texture image onto each |
c7b31271 | 20864 | graphical primitive for which texturing is enabled. To enable and |
8925f36f | 20865 | disable two-dimensional texturing, call @code{glEnable} and |
c7b31271 | 20866 | @code{glDisable} with argument @code{GL_TEXTURE_2D}. To enable and |
8925f36f AW |
20867 | disable texturing using cube-mapped texture, call @code{glEnable} and |
20868 | @code{glDisable} with argument @code{GL_TEXTURE_CUBE_MAP}. | |
20869 | ||
c7b31271 | 20870 | To define texture images, call @code{glTexImage2D}. The arguments |
8925f36f AW |
20871 | describe the parameters of the texture image, such as height, width, |
20872 | width of the border, level-of-detail number (see @code{glTexParameter}), | |
c7b31271 | 20873 | and number of color components provided. The last three arguments |
8925f36f AW |
20874 | describe how the image is represented in memory; they are identical to |
20875 | the pixel formats used for @code{glDrawPixels}. | |
20876 | ||
20877 | If @var{target} is @code{GL_PROXY_TEXTURE_2D} or | |
20878 | @code{GL_PROXY_TEXTURE_CUBE_MAP}, no data is read from @var{data}, but | |
20879 | all of the texture image state is recalculated, checked for consistency, | |
c7b31271 | 20880 | and checked against the implementation's capabilities. If the |
8925f36f AW |
20881 | implementation cannot handle a texture of the requested texture size, it |
20882 | sets all of the image state to 0, but does not generate an error (see | |
c7b31271 | 20883 | @code{glGetError}). To query for an entire mipmap array, use an image |
8925f36f AW |
20884 | array level greater than or equal to 1. |
20885 | ||
20886 | If @var{target} is @code{GL_TEXTURE_2D}, or one of the | |
20887 | @code{GL_TEXTURE_CUBE_MAP} targets, data is read from @var{data} as a | |
20888 | sequence of signed or unsigned bytes, shorts, or longs, or | |
c7b31271 | 20889 | single-precision floating-point values, depending on @var{type}. These |
8925f36f | 20890 | values are grouped into sets of one, two, three, or four values, |
c7b31271 | 20891 | depending on @var{format}, to form elements. If @var{type} is |
8925f36f | 20892 | @code{GL_BITMAP}, the data is considered as a string of unsigned bytes |
c7b31271 | 20893 | (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is |
8925f36f AW |
20894 | treated as eight 1-bit elements, with bit ordering determined by |
20895 | @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}). | |
20896 | ||
20897 | If a non-zero named buffer object is bound to the | |
20898 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
20899 | texture image is specified, @var{data} is treated as a byte offset into | |
20900 | the buffer object's data store. | |
20901 | ||
20902 | The first element corresponds to the lower left corner of the texture | |
c7b31271 | 20903 | image. Subsequent elements progress left-to-right through the remaining |
8925f36f | 20904 | texels in the lowest row of the texture image, and then in successively |
c7b31271 | 20905 | higher rows of the texture image. The final element corresponds to the |
8925f36f AW |
20906 | upper right corner of the texture image. |
20907 | ||
20908 | @var{format} determines the composition of each element in @var{data}. | |
20909 | It can assume one of these symbolic values: | |
20910 | ||
20911 | @table @asis | |
20912 | @item @code{GL_COLOR_INDEX} | |
c7b31271 | 20913 | Each element is a single value, a color index. The GL converts it to |
8925f36f AW |
20914 | fixed point (with an unspecified number of zero bits to the right of the |
20915 | binary point), shifted left or right depending on the value and sign of | |
20916 | @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see | |
c7b31271 | 20917 | @code{glPixelTransfer}). The resulting index is converted to a set of |
8925f36f AW |
20918 | color components using the @code{GL_PIXEL_MAP_I_TO_R}, |
20919 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
20920 | @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1]. | |
20921 | ||
20922 | @item @code{GL_RED} | |
c7b31271 | 20923 | Each element is a single red component. The GL converts it to floating |
8925f36f | 20924 | point and assembles it into an RGBA element by attaching 0 for green and |
c7b31271 | 20925 | blue, and 1 for alpha. Each component is then multiplied by the signed |
8925f36f AW |
20926 | scale factor @code{GL_c_SCALE}, added to the signed bias |
20927 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20928 | @code{glPixelTransfer}). | |
20929 | ||
20930 | @item @code{GL_GREEN} | |
c7b31271 DH |
20931 | Each element is a single green component. The GL converts it to |
20932 | floating point and assembles it into an RGBA element by attaching 0 for | |
20933 | red and blue, and 1 for alpha. Each component is then multiplied by the | |
20934 | signed scale factor @code{GL_c_SCALE}, added to the signed bias | |
8925f36f AW |
20935 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see |
20936 | @code{glPixelTransfer}). | |
20937 | ||
20938 | @item @code{GL_BLUE} | |
c7b31271 | 20939 | Each element is a single blue component. The GL converts it to floating |
8925f36f | 20940 | point and assembles it into an RGBA element by attaching 0 for red and |
c7b31271 | 20941 | green, and 1 for alpha. Each component is then multiplied by the signed |
8925f36f AW |
20942 | scale factor @code{GL_c_SCALE}, added to the signed bias |
20943 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20944 | @code{glPixelTransfer}). | |
20945 | ||
20946 | @item @code{GL_ALPHA} | |
c7b31271 DH |
20947 | Each element is a single alpha component. The GL converts it to |
20948 | floating point and assembles it into an RGBA element by attaching 0 for | |
20949 | red, green, and blue. Each component is then multiplied by the signed | |
20950 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
20951 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20952 | @code{glPixelTransfer}). | |
8925f36f AW |
20953 | |
20954 | @item @code{GL_INTENSITY} | |
c7b31271 DH |
20955 | Each element is a single intensity value. The GL converts it to |
20956 | floating point, then assembles it into an RGBA element by replicating | |
20957 | the intensity value three times for red, green, blue, and alpha. Each | |
8925f36f AW |
20958 | component is then multiplied by the signed scale factor |
20959 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
20960 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20961 | ||
20962 | @item @code{GL_RGB} | |
20963 | @item @code{GL_BGR} | |
c7b31271 DH |
20964 | Each element is an RGB triple. The GL converts it to floating point and |
20965 | assembles it into an RGBA element by attaching 1 for alpha. Each | |
8925f36f AW |
20966 | component is then multiplied by the signed scale factor |
20967 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
20968 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20969 | ||
20970 | @item @code{GL_RGBA} | |
20971 | @item @code{GL_BGRA} | |
c7b31271 | 20972 | Each element contains all four components. Each component is multiplied |
8925f36f AW |
20973 | by the signed scale factor @code{GL_c_SCALE}, added to the signed bias |
20974 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20975 | @code{glPixelTransfer}). | |
20976 | ||
20977 | @item @code{GL_LUMINANCE} | |
c7b31271 DH |
20978 | Each element is a single luminance value. The GL converts it to |
20979 | floating point, then assembles it into an RGBA element by replicating | |
20980 | the luminance value three times for red, green, and blue and attaching 1 | |
20981 | for alpha. Each component is then multiplied by the signed scale factor | |
8925f36f AW |
20982 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and |
20983 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
20984 | ||
20985 | @item @code{GL_LUMINANCE_ALPHA} | |
c7b31271 | 20986 | Each element is a luminance/alpha pair. The GL converts it to floating |
8925f36f | 20987 | point, then assembles it into an RGBA element by replicating the |
c7b31271 | 20988 | luminance value three times for red, green, and blue. Each component is |
8925f36f AW |
20989 | then multiplied by the signed scale factor @code{GL_c_SCALE}, added to |
20990 | the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
20991 | @code{glPixelTransfer}). | |
20992 | ||
20993 | @item @code{GL_DEPTH_COMPONENT} | |
c7b31271 | 20994 | Each element is a single depth value. The GL converts it to floating |
8925f36f AW |
20995 | point, multiplies by the signed scale factor @code{GL_DEPTH_SCALE}, adds |
20996 | the signed bias @code{GL_DEPTH_BIAS}, and clamps to the range [0,1] (see | |
20997 | @code{glPixelTransfer}). | |
20998 | ||
20999 | @end table | |
21000 | ||
21001 | Refer to the @code{glDrawPixels} reference page for a description of the | |
21002 | acceptable values for the @var{type} parameter. | |
21003 | ||
21004 | If an application wants to store the texture at a certain resolution or | |
21005 | in a certain format, it can request the resolution and format with | |
c7b31271 DH |
21006 | @var{internalFormat}. The GL will choose an internal representation |
21007 | that closely approximates that requested by @var{internalFormat}, but it | |
21008 | may not match exactly. (The representations specified by | |
8925f36f | 21009 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and |
c7b31271 DH |
21010 | @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 |
21011 | may also be used to specify the above representations.) | |
8925f36f AW |
21012 | |
21013 | If the @var{internalFormat} parameter is one of the generic compressed | |
21014 | formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
21015 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
21016 | @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will | |
21017 | replace the internal format with the symbolic constant for a specific | |
c7b31271 | 21018 | internal format and compress the texture before storage. If no |
8925f36f AW |
21019 | corresponding internal format is available, or the GL can not compress |
21020 | that image for any reason, the internal format is instead replaced with | |
21021 | a corresponding base internal format. | |
21022 | ||
21023 | If the @var{internalFormat} parameter is @code{GL_SRGB}, | |
21024 | @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8}, | |
21025 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
21026 | or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red, | |
21027 | green, blue, or luminance components are encoded in the sRGB color | |
c7b31271 | 21028 | space. Any alpha component is left unchanged. The conversion from the |
3c9b6116 AW |
21029 | sRGB encoded component @r{@var{c}_@var{s}} to a linear component |
21030 | @r{@var{c}_@var{l}} is: | |
8925f36f | 21031 | |
3c9b6116 AW |
21032 | @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045), |
21033 | ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)} | |
8925f36f | 21034 | |
3c9b6116 | 21035 | Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1]. |
8925f36f AW |
21036 | |
21037 | Use the @code{GL_PROXY_TEXTURE_2D} or @code{GL_PROXY_TEXTURE_CUBE_MAP} | |
c7b31271 | 21038 | target to try out a resolution and format. The implementation will |
8925f36f | 21039 | update and recompute its best match for the requested storage resolution |
c7b31271 DH |
21040 | and format. To then query this state, call |
21041 | @code{glGetTexLevelParameter}. If the texture cannot be accommodated, | |
8925f36f AW |
21042 | texture state is set to 0. |
21043 | ||
21044 | A one-component texture image uses only the red component of the RGBA | |
c7b31271 DH |
21045 | color extracted from @var{data}. A two-component image uses the R and A |
21046 | values. A three-component image uses the R, G, and B values. A | |
8925f36f AW |
21047 | four-component image uses all of the RGBA components. |
21048 | ||
21049 | Depth textures can be treated as LUMINANCE, INTENSITY or ALPHA textures | |
c7b31271 | 21050 | during texture filtering and application. Image-based shadowing can be |
8925f36f | 21051 | enabled by comparing texture r coordinates to depth texture values to |
c7b31271 | 21052 | generate a boolean result. See @code{glTexParameter} for details on |
8925f36f AW |
21053 | texture comparison. |
21054 | ||
8925f36f AW |
21055 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
21056 | @code{GL_TEXTURE_2D}, @code{GL_PROXY_TEXTURE_2D}, | |
21057 | @code{GL_PROXY_TEXTURE_CUBE_MAP}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
21058 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
21059 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
21060 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
21061 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
21062 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
21063 | ||
21064 | @code{GL_INVALID_ENUM} is generated if @var{target} is one of the six | |
21065 | cube map 2D image targets and the width and height parameters are not | |
21066 | equal. | |
21067 | ||
21068 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
21069 | constant. | |
21070 | ||
21071 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
21072 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
21073 | ||
21074 | @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is | |
21075 | less than 0 or greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
21076 | ||
21077 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
21078 | ||
21079 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
21080 | @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of |
21081 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
21082 | |
21083 | @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1, | |
21084 | 2, 3, 4, or one of the accepted resolution and format symbolic | |
21085 | constants. | |
21086 | ||
21087 | @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is | |
21088 | less than 0 or greater than 2 + @code{GL_MAX_TEXTURE_SIZE}. | |
21089 | ||
21090 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
21091 | not supported and the @var{width} or @var{height} cannot be represented | |
3c9b6116 | 21092 | as @r{2^@var{k}+2(@var{border},)} for some integer value of @var{k}. |
8925f36f AW |
21093 | |
21094 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
21095 | ||
21096 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21097 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
21098 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
21099 | and @var{format} is not @code{GL_RGB}. | |
21100 | ||
21101 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21102 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
21103 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
21104 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
21105 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
21106 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
21107 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
21108 | ||
21109 | @code{GL_INVALID_OPERATION} is generated if @var{target} is not | |
21110 | @code{GL_TEXTURE_2D} or @code{GL_PROXY_TEXTURE_2D} and | |
21111 | @var{internalFormat} is @code{GL_DEPTH_COMPONENT}, | |
21112 | @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, or | |
21113 | @code{GL_DEPTH_COMPONENT32}. | |
21114 | ||
21115 | @code{GL_INVALID_OPERATION} is generated if @var{format} is | |
21116 | @code{GL_DEPTH_COMPONENT} and @var{internalFormat} is not | |
21117 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
21118 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}. | |
21119 | ||
21120 | @code{GL_INVALID_OPERATION} is generated if @var{internalFormat} is | |
21121 | @code{GL_DEPTH_COMPONENT}, @code{GL_DEPTH_COMPONENT16}, | |
21122 | @code{GL_DEPTH_COMPONENT24}, or @code{GL_DEPTH_COMPONENT32}, and | |
21123 | @var{format} is not @code{GL_DEPTH_COMPONENT}. | |
21124 | ||
21125 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21126 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
21127 | object's data store is currently mapped. | |
21128 | ||
21129 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21130 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
21131 | would be unpacked from the buffer object such that the memory reads | |
21132 | required would exceed the data store size. | |
21133 | ||
21134 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21135 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
21136 | is not evenly divisible into the number of bytes needed to store in | |
21137 | memory a datum indicated by @var{type}. | |
21138 | ||
21139 | @code{GL_INVALID_OPERATION} is generated if @code{glTexImage2D} is | |
21140 | executed between the execution of @code{glBegin} and the corresponding | |
21141 | execution of @code{glEnd}. | |
21142 | ||
bb894c9d | 21143 | @end deftypefun |
8925f36f | 21144 | |
bb894c9d | 21145 | @deftypefun void glTexImage3D target level internalFormat width height depth border format type data |
3c9b6116 AW |
21146 | Specify a three-dimensional texture image. |
21147 | ||
8925f36f AW |
21148 | @table @asis |
21149 | @item @var{target} | |
c7b31271 | 21150 | Specifies the target texture. Must be @code{GL_TEXTURE_3D} or |
8925f36f AW |
21151 | @code{GL_PROXY_TEXTURE_3D}. |
21152 | ||
21153 | @item @var{level} | |
c7b31271 | 21154 | Specifies the level-of-detail number. Level 0 is the base image level. |
3c9b6116 | 21155 | Level @r{@var{n}} is the @r{@var{n}^@var{th}} mipmap reduction image. |
8925f36f AW |
21156 | |
21157 | @item @var{internalFormat} | |
c7b31271 | 21158 | Specifies the number of color components in the texture. Must be 1, 2, |
8925f36f AW |
21159 | 3, or 4, or one of the following symbolic constants: @code{GL_ALPHA}, |
21160 | @code{GL_ALPHA4}, @code{GL_ALPHA8}, @code{GL_ALPHA12}, | |
21161 | @code{GL_ALPHA16}, @code{GL_COMPRESSED_ALPHA}, | |
21162 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
21163 | @code{GL_COMPRESSED_INTENSITY}, @code{GL_COMPRESSED_RGB}, | |
21164 | @code{GL_COMPRESSED_RGBA}, @code{GL_LUMINANCE}, @code{GL_LUMINANCE4}, | |
21165 | @code{GL_LUMINANCE8}, @code{GL_LUMINANCE12}, @code{GL_LUMINANCE16}, | |
21166 | @code{GL_LUMINANCE_ALPHA}, @code{GL_LUMINANCE4_ALPHA4}, | |
21167 | @code{GL_LUMINANCE6_ALPHA2}, @code{GL_LUMINANCE8_ALPHA8}, | |
21168 | @code{GL_LUMINANCE12_ALPHA4}, @code{GL_LUMINANCE12_ALPHA12}, | |
21169 | @code{GL_LUMINANCE16_ALPHA16}, @code{GL_INTENSITY}, | |
21170 | @code{GL_INTENSITY4}, @code{GL_INTENSITY8}, @code{GL_INTENSITY12}, | |
21171 | @code{GL_INTENSITY16}, @code{GL_R3_G3_B2}, @code{GL_RGB}, | |
21172 | @code{GL_RGB4}, @code{GL_RGB5}, @code{GL_RGB8}, @code{GL_RGB10}, | |
21173 | @code{GL_RGB12}, @code{GL_RGB16}, @code{GL_RGBA}, @code{GL_RGBA2}, | |
21174 | @code{GL_RGBA4}, @code{GL_RGB5_A1}, @code{GL_RGBA8}, @code{GL_RGB10_A2}, | |
21175 | @code{GL_RGBA12}, @code{GL_RGBA16}, @code{GL_SLUMINANCE}, | |
21176 | @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
21177 | @code{GL_SLUMINANCE8_ALPHA8}, @code{GL_SRGB}, @code{GL_SRGB8}, | |
21178 | @code{GL_SRGB_ALPHA}, or @code{GL_SRGB8_ALPHA8}. | |
21179 | ||
21180 | @item @var{width} | |
c7b31271 | 21181 | Specifies the width of the texture image including the border if any. If |
8925f36f | 21182 | the GL version does not support non-power-of-two sizes, this value must |
c7b31271 | 21183 | be @r{2^@var{n}+2(@var{border},)} for some integer @r{@var{n}}. All |
3c9b6116 AW |
21184 | implementations support 3D texture images that are at least 16 texels |
21185 | wide. | |
8925f36f AW |
21186 | |
21187 | @item @var{height} | |
21188 | Specifies the height of the texture image including the border if any. | |
21189 | If the GL version does not support non-power-of-two sizes, this value | |
3c9b6116 AW |
21190 | must be @r{2^@var{m}+2(@var{border},)} for some integer @r{@var{m}}. |
21191 | All implementations support 3D texture images that are at least 16 | |
21192 | texels high. | |
8925f36f AW |
21193 | |
21194 | @item @var{depth} | |
c7b31271 | 21195 | Specifies the depth of the texture image including the border if any. If |
8925f36f | 21196 | the GL version does not support non-power-of-two sizes, this value must |
c7b31271 | 21197 | be @r{2^@var{k}+2(@var{border},)} for some integer @r{@var{k}}. All |
3c9b6116 AW |
21198 | implementations support 3D texture images that are at least 16 texels |
21199 | deep. | |
8925f36f AW |
21200 | |
21201 | @item @var{border} | |
c7b31271 | 21202 | Specifies the width of the border. Must be either 0 or 1. |
8925f36f AW |
21203 | |
21204 | @item @var{format} | |
c7b31271 | 21205 | Specifies the format of the pixel data. The following symbolic values |
8925f36f AW |
21206 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, |
21207 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
21208 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
21209 | @code{GL_LUMINANCE_ALPHA}. | |
21210 | ||
21211 | @item @var{type} | |
c7b31271 DH |
21212 | Specifies the data type of the pixel data. The following symbolic |
21213 | values are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, | |
21214 | @code{GL_BITMAP}, @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, | |
21215 | @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT}, | |
21216 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
21217 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
21218 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
21219 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
21220 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
21221 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
21222 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
8925f36f AW |
21223 | |
21224 | @item @var{data} | |
21225 | Specifies a pointer to the image data in memory. | |
21226 | ||
21227 | @end table | |
21228 | ||
8925f36f | 21229 | Texturing maps a portion of a specified texture image onto each |
c7b31271 | 21230 | graphical primitive for which texturing is enabled. To enable and |
8925f36f AW |
21231 | disable three-dimensional texturing, call @code{glEnable} and |
21232 | @code{glDisable} with argument @code{GL_TEXTURE_3D}. | |
21233 | ||
c7b31271 | 21234 | To define texture images, call @code{glTexImage3D}. The arguments |
8925f36f AW |
21235 | describe the parameters of the texture image, such as height, width, |
21236 | depth, width of the border, level-of-detail number (see | |
c7b31271 | 21237 | @code{glTexParameter}), and number of color components provided. The |
8925f36f AW |
21238 | last three arguments describe how the image is represented in memory; |
21239 | they are identical to the pixel formats used for @code{glDrawPixels}. | |
21240 | ||
21241 | If @var{target} is @code{GL_PROXY_TEXTURE_3D}, no data is read from | |
21242 | @var{data}, but all of the texture image state is recalculated, checked | |
21243 | for consistency, and checked against the implementation's capabilities. | |
21244 | If the implementation cannot handle a texture of the requested texture | |
21245 | size, it sets all of the image state to 0, but does not generate an | |
c7b31271 | 21246 | error (see @code{glGetError}). To query for an entire mipmap array, use |
8925f36f AW |
21247 | an image array level greater than or equal to 1. |
21248 | ||
21249 | If @var{target} is @code{GL_TEXTURE_3D}, data is read from @var{data} as | |
21250 | a sequence of signed or unsigned bytes, shorts, or longs, or | |
c7b31271 | 21251 | single-precision floating-point values, depending on @var{type}. These |
8925f36f | 21252 | values are grouped into sets of one, two, three, or four values, |
c7b31271 | 21253 | depending on @var{format}, to form elements. If @var{type} is |
8925f36f | 21254 | @code{GL_BITMAP}, the data is considered as a string of unsigned bytes |
c7b31271 | 21255 | (and @var{format} must be @code{GL_COLOR_INDEX}). Each data byte is |
8925f36f AW |
21256 | treated as eight 1-bit elements, with bit ordering determined by |
21257 | @code{GL_UNPACK_LSB_FIRST} (see @code{glPixelStore}). | |
21258 | ||
21259 | If a non-zero named buffer object is bound to the | |
21260 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
21261 | texture image is specified, @var{data} is treated as a byte offset into | |
21262 | the buffer object's data store. | |
21263 | ||
21264 | The first element corresponds to the lower left corner of the texture | |
c7b31271 | 21265 | image. Subsequent elements progress left-to-right through the remaining |
8925f36f | 21266 | texels in the lowest row of the texture image, and then in successively |
c7b31271 | 21267 | higher rows of the texture image. The final element corresponds to the |
8925f36f AW |
21268 | upper right corner of the texture image. |
21269 | ||
21270 | @var{format} determines the composition of each element in @var{data}. | |
21271 | It can assume one of these symbolic values: | |
21272 | ||
21273 | @table @asis | |
21274 | @item @code{GL_COLOR_INDEX} | |
c7b31271 | 21275 | Each element is a single value, a color index. The GL converts it to |
8925f36f AW |
21276 | fixed point (with an unspecified number of zero bits to the right of the |
21277 | binary point), shifted left or right depending on the value and sign of | |
21278 | @code{GL_INDEX_SHIFT}, and added to @code{GL_INDEX_OFFSET} (see | |
c7b31271 | 21279 | @code{glPixelTransfer}). The resulting index is converted to a set of |
8925f36f AW |
21280 | color components using the @code{GL_PIXEL_MAP_I_TO_R}, |
21281 | @code{GL_PIXEL_MAP_I_TO_G}, @code{GL_PIXEL_MAP_I_TO_B}, and | |
21282 | @code{GL_PIXEL_MAP_I_TO_A} tables, and clamped to the range [0,1]. | |
21283 | ||
21284 | @item @code{GL_RED} | |
c7b31271 | 21285 | Each element is a single red component. The GL converts it to floating |
8925f36f | 21286 | point and assembles it into an RGBA element by attaching 0 for green and |
c7b31271 | 21287 | blue, and 1 for alpha. Each component is then multiplied by the signed |
8925f36f AW |
21288 | scale factor @code{GL_c_SCALE}, added to the signed bias |
21289 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
21290 | @code{glPixelTransfer}). | |
21291 | ||
21292 | @item @code{GL_GREEN} | |
c7b31271 DH |
21293 | Each element is a single green component. The GL converts it to |
21294 | floating point and assembles it into an RGBA element by attaching 0 for | |
21295 | red and blue, and 1 for alpha. Each component is then multiplied by the | |
21296 | signed scale factor @code{GL_c_SCALE}, added to the signed bias | |
8925f36f AW |
21297 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see |
21298 | @code{glPixelTransfer}). | |
21299 | ||
21300 | @item @code{GL_BLUE} | |
c7b31271 | 21301 | Each element is a single blue component. The GL converts it to floating |
8925f36f | 21302 | point and assembles it into an RGBA element by attaching 0 for red and |
c7b31271 | 21303 | green, and 1 for alpha. Each component is then multiplied by the signed |
8925f36f AW |
21304 | scale factor @code{GL_c_SCALE}, added to the signed bias |
21305 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
21306 | @code{glPixelTransfer}). | |
21307 | ||
21308 | @item @code{GL_ALPHA} | |
c7b31271 DH |
21309 | Each element is a single alpha component. The GL converts it to |
21310 | floating point and assembles it into an RGBA element by attaching 0 for | |
21311 | red, green, and blue. Each component is then multiplied by the signed | |
21312 | scale factor @code{GL_c_SCALE}, added to the signed bias | |
21313 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
21314 | @code{glPixelTransfer}). | |
8925f36f AW |
21315 | |
21316 | @item @code{GL_INTENSITY} | |
c7b31271 DH |
21317 | Each element is a single intensity value. The GL converts it to |
21318 | floating point, then assembles it into an RGBA element by replicating | |
21319 | the intensity value three times for red, green, blue, and alpha. Each | |
8925f36f AW |
21320 | component is then multiplied by the signed scale factor |
21321 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
21322 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
21323 | ||
21324 | @item @code{GL_RGB} | |
21325 | @item @code{GL_BGR} | |
c7b31271 DH |
21326 | Each element is an RGB triple. The GL converts it to floating point and |
21327 | assembles it into an RGBA element by attaching 1 for alpha. Each | |
8925f36f AW |
21328 | component is then multiplied by the signed scale factor |
21329 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and | |
21330 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
21331 | ||
21332 | @item @code{GL_RGBA} | |
21333 | @item @code{GL_BGRA} | |
c7b31271 | 21334 | Each element contains all four components. Each component is multiplied |
8925f36f AW |
21335 | by the signed scale factor @code{GL_c_SCALE}, added to the signed bias |
21336 | @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
21337 | @code{glPixelTransfer}). | |
21338 | ||
21339 | @item @code{GL_LUMINANCE} | |
c7b31271 DH |
21340 | Each element is a single luminance value. The GL converts it to |
21341 | floating point, then assembles it into an RGBA element by replicating | |
21342 | the luminance value three times for red, green, and blue and attaching 1 | |
21343 | for alpha. Each component is then multiplied by the signed scale factor | |
8925f36f AW |
21344 | @code{GL_c_SCALE}, added to the signed bias @code{GL_c_BIAS}, and |
21345 | clamped to the range [0,1] (see @code{glPixelTransfer}). | |
21346 | ||
21347 | @item @code{GL_LUMINANCE_ALPHA} | |
c7b31271 | 21348 | Each element is a luminance/alpha pair. The GL converts it to floating |
8925f36f | 21349 | point, then assembles it into an RGBA element by replicating the |
c7b31271 | 21350 | luminance value three times for red, green, and blue. Each component is |
8925f36f AW |
21351 | then multiplied by the signed scale factor @code{GL_c_SCALE}, added to |
21352 | the signed bias @code{GL_c_BIAS}, and clamped to the range [0,1] (see | |
21353 | @code{glPixelTransfer}). | |
21354 | ||
21355 | @end table | |
21356 | ||
21357 | Refer to the @code{glDrawPixels} reference page for a description of the | |
21358 | acceptable values for the @var{type} parameter. | |
21359 | ||
21360 | If an application wants to store the texture at a certain resolution or | |
21361 | in a certain format, it can request the resolution and format with | |
c7b31271 DH |
21362 | @var{internalFormat}. The GL will choose an internal representation |
21363 | that closely approximates that requested by @var{internalFormat}, but it | |
21364 | may not match exactly. (The representations specified by | |
8925f36f | 21365 | @code{GL_LUMINANCE}, @code{GL_LUMINANCE_ALPHA}, @code{GL_RGB}, and |
c7b31271 DH |
21366 | @code{GL_RGBA} must match exactly. The numeric values 1, 2, 3, and 4 |
21367 | may also be used to specify the above representations.) | |
8925f36f AW |
21368 | |
21369 | If the @var{internalFormat} parameter is one of the generic compressed | |
21370 | formats, @code{GL_COMPRESSED_ALPHA}, @code{GL_COMPRESSED_INTENSITY}, | |
21371 | @code{GL_COMPRESSED_LUMINANCE}, @code{GL_COMPRESSED_LUMINANCE_ALPHA}, | |
21372 | @code{GL_COMPRESSED_RGB}, or @code{GL_COMPRESSED_RGBA}, the GL will | |
21373 | replace the internal format with the symbolic constant for a specific | |
c7b31271 | 21374 | internal format and compress the texture before storage. If no |
8925f36f AW |
21375 | corresponding internal format is available, or the GL can not compress |
21376 | that image for any reason, the internal format is instead replaced with | |
21377 | a corresponding base internal format. | |
21378 | ||
21379 | If the @var{internalFormat} parameter is @code{GL_SRGB}, | |
21380 | @code{GL_SRGB8}, @code{GL_SRGB_ALPHA}, @code{GL_SRGB8_ALPHA8}, | |
21381 | @code{GL_SLUMINANCE}, @code{GL_SLUMINANCE8}, @code{GL_SLUMINANCE_ALPHA}, | |
21382 | or @code{GL_SLUMINANCE8_ALPHA8}, the texture is treated as if the red, | |
21383 | green, blue, or luminance components are encoded in the sRGB color | |
c7b31271 | 21384 | space. Any alpha component is left unchanged. The conversion from the |
3c9b6116 AW |
21385 | sRGB encoded component @r{@var{c}_@var{s}} to a linear component |
21386 | @r{@var{c}_@var{l}} is: | |
8925f36f | 21387 | |
3c9b6116 AW |
21388 | @r{@var{c}_@var{l}=@{(@var{c}_@var{s}/12.92 if @var{c}_@var{s}≤0.04045), |
21389 | ((@code{c}_@code{s}+0.055/1.055)^2.4 if @var{c}_@var{s}>0.04045)} | |
8925f36f | 21390 | |
3c9b6116 | 21391 | Assume @r{@var{c}_@var{s}} is the sRGB component in the range [0,1]. |
8925f36f AW |
21392 | |
21393 | Use the @code{GL_PROXY_TEXTURE_3D} target to try out a resolution and | |
c7b31271 DH |
21394 | format. The implementation will update and recompute its best match for |
21395 | the requested storage resolution and format. To then query this state, | |
21396 | call @code{glGetTexLevelParameter}. If the texture cannot be | |
8925f36f AW |
21397 | accommodated, texture state is set to 0. |
21398 | ||
21399 | A one-component texture image uses only the red component of the RGBA | |
c7b31271 DH |
21400 | color extracted from @var{data}. A two-component image uses the R and A |
21401 | values. A three-component image uses the R, G, and B values. A | |
8925f36f AW |
21402 | four-component image uses all of the RGBA components. |
21403 | ||
8925f36f AW |
21404 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
21405 | @code{GL_TEXTURE_3D} or @code{GL_PROXY_TEXTURE_3D}. | |
21406 | ||
21407 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
c7b31271 DH |
21408 | format constant. Format constants other than @code{GL_STENCIL_INDEX} |
21409 | and @code{GL_DEPTH_COMPONENT} are accepted. | |
8925f36f AW |
21410 | |
21411 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
21412 | constant. | |
21413 | ||
21414 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
21415 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
21416 | ||
21417 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
21418 | ||
21419 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 AW |
21420 | @r{@var{log}_2(@var{max},)}, where @var{max} is the returned value of |
21421 | @code{GL_MAX_TEXTURE_SIZE}. | |
8925f36f AW |
21422 | |
21423 | @code{GL_INVALID_VALUE} is generated if @var{internalFormat} is not 1, | |
21424 | 2, 3, 4, or one of the accepted resolution and format symbolic | |
21425 | constants. | |
21426 | ||
21427 | @code{GL_INVALID_VALUE} is generated if @var{width}, @var{height}, or | |
21428 | @var{depth} is less than 0 or greater than 2 + | |
21429 | @code{GL_MAX_TEXTURE_SIZE}. | |
21430 | ||
21431 | @code{GL_INVALID_VALUE} is generated if non-power-of-two textures are | |
21432 | not supported and the @var{width}, @var{height}, or @var{depth} cannot | |
3c9b6116 AW |
21433 | be represented as @r{2^@var{k}+2(@var{border},)} for some integer value |
21434 | of @var{k}. | |
8925f36f AW |
21435 | |
21436 | @code{GL_INVALID_VALUE} is generated if @var{border} is not 0 or 1. | |
21437 | ||
21438 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21439 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
21440 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
21441 | and @var{format} is not @code{GL_RGB}. | |
21442 | ||
21443 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21444 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
21445 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
21446 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
21447 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
21448 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
21449 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
21450 | ||
21451 | @code{GL_INVALID_OPERATION} is generated if @var{format} or | |
21452 | @var{internalFormat} is @code{GL_DEPTH_COMPONENT}, | |
21453 | @code{GL_DEPTH_COMPONENT16}, @code{GL_DEPTH_COMPONENT24}, or | |
21454 | @code{GL_DEPTH_COMPONENT32}. | |
21455 | ||
21456 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21457 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
21458 | object's data store is currently mapped. | |
21459 | ||
21460 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21461 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
21462 | would be unpacked from the buffer object such that the memory reads | |
21463 | required would exceed the data store size. | |
21464 | ||
21465 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21466 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
21467 | is not evenly divisible into the number of bytes needed to store in | |
21468 | memory a datum indicated by @var{type}. | |
21469 | ||
21470 | @code{GL_INVALID_OPERATION} is generated if @code{glTexImage3D} is | |
21471 | executed between the execution of @code{glBegin} and the corresponding | |
21472 | execution of @code{glEnd}. | |
21473 | ||
bb894c9d | 21474 | @end deftypefun |
8925f36f | 21475 | |
bb894c9d AW |
21476 | @deftypefun void glTexParameterf target pname param |
21477 | @deftypefunx void glTexParameteri target pname param | |
d172eed9 AW |
21478 | @deftypefunx void glTexParameterfv target pname params |
21479 | @deftypefunx void glTexParameteriv target pname params | |
3c9b6116 AW |
21480 | Set texture parameters. |
21481 | ||
8925f36f AW |
21482 | @table @asis |
21483 | @item @var{target} | |
21484 | Specifies the target texture, which must be either @code{GL_TEXTURE_1D}, | |
21485 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_3D}, or | |
21486 | @code{GL_TEXTURE_CUBE_MAP}. | |
21487 | ||
21488 | @item @var{pname} | |
21489 | Specifies the symbolic name of a single-valued texture parameter. | |
21490 | @var{pname} can be one of the following: @code{GL_TEXTURE_MIN_FILTER}, | |
21491 | @code{GL_TEXTURE_MAG_FILTER}, @code{GL_TEXTURE_MIN_LOD}, | |
21492 | @code{GL_TEXTURE_MAX_LOD}, @code{GL_TEXTURE_BASE_LEVEL}, | |
21493 | @code{GL_TEXTURE_MAX_LEVEL}, @code{GL_TEXTURE_WRAP_S}, | |
21494 | @code{GL_TEXTURE_WRAP_T}, @code{GL_TEXTURE_WRAP_R}, | |
21495 | @code{GL_TEXTURE_PRIORITY}, @code{GL_TEXTURE_COMPARE_MODE}, | |
21496 | @code{GL_TEXTURE_COMPARE_FUNC}, @code{GL_DEPTH_TEXTURE_MODE}, or | |
21497 | @code{GL_GENERATE_MIPMAP}. | |
21498 | ||
21499 | @item @var{param} | |
21500 | Specifies the value of @var{pname}. | |
21501 | ||
21502 | @end table | |
21503 | ||
8925f36f | 21504 | Texture mapping is a technique that applies an image onto an object's |
c7b31271 | 21505 | surface as if the image were a decal or cellophane shrink-wrap. The |
3c9b6116 | 21506 | image is created in texture space, with an (@r{@var{s}}, @r{@var{t}}) |
c7b31271 | 21507 | coordinate system. A texture is a one- or two-dimensional image and a |
3c9b6116 | 21508 | set of parameters that determine how samples are derived from the image. |
8925f36f AW |
21509 | |
21510 | @code{glTexParameter} assigns the value or values in @var{params} to the | |
c7b31271 | 21511 | texture parameter specified as @var{pname}. @var{target} defines the |
8925f36f | 21512 | target texture, either @code{GL_TEXTURE_1D}, @code{GL_TEXTURE_2D}, or |
c7b31271 DH |
21513 | @code{GL_TEXTURE_3D}. The following symbols are accepted in |
21514 | @var{pname}: | |
8925f36f AW |
21515 | |
21516 | @table @asis | |
21517 | @item @code{GL_TEXTURE_MIN_FILTER} | |
21518 | The texture minifying function is used whenever the pixel being textured | |
c7b31271 DH |
21519 | maps to an area greater than one texture element. There are six defined |
21520 | minifying functions. Two of them use the nearest one or nearest four | |
21521 | texture elements to compute the texture value. The other four use | |
8925f36f AW |
21522 | mipmaps. |
21523 | ||
21524 | A mipmap is an ordered set of arrays representing the same image at | |
c7b31271 | 21525 | progressively lower resolutions. If the texture has dimensions |
3c9b6116 | 21526 | @r{2^@var{n}×2^@var{m}}, there are @r{@var{max}(@var{n},@var{m})+1} |
c7b31271 DH |
21527 | mipmaps. The first mipmap is the original texture, with dimensions |
21528 | @r{2^@var{n}×2^@var{m}}. Each subsequent mipmap has dimensions | |
3c9b6116 AW |
21529 | @r{2^@var{k}-1,×2^@var{l}-1,}, where @r{2^@var{k}×2^@var{l}} are the |
21530 | dimensions of the previous mipmap, until either @r{@var{k}=0} or | |
c7b31271 | 21531 | @r{@var{l}=0}. At that point, subsequent mipmaps have dimension |
3c9b6116 | 21532 | @r{1×2^@var{l}-1,} or @r{2^@var{k}-1,×1} until the final mipmap, which |
c7b31271 | 21533 | has dimension @r{1×1}. To define the mipmaps, call @code{glTexImage1D}, |
8925f36f AW |
21534 | @code{glTexImage2D}, @code{glTexImage3D}, @code{glCopyTexImage1D}, or |
21535 | @code{glCopyTexImage2D} with the @var{level} argument indicating the | |
c7b31271 | 21536 | order of the mipmaps. Level 0 is the original texture; level |
3c9b6116 | 21537 | @r{@var{max}(@var{n},@var{m})} is the final @r{1×1} mipmap. |
8925f36f AW |
21538 | |
21539 | @var{params} supplies a function for minifying the texture as one of the | |
21540 | following: | |
21541 | ||
21542 | As more texture elements are sampled in the minification process, fewer | |
c7b31271 | 21543 | aliasing artifacts will be apparent. While the @code{GL_NEAREST} and |
8925f36f AW |
21544 | @code{GL_LINEAR} minification functions can be faster than the other |
21545 | four, they sample only one or four texture elements to determine the | |
21546 | texture value of the pixel being rendered and can produce moire patterns | |
c7b31271 DH |
21547 | or ragged transitions. The initial value of |
21548 | @code{GL_TEXTURE_MIN_FILTER} is @code{GL_NEAREST_MIPMAP_LINEAR}. | |
8925f36f AW |
21549 | |
21550 | @item @code{GL_TEXTURE_MAG_FILTER} | |
21551 | The texture magnification function is used when the pixel being textured | |
c7b31271 | 21552 | maps to an area less than or equal to one texture element. It sets the |
8925f36f | 21553 | texture magnification function to either @code{GL_NEAREST} or |
c7b31271 DH |
21554 | @code{GL_LINEAR} (see below). @code{GL_NEAREST} is generally faster |
21555 | than @code{GL_LINEAR}, but it can produce textured images with sharper | |
21556 | edges because the transition between texture elements is not as smooth. | |
21557 | The initial value of @code{GL_TEXTURE_MAG_FILTER} is @code{GL_LINEAR}. | |
8925f36f AW |
21558 | |
21559 | @end table | |
21560 | ||
21561 | @table @asis | |
21562 | @item @code{GL_NEAREST} | |
21563 | Returns the value of the texture element that is nearest (in Manhattan | |
21564 | distance) to the center of the pixel being textured. | |
21565 | ||
21566 | @item @code{GL_LINEAR} | |
21567 | Returns the weighted average of the four texture elements that are | |
c7b31271 | 21568 | closest to the center of the pixel being textured. These can include |
8925f36f AW |
21569 | border texture elements, depending on the values of |
21570 | @code{GL_TEXTURE_WRAP_S} and @code{GL_TEXTURE_WRAP_T}, and on the exact | |
21571 | mapping. | |
21572 | ||
21573 | @item @code{GL_NEAREST_MIPMAP_NEAREST} | |
21574 | Chooses the mipmap that most closely matches the size of the pixel being | |
21575 | textured and uses the @code{GL_NEAREST} criterion (the texture element | |
21576 | nearest to the center of the pixel) to produce a texture value. | |
21577 | ||
21578 | @item @code{GL_LINEAR_MIPMAP_NEAREST} | |
21579 | Chooses the mipmap that most closely matches the size of the pixel being | |
21580 | textured and uses the @code{GL_LINEAR} criterion (a weighted average of | |
21581 | the four texture elements that are closest to the center of the pixel) | |
21582 | to produce a texture value. | |
21583 | ||
21584 | @item @code{GL_NEAREST_MIPMAP_LINEAR} | |
21585 | Chooses the two mipmaps that most closely match the size of the pixel | |
21586 | being textured and uses the @code{GL_NEAREST} criterion (the texture | |
21587 | element nearest to the center of the pixel) to produce a texture value | |
c7b31271 DH |
21588 | from each mipmap. The final texture value is a weighted average of |
21589 | those two values. | |
8925f36f AW |
21590 | |
21591 | @item @code{GL_LINEAR_MIPMAP_LINEAR} | |
21592 | Chooses the two mipmaps that most closely match the size of the pixel | |
21593 | being textured and uses the @code{GL_LINEAR} criterion (a weighted | |
21594 | average of the four texture elements that are closest to the center of | |
c7b31271 | 21595 | the pixel) to produce a texture value from each mipmap. The final |
8925f36f AW |
21596 | texture value is a weighted average of those two values. |
21597 | ||
21598 | @end table | |
21599 | ||
21600 | @table @asis | |
21601 | @item @code{GL_NEAREST} | |
21602 | Returns the value of the texture element that is nearest (in Manhattan | |
21603 | distance) to the center of the pixel being textured. | |
21604 | ||
21605 | @item @code{GL_LINEAR} | |
21606 | Returns the weighted average of the four texture elements that are | |
c7b31271 | 21607 | closest to the center of the pixel being textured. These can include |
8925f36f AW |
21608 | border texture elements, depending on the values of |
21609 | @code{GL_TEXTURE_WRAP_S} and @code{GL_TEXTURE_WRAP_T}, and on the exact | |
21610 | mapping. | |
21611 | ||
21612 | @end table | |
21613 | ||
21614 | ||
21615 | ||
21616 | @table @asis | |
21617 | @item @code{GL_TEXTURE_MIN_LOD} | |
c7b31271 | 21618 | Sets the minimum level-of-detail parameter. This floating-point value |
8925f36f AW |
21619 | limits the selection of highest resolution mipmap (lowest mipmap level). |
21620 | The initial value is -1000. | |
21621 | ||
21622 | @end table | |
21623 | ||
21624 | ||
21625 | ||
21626 | @table @asis | |
21627 | @item @code{GL_TEXTURE_MAX_LOD} | |
c7b31271 | 21628 | Sets the maximum level-of-detail parameter. This floating-point value |
8925f36f | 21629 | limits the selection of the lowest resolution mipmap (highest mipmap |
c7b31271 | 21630 | level). The initial value is 1000. |
8925f36f AW |
21631 | |
21632 | @end table | |
21633 | ||
21634 | ||
21635 | ||
21636 | @table @asis | |
21637 | @item @code{GL_TEXTURE_BASE_LEVEL} | |
c7b31271 DH |
21638 | Specifies the index of the lowest defined mipmap level. This is an |
21639 | integer value. The initial value is 0. | |
8925f36f AW |
21640 | |
21641 | @end table | |
21642 | ||
21643 | ||
21644 | ||
21645 | @table @asis | |
21646 | @item @code{GL_TEXTURE_MAX_LEVEL} | |
c7b31271 DH |
21647 | Sets the index of the highest defined mipmap level. This is an integer |
21648 | value. The initial value is 1000. | |
8925f36f AW |
21649 | |
21650 | @end table | |
21651 | ||
21652 | ||
21653 | ||
21654 | @table @asis | |
21655 | @item @code{GL_TEXTURE_WRAP_S} | |
3c9b6116 | 21656 | Sets the wrap parameter for texture coordinate @r{@var{s}} to either |
8925f36f | 21657 | @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE}, |
c7b31271 | 21658 | @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. @code{GL_CLAMP} causes |
3c9b6116 AW |
21659 | @r{@var{s}} coordinates to be clamped to the range [0,1] and is useful |
21660 | for preventing wrapping artifacts when mapping a single image onto an | |
c7b31271 | 21661 | object. @code{GL_CLAMP_TO_BORDER} causes the @r{@var{s}} coordinate to |
3c9b6116 AW |
21662 | be clamped to the range @r{[-1/2@var{N},,1+1/2@var{N},]}, where |
21663 | @r{@var{N}} is the size of the texture in the direction of | |
21664 | clamping.@code{GL_CLAMP_TO_EDGE} causes @r{@var{s}} coordinates to be | |
21665 | clamped to the range @r{[1/2@var{N},,1-1/2@var{N},]}, where @r{@var{N}} | |
21666 | is the size of the texture in the direction of clamping. | |
21667 | @code{GL_REPEAT} causes the integer part of the @r{@var{s}} coordinate | |
21668 | to be ignored; the GL uses only the fractional part, thereby creating a | |
c7b31271 | 21669 | repeating pattern. @code{GL_MIRRORED_REPEAT} causes the @r{@var{s}} |
3c9b6116 AW |
21670 | coordinate to be set to the fractional part of the texture coordinate if |
21671 | the integer part of @r{@var{s}} is even; if the integer part of | |
21672 | @r{@var{s}} is odd, then the @r{@var{s}} texture coordinate is set to | |
21673 | @r{1-@var{frac}(@var{s},)}, where @r{@var{frac}(@var{s},)} represents | |
c7b31271 DH |
21674 | the fractional part of @r{@var{s}}. Border texture elements are |
21675 | accessed only if wrapping is set to @code{GL_CLAMP} or | |
21676 | @code{GL_CLAMP_TO_BORDER}. Initially, @code{GL_TEXTURE_WRAP_S} is set | |
21677 | to @code{GL_REPEAT}. | |
8925f36f AW |
21678 | |
21679 | @end table | |
21680 | ||
21681 | ||
21682 | ||
21683 | @table @asis | |
21684 | @item @code{GL_TEXTURE_WRAP_T} | |
3c9b6116 | 21685 | Sets the wrap parameter for texture coordinate @r{@var{t}} to either |
8925f36f | 21686 | @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE}, |
c7b31271 DH |
21687 | @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. See the discussion |
21688 | under @code{GL_TEXTURE_WRAP_S}. Initially, @code{GL_TEXTURE_WRAP_T} is | |
21689 | set to @code{GL_REPEAT}. | |
8925f36f AW |
21690 | |
21691 | @item @code{GL_TEXTURE_WRAP_R} | |
3c9b6116 | 21692 | Sets the wrap parameter for texture coordinate @r{@var{r}} to either |
8925f36f | 21693 | @code{GL_CLAMP}, @code{GL_CLAMP_TO_BORDER}, @code{GL_CLAMP_TO_EDGE}, |
c7b31271 DH |
21694 | @code{GL_MIRRORED_REPEAT}, or @code{GL_REPEAT}. See the discussion |
21695 | under @code{GL_TEXTURE_WRAP_S}. Initially, @code{GL_TEXTURE_WRAP_R} is | |
21696 | set to @code{GL_REPEAT}. | |
8925f36f AW |
21697 | |
21698 | @item @code{GL_TEXTURE_BORDER_COLOR} | |
c7b31271 DH |
21699 | Sets a border color. @var{params} contains four values that comprise |
21700 | the RGBA color of the texture border. Integer color components are | |
8925f36f | 21701 | interpreted linearly such that the most positive integer maps to 1.0, |
c7b31271 DH |
21702 | and the most negative integer maps to -1.0. The values are clamped to |
21703 | the range [0,1] when they are specified. Initially, the border color is | |
8925f36f AW |
21704 | (0, 0, 0, 0). |
21705 | ||
21706 | @item @code{GL_TEXTURE_PRIORITY} | |
21707 | Specifies the texture residence priority of the currently bound texture. | |
c7b31271 | 21708 | Permissible values are in the range @r{[0,1]}. See |
8925f36f AW |
21709 | @code{glPrioritizeTextures} and @code{glBindTexture} for more |
21710 | information. | |
21711 | ||
21712 | @item @code{GL_TEXTURE_COMPARE_MODE} | |
21713 | Specifies the texture comparison mode for currently bound depth | |
c7b31271 | 21714 | textures. That is, a texture whose internal format is |
8925f36f AW |
21715 | @code{GL_DEPTH_COMPONENT_*}; see @code{glTexImage2D}) Permissible values |
21716 | are: | |
21717 | ||
21718 | @item @code{GL_TEXTURE_COMPARE_FUNC} | |
21719 | Specifies the comparison operator used when | |
21720 | @code{GL_TEXTURE_COMPARE_MODE} is set to @code{GL_COMPARE_R_TO_TEXTURE}. | |
3c9b6116 AW |
21721 | Permissible values are: where @r{@var{r}} is the current interpolated |
21722 | texture coordinate, and @r{@var{D}_@var{t}} is the depth texture value | |
c7b31271 | 21723 | sampled from the currently bound depth texture. @r{@var{result}} is |
3c9b6116 AW |
21724 | assigned to the either the luminance, intensity, or alpha (as specified |
21725 | by @code{GL_DEPTH_TEXTURE_MODE}.) | |
8925f36f AW |
21726 | |
21727 | @item @code{GL_DEPTH_TEXTURE_MODE} | |
21728 | Specifies a single symbolic constant indicating how depth values should | |
c7b31271 DH |
21729 | be treated during filtering and texture application. Accepted values |
21730 | are @code{GL_LUMINANCE}, @code{GL_INTENSITY}, and @code{GL_ALPHA}. The | |
8925f36f AW |
21731 | initial value is @code{GL_LUMINANCE}. |
21732 | ||
21733 | @item @code{GL_GENERATE_MIPMAP} | |
21734 | Specifies a boolean value that indicates if all levels of a mipmap array | |
21735 | should be automatically updated when any modification to the base level | |
c7b31271 | 21736 | mipmap is done. The initial value is @code{GL_FALSE}. |
8925f36f AW |
21737 | |
21738 | @end table | |
21739 | ||
21740 | @table @asis | |
21741 | @item @code{GL_COMPARE_R_TO_TEXTURE} | |
3c9b6116 | 21742 | Specifies that the interpolated and clamped @r{@var{r}} texture |
8925f36f | 21743 | coordinate should be compared to the value in the currently bound depth |
c7b31271 DH |
21744 | texture. See the discussion of @code{GL_TEXTURE_COMPARE_FUNC} for |
21745 | details of how the comparison is evaluated. The result of the | |
21746 | comparison is assigned to luminance, intensity, or alpha (as specified | |
21747 | by @code{GL_DEPTH_TEXTURE_MODE}). | |
8925f36f AW |
21748 | |
21749 | @item @code{GL_NONE} | |
21750 | Specifies that the luminance, intensity, or alpha (as specified by | |
21751 | @code{GL_DEPTH_TEXTURE_MODE}) should be assigned the appropriate value | |
21752 | from the currently bound depth texture. | |
21753 | ||
21754 | @end table | |
21755 | ||
21756 | @table @asis | |
21757 | @item @strong{Texture Comparison Function} | |
21758 | @strong{Computed result} | |
21759 | ||
21760 | @item @code{GL_LEQUAL} | |
3c9b6116 | 21761 | @r{@var{result}=@{(1.0), (0.0) (@var{r}<=@var{D}_@var{t},), |
8925f36f AW |
21762 | (@var{r}>@var{D}_@var{t},),} |
21763 | ||
21764 | @item @code{GL_GEQUAL} | |
3c9b6116 | 21765 | @r{@var{result}=@{(1.0), (0.0) (@var{r}>=@var{D}_@var{t},), |
8925f36f AW |
21766 | (@var{r}<@var{D}_@var{t},),} |
21767 | ||
21768 | @item @code{GL_LESS} | |
3c9b6116 | 21769 | @r{@var{result}=@{(1.0), (0.0) (@var{r}<@var{D}_@var{t},), |
8925f36f AW |
21770 | (@var{r}>=@var{D}_@var{t},),} |
21771 | ||
21772 | @item @code{GL_GREATER} | |
3c9b6116 | 21773 | @r{@var{result}=@{(1.0), (0.0) (@var{r}>@var{D}_@var{t},), |
8925f36f AW |
21774 | (@var{r}<=@var{D}_@var{t},),} |
21775 | ||
21776 | @item @code{GL_EQUAL} | |
3c9b6116 | 21777 | @r{@var{result}=@{(1.0), (0.0) (@var{r}=@var{D}_@var{t},), |
8925f36f AW |
21778 | (@var{r}≠@var{D}_@var{t},),} |
21779 | ||
21780 | @item @code{GL_NOTEQUAL} | |
3c9b6116 | 21781 | @r{@var{result}=@{(1.0), (0.0) (@var{r}≠@var{D}_@var{t},), |
8925f36f AW |
21782 | (@var{r}=@var{D}_@var{t},),} |
21783 | ||
21784 | @item @code{GL_ALWAYS} | |
3c9b6116 | 21785 | @r{@var{result}=@code{1.0}} |
8925f36f AW |
21786 | |
21787 | @item @code{GL_NEVER} | |
3c9b6116 | 21788 | @r{@var{result}=@code{0.0}} |
8925f36f AW |
21789 | |
21790 | @end table | |
21791 | ||
8925f36f AW |
21792 | @code{GL_INVALID_ENUM} is generated if @var{target} or @var{pname} is |
21793 | not one of the accepted defined values. | |
21794 | ||
21795 | @code{GL_INVALID_ENUM} is generated if @var{params} should have a | |
21796 | defined constant value (based on the value of @var{pname}) and does not. | |
21797 | ||
21798 | @code{GL_INVALID_OPERATION} is generated if @code{glTexParameter} is | |
21799 | executed between the execution of @code{glBegin} and the corresponding | |
21800 | execution of @code{glEnd}. | |
21801 | ||
bb894c9d | 21802 | @end deftypefun |
8925f36f | 21803 | |
bb894c9d | 21804 | @deftypefun void glTexSubImage1D target level xoffset width format type data |
3c9b6116 AW |
21805 | Specify a one-dimensional texture subimage. |
21806 | ||
8925f36f AW |
21807 | @table @asis |
21808 | @item @var{target} | |
c7b31271 | 21809 | Specifies the target texture. Must be @code{GL_TEXTURE_1D}. |
8925f36f AW |
21810 | |
21811 | @item @var{level} | |
c7b31271 | 21812 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
21813 | Level @var{n} is the @var{n}th mipmap reduction image. |
21814 | ||
21815 | @item @var{xoffset} | |
21816 | Specifies a texel offset in the x direction within the texture array. | |
21817 | ||
21818 | @item @var{width} | |
21819 | Specifies the width of the texture subimage. | |
21820 | ||
21821 | @item @var{format} | |
c7b31271 | 21822 | Specifies the format of the pixel data. The following symbolic values |
8925f36f AW |
21823 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, |
21824 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
21825 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
21826 | @code{GL_LUMINANCE_ALPHA}. | |
21827 | ||
21828 | @item @var{type} | |
c7b31271 DH |
21829 | Specifies the data type of the pixel data. The following symbolic |
21830 | values are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, | |
21831 | @code{GL_BITMAP}, @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, | |
21832 | @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT}, | |
21833 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
21834 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
21835 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
21836 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
21837 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
21838 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
21839 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
8925f36f AW |
21840 | |
21841 | @item @var{data} | |
21842 | Specifies a pointer to the image data in memory. | |
21843 | ||
21844 | @end table | |
21845 | ||
8925f36f | 21846 | Texturing maps a portion of a specified texture image onto each |
c7b31271 DH |
21847 | graphical primitive for which texturing is enabled. To enable or |
21848 | disable one-dimensional texturing, call @code{glEnable} and | |
21849 | @code{glDisable} with argument @code{GL_TEXTURE_1D}. | |
8925f36f AW |
21850 | |
21851 | @code{glTexSubImage1D} redefines a contiguous subregion of an existing | |
c7b31271 | 21852 | one-dimensional texture image. The texels referenced by @var{data} |
8925f36f | 21853 | replace the portion of the existing texture array with x indices |
c7b31271 | 21854 | @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive. This |
8925f36f | 21855 | region may not include any texels outside the range of the texture array |
c7b31271 | 21856 | as it was originally specified. It is not an error to specify a |
8925f36f AW |
21857 | subtexture with width of 0, but such a specification has no effect. |
21858 | ||
21859 | If a non-zero named buffer object is bound to the | |
21860 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
21861 | texture image is specified, @var{data} is treated as a byte offset into | |
21862 | the buffer object's data store. | |
21863 | ||
8925f36f AW |
21864 | @code{GL_INVALID_ENUM} is generated if @var{target} is not one of the |
21865 | allowable values. | |
21866 | ||
21867 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
21868 | format constant. | |
21869 | ||
21870 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
21871 | constant. | |
21872 | ||
21873 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
21874 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
21875 | ||
21876 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
21877 | ||
21878 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 | 21879 | @r{@var{log}_2}@var{max}, where @var{max} is the returned value of |
8925f36f AW |
21880 | @code{GL_MAX_TEXTURE_SIZE}. |
21881 | ||
3c9b6116 AW |
21882 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, or |
21883 | if @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, where | |
21884 | @r{@var{w}} is the @code{GL_TEXTURE_WIDTH}, and @r{@var{b}} is the width | |
21885 | of the @code{GL_TEXTURE_BORDER} of the texture image being modified. | |
21886 | Note that @r{@var{w}} includes twice the border width. | |
8925f36f AW |
21887 | |
21888 | @code{GL_INVALID_VALUE} is generated if @var{width} is less than 0. | |
21889 | ||
21890 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
21891 | been defined by a previous @code{glTexImage1D} operation. | |
21892 | ||
21893 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21894 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
21895 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
21896 | and @var{format} is not @code{GL_RGB}. | |
21897 | ||
21898 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
21899 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
21900 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
21901 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
21902 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
21903 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
21904 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
21905 | ||
21906 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21907 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
21908 | object's data store is currently mapped. | |
21909 | ||
21910 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21911 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
21912 | would be unpacked from the buffer object such that the memory reads | |
21913 | required would exceed the data store size. | |
21914 | ||
21915 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
21916 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
21917 | is not evenly divisible into the number of bytes needed to store in | |
21918 | memory a datum indicated by @var{type}. | |
21919 | ||
21920 | @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage1D} is | |
21921 | executed between the execution of @code{glBegin} and the corresponding | |
21922 | execution of @code{glEnd}. | |
21923 | ||
bb894c9d | 21924 | @end deftypefun |
8925f36f | 21925 | |
bb894c9d | 21926 | @deftypefun void glTexSubImage2D target level xoffset yoffset width height format type data |
3c9b6116 AW |
21927 | Specify a two-dimensional texture subimage. |
21928 | ||
8925f36f AW |
21929 | @table @asis |
21930 | @item @var{target} | |
c7b31271 | 21931 | Specifies the target texture. Must be @code{GL_TEXTURE_2D}, |
8925f36f AW |
21932 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, |
21933 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
21934 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
21935 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
21936 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
21937 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
21938 | ||
21939 | @item @var{level} | |
c7b31271 | 21940 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
21941 | Level @var{n} is the @var{n}th mipmap reduction image. |
21942 | ||
21943 | @item @var{xoffset} | |
21944 | Specifies a texel offset in the x direction within the texture array. | |
21945 | ||
21946 | @item @var{yoffset} | |
21947 | Specifies a texel offset in the y direction within the texture array. | |
21948 | ||
21949 | @item @var{width} | |
21950 | Specifies the width of the texture subimage. | |
21951 | ||
21952 | @item @var{height} | |
21953 | Specifies the height of the texture subimage. | |
21954 | ||
21955 | @item @var{format} | |
c7b31271 | 21956 | Specifies the format of the pixel data. The following symbolic values |
8925f36f AW |
21957 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, |
21958 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
21959 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
21960 | @code{GL_LUMINANCE_ALPHA}. | |
21961 | ||
21962 | @item @var{type} | |
c7b31271 DH |
21963 | Specifies the data type of the pixel data. The following symbolic |
21964 | values are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, | |
21965 | @code{GL_BITMAP}, @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, | |
21966 | @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT}, | |
21967 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
21968 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
21969 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
21970 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
21971 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
21972 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
21973 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
8925f36f AW |
21974 | |
21975 | @item @var{data} | |
21976 | Specifies a pointer to the image data in memory. | |
21977 | ||
21978 | @end table | |
21979 | ||
8925f36f | 21980 | Texturing maps a portion of a specified texture image onto each |
c7b31271 | 21981 | graphical primitive for which texturing is enabled. To enable and |
8925f36f AW |
21982 | disable two-dimensional texturing, call @code{glEnable} and |
21983 | @code{glDisable} with argument @code{GL_TEXTURE_2D}. | |
21984 | ||
21985 | @code{glTexSubImage2D} redefines a contiguous subregion of an existing | |
c7b31271 | 21986 | two-dimensional texture image. The texels referenced by @var{data} |
8925f36f | 21987 | replace the portion of the existing texture array with x indices |
3c9b6116 AW |
21988 | @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive, and y |
21989 | indices @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive. | |
21990 | This region may not include any texels outside the range of the texture | |
c7b31271 | 21991 | array as it was originally specified. It is not an error to specify a |
3c9b6116 AW |
21992 | subtexture with zero width or height, but such a specification has no |
21993 | effect. | |
8925f36f AW |
21994 | |
21995 | If a non-zero named buffer object is bound to the | |
21996 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
21997 | texture image is specified, @var{data} is treated as a byte offset into | |
21998 | the buffer object's data store. | |
21999 | ||
8925f36f AW |
22000 | @code{GL_INVALID_ENUM} is generated if @var{target} is not |
22001 | @code{GL_TEXTURE_2D}, @code{GL_TEXTURE_CUBE_MAP_POSITIVE_X}, | |
22002 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_X}, | |
22003 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Y}, | |
22004 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Y}, | |
22005 | @code{GL_TEXTURE_CUBE_MAP_POSITIVE_Z}, or | |
22006 | @code{GL_TEXTURE_CUBE_MAP_NEGATIVE_Z}. | |
22007 | ||
22008 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
22009 | format constant. | |
22010 | ||
22011 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
22012 | constant. | |
22013 | ||
22014 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
22015 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
22016 | ||
22017 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
22018 | ||
22019 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 | 22020 | @r{@var{log}_2}@var{max}, where @var{max} is the returned value of |
8925f36f AW |
22021 | @code{GL_MAX_TEXTURE_SIZE}. |
22022 | ||
3c9b6116 AW |
22023 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, |
22024 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, | |
22025 | @r{@var{yoffset}<-@var{b}}, or | |
22026 | @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, where @r{@var{w}} | |
22027 | is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the | |
22028 | @code{GL_TEXTURE_HEIGHT}, and @r{@var{b}} is the border width of the | |
c7b31271 | 22029 | texture image being modified. Note that @r{@var{w}} and @r{@var{h}} |
3c9b6116 | 22030 | include twice the border width. |
8925f36f AW |
22031 | |
22032 | @code{GL_INVALID_VALUE} is generated if @var{width} or @var{height} is | |
22033 | less than 0. | |
22034 | ||
22035 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
22036 | been defined by a previous @code{glTexImage2D} operation. | |
22037 | ||
22038 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
22039 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
22040 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
22041 | and @var{format} is not @code{GL_RGB}. | |
22042 | ||
22043 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
22044 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
22045 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
22046 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
22047 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
22048 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
22049 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
22050 | ||
22051 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
22052 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
22053 | object's data store is currently mapped. | |
22054 | ||
22055 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
22056 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
22057 | would be unpacked from the buffer object such that the memory reads | |
22058 | required would exceed the data store size. | |
22059 | ||
22060 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
22061 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
22062 | is not evenly divisible into the number of bytes needed to store in | |
22063 | memory a datum indicated by @var{type}. | |
22064 | ||
22065 | @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage2D} is | |
22066 | executed between the execution of @code{glBegin} and the corresponding | |
22067 | execution of @code{glEnd}. | |
22068 | ||
bb894c9d | 22069 | @end deftypefun |
8925f36f | 22070 | |
bb894c9d | 22071 | @deftypefun void glTexSubImage3D target level xoffset yoffset zoffset width height depth format type data |
3c9b6116 AW |
22072 | Specify a three-dimensional texture subimage. |
22073 | ||
8925f36f AW |
22074 | @table @asis |
22075 | @item @var{target} | |
c7b31271 | 22076 | Specifies the target texture. Must be @code{GL_TEXTURE_3D}. |
8925f36f AW |
22077 | |
22078 | @item @var{level} | |
c7b31271 | 22079 | Specifies the level-of-detail number. Level 0 is the base image level. |
8925f36f AW |
22080 | Level @var{n} is the @var{n}th mipmap reduction image. |
22081 | ||
22082 | @item @var{xoffset} | |
22083 | Specifies a texel offset in the x direction within the texture array. | |
22084 | ||
22085 | @item @var{yoffset} | |
22086 | Specifies a texel offset in the y direction within the texture array. | |
22087 | ||
22088 | @item @var{zoffset} | |
22089 | Specifies a texel offset in the z direction within the texture array. | |
22090 | ||
22091 | @item @var{width} | |
22092 | Specifies the width of the texture subimage. | |
22093 | ||
22094 | @item @var{height} | |
22095 | Specifies the height of the texture subimage. | |
22096 | ||
22097 | @item @var{depth} | |
22098 | Specifies the depth of the texture subimage. | |
22099 | ||
22100 | @item @var{format} | |
c7b31271 | 22101 | Specifies the format of the pixel data. The following symbolic values |
8925f36f AW |
22102 | are accepted: @code{GL_COLOR_INDEX}, @code{GL_RED}, @code{GL_GREEN}, |
22103 | @code{GL_BLUE}, @code{GL_ALPHA}, @code{GL_RGB}, @code{GL_BGR}, | |
22104 | @code{GL_RGBA}, @code{GL_BGRA}, @code{GL_LUMINANCE}, and | |
22105 | @code{GL_LUMINANCE_ALPHA}. | |
22106 | ||
22107 | @item @var{type} | |
c7b31271 DH |
22108 | Specifies the data type of the pixel data. The following symbolic |
22109 | values are accepted: @code{GL_UNSIGNED_BYTE}, @code{GL_BYTE}, | |
22110 | @code{GL_BITMAP}, @code{GL_UNSIGNED_SHORT}, @code{GL_SHORT}, | |
22111 | @code{GL_UNSIGNED_INT}, @code{GL_INT}, @code{GL_FLOAT}, | |
22112 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
22113 | @code{GL_UNSIGNED_SHORT_5_6_5}, @code{GL_UNSIGNED_SHORT_5_6_5_REV}, | |
22114 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
22115 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
22116 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
22117 | @code{GL_UNSIGNED_INT_10_10_10_2}, and | |
22118 | @code{GL_UNSIGNED_INT_2_10_10_10_REV}. | |
8925f36f AW |
22119 | |
22120 | @item @var{data} | |
22121 | Specifies a pointer to the image data in memory. | |
22122 | ||
22123 | @end table | |
22124 | ||
8925f36f | 22125 | Texturing maps a portion of a specified texture image onto each |
c7b31271 | 22126 | graphical primitive for which texturing is enabled. To enable and |
8925f36f AW |
22127 | disable three-dimensional texturing, call @code{glEnable} and |
22128 | @code{glDisable} with argument @code{GL_TEXTURE_3D}. | |
22129 | ||
22130 | @code{glTexSubImage3D} redefines a contiguous subregion of an existing | |
c7b31271 | 22131 | three-dimensional texture image. The texels referenced by @var{data} |
8925f36f | 22132 | replace the portion of the existing texture array with x indices |
3c9b6116 AW |
22133 | @var{xoffset} and @r{@var{xoffset}+@var{width}-1}, inclusive, y indices |
22134 | @var{yoffset} and @r{@var{yoffset}+@var{height}-1}, inclusive, and z | |
22135 | indices @var{zoffset} and @r{@var{zoffset}+@var{depth}-1}, inclusive. | |
22136 | This region may not include any texels outside the range of the texture | |
c7b31271 | 22137 | array as it was originally specified. It is not an error to specify a |
3c9b6116 AW |
22138 | subtexture with zero width, height, or depth but such a specification |
22139 | has no effect. | |
8925f36f AW |
22140 | |
22141 | If a non-zero named buffer object is bound to the | |
22142 | @code{GL_PIXEL_UNPACK_BUFFER} target (see @code{glBindBuffer}) while a | |
22143 | texture image is specified, @var{data} is treated as a byte offset into | |
22144 | the buffer object's data store. | |
22145 | ||
8925f36f AW |
22146 | @code{GL_INVALID_ENUM} is generated if /@var{target} is not |
22147 | @code{GL_TEXTURE_3D}. | |
22148 | ||
22149 | @code{GL_INVALID_ENUM} is generated if @var{format} is not an accepted | |
22150 | format constant. | |
22151 | ||
22152 | @code{GL_INVALID_ENUM} is generated if @var{type} is not a type | |
22153 | constant. | |
22154 | ||
22155 | @code{GL_INVALID_ENUM} is generated if @var{type} is @code{GL_BITMAP} | |
22156 | and @var{format} is not @code{GL_COLOR_INDEX}. | |
22157 | ||
22158 | @code{GL_INVALID_VALUE} is generated if @var{level} is less than 0. | |
22159 | ||
22160 | @code{GL_INVALID_VALUE} may be generated if @var{level} is greater than | |
3c9b6116 | 22161 | @r{@var{log}_2}@var{max}, where @var{max} is the returned value of |
8925f36f AW |
22162 | @code{GL_MAX_TEXTURE_SIZE}. |
22163 | ||
3c9b6116 AW |
22164 | @code{GL_INVALID_VALUE} is generated if @r{@var{xoffset}<-@var{b}}, |
22165 | @r{(@var{xoffset}+@var{width},)>(@var{w}-@var{b},)}, | |
22166 | @r{@var{yoffset}<-@var{b}}, or | |
22167 | @r{(@var{yoffset}+@var{height},)>(@var{h}-@var{b},)}, or | |
22168 | @r{@var{zoffset}<-@var{b}}, or | |
22169 | @r{(@var{zoffset}+@var{depth},)>(@var{d}-@var{b},)}, where @r{@var{w}} | |
22170 | is the @code{GL_TEXTURE_WIDTH}, @r{@var{h}} is the | |
22171 | @code{GL_TEXTURE_HEIGHT}, @r{@var{d}} is the @code{GL_TEXTURE_DEPTH} and | |
22172 | @r{@var{b}} is the border width of the texture image being modified. | |
22173 | Note that @r{@var{w}}, @r{@var{h}}, and @r{@var{d}} include twice the | |
22174 | border width. | |
8925f36f AW |
22175 | |
22176 | @code{GL_INVALID_VALUE} is generated if @var{width}, @var{height}, or | |
22177 | @var{depth} is less than 0. | |
22178 | ||
22179 | @code{GL_INVALID_OPERATION} is generated if the texture array has not | |
22180 | been defined by a previous @code{glTexImage3D} operation. | |
22181 | ||
22182 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
22183 | @code{GL_UNSIGNED_BYTE_3_3_2}, @code{GL_UNSIGNED_BYTE_2_3_3_REV}, | |
22184 | @code{GL_UNSIGNED_SHORT_5_6_5}, or @code{GL_UNSIGNED_SHORT_5_6_5_REV} | |
22185 | and @var{format} is not @code{GL_RGB}. | |
22186 | ||
22187 | @code{GL_INVALID_OPERATION} is generated if @var{type} is one of | |
22188 | @code{GL_UNSIGNED_SHORT_4_4_4_4}, @code{GL_UNSIGNED_SHORT_4_4_4_4_REV}, | |
22189 | @code{GL_UNSIGNED_SHORT_5_5_5_1}, @code{GL_UNSIGNED_SHORT_1_5_5_5_REV}, | |
22190 | @code{GL_UNSIGNED_INT_8_8_8_8}, @code{GL_UNSIGNED_INT_8_8_8_8_REV}, | |
22191 | @code{GL_UNSIGNED_INT_10_10_10_2}, or | |
22192 | @code{GL_UNSIGNED_INT_2_10_10_10_REV} and @var{format} is neither | |
22193 | @code{GL_RGBA} nor @code{GL_BGRA}. | |
22194 | ||
22195 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
22196 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the buffer | |
22197 | object's data store is currently mapped. | |
22198 | ||
22199 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
22200 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and the data | |
22201 | would be unpacked from the buffer object such that the memory reads | |
22202 | required would exceed the data store size. | |
22203 | ||
22204 | @code{GL_INVALID_OPERATION} is generated if a non-zero buffer object | |
22205 | name is bound to the @code{GL_PIXEL_UNPACK_BUFFER} target and @var{data} | |
22206 | is not evenly divisible into the number of bytes needed to store in | |
22207 | memory a datum indicated by @var{type}. | |
22208 | ||
22209 | @code{GL_INVALID_OPERATION} is generated if @code{glTexSubImage3D} is | |
22210 | executed between the execution of @code{glBegin} and the corresponding | |
22211 | execution of @code{glEnd}. | |
22212 | ||
bb894c9d | 22213 | @end deftypefun |
8925f36f | 22214 | |
d172eed9 AW |
22215 | @deftypefun void glTranslated x y z |
22216 | @deftypefunx void glTranslatef x y z | |
3c9b6116 AW |
22217 | Multiply the current matrix by a translation matrix. |
22218 | ||
8925f36f AW |
22219 | @table @asis |
22220 | @item @var{x} | |
22221 | @itemx @var{y} | |
22222 | @itemx @var{z} | |
22223 | Specify the @var{x}, @var{y}, and @var{z} coordinates of a translation | |
22224 | vector. | |
22225 | ||
22226 | @end table | |
22227 | ||
8925f36f | 22228 | @code{glTranslate} produces a translation by |
c7b31271 | 22229 | @r{(@var{x},@var{y}@var{z})}. The current matrix (see |
8925f36f AW |
22230 | @code{glMatrixMode}) is multiplied by this translation matrix, with the |
22231 | product replacing the current matrix, as if @code{glMultMatrix} were | |
22232 | called with the following matrix for its argument: | |
22233 | ||
3c9b6116 | 22234 | @r{((1 0 0 @var{x}), (0 1 0 @var{y}), (0 0 1 @var{z}), (0 0 0 1),)} |
8925f36f AW |
22235 | |
22236 | ||
22237 | ||
22238 | If the matrix mode is either @code{GL_MODELVIEW} or | |
22239 | @code{GL_PROJECTION}, all objects drawn after a call to | |
22240 | @code{glTranslate} are translated. | |
22241 | ||
22242 | Use @code{glPushMatrix} and @code{glPopMatrix} to save and restore the | |
22243 | untranslated coordinate system. | |
22244 | ||
8925f36f AW |
22245 | @code{GL_INVALID_OPERATION} is generated if @code{glTranslate} is |
22246 | executed between the execution of @code{glBegin} and the corresponding | |
22247 | execution of @code{glEnd}. | |
22248 | ||
bb894c9d | 22249 | @end deftypefun |
8925f36f | 22250 | |
bb894c9d AW |
22251 | @deftypefun void glUniform1f location v0 |
22252 | @deftypefunx void glUniform2f location v0 v1 | |
22253 | @deftypefunx void glUniform3f location v0 v1 v2 | |
22254 | @deftypefunx void glUniform4f location v0 v1 v2 v3 | |
22255 | @deftypefunx void glUniform1i location v0 | |
22256 | @deftypefunx void glUniform2i location v0 v1 | |
22257 | @deftypefunx void glUniform3i location v0 v1 v2 | |
22258 | @deftypefunx void glUniform4i location v0 v1 v2 v3 | |
d172eed9 AW |
22259 | @deftypefunx void glUniform1fv location count value |
22260 | @deftypefunx void glUniform2fv location count value | |
22261 | @deftypefunx void glUniform3fv location count value | |
22262 | @deftypefunx void glUniform4fv location count value | |
22263 | @deftypefunx void glUniform1iv location count value | |
22264 | @deftypefunx void glUniform2iv location count value | |
22265 | @deftypefunx void glUniform3iv location count value | |
22266 | @deftypefunx void glUniform4iv location count value | |
b002944d AW |
22267 | @deftypefunx void glUniformMatrix2fv location count transpose value |
22268 | @deftypefunx void glUniformMatrix3fv location count transpose value | |
22269 | @deftypefunx void glUniformMatrix4fv location count transpose value | |
22270 | @deftypefunx void glUniformMatrix2x3fv location count transpose value | |
22271 | @deftypefunx void glUniformMatrix3x2fv location count transpose value | |
22272 | @deftypefunx void glUniformMatrix2x4fv location count transpose value | |
22273 | @deftypefunx void glUniformMatrix4x2fv location count transpose value | |
22274 | @deftypefunx void glUniformMatrix3x4fv location count transpose value | |
22275 | @deftypefunx void glUniformMatrix4x3fv location count transpose value | |
3c9b6116 AW |
22276 | Specify the value of a uniform variable for the current program object. |
22277 | ||
8925f36f AW |
22278 | @table @asis |
22279 | @item @var{location} | |
22280 | Specifies the location of the uniform variable to be modified. | |
22281 | ||
22282 | @item @var{v0}, @var{v1}, @var{v2}, @var{v3} | |
22283 | Specifies the new values to be used for the specified uniform variable. | |
22284 | ||
22285 | @end table | |
22286 | ||
8925f36f | 22287 | @code{glUniform} modifies the value of a uniform variable or a uniform |
c7b31271 | 22288 | variable array. The location of the uniform variable to be modified is |
8925f36f | 22289 | specified by @var{location}, which should be a value returned by |
c7b31271 | 22290 | @code{glGetUniformLocation}. @code{glUniform} operates on the program |
8925f36f AW |
22291 | object that was made part of current state by calling |
22292 | @code{glUseProgram}. | |
22293 | ||
22294 | The commands @code{glUniform@{1|2|3|4@}@{f|i@}} are used to change the | |
22295 | value of the uniform variable specified by @var{location} using the | |
c7b31271 | 22296 | values passed as arguments. The number specified in the command should |
8925f36f AW |
22297 | match the number of components in the data type of the specified uniform |
22298 | variable (e.g., @code{1} for float, int, bool; @code{2} for vec2, ivec2, | |
c7b31271 | 22299 | bvec2, etc.). The suffix @code{f} indicates that floating-point values |
8925f36f AW |
22300 | are being passed; the suffix @code{i} indicates that integer values are |
22301 | being passed, and this type should also match the data type of the | |
c7b31271 | 22302 | specified uniform variable. The @code{i} variants of this function |
8925f36f | 22303 | should be used to provide values for uniform variables defined as int, |
c7b31271 DH |
22304 | ivec2, ivec3, ivec4, or arrays of these. The @code{f} variants should |
22305 | be used to provide values for uniform variables of type float, vec2, | |
22306 | vec3, vec4, or arrays of these. Either the @code{i} or the @code{f} | |
22307 | variants may be used to provide values for uniform variables of type | |
22308 | bool, bvec2, bvec3, bvec4, or arrays of these. The uniform variable | |
22309 | will be set to false if the input value is 0 or 0.0f, and it will be set | |
22310 | to true otherwise. | |
8925f36f AW |
22311 | |
22312 | All active uniform variables defined in a program object are initialized | |
c7b31271 | 22313 | to 0 when the program object is linked successfully. They retain the |
8925f36f AW |
22314 | values assigned to them by a call to @code{glUniform } until the next |
22315 | successful link operation occurs on the program object, when they are | |
22316 | once again initialized to 0. | |
22317 | ||
22318 | The commands @code{glUniform@{1|2|3|4@}@{f|i@}v} can be used to modify a | |
c7b31271 DH |
22319 | single uniform variable or a uniform variable array. These commands |
22320 | pass a count and a pointer to the values to be loaded into a uniform | |
22321 | variable or a uniform variable array. A count of 1 should be used if | |
22322 | modifying the value of a single uniform variable, and a count of 1 or | |
22323 | greater can be used to modify an entire array or part of an array. When | |
22324 | loading @var{n} elements starting at an arbitrary position @var{m} in a | |
22325 | uniform variable array, elements @var{m} + @var{n} - 1 in the array will | |
22326 | be replaced with the new values. If @var{m} + @var{n} - 1 is larger | |
22327 | than the size of the uniform variable array, values for all array | |
22328 | elements beyond the end of the array will be ignored. The number | |
22329 | specified in the name of the command indicates the number of components | |
22330 | for each element in @var{value}, and it should match the number of | |
22331 | components in the data type of the specified uniform variable (e.g., | |
22332 | @code{1} for float, int, bool; @code{2} for vec2, ivec2, bvec2, etc.). | |
22333 | The data type specified in the name of the command must match the data | |
22334 | type for the specified uniform variable as described previously for | |
8925f36f AW |
22335 | @code{glUniform@{1|2|3|4@}@{f|i@}}. |
22336 | ||
22337 | For uniform variable arrays, each element of the array is considered to | |
22338 | be of the type indicated in the name of the command (e.g., | |
22339 | @code{glUniform3f} or @code{glUniform3fv} can be used to load a uniform | |
c7b31271 | 22340 | variable array of type vec3). The number of elements of the uniform |
8925f36f AW |
22341 | variable array to be modified is specified by @var{count} |
22342 | ||
22343 | The commands @code{glUniformMatrix@{2|3|4|2x3|3x2|2x4|4x2|3x4|4x3@}fv} | |
c7b31271 DH |
22344 | are used to modify a matrix or an array of matrices. The numbers in the |
22345 | command name are interpreted as the dimensionality of the matrix. The | |
8925f36f AW |
22346 | number @code{2} indicates a 2 × 2 matrix (i.e., 4 values), the number |
22347 | @code{3} indicates a 3 × 3 matrix (i.e., 9 values), and the number | |
c7b31271 | 22348 | @code{4} indicates a 4 × 4 matrix (i.e., 16 values). Non-square matrix |
8925f36f AW |
22349 | dimensionality is explicit, with the first number representing the |
22350 | number of columns and the second number representing the number of rows. | |
22351 | For example, @code{2x4} indicates a 2 × 4 matrix with 2 columns and 4 | |
c7b31271 DH |
22352 | rows (i.e., 8 values). If @var{transpose} is @code{GL_FALSE}, each |
22353 | matrix is assumed to be supplied in column major order. If | |
8925f36f | 22354 | @var{transpose} is @code{GL_TRUE}, each matrix is assumed to be supplied |
c7b31271 DH |
22355 | in row major order. The @var{count} argument indicates the number of |
22356 | matrices to be passed. A count of 1 should be used if modifying the | |
8925f36f AW |
22357 | value of a single matrix, and a count greater than 1 can be used to |
22358 | modify an array of matrices. | |
22359 | ||
8925f36f AW |
22360 | @code{GL_INVALID_OPERATION} is generated if there is no current program |
22361 | object. | |
22362 | ||
22363 | @code{GL_INVALID_OPERATION} is generated if the size of the uniform | |
22364 | variable declared in the shader does not match the size indicated by the | |
22365 | @code{glUniform} command. | |
22366 | ||
22367 | @code{GL_INVALID_OPERATION} is generated if one of the integer variants | |
22368 | of this function is used to load a uniform variable of type float, vec2, | |
22369 | vec3, vec4, or an array of these, or if one of the floating-point | |
22370 | variants of this function is used to load a uniform variable of type | |
22371 | int, ivec2, ivec3, or ivec4, or an array of these. | |
22372 | ||
22373 | @code{GL_INVALID_OPERATION} is generated if @var{location} is an invalid | |
22374 | uniform location for the current program object and @var{location} is | |
22375 | not equal to -1. | |
22376 | ||
22377 | @code{GL_INVALID_VALUE} is generated if @var{count} is less than 0. | |
22378 | ||
22379 | @code{GL_INVALID_OPERATION} is generated if @var{count} is greater than | |
22380 | 1 and the indicated uniform variable is not an array variable. | |
22381 | ||
22382 | @code{GL_INVALID_OPERATION} is generated if a sampler is loaded using a | |
22383 | command other than @code{glUniform1i} and @code{glUniform1iv}. | |
22384 | ||
22385 | @code{GL_INVALID_OPERATION} is generated if @code{glUniform} is executed | |
22386 | between the execution of @code{glBegin} and the corresponding execution | |
22387 | of @code{glEnd}. | |
22388 | ||
bb894c9d | 22389 | @end deftypefun |
8925f36f | 22390 | |
bb894c9d | 22391 | @deftypefun void glUseProgram program |
3c9b6116 AW |
22392 | Installs a program object as part of current rendering state. |
22393 | ||
8925f36f AW |
22394 | @table @asis |
22395 | @item @var{program} | |
22396 | Specifies the handle of the program object whose executables are to be | |
22397 | used as part of current rendering state. | |
22398 | ||
22399 | @end table | |
22400 | ||
8925f36f | 22401 | @code{glUseProgram} installs the program object specified by |
c7b31271 | 22402 | @var{program} as part of current rendering state. One or more |
8925f36f AW |
22403 | executables are created in a program object by successfully attaching |
22404 | shader objects to it with @code{glAttachShader}, successfully compiling | |
22405 | the shader objects with @code{glCompileShader}, and successfully linking | |
22406 | the program object with @code{glLinkProgram}. | |
22407 | ||
22408 | A program object will contain an executable that will run on the vertex | |
22409 | processor if it contains one or more shader objects of type | |
22410 | @code{GL_VERTEX_SHADER} that have been successfully compiled and linked. | |
22411 | Similarly, a program object will contain an executable that will run on | |
22412 | the fragment processor if it contains one or more shader objects of type | |
22413 | @code{GL_FRAGMENT_SHADER} that have been successfully compiled and | |
22414 | linked. | |
22415 | ||
22416 | Successfully installing an executable on a programmable processor will | |
22417 | cause the corresponding fixed functionality of OpenGL to be disabled. | |
22418 | Specifically, if an executable is installed on the vertex processor, the | |
22419 | OpenGL fixed functionality will be disabled as follows. | |
22420 | ||
22421 | @itemize | |
22422 | @item | |
22423 | The modelview matrix is not applied to vertex coordinates. | |
22424 | ||
22425 | @item | |
22426 | The projection matrix is not applied to vertex coordinates. | |
22427 | ||
22428 | @item | |
22429 | The texture matrices are not applied to texture coordinates. | |
22430 | ||
22431 | @item | |
22432 | Normals are not transformed to eye coordinates. | |
22433 | ||
22434 | @item | |
22435 | Normals are not rescaled or normalized. | |
22436 | ||
22437 | @item | |
22438 | Normalization of @code{GL_AUTO_NORMAL} evaluated normals is not | |
22439 | performed. | |
22440 | ||
22441 | @item | |
22442 | Texture coordinates are not generated automatically. | |
22443 | ||
22444 | @item | |
22445 | Per-vertex lighting is not performed. | |
22446 | ||
22447 | @item | |
22448 | Color material computations are not performed. | |
22449 | ||
22450 | @item | |
22451 | Color index lighting is not performed. | |
22452 | ||
22453 | @item | |
22454 | This list also applies when setting the current raster position. | |
22455 | ||
22456 | @end itemize | |
22457 | ||
22458 | The executable that is installed on the vertex processor is expected to | |
22459 | implement any or all of the desired functionality from the preceding | |
c7b31271 | 22460 | list. Similarly, if an executable is installed on the fragment |
8925f36f AW |
22461 | processor, the OpenGL fixed functionality will be disabled as follows. |
22462 | ||
22463 | @itemize | |
22464 | @item | |
22465 | Texture environment and texture functions are not applied. | |
22466 | ||
22467 | @item | |
22468 | Texture application is not applied. | |
22469 | ||
22470 | @item | |
22471 | Color sum is not applied. | |
22472 | ||
22473 | @item | |
22474 | Fog is not applied. | |
22475 | ||
22476 | @end itemize | |
22477 | ||
22478 | Again, the fragment shader that is installed is expected to implement | |
22479 | any or all of the desired functionality from the preceding list. | |
22480 | ||
22481 | While a program object is in use, applications are free to modify | |
22482 | attached shader objects, compile attached shader objects, attach | |
c7b31271 | 22483 | additional shader objects, and detach or delete shader objects. None of |
8925f36f | 22484 | these operations will affect the executables that are part of the |
c7b31271 | 22485 | current state. However, relinking the program object that is currently |
8925f36f AW |
22486 | in use will install the program object as part of the current rendering |
22487 | state if the link operation was successful (see @code{glLinkProgram} ). | |
22488 | If the program object currently in use is relinked unsuccessfully, its | |
22489 | link status will be set to @code{GL_FALSE}, but the executables and | |
22490 | associated state will remain part of the current state until a | |
c7b31271 | 22491 | subsequent call to @code{glUseProgram} removes it from use. After it is |
8925f36f AW |
22492 | removed from use, it cannot be made part of current state until it has |
22493 | been successfully relinked. | |
22494 | ||
22495 | If @var{program} contains shader objects of type @code{GL_VERTEX_SHADER} | |
22496 | but it does not contain shader objects of type | |
22497 | @code{GL_FRAGMENT_SHADER}, an executable will be installed on the vertex | |
22498 | processor, but fixed functionality will be used for fragment processing. | |
22499 | Similarly, if @var{program} contains shader objects of type | |
22500 | @code{GL_FRAGMENT_SHADER} but it does not contain shader objects of type | |
22501 | @code{GL_VERTEX_SHADER}, an executable will be installed on the fragment | |
22502 | processor, but fixed functionality will be used for vertex processing. | |
22503 | If @var{program} is 0, the programmable processors will be disabled, and | |
22504 | fixed functionality will be used for both vertex and fragment | |
22505 | processing. | |
22506 | ||
8925f36f AW |
22507 | @code{GL_INVALID_VALUE} is generated if @var{program} is neither 0 nor a |
22508 | value generated by OpenGL. | |
22509 | ||
22510 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
22511 | program object. | |
22512 | ||
22513 | @code{GL_INVALID_OPERATION} is generated if @var{program} could not be | |
22514 | made part of current state. | |
22515 | ||
22516 | @code{GL_INVALID_OPERATION} is generated if @code{glUseProgram} is | |
22517 | executed between the execution of @code{glBegin} and the corresponding | |
22518 | execution of @code{glEnd}. | |
22519 | ||
bb894c9d | 22520 | @end deftypefun |
8925f36f | 22521 | |
bb894c9d | 22522 | @deftypefun void glValidateProgram program |
3c9b6116 AW |
22523 | Validates a program object. |
22524 | ||
8925f36f AW |
22525 | @table @asis |
22526 | @item @var{program} | |
22527 | Specifies the handle of the program object to be validated. | |
22528 | ||
22529 | @end table | |
22530 | ||
8925f36f | 22531 | @code{glValidateProgram} checks to see whether the executables contained |
c7b31271 | 22532 | in @var{program} can execute given the current OpenGL state. The |
8925f36f | 22533 | information generated by the validation process will be stored in |
c7b31271 | 22534 | @var{program}'s information log. The validation information may consist |
8925f36f AW |
22535 | of an empty string, or it may be a string containing information about |
22536 | how the current program object interacts with the rest of current OpenGL | |
c7b31271 | 22537 | state. This provides a way for OpenGL implementers to convey more |
8925f36f AW |
22538 | information about why the current program is inefficient, suboptimal, |
22539 | failing to execute, and so on. | |
22540 | ||
22541 | The status of the validation operation will be stored as part of the | |
c7b31271 DH |
22542 | program object's state. This value will be set to @code{GL_TRUE} if the |
22543 | validation succeeded, and @code{GL_FALSE} otherwise. It can be queried | |
8925f36f | 22544 | by calling @code{glGetProgram} with arguments @var{program} and |
c7b31271 DH |
22545 | @code{GL_VALIDATE_STATUS}. If validation is successful, @var{program} |
22546 | is guaranteed to execute given the current state. Otherwise, | |
22547 | @var{program} is guaranteed to not execute. | |
8925f36f AW |
22548 | |
22549 | This function is typically useful only during application development. | |
22550 | The informational string stored in the information log is completely | |
22551 | implementation dependent; therefore, an application should not expect | |
22552 | different OpenGL implementations to produce identical information | |
22553 | strings. | |
22554 | ||
8925f36f AW |
22555 | @code{GL_INVALID_VALUE} is generated if @var{program} is not a value |
22556 | generated by OpenGL. | |
22557 | ||
22558 | @code{GL_INVALID_OPERATION} is generated if @var{program} is not a | |
22559 | program object. | |
22560 | ||
22561 | @code{GL_INVALID_OPERATION} is generated if @code{glValidateProgram} is | |
22562 | executed between the execution of @code{glBegin} and the corresponding | |
22563 | execution of @code{glEnd}. | |
22564 | ||
bb894c9d | 22565 | @end deftypefun |
8925f36f | 22566 | |
bb894c9d | 22567 | @deftypefun void glVertexAttribPointer index size type normalized stride pointer |
3c9b6116 AW |
22568 | Define an array of generic vertex attribute data. |
22569 | ||
8925f36f AW |
22570 | @table @asis |
22571 | @item @var{index} | |
22572 | Specifies the index of the generic vertex attribute to be modified. | |
22573 | ||
22574 | @item @var{size} | |
c7b31271 DH |
22575 | Specifies the number of components per generic vertex attribute. Must |
22576 | be 1, 2, 3, or 4. The initial value is 4. | |
8925f36f AW |
22577 | |
22578 | @item @var{type} | |
c7b31271 | 22579 | Specifies the data type of each component in the array. Symbolic |
8925f36f AW |
22580 | constants @code{GL_BYTE}, @code{GL_UNSIGNED_BYTE}, @code{GL_SHORT}, |
22581 | @code{GL_UNSIGNED_SHORT}, @code{GL_INT}, @code{GL_UNSIGNED_INT}, | |
c7b31271 | 22582 | @code{GL_FLOAT}, or @code{GL_DOUBLE} are accepted. The initial value is |
8925f36f AW |
22583 | @code{GL_FLOAT}. |
22584 | ||
22585 | @item @var{normalized} | |
22586 | Specifies whether fixed-point data values should be normalized | |
22587 | (@code{GL_TRUE}) or converted directly as fixed-point values | |
22588 | (@code{GL_FALSE}) when they are accessed. | |
22589 | ||
22590 | @item @var{stride} | |
22591 | Specifies the byte offset between consecutive generic vertex attributes. | |
22592 | If @var{stride} is 0, the generic vertex attributes are understood to be | |
c7b31271 | 22593 | tightly packed in the array. The initial value is 0. |
8925f36f AW |
22594 | |
22595 | @item @var{pointer} | |
22596 | Specifies a pointer to the first component of the first generic vertex | |
c7b31271 | 22597 | attribute in the array. The initial value is 0. |
8925f36f AW |
22598 | |
22599 | @end table | |
22600 | ||
8925f36f AW |
22601 | @code{glVertexAttribPointer} specifies the location and data format of |
22602 | the array of generic vertex attributes at index @var{index} to use when | |
c7b31271 DH |
22603 | rendering. @var{size} specifies the number of components per attribute |
22604 | and must be 1, 2, 3, or 4. @var{type} specifies the data type of each | |
8925f36f AW |
22605 | component, and @var{stride} specifies the byte stride from one attribute |
22606 | to the next, allowing vertices and attributes to be packed into a single | |
c7b31271 | 22607 | array or stored in separate arrays. If set to @code{GL_TRUE}, |
8925f36f AW |
22608 | @var{normalized} indicates that values stored in an integer format are |
22609 | to be mapped to the range [-1,1] (for signed values) or [0,1] (for | |
22610 | unsigned values) when they are accessed and converted to floating point. | |
22611 | Otherwise, values will be converted to floats directly without | |
22612 | normalization. | |
22613 | ||
22614 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
22615 | target (see @code{glBindBuffer}) while a generic vertex attribute array | |
22616 | is specified, @var{pointer} is treated as a byte offset into the buffer | |
c7b31271 | 22617 | object's data store. Also, the buffer object binding |
8925f36f AW |
22618 | (@code{GL_ARRAY_BUFFER_BINDING}) is saved as generic vertex attribute |
22619 | array client-side state (@code{GL_VERTEX_ATTRIB_ARRAY_BUFFER_BINDING}) | |
22620 | for index @var{index}. | |
22621 | ||
22622 | When a generic vertex attribute array is specified, @var{size}, | |
22623 | @var{type}, @var{normalized}, @var{stride}, and @var{pointer} are saved | |
22624 | as client-side state, in addition to the current vertex array buffer | |
22625 | object binding. | |
22626 | ||
22627 | To enable and disable a generic vertex attribute array, call | |
22628 | @code{glEnableVertexAttribArray} and @code{glDisableVertexAttribArray} | |
c7b31271 DH |
22629 | with @var{index}. If enabled, the generic vertex attribute array is |
22630 | used when @code{glArrayElement}, @code{glDrawArrays}, | |
8925f36f AW |
22631 | @code{glMultiDrawArrays}, @code{glDrawElements}, |
22632 | @code{glMultiDrawElements}, or @code{glDrawRangeElements} is called. | |
22633 | ||
8925f36f AW |
22634 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or |
22635 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
22636 | ||
22637 | @code{GL_INVALID_VALUE} is generated if @var{size} is not 1, 2, 3, or 4. | |
22638 | ||
22639 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted | |
22640 | value. | |
22641 | ||
22642 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
22643 | ||
bb894c9d AW |
22644 | @end deftypefun |
22645 | ||
ca09631c AW |
22646 | @deftypefun void glVertexAttrib1f index v0 |
22647 | @deftypefunx void glVertexAttrib1s index v0 | |
d172eed9 | 22648 | @deftypefunx void glVertexAttrib1d index v0 |
ca09631c | 22649 | @deftypefunx void glVertexAttrib2f index v0 v1 |
bb894c9d | 22650 | @deftypefunx void glVertexAttrib2s index v0 v1 |
d172eed9 | 22651 | @deftypefunx void glVertexAttrib2d index v0 v1 |
ca09631c | 22652 | @deftypefunx void glVertexAttrib3f index v0 v1 v2 |
bb894c9d | 22653 | @deftypefunx void glVertexAttrib3s index v0 v1 v2 |
d172eed9 | 22654 | @deftypefunx void glVertexAttrib3d index v0 v1 v2 |
ca09631c | 22655 | @deftypefunx void glVertexAttrib4f index v0 v1 v2 v3 |
bb894c9d | 22656 | @deftypefunx void glVertexAttrib4s index v0 v1 v2 v3 |
d172eed9 | 22657 | @deftypefunx void glVertexAttrib4d index v0 v1 v2 v3 |
bb894c9d | 22658 | @deftypefunx void glVertexAttrib4Nub index v0 v1 v2 v3 |
d172eed9 AW |
22659 | @deftypefunx void glVertexAttrib1fv index v |
22660 | @deftypefunx void glVertexAttrib1sv index v | |
22661 | @deftypefunx void glVertexAttrib1dv index v | |
22662 | @deftypefunx void glVertexAttrib2fv index v | |
22663 | @deftypefunx void glVertexAttrib2sv index v | |
22664 | @deftypefunx void glVertexAttrib2dv index v | |
22665 | @deftypefunx void glVertexAttrib3fv index v | |
22666 | @deftypefunx void glVertexAttrib3sv index v | |
22667 | @deftypefunx void glVertexAttrib3dv index v | |
22668 | @deftypefunx void glVertexAttrib4fv index v | |
22669 | @deftypefunx void glVertexAttrib4sv index v | |
22670 | @deftypefunx void glVertexAttrib4dv index v | |
b002944d | 22671 | @deftypefunx void glVertexAttrib4iv index v |
d172eed9 AW |
22672 | @deftypefunx void glVertexAttrib4bv index v |
22673 | @deftypefunx void glVertexAttrib4ubv index v | |
22674 | @deftypefunx void glVertexAttrib4usv index v | |
b002944d | 22675 | @deftypefunx void glVertexAttrib4uiv index v |
d172eed9 AW |
22676 | @deftypefunx void glVertexAttrib4Nbv index v |
22677 | @deftypefunx void glVertexAttrib4Nsv index v | |
b002944d | 22678 | @deftypefunx void glVertexAttrib4Niv index v |
d172eed9 AW |
22679 | @deftypefunx void glVertexAttrib4Nubv index v |
22680 | @deftypefunx void glVertexAttrib4Nusv index v | |
b002944d | 22681 | @deftypefunx void glVertexAttrib4Nuiv index v |
3c9b6116 AW |
22682 | Specifies the value of a generic vertex attribute. |
22683 | ||
8925f36f AW |
22684 | @table @asis |
22685 | @item @var{index} | |
22686 | Specifies the index of the generic vertex attribute to be modified. | |
22687 | ||
22688 | @item @var{v0}, @var{v1}, @var{v2}, @var{v3} | |
22689 | Specifies the new values to be used for the specified vertex attribute. | |
22690 | ||
22691 | @end table | |
22692 | ||
8925f36f AW |
22693 | OpenGL defines a number of standard vertex attributes that applications |
22694 | can modify with standard API entry points (color, normal, texture | |
c7b31271 | 22695 | coordinates, etc.). The @code{glVertexAttrib} family of entry points |
8925f36f AW |
22696 | allows an application to pass generic vertex attributes in numbered |
22697 | locations. | |
22698 | ||
22699 | Generic attributes are defined as four-component values that are | |
c7b31271 | 22700 | organized into an array. The first entry of this array is numbered 0, |
8925f36f | 22701 | and the size of the array is specified by the implementation-dependent |
c7b31271 DH |
22702 | constant @code{GL_MAX_VERTEX_ATTRIBS}. Individual elements of this |
22703 | array can be modified with a @code{glVertexAttrib} call that specifies | |
22704 | the index of the element to be modified and a value for that element. | |
8925f36f AW |
22705 | |
22706 | These commands can be used to specify one, two, three, or all four | |
c7b31271 | 22707 | components of the generic vertex attribute specified by @var{index}. A |
8925f36f AW |
22708 | @code{1} in the name of the command indicates that only one value is |
22709 | passed, and it will be used to modify the first component of the generic | |
c7b31271 DH |
22710 | vertex attribute. The second and third components will be set to 0, and |
22711 | the fourth component will be set to 1. Similarly, a @code{2} in the | |
22712 | name of the command indicates that values are provided for the first two | |
8925f36f | 22713 | components, the third component will be set to 0, and the fourth |
c7b31271 | 22714 | component will be set to 1. A @code{3} in the name of the command |
8925f36f AW |
22715 | indicates that values are provided for the first three components and |
22716 | the fourth component will be set to 1, whereas a @code{4} in the name | |
22717 | indicates that values are provided for all four components. | |
22718 | ||
22719 | The letters @code{s}, @code{f}, @code{i}, @code{d}, @code{ub}, | |
22720 | @code{us}, and @code{ui} indicate whether the arguments are of type | |
22721 | short, float, int, double, unsigned byte, unsigned short, or unsigned | |
c7b31271 DH |
22722 | int. When @code{v} is appended to the name, the commands can take a |
22723 | pointer to an array of such values. The commands containing @code{N} | |
8925f36f AW |
22724 | indicate that the arguments will be passed as fixed-point values that |
22725 | are scaled to a normalized range according to the component conversion | |
c7b31271 | 22726 | rules defined by the OpenGL specification. Signed values are understood |
8925f36f AW |
22727 | to represent fixed-point values in the range [-1,1], and unsigned values |
22728 | are understood to represent fixed-point values in the range [0,1]. | |
22729 | ||
22730 | OpenGL Shading Language attribute variables are allowed to be of type | |
c7b31271 DH |
22731 | mat2, mat3, or mat4. Attributes of these types may be loaded using the |
22732 | @code{glVertexAttrib} entry points. Matrices must be loaded into | |
8925f36f AW |
22733 | successive generic attribute slots in column major order, with one |
22734 | column of the matrix in each generic attribute slot. | |
22735 | ||
22736 | A user-defined attribute variable declared in a vertex shader can be | |
22737 | bound to a generic attribute index by calling | |
c7b31271 DH |
22738 | @code{glBindAttribLocation}. This allows an application to use more |
22739 | descriptive variable names in a vertex shader. A subsequent change to | |
8925f36f AW |
22740 | the specified generic vertex attribute will be immediately reflected as |
22741 | a change to the corresponding attribute variable in the vertex shader. | |
22742 | ||
22743 | The binding between a generic vertex attribute index and a user-defined | |
22744 | attribute variable in a vertex shader is part of the state of a program | |
22745 | object, but the current value of the generic vertex attribute is not. | |
22746 | The value of each generic vertex attribute is part of current state, | |
22747 | just like standard vertex attributes, and it is maintained even if a | |
22748 | different program object is used. | |
22749 | ||
22750 | An application may freely modify generic vertex attributes that are not | |
c7b31271 | 22751 | bound to a named vertex shader attribute variable. These values are |
8925f36f | 22752 | simply maintained as part of current state and will not be accessed by |
c7b31271 | 22753 | the vertex shader. If a generic vertex attribute bound to an attribute |
8925f36f AW |
22754 | variable in a vertex shader is not updated while the vertex shader is |
22755 | executing, the vertex shader will repeatedly use the current value for | |
22756 | the generic vertex attribute. | |
22757 | ||
22758 | The generic vertex attribute with index 0 is the same as the vertex | |
c7b31271 | 22759 | position attribute previously defined by OpenGL. A @code{glVertex2}, |
8925f36f AW |
22760 | @code{glVertex3}, or @code{glVertex4} command is completely equivalent |
22761 | to the corresponding @code{glVertexAttrib} command with an index | |
c7b31271 DH |
22762 | argument of 0. A vertex shader can access generic vertex attribute 0 by |
22763 | using the built-in attribute variable @var{gl_Vertex}. There are no | |
22764 | current values for generic vertex attribute 0. This is the only generic | |
8925f36f AW |
22765 | vertex attribute with this property; calls to set other standard vertex |
22766 | attributes can be freely mixed with calls to set any of the other | |
22767 | generic vertex attributes. | |
22768 | ||
8925f36f AW |
22769 | @code{GL_INVALID_VALUE} is generated if @var{index} is greater than or |
22770 | equal to @code{GL_MAX_VERTEX_ATTRIBS}. | |
22771 | ||
bb894c9d | 22772 | @end deftypefun |
8925f36f | 22773 | |
bb894c9d | 22774 | @deftypefun void glVertexPointer size type stride pointer |
3c9b6116 AW |
22775 | Define an array of vertex data. |
22776 | ||
8925f36f AW |
22777 | @table @asis |
22778 | @item @var{size} | |
c7b31271 | 22779 | Specifies the number of coordinates per vertex. Must be 2, 3, or 4. The |
8925f36f AW |
22780 | initial value is 4. |
22781 | ||
22782 | @item @var{type} | |
c7b31271 | 22783 | Specifies the data type of each coordinate in the array. Symbolic |
8925f36f | 22784 | constants @code{GL_SHORT}, @code{GL_INT}, @code{GL_FLOAT}, or |
c7b31271 | 22785 | @code{GL_DOUBLE} are accepted. The initial value is @code{GL_FLOAT}. |
8925f36f AW |
22786 | |
22787 | @item @var{stride} | |
c7b31271 DH |
22788 | Specifies the byte offset between consecutive vertices. If @var{stride} |
22789 | is 0, the vertices are understood to be tightly packed in the array. The | |
8925f36f AW |
22790 | initial value is 0. |
22791 | ||
22792 | @item @var{pointer} | |
22793 | Specifies a pointer to the first coordinate of the first vertex in the | |
c7b31271 | 22794 | array. The initial value is 0. |
8925f36f AW |
22795 | |
22796 | @end table | |
22797 | ||
8925f36f | 22798 | @code{glVertexPointer} specifies the location and data format of an |
c7b31271 DH |
22799 | array of vertex coordinates to use when rendering. @var{size} specifies |
22800 | the number of coordinates per vertex, and must be 2, 3, or 4. @var{type} | |
8925f36f AW |
22801 | specifies the data type of each coordinate, and @var{stride} specifies |
22802 | the byte stride from one vertex to the next, allowing vertices and | |
22803 | attributes to be packed into a single array or stored in separate | |
c7b31271 | 22804 | arrays. (Single-array storage may be more efficient on some |
8925f36f AW |
22805 | implementations; see @code{glInterleavedArrays}.) |
22806 | ||
22807 | If a non-zero named buffer object is bound to the @code{GL_ARRAY_BUFFER} | |
22808 | target (see @code{glBindBuffer}) while a vertex array is specified, | |
22809 | @var{pointer} is treated as a byte offset into the buffer object's data | |
c7b31271 | 22810 | store. Also, the buffer object binding (@code{GL_ARRAY_BUFFER_BINDING}) |
8925f36f AW |
22811 | is saved as vertex array client-side state |
22812 | (@code{GL_VERTEX_ARRAY_BUFFER_BINDING}). | |
22813 | ||
22814 | When a vertex array is specified, @var{size}, @var{type}, @var{stride}, | |
22815 | and @var{pointer} are saved as client-side state, in addition to the | |
22816 | current vertex array buffer object binding. | |
22817 | ||
22818 | To enable and disable the vertex array, call @code{glEnableClientState} | |
22819 | and @code{glDisableClientState} with the argument | |
c7b31271 | 22820 | @code{GL_VERTEX_ARRAY}. If enabled, the vertex array is used when |
8925f36f AW |
22821 | @code{glArrayElement}, @code{glDrawArrays}, @code{glMultiDrawArrays}, |
22822 | @code{glDrawElements}, @code{glMultiDrawElements}, or | |
22823 | @code{glDrawRangeElements} is called. | |
22824 | ||
8925f36f AW |
22825 | @code{GL_INVALID_VALUE} is generated if @var{size} is not 2, 3, or 4. |
22826 | ||
22827 | @code{GL_INVALID_ENUM} is generated if @var{type} is not an accepted | |
22828 | value. | |
22829 | ||
22830 | @code{GL_INVALID_VALUE} is generated if @var{stride} is negative. | |
22831 | ||
bb894c9d | 22832 | @end deftypefun |
8925f36f | 22833 | |
d172eed9 AW |
22834 | @deftypefun void glVertex2s x y |
22835 | @deftypefunx void glVertex2i x y | |
ca09631c | 22836 | @deftypefunx void glVertex2f x y |
d172eed9 AW |
22837 | @deftypefunx void glVertex2d x y |
22838 | @deftypefunx void glVertex3s x y z | |
bb894c9d | 22839 | @deftypefunx void glVertex3i x y z |
ca09631c | 22840 | @deftypefunx void glVertex3f x y z |
d172eed9 AW |
22841 | @deftypefunx void glVertex3d x y z |
22842 | @deftypefunx void glVertex4s x y z w | |
bb894c9d | 22843 | @deftypefunx void glVertex4i x y z w |
ca09631c | 22844 | @deftypefunx void glVertex4f x y z w |
d172eed9 AW |
22845 | @deftypefunx void glVertex4d x y z w |
22846 | @deftypefunx void glVertex2sv v | |
22847 | @deftypefunx void glVertex2iv v | |
22848 | @deftypefunx void glVertex2fv v | |
22849 | @deftypefunx void glVertex2dv v | |
22850 | @deftypefunx void glVertex3sv v | |
22851 | @deftypefunx void glVertex3iv v | |
22852 | @deftypefunx void glVertex3fv v | |
22853 | @deftypefunx void glVertex3dv v | |
22854 | @deftypefunx void glVertex4sv v | |
22855 | @deftypefunx void glVertex4iv v | |
22856 | @deftypefunx void glVertex4fv v | |
22857 | @deftypefunx void glVertex4dv v | |
3c9b6116 AW |
22858 | Specify a vertex. |
22859 | ||
8925f36f AW |
22860 | @table @asis |
22861 | @item @var{x} | |
22862 | @itemx @var{y} | |
22863 | @itemx @var{z} | |
22864 | @itemx @var{w} | |
22865 | Specify @var{x}, @var{y}, @var{z}, and @var{w} coordinates of a vertex. | |
22866 | Not all parameters are present in all forms of the command. | |
22867 | ||
22868 | @end table | |
22869 | ||
8925f36f | 22870 | @code{glVertex} commands are used within @code{glBegin}/@code{glEnd} |
c7b31271 | 22871 | pairs to specify point, line, and polygon vertices. The current color, |
8925f36f AW |
22872 | normal, texture coordinates, and fog coordinate are associated with the |
22873 | vertex when @code{glVertex} is called. | |
22874 | ||
3c9b6116 | 22875 | When only @r{@var{x}} and @r{@var{y}} are specified, @r{@var{z}} |
c7b31271 | 22876 | defaults to 0 and @r{@var{w}} defaults to 1. When @r{@var{x}}, |
3c9b6116 | 22877 | @r{@var{y}}, and @r{@var{z}} are specified, @r{@var{w}} defaults to 1. |
8925f36f | 22878 | |
bb894c9d | 22879 | @end deftypefun |
8925f36f | 22880 | |
bb894c9d | 22881 | @deftypefun void glViewport x y width height |
3c9b6116 AW |
22882 | Set the viewport. |
22883 | ||
8925f36f AW |
22884 | @table @asis |
22885 | @item @var{x} | |
22886 | @itemx @var{y} | |
c7b31271 | 22887 | Specify the lower left corner of the viewport rectangle, in pixels. The |
8925f36f AW |
22888 | initial value is (0,0). |
22889 | ||
22890 | @item @var{width} | |
22891 | @itemx @var{height} | |
c7b31271 DH |
22892 | Specify the width and height of the viewport. When a GL context is |
22893 | first attached to a window, @var{width} and @var{height} are set to the | |
8925f36f AW |
22894 | dimensions of that window. |
22895 | ||
22896 | @end table | |
22897 | ||
3c9b6116 AW |
22898 | @code{glViewport} specifies the affine transformation of @r{@var{x}} and |
22899 | @r{@var{y}} from normalized device coordinates to window coordinates. | |
22900 | Let @r{(@var{x}_@var{nd},@var{y}_@var{nd})} be normalized device | |
c7b31271 | 22901 | coordinates. Then the window coordinates |
3c9b6116 | 22902 | @r{(@var{x}_@var{w},@var{y}_@var{w})} are computed as follows: |
8925f36f | 22903 | |
3c9b6116 | 22904 | @r{@var{x}_@var{w}=(@var{x}_@var{nd}+1,)(@var{width}/2,)+@var{x}} |
8925f36f | 22905 | |
3c9b6116 | 22906 | @r{@var{y}_@var{w}=(@var{y}_@var{nd}+1,)(@var{height}/2,)+@var{y}} |
8925f36f AW |
22907 | |
22908 | Viewport width and height are silently clamped to a range that depends | |
c7b31271 | 22909 | on the implementation. To query this range, call @code{glGet} with |
8925f36f AW |
22910 | argument @code{GL_MAX_VIEWPORT_DIMS}. |
22911 | ||
8925f36f AW |
22912 | @code{GL_INVALID_VALUE} is generated if either @var{width} or |
22913 | @var{height} is negative. | |
22914 | ||
22915 | @code{GL_INVALID_OPERATION} is generated if @code{glViewport} is | |
22916 | executed between the execution of @code{glBegin} and the corresponding | |
22917 | execution of @code{glEnd}. | |
22918 | ||
bb894c9d | 22919 | @end deftypefun |
8925f36f | 22920 | |
d172eed9 AW |
22921 | @deftypefun void glWindowPos2s x y |
22922 | @deftypefunx void glWindowPos2i x y | |
ca09631c | 22923 | @deftypefunx void glWindowPos2f x y |
d172eed9 AW |
22924 | @deftypefunx void glWindowPos2d x y |
22925 | @deftypefunx void glWindowPos3s x y z | |
bb894c9d | 22926 | @deftypefunx void glWindowPos3i x y z |
ca09631c | 22927 | @deftypefunx void glWindowPos3f x y z |
d172eed9 AW |
22928 | @deftypefunx void glWindowPos3d x y z |
22929 | @deftypefunx void glWindowPos2sv v | |
22930 | @deftypefunx void glWindowPos2iv v | |
22931 | @deftypefunx void glWindowPos2fv v | |
22932 | @deftypefunx void glWindowPos2dv v | |
22933 | @deftypefunx void glWindowPos3sv v | |
22934 | @deftypefunx void glWindowPos3iv v | |
22935 | @deftypefunx void glWindowPos3fv v | |
22936 | @deftypefunx void glWindowPos3dv v | |
3c9b6116 AW |
22937 | Specify the raster position in window coordinates for pixel operations. |
22938 | ||
8925f36f AW |
22939 | @table @asis |
22940 | @item @var{x} | |
22941 | @itemx @var{y} | |
22942 | @itemx @var{z} | |
3c9b6116 AW |
22943 | Specify the @r{@var{x}}, @r{@var{y}}, @r{@var{z}} coordinates for the |
22944 | raster position. | |
8925f36f AW |
22945 | |
22946 | @end table | |
22947 | ||
c7b31271 | 22948 | The GL maintains a 3D position in window coordinates. This position, |
8925f36f | 22949 | called the raster position, is used to position pixel and bitmap write |
c7b31271 | 22950 | operations. It is maintained with subpixel accuracy. See |
8925f36f AW |
22951 | @code{glBitmap}, @code{glDrawPixels}, and @code{glCopyPixels}. |
22952 | ||
3c9b6116 AW |
22953 | @code{glWindowPos2} specifies the @r{@var{x}} and @r{@var{y}} |
22954 | coordinates, while @r{@var{z}} is implicitly set to 0. | |
c7b31271 | 22955 | @code{glWindowPos3} specifies all three coordinates. The @r{@var{w}} |
8925f36f AW |
22956 | coordinate of the current raster position is always set to 1.0. |
22957 | ||
3c9b6116 AW |
22958 | @code{glWindowPos} directly updates the @r{@var{x}} and @r{@var{y}} |
22959 | coordinates of the current raster position with the values specified. | |
22960 | That is, the values are neither transformed by the current modelview and | |
c7b31271 | 22961 | projection matrices, nor by the viewport-to-window transform. The |
3c9b6116 AW |
22962 | @r{@var{z}} coordinate of the current raster position is updated in the |
22963 | following manner: | |
8925f36f | 22964 | |
3c9b6116 | 22965 | @r{@var{z}=@{(@var{n}), (@var{f}), |
8925f36f AW |
22966 | (@var{n}+@var{z}×(@var{f}-@var{n},),)(@var{if}@var{z}<=0), |
22967 | (@var{if}@var{z}>=1), (@code{otherwise},),} | |
22968 | ||
22969 | ||
22970 | ||
3c9b6116 | 22971 | where @r{@var{n}} is @code{GL_DEPTH_RANGE}'s near value, and @r{@var{f}} |
c7b31271 | 22972 | is @code{GL_DEPTH_RANGE}'s far value. See @code{glDepthRange}. |
8925f36f AW |
22973 | |
22974 | The specified coordinates are not clip-tested, causing the raster | |
22975 | position to always be valid. | |
22976 | ||
22977 | The current raster position also includes some associated color data and | |
c7b31271 | 22978 | texture coordinates. If lighting is enabled, then |
8925f36f AW |
22979 | @code{GL_CURRENT_RASTER_COLOR} (in RGBA mode) or |
22980 | @code{GL_CURRENT_RASTER_INDEX} (in color index mode) is set to the color | |
22981 | produced by the lighting calculation (see @code{glLight}, | |
c7b31271 | 22982 | @code{glLightModel}, and @code{glShadeModel}). If lighting is disabled, |
8925f36f AW |
22983 | current color (in RGBA mode, state variable @code{GL_CURRENT_COLOR}) or |
22984 | color index (in color index mode, state variable | |
22985 | @code{GL_CURRENT_INDEX}) is used to update the current raster color. | |
22986 | @code{GL_CURRENT_RASTER_SECONDARY_COLOR} (in RGBA mode) is likewise | |
22987 | updated. | |
22988 | ||
22989 | Likewise, @code{GL_CURRENT_RASTER_TEXTURE_COORDS} is updated as a | |
22990 | function of @code{GL_CURRENT_TEXTURE_COORDS}, based on the texture | |
c7b31271 | 22991 | matrix and the texture generation functions (see @code{glTexGen}). The |
8925f36f AW |
22992 | @code{GL_CURRENT_RASTER_DISTANCE} is set to the |
22993 | @code{GL_CURRENT_FOG_COORD}. | |
22994 | ||
22995 | ||
22996 | ||
8925f36f AW |
22997 | @code{GL_INVALID_OPERATION} is generated if @code{glWindowPos} is |
22998 | executed between the execution of @code{glBegin} and the corresponding | |
22999 | execution of @code{glEnd}. | |
23000 | ||
bb894c9d | 23001 | @end deftypefun |
8925f36f AW |
23002 | |
23003 | ||
23004 | @c %end of fragment |